#ifndef TDx_DrawSurfaceH
#define TDx_DrawSurfaceH

// ==========================================================================
// File:         TDx_DrawSurface.H
// Authors:      BCB_Code_Generator v1.62,
//               Darren Dwyer (source code, documentation, demos, website),
//               Hugh Edwards (documentation, icons)
// Description:  This file defines the TDx_DrawSurface Component 
//
// "TDx_Draw_Library v1.62"
// (c) 2002 BCB-Tools.com Pty. Ltd., Sydney, Australia.
// All Rights Reserved.
//
// Refer to the 'Licence.Txt' file for licencing & copyright information.
// ==========================================================================

// --------------------------------------------------------------------------
// #includes
// --------------------------------------------------------------------------
#include <vcl\SysUtils.hpp>
#include <vcl\Controls.hpp>
#include <vcl\Classes.hpp>
#include <vcl\Forms.hpp>
// --------------------------------------------------------------------------
#include "TDx_Library_Defns.H"
#include "TDx_Library_Functions.H"
// --------------------------------------------------------------------------
#include "TDx_Draw_Library_Defns.H"
#include "TDx_Draw_Library_Functions.H"
// --------------------------------------------------------------------------
// external classes used by the TDx_DrawSurface component.
class TDx_Draw;
class TDDSurfaceDesc;
// --------------------------------------------------------------------------
// external classes used by TDx_DrawSurface methods.
class TDx_DrawSurface;
class TDDBltFX;
class TDDSCaps;
class TDx_DrawClipper;
class TDDColorKey;
class TDx_DrawPalette;
class TDDPixelFormat;
class TDDOverlayFX;

// --------------------------------------------------------------------------
// --------------------------------------------------------------------------
// Definition for the OnEnumAttachedSurfaces callback event.
typedef	__fastcall void	(__closure*     TDx_EnumAttachedSurfacesCallback) 
                        ( TObject*      Sender, 
                          TDx_DrawSurface* Surface, 
                          TDDSurfaceDesc* SurfaceDesc, 
                          void*         Context, 
                          bool&         Finished ); 

// Definition for the OnEnumOverlayZOrders callback event.
typedef	__fastcall void	(__closure*     TDx_EnumOverlayZOrdersCallback) 
                        ( TObject*      Sender, 
                          TDx_DrawSurface* Surface, 
                          TDDSurfaceDesc* SurfaceDesc, 
                          void*         Context, 
                          bool&         Finished ); 

// ==========================================================================
// Class:       TDx_DrawSurface
// Description: The TDx_DrawSurface component wraps the DirectX 
//              IDirectDrawSurface7 interface, which is used for working with 
//              surfaces and surface related system variables. 
//              
//              It is used to interact with the large variety of tasks and 
//              information relating to the manipulation of surfaces, which 
//              are after all, the means by which all visual effects are 
//              displayed for the user. 
//              
//              These tasks include: 
//              
//              Initializing a manually created surface, determining whether 
//              a surface has lost its allocated memory and restoring that 
//              memory if neccessary. 
//              
//              The addition, removal, retrieval and enumeration of surfaces 
//              within a flip chain or complex surface construct like a 
//              cubemap or mipmap. 
//              Determining the blitter status and blitting using normal or 
//              bltfast techniques. 
//              
//              Retrieval and definition of the color keys, palettes and 
//              clippers associated with a surface. 
//              Acquisition and release of the GDI compatible device context 
//              handles for the surface. 
//              Lock and unlock regions of a surface for blitting or page 
//              lock and unlock sections of memory for direct memory access 
//              (DMA) blits. 
//              Flipping to the next surface in a flip chain or determining 
//              the status of the last flip. 
//              
//              Retrieval of the underlying IDirectDraw7 interface used to 
//              create the surface. 
//              Change or retrieve the uniqueness value associated with the 
//              surface. 
//              Retrieve the capabilities, pixel format or description of a 
//              surface and modify an explicitly allocated surface's 
//              description. 
//              
//              Free, define or retrieve application specific information 
//              associated with the surface. 
//              Change or retrieve an overlays display parameters and 
//              position. 
// ==========================================================================
#if (__BORLANDC__ >= 0x0530) // BCB Version 3 +
class PACKAGE TDx_DrawSurface : public TComponent
{
// --------------------------------------------------------------------------
#else // BCB Version 1
class TDx_DrawSurface : public TComponent
{
#endif
// ==========================================================================
__published:
// ==========================================================================

    // ----------------------------------------------------------------------
    // Event:       OnCreate()
    // Description: The OnCreate() event is triggered by the 
    //              TDx_DrawSurface::Create() method after it has 
    //              successfully created the internal LPDIRECTDRAWSURFACE7 
    //              used within the TDx_DrawSurface component. 
    //              
    //              Note that since this event is only called upon successful 
    //              creation, this event is an ideal place for code that is 
    //              to be activated only once, immediately upon the 
    //              successful creation of the LPDIRECTDRAWSURFACE7 
    //              interface. 
    //              
    //              For example, you could retrieve the TDx_DrawSurface 
    //              component's capabilities, Create() dependant components, 
    //              allocate memory, etc. 
    //              
    //              When used in conjunction with the 
    //              TDx_DrawSurface::OnDestroy() event, you can fully 
    //              automate and insulate your code on a per-component basis. 
    // ----------------------------------------------------------------------
    __property TDx_Event OnCreate = {read=FOnCreate, write=FOnCreate, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Event:       OnDestroy()
    // Description: The OnDestroy() event is triggered by the 
    //              TDx_DrawSurface::Destroy() method, just before the 
    //              TDx_DrawSurface internal LPDIRECTDRAWSURFACE7 interface 
    //              is destroyed. 
    //              
    //              Note: This event is an ideal place to place code that 
    //              reverses the results of the TDx_DrawSurface::OnCreate() 
    //              event. For example, assume you have already setup the 
    //              TDx_DrawSurface::OnCreate() event to retrieve the 
    //              component's capabilities, Create() a dependant component 
    //              and allocate some memory; 
    //              You can then fully automate and insulate your code on a 
    //              per-component basis by placing code in the 
    //              TDx_DrawSurface::OnDestroy() event to deallocate memory, 
    //              Destroy() the dependant components and, when required, 
    //              destroy the capabilities component. 
    // ----------------------------------------------------------------------
    __property TDx_Event OnDestroy = {read=FOnDestroy, write=FOnDestroy, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Event:       OnError()
    // Description: The OnError event is called when an error occurs in the 
    //              TDx_DrawSurface component. 
    // ----------------------------------------------------------------------
    __property TDx_Error OnError = {read=FOnError, write=FOnError, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Event:       OnSurfaceLost()
    // Description: The OnSurfaceLost event is automatically called when 
    //              various TDx_DrawSurface methods determine that the 
    //              surface is lost. 
    //              This event is ideal for restoring a lost surface to its 
    //              previous state. 
    // ----------------------------------------------------------------------
    __property TDx_Event OnSurfaceLost = {read=FOnSurfaceLost, 
    write=FOnSurfaceLost, nodefault}; 

    // ----------------------------------------------------------------------
    // Callback:    OnEnumAttachedSurfaces()
    // Description: The OnEnumAttachedSurfaces callback is used to process 
    //              information returned by the 
    //              TDx_DrawSurface::EnumAttachedSurfaces method. 
    //              Set the Finished parameter to halt the enumeration 
    //              process. 
    // ----------------------------------------------------------------------
    __property TDx_EnumAttachedSurfacesCallback OnEnumAttachedSurfaces = 
    {read=FOnEnumAttachedSurfaces, write=FOnEnumAttachedSurfaces, nodefault}; 

    // ----------------------------------------------------------------------
    // Callback:    OnEnumOverlayZOrders()
    // Description: The OnEnumOverlayZOrders callback is used to process 
    //              information returned by the 
    //              TDx_DrawSurface::EnumOverlayZOrders method. 
    //              Set the Finished parameter to halt the enumeration 
    //              process. 
    // ----------------------------------------------------------------------
    __property TDx_EnumOverlayZOrdersCallback OnEnumOverlayZOrders = 
    {read=FOnEnumOverlayZOrders, write=FOnEnumOverlayZOrders, nodefault}; 

// ==========================================================================
public:
// ==========================================================================

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    __property bool Created = { read=FGetCreated, write=FSetCreated, 
    default=false }; 

    // ----------------------------------------------------------------------
    // 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 
    // ----------------------------------------------------------------------
    __property HRESULT ErrorValue = { read=FGetErrorValue, 
    write=FSetErrorValue, default=DD_OK }; 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall AddAttachedSurface( TDx_DrawSurface* 
    pAttachedSurface ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Blt( TRect* pDestRect, TDx_DrawSurface* 
    pSrcSurface, TRect* pSrcRect, dword pFlags, TDDBltFX* pBltFx ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall BltFast( dword pX, dword pY, TDx_DrawSurface* 
    pSrcSurface, TRect* pSrcRect, dword pTrans ); 

    // ----------------------------------------------------------------------
    // 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 
    // ----------------------------------------------------------------------
    virtual bool __fastcall ChangeUniquenessValue(); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Create( TDDSurfaceDesc* pSurfaceDesc, TDx_Draw* 
    pDraw ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall CreateFromFile( TDx_Draw* pDraw, AnsiString 
    pFileName ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall CreateFromSurface( TDx_Draw* pDraw, 
    TDx_DrawSurface* pSurface ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall DeleteAttachedSurface( TDx_DrawSurface* 
    pAttachedSurface ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Destroy(); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall EnumAttachedSurfaces( void* pContext ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall EnumOverlayZOrders( dword pFlags, void* pContext 
    ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Flip( TDx_DrawSurface* pSurfaceTargetOverride, 
    dword pFlags ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall FreePrivateData( REFGUID pTag ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetAttachedSurface( TDDSCaps* pSCaps, 
    TDx_DrawSurface* pAttachedSurface ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual HRESULT __fastcall GetBltStatus( dword pFlags ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetCaps( TDDSCaps* pSCaps ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetClipper( TDx_DrawClipper* pClipper ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetColorKey( dword pFlags, TDDColorKey* pColorKey 
    ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetDC( HDC* pDC ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetDDInterface( void** pDD ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetFlipStatus( dword pFlags ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetLOD( dword* pMaxLOD ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetOverlayPosition( long* pX, long* pY ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetPalette( TDx_DrawPalette* pPalette ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetPixelFormat( TDDPixelFormat* pPixelFormat ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetPriority( dword* pPriority ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual HRESULT __fastcall GetPrivateData( REFGUID pTag, void* pBuffer, 
    dword* pBufferSize ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetSurfaceDesc( TDDSurfaceDesc* pSurfaceDesc ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetUniquenessValue( dword* pValue ); 

    // ----------------------------------------------------------------------
    // 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 
    // ----------------------------------------------------------------------
    virtual bool __fastcall IsLost(); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall LoadFromFile( TDx_Draw* pDraw, AnsiString 
    pFileName ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall LoadFromSurface( TDx_Draw* pDraw, 
    TDx_DrawSurface* pSurface ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Lock( TRect* pDestRect, TDDSurfaceDesc* 
    pSurfaceDesc, dword pFlags ); 

    // ----------------------------------------------------------------------
    // 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 
    // ----------------------------------------------------------------------
    virtual bool __fastcall PageLock(); 

    // ----------------------------------------------------------------------
    // 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 
    // ----------------------------------------------------------------------
    virtual bool __fastcall PageUnlock(); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall ReleaseDC( HDC pDC ); 

    // ----------------------------------------------------------------------
    // 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 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Restore(); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SaveToFile( TDx_Draw* pDraw, AnsiString pFileName 
    ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetClipper( TDx_DrawClipper* pClipper ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetColorKey( dword pFlags, TDDColorKey* pColorKey 
    ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetLOD( dword pMaxLOD ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetOverlayPosition( long pX, long pY ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetPalette( TDx_DrawPalette* pPalette ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetPriority( dword pPriority ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetPrivateData( REFGUID pTag, void* pData, dword 
    pSize, dword pFlags ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetSurfaceDesc( TDDSurfaceDesc* pSD ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Unlock( TRect* pSurfaceData ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall UpdateOverlay( TRect* pSrcRect, TDx_DrawSurface* 
    pDestSurface, TRect* pDestRect, dword pFlags, TDDOverlayFX* pOverlayFx ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall UpdateOverlayZOrder( dword pFlags, 
    TDx_DrawSurface* pReference ); 

    // ----------------------------------------------------------------------
    // Constructor() and Destructor()
    // ----------------------------------------------------------------------
    __fastcall TDx_DrawSurface(TComponent* Owner); 
    virtual __fastcall ~TDx_DrawSurface(); 

    // ----------------------------------------------------------------------
    // The following properties and methods are used internally by 
    // TDx_Draw_Library and should not be used. 
    // ----------------------------------------------------------------------
    __property LPDIRECTDRAWSURFACE7 Internal_LPDIRECTDRAWSURFACE7 = { 
    read=FGetInternal_LPDIRECTDRAWSURFACE7, 
    write=FSetInternal_LPDIRECTDRAWSURFACE7, nodefault }; 
    __property LPDIRECTDRAWSURFACE7* Internal_LPDIRECTDRAWSURFACE7_Ptr = { 
    read=FGetInternal_LPDIRECTDRAWSURFACE7_Ptr, nodefault }; 
    void __fastcall Internal_LPDIRECTDRAWSURFACE7_Update(); 
    __property LPDIRECTDRAWSURFACE Internal_LPDIRECTDRAWSURFACE = { 
    read=FGetInternal_LPDIRECTDRAWSURFACE, 
    write=FSetInternal_LPDIRECTDRAWSURFACE, nodefault }; 
    __property LPDIRECTDRAWSURFACE* Internal_LPDIRECTDRAWSURFACE_Ptr = { 
    read=FGetInternal_LPDIRECTDRAWSURFACE_Ptr, nodefault }; 
    void __fastcall Internal_LPDIRECTDRAWSURFACE_Update(); 

// ==========================================================================
protected:
// ==========================================================================

    // ----------------------------------------------------------------------
    // Property Access Methods
    // ----------------------------------------------------------------------
    bool __fastcall FGetCreated(); 
    void __fastcall FSetCreated( bool pCreated ); 
    HRESULT __fastcall FGetErrorValue(); 
    void __fastcall FSetErrorValue( HRESULT pErrorValue ); 

// ==========================================================================
private:
// ==========================================================================

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    static HRESULT __stdcall Internal_EnumAttachedSurfacesCallback( 
    LPDIRECTDRAWSURFACE7 pDDSurface, LPDDSURFACEDESC2 pDDSurfaceDesc, LPVOID 
    pContext ); 

    // ----------------------------------------------------------------------
    // 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. 
    // ----------------------------------------------------------------------
    static HRESULT __stdcall Internal_EnumOverlayZOrdersCallback( 
    LPDIRECTDRAWSURFACE7 pDDSurface, LPDDSURFACEDESC2 pDDSurfaceDesc, LPVOID 
    pContext ); 

    // ----------------------------------------------------------------------
    // Internal Interface Access
    // ----------------------------------------------------------------------
    LPDIRECTDRAWSURFACE7 __fastcall FGetInternal_LPDIRECTDRAWSURFACE7(); 
    void __fastcall FSetInternal_LPDIRECTDRAWSURFACE7( LPDIRECTDRAWSURFACE7 
    pLPDIRECTDRAWSURFACE7 ); 
    LPDIRECTDRAWSURFACE7* __fastcall FGetInternal_LPDIRECTDRAWSURFACE7_Ptr(); 
    LPDIRECTDRAWSURFACE __fastcall FGetInternal_LPDIRECTDRAWSURFACE(); 
    void __fastcall FSetInternal_LPDIRECTDRAWSURFACE( LPDIRECTDRAWSURFACE 
    pLPDIRECTDRAWSURFACE ); 
    LPDIRECTDRAWSURFACE* __fastcall FGetInternal_LPDIRECTDRAWSURFACE_Ptr(); 

    // ----------------------------------------------------------------------
    // Property Variables 
    // ----------------------------------------------------------------------
    bool fCreated; 
    HRESULT fErrorValue; 

    // ----------------------------------------------------------------------
    // Interface Variables 
    // ----------------------------------------------------------------------
    LPDIRECTDRAWSURFACE7 fLPDIRECTDRAWSURFACE7; 
    LPDIRECTDRAWSURFACE fLPDIRECTDRAWSURFACE; 

    // ----------------------------------------------------------------------
    // Event Variables
    // ----------------------------------------------------------------------
    TDx_Event FOnCreate;
    TDx_Event FOnDestroy;
    TDx_Error FOnError;
    TDx_Event FOnSurfaceLost;

    // ----------------------------------------------------------------------
    // Callback Variables
    // ----------------------------------------------------------------------
    TDx_EnumAttachedSurfacesCallback FOnEnumAttachedSurfaces;
    TDx_EnumOverlayZOrdersCallback FOnEnumOverlayZOrders;

};
// --------------------------------------------------------------------------
#endif
// --------------------------------------------------------------------------