Applications use the methods of the IDirect3DRMFace2 interface to interact with a face. A face represents a single polygon in a mesh. An application can set the color, texture, and material of the face by using the IDirect3DRMFace2::SetColor, IDirect3DRMFace2::SetColorRGB, IDirect3DRMFace2::SetTexture, and IDirect3DRMFace2::SetMaterial methods.
Faces are constructed from vertices by using the IDirect3DRMFace2::AddVertex and IDirect3DRMFace2::AddVertexAndNormalIndexed methods. An application can read the vertices of a face by using the IDirect3DRMFace2::GetVertices and IDirect3DRMFace2::GetVertex methods.
In IDirect3DRMFace2, the SetTexture method can now specify a texture whose width and height are not a power of two.
The methods of the IDirect3DRMFace2 interface can be organized into the following groups:
Color | GetColor |
SetColor | |
SetColorRGB | |
Materials | GetMaterial |
SetMaterial | |
Textures | GetTexture |
GetTextureCoordinateIndex | |
GetTextureCoordinates | |
SetTexture | |
SetTextureCoordinates | |
SetTextureTopology | |
Vertices and normals | AddVertex |
AddVertexAndNormalIndexed | |
GetNormal | |
GetVertex | |
GetVertexCount | |
GetVertexIndex | |
GetVertices |
The IDirect3DRMFace2 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 IDirect3DRMFace2 interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback |
Clone |
DeleteDestroyCallback |
GetAppData |
GetClassName |
GetName |
SetAppData |
SetName |
The Direct3DRMFace2 object is obtained by using the IDirect3DRM3::CreateFace method.
Adds a vertex to a Direct3DRMFace2 object.
Syntax
HRESULT AddVertex(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);
Parameters
- x, y, and z
- The x, y, and z components of the new vertex position.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Adds a vertex and a normal to a Direct3DRMFace2 object, using an index for the vertex and an index for the normal in the containing mesh builder. The face, vertex, and normal must already be part of a Direct3DRMMeshBuilder3 object .
Syntax
HRESULT AddVertexAndNormalIndexed(
DWORD vertex,
DWORD normal
);
Parameters
- vertex and normal
- Indexes of the vertex and normal to add.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the color of a Direct3DRMFace2 object.
Syntax
D3DCOLOR GetColor( );
Return Value
Returns the color.
See Also
Retrieves the material of a Direct3DRMFace2 object.
Syntax
HRESULT GetMaterial(
LPDIRECT3DRMMATERIAL *lplpMaterial
);
Parameters
- lplpMaterial
- Address of the pointer to the Direct3DRMMaterial object applied to the face.
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
Retrieves the normal vector of a Direct3DRMFace2 object.
Syntax
HRESULT GetNormal(
D3DVECTOR *lpNormal
);
Parameters
- lpNormal
- Address of a D3DVECTOR structure that will be filled with the normal vector of the face.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the Direct3DRMTexture object applied to a Direct3DRMFace2 object.
Syntax
HRESULT GetTexture(
LPDIRECT3DRMTEXTURE *lplpTexture
);
Parameters
- lplpTexture
- Address of a variable that will be filled with a pointer to the texture applied to the face.
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
Retrieves the index of the vertex for texture coordinates in the face's mesh. You pass in the face-relative vertex index in the which parameter, and this method returns the corresponding mesh-relative vertex index.
Syntax
int GetTextureCoordinateIndex(
DWORD which
);
Parameters
- which
- Index within the face of the vertex whose coorresponding mesh vertex index is being retrieved.
Return Value
Returns the face's mesh-relative vertex index.
Retrieves the texture coordinates of a vertex in a Direct3DRMFace2 object.
Syntax
HRESULT GetTextureCoordinates(
DWORD index,
D3DVALUE *lpU,
D3DVALUE *lpV
);
Parameters
- index
- Index of the vertex.
- lpU and lpV
- Addresses of variables that are filled with the texture coordinates of the vertex.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the position and normal of a vertex in a Direct3DRMFace2 object.
Syntax
HRESULT GetVertex(
DWORD index,
D3DVECTOR *lpPosition,
D3DVECTOR *lpNormal
);
Parameters
- index
- Index of the vertex.
- lpPosition and lpNormal
- Addresses of D3DVECTOR structures that will be filled with the position and normal of the vertex, respectively.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the number of vertices in a Direct3DRMFace2 object.
Syntax
int GetVertexCount( );
Return Value
Returns the number of vertices.
Retrieves the index of the vertex in the face's mesh. You pass in the face-relative vertex index in the which parameter, and this method returns the corresponding mesh-relative vertex index.
Syntax
int GetVertexIndex (
DWORD which
);
Parameters
- which
- Index within the face of the vertex whose coorresponding mesh vertex index is being retrieved.
Return Value
Returns the mesh-relative vertex index.
Retrieves the position and normal vector of each vertex in a Direct3DRMFace2 object.
Syntax
HRESULT GetVertices(
DWORD *lpdwVertexCount,
D3DVECTOR *lpPosition,
D3DVECTOR *lpNormal
);
Parameters
- lpdwVertexCount
- Address of a variable that contains the number of vertices. If both lpPosition and lpNormal are NULL, lpdwVertexCount is filled with the number of vertices that will be retrieved. This parameter cannot be NULL.
- lpPosition and lpNormal
- Arrays of D3DVECTOR structures that will be filled with the positions and normal vectors of the vertices, respectively. If both of these parameters are NULL, the method will fill the lpdwVertexCount parameter with the number of vertices that will be retrieved.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets a Direct3DRMFace2 object to a given color.
Syntax
HRESULT SetColor(
D3DCOLOR color
);
Parameters
- color
- Color to set. Be sure to set the alpha component as well as the red, green, and blue color components or your objects might not be visible. The RGBA_MAKE DirectX macro allows you to specify these values.
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
Sets a Direct3DRMFace2 object to a given color.
Syntax
HRESULT SetColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);
Parameters
- red, green, and blue
- The red, green, and blue components of the color.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the material of a Direct3DRMFace2 object.
Syntax
HRESULT SetMaterial(
LPDIRECT3DRMMATERIAL lpD3DRMMaterial
);
Parameters
- lpD3DRMMaterial
- Address of the material.
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
Sets the texture of a Direct3DRMFace2 object.
Syntax
HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);
Parameters
- lpD3DRMTexture
- Address of the texture.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Remarks
Starting with DirectX Foundation 6, the width and height of the texture are not required to be a power of two.
See Also
Sets the texture coordinates of a specified vertex in a Direct3DRMFace2 object.
Syntax
HRESULT SetTextureCoordinates(
DWORD vertex,
D3DVALUE u,
D3DVALUE v
);
Parameters
- vertex
- Index of the vertex to be set. For example, if the face were a triangle, the possible vertex indices would be 0, 1, and 2.
- u and v
- Texture coordinates to assign to the specified vertex.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the texture topology of a Direct3DRMFace2 object.
Syntax
HRESULT SetTextureTopology(
BOOL cylU,
BOOL cylV
);
Parameters
- cylU and cylV
- Specify whether the texture has a cylindrical topology in the u and v dimensions.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Remarks
Several interfaces provide SetTextureTopology methods. See IDirect3DRMeshBuilder3::SetTextureTopology for more information about the relationship between the SetTextureTopology methods, and for more information about the purpose of the cylU and cylV parameters.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.