IDirect3DDevice9::CreateTexture method (d3d9.h)

Creates a texture resource.

Syntax

HRESULT CreateTexture(
  [in]          UINT              Width,
  [in]          UINT              Height,
  [in]          UINT              Levels,
  [in]          DWORD             Usage,
  [in]          D3DFORMAT         Format,
  [in]          D3DPOOL           Pool,
  [out, retval] IDirect3DTexture9 **ppTexture,
  [in]          HANDLE            *pSharedHandle
);

Parameters

[in] Width

Type: UINT

Width of the top-level of the texture, in pixels. The pixel dimensions of subsequent levels will be the truncated value of half of the previous level's pixel dimension (independently). Each dimension clamps at a size of 1 pixel. Thus, if the division by 2 results in 0, 1 will be taken instead.

[in] Height

Type: UINT

Height of the top-level of the texture, in pixels. The pixel dimensions of subsequent levels will be the truncated value of half of the previous level's pixel dimension (independently). Each dimension clamps at a size of 1 pixel. Thus, if the division by 2 results in 0, 1 will be taken instead.

[in] Levels

Type: UINT

Number of levels in the texture. If this is zero, Direct3D will generate all texture sublevels down to 1 by 1 pixels for hardware that supports mipmapped textures. Call IDirect3DBaseTexture9::GetLevelCount to see the number of levels generated.

[in] Usage

Type: DWORD

Usage can be 0, which indicates no usage value. However, if usage is desired, use a combination of one or more D3DUSAGE constants. It is good practice to match the usage parameter with the behavior flags in IDirect3D9::CreateDevice.

[in] Format

Type: D3DFORMAT

Member of the D3DFORMAT enumerated type, describing the format of all levels in the texture.

[in] Pool

Type: D3DPOOL

Member of the D3DPOOL enumerated type, describing the memory class into which the texture should be placed.

[out, retval] ppTexture

Type: IDirect3DTexture9**

Pointer to an IDirect3DTexture9 interface, representing the created texture resource.

[in] pSharedHandle

Type: HANDLE*

Reserved. Set this parameter to NULL. This parameter can be used in Direct3D 9 for Windows Vista to share resources.

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK. If the method fails, the return value can be one of the following: D3DERR_INVALIDCALL, D3DERR_OUTOFVIDEOMEMORY, E_OUTOFMEMORY.

Remarks

An application can discover support for Automatic Generation of Mipmaps (Direct3D 9) in a particular format by calling IDirect3D9::CheckDeviceFormat with D3DUSAGE_AUTOGENMIPMAP. If IDirect3D9::CheckDeviceFormat returns D3DOK_NOAUTOGEN, IDirect3DDevice9::CreateTexture will succeed but it will return a one-level texture.

In Windows Vista CreateTexture can create a texture from a system memory pointer allowing the application more flexibility over the use, allocation and deletion of the system memory. For example, an application could pass a GDI system memory bitmap pointer and get a Direct3D texture interface around it. Using a system memory pointer with CreateTexture has the following restrictions.

• The pitch of the texture must be equal to the width multiplied by the number of bytes per pixel.
• Only textures with a single mipmap level are supported. The Levels argument must be 1.
• The Pool argument must be D3DPOOL_SYSTEMMEM.
• The pSharedHandle argument must be a valid pointer to a buffer that can hold the system memory point; *pSharedHandle must be a valid pointer to system memory with a size in bytes of texture width * texture height * bytes per pixel of the texture format.

Requirements

See also

D3DXCreateTexture

D3DXCreateTextureFromFile

D3DXCreateTextureFromFileEx

D3DXCreateTextureFromFileInMemory

D3DXCreateTextureFromFileInMemoryEx

D3DXCreateTextureFromResource

D3DXCreateTextureFromResourceEx

IDirect3DDevice9