Applications use the methods of the IDirect3DRM interface to create Microsoft® Direct3D® Retained Mode objects and work with system-level variables. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRM and IDirect3DRM2 Interfaces.
The methods of the IDirect3DRM 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 | |
| Search paths | AddSearchPath |
| GetSearchPath | |
| SetSearchPath | |
| Shadows | CreateShadow |
| Textures | CreateTexture |
| CreateTextureFromSurface | |
| LoadTexture | |
| LoadTextureFromResource | |
| SetDefaultTextureColors | |
| SetDefaultTextureShades | |
| Viewports | CreateViewport |
| Wraps | CreateWrap |
The IDirect3DRM interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
| AddRef |
| QueryInterface |
| Release |
The IDirect3DRM COM interface is created by using the Direct3DRMCreate function.
Adds a list of directories to the end of the current file search path.
HRESULT AddSearchPath(
LPCSTR lpPath
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
For Microsoft® Windows®, the path should be a list of directories separated by semicolons (;).
Creates an empty Direct3DRMAnimation object.
HRESULT CreateAnimation(
LPDIRECT3DRMANIMATION * lplpD3DRMAnimation
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Immediate Mode Return Values.
Creates an empty Direct3DRMAnimationSet object.
HRESULT CreateAnimationSet (
LPDIRECT3DRMANIMATIONSET * lplpD3DRMAnimationSet
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Not implemented on the Windows platform.
HRESULT CreateDevice(
DWORD dwWidth,
DWORD dwHeight,
LPDIRECT3DRMDEVICE* lplpD3DRMDevice
);
Creates a Direct3D Retained Mode Windows device by using a specified DirectDrawClipper object.
HRESULT CreateDeviceFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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:
If a hardware device is not found, the monochromatic (ramp) software driver is loaded. An application should enumerate devices instead of specifying NULL for lpGUID if it has special needs that are not met by this list of default settings.
Creates a Direct3D Retained Mode Windows device by using specified Direct3D objects.
HRESULT CreateDeviceFromD3D(
LPDIRECT3D lpD3D,
LPDIRECT3DDEVICE lpD3DDev,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a Windows device for rendering from the specified DirectDraw surfaces.
HRESULT CreateDeviceFromSurface(
LPGUID lpGUID,
LPDIRECTDRAW lpDD,
LPDIRECTDRAWSURFACE lpDDSBack,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates an instance of the IDirect3DRMFace interface.
HRESULT CreateFace(
LPDIRECT3DRMFACE * lplpd3drmFace
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a new child frame of the given parent frame.
HRESULT CreateFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame,
LPDIRECT3DRMFRAME* lplpD3DRMFrame
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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 IDirect3DRMFrame::AddChild method.
Creates a new light source with the given type and color.
HRESULT CreateLight(
D3DRMLIGHTTYPE d3drmltLightType,
D3DCOLOR cColor,
LPDIRECT3DRMLIGHT* lplpD3DRMLight
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a new light source with the given type and color.
HRESULT CreateLightRGB(
D3DRMLIGHTTYPE ltLightType,
D3DVALUE vRed,
D3DVALUE vGreen,
D3DVALUE vBlue,
LPDIRECT3DRMLIGHT* lplpD3DRMLight
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a material with the given specular property.
HRESULT CreateMaterial(
D3DVALUE vPower,
LPDIRECT3DRMMATERIAL * lplpD3DRMMaterial
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a new mesh object with no faces. The mesh is not visible until it is added to a frame.
HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a new mesh builder object.
HRESULT CreateMeshBuilder(
LPDIRECT3DRMMESHBUILDER* lplpD3DRMMeshBuilder
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a new object without initializing the object.
HRESULT CreateObject(
REFCLSID rclsid,
LPUNKNOWN pUnkOuter,
REFIID riid,
LPVOID FAR* ppv
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
An application that uses this method must initialize the object that has been created. (The other creation methods of the IDirect3DRM 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.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a texture from an image in memory.
HRESULT CreateTexture(
LPD3DRMIMAGE lpImage,
LPDIRECT3DRMTEXTURE* lplpD3DRMTexture
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
The memory associated with the image is used each time the texture is rendered, rather than the memory being copied into the Direct3D Retained Mode buffers. This allows the image to be used both as a rendering target and as a texture.
Creates a texture from a specified DirectDraw surface.
HRESULT CreateTextureFromSurface(
LPDIRECTDRAWSURFACE lpDDS,
LPDIRECT3DRMTEXTURE * lplpD3DRMTexture
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Should return D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Creates a viewport on a device with device coordinates (dwXPos, dwYPos) to (dwXPos + dwWidth, dwYPos + dwHeight).
HRESULT CreateViewport(
LPDIRECT3DRMDEVICE lpDev,
LPDIRECT3DRMFRAME lpCamera,
DWORD dwXPos,
DWORD dwYPos,
DWORD dwWidth,
DWORD dwHeight,
LPDIRECT3DRMVIEWPORT* lplpD3DRMViewport
);
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 errors, see Direct3D Retained Mode Return Values.
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.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Uses the callback function specified by the func parameter on each of the active Direct3DRM objects.
HRESULT EnumerateObjects(
D3DRMOBJECTCALLBACK func,
LPVOID lpArg
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Returns all the Direct3DRM devices that have been created in the system.
HRESULT GetDevices(
LPDIRECT3DRMDEVICEARRAY* lplpDevArray
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Finds a Direct3DRMObject given the Direct3DRMObject name.
HRESULT GetNamedObject(
const char * lpName,
LPDIRECT3DRMOBJECT* lplpD3DRMObject
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
Returns the current search path. For Windows, the path is a list of directories separated by semicolons (;).
HRESULT GetSearchPath(
DWORD * lpdwSize,
LPSTR lpszPath
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method allows great flexibility in loading objects from Microsoft® DirectX® files. Here is an example of how to use it:
#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_IDirect3DRMFrame)) {
totalFrames ++;
return;
}
if (IsEqualIID(objGuid, &IID_IDirect3DRMAnimationSet)) {
totalAnim ++;
return;
}
if (IsEqualIID(objGuid, &IID_IDirect3DRMMeshBuilder)) {
totalMesh ++;
return;
}
return;
}
BOOL loadObjects(LPSTR filename)
{
LPGUID guids[] = { (LPGUID)&IID_IDirect3DRMMeshBuilder,
(LPGUID)&IID_IDirect3DRMAnimationSet,
(LPGUID)&IID_IDirect3DRMFrame };
/* 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);
}
Loads a 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,
LPDIRECT3DRMTEXTURE* lplpD3DRMTexture
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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 IDirect3DRM::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, LPDIRECT3DRMTEXTURE *tex)
{
return lpD3DRM->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:
LPDIRECT3DRMTEXTURE *texarray;
HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE *tex)
{
if (FAILED(lpD3DRM->LoadTexture(name, tex)) {
return NULL;
}
texArray[current++] = tex;
tex->AddRef();
return tex;
}
Loads a texture from a specified resource.
HRESULT LoadTextureFromResource(
HRSRC rs,
LPDIRECT3DRMTEXTURE * lplpD3DRMTexture
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the default colors to be used for a Direct3DRMTexture object.
HRESULT SetDefaultTextureColors(
DWORD dwColors
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method affects the texture colors only when it is used before the IDirect3DRM::CreateTexture method; it has no effect on textures that have already been created.
Sets the default shades to be used for an Direct3DRMTexture object.
HRESULT SetDefaultTextureShades(
DWORD dwShades
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method affects the texture shades only when it is used before the IDirect3DRM::CreateTexture method; it has no effect on textures that have already been created.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
You can implement this method by using other Retained Mode methods to allow more flexibility in rendering a scene.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.