D3DXCreateTextureFromFileEx 函数

项目
06/13/2023

从文件创建纹理。这是比 D3DXCreateTextureFromFile 更高级的函数。

语法

HRESULT D3DXCreateTextureFromFileEx(
  _In_    LPDIRECT3DDEVICE9  pDevice,
  _In_    LPCTSTR            pSrcFile,
  _In_    UINT               Width,
  _In_    UINT               Height,
  _In_    UINT               MipLevels,
  _In_    DWORD              Usage,
  _In_    D3DFORMAT          Format,
  _In_    D3DPOOL            Pool,
  _In_    DWORD              Filter,
  _In_    DWORD              MipFilter,
  _In_    D3DCOLOR           ColorKey,
  _Inout_ D3DXIMAGE_INFO     *pSrcInfo,
  _Out_   PALETTEENTRY       *pPalette,
  _Out_   LPDIRECT3DTEXTURE9 *ppTexture
);

parameters

pDevice [in]

类型： LPDIRECT3DDEVICE9

指向 IDirect3DDevice9 接口的指针，表示要与纹理关联的设备。

pSrcFile [in]

类型： LPCTSTR

指向指定文件名的字符串的指针。如果编译器设置需要 Unicode，则数据类型 LPCTSTR 解析为 LPCWSTR。否则，字符串数据类型解析为 LPCSTR。请参阅“备注”。

Width [in]

类型： UINT

宽度（以像素为单位）。如果此值为零或D3DX_DEFAULT，则维度取自文件并向上舍入为 2 的幂。如果设备支持 2 个纹理的非幂，并且指定了D3DX_DEFAULT_NONPOW2 ，则不会舍入大小。

高度 [in]

类型： UINT

高度（以像素为单位）。如果此值为零或D3DX_DEFAULT，则维度取自文件并向上舍入为 2 的幂。如果设备支持 2 个纹理的非幂，并且 D3DX_DEFAULT_NONPOW2 是分离的，则不会对大小进行舍入。

MipLevels [in]

类型： UINT

请求的 mip 级别数。如果此值为零或D3DX_DEFAULT，则会创建完整的 mipmap 链。如果D3DX_FROM_FILE，大小将完全按照文件中的原样进行，如果这违反了设备功能，调用将失败。

用法 [in]

类型： DWORD

0、 D3DUSAGE_RENDERTARGET 或 D3DUSAGE_DYNAMIC。将此标志设置为 D3DUSAGE_RENDERTARGET 表示该图面将用作呈现目标。然后，可以将资源传递给 SetRenderTarget 方法的 pNewRenderTarget 参数。如果指定了D3DUSAGE_RENDERTARGET或D3DUSAGE_DYNAMIC，则必须将“池”设置为“D3DPOOL_DEFAULT”，并且应用程序应通过调用 CheckDeviceFormat 检查设备支持此操作。 D3DUSAGE_DYNAMIC 指示应动态处理图面。请参阅使用动态纹理。

格式 [in]

类型： D3DFORMAT

D3DFORMAT 枚举类型的成员，描述纹理请求的像素格式。返回的纹理的格式可能与 Format 指定的格式不同。应用程序应检查返回的纹理的格式。如果D3DFMT_UNKNOWN，则格式取自文件。如果D3DFMT_FROM_FILE，则采用的格式与文件中的格式完全相同，如果这违反了设备功能，调用将失败。

池 [in]

类型： D3DPOOL

D3DPOOL 枚举类型的成员，描述应放置纹理的内存类。

筛选器 [in]

类型： DWORD

控制图像筛选方式的一个或多个 D3DX_FILTER 常量的组合。为此参数指定 D3DX_DEFAULT 等效于指定D3DX_FILTER_TRIANGLE |D3DX_FILTER_DITHER。

MipFilter [in]

类型： DWORD

控制图像筛选方式的一个或多个 D3DX_FILTER 常量的组合。为此参数指定D3DX_DEFAULT等效于指定D3DX_FILTER_BOX。此外，使用位 27-31 指定要从 mipmap 链顶部 (跳过的 mip 级别数，) .dds 纹理加载到内存中时;这样，最多可以跳过 32 个级别。

ColorKey [in]

类型： D3DCOLOR

要替换为透明黑色的 D3DCOLOR 值，或 0 表示禁用颜色键。这始终是 32 位 ARGB 颜色，与源图像格式无关。 Alpha 非常重要，对于不透明颜色键，通常应设置为 FF。因此，对于不透明的黑色，该值将等于 0xFF000000。

pSrcInfo [in， out]

类型： D3DXIMAGE_INFO*

指向要用源图像文件中数据的说明填充 的D3DXIMAGE_INFO 结构的指针，或 为 NULL。

pPalette [out]

类型： PALETTEENTRY*

指向 PALETTEENTRY 结构的指针，表示要填充的 256 色调色板或 NULL。

ppTexture [out]

类型： LPDIRECT3DTEXTURE9*

指向 IDirect3DTexture9 接口的指针的地址，表示创建的纹理对象。

返回值

类型： HRESULT

如果函数成功，则返回值D3D_OK。如果函数失败，则返回值可以是以下值之一：D3DERR_INVALIDCALL、D3DERR_NOTAVAILABLE、D3DERR_OUTOFVIDEOMEMORY、D3DXERR_INVALIDDATA E_OUTOFMEMORY。

备注

编译器设置还确定函数版本。如果定义了 Unicode，则函数调用将解析为 D3DXCreateTextureFromFileExW。否则，函数调用将解析为 D3DXCreateTextureFromFileExA，因为正在使用 ANSI 字符串。

使用 D3DXCheckTextureRequirements 确定设备是否可以支持给定当前状态的纹理。

此函数支持以下文件格式：.bmp、.dds、.dib、.hdr、.jpg、.pfm、.png、.ppm 和 .tga。请参阅 D3DXIMAGE_FILEFORMAT。

Mipmapped 纹理会自动为每个级别填充已加载的纹理。将图像加载到误贴纹理中时，某些设备无法转到 1x1 图像，并且此功能将失败。如果发生这种情况，则需要手动加载映像。

为了在使用 D3DXCreateTextureFromFileEx 时获得最佳性能：

在加载时执行图像缩放和格式转换可能会很慢。以要使用的格式和分辨率存储图像。如果目标硬件需要 2 个维度的电源，则使用 2 个维度的强大功能创建和存储映像。
若要在加载时创建 mipmap 图像，请使用 D3DX_FILTER_BOX进行筛选。框筛选器比其他筛选器类型（如D3DX_FILTER_TRIANGLE）快得多。
请考虑使用 DDS 文件。由于 DDS 文件可用于表示任何 Direct3D 9 纹理格式，因此 D3DX 很容易读取它们。此外，它们可以存储 mipmap，因此可以使用任何 mipmap 生成算法来创作图像。

加载 .dds 文件时跳过 mipmap 级别时，请使用 D3DX_SKIP_DDS_MIP_LEVELS 宏生成 MipFilter 值。此宏采用要跳过的级别数和筛选器类型，并返回筛选器值，该值随后将传递到 MipFilter 参数中。

要求

要求	值
标头	D3dx9tex.h
库	D3dx9.lib

另请参阅

D3DXCreateTextureFromFile
D3DX 9 中的纹理函数

通过

D3DXCreateTextureFromFileEx 函数

语法

parameters

返回值

备注

要求

另请参阅

反馈

其他资源