D3DXCreateTextureFromFileEx-Funktion

Erstellt eine Textur aus einer Datei. Dies ist eine erweiterte Funktion als D3DXCreateTextureFromFile.

Syntax

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
);

Parameter

pDevice [in]

Typ: LPDIRECT3DDEVICE9

Zeiger auf eine IDirect3DDevice9-Schnittstelle , die das Gerät darstellt, das der Textur zugeordnet werden soll.

pSrcFile [in]

Typ: LPCTSTR

Zeiger auf eine Zeichenfolge, die den Dateinamen angibt. Wenn die Compilereinstellungen Unicode erfordern, wird der Datentyp LPCTSTR in LPCWSTR aufgelöst. Andernfalls wird der Zeichenfolgendatentyp in LPCSTR aufgelöst. Siehe Hinweise.

Breite [in]

Typ: UINT

Breite in Pixel. Wenn dieser Wert null oder D3DX_DEFAULT ist, werden die Dimensionen aus der Datei übernommen und auf eine Leistung von zwei aufgerundet. Wenn das Gerät zwei Texturen ohne Leistung unterstützt und D3DX_DEFAULT_NONPOW2 angegeben ist, wird die Größe nicht gerundet.

Höhe [in]

Typ: UINT

Höhe in Pixel. Wenn dieser Wert null oder D3DX_DEFAULT ist, werden die Dimensionen aus der Datei übernommen und auf eine Leistung von zwei aufgerundet. Wenn das Gerät 2 Texturen ohne Leistung unterstützt und D3DX_DEFAULT_NONPOW2 getrennt ist, wird die Größe nicht gerundet.

MipLevels [in]

Typ: UINT

Anzahl der angeforderten Mip-Ebenen. Wenn dieser Wert null oder D3DX_DEFAULT ist, wird eine vollständige Mipmap-Kette erstellt. Wenn D3DX_FROM_FILE, wird die Größe genau wie in der Datei verwendet, und der Aufruf schlägt fehl, wenn dies die Gerätefunktionen verletzt.

Verwendung [in]

Typ: DWORD

0, D3DUSAGE_RENDERTARGET oder D3DUSAGE_DYNAMIC. Das Festlegen dieses Flags auf D3DUSAGE_RENDERTARGET gibt an, dass die Oberfläche als Renderziel verwendet werden soll. Die Ressource kann dann an den pNewRenderTarget-Parameter der SetRenderTarget-Methode übergeben werden. Wenn entweder D3DUSAGE_RENDERTARGET oder D3DUSAGE_DYNAMIC angegeben ist, muss Pool auf D3DPOOL_DEFAULT festgelegt werden, und die Anwendung sollte überprüfen, ob das Gerät diesen Vorgang unterstützt, indem CheckDeviceFormat aufgerufen wird. D3DUSAGE_DYNAMIC gibt an, dass die Oberfläche dynamisch behandelt werden soll. Weitere Informationen finden Sie unter Verwenden dynamischer Texturen.

Format [in]

Typ: D3DFORMAT

Member des aufgezählten D3DFORMAT-Typs , der das angeforderte Pixelformat für die Textur beschreibt. Die zurückgegebene Textur hat möglicherweise ein anderes Format als das durch Format angegebene. Anwendungen sollten das Format der zurückgegebenen Textur überprüfen. Wenn D3DFMT_UNKNOWN, wird das Format aus der Datei übernommen. Wenn D3DFMT_FROM_FILE, wird das Format genau wie in der Datei verwendet, und der Aufruf schlägt fehl, wenn dies die Gerätefunktionen verletzt.

Pool [in]

Typ: D3DPOOL

Member des aufgezählten D3DPOOL-Typs , der die Speicherklasse beschreibt, in der die Textur platziert werden soll.

Filtern [in]

Typ: DWORD

Eine Kombination aus einer oder mehreren D3DX_FILTER Konstanten, die steuern, wie das Bild gefiltert wird. Die Angabe D3DX_DEFAULT für diesen Parameter entspricht der Angabe von D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER.

MipFilter [in]

Typ: DWORD

Eine Kombination aus einer oder mehreren D3DX_FILTER Konstanten, die steuern, wie das Bild gefiltert wird. Das Angeben D3DX_DEFAULT für diesen Parameter entspricht der Angabe D3DX_FILTER_BOX. Verwenden Sie außerdem die Bits 27-31, um die Anzahl der Mip-Ebenen anzugeben, die übersprungen werden sollen (vom Anfang der Mipmap-Kette), wenn eine DDS-Textur in den Arbeitsspeicher geladen wird. Dadurch können Sie bis zu 32 Ebenen überspringen.

ColorKey [in]

Typ: D3DCOLOR

D3DCOLOR-Wert , der durch transparentes Schwarz ersetzt werden soll, oder 0, um die Farbtaste zu deaktivieren. Dies ist immer eine 32-Bit-ARGB-Farbe, unabhängig vom Quellbildformat. Alpha ist signifikant und sollte normalerweise für undurchsichtige Farbtasten auf FF festgelegt werden. Daher wäre der Wert für undurchsichtiges Schwarz gleich 0xFF000000.

pSrcInfo [in, out]

Typ: D3DXIMAGE_INFO*

Zeiger auf eine D3DXIMAGE_INFO Struktur, die mit einer Beschreibung der Daten in der Quellbilddatei oder NULL ausgefüllt werden soll.

pPalette [out]

Typ: PALETTEENTRY*

Zeiger auf eine PALETTEENTRY-Struktur , die eine zu füllende Palette mit 256 Farben darstellt, oder NULL.

ppTexture [out]

Typ: LPDIRECT3DTEXTURE9*

Adresse eines Zeigers auf eine IDirect3DTexture9-Schnittstelle , die das erstellte Texturobjekt darstellt.

Rückgabewert

Typ: HRESULT

Wenn die Funktion erfolgreich ist, wird der Rückgabewert D3D_OK. Wenn die Funktion fehlschlägt, kann der Rückgabewert wie folgt aussehen: D3DERR_INVALIDCALL, D3DERR_NOTAVAILABLE, D3DERR_OUTOFVIDEOMEMORY, D3DXERR_INVALIDDATA, E_OUTOFMEMORY.

Bemerkungen

Die Compilereinstellung bestimmt auch die Funktionsversion. Wenn Unicode definiert ist, wird der Funktionsaufruf in D3DXCreateTextureFromFileExW aufgelöst. Andernfalls wird der Funktionsaufruf in D3DXCreateTextureFromFileExA aufgelöst, da ANSI-Zeichenfolgen verwendet werden.

Verwenden Sie D3DXCheckTextureRequirements , um zu bestimmen, ob Ihr Gerät die Textur im aktuellen Zustand unterstützen kann.

Diese Funktion unterstützt die folgenden Dateiformate: .bmp, DDS, DIB, HDR, .jpg, PFM, .png, PPM und TGA. Siehe D3DXIMAGE_FILEFORMAT.

In Mipmapped-Texturen wird jede Ebene automatisch mit der geladenen Textur gefüllt. Beim Laden von Bildern in mipmappenfähige Texturen können einige Geräte nicht zu einem 1x1-Bild wechseln, und diese Funktion schlägt fehl. In diesem Fall müssen die Bilder manuell geladen werden.

Optimale Leistung bei Verwendung von D3DXCreateTextureFromFileEx:

1. Die Bildskalierung und Formatkonvertierung zur Ladezeit kann langsam sein. Speichern Sie Bilder in dem Format und der Auflösung, die sie verwenden. Wenn die Zielhardware eine Leistung von zwei Dimensionen erfordert, erstellen und speichern Sie Bilder mit einer Leistung von zwei Dimensionen.
2. Für die Erstellung von mipmap-Images zur Ladezeit filtern Sie mit D3DX_FILTER_BOX. Ein Boxfilter ist viel schneller als andere Filtertypen wie z. B. D3DX_FILTER_TRIANGLE.
3. Erwägen Sie die Verwendung von DDS-Dateien. Da DDS-Dateien verwendet werden können, um jedes Direct3D 9-Texturformat darzustellen, sind sie für D3DX sehr einfach zu lesen. Außerdem können sie Mipmaps speichern, sodass alle Algorithmen zur Mipmap-Generierung zum Erstellen der Bilder verwendet werden können.

Verwenden Sie beim Überspringen von Mipmap-Ebenen beim Laden einer DDS-Datei das makro D3DX_SKIP_DDS_MIP_LEVELS, um den MipFilter-Wert zu generieren. Dieses Makro verwendet die Anzahl der zu überspringenden Ebenen und den Filtertyp und gibt den Filterwert zurück, der dann an den MipFilter-Parameter übergeben wird.

Anforderungen

Anforderung	Wert
Header	D3dx9tex.h
Bibliothek	D3dx9.lib

Siehe auch

D3DXCreateTextureFromFile

Texturfunktionen in D3DX 9