IDirect3DRMMeshBuilder3 Methods A to M

This section contains the reference pages for the methods of the IDirect3DRMMeshBuilder3 interface that begin with the letters A through M.

IDirect3DRMMeshBuilder3::AddFace

IDirect3DRMMeshBuilder3

Adds a face to a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT AddFace(
  LPDIRECT3DRMFACE2 lpD3DRMFace
  );

Parameters

lpD3DRMFace
Address of a pointer to the face being added.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

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

IDirect3DRMMeshBuilder3::AddFaces

IDirect3DRMMeshBuilder3

Adds faces to a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT AddFaces(
  DWORD dwVertexCount,
  D3DVECTOR  *lpD3DVertices,
  DWORD normalCount,
  D3DVECTOR *lpNormals,
  DWORD *lpFaceData,
  LPDIRECT3DRMFACEARRAY *lplpD3DRMFaceArray
  );

Parameters

dwVertexCount
Number of vertices.
lpD3DVertices
Base address of an array of D3DVECTOR structures that store the vertex positions.
normalCount
Number of normals.
lpNormals
Base address of an array of D3DVECTOR structures that store the normal positions.
lpFaceData
For each face, this parameter should contain a vertex count followed by the indexes into the vertices array. If normalCount 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.
lplpD3DRMFaceArray
Address of a pointer to an IDirect3DRMFaceArray interface that will be filled with a pointer to the newly created faces.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder3::AddFacesIndexed

IDirect3DRMMeshBuilder3

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

Syntax

IDirect3DRMMeshBuilder3::AddFacesIndexed(
  DWORD dwFlags,
  DWORD *lpdwvIndices,
  DWORD *lpdwIndexFirst,
  DWORD *lpdwCount);

Parameters

dwFlags

Flag value that specifies how normal indexes should be handled. Must be either 0 or D3DRMADDFACES_VERTICESONLY. If the value is 0, indexes of pre-existing normals must be specified in the lpdwvIndices parameter. Otherwise, the normal with the corresponding index will be used automatically for each vertex.

lpdwvIndices

Pointer to a contiguous array of unsigned 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 dwFlags parameter and the required face tuple format for the lpdwvIndices parameter.

dwFlags Required face tuple format

0 {<n>, <vIndex0>, <nIndex0>,...,<vIndexn-1>, <nIndexn-1>}

D3DRMADDFACES_VERTICESONLY {<n>, <vIndex0>,...,<vIndexn-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.

lpdwIndexFirst

Optional pointer to a DWORD that, if supplied, is filled with the index of the first new face added to the meshbuilder. Subsequent faces have contiguous indexes. Faces are added in the order in which they are specified in the lpdwvIndices parameter.

lpdwCount

Optional pointer to a DWORD that, if supplied, is filled with the number of faces added to the meshbuilder.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMMeshBuilder3::AddFrame

IDirect3DRMMeshBuilder3

Adds the contents of a frame to a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT AddFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame
  );

Parameters

lpD3DRMFrame
Address of a pointer to the frame whose contents are being added.

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 adds a copy of all the mesh and meshbuilder faces from the specified frame hierarchy (which may be a sub-branch 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.

IDirect3DRMMeshBuilder3::AddMesh

IDirect3DRMMeshBuilder3

Adds a mesh to a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT AddMesh(
  LPDIRECT3DRMMESH lpD3DRMMesh
  );

Parameters

lpD3DRMMesh
Address of a pointer to the mesh being added.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder3::AddMeshBuilder

IDirect3DRMMeshBuilder3

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

HRESULT
AddMeshBuilder(
  LPDIRECT3DRMMESHBUILDER3 lpD3DRMMeshBuild
  DWORD dwFlags);
  );

Parameters

lpD3DRMMeshBuild
Pointer to the Direct3DRMMeshBuilder3 object whose contents are being added.

dwFlags

One of the following defined flags:
D3DRMADDMESHBUILDER_FLATTENSUBMESHES

Causes the submesh objects to not be duplicated. Their faces are still copied, but only to the top-level of the destination meshbuilder.

D3DRMADDMESHBUILDER_NOSUBMESHES

Causes sub-meshbuilders to be ignored.

D3DRMADDMESHBUILDER_DONTCOPYAPPDATA

By default, AddMeshBuilder3 copies the application data of source meshbuilders to the destination. Specifying D3DRMADDMESHBUILDER_DONTCOPYAPPDATA prevents this from occurring.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

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

IDirect3DRMMeshBuilder3::AddNormal

IDirect3DRMMeshBuilder3

Adds a normal to a Direct3DRMMeshBuilder3 object.

Syntax

int AddNormal(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

Parameters

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.

IDirect3DRMMeshBuilder3::AddTriangles

IDirect3DRMMeshBuilder3

Enables the application to add new triangles (as opposed to general polygons) to the IDirect3DRMMeshBuilder3 object, and in the process, to implicitly create new faces. 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 may optionally have none or any of the following: normal, texture coordinates, or color. The vertex also has a type that describes whether this new vertex describes a list, strip, or fan. A flag also indicates whether this triangle is to be added to the face of the previous triangle, or whether a new face is to be created.

IDirect3DRMMeshBuilder3::AddTriangles Example

Syntax

HRESULT AddTriangles(
  DWORD dwFlags,
  DWORD dwFormat,
  DWORD dwVertexCount,
  LPVOID lpData);

Parameters

dwFlags

Must be zero.

dwFormat
Logical combination of values describing the format of the vertex data. If all valid values are included, the vertex data is described by the following Element structure.
struct Element
{
    DWORD     dwType;
    D3DVECTOR dvPosition;
    D3DVECTOR dvNormal;
    D3DCOLOR  dcColor;
    D3DVALUE  tu;
    D3DVALUE  tv;
};
Valid values include a logical combination of any of the following values, which indicate which members of the Element structure to include in the description for each element. The dvPosition member is always present.

D3DRMFVF_TYPE

Include the dwType structure member. If the dwType structure 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 dvNormal structure member.

D3DRMFVF_COLOR

Include the dcColor structure member.

D3DRMFVF_TEXTURECOORDS

Include the tu and tv structure members.
dwVertexCount

Vertex number.

lpvData

Pointer to the data described by dwFormat.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.
The following example shows the appropriate dwType flag for each vertex in the diagram.

Vertex Number dwType 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_FAN

9 D3DRMVERTEX_LIST

10 D3DRMVERTEX_LIST

11 D3DRMVERTEX_LIST

12 D3DRMVERTEX_LIST

13 D3DRMVERTEX_LIST

14 D3DRMVERTEX_LIST

IDirect3DRMMeshBuilder3::AddVertex

IDirect3DRMMeshBuilder3

Adds a vertex to a Direct3DRMMeshBuilder3 object.

Syntax

int AddVertex(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

Parameters

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

Return Value

Returns the index of the vertex.

IDirect3DRMMeshBuilder3::CreateFace

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT CreateFace(
  LPDIRECT3DRMFACE2 *lplpD3DRMFace2
  );

Parameters

lplpD3DRMFace2
Address of a pointer to an IDirect3DRMFace2 interface that will be filled with a pointer to the face that was created.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder3::CreateMesh

IDirect3DRMMeshBuilder3

Creates a new mesh from a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT CreateMesh(
  LPDIRECT3DRMMESH *lplpD3DRMMesh
  );

Parameters

lplpD3DRMMesh
Address that will be filled with a pointer to an IDirect3DRMMesh interface.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder3::CreateSubMesh

IDirect3DRMMeshBuilder3

Creates a new submesh for the current Direct3DRMMeshBuilder3 object. A submesh is similar to a meshbuilder object in that it supports the IDirect3DRMMeshBuilder3 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.

Syntax

HRESULT CreateSubMesh(
  LPUNKNOWN  *lplpUnk);

Parameters

lplpUnk

Address to receive a pointer to the IUnknown interface of the new submesh. You can use QueryInterface on the IUnknown interface to query for IDirect3DRMMeshBuilder3 support.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

DeleteSubMesh, GetSubMeshes, GetParentMesh

IDirect3DRMMeshBuilder3::DeleteFace

IDirect3DRMMeshBuilder3

Deletes a face from the IDirect3DRMMeshBuilder3 object.

Syntax

HRESULT DeleteFace
(LPDIRECT3DRMFACE2 lpFace);

Parameters

lpFace

Pointer to the interface of a Direct3DRMFace2 object to remove from the Direct3DRMMeshBuilder3 object.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMMeshBuilder3::DeleteNormals

IDirect3DRMMeshBuilder3

Deletes an inclusive range of normals. Note that if any of the normals are currently in use by a face, an error is returned.

Syntax

HRESULT DeleteNormals
(DWORD dwFirstIndex,
DWORD dwCount);

Parameters

dwFirstIndex

Index of the first normal to delete.

dwCount

Count of vertices to delete.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMMeshBuilder3::DeleteSubMesh

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT DeleteSubMesh(
  LPUNKNOWN lplpUnk);

Parameters

lplpUnk

Pointer to the IUnknown interface of the submesh to delete.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

CreateSubMesh, GetSubMeshes and GetParentMesh

IDirect3DRMMeshBuilder3::DeleteVertices

IDirect3DRMMeshBuilder3

Deletes an inclusive range of vertices. Note that if any of the vertices are currently in use by a face, an error is returned.

Syntax

HRESULT DeleteVertices
(DWORD dwFirstIndex,
DWORD dwCount);

Parameters

dwFirstIndex

Index of the first vertex to delete.

dwCount

Count of the vertices to delete.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMMeshBuilder3::Empty

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT Empty
(DWORD dwFlags);

Parameters

dwFlags

Flags; must be zero.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMMeshBuilder3::Enable

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT Enable(
  DWORD dwFlags);

Parameters

dwFlags

The currently defined flags are:

D3DRMADDMESHBUILDER_RENDERENABLE

Rendering is enabled on this Direct3DRMMeshBuilder3 object. This setting is the default.

D3DRMADDMESHBUILDER_PICKENABLE

Picking is enabled on this Direct3DRMMeshBuilder3 object. This setting is the default.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

GetEnable

IDirect3DRMMeshBuilder3::GenerateNormals

IDirect3DRMMeshBuilder3

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

HRESULT GenerateNormals(
  D3DVALUE dvCreaseAngle,
  DWORD dwFlags
  );

Parameters

dvCreaseAngle
The least angle in radians that faces can have between them and have a new normal generated.
dwFlags
One of the following values.

D3DRMGENERATENORMALS_PRECOMPACT (dwFlags = 1)

Specifies that the algorithm should attempt to compact mesh vertices before it generates normals. See comments below.

D3DRMGENERATENORMALS_USECREASEANGLE (dwFlags = 2)

Specifies that the dvCreaseAngle parameter should be used. Otherwise, the crease angle is ignored.

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 replaces IDirect3DRMMeshBuilder2::GenerateNormals2. 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.

IDirect3DRMMeshBuilder3::GetBox

IDirect3DRMMeshBuilder3

Retrieves the bounding box containing a Direct3DRMMeshBuilder3 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 that will be 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.

IDirect3DRMMeshBuilder3::GetColorSource

IDirect3DRMMeshBuilder3

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

Syntax

D3DRMCOLORSOURCE GetColorSource( );

Return Value

Returns a member of the D3DRMCOLORSOURCE enumerated type.

See Also

IDirect3DRMMeshBuilder3::SetColorSource

IDirect3DRMMeshBuilder3::GetEnable

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT GetEnable(
  LPDWORD lpdwFlags);

Parameters

lpdwFlags

Pointer to receive a flag indicating the current enable status of this Direct3DRMMeshBuilder3 object. The currently defined flags are:

D3DRMADDMESHBUILDER_PICKENABLE

Picking is enabled on this Direct3DRMMeshBuilder3 object. This flag is set by default.

D3DRMADDMESHBUILDER_RENDERENABLE

Rendering is enabled on this Direct3DRMMeshBuilder3 object. This flag is set by default.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

Enable

IDirect3DRMMeshBuilder3::GetFace

IDirect3DRMMeshBuilder3

Retrieves a single face of a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT GetFace(
  DWORD dwIndex,
  LPDIRECT3DRMFACE2 *lplpD3DRMFace2
  );

Parameters

dwIndex
The index of the mesh face to be retrieved. The face must already be part of a Direct3DRMMeshBuilder3 object.
lplpD3DRMFace2
Address of a pointer to an IDirect3DRMFace2 interface that is filled with an address of the face.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder3::GetFaceCount

IDirect3DRMMeshBuilder3

Retrieves the number of faces in a Direct3DRMMeshBuilder3 object.

Syntax

int GetFaceCount( );

Return Value

Returns the number of faces.

IDirect3DRMMeshBuilder3::GetFaces

IDirect3DRMMeshBuilder3

Retrieves the faces of a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT GetFaces(
  LPDIRECT3DRMFACEARRAY *lplpD3DRMFaceArray
  );

Parameters

lplpD3DRMFaceArray
Address of a pointer to an IDirect3DRMFaceArray interface that is filled with an address of the faces.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder3::GetGeometry

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT GetGeometry(
  DWORD *vcount,
  D3DVECTOR *vertices,
  DWORD *ncount,
  D3DVECTOR *normals,
  DWORD *face_data_size,
  DWORD *face_data
  );

Parameters

vcount
Address of a variable that will contain the number of vertices.
vertices
Address of an array of D3DVECTOR structures that will contain the vertices for the Direct3DRMMeshBuilder3 object. If this parameter is NULL, the method returns the number of vertices in the vcount parameter.
ncount
Address of a variable that will contain the number of normals.
normals
Address of an array of D3DVECTOR structures that will contain the normals for the Direct3DRMMeshBuilder3 object. If this parameter is NULL, the method returns the number of normals in the ncount parameter.
face_data_size
Address of a variable that specifies the size of the buffer pointed to by the face_data parameter. The size is given in units of DWORD values. This parameter cannot be NULL.
face_data
Address of the face data for the Direct3DRMMeshBuilder3 object. This data is in the same format as specified in the IDirect3DRMMeshBuilder3::AddFaces method except that it is null-terminated. If this parameter is NULL, the method returns the required size of the face-data buffer in the face_data_size parameter.

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 was introduced with DirectX version 6.0. The IDirect3DRMMeshBuilder and IDirect3DRMMeshBuilder2 interfaces provided this functionality through the GetVertices method. The old method was renamed to GetGeometry with the IDirect3DRMMeshBuilder3 interface to better describe what this method does and to avoid conflicts with the new GetVertices method.

IDirect3DRMMeshBuilder3::GetNormal

IDirect3DRMMeshBuilder3

Retrieves a normal vector.

Syntax

HRESULT GetNormal
(DWORD dwIndex,
LPD3DVECTOR lpVector);

Parameters

dwIndex

Index of the normal to return.

lpVector

Pointer to a D3DVECTOR structure that will be filled in with the x-, y-, and z-coordinates of the normal.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMMeshBuilder3::GetNormalCount

IDirect3DRMMeshBuilder3

Returns the number of normals in the Direct3DRMMeshBuilder3 object.

Syntax

DWORD GetNormalCount(void);

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

GetNormals and SetNormals

IDirect3DRMMeshBuilder3::GetNormals

IDirect3DRMMeshBuilder3

Retrieves an array of normals that have previously been defined in the Direct3DRMMeshBuilder3 object.

Syntax

HRESULT GetNormals(
  DWORD dwFirst,
  LPDWORD lpdwCount,
  LPD3DVECTOR lpdvVector);

Parameters

dwFirst

Index of the first normal to be returned.

lpdwCount

Pointer to a DWORD containing the number of normals expected to be returned. If lpdvVector is NULL, this parameter receives the number of normals available, starting from the index given in dwFirst. If lpdvVector is not NULL, this parameter contains the number of normals actually retrieved. To ensure that you receive all the available normals, starting from dwFirst, call this method with lpdvVector set to NULL, then use the value returned in lpdwCount to size the array in lpdvVector, and call the method again.

lpdvVector

Pointer to an array of vectors to receive the normal data.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

GetNormalCount and SetNormals

IDirect3DRMMeshBuilder3::GetParentMesh

IDirect3DRMMeshBuilder3

Retrieves a parent mesh of this Direct3DRMMeshBuilder3 object. If the current mesh is not a submesh, this method retrieves a pointer to its own IUnknown interface.

Syntax

HRESULT GetParentMesh(
  DWORD dwFlags,
  LPUNKNOWN  *lplpUnk);

Parameters

dwFlags

Flag value that defines which Direct3DRMMeshBuilder3 object to retrieve. The currently defined flags are:

D3DRMMESHBUILDER_DIRECTPARENT

This Direct3DRMMeshBuilder3 object's direct parent.

D3DRMMESHBUILDER_ROOTMESH

The final parent of this Direct3DRMMeshBuilder3 object that has no parent.

lplpUnk

Address of a pointer to receive the parent's IUnknown interface.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

GetSubMeshes

IDirect3DRMMeshBuilder3::GetPerspective

IDirect3DRMMeshBuilder3

Determines whether perspective correction is on for a Direct3DRMMeshBuilder3 object.

Syntax

BOOL GetPerspective( );

Return Value

Returns TRUE if perspective correction is on, or FALSE otherwise.

IDirect3DRMMeshBuilder3::GetQuality

IDirect3DRMMeshBuilder3

Retrieves the rendering quality of a Direct3DRMMeshBuilder3 object.

Syntax

D3DRMRENDERQUALITY GetQuality( );

Return Value

Returns a member of the D3DRMRENDERQUALITY enumerated type that specifies the rendering quality of the mesh.

See Also

IDirect3DRMMeshBuilder3::SetQuality

IDirect3DRMMeshBuilder3::GetSubMeshes

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT GetSubMeshes(
  LPDWCOUNT lpdwCount,
  LPUNKNOWN lpUnk);

Parameters

lpdwCount

Pointer to a DWORD value containing the number of IUnknown interface pointers expected to be returned. If lpUnk is NULL, the value pointed to by lpdwCount receives the number of pointers available. Otherwise, the value pointed to by lpdwCount receives the number of IUnknown pointers actually retrieved.

lpUnk

Array of IUnknown pointers to child submeshes

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

GetParentMesh

IDirect3DRMMeshBuilder3::GetTextureCoordinates

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT GetTextureCoordinates(
  DWORD index,
  D3DVALUE *lpU,
  D3DVALUE *lpV
  );

Parameters

index
Index of the vertex.
lpU and lpV
Addresses of variables that will be filled with the texture coordinates of the vertex 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

IDirect3DRMMeshBuilder3::SetTextureCoordinates

IDirect3DRMMeshBuilder3::GetVertex

IDirect3DRMMeshBuilder3

Retrieves a vertex vector.

Syntax

HRESULT GetVertex
(DWORD dwIndex,
LPD3DVECTOR lpVector);

Parameters

dwIndex

Index of the vertex to return.

lpVector

Pointer to a D3DVECTOR structure that will be filled in with the x-, y-, and z-coordinates of the vertex.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMMeshBuilder3::GetVertexColor

IDirect3DRMMeshBuilder3

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

Syntax

D3DCOLOR GetVertexColor(
  DWORD index
  );

Parameters

index
Index of the vertex.

Return Value

Returns the color.

See Also

IDirect3DRMMeshBuilder3::SetVertexColor

IDirect3DRMMeshBuilder3::GetVertexCount

IDirect3DRMMeshBuilder3

Retrieves the number of vertices in a Direct3DRMMeshBuilder3 object.

Syntax

int GetVertexCount( );

Return Value

Returns the number of vertices.

IDirect3DRMMeshBuilder3::GetVertices

IDirect3DRMMeshBuilder3

Retrieves an array of vertices that previously have been defined in the Direct3DRMMeshBuilder3 object.

Syntax

HRESULT GetVertices(
  DWORD dwFirst,
  LPDWORD lpdwCount,
  LPD3DVECTOR lpdvVector);

Parameters

dwFirst

Index of the first vertex to be returned.

lpdwCount

Pointer to a DWORD value containing the number of vectors expected to be returned. If lpdvVector is NULL, the DWORD value receives the number of vertices available from the given offset. Otherwise, the DWORD value receives the number of vectors actually retrieved.

lpdvVector

Pointer to an array of vectors that will be initialized with the vertex data.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0 and is different from the GetVertices method that the old IDirect3DRMMeshBuilder and IDirect3DRMMeshBuilder2 interfaces provide. For IDirect3DRMMeshBuilder3, the older method has been renamed to GetGeometry, which better describes its function.

See Also

SetVertices and GetGeometry

IDirect3DRMMeshBuilder3::Load

IDirect3DRMMeshBuilder3

Loads a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpvArg
  );

Parameters

lpvObjSource
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 d3drmLOFlags parameter.
lpvObjID
Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadTextureProc
A D3DRMLOADTEXTURE3CALLBACK callback function used to load any textures used by an object that require special formatting. This parameter can be NULL.
lpvArg
Address of application-defined data passed to the D3DRMLOADTEXTURE3CALLBACK callback function.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

By default, this method loads the first mesh from the source specified in the lpvObjSource parameter.
This method respects the right-handed and left-handed geometry options as set by IDirect3DRM3::SetOptions.
You can load more than one object into a MeshBuilder by calling its load method multiple times.

*dwFlags*	Required face tuple format
0	{<n>, <vIndex0>, <nIndex0>,...,<vIndexn-1>, <nIndexn-1>}
D3DRMADDFACES_VERTICESONLY	{<n>, <vIndex0>,...,<vIndexn-1>}

Vertex Number	dwType 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_FAN
9	D3DRMVERTEX_LIST
10	D3DRMVERTEX_LIST
11	D3DRMVERTEX_LIST
12	D3DRMVERTEX_LIST
13	D3DRMVERTEX_LIST
14	D3DRMVERTEX_LIST