Direct3DRMFace2

Applications use the methods of the Direct3DRMFace2 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 Direct3DRMFace2.SetColor, Direct3DRMFace2.SetColorRGB, Direct3DRMFace2.SetTexture, and Direct3DRMFace2.SetMaterial methods.

Faces are constructed from vertices by using the Direct3DRMFace2.AddVertex and Direct3DRMFace2.AddVertexAndNormalIndexed methods. An application can read the vertices of a face by using the Direct3DRMFace2.GetVertices and Direct3DRMFace2.GetVertex methods.

In Direct3DRMFace2, the SetTexture method can now specify a texture whose width and height are not a power of two.

The methods of the Direct3DRMFace2 interface can be organized into the following groups.

Color GetColor
SetColor
SetColorRGB

Materials GetMaterial
SetMaterial

Textures GetTexture
GetTextureCoordinateIndex
GetTextureCoordinates

GetTextureTopology
SetTexture
SetTextureCoordinates
SetTextureTopology

Vertices and normals AddVertex
AddVertexAndNormalIndexed
GetNormal
GetVertex
GetVertexCount
GetVertexIndex
GetVertices

The Direct3DRMFace2 interface inherits the following methods from the Direct3DRMObject interface.

The Direct3DRMFace2 object is obtained by using the Direct3DRM3.CreateFace method.

Direct3DRMFace2.AddVertex

Direct3DRMFace2

Adds a vertex to a Direct3DRMFace2 object.

Syntax

object.AddVertex(x As Single,
  y As Single,
  z As Single)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

x, y, and z
The x, y, and z components of the new vertex position.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.AddVertexAndNormalIndexed

Direct3DRMFace2

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

object.AddVertexAndNormalIndexed(vertexIndex As Long,
  normalIndex As Long)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

vertexIndex and normal
Indexes of the vertex and normal to add.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.GetColor

Direct3DRMFace2

Retrieves the color of a Direct3DRMFace2 object.

Syntax

object.GetColor( ) As Long

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

Return Value

Returns the color.

Error Values

For a list of possible error codes, see Direct3D Retained Mode Error Values.

See Also

Direct3DRMFace2.SetColor

Direct3DRMFace2.GetMaterial

Direct3DRMFace2

Retrieves the material of a Direct3DRMFace2 object.

Syntax

object.GetMaterial( ) As Direct3DRMMaterial2

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

Return Value

Returns the Direct3DRMMaterial object applied to the face.

Error Values

For a list of possible error codes, see Direct3D Retained Mode Error Values.

See Also

Direct3DRMFace2.SetMaterial

Direct3DRMFace2.GetNormal

Direct3DRMFace2

Retrieves the normal vector of a Direct3DRMFace2 object.

Syntax

object.GetNormal(val As D3DVECTOR)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

val
D3DVECTOR type that will be filled with the normal vector of the face.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.GetTexture

Direct3DRMFace2

Retrieves the Direct3DRMTexture3 object applied to a Direct3DRMFace2 object.

Syntax

object.GetTexture( ) As Direct3DRMTexture3

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

Return Value

Returns a Direct3DRMTexture3 object.

Error Values

For a list of possible error codes, see Direct3D Retained Mode Error Values.

See Also

Direct3DRMFace2.SetTexture

Direct3DRMFace2.GetTextureCoordinateIndex

Direct3DRMFace2

Retrieves the index of the vertex for texture coordinates in the face's mesh.

Syntax

object.GetTextureCoordinateIndex(which As Long) As Long

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

which
Index within the face of the vertex whose corresponding mesh vertex index is being retrieved.

Return Value

Returns the face's mesh-relative vertex index.

Error Values

For a list of possible error codes, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.GetTextureCoordinates

Direct3DRMFace2

Retrieves the texture coordinates of a vertex in a Direct3DRMFace2 object.

Syntax

object.GetTextureCoordinates(Vertex As Long,
  u As Single,
  v As Single)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

Vertex
Index of the vertex.
u and v
Variables that are filled with the texture coordinates of the vertex.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.GetTextureTopology

Direct3DRMFace2

Retrieves the texture topology of a Direct3DRMFace2 object.

Syntax

object.GetTextureTopology(u As Long,
  v As Long)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

u and v
Variables filled with texture coordinates.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.GetVertex

Direct3DRMFace2

Retrieves the position and normal of a vertex in a Direct3DRMFace2 object.

Syntax

object.GetVertex(idx As Long,
  vert As D3DVECTOR,
  norm As D3DVECTOR)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

idx
Index of the vertex.
vert and norm
D3DVECTOR types that will be filled with the position and normal of the vertex, respectively.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.GetVertexCount

Direct3DRMFace2

Retrieves the number of vertices in a Direct3DRMFace2 object.

Syntax

object.GetVertexCount( ) As Long

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

Return Value

Returns the number of vertices.

Error Values

For a list of possible error codes, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.GetVertexIndex

Direct3DRMFace2

Retrieves the index of the vertex in the face's mesh.

Syntax

object.GetVertexIndex(which As Long) As Long

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

which
Index within the face of the vertex whose corresponding mesh vertex index is being retrieved.

Return Value

Returns the mesh-relative vertex index.

Error Values

For a list of possible error codes, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.GetVertices

Direct3DRMFace2

Retrieves the position and normal vector of each vertex in a Direct3DRMFace2 object.

Syntax

object.GetVertices(vertexCount As Long,
  coord() As D3DVECTOR,
  normals() As D3DVECTOR)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

vertexCount
Variable filled with the number of vertices. This parameter cannot be NOTHING.
coord and normals
An array of D3DVECTOR types that will be filled with the positions and normal vectors of the vertices, respectively.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

Use GetVertexCount to determine vertexCount and make both coord and normals that size.

Direct3DRMFace2.SetColor

Direct3DRMFace2

Sets a Direct3DRMFace2 object to a given color.

Syntax

object.SetColor(c As Long)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

c
Color to set. Make sure to set the alpha component as well as the red, green, and blue color components or your objects might not be visible. Colors are represented by a Long, consisting of 4 bytes. The high byte is the alpha component and the subsequent bytes define red, green, and blue. Use CreateColorRGBA from the DirectX7 object to more easily construct a color or use SetColorRGB if you only want full alpha.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

See Also

Direct3DRMFace2.GetColor

Direct3DRMFace2.SetColorRGB

Direct3DRMFace2

Sets the red, green, and blue color components of a Direct3DRMFace2 object.

Syntax

object.SetColorRGB(r As Single,
  g As Single,
  b As Single)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

r, g, and b
Red, green, and blue components of the color.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.SetMaterial

Direct3DRMFace2

Sets the material of a Direct3DRMFace2 object.

Syntax

object.SetMaterial(ref As Direct3DRMMaterial2)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

ref
Direct3DRMMaterial object to use as the material.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

See Also

Direct3DRMFace2.GetMaterial

Direct3DRMFace2.SetTexture

Direct3DRMFace2

Sets the texture of a Direct3DRMFace2 object.

Syntax

object.SetTexture(ref As Direct3DRMTexture3)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

ref
Direct3DRMTexture3 object to use as the texture.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error 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

Direct3DRMFace2.GetTexture

Direct3DRMFace2.SetTextureCoordinates

Direct3DRMFace2

Sets the texture coordinates of a specified vertex in a Direct3DRMFace2 object.

Syntax

object.SetTextureCoordinates(Vertex As Long,
  u As Single,
  v As Single)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

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.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMFace2.SetTextureTopology

Direct3DRMFace2

Sets the texture topology of a Direct3DRMFace2 object.

Syntax

object.SetTextureTopology(wrap_u As CONST_DBOOLFLAGS,
  wrap_v As CONST_DBOOLFLAGS)

Parts

object

Object expression that resolves to a Direct3DRMFace2 object.

wrap_u and wrap_v
Specify D_TRUE for either or both of these parameters if you want the texture to have a cylindrical topology in the u- and v-dimensions, respectively; otherwise, specify D_FALSE.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

Several interfaces provide SetTextureTopology methods. See Direct3DRMeshBuilder3.SetTextureTopology for more information about the relationship between the SetTextureTopology methods, and for more information about the purpose of the wrap_u and wrap_v parameters.

Color	GetColor
	SetColor
	SetColorRGB

Materials	GetMaterial
	SetMaterial

Textures	GetTexture
	GetTextureCoordinateIndex
	GetTextureCoordinates
	GetTextureTopology
	SetTexture
	SetTextureCoordinates
	SetTextureTopology

Vertices and normals	AddVertex
	AddVertexAndNormalIndexed
	GetNormal
	GetVertex
	GetVertexCount
	GetVertexIndex
	GetVertices