Export (0) Print
Expand All
Expand Minimize

IDirect3DDevice9::CreateTexture method

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

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

See also

IDirect3DDevice9
D3DXCreateTexture
D3DXCreateTextureFromFile
D3DXCreateTextureFromFileEx
D3DXCreateTextureFromFileInMemory
D3DXCreateTextureFromFileInMemoryEx
D3DXCreateTextureFromResource
D3DXCreateTextureFromResourceEx

 

 

Community Additions

ADD
Show:
© 2014 Microsoft