IDirect3DRMTexture2

The IDirect3DRMTexture2 interface is an extension of the IDirect3DRMTexture interface. IDirect3DRMTexture2::InitFromResource2 allows resources to be loaded from DLLs and executables other than the currently executing file. In addition, IDirect3DRMTexture2 has two additional methods. The IDirect3DRMTexture2::InitFromImage method creates a texture from an image in memory. This method is equivalent to the IDirect3DRM::CreateTexture method. The IDirect3DRMTexture2::GenerateMIPMap method generates a mipmap from a source image.

To avoid unnecessary delays when creating textures, hold onto textures you want to use again, instead of creating them each time they're needed. For optimal performance, use a texture surface format that is supported by the device you are using. This will avoid a costly format conversion when the texture is created and any time it changes.

See the remarks in IDirect3DRM2::LoadTexture for an example showing how to keep a reference to textures loaded in a texture callback through IDirect3DRM2::LoadTexture.

For a conceptual overview, see IDirect3DRMTexture and IDirect3DRMTexture2.

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

Color	GetColors
	SetColors
Decals	GetDecalOrigin
	GetDecalScale
	GetDecalSize
	GetDecalTransparency
	GetDecalTransparentColor
	SetDecalOrigin
	SetDecalScale
	SetDecalSize
	SetDecalTransparency
	SetDecalTransparentColor
Images	GetImage
Initialization	InitFromFile
	InitFromImage
	InitFromResource2
	InitFromSurface
MIP map generation	GenerateMIPMap
Renderer notification	Changed
Shading	GetShades
	SetShades

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

AddRef

QueryInterface

Release

In addition, the IDirect3DRMTexture2 interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback

Clone

DeleteDestroyCallback

GetAppData

GetClassName

GetName

SetAppData

SetName

You can create an IDirect3DRMTexture2 object by calling IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface.

---

IDirect3DRMTexture2::Changed

IDirect3DRMTexture2

Informs the renderer that the application has changed the pixels or the palette of a Direct3DRMTexture2 object.

HRESULT Changed(
  BOOL bPixels,
  BOOL bPalette
  );

Parameters

bPixels

If this parameter is TRUE, the pixels have changed.

bPalette

If this parameter is TRUE, the palette has changed.

Return Values

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

---

IDirect3DRMTexture2::GenerateMIPMap

IDirect3DRMTexture2

Generates a mipmap from a single image source.

HRESULT GenerateMIPMap(
  DWORD dwFlags
  );

Parameters

dwFlags

Should be set to zero.

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 can be called any time after a texture is created. It will generate a MIP map of the source image down to a resolution of 1×1 by using bilinear filtering between levels. Once a MIP map has been generated, it will always be available and will be updated whenever IDirect3DRMTexture::Changed is called. When using MIP mapping, remember to change the texture quality to D3DRMTEXTURE_MIPNEAREST, D3DRMTEXTURE_MIPLINEAR, D3DRMTEXTURE_LINEARMIPNEAREST, or D3DRMTEXTURE_LINEARMIPLINEAR using IDirect3DRMDevice::SetTextureQuality. Extra MIP map levels will not be put into video memory for hardware devices unless the texture quality includes a MIP mapping type and the hardware device supports MIP mapping.

See Also

Mipmaps

---

IDirect3DRMTexture2::GetColors

IDirect3DRMTexture2

Retrieves the maximum number of colors used for rendering a Direct3DRMTexture2 object.

DWORD GetColors( );

Return Values

Returns the number of colors.

Remarks

This method returns the number of colors that the Direct3DRMTexture2 object has been quantized to, not the number of colors in the image from which the Direct3DRMTexture2 object was created. Consequently, the number of colors that are returned usually matches the colors that were set by calling the IDirect3DRM::SetDefaultTextureColors method, unless you used the IDirect3DRMTexture2::SetColors method explicitly to change the colors for the Direct3DRMTexture2 object.

See Also

IDirect3DRMTexture2::SetColors

---

IDirect3DRMTexture2::GetDecalOrigin

IDirect3DRMTexture2

Retrieves the current origin of the decal.

HRESULT GetDecalOrigin(
  LONG * lplX,
  LONG * lplY
  );

Parameters

lplX and lplY

Addresses of variables that will be filled with the origin of the decal 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.

See Also

IDirect3DRMTexture2::SetDecalOrigin

---

IDirect3DRMTexture2::GetDecalScale

IDirect3DRMTexture2

Retrieves the scaling property of the given decal.

DWORD GetDecalScale( );

Return Values

Returns the scaling property if successful, or -1 otherwise.

See Also

IDirect3DRMTexture2::SetDecalScale

---

IDirect3DRMTexture2::GetDecalSize

IDirect3DRMTexture2

Retrieves the size of the decal.

HRESULT GetDecalSize(
  D3DVALUE *lprvWidth,
  D3DVALUE *lprvHeight
  );

Parameters

lprvWidth and lprvHeight

Addresses of variables that will be filled with the width and height of the decal 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.

See Also

IDirect3DRMTexture2::SetDecalSize

---

IDirect3DRMTexture2::GetDecalTransparency

IDirect3DRMTexture2

Retrieves the transparency property of the decal.

BOOL GetDecalTransparency( );

Return Values

Returns TRUE if the decal has a transparent color, FALSE otherwise.

See Also

IDirect3DRMTexture2::SetDecalTransparency

---

IDirect3DRMTexture2::GetDecalTransparentColor

IDirect3DRMTexture2

Retrieves the transparent color of the decal.

D3DCOLOR GetDecalTransparentColor( );

Return Values

Returns the value of the transparent color.

See Also

IDirect3DRMTexture2::SetDecalTransparentColor

---

IDirect3DRMTexture2::GetImage

IDirect3DRMTexture2

Returns an address of the image that the texture was created with.

D3DRMIMAGE * GetImage( );

Return Values

Returns the address of the D3DRMIMAGE structure that the current Direct3DRMTexture2 object was created with.

---

IDirect3DRMTexture2::GetShades

IDirect3DRMTexture2

Retrieves the number of shades used for each color in the texture when rendering.

DWORD GetShades( );

Return Values

Returns the number of shades.

See Also

IDirect3DRMTexture2::SetShades

---

IDirect3DRMTexture2::InitFromFile

IDirect3DRMTexture2

Initializes a Direct3DRMTexture2 object using the information in a given file.

HRESULT InitFromFile(
  LPCSTR filename
  );

Parameters

filename

A string that specifies the file from which the texture initialization information is drawn.

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 must have created the Direct3DRMTexture2 object to be initialized using the IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface methods.

See Also

IDirect3DRMTexture2::InitFromImage, IDirect3DRMTexture2::InitFromResource2, IDirect3DRMTexture2::InitFromSurface

---

IDirect3DRMTexture2::InitFromImage

IDirect3DRMTexture2

Initializes a texture from an image in memory.

HRESULT InitFromImage(
  LPD3DRMIMAGE lpImage
  );

Parameters

lpImage

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

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 must have created the IDirect3DRMTexture2 object to be initialized using the IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface methods.

See Also

IDirect3DRMTexture2::InitFromFile, IDirect3DRMTexture2::InitFromResource2, IDirect3DRMTexture2::InitFromSurface

---

IDirect3DRMTexture2::InitFromResource2

IDirect3DRMTexture2

Initializes a Direct3DRMTexture2 object from a specified resource.

HRESULT InitFromResource2(
  HModule hModule,
  LPCTSTR strName,
  LPCTSTR strType
  );

Parameters

hModule

Handle of the specified resource.

strName

The name of the resource to be used to initialize the texture.

strType

The type name of the resource used to initialize the texture. Textures can be stored in RT_BITMAP and RT_RCDATA resource types, or user-defined types. If the resource type is user-defined, this method passes the resource module handle, the resource name, and the resource type to the FindResource Win32 API.

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 must have created the IDirect3DRMTexture2 object to be initialized using the IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface methods.

See Also

IDirect3DRMTexture2::InitFromFile, IDirect3DRMTexture2::InitFromImage, IDirect3DRMTexture2::InitFromSurface

---

IDirect3DRMTexture2::InitFromSurface

IDirect3DRMTexture2

Initializes a Direct3DRMTexture2 object by using the data from a given DirectDraw surface. This method performs the same as IDirect3DRMTexture::InitFromSurface.

HRESULT InitFromSurface(
  LPDIRECTDRAWSURFACE lpDDS
  );

Parameters

lpDDS

Address of a DirectDraw surface from which initialization information is drawn.

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 must have created the IDirect3DRMTexture2 object to be initialized using the IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface methods.

See Also

IDirect3DRMTexture2::InitFromFile, IDirect3DRMTexture2::InitFromImage, IDirect3DRMTexture2::InitFromResource2

---

IDirect3DRMTexture2::SetColors

IDirect3DRMTexture2

Sets the maximum number of colors used for rendering a Direct3DRMTexture2 object. This method is required only in the ramp color model.

HRESULT SetColors(
  DWORD ulColors
  );

Parameters

ulColors

Number of colors. The default value is 8.

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

IDirect3DRMTexture2::GetColors

---

IDirect3DRMTexture2::SetDecalOrigin

IDirect3DRMTexture2

Sets the origin of the decal as an offset from the top left of the decal.

HRESULT SetDecalOrigin(
  LONG lX,
  LONG lY
  );

Parameters

lX and lY

New origin, in decal coordinates, for the decal. The default origin is [0, 0].

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 decal's origin is mapped to its frame's position when rendering. For example, the origin of a decal of a cross would be set to the middle of the decal, and the origin of an arrow pointing down would be set to midway along the bottom edge.

This method is also used to add a decal origin key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture2::GetDecalOrigin

---

IDirect3DRMTexture2::SetDecalScale

IDirect3DRMTexture2

Sets the scaling property for a decal.

HRESULT SetDecalScale(
  DWORD dwScale
  );

Parameters

dwScale

If this parameter is TRUE, depth is taken into account when the decal is scaled. If it is FALSE, depth information is ignored. The default value is TRUE.

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

IDirect3DRMTexture2::GetDecalScale

---

IDirect3DRMTexture2::SetDecalSize

IDirect3DRMTexture2

Sets the size of the decal to be used if the decal is being scaled according to its depth in the scene.

HRESULT SetDecalSize(
  D3DVALUE rvWidth,
  D3DVALUE rvHeight
  );

Parameters

rvWidth and rvHeight

New width and height, in model coordinates, of the decal. The default size is [1, 1].

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 is also used to add a decal size key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture2::GetDecalSize

---

IDirect3DRMTexture2::SetDecalTransparency

IDirect3DRMTexture2

Sets the transparency property of the decal.

HRESULT SetDecalTransparency(
  BOOL bTransp
  );

Parameters

bTransp

If this parameter is TRUE, the decal has a transparent color. If it is FALSE, it has an opaque color. The default value is FALSE.

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

IDirect3DRMTexture2::GetDecalTransparency

---

IDirect3DRMTexture2::SetDecalTransparentColor

IDirect3DRMTexture2

Sets the transparent color for a decal.

HRESULT SetDecalTransparentColor(
  D3DCOLOR rcTransp
  );

Parameters

rcTransp

New transparent color. The default transparent color is black.

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 is also used to add a decal transparent color key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture2::GetDecalTransparentColor

---

IDirect3DRMTexture2::SetShades

IDirect3DRMTexture2

Sets the maximum number of shades to use for each color for the Direct3DRMTexture2 object when rendering. This method is required only in the ramp color model.

HRESULT SetShades(
  DWORD ulShades
  );

Parameters

ulShades

New number of shades. This value must be a power of 2. The default value is 16.

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

IDirect3DRMTexture2::GetShades

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

Top of Page