Direct3DRMMesh
Applications use the methods of the Direct3DRMMesh interface to interact with groups of meshes. A mesh is a visual object made up of a set of polygonal faces. A mesh defines a set of vertices and a set of faces (the faces are defined in terms of the vertices and normals of the mesh). Changing a vertex or normal that is used by several faces changes the appearance of all faces sharing it.
The vertices of a mesh define the positions of faces in the mesh, and they can also be used to define 2-D coordinates within a texture map.
You can manipulate meshes in Microsoft® Direct3D® Retained Mode by using Direct3DRMMesh and Direct3DRMMeshBuilder3.
If an application needs to assign the same characteristics (such as material or texture) to several vertices or faces, it can use the Direct3DRMMesh interface to combine them in a group. If the application needs to share vertices between two different groups (for example, if neighboring faces in a mesh are different colors), the vertices must be duplicated in both groups. The Direct3DRMMesh.AddGroup method assigns a group identifier to a collection of faces. This identifier is used to refer to the group in subsequent calls.
The Direct3DRMMeshBuilder3 and Direct3DRMMesh interfaces enable an application to create faces with more than three sides. They also automatically split a mesh into multiple buffers if, for example, the hardware the application is rendering to has a limit of 64 KB and a mesh is larger than that size. These features set the Direct3DRMMesh and Direct3DRMMeshBuilder3 API apart from the Direct3D API.
You can define individual color, texture, and material properties for each face in the mesh, or for all faces in the mesh at once, by using the Direct3DRMMesh.SetGroupColor, SetGroupColorRGB, SetGroupTexture, and SetGroupMaterial methods.
For a mesh to be rendered, you must first add it to a frame by using the Direct3DRMFrame3.AddVisual method. You can add a single mesh to multiple frames to create multiple instances of that mesh.
Your application can use flat and Gouraud shade modes, as specified by a call to the Direct3DRMMesh.SetGroupQuality method. (Phong shading is not yet available, however.)
The methods of the Direct3DRMMesh interface can be organized into the following groups.
Color GetGroupColor SetGroupColor SetGroupColorRGB Creation and information AddGroup GetBox GetGroupCount GetGroupData GetSizes GetGroupDataSize Materials GetGroupMaterial SetGroupMaterial Miscellaneous Scale Translate Rendering quality GetGroupQuality SetGroupQuality Texture mapping GetGroupMapping SetGroupMapping Textures GetGroupTexture SetGroupTexture Vertex positions GetVertex GetVertexCount GetVertices SetVertex SetVertices
The Direct3DRMMesh interface inherits the following methods from the Direct3DRMObject interface.
Obtain a Direct3DRMMesh object by using the Direct3DRM3.CreateMesh method.
Direct3DRMMesh.AddGroup
Direct3DRMMesh
Groups a collection of faces and retrieves an identifier for the group. The first group added to a mesh always has index 0. The index of each successive group increases by 1.
Syntax
object.AddGroup(vertexCount As Long, faceCount As Long, verticesPerFace As Long, fdata() As Long) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- vertexCount and faceCount
- Number of vertices and faces in the group.
- verticesPerFace
- Number of vertices per face in the group, if all faces have the same vertex count. If the group contains faces with varying vertex counts, this parameter should be zero.
- fdata
- Face data. If the verticesPerFace parameter specifies a value, this data is simply a list of indices into the group's vertex array. If verticesPerFace is zero, the vertex indices should be preceded by an integer specifying the number of vertices in that face. For example, if verticesPerFace is zero and the group is made up of triangular and quadrilateral faces, the data might be in the following form: 3 index index index 4 index index index index 3 index index index ...
Return Value
Returns the value that identifies the group.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
A newly added group has the following default properties.
- White
- No texture
- No specular reflection
- Position, normal, and color of each vertex in the vertex array equal to zero
To set the positions of the vertices, use the Direct3DRMMesh.SetVertices method.
Direct3DRMMesh.GetBox
Direct3DRMMesh
Retrieves the bounding box containing a Direct3DRMMesh object. The bounding box gives the minimum and maximum model coordinates in each dimension.
Syntax
object.GetBox(vector As D3DRMBOX)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- vector
- D3DRMBOX type filled with the bounding box coordinates.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMMesh.GetGroupColor
Direct3DRMMesh
Retrieves the color for a group.
Syntax
object.GetGroupColor(id As Long) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
Return Value
Returns a value specifying the color if successful, or zero otherwise.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.SetGroupColor, Direct3DRMMesh.SetGroupColorRGB
Direct3DRMMesh.GetGroupCount
Direct3DRMMesh
Retrieves the number of groups for a given Direct3DRMMesh object.
Syntax
object.GetGroupCount( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
Return Value
Returns the number of groups if successful, or zero otherwise.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMMesh.GetGroupData
Direct3DRMMesh
Retrieves the face data associated with a specified group.
Syntax
object.GetGroupData(id As Long, psa() As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- psa
- Array to be filled with face data. This data is a list of indices into the group's vertex array preceded by an integer specifying the number of vertices in that face. For example, if the group is made up of triangular and quadrilateral faces, the data might be in the following form: 3 index index index 4 index index index index 3 index index index ...
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMMesh.GetGroupDataSize
Direct3DRMMesh
Retrieves the number of elements in the data array associated with a particular group.
Syntax
object.GetGroupDataSize(id As Long) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
Return Value
Returns the number of elements.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMMesh.GetGroupMapping
Direct3DRMMesh
Retrieves a description of how textures are mapped to a group in a Direct3DRMMesh object.
Syntax
object.GetGroupMapping(id As Long) As CONST_D3DRMMAPPINGFLAGS
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
Return Value
Returns one of the following values from the CONST_D3DRMMAPPINGFLAGS enumerated type describing how textures are mapped to a group.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.GetGroupMaterial
Direct3DRMMesh
Retrieves the material associated with a group in a Direct3DRMMesh object.
Syntax
object.GetGroupMaterial(id As Long) As Direct3DRMMaterial2
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
Return Value
Returns a Direct3DRMMaterial2 object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.GetGroupQuality
Direct3DRMMesh
Retrieves the rendering quality for a specified group in a Direct3DRMMesh object.
Syntax
object.GetGroupQuality(id As Long) As CONST_D3DRMRENDERQUALITY
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
Return Value
Returns values from the CONST_D3DRMRENDERQUALITY enumerated type specifying render quality if successful, or zero otherwise.
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
Direct3DRMMesh.GetGroupTexture
Direct3DRMMesh
Retrieves the texture associated with a group in a Direct3DRMMesh object.
Syntax
object.GetGroupTexture(id As Long) As Direct3DRMTexture3
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
Return Value
Returns a Direct3DRMTexture3 object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.GetSizes
Direct3DRMMesh
Retrieves information for a specified group in a Direct3DRMMesh object.
Syntax
object.GetSizes(id As Long, cnt1 As Long, cnt2 As Long, cnt3 As Long, cnt4 As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must have been produced by using the Direct3DRMMesh.AddGroup method.
- cnt1
- Filled with the number of vertices in the group.
- cnt2
- Filled with the number of faces in the group.
- cnt3
- Filled with the number of vertices per face in the group, if all faces have the same vertex count. If the group contains faces with varying vertex counts, this parameter is filled with zero.
- cnt4
- Filled with the required size of psa required by GetGroupData.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.GetVertex
Direct3DRMMesh
Retrieves a single vertex from a particular group.
Syntax
object.GetVertex(id As Long, idx As Long, ret As D3DRMVERTEX)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must have been produced by using the Direct3DRMMesh.AddGroup method.
- idx
- Index into the array of D3DRMVERTEX types at which to begin returning vertex positions.
- ret
- D3DRMVERTEX type that will contain the vertex information (vertex positions, colors, texture coordinates, and so on) when the method returns.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.GetVertexCount
Direct3DRMMesh
Retrieves the number of vertices for a given Direct3DRMMesh object.
Syntax
object.GetVertexCount(id As Long) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must have been produced by using the Direct3DRMMesh.AddGroup method.
Return Value
Returns the number of vertices if successful, or zero otherwise.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.GetVertices
Direct3DRMMesh
Retrieves vertex information for a specified group in a Direct3DRMMesh object.
Syntax
object.GetVertices(id As Long, idx As Long, cnt As Long, vertexArray() As D3DRMVERTEX)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must have been produced by using the Direct3DRMMesh.AddGroup method.
- idx
- Index into the array of D3DRMVERTEX types at which to begin returning vertex positions.
- cnt
- Number of D3DRMVERTEX types (vertices) to retrieve following the index given in the idx parameter. This parameter cannot be NOTHING. To retrieve the number of vertices in a group, use the Direct3DRMMesh.GetVertexCount method.
- vertexArray
- An array of D3DRMVERTEX types that will contain the vertex information (vertex positions, colors, texture coordinates, and so on) when the method returns.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.Scale
Direct3DRMMesh
Scales a Direct3DRMMesh object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.
Syntax
object.Scale(sx As Single, sy As Single, sz As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh 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.
Direct3DRMMesh.SetGroupColor
Direct3DRMMesh
Sets the color of a group in a Direct3DRMMesh object.
Syntax
object.SetGroupColor(id As Long, val As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- val
- Color of the group.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method is also used to add a group color key to a Direct3DRMMeshInterpolator object.
See Also
Direct3DRMMesh.GetGroupColor, Direct3DRMMesh.SetGroupColorRGB
Direct3DRMMesh.SetGroupColorRGB
Direct3DRMMesh
Sets the color of a group in a Direct3DRMMesh object, using individual RGB values.
Syntax
object.SetGroupColorRGB(id As Long, r As Single, g As Single, b As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- r, g, and b
- Red, green, and blue components of the group color.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method is also used to add a group RGB key to a Direct3DRMMeshInterpolator object.
See Also
Direct3DRMMesh.SetGroupMapping
Direct3DRMMesh
Sets the mapping for a group in a Direct3DRMMesh object. The mapping controls how textures are mapped to a surface.
Syntax
object.SetGroupMapping(id As Long, value As CONST_D3DRMMAPPINGFLAGS)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- value
- Value from the CONST_D3DRMMAPPINGFLAGS enumerated type that describes the mapping for the group.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.SetGroupMaterial
Direct3DRMMesh
Sets the material associated with a group in a Direct3DRMMesh object.
Syntax
object.SetGroupMaterial(id As Long, val As Direct3DRMMaterial2)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- val
- Direct3DRMMaterial2 interface for the Direct3DRMMesh object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.SetGroupQuality
Direct3DRMMesh
Sets the rendering quality for a specified group in a Direct3DRMMesh object.
Syntax
object.SetGroupQuality(id As Long, value As CONST_D3DRMRENDERQUALITY)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- value
- Values from the CONST_D3DRMRENDERQUALITY enumerated type identifying the rendering quality. These values include the shading, lighting, and fill modes for the object.
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
Direct3DRMMesh.SetGroupTexture
Direct3DRMMesh
Sets the texture associated with a group in a Direct3DRMMesh object.
Syntax
object.SetGroupTexture(id As Long, val As Direct3DRMTexture3)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- val
- Direct3DRMTexture3 interface for the Direct3DRMMesh object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMMesh.SetVertex
Direct3DRMMesh
Modifies the geometry of an existing group in a Direct3DRMMesh object.
Syntax
object.SetVertex(id As Long, idx As Long, values As D3DRMVERTEX)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- idx
- Index of the first vertex in the mesh group to be modified.
- values
- D3DRMVERTEX type specifying the vertex positions to be set.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
Vertices are local to the group. If an application needs to share vertices between two different groups (for example, if neighboring faces in a mesh are different colors), the vertices must be duplicated in both groups.
This method is also used to add a vertex position key to a Direct3DRMMeshInterpolator object.
See Also
Direct3DRMMesh.SetVertices
Direct3DRMMesh
Sets the vertex positions for a specified group in a Direct3DRMMesh object.
Syntax
object.SetVertices(id As Long, idx As Long, count As Long, vertexArray() As D3DRMVERTEX)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh object.
- id
- Identifier of the group. This identifier must be produced by using the Direct3DRMMesh.AddGroup method.
- idx
- Index of the first vertex in the mesh group to be modified.
- count
- Number of consecutive vertices to set. The vertexArray parameter must contain at least the number of count elements.
- vertexArray
- n array of D3DRMVERTEX types specifying the vertex positions to be set.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
Vertices are local to the group. If an application needs to share vertices between two different groups (for example, if neighboring faces in a mesh are different colors), the vertices must be duplicated in both groups.
This method is also used to add a vertex position key to a Direct3DRMMeshInterpolator object.
See Also
Direct3DRMMesh.Translate
Direct3DRMMesh
Adds the specified offsets to the vertex positions of a Direct3DRMMesh object.
Syntax
object.Translate(tx As Single, ty As Single, tz As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMMesh 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.