D3DXCreateTextureFromFileEx 函式

  • 發行項

從檔案建立紋理。 這是比 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
);

參數

pDevice [in]

類型： LPDIRECT3DDEVICE9

IDirect3DDevice9介面的指標，代表要與紋理相關聯的裝置。

pSrcFile [in]

類型： LPCTSTR

指定檔案名的字串指標。 如果編譯器設定需要 Unicode，則資料類型 LPCTSTR 會解析為 LPCWSTR。 否則，字串資料類型會解析為 LPCSTR。 請參閱＜備註＞。

寬度 [in]

類型： UINT

以圖元為單位的寬度。 如果此值為零或D3DX_DEFAULT，維度會取自檔案，並四捨五入為兩個的乘冪。 如果裝置支援 2 個紋理的非電源，且 已指定D3DX_DEFAULT_NONPOW2 ，將不會四捨五入大小。

高度 [in]

類型： UINT

高度，以圖元為單位。 如果此值為零或D3DX_DEFAULT，維度會取自檔案，並四捨五入為兩個的乘冪。 如果裝置支援 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 ， 則必須將 Pool 設定為 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 指定要在 .dds 紋理載入記憶體時，從 mipmap 鏈結頂端略過 (的 mip 層級數目) ;這可讓您跳到最多 32 個層級。

ColorKey [in]

類型： D3DCOLOR

要以透明黑色取代的D3DCOLOR值，或 0 以停用色彩索引鍵。 這一律是 32 位的 ARGB 色彩，與來源影像格式無關。 Alpha 相當重要，而且通常應該設定為 FF 以取得不透明色彩索引鍵。 因此，對於不透明黑色，此值會等於0xFF000000。

pSrcInfo [in， out]

類型： D3DXIMAGE_INFO*

要填入來源影像檔或Null中資料描述之D3DXIMAGE_INFO結構的指標。

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。

已套用的紋理會自動讓每個層級填滿載入的紋理。 將影像載入到已套用的紋理時，某些裝置無法移至 1x1 影像，而此函式將會失敗。 如果發生這種情況，則必須手動載入映射。

若要獲得最佳效能，請使用 D3DXCreateTextureFromFileEx：

  1. 在載入時間執行影像縮放和格式轉換可能會很慢。 使用影像的格式和解析度來儲存影像。 如果目標硬體需要 2 個維度的電源，則使用 2 個維度的電源來建立及儲存映射。
  2. 若要在載入時建立 mipmap 影像，請使用 D3DX_FILTER_BOX進行篩選。 方塊篩選比其他篩選類型更快，例如D3DX_FILTER_TRIANGLE。
  3. 請考慮使用 DDS 檔案。 由於 DDS 檔案可用來代表任何 Direct3D 9 紋理格式，因此 D3DX 很容易讀取。 此外，它們可以儲存 mipmap，因此任何 mipmap 產生演算法都可以用來撰寫影像。

載入 .dds 檔案時略過 mipmap 層級時，請使用 D3DX_SKIP_DDS_MIP_LEVELS 宏來產生 MipFilter 值。 此宏會接受要略過的層級數目，並傳回篩選值，然後傳遞至 MipFilter 參數。

規格需求

需求 值
標頭
D3dx9tex.h
程式庫
D3dx9.lib

另請參閱

D3DXCreateTextureFromFile

D3DX 9 中的紋理函式