IDirect3DRMDevice2

Applications use the methods of the IDirect3DRMDevice2 and IDirect3DRMDevice interfaces to interact with the output device. While IDirect3DRMDevice, when created from the IDirect3DRM interface, works with an IDirect3DDevice Immediate Mode device, IDirect3DRMDevice2, when created from the IDirect3DRM2 interface, or initialized by the IDirect3DRMDevice2::InitFromD3D2 or IDirect3DRMDevice2::InitFromSurface method, works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface, as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

The IDirect3DRMDevice2::InitFromSurface method uses the IDirect3DRM2::CreateDevice method to create an IDirect3DRMDevice2 interface. The IDirect3DRMDevice2::InitFromD3D2 method uses an IDirect3D2 Immediate Mode object and an IDirect3DDevice2 Immediate Mode device to initialize an IDirect3DRMDevice2 Microsoft® Direct3D® Retained Mode device.

You can still query back and forth between IDirect3DRMDevice and IDirect3DRMDevice2. The main difference is in how the underlying Immediate Mode device is created.

IDirect3DRMDevice2 contains all the methods in IDirect3DRMDevice, plus two addition ones that allow you to control transparency: IDirect3DRMDevice2::GetRenderMode and IDirect3DRMDevice2::SetRenderMode; one additional initialization method: IDirect3DRMDevice2::InitFromSurface; and two changed methods IDirect3DRMDevice2::GetDirect3DDevice2 and IDirect3DRMDevice2::InitFromD3D2, which get and initialize an IDirect3DRMDevice2 object rather than an IDirect3DRMDevice object.

This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMDevice, IDirect3DRMDevice2, and IDirect3DRMDeviceArray Interfaces.

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

Buffer counts	GetBufferCount
	SetBufferCount
Color models	GetColorModel
Dithering	GetDither
	SetDither
Initialization	Init
	InitFromClipper
	InitFromD3D2
	InitFromSurface
Miscellaneous	GetDirect3DDevice2
	GetHeight
	GetTrianglesDrawn
	GetViewports
	GetWidth
	GetWireframeOptions
	Update
Notifications	AddUpdateCallback
	DeleteUpdateCallback
Rendering quality	GetQuality
	SetQuality
Shading	GetShades
	SetShades
Texture quality	GetTextureQuality
	SetTextureQuality
Transparency	GetRenderMode
	SetRenderMode

The IDirect3DRMDevice2 interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

AddRef

QueryInterface

Release

In addition, the IDirect3DRMDevice2 interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback

Clone

DeleteDestroyCallback

GetAppData

GetClassName

GetName

SetAppData

SetName

The Direct3DRMDevice2 object is obtained by calling the IDirect3DRM2::CreateDevice method.

---

IDirect3DRMDevice2::AddUpdateCallback

IDirect3DRMDevice2

Adds a callback function that alerts the application when a change occurs to the device. The system calls this callback function whenever the application calls the IDirect3DRMDevice2::Update method.

HRESULT AddUpdateCallback(
  D3DRMUPDATECALLBACK d3drmUpdateProc,
  LPVOID arg
  );

Parameters

d3drmUpdateProc

Address of an application-defined callback function, D3DRMUPDATECALLBACK.

arg

Private data to be passed to the update callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::DeleteUpdateCallback, IDirect3DRMDevice2::Update, D3DRMUPDATECALLBACK

---

IDirect3DRMDevice2::DeleteUpdateCallback

IDirect3DRMDevice2

Removes an update callback function that was added by calling the IDirect3DRMDevice2::AddUpdateCallback method.

HRESULT DeleteUpdateCallback(
  D3DRMUPDATECALLBACK d3drmUpdateProc,
  LPVOID arg
  );

Parameters

d3drmUpdateProc

Address of an application-defined callback function, D3DRMUPDATECALLBACK.

arg

Private data that was passed to the update callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::AddUpdateCallback, IDirect3DRMDevice2::Update, D3DRMUPDATECALLBACK

---

IDirect3DRMDevice2::GetBufferCount

IDirect3DRMDevice2

Retrieves the value set in a call to the IDirect3DRMDevice2::SetBufferCount method.

DWORD GetBufferCount( );

Return Values

Returns the number of buffers—one for single-buffering, two for double-buffering, and so on.

---

IDirect3DRMDevice2::GetColorModel

IDirect3DRMDevice2

Retrieves the color model of a device.

D3DCOLORMODEL GetColorModel( );

Return Values

Returns a value from the D3DCOLORMODEL enumerated type that describes the Direct3D color model (RGB or monochrome).

See Also

Color Models

---

IDirect3DRMDevice2::GetDirect3DDevice2

IDirect3DRMDevice2

Retrieves a pointer to an IDirect3DDevice2 Immediate Mode device.

HRESULT GetDirect3DDevice2(
  LPDIRECT3DDEVICE2 * lplpD3DDevice
  );

Parameters

lplpD3DDevice

Address of a pointer that is initialized with a pointer to an IDirect3DDevice2 Immediate Mode device object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The IDirect3DDevice2 device will support the DrawPrimitive interface and execute buffers and is required for progressive meshes and for alpha blending and sorting of transparent objects.

---

IDirect3DRMDevice2::GetDither

IDirect3DRMDevice2

Retrieves the dither flag for the device.

BOOL GetDither( );

Return Values

Returns TRUE if the dither flag is set, or FALSE otherwise.

See Also

IDirect3DRMDevice2::SetDither

---

IDirect3DRMDevice2::GetHeight

IDirect3DRMDevice2

Retrieves the height, in pixels, of a device. This method is a convenience function.

DWORD GetHeight( );

Return Values

Returns the height.

---

IDirect3DRMDevice2::GetQuality

IDirect3DRMDevice2

Retrieves the rendering quality for the device.

D3DRMRENDERQUALITY GetQuality( );

Return Values

Returns one or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY type.

See Also

IDirect3DRMDevice2::SetQuality

---

IDirect3DRMDevice2::GetRenderMode

IDirect3DRMDevice2

Retrieves the current transparency flags.

DWORD GetRenderMode( );

Return Values

Returns the value of the current transparency flags.

Remarks

Transparency flags have the following values:

Flag	Value
No flag set (default)	0
D3DRMRENDERMODE_BLENDEDTRANSPARENCY	1
D3DRMRENDERMODE_SORTEDTRANSPARENCY	2

See Also

IDirect3DRMDevice2::SetRenderMode

---

IDirect3DRMDevice2::GetShades

IDirect3DRMDevice2

Retrieves the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.

DWORD GetShades( );

Return Values

Returns the number of shades.

See Also

IDirect3DRMDevice2::SetShades

---

IDirect3DRMDevice2::GetTextureQuality

IDirect3DRMDevice2

Retrieves the current texture quality parameter for the device. Texture quality is relevant only for an RGB device.

D3DRMTEXTUREQUALITY GetTextureQuality( );

Return Values

Returns one of the members of the D3DRMTEXTUREQUALITY enumerated type.

See Also

IDirect3DRMDevice2::SetTextureQuality

---

IDirect3DRMDevice2::GetTrianglesDrawn

IDirect3DRMDevice2

Retrieves the number of triangles drawn to a device since its creation. This method is a convenience function.

DWORD GetTrianglesDrawn( );

Return Values

Returns the number of triangles.

Remarks

The number of triangles includes those that were passed to the renderer but were not drawn because they were backfacing. The number does not include triangles that were rejected for lying outside of the viewing frustum.

---

IDirect3DRMDevice2::GetViewports

IDirect3DRMDevice2

Constructs a Direct3DRMViewportArray object that represents the viewports currently constructed from the device.

HRESULT GetViewports(
  LPDIRECT3DRMVIEWPORTARRAY* lplpViewports
  );

Parameters

lplpViewports

Address of a pointer that is initialized with a valid Direct3DRMViewportArray object if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

---

IDirect3DRMDevice2::GetWidth

IDirect3DRMDevice2

Retrieves the width, in pixels, of a device. This method is a convenience function.

DWORD GetWidth( );

Return Values

Returns the width.

---

IDirect3DRMDevice2::GetWireframeOptions

IDirect3DRMDevice2

Retrieves the wireframe options of a given device.

DWORD GetWireframeOptions( );

Return Values

Returns a bitwise OR of the following values:

D3DRMWIREFRAME_CULL

The backfacing faces are not drawn.

D3DRMWIREFRAME_HIDDENLINE

Wireframe-rendered lines are obscured by nearer objects.

---

IDirect3DRMDevice2::Init

IDirect3DRMDevice2

Not implemented on the Microsoft® Windows® platform.

HRESULT Init(
  ULONG width,
  ULONG height
  );

---

IDirect3DRMDevice2::InitFromClipper

IDirect3DRMDevice2

Initializes an IDirect3DDevice2 device from a specified DirectDrawClipper object using IDirect3DRM2::CreateDevice.

HRESULT InitFromClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper,
  LPGUID lpGUID,
  int width,
  int height
  );

Parameters

lpDDClipper

Address of the DirectDrawClipper object to use as an initializer.

lpGUID

Direct3D device driver to use.

width and height

Width and height of the device in pixels.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

---

IDirect3DRMDevice2::InitFromD3D2

IDirect3DRMDevice2

Initializes an IDirect3DRMDevice2 Retained Mode device from an IDirect3D2 Immediate Mode object and an IDirect3DDevice2 Immediate Mode device.

HRESULT InitFromD3D2(
  LPDIRECT3D2 lpD3D,
  LPDIRECT3DDEVICE2 lpD3DIMDev
  );

Parameters

lpD3D

Address of the IDirect3D2 Immediate Mode object to use to initialize the Retained Mode device.

lpD3DIMDev

Address of the IDirect3DDevice2 Immediate Mode device to use to initialize the Retained Mode device.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The IDirect3DRMDevice2 device initialized from IDirect3DDevice2 will support the DrawPrimitive interface and execute buffers and is required for progressive meshes and for alpha blending and sorting of transparent objects.

---

IDirect3DRMDevice2::InitFromSurface

IDirect3DRMDevice2

Initializes a IDirect3DDevice2 device from a specified DirectDraw surface, using the IDirect3DRM2::CreateDevice method.

HRESULT InitFromSurface(
  LPGUID lpGUID,
  LPDIRECTDRAW lpDD,
  LPDIRECTDRAWSURFACE lpDDSBack
  );

Parameters

lpGUID

Address of the globally unique identifier (GUID) that identifies the Direct3D device driver to use.

lpDD

Address of the interface of a DirectDraw object that created the DirectDrawSurface.

lpDDSBack

Address of the interface of a DirectDrawSurface back buffer onto which the device will render.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The IDirect3DRMDevice2 device initialized will support the DrawPrimitive interface and execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

---

IDirect3DRMDevice2::SetBufferCount

IDirect3DRMDevice2

Sets the number of buffers currently being used by the application.

HRESULT SetBufferCount(
  DWORD dwCount
  );

Parameters

dwCount

Number of buffers—one for single-buffering, two for double-buffering, and so on. The default value is 1, which is correct only for a single-buffered window operation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

An application that employs double-buffering or triple-buffering must use this method to inform the system of how many buffers it is using so that the system can calculate how much of the window to clear and update on each frame.

See Also

IDirect3DRMDevice2::GetBufferCount

---

IDirect3DRMDevice2::SetDither

IDirect3DRMDevice2

Sets the dither flag for the device.

HRESULT SetDither(
  BOOL bDither
  );

Parameters

bDither

New dithering mode for the device. The default is TRUE.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::GetDither

---

IDirect3DRMDevice2::SetQuality

IDirect3DRMDevice2

Sets the rendering quality of a device

HRESULT SetQuality (
  D3DRMRENDERQUALITY rqQuality
  );

Parameters

rqQuality

One or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY type. The default setting is D3DRMRENDER_FLAT.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The rendering quality is the maximum quality at which rendering can take place on the rendering surface of that device.

An object's quality has three components: shade mode (flat or Gouraud; Phong is not yet implemented and will default to Gouraud shading), lighting type (on or off), and fill mode (point, wireframe or solid).

You set the quality of a device with SetQuality. By default it is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMProgressiveMesh, Direct3DRMMeshBuilder, or Direct3DRMMeshBuilder2 object with their respective SetQuality methods. By default, the quality of these objects is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Direct3D Retained Mode renders an object at the lowest quality setting based on the device and object's current setting for each individual component. For example, if the object's current quality setting is D3DRMRENDER_GOURAUD, and the device is D3DRMRENDER_FLAT, the object will be rendered with flat shading, solid fill, and lights on.

If the object's current quality setting is D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME and the device's quality setting is D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT, the object will be rendered with flat shading, lights off, and point fill mode.

These rules apply to Direct3DRMMeshBuilder objects, Direct3DRMMeshBuilder2 objects, and Direct3DRMProgressiveMesh objects. However, Direct3DRMMesh objects do not follow these rules. Mesh objects ignore the device's quality settings and use the group quality setting (which defaults to D3DRMRENDER_GOURAUD).

See Also

IDirect3DRMDevice2::GetQuality

---

IDirect3DRMDevice2::SetRenderMode

IDirect3DRMDevice2

Sets the transparency mode. The mode type determines how transparent objects will be rendered. The default mode renders transparent objects with stippled transparency.

HRESULT SetRenderMode(
  DWORD dwFlags
  );

Parameters

dwFlags

One or more of the transparent mode flags. The default (dwFlags = 0) sets the transparency mode to stippled transparency. In addition, flags can have one or more of the following values:

D3DRMRENDERMODE_BLENDEDTRANSPARENCY (dwFlags = 1) sets the transparency mode to alpha blending.

D3DRMRENDERMODE_SORTEDTRANSPARENCY (dwFlags = 2) sets the transparency mode so that transparent polygons in the scene are buffered, sorted, and rendered in a second pass. This flag has no effect if the D3DRMRENDERMODE_BLENDEDTRANSPARENCY flag is not also set.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

If the D3DRMRENDERMODE_BLENDEDTRANSPARENCY and D3DRMRENDERMODE_SORTEDTRANSPARENCY flags are set together, it ensures that when two transparent objects are rendered one on top of the other, the image will blend in the correct order to ensure the right visual result.

See Also

IDirect3DRMDevice2::GetRenderMode

---

IDirect3DRMDevice2::SetShades

IDirect3DRMDevice2

Sets the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.

HRESULT SetShades(
  DWORD ulShades
  );

Parameters

ulShades

New number of shades. This parameter must be a power of 2. The default is 32.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::GetShades

---

IDirect3DRMDevice2::SetTextureQuality

IDirect3DRMDevice2

Sets the texture quality for the device.

HRESULT SetTextureQuality(
  D3DRMTEXTUREQUALITY tqTextureQuality
  );

Parameters

tqTextureQuality

One of the members of the D3DRMTEXTUREQUALITY enumerated type. The default is D3DRMTEXTURE_NEAREST.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::GetTextureQuality

---

IDirect3DRMDevice2::Update

IDirect3DRMDevice2

Copies the image that has been rendered to the display. It also provides a heartbeat function to the device driver.

HRESULT Update( );

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

Each call to this method causes the system to call an application-defined callback function, D3DRMUPDATECALLBACK. To add a callback function, use the IDirect3DRMDevice2::AddUpdateCallback method.

See Also

IDirect3DRMDevice2::AddUpdateCallback, D3DRMUPDATECALLBACK

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page