This topic has not yet been rated - Rate this topic

IDirect3DDevice9::CreateTexture method

Applies to: desktop apps only

Creates a texture resource.

Syntax

Copy

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

Width [in]

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.

Height [in]

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.

Levels [in]

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.

Usage [in]

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.

Format [in]

Type: D3DFORMAT

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

Pool [in]

Type: D3DPOOL

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

ppTexture [out, retval]

Type: IDirect3DTexture9**

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

pSharedHandle [in]

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

Header	D3D9.h
Library	D3D9.lib

IDirect3DDevice9::CreateTexture method

Syntax

Parameters

Return value

Remarks

Requirements

See also