IDirect3DRMMesh
Applications use the methods of the IDirect3DRMMesh interface to interact with groups of meshes. A mesh is a visual object that is 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 Retained Mode by using IDirect3DRMMesh and IDirect3DRMMeshBuilder3.
If an application needs to assign the same characteristics (such as material or texture) to several vertices or faces, it can use the IDirect3DRMMesh 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 IDirect3DRMMesh::AddGroup method assigns a group identifier to a collection of faces. This identifier is used to refer to the group in subsequent calls.
The IDirect3DRMMeshBuilder3 and IDirect3DRMMesh interfaces allow 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 64K 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 IDirect3DRMMesh::SetGroupColor, SetGroupColorRGB, SetGroupTexture, and SetGroupMaterial methods.
For a mesh to be rendered, you must first add it to a frame by using the IDirect3DRMFrame3::AddVisual method. You can add a single mesh to multiple frames to create multiple instances of that mesh.
Your application can use flat, Gouraud, and Phong shade modes, as specified by a call to the IDirect3DRMMesh::SetGroupQuality method. (Phong shading is not yet available, however.) This method uses values from the D3DRMRENDERQUALITY enumerated type. For more information about shade modes, see Polygons.
The methods of the IDirect3DRMMesh interface can be organized into the following groups:
| Color | GetGroupColor |
| SetGroupColor | |
| SetGroupColorRGB | |
| Creation and | AddGroup |
| information | GetBox |
| GetGroup | |
| GetGroupCount | |
| Materials | GetGroupMaterial |
| SetGroupMaterial | |
| Miscellaneous | Scale |
| Translate | |
| Rendering quality | GetGroupQuality |
| SetGroupQuality | |
| Texture mapping | GetGroupMapping |
| SetGroupMapping | |
| Textures | GetGroupTexture |
| SetGroupTexture | |
| Vertex positions | GetVertices |
| SetVertices |
The IDirect3DRMMesh 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 IDirect3DRMMesh interface inherits the following methods from the IDirect3DRMObject interface:
| AddDestroyCallback |
| Clone |
| DeleteDestroyCallback |
| GetAppData |
| GetClassName |
| GetName |
| SetAppData |
| SetName |
The Direct3DRMMesh object is obtained by using the IDirect3DRM3::CreateMesh method.
IDirect3DRMMesh::AddGroup
IDirect3DRMMesh
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
HRESULT AddGroup(
unsigned vCount,
unsigned fCount,
unsigned vPerFace,
unsigned *fData,
D3DRMGROUPINDEX *returnId
);
Parameters
- vCount and fCount
- Number of vertices and faces in the group.
- vPerFace
- 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
- Address of face data. If the vPerFace parameter specifies a value, this data is simply a list of indices into the group's vertex array. If vPerFace is zero, the vertex indices should be preceded by an integer specifying the number of vertices in that face. For example, if vPerFace 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 ...
- returnId
- Address of the variable that identifies the group when the method returns.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return 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 IDirect3DRMMesh::SetVertices method.
IDirect3DRMMesh::GetBox
IDirect3DRMMesh
Retrieves the bounding box containing a Direct3DRMMesh object. The bounding box gives the minimum and maximum model coordinates in each dimension.
Syntax
HRESULT GetBox(
D3DRMBOX *lpD3DRMBox
);
Parameters
- lpD3DRMBox
- Address of a D3DRMBOX structure filled with the bounding box coordinates.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMMesh::GetGroup
IDirect3DRMMesh
Retrieves the data associated with a specified group.
Syntax
HRESULT GetGroup(
D3DRMGROUPINDEX id,
unsigned *vCount,
unsigned *fCount,
unsigned *vPerFace,
DWORD *fDataSize,
unsigned *fData
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- vCount and fCount
- Addresses of variables that will contain the number of vertices and the number of faces for the group when the method returns. These parameters can be NULL.
- vPerFace
- Address of a variable that will contain the number of vertices per face for the group when the method returns. This parameter can be NULL.
- fDataSize
- Address of a variable that specifies the number of unsigned elements in the buffer that the fData parameter points to. This parameter cannot be NULL.
- fData
- Address of a buffer that will contain the face data for the group when the method returns. The format of this data is the same as was specified in the call to the IDirect3DRMMesh::AddGroup method. If this parameter is NULL, the method returns the required size of the buffer in the fDataSize parameter.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMMesh::GetGroupColor
IDirect3DRMMesh
Retrieves the color for a group.
Syntax
D3DCOLOR GetGroupColor(
D3DRMGROUPINDEX id
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
Return Value
Returns a D3DCOLOR variable specifying the color if successful, or zero otherwise.
See Also
IDirect3DRMMesh::SetGroupColor, IDirect3DRMMesh::SetGroupColorRGB
IDirect3DRMMesh::GetGroupCount
IDirect3DRMMesh
Retrieves the number of groups for a given Direct3DRMMesh object.
Syntax
unsigned GetGroupCount( );
Return Value
Returns the number of groups if successful, or zero otherwise.
IDirect3DRMMesh::GetGroupMapping
IDirect3DRMMesh
Retrieves a description of how textures are mapped to a group in a Direct3DRMMesh object.
Syntax
D3DRMMAPPING GetGroupMapping(
D3DRMGROUPINDEX id
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
Return Value
Returns one of the D3DRMMAPPING values that describe how textures are mapped to a group, if successful. Returns zero otherwise.
See Also
IDirect3DRMMesh::GetGroupMaterial
IDirect3DRMMesh
Retrieves a pointer to the material associated with a group in a Direct3DRMMesh object.
Syntax
HRESULT GetGroupMaterial(
D3DRMGROUPINDEX id,
LPDIRECT3DRMMATERIAL *returnPtr
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- returnPtr
- Address of a pointer to a variable that will contain the IDirect3DRMMaterial interface for the group when the method returns.
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
IDirect3DRMMesh::GetGroupQuality
IDirect3DRMMesh
Retrieves the rendering quality for a specified group in a Direct3DRMMesh object.
Syntax
D3DRMRENDERQUALITY GetGroupQuality(
D3DRMGROUPINDEX id
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
Return Value
Returns values from the enumerated types represented by D3DRMRENDERQUALITY if successful, or zero otherwise. These values include the shading, lighting, and fill modes for the object.
See Also
IDirect3DRMMesh::GetGroupTexture
IDirect3DRMMesh
Retrieves an address of the texture associated with a group in a Direct3DRMMesh object.
Syntax
HRESULT GetGroupTexture(
D3DRMGROUPINDEX id,
LPDIRECT3DRMTEXTURE *returnPtr
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- returnPtr
- Address of a pointer to a variable that will contain the IDirect3DRMTexture interface for the group when the method returns.
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
IDirect3DRMMesh::GetVertices
IDirect3DRMMesh
Retrieves vertex information for a specified group in a Direct3DRMMesh object.
Syntax
HRESULT GetVertices(
D3DRMGROUPINDEX id,
DWORD index,
DWORD count,
D3DRMVERTEX *returnPtr
);
Parameters
- id
- Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.
- index
- Index into the array of D3DRMVERTEX structures at which to begin returning vertex positions.
- count
- Number of D3DRMVERTEX structures (vertices) to retrieve following the index given in the index parameter. This parameter cannot be NULL. To retrieve the number of vertices in a group, use the IDirect3DRMMesh::GetGroup method.
- returnPtr
- Array of D3DRMVERTEX structures that will contain the vertex information (vertex positions, colors, texture coordinates, and so on) when the method returns.
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
IDirect3DRMMesh::Scale
IDirect3DRMMesh
Scales a Direct3DRMMesh object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.
Syntax
HRESULT Scale(
D3DVALUE sx,
D3DVALUE sy,
D3DVALUE sz
);
Parameters
- sx, sy, and sz
- Scaling factors that are applied along the x-, y-, and z-axes.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMMesh::SetGroupColor
IDirect3DRMMesh
Sets the color of a group in a Direct3DRMMesh object.
Syntax
HRESULT SetGroupColor(
D3DRMGROUPINDEX id,
D3DCOLOR value
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- value
- Color of the group.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Remarks
This method is also used to add a group color key to a Direct3DRMMeshInterpolator object.
See Also
IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColorRGB
IDirect3DRMMesh::SetGroupColorRGB
IDirect3DRMMesh
Sets the color of a group in a Direct3DRMMesh object, using individual RGB values.
Syntax
HRESULT SetGroupColorRGB(
D3DRMGROUPINDEX id,
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- red, green, and blue
- Red, green, and blue components of the group color.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Remarks
This method is also used to add a group RGB key to a Direct3DRMMeshInterpolator object.
See Also
IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColor
IDirect3DRMMesh::SetGroupMapping
IDirect3DRMMesh
Sets the mapping for a group in a Direct3DRMMesh object. The mapping controls how textures are mapped to a surface.
Syntax
HRESULT SetGroupMapping(
D3DRMGROUPINDEX id,
D3DRMMAPPING value
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- value
- Value of the D3DRMMAPPING type that describes the mapping for the group.
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
IDirect3DRMMesh::SetGroupMaterial
IDirect3DRMMesh
Sets the material associated with a group in a Direct3DRMMesh object.
Syntax
HRESULT SetGroupMaterial(
D3DRMGROUPINDEX id,
LPDIRECT3DRMMATERIAL value
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- value
- Address of the IDirect3DRMMaterial interface for the Direct3DRMMesh object.
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
IDirect3DRMMesh::SetGroupQuality
IDirect3DRMMesh
Sets the rendering quality for a specified group in a Direct3DRMMesh object.
Syntax
HRESULT SetGroupQuality(
D3DRMGROUPINDEX id,
D3DRMRENDERQUALITY value
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- value
- Values from the enumerated types represented by the D3DRMRENDERQUALITY type. These values include the shading, lighting, and fill modes for the object.
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
IDirect3DRMMesh::SetGroupTexture
IDirect3DRMMesh
Sets the texture associated with a group in a Direct3DRMMesh object.
Syntax
HRESULT SetGroupTexture(
D3DRMGROUPINDEX id,
LPDIRECT3DRMTEXTURE value
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- value
- Address of the IDirect3DRMTexture interface for the Direct3DRMMesh object.
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
IDirect3DRMMesh::SetVertices
IDirect3DRMMesh
Sets the vertex positions for a specified group in a Direct3DRMMesh object.
Syntax
HRESULT SetVertices(
D3DRMGROUPINDEX id,
unsigned index,
unsigned count,
D3DRMVERTEX *values
);
Parameters
- id
- Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
- index
- Index of the first vertex in the mesh group to be modified.
- count
- Number of consecutive vertices to set. The values array must contain at least the number of count elements.
- values
- Array of D3DRMVERTEX structures specifying the vertex positions to be set.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return 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
IDirect3DRMMesh::Translate
IDirect3DRMMesh
Adds the specified offsets to the vertex positions of a Direct3DRMMesh object.
Syntax
HRESULT Translate(
D3DVALUE tx,
D3DVALUE ty,
D3DVALUE tz
);
Parameters
- tx, ty, and tz
- Offsets that are added to the x-, y-, and z-coordinates, respectively, of each 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.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.