IDirect3DRMDevice3
Applications use the IDirect3DRMDevice3, IDirect3DRMDevice2, and IDirect3DRMDevice interfaces to interact with the output device. For a conceptual overview, see Output Devices.
IDirect3DRMDevice3 contains all the methods in the older IDirect3DRMDevice2 and IDirect3DRMDevice interfaces, but adds the FindPreferredTextureFormat method to select a texture format based on certain criteria and also adds four methods that eliminate redundant state changes (setting a state to a value equal to its current value): GetStateChangeOptions, LightStateChange, RenderStateChange, and SetStateChangeOptions.
IDirect3DRMDevice2 contains all the methods in IDirect3DRMDevice, plus: two additional methods that enable you to control transparency, GetRenderMode and SetRenderMode; one additional initialization method, InitFromSurface; and two changed methods, GetDirect3DDevice2 and InitFromD3D2, which get and initialize an IDirect3DRMDevice2 object rather than an IDirect3DRMDevice object.
When you create the IDirect3DRMDevice3 or IDirect3DRMDevice2 interface from the IDirect3DRM3 or IDirect3DRM2 interface, respectively, or initialize either interface using its respective InitFromClipper, InitFromD3D2, or InitFromSurface IDirect3DRMDevice3 methods, the interface works with an IDirect3DDevice3 or IDirect3DDevice2 Immediate Mode device, respectively. The IDirect3DDevice3 and IDirect3DDevice2 devices support the DrawPrimitive interface, as well as execute buffers, and are required for progressive meshes, for alpha blending and sorting of transparent objects. When you create the old IDirect3DRMDevice interface from the IDirect3DRM interface, the IDirect3DRMDevice Retained Mode interface works with an IDirect3DDevice Immediate Mode device.
The InitFromClipper and InitFromSurface methods use the IDirect3DRM3::CreateDevice method to create a Direct3DRMDevice3 object.
The InitFromD3D2 method uses an IDirect3D2 Immediate Mode object and an IDirect3DDevice2 Immediate Mode device to initialize an IDirect3DDevice2 Direct3D Retained Mode device.
You can still query between the IDirect3DRMDevice3, IDirect3DRMDevice2, and IDirect3DRMDevice interfaces. The main difference is in how the underlying Immediate Mode device is created.
The methods of the IDirect3DRMDevice3 interface can be organized into the following groups:
| Buffer counts | GetBufferCount |
| SetBufferCount | |
| Color models | GetColorModel |
| Dithering | GetDither |
| SetDither | |
| Eliminating Redundant State Changes | GetStateChangeOptions |
| LightStateChange | |
| RenderStateChange | |
| SetStateChangeOptions | |
| Initialization | Init |
| InitFromClipper | |
| InitFromD3D2 | |
| InitFromSurface | |
| Miscellaneous | GetDirect3DDevice2 |
| GetHeight | |
| GetTrianglesDrawn | |
| GetViewports | |
| GetWidth | |
| GetWireframeOptions | |
| Update | |
| Notifications | AddUpdateCallback |
| DeleteUpdateCallback | |
| Rendering quality | GetQuality |
| SetQuality | |
| Shading | GetShades |
| SetShades | |
| Textures | FindPreferredTextureFormat |
| GetTextureQuality | |
| SetTextureQuality | |
| Transparency | GetRenderMode |
| SetRenderMode |
The IDirect3DRMDevice3 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 IDirect3DRMDevice3 interface inherits the following methods from the IDirect3DRMObject interface:
| AddDestroyCallback |
| Clone |
| DeleteDestroyCallback |
| GetAppData |
| GetClassName |
| GetName |
| SetAppData |
| SetName |
The Direct3DRMDevice3 object is obtained by calling the IDirect3DRM3::CreateDevice method.
IDirect3DRMDevice3::AddUpdateCallback
IDirect3DRMDevice3
Adds a callback function that alerts the application when a change occurs to the device. The system uses this callback function when the application uses the IDirect3DRMDevice3::Update method.
Syntax
HRESULT AddUpdateCallback(
D3DRMDEVICE3UPDATECALLBACK d3drmUpdateProc,
LPVOID arg
);
Parameters
- d3drmUpdateProc
- Pointer to an application-defined callback function, D3DRMDEVICE3UPDATECALLBACK.
- arg
- Pointer to private data to be passed to the update callback function.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return values, see Direct3D Retained Mode Return Values.
Remarks
IDirect3DRMDevice2::AddUpdateCallback and IDirect3DRMDevice::AddUpdateCallback take a D3DRMUPDATECALLBACK type callback for the d3drmUpdateProc parameter. With DirectX version 6.0, IDirect3DRMDevice3 introduced the newer D3DRMDEVICE3UPDATECALLBACK callback.
See Also
IDirect3DRMDevice3::DeleteUpdateCallback, IDirect3DRMDevice3::Update, D3DRMDEVICE3UPDATECALLBACK
IDirect3DRMDevice3::DeleteUpdateCallback
IDirect3DRMDevice3
Removes an update callback function that was added by using the IDirect3DRMDevice3::AddUpdateCallback method.
Syntax
HRESULT DeleteUpdateCallback(
D3DRMDEVICE3UPDATECALLBACK d3drmUpdateProc,
LPVOID arg
);
Parameters
- d3drmUpdateProc
- Pointer to an application-defined callback function, D3DRMDEVICE3UPDATECALLBACK.
- arg
- Pointer to private data that was passed to the update callback function.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return values, see Direct3D Retained Mode Return Values.
Remarks
IDirect3DRMDevice2::DeleteUpdateCallback and IDirect3DRMDevice::DeleteUpdateCallback take a D3DRMUPDATECALLBACK type callback for the d3drmUpdateProc parameter. With DirectX version 6.0, IDirect3DRMDevice3 introduced the newer D3DRMDEVICE3UPDATECALLBACK callback.
See Also
IDirect3DRMDevice3::AddUpdateCallback, IDirect3DRMDevice3::Update, D3DRMDEVICE3UPDATECALLBACK
IDirect3DRMDevice3::FindPreferredTextureFormat
IDirect3DRMDevice3
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 function to choose the pixel format of texture surfaces.
Syntax
HRESULT FindPreferredTextureFormat( DWORD dwBitDepths, DWORD dwFlags, LPDDPIXELFORMAT lpDDPF);
Parameters
- dwBitDepths
- 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 DirectDraw bit-depth flags.
- DDBD_4
- DDBD_8
- DDBD_16
- DDBD_24
- DDBD_32
- dwFlags
- Flags that specify additional requirements. Specify zero to use the default preferences. Other valid values must be a logical combination of one or more of the following values.
- D3DRMFPTF_ALPHA
- The returned texture format must have an alpha channel.
- D3DRMFPTF_NOALPHA
- The returned texture format must not have an alpha channel. Omit both the D3DRMFPTF_ALPHA and D3DRMFPTF_NOALPHA flags to indicate that the absence of an alpha channel is preferred, but not required.
- D3DRMFPTF_PALETTIZED
- The returned texture format must be palettized.
- D3DRMFPTF_NOTPALETTIZED
- The returned texture format must not be palettized. Omit both the D3DRMFPTF_PALETTIZED and D3DRMFPTF_NOTPALETTIZED flags to indicate that the absence of a palette is preferred, but not required.
- lpDDPF
- Pointer to receive the texture format.
Return Value
Returns one of the following values.
D3DRMERR_TEXTUREFORMATNOTFOUND DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK FindPreferredTextureFormat returns D3DRMERR_TEXTUREFORMATNOTFOUND if the does not find an acceptable format.
Remarks
This method was introduced with DirectX version 6.0.
IDirect3DRMDevice3::GetBufferCount
IDirect3DRMDevice3
Retrieves the value set in a call to the IDirect3DRMDevice3::SetBufferCount method.
Syntax
DWORD GetBufferCount( );
Return Value
Returns the number of buffers—one for single-buffering, two for double-buffering, and so on.
IDirect3DRMDevice3::GetColorModel
IDirect3DRMDevice3
Retrieves the color model of a device.
Syntax
D3DCOLORMODEL GetColorModel( );
Return Value
Returns a value from the D3DCOLORMODEL enumerated type that describes the Direct3D color model (RGB or monochrome).
See Also
IDirect3DRMDevice3::GetDirect3DDevice2
IDirect3DRMDevice3
Retrieves a pointer to an IDirect3DDevice2 Immediate Mode device.
Syntax
HRESULT GetDirect3DDevice2(
LPDIRECT3DDEVICE2 *lplpD3DDevice
);
Parameters
- lplpD3DDevice
- Address of a pointer that is initialized with a pointer to an IDirect3DDevice2 Immediate Mode device object.
Return Value
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.
IDirect3DRMDevice3::GetDither
IDirect3DRMDevice3
Retrieves the dither flag for the device.
Syntax
BOOL GetDither( );
Return Value
Returns TRUE if the dither flag is set, or FALSE otherwise.
See Also
IDirect3DRMDevice3::GetHeight
IDirect3DRMDevice3
Retrieves the height, in pixels, of a device. This method is a convenience function.
Syntax
DWORD GetHeight( );
Return Value
Returns the height.
IDirect3DRMDevice3::GetQuality
IDirect3DRMDevice3
Retrieves the rendering quality for the device.
Syntax
D3DRMRENDERQUALITY GetQuality( );
Return Value
Returns one or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY enumerated type.
See Also
IDirect3DRMDevice3::GetRenderMode
IDirect3DRMDevice3
Retrieves the current transparency flags.
Syntax
DWORD GetRenderMode( );
Return Value
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_DISABLESORTEDALPHAZWRITE 32 D3DRMRENDERMODE_LIGHTINMODELSPACE 8 D3DRMRENDERMODE_SORTEDTRANSPARENCY 2 D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 16
See Also
IDirect3DRMDevice3::GetShades
IDirect3DRMDevice3
Retrieves the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.
Syntax
DWORD GetShades( );
Return Value
Returns the number of shades.
See Also
IDirect3DRMDevice3::GetStateChangeOptions
IDirect3DRMDevice3
Retrieves the state change options flags associated with a render or light state. See Eliminating Redundant State Changes for more details.
Syntax
HRESULT GetStateChangeOptions(
DWORD dwStateClass,
DWORD dwStateNum,
LPDWORD pdwFlags
);
Parameters
- dwStateClass
- Class of states to which this state belongs. The value can be D3DRMSTATECHANGE_LIGHT or D3DRMSTATECHANGE_RENDER.
- dwStateNum
- Appropriate D3DRENDERSTATE or D3DLIGHTSTATE number. A zero value indicates that all states of the given class should be affected.
- pdwFlags
- Pointer to the options flags. Contains one of the following values:
- D3DRMSTATECHANGE_NONVOLATILE
- D3DRMSTATECHANGE_VOLATILE
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
Remarks
This method was introduced with DirectX version 6.0.
The following example code gets the options on the texture handle render state.
lpDirect3DRMDev3->GetStateChangeOptions(D3DRMSTATECHANGE_RENDER, D3DRENDERSTATE_TEXTUREHANDLE, &dwFlags);
See Also
IDirect3DRMDevice3::GetTextureQuality
IDirect3DRMDevice3
Retrieves the current texture quality parameter for the device. Texture quality is relevant only for an RGB device.
Syntax
D3DRMTEXTUREQUALITY GetTextureQuality( );
Return Value
Returns one of the members of the D3DRMTEXTUREQUALITY enumerated type.
See Also
IDirect3DRMDevice3::GetTrianglesDrawn
IDirect3DRMDevice3
Retrieves the number of triangles drawn to a device since its creation. This method is a convenience function.
Syntax
DWORD GetTrianglesDrawn( );
Return Value
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 (facing away from the camera). The number does not include triangles that were rejected for lying outside of the viewing frustum.
IDirect3DRMDevice3::GetViewports
IDirect3DRMDevice3
Constructs a Direct3DRMViewportArray object that represents the viewports currently constructed from the device.
Syntax
HRESULT GetViewports(
LPDIRECT3DRMVIEWPORTARRAY *lplpViewports
);
Parameters
- lplpViewports
- Address of a pointer that is initialized with a valid Direct3DRMViewportArray object if the call succeeds.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
IDirect3DRMDevice3::GetWidth
IDirect3DRMDevice3
Retrieves the width, in pixels, of a device. This method is a convenience function.
Syntax
DWORD GetWidth( );
Return Value
Returns the width of the device, in pixels.
IDirect3DRMDevice3::GetWireframeOptions
IDirect3DRMDevice3
Retrieves the wire-frame options of a given device.
Syntax
DWORD GetWireframeOptions( );
Return Value
Returns a bitwise or one of the following values.
- D3DRMWIREFRAME_CULL
- The backfacing faces are not drawn.
- D3DRMWIREFRAME_HIDDENLINE
- Wire-frame-rendered lines are obscured by nearer objects.
IDirect3DRMDevice3::Init
IDirect3DRMDevice3
Not implemented on the Microsoft® Windows® platform.
Syntax
HRESULT Init(
ULONG width,
ULONG height
);
IDirect3DRMDevice3::InitFromClipper
IDirect3DRMDevice3
Initializes an IDirect3DDevice2 device from a specified DirectDrawClipper object using IDirect3DRM3::CreateDevice.
Syntax
HRESULT InitFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height
);
Parameters
- lpDDClipper
- Pointer to 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 Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
IDirect3DRMDevice3::InitFromD3D2
IDirect3DRMDevice3
Initializes an IDirect3DRMDevice2 Retained Mode device from an IDirect3D2 Immediate Mode object and an IDirect3DDevice2 Immediate Mode device.
Syntax
HRESULT InitFromD3D2(
LPDIRECT3D2 lpD3D,
LPDIRECT3DDEVICE2 lpD3DIMDev
);
Parameters
- lpD3D
- Pointer to the IDirect3D2 Immediate Mode object to use to initialize the Retained Mode device.
- lpD3DIMDev
- Pointer to the IDirect3DDevice2 Immediate Mode device to use to initialize the Retained Mode device.
Return Value
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.
IDirect3DRMDevice3::InitFromSurface
IDirect3DRMDevice3
Initializes a IDirect3DDevice2 device from a specified DirectDraw surface, using the IDirect3DRM3::CreateDevice method.
Syntax
HRESULT InitFromSurface(
LPGUID lpGUID,
LPDIRECTDRAW lpDD,
LPDIRECTDRAWSURFACE lpDDSBack
);
Parameters
- lpGUID
- Pointer to the globally unique identifier (GUID) that identifies the Direct3D device driver to use.
- lpDD
- Pointer to the interface of a DirectDraw object that created the DirectDrawSurface.
- lpDDSBack
- Pointer to the interface of a DirectDrawSurface back buffer onto which the device will render.
Return Value
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 methods and execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.
IDirect3DRMDevice3::LightStateChange
IDirect3DRMDevice3
Changes a light state or informs Direct3D Retained Mode of a change to a render state. If the D3DRMSTATECHANGE_NONVOLATILE flag is associated with the render state, Retained Mode eliminates redundant changes to the state made by using IDirect3DRMDevice3 (it won't set the state to a value equal to its current value). See Eliminating Redundant State Changes for more details.
Syntax
HRESULT LightStateChange(
DWORD dwStateNum,
DWORD dwVal,
DWORD dwFlags
);
Parameters
- dwStateNum
- Appropriate D3DLIGHTSTATE number.
- dwVal
- New value of the state.
- dwFlags
- Flag that indicates whether Retained Mode should update the cache only. If this flag is set to D3DRMSTATECHANGE_UPDATEONLY, only the value held in the internal cache is updated. You can use D3DRMSTATECHANGE_UPDATEONLY to indicate a state change.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
Remarks
This method was introduced with DirectX version 6.0.
The following code sets the material handle light state, eliminating redundant changes if the D3DRMSTATECHANGE_NONVOLATILE flag has been associated with the state.
lpDirect3DRMDev3->LightStateChange(D3DLIGHTSTATE_MATERIAL, hMat, 0);The following indicates a change to the fog mode.
lpDirect3DRMDev3->LightStateChange(D3DLIGHTSTATE_FOGMODE, D3DFOG_NONE, D3DRMSTATECHANGE_UPDATEONLY);
See Also
IDirect3DRMDevice3::RenderStateChange
IDirect3DRMDevice3
Changes a render state or indicates a change to a render state. If the D3DRMSTATECHANGE_NONVOLATILE flag is associated with the render state, Retained Mode eliminates redundant changes to the state made by using IDirect3DRMDevice3 (it won't set the state to a value equal to its current value). See Eliminating Redundant State Changes for more details.
Syntax
HRESULT RenderStateChange(
DWORD dwStateNum,
DWORD dwVal,
DWORD dwFlags
);
Parameters
- dwStateNum
- Appropriate D3DRENDERSTATE number.
- dwVal
- New value of the state.
- dwFlags
- Flag that indicates whether to update the cache only. If this flag is set to D3DRMSTATECHANGE_UPDATEONLY, only the value held in the internal cache is updated. You can use D3DRMSTATECHANGE_UPDATEONLY to indicate a change made to the state.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
Remarks
This method was introduced with DirectX version 6.0.
The following code sets the fill mode render state, eliminating redundant changes if the D3DRMSTATECHANGE_NONVOLATILE flag has been associated with the state.
lpDirect3DRMDev3->RenderStateChange(D3DRENDERSTATE_FILLMODE, D3DFILL_SOLID, 0);The following code indicates a change to the texture handle render state.
lpDirect3DRMDev3->RenderStateChange(D3DRENDERSTATE_TEXTUREHANDLE, hTex, D3DRMSTATECHANGE_UPDATEONLY);
See Also
IDirect3DRMDevice3::SetBufferCount
IDirect3DRMDevice3
Sets the number of buffers currently being used by the application.
Syntax
HRESULT SetBufferCount(
DWORD dwCount
);
Parameters
- dwCount
- 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.
Return Value
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
IDirect3DRMDevice3::SetDither
IDirect3DRMDevice3
Sets the dither flag for the device.
Syntax
HRESULT SetDither(
BOOL bDither
);
Parameters
- bDither
- New dithering mode for the device. The default is TRUE.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMDevice3::SetQuality
IDirect3DRMDevice3
Sets the rendering quality of a device.
Syntax
HRESULT SetQuality (
D3DRMRENDERQUALITY rqQuality
);
Parameters
- rqQuality
- One or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY enumerated type. The default setting is D3DRMRENDER_FLAT.
Return Value
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, wire frame, 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 or Direct3DRMMeshBuilder3 object with their respective SetQuality methods. By default, the quality of these objects is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).
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.
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 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
IDirect3DRMDevice3::SetRenderMode
IDirect3DRMDevice3
Sets the transparency mode. The mode type determines how transparent objects will be rendered. The default mode renders transparent objects with stippled transparency.
Syntax
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. Stippled (or "screen door") transparency is achieved by replacing some of the pixels in one image with pixels from the other image (as if you are seeing one image through a screen door painted with the second image).
In addition, flags can have one or more of the following values:
- D3DRMRENDERMODE_BLENDEDTRANSPARENCY (dwFlags = 1) sets the transparency mode to alpha blending. Blended transparency is achieved by combining two images by adding the color values at each pixel.
- D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE (dwFlags = 32) specifies that no depth information will be written to the z-buffer when drawing sorted, transparent objects.
- D3DRMRENDERMODE_LIGHTINMODELSPACE (dwFlags = 8). Reserved. Do not use.
- 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. Transparent polygons in external visuals or user visuals are not sorted. Only native Direct3D Retained Mode visuals (such as D3DRMMesh objects and D3DRMMeshBuilder objects) are sorted.
- D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR (dwFlags = 16) enables more realistic specular lights that depend both on the light direction and the viewer's location. Previous versions of DirectX Foundation only supported flat specular light that did not take into account the viewer's location. If this flag is set, Direct3D Retained Mode uses the D3DLIGHT2 structure to define the light type when calling Direct3D Immediate Mode's IDirect3DLight::SetLight. If this flag is not set, Direct3D Retained Mode uses the D3DLIGHT structure, and you will get the lighting behavior of previous versions of DirectX.
Return Value
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.
The D3DRMRENDERMODE_SORTEDTRANSPARENCY turns on the per triangle back-to-front sorting of alpha polygons. Only native Direct3D Retained Mode visuals (such as D3DRMMesh objects and D3DRMMeshBuilder objects) are sorted. You cannot add triangles from external visuals to the sorted list.
The D3DRMRENDERMODE_BLENDEDTRANSPARENCY flag turns on true alpha blending as opposed to stippled alpha. In true alpha blending, the pixels of overlapping triangles are blended together. In stippled alpha, some pixels from the triangle in front are not drawn revealing the triangle below (this is also called screen-door transparency). When doing stippled alpha, it is not necessary to sort triangles since the result is the same no matter what order you render the triangles in.
The only valid parameters to SetSortMode are 0 (stippled alpha with no sorting), BLENDEDTRANSPARENCY (true alpha with no sorting), and both BLENDEDTRANSPARENCY and SORTEDTRANSPARENCY (per triangle sorted true alpha).
See Also
IDirect3DRMDevice3::SetShades
IDirect3DRMDevice3
Sets the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.
Syntax
HRESULT SetShades(
DWORD ulShades
);
Parameters
- ulShades
- New number of shades. This parameter must be a power of two. The default is 32.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMDevice3::SetStateChangeOptions
IDirect3DRMDevice3
Changes the options flags associated with one or more render or light states. The default value for all render and light states is D3DRMSTATECHANGE_VOLATILE. If the D3DRMSTATECHANGE_NONVOLATILE flag is associated with a render or light state, Direct3D Retained Mode caches the value and eliminates redundant changes (it won't set the state to a value equal to its current value). You must, however, indicate when you change the state with either the LightStateChange or RenderStateChange method. See Eliminating Redundant State Changes for more details.
Syntax
HRESULT SetStateChangeOptions(
DWORD dwStateClass,
DWORD dwStateNum,
DWORD dwFlags
);
Parameters
- dwStateClass
- Class of states to which this state belongs. The value can be D3DRMSTATECHANGE_LIGHT or D3DRMSTATECHANGE_RENDER.
- dwStateNum
- Appropriate D3DRENDERSTATE or D3DLIGHTSTATE number. A zero value indicates that all states of the given class should be affected.
- dwFlags
- Options flags. One of the following values:
- D3DRMSTATECHANGE_NONVOLATILE
- D3DRMSTATECHANGE_VOLATILE
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
Remarks
This method was introduced with DirectX version 6.0.
The following code sets the D3DRMSTATECHANGE_NONVOLATILE flag on all render states.
lpDirect3DRMDev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER, 0, D3DRMSTATECHANGE_NONVOLATILE);The following code sets the D3DRMSTATECHANGE_VOLATILE flag on the texture handle render state.
lpDirect3DRMDev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER, D3DRENDERSTATE_TEXTUREHANDLE, D3DRMSTATECHANGE_VOLATILE);
See Also
IDirect3DRMDevice3::SetTextureQuality
IDirect3DRMDevice3
Sets the texture quality for the device.
Syntax
HRESULT SetTextureQuality(
D3DRMTEXTUREQUALITY tqTextureQuality
);
Parameters
- tqTextureQuality
- One of the members of the D3DRMTEXTUREQUALITY enumerated type. The default is D3DRMTEXTURE_NEAREST.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMDevice3::Update
IDirect3DRMDevice3
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
HRESULT Update( );
Return Value
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, D3DRMDEVICE3UPDATECALLBACK. To add a callback function, use the IDirect3DRMDevice3::AddUpdateCallback method.
IDirect3DRMDevice2::Update and IDirect3DRMDevice::Update cause the system to call a D3DRMUPDATECALLBACK type callback. With DirectX version 6.0, IDirect3DRMDevice3 introduced the newer D3DRMDEVICE3UPDATECALLBACK callback.
See Also
IDirect3DRMDevice3::AddUpdateCallback, D3DRMDEVICE3UPDATECALLBACK
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.