DirectX SDK

Direct3DDevice7.Load

The Direct3DDevice7.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.

object.Load( _ 
    DestTex As DirectDrawSurface7, _ 
    xDest As Long, _ 
    yDest As Long, _ 
    SrcTex  As DirectDrawSurface7, _ 
    rcSrcRect As RECT, _ 
    flags As Long)

Parameters

object

Object expression that resolves to a Direct3DDevice7 object.

DestTex

The DirectDrawSurface7 class that will receive image data from the source texture. For complex texture surfaces like cubic envionment maps and mipmaps, this must refer to the top-level surface.

xDest and yDest

The x- and y-coordinates of the point at which the method should load the image data onto the destination texture.

SrcTex

The DirectDrawSurface7 class that contains the image data to be loaded. For complex texture surfaces like cubic envionment maps and mipmaps, this must refer to the top-level surface.

rcSrcRect

Address of a RECT type that describes the area within the source texture that the method will load. Set this parameter to Nothing when the source rectangle should cover the entire source texture or when using this method to explicitly load a managed texture.

flags

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.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following error codes:

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 mipmaps at all levels, cube-map 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.