IDirect3DRMMaterial2
Applications use the methods of the IDirect3DRMMaterial2 interface to interact with material objects.
A material defines how a surface reflects light. A material has two components: an emissive property (whether it emits light) and a specular property, whose brightness is determined by a power setting. The value of the power determines the sharpness of the reflected highlights, with a value of 5 giving a metallic appearance and higher values giving a more plastic appearance.
An application can control the emission of a material by using the GetEmissive and SetEmissive methods, the specular component by using the GetSpecular and SetSpecular methods, and the power by using the GetPower and SetPower methods.
Microsoft DirectX version 6.0 introduced the IDirect3DRMMaterial2 interface. IDirect3DRMMaterial2 extends the older IDirect3DRMMaterial interface that it replaces by adding the GetAmbient and SetAmbient methods to allow finer control over material properties. With IDirect3DRMMaterial the ambient color could not be modified and was always equal to the face color. An IDirect3DRMMaterial2 object uses the object's face color as the ambient color until SetAmbient is called. For a history of the Direct3D Retained Mode interfaces, see Interface Changes.
The methods of the IDirect3DRMMaterial2 interface can be organized into the following groups:
| Ambient | GetAmbient |
| SetAmbient | |
| Emission | GetEmissive |
| SetEmissive | |
| Power for | GetPower |
| specular exponent | SetPower |
| Specular | GetSpecular |
| SetSpecular | |
The IDirect3DRMMaterial2 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 IDirect3DRMMaterial2 interface inherits the following methods from the IDirect3DRMObject interface:
| AddDestroyCallback |
| Clone |
| DeleteDestroyCallback |
| GetAppData |
| GetClassName |
| GetName |
| SetAppData |
| SetName |
The Direct3DRMMaterial object is obtained by using the IDirect3DRM3::CreateMaterial method.
IDirect3DRMMaterial2::GetAmbient
IDirect3DRMMaterial2
Retrieves the current ambient value for the material.
Syntax
HRESULT GetAmbient(
LPD3DVALUE lpdvRed,
LPD3DVALUE lpdvGreen,
LPD3DVALUE lpdvBlue);
Parameters
- lpdvRed
- Will be filled in with the red component of the ambient color.
- lpdvGreen
- Will be filled in with the green component of the ambient color.
- lpdvBlue
- Will be filled in with the blue component of the ambient color.
Return Value
Returns one of the following values:
DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK
Remarks
This method was introduced with DirectX version 6.0.
IDirect3DRMMaterial2::GetEmissive
IDirect3DRMMaterial2
Retrieves the setting for the emissive property of a material. The setting of this property is the color and intensity of the light the object emits.
Syntax
HRESULT GetEmissive(
D3DVALUE *lpr,
D3DVALUE *lpg,
D3DVALUE *lpb
);
Parameters
- lpr, lpg, and lpb
- Addresses that will contain the red, green, and blue components of the emissive color when the method returns.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMMaterial2::GetPower
IDirect3DRMMaterial2
Retrieves the power used for the specular exponent in the given material.
Syntax
D3DVALUE GetPower( );
Return Value
Returns the value specifying the power of the specular exponent.
See Also
IDirect3DRMMaterial2::GetSpecular
IDirect3DRMMaterial2
Retrieves the color of the specular highlights of a material.
Syntax
HRESULT GetSpecular(
D3DVALUE *lpr,
D3DVALUE *lpg,
D3DVALUE *lpb
);
Parameters
- lpr, lpg, and lpb
- Addresses that will contain the red, green, and blue components of the color of the specular highlights when the method returns.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMMaterial2::SetAmbient
IDirect3DRMMaterial2
Sets the ambient value for the material. The default is the diffuse color. The diffuse color is the diffuse (or matte) reflective color of the surface.
Syntax
HRESULT SetAmbient(
D3DVALUE dvRed,
D3DVALUE dvGreen,
D3DVALUE dvBlue);
Parameters
- dvRed
- The red component of the ambient color.
- dvGreen
- The green component of the ambient color.
- dvBlue
- The blue component of the ambient color.
Return Value
Returns one of the following values:
DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK
Remarks
This method was introduced with DirectX version 6.0.
IDirect3DRMMaterial2::SetEmissive
IDirect3DRMMaterial2
Sets the emissive property of a material.
Syntax
HRESULT SetEmissive(
D3DVALUE r,
D3DVALUE g,
D3DVALUE b
);
Parameters
- r, g, and b
- Red, green, and blue components of the emissive color.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Remarks
This method is also used to add an emissive property key to a Direct3DRMMaterialInterpolator object.
See Also
IDirect3DRMMaterial2::SetPower
IDirect3DRMMaterial2
Sets the power used for the specular exponent in a material.
Syntax
HRESULT SetPower(
D3DVALUE rvPower
);
Parameters
- rvPower
- New specular exponent.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Remarks
This method is also used to add a spectral power key to a Direct3DRMMaterialInterpolator object.
See Also
IDirect3DRMMaterial2::SetSpecular
IDirect3DRMMaterial2
Sets the color of the specular highlights for a material.
Syntax
HRESULT SetSpecular(
D3DVALUE r,
D3DVALUE g,
D3DVALUE b
);
Parameters
- r, g, and b
- Red, green, and blue components of the color of the specular highlights.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Remarks
This method is also used to add a spectral color key to a Direct3DRMMaterialInterpolator object.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.