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