Direct3DRMTexture3
The Direct3DRMTexture3 interface provides fine control over texture management. The Changed method enables you to specify the changed region of the texture. Direct3DRMTexture3 also provides the texture management caching methods GetCacheFlags, SetCacheOptions, and GetCacheImportance.
The GenerateMIPMap method generates a mipmap from a source image.
To avoid unnecessary delays when creating textures, hold on to 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.
The methods of the Direct3DRMTexture3 interface can be organized into the following groups.
Color GetColors SetColors Decals GetDecalOrigin GetDecalScale GetDecalSize GetDecalTransparency GetDecalTransparentColor SetDecalOrigin SetDecalScale SetDecalSize SetDecalTransparency SetDecalTransparentColor MIP map generation GenerateMIPMap Miscellaneous GetCacheFlags GetCacheImportance GetSurface SetCacheOptions Renderer notification Changed Shading GetShades SetShades
The Direct3DRMTexture3 interface inherits the following methods from the Direct3DRMObject interface.
AddDestroyCallback CloneObject DeleteDestroyCallback GetAppData GetClassName GetName SetAppData SetName
Call the Direct3DRM3.CreateTextureFromSurface method to create a Direct3DRMTexture3 object.
Direct3DRMTexture3.Changed
Direct3DRMTexture3
Enables the application to specify which region of the texture has changed.
Syntax
object.Changed(flags As CONST_D3DRMTEXTURECHANGEDFLAGS, nRects As Long, rects() As RECT)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- flags
- One or more of the values from the CONST_D3DRMTEXTURECHANGEDFLAGS enumerated type, indicating textural changes.
- nRects
- Number of RECT types in rects. If this value is zero, and flags contains D3DRMTEXTURE_CHANGEDPIXELS or D3DRMTEXTURE_INVALIDATEONLY, the whole texture is updated.
- rects
- Array of RECT types describing the regions of pixels that have changed. The rects parameter is only valid if flags contains D3DRMTEXTURE_CHANGEDPIXELS or D3DRMTEXTURE_INVALIDATEONLY. A RECT is a type that is a rectangle definition:
Type RECT Bottom As Long Left As Long Right As Long Top As Long End Type
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMTexture3.GenerateMIPMap
Direct3DRMTexture3
Generates a mipmap from a single image source.
Syntax
object.GenerateMIPMap( )
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error 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. After a mipmap has been generated, it will always be available and will be updated whenever Direct3DRMTexture3.Changed is called. When using mipmapping, remember to change the texture quality to D3DRMTEXTURE_MIPNEAREST, D3DRMTEXTURE_MIPLINEAR, D3DRMTEXTURE_LINEARMIPNEAREST, or D3DRMTEXTURE_LINEARMIPLINEAR using Direct3DRMDevice3.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.
Direct3DRMTexture3.GetCacheFlags
Direct3DRMTexture3
Retrieves information about how texture management treats the current texture if texture memory is restricted.
Syntax
object.GetCacheFlags( ) As CONST_D3DRMTEXTURECACHEFLAGS
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
Return Value
Returns values from the CONST_D3DRMTEXTURECACHEFLAGS enumerated type.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMTexture3.GetCacheImportance
Direct3DRMTexture3
Retrieves information on the relative importance of a texture if texture memory is restricted.
Syntax
object.GetCacheImportance( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
Return Value
Returns a 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.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMTexture3.GetColors
Direct3DRMTexture3
Retrieves the maximum number of colors used for rendering a Direct3DRMTexture3 object.
Syntax
object.GetColors( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
Return Value
Returns the number of colors.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method returns the number of colors that the Direct3DRMTexture3 object has been quantized to, not the number of colors in the image from which the Direct3DRMTexture3 object was created. Consequently, the number of colors returned usually matches the colors that were set by calling the Direct3DRM3.SetDefaultTextureColors method, unless you used the Direct3DRMTexture3.SetColors method explicitly to change the colors for the Direct3DRMTexture3 object.
Direct3DRMTexture3.GetDecalOrigin
Direct3DRMTexture3
Retrieves the current origin of the decal.
Syntax
object.GetDecalOrigin(x As Long, y As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- x and y
- The x- and y-coordinates of the decal's origin.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.GetDecalScale
Direct3DRMTexture3
Retrieves the scaling property of the given decal.
Syntax
object.GetDecalScale( ) As CONST_DBOOLFLAGS
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
Return Value
Returns –1 if 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 is closer to the viewer. Otherwise, if depth information is ignored, and the decal will be the same size whether it is close to or far from the viewer, zero is returned.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.GetDecalSize
Direct3DRMTexture3
Retrieves the size of the decal.
Syntax
object.GetDecalSize(w As Single, h As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- w and h
- Width and height of the decal.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.GetDecalTransparency
Direct3DRMTexture3
Retrieves the transparency property of the decal.
Syntax
object.GetDecalTransparency( ) As CONST_DBOOLFLAGS
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
Return Value
Returns –1 if the decal has a transparent color, or zero otherwise.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.GetDecalTransparentColor
Direct3DRMTexture3
Retrieves the transparent color of the decal.
Syntax
object.GetDecalTransparentColor( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
Return Value
Returns the value of the transparent color.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.GetShades
Direct3DRMTexture3
Retrieves the number of shades used for each color in the texture when rendering.
Syntax
object.GetShades( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
Return Value
Returns the number of shades.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.GetSurface
Direct3DRMTexture3
Retrieves the Microsoft® DirectDraw® surface that was used to create the texture. This method only retrieves a surface if Direct3DRM3.CreateTextureFromSurface was used to create the texture.
Syntax
object.GetSurface(flags As Long) As DirectDrawSurface4
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- flags
- Flag value. Must be zero.
Return Value
Returns the corresponding DirectDrawSurface4 object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMTexture3.SetCacheOptions
Direct3DRMTexture3
Provides information about how texture management should treat this texture if texture memory is restricted.
Syntax
object.SetCacheOptions(importance As Long CONST_D3DRMTEXTURECACHEFLAGS As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- importance
- 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 rendered last if texture memory is restricted.
- flags
- One or more values from the CONST_D3DRMTEXTURECACHEFLAGS enumerated type.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMTexture3.SetColors
Direct3DRMTexture3
Sets the maximum number of colors used for rendering a Direct3DRMTexture3 object. This method is required only in the ramp color model.
Syntax
object.SetColors(c As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- c
- Number of colors. The default value is 8.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.SetDecalOrigin
Direct3DRMTexture3
Sets the origin of the decal as an offset from the top left of the decal.
Syntax
object.SetDecalOrigin(x As Long, y As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- x and y
- New origin, in decal coordinates, for the decal. The default origin is (0, 0).
Error Values
For a list of possible errors, see Direct3D Retained Mode Error 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
Direct3DRMTexture3.SetDecalScale
Direct3DRMTexture3
Sets the scaling property for a decal.
Syntax
object.SetDecalScale(considerScale As CONST_DBOOLFLAGS)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- considerScale
- Value indicating whether depth information is used when scaling the decal. If this parameter is set to D_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 is closer to the viewer. If this parameter is set to D_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 is D_TRUE.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.SetDecalSize
Direct3DRMTexture3
Sets the size of the decal to use if the decal is being scaled according to its depth in the scene.
Syntax
object.SetDecalSize(width As Single, height As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- width and height
- New width and height, in model coordinates, of the decal. The default size is [1, 1].
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method is also used to add a decal size key to a Direct3DRMTextureInterpolator object.
See Also
Direct3DRMTexture3.SetDecalTransparency
Direct3DRMTexture3
Sets the transparency property of the decal.
Syntax
object.SetDecalTransparency(transparencyEnabled As CONST_DBOOLFLAGS)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- transparencyEnabled
- Value indicating whether the decal has a transparent or opaque color. If set to D_TRUE, the decal has a transparent color; if set to D_FALSE, the decal does not have a transparent color. The default is D_FALSE.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMTexture3.SetDecalTransparentColor
Direct3DRMTexture3
Sets the transparent color for a decal.
Syntax
object.SetDecalTransparentColor(tcolor As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- tcolor
- New transparent color. The default is black. To specify an object's color, including the alpha component, call the CreateColorRGBA method from the DirectX7 interface on the object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method is also used to add a decal transparent color key to a Direct3DRMTextureInterpolator object.
See Also
Direct3DRMTexture3.SetShades
Direct3DRMTexture3
Sets the maximum number of shades to use for each color for the Direct3DRMTexture3 object when rendering. This method is required only in the ramp color model.
Syntax
object.SetShades(numShades As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMTexture3 object.
- numShades
- New number of shades. This value must be a power of 2. The default value is 16.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.