D3DXLoadTextureFromMemory

The D3DXLoadTextureFromMemory function loads a mipmap level from memory, performing the necessary color conversion.

HRESULT D3DXLoadTextureFromMemory(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPVOID pMemory,
  LPDIRECTDRAWPALETTE pDDPal,
  D3DX_SURFACEFORMAT srcPixelFormat,
  DWORD srcPitch,
  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.

pMemory

A pointer to the source memory from which the texture will be loaded.

pDDPal

A pointer to the DirectDraw palette, an IDirectDrawPalette interface, that the application passes in optionally if the memory is supposed to be paletteized.

srcPixelFormat

A pointer to a member of the D3DX_SURFACEFORMAT enumerated type, indicating the pixel format of the source.

srcPitch

The pitch of the memory, or D3DX_DEFAULT. This parameter is based on the srcPixelFormat, parameter.

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 the filter used for 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 some pixels from memory to a surface.

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

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.

This function assumes that the source (memory) has been loaded in full.

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.
  Windows CE: Unsupported.
  Version: Requires DirectX 7.0.
  Header: Declared in d3dxcore.h.
  Library: Use d3dx.lib.

See Also

D3DXLoadTextureFromFile, D3DXLoadTextureFromSurface