D3DXLoadTextureFromSurface

The D3DXLoadTextureFromSurface function loads a texture from a DirectDrawSurface into a mipmap level, performing the necessary color conversion.

HRESULT D3DXLoadTextureFromSurface(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPDIRECTDRAWSURFACE7 pSurfaceSrc,
  RECT* pSrcRect,
  RECT* pDestRect,
  D3DX_FILTERTYPE filterType
);

Parameters

pd3dDevice

A pointer to the Direct3D device, an IDirect3DDevice7 interface, associated with the texture.

pTexture

A pointer to the DirectDrawSurface that was created with either the D3DXCreateTextureFromFile or D3DXCreateTexture functions. This parameter points to the texture surface object.

mipMapLevel

Indicates mipmap level. See remarks.

pSurfaceSrc

A pointer to the source surface, an IDirectDrawSurface7 interface. The surface object that contains the pixels to load from.

pSrcRect

A pointer to a RECT structure, identifying the source rectangle. If NULL is specified for this parameter, the whole surface is used.

pDestRect

A pointer to a RECT structure, identifying the destination rectangle. If NULL is specified for this parameter, the whole surface is used.

filterType

A member of the D3DX_FILTERTYPE enumerated type, indicating what filtering function should be used for any necessary resizing or mipmap generation.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails, the return value may be one of the following values:

Remarks

This function provides a mechanism to copy one surface to another.

Concerning the mipMapLevel parameter:

• If the specified mipmap level does not exist, as error is returned.
• If D3DX_DEFAULT is specified and an equal number of mipmap levels exist, then all of the source mipmap levels are loaded.
• If the source has mipmap levels and the destination does not, the top level is used.
• If the destination has mipmap levels and the source does not, expansion is used.
• If there are unequal numbers of mipmap levels between the source and destination, expansion is used.

If the source or destination surface was created by Direct3DX, then the RECT structure should be specified in the original coordinates of that surface.

This function supports a full range of color-conversion for all surface formats that can be described by a D3DX_SURFACEFORMAT structure. It also implements filtered re-scaling and updates mipmaps automatically.

By taking pDestRect in the space of the original image, the application does not have to worry about how the surface may have been resized as part of the D3DXCreateTexture routine. For example, if an image was 100x150 pixels, then it may end up being 128x256 or 256x256 on different configurations. In both cases, the RECT structure to use to update the upper left quadrant is (0, 0, 50, 75); as if no resizing had taken place.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Version: Requires DirectX 7.0.
  Header: Declared in d3dxcore.h.
  Library: Use d3dx.lib.

See Also

D3DXLoadTextureFromFile, D3DXLoadTextureFromMemory