Direct3D Retained Mode Animated Header --IDirect3DRM2 Direct3D Retained Mode Animated Header --IDirect3DRM2 * Microsoft Direct3D Retained Mode SDK
*Index  *Topic Contents
*Previous Topic: IDirect3DRM
*Next Topic: IDirect3DRMAnimation

IDirect3DRM2


Applications use the methods of the IDirect3DRM2 interface to create Direct3DRM2 objects and work with system-level variables.

Applications use the methods of the IDirect3DRMDevice2 and IDirect3DRMDevice interfaces to interact with the output device. While the IDirect3DRMDevice interface, when created from the IDirect3DRM interface, works with an IDirect3DDevice Immediate Mode device, the IDirect3DRMDevice2 interface, when created from the IDirect3DRM2 interface or initialized by the IDirect3DRMDevice2::InitFromClipper, IDirect3DRMDevice2::InitFromD3D2, or IDirect3DRMDevice2::InitFromSurface method, works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface, as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

IDirect3DRM2 supports all the methods in IDirect3DRM. In addition, the IDirect3DRM2::CreateProgressiveMesh method had been added. The IDirect3DRM2::CreateDeviceFromSurface, IDirect3DRM2::CreateDeviceFromD3D, and IDirect3DRM2::CreateDeviceFromClipper methods all create a DIRECT3DRMDEVICE2 object. The IDirect3DRM2::CreateViewport method creates a viewport on a DirectDRMDevice2 object. The IDirect3DRM2::LoadTexture and IDirect3DRM2::LoadTextureFromResource methods load a Direct3DRMTexture2 object.

To access the IDirect3DRM2 Component Object Model (COM) interface, create an IDirect3DRM object with Direct3DRMCreate, then query for IDirect3DRM2 from IDirect3DRM.

For a conceptual overview, see IDirect3DRM and IDirect3DRM2 Interfaces.

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

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

The IDirect3DRM2 interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release


IDirect3DRM2::AddSearchPath

IDirect3DRM2

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

HRESULT AddSearchPath(
  LPCSTR lpPath
  );

Parameters
lpPath
Address of a null-terminated string specifying the path to add to the current search path.
Return Values

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

IDirect3DRM2::SetSearchPath


IDirect3DRM2::CreateAnimation

IDirect3DRM2

Creates an empty Direct3DRMAnimation object.

HRESULT CreateAnimation(
  LPDIRECT3DRMANIMATION * lplpD3DRMAnimation
  );

Parameters
lplpD3DRMAnimation
Address that will be filled with a pointer to an IDirect3DRMAnimation interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateAnimationSet

IDirect3DRM2

Creates an empty Direct3DRMAnimationSet object.

HRESULT CreateAnimationSet (
  LPDIRECT3DRMANIMATIONSET * lplpD3DRMAnimationSet
  );

Parameters
lplpD3DRMAnimationSet
Address that will be filled with a pointer to an IDirect3DRMAnimationSet interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateDevice

IDirect3DRM2

Not implemented on the Windows platform.

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


IDirect3DRM2::CreateDeviceFromClipper

IDirect3DRM2

Creates a Direct3DRMDevice2 Windows device by using a specified DirectDrawClipper object. An IDirect3DRMDevice2 interface works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface, as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

HRESULT CreateDeviceFromClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper,
  LPGUID lpGUID,
  int width,
  int height,
  LPDIRECT3DRMDEVICE2 * 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 IDirect3DRMDevice2 interface if the call succeeds.
Return Values

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.


IDirect3DRM2::CreateDeviceFromD3D

IDirect3DRM2

Creates a Direct3DRMDevice2 Windows device by using specified Direct3D objects. An IDirect3DRMDevice2 interface works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

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

Parameters
lpD3D
Address of an instance of Direct3D2.
lpD3DDev
Address of a Direct3D2 device object.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice2 interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateDeviceFromSurface

IDirect3DRM2

Creates a Direct3DRMDevice2 Windows device for rendering from the specified DirectDraw surfaces. An IDirect3DRMDevice2 interface works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

HRESULT CreateDeviceFromSurface(
  LPGUID lpGUID,
  LPDIRECTDRAW lpDD,
  LPDIRECTDRAWSURFACE lpDDSBack,
  LPDIRECT3DRMDEVICE2 * 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.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice2 interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateFace

IDirect3DRM2

Creates an instance of the IDirect3DRMFace interface.

HRESULT CreateFace(
  LPDIRECT3DRMFACE * lplpd3drmFace
  );

Parameters
lplpd3drmFace
Address that will be filled with a pointer to an IDirect3DRMFace interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateFrame

IDirect3DRM2

Creates a new child frame (a Direct3DRMFrame2 object) of the given parent frame.

HRESULT CreateFrame(
  LPDIRECT3DRMFRAME lpD3DRMFrame,
  LPDIRECT3DRMFRAME2* lplpD3DRMFrame2
  );

Parameters
lpD3DRMFrame
Address of a DIRECT3DRMFRAME object that is to be the parent of the new frame.
lplpD3DRMFrame
Address that will be filled with a pointer to an IDirect3DRMFrame2 interface if the call succeeds.
Return Values

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 IDirect3DRMFrame2::AddChild method.

See Also

IDirect3DRMFrame2::AddChild


IDirect3DRM2::CreateLight

IDirect3DRM2

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

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 Values

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


IDirect3DRM2::CreateLightRGB

IDirect3DRM2

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

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.
lplpD3DRMLight
Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateMaterial

IDirect3DRM2

Creates a material with the given specular property.

HRESULT CreateMaterial(
  D3DVALUE vPower,
  LPDIRECT3DRMMATERIAL * 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 IDirect3DRMMaterial interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateMesh

IDirect3DRM2

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

HRESULT CreateMesh(
  LPDIRECT3DRMMESH* lplpD3DRMMesh
  );

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

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


IDirect3DRM2::CreateMeshBuilder

IDirect3DRM2

Creates a new mesh builder object.

HRESULT CreateMeshBuilder(
  LPDIRECT3DRMMESHBUILDER2* lplpD3DRMMeshBuilder2
  );

Parameters
lplpD3DRMMeshBuilder
Address that will be filled with a pointer to an IDirect3DRMMeshBuilder2 interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateObject

IDirect3DRM2

Creates a new object without initializing the object.

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 Values

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 IDirect3DRM2 interface initialize the object automatically.) To initialize the new object, you should 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.


IDirect3DRM2::CreateProgressiveMesh

IDirect3DRM2

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

HRESULT CreateProgressiveMesh(
  LPDIRECT3DRMPROGRESSIVEMESH* lplpD3DRMProgressiveMesh
  );

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

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


IDirect3DRM2::CreateShadow

IDirect3DRM2

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.

HRESULT CreateShadow(
  LPDIRECT3DRMVISUAL lpVisual,
  LPDIRECT3DRMLIGHT lpLight,
  D3DVALUE px,
  D3DVALUE py,
  D3DVALUE pz,
  D3DVALUE nx,
  D3DVALUE ny,
  D3DVALUE nz,
  LPDIRECT3DRMVISUAL * lplpShadow
  );

Parameters
lpVisual
Address of the Direct3DRMVisual object that is 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 Values

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


IDirect3DRM2::CreateTexture

IDirect3DRM2

Creates a texture from an image in memory.

HRESULT CreateTexture(
  LPD3DRMIMAGE lpImage,
  LPDIRECT3DRMTEXTURE2* lplpD3DRMTexture2
  );

Parameters
lpImage
Address of a D3DRMIMAGE structure describing the source for the texture.
lplpD3DRMTexture2
Address that will be filled with a pointer to an IDirect3DRMTexture2 interface if the call succeeds.
Return Values

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's buffers. This allows the image to be used both as a rendering target and as a texture.


IDirect3DRM2::CreateTextureFromSurface

IDirect3DRM2

Creates a texture from a specified DirectDraw surface.

HRESULT CreateTextureFromSurface(
  LPDIRECTDRAWSURFACE lpDDS,
  LPDIRECT3DRMTEXTURE2 * lplpD3DRMTexture2
  );

Parameters
lpDDS
Address of the DirectDrawSurface object containing the texture.
lplpD3DRMTexture
Address that will be filled with a pointer to an IDirect3DRMTexture2 interface if the call succeeds.
Return Values

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


IDirect3DRM2::CreateUserVisual

IDirect3DRM2

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

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 Values

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


IDirect3DRM2::CreateViewport

IDirect3DRM2

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

HRESULT CreateViewport(
  LPDIRECT3DRMDEVICE2 lpDev,
  LPDIRECT3DRMFRAME lpCamera,
  DWORD dwXPos,
  DWORD dwYPos,
  DWORD dwWidth,
  DWORD dwHeight,
  LPDIRECT3DRMVIEWPORT* lplpD3DRMViewport
  );

Parameters
lpDev
Address of a Direct3DRMDevice2 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 IDirect3DRMViewport interface if the call succeeds.
Return Values

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.

An IDirect3DRMDevice2 interface works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.


IDirect3DRM2::CreateWrap

IDirect3DRM2

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.

HRESULT CreateWrap(
  D3DRMWRAPTYPE type,
  LPDIRECT3DRMFRAME 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 Values

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


IDirect3DRM2::EnumerateObjects

IDirect3DRM2

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

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 Values

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


IDirect3DRM2::GetDevices

IDirect3DRM2

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

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 Values

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


IDirect3DRM2::GetNamedObject

IDirect3DRM2

Finds a Direct3DRMObject given the Direct3DRMObject name.

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 Values

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.


IDirect3DRM2::GetSearchPath

IDirect3DRM2

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

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 Values

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

See Also

IDirect3DRM2::SetSearchPath


IDirect3DRM2::Load

IDirect3DRM2

Loads an object.

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  LPIID * lplpGUIDs,
  DWORD dwcGUIDs,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADCALLBACK d3drmLoadProc,
  LPVOID lpArgLP,
  D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP,
  LPDIRECT3DRMFRAME 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_IDirect3DRMMeshBuilder and IID_IDirect3DRMAnimationSet, this method loads all the animation sets and mesh-builder objects. Possible GUIDs must be one or more of the following: IID_IDirect3DRMMeshBuilder, IID_IDirect3DRMAnimationSet, IID_IDirect3DRMAnimation, and IID_IDirect3DRMFrame.
dwcGUIDs
Number of elements specified in the lplpGUIDs parameter.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadProc
A D3DRMLOADCALLBACK callback function used when the system reads the specified object.
lpArgLP
Address of application-defined data passed to the D3DRMLOADCALLBACK callback function.
d3drmLoadTextureProc
A D3DRMLOADTEXTURECALLBACK 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 D3DRMLOADTEXTURECALLBACK 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 Values

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 allows great flexibility in loading objects from DirectX files. See IDirect3DRM::Load for an example of how to use it.


IDirect3DRM2::LoadTexture

IDirect3DRM2

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.

HRESULT LoadTexture(
  const char * lpFileName,
  LPDIRECT3DRMTEXTURE2* 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 IDirect3DRMTexture2 pointer if the call succeeds.
Return Values

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 IDirect3DRM2::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;
}


IDirect3DRM2::LoadTextureFromResource

IDirect3DRM2

Loads a Direct3DRMTexture2 texture from a specified resource.

HRESULT LoadTextureFromResource(
  HMODULE hModule,
  LPCTSTR strName,
  LPCTSTR strType,
  LPDIRECT3DRMTEXTURE2 * 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 reource
RT_RCDATA Application-defined resource (raw data)
lplpD3DRMTexture
Address of a pointer to be initialized with a valid IDirect3DRMTexture2 object if the call succeeds.
Return Values

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


IDirect3DRM2::SetDefaultTextureColors

IDirect3DRM2

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

HRESULT SetDefaultTextureColors(
  DWORD dwColors
  );

Parameters
dwColors
Number of colors.
Return Values

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 IDirect3DRM2::CreateTexture method; it has no effect on textures that have already been created.


IDirect3DRM2::SetDefaultTextureShades

IDirect3DRM2

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

HRESULT SetDefaultTextureShades(
  DWORD dwShades
  );

Parameters
dwShades
Number of shades.
Return Values

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 IDirect3DRM2::CreateTexture method; it has no effect on textures that have already been created.


IDirect3DRM2::SetSearchPath

IDirect3DRM2

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

HRESULT SetSearchPath(
  LPCSTR lpPath
  );

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

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

IDirect3DRM2::GetSearchPath


IDirect3DRM2::Tick

IDirect3DRM2

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.

HRESULT Tick(
  D3DVALUE d3dvalTick
  );

Parameters
d3dvalTick
Velocity and rotation step for the IDirect3DRMFrame::SetRotation and IDirect3DRMFrame::SetVelocity methods.
Return Values

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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

*Top of Page