Direct3DRMProgressiveMesh

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. For more information about meshes, see Direct3DRMMesh.

A progressive mesh is a mesh that is stored as a base mesh (a coarse version) and a set of vertex split records that are used to increasingly refine the mesh. In other words, it enables progressive refinement. This enables you to set the level of detail rendered for a mesh and also enables progressive download from remote sources.

The progressive mesh is a visual in Microsoft® Direct3D® Retained Mode and can be used in the standard ways that visuals are used. That is, a progressive mesh can be added to frame hierarchies, instantiated a multiple number of times, and picked.

Using the methods of the Direct3DRMProgressiveMesh interface, you can set the number of vertices or faces to render, and thereby control, the render detail. You can also specify a minimum level of detail required for rendering. Normally, a progressive mesh is rendered when the base mesh is available, but with the Direct3DRMProgressiveMesh.SetMinRenderDetail method you can specify that a greater level of detail is necessary before rendering. You can also build a Direct3DRMMesh object from a particular state of the progressive mesh by using the Direct3DRMProgressiveMesh.CreateMesh method.

You can load a progressive mesh from a file, resource, memory, or URL. Loading can be done synchronously or asynchronously. You can check the status of a download with the Direct3DRMProgressiveMesh.GetLoadStatus method, and terminate a download with the Direct3DRMProgressiveMesh.Abort method. If loading is asynchronous, it is up to the application to use events through the Direct3DRMProgressiveMesh.RegisterEvents and Direct3DRMProgressiveMesh.GetLoadStatus methods to find out how the load is progressing.

The Direct3DRMProgressiveMesh object is created by using the Direct3DRM3.CreateProgressiveMesh method. After creation, the object can be added to a hierarchy, but will not render until at least the base mesh is available.

The methods of the Direct3DRMProgressiveMesh interface can be organized into the following groups.

Creating and Copying Meshes CreateMesh
Duplicate
GetBox
Loading Abort
GetLoadStatus
LoadFromFile
Setting Quality SetQuality
GetQuality
Managing Details GetDetail
GetFaceDetail
GetFaceDetailRange
GetVertexDetail
GetVertexDetailRange
SetDetail
SetFaceDetail
SetMinRenderDetail
SetVertexDetail
Registering Events RegisterEvents

The Direct3DRMProgressiveMesh interface inherits the following methods from the Direct3DRMObject interface.
AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMProgressiveMesh.Abort

Direct3DRMProgressiveMesh

Terminates the currently active download.

Syntax

object.Abort( )

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If the base mesh has been downloaded before this method is used, the effect is as if the progressive mesh has loaded, the vertex splits are in a valid state, and the progressive mesh is renderable. The other progressive mesh methods will work. If the base mesh has not been downloaded before the Direct3DRMProgressiveMesh.Abort call and you have added the progressive mesh to a scene, the Direct3DRMViewport2.Render method will succeed, but the progressive mesh will not be rendered. Also, if the base mesh has not been downloaded when you try to use the progressive mesh (to create a mesh or clone, for example) the call will return D3DRMERR_NOTENOUGHDATA.

If there are any outstanding events, they are signaled.

Direct3DRMProgressiveMesh.CreateMesh

Direct3DRMProgressiveMesh

Builds a mesh from the current level of detail.

Syntax

object.CreateMesh( ) As Direct3DRMMesh

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.

Return Value

Returns the newly generated Direct3DRMMesh object.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If the application has requested a level of detail that is not yet available or if the base mesh is not yet available, this method returns the error D3DRMERR_NOTENOUGHDATA.

Direct3DRMProgressiveMesh.Duplicate

Direct3DRMProgressiveMesh

Creates a copy of the Direct3DRMProgressiveMesh object. The copy shares all geometry and face data with the original, but has a detail level that can be set independently of the original. This enables the same mesh data to be used in different parts of the hierarchy but with different levels of detail. In essence, you almost have two instances of a progressive mesh within the frame hierarchy.

Syntax

object.Duplicate( ) As Direct3DRMProgressiveMesh

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.

Return Value

Returns the newly generated Direct3DRMProgressiveMesh object.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

The progressive mesh being duplicated must have at least its base mesh loaded. If you use this method on a progressive mesh that is currently being asynchronously loaded, the duplicated mesh only has as much detail as the loading progressive mesh had at the time it was duplicated. Any vertex splits loaded after the duplication are not available to the duplicated mesh.

A progressive mesh has a set of data representing the base mesh and a set of data representing the vertex splits. The base mesh data and data describing the current state of the progressive mesh and the current level of detail aren't shared between meshes that are duplicated, but the vertex splits are.

Direct3DRMProgressiveMesh.GetBox

Direct3DRMProgressiveMesh

Retrieves the bounding box containing a Direct3DRMProgressiveMesh object. The bounding box gives the minimum and maximum coordinates relative to a child frame, in each dimension.

Syntax

object.GetBox(box As D3DRMBOX)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
box
A D3DRMBOX type that will be filled with the bounding box coordinates.

Error Values

For a list of possible return codes, see Direct3D Retained Mode Error Values.

Direct3DRMProgressiveMesh.GetDetail

Direct3DRMProgressiveMesh

Returns the current detail level of the progressive mesh normalized between 0.0 and 1.0.

Syntax

object.GetDetail( ) As Single

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.

Return Value

Returns a value that will be filled with the current detail level of the progressive mesh.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If the base mesh has not yet downloaded, this method will return D3DRMERR_PENDING. If a requested level of detail has been set, the return value will increase on each subsequent call until the requested level has been met. If no level has been requested, the detail will increase until all vertex splits have been downloaded.

The normalized value 0.0 represents the minimum number of vertices (the number of vertices in the base mesh), and the normalized value 1.0 represents the maximum number of vertices.

Direct3DRMProgressiveMesh.GetFaceDetail

Direct3DRMProgressiveMesh

Retrieves the number of faces in the progressive mesh.

Syntax

object.GetFaceDetail( ) As Long

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.

Return Value

Returns a value that will be filled in with the number of faces in the progressive mesh.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If the number of faces is not available, this method returns D3DRMERR_PENDING.

Direct3DRMProgressiveMesh.GetFaceDetailRange

Direct3DRMProgressiveMesh

Retrieves the minimum and maximum face count available in the progressive mesh.

Syntax

object.GetFaceDetailRange(min As Long,
  max As Long)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
min
Value that will be filled in with the minimum number of faces.
max
Value that will be filled in with the maximum number of faces.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If the face count is not available, this method returns D3DRMERR_PENDING.

Direct3DRMProgressiveMesh.GetLoadStatus

Direct3DRMProgressiveMesh

Allows the application to inquire about the current status of the load.

Syntax

object.GetLoadStatus(loadStatus As D3DRMPMESHLOADSTATUS)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
loadStatus
A D3DRMPMESHLOADSTATUS type that indicates the loading status of the progressive mesh.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Direct3DRMProgressiveMesh.GetQuality

Direct3DRMProgressiveMesh

Retrieves a value indicating the rendering quality of the progressive mesh.

Syntax

object.GetQuality( ) As CONST_D3DRMRENDERQUALITY

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.

Return Value

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

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

See Also

Direct3DRMProgressiveMesh.SetQuality

Direct3DRMProgressiveMesh.GetVertexDetail

Direct3DRMProgressiveMesh

Retrieves the number of vertices in the progressive mesh.

Syntax

object.GetVertexDetail( ) As Long

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.

Return Value

Returns a value that will be filled in with the number of vertices in the progressive mesh.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If the number of vertices is not available, this method returns D3DRMERR_PENDING.

Direct3DRMProgressiveMesh.GetVertexDetailRange

Direct3DRMProgressiveMesh

Retrieves the minimum and maximum vertex count available in the progressive mesh.

Syntax

object.GetVertexDetailRange(min As Long,
  max As Long)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
min
Value that will be filled in with the minimum number of vertices.
max
Value that will be filled in with the maximum number of vertices.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If the vertex count information is not available, this method returns D3DRMERR_PENDING.

Direct3DRMProgressiveMesh.LoadFromFile

Direct3DRMProgressiveMesh

Loads the progressive mesh object from memory, a file, a resource, or a URL. Loading can be done synchronously or asynchronously.

Syntax

object.LoadFromFile(sFile As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As Object)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
sFile
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 options parameter.
id
Object name or position to be loaded. If id is "", you must set the options parameter to D3DRMLOAD_FIRST. Note that Microsoft Visual Basic® will accept an Integer in the id parameter, indicating the position of the item to be loaded, even though a String data type is specified. For example, placing 1 in the id parameter will load the object in the first position.
options
One or more values from the CONST_D3DRMLOADFLAGS enumerated type describing how the load is to be performed.
loadTextureImplementation
Direct3DRMLoadTextureCallback3 callback interface that will be used to load any texture encountered. Textures must have a width and length divisible by two. The callback will be used with the texture name as encountered by the loader and the user-defined args parameter. A new thread is not spawned for the callback.
userArgument
User-defined data passed to the callback.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

The progressive mesh is not useful unless it has been initialized. If asynchronous download is specified, the API returns immediately, and a separate thread is spawned to perform the download. It is up to the application to use events with Direct3DRMProgressiveMesh.RegisterEvents and Direct3DRMProgressiveMesh.GetLoadStatus to find out how the load is progressing.

This method and the Direct3DRMProgressiveMesh.Duplicate method initialize a progressive mesh. You can only initialize an object once. Therefore, you cannot clone or duplicate a progressive mesh and then try to load into the cloned or duplicated mesh, nor can you load into a previously loaded mesh.

Direct3DRMProgressiveMesh.RegisterEvents

Direct3DRMProgressiveMesh

Allows the application to register events with the progressive mesh object that will be signaled when the appropriate conditions are met.

Syntax

object.RegisterEvents(hEvent As Long,
  flags As Long,
  reserved As Long)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
hEvent
Event to be signaled when the required condition is met.
flags
One or more values from the CONST_D3DRMPMESHSTATUSFLAGS enumerated type.
reserved
Must be zero.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

This method can be used to monitor the progress of loads. Events will also be signaled if an error occurs, so your application should always use the Direct3DRMProgressiveMesh.GetLoadStatus method after being signaled.

Direct3DRMProgressiveMesh.SetDetail

Direct3DRMProgressiveMesh

Sets a requested level of detail normalized between 0.0 (minimum detail) and 1.0 (maximum detail).

Syntax

object.SetDetail(detail As Single)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
detail
Requested level of detail.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If not enough detail has been downloaded yet (but will be available), the request is acknowledged and D3DRMERR_PENDING is returned. This error is informational and indicates that the requested level will be set as soon as enough detail is available.

The normalized value 0.0 represents the minimum number of vertices (the number of vertices in the base mesh), and the normalized value 1.0 represents the maximum number of vertices.

Direct3DRMProgressiveMesh.SetFaceDetail

Direct3DRMProgressiveMesh

Sets the requested level of face detail.

Syntax

object.SetFaceDetail(count As Long)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
count
Number of faces requested.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

Sometimes it is not possible to set the progressive mesh to the number of faces requested, though it will always be within one of the requested value. This is because a vertex split can add one or two faces. For example, if you use SetFaceDetail(20), the progressive mesh may only be able to set the face detail to 19 or 21. You can always get the actual number of faces in the progressive mesh by using the Direct3DRMProgressiveMesh.GetFaceDetail method.

If not enough detail has been downloaded yet (but will be available), the request is acknowledged and D3DRMERR_PENDING is returned. This error is informational and indicates that the requested level will be set as soon as enough detail is available. If the detail requested is greater that the detail available in the progressive mesh, D3DRMERR_REQUESTTOOLARGE is returned.

See Also

Direct3DRMProgressiveMesh.GetFaceDetail

Direct3DRMProgressiveMesh.SetMinRenderDetail

Direct3DRMProgressiveMesh

Sets the minimum level of detail that will be rendered during a load from 0.0 (minimum detail) to 1.0 (maximum detail). Normally, the progressive mesh will be rendered after the base mesh is available (and the mesh is in the scene graph).

Syntax

object.SetMinRenderDetail(val As Single)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
val
Requested minimum detail.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

This method sets the minimum number of faces/vertices that will be rendered during the load. The value is in addition to those that are already rendered in the base mesh.

Any subsequent Direct3DRMProgressiveMesh.SetDetail, Direct3DRMProgressiveMesh.SetFaceDetail, or Direct3DRMProgressiveMesh.SetVertexDetail calls will override this.

Direct3DRMProgressiveMesh.SetQuality

Direct3DRMProgressiveMesh

Sets the rendering quality of a Direct3DRMProgressiveMesh object.

Syntax

object.SetQuality(quality As CONST_D3DRMRENDERQUALITY)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
quality
Member of the CONST_D3DRMRENDERQUALITY enumerated type that specifies the new rendering quality to use.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

An object's quality has three components: shade mode (flat or Gouraud; Phong 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 the Direct3DRMDevice3.SetQuality method. By default, the quality is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMProgressiveMesh object with the SetQuality method. By default, a Direct3DRMProgressiveMesh object's quality is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Tip: Gouraud shading performs better 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, 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, 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

Direct3DRMProgressiveMesh.GetRenderQuality

Direct3DRMProgressiveMesh.SetVertexDetail

Direct3DRMProgressiveMesh

Sets the requested level of vertex detail.

Syntax

object.SetVertexDetail(count As Long)

Parts

object
Object expression that resolves to a Direct3DRMProgressiveMesh object.
count
Number of vertices requested.

Error Values

For a list of possible errors, see Direct3D Retained Mode Error Values.

Remarks

If not enough detail has been downloaded yet (but will be available), the request will be acknowledged and D3DRMERR_PENDING is returned. This error is informational and indicates that the requested level will be set as soon as enough detail is available. If the detail requested is greater than the detail available in the progressive mesh, D3DRMERR_REQUESTTOOLARGE is returned.

See Also

Direct3DRMProgressiveMesh.GetVertexDetail

Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.