A Library for Simplified DirectX Programming

Table of Contents

1. Library Overview.......................................................................................................................................................... 5

1.1. General Considerations........................................................................................................................................ 5

1.2. Creating the DXMgr Object................................................................................................................................ 5

HRESULT DXMgrCreate( REFIID riid, LPVOID *ppDXMgr );....................................................................... 5

1.3. Return Values........................................................................................................................................................ 6

2. Interface Descriptions................................................................................................................................................. 7

2.1. IDXMgr.................................................................................................................................................................. 7

HRESULT QueryInterface( REFIID, LPVOID *);................................................................................................ 7

ULONG AddRef();................................................................................................................................................... 7

ULONG Release();................................................................................................................................................... 7

HRESULT Clear(UINT cNumRects, PRECT pRects, UINT D3DClearFlags, D3DCOLOR ClearColor, D3DVALUE dvZClearValue, UINT StencilClearValue);.................................................................................................................................................. 7

HRESULT CreateEnumDirectDraws( IEnumDirectDraws **pEnum, UINT Flags );..................................... 8

HRESULT CreateEnumDisplayModes( IEnumDisplayModes **pEnum, UINT Flags );............................ 8

HRESULT CreateEnumTextureFormats( IEnumPixelFormats **pEnum, UINT Flags );............................... 9

HRESULT CreateEnumZBufferFormats( IEnumPixelFormats **pEnum, IID *piidDeviceType, UINT Flags ); 9

HRESULT Disable( UINT Flags );...................................................................................................................... 10

HRESULT Enable( PDXMGRENABLE pEnable );........................................................................................... 10

HRESULT FlipToGDISurface();.......................................................................................................................... 12

HRESULT GetBackBuffer(LPDIRECTDRAWSURFACE4 *lplpBackBuffer);.............................................. 13

HRESULT GetDeviceCaps( LPD3DDEVICEDESC pDesc );........................................................................... 13

HRESULT GetDirect3D(LPDIRECT3D3 *lplpD3D);........................................................................................ 13

HRESULT GetDirect3DDevice(LPDIRECT3DDEVICE3 *lplpD3DDevice);................................................. 13

HRESULT GetDirectDraw(LPDIRECTDRAW4 *lplpDD);.............................................................................. 14

HRESULT GetEnableInfo(PDXMGRENABLEINFO pInfo);........................................................................... 14

HRESULT GetDeviceWindow(HWND *phwnd);............................................................................................ 14

HRESULT GetFocusWindow(HWND *phwnd);............................................................................................. 14

HRESULT GetPrimary(LPDIRECTDRAWSURFACE4 *lplpPrimary);.......................................................... 15

HRESULT GetZBuffer(LPDIRECTDRAWSURFACE4 *lplpZBuffer);.......................................................... 15

HRESULT Initialize(LPGUID pDDGuid, HWND hwndFocus, UINT Flags );.............................................. 15

HRESULT RestoreSurfaces( );............................................................................................................................ 15

HRESULT Update(UINT Flags, PRECT pRect);............................................................................................... 16

2.2. IEnumDirectDraws.............................................................................................................................................. 16

HRESULT Next( UINT cNumDDs, PDXMGROBJECTDESC pDDs, UINT *pNumDDs );......................... 16

HRESULT Skip( UINT cNumDDs );................................................................................................................... 17

HRESULT Reset();................................................................................................................................................ 17

HRESULT Clone( IEnumDirectDraws **ppEnum );........................................................................................ 17

2.3. IEnumPixelFormats.............................................................................................................................................. 17

HRESULT Next( UINT cNumPFss, LPDDPIXELFORMAT, UINT *pNumPFs );........................................ 17

HRESULT Skip( UINT cNumPFs );..................................................................................................................... 17

HRESULT Reset();................................................................................................................................................ 18

HRESULT Clone( IEnumPixelFormats **ppEnum );........................................................................................ 18

2.4. IEnumDisplayModes.......................................................................................................................................... 18

HRESULT Next( UINT cNumModes, PDDMODEDESC pMode, UINT *pNumModes );......................... 18

HRESULT Skip( UINT cNumModes );............................................................................................................... 18

HRESULT Reset();................................................................................................................................................ 18

HRESULT Clone( IEnumDisplayModes **ppEnum );.................................................................................... 18

3. Structures.................................................................................................................................................................... 18

3.1. DXMGROBJECTDESC....................................................................................................................................... 18

3.2. DXMGRMODEDESC......................................................................................................................................... 19

3.3. DXMGRENABLE................................................................................................................................................ 19

3.4. DXMGRENABLEINFO...................................................................................................................................... 21

4. Software Development Kit materials....................................................................................................................... 21

5. Sample Code................................................................................................................................................................ 22

5.1. TrivWin – trivial windowed application.......................................................................................................... 23

5.2. TrivFS – trivial fullscreen application.............................................................................................................. 23

5.3. TrivBoth – trivial windowed and fullscreen application............................................................................... 23

5.4. MultiFS – multimon-aware fullscreen application.......................................................................................... 23

6. Support........................................................................................................................................................................ 23

6.1. Contact Info......................................................................................................................................................... 23

6.2. Frequently Asked Questions............................................................................................................................ 24

6.3. Planned Enhancements...................................................................................................................................... 25

1. Library Overview

This library provides services to simplify some common tasks in DirectDraw and Direct3D programming, including the following:

- Enumeration of DirectDraw devices, screen resolutions, and pixel formats

- Initialization of DirectDraw and Direct3D

- Screen updates

DXMgr is intended to be flexible enough to simplify programming without imposing undue policy on the application.

NOTE: DXMgr is not thread-safe. Applications that call DXMgr from multiple threads must perform their own synchronization to ensure that only one thread accesses DXMgr at a time. (This restriction is not as onerous as it may appear, since DirectDraw and Direct3D only allow one thread to access them at a time.)

DXMgr requires the DirectX 6.0 SDK for Windows 95/98, and applications built with DXMgr require DirectX 6.0 to be installed on the end user’s machine. The DirectX 6.0 SDK can be downloaded or ordered over the Internet at http://www.microsoft.com/directx.

DirectX 6.0 is also built into post-Beta 1 versions of Windows NT 5.0, and the DXMgr libraries have been tested on prerelease versions of this operating system, including Windows NT 5.0 Beta 2.

1.1. General Considerations

DXMgr is an object that exists in three states: uninitialized, initialized, and enabled. When DXMgr is first created, it is uninitialized and can only be used to enumerate the DirectDraw devices available in a system.

Once a DirectDraw device has been selected, DXMgr should be initialized. This will create an instance of the DirectDraw object and allow the application to enumerate the available display modes, Z buffer formats, and so on. These enumerators can be used to decide how to enable the DXMgr object.

When IDXMgr::Enable is called, DXMgr allocates the various DirectDraw and Direct3D objects needed for windowed or full-screen rendering. In windowed mode, it allocates a backbuffer to render from, creates an instance of the primary, and attaches a clipper (using the HWND given) to the primary. If 3D rendering is requested, it also creates an instance of Direct3D; creates a Z buffer (if requested) and attaches it to the back buffer; creates a device that can render to the back buffer; and initializes the device to a set of ‘reasonable defaults.’

In fullscreen mode, DXMgr sets fullscreen exclusive mode; sets the display mode; and creates a primary flipping chain instead of creating a back buffer and separate instance of the primary. Also, in fullscreen mode, DXMgr does not create a clipper. The fullscreen initialization done by DXMgr is identical to windowed mode in other respects.

DXMgr prefers to render using hardware accelerators, so it first attempts to create the back and Z buffers in video memory, provided the Direct3D device that will be rendering to them will be hardware-accelerated. If these operations fail, it will fall back to software rendering. It will also fall back to software rendering under other circumstances, if there is insufficient video memory for the back and Z buffers or if the primary is in a mode that is not supported by the 3D accelerator (usually 8-bit palettized).

1.2. Creating the DXMgr Object

HRESULT DXMgrCreate( REFIID riid, LPVOID *ppDXMgr );

Creates the DXMgr object and returns the resulting IDXMgr interface. Immediately after creation, the DirectDraw objects available in the system can be enumerated by calling IDXMgr:: CreateEnumDirectDraws. If you want to do anything else with the DXMgr object, however, you must call IDXMgr::Initialize to select a DirectDraw object for the DXMgr to deal with.

Parameters

REFIID riid;

This must be set to IID_IDXMgr.

LPVOID *ppDXMgr;

This parameter will receive a pointer to the requested interface.

Error Returns

E_OUTOFMEMORY

E_INVALIDARG

1.3. Return Values

All functions in this library return S_OK if they complete successfully.

Errors returned by IDXMgr usually will be errors from DirectDraw or Direct3D. These errors are easy to differentiate from errors generated by IDXMgr itself because the facility code is different (IDXMgr uses the FACILITY_ITF (interface-specific) facility code of 0x4, while DirectDraw and Direct3D use a facility code of 0x876).

The debug version of DXMgr will print a diagnostic string using OutputDebugString if it returns an error. Otherwise, it relies on the underlying DirectX API to report the error that it propagates back to the caller.

The errors that DXMgr can return on its own are as follows.

E_OUTOFMEMORY

Returned if there was insufficient memory to perform the operation.

E_INVALIDARG

Returned in an invalid argument (e.g. an invalid flag) was passed to a function.

E_POINTER

Returned if an invalid pointer was passed to a function. This error will only be returned by the debug version of the library.

DXMGRERR_NODIRECTX6

Returned by DXMgrCreate if the library was unable to load the DirectDraw DLL, or if the DirectDraw available on the system is not DirectX 6.0 or later.

DXMGRERR_NOTINITIALIZED

Returned by functions that require DXMgr to be initialized.

DXMGRERR_NOTENABLED

Returned by functions that require DXMgr to be enabled.

DXMGRERR_ALREADYINITIALIZED

Returned by Initialize if the object has already been initialized.

DXMGRERR_ALREADYENABLED

Returned by Enable if the object has already been enabled. The object can be disabled by calling Disable.

DXMGRERR_INVALIDFOCUSWINDOW

Returned by Initialize if the focus window is different from one that has previously been specified.

DXMGRERR_WINDOWEDREQUIRED

Returned if an operation that is only valid windowed has been requested in fullscreen mode.

DXMGRERR_FULLSCREENREQUIRED

Returned if an operation that is only valid in fullscreen has been requested in windowed mode.

DXMGRERR_3DREQUIRED

Returned by functions that require the DXMgr to have been enabled with 3D, such as GetDirect3DDevice.

DXMGRERR_BADPIXELFORMAT

Returned by IDXMgr::Clear if the DXMgr is not enabled for 3D and the back buffer’s pixel format is palettized.

2. Interface Descriptions

2.1. IDXMgr

HRESULT QueryInterface( REFIID, LPVOID *);

IDXMgr can be QI’d for IUnknown and IDXMgr.

ULONG AddRef();

Increments the DXMgr object’s refcnt.

ULONG Release();

Decrements the DXMgr object’s refcnt. If the refcnt goes to 0, all resources that the DXMgr has obtained are released.

IMPORTANT NOTE

The client application should Release all objects that it obtained from the DXMgr before calling Release.

HRESULT Clear(UINT cNumRects, PRECT pRects, UINT D3DClearFlags, D3DCOLOR ClearColor, D3DVALUE dvZClearValue, UINT StencilClearValue);

This convenience function reduces the need for clients to keep track of the back buffer and viewport interfaces by wrapping IDirectDrawSurface::Blt and IDirect3DViewport3::Clear2.

If the DXMgr was enabled for 3D, this function will call IDirect3DViewport3::Clear2 with the parameters specified.

If an empty array is passed to this function (pRects equal to NULL and cNumRects equal to 0), DXMgr will clear the entire back buffer.

This function will also work if DXMgr was not enabled for 3D. In that case, the D3DClearFlags parameter must be set to D3DCLEAR_TARGET, and DXMgr will use DirectDraw color fill blts to clear the specified rectangles to the clear color. The function will fail if the back buffer is palettized.

Parameters

cNumRects

Number of rectangles to clear. Set this parameter to 0 if you want the entire buffer to be cleared.

pRects

Pointer to a list of subrectangles to clear. Set this parameter to NULL if you want the entire buffer to be cleared.

D3DClearFlags

The same flags as may be specified to IDirect3DViewport3::Clear2.

D3DCLEAR_TARGET specifies that the render target should be cleared.

D3DCLEAR_ZBUFFER specifies that the Z buffer should be cleared.

D3DCLEAR_STENCIL specifies that the stencil planes in the Z buffer should be cleared.

ClearColor

Value to clear the back buffer to. This parameter is ignored if the D3DCLEAR_TARGET flag is not specified.

dvZClearValue

Value to clear the Z buffer to. 0.0f is the minimum Z value and 1.0f is the maximum value. This parameter is ignored if the D3DCLEAR_ZBUFFER flag is not specified.

StencilClearValue

Value to clear the stencil planes, if any. This parameter is ignored if the Z buffer does not contain stencil planes or the D3DCLEAR_STENCIL flag is not specified.

Return Values

E_INVALIDARG

DXMGRERR_NOTENABLED

DXMGRERR_3DREQUIRED

DXMGRERR_BADPIXELFORMAT

HRESULT CreateEnumDirectDraws( IEnumDirectDraws **pEnum, UINT Flags );

Creates an object that can enumerate the DirectDraw objects available to this DXMgr object. See the description of IEnumDirectDraws later in this document for more details.

Parameters

UINT Flags

One or more flags should be specified to tell which types of display device should be included in the enumeration. These flags mirror the flags parameter to DirectDrawEnumerateEx, a DirectDraw function that first shipped in Windows 98.

DXMGREDD_ATTACHEDSECONDARYDEVICES

Enumerate GDI display devices that are part of the desktop.

DXMGREDD_DETACHEDSECONDARYDEVICES

Enumerate GDI display devices that are not part of the desktop.

DXMGREDD_NONDISPLAYDEVICES

Enumerate non-GDI display devices, such as the 3Dfx Voodoo accelerator.

Return Values

Return Values

E_POINTER

E_INVALIDARG

DXMGRERR_NOTINITIALIZED

DXMGRERR_NOTENABLED

DXMGRERR_3DREQUIRED

HRESULT Disable( UINT Flags );

This routine causes the IDXMgr object to release all of the objects that it created during a preceding Enable call and restores it to the initialized state. If it was in full screen mode, it also restores the display mode.

IMPORTANT NOTE

The client application should Release all objects that it obtained from the DXMgr before calling Disable. Having outstanding references to objects such as the DirectDraw object when IDXMgr::Disable is called will have unpredictable results.

Parameters

UINT Flags

No flags have been defined yet. This parameter should be set to 0.

Return Values

E_INVALIDARG

DXMGRERR_NOTENABLED

HRESULT Enable( PDXMGRENABLE pEnable );

Enables the DXMgr object for drawing. For full-screen mode, this function selects and switches to a display mode and creates a primary flipping chain; in windowed mode, it creates a back buffer and an instance of the primary, creates a clipper and attaches it to the primary. If DXMGRENABLE_3D is set, DXMgr will also create and attach a Z buffer to the back buffer; create a Direct3D device and attach it to the back buffer; and create a viewport and initialize it with a 90-degree field of view.

The objects needed by the application to draw to the back buffer can be queried from the DXMgr object by calling GetDeviceWindow, GetFocusWindow, GetDirectDraw, GetDirect3D, GetPrimary, GetBackBuffer, GetZBuffer, or GetDirect3DDevice.

The exact sequence of operations performed by Enable is as follows.

1) Create the primary, back buffer and Z buffer. DXMgr will select the memory type based on the Direct3D device type it is attempting to create (video memory for HAL devices and system memory for software devices). If 3D is not selected, or if a software Direct3D device type was requested, DXMgr will put the back buffer in system memory by default. This behavior can be overridden with the DXMGRENABLE_FORCEVIDEOMEMORY flag.

For fullscreen (DXMGRENABLE_FULLSCREEN set):

a) If hwndDevice is non-NULL, call SetCooperativeLevel with DDSCL_SETFOCUSWINDOW and the focus window that was passed to Initialize, then call SetCooperativeLevel again with uDDSCLFlags | DDSCL_FULLSCREEN | DDSCL_EXCLUSIVE | DDSCL_SETDEVICEWINDOW. If hwndDevice is NULL, call SetCooperativeLevel once with uDDSCLFlags | DDSCL_FULLSCREEN | DDSCL_EXCLUSIVE | DDSCL_SETFOCUSWINDOW | DDSCL_CREATEDEVICEWINDOW with the focus window that was passed to Initialize.

uDDSCLFlags is a member of the Enable structure used to pass application-specified flags such as DDSCL_MULTITHREADED and DDSCL_FPUSETUP to SetCooperativeLevel.

b) Set the display mode to 640x480x16. If DXMGRENABLE_DISPLAYMODE is set, the DisplayMode member of the Enable structure will be used instead.

c) Create a double-buffered primary flipping chain. If DXMGRENABLE_ BACKBUFFERCOUNT is set, the cBackBuffers member of the Enable structure will be used instead. This CreateSurface call returns the interface pointer to the primary surface.

Notes: DDSCAPS_3DDEVICE will be set on this surface if DXMGRENABLE_3D is set. DDSCAPS_VIDEOMEMORY will be set if 3D is enabled and a HAL device is requested. Otherwise, DDSCAPS_SYSTEMMEMORY is set on the surface.

d) Call GetAttachedSurface to obtain a pointer to the back buffer.

e) If DXMGRENABLE_3D and DXMGRENABLE_ZBUFFER are set, a Z buffer is created and attached to the back buffer. Unless DXMGRENABLE_DDPFZBUFFER is set, a 16-bit Z buffer is created; otherwise, the pixel format in the ddpfZBuffer member of the Enable structure is used.

For windowed mode (DXMGRENABLE_FULLSCREEN not set):

a) Call SetCooperativeLevel with DDSCL_NORMAL | uDDSCLFlags (see 1a above for a description of this member of the DXMGRENABLE structure).

b) Create an instance of the primary surface.

c) Create a clipper, call SetHWND on it with the hwndDevice member of the Enable structure, and set it on the primary by calling IDirectDrawSurface4::SetClipper.

d) Create a back buffer that is the same size as the client area of the hwndDevice member of the Enable structure and the same pixel format as the primary. DDSCAPS_3DDEVICE will be set on this surface if DXMGRENABLE_3D is set. DDSCAPS_VIDEOMEMORY will be set if 3D is enabled and a HAL device is requested. Otherwise, DDSCAPS_SYSTEMMEMORY is set on the surface.

2) If any of the above operations failed, the sequence will be reattempted with the RGB device type. This causes the back buffer and Z buffer to be allocated in system memory rather than video memory, so if a lack of video memory caused the failure, the second attempt may succeed. To override this behavior, set DXMGRENABLE_DEVICETYPE and set the iidDeviceType member of the Enable structure to the desired device type.

NOTE: The following steps are taken only if DXMGRENABLE_3D is set.

3) A Direct3D device is created. If DXMGRENABLE_DEVICETYPE is set, DXMgr attempts to set up the back buffer and Z buffer to accommodate that device type. Otherwise, it will attempt to create a HAL device and fall back to software.

4) A viewport is created, added to the device, and set current to the device. The viewport is initialized with a D3DVIEWPORT2 structure, as follows.

dwX = 0;

dwY = 0;

dwWidth = width; // width and height of the back buffer

dwHeight = height;

dvClipX = -1.0f;

dvClipY = height/width;

dvClipWidth = 2.0f;

dvClipHeight = 2.0f * width/height;

dvMinZ = 0.0f;

dvMaxZ = 1.0f;

To set the viewport to other than these defaults, the viewport interface can be obtained by calling IDXMgr::GetDirect3DDevice and calling GetCurrentViewport off the resulting device interface.

5) The projection matrix in the device is initialized as follows:

where

The near and far Z used to compute Q are the fNear and fFar members of the Enable structure. This projection transform is developed by Jim Blinn in pages 179-190 of Jim Blinn’s Corner: A Trip Down the Graphics Pipeliner (Morgan Kaufmann, 1996). The projection matrix set by DXMgr is hard-coded to a field of view (fov) of 90 degrees.

To set the projection matrix to something other than the default, get the Direct3D device by calling IDXMgr::GetDirect3DDevice and call IDirect3DDevice3::SetTransform with D3DTRANSFORMSTATE_PROJECTION and the new matrix.

Parameters

PDXMGRENABLE pEnable

Pointer to the Enable structure that describes how to set up DirectDraw and Direct3D for drawing.

Return Values

E_INVALIDARG

E_POINTER

DXMGRERR_NOTINITIALIZED

DXMGRERR_ALREADYENABLED

HRESULT FlipToGDISurface();

Ensures that the GDI surface is the primary. This function is a wrapper for the function of the same name in IDirectDraw4. It is provided as a convenience so fullscreen exclusive applications don’t have to obtain a DirectDraw interface pointer just to call this function.

Parameters

None.

Return Values

DXMGRERR_NOTENABLED

HRESULT GetBackBuffer(LPDIRECTDRAWSURFACE4 *lplpBackBuffer);

AddRef’s and passes back the back buffer created when the DXMgr object was enabled.

Parameters

LPDIRECTDRAWSURFACE4 **lplpBackBuffer

Parameter to receive the interface pointer.

Return Values

E_POINTER

DXMGRERR_NOTENABLED

HRESULT GetDeviceCaps( LPD3DDEVICEDESC pDesc );

Return Values

E_POINTER

DXMGRERR_NOTENABLED

HRESULT Initialize(LPGUID pDDGuid, HWND hwndFocus, UINT Flags );

Initializes the DXMgr object to talk to a specific DirectDraw object (or the primary display device). The DXMgr object can be initialized exactly once.

Parameters

LPGUID pDDGuid

Specifies the DirectDraw object to use to initialize the DXMgr. If NULL, or if the pointer points to a GUID that is all zeroes, the primary display device is used.

HWND hwndFocus

Specifies the focus window handle. In general, this should be the handle of the application’s main window. DirectDraw will forward keyboard messages to this window.

UINT Flags

No flags have been defined yet. This parameter should be set to 0.

Return Values

E_INVALIDARG

E_POINTER

DXMGRERR_ALREADYINITIALIZED

HRESULT RestoreSurfaces( );

Restores the primary, back buffer (if windowed), and Z buffer (if present). For fullscreen apps, the back buffer is an implicitly created surface, so it will be restored along with the primary.

This function is provided as a convenience to API clients that have not obtained pointers to all of the surfaces created by DXMgr. In particular, it is possible for Direct3D applications to only call GetDirect3DDevice and not have pointers to any of the surfaces created by DXMgr.

Return Values

If the return value is other than S_OK, it was propagated from IDirectDrawSurface4::Restore. The debug version of DXMgr prints a message telling which surface’s Restore call returned an error.

HRESULT Update(UINT Flags, PRECT pRect);

For a windowed DXMgr object, blts from the back buffer to the primary through a clipper.

For a full-screen DXMgr object, page-flips unless the pRect is non-NULL. If pRect is non-NULL and does not contain the full-screen rectangle, this function blts to the primary. In addition, DXMGRUPDATE_FORCEBLT forces the update to be done with a Blt rather than a page flip.

Parameters

UINT Flags

DXMGRUPDATE_DONOTWAIT – requests that the DDFLIP_WAIT or DDBLT_WAIT flags not be specified by DXMgr. This will cause DDERR_WASSTILLDRAWING to be propagated to the caller if the hardware device is busy, rather than waiting for the hardware device to free up.

DXMGRUPDATE_FORCEBLT - forces the update to be done with a Blt rather than a page flip.

PRECT pRect

If this parameter is NULL, the DXMgr assumes that the entire back buffer is to be updated to the primary. Otherwise, it gives the subrect of the back buffer to update.

Return Values

E_INVALIDARG

E_POINTER

DXMGRERR_NOTENABLED

2.2. IEnumDirectDraws

This interface is returned by CreateEnumDirectDraws. It enumerates DirectDraw objects available in the system. See the description of the DXMGROBJECTDESC structure for more details.

HRESULT Next( UINT cNumDDs, PDXMGROBJECTDESC pDDs, UINT *pNumDDs );

Gets the next cNumDDs DirectDraw objects available in the system. If pNumDDs is NULL, passes back the actual number of objects passed back in *pNumDDs.

Note: Programs can only examine or copy the strings referred to by the lpszDriverName and lpszDriverDesc members of DXMGROBJECTDESC. They must not cache the pointers or modify the strings.

Parameters

UINT cNumDDs;

The number of objects to be copied into the array pointed to by pDDs.

PDDOBJECTDESC pDDs;

Array to copy the data into.

UINT *pNumDDs;

Pointer to a UINT to receive the actual number of objects copied. If NULL, this parameter is ignored.

Return Values

S_OK if the number of objects returned is the same as cNumDDs.

S_FALSE otherwise.

HRESULT Skip( UINT cNumDDs );

Skips over cNumDDs objects in the enumeration.

Parameters

UINT cNumDDs;

Number of objects to skip.

Return Values

S_OK if the number of objects skipped is the same as cNumDDs.

S_FALSE otherwise.

HRESULT Reset();

Resets the enumerator to point to the beginning of the enumeration.

Parameters

None.

Return Values

S_OK

HRESULT Clone( IEnumDirectDraws **ppEnum );

Creates an enumerator with the exact same state.

Parameters

IEnumDirectDraws **ppEnum;

Pointer to receive the cloned enumerator.

Return Values

E_OUTOFMEMORY

2.3. IEnumPixelFormats

This interface is returned by CreateEnumZBufferFormats and CreateEnumTextureFormats. It enumerates DDPIXELFORMAT structures. See the description of IEnumDirectDraws for details on the functions in this interface.

HRESULT Next( UINT cNumPFss, LPDDPIXELFORMAT, UINT *pNumPFs );

Gets the next cNumPFs pixel formats. If pNumPFs is non-NULL, passes back the actual number of objects copied in *pNumPFs.

HRESULT Skip( UINT cNumPFs );

Skips over cNumPFs objects in the enumeration.

HRESULT Reset();

Resets the enumerator to point to the beginning of the enumeration.

HRESULT Clone( IEnumPixelFormats **ppEnum );

Creates an enumerator with the exact same state.

2.4. IEnumDisplayModes

This interface is returned by CreateEnumDisplayModes. It enumerates DXMGRMODEDESC structures. See the description of IEnumDirectDraws for details on the functions in this interface.

HRESULT Next( UINT cNumModes, PDDMODEDESC pMode, UINT *pNumModes );

Gets the next cNumModes display modes available in the system. If pNumModes is non-NULL, passes back the actual number of objects copied in *pNumModes.

HRESULT Skip( UINT cNumModes );

Skips over cNumModes objects in the enumeration.

HRESULT Reset();

Resets the enumerator to point to the beginning of the enumeration.

HRESULT Clone( IEnumDisplayModes **ppEnum );

Creates an enumerator with the exact same state.

3. Structures

3.1. DXMGROBJECTDESC

This structure describes a DirectDraw object that can be chosen at Enable time by passing a pointer to the guid member to IDXMgr::Initialize. Note: the GUID is zeroed out in the case of the primary display device, and Initialize correctly recognizes this and creates an instance of the primary. This obviates the need to check whether to pass a NULL pointer when passing a pointer to the guid member of this structure to IDXMgr::Initialize.

typedef struct _DXMGROBJECTDESC

{

GUID guid;

LPSTR lpszDriverName;

LPSTR lpszDriverDesc;

HMONITOR hMonitor;

} DXMGROBJECTDESC, *PDXMGROBJECTDESC;

GUID guid;

The GUID that uniquely identifies the hardware device in the system.

LPSTR lpszDriverName;

The driver name, e.g. “\\.\Display2” is a typical name for a secondary in a multimonitor configuration.

LPSTR lpszDriverDesc;

The driver description.

HMONITOR hMonitor;

The monitor that the display corresponds to. This handle is used in conjunction with the GDI extensions that were added for multimonitor support in Windows 98 and Windows NT 5.0.

3.2. DXMGRMODEDESC

This structure describes a display mode available on the Windows display adapter. The width, height and bits per pixel are always specified. On systems without refresh rate information, the dwRefreshRate member of this structure is set to 0. Otherwise dwRefreshRate is set to the display mode’s refresh rate in Hz.

typedef struct _DXMGRMODEDESC

{

DWORD dwWidth, dwHeight;

DWORD dwBPP;

DWORD dwRefreshRate;

} DXMGRMODEDESC, *PDXMGRMODEDESC;

Important note about refresh rates

Despite some safeguards built into Windows to avoid the possibility, it is not difficult to switch to a display mode that drives the monitor out of sync (at a refresh rate higher than the monitor can accommodate). To help end users avoid having this happen, ISVs can address the problem through documentation and software design. The documentation should encourage end users to set up their monitors if they have not already done so. If the monitor has been set up, Windows can do a better job of filtering out display modes that would drive it out of sync. To set up a monitor, users can click the Advanced… button in the Display Control Panel and select the Monitor tab.

Regardless of whether the end user has set up their monitor, applications that enable end users to select a display mode should make provision for the possibility of driving the monitor out of sync. The Display Control Panel implements one possible design to avoid having end users select unusable display modes. As soon as a new display mode is selected, the Control Panel switches to that mode and asks the end user to indicate that it is working correctly. If the end user does not respond within a few seconds, it restores the original display mode.

3.3. DXMGRENABLE

This structure is passed to IDXMgr::Enable as a parameter to describe how the object should be enabled. It contains a few required parameters, but most of the members of this structure are optional parameters to control how the DirectDraw and Direct3D objects are created underneath

typedef struct _DXMGRENABLE

{

UINT uFlags;

HWND hwndDevice;

DXMGRMODEDESC DisplayMode;

UINT cBackBuffers;

IID iidDeviceType;

LPDDPIXELFORMAT pddpfZBuffer;

float fNear, fFar;

} DXMGRENABLE;

UINT uFlags;

Flags to describe how to enable DXMgr for drawing. The possible values are described below.

Flag	Description
DXMGRENABLE_FULLSCREEN	Initialize DirectDraw to full-screen exclusive mode.
DXMGRENABLE_DISPLAYMODE	Application has filled in the DisplayMode structure to select the desired display mode to set for fullscreen. If this is not filled in, DXMgr will set the display mode to 640x480x16.
DXMGRENABLE_BACKBUFFERCOUNT	Application has filled in the cBackBuffers member of the Enable structure to specify the desired number of back buffers (the default is 1 for double buffering).
DXMGRENABLE_3D	If specified, 3D initialization is performed.
DXMGRENABLE_ZBUFFER	If specified, a Z buffer is created and attached to the back buffer.
DXMGRENABLE_DDPFZBUFFER	If specified, pddpfZBuffer points at a pixel format structure that describes the desired Z buffer format.
DXMGRENABLE_DEVICETYPE	If specified, the device type specified in the initialization structure will be used. If this device type cannot be supported for some reason, initialization will fail. NOTE: To prevent DXMgr from falling back to a software device, set DXMGRENABLE_DEVICETYPE flag and set iidDeviceType to IDirect3DHALDevice.
DXMGRENABLE_FORCEVIDEOMEMORY	Forces the back buffer into video memory. By default, the back buffer is put into video memory for HAL devices and system memory otherwise (software devices and when not initializing for 3D).

HWND hwndDevice;

In fullscreen mode (DXMGRENABLE_FULLSCREEN specified), this gives the device window handle. The device window is resized to fit the screen, and DirectDraw forwards mouse-related messages to this window. If NULL, DXMgr asks DirectDraw to create a device window.

In windowed mode, the window must be valid and DXMgr uses it to size the back buffer (by default, the back buffer is created the same size as this window’s client rectangle) and initialize the clipper.

DXMGRMODEDESC DisplayMode;

If DXMGRENABLE_DISPLAYMODE is set, DXMgr will attempt to set the display mode specified in this member of the structure. Otherwise, DXMgr will attempt to set the display mode to 640x480x16.

Note: the DXMGRENABLE_DISPLAYMODE flag is only valid if DXMGRENABLE_FULLSCREEN is set.

UINT cBackBuffers;

If DXMGRENABLE_BACKBUFFERCOUNT is set, DXMgr will create this number of back buffers instead of the default of 1 (double buffering). For example, to set up triple buffering, set cBackBuffers to 2.

Note: the DXMGRENABLE_BACKBUFFERCOUNT flag is only valid if DXMGRENABLE_FULLSCREEN is set.

IID iidDeviceType;

If DXMGRENABLE_DEVICETYPE is set, DXMgr will force creation of this Direct3D device type instead of following the default device selection algorithm.

LPDDPIXELFORMAT pddpfZBuffer;

Points to the Z buffer pixel format. This structure member is ignored unless the DXMGRENABLE_DDPFZBUFFER flag is set.

float fNear, fFar;

If DXMGRENABLE_3D is set, DXMgr will initialize the Direct3D device with a PROJECTION matrix that corresponds to a 90-degree field of view and near and far clipping planes at the distances of fNear and fFar. The description of the Enable function has details on the default viewport and projection matrix setup.

3.4. DXMGRENABLEINFO

This structure is returned by IDXMgr::GetEnableInfo. It contains information on how the DirectDraw and Direct3D objects were created by IDXMgr::Enable. For the most part, this information is provided as a convenience; however, if the device selection is left to DXMgr, it is difficult to tell what type of device was selected given the interface pointer alone.

typedef struct _DXMGRENABLEINFO

{
UINT uWidth, uHeight;

DXMGRMODEDESC DisplayMode;

DDPIXELFORMAT ddpfPrimary;

DDPIXELFORMAT ddpfZBuffer;

IID iidDeviceType;

} DXMGRENABLEINFO;

UINT uWidth, uHeight;

Width and height of the back buffer created by DXMgr.

DXMGRMODEDESC DisplayMode;

Display mode after DXMgr was enabled. If DXMgr was enabled in windowed mode, this structure is filled with zeroes.

DDPIXELFORMAT ddpfPrimary;

Pixel format of the primary.

DDPIXELFORMAT ddpfZBuffer;

Pixel format of the Z buffer. If DXMgr was enabled without 3D, this structure is zeroed out.

IID iidDeviceType;

Device type that the DXMgr was enabled with. If DXMgr was enabled without 3D, this structure is zeroed out.

4. Software Development Kit materials

The DXMgr distribution contains the following directories and files.

File/Directory	Description
dxmgr.doc	Word document that describes the DXMgr library
INCLUDE\	Directory for header files
dxmgr.h	DXMgr header file
dxmgr_i.c	Header that contains DXMgr GUID declarations
LIB\	Directory for library files
ALPHA\	* Directory for library files for Alpha processors
DEBUG\	Directory for debug library
dxmgr.lib	Static library for debug DXMgr for Alpha
RETAIL\	Directory for retail library
dxmgr.lib	Static library for retail DXMgr for Alpha
I386\	Directory for library files for Intel processors
DEBUG\	Directory for debug library
dxmgr.lib	Static library for debug DXMgr for Intel
RETAIL\	Directory for retail library
dxmgr.lib	Static library for retail DXMgr for Intel
SAMPLES\	Directory for samples
BIN\	Directory for built samples
trivwin.exe	Trivial windowed sample
trivfs.exe	Trivial fullscreen sample
trivboth.exe	Trivial windowed and fullscreen sample
multifs.exe	Multimonitor-aware fullscreen sample
TRIVWIN\	Source code for trivial windowed sample
trivwin.dsp	Microsoft Visual C++ 5.0 project file
trivwin.cpp	C++ source file
resource.h	Header file for resources
trivwin.rc	Resource file
TRIVFS\	Source code for trivial fullscreen sample
trivfs.dsp	Microsoft Visual C++ 5.0 project file
trivfs.cpp	C++ source file
resource.h	Header file for resources
trivfs.rc	Resource file
TRIVBOTH\	Source code for trivial windowed and fullscreen sample
trivboth.dsp	Microsoft Visual C++ 5.0 project file
trivboth.cpp	C++ source file
resource.h	Header file for resources
trivboth.rc	Resource file
MULTIFS\	Source code for multimon-aware fullscreen sample
multifs.dsp	Microsoft Visual C++ 5.0 project file
multifs.cpp	C++ source file
resource.h	Header file for resources
multifs.rc	Resource file

* The Web site distribution of DXMgr does not contain the Alpha versions of the libraries. To obtain copies of these binaries, which require Windows NT 5.0 Beta 2 or later, send email to dxmgr@microsoft.com.

5. Sample Code

The sample code included with DXMgr shows how to build applications in the most common application scenarios. They are intended to be as small and approachable as possible, so do not implement large amounts of user interface code. For example, if DXMgr is unable to initialize for some reason (ranging from a lack of video memory to the absence of DirectX 6.0 on the system), these applications will silently exit rather than explain the problem in a message box.

5.1. TrivWin – trivial windowed application

This sample spins a triangle in a window using Direct3D. It relies on the default behaviors implemented in DXMgr; for example, if you launch many instances of TrivWin, they will create HAL devices until the system runs out of video memory. When there is no longer enough video memory to create a back buffer, TrivWin falls back to software rasterization. Similarly, TrivWin falls back to software if the window is resized such that there is no longer enough video memory for the back buffer.

The application handles resize messages by Disabling and re-Enabling the DXMgr object, which basically reduces to tearing down and reconstructing everything but the DirectDraw object (back buffer, Direct3D device, viewport, etc.).

A planned enhancement of DXMgr is to implement OnMove and OnSize methods which would destroy the back buffer, create a new one, and SetRenderTarget the existing device to the new back buffer if possible. This would obviate the need to create a new device (and corresponding new lights, materials and textures) whenever the end user resized the window. These entry points would also facilitate hardware-accelerated rendering on whichever device the window happened to reside in (TrivWin currently defaults to hardware rendering only on the primary).

5.2. TrivFS – trivial fullscreen application

This sample is substantially the same as TrivWin, but sets DXMGRENABLE_FULLSCREEN to request that the primary device be put into fullscreen exclusive mode. Like TrivWin, it relies on DXMgr to fall back on software rasterization if no HAL is available.

TrivFS uses DXMgr’s default display mode setting, which simply sets the device to 640x480x16.

5.3. TrivBoth – trivial windowed and fullscreen application

This sample spins the same triangle as TrivWin and TrivFS, but allows the user to hit Alt+Enter to toggle between fullscreen and windowed modes. Hence, it includes the union of the window handling and update code for TrivWin and TrivFS and toggles between the two based on whether it is running in windowed or fullscreen mode.

5.4. MultiFS – multimon-aware fullscreen application

This sample puts all available DirectDraw devices into fullscreen exclusive mode and spins an untextured triangle on all of them. Owners of the 3Dfx Voodoo accelerator will be interested to know that this application drives both the primary and the 3Dfx simultaneously (you are missing out if you are using a passthrough cable).

MultiFS illustrates some of the intricacies of fullscreen DirectDraw programming in a multimon scenario. It uses the application window as the focus window and device window for the first available device. For subsequent devices, it sets the application window as the focus window and asks DXMgr to create a device window.

MultiFS also includes some user interface code to enable the user to see how each device was enabled. If you select “DirectDraw Devices…” from the File menu, it will put up a dialog with a list box that shows the name of each device and whether it was enabled for hardware or software rendering.

6. Support

6.1. Contact Info

Send mail to dxmgr@microsoft.com with comments, suggestions and other feedback on DXMgr.

6.2. Frequently Asked Questions

Q. Why am I getting an “already defined” link error for various GUIDs used by DXMgr?

A. The dxmgr_i.c file should be included in only one file in your application. The sample programs do not make this clear because each sample contains only one C++ source file.

Q. How do I set up for triple buffering?

A. In the DXMGRENABLE structure, set the DXMGRENABLE_BACKBUFFERCOUNT flag and set cBackBuffers to 2.

Q. Why isn’t the source code provided?

A. The source code to initialize DirectX consists of several thousand lines and has been made available in several forms since DirectX 2.0. We believed it would be beneficial to move this code into a library so Direct3D applications could be written without incorporating several thousand lines of initialization code.

Developers interested in the nitty-gritty details of DirectX initialization may wish to consult the “Multimedia\D3DIM\src\D3DFrame” directory in the DirectX 6.0 Software Development Kit.

Q. How do I do Z buffering?

A. Set the uFlags member of the DXMGRENABLE structure to DXMGRENABLE_3D | DXMGRENABLE_ZBUFFER to cause DXMgr to create and attach a Z buffer. By default, this will create a 16-bit Z buffer.

To create a Z buffer with a particular pixel format, set the DXMGRENABLE_DDPFZBUFFER flag and fill in the ddpfZBuffer member of the DXMGRENABLE structure. The DDPIXELFORMAT structure can be copied directly from the enumerator returned by IDXMgr::CreateEnumZBufferFormats.

NOTE: the default Z buffer compare mode is D3DCMP_LESSEQUAL, and the Z buffer contents are undefined at initialization. To clear the Z buffer to maximum, set the dvClearValue parameter of IDXMgr::Clear (or IDirect3DViewport3::Clear2) to 1.0f, not 0.0f.

Q. How can I implement a complicated initialization sequence, such as triple buffering only if enough memory is available?

The suggested method for implementing complicated initializations is to create and Enable a DXMgr object, then check whether the result was satisfactory. If not, the DXMgr can be Disable/re-Enabled in a different way to get a better result. For example, if an application wants to triple buffer as long as that consumes less than half of the available video memory, it could start by enabling the DXMgr object for triple buffering. If this Enable call fails for some reason, the application can check the error code and respond accordingly (perhaps by calling Enable again with different parameters); if the Enable call succeeds, the application can call GetAvailableVidMem and decide whether to continue. If the application decides it needs to run double-buffered after all, it can call Disable and then call Enable again without requesting triple buffering the second time. This sequence of calls asks DirectX to do a lot of work under the hood, but does not consume many lines of code in the application and runs fast enough that the end user will not notice.

Another complicated initialization scenario would be for applications that prefer to run on hardware but always want to run with a sophisticated rendering capability, such as anisotropic filtering. To do this using DXMgr, start out by Enabling for HAL (set the DXMGRENABLE_DEVICETYPE flag and set iidDeviceType to IID_IDirect3DHALDevice). If this succeeds, check the resulting device’s capabilities. If they are unsatisfactory, the DXMgr can be Disabled and re-Enabled with (for example) the reference rasterizer device.

Q. How do I force HAL rendering and fall back to my own software rasterizer if a HAL is unavailable?

A. First, try Enabling the DXMgr for 3D with the DXMGRENABLE_DEVICETYPE flag set and iidDeviceType set to IID_IDirect3DHALDevice. This will cause Enable to fail if no 3D hardware device is available. If Enable fails, call it again without DXMGRENABLE_3D (and, most likely, with the DXMGRENABLE_FORCEVIDEOMEMORY flag set) to set up DirectDraw only. You can then call GetBackBuffer to get a pointer to the DirectDraw surface that DXMgr created as your back buffer, and Lock it to do your software rendering.

Q. How do I obtain the viewport that DXMgr created?

A. Call IDXMgr::GetDirect3DDevice, then call IDirect3DDevice3::GetCurrentViewport off the Direct3D device interface. This function will AddRef and return the viewport interface pointer.

6.3. Planned Enhancements

Several enhancements to DXMgr are likely to be implemented in a future release of the library. Please send comments on these planned enhancements, and suggestions for other enhancements, to dxmgr@microsoft.com.

1) Enhanced display mode enumeration. This is an oft-requested feature from ISVs who want to filter out display modes that will not support hardware-accelerated 3D rendering.

2) Fallback to overlay surface in windowed mode, if the desktop is in a mode that does not support hardware-accelerated rendering.

3) OnMove and OnSize methods for better windowed mode support. These would only be callable if the application specified a NULL DirectDraw GUID at Initialize time, which asks DXMgr to manage the DirectDraw object on behalf of the application. Then, DXMgr would strive to always put the back buffer in the video memory of the display adapter that the window currently resides on. (Currently, DXMgr strives to always put the back buffer in the video memory of the primary display adapter.)

Note: OnMove and OnSize are intended to be called only by windowed 3D applications.

HRESULT OnMove(PDXMGRENABLE pEnable);

Called when the window specified at Enable time gets moved.

This function does nothing and returns S_OK in single-monitor configurations or if the window stayed on the same device in a multimonitor configuration.

In multimonitor configurations, if the window transitions to a different device, DXMgr will create a new DirectDraw object and Enable it for drawing. If this operation is successful, DXMgr will return S_FALSE, indicating that the application should release its existing references to DXMgr objects and obtain new ones. If the operation is not successful, DXMgr will propagate a DirectX error as to the reason.

NOTE: if OnMove returns an error, the various objects that DXMgr owned before the call (back buffer, Z buffer, etc.) are no longer available. In other words, the DXMgr object reverts to the Initialized state if the call fails.

HRESULT OnSize(PDXMGRENABLE pEnable);

Called when the window specified at Enable time gets resized.

This function first attempts to do the minimum work necessary to respond to the resize: it allocates new back and Z buffers and attempts to SetRenderTarget the DXMgr’s existing Direct3D device to these new buffers. If this operation succeeds, the function will return S_OK.

If DXMgr is unable to set a new render target to the device, it will Disable (Release the primary, back buffer, Z buffer, Direct3D device, etc.) and re-Enable with a new DirectDraw object. If this operation is successful, DXMgr will return S_FALSE, indicating to the application that it had to create a new Direct3D device.

As with OnMove, if this function fails, the DXMgr object is left in the Initialized state (i.e. it does not have references to any DirectX objects).

вторник, 12 июня 2007 г.

A Library for Simplified DirectX Programming

Parameters

Error Returns

IMPORTANT NOTE

Parameters

Return Values

Return Values

Return Values

Return Values

Return Values

IMPORTANT NOTE

Parameters

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Important note about refresh rates

UINT uFlags;

Комментариев нет:

Keeley hazell videos

Архив блога

Link Building Guide

Обычный такой блог

Cyb"s Blog - böse Netzgeschichten

вторник, 12 июня 2007 г.