#ifndef TDx_DrawH #define TDx_DrawH // ========================================================================== // // File: TDx_Draw.H // Created: 12th February 2009 // Author: BCB_Code_Generator v2.10, // Darren John Dwyer // ( // data entry, // source code, // documentation, // help files, // project files, // tutorials, // demos, // website // ) // // Hugh Dunbar Edwards // ( // data entry creation, // documentation creation, // icon creation // ) // // Description: This file defines the TDx_Draw Component // // "TDx_Library v1.90" // "TDx_Draw_Library v1.90" // // (c) 2009 Darren John Dwyer, Australia. // All Rights Reserved. // // Refer to the 'License.Txt' file for licencing & copyright information. // // ========================================================================== // -------------------------------------------------------------------------- #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 TDx_Draw methods. class TDx_DrawClipper; class TDx_DrawPalette; class TDDSurfaceDesc; class TDx_DrawSurface; class TDDSCaps; class TDDCaps; class TDDDeviceIdentifier; // -------------------------------------------------------------------------- // -------------------------------------------------------------------------- // Definition for the OnDDEnumerate callback event. typedef __fastcall void (__closure* TDx_DDEnumerateCallback) ( TObject* Sender, GUID* Guid, AnsiString DriverDescription, AnsiString DriverName, void* Context, HMONITOR HMonitor, bool& Finished ); // Definition for the OnEnumDisplayModes callback event. typedef __fastcall void (__closure* TDx_EnumDisplayModesCallback) ( TObject* Sender, TDDSurfaceDesc* SurfaceDesc, void* Context, bool& Finished ); // Definition for the OnEnumSurfaces callback event. typedef __fastcall void (__closure* TDx_EnumSurfacesCallback) ( TObject* Sender, TDx_DrawSurface* Surface, TDDSurfaceDesc* SurfaceDesc, void* Context, bool& Finished ); // ========================================================================== // Class: TDx_Draw // Class Type: Interface // Description: The TDx_Draw component wraps the DirectX IDirectDraw7 // interface, which is the main DirectDraw interface. // // It can be used to set and check the cooperative level between // the operating system and the application, create several // other components and set or retrieve values relating to the // available capabilities. // // It also creates or duplicates surface's of various kinds; it // can create clippers to be used when blitting or overlaying; // and it can create palette's to be associated with a surface. // // It will also enumerate such things as the available display // modes and existing or potential surfaces meeting a given // description. // // Other functions of TDx_Draw include the retrieval of // properties such as the available video memory, hardware and // software capabilities, display mode, monitor frequency, // current scan line or vertical blank status, supported FourCC // codes and information identifying the specific display // hardware being used. // // There are also methods for initializing manually created // TDx_Draw components, retrieving the GDI surface or a device // context, restoring the display mode or the memory for all // surfaces, returning the primary surface to the GDI and // waiting until the vertical blank occurs. // ========================================================================== #if (__BORLANDC__ >= 0x0530) // BCB Version 3 + class PACKAGE TDx_Draw : public TComponent { // -------------------------------------------------------------------------- #else // BCB Version 1 class TDx_Draw : public TComponent { #endif // ========================================================================== __published: // ========================================================================== // ---------------------------------------------------------------------- // Event: OnCreate() // Description: The OnCreate() event is triggered by the // TDx_Draw::Create() method after it has successfully // created the internal LPDIRECTDRAW7 used within the // TDx_Draw 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 LPDIRECTDRAW7 interface. // // For example, you could retrieve the TDx_Draw component's // capabilities, Create() dependant components, allocate // memory, etc. // // When used in conjunction with the TDx_Draw::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_Draw::Destroy() method, just before the TDx_Draw // internal LPDIRECTDRAW7 interface is destroyed. // // Note: This event is an ideal place to place code that // reverses the results of the TDx_Draw::OnCreate() event. // For example, assume you have already setup the // TDx_Draw::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_Draw::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_Draw component. // ---------------------------------------------------------------------- __property TDx_Error OnError = {read=FOnError, write=FOnError, nodefault}; // ---------------------------------------------------------------------- // Callback: OnDDEnumerate() // Description: The OnDDEnumerate callback is used to process information // returned by the TDx_Draw::DDEnumerate method. // Set the Finished parameter to halt the enumeration // process. // ---------------------------------------------------------------------- __property TDx_DDEnumerateCallback OnDDEnumerate = {read=FOnDDEnumerate, write=FOnDDEnumerate, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumDisplayModes() // Description: The OnEnumDisplayModes callback is used to process // information returned by the TDx_Draw::EnumDisplayModes // method. // Set the Finished parameter to halt the enumeration // process. // ---------------------------------------------------------------------- __property TDx_EnumDisplayModesCallback OnEnumDisplayModes = {read=FOnEnumDisplayModes, write=FOnEnumDisplayModes, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumSurfaces() // Description: The OnEnumSurfaces callback is used to process // information returned by the TDx_Draw::EnumSurfaces // method. // Set the Finished parameter to halt the enumeration // process. // ---------------------------------------------------------------------- __property TDx_EnumSurfacesCallback OnEnumSurfaces = {read=FOnEnumSurfaces, write=FOnEnumSurfaces, nodefault}; // ========================================================================== public: // ========================================================================== // ---------------------------------------------------------------------- // Property: Created // Description: The Created property is true if the internal // LPDIRECTDRAW7 used in this component has been // successfully created, otherwise Created is false. // // To create the internal LPDIRECTDRAW7, call the // TDx_Draw::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_Draw method or fget/fset. // eg. DD_OK or DDERR_SURFACELOST or TDX_ERROR // ---------------------------------------------------------------------- __property HRESULT ErrorValue = { read=FGetErrorValue, write=FSetErrorValue, default=DD_OK }; // ---------------------------------------------------------------------- // Method: Create() // Description: The Create() method is used to automatically create the // internal LPDIRECTDRAW7 interface used in the TDx_Draw // component and must be called before any methods of the // TDx_Draw component will function. // Params: pGuid - // The Guid parameter contains the address of a Guid // representing the display driver to be used for this // DirectDraw interface. // By specifying NULL for the Guid parameter, you can select // the current display device. Alternatively, specify a Guid // that has been retrieved by calling the // TDx_Draw::DDEnumerate() method. Finally, you can specify // one of the following flags, typically used for debugging // purposes: // Flags: // DDCREATE_EMULATIONONLY - // By passing this flag instead of a specific GUID, // DirectDraw will use software emulation for all // features and will not use any hardware features. // DDCREATE_HARDWAREONLY - // By passing this flag instead of a specific GUID, // DirectDraw will not use software emulation for any // features, it will only use those features available // in hardware. // After setting this flag, any attempts to use // features not available in hardware will fail with // the DDERR_UNSUPPORTED error. // ---------------------------------------------------------------------- virtual bool __fastcall Create( GUID* pGuid ); // ---------------------------------------------------------------------- // Method: CreateClipper() // Description: The TDx_Draw::CreateClipper method will create a clipper // that can be attached to a surface and used in // TDx_DrawSurface::Blt() and // TDx_DrawSurface::UpdateOverlay() operations. // // If you must use a clipper that is independent of a // TDx_Draw component, use the DirectDrawCreateClipper // function and pass in the // 'Internal_LPDIRECTDRAWCLIPPER_Ptr' property of a // TDx_DrawClipper component that has been placed on your // form. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_NOCOOPERATIVELEVELSET // DDERR_OUTOFMEMORY // Params: pClipper - // The Clipper parameter will reference the newly created // clipper if the method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall CreateClipper( TDx_DrawClipper* pClipper ); // ---------------------------------------------------------------------- // Method: CreatePalette() // Description: The TDx_Draw::CreatePalette method will create a palette // to be used by the TDx_Draw component calling this method. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_NOCOOPERATIVELEVELSET // DDERR_OUTOFMEMORY // DDERR_UNSUPPORTED // Params: pFlags - // The Flags parameter defines flags indicating the type of // index used to access the created palette's color table. // The described effect applies when the flag is set. // Flags: // DDPCAPS_1BIT - // The palette index will be 1 bit. // There will be 2 entries in the color table. // DDPCAPS_2BIT - // The palette index will be 2 bits. // There will be 4 entries in the color table. // DDPCAPS_4BIT - // The palette index will be 4 bits. // There will be 16 entries in the color table. // DDPCAPS_8BIT - // The palette index will be 8 bits. // There will be 256 entries in the color table. // DDPCAPS_8BITENTRIES - // The palette index will reference an 8 bit color // index. // This flag is only valid when one of the // DDPCAPS_1BIT, DDPCAPS_2BIT or DDPCAPS_4BIT flags // are set and the surface which is to use the new // palette has a bit depth of 8. // Each color entry is an 8 bit index into the // destination surface's 8 bpp palette. // DDPCAPS_ALLOW256 - // All 256 entries of the created palette may be // accessed. // Entry 0 and entry 255 on 8-bit palettes are // reserved for system use unless this flag is set. // DDPCAPS_ALPHA - // The peFlags member of the associated PALETTEENTRY // structure is to be interpreted as an 8-bit alpha // value. // Palettes with this capability may only be attached // to textures. // DDPCAPS_INITIALIZE - // The palette is to be initialized with the colors // referenced by the ColorArray parameter of this // method. // DDPCAPS_PRIMARYSURFACE - // The palette is attached to the primary surface. // Changes to the palette will have an immediate // effect on the display unless the DDPCAPS_VSYNC // capability is specified and supported. // DDPCAPS_PRIMARYSURFACELEFT - // The palette is attached to the primary surface for // the left eye. // Changes to the palette will have an immediate // effect on the left eye display unless the // DDPCAPS_VSYNC capability is specified and // supported. // DDPCAPS_VSYNC - // The palette can be modified synchronously with the // monitor's refresh rate. // pColorArray - // The ColorArray parameter references an array of 2, 4, 16, // or 256 PALETTEENTRY structures used to initialize the // palette being created. // pPalette - // The Palette parameter will reference the new palette if // this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall CreatePalette( dword pFlags, PALETTEENTRY* pColorArray, TDx_DrawPalette* pPalette ); // ---------------------------------------------------------------------- // Method: CreateSurface() // Description: The TDx_Draw::CreateSurface method will create a surface // to be used by the TDx_Draw component calling this method. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INCOMPATIBLEPRIMARY // DDERR_INVALIDCAPS // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_INVALIDPIXELFORMAT // DDERR_NOALPHAHW // DDERR_NOCOOPERATIVELEVELSET // DDERR_NODIRECTDRAWHW // DDERR_NOEMULATION // DDERR_NOEXCLUSIVEMODE // DDERR_NOFLIPHW // DDERR_NOMIPMAPHW // DDERR_NOOVERLAYHW // DDERR_NOZBUFFERHW // DDERR_OUTOFMEMORY // DDERR_OUTOFVIDEOMEMORY // DDERR_PRIMARYSURFACEALREADYEXISTS // DDERR_UNSUPPORTEDMODE // Params: pSurfaceDesc - // The SurfaceDesc parameter references a TDDSurfaceDesc // component describing the surface to be created. // Unused properties of the component referenced by this // parameter should be set to zero before this method is // called. // pSurface - // The Surface parameter will reference the newly created // surface if this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall CreateSurface( TDDSurfaceDesc* pSurfaceDesc, TDx_DrawSurface* pSurface ); // ---------------------------------------------------------------------- // Method: DDEnumerate() // Description: The TDx_Draw::DDEnumerate method scans all DirectDraw // devices installed on the system and calls the // OnDDEnumerate event for each device. // There is no need to write a manual callback function, // just place your code in the OnDDEnumerate event. // Params: pContext - // The Context parameter references an application defined // object to be passed to the callback function for each // device enumerated. // pFlags - // The Flags parameter defines flags indicating the scope // the enumeration is to employ. // The described effect applies when the flag is set. // A setting of 0 will enumerate the primary display device // and a non-display device if one is installed. // Flags: // DDENUM_ATTACHEDSECONDARYDEVICES - // Enumerate the primary device along with all display // devices attached to the desktop. // DDENUM_DETACHEDSECONDARYDEVICES - // Enumerate the primary device along with all display // devices not attached to the desktop. // DDENUM_NONDISPLAYDEVICES - // Enumerate all non-display devices. // This could be 3-D accelerators that have no 2-D // capabilities for example. // ---------------------------------------------------------------------- virtual bool __fastcall DDEnumerate( LPVOID pContext, DWORD pFlags ); // ---------------------------------------------------------------------- // Method: Destroy() // Description: The Destroy() method is used to automatically destroy the // internal LPDIRECTDRAW7 interface used in the TDx_Draw // 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: DuplicateSurface() // Description: The TDx_Draw::DuplicateSurface method will duplicate an // existing surface. // // The new surface will reference the same surface memory as // the existing surface and function in an identical manner // to the original. // // The surface memory will be released when there is no // longer anything referencing it. // Primary, 3-D or implicitly created surfaces cannot be // duplicated. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_CANTDUPLICATE // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_OUTOFMEMORY // DDERR_SURFACELOST // Params: pSurface - // The Surface parameter references an existing surface that // is to be duplicated. // pDupSurface - // The DupSurface parameter will reference the duplicate // surface if this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall DuplicateSurface( TDx_DrawSurface* pSurface, TDx_DrawSurface* pDupSurface ); // ---------------------------------------------------------------------- // Method: EnumDisplayModes() // Description: The TDx_Draw::EnumDisplayModes method will enumerate // display modes that are available from the current video // card and monitor combination. // // Calling this method triggers the // TDx_Draw::OnEnumDisplayModes() event. // // If this method call fails, the one of the following // values will be returned: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // Params: pFlags - // The Flags parameter defines flags indicating whether // refresh rate and mode13 are taken into account when // enumeration is being performed. // Typically, this parameter is set to 0 to ignore extra // options. // The described effect applies when the flag is set. // Flags: // DDEDM_REFRESHRATES - // Enumeration is to define display modes that have // different refresh rates as being unique. // DDEDM_STANDARDVGAMODES - // Enumerate Mode 13 as well as Mode X. // Refer to the DirectX SDK for details on "Mode X and // Mode 13 Display Modes" limitations. // pSurfaceDesc - // The SurfaceDesc parameter references a TDDSurfaceDesc // component to be compared to available display modes. // Set this parameter to NULL to enumerate all display // modes. // pContext - // The Context parameter references an application defined // object to be passed to the callback function for each // display mode enumerated. // Set this parameter to NULL if you do not need to pass any // further information to the TDx_Draw::EnumModesCallback() // event. // ---------------------------------------------------------------------- virtual bool __fastcall EnumDisplayModes( dword pFlags, TDDSurfaceDesc* pSurfaceDesc, void* pContext ); // ---------------------------------------------------------------------- // Method: EnumSurfaces() // Description: The TDx_Draw::EnumSurfaces method will enumerate any // existing or possible surfaces compatible with a specfied // surface description. // // Calling this method triggers the // TDx_Draw::OnEnumSurfaces() event. // // When DDENUMSURFACES_CANBECREATED is set in the Flags // parameter, an attempt is made to create a temporary // surface meeting the enumeration critera. // When DDENUMSURFACES_DOESEXIST is set in the Flags // parameter, the reference count of each enumerated surface // will be incremented. // // If you don't wish to utilize those surfaces, use // TDx_DrawSurface::Release() to remove them after each // enumeration is performed. // // 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 how the // enumeration is to employ the information referenced by // the SD parameter of this method. // The described effect applies when the flag is set. // Flags: // DDENUMSURFACES_ALL - // All surfaces that meet the search criterion will be // enumerated. // DDENUMSURFACES_DOESEXIST must also be set. // DDENUMSURFACES_CANBECREATED - // The first surface that meets the search criterion // and can be created will be enumerated. // DDENUMSURFACES_MATCH must also be set. // DDENUMSURFACES_DOESEXIST - // Only surfaces that already exist and meet the // search criterion will be enumerated. // DDENUMSURFACES_MATCH - // Only surfaces that match the surface description // referenced by the SD parameter of this method will // be enumerated. // DDENUMSURFACES_NOMATCH - // Only surfaces that do not match the surface // description referenced by the SD parameter of this // method will be enumerated. // pSurfaceDesc - // The SurfaceDesc parameter references a TDDSurfaceDesc // component defining the surface description to use for the // enumeration. // This parameter may be NULL when DDENUMSURFACES_ALL is set // in the Flags parameter of this method. // pContext - // The Context parameter references an application defined // object passed to the TDx_Draw::EnumSurfacesCallback() // event for each surface enumerated. // ---------------------------------------------------------------------- virtual bool __fastcall EnumSurfaces( dword pFlags, TDDSurfaceDesc* pSurfaceDesc, void* pContext ); // ---------------------------------------------------------------------- // Method: EvaluateMode() // Description: The TDx_Draw::EvaluateMode method is used in conjunction // with TDx_Draw::StartModeTest() to evaluate the maximum // refresh rate possible for each screen resolution using // the current combination of display adapter and EDID // monitor. // // Call TDx_Draw::StartModeTest() to establish a set of // testable resolutions and display the first video mode in // that set. TDx_Draw::EvaluateMode() can then be used to // step through the testable resolutions starting with the // highest supported refresh rate for a given resolution. As // soon as a given resolution passes the test any lower // refresh rates for that resolution are skipped. // // There is a 15 second timeout when the test is started or // when a mode is passed or failed. Calling // TDx_Draw::EvaluateMode() with the Flags parameter set to // 0 will retrieve the time remaining without interfering // with the current test. // // Test termination or mode changes only occur when // TDx_Draw::EvaluateMode() is called, but the current mode // will always be failed if the call comes after the timeout // period has passed. // // On completion, the following messages may be returned. // DDERR_TESTFINISHED // DDERR_NEWMODE // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_NOTFOUND // Params: pFlags - // The Flags parameter defines flags indicating the status // of the mode being tested. // The described effect applies when the flag is set. // Flags: // DDEM_MODEFAILED - // The video mode has failed or timed out at the // current refresh rate. // DDEM_MODEPASSED - // The video mode has passed the test at the current // refresh rate. // pSecondsUntilTimeout - // The SecondUntilTimout parameter will reference the time // remaining, in seconds, before the current mode is // automatically failed. // ---------------------------------------------------------------------- virtual HRESULT __fastcall EvaluateMode( dword pFlags, dword* pSecondsUntilTimeout ); // ---------------------------------------------------------------------- // Method: FlipToGDISurface() // Description: The TDx_Draw::FlipToGDISurface method will set the // surface currently used by the GDI to be the primary // surface. // // This is useful for ensuring that the display memory the // GDI is using is visible to the user at the end of a page // flipping application or making the GDI surface the // primary surface so normal windows, such as dialog boxes, // can be displayed in full screen mode. // The hardware must have the DDCAPS2_CANRENDERWINDOWED // capability to perform the latter action. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_NOTFOUND // ---------------------------------------------------------------------- virtual bool __fastcall FlipToGDISurface(); // ---------------------------------------------------------------------- // Method: GetAvailableVidMem() // Description: The TDx_Draw::GetAvailableVidMem method will return the // total display memory available and also the amount of // display memory that is free for a specified type of // surface. // // This is only a snapshot of the current display memory // state and will change as surfaces are created and // released. Some display cards utilize the same memory for // different surface types, thus allocating one type of // surface may affect the amount of memory available for // another surface type. // // Surfaces with the DDSCAPS_VIDEOMEMORY flag set will // return the sum of local and non-local video memory on AGP // systems if the surface can be used for 3D textures. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDCAPS // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_NODIRECTDRAWHW // Params: pSCaps - // The SCaps parameter references a TDDSCaps component // defining the type of surface for which display memory // information is being requested. // pTotal - // The Total parameter will reference the total amount of // available display memory if this method returns // successfully. // pFree - // The Free parameter will reference the amount of display // memory available for allocation to a surface of the // specified type. // ---------------------------------------------------------------------- virtual bool __fastcall GetAvailableVidMem( TDDSCaps* pSCaps, dword* pTotal, dword* pFree ); // ---------------------------------------------------------------------- // Method: GetCaps() // Description: The TDx_Draw::GetCaps method will retrieve the hardware // and/or hardware emulation layer capabilities that are // available. // // You can pass NULL to either parameter, but not both. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // Params: pDriverCaps - // The DriverCaps parameter references a TDDCaps component // for holding the reported hardware capabilities if this // method returns successfully. // This parameter should be set to NULL if hardware // capabilities are not required. // pHELCaps - // The HELCaps parameter references a TDDCaps component for // holding the hardware emulation layer capabilities if this // method returns successfully. // This parameter should be set to NULL if hardware // emulation capabilities are not required. // ---------------------------------------------------------------------- virtual bool __fastcall GetCaps( TDDCaps* pDriverCaps, TDDCaps* pHELCaps ); // ---------------------------------------------------------------------- // Method: GetDeviceIdentifier() // Description: The TDx_Draw::GetDeviceIdentifier method provides // information uniquely identifying the device driver. // // The information this method retrieves can be used to // identify specific hardware so that problems relating to // that particular hardware may be dealt with. // // If the method call fails, the OnError event will be // triggered with the following value: // DDERR_INVALIDPARAMS // Params: pDeviceIdentifier - // The DeviceIdentifier parameter references a // TDDDeviceIdentifier component for holding the driver // details if this method returns successfully. // pFlags - // The Flags parameter defines a flag indicating which // information is to be retrieved. // The described effect applies when the flag is set. // Flags: // DDGDI_GETHOSTIDENTIFIER - // Retrieve information about the host, often 2-D, // hardware rather than the stacked secondary 3-D // adapter. // A stacked secondary 3-D adapter may appear to be // part of the host adapter, but often it may be // located on a separate card. // When this flag is not set information regarding the // secondary adapter will be retrieved. // ---------------------------------------------------------------------- virtual bool __fastcall GetDeviceIdentifier( TDDDeviceIdentifier* pDeviceIdentifier, dword pFlags ); // ---------------------------------------------------------------------- // Method: GetDisplayMode() // Description: The TDx_Draw::GetDisplayMode method will retrieve the // current display mode settings. // // Use TDx_Draw::RestoreDisplayMode() to restore the video // mode when your application terminates to avoid conflicts // in a multiprocess environment. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_UNSUPPORTEDMODE // Params: pSurfaceDesc - // The SurfaceDesc parameter will reference the current // display mode settings if this method returns // successfully. // TDx_Draw::RestoreDisplayMode() should be used to restore // display settings rather than using the information // returned by this method. // ---------------------------------------------------------------------- virtual bool __fastcall GetDisplayMode( TDDSurfaceDesc* pSurfaceDesc ); // ---------------------------------------------------------------------- // Method: GetFourCCCodes() // Description: The TDx_Draw::GetFourCCCodes will return the supported // FOURCC codes. // // The number of codes supported can also be retrieved by // this method. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // Params: pNumCodes - // The NumCodes parameter references the size of the array // referenced by the Codes parameter of this method. // When there is insufficient space to accommodate all the // codes, this parameter will be set to the total number of // codes and the array will contain all of the codes that // would fit. // pCodes - // The Codes parameter references an array for holding the // supported FOURCC codes if this method returns // successfully. // Setting this parameter to NULL will result in the // NumCodes parameter of this method being set to the number // of supported FOURCC codes. // ---------------------------------------------------------------------- virtual bool __fastcall GetFourCCCodes( dword* pNumCodes, dword* pCodes ); // ---------------------------------------------------------------------- // Method: GetGDISurface() // Description: The TDx_Draw::GetGDISurface method will retrieve the // surface the GDI is currently using as its primary // surface. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_NOTFOUND // Params: pGDISurface - // The GDISurface parameter will reference the surface the // GDI is using as its primary surface if this method // returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetGDISurface( TDx_DrawSurface* pGDISurface ); // ---------------------------------------------------------------------- // Method: GetMonitorFrequency() // Description: The TDx_Draw::GetMonitorFrequency method will retrieve // the monitor frequency. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_UNSUPPORTED // Params: pFrequency - // The Frequency parameter will reference the monitor // frequency, in Hertz, if this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetMonitorFrequency( dword* pFrequency ); // ---------------------------------------------------------------------- // Method: GetScanLine() // Description: The TDx_Draw::GetScanLine method will return the number // of the scan line currently being drawn. // // The scan line number is a zero based integer between 0, // the first scan line visible, and a number equal to the // number of the last visible scan line plus any additional // scan lines contained within the vertical blank. Thus, if // the screen resolution is 800 by 600 with 20 scan lines // during the vertical blank, the scan line number will // range from 0 to 619. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_UNSUPPORTED // DDERR_VERTICALBLANKINPROGRESS // Params: pScanLine - // The ScanLine parameter will reference the current scan // line number if this method returns successfully. // The value returned by this method will be a zero based // integer between 0 and the bottom of the display plus any // scan lines from the vertical blanking interval. // ---------------------------------------------------------------------- virtual bool __fastcall GetScanLine( dword* pScanLine ); // ---------------------------------------------------------------------- // Method: GetSurfaceFromDC() // Description: The TDx_Draw::GetSurfaceFromDC method will retrieve the // surface referenced by the specified device context // handle. // // Only surfaces that are already associated with the // TDx_Draw component calling this method may be retrieved. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_GENERIC // DDERR_INVALIDPARAMS // DDERR_OUTOFMEMORY // DDERR_NOTFOUND // Params: pDC - // The DC parameter references the handle of the display // device context for which the surface is to be retrieved. // pSurface - // The Surface parameter will reference the specified // surface if this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetSurfaceFromDC( HDC pDC, TDx_DrawSurface* pSurface ); // ---------------------------------------------------------------------- // Method: GetVerticalBlankStatus() // Description: The TDx_Draw::GetVerticalBlankStatus method will indicate // whether there is a vertical blank currently occuring. // // TDx_Draw::WaitForVerticalBlank() can be used to // synchronise with the vertical blank. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // Params: pIsInVB - // The IsInVB parameter will reference the current vertical // blank status if this method returns successfully. // TRUE when a vertical blank is occurring. // ---------------------------------------------------------------------- virtual bool __fastcall GetVerticalBlankStatus( bool* pIsInVB ); // ---------------------------------------------------------------------- // Method: RestoreAllSurfaces() // Description: TheTDx_Draw::RestoreAllSurfaces method will restore all // associated surfaces in creation order. // // This is equivilent to calling TDx_Draw::Restore() for // each surface. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // ---------------------------------------------------------------------- virtual bool __fastcall RestoreAllSurfaces(); // ---------------------------------------------------------------------- // Method: RestoreDisplayMode() // Description: The TDx_Draw::RestoreDisplayMode method will restore the // hardwares display mode settings to their original mode. // // If TDx_Draw::SetDisplayMode() has been called by an // exclusive mode application, the display mode is // automatically restored upon setting the cooperative level // back to normal. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_GENERIC // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_LOCKEDSURFACES // DDERR_NOEXCLUSIVEMODE // ---------------------------------------------------------------------- virtual bool __fastcall RestoreDisplayMode(); // ---------------------------------------------------------------------- // Method: SetCooperativeLevel() // Description: The TDx_Draw::SetCooperativeLevel method will define the // level of access an application has to system resources. // // Either the DDSCL_EXCLUSIVE or DDSCL_NORMAL flag must be // set. // // This method must be called by the thread that created the // application window and is used to determine if a full // screen or windowed application is required. Full screen // exclusive mode allows full utilisation of video hardware // capabilities. // // Normal mode precludes page flipping and changing the // primary surfaces pallete, multiple window applications // can be written by passing NULL as the window handle and // setting DDSCL_NORMAL. DirectDraw does not send activation // event messages to all of an applications windows, only // the top-level window. Child windows that require // activation event messages will have to be subclassed. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_EXCLUSIVEMODEALREADYSET // DDERR_HWNDALREADYSET // DDERR_HWNDSUBCLASSED // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_OUTOFMEMORY // Params: pWnd - // The Wnd parameter defines the top level window handle of // the application for which the cooperative levels are // being set. // If DDSCL_NORMAL is set in the Flags parameter then this // parameter may be NULL. // pFlags - // The Flags parameter defines flags indicating the // cooperative level settings for the application. // The described effect applies when the flag is set. // Flags: // DDSCL_ALLOWMODEX - // Mode X display modes may be used. // When this flag is set, DDSCL_EXCLUSIVE and // DDSCL_FULLSCREEN must also be set. // Refer to the DirectX SDK for details on "Mode X and // Mode 13 Display Modes" limitations. // DDSCL_ALLOWREBOOT - // CTRL+ALT+DEL may be used when DDSCL_EXCLUSIVE and // DDSCL_FULLSCREEN are set. // DDSCL_CREATEDEVICEWINDOW - // A default device window is to be created and // managed. // Applications can have one device window for each // display device. // Support for this flag only exists in Windows 98 and // Windows NT 2000. // DDSCL_EXCLUSIVE - // Requests exclusive level access for the // application. // DDSCL_FULLSCREEN must also be set. // DDSCL_FPUPRESERVE - // TDx_3D will preserve the FPU state by saving and // restoring its settings whenever it needs to modify // it. // DDSCL_FPUSETUP - // The floating point unit is likely to remain set for // optimal 3D performance to avoid the need for // explicitly setting it each time. // DDSCL_FULLSCREEN - // The exclusive mode application is responsible for // the primary surface. // DDSCL_EXCLUSIVE must also be set. The GDI can // effectively be ignored. // DDSCL_MULTITHREADED - // Requests multithread safe TDx_Draw behavior. // TDx_3D will take the global critical section more // frequently. // DDSCL_NORMAL - // The application functions via the regular Windows // handling routines. // When this flag is set, DDSCL_ALLOWMODEX, // DDSCL_EXCLUSIVE and DDSCL_FULLSCREEN may not be // set. // DDSCL_NOWINDOWCHANGES - // The application window will not be minimized or // restored on activation. // DDSCL_SETDEVICEWINDOW - // The Wnd parameter of this method contains the // handle of the device window to be set. // The DDSCL_SETFOCUSWINDOW flag cannot also be set. // Support for this flag only exists in Windows 98 and // Windows NT 2000. // DDSCL_SETFOCUSWINDOW - // The Wnd parameter of this method contains the // handle of the focus window. // DDSCL_SETDEVICEWINDOW cannot also be set. // Support for this flag only exists in Windows 98 and // Windows NT 2000. // ---------------------------------------------------------------------- virtual bool __fastcall SetCooperativeLevel( HWND pWnd, dword pFlags ); // ---------------------------------------------------------------------- // Method: SetDisplayMode() // Description: The TDx_Draw::SetDisplayMode method will set the mode of // the display hardware. // // Other applications changing the display mode will cause // the primary surface to be lost and result in // DDERR_SURFACELOST messages until the surface is recreated // to match the new display mode. // // This method must be called by the thread which created // the application window. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_GENERIC // DDERR_INVALIDMODE // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_LOCKEDSURFACES // DDERR_NOEXCLUSIVEMODE // DDERR_SURFACEBUSY // DDERR_UNSUPPORTED // DDERR_UNSUPPORTEDMODE // DDERR_WASSTILLDRAWING // Params: pWidth - // The Width parameter defines the width of the mode being // set. // pHeight - // The Height parameter defines the height of the mode being // set. // pBPP - // The BPP parameter defines the bit depth of the mode being // set. To determine the Pixel format used by the hardware, // use TDx_Draw::GetDisplayMode(), which will return the // pixel masks used. // pRefreshRate - // The RefreshRate parameter defines the refresh rate of the // mode being set. // Set this parameter to 0 to use the current refresh rate // setting. // pFlags - // The Flags parameter defines a flag indicating an // additional mode option. // The described effect applies when this flag is set. // Flags: // DDSDM_STANDARDVGAMODE - // Mode 13 will be set instead of Mode X 320x200x8 // mode. // When not setting Mode 13 this parameter should be // set to 0. // Refer to the DirectX SDK for details on "Mode X and // Mode 13 Display Modes" limitations. // ---------------------------------------------------------------------- virtual bool __fastcall SetDisplayMode( dword pWidth, dword pHeight, dword pBPP, dword pRefreshRate, dword pFlags ); // ---------------------------------------------------------------------- // Method: StartModeTest() // Description: The TDx_Draw::StartModeTest method will update the // refresh rate information in the system registry by // testing the current display adapter / EDID monitor // combination. // // Once the testable resolutions are defined using this // method, TDx_Draw::EvaluateMode() can be used to test each // resolution for the maximum refresh rate that can be // displayed. // // The changed registry settings may change the results // returned by TDx_Draw::EnumDisplayModes() when it is // called with DDEDM_REFRESHRATES set. // // No testing and a return value of DDERR_TESTFINISHED will // result if the monitor being tested is not EDID compliant. // // No modes will be tested if the EDID table does not // contain values higher than 60 Hz and refresh rates higher // than 100 Hz will only be tested if the EDID table // contains values higher than 85 Hz. // // Set the parameters to NULL, 0 and 0 to clear existing // refresh rate information from the registry. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_CURRENTLYNOTAVAIL // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_NOEXCLUSIVEMODE // DDERR_NOTFOUND // DDERR_TESTFINISHED // // Calling this method with DDSMT_ISTESTREQUIRED set may // return one of these values: // DDERR_NEWMODE // DDERR_NODRIVERSUPPORT // DDERR_NOMONITORINFORMATION // DDERR_TESTFINISHED // Params: pModesToTest - // The ModesToTest parameter references an array of SIZE // elements defining the screen resolutions to be tested. // pNumEntries - // The NumEntries parameter defines how many elements the // array referenced by the ModesToTest parameter contains. // pFlags - // The Flags parameter defines a flag indicating whether a // test should be initiated. // The described effect applies when the flag is set. // Flags: // DDSMT_ISTESTREQUIRED - // The method will return a value indicating whether // it is neccessary (or possible) to test the // resolutions referenced by the ModesToTest // parameter, without initiating any tests. // ---------------------------------------------------------------------- virtual HRESULT __fastcall StartModeTest( SIZE* pModesToTest, dword pNumEntries, dword pFlags ); // ---------------------------------------------------------------------- // Method: TestCooperativeLevel() // Description: The TDx_Draw::TestCooperativeLevel method is used to // determine if a program can restore/use its surfaces. // // A fullscreen exclusive application will receive // DDERR_NOEXCLUSIVEMODE if ALT-TAB is pressed. // // A minimised normal mode application will receive // DDERR_EXCLUSIVEMODEALREADYSET if another application has // exclusive mode. // // TDx_Draw::TestCooperativeLevel() should be used until // DD_OK is returned, before any operations are performed. // Use TApplication.ProcessMessages() to reduce CPU usage // during the TDx_Draw::TestCooperativeLevel() loop. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_EXCLUSIVEMODEALREADYSET // DDERR_NOEXCLUSIVEMODE // DDERR_WRONGMODE // ---------------------------------------------------------------------- virtual HRESULT __fastcall TestCooperativeLevel(); // ---------------------------------------------------------------------- // Method: WaitForVerticalBlank() // Description: The TDx_Draw::WaitForVerticalBlank method will help // synchronize an application with the VBI. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DDERR_INVALIDOBJECT // DDERR_INVALIDPARAMS // DDERR_UNSUPPORTED // DDERR_WASSTILLDRAWING // Params: pFlags - // The Flags parameter defines flags indicating which // portion of the vertical blank to wait for. // The described effect applies when the flag is set. // Flags: // DDWAITVB_BLOCKBEGIN - // The method will return at the start of the VBI. // DDWAITVB_BLOCKBEGINEVENT - // The event referenced by the Event parameter of this // method will be triggered at the start of the VBI. // Support for this flag is not currently available. // DDWAITVB_BLOCKEND - // The method will return at the end of the VBI. // ---------------------------------------------------------------------- virtual bool __fastcall WaitForVerticalBlank( dword pFlags ); // ---------------------------------------------------------------------- // Constructor() and Destructor() // ---------------------------------------------------------------------- __fastcall TDx_Draw(TComponent* Owner); virtual __fastcall ~TDx_Draw(); // ---------------------------------------------------------------------- // The following properties and methods are used internally by // TDx_Draw_Library and should not be used. // ---------------------------------------------------------------------- __property LPDIRECTDRAW7 Internal_LPDIRECTDRAW7 = { read=FGetInternal_LPDIRECTDRAW7, write=FSetInternal_LPDIRECTDRAW7, nodefault }; __property LPDIRECTDRAW7* Internal_LPDIRECTDRAW7_Ptr = { read=FGetInternal_LPDIRECTDRAW7_Ptr, nodefault }; void __fastcall Internal_LPDIRECTDRAW7_Update(); // ========================================================================== protected: // ========================================================================== // ---------------------------------------------------------------------- // Property: EnumSurfacesFlags // Description: The EnumSurfacesFlags property is used to store to the // last flags passed into the TDx_Draw::EnumSurfaces() // method, for use by the // TDx_Draw::Internal_DDEnumSurfacesCallback() method. // ---------------------------------------------------------------------- __property dword EnumSurfacesFlags = { read=FGetEnumSurfacesFlags, nodefault }; // ---------------------------------------------------------------------- // Property Access Methods // ---------------------------------------------------------------------- bool __fastcall FGetCreated(); void __fastcall FSetCreated( bool pCreated ); dword __fastcall FGetEnumSurfacesFlags(); HRESULT __fastcall FGetErrorValue(); void __fastcall FSetErrorValue( HRESULT pErrorValue ); // ========================================================================== private: // ========================================================================== // ---------------------------------------------------------------------- // Method: Internal_DDEnumerateCallback() // Description: The Internal_DDEnumerateCallback method is used // internally by the TDx_Draw_Library to redirect a standard // callback function to a BCB style event. It receives all // enumeration callbacks generated by the // TDx_Draw::DDEnumerate() method and on each enumeration // calls the TDx_Draw::OnDDEnumerate() event, translating // parameters between DirectX and BCB as required. // Params: pGuid - // The address of the unique identifier for the DirectDraw // Object. // pDriverDescription - // The Description of the driver for the currently // enumerated device. // pDriverName - // The name of the driver for the currently enumerated // device. // pContext - // Application defined data passed to the enumeration method // call. // pHMonitor - // Handle to the monitor for the currently enumerated // device. // ---------------------------------------------------------------------- static BOOL __stdcall Internal_DDEnumerateCallback( GUID* pGuid, LPSTR pDriverDescription, LPSTR pDriverName, LPVOID pContext, HMONITOR pHMonitor ); // ---------------------------------------------------------------------- // Method: Internal_EnumDisplayModesCallback() // Description: The Internal_EnumDisplayModesCallback method is used // internally by the TDx_Draw_Library to redirect a standard // callback function to a BCB style event. It receives all // enumeration callbacks generated by the // TDx_Draw::EnumDisplayModes() method and on each // enumeration calls the TDx_Draw::OnEnumDisplayModes() // event, translating parameters between DirectX and BCB as // required. // Params: pDDSurfaceDesc - // The DDSurfaceDesc parameter describes the monitor // frequency and the mode being enumerated. // pContext - // Application defined data passed to the enumeration method // call. // ---------------------------------------------------------------------- static HRESULT __stdcall Internal_EnumDisplayModesCallback( LPDDSURFACEDESC2 pDDSurfaceDesc, LPVOID pContext ); // ---------------------------------------------------------------------- // Method: Internal_EnumSurfacesCallback() // Description: The Internal_EnumSurfacesCallback method is used // internally by the TDx_Draw_Library to redirect a standard // callback function to a BCB style event. It receives all // enumeration callbacks generated by the // TDx_Draw::EnumSurfaces() method and on each enumeration // calls the TDx_Draw::OnEnumSurfaces() event, translating // parameters between DirectX and BCB as required. // Params: pDDSurface - // Contains a pointer to the DirectDrawSurface interface. // pDDSurfaceDesc - // The DDSurfaceDesc parameter describes the DDSurface // parameter. // pContext - // Application defined data passed to the enumeration method // call. // ---------------------------------------------------------------------- static HRESULT __stdcall Internal_EnumSurfacesCallback( LPDIRECTDRAWSURFACE7 pDDSurface, LPDDSURFACEDESC2 pDDSurfaceDesc, LPVOID pContext ); // ---------------------------------------------------------------------- // Internal Interface Access // ---------------------------------------------------------------------- LPDIRECTDRAW7 __fastcall FGetInternal_LPDIRECTDRAW7(); void __fastcall FSetInternal_LPDIRECTDRAW7( LPDIRECTDRAW7 pLPDIRECTDRAW7 ); LPDIRECTDRAW7* __fastcall FGetInternal_LPDIRECTDRAW7_Ptr(); // ---------------------------------------------------------------------- // Property Variables // ---------------------------------------------------------------------- bool fCreated; dword fEnumSurfacesFlags; HRESULT fErrorValue; // ---------------------------------------------------------------------- // Interface Variables // ---------------------------------------------------------------------- LPDIRECTDRAW7 fLPDIRECTDRAW7; // ---------------------------------------------------------------------- // Event Variables // ---------------------------------------------------------------------- TDx_Event FOnCreate; TDx_Event FOnDestroy; TDx_Error FOnError; // ---------------------------------------------------------------------- // Callback Variables // ---------------------------------------------------------------------- TDx_DDEnumerateCallback FOnDDEnumerate; TDx_EnumDisplayModesCallback FOnEnumDisplayModes; TDx_EnumSurfacesCallback FOnEnumSurfaces; }; // -------------------------------------------------------------------------- #endif // --------------------------------------------------------------------------