Applications use the methods of the IDirect3DRMMeshBuilder2 interface to interact with mesh objects. IDirect3DRMMeshBuilder2 has the same functionality as IDirect3DRMMeshBuilder and in addition has extended the IDirect3DRMMeshBuilder2::GenerateNormals2 method to give greater control over the mesh normals generated. IDirect3DRMMeshBuilder2 also allows you to retrieve a single mesh face with IDirect3DRMMeshBuilder2::GetFace.
This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMMesh, IDirect3DRMMeshBuilder, and IDirect3DRMMeshBuilder2 Interfaces.
The methods of the IDirect3DRMMeshBuilder2 interface can be organized into the following groups:
| Color | GetColorSource |
| SetColor | |
| SetColorRGB | |
| SetColorSource | |
| Creation | GetBox |
| Faces | AddFace |
| AddFaces | |
| CreateFace | |
| GetFaceCount | |
| GetFace | |
| GetFaces | |
| Loading | Load |
| Meshes | AddMesh |
| CreateMesh | |
| Miscellaneous | AddFrame |
| AddMeshBuilder | |
| ReserveSpace | |
| Save | |
| Scale | |
| SetMaterial | |
| Translate | |
| Normals | AddNormal |
| GenerateNormals2 | |
| SetNormal | |
| Perspective | GetPerspective |
| SetPerspective | |
| Rendering quality | GetQuality |
| SetQuality | |
| Textures | GetTextureCoordinates |
| SetTexture | |
| SetTextureCoordinates | |
| SetTextureTopology | |
| Vertices | AddVertex |
| GetVertexColor | |
| GetVertexCount | |
| GetVertices | |
| SetVertex | |
| SetVertexColor | |
| SetVertexColorRGB |
The IDirect3DRMMeshBuilder2 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 IDirect3DRMMeshBuilder2 interface inherits the following methods from the IDirect3DRMObject interface:
| AddDestroyCallback |
| Clone |
| DeleteDestroyCallback |
| GetAppData |
| GetClassName |
| GetName |
| SetAppData |
| SetName |
The Direct3DRMMeshBuilder2 object is obtained by using the IDirect3DRM::CreateMeshBuilder method.
Adds a face to a Direct3DRMMeshBuilder2 object.
HRESULT AddFace(
LPDIRECT3DRMFACE lpD3DRMFace
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Any one face can exist in only one mesh at a time.
Adds faces to a Direct3DRMMeshBuilder2 object.
HRESULT AddFaces(
DWORD dwVertexCount,
D3DVECTOR * lpD3DVertices,
DWORD normalCount,
D3DVECTOR *lpNormals,
DWORD *lpFaceData,
LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Adds the contents of a frame to a Direct3DRMMeshBuilder2 object.
HRESULT AddFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
The source frame is not modified or referenced by this operation.
Adds a mesh to a Direct3DRMMeshBuilder2 object.
HRESULT AddMesh(
LPDIRECT3DRMMESH lpD3DRMMesh
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Adds the contents of a Direct3DRMMeshBuilder object to a Direct3DRMMeshBuilder2 object.
HRESULT AddMeshBuilder(
LPDIRECT3DRMMESHBUILDER lpD3DRMMeshBuild
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
The source Direct3DRMMeshBuilder object is not modified or referenced by this operation.
Adds a normal to a Direct3DRMMeshBuilder2 object.
int AddNormal(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);
Returns the index of the normal.
Adds a vertex to a Direct3DRMMeshBuilder2 object.
int AddVertex(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);
Returns the index of the vertex.
Creates a new face with no vertices and adds it to a Direct3DRMMeshBuilder2 object.
HRESULT CreateFace(
LPDIRECT3DRMFACE* lplpD3DRMFace
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a new mesh from a Direct3DRMMeshBuilder2 object.
HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Processes the Direct3DRMMeshBuilder2 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.
HRESULT GenerateNormals2(
D3DVALUE dvCreaseAngle,
DWORD dwFlags
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
Retrieves the bounding box containing a Direct3DRMMeshBuilder2 object. The bounding box gives the minimum and maximum model coordinates in each dimension.
HRESULT GetBox(
D3DRMBOX *lpD3DRMBox
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the color source of a Direct3DRMMeshBuilder2 object. The color source can be either a face or a vertex.
D3DRMCOLORSOURCE GetColorSource( );
Returns a member of the D3DRMCOLORSOURCE enumerated type.
IDirect3DRMMeshBuilder2::SetColorSource
Retrieves a single face of a Direct3DRMMeshBuilder2 object.
HRESULT GetFace(
DWORD dwIndex,
LPDIRECT3DRMFACE* lplpD3DRMFace
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the number of faces in a Direct3DRMMeshBuilder2 object.
int GetFaceCount( );
Returns the number of faces.
Retrieves the faces of a Direct3DRMMeshBuilder2 object.
HRESULT GetFaces(
LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Determines whether perspective correction is on for a Direct3DRMMeshBuilder2 object.
BOOL GetPerspective( );
Returns TRUE if perspective correction is on, or FALSE otherwise.
Retrieves the rendering quality of a Direct3DRMMeshBuilder2 object.
D3DRMRENDERQUALITY GetQuality( );
Returns a member of the D3DRMRENDERQUALITY enumerated type that specifies the rendering quality of the mesh.
IDirect3DRMMeshBuilder2::SetQuality
Retrieves the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder2 object.
HRESULT GetTextureCoordinates(
DWORD index,
D3DVALUE *lpU,
D3DVALUE *lpV
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMMeshBuilder2::SetTextureCoordinates
Retrieves the color of a specified vertex in a Direct3DRMMeshBuilder2 object.
D3DCOLOR GetVertexColor(
DWORD index
);
Returns the color.
IDirect3DRMMeshBuilder2::SetVertexColor
Retrieves the number of vertices in a Direct3DRMMeshBuilder2 object.
int GetVertexCount( );
Returns the number of vertices.
Retrieves the vertices, normals, and face data for a Direct3DRMMeshBuilder2 object.
HRESULT GetVertices(
DWORD *vcount,
D3DVECTOR *vertices,
DWORD *ncount,
D3DVECTOR *normals,
DWORD *face_data_size,
DWORD *face_data
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Loads a Direct3DRMMeshBuilder2 object.
HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpvArg
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
By default, this method loads the first mesh from the source specified in the lpvObjSource parameter.
Reserves space within a Direct3DRMMeshBuilder2 object for the specified number of vertices, normals, and faces. This allows the system to use memory more efficiently.
HRESULT ReserveSpace(
DWORD vertexCount,
DWORD normalCount,
DWORD faceCount
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Saves a Direct3DRMMeshBuilder2 object.
HRESULT Save(
const char * lpFilename,
D3DRMXOFFORMAT d3drmXOFFormat,
D3DRMSAVEOPTIONS d3drmSOContents
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Scales a Direct3DRMMeshBuilder2 object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.
HRESULT Scale(
D3DVALUE sx,
D3DVALUE sy,
D3DVALUE sz
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets all the faces of a Direct3DRMMeshBuilder2 object to a given color.
HRESULT SetColor(
D3DCOLOR color
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets all the faces of a Direct3DRMMeshBuilder2 object to a given color.
HRESULT SetColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the color source of a Direct3DRMMeshBuilder2 object.
HRESULT SetColorSource(
D3DRMCOLORSOURCE source
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMMeshBuilder2::GetColorSource
Sets the material of all the faces of a Direct3DRMMeshBuilder2 object.
HRESULT SetMaterial(
LPDIRECT3DRMMATERIAL lpIDirect3DRMmaterial
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the normal vector of a specified vertex in a Direct3DRMMeshBuilder2 object.
HRESULT SetNormal(
DWORD index,
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Enables or disables perspective-correct texture-mapping for a Direct3DRMMeshBuilder2 object.
HRESULT SetPerspective(
BOOL perspective
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the rendering quality of a Direct3DRMMeshBuilder2 object.
HRESULT SetQuality(
D3DRMRENDERQUALITY quality
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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, wireframe, or solid).
You can set the quality of a device with IDirect3DRMDevice::SetQuality. By default it is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).
You can set the quality of a Direct3DRMMeshBuilder2 object with the SetQuality method. By default, a Direct3DRMMeshBuilder2 object's quality is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).
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 Direct3DRMMeshBuilder objects, Direct3DRMMeshBuilder2 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).
IDirect3DRMMeshBuilder2::GetQuality
Sets the texture of all the faces of a Direct3DRMMeshBuilder2 object.
HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder2 object.
HRESULT SetTextureCoordinates(
DWORD index,
D3DVALUE u,
D3DVALUE v
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMMeshBuilder2::GetTextureCoordinates
Sets the texture topology of a Direct3DRMMeshBuilder2 object.
HRESULT SetTextureTopology(
BOOL cylU,
BOOL cylV
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the position of a specified vertex in a Direct3DRMMeshBuilder2 object.
HRESULT SetVertex(
DWORD index,
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the color of a specified vertex in a Direct3DRMMeshBuilder2 object.
HRESULT SetVertexColor(
DWORD index,
D3DCOLOR color
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMMeshBuilder2::GetVertexColor
Sets the color of a specified vertex in a Direct3DRMMeshBuilder2 object.
HRESULT SetVertexColorRGB(
DWORD index,
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Adds the specified offsets to the vertex positions of a Direct3DRMMeshBuilder2 object.
HRESULT Translate(
D3DVALUE tx,
D3DVALUE ty,
D3DVALUE tz
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.