// --------------------------------------------------------------------------

// ==========================================================================
//
// File:          TDx_DrawSurface.CPP
// Created:       12th February 2009
// Author:        BCB_Code_Generator v2.10,
//                Darren John Dwyer 
//                    (
//                    data entry, 
//                    source code,
//                    documentation,
//                    help files,
//                    project files,
//                    tutorials,
//                    demos, 
//                    website
//                    )
//                
//                Hugh Dunbar Edwards 
//                    (
//                    data entry creation, 
//                    documentation creation, 
//                    icon creation
//                    )
//
// Description:   This file contains the code for the TDx_DrawSurface 
//                Component 
//
// "TDx_Library v1.90"
// "TDx_Draw_Library v1.90"
//
// (c) 2009 Darren John Dwyer, Australia.
// All Rights Reserved.
//
// Refer to the 'License.Txt' file for licencing & copyright information.
// ==========================================================================

// --------------------------------------------------------------------------
// #includes ...
// --------------------------------------------------------------------------
#include <vcl\vcl.h>
#pragma hdrstop
// --------------------------------------------------------------------------
#include "TDx_DrawSurface.H"
// --------------------------------------------------------------------------
// external classes used by the TDx_DrawSurface component.
#include "TDx_Draw.H"
#include "TDDSurfaceDesc.H"
// --------------------------------------------------------------------------
// external classes used by TDx_DrawSurface methods.
#include "TDx_DrawSurface.H"
#include "TDDBltFX.H"
#include "TDDSCaps.H"
#include "TDx_DrawClipper.H"
#include "TDDColorKey.H"
#include "TDx_DrawPalette.H"
#include "TDDPixelFormat.H"
#include "TDDOverlayFX.H"
// --------------------------------------------------------------------------
#pragma link "TDx_Library_Defns"
#pragma link "TDx_Library_Functions"
#pragma link "TDx_Draw_Library_Defns"
#pragma link "TDx_Draw_Library_Functions"

// --------------------------------------------------------------------------
// Object Registration...
// --------------------------------------------------------------------------
#if (__BORLANDC__ >= 0x0530) // BCB Version 3+
    #pragma package(smart_init)
#endif
// --------------------------------------------------------------------------
static inline void ValidCtrCheck(TDx_DrawSurface*)
{
    new TDx_DrawSurface(NULL);
}
// --------------------------------------------------------------------------
namespace Tdx_drawsurface
{
    #if (__BORLANDC__ >= 0x0530) // BCB Version 3+
    void __fastcall PACKAGE Register()
    #else
    void __fastcall Register()
    #endif
    {
        TComponentClass classes[1] = {__classid(TDx_DrawSurface)};
        RegisterComponents("TDx_Draw", classes, 0);
    }
}

// --------------------------------------------------------------------------
// Extra code for Callback Handling
// --------------------------------------------------------------------------
TDx_DrawSurface* TDx_DrawSurface_OnEnumAttachedSurfacesOwner = NULL;
TDx_DrawSurface* TDx_DrawSurface_OnEnumOverlayZOrdersOwner = NULL;

// --------------------------------------------------------------------------
// Constructor: TDx_DrawSurface::TDx_DrawSurface()
// Description: The default constructor for the TDx_DrawSurface (Interface) object.
// --------------------------------------------------------------------------
__fastcall TDx_DrawSurface::TDx_DrawSurface(TComponent* Owner)
    : TComponent(Owner)
{
fCreated = false;
fErrorValue = DD_OK;
}
// --------------------------------------------------------------------------
// Destructor:  TDx_DrawSurface::~TDx_DrawSurface()
// Description: The destructor for the TDx_DrawSurface(Interface) object.
// --------------------------------------------------------------------------
__fastcall TDx_DrawSurface::~TDx_DrawSurface()
{
// destroy internals
if (Created) Destroy();
}
// --------------------------------------------------------------------------
// Property:    Created
// Description: The Created property is true if the internal 
//              LPDIRECTDRAWSURFACE7 used in this component has been 
//              successfully created, otherwise Created is false. 
//              
//              To create the internal LPDIRECTDRAWSURFACE7, call the 
//              TDx_DrawSurface::Create() method. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::FGetCreated()
{
return fCreated;
}
// --------------------------------------------------------------------------
void __fastcall TDx_DrawSurface::FSetCreated( bool pCreated )
{
fCreated = (pCreated && (fLPDIRECTDRAWSURFACE7==NULL));
}
// --------------------------------------------------------------------------
// Property:    ErrorValue
// Description: The ErrorValue property contains the last error value 
//              returned from a call to a TDx_DrawSurface method or 
//              fget/fset. eg. DD_OK or DDERR_SURFACELOST or TDX_ERROR 
// --------------------------------------------------------------------------
HRESULT __fastcall TDx_DrawSurface::FGetErrorValue()
{
return fErrorValue;
}
// --------------------------------------------------------------------------
void __fastcall TDx_DrawSurface::FSetErrorValue( HRESULT pErrorValue )
{
fErrorValue = pErrorValue;
}
// --------------------------------------------------------------------------
// Method:      AddAttachedSurface()
// Description: The TDx_DrawSurface::AddAttachedSurface method is used for 
//              explicitly attaching the specified z-buffer, alpha channel or 
//              back buffer. 
//              
//              This method will increment the reference count of the 
//              surface, the attachment can be broken and the reference count 
//              decremented using TDx_DrawSurface::DeleteAttachedSurface(). 
//              Surfaces attached using this method are not automatically 
//              released, it is the responsibility of the application to do 
//              so. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_CANNOTATTACHSURFACE 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_SURFACEALREADYATTACHED 
//              DDERR_SURFACELOST 
//              DDERR_WASSTILLDRAWING 
// Params:      pAttachedSurface - 
//                The AttachedSurface parameter references the surface that is 
//                to be attached. 
//                
//                The possible attachments that can be made include z-buffers, 
//                alpha channels and back buffers, subject to certain rules. 
//                Some attachments are exclusive and will break other 
//                attachments. For example, a 3D z-buffer may be attached to 
//                one back buffer at a time, thus attaching it to another 
//                surface may cause the original attachment to be broken. 
//                
//                You cannot attach a surface to itself and attachments are not 
//                bidirectional. 
//                System memory surfaces cannot be attached to video memory 
//                surfaces and the surfaces being attached must be the same 
//                size unless one is a texture map. 
//                
//                Flipping surfaces of the same type may not be attached, 
//                although flipping surfaces of differing types can be 
//                attached. For example, a flipping alpha surface may be 
//                attached to a flipping normal surface. 
//                Attaching two nonflipping surfaces of the same type creates a 
//                flip chain, attaching a nonflipping surface to a flipping 
//                surface will add it to the existing flip chain. 
//                
//                Each call to TDx_DrawSurface::Flip() will advance one step 
//                through the flip chain in the order the surfaces were 
//                attached. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::AddAttachedSurface( TDx_DrawSurface* pAttachedSurface )
{
// Original Function Definition
// HRESULT AddAttachedSurface( 
//   LPDIRECTDRAWSURFACE7 lpDDSAttachedSurface   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::AddAttachedSurface()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pAttachedSurface==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::AddAttachedSurface()", "TDX_BADPARAMS", "'pAttachedSurface' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->AddAttachedSurface( pAttachedSurface->Internal_LPDIRECTDRAWSURFACE7 );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::AddAttachedSurface()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      Blt()
// Description: The TDx_DrawSurface::Blt method will perform a bit block 
//              transfer. 
//              
//              Z-buffering or alpha blending during blit operations is not 
//              yet supported. 
//              
//              This method performs asynchronous blits by default, specify 
//              DDBLT_WAIT to request a synchronous blit. 
//              
//              Blits can be performed using source and/or destination color 
//              keys and arbitrary shrinking or stretching will be performed 
//              if the source and destination rectangles are of differing 
//              sizes. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDCLIPLIST 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDRECT 
//              DDERR_NOALPHAHW 
//              DDERR_NOBLTHW 
//              DDERR_NOCLIPLIST 
//              DDERR_NODDROPSHW 
//              DDERR_NOMIRRORHW 
//              DDERR_NORASTEROPHW 
//              DDERR_NOROTATIONHW 
//              DDERR_NOSTRETCHHW 
//              DDERR_NOZBUFFERHW 
//              DDERR_SURFACEBUSY 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
//              DDERR_WASSTILLDRAWING 
// Params:      pDestRect - 
//                The DestRect parameter references a TRect defining the target 
//                of the blit on the destination surface. 
//                Set this parameter to NULL to blit to the entire destination 
//                surface. 
//                
//                This parameter is defined so that the right and bottom 
//                members are exclusive. Thus the right value minus the left 
//                value will equal the width, not one less than the width. 
//              pSrcSurface - 
//                The SrcSurface parameter references the surface that is to be 
//                the source for the blit. 
//              pSrcRect - 
//                The SrcRect parameter references a TRect defining the source 
//                rectangle of the blit. 
//                Set this parameter to NULL to blit from the entire source 
//                surface. 
//                
//                This parameter is defined so that the right and bottom 
//                members are exclusive. Thus the right value minus the left 
//                value will equal the width, not one less than the width. 
//              pFlags - 
//                The Flags parameter defines flags indicating what effect 
//                information the blit is to use and from where that 
//                information is to be retrieved.   
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDBLT_ASYNC -
//                    The blit will be performed asynchronously through the 
//                    FIFO hardware. 
//                    When the FIFO hardware is already full the blit will 
//                    fail. 
//                  DDBLT_COLORFILL -
//                    The blit will use the TDDBltFX::FillColor referenced by 
//                    the BltFX parameter of this method as the color that 
//                    fills the destination rectangle before the blit occurs. 
//                  DDBLT_DDFX -
//                    The blit will use the TDDBltFX::FX referenced by the 
//                    BltFX parameter of this method to specify the blit 
//                    effects used. 
//                  DDBLT_DDROPS -
//                    The blit will use the TDDBltFX::DDRops referenced by 
//                    the BltFX parameter of this method to specify non 
//                    standard raster operations. 
//                  DDBLT_DEPTHFILL -
//                    The blit will use the TDDBltFX::FillDepth referenced by 
//                    the BltFX parameter of this method as the depth value 
//                    that fills the destination rectangle of the z-buffer 
//                    surface before the blit occurs. 
//                  DDBLT_KEYDEST -
//                    The blit will use the destination surface color key for 
//                    transparency. 
//                  DDBLT_KEYDESTOVERRIDE -
//                    The blit will use the TDDBltFX::DestColorKey referenced 
//                    by the BltFX parameter of this method as the 
//                    destination color key. 
//                  DDBLT_KEYSRC -
//                    The blit will use the source surface color key for 
//                    transparency effects. 
//                  DDBLT_KEYSRCOVERRIDE -
//                    The blit will use the TDDBltFX::SrcColorKey referenced 
//                    by the BltFX parameter of this method as the source 
//                    color key. 
//                  DDBLT_ROP -
//                    The blit will use the TDDBltFX::ROP referenced by the 
//                    BltFX parameter of this method to define its standard 
//                    raster operation. 
//                    The possible ROP's are detailed in the Win32 API. 
//                  DDBLT_ROTATIONANGLE -
//                    The blit will use the TDDBltFX::RotationAngle 
//                    referenced by the BltFX parameteer of this method is to 
//                    be used as the amount of rotation, in 1/100ths of a 
//                    degree, applied to the blit. 
//                  DDBLT_WAIT -
//                    The blit will wait for the blitter to accept the 
//                    command  unless an error other than 
//                    DDERR_WASSTILLDRAWING occurs. 
//              pBltFx - 
//                The BltFx parameter references a TDDBltFX component holding 
//                the settings that are to be used when blitting if the 
//                corresponding flags are set within the Flags parameter of 
//                this method. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::Blt( TRect* pDestRect, TDx_DrawSurface* pSrcSurface, TRect* pSrcRect, dword pFlags, TDDBltFX* pBltFx )
{
// Original Function Definition
// HRESULT Blt( 
//   LPRECT lpDestRect,                     
//   LPDIRECTDRAWSURFACE7 lpDDSrcSurface,   
//   LPRECT lpSrcRect,                     
//   DWORD dwFlags,                         
//   LPDDBLTFX lpDDBltFx                   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::Blt()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Translate Parameters before calling Original Function
RECT TempDestRect;
LPRECT TempDestRect_Ptr;
if (pDestRect==NULL)
    {
    TempDestRect_Ptr = NULL;
    }
 else
    {
    TempDestRect.top = pDestRect->Top;
    TempDestRect.left = pDestRect->Left;
    TempDestRect.right = pDestRect->Right;
    TempDestRect.bottom = pDestRect->Bottom;
    TempDestRect_Ptr = &TempDestRect;
    }
RECT TempSrcRect;
LPRECT TempSrcRect_Ptr;
if (pSrcRect==NULL)
    {
    TempSrcRect_Ptr = NULL;
    }
 else
    {
    TempSrcRect.top = pSrcRect->Top;
    TempSrcRect.left = pSrcRect->Left;
    TempSrcRect.right = pSrcRect->Right;
    TempSrcRect.bottom = pSrcRect->Bottom;
    TempSrcRect_Ptr = &TempSrcRect;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->Blt( TempDestRect_Ptr, (pSrcSurface==NULL) ? NULL : pSrcSurface->Internal_LPDIRECTDRAWSURFACE7, TempSrcRect_Ptr, (DWORD) pFlags, (pBltFx==NULL) ? NULL : pBltFx->Internal_DDBLTFX_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
if (pBltFx!=NULL) pBltFx->Internal_DDBLTFX_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::Blt()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      BltFast()
// Description: The TDx_DrawSurface::BltFast method can perform source copy 
//              or color keyed blits. 
//              
//              The blit will always be unclipped and only works for display 
//              memory surfaces. A 10% speed benefit is gained by using this 
//              method but only when there is no hardware blitter. 
//              An asychronous blit will be attempted if supported by the 
//              hardware, with the method returning immediately unless 
//              DDBLTFAST_WAIT is specified. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_EXCEPTION 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDRECT 
//              DDERR_NOBLTHW 
//              DDERR_SURFACEBUSY 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
//              DDERR_WASSTILLDRAWING 
// Params:      pX - 
//                The X parameter defines the destination surface X coordinate 
//                for the blit. 
//              pY - 
//                The Y parameter defines the destination surface Y coordinate 
//                for the blit. 
//              pSrcSurface - 
//                The SrcSurface parameter references the source surface to be 
//                blitted from. 
//              pSrcRect - 
//                The SrcRect parameter references a TRect defining the source 
//                rectangle to be blitted from. 
//                Set this parameter to NULL to blit from the whole source 
//                surface. 
//              pTrans - 
//                The Trans parameter defines flags indicating the type of blit 
//                to be performed. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDBLTFAST_DESTCOLORKEY -
//                    The blit is to be performed using the destination color 
//                    key. 
//                  DDBLTFAST_NOCOLORKEY -
//                    The blit is a normal copy blit. 
//                  DDBLTFAST_SRCCOLORKEY -
//                    The blit is to be performed using the source color key. 
//                  DDBLTFAST_WAIT -
//                    The blit will wait until it can be set up or an error 
//                    other than DDERR_WASSTILLDRAWING occurs. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::BltFast( dword pX, dword pY, TDx_DrawSurface* pSrcSurface, TRect* pSrcRect, dword pTrans )
{
// Original Function Definition
// HRESULT BltFast( 
//   DWORD dwX,                             
//   DWORD dwY,                             
//   LPDIRECTDRAWSURFACE7 lpDDSrcSurface,   
//   LPRECT lpSrcRect,                     
//   DWORD dwTrans                         
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::BltFast()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Translate Parameters before calling Original Function
RECT TempSrcRect;
LPRECT TempSrcRect_Ptr;
if (pSrcRect==NULL)
    {
    TempSrcRect_Ptr = NULL;
    }
 else
    {
    TempSrcRect.top = pSrcRect->Top;
    TempSrcRect.left = pSrcRect->Left;
    TempSrcRect.right = pSrcRect->Right;
    TempSrcRect.bottom = pSrcRect->Bottom;
    TempSrcRect_Ptr = &TempSrcRect;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->BltFast( (DWORD) pX, (DWORD) pY, (pSrcSurface==NULL) ? NULL : pSrcSurface->Internal_LPDIRECTDRAWSURFACE7, TempSrcRect_Ptr, (DWORD) pTrans );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::BltFast()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      ChangeUniquenessValue()
// Description: The TDx_DrawSurface::ChangeUniquenessValue method will 
//              manually update the surface's uniqueness value. 
//              
//              The uniqueness value is usually updated whenever the surface 
//              contents change. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_EXCEPTION 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::ChangeUniquenessValue()
{
// Original Function Definition
// HRESULT ChangeUniquenessValue(); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::ChangeUniquenessValue()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->ChangeUniquenessValue(  );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::ChangeUniquenessValue()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      Create()
// Description: The Create() method is used to automatically create the 
//              internal LPDIRECTDRAWSURFACE7 interface used in the 
//              TDx_DrawSurface component and must be called before any 
//              methods of the TDx_DrawSurface component will function. 
// Params:      pSurfaceDesc - 
//                The SurfaceDesc parameter describes the requested surface. 
//              pDraw - 
//                A TDx_Draw object that will manage the created surface. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::Create( TDDSurfaceDesc* pSurfaceDesc, TDx_Draw* pDraw )
{
// if the component internals have already been created, exit
if (fCreated)
    {
    fErrorValue = TDX_ALREADYCREATED;
    if (FOnError) FOnError( this, Name+"::Create()", "TDX_ALREADYCREATED", "The "+Name+"::Create() method was called when the component has already been created successfully." );
    return false;
    }

// check params for accuracy
if (pSurfaceDesc==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::Create()", "TDX_BADPARAMS", "The 'pSurfaceDesc' parameter must point to an existing TDDSurfaceDesc component and cannot be NULL." );
    return false;
    }
if (pDraw==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::Create()", "TDX_BADPARAMS", "The 'pDraw' parameter must point to an existing TDx_Draw component and cannot be NULL." );
    return false;
    }

// code that creates the internal interface
pDraw->CreateSurface( pSurfaceDesc, this );
fErrorValue = pDraw->ErrorValue;

// check for error result
if (fErrorValue!=DD_OK)
    {
    if (FOnError) FOnError( this, Name+"::Create()", "TDX_ERROR", Name+"::Create() failed with Error: "+TDx_Draw_Library_ErrorString(fErrorValue)+", "+TDx_Draw_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// successfully created
fCreated = true;
if (FOnCreate) FOnCreate(this);
return true;
}

// --------------------------------------------------------------------------
// Method:      CreateFromFile()
// Description: The CreateFromFile method is used to create the surface based 
//              on an image from an existing .BMP file. 
//              If the image file does not exist, nothing happens. 
//              If the image file exists, the surface is created or recreated 
//              using the dimensions of the bitmap. 
//              Refer to TDx_DrawPalette::CreateFromFile() for info on how to 
//              load a bitmap's palette. 
//              
//              This method returns the following error values: 
//              TDX_ERROR 
//              TDX_BADPARAMS 
// Params:      pDraw - 
//                The Draw parameter must be a previously created TDx_Draw 
//                component 
//              pFileName - 
//                The FileName parameter specifies the name of a standard .BMP 
//                file that the image is to be loaded from and can include a 
//                directory path if required. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::CreateFromFile( TDx_Draw* pDraw, AnsiString pFileName )
{
// check parameters for accuracy
if (pDraw==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::CreateFromFile()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a NULL pDraw parameter." );
    return false;
    }
if (pFileName=="")
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::CreateFromFile()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a empty pFileName parameter." );
    return false;
    }

// check that the file exists
if (!FileExists(pFileName))
    {
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::CreateFromFile()", "TDX_ERROR", "The "+Name+" component is attempting to load from a non-existant bitmap file: "+pFileName );
    return false;
    }

// Allocate anything we need to use to load the bitmap data
Graphics::TBitmap* bitmap = new Graphics::TBitmap();
TDDSurfaceDesc* desc = new TDDSurfaceDesc(NULL);
TDDSCaps* scaps = new TDDSCaps(NULL);
if (bitmap==NULL || desc==NULL || scaps==NULL)
    {
    if (scaps) delete scaps;
    if (desc) delete desc;
    if (bitmap) delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError(this, Name+"::CreateFromFile()", "TDX_ERROR", "Could not allocate temporary buffers used to load the bitmap image: "+pFileName );
    return false;
    }

// load the bitmap from the file using TBitmap::LoadFromFile()
try {
    bitmap->LoadFromFile( pFileName );
    }
catch (...)
    {
    delete scaps;
    delete desc;
    delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError(this, Name+"::CreateFromFile()", "TDX_ERROR", "An unknown error occurred while attempting to read the data from bitmap file: "+pFileName );
    return false;
    }

// define the new surface
desc->Flags = DDSD_CAPS | DDSD_WIDTH | DDSD_HEIGHT;
desc->Width = bitmap->Width;
desc->Height = bitmap->Height;
desc->SCaps = scaps;
desc->SCaps->Caps = DDSCAPS_OFFSCREENPLAIN;

// if the surface is already created, destroy the surface
if (Created) Destroy();

// if we can create the new surface using above settings
if (Create(desc,pDraw))
    {
    // copy the image data from our temporary image to the surface
    HDC hdc;
    if (this->GetDC( &hdc ))
        {
        TCanvas* canvas = new TCanvas();
        if (canvas)
            {
            canvas->Handle = hdc;
            canvas->Draw( 0,0, bitmap );
            delete canvas;
            }
        else
            {
            // couldn't create canvas
            this->ReleaseDC( hdc );
            delete scaps;
            delete desc;
            delete bitmap;
            fErrorValue = TDX_ERROR;
            if (FOnError) FOnError( this, Name+"::CreateFromFile()", "TDX_ERROR", "Could not paint contents into offscreen buffer." );
            return false;
            }
        this->ReleaseDC( hdc );
        }
    else
        {
        // couldn't get DC :(
        delete scaps;
        delete desc;
        delete bitmap;
        fErrorValue = TDX_ERROR;
        if (FOnError) FOnError( this, Name+"::CreateFromFile()", "TDX_ERROR", "The surface may contain invalid data because it could not GetDC() to access surface data." );
        return false;
        }
    }
else
    {
    // couldn't create surface :(
    delete scaps;
    delete desc;
    delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::CreateFromFile()", "TDX_ERROR", "Could not create the surface using the settings in the bitmap file: '"+pFileName+"'" );
    return false;
    }

// clean-up
delete scaps;
delete desc;
delete bitmap;

// successful
return true;
}

// --------------------------------------------------------------------------
// Method:      CreateFromSurface()
// Description: The CreateFromSurface method is used to create the surface 
//              based on an existing surface. 
//              If the supplied surface exists, the current surface is 
//              created or recreated using the dimensions of the supplied 
//              surface. Refer to TDx_DrawPalette::CreateFromFile() for info 
//              on how to load a bitmap's palette. 
//              
//              This method returns the following error values: 
//              TDX_ERROR 
//              TDX_BADPARAMS 
// Params:      pDraw - 
//                The Draw parameter must be a previously created TDx_Draw 
//                component. 
//              pSurface - 
//                The Surface parameter must be a previously created 
//                TDx_DrawSurface component. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::CreateFromSurface( TDx_Draw* pDraw, TDx_DrawSurface* pSurface )
{
// check parameters for accuracy
if (pDraw==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::CreateFromSurface()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a NULL pDraw parameter." );
    return false;
    }
if (pSurface==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::CreateFromSurface()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a NULL pSurface parameter." );
    return false;
    }

// Allocate anything we need to use to load the bitmap data
TDDSurfaceDesc* srce_desc = new TDDSurfaceDesc(NULL);
TDDSurfaceDesc* dest_desc = new TDDSurfaceDesc(NULL);
TDDSCaps* scaps = new TDDSCaps(NULL);
if (scaps==NULL || dest_desc==NULL || srce_desc==NULL)
    {
    if (scaps) delete scaps;
    if (srce_desc) delete srce_desc;
    if (dest_desc) delete dest_desc;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError(this, Name+"::CreateFromSurface()", "TDX_ERROR", "Could not allocate temporary buffers used to create the surface: "+Name );
    return false;
    }

// retrieve the required surface characteristics
dest_desc->SCaps = scaps;
pSurface->GetSurfaceDesc( dest_desc );
pSurface->GetSurfaceDesc( srce_desc );

// if the surface is already created, destroy the surface
if (Created) Destroy();

// if we can create a surface same as the image
if (Create(dest_desc,pDraw))
    {
    // copy the image data from our temporary image to the surface
    HDC dest_hdc;
    HDC srce_hdc;
    bool dest_ok = this->GetDC( &dest_hdc );
    bool srce_ok = pSurface->GetDC( &srce_hdc );

    if (dest_ok && srce_ok)
        StretchBlt( dest_hdc, 0, 0, dest_desc->Width, dest_desc->Height,
                    srce_hdc, 0, 0, srce_desc->Width, srce_desc->Height,
                    SRCCOPY );

    if (srce_ok) pSurface->ReleaseDC( srce_hdc );
    if (dest_ok) this->ReleaseDC( dest_hdc );

    if (!dest_ok || !srce_ok)
        {
        delete scaps;
        delete srce_desc;
        delete dest_desc;
        fErrorValue = TDX_ERROR;
        if (FOnError) FOnError( this, Name+"::CreateFromFile()", "TDX_ERROR", "The surface may contain invalid data because it could not GetDC() to access surface data." );
        return false;
        }
    }
else
    {
    // couldn't create surface :(
    delete scaps;
    delete srce_desc;
    delete dest_desc;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::CreateFromSurface()", "TDX_ERROR", "Could not create the surface using the settings in the supplied surface: '"+pSurface->Name+"'" );
    return false;
    }

// clean-up
delete scaps;
delete srce_desc;
delete dest_desc;

// successful
return true;
}

// --------------------------------------------------------------------------
// Method:      DeleteAttachedSurface()
// Description: The TDx_DrawSurface::DeleteAttachedSurface method will detach 
//              attached surfaces, decrementing the reference count of the 
//              surface. 
//              
//              Surfaces that are detached are not released unless their 
//              reference count is reduced to 0. 
//              
//              This method will only detach attachments explicitly formed 
//              using TDx_DrawSurface::AddAttachedSurface(). 
//              
//              Removing surfaces from a chain may change the attachment 
//              order or designation of the surfaces remaining in that chain. 
//              
//              For example, removing a front buffer causes the next surface 
//              in the chain to become the front buffer and the surface after 
//              that to become the back buffer. 
//              Detaching a back buffer causes the next surface in the chain 
//              to become the back buffer while detaching a plain surface 
//              merely shortens the chain. 
//              Detaching a surface from a chain containing two surfaces will 
//              destroy the chain and return the surfaces to the designations 
//              they had prior to being placed in the chain. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_CANNOTDETACHSURFACE 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_SURFACELOST 
//              DDERR_SURFACENOTATTACHED 
// Params:      pAttachedSurface - 
//                The AttachedSurface parameter references the surface that is 
//                to be detached. 
//                Set this parameter to NULL to detach all attached surfaces. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::DeleteAttachedSurface( TDx_DrawSurface* pAttachedSurface )
{
// Original Function Definition
// HRESULT DeleteAttachedSurface( 
//   DWORD dwFlags,                             
//   LPDIRECTDRAWSURFACE7 lpDDSAttachedSurface   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::DeleteAttachedSurface()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->DeleteAttachedSurface( 0, (pAttachedSurface==NULL) ? NULL : pAttachedSurface->Internal_LPDIRECTDRAWSURFACE7 );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::DeleteAttachedSurface()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      Destroy()
// Description: The Destroy() method is used to automatically destroy the 
//              internal LPDIRECTDRAWSURFACE7 interface used in the 
//              TDx_DrawSurface component and should be called when the 
//              internal interface is no longer required. 
//              
//              Note: This method is called by the component's destructor. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::Destroy()
{
// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::Destroy()", "TDX_NOTCREATED", "The "+Name+"::Destroy() method was called before being created successfully." );
    return false;
    }

// code that destroys the internal interfaces
if (FOnDestroy) FOnDestroy(this);

if (fLPDIRECTDRAWSURFACE7==NULL)
    {
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::Destroy()", "TDX_ERROR", "The "+Name+" component's internal LPDIRECTDRAWSURFACE7 is NULL. Aborting the Destroy()." );
    return false;
    }

try {
    fLPDIRECTDRAWSURFACE7->Release();
    }
catch (...)
    {
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::Destroy()", "TDX_ERROR", "An exception occurred in LPDIRECTDRAWSURFACE7->Release(). Check you are destroying all components in reverse order of creation." );
    }

// successful destruction
fLPDIRECTDRAWSURFACE7 = NULL;
fLPDIRECTDRAWSURFACE = NULL;
fCreated = false;
return true;
}

// --------------------------------------------------------------------------
// Method:      EnumAttachedSurfaces()
// Description: The TDx_DrawSurface::EnumAttachedSurfaces method will 
//              enumerate attached surfaces. 
//              
//              This method will only enumerate surfaces directly attached to 
//              this one. 
//              
//              Instead of writing a manual callback function, just place 
//              your code in the TDx_DrawSurface::OnEnumAttachedSurfaces() 
//              event. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_SURFACELOST 
// Params:      pContext - 
//                The Context parameter references an application defined 
//                object passed to the TDx_DrawSurface::EnumSurfacesCallback() 
//                event for each surface enumerated. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::EnumAttachedSurfaces( void* pContext )
{
// Original Function Definition
// HRESULT EnumAttachedSurfaces( 
//   LPVOID lpContext,                                 
//   LPDDENUMSURFACESCALLBACK2 lpEnumSurfacesCallback   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::EnumAttachedSurfaces()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
TDx_DrawSurface_OnEnumAttachedSurfacesOwner = this;
fErrorValue = fLPDIRECTDRAWSURFACE7->EnumAttachedSurfaces( (LPVOID) pContext, Internal_EnumAttachedSurfacesCallback );
TDx_DrawSurface_OnEnumAttachedSurfacesOwner = NULL;

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::EnumAttachedSurfaces()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost)) FOnSurfaceLost(this);

    return false;
    }

// Success!
return true;
}

// --------------------------------------------------------------------------
// Method:      EnumOverlayZOrders()
// Description: The TDx_DrawSurface::EnumOverlayZOrders method will enumerate 
//              overlay surfaces. 
//              
//              Instead of writing a manual callback function, just place 
//              your code in the TDx_DrawSurface::OnEnumOverlayZOrders() 
//              event. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
// Params:      pFlags - 
//                The Flags parameter defines flags indicating the enumeration 
//                direction. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDENUMOVERLAYZ_BACKTOFRONT -
//                    Enumerate overlay surfaces from back to front. 
//                  DDENUMOVERLAYZ_FRONTTOBACK -
//                    Enumerate overlay surfaces from front to back. 
//              pContext - 
//                The Context parameter references an application defined 
//                object passed to the TDx_DrawSurface::EnumSurfacesCallback() 
//                event for each overlay surface enumerated. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::EnumOverlayZOrders( dword pFlags, void* pContext )
{
// Original Function Definition
// HRESULT EnumOverlayZOrders( 
//   DWORD dwFlags,                           
//   LPVOID lpContext,                       
//   LPDDENUMSURFACESCALLBACK2 lpfnCallback   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::EnumOverlayZOrders()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
TDx_DrawSurface_OnEnumOverlayZOrdersOwner = this;
fErrorValue = fLPDIRECTDRAWSURFACE7->EnumOverlayZOrders( (DWORD) pFlags, (LPVOID) pContext, Internal_EnumOverlayZOrdersCallback );
TDx_DrawSurface_OnEnumOverlayZOrdersOwner = NULL;

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::EnumOverlayZOrders()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// Success!
return true;
}

// --------------------------------------------------------------------------
// Method:      Flip()
// Description: The TDx_DrawSurface::Flip method will cause the next surface 
//              in a flip chain to become the DDSCAPS_FRONTBUFFER surface. 
//              
//              The current DDSCAPS_FRONTBUFFER surface becomes a back buffer 
//              and moves to the back of the flip chain. 
//              
//              This method may only be called for surfaces with DDSCAPS_FLIP 
//              and DDSCAPS_FRONTBUFFER set. 
//              
//              Flips are automatically synchronized with the vertical blank. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOFLIPHW 
//              DDERR_NOTFLIPPABLE 
//              DDERR_SURFACEBUSY 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
//              DDERR_WASSTILLDRAWING 
// Params:      pSurfaceTargetOverride - 
//                The SurfaceTargetOverride parameter references a target 
//                surface for the flip. 
//                Set this parameter to NULL to cycle through the surfaces 
//                using the normal attachment order. 
//              pFlags - 
//                The Flags parameter defines flags indicating flip options. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDFLIP_DONOTWAIT -
//                    Continue with application execution immediately after 
//                    the flip is attempted without waiting for a return 
//                    value indicating a successful flip. 
//                  DDFLIP_EVEN -
//                    The surface being flipped to contains the even field of 
//                    a video signal. 
//                    Mutually exclusive with DDFLIP_ODD. 
//                  DDFLIP_INTERVAL2 -
//                    A flip is to occur only every second VSYNC. 
//                    Requires the DDCAPS2_FLIPINTERVAL capability. 
//                  DDFLIP_INTERVAL3 -
//                    A flip is to occur only every third VSYNC. 
//                    Requires the DDCAPS2_FLIPINTERVAL capability. 
//                  DDFLIP_INTERVAL4 -
//                    A flip is to occur only every fourth VSYNC. 
//                    Requires the DDCAPS2_FLIPINTERVAL capability. 
//                  DDFLIP_NOVSYNC -
//                    The flip will occur as close as possible to the next 
//                    scan line, regardless of VSYNC timing. 
//                    Requires the DDCAPS2_FLIPNOVSYNC capability. 
//                    Using this flag allows flips to be performed faster 
//                    than the monitor refresh rate but may cause artifacts. 
//                  DDFLIP_ODD -
//                    The surface being flipped to contains the odd field of 
//                    a video signal. 
//                    Mutually exclusive with DDFLIP_EVEN. 
//                  DDFLIP_WAIT -
//                    The flip will wait until it can be set up or an error 
//                    other than DDERR_WASSTILLDRAWING occurs. 
//                    This is the default flip behaviour, use 
//                    DDFLIP_DONOTWAIT to override. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::Flip( TDx_DrawSurface* pSurfaceTargetOverride, dword pFlags )
{
// Original Function Definition
// HRESULT Flip( 
//   LPDIRECTDRAWSURFACE7 lpDDSurfaceTargetOverride,   
//   DWORD dwFlags                                     
// ); 
// 
// This method may only be called for surfaces with the DDSCAPS_FLIP and 
// DDSCAPS_FRONTBUFFER flags set. 
// Flips are synchronized with the vertical blank. 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::Flip()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->Flip( (pSurfaceTargetOverride==NULL) ? NULL : pSurfaceTargetOverride->Internal_LPDIRECTDRAWSURFACE7, (DWORD) pFlags );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::Flip()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      FreePrivateData()
// Description: The TDx_DrawSurface::FreePrivateData method will free 
//              specified private data. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOTFOUND 
// Params:      pTag - 
//                The Tag parameter references the GUID of the private data 
//                that is to be freed. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::FreePrivateData( REFGUID pTag )
{
// Original Function Definition
// HRESULT FreePrivateData( 
//   REFGUID guidTag, 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::FreePrivateData()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->FreePrivateData( pTag );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::FreePrivateData()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetAttachedSurface()
// Description: The TDx_DrawSurface::GetAttachedSurface method will retrieve 
//              an attached surface with the specified capabilities, 
//              incrementing its reference count. 
//              
//              This method will fail if multiple surfaces match the 
//              specified capabilities. If this occurs, use 
//              TDx_DrawSurface::EnumAttachedSurfaces() to obtain the surface 
//              you seek. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOTFOUND 
//              DDERR_SURFACELOST 
// Params:      pSCaps - 
//                The SCaps parameter references a TDDSCaps component defining 
//                the desired surface's capabilities. 
//              pAttachedSurface - 
//                The AttachedSurface parameter will reference the retrieved 
//                surface if this method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetAttachedSurface( TDDSCaps* pSCaps, TDx_DrawSurface* pAttachedSurface )
{
// Original Function Definition
// HRESULT GetAttachedSurface( 
//   LPDDSCAPS2 lpDDSCaps, 
//   LPDIRECTDRAWSURFACE7 FAR *lplpDDAttachedSurface   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetAttachedSurface()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pSCaps==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetAttachedSurface()", "TDX_BADPARAMS", "'pSCaps' cannot be 'NULL'");
    return false;
    }
if (pAttachedSurface==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetAttachedSurface()", "TDX_BADPARAMS", "'pAttachedSurface' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetAttachedSurface( pSCaps->Internal_DDSCAPS2_Ptr, pAttachedSurface->Internal_LPDIRECTDRAWSURFACE7_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
pSCaps->Internal_DDSCAPS2_Update();
pAttachedSurface->Internal_LPDIRECTDRAWSURFACE7_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetAttachedSurface()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetBltStatus()
// Description: The TDx_DrawSurface::GetBltStatus method will retrieve the 
//              status of the blitter. 
//              
//              If the method call fails, one of the following values will be 
//              returned: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOBLTHW 
//              DDERR_SURFACEBUSY 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
//              DDERR_WASSTILLDRAWING 
// Params:      pFlags - 
//                The Flags parameter defines flags indicating the type of 
//                status information being requested. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDGBS_CANBLT -
//                    A blit involving this surface can occur immediately. 
//                    Returns DD_OK if TRUE. 
//                  DDGBS_ISBLTDONE -
//                    The last blit has been completed. 
//                    Returns DD_OK if TRUE. 
// --------------------------------------------------------------------------
HRESULT __fastcall TDx_DrawSurface::GetBltStatus( dword pFlags )
{
// Original Function Definition
// HRESULT GetBltStatus( 
//   DWORD dwFlags   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetBltStatus()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return fErrorValue;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetBltStatus( (DWORD) pFlags );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetBltStatus()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return fErrorValue;
    }

// Success!
return fErrorValue;
}


// --------------------------------------------------------------------------
// Method:      GetCaps()
// Description: The TDx_DrawSurface::GetCaps method will retrieve surface 
//              capability information. 
//              
//              The capabilities of a given surface are not neccessarily 
//              related to the capabilities of the display device. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
// Params:      pSCaps - 
//                The SCaps parameter references a TDDSCaps component for 
//                holding the retrieved surface capabilities if this method 
//                returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetCaps( TDDSCaps* pSCaps )
{
// Original Function Definition
// HRESULT GetCaps( 
//   LPDDSCAPS2 lpDDSCaps   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetCaps()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pSCaps==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetCaps()", "TDX_BADPARAMS", "'pSCaps' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetCaps( pSCaps->Internal_DDSCAPS2_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
pSCaps->Internal_DDSCAPS2_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetCaps()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetClipper()
// Description: The TDx_DrawSurface::GetClipper method will retrieve the 
//              associated clipper and increment its reference count. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOCLIPPERATTACHED 
// Params:      pClipper - 
//                The Clipper parameter will reference the associated clipper 
//                if this method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetClipper( TDx_DrawClipper* pClipper )
{
// Original Function Definition
// HRESULT GetClipper( 
//   LPDIRECTDRAWCLIPPER FAR *lplpDDClipper   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetClipper()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pClipper==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetClipper()", "TDX_BADPARAMS", "'pClipper' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetClipper( pClipper->Internal_LPDIRECTDRAWCLIPPER_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
pClipper->Internal_LPDIRECTDRAWCLIPPER_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetClipper()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetColorKey()
// Description: The TDx_DrawSurface::GetColorKey method will retrieve the 
//              color key information. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOCOLORKEY 
//              DDERR_NOCOLORKEYHW 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
// Params:      pFlags - 
//                The Flags parameter defines flags indicating which color key 
//                is being requested. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDCKEY_DESTBLT -
//                    Retrieve the destination color key for blits. 
//                  DDCKEY_DESTOVERLAY -
//                    Retrieve the destination color key for overlays. 
//                  DDCKEY_SRCBLT -
//                    Retrieve the source color key for blits. 
//                  DDCKEY_SRCOVERLAY -
//                    Retrieve the source color key for overlays. 
//              pColorKey - 
//                The ColorKey parameter references a TDDColorKey component 
//                which will hold the specified color key information if this 
//                method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetColorKey( dword pFlags, TDDColorKey* pColorKey )
{
// Original Function Definition
// HRESULT GetColorKey( 
//   DWORD dwFlags,             
//   LPDDCOLORKEY lpDDColorKey   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetColorKey()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pColorKey==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetColorKey()", "TDX_BADPARAMS", "'pColorKey' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetColorKey( (DWORD) pFlags, pColorKey->Internal_DDCOLORKEY_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
pColorKey->Internal_DDCOLORKEY_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetColorKey()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetDC()
// Description: The TDx_DrawSurface::GetDC method will create a GDI 
//              compatible device context handle for the surface. 
//              
//              Calling this method will lock the surface until 
//              TDx_DrawSurface::ReleaseDC() is called. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_DCALREADYCREATED 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDSURFACETYPE 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
//              DDERR_WASSTILLDRAWING 
// Params:      pDC - 
//                The DC parameter will reference the device context handle for 
//                the surface if this method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetDC( HDC* pDC )
{
// Original Function Definition
// HRESULT GetDC( 
//   HDC FAR *lphDC   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetDC()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pDC==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetDC()", "TDX_BADPARAMS", "'pDC' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetDC( pDC );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetDC()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetDDInterface()
// Description: The TDx_DrawSurface::GetDDInterface method will retrieve a 
//              reference to the surface's parent TDx_Draw component. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
// Params:      pDD - 
//                The DD parameter will reference the parent TDx_Draw component 
//                if this method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetDDInterface( void** pDD )
{
// Original Function Definition
// HRESULT GetDDInterface( 
//   LPVOID FAR *lplpDD   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetDDInterface()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetDDInterface( (LPVOID*) pDD );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetDDInterface()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetFlipStatus()
// Description: The TDx_DrawSurface::GetFlipStatus method will retrieve the 
//              current flip status. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDSURFACETYPE 
//              DDERR_SURFACEBUSY 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
//              DDERR_WASSTILLDRAWING 
// Params:      pFlags - 
//                The Flags parameter defines flags indicating the type of 
//                status information desired. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDGFS_CANFLIP -
//                    A flip can occur immediately. 
//                    Returns DD_OK if TRUE. 
//                  DDGFS_ISFLIPDONE -
//                    The last flip has been completed. 
//                    Returns DD_OK if TRUE. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetFlipStatus( dword pFlags )
{
// Original Function Definition
// HRESULT GetFlipStatus( 
//   DWORD dwFlags   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetFlipStatus()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetFlipStatus( (DWORD) pFlags );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetFlipStatus()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetLOD()
// Description: The TDx_DrawSurface::GetLOD method will return the maximum 
//              level of detail (LOD) currently set for a managed mipmap. 
//              
//              Calling this method on a surface without 
//              DDSCAPS2_TEXTUREMANAGE set will merely result in a 
//              DDERR_INVALIDOBJECT error being returned. 
//              
//              If successful the MaxLOD parameter will contain a number 
//              indicating the largest mipmap level in the chain the TDx_3D 
//              texture manager should display. 
//              
//              For example, if this method returned a 3 in the MaxLOD 
//              parameter, it would indicate that only mipmaps of level 3 or 
//              smaller should be displayed. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT   
//              DDERR_INVALIDPARAMS 
// Params:      pMaxLOD - 
//                The MaxLOD parameter will reference the maximum level of 
//                detail set for the mipmap chain if the method call succeeds. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetLOD( dword* pMaxLOD )
{
// Original Function Definition
// HRESULT GetLOD( 
//     LPDWORD lpdwMaxLOD 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetLOD()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetLOD( (LPDWORD) pMaxLOD );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetLOD()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetOverlayPosition()
// Description: The TDx_DrawSurface::GetOverlayPosition method will retrieve 
//              the current display coordinates of an overlay surface. 
//              
//              This method will fail unless the surface is a visible, active 
//              surface with DDSCAPS_OVERLAY set. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDPOSITION 
//              DDERR_NOOVERLAYDEST 
//              DDERR_NOTAOVERLAYSURFACE 
//              DDERR_OVERLAYNOTVISIBLE 
//              DDERR_SURFACELOST 
// Params:      pX - 
//                The X parameter will reference the overlay's  X axis display 
//                coordinate if this method returns successfully. 
//              pY - 
//                The Y parameter will reference the overlay's  Y axis display 
//                coordinate if this method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetOverlayPosition( long* pX, long* pY )
{
// Original Function Definition
// HRESULT GetOverlayPosition( 
//   LPLONG lplX, 
//   LPLONG lplY   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetOverlayPosition()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pX==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetOverlayPosition()", "TDX_BADPARAMS", "'pX' cannot be 'NULL'");
    return false;
    }
if (pY==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetOverlayPosition()", "TDX_BADPARAMS", "'pY' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetOverlayPosition( (LPLONG) pX, (LPLONG) pY );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetOverlayPosition()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetPalette()
// Description: The TDx_DrawSurface::GetPalette method will retrieve the 
//              surface's palette and increment the palette's reference 
//              count. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOEXCLUSIVEMODE 
//              DDERR_NOPALETTEATTACHED 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
// Params:      pPalette - 
//                The Palette parameter will reference the retrieved palette if 
//                this method returns successfully. 
//                NULL will be returned if there is no palette associated with 
//                the surface. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetPalette( TDx_DrawPalette* pPalette )
{
// Original Function Definition
// HRESULT GetPalette( 
//   LPDIRECTDRAWPALETTE FAR *lplpDDPalette   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetPalette()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetPalette( (pPalette==NULL) ? NULL : pPalette->Internal_LPDIRECTDRAWPALETTE_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
if (pPalette!=NULL) pPalette->Internal_LPDIRECTDRAWPALETTE_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetPalette()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetPixelFormat()
// Description: The TDx_DrawSurface::GetPixelFormat method will retrieve the 
//              surface's color and pixel format information. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDSURFACETYPE 
// Params:      pPixelFormat - 
//                The PixelFormat parameter references a TDDPixelFormat 
//                component for holding the surface's current pixel and color 
//                format if this method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetPixelFormat( TDDPixelFormat* pPixelFormat )
{
// Original Function Definition
// HRESULT GetPixelFormat( 
//   LPDDPIXELFORMAT lpDDPixelFormat   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetPixelFormat()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pPixelFormat==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetPixelFormat()", "TDX_BADPARAMS", "'pPixelFormat' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetPixelFormat( pPixelFormat->Internal_DDPIXELFORMAT_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
pPixelFormat->Internal_DDPIXELFORMAT_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetPixelFormat()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetPriority()
// Description: The TDx_DrawSurface::GetPriority method will retrieve current 
//              management priority level assigned for a texture. 
//              
//              This method only works with managed textures, which are 
//              removed in order of the least recently used texture first. 
//              The priority level indicates which texture will be removed 
//              first if two textures have the same "last use" time stamp. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with the following value: 
//              DDERR_INVALIDOBJECT 
// Params:      pPriority - 
//                The Priority parameter will reference the current texture 
//                priority level if the method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetPriority( dword* pPriority )
{
// Original Function Definition
// HRESULT GetPriority( 
//   LPDWORD lpdwPriority 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetPriority()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetPriority( (LPDWORD) pPriority );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetPriority()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetPrivateData()
// Description: The TDx_DrawSurface::GetPrivateData method will retrieve the 
//              surface's private data. 
//              
//              If the method call fails, one of the following values will be 
//              returned: 
//              DDERR_EXPIRED 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_MOREDATA 
//              DDERR_NOTFOUND 
//              DDERR_OUTOFMEMORY 
// Params:      pTag - 
//                The Tag parameter references the GUID of the private data 
//                that is to be retrieved. 
//              pBuffer - 
//                The Buffer parameter references a buffer for holding the 
//                retrieved private data if this method returns successfully. 
//                The buffer must be explicitly allocated and released by the 
//                calling application. 
//              pBufferSize - 
//                The BufferSize parameter defines the size, in bytes, of the 
//                buffer referenced by the Buffer parameter of this method. 
//                If there is insufficient space for the requested information, 
//                this parameter will be set to the required size and 
//                DDERR_MOREDATA returned. 
// --------------------------------------------------------------------------
HRESULT __fastcall TDx_DrawSurface::GetPrivateData( REFGUID pTag, void* pBuffer, dword* pBufferSize )
{
// Original Function Definition
// HRESULT GetPrivateData( 
//   REFGUID guidTag, 
//   LPVOID  lpBuffer, 
//   LPDWORD lpcbBufferSize 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetPrivateData()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return fErrorValue;
    }

// Check Parameters for Accuracy
if (pBufferSize==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetPrivateData()", "TDX_BADPARAMS", "'pBufferSize' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetPrivateData( pTag, (LPVOID) pBuffer, (LPDWORD) pBufferSize );
    }
catch (...)
    {
    }

// Success!
return fErrorValue;
}


// --------------------------------------------------------------------------
// Method:      GetSurfaceDesc()
// Description: The TDx_DrawSurface::GetSurfaceDesc method will retrieve the 
//              current surface description. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
// Params:      pSurfaceDesc - 
//                The SurfaceDesc parameter references a TDDSurfaceDesc 
//                component for holding the retrieved surface description if 
//                this method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetSurfaceDesc( TDDSurfaceDesc* pSurfaceDesc )
{
// Original Function Definition
// HRESULT GetSurfaceDesc( 
//   LPDDSURFACEDESC2 lpDDSurfaceDesc   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetSurfaceDesc()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pSurfaceDesc==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetSurfaceDesc()", "TDX_BADPARAMS", "'pSurfaceDesc' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetSurfaceDesc( pSurfaceDesc->Internal_DDSURFACEDESC2_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
pSurfaceDesc->Internal_DDSURFACEDESC2_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetSurfaceDesc()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      GetUniquenessValue()
// Description: The TDx_DrawSurface::GetUniquenessValue method will retrieve 
//              the surface's current uniqueness value. 
//              
//              If the retrieved uniqueness value is different to the 
//              previous one, it indicates that the surface contents have 
//              changed. 
//              
//              A uniqueness value of zero indicates the surface is likely to 
//              be changing beyond the control of the TDx_Draw_Library. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
// Params:      pValue - 
//                The Value parameter will reference the surface's current 
//                uniqueness value if this method returns successfully. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::GetUniquenessValue( dword* pValue )
{
// Original Function Definition
// HRESULT GetUniquenessValue( 
//   LPDWORD lpValue, 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetUniquenessValue()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pValue==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetUniquenessValue()", "TDX_BADPARAMS", "'pValue' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->GetUniquenessValue( (LPDWORD) pValue );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::GetUniquenessValue()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      Internal_EnumAttachedSurfacesCallback()
// Description: The Internal_EnumAttachedSurfacesCallback method is used 
//              internally by the TDx_Draw_Library to redirect a standard 
//              callback function to a BCB style event. 
// Params:      pDDSurface - 
//                Address of the LPDIRECTDRAWSURFACE7 interface for the 
//                attached surface. 
//              pDDSurfaceDesc - 
//                The DDSurfaceDesc parameter describes the enumerated surface. 
//              pContext - 
//                Application defined data passed to the enumeration method 
//                call. 
// --------------------------------------------------------------------------
HRESULT __stdcall TDx_DrawSurface::Internal_EnumAttachedSurfacesCallback( LPDIRECTDRAWSURFACE7 pDDSurface, LPDDSURFACEDESC2 pDDSurfaceDesc, LPVOID pContext )
{
// Original Function Definition
// HRESULT WINAPI EnumSurfacesCallback7(
//   LPDIRECTDRAWSURFACE7 lpDDSurface,
//   LPDDSURFACEDESC2 lpDDSurfaceDesc,
//   LPVOID lpContext
// );

// Allocate temporary storage for converted data
TDx_DrawSurface* surface = new TDx_DrawSurface(TDx_DrawSurface_OnEnumAttachedSurfacesOwner);
if (surface==NULL)
    {
    TDx_DrawSurface_OnEnumAttachedSurfacesOwner->fErrorValue = TDX_ERROR;
    if (TDx_DrawSurface_OnEnumAttachedSurfacesOwner->FOnError)
    	TDx_DrawSurface_OnEnumAttachedSurfacesOwner->FOnError( TDx_DrawSurface_OnEnumAttachedSurfacesOwner, TDx_DrawSurface_OnEnumAttachedSurfacesOwner->Name+"::Internal_EnumSurfacesCallback()", "TDX_ERROR", "Could not create a temporary TDx_DrawSurface component." );
    return DDENUMRET_CANCEL;
    }

TDDSurfaceDesc* surface_desc = new TDDSurfaceDesc(TDx_DrawSurface_OnEnumAttachedSurfacesOwner);
if (surface_desc==NULL)
    {
    delete surface;
    TDx_DrawSurface_OnEnumAttachedSurfacesOwner->fErrorValue = TDX_ERROR;
    if (TDx_DrawSurface_OnEnumAttachedSurfacesOwner->FOnError)
    	TDx_DrawSurface_OnEnumAttachedSurfacesOwner->FOnError( TDx_DrawSurface_OnEnumAttachedSurfacesOwner, TDx_DrawSurface_OnEnumAttachedSurfacesOwner->Name+"::Internal_EnumSurfacesCallback()", "TDX_ERROR", "Could not create a temporary TDDSurfaceDesc component." );
    return DDENUMRET_CANCEL;
    }

TDDPixelFormat* pixel_format = new TDDPixelFormat(TDx_DrawSurface_OnEnumAttachedSurfacesOwner);
if (pixel_format==NULL)
    {
    delete surface_desc;
    delete surface;
    TDx_DrawSurface_OnEnumAttachedSurfacesOwner->fErrorValue = TDX_ERROR;
    if (TDx_DrawSurface_OnEnumAttachedSurfacesOwner->FOnError)
    	TDx_DrawSurface_OnEnumAttachedSurfacesOwner->FOnError( TDx_DrawSurface_OnEnumAttachedSurfacesOwner, TDx_DrawSurface_OnEnumAttachedSurfacesOwner->Name+"::Internal_EnumSurfacesCallback()", "TDX_ERROR", "Could not create a temporary TDDPixelFormat component." );
    return DDENUMRET_CANCEL;
    }


// Translate Parameters before calling Original Function
surface->Internal_LPDIRECTDRAWSURFACE7 = pDDSurface;
CopyMemory( surface_desc->Internal_DDSURFACEDESC2_Ptr, pDDSurfaceDesc, sizeof(DDSURFACEDESC2));
surface_desc->PixelFormat = pixel_format;
surface_desc->Internal_DDSURFACEDESC2_Update();
void* context = pContext;

// transfer to the Callback Event (if it exists)
bool finished = false;
if (TDx_DrawSurface_OnEnumAttachedSurfacesOwner->OnEnumAttachedSurfaces)
	TDx_DrawSurface_OnEnumAttachedSurfacesOwner->OnEnumAttachedSurfaces( TDx_DrawSurface_OnEnumAttachedSurfacesOwner, surface, surface_desc, context, finished );

// cleanup as required
delete pixel_format;
delete surface_desc;
delete surface;

// Finished, return 1 if not aborted
if (finished) return DDENUMRET_CANCEL;
return DDENUMRET_OK;
}

// --------------------------------------------------------------------------
// Method:      Internal_EnumOverlayZOrdersCallback()
// Description: The Internal_EnumOverlayZOrdersCallback method is used 
//              internally by the TDx_Draw_Library to redirect a standard 
//              callback function to a BCB style event. 
// Params:      pDDSurface - 
//                Address of the LPDIRECTDRAWSURFACE7 interface for the 
//                attached surface. 
//              pDDSurfaceDesc - 
//                The DDSurfaceDesc parameter describes the enumerated surface. 
//              pContext - 
//                Application defined data passed to the enumeration method 
//                call. 
// --------------------------------------------------------------------------
HRESULT __stdcall TDx_DrawSurface::Internal_EnumOverlayZOrdersCallback( LPDIRECTDRAWSURFACE7 pDDSurface, LPDDSURFACEDESC2 pDDSurfaceDesc, LPVOID pContext )
{
// Original Function Definition
// HRESULT WINAPI EnumSurfacesCallback7( 
//   LPDIRECTDRAWSURFACE7 lpDDSurface,   
//   LPDDSURFACEDESC2 lpDDSurfaceDesc,   
//   LPVOID lpContext                   
// ); 

// Allocate temporary storage for converted data
TDx_DrawSurface* surface = new TDx_DrawSurface(TDx_DrawSurface_OnEnumOverlayZOrdersOwner);
if (surface==NULL)
    {
    TDx_DrawSurface_OnEnumOverlayZOrdersOwner->fErrorValue = TDX_ERROR;
    if (TDx_DrawSurface_OnEnumOverlayZOrdersOwner->FOnError) TDx_DrawSurface_OnEnumOverlayZOrdersOwner->FOnError( TDx_DrawSurface_OnEnumOverlayZOrdersOwner, TDx_DrawSurface_OnEnumOverlayZOrdersOwner->Name+"::Internal_EnumOverlayZOrdersCallback()", "TDX_ERROR", "Could not create a temporary TDx_DrawSurface component." );
    return DDENUMRET_CANCEL;
    }

TDDSurfaceDesc* surface_desc = new TDDSurfaceDesc(TDx_DrawSurface_OnEnumOverlayZOrdersOwner);
if (surface_desc==NULL)
    {
    delete surface;
    TDx_DrawSurface_OnEnumOverlayZOrdersOwner->fErrorValue = TDX_ERROR;
    if (TDx_DrawSurface_OnEnumOverlayZOrdersOwner->FOnError) TDx_DrawSurface_OnEnumOverlayZOrdersOwner->FOnError( TDx_DrawSurface_OnEnumOverlayZOrdersOwner, TDx_DrawSurface_OnEnumOverlayZOrdersOwner->Name+"::Internal_EnumOverlayZOrdersCallback()", "TDX_ERROR", "Could not create a temporary TDDSurfaceDesc component." );
    return DDENUMRET_CANCEL;
    }

TDDPixelFormat* pixel_format = new TDDPixelFormat(TDx_DrawSurface_OnEnumOverlayZOrdersOwner);
if (pixel_format==NULL)
    {
    delete surface_desc;
    delete surface;
    TDx_DrawSurface_OnEnumOverlayZOrdersOwner->fErrorValue = TDX_ERROR;
    if (TDx_DrawSurface_OnEnumOverlayZOrdersOwner->FOnError) TDx_DrawSurface_OnEnumOverlayZOrdersOwner->FOnError( TDx_DrawSurface_OnEnumOverlayZOrdersOwner, TDx_DrawSurface_OnEnumOverlayZOrdersOwner->Name+"::Internal_EnumOverlayZOrdersCallback()", "TDX_ERROR", "Could not create a temporary TDDPixelFormat component." );
    return DDENUMRET_CANCEL;
    }

// Translate Parameters before calling Original Function
surface->Internal_LPDIRECTDRAWSURFACE7 = pDDSurface;
CopyMemory( surface_desc->Internal_DDSURFACEDESC2_Ptr, pDDSurfaceDesc, sizeof(DDSURFACEDESC2));
surface_desc->PixelFormat = pixel_format;
surface_desc->Internal_DDSURFACEDESC2_Update();
void* context = pContext;

// transfer to the Callback Event (if it exists)
bool finished = false;
if (TDx_DrawSurface_OnEnumOverlayZOrdersOwner->OnEnumOverlayZOrders)
TDx_DrawSurface_OnEnumOverlayZOrdersOwner->OnEnumOverlayZOrders( TDx_DrawSurface_OnEnumOverlayZOrdersOwner, surface, surface_desc, context, finished );

// cleanup as required
delete pixel_format;
delete surface_desc;
delete surface;

// Finished, return 1 if not aborted
if (finished) return DDENUMRET_CANCEL;
return DDENUMRET_OK;
}

// --------------------------------------------------------------------------
// Method:      IsLost()
// Description: The TDx_DrawSurface::IsLost method will determine whether a 
//              surface's associated memory has been lost. 
//              
//              Possible ways memory could be lost may be the changing of 
//              display card mode or another application getting exclusive 
//              access to the display card and freeing all of the previously 
//              allocated surface memory. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_SURFACELOST 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::IsLost()
{
// Original Function Definition
// HRESULT IsLost(); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::IsLost()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->IsLost(  );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DDERR_SURFACELOST)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::IsLost()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      LoadFromFile()
// Description: The LoadFromFile method is used to load an existing image 
//              from an existing .BMP file. 
//              If the image file does not exist, nothing happens. 
//              If the image file exists, the image data is scaled to the 
//              size of the surface using the StretchBlt() method. 
//              Refer to TDx_DrawPalette::LoadFromFile() for info on how to 
//              load a bitmap's palette. 
//              
//              This method returns the following error values: 
//              TDX_ERROR 
//              TDX_BADPARAMS 
// Params:      pDraw - 
//                The Draw parameter must be a previously created TDx_Draw 
//                component. 
//              pFileName - 
//                The FileName parameter specifies the name of a standard .BMP 
//                file that the image is to be loaded from and can include a 
//                directory path if required. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::LoadFromFile( TDx_Draw* pDraw, AnsiString pFileName )
{
// check parameters for accuracy
if (pDraw==NULL) 
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::LoadFromFile()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a NULL pDraw parameter." );
    return false;
    }
if (pFileName=="") 
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::LoadFromFile()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a empty pFileName parameter." );
    return false;
    }

// check that the file exists
if (!FileExists(pFileName))
    {
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::LoadFromFile()", "TDX_ERROR", "The "+Name+" component is attempting to load from a non-existant bitmap file: "+pFileName );
    return false;
    }

// Allocate anything we need to use to load the bitmap data
Graphics::TBitmap* bitmap = new Graphics::TBitmap();
TDDSurfaceDesc* desc = new TDDSurfaceDesc(NULL);
TDDSCaps* scaps = new TDDSCaps(NULL);
TCanvas* canvas = new TCanvas();
if (bitmap==NULL || desc==NULL || scaps==NULL || canvas==NULL)
    {
    if (canvas) delete canvas;
    if (scaps) delete scaps;
    if (desc) delete desc;
    if (bitmap) delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError(this, Name+"::LoadFromFile()", "TDX_ERROR", "Could not allocate temporary buffers used to load the bitmap image: "+pFileName );
    return false;
    }

// load the bitmap from the bitmap file
try {
    bitmap->LoadFromFile( pFileName );
    }
catch (...)
    {
    delete canvas;
    delete scaps;
    delete desc;
    delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError(this, Name+"::LoadFromFile()", "TDX_ERROR", "An unknown error occurred while attempting to read the data from bitmap file: "+pFileName );
    return false;
    }

// copy the image data from our temporary image to the surface
HDC hdc;
if (this->GetDC( &hdc ))
    {
    StretchBlt( hdc, 0, 0, desc->Width, desc->Height,
                bitmap->Handle, 0, 0, bitmap->Width, bitmap->Height,
                SRCCOPY );
    this->ReleaseDC( hdc );
    }
else
    {
    // couldn't get DC :(
    delete scaps;
    delete desc;
    delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::LoadFromFile()", "TDX_ERROR", "The surface may contain invalid data because it could not GetDC() to access surface data." );
    return false;
    }

// clean-up
delete canvas;
delete scaps;
delete desc;
delete bitmap;

// return true if successful
return true;
}

// --------------------------------------------------------------------------
// Method:      LoadFromSurface()
// Description: The LoadFromSurface method is used to load the surface data 
//              from an existing surface, without recreating the current 
//              surface. Supplied surface data is scaled to the size of the 
//              current surface using the StretchBlt() method. 
//              Refer to TDx_DrawPalette::CreateFromFile() for info on how to 
//              load a bitmap's palette. 
//              
//              This method returns the following error values: 
//              TDX_ERROR 
//              TDX_BADPARAMS 
// Params:      pDraw - 
//                The Draw parameter must be a previously created TDx_Draw 
//                component. 
//              pSurface - 
//                The Surface parameter must be a previously created 
//                TDx_DrawSurface component. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::LoadFromSurface( TDx_Draw* pDraw, TDx_DrawSurface* pSurface )
{
// check parameters for accuracy
if (pDraw==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::LoadFromSurface()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a NULL pDraw parameter." );
    return false;
    }
if (pSurface==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::LoadFromSurface()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a NULL pSurface parameter." );
    return false;
    }

// Allocate anything we need to use to load the bitmap data
TDDSurfaceDesc* dest_desc = new TDDSurfaceDesc(NULL);
TDDSurfaceDesc* srce_desc = new TDDSurfaceDesc(NULL);
if (dest_desc==NULL || srce_desc==NULL)
    {
    if (srce_desc) delete srce_desc;
    if (dest_desc) delete dest_desc;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError(this, Name+"::LoadFromSurface()", "TDX_ERROR", "Could not allocate temporary buffers used to create the surface: "+Name );
    return false;
    }

// retrieve the surface characteristics
this->GetSurfaceDesc( dest_desc );
pSurface->GetSurfaceDesc( srce_desc );

// copy the image data from our temporary image to the surface
HDC dest_hdc;
HDC srce_hdc;
bool dest_ok = this->GetDC( &dest_hdc );
bool srce_ok = pSurface->GetDC( &srce_hdc );

if (dest_ok && srce_ok)
    StretchBlt( dest_hdc, 0, 0, dest_desc->Width, dest_desc->Height,
                srce_hdc, 0, 0, srce_desc->Width, srce_desc->Height,
                SRCCOPY );

if (srce_ok) pSurface->ReleaseDC( srce_hdc );
if (dest_ok) this->ReleaseDC( dest_hdc );

if (!dest_ok || !srce_ok)
    {
    delete srce_desc;
    delete dest_desc;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::CreateFromFile()", "TDX_ERROR", "The surface may contain invalid data because it could not GetDC() to access surface data." );
    return false;
    }

// clean-up
delete srce_desc;
delete dest_desc;

// successful
return true;
}

// --------------------------------------------------------------------------
// Method:      Lock()
// Description: The TDx_DrawSurface::Lock method will obtain a pointer to the 
//              specified portion of surface memory. 
//              
//              This prevents the system blitter from accessing that 
//              particular area of memory. 
//              
//              Page flipping is prevented until the surface is unlocked 
//              using TDx_DrawSurface::Unlock(). 
//              
//              Attempting to blit from a locked region will return errors 
//              and GDI blits will silently fail when used on a locked video 
//              memory surface. 
//              
//              Specify DDLOCK_NOSYSLOCK to avoid the Win16Mutex (Win16Lock) 
//              being held for non-primary surfaces. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_OUTOFMEMORY 
//              DDERR_SURFACEBUSY 
//              DDERR_SURFACELOST 
//              DDERR_WASSTILLDRAWING 
// Params:      pDestRect - 
//                The DestRect parameter references a TRect defining the 
//                portion of the surface that is to be locked. 
//                Set this parameter to NULL to lock an entire surface. 
//              pSurfaceDesc - 
//                The SurfaceDesc parameter references a TDDSurfaceDesc 
//                component for holding the description of the locked surface 
//                if this method returns successfully. 
//              pFlags - 
//                The Flags parameter defines flags indicating the type of lock 
//                to be performed. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDLOCK_DISCARDCONTENTS -
//                    No assumptions are made about vertex buffer contents 
//                    during this lock. 
//                    
//                    This flag is only used in relation to TDx_3D 
//                    vertex-buffer locks and is useful when clearing the 
//                    vertex buffer and filling it with new data. 
//                    TDx_3D or the driver may provide an alternative memory 
//                    area for the vertex buffer. 
//                  DDLOCK_DONOTWAIT -
//                    Continue with application execution immediately after 
//                    the lock is attempted without waiting for a return 
//                    value indicating a successful lock. 
//                  DDLOCK_EVENT -
//                    This flag has not yet been implemented by Microsoft. 
//                  DDLOCK_NOOVERWRITE -
//                    No 3D vertices referred to since the start of the frame 
//                    or the last lock without this flag are modified during 
//                    this lock. 
//                    This flag is only used in relation to TDx_3D 
//                    vertex-buffer locks and is useful when appending data 
//                    to the vertex buffer. 
//                  DDLOCK_NOSYSLOCK -
//                    Win16Lock will not be taken unless it is unavoidable. 
//                    This flag does not apply when attempting to lock the 
//                    primary surface. 
//                  DDLOCK_READONLY -
//                    The locked surface will only be read from. 
//                  DDLOCK_SURFACEMEMORYPTR -
//                    A memory pointer to the top of the rectangle specified 
//                    in the DestRect parameter of this method will be 
//                    returned. 
//                    Set the DestRect parameter of this method to NULL to 
//                    return a pointer to the top of the surface. 
//                  DDLOCK_WAIT -
//                    The lock will wait until it can be obtained or an error 
//                    other than DDERR_WASSTILLDRAWING occurs. 
//                  DDLOCK_WRITEONLY -
//                    The locked surface will only be written to. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::Lock( TRect* pDestRect, TDDSurfaceDesc* pSurfaceDesc, dword pFlags )
{
// Original Function Definition
// HRESULT Lock( 
//   LPRECT lpDestRect,                 
//   LPDDSURFACEDESC2 lpDDSurfaceDesc,   
//   DWORD dwFlags,                     
//   HANDLE hEvent                     
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::Lock()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pSurfaceDesc==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::Lock()", "TDX_BADPARAMS", "'pSurfaceDesc' cannot be 'NULL'");
    return false;
    }

// Translate Parameters before calling Original Function
RECT TempDestRect;
LPRECT TempDestRect_Ptr;
if (pDestRect==NULL)
    {
    TempDestRect_Ptr = NULL;
    }
 else
    {
    TempDestRect.top = pDestRect->Top;
    TempDestRect.left = pDestRect->Left;
    TempDestRect.right = pDestRect->Right;
    TempDestRect.bottom = pDestRect->Bottom;
    TempDestRect_Ptr = &TempDestRect;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->Lock( TempDestRect_Ptr, pSurfaceDesc->Internal_DDSURFACEDESC2_Ptr, (DWORD) pFlags, NULL );
    }
catch (...)
    {
    }

// Translate Data returned from Function
pSurfaceDesc->Internal_DDSURFACEDESC2_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::Lock()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      PageLock()
// Description: The TDx_DrawSurface::PageLock method will prevent a system 
//              memory surface from being paged out while a DMA blit is 
//              taking place. 
//              
//              The lock count for the surface will be incremented. Use 
//              TDx_DrawSurface::PageUnlock() to decrement the lock count. 
//              Once the lock count reaches zero the surface is unlocked and 
//              can again be paged out by the operating system. 
//              
//              Only non-primary system memory surfaces can be PageLocked. 
//              Calling this method on display memory surfaces will do 
//              nothing other than return without error. 
//              
//              PageLock must be held before using DMA support, otherwise the 
//              blit will use software emulation. 
//              
//              PageLocking excessive amounts of memory can seriously impede 
//              operating system performance. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_CANTPAGELOCK 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_SURFACELOST 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::PageLock()
{
// Original Function Definition
// HRESULT PageLock( 
//   DWORD dwFlags   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::PageLock()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->PageLock( 0 );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::PageLock()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      PageUnlock()
// Description: The TDx_DrawSurface::PageUnlock method will decrement the 
//              lock count of a locked system memory surface. 
//              
//              The memory can be paged out when the lock count is reduced to 
//              zero. 
//              
//              This method will not page unlock display memory or primary 
//              surfaces, doing nothing other than returning without error. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_CANTPAGEUNLOCK 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOTPAGELOCKED 
//              DDERR_SURFACELOST 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::PageUnlock()
{
// Original Function Definition
// HRESULT PageUnlock( 
//   DWORD dwFlags   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::PageUnlock()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->PageUnlock( 0 );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::PageUnlock()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      ReleaseDC()
// Description: The TDx_DrawSurface::ReleaseDC method will release the device 
//              context handle obtained using TDx_DrawSurface::GetDC. 
//              
//              The surface locked by TDx_DrawSurface::GetDC() is also 
//              released. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
// Params:      pDC - 
//                The DC parameter references the device context handle to be 
//                released. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::ReleaseDC( HDC pDC )
{
// Original Function Definition
// HRESULT ReleaseDC( 
//   HDC hDC   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::ReleaseDC()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pDC==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::ReleaseDC()", "TDX_BADPARAMS", "'pDC' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->ReleaseDC( pDC );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::ReleaseDC()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      Restore()
// Description: The TDx_DrawSurface::Restore method will restore a lost 
//              memory surface by reallocating and reattaching the memory. 
//              
//              Allocated surface memory will be restored, but it is the 
//              responsibility of the application to restore the contents of 
//              the surface. 
//              
//              Lost surfaces may be caused by display card mode changes or 
//              another application acquiring access and freeing all the 
//              display card surface memory. 
//              
//              All associated implicitly created surfaces will be restored 
//              in a single call, while surfaces that have been explicitly 
//              attached will require individual restoration. 
//              
//              Attempting to directly restore an implicitly created surface 
//              will result in an error. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_IMPLICITLYCREATED 
//              DDERR_INCOMPATIBLEPRIMARY 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOEXCLUSIVEMODE 
//              DDERR_OUTOFMEMORY 
//              DDERR_UNSUPPORTED 
//              DDERR_WRONGMODE 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::Restore()
{
// Original Function Definition
// HRESULT Restore(); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::Restore()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->Restore(  );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::Restore()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      SaveToFile()
// Description: The SaveToFile method is used to create an image file 
//              containing the contents of the current surface. 
//              If the image file already exists, nothing happens. 
//              If the image file can be created, the surface data is saved 
//              into the file. 
//              Refer to TDx_DrawPalette::SaveToFile() for info on how to 
//              save a bitmap's palette. 
//              
//              This method returns the following error values: 
//              TDX_ERROR 
//              TDX_BADPARAMS 
// Params:      pDraw - 
//                The Draw parameter must be a previously created TDx_Draw 
//                component. 
//              pFileName - 
//                The FileName parameter specifies the name of a standard .BMP 
//                file that the image is to be saved to and can include a 
//                directory path if required. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SaveToFile( TDx_Draw* pDraw, AnsiString pFileName )
{
// check parameters for accuracy
if (pDraw==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::SaveToFile()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a NULL pDraw parameter." );
    return false;
    }
if (pFileName=="")
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::SaveToFile()", "TDX_BADPARAMS", "The "+Name+" component is attempting to use a empty pFileName parameter." );
    return false;
    }

// check that the file exists
if (FileExists(pFileName))
    {
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::SaveToFile()", "TDX_ERROR", "The "+Name+" component is attempting to save to a pre-existing bitmap file: "+pFileName );
    return false;
    }

// Allocate anything we need to use to load the bitmap data
Graphics::TBitmap* bitmap = new Graphics::TBitmap();
TDDSurfaceDesc* desc = new TDDSurfaceDesc(NULL);
TDDSCaps* scaps = new TDDSCaps(NULL);
if (bitmap==NULL || desc==NULL || scaps==NULL)
    {
    if (scaps) delete scaps;
    if (desc) delete desc;
    if (bitmap) delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError(this, Name+"::SaveToFile()", "TDX_ERROR", "Could not allocate temporary buffers used to save the bitmap image: "+pFileName );
    return false;
    }

// retrieve the surface characteristics
desc->SCaps = scaps;
GetSurfaceDesc( desc );

// resize data storage area
bitmap->Width = desc->Width;
bitmap->Height = desc->Height;

// copy the image data from the surface to the image
HDC hdc;
if (this->GetDC( &hdc ))
    {
    StretchBlt( bitmap->Canvas->Handle, 0, 0, desc->Width, desc->Height,
                hdc, 0, 0, desc->Width, desc->Height,
                SRCCOPY );
    this->ReleaseDC( hdc );
    }
else
    {
    // couldn't get DC :(
    delete scaps;
    delete desc;
    delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::SaveToFile()", "TDX_ERROR", "The SaveToFile() method has failed because it could not GetDC() to access surface data." );
    return false;
    }

// save the bitmap to the file using TBitmap::SaveToFile()
try {
    bitmap->SaveToFile( pFileName );
    }
catch (...)
    {
    delete scaps;
    delete desc;
    delete bitmap;
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError(this, Name+"::SaveToFile()", "TDX_ERROR", "An unknown error occurred while attempting to write the data to bitmap file: "+pFileName );
    return false;
    }

// clean-up
delete scaps;
delete desc;
delete bitmap;

// successful
return true;
}

// --------------------------------------------------------------------------
// Method:      SetClipper()
// Description: The TDx_DrawSurface::SetClipper method will attach or detach 
//              a clipper for the surface. 
//              
//              The initial call to this method will increment the clippers 
//              reference count but further calls associating it with the 
//              same surface will not further affect the reference count. 
//              
//              Passing NULL to the Clipper parameter detaches the clipper 
//              and decrements the clippers reference count. If the surface 
//              is released before the clipper is detached, the clippers 
//              reference count will automatically be decremented. It is the 
//              applications responsibility to release further references to 
//              the clipper if it is no longer needed. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDSURFACETYPE 
//              DDERR_NOCLIPPERATTACHED 
// Params:      pClipper - 
//                The Clipper parameter references the clipper that is to be 
//                attached. 
//                Set this parameter to NULL to detach the current clipper. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SetClipper( TDx_DrawClipper* pClipper )
{
// Original Function Definition
// HRESULT SetClipper( 
//   LPDIRECTDRAWCLIPPER lpDDClipper   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetClipper()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->SetClipper( (pClipper==NULL) ? NULL : pClipper->Internal_LPDIRECTDRAWCLIPPER );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::SetClipper()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      SetColorKey()
// Description: The TDx_DrawSurface::SetColorKey method will set the 
//              surface's color key. 
//              
//              Hardware support for "per surface" color keys must exist. 
//              
//              When performing transparent blits and overlays, the 
//              destination color key should be set on the destination 
//              surface and the source color key set on the source surface. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDSURFACETYPE 
//              DDERR_NOOVERLAYHW 
//              DDERR_NOTAOVERLAYSURFACE 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
//              DDERR_WASSTILLDRAWING 
// Params:      pFlags - 
//                The Flags parameter defines flags indicating which color key 
//                is being set. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDCKEY_COLORSPACE -
//                    The key being set is a range of color values rather 
//                    than a single color. 
//                  DDCKEY_DESTBLT -
//                    The key being set is the destination color key for 
//                    blits. 
//                  DDCKEY_DESTOVERLAY -
//                    The key being set is the destination color key for 
//                    overlays. 
//                  DDCKEY_SRCBLT -
//                    The key being set is the source color key for blits. 
//                  DDCKEY_SRCOVERLAY -
//                    The key being set is the source color key for overlays. 
//              pColorKey - 
//                The ColorKey parameter references a TDDColorKey component 
//                holding the color key values to be set. 
//                Set this parameter to NULL to remove the specified color key. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SetColorKey( dword pFlags, TDDColorKey* pColorKey )
{
// Original Function Definition
// HRESULT SetColorKey( 
//   DWORD dwFlags,             
//   LPDDCOLORKEY lpDDColorKey   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetColorKey()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->SetColorKey( (DWORD) pFlags, (pColorKey==NULL) ? NULL : pColorKey->Internal_DDCOLORKEY_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
if (pColorKey!=NULL) pColorKey->Internal_DDCOLORKEY_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::SetColorKey()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      SetLOD()
// Description: The TDx_DrawSurface::SetLOD method is used to define the 
//              maximum level of detail (LOD) that a managed mipmap should 
//              display. 
//              
//              Calling this method on a surface without 
//              DDSCAPS2_TEXTUREMANAGE set will merely result in a 
//              DDERR_INVALIDOBJECT error being returned. 
//              
//              For example, if this method set the MaxLOD parameter to 3, it 
//              would mean that only mipmaps of level 3 or smaller should be 
//              displayed. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT   
//              DDERR_INVALIDPARAMS 
// Params:      pMaxLOD - 
//                The MaxLOD parameter defines the maximum level of detail to 
//                be set for the mipmap chain. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SetLOD( dword pMaxLOD )
{
// Original Function Definition
// HRESULT SetLOD( 
//     DWORD dwMaxLOD 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetLOD()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->SetLOD( (DWORD) pMaxLOD );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::SetLOD()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      SetOverlayPosition()
// Description: The TDx_DrawSurface::SetOverlayPosition method will change 
//              the display coordinates of an overlay surface. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDPOSITION 
//              DDERR_NOOVERLAYDEST 
//              DDERR_NOTAOVERLAYSURFACE 
//              DDERR_OVERLAYNOTVISIBLE 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
// Params:      pX - 
//                The X parameter defines the new X axis display coordinate for 
//                the overlay. 
//              pY - 
//                The Y parameter defines the new Y axis display coordinate for 
//                the overlay. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SetOverlayPosition( long pX, long pY )
{
// Original Function Definition
// HRESULT SetOverlayPosition( 
//   LONG lX, 
//   LONG lY   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetOverlayPosition()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->SetOverlayPosition( (LONG) pX, (LONG) pY );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::SetOverlayPosition()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      SetPalette()
// Description: The TDx_DrawSurface::SetPalette method attaches a palette to 
//              a surface. 
//              
//              The change will be immediate, without regard to refresh 
//              timing. 
//              
//              The initial call to this method will increment the palette's 
//              reference count but further calls associating it with the 
//              same surface will not further affect the reference count. 
//              
//              Passing NULL to the Palette parameter removes the palette and 
//              decrements the palettes reference count. If the surface is 
//              released before the palette is removed, the palettes 
//              reference count will automatically be decremented. It is the 
//              applications responsibility to release further references to 
//              the palette if it is no longer needed. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDPIXELFORMAT 
//              DDERR_INVALIDSURFACETYPE 
//              DDERR_NOEXCLUSIVEMODE 
//              DDERR_NOPALETTEATTACHED 
//              DDERR_NOPALETTEHW 
//              DDERR_NOT8BITCOLOR 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
// Params:      pPalette - 
//                The Palette parameter references the palette that is to be 
//                attached. 
//                Set this parameter to NULL to detach the current palette. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SetPalette( TDx_DrawPalette* pPalette )
{
// Original Function Definition
// HRESULT SetPalette( 
//   LPDIRECTDRAWPALETTE lpDDPalette   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetPalette()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->SetPalette( (pPalette==NULL) ? NULL : pPalette->Internal_LPDIRECTDRAWPALETTE );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::SetPalette()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      SetPriority()
// Description: The TDx_DrawSurface::SetPriority method will define the 
//              management priority level for a texture. 
//              
//              This method only works with managed textures, which are 
//              removed in order of the least recently used texture first. 
//              The priority level indicates which texture will be removed 
//              first if two textures have the same "last use" time stamp. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with the following value: 
//              DDERR_INVALIDOBJECT 
// Params:      pPriority - 
//                The Priority parameter defines the new texture-management 
//                priority to be set for the texture. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SetPriority( dword pPriority )
{
// Original Function Definition
// HRESULT SetPriority( 
//   DWORD dwPriority 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetPriority()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->SetPriority( (DWORD) pPriority );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::SetPriority()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      SetPrivateData()
// Description: The TDx_DrawSurface::SetPrivateData method will associate 
//              application specific data with the surface. 
//              
//              Multiple sets of data may be associated with a surface. 
//              
//              The memory referenced by the Data parameter is not managed by 
//              TDx_Draw, so if the buffer was dynamically allocated, it is 
//              the applications responsibility to free the memory. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_OUTOFMEMORY 
// Params:      pTag - 
//                The Tag parameter references the GUID of the private data 
//                that is to be set. 
//              pData - 
//                The Data parameter references the buffer holding the private 
//                data that is to be associated with the surface. 
//              pSize - 
//                The Size parameter defines the size, in bytes, of the buffer 
//                referenced by the Data parameter of this method. 
//              pFlags - 
//                The Flags parameter defines flags indicating the type of data 
//                being associated and its lifetime. 
//                The described effect applies when the flag is set. 
//                Setting no flags causes the data to be stored in a buffer 
//                allocated by TDx_Draw, which will be freed when appropriate. 
//                Flags:
//                  DDSPD_IUNKNOWNPOINTER -
//                    The information referenced by the Data parameter of 
//                    this method references an IUnknown interface. 
//                    The interface's reference count will be incremented and 
//                    then decremented when the data is no longer needed. 
//                  DDSPD_VOLATILE -
//                    The data being associated will only remain valid until 
//                    the current state of the surface changes. 
//                    Attempts to retrieve the data after the surface has 
//                    changed will return DDERR_EXPIRED. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SetPrivateData( REFGUID pTag, void* pData, dword pSize, dword pFlags )
{
// Original Function Definition
// HRESULT SetPrivateData( 
//   REFGUID guidTag, 
//   LPVOID  lpData, 
//   DWORD   cbSize, 
//   DWORD   dwFlags 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetPrivateData()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pData==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::SetPrivateData()", "TDX_BADPARAMS", "'pData' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->SetPrivateData( pTag, (LPVOID) pData, (DWORD) pSize, (DWORD) pFlags );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::SetPrivateData()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      SetSurfaceDesc()
// Description: The TDx_DrawSurface::SetSurfaceDesc method will modify the 
//              surface description of an existing surface. 
//              
//              Surface data and pixel formats can currently only be set for 
//              explicitly created system memory surfaces. 
//              
//              The application must allocate the new surface memory and thus 
//              must deallocate it also. 
//              
//              The surface memory allocated by TDx_Draw when the surface was 
//              originally created will be released. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDOBJECT 
//              DDERR_SURFACELOST 
//              DDERR_SURFACEBUSY 
//              DDERR_INVALIDSURFACETYPE 
//              DDERR_INVALIDPIXELFORMAT 
//              DDERR_INVALIDCAPS 
//              DDERR_UNSUPPORTED 
//              DDERR_GENERIC 
// Params:      pSD - 
//                The SD parameter references a TDDSurfaceDesc component 
//                holding the surface description to be set. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::SetSurfaceDesc( TDDSurfaceDesc* pSD )
{
// Original Function Definition
// HRESULT SetSurfaceDesc( 
//   LPDDSURFACEDESC2 lpddsd2,   
//   DWORD dwFlags             
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetSurfaceDesc()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pSD==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::SetSurfaceDesc()", "TDX_BADPARAMS", "'pSD' cannot be 'NULL'");
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->SetSurfaceDesc( pSD->Internal_DDSURFACEDESC2_Ptr, 0 );
    }
catch (...)
    {
    }

// Translate Data returned from Function
pSD->Internal_DDSURFACEDESC2_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::SetSurfaceDesc()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      Unlock()
// Description: The TDx_DrawSurface::Unlock method will unlock surface memory 
//              that was locked using TDx_DrawSurface::Lock(). 
//              
//              It is possible to hold locks on different regions of the same 
//              surface, thus it is important that the contents of the Rect 
//              parameter be the same as was passed in the Rect parameter of 
//              the corresponding TDx_DrawSurface::Lock(). 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_GENERIC 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDRECT 
//              DDERR_NOTLOCKED 
//              DDERR_SURFACELOST 
// Params:      pSurfaceData - 
//                The SurfaceData parameter references a TRect defining the 
//                portion of the surface that is to be unlocked. 
//                Set this parameter to NULL only when the DestRect parameter 
//                of TDx_DrawSurface::Lock() was also set to NULL when the 
//                surface was locked. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::Unlock( TRect* pSurfaceData )
{
// Original Function Definition
// HRESULT Unlock( 
//   LPRECT lpRect 
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::Unlock()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Translate Parameters before calling Original Function
RECT TempSurfaceData;
LPRECT TempSurfaceData_Ptr;
if (pSurfaceData==NULL)
    {
    TempSurfaceData_Ptr = NULL;
    }
 else
    {
    TempSurfaceData.top = pSurfaceData->Top;
    TempSurfaceData.left = pSurfaceData->Left;
    TempSurfaceData.right = pSurfaceData->Right;
    TempSurfaceData.bottom = pSurfaceData->Bottom;
    TempSurfaceData_Ptr = &TempSurfaceData;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->Unlock( TempSurfaceData_Ptr );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::Unlock()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      UpdateOverlay()
// Description: The TDx_DrawSurface::UpdateOverlay method will reposition 
//              and/or modify an overlay surface. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_DEVICEDOESNTOWNSURFACE 
//              DDERR_GENERIC 
//              DDERR_HEIGHTALIGN 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_INVALIDRECT 
//              DDERR_INVALIDSURFACETYPE 
//              DDERR_NOSTRETCHHW 
//              DDERR_NOTAOVERLAYSURFACE 
//              DDERR_OUTOFCAPS 
//              DDERR_SURFACELOST 
//              DDERR_UNSUPPORTED 
//              DDERR_XALIGN 
// Params:      pSrcRect - 
//                The SrcRect parameter references a TRect defining a region of 
//                the source surface that is being used for the overlay. 
//                
//                Set this parameter to NULL if the entire source surface is to 
//                be used and it conforms to driver boundary and size alignment 
//                restrictions. 
//                This parameter may also be NULL when hiding the overlay. 
//              pDestSurface - 
//                The DestSurface parameter references the surface being 
//                overlaid. 
//              pDestRect - 
//                The DestRect parameter references a TRect defining the region 
//                of destination surface that is to be overlaid. 
//                This parameter may be NULL when hiding the overlay. 
//              pFlags - 
//                The Flags parameter defines flags indicating overlay settings 
//                and effects. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDOVER_ADDDIRTYRECT -
//                    Add a dirty rectangle to the overlay. 
//                    Only useful when the overlay is being emulated. 
//                  DDOVER_ALPHADEST -
//                    The overlay is to be performed using the destination 
//                    surface's alpha information as the alpha channel. 
//                  DDOVER_ALPHADESTCONSTOVERRIDE -
//                    The overlay operation's destination alpha channel is 
//                    obtained from the TDDOverlayFX::AlphaDestConst 
//                    referenced by the OverlayFX parameter of this method. 
//                  DDOVER_ALPHADESTNEG -
//                    The destination surface will increase in transparency 
//                    as alpha values increase. 
//                  DDOVER_ALPHADESTSURFACEOVERRIDE -
//                    The overlay operation's destination alpha channel is 
//                    obtained from the TDDOverlayFX::SAlphaDest referenced 
//                    by the OverlayFX parameter of this method. 
//                  DDOVER_ALPHAEDGEBLEND -
//                    The overlay operation's alpha channel for alpha edge 
//                    blending is obtained from the 
//                    TDDOverlayFX::AlphaEdgeBlend referenced by the 
//                    OverlayFX parameter of this method. 
//                  DDOVER_ALPHASRC -
//                    The overlay is to be performed using the source 
//                    surface's alpha information as the alpha channel. 
//                  DDOVER_ALPHASRCCONSTOVERRIDE -
//                    The overlay operation's source alpha channel is 
//                    obtained from the TDDOverlayFX::AlphaSrcConst 
//                    referenced by the OverlayFX parameter of this method. 
//                  DDOVER_ALPHASRCNEG -
//                    The source surface will increase in transparency as 
//                    alpha values increase. 
//                  DDOVER_ALPHASRCSURFACEOVERRIDE -
//                    The overlay operation's source alpha channel is 
//                    obtained from the TDDOverlayFX::SAlphaSrc referenced by 
//                    the OverlayFX parameter of this method. 
//                  DDOVER_ARGBSCALEFACTORS -
//                    The TDDOverlayFX component referenced by the OverlayFX 
//                    parameter of this method contains valid ARGB scaling 
//                    factors. 
//                  DDOVER_AUTOFLIP -
//                    Autoflip to the next surface in the flip chain every 
//                    video port VSYNC. 
//                  DDOVER_BOB -
//                    Use the bob technique to prevent artifacts when 
//                    individually displaying the odd and even fields of the 
//                    video stream. 
//                  DDOVER_BOBHARDWARE -
//                    The performance of bob operations is hardware, rather 
//                    than software or emulation, based. 
//                    DDOVER_BOB must also be set. 
//                  DDOVER_DDFX -
//                    The special effects flag settings for this overlay 
//                    operation is obtained from the TDDOverlayFX::FX 
//                    referenced by the OverlayFX parameter of this method. 
//                  DDOVER_DEGRADEARGBSCALING -
//                    Degrade ARGB scaling factors to match the driver 
//                    capabilities if neccessary. 
//                  DDOVER_HIDE -
//                    The overlay will not be displayed until this method is 
//                    called with DDOVER_SHOW set. 
//                  DDOVER_INTERLEAVED -
//                    The surface memory is composed of interleaved fields. 
//                  DDOVER_KEYDEST -
//                    The overlay is to be performed using the destination 
//                    surface's color key. 
//                  DDOVER_KEYDESTOVERRIDE -
//                    The overlay operation's destination color key is 
//                    obtained from the TDDOverlayFX::DestColorKey referenced 
//                    by the OverlayFX parameter of this method. 
//                  DDOVER_KEYSRC -
//                    The overlay is to be performed using the source 
//                    surface's color key. 
//                  DDOVER_KEYSRCOVERRIDE -
//                    The overlay operation's source color key is obtained 
//                    from the TDDOverlayFX::SrcColorKey referenced by the 
//                    OverlayFX parameter of this method. 
//                  DDOVER_OVERRIDEBOBWEAVE -
//                    Decisions about the use of bob/weave techniques will 
//                    not be overridden by another component. 
//                  DDOVER_REFRESHALL -
//                    The entire emulated overlay surface should be redrawn. 
//                  DDOVER_REFRESHDIRTYRECTS -
//                    All dirty rectangles on the emulated overlay surface 
//                    should be redrawn. 
//                  DDOVER_SHOW -
//                    The overlay will be displayed until this method is 
//                    called with DDOVER_HIDE set. 
//              pOverlayFx - 
//                The OverlayFx parameter references a TDDOverlayFX component 
//                defining values and effects to be used for this overlay. 
//                DDOVER_DDFX should not be set if this parameter is NULL. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::UpdateOverlay( TRect* pSrcRect, TDx_DrawSurface* pDestSurface, TRect* pDestRect, dword pFlags, TDDOverlayFX* pOverlayFx )
{
// Original Function Definition
// HRESULT UpdateOverlay( 
//   LPRECT lpSrcRect,                       
//   LPDIRECTDRAWSURFACE7 lpDDDestSurface,   
//   LPRECT lpDestRect,                     
//   DWORD dwFlags,                         
//   LPDDOVERLAYFX lpDDOverlayFx             
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::UpdateOverlay()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pDestSurface==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::UpdateOverlay()", "TDX_BADPARAMS", "'pDestSurface' cannot be 'NULL'");
    return false;
    }

// Translate Parameters before calling Original Function
RECT TempSrcRect;
LPRECT TempSrcRect_Ptr;
if (pSrcRect==NULL)
    {
    TempSrcRect_Ptr = NULL;
    }
 else
    {
    TempSrcRect.top = pSrcRect->Top;
    TempSrcRect.left = pSrcRect->Left;
    TempSrcRect.right = pSrcRect->Right;
    TempSrcRect.bottom = pSrcRect->Bottom;
    TempSrcRect_Ptr = &TempSrcRect;
    }
RECT TempDestRect;
LPRECT TempDestRect_Ptr;
if (pDestRect==NULL)
    {
    TempDestRect_Ptr = NULL;
    }
 else
    {
    TempDestRect.top = pDestRect->Top;
    TempDestRect.left = pDestRect->Left;
    TempDestRect.right = pDestRect->Right;
    TempDestRect.bottom = pDestRect->Bottom;
    TempDestRect_Ptr = &TempDestRect;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->UpdateOverlay( TempSrcRect_Ptr, pDestSurface->Internal_LPDIRECTDRAWSURFACE7, TempDestRect_Ptr, (DWORD) pFlags, (pOverlayFx==NULL) ? NULL : pOverlayFx->Internal_DDOVERLAYFX_Ptr );
    }
catch (...)
    {
    }

// Translate Data returned from Function
if (pOverlayFx!=NULL) pOverlayFx->Internal_DDOVERLAYFX_Update();

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::UpdateOverlay()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    
    // Translate Errors to Events
    if ((fErrorValue==DDERR_SURFACELOST) && (FOnSurfaceLost))
        try {
            FOnSurfaceLost(this);
            }
        catch (...)
            {
            }

    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Method:      UpdateOverlayZOrder()
// Description: The TDx_DrawSurface::UpdateOverlayZOrder method will define 
//              the z-order for an overlay. 
//              
//              If the method call fails, the OnError event will be triggered 
//              with one of the following values: 
//              DDERR_INVALIDOBJECT 
//              DDERR_INVALIDPARAMS 
//              DDERR_NOTAOVERLAYSURFACE 
// Params:      pFlags - 
//                The Flags parameter defines flags indicating the z-order 
//                position of this overlay, relative to the reference overlay 
//                specified in the Reference parameter of this method. 
//                The described effect applies when the flag is set. 
//                Flags:
//                  DDOVERZ_INSERTINBACKOF -
//                    The overlay is to be positioned directly behind the 
//                    reference overlay. 
//                  DDOVERZ_INSERTINFRONTOF -
//                    The overlay is to be positioned directly in front of 
//                    the reference overlay. 
//                  DDOVERZ_MOVEBACKWARD -
//                    The overlay is to be moved one position backwards 
//                    relative to its current position. 
//                  DDOVERZ_MOVEFORWARD -
//                    The overlay is to be moved one position forwards 
//                    relative to its current position. 
//                  DDOVERZ_SENDTOBACK -
//                    The overlay is to be the backmost overlay. 
//                  DDOVERZ_SENDTOFRONT -
//                    The overlay is to be the foremost overlay. 
//              pReference - 
//                The Reference parameter references the surface to be used as 
//                a relative position. 
//                This parameter need only be set when using 
//                DDOVERZ_INSERTINBACKOF or DDOVERZ_INSERTINFRONTOF. 
// --------------------------------------------------------------------------
bool __fastcall TDx_DrawSurface::UpdateOverlayZOrder( dword pFlags, TDx_DrawSurface* pReference )
{
// Original Function Definition
// HRESULT UpdateOverlayZOrder( 
//   DWORD dwFlags,                       
//   LPDIRECTDRAWSURFACE7 lpDDSReference   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::UpdateOverlayZOrder()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
try {
    fErrorValue = (uint) fLPDIRECTDRAWSURFACE7->UpdateOverlayZOrder( (DWORD) pFlags, (pReference==NULL) ? NULL : pReference->Internal_LPDIRECTDRAWSURFACE7 );
    }
catch (...)
    {
    }

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError)
        try {
            FOnError( this, Name+"::UpdateOverlayZOrder()", TDx_Draw_Library_ErrorString(fErrorValue), TDx_Draw_Library_ErrorMessage(fErrorValue) );
            }
        catch (...)
            {
            }
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Internal Interface Access
// --------------------------------------------------------------------------
LPDIRECTDRAWSURFACE7 __fastcall TDx_DrawSurface::FGetInternal_LPDIRECTDRAWSURFACE7()
{
return fLPDIRECTDRAWSURFACE7;
}
// --------------------------------------------------------------------------
LPDIRECTDRAWSURFACE7* __fastcall TDx_DrawSurface::FGetInternal_LPDIRECTDRAWSURFACE7_Ptr()
{
return &fLPDIRECTDRAWSURFACE7;
}
// --------------------------------------------------------------------------
void __fastcall TDx_DrawSurface::FSetInternal_LPDIRECTDRAWSURFACE7( LPDIRECTDRAWSURFACE7 pLPDIRECTDRAWSURFACE7 )
{
if (!fCreated)
    {
    fLPDIRECTDRAWSURFACE7 = pLPDIRECTDRAWSURFACE7;
    fCreated = (fLPDIRECTDRAWSURFACE7!=NULL);
    }
}
// --------------------------------------------------------------------------
void __fastcall TDx_DrawSurface::Internal_LPDIRECTDRAWSURFACE7_Update()
{
fCreated = (fLPDIRECTDRAWSURFACE7!=NULL);
}

// --------------------------------------------------------------------------