D3DXCreateTexture

The D3DXCreateTexture function creates an empty texture object.

HRESULT D3DXCreateTexture(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps
);

Parameters

pd3dDevice

The Direct3D device, an IDirect3DDevice7 interface, associated with the texture.

pFlags

A pointer to a DWORD value. This parameter allows you to specify the D3DX_TEXTURE_NOMIPMAP flag if mipmap generation is not desired. This value can be NULL. The D3DX_TEXTURE_NOMIPMAP flag may be returned in the case where mipmap creation is not supported.

pWidth

A pointer to a DWORD value, indicating the width in pixels. This parameter returns the corrected width.

pHeight

A pointer to a DWORD value, indicating the height in pixels. This parameter returns the corrected height.

pPixelFormat

A pointer to a member of the D3DX_SURFACEFORMAT enumerated type. D3DX_DEFAULT is not valid for this parameter. The input value for this parameter should be the desired texture format. The return value will be the closest texture format that is supported by the hardware.

pDDPal

A pointer to the DirectDraw palette, an IDirectDrawPalette interface, that is set (if present) on paletted surfaces. It is ignored even if it is set, for non-paletted surfaces. So, it allows specification of the palette to use if the resulting surface is an 8-bit palettized surface.

ppDDSurf

The address of a pointer to the DirectDrawSurface object, the texture created that matched the specifications and the current hardware.

pNumMipMaps

A pointer to a DWORD value. The number of mipmaps generated for a particular face of the cube map.

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

Unless the pFlags parameter is set to specifically prevent creating mipmaps, mipmaps are generated until reaching the minimum level size of 1x1.

For more information on mipmaps, see Texture Filtering With Mipmaps.

Width, height and pixel format are altered based on available hardware. For example, mipmap dimensions may be required to be powers of 2 and width may be required to be equal to height for square textures. Also, if the specified pixel format is unavailable, a best fit will be made.

This function creates a surface whose size and pixel format has been adjusted to match the requirements of the current device. The surface created is system memory which is marked as Texture-Managed; see Direct3D Immediate Mode documentation for more details.

The surface created may be larger or smaller than that specified by the width and height parameters. The pixel format chosen may not be the format passed in. Attention to the actual width, height, and pixel format is necessary only if you plan to directly access the surface returned by this function. (Doing so is not advised however, because you will find that the surface may have different properties on different devices.)

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

D3DXCreateCubeMapTexture