IDirect3D9

IDirect3D9 (d3d9.h) インターフェイス。アプリケーションは IDirect3D9 インターフェイスのメソッドを使用して、Microsoft Direct3D オブジェクトを作成し、環境をセットアップします。

IDirect3D9 インターフェイスは、Direct3DCreate9 関数を呼び出すことで取得します。

LPDIRECT3D9 型および PDIRECT3D9 型は、IDirect3D9 インターフェイスへのポインターとして定義されています。

typedef struct IDirect3D9 *LPDIRECT3D9, *PDIRECT3D9;

IDirect3D9::RegisterSoftwareDevice メソッド (d3d9.h) は、プラグイン可能なソフトウェアデバイスを登録します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。失敗した場合、戻り値は次のいずれかになります: D3DERR_INVALIDCALL (メソッド呼び出しが無効です。たとえば、メソッドのパラメーターに無効な値が指定されている場合など)、D3DERR_OUTOFVIDEOMEMORY。

ユーザーのコンピューターが 3D 処理に対する特別なハードウェアアクセラレーションを備えていない場合、アプリケーションはソフトウェアで 3D ハードウェアをエミュレートできます。ソフトウェアラスタライズデバイスは、カラー 3D ハードウェアの機能をソフトウェアでエミュレートします。ソフトウェアデバイスは hal よりも動作が低速です。ただし、ソフトウェアデバイスは CPU がサポートする特殊命令を活用して性能を高めます。命令セットには、一部の AMD プロセッサがサポートする AMD 3DNow! 命令セットや、多くの Intel プロセッサがサポートする MMX 命令セットがあります。Direct3D は、変換とライティングの処理を高速化するために 3D-Now! 命令セットを、ラスタライズを高速化するために MMX 命令セットを使用します。

ソフトウェアデバイスは、ハードウェアデバイスドライバーインターフェイス (DDI) に類似したインターフェイスを介して Direct3D と通信します。

ソフトウェアデバイスはアプリケーションによって読み込まれ、IDirect3D9 オブジェクトに登録されます。Direct3D はレンダリングにそのソフトウェアデバイスを使用します。

プラグイン可能なソフトウェアデバイスを開発するためのドキュメントとヘッダーは、Direct3D ドライバー開発キット (DDK) で提供されています。

IDirect3D9::GetAdapterCount メソッド (d3d9.h) は、システム上のアダプター数を返します。

型: UINT

この IDirect3D9 インターフェイスがインスタンス化された時点でシステムに存在するアダプター数を示す UINT 値。

IDirect3D9::GetAdapterIdentifier メソッド (d3d9.h) は、IDirect3D9 インターフェイスがインスタンス化された時点でシステムに存在する物理ディスプレイアダプターの情報を取得します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。Adapter が範囲外の場合、Flags に認識できないパラメーターが含まれる場合、または pIdentifier が NULL か書き込み不可能なメモリを指している場合は、D3DERR_INVALIDCALL が返されます。

IDirect3D9::GetAdapterModeCount メソッド (d3d9.h) は、このアダプターで利用可能なディスプレイモードの数を返します。

型: UINT

このメソッドは、このアダプターのディスプレイモード数を返します。Adapter がシステム上のアダプター数以上の場合はゼロを返します。

IDirect3D9::EnumAdapterModes メソッド (d3d9.h) は、指定したアダプターが要求されたフォーマットとディスプレイモードをサポートするかどうかをデバイスに問い合わせます。

型: HRESULT

• このアダプターでデバイスを使用できる場合は D3D_OK が返されます。
• Adapter がシステム内のディスプレイアダプター数以上の場合は D3DERR_INVALIDCALL が返されます。
• いずれかのサーフェスフォーマットがサポートされていない場合、または指定されたフォーマットに対してハードウェアアクセラレーションが利用できない場合は D3DERR_NOTAVAILABLE が返されます。

アプリケーションがディスプレイモードとフォーマットを EnumAdapterModes に渡すと、ディスプレイモードが返されます。このメソッドをループ内で使用すれば、利用可能なすべてのディスプレイモードを列挙できます。

アプリケーションがフォーマットを指定すると、列挙はそのフォーマットに厳密に一致するディスプレイモードに限定されます (アルファは無視されます)。許可されるフォーマット (D3DFORMAT のメンバー) は次のとおりです。

• D3DFMT_A1R5G5B5
• D3DFMT_A2R10G10B10
• D3DFMT_A8R8G8B8
• D3DFMT_R5G6B5
• D3DFMT_X1R5G5B5
• D3DFMT_X8R8G8B8

さらに EnumAdapterModes は、ピクセルフォーマット 565 と 555 を等価として扱い、正しいバージョンを返します。この違いが意味を持つのは、アプリケーションがバックバッファーをロックする場合のみであり、そのためにアプリケーションが明示的に設定しなければならないフラグがあります。

IDirect3D9::GetAdapterDisplayMode メソッド (d3d9.h) は、アダプターの現在のディスプレイモードを取得します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。

Adapter が範囲外の場合、または pMode が無効な場合、このメソッドは D3DERR_INVALIDCALL を返します。

ディスプレイが 2:10:10:10 のような拡張フォーマットになっている場合、GetAdapterDisplayMode は正しいフォーマットを返しません。代わりに X8R8G8B8 フォーマットを返します。

IDirect3D9::CheckDeviceType メソッド (d3d9.h) は、ハードウェアアクセラレーション対応のデバイスタイプをこのアダプターで使用できるかどうかを確認します。

型: HRESULT

このアダプターでデバイスを使用できる場合は D3D_OK が返されます。

Adapter がシステム内のディスプレイアダプター数以上の場合は D3DERR_INVALIDCALL が返されます。また、CheckDeviceType に存在しないデバイスが指定された場合も D3DERR_INVALIDCALL が返されます。

要求されたバックバッファーフォーマットがサポートされていない場合、または指定されたフォーマットに対してハードウェアアクセラレーションが利用できない場合は D3DERR_NOTAVAILABLE が返されます。

hal デバイスタイプにはハードウェアアクセラレーションが必要です。アプリケーションは CheckDeviceType を使用して、hal デバイスをサポートするために必要なハードウェアとドライバーが存在するかどうかを判定できます。

フルスクリーンのアプリケーションでは、アルファチャネルを含む DisplayFormat を指定してはいけません。指定すると呼び出しが失敗します。バックバッファーにアルファチャネルが存在するのは問題ありませんが、2 つのディスプレイフォーマットはそれ以外のすべての点で同一である必要があります。たとえば DisplayFormat = D3DFMT_X1R5G5B5 の場合、BackBufferFormat の有効な値には D3DFMT_X1R5G5B5 と D3DFMT_A1R5G5B5 が含まれますが、D3DFMT_R5G6B5 は含まれません。

次のコード断片は、あるデバイスタイプをこのアダプターで使用できるかどうかを CheckDeviceType でテストする方法を示しています。

if(SUCCEEDED(pD3Device->CheckDeviceType(D3DADAPTER_DEFAULT, 
                                        D3DDEVTYPE_HAL, 
                                        DisplayFormat, 
                                        BackBufferFormat, 
                                        bIsWindowed)))
    
     return S_OK;
// There is no HAL on this adapter using this render-target format. 
// Try again, using another format.

このコードは、指定したサーフェスフォーマットで既定のアダプター上においてデバイスを使用できる場合に S_OK を返します。

CheckDeviceType を使用して、ディスプレイフォーマットと異なるバックバッファーとの互換性をテストすると、適切な値が返されます。つまり、呼び出しの結果はデバイスの能力を反映します。デバイスが要求されたバックバッファーフォーマットへレンダリングできない場合、呼び出しは D3DERR_NOTAVAILABLE を返します。デバイスがそのフォーマットへレンダリングできても、色変換を伴うプレゼンテーションを実行できない場合も、戻り値は D3DERR_NOTAVAILABLE になります。プレゼンテーション自体のハードウェアサポートは、CheckDeviceFormatConversion を呼び出すことで確認できます。色変換を伴うプレゼンテーション自体のソフトウェアエミュレーションは提供されません。

IDirect3D9::CheckDeviceFormat メソッド (d3d9helper.h) は、あるサーフェスフォーマットが指定したリソースタイプとして利用可能かどうかを判定します。

型: HRESULT

要求された用途において、指定したデバイスとフォーマットに互換性がある場合、このメソッドは D3D_OK を返します。

Adapter がシステム内のディスプレイアダプター数以上の場合、または DeviceType がサポートされていない場合は D3DERR_INVALIDCALL が返されます。

この用途においてデバイスがそのフォーマットを受け付けない場合は D3DERR_NOTAVAILABLE が返されます。

CheckDeviceFormat を使用してハードウェアサポートを確認する例をいくつか示します。

• オフスクリーンプレーンサーフェスのフォーマット - Usage = 0、RType = D3DRTYPE_SURFACE を指定します。
• 深度ステンシルフォーマット - 次のコード断片は、渡された深度ステンシルフォーマットをテストします。

  
  BOOL IsDepthFormatExisting( D3DFORMAT DepthFormat, D3DFORMAT AdapterFormat ) 
  {
      HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                            D3DDEVTYPE_HAL,
                                            AdapterFormat,
                                            D3DUSAGE_DEPTHSTENCIL,
                                            D3DRTYPE_SURFACE,
                                            DepthFormat);
      
      return SUCCEEDED( hr );
  }
  

  列挙処理の詳細については、デバイスの選択 (Direct3D 9) を参照してください。

• 特定のフォーマットでテクスチャをレンダリングできるか - 現在のディスプレイモードにおいて、テクスチャフォーマットが特定のバックバッファーフォーマットと互換性があることを確認する例を示します。

  
  BOOL IsTextureFormatOk( D3DFORMAT TextureFormat, D3DFORMAT AdapterFormat ) 
  {
      HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                            D3DDEVTYPE_HAL,
                                            AdapterFormat,
                                            0,
                                            D3DRTYPE_TEXTURE,
                                            TextureFormat);
      
      return SUCCEEDED( hr );
  }
  

• ピクセルシェーダーでのアルファブレンディング - Usage に D3DUSAGE_QUERY_POSTPIXELSHADER_BLENDING を設定します。浮動小数点のレンダーターゲットではすべて失敗すると考えてください。
• ミップマップの自動生成 - Usage に D3DUSAGE_AUTOGENMIPMAP を設定します。ミップマップの自動生成が失敗した場合、アプリケーションはミップマップのないテクスチャを取得します。このメソッドの呼び出しはヒントとして扱われるため、失敗するのがミップマップ生成のみであれば、このメソッドは D3DOK_NOAUTOGEN (有効な成功コード) を返すことがあります。ミップマップ生成の詳細については、ミップマップの自動生成 (Direct3D 9) を参照してください。

Direct3D 9 から Direct3D 10 へコードを移行する場合、CheckDeviceFormat に相当する Direct3D 10 の機能は CheckFormatSupport です。

IDirect3D9::CheckDeviceMultiSampleType メソッド (d3d9.h) は、あるマルチサンプリング手法がこのデバイスで利用可能かどうかを判定します。

型: HRESULT

デバイスが指定されたマルチサンプリング方式を実行できる場合、このメソッドは D3D_OK を返します。 Adapter または MultiSampleType パラメーターが無効な場合は D3DERR_INVALIDCALL が返されます。問い合わせたマルチサンプリング手法がこのデバイスでサポートされていない場合は D3DERR_NOTAVAILABLE を返します。DeviceType がこのアダプターに適用できない場合は D3DERR_INVALIDDEVICE が返されます。

レンダーターゲットサーフェスと深度ステンシルサーフェスを組み合わせて使用する場合は両方をマルチサンプル対応で作成する必要があるため、このメソッドはその両方に対して使用することを想定しています。

次のコード断片は、特定のマルチサンプリング方式をサポートするデバイスを CheckDeviceMultiSampleType でテストする方法を示しています。

if( SUCCEEDED(pD3D->CheckDeviceMultiSampleType( pCaps->AdapterOrdinal, 
                                pCaps->DeviceType, BackBufferFormat, 
                                FALSE, D3DMULTISAMPLE_3_SAMPLES, NULL ) ) &&
         SUCCEEDED(pD3D->CheckDeviceMultiSampleType( pCaps->AdapterOrdinal, 
                                pCaps->DeviceType, DepthBufferFormat, 
                                FALSE, D3DMULTISAMPLE_3_SAMPLES, NULL ) ) )
    return S_OK;

上記のコードは、指定したサーフェスフォーマットでフルスクリーンの D3DMULTISAMPLE_3_SAMPLES マルチサンプリング方式をデバイスがサポートしている場合に S_OK を返します。

マルチサンプルタイプと品質レベルの取り扱いや設定に関する追加情報については、D3DMULTISAMPLE_TYPE の解説を参照してください。

IDirect3D9::CheckDepthStencilMatch メソッド (d3d9helper.h) は、特定のディスプレイモードにおいて、深度ステンシルフォーマットがレンダーターゲットフォーマットと互換性があるかどうかを判定します。

型: HRESULT

そのディスプレイモードにおいて深度ステンシルフォーマットがレンダーターゲットフォーマットと互換性がある場合、このメソッドは D3D_OK を返します。1 つ以上のパラメーターが無効な場合は D3DERR_INVALIDCALL が返されることがあります。そのディスプレイモードにおいて深度ステンシルフォーマットがレンダーターゲットと互換性がない場合、このメソッドは D3DERR_NOTAVAILABLE を返します。

このメソッドは、特定の深度フォーマットが特定のレンダーターゲットフォーマットとのみ組み合わせて動作するようなハードウェアに、アプリケーションが対応できるようにするために提供されています。

このメソッドの動作は DirectX 8.1 で変更されました。現在は D24x8 および D32 の深度ステンシルフォーマットも考慮されます。以前のバージョンでは、これらのフォーマットは 32 ビットまたは 16 ビットのレンダーターゲットと常に併用できるものと想定していました。現在は、デバイスが混在深度の処理に対応している場合にのみ、これらのフォーマットに対して D3D_OK を返します。

次のコード断片は、CheckDeviceFormat を使用して深度ステンシルフォーマットを検証する方法を示しています。

BOOL IsDepthFormatOk(D3DFORMAT DepthFormat, 
                          D3DFORMAT AdapterFormat, 
                          D3DFORMAT BackBufferFormat)
{
    
    // Verify that the depth format exists
    HRESULT hr = pD3D->CheckDeviceFormat(D3DADAPTER_DEFAULT,
                                         D3DDEVTYPE_HAL,
                                         AdapterFormat,
                                         D3DUSAGE_DEPTHSTENCIL,
                                         D3DRTYPE_SURFACE,
                                         DepthFormat);
    
    if(FAILED(hr)) return FALSE;
    
    // Verify that the depth format is compatible
    hr = pD3D->CheckDepthStencilMatch(D3DADAPTER_DEFAULT,
                                      D3DDEVTYPE_HAL,
                                      AdapterFormat,
                                      BackBufferFormat,
                                      DepthFormat);
    
    return SUCCEEDED(hr);
    
}

上記の呼び出しは、DepthFormat を AdapterFormat および BackBufferFormat と組み合わせて使用できない場合に FALSE を返します。

IDirect3D9::CheckDeviceFormatConversion メソッド (d3d9helper.h) は、あるディスプレイフォーマットから別のディスプレイフォーマットへの変換をデバイスがサポートしているかどうかをテストします。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。失敗した場合、戻り値は D3DERR_INVALIDCALL です。 2 つのフォーマット間の変換をハードウェアがサポートしていない場合、このメソッドは D3DERR_NOTAVAILABLE を返します。

CheckDeviceType を使用して、ディスプレイフォーマットと異なるバックバッファーとの互換性をテストすると、適切な値が返されます。つまり、呼び出しの結果はデバイスの能力を反映します。デバイスが要求されたバックバッファーフォーマットへレンダリングできない場合、呼び出しは D3DERR_NOTAVAILABLE を返します。デバイスがそのフォーマットへレンダリングできても、色変換を伴うプレゼンテーションを実行できない場合も、戻り値は D3DERR_NOTAVAILABLE になります。プレゼンテーション自体のハードウェアサポートは、CheckDeviceFormatConversion を呼び出すことで確認できます。色変換を伴うプレゼンテーション自体のソフトウェアエミュレーションは提供されません。

CheckDeviceFormatConversion は、StretchRect の呼び出しで許可される、変換元サーフェスフォーマットと変換先サーフェスフォーマットの組み合わせを判定するためにも使用できます。

色変換は、次の変換元および変換先フォーマットに限定されます。

• 変換元フォーマットは、FOURCC フォーマットまたは有効なバックバッファーフォーマットである必要があります。一覧については、FourCC フォーマット、およびバックバッファーまたはディスプレイフォーマットを参照してください。
• 変換先フォーマットは、次の符号なしフォーマットのいずれかである必要があります。

  D3DFMT_X1R5G5B5	D3DFMT_A1R5G5B5	D3DFMT_R5G6B5
  D3DFMT_R8G8B8	D3DFMT_X8R8G8B8	D3DFMT_A8R8G8B8
  D3DFMT_A2R10G10B10	D3DFMT_A16B16G16R16	D3DFMT_A2B10G10R10
  D3DFMT_A8B8G8R8	D3DFMT_X8B8G8R8	D3DFMT_A16B16G16R16F
  D3DFMT_A32B32G32R32F

IDirect3D9::GetDeviceCaps メソッド (d3d9.h) は、デバイス固有の情報を取得します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。失敗した場合、戻り値は次のいずれかになります: D3DERR_INVALIDCALL、D3DERR_INVALIDDEVICE、D3DERR_OUTOFVIDEOMEMORY、D3DERR_NOTAVAILABLE。

アプリケーションは、頂点処理能力が Direct3D デバイスオブジェクト間で一貫して保たれると想定してはいけません。物理デバイスが公開する具体的な能力は、CreateDevice に渡すパラメーターに依存する場合があります。たとえば、ハードウェア頂点処理を有効にして Direct3D デバイスオブジェクトを作成する前と後とで、頂点処理能力が異なることがあります。詳細については D3DCAPS9 の説明を参照してください。

IDirect3D9::GetAdapterMonitor メソッド (d3d9.h) は、Direct3D オブジェクトに関連付けられたモニターのハンドルを返します。

型: HMONITOR

Direct3D オブジェクトに関連付けられたモニターのハンドル。

次のコード断片は、指定したデバイスに関連付けられたモニターのハンドルを取得する方法を示しています。GetDirect3D を使用してデバイスから Direct3D 列挙子を取得し、GetCreationParameters を使用して Adapter の値を取得します。

    if( FAILED( pDevice->GetCreationParameters(  &Parameters ) ) )
        return D3DERR_INVALIDCALL;
    
    if( FAILED( pDevice->GetDirect3D(&pD3D) ) )
        return D3DERR_INVALIDCALL;
    
    hMonitor = pD3D->GetAdapterMonitor(Parameters.AdapterOrdinal);
    
    pD3D->Release();

IDirect3D9::CreateDevice メソッド (d3d9.h) は、ディスプレイアダプターを表すデバイスを作成します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。失敗した場合、戻り値は次のいずれかになります: D3DERR_DEVICELOST、D3DERR_INVALIDCALL、D3DERR_NOTAVAILABLE、D3DERR_OUTOFVIDEOMEMORY。

このメソッドは、必要なディスプレイモード (またはウィンドウモード) に設定され、適切なバックバッファーが割り当てられた、完全に動作するデバイスインターフェイスを返します。レンダリングを開始するには、アプリケーションは深度バッファーを作成して設定するだけで済みます (D3DPRESENT_PARAMETERS の EnableAutoDepthStencil が FALSE の場合)。

Direct3D デバイスを作成するときは、フォーカスウィンドウ (hFocusWindow) とデバイスウィンドウ (D3DPRESENT_PARAMETERS の hDeviceWindow) という 2 つの異なるウィンドウパラメーターを指定します。それぞれの目的は次のとおりです。

• フォーカスウィンドウは、アプリケーションが (Alt-Tab、マウスクリック、その他の方法によって) フォアグラウンドモードからバックグラウンドモードへ切り替わったことを Direct3D に通知します。フォーカスウィンドウは 1 つであり、アプリケーションが作成する各デバイスで共有されます。
• デバイスウィンドウは、画面上のバックバッファーの位置とサイズを決定します。これは、Present の際にバックバッファーの内容がフロントバッファーへコピーされるときに Direct3D が使用します。

このメソッドを WM_CREATE の処理中に実行してはいけません。アプリケーションは WM_CREATE の処理中に Direct3D へウィンドウハンドルを渡してはいけません。

デバイスの作成、解放、リセットの呼び出しは、いずれもフォーカスウィンドウのウィンドウプロシージャと同じスレッドから行う必要があります。

なお、D3DCREATE_HARDWARE_VERTEXPROCESSING、D3DCREATE_MIXED_VERTEXPROCESSING、D3DCREATE_SOFTWARE_VERTEXPROCESSING は相互排他的なフラグであり、このメソッドを呼び出す際にはこれらの頂点処理フラグの少なくとも 1 つを指定する必要があります。

デバイスの一部として作成されるバックバッファーは、プレゼンテーションパラメーターで D3DPRESENTFLAG_LOCKABLE_BACKBUFFER が指定されている場合にのみロック可能です (マルチサンプリングされたバックバッファーおよび深度サーフェスは決してロックできません)。

Reset、IUnknown、TestCooperativeLevel の各メソッドは、このメソッドでデバイスを作成したスレッドと同じスレッドから呼び出す必要があります。

CreateDevice、Reset、CreateAdditionalSwapChain を呼び出す際、ウィンドウモードのバックバッファーフォーマットには D3DFMT_UNKNOWN を指定できます。これにより、ウィンドウモードで CreateDevice を呼び出す前に、アプリケーションが現在のデスクトップフォーマットを問い合わせる必要がなくなります。フルスクリーンモードでは、バックバッファーフォーマットを指定する必要があります。

サイズが 0x0 のウィンドウでデバイスを作成しようとすると、CreateDevice は失敗します。

#define global IID_IDirect3D9 "{81BDCBCA-64D4-426D-AE8D-AD0147F4275C}"
#usecom global IDirect3D9 IID_IDirect3D9 "{}"
#comfunc global IDirect3D9_RegisterSoftwareDevice       3 sptr
#comfunc global IDirect3D9_GetAdapterCount              4
#comfunc global IDirect3D9_GetAdapterIdentifier         5 int,int,var
#comfunc global IDirect3D9_GetAdapterModeCount          6 int,int
#comfunc global IDirect3D9_EnumAdapterModes             7 int,int,int,var
#comfunc global IDirect3D9_GetAdapterDisplayMode        8 int,var
#comfunc global IDirect3D9_CheckDeviceType              9 int,int,int,int,int
#comfunc global IDirect3D9_CheckDeviceFormat            10 int,int,int,int,int,int
#comfunc global IDirect3D9_CheckDeviceMultiSampleType   11 int,int,int,int,int,var
#comfunc global IDirect3D9_CheckDepthStencilMatch       12 int,int,int,int,int
#comfunc global IDirect3D9_CheckDeviceFormatConversion  13 int,int,int,int
#comfunc global IDirect3D9_GetDeviceCaps                14 int,int,var
#comfunc global IDirect3D9_GetAdapterMonitor            15 int
#comfunc global IDirect3D9_CreateDevice                 16 int,int,sptr,int,var,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。