Platform SDK: DirectX

IDirect3DDevice7::Load

The IDirect3DDevice7::Load method loads a rectangular area of a source texture to a specified point in a destination texture or to faces within a cubic environment map.

HRESULT Load( 
  LPDIRECTDRAWSURACE7 lpDestTex, 
  LPPOINT lpDestPoint, 
  LPDIRECTDRAWSURACE7 lpSrcTex, 
  LPRECT lprcSrcRect, 
  DWORD dwFlags
);

Parameters

lpDestTex

Address of the IDirectDrawSurface7 interface of the texture that receives image data from the source texture. The destination texture can be a cubic environment map. For complex texture surfaces like cubic envionment maps and mipmaps, this must point to the top-level surface.

lpDestPoint

Address of a POINT structure that describes the point at which the method loads the image data onto the destination texture. Set this parameter to NULL when the destination point should be the origin of the destination texture.

lpSrcTex

Address of the IDirect3DTexture7 interface of the texture that contains the image data to be loaded. For complex texture surfaces like cubic envionment maps and mipmaps, this must point to the top-level surface.

lprcSrcRect

Address of a RECT structure that describes the area within the source texture that the method loads. Set this parameter to NULL when the source rectangle should cover the entire source texture.

dwFlags

Value indicating, in the case of a cubic environment map, which face of the destination texture is to receive the image data. This can be any combination of the following flags.

0: Required if the destination texture is a managed texture.
DDSCAPS2_CUBEMAP_ALLFACES: All faces should be loaded with the image data within the source texture.
DDSCAPS2_CUBEMAP_NEGATIVEX, DDSCAPS2_CUBEMAP_NEGATIVEY, or DDSCAPS2_CUBEMAP_NEGATIVEZ: The negative x, y, or z faces should receive the image data.
DDSCAPS2_CUBEMAP_POSITIVEX, DDSCAPS2_CUBEMAP_POSITIVEY, or DDSCAPS2_CUBEMAP_POSITIVEZ: The positive x, y, or z faces should receive the image data.

Return Values

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

The destination texture can be used with any rendering device, not just the one that created it. On hardware devices, the load operation is hardware-accelerated.

Loading textures into video memory by calling this method is preferred over blit operations.

This method copies all mip-levels, cubemap faces, palettes and color keys from the source texture to the destination texture.

When using this method to load mipmaps, the following special points apply:

The destination texture surface can be a subset of the mip-levels contained in the source texture. In this case, only the mip-levels common to both textures are copied. This is useful in implementing texture LOD. You can create a video memory texture with only two mip-levels, then use this method to copy those levels from a source texture that comprises the entire set of mip-levels.
The source and destination surface pointers must point to top-level surfaces.
When loading a subrectangle of a mipmap, the subrectangle refers to the top-level surface in the mipmap chain, and is divided by two for each lower mip-level.

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 d3d.h.