Direct3DRMDevice3
When you create the Direct3DRMDevice3 interface from the Direct3DRM3 interface, the interface works with a Direct3DDevice3 Immediate Mode device. The Direct3DDevice3 device executes buffers, and is required for progressive meshes, for alpha blending and sorting of transparent objects.
The methods of the Direct3DRMDevice3 interface can be organized into the following groups.
Buffer counts GetBufferCount SetBufferCount Color models GetColorModel Dithering GetDither SetDither Miscellaneous GetDirect3DDevice3 GetHeight GetTrianglesDrawn GetViewports GetWidth GetWireframeOptions Update Notifications AddUpdateCallback DeleteUpdateCallback Rendering quality GetQuality SetQuality Shading GetShades SetShades Textures FindPreferredTextureFormat GetTextureQuality SetTextureQuality Transparency GetRenderMode SetRenderMode
The Direct3DRMDevice3 interface inherits the following methods from the Direct3DRMObject interface.
- AddDestroyCallback
- CloneObject
- DeleteDestroyCallback
- GetAppData
- GetClassName
- GetName
- SetAppData
- SetName
The Direct3DRMDevice3 object can be obtained by calling the Direct3DRM3.CreateDeviceFromClipper, Direct3DRM3.CreateDeviceFromD3D, or Direct3DRM3.CreateDeviceFromSurface methods.
Direct3DRMDevice3.AddUpdateCallback
Direct3DRMDevice3
Adds a callback that alerts the application when a change occurs to the device. The system uses this callback when the application uses the Direct3DRMDevice3.Update method.
Syntax
object.AddUpdateCallback(
updateCallbackImplementation As Direct3DRMDeviceUpdateCallback3,
userArgument As object)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- updateCallbackImplementation
- Application-defined callback interface, Direct3DRMDeviceUpdateCallback3.
- userArgument
- Private data to be passed to the update callback.
Error Values
For a list of possible error values, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.DeleteUpdateCallback
Direct3DRMDevice3
Removes an update callback that was added by using the Direct3DRMDevice3.AddUpdateCallback method.
Syntax
object.DeleteUpdateCallback(
updateCallbackImplementation As Direct3DRMDeviceUpdateCallback3,
userArgument As Object)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- updateCallbackImplementation
- Application-defined callback, Direct3DRMDeviceUpdateCallback3.
- userArgument
- Private data that was passed to the update callback.
Error Values
For a list of possible error values, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.FindPreferredTextureFormat
Direct3DRMDevice3
Finds a texture format that meets the user criteria and that the underlying Immediate Mode device supports. For optimal performance of the texture cache, use this method to choose the pixel format of texture surfaces.
Syntax
object.FindPreferredTextureFormat(bitDepth As CONST_DDBITDEPTHFLAGS, flags As CONST_D3DRMFPTFFLAGS, ddpf As DDPIXELFORMAT)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- CONST_DDBITDEPTHFLAGS
- Requested texture format bit depth. Specify zero to indicate that any bit depth is acceptable. Specify other values, using a logical combination of one or more of the following Microsoft® DirectDraw® bit-depth flags.
- DDBD_4
- DDBD_8
- DDBD_16
- DDBD_24
- DDBD_32
- flags
- One or more values from the CONST_D3DRMFPTFFLAGS enumerated type.
- ddpf
- Variable to receive the texture format.
Error Values
If an error occurs, this method returns one of the following values.
This method returns D3DRMERR_TEXTUREFORMATNOTFOUND if it does not find an acceptable format.
Direct3DRMDevice3.GetBufferCount
Direct3DRMDevice3
Retrieves the value set in a call to the Direct3DRMDevice3.SetBufferCount method.
Syntax
object.GetBufferCount( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns the number of buffers—one for single-buffering, two for double-buffering, and so on.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
Direct3DRMDevice3.GetColorModel
Direct3DRMDevice3
Retrieves the color model of a device.
Syntax
object.GetColorModel( ) As CONST_D3DCOLORMODEL
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns a value from the CONST_D3DCOLORMODEL enumerated type that describes the Direct3D color model (RGB or monochrome). For more information on the CONST_D3DCOLORMODEL enumerated type and its possible settings, see CONST_D3DCOLORMODEL in Further Reading.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
Direct3DRMDevice3.GetDirect3DDevice3
Direct3DRMDevice3
Retrieves a Direct3DDevice3 Immediate Mode device.
Syntax
object.GetDirect3DDevice3( ) As Direct3DDevice3
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns a Direct3DDevice3 Immediate Mode device object.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
Remarks
The Direct3DDevice3 device will support the Microsoft DirectX® DrawPrimitive interface and execute buffers and is required for progressive meshes and for alpha blending and sorting of transparent objects.
Direct3DRMDevice3.GetDither
Direct3DRMDevice3
Retrieves the dither flag for the device.
Syntax
object.GetDither( ) As CONST_DBOOLFLAGS
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns –1 if the dither flag is set, or zero otherwise.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.GetHeight
Direct3DRMDevice3
Retrieves the height of a device. This method is a convenience function.
Syntax
object.GetHeight( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns the height, in pixels.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
Direct3DRMDevice3.GetQuality
Direct3DRMDevice3
Retrieves the rendering quality for the device.
Syntax
object.GetQuality( ) As CONST_D3DRMRENDERQUALITY
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns one or more of the values from the CONST_D3DRMRENDERQUALITY enumerated type.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error 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), lighting type (on or off), and fill mode (point, wire frame, or solid).
After this method returns the quality, q, you can query to determine if lighting is on,
((q And D3DRMLIGHT_MASK) = D3DRMLIGHT_ON), query to determine shading use,((q And D3DRMSHADE_MASK)= D3DRMSHADE_PHONG), and query to determine fill use,((q And D3DRMFILL_MASK)=D3DRMFILL_SOLID).
See Also
Direct3DRMDevice3.GetRenderMode
Direct3DRMDevice3
Retrieves the current transparency flags.
Syntax
object.GetRenderMode( ) As CONST_D3DRMRENDERMODEFLAGS
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns a value from the CONST_D3DRMRENDERMODEFLAGS enumerated type.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.GetShades
Direct3DRMDevice3
Retrieves the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.
Syntax
object.GetShades( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns the number of shades.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.GetTextureQuality
Direct3DRMDevice3
Retrieves the current texture quality parameter for the device. Texture quality is relevant only for an RGB device.
Syntax
object.GetTextureQuality( ) As CONST_D3DRMTEXTUREQUALITY
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns one of the members of the CONST_D3DRMTEXTUREQUALITY enumerated type.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.GetTrianglesDrawn
Direct3DRMDevice3
Retrieves the number of triangles drawn to a device since its creation. This method is a convenience function.
Syntax
object.GetTrianglesDrawn( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns the number of triangles.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
Remarks
The number of triangles includes those that were passed to the renderer but were not drawn because they were back-facing (facing away from the camera). The number does not include triangles that were rejected for lying outside the viewing frustum.
Direct3DRMDevice3.GetViewports
Direct3DRMDevice3
Constructs an Direct3DRMViewportArray object that represents the viewports currently constructed from the device.
Syntax
object.GetViewports( ) As Direct3DRMViewportArray
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns a Direct3DRMViewportArray object if the call succeeds.
Error Values
For a list of possible return codes, see Direct3D Retained Mode Error Values.
Direct3DRMDevice3.GetWidth
Direct3DRMDevice3
Retrieves the width of a device. This method is a convenience function.
Syntax
object.GetWidth( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns the width of the device, in pixels.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
Direct3DRMDevice3.GetWireframeOptions
Direct3DRMDevice3
Retrieves the wire-frame options of a given device.
Syntax
object.GetWireframeOptions( ) As CONST_D3DRMWIREFRAMEFLAGS
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Return Value
Returns a value from the CONST_D3DRMWIREFRAMEFLAGS enumerated type.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
Direct3DRMDevice3.SetBufferCount
Direct3DRMDevice3
Sets the number of buffers being used by the application.
Syntax
object.SetBufferCount(count As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- count
- Number of buffers—one for single-buffering, two for double-buffering, and so on. The default value is one, which is correct only for a single-buffered window operation.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error 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
Direct3DRMDevice3.SetDither
Direct3DRMDevice3
Sets the dither flag for the device.
Syntax
object.SetDither(ditherEnabled As CONST_DBOOLFLAGS)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- ditherEnabled
- New dithering mode for the device. Specify D_TRUE to enable dithering; otherwise, specify D_FALSE. The default is D_TRUE.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.SetQuality
Direct3DRMDevice3
Sets the rendering quality of a device.
Syntax
object.SetQuality(q As CONST_D3DRMRENDERQUALITY)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- q
- One or more of the values from the CONST_D3DRMRENDERQUALITY enumerated type.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error 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, wire frame, or solid).
The shade mode, lighting type, and fill mode, are specified with members of the CONST_D3DRMRENDERQUALITY enumeration.
You can set the quality of a Direct3DRMProgressiveMesh or Direct3DRMMeshBuilder3 object with their respective SetQuality methods. By default, the quality of these objects is D3DRMRENDER_GOURAUD. Note that D3DRMRENDER_GOURAUD is equal to D3DRMLIGHT_ON or D3DRMFILL_SOLID or D3DRMSHADE_GOURAUD.
Tip: Gouraud shading gets better performance on progressive mesh objects that change level of detail often or quickly.
Direct3D Retained Mode renders an object at the lowest quality setting based on the device and the 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.
These rules apply to Direct3DRMMeshBuilder3 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
Direct3DRMDevice3.SetRenderMode
Direct3DRMDevice3
Sets the transparency mode, which determines how transparent objects will be rendered.
Syntax
object.SetRenderMode(flags As CONST_D3DRMRENDERMODEFLAGS)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- flags
- One or more values from the CONST_D3DRMRENDERMODEFLAGS enumerated type, indicating the transparency mode.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.SetShades
Direct3DRMDevice3
Sets the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.
Syntax
object.SetShades(numShades As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- numShades
- New number of shades. This parameter must be a power of two. The default is 32.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.SetTextureQuality
Direct3DRMDevice3
Sets the texture quality for the device.
Syntax
object.SetTextureQuality(d As CONST_D3DRMTEXTUREQUALITY)
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
- d
- One of the members of the CONST_D3DRMTEXTUREQUALITY enumerated type. The default is D3DRMTEXTURE_NEAREST.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMDevice3.Update
Direct3DRMDevice3
Copies the image that has been rendered to the display. It also provides a heartbeat function to the device driver, letting it know when to update the image.
Syntax
object.Update( )
Parts
- object
- Object expression that resolves to a Direct3DRMDevice3 object.
Error Values
For a list of possible error codes, see Direct3D Retained Mode Error Values.
Remarks
Each call to this method causes the system to call an application-defined callback interface, D3DRMDeviceUpdateCallback3. To add a callback, use the Direct3DRMDevice3.AddUpdateCallback method.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.