D3DXCreateTextureFromFileEx 関数

  • [アーティクル]

D3DXCreateTextureFromFileEx 関数

ファイルを基にしてテクスチャを作成する。これは、D3DXCreateTextureFromFile の上位の関数である。

構文

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

パラメータ

  • pDevice
    [in] IDirect3DDevice9 インターフェイスへのポインタ。テクスチャに関連付けられているデバイスを表す。
  • pSrcFile
    [in] ファイル名を指定する文字列へのポインタ。コンパイラの設定が Unicode を要求している場合、データ タイプ LPCTSTR は LPCWSTR になる。それ以外の場合は、この文字列のデータ タイプは LPCSTR になる。「注意」を参照すること。
  • Width
    [in] 幅 (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
  • Height
    [in] 高さ (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
  • MipLevels
    [in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
  • Usage
    [in] 0、D3DUSAGE_RENDERTARGET、または D3DUSAGE_DYNAMIC。このフラグを D3DUSAGE_RENDERTARGET に設定すると、そのサーフェイスはレンダリング ターゲットとして使われることを示す。リソースは、IDirect3DDevice9::SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET または D3DUSAGE_DYNAMIC を指定する場合、Pool を D3DPOOL_DEFAULT に設定し、アプリケーションは IDirect3D9::CheckDeviceFormat を呼び出して、デバイスがこの処理をサポートしていることを確認する必要がある。D3DUSAGE_DYNAMIC は、サーフェイスを動的に処理する必要があることを示す。動的テクスチャの使い方の詳細については、「動的テクスチャの使い方」を参照すること。
  • Format
    D3DFORMAT 列挙型のメンバ。テクスチャに対して要求されたピクセル フォーマットを記述する。返されるテクスチャのフォーマットは、Format で指定したフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format の値が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
  • Pool
    [in] D3DPOOL 列挙型のメンバ。テクスチャの配置先となるメモリ クラスを記述する。
  • Filter
    [in] イメージをフィルタリングする方法を制御する 1 つあるいは複数の D3DX_FILTER の組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。
  • MipFilter
    [in] イメージをフィルタリングする方法を制御する 1 つあるいは複数の D3DX_FILTER の組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。
  • ColorKey
    [in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラー キーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
  • pSrcInfo
    [in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
  • pPalette
    [out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。
  • ppTexture
    [out] 作成されたキューブ テクスチャ オブジェクトを表す、IDirect3DTexture9 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE このデバイスは、照会されたテクニックをサポートしていない。
D3DERR_OUTOFVIDEOMEMORY Microsoft® Direct3D® が処理を行うのに十分なディスプレイ メモリがない。
D3DERR_INVALIDCALL メソッドの呼び出しが無効である。たとえば、メソッドのパラメータに無効な値が設定されている場合などである。
D3DXERR_INVALIDDATA データが無効である。
E_OUTOFMEMORY Direct3D が呼び出しを完了するための十分なメモリを割り当てることができなかった。

注意

コンパイラの設定によって関数のバージョンも決まる。Unicode が定義されている場合、この関数の呼び出しは D3DXCreateTextureFromFileExW になる。それ以外の場合は ANSI 文字列を使うので、この関数の呼び出しは D3DXCreateTextureFromFileExA になる。

この関数がサポートしている ファイル フォーマットは、.bmp、.dds、.dib、.jpg、.png、および .tga である。

ミップマップされたテクスチャの各レベルには、ロードされたテクスチャが自動的に格納される。

ミップマップされたテクスチャにイメージをロードするとき、デバイスによっては、1x1 のイメージに変換できず、関数が失敗することがある。このような場合は、イメージを手動でロードする必要がある。

D3DXCreateTextureFromFileEx を使って最適なパフォーマンスを得るには、次のことを行う。

  1. イメージのスケーリングおよびフォーマット変換をロード時に行うと、処理に時間がかかる場合がある。イメージは、使うときのフォーマットおよび解像度で保存する。ターゲット ハードウェアで処理できるのが 2 の累乗のディメンジョンだけの場合は、2 の累乗のディメンジョンを使ってイメージを作成し保存する。
  2. ロード時にミップマップ イメージを作成する場合は、D3DXFILTER_BOX を使ってフィルタリングする。ボックス フィルタは、D3DXFILTER_TRIANGLE などの他の種類のフィルタよりも処理が速い。
  3. DDS ファイルの使用を検討する。Microsoft DirectX® 9.0 テキスト フォーマットはすべて .dds ファイルを使って表現できるため、.dds ファイルは Direct3D エクステンション (D3DX) にとって読み取りやすい。また、.dds ファイル にミップマップを保存することができ、任意のミップマップ生成アルゴリズムを使ってイメージを作成できる。

関数の情報

ヘッダー d3dx9tex.h
インポート ライブラリ d3dx9.lib
最低限のオペレーティング システム Windows 98

参照

D3DXCreateTextureFromFile、テクスチャの色変換