Direct3DRMMeshBuilder3

Applications use the methods of the Direct3DRMMeshBuilder3 interface to interact with mesh objects. For more information about meshes, see Direct3DRMMesh.

You can add vertices and faces individually to a mesh by using the Direct3DRMMeshBuilder3.AddVertex, AddFace, and AddFaces methods. You can retrieve an individual face with the GetFace method.

You can set normals (which should be unit vectors), or normals can be calculated by averaging the face normals of the surrounding faces by using the GenerateNormals method.

Direct3DRMMeshBuilder3 methods retrieve normals, the number of normals, faces, one or more vertices, and the state (enabled or disabled) of the meshbuilder. This interface enables you to set vertices and normals, and to create and retrieve new submeshes and parent meshes of the meshbuilder. Direct3DRMMeshBuilder3 also enables the application to add new triangles (as opposed to general polygons) to the Direct3DRMMeshBuilder3 object and, in the process, implicitly create new faces by using the AddTriangles method.

In Retained Mode 6.x, you can create a Direct3DRMMeshBuilder3 object by using the Direct3DRM3 interface, in which case the Direct3DRMMeshBuilder3 object uses the Immediate Mode DrawPrimitive interface for its implementation.

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

Color	GetColorSource
	SetColor
	SetColorRGB
	SetColorSource
Creation	GetBox
Faces	AddFace
	AddFaces
	AddFacesIndexed
	CreateFace
	DeleteFace
	GetFaceCount
	GetFaceDataSize
	GetFace
	GetFaces
Loading	LoadFromFile
Meshes	AddMesh
	CreateMesh
Miscellaneous	AddFrame
	AddMeshBuilder
	AddTriangles
	Empty
	Enable
	GetEnable
	Optimize
	Save
	ScaleMesh
	SetMaterial
	Translate
Normals	AddNormal
	GenerateNormals
	GetNormals
	GetNormalCount
	SetNormal
Perspective	GetPerspective
	SetPerspective
Rendering quality	GetQuality
	SetQuality
SubMeshes	CreateSubMesh
	DeleteSubMesh
	GetParentMesh
	GetSubMeshCount
	GetSubMeshes
Textures	GetTextureCoordinates
	SetTexture
	SetTextureCoordinates
	SetTextureTopology
Vertices	AddVertex
	GetGeometry
	GetVertex
	GetVertexColor
	GetVertexCount
	SetVertex
	SetVertexColor
	SetVertexColorRGB

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

• AddDestroyCallback
• CloneObject
• DeleteDestroyCallback
• GetAppData
• GetClassName
• GetName
• SetAppData
• SetName

Obtain the Direct3DRMMeshBuilder3 object by using the Direct3DRM3.CreateMeshBuilder method.

Direct3DRMMeshBuilder3.AddFace

---

Direct3DRMMeshBuilder3

Adds a face to a Direct3DRMMeshBuilder3 object.

Syntax

object.AddFace(f As Direct3DRMFace2)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

f

Direct3DRMFace2 object being added.

Error Values

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

Remarks

Any one face can exist in only one mesh at a time.

Direct3DRMMeshBuilder3.AddFaces

---

Direct3DRMMeshBuilder3

Adds faces to a Direct3DRMMeshBuilder3 object.

Syntax

object.AddFaces(vc As Long,
  vertexArray() As D3DVECTOR,
  nc As Long,
  normalArray() As D3DVECTOR,
  data() As Long) As Direct3DRMFaceArray

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

vc

Number of vertices.

vertexArray

An array of D3DVECTOR types that store the vertex positions.

nc

Number of normals.

normalArray

An array of D3DVECTOR types that store the normal positions.

data

For each face, this parameter should contain a vertex count followed by the indexes into the vertices array. If nc is not zero, this parameter should contain a vertex count followed by pairs of indexes, with the first index of each pair indexing into the array of vertices, and the second indexing into the array of normals. The list of indexes must terminate with a zero.

Return Value

Returns a Direct3DRMFaceArray interface that will be filled with the newly created faces.

Error Values

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

Direct3DRMMeshBuilder3.AddFacesIndexed

---

Direct3DRMMeshBuilder3

Enables a number of faces to be created on the meshbuilder that use pre-existing vertices and normals (optional).

Syntax

object.AddFacesIndexed(flags As CONST_D3DRMADDFACESFLAGS,
  indexArray() As Long) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

flags

A value from the CONST_D3DRMADDFACESFLAGS enumerated type that specifies how normal indexes should be handled. If the value is D3DRMADDFACES_DEFAULT, indexes of pre-existing normals must be specified in the indexArray parameter. Otherwise, the normal with the corresponding index will be used automatically for each vertex.

indexArray

Contiguous array of integer tuples that specify the following for each face.

• Number of vertices n, where n is greater than or equal to 3
• Vertex indexes
• Normal indexes (optional)

The following table shows the relationship between the value for the flags parameter and the required face tuple format for the indexArray parameter.

flags	Required face tuple format
D3DRMADDFACES_DEFAULT	{<n>, <vIndex0>, <nIndex0>,...,<vIndex n-1>, <nIndex n-1>}
D3DRMADDFACES_VERTICESONLY	{<n>, <vIndex0>,...,<vIndex n-1>}

The vIndex and nIndex values are required to index into previously existing vertices and normals within the meshbuilder. The array of tuples should be terminated with the value 0.

Return Value

Returns the index of the first new face added to the meshbuilder.

Error Values

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

Direct3DRMMeshBuilder3.AddFrame

---

Direct3DRMMeshBuilder3

Adds the contents of a frame to a Direct3DRMMeshBuilder3 object.

Syntax

object.AddFrame(f As Direct3DRMFrame3)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

f

Direct3DRMFrame3 object whose contents are being added.

Error Values

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

Remarks

This method adds a copy of all the mesh and meshbuilder faces from the specified frame hierarchy (which can be a subbranch of a larger frame hierarchy) to the Direct3DRMMeshBuilder3 object. The frame tree is specified by passing the root frame. Faces are added with the position and orientation of their containing frame factored in. Transforms of the specified root frame are ignored, even if the root frame has a parent.

The source frame is not modified or referenced by this operation.

Direct3DRMMeshBuilder3.AddMesh

---

Direct3DRMMeshBuilder3

Adds a mesh to a Direct3DRMMeshBuilder3 object.

Syntax

object.AddMesh(m As Direct3DRMMesh)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

m

Direct3DRMMesh object being added.

Error Values

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

Direct3DRMMeshBuilder3.AddMeshBuilder

---

Direct3DRMMeshBuilder3

Adds the contents of a Direct3DRMMeshBuilder3 object to a Direct3DRMMeshBuilder3 object. All sub-meshbuilders underneath the source Direct3DRMMeshBuilder3 object and the faces they contain are duplicated beneath the target Direct3DRMMeshBuilder3 object.

Syntax

object.AddMeshBuilder(meshbuilder As Direct3DRMMeshBuilder3,
  flags As CONST_D3DRMADDMESHBUILDERFLAGS)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

meshbuilder

Direct3DRMMeshBuilder3 object whose contents are being added.

flags

One or more values from the CONST_D3DRMADDMESHBUILDERFLAGS enumerated type, indicating the copying options.

Error Values

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

Remarks

The source Direct3DRMMeshBuilder3 object is not modified or referenced by this operation.

Direct3DRMMeshBuilder3.AddNormal

---

Direct3DRMMeshBuilder3

Adds a normal to a Direct3DRMMeshBuilder3 object.

Syntax

object.AddNormal(x As Single,
  y As Single,
  z As Single) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

x, y, and z

The x-, y-, and z-components of the direction of the new normal.

Return Value

Returns the index of the normal.

Error Values

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

Direct3DRMMeshBuilder3.AddTriangles

---

Direct3DRMMeshBuilder3

Enables the application to add new triangles (as opposed to general polygons) to the Direct3DRMMeshBuilder3 object, and in the process, to implicitly create new faces.

Syntax

object.AddTriangles(flags As Long,
  format As CONST_D3DRMADDTRIANGLESVT,
  vertexCount As Long,
  data As Any)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

flags

Must be zero.

format

Logical combination of values from the CONST_D3DRMADDTRIANGLESVT enumerated type that describes the format of the vertex data. If all valid values are included, the vertex data is described by the following D3DRMFLEXVERTEX user-defined type.

Syntax

Type D3DRMFLEXVERTEX
  IType As Long
  color As Long
  normal As D3DVECTOR
  position As D3DVECTOR
  tu As Single
  tv As Single
End Type

Dim verts(100) As D3DRMFLEXVERTEX

AddTriangles(D3DRMFVF_TYPE Or D3DRMFVF_NORMAL Or D3DRMFVF_COLOR Or D3DRMFVF_TEXTURECOORDS, 100, verts(0))

Valid values include a logical combination of any of the following values, which indicate which members of the D3DRMFLEXVERTEX type to include in the description for each element. The position member is always present.

D3DRMFVF_TYPE

Include the IType member. If the IType member is present, it must include one of the following:

D3DRMVERTEX_LIST

Starts a new list or is a member of a previously started list. If the previous vertex (or the vertex previous to that) was not marked with this flag, the following vertices must be marked with this flag until at least one triangle is formed.

D3DRMVERTEX_STRIP

Forms a new triangle in strip format with the previous two vertices.

D3DRMVERTEX_FAN

Forms a new triangle with the previous vertex and the first vertex in the fan.

D3DRMFVF_NORMAL

Include the normal member.

D3DRMFVF_COLOR

Include the color member.

D3DRMFVF_TEXTURECOORDS

Include the tu and tv members.

vertexCount

Vertex number.

data

Data described by format.

Error Values

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

Remarks

This method provides flexibility to the application in describing the triangles. The triangles are described by a set of vertices. Each vertex must have a position, but can optionally have none or any of the following: normal, texture coordinates, or color.

The following table shows the appropriate IType flag for each vertex in the following diagram.

Vertex number	IType flag
0	D3DRMVERTEX_STRIP
1	D3DRMVERTEX_STRIP
2	D3DRMVERTEX_STRIP
3	D3DRMVERTEX_STRIP
4	D3DRMVERTEX_STRIP
5	D3DRMVERTEX_FAN
6	D3DRMVERTEX_FAN
7	D3DRMVERTEX_FAN
8	D3DRMVERTEX_LIST
9	D3DRMVERTEX_LIST
10	D3DRMVERTEX_LIST
11	D3DRMVERTEX_LIST
12	D3DRMVERTEX_LIST
13	D3DRMVERTEX_LIST

Direct3DRMMeshBuilder3.AddVertex

---

Direct3DRMMeshBuilder3

Adds a vertex to a Direct3DRMMeshBuilder3 object.

Syntax

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

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

x, y, and z

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

Return Value

Returns the index of the vertex.

Error Values

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

Direct3DRMMeshBuilder3.CreateFace

---

Direct3DRMMeshBuilder3

Creates a new face with no vertices and adds it to a Direct3DRMMeshBuilder3 object.

Syntax

object.CreateFace( ) As Direct3DRMFace2

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns a Direct3DRMFace2 object that will be filled with the newly created face.

Error Values

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

Direct3DRMMeshBuilder3.CreateMesh

---

Direct3DRMMeshBuilder3

Creates a new mesh from a Direct3DRMMeshBuilder3 object.

Syntax

object.CreateMesh( ) As Direct3DRMMesh

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns a Direct3DRMMesh object.

Error Values

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

Direct3DRMMeshBuilder3.CreateSubMesh

---

Direct3DRMMeshBuilder3

Creates a new submesh for the current Direct3DRMMeshBuilder3 object.

Syntax

object.CreateSubMesh( ) As Direct3DRMMeshBuilder3

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns a Direct3DRMMeshBuilder3 object.

Error Values

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

Remarks

A submesh is similar to a meshbuilder object in that it supports the Direct3DRMMeshBuilder3 interface, and can itself have submeshes. The difference between submeshes and meshbuilders is that all submeshes share the vertices and normals with the greatest ancestor in the chain of submeshes. Meshbuilders do not share vertices and normals.

See Also

Direct3DRMMeshBuilder3.DeleteSubMesh, Direct3DRMMeshBuilder3.GetSubMesh, Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.DeleteFace

---

Direct3DRMMeshBuilder3

Deletes a face from the Direct3DRMMeshBuilder3 object.

Syntax

object.DeleteFace(face As Direct3DRMFace2)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

face

Interface of a Direct3DRMFace2 object to remove from the Direct3DRMMeshBuilder3 object.

Error Values

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

Direct3DRMMeshBuilder3.DeleteSubMesh

---

Direct3DRMMeshBuilder3

Deletes a submesh. The submesh must be an immediate child of the current Direct3DRMMeshBuilder3 object.

Syntax

object.DeleteSubMesh(mesh As Direct3DRMMeshBuilder3)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

mesh

Direct3DRMMeshBuilder3 interface of the submesh to delete.

Error Values

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

See Also

Direct3DRMMeshBuilder3.CreateSubMesh, Direct3DRMMeshBuilder3.GetSubMesh and Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.Empty

---

Direct3DRMMeshBuilder3

Removes all faces, vertices, and normals from the Direct3DRMMeshBuilder3 object.

Syntax

object.Empty( )

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Error Values

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

Direct3DRMMeshBuilder3.Enable

---

Direct3DRMMeshBuilder3

Specifies whether this Direct3DRMMeshBuilder3 object should be enabled or disabled for rendering and picking.

Syntax

object.Enable(flags As CONST_D3DRMADDMESHBUILDERFLAGS)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

flags

One or more values from the CONST_D3DRMMESHBUILDERENABLEFLAGS enumerated type indicating whether rendering and picking are enabled.

Error Values

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

See Also

Direct3DRMMeshBuilder3.GetEnable

Direct3DRMMeshBuilder3.GenerateNormals

---

Direct3DRMMeshBuilder3

Processes the Direct3DRMMeshBuilder3 object and generates normals for each vertex in a mesh by averaging the face normals for each face that shares the vertex. New normals are generated if the faces sharing a vertex have an angle between them greater than the crease angle.

Syntax

object.GenerateNormals(angle As Single,
  flags As CONST_D3DRMGENERATENORMALSFLAGS)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

angle

Least angle, in radians, that faces can have between them and have a new normal generated.

flags

One or more of the values from the CONST_D3DRMGENERATENORMALSFLAGS enumerated type.

Error Values

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

Remarks

If you specify the D3DRMGENERATENORMALS_PRECOMPACT flag, the precompact pass searches all the vertices in the mesh and merges any that are the same. This is a good way of compacting a mesh that has been loaded. Some meshes have multiple vertices if they have multiple normals at that vertex. This is not necessary in Direct3D Retained Mode. Specifying this flag is the way to get rid of the multiple vertices.

After compacting, the normals are generated. The edges between faces are examined, and if the angle the faces make at the edge is less than the crease angle, the face normals are averaged to generate the vertex normal. If the angle is greater than the crease angle, a new normal is generated. Note that a new vertex is not generated.

Direct3DRMMeshBuilder3.GetBox

---

Direct3DRMMeshBuilder3

Retrieves the bounding box containing a Direct3DRMMeshBuilder3 object. The bounding box gives the minimum and maximum model coordinates in each dimension.

Syntax

object.GetBox(retV As D3DRMBOX)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

retV

D3DRMBOX type that will be filled with the bounding box coordinates.

Error Values

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

Direct3DRMMeshBuilder3.GetColorSource

---

Direct3DRMMeshBuilder3

Retrieves the color source of a Direct3DRMMeshBuilder3 object. The color source can be either a face or a vertex.

Syntax

object.GetColorSource( ) As CONST_D3DRMCOLORSOURCE

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns a member of the CONST_D3DRMCOLORSOURCE enumerated type.

Error Values

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

See Also

Direct3DRMMeshBuilder3.SetColorSource

Direct3DRMMeshBuilder3.GetEnable

---

Direct3DRMMeshBuilder3

Retrieves a value that indicates whether this Direct3DRMMeshBuilder3 object should be enabled or disabled.

Syntax

object.GetEnable( ) As CONST_D3DRMADDMESHBUILDERFLAGS

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns a value from the CONST_D3DRMMESHBUILDERENABLEFLAGS enumerated type indicating the current enable status of this Direct3DRMMeshBuilder3 object.

Error Values

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

See Also

Direct3DRMMeshBuilder3.Enable

Direct3DRMMeshBuilder3.GetFace

---

Direct3DRMMeshBuilder3

Retrieves a single face of a Direct3DRMMeshBuilder3 object.

Syntax

object.GetFace(id As Long) As Direct3DRMFace2

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

id

ID of the mesh face to be retrieved. The face must already be part of a Direct3DRMMeshBuilder3 object.

Return Value

Returns a Direct3DRMFace2 interface that is filled with the face.

Error Values

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

Direct3DRMMeshBuilder3.GetFaceCount

---

Direct3DRMMeshBuilder3

Retrieves the number of faces in a Direct3DRMMeshBuilder3 object.

Syntax

object.GetFaceCount( ) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns the number of faces.

Error Values

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

Direct3DRMMeshBuilder3.GetFaceDataSize

---

Direct3DRMMeshBuilder3

Retrieves the size of the face data array for a Direct3DRMMeshBuilder3 object.

Syntax

object.GetFaceDataSize( ) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns the size of the face data array argument required by GetGeometry.

Error Values

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

Direct3DRMMeshBuilder3.GetFaces

---

Direct3DRMMeshBuilder3

Retrieves the faces of a Direct3DRMMeshBuilder3 object.

Syntax

object.GetFaces( ) As Direct3DRMFaceArray

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns a Direct3DRMFaceArray object that is filled with the faces.

Error Values

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

Direct3DRMMeshBuilder3.GetGeometry

---

Direct3DRMMeshBuilder3

Retrieves the vertices, normals, and face data for a Direct3DRMMeshBuilder3 object.

Syntax

object.GetGeometry(vertexArray() As D3DVECTOR,
  normalArray() As D3DVECTOR,
  faceData() As Long) 

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

vertexArray

Array of D3DVECTOR types that will contain the vertices for the Direct3DRMMeshBuilder3 object. Use GetVertexCount to determine the minimum size for this array.

normalArray

Array of D3DVECTOR types that will contain the normals for the Direct3DRMMeshBuilder3 object. Use GetNormalCount to determine the size of the array.

faceData

Face data for the Direct3DRMMeshBuilder3 object. This data is in the same format as specified in the Direct3DRMMeshBuilder3.AddFaces method except that it is null-terminated. Call GetFaceDataSize to determine the size of the array.

Error Values

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

Direct3DRMMeshBuilder3.GetNormal

---

Direct3DRMMeshBuilder3

Retrieves a normal vector.

Syntax

object.GetNormal(index As Long,
  desc As D3DVECTOR)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

index

Index of the normal to return.

desc

D3DVECTOR type that will be filled in with the x-, y-, and z-coordinates of the normal.

Error Values

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

Direct3DRMMeshBuilder3.GetNormalCount

---

Direct3DRMMeshBuilder3

Retrieves the number of normals in a Direct3DRMMeshBuilder3 object.

Syntax

object.GetNormalCount( ) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns the number of normals in the Direct3DRMMeshBuilder3 object.

Error Values

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

See Also

Direct3DRMMeshBuilder3.GetNormal and Direct3DRMMeshBuilder3.SetNormal

Direct3DRMMeshBuilder3.GetParentMesh

---

Direct3DRMMeshBuilder3

Retrieves a parent mesh of this Direct3DRMMeshBuilder3 object.

Syntax

object.GetParentMesh(
    flags As CONST_D3DRMPARENTINGFLAGS) 
    As Direct3DRMMeshBuilder3

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

flags

One or more values from the CONST_D3DRMPARENTINGFLAGS enumerated type, defining which Direct3DRMMeshBuilder3 object to retrieve.

Return Value

Returns a Direct3DRMMeshBuilder3 object.

Error Values

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

See Also

Direct3DRMMeshBuilder3.GetSubMesh

Direct3DRMMeshBuilder3.GetPerspective

---

Direct3DRMMeshBuilder3

Determines whether perspective correction is on for a Direct3DRMMeshBuilder3 object.

Syntax

object.GetPerspective( ) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns –1 if perspective correction is on, or zero otherwise.

Error Values

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

Direct3DRMMeshBuilder3.GetQuality

---

Direct3DRMMeshBuilder3

Retrieves the rendering quality of a Direct3DRMMeshBuilder3 object.

Syntax

object.GetQuality( ) As CONST_D3DRMRENDERQUALITY

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns a value from the CONST_D3DRMRENDERQUALITY enumerated type that specifies the rendering quality of the mesh.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error 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), lighting type (on or off), and fill mode (point, wire frame, or solid).

See Also

Direct3DRMMeshBuilder3.SetQuality

Direct3DRMMeshBuilder3.GetSubMeshCount

---

Direct3DRMMeshBuilder3

Retrieves the number of submeshes that this Direct3DRMMeshBuilder3 object contains.

Syntax

object.GetSubMeshCount( ) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns the number of submeshes.

Error Values

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

See Also

Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.GetSubMeshes

---

Direct3DRMMeshBuilder3

Retrieves a list of the submeshes that this Direct3DRMMeshBuilder3 object contains.

Syntax

object.GetSubMeshes(count As Long,
  arrayOfMeshBuilders() As Direct3DRMMeshBuilder3)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

count

Number of submeshes expected to be returned. The value pointed to by count receives the number of submeshes actually retrieved.

arrayOfMeshBuilders

Array of Direct3DRMMeshBuilder3 objects containing child submeshes.

Error Values

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

See Also

Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.GetTextureCoordinates

---

Direct3DRMMeshBuilder3

Retrieves the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder3 object.

Syntax

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

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

idx

Index of the vertex.

u and v

Returned texture coordinates of the vertex.

Error Values

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

See Also

Direct3DRMMeshBuilder3.SetTextureCoordinates

Direct3DRMMeshBuilder3.GetVertex

---

Direct3DRMMeshBuilder3

Retrieves a vertex vector.

Syntax

object.GetVertex(id As Long,
  vec As D3DVECTOR)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

id

ID of the vertex to return.

vec

D3DVECTOR type that will be filled with the x-, y-, and z-coordinates of the vertex.

Error Values

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

Direct3DRMMeshBuilder3.GetVertexColor

---

Direct3DRMMeshBuilder3

Retrieves the color of a specified vertex in a Direct3DRMMeshBuilder3 object.

Syntax

object.GetVertexColor(index As Long) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

index

Index of the vertex.

Return Value

Returns the color.

Error Values

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

See Also

Direct3DRMMeshBuilder3.SetVertexColor

Direct3DRMMeshBuilder3.GetVertexCount

---

Direct3DRMMeshBuilder3

Retrieves the number of vertices in a Direct3DRMMeshBuilder3 object.

Syntax

object.GetVertexCount( ) As Long

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Return Value

Returns the number of vertices.

Error Values

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

Direct3DRMMeshBuilder3.LoadFromFile

---

Direct3DRMMeshBuilder3

Loads a Direct3DRMMeshBuilder3 object.

Syntax

object.LoadFromFile(filename As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As Object)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

filename

Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the flags parameter.

id

Object name or position to be loaded. If id is "", you must set the options parameter to D3DRMLOAD_FIRST. Note that Microsoft Visual Basic® will accept an Integer in the id parameter, indicating the position of the item to be loaded, even though a String data type is specified. For example, placing 1 in the id parameter will load the object in the first position.

options

One or more values from the CONST_D3DRMLOADFLAGS enumerated type describing the load options.

loadTextureImplementation

Direct3DRMLoadTextureCallback3 callback interface used to load any textures used by an object that require special formatting. Textures must have a width and length divisible by 2. This parameter can be NOTHING.

userArgument

Application-defined data passed to the callback.

Error Values

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

Remarks

By default, this method loads the first mesh from the source specified in the filename parameter.

This method respects the right-handed and left-handed geometry options as set by Direct3DRM3.SetOptions.

You can load more than one object into a Direct3DRMMeshBuilder3 object by calling its load method multiple times.

Each of the LoadFromFile methods uses a filename parameter to specify the source of the object and an id parameter to identify the object. The system interprets the contents of the filename parameter based on the choice of source flags, and it interprets the contents of the id parameter based on the choice of identifier flags.

The instance flags do not change the interpretation of any of the members. By using the D3DRMLOAD_INSTANCEBYREFERENCE flag, an application can load the same file twice without creating any new objects. If an object does not have a name, setting the D3DRMLOAD_INSTANCEBYREFERENCE flag has the same effect as setting the D3DRMLOAD_INSTANCEBYCOPYING flag—the loader creates each unnamed object as a new one, even if some of the objects are identical.

Direct3DRMMeshBuilder3.Optimize

---

Direct3DRMMeshBuilder3

Optimizes the Direct3DRMMeshBuilder3 object for the current device. This can be an expensive operation.

Syntax

object.Optimize( )

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

Error Values

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

Direct3DRMMeshBuilder3.Save

---

Direct3DRMMeshBuilder3

Saves a Direct3DRMMeshBuilder3 object.

Syntax

object.Save(fname As String,
  xFormat As CONST_D3DRMXOFFORMAT,
  Save As CONST_D3DRMSAVEFLAGS)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

fname

Name of the created file. This file must have the .x file name extension.

xFormat

D3DRMXOF_TEXT value from the CONST_D3DRMXOFFORMAT enumerated type.

Save

One or more values from the CONST_D3DRMSAVEFLAGS enumerated type describing the save options.

Error Values

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

Direct3DRMMeshBuilder3.ScaleMesh

---

Direct3DRMMeshBuilder3

Scales a Direct3DRMMeshBuilder3 object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.

Syntax

object.ScaleMesh(sx As Single,
  sy As Single,
  sz As Single)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

sx, sy, and sz

Scaling factors that are applied along the x-, y-, and z-axes.

Error Values

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

Direct3DRMMeshBuilder3.SetColor

---

Direct3DRMMeshBuilder3

Sets all the faces of a Direct3DRMMeshBuilder3 object to a given color.

Syntax

object.SetColor(col As Long)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

col

Color of the faces. 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.

Direct3DRMMeshBuilder3.SetColorRGB

---

Direct3DRMMeshBuilder3

Sets the red, green, and blue color components of all the faces of a Direct3DRMMeshBuilder3 object.

Syntax

object.SetColorRGB(red As Single,
  green As Single,
  blue As Single)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

red, green, and blue

Red, green, and blue components of the color.

Error Values

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

Direct3DRMMeshBuilder3.SetColorSource

---

Direct3DRMMeshBuilder3

Sets the color source of a Direct3DRMMeshBuilder3 object.

Syntax

object.SetColorSource(val As CONST_D3DRMCOLORSOURCE)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

val

Member of the CONST_D3DRMCOLORSOURCE enumerated type that specifies the new color source to use.

Error Values

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

See Also

Direct3DRMMeshBuilder3.GetColorSource

Direct3DRMMeshBuilder3.SetMaterial

---

Direct3DRMMeshBuilder3

Sets the material of all the faces of a Direct3DRMMeshBuilder3 object.

Syntax

object.SetMaterial(mat As Direct3DRMMaterial2)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

mat

Direct3DRMMaterial2 interface for the Direct3DRMMeshBuilder3 object.

Error Values

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

Direct3DRMMeshBuilder3.SetNormal

---

Direct3DRMMeshBuilder3

Sets the normal vector of a specified vertex in a Direct3DRMMeshBuilder3 object.

Syntax

object.SetNormal(idx As Long,
  x As Single,
  y As Single,
  z As Single)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

idx

Index of the normal to be set.

x, y, and z

The x-, y-, and z-components of the vector to assign to the specified normal.

Error Values

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

Direct3DRMMeshBuilder3.SetPerspective

---

Direct3DRMMeshBuilder3

Enables or disables perspective-correct texture mapping for a Direct3DRMMeshBuilder3 object.

Syntax

object.SetPerspective(perspectiveEnabled As CONST_DBOOLFLAGS)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

perspectiveEnabled

D_TRUE if the mesh should be texture-mapped with perspective correction, or D_FALSE otherwise.

Error Values

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

Direct3DRMMeshBuilder3.SetQuality

---

Direct3DRMMeshBuilder3

Sets the rendering quality of a Direct3DRMMeshBuilder3 object.

Syntax

object.SetQuality(q As CONST_D3DRMRENDERQUALITY)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

q

Member of the CONST_D3DRMRENDERQUALITY enumerated type that specifies the new rendering quality to use.

Error Values

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

Remarks

An object's quality has three components: shade mode (flat or Gouraud; Phong shading is not yet implemented and will default to Gouraud shading), lighting type (on or off), and fill mode (point, wire frame, or solid).

You can set the quality of a device with Direct3DRMDevice3.SetQuality. By default it is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMMeshBuilder3 object with the SetQuality method. By default, a Direct3DRMMeshBuilder3 object's quality is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Tip: Gouraud shading performs better than Phong shading on progressive mesh objects that change their level of detail often or quickly.

Direct3D Retained Mode renders an object at the lowest quality setting based on the device and 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 then 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, then 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

Direct3DRMMeshBuilder3.GetQuality

Direct3DRMMeshBuilder3.SetTexture

---

Direct3DRMMeshBuilder3

Sets the texture of all the faces of a Direct3DRMMeshBuilder3 object.

Syntax

object.SetTexture(tex As Direct3DRMTexture3)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

tex

Required Direct3DRMTexture3 object.

Error Values

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

Direct3DRMMeshBuilder3.SetTextureCoordinates

---

Direct3DRMMeshBuilder3

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

Syntax

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

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

idx

Index of the vertex to set.

u and v

Texture coordinates to assign to the specified mesh vertex.

Error Values

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

See Also

Direct3DRMMeshBuilder3.GetTextureCoordinates

Direct3DRMMeshBuilder3.SetTextureTopology

---

Direct3DRMMeshBuilder3

Sets the texture topology of a Direct3DRMMeshBuilder3 object.

Syntax

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

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

wrap_u and wrap_v

Value indicating the texture topology. 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

The texture topology flags, wrap_u and wrap_v, control the settings of the Direct3D Immediate Mode render states D3DRENDERSTATE_WRAPU and D3DRENDERSTATE_WRAPV. When a wrap flag is set to D_TRUE, the rasterizer will cross from one edge of the texture to the opposite edge (toroidal mapping) if it is the shorter path between two texture coordinates.

Consider a triangle that has v coordinates ranging from 0.1 and 0.9 along one edge. If WRAPV is D_FALSE, nearly the full length of the texture will be rendered along the triangle. If WRAPV is D_TRUE, a sliver from the top of the texture and one from the bottom will be rendered. Additionally, when a wrap flag is D_TRUE, only the fractional part of a texture coordinate is considered for values greater than 1.0, which means textures will not be tiled across a face when wrap is D_TRUE.

Controlling the wrapping behavior is necessary for proper interpretation of texture coordinates. If you have a single texture wrapped across many faces, set the wrap_u and wrap_v parameters to D_TRUE. If a model has one texture per face or you want multiple copies of the texture to be tiled across a single face by using texture coordinates greater than 1, set wrap_u and wrap_v to D_FALSE.

Several interfaces expose a SetTextureTopology method. Direct3DRMMeshBuilder3.SetTextureTopology updates the topology on all component faces, overriding any settings made by Direct3DRMFace2.SetTextureTopology. By default, Direct3DRMFrame3.SetTextureTopology reads from the mesh because the default material mode is D3DRMMATERIAL_FROMMESH. If the material mode is not D3DRMMATERIAL_FROMMESH, Direct3DRMFrame3.SetTextureTopology overrides settings made by Direct3DRMMeshBuilder3.SetTextureTopology.

Direct3DRMMeshBuilder3.SetVertex

---

Direct3DRMMeshBuilder3

Sets the position of a specified vertex in a Direct3DRMMeshBuilder3 object.

Syntax

object.SetVertex(idx As Long,
  x As Single,
  y As Single,
  z As Single)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

idx

Index of the vertex to be set.

x, y, and z

The x-, y-, and z-components of the position to assign to the specified vertex.

Error Values

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

Direct3DRMMeshBuilder3.SetVertexColor

---

Direct3DRMMeshBuilder3

Sets the color of a specified vertex in a Direct3DRMMeshBuilder3 object.

Syntax

object.SetVertexColor(idx As Long,
  c As Long)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

idx

Index of the vertex to be set.

c

Color to assign to the specified vertex.

Error Values

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

See Also

Direct3DRMMeshBuilder3.GetVertexColor

Direct3DRMMeshBuilder3.SetVertexColorRGB

---

Direct3DRMMeshBuilder3

Sets red, green, and blue color components of a specified vertex in a Direct3DRMMeshBuilder3 object.

Syntax

object.SetVertexColorRGB(idx As Long,
  r As Single,
  g As Single,
  b As Single)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

idx

Index of the vertex to be set.

r, g, and b

Red, green, and blue components of the color to assign to the specified vertex.

Error Values

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

Direct3DRMMeshBuilder3.Translate

---

Direct3DRMMeshBuilder3

Adds the specified offsets to the vertex positions of a Direct3DRMMeshBuilder3 object.

Syntax

object.Translate(tx As Single,
  ty As Single,
  tz As Single)

Parts

object

Object expression that resolves to a Direct3DRMMeshBuilder3 object.

tx, ty, and tz

Offsets that are added to the x-, y-, and z-coordinates, respectively, of each vertex position.

Error Values

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

---

 Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.