IDirect3DRM3

Applications use the IDirect3DRM3 interface to create Direct3DRM3 objects and work with system-level variables. For a history of the Direct3D Retained Mode interfaces, see Interface Changes.

The methods of the IDirect3DRM3, IDirect3DRM2, and IDirect3DRM interfaces create the following objects:

• Animations and animation sets
• ClippedVisuals
• Devices
• Faces
• Frames
• Generic uninitialized objects
• Lights
• Materials
• Meshes and mesh builders
• Shadows
• Textures
• UserVisuals
• Viewports
• Wraps

Microsoft DirectX version 6.0 introduced the IDirect3DRM3 interface. IDirect3DRM3 supports all of the methods provided by the IDirect3DRM2 and IDirect3DRM interfaces and replaces these two older interfaces. It adds a flag parameter to IDirect3DRM2's CreateDeviceFromSurface, and adds RegisterClient, UnregisterClient, and CreateClippedVisual methods to the methods IDirect3DRM2 provides. IDirect3DRM3 also adds the GetOptions and SetOptions methods to set and retrieve whether left-handed or right-handed geometry should be used.

IDirect3DRM3, like IDirect3DRM2, supports all the methods in IDirect3DRM. It adds the CreateProgressiveMesh method to the methods IDirect3DRM provides. The CreateDeviceFromSurface, CreateDeviceFromD3D, and CreateDeviceFromClipper methods all create a DIRECT3DRMDEVICE2 object with IDirect3DRM2 and a DIRECT3DRMDEVICE3 object with IDirect3DRM3. The CreateViewport method creates a viewport on a DirectDRMDevice2 object. The LoadTexture and LoadTextureFromResource methods load a Direct3DRMTexture2 object with IDirect3DRM2 and a Direct3DRMTexture3 object with IDirect3DRM3.

To access the IDirect3DRM3 or IDirect3DRM2 Component Object Model (COM) interfaces, create an IDirect3DRM object with Direct3DRMCreate, then query for IDirect3DRM3 or IDirect3DRM2, respectively, from IDirect3DRM. You can also access the main Direct3D Retained Mode object directly using CoCreateInstance.

When you create a MeshBuilder object using the IDirect3DRM3 interface, the MeshBuilder uses the Immediate Mode DrawPrimitive interface for its implementation.

When you create Lights using the IDirect3DRM3 interface, they take advantage of the latest Immediate Mode functionality and use the D3DLIGHT2 structure.

Applications use the IDirect3DRMDevice3, IDirect3DRMDevice2, and IDirect3DRMDevice interfaces to interact with the output device. For more information about the capabilities of the output device when you create it using the IDirect3DRM3, IDirect3DRM2, or IDirect3DRM interfaces, see IDirect3DRMDevice3. For a conceptual overview of output devices, see Output Devices.

The methods of the IDirect3DRM3 interface can be organized into the following groups:

Animation	CreateAnimation
	CreateAnimationSet
Application-specific Data	RegisterClient
	UnregisterClient
Clipped Visuals	CreateClippedVisual
Devices	CreateDevice
	CreateDeviceFromClipper
	CreateDeviceFromD3D
	CreateDeviceFromSurface
	GetDevices
Enumeration	EnumerateObjects
Faces	CreateFace
Frames	CreateFrame
Lights	CreateLight
	CreateLightRGB
Materials	CreateMaterial
Meshes	CreateMesh
	CreateMeshBuilder
Miscellaneous	CreateObject
	CreateUserVisual
	GetNamedObject
	GetOptions
	Load
	SetOptions
	Tick
Progressive Meshes	CreateProgressiveMesh
Search paths	AddSearchPath
	GetSearchPath
	SetSearchPath
Shadows	CreateShadow
Textures	CreateTexture
	CreateTextureFromSurface
	LoadTexture
	LoadTextureFromResource
	SetDefaultTextureColors
	SetDefaultTextureShades
Viewports	CreateViewport
Wraps	CreateWrap

The IDirect3DRM3 interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

AddRef

QueryInterface

Release

IDirect3DRM3::AddSearchPath

---

IDirect3DRM3

Adds a list of directories to the end of the current file search path.

Syntax

HRESULT AddSearchPath(
  LPCSTR lpPath
  );

Parameters

lpPath

Address of a null-terminated string specifying the path to add to the current search path.

Return Value

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

Remarks

For Microsoft® Windows®, the path should be a list of directories separated by semicolons (;).

See Also

IDirect3DRM3::SetSearchPath

IDirect3DRM3::CreateAnimation

---

IDirect3DRM3

Creates an empty Direct3DRMAnimation object.

Syntax

HRESULT CreateAnimation(
  LPDIRECT3DRMANIMATION2  *lplpD3DRMAnimation
  );

Parameters

lplpD3DRMAnimation

Address that will be filled with a pointer to an IDirect3DRMAnimation2 interface if the call succeeds.

Return Value

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

IDirect3DRM3::CreateAnimationSet

---

IDirect3DRM3

Creates an empty Direct3DRMAnimationSet object.

Syntax

HRESULT CreateAnimationSet (
  LPDIRECT3DRMANIMATIONSET2  *lplpD3DRMAnimationSet
  );

Parameters

lplpD3DRMAnimationSet

Address that will be filled with a pointer to an IDirect3DRMAnimationSet2 interface if the call succeeds.

Return Value

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

IDirect3DRM3::CreateClippedVisual

---

IDirect3DRM3

Creates a clipped visual object.

Syntax

HRESULT CreateClippedVisual(
  LPDIRECT3DRMVISUAL lpVisual,
  LPDIRECT3DRMCLIPPEDVISUAL  *lpClippedVisual);

Parameters

lpVisual

Pointer to a visual object, such as a meshbuilder object.

lpClippedVisual

Pointer to receive the created IDirect3DRMClippedVisual clipped visual 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.

IDirect3DRM3::CreateDevice

---

IDirect3DRM3

Not implemented on the Windows platform.

Syntax

HRESULT CreateDevice(
  DWORD dwWidth,
  DWORD dwHeight,
  LPDIRECT3DRMDEVICE3 *lplpD3DRMDevice
  );

IDirect3DRM3::CreateDeviceFromClipper

---

IDirect3DRM3

Creates a Direct3D Retained Mode Windows device by using a specified DirectDrawClipper object.

Syntax

HRESULT CreateDeviceFromClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper,
  LPGUID lpGUID,
  int width,
  int height,
  LPDIRECT3DRMDEVICE3  *lplpD3DRMDevice
  );

Parameters

lpDDClipper

Address of a DirectDrawClipper object.

lpGUID

Address of a globally unique identifier (GUID). This parameter can be NULL.

width and height

Width and height of the device to be created.

lplpD3DRMDevice

Address that will be filled with a pointer to an IDirect3DRMDevice3 interface if the call succeeds.

Return Value

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

Remarks

If the lpGUID parameter is NULL, the system searches for a device with a default set of device capabilities. This is the recommended way to create a Retained Mode device because it always works, even if the user installs new hardware.

The system describes the default settings by using the following flags from the D3DPRIMCAPS structure in internal device-enumeration calls:

D3DPSHADECAPS_ALPHAFLATSTIPPLED

D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE

D3DPMISCCAPS_CULLCCW

D3DPRASTERCAPS_FOGVERTEX

D3DPCMPCAPS_LESSEQUAL

D3DPTFILTERCAPS_NEAREST

D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY

D3DPTADDRESSCAPS_WRAP

If a hardware device is not found, the monochromatic (ramp) software driver is loaded. An application should enumerate devices instead of specifying NULL in the lpGUID parameter if it has special needs that are not met by this list of default settings.

For more information about devices, see Output Devices and IDirect3DRMDevice3.

IDirect3DRM3::CreateDeviceFromD3D

---

IDirect3DRM3

Creates a Direct3D Retained Mode Windows device by using specified Direct3D objects.

Syntax

HRESULT CreateDeviceFromD3D(
  LPDIRECT3D2 lpD3D,
  LPDIRECT3DDEVICE2 lpD3DDev,
  LPDIRECT3DRMDEVICE3  *lplpD3DRMDevice
  );

Parameters

lpD3D

Pointer to an instance of a Direct3D Immediate Mode Direct3D2 object.

lpD3DDev

Pointer to a Direct3D Immediate Mode Direct3DDevice2 object.

lplpD3DRMDevice

Address that will be filled with a pointer to an IDirect3DRMDevice3 interface if the call succeeds.

Return Value

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

Remarks

For more information about devices, see Output Devices and IDirect3DRMDevice3.

IDirect3DRM3::CreateDeviceFromSurface

---

IDirect3DRM3

Creates a Direct3D Retained Mode Windows device for rendering from the specified DirectDraw surfaces.

Syntax

HRESULT CreateDeviceFromSurface(  
  LPGUID lpGUID,
  LPDIRECTDRAW lpDD,
  LPDIRECTDRAWSURFACE lpDDSBack,
  DWORD dwFlags,
  LPDIRECT3DRMDEVICE3 *lplpD3DRMDevice);

Parameters

lpGUID

Address of the globally unique identifier (GUID) used as the required device driver. If this parameter is NULL, the default device driver is used.

lpDD

Address of the DirectDraw object that is the source of the DirectDraw surface.

lpDDSBack

Address of the DirectDrawSurface object that represents the back buffer.

dwFlags

The only currently defined flag is:

D3DRMDEVICE_NOZBUFFER

Indicates that if the lpDDSBack parameter has no z-buffer attached, no z-buffer is to be created. By default, a z-buffer will be created.

lplpD3DRMDevice

Address that will be filled with a pointer to an IDirect3DRMDevice3 interface if the call succeeds.

Return Value

Returns one of the following values:
 

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

DD_OK

Remarks

This method was introduced with DirectX version 6.0. This method adds the dwFlags parameter to the older IDirect3DRM2::CreateDeviceFromSurface method which it replaces.

For more information about devices, see Output Devices and IDirect3DRMDevice3.

IDirect3DRM3::CreateFace

---

IDirect3DRM3

Creates an instance of the IDirect3DRMFace2 interface.

Syntax

HRESULT CreateFace(
  LPDIRECT3DRMFACE2  *lplpd3drmFace2
  );

Parameters

lplpd3drmFace2

Address that will be filled with a pointer to an IDirect3DRMFace2 interface if the call succeeds.

Return Value

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

IDirect3DRM3::CreateFrame

---

IDirect3DRM3

Creates a new child frame of the given parent frame.

Syntax

HRESULT CreateFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame,
  LPDIRECT3DRMFRAME3 *lplpD3DRMFrame
  );

Parameters

lpD3DRMFrame

Address of a IDirect3DRMFrame3 object that is to be the parent of the new frame.

lplpD3DRMFrame

Address that will be filled with a pointer to an IDirect3DRMFrame3 interface if the call succeeds.

Return Value

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

Remarks

The child frame inherits the motion attributes of its parent. For example, if the parent is moving with a given velocity, the child frame will also move with that velocity. Furthermore, if the parent is set rotating, the child frame will rotate about the origin of the parent. Frames that have no parent are called scenes. To create a scene, specify NULL as the parent. An application can create a frame with no parent and then associate it with a parent frame later by using the IDirect3DRMFrame3::AddChild method.

If an application calls IDirect3DRM3::SetOptions to set right-handed geometry, the default axes for root frames (frames with NULL as the parent) becomes v = (0, 0, -1) and u = (0, 1, 0). Therefore IDirect3DRMFrame3::GetOrientation and IDirect3DRMFrame3::SetOrientation work correctly in right-handed mode.

See Also

IDirect3DRMFrame3::AddChild

IDirect3DRM3::CreateLight

---

IDirect3DRM3

Creates a new light source with the given type and color.

Syntax

HRESULT CreateLight(
  D3DRMLIGHTTYPE d3drmltLightType,
  D3DCOLOR cColor,
  LPDIRECT3DRMLIGHT *lplpD3DRMLight
  );

Parameters

d3drmltLightType

One of the lighting types given in the D3DRMLIGHTTYPE enumerated type.

cColor

Color of the light.

lplpD3DRMLight

Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.

Return Value

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

IDirect3DRM3::CreateLightRGB

---

IDirect3DRM3

Creates a new light source with the given type and color.

Syntax

HRESULT CreateLightRGB(
  D3DRMLIGHTTYPE ltLightType,
  D3DVALUE vRed,
  D3DVALUE vGreen,
  D3DVALUE vBlue,
  LPDIRECT3DRMLIGHT *lplpD3DRMLight
  );

Parameters

ltLightType

One of the lighting types given in the D3DRMLIGHTTYPE enumerated type.

vRed, vGreen, and vBlue

Color of the light. Each component of the color should be in the range 0.0 to 1.0.

lplpD3DRMLight

Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.

Return Value

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

Remarks

The following code fragment calls CreateLightRGB to create a bright directional light. It assumes the Direct3D Retained Mode object has already been created using the Direct3DRMCreate function.

LPDIRECT3DRM3 lpD3DRM;
LPDIRECT3DRMLIGHT light;

if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_DIRECTIONAL,
                                   D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9),
                                   &light))
{
    // error
}

IDirect3DRM3::CreateMaterial

---

IDirect3DRM3

Creates a material with the given specular property.

Syntax

HRESULT CreateMaterial(
  D3DVALUE vPower,
  LPDIRECT3DRMMATERIAL2  *lplpD3DRMMaterial
  );

Parameters

vPower

Sharpness of the reflected highlights, with a value of 5 giving a metallic look and higher values giving a more plastic look to the rendered surface.

lplpD3DRMMaterial

Address that will be filled with a pointer to an IDirect3DRMMaterial2 interface if the call succeeds.

Return Value

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

IDirect3DRM3::CreateMesh

---

IDirect3DRM3

Creates a new mesh object with no faces. The mesh is not visible until it is added to a frame.

Syntax

HRESULT CreateMesh(
  LPDIRECT3DRMMESH *lplpD3DRMMesh
  );

Parameters

lplpD3DRMMesh

Address that will be filled with a pointer to an IDirect3DRMMesh interface if the call succeeds.

Return Value

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

IDirect3DRM3::CreateMeshBuilder

---

IDirect3DRM3

Creates a new mesh builder object.

Syntax

HRESULT CreateMeshBuilder(
  LPDIRECT3DRMMESHBUILDER3  *lplpD3DRMMeshBuilder3
  );

Parameters

lplpD3DRMMeshBuilder3

Address that will be filled with a pointer to an IDirect3DRMMeshBuilder3 interface if the call succeeds.

Return Value

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

Remarks

By default, perspective correction is on.

IDirect3DRM3::CreateObject

---

IDirect3DRM3

Creates a new object without initializing the object.

Syntax

HRESULT CreateObject(
  REFCLSID rclsid,
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID FAR *ppv
  );

Parameters

rclsid

Class identifier for the new object.

pUnkOuter

Pointer to the outer IUnknown that allows COM aggregation features.

riid

Interface identifier of the object to be created.

ppv

Address of a pointer to the object when the method returns.

Return Value

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

Remarks

An application that uses this method must initialize the object that has been created. (The other creation methods of the IDirect3DRM3 interface initialize the object automatically.) In some cases, for example, for Direct3DRMViewport2 objects, you can use the Init method for that object. An application should use the Init method only once to initialize any given object.

Applications can use this method to implement aggregation in Direct3DRM objects.

IDirect3DRM3::CreateProgressiveMesh

---

IDirect3DRM3

Creates a new progressive mesh object with no faces. The mesh is not visible until it is added to a frame.

Syntax

HRESULT CreateProgressiveMesh(
  LPDIRECT3DRMPROGRESSIVEMESH *lplpD3DRMProgressiveMesh
  );

Parameters

lplpD3DRMProgressiveMesh

Address that will be filled with a pointer to an IDirect3DRMProgressiveMesh interface if the call succeeds.

Return Value

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

IDirect3DRM3::CreateShadow

---

IDirect3DRM3

Creates a shadow by using the specified visual and light, projecting the shadow onto the specified plane. The shadow is a visual that should be added to the frame that contains the visual.

Syntax

HRESULT CreateShadow(
  LPUNKNOWN pUnk,
  LPDIRECT3DRMLIGHT lpLight,
  D3DVALUE px,
  D3DVALUE py,
  D3DVALUE pz,
  D3DVALUE nx,
  D3DVALUE ny,
  D3DVALUE nz,
  LPDIRECT3DRMSHADOW2  *lplpShadow
  );

Parameters

pUnk

Pointer to the object casting the shadow.

lpLight

Address of the IDirect3DRMLight interface that is the light source.

px, py, and pz

Plane that the shadow is to be projected on.

nx, ny, and nz

Normal to the plane that the shadow is to be projected on.

lplpShadow

Address of a pointer to be initialized with a valid pointer to the shadow visual, if the call succeeds.

Return Value

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

IDirect3DRM3::CreateTexture

---

IDirect3DRM3

Creates a texture from an image in memory.

Syntax

HRESULT CreateTexture(
  LPD3DRMIMAGE lpImage,
  LPDIRECT3DRMTEXTURE3 *lplpD3DRMTexture3
  );

Parameters

lpImage

Address of a D3DRMIMAGE structure describing the source for the texture.

lplpD3DRMTexture3

Address that will be filled with a pointer to an IDirect3DRMTexture3 interface if the call succeeds.

Return Value

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

Remarks

The memory associated with the image is used each time the texture is rendered, rather than the memory being copied into Direct3D Retained Mode buffers. This enables the image to be used both as a rendering target and as a texture.

IDirect3DRM3::CreateTextureFromSurface

---

IDirect3DRM3

Creates a texture from a specified DirectDraw surface.

Syntax

HRESULT CreateTextureFromSurface(
  LPDIRECTDRAWSURFACE lpDDS,
  LPDIRECT3DRMTEXTURE3  *lplpD3DRMTexture3
  );

Parameters

lpDDS

Address of the DirectDrawSurface object containing the texture.

lplpD3DRMTexture3

Address that will be filled with a pointer to an IDirect3DRMTexture3 interface if the call succeeds.

Return Value

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

Remarks

When you create a texture from a DirectDraw surface, it is best to create the surface in system memory. This enables optimal performance for software devices and allows Direct3D Retained Mode to manage the use of video memory more effectively for hardware devices.

IDirect3DRM3::CreateUserVisual

---

IDirect3DRM3

Creates an application-defined visual object, which can then be added to a scene and rendered by using an application-defined handler.

Syntax

HRESULT CreateUserVisual(
  D3DRMUSERVISUALCALLBACK fn,
  LPVOID lpArg,
  LPDIRECT3DRMUSERVISUAL  *lplpD3DRMUV
  );

Parameters

fn

Application-defined D3DRMUSERVISUALCALLBACK callback function.

lpArg

Address of application-defined data passed to the callback function.

lplpD3DRMUV

Address that will be filled with a pointer to an IDirect3DRMUserVisual interface if the call succeeds.

Return Value

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

See Also

IDirect3DRMUserVisual::Init

IDirect3DRM3::CreateViewport

---

IDirect3DRM3

Creates a viewport on a device with device coordinates (dwXPos, dwYPos) to (dwXPos + dwWidth, dwYPos + dwHeight).

Syntax

HRESULT CreateViewport(
  LPDIRECT3DRMDEVICE3 lpDev,
  LPDIRECT3DRMFRAME3 lpCamera,
  DWORD dwXPos,
  DWORD dwYPos,
  DWORD dwWidth,
  DWORD dwHeight,
  LPDIRECT3DRMVIEWPORT2 *lplpD3DRMViewport
  );

Parameters

lpDev

Address of a IDirect3DRMDevice3 device on which the viewport is to be created.

lpCamera

Address of a frame that describes the position and direction of the view.

dwXPos, dwYPos, dwWidth, and dwHeight

Position and size of the viewport, in device coordinates. The viewport size cannot be larger than the physical device or the method will fail.

lplpD3DRMViewport

Address that will be filled with a pointer to an IDirect3DRMViewport2 interface if the call succeeds.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. If the viewport size is larger than the physical device, returns D3DRMERR_BADVALUE. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The viewport displays objects in the scene that contains the camera, with the view direction and up vector taken from the camera. The viewport size cannot be larger than the physical device.

For more information about devices, see Output Devices and IDirect3DRMDevice3.

IDirect3DRM3::CreateWrap

---

IDirect3DRM3

Creates a wrapping function that can be used to assign texture coordinates to faces and meshes. The vector [ox oy oz] gives the origin of the wrap, [dx dy dz] gives its z-axis, and [ux uy uz] gives its y-axis. The 2-D vectors [ou ov] and [su sv] give an origin and scale factor in the texture applied to the result of the wrapping function.

Syntax

HRESULT CreateWrap(
  D3DRMWRAPTYPE type,
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE ox,
  D3DVALUE oy,
  D3DVALUE oz,
  D3DVALUE dx,
  D3DVALUE dy,
  D3DVALUE dz,
  D3DVALUE ux,
  D3DVALUE uy,
  D3DVALUE uz,
  D3DVALUE ou,
  D3DVALUE ov,
  D3DVALUE su,
  D3DVALUE sv,
  LPDIRECT3DRMWRAP *lplpD3DRMWrap
  );

Parameters

type

One of the members of the D3DRMWRAPTYPE enumerated type.

lpRef

Reference frame for the wrap.

ox, oy, and oz

Origin of the wrap.

dx, dy, and dz

The z-axis of the wrap.

ux, uy, and uz

The y-axis of the wrap.

ou and ov

Origin in the texture.

su and sv

Scale factor in the texture.

lplpD3DRMWrap

Address that will be filled with a pointer to an IDirect3DRMWrap interface if the call succeeds.

Return Value

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

See Also

IDirect3DRMWrap

IDirect3DRM3::EnumerateObjects

---

IDirect3DRM3

Uses the callback function specified by the func parameter on each of the active Direct3DRM objects.

Syntax

HRESULT EnumerateObjects(
  D3DRMOBJECTCALLBACK func,
  LPVOID lpArg
  );

Parameters

func

Application-defined D3DRMOBJECTCALLBACK callback function to be used with each Direct3DRMObject object and the application-defined argument.

lpArg

Address of application-defined data passed to the callback function.

Return Value

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

IDirect3DRM3::GetDevices

---

IDirect3DRM3

Returns all the Direct3DRM devices that have been created in the system.

Syntax

HRESULT GetDevices(
  LPDIRECT3DRMDEVICEARRAY *lplpDevArray
  );

Parameters

lplpDevArray

Address of a pointer that will be filled with the resulting array of Direct3DRM devices. For information about the Direct3DRMDeviceArray object, see the IDirect3DRMDeviceArray interface.

Return Value

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

IDirect3DRM3::GetNamedObject

---

IDirect3DRM3

Finds a Direct3DRMObject given the Direct3DRMObject name.

Syntax

HRESULT GetNamedObject(
  const char  *lpName,
  LPDIRECT3DRMOBJECT *lplpD3DRMObject
  );

Parameters

lpName

Name of the object to be searched for.

lplpD3DRMObject

Address of a pointer to be initialized with a valid Direct3DRMObject pointer if the call succeeds.

Return Value

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

Remarks

If the system does not find an object with the name specified in the lpName parameter, this method returns D3DRM_OK but the lplpD3DRMObject parameter is NULL.

IDirect3DRM3::GetOptions

---

IDirect3DRM3

Retrieves whether Direct3D Retained Mode uses left-handed or right-handed geometry.

Syntax

HRESULT GetOptions(
  LPDWORD lpdwOptions);

Parameters

lpdwOptions

Pointer to a flag value that indicates the current Direct3D Retained Mode options. Currently defined flags are:

D3DRMOPTIONS_LEFTHANDED

Use left-handed geometry. This value is the default.

D3DRMOPTIONS_RIGHTHANDED

Use right-handed geometry.

Return Value

Returns one of the following values:
 

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

D3DRMOPTIONS_LEFTHANDED and D3DRMOPTIONS_RIGHTHANDED affect the following objects as well as picking and ray picking.

• IDirect3DRMClippedVisual
• IDirect3DRMMesh
• IDirect3DRMMeshBuilder3
• IDirect3DRMProgressiveMesh
• IDirect3DRMShadow2
• IDirect3DRMTexture3
• IDirect3DRMViewport2

This method was introduced in DirectX version 6.0.

See Also

Direct3D Coordinate System

IDirect3DRM3::SetOptions

IDirect3DRM3::GetSearchPath

---

IDirect3DRM3

Returns the current search path. For Windows, the path is a list of directories separated by semicolons (;).

Syntax

HRESULT GetSearchPath(
  DWORD  *lpdwSize,
  LPSTR lpszPath
  );

Parameters

lpdwSize

Pointer to a DWORD. Should contain the length of lpszPath when GetSearchPath is used. On return, contains the length of the string in lpszPath containing the current search path. This parameter cannot be NULL.

lpszPath

A pointer to a null-terminated string specifying the search path. If lpszPath equals NULL when GetSearchPath is used, the method returns the length of the current string in the location pointed to by the lpdwSize parameter.

Return Value

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

See Also

IDirect3DRM3::SetSearchPath

IDirect3DRM3::Load

---

IDirect3DRM3

Loads an object.

Syntax

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  LPIID  *lplpGUIDs,
  DWORD dwcGUIDs,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADCALLBACK d3drmLoadProc,
  LPVOID lpArgLP,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP,
  LPDIRECT3DRMFRAME3 lpParentFrame
  );

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.

lplpGUIDs

Address of an array of interface identifiers to be loaded. For example, if this parameter is a two-element array containing IID_IDirect3DRMMeshBuilder3 and IID_IDirect3DRMAnimationSet2, this method loads all the animation sets and mesh-builder objects. Possible GUIDs must be one or more of the following: IID_IDirect3DRMProgressiveMesh, IID_IDirect3DRMMeshBuilder3, IID_IDirect3DRMAnimationSet2, IID_IDirect3DRMAnimation2, and IID_IDirect3DRMFrame3.

dwcGUIDs

Number of elements specified in the lplpGUIDs parameter.

d3drmLOFlags

Value of the D3DRMLOADOPTIONS type describing the load options.

d3drmLoadProc

A D3DRMLOAD3CALLBACK callback function used when the system reads the specified object.

lpArgLP

Address of application-defined data passed to the D3DRMLOADCALLBACK callback function.

d3drmLoadTextureProc

A D3DRMLOADTEXTURE3CALLBACK callback function used to load any textures used by an object that require special formatting. This parameter can be NULL.

lpArgLTP

Address of application-defined data passed to the D3DRMLOADTEXTURE3CALLBACK callback function.

lpParentFrame

Address of a parent Direct3DRMFrame object. This argument only affects the loading of animation sets. When an animation that is loaded from an .x file references an unparented frame in the .x file, the unparented frame's parent is set to the parent frame at lpParentFrame. However, if you use Load to load any frames in the .x file, the parent frame at lpParentFrame will not be used as the parent frame for frames in the .x file with no parent. That is, lpParentFrame is used only when you load animation sets. This value of lpParentFrame can be NULL.

Return Value

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

Remarks

By default, perspective correction is on.

This method allows great flexibility in loading objects from Microsoft® DirectX® files. Here is an example of how to use it:

Sample Code

#include <windows.h>
#include <stdio.h>
#include <initguid.h>
#include <d3drm.h>

LPDIRECT3DRM d3dApi;

int totalMesh = 0, totalAnim = 0, totalFrames = 0;

HRESULT loadTexture(LPSTR name, LPVOID lpArg, LPDIRECT3DRMTEXTURE *tex)
{
	return d3dApi->lpVtbl->LoadTexture(d3dApi, name, tex);
}

void loadCallback(LPDIRECT3DRMOBJECT lpObject, REFIID objGuid, LPVOID lpArg)
{
	if (IsEqualIID(objGuid, &IID_IDirect3DRMFrame3)) {
		totalFrames ++;
		return;
	}

	if (IsEqualIID(objGuid, &IID_IDirect3DRMAnimationSet2)) {
		totalAnim ++;
		return;
	}

	if (IsEqualIID(objGuid, &IID_IDirect3DRMMeshBuilder)) {
		totalMesh ++;
		return;
	}

	return;
}


BOOL loadObjects(LPSTR filename)
{
	LPGUID guids[] = { (LPGUID)&IID_IDirect3DRMMeshBuilder,
		(LPGUID)&IID_IDirect3DRMAnimationSet2,
		(LPGUID)&IID_IDirect3DRMFrame3 };

	/* Tell the loader which objects you're interested in */

	if (FAILED(d3dApi->lpVtbl->Load(d3dApi, filename, NULL, 
			guids, 3, D3DRMLOAD_FROMFILE,
			loadCallback, NULL, loadTexture, NULL, NULL)))
		return FALSE;

	printf("Total Frames loaded = %d\n", totalFrames);
	printf("Total Animation Sets loaded = %d\n", totalAnim);
	printf("Total Meshbuilders loaded = %d\n", totalMesh);

	return TRUE;
}

int main(int argc, char **argv)
{

	if (FAILED(Direct3DRMCreate(&d3dApi)))
		return FALSE;

	if (argc != 2) {
		fprintf(stderr, "usage: %s filename\n", argv[0]);
		return FALSE;
	}

	if (!loadObjects(argv[1])) return FALSE;
	
  return(0);
}

IDirect3DRM3::LoadTexture

---

IDirect3DRM3

Loads a Direct3DRMTexture2 texture from the specified file. This texture can have 8, 24, or 32 bits-per-pixel, and it should be in either the Windows bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

Syntax

HRESULT LoadTexture(
  const char  *lpFileName,
  LPDIRECT3DRMTEXTURE3 *lplpD3DRMTexture
  );

Parameters

lpFileName

Address of the name of the required .bmp or .ppm file.

lplpD3DRMTexture

Address of a pointer to be initialized with a valid IDirect3DRMTexture3 pointer if the call succeeds.

Return Value

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

Remarks

LoadTexture checks whether the texture is in BMP or PPM format, which are the formats it can load. If you want to load other formats, you can add code to the callback to load the image into a D3DRMIMAGE structure and then use IDirect3DRM3::CreateTexture.

If you write your own texture callback, the LoadTexture call in the texture callback does not take a reference to the texture. For example:

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE2 *tex)
{
    return lpD3DRM2->LoadTexture(name, tex);
}

In this sample, no reference is taken for tex. If you want to keep a reference to each texture loaded by your texture callback, you should AddRef the texture. For example:

LPDIRECT3DRMTEXTURE2 *texarray;

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE2 *tex)
{
	if (FAILED(lpD3DRM2->LoadTexture(name, tex)) {
		return NULL;
	}

	texArray[current++] = tex;
	tex->AddRef();

	return tex;
}

IDirect3DRM3::LoadTextureFromResource

---

IDirect3DRM3

Loads a Direct3DRMTexture2 texture from a specified resource.

Syntax

HRESULT LoadTextureFromResource(
  HMODULE hModule,
  LPCTSTR strName,
  LPCTSTR strType,
  LPDIRECT3DRMTEXTURE3  *lplpD3DRMTexture
  );

Parameters

hModule

Handle of the module whose executable file contains the resource.

strName

A null-terminated string specifying the name of the resource to be used as the texture.

strType

A null-terminated string specifying the type name of the resource. This parameter can be one of the following resource types or a user-defined type:

Value	Meaning
RT_BITMAP	Bitmap resource
RT_RCDATA	Application-defined resource (raw data)

lplpD3DRMTexture

Address of a pointer to be initialized with a valid IDirect3DRMTexture3 object if the call succeeds.

Return Value

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

IDirect3DRM3::RegisterClient

---

IDirect3DRM3

Registers a client (application) with which data can be associated.

Syntax

HRESULT RegisterClient(  
  REFGUID rguid,
  LPDWORD lpdwID);

Parameters

rguid

Reference to a GUID that represents the application.

lpdwID

Address that receives a unique ID that the application can use with IDirect3DRMObject2::SetClientData and IDirect3DRMObject2::GetClientData to associate data with the Retained Mode object.

Return Value

Returns one of the following values:
 

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

DD_OK

Remarks

The application passes a GUID and receives a DWORD identifier that can then be used with IDirect3DRMObject2::SetClientData and IDirect3DRMObject2::GetClientData to associate data with the Retained Mode object. When an application uses UnregisterClient, any data stored by the application by means of IDirect3DRMObject2::SetClientData is released in a manner dependent on its type. The same ID is returned for multiple invocations of this method with the same GUID. This method was introduced in DirectX version 6.0.

IDirect3DRM3::SetDefaultTextureColors

---

IDirect3DRM3

Sets the default colors to be used for a Direct3DRMTexture2 object.

Syntax

HRESULT SetDefaultTextureColors(
  DWORD dwColors
  );

Parameters

dwColors

Number of colors.

Return Value

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

Remarks

This method affects the texture colors only when it is used before the IDirect3DRM3::CreateTexture method; it has no effect on textures that have already been created.

IDirect3DRM3::SetDefaultTextureShades

---

IDirect3DRM3

Sets the default shades to be used for an Direct3DRMTexture2 object.

Syntax

HRESULT SetDefaultTextureShades(
  DWORD dwShades
  );

Parameters

dwShades

Number of shades.

Return Value

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

Remarks

This method affects the texture shades only when it is used before the IDirect3DRM3::CreateTexture method; it has no effect on textures that have already been created.

IDirect3DRM3::SetOptions

---

IDirect3DRM3

Sets whether Direct3D Retained Mode uses left-handed or right-handed geometry.

Syntax

HRESULT SetOptions(
  LPDWORD dwOptions);

Parameters

dwOptions

Flag value that indicates the current Direct3D Retained Mode options. Currently defined flags are:

D3DRMOPTIONS_LEFTHANDED

Use left-handed geometry. This value is the default.

D3DRMOPTIONS_RIGHTHANDED

Use right-handed geometry.

Return Value

Returns one of the following values:
 

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

D3DRMOPTIONS_LEFTHANDED and D3DRMOPTIONS_RIGHTHANDED affect the following objects as well as picking and ray picking.

• IDirect3DRMClippedVisual
• IDirect3DRMMesh
• IDirect3DRMMeshBuilder3
• IDirect3DRMProgressiveMesh
• IDirect3DRMShadow2
• IDirect3DRMTexture3
• IDirect3DRMViewport2

This method was introduced in DirectX version 6.0.

See Also

Direct3D Coordinate System

IDirect3DRM3::GetOptions

IDirect3DRM3::SetSearchPath

---

IDirect3DRM3

Sets the current file search path from a list of directories. For Windows, the path should be a list of directories separated by semicolons (;).

Syntax

HRESULT SetSearchPath(
  LPCSTR lpPath
  );

Parameters

lpPath

Address of a null-terminated string specifying the path to set as the current search path.

Return Value

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

Remarks

The default search path is taken from the value of the D3DPATH environment variable. If this is not set, the search path will be empty. When opening a file, the system first looks for the file in the current working directory and then checks every directory in the search path.

D3DPATH is an environment variable that sets the default search path.

See Also

IDirect3DRM3::GetSearchPath

IDirect3DRM3::Tick

---

IDirect3DRM3

Performs the Direct3DRM system heartbeat. When this method is used, the positions of all moving frames are updated according to their current motion attributes, the scene is rendered to the current device, and relevant callback functions are used at their appropriate times. Control is returned when the rendering cycle is complete.

Syntax

HRESULT Tick(
  D3DVALUE d3dvalTick
  );

Parameters

d3dvalTick

Velocity and rotation step for the IDirect3DRMFrame3::SetRotation and IDirect3DRMFrame3::SetVelocity methods.

Return Value

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

Remarks

You can implement this method by using other Retained Mode methods to allow more flexibility in rendering a scene.

IDirect3DRM3::UnregisterClient

---

IDirect3DRM3

Disassociates all data and object associations set by IDirect3DRMObject2::SetClientData and frees the data in a manner dependent on its type.

Syntax

HRESULT UnregisterClient(  
  REFGUID rguid);

Parameters

rguid

Reference to a GUID that represents the application.

Return Value

Returns one of the following values:
 

D3DRMERR_CLIENTNOTREGISTERED

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

---

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