IDirect3DRMMeshBuilder3 Methods N to Z

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

IDirect3DRMMeshBuilder3::Optimize

IDirect3DRMMeshBuilder3

Optimizes the MeshBuilder object for the current device. Note that this may be an expensive operation.

Syntax

HRESULT Optimize
(DWORD dwFlags);

Parameters

dwFlags

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::ReserveSpace

IDirect3DRMMeshBuilder3

Reserves space within a Direct3DRMMeshBuilder3 object for the specified number of vertices, normals, and faces. This allows the system to use memory more efficiently.

Syntax

HRESULT ReserveSpace(
  DWORD vertexCount,
  DWORD normalCount,
  DWORD faceCount
  );

Parameters

vertexCount, normalCount, and faceCount
Number of vertices, normals, and faces to allocate space for.

Return Value

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

IDirect3DRMMeshBuilder3::Save

IDirect3DRMMeshBuilder3

Saves a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT Save(
  const char * lpFilename,
  D3DRMXOFFORMAT d3drmXOFFormat,
  D3DRMSAVEOPTIONS d3drmSOContents
  );

Parameters

lpFilename
Address specifying the name of the created file. This file must have a .x file name extension.
d3drmXOFFormat
The D3DRMXOF_TEXT value from the D3DRMXOFFORMAT enumerated type.
d3drmSOContents
Value of the D3DRMSAVEOPTIONS type describing the save options.

Return Value

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

IDirect3DRMMeshBuilder3::Scale

IDirect3DRMMeshBuilder3

Scales a Direct3DRMMeshBuilder3 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.

IDirect3DRMMeshBuilder3::SetColor

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetColor(
  D3DCOLOR color
  );

Parameters

color
Color of the faces. Be sure to set the alpha component as well as the red, green, and blue color components or your objects might not be visible. The RGBA_MAKE DirectX macro allows you to specify these values.

Return Value

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

IDirect3DRMMeshBuilder3::SetColorRGB

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetColorRGB(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

Parameters

red, green, and blue
Red, green, and blue components of the color.

Return Value

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

IDirect3DRMMeshBuilder3::SetColorSource

IDirect3DRMMeshBuilder3

Sets the color source of a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT SetColorSource(
  D3DRMCOLORSOURCE source
  );

Parameters

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

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::GetColorSource

IDirect3DRMMeshBuilder3::SetMaterial

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetMaterial(
  LPDIRECT3DRMMATERIAL2 lpIDirect3DRMmaterial
  );

Parameters

lpIDirect3DRMmaterial
Address of IDirect3DRMMaterial2 interface for the Direct3DRMMeshBuilder3 object.

Return Value

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

IDirect3DRMMeshBuilder3::SetNormal

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetNormal(
  DWORD index,
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

Parameters

index
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.

Return Value

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

IDirect3DRMMeshBuilder3::SetNormals

IDirect3DRMMeshBuilder3

Sets the normals that previously have been defined in the Direct3DRMMeshBuilder3 object.

Syntax

HRESULT SetNormals(
  DWORD dwFirst,
  DWORD dwCount,
  LPD3DVECTOR lpdvVector);

Parameters

dwFirst

Index of the first normal to be modified.

dwCount

Number of normals to be modified.

lpdvVector

Array of vectors describing the new 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

GetNormals

IDirect3DRMMeshBuilder3::SetPerspective

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetPerspective(
  BOOL perspective
  );

Parameters

perspective
Specify TRUE if the mesh should be texture-mapped with perspective correction, or FALSE otherwise.

Return Value

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

IDirect3DRMMeshBuilder3::SetQuality

IDirect3DRMMeshBuilder3

Sets the rendering quality of a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT SetQuality(
  D3DRMRENDERQUALITY quality
  );

Parameters

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

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return 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, wireframe, or solid).
You can set the quality of a device with IDirect3DRMDevice3::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

IDirect3DRMMeshBuilder3::GetQuality

IDirect3DRMMeshBuilder3::SetTexture

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetTexture(
  LPDIRECT3DRMTEXTURE3 lpD3DRMTexture
  );

Parameters

lpD3DRMTexture
Address of the required Direct3DRMTexture object.

Return Value

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

IDirect3DRMMeshBuilder3::SetTextureCoordinates

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetTextureCoordinates(
  DWORD index,
  D3DVALUE u,
  D3DVALUE v
  );

Parameters

index
Index of the vertex to be set.
u and v
Texture coordinates to assign to the specified mesh vertex.

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::GetTextureCoordinates

IDirect3DRMMeshBuilder3::SetTextureTopology

IDirect3DRMMeshBuilder3

Sets the texture topology of a Direct3DRMMeshBuilder3 object.

Syntax

HRESULT SetTextureTopology(
  BOOL cylU,
  BOOL cylV
  );

Parameters

cylU and cylV
Specify 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 FALSE.

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 texture topology flags, cylU and cylV, control the settings of the Direct3D Immediate Mode render states D3DRENDERSTATE_WRAPU and D3DRENDERSTATE_WRAPV. When a wrap flag is 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 FALSE, nearly the full length of the texture will be rendered along the triangle. If WRAPV is TRUE, a sliver from the top of the texture and one from the bottom will be rendered. Additionally, when a wrap flag is 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 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 cylU and cylV parameters to 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 cylU and cylV to FALSE.
Several interfaces expose a SetTextureTopology method. IDirect3DRMMeshBuilder3::SetTextureTopology updates the topology on all component faces, overriding any settings made by IDirect3DRMFace2::SetTextureTopology. By default, IDirect3DRMFrame3::SetTexture reads from the mesh because the default material mode is D3DRMMATERIAL_FROMMESH. If the material mode is not D3DRMMATERIAL_FROMMESH, IDirect3DRMFrame3::SetTexture overrides settings made by IDirect3DRMMeshBuilder3::SetTextureTopology.

IDirect3DRMMeshBuilder3::SetVertex

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetVertex(
  DWORD index,
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

Parameters

index
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.

Return Value

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

IDirect3DRMMeshBuilder3::SetVertexColor

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetVertexColor(
  DWORD index,
  D3DCOLOR color
  );

Parameters

index
Index of the vertex to be set.
color
Color to assign to the specified vertex.

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::GetVertexColor

IDirect3DRMMeshBuilder3::SetVertexColorRGB

IDirect3DRMMeshBuilder3

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

Syntax

HRESULT SetVertexColorRGB(
  DWORD index,
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

Parameters

index
Index of the vertex to be set.
red, green, and blue
Red, green, and blue components of the color to assign to the specified vertex.

Return Value

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

IDirect3DRMMeshBuilder3::SetVertices

IDirect3DRMMeshBuilder3

Sets the vertices that previously have been defined in the Direct3DRMMeshBuilder3 object.

Syntax

HRESULT SetVertices(
  DWORD dwFirst,
  DWORD dwCount,
  LPD3DVECTOR lpdvVector);

Parameters

dwFirst

Index of the first vertex to be modified.

dwCount

Number of vertices to modify.

lpdvVector

Array of vectors describing the new 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.

See Also

GetVertices

IDirect3DRMMeshBuilder3::Translate

IDirect3DRMMeshBuilder3

Adds the specified offsets to the vertex positions of a Direct3DRMMeshBuilder3 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.