IDirectDrawSurface7 interface (ddraw.h)
Applications use the methods of the IDirectDrawSurface7 interface to create DirectDrawSurface objects and work with system-level variables. This section is a reference to the methods of this interface.
Inheritance
The IDirectDrawSurface7 interface inherits from the IUnknown interface. IDirectDrawSurface7 also has these types of members:
Methods
The IDirectDrawSurface7 interface has these methods.
| IDirectDrawSurface7::AddAttachedSurface Attaches the specified z-buffer surface to this surface. |
| IDirectDrawSurface7::AddOverlayDirtyRect The IDirectDrawSurface7::AddOverlayDirtyRect method is not currently implemented. |
| IDirectDrawSurface7::Blt Performs a bit block transfer (bitblt). This method does not support z-buffering or alpha blending during bitblt operations. |
| IDirectDrawSurface7::BltBatch The IDirectDrawSurface7::BltBatch method is not currently implemented. |
| IDirectDrawSurface7::BltFast Performs a source copy bitblt or transparent bitblt by using a source color key or destination color key. |
| IDirectDrawSurface7::ChangeUniquenessValue Manually updates the uniqueness value for this surface. |
| IDirectDrawSurface7::DeleteAttachedSurface Detaches one or more attached surfaces. |
| IDirectDrawSurface7::EnumAttachedSurfaces Enumerates all the surfaces that are attached to this surface. |
| IDirectDrawSurface7::EnumOverlayZOrders Enumerates the overlay surfaces on the specified destination. You can enumerate the overlays in front-to-back or back-to-front order. |
| IDirectDrawSurface7::Flip Makes the surface memory that is associated with the DDSCAPS_BACKBUFFER surface become associated with the front-buffer surface. |
| IDirectDrawSurface7::FreePrivateData Frees the specified private data that is associated with this surface. |
| IDirectDrawSurface7::GetAttachedSurface Obtains the attached surface that has the specified capabilities, and increments the reference count of the retrieved interface. |
| IDirectDrawSurface7::GetBltStatus Obtains status about a bit block transfer (bitblt) operation. |
| IDirectDrawSurface7::GetCaps Retrieves the capabilities of this surface. These capabilities are not necessarily related to the capabilities of the display device. |
| IDirectDrawSurface7::GetClipper Retrieves the DirectDrawClipper object that is associated with this surface, and increments the reference count of the returned clipper. |
| IDirectDrawSurface7::GetColorKey Retrieves the color key value for this surface. |
| IDirectDrawSurface7::GetDC Creates a GDI-compatible handle of a device context for this surface. |
| IDirectDrawSurface7::GetDDInterface Retrieves an interface to the DirectDraw object that was used to create this surface. |
| IDirectDrawSurface7::GetFlipStatus Retrieves status about whether this surface has finished its flipping process. |
| IDirectDrawSurface7::GetLOD Retrieves the maximum level of detail (LOD) currently set for a managed mipmap surface. This method succeeds only on managed textures. |
| IDirectDrawSurface7::GetOverlayPosition Retrieves the display coordinates of this surface. This method is used on a visible, active overlay surface (that is, a surface that has the DDSCAPS_OVERLAY flag set). |
| IDirectDrawSurface7::GetPalette Retrieves the DirectDrawPalette object that is associated with this surface, and increments the reference count of the returned palette. |
| IDirectDrawSurface7::GetPixelFormat Retrieves the color and pixel format of this surface. |
| IDirectDrawSurface7::GetPriority Retrieves the texture-management priority for this texture. This method succeeds only on managed textures. |
| IDirectDrawSurface7::GetPrivateData Copies the private data that is associated with this surface to a provided buffer. |
| IDirectDrawSurface7::GetSurfaceDesc Retrieves a description of this surface in its current condition. |
| IDirectDrawSurface7::GetUniquenessValue Retrieves the current uniqueness value for this surface. |
| IDirectDrawSurface7::Initialize Initializes a DirectDrawSurface object. |
| IDirectDrawSurface7::IsLost Determines whether the surface memory that is associated with a DirectDrawSurface object has been freed. |
| IDirectDrawSurface7::Lock Obtains a pointer to the surface memory. |
| IDirectDrawSurface7::PageLock Prevents a system-memory surface from being paged out while a bit block transfer (bitblt) operation that uses direct memory access (DMA) transfers to or from system memory is in progress. |
| IDirectDrawSurface7::PageUnlock Unlocks a system-memory surface, which then allows it to be paged out. |
| IDirectDrawSurface7::ReleaseDC Releases the handle of a device context that was previously obtained by using the IDirectDrawSurface7::GetDC method. |
| IDirectDrawSurface7::Restore Restores a surface that has been lost. This occurs when the surface memory that is associated with the DirectDrawSurface object has been freed. |
| IDirectDrawSurface7::SetClipper Attaches a clipper object to, or deletes one from, this surface. |
| IDirectDrawSurface7::SetColorKey Sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per-surface basis. |
| IDirectDrawSurface7::SetLOD Sets the maximum level of detail (LOD) for a managed mipmap surface. This method succeeds only on managed textures. |
| IDirectDrawSurface7::SetOverlayPosition Changes the display coordinates of an overlay surface. |
| IDirectDrawSurface7::SetPalette Attaches a palette object to (or detaches one from) a surface. The surface uses this palette for all subsequent operations. The palette change takes place immediately, without regard to refresh timing. |
| IDirectDrawSurface7::SetPriority Assigns the texture-management priority for this texture. This method succeeds only on managed textures. |
| IDirectDrawSurface7::SetPrivateData Associates data with the surface that is intended for use by the application, not by DirectDraw. Data is passed by value, and multiple sets of data can be associated with a single surface. |
| IDirectDrawSurface7::SetSurfaceDesc Sets the characteristics of an existing surface. |
| IDirectDrawSurface7::Unlock Notifies DirectDraw that the direct surface manipulations are complete. |
| IDirectDrawSurface7::UpdateOverlay Repositions or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY flag set. |
| IDirectDrawSurface7::UpdateOverlayDisplay The IDirectDrawSurface7::UpdateOverlayDisplay method is not currently implemented. |
| IDirectDrawSurface7::UpdateOverlayZOrder Sets the z-order of an overlay. |
Remarks
The methods of the IDirectDrawSurface7 interface can be organized into the following groups:
| Group | Methods |
|---|---|
| Allocating memory | Initialize, IsLost, and Restore |
| Attaching surfaces | AddAttachedSurface, DeleteAttachedSurface, EnumAttachedSurfaces, and GetAttachedSurface |
| BitBltting | Blt, BltBatch, BltFast, and GetBltStatus |
| Color keying | GetColorKey and SetColorKey |
| Device contexts | GetDC and ReleaseDC |
| Flipping | Flip and GetFlipStatus |
| Locking surfaces | Lock, PageLock, PageUnlock, and Unlock |
| Miscellaneous | GetDDInterface |
| Overlays | AddOverlayDirtyRect, EnumOverlayZOrders, GetOverlayPosition, SetOverlayPosition, UpdateOverlay, UpdateOverlayDisplay, and UpdateOverlayZOrder |
| Private surface data | FreePrivateData, GetPrivateData, and SetPrivateData |
| Surface capabilities | GetCaps |
| Surface clipper | GetClipper and SetClipper |
| Surface characteristics | ChangeUniquenessValue, GetPixelFormat, GetSurfaceDesc, GetUniquenessValue, and SetSurfaceDesc |
| Surface palettes | GetPalette and SetPalette |
| Textures | GetLOD, GetPriority, SetLOD, and SetPriority |
The IDirectDrawSurface7 interface extends the features of previous versions of the interface by offering methods that offer better surface management and ease of use. Many methods in this interface accept slightly different parameters than their counterparts in former versions of the interface. Wherever an IDirectDrawSurface3 interface method might accept a DDSURFACEDESC structure or an IDirectDrawSurface3 interface, the methods in IDirectDrawSurface7 accept a DDSURFACEDESC2 structure or an IDirectDrawSurface7 interface, instead.
Use the LPDIRECTDRAWSURFACE, LPDIRECTDRAWSURFACE2, LPDIRECTDRAWSURFACE3, LPDIRECTDRAWSURFACE4, or LPDIRECTDRAWSURFACE7 data type to declare a variable that points to various DirectDrawSurface object interfaces. The Ddraw.h header file declares these data types with the following code:
typedef struct IDirectDrawSurface FAR *LPDIRECTDRAWSURFACE;
typedef struct IDirectDrawSurface2 FAR *LPDIRECTDRAWSURFACE2;
typedef struct IDirectDrawSurface3 FAR *LPDIRECTDRAWSURFACE3;
typedef struct IDirectDrawSurface4 FAR *LPDIRECTDRAWSURFACE4;
typedef struct IDirectDrawSurface7 FAR *LPDIRECTDRAWSURFACE7;
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Windows |
| Header | ddraw.h |