Microsoft DirectX 8.0 (C++)

D3DXLoadSurfaceFromMemory

Loads a surface from memory.

HRESULT D3DXLoadSurfaceFromMemory(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCVOID pSrcMemory,
  D3DFORMAT SrcFormat,
  UINT SrcPitch,
  CONST PALETTEENTRY* pSrcPalette,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey
);

Parameters

pDestSurface
[in] Pointer to an IDirect3DSurface8 interface. Specifies the destination surface, which receives the image.
pDestPalette
[in] Pointer to a PALETTEENTRY structure, the destination palette of 256 colors or NULL. See Remarks.
pDestRect
[in] Pointer to a RECT structure. Specifies the destination rectangle. Set this parameter to NULL to specify the entire surface.
pSrcMemory
[in] Pointer to the top-left corner of the source image in memory.
SrcFormat
[in] Member of the D3DFORMAT enumerated type, the pixel format of the source image.
SrcPitch
[in] Pitch of source image, in bytes. For DXT formats, this number should represent the width of one row of cells, in bytes.
pSrcPalette
[in] Pointer to a PALETTEENTRY structure, the source palette of 256 colors or NULL. See Remarks.
pSrcRect
[in] Pointer to a RECT structure. Specifies the dimensions of the source image in memory. This value cannot be NULL.
Filter
[in] A combination of one or more flags controlling how the image is filtered. Specifying D3DX_DEFAULT for this parameter is the equivalent of specifying D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER.

Each valid filter must contain exactly one of the following flags.

D3DX_FILTER_BOX
Each pixel is computed by averaging a 2×2(×2) box of pixels from the source image. This filter works only when the dimensions of the destination are half those of the source, as is the case with mipmaps.
D3DX_FILTER_LINEAR
Each destination pixel is computed by sampling the four nearest pixels from the source image. This filter works best when the scale on both axes is less than two.
D3DX_FILTER_NONE
No scaling or filtering will take place. Pixels outside the bounds of the source image are assumed to be transparent black.
D3DX_FILTER_POINT
Each destination pixel is computed by sampling the nearest pixel from the source image.
D3DX_FILTER_TRIANGLE
Every pixel in the source image contributes equally to the destination image. This is the slowest of the filters.

In addition, you can use the OR operator to specify zero or more of the following optional flags with a valid filter.

D3DX_FILTER_MIRROR
Specifying this flag is the same as specifying the D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, and D3DX_FILTER_MIRROR_W flags.
D3DX_FILTER_MIRROR_U
Pixels off the edge of the texture on the u-axis should be mirrored, not wrapped.
D3DX_FILTER_MIRROR_V
Pixels off the edge of the texture on the v-axis should be mirrored, not wrapped.
D3DX_FILTER_MIRROR_W
Pixels off the edge of the texture on the w-axis should be mirrored, not wrapped.
D3DX_FILTER_DITHER
The resulting image must be dithered using a 4x4 ordered dither algorithm.
ColorKey
[in] D3DCOLOR value to replace with transparent black, or 0 to disable the colorkey. This is always a 32-bit ARGB color, independent of the source image format. Alpha is significant and should usually be set to FF for opaque colorkeys. Thus, for opaque black, the value would be equal to 0xFF000000.

Return Values

If the function succeeds, the return value is D3D_OK.

If the function fails, the return value can be one of the following values.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

Remarks

For details on PALETTEENTRY, see the Microsoft® Platform Software Development Kit (SDK). Note that as of Microsoft DirectX® 8.0, the peFlags member of the PALLETTEENTRY structure does not function as documented in the Platform SDK. The peFlags member is now the alpha channel for 8-bit palletized formats.

Requirements

  Header: Declared in D3dx8tex.h.
  Import Library: Use D3dx8.lib.