IDirect3DRMTexture3
Microsoft DirectX version 6.0 introduced the IDirect3DRMTexture3 interface. IDirect3DRMTexture3 extends the older IDirect3DRMTexture2 and IDirect3DRMTexture interfaces that it replaces and it allows finer control over texture management. For a conceptual overview, see Textures. For a history of the Direct3D Retained Mode interfaces, see Interface Changes.
IDirect3DRMTexture3 extends the functionality of the Changed method by allowing you to specify the changed region of the texture. It also provides the texture management caching methods GetCacheOptions and SetCacheOptions. GetSurface, SetDownSampleCallback, and SetValidationCallback are the other new methods IDirect3DRMTexture3 provides.
Previously new methods, added by the older IDirect3DRMTexture2, and also supported by IDirect3DRMTexture3 include InitFromResource2, which allows resources to be loaded from DLLs and executables other than the currently executing file. The InitFromImage method creates a texture from an image in memory. This method is equivalent to the IDirect3DRM3::CreateTexture method. The 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 IDirect3DRM3::LoadTexture for an example showing how to keep a reference to textures loaded in a texture callback through IDirect3DRM3::LoadTexture.
The methods of the IDirect3DRMTexture3 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 | |
| Mipmap generation | GenerateMIPMap |
| Miscellaneous | GetCacheOptions |
| GetSurface | |
| SetCacheOptions | |
| SetDownsampleCallback | |
| SetValidationCallback | |
| Renderer notification | Changed |
| Shading | GetShades |
| SetShades |
The IDirect3DRMTexture3 interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
| AddRef |
| QueryInterface |
| Release |
In addition, the IDirect3DRMTexture3 interface inherits the following methods from the IDirect3DRMObject interface:
| AddDestroyCallback |
| Clone |
| DeleteDestroyCallback |
| GetAppData |
| GetClassName |
| GetName |
| SetAppData |
| SetName |
You can create an IDirect3DRMTexture3 object by calling IDirect3DRM3::CreateTexture or IDirect3DRM3::CreateTextureFromSurface.
IDirect3DRMTexture3::Changed
IDirect3DRMTexture3
Enables the application to specify which region of the texture has changed.
Syntax
HRESULT Changed( DWORD dwFlags, DWORD dwcRects, LPRECT pRects);
Parameters
- dwFlags
- The following flags are defined:
- D3DRMTEXTURE_CHANGEDPIXELS
- Indicates that the pixel values have changed.
- D3DRMTEXTURE_CHANGEDPALETTE
- Indicates that the palette has changed.
- D3DRMTEXTURE_INVALIDATEONLY
- Indicates that the texture regions are invalidated but do not need to be updated by the application. Before Direct3D Retained Mode renders the texture, it calls the application to update the primary source. This callback is set by SetValidationCallback.
- dwcRects
- Number of RECT structures pointed to by pRects. If this value is zero, and dwFlags contains D3DRMTEXTURE_CHANGEDPIXELS or D3DRMTEXTURE_INVALIDATEONLY, the whole texture is updated.
- pRects
- Array of RECT structures describing the regions of pixels that have changed. The pRects parameter is only valid if dwFlags contains D3DRMTEXTURE_CHANGEDPIXELS or D3DRMTEXTURE_INVALIDATEONLY.
Return Value
Returns one of the following values:
DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK
Remarks
This method was introduced with DirectX version 6.0. This method replaces the old IDirect3DRMTexture::Changed method. This old method has two Boolean parameters that indicate whether the application has changed the pixels or the palette of a texture.
IDirect3DRMTexture3::GenerateMIPMap
IDirect3DRMTexture3
Generates a mipmap from a single image source.
Syntax
HRESULT GenerateMIPMap(
DWORD dwFlags
);
Parameters
- dwFlags
- Should be set to zero.
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 can be called any time after a texture is created. It will generate a mipmap of the source image down to a resolution of 1×1 by using bilinear filtering between levels. Once a mipmap has been generated, it will always be available and will be updated whenever IDirect3DRMTexture3::Changed is called. When using mipmapping, remember to change the texture quality to D3DRMTEXTURE_MIPNEAREST, D3DRMTEXTURE_MIPLINEAR, D3DRMTEXTURE_LINEARMIPNEAREST, or D3DRMTEXTURE_LINEARMIPLINEAR using IDirect3DRMDevice3::SetTextureQuality. Extra mipmap levels will not be put into video memory for hardware devices unless the texture quality includes a mipmapping type and the hardware device supports mipmapping.
See Also
IDirect3DRMTexture3::GetCacheOptions
IDirect3DRMTexture3
Retrieves information about how texture management treats the current texture if texture memory is restricted.
Syntax
HRESULT GetCacheOptions( LPLONG lplImportance, LPDWORD lpdwFlags);
Parameters
- lplImportance
- A signed value that indicates the relative importance of a texture. The default is zero. Higher values indicate a greater importance. This value is used to calculate which textures should be downsampled last if texture memory is restricted.
- lpdwFlags
- Flags that control the texture management system with respect to the current texture. The currently defined flags are:
- D3DRMTEXTURE_FORCERESIDENT
- Indicates that the texture should be kept in video memory (in a hardware scenario).
- D3DRMTEXTURE_STATIC
- Indicates that the texture will not change. The application guarantees not to use the Changed method.
- D3DRMTEXTURE_DOWNSAMPLEPOINT
- Indicates that when the texture is downsampled, point filtering will be used.
- D3DRMTEXTURE_DOWNSAMPLEBILINEAR
- Indicates that when the texture is downsampled, bilinear filtering will be used.
- D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH
- Indicates that when the texture is downsampled, the pixel depth will be reduced.
- D3DRMTEXTURE_DOWNSAMPLENONE
- Indicates that the texture should never be downsampled.
Return Value
Returns one of the following values:
DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK
Remarks
This method was introduced with DirectX version 6.0.
IDirect3DRMTexture3::GetColors
IDirect3DRMTexture3
Retrieves the maximum number of colors used for rendering a Direct3DRMTexture2 object.
Syntax
DWORD GetColors( );
Return Value
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 IDirect3DRM3::SetDefaultTextureColors method, unless you used the IDirect3DRMTexture3::SetColors method explicitly to change the colors for the Direct3DRMTexture2 object.
See Also
IDirect3DRMTexture3::GetDecalOrigin
IDirect3DRMTexture3
Retrieves the current origin of the decal.
Syntax
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 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
IDirect3DRMTexture3::GetDecalScale
IDirect3DRMTexture3
Retrieves the scaling property of the given decal.
Syntax
DWORD GetDecalScale( );
Return Value
Returns the scaling property if successful, or -1 otherwise.
See Also
IDirect3DRMTexture3::GetDecalSize
IDirect3DRMTexture3
Retrieves the size of the decal.
Syntax
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 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
IDirect3DRMTexture3::GetDecalTransparency
IDirect3DRMTexture3
Retrieves the transparency property of the decal.
Syntax
BOOL GetDecalTransparency( );
Return Value
Returns TRUE if the decal has a transparent color, FALSE otherwise.
See Also
IDirect3DRMTexture3::GetDecalTransparentColor
IDirect3DRMTexture3
Retrieves the transparent color of the decal.
Syntax
D3DCOLOR GetDecalTransparentColor( );
Return Value
Returns the value of the transparent color.
See Also
IDirect3DRMTexture3::GetImage
IDirect3DRMTexture3
Returns an address of the image that the texture was created with.
Syntax
D3DRMIMAGE *GetImage( );
Return Value
Returns the address of the D3DRMIMAGE structure that the current Direct3DRMTexture2 object was created with.
IDirect3DRMTexture3::GetShades
IDirect3DRMTexture3
Retrieves the number of shades used for each color in the texture when rendering.
Syntax
DWORD GetShades( );
Return Value
Returns the number of shades.
See Also
IDirect3DRMTexture3::GetSurface
IDirect3DRMTexture3
Retrieves the DirectDraw surface that was used to create the texture. This only retrieves a surface if CreateTextureFromSurface or InitFromSurface was used to create the texture.
Syntax
HRESULT GetSurface( DWORD dwFlags, LPDIRECTDRAWSURFACE *lplpDDS);
Parameters
- dwFlags
- Flag value. Must be zero.
- lplpDDS
- Address of a variable that receives a pointer to the interface of the corresponding DirectDraw surface. Note that the interface's reference count is incremented before the interface is handed to the caller.
Return Value
Returns one of the following values:
D3DRMERR_NOTCREATEDFROMDDS DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK
Remarks
This method was introduced with DirectX version 6.0.
IDirect3DRMTexture3::InitFromFile
IDirect3DRMTexture3
Initializes a Direct3DRMTexture2 object using the information in a given file.
Syntax
HRESULT InitFromFile(
LPCSTR filename
);
Parameters
- filename
- A string that specifies the file from which the texture initialization information is drawn.
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 must have created the Direct3DRMTexture2 object to be initialized using the IDirect3DRM3::CreateTexture or IDirect3DRM3::CreateTextureFromSurface methods.
See Also
IDirect3DRMTexture3::InitFromImage, IDirect3DRMTexture3::InitFromResource2, IDirect3DRMTexture3::InitFromSurface
IDirect3DRMTexture3::InitFromImage
IDirect3DRMTexture3
Initializes a texture from an image in memory.
Syntax
HRESULT InitFromImage(
LPD3DRMIMAGE lpImage
);
Parameters
- lpImage
- Address of a D3DRMIMAGE structure describing the source of the texture.
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 must have created the IDirect3DRMTexture3 object to be initialized using the IDirect3DRM3::CreateTexture or IDirect3DRM3::CreateTextureFromSurface methods.
See Also
IDirect3DRMTexture3::InitFromFile, IDirect3DRMTexture3::InitFromResource2, IDirect3DRMTexture3::InitFromSurface
IDirect3DRMTexture3::InitFromResource2
IDirect3DRMTexture3
Initializes a Direct3DRMTexture2 object from a specified resource.
Syntax
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 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 must have created the IDirect3DRMTexture3 object to be initialized using the IDirect3DRM3::CreateTexture or IDirect3DRM3::CreateTextureFromSurface methods.
See Also
IDirect3DRMTexture3::InitFromFile, IDirect3DRMTexture3::InitFromImage, IDirect3DRMTexture3::InitFromSurface
IDirect3DRMTexture3::InitFromSurface
IDirect3DRMTexture3
Initializes a Direct3DRMTexture2 object by using the data from a given DirectDraw surface. This method performs the same as IDirect3DRMTexture3::InitFromSurface.
Syntax
HRESULT InitFromSurface(
LPDIRECTDRAWSURFACE lpDDS
);
Parameters
- lpDDS
- Address of a DirectDraw surface from which initialization information is drawn.
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.
See Also
IDirect3DRMTexture3::InitFromFile, IDirect3DRMTexture3::InitFromImage, IDirect3DRMTexture3::InitFromResource2
IDirect3DRMTexture3::SetCacheOptions
IDirect3DRMTexture3
Provides information about how texture management should treat this texture if texture memory is restricted.
Syntax
HRESULT SetCacheOptions( LONG lImportance, DWORD dwFlags);
Parameters
- lImportance
- A signed value that indicates the relative importance of a texture. The default value is zero. Higher values indicate a greater importance. This value is used to calculate which textures should be downsampled last if texture memory is restricted.
- dwFlags
- Flags that control the texture-management system with respect to the current texture. The currently defined flags are:
- D3DRMTEXTURE_FORCERESIDENT
- Indicates that the texture should be kept in video memory (in a hardware scenario).
- D3DRMTEXTURE_STATIC
- Indicates that the texture will not change.
- D3DRMTEXTURE_DOWNSAMPLEPOINT
- Indicates that when the texture is downsampled, point filtering should be used.
- D3DRMTEXTURE_DOWNSAMPLEBILINEAR
- Indicates that when the texture is downsampled, bilinear filtering should be used.
- D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH
- Indicates that when the texture is downsampled, the pixel depth should be reduced. If no lower bit depth is available, the size of the texture will be reduced.
- D3DRMTEXTURE_DOWNSAMPLENONE
- Indicates that the texture should never be downsampled. The default value is D3DRMTEXTURE_DOWNSAMPLEPOINT.
Return Value
Returns one of the following values:
DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK
Remarks
This method was introduced with DirectX version 6.0.
IDirect3DRMTexture3::SetColors
IDirect3DRMTexture3
Sets the maximum number of colors used for rendering a Direct3DRMTexture2 object. This method is required only in the ramp color model.
Syntax
HRESULT SetColors(
DWORD ulColors
);
Parameters
- ulColors
- Number of colors. The default value is 8.
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
IDirect3DRMTexture3::SetDecalOrigin
IDirect3DRMTexture3
Sets the origin of the decal as an offset from the top left of the decal.
Syntax
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 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 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
IDirect3DRMTexture3::SetDecalScale
IDirect3DRMTexture3
Sets the scaling property for a decal.
Syntax
HRESULT SetDecalScale(
DWORD dwScale
);
Parameters
- dwScale
- If this parameter is TRUE, depth is taken into account when the decal is scaled and, when the decal is a texture on a frame in a scene, the decal will be scaled smaller when it is farther from the viewer and larger when it closer to the viewer. If this parameter is FALSE, depth information is ignored, and the decal will be the same size whether it is close to or far from the viewer. The default value is TRUE.
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
IDirect3DRMTexture3::SetDecalSize
IDirect3DRMTexture3
Sets the size of the decal to be used if the decal is being scaled according to its depth in the scene.
Syntax
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 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 is also used to add a decal size key to a Direct3DRMTextureInterpolator object.
See Also
IDirect3DRMTexture3::SetDecalTransparency
IDirect3DRMTexture3
Sets the transparency property of the decal.
Syntax
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 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
IDirect3DRMTexture3::SetDecalTransparentColor
IDirect3DRMTexture3
Sets the transparent color for a decal.
Syntax
HRESULT SetDecalTransparentColor(
D3DCOLOR rcTransp
);
Parameters
- rcTransp
- New transparent color. The default transparent color is black.
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 is also used to add a decal transparent color key to a Direct3DRMTextureInterpolator object.
See Also
IDirect3DRMTexture3::SetDownsampleCallback
IDirect3DRMTexture3
Specifies a callback that texture management will use when a texture is to be downsampled, rather than using the D3DRM built-in method. If a callback has already been specified, the new callback replaces the old one. If the callback is NULL, the current callback is removed.
Syntax
typedef HRESULT (CDECL *D3DRMDOWNSAMPLECALLBACK) (LPVOID pArg, LPDIRECTDRAWSURFACE pDDSSrc, LPDIRECTDRAWSURFACE pDDSDst); HRESULT SetDownsampleCallback( LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture, D3DRMDOWNSAMPLECALLBACK pCallback, LPVOID pArg);
Parameters
- pCallback
- Pointer to a callback function that will be invoked to perform the downsampling. A value of NULL indicates that the current callback is to be removed.
- pArg
- Application-specific data that will be passed to the callback upon invocation.
Return Value
Returns one of the following values:
DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK
Remarks
Downsampling is done when the video memory is getting overloaded and the texture surfaces need to be reduced in size. Direct3D Retained Mode provides default methods for reducing texture sizes, such as DirectDraw blitting and bilinear filtering, but users can define a callback with their own method to scale down texture size.
This method was introduced with DirectX version 6.0.
See Also
IDirect3DRMTexture3::SetShades
IDirect3DRMTexture3
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.
Syntax
HRESULT SetShades(
DWORD ulShades
);
Parameters
- ulShades
- New number of shades. This value must be a power of 2. The default value is 16.
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
IDirect3DRMTexture3::SetValidationCallback
IDirect3DRMTexture3
Sets the callback function that will validate and update the primary source texture.
Syntax
typedef HRESULT (CDECL *D3DRMVALIDATIONCALLBACK) (LPVOID pArg, DWORD dwFlags, DWORD dwcRects, LPRECT pRects); HRESULT SetValidationCallback( LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture, D3DRMVALIDATIONCALLBACK pCallback, LPVOID pArg);
Parameters
- pCallback
- Pointer to a callback function that will be invoked to perform the validation. If a callback has already been specified, the new callback replaces the old one. Specify NULL to remove the current callback.
- pArg
- Application-specific data that will be passed to the callback upon invocation.
Return Value
Returns one of the following values:
DDERR_INVALIDOBJECT DDERR_INVALIDPARAMS DD_OK
Remarks
Direct3D Retained Mode calls the texture validation callback when a texture region that has previously been marked as invalid, meaning it has changed but not been updated, now needs to be updated. The application updates the primary source and returns.
This method was introduced with DirectX version 6.0.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.