IDirect3DRMFace2

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.

IDirect3DRMFace2::AddVertex

IDirect3DRMFace2

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.

IDirect3DRMFace2::AddVertexAndNormalIndexed

IDirect3DRMFace2

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.

IDirect3DRMFace2::GetColor

IDirect3DRMFace2

Retrieves the color of a Direct3DRMFace2 object.

Syntax

D3DCOLOR GetColor( );

Return Value

Returns the color.

See Also

IDirect3DRMFace2::SetColor

IDirect3DRMFace2::GetMaterial

IDirect3DRMFace2

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

IDirect3DRMFace2::SetMaterial

IDirect3DRMFace2::GetNormal

IDirect3DRMFace2

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.

IDirect3DRMFace2::GetTexture

IDirect3DRMFace2

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

IDirect3DRMFace2::SetTexture

IDirect3DRMFace2::GetTextureCoordinateIndex

IDirect3DRMFace2

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.

IDirect3DRMFace2::GetTextureCoordinates

IDirect3DRMFace2

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.

IDirect3DRMFace2::GetVertex

IDirect3DRMFace2

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.

IDirect3DRMFace2::GetVertexCount

IDirect3DRMFace2

Retrieves the number of vertices in a Direct3DRMFace2 object.

Syntax

int GetVertexCount( );

Return Value

Returns the number of vertices.

IDirect3DRMFace2::GetVertexIndex

IDirect3DRMFace2

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.

IDirect3DRMFace2::GetVertices

IDirect3DRMFace2

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.

IDirect3DRMFace2::SetColor

IDirect3DRMFace2

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

IDirect3DRMFace2::GetColor

IDirect3DRMFace2::SetColorRGB

IDirect3DRMFace2

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.

IDirect3DRMFace2::SetMaterial

IDirect3DRMFace2

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

IDirect3DRMFace2::GetMaterial

IDirect3DRMFace2::SetTexture

IDirect3DRMFace2

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

IDirect3DRMFace2::GetTexture

IDirect3DRMFace2::SetTextureCoordinates

IDirect3DRMFace2

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.

IDirect3DRMFace2::SetTextureTopology

IDirect3DRMFace2

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.

Color	GetColor
	SetColor
	SetColorRGB

Materials	GetMaterial
	SetMaterial

Textures	GetTexture
	GetTextureCoordinateIndex
	GetTextureCoordinates
	SetTexture
	SetTextureCoordinates
	SetTextureTopology

Vertices and normals	AddVertex
	AddVertexAndNormalIndexed
	GetNormal
	GetVertex
	GetVertexCount
	GetVertexIndex
	GetVertices