Creates a texture resource.
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 );
- Width [in]
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]
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]
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]
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]
Member of the D3DFORMAT enumerated type, describing the format of all levels in the texture.
- Pool [in]
Member of the D3DPOOL enumerated type, describing the memory class into which the texture should be placed.
- ppTexture [out, retval]
Pointer to an IDirect3DTexture9 interface, representing the created texture resource.
- pSharedHandle [in]
Reserved. Set this parameter to NULL. This parameter can be used in Direct3D 9 for Windows Vista to share resources.
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.
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.