Index Topic Contents | |||
Previous Topic: IDirect3DRMAnimationSet Next Topic: IDirect3DRMDevice2 |
IDirect3DRMDevice
Applications use the methods of the IDirect3DRMDevice interface to interact with the output device. 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 IDirect3DRMDevice interface can be organized into the following groups:
Buffer counts GetBufferCount SetBufferCount Color models GetColorModel Dithering GetDither SetDither Initialization Init InitFromClipper InitFromD3D Miscellaneous GetDirect3DDevice GetHeight GetTrianglesDrawn GetViewports GetWidth GetWireframeOptions Update Notifications AddUpdateCallback DeleteUpdateCallback Rendering quality GetQuality SetQuality Shading GetShades SetShades Texture quality GetTextureQuality SetTextureQuality The IDirect3DRMDevice 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 IDirect3DRMDevice interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback Clone DeleteDestroyCallback GetAppData GetClassName GetName SetAppData SetName The Direct3DRMDevice object is obtained by using the IDirect3DRM::CreateDevice method.
IDirect3DRMDevice
IDirect3DRMDevice::AddUpdateCallbackAdds a callback function that alerts the application when a change occurs to the device. The system uses this callback function whenever the application uses the IDirect3DRMDevice::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 errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMDevice::DeleteUpdateCallback, IDirect3DRMDevice::Update, D3DRMUPDATECALLBACK
IDirect3DRMDevice
IDirect3DRMDevice::DeleteUpdateCallbackRemoves an update callback function that was added by using the IDirect3DRMDevice::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 errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMDevice::AddUpdateCallback, IDirect3DRMDevice::Update, D3DRMUPDATECALLBACK
IDirect3DRMDevice
IDirect3DRMDevice::GetBufferCount
Retrieves the value set in a call to the IDirect3DRMDevice::SetBufferCount method.
DWORD GetBufferCount( );
Return Values
Returns the number of buffersone for single-buffering, two for double-buffering, and so on.
IDirect3DRMDevice
IDirect3DRMDevice::GetColorModel
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
IDirect3DRMDevice
IDirect3DRMDevice::GetDirect3DDevice
Retrieves a pointer to an Immediate Mode device.
HRESULT GetDirect3DDevice(
LPDIRECT3DDEVICE * lplpD3DDevice
);Parameters
- lplpD3DDevice
- Address of a pointer that is initialized with a pointer to an Immediate Mode device object.
Return Values
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMDevice
IDirect3DRMDevice::GetDither
Retrieves the dither flag for the device.
BOOL GetDither( );
Return Values
Returns TRUE if the dither flag is set, or FALSE otherwise.
See Also
IDirect3DRMDevice
IDirect3DRMDevice::GetHeight
Retrieves the height, in pixels, of a device. This method is a convenience function.
DWORD GetHeight( );
Return Values
Returns the height.
IDirect3DRMDevice
IDirect3DRMDevice::GetQuality
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
IDirect3DRMDevice
IDirect3DRMDevice::GetShades
Retrieves the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) color model.
DWORD GetShades( );
Return Values
Returns the number of shades.
See Also
IDirect3DRMDevice
IDirect3DRMDevice::GetTextureQuality
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
IDirect3DRMDevice::SetTextureQuality
IDirect3DRMDevice
IDirect3DRMDevice::GetTrianglesDrawn
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.
IDirect3DRMDevice
IDirect3DRMDevice::GetViewports
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 errors, see Direct3D Retained Mode Return Values.
IDirect3DRMDevice
IDirect3DRMDevice::GetWidth
Retrieves the width, in pixels, of a device. This method is a convenience function.
DWORD GetWidth( );
Return Values
Returns the width.
IDirect3DRMDevice
IDirect3DRMDevice::GetWireframeOptions
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.
IDirect3DRMDevice
IDirect3DRMDevice::InitNot implemented on the Windows® platform.
HRESULT Init(
ULONG width,
ULONG height
);IDirect3DRMDevice
IDirect3DRMDevice::InitFromClipperInitializes a device from a specified DirectDrawClipper object.
HRESULT InitFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height
);Parameters
- lpDDClipper
- Address of the DirectDrawClipper object to use as an initializer.
- lpGUID
- Address of the globally unique identifier (GUID) used as the interface identifier.
- 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 errors, see Direct3D Retained Mode Return Values.
IDirect3DRMDevice
IDirect3DRMDevice::InitFromD3D
Initializes a Retained Mode device from a specified Direct3D Immediate Mode object and Immediate Mode device.
HRESULT InitFromD3D(
LPDIRECT3D lpD3D,
LPDIRECT3DDEVICE lpD3DIMDev
);Parameters
- lpD3D
- Address of the Direct3D Immediate Mode object to use to initialize the Retained Mode device.
- lpD3DIMDev
- Address of the 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 errors, see Direct3D Retained Mode Return Values.
IDirect3DRMDevice
IDirect3DRMDevice::SetBufferCount
Sets the number of buffers currently being used by the application.
HRESULT SetBufferCount(
DWORD dwCount
);Parameters
- dwCount
- Specifies the number of buffersone 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 errors, 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
IDirect3DRMDevice::GetBufferCount
IDirect3DRMDevice
IDirect3DRMDevice::SetDither
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 errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMDevice
IDirect3DRMDevice::SetQuality
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 errors, 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 then 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, then 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
IDirect3DRMDevice
IDirect3DRMDevice::SetShades
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 errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMDevice
IDirect3DRMDevice::SetTextureQuality
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 errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMDevice::GetTextureQuality
IDirect3DRMDevice
IDirect3DRMDevice::Update
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 errors, see Direct3D Retained Mode Return Values.
Remarks
Each call to this method causes the system to use an application-defined callback function, D3DRMUPDATECALLBACK. To add a callback function, use the IDirect3DRMDevice::AddUpdateCallback method.
See Also
IDirect3DRMDevice::AddUpdateCallback, D3DRMUPDATECALLBACK
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.