Tell us about your PDF experience.

DirectDraw
Article • 08/23/2019

This section contains information about programming with the DirectDraw component
of the DirectX application programming interface (API).

DirectDraw is no longer recommended for use. With the release of Direct3D 9.0, all two-
dimensional functionality is contained within Direct3D, its associated helper functions in
D3DX, and the DirectX 11 technology Direct2D. However, the DirectDraw reference
documentation is still available in this section.

In This Section
This section contains the DirectDraw Reference documentation.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDraw Reference
Article • 08/23/2019

This section contains reference information for the application programming interface
(API) elements provided by DirectDraw in C/C++. Reference material is divided into the
following categories:

Category Description

DirectDraw Interfaces This section contains reference pages for DirectDraw interfaces.

DirectDraw Functions This section contains reference pages for DirectDraw functions.

DirectDraw Callback This section contains reference pages for DirectDraw callback
Functions functions.

DirectDraw Structures This section contains reference pages for DirectDraw structures.

DirectDraw Return Codes This section contains reference pages for DirectDraw return values.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDraw Interfaces
Article • 08/23/2019

This section contains reference information about the interfaces used with the
DirectDraw component. The following interfaces are covered:

IDirectDraw7
IDirectDrawClipper
IDirectDrawColorControl
IDirectDrawGammaControl
IDirectDrawPalette
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7 interface (ddraw.h)
Article02/16/2023

Applications use the methods of the IDirectDraw7 interface to create DirectDraw

objects and work with system-level variables. This section is a reference to the methods
of the IDirectDraw7 interface.

Inheritance
The IDirectDraw7 interface inherits from the IUnknown interface. IDirectDraw7 also has
these types of members:

Methods
The IDirectDraw7 interface has these methods.

IDirectDraw7::Compact

This method is not currently implemented. (IDirectDraw7.Compact)

IDirectDraw7::CreateClipper

Creates a DirectDrawClipper object.

IDirectDraw7::CreatePalette

Creates a DirectDrawPalette object for this DirectDraw object.

IDirectDraw7::CreateSurface

Creates a DirectDrawSurface object for this DirectDraw object.

IDirectDraw7::DuplicateSurface

Duplicates a DirectDrawSurface object.

IDirectDraw7::EnumDisplayModes

Enumerates all the display modes that the hardware exposes through the DirectDraw object and
that are compatible with a provided surface description.
IDirectDraw7::EnumSurfaces

Enumerates all the existing or possible surfaces that meet the specified surface description.

IDirectDraw7::EvaluateMode

Used after a call to IDirectDraw7::StartModeTest to pass or fail each mode that the test presents
and to step through the modes until the test is complete.

IDirectDraw7::FlipToGDISurface

Makes the surface that the GDI writes to the primary surface.

IDirectDraw7::GetAvailableVidMem

Retrieves the total amount of display memory available and the amount of display memory
currently free for a given type of surface.

IDirectDraw7::GetCaps

Retrieves the capabilities of the device driver for the hardware and the hardware emulation layer
(HEL).

IDirectDraw7::GetDeviceIdentifier

Obtains information about the device driver. This method can be used, with caution, to recognize
specific hardware installations to implement workarounds for poor driver or chipset behavior.

IDirectDraw7::GetDisplayMode

Retrieves the current display mode.

IDirectDraw7::GetFourCCCodes

Retrieves the four-character codes (FOURCC) that are supported by the DirectDraw object. This
method can also retrieve the number of codes that are supported.

IDirectDraw7::GetGDISurface

Retrieves the DirectDrawSurface object that currently represents the surface memory that GDI is
treating as the primary surface.

IDirectDraw7::GetMonitorFrequency

Retrieves the frequency of the monitor that the DirectDraw object controls.

IDirectDraw7::GetScanLine

Retrieves the scan line that is currently being drawn on the monitor.
IDirectDraw7::GetSurfaceFromDC

Retrieves the IDirectDrawSurface7 interface for a surface, based on its GDI device context handle.

IDirectDraw7::GetVerticalBlankStatus

Retrieves the status of the vertical blank.

IDirectDraw7::Initialize

Initializes a DirectDraw object that was created by using the CoCreateInstance COM function.

IDirectDraw7::RestoreAllSurfaces

Restores all the surfaces that were created for the DirectDraw object, in the order that they were
created.

IDirectDraw7::RestoreDisplayMode

Resets the mode of the display device hardware for the primary surface to what it was before the
IDirectDraw7::SetDisplayMode method was called. Exclusive-level access is required to use this
method.

IDirectDraw7::SetCooperativeLevel

Determines the top-level behavior of the application.

IDirectDraw7::SetDisplayMode

Sets the mode of the display-device hardware.

IDirectDraw7::StartModeTest

Initiates a test to update the system registry with refresh rate information for the current display
adapter and monitor combination.

IDirectDraw7::TestCooperativeLevel

Reports the current cooperative-level status of the DirectDraw device for a windowed or full-
screen application.

IDirectDraw7::WaitForVerticalBlank

Helps the application synchronize itself with the vertical-blank interval.

Remarks
The methods of the IDirectDraw7 interface can be organized into the following groups:

Group Methods

Allocating Compact and Initialize

memory

Cooperative SetCooperativeLevel and TestCooperativeLevel

levels

Creating CreateClipper, CreatePalette, and CreateSurface

objects

Device GetCaps
capabilities

Display EnumDisplayModes, GetDisplayMode, GetMonitorFrequency,

modes RestoreDisplayMode, SetDisplayMode, and WaitForVerticalBlank

Display status GetScanLine and GetVerticalBlankStatus

Miscellaneous EvaluateMode, GetAvailableVidMem, GetDeviceIdentifier, GetFourCCCodes, and

StartModeTest

Surface DuplicateSurface, EnumSurfaces, FlipToGDISurface, GetGDISurface,

management GetSurfaceFromDC, and RestoreAllSurfaces

The IDirectDraw7 interface extends the features of previous versions of the interface by
offering methods that enable more flexible surface management than previous versions.
All the surface-related methods in the IDirectDraw7 interface accept slightly different
parameters than their counterparts in the IDirectDraw2 interface. Wherever an
IDirectDraw2 interface method might accept a DDSURFACEDESC structure and retrieve
an IDirectDrawSurface3 interface, the methods in IDirectDraw7 accept a
DDSURFACEDESC2 structure and retrieve an IDirectDrawSurface7 interface, instead.

IDirectDraw7 introduces improved compliance with COM rules that dictate the lifetime
of child objects.

Use the LPDIRECTDRAW, LPDIRECTDRAW2, LPDIRECTDRAW4 or LPDIRECTDRAW7 data

types to declare a variable that contains a pointer to an IDirectDraw, IDirectDraw2,
IDirectDraw4 or IDirectDraw7 interface. The Ddraw.h header file declares these data
types with the following code:

typedef struct IDirectDraw FAR *LPDIRECTDRAW;

 typedef struct IDirectDraw2 FAR *LPDIRECTDRAW2;
typedef struct IDirectDraw4 FAR *LPDIRECTDRAW4;
typedef struct IDirectDraw7 FAR *LPDIRECTDRAW7;

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::Compact method
(ddraw.h)
Article07/27/2022

This method is not currently implemented.

Syntax
C++

HRESULT Compact();

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY

Requirements

Target Platform Windows

Header ddraw.h

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::CreateClipper method
(ddraw.h)
Article11/01/2022

Creates a DirectDrawClipper object.

Syntax
C++

HRESULT CreateClipper(
[in] DWORD unnamedParam1,
[out] LPDIRECTDRAWCLIPPER *unnamedParam2,
[in] IUnknown *unnamedParam3
);

Parameters
[in] unnamedParam1

Currently not used and must be set to 0.

[out] unnamedParam2

Address of a variable to be set to a valid IDirectDrawClipper interface pointer if the call

succeeds.

[in] unnamedParam3

Allows for future compatibility with COM aggregation features. Currently this method
returns an error if this parameter is not NULL.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
 DDERR_OUTOFMEMORY

Remarks
The DirectDrawClipper object can be attached to a DirectDrawSurface and used during
IDirectDrawSurface7::Blt, IDirectDrawSurface7::BltBatch, and
IDirectDrawSurface7::UpdateOverlay operations.

To create a DirectDrawClipper object that is not owned by a specific DirectDraw object,

use the DirectDrawCreateClipper function.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::CreatePalette method
(ddraw.h)
Article11/01/2022

Creates a DirectDrawPalette object for this DirectDraw object.

Syntax
C++

HRESULT CreatePalette(
[in] DWORD unnamedParam1,
[in] LPPALETTEENTRY unnamedParam2,
[out] LPDIRECTDRAWPALETTE *unnamedParam3,
[in] IUnknown *unnamedParam4
);

Parameters
[in] unnamedParam1

This value consists of one or more of the following flags:

DDPCAPS_1BIT

The index is 1 bit. There are two entries in the color table.

DDPCAPS_2BIT
The index is 2 bits. There are four entries in the color table.

DDPCAPS_4BIT
The index is 4 bits. There are 16 entries in the color table.

DDPCAPS_8BIT
The index is 8 bits. There are 256 entries in the color table.
DDPCAPS_8BITENTRIES
The index refers to an 8-bit color index. This flag is valid only when used with the
DDPCAPS_1BIT, DDPCAPS_2BIT, or DDPCAPS_4BIT flag, and when the target surface is 8
bpp. Each color entry is 1 byte long and is an index to a destination surface's 8-bpp
palette.

DDPCAPS_ALPHA
The peFlags member of the associated PALETTEENTRY structure is to be interpreted as a
single 8-bit alpha value (in addition to the peRed, peGreen, and peBlue members). A
palette created by using this flag can be attached only to a texture: a surface created
with the DDSCAPS_TEXTURE capability flag.

DDPCAPS_ALLOW256
This palette can have all 256 entries defined.

DDPCAPS_INITIALIZE
Obsolete. DirectDraw always initializes this palette with the colors in the color array
passed at lpDDColorArray.

DDPCAPS_PRIMARYSURFACE

This palette is attached to the primary surface. Changing this palette's color table
immediately affects the display unless DDPSETPAL_VSYNC is specified and supported.

DDPCAPS_PRIMARYSURFACELEFT
This palette is the one attached to the left-eye primary surface. Changing this palette's
color table immediately affects the left-eye display unless DDPSETPAL_VSYNC is
specified and supported.

DDPCAPS_VSYNC

This palette can have modifications to it synchronized with the monitor's refresh rate.

[in] unnamedParam2
Address of an array of 2, 4, 16, or 256 PALETTEENTRY structures to initialize the
DirectDrawPalette object.

[out] unnamedParam3

Address of a variable to be set to a valid IDirectDrawPalette interface pointer if the call

succeeds.

[in] unnamedParam4

Allows for future compatibility with COM aggregation features. Currently, this method
returns an error if this parameter is not NULL.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::CreateSurface method
(ddraw.h)
Article11/01/2022

Creates a DirectDrawSurface object for this DirectDraw object.

Syntax
C++

HRESULT CreateSurface(
[in] LPDDSURFACEDESC2 unnamedParam1,
[out] LPDIRECTDRAWSURFACE7 *unnamedParam2,
[in] IUnknown *unnamedParam3
);

Parameters
[in] unnamedParam1

Address of a DDSURFACEDESC2 structure that describes the requested surface. Set any
unused members of the DDSURFACEDESC2 structure to 0 before calling this method. A
DDSCAPS2 structure is a member of DDSURFACEDESC2.

[out] unnamedParam2

Address of a variable to be set to a valid IDirectDrawSurface7 interface pointer if the call

succeeds.

[in] unnamedParam3

Allows for future compatibility with COM aggregation features. Currently, this method
returns an error if this parameter is not NULL.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error 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

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::DuplicateSurface method
(ddraw.h)
Article11/01/2022

Duplicates a DirectDrawSurface object.

Syntax
C++

HRESULT DuplicateSurface(
[in] LPDIRECTDRAWSURFACE7 unnamedParam1,
[out] LPDIRECTDRAWSURFACE7 *unnamedParam2
);

Parameters
[in] unnamedParam1

Address of the IDirectDrawSurface7 interface for the surface to be duplicated.

[out] unnamedParam2

Address of a variable to contain an IDirectDrawSurface7 interface pointer for the newly

duplicated DirectDrawSurface object.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_CANTDUPLICATE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACELOST

Remarks
DuplicateSurface creates a new DirectDrawSurface object that points to the same
surface memory as an existing DirectDrawSurface object. This duplicate can be used just
like the original object. The surface memory is released after the last object referring to
it is released. A primary surface, 3-D surface, or implicitly created surface cannot be
duplicated.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::EnumDisplayModes
method (ddraw.h)
Article11/01/2022

Enumerates all the display modes that the hardware exposes through the DirectDraw
object and that are compatible with a provided surface description.

Syntax
C++

HRESULT EnumDisplayModes(
[in] DWORD unnamedParam1,
[in] LPDDSURFACEDESC2 unnamedParam2,
[in] LPVOID unnamedParam3,
[in] LPDDENUMMODESCALLBACK2 unnamedParam4
);

Parameters
[in] unnamedParam1

This value consists of one or more of the following flags:

DDEDM_REFRESHRATES

Enumerates modes with different refresh rates. IDirectDraw7::EnumDisplayModes

guarantees that a particular mode is enumerated only once. This flag specifies whether
the refresh rate is taken into account when determining whether a mode is unique.

DDEDM_STANDARDVGAMODES

Enumerates Mode 13 in addition to the 320x200x8 Mode X mode.

[in] unnamedParam2

Address of a DDSURFACEDESC2 structure to be checked against available modes. If the

value of this parameter is NULL, all modes are enumerated.

[in] unnamedParam3
Address of an application-defined structure to be passed to each enumeration member.

[in] unnamedParam4

Address of the EnumModesCallback2 function that the enumeration procedure calls

every time a match is found.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
IDirectDraw7::EnumDisplayModes enumerates the dwRefreshRate member of the
DDSURFACEDESC2 structure; the IDirectDraw::EnumDisplayModes method does not
have this ability. If you use the IDirectDraw7::SetDisplayMode method to set the refresh
rate of a new mode, use IDirectDraw7::EnumDisplayModes to enumerate the
dwRefreshRate member.

IDirectDraw7::EnumDisplayModes differs from its counterparts in former interfaces in

that it accepts the address of an EnumModesCallback2 function as a parameter, rather
than an EnumModesCallback function.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::EnumSurfaces method
(ddraw.h)
Article11/01/2022

Enumerates all the existing or possible surfaces that meet the specified surface
description.

Syntax
C++

HRESULT EnumSurfaces(
[in] DWORD unnamedParam1,
[in] LPDDSURFACEDESC2 unnamedParam2,
[in] LPVOID unnamedParam3,
[in] LPDDENUMSURFACESCALLBACK7 unnamedParam4
);

Parameters
[in] unnamedParam1

A combination of one search type flag and one matching flag. The search type flag
determines how the method searches for matching surfaces; you can search for surfaces
that can be created using the description in the lpDDSD2 parameter or for existing
surfaces that already match that description. The matching flag determines whether the
method enumerates all surfaces, only those that match, or only those that do not match
the description in the lpDDSD2 parameter.

Search type flags

DDENUMSURFACES_CANBECREATED
Enumerates the first surface that can be created and meets the search criterion. This flag
can be used only with the DDENUMSURFACES_MATCH flag.

DDENUMSURFACES_DOESEXIST

Enumerates the already existing surfaces that meet the search criterion.
Matching flags

DDENUMSURFACES_ALL
Enumerates all surfaces that meet the search criterion. This flag can be used only with
the DDENUMSURFACES_DOESEXIST search type flag.

DDENUMSURFACES_MATCH

Searches for any surface that matches the surface description.

DDENUMSURFACES_NOMATCH

Searches for any surface that does not match the surface description.

[in] unnamedParam2

Address of a DDSURFACEDESC2 structure that defines the surface of interest. This

parameter can be NULL if dwFlags includes the DDENUMSURFACES_ALL flag.

[in] unnamedParam3

Address of an application-defined structure to be passed to each enumeration member.

[in] unnamedParam4

Address of the EnumSurfacesCallback7 function that the enumeration procedure calls

every time a match is found.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
If the DDENUMSURFACES_CANBECREATED flag is set, this method attempts to
temporarily create a surface that meets the search criterion.
When you use the DDENUMSURFACES_DOESEXIST flag, an enumerated surface's
reference count is incremented—if you are not going to use the surface, be sure to use
IDirectDrawSurface7::Release to release it after each enumeration. If you will be using
the surface, release it when it is no longer needed.

This method differs from its counterparts in previous interface versions in that it accepts
a pointer to an EnumSurfacesCallback7 function, rather than an EnumSurfacesCallback
or EnumSurfacesCallback2 function.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::EvaluateMode method
(ddraw.h)
Article11/01/2022

Used after a call to IDirectDraw7::StartModeTest to pass or fail each mode that the test
presents and to step through the modes until the test is complete.

Syntax
C++

HRESULT EvaluateMode(
[in] DWORD unnamedParam1,
[out] DWORD *unnamedParam2
);

Parameters
[in] unnamedParam1

One of the following flags that indicate the status of the mode being tested:

DDEM_MODEPASSED

The mode being tested has passed.

DDEM_MODEFAILED

The mode being tested has failed.

[out] unnamedParam2

A pointer to a variable that receives a value that denotes the seconds that remain before
the current mode is failed automatically unless it is explicitly passed or failed.

Return value
If the method succeeds, the return value is DD_OK.
If it fails or on completion, the method can return one of the following error values:

DDERR_TESTFINISHED
DDERR_NEWMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

Remarks
You can use EvaluateMode in conjunction with the IDirectDraw7::StartModeTest method
to determine the maximum refresh rate that an EDID monitor and display adapter
combination can support for each screen resolution.

Specifically, a call to IDirectDraw7::StartModeTest directs DirectDraw to establish a set of

testable resolutions and to display a mode based on the first resolution in the set.
Subsequent calls to EvaluateMode can be used to pass or fail each mode and to
advance the test to the next display mode. The method steps through the testable
resolutions starting with the highest refresh rate supported for a given resolution. After
a refresh rate for a given resolution passes, testing of lower refresh rates for that
resolution is skipped.

When the test is initiated, or whenever a mode is passed or failed, DirectDraw begins a
15 second timeout. An application can monitor the time remaining without passing or
failing the current mode by calling EvaluateMode with a value of 0 for the dwFlags
argument. Note that DirectDraw only changes modes or terminates the test when
EvaluateMode is called. However, if an application calls EvaluateMode after the timeout
period has elapsed, the current mode fails, regardless of the value passed to the dwFlags
parameter.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll
See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::FlipToGDISurface method
(ddraw.h)
Article11/01/2022

Makes the surface that the GDI writes to the primary surface.

Syntax
C++

HRESULT FlipToGDISurface();

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

Remarks
You can call FlipToGDISurface at the end of a page-flipping application to ensure that
the display memory that the GDI writes to is visible.

You can also use FlipToGDISurface to make the GDI surface the primary surface so that
normal windows, such as dialog boxes, can be displayed in full-screen mode. The
hardware must have the DDCAPS2_CANRENDERWINDOWED capability.

FlipToGDISurface disables stereo autoflipping.

Requirements

Target Platform Windows

 Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetAvailableVidMem
method (ddraw.h)
Article11/01/2022

Retrieves the total amount of display memory available and the amount of display
memory currently free for a given type of surface.

Syntax
C++

HRESULT GetAvailableVidMem(
[in] LPDDSCAPS2 unnamedParam1,
[out] LPDWORD unnamedParam2,
[out] LPDWORD unnamedParam3
);

Parameters
[in] unnamedParam1

A pointer to a DDSCAPS2 structure that indicates the hardware capabilities of the

proposed surface.

[out] unnamedParam2

A pointer to a variable that receives the total amount of display memory available, in
bytes. The value received reflects the total video memory, minus the video memory
required for the primary surface and any private caches that the display driver reserves.

[out] unnamedParam3

A pointer to a variable that receives the amount of display memory currently free that
can be allocated for a surface that matches the capabilities specified by the structure at
lpDDSCaps2.

Return value
If the method succeeds, the return value is DD_OK.
If it fails, the method can return one of the following error values:

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

Remarks
The following C++ example demonstrates how to use GetAvailableVidMem to
determine both the total and free display memory available for texture-map surfaces:

// For this example, the lpDD variable is a valid

// pointer to an IDirectDraw7 interface.
LPDIRECTDRAW7 lpDD;
DDSCAPS2 ddsCaps2;
DWORD dwTotal;
DWORD dwFree;
HRESULT hr;

hr = lpDD->QueryInterface(IID_IDirectDraw7, &lpDD);
if (FAILED(hr))
return hr;

// Initialize the structure.

ZeroMemory(&ddsCaps2, sizeof(ddsCaps2));

ddsCaps2.dwCaps = DDSCAPS_TEXTURE;
hr = lpDD->GetAvailableVidMem(&ddsCaps2, &dwTotal, &dwFree);
if (FAILED(hr))
return hr;

If the surface has the DDSCAPS_VIDEOMEMORY flag set, GetAvailableVidMem returns

different amounts of video memory depending on whether the surface can be used as a
3-D texture. If the surface can be used for 3-D textures, GetAvailableVidMem returns
the sum of the local video memory and the non-local video memory on AGP systems.

GetAvailableVidMem provides only a snapshot of the current display-memory state.

The amount of free display memory is subject to change as surfaces are created and
released. Therefore, you should use the free memory value only as an approximation. In
addition, a particular display adapter card might make no distinction between two
different memory types. For example, the adapter might use the same portion of display
memory to store z-buffers and textures. So, allocating one type of surface (for example,
a z-buffer) can affect the amount of display memory available for another type of
surface (textures). Therefore, it is best to first allocate an application's fixed resources
(such as front and back buffers and z-buffers) before determining how much memory is
available for dynamic use (such as texture mapping).

GetAvailableVidMem was not implemented in the previous DirectX IDirectDraw

interface version.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetCaps method
(ddraw.h)
Article11/01/2022

Retrieves the capabilities of the device driver for the hardware and the hardware
emulation layer (HEL).

Syntax
C++

HRESULT GetCaps(
[out] LPDDCAPS unnamedParam1,
[out] LPDDCAPS unnamedParam2
);

Parameters
[out] unnamedParam1

A pointer to a DDCAPS structure that receives the capabilities of the hardware, as

reported by the device driver. Set this parameter to NULL if you do not want to retrieve
device driver capabilities.

[out] unnamedParam2

A pointer to a DDCAPS structure that receives the capabilities of the HEL. Set this
parameter to NULL if you do not want to retrieve HEL capabilities.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

You can set only one of the two parameters to NULL to exclude it. If you set both to
NULL, the method fails and returns DDERR_INVALIDPARAMS.
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetDeviceIdentifier
method (ddraw.h)
Article11/01/2022

Obtains information about the device driver. This method can be used, with caution, to
recognize specific hardware installations to implement workarounds for poor driver or
chipset behavior.

Syntax
C++

HRESULT GetDeviceIdentifier(
[out] LPDDDEVICEIDENTIFIER2 unnamedParam1,
[in] DWORD unnamedParam2
);

Parameters
[out] unnamedParam1

A pointer to a DDDEVICEIDENTIFIER2 structure that receives information about the

driver.

[in] unnamedParam2

This value consists of flags that specify options. The following flag is the only defined
flag:

DDGDI_GETHOSTIDENTIFIER

Causes GetDeviceIdentifier to return information about the host (typically 2-D) adapter
in a system equipped with a stacked secondary 3-D adapter. Such an adapter appears to
the application as if it were part of the host adapter, but is typically located on a
separate card. When the dwFlags parameter is 0, information on the stacked secondary
is returned because this most accurately reflects the qualities of the DirectDraw object
involved.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return DDERR_INVALIDPARAMS.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetDisplayMode method
(ddraw.h)
Article11/01/2022

Retrieves the current display mode.

Syntax
C++

HRESULT GetDisplayMode(
[in] LPDDSURFACEDESC2 unnamedParam1
);

Parameters
[in] unnamedParam1

A pointer to a DDSURFACEDESC2 structure that receives a description of the current

surface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTEDMODE

Remarks
An application should not save the information that GetDisplayMode returns to restore
the display mode on clean-up. The application should instead use the
IDirectDraw7::RestoreDisplayMode method to restore the mode on clean-up, thus
avoiding mode-setting conflicts that could arise in a multiprocess environment.
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetFourCCCodes method
(ddraw.h)
Article11/01/2022

Retrieves the four-character codes (FOURCC) that are supported by the DirectDraw
object. This method can also retrieve the number of codes that are supported.

Syntax
C++

HRESULT GetFourCCCodes(
[in, out] LPDWORD unnamedParam1,
[in, out] LPDWORD unnamedParam2
);

Parameters
[in, out] unnamedParam1

A pointer to a variable that contains the number of entries that the array specified by
lpCodes can hold. If the number of entries is too small to accommodate all the codes,
lpNumCodes is set to the required number, and the array specified by lpCodes is filled
with all that fits.

[in, out] unnamedParam2

An array of variables to be filled with FOURCCs that are supported by this DirectDraw
object. If you specify NULL, lpNumCodes is set to the number of supported FOURCCs,
and the method returns.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetGDISurface method
(ddraw.h)
Article11/01/2022

Retrieves the DirectDrawSurface object that currently represents the surface memory
that GDI is treating as the primary surface.

Syntax
C++

HRESULT GetGDISurface(
[out] LPDIRECTDRAWSURFACE7 *unnamedParam1
);

Parameters
[out] unnamedParam1

Address of a variable to be filled with a pointer to the IDirectDrawSurface7 interface for

the surface that currently controls the GDI's primary surface memory.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

Requirements

Target Platform Windows

Header ddraw.h
 Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetMonitorFrequency
method (ddraw.h)
Article11/01/2022

Retrieves the frequency of the monitor that the DirectDraw object controls.

Syntax
C++

HRESULT GetMonitorFrequency(
[out] LPDWORD unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the monitor frequency, in Hertz (Hz).

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetScanLine method
(ddraw.h)
Article11/01/2022

Retrieves the scan line that is currently being drawn on the monitor.

Syntax
C++

HRESULT GetScanLine(
[out] LPDWORD unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the scan line that the display is currently drawing.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS

Remarks
Scan lines are reported as zero-based integers. The returned scan line value is in the
range from 0 through n, where 0 is the first visible scan line on the screen and n is the
last visible scan line, plus any scan lines that occur during the vertical blank period. So,
in a case where an application is running at a resolution of 640×480 and there are 12
scan lines during vblank, the values returned by this method range from 0 through 491.
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetSurfaceFromDC
method (ddraw.h)
Article11/01/2022

Retrieves the IDirectDrawSurface7 interface for a surface, based on its GDI device
context handle.

Syntax
C++

HRESULT GetSurfaceFromDC(
[in] HDC unnamedParam1,
[out] LPDIRECTDRAWSURFACE7 *unnamedParam2
);

Parameters
[in] unnamedParam1

Handle of a display device context.

[out] unnamedParam2

Address of a variable to be filled with a pointer to the IDirectDrawSurface7 interface for

the surface if the call succeeds.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_NOTFOUND

Remarks
This method succeeds only for device context handles that identify surfaces already
associated with the DirectDraw object.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::GetVerticalBlankStatus
method (ddraw.h)
Article11/01/2022

Retrieves the status of the vertical blank.

Syntax
C++

HRESULT GetVerticalBlankStatus(
[out] LPBOOL unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the status of the vertical blank. This parameter is
TRUE if a vertical blank is occurring, and FALSE otherwise.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
To synchronize with the vertical blank, use the IDirectDraw7::WaitForVerticalBlank
method.

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::Initialize method
(ddraw.h)
Article11/01/2022

Initializes a DirectDraw object that was created by using the CoCreateInstance COM
function.

Syntax
C++

HRESULT Initialize(
[in] GUID *unnamedParam1
);

Parameters
[in] unnamedParam1

A pointer to the globally unique identifier (GUID) that this method uses as the
DirectDraw interface identifier.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_ALREADYINITIALIZED
DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_NODIRECTDRAWSUPPORT
DDERR_OUTOFMEMORY

This method is provided for compliance with the Component Object Model (COM). If
you already used the DirectDrawCreate function to create a DirectDraw object, this
method returns DDERR_ALREADYINITIALIZED. If you do not call IDirectDraw7::Initialize
when you use CoCreateInstance to create a DirectDraw object, any method that you call
afterward returns DDERR_NOTINITIALIZED.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::RestoreAllSurfaces
method (ddraw.h)
Article11/01/2022

Restores all the surfaces that were created for the DirectDraw object, in the order that
they were created.

Syntax
C++

HRESULT RestoreAllSurfaces();

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
This method is provided for convenience. Effectively, this method calls the
IDirectDrawSurface7::Restore method for each surface that is created by this DirectDraw
object.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll
See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::RestoreDisplayMode
method (ddraw.h)
Article11/01/2022

Resets the mode of the display device hardware for the primary surface to what it was
before the IDirectDraw7::SetDisplayMode method was called. Exclusive-level access is
required to use this method.

Syntax
C++

HRESULT RestoreDisplayMode();

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::SetCooperativeLevel
method (ddraw.h)
Article11/01/2022

Determines the top-level behavior of the application.

Syntax
C++

HRESULT SetCooperativeLevel(
[in] HWND unnamedParam1,
[in] DWORD unnamedParam2
);

Parameters
[in] unnamedParam1

Window handle used for the application. Set to the calling application's top-level
window handle (not a handle for any child windows created by the top-level window).
This parameter can be NULL when the DDSCL_NORMAL flag is specified in the dwFlags
parameter.

[in] unnamedParam2

This value consists of one or more of the following flags:

DDSCL_ALLOWMODEX

Allows the use of Mode X display modes. This flag can be used only if the
DDSCL_EXCLUSIVE and DDSCL_FULLSCREEN flags are present.

DDSCL_ALLOWREBOOT

Allows CTRL+ALT+DEL to function while in exclusive (full-screen) mode.

DDSCL_CREATEDEVICEWINDOW
This flag is supported in Windows 98 and Windows 2000 only. Indicates that DirectDraw
will create and manage a default device window for this DirectDraw object.

DDSCL_EXCLUSIVE

Requests the exclusive level. This flag must be used with the DDSCL_FULLSCREEN flag.

DDSCL_FPUPRESERVE

The calling application cares about the FPU state and does not want Direct3D to modify
it in ways visible to the application. In this mode, Direct3D saves and restores the FPU
state every time that it needs to modify the FPU state.

DDSCL_FPUSETUP

The calling application is likely to keep the FPU set up for optimal Direct3D performance
(single precision and exceptions disabled), so Direct3D does not need to explicitly set
the FPU each time. This is the default state.

DDSCL_FULLSCREEN
The exclusive-mode owner is responsible for the entire primary surface. The GDI can be
ignored. This flag must be used with the DDSCL_EXCLUSIVE flag.

DDSCL_MULTITHREADED

Requests multithread-safe DirectDraw behavior. This causes Direct3D to take the global
critical section more frequently.

DDSCL_NORMAL
The application functions as a typical Windows application. This flag cannot be used
with the DDSCL_ALLOWMODEX, DDSCL_EXCLUSIVE, or DDSCL_FULLSCREEN flags.

DDSCL_NOWINDOWCHANGES
DirectDraw is not allowed to minimize or restore the application window on activation.

DDSCL_SETDEVICEWINDOW
This flag is supported in Windows 98 and Windows 2000 only. Indicates that the hWnd
parameter is the window handle of the device window for this DirectDraw object. This
flag cannot be used with the DDSCL_SETFOCUSWINDOW flag.

DDSCL_SETFOCUSWINDOW
This flag is supported in Windows 98 and Windows 2000 only. Indicates that the hWnd
parameter is the window handle of the focus window for this DirectDraw object. This
flag cannot be used with the DDSCL_SETDEVICEWINDOW flag.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_EXCLUSIVEMODEALREADYSET
DDERR_HWNDALREADYSET
DDERR_HWNDSUBCLASSED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

Remarks
This method must be called by the same thread that created the application window.

An application must set either the DDSCL_EXCLUSIVE or the DDSCL_NORMAL flag.

The DDSCL_EXCLUSIVE flag must be set to call functions that can adversely affect
performance of other applications.

Interaction between this method and the IDirectDraw7::SetDisplayMode method differs

from their IDirectDraw counterparts.

If you use Microsoft Foundation Classes (MFC), the window handle passed to this
method must identify the application's top-level window, not a derived child window. To
retrieve your MFC application's top-level window handle, you could use the following
code:
 HWND hwndTop = AfxGetMainWnd()->GetSafeHwnd();

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::SetDisplayMode method
(ddraw.h)
Article11/01/2022

Sets the mode of the display-device hardware.

Syntax
C++

HRESULT SetDisplayMode(
[in] DWORD unnamedParam1,
[in] DWORD unnamedParam2,
[in] DWORD unnamedParam3,
[in] DWORD unnamedParam4,
[in] DWORD unnamedParam5
);

Parameters
[in] unnamedParam1

Width of the new display mode.

[in] unnamedParam2

Height of the new display mode.

[in] unnamedParam3

Bits per pixel (bpp) of the new display mode.

[in] unnamedParam4

Refresh rate of the new display mode. Set this value to 0 to request the default refresh
rate for the driver.

[in] unnamedParam5

This value consists of flags that describe additional options. Currently, the only valid flag
is DDSDM_STANDARDVGAMODE, which causes the method to set Mode 13, instead of
Mode X 320x200x8 mode. If you are setting another resolution, bit depth, or a Mode X
mode, do not use this flag; instead, set the parameter to 0.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

Remarks
This method must be called by the same thread that created the application window.

If another application changes the display mode, the primary surface is lost, and the
method returns DDERR_SURFACELOST until the primary surface is recreated to match
the new display mode.

As part of the prior-version IDirectDraw interface, this method did not include the
dwRefreshRate and dwFlags parameters.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll
See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::StartModeTest method
(ddraw.h)
Article11/01/2022

Initiates a test to update the system registry with refresh rate information for the current
display adapter and monitor combination. A call to this method is typically followed by
calls to IDirectDraw7::EvaluateMode to pass or fail modes displayed by the test.

Syntax
C++

HRESULT StartModeTest(
[in] LPSIZE unnamedParam1,
[in] DWORD unnamedParam2,
[in] DWORD unnamedParam3
);

Parameters
[in] unnamedParam1

An array of SIZE elements that describe, in terms of screen resolutions, the modes that
should be tested.

[in] unnamedParam2

The number of elements in the array that the lpModesToTest parameter specifies.

[in] unnamedParam3

Flags that specify options for starting a test. The only flag value that is currently valid is
DDSMT_ISTESTREQUIRED. When this flag is specified, StartModeTest does not initiate a
test, but instead returns a value that indicates whether it is possible or necessary to test
the resolutions that the lpModesToTest and dwNumEntries parameters identify.

Return value
If the method succeeds, the return value is DD_OK.
If it fails, the method can return one of the following error values:

DDERR_CURRENTLYNOTAVAIL
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOTFOUND
DDERR_TESTFINISHED

When the method is called with the DDSMT_ISTESTREQUIRED flag, it can return one of
the following values:

DDERR_NEWMODE
DDERR_NODRIVERSUPPORT
DDERR_NOMONITORINFORMATION
DDERR_TESTFINISHED

Remarks
You can use the StartModeTest method together with the IDirectDraw7::EvaluateMode
method to determine the maximum refresh rate that an EDID monitor and display
adapter combination can support for each screen resolution. The results of the testing
are stored in the system registry and affect the operation of
IDirectDraw7::EnumDisplayModes when that method is called with the
DDEDM_REFRESHRATES flag set.

Specifically, a call to StartModeTest directs DirectDraw to establish a set of testable

resolutions and to display a mode based on the first resolution in the set. Subsequent
calls to IDirectDraw7::EvaluateMode can be used to pass or fail each mode and to
advance the test to the next display mode.

StartModeTest succeeds only with monitors that contain EDID data. If the monitor is not
EDID-compliant, StartModeTest returns DDERR_TESTFINISHED without testing any
modes. If the EDID table does not contain values higher than 60 Hz, no modes are
tested. Refresh rates higher than 100 Hz are tested only if the EDID table contains values
higher than 85 Hz.

If you call StartModeTest with an argument list of (NULL, 0, 0), StartModeTest clears
existing refresh rate information from the registry.

The test does not guarantee to display only the resolutions in the array described by the
lpModesToTest and dwNumEntries parameters. For example, the 640×480 resolution is
used to obtain a maximum viewable refresh rate for the 320×200 resolution.
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::TestCooperativeLevel
method (ddraw.h)
Article11/01/2022

Reports the current cooperative-level status of the DirectDraw device for a windowed or
full-screen application.

Syntax
C++

HRESULT TestCooperativeLevel();

Return value
If the method succeeds, the return value is DD_OK, which indicates that the calling
application can continue.

If it fails, the method can return one of the following error values (see Remarks):

DDERR_INVALIDOBJECT
DDERR_EXCLUSIVEMODEALREADYSET
DDERR_NOEXCLUSIVEMODE
DDERR_WRONGMODE

Remarks
This method is particularly useful to applications that use the WM_ACTIVATEAPP and
WM_DISPLAYCHANGE system messages as a notification to restore surfaces or recreate
DirectDraw objects. The DD_OK return value always indicates that the application can
continue, but the error codes are interpreted differently, depending on the cooperative
level that the application uses.

Requirements

Target Platform Windows

 Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDraw7::WaitForVerticalBlank
method (ddraw.h)
Article11/01/2022

Helps the application synchronize itself with the vertical-blank interval.

Syntax
C++

HRESULT WaitForVerticalBlank(
[in] DWORD unnamedParam1,
[in] HANDLE unnamedParam2
);

Parameters
[in] unnamedParam1

One of the following flags that indicates how long to wait for the vertical blank:

DDWAITVB_BLOCKBEGIN
WaitForVerticalBlank returns when the vertical-blank interval begins.

DDWAITVB_BLOCKBEGINEVENT
Triggers an event when the vertical blank begins. This value is not currently supported.

DDWAITVB_BLOCKEND
WaitForVerticalBlank returns when the vertical-blank interval ends and the display
begins.

[in] unnamedParam2

Handle of the event to be triggered when the vertical blank begins. This parameter is
not currently used.
Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDraw7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawClipper interface (ddraw.h)
Article07/22/2021

Applications use the methods of the IDirectDrawClipper interface to manage clip lists.
This section is a reference to the methods of this interface.

Inheritance
The IDirectDrawClipper interface inherits from the IUnknown interface.
IDirectDrawClipper also has these types of members:

Methods
The IDirectDrawClipper interface has these methods.

IDirectDrawClipper::GetClipList

Retrieves a copy of the clip list that is associated with a DirectDrawClipper object. To select a
subset of the clip list, you can pass a rectangle that clips the clip list.

IDirectDrawClipper::GetHWnd

Retrieves the window handle that was previously associated with this DirectDrawClipper object by
the IDirectDrawClipper::SetHWnd method.

IDirectDrawClipper::Initialize

Initializes a DirectDrawClipper object that was created by using the CoCreateInstance COM
function.

IDirectDrawClipper::IsClipListChanged

Retrieves the status of the clip list if a window handle is associated with a DirectDrawClipper
object.

IDirectDrawClipper::SetClipList

Sets or deletes the clip list that is used by the IDirectDrawSurface7::Blt,

IDirectDrawSurface7::BltBatch, and IDirectDrawSurface7::UpdateOverlay methods on surfaces to
which the parent DirectDrawClipper object is attached.
 IDirectDrawClipper::SetHWnd

Sets the window handle that the clipper object uses to obtain clipping information.

Remarks
The methods of the IDirectDrawClipper interface can be organized into the following
groups:

Group Methods

Allocating memory Initialize

Clip list GetClipList, IsClipListChanged, SetClipList, and SetHWnd

Handles GetHWnd

You can use the LPDIRECTDRAWCLIPPER data type to declare a variable that contains a
pointer to an IDirectDrawClipper interface. The Ddraw.h header file declares this data
type with the following code:

typedef struct IDirectDrawClipper FAR *LPDIRECTDRAWCLIPPER;

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No
Get help at Microsoft Q&A
IDirectDrawClipper::GetClipList method
(ddraw.h)
Article11/01/2022

Retrieves a copy of the clip list that is associated with a DirectDrawClipper object. To
select a subset of the clip list, you can pass a rectangle that clips the clip list.

Syntax
C++

HRESULT GetClipList(
[in] LPRECT unnamedParam1,
[out] LPRGNDATA unnamedParam2,
[out] LPDWORD unnamedParam3
);

Parameters
[in] unnamedParam1

A pointer to a RECT structure that GetClipList uses to clip the clip list. Set this parameter
to NULL to retrieve the entire clip list.

[out] unnamedParam2

A pointer to a RGNDATA structure that receives the resulting copy of the clip list. If this
parameter is NULL, GetClipList fills the variable at lpdwSize with the number of bytes
necessary to hold the entire clip list.

[out] unnamedParam3

A pointer to a variable that receives the size of the resulting clip list. When retrieving the
clip list, this parameter is the size of the buffer at lpClipList. When lpClipList is NULL, the
variable at lpdwSize receives the required size of the buffer, in bytes.

Return value
If the method succeeds, the return value is DD_OK.
If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST
DDERR_REGIONTOOSMALL

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawClipper

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawClipper::GetHWnd method
(ddraw.h)
Article11/01/2022

Retrieves the window handle that was previously associated with this DirectDrawClipper
object by the IDirectDrawClipper::SetHWnd method.

Syntax
C++

HRESULT GetHWnd(
[out] HWND *unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the window handle that was previously associated
with this DirectDrawClipper object by the IDirectDrawClipper::SetHWnd method.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDrawClipper

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawClipper::Initialize method
(ddraw.h)
Article11/01/2022

Initializes a DirectDrawClipper object that was created by using the CoCreateInstance

COM function.

Syntax
C++

HRESULT Initialize(
[in] LPDIRECTDRAW unnamedParam1,
[in] DWORD unnamedParam2
);

Parameters
[in] unnamedParam1

A pointer to the DirectDraw object to associate with the DirectDrawClipper object. If this
parameter is set to NULL, an independent DirectDrawClipper object is initialized; a call of
this type is equivalent to using the DirectDrawCreateClipper function.

[in] unnamedParam2

Currently not used and must be set to 0.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_ALREADYINITIALIZED
DDERR_INVALIDPARAMS

Remarks
The IDirectDrawClipper::Initialize method is provided for compliance with the
Component Object Model (COM). If you used the DirectDrawCreateClipper function or
the IDirectDraw7::CreateClipper method to create the DirectDrawClipper object, the
IDirectDrawClipper::Initialize method returns DDERR_ALREADYINITIALIZED.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawClipper

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawClipper::IsClipListChanged
method (ddraw.h)
Article11/01/2022

Retrieves the status of the clip list if a window handle is associated with a
DirectDrawClipper object.

Syntax
C++

HRESULT IsClipListChanged(
[out] BOOL *unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the status of the clip list. This parameter is TRUE if
the clip list has changed, and FALSE otherwise.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDrawClipper

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawClipper::SetClipList method
(ddraw.h)
Article11/01/2022

Sets or deletes the clip list that is used by the IDirectDrawSurface7::Blt,

IDirectDrawSurface7::BltBatch, and IDirectDrawSurface7::UpdateOverlay methods on
surfaces to which the parent DirectDrawClipper object is attached.

Syntax
C++

HRESULT SetClipList(
[in] LPRGNDATA unnamedParam1,
[in] DWORD unnamedParam2
);

Parameters
[in] unnamedParam1

A pointer to a valid RGNDATA structure for the clip list to set or NULL. If there is an
existing clip list that is associated with the DirectDrawClipper object and this value is
NULL, the clip list is deleted.

[in] unnamedParam2

Currently not used and must be set to 0.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_CLIPPERISUSINGHWND
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
Remarks
You cannot set the clip list if a window handle is already associated with the
DirectDrawClipper object.

The IDirectDrawSurface7::BltFast method cannot clip. If you call

IDirectDrawSurface7::BltFast on a surface with an attached clipper, it returns
DDERR_UNSUPPORTED.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawClipper

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawClipper::SetHWnd method
(ddraw.h)
Article11/01/2022

Sets the window handle that the clipper object uses to obtain clipping information.

Syntax
C++

HRESULT SetHWnd(
[in] DWORD unnamedParam1,
[in] HWND unnamedParam2
);

Parameters
[in] unnamedParam1

Currently not used and must be set to 0.

[in] unnamedParam2

Window handle that obtains the clipping information.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawClipper

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawColorControl interface
(ddraw.h)
Article07/22/2021

Applications use the methods of the IDirectDrawColorControl interface to get and set
color controls.

Inheritance
The IDirectDrawColorControl interface inherits from the IUnknown interface.
IDirectDrawColorControl also has these types of members:

Methods
The IDirectDrawColorControl interface has these methods.

IDirectDrawColorControl::GetColorControls

Retrieves the current color-control settings that are associated with an overlay or a primary
surface.

IDirectDrawColorControl::SetColorControls

Sets the color-control options for an overlay or a primary surface.

Remarks
You can use the LPDIRECTDRAWCOLORCONTROL data type to declare a variable that
contains a pointer to an IDirectDrawColorControl interface. The Ddraw.h header file
declares this data type with the following code:

typedef struct IDirectDrawColorControl FAR *LPDIRECTDRAWCOLORCONTROL;

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawColorControl::GetColorContr
ols method (ddraw.h)
Article11/01/2022

Retrieves the current color-control settings that are associated with an overlay or a
primary surface.

Syntax
C++

HRESULT GetColorControls(
[in, out] LPDDCOLORCONTROL unnamedParam1
);

Parameters
[in, out] unnamedParam1

A pointer to a DDCOLORCONTROL structure that receives the current control settings.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

Remarks
The dwFlags member of the DDCOLORCONTROL structure indicates which of the color-
control options are supported.

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawColorControl

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawColorControl::SetColorContr
ols method (ddraw.h)
Article11/01/2022

Sets the color-control options for an overlay or a primary surface.

Syntax
C++

HRESULT SetColorControls(
[in] LPDDCOLORCONTROL unnamedParam1
);

Parameters
[in] unnamedParam1

A pointer to a DDCOLORCONTROL structure that contains the new control settings to

apply.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDrawColorControl

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawGammaControl interface
(ddraw.h)
Article07/22/2021

Applications use the methods of the IDirectDrawGammaControl interface to adjust the

red, green, and blue gamma ramp levels of the primary surface. This section is a
reference to the methods of this interface.

Inheritance
The IDirectDrawGammaControl interface inherits from the IUnknown interface.
IDirectDrawGammaControl also has these types of members:

Methods
The IDirectDrawGammaControl interface has these methods.

IDirectDrawGammaControl::GetGammaRamp

Retrieves the red, green, and blue gamma ramps for the primary surface.

IDirectDrawGammaControl::SetGammaRamp

Sets the red, green, and blue gamma ramps for the primary surface.

Remarks
The IDirectDrawGammaControl interface is supported by DirectDrawSurface objects.
That is, you can retrieve a pointer to the IDirectDrawGammaControl interface by calling
the IUnknown::QueryInterface method of a DirectDrawSurface object and by specifying
the IID_IDirectDrawGammaControl reference identifier in the riid parameter.

You can use the LPDIRECTDRAWGAMMACONTROL data type to declare a variable that
contains a pointer to an IDirectDrawGammaControl interface. The Ddraw.h header file
declares the data type with the following code:
 typedef struct IDirectDrawGammaControl FAR *LPDIRECTDRAWGAMMACONTROL;

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawGammaControl::GetGamma
Ramp method (ddraw.h)
Article11/01/2022

Retrieves the red, green, and blue gamma ramps for the primary surface.

Syntax
C++

HRESULT GetGammaRamp(
[in] DWORD unnamedParam1,
[in, out] LPDDGAMMARAMP unnamedParam2
);

Parameters
[in] unnamedParam1

Currently not used and must be set to 0.

[in, out] unnamedParam2

A pointer to a DDGAMMARAMP structure that receives the current red, green, and blue
gamma ramps. Each array maps color values in the frame buffer to the color values to
be passed to the digital-to-analog converter (DAC).

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawGammaControl

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawGammaControl::SetGammaR
amp method (ddraw.h)
Article11/01/2022

Sets the red, green, and blue gamma ramps for the primary surface.

Syntax
C++

HRESULT SetGammaRamp(
[in] DWORD unnamedParam1,
[in] LPDDGAMMARAMP unnamedParam2
);

Parameters
[in] unnamedParam1

Flag that indicates whether gamma calibration is required. Set this parameter to
DDSGR_CALIBRATE to request that the calibrator adjust the gamma ramp according to
the physical properties of the display, which makes the result identical on all computers.
If calibration is not needed, set this parameter to 0.

[in] unnamedParam2

A pointer to a DDGAMMARAMP structure that contains the new red, green, and blue
gamma ramp entries. Each array maps color values in the frame buffer to the color
values to be passed to the digital-to-analog converter (DAC).

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
Remarks
Not all systems support gamma calibration. To determine whether gamma calibration is
supported, call IDirectDraw7::GetCaps and examine the dwCaps2 member of the
associated DDCAPS structure after the method returns. If the
DDCAPS2_CANCALIBRATEGAMMA capability flag is present, gamma calibration is
supported.

Calibrating gamma ramps incurs some processing overhead and should not be used
frequently.

Including the DDSGR_CALIBRATE flag in the dwFlags parameter when running on

computers that do not support gamma calibration does not cause this method to fail.
The method succeeds and sets new gamma ramp values without calibration.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawGammaControl

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawPalette interface (ddraw.h)
Article07/22/2021

Applications use the methods of the IDirectDrawPalette interface to create

DirectDrawPalette objects and work with system-level variables. This section is a
reference to the methods of this interface.

Inheritance
The IDirectDrawPalette interface inherits from the IUnknown interface.
IDirectDrawPalette also has these types of members:

Methods
The IDirectDrawPalette interface has these methods.

IDirectDrawPalette::GetCaps

Retrieves the capabilities of the palette object.

IDirectDrawPalette::GetEntries

Retrieves palette values from a DirectDrawPalette object.

IDirectDrawPalette::Initialize

Initializes the DirectDrawPalette object.

IDirectDrawPalette::SetEntries

Changes entries in a DirectDrawPalette object immediately.

Remarks
The methods of the IDirectDrawPalette interface can be organized into the following
groups:

Group Methods

Allocating memory Initialize

 Palette capabilities GetCaps

Palette entries GetEntries and SetEntries

You can use the LPDIRECTDRAWPALETTE data type to declare a variable that contains a
pointer to an IDirectDrawPalette interface. The Ddraw.h header file declares the data
type with the following code:

typedef struct IDirectDrawPalette FAR *LPDIRECTDRAWPALETTE;

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawPalette::GetCaps method
(ddraw.h)
Article11/01/2022

Retrieves the capabilities of the palette object.

Syntax
C++

HRESULT GetCaps(
[out] LPDWORD unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives a value from the dwPalCaps member of the
DDCAPS structure that defines palette capabilities. This value consists of one or more of
the following flags.

DDPCAPS_1BIT
The index is 1 bit. There are two entries in the color table.

DDPCAPS_2BIT
The index is 2 bits. There are four entries in the color table.

DDPCAPS_4BIT
The index is 4 bits. There are 16 entries in the color table.

DDPCAPS_8BIT
The index is 8 bits. There are 256 entries in the color table.
DDPCAPS_8BITENTRIES
The index refers to an 8-bit color index. This flag is valid only when used with the
DDPCAPS_1BIT, DDPCAPS_2BIT, or DDPCAPS_4BIT flag, and when the target surface is 8
bpp. Each color entry is 1 byte long and is an index to a destination surface's 8-bpp
palette.

DDPCAPS_ALPHA
The peFlags member of the associated PALETTEENTRY structure must be interpreted as
a single 8-bit alpha value (in addition to the peRed, peGreen, and peBlue members). A
palette created with this flag can be attached only to a texture: a surface created with
the DDSCAPS_TEXTURE capability flag.

DDPCAPS_ALLOW256
This palette can have all 256 entries defined.

DDPCAPS_PRIMARYSURFACE
This palette is attached to the primary surface. Changing this palette's color table
immediately affects the display unless DDPSETPAL_VSYNC is specified and supported.

DDPCAPS_PRIMARYSURFACELEFT

This palette is the one attached to the left-eye primary surface. Changing this palette's
color table immediately affects the left-eye display unless DDPSETPAL_VSYNC is
specified and supported.

DDPCAPS_VSYNC
This palette can have modifications to it synchronized with the monitor's refresh rate.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawPalette

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawPalette::GetEntries method
(ddraw.h)
Article11/01/2022

Retrieves palette values from a DirectDrawPalette object.

Syntax
C++

HRESULT GetEntries(
[in] DWORD unnamedParam1,
[in] DWORD unnamedParam2,
[in] DWORD unnamedParam3,
[out] LPPALETTEENTRY unnamedParam4
);

Parameters
[in] unnamedParam1

Currently not used and must be set to 0.

[in] unnamedParam2

Start of the entries to be retrieved sequentially.

[in] unnamedParam3

Number of palette entries that can fit in the array that lpEntries specifies. The colors of
the palette entries are returned in sequence, from the value of the dwStartingEntry
parameter through the value of the dwCount parameter minus 1. (These parameters are
set by IDirectDrawPalette::SetEntries.)

[out] unnamedParam4

An array of PALETTEENTRY structures that receives the palette entries from the
DirectDrawPalette object. The palette entries are 1 byte each if the
DDPCAPS_8BITENTRIES flag is set, and 4 bytes otherwise. Each field is a color
description.
Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPALETTIZED

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawPalette

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawPalette::Initialize method
(ddraw.h)
Article11/01/2022

Initializes the DirectDrawPalette object.

Syntax
C++

HRESULT Initialize(
[in] LPDIRECTDRAW unnamedParam1,
[in] DWORD unnamedParam2,
[out] LPPALETTEENTRY unnamedParam3
);

Parameters
[in] unnamedParam1

A pointer to the DirectDraw object to associate with the DirectDrawPalette object.

[in] unnamedParam2

Currently not used and must be set to 0.

[out] unnamedParam3

Currently not used and must be set to NULL.

Return value
This method returns DDERR_ALREADYINITIALIZED.

This method is provided for compliance with the Component Object Model (COM).
Because the DirectDrawPalette object is initialized when it is created, this method always
returns DDERR_ALREADYINITIALIZED.

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawPalette

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawPalette::SetEntries method
(ddraw.h)
Article11/01/2022

Changes entries in a DirectDrawPalette object immediately.

Syntax
C++

HRESULT SetEntries(
[in] DWORD unnamedParam1,
[in] DWORD unnamedParam2,
[in] DWORD unnamedParam3,
[in] LPPALETTEENTRY unnamedParam4
);

Parameters
[in] unnamedParam1

Currently not used and must be set to 0.

[in] unnamedParam2

First entry to be set.

[in] unnamedParam3

Number of palette entries to be changed.

[in] unnamedParam4

An array of PALETTEENTRY structures that contains the palette entries that SetEntries
uses to change the DirectDrawPalette object. The palette entries are 1 byte each if the
DDPCAPS_8BITENTRIES flag is set, and 4 bytes otherwise. Each field is a color
description.

Return value
If the method succeeds, the return value is DD_OK.
If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOPALETTEATTACHED
DDERR_NOTPALETTIZED
DDERR_UNSUPPORTED

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawPalette

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7 interface (ddraw.h)
Article02/16/2023

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 Initialize, IsLost, and Restore

memory
 Attaching AddAttachedSurface, DeleteAttachedSurface, EnumAttachedSurfaces, and
surfaces GetAttachedSurface

BitBltting Blt, BltBatch, BltFast, and GetBltStatus

Color keying GetColorKey and SetColorKey

Device GetDC and ReleaseDC

contexts

Flipping Flip and GetFlipStatus

Locking Lock, PageLock, PageUnlock, and Unlock

surfaces

Miscellaneous GetDDInterface

Overlays AddOverlayDirtyRect, EnumOverlayZOrders, GetOverlayPosition,

SetOverlayPosition, UpdateOverlay, UpdateOverlayDisplay, and
UpdateOverlayZOrder

Private FreePrivateData, GetPrivateData, and SetPrivateData

surface data

Surface GetCaps
capabilities

Surface GetClipper and SetClipper

clipper

Surface ChangeUniquenessValue, GetPixelFormat, GetSurfaceDesc, GetUniquenessValue,

characteristics and SetSurfaceDesc

Surface GetPalette and SetPalette

palettes

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

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::AddAttachedSurfa
ce method (ddraw.h)
Article11/01/2022

Attaches the specified z-buffer surface to this surface.

Syntax
C++

HRESULT AddAttachedSurface(
[in] LPDIRECTDRAWSURFACE7 unnamedParam1
);

Parameters
[in] unnamedParam1

Address of the IDirectDrawSurface7 interface for the surface to be attached.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

Remarks
AddAttachedSurface increments the reference count of the surface being attached. You
can explicitly unattach the surface and decrement its reference count by using the
IDirectDrawSurface7::DeleteAttachedSurface method. Unlike complex surfaces that you
create with a single call to IDirectDraw7::CreateSurface, surfaces attached with this
method are not automatically released. The application must release such surfaces.

You can attach only z-buffer surfaces with this method.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::AddOverlayDirtyR
ect method (ddraw.h)
Article11/01/2022

The IDirectDrawSurface7::AddOverlayDirtyRect method is not currently implemented.

Syntax
C++

HRESULT AddOverlayDirtyRect(
[in] LPRECT unnamedParam1
);

Parameters
[in] unnamedParam1

A pointer to a RECT structure for the rectangle to update.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_UNSUPPORTED

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::Blt method
(ddraw.h)
Article11/01/2022

Performs a bit block transfer (bitblt). This method does not support z-buffering or alpha
blending during bitblt operations.

Syntax
C++

HRESULT Blt(
[in] LPRECT unnamedParam1,
[in] LPDIRECTDRAWSURFACE7 unnamedParam2,
[in] LPRECT unnamedParam3,
[in] DWORD unnamedParam4,
[in] LPDDBLTFX unnamedParam5
);

Parameters
[in] unnamedParam1

A pointer to a RECT structure that defines the upper-left and lower-right points of the
rectangle to bitblt to on the destination surface. If this parameter is NULL, the entire
destination surface is used.

[in] unnamedParam2

A pointer to the IDirectDrawSurface7 interface for the DirectDrawSurface object that is

the source of the bitblt.

[in] unnamedParam3

A pointer to a RECT structure that defines the upper-left and lower-right points of the
rectangle to bitblt from on the source surface. If this parameter is NULL, the entire
source surface is used.

[in] unnamedParam4

A combination of flags that determine the valid members of the associated DDBLTFX
structure, specify color-key information, or request special behavior from the method.
The following flags are defined:

Validation flags

DDBLT_COLORFILL

Uses the dwFillColor member of the DDBLTFX structure as the RGB color that fills the
destination rectangle on the destination surface.

DDBLT_DDFX
Uses the dwDDFX member of the DDBLTFX structure to specify the effects to use for this
bitblt.

DDBLT_DDROPS

Uses the dwDDROP member of the DDBLTFX structure to specify the raster operations
(ROPS) that are not part of the Win32 API.

DDBLT_DEPTHFILL

Uses the dwFillDepth member of the DDBLTFX structure as the depth value with which
to fill the destination rectangle on the destination z-buffer surface.

DDBLT_KEYDESTOVERRIDE
Uses the ddckDestColorkey member of the DDBLTFX structure as the color key for the
destination surface.

DDBLT_KEYSRCOVERRIDE

Uses the ddckSrcColorkey member of the DDBLTFX structure as the color key for the
source surface.

DDBLT_ROP
Uses the dwROP member of the DDBLTFX structure for the ROP for this bitblt. These
ROPs are the same as those defined in the Win32 API.

DDBLT_ROTATIONANGLE
Uses the dwRotationAngle member of the DDBLTFX structure as the rotation angle
(specified in 1/100s of a degree) for the surface.

Color key flags

DDBLT_KEYDEST
Uses the color key that is associated with the destination surface.

DDBLT_KEYSRC
Uses the color key that is associated with the source surface.

Behavior flags

DDBLT_ASYNC

Performs this bitblt asynchronously through the first in, first out (FIFO) hardware in the
order received. If no room is available in the FIFO hardware, the call fails.

DDBLT_DONOTWAIT

Returns without bitbltting and also returns DDERR_WASSTILLDRAWING if the bitbltter is

busy.

DDBLT_WAIT
Postpones the DDERR_WASSTILLDRAWING return value if the bitbltter is busy, and
returns as soon as the bitblt can be set up or another error occurs.

Obsolete and unsupported flags

All DDBLT_ALPHA flag values

Not currently implemented.

All DDBLT_ZBUFFER flag values

This method does not currently support z-aware bitblt operations. None of the flags
beginning with "DDBLT_ZBUFFER" are supported.
[in] unnamedParam5

A pointer to the DDBLTFX structure for the bitblt.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error 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

Remarks
Blt can perform synchronous or asynchronous bitblts (the latter is the default behavior).
These bitblts can occur from display memory to display memory, from display memory
to system memory, from system memory to display memory, or from system memory to
system memory. The bitblts can be performed by using source color keys and
destination color keys. Arbitrary stretching or shrinking is performed if the source and
destination rectangles are not the same size.

Typically, Blt returns immediately with an error if the bitbltter is busy and the bitblt
could not be set up. Specify the DDBLT_WAIT flag to request a synchronous bitblt. When
you include the DDBLT_WAIT flag, Blt waits until the bitblt can be set up or another error
occurs before it returns.

RECT structures are defined so that the right and bottom members are exclusive—
therefore, right minus left equals the width of the rectangle, not 1 less than the width.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::BltBatch method
(ddraw.h)
Article11/01/2022

The IDirectDrawSurface7::BltBatch method is not currently implemented.

Syntax
C++

HRESULT BltBatch(
[in] LPDDBLTBATCH unnamedParam1,
[in] DWORD unnamedParam2,
[in] DWORD unnamedParam3
);

Parameters
[in] unnamedParam1

A pointer to the first DDBLTBATCH structure that defines the parameters for the bitblt
operations.

[in] unnamedParam2

Number of bitblt operations to be performed.

[in] unnamedParam3

Currently not used and must be set to 0.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error 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

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::BltFast method
(ddraw.h)
Article11/01/2022

Performs a source copy bitblt or transparent bitblt by using a source color key or
destination color key.

Syntax
C++

HRESULT BltFast(
[in] DWORD unnamedParam1,
[in] DWORD unnamedParam2,
[in] LPDIRECTDRAWSURFACE7 unnamedParam3,
[in] LPRECT unnamedParam4,
[in] DWORD unnamedParam5
);

Parameters
[in] unnamedParam1

The x-coordinate to bitblt to on the destination surface.

[in] unnamedParam2

The y-coordinate to bitblt to on the destination surface.

[in] unnamedParam3

A pointer to the IDirectDrawSurface7 interface for the DirectDrawSurface object that is

the source of the bitblt.

[in] unnamedParam4

A pointer to a RECT structure that defines the upper-left and lower-right points of the
rectangle to bitblt from on the source surface.

[in] unnamedParam5

Type of transfer. The following transfers are defined:

DDBLTFAST_DESTCOLORKEY
A transparent bitblt that uses the destination color key.

DDBLTFAST_NOCOLORKEY

A normal copy bitblt with no transparency.

DDBLTFAST_SRCCOLORKEY

A transparent bitblt that uses the source color key.

DDBLTFAST_WAIT

Postpones the DDERR_WASSTILLDRAWING message if the bitbltter is busy, and returns

as soon as the bitblt can be set up or another error occurs.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_EXCEPTION
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Remarks
BltFast always attempts an asynchronous blit if it is supported by the hardware.

BltFast works only on display memory surfaces and cannot clip when it performs a bitblt
operation. If you use this method on a surface with an attached clipper, the call fails, and
the method returns DDERR_UNSUPPORTED.
The software implementation of IDirectDrawSurface7::BltFast is 10 percent faster than
the IDirectDrawSurface7::Blt method. However, there is no speed difference between the
two if display hardware is used.

Typically, IDirectDrawSurface7::BltFast returns immediately with an error if the bitbltter

is busy and the bitblt cannot be set up. You can use the DDBLTFAST_WAIT flag, however,
if you want this method not to return until either the bitblt can be set up or another
error occurs.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::ChangeUniquenes
sValue method (ddraw.h)
Article11/01/2022

Manually updates the uniqueness value for this surface.

Syntax
C++

HRESULT ChangeUniquenessValue();

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
DirectDraw automatically updates uniqueness values whenever the contents of a surface
change.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll
See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::DeleteAttachedSur
face method (ddraw.h)
Article11/01/2022

Detaches one or more attached surfaces.

Syntax
C++

HRESULT DeleteAttachedSurface(
[in] DWORD unnamedParam1,
[in] LPDIRECTDRAWSURFACE7 unnamedParam2
);

Parameters
[in] unnamedParam1

Currently not used and must be set to 0.

[in] unnamedParam2

A pointer to the IDirectDrawSurface7 interface for the DirectDrawSurface object to be

detached. If this parameter is NULL, all attached surfaces become detached.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_CANNOTDETACHSURFACE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_SURFACENOTATTACHED

Remarks
DeleteAttachedSurface decrements the reference count of the surface to be detached.
If the reference count of the surface to be detached reaches 0, the surface is lost and
removed from memory.

Implicit attachments, those formed by DirectDraw rather than the

IDirectDrawSurface7::AddAttachedSurface method, cannot be detached. Detaching
surfaces from a flipping chain can alter other surfaces in the chain. If a front buffer is
detached from a flipping chain, the next surface in the chain becomes the front buffer,
and the following surface becomes the back buffer. If a back buffer is detached from a
chain, the following surface becomes a back buffer. If a plain surface is detached from a
chain, the chain simply becomes shorter. If a flipping chain has only two surfaces and
they are detached, the chain is destroyed, and both surfaces return to their previous
designations.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::EnumAttachedSurf
aces method (ddraw.h)
Article11/01/2022

Enumerates all the surfaces that are attached to this surface.

Syntax
C++

HRESULT EnumAttachedSurfaces(
[in] LPVOID unnamedParam1,
[in] LPDDENUMSURFACESCALLBACK7 unnamedParam2
);

Parameters
[in] unnamedParam1

Address of the application-defined structure that is passed to the enumeration member

every time that it is called.

[in] unnamedParam2

Address of the EnumSurfacesCallback7 function to be called for each surface that is

attached to this surface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

Remarks
EnumAttachedSurfaces enumerates only those surfaces that are directly attached to this
surface. For example, in a flipping chain of three or more surfaces, only one surface is
enumerated because each surface is attached only to the next surface in the flipping
chain. In such a configuration, you can call EnumAttachedSurfaces on each successive
surface to walk the entire flipping chain.

EnumAttachedSurfaces differs from its counterparts in previous interface versions in

that it accepts a pointer to an EnumSurfacesCallback7 function, rather than an
EnumSurfacesCallback or EnumSurfacesCallback2 function.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::EnumOverlayZOrd
ers method (ddraw.h)
Article11/01/2022

Enumerates the overlay surfaces on the specified destination. You can enumerate the
overlays in front-to-back or back-to-front order.

Syntax
C++

HRESULT EnumOverlayZOrders(
[in] DWORD unnamedParam1,
[in] LPVOID unnamedParam2,
[in] LPDDENUMSURFACESCALLBACK7 unnamedParam3
);

Parameters
[in] unnamedParam1

A value that can be set to one of the following flags:

DDENUMOVERLAYZ_BACKTOFRONT

Enumerates overlays back to front.

DDENUMOVERLAYZ_FRONTTOBACK

Enumerates overlays front to back.

[in] unnamedParam2

Address of the user-defined structure to be passed to the callback function for each
overlay surface.

[in] unnamedParam3

Address of the EnumSurfacesCallback7 callback function to be called for each surface to

be overlaid on this surface.
Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
EnumOverlayZOrders differs from its counterparts in previous interface versions in that
it accepts a pointer to an EnumSurfacesCallback7 function, rather than an
EnumSurfacesCallback or EnumSurfacesCallback2 function.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::Flip method
(ddraw.h)
Article11/01/2022

Makes the surface memory that is associated with the DDSCAPS_BACKBUFFER surface
become associated with the front-buffer surface.

Syntax
C++

HRESULT Flip(
[in] LPDIRECTDRAWSURFACE7 unnamedParam1,
[in] DWORD unnamedParam2
);

Parameters
[in] unnamedParam1

A pointer to the IDirectDrawSurface7 interface for an arbitrary surface in the flipping

chain. The default for this parameter is NULL, in which case DirectDraw cycles through
the buffers in the order that they are attached to each other. If this parameter is not
NULL, DirectDraw flips to the specified surface, instead of the next surface in the flipping
chain. Flip fails if the specified surface is not a member of the flipping chain.

[in] unnamedParam2

A combination of flags that specify flip options. The following flags are defined:

DDFLIP_DONOTWAIT
On IDirectDrawSurface7 interfaces, the default is DDFLIP_WAIT. If you want to override
the default and use time when the accelerator is busy (as denoted by the
DDERR_WASSTILLDRAWING return value), use DDFLIP_DONOTWAIT.

DDFLIP_EVEN
For use only when displaying video in an overlay surface. The new surface contains data
from the even field of a video signal. This flag cannot be used with the DDFLIP_ODD
flag.

DDFLIP_STEREO
DirectDraw flips and displays a main stereo surface. When this flag is set, stereo
autoflipping is enabled. The hardware automatically flips between the left and right
buffers during each screen refresh.

DDFLIP_INTERVAL2

DDFLIP_INTERVAL3

DDFLIP_INTERVAL4
The DDFLIP_INTERVAL2, DDFLIP_INTERVAL3, and DDFLIP_INTERVAL4 flags indicate how
many vertical retraces to wait between each flip. The default is 1. DirectDraw returns
DERR_WASSTILLDRAWING for each surface involved in the flip until the specified
number of vertical retraces has occurred. If DDFLIP_INTERVAL2 is set, DirectDraw flips on
every second vertical sync; if DDFLIP_INTERVAL3, on every third sync; and if
DDFLIP_INTERVAL4, on every fourth sync.

These flags are effective only if DDCAPS2_FLIPINTERVAL bit is set in the dwCaps2
member of the DDCAPS structure that is returned for the display hardware.

DDFLIP_NOVSYNC

Causes DirectDraw to perform the physical flip as close as possible to the next scan line.
Subsequent operations that involve the two flipped surfaces do not check whether the
physical flip has finished—that is, they do not return DDERR_WASSTILLDRAWING for
that reason (but might for other reasons). This allows an application to perform flips at a
higher frequency than the monitor refresh rate, but might introduce visible artifacts.

If DDCAPS2_FLIPNOVSYNC is not set in the dwCaps2 member of the DDCAPS structure

that is returned for the display hardware, DDFLIP_NOVSYNC has no effect.

DDFLIP_ODD
For use only when displaying video in an overlay surface. The new surface contains data
from the odd field of a video signal. This flag cannot be used with the DDFLIP_EVEN
flag.

DDFLIP_WAIT
Typically, if the flip cannot be set up because the state of the display hardware is not
appropriate, the DDERR_WASSTILLDRAWING error returns immediately, and no flip
occurs. Setting this flag causes Flip to continue trying to flip if it receives the
DDERR_WASSTILLDRAWING error from the hardware abstraction layer (HAL). Flip does
not return until the flipping operation has been successfully set up or another error,
such as DDERR_SURFACEBUSY, is returned.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Remarks
With IDirectDrawSurface7, the default behavior of Flip is to wait for the accelerator to
finish. Therefore, under default conditions, Flip never returns
DDERR_WASSTILLDRAWING. If you want to see the error codes and not wait until the
flip operation succeeds, use the DDFLIP_DONOTWAIT flag.

Flip can be called only for a surface that has the DDSCAPS_FLIP and
DDSCAPS_FRONTBUFFER capabilities. The display memory previously associated with
the front buffer is associated with the back buffer.
The lpDDSurfaceTargetOverride parameter is used in rare cases in which the back buffer
is not the buffer that should become the front buffer. Typically, this parameter is NULL.

Flip is always synchronized with the vertical blank. If the surface has been assigned to a
video port, this method updates the visible overlay surface and the target surface of the
video port.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::FreePrivateData
method (ddraw.h)
Article11/01/2022

Frees the specified private data that is associated with this surface.

Syntax
C++

HRESULT FreePrivateData(
[in] REFGUID unnamedParam1
);

Parameters
[in] unnamedParam1

Reference to (C++) or address of (C) the globally unique identifier that identifies the
private data to be freed.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

Remarks
DirectDraw calls this method automatically when a surface is released.

If the private data was set by using the DDSPD_IUNKNOWNPOINTER flag,

FreePrivateData calls the IUnknown::Release method on the associated interface.
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetAttachedSurfac
e method (ddraw.h)
Article11/01/2022

Obtains the attached surface that has the specified capabilities, and increments the
reference count of the retrieved interface.

Syntax
C++

HRESULT GetAttachedSurface(
[in] LPDDSCAPS2 unnamedParam1,
[out] LPDIRECTDRAWSURFACE7 *unnamedParam2
);

Parameters
[in] unnamedParam1

A pointer to a DDSCAPS2 structure that indicates the hardware capabilities of the

attached surface.

[out] unnamedParam2

A pointer to a variable to receive a pointer to the retrieved surface's

IDirectDrawSurface7 interface. The retrieved surface is the one that matches the
description, according to the lpDDSCaps parameter.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST
Remarks
Attachments are used to connect multiple DirectDrawSurface objects into complex
structures, like the complex structures required to support 3-D page flipping with z-
buffers. GetAttachedSurface fails if more than one surface is attached that matches the
capabilities requested. In this case, the application must use the
IDirectDrawSurface7::EnumAttachedSurfaces method to obtain the attached surfaces.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetBltStatus
method (ddraw.h)
Article11/01/2022

Obtains status about a bit block transfer (bitblt) operation.

Syntax
C++

HRESULT GetBltStatus(
[in] DWORD unnamedParam1
);

Parameters
[in] unnamedParam1

A value that can be set to one of the following flags.

DDGBS_CANBLT
Inquires whether a bitblt that involves this surface can occur immediately, and returns
DD_OK if the bitblt can be completed.

DDGBS_ISBLTDONE

Inquires whether the bitblt is done, and returns DD_OK if the last bitblt on this surface
has completed.

Return value
If the method succeeds, a bitbltter is present, and the return value is DD_OK.

If it fails, the method returns DDERR_WASSTILLDRAWING if the bitbltter is busy,

DDERR_NOBLTHW if there is no bitbltter, or one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
 DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetCaps method
(ddraw.h)
Article11/01/2022

Retrieves the capabilities of this surface. These capabilities are not necessarily related to
the capabilities of the display device.

Syntax
C++

HRESULT GetCaps(
[in] LPDDSCAPS2 unnamedParam1
);

Parameters
[in] unnamedParam1

A pointer to a DDSCAPS2 structure that receives the hardware capabilities of this

surface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
The IDirectDrawSurface7::GetCaps method differs from its counterpart in the
IDirectDrawSurface3 interface in that it accepts a pointer to a DDSCAPS2 structure,
rather than the legacy DDSCAPS structure.

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetClipper
method (ddraw.h)
Article11/01/2022

Retrieves the DirectDrawClipper object that is associated with this surface, and
increments the reference count of the returned clipper.

Syntax
C++

HRESULT GetClipper(
[out] LPDIRECTDRAWCLIPPER *unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable to receive a pointer to the clipper's IDirectDrawClipper interface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPPERATTACHED

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetColorKey
method (ddraw.h)
Article11/01/2022

Retrieves the color key value for this surface.

Syntax
C++

HRESULT GetColorKey(
[in] DWORD unnamedParam1,
[out] LPDDCOLORKEY unnamedParam2
);

Parameters
[in] unnamedParam1

A value that can be set to one of the following flags to specify the color key to retrieve:

DDCKEY_DESTBLT
A color key or color space to be used as a destination color key for bit block transfer
(bitblt) operations.

DDCKEY_DESTOVERLAY

A color key or color space to be used as a destination color key for overlay operations.

DDCKEY_SRCBLT

A color key or color space to be used as a source color key for bitblt operations.

DDCKEY_SRCOVERLAY

A color key or color space to be used as a source color key for overlay operations.

[out] unnamedParam2
A pointer to a DDCOLORKEY structure that receives the current values for the specified
color key of the DirectDrawSurface object.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOLORKEY
DDERR_NOCOLORKEYHW
DDERR_SURFACELOST
DDERR_UNSUPPORTED

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetDC method
(ddraw.h)
Article11/01/2022

Creates a GDI-compatible handle of a device context for this surface.

Syntax
C++

HRESULT GetDC(
[out] HDC *unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the handle of the device context for this surface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Remarks
GetDC uses an internal version of the IDirectDrawSurface7::Lock method to lock the
surface. The surface remains locked until the IDirectDrawSurface7::ReleaseDC method is
called.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetDDInterface
method (ddraw.h)
Article11/01/2022

Retrieves an interface to the DirectDraw object that was used to create this surface.

Syntax
C++

HRESULT GetDDInterface(
[out] LPVOID *unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives a valid interface pointer if the call succeeds. Cast
this pointer to an IUnknown interface pointer; then query for the IDirectDraw7 interface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetFlipStatus
method (ddraw.h)
Article11/01/2022

Retrieves status about whether this surface has finished its flipping process.

Syntax
C++

HRESULT GetFlipStatus(
[in] DWORD unnamedParam1
);

Parameters
[in] unnamedParam1

A value that can be set to one of the following flags:

DDGFS_CANFLIP
Inquires whether this surface can be flipped immediately, and returns DD_OK if the flip
can be completed.

DDGFS_ISFLIPDONE

Inquires whether the flip has finished, and returns DD_OK if the last flip on this surface
has completed.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return DDERR_WASSTILLDRAWING if the surface has not
finished its flipping process, or one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
 DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetLOD method
(ddraw.h)
Article11/01/2022

Retrieves the maximum level of detail (LOD) currently set for a managed mipmap
surface. This method succeeds only on managed textures.

Syntax
C++

HRESULT GetLOD(
[out] LPDWORD unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the maximum LOD value if the call succeeds.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
Applications can call this method only for managed textures (those surfaces that were
created with the DDSCAPS2_TEXTUREMANAGE flag). If you call GetLOD on a
nonmanaged texture, GetLOD fails and returns DDERR_INVALIDOBJECT.

GetLOD communicates to the Direct3D texture manager the most detailed mipmap in
this chain that it should load into local video memory. For example, in a five-level
mipmap chain, a value of 2 in the variable at lpdwMaxLOD indicates that the texture
manager loads only mipmap levels 2 through 4 into local video memory at any given
time. Likewise, if the most detailed mipmap in the chain has the dimensions 256×256, a
value of 2 in lpdwMaxLOD means that the largest mipmap ever present in video memory
has dimensions 64×64.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetOverlayPositio
n method (ddraw.h)
Article11/01/2022

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).

Syntax
C++

HRESULT GetOverlayPosition(
[out] LPLONG unnamedParam1,
[out] LPLONG unnamedParam2
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the x- display coordinate of this surface if the call
succeeds.

[out] unnamedParam2

A pointer to a variable that receives the y-display coordinate of this surface if the call
succeeds.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
 DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetPalette method
(ddraw.h)
Article11/01/2022

Retrieves the DirectDrawPalette object that is associated with this surface, and
increments the reference count of the returned palette.

Syntax
C++

HRESULT GetPalette(
[out] LPDIRECTDRAWPALETTE *unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable to receive a pointer to the palette object's IDirectDrawPalette

interface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetPixelFormat
method (ddraw.h)
Article11/01/2022

Retrieves the color and pixel format of this surface.

Syntax
C++

HRESULT GetPixelFormat(
[out] LPDDPIXELFORMAT unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a DDPIXELFORMAT structure that receives a detailed description of the

current pixel and color space format of this surface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetPriority
method (ddraw.h)
Article11/01/2022

Retrieves the texture-management priority for this texture. This method succeeds only
on managed textures.

Syntax
C++

HRESULT GetPriority(
[out] LPDWORD unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the texture priority if the call succeeds.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the return value is an error. The method returns DDERR_INVALIDOBJECT if the
parameter is invalid or if the texture is not managed by Direct3D.

Remarks
Priorities are used to determine when managed textures are to be removed from
memory. A texture assigned a low priority is removed before a texture with a high
priority. If two textures have the same priority, the texture that was used more recently is
kept in memory; the other texture is removed.

Applications can set and retrieve priorities only for managed textures (those surfaces
that were created with the DDSCAPS2_TEXTUREMANAGE flag). If you call GetPriority on
a nonmanaged texture, GetPriority fails and returns DDERR_INVALIDOBJECT.
GetPriority was introduced with the IDirectDrawSurface7 interface.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetPrivateData
method (ddraw.h)
Article11/01/2022

Copies the private data that is associated with this surface to a provided buffer.

Syntax
C++

HRESULT GetPrivateData(
[in] REFGUID unnamedParam1,
[out] LPVOID unnamedParam2,
[in, out] LPDWORD unnamedParam3
);

Parameters
[in] unnamedParam1

Reference to (C++) or address of (C) the globally unique identifier that identifies the
private data to be retrieved.

[out] unnamedParam2

A pointer to a previously allocated buffer that receives the requested private data if the
call succeeds. The application that calls this method must allocate and release this
buffer.

[in, out] unnamedParam3

A pointer to a variable that contains the size value of the buffer at lpBuffer, in bytes. If
this value is less than the actual size of the private data (such as 0), GetPrivateData sets
the variable to the required buffer size, and then returns DDERR_MOREDATA.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:
 DDERR_EXPIRED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA
DDERR_NOTFOUND
DDERR_OUTOFMEMORY

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetSurfaceDesc
method (ddraw.h)
Article11/01/2022

Retrieves a description of this surface in its current condition.

Syntax
C++

HRESULT GetSurfaceDesc(
[in, out] LPDDSURFACEDESC2 unnamedParam1
);

Parameters
[in, out] unnamedParam1

A pointer to a DDSURFACEDESC2 structure that receives the current description of this

surface. You need only initialize this structure's dwSize member to the size, in bytes, of
the structure prior to the call; no other preparation is required.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::GetUniquenessVal
ue method (ddraw.h)
Article11/01/2022

Retrieves the current uniqueness value for this surface.

Syntax
C++

HRESULT GetUniquenessValue(
[out] LPDWORD unnamedParam1
);

Parameters
[out] unnamedParam1

A pointer to a variable that receives the surface's current uniqueness value if the call
succeeds.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
The only defined uniqueness value is 0, which indicates that the surface is likely to be
changing beyond the control of DirectDraw. Other uniqueness values are significant
only if they differ from a previously cached uniqueness value. If the current value is
different from a cached value, the contents of the surface have changed.

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::Initialize method
(ddraw.h)
Article11/01/2022

Initializes a DirectDrawSurface object.

Syntax
C++

HRESULT Initialize(
[in] LPDIRECTDRAW unnamedParam1,
[in] LPDDSURFACEDESC2 unnamedParam2
);

Parameters
[in] unnamedParam1

A pointer to the DirectDraw object to associate with the DirectDrawSurface object.

[in] unnamedParam2

A pointer to a DDSURFACEDESC2 structure that describes how to initialize this surface.

Return value
This method returns DDERR_ALREADYINITIALIZED.

This method is provided for compliance with the Component Object Model (COM).
Because the DirectDrawSurface object is initialized when it is created, this method
always returns DDERR_ALREADYINITIALIZED.

Requirements

Target Platform Windows

Header ddraw.h
 Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::IsLost method
(ddraw.h)
Article11/01/2022

Determines whether the surface memory that is associated with a DirectDrawSurface

object has been freed.

Syntax
C++

HRESULT IsLost();

Return value
If the method succeeds, the return value is DD_OK because the memory has not been
freed.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

You can use this method to determine when you need to reallocate surface memory.
When a DirectDrawSurface object loses its surface memory, most methods return
DDERR_SURFACELOST and perform no other action.

Remarks
Surfaces can lose their memory when the mode of the graphics adapter is changed or
when an application receives exclusive access to the graphics adapter and frees all
surface memory that is currently allocated on the graphics adapter.

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::Lock method
(ddraw.h)
Article11/01/2022

Obtains a pointer to the surface memory.

Syntax
C++

HRESULT Lock(
[in] LPRECT unnamedParam1,
[in, out] LPDDSURFACEDESC2 unnamedParam2,
[in] DWORD unnamedParam3,
[in] HANDLE unnamedParam4
);

Parameters
[in] unnamedParam1

A pointer to a RECT structure that identifies the region of the surface that is being
locked. If this parameter is NULL, the entire surface is locked.

[in, out] unnamedParam2

A pointer to a DDSURFACEDESC2 structure that describes relevant details about the

surface and that receives information about the surface.

[in] unnamedParam3

A combination of flags that determine how to lock the surface. The following flags are
defined:

DDLOCK_DONOTWAIT
On IDirectDrawSurface7 interfaces, the default is DDLOCK_WAIT. If you want to override
the default and use time when the accelerator is busy (as denoted by the
DDERR_WASSTILLDRAWING return value), use DDLOCK_DONOTWAIT.
DDLOCK_EVENT
Not currently implemented.

DDLOCK_NOOVERWRITE

New for DirectX 7.0. Used only with Direct3D vertex-buffer locks. Indicates that no
vertices that were referred to in a draw operation since the start of the frame (or the last
lock without this flag) are modified during the lock. This can be useful when you want
only to append data to the vertex buffer.

DDLOCK_NOSYSLOCK
Do not take the Win16Mutex (also known as Win16Lock). This flag is ignored when
locking the primary surface.

DDLOCK_DISCARDCONTENTS
New for DirectX 7.0. Used only with Direct3D vertex-buffer locks. Indicates that no
assumptions are made about the contents of the vertex buffer during this lock. This
enables Direct3D or the driver to provide an alternative memory area as the vertex
buffer. This is useful when you plan to clear the contents of the vertex buffer and fill in
new data.

DDLOCK_OKTOSWAP
This flag is obsolete and was replaced by the DDLOCK_DISCARDCONTENTS flag.

DDLOCK_READONLY
Indicates that the surface being locked can only be read.

DDLOCK_SURFACEMEMORYPTR
Indicates that a valid memory pointer to the top of the specified rectangle should be
returned. If no rectangle is specified, a pointer to the top of the surface is returned. This
is the default.

DDLOCK_WAIT
If a lock cannot be obtained because a bit block transfer (bitblt) operation is in progress,
Lock retries until a lock is obtained or another error occurs, such as
DDERR_SURFACEBUSY.

DDLOCK_WRITEONLY
Indicates that the surface being locked is write-enabled.

[in] unnamedParam4

Handle of the event. This parameter is not currently used and must be set to NULL.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

Remarks
In IDirectDrawSurface7, the default behavior of Lock is to wait for the accelerator to
finish. Therefore, under default conditions, Lock never returns
DDERR_WASSTILLDRAWING. If you want to see the error codes and not wait until the
bitblt operation succeeds, use the DDLOCK_DONOTWAIT flag.

After retrieving a surface memory pointer, you can access the surface memory until a
corresponding IDirectDrawSurface7::Unlock method is called. When the surface is
unlocked, the pointer to the surface memory is invalid.

Do not call DirectDraw bitblt functions to bitblt from a locked region of a surface. If you
do, the bitblt returns either DDERR_SURFACEBUSY or DDERR_LOCKEDSURFACES. GDI blit
functions also silently fail when used on a locked video memory surface.

Unless you include the DDLOCK_NOSYSLOCK flag, Lock causes DirectDraw to hold the
Win16Mutex (also known as Win16Lock) until you call the IDirectDrawSurface7::Unlock
method. GUI debuggers cannot operate while the Win16Mutex is held.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::PageLock method
(ddraw.h)
Article11/01/2022

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.

Syntax
C++

HRESULT PageLock(
[in] DWORD unnamedParam1
);

Parameters
[in] unnamedParam1

Currently not used and must be set to 0.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_CANTPAGELOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

Remarks
You must call PageLock to make use of DMA support. If you do not, the bitblt occurs by
using software emulation.
The performance of the operating system can be negatively affected if too much
memory is locked.

A lock count is maintained for each surface and is incremented each time that PageLock
is called for that surface. The count is decremented when
IDirectDrawSurface7::PageUnlock is called. When the count reaches 0, the memory is
unlocked, and can then be paged by the operating system.

PageLock works only on system-memory surfaces; it does not page-lock a display-

memory surface or an emulated primary surface. If an application calls PageLock on a
display memory surface, the method does nothing except return DD_OK.

IDirectDrawSurface7::PageLock was not implemented in the IDirectDraw interface

version.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::PageUnlock
method (ddraw.h)
Article11/01/2022

Unlocks a system-memory surface, which then allows it to be paged out.

Syntax
C++

HRESULT PageUnlock(
[in] DWORD unnamedParam1
);

Parameters
[in] unnamedParam1

Currently not used and must be set to 0.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_CANTPAGEUNLOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPAGELOCKED
DDERR_SURFACELOST

Remarks
A lock count is maintained for each surface and is incremented each time that
IDirectDrawSurface7::PageLock is called for that surface. The count is decremented when
PageUnlock is called. When the count reaches 0, the memory is unlocked, and can then
be paged by the operating system.
PageUnlock works only on system-memory surfaces; it does not page-unlock a display-
memory surface or an emulated primary surface. If an application calls PageUnlock on a
display memory surface, the method does nothing except return DD_OK.

IDirectDrawSurface7::PageUnlock was not implemented in the IDirectDraw interface

version.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::ReleaseDC method
(ddraw.h)
Article11/01/2022

Releases the handle of a device context that was previously obtained by using the
IDirectDrawSurface7::GetDC method.

Syntax
C++

HRESULT ReleaseDC(
[in] HDC unnamedParam1
);

Parameters
[in] unnamedParam1

The handle of a device context that was previously obtained by

IDirectDrawSurface7::GetDC.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_UNSUPPORTED

Remarks
ReleaseDC also unlocks the surface that was previously locked when the
IDirectDrawSurface7::GetDC method was called.
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::Restore method
(ddraw.h)
Article11/01/2022

Restores a surface that has been lost. This occurs when the surface memory that is
associated with the DirectDrawSurface object has been freed.

Syntax
C++

HRESULT Restore();

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

Remarks
Restore restores the memory that was allocated for a surface, but does not reload any
bitmaps that might have existed in the surface before it was lost.

Surfaces can be lost because the mode of the graphics adapter was changed or because
an application received exclusive access to the graphics adapter and freed all surface
memory currently allocated on the adapter. When a DirectDrawSurface object loses its
surface memory, many methods return DDERR_SURFACELOST and perform no other
function. The IDirectDrawSurface7::Restore method reallocates surface memory and
reattaches it to the DirectDrawSurface object.

A single call to Restore restores a DirectDrawSurface object's associated implicit surfaces

(back buffers, and so on). An attempt to restore an implicitly created surface results in
an error. Restore does not work across explicit attachments that were created by using
the IDirectDrawSurface7::AddAttachedSurface method—each of these surfaces must be
restored individually.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::SetClipper method
(ddraw.h)
Article11/01/2022

Attaches a clipper object to, or deletes one from, this surface.

Syntax
C++

HRESULT SetClipper(
[in] LPDIRECTDRAWCLIPPER unnamedParam1
);

Parameters
[in] unnamedParam1

A pointer to the IDirectDrawClipper interface for the DirectDrawClipper object to be

attached to the DirectDrawSurface object. If you set this parameter to NULL, the current
DirectDrawClipper object is detached.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOCLIPPERATTACHED

Remarks
When you set a clipper to a surface for the first time, SetClipper increments the clipper's
reference count; subsequent calls do not affect the clipper's reference count. If you pass
NULL as the lpDDClipper parameter, the clipper is removed from the surface, and the
clipper's reference count is decremented. If you do not delete the clipper, the surface
automatically releases its reference to the clipper when the surface itself is released.
According to COM rules, your application must release any references that it holds to
the clipper when the object is no longer needed.

SetClipper is primarily used by surfaces that are being overlaid on or bitbltted to the
primary surface. However, it can be used on any surface. After a DirectDrawClipper
object has been attached and a clip list is associated with it, the DirectDrawClipper
object is used for the IDirectDrawSurface7::Blt, IDirectDrawSurface7::BltBatch, and
IDirectDrawSurface7::UpdateOverlay operations that involve the parent
DirectDrawSurface object. SetClipper can also detach the current DirectDrawClipper
object of a DirectDrawSurface object.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::SetColorKey
method (ddraw.h)
Article11/01/2022

Sets the color key value for the DirectDrawSurface object if the hardware supports color
keys on a per-surface basis.

Syntax
C++

HRESULT SetColorKey(
[in] DWORD unnamedParam1,
[in] LPDDCOLORKEY unnamedParam2
);

Parameters
[in] unnamedParam1

A value that can be set to one of the following flags to specify the requested color key:

DDCKEY_COLORSPACE

The structure contains a color space. Not set if the structure contains a single color key.

DDCKEY_DESTBLT

A color key or color space to be used as a destination color key for bit block transfer
(bitblt) operations.

DDCKEY_DESTOVERLAY
A color key or color space to be used as a destination color key for overlay operations.

DDCKEY_SRCBLT
A color key or color space to be used as a source color key for bitblt operations.
DDCKEY_SRCOVERLAY
A color key or color space to be used as a source color key for overlay operations.

[in] unnamedParam2

A pointer to a DDCOLORKEY structure that contains the new color key values for the
DirectDrawSurface object. This value can be NULL to remove a previously set color key.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOOVERLAYHW
DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Remarks
For transparent bitblt operations and overlays, set destination color on the destination
surface and source color on the source surface.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll
See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::SetLOD method
(ddraw.h)
Article11/01/2022

Sets the maximum level of detail (LOD) for a managed mipmap surface. This method
succeeds only on managed textures.

Syntax
C++

HRESULT SetLOD(
[in] DWORD unnamedParam1
);

Parameters
[in] unnamedParam1

The maximum LOD value to be set for the mipmap chain if the call succeeds.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks
Applications can call this method only for managed textures (those surfaces that were
created with the DDSCAPS2_TEXTUREMANAGE flag). If you call SetLOD on a
nonmanaged texture, SetLOD fails and returns DDERR_INVALIDOBJECT.

SetLOD communicates to the Direct3D texture manager the most detailed mipmap in
this chain that it should load into local video memory. For example, in a five-level
mipmap chain, if you set dwMaxLOD to 2, the texture manager should load only
mipmap levels 2 through 4 into local video memory at any given time. Likewise, if the
most detailed mipmap in the chain has the dimensions 256×256, setting the maximum
level to 2 means that the largest mipmap ever present in video memory has dimensions
64×64.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::SetOverlayPosition
method (ddraw.h)
Article11/01/2022

Changes the display coordinates of an overlay surface.

Syntax
C++

HRESULT SetOverlayPosition(
[in] LONG unnamedParam1,
[in] LONG unnamedParam2
);

Parameters
[in] unnamedParam1

The new x- display coordinate of this surface.

[in] unnamedParam2

The new y-display coordinate of this surface.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::SetPalette method
(ddraw.h)
Article11/01/2022

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.

Syntax
C++

HRESULT SetPalette(
[in] LPDIRECTDRAWPALETTE unnamedParam1
);

Parameters
[in] unnamedParam1

A pointer to the IDirectDrawPalette interface for the palette object to be used with this
surface. If NULL, the current palette is detached.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_SURFACELOST
 DDERR_UNSUPPORTED

Remarks
When you call SetPalette to set a palette to a surface for the first time, SetPalette
increments the palette's reference count; subsequent calls to SetPalette do not affect
the palette's reference count. If you pass NULL as the lpDDPalette parameter, the palette
is removed from the surface, and the palette's reference count is decremented. If you do
not delete the palette, the surface automatically releases its reference to the palette
when the surface itself is released. According to COM rules, your application must
release any references that it holds to the palette when the object is no longer needed.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::SetPriority method
(ddraw.h)
Article11/01/2022

Assigns the texture-management priority for this texture. This method succeeds only on
managed textures.

Syntax
C++

HRESULT SetPriority(
[in] DWORD unnamedParam1
);

Parameters
[in] unnamedParam1

A value that specifies the new texture-management priority for the texture.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the return value is an error. The method returns DDERR_INVALIDOBJECT if the
parameter is invalid or if the texture is not managed by Direct3D.

Remarks
SetPriority was introduced with the IDirectDrawSurface7 interface.

Priorities are used to determine when managed textures are to be removed from
memory. A texture assigned a low priority is removed before a texture with a high
priority. If two textures have the same priority, the texture that was used more recently is
kept in memory; the other texture is removed.

Applications can set and retrieve priorities only for managed textures (those surfaces
that were created with the DDSCAPS2_TEXTUREMANAGE flag). If you call SetPriority on
a nonmanaged texture, SetPriority fails and returns DDERR_INVALIDOBJECT.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::SetPrivateData
method (ddraw.h)
Article11/01/2022

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.

Syntax
C++

HRESULT SetPrivateData(
[in] REFGUID unnamedParam1,
[in] LPVOID unnamedParam2,
[in] DWORD unnamedParam3,
[in] DWORD unnamedParam4
);

Parameters
[in] unnamedParam1

Reference to (C++) or address of (C) the globally unique identifier that identifies the
private data to be set.

[in] unnamedParam2

A pointer to a buffer that contains the data to be associated with the surface.

[in] unnamedParam3

The size value of the buffer at lpData, in bytes.

[in] unnamedParam4

A value that can be set to one of the following flags. These flags describe the type of
data being passed or request that the data be invalidated when the surface changes.

(none)
If no flags are specified, DirectDraw allocates memory to hold the data within the buffer
and copies the data into the new buffer. The buffer allocated by DirectDraw is
automatically freed, as appropriate.

DDSPD_IUNKNOWNPOINTER
The data at lpData is a pointer to an IUnknown interface. DirectDraw automatically calls
the IUnknown::AddRef method of this interface. When this data is no longer needed,
DirectDraw automatically calls the IUnknown::Release method of this interface.

DDSPD_VOLATILE
The buffer at lpData is only valid while the surface remains unchanged. If the surface's
contents change, subsequent calls to the IDirectDrawSurface7::GetPrivateData method
return DDERR_EXPIRED.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

Remarks
DirectDraw does not manage the memory at lpData. If this buffer was dynamically
allocated, the caller must free the memory.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll
See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::SetSurfaceDesc
method (ddraw.h)
Article11/01/2022

Sets the characteristics of an existing surface.

Syntax
C++

HRESULT SetSurfaceDesc(
[in] LPDDSURFACEDESC2 unnamedParam1,
[in] DWORD unnamedParam2
);

Parameters
[in] unnamedParam1

A pointer to a DDSURFACEDESC2 structure that contains the new surface characteristics.

[in] unnamedParam2

Currently not used and must be set to 0.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDPARAMS
DDERR_INVALIDOBJECT
DDERR_SURFACELOST
DDERR_SURFACEBUSY
DDERR_INVALIDSURFACETYPE
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDCAPS
DDERR_UNSUPPORTED
DDERR_GENERIC
Remarks
Currently, you can use SetSurfaceDesc only to set the surface data and pixel format that
is used by an explicit system-memory surface. This is useful because it allows a surface
to use data from a previously allocated buffer without copying. The new surface
memory is allocated by the client application, and therefore the client application must
also deallocate it.

The DirectDrawSurface object does not deallocate surface memory that it did not
allocate. Therefore, when the surface memory is no longer needed, you must deallocate
it. However, when you call SetSurfaceDesc, DirectDraw frees the original surface
memory that it implicitly allocated when it created the surface.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::Unlock method
(ddraw.h)
Article11/01/2022

Notifies DirectDraw that the direct surface manipulations are complete.

Syntax
C++

HRESULT Unlock(
[in] LPRECT unnamedParam1
);

Parameters
[in] unnamedParam1

A pointer to a RECT structure that was used to lock the surface in the corresponding call
to the IDirectDrawSurface7::Lock method. This parameter can be NULL only if the entire
surface was locked by passing NULL in the lpDestRect parameter of the corresponding
call to the IDirectDrawSurface7::Lock method.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOTLOCKED
DDERR_SURFACELOST

Remarks
Because you can call IDirectDrawSurface7::Lock multiple times for the same surface with
different destination rectangles, the pointer in lpRect links the calls to the
IDirectDrawSurface7::Lock and IDirectDrawSurface7::Unlock methods.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::UpdateOverlay
method (ddraw.h)
Article11/01/2022

Repositions or modifies the visual attributes of an overlay surface. These surfaces must
have the DDSCAPS_OVERLAY flag set.

Syntax
C++

HRESULT UpdateOverlay(
[in] LPRECT unnamedParam1,
[in] LPDIRECTDRAWSURFACE7 unnamedParam2,
[in] LPRECT unnamedParam3,
[in] DWORD unnamedParam4,
[in] LPDDOVERLAYFX unnamedParam5
);

Parameters
[in] unnamedParam1

A pointer to a RECT structure that defines the x, y, width, and height of the region on
the source surface being used as the overlay. This parameter can be NULL to hide an
overlay or to indicate that the entire overlay surface is to be used and that the overlay
surface conforms to any boundary and size-alignment restrictions imposed by the
device driver.

[in] unnamedParam2

A pointer to the IDirectDrawSurface7 interface for the DirectDrawSurface object that is

being overlaid.

[in] unnamedParam3

A pointer to a RECT structure that defines the width, x, and height, y, of the region on
the destination surface that the overlay should be moved to. This parameter can be
NULL to hide the overlay.

[in] unnamedParam4
A combination of the following flags that determine the overlay update:

DDOVER_ADDDIRTYRECT
Adds a dirty rectangle to an emulated overlay surface.

DDOVER_ALPHADEST
Obsolete.

DDOVER_ALPHADESTCONSTOVERRIDE
Uses the dwAlphaDestConst member of the DDOVERLAYFX structure as the destination
alpha channel for this overlay.

DDOVER_ALPHADESTNEG

Indicates that the destination surface becomes more transparent as the alpha value
increases (0 is opaque).

DDOVER_ALPHADESTSURFACEOVERRIDE
Uses the lpDDSAlphaDest member of the DDOVERLAYFX structure as the alpha channel
destination for this overlay.

DDOVER_ALPHAEDGEBLEND
Uses the dwAlphaEdgeBlend member of the DDOVERLAYFX structure as the alpha
channel for the edges of the image that border the color key colors.

DDOVER_ALPHASRC

Uses either the alpha information in pixel format or the alpha channel surface attached
to the source surface as the source alpha channel for this overlay.

DDOVER_ALPHASRCCONSTOVERRIDE
Uses the dwAlphaSrcConst member of the DDOVERLAYFX structure as the source alpha
channel for this overlay.
DDOVER_ALPHASRCNEG
Indicates that the source surface becomes more transparent as the alpha value increases
(0 is opaque).

DDOVER_ALPHASRCSURFACEOVERRIDE
Uses the lpDDSAlphaSrc member of the DDOVERLAYFX structure as the alpha channel
source for this overlay.

DDOVER_ARGBSCALEFACTORS

New for DirectX 7.0. Indicates that the DDOVERLAYFX structure contains valid ARGB
scaling factors.

DDOVER_AUTOFLIP
Automatically flips to the next surface in the flipping chain each time that a video port
VSYNC occurs.

DDOVER_BOB
Displays each field of the interlaced video stream individually without causing any
artifacts to display.

DDOVER_BOBHARDWARE

Bob operations are performed by using hardware, rather than by using software or
being emulated. This flag must be used with the DDOVER_BOB flag.

DDOVER_DDFX
Uses the overlay FX flags in the lpDDOverlayFx parameter to define special overlay
effects.

DDOVER_DEGRADEARGBSCALING

New for DirectX 7.0. ARGB scaling factors can be degraded to fit driver capabilities.

DDOVER_HIDE
Turns off this overlay.

DDOVER_INTERLEAVED
The surface memory is composed of interleaved fields.

DDOVER_KEYDEST
Uses the color key associated with the destination surface.

DDOVER_KEYDESTOVERRIDE
Uses the dckDestColorkey member of the DDOVERLAYFX structure as the color key for
the destination surface.

DDOVER_KEYSRC

Uses the color key associated with the source surface.

DDOVER_KEYSRCOVERRIDE

Uses the dckSrcColorkey member of the DDOVERLAYFX structure as the color key for
the source surface.

DDOVER_OVERRIDEBOBWEAVE
Bob and weave decisions should not be overridden by other interfaces.

DDOVER_REFRESHALL

Redraws the entire surface on an emulated overlayed surface.

DDOVER_REFRESHDIRTYRECTS

Redraws all dirty rectangles on an emulated overlayed surface.

DDOVER_SHOW

Turns on this overlay.

[in] unnamedParam5

A pointer to the DDOVERLAYFX structure that describes the effects to be used. Can be
NULL if the DDOVER_DDFX flag is not specified.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error 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

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7
Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::UpdateOverlayDis
play method (ddraw.h)
Article11/01/2022

The IDirectDrawSurface7::UpdateOverlayDisplay method is not currently implemented.

Syntax
C++

HRESULT UpdateOverlayDisplay(
[in] DWORD unnamedParam1
);

Parameters
[in] unnamedParam1

The method is not currently implemented.

Return value
The method is not currently implemented.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7
Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

IDirectDrawSurface7::UpdateOverlayZOr
der method (ddraw.h)
Article11/01/2022

Sets the z-order of an overlay.

Syntax
C++

HRESULT UpdateOverlayZOrder(
[in] DWORD unnamedParam1,
[in] LPDIRECTDRAWSURFACE7 unnamedParam2
);

Parameters
[in] unnamedParam1

One of the following flags that determines the z-order of the overlay:

DDOVERZ_INSERTINBACKOF
Inserts this overlay in the overlay chain behind the reference overlay.

DDOVERZ_INSERTINFRONTOF
Inserts this overlay in the overlay chain in front of the reference overlay.

DDOVERZ_MOVEBACKWARD
Moves this overlay one position backward in the overlay chain.

DDOVERZ_MOVEFORWARD
Moves this overlay one position forward in the overlay chain.

DDOVERZ_SENDTOBACK
Moves this overlay to the back of the overlay chain.

DDOVERZ_SENDTOFRONT
Moves this overlay to the front of the overlay chain.

[in] unnamedParam2

A pointer to the IDirectDrawSurface7 interface for the DirectDraw surface to be used as

a relative position in the overlay chain. This parameter is needed only for the
DDOVERZ_INSERTINBACKOF and DDOVERZ_INSERTINFRONTOF flags.

Return value
If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTAOVERLAYSURFACE

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

See also
IDirectDrawSurface7

Feedback
Was this page helpful? ﾂ Yes ﾄ No
Get help at Microsoft Q&A
DirectDraw Functions
Article • 08/23/2019

This section contains information about the following DirectDraw global functions:

DirectDrawCreate
DirectDrawCreateClipper
DirectDrawCreateEx
DirectDrawEnumerate
DirectDrawEnumerateEx

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDrawCreate function (ddraw.h)
Article10/13/2021

Creates an instance of a DirectDraw object. A DirectDraw object that is created by using

this function does not support the complete set of Direct3D interfaces in DirectX 7.0. To
create a DirectDraw object that is capable of exposing all of the features of Direct3D in
DirectX 7.0, use the DirectDrawCreateEx function.

Syntax
C++

HRESULT DirectDrawCreate(
[in] GUID *lpGUID,
[out] LPDIRECTDRAW *lplpDD,
[in] IUnknown *pUnkOuter
);

Parameters
[in] lpGUID

A pointer to the globally unique identifier (GUID) that represents the driver to be
created. This can be NULL to indicate the active display driver, or you can pass one of
the following flags to restrict the active display driver's behavior for debugging
purposes:

DDCREATE_EMULATIONONLY
The DirectDraw object uses emulation for all features; it does not take advantage of any
hardware-supported features.

DDCREATE_HARDWAREONLY
The DirectDraw object never emulates features not supported by the hardware.
Attempts to call methods that require unsupported features fail, returning
DDERR_UNSUPPORTED.

[out] lplpDD
A pointer to a variable to be set to a valid IDirectDraw interface pointer if the call
succeeds.

[in] pUnkOuter

Allows for future compatibility with COM aggregation features. Presently, however, this
function returns an error if this parameter is anything but NULL.

Return value
If the function succeeds, the return value is DD_OK.

If it fails, the function can return one of the following error values:

DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_OUTOFMEMORY

Remarks
This function attempts to initialize a DirectDraw object, and then sets a pointer to the
object if the call succeeds.

On computers with multiple monitors, if you specify NULL for lpGUID, the DirectDraw
object runs in emulation mode when the normal cooperative level is set. To make use of
hardware acceleration on these computers, specify the device's GUID.

You must use LoadLibrary to explicitly link to Ddraw.dll and then use GetProcAddress to
access the DirectDrawCreate function.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib
 DLL Ddraw.dll

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDrawCreateClipper function
(ddraw.h)
Article10/13/2021

Creates an instance of a DirectDrawClipper object that is not associated with a

DirectDraw object.

Syntax
C++

HRESULT DirectDrawCreateClipper(
[in] DWORD dwFlags,
[out] LPDIRECTDRAWCLIPPER *lplpDDClipper,
[in] IUnknown *pUnkOuter
);

Parameters
[in] dwFlags

Currently not used and must be set to 0.

[out] lplpDDClipper

Address of a pointer to be filled with the address of the new DirectDrawClipper object.

[in] pUnkOuter

Allows for future compatibility with COM aggregation features. Currently, this function
returns an error if this parameter is not NULL.

Return value
If the function succeeds, the return value is DD_OK.

If it fails, the function can return one of the following error values:

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
Remarks
You can call DirectDrawCreateClipper before any DirectDraw objects are created.
Because these DirectDrawClipper objects are not owned by any DirectDraw object, they
are not automatically released when an application's objects are released. If the
application does not explicitly release the DirectDrawClipper objects, DirectDraw
releases them when the application terminates.

To create a DirectDrawClipper object that is owned by a specific DirectDraw object, use

the IDirectDraw7::CreateClipper method.

You must use LoadLibrary to explicitly link to Ddraw.dll and then use GetProcAddress to
access the DirectDrawCreateClipper function.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDrawCreateEx function (ddraw.h)
Article10/13/2021

Creates an instance of a DirectDraw object that supports the set of Direct3D interfaces
in DirectX 7.0. To use the features of Direct3D in DirectX 7.0, create a DirectDraw object
with this function.

Syntax
C++

HRESULT DirectDrawCreateEx(
[in] GUID *lpGuid,
[out] LPVOID *lplpDD,
[in] REFIID iid,
[in] IUnknown *pUnkOuter
);

Parameters
[in] lpGuid

A pointer to the globally unique identifier (GUID) that represents the driver to be
created. This can be NULL to indicate the active display driver, or you can pass one of
the following flags to restrict the active display driver's behavior for debugging
purposes:

DDCREATE_EMULATIONONLY

The DirectDraw object uses emulation for all features; it does not take advantage of any
hardware-supported features.

DDCREATE_HARDWAREONLY
The DirectDraw object never emulates features not supported by the hardware.
Attempts to call methods that require unsupported features fail, returning
DDERR_UNSUPPORTED.

[out] lplpDD
A pointer to a variable to be set to a valid IDirectDraw7 interface pointer if the call
succeeds.

[in] iid

This parameter must be set to IID_IDirectDraw7. This function fails and returns
DDERR_INVALIDPARAMS if any other interface is specified.

[in] pUnkOuter

Allows for future compatibility with COM aggregation features. Currently, this function
returns an error if this parameter is not NULL.

Return value
If the function succeeds, the return value is DD_OK.

If it fails, the function can return one of the following error values:

DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_OUTOFMEMORY

Remarks
This function attempts to initialize a DirectDraw object, and then sets a pointer to the
object if the call succeeds.

On computers with multiple monitors, if you specify NULL for lpGUID, the DirectDraw
object runs in emulation mode when the normal cooperative level is set. To make use of
hardware acceleration on these computers, specify the device's GUID.

You must use LoadLibrary to explicitly link to Ddraw.dll and then use GetProcAddress to
access the DirectDrawCreateEx function.

Requirements
 Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDrawEnumerateW function
(ddraw.h)
Article02/09/2023

This function is superseded by the DirectDrawEnumerateEx function.

The DirectDrawEnumerate function enumerates the primary DirectDraw display device

and a nondisplay device (such as a 3-D accelerator that has no 2-D capabilities), if one is
installed. The NULL entry always identifies the primary display device shared with the
GDI.

Syntax
C++

HRESULT DirectDrawEnumerateW(
[in] LPDDENUMCALLBACKW lpCallback,
[in] LPVOID lpContext
);

Parameters
[in] lpCallback

Address of a DDEnumCallback function to be called with a description of each

enumerated DirectDraw-enabled hardware abstraction layer (HAL).

[in] lpContext

Address of an application-defined context to be passed to the enumeration callback

function each time that it is called.

Return value
If the function succeeds, the return value is DD_OK.

If it fails, the function returns DDERR_INVALIDPARAMS.

Remarks
You must use LoadLibrary to explicitly link to Ddraw.dll and then use GetProcAddress to
access the DirectDrawEnumerate function.

Requirements

Target Platform Windows

Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDrawEnumerateExA function
(ddraw.h)
Article02/09/2023

Enumerates all DirectDraw devices that are installed on the computer. The NULL entry
always identifies the primary display device that is shared with GDI.

Syntax
C++

HRESULT DirectDrawEnumerateExA(
[in] LPDDENUMCALLBACKEXA lpCallback,
[in] LPVOID lpContext,
[in] DWORD dwFlags
);

Parameters
[in] lpCallback

Address of a DDEnumCallbackEx function to be called with a description of each

enumerated DirectDraw-enabled hardware abstraction layer (HAL).

[in] lpContext

Address of an application-defined value to be passed to the enumeration callback

function each time that it is called.

[in] dwFlags

Flags that specify the enumeration scope. This parameter can be 0 or a combination of
the following flags. If the value is 0, the function enumerates only the primary display
device.

DDENUM_ATTACHEDSECONDARYDEVICES
The function enumerates the primary device and any display devices that are attached
to the desktop.
DDENUM_DETACHEDSECONDARYDEVICES
The function enumerates the primary device and any display devices that are not
attached to the desktop.

DDENUM_NONDISPLAYDEVICES
The function enumerates the primary device and any nondisplay devices, such as 3-D
accelerators that have no 2-D capabilities.

Return value
If the function succeeds, the return value is DD_OK.

If it fails, the function returns DDERR_INVALIDPARAMS.

Remarks
On computers with multiple monitors, DirectDrawEnumerateEx enumerates multiple
display devices.

You must use LoadLibrary to explicitly link to Ddraw.dll. To retrieve the address of the
DirectDrawEnumerateEx function, call the GetProcAddress Win32 function with the
"DirectDrawEnumerateExA" (ANSI) or "DirectDrawEnumerateExW" (Unicode) process
name strings.

７ Note

The ddraw.h header defines DirectDrawEnumerateEx as an alias which automatically

selects the ANSI or Unicode version of this function based on the definition of the
UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Target Platform Windows

 Header ddraw.h

Library Ddraw.lib

DLL Ddraw.dll

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDraw Callback Functions
Article • 08/23/2019

This section contains information about the following callback functions used with
DirectDraw:

DDEnumCallback
DDEnumCallbackEx
EnumModesCallback
EnumModesCallback2
EnumSurfacesCallback
EnumSurfacesCallback2
EnumSurfacesCallback7

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

LPDDENUMCALLBACKA callback
function (ddraw.h)
Article07/27/2022

The DDEnumCallback function is an application-defined callback function for the

DirectDrawEnumerate function.

Syntax
C++

LPDDENUMCALLBACKA Lpddenumcallbacka;

BOOL Lpddenumcallbacka(
GUID *unnamedParam1,
LPSTR unnamedParam2,
LPSTR unnamedParam3,
LPVOID unnamedParam4
)
{...}

Parameters
unnamedParam1

A pointer to the unique identifier of the DirectDraw object.

unnamedParam2

Address of a string that contains the driver name.

unnamedParam3

Address of a string that contains the driver description.

unnamedParam4

A pointer to an application-defined structure to be passed to the callback function each

time the function is called.

Return value
The callback function returns nonzero to continue the enumeration.

It returns zero to stop the enumeration.

Remarks
You can use the LPDDENUMCALLBACK data type to declare a variable that can contain a
pointer to this callback function.

If UNICODE is defined, the string values are returned as type LPWSTR, rather than LPSTR.

７ Note

The ddraw.h header defines LPDDENUMCALLBACK as an alias which automatically

selects the ANSI or Unicode version of this function based on the definition of the
UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

LPDDENUMCALLBACKEXA callback
function (ddraw.h)
Article07/27/2022

The DDEnumCallbackEx function is an application-defined callback function for the

DirectDrawEnumerateEx function.

Syntax
C++

LPDDENUMCALLBACKEXA Lpddenumcallbackexa;

BOOL Lpddenumcallbackexa(
GUID *unnamedParam1,
LPSTR unnamedParam2,
LPSTR unnamedParam3,
LPVOID unnamedParam4,
HMONITOR unnamedParam5
)
{...}

Parameters
unnamedParam1

A pointer to the unique identifier of the DirectDraw object.

unnamedParam2

Address of a string that contains the driver name.

unnamedParam3

Address of a string that contains the driver description.

unnamedParam4

A pointer to an application-defined structure to be passed to the callback function each

time that the function is called.

unnamedParam5
Handle of the monitor that is associated with the enumerated DirectDraw object. This
parameter is NULL when the enumerated DirectDraw object is for the primary device, a
nondisplay device (such as a 3-D accelerator with no 2-D capabilities), or devices not
attached to the desktop.

Return value
The callback function returns nonzero to continue the enumeration.

It returns zero to stop the enumeration.

Remarks
After the DirectDrawEnumerateEx function completes, the pointer to the GUID at lpGUID
is no longer valid. You must save a copy of the GUID structure itself, not the pointer, or
the DirectDrawCreateEx function fails.

You can use the LPDDENUMCALLBACKEX data type to declare a variable that can
contain a pointer to this callback function.

If UNICODE is defined, the string values are returned as type LPWSTR, rather than LPSTR.

７ Note

The ddraw.h header defines LPDDENUMCALLBACKEX as an alias which

automatically selects the ANSI or Unicode version of this function based on the
definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

Requirements

Target Platform Windows

Header ddraw.h
Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

LPDDENUMMODESCALLBACK callback
function (ddraw.h)
Article02/16/2023

Do not use. This callback function is superseded by the EnumModesCallback2 function

that is used with the IDirectDraw7::EnumDisplayModes method.

Syntax
C++

LPDDENUMMODESCALLBACK Lpddenummodescallback;

HRESULT Lpddenummodescallback(
[in] LPDDSURFACEDESC unnamedParam1,
[in] LPVOID unnamedParam2
)
{...}

Parameters
[in] unnamedParam1

A pointer to a read-only DDSURFACEDESC structure that provides the monitor

frequency and the mode that can be created.

[in] unnamedParam2

A pointer to an application-defined structure to be passed to the callback function each

time that the function is called.

Return value
The callback function returns DDENUMRET_OK to continue the enumeration.

It returns DDENUMRET_CANCEL to stop the enumeration.

Remarks
You can use the LPDDENUMMODESCALLBACK data type to declare a variable that can
contain a pointer to this callback function.

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

LPDDENUMMODESCALLBACK2 callback
function (ddraw.h)
Article10/13/2021

The EnumModesCallback2 function is an application-defined callback function for the

IDirectDraw7::EnumDisplayModes method.

Syntax
C++

LPDDENUMMODESCALLBACK2 Lpddenummodescallback2;

HRESULT Lpddenummodescallback2(
[in] LPDDSURFACEDESC2 unnamedParam1,
[in] LPVOID unnamedParam2
)
{...}

Parameters
[in] unnamedParam1

A pointer to a read-only DDSURFACEDESC2 structure that provides the monitor

frequency and the mode that can be created.

[in] unnamedParam2

A pointer to an application-defined structure to be passed to the callback function each

time that the function is called.

Return value
The callback function returns DDENUMRET_OK to continue the enumeration.

It returns DDENUMRET_CANCEL to stop the enumeration.

Remarks
You can use the LPDDENUMMODESCALLBACK2 data type to declare a variable that can
contain a pointer to this callback function.

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

LPDDENUMSURFACESCALLBACK
callback function (ddraw.h)
Article02/16/2023

Do not use. This callback function is superseded by the EnumSurfacesCallback7 function

that is used with the IDirectDraw7::EnumSurfaces,
IDirectDrawSurface7::EnumAttachedSurfaces, and
IDirectDrawSurface7::EnumOverlayZOrders methods.

Syntax
C++

LPDDENUMSURFACESCALLBACK Lpddenumsurfacescallback;

HRESULT Lpddenumsurfacescallback(
[in] LPDIRECTDRAWSURFACE unnamedParam1,
[in] LPDDSURFACEDESC unnamedParam2,
[in] LPVOID unnamedParam3
)
{...}

Parameters
[in] unnamedParam1

A pointer to the IDirectDrawSurface interface for the attached surface.

[in] unnamedParam2

A pointer to a DDSURFACEDESC structure that describes the attached surface.

[in] unnamedParam3

A pointer to an application-defined structure to be passed to the callback function each

time that the function is called.

Return value
The callback function returns DDENUMRET_OK to continue the enumeration.
It returns DDENUMRET_CANCEL to stop the enumeration.

Remarks
You can use the LPDDENUMSURFACESCALLBACK data type to declare a variable that
can contain a pointer to this callback function.

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

LPDDENUMSURFACESCALLBACK2
callback function (ddraw.h)
Article08/19/2022

Do not use. This callback function is superseded by the EnumSurfacesCallback7 function

that is used with the IDirectDraw7::EnumSurfaces,
IDirectDrawSurface7::EnumAttachedSurfaces, and
IDirectDrawSurface7::EnumOverlayZOrders methods.

Syntax
C++

LPDDENUMSURFACESCALLBACK2 Lpddenumsurfacescallback2;

HRESULT Lpddenumsurfacescallback2(
[in] LPDIRECTDRAWSURFACE4 unnamedParam1,
[in] LPDDSURFACEDESC2 unnamedParam2,
[in] LPVOID unnamedParam3
)
{...}

Parameters
[in] unnamedParam1

A pointer to the IDirectDrawSurface4 interface of the attached surface.

[in] unnamedParam2

A pointer to a DDSURFACEDESC2 structure that describes the attached surface.

[in] unnamedParam3

A pointer to an application-defined structure to be passed to the callback function each

time that the function is called.

Return value
The callback function returns DDENUMRET_OK to continue the enumeration.
It returns DDENUMRET_CANCEL to stop the enumeration.

Remarks
You can use the LPDDENUMSURFACESCALLBACK2 data type to declare a variable that
can contain a pointer to this callback function.

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

LPDDENUMSURFACESCALLBACK7
callback function (ddraw.h)
Article10/13/2021

The EnumSurfacesCallback7 function is an application-defined callback function for the

IDirectDrawSurface7::EnumAttachedSurfaces and
IDirectDrawSurface7::EnumOverlayZOrders methods.

Syntax
C++

LPDDENUMSURFACESCALLBACK7 Lpddenumsurfacescallback7;

HRESULT Lpddenumsurfacescallback7(
[in] LPDIRECTDRAWSURFACE7 unnamedParam1,
[in] LPDDSURFACEDESC2 unnamedParam2,
[in] LPVOID unnamedParam3
)
{...}

Parameters
[in] unnamedParam1

A pointer to the IDirectDrawSurface7 interface of the attached surface.

[in] unnamedParam2

A pointer to a DDSURFACEDESC2 structure that describes the attached surface.

[in] unnamedParam3

A pointer to an application-defined structure to be passed to the callback function each

time that the function is called.

Return value
The callback function returns DDENUMRET_OK to continue the enumeration.

It returns DDENUMRET_CANCEL to stop the enumeration.

Remarks
You can use the LPDDENUMSURFACESCALLBACK7 data type to declare a variable that
can contain a pointer to this callback function.

Requirements

Target Platform Windows

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDraw structures
Article • 07/12/2022

This section contains information about the following structures used with DirectDraw:

DDBLTBATCH
DDBLTFX
DDCAPS
DDCOLORCONTROL
DDCOLORKEY
DDDEVICEIDENTIFIER2
DDGAMMARAMP
DDOVERLAYFX
DDPIXELFORMAT
DDSCAPS
DDSCAPS2
DDSURFACEDESC
DDSURFACEDESC2

７ Note

You should initialize the memory for each DirectX structure to 0 before you use the
structure. In addition, for all structures that contain a dwSize member, you should
set the member to the size of the structure, in bytes, before you use the structure.
The following example performs those tasks on an object of type DDCAPS_DX3:

DDCAPS_DX3 ddcaps; // You can't use this yet.

ZeroMemory(&ddcaps, sizeof(DDCAPS_DX3));
ddcaps.dwSize = sizeof(DDCAPS_DX3);

// Now you can use the structure.

...

Feedback
Was this page helpful? ﾂ Yes ﾄ No
Get help at Microsoft Q&A
DDBLTBATCH structure (ddraw.h)
Article04/02/2021

The DDBLTBATCH structure passes bit block transfer (bitblt) operations to the
IDirectDrawSurface7::BltBatch method.

Syntax
C++

typedef struct _DDBLTBATCH {

LPRECT lprDest;
LPDIRECTDRAWSURFACE lpDDSSrc;
LPRECT lprSrc;
DWORD dwFlags;
LPDDBLTFX lpDDBltFx;
} DDBLTBATCH;

Members
lprDest

Address of a RECT structure that defines the destination for the bitblt.

lpDDSSrc

Address of a DirectDrawSurface object to be the source of the bitblt.

lprSrc

Address of a RECT structure that defines the source rectangle of the bitblt.

dwFlags

Optional control flags. The following values are defined:

DDBLT_ALPHADEST
Uses either the alpha information in pixel format or the alpha channel surface attached
to the destination surface as the alpha channel for this bitblt.

DDBLT_ALPHADESTCONSTOVERRIDE
Uses the dwAlphaDestConst member of the DDBLTFX structure as the alpha channel for
the destination surface for this bitblt.

DDBLT_ALPHADESTNEG

The destination surface becomes more transparent as the alpha value increases (0 is
opaque).

DDBLT_ALPHADESTSURFACEOVERRIDE
Uses the lpDDSAlphaDest member of the DDBLTFX structure as the alpha channel for
the destination surface for this bitblt.

DDBLT_ALPHAEDGEBLEND

Uses the dwAlphaEdgeBlend member of the DDBLTFX structure as the alpha channel for
the edges of the image that border the color key colors.

DDBLT_ALPHASRC

Uses either the alpha information in pixel format or the alpha channel surface attached
to the source surface as the alpha channel for this bitblt.

DDBLT_ALPHASRCCONSTOVERRIDE
Uses the dwAlphaSrcConst member of the DDBLTFX structure as the source alpha
channel for this bitblt.

DDBLT_ALPHASRCNEG

The source surface becomes more transparent as the alpha value increases (0 is
opaque).

DDBLT_ALPHASRCSURFACEOVERRIDE
Uses the lpDDSAlphaSrc member of the DDBLTFX structure as the alpha channel source
for this bitblt.

DDBLT_ASYNC
Performs this bitblt asynchronously through the first in, first out (FIFO) hardware in the
order received. If no room is available in the FIFO hardware, the call fails.

DDBLT_COLORFILL

Uses the dwFillColor member of the DDBLTFX structure as the RGB color that fills the
destination rectangle on the destination surface.

DDBLT_DDFX
Uses the dwDDFX member of the DDBLTFX structure to specify the effects to use for this
bitblt.

DDBLT_DDROPS

Uses the dwDDROP member of the DDBLTFX structure to specify the raster operations
(ROPS) that are not part of the Win32 API.

DDBLT_KEYDEST

Uses the color key that is associated with the destination surface.

DDBLT_KEYDESTOVERRIDE

Uses the ddckDestColorkey member of the DDBLTFX structure as the color key for the
destination surface.

DDBLT_KEYSRC
Uses the color key that is associated with the source surface.

DDBLT_KEYSRCOVERRIDE
Uses the ddckSrcColorkey member of the DDBLTFX structure as the color key for the
source surface.

DDBLT_ROP

Uses the dwROP member of the DDBLTFX structure for the ROP for this bitblt. These
ROPs are the same as those defined in the Win32 API.
DDBLT_ROTATIONANGLE
Uses the dwRotationAngle member of the DDBLTFX structure as the rotation angle
(specified in 1/100s of a degree) for the surface.

DDBLT_ZBUFFER
Performs a z-buffered bitblt, using the z-buffers that are attached to the source and
destination surfaces and the dwZBufferOpCode member of the DDBLTFX structure as
the z-buffer opcode.

DDBLT_ZBUFFERDESTCONSTOVERRIDE
Performs a z-buffered bitblt, using the dwZDestConst and dwZBufferOpCode members
of the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the
destination.

DDBLT_ZBUFFERDESTOVERRIDE

Performs a z-buffered bitblt, using the lpDDSZBufferDest and dwZBufferOpCode

members of the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for
the destination.

DDBLT_ZBUFFERSRCCONSTOVERRIDE

Performs a z-buffered bitblt, using the dwZSrcConst and dwZBufferOpCode members

of the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the
source.

DDBLT_ZBUFFERSRCOVERRIDE
Performs a z-buffered bitblt, using the lpDDSZBufferSrc and dwZBufferOpCode
members of the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for
the source.

lpDDBltFx

Address of a DDBLTFX structure that specifies additional bitblt effects.

Requirements
 Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDBLTFX structure (ddraw.h)
Article11/23/2021

The DDBLTFX structure passes raster operations (ROPs), effects, and override
information to the IDirectDrawSurface7::Blt method. This structure is also part of the
DDBLTBATCH structure that is used with the IDirectDrawSurface7::BltBatch method.

Syntax
C++

typedef struct _DDBLTFX {

DWORD dwSize;
DWORD dwDDFX;
DWORD dwROP;
DWORD dwDDROP;
DWORD dwRotationAngle;
DWORD dwZBufferOpCode;
DWORD dwZBufferLow;
DWORD dwZBufferHigh;
DWORD dwZBufferBaseDest;
DWORD dwZDestConstBitDepth;
#if ...
union {
DWORD dwZDestConst;
LPDIRECTDRAWSURFACE lpDDSZBufferDest;
} DUMMYUNIONNAMEN;
DWORD dwZSrcConstBitDepth;
#elif
union {
DWORD dwZSrcConst;
LPDIRECTDRAWSURFACE lpDDSZBufferSrc;
} DUMMYUNIONNAMEN;
DWORD dwAlphaEdgeBlendBitDepth;
DWORD dwAlphaEdgeBlend;
DWORD dwReserved;
DWORD dwAlphaDestConstBitDepth;
#elif
union {
DWORD dwAlphaDestConst;
LPDIRECTDRAWSURFACE lpDDSAlphaDest;
} DUMMYUNIONNAMEN;
DWORD dwAlphaSrcConstBitDepth;
#elif
union {
DWORD dwAlphaSrcConst;
LPDIRECTDRAWSURFACE lpDDSAlphaSrc;
} DUMMYUNIONNAMEN;
#else
 union {
DWORD dwFillColor;
DWORD dwFillDepth;
DWORD dwFillPixel;
LPDIRECTDRAWSURFACE lpDDSPattern;
} DUMMYUNIONNAMEN;
#endif
DDCOLORKEY ddckDestColorkey;
DDCOLORKEY ddckSrcColorkey;
} DDBLTFX;

Members
dwSize

Size of the structure, in bytes. This member must be initialized before the structure is
used.

dwDDFX

Type of FX operations. The following types are defined.

DDBLTFX_ARITHSTRETCHY

Uses arithmetic stretching along the y-axis for this bit block transfer (bitblt).

DDBLTFX_MIRRORLEFTRIGHT

Turns the surface on its y-axis. This bitblt mirrors the surface from left to right.

DDBLTFX_MIRRORUPDOWN

Turns the surface on its x-axis. This bitblt mirrors the surface from top to bottom.

DDBLTFX_NOTEARING

Schedules this bitblt to avoid tearing.

DDBLTFX_ROTATE180

Rotates the surface 180 degrees clockwise during this bitblt.

DDBLTFX_ROTATE270
Rotates the surface 270 degrees clockwise during this bitblt.

DDBLTFX_ROTATE90

Rotates the surface 90 degrees clockwise during this bitblt.

DDBLTFX_ZBUFFERBASEDEST

Adds the dwZBufferBaseDest member to each of the source z-values before comparing
them with the destination z-values during this z-bitblt.

DDBLTFX_ZBUFFERRANGE
Uses the dwZBufferLow and dwZBufferHigh members as range values to specify limits
to the bits copied from a source surface during this z-bitblt.

dwROP

Win32 raster operations. You can retrieve a list of supported raster operations by calling
the IDirectDraw7::GetCaps method.

dwDDROP

DirectDraw raster operations.

dwRotationAngle

Rotation angle for the bitblt.

dwZBufferOpCode

Z-buffer compares.

dwZBufferLow

Low limit of a z-buffer.

dwZBufferHigh

High limit of a z-buffer.

dwZBufferBaseDest
Destination base value of a z-buffer.

dwZDestConstBitDepth

Bit depth of the destination z-constant.

DUMMYUNIONNAMEN

DUMMYUNIONNAMEN.dwZDestConst

DUMMYUNIONNAMEN.lpDDSZBufferDest

dwZSrcConstBitDepth

Bit depth of the source z-constant.

DUMMYUNIONNAMEN.dwZSrcConst

DUMMYUNIONNAMEN.lpDDSZBufferSrc

dwAlphaEdgeBlendBitDepth

Bit depth of the constant for an alpha edge blend.

dwAlphaEdgeBlend

Alpha constant used for edge blending.

dwReserved

Reserved

dwAlphaDestConstBitDepth

Bit depth of the destination alpha constant.

DUMMYUNIONNAMEN.dwAlphaDestConst

DUMMYUNIONNAMEN.lpDDSAlphaDest

dwAlphaSrcConstBitDepth

Bit depth of the source alpha constant.

DUMMYUNIONNAMEN.dwAlphaSrcConst

DUMMYUNIONNAMEN.lpDDSAlphaSrc
DUMMYUNIONNAMEN.dwFillColor

DUMMYUNIONNAMEN.dwFillDepth

DUMMYUNIONNAMEN.dwFillPixel

DUMMYUNIONNAMEN.lpDDSPattern

ddckDestColorkey

Destination color key override.

ddckSrcColorkey

Source color key override.

Remarks
The unions in this structure have been updated to work with compilers that do not
support nameless unions. If your compiler does not support nameless unions, define the
NONAMELESSUNION token before including the Ddraw.h header file.

Requirements

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDCAPS_DX3 structure (ddraw.h)
Article09/01/2022

The DDCAPS structure represents the capabilities of the hardware exposed through the
DirectDraw object. This structure contains a DDSCAPS2 structure used in this context to
describe what kinds of DirectDrawSurface objects can be created. It might not be
possible to create all the surfaces described by these capabilities simultaneously. This
structure is used with the IDirectDraw7::GetCaps method.

The Ddraw.h header file contains multiple versions of this structure (for example,
DDCAPS_DX7). For more information about how to determine which version to use, see
Remarks.

Syntax
C++

typedef struct _DDCAPS_DX3 {

DWORD dwSize;
DWORD dwCaps;
DWORD dwCaps2;
DWORD dwCKeyCaps;
DWORD dwFXCaps;
DWORD dwFXAlphaCaps;
DWORD dwPalCaps;
DWORD dwSVCaps;
DWORD dwAlphaBltConstBitDepths;
DWORD dwAlphaBltPixelBitDepths;
DWORD dwAlphaBltSurfaceBitDepths;
DWORD dwAlphaOverlayConstBitDepths;
DWORD dwAlphaOverlayPixelBitDepths;
DWORD dwAlphaOverlaySurfaceBitDepths;
DWORD dwZBufferBitDepths;
DWORD dwVidMemTotal;
DWORD dwVidMemFree;
DWORD dwMaxVisibleOverlays;
DWORD dwCurrVisibleOverlays;
DWORD dwNumFourCCCodes;
DWORD dwAlignBoundarySrc;
DWORD dwAlignSizeSrc;
DWORD dwAlignBoundaryDest;
DWORD dwAlignSizeDest;
DWORD dwAlignStrideAlign;
DWORD dwRops[DD_ROP_SPACE];
DDSCAPS ddsCaps;
DWORD dwMinOverlayStretch;
DWORD dwMaxOverlayStretch;
DWORD dwMinLiveVideoStretch;
 DWORD dwMaxLiveVideoStretch;
DWORD dwMinHwCodecStretch;
DWORD dwMaxHwCodecStretch;
DWORD dwReserved1;
DWORD dwReserved2;
DWORD dwReserved3;
DWORD dwSVBCaps;
DWORD dwSVBCKeyCaps;
DWORD dwSVBFXCaps;
DWORD dwSVBRops[DD_ROP_SPACE];
DWORD dwVSBCaps;
DWORD dwVSBCKeyCaps;
DWORD dwVSBFXCaps;
DWORD dwVSBRops[DD_ROP_SPACE];
DWORD dwSSBCaps;
DWORD dwSSBCKeyCaps;
DWORD dwSSBFXCaps;
DWORD dwSSBRops[DD_ROP_SPACE];
DWORD dwReserved4;
DWORD dwReserved5;
DWORD dwReserved6;
} DDCAPS_DX3;

Members
dwSize

Size of the structure, in bytes. This member must be initialized before the structure is
used.

dwCaps

This value consists of one or more of the following flags that specify hardware and
driver capabilities.

DDCAPS_3D
The display hardware has 3-D acceleration.

DDCAPS_ALIGNBOUNDARYDEST
DirectDraw supports only those overlay destination rectangles with the x-axis aligned to
the dwAlignBoundaryDest boundaries of the surface.

DDCAPS_ALIGNBOUNDARYSRC
DirectDraw supports only those overlay source rectangles with the x-axis aligned to the
dwAlignBoundarySrc boundaries of the surface.

DDCAPS_ALIGNSIZEDEST

DirectDraw supports only those overlay destination rectangles whose x-axis sizes, in
pixels, are dwAlignSizeDest multiples.

DDCAPS_ALIGNSIZESRC
DirectDraw supports only those overlay source rectangles whose x-axis sizes, in pixels,
are dwAlignSizeSrc multiples.

DDCAPS_ALIGNSTRIDE

DirectDraw creates display memory surfaces that have a stride alignment equal to the
dwAlignStrideAlign value.

DDCAPS_ALPHA

The display hardware supports alpha-only surfaces.

DDCAPS_BANKSWITCHED

The display hardware is bank-switched and is potentially very slow at random access to
display memory.

DDCAPS_BLT
Display hardware is capable of bit block transfer (bitblt) operations.

DDCAPS_BLTCOLORFILL
Display hardware is capable of color filling with a blitter.

DDCAPS_BLTDEPTHFILL
Display hardware is capable of depth filling z-buffers with a blitter.

DDCAPS_BLTFOURCC
Display hardware is capable of color-space conversions during bitblt operations.

DDCAPS_BLTQUEUE
Display hardware is capable of asynchronous bitblt operations.

DDCAPS_BLTSTRETCH
Display hardware is capable of stretching during bitblt operations.

DDCAPS_CANBLTSYSMEM
Display hardware is capable of blitting to or from system memory.

DDCAPS_CANCLIP
Display hardware is capable of clipping with blitting.

DDCAPS_CANCLIPSTRETCHED
Display hardware is capable of clipping while stretch blitting.

DDCAPS_COLORKEY
Supports some form of color key in either overlay or bitblt operations. More specific
color-key capability information can be found in the dwCKeyCaps member.

DDCAPS_COLORKEYHWASSIST

The color key is partially hardware-assisted. This means that other resources (CPU or
video memory) might be used. If this bit is not set, full hardware support is in place.

DDCAPS_GDI

Display hardware is shared with GDI.

DDCAPS_NOHARDWARE

There is no hardware support.

DDCAPS_OVERLAY
Display hardware supports overlays.

DDCAPS_OVERLAYCANTCLIP

Display hardware supports overlays but cannot clip them.

DDCAPS_OVERLAYFOURCC

Overlay hardware is capable of color-space conversions during overlay operations.

DDCAPS_OVERLAYSTRETCH

Overlay hardware is capable of stretching. The dwMinOverlayStretch and

dwMaxOverlayStretch members contain valid data.

DDCAPS_PALETTE
DirectDraw is capable of creating and supporting DirectDrawPalette objects for surfaces
other than the primary surface.

DDCAPS_PALETTEVSYNC

DirectDraw is capable of updating a palette synchronized with the vertical refresh.

DDCAPS_READSCANLINE

Display hardware is capable of returning the current scan line.

DDCAPS_VBI
Display hardware is capable of generating a vertical-blank interrupt.

DDCAPS_ZBLTS
Supports the use of z-buffers with bitblt operations.

DDCAPS_ZOVERLAYS
Supports the use of the IDirectDrawSurface7::UpdateOverlayZOrder method as a z-value
for overlays to control their layering.

dwCaps2

This value consists of one or more of the following flags that specify more hardware and
driver capabilities.

DDCAPS2_AUTOFLIPOVERLAY
The overlay can be automatically flipped to the next surface in the flipping chain each
time that a video port VSYNC occurs, allowing the video port and the overlay to double-
buffer the video without CPU overhead. This option is only valid when the surface is
receiving data from a video port. If the video port data is noninterlaced or
noninterleaved, it flips on every VSYNC. If the data is being interleaved in memory, it
flips on every other VSYNC.

DDCAPS2_CANBOBHARDWARE
The overlay hardware can display each field of an interlaced video stream individually.

DDCAPS2_CANBOBINTERLEAVED
The overlay hardware can display each field of an interlaced video stream individually
while it is interleaved in memory without causing any artifacts that might normally occur
without special hardware support. This option is only valid when the surface is receiving
data from a video port and the video is zoomed at least twice in the vertical direction.

DDCAPS2_CANBOBNONINTERLEAVED
The overlay hardware can display each field of an interlaced video stream individually
while it is not interleaved in memory without causing any artifacts that might normally
occur without special hardware support. This option is only valid when the surface is
receiving data from a video port and the video is zoomed at least twice in the vertical
direction.

DDCAPS2_CANCALIBRATEGAMMA

The system has a calibrator installed that can automatically adjust the gamma ramp so
that the result is identical on all systems that have a calibrator. To invoke the calibrator
when setting new gamma levels, use the DDSGR_CALIBRATE flag when calling the
IDirectDrawGammaControl::SetGammaRamp method. Calibrating gamma ramps incurs
some processing overhead and should not be used frequently.

DDCAPS2_CANDROPZ16BIT

Sixteen-bit RGBZ values can be converted into 16-bit RGB values. (The system does not
support 8-bit conversions.)

DDCAPS2_CANFLIPODDEVEN
The driver is capable of performing odd and even flip operations, as specified by the
DDFLIP_ODD and DDFLIP_EVEN flags that are used with the IDirectDrawSurface7::Flip
method.

DDCAPS2_CANMANAGETEXTURE

The Direct3D texture manager uses this capability to decide whether to put managed
surfaces in nonlocal video memory. If the capability is set, the texture manager puts
managed surfaces in nonlocal video memory. Drivers that cannot texture from local
video memory should not set this capability.

DDCAPS2_CANRENDERWINDOWED
The driver is capable of rendering in windowed mode.

DDCAPS2_CERTIFIED
Display hardware is certified.

DDCAPS2_COLORCONTROLPRIMARY
The primary surface contains color controls (for instance, gamma).

DDCAPS2_COLORCONTROLOVERLAY
The overlay surface contains color controls (such as brightness and sharpness).

DDCAPS2_COPYFOURCC
The driver supports blitting any FOURCC surface to another surface of the same
FOURCC.

DDCAPS2_FLIPINTERVAL

The driver responds to the DDFLIP_INTERVAL* flags. (For more information about these
flags, see IDirectDrawSurface7::Flip).

DDCAPS2_FLIPNOVSYNC
The driver responds to the DDFLIP_NOVSYNC flag (For more information about this flag,
see IDirectDrawSurface7::Flip).

DDCAPS2_NO2DDURING3DSCENE

Two-dimensional operations such as IDirectDrawSurface7::Blt and

IDirectDrawSurface7::Lock cannot be performed on any surfaces that Direct3D is using
between calls to the BeginScene and EndScene methods.

DDCAPS2_NONLOCALVIDMEM
The display driver supports surfaces in nonlocal video memory.

DDCAPS2_NONLOCALVIDMEMCAPS
Bitblt capabilities for nonlocal video-memory surfaces differ from local video-memory
surfaces. If this flag is present, the DDCAPS2_NONLOCALVIDMEM flag is also present.

DDCAPS2_NOPAGELOCKREQUIRED

DMA bitblt operations are supported on system-memory surfaces that are not page-
locked.

DDCAPS2_PRIMARYGAMMA
Supports dynamic gamma ramps for the primary surface.

DDCAPS2_STEREO
New for DirectX 7.0. Turns on the dwSVCaps bit to support stereo mode. The driver can
do stereo in at least one mode other than the current mode. The application can use
IDirectDraw7::GetDisplayMode or IDirectDraw7::EnumDisplayModes to get per-mode
stereo information.

DDCAPS2_TEXMANINNONLOCALVIDMEM

New for DirectX 7.0. The Direct3D texture manager uses this capability to decide
whether to put managed surfaces in nonlocal video memory. If the capability is set, the
texture manager puts managed surfaces in nonlocal video memory. Drivers that cannot
texture from local video memory should not set this capability.

DDCAPS2_VIDEOPORT

Display hardware supports live video.

DDCAPS2_WIDESURFACES

The display surface supports surfaces wider than the primary surface.

dwCKeyCaps

This value consists of one or more of the following flags that specify color-key
capabilities.

DDCKEYCAPS_DESTBLT

Supports transparent blitting with a color key that identifies the replaceable bits of the
destination surface for RGB colors.

DDCKEYCAPS_DESTBLTCLRSPACE
Supports transparent blitting with a color space that identifies the replaceable bits of
the destination surface for RGB colors.

DDCKEYCAPS_DESTBLTCLRSPACEYUV

Supports transparent blitting with a color space that identifies the replaceable bits of
the destination surface for YUV colors.
DDCKEYCAPS_DESTBLTYUV
Supports transparent blitting with a color key that identifies the replaceable bits of the
destination surface for YUV colors.

DDCKEYCAPS_DESTOVERLAY
Supports overlaying with color keying of the replaceable bits of the destination surface
to be overlaid for RGB colors.

DDCKEYCAPS_DESTOVERLAYCLRSPACE

Supports a color space as the color key for the destination of RGB colors.

DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV

Supports a color space as the color key for the destination of YUV colors.

DDCKEYCAPS_DESTOVERLAYONEACTIVE

Supports only one active destination color key value for visible overlay surfaces.

DDCKEYCAPS_DESTOVERLAYYUV

Supports overlaying, using color keying of the replaceable bits of the destination surface
to be overlaid for YUV colors.

DDCKEYCAPS_NOCOSTOVERLAY

Indicates that there are no bandwidth trade-offs for using the color key with an overlay.

DDCKEYCAPS_SRCBLT

Supports transparent blitting, using the color key for the source with this surface for
RGB colors.

DDCKEYCAPS_SRCBLTCLRSPACE
Supports transparent blitting, using a color space for the source with this surface for
RGB colors.
DDCKEYCAPS_SRCBLTCLRSPACEYUV
Supports transparent blitting, using a color space for the source with this surface for
YUV colors.

DDCKEYCAPS_SRCBLTYUV
Supports transparent blitting, using the color key for the source with this surface for
YUV colors.

DDCKEYCAPS_SRCOVERLAY

Supports overlaying, using the color key for the source with this overlay surface for RGB
colors.

DDCKEYCAPS_SRCOVERLAYCLRSPACE
Supports overlaying, using a color space as the source color key for the overlay surface
for RGB colors.

DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV
Supports overlaying, using a color space as the source color key for the overlay surface
for YUV colors.

DDCKEYCAPS_SRCOVERLAYONEACTIVE

Supports only one active source color key value for visible overlay surfaces.

DDCKEYCAPS_SRCOVERLAYYUV

Supports overlaying, using the color key for the source with this overlay surface for YUV
colors.

dwFXCaps

This value consists of one or more of the following flags that specify driver stretching
and effects capabilities.

DDFXCAPS_BLTALPHA
Supports alpha-blended bitblt operations.

DDFXCAPS_BLTARITHSTRETCHY
Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink
surfaces during a bitblt operation. Occurs along the y-axis (vertically).

DDFXCAPS_BLTARITHSTRETCHYN

Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink
surfaces during a bitblt operation. Occurs along the y-axis (vertically), and works only for
integer stretching (×1, ×2, and so on).

DDFXCAPS_BLTFILTER

Driver can do surface-reconstruction filtering for warped bitblts.

DDFXCAPS_BLTMIRRORLEFTRIGHT
Supports mirroring left to right in a bitblt operation.

DDFXCAPS_BLTMIRRORUPDOWN
Supports mirroring top to bottom in a bitblt operation.

DDFXCAPS_BLTROTATION
Supports arbitrary rotation in a bitblt operation.

DDFXCAPS_BLTROTATION90
Supports 90-degree rotations in a bitblt operation.

DDFXCAPS_BLTSHRINKX
Supports arbitrary shrinking of a surface along the x-axis (horizontally). This flag is valid
only for bitblt operations.

DDFXCAPS_BLTSHRINKXN
Supports integer shrinking (×1, ×2, and so on) of a surface along the x-axis
(horizontally). This flag is valid only for bitblt operations.

DDFXCAPS_BLTSHRINKY

Supports arbitrary shrinking of a surface along the y-axis (vertically). This flag is valid
only for bitblt operations.

DDFXCAPS_BLTSHRINKYN
Supports integer shrinking (×1, ×2, and so on) of a surface along the y-axis (vertically).
This flag is valid only for bitblt operations.

DDFXCAPS_BLTSTRETCHX

Supports arbitrary stretching of a surface along the x-axis (horizontally). This flag is valid
only for bitblt operations.

DDFXCAPS_BLTSTRETCHXN

Supports integer stretching (×1, ×2, and so on) of a surface along the x-axis
(horizontally). This flag is valid only for bitblt operations.

DDFXCAPS_BLTSTRETCHY
Supports arbitrary stretching of a surface along the y-axis (vertically). This flag is valid
only for bitblt operations.

DDFXCAPS_BLTSTRETCHYN

Supports integer stretching (×1, ×2, and so on) of a surface along the y-axis (vertically).
This flag is valid only for bitblt operations.

DDFXCAPS_BLTTRANSFORM
Supports geometric transformations (or warps) for blitted sprites. Transformations are
not currently supported for explicit bitblt operations.

DDFXCAPS_OVERLAYALPHA
Supports alpha blending for overlay surfaces.

DDFXCAPS_OVERLAYARITHSTRETCHY
Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink
overlay surfaces. Occurs along the y-axis (vertically).

DDFXCAPS_OVERLAYARITHSTRETCHYN

Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink
overlay surfaces. Occurs along the y-axis (vertically), and works only for integer
stretching (×1, ×2, and so on).

DDFXCAPS_OVERLAYFILTER

Supports surface-reconstruction filtering for warped overlay sprites. Filtering is not

currently supported for explicitly displayed overlay surfaces (those displayed with calls
to IDirectDrawSurface7::UpdateOverlay).

DDFXCAPS_OVERLAYMIRRORLEFTRIGHT
Supports mirroring of overlays across the vertical axis.

DDFXCAPS_OVERLAYMIRRORUPDOWN
Supports mirroring of overlays across the horizontal axis.

DDFXCAPS_OVERLAYSHRINKX
Supports arbitrary shrinking of a surface along the x-axis (horizontally). This flag is valid
only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a
surface; it does not indicate that shrinking is available.

DDFXCAPS_OVERLAYSHRINKXN
Supports integer shrinking (×1, ×2, and so on) of a surface along the x-axis
(horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates
only the capabilities of a surface; it does not indicate that shrinking is available.

DDFXCAPS_OVERLAYSHRINKY
Supports arbitrary shrinking of a surface along the y-axis (vertically). This flag is valid
only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a
surface; it does not indicate that shrinking is available.

DDFXCAPS_OVERLAYSHRINKYN
Supports integer shrinking (×1, ×2, and so on) of a surface along the y-axis (vertically).
This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the
capabilities of a surface; it does not indicate that shrinking is available.

DDFXCAPS_OVERLAYSTRETCHX
Supports arbitrary stretching of a surface along the x-axis (horizontally). This flag is valid
only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a
surface; it does not indicate that stretching is available.

DDFXCAPS_OVERLAYSTRETCHXN

Supports integer stretching (×1, ×2, and so on) of a surface along the x-axis
(horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates
only the capabilities of a surface; it does not indicate that stretching is available.

DDFXCAPS_OVERLAYSTRETCHY

Supports arbitrary stretching of a surface along the y-axis (vertically). This flag is valid
only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a
surface; it does not indicate that stretching is available.

DDFXCAPS_OVERLAYSTRETCHYN
Supports integer stretching (×1, ×2, and so on) of a surface along the y-axis (vertically).
This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the
capabilities of a surface; it does not indicate that stretching is available.

DDFXCAPS_OVERLAYTRANSFORM
Supports geometric transformations (or warps) for overlay sprites. Transformations are
not currently supported for explicitly displayed overlay surfaces (those displayed with
calls to IDirectDrawSurface7::UpdateOverlay).
dwFXAlphaCaps

This value consists of one or more of the following flags that specify driver alpha
capabilities.

DDFXALPHACAPS_BLTALPHAEDGEBLEND
Supports alpha blending around the edge of a source color-keyed surface. Used for
bitblt operations.

DDFXALPHACAPS_BLTALPHAPIXELS

Supports alpha information in pixel format. The bit depth of alpha information in the
pixel format can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha
value increases. Regardless of the depth of the alpha information, 0 is always the fully
transparent value. Used for bitblt operations.

DDFXALPHACAPS_BLTALPHAPIXELSNEG

Supports alpha information in pixel format. The bit depth of alpha information in the
pixel format can be 1, 2, 4, or 8. The alpha value becomes more transparent as the alpha
value increases. Regardless of the depth of the alpha information, 0 is always the fully
opaque value. This flag can be used only if DDCAPS_ALPHA is set. Used for bitblt
operations.

DDFXALPHACAPS_BLTALPHASURFACES
Supports alpha-only surfaces. The bit depth of an alpha-only surface can be 1, 2, 4, or 8.
The alpha value becomes more opaque as the alpha value increases. Regardless of the
depth of the alpha information, 0 is always the fully transparent value. Used for bitblt
operations.

DDFXALPHACAPS_BLTALPHASURFACESNEG
Indicates that the alpha channel becomes more transparent as the alpha value increases.
The depth of the alpha channel-data can be 1, 2, 4, or 8. Regardless of the depth of the
alpha information, 0 is always the fully opaque value. This flag can be set only if
DDCAPS_ALPHA has been set. Used for bitblt operations.

DDFXALPHACAPS_OVERLAYALPHAEDGEBLEND
Supports alpha blending around the edge of a source color-keyed surface. Used for
overlays.

DDFXALPHACAPS_OVERLAYALPHAPIXELS

Supports alpha information in pixel format. The bit depth of alpha information in pixel
format can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value
increases. Regardless of the depth of the alpha information, 0 is always the fully
transparent value. Used for overlays.

DDFXALPHACAPS_OVERLAYALPHAPIXELSNEG
Supports alpha information in pixel format. The bit depth of alpha information in pixel
format can be 1, 2, 4, or 8. The alpha value becomes more transparent as the alpha value
increases. Regardless of the depth of the alpha information, 0 is always the fully opaque
value. This flag can be used only if DDCAPS_ALPHA has been set. Used for overlays.

DDFXALPHACAPS_OVERLAYALPHASURFACES
Supports alpha-only surfaces. The bit depth of an alpha-only surface can be 1, 2, 4, or 8.
The alpha value becomes more opaque as the alpha value increases. Regardless of the
depth of the alpha information, 0 is always the fully transparent value. Used for overlays.

DDFXALPHACAPS_OVERLAYALPHASURFACESNEG

Indicates that the alpha channel becomes more transparent as the alpha value increases.
The depth of the alpha-channel data can be 1, 2, 4, or 8. Regardless of the depth of the
alpha information, 0 is always the fully opaque value. This flag can be used only if
DDCAPS_ALPHA has been set. Used for overlays.

dwPalCaps

This value consists of one or more of the following flags that specify palette capabilities.

DDPCAPS_1BIT

Supports palettes that contain 1-bit color entries (two colors).

DDPCAPS_2BIT

Supports palettes that contain 2-bit color entries (four colors).

DDPCAPS_4BIT
Supports palettes that contain 4-bit color entries (16 colors).

DDPCAPS_8BIT

Supports palettes that contain 8-bit color entries (256 colors).

DDPCAPS_8BITENTRIES

Specifies an index to an 8-bit color index. This field is valid only when used with the
DDPCAPS_1BIT, DDPCAPS_2BIT, or DDPCAPS_4BIT capability and when the target
surface is 8 bits per pixel (bpp). Each color entry is 1 byte long and is an index to an 8-
bpp palette on the destination surface.

DDPCAPS_ALPHA
Supports palettes that include an alpha component. For alpha-capable palettes, the
peFlags member of each PALETTEENTRY structure that the palette contains is to be
interpreted as a single 8-bit alpha value (in addition to the color data in the peRed,
peGreen, and peBlue members). A palette created with this flag can be attached only to
a texture surface.

DDPCAPS_ALLOW256

Supports palettes that can have all 256 entries defined.

DDPCAPS_PRIMARYSURFACE

The palette is attached to the primary surface. Changing the palette has 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 on the left. Changing the palette has an
immediate effect on the display unless the DDPCAPS_VSYNC capability is specified and
supported.

DDPCAPS_VSYNC
The palette can be modified synchronously with the monitor's refresh rate.

dwSVCaps

This value consists of one or more of the following flags that specify stereo-vision
capabilities.

DDSVCAPS_RESERVED1, DDSVCAPS_RESERVED2,
DDSVCAPS_RESERVED3, DDSVCAPS_RESERVED4
Reserved flags.

DDSVCAPS_STEREOSEQUENTIAL
New for DirectX 7.0. The driver can do stereo in at least one mode other than the
current mode. The application can use IDirectDraw7::GetDisplayMode or
IDirectDraw7::EnumDisplayModes to get per-mode stereo information.

dwAlphaBltConstBitDepths

DDBD_2, DDBD_4, or DDBD_8. (Indicate 2, 4, or 8 bits per pixel.)

dwAlphaBltPixelBitDepths

DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicate 1, 2, 4, or 8 bits per pixel.)

dwAlphaBltSurfaceBitDepths

DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicate 1, 2, 4, or 8 bits per pixel.)

dwAlphaOverlayConstBitDepths

DDBD_2, DDBD_4, or DDBD_8. (Indicate 2, 4, or 8 bits per pixel.)

dwAlphaOverlayPixelBitDepths

DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicate 1, 2, 4, or 8 bits per pixel.)

dwAlphaOverlaySurfaceBitDepths

DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicate 1, 2, 4, or 8 bits per pixel.)

dwZBufferBitDepths

DDBD_8, DDBD_16, DDBD_24, or DDBD_32. (Indicate 8, 16, 24, or 32 bits per pixel.) This
member is obsolete for DirectX 6.0 and later. Use the IDirect3D7::EnumZBufferFormats
to retrieve information about supported depth buffer formats.

dwVidMemTotal

Total amount of display memory on the device, in bytes, minus memory reserved for the
primary surface and any private data structures reserved by the driver. (This value is the
same as the total video memory reported by the IDirectDraw7::GetAvailableVidMem
method.)

dwVidMemFree

Free display memory. This value equals the value in dwVidMemTotal, minus any
memory currently allocated by the application for surfaces. Unlike the
IDirectDraw7::GetAvailableVidMem method, which reports the memory available for a
particular type of surface (such as a texture), this value reflects the memory available for
any type of surface.

dwMaxVisibleOverlays

Maximum number of visible overlays or overlay sprites.

dwCurrVisibleOverlays

Current number of visible overlays or overlay sprites.

dwNumFourCCCodes

Number of FourCC codes.

dwAlignBoundarySrc

Source-rectangle alignment for an overlay surface, in pixels.

dwAlignSizeSrc

Source-rectangle size alignment for an overlay surface, in pixels. Overlay source

rectangles must have a pixel width that is a multiple of this value.

dwAlignBoundaryDest

Destination-rectangle alignment for an overlay surface, in pixels.

dwAlignSizeDest

Destination-rectangle size alignment for an overlay surface, in pixels. Overlay destination

rectangles must have a pixel width that is a multiple of this value.
dwAlignStrideAlign

Stride alignment.

dwRops[DD_ROP_SPACE]

Raster operations supported.

ddsCaps

A DDSCAPS2 structure that contains general surface capabilities.

dwMinOverlayStretch

Minimum overlay stretch factor, multiplied by 1000. For example, 1.3 = 1300.

dwMaxOverlayStretch

Maximum overlay stretch factor, multiplied by 1000. For example, 1.3 = 1300.

dwMinLiveVideoStretch

Obsolete; do not use.

dwMaxLiveVideoStretch

Obsolete; do not use.

dwMinHwCodecStretch

Obsolete; do not use.

dwMaxHwCodecStretch

Obsolete; do not use.

dwReserved1

Reserved

dwReserved2

Reserved

dwReserved3

Reserved
dwSVBCaps

Driver-specific capabilities for bitblts from system memory to display memory. Valid
flags are identical to the bitblt-related flags that are used with the dwCaps member.

dwSVBCKeyCaps

Driver color-key capabilities for bitblts from system memory to display memory. Valid
flags are identical to the bitblt-related flags that are used with the dwCKeyCaps
member.

dwSVBFXCaps

Driver FX capabilities for bitblts from system memory to display memory. Valid flags are
identical to the bitblt-related flags that are used with the dwFXCaps member.

dwSVBRops[DD_ROP_SPACE]

Raster operations supported for bitblts from system memory to display memory.

dwVSBCaps

Driver-specific capabilities for bitblts from display memory to system memory. Valid
flags are identical to the bitblt-related flags that are used with the dwCaps member.

dwVSBCKeyCaps

Driver color-key capabilities for bitblts from display memory to system memory. Valid
flags are identical to the bitblt-related flags that are used with the dwCKeyCaps
member.

dwVSBFXCaps

Driver FX capabilities for bitblts from display memory to system memory. Valid flags are
identical to the bitblt-related flags used with the dwFXCaps member.

dwVSBRops[DD_ROP_SPACE]

Raster operations supported for bitblts from display memory to system memory.

dwSSBCaps

Driver-specific capabilities for bitblts from system memory to system memory. Valid
flags are identical to the bitblt-related flags used with the dwCaps member.

dwSSBCKeyCaps
Driver color-key capabilities for bitblts from system memory to system memory. Valid
flags are identical to the bitblt-related flags used with the dwCKeyCaps member.

dwSSBFXCaps

Driver FX capabilities for bitblts from system memory to system memory. Valid flags are
identical to the bitblt-related flags used with the dwFXCaps member.

dwSSBRops[DD_ROP_SPACE]

Raster operations supported for bitblts from system memory to system memory.

dwReserved4

Reserved

dwReserved5

Reserved

dwReserved6

Reserved

Remarks
For backward compatibility, the Ddraw.h header file contains multiple definitions of the
DDCAPS structure. The version that passes the preprocessor is determined by the value
of the DIRECTDRAW_VERSION constant.

Requirements

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDCOLORCONTROL structure (ddraw.h)
Article09/15/2022

The DDCOLORCONTROL structure defines the color controls associated with a Microsoft
DirectDraw video port extensions (VPE) object.

Syntax
C++

typedef struct _DDCOLORCONTROL {

DWORD dwSize;
DWORD dwFlags;
LONG lBrightness;
LONG lContrast;
LONG lHue;
LONG lSaturation;
LONG lSharpness;
LONG lGamma;
LONG lColorEnable;
DWORD dwReserved1;
} *LPDDCOLORCONTROL, DDCOLORCONTROL;

Members
dwSize

Specifies the size in bytes of this DDCOLORCONTROL structure.

dwFlags

Indicates a set of flags that specify what structure members contain valid data. When
the structure is returned by DdVideoPortColorControl , it also indicates what options
are supported by the VPE object. This member can be a bitwise OR of the values listed
in the following table.

Flag Meaning

DDCOLOR_BRIGHTNESS The lBrightness member contains valid data.

DDCOLOR_CONTRAST The lContrast member contains valid data.

DDCOLOR_COLORENABLE The lColorEnable member contains valid data.

 Flag Meaning

DDCOLOR_GAMMA The lGamma member contains valid data.

DDCOLOR_HUE The lHue member contains valid data.

DDCOLOR_SATURATION The lSaturation member contains valid data.

DDCOLOR_SHARPNESS The lSharpness member contains valid data.

lBrightness

Specifies the luminance intensity (Black Level), in IRE units*100. This member can range
from 0 to 10,000, with a default value of 750 (7.5 IRE).

lContrast

Specifies the relative difference between higher and lower intensity luminance values, in
IRE units*100. This member can range from 0 to 20,000, with a default value of 10,000
(100 IRE). Higher values of contrast cause darker luminance values to tend toward black,
and cause lighter luminance values to tend toward white. Lower values of contrast cause
all luminance values to move toward the middle luminance values.

lHue

Specifies the phase relationship of the chrominance components. Hue is specified in

degrees, with a valid range of -180 to 180. The default is 0 degrees.

lSaturation

Specifies the color intensity, in IRE units*100. This member can range from 0 to 20,000,
with a default value of 10,000 (100 IRE).

lSharpness

Specifies the sharpness in arbitrary units. The valid range is 0 to 10, with a default value
of 5.

lGamma

Controls the amount of gamma correction applied to the luminance values. The valid
range is 1 to 500 gamma units, with a default of 1.

lColorEnable

Specifies a flag indicating whether color is used. If this member is zero, color is not used;
if it is 1, then color is used. The default value is 1.
dwReserved1

Reserved for system use, and should be ignored.

Requirements

Header ddraw.h

See also
DdVideoPortColorControl

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDCOLORKEY structure (ddraw.h)
Article04/02/2021

The DDCOLORKEY structure describes a source color key, destination color key, or color
space. A color key is specified if the low and high range values are the same. This
structure is used with the IDirectDrawSurface7::GetColorKey and
IDirectDrawSurface7::SetColorKey methods.

Syntax
C++

typedef struct _DDCOLORKEY {

DWORD dwColorSpaceLowValue;
DWORD dwColorSpaceHighValue;
} DDCOLORKEY;

Members
dwColorSpaceLowValue

Low value of the color range that is to be used as the color key.

dwColorSpaceHighValue

High value of the color range that is to be used as the color key.

Requirements

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDDEVICEIDENTIFIER2 structure
(ddraw.h)
Article09/01/2022

The DDDEVICEIDENTIFIER2 structure is passed to the IDirectDraw7::GetDeviceIdentifier

method to obtain information about a device.

Syntax
C++

typedef struct tagDDDEVICEIDENTIFIER2 {

char szDriver[MAX_DDDEVICEID_STRING];
char szDescription[MAX_DDDEVICEID_STRING];
LARGE_INTEGER liDriverVersion;
DWORD dwDriverVersionLowPart;
DWORD dwDriverVersionHighPart;
DWORD dwVendorId;
DWORD dwDeviceId;
DWORD dwSubSysId;
DWORD dwRevision;
GUID guidDeviceIdentifier;
DWORD dwWHQLLevel;
} DDDEVICEIDENTIFIER2, *LPDDDEVICEIDENTIFIER2;

Members
szDriver[MAX_DDDEVICEID_STRING]

Name of the driver.

szDescription[MAX_DDDEVICEID_STRING]

Description of the driver.

liDriverVersion

Version of the driver. It is valid to do less than and greater than comparisons on all 64
bits. Caution should be exercised if you use this element to identify problematic drivers;
instead, use the guidDeviceIdentifier member for this purpose.

The data takes the following form:

 wProduct = HIWORD(liDriverVersion.HighPart)
wVersion = LOWORD(liDriverVersion.HighPart)
wSubVersion = HIWORD(liDriverVersion.LowPart)
wBuild = LOWORD(liDriverVersion.LowPart)

dwDriverVersionLowPart

dwDriverVersionHighPart

dwVendorId

Identifier of the manufacturer. Can be 0 if unknown.

dwDeviceId

Identifier of the type of chipset. Can be 0 if unknown.

dwSubSysId

Identifier of the subsystem. Typically, this means the particular board. Can be 0 if
unknown.

dwRevision

Identifier of the revision level of the chipset. Can be 0 if unknown.

guidDeviceIdentifier

Unique identifier for the driver and chipset pair. Use this value if you want to track
changes to the driver or chipset to reprofile the graphics subsystem. It can also be used
to identify particular problematic drivers.

dwWHQLLevel

The Windows Hardware Quality Lab (WHQL) certification level for the device and driver
pair.

Remarks
The values in szDriver and szDescription are for presentation to the user only. They
should not be used to identify particular drivers because different strings might be
associated with the same device, or the same driver from different vendors might be
described differently.

The dwVendorId, dwDeviceId, dwSubSysId, and dwRevision members can be used to

identify particular chipsets, but use extreme caution.

Requirements

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDGAMMARAMP structure (ddraw.h)
Article09/01/2022

The DDGAMMARAMP structure contains red, green, and blue ramp data for the
IDirectDrawGammaControl::GetGammaRamp and
IDirectDrawGammaControl::SetGammaRamp methods.

Syntax
C++

typedef struct _DDGAMMARAMP {

WORD red[256];
WORD green[256];
WORD blue[256];
} DDGAMMARAMP;

Members
red[256]

Array of 256 WORD elements that describe the red gamma ramp.

green[256]

Array of 256 WORD elements that describe the green gamma ramp.

blue[256]

Array of 256 WORD elements that describe the blue gamma ramp.

Requirements

Header ddraw.h

Feedback

ﾂ ﾄ
 ﾂ Yes ﾄ No
Was this page helpful?

Get help at Microsoft Q&A

DDOVERLAYFX structure (ddraw.h)
Article11/23/2021

The DDOVERLAYFX structure passes overlay information to the

IDirectDrawSurface7::UpdateOverlay method.

Syntax
C++

typedef struct _DDOVERLAYFX {

DWORD dwSize;
DWORD dwAlphaEdgeBlendBitDepth;
DWORD dwAlphaEdgeBlend;
DWORD dwReserved;
DWORD dwAlphaDestConstBitDepth;
#if ...
union {
DWORD dwAlphaDestConst;
LPDIRECTDRAWSURFACE lpDDSAlphaDest;
} DUMMYUNIONNAMEN;
DWORD dwAlphaSrcConstBitDepth;
#else
union {
DWORD dwAlphaSrcConst;
LPDIRECTDRAWSURFACE lpDDSAlphaSrc;
} DUMMYUNIONNAMEN;
#endif
DDCOLORKEY dckDestColorkey;
DDCOLORKEY dckSrcColorkey;
DWORD dwDDFX;
DWORD dwFlags;
} DDOVERLAYFX;

Members
dwSize

Size of the structure, in bytes. This member must be initialized before the structure is
used.

dwAlphaEdgeBlendBitDepth

Bit depth used to specify the constant for an alpha edge blend.
dwAlphaEdgeBlend

Constant to use as the alpha for an edge blend.

dwReserved

Reserved

dwAlphaDestConstBitDepth

Bit depth used to specify the alpha constant for a destination.

DUMMYUNIONNAMEN

See Remarks.

DUMMYUNIONNAMEN.dwAlphaDestConst

Constant to use as the alpha channel for a destination.

DUMMYUNIONNAMEN.lpDDSAlphaDest

Address of a surface to use as the alpha channel for a destination.

dwAlphaSrcConstBitDepth

Bit depth used to specify the alpha constant for a source.

DUMMYUNIONNAMEN.dwAlphaSrcConst

Constant to use as the alpha channel for a source.

DUMMYUNIONNAMEN.lpDDSAlphaSrc

Address of a surface to use as the alpha channel for a source.

dckDestColorkey

Destination color key for the overlay.

dckSrcColorkey

Source color key for the overlay.

dwDDFX

The following flags that specify overlay effects.

DDOVERFX_ARITHSTRETCHY
If stretching, use arithmetic stretching along the y-axis for this overlay.

DDOVERFX_MIRRORLEFTRIGHT

Mirror the overlay around the vertical axis.

DDOVERFX_MIRRORUPDOWN

Mirror the overlay around the horizontal axis.

dwFlags

Currently not used and must be set to 0.

Remarks
The unions in this structure have been updated to work with compilers that do not
support nameless unions. If your compiler does not support nameless unions, define the
NONAMELESSUNION token before including the Ddraw.h header file.

Requirements

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDPIXELFORMAT structure (ddraw.h)
Article11/23/2021

The DDPIXELFORMAT structure describes the pixel format of a DirectDrawSurface

object for the IDirectDrawSurface7::GetPixelFormat method.

Note Rather than use this structure to decode files with the DirectDraw Surface
(DDS) file format (.dds), you should use an alternative structure that does not rely
on Ddraw.h. For more information about alternative structures for DDS, see DDS.

Syntax
C++

typedef struct _DDPIXELFORMAT {

DWORD dwSize;
DWORD dwFlags;
DWORD dwFourCC;
#if ...
union {
DWORD dwRGBBitCount;
DWORD dwYUVBitCount;
DWORD dwZBufferBitDepth;
DWORD dwAlphaBitDepth;
DWORD dwLuminanceBitCount;
DWORD dwBumpBitCount;
DWORD dwPrivateFormatBitCount;
} DUMMYUNIONNAMEN;
#elif
union {
DWORD dwRBitMask;
DWORD dwYBitMask;
DWORD dwStencilBitDepth;
DWORD dwLuminanceBitMask;
DWORD dwBumpDuBitMask;
DWORD dwOperations;
} DUMMYUNIONNAMEN;
#elif
union {
DWORD dwGBitMask;
DWORD dwUBitMask;
DWORD dwZBitMask;
DWORD dwBumpDvBitMask;
struct {
WORD wFlipMSTypes;
WORD wBltMSTypes;
 } MultiSampleCaps;
} DUMMYUNIONNAMEN;
#elif
union {
DWORD dwBBitMask;
DWORD dwVBitMask;
DWORD dwStencilBitMask;
DWORD dwBumpLuminanceBitMask;
} DUMMYUNIONNAMEN;
#else
union {
DWORD dwRGBAlphaBitMask;
DWORD dwYUVAlphaBitMask;
DWORD dwLuminanceAlphaBitMask;
DWORD dwRGBZBitMask;
DWORD dwYUVZBitMask;
} DUMMYUNIONNAMEN;
#endif
} DDPIXELFORMAT;

Members
dwSize

Size of the structure, in bytes. This member must be initialized before the structure is
used.

dwFlags

The following flags to describe optional controls for this structure.

DDPF_ALPHA

The pixel format describes an alpha-only surface.

DDPF_ALPHAPIXELS

The surface has alpha channel information in the pixel format.

DDPF_ALPHAPREMULT

The surface uses the premultiplied alpha format. That is, the color components in each
pixel are premultiplied by the alpha component.

DDPF_BUMPLUMINANCE
The luminance data in the pixel format is valid, and the dwLuminanceBitMask member
describes valid luminance bits for a luminance-only or luminance-alpha surface.

DDPF_BUMPDUDV

Bump-map data in the pixel format is valid. Bump-map information is in the

dwBumpBitCount, dwBumpDuBitMask, dwBumpDvBitMask, and
dwBumpLuminanceBitMask members.

DDPF_COMPRESSED

The surface accepts pixel data in the specified format and compress it during the write
operation.

DDPF_D3DFORMAT

Indicates a DirectX 8.0 and later format capability entry in the texture format list. This
flag is not exposed to applications and is defined in Ddrawi.h.

DDPF_FOURCC
The dwFourCC member is valid and contains a FOURCC code that describes a non-RGB
pixel format.

DDPF_LUMINANCE

The pixel format describes a luminance-only or luminance-alpha surface.

DDPF_PALETTEINDEXED1

The surface is 1-bit color-indexed.

DDPF_PALETTEINDEXED2

The surface is 2-bit color-indexed.

DDPF_PALETTEINDEXED4

The surface is 4-bit color-indexed.

DDPF_PALETTEINDEXED8
The surface is 8-bit color-indexed.

DDPF_PALETTEINDEXEDTO8

The surface is 1-, 2-, or 4-bit color-indexed to an 8-bit palette.

DDPF_RGB

The RGB data in the pixel format structure is valid.

DDPF_RGBTOYUV

The surface accepts RGB data and translates it during the write operation to YUV data.
The format of the data to be written is contained in the pixel format structure. The
DDPF_RGB flag is set.

DDPF_STENCILBUFFER

The surface encodes stencil and depth information in each pixel of the z-buffer. This flag
can be used only if the DDPF_ZBUFFER flag is also specified.

DDPF_YUV
The YUV data in the pixel format structure is valid.

DDPF_ZBUFFER

The pixel format describes a z-buffer surface.

DDPF_ZPIXELS

The surface contains z information in the pixels.

dwFourCC

A FourCC code.

DUMMYUNIONNAMEN

DUMMYUNIONNAMEN.dwRGBBitCount
RGB bits per pixel (4, 8, 16, 24, or 32).

DUMMYUNIONNAMEN.dwYUVBitCount

YUV bits per pixel (4, 8, 16, 24, or 32).

DUMMYUNIONNAMEN.dwZBufferBitDepth

Z-buffer bit depth (8, 16, 24, or 32).

DUMMYUNIONNAMEN.dwAlphaBitDepth

Alpha channel bit depth (1, 2, 4, or 8) for an alpha-only surface (DDPF_ALPHA). For pixel
formats that contain alpha information interleaved with color data (DDPF_ALPHAPIXELS),
count the bits in the dwRGBAlphaBitMask member to obtain the bit depth of the alpha
component. For more information about how to determine alpha bit depth, see
Remarks.

DUMMYUNIONNAMEN.dwLuminanceBitCount

Total luminance bits per pixel. This member applies only to luminance-only and
luminance-alpha surfaces.

DUMMYUNIONNAMEN.dwBumpBitCount

Total bump-map bits per pixel in a bump-map surface.

DUMMYUNIONNAMEN.dwPrivateFormatBitCount

Bits per pixel of private driver formats. Only valid in texture format list and if
DDPF_D3DFORMAT is set.

DUMMYUNIONNAMEN.dwRBitMask

Mask for red bits.

DUMMYUNIONNAMEN.dwYBitMask

Mask for Y bits.

DUMMYUNIONNAMEN.dwStencilBitDepth

Bit depth of the stencil buffer. This member specifies how many bits are reserved within
each pixel of the z-buffer for stencil information (the total number of z-bits is equal to
dwZBufferBitDepth minus dwStencilBitDepth).

DUMMYUNIONNAMEN.dwLuminanceBitMask
Mask for luminance bits.

DUMMYUNIONNAMEN.dwBumpDuBitMask

Mask for bump-map U-delta bits.

DUMMYUNIONNAMEN.dwOperations

Flags that specify the operations that can be performed on surfaces with the
DDPF_D3DFORMAT pixel format. The flags are defined in Ddrawi.h.

DUMMYUNIONNAMEN.dwGBitMask

Mask for green bits.

DUMMYUNIONNAMEN.dwUBitMask

Mask for U bits.

DUMMYUNIONNAMEN.dwZBitMask

Mask for z bits.

DUMMYUNIONNAMEN.dwBumpDvBitMask

Mask for bump-map V-delta bits.

DUMMYUNIONNAMEN.MultiSampleCaps

A structure that contains the following two members. This structure is used to specify
surfaces that can be used when performing multisample rendering. Each bit in the 16-bit
masks indicates support of multisampling with a specific number of samples. For
example, bit 0 indicates support of multisampling with only a single sample, bit 1
indicates the support of multisampling with two samples, and so on. The driver can
indicate more than one supported level by combining the bits by using a bitwise OR.

DUMMYUNIONNAMEN.MultiSampleCaps.wFlipMSTypes

A 16-bit mask for full-screen (flip) mode multisampling.

DUMMYUNIONNAMEN.MultiSampleCaps.wBltMSTypes

A 16-bit mask for windowed (bit-block transfer) mode multisampling.

DUMMYUNIONNAMEN.dwBBitMask

Mask for blue bits.

DUMMYUNIONNAMEN.dwVBitMask

Mask for V bits.

DUMMYUNIONNAMEN.dwStencilBitMask

Mask for stencil bits within each z-buffer pixel.

DUMMYUNIONNAMEN.dwBumpLuminanceBitMask

Mask for luminance in a bump-map pixel.

DUMMYUNIONNAMEN.dwRGBAlphaBitMask

RGB mask for the alpha channel.

DUMMYUNIONNAMEN.dwYUVAlphaBitMask

YUV mask for the alpha channel.

DUMMYUNIONNAMEN.dwLuminanceAlphaBitMask

Luminance mask for the alpha channel.

DUMMYUNIONNAMEN.dwRGBZBitMask

RGB mask for the z channel.

DUMMYUNIONNAMEN.dwYUVZBitMask

YUV mask for the z channel.

Remarks
The dwAlphaBitDepth member reflects the bit depth of an alpha-only pixel format
(DDPF_ALPHA). For pixel formats that include the alpha component with color
components (DDPF_ALPHAPIXELS), the alpha bit depth is obtained by counting the bits
in the various mask members. The following code example returns the number of bits
set in a given bitmask.

C++

WORD GetNumberOfBits( DWORD dwMask )

{
WORD wBits = 0;
while( dwMask )
{
 dwMask = dwMask & ( dwMask - 1 );
wBits++;
}
return wBits;
}

The unions in DDPIXELFORMAT have been updated to work with compilers that do not
support nameless unions. If your compiler does not support nameless unions, define the
NONAMELESSUNION token before including the Ddraw.h header file.

Requirements

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDSCAPS structure (ddraw.h)
Article02/16/2023

The DDSCAPS structure defines the capabilities of a Microsoft DirectDraw surface object.

Syntax
C++

typedef struct _DDSCAPS {

DWORD dwCaps;
} DDSCAPS;

Members
dwCaps

Indicates a set of flags that specify the capabilities of the surface. This member is a
bitwise OR of any of the following flags:

Flag Meaning

DDSCAPS_3DDEVICE This surface can be used for 3D rendering. Applications can

use this flag to ensure that a device that can only render to a
certain heap has offscreen surfaces allocated from the correct
heap. If this flag is set for a heap, the surface is not allocated
from that heap.

DDSCAPS_ALLOCONLOAD Memory for the surface is not allocated until the surface is
loaded by the application using the IDirect3DTexture::Load
method.

DDSCAPS_ALPHA This surface contains alpha information only.

Flag Meaning

DDSCAPS_BACKBUFFER This surface is the back buffer of a surface flipping structure.

Typically, this capability is set by the application's
CreateSurface method when the DDSCAPS_FLIP flag is used.
Only the surface that immediately precedes the
DDSCAPS_FRONTBUFFER surface has this capability set. The
other surfaces are identified as back buffers by the presence
of the DDSCAPS_FLIP flag, their attachment order, and the
absence of the DDSCAPS_FRONTBUFFER and
DDSCAPS_BACKBUFFER capabilities. If this capability is sent to
the application's CreateSurface method, a stand-alone back
buffer is being created. After this method is called, this
surface could be attached to a front buffer, another back
buffer, or both to form a flipping surface structure. For more
information, see the AddAttachedSurface method in the
DirectX SDK. DirectDraw supports an arbitrary number of
surfaces in a flipping structure.

DDSCAPS_COMPLEX A complex surface is being described. A complex surface

results in the creation of more than one surface. The
additional surfaces are attached to the root surface. The
complex structure can be destroyed only by destroying the
root.

DDSCAPS_EXECUTEBUFFER The surface is an execute buffer, which is a linear chunk of

system or video memory that holds a Microsoft Direct3D
display list. A driver reports this capability bit to indicate that
it can create execute buffers in video memory. If the Direct3D
runtime detects this bit, it can request execute buffers from
the driver. Applications cannot detect this capability bit.

DDSCAPS_FLIP This surface is a part of a surface flipping structure. When this

capability is passed to the application's CreateSurface
method, a front buffer and one or more back buffers are
created. DirectDraw sets the DDSCAPS_FRONTBUFFER bit on
the front-buffer surface and the DDSCAPS_BACKBUFFER bit
on the surface adjacent to the front-buffer surface. The
dwBackBufferCount member of the DDSURFACEDESC
structure must be set to at least 1 in order for the method call
to succeed. The DDSCAPS_COMPLEX capability must always
be set when creating multiple surfaces by using the
CreateSurface method.
Flag Meaning

DDSCAPS_FRONTBUFFER This surface is the front buffer of a surface flipping structure.

This flag is typically set by the application's CreateSurface
method when the DDSCAPS_FLIP capability is set. If this
capability is sent to the CreateSurface method, a stand-alone
front buffer is created. This surface does not have the
DDSCAPS_FLIP capability. It can be attached to other back
buffers to form a flipping structure by using the application's
AddAttachedSurface method.

DDSCAPS_HWCODEC This surface should be able to have a stream decompressed

to it by the hardware.

DDSCAPS_LIVEVIDEO This surface should be able to receive live video.

DDSCAPS_LOCALVIDMEM This surface exists in true, local display memory rather than
nonlocal display memory. If this flag is specified, then
DDSCAPS_VIDEOMEMORY must be specified as well. This flag
cannot be used with the DDSCAPS_NONLOCALVIDMEM flag.

DDSCAPS_MIPMAP This surface is one level of a mipmap. This surface is attached

to other DDSCAPS_MIPMAP surfaces to form the mipmap.
This can be done explicitly by creating a number of surfaces
and attaching them by using the application's
AddAttachedSurface method, or implicitly by the
application's CreateSurface method. If this capability is set,
DDSCAPS_TEXTURE must also be set.

DDSCAPS_MODEX This surface is a 320x200 or 320x240 Mode X surface. If this

capability bit is set by the Microsoft Windows 2000 or later
driver, DirectDraw is disabled.

DDSCAPS_NONLOCALVIDMEM This surface exists in nonlocal display memory rather than

true, local display memory. If this flag is specified, then
DDSCAPS_VIDEOMEMORY flag must be specified as well. This
cannot be used with the DDSCAPS_LOCALVIDMEM flag.

DDSCAPS_OFFSCREENPLAIN This surface is any offscreen surface that is not an overlay,

texture, z-buffer, front-buffer, back-buffer, or alpha surface. It
is used to identify plain surfaces.

DDSCAPS_OVERLAY This surface is an overlay. The visibility of this overlay

depends on whether it is currently being overlaid onto the
primary surface. DDSCAPS_VISIBLE can be used to determine
whether it is being overlaid at the moment.

DDSCAPS_OPTIMIZED This flag is not currently implemented.

Flag Meaning

DDSCAPS_OWNDC This surface will have a device context (DC) association for a
long period. If this capability bit is set by the Windows 2000
or later driver, DirectDraw will be disabled.

DDSCAPS_PALETTE This device driver allows unique DirectDrawPalette objects to

be created and attached to this surface.

DDSCAPS_PRIMARYSURFACE This surface is the primary surface. It represents what is visible

to the user at the moment.

DDSCAPS_PRIMARYSURFACELEFT This surface is the primary surface for the left eye. It
represents what is visible to the user's left eye at the moment.
When this surface is created, the surface with the
DDSCAPS_PRIMARYSURFACE capability represents what is
seen by the user's right eye.

DDSCAPS_STANDARDVGAMODE This surface is a standard VGA mode surface, and not a

ModeX surface. This flag cannot be used in combination with
the DDSCAPS_MODEX flag.

DDSCAPS_SYSTEMMEMORY This surface memory was allocated from system memory. If

this capability bit is set by the Windows 2000 or later driver,
DirectDraw is disabled.

DDSCAPS_TEXTURE This surface can be used as a 3D texture. It does not indicate

whether the surface is being used for that purpose.

DDSCAPS_VIDEOMEMORY This surface exists in display memory.

DDSCAPS_VIDEOPORT This surface can receive data from a video port extensions
(VPE) object.

DDSCAPS_VISIBLE Changes made to this surface are immediately visible. It is

always set for the primary surface, as well as for overlays
while they are being overlaid and texture maps while they are
being textured.

DDSCAPS_WRITEONLY Only write access is permitted to the surface. Read access

from the surface may generate a general protection fault
(GPF), but the read results from this surface are not
meaningful. If this capability bit is set by the Windows 2000
or later driver, DirectDraw is disabled.

DDSCAPS_ZBUFFER This surface is the z-buffer. It contains bit-depth information

that is used to determine which pixels are visible and which
are obscured. The z-buffer contains information that cannot
be displayed.
Remarks
This structure is used by the driver to report the types of surfaces the driver supports. It
is also filled in by an application to specify the type of surface to be created.

Requirements

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDSCAPS2 structure (ddraw.h)
Article07/12/2022

The DDSCAPS2 structure defines additional capabilities of a Microsoft DirectDraw

surface object.

Syntax
C++

typedef struct _DDSCAPS2 {

DWORD dwCaps;
DWORD dwCaps2;
DWORD dwCaps3;
union {
DWORD dwCaps4;
DWORD dwVolumeDepth;
} DUMMYUNIONNAMEN;
} DDSCAPS2;

Members
dwCaps

Specifies a set of flags representing the capabilities of the surface. The flags in this
member are identical to those in the corresponding member of the DDSCAPS structure.

dwCaps2

Specifies a set of flags that indicate additional surface capabilities. This member can
contain one or more of the following capability flags. Each of these flags, except
DDSCAPS2_TEXTUREMANAGE, are set by the application when the application calls its
CreateSurface method.

Flag Meaning
Flag Meaning

DDSCAPS2_ADDITIONALPRIMARY Microsoft DirectX 9.0 and later versions only.

Indicates that subordinate heads of a multiple-head

card are no longer in control of their video memory
after surfaces are created for those subordinate heads
with this bit set. Once such surfaces are destroyed,
subordinate heads regain control of their memory. For
more information, see Managing Multiple-Head
Memory.

DDSCAPS2_COMMANDBUFFER Marks a command buffer, used by Microsoft Direct3D

to batch commands.

DDSCAPS2_CUBEMAP This surface is a cubic environment map. When using

this flag, also specify the face or faces of the cubic
environment map to create.

DDSCAPS2_CUBEMAP_POSITIVEX This flag is used with the DDSCAPS2_CUBEMAP flag to

create the positive X face of a cubic environment map.

DDSCAPS2_CUBEMAP_NEGATIVEX This flag is used with the DDSCAPS2_CUBEMAP flag to

create the negative X face of a cubic environment
map.

DDSCAPS2_CUBEMAP_POSITIVEY This flag is used with the DDSCAPS2_CUBEMAP flag to

create the positive Y face of a cubic environment map.

DDSCAPS2_CUBEMAP_NEGATIVEY This flag is used with the DDSCAPS2_CUBEMAP flag to

create the negative Y face of a cubic environment
map.

DDSCAPS2_CUBEMAP_POSITIVEZ This flag is used with the DDSCAPS2_CUBEMAP flag to

create the positive Z face of a cubic environment map.

DDSCAPS2_CUBEMAP_NEGATIVEZ This flag is used with the DDSCAPS2_CUBEMAP flag to

create the negative Z face of a cubic environment
map.

DDSCAPS2_CUBEMAP_ALLFACES This flag is used with the DDSCAPS2_CUBEMAP flag to

create all six faces of a cubic environment map.

DDSCAPS2_D3DTEXTUREMANAGE The texture is always managed by Direct3D.

Flag Meaning

DDSCAPS2_DISCARDBACKBUFFER DirectX 8.0 and later versions only.

Indicates that preservation of the back buffer is not

required. It will be set on the primary surface and the
back buffers if the application has set
D3DSWAPEFFECT_DISCARD on the Present API.
DirectX 9.0 and later versions only. Indicates that
preservation of the depth-stencil surface is not
required.

DDSCAPS2_DONOTPERSIST The managed surface can be safely lost.

DDSCAPS2_ENABLEALPHACHANNEL DirectX 8.1 and later versions only.

Indicates to create surfaces that are part of a primary

flipping chain or that are on stand-alone back buffers.
This flag turns on the alpha channel. For more
information, see Enabling Alpha Channels On Full-
Screen Back Buffers.

DDSCAPS2_EXTENDEDFORMATPRIMARY DirectX 9.0 and later versions only.

Indicates to create a dummy primary surface for use

with a nonstandard display mode. For more
information, see Switching Between Standard and
Nonstandard Modes.

DDSCAPS2_HARDWAREDEINTERLACE The driver must convert the interlaced signal to

progressive frames. The DDSCAPS_VIDEOPORT and
DDSCAPS_OVERLAY flags in this structure must also be
set.

DDSCAPS2_HINTANTIALIASING The application will use antialiasing. This flag is valid

only if the DDSCAPS_3DDEVICE flag is also set.

DDSCAPS2_HINTDYNAMIC The application will be updating the surface

frequently. Surfaces with this flag set must also have
the DDSCAPS_TEXTURE flag in this structure set. This
flag cannot be used with the DDSCAPS2_HINTSTATIC
or DDSCAPS2_OPAQUE flags.

DDSCAPS2_HINTSTATIC The application will be updating the surface

infrequently, but still requires access. Surfaces with this
flag set must also have the DDSCAPS_TEXTURE flag in
this structure set. This flag cannot be used with the
DDSCAPS2_HINTDYNAMIC or DDSCAPS2_OPAQUE
flags.
Flag Meaning

DDSCAPS2_INDEXBUFFER DirectX 8.0 and later versions only.

Marks an index buffer, created and controlled by the

application.

DDSCAPS2_MIPMAPSUBLEVEL It enables easier use of GetAttachedSurface, rather

than EnumAttachedSurfaces, for surface constructs
such as cube maps, in which there is more than one
mipmap surface attached to the root surface. This
should be set on all nontop-level surfaces in a
mipmapped cube map so that a call to
GetAttachedSurface can distinguish between top-
level faces and attached mipmap levels. This capability
bit is ignored by CreateSurface.

DDSCAPS2_NOTUSERLOCKABLE DirectX 8.0 and later versions only.

Set on the primary and the back buffers if the flipping

chain is not lockable, or on any render target that is
not lockable. This allows drivers to do behind the
scenes optimization. Note that it is still possible to
lock the surfaces so the driver must handle these
cases, but such locks are infrequent and are not
expected to be fast. The driver can also determine
whether the depth/stencil buffer is lockable by the
presence of this flag.

DDSCAPS2_NPATCHES DirectX 8.0 and later versions only.

Indicates that the vertex buffer data can be used to

render n-patches.

DDSCAPS2_OPAQUE The application will never lock, blit, or update the

surface for the rest of that surface's lifetime. The driver
can compress or reorder the surface without ever
having to decompress it. Surfaces with this flag set
must also have the DDSCAPS_TEXTURE flag in this
structure set. This flag cannot be used with the
DDSCAPS2_HINTDYNAMIC or DDSCAPS2_HINTSTATIC
flags.

DDSCAPS2_POINTS DirectX 8.0 and later versions only.

Indicates that the vertex buffer data can be used to

render points and point sprites.
 Flag Meaning

DDSCAPS2_RTPATCHES DirectX 8.0 and later versions only.

Indicates that the vertex buffer data can be used to

render rt-patches.

DDSCAPS2_STEREOSURFACELEFT This surface is part of a stereo flipping chain. When

this flag is set during a CreateSurface call, a pair of
stereo surfaces are created for each buffer in the
primary flipping chain. You must create a complex
flipping chain (with back buffers). You cannot create a
single set of stereo surfaces. The Flip method requires
back buffers, so at least 4 surfaces must be created.

In addition, when this flag is set in a DDSURFACEDESC

structure as the result of an EnumDisplayModes or
GetDisplayMode call, it indicates support for stereo in
that mode.

DDSCAPS2_TEXTUREMANAGE The client indicates that this texture surface should be

managed by the driver if possible; otherwise it is
managed by Direct3D Immediate Mode. This flag can
be used only for texture surfaces (DDSCAPS_TEXTURE
flag set in the dwCaps member). For more
information, see Automatic Texture Management in
the Direct3D Immediate Mode documentation.

DDSCAPS2_VERTEXBUFFER Marks an explicit vertex buffer, created and controlled

by the application.

DDSCAPS2_VOLUME DirectX 8.0 and later versions only.

This flag is set if the texture has depth in addition to

width and height.

dwCaps3

DirectX 8.0 and DirectX 8.1 versions only.

Specifies the number of samples for a multisampled surface. This field holds one of the
values of the enumerated type D3DMULTISAMPLE_TYPE. If a surface is not
multisampled, dwCaps3 has the value D3DMULTISAMPLE_NONE (0).

DirectX 9.0 and later versions only.

Specifies a set of bits that indicate additional surface capabilities. This member can be a
bitwise OR of the following bits.
 Bits Meaning

Bits in the The first five bits of dwCaps3 indicate the number
DDSCAPS3_MULTISAMPLE_MASK mask of samples for a multiple-sampled surface. The
(0x0000001FL). number of samples can be specified using one of
the values of the enumerated type
D3DMULTISAMPLE_TYPE. If a surface is not
multisampled, this value is
D3DMULTISAMPLE_NONE (0).

Bits in the The next three bits of dwCaps3 indicate the quality
DDSCAPS3_MULTISAMPLE_QUALITY_MASK level of rendering samples in a multiple-sampled
mask (0x000000E0L). surface. The quality level must be a number from 0
to 7 that represents a quality level from 1 to 8
respectively. Note that even if a surface is not
multisampled (specified in the first five bits using
D3DMULTISAMPLE_NONE) it can still have a
greater-than-1 quality level (specified using a
number greater than 0).

DDSCAPS3_RESERVED1 (0x00000100L) Reserved

DDSCAPS3_VIDEO (0x00000200L) Indicates that the render target contains video data.
Note that several render targets can be created with
this flag, and if two or more of these render targets
belong to the same Direct3D context, then the
driver determines that these render targets all
display the same video stream regardless of
whether the render target surfaces are attached to
each other.

DDSCAPS3_LIGHTWEIGHTMIPMAP Indicates whether this surface has lightweight mip

(0x00000400L) levels

DDSCAPS3_AUTOGENMIPMAP Indicates that the mip sublevels for this surface are
(0x00000800L) automatically generated.

DDSCAPS3_DMAP (0x00001000L) Indicates a displacement-map texture that can be

sampled by the displacement-map sampler in the
tessellation unit.

DUMMYUNIONNAMEN

N/A

DUMMYUNIONNAMEN.dwCaps4

The low word is the depth for a volume texture.

DUMMYUNIONNAMEN.dwVolumeDepth
Specifies the volume texture bit-depth.

Remarks
This structure is used by the driver to report the types of surfaces the driver supports. It
is also filled in by an application to specify the type of surface to be created.

Requirements

Header ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDSURFACEDESC structure (ddraw.h)
Article09/15/2022

The DDSURFACEDESC structure contains a description of a surface to be created by the

driver.

Syntax
C++

typedef struct _DDSURFACEDESC {

DWORD dwSize;
DWORD dwFlags;
DWORD dwHeight;
DWORD dwWidth;
#if ...
union {
LONG lPitch;
DWORD dwLinearSize;
} DUMMYUNIONNAMEN;
DWORD dwBackBufferCount;
#else
union {
DWORD dwMipMapCount;
DWORD dwZBufferBitDepth;
DWORD dwRefreshRate;
} DUMMYUNIONNAMEN;
#endif
DWORD dwAlphaBitDepth;
DWORD dwReserved;
LPVOID lpSurface;
DDCOLORKEY ddckCKDestOverlay;
DDCOLORKEY ddckCKDestBlt;
DDCOLORKEY ddckCKSrcOverlay;
DDCOLORKEY ddckCKSrcBlt;
DDPIXELFORMAT ddpfPixelFormat;
DDSCAPS ddsCaps;
} *LPDDSURFACEDESC, DDSURFACEDESC;

Members
dwSize

Specifies the size in bytes of this DDSURFACEDESC structure. This member must be
initialized before the structure is used.
dwFlags

Specifies a set of flags that determine what members of the DDSURFACEDESC structure
contain valid data. This member can be one or more of the following flags:

Flag Meaning

DDSD_ALL All input members contain valid data.

DDSD_ALPHABITDEPTH The dwAlphaBitDepth member is valid.

DDSD_BACKBUFFERCOUNT The dwBackBufferCount member is valid.

DDSD_CAPS The ddsCaps member is valid.

DDSD_CKDESTBLT The ddckCKDestBlt member is valid.

DDSD_CKDESTOVERLAY The ddckCKDestOverlay member is valid.

DDSD_CKSRCBLT The ddckCKSrcBlt member is valid.

DDSD_CKSRCOVERLAY The ddckCKSrcOverlay member is valid.

DDSD_HEIGHT The dwHeight member is valid.

DDSD_LINEARSIZE The dwLinearSize member is valid.

DDSD_MIPMAPCOUNT The dwMipMapCount member is valid.

DDSD_PITCH The lPitch member is valid.

DDSD_PIXELFORMAT The ddpfPixelFormat member is valid.

DDSD_REFRESHRATE The dwRefreshRate member is valid.

DDSD_WIDTH The dwWidth member is valid.

DDSD_ZBUFFERBITDEPTH The dwZBufferBitDepth member is valid.

dwHeight

Specifies the height of surface, in pixels.

dwWidth

Specifies the width of the surface, in pixels.

DUMMYUNIONNAMEN

N/A
DUMMYUNIONNAMEN.lPitch

Specifies the number of bytes between the beginnings of two adjacent scan lines; that
is, the number of bytes to add to the beginning address of one scan line to reach the
beginning address of the next scan line below it. The driver's DdCreateSurface callback
must return this value.

DUMMYUNIONNAMEN.dwLinearSize

Specifies the size in bytes of a formless, late-allocated, optimized surface.

dwBackBufferCount

Specifies the number of back buffers associated with the surface.

DUMMYUNIONNAMEN.dwMipMapCount

Specifies the number of mipmap levels.

DUMMYUNIONNAMEN.dwZBufferBitDepth

Specifies the depth of z-buffer in bits per pixel.

DUMMYUNIONNAMEN.dwRefreshRate

Specifies the refresh rate in hertz of the monitor (used when the display mode is
described).

dwAlphaBitDepth

Specifies the depth of the alpha buffer in bits per pixel.

dwReserved

Reserved, and should be set to zero.

lpSurface

Specifies the address of the associated surface memory.

ddckCKDestOverlay

Specifies the color key for destination overlay use.

ddckCKDestBlt

Specifies the color key for destination blt use.

ddckCKSrcOverlay

Specifies the color key for source overlay use.

ddckCKSrcBlt

Specifies the color key for source blt use.

ddpfPixelFormat

Specifies a DDPIXELFORMAT structure that describes the pixel format of the surface.

ddsCaps

Specifies a DDSCAPS structure that contains the Microsoft DirectDrawMicrosoft surface

capabilities.

Remarks
The relevant members differ for each potential type of surface. This structure is typically
created and initialized by an application.

Requirements

Header ddraw.h

See also
DdCreateSurface
DDPIXELFORMAT
DDSCAPS

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DDSURFACEDESC2 structure (ddraw.h)
Article09/15/2022

The DDSURFACEDESC2 structure contains a description of a surface to be created by the

driver.

Syntax
C++

typedef struct _DDSURFACEDESC2 {

DWORD dwSize;
DWORD dwFlags;
DWORD dwHeight;
DWORD dwWidth;
#if ...
union {
LONG lPitch;
DWORD dwLinearSize;
} DUMMYUNIONNAMEN;
#elif
union {
DWORD dwBackBufferCount;
DWORD dwDepth;
} DUMMYUNIONNAMEN;
#elif
union {
DWORD dwMipMapCount;
DWORD dwRefreshRate;
DWORD dwSrcVBHandle;
} DUMMYUNIONNAMEN;
DWORD dwAlphaBitDepth;
DWORD dwReserved;
LPVOID lpSurface;
#elif
union {
DDCOLORKEY ddckCKDestOverlay;
DWORD dwEmptyFaceColor;
} DUMMYUNIONNAMEN;
DDCOLORKEY ddckCKDestBlt;
DDCOLORKEY ddckCKSrcOverlay;
DDCOLORKEY ddckCKSrcBlt;
#else
union {
DDPIXELFORMAT ddpfPixelFormat;
DWORD dwFVF;
} DUMMYUNIONNAMEN;
#endif
DDSCAPS2 ddsCaps;
 DWORD dwTextureStage;
} *LPDDSURFACEDESC2, DDSURFACEDESC2;

Members
dwSize

Specifies the size in bytes of this DDSURFACEDESC2 structure. This member must be
initialized before the structure is used.

dwFlags

Specifies a set of flags that determine what members of the DDSURFACEDESC2 structure
contain valid data. This member can be one or more of the following flags:

Flag Meaning

DDSD_ALL All input members contain valid data.

DDSD_ALPHABITDEPTH The dwAlphaBitDepth member is valid.

DDSD_BACKBUFFERCOUNT The dwBackBufferCount member is valid.

DDSD_CAPS The ddsCaps member is valid.

DDSD_CKDESTBLT The ddckCKDestBlt member is valid.

DDSD_CKDESTOVERLAY The ddckCKDestOverlay member is valid.

DDSD_CKSRCBLT The ddckCKSrcBlt member is valid.

DDSD_CKSRCOVERLAY The ddckCKSrcOverlay member is valid.

DDSD_FVF The dwFVF member is valid.

DDSD_HEIGHT The dwHeight member is valid.

DDSD_LINEARSIZE The dwLinearSize member is valid.

DDSD_LPSURFACE The lpSurface member is valid.

DDSD_MIPMAPCOUNT The dwMipMapCount member is valid.

DDSD_PITCH The lPitch member is valid.

DDSD_PIXELFORMAT The ddpfPixelFormat member is valid.

DDSD_REFRESHRATE The dwRefreshRate member is valid.

DDSD_SRCVBHANDLE The dwSrcVBHandle member is valid.

 Flag Meaning

DDSD_TEXTURESTAGE The dwTextureStage member is valid.

DDSD_WIDTH The dwWidth member is valid.

DDSD_ZBUFFERBITDEPTH This flag is not used in DDSURFACEDESC2. It is only used in

DDSURFACEDESC.

dwHeight

Specifies the height of surface in pixels.

dwWidth

Specifies the width of the surface in pixels.

DUMMYUNIONNAMEN

N/A

DUMMYUNIONNAMEN.lPitch

Specifies the number of bytes between the beginnings of two adjacent scan lines; that
is, the number of bytes to add to the beginning address of one scan line to reach the
beginning address of the next scan line below it. The driver's DdCreateSurface callback
must return this value.

DUMMYUNIONNAMEN.dwLinearSize

Specifies the size in bytes of a formless, late-allocated, optimized surface.

DUMMYUNIONNAMEN.dwBackBufferCount

Specifies the number of back buffers associated with the surface.

DUMMYUNIONNAMEN.dwDepth

The bit-depth if this is a volume texture.

DUMMYUNIONNAMEN.dwMipMapCount

Specifies the number of mipmap levels.

DUMMYUNIONNAMEN.dwRefreshRate

Specifies the refresh rate in hertz of the monitor (used when the display mode is
described).
DUMMYUNIONNAMEN.dwSrcVBHandle

Specifies the source used in IDirect3DVertexBuffer7::Optimize (described in the

Microsoft Direct3D SDK documentation).

dwAlphaBitDepth

Specifies the depth of the alpha buffer in bits per pixel.

dwReserved

Reserved, and should be set to zero.

lpSurface

Specifies the address of the associated surface memory.

DUMMYUNIONNAMEN.ddckCKDestOverlay

Specifies the color key for destination overlay use.

DUMMYUNIONNAMEN.dwEmptyFaceColor

Specifies the physical color for empty cube map faces.

ddckCKDestBlt

Specifies the color key for destination blit use.

ddckCKSrcOverlay

Specifies the color key for source overlay use.

ddckCKSrcBlt

Specifies the color key for source blit use.

DUMMYUNIONNAMEN.ddpfPixelFormat

Specifies a DDPIXELFORMAT structure that describes the pixel format of the surface.

DUMMYUNIONNAMEN.dwFVF

Specifies the Flexible Vertex Format (D3DFVF) for the vertex buffers.

ddsCaps

Specifies a DDSCAPS structure that contains the DirectDraw surface capabilities.

dwTextureStage

Specifies the stage in the multitexture cascade. For more information, see Texture
Stages.

Remarks
The relevant members differ for each potential type of surface. This structure is typically
created and initialized by an application.

Requirements

Header ddraw.h

See also
DdCreateSurface
DDPIXELFORMAT
DDSCAPS

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

DirectDraw Return Codes
Article • 04/27/2021

Errors are represented by negative values and cannot be combined. This table lists the
values that can be returned by all methods of the DirectDraw Interfaces and DirectDraw
Functions. For a list of the error codes that each method or function can return, see the
method or function description.

DD_OK

The request completed successfully.

DDERR_ALREADYINITIALIZED

The object has already been initialized.

DDERR_BLTFASTCANTCLIP

A DirectDrawClipper object is attached to a source surface that has passed into a call to
the IDirectDrawSurface7::BltFast method.

DDERR_CANNOTATTACHSURFACE

A surface cannot be attached to another requested surface.

DDERR_CANNOTDETACHSURFACE

A surface cannot be detached from another requested surface.

DDERR_CANTCREATEDC

Windows cannot create any more device contexts (DCs), or a DC has requested a
palette-indexed surface when the surface had no palette and the display mode was not
palette-indexed (in this case, DirectDraw cannot select a proper palette into the DC).

DDERR_CANTDUPLICATE

Primary and 3-D surfaces, or surfaces that are implicitly created, cannot be duplicated.

DDERR_CANTLOCKSURFACE

Access to this surface is refused because an attempt was made to lock the primary
surface without Display Control Interface (DCI) support.

DDERR_CANTPAGELOCK
An attempt to page-lock a surface failed. Page lock does not work on a display-memory
surface or an emulated primary surface.

DDERR_CANTPAGEUNLOCK

An attempt to page-unlock a surface failed. Page unlock does not work on a display-
memory surface or an emulated primary surface.

DDERR_CLIPPERISUSINGHWND

An attempt was made to set a clip list for a DirectDrawClipper object that is already
monitoring a window handle.

DDERR_COLORKEYNOTSET

No source color key is specified for this operation.

DDERR_CURRENTLYNOTAVAIL

No support is currently available.

DDERR_DDSCAPSCOMPLEXREQUIRED

New for DirectX 7.0. The surface requires the DDSCAPS_COMPLEX flag.

DDERR_DCALREADYCREATED

A device context (DC) has already been returned for this surface. Only one DC can be
retrieved for each surface.

>DDERR_DEVICEDOESNTOWNSURFACE

Surfaces created by one DirectDraw device cannot be used directly by another

DirectDraw device.

>DDERR_DIRECTDRAWALREADYCREATED

A DirectDraw object representing this driver has already been created for this process.

DDERR_EXCEPTION

An exception was encountered while performing the requested operation.

DDERR_EXCLUSIVEMODEALREADYSET

An attempt was made to set the cooperative level when it was already set to exclusive.

DDERR_EXPIRED
The data has expired and is therefore no longer valid.

DDERR_GENERIC

There is an undefined error condition.

DDERR_HEIGHTALIGN

The height of the provided rectangle is not a multiple of the required alignment.

DDERR_HWNDALREADYSET

The DirectDraw cooperative-level window handle has already been set. It cannot be
reset while the process has surfaces or palettes created.

DDERR_HWNDSUBCLASSED

DirectDraw is prevented from restoring state because the DirectDraw cooperative-level

window handle has been subclassed.

DDERR_IMPLICITLYCREATED

The surface cannot be restored because it is an implicitly created surface.

DDERR_INCOMPATIBLEPRIMARY

The primary surface creation request does not match the existing primary surface.

DDERR_INVALIDCAPS

One or more of the capability bits passed to the callback function are incorrect.

DDERR_INVALIDCLIPLIST

DirectDraw does not support the provided clip list.

DDERR_INVALIDDIRECTDRAWGUID

The globally unique identifier (GUID) passed to the DirectDrawCreate function is not a
valid DirectDraw driver identifier.

DDERR_INVALIDMODE

DirectDraw does not support the requested mode.

DDERR_INVALIDOBJECT

DirectDraw received a pointer that was an invalid DirectDraw object.

DDERR_INVALIDPARAMS

One or more of the parameters passed to the method are incorrect.

DDERR_INVALIDPIXELFORMAT

The pixel format was invalid as specified.

DDERR_INVALIDPOSITION

The position of the overlay on the destination is no longer valid.

DDERR_INVALIDRECT

The provided rectangle was invalid.

DDERR_INVALIDSTREAM

The specified stream contains invalid data.

DDERR_INVALIDSURFACETYPE

The surface was of the wrong type.

DDERR_LOCKEDSURFACES

One or more surfaces are locked, causing the failure of the requested operation.

DDERR_MOREDATA

There is more data available than the specified buffer size can hold.

DDERR_NEWMODE

New for DirectX 7.0. When IDirectDraw7::StartModeTest is called with the

DDSMT_ISTESTREQUIRED flag, it might return this value to denote that some or all of
the resolutions can and should be tested. IDirectDraw7::EvaluateMode returns this
value to indicate that the test has switched to a new display mode.

DDERR_NO3D

No 3-D hardware or emulation is present.

DDERR_NOALPHAHW

No alpha-acceleration hardware is present or available, causing the failure of the

requested operation.

DDERR_NOBLTHW
No bit block transferring hardware is present.

DDERR_NOCLIPLIST

No clip list is available.

DDERR_NOCLIPPERATTACHED

No DirectDrawClipper object is attached to the surface object.

DDERR_NOCOLORCONVHW

No color-conversion hardware is present or available.

DDERR_NOCOLORKEY

The surface does not currently have a color key.

DDERR_NOCOLORKEYHW

There is no hardware support for the destination color key.

DDERR_NOCOOPERATIVELEVELSET

A create function was called without the IDirectDraw7::SetCooperativeLevel method.

DDERR_NODC

No device context (DC) has ever been created for this surface.

DDERR_NODDROPSHW

No DirectDraw raster-operation (ROP) hardware is available.

DDERR_NODIRECTDRAWHW

Hardware-only DirectDraw object creation is not possible; the driver does not support
any hardware.

DDERR_NODIRECTDRAWSUPPORT

DirectDraw support is not possible with the current display driver.

DDERR_NODRIVERSUPPORT

New for DirectX 7.0. Testing cannot proceed because the display adapter driver does not
enumerate refresh rates.

DDERR_NOEMULATION
Software emulation is not available.

DDERR_NOEXCLUSIVEMODE

The operation requires the application to have exclusive mode, but the application does
not have exclusive mode.

DDERR_NOFLIPHW

Flipping visible surfaces is not supported.

DDERR_NOFOCUSWINDOW

An attempt was made to create or set a device window without first setting the focus
window.

DDERR_NOGDI

No GDI is present.

DDERR_NOHWND

Clipper notification requires a window handle, or no window handle has been previously
set as the cooperative level window handle.

DDERR_NOMIPMAPHW

No mipmap-capable texture mapping hardware is present or available.

DDERR_NOMIRRORHW

No mirroring hardware is present or available.

DDERR_NOMONITORINFORMATION

New for DirectX 7.0. Testing cannot proceed because the monitor has no associated
EDID data.

DDERR_NONONLOCALVIDMEM

An attempt was made to allocate nonlocal video memory from a device that does not
support nonlocal video memory.

DDERR_NOOPTIMIZEHW

The device does not support optimized surfaces.

DDERR_NOOVERLAYDEST
The IDirectDrawSurface7::GetOverlayPosition method is called on an overlay that the
IDirectDrawSurface7::UpdateOverlay method has not been called on to establish as a
destination.

DDERR_NOOVERLAYHW

No overlay hardware is present or available.

DDERR_NOPALETTEATTACHED

No palette object is attached to this surface.

DDERR_NOPALETTEHW

There is no hardware support for 16- or 256-color palettes.

DDERR_NORASTEROPHW

No appropriate raster-operation hardware is present or available.

DDERR_NOROTATIONHW

No rotation hardware is present or available.

DDERR_NOSTEREOHARDWARE

There is no stereo hardware present or available.

DDERR_NOSTRETCHHW

There is no hardware support for stretching.

DDERR_NOSURFACELEFT

There is no hardware present that supports stereo surfaces.

DDERR_NOT4BITCOLOR

The DirectDrawSurface object is not using a 4-bit color palette, and the requested
operation requires a 4-bit color palette.

DDERR_NOT4BITCOLORINDEX

The DirectDrawSurface object is not using a 4-bit color index palette, and the requested
operation requires a 4-bit color index palette.

DDERR_NOT8BITCOLOR
The DirectDrawSurface object is not using an 8-bit color palette, and the requested
operation requires an 8-bit color palette.

DDERR_NOTAOVERLAYSURFACE

An overlay component is called for a nonoverlay surface.

DDERR_NOTEXTUREHW

The operation cannot be carried out because no texture-mapping hardware is present

or available.

DDERR_NOTFLIPPABLE

An attempt was made to flip a surface that cannot be flipped.

DDERR_NOTFOUND

The requested item was not found.

DDERR_NOTINITIALIZED

An attempt was made to call an interface method of a DirectDraw object created by

CoCreateInstance before the object was initialized.

DDERR_NOTLOADED

The surface is an optimized surface, but it has not yet been allocated any memory.

DDERR_NOTLOCKED

An attempt was made to unlock a surface that was not locked.

DDERR_NOTPAGELOCKED

An attempt was made to page-unlock a surface with no outstanding page locks.

DDERR_NOTPALETTIZED

The surface being used is not a palette-based surface.

DDERR_NOVSYNCHW

There is no hardware support for vertical blank synchronized operations.

DDERR_NOZBUFFERHW

The operation to create a z-buffer in display memory or to perform a bit block transfer
(bitblt), using a z-buffer cannot be carried out because there is no hardware support for
z-buffers.

DDERR_NOZOVERLAYHW

The overlay surfaces cannot be z-layered, based on the z-order because the hardware
does not support z-ordering of overlays.

DDERR_OUTOFCAPS

The hardware needed for the requested operation has already been allocated.

DDERR_OUTOFMEMORY

DirectDraw does not have enough memory to perform the operation.

DDERR_OUTOFVIDEOMEMORY

DirectDraw does not have enough display memory to perform the operation.

DDERR_OVERLAPPINGRECTS

The source and destination rectangles are on the same surface and overlap each other.

DDERR_OVERLAYCANTCLIP

The hardware does not support clipped overlays.

DDERR_OVERLAYCOLORKEYONLYONEACTIVE

An attempt was made to have more than one color key active on an overlay.

DDERR_OVERLAYNOTVISIBLE

The IDirectDrawSurface7::GetOverlayPosition method was called on a hidden overlay.

DDERR_PALETTEBUSY

Access to this palette is refused because the palette is locked by another thread.

DDERR_PRIMARYSURFACEALREADYEXISTS

This process has already created a primary surface.

DDERR_REGIONTOOSMALL

The region passed to the IDirectDrawClipper::GetClipList method is too small.

DDERR_SURFACEALREADYATTACHED
An attempt was made to attach a surface to another surface to which it is already
attached.

DDERR_SURFACEALREADYDEPENDENT

An attempt was made to make a surface a dependency of another surface on which it is

already dependent.

DDERR_SURFACEBUSY

Access to the surface is refused because the surface is locked by another thread.

DDERR_SURFACEISOBSCURED

Access to the surface is refused because the surface is obscured.

DDERR_SURFACELOST

Access to the surface is refused because the surface memory is gone. Call the
IDirectDrawSurface7::Restore method on this surface to restore the memory associated
with it.

DDERR_SURFACENOTATTACHED

The requested surface is not attached.

DDERR_TESTFINISHED

New for DirectX 7.0. When returned by the IDirectDraw7::StartModeTest method, this
value means that no test could be initiated because all the resolutions chosen for testing
already have refresh rate information in the registry. When returned by
IDirectDraw7::EvaluateMode, the value means that DirectDraw has completed a refresh
rate test.

DDERR_TOOBIGHEIGHT

The height requested by DirectDraw is too large.

DDERR_TOOBIGSIZE

The size requested by DirectDraw is too large. However, the individual height and width
are valid sizes.

DDERR_TOOBIGWIDTH

The width requested by DirectDraw is too large.

DDERR_UNSUPPORTED
The operation is not supported.

DDERR_UNSUPPORTEDFORMAT

The pixel format requested is not supported by DirectDraw.

DDERR_UNSUPPORTEDMASK

The bitmask in the pixel format requested is not supported by DirectDraw.

DDERR_UNSUPPORTEDMODE

The display is currently in an unsupported mode.

DDERR_VERTICALBLANKINPROGRESS

A vertical blank is in progress.

DDERR_VIDEONOTACTIVE

The video port is not active.

DDERR_WASSTILLDRAWING

The previous bitblt operation that is transferring information to or from this surface is
incomplete.

DDERR_WRONGMODE

This surface cannot be restored because it was created in a different mode.

DDERR_XALIGN

The provided rectangle was not horizontally aligned on a required boundary.

Requirements
Requirement Value

Header Ddraw.h

Feedback
Was this page helpful? ﾂ Yes ﾄ No
Get help at Microsoft Q&A