DirectXの目的

Microsoft DirectX� Software Development Kit (SDK)は、ハイパフォーマンスでリアルタイムなアプリケーションを設計するために必要なリソースを提供すべく、精巧なチューニングを行ったアプリケーションプログラミング・インターフェイス(API)セットである。DirectXテクノロジーは、次世代のコンピュータゲームやマルチメディアアプリケーション開発に役立つだろう。

Microsoftは、Microsoft Windowsオペレーティングシステムで動作するアプリケーションのパフォーマンスを、MS-DOSやアーケードゲーム機で動作するアプリケーションのパフォーマンス以上のものにしようとDirectXを開発した。頑強で、標準化され、適切に文書化された、ゲームを書くためのオペレーティング環境を提供することにより、Windowsでのゲーム開発を促進するために、このSDKは開発されたのである。

この章では、DirectXを使用するふたつの重要な利点を説明する。ソフトウェア開発者のためのハードウェア非依存性の提供と、ハードウェア開発者のためのガイドラインの設定である。

DirectX Windowsアプリケーション開発の利点

ハードウェア開発のためのガイドラインの提供


DirectX Windowsアプリケーション開発の利点

DirectXの第一の目的は、今日MS-DOSで使用されている機能への互換性のあるアクセスを提供し、MS-DOSコンソールベースのアプリケーション並みあるいはそれ以上のパフォーマンスを出させ、そしてパーソナルコンピュータにおけるハードウェア技術革新の障害を取り除くことである。

Microsoftは、Windowsベースのアプリケーションに、現在そして将来のコンピュータシステム上で利用可能なハードウェアへのハイパフォーマンスでリアルタイムなアクセスを提供するためDirectXを開発した。DirectXは、インストールやコンフィギュレーションの煩雑さを減らし、ハードウェアの長所を最大限活かしながら、ハードウェアとアプリケーションとの間に一貫したインターフェイスを提供している。

ハイパフォーマンスなWindowsベースのゲームは、以下のテクノロジーを利用している。

パフォーマンス向上のため特別設計されたアクセラレータカード

プラグアンドプレイと、他のWindowsハードウェアやソフトウェア

DirectPlayを含む、Windowsビルトインの通信サービス


ハードウェア開発のためのガイドラインの提供

MicrosoftがDirectXを開発したときの第一の目的のひとつは、Windowsオペレーティング環境でのゲーム開発の促進だった。DirectX以前は、パーソナルコンピュータ用に開発されたゲームの主流はMS-DOSベースだった。それらのゲームの開発者は、さまざまなカードの数多いハードウェア実装に従わなければならなかった。しかしDirectXでは、ゲーム開発者は、ハードウェアへのダイレクトアクセスの利点を失うことなく、デバイス非依存性という利点が得られるのである。

もうひとつの重要な目的は、ハードウェア会社に対し、ハイパフォーマンスなアプリケーションの開発者やハードウェアベンダー(IHV)からのフィードバックに基づいたガイドラインを提供することである。DirectX SDKコンポーネントは、結果としてまだ存在しないハードウェアクセラレータ機能の仕様を提供することになるかもしれない。多くの場合では、ソフトウェアがそれらの機能をエミュレートする。それ以外では、ソフトウェアはハードウェアに対しその能力について問い合わせ、もしサポートされていなければ無視するということになる。

近々使用可能になるであろうディスプレイハードウェア機能は、以下を含んでいる。

オーバーレイ。ページ・フリッピングをグラフィックデバイスインターフェイス(GDI)ウィンドウ内で可能にするためにサポートされるだろう。ページ・フリッピングは、スクリーン全体にあるフレームを表示するため使用されるダブルバッファ・スキームである。

スプライトエンジン。スプライトをオーバーレイさせることを容易にする。

補間による伸長。小さいフレームでもスクリーン全体にフィットするように拡大するため、ディスプレイメモリを効率的に節約する。

アルファ・ブレンディング。ハードウェアピクセルのレベルで色を混合する。

パースが正確なテクスチャを持つ3次元(3D)アクセラレータ。3Dの面にテクスチャを表示できる。たとえば、3Dソフトウェアで生成した城の玄関に、パースを正確に保ったまま煉瓦壁ビットマップのテクスチャを貼ることができる。

Zバッファを考慮に入れた3Dグラフィックのブロック転送。

標準2メガバイト(MB)のディスプレイメモリ。一般的に、3Dゲームに最低限必要とされる。

圧縮技法の標準。ディスプレイメモリにより多くのデータを格納できるようにする。この標準は、ソフトウェア、ハードウェア双方に実装されればたいへん高速になるだろう。テクスチャに使用され、透過圧縮を含む。

近々使用可能になるであろうオーディオハードウェア機能は、以下を含んでいる。

異なる音を3D空間に配置するハードウェアとエンハンサ。

オーディオボードのオンボードメモリ。

オンボードメモリを共有する、オーディオ・ビデオ・コンビネーションボード。

加えて、将来のDirectX互換ハードウェアアクセラレータにより、ビデオ再生も恩恵を受けるだろう。将来リリースされるDirectXの一機能として、YUVビデオの展開ハードウェアアクセラレーションがサポートされるだろう。


DirectX SDK

このセクションでは、DirectX SDKといくつかのDirectX実装の詳細を記述する。以下のトピックについて説明する。

DirectX SDKコンポーネント

マクロ定義の使用


DirectX SDKコンポーネント

DirectX SDKは、Windowsベースのゲームやハイパフォーマンスなアプリケーションのパフォーマンスを扱ういくつかのコンポーネントを含んでいる。このセクションでは、それらのコンポーネントを列挙し、説明のある章へのリンクを示す。

DirectDrawｮは、ハードウェアのブロック転送やバッファフリッピング機能への超高速アクセスはもちろん、オフスクリーンディスプレイメモリ中のビットマップへのダイレクトアクセスを提供することにより、ハードウェアとソフトウェアのアニメーション技術を高速化する。このコンポーネントについての詳細情報は、DirectDrawのDirectDrawについて を参照すること。

DirectSoundｮにより、ハードウェア、ソフトウェアでサウンドのミキシングや再生が可能になる。このコンポーネントについての詳細情報は、DirectSoundのDirectSoundについて を参照すること。

DirectPlayｮは、モデムリンクやネットワークを介したゲーム間の接続を容易にする。このコンポーネントについての詳細情報は、DirectPlayのDirectPlayについてを参照すること。

Direct3D�は、アプリケーションが完全な3Dグラフィックシステムを容易に実装できるよう、高レベルのリテインド・モードインターフェイスを提供する。また、アプリケーションがレンダリングパイプラインを完全にコントロールできるよう、低レベルのイミディエート・モードインターフェイスも提供する。このコンポーネントについての詳細情報は、Direct3DのDirect3Dについて を参照すること。

DirectInput�は、将来のWindowsベースのハードウェア入力APIとドライバへスケーラブルな入力機能をゲームに提供する。現在、ジョイスティック、マウス、キーボードがサポートされている。このコンポーネントについての詳細情報は、DirectInputによるジョイスティックのサポート を参照すること。

DirectSetupは、1回の呼び出しでインストールが完了するDirectXプロシージャを提供する。このコンポーネントについての詳細情報は、DirectSetupのDirectSetupについて を参照すること。

AutoPlayは、CD-ROMドライブにコンパクトディスクを挿入すると自動的にインストールプログラムやゲームを開始するWindows 95の機能である。このコンポーネントについての詳細情報は、AutoPlayのAutoPlayについて を参照すること。

AutoPlay機能は、Microsoft Win32ｮ APIの一部であり、DirectX特有のものではない。

DirectX SDKドキュメントの最も重要な部分が、サンプルコードである。生きたサンプルからコードを学ぶことこそ、DirectXを理解するための最もよいやり方のひとつなのだ。サンプルアプリケーションは、SDKのSdk\Samplesフォルダの中にある。


マクロ定義の使用

DirectXインターフェイスのヘッダファイルの多くは、各メソッドのマクロ定義を含んでいる。これらのマクロにより、プログラミングでメソッドを使用するのが容易になる。

以下の例では、 IDirectDraw2::CreateSurfaceメソッドを呼ぶためIDirectDraw2_CreateSurfaceマクロを使用している。最初のパラメータは、DirectDrawオブジェクトへの参照である。

ret = IDirectDraw2_CreateSurface (lpDD, &ddsd, &lpDDS,

    NULL);

マクロ定義がサポートするメソッドの現在のリストを得るには、使用したいDirectXコンポーネントの適切なヘッダファイルを参照すること。


DirectXとコンポーネント・オブジェクト・モデル

このセクションでは、コンポーネント・オブジェクト・モデル(COM)と、COMのオブジェクトおよびインターフェイスの実装について記述する。説明するトピックは以下の通りである。

コンポーネント・オブジェクト・モデル

IUnknownインターフェイス

DirectX COMインターフェイス

C++とCOMのインターフェイス

CでのCOMオブジェクトへのアクセス

インターフェイスメソッド名とシンタックス


コンポーネント・オブジェクト・モデル

DirectX SDKの大部分のAPIは、COMに基づくオブジェクトおよびインターフェイスから構成される。COMは、インターフェイスの再利用に焦点を当てたオブジェクトベースシステムのための土台であり、OLEプログラミングの核心にあるモデルである。また、インターフェイスをいくつでも構築できるようなインターフェイス仕様でもある。COMは、OSレベルでのオブジェクトモデルなのである。

多くのDirectX APIは、OLEオブジェクトの集合としてインスタンス化できる。オブジェクトは、ハードウェアを表しインターフェイスを通してアプリケーションと通信する必要のあるブラックボックスと考えることができる。COMインターフェイスを通してオブジェクト間で受け渡しされるコマンドはメソッドと言われる。たとえば、ディスプレイアダプタの現在のディスプレイモードを取得するため、 DirectDrawオブジェクトからIDirectDraw2::GetDisplayModeメソッドがIDirectDraw2インターフェイスを通して送られる。

オブジェクトは、実行時に他のオブジェクトとバインドでき、他のオブジェクトが提供するインターフェイスを実装して使用できる。オブジェクトがOLEオブジェクトであり、そしてそのオブジェクトがサポートするインターフェイスがわかれば、アプリケーション(または他のオブジェクト) は、最初のオブジェクトが実行できるサービスを決定することが可能である。 QueryInterfaceメソッドは、OLEオブジェクトすべてが継承するメソッドのひとつだが、これにより、あるオブジェクトがサポートするインターフェイスを決定できる。それらのインターフェイスへのポインタはこのメソッドで作成する。詳細情報は、IUnknownインターフェイスを参照すること。


IUnknownインターフェイス

COMインターフェイスはすべて、IUnknownと呼ばれるインターフェイスから導出される。このインターフェイスは、オブジェクトの寿命の制御や多重インターフェイスを操作する機能をDirectXに提供する。IUnknownは、３つのメソッドを持つ。

AddRefは、インターフェイス、または他のアプリケーションがそれ自身をオブジェクトとバインドしたとき、オブジェクトの参照カウントをインクリメントする。

QueryInterfaceは、指定したインターフェイスへのポインタを要求することにより、オブジェクトがサポートする機能について照会する。

Releaseは、オブジェクトの参照カウントをデクリメントする。カウントが0になったとき、オブジェクトは解放される。

AddRefとReleaseは参照カウントをメンテナンスする。たとえばDirectDrawSurfaceオブジェクトを作成すると、オブジェクトの参照カウントは1に設定される。関数がオブジェクトのインターフェイスにポインタを返すたび、参照カウントをインクリメントする。その関数は返したポインタを通してAddRefを呼び出さなければならない。またAddRefの各呼び出しにはReleaseの呼び出しを対応させなくてはならない。ポインタを破棄される前に、そのポインタを通してReleaseを呼ばなければならないのである。オブジェクトの参照カウントが0になると、オブジェクトは破棄され、すべてのインターフェイスは無効となる。

QueryInterfaceは、オブジェクトが指定されたインターフェイスをサポートするかどうか決定する。オブジェクトがインターフェイスをサポートしている場合、QueryInterfaceは、そのインターフェイスへのポインタを返す。するとオブジェクトと通信するためにインターフェイスを持つメソッドが使用できる。インターフェイスへのポインタを返すのに成功すると、QueryInterfaceは、参照カウントをインクリメントするべく暗にAddRefを呼ぶ。そのためアプリケーションは、インターフェイスへのポインタ破棄する前に、参照カウントをデクリメントするべくReleaseを呼ばなければならない。


IUnknown::AddRef

ULONG AddRef();

オブジェクトの参照カウントをインクリメントする。

新しい参照カウントを返す。

オブジェクトが作成されると、参照カウントは1に設定される。アプリケーションがオブジェクトへのインターフェイスを取得するか、AddRefメソッドを呼び出すたびに、オブジェクトの参照カウントはインクリメントされる。オブジェクトの参照カウントをデクリメントするにはRelease メソッドを使用すること。

このメソッドは、オブジェクトによって継承されるIUnknown インターフェイスの1部である。


IUnknown::QueryInterface

HRESULT QueryInterface(REFIID riid, LPVOID* obp);

オブジェクトが特定のCOMインターフェイスをサポートしているかどうか決定する。サポートしている場合、システムはオブジェクトの参照カウントを増やし、アプリケーションはただちにそのインターフェイスを使用できる。

呼び出しが成功した場合、S_OKを返す。呼び出しが失敗した場合、メソッドは、E_NOINTERFACEまたは以下のインターフェイス固有のエラー値のひとつを返す。インターフェイス固有のエラー値は、コンポーネント単位でリストされる。

DirectDraw

	DDERR_INVALIDOBJECT
	DDERR_INVALIDPARAMS
	DDERR_OUTOFMEMORY (IDirectDrawSurface2のみ)

DirectSound

	DSERR_GENERIC (IDirectSoundとIDirectSoundBufferのみ)
	DSERR_INVALIDPARAM

DirectPlay

	DPERR_INVALIDOBJECT
	DPERR_INVALIDPARAMS
Direct3Dのリテインド・モードとイミディエート・モードのインターフェイスについては、QueryInterfaceメソッドは、Direct3D保持モードの返値とDirect3D直接モードの返値のどちらかひとつを返す。

riid

要求されたインターフェイスの参照識別子。

obp

照会が成功した場合、インターフェイスポインタが返されるポインタのアドレス。

このメソッドを呼ぶことで取得したインターフェイスが不要になった場合、アプリケーションは、インターフェイスを解放するためにReleaseメソッドを呼び出す必要がある。QueryInterfaceメソッドにより、Microsoftとサードパーティは、現存あるいは将来の機能と干渉することなくオブジェクトを拡張できるようになる。

このメソッドは、オブジェクトによって継承されるIUnknownインターフェイスの一部である。


IUnknown::Release

ULONG Release();

オブジェクトの参照カウントをデクリメントする。

新しい参照カウントを返す。

参照カウントが0になったとき、オブジェクトは自分自身を解放する。オブジェクトの参照カウントをインクリメントするには、AddRefメソッドを使用すること。

このメソッドは、オブジェクトによって継承されるIUnknownインターフェイスの一部である。


DirectX COMインターフェイス

DirectX SDKのインターフェイスは、COMプログラミング階層の非常に基本的なレベルで作成された。 IDirectDraw2、IDirectSound、IDirectPlayといった、デバイスを表すオブジェクトへのそれぞれのインターフェイスは、 IUnknown OLEインターフェイスから直接導出される。これらの基本オブジェクトの作成は、COMオブジェクト作成に一般に用いられるWin32のCoCreateInstance関数よりはむしろ、各オブジェクトのためダイナミックリンクライブラリ(DLL)中で特化された関数により処理される。

一般には、DirectX SDKのオブジェクトモデルは、各デバイスにひとつの主要なオブジェクトを提供する。他のサポートサービスオブジェクトは、そのオブジェクトから導出されることになる。たとえば、DirectDrawオブジェクトは、ディスプレイアダプタを表している。このオブジェクトを用い、ディスプレイメモリを表すDirectDrawSurfaceオブジェクトを、ハードウェアパレットを表すDirectDrawPaletteオブジェクトを作成することができる。同様に、DirectSoundオブジェクトはオーディオカードを表し、そのカード上の音源を表すDirectSoundBufferオブジェクトを作成する。

下位オブジェクト生成の能力に加え、主要なデバイスオブジェクトは、スクリーンのサイズや色数、オーディオカードがウェーブテーブルシンセサイザーを持つかどうかといった、オブジェクトが表すハードウェアデバイスの能力を決定する。


C++とCOMのインターフェイス

C++プログラマにとって、COMインターフェイスは、抽象基本クラスに似ている。すなわち、シグネチャとセマンティックスを定義するが、実装は定義せず、ステートのデータをインターフェイスに関連づけないのである。C++の抽象基本クラスでは、あらゆるメソッドは、関連するコードを持たないという意味で、純粋仮想として定義される。

純粋仮想C++関数とCOMインターフェイスは、ともにVテーブルと呼ばれるデバイスを用いる。Vテーブルは、与えられたインターフェイスを実装する関数すべてのアドレスを持つ。これらの関数を使用するプログラムやオブジェクトが必要な場合、 QueryInterfaceメソッドを用いて、オブジェクトにそのインターフェイスが存在するかどうか確認し、そのインターフェイスへのポインタを得ることができる。 QueryInterfaceを呼べるのはオブジェクトが実装するインターフェイスメソッドだが、実際にはこのメソッドの送信後、アプリケーションやオブジェクトは、Vテーブルへのポインタをオブジェクトから受け取ることになる。このメカニズムは、オブジェクトが使用するプライベートデータと呼び出し側クライアントプロセスとを切り離す。

COM オブジェクトとC++オブジェクトとの間のもうひとつの類似点は、メソッドの最初の引数がそのインターフェイスまたはクラスの名前であることである。C++ではthis引数と言われるものである。COMオブジェクトとC++オブジェクトは完全にバイナリ互換なため、コンパイラはCOMインターフェイスをC++抽象クラスのように扱い、同じ文法であるものと仮定する。この結果、コードの複雑さが軽減されるのである。たとえば、C++で引数のthisは、すでに解釈されたパラメータとして扱われてコード化されず、Vテーブルを通した不正はC++で暗に処理される。


CでのCOMオブジェクトへのアクセス

どんなCOMインターフェイスメソッドもC言語から呼び出すことができる。C言語からインターフェイスメソッドを呼ぶときに、覚えておくべき事柄がふたつある。

メソッドの最初のパラメータは、つねにメソッドを呼び出す。すでに生成されたオブジェクトを参照する(引数のthis)。

インターフェイスの各メソッドは、オブジェクトのVテーブルへのポインタを通して参照される。

以下の例では、 C言語でIDirectDraw2::CreateSurfaceメソッドを呼び出すことでDirectDrawオブジェクトと関連づけられたサーフェスを作成する。

ret = lpDD->lpVtbl->CreateSurface (lpDD, &ddsd, &lpDDS,

      NULL);

lpDDパラメータは、新しいサーフェスに関連づけられたDirectDrawオブジェクトを参照する。ちなみにこのメソッドは、サーフェス情報構造体(&ddsd)を設定し、新しいサーフェスへのポインタ(&lpDDS)を返す。

IDirectDraw2::CreateSurfaceメソッドを呼び出すには、まずDirectDrawオブジェクトVテーブルへの参照を外し、そしてVテーブルからメソッドへの参照を外す。メソッドで供給される最初のパラメータが、メソッドを起動するために、すでに作成されたDirectDrawオブジェクトへの参照である。

COMオブジェクトメソッドをCとC++で呼び出す違いを説明するため、C++の同じメソッドを次に示す(C++は、lpVtblパラメータへの参照を外し、thisポインタも飛ばしてしまう)。

ret = lpDD->CreateSurface(&ddsd, &lpDDS, NULL)


インターフェイスメソッド名とシンタックス

本ドキュメント中で記述されているCOMインターフェイスメソッドはすべて、C++クラス名によって表されている。この命名規約は、統一性のために用いられ、また、QueryInterface、AddRef、Releaseといった、同じ名前を使用するが異なるDirectXオブジェクトと、メソッドとを区別するため使用される。これはC++でのみ、これらのメソッドを使用できるということではない。

これに加え、メソッドのために提供される文法は、統一性のためC++の命名規約を使用する。これはインターフェイスへのthisポインタを含まない。C言語では、インターフェイスへのポインタは各メソッドに含まれている必要がある。以下の例で、IDirectDraw2::GetCapsメソッドのC++での文法を示す。

HRESULT GetCaps(LPDDCAPS lpDDDriverCaps,

    LPDDCAPS lpDDHELCaps);

同じ例が、Cの文法だとこのようになる。

HRESULT GetCaps(LPDIRECTDRAW lpDD,

    LPDDCAPS lpDDDriverCaps, LPDDCAPS lpDDHELCaps);

lpDDパラメータは、DirectDrawオブジェクトを表すDirectDraw構造体へのポインタである。


DirectX 3 SDKでの新機能とは?

DirectX 3 SDKは、DirectX 2 SDKより多くのサービスや多くの技術革新への手段を提供する。このSDKは追加された関数やサービスを含んでいるが、DirectX 2 SDKやオリジナルのDirectX 1 SDKで書かれたアプリケーションはすべて、ソースを変更せずに再コンパイルし実行できるであろう。

この章での目的は、DirectX 2 SDKをよく知る人へ、このSDKで大きく異なっているいくつかの重要な事項をすばやく理解するための手助けになることである。これらの違いを、コンポーネント単位で一覧にする。

DirectDraw

	APIの変更はない。シンプルなDirectDrawアプリケーションを実装する説明を、ステップごとに提供するチュートリアルをいくつか入れた。チュートリアルについては、DirectDrawのDirectDrawチュートリアルを参照すること。

DirectSound

	DirectX 3は、アプリケーションが音源の聞こえてくる位置を変更できるようにする DirectSound3D機能を含む。アプリケーションは、指向性のある音源の音円錐、移動する音のドップラー効果、そして異なる効果が発生する距離を指定できる。DirectSoundの新機能についての詳細情報は、DirectSoundの章の3Dサウンドを参照すること。

DirectPlay

	DirectPlayは、基礎にあるトランスポート、プロトコル、オンラインサービスによらずアプリケーションが互いに通信できるようにするだけでなく、マッチメーキングサーバへの非依存性も提供する技術の一環となった。この新しい技術を実装するため、IDirectPlay2、 IDirectPlay2A、IDirectPlayLobby インターフェイスが追加された。DirectPlayの新機能についての詳細情報は、DirectPlayバージョン 3で何が新しくなったか?を参照すること。

Direct3D

	APIの変更はない。リテインド・モードのチュートリアルは、更新され簡単になっている。このチュートリアルについては、Direct3Dの Direct3Dの 保持モードのチュートリアルを参照すること。

DirectInput

	DirectInputは新たに、ジョイスティックと同様、マウスとキーボード入力をサポートした。

DirectSetup

	DirectSetupは、アプリケーションをインストール中にレジストリへ正しくエントリを登録できるよう補助する新機能を持った。

AutoPlay

	AutoPlayについてのドキュメントは、新たにWindows NTｮの情報も持った。


表記

以下に本文での表記を説明する。

表記	意味
イタリック体	プレースホルダーまたは変数を表す。実際の値を与えなければならない。たとえば、ステートメント SetCursorPos(X, Y)では、X、Yパラメータに代わる実際の値を与えなければならない。
[]	オプションのパラメータを括る。
|	どちらかあるいは両方の選択肢を分ける。
...	直前の項目の繰り返しを示す。
. . .	サンプルアプリケーションの省略部分を表す。
次の書体はそれぞれ以下の意味を表す。

表記	意味
SMALL CAPITALS	キー、キーシーケンス、キーコンビネーションの名前を表す。たとえば、ALT+SPACEBAR。
FULL CAPITALS	大部分の型や構造体の名前を表す。それらはボールドでも表記される。定数も表す。
monospace	コードサンプルを強調し、シンタックスのスペーシングを示す。


DirectDrawについて

DirectDrawｮ は、ディスプレイ・メモリ、ハードウェア・ブロック転送、オーバーレイ、フリッピングなどの直接操作を可能にするDirectX� SDKコンポーネントである。これらの機能を、 DirectDrawは既存のMicrosoftｮ Windowsｮ ベースのアプリケーションやデバイス・ドライバとの互換性を保ちながら実現する。

DirectDrawは、あくまでWindows グラフィック・デバイス・インターフェイス (GDI)との互換性を保ちながらも、ディスプレイ・デバイスへの直接アクセスを提供するソフトウェア・インターフェイスであり、グラフィックスのための高レベルなアプリケーション・プログラミング・インターフェイス (API)ではない。3Dグラフィックス・パッケージやデジタル・ビデオ・コーデックスを利用したゲームやWindowsサブシステムに対し、デバイスに依存しない特定ディスプレイ・デバイス機能へのアクセスを提供するものである。

DirectDrawは、さまざまなディスプレイ・ハードウェアで動作する。その範囲は、シンプルなSVGAモニターから、クリッピングや伸長、非RGBカラーフォーマットをサポートする最新のハードウェアにまで至る。 DirectDrawのインターフェイスは、基礎にあるハードウェアの能力を認識し、サポートされたすべてのハードウェア・アクセラレーションを使うことができるように設計されている。ハードウェアが実装していない機能は、DirectXがエミュレートするようになっている。

DirectDrawは、従来なら特定のディスプレイ・デバイスに依存したコードを必要とするアプリケーションでしかできなかった以下のような利点を、デバイスに依存しないかたちで提供する。

ダブルバッファとフリッピング・グラフィックスのサポート

ディスプレイ・カードのハードウェア・ブロック転送へのアクセスと制御

3D Zバッファ のサポート

Zオーダリングのハードウェア・オーバーレイのサポート

イメージ伸長ハードウェアへのアクセス

スタンダードおよびエンハンスド双方のディスプレイ・メモリ領域への同時アクセス

DirectDrawの目的は、本来、ディスプレイ・メモリへのデバイスに依存するアクセスを、デバイスに依存しない方法で提供することである。事実上、DirectDrawはディスプレイ・メモリを管理する。アプリケーションは、RGBとYUVカラー・フォーマットやラスタ間ピッチなど、ハードウェア実装に関する標準的な基本的デバイス依存性を認識するだけでよい。ブロック転送やパレット・レジスタの利用に必要な特定のプロシージャ呼び出しについて考慮する必要がないのである。 DirectDrawを使えば、異なるタイプのハードウェアが持つブロック転送や色伸長の機能をフルに引き出しながら、しかもハードウェアの特定部位に依存することなく、 ディスプレイ・メモリを簡単に操作することができる。

Windows 95と Windows NTｮ version 4.0以降が動作するコンピュータ上で広く使えるゲーム・グラフィックスを、 DirectDrawは提供するのである。


DirectDrawアーキテクチャ

DirectDrawは、ディスプレイ・メモリとディスプレイ・ハードウェア管理サービスを提供し、メモリ管理に関連したメモリの割り当て、移動、転送、解放などの一般的機能も提供する。DirectDrawが管理するメモリは画像イメージを表し、サーフェスと呼ばれる。 アプリケーションはDirectDrawのハードウェア・アブストラクション・レイヤ (HAL)を通じ、伸長やオーバーレイ、テクスチャ・マッピング、回転、ミラーリングを含む独特なディスプレイ・ハードウェア機能を利用できる。


DirectDraw概要

この節では、DirectDrawコンポーネントの一般的なことについて説明する。

DirectDraw

その他の DirectDrawの特徴

DirectDraw HAL

DirectDraw HEL

DirectDrawオブジェクトのタイプ

幅とピッチ

3D サーフェスのサポート

DirectDrawとDirect3Dの統合

モードXディスプレイ・モード

ピクセル・フォーマット


DirectDraw

DirectDrawは、ハードウェアとソフトウェア双方で実装される。 DirectDrawを使うアプリケーションは、ハードウェアおよびソフトウェア・エミュレーションの２つの能力を利用することができる。アプリケーションは、 DirectDrawが何をエミュレーションしているか、そしてどの機能がハードウェアで提供されているか、簡単に調査できる。DirectDrawは、 DirectDraw ハードウェア・アブストラクション・レイヤ(HAL)の唯一のクライアントでり、アプリケーションは 必ずDirectDrawに対してアクセスを行わなければならず、それより低レベルなHALに直接アクセスすることはできない。

DirectDraw は、 Ddrawダイナミック・リンク・ライブラリ (DLL)によって実装されている。この32ビットDLLは、 DirectDrawの要求する共通機能すべてを実装している。 このDLLは、パラメータを完全に有効化するのはもちろん、 Win32ｮとHALの16ビット部分との間に必要なサンクをすべて行い、オフスクリーン・ディスプレイ・メモリを管理し、DirectDrawが要求するすべての管理記録やセマンティック・ロジックを担当する。またクリップ・リストとその他すべてのデバイス独立機能を提供するウィンドウ・ハンドルをフックすることで、アプリケーションへのコンポーネント・オブジェクト・モデル（COM）インターフェイスを提供する。

DirectDrawは、IDirectDraw2、 IDirectDrawSurface2、 IDirectDrawPalette、 IDirectDrawClipperという4つのCOMインターフェイスの組み合わせである。COMの概念については、「コンポーネント・オブジェクト・モデル」を参照すること。

DirectDrawアプリケーションが最初に使うふたつのオブジェクトはDirectDrawとDirectDrawSurfaceである。 DirectDrawオブジェクトは、DirectDrawCreate関数を用いて作成され、 ディスプレイ・アダプタ・カードを表す。アプリケーションは、オブジェクトへの IDirectDraw2インターフェイスを取得した後、プライマリDirectDrawSurfaceオブジェクトを作成するため、モニタ描画用のディスプレイ・メモリを表すIDirectDraw2::CreateSurfaceメソッドを呼び出せるようになる。また、プライマリ・サーフェスから連結リスト方式でオフスクリーン・サーフェスを作成することもできる。

通常、プライマリ・サーフェスと表示イメージをフリッピングするため、バック・バッファをひとつ作成する。プライマリ・サーフェスの表示イメージを走査するのにスクリーンがビジーになっている間、バック・バッファ・サーフェス・フレームへ描画する。これはディスプレイ・メモリのDirectDrawSurfaceオブジェクトに格納されている一連のオフスクリーン・ビットマップをバック・バッファに転送することにより実現する。アプリケーションは、直前に描画したフレームを表示するために、IDirectDrawSurface2::Flipメソッドを呼び出す。このメソッドは、スクリーン（モニタ）が垂直方向の再走査を行うときに画面を描き換えるようにレジスタをセットする。 この操作は非同期なため、メソッドを呼んでからもアプリケーションは処理を続けられる（このメソッドが呼ばれると、描き換えられるまで自動的にバック・バッファは書きこみ禁止となる）。プライマリ・サーフェスが描き換えられた後、アプリケーションはバック・バッファに次のフレームを構成しIDirectDrawSurface2::Flipを呼び出すなどの処理を続ける。

Windows 3.1 GDIモデルではディスプレイ・メモリのビットマップへの直接アクセスをするわけではないが、 DirectDrawによりそのパフォーマンスは向上する。実は、GDIのパフォーマンス低下の根本的な要因は、ブロック転送をまずシステム・メモリ上で実行し、その結果をディスプレイ・メモリへ転送する、という二重のオーバーヘッドにある。しかし、 DirectDrawを利用する場合、可能なかぎりディスプレイ・アダプタ・カード上で処理を行うため、そのオーバーヘッドを圧縮できるのである。またWindows 95やWindows NT GDIモデルではCreateDIBSection関数がハードウェア処理を可能にするが、DirectDrawはそのパフォーマンスも向上させる。

第三の DirectDrawオブジェクトは DirectDrawPaletteである。物理ディスプレイ・パレットは通常ディスプレイ・ハードウェア内に持たれるため、ひとつのオブジェクトによりそれを表し操作することになる。  IDirectDrawPaletteインターフェイスは、パレットをハードウェア上で実装する。これらによりWindowsパレットはバイパスされ、ゲームがディスプレイ・ハードウェアを排他的にアクセスするときだけ使われる。 DirectDrawPaletteオブジェクトもまた、DirectDrawオブジェクトから作成される。

最後の DirectDrawオブジェクトはDirectDrawClipperである。 DirectDrawはこのオブジェクトを使って、ディスプレイ・メモリのクリッピングされた領域を管理する。


その他のDirectDrawの特徴

DirectDraw節で示した特徴に加え、DirectDrawは透過型ブロック転送とオーバーレイもサポートしている。

透過型ブロック転送中は、ビットマップはサーフェスに転送され、ビットマップ中のある色または色領域は透過として定義される。透過型ブロック転送は、カラー・キーを使って実現される。 転送元カラー・キーは、転送処理中、ビットマップのどの色、どの色領域を透過にするか、つまりコピーしないのかを定義することにより行われる。転送先カラー・キーは、転送元ビットマップのその色、色領域を持つピクセルによって、サーフェスのどの色、どの色域が上書きされるかを定義することにより行われる。詳細は「カラー・キーイング」を参照すること。

最後に、 DirectDrawはハードウェアのオーバーレイとソフトウェア・エミュレーションによるオーバーレイの両方をサポートする。オーバーレイは、スプライトの実装やアニメーションの複数レイヤ管理の、より簡単な手段である。オーバーレイだけに関連した追加能力に加え、その他どんなサーフェスの能力もすべて持つオーバーレイとして、あらゆるDirectDrawSurfaceオブジェクトを作成できる。これらの機能は追加のディスプレイ・メモリを必要とし、ディスプレイ・メモリにオーバーレイ機能がなければ、システム・メモリ上にオーバーレイ・メモリを置くこともできる。

カラー・キーは、 オーバーレイに対しても透過型ブロック転送に対してと同様に働く。 オーバーレイZオーダーは、オーバーレイ間の 重ねあわせ処理と透過処理を自動的に扱う。


DirectDraw HAL

DirectDraw ハードウェア・アブストラクション・レイヤ (HAL) は、ハードウェアに依存し、ハードウェア固有のコードだけからなる。 HALは、16ビットでも32ビットでも、また Windows 95上では双方の組み合わせで実装され得る。Windows NT上ではつねに32 ビットで実装される。 HALは、ディスプレイ・ドライバに統合された一部にも、またドライバ作成者が定義したプライベート・インターフェイスを通してディスプレイ・ドライバと通信する独立したDLLにもなり得る。

DirectDraw HALは、チップメーカー、ボードメーカー、ＯＥＭにより実装される。 HALはデバイス固有のコードだけから実装され、エミュレーションは行わず、ハードウェアにない機能は通知しない。 HALは、パラメータの確認を行わなず、パラメータ・チェックは、HALが呼び出される前にDirectDrawにより行われる。


DirectDraw HEL

DirectDrawハードウェア・エミュレーション・レイヤ(HEL) は、HALが行うのと同様に、 DirectDrawに対しその能力を通知する。こうした能力をアプリケーション初期化段階で調査することによって、パフォーマンスを最適化し、プラットフォームごとにアプリケーションのパラメータを調整できる。もしDirectDraw HALが見つからない場合、または要求された機能をハードウェアが提供していない場合、 DirectDrawはその機能をエミュレートすることになる。


DirectDrawオブジェクトのタイプ

DirectDrawオブジェクトはディスプレイ・デバイスを示す。各論理ディスプレイ・デバイスに対し複数の DirectDrawオブジェクトを作成することができる。 それぞれ独自のDirectDrawオブジェクトは、その他すべてのDirectDrawオブジェクトから独立したサーフェス、パレット、クリッパーなどのオブジェクトを作成する。

 DirectDrawSurfaceオブジェクトは、直接アクセスしたり操作したりできるディスプレイ・メモリの連続部分を表す。これらのディスプレイ・メモリのアドレスは、可視フレーム・バッファ・メモリ（プライマリ・サーフェス）あるいは 不可視バッファ（オフスクリーン・サーフェスまたはオーバーレイ・サーフェス)を指す。不可視バッファは通常、ディスプレイ・メモリに常駐する。しかし、ハード設計上の理由から、または DirectDrawがソフトウェア・エミュレーションを実行している場合、システム・メモリ上に作成することもできる。

DirectDrawPaletteオブジェクトは、16色と256色双方のインデックス・パレットを表す。 パレットは、 テクスチャ、オフスクリーン・サーフェス、オーバーレイ・サーフェスに対し提供される。これらはどれも、プライマリ・サーフェスと同じパレットを持たなくともよい。

DirectDrawオブジェクトはDirectDrawSurface、DirectDrawPalette、DirectDrawClipperの各オブジェクトを作成する。 DirectDrawPalette オブジェクトと DirectDrawClipperオブジェクトは、それが作用するDirectDrawSurfaceにアタッチしなければならない。DirectDrawSurfaceオブジェクトは、 DirectDrawPaletteオブジェクトをアタッチする要求を拒否する可能性がある。大部分のハードウェアは複数パレットをサポートしていないためで、しばしば起きることとして注意しなくてはいけない。


幅とピッチ

ディスプレイ・メモリに書きこむようなアプリケーションの場合、メモリに格納されたビットマップは連続したメモリ上になくとも良く、この場合、ビットマップ上のラインの幅とピッチが異なっていてもよい。幅は、格納されたビットマップのラインの始点と終点とを表すメモリ上の二アドレス間の距離である。 この距離は、メモリ上のビットマップの幅だけを表し、ビットマップの次のラインの始点に達するために必要な追加メモリ（カウント）を含まない。ピッチは、格納されたビットマップの現在のラインの始点と次のラインの始点とを表すメモリ上の二アドレス間の距離である。

たとえば矩形メモリでは、ディスプレイ・メモリのピッチは、ビットマップの幅プラス、キャッシュ部分を含む。次の図は、矩形メモリにおける幅とピッチの違いを示している。

この図では、フロント・バッファとバック・バッファは640×480×8、キャッシュは384×480×8である。 次ラインのアドレスを求めるには、 640と384を足して1024とし、これが次ラインの始点となる。

したがって、サーフェス・メモリに直接レンダリングするときは、つねにIDirectDrawSurface2::Lock メソッド (または、 IDirectDrawSurface2::GetDCメソッド)が返す値を使用する。単純にディスプレイ・モードに基づくピッチを前提としてはならない。 単にディスプレイ・モードに基づくピッチを前提とすると、アプリケーションがディスプレイ・アダプタによって動いたりうまく動かなかったりする場合がある。


3Dサーフェスのサポート

この節ではDirectDrawの3Dサーフェス機能について説明する。

テクスチャ・マップ

ミップマップ

Zバッファ


テクスチャ・マップ

テクスチャ・マップは、HELを使ってシステム・メモリ上に割り当てることが可能である。テクスチャ・マップ・サーフェスを割り当てるために、 IDirectDraw2::CreateSurfaceメソッドに渡すDDSURFACEDESC構造体のddsCapsメンバにDDSCAPS_TEXTUREフラグを指定する。

HELは広範なテクスチャ・ピクセル・フォーマットをサポートする。これらのフォーマットの詳細は、「テクスチャ・マップのフォーマット」を参照すること。


ミップマップ

DirectDrawは、ミップマップ・テクスチャ・サーフェスをサポートする。 ミップマップはテクスチャのシーケンスであり、それぞれのテクスチャは解像度が漸次低くなる同じイメージである。 ミップマップ中のフィルタをかけられた画像イメージをレベルと呼び、その大きさはレベル間で二乗の関係にある。高解像度レベルは、観測者に近いオブジェクトで用い、 低解像度レベルは、観測者からより遠いオブジェクトで用いる。ミップマップは、レンダリングされたテクスチャの品質を向上し、計算量を節約するために使用する。

 DirectDrawでのミップマップは、アタッチされたサーフェスのチェーンとして表す。 最高解像度のテクスチャはチェーンの先頭に置かれ、アタッチメントすなわち次レベルのミップマップを持つ。そのレベルもまたさらに次レベルをアタッチメントとして持ち、そうして順に最低解像度レベルまで続いていく。

ミップマップの１レベルを表すサーフェスを作成するには、IDirectDraw2::CreateSurfaceメソッドに渡すDDSURFACEDESC構造体のDDSCAPS_MIPMAPフラグを指定する。ミップマップはすべてテクスチャでもあるため、 DDSCAPS_TEXTURE フラグも指定されていなければならない。 IDirectDrawSurface2::AddAttachedSurfaceメソッド を使い、各レベルを自分で作成してチェーンを構成することができる。しかしIDirectDraw2::CreateSurfaceメソッドを使えば、全チェーンを一操作で構成できる。

次の例では、 サイズが256×256、128×128、64×64、32×32、16×16の５つのミップマップ・レベルからチェーンを構成する場合を示す。

DDSURFACEDESC       ddsd;

LPDIRECTDRAWSURFACE2 lpDDMipMap;

ZeroMemory(&ddsd, sizeof(ddsd));

ddsd.dwSize = sizeof(ddsd);

ddsd.dwFlags = DDSD_CAPS | DDSD_MIPMAPCOUNT;

ddsd.dwMipMapCount = 5;

ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE |

    DDSCAPS_MIPMAP | DDSCAPS_COMPLEX;

ddsd.dwWidth = 256UL;

ddsd.dwHeight = 256UL;

ddres = lpDD->CreateSurface(&ddsd, &lpDDMipMap);

if (FAILED(ddres))

.

.

.

ミップマップ・レベルの数を省略することもできるが、その場合IDirectDraw2::CreateSurfaceメソッドがサーフェスのチェーンを作成する。そのそれぞれのサーフェスは前サーフェスの平方根の大きさで作られ、可能なかぎりの小ささまで続く。幅と高さを省略することもでき、その場合IDirectDraw2::CreateSurfaceが、 最小レベルのサイズを1×1とする指定した数のレベルを作成する。

ミップマップ・サーフェスのチェーンは、DirectDrawSurface2::GetAttachedSurfaceメソッドを用い、DDSCAPS構造体のDDSCAPS_MIPMAPと DDSCAPS_TEXTURE フラグを指定することによって行う。 次の例は、最高解像度から最低解像度までミップマップ・チェーンをトレースしたものである。

LPDIRECTDRAWSURFACE lpDDLevel, lpDDNextLevel;

DDSCAPS ddsCaps;

lpDDLevel = lpDDMipMap;

lpDDLevel->AddRef();

ddsCaps.dwCaps = DDSCAPS_TEXTURE | DDSCAPS_MIPMAP;

ddres = DD_OK;

while (ddres == DD_OK)

{

    // このレベルの処理

    .

    .

    .

    ddres = lpDDLevel->GetAttachedSurface(

        &ddsCaps, &lpDDNextLevel);

    lpDDLevel->Release();

    lpDDLevel = lpDDNextLevel;

}

if ((ddres != DD_OK) && (ddres != DDERR_NOTFOUND))

.

.

.

ミップマップのフリッピング・チェーンを構成することもできる。この場合、各ミップマップ・レベルが、関連するバック・バッファ・テクスチャサーフェスを持つ。各バック・バッファ・テクスチャサーフェスは、ミップマップの一レベルにアタッチされている。 チェーンのフロント・バッファだけはDDSCAPS_MIPMAP フラグのセットを持ち、その他は単なるテクスチャ・マップである（DDSCAPS_TEXTURE フラグを使い作成されるテクスチャ・マップ) 。 ひとつのミップマップ・レベルは、アタッチされたテクスチャ・マップをふたつ持つことができる。ひとつはミップマップ・チェーンの次レベルであるDDSCAPS_MIPMAPセット、もうひとつはフリッピング・チェーンのバック・バッファであるDDSCAPS_BACKBUFFERフラグのセットである。各フリッピング・チェーンのサーフェスは、すべて同じサイズでなければならない。

このようなサーフェスの整列は、 IDirectDraw2::CreateSurfaceメソッドの呼び出し一回では構成できない。フリッピング・ミップマップを組み立てるには、複合ミップマップ・チェーンを構成し IDirectDrawSurface2::AddAttachedSurface メソッドによりバック・バッファを手動でアタッチするか、あるいはフリッピング・チェーンのシーケンスを作成して IDirectDrawSurface2::AddAttachedSurfaceによりミップマップを構成することになる。

Note

ブロック転送操作は、ミップマップ・チェーンの一レベルにのみ適用される。ミップマップの全チェーンをブロック転送するためには、各レベルを別々にブロック転送しなければならない。

 IDirectDrawSurface2::Flipメソッドは、与えられたレベルからミップマップ中の最低レベルまで、すべてのレベルをフリッピングする。フリッピング先のサーフェスも提供されるが、その場合ミップマップの全レベルが そのフリッピング・チェーンのバック・バッファにフリッピングされる。このバック・バッファは、与えられたオーバライドと一致する。たとえばフリッピングチェーンのトップレベルにある３番目のバック・バッファがオーバライドとして与えられた場合、ミップマップの全レベルはその３番目のバック・バッファにフリッピングする。

ミップマップ・チェーンのレベル数は、明示的に格納される。 アプリケーションが（IDirectDrawSurface2::LockまたはIDirectDrawSurface2::GetSurfaceDescメソッドを呼び出して)ミップマップのサーフェス・デスクリプタを取得するとき、トップレベルを含むミップマップのレベル数は DDSURFACEDESC 構造体の dwMipMapCountメンバが持っている。ミップマップのトップレベル以外のレベルについては、 dwMipMapCountメンバは、そのミップマップからチェーンの最小ミップマップまでのレベル数を指定する。


Zバッファ

DirectDraw HELは、 Direct3D� やその他3Dレンダリング・ソフトウェアが使うZバッファを作成できる。HELは16ビットと32ビット双方のZバッファをサポートする。 3Dアクセラレーションを持つディスプレイ・カード用のDirectDrawデバイス・ドライバは、 DDSCAPS_ZBUFFERフラグをエクスポートすることにより、ディスプレイ・メモリにZバッファを作ることができる。その場合デバイス・ドライバは、 DDCAPS 構造体のdwZBufferBitDepthsメンバを使って、サポートする Zバッファの深さも指定しなくてはならない。

アプリケーションは、 IDirectDrawSurface2::Blt メソッドを使うことによって、 Zバッファをクリアすることができる。DDBLT_DEPTHFILLフラグは、 ブロック転送がZバッファをクリアすることを示している。このフラグが指定されていると、 IDirectDrawSurface2::Bltメソッドに渡されたDDBLTFX 構造体は、要求されたZバッファ値をdwFillDepthメンバにセットする。3Dアクセラレーションを持つディスプレイ・カードのための DirectDrawデバイス・ドライバが、Zバッファのクリアをハードウェアでサポートするように設計されている場合、 DDCAPS_BLTDEPTHFILL フラグをエクスポートし、 DDBLT_DEPTHFILL ブロック転送を扱うはずである。奥行きを埋めるブロック転送の転送先サーフェスは、 Zバッファでなければならない。

Note

奥行き値の実際の解釈は、3Dレンダリング・システムに依存する。


DirectDrawとDirect3Dの統合

この節では、DirectDrawと Direct3Dの関係について述べる。

Direct3Dドライバ・インターフェイス

Direct3Dデバイス・インターフェイス

Direct3Dテクスチャ・インターフェイス

DirectDraw HELとDirect3D


Direct3Dドライバ・インターフェイス

DirectDrawはプログラマに統合された単一のオブジェクトを提供する。このオブジェクトは、 DirectDrawと Direct3D双方の状態をカプセル化する。 DirectDrawドライバのCOMインターフェイスとDirect3DドライバのCOMインターフェイスは、ともに、基礎にある同一オブジェクトとの通信が可能である。アプリケーションが Direct3Dを使うとき、 Direct3Dオブジェクトは作成されない。アプリケーションがDirectDrawオブジェクトへのDirect3D インターフェイスを得るには、標準のCOM QueryInterfaceメソッドを用いる。

次の例は、DirectDrawオブジェクトを作成し、そのオブジェクトと通信するためのDirect3Dインターフェイスを得る方法を示している。

LPDIRECTDRAW lpDD;

LPDIRECT3D lpD3D;

ddres = DirectDrawCreate(NULL, &lpDD, NULL);

if (FAILED(ddres))

.

.

.

ddres = lpDD->QueryInterface(IID_IDirect3D,

    &lpD3D);

if (FAILED(ddres))

.

.

.

この例で示されているコードでは、ひとつのオブジェクトを作成し、そのオブジェクトに対するふたつのインターフェイスを得ている。したがって、オブジェクトの参照カウントは、 IDirectDraw2::QueryInterface メソッドの呼び出し後は2となる。ここで重要なのは、Direct3Dドライバ・ステータスの寿命は、 DirectDrawオブジェクトの寿命と同じであるということである。 Direct3D インターフェイスを開放しても、 Direct3Dドライバ・ステータスが使えなくなるわけではない。 そのステータスは、そのオブジェクトへの参照が（その参照がDirectDrawまたは Direct3Dのいずれであるかにかかわらず）すべて開放されるまでなくなることはない。したがって、DirectDrawドライバ ・インターフェイスを参照したままDirect3Dインターフェイスを開放し 、再びDirect3D インターフェイスを照会した場合でも、Direct3Dステータスは維持されている。


Direct3Dデバイス・インターフェイス

Direct3Dオブジェクトの場合と同様、独立した Direct3Dデバイス・オブジェクトはない。 Direct3Dデバイスは、 3Dレンダリングの対象として使われる DirectDrawSurfaceオブジェクトと通信するための単なるインターフェイスなのである。次の例では、 DirectDrawSurfaceオブジェクトへのDirect3D デバイス・インターフェイスを作成している。

LPDIRECTDRAWSURFACE lpDDSurface;

LPDIRECT3DDEVICE    lpD3DDevice;

ddres = lpDD->CreateSurface(&ddsd, &lpDDSurface,

    NULL);

if (FAILED(ddres))

    .

    .

    .

ddres = lpDDSurface->QueryInterface(lpGuid,

    &lpD3DDevice);

if (FAILED(ddres))

    .

    .

    .

参照カウントとステータスの寿命について、同じルールがDirectDrawSurfaceオブジェクトと Direct3Dデバイスに適用される(これらのルールついては、「Direct3Dドライバ・インターフェイス」を参照すること)。さらに、同一の DirectDrawSurfaceオブジェクトに対し、複数の独自な Direct3D デバイス・インターフェイスを得ることができる。したがって、 単一の DirectDrawSurfaceオブジェクトを、ランプベース・デバイスとRGBベース・デバイス双方のターゲットとすることもできる。


Direct3Dテクスチャ・インターフェイス

Direct3D テクスチャは独自のオブジェクトタイプではなく、 DirectDrawSurfaceオブジェクトのもうひとつのインターフェイスである。次の例では、DirectDrawSurfaceオブジェクトからDirect3Dテクスチャ・インターフェイスを得ている。

LPDIRECTDRAWSURFACE lpDDSurface;

LPDIRECT3DTEXTURE   lpD3DTexture;

ddres = lpDD->CreateSurface(&ddsd, &lpDDSurface,

    NULL);

if (FAILED(ddres))

    .

    .

    .

ddres = lpDDSurface->QueryInterface(

    IID_IDirect3DTexture, &lpD3DTexture);

if (FAILED(ddres))

    .

    .

    .

参照カウントとステータス寿命について、同じルールがDirect3Dテクスチャに適用される(これらのルールついては、「Direct3Dドライバ・インターフェイス」を参照すること)。 ひとつのDirectDrawSurfaceオブジェクトをレンダリングのターゲットとテクスチャの双方に併用することが可能である。


DirectDraw HELとDirect3D

DirectDraw HELは、 テクスチャ、ミップマップ、Zバッファ・サーフェスの作成をサポートする。 さらに、DirectDrawと Direct3Dとの密な統合により、DirectDrawが動作可能なシステムはつねにDirect3Dをサポートする（少なくともソフトウェアエミュレーションによってサポートされる）。したがってDirectDraw HELは、サーフェスを3Dレンダリングに使えることを示すため、 DDSCAPS_3DDEVICE フラグをエクスポートする。ハードウェアでアクセラレートされた3Dディスプレイ・カードのDirectDrawドライバは、3Dハードウェア・アクセラレーションの存在を示すためこの能力をエクスポートする。


モードXディスプレイ・モード

モードXは、標準VGAモード13から派生したハイブリッド・ディスプレイ・モードである。このモードでは、 VGAディスプレイ・アダプタのEGA複数ビデオ・プレーン・システムにより256Kバイトまでのディスプレイ・メモリを使うことができる(モード13では64Kバイトまで) 。Windows 95上では、 DirectDrawはあらゆるディスプレイ・カードに ふたつのモードXモード (320×200×8と320×240×8) を提供する。また、リニアな低解像度モードをサポートするカードもあり、リニアな低解像度モードではプライマリ・サーフェスをロックして直接アクセスできる。モードXモードではプライマリ・サーフェスへの直接アクセスはできない。.

モードXモードは現在Windows NTではサポートされておらず、リニア低解像度モードも広くサポートはされていない。


ピクセル・フォーマット

この節は、 ハードウェア・エミュレーション・レイヤ(HEL)によってサポートされるピクセル・フォーマットの情報について 述べる。以下のトピックについて説明する。

テクスチャ・マップのフォーマット

オフスクリーン・サーフェスのフォーマット


テクスチャ・マップのフォーマット

HELは広範なテクスチャ・ピクセル・フォーマットをサポートする。次表がそれらのフォーマットを示している。マスクの欄は、赤（red）、緑（green）、青（blue）、混色（alpha）マスクから構成され、それぞれのピクセル・フォーマット・フラグとビット深度との組み合わせに対応する。

ピクセル・フォーマット・フラグ	ビット深度	マスク
DDPF_RGB |	1	R: 0x00000000
DDPF_PALETTEINDEXED1		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	1	R: 0x00000000
DDPF_PALETTEINDEXED1 |		G: 0x00000000
DDPF_PALETTEINDEXEDTO8		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	2	R: 0x00000000
DDPF_PALETTEINDEXED2		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	2	R: 0x00000000
DDPF_PALETTEINDEXED2 |		G: 0x00000000
DDPF_PALETTEINDEXEDTO8		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	4	R: 0x00000000
DDPF_PALETTEINDEXED4		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	4	R: 0x00000000
DDPF_PALETTEINDEXED4 |		G: 0x00000000
DDPF_PALETTEINDEXEDTO8		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	8	R: 0x00000000
DDPF_PALETTEINDEXED8		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB	8	R: 0x000000E0
		G: 0x0000001C
		B: 0x00000003
		A: 0x00000000
DDPF_RGB |	16	R: 0x00000F00
DDPF_ALPHAPIXELS		G: 0x000000F0
		B: 0x0000000F
		A: 0x0000F000
DDPF_RGB	16	R: 0x0000F800
		G: 0x000007E0
		B: 0x0000001F
		A: 0x00000000
DDPF_RGB	16	R: 0x0000001F
		G: 0x000007E0
		B: 0x0000F800
		A: 0x00000000
DDPF_RGB	16	R: 0x00007C00
		G: 0x000003E0
		B: 0x0000001F
		A: 0x00000000
DDPF_RGB |	16	R: 0x00007C00
DDPF_ALPHAPIXELS		G: 0x000003E0
		B: 0x0000001F
		A: 0x00008000
DDPF_RGB	24	R: 0x00FF0000
		G: 0x0000FF00
		B: 0x000000FF
		A: 0x00000000
DDPF_RGB	24	R: 0x000000FF
		G: 0x0000FF00
		B: 0x00FF0000
		A: 0x00000000
DDPF_RGB	32	R: 0x00FF0000
		G: 0x0000FF00
		B: 0x000000FF
		A: 0x00000000
DDPF_RGB	32	R: 0x000000FF
		G: 0x0000FF00
		B: 0x00FF0000
		A: 0x00000000
DDPF_RGB |	32	R: 0x00FF0000
DDPF_ALPHAPIXELS		G: 0x0000FF00
		B: 0x000000FF
		A: 0xFF000000
DDPF_RGB |	32	R: 0x000000FF
DDPF_ALPHAPIXELS		G: 0x0000FF00
		B: 0x00FF0000
		A: 0xFF000000
 HELはこれらのフォーマットをシステム・メモリ上に作成することができる。3Dアクセラレーション・ディスプレイ・カードのためのDirectDrawデバイス・ドライバは、ディスプレイ・メモリに他のフォーマットを作成する場合がある。そうしたドライバは、テクスチャを作成できることを示すため DDSCAPS_TEXTURE フラグをエクスポートする。


オフスクリーン・サーフェスのフォーマット

次の表は、 DirectX 3 HELがサポートするオフスクリーン・プレーンサーフェスのピクセル・フォーマットを示している。マスクの欄は赤（red） 、緑（green） 、青（blue）、アルファ（alpha）で構成され、それぞれのピクセル・フォーマット・フラグとビット深度との組み合わせに対応する。

ピクセル・フォーマット・フラグ	ビット深度	マスク
DDPF_RGB |	1	R: 0x00000000
DDPF_PALETTEINDEXED1		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	2	R: 0x00000000
DDPF_PALETTEINDEXED2		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	4	R: 0x00000000
DDPF_PALETTEINDEXED4		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	8	R: 0x00000000
DDPF_PALETTEINDEXED8		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB	16	R: 0x0000F800
		G: 0x000007E0
		B: 0x0000001F
		A: 0x00000000
DDPF_RGB	16	R: 0x00007C00
		G: 0x000003E0
		B: 0x0000001F
		A: 0x00000000
DDPF_RGB	24	R: 0x00FF0000
		G: 0x0000FF00
		B: 0x000000FF
		A: 0x00000000
DDPF_RGB	24	R: 0x000000FF
		G: 0x0000FF00
		B: 0x00FF0000
		A: 0x00000000
DDPF_RGB	32	R: 0x00FF0000
		G: 0x0000FF00
		B: 0x000000FF
		A: 0x00000000
DDPF_RGB	32	R: 0x000000FF
		G: 0x0000FF00
		B: 0x00FF0000
		A: 0x00000000
HELはまた、 広範なオフスクリーン・サーフェスのサポートに加え、 Direct3Dとその他3Dレンダリング・システムで使われるよう設計されたサーフェスもサポートする。


DirectDrawインターフェイス概要

この節はDirectDraw COM インターフェイスについての一般的な概要を説明する。

IDirectDraw2 インターフェイス

IDirectDrawClipper インターフェイス

IDirectDrawPalette インターフェイス

IDirectDrawSurface2 インターフェイス


IDirectDraw2インターフェイス

この節ではIDirectDraw2インターフェイスに関する追加情報を説明する。

DirectDrawオブジェクト

IDirectDraw2で何が新しくなったか?

処理ごとの複数DirectDrawオブジェクト

高解像度とトゥルーカラーのビット深度サポート

プライマリ・サーフェス・リソース共有モデル

モード変更と排他的アクセス

CoCreateInstanceを用いたDirectDrawオブジェクトの作成


DirectDrawオブジェクト

DirectDrawオブジェクトは、ディスプレイ・ハードウェアを表す。 インスタンス化されたディスプレイ・デバイスがハードウェア・アクセラレーションを持つ場合、オブジェクトはハードウェア・アクセラレーションが行われる。 DirectDrawオブジェクトは三種類のオブジェクトを作成する。DirectDrawSurface、DirectDrawPalette、DirectDrawClipperである。

DirectDrawオブジェクトは、一度にふたつ以上インスタンス化できる。 最も単純な例としては、Windows 95 システム上でふたつのモニターを使う場合がある。 Windows 95自体は、デュアル・モニタをサポートしないが、ディスプレイ・デバイスそれぞれにDirectDraw HALを書くことができる。 Windows 95とGDIが認識するディスプレイ・デバイスは、デフォルトのDirectDrawオブジェクトがインスタンス化されるとき用いられるものであり、 そうでないデバイスは、第二のディスプレイ・デバイスのグローバル・ユニーク識別子 (GUID) を使って作成された独立したもうひとつのDirectDrawオブジェクトによりアドレスする。この GUIDは、DirectDrawEnumerate 関数を使って取得できる。

DirectDrawオブジェクトは作成したオブジェクトすべてを管理し、デフォルトのパレット（プライマリ・サーフェスが8ビット/ピクセル・モードの場合）、デフォルトのカラー・キー 、ハードウェア・ディスプレイ・モードを制御する。そしてどのリソースが割り当て済みでどのリソースが使用可能かを調査する。


IDirectDraw2で何が新しくなったか?

DirectXが使用するCOMモデルは、新しいインターフェイスの提供により新しい機能を追加できるという特徴をもっており、 IDirectDraw2インターフェイスは、IDirectDrawインターフェイスを代替するものである。IDirectDraw2インターフェイスは、 IDirectDraw::QueryInterface メソッドを使って得ることができる。次に例を示す。

// IDirectDraw2インターフェイスの作成

LPDIRECTDRAW  lpDD;

LPDIRECTDRAW2 lpDD2;

ddrval = DirectDrawCreate(NULL, &lpDD, NULL);

if(ddrval != DD_OK)

    return;

ddrval = lpDD->SetCooperativeLevel(hwnd,

    DDSCL_NORMAL);

if(ddrval != DD_OK)

    return;

ddrval = lpDD->QueryInterface(IID_IDirectDraw2,

    (LPVOID *)&lpDD2);

if(ddrval != DD_OK)

    return;

ddscaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;

ddrval = lpDD2->GetAvailableVidMem(&ddscaps, &total,

    &free);

if(ddrval != DD_OK)

    return;

例は、C++文法で記述されている。この場合、IDirectDraw2 インターフェイスを作成するためにIDirectDraw::QueryInterface メソッドを用いることになる。このインターフェイスはIDirectDraw2::GetAvailableVidMem メソッドを含んでいるが、このメソッドをIDirectDraw インターフェイスから使おうとするとコンパイル中にエラーが発生する。

IDirectDraw2::GetAvailableVidMemメソッド は、IDirectDraw2 インターフェイスが作成されたときにIDirectDrawtDrawインターフェイスに加わった唯一のメソッドである（IDirectDraw2::SetDisplayModeとIDirectDraw2::EnumDisplayModesのふたつのメソッドは 、IDirectDraw2に含まれたときに変更・拡張がなされた）。

IDirectDraw::SetCooperativeLevelメソッドとCooperativeLevelIDirectDrawメソッドとの相互作用は、 IDirectDraw2::SetCooperativeLevelメソッドとIDirectDraw2::SetDisplayModeメソッドとの相互作用とはわずかに異なっている。IDirectDrawインターフェイスを使い、アプリケーションが、DDSCL_EXCLUSIVEフラグをセットしてIDirectDraw2::SetCooperativeLevelを呼び出して排他的（フルスクリーン）モードを取得、 IDirectDraw2::SetDisplayModeを使ってモードを変え、DDSCL_NORMALフラグをセットしIDirectDraw２::SetCooperativeLevelを呼び出して排他的モードを解放した場合にオリジナルのディスプレイ・モードが復元されないのである。この場合はアプリケーションが IDirectDraw::RestoreDisplayModeメソッドを呼び出すか、 DirectDrawオブジェクトが削除されるまでは、新しいディスプレイ・モードのままとなる。 しかし、IDirectDraw2インターフェイスを使っている場合、アプリケーションが同様のステップを踏むと、排他的モードが失われればオリジナルのディスプレイ・モードが自動的にリストアされるようになる。

新しいインターフェイスのリリースとともに、従来のメソッドがいくつか変更される。そのため、インターフェイス・メソッドの新旧バージョン（たとえば IDirectDrawと IDirectDraw2）を混用すると、予想外の結果を引き起こす。特定のバージョンのインターフェイスからだけメソッドを使うべきである。


処理ごと複数 DirectDraw オブジェクト
処理ごとの複数DirectDrawオブジェクト

DirectDrawでは、必要な回数だけの DirectDrawCreate 関数呼び出し処理が可能である。 呼び出しごとに、独立した異なるインターフェイスが返される。 それぞれのDirectDrawオブジェクトは、オブジェクト間で依存性がない。まさに、独自プロセスから作成されたかのように振る舞うのである。

DirectDrawオブジェクトが独立していることから、特定の DirectDrawオブジェクトによって作成された DirectDrawSurface、DirectDrawPalette、DirectDrawClipperの各オブジェクトは、作成源以外のDirectDrawオブジェクトとともに使われてはならない。これらのオブジェクトは作成源のDirectDrawオブジェクトが破棄されるときに自動的に解放されるからである。他の DirectDrawオブジェクトとともに使われた場合、もとのオブジェクトが破棄されると機能が停止してしまう可能性がある。

ただし、DirectDrawCreateClipper 関数により作成されたDirectDrawClipperオブジェクトは例外である。このオブジェクトは、あらゆるDirectDrawオブジェクトから独立し、ひとつまたはそれ以上のDirectDrawオブジェクトとともに使用することができる。


高解像度とトゥルーカラーのビット深度サポート

DirectDrawは、 ディスプレイ・デバイス・ドライバがサポートするすべてのスクリーン解像度とビット深度をサポートする。 DirectDrawにより、アプリケーションは、コンピュータのディスプレイ・ドライバがサポートするどのモードにも変更できるようになる。これにはサポートされている24-bppと32-bppのモードすべてが含まれる。

DirectDrawはまた、 HELが24- bppと 32-bpp サーフェスのブロック転送もサポートしている。 ディスプレイ・デバイス・ドライバがこれらの解像度でブロック転送をサポートしている場合は、ディスプレイ・メモリ間のブロック転送にハードウェア・ブロック転送が使われ、そうでないときはHELが使用される。

Windowsでは、使っているモニタのタイプをユーザが指定することができる。DirectDrawは、インストールされたモニタのディスプレイ制限をチェックする。要求されたモードがユーザのモニタで表示できないと、 IDirectDraw2::SetDisplayMode メソッドの呼び出しは失敗する。また、IDirectDraw2::EnumDisplayModesメソッドを呼び出したときに列挙されるのは、インストールされているモニタがサポートするモードだけである。


プライマリ・サーフェス・リソース共有モデル

DirectDrawは単純なリソース共有モデルである。 ディスプレイ・メモリは共有リソースであり、不足しがちである。 ディスプレイ・モードが変更されると、 ディスプレイ・メモリに格納されたサーフェスはすべて失われる（ 詳しくは、「サーフェスの消失」を参照すること）。

DirectDrawは、 GDIと共有するディスプレイ・デバイスのためにインスタンス化されるとき、暗黙的に GDI プライマリ・サーフェスを作成する。 GDIは、 プライマリ・サーフェスへの共有アクセスを与えられる。DirectDrawは、 GDIが プライマリ・サーフェスとして認識するサーフェス・メモリを記憶している。 GDIのプライマリ・サーフェスを所有するDirectDrawSurfaceオブジェクトは、つねにIDirectDraw2::GetGDISurface メソッドを使うことによって得られる。

GDIは、 DirectDrawが管理するディスプレイ・メモリ上のフォント、ブラシ、 デバイス依存ビットマップ(DDB)をキャッシュできない。利用できるメモリを DirectDrawのヒープマネージャに通知する前、あるいはDirectDrawのヒープマネージャからキャッシュされたデータのためにディスプレイ・ドライバがメモリを割り当てまたは解放できるようになる前に、HALは、 DIBエンジン・ドライバが必要とするディスプレイ・メモリを予約しなければならない。


モード変更と排他的アクセス

アプリケーションは、 IDirectDraw2::SetDisplayMode メソッドを使ってディスプレイ・モードを変更することができる。 一枚のディスプレイ・カードを共有しているかぎり、すべてのアプリケーションがモードを変更できる。

ディスプレイ・モードのピクセル深度は、 DirectDrawオブジェクトへの排他的アクセスが取得できた場合にだけ、アプリケーションから変更できる。モードが変更されると、すべての DirectDrawSurfaceオブジェクトはサーフェス・メモリを失い操作不能になる。 サーフェスのメモリは、IDirectDrawSurface2::Restore メソッドを使うことで再割り当てしなくてはならない。

DirectDrawの排他的（フルスクリーン）モードにおいて、他のアプリケーションではDirectDrawSurfaceオブジェクトを割り当てられ、DirectDrawの使用やGDIの機能も利用可能である。しかし、排他的モード以外のアプリケーションがディスプレイ・モードやパレットを変更することは禁止される。


CoCreateInstanceを用いたDirectDrawオブジェクトの作成

DirectDrawCreate 関数ではなく、CoCreateInstance 関数 とIDirectDraw2::Initialize メソッド を使ってDirectDrawオブジェクトを作成することができる。 以下に手順を示す。

1	アプリケーションの始めで、 NULLを指定してCoInitializeを呼び出し、COMを初期化する。

if (FAILED(CoInitialize(NULL)))

    return FALSE;

2	CoCreateInstanceとIDirectDraw2::Initialize メソッドを使ってDirectDrawオブジェクトを作成する。

ddrval = CoCreateInstance(&CLSID_DirectDraw,

    NULL, CLSCTX_ALL, &IID_IDirectDraw2, &lpdd);

if(!FAILED(ddrval))

    ddrval = IDirectDraw2_Initialize(lpdd, NULL);

このCoCreateInstanceの呼び出し中、最初のパラメータCLSID_DirectDrawは、 DirectDrawドライバ・オブジェクト・クラスのクラス識別子である。 IID_IDirectDraw2 パラメータは、作成される特定のDirectDraw インターフェイスを識別する。 lpddパラメータは、取得されるDirectDrawオブジェクトを指す。 呼び出しが成功すると、この関数は初期化されていないオブジェクトを返す。

3	DirectDrawオブジェクトを使う前に、IDirectDraw2::Initializeを呼び出さなくてはならない。このメソッドは、 DirectDrawCreate 関数が一般的に使うドライバ GUID パラメータ （この場合NULL）を引数に取る。 DirectDrawオブジェクト初期化後は、 DirectDrawCreate 関数を使って作成したのと同様に使用、解放することができる。 DirectDrawオブジェクトと関連づけられたメソッドを使う前に、 IDirectDraw2::Initialize メソッドを呼び出さないと、 DDERR_NOTINITIALIZEDエラーが発生する。.

アプリケーションを閉じる前に、 CoUninitialize 関数を使ってCOMをシャットダウンしなくてはならない。

CoUnitialize();


IDirectDrawClipperインターフェイス

IDirectDrawClipper インターフェイスは、クリップ・リストの作成とメンテナンスのタスクを単純化する。 このインターフェイスは、排他的（フルスクリーン）モードよりも、ウィンドウで動作するアプリケーションで有用である。ウィンドウで動作するアプリケーションは、変更された領域だけスクリーンを更新するために、クリップ・リストを使うことができる。

以下のトピックは、IDirectDrawClipper インターフェイス に関連する追加情報からなる。

クリップ・リスト

DirectDrawClipperオブジェクトの共有

ドライバ非依存のDirectDrawClipperオブジェクト

CoCreateInstanceを用いたDirectDrawClipperオブジェクトの作成


クリップ・リスト

DirectDrawは、DirectDrawClipperオブジェクトを使ってクリップ・リストを管理する。 クリップ・リストは、サーフェスの可視領域を記述する矩形のリストである。 DirectDrawClipperオブジェクトは、どのサーフェスにもアタッチできる。またウィンドウ・ハンドルをDirectDrawClipperオブジェクトにアタッチすることもでき、その場合DirectDrawは、ウィンドウの変更に伴ってウィンドウから得られるクリップ・リストにより、DirectDrawClipperクリップ・リストを更新する。

クリップ・リストは DirectDraw HALによって可視化されるが、 DirectDrawはクリップ・リストの要求に見合う矩形のブロック転送にだけHALを呼び出す。たとえばサーフェスの右上の四角形がクリッピングされ、そのサーフェスをプライマリ・サーフェスにブロック転送するようアプリケーションが DirectDrawに指示した場合、 DirectDrawはHALにふたつのブロック転送を行わせる。ひとつはサーフェスの左上角、もうひとつはサーフェスの下半分である。

オーバーレイ・ハードウェアがクリッピングをサポートし、かつ転送先カラー・キーがアクティブでない場合にのみ、 HALはオーバーレイにクリップ・リストを利用する。 現在のハードウェアの大部分は、転送先カラー・キーに従わないかぎり、閉塞したオーバーレイはサポートしない。これはハードウェア能力としてDirectDrawに報告されるが、このときもし閉塞となるとオーバーレイは無効化される。この場合、HALはクリップ・リストを無視する。


DirectDrawClipperオブジェクトの共有

DirectDrawClipperオブジェクトは、 複数サーフェス間で共有することができる。たとえば同じ DirectDrawClipperオブジェクトは、フリッピング・チェーンのフロント・バッファとバック・バッファの双方でセットすることができる。アプリケーションがＩＤirectDrawSurface2::SetClipper メソッドを使って DirectDrawClipperオブジェクトをサーフェスにアタッチするとき、サーフェスはそのオブジェクトの参照カウントをインクリメントする。サーフェスの参照カウントが0になると、 アタッチされたDirectDrawClipperオブジェクトの参照カウントはデクリメントされる。さらに、 クリッパー・インターフェイス・ポインタをNULLにしてIDirectDrawSurface2::SetClipperを呼び出すことによりDirectDrawClipperオブジェクトがサーフェスからデタッチされた場合、 サーフェスのDirectDrawClipperオブジェクトの 参照カウントはデクリメントされる。

Note

同じDirectDrawClipperオブジェクト、同じサーフェスに対し、 IDirectDrawSurface2::SetClipperを何度か続けて呼び出した場合、オブジェクトの参照カウントは一度しかインクリメントされない。連続する呼び出しは、オブジェクトの参照カウントに影響を与えないのである。


ドライバ非共存の DirectDrawClipper オブジェクト
ドライバ非依存のDirectDrawClipperオブジェクト

あらゆるDirectDrawオブジェクトにも直接所有されないDirectDrawClipperオブジェクトを作成することができる。これらのDirectDrawClipperオブジェクトは、複数のDirectDrawオブジェクトが共有することが可能である。ドライバ非依存のDirectDrawClipperオブジェクトは、新しいDirectDrawCreateClipper 関数を使って作成する。アプリケーションは、DirectDrawオブジェクトを作成する前でも、DirectDawClipperオブジェクトを作成することができる。

DirectDrawオブジェクトはこれらのDirectDrawClipperオブジェクト を所有しないため、アプリケーションのオブジェクトが解放されても自動的には解放されない。また、アプリケーションが明示的に解放しない場合はDirectDrawがアプリケーション終了時に解放する。

IDirectDraw2::CreateClipper メソッドを使って DirectDrawClipperオブジェクトを作成することもできる。これらのDirectDrawClipperオブジェクトは、もとのDirectDrawオブジェクトが解放されたとき自動的に解放される。


CoCreateInstanceを用いたDirectDrawClipperオブジェクトの作成

DirectDrawClipperオブジェクトは、COMとの互換性のためにクラス・ファクトリを完全サポートする。さらに、標準的な DirectDrawCreateClipper 関数と IDirectDraw2::CreateClipper メソッドを使うことに加え、CoGetClassObject 関数を呼びクラス・ファクトリを得てからCoCreateInstance関数を呼び出すか、あるいは直接 CoCreateInstanceを呼び出すことによって、DirectDrawClipperオブジェクトを作成することができる。以下の用例は、 CoCreateInstanceとIDirectDrawClipper::Initialize メソッドを使ってDirectDrawClipperオブジェクトを作成する方法を示している。

ddrval = CoCreateInstance(&CLSID_DirectDrawClipper,

    NULL, CLSCTX_ALL, &IID_IDirectDrawClipper, &lpClipper);

if (!FAILED(ddrval))

    ddrval = IDirectDrawClipper_Initialize(lpClipper,

        lpDD, 0UL);

CoCreateInstanceの呼び出しでは、最初のパラメータCLSID_DirectDrawClipperは、DirectDrawClipperオブジェクト・クラスのクラス識別子である。IID_IDirectDrawClipperパラメータは、現在サポートされているインターフェイスを識別し、lpClipperパラメータは、取得されたDirectDrawClipperオブジェクトを指す。

クラス・ファクトリのメカニズムによって作成されるDirectDrawClipperオブジェクトを使用前に初期化するために、アプリケーションは IDirectDrawClipper::Initializeメソッドを使う必要がある。 0ULの値はdwFlagパラメータで、この場合はフラグが現在サポートされていないため値は0となる。用例では、 lpDDはDirectDrawClipperオブジェクトを所有するDirectDrawオブジェクトである。しかし、代わりにNULLの値を指定することもでき、そうすると独立した DirectDrawClipperオブジェクトが作成される（これはDirectDrawCreateClipper 関数を使ってDirectDrawClipperを作成することと同じである）。

アプリケーションを終了する前にCoUninitialize 関数を使ってCOMをシャットダウンすることが必要である。

CoUnitialize();


IDirectDrawPalette インターフェイス

以下は、 IDirectDrawPalette インターフェイスに関する追加情報である。

DirectDrawPaletteオブジェクト

非プライマリ・サーフェスでのパレットの設定

パレットの共有

パレット・タイプ


DirectDrawPaletteオブジェクト

DirectDrawPaletteオブジェクトは、16色と256色のパレットを直接操作できるようにするため提供されている（ DirectDrawPaletteオブジェクトは一般に、DirectDrawSurfaceオブジェクトにアタッチされる）。 DirectDrawPaletteオブジェクトは、256色パレットのために0から255までのエントリを用意する。16色パレットのためのエントリは用意されない。これによりカラー・テーブルを一つのテーブルとして直接操作できる。カラー・テーブルはカラー値（一般にはRGB三原色）の配列であり、このテーブルは、一般に 各インデックスと関連した色を表現する16ビットと24ビットのRGBエントリを含む。また16色パレットのために、テーブルはもうひとつの256色パレットへのインデックスも持つことができる。

アプリケーションは、 IDirectDrawPalette::GetEntries メソッドを使ってこれらのテーブル中のエントリを取得できる。また、 IDirectDrawPalette::SetEntries メソッドを使って、これらのエントリを変更することもできる。このメソッドは、 パレットへの変更がいつ発効するか指定するdwFlags パラメータを持つ。

DirectDrawPaletteオブジェクトを使った簡単なパレットアニメーションを提供するには、それぞれひとつづつのメソッドを用いたふたつの方法がある。 最初の方法は、動画に使用される色に対応するパレット・エントリを直接変更することである。これにはIDirectDrawPalette::SetEntries メソッドを一回呼び出せばよい。もうひとつの方法には、 ふたつのDirectDrawPaletteオブジェクトが必要である。アプリケーションは、 ひとつのDirectDrawSurfaceオブジェクトに２つのDirectDrawPaletteオブジェクトを交互にアタッチすることでアニメーションを実行する。これは IDirectDrawSurface2::SetPaletteメソッドを使って行うことができる。


非プライマリ・サーフェスでのパレットの設定

パレットは、パレット化されたどんなサーフェス（プライマリ、バック・バッファ、オフスクリーン・プレーン、テクスチャ・マップ）にもアタッチすることができるが、システム・パレットに影響を与えるのは、プライマリ・サーフェスにアタッチされたパレットだけである。注意すべき重要な点は、 DirectDraw ブロック転送が色変換を実行しないということである。ブロック転送の転送元あるいは転送先サーフェスにアタッチされたすべてのパレットが無視されるのである。さらにIDirectDrawSurface2::GetDC メソッドは、サーフェスに対して選ばれたあらゆるDirectDrawPaletteオブジェクトを無視する。

アプリケーションやDirect3D (または他の3Dレンダリングシステム)は、非プライマリ・サーフェス ・パレットの使用を前提にしている。


パレットの共有

パレットは複数サーフェス間で共有する。フリッピング・チェーンのフロント・バッファとバック・バッファで同じパレットがセットされ、複数テクスチャ・サーフェス間で共有される。アプリケーションが IDirectDrawSurface2::SetPalette メソッドを使ってパレットをサーフェスにアタッチすると、サーフェスはそのパレットの参照カウントをインクリメントする。サーフェスの参照カウントが0になると、サーフェスはアタッチされたパレットの参照カウントをデクリメントする。さらに、パレット・インターフェイス・ポインタをNULLにして IDirectDrawSurface2::SetPaletteによりサーフェスからパレットをデタッチした場合、サーフェス・パレットの参照カウントはデクリメントされる。

Note

 同じパレット、同じサーフェスに対し、 IDirectDrawSurface2::SetPaletteが何度か続けて呼び出された場合、パレットの参照カウントは一度しかインクリメントされない。連続する呼び出しは、パレットの参照カウントに影響を与えないのである。


パレット・タイプ

DirectDrawは、 1ビット (2 エントリ)、2ビット (4 エントリ)、 4ビット (16 エントリ)、 8ビット (256エントリ) パレットをサポートする。パレットは、ピクセル・フォーマットが一致するサーフェスにだけアタッチされることができる。たとえば、 DDPCAPS_1BIT フラグを指定して作成された2エントリパレットは、 DDPF_PALETTEINDEXED1 フラグを指定して作成された1ビットサーフェスにだけアタッチされることができる。.

また、インデックス・パレットを作成することもできる。インデックス・パレットのエントリはRGBカラーを持たず、ターゲットとなる他のパレットのPALETTEENTRY 構造体の配列への整数インデックスを持つ。インデックス・パレットのカラー・テーブルは、2、4、16、256バイトの配列であり、それぞれのバイトは、パレットのインデックスを表す。

インデックス・パレットを作成するには、 IDirectDraw2::CreatePalette メソッド.を呼び出すときに、 DDPCAPS_8BITENTRIES フラグを指定する。たとえば、４ビットのインデックス・パレットを作成するときは DDPCAPS_4BIT |DDPCAPS_8BITENTRIESを指定する。また、インデックス・パレットを作成するときは、PALETTEENTRY 構造体の配列ポインタよりも、バイト配列ポインタを渡すほうが望ましい。 そのときIDirectDraw2::CreatePalette メソッドを使う場合は、 LPPALETTEENTRY型へバイト配列ポインタをキャストしなければならない。


ウィンドウ・モードでのDirectDrawパレット使用

 IDirectDrawPalette インターフェイス・メソッドは、ディスプレイが排他的（フルスクリーン）モードの場合、ハードウェアに直接書きこみを行う。しかしディスプレイ・モードが、非排他的（ウィンドウ）モードの場合、他のウィンドウアプリケーションと協調動作するために、 IDirectDrawPalette インターフェイスメソッドはGDIのパレット操作関数を呼ばなければならない。 これにより、 DirectDrawのウィンドウ・アプリケーションではパレットは次のような方法で使われることになる。

(IDirectDraw2::CreatePaletteとIDirectDrawPalette::SetEntriesメソッドに渡される) PALETTEENTRY 構造体のpeFlagsメンバを的確にセットしなければならない。

 Windowsの静的パレット・エントリ（0から9、246から255にインデックスされている)を変更しようとしてはならない。

次のトピックは、プライマリ・サーフェスや一般的なWindowsのウィンドウを作成経験があること、Windowsのデスクトップが8ビット・パレット・モードであることを想定して書かれている。

ウィンドウ・モードのパレット・エントリ・タイプ

ウィンドウ・モードでのIDirectDraw::CreatePaletteの呼び出し

ウィンドウ・モードのIDirectDrawPalette::SetEntriesの呼び出し

ウィンドウ・モードのパレット・エントリ・タイプ

非排他的（ウィンドウ）モードでは、パレット・エントリの以下の各タイプは、対応する PALETTEENTRY 構造体のpeFlagsメンバに異なるセットを持たなければならない。構造体はIDirectDraw2::CreatePaletteまたは IDirectDrawPalette::SetEntries メソッドに渡す配列中にある。排他的（フルスクリーン）モードではpeFlagsメンバは無視されるため、考慮しなくてよい。 非排他的（ウィンドウ）モードでは、パレットに対するエントリは次の3つのタイプである。

Windows静的エントリ

一般的に、Windowsは、0から9、246から255までのエントリを予約（システムパレット）しており、アプリケーションがそれらエントリの色値を変更することを禁止している。それらの色を含む256色エントリ・パレットをGetSystemPaletteEntries Win32 関数を呼び出して構成することはできるが、アプリケーションが直接これらのエントリを参照する方が効率的である。 それにはまず、パレット・テーブルの与えられたエントリがどの物理的なパレット・インデックスをマップするか指定する。PC_EXPLICIT フラグをPALETTEETRY 構造体のpeFlagsメンバ  に格納し、 エントリがマップする物理パレットのインデックスとしてpeRedメンバをセットする。こうしてアプリケーションから直接参照することができる。アプリケーションはまた、強制的にWindowsに0と255のエントリだけを予約するようにさせるため、SetSystemPaletteUse Win32 関数を呼びだすこともでき、この場合はPC_EXPLICITに対するPALETTEENTRY 構造体の0と255のエントリだけを指定するべきである。

 	アニメーション・エントリ

アプリケーションが、パレット・アニメーション効果を作成するために変更できる。 アニメーション・エントリのための PC_RESERVED フラグをアプリケーションが指定した場合、 Windowsは他アプリケーションが論理パレットを物理パレットにマップすることを禁止する。これにより、アプリケーションがエントリに異なる色を設定したときに、他のアプリケーションがその色を戻してしまうことを避けられる。

 	非アニメーション・エントリ

アプリケーションが変更できないエントリである。 非アニメーション・エントリは、単にPC_NOCOLLAPSE フラグで埋められており、このフラグは、他の割り当て済み物理パレット・エントリをWindowsが置き換えないようにしている。

まとめると、 PALETTEENTRY 構造体には以下のような3つのタイプを設定することになる。

エントリ・タイプ	peFlags値	peRed, peGreen,  peBlue値
Windows静的エントリ(0-9と 246-255、または0と255へのインデックス)	PC_EXPLICIT	peRed = index, peGreen = 0, peBlue = 0
アニメーション・エントリ	PC_RESERVED | PC_NOCOLLAPSE	色値
非アニメーション・エントリ	PC_NOCOLLAPSE	色値
ウィンドウ・モードでのIDirectDraw2::CreatePaletteの呼び出し

次に、 非排他的（ウィンドウ）モードで DirectDrawパレットをどのように作成するかを示す。 IDirectDraw2::CreatePalette メソッドに渡した PALETTEENTRY 構造体の256エントリのすべてをセットアップすることがきわめて重要である。

LPDIRECTDRAW        lpDD; // あらかじめ初期化されている

PALETTEENTRY        pPaletteEntry[256];

int                 index;

HRESULT             ddrval;

LPDIRECTDRAWPALETTE lpDDPal;

// Windows静的エントリを設定する

for (index = 0; index < 10 ; index++)

{

    // 最初の10の静的エントリ

    pPaletteEntry[index].peFlags = PC_EXPLICIT;

    pPaletteEntry[index].peRed = index;

    pPaletteEntry[index].peGreen = 0;

    pPaletteEntry[index].peBlue = 0;

    // 最後の10の静的エントリ

    pPaletteEntry[index+246].peFlags = PC_EXPLICIT;

    pPaletteEntry[index+246].peRed = index+246;

    pPaletteEntry[index+246].peGreen = 0;

    pPaletteEntry[index+246].peBlue = 0;

}

// プライベートエントリのセットアップ。この例では、利用できる

// 最初の16エントリがアニメーションされる

for (index = 10; index < 26; index ++)

{

    pPaletteEntry[index].peFlags = PC_NOCOLLAPSE|PC_RESERVED;

    pPaletteEntry[index].peRed = 255;

    pPaletteEntry[index].peGreen = 64;

    pPaletteEntry[index].peBlue = 32;

}

// 残りをセットアップ。非アニメーション・エントリ

for (; index < 246; index ++) // 前のループでインデックスをセット

{

    pPaletteEntry[index].peFlags = PC_NOCOLLAPSE;

    pPaletteEntry[index].peRed = 25;

    pPaletteEntry[index].peGreen = 6;

    pPaletteEntry[index].peBlue = 63;

}

// すべての256エントリが埋まった。パレットの作成

ddrval = lpDD->CreatePalette(DDPCAPS_8BIT, pPaletteEntry,

    &lpDDPal,NULL);

ウィンドウ・モードでのIDirectDrawPalette::SetEntriesの呼び出し

IDirectDrawPalette::SetEntries メソッドで用いられるPALETTEENTRY 構造体に適用されるルールは、IDirectDraw2::CreatePalette メソッドにも適用される。一般にPALETTEENTRY 構造体の配列はアプリケーション開発者自身がメンテナンスするため、再構築は不要と考えられる。必要ならば配列を変更し、パレット更新時には IDirectDrawPalette::SetEntriesを呼び出すこともできる。

多くの場合、 非排他的（ウィンドウ）モードでWindows静的エントリを設定しようとした場合、結果は予測できない。従って非排他的（ウィンドウ）モードでのWindows静的エントリへの設定はするべきではない。 唯一の例外は、256エントリをすべてリセットする場合である。パレットアニメーションでは一般に、 PALETTEENTRY配列の小さなサブセットだけを変更する。 それらのエントリだけを IDirectDrawPalette::SetEntriesに渡すのである。そのような小さいサブセットをリセットする場合は、 PC_NOCOLLAPSEと PC_RESERVED フラグでマークされたエントリだけをリセットしなくてはならない。他のエントリをアニメーションしようとすると予期しない結果を招くことになり、好ましくない。

次の例は、非排他的モードのパレットアニメーションを示している。

LPDIRECTDRAW        lpDD;        // あらかじめ初期化されている

PALETTEENTRY pPaletteEntry[256]; // あらかじめ初期化されている

LPDIRECTDRAWPALETTE lpDDPal;     // あらかじめ初期化されている

int                 index;

HRESULT             ddrval;

PALETTEENTRY        temp;

// いくつかのエントリをアニメーションする。はじめの16の利用できる

// エントリを循環させる。これによってアニメーションが行われる

temp = pPaletteEntry[10];

for (index = 10; index < 25; index ++)

{

    pPaletteEntry[index] = pPaletteEntry[index+1];

}

pPaletteEntry[25] = temp;

// 値を設定する。パレット・エントリ構造体全体へのポインタではなく、

// 変更されたエントリだけへのポインタを渡さなければならない

ddrval = lpDDPal->SetEntries(

    0,                      // フラグはゼロでなければならない

    10,                     // 最初のエントリ

    16,                     // エントリ数

    & (pPaletteEntry[10])); // データが得られるところ


IDirectDrawSurface2インターフェイス

以下のトピックでは、 IDirectDrawSurface2 インターフェイスについて説明する。

IDirectDrawSurface2

IDirectDrawSurface2で何が新しくなったか?

サーフェスの作成

フレーム・バッファのアクセス

フリッピング・サーフェスとGDIフレーム・レート

サーフェスの消失

色変換とフォーマット変換

カラー・キーイング

オーバーレイZオーダー

オフスクリーン・サーフェスのための複数パレット

ブロック転送とシステム・メモリ・サーフェス


DirectDrawSurfaceオブジェクト

DirectDrawSurfaceオブジェクトは2D部分を表す。このデータはディスプレイ・ハードウェアが理解できる形態となっており、またそのハードウェアはDirectDrawSurfaceオブジェクト を作成する DirectDrawオブジェクトによって表現されている。 DirectDrawSurfaceオブジェクトは、 IDirectDraw2::CreateSurface メソッドを使って作成する。 DirectDrawSurfaceオブジェクトは通常、不要な場合であってもディスプレイ・カードのディスプレイ・メモリに常駐している。 DirectDrawオブジェクトは、DirectDrawSurfaceオブジェクトの作成中、特別に指示されないかぎり、 要求された機能で最高のパフォーマンスが得られる場所にDirectDrawSurfaceオブジェクトを置く。

DirectDrawSurfaceオブジェクトは、ディスプレイ・カードの持つ特化されたプロセッサを有効に利用でき、タスクをより高速に行うばかりでなく、並行してシステムのCPUにタスクを実行させる。

DirectDrawSurfaceオブジェクトは、Windowsのディスプレイ・システムの他のコンポーネントを認識し、またそれらと統合されている。 DirectDrawSurfaceオブジェクトが表現するサーフェス・メモリにGDI 関数が書きこみできるようにするWindows GDIデバイス・コンテキストへのハンドル (HDC)を、DirectDrawSurfaceオブジェクトは作成することが可能である。 GDIは、これらのHDCをメモリ・デバイス・コンテキストとして認識するが、ハードウェア・アクセラレータは通常、ディスプレイ・メモリ上にある場合HDCに対して有効となる。


IDirectDrawSurface2で何が新しくなったか?

DirectXが使うCOMモデルは、新しいインターフェイスの提供により新機能が追加される。 IDirectDrawSurface2 インターフェイスは、  IDirectDrawSurface インターフェイスを代替するものである。この新しいインターフェイスはIDirectDraw::QueryInterfaceメソッドを使って得ることができる。 次に例を示す。

LPDIRECTDRAWSURFACE  lpSurf;

LPDIRECTDRAWSURFACE2 lpSurf2;

// サーフェスの作成.

memset(&ddsd, 0, sizeof(ddsd));

ddsd.dwSize = sizeof(ddsd);

ddsd.dwFlags = DDSD_CAPS | DDSD_WIDTH | DDSD_HEIGHT;

ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN |

    DDSCAPS_SYSTEMMEMORY;

ddsd.dwWidth = 10;

ddsd.dwHeight = 10;

ddrval = lpDD2->CreateSurface(&ddsd, &lpSurf,

    NULL);

if(ddrval != DD_OK)

    return;

ddrval = lpSurf->QueryInterface(

    IID_IDirectDrawSurface2, (LPVOID *)&lpSurf2);

if(ddrval != DD_OK)

    return;

ddrval = lpSurf2->PageLock(0);

if(ddrval != DD_OK)

    return;

ddrval = lpSurf2->PageUnlock(0);

if(ddrval != DD_OK)

    return;

IDirectDrawSurface2 インターフェイスは、３つの新しいメソッド（ IDirectDrawSurface2::GetDDInterface、 IDirectDrawSurface2::PageLock、IDirectDrawSurface2::PageUnlock）を始め、 IDirectDrawSurface インターフェイスで提供されるすべてのメソッドを含んでいる。


サーフェスの作成

DirectDrawSurfaceオブジェクトは、サーフェス（ピクセルメモリ）を表現する。サーフェスは通常ディスプレイ・メモリに常駐しているが、ディスプレイ・メモリが消費された場合や明示的にリクエストされた場合、システム・メモリにも存在することが可能である。ハードウェアが要求された能力をサポートできない場合やリソースが他のDirectDrawSurfaceオブジェクトにあらかじめ割り当てられていた場合は、 IDirectDraw2::CreateSurfaceの処理は失敗する。

IDirectDraw2::CreateSurface メソッドは通常、ひとつのDirectDrawSurfaceオブジェクトを作成する。 DDSCAPS 構造体のdwCapsメンバのDDSCAPS_FLIP フラグがセットされている場合、 IDirectDraw2::CreateSurface メソッドはいくつかのDirectDrawSurfaceオブジェクトを作成する。それらはまとめて複合サーフェスと呼ばれ、また追加して作成されたサーフェスは暗示的サーフェスと呼ばれる。暗示的サーフェスはデタッチすることができない。詳細は、 IDirectDrawSurface2::DeleteAttachedSurfaceを参照すること。

また、プライマリ・サーフェスより広くディスプレイ・メモリ・サーフェスを取ることはできない。

以下は、有効なサーフェス作成のシナリオ例である。

シナリオ 1

プライマリ・サーフェスは、現在ユーザに見えているサーフェスである。プライマリ・サーフェスを作成するときには、 GDIが使用している既存のサーフェスにアクセスするため、DirectDrawSurfaceオブジェクト を作成する。したがって、 DDSURFACEDESC 構造体の dwHeightメンバ やdwWidthメンバの値をサーフェスの他のタイプすべてが要求している間は、現在のサーフェスと同じ次元であるとわかっていたとしても、プライマリ・サーフェスはその値を指定してはならない。

そうしてプライマリ・サーフェス作成に関係するDDSURFACEDESC 構造体 (以下のddsd) のメンバが書きこまれる。

DDSURFACEDESC ddsd;

ddsd.dwSize = sizeof(ddsd);

// どのメンバが有効かDirectDrawに知らせる

ddsd.dwFlags = DDSD_CAPS;

// プライマリ・サーフェスをリクエスト

ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;

シナリオ 2

ブロック転送ハードウェアが構成するビットマップのキャッシュに使われる単純なオフスクリーン・サーフェスを作成してみる。 プライマリ・サーフェス以外のすべてのサーフェスでは、 高さと幅を決める必要がある。するとオフスクリーン・サーフェス作成に関係する DDSURFACEDESC 構造体 (ddsd below)のメンバが書きこまれる。

DDSURFACEDESC ddsd;

ddsd.dwSize = sizeof(ddsd);

// どのメンバが有効かDirectDrawに知らせる

ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH;

// 簡単なオフスクリーン・サーフェスを要求する。

// サイズは100×100ピクセルである。

ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;

dwHeight = 100;

dwWidth = 100;

DirectDrawは、このサーフェスをディスプレイ・メモリに作成する。しかしディスプレイ・メモリに入りきらない場合には、サーフェスはシステム・メモリに作成される。 このときDDSCAPS 構造体のdwCapsメンバ には、サーフェスをシステム・メモリで作成しなければならない場合にはDDSCAPS_SYSTEMMEMORYフラグを、ディスプレイ・メモリで作成しなければならない場合にはDDSCAPS_VIDEOMEMORY フラグを、それぞれ使用する。指定した場所にサーフェスを作成できない場合は、エラーが返される。

DirectDrawも複合サーフェスを作成することができる。複合サーフェスは、 IDirectDraw2::CreateSurface メソッドを一度呼び出すことで作成されるサーフェスのセットである。 IDirectDraw2::CreateSurfaceの呼び出しでDDSCAPS_COMPLEX フラグがセットされている場合、指定した明示的サーフェスの他にひとつ以上の暗示的サーフェスがDirectDrawによって作成される。また、複合サーフェスは、ひとつのサーフェスとして管理される。つまり IDirectDraw::Release メソッドの一度の呼び出しで、構造体のすべてのサーフェスが解放され、 IDirectDrawSurface2::Restoreメソッドの一度の呼び出しでそれらがリストアされるのである。

シナリオ 3

最も有用な複合サーフェスのひとつは、プライマリ・サーフェスとサーフェス・フリッピング環境を形成するひとつ以上のバック・バッファを持つものである。 複合サーフェス作成と関係するDDSURFACEDESC 構造体 (以下のddsd)のメンバは、バック・バッファをひとつ持つフリッピング・サーフェスを記述するために書きこまれる。

DDSURFACEDESC ddsd;

ddsd.dwSize = sizeof(ddsd);

// どのメンバが有効かDirectDrawに知らせる

ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;

// ひとつのバック・バッファとともにプライマリ・サーフェスを要求する

//

ddsd.ddsCaps.dwCaps = DDSCAPS_COMPLEX | DDSCAPS_FLIP |

DDSCAPS_PRIMARYSURFACE;

ddsd.dwBackBufferCount = 1;

これらは、ダブルバッファ・フリッピング環境を構築する。 IDirectDrawSurface2::Flipメソッドを一度呼び出すことで、プライマリ・サーフェスのサーフェス・メモリとバック・バッファとを交換するのである。 DDSURFACEDESC 構造体の BackBufferCountメンバを2に指定すれば2個のバック・バッファが作成され、 IDirectDrawSurface2::Flipを呼び出すごとにトリプルバッファ・フリッピング環境が提供されて3つの円形パターンのように切り替えられる。


フレーム・バッファのアクセス

DirectDrawアーキテクチャでは、DirectDrawSurfaceオブジェクトがサーフェス・メモリを表す。アプリケーションは IDirectDrawSurface2::Lock メソッドを使ってサーフェス・メモリを直接アクセスすることが可能である。アプリケーションはアクセスを要するサーフェス上の矩形をRECT 構造体で指定し、 IDirectDrawSurface2::Lock メソッドを呼び出す。 RECT 構造体をNULLにしてIDirectDrawSurface2::Lockを呼び出す場合、サーフェス・メモリのすべての部分に排他的アクセスを要求するという意味になる。このメソッドは、サーフェス・メモリへのアクセスをするためにアプリケーションが必要な情報をDDSURFACEDESC 構造体に書きこむ。この情報は、プライマリ・サーフェスとピクセル・フォーマットが異なる場合、サーフェスのピッチ（またはストライド）とピクセル・フォーマットを含んでいる。アプリケーションが、サーフェス・メモリとともに終了した場合、サーフェス・メモリは、 IDirectDrawSurface2::Unlockメソッドを用いて 解放することができる。

次のリストは、 DirectDrawSurfaceオブジェクトを直接レンダリングするときの、よくある問題を回避するためのヒントである。

一定のディスプレイ・ピッチを前提としてはならない。つねにIDirectDrawSurface2::Lock メソッドが返すピッチ情報を調べること。ピッチは、サーフェス・メモリの場所、ディスプレイ・カードのタイプ、 DirectDrawドライバのバージョンといったさまざまな理由から変化する。

 	IDirectDrawSurface2::Lockの呼び出しとIDirectDrawSurface2::Unlock メソッドの間のやり取りを制限すること。サーフェス・メモリのアクセス取得を安全に行うため、 IDirectDrawSurface2::Lock メソッドはWIN16のロックを保持しており、IDirectDrawSurface2::GetDC メソッドは暗黙的にIDirectDrawSurface2::Lockを呼び出す。 WIN16ロックは、 IDirectDrawSurface2::Lockと IDirectDrawSurface2::Unlockの間も GDIとUSERのアクセスをIDirectDrawSurface2::GetDCと IDirectDrawSurface2::ReleaseDCの間と同じように制限する 。

ディスプレイ・メモリを連続させてコピーすること。 バンク・スイッチ・メモリを使ったディスプレイ・カードのための仮想フラット・フレーム・バッファを実装するために、Windows 95はページ・フォールト・ハンドラ Vflatd.386を使う。 このハンドラによって、これらのディスプレイ・デバイスは DirectDrawに連続したフレームバッファを渡すことができる。分断したディスプレイ・メモリへコピーすると、コピーがメモリバンクにわたった場合に、システムが一時停止を起こす可能性がある。


フリッピング・サーフェス とGDIフレーム・レート

 DirectDrawのすべてのサーフェスがフリッピング・サーフェスとして利用できる。 フリッピング・サーフェスは、フロント・バッファとバック・バッファ間でスワップされるメモリの任意の部分である。 フリッピング・サーフェスとしてDirectDrawサーフェスを構築することは、従来の限られたページフリッピングの考え方に比べ多くの利点がある。

アプリケーションがフリッピング操作の要求にIDirectDrawSurface2::Flipメソッドを使うとき、フリッピングされるDirectDrawSurfaceオブジェクトと関連づけられたサーフェス・メモリ領域は切り替えられる。フリッピングされるDirectDrawSurfaceオブジェクトにアタッチされたサーフェスには影響しない。たとえばダブルバッファの状態では、バック・バッファに描画するアプリケーションはつねに同じDirectDrawSurfaceオブジェクトを使用する。 IDirectDrawSurface2::Flipがリクエストされたとき、オブジェクト下のサーフェス・メモリは、単にフロント・バッファへ切り替えられる。

フロント・バッファが可視であれば、それはプライマリ・サーフェスであるかあるいは現在可視のオーバーレイであるため、バック・バッファを対象とするIDirectDrawSurface2::LockまたはIDirectDrawSurface2::Bltメソッドを連続して呼び出すと、次の垂直方向のリフレッシュが起こるまでの間失敗し、 DDERR_WASSTILLDRAWINGを返す。これは、フロント・バッファの以前のメモリが、バック・バッファにもうアタッチされていないにもかかわらず、なおハードウェアにより物理ディスプレイに描画され続けるために起こる。この状態は、次の垂直方向のリフレッシュ中に消滅する。物理ディスプレイを更新するハードウェアが、リフレッシュごとにディスプレイ・メモリの配置を読み込み直しているからである。

このような物理的な原因から、可視サーフェス上のDirectDrawSurface2::Flip メソッド呼び出しは非同期コマンドとなる。ゲームを作るときは、メソッドが呼ばれた後でゲームのすべての不可視要素を実行すべきである。たとえば、入力やオーディオ、ゲームのプレイ、そしてシステム・メモリ描画操作が完了してから、可視バック・バッファへのアクセス取得を要する描画タスクをはじめることができる。

アプリケーションがウィンドウで動く必要があり、なおフリッピング環境を要するなら、フリッピングオーバーレイ・サーフェスの作成を試みる。ハードウェアがオーバーレイをサポートしていなくても、ページをフリッピングするプライマリ・サーフェスを作成することができる。 サーフェスがプライマリになろうとしているときにGDIがそのサーフェスについて情報を持っていなければ、GDIが書きこんでいるプライマリ・サーフェスの中身を可視になろうとしているバッファへブロック転送することができる。ブロック転送は非同期に実行されるため、このタスクは時間がかかるとしてもほんのわずかである。しかし、 ページがフリッピングされるウィンドウのサイズとスクリーン解像度に依存するブロック転送のバンド幅とをかなり消費する。フレームレートが20fpsを下回らないかぎりは、 GDIが正しく動作しているように見えるであろう。

DirectDrawオブジェクトをインスタンス化する前に、GDIは、自身の表示にディスプレイ・メモリをすでに使っている。プライマリ・サーフェスをインスタンス化するために DirectDrawを呼び出すとき、そのサーフェスのメモリアドレスは、GDIが現在使っているものと同じである。

バック・バッファで複合サーフェスを作成する場合は、GDIは、まずプライマリ・サーフェスのためのディスプレイ・メモリを指す。GDIはDirectDrawより古いため、DirectDrawの動作を知ることができない。したがってGDIは、たとえフリッピングされ不可視バック・バッファになったとしても、このサーフェスを操作し続ける。

多くのアプリケーションは、全スクリーンを覆う大きなウィンドウを作成することから処理を始める。アプリケーションがアクティブで、かつフォーカスを持つかぎり、 GDIはバッファのコピーを書きこまない。GDIがコントロールするものは再描画を必要としないからである。

他のシナリオでは、GDIはオリジナルなサーフェスの情報しか持たず、現在プライマリ・サーフェスなのかバック・バッファなのかという情報を持たないことを思い出してほしい。 GDIスクリーンが不要なら、上述のテクニックが使える。 GDIが必要であれば、次にあげるテクニックを試してみることができる。

1	バック・バッファをふたつ持つプライマリ・サーフェスを作成する。

2	初期プライマリ・サーフェス(GDIサーフェス)を中間バック・バッファにブロック転送する。

   	3 GDIを前の場所に置いて初期コピーを可視化するため、lpDDSurfaceTargetOverride パラメータをNULLにセットしてサーフェスをフリッピングする。

これを行えば、GDIバッファから中間バッファへコピーができ、そのバッファ上でユーザに見せたいものを描画できる。GDIを安全に下方に置いておき、ふたつのバッファ間を往復させることもできる。方法は次の通りである。

pPrimary->Flip(pMiddle);


サーフェスの消失

サーフェス・メモリの部分を表現する DirectDrawSurfaceオブジェクトが必ずしも解放する必要がないにも関わらず、 DirectDrawSurfaceオブジェクトと関連づけられたサーフェス・メモリが解放されることがある。DirectDrawSurfaceオブジェクトがサーフェス・メモリを失った場合、多くのメソッドはDDERR_SURFACELOSTを返し、他のアクションを実行しない。

ディスプレイ・カードのモードが変更されたり、アプリケーションがディスプレイ・カードへの排他的アクセスを受け取りカードに割り当てられたサーフェス・メモリをすべて解放したりした場合、サーフェスは失われる。 IDirectDrawSurface2::Restore メソッド は、失われたサーフェスを再作成しDirectDrawSurfaceオブジェクトへ再接続する。

さらに詳しくは、「モード変更と排他的アクセス」を参照すること。


色変換とフォーマット変換

非RGBサーフェス・フォーマットは、 4文字コード（FOURCCコード)によって記述される。アプリケーションがピクセル・フォーマットをリクエストするために IDirectDrawSurface2::GetPixelFormat メソッドを呼び出す場合、およびサーフェスが非RGBサーフェスである場合、 DDPF_FOURCC フラグがセットされ、 DDPIXELFORMAT 構造体のdwFourCCメンバが有効となる。 もし、 FOURCCコードが YUVフォーマットを表す場合、 DDPF_YUV フラグもセットされ、 dwYUVBitCountとdwYBits、 dwUBits、 dwVBits、dwYUVAlphaBitsメンバがピクセルから情報を引き出すために使われる有効なマスクになる。

RGB フォーマットが存在すると DDPF_RGB フラグがセットされ、 dwRGBBitCount、 dwRBits、dwGBits、 dwBBits、dwRGBAlphaBitsメンバがピクセルから情報を引き出すために使われる有効なマスクになる。非標準RGB フォーマットが記述される場合は、 DDPF_RGB フラグはDDPF_FOURCC フラグと組み合わせてセットできる。

色変換とフォーマット変換中に、アプリケーションに対しFOURCCコードが２セット公開される。FOURCCコードのセットのひとつは、ハードウェアのブロック転送能力をあらわし、もうひとつは、ハードウェアのオーバーレイ能力をあらわす。


カラー・キーイング

DirectDrawでは、ブロック転送とオーバーレイのために転送元・転送先「カラー・キーイング」がサポートされている。 転送元・転送先のどちらにも、このカラー・キー、または色域を指定することができる。

転送元カラー・キーイングは、ブロック転送時にコピーされない色または色域、オーバーレイ時に転送先で不可視の色または色域を指定する。 転送先カラー・キーイングは、ブロック転送時に置き換えられる色または色域、オーバーレイ時に転送先を覆う色または色域を指定する。 転送元カラー・キー はサーフェスから何が読みとれ何が読みとれないか指定する。 転送先カラー・キーは、転送先サーフェスで書いたり覆ったりできるものとできないものとを指定する。転送先サーフェスがカラー・キーを持つと、カラー・キーとマッチしたピクセルだけが転送先サーフェス上で変更、上書きされる。

いくつかのハードウェアは、 YUVピクセル・データのための色域だけをサポートする。 YUVデータは通常はビデオであり、変換中に誤差が起こるので、透過バックグラウンドは単色ではない可能性があるが、本来はピクセル・フォーマットによらず可能なかぎり単一の透過色とするべきである。

カラー・キーは、サーフェスのピクセル・フォーマットで指定される。サーフェスがパレット化されたフォーマットである場合、 カラー・キーは、インデックスまたはインデックス域として指定される。サーフェスのピクセル・フォーマットがYUV フォーマットを記述するFOURCCコードにより指定されている場合、 YUV カラー・キーは、 DDCOLORKEY 構造体.のdwColorSpaceLowValueメンバとdwColorSpaceHighValueメンバ双方の下位3バイトで指定される。最下位バイトはVデータ、２番目はUデータ、最上位バイトはYデータである。 IDirectDrawSurface2::SetColorKey メソッドの dwFlags パラメータは、カラー・キーがオーバーレイまたはブロック転送のどちらで使われるか、転送元なのか転送先なのかを指定する。以下は有効なカラー・キーの例である。

8ビットパレット化モード

// パレット・エントリ26はカラー・キー.

dwColorSpaceLowValue = 26;

dwColorSpaceHighValue = 26;

24ビットトゥルーカラーモード

// 色255,128,128はカラー・キー

dwColorSpaceLowValue = RGBQUAD(255,128,128);

dwColorSpaceHighValue = RGBQUAD(255,128,128);

FourCC YUVモード

// YUVカラー  Yは100と110の間

//  Uまたは Vは50と55の間で透過である

dwColorSpaceLowValue = YUVQUAD(100,50,50);

dwColorSpaceHighValue = YUVQUAD(110,55,55);


オーバレイ Z オーダー
オーバーレイZオーダー

オーバーレイZオーダーは、オーバーレイが互いにクリッピングし合う順番を決定する。これによりDirectDraw下のハードウェア・スプライト・システム実装が可能になる。オーバーレイは、他のスクリーン・コンポーネントすべての上位に位置するものと仮定される。転送先カラー・キーは、プライマリ・サーフェスのビットにだけ影響されるべきで、他のオーバーレイに遮られたオーバーレイに影響されるべきでない。転送元カラー・キーは、Zオーダ指定の有無によらずオーバーレイに作用する。指定されたZオーダを持たないオーバーレイは、 プライマリ・サーフェス上の同じ領域にオーバーレイされると、予期しない振る舞いをする。Zオーダーの指定されていないオーバーレイは、 Zオーダー0とみなされる。Zオーダの範囲は、プライマリ・サーフェス最上位である0から、観測者に最も近い位置の40億までである。Zオーダ2のオーバーレイは、Zオーダ1のオーバーレイを覆い隠す。同じZオーダを持つオーバーレイは存在しない。


オフスクリーン・サーフェスのための複数パレット

DirectDrawにより、オフスクリーン・サーフェスにアタッチできるパレットを複数作成することができる。このときオフスクリーン・サーフェスは、プライマリ・サーフェスとパレットを共有しない。プライマリ・サーフェスのものと異なったピクセル・フォーマットを持つオフスクリーン・サーフェスを作成する場合は、ハードウェアがそれを使用できることが前提である。たとえば、プライマリ・サーフェスが16ビット・カラーモードのときパレット化オフスクリーン・サーフェスを作成する場合、ブロック転送ハードウェアは操作中にパレット化サーフェスをトゥルーカラーへ変換することができるものと仮定する。

DirectDrawでは、256色を表示できる標準8ビットのパレット化サーフェスと、それぞれ16色を表示できる２種類の4ビットパレット化サーフェスとを作成することができる。4ビットパレット化サーフェスの第一のタイプはトゥルーカラーのカラー・テーブルでインデックスされ、第二のタイプはプライマリ・サーフェスのインデックス・カラー・テーブルにインデックスされる。この第二のタイプは、第一のタイプの半分のデータ量で済み、スプライトを格納するために間接的に用いられたりする。

これらのサーフェスが作成されるときには、ブロック転送ハードウェアは操作中にパレットの置換が可能でなければならない。したがって、パレット化サーフェスからパレット化サーフェスへブロック転送操作が行われると、そのパレットは無視される。パレットのデコードは、トゥルーカラー・サーフェスの場合と、4ビットパレットが8ビットパレット・インデックスへのインデックスである場合とでだけ行われる。他の場合では、インデックス・パレットは転送先のパレットになる。

パレット化サーフェスのラスタ操作は無視される。またアタッチされたパレットの変更操作はきわめて高速である。これらパレット化されたサーフェスの３つすべては、3Dアクセラレーション・ハードウェアのテクスチャとしてサポートされなくてはならない。

オフスクリーン・プレーン・サーフェスのピクセル・フォーマットについてのさらに詳しい情報は、「オフスクリーン・サーフェスのフォーマット」を参照すること。


ブロック転送とシステム・メモリ・サーフェス

システム・メモリから、またはシステム・メモリへ効率的なブロック転送を可能にするDMAハードウェアをもつディスプレイ・カードがある。ドライバは、この機能をDDCAPS 構造体を通して知らせる。この構造体は次の12の新しいメンバから構成される。

dwSVBCaps	dwVSBCaps	dwSSBCaps
dwSVBCKeyCaps	dwVSBCKeyCaps	dwSSBCKeyCaps
dwSVBFXCaps	dwVSBFXCaps	dwSSBFXCaps
dwSVBRops	dwVSBRops	dwSSBRops
略語SVBは、システム・メモリからディスプレイ・メモリへのブロック転送に関係する能力値を示す。 VSBは、ディスプレイ・メモリからシステム・メモリへのブロック転送に関係する能力値を示す。SSBは、システム・メモリからシステム・メモリへのブロック転送に関係する能力値を示す。

dwSVBCapsメンバは、dwCapsメンバに対応する。ただし、システム・メモリからディスプレイメモリへのブロック転送に関係するディスプレイ・ドライバの能力を記述する場合を除く。 同様に、dwSVBCKeyCapsメンバは dwCKeyCapsメンバに対応し、dwSVBFXCapsメンバはdwFXCapsメンバに対応する。 dwSVBRopsメンバ 配列は、このタイプのブロック転送でドライバーがサポートするラスタ操作を記述する。

これらのメンバーは、 dwCapsで DDCAPS_CANBLTSYSMEM フラグがセットされている場合にのみ有効である。このフラグがセットされていると、システム・メモリから、またはシステム・メモリへ、ブロック転送できる能力がドライバーにあることを示している。

ハードウェア・ブロック転送によって使われているシステム・メモリ・サーフェスがロックされていない場合、 DirectDrawは自動的に、サーフェスに対し IDirectDrawSurface2::PageLock メソッドを呼び出す。


DirectDraw チュートリアル

この節は、一連のチュートリアルから構成される。それぞれステップごとに、 簡単なDirectDraw アプリケーションを実現するための方法を紹介する。これらのチュートリアルは、SDKによって提供される DirectDrawサンプルファイルの多くを使っている。サンプルの多くは DDEXという文字を先頭に名付けられている。これらのサンプルでは、 DirectDrawをどのようにしてセットアップするか、簡単なタスクを実現するために DirectDraw メソッドをどのように使うかを紹介する。

チュートリアル 1: DirectDrawの基礎(DDEX1)

チュートリアル 2: ビットマップをバック・バッファに転送(DDEX2)

チュートリアル 3: オフスクリーン・サーフェスからのブロック転送(DDEX3)

チュートリアル 4: カラー・キーとビットマップ・アニメーション(DDEX4)

チュートリアル 5: パレットの動的変更(DDEX5)

これらのチュートリアルのサンプルは、 IDirectDrawと IDirectDrawSurface インターフェイスの古いバージョンを使っている。 DirectX 3 インターフェイス�IDirectDraw2と IDirectDrawSurface2�を使うこれらの例をアップデートする場合は、両方のインターフェイスに QueryInterfaceを加えること。これについては、「IDirectDraw2で何が新しくなったか?」と「IDirectDrawSurface2で何が新しくなったか?」で説明されている。さらにIDirectDraw2または IDirectDrawSurface2によって、アップデートされたメソッドに割り当てられたパラメータを変更する必要がある。

Note

これらのチュートリアルの DDEXサンプルファイルC++で書かれている。 Cコンパイラを使っている場合、コンパイラを通すためにファイルを適宜変更しなければならない。Cコンパイラに通すためには、少なくともvtableインターフェイス・メソッドについてのthisポインタを加える必要がある。さらに詳しい情報は、「CでのCOMオブジェクトへのアクセス」を参照すること。


チュートリアル 1: DirectDrawの基礎

DirectDrawを使うには、まず始めに、 コンピュータのディスプレイ・アダプタを表現するDirectDrawオブジェクトのインスタンスを作成しなければならない。そして、そのオブジェクトを操作するためのインターフェイスメソッドを使用する。加えて、ゲームをグラフィックサーフェス上に表示するためには、 DirectDrawSurfaceオブジェクトのインスタンスを一つかそれ以上作成する必要がある。 これを説明するために、SDKに含まれるDDEX1のサンプルを次のステップで紹介する。

Step 1: DirectDrawオブジェクトの作成

Step 2: アプリケーションの振る舞いの決定

Step 3: ディスプレイ・モードの変更

Step 4: フリッピング・サーフェスの作成

Step 5: サーフェス へのレンダリング

Step 6: サーフェスへの書きこみ

Step 7: フリッピング・サーフェス

Step 8: DirectDrawオブジェクトの割り当て削除


Step 1: DirectDrawオブジェクトの作成

DirectDrawオブジェクトのインスタンスを作成するには、 DDEX1プログラムのdoInit 関数内で示されるように、DirectDrawCreate 関数を使う。DirectDrawCreateは3つのパラメータを必要とする。 第一のパラメータには、ディスプレイ・デバイスを表現するグローバル・ユニーク識別子 (GUID)をとる。GUIDはほとんどの場合NULLにセットされるが、これはDirectDrawがシステムのデフォルトのディスプレイ・デバイスを使うことを意味している。 第二のパラメータは、作成されたDirectDrawオブジェクトのロケーションを識別するポインタのアドレスを持つ。第三のパラメータはつねにNULLにセットされているが、これは将来の拡張に備えるためである。

次の例は、 DirectDrawオブジェクトの作成方法と、その処理が成功したかどうかを判断する方法を示している。

ddrval = DirectDrawCreate(NULL, &lpDD, NULL);

if(ddrval == DD_OK)

{

    // lpDDは有効なDirectDrawオブジェクトである

}

else

{

    //  DirectDrawオブジェクトは作成できなかった

}


Step 2: アプリケーションの振る舞いの決定

ディスプレイの解像度を変更する前には、最低限IDirectDraw2::SetCooperativeLevel メソッドのパラメータdwFlags にあるDDSCL_EXCLUSIVEと DDSCL_FULLSCREEN フラグを指定しなければならない。これにより、アプリケーションがディスプレイ・デバイスを完全にコントロールできるようになり、他アプリケーションはディスプレイ・デバイスを共有できなくなる。加えて DDSCL_FULLSCREEN フラグは、アプリケーションを排他的（フルスクリーン）モードにセットする。するとアプリケーションはデスクトップいっぱいに広がり、またそのアプリケーションだけがスクリーンに書きこむことができるようになる。その状態でも、デスクトップはまだ利用可能である（たとえば、排他的モードで動くアプリケーションにおいてデスクトップを見るには 、DDEX1をスタートさせ、 ALT + TABを押せばよい）。

次の例では IDirectDraw2::SetCooperativeLevel の使い方を説明している。

HRESULT      ddrval;

LPDIRECTDRAW lpDD;     // DirectDrawCreateによってすでに作成されている

ddrval = lpDD->SetCooperativeLevel(hwnd, DDSCL_EXCLUSIVE |

    DDSCL_FULLSCREEN);

if(ddrval == DD_OK)

{

    // 排他的モードは成功した.

}

else

{

    // 排他的モードは失敗した

    // しかし、アプリケーションはまだ動いている

}

 IDirectDraw2::SetCooperativeLevelが DD_OKを返さない場合でも、アプリケーションは続行できる。しかし、アプリケーションが排他的モードになければ、要求されるパフォーマンスを実現できない可能性がある。この場合、続行するかどうかユーザに決定させるメッセージを表示したほうが良いだろう。

IDirectDraw2::SetCooperativeLevelを使う場合、アプリケーションが異常終了したことをWindowsに知らせるようウィンドウ・ハンドル(HWND) を渡さなければならない。たとえば、一般保護 (GP)違反が起こりGDIがバック・バッファにフリッピングされていると、ユーザは Windowsのスクリーンを取り戻すことができない。これを防ぐため DirectDrawは、そのウィンドウに送られたメッセージをトラップするバックグラウンド・プロセスを提供している。トラップしたメッセージを使い、 DirectDrawはアプリケーションがいつ終了したか決定する。この機能には制限がいくつかある。まずアプリケーションのためのメッセージを取得しているウィンドウ・ハンドルを指定しなければならない。 つまり、ウィンドウをもうひとつ作成する場合、指定するウィンドウは確実にアクティブでなくてはならない。さもないと、GDIから予期しない振る舞いが生じたり、 ALT+TABを押してもレスポンスがなかったりといった問題に遭うことがある。


Step 3: ディスプレイ・モードの変更

アプリケーションの振る舞いをセットした後で、 IDirectDraw2::SetDisplayMode メソッドを使い、ディスプレイの解像度を変更することができる。次の例では、ディスプレイ・モードを 640×480×8 bppにセットする方法を示している。

HRESULT      ddrval;

LPDIRECTDRAW lpDD;  // すでに作成されている

ddrval = lpDD->SetDisplayMode(640, 480, 8);

if(ddrval == DD_OK)

{

    // ディスプレイ・モードの変更は成功した

}

else

{

    // ディスプレイ・モードは変更できなかった

    // モードがサポートされていないか、他のアプリケーションが

    // 排他的モードになっている

}

ディスプレイ・モードをセットするにあたり、ユーザのハードウェアが高解像度をサポートしていないないときにはディスプレイ・アダプタの大多数がサポートしている標準モードにアプリケーションが復帰できることを保証しておかなければならない。たとえば、640×480×8という標準のバックアップ解像度をサポートしているすべてのシステムで動くようアプリケーションを設計するべきである (要求する解像度にディスプレイ・アダプタをセットできなかった場合、IDirectDraw::SetDisplayModeはエラー値 DDERR_INVALIDMODEを返す。 したがって、ディスプレイ・モードをセットしようとする前に、ユーザのディスプレイ・アダプタの特定できるIDirectDraw2::EnumDisplayModesメソッドを使うべきである)。


Step 4: フリッピング・サーフェスの作成

ディスプレイ・モードをセットしたら、アプリケーションで使用するサーフェスを作成しなければならない。DDEX1の例では、排他的（フルスクリーン）モードにセットするためIDirectDraw2::SetCooperativeLevel メソッドを使っているので、サーフェス間でフリッピングするサーフェスを作成することができる。モードをDDSCL_NORMALにセットするためIDirectDraw2::SetCooperativeLevelを使った場合、 サーフェス間でブロック転送するサーフェスしか作成できない。フリッピング・サーフェスを作成するには、次のようなステップで行う。

サーフェス要求の定義

サーフェス作成

サーフェス要求の定義

フリッピング・サーフェスを作成する最初のステップは、 DDSURFACEDESC 構造体のサーフェス要求を定義することである。次の例では、フリッピング・サーフェスを作成するのに必要な、構造体定義とフラグを示している。

// バック・バッファをひとつ持つプライマリ・サーフェスを作成する

ddsd.dwSize = sizeof(ddsd);

ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;

ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE |

    DDSCAPS_FLIP | DDSCAPS_COMPLEX;

ddsd.dwBackBufferCount = 1;

この例では、 dwSizeメンバに DDSURFACEDESC 構造体のサイズをセットする。 これはDirectDraw メソッド呼び出しで有効でないメンバエラーが返ってこないようにするためである（ dwSizeメンバは、 DDSURFACEDESC 構造体の将来の拡張のために用意されたものである）。

dwFlagsメンバは、 DDSURFACEDESC 構造体のどのメンバに有効な情報が返されるか決定する。DDEX1の例では、dwFlagsをセットすることで、DDSCAPS 構造体を使い(DDSD_CAPS)バック・バッファ を作成する(DDSD_BACKBUFFERCOUNT)ことを指定している。

dwCapsメンバは、 DDSCAPS 構造体で使われるフラグを示している。この場合は、プライマリ・サーフェス(DDSCAPS_PRIMARYSURFACE)とフリッピング・サーフェス (DDSCAPS_FLIP)、複合サーフェス (DDSCAPS_COMPLEX)を指定している。

最後に、この例ではバック・バッファをひとつ指定している。バック・バッファは、背景とスプライトが実際に書きこまれる場所である。そしてバック・バッファは、プライマリ・サーフェスにフリッピングされる。 DDEX1の例ではバック・バッファの数は1にセットされているが、 ディスプレイ・メモリが許すかぎりいくつでも作成することができる。バック・バッファに関するさらに詳しい情報は、「トリプル・バッファリング」を参照すること。.

サーフェス・メモリはディスプレイ・メモリにもシステム・メモリにも置くことができる。 DirectDrawは、アプリケーションがディスプレイ・メモリ外で動くときはシステム・メモリを使う (たとえば、1MBのRAMメモリしかないディスプレイ・アダプタ上で、ひとつ以上のバック・バッファを指定するような場合である)。 DDSCAPS 構造体のdwCapsメンバをDDSCAPS_SYSTEMMEMORYまたはDDSCAPS_VIDEOMEMORYに指定することによって、システム・メモリだけを使うかディスプレイ・メモリだけを使うかを指定できる（DDSCAPS_VIDEOMEMORYを指定したにも関わらずサーフェス作成に充分なメモリを利用できない場合は、IDirectDraw2::CreateSurfaceが DDERR_OUTOFVIDEOMEMORYエラーが返る）。

サーフェスの作成

DDSURFACEDESC 構造体のメンバを埋めたら、 DirectDrawCreate が作成したDirectDrawオブジェクトへのポインタ lpDDとDDSURFACEDESC 構造体とを使って、IDirectDraw2::CreateSurface メソッドを呼び出すことができる。次に例を示す。

ddrval = lpDD->CreateSurface(&ddsd, &lpDDSPrimary, NULL);

if(ddrval == DD_OK)

{

    // 新しいサーフェスを指すlpDDSPrimary

}

else

{

    // サーフェスが作成されなかった

    return FALSE;

}

 lpDDSPrimary パラメータは、呼び出しが成功した場合、 IDirectDraw::CreateSurfaceが返すプライマリ・サーフェスへのポインタとなる。

プライマリ・サーフェスへのポインタを取得したら、次の例で示す通り、バック・バッファのポインタを取得するために IDirectDrawSurface2::GetAttachedSurface メソッドを使用できる。

ddscaps.dwCaps = DDSCAPS_BACKBUFFER;

ddrval = lpDDSPrimary->GetAttachedSurface(&ddcaps, &lpDDSBack);

if(ddrval == DD_OK)

{

    // lpDDSBackは、バック・バッファへのポインタ

}

else

{

    return FALSE;

}

サーフェスのプライマリ・サーフェスのアドレスを提供し、DDSCAPS_BACKBUFFER フラグで能力値をセットすることによって、  IDirectDrawSurface2::GetAttachedSurfaceの呼び出しが成功した場合、 lpDDSBack パラメータは バック・バッファへのポインタとなる。


Step 5:  サーフェスへのレンダリング

プライマリ・サーフェスとバック・バッファが作成された後、 DDEX1サンプルでは、標準の Windows GDI 関数を使いプライマリ・サーフェスとバック・バッファ・サーフェス上でいくつかのテキストをレンダリングしている。次の例で示す通りである。

if (lpDDSPrimary->GetDC(&hdc) == DD_OK)

{

    SetBkColor(hdc, RGB(0, 0, 255));

    SetTextColor(hdc, RGB(255, 255, 0));

    TextOut(hdc, 0, 0, szFrontMsg, lstrlen(szFrontMsg));

    lpDDSPrimary->ReleaseDC(hdc);

}

if (lpDDSBack->GetDC(&hdc) == DD_OK)

{

    SetBkColor(hdc, RGB(0, 0, 255));

    SetTextColor(hdc, RGB(255, 255, 0));

    TextOut(hdc, 0, 0, szBackMsg, lstrlen(szBackMsg));

    lpDDSBack->ReleaseDC(hdc);

}

例では、デバイス・コンテキストへのハンドルを取得するために IDirectDrawSurface2::GetDC メソッドを使い、内部でサーフェスをロックしている。デバイス・コンテキストへのハンドルを必要とするWindows関数を使わないのなら、バック・バッファをロックまたはロック解除するために IDirectDrawSurface2::Lock and IDirectDrawSurface2::Unlockとメソッドを使うことができる。

サーフェス・メモリ（サーフェスの全体、もしくは一部）をロックすることは、アプリケーションとシステム・ブロック転送とが同時にサーフェス・メモリへアクセスできないことを意味している。これは、アプリケーションがサーフェス・メモリへ書きこみ中にエラーが発生しないようにするためである。さらに、アプリケーションは、サーフェス・メモリがロック解除されるまでページ・フリッピングできない。

サーフェスがロックされた後、サンプルでは、背景色をセットするために標準のWindows GDI 関数 SetBkColorを使い、背景に置くテキストの色を選ぶためにSetTextColorを、サーフェス上にテキストと背景色を書くためにTextOutを使っている。

サンプルでは、バッファにテキストを書き込んだ後、IDirectDrawSurface2::ReleaseDC メソッドを使いサーフェスをロック解除している。アプリケーションがバック・バッファへの書き込みを終了したときは常に、 IDirectDrawSurface2::ReleaseDCまたは IDirectDrawSurface2::Unlockのどちらかを場合に応じて呼び出さなければならない。アプリケーションは、サーフェスをロック解除するまでフリッピングできない。

一般に、書き込みは表示されるプライマリ・サーフェスへフリッピングするバック・バッファに対して行う。 DDEX1の場合、最初のフリッピングの前に有意な遅延が生じるため、 DDEX1ではサーフェス表示前の遅れを避けるため初期化関数内でプライマリバッファに書きこみをする。このチュートリアルの次のステップを見ればわかるように、 DDEX1サンプルでは WM_TIMERの間、バック・バッファにだけ書きこみを行う。プライマリ・サーフェスに書きこみが必要なのは、初期化関数かタイトルページくらいだと思われる。

Note

IDirectDrawSurface2::Unlockでサーフェスをロック解除した後、サーフェス・メモリへのポインタは無効となる。 サーフェス・メモリへの有効なポインタを得るには、IDirectDrawSurface2::Lockを再び使わなければならない。


Step 6: サーフェスへの書き込み
Step 6: サーフェスへの書きこみ

DDEX1の WM_TIMERメッセージの前半では、次の例で示す通り専らバック・バッファへの書きこみを行う。

case WM_TIMER:

    // サーフェスをフリッピング

    if(bActive)

    {

        if (lpDDSBack->GetDC(&hdc) == DD_OK)

        {

            SetBkColor(hdc, RGB(0, 0, 255));

            SetTextColor(hdc, RGB(255, 255, 0));

            if(phase)

            {

                TextOut(hdc, 0, 0, szFrontMsg, lstrlen(szFrontMsg));

                phase = 0;

            }

            else

            {

                TextOut(hdc, 0, 0, szBackMsg, lstrlen(szBackMsg));

                phase = 1;

            }

            lpDDSBack->ReleaseDC(hdc);

        }

IDirectDrawSurface2::GetDC メソッドを呼び出す行では、書きこみの準備でバック・バッファをロックする。 SetBkColorと SetTextColor 関数によって、背景とテキストの色を指定する。

続いて、phase 変数は、プライマリ・バッファ・メッセージまたはバック・バッファ・メッセージのどちらが書きこまれるべきかを決定する。変数phaseが1であれば、プライマリ・サーフェス・メッセージが書きこまれ、 変数phaseは0にセットされる。変数phaseが0に等しければ、バック・バッファ・メッセージが書きこまれ、変数phaseは1にセットされる。しかし、どちらの場合にもメッセージはバック・バッファに書きこまれるということに注意すること。

メッセージがバック・バッファに書かれた後、バック・バッファは、 IDirectDrawSurface2::ReleaseDC メソッドによってロック解除される。


Step 7: フリッピング・サーフェス

サーフェス・メモリがロック解除された後で、バック・バッファをプライマリ・サーフェスにフリッピングするIDirectDrawSurface2::Flip メソッドを使用できるようになる。次の例で示す通りである。

while(1)

{

    HRESULT ddrval;

    ddrval = lpDDSPrimary->Flip(NULL, 0);

    if(ddrval == DD_OK)

    {

        break;

    }

    if(ddrval == DDERR_SURFACELOST)

    {

        ddrval = lpDDSPrimary->Restore();

        if(ddrval != DD_OK)

        {

            break;

        }

    }

    if(ddrval != DDERR_WASSTILLDRAWING)

    {

        break;

    }

}

例では、 lpDDSPrimaryはプライマリ・サーフェスとそれに関連づけられたバック・バッファとを示している。 IDirectDrawSurface2::Flipが呼ばれると、フロント・サーフェスとバック・サーフェスが交換される（サーフェスへのポインタが変更されるだけで、実際にデータが移動するわけではない）。フリッピングが成功し DD_OKが返されると、アプリケーションはwhileループから抜ける。

フリッピングが返値DDERR_SURFACELOSTを返す場合、IDirectDrawSurface2::Restore メソッドによってサーフェスのリストアが試みられる。リストアが成功すると、アプリケーションはループに戻り IDirectDrawSurface2::Flipの呼び出しを再び試みる。リストアが失敗すると、アプリケーションはwhileループを抜けて、エラーを返す。

Note

IDirectDrawSurface2::Flipを呼び出す場合、フリッピングはすぐには完了せず、次の垂直帰線期間に行われる。たとえば前のフリッピングが終わっていないとき、 IDirectDrawSurface2::Flipは DDERR_WASSTILLDRAWINGを返す。例では、 IDirectDrawSurface2::FlipはDD_OKを返すまでループし続ける。


Step 8: DirectDrawオブジェクトの割り当て削除

F12キーを押すと、 DDEX1 アプリケーションは終了前に WM_DESTROY メッセージを処理する。次に示す通り、このメッセージはすべてのIUnknown::Release関数を含むfiniObjects 関数を呼び出す。

static void finiObjects(void)

{

    if(lpDD != NULL)

    {

        if(lpDDSPrimary != NULL)

        {

            lpDDSPrimary->Release();

            lpDDSPrimary = NULL;

        }

        lpDD->Release();

        lpDD = NULL;

    }

} // finiObjects

アプリケーションは、DirectDrawオブジェクトへのポインタ(lpDD)とDirectDrawSurfaceオブジェクトへのポインタ(lpDDSPrimary)がNULLでないかどうかチェックする。 そしてDDEX1は、 DirectDrawSurfaceオブジェクトの参照カウントを1ずつ減らすため IDirectDrawSurface2::Release メソッドを呼び出す。参照カウントが0になると、 DirectDrawSurfaceは解放される。 DirectDrawSurfaceポインタは、NULLを値にセットして破棄される。次に、 DirectDrawオブジェクトの参照カウントを0まで減らすために、 IDirectDraw::Releaseを呼び出す。 DirectDrawオブジェクトの割り当ては解除される。このポインタもまた、 NULLを値にセットして破棄される。


チュートリアル 2: ビットマップをバック・バッファに転送

このチュートリアル (DDEX2)で解説するサンプルは、チュートリアル1で解説した DDEX1 を拡張したものである。 DDEX2は、ビットマップファイルをバック・バッファへロードする機能を含んでいる。この新しい機能を、次のようなステップで説明する。

Step 1: パレットの作成

Step 2: パレットの設定

Step 3: バック・バッファへのビットマップのロード

Step 4: サーフェス・フリッピング

DDEX1と同様、 doInitは DDEX2アプリケーションの初期化関数である。 DirectDraw初期化コードは、 DDEX1とDDEX2とではいささか異なって見えるが、本質的には同じであり、次のセクションが異なるだけである。

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL)

    goto error;

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval != DD_OK)

    goto error;

// ビットマップをバック・バッファにロード

ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval != DD_OK)

    goto error;


Step 1: パレットの作成

DDEX2サンプルでは、次のコードを使って構造体へパレットをロードする。

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL)

    goto error;

DDLoadPaletteは、共通DirectDraw 関数であり、\Sdk\Samples\Misc\Ddutil.cppにある。 DirectDrawサンプルファイルの大部分がこのファイルを使っている。これは、ファイルまたはリソースからビットマップとパレットをロードするための関数群から構成される。 これらの関数は、再利用できるひとつのファイルにまとめられている。残りの DDEX samplesとともにコンパイルするファイル群のリストに Ddutil.cppが含まれていることを確認すること。

DDEX2で、DDLoadPalette 関数 は Back.bmpファイルからDirectDrawPaletteオブジェクトを作成する。DDLoadPalette 関数は、パレットを作成するためのファイルまたはリソースが存在するかどうかを判断する。もし存在しなければデフォルトのパレットを作成する。 DDEX2では、ビットマップパレットからパレット情報を抽出し、ポインタ apeが指す構造体に格納する。

そうしてDDEX2は 次の例に示すようにDirectDrawPaletteオブジェクトを作成する。

pdd->CreatePalette(DDPCAPS_8BIT, ape, &ddpal, NULL);

return ddpal;

IDirectDraw2::CreatePaletteメソッドが戻るとき、ddpalパラメータはDirectDrawPaletteオブジェクトを指す。DDLoadPaletteの呼び出しで返されるものである。

ape パラメータは構造体へのポインタで、連続した2、4、16、256エントリのいずれかを含んでいる。 エントリの数は IDirectDraw2::CreatePalette メソッドのdwFlags パラメータに依存する。上の場合、 dwFlags パラメータはDDPCAPS_8BITにセットされ、この構造体に256のエントリがあることを示している。エントリはそれぞれ4バイト（チャネル赤、チャネル緑、チャネル青、フラグ）で構成される。


Step 2:  パレットの設定

パレットを作成した後、 IDirectDrawSurface2::SetPalette メソッドを呼び出すことで、DirectDrawPaletteオブジェクトへのポインタ（ddpal）をプライマリ・サーフェスに渡す。次の例で示す通りである。

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval != DD_OK)

    // SetPalette失敗

IDirectDrawSurface2::SetPaletteを呼び出すことによって、 DirectDrawPaletteオブジェクトは DirectDrawSurfaceオブジェクトに関連づけられる。パレットの変更が必要なときはいつでも新しいパレットを作成しパレットを再設定するだけでよい。（これはサンプルで使われている方法だが、後に説明するとおり他にも方法がある。）


Step 3: バック・バッファへのビットマップのロード

DirectDrawPaletteオブジェクトが DirectDrawSurfaceオブジェクトと関連づけられると、DDEX2は次のコードで Back.bmpビットマップをバック・バッファにロードする。

// バック・バッファにビットマップをロード

ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval != DD_OK)

    // ロードは失敗した

DDReLoadBitmapは、 Ddutil.cppにあるもうひとつの関数である。この関数はファイルまたはリソースからビットマップを既存のDirectDrawサーフェスへロードする。(サーフェスを作成し、ビットマップをそのサーフェスへロードするために DDLoadBitmapを使うことができる。 さらに詳しい情報は、「 チュートリアル 5 :パレットの動的変更」を参照すること。) DDEX2においては、szBackgroundが指す Back.bmpファイルを、 lpDDSBackが指すバック・バッファにロードする。 DDReLoadBitmap 関数はファイルをバック・バッファにコピーし適切なサイズに伸長するために、 DDCopyBitmap 関数を呼び出す。

DDCopyBitmap 関数は、ビットマップをメモリにコピーし、ビットマップのサイズを調べるためにGetObject 関数を使う。そしてビットマップが置かれるバック・バッファのサイズを調べるために次のようにしている。

// サーフェスのサイズを得る

ddsd.dwSize = sizeof(ddsd);

ddsd.dwFlags = DDSD_HEIGHT | DDSD_WIDTH;

pdds->GetSurfaceDesc(&ddsd);

ddsd は、 DDSURFACEDESC 構造体へのポインタである。この構造体は、 DirectDrawサーフェスの現在の記述を格納する。この場合、 DDSURFACEDESCメンバは、 DDSD_HEIGHTと DDSD_WIDTHで示されるサーフェスの高さと幅とを記述する。 IDirectDrawSurface2::GetSurfaceDesc メソッドへの呼び出しは、構造体に適切な値をロードする。 DDEX2では、高さ480、幅640となっている。

DDCopyBitmap 関数は、サーフェスをロックし、次の例で示すようにバック・バッファにあてはまるよう伸長または圧縮してビットマップをコピーする。

if ((hr = pdds->GetDC(&hdc)) == DD_OK)

{

    StretchBlt(hdc, 0, 0, ddsd.dwWidth, ddsd.dwHeight, hdcImage, x, y,

        dx, dy, SRCCOPY);

    pdds->ReleaseDC(hdc);

}


Step 4: サーフェス・フリッピング

DDEX2サンプルでのサーフェスのフリッピングは、本質的に、サーフェスが消失した場合（ DDERR_SURFACELOST）を除いて DDEX1チュートリアルと同じである（「チュートリアル1:  DirectDrawの基礎」を参照すること) 。その場合、サーフェスがリストアされた後、DDReLoadBitmap 関数を使ってビットマップをバック・バッファにロードし直さなければならない。


チュートリアル 3: オフスクリーン・サーフェスからのブロック転送

チュートリアル 2 (DDEX2)のサンプルは、ビットマップを取得してバック・バッファに置き、バック・バッファとプライマリバッファとの間をフリッピングしている。これは、ビットマップを表示するのにあまり現実的な方法ではない。ふたつのビットマップ－ひとつは、偶数のスクリーン、もうひとつは奇数のスクリーン－が格納されたふたつのオフスクリーンバッファを含むことによって、この チュートリアル3(DDEX3) の例では、 DDEX2の能力を拡張している。オフスクリーン・サーフェスの内容をバック・バッファにコピーするために、 IDirectDrawSurface2::BltFast メソッドを使う。そして、バッファをフリッピングし、次のオフスクリーン・サーフェスをバック・バッファにコピーする。

DDEX3で示される新しい機能を次のステップで説明する。

Step 1: オフスクリーン・サーフェスの作成

Step 2: オフスクリーン・サーフェスのビットマップのロード

Step 3: バック・バッファへのオフスクリーン・サーフェスのブロック転送


Step 1: オフスクリーン・サーフェスの作成

次のコードでは、ふたつのオフスクリーンバッファを作成するために、 DDEX3のdoInit 関数を追加している。

// オフスクリーンビットマップを作成

ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH;

ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;

ddsd.dwHeight = 480;

ddsd.dwWidth = 640;

ddrval = lpDD->CreateSurface(&ddsd, &lpDDSOne, NULL);

if(ddrval != DD_OK)

{

    return initFail(hwnd);

}

// もうひとつのオフスクリーンビットマップを作成

ddrval = lpDD->CreateSurface(&ddsd, &lpDDSTwo, NULL);

if(ddrval != DD_OK)

{

    return initFail(hwnd);

}

dwFlagsメンバで、アプリケーションがDDSCAPS 構造体を使うことを指定する。そして‘ DDSCAPS_OFFSCREENフラグが DDSCAPS 構造体にセットされることによって示されるように、バッファの高さと横幅をセットする。 サーフェスはオフスクリーン・プレーン・バッファになる。高さと幅はそれぞれ、480と640に DDSURFACEDESC 構造体内でセットされる。サーフェスは IDirectDraw::CreateSurfaceメソッドを使って作成する。

オフスクリーン・プレーン・バッファは両方とも同じサイズであるため、セカンド・バッファを作成するためには、 再び、異なるポインタ名でIDirectDraw::CreateSurfaceを呼び出せばよい。

特に DDSCAPS 構造体のDDSCAPS_SYSTEMMEMORYまたはDDSCAPS_VIDEOMEMORY能力をセットすることによって、オフスクリーン・バッファをシステム・メモリまたはディスプレイメモリに置くことを指定することができる。  ディスプレイ・メモリにビットマップを保存することによって、オフスクリーン・サーフェスとバック・バッファ間の転送スピードを上げることができる。ビットマップ・アニメーションを使うときにこれはより重要となる。しかしオフスクリーン・バッファに DDSCAPS_VIDEOMEMORYを指定した場合、ビットマップ全部を保持するのに充分なメモリがない場合、サーフェスを作成する際に失敗し、DDERR_OUTOFVIDEOMEMORYエラーが返される。


Step 2: オフスクリーン・サーフェスのビットマップのロード

ふたつのオフスクリーン・サーフェスが作成された後、 DDEX3は Frntback.bmpファイルからサーフェスへビットマップをロードするために、 InitSurfaces 関数を使用する。 InitSurfaces 関数は、 両方のビットマップをロードするためにDdutil.cppにあるDDCopyBitmap 関数を使用する。次の例を参照すること。

// ビットマップリソースのロード

hbm = (HBITMAP)LoadImage(GetModuleHandle(NULL), szBitmap,

    IMAGE_BITMAP, 0, 0, LR_CREATEDIBSECTION);

if (hbm == NULL)

    return FALSE;

DDCopyBitmap(lpDDSOne, hbm, 0, 0,   640, 480);

DDCopyBitmap(lpDDSTwo, hbm, 0, 480, 640, 480);

DeleteObject(hbm);

return TRUE;

Microsoft Paintやほかのドローアプリケーションで Frntback.bmpファイルの中身を見た場合、一方がもう一方に重なるふたつのスクリーンからビットマップが成り立つことがわかるだろう。 DDCopyBitmap 関数は、そのスクリーンが合わさるポイントをふたつに分ける。さらに、1番目のビットマップを1番目のオフスクリーン・サーフェスにロードする。(lpDDSOne)また、2番目のビットマップは、2番目のオフスクリーン・サーフェスにロードする。(lpDDSTwo)


Step 3: バック・バッファへのオフスクリーン・サーフェスのブロック転送

WM_TIMER メッセージ処理部は、サーフェスに書きこむコードと、フリッピングするコードを含んでいる。 DDEX3の場合、次のような、適当なオフスクリーン・サーフェスを選ぶようなコードと、バック・バッファに転送するコードとを含んでいる。

rcRect.left = 0;

rcRect.top = 0;

rcRect.right = 640;

rcRect.bottom = 480;

if(phase)

{

    pdds = lpDDSTwo;

    phase = 0;

}

else

{

    pdds = lpDDSOne;

    phase = 1;

}

while(1)

{

    ddrval = lpDDSBack->BltFast(0, 0, pdds, &rcRect, FALSE);

    if(ddrval == DD_OK)

    {

        break;

    }

 phaseは、オフスクリーン・サーフェスがバック・バッファにブロック転送されるためのフラグである。  IDirectDrawSurface2::BltFast メソッドは、選ばれたオフスクリーン・サーフェスをバック・バッファに左上角の座標(0,0)からブロック転送するために呼び出される。 rcRect パラメータは RECT 構造体であり、アンパサンド（＆）をつけてそのポインタとなる。この呼び出しにより、オフスクリーン・サーフェスの左上角から右下角までの領域が転送される。最後のパラメータは FALSE (または 0)に設定され、特別な転送フラグは使わないことを示している。

必要ならば、 IDirectDrawSurface2::Blt メソッドとIDirectDrawSurface2::BltFast メソッドのどちらもオフスクリーン・バッファから転送するために使うことができる。 もちろん、オフスクリーン・プレーン・バッファからの転送のパフォーマンスをあげる場合、 IDirectDrawSurface2::BltFastを使うべきである。 ディスプレイ・アダプタ上のハードウェア・ブロック転送を使っても、システムのスピードが得られない場合、ハードウェア・エミュレーションが転送を実行すると10パーセント程パフォーマンスが落ちる。このため、ディスプレイ・メモリからディスプレイ・メモリへ転送させるすべてのディスプレイ操作のためには、 IDirectDrawSurface2::BltFastを使うべきである。しかし、システム・メモリから転送したり、特別なハードウェア・フラグを要求する場合は、 IDirectDrawSurface2::Bltを使わなければならない。

オフスクリーン・サーフェスをバック・バッファにロードした後、バック・バッファとプライマリ・サーフェスは前のチュートリアルで示したのとほとんど同じ方法でフリッピングされる。


チュートリアル 4: カラー・キーとビットマップアニメーション

チュートリアル３(DDEX3)のサンプルでは、バック・バッファに転送する前にビットマップをオフスクリーンバッファへ配置するのに、原始的な方法を使っている。チュートリアル (DDEX4) のサンプルでは、前のチュートリアルで説明された背景と一連のスプライトをオフスクリーン・サーフェスへロードするためのテクニックを示す。ここではオフスクリーン・サーフェスの一部をバック・バッファにコピーする、つまり、簡単なビットマップ・アニメーションを作成するために、 IDirectDrawSurface2::BltFast メソッドを使用する。

DDEX4で使うビットマップファイルは、背景と黒の背景に赤い輪がぐるぐる回るその繰り返しから構成されるAll.bmpである。  DDEX4のサンプルは、回転している輪を重ねあわせるためのカラー・キーをセットする新しい関数を含んでいる。そしてサンプルは、 適当なスプライトをオフスクリーン・サーフェスからバック・バッファへコピーする。

DDEX4の新しい機能を次のようなステップで説明する。

Step 1:  カラー・キーの設定

Step 2: 簡単なアニメーションの作成


Step 1: カラー・キーの設定

他のDirectDrawサンプルでは、他の関数にdoInit関数を見つけることができる。しかし、 DDEX4のサンプルは、スプライトのためのカラー・キーをセットするコードを含んでいる。カラー・キーは、透明化で使われる色値の設定をする。システムがハードウェア転送能力を持つとき、矩形のピクセルは、カラー・キーとしてセットされた値を除いて、サーフェス上の非矩形スプライトを作成しながら転送される。 DDEX4でカラー・キーを設定している部分は次の通りである。

//黒のビットマップをカラー・キーに設定する

DDSetColorKey(lpDDSOne, RGB(0,0,0));

return TRUE;

DDSetColorKey 関数を呼び出すときに、指定したい色のRGB値を設定することによってカラー・キーを選択する。（黒の RGB値は (0, 0, 0)である）。 DDSetColorKey関数は、 DDColorMatch 関数を呼びだす。（どちらも、Ddutil.cppにある） DDColorMatch関数は、 lpDDSOneサーフェスに配置されたビットマップ上の (0, 0)のピクセルの現在のカラー値を格納し、指定した RGB値を取って (0, 0)の位置のピクセルにその色をセットする。最後に、利用可能なピクセル毎のビット数でそのカラーの値をマスクする。これが終わると、始めの色は(0, 0)の位置の後ろに置かれ、実際のカラー・キーの値と共に、 DDSetColorKeyへ戻る。 DDColorMatchの呼び出しが終わった後、カラー・キー値は、 DDCOLORKEY 構造体のdwColorSpaceLowValueメンバに置かれる。また、 dwColorSpaceHighValueメンバにもコピーされる。 IDirectDrawSurface2::SetColorKeyへの呼びだしによってカラー・キーを設定する。

DDSetColorKeyとDDColorMatchで、 CLR_INVALIDを参照していることに気づいたかもしれない。（DDEX4の DDSetColorKeyを呼び出すときに、カラー・キーとしてCLR_INVALIDを渡す場合、ビットマップの左上角の  (0, 0)ピクセルが、カラー・キーとして使われる。 DDEX4のビットマップが渡された場合、(0, 0) のピクセルの色が、グレーの影となること意味するわけではない。 DDEX4のサンプルで、(0, 0) のピクセルをカラー・キーとして使う方法を理解したければ、ビットマップファイルAll.bmpをドローイングアプリケーションで開き、(0, 0)のピクセルを黒に変更してみること。 ）それは、次のDDEX4 DDSetColorKeyを呼び出す行で行われる。

DDSetColorKey(lpDDSOne, CLR_INVALID);

DDEX4のサンプルを再コンパイルするとき、新しいビットマップファイルが含まれているため、リソースが定義されたファイルを再コンパイルしたことを確認すること。（これを行うためには、 Ddex4.rcファイルに一つのスペースを追加して消せばいいだけである。）すると DDEX4の例はカラー・キーとして黒にセットされた (0, 0)のピクセルを使うようになる。


Step 2: 簡単なアニメーションの作成

 DDEX4のサンプルでは、 All.bmpファイルに含まれる赤い輪を使った簡単なアニメーションを作成するために updateFrame関数を使っている。 そのアニメーションは、3つの赤い輪が3角形を形作り、様々なスピードで回転する。このサンプルでは、 Win32 GetTickCount関数を、最後にGetTickCountを呼び出してからスプライトを再描画するかどうかを決定するために何ミリ秒かかったかで比較している。その後、まず、 IDirectDrawSurface2::BltFast メソッドを使って、背景をオフスクリーン・サーフェス(lpDDSOne)からバック・バッファへ転送し、あらかじめどのピクセルを透過にするか決めておきカラー・キーを使ってバック・バッファへスプライトを転送する。バック・バッファにスプライトが転送された後、 DDEX4はバック・バッファとプライマリ・サーフェスをフリッピングするためにIDirectDrawSurface2::Flipを呼ぶ。

オフスクリーン・サーフェスから背景を転送するためにIDirectDrawSurface2::BltFastを呼び出すときは、転送のタイプを指定するdwTrans パラメータをDDBLTFAST_NOCOLORKEYに指定する。これは、 ノーマルな転送では透過ビットがないことを示している。その後、赤い輪がバック・バッファに転送されたとき、dwTrans パラメータを、 DDBLTFAST_SRCCOLORKEYにセットする。これは、定義された透過のためのカラー・キー（この場合 lpDDSOneに存在する）が存在するブロック転送をすることを示している。

このサンプルでは、 updateFrameによって背景全部が毎回再描画される。このサンプルを最適化する一つの方法は、赤い輪が回転している間、変更される部分だけ背景を再描画することである。輪が重ね合わされる矩形のサイズや配置は変更しないように、 DDEX4のサンプルを最適化するための簡単な修正をすることができる。


チュートリアル 5: パレットの動的変更

このチュートリアル (DDEX5) では、 チュートリアル 4 (DDEX4)で解説されたサンプルの修正について説明する。 ここでは、アプリケーションが動いている間、パレットのエントリを動的に変更する方法を解説する。 DDEX5で解説される新しい機能を、次のステップで説明する。

Step 1: パレット・エントリのロード

Step 2: パレットのローテート


Step 1: パレット・エントリのロード

DDEX5の次のコードは、パレット・エントリに、 All.bmpファイルの後半部分（赤い輪のを含む部分）の値をロードしている。

// はじめに、すべての色を未使用にセットする

for(i=0; i<256; i++)

{

    torusColors[i] = 0;

}

// サーフェスをロックし、後半部分をスキャンする（トーラス・エリア）

// 見つかったインデックスの記録を保持する

ddsd.dwSize = sizeof(ddsd);

while (lpDDSOne->Lock(NULL, &ddsd, 0, NULL) == DDERR_WASSTILLDRAWING)

    ;

// トーラス・フレームを検索し、使用色をマークする

for(y=480; y<480+384; y++)

{

    for(x=0; x<640; x++)

    {

        torusColors[((BYTE *)ddsd.lpSurface)[y*ddsd.lPitch+x]] = 1;

    }

}

lpDDSOne->Unlock(NULL);

torusColors配列は、 All.bmpファイルの後半部分で使われるカラー・インデックスのインジケータとして使う。最初に、 torusColors配列の値のすべてを0にリセットする。オフスクリーン・バッファは、カラー・インデックス値が使われる場合、それらの色が確定される前にロックされる。

torusColors配列は、ビットマップの480列の0桁からはじめるようにセットする。配列のカラー・インデックス値は、ビットマップ・サーフェスが配置されるメモリの配置場所により決定する。この配置場所は、 DDSURFACEDESC構造体のlpSurfaceメンバによって決定される。それはビットマップの480列0桁(y×lPitch+x)に対応したメモリの配置場所へのポインタとなる。特定のカラー・インデックス値の配置場所は1にセットする。値y (行row) は、 lPitch値（ DDSURFACEDESC構造体である）リニアメモリのピクセルの実際の配置を得ることができる。

torusColorsにセットされたカラー・インデックス値は、あとでパレット内のどの色をローテートするか決めるときに使う。 背景と赤い輪には共通する色がないため、赤い輪と関連づけられた色だけがローテートされる。これがtrueかどうかをチェックするためには、配列から"*ddsd.lPitch"を取り除き、プログラムを再コンパイルしたあと動かすときに何が起こるかを理解すること。 (y×lPitchで掛け算をしないと赤い輪は取得されないし背景で見られる色だけがインデックスされ、あとでローテートされる)さらに詳しい情報は、「幅とピッチ」を参照すること。


Step 2: パレットのローテート

 DDEX5の updateFrame関数は、 チュートリアル 4 (DDEX4)とほとんど同じ方法で働く。はじめに背景をバック・バッファに転送し、次に、3つの輪を前面に転送する。サーフェスをフリッピングする前に、 updateFrameは、プライマリ・サーフェスのパレットをdoInit関数で作成されたパレット・インデックスから変更する。方法は次のコードの通り。

// パレットの変更

if(lpDDPal->GetEntries(0, 0, 256, pe) != DD_OK)

{

    return;

}

for(i=1; i<256; i++)

{

    if(!torusColors[i])

    {

       continue;

    }

    pe[i].peRed = (pe[i].peRed+2) % 256;

    pe[i].peGreen = (pe[i].peGreen+1) % 256;

    pe[i].peBlue = (pe[i].peBlue+3) % 256;

}

if(lpDDPal->SetEntries(0, 0, 256, pe) != DD_OK)

{

    return;

}

IDirectDrawPalette::GetEntries メソッドは、最初の行で DirectDrawPaletteからパレット値を得る。パレット・エントリ値は、 peをポインタとする変数に入り、メソッドは DD_OKを返し、処理が続けられる。その間、カラー・インデックスが1にセットされているかどうか、torusColorsをチェックし続ける。セットされている場合、パレット・エントリの赤、緑、青の値は、ローテート（循環）される。

マークされたすべてのパレット・エントリがローテートされた後、 DirectDrawPaletteオブジェクトのエントリを変更するためにIDirectDrawPalette::SetEntriesメソッドを呼び出す。この変更は、プライマリ・サーフェスへのパレットセットが有効になるとすぐにあらわれる。

これが終わると、続いてサーフェスはDDEX5をフリッピングする


その他の DirectDrawサンプル

アプリケーションでDirectDrawをどのように使うか学ぶには、 DirectX SDKに含まれる次のサンプルのいくつかをチェックするとよい。

Stretch

非排他的（ウィンドウ）モード・アニメーションを（クリッピングされた転送と伸長しクリッピングされた転送の能力がある）ウィンドウ内に作成する方法を示す。

Donut

多くの排他的モード・アプリケーションが非排他的モード・アプリケーションと相互作用する試みを示す。

Wormhole

パレット・アニメーションの方法を示す。

Dxview

ディスプレイ・ハードウェアの能力を調べる方法を示す。

ほかにもDirectDrawに関するサンプルは、 Duel, Iklowns, Foxbear, Palette,Flip2dなどがある。


最適化とカスタマイズ

このSDKで提供されるDirectDrawのサンプルは比較的シンプルなもので、動作するシステムに多くの前提条件を設けている。この節では、コードが現実により良く動作するようなサンプルの最適化、カスタマイズについて説明する。

フリッピングとブロック転送の状態取得

カラーフィルを伴うブロック転送

ディスプレイ・ハードウェア能力の決定

ディスプレイ・メモリへのビットマップの格納

トリプル・バッファリング


フリッピングとブロック転送の状態取得

IDirectDrawSurface2::Flipメソッドが呼ばれたとき、プライマリ・サーフェス とバック・バッファは交換される。しかし、その変換はすぐには行われない。たとえば前のフリッピングが終了していない場合、またはフリッピングに失敗しなかった場合、このメソッドはDDERR_WASSTILLDRAWINGを返す。SDKのサンプルでは、 IDirectDrawSurface2::Flipの呼び出しは DD_OKが返されるまでループし続ける。また IDirectDrawSurface2::Flipの呼び出しもすぐに完了しない。フリッピングはシステムの次の垂直帰線がおこったときに行われる。

DDERR_WASSTILLDRAWINGが返されなくなるまで待つのは効率が悪い。代わりに、フリッピングが終了したかどうかを決定するため、バック・バッファでIDirectDrawSurface2::GetFlipStatusを呼び出す関数を作成すべきである。

もし前のフリッピングが終わっておらず、呼び出しで DDERR_WASSTILLDRAWINGが返った場合、アプリケーションは、ステータスを再びチェックする前に他の仕事を行うことができる。そうでなければ、次のフリッピングを実行できる。次の例で、この概念を説明する。

while(lpDDSBack->GetFlipStatus(DDGFS_ISFLIPDONE) ==

    DDERR_WASSTILLDRAWING);

    // 前のフリッピングが終了したのを待つ

    // アプリケーションはここで、他のタスクを実行できる

ddrval = lpDDSPrimary->Flip(NULL, 0);

ブロック転送が終了したかどうかを判断するために同じような方法でIDirectDrawSurface2::GetBltStatusメソッドを使うことができる。IDirectDrawSurface2::GetFlipStatusと IDirectDrawSurface2::GetBltStatusはすぐに返るため、周期的にこれらを使ってもアプリケーションはほとんどスピードをロスしない。


カラー・フィルを伴うブロック転送

表示させたい共通色のカラー・フィルを実現するためにIDirectDrawSurface2::Bltメソッドを使うことができる。たとえば、アプリケーションが表示する共通色が青の場合、青色で最初にサーフェスを埋めるためにDDBLT_COLORFILL フラグと共にIDirectDrawSurface2::Bltを使う。すると、その上に何でも書きこむことができる。 共通色ですばやく埋めることができるので、サーフェスへ最小の色数を書かなければいけないだけである。

次の例は、カラー・フィルを実現する方法のひとつである。

DDBLTFX ddbltfx;

ddbltfx.dwSize = sizeof(ddbltfx);

ddbltfx.dwFillColor = 0;

ddrval = lpDDSPrimary->Blt(

    NULL,        // 転送先

    NULL, NULL,  // 転送元矩形

    DDBLT_COLORFILL, &ddbltfx);

switch(ddrval)

{

    case DDERR_WASSTILLDRAWING:

        .

        .

        .

    case DDERR_SURFACELOST:

        .

        .

        .

    case DD_OK:

        .

        .

        .

    default:

}


ディスプレイ・ハードウェア能力の決定

DirectDrawは、ユーザのハードウェアがサポートしていないDirectDraw関数を実行するためにハードウェア・エミュレーションを使う。 DirectDrawアプリケーションのパフォーマンスを高速化するために、 DirectDrawオブジェクトを作成した後で、ユーザのディスプレイ・ハードウェアの能力を決定すべきである。 DirectDrawは、ユーザのシステム上で使用可能などのディスプレイ高速化ハードウェアも使うことができる。アプリケーションが要求するディスプレイ高速化ハードウェアをユーザのシステム上のディスプレイ・アダプタに存在しない場合、アプリケーションは必要とするハードウェアエミュレーションのリストをDirectDrawに提供しなければならないことに注意する。

ディスプレイ・ハードウェアの能力を取得するために、 IDirectDraw2::GetCapsを使うことができる。ハードウェアのためのDirectDrawデバイス・ドライバは、 DDCAPS 構造体のdwCapsメンバの値を書き表す。 これらの値は、システムのディスプレイ高速化ハードウェアの能力を示す。 DDCAPS 構造体は、アプリケーションの要求でハードウェア・エミュレーションを提供するDDSCAPS 構造体のアドレスを含んでいる。 DirectDrawのハードウェア制御能力がディスプレイ・アダプタ上で利用できない場合、ハードウェア・エミュレーションが使用される。この場合、アプリケーションがDDSCAPS 構造体 で要求されるハードウェア・エミュレーション値を提供しなければならない。.


ディスプレイ・メモリへのビットマップの格納

ディスプレイ・メモリからディスプレイ・メモリへの転送は、システム・メモリからディスプレイ・メモリへの転送よりもはるかに効率的である。ということは、アプリケーションは多くのスプライトをディスプレイ・メモリに格納したほうがいいことになる。

ほとんどのディスプレイ・ハードウェアは、プライマリ・サーフェスとバック・バッファだけでなくもっと多くのものを格納するために充分なメモリを持っている。ディスプレイ・アダプタメモリにビットマップを格納するために利用できるメモリの大きさを決定するために DDCAPS 構造体の dwVidMemTotalメンバと dwVidMemFreeメンバを使うことができる。(もし、ユーザのディスプレイ・ハードウェアの能力を得るために IDirectDraw2::GetCapsメソッドを使った場合) これがどのように動くか理解したければ、 DirectX SDKが提供する DirectXビューワ・アプリケーションを使う。 DirectDrawデバイスのもとでは、 プライマリ・ディスプレイ・ドライバ・フォルダを開き、その後 一般フォルダを開くこと。ディスプレイ・メモリの合計と（プライマリ・サーフェスを除く）未使用メモリの合計が表示される。サーフェスが、 DirectDrawオブジェクトに追加される度に、未使用メモリの合計は、追加されたサーフェスが使った分のメモリ分減っていく。


トリプル・バッファリング

トリプル・バッファリングを使って、アプリケーションの表示処理を高速化できる場合がある、トリプル・バッファリングは、一つのプライマリ・サーフェスとふたつのバック・バッファを使う。次の例では、トリプル・バッファリング・スキームを初期化する方法を示している。

// ふたつのバック・バッファとプライマリ・サーフェスを作成

ddsd.dwSize = sizeof(ddsd);

ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;

ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE |

    DDSCAPS_FLIP | DDSCAPS_COMPLEX;

ddsd.dwBackBufferCount = 2;

ddrval = lpDD->CreateSurface(&ddsd, &lpDDSPrimary, NULL);

if(ddrval == DD_OK)

{

    // 第一のバック・バッファへのポインタを取得

    ddscaps.dwCaps = DDSCAPS_BACKBUFFER;

    ddrval = lpDDSPrimary->GetAttachedSurface(&ddscaps,

        &lpDDSBackOne);

    if(ddrval != DD_OK)

        // ここでエラーメッセージを表示

    // 第二のバック・バッファへのポインタを取得

    ddscaps.dwCaps = DDSCAPS_BACKBUFFER;

    ddrval = lpDDSPrimary->GetAttachedSurface(&ddscaps,

        &lpDDSBackTwo);

フリッピングが完了しなくても、また第一のバック・バッファが転送を終了しなくても、トリプル・バッファリングによってアプリケーションはバック・バッファに転送し続けることができる。フリッピングの実行はすぐには起こらない。したがって、アプリケーションがひとつのバック・バッファだけ使う場合、 IDirectDrawSurface2::Flipメソッドが DD_OKを返すのを待つ間、アイドリング時間がかかる可能性がある。


DirectDrawリファレンス


関数


DirectDrawCreate

HRESULT DirectDrawCreate(GUID FAR * lpGUID,

    LPDIRECTDRAW FAR * lplpDD, IUnknown FAR * pUnkOuter);

DirectDrawオブジェクトのインスタンスを作成する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_DIRECTDRAWALREADYCREATED

DDERR_GENERIC

DDERR_INVALIDDIRECTDRAWGUID

DDERR_INVALIDPARAMS

DDERR_NODIRECTDRAWHW

DDERR_OUTOFMEMORY

lpGUID

作成されるドライバを表すグローバルユニーク識別子 (GUID)へのアドレス。 NULLはつねに、アクティブなディスプレイ・ドライバを示す。

lplpDD

呼び出しが成功した場合、有効なDirectDrawオブジェクトのポインタで初期化されるポインタへのアドレス。

pUnkOuter

COM集成化機能と将来の互換性のためにある。現在は NULLを設定しないとエラーとなる。

この関数はDirectDrawオブジェクトの初期化を試みる。呼び出しが成功した場合、オブジェクトへのポインタがlplpDDにセットされる。初期化直後にIDirectDraw2::GetCaps メソッドを呼ぶことで、このオブジェクトがハードウェアでどの程度アクセラレートされるかを検出し知らせる。


DirectDrawCreateClipper

HRESULT DirectDrawCreateClipper(DWORD dwFlags,

    LPDIRECTDRAWCLIPPER FAR *lplpDDClipper,

    IUnknown FAR *pUnkOuter);

DirectDrawオブジェクトに関連づけられないDirectDrawClipperオブジェクトのインスタンスを作成する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

dwFlags

このパラメータは現在未使用で、0にセットしておかなければならない。

lplpDDClipper

新しいDirectDrawClipperオブジェクトへのアドレスが返されるポインタへのアドレス。

pUnkOuter

COM集成化機能と将来の互換性のためにある。現在は、 NULLを設定しないとエラーとなる。

この関数は、 どのDirectDrawオブジェクトが作成される前にも呼び出すことができる。DirectDrawClipperオブジェクトはどのDirectDrawオブジェクトにも所有されないため、アプリケーションのオブジェクトが解放されても自動的に解放さることはない。アプリケーションが明示的にDirectDrawClipperオブジェクトを解放しない場合、 アプリケーション終了時にDirectDrawが解放する。

特定のDirectDrawオブジェクトによって所有されたDirectDrawClipperオブジェクトを作成するためには、 IDirectDraw2::CreateClipper メソッドを使うこと。

参照　IDirectDraw2::CreateClipper


DirectDrawEnumerate

HRESULT DirectDrawEnumerate(LPDDENUMCALLBACK lpCallback,

    LPVOID lpContext);

システムにインストールされたDirectDrawオブジェクトを列挙する。 NULLのGUIDエントリは、GDIと共有されるプライマリ・ディスプレイ・デバイスを示す。

成功したらDD_OK、失敗するとDDERR_INVALIDPARAMSを返す。

lpCallback

システムのHALデスクリプタをパラメータにして呼び出される Callback関数のアドレス。

lpContext

列挙コールバック関数が呼び出されるごとに渡されるアプリケーションで定義したコンテキストへのポインタ。


コールバック関数


Callback

BOOL WINAPI lpCallback(GUID FAR * lpGUID,

    LPSTR lpDriverDescription, LPSTR lpDriverName,

    LPVOID lpContext);

DirectDrawEnumerate 関数のためのアプリケーションで定義するコールバック関数。

列挙を続ける場合はDDENUMRET_OKを返し、止める場合はDDENUMRET_CANCELを返す。

lpGUID

DirectDrawオブジェクト内のグローバルユニーク識別子（ＧＵＩＤ）のアドレス。

lpDriverDescription

ドライバに関する記述を示す文字列のアドレス。

lpDriverName

ドライバ名を示す文字列のアドレス。

lpContext

関数が呼び出されるごとにコールバック関数に渡されるアプリケーションで定義した構造体へのポインタ。


EnumModesCallback

HRESULT WINAPI lpEnumModesCallback(LPDDSURFACEDESC lpDDSurfaceDesc,

    LPVOID lpContext);

IDirectDraw2::EnumDisplayModes メソッドのためのアプリケーションで定義するコールバック関数。

列挙を続ける場合はDDENUMRET_OKを返す。止める場合はDDENUMRET_CANCELを返す。

lpDDSurfaceDesc

モニターの周波数と作成され得るモードを提供するDDSURFACEDESC構造体 のアドレス。このデータは読み出し専用である。

lpContext

関数が呼び出されるごとにコールバック関数に渡されるアプリケーションで定義した構造体へのポインタ。


EnumSurfacesCallback

HRESULT WINAPI lpEnumSurfacesCallback(

    LPDIRECTDRAWSURFACE2 lpDDSurface,

    LPDDSURFACEDESC lpDDSurfaceDesc, LPVOID lpContext);

IDirectDrawSurface2::EnumAttachedSurfaces メソッドのためのアプリケーションで定義するコールバック関数。

列挙を続ける場合は DDENUMRET_OKを返し、止める場合はDDENUMRET_CANCELを返す。

lpDDSurface

このサーフェスにアタッチされたサーフェスのアドレス。

lpDDSurfaceDesc

アタッチされたサーフェスを記述するDDSURFACEDESC構造体のアドレス。

lpContext

関数が呼び出されるごとにコールバック関数に渡されるアプリケーションで定義した構造体へのポインタ。


fnCallback

HRESULT WINAPI lpfnCallback(LPDIRECTDRAWSURFACE lpDDSurface,

    LPVOID lpContext);

IDirectDrawSurface2::EnumOverlayZOrders メソッドのためのアプリケーションで定義するコールバック関数。

列挙を続ける場合は DDENUMRET_OKを返し、止める場合はDDENUMRET_CANCELを返す。

lpDDSurface

サーフェスにオーバーレイされているサーフェスのアドレス。

lpContext

関数が呼び出されるごとにコールバック関数に渡されるアプリケーションで定義した構造体へのポインタ。


IDirectDraw2

DirectDrawオブジェクトを作成しシステム・レベル変数で動作するために、アプリケーションはIDirectDraw2 インターフェイスのメソッドを使う。この節では、IDirectDraw2 インターフェイスのメソッドについて説明する。概念の概要は、「DirectDrawオブジェクト」を参照すること。

IDirectDraw2 インターフェイスのメソッドは、次のようなグループに分けられる。

メモリの割り当て	Compact
	Initialize
オブジェクトの作成	CreateClipper
	CreatePalette
	CreateSurface
デバイスの能力	GetCaps
ディスプレイ・モード	EnumDisplayModes
	GetDisplayMode
	GetMonitorFrequency
	RestoreDisplayMode
	SetDisplayMode
ディスプレイ・ステータス	GetScanLine
	GetVerticalBlankStatus
その他	GetAvailableVidMem
	GetFourCCCodes
	WaitForVerticalBlank
動作環境の設定	SetCooperativeLevel
サーフェス	DuplicateSurface
	EnumSurfaces
	FlipToGDISurface
	GetGDISurface
IDirectDraw2インターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイスメソッドを継承する。 IUnknownインターフェイスは、次の3つのメソッドをサポートしている。

AddRef
QueryInterface
Release


IDirectDraw2::Compact

HRESULT Compact();

現在、このメソッドは定義されているだけであり、実装はまだされていない。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOEXCLUSIVEMODE

DDERR_SURFACEBUSY

このメソッドは、ディスプレイ・カードのサーフェス・メモリの断片を移動させて連続した一ブロックをとり、利用できる未使用メモリを最大にする。なんらかの処理が行われているときに呼び出すと失敗する。

このメソッドを呼びだすアプリケーションは、共有レベルを排他的レベルにセットしておかなければならない。


IDirectDraw2::CreateClipper

HRESULT CreateClipper(DWORD dwFlags,

    LPDIRECTDRAWCLIPPER FAR * lplpDDClipper,

    IUnknown FAR * pUnkOuter);

DirectDrawClipperオブジェクトを作成する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOCOOPERATIVELEVELSET

DDERR_OUTOFMEMORY

dwFlags

このパラメータは現在未使用で、0にセットしておかなければならない。

lplpDDClipper

このメソッドが成功した場合返される新しいDirectDrawClipperオブジェクトを示すポインタのアドレス。

pUnkOuter

COM集成化機能と将来の互換性のためにある。現在は、 NULLを設定しないとエラーとなる。

DirectDrawClipperオブジェクトはDirectDrawSurfaceオブジェクトにアタッチすることができ、IDirectDrawSurface2::Blt、IDirectDrawSurface2::BltBatch、IDirectDrawSurface2::UpdateOverlay の処理中に 使用できる。

特定のDirectDrawに所有されないDirectDrawClipperオブジェクトを作成するには、 DirectDrawCreateClipper関数を使用すること。

参照　IDirectDrawSurface2::GetClipper、IDirectDrawSurface2::SetClipper


IDirectDraw2::CreatePalette

HRESULT CreatePalette(DWORD dwFlags,

    LPPALETTEENTRY lpColorTable,

    LPDIRECTDRAWPALETTE FAR * lplpDDPalette,

    IUnknown FAR * pUnkOuter);

DirectDrawPaletteオブジェクトを作成する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOCOOPERATIVELEVELSET

DDERR_NOEXCLUSIVEMODE

DDERR_OUTOFCAPS

DDERR_OUTOFMEMORY

DDERR_UNSUPPORTED

dwFlags

次のフラグのうち、ひとつ以上の値を取る。

DDPCAPS_1BIT

	インデックスは1ビット。カラー・テーブルへのエントリはふたつである。

DDPCAPS_2BIT

	インデックスは２ビット。カラー・テーブルへのエントリは４つである。

DDPCAPS_4BIT

	インデックスは４ビット。カラー・テーブルへのエントリは１６個である。

DDPCAPS_8BITENTRIES

	8ビットカラー・インデックスを参照するインデックスを示す。このフラグは、 DDPCAPS_1BIT、DDPCAPS_2BIT、DDPCAPS_4BITを使う場合とターゲット・サーフェスが8bppの場合だけ有効となる。各カラーエントリは、１バイト長で、8bppパレットのサーフェスのインデックスを指す。

DDPCAPS_8BIT

	インデックスは8ビット。カラー・テーブルへのエントリは256個である。

DDPCAPS_ALLOW256

	このパレットは256個のエントリすべてを定義できる。
lpColorTable

このDirectDrawPaletteオブジェクトを初期化するための2、 4、 16、  256色ぶんのPALETTEENTRY型配列のアドレス。

lplpDDPalette

このメソッドが成功した場合返される新しいDirectDrawPaletteオブジェクトへのポインタのアドレス。

pUnkOuter

COM集成化機能と将来の互換性のためにある。現在は NULLを設定しないとエラーとなる。


IDirectDraw2::CreateSurface

HRESULT CreateSurface(LPDDSURFACEDESC lpDDSurfaceDesc,

    LPDIRECTDRAWSURFACE FAR * lplpDDSurface,

    IUnknown FAR * pUnkOuter);

DirectDrawSurfaceオブジェクトを作成する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INCOMPATIBLEPRIMARY

DDERR_INVALIDCAPS

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDPIXELFORMAT

DDERR_NOALPHAHW

DDERR_NOCOOPERATIVELEVELSET

DDERR_NODIRECTDRAWHW

DDERR_NOEMULATION

DDERR_NOEXCLUSIVEMODE

DDERR_NOFLIPHW

DDERR_NOMIPMAPHW

DDERR_NOZBUFFERHW

DDERR_OUTOFMEMORY

DDERR_OUTOFVIDEOMEMORY

DDERR_PRIMARYSURFACEALREADYEXISTS

DDERR_UNSUPPORTEDMODE

lpDDSurfaceDesc

作成したいサーフェスへの要求を記述したDDSURFACEDESC構造体へのポインタ。

lplpDDSurface

呼び出しが成功した場合、有効なDirectDrawSurfaceポインタによって初期化されるサーフェスへのポインタのアドレス。

pUnkOuter

COM集成化機能と将来の互換性のためにある。現在は NULLを設定しないとエラーとなる。


IDirectDraw2::DuplicateSurface

HRESULT DuplicateSurface(LPDIRECTDRAWSURFACE lpDDSurface,

    LPLPDIRECTDRAWSURFACE FAR * lplpDupDDSurface);

DirectDrawSurfaceオブジェクトの複製を行う。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_CANTDUPLICATE

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

DDERR_SURFACELOST

lpDDSurface

複製するDirectDrawSurface構造体のアドレス。

lplpDupDDSurface

新しく作成される複製のDirectDrawSurface構造体を指すDirectDrawSurfaceポインタ のアドレス。

このメソッドは、すでに存在するDirectDrawSurfaceオブジェクトのサーフェス・メモリを共用する新しいDirectDrawSurfaceオブジェクトを作成する。 この複製は、オリジナルのオブジェクトとまったく同じように使用できる。最後に参照されたオブジェクトが解放されるとサーフェス・メモリは解放される。プライマリ・サーフェス、3Dサーフェス、または、暗黙的に作成されたサーフェスは複製できない。


IDirectDraw2::EnumDisplayModes

HRESULT EnumDisplayModes(DWORD dwFlags,

    LPDDSURFACEDESC lpDDSurfaceDesc, LPVOID lpContext,

    LPDDENUMMODESCALLBACK lpEnumModesCallback);

DirectDrawオブジェクトによって提供されたサーフェスと互換性があるとハードウェアが認識したディスプレイ・モードを列挙する。サーフェスにNULLが渡された場合、すべてのモードを列挙する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

dwFlags

DDEDM_REFRESHRATES

	異なるリフレッシュレートを列挙する。 IDirectDraw2::EnumDisplayModesは 各モードが一度だけしか列挙されないことを保証する。このフラグは、モードがユニークかどうかを決定する時に、リフレッシュレートが考慮に入れられるかどうかを指定する。
lpDDSurfaceDesc

利用できるモードをチェックするDDSURFACEDESC構造体へのポインタのアドレス。NULLを指定した場合、すべてのモードが列挙される。

lpContext

列挙されるメンバそれぞれに渡されるアプリケーションで定義した構造体へのポインタ。

lpEnumModesCallback

条件に合致したものが見つかる度に呼ばれるEnumModesCallback 関数へのポインタ

このメソッドはDDSURFACEDESC 構造体のdwRefreshRateメンバを列挙することができるようになっている。古い IDirectDraw::EnumDisplayModes メソッドには、その機能がない。新機能のリフレッシュモードをセットするためにIDirectDraw2::SetDisplayMode メソッドを使う際には、 dwRefreshRateメンバを列挙するために IDirectDraw2::EnumDisplayModesを使わなくてはならない。

参照　IDirectDraw2::GetDisplayMode、 IDirectDraw2::SetDisplayMode、 IDirectDraw2::RestoreDisplayMode


IDirectDraw2::EnumSurfaces

HRESULT EnumSurfaces(DWORD dwFlags, LPDDSURFACEDESC lpDDSD,

    LPVOID lpContext, LPDDENUMSURFACESCALLBACK lpEnumSurfacesCallback);

指定された基準に合致するサーフェスをすべて列挙する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

dwFlags

次のフラグのうちのひとつ。

DDENUMSURFACES_ALL

	基準に合致するサーフェスすべてを列挙する。

DDENUMSURFACES_CANBECREATED

	基準に合致して、かつ最初に作成されたサーフェスを列挙する。

DDENUMSURFACES_DOESEXIST

	基準に合致して、すでに存在しているサーフェスを列挙する。

DDENUMSURFACES_MATCH

	サーフェス・デスクリプタに該当するサーフェスを探す。

DDENUMSURFACES_NOMATCH

	サーフェス・デスクリプタに該当しなかったサーフェスを探す。
lpDDSD

所有しているサーフェスを定義するDDSURFACEDESC構造体へのポインタ。

lpContext

列挙されたメンバに渡されるアプリケーションが定義した構造体へのポインタ。

lpEnumSurfacesCallback

一致に合致するものが見つかる度に呼ばれるEnumSurfacesCallback関数へのポインタ。

DDENUMSURFACES_CANBECREATEDフラグがセットされる場合、このメソッドは基準に合うサーフェスを一時的に作成しようとする。 サーフェスが列挙されると参照カウントも増えることに気をつけること。もしそのサーフェスを使わない場合、列挙された後、 IDirectDraw::Releaseを使ってそのサーフェスを解放する。

IDirectDraw インターフェイスの一部として、このメソッドは dwFlagsがゼロ以外の値はサポートしない。


IDirectDraw2::FlipToGDISurface

HRESULT FlipToGDISurface();

GDIが、プライマリ・サーフェスとして扱うサーフェスを作る。

成功したらDD_OKを返し、失敗すると次のエラー・コードを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTFOUND

このメソッドは、GDIが書きこんでいるディスプレイ・メモリが、ユーザに可視となることを保証するために、ページ・フリッピング・アプリケーションの最後に呼ばれる。

参照　IDirectDraw2::GetGDISurface


IDirectDraw2::GetAvailableVidMem

HRESULT GetAvailableVidMem(LPDDSCAPS lpDDSCaps,

    LPDWORD lpdwTotal, LPDWORD lpdwFree);

利用できるディスプレイ・メモリの総容量とディスプレイ・モードの現在の空き容量を取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDCAPS

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NODIRECTDRAWHW

lpDDSCaps

サーフェスの、ハードウェア能力を含むDDSCAPS構造体へのポインタ。

lpdwTotal

利用できるディスプレイ・メモリの総容量を取得する変数へのポインタ。

lpdwFree

現在のシスプレイメモリの空き容量を取得する変数へのポインタ。

lpdwTotalまたはlpdwFree  にNULLが渡された場合、パラメータに対する値は返されない。

次の C++ の例では、テクスチャ・マップ・サーフェスで利用できるディスプレイ・メモリの総容量と空き容量を決定する IDirectDraw2::GetAvailableVidMemを使っている。

LPDIRECTDRAW2 lpDD2;

DDSCAPS       ddsCaps;

DWORD         dwTotal;

DWORD         dwFree;

ddres = lpDD->QueryInterface(IID_IDirectDraw2, &lpDD2);

if (FAILED(ddres))

.

.

.

ddsCaps.dwCaps = DDSCAPS_TEXTURE;

ddres = lpDD2->GetAvailableVidMem(&ddsCaps, &dwTotal, &dwFree);

if (FAILED(ddres))

.

.

.

このメソッドは、現在のディスプレイ・メモリの状態のスナップショットを提供する。ディスプレイ・メモリの空き容量は、サーフェスの作成と解放の順番などよって変わる。したがって、空きメモリの量はおおまかな判断材料として使うべきである。さらに、特定のディスプレイ・アダプタ・カードは、ふたつの異なるメモリタイプを区別できない。たとえば、 Zバッファとテクスチャを格納するのに、ディスプレイ・メモリの同じ部分をアダプタが使用する可能性がある。よって、サーフェスの一つのタイプ（たとえば、Zバッファ）は、もう一方のサーフェス（たとえば、テクスチャ）が利用できるディスプレイ・メモリの容量に影響を与える。 したがって、動的使用（テクスチャ・マッピングのような）に利用できるメモリの容量を決定する前に、アプリケーションが固定したリソース（フロント・バッファとバック・バッファ、Zバッファのような）を初めに配置するのが最良の方法である。

このメソッドは、 IDirectDraw2インターフェイスの新機能であり、 IDirectDrawインターフェイスには実装されていない。


IDirectDraw2::GetCaps

HRESULT GetCaps(LPDDCAPS lpDDDriverCaps, LPDDCAPS lpDDHELCaps);

ハードウェアとHEL（ハードウェア・エミュレーション・レイヤ）双方のデバイス・ドライバの能力を取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lpDDDriverCaps

デバイス・ドライバに報告されるハードウェアの能力を取得するDDCAPS構造体へのポインタ。

lpDDHELCaps

HELの能力を取得するDDCAPS構造体へのポインタ。

参照　DDCAPS


IDirectDraw2::GetDisplayMode

HRESULT GetDisplayMode(LPDDSURFACEDESC lpDDSurfaceDesc);

現在のディスプレイ・モードを取得する。

成功したらDD_OKを返し、失敗すれば次のようなエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_UNSUPPORTEDMODE

lpDDSurfaceDesc

サーフェスを示すDDSURFACEDESC構造体へのポインタ。

アプリケーションがこのメソッドで返された情報を予め保存して、クリーンアップの際のディスプレイ・モード復元のために利用することは望ましくない。したがって、マルチプロセス環境で起こるモード設定の競合を避けるために、アプリケーションは、クリーンアップのためのモード復元には、 IDirectDraw2::RestoreDisplayModeを使うべきである。

参照　IDirectDraw2::SetDisplayMode、

 IDirectDraw2::RestoreDisplayMode、 IDirectDraw2::EnumDisplayModes


IDirectDraw2::GetFourCCCodes

HRESULT GetFourCCCodes(LPDWORD lpNumCodes, LPDWORD lpCodes);

DirectDrawオブジェクトでサポートされているFourCCコードを取得する。このメソッドは、サポートされているコードの数字を返すためにも使用される。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lpNumCodes

lpCodesで示される配列のエントリ数。エントリ数が小さすぎてすべてのコードが収納できない場合には、 lpNumCodesには要求された値がセットされ、 その数ぶんがlpCodesに入る。

lpCodes

FourCCコードが入る配列へのポインタ。 NULLが渡されると、 lpNumCodesには FourCCコードをサポートする値をセットして、リターンする。


IDirectDraw2::GetGDISurface

HRESULT GetGDISurface(LPDIRECTDRAWSURFACE FAR * lplpGDIDDSSurface);

GDIがプライマリ・サーフェスとして扱うサーフェス・メモリを表すDirectDrawSurfaceオブジェクトを取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTFOUND

lplpGDIDDSSurface

GDIのプライマリ・サーフェスをコントロールしているDirectDrawSurfaceオブジェクトへのポインタ。

参照　IDirectDraw2::FlipToGDISurface


IDirectDraw2::GetMonitorFrequency

HRESULT GetMonitorFrequency(LPDWORD lpdwFrequency);

 DirectDrawオブジェクトが動作するモニタ周波数を取得する。周波数の値は100を掛け算した値である。たとえば、60Hzであれば、 6000が返る。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_UNSUPPORTED

lpdwFrequency

モニター周波数を示す変数のアドレス。


IDirectDraw2::GetScanLine

HRESULT GetScanLine(LPDWORD lpdwScanLine);

モニタが現在描画しているスキャンラインを取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_UNSUPPORTED

DDERR_VERTICALBLANKINPROGRESS

lpdwScanLine

ディスプレイが現在描画しているスキャンラインを取得する変数のポインタ。

参照　IDirectDraw2::GetVerticalBlankStatus、 IDirectDraw2::WaitForVerticalBlank


IDirectDraw2::GetVerticalBlankStatus

HRESULT GetVerticalBlankStatus(LPBOOL lpbIsInVB);

垂直帰線の状態を取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lpbIsInVB

垂直帰線の状態を取得する変数のポインタ。このパラメータは、垂直帰線期間にある場合は TRUE、そうでない場合は FALSEになる。

垂直帰線と同期を取る場合は、 IDirectDraw2::WaitForVerticalBlank メソッドを使うこと。

参照　IDirectDraw2::GetScanLine、 IDirectDraw2::WaitForVerticalBlank


IDirectDraw2::Initialize

HRESULT Initialize(GUID FAR * lpGUID);

CoCreateInstance OLE 関数を使って、作成されるDirectDrawオブジェクトを初期化する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_ALREADYINITIALIZED

DDERR_DIRECTDRAWALREADYCREATED

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NODIRECTDRAWHW

DDERR_NODIRECTDRAWSUPPORT

DDERR_OUTOFMEMORY

lpGUID

インターフェイス識別子として使用されるGUID （グローバルユニーク識別子）のアドレス。

このメソッドは、 COM（コンポーネント・オブジェクト・モデル）プロトコルによって提供される。 DirectDrawオブジェクトを作成するためにDirectDrawCreate関数が使われた場合、このメソッドは DDERR_ALREADYINITIALIZEDを返す。 IDirectDraw2::Initializeが DirectDrawオブジェクトを作成するためにCoCreateInstanceがすでに呼ばれていない場合は、エラーとなり、DDERR_NOTINITIALIZEDを返す。

CoCreateInstanceと共にIDirectDraw2::Initializeを使う場合、「CoCreateInstanceを用いたDirectDrawオブジェクトの作成」を参照すること。

参照　IUnknown::AddRef、 IUnknown::QueryInterface、

 IUnknown::Release


IDirectDraw2::RestoreDisplayMode

HRESULT RestoreDisplayMode();

プライマリ・サーフェスのディスプレイ・デバイス・ハードウェアを、 IDirectDraw2::SetDisplayModeが呼ばれる以前に復元する。排他的レベルでのアクセスした後には必要な処理である。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_LOCKEDSURFACES

DDERR_NOEXCLUSIVEMODE

参照　IDirectDraw2::SetDisplayMode、

IDirectDraw2::EnumDisplayModes、 IDirectDraw2::SetCooperativeLevel


IDirectDraw2::SetCooperativeLevel

HRESULT SetCooperativeLevel(HWND hWnd, DWORD dwFlags);

アプリケーションに動作環境の協調レベルを設定する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_EXCLUSIVEMODEALREADYSET

DDERR_HWNDALREADYSET

DDERR_HWNDSUBCLASSED

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

hWnd

アプリケーションで使われるウィンドウ・ハンドル。

dwFlags

次のフラグの値のうち、ひとつ以上を取る。

DDSCL_ALLOWMODEX

	モード Xディスプレイモードの使用の許可。

DDSCL_ALLOWREBOOT

	排他的（フルスクリーン）モード時に、 CTRL+ALT+DELの機能の許可。

DDSCL_EXCLUSIVE

	排他的レベルの要求。

DDSCL_FULLSCREEN

	排他的モードの所有者が全プライマリ・サーフェスに対する応答を行うことを示す。 GDIは無視してもよい。

DDSCL_NORMAL

	アプリケーションが通常のWindowsアプリケーションとして機能することを示す。

DDSCL_NOWINDOWCHANGES

	アクティベート時、 DirectDrawがアプリケーションウィンドウを最小化したりリストアしたりさせない。
他のアプリケーションよりもはるかに優先的な機能を有するためには、DDSCL_EXCLUSIVEフラグをセットする必要がある。 IDirectDraw2::Compact メソッドを呼び、ディスプレイ・モードを変更し、プライマリ・サーフェスの動作（たとえばフリッピング）を操作するには、アプリケーションは排他的レベルにセットしておく。アプリケーションがDDSCL_EXCLUSIVEフラグとDDSCL_FULLSCREENフラグをセットしてIDirectDraw2::SetCooperativeLevelを呼ぶ場合ウィンドウはフルスクリーンへのリサイズを行おうとする。DDSCL_EXCLUSIVEフラグまたはDDSCL_NORMALフラグはどちらかひとつがセットされなければならない。また、 DDSCL_EXCLUSIVEは、 DDSCL_FULLSCREENのセットも同時に必要とする。

モードXモードは、アプリケーションが DDSCL_ALLOWMODEXとDDSCL_FULLSCREENと DDSCL_EXCLUSIVEをセットした場合にのみ利用できる。 DDSCL_ALLOWMODEXは、 DDSCL_NORMALと一緒に使うことはできない。 DDSCL_ALLOWMODEXが指定されていない場合、 IDirectDraw2::EnumDisplayModes メソッドは モードXモードを列挙しない。 Mode Xが要求された場合、 IDirectDraw2::SetDisplayModeは失敗する。サポートされるディスプレイ・モードは、 IDirectDraw2::SetCooperativeLevelを使うと変更できる。

Windowsでは モードXモードは未サポートである。したがってモードXモードではプライマリ・サーフェスをロックまたは転送する。IDirectDrawSurface2::LockメソッドとIDirectDrawSurface2::Bltメソッドは使用できない。プライマリ・サーフェスのIDirectDrawSurface2::GetDCメソッドを使うこともできない。また、スクリーンDCと共にGDIを使うこともできない。 モードXモードは、 IDirectDrawSurface2::GetCaps メソッドと IDirectDraw2::EnumDisplayModesメソッドによって返される ことになる。DDSURFACEDESC構造体の一部分であるDDSCAPS構造体のDDSCAPS_MODEXフラグで示される。

IDirectDraw2::SetCooperativeLevel は  、アプリケーションが DirectDrawをマルチプル・ウィンドウで使うことができるように、 DDSCL_NORMALモードを指定した際にもウィンドウ・ハンドルを要求しない。ウィンドウ・ハンドルにNULLを渡せば、すべてのウィンドウは、ノーマルなWindowsモードで同時にDirectDrawで使えるようになる。

IDirectDraw::SetDisplayModeメソッドと IDirectDraw::SetCooperativeLevelメソッドとの相互作用は、 IDirectDraw2におけるそれとは異なっている。つまりアプリケーションが制御レベルをセットするために、これらのインターフェイスの IDirectDrawバージョンを使う場合は、元のディスプレイモードは、 IDirectDraw::RestoreDisplayModeメソッドを使うことによってリストアされる。

1	排他的モードにするために、DDSCL_EXCLUSIVEフラグをセットして IDirectDraw::SetCooperativeLevelを呼び出す。

2	ディスプレイモードを変更するために IDirectDraw::SetDisplayModeを呼び出す。

3	排他的モードを解除するためにDDSCL_NORMALフラグと共にIDirectDraw::SetCooperativeLevelを呼び出す。

しかし、 IDirectDraw2インターフェイスを使って同じような手順をとる場合、元のディスプレイ・モードは排他的モードが解除されたときに自動的に復元される。

参照　IDirectDraw2::SetDisplayMode、 IDirectDraw2::Compact、 IDirectDraw2::EnumDisplayModes


IDirectDraw2::SetDisplayMode

HRESULT SetDisplayMode(DWORD dwWidth, DWORD dwHeight,

    DWORD dwBPP, DWORD dwRefreshRate, DWORD dwFlags);

ディスプレイ・デバイス・ハードウェアのモードを設定する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDMODE

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_LOCKEDSURFACES

DDERR_NOEXCLUSIVEMODE

DDERR_SURFACEBUSY

DDERR_UNSUPPORTED

DDERR_UNSUPPORTEDMODE

DDERR_WASSTILLDRAWING

dwWidth and dwHeight

新しいモードの幅と高さ。

dwBPP

新しいモードのビット／ピクセル(bpp)。

dwRefreshRate

新しいモードのリフレッシュレート。このパラメータが０にセットされると、 このメソッドのIDirectDraw インターフェイス・バージョンが使用される。

dwFlags

このパラメータは現在未使用。0にセットしておくこと。

IDirectDraw2::SetCooperativeLevelメソッドは、モードが変更が可能になる前に排他的レベルアクセスをセットするために使用する。他のアプリケーションが、プライマリ・サーフェス上のDirectDrawSurfaceを作成して、モードを変更する場合には、アプリケーションのプライマリ・サーフェス・オブジェクトは、リストアされるまで DDERR_SURFACELOSTを返す。

IDirectDraw インターフェイスでは、このメソッドはパラメータdwRefreshRateとdwFlagsを含んでいない。

IDirectDraw::SetDisplayModeとIDirectDraw::SetCooperativeLevelの間の 相互作用はIDirectDraw2でのそれと異なる。つまりアプリケーションが、 次のような手順でディスプレイ・モードと制御レベルをセットするためにこれらのインターフェイスのIDirectDrawバージョンを使う場合、元のディスプレイ・モードは IDirectDraw::RestoreDisplayModeメソッドを使って復元しなければならない。

1	排他的モードにするために、DDSCL_EXCLUSIVEフラグをセットして IDirectDraw::SetCooperativeLevelを呼び出す。

2	ディスプレイ・モードの変更のために IDirectDraw::SetDisplayModeを呼び出す。

3	排他的モードを解除するためにDDSCL_NORMALフラグをセットしてIDirectDraw::SetCooperativeLevel  を呼び出す。

しかし IDirectDraw2を使って同じような手順を踏む場合には、元のディスプレイ・モードの復元は、排他的モードが解除された時に行われる。

参照　IDirectDraw2::RestoreDisplayMode、

IDirectDraw2::GetDisplayMode、 IDirectDraw2::EnumDisplayModes、 IDirectDraw2::SetCooperativeLevel


IDirectDraw2::WaitForVerticalBlank

HRESULT WaitForVerticalBlank(DWORD dwFlags, HANDLE hEvent);

アプリケーションが垂直帰線期間を使って同期を取る方法を提供する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

dwFlags

垂直帰線期間に対し、どのように待つのか決定する。

DDWAITVB_BLOCKBEGIN

	垂直帰線期間の開始時から返す。

DDWAITVB_BLOCKBEGINEVENT

	垂直帰線が始まるときのイベント・トリガ。これは現在サポートされていない。

DDWAITVB_BLOCKEND

	垂直帰線期間が終わり、表示を開始したときに返される。
hEvent

垂直帰線が始まったときにトリガとなるイベント・ハンドル

参照　IDirectDraw2::GetVerticalBlankStatus、 IDirectDraw2::GetScanLine


IDirectDrawClipper

アプリケーションはクリップ・リストを管理するためにIDirectDrawClipperインターフェイスのメソッドを使う。このセクションでは、このインターフェイスのメソッドについて解説する。概要については、 「IDirectDrawClipper インターフェイス」を参照すること。

IDirectDrawClipperインターフェイスのメソッドは、次のようなグループに分けられる。

メモリ配置	Initialize
クリップ・リスト	GetClipList
	IsClipListChanged
	SetClipList
	SetHWnd
ハンドル	GetHWnd
IDirectDrawClipperインターフェイスは、すべてのCOMインターフェイスのように IUnknownインターフェイス・メソッドを継承する。Iunknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release


IDirectDrawClipper::GetClipList

HRESULT GetClipList(LPRECT lpRect, LPRGNDATA lpClipList,

    LPDWORD lpdwSize);

DirectDrawClipperオブジェクトに関連づけられたクリップ・リストのコピーを取得する。クリップ・リストをクリッピングする矩形を渡すことによって、クリップ・リストのサブセットを選択することができる。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDCLIPLIST

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOCLIPLIST

DDERR_REGIONTOOSMALL

lpRect

クリップ・リストをクリッピングするために使用する矩形の構造体へのポインタ。

lpClipList

クリップ・リストのコピー結果を含むRGNDATA構造体へのポインタ。

lpdwSize

クリップ・リストのサイズを設定する変数へのポインタ。

このメソッドで使われるRGNDATA 構造体は、次のような文法で使われる。

typedef struct _RGNDATA {

    RGNDATAHEADER rdh;

    char          Buffer[1];

} RGNDATA;

RGNDATA構造体の rdhメンバは、次のような文法で使われるRGNDATAHEADER構造体である。

typedef struct _RGNDATAHEADER {

    DWORD dwSize;

    DWORD iType;

    DWORD nCount;

    DWORD nRgnSize;

    RECT  rcBound;

} RGNDATAHEADER;

これらの構造体についてのさらに詳しい情報は、 Win32SDKのドキュメントを参照すること。

参照　IDirectDrawClipper::SetClipList


IDirectDrawClipper::GetHWnd

HRESULT GetHWnd(HWND FAR * lphWnd);

以前にIDirectDrawClipper::SetHWnd メソッドを使って、DirectDrawClipperオブジェクトと関連づけられたウィンドウ・ハンドルを取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lphWnd

すでにIDirectDrawClipper::SetHWndメソッドによって、 DirectDrawClipperオブジェクトと関連づけられたウィンドウ・ハンドルのポインタ。

参照　IDirectDrawClipper::SetHWnd


IDirectDrawClipper::Initialize

HRESULT Initialize(LPDIRECTDRAW lpDD, DWORD dwFlags);

DirectDrawClipperオブジェクトがCoCreateInstance OLE 関数を使って作成された場合の初期化 を行う。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_ALREADYINITIALIZED

DDERR_INVALIDPARAMS

lpDD

DirectDrawオブジェクトの DirectDraw構造体のポインタ。このパラメータがNULLにセットされると、独立したDirectDrawClipperオブジェクトが作成される。(DirectDrawCreateClipper関数を 使うのと等しい)

dwFlags

このパラメータは現在未使用なので、0にセットしておくこと。

このメソッドは、コンポーネント・オブジェクト・モデル (COM) にしたがって提供される。すでにDirectDrawCreateClipperまたはIDirectDraw2::CreateClipperメソッドがDirectDrawClipperを作成するために使われた場合には、このメソッドはエラーとなり、 DDERR_ALREADYINITIALIZEDを返す。

IDirectDrawClipper::InitializeとCoCreateInstanceの使用についての詳細は、「CoCreateInstanceを用いたDirectDrawClipperオブジェクトの作成」を参照すること。

参照　IUnknown::AddRef、 IUnknown::QueryInterface、 IUnknown::Release、 IDirectDraw2::CreateClipper


IDirectDrawClipper::IsClipListChanged

HRESULT IsClipListChanged(BOOL FAR * lpbChanged);

ウィンドウ・ハンドルがDirectDrawClipperオブジェクトに関連づけられている場合、クリップ・リストの状態をモニタする。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lpbChanged

結果を格納する変数へのポインタ。クリップ・リストが変更された場合、 TRUEがセットされる。


IDirectDrawClipper::SetClipList

HRESULT SetClipList(LPRGNDATA lpClipList, DWORD dwFlags);

DirectDrawClipperの 親オブジェクトがアタッチされるサーフェス上の メソッドIDirectDrawSurface2::Blt、 IDirectDrawSurface2::BltBatch、 IDirectDrawSurface2::UpdateOverlayによって使用されるクリップ・リストをセットするか、削除する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_CLIPPERISUSINGHWND

DDERR_INVALIDCLIPLIST

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

lpClipList

有効なRGNDATA構造体へのポインタ、もしくはNULL。  すでにDirectDrawClipper  に関連づけられたクリップ・リストが存在し、なおかつこの値がNULLであれば、クリップ・リストは削除される。

dwFlags

このパラメータは現在未使用で、0にセットしておかなければならない。

すでにウィンドウ・ハンドルがDirectDrawClipperオブジェクトと関連づけられている場合は、クリップ・リストをセットすることはできない。 IDirectDrawSurface2::BltFastメソッドによる描画は、クリッピングされないことに注意する。

このメソッドで使われるRGNDATA構造体は、次のような文法で使う。

typedef struct _RGNDATA {

    RGNDATAHEADER rdh;

    char          Buffer[1];

} RGNDATA;

RGNDATA構造体のrdhメンバは、次のような文法で使われるRGNDATAHEADER構造体である。

typedef struct _RGNDATAHEADER {

    DWORD dwSize;

    DWORD iType;

    DWORD nCount;

    DWORD nRgnSize;

    RECT  rcBound;

} RGNDATAHEADER;

これらの構造体についての詳細は、 Win32 SDKのドキュメントを参照すること。

参照　IDirectDrawClipper::GetClipList、 IDirectDrawSurface2::Blt、 IDirectDrawSurface2::BltFast、 IDirectDrawSurface2::BltBatch、 IDirectDrawSurface2::UpdateOverlay


IDirectDrawClipper::SetHWnd

HRESULT SetHWnd(DWORD dwFlags, HWND hWnd);

クリッピング情報を含むウィンドウ・ハンドルを設定する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDCLIPLIST

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

dwFlags

このパラメータは現在未使用で、0にセットしておかなければならない。

hWnd

クリッピング情報を含むウィンドウ・ハンドル

参照　IDirectDrawClipper::GetHWnd


IDirectDrawPalette

DirectDrawPaletteオブジェクトを作成しシステム・レベル変数で動作させるには、IDirectDrawPaletteインターフェイスのメソッドを使う。この節は、このインターフェイスのメソッドについてのリファレンスである。概要については、「DirectDrawPaletteオブジェクト」を参照すること。

IDirectDrawPalette  インターフェイスのメソッドは、次のようなグループに分けられる。

メモリ配置	Initialize
パレットの能力	GetCaps
パレット・エントリ	GetEntries
	SetEntries
IDirectDrawPalette インターフェイスは、すべての COMインターフェイスのようにIUnknown メソッドを継承する。 Iunknownインターフェイスは次の3つのメソッドをサポートしている。

AddRef
QueryInterface
Release


IDirectDrawPalette::GetCaps

HRESULT GetCaps(LPDWORD lpdwCaps);

パレット・オブジェクトの能力を取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lpdwCaps

パレットの能力を取得するDDCAPS構造体のdwPalCapsメンバからのフラグ。

DDPCAPS_4BIT

DDPCAPS_8BIT

DDPCAPS_8BITENTRIES

DDPCAPS_ALLOW256

DDPCAPS_PRIMARYSURFACE

DDPCAPS_PRIMARYSURFACELEFT

DDPCAPS_VSYNC


IDirectDrawPalette::GetEntries

HRESULT GetEntries(DWORD dwFlags, DWORD dwBase,

    DWORD dwNumEntries, LPPALETTEENTRY lpEntries);

DirectDrawPalette  オブジェクトからのパレット値を得る。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTPALETTIZED

dwFlags

このパラメータは現在未使用。0にセットしておくこと。

dwBase

エントリの開始インデックス。

dwNumEntries

lpEntriesに指定されたアドレスに適応したパレット・エントリの数。それぞれのパレット・エントリの色は順に返される。 dwStartingEntryの値からパラメータ dwCountをマイナス１した値まで（ これらのパラメータは、IDirectDrawPalette::SetEntries によって可視となる）。

lpEntries

パレット・エントリのアドレス。 DDPCAPS_8BITENTRIESフラグがセットされた場合、パレット・エントリは１バイト毎である。それ以外は4バイト毎となる。各フィールドは色指定である。

参照　IDirectDrawPalette::SetEntries


IDirectDrawPalette::Initialize

HRESULT Initialize(LPDIRECTDRAW lpDD, DWORD dwFlags,

    LPPALETTEENTRY lpDDColorTable);

DirectDrawPaletteオブジェクトを初期化する。

DDERR_ALREADYINITIALIZEDを返す。

lpDD

DirectDrawオブジェクトを意味するDirectDraw構造体のアドレス。

dwFlags and lpDDColorTable

これらのパラメータは現在未使用。0にセットしておくこと。

COM集成化機能と将来の互換性のためにある。現在は NULLを設定しないとDirectDrawPaletteがエラーDDERR_ALREADYINITIALIZEDを返す。

参照　IUnknown::AddRef、 IUnknown::QueryInterface、

IUnknown::Release


IDirectDrawPalette::SetEntries

HRESULT SetEntries(DWORD dwFlags, DWORD dwStartingEntry,

    DWORD dwCount, LPPALETTEENTRY lpEntries);

DirectDrawPaletteオブジェクトのエントリの変更を即座に行う。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOPALETTEATTACHED

DDERR_NOTPALETTIZED

DDERR_UNSUPPORTED

dwFlags

このパラメータは現在未使用。0にセットしておくこと。

dwStartingEntry

セットされる初めてのエントリ。

dwCount

変更されたパレット・エントリ数。

lpEntries

パレット・エントリのアドレス。このパレット・エントリは、 DDPCAPS_8BITENTRIES フラグがセットされると、パレット・エントリは１バイトで、そうでない場合は4バイトである。各フィールドは色指定の記述がされる。

IDirectDrawPalette::SetEntriesを使用する前にIDirectDrawSurface2::SetPalette  メソッドを使って、パレットをアタッチしておかなくてはならない。

参照　IDirectDrawPalette::GetEntries、 IDirectDrawSurface2::SetPalette


IDirectDrawSurface2

アプリケーションは、 IDirectDrawSurface2 インターフェイスのメソッドを使用し、DirectDrawSurface オブジェクトを作成してシステム・レベルで動作する。 この節はこのインターフェイス・メソッドについてのリファレンスである。 概念の概要は、「DirectDrawSurface オブジェクト」を参照すること。

IDirectDrawSurface2 インターフェイスのメソッドは以下のグループに分けられる。

メモリの割り当て	Initialize
	IsLost
	Restore
サーフェスのアタッチ	AddAttachedSurface
	DeleteAttachedSurface
	EnumAttachedSurfaces
	GetAttachedSurface
ブロック転送	Blt
	BltBatch
	BltFast
カラー・キー	GetColorKey
	SetColorKey
デバイス・コンテキスト	GetDC
	ReleaseDC
サーフェス・フリッピング	Flip
サーフェス・ロック	Lock
	PageLock
	PageUnlock
	Unlock
その他	GetDDInterface
オーバーレイ	AddOverlayDirtyRect
	EnumOverlayZOrders
	GetOverlayPosition
	SetOverlayPosition
	UpdateOverlay
	UpdateOverlayDisplay
	UpdateOverlayZOrder
状態	GetBltStatus
	GetFlipStatus
サーフェス能力	GetCaps
サーフェス・クリッパ	GetClipper
	SetClipper
サーフェス記述	GetPixelFormat
	GetSurfaceDesc
サーフェス・パレット	GetPalette
	SetPalette
IDirectDrawSurface2 インターフェイスは、すべての COM インターフェイスと同様、 IUnknown インターフェイス・メソッドを継承する。 IUnknown インターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release


IDirectDrawSurface2::AddAttachedSurface

HRESULT AddAttachedSurface(

    LPDIRECTDRAWSURFACE2 lpDDSAttachedSurface);

サーフェスをもうひとつのサーフェスにアタッチする。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_CANNOTATTACHSURFACE

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACEALREADYATTACHED

DDERR_SURFACELOST

DDERR_WASSTILLDRAWING

lpDDSAttachedSurface

アタッチする DirectDraw サーフェスへのポインタ。

Zバッファ、アルファ・チャネルおよびバック・バッファへのアタッチが可能である。 自動的に他のアタッチを切断(デタッチ)するアタッチもある。 たとえば3D Zバッファがアタッチできるのは一度にひとつのバック・バッファへのみとなっている。 アタッチは双方向的ではなく、サーフェスそれ自身へのアタッチは不可能である。 また、(システム・メモリで)エミュレートされたサーフェスは、エミュレーションでないサーフェスにはアタッチできない。 ひとつのサーフェスがテクスチャ・マップでない場合は、アタッチの対象となるふたつのサーフェスは同じサイズの必要がある。 フリッピングするサーフェスは、同タイプのフリッピング・サーフェスにはアタッチできないが、異なるタイプのふたつのサーフェスをアタッチすることはできる。 たとえば、フリッピングするZバッファをフリッピングする通常のサーフェスにアタッチすることはできる。 フリッピングしないサーフェスが同タイプのやはりフリッピングしないサーフェスにアタッチされると、ふたつのサーフェスはフリッピング・チェーンになる。また、フリッピングしないサーフェスがフリッピングするサーフェスにアタッチされると、既存のフリッピング・チェーンの一部になる。 このチェーンにはサーフェスの追加ができ、IDirectDrawSurface2::Flip メソッドの各呼び出しは、サーフェスの処理を終えると一ステップ進むことができる。

参照　IDirectDrawSurface2::DeleteAttachedSurface、 IDirectDrawSurface2::EnumAttachedSurfaces、 IDirectDrawSurface2::Flip


IDirectDrawSurface2::AddOverlayDirtyRect

HRESULT AddOverlayDirtyRect(LPRECT lpRect);

次にIDirectDrawSurface2::UpdateOverlayDisplayメソッドが呼び出されるときに更新する必要がある矩形のリストを作成する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_UNSUPPORTED

lpRect

更新する必要がある RECT 構造体へのポインタ。

このメソッドはオーバーレイをソフトウェアで実装するときのために使用される。 ハードウェアがオーバーレイをサポートする場合には必要ない。

 参照　IDirectDrawSurface2::UpdateOverlayDisplay


IDirectDrawSurface2::Blt

HRESULT Blt(LPRECT lpDestRect, LPDIRECTDRAWSURFACE2 lpDDSrcSurface,

    LPRECT lpSrcRect, DWORD dwFlags, LPDDBLTFX lpDDBltFx);

ビット・ブロック転送を行う。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDCLIPLIST

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDRECT

DDERR_NOALPHAHW

DDERR_NOBLTHW

DDERR_NOCLIPLIST

DDERR_NODDROPSHW

DDERR_NOMIRRORHW

DDERR_NORASTEROPHW

DDERR_NOROTATIONHW

DDERR_NOSTRETCHHW

DDERR_NOZBUFFERHW

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

lpDestRect

ブロック転送する転送先のサーフェス上の矩形の左上および右下の位置を定義した RECT 構造体のポインタ。

lpDDSrcSurface

ブロック転送操作の転送元である DirectDraw サーフェスのアドレス。

lpSrcRect

ブロック転送される転送元サーフェス上の矩形の左上および右下の場所を定義した RECT 構造体のポインタ。

dwFlags

DDBLT_ALPHADEST

	ピクセル・フォーマットのアルファ情報か、このブロック転送のアルファ・チャネルとして転送先サーフェスにアタッチされたアルファ・チャネル・サーフェスのいずれかを使用する。

DDBLT_ALPHADESTCONSTOVERRIDE

	このブロック転送の転送先サーフェスのアルファ・チャネルとして DDBLTFX構造体の dwAlphaDestConst メンバを使用する。

DDBLT_ALPHADESTNEG

	アルファ値の増加につれ転送先サーフェスが透明化することを表す（0は不透明）。

DDBLT_ALPHADESTSURFACEOVERRIDE

	転送先のアルファ・チャネルとして、 DDBLTFX 構造体のlpDDSAlphaDest メンバを使用する。

DDBLT_ALPHAEDGEBLEND

	カラー・キーの色を縁取る画像のエッジのアルファ・チャネルとして DDBLTFX 構造体のdwAlphaEdgeBlend メンバを使用する。

DDBLT_ALPHASRC

	ピクセル・フォーマットでのアルファ情報か、このブロック転送のアルファ・チャネルとして転送元サーフェスにアタッチされたアルファ・チャネル・サーフェスのいずれかを使用する。

DDBLT_ALPHASRCCONSTOVERRIDE

	転送元サーフェスのアルファ・チャネルとして DDBLTFX 構造体の dwAlphaSrcConst メンバを使用する。

DDBLT_ALPHASRCNEG

	アルファ値の増加につれ転送元サーフェスが透明化することを表す（0は不透明）。

DDBLT_ALPHASRCSURFACEOVERRIDE

	転送元のアルファ・チャネルとして DDBLTFX 構造体のlpDDSAlphaSrc メンバを使用する。

DDBLT_ASYNC

	受け取り順のFIFO を通してこのブロック転送を非同期実行する。 FIFO ハードウェアの空領域が利用可能でないなら、呼び出しは失敗する。

DDBLT_COLORFILL

	転送先サーフェス上の転送先矩形を埋める RGB 色として DDBLTFX 構造体のdwFillColor メンバを使用する。

DDBLT_DDFX

	このブロック転送に使用する効果を指定するために DDBLTFX 構造体のdwDDFX メンバを使用する。

DDBLT_DDROPS

	Win32 APIに含まれないラスタ処理（ ROPS ）を指定するためにDDBLTFX 構造体のdwDDROPS メンバを使用する。

DDBLT_DEPTHFILL

	転送先Zバッファ・サーフェス上の転送先矩形を埋める深度値としてDDBLTFX 構造体のdwFillDepth メンバを使用する。

DDBLT_KEYDEST

	転送先サーフェスと関連づけられたカラー・キーを使用する。

DDBLT_KEYDESTOVERRIDE

	転送先サーフェスのカラー・キーとして DDBLTFX 構造体のdckDestColorkey メンバを使用する。

DDBLT_KEYSRC

	転送元サーフェスと関連づけられたカラー・キーを使用する。

DDBLT_KEYSRCOVERRIDE

	転送元サーフェスのカラー・キーとして DDBLTFX 構造体のdckSrcColorkey メンバを使用する。

DDBLT_ROP

	このブロック転送におけるROP に DDBLTFX 構造体の dwROP メンバを使用する。 これらの ROP は Win32 API で定義されているものと同じである。

DDBLT_ROTATIONANGLE

	サーフェスの回転角（1/100度単位で指定される）としてDDBLTFX 構造体の dwRotationAngle メンバを使用する。

DDBLT_WAIT

	ブロック転送がビジーの場合、 DDERR_WASSTILLDRAWING返値をすぐに返さずに待つ。そしてブロック転送の準備ができるかあるいは他のエラーが発生次第、ただちに戻る。

DDBLT_ZBUFFER

	サーフェスの転送元と転送先とにアタッチされた Zバッファ、そしてZバッファのオペコードとしてのDDBLTFX 構造体の dwZBufferOpCode メンバを使用し、 Zバッファ・ブロック転送を実行する。

DDBLT_ZBUFFERDESTCONSTOVERRIDE

	転送先について、DDBLTFX 構造体のdwZDestConstおよび dwZBufferOpCode メンバをそれぞれ ZバッファおよびZバッファ・オペコードとして使用し、 Zバッファ・ブロック転送を実行する。

DDBLT_ZBUFFERDESTOVERRIDE

	転送先について、DDBLTFX 構造体の lpDDSZBufferDest および dwZBufferOpCode メンバをそれぞれ ZバッファおよびZバッファ ・オペコードとして使用し、 Zバッファ・ブロック転送を実行する。

DDBLT_ZBUFFERSRCCONSTOVERRIDE

	転送元について、 DDBLTFX 構造体の dwZSrcConst およびdwZBufferOpCode メンバをそれぞれZバッファおよびZバッファ・オペコードとして使用し、 Zバッファ・ブロック転送を実行する。

DDBLT_ZBUFFERSRCOVERRIDE

	転送元について、 DDBLTFX 構造体の lpDDSZBufferSrc および dwZBufferOpCode メンバをそれぞれ  ZバッファおよびZバッファ・オペコードとして使用し、 Zバッファ・ブロック転送を実行する。
lpDDBltFx

DDBLTFX 構造体のアドレス。

このメソッドは同期あるいは非同期のブロック転送を、ディスプレイ・メモリからディスプレイ・メモリへ、ディスプレイ・メモリからシステム・メモリへ、システム・メモリからディスプレイ・メモリへ、システム・メモリからシステム・メモリへ、のいずれかで行う能力を持ち、Z情報やアルファ情報、転送元カラー・キー、転送先カラー・キーを使用してブロック転送を実行することができる。転送元と転送先との矩形の大きさが異なる場合、任意の拡大または縮小が実行される。

通常、IDirectDrawSurface2::Bltはブロック転送実行中の場合、もしくはブロック転送をセットアップできなかった場合、エラーを返してただちに戻る。しかし、DDBLT_WAIT フラグを指定すれば、ブロック転送を準備完了するか別のエラーが発生する時まで、メソッドを待機させる。


IDirectDrawSurface2::BltBatch

HRESULT BltBatch(LPDDBLTBATCH lpDDBltBatch,

    DWORD dwCount, DWORD dwFlags);

いくつかの転送元からひとつの転送先へ、まとめて IDirectDrawSurface2::Blt処理を実行する。 このメソッドは現在定義されてはいるものの、実装はまだなされていない。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDCLIPLIST

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDRECT

DDERR_NOALPHAHW

DDERR_NOBLTHW

DDERR_NOCLIPLIST

DDERR_NODDROPSHW

DDERR_NOMIRRORHW

DDERR_NORASTEROPHW

DDERR_NOROTATIONHW

DDERR_NOSTRETCHHW

DDERR_NOZBUFFERHW

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

lpDDBltBatch

ブロック転送のためのパラメータを定義する最初の DDBLTBATCH 構造体のポインタ。

dwCount

実行するブロック転送操作の数。

dwFlags

このパラメータは現在未使用。0にセットしておくこと。


IDirectDrawSurface2::BltFast

HRESULT BltFast(DWORD dwX, DWORD dwY,

    LPDIRECTDRAWSURFACE2 lpDDSrcSurface, LPRECT lpSrcRect,

    DWORD dwTrans);

転送元カラー・キーあるいは転送先カラー・キーを使用し、転送元コピー・ブロック転送あるいは透過型ブロック転送を実行する。このメソッドはハードウェアが非同期ブロック転送をサポートする場合、常に非同期ブロック転送を試みる。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_EXCEPTION

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDRECT

DDERR_NOBLTHW

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

dwX and dwY

転送先サーフェス上にブロック転送するｘ座標およびｙ座標。

lpDDSrcSurface

ブロック転送操作の転送元 DirectDraw サーフェスのポインタ。

lpSrcRect

ブロック転送される転送元サーフェス上の矩形の左上および右下の座標を定義する RECT 構造体のポインタ。

dwTrans

転送タイプ。

DDBLTFAST_DESTCOLORKEY

	転送先のカラー・キーを使用する透過型ブロック転送を指定する。

DDBLTFAST_NOCOLORKEY

	透過でない通常のコピー・ブロック転送を指定する。

DDBLTFAST_SRCCOLORKEY

	転送元のカラー・キーを使用する透過型ブロック転送を指定する。

DDBLTFAST_WAIT

	ブロック転送がビジーの場合、 DDERR_WASSTILLDRAWING返値をすぐには返さずに待つ。そしてブロック転送の準備ができるかあるいは他のエラーが発生次第、ただちに戻る。
このメソッドはディスプレイ・メモリ・サーフェス上のみで動作し、ブロック転送中はフリッピングできない。 IDirectDrawSurface2::BltFastのソフトウェア実装は IDirectDrawSurface2::Bltメソッドよりも10パーセント速い。 しかし、ディスプレイ・ハードウェアが使用されている場合には、両者の間でスピードの差異はない。

通常、IDirectDrawSurface2::BltFastはブロック転送実行中の場合、もしくはブロック転送をセットアップできなかった場合、エラーを返してただちに戻る。DDBLT_WAIT フラグはこの動作を変更し、ブロック転送を準備完了するか別のエラーが発生するまで、メソッドを待機させる。


IDirectDrawSurface2::DeleteAttachedSurface

HRESULT DeleteAttachedSurface(DWORD dwFlags,

    LPDIRECTDRAWSURFACE2 lpDDSAttachedSurface);

ふたつのアタッチされているサーフェスを切り離す(デタッチする)。デタッチされたサーフェスは解放されない。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_CANNOTDETACHSURFACE

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

DDERR_SURFACENOTATTACHED

dwFlags

このパラメータは現在未使用のため、0にセットしておかなければならない。

lpDDSAttachedSurface

デタッチされる DirectDraw サーフェスのアドレス。 このパラメータがNULLの場合、アタッチされているすべてのサーフェスがデタッチされる。

IDirectDrawSurface2::AddAttachedSurfaceメソッドにより明示的にアタッチしたサーフェスをデタッチする。ただし DirectDrawが暗黙的に行ったアタッチ・サーフェスはデタッチされない。 フリッピング・チェーンからサーフェスをデタッチすると、チェーン中の他サーフェスは変更される可能性がある。フロント・バッファをフリッピング・チェーンからデタッチすると、チェーン中の次サーフェスはフロント・バッファになり、その次のサーフェスはバック・バッファになる。 バック・バッファをチェーンからデタッチすると、次サーフェスはバック・バッファになる。 ふつうのサーフェスをチェーンからデタッチすると、チェーンは短くなるだけである。 サーフェスがふたつしかないフリッピングチェーンをデタッチすると、チェーンは破棄されて双方のサーフェスは以前の状態に戻る。

参照　IDirectDrawSurface2::Flip


IDirectDrawSurface2::EnumAttachedSurfaces

HRESULT EnumAttachedSurfaces(LPVOID lpContext,

    LPDDENUMSURFACESCALLBACK lpEnumSurfacesCallback);

指定されたサーフェスにアタッチされているすべてのサーフェスを列挙する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

lpContext

コールバック関数に渡される、アプリケーションが定義した構造体へのポインタ。

lpEnumSurfacesCallback

アタッチされているサーフェス毎に呼び出される EnumSurfacesCallback 関数のポインタ。


IDirectDrawSurface2::EnumOverlayZOrders

HRESULT EnumOverlayZOrders(DWORD dwFlags, LPVOID lpContext,

    LPDDENUMSURFACESCALLBACK lpfnCallback);

指定された転送先上のオーバーレイ・サーフェスを列挙する。 フロントからバックへ、あるいはバックからフロントへ、など列挙する順序を指定できる。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

dwFlags

以下のフラグのうちどちらかひとつの値を取る。

DDENUMOVERLAYZ_BACKTOFRONT

	バックからフロントへ向かいオーバーレイを列挙する。

DDENUMOVERLAYZ_FRONTTOBACK

	フロントからバックへ向かいオーバーレイを列挙する。
lpContext

各オーバーレイ・サーフェスのコールバック関数に渡されるユーザ定義コンテキストへのポインタ。

lpfnCallback

このサーフェス上にオーバーレイされたサーフェス毎に呼び出されるの fnCallback 関数のポインタ。


IDirectDrawSurface2::Flip

HRESULT Flip(

    LPDIRECTDRAWSURFACE2 lpDDSurfaceTargetOverride,

    DWORD dwFlags);

DDSCAPS_BACKBUFFER サーフェスと関連づけられたサーフェス・メモリを、フロント・バッファ・サーフェスと関連づける。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOFLIPHW

DDERR_NOTFLIPPABLE

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

lpDDSurfaceTargetOverride

フリッピングされる DirectDraw サーフェスのポインタ。 このパラメータのデフォルトはNULLであり、このときIDirectDrawSurface2::Flipはバッファ中で互いにアタッチされている順にサイクルする。このパラメータはオーバーライドとしてだけ使用される。

dwFlags

DDFLIP_WAIT

	一般に、ディスプレイ・ハードウェアの状態が適切でなくフリッピングの準備ができない場合、 DDERR_WASSTILLDRAWING エラーがただちに返り、フリッピングは起こらない。しかし、このフラグをセットすると、 HALからDDERR_WASSTILLDRAWING エラーを受け取ってもIDirectDrawSurface2::Flipはフリッピングしようとし続ける。 その場合IDirectDrawSurface2::Flipはフリッピング処理が成功するか、 DDERR_SURFACEBUSYのような別のエラーが返されるまで戻らない。
このメソッドを呼び出すことができるのは、 DDSCAPS_FLIPおよび DDSCAPS_FRONTBUFFERがセットされたサーフェスだけである。このメソッドを呼び出す以前にフロント・バッファと関連づけられていたディスプレイ・メモリは、バック・バッファと関連づけられる。 複数のバック・バッファがある場合はリングが形成され、サーフェス・メモリ・バッファは IDirectDrawSurface2::Flipが呼び出されるたびにそのリングを１サイクルする。

lpDDSurfaceTargetOverride パラメータは、バック・バッファがフロント・バッファになるべきバッファではないという、まれなケースで使われる。 一般にはこのパラメータはNULLである。

IDirectDrawSurface2::Flipメソッドはつねに垂直帰線と同期する。

参照　IDirectDrawSurface2::GetFlipStatus


IDirectDrawSurface2::GetAttachedSurface

HRESULT GetAttachedSurface(LPDDSCAPS lpDDSCaps,

    LPDIRECTDRAWSURFACE2 FAR * lplpDDAttachedSurface);

指定された能力を持つ、アタッチされたサーフェスを取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTFOUND

DDERR_SURFACELOST

lpDDSCaps

サーフェスのハードウェア能力を持つ DDSCAPS 構造体のアドレス。

lplpDDAttachedSurface

EnumSurfacesCallback コールバック関数の lpDDSurface パラメータが指定する現在の DirectDraw サーフェスにアタッチされ、かつlpDDSCaps パラメータの指定に見合う能力を持った DirectDraw サーフェスへのポインタのアドレス。

アタッチは、複数のDirectDrawSurface オブジェクトを複合構造体に接続するために使用される。複合構造体は、Zバッファによる３Ｄページ・フリッピングのサポートに必要なものなどである。 要求された能力に見合うサーフェスがひとつ以上アタッチされていると、このメソッドは失敗する。 この場合、アプリケーションはアタッチされているサーフェスを得るためにIDirectDrawSurface2::EnumAttachedSurfacesメソッドを使用しなければならない。


IDirectDrawSurface2::GetBltStatus

HRESULT GetBltStatus(DWORD dwFlags);

ブロック転送ハードウェアの状態を取得する。

ブロック転送ハードウェアが存在するなら DD_OK を返す、ブロック転送ハードウェアがビジーなら DDERR_WASSTILLDRAWING 、ブロック転送ハードウェアが存在しないなら DDERR_NOBLTHW、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOBLTHW

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

dwFlags

以下のフラグのうちどちらかひとつを取る。

DDGBS_CANBLT

	このサーフェスに関わるブロック転送をただちに実行できるかどうかを問い合わせ、ブロック転送を完了できる場合DD_OK を返す。

DDGBS_ISBLTDONE

	ブロック転送が行われたかどうかを問い合わせ、このサーフェスの最後のブロック転送が完了しているならDD_OK を返す。


IDirectDrawSurface2::GetCaps

HRESULT GetCaps(LPDDSCAPS lpDDSCaps);

サーフェスの能力を取得する。 これらの能力はディスプレイ・デバイスの能力とは無関係でもよい。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lpDDSCaps

サーフェスのハードウェア能力が入る DDSCAPS 構造体のアドレス。


IDirectDrawSurface2::GetClipper

HRESULT GetClipper(LPDIRECTDRAWCLIPPER FAR * lplpDDClipper);

このサーフェスと関連づけられた DirectDrawClipper オブジェクトを取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOCLIPPERATTACHED

lplpDDClipper

サーフェスと関連づけられた DirectDrawClipper オブジェクトへのポインタのアドレス。

参照　IDirectDrawSurface2::SetClipper


IDirectDrawSurface2::GetColorKey

HRESULT GetColorKey(DWORD dwFlags, LPDDCOLORKEY lpDDColorKey);

DirectDrawSurface オブジェクトのカラー・キー値を取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOCOLORKEY

DDERR_NOCOLORKEYHW

DDERR_SURFACELOST

DDERR_UNSUPPORTED

dwFlags

どのカラー・キーが要求されるか指定する。

DDCKEY_DESTBLT

	構造体はカラー・キーあるいはブロック転送において転送先カラー・キーとして使われる色空間 を指定する。

DDCKEY_DESTOVERLAY

	構造体はカラー・キーあるいはオーバー・レイ処理において転送先カラー・キーとして使われる色空間を指定する。

DDCKEY_SRCBLT

	構造体はカラー・キーあるいはブロック転送において転送元カラー・キーとして使われる色空間を指定する。

DDCKEY_SRCOVERLAY

	構造体はカラー・キーあるいはオーバーレイ処理において転送元カラー・キーとして使われる色空間を指定する。
lpDDColorKey

DirectDrawSurface オブジェクトの指定されたカラー・キーの現在の値を格納するDDCOLORKEY  構造体のポインタ。

参照　IDirectDrawSurface2::SetColorKey


IDirectDrawSurface2::GetDC

HRESULT GetDC(HDC FAR * lphDC);

サーフェスのデバイス・コンテキストの GDI互換ハンドルを作成する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_DCALREADYCREATED

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

lphDC

デバイス・コンテキストが返されるハンドルへのポインタ。

このメソッドは、サーフェスのロックにIDirectDrawSurface2::Lockメソッドの内部バージョンを使用する。 サーフェスは 、IDirectDrawSurface2::ReleaseDCメソッドが呼び出されない限り、ロックが維持される。

参照　IDirectDrawSurface2::Lock


IDirectDrawSurface2::GetDDInterface

HRESULT GetDDInterface(LPVOID FAR *lplpDD);

サーフェスを作成するために使用された DirectDraw オブジェクトへのインターフェイスを取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lplpDD

DirectDraw ポインタが返されるポインタのアドレス。 呼び出しが失敗した場合、この値は無効となる。

このメソッドはIDirectDraw2インターフェイスから追加されたもので、 IDirectDraw インターフェイスには実装されていない。


IDirectDrawSurface2::GetFlipStatus

HRESULT GetFlipStatus(DWORD dwFlags);

サーフェスがフリッピング処理を終えたかどうかを取得する。

成功すれば DD_OK 、サーフェスがフリッピング処理を終えていなければ DDERR_WASSTILLDRAWING 、その他の理由で失敗したら次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

dwFlags

以下のフラグのうちひとつを指定する。

DDGFS_CANFLIP

	このサーフェスをただちにフリッピングできるかどうかを問い合わせ、フリッピングを完了できる場合 DD_OKが返る。

DDGFS_ISFLIPDONE

	フリッピングが行われたかどうか問い合わせ、このサーフェスの最後のフリッピングが完了していた場合にはDD_OK を返す。
参照　IDirectDrawSurface2::Flip


IDirectDrawSurface2::GetOverlayPosition

HRESULT GetOverlayPosition(LPLONG lplX, LPLONG lplY);

可視のアクティブ・オーバーレイ・サーフェス（ DDSCAPS_OVERLAY フラグがセットされているもの）のディスプレイ座標を返す。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDPOSITION

DDERR_NOOVERLAYDEST

DDERR_NOTAOVERLAYSURFACE

DDERR_OVERLAYNOTVISIBLE

DDERR_SURFACELOST

lplX and lplY

xディスプレイ座標およびyディスプレイ座標のポインタ。

参照　IDirectDrawSurface2::SetOverlayPosition、 IDirectDrawSurface2::UpdateOverlay


IDirectDrawSurface2::GetPalette

HRESULT GetPalette(LPDIRECTDRAWPALETTE FAR * lplpDDPalette);

サーフェスに関連づけられた DirectDrawPalette 構造体を取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOEXCLUSIVEMODE

DDERR_NOPALETTEATTACHED

DDERR_SURFACELOST

DDERR_UNSUPPORTED

lplpDDPalette

取得するサーフェスと関連づけられた DirectDrawPalette 構造体のポインタへのアドレス。 このサーフェスと関連づけられた DirectDrawPalette 構造体がない場合、 NULL にセットされる。 このパラメータは、サーフェスがプライマリ・サーフェスの場合、もしくはプライマリ・サーフェスのバック・バッファで、かつプライマリ・サーフェスが8 bppモードである場合、システム・パレットへのポインタを持つ。

参照　IDirectDrawSurface2::SetPalette


IDirectDrawSurface2::GetPixelFormat

HRESULT GetPixelFormat(LPDDPIXELFORMAT lpDDPixelFormat);

サーフェスのカラーとピクセル・フォーマットを取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

lpDDPixelFormat

現在ピクセルの詳細情報とサーフェスの色空間 ・フォーマットの詳細な記述を取得する DDPIXELFORMAT 構造体へのポインタ。


IDirectDrawSurface2::GetSurfaceDesc

HRESULT GetSurfaceDesc(LPDDSURFACEDESC lpDDSurfaceDesc);

サーフェスの現在の状態を 指定したDDSURFACEDESC 構造体に取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

lpDDSurfaceDesc

サーフェスの状態を取得するDDSURFACEDESC 構造体へのポインタ。

参照　DDSURFACEDESC


IDirectDrawSurface2::Initialize

HRESULT Initialize(LPDIRECTDRAW lpDD,

    LPDDSURFACEDESC lpDDSurfaceDesc);

DirectDrawSurface オブジェクトを初期化する。

DDERR_ALREADYINITIALIZEDを返す。

lpDD

DirectDraw オブジェクトを表す DirectDraw 構造体のポインタ。

lpDDSurfaceDesc

サーフェスについての詳細情報が設定された DDSURFACEDESC  構造体へのポインタ。

このメソッドはコンポーネント・オブジェクト・モデル（ COM ）プロトコルに基づき提供される。 DirectDrawSurface オブジェクトは作成されたときに初期化されるので、このメソッドは常に DDERR_ALREADYINITIALIZED を返す。

参照　IUnknown::AddRef、 IUnknown::QueryInterface、 IUnknown::Release


IDirectDrawSurface2::IsLost

HRESULT IsLost();

DirectDrawSurface オブジェクトが管理するサーフェス・メモリがなんらかの原因によって失われたかどうかを判断する。

失われていなければ DD_OK 、そうでなければ次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

サーフェス・メモリの再割り当てのために、このメソッドを使用することができる。 DirectDrawSurface オブジェクトがサーフェス・メモリを失うと、大部分のメソッドは DDERR_SURFACELOST を返して他の処理を実行しない。

ディスプレイ・カードのモードを変更する時、あるいはアプリケーションがディスプレイ・カードへの排他的なアクセスを受け取って現在ディスプレイ・カード上に割り当てられているサーフェス・メモリのすべてを解放する時には、サーフェスはメモリを失う可能性がある。

参照　IDirectDrawSurface2::Restore


IDirectDrawSurface2::Lock

HRESULT Lock(LPRECT lpDestRect, LPDDSURFACEDESC lpDDSurfaceDesc,

    DWORD dwFlags, HANDLE hEvent);

サーフェス・メモリへのポインタを取得する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_WASSTILLDRAWING

lpDestRect

ロックするサーフェス領域を示す RECT 構造体のポインタ。

lpDDSurfaceDesc

サーフェスについての情報を指定する DDSURFACEDESC 構造体へのポインタ。

dwFlags

DDLOCK_EVENT

	IDirectDrawSurface2::Lockが要求されたサーフェス・メモリのポインタを返すことが可能なときにイベントを駆動するフラグ。イベント・ハンドルがIDirectDrawSurface2::Lock に渡されている場合、セットされる。 このタイプのロックがサーフェス上に複数あるとき、イベントはFIFO 順で引き起こされる。

DDLOCK_READONLY

	ロックするサーフェスは読み出し専用であることを示すフラグ。

DDLOCK_SURFACEMEMORYPTR

	指定した矩形の先頭への有効なメモリ・ポインタを返さなければならないことを表すフラグ。 矩形が指定されない場合、一番上のサーフェスへのポインタが返される。 デフォルトではこのフラグを指定する。

DDLOCK_WAIT

	通常、ブロック転送処理がビジー状態のためロックを得られない場合、メソッドは直ちに終了し、 DDERR_WASSTILLDRAWING エラーを返す。 しかしこのフラグをセットした場合、ロックが得られるか DDERR_SURFACEBUSYなど、別のエラーが発生するまでIDirectDrawSurface2::Lockを再試行する。

DDLOCK_WRITEONLY

	ロックするサーフェスは書きこみ専用であることを示す。
hEvent

サーフェスのロックの準備ができた瞬間をトリガとするシステム・イベントへのハンドル。

ポインタを取得した後、対応する IDirectDrawSurface2::Unlockメソッドを呼び出すまで、アプリケーションはサーフェス・メモリにアクセスすることができる。 IDirectDrawSurface2::Unlockメソッド呼び出し後は、サーフェス・メモリへのポインタは無効になる。

アプリケーションは、ロックされたサーフェスの領域でブロック転送することはできない。 ロックされたサーフェス上でブロック転送が試みられた場合、ブロック転送は DDERR_SURFACEBUSY あるいは DDERR_LOCKEDSURFACES エラーを返す。

一般に、ブロック転送処理中であるという理由でロックを取得できない場合、 IDirectDrawSurface2::Lockはエラーを返して戻る。 ロックが取得できるまで待っても良い場合、 DDLOCK_WAIT フラグを使用する。

サーフェスへのアクセス中にディスプレイ・メモリが失われるのを防ぐため、 DirectDraw は IDirectDrawSurface2::Lockおよび IDirectDrawSurface2::Unlock操作の間に、 Win16 ロックを保持している。 Win16ロックは GDI とUSERのアクセス実行にかかわる重大な部分であり、このテクニックによりディスプレイ・メモリへの直接アクセスが可能になっている。そのアクセス中には他のアプリケーションはモード変更ができないが、Windowsの動作が止まってしまう。そのため、 IDirectDrawSurface2::Lock/IDirectDrawSurface2::Unlockから IDirectDrawSurface2::GetDC/IDirectDrawSurface2::ReleaseDCの期間はできる限り短くするべきである。 この期間、Windowsが止まってしまうため、GUIデバッガの使用ができなくなる。

参照　IDirectDrawSurface2::Unlock、 IDirectDrawSurface2::GetDC、 IDirectDrawSurface2::ReleaseDC


IDirectDrawSurface2::PageLock

HRESULT PageLock(DWORD dwFlags);

ダイレクト・メモリ・アクセス (DMA) 転送を用いたシステム・メモリ内の転送、あるいはシステム・メモリを含むブロック転送の処理中、システム・メモリ・サーフェスがページ・アウトされることを防ぐ。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_CANTPAGELOCK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

dwFlags

このパラメータは現在未使用。0にセットしておくこと。

ロックはオペレーティング・システムのパフォーマンスに悪影響を与える。

ロック・カウントはそれぞれのサーフェスのために保持され、IDirectDrawSurface2::PageLock呼び出しをするたびにインクリメントされ、IDirectDrawSurface2::PageUnlockが呼び出されたときデクリメントされる。 カウントが0に達した時、メモリがロックを解除し、システム・メモリ・サーフェスをオペレーティング・システムがページング対象とできるようになる。

このメソッドはシステム・メモリ・サーフェス上でのみ動作する。ディスプレイ・メモリ・サーフェスあるいはエミュレートされたプライマリ・サーフェスをページ・ロックすることはできない。もしディスプレイ・メモリ・サーフェス上でこのメソッドを呼び出した場合、メソッドは DD_OKを返す以外は何もしない。

このメソッドはIDirectDraw2インターフェイスから追加されたもので、 IDirectDraw インターフェイスには実装されていない。

参照　IDirectDrawSurface2::PageUnlock


IDirectDrawSurface2::PageUnlock

HRESULT PageUnlock(DWORD dwFlags);

システム・メモリ・サーフェスのロックを解除し、ページ・アウトできるようにする。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_CANTPAGEUNLOCK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTPAGELOCKED

DDERR_SURFACELOST

dwFlags

このパラメータは現在未使用。0にセットしておくこと。

ロック・カウントはそれぞれのサーフェスについて保持され、IDirectDrawSurface2::PageLock呼び出しによつてインクリメントされ、 IDirectDrawSurface2::PageUnlockの呼び出しの際にデクリメントされる。 カウントが0に達した時、メモリはロックを解除され、オペレーティング・システムはそのシステム・メモリ・サーフェスをページング対象とできるようになる。

このメソッドはシステム・メモリ・サーフェス上でのみ動作する。ディスプレイ・メモリ・サーフェスやエミュレートされたプライマリ・サーフェスのページ・ロックはできない。ディスプレイ・メモリ・サーフェス上でこのメソッドを呼び出しても、メソッドは DD_OKを返すだけである。

このメソッドはIDirectDraw2インターフェイスから追加されたもので、 IDirectDraw インターフェイスには実装されていない。

参照　IDirectDrawSurface2::PageLock


IDirectDrawSurface2::ReleaseDC

HRESULT ReleaseDC(HDC hDC);

IDirectDrawSurface2::GetDC method.

HRESULT ReleaseDC(
メソッドを使用して取得したデバイス・コンテキストのハンドルを解放する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

DDERR_UNSUPPORTED

hDC

IDirectDrawSurface2::GetDCメソッドを使用して取得したデバイス・コンテキストのハンドル。

このメソッドによって、前回 IDirectDrawSurface2::GetDCメソッドを呼び出した時のサーフェスのロックが解除される。

参照　IDirectDrawSurface2::GetDC


IDirectDrawSurface2::Restore

HRESULT Restore();

失ったサーフェスをリストアする。 これは DirectDrawSurface オブジェクトと関連づけられたサーフェス・メモリが解放されたとき発生する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_IMPLICITLYCREATED

DDERR_INCOMPATIBLEPRIMARY

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOEXCLUSIVEMODE

DDERR_OUTOFMEMORY

DDERR_UNSUPPORTED

DDERR_WRONGMODE

ディスプレイ・カードのモード変更時や、アプリケーションがディスプレイ・カードへの排他アクセスを受け取って現在カード上に割り当てられているサーフェス・メモリのすべてを解放する時には、サーフェスが失われる可能性がある。 DirectDrawSurface オブジェクトがそのサーフェス・メモリを失ったとき、多くのメソッドは DDERR_SURFACELOST を返し、他のあらゆる機能の実行が不可能になる。 IDirectDrawSurface2::Restoreメソッドはサーフェス・メモリを再割り当てし、 DirectDrawSurface オブジェクトにそれを再アタッチする。

このメソッドの呼び出しを行うと、 DirectDrawSurface オブジェクトに関連づけられた暗黙のサーフェス（バック・バッファなど）がリストアされる。 暗黙的に作られたサーフェスをリストアする試みはエラーとなる。 IDirectDrawSurface2::RestoreはIDirectDrawSurface2::AddAttachedSurfaceメソッドを使用して作成された明示的なアタッチまでは自動的にリストアしない（ これらのサーフェスはそれぞれが個々にリストアさせられなくてはならない）。

参照　IDirectDrawSurface2::IsLost、 IDirectDrawSurface2::AddAttachedSurface


IDirectDrawSurface2::SetClipper

HRESULT SetClipper(LPDIRECTDRAWCLIPPER lpDDClipper);

DirectDrawClipper オブジェクトを DirectDrawSurface オブジェクトにアタッチする。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_NOCLIPPERATTACHED

lpDDClipper

DirectDrawSurface オブジェクトにアタッチする DirectDrawClipper オブジェクトを表している DirectDrawClipper 構造体のポインタ。 もしこのパラメータがゼロならば、現在の DirectDrawClipper オブジェクトをデタッチすることを意味する。

このメソッドは主にサーフェスが最初のサーフェスの上にオーバーレイされるか、あるいはブロック転送されるために使用され、あらゆるサーフェス上で使用できる。  DirectDrawClipper オブジェクトがアタッチされ、そしてクリップ・リストがそれと結び付けられた後、 DirectDrawClipper オブジェクトはIDirectDrawSurface2::Blt、 IDirectDrawSurface2::BltBatch、 および IDirectDrawSurface2::UpdateOverlay 処理のために使用される。このメソッドは DirectDrawSurface オブジェクトの現在の DirectDrawClipper オブジェクトをデタッチすることができる。

このメソッドが同じ DirectDrawClipper オブジェクトに対して同一サーフェス上で連続して数回呼び出さた場合でも、オブジェクトの参照カウントは１しか増加しない。 重複する呼び出しは、オブジェクトの参照カウントに影響を与えない。

参照　IDirectDrawSurface2::GetClipper


IDirectDrawSurface2::SetColorKey

HRESULT SetColorKey(DWORD dwFlags, LPDDCOLORKEY lpDDColorKey);

ハードウェアがサーフェス・ベース毎にカラー・キーをサポートする場合、 DirectDrawSurface オブジェクトのカラー・キー値をセットする。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_NOOVERLAYHW

DDERR_NOTAOVERLAYSURFACE

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

dwFlags

いずれのカラー・キーが要求されるか指定する。

DDCKEY_COLORSPACE

	構造体が色空間を含んでいる場合セットする。 構造体が単一のカラー・キーを含んでいるときはセットしてはいけない。

DDCKEY_DESTBLT

	ブロック転送の転送先カラー・キーとして使用されるカラー・キーあるいは転送先色空間を構造体が指定している場合セットする。

DDCKEY_DESTOVERLAY

	オーバーレイ処理の転送先カラー・キーとして使用されるカラー・キーあるいは転送先色空間を構造体が指定している場合セットする。

DDCKEY_SRCBLT

	ブロック転送の転送元カラー・キーとして使用されるカラー・キーあるいは転送先色空間を構造体が指定している場合セットする。

DDCKEY_SRCOVERLAY

	オーバーレイ処理の転送元カラー・キーとして使用されるカラー・キーあるいは転送先色空間を構造体が指定している場合セットする。
lpDDColorKey

DirectDrawSurface オブジェクトの新しいカラー・キー値を含んでいる DDCOLORKEY 構造体のポインタ。

参照　IDirectDrawSurface2::GetColorKey


IDirectDrawSurface2::SetOverlayPosition

HRESULT SetOverlayPosition(LONG lX, LONG lY);

オーバーレイ・サーフェスのディスプレイ座標を変える。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

DDERR_UNSUPPORTED

lX and lY

新しいｘディスプレイ座標およびｙディスプレイ座標。

参照　IDirectDrawSurface2::GetOverlayPosition、IDirectDrawSurface2::UpdateOverlay


IDirectDrawSurface2::SetPalette

HRESULT SetPalette(LPDIRECTDRAWPALETTE lpDDPalette);

指定された DirectDrawPalette オブジェクトをサーフェスにアタッチする。 サーフェスは以降の処理ではこのパレットを使用する。 パレット変更はリフレッシュ・タイミングに関係なく即座に行われる。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_NOEXCLUSIVEMODE

DDERR_NOPALETTEATTACHED

DDERR_NOPALETTEHW

DDERR_NOT8BITCOLOR

DDERR_SURFACELOST

DDERR_UNSUPPORTED

lpDDPalette

DirectDrawPalette 構造体のポインタ。

このメソッドが同一サーフェス上で連続して数回呼び出された場合でも、パレットの参照カウントは１つ増加するだけである。重複する呼び出しはパレットの参照カウントに影響を与えない。

参照　IDirectDrawSurface2::GetPalette、IDirectDraw2::CreatePalette


IDirectDrawSurface2::Unlock

HRESULT Unlock(LPVOID lpSurfaceData);

DirectDraw に直接サーフェス操作が終了したことを知らせる。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDRECT

DDERR_NOTLOCKED

DDERR_SURFACELOST

lpSurfaceData

IDirectDrawSurface2::Lockメソッドによって返されたポインタのアドレス。同じサーフェスで異なる転送先矩形のために複数の IDirectDrawSurface2::Lock呼び出しが可能であり、このポインタは IDirectDrawSurface2::Lockおよび IDirectDrawSurface2::Unlock呼び出しとを結び付ける。

参照　IDirectDrawSurface2::Lock


IDirectDrawSurface2::UpdateOverlay

HRESULT UpdateOverlay(LPRECT lpSrcRect,

    LPDIRECTDRAWSURFACE2 lpDDDestSurface,

    LPRECT lpDestRect, DWORD dwFlags,

    LPDDOVERLAYFX lpDDOverlayFx);

オーバーレイ・サーフェスの視覚属性を置換または修正する。 これらのサーフェスは DDSCAPS_OVERLAY 値セットを持っていなくてはならない。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_GENERIC

DDERR_HEIGHTALIGN

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDRECT

DDERR_INVALIDSURFACETYPE

DDERR_NOSTRETCHHW

DDERR_NOTAOVERLAYSURFACE

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_XALIGN

lpSrcRect

転送元サーフェスがオーバーレイで使う ｘ幅 、ｙ幅および領域の高さを定義する RECT 構造体のポインタ。

lpDDDestSurface

オーバーレイされている DirectDraw サーフェスのポインタ。

lpDestRect

オーバーレイが行われる転送先サーフェスの上に ｘ幅 、ｙ幅および領域の高さを定義する RECT 構造体のポインタ。

dwFlags

DDOVER_ADDDIRTYRECT

	エミュレーションでオーバーレイされたサーフェスに、更新しなければならない領域を加える。

DDOVER_ALPHADEST

	ピクセル・フォーマットでのアルファ情報あるいはアルファ・チャネル・サーフェスを、このオーバーレイの転送先アルファ・チャネルとしてサーフェスにアタッチするために使用する。

DDOVER_ALPHADESTCONSTOVERRIDE

	このオーバーレイの転送先アルファ・チャネルとしてDDOVERLAYFX 構造体の dwAlphaDestConst メンバを使用する。

DDOVER_ALPHADESTNEG

	アルファ値の増加につれ転送先サーフェスが透明化することを表す（0は不透明）。

DDOVER_ALPHADESTSURFACEOVERRIDE

	このオーバーレイの転送先アルファ・チャネルとしてDDOVERLAYFX 構造体の lpDDSAlphaDest メンバを使用する。

DDOVER_ALPHAEDGEBLEND

	カラー・キー色と境を接する画像のエッジのアルファ・チャネルとしてDDOVERLAYFX 構造体の dwAlphaEdgeBlend メンバを使用する。

DDOVER_ALPHASRC

	ピクセル・フォーマットでのアルファ情報あるいはアルファ・チャネル・サーフェスを、このオーバーレイの転送元アルファ・チャネルとしてサーフェスにアタッチするために使用する。

DDOVER_ALPHASRCCONSTOVERRIDE

	このオーバーレイの転送元アルファ・チャネルとして DDOVERLAYFX 構造体のdwAlphaSrcConst メンバを使用する。

DDOVER_ALPHASRCNEG

	アルファ値の増加につれ転送元サーフェスが透明化することを表す（0は不透明）。

DDOVER_ALPHASRCSURFACEOVERRIDE

	このオーバーレイのアルファ・チャネル源として DDOVERLAYFX 構造体のlpDDSAlphaSrc メンバを使用する。

DDOVER_DDFX

	特殊なオーバーレイ効果を定義するために、オーバーレイFXフラグを使用する。

DDOVER_HIDE

	このオーバーレイをオフにする。

DDOVER_KEYDEST

	転送先サーフェスと結び付けられたカラー・キーを使用する。

DDOVER_KEYDESTOVERRIDE

	転送先サーフェスのカラー・キーとして DDOVERLAYFX 構造体のdckDestColorkey メンバを使用する。

DDOVER_KEYSRC

	転送元サーフェスと結び付けられたカラー・キーを使用する。

DDOVER_KEYSRCOVERRIDE

	転送元サーフェスのカラー・キーとして DDOVERLAYFX 構造体のdckSrcColorkey メンバを使用する。

DDOVER_SHOW

	このオーバーレイをオンにする。

DDOVER_ZORDER

	このオーバーレイのZオーダーとして DDOVERLAYFX 構造体のdwZOrderFlags メンバを使用する。 lpDDSRelative メンバは、dwZOrderFlags メンバがDDOVERZ_INSERTINBACKOF あるいはDDOVERZ_INSERTINFRONTOF にセットされるとき使用する。
lpDDOverlayFx

DDOVERLAYFX 構造体を参照すること。


IDirectDrawSurface2::UpdateOverlayDisplay

HRESULT UpdateOverlayDisplay(DWORD dwFlags);

有効なすべてのオーバーレイのうち、更新しなければならない矩形のリストで矩形を再描画する。また、 処理が終わるとその矩形リストをクリアする。 このメソッドはソフトウェア・エミュレーション時のみ有効で、ハードウェアでオーバーレイがサポートされている場合、何もしない。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_UNSUPPORTED

dwFlags

処理すべき更新タイプ。 以下のフラグのうちひとつの値を取る。

DDOVER_REFRESHDIRTYRECTS

	この転送先のために前もって用意した更新すべき矩形のリストを使用して、ディスプレイを更新する。また、その矩形リストをクリアする。

DDOVER_REFRESHALL

	更新すべき矩形のリストを無視して、オーバーレイ・ディスプレイを完全に更新する。 また、その矩形リストをクリアする。
参照　IDirectDrawSurface2::AddOverlayDirtyRect


IDirectDrawSurface2::UpdateOverlayZOrder

HRESULT UpdateOverlayZOrder(DWORD dwFlags,

    LPDIRECTDRAWSURFACE2 lpDDSReference);

オーバーレイのZオーダーを設定する。

成功すれば DD_OK 、失敗すれば次のエラーを返す。

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTAOVERLAYSURFACE

dwFlags

以下のフラグのうちひとつの値を取る。

DDOVERZ_INSERTINBACKOF

	このオーバーレイをオーバーレイ・チェーンの参照オーバーレイの後ろに挿入する。

DDOVERZ_INSERTINFRONTOF

	このオーバーレイをオーバーレイ・チェーンの参照オーバーレイの前に挿入する。

DDOVERZ_MOVEBACKWARD

	このオーバーレイをオーバーレイ・チェーンのひとつ後方に移動する。

DDOVERZ_MOVEFORWARD

	このオーバーレイをオーバーレイ・チェーンのひとつ前方に移動する。

DDOVERZ_SENDTOBACK

	このオーバーレイをオーバーレイ・チェーンの後方に移動する。

DDOVERZ_SENDTOFRONT

	このオーバーレイをオーバーレイ・チェーンの前方に移動する。
lpDDSReference

オーバーレイ・チェーンにおける相対的な位置として使用されるDirectDraw サーフェスのポインタ。 このパラメータは DDOVERZ_INSERTINBACKOFおよび DDOVERZ_INSERTINFRONTOF だけのために必要とされる。

参照　IDirectDrawSurface2::EnumOverlayZOrders


構造体


DDBLTBATCH

typedef struct _DDBLTBATCH{

    LPRECT              lprDest;

    LPDIRECTDRAWSURFACE lpDDSSrc;

    LPRECT              lprSrc;

    DWORD               dwFlags;

    LPDDBLTFX           lpDDBltFx;

} DDBLTBATCH,FAR *LPDDBLTBATCH;

IDirectDrawSurface2::BltBatchメソッドに渡すブロック転送操作。

lprDest

ブロック転送先を定義する RECT 構造体のポインタ。

lpDDSSrc

ブロック転送元を定義する DirectDrawSurfaceオブジェクトのアドレス。

lprSrc

ブロック転送元の矩形を定義する RECT 構造体のアドレス。

dwFlags

オプション制御フラグ。

DDBLT_ALPHADEST

	このブロック転送におけるブロック転送先サーフェスのアルファ・チャネルとして、ピクセル・フォーマットでのアルファ情報あるいはアルファ・チャネル・サーフェスのいずれかを使用する。

DDBLT_ALPHADESTCONSTOVERRIDE

	このブロック転送におけるブロック転送先サーフェスのアルファ・チャネルとして、DDBLTFX 構造体の dwAlphaDestConst メンバを使用する。

DDBLT_ALPHADESTNEG

	アルファ値の増加につれ転送先サーフェスが透明化することを表す（0は不透明）。

DDBLT_ALPHADESTSURFACEOVERRIDE

	このブロック転送におけるブロック転送先サーフェスのアルファ・チャネルとして、DDBLTFX 構造体の lpDDSAlphaDest メンバを使用する。

DDBLT_ALPHAEDGEBLEND

	カラー・キー色と境を接する画像のエッジのアルファ・チャネルとしてDDBLTFX 構造体の dwAlphaEdgeBlend メンバを使用する。

DDBLT_ALPHASRC

	このブロック転送におけるブロック転送先サーフェスのアルファ・チャネルとして、ピクセル・フォーマットでのアルファ情報あるいはアルファ・チャネル・サーフェスのいずれかを使用する。

DDBLT_ALPHASRCCONSTOVERRIDE

	このブロック転送におけるブロック転送元サーフェスのアルファ・チャネルとして、DDBLTFX 構造体の dwAlphaSrcConst メンバを使用する。

DDBLT_ALPHASRCNEG

	アルファ値の増加につれ転送元サーフェスが透明化することを表す（0は不透明）。

DDBLT_ALPHASRCSURFACEOVERRIDE

	このブロック転送におけるブロック転送元サーフェスのアルファ・チャネルとして、DDBLTFX 構造体の lpDDSAlphaSrc メンバを使用する。

DDBLT_ASYNC

	FIFO ハードウェアを通して受信した順序で、このブロック転送を非同期に実行する。 もし FIFO ハードウェアに空領域がないなら、呼び出しは失敗する。

DDBLT_COLORFILL

	ブロック転送先サーフェス上のブロック転送先矩形を満たす RGB 色として、 DDBLTFX 構造体の dwFillColor メンバを使用する。

DDBLT_DDFX

	このブロック転送で使用される効果を指定する DDBLTFX 構造体の dwDDFX メンバを使用する。

DDBLT_DDROPS

	Win32 API の一部でないラスタ処理（ ROPs ）を指定するためにDDBLTFX 構造体の dwDDROPS メンバを使用する。

DDBLT_KEYDEST

	ブロック転送先サーフェスと結び付けられたカラー・キーを使用する。

DDBLT_KEYDESTOVERRIDE

	ブロック転送先サーフェスのカラー・キーとして、DDBLTFX 構造体のdckDestColorkey メンバを使用する。

DDBLT_KEYSRC

	ブロック転送元サーフェスと結び付けられたカラー・キーを使用する。

DDBLT_KEYSRCOVERRIDE

	情報元サーフェスのカラー・キーとして、DDBLTFX 構造体のdckSrcColorkey メンバを使用する。

DDBLT_ROP

	このブロック転送の ROP のために DDBLTFX 構造体の dwROP メンバを使用する。 ROP は Win32 API で定義されるものと同じである。

DDBLT_ROTATIONANGLE

	サーフェスの回転角（1/100度単位で指定される）として、DDBLTFX 構造体の dwRotationAngle メンバを使用する。

DDBLT_ZBUFFER

	ブロック転送元およびブロック転送先サーフェスにアタッチされたZバッファを使用して Zバッファ・ブロック転送を行う。 DDBLTFX 構造体の dwZBufferOpCode メンバを Zバッファ・オペコードとする。

DDBLT_ZBUFFERDESTCONSTOVERRIDE

	DDBLTFX 構造体のdwZDestConstを転送先 Zバッファに使用して、Zバッファ・ブロック転送を実行する。同構造体のdwZBufferOpCodeメンバを転送先Zバッファ・オペコードとする。

DDBLT_ZBUFFERDESTOVERRIDE

	DDBLTFX 構造体のlpDDSZBufferDestを転送先 Zバッファに使用して、Zバッファ・ブロック転送を実行する。同構造体のdwZBufferOpCode メンバを転送先Zバッファ・オペコードとする。

DDBLT_ZBUFFERSRCCONSTOVERRIDE

	DDBLTFX 構造体の dwZSrcConstを転送元Zバッファに使用して、Zバッファ・ブロック転送を実行する。同構造体のdwZBufferOpCode メンバを転送元Zバッファ・オペコードとする。

DDBLT_ZBUFFERSRCOVERRIDE

	DDBLTFX 構造体の lpDDSZBufferSrcを転送元Zバッファに使用して、Zバッファ・ブロック転送を実行する。同構造体の dwZBufferOpCode メンバを転送元Zバッファ・オペコードとする。
lpDDBltFx

追加されたブロック転送効果を指定する DDBLTFX 構造体のポインタ。


DDBLTFX

typedef struct _DDBLTFX{

    DWORD dwSize;

    DWORD dwDDFX;

    DWORD dwROP;

    DWORD dwDDROP;

    DWORD dwRotationAngle;

    DWORD dwZBufferOpCode;

    DWORD dwZBufferLow;

    DWORD dwZBufferHigh;

    DWORD dwZBufferBaseDest;

    DWORD dwZDestConstBitDepth;

union

{

        DWORD               dwZDestConst;

        LPDIRECTDRAWSURFACE lpDDSZBufferDest;

};

    DWORD dwZSrcConstBitDepth;

union

{

        DWORD               dwZSrcConst;

        LPDIRECTDRAWSURFACE lpDDSZBufferSrc;

};

    DWORD dwAlphaEdgeBlendBitDepth;

    DWORD dwAlphaEdgeBlend;

    DWORD dwReserved;

    DWORD dwAlphaDestConstBitDepth;

union

{

        DWORD               dwAlphaDestConst;

        LPDIRECTDRAWSURFACE lpDDSAlphaDest;

};

    DWORD dwAlphaSrcConstBitDepth;

union

{

        DWORD               dwAlphaSrcConst;

        LPDIRECTDRAWSURFACE lpDDSAlphaSrc;

};

union

{

        DWORD               dwFillColor;

        DWORD               dwFillDepth;

        LPDIRECTDRAWSURFACE lpDDSPattern;

};

DDCOLORKEY ddckDestColorkey;

DDCOLORKEY ddckSrcColorkey;

} DDBLTFX,FAR* LPDDBLTFX;

ラスタ処理、効果およびオーバライド情報を IDirectDrawSurface2::Bltに渡す。この構造体はまた IDirectDrawSurface2::BltBatchメソッドで使用されるDDBLTBATCH 構造体の一部である。

dwSize

構造体の大きさ。 このメンバは構造体が使われる前に設定されていなくてはならない。

dwDDFX

効果処理のタイプを指定するフラグ。

DDBLTFX_ARITHSTRETCHY

	このブロック転送においてｙ軸に沿って演算伸長を使用する。

DDBLTFX_MIRRORLEFTRIGHT

	ｙ軸上でサーフェスを回転する。 このブロック転送はサーフェスを左から右に転写する。

DDBLTFX_MIRRORUPDOWN

	ｘ軸上でサーフェスを回転する。 このブロック転送はサーフェスを上から下に転写する。

DDBLTFX_NOTEARING

	このブロック転送においてティアリングを避けるように考慮する。

DDBLTFX_ROTATE180

	このブロック転送の間にサーフェスを時計回りで180度回転させる。

DDBLTFX_ROTATE270

	このブロック転送の間にサーフェスを時計回りで270度回転させる。

DDBLTFX_ROTATE90

	このブロック転送の間にサーフェスを時計回りで90度回転させる。

DDBLTFX_ZBUFFERBASEDEST

	このブロック転送の間に、比較する前のブロック転送元ｚ値およびｚブロック転送するブロック転送先ｚ値のそれぞれにdwZBufferBaseDest メンバを加える。

DDBLTFX_ZBUFFERRANGE

	このブロック転送の間にブロック転送元サーフェスから複製したビットの限界を指定する範囲値としてdwZBufferLowおよび dwZBufferHigh メンバを使用する。
dwROP

Win32 ラスタ処理。

dwDDROP

DirectDraw ラスタ処理。

dwRotationAngle

ブロック転送の回転角度。

dwZBufferOpCode

Zバッファ比較。

dwZBufferLow

Zバッファの最低限界。

dwZBufferHigh

Zバッファの最高限界。

dwZBufferBaseDest

Zバッファのブロック転送先基底値。

dwZDestConstBitDepth

ブロック転送先ｚ定数のビット深度。

dwZDestConst

ブロック転送先Zバッファとして使用される定数。

lpDDSZBufferDest

ブロック転送先Zバッファとして使用されるサーフェス。

dwZSrcConstBitDepth

ブロック転送元ｚ定数のビット深度。

dwZSrcConst

ブロック転送元Zバッファとして使用される定数。

DDSZBufferSrc

ブロック転送元Zバッファとして使用されるサーフェス。

dwAlphaEdgeBlendBitDepth

アルファ・エッジ・ブレンドのためのビット深度定数。

dwAlphaEdgeBlend

エッジ混合のために使われたアルファ定数。

dwReserved

将来のために予約されている。

dwAlphaDestConstBitDepth

ブロック転送先アルファ定数のビット深度。

dwAlphaDestConst

ブロック転送先アルファ・チャネルのために使われる定数。

lpDDSAlphaDest

ブロック転送先アルファ・チャネルとして使用されるサーフェス。

dwAlphaSrcConstBitDepth

ブロック転送元アルファ定数のビット深度。

dwAlphaSrcConst

ブロック転送元アルファ・チャネルのために使われる定数。

lpDDSAlphaSrc

ブロック転送元アルファ・チャネルとして使用されるサーフェス。

dwFillColor

DDBLT_COLORFILL が指定される時、サーフェスを補充するために使用される色の指定。この値は サーフェス・タイプに依存してRGB３重値あるいはパレット・インデックスである。

dwFillDepth

Zバッファの深度値。

lpDDSPattern

パターンとして使用するサーフェス。 パターンはブロック転送元とブロック転送先をアタッチする特定のブロック転送操作に使用される。

ddckDestColorkey

優先するブロック転送先カラー・キー。

ddckSrcColorkey

優先するブロック転送元カラー・キー。


DDCAPS

typedef struct _DDCAPS{

    DWORD    dwSize;

    DWORD    dwCaps;

    DWORD    dwCaps2;

    DWORD    dwCKeyCaps;

    DWORD    dwFXCaps;

    DWORD    dwFXAlphaCaps;

    DWORD    dwPalCaps;

    DWORD    dwSVCaps;

    DWORD    dwAlphaBltConstBitDepths;

    DWORD    dwAlphaBltPixelBitDepths;

    DWORD    dwAlphaBltSurfaceBitDepths;

    DWORD    dwAlphaOverlayConstBitDepths;

    DWORD    dwAlphaOverlayPixelBitDepths;

    DWORD    dwAlphaOverlaySurfaceBitDepths;

    DWORD    dwZBufferBitDepths;

    DWORD    dwVidMemTotal;

    DWORD    dwVidMemFree;

    DWORD    dwMaxVisibleOverlays;

    DWORD    dwCurrVisibleOverlays;

    DWORD    dwNumFourCCCodes;

    DWORD    dwAlignBoundarySrc;

    DWORD    dwAlignSizeSrc;

    DWORD    dwAlignBoundaryDest;

    DWORD    dwAlignSizeDest;

    DWORD    dwAlignStrideAlign;

    DWORD    dwRops[DD_ROP_SPACE];

    DDSCAPS  ddsCaps;

    DWORD    dwMinOverlayStretch;

    DWORD    dwMaxOverlayStretch;

    DWORD    dwMinLiveVideoStretch;

    DWORD    dwMaxLiveVideoStretch;

    DWORD    dwMinHwCodecStretch;

    DWORD    dwMaxHwCodecStretch;

    DWORD    dwReserved1;

    DWORD    dwReserved2;

    DWORD    dwReserved3;

    DWORD    dwSVBCaps;

    DWORD    dwSVBCKeyCaps;

    DWORD    dwSVBFXCaps;

    DWORD    dwSVBRops[DD_ROP_SPACE];

    DWORD    dwVSBCaps;

    DWORD    dwVSBCKeyCaps;

    DWORD    dwVSBFXCaps;

    DWORD    dwVSBRops[DD_ROP_SPACE];

    DWORD    dwSSBCaps;

    DWORD    dwSSBCKeyCaps;

    DWORD    dwSSBCFXCaps;

    DWORD    dwSSBRops[DD_ROP_SPACE];

    DWORD    dwReserved4;

    DWORD    dwReserved5;

    DWORD    dwReserved6;

} DDCAPS,FAR* LPDDCAPS;

DirectDrawオブジェクトから得られたハードウェア能力を表す。 この構造体はこのコンテキストでどんな DirectDrawSurface オブジェクトを作成することができるか記述する DDSCAPS 構造体を含んでいる。 しかし同時にこれらの能力によって記述されたサーフェスのすべてを作ることは不可能な可能性もある。 この構造体は IDirectDraw2::GetCapsおよび IDirectDrawPalette::GetCapsメソッドで使用される。

dwSize

構造体の大きさ。 このメンバは構造体が使われる前に設定されなくてはならない。

dwCaps

ドライバ特定能力をあらわすフラグ。

DDCAPS_3D

	ディスプレイ・ハードウェアが３Ｄアクセラレーションを持っていることを表す。

DDCAPS_ALIGNBOUNDARYDEST

	DirectDrawのブロック転送元矩形の座標は、 dwAlignBoundaryDest の倍数である場合のみをサポートすることを表す。

DDCAPS_ALIGNBOUNDARYSRC

	DirectDrawのブロック転送元矩形の座標は、 dwAlignBoundarySrc の倍数である場合のみをサポートすることを表す。

DDCAPS_ALIGNSIZEDEST

	DirectDraw がバイト単位でのｘ軸方向の大きさがdwAlignSizeDestの倍数である場合のブロック転送元矩形だけをサポートすることを表す。

DDCAPS_ALIGNSIZESRC

	DirectDraw がバイト単位でのｘ方向の大きさがdwAlignSizeSrcの倍数である場合のブロック転送元矩形だけをサポートすることを表す。

DDCAPS_ALIGNSTRIDE

	DirectDraw がdwAlignStrideAlign 値と等しいストライド・アラインメントを持っているディスプレイ・メモリ・サーフェスを作成することを表す。

DDCAPS_ALPHA

	ブロック転送操作の間、ディスプレイ・ハードウェアがアルファ・チャネルをサポートすることを表す。

DDCAPS_BANKSWITCHED

	ディスプレイ・ハードウェアがバンク切り替えであり、ディスプレイ・メモリのランダム・アクセスが非常に遅い可能性があることを表す。

DDCAPS_BLT

	ディスプレイ・ハードウェアはブロック転送操作ができることを表す。

DDCAPS_BLTCOLORFILL

	ディスプレイ・ハードウェアがブロック転送でカラー・フィルができることを表す。

DDCAPS_BLTDEPTHFILL

	ディスプレイ・ハードウェアがブロック転送で Zバッファ深度補充ができることを表す。

DDCAPS_BLTFOURCC

	ディスプレイ・ハードウェアがブロック転送で 色空間変換ができることを表す。

DDCAPS_BLTQUEUE

	ディスプレイ・ハードウェアが非同期ブロック転送ができることを表す。

DDCAPS_BLTSTRETCH

	ブロック転送操作で、ディスプレイ・ハードウェアが伸長できることを表す。

DDCAPS_CANBLTSYSMEM

	ディスプレイ・ハードウェアがシステム・メモリにあるいはシステム・メモリからブロック転送できることを表す。

DDCAPS_CANCLIP

	ディスプレイ・ハードウェアがブロック転送でクリッピングできることを表す。

DDCAPS_CANCLIPSTRETCHED

	ディスプレイ・ハードウェアが、伸長ブロック転送中にクリッピングできることを表す。

DDCAPS_COLORKEY

	オーバーレイまたはブロック転送操作のいずれかでカラー・キーのいくつかの形式をサポートする。特定のカラー・キー能力情報は dwCKeyCaps メンバにある。

DDCAPS_COLORKEYHWASSIST

	カラー・キーがハードウェアによりサポートされていることを表す。

DDCAPS_GDI

	ディスプレイ・ハードウェアが GDI と共有されることを表す。

DDCAPS_NOHARDWARE

	ハードウェア・サポートがないことを表す。

DDCAPS_OVERLAY

	ディスプレイ・ハードウェアがオーバーレイをサポートすることを表す。

DDCAPS_OVERLAYCANTCLIP

	ディスプレイ・ハードウェアがオーバーレイをサポートするが、クリッピングはできないことを表す。

DDCAPS_OVERLAYFOURCC

	オーバーレイ・ハードウェアがオーバーレイ処理の間、色空間変換ができることを表す。

DDCAPS_OVERLAYSTRETCH

	オーバーレイ・ハードウェアに伸長の能力があることを表す。

DDCAPS_PALETTE

	DirectDraw がプライマリ・サーフェスだけでなく、他のサーフェスにも DirectDrawPalette オブジェクトを作成して、サポートできることを示す。

DDCAPS_PALETTEVSYNC

	DirectDrawがVSYNCに同期してパレットを更新できることを表す。

DDCAPS_READSCANLINE

	ディスプレイ・ハードウェアがスキャンライン読み取りが可能であることを表す。

DDCAPS_STEREOVIEW

	ディスプレイ・ハードウェアがステレオ・ビジョン能力を持っていることを表す。

DDCAPS_VBI

	ディスプレイ・ハードウェアがVブランク割り込みを生成できることを表す。

DDCAPS_ZBLTS

	ブロック転送操作においてZバッファの使用をサポートする。

DDCAPS_ZOVERLAYS

	重なりを制御するオーバーレイｚ値としてIDirectDrawSurface2::UpdateOverlayZOrderメソッドの使用をサポートする。
dwCaps2

そのドライバ特定能力の詳細を表すフラグ。

DDCAPS2_CERTIFIED

	ディスプレイ・ハードウェアが保証されていることを表す。

DDCAPS2_NO2DDURING3DSCENE

	IDirect3DDevice::BeginSceneメソッド呼び出しと IDirect3DDevice::EndSceneメソッド呼び出しとの間に Direct3Dが使用しているすべてのサーフェス上で、IDirectDrawSurface2::BltおよびIDirectDrawSurface2::Lockのような 2D 処理を実行できないことを表す。
dwCKeyCaps

カラー・キー能力を表すフラグ。

DDCKEYCAPS_DESTBLT

	カラー・キーによる透過型ブロック転送をサポートする。 カラー・キーはRGB 色のブロック転送先サーフェスで置換可能なビットを示す。

DDCKEYCAPS_DESTBLTCLRSPACE

	色空間による透過型ブロック転送をサポートする。色空間はRGB 色のブロック転送先サーフェスで置換可能なビットを示す。

DDCKEYCAPS_DESTBLTCLRSPACEYUV

	色空間による透過型ブロック転送をサポートする。色空間はYUV 色のブロック転送先サーフェスで置換可能なビットを示す。

DDCKEYCAPS_DESTBLTYUV

	カラー・キーによる透過型ブロック転送をサポートする。カラー・キーはYUV 色のブロック転送先サーフェスで置換可能なビットを示す。

DDCKEYCAPS_DESTOVERLAY

	カラー・キーイングによるオーバーレイをサポートする。カラー・キーはRGB 色でオーバーレイされるブロック転送先サーフェスで置換可能なビット。

DDCKEYCAPS_DESTOVERLAYCLRSPACE

	RGB 色のブロック転送先カラー・キーとして色空間をサポートする。

DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV

	YUV 色のブロック転送先カラー・キーとして色空間をサポートする。

DDCKEYCAPS_DESTOVERLAYONEACTIVE

	可視状態のオーバーレイ・サーフェスに、ひとつだけの有効なブロック転送先カラー・キー値をサポートする。

DDCKEYCAPS_DESTOVERLAYYUV

	カラー・キーイングによるオーバーレイをサポートする。カラー・キーは YUV色でオーバーレイされるブロック転送先サーフェスで置換可能なビット。

DDCKEYCAPS_NOCOSTOVERLAY

	オーバーレイでカラー・キーを使用することに対して処理速度に影響がないことを表す。

DDCKEYCAPS_SRCBLT

	RGB 色サーフェスのブロック転送元カラー・キーによる透過型ブロック転送をサポートする。

DDCKEYCAPS_SRCBLTCLRSPACE

	RGB 色サーフェスのブロック転送元色空間による透過型ブロック転送をサポートする。

DDCKEYCAPS_SRCBLTCLRSPACEYUV

	YUV 色サーフェスのブロック転送元色空間による透過型ブロック転送をサポートする。

DDCKEYCAPS_SRCBLTYUV

	YUV 色サーフェスのカラー・キーによる透過型ブロック転送をサポートする。

DDCKEYCAPS_SRCOVERLAY

	RGB 色のブロック転送元カラー・キーによるオーバーレイをサポートする。

DDCKEYCAPS_SRCOVERLAYCLRSPACE

	RGB 色オーバーレイ・サーフェスでブロック転送元カラー・キーとして色空間を使ったオーバーレイをサポートする。

DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV

	YUV 色オーバーレイ・サーフェスでブロック転送元カラー・キーとして色空間をサポートする。

DDCKEYCAPS_SRCOVERLAYONEACTIVE

	可視状態のオーバーレイ・サーフェスに、ひとつだけの有効なブロック転送元カラー・キー値をサポートする。

DDCKEYCAPS_SRCOVERLAYYUV

	YUV 色オーバーレイ・サーフェスでブロック転送元カラー・キーによるオーバーレイをサポートする。
dwFXCaps

ドライバ特定の伸長およびFX能力。

DDFXCAPS_BLTARITHSTRETCHY

	ピクセルを２乗にして拡大するテクニックではなく、ブロック転送操作の間に拡大し、サーフェスを縮小する演算処理を使用する。これは、ｙ軸（垂直に）に沿って行われる。

DDFXCAPS_BLTARITHSTRETCHYN

	ピクセルを２乗にして拡大するテクニックではなく、ブロック転送操作の間に拡大して、サーフェスを縮小する演算処理を使用する。これはｙ軸（垂直に）に沿って行われ、整数倍（×1, ×2, のように）で拡大するために動作する。

DDFXCAPS_BLTMIRRORLEFTRIGHT

	ブロック転送操作中に左右反転することをサポートする。

DDFXCAPS_BLTMIRRORUPDOWN

	ブロック転送操作中に上下反転することをサポートする。

DDFXCAPS_BLTROTATION

	ブロック転送操作中に任意の回転をサポートする。

DDFXCAPS_BLTROTATION90

	ブロック転送操作中に９０度の回転をサポートする。

DDFXCAPS_BLTSHRINKX

	ｘ軸（水平）に沿ってサーフェスを任意に縮小することをサポートする。 このフラグはブロック転送操作のみに有効である。

DDFXCAPS_BLTSHRINKXN

	ｘ軸（水平）に沿ってサーフェスを整数分の一（×1/2、×1/3のように）で縮小することをサポートする。 このフラグはブロック転送操作のみに有効である。

DDFXCAPS_BLTSHRINKY

	ｙ軸（垂直）に沿ってサーフェスを任意に縮小することをサポートする。 このフラグはブロック転送操作のみに有効である。

DDFXCAPS_BLTSHRINKYN

	ｙ軸（垂直）に沿ってサーフェスを整数分の一（×1/2、×1/3のように）で縮小することをサポートする。 このフラグはブロック転送操作のみに有効である。

DDFXCAPS_BLTSTRETCHX

	ｘ軸（水平）に沿ってサーフェスを任意に拡大することをサポートする。 このフラグはブロック転送操作のみに有効である。

DDFXCAPS_BLTSTRETCHXN

	ｘ軸（水平）に沿ってサーフェスを整数倍（×1, ×2, のように）で拡大することをサポートする。 このフラグはブロック転送操作のみに有効である。

DDFXCAPS_BLTSTRETCHY

	ｙ軸（垂直）に沿ってサーフェスを任意に拡大することをサポートする。 このフラグはブロック転送操作のみに有効である。

DDFXCAPS_BLTSTRETCHYN

	ｙ軸（垂直）に沿ってサーフェスの整数倍（×1, ×2, のように）で拡大することをサポートする。 このフラグはブロック転送操作のみに有効である。

DDFXCAPS_OVERLAYARITHSTRETCHY

	ピクセルを２乗にして拡大するテクニックではなく、ブロック転送操作の間に拡大し、サーフェスを縮小する演算処理を使用する。ｙ軸（垂直）に沿って行われる。

DDFXCAPS_OVERLAYARITHSTRETCHYN

	ピクセルを２乗にして拡大するテクニックではなく、ブロック転送操作の間に拡大し、サーフェスを縮小する演算処理を使用する。ｙ軸（垂直）に沿って行われ、整数倍（×1, ×2, のように）の拡大が行われる。

DDFXCAPS_OVERLAYMIRRORLEFTRIGHT

	左右反転オーバーレイをサポートする。

DDFXCAPS_OVERLAYMIRRORUPDOWN

	上下反転オーバーレイをサポートする。

DDFXCAPS_OVERLAYSHRINKX

	ｘ軸（水平）に沿ってサーフェスを任意に縮小することをサポートする。 このフラグは DDSCAPS_OVERLAY サーフェスのみに有効である。 このフラグはサーフェスの能力だけを示し、縮小が可能であることを表さない。

DDFXCAPS_OVERLAYSHRINKXN

	ｘ軸（水平）に沿ってサーフェスを整数倍（×1, ×2, のように）で縮小することをサポートする。 このフラグは DDSCAPS_OVERLAY サーフェスのみに有効である。 このフラグはサーフェスの能力だけを示し、縮小が可能であることを表さない。

DDFXCAPS_OVERLAYSHRINKY

	ｙ軸（垂直）に沿ってサーフェスを任意に縮小することをサポートする。 このフラグは DDSCAPS_OVERLAY サーフェスのみに有効である。 このフラグはサーフェスの能力だけを示し、縮小が可能であることを表さない。

DDFXCAPS_OVERLAYSHRINKYN

	ｙ軸（垂直）に沿ってサーフェスの整数分の一（×1/2、×1/3のように）で縮小することをサポートする。 このフラグは DDSCAPS_OVERLAY サーフェスのみに有効である。このフラグはサーフェスの能力だけを示し、縮小が可能であることを表さない。

DDFXCAPS_OVERLAYSTRETCHX

	ｘ軸（水平）に沿ってサーフェスを任意に拡大することをサポートする。 このフラグは DDSCAPS_OVERLAY サーフェスのみに有効である。このフラグはサーフェスの能力だけを示し、縮小が可能であることを表さない。

DDFXCAPS_OVERLAYSTRETCHXN

	ｘ軸（水平）に沿ってサーフェスを整数倍（×1, ×2, のように）で拡大することをサポートする。 このフラグは DDSCAPS_OVERLAY サーフェスのみに有効である。 このフラグはサーフェスの能力だけを示し、縮小が可能であることを表さない。

DDFXCAPS_OVERLAYSTRETCHY

	ｙ軸（垂直）に沿ってサーフェスを任意に拡大することをサポートする。 このフラグはDDSCAPS_OVERLAY サーフェスのみに有効である。このフラグはサーフェスの能力だけを示し、縮小が可能であることを表さない。

DDFXCAPS_OVERLAYSTRETCHYN

	ｙ軸（垂直）に沿ってサーフェスの整数倍（×1, ×2, のように）の拡大をサポートする。 このフラグはDDSCAPS_OVERLAY サーフェスのみに有効である。 このフラグはサーフェスの能力だけを示し、縮小が可能であることを表さない。
dwFXAlphaCaps

ドライバ特定のアルファ能力。

DDFXALPHACAPS_BLTALPHAEDGEBLEND

	ブロック転送元カラー・キーのサーフェスのエッジ周りのアルファ・ブレンディングをサポートする。ブロック転送操作のために使用される。

DDFXALPHACAPS_BLTALPHAPIXELS

	ピクセル・フォーマットでアルファ情報をサポートする。 ピクセル・フォーマットでのアルファ情報のビット深度は１、２、４、あるいは８である。 アルファ値は増加するにつれて不透明になる。 アルファ情報の深度にかかわらず、０がつねに完全に透明な値である。 ブロック転送操作のために使用される。

DDFXALPHACAPS_BLTALPHAPIXELSNEG

	ピクセル・フォーマットでアルファ情報をサポートする。 ピクセル・フォーマットでのアルファ情報のビット深度は１、２、４、あるいは８である。 アルファ値は増加するにつれて透明になる。 アルファ情報の深度にかかわらず、０がつねに完全に不透明な値である。 このフラグは DDCAPS_ALPHA がセットされた場合に限り使うことができる。 ブロック転送操作のために使用される。

DDFXALPHACAPS_BLTALPHASURFACES

	アルファ専用サーフェスをサポートする。アルファ専用サーフェスのビット深度は１、２、４、あるいは８であり得る。 アルファ値は増加するにつれて不透明になる。 アルファ情報の深度にかかわらず、０がつねに完全に透明な値である。 ブロック転送操作のために使用される。

DDFXALPHACAPS_BLTALPHASURFACESNEG

	アルファ・チャネルが、アルファ値の増加につれて透明になることを表す。 アルファ・チャネル・データの深度は１、２、４、あるいは８である。 アルファ情報の深度にかかわらず、０がつねに完全に不透明な値である。このフラグは DDCAPS_ ALPHASURFACES がセットされた場合に限りセットすることができる。 ブロック転送操作のために使用される。

DDFXALPHACAPS_OVERLAYALPHAEDGEBLEND

	ブロック転送元カラー・キーのサーフェスのエッジ周りのアルファ・ブレンディングをサポートする。オーバーレイのために使用される。

DDFXALPHACAPS_OVERLAYALPHAPIXELS

	ピクセル・フォーマットでアルファ情報をサポートする。 ピクセル・フォーマットでのアルファ情報のビット深度は１、２、４、あるいは８である。 アルファ値は増加するにつれて不透明になる。 アルファ情報の深度にかかわらず、０がつねに完全に透明な値である。 オーバーレイのために使用される。

DDFXALPHACAPS_OVERLAYALPHAPIXELSNEG

	ピクセル・フォーマットでアルファ情報をサポートする。 ピクセル・フォーマットでのアルファ情報のビット深度は１、２、４、あるいは８である。 アルファ値は増加するにつれて透明になる。 アルファ情報の深度にかかわらず、０がつねに完全に不透明な値である。 このフラグは DDCAPS_ ALPHAPIXELS がセットされた場合に限り使うことができる。 オーバーレイのために使用される。

DDFXALPHACAPS_OVERLAYALPHASURFACES

	アルファ専用サーフェスをサポートする。アルファ専用サーフェスのビット深度は１、２、４、あるいは８である。 アルファ値は増加するにつれて不透明になる。 アルファ情報の深度にかかわらず、０がつねに完全に透明な値である。 オーバーレイのために使用される。

DDFXALPHACAPS_OVERLAYALPHASURFACESNEG

	アルファ・チャネルが、アルファ値の増加につれて透明になることを表す。 アルファ・チャネル・データの深度は１、２、４、あるいは８である。 アルファ情報の深度にかかわらず、０がつねに完全に不透明な値である。このフラグはDDCAPS_ ALPHASURFACES がセットされた場合に限りセットすることができる。 オーバーレイのために使用される。
dwPalCaps

パレット能力を表すフラグ。

DDPCAPS_1BIT

	インデックスが１ビットであることを表す。 カラー・テーブルに2つの項目がある。

DDPCAPS_2BIT

	インデックスが２ビットであることを表す。 カラー・テーブルに4つの項目がある。

DDPCAPS_4BIT

	インデックスが４ビットであることを表す。 カラー・テーブルに16の項目がある。

DDPCAPS_8BIT

	インデックスが８ビットであることを表す。 カラー・テーブルに256の項目がある。

DDPCAPS_8BITENTRIES

	インデックスを８ビットのカラー・インデックスに指定する。 このフィールドは、ただDDPCAPS_1BIT 、 DDPCAPS_2BIT 、あるいは DDPCAPS_4BIT能力が使われる時のみ、および目標サーフェスがピクセル（ bpp ）毎に８ビットである場合に有効である。 それぞれの色項目が長さ１バイトであり、ブロック転送先サーフェス上の８ bpp パレットのインデックスである。

DDPCAPS_ALLOW256

	このパレットが256の項目すべてを定義できることを示す。

DDPCAPS_PRIMARYSURFACE

	パレットがプライマリ・サーフェスにアタッチされていることを表す。 パレットの変更は、 DDPCAPS_VSYNC 能力の指定、サポートがないかぎり、ディスプレイに即座に反映される。

DDPCAPS_PRIMARYSURFACELEFT

	パレットが左側プライマリ・サーフェスにアタッチされることを表す。 パレットの変更は、 DDPCAPS_VSYNC能力の指定、サポートがないかぎり、ディスプレイに即座に反映される。

DDPCAPS_VSYNC

	パレットがモニターのリフレッシュに同期して更新できることを表す。
dwSVCaps

ステレオ・ビジョン能力を表すフラグ。

DDSVCAPS_ENIGMA

	エニグマ・コーディングによりステレオ・ビューを実現していることを表す。

DDSVCAPS_FLICKER

	高周波フリッカリングによりステレオ・ビューを実現していることを表す。

DDSVCAPS_REDBLUE

	赤と青のフィルタを左と右の眼に配した3D眼鏡でステレオ・ビューを実現していることを表す。 すべての画像(の色空間)をこの仕組みに適合させなくてはならない。

DDSVCAPS_SPLIT

	分割スクリーンによりステレオ・ビューを実現していることを表す。
dwAlphaBltConstBitDepths

DDBD_2、DDBD_4または DDBD_8（ピクセル毎に2ビット、4ビット あるいは8ビットを示す）。

dwAlphaBltPixelBitDepths

DDBD_1、DDBD_2、DDBD_4または DDBD_8（ピクセル毎に1ビット、2ビット、4ビット あるいは8ビットを示す）。

dwAlphaBltSurfaceBitDepths

DDBD_1、DDBD_2、DDBD_4または DDBD_8（ピクセル毎に1ビット、2ビット、4ビット あるいは8ビットを示す）。

dwAlphaOverlayConstBitDepths

DDBD_2、DDBD_4または DDBD_8（ピクセル毎に2ビット、4ビット あるいは8ビットを示す）。

dwAlphaOverlayPixelBitDepths

DDBD_1、DDBD_2、DDBD_4または DDBD_8（ピクセル毎に1ビット、2ビット、4ビット あるいは8ビットを示す）。

dwAlphaOverlaySurfaceBitDepths

DDBD_1、DDBD_2、DDBD_4または DDBD_8（ピクセル毎に1ビット、2ビット、4ビット あるいは8ビットを示す）。

dwZBufferBitDepths

DDBD_8、DDBD_16、DDBD_24または DDBD_32（ピクセル毎に1ビット、16ビット、24ビットあるいは32ビットを示す）。

dwVidMemTotal

ディスプレイ・メモリの全体の量。

dwVidMemFree

空きディスプレイ・メモリの量。

dwMaxVisibleOverlays

可視状態のオーバーレイの最大の数。

dwCurrVisibleOverlays

可視状態のオーバーレイの現在の数。

dwNumFourCCCodes

FourCC コードの数。

dwAlignBoundarySrc

ブロック転送元矩形の座標の単位。

dwAlignSizeSrc

ブロック転送元矩形の大きさ。

dwAlignBoundaryDest

ブロック転送先矩形の座標の単位。

dwAlignSizeDest

ブロック転送先矩形の大きさの単位。

dwAlignStrideAlign

ストライド整列。

dwRops[DD_ROP_SPACE]

ラスタ処理のサポート。

ddsCaps

一般的な能力を示す DDSCAPS 構造体。

dwMinOverlayStretch and dwMaxOverlayStretch

1000倍される最小・最大限のオーバーレイ拡大係数。 たとえば、1.3=1300。

dwMinLiveVideoStretch and dwMaxLiveVideoStretch

1000倍される最小・最大限のライブ・ビデオ拡大係数。 たとえば、1.3=1300。

dwMinHwCodecStretch and  dwMaxHwCodecStretch

1000倍される最小・最大限のハードウェア・コーデック拡大係数。 たとえば、1.3=1300。

dwReserved1, dwReserved2, dwReserved3

将来のために予約されている。

dwSVBCaps

システム・メモリ－ディスプレイ・メモリブロック転送のドライバ能力。

dwSVBCKeyCaps

システム・メモリ－ディスプレイ・メモリブロック転送のドライバカラー・キー互換性。

dwSVBFXCaps

システム・メモリ－ディスプレイ・メモリブロック転送のドライバFX互換性。

dwSVBRops[DD_ROP_SPACE]

システム・メモリ－ディスプレイ・メモリブロック転送のラスタ処理サポート。

dwVSBCaps

ディスプレイ・メモリ－システム・メモリブロック転送のドライバ能力。

dwVSBCKeyCaps

ディスプレイ・メモリ－システム・メモリブロック転送のドライバカラー・キー互換性。

dwVSBFXCaps

ディスプレイ・メモリ－システム・メモリブロック転送のドライバFX互換性。

dwVSBRops[DD_ROP_SPACE]

ディスプレイ・メモリ－システム・メモリブロック転送のラスタ処理サポート。

dwSSBCaps

システム・メモリ－システム・メモリブロック転送のドライバ能力。

dwSSBCKeyCaps

システム・メモリ－システム・メモリブロック転送のドライバカラー・キー互換性。

wSSBCFXCaps

システム・メモリ－システム・メモリブロック転送のドライバFX互換性。

dwSSBRops[DD_ROP_SPACE]

システム・メモリ－システム・メモリブロック転送のラスタ処理サポート。

dwReserved4, dwReserved5, dwReserved6

将来のために予約されている。


DDCOLORKEY

typedef struct _DDCOLORKEY{

    DWORD dwColorSpaceLowValue;

    DWORD dwColorSpaceHighValue;

} DDCOLORKEY,FAR* LPDDCOLORKEY;

ブロック転送元カラー・キーもしくはブロック転送先カラー・キーとなる色空間を指定する。 もし上限と下限の範囲値が同じであるなら、カラー・キーとして指定される。 この構造体は IDirectDrawSurface2::GetColorKeyおよび IDirectDrawSurface2::SetColorKeyメソッドで使われる。

dwColorSpaceLowValue

カラー・キーとして用いられる色範囲の下限値。

dwColorSpaceHighValue

カラー・キーとして用いられる色範囲の上限値。


DDOVERLAYFX

typedef struct _DDOVERLAYFX{

    DWORD dwSize;

    DWORD dwAlphaEdgeBlendBitDepth;

    DWORD dwAlphaEdgeBlend;

    DWORD dwReserved;

    DWORD dwAlphaDestConstBitDepth;

union

{

        DWORD               dwAlphaDestConst;

        LPDIRECTDRAWSURFACE lpDDSAlphaDest;

};

    DWORD dwAlphaSrcConstBitDepth;

union

{

        DWORD               dwAlphaSrcConst;

        LPDIRECTDRAWSURFACE lpDDSAlphaSrc;

};

    DDCOLORKEY dckDestColorkey;

    DDCOLORKEY dckSrcColorkey;

    DWORD dwDDFX;

    DWORD dwFlags;

} DDOVERLAYFX,FAR *LPDDOVERLAYFX;

IDirectDrawSurface2::UpdateOverlayメソッドに渡されるオーバレイ情報。

dwSize

構造体の大きさ。 このメンバは構造体が使われる前に値が設定されなければならない。

dwAlphaEdgeBlendBitDepth

アルファ・エッジ・ブレンド係数を指定するために使用されるビット深度。

dwAlphaEdgeBlend

アルファ・エッジ・ブレンドのアルファとして使われる定数。

dwReserved

将来の使用のために予約されている。

dwAlphaDestConstBitDepth

ブロック転送先のアルファ定数を指定するために使用されるビット深度。

dwAlphaDestConst

ブロック転送先のアルファ・チャネルとして使われる定数。

lpDDSAlphaDest

ブロック転送先のアルファ・チャネルとして使われるサーフェスのアドレス。

dwAlphaSrcConstBitDepth

ブロック転送元のアルファ定数を指定するのに使用されるビット深度。

dwAlphaSrcConst

ブロック転送元のアルファ・チャネルとして使われる定数。

lpDDSAlphaSrc

ブロック転送元のアルファ・チャネルとして使われるサーフェスのポインタ。

dckDestColorkey

優先するブロック転送先カラー・キー。

dckSrcColorkey

優先するブロック転送元カラー・キー。

dwDDFX

オーバーレイ FXフラグ。

DDOVERFX_ARITHSTRETCHY

	もし拡大するなら、ｙ軸に沿って演算拡大を使用する。

DDOVERFX_MIRRORLEFTRIGHT

	左右反転を行う。

DDOVERFX_MIRRORUPDOWN

	上下反転を行う。
dwFlags

このメンバは現在使われていない。０がセットされなくてはならない。


DDPIXELFORMAT

typedef struct _DDPIXELFORMAT{

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwFourCC;

union

{

        DWORD dwRGBBitCount;

        DWORD dwYUVBitCount;

        DWORD dwZBufferBitDepth;

        DWORD dwAlphaBitDepth;

};

union

{

        DWORD dwRBitMask;

        DWORD dwYBitMask;

};

union

{

        DWORD dwGBitMask;

        DWORD dwUBitMask;

};

union

{

        DWORD dwBBitMask;

        DWORD dwVBitMask;

};

union

{

        DWORD dwRGBAlphaBitMask;

        DWORD dwYUVAlphaBitMask;

};

} DDPIXELFORMAT, FAR* LPDDPIXELFORMAT;

この構造体はIDirectDrawSurface2::GetPixelFormatメソッドのために、DirectDrawSurfaceオブジェクトのピクセル・フォーマットを記述するものである。

dwSize

構造体の大きさ。 このメンバは構造体が使われる前に値が設定されなければならない。

dwFlags

オプション制御フラグ。

DDPF_ALPHA

	ピクセル・フォーマットはアルファ専用サーフェスを記述している。

DDPF_ALPHAPIXELS

	サーフェスはアルファ・チャネル情報を持ったピクセル・フォーマットである。

DDPF_COMPRESSED

	サーフェスは指定されたフォーマットでピクセル・データを受け入れ、書きこみ処理中にデータ圧縮する。

DDPF_FOURCC

	FourCC コードが有効である。

DDPF_PALETTEINDEXED1

DDPF_PALETTEINDEXED2

DDPF_PALETTEINDEXED4

DDPF_PALETTEINDEXED8

	サーフェスは１ビット、２ビット 、４ビットあるいは８ビットでインデックスされている。

DDPF_PALETTEINDEXEDTO8

	サーフェスは１ビット、２ビットあるいは ４ビットの色を８ビット・パレットにインデックスしている。

DDPF_RGB

	ピクセル・フォーマット構造体でのRGB データは有効である。

DDPF_RGBTOYUV

	サーフェスはRGB データを受け入れて、そして 書きこみ処理の間にYUV データに変換する。書きこみのデータのフォーマットはピクセル・フォーマット構造体に含まれる。 DDPF_RGB フラグともにセットされなければならない。

DDPF_YUV

	ピクセル・フォーマット構造体での YUV データは有効である。

DDPF_ZBUFFER

	Zバッファ専用サーフェスはピクセル・フォーマットで記述される。
dwFourCC

FourCC コード。

wRGBBitCount

ピクセル毎の RGB ビット（4,8,16,24あるいは32）。

dwYUVBitCount

ピクセル毎の YUV ビット（ DDBD_4 、 DDBD_8 、 DDBD_16 、 DDBD_24 、あるいは DDBD_32 ）。

dwZBufferBitDepth

Zバッファ・ビット深度（8,16,24,あるいは32）。

dwAlphaBitDepth

アルファ・チャネル・ビット深度（ DDBD_1 、 DDBD_2 、 DDBD_4 、あるいは DDBD_8 ）。

dwRBitMask

赤ビットのマスク。

dwYBitMask

Ｙビットのマスク。

dwGBitMask

緑ビットのマスク。

dwUBitMask

Ｕビットのマスク。

dwBBitMask

青ビットのマスク。

dwVBitMask

Ｖビットのマスク。

dwRGBAlphaBitMask

アルファ・チャネルのマスク。

dwYUVAlphaBitMask

アルファ・チャネルのマスク。


DDSCAPS

typedef struct _DDSCAPS{

        DWORD dwCaps;

} DDSCAPS,FAR* LPDDSCAPS;

DirectDrawSurface オブジェクトの能力を定義する。 この構造体は DirectDraw オブジェクトの能力を記述するために使われる DDCAPS  構造体の一部である。

dwCaps

サーフェスの能力を表す。 以下のフラグのうちひとつまたはあるいは複数の属性を持つ。

DDSCAPS_3D

	これは下位互換性のためにサポートされているが、アプリケーションは代わりに、 DDSCAPS_3DDEVICE フラグを使うべきである。

DDSCAPS_3DDEVICE

	このサーフェスが３Ｄ表現用に利用可能なことを表す。 アプリケーションはデバイスが適切なヒープから割り当てられたオフスクリーン・サーフェスを持っている、特定のヒープのみを表現することができることを保証するために、このフラグを使用することができる。 もしこのフラグがヒープのためにセットされているなら、サーフェスはそのヒープから割り当てられない。

DDSCAPS_ALLOCONLOAD

	サーフェスがIDirect3DTexture::Loadメソッドによってロードされるまで、サーフェスにメモリを割り当てないという指定。

DDSCAPS_ALPHA

	このサーフェスがアルファ情報を含んでいることを表す。 ピクセル・フォーマットはこのサーフェスがただアルファ情報あるいはピクセル色データ（ RGBA あるいは YUVA のような）と混合されたアルファ情報だけを含んでいるかどうか決定するために取得されなくてはならない。

DDSCAPS_BACKBUFFER

	このサーフェスがサーフェス・フリッピング構造体のバック・バッファであることを表す。 一般にこのフラグは DDSCAPS_FLIPフラグが使用されたIDirectDraw2::CreateSurfaceメソッドによって設定される。DDSCAPS_FRONTBUFFERサーフェスより直接先行するサーフェスだけがこのフラグを持っている。 他のサーフェスは DDSCAPS_FLIP、DDSCAPS_BACKBUFFER フラグの存在、および DDSCAPS_FRONTBUFFER の欠如によりバック・バッファとして認知される。この能力が IDirectDraw2::CreateSurfaceメソッドに送られると、独立型のバック・バッファが作成される。 このメソッドが呼び出された後、このサーフェスは、サーフェス・フリッピング構造体を形成するためにフロント・バッファ、もうひとつのバック・バッファ、あるいは両方ともにアタッチすることができる。詳細は IDirectDrawSurface2::AddAttachedSurfaceを参照すること。 DirectDraw はフリッピング構造体で任意の数のサーフェスをサポートする。

DDSCAPS_COMPLEX

	複合サーフェスが記述されていることを表す。 複合サーフェスは１以上のサーフェスの作成をもたらす。 追加サーフェスはルート・サーフェスにアタッチされる。 複合構造体はただルートを破棄することによって破棄することができる。

DDSCAPS_FLIP

	このサーフェスがサーフェスフリッピング構造体の一部であることを表す。 この能力が IDirectDraw2::CreateSurfaceメソッドに渡されるとき、ひとつのフロント・バッファおよびひとつ以上のバック・バッファが作成される。 DirectDraw はフロント・バッファのDDSCAPS_FRONTBUFFERビットおよびフロント・バッファに隣接しているサーフェスの DDSCAPS_BACKBUFFERビットをセットする。 このフラグを指定する場合、DDSURFACEDESC構造体の dwBackBufferCountメンバは少なくとも１にセットしなければいけない。 IDirectDraw2::CreateSurfaceメソッドを使用して 多数のサーフェスを作る時、常にDDSCAPS_COMPLEXフラグをセットしなくてはならない。

DDSCAPS_FRONTBUFFER

	このサーフェスがサーフェス・フリッピング構造体のフロント・バッファであることを表す。 このフラグは一般に DDSCAPS_FLIP 能力がセットされたとき IDirectDraw2::CreateSurfaceメソッドによってセットされる。 IDirectDraw2::CreateSurfaceメソッドを使用した場合は独立型フロント・バッファが作られる。 このサーフェスは DDSCAPS_FLIPフラグを持たない。フリッピング構造体を形成するために、IDirectDrawSurface2::AddAttachedSurface を使用することによって他のバック・バッファにアタッチできる。

DDSCAPS_HWCODEC

	このサーフェスがハードウェアによって圧縮解除されたストリームを持つことができることを表す。

DDSCAPS_LIVEVIDEO

	このサーフェスがライブ・ビデオの受け取りが可能であることを表す。

DDSCAPS_MIPMAP

	このサーフェスが１レベルのミップマップであることを表す。 このサーフェスはミップマップを形成するために他のDDSCAPS_MIPMAP サーフェスにアタッチされる。これは、多数のサーフェスを作りIDirectDrawSurface2::AddAttachedSurfaceメソッドを使用することで明示的に行われるか、あるいは IDirectDraw2::CreateSurfaceメソッドを使用することで暗黙的に行われる。 もしこのフラグをセットするなら、 DDSCAPS_TEXTUREもセットしなくてはならない。

DDSCAPS_MODEX

	このサーフェスが 320×200あるいは 320×240のモードX10 (モード X) サーフェスであることを表す。

DDSCAPS_OFFSCREENPLAIN

	このサーフェスがオーバーレイ、テクスチャ、Zバッファ、フロント・バッファ、バック・バッファ、あるいはアルファ・サーフェスのどれでもない、スクリーン外のサーフェスであることを表す。プレーン・サーフェスを識別するために使われる。

DDSCAPS_OVERLAY

	このサーフェスがオーバーレイであることを表す。 現在最初のサーフェスにオーバーレイされているかどうかによって、可視であるか、そうでないかが決まる。 DDSCAPS_VISIBLE は、サーフェスが現在オーバーレイされているかどうか判断するために使うことができる。

DDSCAPS_OWNDC

	このサーフェスが長時間にわたりデバイス・コンテキスト（ＤＣ）との関連を持つであろうことを表す。

DDSCAPS_PALETTE

	このデバイス・ドライバにより一意的なDirectDrawPalette オブジェクトを作成してこのサーフェスにアタッチできることを表す。

DDSCAPS_PRIMARYSURFACE

	このサーフェスがプライマリ・サーフェスであることを表す。 このサーフェスが可視であることを意味する。

DDSCAPS_PRIMARYSURFACELEFT

	このサーフェスが左目用のプライマリ・サーフェスであることを表す。 このサーフェスはユーザの左目に見えるものの内容を表す。 このサーフェスが作られる時、 DDSCAPS_PRIMARYSURFACEフラグを持っているサーフェスは、暗黙のうちに右目用のプライマリ・サーフェスと解釈される。

DDSCAPS_SYSTEMMEMORY

	このサーフェス・メモリがシステム・メモリに割り当てられることを表す。

DDSCAPS_TEXTURE

	このサーフェスを３Ｄテクスチャとして用ることができることを表す。 ただし、必ずしも３Ｄテクスチャとして使わなくてはいけないということではない。

DDSCAPS_VIDEOMEMORY

	このサーフェスがディスプレイ・メモリに存在することを表す。

DDSCAPS_VISIBLE

	このサーフェスに対して行われる変更が即座に画面に反映されることを表す。つねにプライマリ・サーフェスにセットされる。

DDSCAPS_WRITEONLY

	サーフェスが書きこみ専用となることを表す。 サーフェスからの読み出しアクセスが一般保護（ＧＰ）例外を生成する可能性もある。このサーフェスからの読み出し結果の内容は保証されない。

DDSCAPS_ZBUFFER

	このサーフェスがZバッファであることを表す。 Zバッファは表示できない情報を含んでいる。ピクセルの陰面消去等に利用されるビット深度情報を含んでいる。


DDSURFACEDESC

typedef struct _DDSURFACEDESC{

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwHeight;

    DWORD dwWidth;

    LONG  lPitch;

    DWORD dwBackBufferCount;

    union

    {

        DWORD dwMipMapCount;

        DWORD dwZBufferBitDepth;

        DWORD dwRefreshRate;

    };

    DWORD      dwAlphaBitDepth;

    DWORD      dwReserved;

    LPVOID     lpSurface;

    DDCOLORKEY ddckCKDestOverlay;

    DDCOLORKEY ddckCKDestBlt;

    DDCOLORKEY    ddckCKSrcOverlay;

    DDCOLORKEY    ddckCKSrcBlt;

    DDPIXELFORMAT ddpfPixelFormat;

    DDSCAPS       ddsCaps;

} DDSURFACEDESC,  FAR* LPDDSURFACEDESC;

サーフェスを作成するデスクリプタを表す。 この構造体はIDirectDraw2::CreateSurfaceメソッドに渡される。 適切なメンバはそれぞれのタイプのサーフェスにより異なる。

dwSize

構造体の大きさ。 このメンバは構造体が使われる前に値が設定されなくてはならない。

dwFlags

オプション制御フラグ。 以下のフラグのうちひとつまたは複数の属性を持つ。構造体のどのメンバが有効なのか指定する。

DDSD_ALL

	入力されたすべてのメンバが有効であることを表す。

DDSD_ALPHABITDEPTH

	dwAlphaBitDepth メンバが有効であることを表す。

DDSD_BACKBUFFERCOUNT

	dwBackBufferCount メンバが有効であることを表す。

DDSD_CAPS

	ddsCaps メンバが有効であることを表す。

DDSD_CKDESTBLT

	ddckCKDestBlt メンバが有効であることを表す。

DDSD_CKDESTOVERLAY

	ddckCKDestOverlay メンバが有効であることを表す。

DDSD_CKSRCBLT

	ddckCKSrcBlt メンバが有効であることを表す。

DDSD_CKSRCOVERLAY

	ddckCKSrcOverlay メンバが有効であることを表す。

DDSD_HEIGHT

	dwHeight メンバが有効であることを表す。

DDSD_MIPMAPCOUNT

	dwMipMapCount メンバが有効であることを表す。

DDSD_PITCH

	lPitch メンバが有効であることを表す。

DDSD_PIXELFORMAT

	ddpfPixelFormat メンバが有効であることを表す。

DDSD_REFRESHRATE

	dwRefreshRate メンバが有効であることを表す。

DDSD_WIDTH

	dwWidth メンバが有効であることを表す。

DDSD_ZBUFFERBITDEPTH

	dwZBufferBitDepth メンバが有効であることを表す。
dwHeight

サーフェスの高さ。

dwWidth

入力サーフェスの幅。

lPitch

次のライン開始までの距離（返値のみ）（ピッチ）。

dwBackBufferCount

バック・バッファの数。

dwMipMapCount

ミップマップレベルの数。

dwZBufferBitDepth

Zバッファの深度。

dwRefreshRate

リフレッシュ速度（ディスプレイ・モードが記述される時使用される）。

dwAlphaBitDepth

アルファ・バッファの深度。

dwReserved

予約されている。

lpSurface

関連づけられたサーフェス・メモリのアドレス。

ddckCKDestOverlay

オーバーレイ先に使用するカラー・キー。

ddckCKDestBlt

ブロック転送先に使用するカラー・キー。

ddckCKSrcOverlay

オーバーレイ元に使用するカラー・キー。

ddckCKSrcBlt

ブロック転送元に使用するカラー・キー。

ddpfPixelFormat

サーフェスのピクセル・フォーマット記述。

ddsCaps

DirectDraw サーフェス能力。


返値

エラーは負の値によって表され、組み合わされることはない。 このテーブルはすべての IDirectDraw2、IDirectDrawSurface2、IDirectDrawPaletteおよび IDirectDrawClipperインターフェイスのメソッドによって返される可能性のある値をリストアップしている。それぞれのメソッドが返す可能性のあるエラーコードのリストは、メソッドの記述を参照すること。

DD_OK

	要求は成功し完了した。

DDERR_ALREADYINITIALIZED

	オブジェクトはすでに初期化されている。

DDERR_BLTFASTCANTCLIP

	DirectDrawClipper オブジェクトがIDirectDrawSurface2::BltFastメソッドの呼び出しに渡される転送元サーフェスにアタッチされている。

DDERR_CANNOTATTACHSURFACE

	要求されたサーフェスにはサーフェスをアタッチできない。

DDERR_CANNOTDETACHSURFACE

	要求されたサーフェスからサーフェスをデタッチできない。

DDERR_CANTCREATEDC

	Windowsはそれ以上のいかなるデバイス・コンテキスト（ DC ）を作ることができない。

DDERR_CANTDUPLICATE

	プライマリ・サーフェス、3Dサーフェス、暗黙的に作られるサーフェスは複製できない。

DDERR_CANTLOCKSURFACE

	DCI サポートなしでプライマリ・サーフェスのロックをしようとしたため、このサーフェスへのアクセスが拒否された。

DDERR_CANTPAGELOCK

	サーフェスのページ・ロックが失敗した。 ページ・ロックはディスプレイ・メモリ・サーフェスあるいはエミュレートされたプライマリ・サーフェスの上では動作しない。

DDERR_CANTPAGEUNLOCK

	サーフェスのページ・ロック解除が失敗した。 ページ・ロック解除はディスプレイ・メモリ・サーフェスあるいはエミュレートされたプライマリ・サーフェスの上では動作しない。

DDERR_CLIPPERISUSINGHWND

	ウィンドウ・ハンドルをすでにモニターしているDirectDrawClipper オブジェクトにクリップ・リストをセットしようとした。

DDERR_COLORKEYNOTSET

	転送元カラー・キーが指定されていない。

DDERR_CURRENTLYNOTAVAIL

	現在サポートされていない。

DDERR_DCALREADYCREATED

	デバイス・コンテキスト(DC)はすでにこのサーフェスに対し返されている。 一サーフェスにつきひとつのＤＣしか取得することはできない。

DDERR_DIRECTDRAWALREADYCREATED

	DirectDrawオブジェクトはすでに作成されている。

DDERR_EXCEPTION

	要求された処理を行う間に例外が発生した。

DDERR_EXCLUSIVEMODEALREADYSET

	すでに排他的モードがセットされているにもかかわらず、協調レベルをセットしようとした。

DDERR_GENERIC

	未定義のエラー状態である。

DDERR_HEIGHTALIGN

	与えられた矩形の高さは必要とされる整列の倍数ではない。

DDERR_HWNDALREADYSET

	DirectDraw協調レベル・ウィンドウ・ハンドルはすでに設定されている。ウィンドウ・ハンドルはプロセスがサーフェスあるいは生成したパレットを保持している間はリセットできない。

DDERR_HWNDSUBCLASSED

	DirectDraw協調レベル・ウィンドウ・ハンドルが サブクラス化されているため、 DirectDrawの状態のリストアが阻止された。

DDERR_IMPLICITLYCREATED

	暗黙的に作られたサーフェスをリストアしようとした。

DDERR_INCOMPATIBLEPRIMARY

	プライマリ・サーフェス作成要求が既存のプライマリ・サーフェスと一致していない。

DDERR_INVALIDCAPS

	コールバック関数に渡されたひとつ以上の能力ビットが不正である。

DDERR_INVALIDCLIPLIST

	DirectDraw は与えられたクリップ・リストをサポートしない。

DDERR_INVALIDDIRECTDRAWGUID

	DirectDrawCreate 関数に渡されるグローバル・ユニーク識別子（ GUID ）は有効な DirectDraw ドライバ識別子ではない。

DDERR_INVALIDMODE

	DirectDraw は要求されたモードをサポートしない。

DDERR_INVALIDOBJECT

	DirectDraw は無効なDirectDraw オブジェクトのポインタを受け取った。

DDERR_INVALIDPARAMS

	メソッドに渡されたひとつ以上のパラメータが正しくない。

DDERR_INVALIDPIXELFORMAT

	指定されたピクセル・フォーマットは無効である。

DDERR_INVALIDPOSITION

	転送先上のオーバーレイの位置が不正である。

DDERR_INVALIDRECT

	与えられた矩形が無効である。

DDERR_INVALIDSURFACETYPE

	サーフェスが間違ったタイプであったため、要求された処理を実行できなかった。

DDERR_LOCKEDSURFACES

	ひとつ以上のサーフェスがロックされており、要求された処理に失敗した。

DDERR_NO3D

	３Ｄハードウェアあるいはエミュレーションが存在しない。

DDERR_NOALPHAHW

	アルファ・アクセラレーション・ハードウェアが存在しないかあるいは利用できなかったため、要求された処理に失敗した。

DDERR_NOBLTHW

	ブロック転送ハードウェアが存在しない。

DDERR_NOCLIPLIST

	クリップ・リストが利用できない。

DDERR_NOCLIPPERATTACHED

	このサーフェス・オブジェクトにはDirectDrawClipper オブジェクトをアタッチできない。

DDERR_NOCOLORCONVHW

	色変換ハードウェアが存在しない、あるいは利用できないため、処理が実行できない。

DERR_NOCOLORKEY

	サーフェスは現在カラー・キーを持っていない。

DDERR_NOCOLORKEYHW

	転送先カラー・キーに対するハードウェアサポートがないため、処理が実行できない。

DDERR_NOCOOPERATIVELEVELSET

	IDirectDraw2::SetCooperativeLevel メソッドを呼び出すことなく作成関数が呼び出された。

DDERR_NODC

	ＤＣは、これまでにこのサーフェス用に作られていなかった。

DDERR_NODDROPSHW

	DirectDraw ラスタ処理（ ROP ）ハードウェアが利用できない。

DDERR_NODIRECTDRAWHW

	ハードウェア専用 DirectDraw オブジェクト作成できない。ドライバはハードウェアをサポートしない。

DDERR_NODIRECTDRAWSUPPORT

	現在のディスプレイ・ドライバはDirectDrawをサポートしていない。

DDERR_NOEMULATION

	ソフトウェア・エミュレーションが利用できない。

DDERR_NOEXCLUSIVEMODE

	アプリケーションに対し排他的モードが要求されたが、アプリケーションは排他的モードを持っていない。

DDERR_NOFLIPHW

	可視サーフェスはフリッピングできない。

DDERR_NOGDI

	GDI が存在しない。

DDERR_NOHWND

	クリッピング通知がウィンドウ・ハンドルを必要とする、あるいはウィンドウ・ハンドルが協調レベル・ウィンドウ・ハンドルとしてあらかじめセットされていない。

DDERR_NOMIPMAPHW

	ミップマップ・テクスチャ・マッピングのハードウェアが存在していないかあるいは利用できないため、処理を実行できない。

DDERR_NOMIRRORHW

	ミラーリング・ハードウェアが存在しないかあるいは利用できないため、処理が実行できない。

DDERR_NOOVERLAYDEST

	転送先確立のためのIDirectDrawSurface2::UpdateOverlayメソッド呼び出しをしていないオーバーレイに対し、IDirectDrawSurface2::GetOverlayPositionメソッドが呼び出された。

DDERR_NOOVERLAYHW

	オーバーレイ・ハードウェアが存在していないかあるいは利用できないため、処理が実行できない。

DDERR_NOPALETTEATTACHED

	パレット・オブジェクトがこのサーフェスにアタッチされていない。

DDERR_NOPALETTEHW

	16色あるいは256色のパレットに対するハードウェア・サポートがない。

DDERR_NORASTEROPHW

	適切なラスタ処理ハードウェアが存在しないかあるいは利用できないため、処理が実行できない。

DDERR_NOROTATIONHW

	回転ハードウェアが存在していないか、あるいは利用できないため処理が実行できない。

DDERR_NOSTRETCHHW

	拡大ハードウェアが存在していないかあるいは利用できないため、処理が実行できない。

DDERR_NOT4BITCOLOR

	DirectDrawSurface オブジェクトは、要求された４ビット色パレットを使っていない。

DDERR_NOT4BITCOLORINDEX

	DirectDrawSurface オブジェクトは、要求された４ビットのカラー・インデックス・パレットを使っていない。

DDERR_NOT8BITCOLOR

	DirectDrawSurface オブジェクトは、要求された８ビット色パレットを使っていない。

DDERR_NOTAOVERLAYSURFACE

	非オーバーレイ・サーフェスに対し、オーバーレイ・コンポーネントが呼び出された。

DDERR_NOTEXTUREHW

	テクスチャ・マッピング・ハードウェアが存在していないかあるいは利用できないため、処理が実行できない。

DDERR_NOTFLIPPABLE

	フリッピングできないサーフェスをフリッピングしようとした。

DDERR_NOTFOUND

	要求された項目は見つからなかった。

DDERR_NOTINITIALIZED

	オブジェクトが初期化される前に、 CoCreateInstanceで作成された DirectDraw オブジェクトのインターフェイス・メソッドを呼び出そうとした。

DDERR_NOTLOCKED

	ロックされていないサーフェスのロック解除が行われた。

DDERR_NOTPAGELOCKED

	未処理のページ・ロックがないサーフェスのページ・ロック解除が行われた。

DDERR_NOTPALETTIZED

	使用しているサーフェスはパレット・ベースのサーフェスではない。

DDERR_NOVSYNCHW

	垂直帰線同期処理に対するハードウェアサポートがないため、処理を実行できない。

DDERR_NOZBUFFERHW

	Zバッファに対するハードウェア・サポートがないため、ディスプレイ・メモリでのZバッファ作成あるいはZバッファを使用したブロック転送が実行できない。

DDERR_NOZOVERLAYHW

	オーバーレイ・サーフェスは、ハードウェアがオーバーレイ・Zオーダーをサポートしないため、Zオーダーが無視された。

DDERR_OUTOFCAPS

	要求された処理に必要なハードウェアがすでに割り当てられている。

DDERR_OUTOFMEMORY

	DirectDrawが処理を行うのに十分なメモリがない。

DDERR_OUTOFVIDEOMEMORY

	DirectDrawが処理を行うのに十分なディスプレイ・メモリがない。

DDERR_OVERLAYCANTCLIP

	ハードウェアはクリッピング・オーバーレイをサポートしない。

DDERR_OVERLAYCOLORKEYONLYONEACTIVE

	オーバーレイ上にひとつ以上の有効なカラー・キーを持とうとした。

DDERR_OVERLAYNOTVISIBLE

	IDirectDrawSurface2::GetOverlayPosition メソッドが不可視オーバーレイ上で呼び出された。

DDERR_PALETTEBUSY

	パレットがもうひとつのスレッドによってロックされているため、アクセスが拒否された。

DDERR_PRIMARYSURFACEALREADYEXISTS

	この処理はすでにプラリマリ・サーフェスを作成している。

DDERR_REGIONTOOSMALL

	IDirectDrawClipper::GetClipList メソッドに渡された領域が小さすぎる。

DDERR_SURFACEALREADYATTACHED

	すでにアタッチしているもうひとつのサーフェスにサーフェスをアタッチしようとした。

DDERR_SURFACEALREADYDEPENDENT

	すでに他のサーフェスに依存しているサーフェスを依存させようとした。

DDERR_SURFACEBUSY

	サーフェスがもうひとつのスレッドによってロックされているため、サーフェスへのアクセスが拒否された。

DERR_SURFACEISOBSCURED

	サーフェスへのアクセスが、サーフェスが覆い隠されているため拒否された。

DDERR_SURFACELOST

	サーフェス・メモリの不足のため、サーフェスへのアクセスが拒否された。 このサーフェスを表すDirectDrawSurface オブジェクトにはIDirectDrawSurface2::Restoreメソッドが呼び出されなければならない。

DDERR_SURFACENOTATTACHED

	要求されたサーフェスはアタッチできない。

DDERR_TOOBIGHEIGHT

	DirectDraw によって要求された高さが大きすぎる。

DDERR_TOOBIGSIZE

	DirectDraw によって要求された大きさが大きすぎる。 しかし、個別の高さと幅は問題がない。

DDERR_TOOBIGWIDTH

	DirectDraw によって要求された幅が大きすぎる。

DDERR_UNSUPPORTED

	サポートされていない処理であった。

DDERR_UNSUPPORTEDFORMAT

	要求された FourCC フォーマットはDirectDraw によってサポートされていない。

DDERR_UNSUPPORTEDMASK

	要求されたピクセル・フォーマットでの ビットマスク はDirectDraw によってサポートされていない。

DDERR_UNSUPPORTEDMODE

	ディスプレイは現在サポートされていないモードである。

DDERR_VERTICALBLANKINPROGRESS

	垂直帰線期間である。

DDERR_WASSTILLDRAWING

	このサーフェスから、またはサーフェスへの前回のブロック転送操作が完了していない。

DDERR_WRONGMODE

	異なったモードで作られたため、このサーフェスはリストアすることができない。

DDERR_XALIGN

	与えられた矩形を必要とされる範囲に水平一列に並べることができなかった。


 DirectSoundについて

The Microsoftｮ DirectSoundｮ アプリケーション・プログラミング・インターフェイス(API) は、DirectX� 3 Software Development Kit (SDK)のオーディオ・コンポーネントである。DirectSoundは待ち時間（レイテンシ）の少ないミキシング、ハードウェアのアクセラレーション、そしてサウンド・デバイスへのダイレクトなアクセスを実現する。これらの機能の実現のためには、現存のWindows上のアプリケーションとデバイス・ドライバとの間の互換性が必要条件となる。

DirectX 3によって、ハードウェアに関する詳細な知識なしでディスプレイやオーディオ・デバイスへアクセスすることが可能になる。DirectX設計時の最優先目的事項はスピードである。高レベル関数群により、 DirectSoundはデバイス非依存インターフェイスを提供し、それによってアプリケーションはオーディオ機器の能力を最大限に引き出すことができる。


DirectSoundアーキテクチャ

この節では、DirectSoundコンポーネントとその他の DirectX、オペレーティング・システム、システム・ハードウェアの関係についての一般的な情報を説明する。

アーキテクチャ概要

オブジェクト・タイプ

ソフトウェア・エミュレーション

デバイス・ドライバ

協調レベル

システムの統合


アーキテクチャ概要

ハイパフォーマンスのアプリケーションやゲームのプログラミングには、効果的で力強いサウンド作りが求められる。Microsoftがそのために提供しているのがMIDIストリームとDirectSoundのふたつのメソッドである。 MIDIストリームは、Windows 95マルチメディアAPIの一部である。 MIDIストリームはMIDIメッセージにタイムスタンプを付け、そのメッセージのバッファをシステムへ送信する。MIDIストリームについての詳細情報は、 Microsoft Win32ｮ Software Development Kit (SDK)に含まれるドキュメントを参照すること。

一方、DirectSoundは、デジタル録音されたサンプリング・サウンドの再生とサンプリング音源のミキシングの新しいモデルを実装している。 他のDirectX 3 SDKのオブジェクト・クラスと同様、 DirectSoundはハードウェアの機能を最大限に引き出し、ハードウェアで現在未サポートの能力があれば、それをソフトウェアでエミュレートする。実行時にハードウェアの能力の照会ができ、パソコン環境にかかわりなく最高の性能を引き出すことができる。

DirectSoundはIDirectSoundとIDirectSoundBufferというCOMベースのインターフェイス上に構築され、他のインターフェイスへ拡張もできる。DirectX 3 SDKでアプリケーションの作成にはCOMの概念への理解を要するが、これについてはコンポーネント・オブジェクト・モデルを参照すること。

DirectSoundオブジェクトは、サウンド・カードとその様々な属性を表す。アプリケーションはDirectSoundオブジェクトのIDirectSound::CreateSoundBufferメソッドを使用してDirectSoundBufferオブジェクトを作成する。DirectSoundBufferオブジェクトとは、バッファを含むサウンド・データのことである。プライマリDirectSoundBufferオブジェクトには複数のDirectSoundBufferオブジェクトが存在し、相互にミキシングが可能である。DirectSoundバッファは周波数・フォーマットなどの属性を設定するとともに、サウンドの再生・停止・一時停止に使用される。

DirectSoundバッファは、オンボードRAM、 ウェーブテーブル・メモリ、ダイレクト・メモリ・アクセス(DMA)チャネル、仮想バッファ(I/Oポートがひとつのオーディオ・カードの場合)のいずれかのハードウェア用に作成される。バッファ作成は、カードのタイプに依存する。DirectSoundバッファのためのハードウェアがない場合は、システム・メモリでエミュレートされる。

プライマリ・サウンド・バッファは通常セカンダリ・サウンド・バッファから送られるサウンドのミキシングのために使用されるが、カスタム・ミキシングやその他の特別な動作で直接アクセスすることもできる(プライマリ・バッファをロックすると、サウンド機器への他のソースからのアクセスもブロックされてしまう。ロックする際は警告を出すこと)。

セカンダリ・バッファには、ゲーム・アプリケーションの実行中、くり返し再生される共通サウンドを記憶しておくことができる。セカンダリ・バッファに記憶されたサウンドは、アプリケーションの中で、1回限りのイベントとして再生することも、連続してくり返し再生されるルーピング・サウンドとして再生することも可能である。

さらに、セカンダリ・バッファは、有効なサウンド・バッファ・メモリよりも大きいサイズのサウンドを再生することができる。サウンド・バッファ・メモリよりも大きいサウンドの再生にセカンダリ・バッファを使用すると、セカンダリ・バッファは再生するサウンドの一部分を記憶するキューを用意するようになる。


オブジェクト・タイプ

まず、第一の基本的なオブジェクト・タイプはDirectSoundオブジェクトで、これはサウンド・カードのことである。IDirectSoundオブジェクトを制御しているのは、IDirectSoundコンポーネント・オブジェクト・モデル(COM)インターフェイスである。このインターフェイスのメソッドにより、アプリケーションからカードの特性を変更することができる。

第二のオブジェクト・タイプはサウンド・バッファである。DirectSoundはプライマリ・サウンド・バッファ、およびセカンダリ・サウンド・バッファを使用する。プライマリ・サウンド・バッファとは実際にユーザが聞き取れるオーディオ・データのことであり、セカンダリ・サウンド・バッファとはそれぞれの音源のことである。DirectSoundは、プライマリ・サウンド・バッファ、およびセカンダリ・サウンド・バッファに対して制御を行い、それらは IDirectSoundBufferインターフェイス内にある。

プライマリ・バッファは、出力形式、トータル・ボリュームなど、サウンドの特性を制御する。また、作成したアプリケーションから直接プライマリ・バッファへの書きこみを行える。ただしその場合は、DirectSoundミキシングとハードウェア・アクセラレーションの機能は無効になる。さらに、プライマリ・バッファへの直接的な書きこみは、他のDirectSoundアプリケーションの動作を妨げることにもなる。したがってアプリケーションからの書きこみは、プライマリ・バッファにではなくセカンダリ・バッファへ行う方がよい。セカンダリ・バッファであれば、ハードウェアが現在持っていない機能をエミュレートすることができ、さらにサウンド・カードをシステム内の他のアプリケーションと共有することもできるからである。

セカンダリ・バッファとはアプリケーションが使用する個々の音源のことである。ひとつのアプリケーションから、それぞれのバッファを個々に再生・停止することができる。DirectSoundは再生中のバッファをすべてプライマリ・バッファ上でミキシングし、そのプライマリ・バッファをサウンド・デバイスへ出力できる。セカンダリ・バッファはハードウェア、もしくはシステム・バッファへ常駐させることができる。ハードウェア・バッファはサウンド・デバイス上でミキシングされるので、システム上の処理に負担をかけることがない。

セカンダリ・サウンド・バッファには、スタティック・サウンド・バッファ、およびストリーム・サウンド・バッファの２種類がある。スタティック・サウンド・バッファとは、サウンド・データ全体を収容するバッファである。ストリーム・サウンド・バッファとはサウンドの一部だけを収容するバッファであり、そのために再生中はアプリケーションから絶えず新しいデータをバッファへ書きこむ必要がある。サウンド機器上のサウンド・メモリが有効であれば、 DirectSoundはそれを利用してスタティック・バッファを確保しようとする。サウンド機器上に確保されたバッファは、ハードウェア上でミキシングが完了しているため、再生中にシステム処理時間を消費することがない。銃声音などのくり返し使われるサウンドには、スタティック・バッファの使用が最適である。 アプリケーションは、サウンド・バッファ内にあるカレント・プレイ・ポジションとカレント・ライト・ポジションというふたつの重要なポジションで動作する。カレント・プレイ・ポジションは、バッファの中のサウンドの再生が開始される位置を示している。カレント・ライト・ポジションは、バッファの中で安全にデータを変更できる位置を示している。次の図はこのふたつのポジションの関係を示している。

DirectSoundバッファは概念的にはリング状になっているが、実際には連続したリニアなメモリで作成されている（リング・バッファ）。カレント・プレイ・ポジションはバッファの最後までくると開始位置まで戻る。

この章では、DirectSound、および DirectSoundBufferオブジェクトについてと、アプリケーションにおけるこれらオブジェクトの利用方法を解説する。

DirectSoundオブジェクト

DirectSoundBuffer オブジェクト


DirectSoundオブジェクト

システムにインストールされているそれぞれのサウンド・デバイスはDirectSoundオブジェクトであり、 IDirectSoundインターフェイスを通してアクセスが行われる。DirectSoundオブジェクトの作成は DirectSoundCreate関数を呼び出して行う。この関数は返値として、ひとつのIDirectSoundインターフェイスを返す。 DirectSoundEnumerate関数を呼び出すと、システムにインストールされているDirectSoundオブジェクトを列挙する。

Windowsはマルチタスク・オペレーティング・システムである。ユーザが一度に複数のプログラムを走らせ、それらすべてにリソースを共有させたいと考えるのは当然である。DirectSoundオブジェクトは入力フォーカスの追跡を行ってサウンド・デバイスを共有する。DirectSoundオブジェクトは、それぞれが担当するアプリケーションが入力フォーカスを得た時にだけ音を鳴らす。あるアプリケーションが入力フォーカスを失うと、そのオブジェクトからのオーディオ・ストリームはミュートされる。複数のアプリケーションが同じサウンドデバイスに対するそれぞれのDirectSoundオブジェクトを作成することも可能である。アプリケーション間で入力フォーカスが変わると、オーディオ出力は自動的にそのアプリケーションのストリームから次のアプリケーションのストリームへ切り替わる。結果的に、アプリケーションは入力フォーカスが変わるたびにバッファの再生・停止を繰り返す必要がなくなる。

Note

DirectSoundのヘッダファイルはIDirectSoundのメソッドとIDirectSoundBufferインターフェイスで定義された、C言語のマクロ定義を含んでいる。


DirectSoundBufferオブジェクト

ひとつひとつのサウンドおよびオーディオ・ストリームはDirectSoundBufferであり、アプリケーションはIDirectSoundBufferインターフェイスを通してこれらへのアクセスを行う。IDirectSound::CreateSoundBufferメソッドを呼び出すと、DirectSoundBufferオブジェクトを作成することができる。この返値はIDirectSoundBufferインターフェイスである。

また、アプリケーションはプライマリ・サウンド・バッファとセカンダリ・サウンド・バッファを作成することができる。現在のところは、ひとつのDirectSoundオブジェクトにつき、ひとつのプライマリ・バッファしか持つことができない。

アプリケーションによるサウンド・バッファへのデータの書きこみは、まずバッファをロックしてから書きこみを行い、その後にバッファのロックを解除する。バッファをロックするにはIDirectSoundBuffer::Lockメソッドを呼び出す。このメソッドはロックされたバッファのポインタを返す。バッファがロックされると、アプリケーションによるオーディオ・データのバッファへのコピーが可能になる。バッファへのデータ書きこみ終了後、バッファのロックを解除して書きこみ操作を完了する。バッファのロックを解除するにはIDirectSoundBuffer::Unlockメソッドを呼び出す。

プライマリ・サウンド・バッファには実際に聞き取り可能なデータが格納される。 IDirectSoundBuffer::Playメソッドを使用することにより、セカンダリ・サウンド・バッファからのオーディオ再生も可能である。このメソッドを使用すると、DirectSoundはセカンダリ・バッファをプライマリ・バッファへミキシングする。ミキシングできない場合、 IDirectSoundBuffer::Playは１回だけバッファを再生して最後で停止する。このメソッド内に DSBPLAY_LOOPINGフラグを指定すると、連続ループの中で繰り返しサウンドを再生できる。再生中のバッファを停止するにはIDirectSoundBuffer::Stopメソッドを使用する。

サウンド・バッファごとのアプリケーションによる使い分けは、サウンドの再生時間で決定する。サウンドの長さが数秒程度であれば、スタティック・サウンド・バッファへサウンドを格納することができる。それよりも長いサウンドであれば、ストリーム・サウンド・バッファを使用するとよい。

スタティック・バッファを持つDirectSoundBufferオブジェクトを作成するには、 IDirectSound::CreateSoundBufferメソッドを使用して、 DSBCAPS_STATICフラグを明記する (このフラグを指定しなければ、ストリーム・バッファが作成される)。 DirectSoundは、サウンド機器が有効であれば、その機器上にあるサウンド・メモリを使用してスタティック・バッファへの格納を試みる。サウンド機器上に記憶されたバッファはミキシングがハードウェア上で行われるため、再生中にCPUパワーを消費しない。エンジン音、歓声、やじなどのくり返し使われるサウンドは、スタティック・バッファ用として最適である。

ハードウェア・ミキシングをサポートした高速バス（PCIのような）上のサウンド・デバイスであれば、ストリーム・バッファを利用することも可能である。しかしコンピュータが高速バスを持っていない場合は、ハードウェア ・ミキシングの利点よりデータ転送のオーバーヘッドのほうが大きくなってしまう。 DirectSoundは、サウンド・デバイスが高速バス上にある場合にだけストリーム・バッファをハードウェア上に作成する。


ソフトウェア・エミュレーション

DirectSoundは、あるサウンド・カードが実際にはサポートしていない機能を、ソフトウェアでエミュレートできる。 IDirectSound::GetCapsメソッドを使用すれば、アプリケーションからDirectSoundに対してオーディオ機器の機能を報告するよう要求できる。これによって、ハイパフォーマンスのゲームでそのオーディオの特性を調べるといったことが可能である。


デバイス・ドライバ

DirectSoundは、オーディオ・デバイス・ドライバが実装するインターフェイス、 DirectSound HALを用いてサウンド機器へアクセスする。これはWindowsのオーディオ・デバイス・ドライバ であり、HALをサポートするために変更を加えられている。 このドライバ・アーキテクチャは、現存するWindowsベースのアプリケーションに下位互換性を提供する。DirectSound HALが提供する機能は、次の通りである。

オーディオ機器に対するコントロールの取得と解放

オーディオ機器の性能評価

ハードウェアが有効な場合の特定の操作の実行

ハードウェアが無効な場合の操作要求の拒否

デバイス・ドライバはソフトウェア・エミュレーションを一切行わない。ハードウェアの性能をDirectSoundへ通知し、DirectSoundからの要求をハードウェアに伝えるだけである。もし要求された操作をハードウェアが実行できない場合、DirectSoundがそれをエミュレートする。

DirectSoundがハードウェアとの交信を行う時にDirectSoundドライバが有効でない場合には、標準のWindows 95、Windows NTｮ、Windows 3.1のオーディオ・デバイス・ドライバを使用する。この場合、DirectSoundの機能はソフトウェア・エミュレーションによりすべて有効となるが、ハードウェアのアクセラレーションは不可能となる。


協調レベル

DirectSoundは、サウンド・デバイスに対して標準、 優先、排他、書きこみ優先の4つの協調レベルを定義する。アプリケーションは IDirectSound::SetCooperativeLevelメソッドを使用してサウンド・デバイスの協調レベルを設定する。また、書きこみ優先を除くすべての協調レベル内にグローバル・サウンド・バッファ、もしくはスティッキー・サウンド・バッファを作成することができる。

「標準」協調レベルはもっとも下位のレベルである。標準レベルでは、 IDirectSoundBuffer::SetFormat、およびIDirectSound::Compactメソッドの呼び出しは不可能である。 さらに、アプリケーションでのプライマリ・バッファへの書きこみができない。この協調レベルでアプリケーションを使用している時にスムーズなタスク切り替えを行うには、22 kHzのプライマリ・バッファ、ステレオサウンド、そして8ビットサンプリングのフォーマットを使用する。

DirectSoundオブジェクトを「優先」協調レベルで使用すると、アプリケーションは、ハードウェア・ミキシングなどのハードウェア・リソースに対して第一級の優先度を持つことができ、 IDirectSoundBuffer::SetFormat と IDirectSound::Compactを呼び出すことができる。

DirectSoundオブジェクトを「排他」協調レベルで使用すると、アプリケーションは優先レベルにおけるすべての特権を持つことができる。しかし、そのアプリケーションが入力フォーカスを持つ場合、そのバッファのみからしか音が聞こえない。入力フォーカスの獲得後、DirectSoundはアプリケーションで優先されるwaveフォーマットをリストアする。優先されるwaveフォーマットとは、 IDirectSoundBuffer::SetFormatの呼び出しでもっとも最近に定義されたもののことである (DirectSoundは優先レベルに関係なくwaveをリストアする)。

最も上位の協調レベルは「書きこみ優先」である。 DirectSoundオブジェクトを書きこみ優先協調レベルで使用すると、サウンド・バッファへダイレクトにアクセスできる。このモードでは、アプリケーションがIDirectSoundBuffer::Lockメソッドを用いてバッファをロックし、プライマリ・バッファに直接書き込むことになる。この際、セカンダリ・バッファの再生はできない。

書きこみ優先協調レベルに設定されているアプリケーションが入力フォーカスを取得すると、他のアプリケーションのセカンダリ・バッファはすべて停止され、データは失われる(これらのバッファを再び再生させるには、IDirectSoundBuffer::Restoreメソッドでリストアを行う必要がある)。 このアプリケーションが入力フォーカスを失えば、プライマリ・バッファのデータは失われるが、アプリケーションが入力フォーカスを再取得すればリストアも可能である。

書きこみ優先レベルは、プライマリ・バッファを作成するための必要絶対条件ではない。しかし、プライマリ・バッファ内のサンプリング・オーディオへアクセスするためには、アプリケーションが書き込み優先レベルに設定されている必要がある。このレベルにセットされていないと、たとえIDirectSoundBuffer::GetFormat, IDirectSoundBuffer::SetFormat,  IDirectSoundBuffer::GetVolumeなどのメソッドの呼び出しに成功したとしても、 IDirectSoundBuffer::Lock 、および IDirectSoundBuffer::Playの呼び出しには失敗する。


システムの統合

次の図はDirectSoundとその他のシステムオーディオ・コンポーネントとの関係を示している。

DirectSound HAL用に作られたサウンド・デバイス・ドライバは、オーディオ再生時に最高の能力を発揮する。デバイス・ドライバはHALの機能を各々実行してサウンド機器のアーキテクチャへ働きかけ、その機能性とパフォーマンスを引き出す。HALはハードウェアの能力をDirectSoundへと知らせ、DirectSoundからの要求をハードウェアへと伝える。もしハードウェアが要求に応える能力がない場合は、DirectSoundがソフトウェアでエミュレートする。

DirectSoundドライバがない場合でもアプリケーションでのDirectSound関数の使用は可能である。サウンド機器にDirectSoundドライバがインストールされていない場合、DirectSoundが使用するのはHALエミュレーション・レイヤである。このレイヤではWindowsマルチメディアのウェーブフォーム・オーディオ関数を使用している。

DirectSound関数とウェーブ・オーディオ関数を用いると、サウンド機器のウェーブフォーム・オーディオへのパスに選択肢が与えられる。 ひとつのデバイスでは、一度にアクセスを提供するパスはひとつである。ウェーブフォーム・オーディオ・ドライバがひとつのデバイスを割り当てる場合、DirectSoundでの同デバイスへの割り当ては失敗する。同様に、DirectSoundがひとつのデバイスを割り当てると、ウェーブフォーム・オーディオ・ドライバでのデバイスの割り当ては失敗する。

アプリケーションが両方の関数を使用する必要がある時には、それぞれの関数を交互に使用すればよい。つまり、 DirectSoundCreate関数でサウンド・ハードウェアをオープンし、 IDirectSoundおよびIDirectSoundBufferインターフェイスでサウンドを再生し、 IDirectSound::Releaseメソッドで同ハードウェアをクローズするといったことが可能である。サウンド・ハードウェアが有効となるのは、Win32 SDKのウェーブフォーム・オーディオ関数による。

ふたつのサウンド・デバイスがシステムにインストールされている場合もまた同様に、DirectSound関数とウェーブフォーム・オーディオ関数のどちらを用いても、アプリケーションはそれぞれのデバイスに独立したアクセスが可能である。

ある種のアプリケーションにおけるウェーブフォーム・オーディオ関数の使用は、非常に有効な解決法となることがしばしばある。たとえば、 PlaySoundおよびWaveOut関数の使用によって、導入音などの単一のサウンドやオーディオ・ストリームの再生が容易になる。

Note

Microsoft Video for Windowsは、現在avi(audio visual interleaved)ファイルのオーディオ・トラックを出力するのにウェーブフォーム・オーディオ関数を使用している。そのため、アプリケーションがDirectSoundを使用してからaviファイルを再生しようとしても、そのオーディオ・トラックは再生できない。同様に、aviファイルを再生してからDirectSoundオブジェクトを作成しようとしても、作成時の関数はエラーを返す。

現在のところでは、アプリケーションがDirectSoundオブジェクトを解放するためには、aviファイルの再生前にIDirectSound::Releaseの呼び出しを行う。アプリケーションはビデオの再生終了後にDirectSoundオブジェクトとそのDirectSoundBufferオブジェクトの再作成と再設定を行える。


DirectSound概要

この節ではDirectSoundコンポーネントの一般的な情報について解説する。

DirectSoundの特徴

3Dサウンド


DirectSoundの特徴

この節ではDirectSoundのオーディオ・ミキシングと、ハードウェア・アクセラレーションを利用した能力について解説する。さらに、アプリケーションをデザインする際のプライマリ・サウンド・バッファへの書きこみ時に考慮すべき点についても解説する。

ミキシング

ハードウェア・アクセラレーション

プライマリ・バッファへの書きこみアクセス


ミキシング

DirectSoundで使用頻度がもっとも高いのは、わずかなレイテンシでオーディオ・ミキシングを行う機能である。レイテンシとは、サウンド・バッファが作成されてからスピーカで再生されるまでにかかる時間のことである。アプリケーションは、ひとつまたはそれ以上のセカンダリ・サウンド・バッファを作成してそれらにオーディオ・データを書きこむことができる。そして、再生、または停止するバッファの選択ができる。DirectSoundは再生中のバッファをすべてミキシングする。そして、ミキシングした結果を、サウンド機器へのオーディオ・データの供給をしているプライマリ・サウンド・バッファに書きこむことができる。DirectSoundがミキシングできるバッファの数は、有効な処理時間によってのみ制限を受ける。

レイテンシが20ミリ秒以下の場合、ユーザがバッファの作成からスピーカの再生までの遅延を感じることはない。DirectSoundミキサーのレイテンシは20ミリ秒なので、再生が始まるまでの遅延は知覚されないのである。この条件下だと、バッファを再生すると同時にスクリーン・アニメーションを開始すれば、オーディオとビデオは同時にスタートする。しかし、DirectSoundがHELを使用しなくてはならない場合(サウンド機器用のDirectSoundドライバがない場合)、ハードウェアに依存する遅延(通常100～500ミリ秒)が、サウンドが再生される前に発生する。

どのような場合でも、再生できるのはひとつのアプリケーションのバッファのみとなる。これは、一度に特定のDirectSoundドライバをオープンできるのがひとつのアプリケーションのみであるためである。


ハードウェア・アクセラレーション

DirectSoundはハードウェア・ミキシングやハードウェア・サウンド・バッファメモリ等のサウンド機器を自動的に高速化する。アプリケーションからは、特にハードウェア・アクセラレーションの設置要求を行う必要はない。

ただし、現在のハードウェアのリソースを最大限に利用したいと考えるなら、 DirectSoundに対してサウンド・デバイスのハードウェア性能情報の表示を要求する方法がある。この情報から、ハードウェア・アクセラレーションを行う際の対象となるサウンド・バッファの指定ができるようになる。

これは、それぞれの効果使用やサウンド・バッファ再生のタイミング、バッファ取得の優先度などをアプリケーション側で決定することができ、必要なハードウェアのリソースの割り振りができるからである。


プライマリ・バッファへの書きこみアクセス

プライマリ・サウンド・バッファはサウンド・デバイスからサンプリング・オーディオを出力する。DirectSoundではプライマリ・バッファへの直接書きこみアクセスができる。この機能は、非常に限られた種類のアプリケーション、つまり特化されたミキシングや、その他セカンダリ・バッファでサポートしていない機能付きアプリケーションでのみ有用である。アプリケーションからプライマリ・バッファへ直接書きこみを行うと、どうしてもサウンドが途切れやすくなる。プライマリ・バッファへ直接アクセスを行うアプリケーションは、パフォーマンス条件が厳しくなるのである。

プライマリ・バッファは通常とても小さい。そのため、この種のバッファへ直接書きこみを行う場合は、すでにバッファ内にあるブロックが繰り返し再生されないよう、データ・ブロックへの書きこみを短い間隔で行わなければならない。バッファ作成中はバッファのサイズは指定できないため、作成作業終了後にできあがったサイズを受け入れることになる。

プライマリ・サウンド・バッファに対する書きこみアクセスを獲得すると、他のDirectSoundの機能は無効になる。セカンダリ・バッファはミキシングされないため、ハードウェア・アクセラレーション・ミキシングは無効になる (DirectSoundがセカンダリ・バッファでミキシングを行うと、ミキシングされたオーディオ・データはプライマリ・バッファに置かれる)。

アプリケーションの多くは、プライマリ・バッファへ直接アクセスせずにセカンダリ・バッファを使用する。セカンダリ・バッファへの書きこみは自由に行える。大きなバッファが次のデータ・ブロックへの書きこみまでの時間を稼ぎ、それによってオーディオで音が途切れる危険を最小限にとどめるのである。たとえ、アプリケーションからのオーディオへの要求が、ミキシングを必要としないオーディオ・ストリームのようなシンプルなものであっても、そのオーディオ・データの再生にセカンダリ・バッファを使用することで高いパフォーマンスを実現することができる。


3Dサウンド

DirectSoundにより、アプリケーションは音源が識別される位置（定位）を変更することができる。これには、IDirectSound3DBuffer、およびIDirectSound3DListenerインターフェイスを使用する。ちなみに音源とは、音が全方向へ広がるときの中心位置、もしくは音が円錐状に小さくなっていくときの頂点のことである。また、ドップラー効果をかけることもできる。標準的なラウド・スピーカを使用してもこれらの効果は聞き取り可能だが、ヘッドホンを使えばこれらの効果がさらに明確に聞き取れる。

3Dサウンドの概要として、ここでは以下のトピックについて説明する。

音像定位の認識

リスナー

サウンド・コーン

最短距離と最長距離

位置と速度

Direct3Dへの統合

測定単位と距離要素

モノラル音源とステレオ音源


音像定位の認識

現実世界では、空間における音像定位の認識は、多数の要素に影響される。次に示すのはその一部である。

ボリューム。音を出す物体がリスナーから離れるほど、その音は小さくなっていく。この現象はロールオフと呼ばれている。

到達のずれ。リスナーの右方向から発せられた音はがリスナーの右耳に到達するのは、左耳よりもほんの少し先である (このずれの持続時間は、約1ミリ秒である)。

消音。リスナーの後ろからくる音は、前からきた音に比べてかすかに消音されている。これにより人の耳の方向確認は確実になる。さらに、リスナーの右から音がきた場合も、左耳に届く音は頭ひとつぶん消音される。

これらは、人が音の位置を識別するための、すべてではないが主な要素である。そしてこれらの要素がDirectSoundのポジショニング・システムの中で提供されているのである。将来3Dサウンドをサポートするハードウェアが一般的になれば、これ以外のポジショニング要素がシステムに組み込まれることだろう。たとえば、リスナーの頭の質量または肩や外耳への反射による消音は、高周波と低周波とでは異なってくる。

しかし、最も重要な音の位置識別要素は、音源の視覚的な位置である。たとえば、遠くにある、小さな点として見えていた発射体が、見ている人の頭上を越える前に大陸間弾道ミサイルの大きさにになっていれば、こまごまとした手がかりなどがなくても、音は確実にそのリスナーに近づき、去ってていくだろう。


リスナー

物体がリスナーの周りを90度回転した場合と、リスナーが物体に相対して90度頭を回転させた場合とでは、リスナーが経験する音響効果は同一である。しかしプログラム上では、リスナーの位置や方向を変更する方が、場面の中の他のすべての物体の位置を変えるより簡単なことが多い。DirectSoundは、IDirectSound3DListenerインターフェイスを通じてこの能力を提供している。


サウンド・コーン

位置はあるが方向のない音は点音源である。どの方向であってもリスナーが音から離れれば、音は小さくなる。位置と方向のある音をサウンド・コーンという。

DirectSoundのサウンド・コーンには内部コーンと外部コーンがある。内部コーンのなかでは、ボリュームはその音源の最大レベルとなる(DirectSoundでは増幅をサポートしておらず、最大ボリューム・レベルは0である。その他のすべてのボリューム・レベルは、最大ボリュームから減衰していくという意味で、負の値になる)。外部コーンの外側では、ボリュームは、内部ボリュームに特定の外部ボリュームを加えたものとなる。たとえば、アプリケーションが外部ボリュームを-10,000にセットすると、その音源は外部コーンの外では聞き取れない。外部コーンと内部コーンの間では、ボリュームはあるレベルから別のレベルに徐々に変化する。サウンド・コーンの概念を次の図に示す。

 技術的には、 IDirectSound3Dbufferインターフェイスであるサウンド・バッファはすべてサウンド・コーンである。たとえば、サウンド・コーンの外部のボリュームの初期値は0である。アプリケーションでこの値を変えても、ボリュームはコーンの内部でも外部でも同じで、音は明確な方向を一切もたない。さらに、サウンド・コーンの角度は好きなだけ広げられるが、実際のサウンド・コーンは球状に作られていく。


最短距離と最長距離

リスナーが音源に近づけば、音は大きくなっていく。しかし、最大値(0)に到達したり、音源の性質上論理的な限界に至った場合など、一定のポイントを通過した時以後は、ボリュームは大きくなり続けない。これを音源の最短距離という。同様に、音源の最長距離とは、これ以上音が小さくならないという位置を超えた場合の距離を言う。

別々の音の絶対ボリューム・レベルの違いを補償しなければならない場合、最短距離は特に有用である。たとえば、ジェット機の音はみつばちの羽音よりも大きくなければならないが、ある理由からこれらの音は同じ絶対ボリューム・レベルで録音されなければならない(16ビットのオーディオにはこのようなボリューム・レベルの差違を吸収するだけの余地がない)。たとえば、 ジェット機には100メートルの、みつばちには2センチメートルの最短距離を使用したとする。この設定であれば、ジェット機はリスナーが200メートル離れたときにボリュームが半分になるが、みつばちはリスナーが4センチメートル離れただけで半分のボリュームになる。この概念は次の図に示す。


位置と速度

すべての3Dサウンド・バッファと3Dリスナーにはある位置とある速度がある。グラフィックとアニメーションの見地からは、これらの特性はまったく同じにみえる。その気になれば、3Dサウンド・バッファまたは3Dリスナーの位置を、その3D空間内における位置として表すことはできる。しかし、バッファやリスナーがその物体が空間を移動している速さを速度で表すことはできない。バッファやリスナーの速度は、 DirectSoundではドップラー効果の計算に使用される。

速度調節は、物体のドップラー効果を強調したい場合に有用である。たとえば、うなりをあげて走ってくるレーシングカーがリスナーの横を通り過ぎるときの音が欲しいとしよう。もしリスナーに対してドップラー効果を強調させたとすると、その強調はリスナーに聞き取り可能なすべてのサウンド・バッファに影響を及ぼしてしまう。 レーシングカーにだけこの効果を強調させるには、レーシングカーの3Dサウンド・バッファの速度設定を拡大すればよい。

システムはドップラー効果を累積的に扱う。アプリケーションのリスナーと音源が速度を持っていれば、システムは自動的にその速度間の関係を計算し、ドップラー効果を速やかに調節する。


Direct3Dへの統合

IDirectSound3DBuffer、およびIDirectSound3DListenerインターフェイスはDirect3D�と一緒に動作するように設計されている。 Direct3Dが仮想環境のなかのオブジェクトをアレンジするために使用するポジショニング情報は、音源をアレンジするためにも使用される。 Direct3D開発者には周知のD3DVECTORとD3DVALUEタイプは、 IDirectSound3DbufferとIDirectSound3DListenerインターフェイスでも使用される。 また、Direct3Dで使用されている左手座標系と同じものがDirectSoundでも採用されている(座標系については、 Direct3D概要の中の3D座標系を参照すること)。

3Dサウンドの再生を簡単にするためには、 Direct3Dのシステム・コールバック機構を利用する。たとえば、 D3DRMFRAMEMOVECALLBACKコールバック関数を使用すれば、アプリケーション内のフレームの動きを監視し、特定の状態に達したときだけ音の環境を変えることができる。


測定単位と距離要素

3Dサウンド効果のデフォルト値は、自然界を模倣したのもである。しかし、多くの設計者は、よりドラマティックな効果を追求してこの値を変更しようとする。アプリケーションはよりエキサイティングなものとするためには、ドップラー効果を強調したり、距離による音の減衰を強調させる。

DirectSoundの3D効果では、距離の測定単位として、メートルを使用する。もしアプリケーションでメートルを使用していない場合も、そのコンポーネントの能力を維持するために測定単位の変換は不要である。代わりにアプリケーションでは距離要素を設定することができる。これはアプリケーションで指定した距離単位をメートルに換算する浮動小数点の値である。たとえば、アプリケーションが測定単位としてフィートを使用した場合、距離要素として0.30480006096を指定できる。この値は、1フィートをメートルに換算した値である。


モノラル音源とステレオ音源

3Dサウンドの環境ではステレオ音源は特に有効ではない。単一のステレオ信号は、結果的に、同時に別々のスピーカで再生されるふたつの分割されたモノラル・トラックとして構成される。

DirectSoundの3D機能を利用するときは、モノラル音源を用意すること。システムがステレオ音源をモノラルに変換する機能を備えていたとしも、ステレオを使用する意味はなく、変換時間の無駄になる。


DirectSoundインターフェイス概要

この節では以下のDirectSoundインターフェイスについて一般的な情報を解説する。

IDirectSoundインターフェイス

IDirectSound3DBuffer インターフェイス

IDirectSound3DListener インターフェイス

IDirectSoundBuffer インターフェイス


IDirectSoundインターフェイス

DirectSoundオブジェクトはシステム上のハードウェアを表している。オーディオ・データ自体はDirectSoundBufferオブジェクトを呼び出したバッファ内に常駐する。DirectSoundバッファについての詳細は、IDirectSoundBufferインターフェイスを参照すること。IDirectSoundインターフェイスを使用すると、サウンド・カード、スピーカ、メモリ環境のアプリケーションからの定義が可能になる。

この節では、システム内のサウンド・デバイスの性能の取得方法、サウンド・バッファの作成法、システム・スピーカの環境設定法およびハードウェアのコンパクトなメモリ設定方法の解説をする。

デバイスの性能

バッファの作成

スピーカの環境設定

ハードウェアメモリ管理


デバイスの性能

DirectSoundCreate関数を呼び出してDirectSoundオブジェクトを作成した後は、IDirectSound::GetCapsメソッドを使用することでサウンド・デバイスの性能を取得できる。 最適なパフォーマンスを得るためには、この呼び出しを行うことで常駐のサウンド・カードの性能を測定し、サウンドのパラメータを適正なものに変更する。


バッファの作成

DirectSoundCreate関数を呼び出してDirectSoundオブジェクトを作成し、サウンド・デバイスの性能を調査した後は、アプリケーションは、オーディオ・データを含むサウンド・バッファを作成・列挙することができる。IDirectSound::CreateSoundBufferメソッドはサウンド・バッファを作成する。IDirectSound::DuplicateSoundBufferメソッドは、最初と同じ物理バッファ・メモリを使用してセカンド・サウンド・バッファを作成する。サウンド・バッファをコピーした場合、バッファ・メモリを消費することなく両方のバッファを別々に再生することができる。

サウンド・デバイスに対して協調レベルを設定するにはIDirectSound::SetCooperativeLevelメソッドを使用する。これは、サウンド・バッファを再生する前に行う必要がある。ほとんどのアプリケーションは標準の協調レベルであるDSSCL_NORMALを使用する。このレベルは、他のアプリケーションと競合することは決してない。


スピーカの環境設定

IDirectSoundインターフェイスには、システム内のスピーカの調査・環境設定を行うふたつのメソッドが含まれている。IDirectSound::GetSpeakerConfigおよびIDirectSound::SetSpeakerConfigメソッドである。現在のところ、環境としては、イヤホン、ヘッドホン、ステレオ、4チャンネルの録音再生、サラウンド・サウンドがある。


ハードウェアメモリ管理

IDirectSound::Compactメソッドを使用すると、オンボードのサウンド・メモリをすべて連続ブロックへ移動して最大のフリーメモリ領域を作成することができる。


IDirectSound3DBufferインターフェイス

IDirectSound3DBufferインターフェイスは、サウンド・バッファの3Dパラメータに対するアクセスを提供している。このインターフェイスはすべてのサウンド・バッファでサポートされているわけではない。

この節ではIDirectSound3DBufferインターフェイスのポインタを取得する方法と、インターフェイス・メソッドを使用したバッファ・パラメータの管理について説明する。以下のトピックについて説明する。

IDirectSound3DBufferインターフェイス・ポインタの取得

バッチパラメータ操作

最短距離値と最長距離値

操作モード

位置と速度

サウンド・プロジェクション・コーン


IDirectSound3DBufferインターフェイス・ポインタの取得

IDirectSound3DBufferのポインタを取得するには、まずセカンダリ3Dサウンド・バッファを作成する必要がある。作成方法は、 IDirectSound::CreateSoundBufferを使用して、DSBUFFERDESC構造体に付随するdwFlagsメンバの中にDSBCAPS_CTRL3Dを指定する。そして、作成されたバッファ上でIDirectSoundBuffer::QueryInterfaceメソッドを使用して、そのバッファのIDirectSound3DListenerインターフェイスへのポインタを取得する。

// DSBCAPS_CTRL3Dを使用してlpDsbSecondaryを作成する

hr = lpDsbSecondary->QueryInterface(IID_IDirectSound3DBuffer,

        &lpDs3dBuffer);

    if(SUCCEEDED(hr)) {

    // このサウンドの3Dパラメータを設定する

       .

       .

       .

}

DirectSoundは3Dサウンド・バッファとして、モノラル、ステレオ両方の波形をサポートしているが、3Dサウンドの真価を発揮するにはモノラル・サウンドを使用した方がよい。これは3D処理がモノラル・サウンドからステレオ出力を作成するためである。もしステレオ・サウンド・バッファを使用した場合、3D処理が施される前に左右のサンプルの値は平均化される。ふたつのステレオ・チャンネルを別々に配置するには、ステレオ・ストリームをふたつのモノラル・ストリームに分割し、このデータをふたつのモノラル・サウンド・バッファに書きこむ必要がある。

Note

パン制御は3D処理と競合する。そのため、 DSBCAPS_CTRL3DとDSBCAPS_CTRLPANの両方が指定されているとDirectSoundは要求の作成に失敗する。


バッチパラメータ操作

アプリケーションは3Dサウンド・パラメータの取得・設定を、個々に再生することも、バッチを使用して再生することもできる。個々の値を設定するためには、適用可能なIDirectSound3DBufferインターフェイス・メソッドを使用する。しかし、バッファを表現するすべての値を一度に取得・設定する必要があることもある。その場合は、 IDirectSound3DBuffer::GetAllParametersおよび IDirectSound3DBuffer::SetAllParametersメソッドを使用すると、バッチ・パラメータ操作を1回の呼び出しで実行できる。


最短距離値と最長距離値

3Dサウンド・バッファに対して、最短距離値と最長距離値を指定することができる。最短距離とは、音がこれ以上大きくならない距離である。反対に、最長距離とは音がこれ以上小さくならない距離である。これらの値の関係については最短距離と最長距離を参照すること。

最短距離値の設定と取得には IDirectSound3DBuffer::SetMinDistance、および IDirectSound3DBuffer::GetMinDistanceメソッドを使用する。同様に、最長距離値の設定と取得にはIDirectSound3DBuffer::SetMaxDistance、および IDirectSound3DBuffer::GetMaxDistanceメソッドを使用する。


操作モード

サウンド・バッファは、 標準 、 頭相対、 無効の３つの処理モードを持つ。 標準処理モードはデフォルトのモードである。 頭相対モードではサウンドパラメータ(位置、速度、方角)はリスナー・パラメータと相対関係にある。このモードでは、サウンドの絶対パラメータは、リスナー・パラメータが変更されたときに自動的に更新されるので、相対パラメータは変わらないままである。

3Dサウンド・バッファのモード設定にはIDirectSound3DBuffer::SetMode メソッドを使用する。このメソッドは、dwModeフラグをもとに操作モードを設定する。このフラグは1番目のパラメータとして指定する。


位置と速度

3D空間における3Dサウンドの位置を設定・取得するには、IDirectSound3DBuffer::SetPosition 、および IDirectSound3DBuffer::GetPosition メソッドを使用する。

DirectSoundがリスナーに対するドップラー効果の計算に使用する速度値を設定・取得するには、IDirectSound3DBuffer::SetVelocity 、および IDirectSound3DBuffer::GetVelocityメソッドを使用する。バッファの位置は、その速度の影響を受けない。位置と速度の関係についての詳細は、位置と速度を参照すること。


サウンド・プロジェクション・コーン

3Dサウンド・バッファは、内部コーンと外部コーンのふたつのコーンを持つ。さまざまなIDirectSound3DBufferメソッドを使用して、コーンの角度、最長距離と最短距離、バッファのサウンド・プロジェクション・コーンの位置・方角といったことを設定・取得することができる。サウンド・プロジェクション・コーンの動作、特徴ついては、サウンド・コーンを参照すること。

サウンド・コーンを適切に設定すれば、アプリケーションにドラマティックな効果を加えることができる。たとえば幽霊の声が必要な場合、サウンドを淡々と再生するかわりに IDirectSound3DBufferメソッドを使用すれば、次のようにして一層サスペンス効果をあおることができる。音源を部屋の中心に位置付けし、方角をドアに向かって設定する。そして、サウンド・コーンをドアの幅に合わせ、外部コーンのボリュームを-10,000(不可聴音)に設定する。これらの特性が結合されると、ドアから音が発せられるように聞こえるのである。

この節では、以下のサウンド特性をどのように設定するかを説明する。

コーンの角度と方角

内部・外部コーン・ボリューム

コーンの角度と方角

コーンの範囲を定める角度を設定・取得するには IDirectSound3DBuffer::SetConeAngles 、および IDirectSound3DBuffer::GetConeAnglesメソッドを使用する。サウンド・コーンの方角を設定・取得するにはIDirectSound3DBuffer::SetConeOrientation 、および IDirectSound3DBuffer::GetConeOrientationメソッドを使用する。

コーン角度のデフォルト値は360度、つまりすべての方向に対して同じボリュームで音が発せられるようになっている。値を下げると、定義されたコーンの外側ではボリュームが下がる。外部コーン角度はつねに内部コーン角度と同じかそれよりも大きな値である必要がある。

内部・外部コーン・ボリューム

外部コーン・ボリュームとは、リスナーがバッファのサウンド・コーンの外側にいるときの付加的なボリュームの減衰のことである。この要素は100dBで表現される。外部ボリュームのデフォルト値は0である。つまりサウンド・コーンは、このパラメータが変更されない限り特別な効果を示さない。

外部コーン・ボリュームの設定・取得にはIDirectSound3DBuffer::SetConeOutsideVolume 、および IDirectSound3DBuffer::GetConeOutsideVolumeメソッドを使用する。ただし可聴な外部コーン・ボリュームであっても、音源から離れるごとに減衰していく。

リスナーがサウンド・コーンの中にいるときはノーマルなバッファ・ボリュームが使用される(この値はIDirectSoundBuffer::GetVolumeメソッドにより返される)。リスナーがサウンド・コーンの外にいるときはボリュームの外側のコーンも用いられ、このふたつが合わさったボリュームとなる。コーンの境界近くでの音はスムーズに消えていき、自然な効果を得ることができる。


IDirectSound3DListenerインターフェイス

3Dリスナーとは、3D空間内のサウンド・バッファ・オブジェクトによって発生した音を聞く人のことを指す。IDirectSound3DListenerインターフェイスはリスナーの3D空間における位置と現在の速度を制御する。または、リスナーから離れた場合のドップラー効果の量やボリュームの減衰といった、DirectSoundコンポーネントの動作に影響する環境パラメータを制御する。

この節では、IDirectSound3DListenerインターフェイスのポインタを取得する方法と、インターフェイス・メソッドを使用したリスナー・パラメータの管理方法について説明する。 以下のトピックについて説明する。

IDirectSound3DListenerインターフェイス・ポインタの取得

バッチ・パラメータ操作

据え置き設定

距離要素

ドップラー要素

リスナーの位置と速度

リスナーの方向

ロールオフ要素


IDirectSound3DListenerインターフェイス・ポインタの取得

IDirectSound3DListenerインターフェイスへポインタを取得するには、まずプライマリ3Dサウンド・バッファを作成する必要がある。これを作成するには、IDirectSound::CreateSoundBufferメソッドを使用し、 DSBUFFERDESC構造体のdwFlagsメンバ中にDSBCAPS_CTRL3Dフラグを指定する。そして作成されたバッファ上でIDirectSoundBuffer::QueryInterfaceメソッドを使用して、そのバッファのIDirectSound3DListenerインターフェイスへのポインタを取得する。以下の例を参照すること。

// DSBCAPS_CTRL3Dを使用してlpDsbPrimaryを作成する

hr = lpDsbPrimary->QueryInterface(IID_IDirectSound3DListener,

    &lpDs3dListener);

if(SUCCEEDED(hr)) {

    // 3D操作を実行する

    .

    .

    .

}


バッチ・パラメータ操作

アプリケーションでの3Dサウンドパラメータの取得・設定は、個々の実行でも、バッチを使用した実行でも可能である。個々の値を設定するために、適用可能なIDirectSound3DListenerインターフェイス・メソッドを使用することができる。しかし、バッファを表現するすべての値を一度に取得・設定する必要がある場合もある。その際には、 IDirectSound3DListener::GetAllParameters 、および IDirectSound3DListener::SetAllParametersメソッドを使用すると、バッチ・パラメータ操作を1回の呼び出しで実行できる。


据え置き設定

3Dリスナー・パラメータを変更するたびに、3D位置 フィルタ・パラメータの再計算が必要となる。そのため、アプリケーションは、適用可能なメソッドのdwApplyパラメータ内にDS3D_DEFERREDフラグを使用している間はパラメータを変更でき、これにより最高のパフォーマンスを得ることができる。そして設定がすべて完了すれば、IDirectSound3DListener::CommitDeferredSettingsを呼び出すことができる｡

Note

どの据え置き設定も、IDirectSound3DListener::CommitDeferredSettingsを呼び出すまでは、同じ設定をDS3D_IMMEDIATEフラグを使用して呼び出せば、上書きが行われる。据え置きフラグを使用してリスナー速度を(1,2,3)に設定し、それから同じフラグを使用してリスナー速度を(4,5,6)に設定したとすると、リスナー速度は(4,5,6)となる。その後 DirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すと、速度は(4,5,6)となる。


距離要素

DirectSoundはデフォルトの距離測定単位としてメートルを使用している。もしアプリケーションがメートルを使用しない場合、距離要素を設定することができる。距離要素についての情報は、測定単位と距離要素を参照すること。

フィートを使用しているアプリケーションへ距離要素を設定するには、IDirectSound3DListener::SetDistanceFactorを使用してflDistanceFactorパラメータに 0.30480006096を指定する(この値は、1フィートをメートルに換算した値である)。距離要素の設定後は、リスナーに適用可能なメソッドであれば、アプリケーション固有の距離要素を使用して呼び出しできる。

アプリケーションはまた、現在の距離要素設定をIDirectSound3DListener::GetDistanceFactorメソッドを使用して取得することができる。デフォルト値はDS3D_DEFAULTDISTANCEFACTOR (1.0)である。これはひとつの距離単位が1メートルに相当するという意味である。デフォルト値では、位置ベクトル(3.0,7.2,-20.9)というのは物体が元の位置より3m右、7.2m上、20.9m後ろにあるという意味になる。距離要素が2.0に変更されると、同じ位置ベクトルでも物体が6m右、14.4m上、41.8m後ろにあるという意味になる。


ドップラー要素

DirectSoundはひとつまたはそれ以上の3Dサウンド・バッファに対して、リスナーの速度をもとにサウンドにドップラー効果を加えることができる。ドップラー要素を設定することにより、 DirectSoundは、現実世界で体験できるドップラー効果を、サウンドに対する効果を10倍まで強めて生じさせることができる。この要素を設定するにはIDirectSound3DListener::SetDopplerFactorメソッドを使用する。ドップラー要素は0から10の範囲で設定できる。0はドップラー効果がサウンドに加えられていないことを示す。他の値はすべて、現実世界で体験できるドップラー効果の倍数を表す。つまり、1は、現実世界で感じられるドップラー効果が加えられることを表し、2は現実世界で感じられるドップラー効果が2倍加えられることを表す。3Dリスナーに設定されているドップラー要素を取得するにはIDirectSound3DListener::GetDopplerFactorメソッドを使用する。


リスナーの位置と速度

IDirectSound3DListener::SetPosition 、および IDirectSound3DListener::GetPositionメソッドを使用して、3D空間におけるリスナーの位置を設定・取得できる。

リスナーへのドップラー効果を計算するために使用する速度を設定・取得するにはIDirectSound3DListener::SetVelocity 、および IDirectSound3DListener::GetVelocity メソッドを使用する。リスナーの位置はその速度には影響を受けない。位置と速度の関係についての詳細は、位置と速度を参照すること。


リスナーの方向

リスナーの方向は3D効果の処理において強力な役割を果たす。空間内の一定の位置で音が発生したような錯覚を作り出すために、DirectSoundはサウンド・キューを概算する。キューについての詳細は、音像定位の認識を参照すること。

リスナーの方向は、上方ベクトルと前方ベクトルという、原点を共有するふたつのベクトルの関係によって定義される。上方ベクトルはリスナーの頭の中心から始まり、頭の一番上に向かって一直線に通過する。前方ベクトルもまたリスナーの頭の中心から始まるが、上方ベクトルから見ると右へ向かい、リスナーの顔の前面を通過する。次の図はこれらのベクトルの関係を示している。

リスナーの方向を設定・取得するにはIDirectSound3DListener::SetOrientation 、および IDirectSound3DListener::GetOrientationメソッドを使用する。デフォルト値は、前方ベクトルが (0,0,1.0)、上方ベクトルが(0,1.0,0)になっている。


ロールオフ要素

ロールオフは、リスナーとサウンドの距離によって生じる音の減衰の度合である。DirectSoundは、ロールオフを現実世界で体験できる10倍までの範囲で生じさせることができる。この要素を設定するにはIDirectSound3DListener::SetRolloffFactorメソッドを使用する。ロールオフ要素は0から10の範囲で設定できる。0はロールオフがサウンドに加えられていないことを示す。その他の数値は現実世界で体験できるロールオフの倍数を表す。つまり、1は、現実世界で感じられるロールオフが加えらることを表し、2は現実世界で感じられるロールオフが2倍加えられることを表す。ロールオフ要素を取得するにはIDirectSound3DListener::GetRolloffFactorメソッドを使用する。


IDirectSoundBufferインターフェイス

IDirectSoundBufferインターフェイスにより、アプリケーションはオーディオ・データのバッファを操作できるようになる。オーディオ・データはDirectSoundバッファに常駐する。再生されるサウンドやオーディオ・ストリームのひとつひとつに対してアプリケーションはDirectSoundバッファを作成する。

プライマリ・サウンド・バッファは、サウンド・デバイスへ現在送られているサンプリング・オーディオを表す。これらのサンプルは単一のストリームでも、複数のオーディオ・ストリームをミキシングして出力したものでもよい。通常はプライマリ・サウンド・バッファ内のオーディオ・データには直接アクセスは行わない。ただし、出力ボリューム、波形の設定など、制御の目的でプライマリ・バッファを使用することはできる。

セカンダリ・サウンド・バッファは単一のストリーム出力およびサウンド出力を表す。このバッファはプライマリ・サウンド・バッファで再生することができる。同時に再生されたセカンダリ・バッファはプライマリ・バッファでミキシングされ、それからサウンド・デバイスへ送られる。

Note

 DirectSoundBufferオブジェクトはそれらを作成したDirectSoundオブジェクトの所有となる。DirectSoundオブジェクトが解放されると、そのオブジェクトが作成したバッファもすべて解放され、参照されることはない。

この節では、サウンド・バッファの録音・再生の管理方法、ボリュームのトラッキングと制御、周波数、パン設定、サウンド・バッファ情報の取得、メモリ管理について説明する。

再生管理

サウンド環境管理

情報の取得

メモリ管理


再生管理

 サウンドのリアルタイムな録音・再生を制御するためには、IDirectSoundBuffer::Playと IDirectSoundBuffer::Stopメソッドを使用する。サウンドの再生にはIDirectSoundBuffer::Playを使用。最後までくるとバッファは自動的に停止する。ただし、ループを指定すると、 IDirectSoundBuffer::Stopを呼び出すまでバッファはくり返し再生される。

 IDirectSoundBuffer::Lockメソッドは現在のサウンド・バッファの書きこみポインタを取得する。バッファへオーディオ・データを書きこんだ後は、 IDirectSoundBuffer::Unlockメソッドを使用してバッファのロックを解除する必要がある。長期間にわたってバッファをロックしておくべきではない。

サウンド・バッファのカレント位置を取得するには、 IDirectSoundBuffer::GetCurrentPosition、もしくは IDirectSoundBuffer::SetCurrentPositionを使用する。


サウンド環境管理

IDirectSoundBuffer::GetVolume、および IDirectSoundBuffer::SetVolumeメソッドを使用すると、再生中のバッファのボリュームの取得・設定が行える。プライマリ・サウンド・バッファのボリュームを設定することで、サウンド・カードのウェーブフォーム・オーディオ・ボリュームが変更される。

同様に、 IDirectSoundBuffer::GetFrequency 、および IDirectSoundBuffer::SetFrequency メソッドを使用して、サンプリング・オーディオが再生される周波数を取得・設定することができる。プライマリ・バッファの周波数を変更することはできない。

パンの取得・設定には、 IDirectSoundBuffer::GetPan 、および IDirectSoundBuffer::SetPanメソッドを呼び出す。プライマリ・バッファのパンを変更することはできない。


情報の取得

IDirectSoundBuffer::GetCaps は、DirectSoundBufferオブジェクトの性能を取得する。 IDirectSoundBuffer::GetStatusメソッドを使用して、カレントのサウンド・バッファが再生中か停止中かを限定することができる。

IDirectSoundBuffer::GetFormatメソッドを使用して、バッファ内のサウンド・データの形式を取得することができる。また、 IDirectSoundBuffer::GetFormat および IDirectSoundBuffer::SetFormatメソッドを使用して、プライマリ・サウンド・バッファ内のサウンド・データの形式を設定することもできる

Note

セカンダリ・サウンド・バッファが作成されると、その形式は固定される。もし別形式のセカンダリ・バッファが必要なら、そのフォーマットで新規にバッファを作成する必要がある。


メモリ管理

IDirectSoundBuffer::Restoreメソッドを使用して、指定されたDirectSoundBufferオブジェクトのサウンド・バッファメモリをリストアすることができる。これはバッファが失われた場合に有用だが、 IDirectSoundBuffer::Restoreがリストアするのはそのメモリ自体のみである。メモリのコントロールはリストアしない。バッファ・メモリがリストアされた後は、そこへ有効なサウンドデータを書きこむ必要がある。


DirectSoundの使用例

DirectSoundを再生するには以下の手順に従う必要がある。

1	DirectSoundCreate関数を呼び出してDirectSoundオブジェクトを作成する。

2	IDirectSound::SetCooperativeLevelメソッドを呼び出して協調レベルを指定する。ほとんどのアプリケーションでは最下位レベルであるDSSCL_NORMALを使用する。

3	IDirectSound::CreateSoundBufferメソッドを使用してセカンダリ・サウンド・バッファを作成する。DSBUFFERDESC構造体の中では、そのバッファがセカンダリ・バッファであることを指定する必要はない。デフォルトでセカンダリ・バッファが作成されるようになっている。

4	セカンダリ・バッファにデータを読み込む。データ領域にポインタを取得するにはIDirectSoundBuffer::Lock メソッドを使用し、そのデバイスにデータをセットするにはIDirectSoundBuffer::Unlockメソッドを使用する。

5	IDirectSoundBuffer::Playメソッドを使用してセカンダリ・バッファを再生する。

6	アプリケーションがサウンドの再生を終了したら、DirectSoundBufferバッファのIDirectSoundBuffer::Stopメソッドを使用してすべてのバッファを停止させる。

7	セカンダリ・バッファを解放する。

8	DirectSoundオブジェクトを解放する。

また、以下のオプションを実行することもできる。

プライマリ・バッファを作成してIDirectSoundBuffer::SetFormatメソッドを呼び出し、プライマリ・サウンド・バッファの出力形式を設定する。この設定の前に、アプリケーションの協調レベルがDSSCL_PRIORITYに設定されている必要がある。

プライマリ・サウンド・バッファを作成し、 IDirectSoundBuffer::Playメソッドを使用してそのバッファを再生する。これは、たとえセカンダリ・バッファが再生されていなくても、プライマリ・バッファがつねに再生されていることを保証する。この動作はCPUパワーをいくらか消費するが、セカンダリ・バッファが再生されるときの開始時間を短縮する。

この節には、DirectSoundコンポーネントに関連した以下の一般的なタスクを実行するコードのサンプルが収められている。コードの解説は各々のサンプルで行う。

DirectSoundオブジェクトの作成

CoCreateInstanceを使用したDirectSoundオブジェクトの作成

ハードウェア性能の照会

サウンド・バッファの作成

サウンド・バッファへの書きこみ

DirectSoundミキサーの使用

カスタム・ミキサーの使用

圧縮waveの使用


DirectSoundオブジェクトの作成

DirectSoundオブジェクトを作成する最も簡単な方法は、 DirectSoundCreate関数を呼び出してNULL GUIDを指定する方法である。この関数はデフォルト・ウィンドウのウェーブ・デバイスと同等のオブジェクトを作成しようとする。そのあとIDirectSound::SetCooperativeLevelメソッドを呼び出す必要がある。このメソッドの呼び出しが行われるまではサウンド・バッファは作成されない。次の例で、このプロセスを示す。

LPDIRECTSOUND lpDirectSound;

if(DS_OK == DirectSoundCreate(NULL, &lpDirectSound,

    NULL)) {

    // 作成に成功した場合

    lpDirectSound->lpVtbl->SetCooperativeLevel(lpDirectSound,

        hwnd, DSSCL_NORMAL);

    // .

    // . DirectSoundへアクセスするためのコードをここに配置する

    // .

} else {

    // 作成に失敗した場合

    // .

    // .

    // .

}

DirectSoundEnumerate関数を使用すると、特定のサウンドデバイスの作成を指定することができる。この関数を使用するには、DSEnumCallback関数と、ほとんどの場合インスタンス・データ構造体も作成する。次に例を示す。

typedef struct {

    // GUIDsへ記憶する

    // デバイスのディスプリクション文字列へ記憶する

} APPINSTANCEDATA, *LPAPPINSTANCEDATA;

BOOL AppEnumCallbackFunction(

    LPGUID lpGuid,

    LPTSTR lpstrDescription,

    LPTSTR lpstrModule,

    LPVOID lpContext)

{

    LPAPPINSTANCEDATA lpInstance = (LPAPPINSTANCEDATA)

    lpContext;

    // lpInstance構造体へGUIDをコピーする

    // Strcpy記述文字列をlpInstance構造体へ

    return TRUE; // 列挙を続ける

}

さらに、次の例を使用してDirectSoundオブジェクトを作成することもできる。

AppInitDirectSound()

{

    APPINSTANCEDATA AppInstanceData;

    LPGUID lpGuid;

    LPDIRECTSOUND lpDirectSound;

    HRESULT hr;

    DirectSoundEnumerate(AppEnumCallbackFunction,

    &AppInstanceData);

    lpGuid = AppLetUserSelectDevice(&AppInstanceData);

    // DirectSoundCreateがエラーのときは

    // 返値をチェックする必要がある

    hr = DirectSoundCreate(lpGuid, &lpDirectSound, NULL);

    // .

    // .

    // .

}

サウンド・デバイスがなかったり、 lpGuidパラメータで指定されたサウンド・デバイスにウェーブフォーム・オーディオ関数が割り振られていると、 DirectSoundCreate関数は失敗する。サウンドなしで続けるにせよ、ユーザにそのサウンド・デバイスを使用しているアプリケーションの終了を促すにせよ、この呼び出しが失敗した場合に備える必要がある。


CoCreateInstanceを使用したDirectSoundオブジェクトの作成

CoCreateInstanceを使用してDirectSoundオブジェクトを作成するには以下の手順を行う。

1	関数にNULLを指定して、COMを初期化する。

if (FAILED(CoInitialize(NULL)))

    return FALSE;

2	DirectSoundCreate 関数を使用するより、CoCreateInstanceおよび IDirectSound::Initializeメソッドを使用してDirectSoundオブジェクトを作成する。

dsrval = CoCreateInstance(&CLSID_DirectSound,

        NULL, &IID_IDirectSound, &lpds);

    if(!FAILED(dsrval))

        dsrval = IDirectSound_Initialize(lpds, NULL);

CLSID_DirectSoundはDirectSoundドライバ・オブジェクト・クラスのクラス識別子で、 IID_IDirectSoundはDirectSoundインターフェイスである。 lpdsパラメータはCoCreateInstanceが返す未初期化オブジェクトである。

DirectSoundオブジェクトを使用する前にIDirectSound::Initializeを呼び出さなくてはならない。このメソッドは、 DirectSoundCreateが通常使用するドライバのGUIDパラメータ(この場合はNULL)を採用する。DirectSoundが初期化されると、 DirectSoundCreateで作成されたときと同じようにDirectSoundオブジェクトを使用したり解放したりすることができるようになる。

アプリケーションを終了する前には、以下のようにCoUninitializeを使用してCOMのシャットダウンを行う。

CoUninitialize();


ハードウェア性能の照会

DirectSoundでは、アプリケーションでオブジェクトが使用するサウンド・デバイスのハードウェア性能を取得することができる。DirectSoundは自動的にハードウェア・アクセラレーションを行うので、ほとんどのアプリケーションではこれを必要としない。しかしハイパフォーマンスなアプリケーションでは、そのサウンド要求に応えるハードウェアの機能を知るためにこの情報を使用することができる。たとえば、ハードウェア・ミキシングが有効なら、再生できるサウンドがより多くなる。

ハードウェア性能を取得するためにはIDirectSound::GetCapsメソッドを使用する。このメソッドは、次の例のようにDSCAPS構造体内に埋め込まれている。

AppDetermineHardwareCaps(LPDIRECTSOUND lpDirectSound)

{

    DSCAPS dscaps;

    HRESULT hr;

    dscaps.dwSize = sizeof(DSCAPS);

    hr = lpDirectSound->lpVtbl->GetCaps(lpDirectSound,

    &dscaps);

    if(DS_OK == hr) {

        // 成功したらDSCAPS構造体を分解する

        // .

        // .

        // .

    }

    // .

    // .

    // .

}

DSCAPS構造体には、それぞれのタイプの最大リソースや現在有効なリソース情報など、サウンド・デバイスのパフォーマンスとリソースに関する情報が含まれている。これらはさまざまなリソース間で矛盾を生じさせる場合がある。たとえば、単一のハードウェア・ストリーム・サウンド・バッファの割り当ては、ふたつのスタティック・ミキシング・チャンネルを消費する。ハードウェア性能を測定する場合、バッファの割り当てと割り当ての間にIDirectSound::GetCapsを呼び出して、バッファ作成に十分なリソースがあるかをチェックする必要がある。

サウンドデバイスの動作について勝手に仮定することは避けるべきである。さもないと作成したアプリケーションが、あるサウンド・デバイスでは動くのに別のデバイスでは動かないといったことになる。その上、将来提供されるデバイスが、現存するデバイスとは異なる動作をすることも考えられる。

ハードウェアのリソース割り当てを行うと、アプリケーションは代わりにそれらをソフトウェア・バッファへ割り当てようとする。つねにすべてのハードウェア・リソースに対して完全なアクセスを行えるわけではない。たとえばIDirectSound::GetCapsメソッドは空きリソースを表示するが、Windowsはマルチタスクなオペレーティング・システムであるため、 リソース割り当てをしようとしても別のアプリケーションに割り当てられる可能性がある。


サウンド・バッファの作成

この節では簡単なサウンド・バッファの作成方法を説明する。また、作成したそれぞれのサウンド・バッファに設定可能な制御オプションについても説明する。さらに、スタティック・サウンド・バッファとストリーム・サウンド・バッファ、ハードウェア・サウンド・バッファとソフトウェア・サウンド・バッファ、プライマリ・サウンド・バッファとセカンダリ・サウンド・バッファのオーディオデータの記憶域の違いについても触れている。

基本的なサウンド・バッファの作成

制御オプション

スタティック・サウンド・バッファとストリーム・サウンド・バッファ

ハードウェア・サウンド・バッファとソフトウェア・サウンド・バッファ

プライマリ・サウンド・バッファとセカンダリ・サウンド・バッファ


基本的なサウンド・バッファの作成

サウンド・バッファを作成するには、 DSBUFFERDESC構造体を引数に、 IDirectSound::CreateSoundBuffer メソッドを呼び出す。これはDirectSoundBufferオブジェクトを作成し、 IDirectSoundBuffer インターフェイスへポインタを返す。このインターフェイスは、バッファの書きこみ・処理および再生に使用できる。

まず始めに、最も重要なサウンドのバッファを作成してから、その他のバッファを重要度の高い順に作成する。DirectSoundはハードウェアのリソースを、利用可能な一番最初のバッファへ割り当てる。

次の例では、セカンダリ・サウンド・バッファの作成方法を示している。

BOOL AppCreateBasicBuffer(

    LPDIRECTSOUND lpDirectSound,

    LPDIRECTSOUNDBUFFER *lplpDsb)

{

    PCMWAVEFORMAT pcmwf;

    DSBUFFERDESC dsbdesc;

    HRESULT hr;

    // waveフォーマット構造体を設定する

    memset(&pcmwf, 0, sizeof(PCMWAVEFORMAT));

    pcmwf.wf.wFormatTag = WAVE_FORMAT_PCM;

    pcmwf.wf.nChannels = 2;

    pcmwf.wf.nSamplesPerSec = 22050;

    pcmwf.wf.nBlockAlign = 4;

    pcmwf.wf.nAvgBytesPerSec =

        pcmwf.wf.nSamplesPerSec * pcmwf.wf.nBlockAlign;

    pcmwf.wBitsPerSample = 16;

    // DSBUFFERDESC構造体を設定する

    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC)); // 0に設定。

    dsbdesc.dwSize = sizeof(DSBUFFERDESC);

    // デフォルトのコントロールを要求する(パン、ボリューム、周波数)。

    dsbdesc.dwFlags = DSBCAPS_CTRLDEFAULT;

    // 3秒のバッファ

    dsbdesc.dwBufferBytes = 3 * pcmwf.wf.nAvgBytesPerSec;

    dsbdesc.lpwfxFormat = (LPWAVEFORMATEX)&pcmwf;

    // バッファを作成する

    hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound,

        &dsbdesc, lplpDsb, NULL);

    if(DS_OK == hr) {

        // 成功。有効なインターフェイスは*lplpDsb

        return TRUE;

    } else {

        // 失敗。

        *lplpDsb = NULL;

        return FALSE;

    }

}


制御オプション

サウンド・バッファを作成するときは、バッファに求められる制御オプションを指定する必要がある。これにはDSBUFFERDESC構造体のdwFlagsメンバを使用する。サウンド・バッファにハードウェア・リソースが割り当てられていると、DirectSoundはアプリケーションが指定したオプションを使用する。たとえば、デバイスがハードウェア・バッファをサポートしていても、そのバッファに対するパン制御は提供していない場合がある。この場合DirectSoundは、DSBCAPS_CTRLPANフラグが指定されている場合を除いて、ハードウェア・アクセラレーションを使用する。

すべてのサウンド・カードから最高の能力を引き出すには、アプリケーションが自分で使用するオプションのみを指定する。

バッファが持っていないメソッドを呼び出しても失敗に終わる。たとえば、 IDirectSoundBuffer::SetVolumeメソッドを使用してボリュームを変更しようとした場合、そのバッファの作成時に DSBCAPS_CTRLVOLUMEフラグが指定されていればメソッドは成功する。フラグが指定されていなければメソッドは失敗に終わり、 DSERR_CONTROLUNAVAILエラーコードが返される。バッファの制御により、現存も含んで将来提供されるデバイス上でのアプリケーションの動作保証がより確実になる。


スタティック・サウンド・バッファとストリーム・サウンド・バッファ

スタティック・サウンド・バッファは、メモリ内にサウンド全体を格納する。このバッファは、サウンド全体をバッファへ1回だけ書きこめばよいので手軽である。ストリーム・サウンド・バッファはサウンドの一部を指す。たとえば、2分間再生されるサウンドのうちの3秒間のオーディオデータだけを保持できるバッファである。この場合、アプリケーションは定期的に新しいデータをサウンド・バッファへ書きこまなければならない。しかし、ストリーム・バッファはスタティック・バッファよりもメモリの消費が少なくてすむ。

サウンド・バッファを作成するとき、 DSBCAPS_STATICフラグを指定すると、バッファがスタティックであることを示すことができる。このフラグを指定しなければ、バッファはストリーム・バッファとなる。

もしサウンド・デバイスがオンボードのサウンドメモリの場合、DirectSoundはスタティック・バッファをハードウェア上のメモリに配置しようとする。このバッファはハードウェア・ミキシングを利用することができ、システムはこれらのサウンド・ミキシング時のオーバーヘッドを最小限に押さえることができる。サウンド・データがハードウェア・メモリに一度ロードされるだけで済むため、これは特に足音や武器などのくり返し再生されるサウンドに有効である。

ストリーム・バッファは、PCIやその他の高速バス上でハードウェア・ミキシングを利用できる場合でも、より効率的な書きこみができるようにメイン・システム・メモリに配置される。ストリーム・バッファを使用するための必要条件は特にない。たとえば、バッファに十分な大きさがあれば、サウンド全体をストリーム・バッファへ書きこむことができる。実際のところ、1回しか使用しないつもりのサウンドなら、ストリーム・バッファを使用した方が、ハードウェア・メモリにロードする必要がないため効率的である。

Note

バッファをスタティックにするかストリームにするかを指定するのはパフォーマンスの最適化のためである。バッファをどのように使用するかを制限するものではない。


ハードウェア・サウンド・バッファとソフトウェア・サウンド・バッファ

ハードウェア・サウンド・バッファはサウンド・デバイス上のハードウェア・ミキサーによってミキシングが実行される。ソフトウェア・サウンド・バッファはCPUによってミキシングが実行される。ほとんどの場合、アプリケーションに必要なことはバッファをスタティックにするかストリームにするか指定するだけである。DirectSoundがハードウェアかソフトウェア、どちらか適切な方へバッファを配置する。

しかし、バッファをハードウェアとソフトウェアのどちらへ配置するかを明確に指定しなければならない場合には、 DSBUFFERDESC構造体の中でDSBCAPS_LOCHARDWARE、もしくは DSBCAPS_LOCSOFTWAREフラグを指定すればよい。DSBCAPS_LOCHARDWAREフラグが指定されていて、ハードウェア・メモリやミキシング能力が不十分なときは、バッファの作成要求は失敗する。また、現在のサウンド・デバイスはほとんどがハードウェア・メモリやミキシング能力を持たないので、そのようなデバイス上ではハードウェア・バッファを作成できない。

バッファの位置の限定にはIDirectSoundBuffer::GetCapsメソッドを使用して、DSBCAPS構造体のdwFlagsメンバでDSBCAPS_LOCHARDWAREもしくは DSBCAPS_LOCSOFTWAREフラグを確認すればよい。つねにどちらかに指定されている。


プライマリ・サウンド・バッファとセカンダリ・サウンド・バッファ

プライマリ・サウンド・バッファは、実際にリスナーが聞き取るサンプリング・オーディオである。セカンダリ・サウンド・バッファはそれぞれ単一のサウンドおよびオーディオ・ストリームである。プライマリ・バッファを作成するには、 DSBUFFERDESC構造体の中でDSBCAPS_PRIMARYBUFFERフラグを指定すればよい。セカンダリ・バッファが作成されるのは、このフラグが指定されない時である。

通常はひとつのアプリケーションにおけるすべてのサウンドに対してセカンダリ・バッファを作成する。古いデータに新しいデータを上書きすることでサウンド・バッファの再利用が可能である。DirectSoundが行う処理は、ハードウェアのリソース割り当てや、再生中のすべてのバッファのミキシングである。

アプリケーションがセカンダリ・バッファを使用しているならば、特定の制御を行うためにプライマリ・バッファを作成することもできる。たとえば、プライマリ・バッファ上でIDirectSoundBuffer::SetFormatメソッドを呼び出すと、ハードウェアの出力形式を制御することができる。ただし IDirectSoundBuffer::LockやIDirectSoundBuffer::GetCurrentPositionなどの、バッファ・メモリへアクセスを行うメソッドはすべて失敗する。

アプリケーションがミキシングを実行する際、DirectSoundはプライマリ・バッファへの書きこみアクセスを提供する。このバッファへの書き込みは、すばやく行われる必要がある。もしデータが更新されないと、バッファは前回のデータを繰り返し、音声にずれが生じる。プライマリ・バッファへの書きこみアクセスは、アプリケーションがDSSCL_WRITEPRIMARY協調レベルを設定している場合のみ有効である。この協調レベルではセカンダリ・バッファはまったく再生されない。

プライマリ・サウンド・バッファはループで再生されることに注意する。必ずDSBPLAY_LOOPINGフラグをセットすること。

プライマリ・バッファへの書きこみアクセスを取得する方法を次の例で示している。

BOOL AppCreateWritePrimaryBuffer(

    LPDIRECTSOUND lpDirectSound, LPDIRECTSOUNDBUFFER *lplpDsb,

    LPDWORD lpdwBufferSize, HWND hwnd)

{

    DSBUFFERDESC dsbdesc;

    DSBCAPS dsbcaps;

    HRESULT hr;

    // wave formatの構造体を設定する

    memset(&pcmwf, 0, sizeof(PCMWAVEFORMAT));

    pcmwf.wf.wFormatTag = WAVE_FORMAT_PCM;

    pcmwf.wf.nChannels = 2;

    pcmwf.wf.nSamplesPerSec = 22050;

    pcmwf.wf.nBlockAlign = 4;

    pcmwf.wf.nAvgBytesPerSec =

        pcmwf.wf.nSamplesPerSec * pcmwf.wf.nBlockAlign;

    pcmwf.wBitsPerSample = 16;

    // DSBUFFERDESC構造体を設定する

    memset(&lplpDsb, 0, sizeof(DSBUFFERDESC)); // 0に設定

    dsbdesc.dwSize = sizeof(DSBUFFERDESC);

    dsbdesc.dwFlags = DSBCAPS_PRIMARYBUFFER;

    // バッファサイズはサウンド機器により制限される

    dsbdesc.dwBufferBytes = 0;

    dsbdesc.lpwfxFormat = NULL; // プライマリ・バッファはNULLでなくてはならない

    // 書き込み優先協調レベルを取得

    hr = lpDirectSound->lpVtbl->SetCooperativeLevel(lpDirectSound,

        hwnd, DSSCL_WRITEPRIMARY);

    if(DS_OK == hr) {

        // 成功。バッファの作成を試みる

        hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound,

            &dsbdesc, lplpDsb, NULL);

        if(DS_OK == hr) {

            // 成功。プライマリ・バッファを要求された形式に設定

            hr = (*lplpDsb)->lpVtbl->SetFormat(*lplpDsb, &pcmwf);

            if(DS_OK == hr) {

                // バッファサイズを知りたいときはGetCapsを呼び出す

                    dsbcaps.dwSize = sizeof(DSBCAPS);

                (*lplpDsb)->lpVtbl->GetCaps(*lplpDsb, &dsbcaps);

                *lpdwBufferSize = dsbcaps.dwBufferBytes;

                return TRUE;

            }

        }

    }

    // SetCooperativeLevelに失敗

    // CreateSoundBuffer、もしくはSetFormat

    *lplpDsb = NULL;

    *lpdwBufferSize = 0;

    return FALSE;

}


サウンド・バッファへの書きこみ

サウンド・バッファへの書きこみアクセスを取得するにはIDirectSoundBuffer::Lockメソッドを使用する。バッファへのデータ書きこみ、コピーは、サウンド・バッファ(メモリ)がロックされた後に可能になる。バッファ・メモリのロックはその後IDirectSoundBuffer::Unlockメソッドで解除すること。

通常、ストリーム・サウンド・バッファは連続して再生されるので、サウンド・バッファをロックするためにDirectSoundはふたつのライト・ポインタを返す。たとえば、400バイトのバッファの途中で300バイトをロックした場合、 IDirectSoundBuffer::Lockは最初のバッファを残りの300バイトのポイントとして返し、最初の100バイトを次のバッファとして返す。バッファのオフセットと長さによっては、ふたつめのポインタはNULLになる場合もある。

サウンド・バッファのメモリは失われることもある。これは特にバッファがハードウェア・サウンド・メモリに配置されている場合に起こりやすい。最も多いのは使用中にサウンド・カード自体が抜き取られてしまう場合である。これはPCMCIAのサウンド・カードでよく起こる。また、書き込み優先協調レベルのアプリケーションが入力フォーカスを得た場合にも起こりやすい。このフラグが設定されていると、フォーカスを持つアプリケーションがプライマリ・バッファへ直接書きこみを行えるため、DirectSoundは他のすべてのサウンド・バッファを消去してしまう。これが起きた場合、DirectSoundは IDirectSoundBuffer::Lockおよび IDirectSoundBuffer::Playメソッドに対してDSERR_BUFFERLOSTエラーコードを返す。そのアプリケーションが書き込み優先協調レベルから他のレベルに下がったり、入力フォーカスを失ったりすると、他のアプリケーションはIDirectSoundBuffer::Restoreメソッドを呼び出してバッファ・メモリの再割り当てを実行できる。成功すると、このメソッドはバッファ・メモリや、その他のボリュームやパン設定などのバッファの設定すべてをリストアする。しかし、リストアされたバッファのサウンド・データは破壊されている。親アプリケーションはリストアされたバッファへデータを再書きこみする必要がある。

次の例ではIDirectSoundBuffer::Lockおよび IDirectSoundBuffer::Unlock メソッドを使用してサウンド・バッファへデータを書きこんでいる。

BOOL AppWriteDataToBuffer(

    LPDIRECTSOUNDBUFFER lpDsb, DWORD dwOffset, LPBYTE lpbSoundData,

    DWORD dwSoundBytes)

{

    LPVOID lpvPtr1;

    DWORD dwBytes1;

    LPVOID lpvPtr2;

    DWORD dwBytes2;

    HRESULT hr;

    // ライトポインタの取得

    hr = lpDsb->lpVtbl->Lock(lpDsb, dwOffset, dwSoundBytes, &lpvPtr1,

        &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    // BUFFERLOSTが返された場合、リストアと再ロックを行う

    if(DSERR_BUFFERLOST == hr) {

        lpDsb->lpVtbl->Restore(lpDsb);

        hr = lpDsb->lpVtbl->Lock(lpDsb, dwOffset, dwSoundBytes,

            &lpvPtr1, &dwAudio1, &lpvPtr2, &dwAudio2, 0);

    }

    if(DS_OK == hr) {

        // ポインタへ書きこみを行う

        CopyMemory(lpvPtr1, lpbSoundData, dwBytes1);

        if(NULL != lpvPtr2) {

            CopyMemory(lpvPtr2, lpbSoundData+dwBytes1, dwBytes2);

        }

        // DirectSoundへデータを返す

        hr = lpDsb->lpVtbl->Unlock(lpDsb, lpvPtr1, dwBytes1, lpvPtr2,

            dwBytes2);

        if(DS_OK == hr) {

            // 成功。

            return TRUE;

        }

    }

    // ロック、ロック解除、もしくは要求の失敗

    return FALSE;

}


DirectSoundミキサーの使用

DirectSoundで複数のストリームをミキシングするのは簡単である。単にセカンダリ・サウンド・バッファを作成し、それぞれのバッファにIDirectSoundBufferインターフェイスを受け取らせるだけでよい。これらのインターフェイスを使用して、 IDirectSoundBuffer::Lock および IDirectSoundBuffer::Unlockメソッドでバッファにデータを書きこみ、 IDirectSoundBuffer::Playでバッファを再生することができる。また、 IDirectSoundBuffer::Stopメソッドを使用して、再生中のバッファをいつでも停止することができる。

IDirectSoundBuffer::Playメソッドはつねにバッファのカレント・ポジションから再生を始める。カレント・ポジションは、バッファ内のオフセットでバイト単位で指定される。新規作成されたバッファのカレント・ポジションは0である。バッファが停止すると、カレント・ポジションは即時に次に再生されるサンプルへ移動する。 IDirectSoundBuffer::SetCurrentPosition メソッドを呼び出せばカレント・ポジションを明確に設定することができ、 IDirectSoundBuffer::GetCurrentPositionメソッドを呼び出せばカレント・ポジションを取得できる。

デフォルトではIDirectSoundBuffer::Playはバッファの終わりに到達したときに再生を終了する。これはループなしのスタティック・バッファの適切な動作である(カレント・ポジションはこの時点でバッファの開始位置までリセットされる)。 ストリーム・バッファおよびスタティック・バッファを連続的に再生する場合は、 IDirectSoundBuffer::Playを呼び出して、 dwFlagsパラメータ内にDSBPLAY_LOOPINGフラグを指定する。これにより、バッファが終わりまで到達するとまた開始位置まで戻るようになる。

ストリーム・サウンド・バッファでは、再生カーソルが開始位置まで巻き戻る前に、次のブロックのデータが書きこまれている必要がある。このためにはWin32関数のSetTimerもしくは SetEventを使用して、定期的にメッセージやコールバック関数が実行されるようにすればよい。さらに、多くのDirectSoundアプリケーションは、リアルタイムDirectDrawコンポーネントを持っており、ディスプレイに対して定期的にサービスを行うものである。このコンポーネントはDirectSoundバッファにも同様にサービスを供給することができる。効率の向上を考え、再生中のオーディオ出力のずれを最小限におさえるためには、アプリケーションはカレントの再生カーソルより少なくとも1秒は先に書きこみを行う必要がある。

もしスタティック・バッファに対してDSBCAPS_STATICフラグを指定していれば、DirectSoundミキサーはハードウェア・アクセラレーションの効用を最大限に受けることができる。このフラグは再利用されるスタティック・バッファでは必ず指定したほうがよい。DirectSoundはこれらのバッファを有効なハードウェア・メモリにロードするので、ミキシング時のオーバーヘッドはない。最も重要なスタティック・サウンド・バッファは、ハードウェア・アクセラレーションを優先的に受けられるように一番最初に作成するほうがよい。

アプリケーション内のサウンドがすべて同じwaveを使用し、ハードウェアへの出力形式がそれらのサウンドと合っていれば、 DirectSoundミキサーは最高級品質のサウンドを作り出す。この条件下では、ミキサーは形式変換をする必要がないためである。

ハードウェアへの出力形式を変更するには、プライマリ・サウンド・バッファを作成してIDirectSoundBuffer::SetFormatメソッドを呼び出す。ただし、このプライマリ・バッファは制御の目的でしか使用できず、 この関数を呼び出せるアプリケーションは、DSSCL_PRIORITYもしくはそれ以上の協調レベルに設定されているもののみである。そしてDirectSoundは、アプリケーションが入力フォーカスを得るたびに、ハードウェアの形式を前回のIDirectSoundBuffer::SetFormatメソッドの呼び出しで設定した形式に返す。


カスタム・ミキサーの使用

ほとんどのアプリケーションではDirectSoundミキサーを使用するが、これは、ほぼすべてのミキシングの要求を満たし、また、自動的にハードウェア・アクセラレーションを利用する。しかし、DirectSoundが提供しない機能をアプリケーションが必要とする場合、プライマリ・サウンド・バッファ への書きこみアクセスを獲得し、そこで直接ストリームをミキシングすることができる。この機能はコンポーネントごとに提供され、ごく限られたハイパフォーマンスのアプリケーションでのみ有効である。この機能を利用したアプリケーションはオーディオのずれを回避するのが難しくなるので、パフォーマンス要求が厳しくなる。

カスタム・ミキサーを作成するには、まずDSSCL_WRITEPRIMARY協調レベルを取得し、プライマリ・サウンド・バッファを作成する。次にIDirectSoundBuffer::Lockメソッドを呼び出し、返されたポインタへデータを書きこみ、そしてIDirectSoundBuffer::Unlockメソッドを呼び出してDirectSoundへデータを返す。アプリケーションはIDirectSoundBuffer::Playメソッドの呼び出しでプライマリ・バッファを再生し、データをスピーカに出力しなくてはならない。DSBPLAY_LOOPINGフラグか指定されていないと IDirectSoundBuffer::Playの呼び出しに失敗するので注意すること。

カスタム・ミキサーの作成方法を次に示している。例の中にあるAppMixIntoPrimaryBuffer関数は、サウンド・デバイスがデータ・ブロックの再生を繰り返さないよう一定の間隔で呼び出しされる必要がある。CustomMixer関数はアプリケーションが定義した関数で、 アプリケーションが定義したCustomMixerの中で指定されたときに複数のストリームをミキシングし、結果を指定されたポインタへ書きこむ。

BOOL AppMixIntoPrimaryBuffer(

    LPAPPSTREAMINFO lpAppStreamInfo, LPDIRECTSOUNDBUFFER lpDsbPrimary,

    DWORD dwDataBytes, DWORD dwOldPos, LPDWORD lpdwNewPos)

{

    LPVOID lpvPtr1;

    DWORD dwBytes1;

    LPVOID lpvPtr2;

    DWORD dwBytes2;

    HRESULT hr;

    // 書きこみポインタを取得

    hr = lpDsbPrimary->lpVtbl->Lock(lpDsbPrimary, dwOldPos, dwDataBytes,

        &lpvPtr1, &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    // DSERR_BUFFERLOSTが返ってきた場合に、リストアして、ロックをかける

    if(DSERR_BUFFERLOST == hr) {

        lpDsbPrimary->lpVtbl->Restore(lpDsbPrimary);

        hr = lpDsbPrimary->lpVtbl->Lock(lpDsbPrimary, dwOldPos,

            dwDataBytes, &lpvPtr1, &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    }

    if(DS_OK == hr) {

        // 返されたポインタへデータをミキシングする

        CustomMixer(lpAppStreamInfo, lpvPtr1, dwBytes1);

        *lpdwNewPos = dwOldPos + dwBytes1;

        if(NULL != lpvPtr2) {

            CustomMixer(lpAppStreamInfo, lpvPtr2, dwBytes2);

            *lpdwNewPos = dwBytes2; // 巻き戻ったため

        }

        // DirectSoundへデータを返す

        hr = lpDsbPrimary->lpVtbl->Unlock(lpDsbPrimary, lpvPtr1,

            dwBytes1, lpvPtr2, dwBytes2);

        if(DS_OK == hr) {

            // 成功

            return TRUE;

        }

    }

    // ロックおよびロック解除の失敗

    return FALSE;

}


圧縮waveの使用

現在のDirectSoundは、圧縮waveをサポートしていない。圧縮されたオーディオ・データを、サウンド・バッファに書きこむ前にPCM(pulse-coded modulation)データへと変換するには、 Win32 SDKで提供しているオーディオ圧縮マネージャ(ACM) 関数を使用する必要がある。実際には、ポインタをサウンド・バッファ・メモリのポインタをロックして ACMに渡せば、最も効率よくデータを直接サウンド・バッファへデコードできる。


DirectSoundリファレンス


関数


DirectSoundCreate

HRESULT DirectSoundCreate(GUID FAR * lpGuid,

    LPDIRECTSOUND * ppDS, IUuknown FAR * pUnkOuter);

IDirectSoundインターフェイスの作成と初期化を行う。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_ALLOCATED

DSERR_INVALIDPARAM

DSERR_NOAGGREGATION

DSERR_NODRIVER

DSERR_OUTOFMEMORY

lpGuid

サウンドデバイスを識別するGUIDへのポインタ。このパラメータの値はDirectSoundEnumerateにより返されるGUIDsのひとつ、もしくはデフォルトのデバイスを要求するためにNULLとなる。

ppDS

この関数に応答して作成されるDirectSoundオブジェクトへのポインタ。

pUnkOuter

未定義の引数。この値はNULLでなければならない。

DirectSoundオブジェクトの作成後は、すみやかにIDirectSound::SetCooperativeLevelメソッドを呼び出さなくてはならない。

参照　IDirectSound::GetCaps, IDirectSound::SetCooperativeLevel


DirectSoundEnumerate

BOOL DirectSoundEnumerate(

    LPDSENUMCALLBACK lpDSEnumCallback, LPVOID lpContext);

システムにインストールされているDirectSoundドライバを列挙する。

成功すればＤＳ_ＯＫ 、失敗すればDSERR_INVALIDPARAMのエラーコードを返す。

lpDSEnumCallback

DSEnumCallback関数へのポインタ。これはシステムにインストールされているそれぞれのDirectSoundオブジェクトから呼び出される。

lpContext

ユーザ定義コンテキストへのポインタ。このコンテキストは、列挙コールバック関数が呼び出されるたびに、その関数へ渡される。

参照　DSEnumCallback


コールバック関数


DSEnumCallback

BOOL DSEnumCallback(GUID FAR * lpGuid,

    LPSTR lpstrDescription, LPSTR lpstrModule,

    LPVOID lpContext);

DirectSoundドライバを列挙するための、アプリケーション定義コールバック関数。システムは直前のDirectSoundEnumerate関数の呼び出しに応答してこの関数を呼び出す。

ドライバの列挙が続く場合にはTRUE、終了する場合にはFALSEを返す。

lpGuid

列挙中のドライバを識別するGUIDへのポインタ。この値は、ドライバのDirectSoundオブジェクトを作成するためにDirectSoundCreate関数へ渡される。

lpstrDescription

DirectSoundデバイスのテキスト記述を与える、 NULLで終わる文字列へのポインタ。

lpstrModule

このデバイスに相当するDirectSoundドライバのモジュール名を指定する、NULLで終わる文字列へのポインタ。

lpContext

アプリケーション定義データへのポインタ。それぞれのコールバック関数へ渡される。

lpstrDescriptionおよび lpstrModuleパラメータに渡された文字列は、ヒープから割り当てられたメモリへコピーして保存することができる。文字列をこのコールバック関数へ渡すのに使用されたメモリは、このコールバック関数が実行中のときにのみ有効となる。

参照　DirectSoundEnumerate


IDirectSound

アプリケーションはDirectSoundオブジェクトの作成と環境設定にIDirectSoundインターフェイスのメソッドを使用する。この節はこのインターフェイスのメソッドのリファレンスとなっている。概念についての概要はIDirectSoundインターフェイスを参照すること。

IDirectSoundインターフェイスのメソッドは以下のグループで編成されている

メモリ割り当て	Compact
	Initialize
バッファ作成	CreateSoundBuffer
	DuplicateSoundBuffer
	SetCooperativeLevel
デバイス性能	GetCaps
スピーカ設定	GetSpeakerConfig
	SetSpeakerConfig
すべてのCOMインターフェイスと同様、IDirectSoundインターフェイスは IUuknownインターフェイスメソッドを継承している。IUuknownインターフェイスは以下の３つのメソッドをサポートしている。

AddRef
QueryInterface
Release


IDirectSound::Compact

HRESULT Compact();

オンボード・サウンドメモリの未使用部分を連続ブロックへ移動し、最大のフリーメモリ領域を使用可能にする。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

DSERR_UNINITIALIZED

このメソッドを呼び出すと、アプリケーションはDirectSoundオブジェクトと排他的な協調レベルを持たなければならない (排他的アクセスを得るには、 IDirectSound::SetCooperativeLevel メソッドの中でDSSCL_EXCLUSIVEを指定する)。進行中の操作がひとつでもあると、このメソッドは失敗する。

参照　IDirectSound, IDirectSound::SetCooperativeLevel


IDirectSound::CreateSoundBuffer

HRESULT CreateSoundBuffer(LPDSBUFFERDESC lpDSBufferDesc,

    LPLPDIRECTSOUNDBUFFER lplpDirectSoundBuffer,

    IUuknown FAR * pUnkOuter);

サンプリング・オーディオのシーケンスを保持するためのDirectSoundBufferオブジェクトを作成する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_ALLOCATED

DSERR_BADFORMAT

DSERR_INVALIDPARAM

DSERR_NOAGGREGATION

DSERR_OUTOFMEMORY

DSERR_UNINITIALIZED

DSERR_UNSUPPORTED

lpDSBufferDesc

作成されたサウンド・バッファの記述が含まれているDSBUFFERDESC構造体へのポインタ。

lplpDirectSoundBuffer

新規のDirectSoundBufferオブジェクトへのポインタ。バッファが作成されなかった場合はNULLとなる。

pUnkOuter

未定義の引数。この値はNULLでなくてはならない。

サウンド・バッファを再生可能にするために、事前にIDirectSound::SetCooperativeLevelメソッドを使用してDirectSoundオブジェクトの協調レベルを指定しておかなくてはならない。

lpDSBufferDescパラメータは、形式、サイズ、性能といった、要求されたバッファのタイプ情報を含む構造体を示す。アプリケーションが必要とする能力について指定していないとこれらは無効になる。たとえばDirectSoundオブジェクトを作成するときに DSBCAPS_CTRLFREQUENCYフラグを指定しておかないと、 IDirectSoundBuffer::SetFrequencyの呼び出しはすべて失敗する。

ハードウェア・ミキシングの利用のために、使用可能なオンボード・メモリ上のバッファを読み込む場合は、 DSBCAPS_STATICフラグを指定することもできる。ハードウェア・ミキシングとソフトウェア・ミキシング、このどちらを使用するかをバッファへ強制的に指定するには、DSBCAPS_LOCHARDWARE 、もしくは DSBCAPS_LOCSOFTWAREフラグを使用する。

参照　DSBUFFERDESC, IDirectSound,

 IDirectSound::DuplicateSoundBuffer, IDirectSound::SetCooperativeLevel, IDirectSoundBuffer, IDirectSoundBuffer::GetFormat, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::Lock, IDirectSoundBuffer::Play, IDirectSoundBuffer::SetFormat, IDirectSoundBuffer::SetFrequency


IDirectSound::DuplicateSoundBuffer

HRESULT DuplicateSoundBuffer(

    LPDIRECTSOUNDBUFFER lpDsbOriginal,

    LPLPDIRECTSOUNDBUFFER lplpDsbDuplicate);

DirectSoundBufferオブジェクトを新規作成する。これは同じバッファ・メモリをオリジナルのオブジェクトとして使用する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_ALLOCATED

DSERR_INVALIDCALL

DSERR_INVALIDPARAM

DSERR_OUTOFMEMORY

DSERR_UNINITIALIZED

lpDsbOriginal

複製されたDirectSoundBufferオブジェクトへのポインタ。

lplpDsbDuplicate

新規のDirectSoundオブジェクトへのポインタ。

新規のオブジェクトはオリジナルと同じように使用できる。

複製直後のバッファは、オリジナルバッファと同じパラメータを持つ。ただし、それぞれのパラメータを個々に変更して、相手に影響を及ぼすことなく、再生および停止を行うことができる。

バッファ内のデータがどちらかのオブジェクトによって変更されると、メモリが共有されているために、その変更はもう一方のオブジェクトにも反映される。

最後のオブジェクト参照が解放されると、バッファ・メモリは解放される。

参照　IDirectSound, IDirectSound::CreateSoundBuffer


IDirectSound::GetCaps

HRESULT GetCaps(LPDSCAPS lpDSCaps);

DirectSoundオブジェクトとなっているハードウェア・デバイスの性能を取得する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_GENERIC

DSERR_INVALIDPARAM

DSERR_UNINITIALIZED

lpDSCaps

サウンド・デバイスの性能が示されているDSCAPS 構造体へのポインタ。

DSCAPS構造体の中から取得された情報は、サウンド・デバイスの最大性能と、それが現在使用可能かどうかを示している。たとえば、ハードウェア・ミキシング・チャンネルの数とオンボード・サウンド・メモリの量などである。この情報をパフォーマンスの向上とリソース割り当ての最適化に利用することができる。

リソースの共有により、ひとつのエリアで性能を最大に引き出すと他のエリアが犠牲になる。たとえば、最大数のストリーム・サウンド・バッファのミキシングがハードウェア上で使用可能になるのは、ハードウェア上にスタティック・サウンド・バッファがひとつもない場合のみである。

参照　DirectSoundCreate, DSCAPS, IDirectSound


IDirectSound::GetSpeakerConfig

HRESULT GetSpeakerConfig(LPDWORD lpdwSpeakerConfig);

DirectSoundオブジェクトで指定されたスピーカ設定を取得する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_INVALIDPARAM

DSERR_UNINITIALIZED

lpdwSpeakerConfig

このDirectSoundオブジェクトのスピーカ設定へのポインタ。スピーカ設定は以下の値で指定される。

DSSPEAKER_HEADPHONE

	オーディオはヘッドホンから出力する。

DSSPEAKER_MONO

	オーディオはモノラル・スピーカから出力する。

DSSPEAKER_QUAD

	オーディオは4チャンネル・スピーカから出力する。

DSSPEAKER_STEREO

	オーディオはステレオ・スピーカから出力される(デフォルト値)。

DSSPEAKER_SURROUND

	オーディオはサラウンド・スピーカから出力される。
参照　IDirectSound, IDirectSound::SetSpeakerConfig


IDirectSound::Initialize

HRESULT Initialize(GUID FAR * lpGuid);

CoCreateInstance関数により作成されたDirectSoundオブジェクトを初期化する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_ALREADYINITIALIZED

DSERR_GENERIC

DSERR_INVALIDPARAM

DSERR_NODRIVER

lpGuid

グローバルユニーク識別子(GUID)へのポインタ。この識別子は、このDirectSoundオブジェクトを結合するためのサウンドドライバを指定する。NULLの場合はプライマリ・サウンド・バッファが選択される。

このメソッドはCOMプロトコルに準拠している。もしDirectSoundオブジェクトの作成にDirectSoundCreate関数が使用されていると、このメソッドはDSERR_ALREADYINITIALIZEDを返す。 CoCreateInstanceを使用してDirectSoundオブジェクトを作成したときにIDirectSound::Initializeが呼び出されないと、その後に呼び出されるメソッドはすべてDSERR_UNINITIALIZEDを返す。

CoCreateInstanceを利用したIDirectSound::Initializeの使用については、 CoCreateInstanceを使用したDirectSoundオブジェクトの作成を参照すること。

参照　DirectSoundCreate


IDirectSound::SetCooperativeLevel

HRESULT SetCooperativeLevel(HWND hwnd, DWORD dwLevel);

サウンド・デバイスに対するアプリケーションの協調レベルを設定する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_ALLOCATED

DSERR_INVALIDPARAM

DSERR_UNINITIALIZED

DSERR_UNSUPPORTED

hwnd

アプリケーションのウィンドウ・ハンドル。

dwLevel

要求された協調レベル。 次の値が指定できる。

DSSCL_EXCLUSIVE

	アプリケーションを排他レベルに設定する。入力フォーカスを得ると、そのアプリケーションだけが唯一鳴らせるようになる (DSBCAPS_GLOBALFOCUSフラグ設定のアプリケーションからのサウンドはミュートされる)。このレベルにおける アプリケーションは、DSSCL_PRIORITYレベルのすべての特権を有す。最新のIDirectSoundBuffer::SetFormatメソッドの呼び出しで指定されると、DirectSoundはハードウェア形式をリストアする (ただし、DirectSoundは 設定された優先レベルに関わらず、つねにwaveをリストアする)。

DSSCL_NORMAL

	アプリケーションに十分な協調状態を設定する。最もスムーズなマルチタスキングとリソース共有を行うので、ほとんどのアプリケーションはこのレベルに設定すべき。

DSSCL_PRIORITY

	アプリケーションを 優先レベルに設定する。このレベルのアプリケーションはIdirectSoundBuffer::SetFormatおよびIDirectSound::Compactメソッドを呼び出すことができる。

DSSCL_WRITEPRIMARY

	これは最上位のレベルである。アプリケーションはプライマリ・サウンド・バッファへの書きこみアクセスを有している。セカンダリ・サウンド・バッファの再生は一切できない。
バッファを再生する前に、このメソッドを呼び出して協調レベルを設定しておくことは必須である。推奨の協調レベルはDSSCL_NORMALである。他の優先レベルは必要に応じて使用する。 詳細については、協調レベルを参照すること。

参照　IDirectSound, IDirectSound::Compact, IDirectSoundBuffer::GetFormat, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::Lock, IDirectSoundBuffer::Play, IDirectSoundBuffer::Restore, IDirectSoundBuffer::SetFormat


IDirectSound::SetSpeakerConfig

HRESULT SetSpeakerConfig(DWORD dwSpeakerConfig);

DirectSoundオブジェクトのスピーカ設定を指定する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_INVALIDPARAM

DSERR_UNINITIALIZED

dwSpeakerConfig

DirectSoundオブジェクトのスピーカ設定。以下の値を指定できる。

DSSPEAKER_HEADPHONE

	スピーカはヘッドホンになる。

DSSPEAKER_MONO

	スピーカはモノラルになる。

DSSPEAKER_QUAD

	スピーカは4チャンネルになる。

DSSPEAKER_STEREO

	スピーカはステレオになる(デフォルト値) 。

DSSPEAKER_SURROUND

	スピーカはサラウンド・サウンドになる。
参照　IDirectSound, IDirectSound::GetSpeakerConfig


IDirectSound3DBuffer

リスナーの3D空間における位置、方向、サウンド・バッファ環境を表すパラメータの取得および設定を行うためには IDirectSound3DBufferインターフェイスのメソッドを使用する。この節はこのインターフェイスのメソッドのリファレンスである。概念についての概要は、 IDirectSound3DBufferインターフェイスを参照すること。

IDirectSound3DBuffer インターフェイスのメソッドは次のグループで構成されている

バッチパラメータ	GetAllParameters
操作	SetAllParameters
距離	GetMaxDistance
	GetMinDistance
	SetMaxDistance
	SetMinDistance
操作モード	GetMode
	SetMode
位置	GetPosition
	SetPosition
サウンド・プロジェクション	GetConeAngles
コーン	GetConeOrientation
	GetConeOutsideVolume
	SetConeAngles
	SetConeOrientation
	SetConeOutsideVolume
速度	GetVelocity
	SetVelocity
すべてのCOMインターフェイスと同様、IDirectSound3DBuffer インターフェイスは IUuknownインターフェイス・メソッドを継承している。IUuknownインターフェイスは次の３つのメソッドをサポートしている。

AddRef
QueryInterface
Release


IDirectSound3DBuffer::GetAllParameters

HRESULT GetAllParameters(LPDS3DBUFFER lpDs3dBuffer);

指定した時点でのサウンドバッファの3D特性についての情報を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpDs3dBuffer

DS3DBUFFER構造体へのポインタ。この構造体はサウンド・バッファの3D特性についての情報を持っている。


IDirectSound3DBuffer::GetConeAngles

HRESULT GetConeAngles(

    LPDWORD lpdwInsideConeAngle, LPDWORD lpdwOutsideConeAngle);

サウンド・バッファのサウンド・プロジェクション・コーンの内部角と外部角を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

lpdwInsideConeAngle および lpdwOutsideConeAngle

サウンド・プロジェクション・コーンの内部角と外部角を示す変数へのポインタ。


IDirectSound3DBuffer::GetConeOrientation

HRESULT GetConeOrientation(LPD3DVECTOR lpvOrientation);

サウンド・バッファのサウンド・プロジェクション・コーンの方向を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpvOrientation

D3DVECTOR構造体へのポインタ。この構造体はサウンド・プロジェクション・コーンの現在の方向を示している。ベクトル情報はサウンド・コーンの中心を表す。

メソッドはコーン角度とコーンボリュームの要素も設定されていないと効果がない。デフォルト値は(0,0,1)である。

参照　IDirectSound3DBuffer::SetConeAngles, IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::GetConeOutsideVolume

HRESULT GetConeOutsideVolume(LPLONG lplConeOutsideVolume);

サウンド・バッファにおける現在のコーン外部ボリュームを取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

lplConeOutsideVolume

バッファの現在のコーン外部ボリュームを示す変数へのポインタ。

ボリューム・レベルは減衰を表す。許容範囲は0(減衰なし)から-10,000(無音)までである。増幅は現在のDirectSoundではサポートされていない。

コーン外部ボリュームについての詳細情報は、サウンド・プロジェクション・コーンを参照すること。

参照　IDirectSoundBuffer::SetVolume


IDirectSound3DBuffer::GetMaxDistance

HRESULT GetMaxDistance(LPD3DVALUE lpflMaxDistance);

サウンド・バッファの現在の最長距離を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM  エラーコードを返す。

lpflMaxDistance

現在の最長距離設定を示す変数へのポインタ。

デフォルトでは最長距離値は無限になっている。最短距離と最長距離についての詳細情報は、最短距離値と最長距離値を参照すること。

参照　IDirectSound3DBuffer::GetMinDistance, IDirectSound3DBuffer::SetMaxDistance


IDirectSound3DBuffer::GetMinDistance

HRESULT GetMinDistance(LPD3DVALUE lpflMinDistance);

サウンド・バッファの現在の最短距離を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpflMinDistance

現在の最短距離設定を示す変数へのポインタ。

デフォルトでは最短距離値は1.0になっている。これはデフォルトの距離値の単位にメートル設定されている場合は1.0メートルということである。最短距離と最長距離についての詳細情報は、最短距離値と最長距離値を参照すること。

参照　IDirectSound3DBuffer::SetMinDistance, IDirectSound3DBuffer::GetMaxDistance


IDirectSound3DBuffer::GetMode

HRESULT GetMode(LPDWORD lpdwMode);

3Dサウンド処理の現在の操作モードを取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpdwMode

現在の操作モードを示す変数へのポインタ。次の値で返る。

DS3DMODE_DISABLE

	3Dサウンド処理は無効になる。サウンドはリスナーの頭の中心から聞こえるように感じる。

DS3DMODE_HEADRELATIVE

	サウンドパラメータ(位置、速度、方向)はリスナーのパラメータと相対関係にある。このモードでは、サウンドの絶対パラメータはリスナー・パラメータが変更されたときに自動的に更新されるので、相対パラメータには変化はないままである。

DS3DMODE_NORMAL

	標準の処理。これがデフォルトモードになっている。


IDirectSound3DBuffer::GetPosition

HRESULT GetPosition(LPD3DVECTOR lpvPosition);

サウンド・バッファの現在の位置を距離単位で取得する。デフォルトでは距離単位はメートルだが、単位の変更はIDirectSound3DListener::SetDistanceFactorメソッドを使用して行える。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpvPosition

D3DVECTOR構造体へのポインタ。この構造体はサウンド・バッファ中のカレント・ポジションを示している。


IDirectSound3DBuffer::GetVelocity

HRESULT GetVelocity(LPD3DVECTOR lpvVelocity);

サウンド・バッファの現在の速度を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

lpvVelocity

D3DVECTOR構造体へのポインタ。この構造体はサウンド・バッファの現在の速度を示している。

速度はドップラー効果でのみ使用される。実際にバッファを移動することはない。詳細は位置と速度を参照すること。

参照　IDirectSound3DBuffer::SetPosition, IDirectSound3DBuffer::SetVelocity


IDirectSound3DBuffer::SetAllParameters

HRESULT SetAllParameters(

    LPDS3DBUFFER lpDs3dBuffer, DWORD dwApply);

サウンド・バッファのある瞬間の状態のすべてを示しているDS3DBUFFER構造体から与えられた、すべての3Dサウンド・バッファ・パラメータを設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpDs3dBuffer

DS3DBUFFER構造体へのポインタ。この構造体はサウンド・バッファの3D特性を示している。

dwApply

設定のタイミングを示す値。次の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。


IDirectSound3DBuffer::SetConeAngles

HRESULT SetConeAngles(

    DWORD dwInsideConeAngle,

    DWORD dwOutsideConeAngle, DWORD dwApply);

サウンド・バッファのサウンド・プロジェクション・コーンの内部角と外部角を設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

dwInsideConeAngleおよび dwOutsideConeAngle

サウンド・プロジェクション・コーンの内部角と外部角。

dwApply

設定が行われるタイミングを示す値。次の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
角度の範囲は0度(コーンなし)から360度(全範囲)までである。デフォルト値は360である。詳細はサウンド・プロジェクション・コーンを参照すること。

参照　IDirectSound3DBuffer::GetConeOutsideVolume, IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::SetConeOrientation

HRESULT SetConeOrientation(D3DVALUE x,

    D3DVALUE y, D3DVALUE z, DWORD dwApply);

サウンド・バッファの、サウンド・プロジェクション・コーンの方向を設定する。このメソッドは、コーン角度とコーンボリュームの要素も設定されていないと効果が得られない。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

x, y, および z

D3DVALUEのタイプを示す値。これは新規のサウンド・コーンの方向ベクトルの座標を表す。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
IDirectSound3DBuffer::GetConeOrientation メソッドの lpvOrientationパラメータ内のベクトル情報は、サウンド・コーンの中心を表している。デフォルト値は(0,0,1)である。

参照　IDirectSound3DBuffer::SetConeAngles, IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::SetConeOutsideVolume

HRESULT SetConeOutsideVolume(

    LONG lConeOutsideVolume, DWORD dwApply);

サウンド・バッファの現在のコーン外部ボリュームを設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lConeOutsideVolume

サウンド・バッファのコーン外部ボリュームを100デシベル（dB）の範囲で指定する。認定可能範囲は0(減衰なし)から-10,000(無音)までである。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
ボリューム・レベルは減衰を表す。増幅はDirectSoundでは現在サポートされていない。

コーン外部ボリュームの概念についての詳細は、サウンド・プロジェクション・コーンを参照すること。

参照　IDirectSoundBuffer::SetVolume


IDirectSound3DBuffer::SetMaxDistance

HRESULT SetMaxDistance(

    D3DVALUE flMaxDistance, DWORD dwApply);

現在の最長距離値を設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

flMaxDistance

新しい最長距離値。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
デフォルトでは最長距離値は無限になっている。最短距離と最長距離についての詳細情報は、最短距離値と最長距離値を参照すること。

参照　IDirectSound3DBuffer::GetMaxDistance, IDirectSound3DBuffer::SetMinDistance


IDirectSound3DBuffer::SetMinDistance

HRESULT SetMinDistance(

    D3DVALUE flMinDistance, DWORD dwApply);

現在の最短距離値を設定する。

成功すればDS_OK、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

flMinDistance

新しい最短距離値。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
デフォルトでは最短距離値は1.0(デフォルトの距離値単位はメートルなので、1.0メートルを意味する)になっている。最短距離と最長距離についての詳細情報は、最短距離値と最長距離値を参照すること。

参照　IDirectSound3DBuffer::SetMaxDistance


IDirectSound3DBuffer::SetMode

HRESULT SetMode(

    DWORD dwMode, DWORD dwApply);

3Dサウンド処理に対する操作モードを設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

dwMode

3Dサウンド処理モードを設定する。次の値で示される。

DS3DMODE_DISABLE

	3Dサウンド処理は無効。サウンドはリスナーの頭の中心から聞こえるように感じる。

DS3DMODE_HEADRELATIVE

	サウンド・パラメータ(位置、速度、方向)はリスナーのパラメータと相対関係にある。このモードでは、サウンドの絶対パラメータはリスナー・パラメータが変更されたときに自動的に更新されるので、相対パラメータは変わらないままである。

DS3DMODE_NORMAL

	標準の処理。これがデフォルト・モードになっている。
dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。


IDirectSound3DBuffer::SetPosition

HRESULT SetPosition(D3DVALUE x,

    D3DVALUE y, D3DVALUE z, DWORD dwApply);

サウンド・バッファの現在の位置を距離単位で設定する。デフォルトの距離単位はメートルだが、IDirectSound3DListener::SetDistanceFactor methodメソッドを使用して単位の変更も行える。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

x, y, および z

D3DVALUEのタイプを示す値。これは新しい位置ベクトルの座標を表す。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。


IDirectSound3DBuffer::SetVelocity

HRESULT SetVelocity(D3DVALUE x,

    D3DVALUE y, D3DVALUE z, DWORD dwApply);

サウンド・バッファの現在の速度を設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

x, y, および z

D3DVALUEのタイプを示す値。これは新しい速度ベクトルの座標を表す。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
速度はドップラー効果でのみ使用される。実際にバッファを移動することはない。詳細は位置と速度を参照すること。

参照　IDirectSound3DBuffer::SetPosition, IDirectSound3DBuffer::GetVelocity


IDirectSound3DListener

リスナーの3D空間における位置、方向、リスニング環境を表すパラメータの取得および設定を行うには IDirectSound3DListenerインターフェイスのメソッドを使用する。この節はこのインターフェイス・メソッドのリファレンスである。概念についての概要は、IDirectSound3DListenerインターフェイスを参照すること。

IDirectSound3DListener インターフェイスのメソッドは以下のグループで構成されている

バッチパラメータ操作	GetAllParameters
	SetAllParameters
据え置き設定	CommitDeferredSettings
距離要素	GetDistanceFactor
	SetDistanceFactor
ドップラー要素	GetDopplerFactor
	SetDopplerFactor
方向	GetOrientation
	SetOrientation
位置	GetPosition
	SetPosition
ロールオフ要素	GetRolloffFactor
	SetRolloffFactor
速度	GetVelocity
	SetVelocity
すべてのCOMインターフェイスと同様、IDirectSound3DBuffer インターフェイスは IUuknownインターフェイスメソッドを継承している。IUuknownインターフェイスは以下の３つのメソッドをサポートしている。

AddRef
QueryInterface
Release


IDirectSound3DListener::CommitDeferredSettings

HRESULT CommitDeferredSettings();

前回のこのメソッドの呼び出し以後に作成された据え置き設定をコミットする。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

最大の能率で据え置き設定を使用する方法についての詳細は据え置き設定を参照すること。


IDirectSound3DListener::GetAllParameters

HRESULT GetAllParameters(LPDS3DLISTENER lpListener);

3Dワールドおよび3Dリスナーの現在の状態を表す情報を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpListener

DS3DLISTENER構造体へのポインタ。この構造体は3Dワールドおよび3Dリスナーの現在の状態を示す。

参照　IDirectSound3DListener::SetAllParameters


IDirectSound3DListener::GetDistanceFactor

HRESULT GetDistanceFactor(LPD3DVALUE lpflDistanceFactor);

現在の距離要素を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpflDistanceFactor

D3DVALUEタイプの変数へのポインタ。これは現在の距離要素の値が示される。

距離要素についての詳細は、距離要素を参照すること。

参照　IDirectSound3DListener::SetDistanceFactor


IDirectSound3DListener::GetDopplerFactor

HRESULT GetDopplerFactor(LPD3DVALUE lpflDopplerFactor);

現在のドップラー効果を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpflDopplerFactor

D3DVALUEタイプの変数へのポインタ。これは現在ドップラー要素の値が示される。

ドップラー要素の範囲は0(ドップラー要素なし)から10.0(実際の世界の10倍のドップラー要素)である 。デフォルト値はDS3D_DEFAULTDOPPLERFACTOR (1.0)である。ドップラー要素についての詳細は、ドップラー要素を参照すること。

参照　IDirectSound3DListener::SetDopplerFactor


IDirectSound3DListener::GetOrientation

HRESULT GetOrientation(

    LPD3DVECTOR lpvOrientFront,

    LPD3DVECTOR lpvOrientTop);

リスナーの現在の方向を前方ベクトルと上方ベクトルのふたつのベクトルで取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

lpvOrientFront

D3DVECTOR構造体へのポインタ。リスナーの前方ベクトルを示している。

lpvOrientTop

D3DVECTOR構造体へのポインタ。リスナーの上方ベクトルを示している。

前方ベクトルはリスナーの鼻に位置し、上方ベクトルはリスナーの頭上から位置する。デフォルトでは前方ベクトルは(0,0,1.0)、上方ベクトルは(0,1.0,0)となっている。

参照　IDirectSound3DListener::SetOrientation


IDirectSound3DListener::GetPosition

HRESULT GetPosition(LPD3DVECTOR lpvPosition);

リスナーの現在の位置を距離単位で取得する。デフォルトの距離単位はメートルだが、IDirectSound3DListener::SetDistanceFactorメソッドを使用して距離単位を変更することもできる。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

lpvPosition

D3DVECTOR構造体へのポインタ。リスナーの現在の位置を示す。

参照　IDirectSound3DListener::SetPosition


IDirectSound3DListener::GetRolloffFactor

HRESULT GetRolloffFactor(LPD3DVALUE lpflRolloffFactor);

現在のロールオフ要素を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

lpflRolloffFactor

D3DVALUEタイプの変数へのポインタ。現在のロールオフ要素の値を示している。

デフォルト値はDS3D_DEFAULTROLLOFFFACTOR (1.0)である。ロールオフ要素についての詳細は、ロールオフ要素を参照すること。

参照　IDirectSound3DListener::SetRolloffFactor


IDirectSound3DListener::GetVelocity

HRESULT GetVelocity(LPD3DVECTOR lpvVelocity);

リスナーの現在の速度を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

lpvVelocity

D3DVECTOR構造体へのポインタ。この構造体はサウンド・バッファの現在の速度を示している。

速度はドップラー要素でのみ使用される。実際にリスナーの位置の移動はない。リスナーの位置を変更するにはIDirectSound3DListener::SetPosition メソッドを使用する。デフォルトの速度は (0,0,0)である。

参照　IDirectSound3DListener::SetVelocity


IDirectSound3DListener::SetAllParameters

HRESULT SetAllParameters(

    LPDS3DLISTENER lpListener, DWORD dwApply);

DS3DLISTENER構造体に指定されたすべての3Dリスナー・パラメータを設定する。この構造体はある瞬間のリスナーの状態をすべて示している。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpListener

DS3DBUFFER構造体へのポインタ。現在の3Dリスナー・パラメータ情報をすべて示している。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算の実行が可能である。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
参照　IDirectSound3DListener::GetAllParameters


IDirectSound3DListener::SetDistanceFactor

HRESULT SetDistanceFactor(

    D3DVALUE flDistanceFactor, DWORD dwApply);

現在の距離要素を設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

flDistanceFactor

新しい距離要素。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能である。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
距離要素についての詳細は距離要素を参照すること。

参照　IDirectSound3DListener::GetDistanceFactor


IDirectSound3DListener::SetDopplerFactor

HRESULT SetDopplerFactor(

    D3DVALUE flDopplerFactor, DWORD dwApply);

現在のドップラー要素の要素を設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

flDopplerFactor

新しいドップラー要素の値。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能である。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
ドップラー要素の範囲は0(ドップラー要素なし)から10.0(実際の世界の10倍のドップラー要素)である。 デフォルト値はDS3D_DEFAULTDOPPLERFACTOR (1.0)である。ドップラー要素についての詳細は、ドップラー要素を参照すること。

参照　IDirectSound3DListener::GetDopplerFactor


IDirectSound3DListener::SetOrientation

HRESULT SetOrientation(D3DVALUE xFront,

    D3DVALUE yFront, D3DVALUE zFront,

    D3DVALUE xTop, D3DVALUE yTop,

    D3DVALUE zTop, DWORD    dwApply);

リスナーの現在の方向を前方ベクトルと上方ベクトルのふたつのベクトルで取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

xFront, yFront, および zFront

D3DVALUEタイプの値。前方ベクトルの座標を示している。

xTop, yTop, および zTop

D3DVALUEタイプの値。上方ベクトルの座標を示している。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行することが可能である。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
前方ベクトルはリスナーの鼻に位置し、上方ベクトルはリスナーの頭上に位置する。デフォルトでは前方ベクトルは(0,0,1.0)、上方ベクトルは(0,1.0,0)となっている。

参照　IDirectSound3DListener::GetOrientation


IDirectSound3DListener::SetPosition

HRESULT SetPosition(D3DVALUE x, D3DVALUE y,

    D3DVALUE z, DWORD dwApply);

リスナーの現在の位置を距離単位で設定する。デフォルトの距離単位はメートルだが、IDirectSound3DListener::SetDistanceFactorメソッドを使用して単位の変更も行える。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

x, y, および z

D3DVALUEタイプの値。リスナーの新規の位置ベクトルの座標を示している。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算を実行したりできる。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標を再計算する。
参照　IDirectSound3DListener::GetPosition


IDirectSound3DListener::SetRolloffFactor

HRESULT SetRolloffFactor(

    D3DVALUE flRolloffFactor, DWORD dwApply);

ロールオフ要素を設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

flRolloffFactor

新規のロールオフ要素。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettingsメソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算の実行が可能である。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
デフォルト値はDS3D_DEFAULTROLLOFFFACTOR (1.0)である。ロールオフ要素についての詳細は、ロールオフ要素を参照すること。

参照　IDirectSound3DListener::GetRolloffFactor


IDirectSound3DListener::SetVelocity

HRESULT SetVelocity(D3DVALUE x,

    D3DVALUE y, D3DVALUE z, DWORD dwApply);

リスナーの速度を設定する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAM エラーコードを返す。

x, y, および z

D3DVALUEタイプの値。リスナーの新規の速度の座標を示している。

dwApply

設定が行われるタイミングを示す値。以下の値で示される。

DS3D_DEFERRED	アプリケーションがIDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定は行われない。複数の設定を変更したり、単独の再計算の実行が可能である。
DS3D_IMMEDIATE	設定は即時に行われ、システムはすべての3Dサウンド・バッファに対する3D座標の再計算を行う。
速度はドップラー要素でのみ使用される。実際にリスナーを移動することはない。リスナーの位置を変更するにはIDirectSound3DListener::SetPositionメソッドを使用する。デフォルトの速度は (0,0,0)である。

参照　IDirectSound3DListener::GetVelocity


IDirectSoundBuffer

DirectSoundBufferオブジェクトを作成して環境設定を行うには、 IDirectSoundBufferインターフェイスのメソッドを使用する。メソッドは以下のグループで構成されている。

情報	GetCaps
	GetFormat
	GetStatus
	SetFormat
メモリ管理	Initialize
	Restore
再生管理	GetCurrentPosition
	Lock
	Play
	SetCurrentPosition
	Stop
	Unlock
サウンド管理	GetFrequency
	GetPan
	GetVolume
	SetFrequency
	SetPan
	SetVolume
すべてのCOMインターフェイスと同様、IDirectSound3DBuffer インターフェイスは IUuknownインターフェイスメソッドを継承している。このインターフェイスは以下の３つのメソッドをサポートしている。

AddRef
QueryInterface
Release


IDirectSoundBuffer::GetCaps

HRESULT GetCaps(LPDSBCAPS lpDSBufferCaps);

DirectSoundBufferオブジェクトの能力を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpDSBufferCaps

DSBCAPS構造体へのポインタ。サウンド・バッファの性能を示している。

DSBCAPS構造体にはIDirectSound::CreateSoundBufferメソッドへ渡されるDSBUFFERDESC構造体と同等の情報に加えて更なる追加情報がいくつか含まれている。この追加情報とは、ハードウェア、ソフトウェア両方のバッファの場所と、コストである。コストには、ハードウェア・バッファへのダウンロードにかかる時間や、システムメモリ上にあるバッファのミキシングや再生時の処理のオーバーヘッドなどといったものがある。

DSBCAPS構造体のdwFlagsメンバ内で指定されたフラグはDSBUFFERDESC構造体で使用されるフラグと同じものである。しかし、 DSBCAPS構造体で使用するフラグの方はDSBCAPS_LOCHARDWAREもしくは DSBCAPS_LOCSOFTWAREのどちらかがバッファ用メモリの場所によって指定される点が唯一の違いである。DSBUFFERDESC構造体ではこれらのフラグは選択可能であり、指定されているフラグによってバッファの配置をハードウェアとソフトウェアのどちらかにすることができる。

参照　DSBCAPS, DSBUFFERDESC, IDirectSoundBuffer, IDirectSound::CreateSoundBuffer


IDirectSoundBuffer::GetCurrentPosition

HRESULT GetCurrentPosition(LPDWORD lpdwCurrentPlayCursor,

    LPDWORD lpdwCurrentWriteCursor);

サウンド・バッファ内の現在の再生カーソルおよび書きこみカーソルの位置を取得する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

lpdwCurrentPlayCursor

DirectSoundBufferオブジェクト内のカレント・プレイ・ポジションを示す変数へのポインタ。この位置はサウンド・バッファ内のオフセットであり、バイトで指定される。

lpdwCurrentWriteCursor

DirectSoundBufferオブジェクト内のカレント・ライト・ポジションを示す変数へのポインタ。この位置はサウンド・バッファ内のオフセットであり、バイトで指定される。

書きこみカーソルは、バッファへのデータ書きこみが安全にできる位置を表示する。書きこみカーソルは、再生カーソルより通常15ミリ秒相当のオーディオ・データ分だけ先にある。

lpdwCurrentPlayCursorパラメータで示された位置よりも後ろのデータを変更するのはつねに安全である。

参照　IDirectSoundBuffer, IDirectSoundBuffer::SetCurrentPosition


IDirectSoundBuffer::GetFormat

HRESULT GetFormat(LPWAVEFORMATEX lpwfxFormat,

    DWORD dwSizeAllocated, LPDWORD lpdwSizeWritten);

バッファ内のサウンド・データの形式についての情報を取得する。もしくは形式についての情報の取得に必要なバッファ・サイズを取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpwfxFormat

バッファ内のサウンド・データについての情報を含むWAVEFORMATEX構造体へのポインタ。形式の情報に必要なバッファ・サイズを取得する場合はNULLを指定する。

dwSizeAllocated

 WAVEFORMATEX構造体のバイト単位のサイズ。DirectSoundはポインタへ書きこむのはせいぜいdwSizeAllocatedのバイト数のみである。もしWAVEFORMATEX構造体がもっと多くのメモリを要求した場合は削られてしまう。

lpdwSizeWritten

WAVEFORMATEX構造体へ書きこまれたバイト数を示す変数へのポインタ。このパラメータはNULLでもよい。

WAVEFORMATEX構造体は可変長である。アプリケーションは形式の情報を取得する前に、このメソッドを使用してDirectSoundBufferへ、その形式のサイズを照会する必要がある。構造体のサイズはlpdwSizeWrittenパラメータへ返される。その後アプリケーションは十分なメモリを割り当てて再度IDirectSoundBuffer::GetFormatを呼び出すことで、形式についての情報の取得ができる。

参照　IDirectSoundBuffer, IDirectSoundBuffer::SetFormat


IDirectSoundBuffer::GetFrequency

HRESULT GetFrequency(LPDWORD lpdwFrequency);

バッファが再生されている場所の1秒間の周波数を取得する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_CONTROLUNAVAIL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

lpdwFrequency

オーディオ・バッファが再生されている場所の周波数を示す変数へのポインタ。

周波数の値は100から 100,000の範囲となっている。

参照　IDirectSoundBuffer, IDirectSoundBuffer::SetFrequency


IDirectSoundBuffer::GetPan

HRESULT GetPan(LPLONG lplPan);

左と右のオーディオ・チャンネルの相対ボリュームを示す変数を取得する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_CONTROLUNAVAIL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

lplPan

右と左の相対ミックスを示す変数へのポインタ。

返値は-10,000から10,000の範囲で10,000を100dB相当として測定される。-10,000の値は右のチャンネルが100dB弱くなっていることを意味する。10,000の値は左のチャンネルが100dB弱くなっていることを意味する。デフォルトの値は0である。 lplPanパラメータでは0は両方のチャンネルがフルボリュームであることを意味する(どちらも0dB弱くなっている)。0以外の設定はどれも、片方がフルボリュームで、もう片方が弱くなっている。

-2173のパンは、左チャンネルがフルボリュームで、右チャンネルが21.73 dB弱くなっていることを意味する。同様に870のパンは、左チャンネルが8.7 dB弱くなっており、右チャンネルがフルボリュームであることを意味する。-10,000のパンは、右チャンネルが無音で、サウンドが「左側のみ」であることを意味する。一方、10,000のパンは、左チャンネルが無音で、サウンドが「右側のみ」であることを意味する。

パン制御はボリューム・コントロールに累積して動作する。

参照　IDirectSoundBuffer, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::SetPan, IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::GetStatus

HRESULT GetStatus(LPDWORD lpdwStatus);

サウンド・バッファの現在の状態を取得する。

成功すればDS_OK 、失敗すればDSERR_INVALIDPARAMエラーコードを返す。

lpdwStatus

サウンド・バッファの状態を示す変数へのポインタ。状態は次の値で設定される。

DSBSTATUS_BUFFERLOST

	バッファは失われており、再生およびロックを行う前にリストアしが必要である。

DSBSTATUS_LOOPING

	バッファはループしている。値が未設定のときは、バッファのサウンドデータの最後で再生は停止する。この値の設定時には、バッファの再生も行われていることに注意する。

DSBSTATUS_PLAYING

	バッファは再生中である。この値が設定されていないとバッファは停止している。
参照　IDirectSoundBuffer


IDirectSoundBuffer::GetVolume

HRESULT GetVolume(LPLONG lplVolume);

サウンド・バッファの現在のボリュームを取得する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_CONTROLUNAVAIL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

lplVolume

指定されたDirectSoundバッファのボリュームを示す変数へのポインタ。

ボリュームは100dBの範囲を0から-10,000の範囲で、指定される。0は最初の、ストリームの未変更のボリュームを表す。-10,000はオーディオボリュームが 100 dB弱くなっていることを表す。増幅は現在のDirectSoundではサポートされていない。

デシベルの尺度は聴力に対して対数で対応している。たとえば、10dB減衰するとはバッファのサウンドは半分になり、20dB減衰すると4分の1になる。

参照　IDirectSoundBuffer, IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::Initialize

HRESULT Initialize(LPDIRECTSOUND lpDirectSound,

    LPDSBUFFERDESC lpDSBufferDesc);

初期化されていないDirectSoundBufferオブジェクトを初期化する。

DSERR_ALREADYINITIALIZEDエラーコードを返す。

lpDirectSound

DirectSoundBufferオブジェクトと結合したDirectSoundオブジェクトへのポインタ。

lpDSBufferDesc

サウンド・バッファの初期化に使用する値を示しているDSBUFFERDESC構造体へのポインタ。

IDirectSound::CreateSoundBufferメソッドは内部でIDirectSoundBuffer::Initializeを呼び出すので、現在のリリースのDirectSoundでは必要ない。これは将来の拡張性のために用意されたものである。

参照　DSBUFFERDESC, IDirectSound::CreateSoundBuffer, IDirectSoundBuffer


IDirectSoundBuffer::Lock

HRESULT Lock(DWORD dwWriteCursor, DWORD dwWriteBytes,

    LPVOID lplpvAudioPtr1, LPDWORD lpdwAudioBytes1,

    LPVOID lplpvAudioPtr2, LPDWORD lpdwAudioBytes2,

    DWORD dwFlags);

サウンド・バッファのオーディオ・データに対して有効な書きこみアクセスを取得する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_BUFFERLOST

DSERR_INVALIDCALL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

dwWriteCursor

バッファの開始位置からロックを開始する位置までの、バイト単位のオフセット。 dwFlagsパラメータでDSBLOCK_FROMWRITECURSORフラグが指定されている場合は、このパラメータは無視される。

dwWriteBytes

ロックするバッファ領域の、バイト単位のサイズ。サウンド・バッファは概念的には円になっている（リングバッファ）ことに注意すること。

lplpvAudioPtr1

ロックされるバッファの最初のブロックへのポインタ。

lpdwAudioBytes1

lplpvAudioPtr1パラメータで示されたバイト数を示す変数へのポインタ。この値がdwWriteBytesパラメータより小さい場合、 lplpvAudioPtr2がサウンドデータの次のブロックを示す。

lplpvAudioPtr2

ロックされるサウンド・バッファの2番目の領域へのポインタ。このパラメータの値がNULLの場合、 lplpvAudioPtr1パラメータはサウンド・バッファのロックされた領域全体を示す。

lpdwAudioBytes2

lplpvAudioPtr2 パラメータでポイントされたバイト数を示す変数のアドレス。 lplpvAudioPtr2がNULLの場合、この値は0となる。

dwFlags

ロックのイベントを修正するフラグ。以下の値で示される。

DSBLOCK_FROMWRITECURSOR

	現在の書きこみカーソルからロックを行い、 これによりIDirectSoundBuffer::GetCurrentPositionの呼び出しが不必要になる。このフラグが指定されるとdwWriteCursorパラメータは無視される。このフラグは任意に指定できる。
このメソッドはオフセットと領域カウントを受け取り、ふたつの書きこみポインタとこれを合わせたサイズを返す。ふたつのポインタを必要とするのはサウンド・バッファが環状（リング・バッファ）のためである。ロックされたバッファが終了位置で循環しない場合、ふたつめのポインタであるlplpvAudioBytes2はNULLになる。ただし循環する場合は、ふたつめのポインタはバッファの開始位置を示す。

lplpvAudioPtr2および lpdwAudioBytes2パラメータに対してNULLを渡すと、DirectSoundはバッファのラップアラウンド領域をロックしない。

アプリケーションはIDirectSoundBuffer::Lockメソッドにより返されたポインタへデータを書きこみ、DirectSoundへバッファを返すためにIDirectSoundBuffer::Unlockメソッドを呼び出す必要がある。サウンド・バッファへのロックは長時間すべきではない。長時間ロックされると、再生カーソルがロックされた領域へ到達してしまい、ランダムノイズといった、機器構成依存のオーディオ問題が発生する。

Warning

このメソッドは書きこみポインタのみを返す。このポインタからサウンドデータの読み込みは行わない。たとえDirectSoundBufferオブジェクトが有効なサウンド・データを含んでいても、そのデータは無効である。たとえば、バッファがオンボード・メモリに配置されていた場合、ポインタはメイン・システムメモリ内のテンポラリ・バッファのアドレスとなる。IDirectSoundBuffer::Unlockが呼び出されると、このテンポラリ・バッファはオンボード・メモリに転送される。

参照　IDirectSoundBuffer, IDirectSoundBuffer::GetCurrentPosition, IDirectSoundBuffer::Unlock


IDirectSoundBuffer::Play

HRESULT Play(DWORD dwReserved1, DWORD dwReserved2,

    DWORD dwFlags);

サウンド・バッファを現在の位置から再生させる。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_BUFFERLOST

DSERR_INVALIDCALL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

dwReserved1

このパラメータは予約済みである。この値は0でなければならない。

dwReserved2

このパラメータは予約済みである。この値は0でなければならない。

dwFlags

バッファの再生方法を指定する。以下の値で示される。

DSBPLAY_LOOPING

	オーディオ・バッファの終了位置まで到達すると、バッファの開始位置から再び再生を行い、停止を明示するまで繰り返す。このフラグはプライマリ・サウンド・バッファの再生中に設定する必要がある。
このメソッドにより、セカンダリ・サウンド・バッファはプライマリ・バッファ内でミキシングされてからサウンド・デバイスへ送られる。これが最初に再生されるバッファである場合、内部でプライマリ・バッファを作成し、そのバッファの再生を開始する。アプリケーションはプライマリ・バッファを直接再生する必要はない。

もしメソッドで指定されたバッファがすでに再生中だった場合、メソッドの呼び出しは成功し、バッファは再生を続ける。ただし録音・再生機能が定義されたフラグは一番最近に定義されたフラグに取って代わられる。

プライマリ・バッファはDSBPLAY_LOOPINGフラグへの設定により再生しなければならない。

プライマリ・サウンド・バッファはこのメソッドによってサウンドデバイスの再生を開始する。アプリケーションが 書き込み優先協調レベルに設定されている場合、プライマリ・バッファ内のオーディオ・データをサウンド・デバイスへと送る。しかし、アプリケーションが他の協調レベルに設定されている場合は、このメソッドによるセカンダリ・バッファの再生ががひとつも行われていなくてもプライマリ・バッファが再生される。この場合は無音となる。この場合、サウンドが順次に再生・停止するときの処理オーバーヘッドを最小限にすることができる。これは、停止、再生をセカンダリ・バッファ間で行うよりも、より連続的にバッファが再生されるためである。

Note

どのサウンド・バッファにおいても、アプリケーションはこのメソッドが呼び出される前にIDirectSound::SetCooperativeLevel メソッドを呼び出し、協調レベルを指定する必要がある。通常はDSSCL_NORMALを指定する。もしIDirectSound::SetCooperativeLevelメソッドが呼び出されていないと、 IDirectSoundBuffer::PlayメソッドはDSERR_PRIOLEVELNEEDEDエラー値を返す。

参照　IDirectSoundBuffer, IDirectSound::SetCooperativeLevel


IDirectSoundBuffer::Restore

HRESULT Restore();

特定のDirectSoundBufferオブジェクトの、失われたサウンド・バッファに対するメモリの割り当てをリストアする。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_BUFFERLOST

DSERR_INVALIDCALL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

アプリケーションが入力フォーカスを持っていないとDirectSoundBuffer::Restoreは成功しない。たとえば、入力フォーカスを持つアプリケーションがDSSCL_WRITEPRIMARY協調レベルに設定されている場合、他のすべてのアプリケーションはバッファのリストアができない状態になる。同様にDSSCL_WRITEPRIMARY書き込み優先協調レベルのアプリケーションがプライマリ・サウンド・バッファをリストアするためには、入力フォーカスを持っている必要がある。

DirectSoundがバッファ・メモリをリストアした場合、有効なサウンド・データの再書きこみが必要である。DirectSoundはメモリの内容をリストアすることはできず、メモリのリストアのみを行う。

IDirectSoundBuffer::Lockもしくは IDirectSoundBuffer::Playメソッドの呼び出し時にバッファを指定しておくと、そのバッファが失われたという知らせを受けることができる。これらのメソッドは、バッファが失われた場合はDSERR_BUFFERLOSTを返す。IDirectSoundBuffer::GetStatusメソッドもまた、サウンド・バッファの状態の取得とDSBSTATUS_BUFFERLOSTフラグのテストに使用される。

参照　IDirectSoundBuffer, IDirectSoundBuffer::Lock, IDirectSoundBuffer::Play, IDirectSoundBuffer::GetStatus


IDirectSoundBuffer::SetCurrentPosition

HRESULT SetCurrentPosition(DWORD dwNewPosition);

現在の再生カーソルをセカンダリ・サウンド・バッファの指定の位置へ移動する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_INVALIDCALL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

dwNewPosition

サウンド・バッファの再生に使用されるバイト単位のオフセット値。

このメソッドはプライマリ・サウンド・バッファ上では呼び出せない。

バッファが再生中の場合は、即座に新規の位置へ移動して継続される。停止中の場合は、 IDirectSoundBuffer::Playメソッドが呼び出しされたあとで、新規の位置から開始する。

参照　IDirectSoundBuffer, IDirectSoundBuffer::GetCurrentPosition, IDirectSoundBuffer::Play


IDirectSoundBuffer::SetFormat

HRESULT SetFormat(LPWAVEFORMATEX lpfxFormat);

プライマリ・サウンド・バッファのアプリケーションでの形式を設定する。このアプリケーションが入力フォーカスを持つたびにDirectSoundはプライマリ・バッファを特定の形式に設定する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_BADFORMAT

DSERR_INVALIDCALL

DSERR_INVALIDPARAM

DSERR_OUTOFMEMORY

DSERR_PRIOLEVELNEEDED

DSERR_UNSUPPORTED

lpfxFormat

WAVEFORMATEX構造体へのポインタ。プライマリ・サウンド・バッファの新しい形式を表す。

書き込み優先協調レベルでアクセスされているプライマリ・バッファ上でこのメソッドを呼び出す場合、バッファをIDirectSoundBuffer::SetFormatが呼び出される前に停止しておかなければならない。このメソッドが書き込み優先以外の協調レベル上で呼び出された場合は、DirectSoundは内部でプライマリ・バッファを停止し、形式を変更し、プライマリをリスタートする。アプリケーションがこれらの作業を明示する必要はない。

要求されたPCM形式をハードウェアが直接サポートしていない場合、このメソッドの呼び出しは失敗する。アプリケーションがDSSCL_NORMAL協調レベルを持っている場合も失敗する。

セカンダリ・サウンド・バッファの形式を変更する必要が生じた場合、新規DirectSoundBufferオブジェクトを新しい形式で作成する必要がある。

DirectSoundはPCM形式をサポートしている。現在は圧縮形式はサポートしていない。

参照　IDirectSoundBuffer, IDirectSoundBuffer::GetFormat


IDirectSoundBuffer::SetFrequency

HRESULT SetFrequency(DWORD dwFrequency);

サンプリング・オーディオが再生されている位置の周波数を設定する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_CONTROLUNAVAIL

DSERR_GENERIC

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

dwFrequency

サンプリング・オーディオが再生されている位置の周波数。単位はヘルツ(Hz)。値の範囲は100から 100,000までとなる。

値が0の場合、周波数は現在のバッファ形式にリセットされる。この形式はIDirectSound::CreateSoundBufferメソッドで指定されている。

周波数の増幅・減衰により、オーディオ・データの供給ピッチが変わる。このメソッドはバッファの形式には影響しない。

参照　IDirectSoundBuffer, IDirectSound::CreateSoundBuffer, IDirectSoundBuffer::GetFrequency, IDirectSoundBuffer::Play, IDirectSoundBuffer::SetFormat


IDirectSoundBuffer::SetPan

HRESULT SetPan(LONG lPan);

左右のチャンネルの相対ボリュームを設定する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_CONTROLUNAVAIL

DSERR_GENERIC

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

lPan

左右のチャンネルの相対ボリュームを取得する。この値の範囲は-10,000から 10,000であり、100dBの範囲で指定する。

lPanの自然なボリュームは0である。これは両方のチャンネルがフルボリュームであることを示す(0dB弱くなっている)。これ以外の設定はどれも、片方がフルボリュームで、もう片方が弱くなっている。たとえば、-2173のパンは、左チャンネルがフルボリュームで、右チャンネルが21.73 dB弱くなっていることを意味する。同様に870のパンは、左チャンネルが8.7 dB弱くなっており、右チャンネルがフルボリュームであることを意味する。

-10,000のパンは、右チャンネルが無音で、サウンドが「左側のみ」であることを意味する。一方、10,000のパンは、左チャンネルが無音で、サウンドが「右側のみ」であることを意味する。パン制御はボリューム・コントロールに累積して動作する。

参照　IDirectSoundBuffer, IDirectSoundBuffer::GetPan, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::SetVolume

HRESULT SetVolume(LONG lVolume);

サウンド・バッファのボリュームを変更する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_CONTROLUNAVAIL

DSERR_GENERIC

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

lVolume

サウンド・バッファに要求される新規のボリューム。値の範囲は0(0dB(dB)。ボリューム変更なし)から-10,000（-100Db。実際は無音）までになる。DirectSoundは現在の増幅をサポートしていない。

ボリュームの単位は100dBであり、0がストリームのオリジナルのボリュームである。

正の値のデシベルは増幅を表し、負の値は減衰を表している。デシベルの尺度は聴力に対して対数で対応している。10dB減衰するとはバッファのサウンドは半分になり、20dB減衰すると4分の1になる。現在のDirectSoundは増幅をサポートしていない。

パン制御はボリューム・コントロールに累積して動作する。

参照　IDirectSoundBuffer, IDirectSoundBuffer::GetPan, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::SetPan


IDirectSoundBuffer::Stop

HRESULT Stop();

サウンド・バッファの再生を停止する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

セカンダリ・サウンド・バッファに対して、 IDirectSoundBuffer::Stopは現在のバッファの位置を、前回のサンプル再生に引き続くサンプルへと設定する。これはIDirectSoundBuffer::Playメソッドがバッファに呼び出された場合にその再生を停止したところから続けるということである。

アプリケーションが プライマリ・サウンド・バッファに対して、書き込み優先 レベルを持っているなら、このメソッドはバッファを停止して、現在のポジションを０（バッファの始め）にリセットする必要がある。 これはバッファの先頭からしか再生が行えないサウンド・カードが大勢を占めているためである。

しかし、プライマリ・バッファ上で IDirectSoundBuffer::Stop が呼び出され、アプリケーションが書き込み優先 以外の協調レベルを持っているならば、このメソッドは IDirectSoundBuffer::Playの効果を無効にするだけである。 セカンダリ・バッファが再生されていない場合には、プライマリ・バッファを停止するように設定する。 他のバッファがここで（あるいは他のアプリケーションで）再生されているなら、それらが停止するまでプライマリ・バッファも実際には停止しない。 たとえバッファが０dBでサウンド・データを再生している場合であっても処理のオーバーヘッドは消費されるのであるから、このメソッドでプライマリ・バッファで再生することは、有用なのである。

参照　IDirectSoundBuffer, IDirectSoundBuffer::Play


IDirectSoundBuffer::Unlock

HRESULT Unlock(LPVOID lpvAudioPtr1, DWORD dwAudioBytes1,

    LPVOID lpvAudioPtr2, DWORD dwAudioBytes2);

サウンド・バッファのロックを解放する。

成功すればDS_OK 、失敗すれば次のエラーコードを返す。

DSERR_INVALIDCALL

DSERR_INVALIDPARAM

DSERR_PRIOLEVELNEEDED

lpvAudioPtr1

IDirectSoundBuffer::Lockメソッドの lplpvAudioPtr1パラメータで取得される変数へのポインタ。

dwAudioBytes1

実際にlpvAudioPtr1パラメータに書きこまれたバイト数。IDirectSoundBuffer::Lockメソッドによって返されたバイト数を越えるべきではない。

lpvAudioPtr2

IDirectSoundBuffer::Lockメソッドの lplpvAudioPtr2 パラメータで取得される変数へのポインタ。

dwAudioBytes2

実際にlpvAudioPtr2 パラメータに書きこまれたバイト数。IDirectSoundBuffer::Lockメソッドによって返されたバイト数を越えるべきではない。

アプリケーションは IDirectSoundBuffer::Lockメソッドで返された両方のポインタ lpvAudioPtr1 と lpvAudioPtr2を、正しく対にして、 IDirectSoundBuffer::Unlockに渡さなければならない。 ２番目のポインタは、たとえ０バイトが２番目のポインタに書きこまれたとしても必要である。

アプリケーションは実際に書きこまれたバイトの数を、dwAudioBytes1 と dwAudioBytes2 パラメータのふたつのポインタに渡さなくてはならない。

サウンド・バッファを長期間ロックしたままにしないこと。

参照　IDirectSoundBuffer, IDirectSoundBuffer::GetCurrentPosition, IDirectSoundBuffer::Lock


構造体


DS3DBUFFER

typedef struct {

    DWORD     dwSize;

    D3DVECTOR  vPosition;

    D3DVECTOR  vVelocity;

    DWORD     dwInsideConeAngle;

    DWORD     dwOutsideConeAngle;

    D3DVECTOR  vConeOrientation;

    LONG      lConeOutsideVolume;

    D3DVALUE     flMinDistance;

    D3DVALUE     flMaxDistance;

    DWORD     dwMode;

} DS3DBUFFER;

３Ｄサウンド・バッファの場所、方向および動作の、個別記述に必要なすべての情報を含んでいる。この構造体は IDirectSound3DBuffer::GetAllParametersおよび IDirectSound3DBuffer::SetAllParametersメソッドとともに使用される。

dwSize

この構造体のバイト単位のサイズ。

vPosition

３Ｄサウンド・バッファの現在の位置を記述する D3DVECTOR 構造体。

vVelocity

３Ｄサウンド・バッファの現在の速度を記述する D3DVECTOR 構造体。

dwInsideConeAngle

内側サウンド・プロジェクション・コーンの角度。

dwOutsideConeAngle

外側サウンド・プロジェクション・コーンの角度。

vConeOrientation

この３Ｄバッファサウンド・プロジェクション・コーンの現在の方向を記述する D3DVECTOR 構造体。

lConeOutsideVolume

外部ボリュームのコーン。

flMinDistance

最小距離。

flMaxDistance

最大距離。

dwMode

３Ｄサウンド処理モード。次の値で示される。

DS3DMODE_DISABLE

	3Dサウンド処理は無効になる。サウンドはリスナーの頭の中心から聞こえるように感じる。

DS3DMODE_HEADRELATIVE

	サウンドパラメータ(位置、速度、方向)はリスナーのパラメータと相対関係にある。このモードでは、サウンドの絶対パラメータはリスナー・パラメータが変更されたときに自動的に更新されるので、相対パラメータは変わらないままである。

DS3DMODE_NORMAL

	標準の処理。これがデフォルトモードになっている。


DS3DLISTENER

typedef struct {

    DWORD      dwSize;

    D3DVECTOR  vPosition;

    D3DVECTOR  vVelocity;

    D3DVECTOR  vOrientFront;

    D3DVECTOR  vOrientTop;

    D3DVALUE   flDistanceFactor;

    D3DVALUE   flRolloffFactor;

    D3DVALUE   flDopplerFactor;

} DS3DLISTENER;

３Ｄワールドパラメータおよびリスナーの位置を、個々に記述するために必要なすべての情報を含んでいる。この構造体は IDirectSound3DListener::GetAllParameters および IDirectSound3DListener::SetAllParameters メソッドとともに使用される。

dwSize

この構造体のバイト単位のサイズ。

vPosition, vVelocity, vOrientFront, および vOrientTop

リスナーの位置、速度、前方向および上方向それぞれを記述する D3DVECTOR 構造体。

flDistanceFactor,flRolloffFactor, およびflDopplerFactor

それぞれ現在の距離、ロールオフおよびドップラー要素。


DSBCAPS

typedef struct _DSBCAPS {

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwBufferBytes;

    DWORD dwUnlockTransferRate;

    DWORD dwPlayCpuOverhead;

} DSBCAPS, *LPDSBCAPS;

IDirectSoundBuffer::GetCaps メソッドにより使用されるDirectSound バッファ・オブジェクトの能力を指定する。

dwSize

この構造体のバイト単位のサイズ。

dwFlags

バッファ・オブジェクト能力を指定するフラグ。

DSBCAPS_CTRL3D

	バッファは３Ｄ制御を使用するプライマリ・バッファである。

DSBCAPS_CTRLFREQUENCY

	バッファは周波数制御能力を持たなくてはならない。

DSBCAPS_CTRLPAN

	バッファはパン制御能力を持たなくてはならない。

DSBCAPS_CTRLVOLUME

	バッファはボリューム制御能力を持たなくてはならない。

DSBCAPS_GETCURRENTPOSITION2

	IDirectSoundBuffer::GetCurrentPosition が再生カーソルの新しい動作を使用するべきであることを示す。 DirectX １のDirectSound では、書きこみカーソルの直後にあった再生カーソルはサウンド・カードがエミュレートした音は、実際の音よりも際立って進んでいた。現在では DSBCAPS_GETCURRENTPOSITION2フラグが指定されれば、アプリケーションによるより正確な再生位置の取得が可能になった。 このフラグが指定されない状態であれば過去の動作が互換性のために維持されている。 このフラグが影響を与えるのはサウンド・カード・エミュレートへのみであることに注意すること。もし DirectSound ドライバがあれば、DirectXのあらゆるバージョンのDirectSoundでの再生カーソルは正確になる。

DSBCAPS_GLOBALFOCUS

	バッファはグローバルなサウンド・バッファである。 このフラグをセットすることにより、もしユーザが他のアプリケーションにフォーカスを切り替えたり、新しいアプリケーションがDirectSound を使う場合、 DirectSound を使っているアプリケーションはそのバッファを再生し続けることができる。 しかし、フォーカスを DSSCL_EXCLUSIVE あるいは DSSCL_WRITEPRIMARYフラグの協調レベルを使うDirectSound アプリケーションに切り替えた場合は例外である。 この場合、他のアプリケーションからのグローバルな音は聞こえなくなる。

DSBCAPS_LOCHARDWARE

	DSBCAPS_STATIC が指定されなくても、バッファは強制的にハードウェア・ミキシングを使用する。 もしデバイスがハードウェア・ミキシングをサポートしていないか、あるいは必要とされるハードウェア・メモリが利用不可能な場合は、 IDirectSound::CreateSoundBuffer の呼び出しは失敗する。 アプリケーションはミキシング・チャネルがこのバッファのために利用可能であることを保証する必要がある。

DSBCAPS_LOCSOFTWARE

	DSBCAPS_STATIC が指定されハードウェア・リソースが利用可能であっても、バッファは強制的にソフトウェア・メモリに格納され、ソフトウェア・ミキシングを使用する。

DSBCAPS_PRIMARYBUFFER

	バッファがプライマリ・サウンド・バッファであることを表す。 もしこの値が指定されないなら、セカンダリ・サウンド・バッファが作られる。

DSBCAPS_STATIC

	バッファがスタティック・サウンド・データのために使われることを表す。 一般にこれらのバッファは１度ロードされて、そして何度も再生される。 これらのバッファはハードウェア・メモリを要求する。

DSBCAPS_STICKYFOCUS

	サウンド・バッファのフォーカスの動作を変える。 このフラグはIDirectSound::CreateSoundBufferの呼び出しで指定することができる。 このフラグがセットされると、もしユーザが他のDirectSound を使っていないアプリケーションに切り替えても、 DirectSound を使っているアプリケーションはそのスティッキー・フォーカス・バッファで再生し続けることができる。 この状態でアプリケーションの標準バッファは消音されるが、スティッキー・フォーカス・バッファは鳴り続ける。たとえばユーザがワード あるいはエクセルでタイプする間にサウンドトラックを聞くような時、ゲーム以外のアプリケーション、たとえば映画再生 (ActiveMovie�)などで役立つ。しかし、ユーザがもし他の DirectSound アプリケーションに切り替えるなら、標準とスティッキー・フォーカス両方のサウンド・バッファがすべて消音される。
dwBufferBytes

このバッファのバイト単位のサイズ。

dwUnlockTransferRate

IDirectSoundBuffer::Unlockが呼び出されたときにバッファ・メモリにデータが転送されるレートを、１秒毎のkバイトで指定する。ハイパフォーマンスなアプリケーションが IDirectSoundBuffer::Unlockを実行するために要する時間を決定するのに、この値を使うことができる 。 システムメモリに配置されているソフトウェア・バッファのためのレートは、処理が不要なので非常に高い。 ハードウェア・バッファのためのレートは、バッファがサウンド・カードにロードされる可能性があるため、より遅くなる可能性がある。そして転送速度が限定される場合がある。

dwPlayCpuOverhead

このサウンド・バッファをミキシングするのに必要なオーバーヘッドを主な処理サイクルのパーセンテージで指定する。 ハードウェア・バッファにおいては、このメンバはミキシングがサウンド・デバイスによって行われるので、０である。 ソフトウェア・バッファにおいては、このメンバはバッファ・フォーマットとシステム・プロセッサの速度に依存される。

DSBCAPS 構造体は IDirectSound::CreateSoundBuffer メソッドに渡される DSBUFFERDESC 構造体に類似して見られる情報を含んでいて、追加の情報をいくつか持っている。 追加情報には、バッファ（ハードウェアあるいはソフトウェア）の位置といくつかのコスト単位（ハードウェアに位置しているならバッファをロードする時間、ソフトウェアでバッファがミキシングされるなら再生するときの処理のオーバーヘッドのような情報）が含まれる。

DSBCAPS 構造体の dwFlags メンバが DSBUFFERDESC 構造体によって使われた同じフラグを含んでいることに注意すること。 唯一の相違は DSBCAPS 構造体において、DSBCAPS_LOCHARDWARE あるいは DSBCAPS_LOCSOFTWARE フラグがバッファメモリの場所によって指定されるということである。 DSBUFFERDESC 構造体で、これらのフラグは任意であり、そしてハードウェアあるいはソフトウェアへのバッファの配置を強制するために使われる。

参照　IDirectSound::CreateSoundBuffer, IDirectSoundBuffer::GetCaps


DSBUFFERDESC

typedef struct _DSBUFFERDESC{

    DWORD           dwSize;

    DWORD           dwFlags;

    DWORD           dwBufferBytes;

    DWORD           dwReserved;

    LPWAVEFORMATEX  lpwfxFormat;

} DSBUFFERDESC, *LPDSBUFFERDESC;

新しい DirectSoundBuffer オブジェクトの大切な特徴を示す。 この構造体は IDirectSound::CreateSoundBuffer メソッドによって使われる。

dwSize

この構造体のバイト単位のサイズ。

dwFlags

新しい DirectSoundBuffer オブジェクトを作るときに含む能力を識別する。 以下のひとつあるいは複数を指定すること。

DSBCAPS_CTRL3D

	バッファは３Ｄ制御を使うプライマリ・バッファである。

DSBCAPS_CTRLALL

	バッファはすべての制御能力を持たなくてはならない。

DSBCAPS_CTRLDEFAULT

	バッファはデフォルトのコントロール・オプションを持つべきである。 これはDSBCAPS_CTRLPAN 、 DSBCAPS_CTRLVOLUMEおよびDSBCAPS_CTRLFREQUENCYフラグを指定することと同じである。

DSBCAPS_CTRLFREQUENCY

	バッファは周波数制御能力を持たなくてはならない。

DSBCAPS_CTRLPAN

	バッファはパン制御能力を持たなくてはならない。

DSBCAPS_CTRLVOLUME

	バッファはボリューム制御能力を持たなくてはならない。

DSBCAPS_GETCURRENTPOSITION2

	IDirectSoundBuffer::GetCurrentPosition が再生カーソルの新しい設定を使用するべきであることを示す。 DirectX １のDirectSound では、書きこみカーソルの直後にあった再生カーソルはサウンド・カードがエミュレートした音は、実際の音よりも際立って進んでいた。現在では DSBCAPS_GETCURRENTPOSITION2フラグが指定され、アプリケーションによるより正確な再生位置の取得が可能になった。 このフラグが指定されない状態であれば過去の動作が互換性のために維持されている。 このフラグが影響を与えるのはサウンド・カード・エミュレートへのみであることに注意すること。もしDirectSound ドライバがあれば、DirectXのあらゆるバージョンのDirectSoundでの再生カーソルは正確である。

DSBCAPS_GLOBALFOCUS

バッファはグローバルなサウンド・バッファである。 このフラグをセットすることにより、もしユーザが他のアプリケーションにフォーカスを切り替えたり、新しいアプリケーションがDirectSound を使う場合、 DirectSound を使っているアプリケーションはそのバッファを再生し続けることができる。 しかし、フォーカスを DSSCL_EXCLUSIVE あるいは DSSCL_WRITEPRIMARYフラグの協調レベルを使うDirectSound アプリケーションに切り替えた場合は例外である。 この場合、他のアプリケーションからのグローバルな音は聞こえなくなる。

DSBCAPS_LOCHARDWARE

DSBCAPS_STATIC が指定されなくても、バッファは強制的にハードウェア・ミキシングを使用する。 もしデバイスがハードウェア・ミキシングをサポートしていないか、あるいは必要とされるハードウェア・メモリが利用不可能な場合は、 IDirectSound::CreateSoundBuffer の呼び出しは失敗する。 アプリケーションはミキシング・チャネルがこのバッファのために利用可能であることを保証する必要がある。

DSBCAPS_LOCSOFTWARE

DSBCAPS_STATIC が指定されハードウェア・リソースが利用可能であっても、バッファは強制的にソフトウェア・メモリに格納され、ソフトウェア・ミキシングを使用する。

DSBCAPS_PRIMARYBUFFER

バッファがプライマリ・サウンド・バッファであることを表す。 もしこの値が指定されないなら、セカンダリ・サウンド・バッファが作られる。

DSBCAPS_STATIC

バッファがスタティック・サウンド・データのために使われることを表す。 一般にこれらのバッファは１度ロードされて、そして何度も再生される。 これらのバッファはハードウェア・メモリを要求する。

DSBCAPS_STICKYFOCUS

サウンド・バッファのフォーカスの動作を変える。 このフラグはIDirectSound::CreateSoundBufferの呼び出しで指定することができる。 このフラグがセットされると、もしユーザが他のDirectSound を使っていないアプリケーションに切り替えても、 DirectSound を使っているアプリケーションはそのスティッキー・フォーカス・バッファで再生し続けることができる。 この状態でアプリケーションの標準バッファは消音されるが、スティッキー・フォーカス・バッファは鳴り続ける。たとえばユーザがワード あるいはエクセルでタイプする間にサウンドトラックを聞くような時、ゲーム以外のアプリケーション、たとえば映画再生 (ActiveMovie�)などで役立つ。しかし、ユーザがもし他の DirectSound アプリケーションに切り替えるなら、標準とスティッキー・フォーカス両方のサウンド・バッファがすべて消音される。

dwBufferBytes

このバッファのバイト単位のサイズ。この値はプライマリ・バッファを作るときは０でなければならない。

dwReserved

このメンバは予約されている。 使用できない。

lpwfxFormat

バッファのためにwaveフォーマットを指定している構造体へのポインタ。 この値はプライマリ・バッファならNULLでなければならない。 アプリケーションはプライマリ・バッファのフォーマットをセットするために IDirectSoundBuffer::SetFormat を使うことができる。

dwFlags メンバで使われる DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE フラグはオプションであり、そして相互に排他的である。 DSBCAPS_LOCHARDWARE はバッファをサウンド・カードのメモリに配置する。 DSBCAPS_LOCSOFTWARE は可能であるなら、バッファをメインシステム・メモリに配置する。

これらのフラグは DSBCAPS 構造体の dwFlags メンバでも使われる。そこでは、指定されたフラグが DirectSoundBuffer オブジェクトの実際の場所を示す。

プライマリ・バッファを作るとき、アプリケーションでは dwBufferBytes メンバを０にセットする。 DirectSound は使用中の特定なサウンド・デバイスであるので最適なバッファの大きさを決定する。作成されたプライマリ・バッファの大きさを取得するには、 IDirectSoundBuffer::GetCapsを呼び出す。

参照　IDirectSound::CreateSoundBuffer


DSCAPS

typedef struct _DSCAPS {

    DWORD  dwSize;

    DWORD  dwFlags;

    DWORD  dwMinSecondarySampleRate;

    DWORD  dwMaxSecondarySampleRate;

    DWORD  dwPrimaryBuffers;

    DWORD  dwMaxHwMixingAllBuffers;

    DWORD  dwMaxHwMixingStaticBuffers;

    DWORD  dwMaxHwMixingStreamingBuffers;

    DWORD  dwFreeHwMixingAllBuffers;

    DWORD  dwFreeHwMixingStaticBuffers;

    DWORD  dwFreeHwMixingStreamingBuffers;

    DWORD  dwMaxHw3DAllBuffers;

    DWORD  dwMaxHw3DStaticBuffers;

    DWORD  dwMaxHw3DStreamingBuffers;

    DWORD  dwFreeHw3DAllBuffers;

    DWORD  dwFreeHw3DStaticBuffers;

    DWORD  dwFreeHw3DStreamingBuffers;

    DWORD  dwTotalHwMemBytes;

    DWORD  dwFreeHwMemBytes;

    DWORD  dwMaxContigFreeHwMemBytes;

    DWORD  dwUnlockTransferRateHwBuffers;

    DWORD  dwPlayCpuOverheadSwBuffers;

    DWORD  dwReserved1;

    DWORD  dwReserved2;

} DSCAPS, *LPDSCAPS;

IDirectSound::GetCapsメソッドによって使用される DirectSound デバイスの能力を指定する。

dwSize

この構造体のバイト単位のサイズ。

dwFlags

デバイスの能力を指定する。 以下のひとつあるいは複数が指定できる。

DSCAPS_CERTIFIED

	このドライバはMicrosoftによって試験され保証されている。

DSCAPS_CONTINUOUSRATE

	デバイスはdwMinSecondarySampleRate とdwMaxSecondarySampleRate メンバ値の間ですべてのサンプリングレポートをサポートする。 一般にこれは実際の出力レートが要求する周波数の＋ ／ －１０ヘルツ（ Hz ）  の中であることを意味する。

DSCAPS_EMULDRIVER

	デバイスにはインストールされたDirectSound ドライバはない。それはウェーブフォーム・オーディオ機能を通してエミュレートされている。 実行能力の低下が予想される。

DSCAPS_PRIMARY16BIT

	デバイスは１６ビットサンプリングでプライマリ・サウンド・バッファをサポートする。

DSCAPS_PRIMARY8BIT

	デバイスは８ビットサンプリングでプライマリ・バッファをサポートする。

DSCAPS_PRIMARYMONO

	デバイスは単音プライマリ・バッファをサポート する。

DSCAPS_PRIMARYSTEREO

	デバイスはステレオプライマリ・バッファをサポートする。

DSCAPS_SECONDARY16BIT

	デバイスは16ビットサンプリングでハードウェア・ミキシング・セカンダリ・サウンド・バッファをサポートする。

DSCAPS_SECONDARY8BIT

	デバイスは８ビットサンプルでハードウェア・ミキシング・セカンダリ・サウンドをサポートする。

DSCAPS_SECONDARYMONO

	デバイスはハードウェア・ミキシング単音セカンダリ・サウンドをサポートする。

DSCAPS_SECONDARYSTEREO

	デバイスはハードウェア・ミキシング・ステレオ・セカンダリ・サウンドをサポートする。
dwMinSecondarySampleRate および dwMaxSecondarySampleRate

このデバイスのハードウェア・セカンダリ・バッファでサポートされる最低・最高のサンプリングレートを指定。

dwPrimaryBuffers

サポートされるプライマリ・バッファの数。今回のリリースでは１である。

dwMaxHwMixingAllBuffers

ハードウェアでミキシングできるバッファの合計の数を指定する。 このメンバは dwMaxHwMixingStaticBuffers と dwMaxHwMixingStreamingBuffers の合計より少ない。 リソースのトレードオフがしばしば発生する。

dwMaxHwMixingStaticBuffers

スタティック・サウンド・バッファの最大数を指定する。

dwMaxHwMixingStreamingBuffers

ストリーム・サウンド・バッファの最大数を指定する。

dwFreeHwMixingAllBuffers, dwFreeHwMixingStaticBuffers, および dwFreeHwMixingStreamingBuffers

割り当てられていないデバイスの、ハードウェア・ミキシング能力の設定。 アプリケーションは、ハードウェア・リソースがセカンダリ・サウンド・バッファの割り当てのために利用可能であるかどうか判断するために、これらの値を使うことができる。 同じくこれらの値を最大のミキシング能力を指定するメンバと比較すれば、すでに割り当てられているリソースを特定することができる。

dwMaxHw3DAllBuffers, dwMaxHw3DStaticBuffers, および dwMaxHw3DStreamingBuffers

デバイスのハードウェア３Ｄ定位能力の記述。 これらはすべて最初のリリースのため０である。

dwFreeHw3DAllBuffers, dwFreeHw3DStaticBuffers, および dwFreeHw3DStreamingBuffers

割り当てられていないデバイスの、ハードウェア３Ｄ定位決め能力の記述。これらはすべて最初のリリースのため０である。

dwTotalHwMemBytes

スタティック・サウンド・バッファを格納するサウンド・カード上のメモリ容量のバイト単位のサイズ。

dwFreeHwMemBytes

サウンド・カード上のフリーメモリのバイト単位のサイズ。

dwMaxContigFreeHwMemBytes

サウンド・カード上のフリーメモリで、最も大きい連続ブロックのバイト単位のサイズ。

dwUnlockTransferRateHwBuffers

ハードウェアスタティック・サウンド・バッファ（オンボードサウンドメモリに配置されている）にデータが転送されるレートを１秒毎のk

バイトで記述する。このレートとバイトでの転送量は IDirectSoundBuffer::Unlockメソッド呼び出しの継続時間を決定する。

dwPlayCpuOverheadSwBuffers

ソフトウェア・バッファ（メインシステムメモリに配置している）をミキシングするために必要な、CPUのパーセンテージの処理オーバーヘッドの値。 これはバスタイプ、プロセッサタイプおよびクロック速度に依存して変化する。

ロックされていないソフトウェア・バッファの転送レートは、データをどこにも転送する必要がないため０である。 同様にハードウェアバッファの再生オーバーヘッドは、ミキシングがサウンド・デバイスによって処理されるため０である。

dwReserved1 および dwReserved2

これらのメンバは予約されている。 使用できない。

参照　IDirectSound::GetCaps


返値

エラーは負数値で表され組み合わされることはない。この表は、すべての IDirectSound と IDirectSoundBuffer メソッドにより返される値の一覧である。個々のメソッドの返すエラーコードのリストについては、そのメソッドの記述を参照すること。

DS_OK

	要求は成功し完了した。

DSERR_ALLOCATED

	要求は優先レベルのようなリソースが他の呼び出しによってすでに使用中であるため失敗した。

DSERR_ALREADYINITIALIZED

	オブジェクトはすでに初期化されている。

DSERR_BADFORMAT

	指定されたwaveはサポートされない。

DSERR_BUFFERLOST

	バッファメモリが失われたため、リストアしなければならない。

DSERR_CONTROLUNAVAIL

	呼び出しによって要求する制御（ボリューム、パンなど）は利用可能ではない。

DSERR_GENERIC

	未確定なエラーが DirectSound サブシステムの中で起こった。

DSERR_INVALIDCALL

	この関数はこのオブジェクトの現在の状態において有効ではない。

DSERR_INVALIDPARAM

	無効なパラメータが関数に渡された。

DSERR_NOAGGREGATION

	オブジェクトはCOM集成化をサポートしない。

DSERR_NODRIVER

	使用するサウンド・ドライバが利用できない。

DSERR_OTHERAPPHASPRIO

	この値は過去のものであり使用されない。

DSERR_OUTOFMEMORY

	DirectSound サブシステムは呼び出しの要求を完了するために十分なメモリを割り当てることができなかった。

DSERR_PRIOLEVELNEEDED

	呼び出しは関数が成功するために必要とする優先レベルを持っていない。

DSERR_UNINITIALIZED

	他のメソッドが呼び出される前にIDirectSound::Initialize メソッドが呼び出されなかったか、あるいは呼び出しが成功しなかった。

DSERR_UNSUPPORTED

	呼び出した関数はここではサポートされていない。


DirectPlayについて

Microsoft Windowsｮオペレーティング・システム用のMicrosoftｮ DirectPlayｮアプリケーション・プログラミング・インターフェイス (API) は、アプリケーションからの通信サービスへのアクセスを単純化するソフトウェア・インターフェイスである。DirectPlay は、トランスポートやプロトコル、あるいはオンライン・サービスに依存しない通信方法を、アプリケーションだけでなく、ロビー・サーバーにも提供するテクノロジとなっている。

リアル・プレイヤたちが対戦するようなアプリケーション（特にゲーム）は、もっと興味をそそるものであっていい。パーソナル・コンピュータは、過去のどんなゲームのプラットフォームよりも優れた接続オプションを持っているのである。DirectPlayは、これらの各接続方法の違いに対処する必要性を取り除き、明確な一般化された通信機能を提供する。 DirectPlay を用いれば、多様な接続方法をインプリメントする際の複雑さを気にせず、優れたアプリケーションを作り出すことに全力を注ぐことができる。


DirectPlayアーキテクチャ

DirectPlayは、単純な送受信通信モデルを使用して、マルチプレイヤ・ アプリケーションの要求に対応した接続APIをインプリメントしている。DirectPlayアーキテクチャは、DirectPlayLobby、DirectPlay、DirectPlayサービス・プロバイダの３つのコンポーネントから構成される。次の図は、これらのコンポーネントと、それに対応するインターフェイスとの関係を示している。

このセクションでは、これらのコンポーネントについての一般的な情報を説明する。

DirectPlayコンポーネント

DirectPlayLobbyコンポーネント

サービス・プロバイダ


DirectPlayコンポーネント

DirectPlayはMicrosoftによって提供され、アプリケーションの共通インターフェイスを公開する。 DirectPlayインターフェイスは、複雑さや、任意の通信リンクを確立するために必要な特殊なタスクを、DirectPlayサービス・プロバイダの内部に隠蔽する。 DirectPlayを利用するアプリケーションは、通信媒体のパフォーマンスのみを配慮すればよく、その媒体を提供するモデムやネットワーク、あるいはオンライン・サービスについて気にする必要はない。

DirectPlayは、ユーザのシステム上にインストールされたどんな DirectPlayサービス・プロバイダにも動的に結合する。アプリケーションは、DirectPlayオブジェクトと互いにアクセスする。 DirectPlayオブジェクトは、使用可能なDirectPlayサービス・プロバイダのひとつと互いに通信し、選択されたサービス・プロバイダは、トランスポートやプロトコルとやり取りをする。

DirectPlay APIは、COMインターフェイスを通してアプリケーションに公開されている。 DirectPlayバージョン3では、IDirectPlay2およびIDirectPlay2Aのふたつのインターフェイスが利用できる。IDirectPlay2AがANSI文字列を使うのに対し、IDirectPlay2では、すべてのDirectPlay構造体でUnicode文字列を使う。 IDirectPlayインターフェイスは、DirectPlayバージョン1と2で書かれたアプリケーションとの下位互換性のためにデフォルトのインターフェイスとして用意されており、ANSI文字列のみを使用する。

アプリケーションはひとつのDirectPlayオブジェクトのインスタンスを作成し、たとえアプリケーションが複数のプレイヤを管理するとしても、そのオブジェクトを通してすべての通信を実行する。パフォーマンスを維持するため、DirectPlayオブジェクトだけが直接お互いと通信を行う。メッセージを受信した後、DirectPlayオブジェクトは、ローカルなアプリケーションが作成したすべてのプレイヤのためにそのメッセージを（もし必要ならば）複製し、メッセージ・キューに追加する。

このバージョンのDirectPlayは、ピア・ツー・ピアのゲーム・パラダイムをサポートする 。 つまり、すべてのプレイヤは、セッション中の他のいかなるプレイヤにでもメッセージを送信することができる。 セッション・ホストは、セッションに加わる新しいコンピュータを調停し、新しいプレイヤとグループが作成されるときにID番号を割り当てる。開発者は、クライアント／サーバ・モデルでゲームを設計することができる。クライアント／サーバ・モデルでは、すべてのメッセージがホスト・コンピュータ上のサーバ・プレイヤに送られる。するとサーバ・プレイヤは、適切なクライアント・プレイヤにメッセージを転送する。将来のバージョンのDirectPlayでは、アプリケーション・サーバをサポートする予定である。


DirectPlayLobbyコンポーネント

DirectPlayLobbyは、DirectPlayアプリケーションと通信するための、一般的なカスタム・ロビー・ソリューションである。通常、カスタム・ロビー・ソリューションは、何種類かのロビー・クライアント・ソフトウェアを含んでいる。ロビー・クライアント・ソフトウェアはユーザのコンピュータ上で動作し、ロビー・サーバーと通信する。ユーザは、ロビー・クライアントが実装しているユーザ・インターフェイスによって、他のプレイヤを見つけてゲーム・セッションに参加することができる。プレイヤ・グループがセッションを開始することを決めると、ロビー・クライアントはそれぞれのコンピュータ上でアプリケーションを開始し、サービス・プロバイダの選択やセッションとの接続のために必要な情報を提供する。 DirectPlayLobby API関数を通して接続され、開始可能となったDirectPlayアプリケーションは、ロビー可能と呼ばれる。また、DirectPlayLobbyは、セッションの進行中にアプリケーションがロビー・クライアントと通信したり、アプリケーションの終了をロビー・クライアントに知らせるためのメソッドを用意している。

ロビー・クライアントは、IDirectPlayLobby::EnumLocalApplicationsメソッドを使用して、ユーザが持っているDirectPlayアプリケーションを判定することができる。また、DirectPlayEnumerate関数によって使用可能なサービス・プロバイダを判定することもできる。 ロビー・クライアントは、ユーザがセッションに加わることを決め、必要なアプリケーションとサービス・プロバイダの存在を確認した後、IDirectPlayLobby::RunApplicationメソッドを用いてアプリケーションの開始とセッションへの接続を実行できる。この呼び出しによって、ロビー・クライアントは、実行するアプリケーション、使用するDirectPlayサービス・プロバイダ、サービス・プロバイダがセッションと接続するために必要な情報（IDirectPlayLobby::CreateAddressおよびIDirectPlayLobby::EnumAddressを使用して）、ロビー環境でのユーザの名前を指定する。 DirectPlayLobbyは実行可能アプリケーションの場所を特定し、適切なコマンドライン・スイッチで開始する。さらに、DirectPlayLobbyは、すべてのサービス・プロバイダと接続情報を格納しておく。

ロビー・クライアントとアプリケーションは、IDirectPlayLobby::SendLobbyMessageとIDirectPlayLobby::ReceiveLobbyMessageメソッドを用いて通信することができる。IDirectPlayLobby::RunApplication メソッドによってメッセージを受信すると、ロビー・クライアントは発生するイベントをセットアップする。アプリケーションからイベントをセットアップするには、IDirectPlayLobby::SetLobbyMessageEvent メソッドを使用する。このメソッドを使うことにより、ロビーのイベントを変更することもできる。

アプリケーションがロビー可能であるためには、IDirectPlayLobbyインターフェイスを作成する必要がある。アプリケーションは、IDirectPlayLobby::GetConnectionSettingsメソッドによってロビー・クライアントが 提供した接続パラメータを調べることができる。これを変更するには、IDirectPlayLobby::SetConnectionSettingsメソッドを使用する。接続の設定を使ってセッションと接続するときは、アプリケーションからIDirectPlayLobby::Connectを呼び出す。この間ロビー・クライアントは、アプリケーション開始プロセスを示すシステム・メッセージを受信する。

プレイヤが作成されるとき、アプリケーションは、プレイヤ名データを（IDirectPlayLobby::GetConnectionSettingsによって）取得し、そのプレイヤに割り当てなくてはならない。IDirectPlayLobby::Connect呼び出しは（成功すれば）、以下の呼び出し手順を代行する。

1	DirectPlayEnumerate （ロビーはサービス・プロバイダを指定する）

2	DirectPlayCreate （IDirectPlayLobby::ConnectはDirectPlayオブジェクトを作成する)

3	IDirectPlay2::EnumSessions（ロビーがセッション情報を指定するため、ユーザがそのうちのひとつを選ぶ必要はない）

4	IDirectPlay2::Open （セッションは自動的に開始される)

IDirectPlayLobby::GetConnectionSettingsがDPERR_NOTLOBBIEDエラーを返すときは、ロビー・クライアントがアプリケーション開始時の初期化処理を行わなかったことを示している。この場合、アプリケーションは、標準的な DirectPlayの初期化を実行するべきである。


サービス・プロバイダ

サービス・プロバイダは、DirectPlayの要求に応じ、媒体に依存した通信サービスを提供する。 オンライン・サービスを含むすべての組織は、専用ハードウェアや通信媒体のためのサービス・プロバイダを用意することができる。DirectDrawには、モデム間直接接続（ TAPI ）、シリアル接続、インターネット TCP/IP、IPXといったサービス・プロバイダが含まれている。


DirectPlayの概要

このセクションには、DirectPlayコンポーネントについての一般的な情報が含まれている。次のトピックについて説明する。

セッション管理

プレイヤ管理

グループ管理

メッセージ管理

データ管理

システム・メッセージの使用

同期

DirectPlayアドレス

DirectPlayバージョン 3で何が新しくなったか?


セッション管理

DirectPlayセッションは、お互いに通信しているリモート・コンピュータ上のいくつかのアプリケーションのインスタンスである。 アプリケーションは、通信チャネルのオープンとクローズのために、 DirectPlay のセッション管理機能を使用する。アプリケーションは、新しいセッションを作成するか既存のセッションを列挙して、接続先のセッションを決定する。セッションを作成するアプリケーションは、ホストとして参照される。 ホストはプレイヤIDとグループIDを割り当て、セッションに参加する新しいアプリケーションを調整する。

アプリケーションは、IDirectPlay2::EnumSessionsメソッドを用い、ネットワーク上で進行中のすべての既存のセッションを取得することができる。新しいセッションを作成したり、既存のセッションに接続するには、 IDirectPlay2::Openメソッドを使用する。セッションは対応する DPSESSIONDESC2構造体によって表される。この構造体には、アプリケーション固有の値と、セッションの名前やオプションのパスワード、参加可能なプレイヤの数といった、セッションの特性が含まれている。セッションをオープンした後は、アプリケーションからIDirectPlay2::GetCapsメソッドを呼び出して、通信速度や、他のネットワークやサービス・プロバイダの特性を取得することができる。

セッションの現在の特性を取得するには、IDirectPlay2::GetSessionDescメソッドを使用する。

セッションから抜けなくてはならないときは、IDirectPlay2::Closeメソッドを用いることができる。セッション・ホストがセッションから抜ける場合、そのセッションがDPSESSIONDESC2構造体にDPSESSION_MIGRATEHOSTフラグを指定して開始されたものであれば、セッション中の他のプレイヤのひとつがホストになり、DPSYS_HOSTシステム・メッセージが発行される。


プレイヤ管理

アプリケーションは、DirectPlayのプレイヤ管理メソッドを使用して、セッション中のプレイヤを管理することができる。プレイヤの作成と削除に加えて、アプリケーションは、プレイヤを列挙したりプレイヤの通信能力を取得することができる。

IDirectPlay2::CreatePlayerおよびIDirectPlay2::DestroyPlayerメソッドは、セッション中のプレイヤの作成および削除を行う。プレイヤが作成されると、アプリケーションはプレイヤの愛称と正式名称、およびいくつかの初期リモート・データを指定することができる（詳細についてはデータ管理を参照）。 DirectPlayはプレイヤにプレイヤIDを割り当てる。アプリケーションとDirectPlayは、このユーザIDを用いてメッセージ・トラフィックの経路を決定する。DirectPlayが愛称や正式名称を使うことはないが、アプリケーションは、それらを利用してプレイヤを識別することができる。

アプリケーションは、IDirectPlay2::EnumPlayersメソッドを使用して、現在のセッションにいるプレイヤや、その愛称と正式名称を判定することができる。通常アプリケーションは、IDirectPlay2::Openメソッドによってセッションを開始した直後にこのメソッドを呼び出す。セッション内のすべてのプレイヤを列挙するには、IDirectPlay2::EnumPlayersメソッドを利用する。セッションへのプレイヤの接続速度についての情報が必要なアプリケーションでは、IDirectPlay2::GetPlayerCaps メソッドを用いることができる。

プレイヤに関連付けられた名前を変更するにはIDirectPlay2::SetPlayerName メソッドを使用する。このメソッドは、プレイヤの名前が変更されたことを通知するため、他のプレイヤへシステム・メッセージを送信する。各プレイヤは、DPMSG_SETPLAYERORGROUPNAME システム・メッセージかIDirectPlay2::GetPlayerNameにより新しい名前を取得することができる。


グループ管理

アプリケーションは、グループ管理メソッドによって、セッション中にプレイヤのグループを作成することができる。IDirectPlay2::Sendメソッドを1度呼び出すと、1度に１人のプレイヤに対してではなく、グループに対してメッセージを送信することができる。サービス・プロバイダによっては、メッセージをグループに送信（配信）したほうが、グループ内の個別のプレイヤに送信するよりも効率的な場合がある。グループを使用すると、プレイヤ管理を単純化できるだけでなく、通信チャネル・バンド幅を節約することも可能である。

IDirectPlay2::CreateGroupとIDirectPlay2::DestroyGroupメソッドは、プレイヤのグループの作成および削除を行う。グループが作成されると、プレイヤの作成時と同様に、アプリケーションは愛称と正式名称を割り当てることができる。DirectPlayはグループにグループIDを割り当てる。初期状態ではグループは空であるが、 IDirectPlay2::AddPlayerToGroupやIDirectPlay2::DeletePlayerFromGroupメソッドによって、アプリケーションからプレイヤの追加と削除を行うことができる。グループの作成、プレイヤの追加、あるいは削除の機能は、セッションの定義の中で設定したDPSESSION_NEWPLAYERSDISABLEDフラグの状態に影響されることはない。

すでに存在するグループを判定するためには、アプリケーションからIDirectPlay2::EnumGroupsメソッドを使うことができる。グループ内のプレイヤを列挙するには、IDirectPlay2::EnumGroupPlayers メソッドを使用する。

アプリケーションは、IDirectPlay2::SetGroupNameメソッドを用いてグループの名前を変更することができる。この呼び出しによって他のプレイヤにシステム・メッセージが通知され、他のプレイヤは、IDirectPlay2::GetGroupNameメソッドを使用して新しい名前を取得する。


メッセージ管理

メッセージ管理機能は、アプリケーションによるプレイヤ間のメッセージのルーティングを支援する。アプリケーションは、システムがすでに定義している少数のメッセージを除き、必要に応じて任意のメッセージを定義することができる。アプリケーションはIDirectPlay2::Sendメソッドを使用して、プレイヤやグループ、またはセッション中のすべてのプレイヤにメッセージを送ることができる。送信先には、それぞれ、プレイヤID、グループID、またはDPID_ALLPLAYERSを指定する。DirectPlayが送信できるメッセージの大きさには制限がない。アプリケーションはIDirectPlay2::GetCapsを呼び出して、ひとつのパケットで送信することができる最大バイト数を取得することができる。それよりも大きいメッセージは、複数のパケットに分割して送信される。

プレイヤやグループのグローバル状態が変更され、セッション中の他のすべてのプレイヤにその変更を通知しなくてはならない場合は、新しいデータについてのメッセージをプレイヤに送るよりも、データ管理関数を利用したほうが便利である。詳細についてはデータ管理を参照。

メッセージ・キューからメッセージを受け取るには、IDirectPlay2::Receiveメソッドを使用する。メッセージが特定のプレイヤに送られたもの、あるいは特定のプレイヤから通知されたものである場合、アプリケーションはこのメソッドによって、キューの最初のメッセージを受け取るかどうかを指定できる。あるプレイヤに対してキューに置かれているメッセージの数を取得するには、IDirectPlay2::GetMessageCountメソッドを使用する。

DirectPlayは、セッション中で起きた変更をプレイヤに通知するシステム・メッセージを生成する。すべてのシステム・メッセージは、DPID_SYSMSGによって定義される仮想プレイヤから送信される。システム・メッセージは、メッセージのタイプを識別する32ビット値から始まる。システム・メッセージを表す定数はDPSYS_で始まっており、対応するメッセージ構造体を含んでいる。この構造体はメッセージを解読するために必要である。アプリケーションは、DPSESSIONDESC2構造体のフラグを指定して、生成されるシステム・メッセージを制御することができる。

別のスレッドを使用してメッセージを受け取る場合、アプリケーションは、メッセージの受信時にセットされる同期イベントを指定することができる。


データ管理

現在のDirectX� 3では、 DirectPlayの機能によって、アプリケーションがデータをプレイヤやグループに関連付けることができる。DirectPlayがプレイヤとグループを追跡しているため、アプリケーション自身は、プレイヤやグループ情報を保持するためのリスト管理を実装する必要がない。さらに、DirectPlayによって、アプリケーションはローカルおよびリモートの2種類の情報を格納できる。ローカル・データは、それをセットするオブジェクトだけが使用可能である。これに対してリモート・データは、セッション中のそれぞれのコンピュータに通知される。この結果、リモート・データはすべてのリモート・コンピュータ間の共有メモリとなる。あまり変更されることがなく、すべてのコンピュータがアクセスする必要があるデータを格納するときは、リモート・データを利用するべきである。他のコンピュータからアクセスする必要がないデータを保持するには、ローカル・データを使うべきである。

アプリケーションは、IDirectPlay2::SetPlayerData メソッドを用いてデータをプレイヤに設定することができる。適切なフラグを渡して呼び出すことにより、データがローカルであるかリモートであるかを指定することができる。データがリモートであれば、保証付きのメッセージを使ってデータを伝達するか、無保証のメッセージを使うかを指定することもできる。プレイヤのデータを取得するには、IDirectPlay2::GetPlayerDataメソッドを使用する。このとき、もう1度、ローカル・データとリモート・データのどちらを受け取るかを指定する。同様に、グループ・データについては、IDirectPlay2::SetGroupDataとIDirectPlay2::GetGroupData メソッドを使うことができる。


システム・メッセージの使用

IDirectPlay2::Receiveメソッドが返す、プレイヤIDやDPID_SYSMSGからのメッセージは、システム・メッセージである。すべてのシステム・メッセージは、dwTypeによって示されるダブルワード値で始まっている。IDirectPlay2::Receiveメソッドによって返されたバッファは、汎用メッセージ（DPMSG_GENERIC）にキャストして、DPSYS_プレフィクスで始まるメッセージのひとつと等しい値のdwType要素を有効にすることができる。アプリケーションは、システム・メッセージを識別したら、データを読み出すために（DPMSG_プレフィクスで始まる）適切な構造体にバッファをキャストするべきである。

アプリケーションは、以下のシステム・メッセージの処理を用意しなくてはならない。

dwTypeの値	メッセージ構造体
DPSYS_ADDPLAYERTOGROUP	DPMSG_ADDPLAYERTOGROUP
DPSYS_CREATEPLAYERORGROUP	DPMSG_CREATEPLAYERORGROUP
DPSYS_DELETEPLAYERFROMGROUP	DPMSG_DELETEPLAYERFROMGROUP
DPSYS_DESTROYPLAYERORGROUP	DPMSG_DESTROYPLAYERORGROUP
DPSYS_HOST	DPMSG_HOST
DPSYS_SESSIONLOST	DPMSG_SESSIONLOST
DPSYS_SETPLAYERORGROUPDATA	DPMSG_SETPLAYERORGROUPDATA
DPSYS_SETPLAYERORGROUPNAME	DPMSG_SETPLAYERORGROUPNAME
IDirectPlayLobby::ReceiveLobbyMessageメソッドが返すメッセージのうち、dwFlagsパラメータにDPLAD_SYSTEMが設定されているものは、システム・メッセージである。すべてのシステム・メッセージはdwTypeによって示されるダブルワード値で始まっている。IDirectPlayLobby::ReceiveLobbyMessageが返すバッファは、汎用メッセージ（DPLMSG_GENERIC）にキャストして、DPLSYS_プレフィクスで始まるメッセージのひとつと等しい値のdwType要素を有効にすることができる。


同期

DirectPlayは、アプリケーションの同期については一般的な方法を提供していない。提供した場合は、アプリケーション通信パラダイムに制限を与えてしまうに違いない。しかし、システムには、これらのタスクを支援するために設計されたいくつかのサービスが含まれている。たとえば、アプリケーションがプレイヤを作成したときは、通知イベントを指定することができる。それからWin32ｮのWaitForSingleObject関数を使用して、メッセージが処理中であるかどうかを知ることができる。


DirectPlayアドレス

このセクションの情報は、DirectPlayLobbyクライアントの開発者のためのものであり、一般的なアプリケーション開発者には関係のない情報も含まれている。

DirectPlayは、ネットワーク・アドレス・データをカプセル化することができる。 DirectPlayには、DirectPlayセッションとの接続に必要なすべての情報が含まれている。この情報の目的は、ユーザに情報の入力を促すダイアログ・ボックスの表示を行うようなサービス・プロバイダを利用せず、アプリケーションからセッションに接続できるようにすることにある。通常サービス・プロバイダは、ユーザから情報を得るためにダイアログ・ボックスを表示するが、完全なDirectPlayアドレスを提供することによって、このダイアログを回避することができる。

DirectPlayアドレスのフォーマットは、リソース交換ファイル形式 （RIFF）に似ている。これは一連のチャンクで構成されている。それぞれのチャンクは、次の要素から成り立っている。

チャンクが含むデータのタイプを示すグローバル・ユニーク識別子（GUID）

データ・サイズ

データ・フィールド

DirectPlayでは、以下のチャンク識別子が定義されている。

GUID	データのタイプ
DPAID_ComPort	DPCOMPORTADDRESS構造体。次の要素を指定する。 使用するCOMポート（1-4） ボーレート（100-256k） ストップ・ビット長（1-2） パリティ（0-無し、1-奇数、2-偶数、3-マーク） フロー制御（0-無し、1-xon/xoff、2-RTS、3-DTR、4-RTS/DTR）
DPAID_Inet	"xxx.xxx.xxx.xxx"書式のIPアドレスまたは"dplay.microsoft.com"のようなサーバー名を表す ASCII文字列。
DPAID_Phone	電話番号の数の桁を表している ASCII文字列。
DPAID_ServiceProvider	このアドレスが作られたサービス・プロバイダの16バイトのGUID。 いくつかの異なるサービス・プロバイダが同じタイプのネットワーク・アドレスを使うことができるため、このチャンクは無視されることができる。
チャンク 識別子 は16バイトの GUID である。


DirectPlayバージョン 3で何が新しくなったか?

DirectPlayバージョン3 API は、以前のバージョンのDirectPlayで書かれたどんなアプリケーションとも完全に互換性がある。つまり、コードに何の変更も加えずに、DirectX 3 SDKのDirectPleyを用いてアプリケーションを再コンパイルすることができる。DirectX 3 SDKが提供するDirectPlayは、以前のバージョンのDirectPlayのすべてのAPIと動作をサポートする。

DirectPlay 3のDLLの名前は旧バージョンと異なっているため、DirectX 2以前のバージョンでコンパイルされたアプリケーションは、新しいDirectPlay DLLを使用しない。新しいDLLを利用するには、アプリケーションを再コンパイルし、Dplayx.libインポート・ライブラリとリンクしなくてはならない。

新しいIDirectPlay2あるいはIDirectPlay2Aインターフェイスを使用してアプリケーションをアップデートし、ロビー可能なアプリケーションを作成するために必要なコードを追加することが、強く推奨されている。これによって、外部のロビーあるいはロビー・プログラムがアプリケーションを開始し、セッションと接続するために必要なすべての情報を提供することができる。アプリケーションは、サービス・プロバイダの決定やセッションの選択、その他の情報（電話番号やネットワーク・アドレスなど）の提供のために、ユーザに問い合わせをする必要がない。

DirectPlayには、このほかの新しい機能がいくつか追加されている。

インターネット・サポート。

直接シリアル接続。

より高い安定性と強靭性。

地域対応をよりサポートするために、Unicodeのサポート。

ホストの移行。もしセッションのホストがセッションから抜ける場合、ホストの責務は別のプレイヤに渡される。DirectPlayバージョン2では、ホスト（ネーム・サーバ）がセッションから抜けた場合、新しいプレイヤを作成することができなかった。

アプリケーションのロビー・プログラムとの通信機能。これによって、初期状態についての情報を受け取ったり、ゲームの状態を更新することができる。

1台のコンピュータの上で複数のアプリケーション・セッションがホストを務める能力。

リモート・コンピュータの接続の切断を判定し、適切なメッセージを生成する能力。

また、通信管理のためのコードの量を減らすため、次のような機能がDirectPlay 3に追加されている。

アプリケーション固有のデータをDirectPlayグループIDやプレイヤIDと関連付ける機能。これによってアプリケーションは、DirectPlayの1部であるプレイヤやグループのリスト管理コードを拡張することができる。ローカル・データとは、プレイヤを表すビットマップのような、ローカル・アプリケーションが直接使用するデータである。ローカル・データがネットワーク上に送信されることはない。リモート・データは、プレイヤあるいはグループに関連付けられる。リモート・データに加えられた変更は、DirectPlayによって、セッション中の他のすべてのアプリケーションに通知される。リモート・データは、プレイヤの位置や向き、速さのように、セッション中のすべてのアプリケーション間で共有されなくてはならないものである。このデータの伝達にDirectPlayを使用すれば、アプリケーションが情報の送受信のための一連のメソッドを用いてデータを管理する必要はなくなる。

アプリケーションがグループに名前を関連付ける機能。これはチーム競技に役立つ。

DirectPlay 3の新機能のうちのいくつかは、アプリケーションとは直接関係がないものである。

ロビー・クライアント・ソフトウェアがロビー可能なDirectPlayアプリケーションの開始や接続に使用するAPI。また、セッションの間にアプリケーションとロビーが情報を交換できるようにするAPIも含まれている。

サービス・プロバイダ開発キット。独自のサービス・プロバイダを作成するための文書とサンプルコードが含まれている。

このセクションでは、DirectPlay 3の新しいメソッド、IDirectPlay2インターフェイスに移行するために必要な手順、アップデートされたDirectPlayの機能にアクセスする方法について説明する。以下のトピックが含まれている。

新しいDirectPlay 3メソッド

IDirectPlay2インターフェイスへの移行


新しいDirectPlay 3メソッド

DirectPlayバージョン3は、以下の新しいメソッドをサポートする。

IDirectPlay2::SetGroupDataおよびIDirectPlay2::GetGroupData

アプリケーション固有のデータをDirectPlayグループIDと関連付ける。アプリケーション・ローカルにも、リモート・データ・スペースにも関連付けることができる。

IDirectPlay2::SetGroupNameおよびIDirectPlay2::GetGroupName

名前をグループに関連付ける。

IDirectPlay2::SetPlayerDataおよびIDirectPlay2::GetPlayerData

アプリケーション固有のデータをDirectPlayプレイヤIDと関連付ける。アプリケーション・ローカルにも、リモート・データ・スペースにも関連付けることができる。

IDirectPlay2::GetSessionDesc

セッションの進行中にセッションの特性を取得する。


IDirectPlay2インターフェイスへの移行

アプリケーションをIDirectPlay2インターフェイスに移行するには、次のステップを実行する必要がある。

1	アプリケーションがロビー・クライアントから起動されたかどうかを調べる。詳細については、DirectPlayチュートリアルの「Step 2: 接続環境の取得 」を参照されたい。

2	アプリケーションがサービス・プロバイダを列挙している場合は、DirectPlayEnumerateコールバック関数を用いて、サービス・プロバイダが使用可能かどうかを判定する。使用可能であれば、そのサービス・プロバイダについてDirectPlayCreate関数を呼び出す。DirectPlayEnumerateコールバック関数がエラーを返したときは、そのサービス・プロバイダをシステム上で実行することはできないので、ユーザに表示するリストに追加しないようにする。呼び出しが成功すれば、Releaseメソッドを使用してDirectPlayオブジェクトを解放し、そのサービス・プロバイダをリストに追加する。

3	IDirectPlay2（Unicode）やIDirectPlay2A（ANSI）インターフェイスを取得するには、IDirectPlayインターフェイスのQueryInterfaceメソッドを呼び出す。これらふたつのインターフェイスの唯一の違いは、構造体における文字列の読み書きの方法である。Unicodeインターフェイスでは、LPWSTR型の構造体メンバにUnicode文字列が読み書きされる。ANSIインターフェイスでは、LPSTR型の構造体メンバにANSI文字列が読み書きされる。

4	既存のAPIで新しい構造体を使うために必要な、すべての変更を行う。 たとえば、次のコードの代わりに、

lpDP->SetPlayerName(pidPlayer, lpszFriendlyName, lpszFormalName)

lpDPがIDirectPlayインターフェイスであるなら、以下のようにする。

DPNAME PlayerName, *lpPlayerName;

PlayerName.dwSize = sizeof(DPNAME);

lpPlayerName = &PlayerName;

lpPayerName->lpszShortNameA = lpszFriendlyName;

lpPlayerName->lpszLongNameA = lpszFormalName;

lpDP2A->SetPlayerName(pidPlayer, lpPlayerName, 0)

lpDP2はIDirectPlay2Aインターフェイスである。 アプリケーションがUnicode文字列を使用する（したがってIDirectPlay2インターフェイスのインスタンスを作成する）場合は、次のようにする。

lpPayerName->lpszShortName = lpwszFriendlyName;

lpPlayerName->lpszLongName = lpwszFormalName;

lpDP2->SetPlayerName(pidPlayer, lpPlayerName, 0)

lpDP2はIDirectPlay2インターフェイスである。

5	次のシステム・メッセージを更新する。

DPSYS_ADDPLAYERはDPSYS_CREATEPLAYERORGROUPに変更された。

DPSYS_DELETEPLAYERとDPSYS_DELETEGROUPは、ひとつのDPSYS_DESTROYPLAYERORGROUP メッセージに統合された。

DPSYS_DELETEPLAYERFROMGRPはDPSYS_DELETEPLAYERFROMGROUPに変更された。

6	プレイヤやグループ名が変更されたとき、DPSYS_SETPLAYERORGROUPNAMEメッセージを発行するようにアプリケーションを更新する。また、プレイヤやグループ・データが変更されたときには、DPSYS_SETPLAYERORGROUPDATAメッセージを生成するようにする。

7	DPSESSIONDESC構造体をDPSESSIONDESC2構造体に更新し、DPCAPS構造体に新しいメンバを追加する。

8	IDirectPlay2::EnumSessions、IDirectPlay2::EnumGroups、IDirectPlay2::EnumGroupPlayers、およびIDirectPlay2::EnumPlayersのコールバック関数を更新する。

9	IDirectPlay2::CreatePlayerメソッドへのbEventパラメータの渡し方を修正する。以前のバージョンのDirectPlayでは、このパラメータはlpEventであった。このバージョンのDirectPlayはイベントを返さない。その代わり、アプリケーションがイベントを作成しなくてはならない。これによってアプリケーションの柔軟性が保たれ、すべてのプレイヤに対するひとつのイベントを作成することができる。

10	プレイヤがゲームを異常終了したことをDirectPlayに検出させる必要があるアプリケーションでは、DPSESSIONDESC2構造体にDPSESSION_KEEPALIVEフラグをセットする。

11	セッションを作成する際、DPSESSION_MIGRATEHOSTフラグを設定するようにアプリケーションを更新する。これによって、現在のホストがセッションを抜けても、別のコンピュータがホストになることができる。ホストを起動するための特別なコードを定義している場合は、セッションの作成時にこのフラグをセットし、さらに、DPSYS_HOSTシステム・メッセージのサポートを追加するべきである。システム・メッセージのリストについては、「システム・メッセージの使用」を参照されたい。

12	IDirectPlay2インターフェイスの新しいメソッドをよく理解して使用すること。特に、IDirectPlay2::SetPlayerDataとIDirectPlay2::GetPlayerDataメソッドには注意が必要である。プレイヤの状態を他のすべてのプレイヤにブロードキャストするコードは、IDirectPlay2::SendとIDirectPlay2::Receiveメソッドを用いて書き換えることができるであろう。


DirectPlayインターフェイスの概要

DirectPlayは、コンポーネント・オブジェクト・モデル（ COM ）に基づいたオブジェクトとインターフェイスで構成されている。COMは、インターフェイスの再利用に焦点を当てたオブジェクトベース・システムの基礎であり、OLEプログラミングの中心モデルである。また、任意の数のインターフェイスを構築することができる仕様になっている。

以前のバージョンのDirectXでは、DirectPlayオブジェクトはただひとつのインターフェイス、IDirectPlayだけで構成されていた。今回、DirectPlayは、より多様な通信方法へのより良いアクセスを提供する新しい機能が追加され、拡張されている。UnicodeとANSI文字列のサポート、ロビー・サービスの作成のためのブロック構築のサポートなど、新しいインターフェイスがDirectPlayに追加された。

このセクションには、以下のDirectPlay COMインターフェイスについての一般的な情報が含まれている。

IDirectPlayインターフェイス

IDirectPlay2インターフェイス

IDirectPlayLobbyインターフェイス


IDirectPlayインターフェイス

IDirectPlay COMインターフェイスは、DirectPlayバージョン3の一部にすぎない。このインターフェイスには、DirectX SDKバージョン1と2で書かれたアプリケーションの実行に必要なメソッドが含まれている。このインターフェイスを用いて新しいアプリケーションを作成することもできるが、拡張された機能を利用するため、IDirectPlay2とIDirectPlay2Aという新しいDirectPlayインターフェイスを使うことを推奨する。


IDirectPlay2インターフェイス

DirectPlayは、Unicode文字列ポインタ（LPWSTR）とANSI文字列ポインタ（LPSTR）の共用体として構造体の文字列ポインタを定義することにより、UnicodeとANSI文字列の両方をサポートしている。ふたつの文字列ポインタは異なる名前を持っている。一般に、ANSI文字列ポインタは"A"の文字で終わる。アプリケーションは、どちらのIDirectPlayインターフェイスが選択されるか（UnicodeのIDirectPlay2か、ANSIのIDirectPlay2A）によって、構造体から適切な文字列を読み書きし、もう一方を無視しなくてはならない。


IDirectPlayLobbyインターフェイス

次のトピックには、IDirectPlayLobbyインターフェイスに関する追加情報が含まれている。

UnicodeとANSIのDirectPlayLobbyインターフェイス

ロビー可能アプリケーションの登録


UnicodeとANSIのDirectPlayLobbyインターフェイス

DirectPlayLobbyは、Unicode文字列ポインタ（LPWSTR）とANSI文字列ポインタ（LPSTR）の共用体として構造体の文字列ポインタを定義することにより、UnicodeとANSI文字列の両方をサポートする。ふたつの文字列は異なる名前を持っている。一般に、 ANSI 文字列ポインタは"A"の文字で終わる。アプリケーションは、どちらのIDirectPlayインターフェイスが選択されるか（UnicodeのIDirectPlay2か、ANSIのIDirectPlay2A）によって、構造体から適切な文字列を読み書きし、もう一方を無視しなくてはならない。


ロビー可能アプリケーションの登録

DirectPlayLobbyによって列挙され、開始されるアプリケーションは、インストール時にWindowsのレジストリにいくつかの情報を追加しなくてはならない。このために、以下のレジストリ・キーが定義されている。"Application Name"は、DirectPlayLobbyがアプリケーションを列挙したときに返される、アプリケーションの名前である。これらの項目を追加するには、DirectSetupのDirectXRegisterApplication関数を使用することができる。

[HKEY_LOCAL_MACHINE\Software\Microsoft\DirectPlay\Applications\Application Name]

"Guid"              アプリケーションのGUID

"Filename"          実行可能なファイル名

"CommandLine"       （必要なら）アプリケーションのコマンドライン・スイッチ

"Path"              実行可能なアプリケーションのパス

"CurrentDirectory"  アプリケーションを開始するディレクトリのパス


DirectPlayチュートリアル

このセクションには、ロビーを利用してアプリケーションを接続する方法、またはロビーを利用せずに接続する方法について、ステップ・バイ・ステップに説明したふたつのチュートリアルが含まれている。LOBBYサンプルは、DirectPlayロビーを用いてアプリケーションを接続する方法を説明している。DIALOGサンプルでは、接続情報をユーザに問い合わせるダイアログ・ボックスを使用してアプリケーションを接続する方法を示している。アプリケーションを記述するときは、どちらかのメソッドによってアプリケーションを開始できるようにしなくてはならない。

チュートリアル 1: ロビーを使用した接続（LOBBY）

チュートリアル 2: ダイアログ・ボックスを使用した接続（DIALOG）

メモ

これらのチュートリアルのサンプル・ファイルはC++で書かれている。 Ｃコンパイラを使用している場合は、コンパイルを通すため、ファイルに適切な変更を加えなくてはならない。少なくとも、インターフェイス・メソッドへのvtableとthisポインタを追加しなくてはならない。 詳細についてはCでのCOMオブジェクトへのアクセスを参照されたい。


チュートリアル 1: ロビーを使用した接続

IDirectPlayLobbyインターフェイスを使用して書かれたアプリケーションは、ユーザが手作業で接続情報をダイアログ・ボックスに入力することなく接続できる。LOBBYサンプルは、次のステップでロビーされたアプリケーションを作成する方法を説明する。

Step 1: DirectPlayLobbyオブジェクトの作成

Step 2: 接続環境の取得

Step 3: セッション記述の設定

Step 4: セッションへの接続

Step 5: プレイヤの作成


Step 1: DirectPlayLobbyオブジェクトの作成

DirectPlayロビー機能を使うため、まず DirectPlayLobbyCreate関数を呼び出してDirectPlayLobbyオブジェクトのインスタンスを作成する。この関数は5つのパラメータを含んでいる。第1、第3、第4パラメータは、将来の拡張のために予約されており、つねにNULLを設定する。第2パラメータにはDirectPlayLobbyオブジェクトのポインタのアドレスを指定する。オブジェクトが作成されると、このポインタを用いてオブジェクトの位置を識別することができる。第5パラメータも将来の拡張のために予約されており、つねに0に設定する。

次の例は、DirectPlayLobbyオブジェクトの作成方法のひとつである。

// ANSI DirectPlayロビー・インターフェイスを取得する。

hr = DirectPlayLobbyCreate(NULL, &lpDirectPlayLobbyA, NULL, NULL, 0);

if FAILED(hr)

    goto FAILURE;


Step 2: 接続環境の取得

 DirectPlayLobbyオブジェクトが作成された後、IDirectPlayLobby::GetConnectionSettingsメソッドを使用して、ロビーから返される接続環境を取得する。このメソッドが DPERR_NOTLOBBIEDを返すと、ロビーはこのアプリケーションを開始しない。この場合、ユーザが手動で接続を設定しなければならない。他の何らかのエラーが発生したときは、アプリケーションは、ロビーの失敗を示すエラーを報告するべきである。

以下の例は、接続設定を取得する方法を示している。

// ロビーから接続設定を取得する。

// このルーチンがDPERR_NOTLOBBIEDを返すと、ロビーはアプリケーションを開始しない。

// この場合、ユーザが接続をする必要がある。

// 接続設定のサイズだけを取得する場合は、NULLポインタを渡す。

hr = lpDirectPlayLobbyA->GetConnectionSettings(0, NULL, &dwSize);

if (DPERR_BUFFERTOOSMALL != hr)

    goto FAILURE;

// 接続設定のためのメモリを確保する。

lpConnectionSettings = (LPDPLCONNECTION) GlobalAllocPtr(GHND, dwSize);

    if (NULL == lpConnectionSettings)

    {

        hr = DPERR_OUTOFMEMORY;

        goto FAILURE;

    }

    // 接続設定を取得する。

    hr = lpDirectPlayLobbyA->GetConnectionSettings(0,

        lpConnectionSettings, &dwSize);

    if FAILED(hr)

        goto FAILURE;


Step 3: セッション記述の設定

アプリケーションに必要なすべてのフラグと特性が正しく設定されていることを確認するには、DPSESSIONDESC2構造体を調べるべきである。修正が必要な場合は、IDirectPlayLobby::SetConnectionSettingsメソッドを使用して、変更した接続設定を記憶する。

次の例では、セッション記述を構成し、接続を設定する方法を示している。

// 接続前に必要なセッション記述を構成する。

// ゲームで使用されるフラグと最大プレイヤ数をセットする。

lpConnectionSettings->lpSessionDesc->dwFlags = DPSESSION_MIGRATEHOST |

    DPSESSION_KEEPALIVE;

lpConnectionSettings->lpSessionDesc->dwMaxPlayers = MAXPLAYERS;

// 修正された接続設定を記憶する。

hr = lpDirectPlayLobbyA->SetConnectionSettings(0, 0,

        lpConnectionSettings);

if FAILED(hr)

    goto FAILURE;


Step 4: セッションへの接続

セッション記述が正しく設定されると、アプリケーションは セッションと接続するためにIDirectPlayLobby::Connectメソッドを使用することができる。このメソッドがDP_OKを返せば、ひとつあるいは複数のプレイヤを作成することができる。このメソッドがDPERR_NOTLOBBIEDを返したときは、ユーザは通信媒体を手動で選択しなければならない（システムにインストールされているサービス・プロバイダを識別するには、DirectPlayEnumerate関数を利用することができる）。他の何らかのエラーが発生した場合は、アプリケーションは、ロビーが失敗したことを示すエラーを報告するべきである。

次の例は、セッションとの接続方法を示している。

// セッションに接続する。ANSI IDirectPlay2Aインターフェイスを返す。

hr = lpDirectPlayLobbyA->Connect(0, &lpDirectPlay2A, NULL);

if FAILED(hr)

    goto FAILURE;


Step 5: プレイヤの作成

IDirectPlayLobby::Connect メソッドによって正常にアプリケーションが開始されると、ひとつまたは複数のプレイヤを作成できるようになる。アプリケーションはIDirectPlay2::CreatePlayerメソッドを使用して、DPNAME 構造体（IDirectPlayLobby::GetConnectionSettings メソッドによって設定されたもの）が指定する名前のプレイヤを作成することができる。

以下にプレイヤの作成方法の例を示す。

// 接続設定に返された名前でプレイヤを作成する。

hr = lpDirectPlay2A->CreatePlayer(&dpidPlayer,

    lpConnectionSettings->lpPlayerName,

    lpDPInfo->hPlayerEvent, NULL, 0, 0);

if FAILED(hr)

    goto FAILURE;

これでアプリケーションは接続され、プレイ準備が完了した。


チュートリアル 2: ダイアログ・ボックスを使用した接続

ロビーがアプリケーションを開始しなかった場合は、ユーザが接続情報を手動で入力できるようなコードを含めておくべきである。DIALOGサンプルは、以下のステップで、セッションに手動で接続する方法と、ひとつ以上のプレイヤを作成する方法を説明する。

Step 1: サービス・プロバイダの列挙

Step 2: DirectPlayオブジェクトの作成

Step 3: セッションへの参加

Step 4: セッションの作成

Step 5: プレイヤの作成


Step 1: サービス・プロバイダの列挙

手動で接続を確立するための第一歩は、ユーザにアプリケーションのための通信媒体の選択を要求することである。アプリケーションは DirectPlayEnumerate関数を使用して、パーソナル・コンピュータ上にインストールされているサービス・プロバイダを識別することができる。

次の例は、サービス・プロバイダの列挙方法を示している。

DirectPlayEnumerate(DirectPlayEnumerateCallback, hWnd);

DirectPlayEnumerate関数の第1パラメータは、DirectPlayによって登録されたサービス・プロバイダを列挙するコールバック関数である。次の例は、このコールバック関数をインプリメントする方法のひとつを示している。

BOOL FAR PASCAL DirectPlayEnumerateCallback(

    LPGUID lpSPGuid, LPTSTR lpszSPName, DWORD dwMajorVersion,

    DWORD dwMinorVersion, LPVOID lpContext)

{

HWND    hWnd = lpContext;

LRESULT iIndex;

LPGUID  lpGuid;

// サービス・プロバイダの名前をコンボ・ボックスに格納する。

iIndex = SendDlgItemMessage(hWnd, IDC_SPCOMBO, CB_ADDSTRING,

    0, (LPARAM) lpszSPName);

if (iIndex == CB_ERR)

    goto FAILURE;

// アプリケーションGUIDの領域を作成する。

lpGuid = (LPGUID) GlobalAllocPtr(GHND, sizeof(GUID));

if (lpGuid == NULL)

    goto FAILURE;

// コンボ・ボックスにGUIDへのポインタを格納する。

*lpGuid = *lpSPGuid;

SendDlgItemMessage(hWnd, IDC_SPCOMBO, CB_SETITEMDATA,

    (WPARAM) iIndex, (LPARAM) lpGuid);

FAILURE:

    return (TRUE);

}


Step 2: DirectPlayオブジェクトの作成

ユーザが使用するサービス・プロバイダを選択すると、選択に基づいてDirectPlayオブジェクトを作成し、適切なサービス・プロバイダのグローバル・ユニーク識別子（GUID）を指定することができる。DirectPlayオブジェクトの作成には、DirectPlayCreate関数を使用する。この関数の呼び出しによって、DirectPlayは選択されたサービス・プロバイダのためのライブラリをロードし、IDirectPlayインターフェイスを返す。

IDirectPlayインターフェイスは新しいゲームの作成に用いることができるが、よりよい方法は、最新のDirectPlayインターフェイスであるIDirectPlay2およびIDirectPlay2Aを利用することである。これらのインターフェイスには、追加されたDirectPlayの全機能が含まれている。IDirectPlay2やIDirectPlay2Aインターフェイスを取得するには、DirectPlayCreate関数が返すIDirectPlayインターフェイスのQueryInterfaceメソッドを呼び出す。

次の例ではIDirectPlayインターフェイスの作成方法を示し、QueryInterfaceを使用してIDirectPlay2Aインターフェイスを作成している。

HRESULT CreateDirectPlayInterface(LPGUID lpguidServiceProvider,

    LPDIRECTPLAY2A *lplpDirectPlay2A)

{

LPDIRECTPLAY   lpDirectPlay1 = NULL;

LPDIRECTPLAY2A lpDirectPlay2A = NULL;

HRESULT        hr;

// DirectPlay 1.0インターフェイスを取得する。

hr = DirectPlayCreate(lpguidServiceProvider, &lpDirectPlay1, NULL);

if FAILED(hr)

    goto FAILURE;

// ANSI DirectPlay2インターフェイスを照会する。

hr = lpDirectPlay1->QueryInterface(IID_IDirectPlay2A,

    (LPVOID *) &lpDirectPlay2A);

if FAILED(hr)

    goto FAILURE;

// 作成されたインターフェイスを返す。

*lplpDirectPlay2A = lpDirectPlay2A;

FAILURE:

if (lpDirectPlay1)

    lpDirectPlay1->Release();

return (hr);

}


Step 3: セッションへの参加

ユーザが既存のセッションに参加するには、IDirectPlay2::EnumSessionsメソッドを使用して使用可能なセッションを列挙し、ユーザに選択肢を提供する。そして、DPOPEN_JOINフラグを指定してIDirectPlay2::Openメソッドを呼び出し、そのセッションと接続する。セッションを列挙する前に、サービス・プロバイダは、ダイアログ・ボックスを表示してユーザに情報の入力を要求する場合がある。

利用可能なセッションを列挙する方法を次に示す。

// この種類のセッションを検索する。

ZeroMemory(&sessionDesc, sizeof(DPSESSIONDESC2));

sessionDesc.dwSize = sizeof(DPSESSIONDESC2);

sessionDesc.guidApplication = DPCHAT_GUID;

hr = lpDirectPlay2A->EnumSessions(&sessionDesc, 0, EnumSessionsCallback,

    hWnd, DPENUMSESSIONS_AVAILABLE);

if FAILED(hr)

    goto FAILURE;

IDirectPlay2::EnumSessionsメソッドの第3パラメータは、利用可能なセッションを列挙するコールバック関数である。次の例では、このコールバック関数をインプリメントする方法のひとつを示している。

BOOL FAR PASCAL EnumSessionsCallback(

    LPCDPSESSIONDESC2 lpSessionDesc, LPDWORD lpdwTimeOut,

    DWORD dwFlags, LPVOID lpContext)

{

HWND   hWnd = lpContext;

LPGUID lpGuid;

LONG   iIndex;

// タイムアウトを判定する。

if (dwFlags & DPESC_TIMEDOUT)

    return (FALSE);            // 再試行しない。

// セッション名をリストに格納する。

iIndex = SendDlgItemMessage(hWnd, IDC_SESSIONLIST, LB_ADDSTRING,

    (WPARAM) 0, (LPARAM) lpSessionDesc->lpszSessionNameA);

if (iIndex == CB_ERR)

    goto FAILURE;

// セッション・インスタンスGUIDの領域を作成する。

lpGuid = (LPGUID) GlobalAllocPtr(GHND, sizeof(GUID));

if (lpGuid == NULL)

    goto FAILURE;

// GUIDのポインタをリストに格納する。

*lpGuid = lpSessionDesc->guidInstance;

SendDlgItemMessage(hWnd, IDC_SESSIONLIST, LB_SETITEMDATA,

    (WPARAM) iIndex, (LPARAM) lpGuid);

FAILURE:

    return (TRUE);

}

ユーザがセッションを選択すると、アプリケーションはユーザに既存のセッションへの参加を許すことができる。 既存のセッションに参加する方法を以下に示す。

// 既存のセッションへ参加する。

ZeroMemory(&sessionDesc, sizeof(DPSESSIONDESC2));

sessionDesc.dwSize = sizeof(DPSESSIONDESC2);

sessionDesc.guidInstance = *lpguidSessionInstance;

hr = lpDirectPlay2A->Open(&sessionDesc, DPOPEN_JOIN);

if FAILED(hr)

    goto OPEN_FAILURE;


Step 4: セッションの作成

ユーザが新しいセッションを作成するには、DPOPEN_CREATEフラグを指定してIDirectPlay2::Openメソッドを呼び出す。ここでもサービス・プロバイダは、セッションが作成される前にダイアログ・ボックスを表示し、ユーザに情報の入力を要求する場合がある。

新しいセッションの作成方法を次に示す。

// 新しいセッションのホストを務める。

ZeroMemory(&sessionDesc, sizeof(DPSESSIONDESC2));

sessionDesc.dwSize = sizeof(DPSESSIONDESC2);

sessionDesc.dwFlags = DPSESSION_MIGRATEHOST | DPSESSION_KEEPALIVE;

sessionDesc.guidApplication = DPCHAT_GUID;

sessionDesc.dwMaxPlayers = MAXPLAYERS;

sessionDesc.lpszSessionNameA = lpszSessionName;

hr = lpDirectPlay2A->Open(&sessionDesc, DPOPEN_CREATE);

if FAILED(hr)

    goto OPEN_FAILURE;


Step 5: プレイヤの作成

セッションを作成、あるいはセッションに参加した後、アプリケーションは、IDirectPlay2::CreatePlayerメソッドによってひとつ以上のプレイヤを作成することができる。次の例では、プレイヤを作成する方法のひとつを示している。

// 名前構造体を設定する。

ZeroMemory(&dpName, sizeof(DPNAME));

dpName.dwSize = sizeof(DPNAME);

dpName.lpszShortNameA = lpszPlayerName;

dpName.lpszLongNameA = NULL;

// この名前でプレイヤを作成する。

hr = lpDirectPlay2A->CreatePlayer(&dpidPlayer, &dpName,

    lpDPInfo->hPlayerEvent, NULL, 0, 0);

if FAILED(hr)

    goto CREATEPLAYER_FAILURE;

アプリケーションは、IDirectPlay2::GetCapsやIDirectPlay2::GetPlayerCapsメソッドを使用してプレイヤの通信能力を判定することができる。また、他のプレイヤを見つけるには、IDirectPlay2::EnumPlayers メソッドを使用する。

これでアプリケーションは接続され、プレイするための準備が完了した。


DirectPlayリファレンス


関数


DirectPlayCreate

HRESULT WINAPI DirectPlayCreate(LPGUID lpGUID,

    LPDIRECTPLAY *lplpDP, IUnknown  *pUnkOuter);

DirectPlayオブジェクトのインスタンスを作成する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

CLASS_E_NOAGGREGATION

DPERR_EXCEPTION

DPERR_INVALIDPARAMS

DPERR_UNAVAILABLE

lpGUID

作成されるサービス・プロバイダを示すグローバル・ユニーク識別子（GUID）へのポインタ。

lplpDP

有効なDirectPlayインターフェイスで初期化されるポインタへのポインタ。IDirectPlay2（Unicode文字列）やIDirectPlay2A（ANSI文字列）インターフェイスを取得するためには、QueryInterfaceメソッドを使用する必要がある。

pUnkOuter

IUnknownインターフェイスへのポインタ。このパラメータは、将来のCOM集成化機能との互換性のために提供される。現在のDirectPlayCreate関数は、このパラメータにNULL以外の値が指定されているとエラーを返す。

この関数はDirectPlayオブジェクトの初期化を行い、正常終了した場合はポインタをセットする。アプリケーションは、初期化の直前に、利用可能なサービス・プロバイダのタイプを判定するためにDirectPlayEnumerate関数を呼び出すべきである（DirectPlayEnumerate関数は、DirectPlayCreateのlpGUIDパラメータを設定する）。

この関数は、IDirectPlayインターフェイスへのポインタを返す。現在のDirectX 3インターフェイスはIDirectPlay2およびIDirectPlay2Aである。これらのインターフェイスを取得するには、DirectPlayCreateによって返されたIDirectPlayインターフェイスのQueryInterfaceメソッドを呼び出す必要がある。

参照　DirectPlayEnumerate


DirectPlayEnumerate

HRESULT WINAPI DirectPlayEnumerate(

    LPDPENUMDPCALLBACK lpEnumDPCallback, LPVOID lpContext);

システムにインストールされているDirectPlayサービス・プロバイダを列挙する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

 DPERR_EXCEPTION

DPERR_GENERIC

DPERR_INVALIDPARAMS

lpEnumDPCallback

システムにインストールされているDirectPlayサービス・プロバイダ・インターフェイスごとに呼び出される、EnumDPCallback関数へのポインタ。

lpContext

関数が呼び出されるたびにコールバック関数に渡される、アプリケーション定義の構造体へのポインタ。

この関数は、システムにインストールされているサービス・プロバイダなら、システムが利用することができないものでも列挙する。たとえば、システムにモデムがインストールされていなくても、列挙にはTAPIサービス・プロバイダが含まれる。


DirectPlayLobbyCreate

HRESULT WINAPI DirectPlayLobbyCreate(

    LPGUID lpguidSP, LPDIRECTPLAYLOBBY *lplpDPL,

    IUnknown *lpUnk, LPVOID lpData, DWORD dwDataSize);

DirectPlayLobbyオブジェクトのインスタンスを作成する。この関数はDirectPlayLobbyオブジェクトの初期化を行い、ポインタをセットする。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

CLASS_E_NOAGGREGATION

DPERR_INVALIDPARAMS

DPERR_OUTOFMEMORY

lpguidSP

将来のために予約されている。NULLにセットしておかなければならない。

lplpDPL

有効なIDirectPlayLobbyインターフェイスで初期化されるポインタへのポインタ。

lpUnk

IUnknownインターフェイスへのポインタ。このパラメータは将来のCOM集成化機能との互換性のために提供されている。現在のDirectPlayLobbyCreate関数では、このパラメータにNULL以外の値が指定されるとエラーを返す。

lpData

DirectPlayLobbyオブジェクトを作成するために追加データを必要とする。このパラメータは NULLにセットしておかなければならない。

dwDataSize

このパラメータは0にセットしておかなければならない。


コールバック関数


EnumAddressCallback

BOOL WINAPI EnumAddressCallback(REFGUID guidDataType,

    DWORD dwDataSize, LPCVOID lpData,

    LPVOID lpContext);

IDirectPlayLobby::EnumAddress メソッドで使用するアプリケーション定義のコールバック関数。

列挙を続ける場合はTRUE、終了する場合はFALSEを返す。

guidDataType

データ・チャンクの型を表すグローバル・ユニーク識別子（GUID）。

dwDataSize

データチャンクのサイズをバイト単位で指定する。

lpData

定数データへのポインタ。

lpContext

コールバック関数に渡されるコンテキスト。

サービス・プロバイダは、guidDataTypeパラメータのGUIDを調べて、lpDataで示される値を処理または記憶しなくてはならない。認識できないguidDataTypeの値は無視することができる。

コールバック関数に返されるすべてのポインタは一時的なものであり、コールバック関数内でのみ有効である。ポインタ情報を保存する必要があるアプリケーションは、データを保持するメモリを確保し、データをコピーし、新しいデータのポインタを保存しなければならない。この関数内のlpDataは一時的なポインタである。


EnumAddressTypeCallback

BOOL WINAPI EnumAddressTypeCallback(

    REFGUID guidDataType, LPVOID lpContext,

    DWORD dwFlags);

IDirectPlayLobby::EnumAddressTypes メソッドで使用するアプリケーション定義のコールバック関数。

列挙を続ける場合はTRUE、終了する場合はFALSEを返す。

guidDataType

アドレス種別を表すグローバル・ユニーク識別子(GUID)。定義済みへのポインタ種別は、DPAID_Phone、DPAID_Inet、DPAID_ComPortである。アドレス種別についての詳細DirectPlayアドレスを参照されたい。

lpContext

コールバック関数に渡されるコンテキスト。

dwFlags

予約されている。使用してはいけない。


EnumDPCallback

BOOL WINAPI EnumDPCallback(LPGUID lpguidSP,

    LPSTR/LPWSTR lpSPName, DWORD dwMajorVersion,

    DWORD dwMinorVersion, LPVOID lpContext);

DirectPlayEnumerate関数で使用するアプリケーション定義のコールバック関数。UNICODEが定義されるかどうかによって、コールバック関数のプロトタイプのlpSPNameは、LPWSTR（Unicodeの場合）あるいはLPSTR（ANSIの場合）として定義される。

列挙を続ける場合はTRUE、終了する場合はFALSEを返す。

lpguidSP

DirectPlayサービス・プロバイダのユニーク識別子のアドレス。

lpSPName

ドライバを示す文字列のアドレス。UNICODEシンボルが定義されるかどうかによって、パラメータはLPWSTR型（Unicode）あるいはLPSTR型（ANSI）となる。

dwMajorVersion and dwMinorVersion

ドライバのメジャーおよびマイナー・バージョン番号。

lpContext

アプリケーション定義のコンテキストへのポインタ。

コールバック関数に返されるすべてのポインタは一時的なものであり、コールバック関数内でのみ有効である。ポインタ情報を保存する必要があるアプリケーションは、データを保持するメモリを確保し、データをコピーし、新しいデータのポインタを保存しなければならない。この関数内のlpguidSP、lpSPName、lpDataは一時的なポインタである。


EnumLocalApplicationsCallback

BOOL WINAPI EnumLocalApplicationsCallback(

    LPCDPLAPPINFO lpAppInfo, LPVOID lpContext, DWORD dwFlags);

IDirectPlayLobby::EnumLocalApplicationsメソッドで使用するアプリケーション定義のコールバック関数。

列挙を続ける場合はTRUE、終了する場合はFALSEを返す。

lpAppInfo

列挙されたアプリケーションの情報を含む、読み出し専用のDPLAPPINFO構造体へのポインタ。

lpContext

IDirectPlayLobby::EnumLocalApplications呼び出しから渡されるコンテキストへのポインタ。

dwFlags

予約されている。使用してはいけない。

コールバック関数に返されるすべてのポインタは一時的なものであり、コールバック関数内でのみ有効である。ポインタ情報を保存する必要があるアプリケーションは、データを保持するメモリを確保し、データをコピーし、新しいデータのポインタを保存しなければならない。この関数内のlpAppInfoは一時的なポインタである。また、lpAppInfoパラメータで示される構造体の中のポインタ、lpszAppNameAおよびlpszAppNameも一時的なものであることに注意が必要である。


EnumPlayersCallback2

BOOL WINAPI EnumPlayersCallback2(DPID dpId,

    DWORD dwPlayerType, LPCDPNAME lpName,

    DWORD dwFlags, LPVOID lpContext);

IDirectPlay2::EnumGroups, IDirectPlay2::EnumGroupPlayersおよびIDirectPlay2::EnumPlayersメソッドで使用されるアプリケーション定義のコールバック関数。

列挙を続ける場合はTRUE、終了する場合はFALSEを返す。

dpId

列挙されたプレイヤまたはグループのID。

dwPlayerType

プレイヤの型。DPPLAYERTYPE_GROUPまたはDPPLAYERTYPE_PLAYERになる。

lpName

プレイヤまたはグループの名前を含んだ変更不可能なDPNAME構造体へのポインタ。

dwFlags

IDirectPlay2::EnumGroups, IDirectPlay2::EnumGroupPlayersまたはIDirectPlay2::EnumPlayersメソッドで渡されるフラグを指定する。

lpContext

アプリケーション定義コンテキストへのポインタ。

コールバック関数に返されるすべてのポインタは一時的なものであり、コールバック関数内でのみ有効である。ポインタ情報を保存する必要があるアプリケーションは、データを保持するメモリを確保し、データをコピーし、新しいデータのポインタを保存しなければならない。この関数内のlpNameは一時的なポインタである。また、lpNameパラメータで示される構造体の中のポインタ、lpszShortName / lpszShortNameAおよびlpszLongName / lpszLongNameAも一時的なものであることに注意が必要である。


EnumSessionsCallback2

BOOL EnumSessionsCallback2(LPDPSESSIONDESC2 lpThisSD,

    LPDWORD lpdwTimeOut, DWORD dwFlags

    LPVOID lpContext);

IDirectPlay2::EnumSessionsメソッドが使用するアプリケーション定義のコールバック関数。

列挙を続ける場合はTRUE、終了する場合はFALSEを返す。

lpThisSD

列挙されたセッションを表すDPSESSIONDESC2構造体へのポインタ。列挙がタイム・アウトした場合、このパラメータにはNULLがセットされる。

lpdwTimeOut

現在のタイム・アウト値を含む変数へのポインタ。応答のためにセッションのタイム・アウト値を長くしたい場合は、DPESC_TIMEDOUTフラグが返されたときにこのパラメータをリセットすることができる。

dwFlags

通常はこのフラグには0がセットされる。

DPESC_TIMEDOUT

	列挙がタイム・アウトしたことを示す。lpdwTimeOut をリセットし、列挙を続ける場合はTRUE、終了する場合はFALSEを返す。
lpContext

アプリケーション定義のコンテキストのアドレス。

コールバック関数に返されるすべてのポインタは一時的なものであり、コールバック関数内でのみ有効である。ポインタ情報を保存する必要があるアプリケーションは、データを保持するメモリを確保し、データをコピーし、新しいデータのポインタを保存しなければならない。この関数内のlpThisSDは一時的なポインタである。 また、lpThisSDパラメータで示される構造体の中のポインタ、lpszSessionName / lpszSessionNameAおよびlpszPassword / lpszPasswordAも一時的なものであることに注意されたい。


IDirectPlay2

DirectPlayオブジェクトを作成し、システム・レベルの変数を操作するには、IDirectPlay2インターフェイスのメソッドを使用する（ IDirectPlay2Aインターフェイスは、IDirectPlay2AがANSI文字を使用し、IDirectPlay2がUnicodeを使用することを除けば、IDirectPlay2インターフェイスと同等である）。このセクションは、IDirectPlay2インターフェイスのメソッドのリファレンスである。

IDirectPlay2インターフェイスのメソッドは、次のグループに分類することができる。

データ管理	GetGroupData
	GetPlayerData
	SetGroupData
	SetPlayerData
グループ管理	AddPlayerToGroup
	CreateGroup
	DeletePlayerFromGroup
	DestroyGroup
	EnumGroupPlayers
	EnumGroups
	GetGroupName
	SetGroupName
初期化	Initialize
メッセージ管理	GetMessageCount
	Receive
	Send
プレイヤ管理	CreatePlayer
	DestroyPlayer
	EnumPlayers
	GetPlayerAddress
	GetPlayerCaps
	GetPlayerName
	SetPlayerName
セッション管理	Close
	EnumSessions
	GetCaps
	GetSessionDesc
	Open
	SetSessionDesc
IDirectPlay2インターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release


IDirectPlay2::AddPlayerToGroup

HRESULT AddPlayerToGroup(DPID idGroup, DPID idPlayer);

現存のプレイヤを現存のグループに追加する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_CANTADDPLAYER

DPERR_INVALIDOBJECT

DPERR_INVALIDPLAYER

idGroup

追加するグループのグループID。

idPlayer

グループに追加するプレイヤのプレイヤID。

グループを他のグループに追加することはできないが、プレイヤは複数のグループのメンバーになることができる。プレイヤが追加されると、DPSYS_ADDPLAYERTOGROUPシステム・メッセージが生成され、他のすべてのプレイヤに送られる。システム・メッセージのリストについてはシステム・メッセージの使用 を参照されたい。

参照　IDirectPlay2::CreateGroup, IDirectPlay2::DeletePlayerFromGroup, DPMSG_ADDPLAYERTOGROUP


IDirectPlay2::Close

HRESULT Close();

オープンしていたセッションをクローズする。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_NOSESSIONS

このメソッドを呼び出すと、ローカルに作成されたすべてのプレイヤが破棄され、対応するDPSYS_DESTROYPLAYERORGROUPシステム・メッセージが他のセッション関係者に通知される。しかし、グループは破棄されない（グループを破棄するには、IDirectPlay2::DestroyGroupを使用する）。システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

参照　IDirectPlay2::DestroyPlayer, DPMSG_DESTROYPLAYERORGROUP, IDirectPlay2::Open


IDirectPlay2::CreateGroup

HRESULT CreateGroup(LPDPID lpidGroup,

    LPDPNAME lpGroupName, LPVOID lpData,

    DWORD dwDataSize, DWORD dwFlags);

現在のセッションに存在するプレイヤの論理グループを作成する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_CANTADDPLAYER

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_OUTOFMEMORY

lpidGroup

DirectPlayグループIDで埋め尽くされる変数へのポインタ。 この値はDirectPlayによって定義される。

lpGroupName

グループの名前を持つDPNAME構造体へのポインタ。 NULLはグループが初期名を持っていないことを表す。

lpData

グループIDと関連付けるアプリケーション定義のリモート・データ・ブロックへのポインタ。 NULLはグループが初期データを持っていないことを表す。 ここで指定されたデータは、IDirectPlay2::SetGroupDataが呼び出されるときと同様、セッション中のすべてのアプリケーションに伝えられるリモート・データであると見なされる。

dwDataSize

lpDataが指すデータ・ブロックのサイズをバイト単位で指定する。

dwFlags

予約されている。使用してはいけない。

メッセージはグループに送信することができ、DirectPlayがグループ中の各プレイヤにメッセージを転送する。アプリケーションに返されたグループIDは、メッセージ伝達とデータ結合においてグループを識別するために用いられる。DirectPlayによって割り当てられたプレイヤIDとグループIDは、つねにセッションの中でユニークである。このメソッドはDPSYS_CREATEPLAYERORGROUPシステム・メッセージを生成し、他のすべてのプレイヤに送信される。システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

アプリケーションは、IDirectPlay2::SetGroupNameメソッドを使って、グループの作成時に初期グループ名を関連付けることができる。lpGroupNameの名前は人間が利用するためだけに提供され、内部では使用されないので、ユニークである必要はない。アプリケーションは、IDirectPlay2::SetGroupDataメソッドによって、グループの作成時に初期データを関連付けることができる。

参照　DPNAME, DPMSG_CREATEPLAYERORGROUP, IDirectPlay2::DestroyGroup, IDirectPlay2::EnumGroups, IDirectPlay2::EnumGroupPlayers, IDirectPlay2::Send, IDirectPlay2::SetGroupData, IDirectPlay2::SetGroupName


IDirectPlay2::CreatePlayer

HRESULT CreatePlayer(LPDPID lpidPlayer,

    LPDPNAME lpPlayerName, HANDLE hEvent,

    LPVOID lpData, DWORD dwDataSize, DWORD dwFlags);

現在のセッションにローカル・プレイヤを作成する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_CANTADDPLAYER

DPERR_CANTCREATEPLAYER

DPERR_GENERIC

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_NOCONNECTION

lpidPlayer

DirectPlayプレイヤIDで埋め尽くされる変数へのポインタ。 この値はDirectPlayによって定義される。

lpPlayerName

プレイヤの名前を持つDPNAME構造体へのポインタ。 NULLはプレイヤが初期名情報を持っていないことを表す。

hEvent

このプレイヤ宛てのメッセージ受信したときにDirectPlayによって起動される、アプリケーションが生成したイベント・オブジェクト。

lpData

プレイヤIDに関連付けるアプリケーション定義のリモート・データ・ブロックへのポインタ。 NULLはプレイヤが初期データを持っていないことを表す。ここで指定されたデータは、IDirectPlay2::SetPlayerDataが呼び出されるときと同様、セッション中のすべてのアプリケーションに伝達されるリモート・データであると見なされる。

dwDataSize

lpDataが指すデータ・ブロックのサイズをバイト単位で指定する。

dwFlags

予約されている。使用してはいけない。

ひとつのプロセスは複数のローカル・プレイヤを持つことができる。ローカル・プレイヤは、DirectPlayオブジェクトを通し、複数のコンピュータ上で実行中の任意の数のローカル・プレイヤや、リモートのプレイヤと対話することができる。アプリケーションは、返されたプレイヤIDを使用して、メッセージ伝達やデータ結合で指定するプレイヤを識別する。DirectPlayによって割り当てられたプレイヤIDとグループIDは、つねにセッションの中でユニークである。

アプリケーションは、IDirectPlay2::SetPlayerNameメソッドを使って、プレイヤの作成時に初期名を関連付けることができる。lpPlayerNameが示す名前は人間が利用するためだけに提供され、内部では使用されないため、ユニークである必要はない。アプリケーションは、IDirectPlay2::SetPlayerDataメソッドによって、プレイヤの作成時に初期データを関連付けることができる。

このメソッドが正常に終了すると、新しいプレイヤがセッションに加入したことを通知するため、セッション中の他のすべてのプレイヤにDPSYS_CREATEPLAYERORGROUPシステム・メッセージが送られる。システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

DirectPlayメッセージの取得を別のスレッドで行うアプリケーションでは、hEventパラメータを用いて同期イベントを提供することができる。このイベントは、このプレイヤがメッセージを受け取ったときにセットされる。hEventで示されるイベントは、複数のプレイヤから使用することができる。

参照　DPNAME, DPMSG_CREATEPLAYERORGROUP, IDirectPlay2::DestroyPlayer, IDirectPlay2::EnumPlayers, IDirectPlay2::Receive, IDirectPlay2::Send, IDirectPlay2::SetPlayerData, IDirectPlay2::SetPlayerName


IDirectPlay2::DeletePlayerFromGroup

HRESULT DeletePlayerFromGroup(DPID idGroup,

    DPID idPlayer);

グループからプレイヤを削除する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPLAYER

idGroup

プレイヤが削除されるグループID。

idPlayer

グループから削除されるプレイヤのプレイヤID。

プレイヤが削除されると、変更を他のプレイヤに通知するためにDPSYS_DELETEPLAYERFROMGROUPシステム・メッセージが生成される。システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

参照　IDirectPlay2::AddPlayerToGroup, DPMSG_DELETEPLAYERFROMGROUP


IDirectPlay2::DestroyGroup

HRESULT DestroyGroup(DPID idGroup);

セッションからグループを削除する。 このグループに属しているIDは、現在のセッションの間、再利用されることはない。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

idGroup

ゲームから削除されるグループID。

削除する前にグループを空にする必要はない。グループに属している個別のプレイヤは破棄されない。このメソッドは、グループに属している各プレイヤにDPSYS_DELETEPLAYERFROMGROUPシステム・メッセージを発行し、次にDPSYS_DESTROYPLAYERORGROUPシステム・メッセージを生成する。システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

参照　IDirectPlay2::CreateGroup, DPMSG_DESTROYPLAYERORGROUP


IDirectPlay2::DestroyPlayer

HRESULT DestroyPlayer(DPID idPlayer);

セッションからプレイヤを削除する。そのプレイヤ宛てのすべての未処理メッセージはメッセージ・キューから削除され、プレイヤは、属していたすべてのグループから削除される。現在のセッションの間は、プレイヤIDが再利用されることはない。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPLAYER

idPlayer

セッションから削除されるプレイヤ ID。

このメソッドは、プレイヤが属していたグループにDPSYS_DELETEPLAYERFROMGROUPシステム・メッセージを発行し、次にDPSYS_DESTROYPLAYERORGROUP システム・メッセージを生成する。システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

参照　IDirectPlay2::CreatePlayer, DPMSG_DESTROYPLAYERORGROUP


IDirectPlay2::EnumGroupPlayers

HRESULT EnumGroupPlayers(DPID idGroup,

    LPGUID lpguidInstance,

    LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,

    LPVOID lpContext, DWORD dwFlags);

現在のセッションに存在するグループのすべてのプレイヤを列挙する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_EXCEPTION

DPERR_INVALIDFLAGS

DPERR_INVALIDOBJECT

DPERR_INVALIDPLAYER

idGroup

プレイヤが列挙されるグループのグループID。

lpguidInstance

関係するDirectPlayセッションのインスタンス。DPENUMPLAYERS_SESSIONフラグが指定されないときは、このパラメータをNULLにセットしなくてはならない。

lpEnumPlayersCallback2

グループ中の各プレイヤについて呼び出されるEnumPlayersCallback2関数へのポインタ。

lpContext

コールバック関数に渡されるアプリケーション定義のコンテキストへのポインタ。

dwFlags

コールバック関数のdwFlagsパラメータに渡されるフラグ。

DPENUMPLAYERS_SESSION

	lpguidInstanceによって識別されるセッション内のグループのプレイヤを列挙する。
通常このメソッドは、現在のセッションのローカル・プレイヤ・リストを使用して列挙する。 DPENUMPLAYERS_SESSIONフラグをセッション・インスタンスGUIDとともに指定すると、セッションのホストに列挙リストの提供を要求する。このメソッドは、IDirectPlay2::EnumSessions 列挙の中から呼び出すことはできない。さらに、DPENUMPLAYERS_SESSIONフラグを使用する場合、このメソッドの呼び出しは、IDirectPlay2::EnumSessionsメソッドの呼び出しの後かつIDirectPlay2::Close およびIDirectPlay2::Openメソッドの呼び出しの前に行わなければならない。

参照　IDirectPlay2::CreatePlayer, IDirectPlay2::DestroyPlayer, IDirectPlay2::AddPlayerToGroup, IDirectPlay2::DeletePlayerFromGroup


IDirectPlay2::EnumGroups

HRESULT EnumGroups(LPGUID lpguidInstance,

    LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,

    LPVOID lpContext, DWORD dwFlags);

セッションで有効なグループを列挙する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_UNSUPPORTED

lpguidInstance

関係するDirectPlayセッションのインスタンス。DPENUMPLAYERS_SESSIONフラグを指定しない場合は、このパラメータをNULLにセットしなくてはならない。

lpEnumPlayersCallback2

セッションの各グループについて呼び出されるEnumPlayersCallback2関数へのポインタ。

lpContext

コールバック関数に渡されるアプリケーション定義のコンテキストへのポインタ。

dwFlags

コールバック関数のdwFlagsパラメータに渡されるフラグ。

DPENUMPLAYERS_SESSION

	lpguidInstance によって識別されたセッション内のグループを列挙する。
通常このメソッドは、現在のセッションのローカル・プレイヤ・リストを使用して列挙する。 DPENUMPLAYERS_SESSIONフラグをセッション・インスタンスGUIDとともに指定すると、セッションのホストに列挙リストの提供を要求する。このメソッドは、IDirectPlay2::EnumSessions 列挙の中から呼び出すことはできない。さらに、DPENUMPLAYERS_SESSIONフラグを使用する場合、このメソッドの呼び出しは、IDirectPlay2::EnumSessionsメソッドの呼び出しの後でかつIDirectPlay2::Close およびIDirectPlay2::Open メソッドの呼び出しの前に行わなければならない。

参照　IDirectPlay2::CreateGroup, IDirectPlay2::DestroyGroup, IDirectPlay2::EnumSessions


IDirectPlay2::EnumPlayers

HRESULT EnumPlayers(LPGUID lpguidInstance,

    LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,

    LPVOID lpContext, DWORD dwFlags);

セッションのプレイヤを列挙する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_EXCEPTION

DPERR_GENERIC

DPERR_INVALIDOBJECT

DPERR_UNSUPPORTED

lpguidInstance

関係するDirectPlay セッションのインスタンス。DPENUMPLAYERS_SESSIONフラグが指定されない場合、このパラメータをNULLにセットしなくてはならない。

lpEnumPlayersCallback2

セッション中の各グループについて呼び出されるEnumPlayersCallback2関数へのポインタ。

lpContext

コールバック関数に渡されるアプリケーション定義のコンテキストへのポインタ。

dwFlags

コールバック関数のdwFlagsパラメータに渡されるフラグ。

DPENUMPLAYERS_GROUP

	プレイヤの列挙にグループを含む。

DPENUMPLAYERS_LOCAL

	この DirectPlayオブジェクトによってローカルに作成されたプレイヤだけを列挙する。

DPENUMPLAYERS_REMOTE

	リモートのDirectPlayオブジェクトによって作成されたプレイヤだけを列挙する。

DPENUMPLAYERS_SESSION

	lpguidInstance によって識別されたセッション内のグループを列挙する。
通常このメソッドは、現在オープンされているセッションのプレイヤを列挙する。 グループも含めて列挙を行うには、DPENUMPLAYERS_GROUPフラグを使用する。DPENUMPLAYERS_SESSIONフラグをセッション・インスタンスGUIDとともに指定すると、セッションのホストに列挙リストの提供を要求する。このメソッドは、IDirectPlay2::EnumSessions 列挙の中から呼び出すことはできない。さらに、DPENUMPLAYERS_SESSIONフラグを使用する場合、このメソッドの呼び出しは、IDirectPlay2::EnumSessionsメソッドの呼び出しの後でかつIDirectPlay2::CloseおよびIDirectPlay2::Openメソッドの呼び出しの前に行わなければならない。

参照　IDirectPlay2::CreatePlayer, IDirectPlay2::DestroyPlayer, IDirectPlay2::EnumSessions


IDirectPlay2::EnumSessions

HRESULT EnumSessions(LPDPSESSIONDESC2 lpsd,

    DWORD dwTimeout,

    LPDPENUMSESSIONSCALLBACK2 lpEnumSessionsCallback2,

    LPVOID lpContext, DWORD dwFlags);

この DirectPlayオブジェクトで有効なセッションを列挙する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_EXCEPTION

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

lpsd

列挙されるセッションを表すDPSESSIONDESC2 構造体へのポインタ。この構造体の基準セットを満たすセッションのみが列挙される。DPSESSIONDESC2構造体のguidApplicationメンバには、アプリケーションに関連するグローバル・ユニーク識別子（GUID）をセットするか、すべてのアプリケーションを指定するにはNULLを設定する。 guidInstanceメンバには、セッション・インスタンスに固有のGUIDが分かればそれを、分からなければ、すべてのセッションを得るためにNULLをセットする。パスワードが必要な場合、lpszPasswordメンバを適切にセットする。

dwTimeout

DirectPlayが列挙メッセージへの応答を待つ全体の時間をミリ秒で指定する（列挙の間隔ではない）。このパラメータには0を設定することを推奨する。この場合、サービス・プロバイダに適当なデフォルトのタイムアウトをDirectPlayが計算する。

lpEnumSessionsCallback2

各DirectPlayセッションに応答して呼び出されるEnumSessionsCallback2関数へのポインタ。

lpContext

コールバック関数に渡されるユーザ定義のコンテキスト。

dwFlags

このパラメータに0が設定された場合、使用可能なセッションだけが列挙される（DPENUMSESSIONS_AVAILABLE）。

DPENUMSESSIONS_AVAILABLE

	このアプリケーションが参加できるすべてのセッションを列挙する。

DPENUMSESSIONS_ALL

	加入できるかどうかに関わらず、すべてのアクティブなセッションを列挙する。プレイヤ制限に達したセッションも、新しいプレイヤが無効にされたセッションも、参加が無効になったセッションも列挙される。 アプリケーションはこの構造体のdwFlagsメンバを調べ、セッションが新しいアプリケーションの参加を許可するかどうかを判定することができる。
通常このメソッドは、DirectPlayCreate 関数を用いてDirectPlayオブジェクトが作成された直後に呼び出される。セッションに接続している間や、アプリケーションがセッションを作成した後に呼び出すことはできない。IDirectPlay2::EnumSessionsは、サービス・プロバイダにネットワーク上にひとつ以上のホストの設立を要求し、それらに列挙のリクエストを送信すると動作する。応答を受信すると、列挙されるセッションが用意される。DirectPlayがこれらの応答を待つ時間はdwTimeoutパラメータによって制御される。 この時間が来ると、コールバック関数にDPESC_TIMEDOUTフラグが通知され、lpThisSDパラメータにNULL値が渡される。この時点で、列挙を続けるには、dwTimeoutに新しい値をセットしてTRUEを返す。列挙を中止するには、FALSEを返す。dwTimeoutには、0を設定しておくとよい。この場合、DirectPlayがサービス・プロバイダに適切なタイムアウトを計算する。

通常は、参加することができるセッションだけが列挙される。DPENUMSESSIONS_ALLフラグが指定されていると、新しいプレイヤを作成することができないセッションも列挙される。この場合、アプリケーションはセッションに参加できないことに注意しなくてはならない。

ロビーがアプリケーションを開始しなかったときは、サービス・プロバイダはユーザから情報を取得するダイアログを表示する場合がある。たとえば、マイクロソフト・シリアル・サービス・プロバイダはCOMポートの設定を問い合わせる、またモデム・サービス・プロバイダは電話番号を問い合わせる。また、インターネット・サービス・プロバイダはホストのIPアドレスの入力を要求する。

パスワード・プロテクトのかかったセッションでは、正しいパスワードが入力されるまで、列挙は行われない。

参照　DPSESSIONDESC2, IDirectPlay2::Open


IDirectPlay2::GetCaps

HRESULT GetCaps(LPDPCAPS lpDPCaps,

    DWORD dwFlags);

DirectPlayオブジェクトの能力を取得する。

成功すればDD_OK、失敗すれば次のエラー値を返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

lpDPCaps

DirectPlayオブジェクトの能力を受け取るDPCAPS 構造体へのポインタ。IDirectPlay2::GetCapsを使用する前に、DPCAPS構造体のdwSizeメンバを設定しなくてはならない。

dwFlags

このパラメータに0がセットされると、無保証なメッセージ交換に対する能力が計算される。

DPGETCAPS_GUARANTEED

	保証されたメッセージ配信に対する能力を取得する。
IDirectPlay2::GetPlayerCapsメソッドが要求されたプレイヤの能力を返すのに対し、このメソッドは現在のセッションの能力を返す。

参照　DPCAPS, IDirectPlay2::GetPlayerCaps, IDirectPlay2::Send


IDirectPlay2::GetGroupData

HRESULT GetGroupData(DPID idGroup,

    LPVOID lpData, LPDWORD lpdwDataSize,

    DWORD dwFlags);

IDirectPlay2::SetGroupDataによってグループIDと関連付けられた、アプリケーション固有のデータ・ブロックを取得する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

idGroup

データが要求されたグループのグループID。

lpData

アプリケーション固有のグループ・データが書き込まれるバッファのアドレス。データのサイズのみが必要な場合は、このパラメータにNULLをセットする。このとき、lpdwDataSizeパラメータには、データを保持するために必要なサイズが設定される。

lpdwDataSize

メソッドを呼び出す前にバッファのサイズで初期化される変数へのポインタ。メソッドが制御を戻した後、このパラメータにはグループ・データのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合、このパラメータには、必要なバッファ・サイズが設定される。

dwFlags

このパラメータに0をセットした場合は、リモート・データを取得する。

DPGET_REMOTE

	リモート共有されたデータ・スペースから現在のデータを取得する。

DPGET_LOCAL

	アプリケーションのローカルなデータ・セットを取得する。
DirectPlayは、ローカルおよびリモートのふたつのタイプのグループ・データを保持することができる。アプリケーションは取得するデータのタイプを指定しなくてはならない。DPSET_LOCALフラグを使うと、DirectPlayオブジェクトによってローカル・データがセットされる。 DPSET_REMOTEフラグを使うと、セッション中の任意のアプリケーションによって、リモート・データが設定される。

参照　IDirectPlay2::SetGroupData


IDirectPlay2::GetGroupName

HRESULT GetGroupName(DPPID idGroup,

    LPVOID lpData, LPDWORD lpdwDataSize);

グループと関連付けられた名前を返す。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

idGroup

名前を要求するグループのグループID。

lpData

名前データが書き込まれるバッファのアドレス。データのサイズだけを取得する場合は、このパラメータにNULLをセットする。このとき、lpdwDataSizeには、データを保持するために必要なサイズが設定される。

lpdwDataSize

メソッドを呼び出す前にバッファのサイズで初期化される変数へのポインタ。メソッドが制御を戻した後、このパラメータには名前データのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合、このパラメータには、必要なバッファのサイズが設定される。

関数が制御を戻した後、グループ名データを読み出すには、ポインタlpDataをDPNAME構造体にキャストしなくてはならない。

参照　DPNAME, IDirectPlay2::SetGroupName


IDirectPlay2::GetMessageCount

HRESULT GetMessageCount(DPID idPlayer, LPDWORD lpdwCount);

特定のローカル・プレイヤの受信キューに置かれているメッセージの数を問い合わせる。

成功すればDD_OK、失敗すれば次のエラーのいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

idPlayer

メッセージの数を取得するプレイヤのプレイヤID。プレイヤはローカルでなければならない。

lpdwCount

このメソッドが制御を戻すとき、メッセージの数が格納される変数。

参照　IDirectPlay2::Receive


IDirectPlay2::GetPlayerAddress

HRESULT GetPlayerAddress(DPID idPlayer,

    LPVOID lpAddress, LPDWORD lpdwAddressSize);

プレイヤに対するDirectPlayアドレスを取得する。DirectPlayアドレス は、特定のサービス・プロバイダを使うプレイヤのネットワーク・アドレスである。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

idPlayer

アドレスを取得するプレイヤのプレイヤID。

lpAddress

DirectPlayアドレスが書き込まれるバッファへのポインタ。データのサイズだけを取得する場合は、このパラメータにNULLをセットする。このときlpdwAddressSizeパラメータには、データを保持するために必要なサイズが設定される。

lpdwAddressSize

このメソッドを呼び出す前にバッファのサイズで初期化される変数へのポインタ。 メソッドが制御を戻した後、このパラメータには、グループ・データのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合、このパラメータには必要なバッファのサイズが設定される。


IDirectPlay2::GetPlayerCaps

HRESULT GetPlayerCaps(DPID idPlayer,

    LPDPCAPS lpPlayerCaps, DWORD dwFlags);

指定されたプレイヤの現在の能力を取得する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

idPlayer

能力を計算するプレイヤのプレイヤID。

lpPlayerCaps

能力を受け取るDPCAPS 構造体へのポインタ。IDirectPlay2::GetPlayerCaps を使用する前に、DPCAPS構造体のdwSizeメンバを設定しなくてはならない。

dwFlags

このパラメータに0を指定すると、無保証なメッセージ交換に対する能力が計算される。

DPGETCAPS_GUARANTEED

	保証されたメッセージ配信に対する能力を取得する。
IDirectPlay2::GetCapsメソッドが現在のセッションの能力を返すのに対し、このメソッドは、要求されたプレイヤの能力を返す。

参照　DPCAPS, IDirectPlay2::GetCaps, IDirectPlay2::Send


IDirectPlay2::GetPlayerData

HRESULT GetPlayerData(DPID idPlayer,

    LPVOID lpData, LPDWORD lpdwDataSize,

    DWORD dwFlags);

IDirectPlay2::SetPlayerDataによってプレイヤに関連付けられた、アプリケーション固有のデータ・ブロックを取得する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_INVALIDFLAGS

DPERR_INVALIDOBJECT

DPERR_INVALIDPLAYER

idPlayer

データを取得するプレイヤのプレイヤID。

lpData

アプリケーション固有のプレイヤ・データが書き込まれるバッファへのポインタ。 データのサイズだけを取得する場合は、このパラメータにNULLをセットする。このとき、lpdwDataSizeパラメータには、データを保持するために必要なサイズが設定される。

lpdwDataSize

このメソッドを呼び出す前にバッファのサイズで初期化される変数へのポインタ          。 メソッドが制御を戻した後、このパラメータには、グループ・データのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合、このパラメータには必要なバッファのサイズが設定される。

dwFlags

このパラメータに0をセットすると、リモート・データを取得する。

DPGET_REMOTE

	リモートで共有されたデータ・スペースから現在のデータを取得する。

DPGET_LOCAL

	このアプリケーションによるローカルなデータ・セットを取得する。
DirectPlayは、ローカルおよびリモートのふたつのタイプのグループ・データを保持することができる。アプリケーションは取得するデータのタイプを指定しなくてはならない。DPSET_LOCALフラグを使うと、DirectPlayオブジェクトによってローカル・データがセットされる。 DPSET_REMOTEフラグを使うと、セッション中の任意のアプリケーションによって、リモート・データが設定される。

参照　IDirectPlay2::SetPlayerData


IDirectPlay2::GetPlayerName

HRESULT GetPlayerName(DPID idPlayer,

    LPVOID lpData, LPDWORD lpdwDataSize);

プレイヤに関連付けられた名前を取得する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_INVALIDOBJECT

DPERR_INVALIDPLAYER

idPlayer

名前を取得するプレイヤのプレイヤID。

lpData

名前データが書き込まれるバッファのアドレス。データのサイズだけを取得する場合は、このパラメータにNULLをセットする。このとき、lpdwDataSizeパラメータには、データを保持するために必要なサイズが設定される。

lpdwDataSize

このメソッドを呼び出す前にバッファのサイズで初期化される変数。 メソッドが制御を戻した後、このパラメータには、グループ・データのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合、このパラメータには必要なバッファのサイズが設定される。

このメソッドが制御を戻した後、グループ名データを読み出すためには、ポインタlpDataをDPNAME 構造体にキャストしなくてはならない。

参照　DPNAME, IDirectPlay2::SetPlayerName


IDirectPlay2::GetSessionDesc

HRESULT GetSessionDesc(LPVOID lpData,

    LPDWORD lpdwDataSize);

現在オープンされているセッションの特性を取得する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_INVALIDOBJECT

DPERR_NOCONNECTION

lpData

セッション記述データが書き込まれるバッファへのポインタ。データのサイズだけを取得する場合は、このパラメータにNULLをセットする。このとき、lpdwDataSizeパラメータには、データを保持するために必要なサイズが設定される。

lpdwDataSize

このメソッドを呼び出す前にバッファのサイズで初期化される変数へのポインタ。 メソッドが制御を戻した後、このパラメータには、グループ・データのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合、このパラメータには必要なバッファのサイズが設定される。

このメソッドが制御を戻した後、セッション記述データを読み出すためには、ポインタlpDataをDPSESSIONDESC2 構造体にキャストしなくてはならない。

参照　DPSESSIONDESC2, IDirectPlay2::EnumSessions, IDirectPlay2::Open


IDirectPlay2::Initialize

HRESULT Initialize(LPGUID lpGUID);

このメソッドはCOMプロトコルへの対応のために提供される。

DPERR_ALREADYINITIALIZEDを返す。

lpGUID

インターフェイスを識別するためのグローバル・ユニーク識別子（GUID）のアドレス。

DirectPlayオブジェクトは作成時に初期化されるため、このメソッドはつねに返値としてDPERR_ALREADYINITIALIZED を返す。

参照　IUnknown::AddRef, IUnknown::QueryInterface


IDirectPlay2::Open

HRESULT Open(LPDPSESSIONDESC2 lpsd,

    DWORD dwFlags);

ゲーム・セッションのインスタンスを確立する。

成功すれば DD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_ACTIVEPLAYERS

DPERR_ALREADYINITIALIZED

DPERR_GENERIC

DPERR_INVALIDFLAGS

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_UNAVAILABLE

DPERR_UNSUPPORTED

DPERR_USERCANCEL

lpsd

作成または参加するセッションを表すDPSESSIONDESC2 構造体へのポインタ。

dwFlags

以下のフラグのいずれか。

DPOPEN_CREATE

	ゲーム・セッションの新しいインスタンスを作成する。

DPOPEN_JOIN

	ゲーム・セッションの既存インスタンスに参加する。
アプリケーションは、新しいセッションを作成するか（そのセッションには他のリモート・アプリケーションが参加する）、既存のセッションに参加することができる。ローカル・プレイヤが作成される前に、アプリケーションはIDirectPlay2::Openを呼び出さなくてはならない。アプリケーションが既存のセッションに参加する前には、参加可能なセッションの一覧とそれらのセッション記述を取得するために IDirectPlay2::EnumSessions を使用するべきである。新しいプレイヤが無効にされているセッションに参加しようとした場合、または参加できない場合、あるいはプレイヤ制限に達した場合、DPERR_UNAVAILABLEエラーが返される結果となる。

参照　DPSESSIONDESC2, IDirectPlay2::Close, IDirectPlay2::EnumSessions


IDirectPlay2::Receive

HRESULT Receive(LPDPID lpidFrom, LPDPID lpidTo,

    DWORD dwFlags, LPVOID lpData, LPDWORD lpdwDataSize);

メッセージ・キューからのメッセージを取得する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_GENERIC

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

DPERR_NOMESSAGES

lpidFrom

メソッドが制御を戻すとき、送信側のプレイヤIDがセットされる変数へのポインタ。 DPRECEIVE_FROMPLAYERフラグが指定されている場合は、この変数をメソッドを呼び出す前にプレイヤIDで初期化しなくてはならない。

lpidTo

メソッドが制御を戻すとき、受信側のプレイヤIDがセットされる変数へのポインタ。DPRECEIVE_TOPLAYERフラグが指定されている場合は、この変数をメソッドを呼び出す前にプレイヤIDで初期化しなくてはならない。

dwFlags

以下の制御フラグのひとつ以上の組み合わせを設定することができる。DPRECEIVE_TOPLAYERとDPRECEIVE_FROMPLAYERの両方を指定すると、最初に見つかったほうのメッセージが返される。

DPRECEIVE_ALL

	最初の使用可能なメッセージを返す。デフォルトである。

DPRECEIVE_FROMPLAYER

	lpidFromパラメータが指すプレイヤIDから送られた最初のメッセージを返す。 システム・メッセージは、プレイヤID DPID_SYSMSGから送られる

DPRECEIVE_PEEK

	他のフラグの指定に応じてメッセージを返すが、メッセージをメッセージ・キューから削除しない。

DPRECEIVE_TOPLAYER

	lpidToパラメータが指すプレイヤIDに充てられた最初のメッセージを返す。
lpData

メッセージ・データが書き込まれるバッファへのポインタ。データのサイズだけを取得する場合は、このパラメータにNULLをセットする。このとき、lpdwDataSizeパラメータには、データを保持するために必要なサイズが設定される。メッセージがプレイヤID DPID_SYSMSGから送られたものであるとき、アプリケーションはlpDataをDPMSB_GENERIC構造体にキャストし、処理を行う前にシステム・メッセージのタイプを調べるため、dwTypeメンバをチェックするべきである。

lpdwDataSize

このメソッドを呼び出す前にバッファのサイズで初期化される変数へのポインタ。 メソッドが制御を戻した後、このパラメータには、グループ・データのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合、このパラメータには必要なバッファのサイズが設定される。キューに置かれたメッセージの順序は、IDirectPlay2::Receiveの呼び出し中に変化することがある。したがって、以前のIDirectPlay2::Receive呼び出しで要求されたメモリを割り当てた後であっても、再びDPERR_BUFFERTOOSMALLエラーが返されることがある。最善の方法は、DPERR_BUFFERTOOSMALLエラーを受け取らなくなるまで、メモリを再割り当てし続けることである。

プレイヤ ID  DPID_SYSMSGから送信されるすべてのメッセージは、ホストによって生成されたシステム・メッセージである。この場合、システム・メッセージのlpDataをDPMSG_GENERICにキャストして、そのシステム・メッセージが何であるかを特定するためにdwTypeメンバを調べるべきである。

すべてのプレイヤにブロードキャストしたり、グループ内のすべてのプレイヤに送信するためにグループに宛てられたメッセージは、プレイヤID DPID_SYSMSGに送られても、送信側のプレイヤIDから来たものとして表される。アプリケーションは、ローカルなプレイヤに宛てられたメッセージだけを受け取る。lpidFromとlpidToパラメータが等しい値を示すメッセージは、プレイヤが受信することができない。

DPSESSION_NOMESSAGEIDフラグがセッションに指定されていると、lpidFromとlpidToパラメータは何も意味を持たない。

DirectPlayとともに動作するすべてのサービス・プロバイダは、データの破損を避けるため、完全性のチェックを実行する。すべての受信メッセージは検証され、データの破損が検出された場合、そのデータは廃棄（保証されていない場合）または再送（保証されている場合）される。

参照　DPMSG_GENERIC, IDirectPlay2::Send


IDirectPlay2::Send

HRESULT Send(DPID idFrom, DPID idTo, DWORD dwFlags,

    LPVOID lpData, DWORD dwDataSize);

他のプレイヤ、グループ内のプレイヤ、またはすべてのプレイヤにメッセージを送信する。

正常終了したときや、たくさんのメッセージがDirectPlayの内部キューで送信待ちの場合はDP_OKを返す。それ以外は次のエラーのいずれかを返す。

DPERR_BUSY

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

DPERR_SENDTOOBIG

idFrom

送信側のプレイヤID。プレイヤIDは、このコンピュータの上のローカルなプレイヤのひとつに対応していなくてはならない。

idTo

メッセージが送信されるプレイヤID、グループID、またはDPID_ALLPLAYERS。DPID_ALLPLAYERSを指定すると、セッション内のすべてのプレイヤにメッセージを送信する。DPSEND_OPENSTREAMやDPSEND_CLOSESTREAMフラグを使用する場合は、このパラメータにプレイヤIDを設定する。

dwFlags

メッセージの送信方法を示す。このパラメータに０をセットすると、メッセージは保証されず、標準的な優先順位で送信される。たくさんのメッセージを送ろうとしていることをDirectPlayやサービス・プロバイダに伝えるには、DPSEND_OPENSTREAMとDPSEND_CLOSESTREAMを使用する。コミュニケーション・パイプ（ストリーム）のオープン／クローズを行わずにメッセージを送信するほうが効率的な場合、サービス・プロバイダは、DPSEND_CLOSESTREAMフラグを指定してIDirectPlay2::Sendメソッドを呼び出すまで、そのプレイヤIDのストリームをオープンしたままにしておく。 DPSEND_OPENSTREAMとDPSEND_CLOSESTREAMはidToが有効なプレイヤIDであるメッセージについてのみ有効である。サービス・プロバイダは、必ずしもDPSEND_OPENSTREAMとDPSEND_CLOSESTREAMをサポートする必要はない。

DPSEND_GUARANTEED

	可能であれば保証付きの配信方法でメッセージを送信する。

DPSEND_HIGHPRIORITY

	最優先メッセージを送信する。すぐに配信するため、メッセージは強制的に送信キューの先頭に置かれ、受信アプリケーションにおいても、受信バッファの先頭に着信される。

DPSEND_OPENSTREAM

	プレイヤに数多くのメッセージを送ろうとしているとき、サービス・プロバイダに最適化のヒントを示す。

DPSEND_CLOSESTREAM

	プレイヤに送ろうとしているメッセージの数がそれほど多くなくなったことを示す。
lpData

送信されるデータへのポインタ。 実際に送信するメッセージがないときは、このパラメータを NULLにセットする。DPSEND_OPENSTREAMやDPSEND_CLOSESTREAMフラグを指定する場合、NULLにしなくてはならない。

dwDataSize

送信されるデータの長さ。

メッセージを他のプレイヤに送信するには、宛先のプレイヤIDを指定する。メッセージをプレイヤのグループに送信するには、グループに割り当てられたIDを指定する。メッセージをセッション全体に送る場合は、DPID_ALLPLAYERSプレイヤIDを指定する。IDirectDrawSurface2::Lock / IDirectDrawSurface2::Unlockの呼び出しの間、またはIDirectDrawSurface2::GetDC / IDirectDrawSurface2::ReleaseDCメソッドの呼び出しの間では、IDirectPlay2::Sendメソッドを使用することはできない。

プレイヤは、自分自身にメッセージを送信することはできない。メッセージを自分が所属するグループやDPID_ALLPLAYERSに送っても、そのメッセージのコピーをプレイヤが受け取ることはない。

DPSESSION_NOMESSAGEID が指定されているセッションでは、グループに送信したメッセージをプレイヤが受信することが可能である。この場合はDirectPlayメッセージIDヘッダ（メッセージの送信者を示す）が付加されないため、サービス・プロバイダによって自分自身からのメッセージが除外されることはない。アプリケーションは、メッセージの内容に基づいて、自分からのメッセージを判定できなくてはならない。

DPSESSION_NOMESSAGEIDが指定されると、メッセージは送信先のコンピュータ上のローカルなプレイヤのひとつに送られる。

メッセージは保証付きでも保証なしでも送信できる。デフォルトでは保証なしで送信される。この場合、DirectPlayは、受取人にメッセージが届いたことを確認しない。保証付きのメッセージを送信するには、保証なしのメッセージよりも最低2、3倍の時間が必要である。アプリケーションは、保証付きのメッセージを送信する回数を最小限に抑えるべきである。またアプリケーションは、メッセージの喪失に対応できなくてはならない。

DirectPlayとともに動作するすべてのサービス・プロバイダは、データの破損を避けるため、完全性のチェックを実行する。すべての受信メッセージは検証され、データの破損が検出された場合、そのデータは廃棄（保証されていない場合）または再送（保証されている場合）される。

メモ

このバージョンのDirectPlayでは、DPSEND_GUARANTEEDは、サービス・プロバイダがサポートする場合にだけ配信を保証する。アプリケーションは、IDirectPlay2::GetCapsを呼び出し、DPCAPS_GUARANTEEDSUPPORTEDフラグをチェックすることにより、配信が保証されているかどうかを確認できる。このフラグがセットされていなければ、DPSEND_GUARANTEEDフラグは無視され、メッセージは保証されない。次のバージョンのDirectPlayでは、保証なしのサービス・プロバイダ上でも配信の保証をインプリメントする予定であり、保証のサポートを示すCAPSフラグはつねに意味を持つようになる。 アプリケーションが保証付きのメッセージ配信を独自にインプリメントする場合、決してDPSEND_GUARANTEEDフラグを使ってはいけない。アプリケーションのパフォーマンスをテストするときは、サービス・プロバイダが保証付きのメッセージ交換をサポートするかどうかを知ることが重要である。 サポートしている場合、次のバージョンのDirectPlayの実行速度は、DPSEND_GUARANTEEDを指定しているすべての箇所で、今よりも遅くなるだろう。

参照　IDirectPlay2::Receive


IDirectPlay2::SetGroupData

HRESULT SetGroupData(DPID idGroup,

    LPVOID lpData, DWORD dwDataSize,

    DWORD dwFlags);

グループIDにアプリケーション固有のデータ・ブロックを関連付ける。

成功すればDD_OK、失敗すれば次のエラー値を返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

idGroup

データを設定するグループのグループID。

lpData

セットされるデータへのポインタ。既存のグループ・データをクリアする場合はNULLを指定する。

dwDataSize

データ・バッファのサイズ。

dwFlags

このパラメータに0を指定すると、リモート・グループ・データがセットされ、保証なしのメッセージによって通知される。

DPSET_REMOTE

	このデータはすべてのアプリケーションによって使用され、セッション内の他のすべてのアプリケーションに伝達される。

DPSET_LOCAL

	このデータはローカルな使用のためだけに用意され、伝達されることはない。

DPSET_GUARANTEED

	（可能であれば）保証付きメッセージによってデータを伝達する。このフラグはDPSET_REMOTEと一緒に指定しなくてはならない。
DirectPlayは、ローカルおよびリモートのふたつのタイプのグループ・データを保持することができる。ローカル・データは、ローカル・コンピュータ上のアプリケーションに対してのみ有効である。リモート・データは、セッション内のすべての他のアプリケーションに伝えられる。DPSESSION_NODATAMESSAGES が指定されていないセッションでは、データの変更を通知するため、すべての他のプレイヤにDPSYS_SETPLAYERORGROUPDATAシステム・メッセージが送られる。リソースへのポインタはローカル・データに格納するのが安全である。ローカル・データ・ブロックは（DPMSG_DESTROYPLAYERORGROUP システム・メッセージが送られて）グループが破棄されようとしているときにも有効であるため、アプリケーションはこれらのリソースを解放することができる。 システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

参照　DPMSG_SETPLAYERORGROUPDATA, IDirectPlay2::GetGroupData, IDirectPlay2::Send


IDirectPlay2::SetGroupName

HRESULT SetGroupName(DPID idGroup,

    LPDPNAME lpGroupName, DWORD dwFlags);

グループの作成後にグループの名前をセットする。 DPSESSION_NODATAMESSAGES が指定されていないセッションでは、名前の変更を通知するため、他のすべてのプレイヤにDPSYS_SETPLAYERORGROUPNAMEシステム・メッセージが送られる。システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_INVALIDPLAYER

idGroup

名前をセットするグループのグループID。

lpGroupName

グループの名前情報を含むDPNAME構造体へのポインタ。グループが名前情報を持たない場合は、このパラメータにNULLをセットする。

dwFlags

このパラメータに0を指定すると、すべてのリモート・システムに保証なしのメッセージによって名前が伝えられる。

DPSET_GUARANTEED

	（可能であれば）保証付きのメッセージによってデータを伝達する。
参照　DPNAME, DPMSG_SETPLAYERORGROUPNAME, IDirectPlay2::GetGroupName, IDirectPlay2::Send


IDirectPlay2::SetPlayerData

HRESULT SetPlayerData(DPID idPlayer, LPVOID lpData,

    DWORD dwDataSize, DWORD dwFlags);

プレイヤIDにアプリケーション固有のデータ・ブロックを関連付ける。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDFLAGS

DPERR_INVALIDOBJECT

DPERR_INVALIDPLAYER

idPlayer

データを設定するプレイヤのプレイヤID。

lpData

セットされるデータのポインタ。既存のプレイヤ・データをクリアする場合はNULLを指定する。

dwDataSize

データ・バッファのサイズ。

dwFlags

このパラメータに0を指定すると、リモート・プレイヤ・データがセットされ、保証なしのメッセージによって伝達される。

DPSET_REMOTE

	このデータはすべてのアプリケーションによって使用され、セッション内のすべての他のアプリケーションに伝達される。

DPSET_LOCAL

	このデータはローカルな使用のためだけに用意され、伝達されることはない。

DPSET_GUARANTEED

	（可能であれば）保証付きメッセージによってデータを伝達する。このフラグはDPSET_REMOTEと一緒に指定しなくてはならない。
DirectPlayは、ローカルおよびリモートのふたつのタイプのグループ・データを保持することができる。ローカル・データは、ローカル・コンピュータ上のアプリケーションに対してのみ有効である。リモート・データは、セッション内のすべての他のアプリケーションに伝えられる。DPSESSION_NODATAMESSAGES が指定されていないセッションでは、データの変更を通知するため、すべての他のプレイヤにDPSYS_SETPLAYERORGROUPDATAシステム・メッセージが送られる。リソースへのポインタはローカル・データに格納するのが安全である。ローカル・データ・ブロックは（DPMSG_DESTROYPLAYERORGROUP システム・メッセージが送られて）グループが破棄されようとしているときにも有効であるため、アプリケーションはこれらのリソースを解放することができる。 システム・メッセージのリストについてはシステム・メッセージの使用を参照されたい。

参照　DPMSG_SETPLAYERORGROUPDATA, IDirectPlay2::GetPlayerData, IDirectPlay2::Send


IDirectPlay2::SetPlayerName

HRESULT SetPlayerName(DPID idPlayer,

    LPDPNAME lpPlayerName, DWORD dwFlags);

プレイヤの作成後にプレイヤの名前を設定する。 DPSESSION_NODATAMESSAGES が指定されていないセッションでは、名前の変更を通知するため、他のすべてのプレイヤにDPSYS_SETPLAYERORGROUPNAMEシステム・メッセージが送られる。システム・メッセージのリストについてはシステム・メッセージの使用 を参照されたい。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT

DPERR_INVALIDPLAYER

idPlayer

名前が設定するプレイヤのプレイヤID。

lpPlayerName

プレイヤの名前情報を含むDPNAME構造体のアドレス。 プレイヤが名前情報を持たない場合は、このパラメータに NULLを設定する。

dwFlags

このパラメータに0を指定すると、すべてのリモート・システムに保証なしのメッセージによって名前が伝えられる。

DPSET_GUARANTEED

	（可能であれば）保証付きのメッセージによってデータを伝達する。
参照　DPNAME, DPMSG_SETPLAYERORGROUPNAME, IDirectPlay2::GetPlayerName, IDirectPlay2::Send


IDirectPlay2::SetSessionDesc

HRESULT SetSessionDesc(LPDPSESSIONDESC2 lpSessDesc,

    DWORD dwFlags);

このメソッドは現在サポートされていない。

現在のセッションの特性を変更する。このメソッドは、セッションのホストであるコンピュータ上で呼び出されたときのみ動作する。

DPERR_UNSUPPORTED.を返す。

lpSessDesc

新しい設定を含んでいるセッション記述構造体へのポインタ。

dwFlags

このメソッドでは現在フラグは使用されていない。

参照　DPSESSIONDESC2, IDirectPlay2::GetSessionDesc


IDirectPlayLobby

アプリケーションは、IDirectPlayLobbyインターフェイスのメソッドを使用して、アプリケーションとアプリケーションに関連付けられたデータを制御する。このセクションは、IDirectPlayLobbyインターフェイス・メソッドのリファレンスである。概念についての概要はIDirectPlayLobbyインターフェイスを参照されたい。

アドレス管理	CreateAddress
	EnumAddress
	EnumAddressTypes
アプリケーション管理	Connect
	EnumLocalApplications
	RunApplication
データ管理	GetConnectionSettings
	ReceiveLobbyMessage
	SendLobbyMessage
	SetConnectionSettings
	SetLobbyMessageEvent


IDirectPlayLobby::Connect

HRESULT WINAPI Connect(DWORD dwFlags,

    LPDIRECTPLAY2 FAR *lplpDP, IUnknown FAR *pUnk);

アプリケーションをセッションに接続する。接続には、IDirectPlayLobby::RunApplication メソッドの中でロビー・クライアントから提供される接続データ、またはIDirectPlayLobby::SetConnectionSettings の呼び出しによって設定されるデータを使用する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

CLASS_E_NOAGGREGATION

DPERR_INVALIDFLAGS

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_NOTLOBBIED

DPERR_OUTOFMEMORY

dwFlags

予約されている。0でなくてはならない。

lplpDP

有効なインターフェイスで初期化されるポインタへのポインタ。IDirectPlay2（IDirectPlayLobbyから呼び出される場合）またはIDirectPlay2A（IDirectPlayLobbyAから呼び出される場合）インターフェイスのいずれかである。

pUnk

IUnknown インターフェイスのアドレス。 このパラメータは将来のCOM集成化機能との互換性のために提供されている。現在のIDirectPlayLobby::Connectでは、このパラメータにNULL以外の値が指定されるとエラーを返す。

成功すると、正しいサービス・プロバイダにDirectPlayオブジェクトを作成し、正しいセッションをオープンする。ユーザに問い合わせのダイアログ・ボックスを表示することはない。このメソッドが失敗してDPERR_NOTLOBBIEDエラーを返す場合、アプリケーションは通常の手順を実行し、DirectPlayEnumerate、DirectPlayCreate、IDirectPlay2::EnumSessions、IDirectPlay2::Openを呼び出さなくてはならない。他のエラー値で失敗する場合は、セッションへの接続に問題がある。

このメソッドを呼び出す前に、アプリケーションを開始するために用いられる接続設定を調べることができる。このためにはIDirectPlayLobby::GetConnectionSettingsメソッドを使用する。アプリケーションは、これらの設定を変更し、IDirectPlayLobby::SetConnectionSettings メソッドによってセットし直すことができる。DPSESSIONDESC2構造体には、適切なセッション特性が設定されるように特別に注意を払わなくてはならない。特に、dwFlags、dwMaxPlayers、dwUserメンバには注意が必要である。

参照　DirectPlayCreate


IDirectPlayLobby::CreateAddress

HRESULT CreateAddress(REFGUID guidSP,

    REFGUID guidDataType, LPCVOID lpData,

    DWORD dwDataSize, LPVOID lpAddress,

    LPDWORD lpdwAddressSize);

与えられたサービス・プロバイダ固有のネットワーク・アドレスから、DirectPlayアドレスを作成する。結果のアドレスには、サービス・プロバイダのグローバル・ユニーク識別子（GUID）、およびサービス・プロバイダがネットワーク・アドレスとして解釈することができるデータが含まれる。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_INVALIDPARAMS

guidSP

サービス・プロバイダのGUIDへのポインタ （ C++ではGUIDへの参照である） 。

guidDataType

固有のネットワーク・アドレス・タイプを識別するGUIDのアドレス。定義済みのネットワーク・アドレス・タイプについてはDirectPlayアドレスを参照されたい（C++ではGUIDへの参照である）。

lpData

固有のネットワーク・アドレスを含むバッファへのポインタ。

dwDataSize

lpDataのネットワーク・アドレスのサイズをバイト単位で指定する。

lpAddress

生成されたDirectPlayアドレスが書き込まれるバッファへのポインタ。

lpdwAddressSize

DirectPlayアドレス・バッファのサイズを含む変数へのポインタ。サービス・プロバイダは、このメソッドを呼び出す前にlpdwAddressSizeをバッファのサイズで初期化しなくてはならない。 メソッドが制御を戻すと、このパラメータにはlpAddressに書き込まれたバイト数が格納される。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合、このパラメータにはDirectPlayアドレスを格納するために必要なサイズがセットされる。

参照　IDirectPlayLobby::EnumAddress


IDirectPlayLobby::EnumAddress

HRESULT EnumAddress(LPDPENUMADDRESS lpEnumAddressCallback,

    LPCVOID lpAddress, DWORD dwAddressSize,

    LPVOID lpContext);

DirectPlayアドレス・バッファからチャンクを解析する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_EXCEPTION

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

lpEnumAddressCallback

DirectPlayアドレスの各情報チャンクについて呼び出されるEnumAddressCallback 関数へのポインタ。

lpAddress

DirectPlayアドレス・バッファの先頭へのポインタ。

dwAddressSize

DirectPlayアドレスのサイズ。

lpContext

コールバック関数に渡されるコンテキスト。

参照　DirectPlayアドレス, IDirectPlayLobby::CreateAddress


IDirectPlayLobby::EnumAddressTypes

HRESULT EnumAddressTypes(

    LDDPLENUMADDRESSTYPESCALLBACK lpEnumAddressTypeCallback,

    REFGUID guidSP, LPVOID lpContext,

    DWORD dwFlags);

指定されたサービス・プロバイダがDirectPlayアドレスを構築するために必要とする、すべてのアドレス・タイプを列挙する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_EXCEPTION

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

lpEnumAddressTypeCallback

サービス・プロバイダの各アドレス・タイプについて呼び出されるEnumAddressTypeCallback関数へのポインタ。 サービス・プロバイダがアドレス・タイプをとらないなら、コールバックは呼び出されない。

guidSP

アドレスタイプを列挙するサービス・プロバイダのGUIDのアドレス （C++ではGUIDへの参照である）。

lpContext

コールバック関数に渡されるコンテキスト。

dwFlags

予約されている。0でなくてはならない。

参照　DirectPlayアドレス, IDirectPlayLobby::CreateAddress


IDirectPlayLobby::EnumLocalApplications

HRESULT EnumLocalApplications(

    LPDPENUMLOCALAPPLICATIONS lpEnumLocalAppCallback,

    LPVOID lpContext, DWORD dwFlags);

DirectPlayに登録されているアプリケーションを列挙する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_GENERIC

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_OUTOFMEMORY

lpEnumLocalAppCallback

列挙された各アプリケーションについて呼び出されるEnumLocalApplicationsCallback 関数へのポインタ。

lpContext

コールバック関数に渡されるコンテキスト。

dwFlags

予約されている。0でなくてはならない。

参照　DPLAPPINFO


IDirectPlayLobby::GetConnectionSettings

HRESULT GetConnectionSettings(DWORD dwAppID,

    LPVOID lpData, LPDWORD lpdwDataSize);

アプリケーションの開始や接続に必要なすべての情報を含むDPLCONNECTION 構造体を取得する。返されたデータは、ロビー・クライアントによってIDirectPlayLobby::RunApplication メソッドに渡されるもの、またはIDirectPlayLobby::SetConnectionSettings メソッドの呼び出しで設定されるものと同じである。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL

DPERR_GENERIC

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_NOTLOBBIED

DPERR_OUTOFMEMORY

dwAppID

ロビー・クライアントが呼び出す場合、接続設定を取得するアプリケーションを識別する（ロビー・クライアントはいくつかのアプリケーションと通信する）。アプリケーションが呼び出すときは、このパラメータは0でなくてはならない（アプリケーションは、ひとつのロビー・クライアントとしか通信しない）。このID番号はDirectPlayLobby::RunApplicationから取得される。

lpData

接続設定が書き込まれるバッファへのポインタ。 データのサイズだけを取得する場合は、このパラメータにNULLを設定する。このとき、lpdwDataSizeパラメータには、データを保持するために必要な最小のサイズが格納される。

lpdwDataSize

このメソッドを呼び出す前にバッファのサイズで初期化される変数へのポインタ。メソッドが制御を戻した後、このパラメータにはデータのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合は、このパラメータには必要な最小のバッファ・サイズが設定される。

関数が制御を戻したとき、データを読み出すためには、lpDataメンバをLPDPLCONNECTION構造体にキャストしなくてはならない。

参照　DPLCONNECTION, IDirectPlayLobby::RunApplication, IDirectPlayLobby::SetConnectionSettings


IDirectPlayLobby::ReceiveLobbyMessage

HRESULT ReceiveLobbyMessage(DWORD dwFlags,

    DWORD dwAppID, LPDWORD lpdwMessageFlags,

    LPVOID lpData, LPDWORD lpdwDataSize);

ロビー・クライアント・アプリケーションとDirectPlayアプリケーションの間で送信されるメッセージを取得する。メッセージはキューに蓄えられるため、読み出されないならデータを失う危険はない。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_APPNOTSTARTED

DPERR_BUFFERTOOSMALL

DPERR_GENERIC

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_NOMESSAGES

DPERR_OUTOFMEMORY

dwFlags

予約されている。0でなくてはならない。

dwAppID

ロビー・クライアントが呼び出す場合、接続設定を取得するアプリケーションを識別する（ロビー・クライアントはいくつかのアプリケーションと通信する）。アプリケーションが呼び出すときは、このパラメータは0でなくてはならない（アプリケーションは、ひとつのロビー・クライアントとしか通信しない）。このID番号はIDirectPlayLobby::RunApplicationから取得される。

lpdwMessageFlags

返されているメッセージのタイプを示すフラグ。

DPLAD_SYSTEM

	アプリケーションにイベントを通知するシステム・メッセージであることを示す。発生したイベントの種類を決定するには、lpDataポインタをDPLMSG_GENERICシステム・メッセージにキャストしてdwTypeメンバを有効にし、システム・メッセージの種類を調べる。
lpData

メッセージが書き込まれるバッファへのポインタ。メッセージのサイズだけを取得する場合は、このパラメータにNULLを設定する。このとき、lpdwDataSizeパラメータには、メッセージを保持するために必要な最小のサイズが格納される。

lpdwDataSize

このメソッドを呼び出す前にバッファのサイズで初期化される変数のアドレス。メソッドが制御を戻した後、このパラメータにはメッセージのサイズがバイト単位でセットされる。バッファが小さすぎる（DPERR_BUFFERTOOSMALL）場合は、このパラメータには必要な最小のバッファ・サイズが設定される。

参照　IDirectPlayLobby::RunApplication, IDirectPlayLobby::SendLobbyMessage


IDirectPlayLobby::RunApplication

HRESULT RunApplication(DWORD dwFlags,

    LPDWORD lpdwAppID, LPDPLCONNECTION lpConn,

    HANDLE hReceiveEvent);

アプリケーションを開始し、セッションとの接続に必要なすべての情報を渡す。このメソッドはロビー・クライアントによって用いられる。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_CANTCREATEPROCESS

DPERR_GENERIC

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_OUTOFMEMORY

DPERR_UNKNOWNAPPLICATION

dwFlags

予約されている。0でなくてはならない。

lpdwAppId

開始されたアプリケーションを識別するIDが格納される変数へのポインタ。ロビー・クライアントは、IDirectPlayLobby::SendLobbyMessageやIDirectPlayLobby::ReceiveLobbyMessageメソッドの呼び出しで使用するために、アプリケーションIDを保存しておかなければならない。

lpConn

開始するアプリケーションを指定し、ダイアログ・ボックスを表示せずにセッション・インスタンスに接続するために必要なすべての情報を含んだ、DPLCONNECTION構造体へのポインタ。

hReceiveEvent

ロビー・メッセージが受信されるときにセットされる同期イベントを指定する。このイベントは、IDirectPlayLobby::SetLobbyMessageEventメソッドを用いて後で変更することができる。

このメソッドはアプリケーション・プロセスが作成されると制御を戻す。ロビー・クライアントは、アプリケーションの状態を示すシステム・メッセージを受け取る。ロビー・クライアントがセッションのホスト・アプリケーションを開始している場合は、DPLSYS_SESSIONCREATEDシステム・メッセージを受信するまで、セッションに参加する他のアプリケーションの開始を待つべきである。アプリケーションがセッションの作成やセッションへの参加に失敗すると、DPLSYS_DPLAYCONNECTFAILEDメッセージが発行される。また、ロビー・クライアントは、アプリケーションが接続設定を読み出すとDPLSYS_CONNECTIONSETTINGSREADシステム・メッセージを受け取る。アプリケーションが終了するとDPLSYS_APPTERMINATED システム・メッセージを受信する。

ロビー・クライアントは、DPLSYS_CONNECTIONSETTINGSREADシステム・メッセージを受信する前にIDirectPlayLobbyインターフェイスを解放してはいけない。このメッセージは、受信するまでIDirectPlayLobby::ReceiveLobbyMessageをループしてチェックするか、同期イベントを提供することによって受け取ることができる。

参照　IDirectPlayLobby::ReceiveLobbyMessage, IDirectPlayLobby::GetConnectionSettings, IDirectPlayLobby::SetLobbyMessageEvent


IDirectPlayLobby::SendLobbyMessage

HRESULT SendLobbyMessage( DWORD dwFlags,

    DWORD dwAppID, LPVOID lpData,

    DWORD dwDataSize);

アプリケーションとロビー・クライアントの間でメッセージを送信する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_APPNOTSTARTED

DPERR_BUFFERTOOLARGE

DPERR_GENERIC

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_OUTOFMEMORY

DPERR_TIMEOUT

dwFlags

予約されている。0でなくてはならない。

dwAppID

ロビー・クライアントが呼び出す場合、接続設定を取得するアプリケーションを識別する（ロビー・クライアントはいくつかのアプリケーションと通信する）。アプリケーションが呼び出すときは、このパラメータは0でなくてはならない（アプリケーションは、ひとつのロビー・クライアントとしか通信しない）。このID番号はIDirectPlayLobby::RunApplicationから取得される。

lpData

送信するメッセージを含むバッファへのポインタ。

dwDataSize

バッファのサイズをバイト単位で指定する。

参照　IDirectPlayLobby::RunApplication, IDirectPlayLobby::ReceiveLobbyMessage


IDirectPlayLobby::SetConnectionSettings

HRESULT SetConnectionSettings(DWORD dwFlags,

    DWORD dwAppID, LPDPLCONNECTION lpConn);

アプリケーションの開始と接続に必要なすべての情報を含んだDPLCONNECTION構造体を変更する。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_GENERIC

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_OUTOFMEMORY

dwFlags

予約されている。0でなくてはならない。

dwAppID

ロビー・クライアントが呼び出す場合、接続設定を取得するアプリケーションを識別する（ロビー・クライアントはいくつかのアプリケーションと通信する）。アプリケーションが呼び出すときは、このパラメータは0でなくてはならない（アプリケーションは、ひとつのロビー・クライアントとしか通信しない）。このID番号はIDirectPlayLobby::RunApplication から取得される。

lpConn

開始するアプリケーションを指定し、ダイアログ・ボックスを表示せずにセッション・インスタンスに接続するために必要なすべての情報を含んだ、DPLCONNECTION 構造体へのポインタ。

参照　IDirectPlayLobby::GetConnectionSettings


IDirectPlayLobby::SetLobbyMessageEvent

HRESULT SetLobbyMessageEvent(DWORD dwFlags,

    DWORD dwAppID, HANDLE hReceiveEvent);

ロビー・メッセージを受け取るときにセットされるイベントを登録する。メッセージと同期をとる必要があるアプリケーションは、このメソッドを呼び出さなくてはならない。ロビー・クライアントは、このメソッドによってIDirectPlayLobby::RunApplication メソッドの呼び出しで指定されたイベントを変更することができる。

成功すればDD_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_GENERIC

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_OUTOFMEMORY

dwFlags

予約されている。0でなくてはならない。

dwAppID

ロビー・クライアントが呼び出す場合、接続設定を取得するアプリケーションを識別する（ロビー・クライアントはいくつかのアプリケーションと通信する）。アプリケーションが呼び出すときは、このパラメータは0でなくてはならない（アプリケーションは、ひとつのロビー・クライアントとしか通信しない）。このID番号はIDirectPlayLobby::RunApplicationから取得される。

hReceiveEvent

メッセージを受信したときにセットされるイベント・ハンドル。

参照　IDirectPlayLobby::ReceiveLobbyMessage, IDirectPlayLobby::SendLobbyMessage


構造体


DPCAPS

typedef struct {

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwMaxBufferSize;

    DWORD dwMaxQueueSize;

    DWORD dwMaxPlayers;

    DWORD dwHundredBaud;

    DWORD dwLatency;

    DWORD dwMaxLocalPlayers;

    DWORD dwHeaderLength;

    DWORD dwTimeout;

} DPCAPS, FAR *LPDPCAPS;

IDirectPlay2::GetCapsまたはIDirectPlay2::GetPlayerCapsメソッドの呼び出しによって、DirectPlay オブジェクトの能力を格納する。要求された能力が保証付きかそうでないかによって、これらの能力は異なってくる。この構造体は読み出し専用である。

dwSize

DPCAPS構造体のサイズをバイト単位で指定する。アプリケーションはDPCAPS構造体を使用する前にこのメンバを設定しなくてはならない。そうでない場合はエラーとなる。

dwFlags

DirectPlayオブジェクトの特性を表す。

DPCAPS_GROUPOPTIMIZED

	このDirectPlayオブジェクトに接続されたサービス・プロバイダが、グループ（マルチキャスト）配信を最適化することができることを示す。

DPCAPS_GUARANTEEDOPTIMIZED

	このDirectPlayオブジェクトに接続されたサービス・プロバイダが、保証付きのメッセージ配信をサポートすることを示す。

DPCAPS_GUARANTEEDSUPPORTED

	DirectPlayオブジェクトが保証付きのメッセージ配信をサポートしていることを示す。サービス・プロバイダがサポートしている、あるいはDirectPlayが保証なしのサービス・プロバイダ上にインプリメントしていることによる。

DPCAPS_ISHOST

	呼び出し元のアプリケーションによって作成されたDirectPlayオブジェクトが、セッション・ホストであることを示す。

DPCAPS_KEEPALIVEOPTIMIZED

	サービス・プロバイダは、セッションへの接続が失われたことを検出できる。
dwMaxBufferSize

このサービス・プロバイダが１個のパケットで送信できる最大サイズ。それよりも大きなメッセージはひとつ以上のパケットを用いて送信される。

dwMaxQueueSize

使用されない。

dwMaxPlayers

このDirectPlayオブジェクトでサポートされているローカルおよびリモートの最大プレイヤ数。

dwHundredBaud

1秒当たりのバンド幅（ボー・レート）を100ビット単位で示す。たとえばこの値が24の場合、2400ボーを示している。

dwLatency

サービス・プロバイダの推定反応時間をミリ秒で指定する。DirectPlayが反応時間を推定できない場合、この値は0である。サービス・プロバイダによっては、メッセージ・サイズの平均を考慮し、アプリケーション間テストに基づいた精度になる。反応時間は、保証付きまたは保証なしのどちらのメッセージ配信をアプリケーションが使用するかによって異なる。

dwMaxLocalPlayers

セッションでサポートされるローカル・プレイヤの最大数。

dwHeaderLength

DirectPlayオブジェクトによってプレイヤ・メッセージに付加されるヘッダのサイズをバイト単位で示す。ヘッダ・サイズは使用しているサービス・プロバイダによって異なる。

dwTimeout

サービス・プロバイダが推奨するタイムアウト値。通常DirectPlayは、メッセージの応答を待つときにこのタイムアウト値を使用する。

参照　IDirectPlay2::Send


DPCOMPORTADDRESS

typedef struct DPCOMPORTADDRESS{

    DWORD dwComPort;

    DWORD dwBaudRate;

    DWORD dwStopBits;

    DWORD dwParity;

    DWORD dwFlowControl;

} DPCOMPORTADDRESS;

typedef DPCOMPORTADDRESS FAR* LPDPCOMPORTADDRESS;

COMポートの構成についての情報を含む。

dwComPort

使用するCOMポートの番号を示す。このメンバの値は1、2、3、または4である。

dwBaudRate

COMポートのボーを示す。以下の値のいずれかである。

CBR_110	CBR_300	CBR_600
CBR_1200	CBR_2400	CBR_4800
CBR_9600	CBR_14400	CBR_19200
CBR_38400	CBR_56000	CBR_57600
CBR_115200	CBR_128000	CBR_256000
dwStopBits

ストップ・ビット長を示す。このメンバの値はONESTOPBIT、ONE5STOPBITS、またはTWOSTOPBITSである。

dwParity

COMポートが使用するパリティチェックを示す。このメンバの値は NOPARITY、ODDPARITY、EVENPARITY、またはMARKPARITYである。

dwFlowControl

COMポートが使用するフロー制御の方法を示す。以下の値のいずれかを使用できる。

DPCPA_DTRFLOW	DTRを使用したハードウェア・フロー制御を示す。
DPCPA_NOFLOW	フロー制御を行わないことを示す。
DPCPA_RTSDTRFLOW	RTSおよびDTRを使用したハードウェア・フロー制御を示す。
DPCPA_RTSFLOW	RTSを使用したハードウェア・フロー制御を示す。
DPCPA_XONXOFFFLOW	ソフトウェア・フロー制御（xon/xoff）を示す。
ボーレート、ストップ・ビット、パリティを定義する定数は、Winbase.hで定義されている。


DPLAPPINFO

typedef struct DPLAPPINFO {

DWORD dwSize;

GUID guidApplication;

union

{

    LPSTR  lpszAppNameA;

    LPWSTR lpszAppName;

};

} DPLAPPINFO, * LPDPLAPPINFO;

レジストリに格納され、IDirectPlayLobby::EnumLocalApplicationsコールバック関数に渡される、アプリケーションについての情報を含む。

dwSize

DPLAPPINFO構造体のサイズをバイト単位で指定する。アプリケーションはDPLAPPINFO構造体を使用する前にこのメンバを設定しなくてはならない。そうでない場合はエラーとなる。

guidApplication

アプリケーションのグローバル・ユニーク識別子（GUID）。

lpszAppNameA, lpszAppName

アプリケーションの名前を示すANSIまたはUnicode文字列。文字列の型は使用しているインターフェイスによる。


DPLCONNECTION

typedef struct {

    DWORD            dwSize;

    DWORD            dwFlags;

    LPDPSESSIONDESC2 lpSessionDesc;

    LPDPNAME         lpPlayerName;

    GUID             guidSP;

    LPVOID           lpAddress;

    DWORD            dwAddressSize;

} DPLCONNECTION, *LPDPLCONNECTION;

アプリケーションをセッションに接続するために必要な情報を含む。

dwSize

DPLCONNECTION構造体のサイズをバイト単位で指定する。アプリケーションはDPLCONNECTION構造体を使用する前にこのメンバを設定しなくてはならない。そうでない場合はエラーとなる。

dwFlags

接続方法を示す。

DPLCONNECTION_CREATESESSION

	セッション記述にしたがって新しいセッションを作成する。

DPLCONNECTION_JOINSESSION

	セッション記述にしたがって既存のセッションに参加する。
lpSessionDesc

作成または参加するセッションを表すDPSESSIONDESC2構造体へのポインタ。

lpPlayerName

プレイヤ作成時に使用される名前を示すDPNAME構造体へのポインタ。これは、ロビーで登録された人の名前になる。アプリケーションは、この名前を無視することができる。

guidSP

セッションに接続するために使用するサービス・プロバイダのグローバル・ユニーク識別子（GUID）。

lpAddress

サービス・プロバイダがセッションに接続するために必要な情報を含むDirectPlayアドレスへのポインタ。

dwAddressSize

アドレス・データのサイズをバイト単位で指定する。


DPNAME

typedef struct {

    DWORD dwSize;

    DWORD dwFlags;

    union {

        LPWSTR lpszShortName;

        LPSTR  lpszShortNameA;

    };

    union {

        LPWSTR lpszLongName;

        LPSTR  lpszLongNameA;

    };

} DPNAME,FAR *LPDPNAME;

プレイヤやグループなどのDirectPlayエンティティの名前情報を含む。

dwSize

DPNAME構造体のサイズをバイト単位で指定する。アプリケーションはDPNAME構造体を使用する前にこのメンバを設定しなくてはならない。そうでない場合はエラーとなる。

dwFlags

構造体に固有のフラグ。現在は0である。

lpszShortName and lpszLongName

短い名前（ニックネーム）と長い（正式な）プレイヤ名またはグループ名を含むUnicode文字列へのポインタはIDirectPlay2インターフェイスを使用している場合のみ使用する。

lpszShortNameA and lpszLongNameA

短い名前（ニックネーム）と長い（正式な）プレイヤ名またはグループ名を含むANSI文字列へのポインタ。このメンバはIDirectPlay2Aインターフェイスを使用している場合のみ使用する。

参照　IDirectPlay2::CreateGroup, IDirectPlay2::CreatePlayer, IDirectPlay2::GetGroupName, IDirectPlay2::GetPlayerName, IDirectPlay2::SetGroupName, IDirectPlay2::SetPlayerName


DPSESSIONDESC2

typedef struct {

    DWORD dwSize;

    DWORD dwFlags;

    GUID  guidInstance;

    GUID  guidApplication;

    DWORD dwMaxPlayers;

    DWORD dwCurrentPlayers;

    union  {

        LPWSTR lpszSessionName;

        LPSTR  lpszSessionNameA;

    };

    union  {

        LPWSTR lpszPassword;

        LPSTR  lpszPasswordA;

    };

    DWORD dwReserved1;

    DWORD dwReserved2;

    DWORD dwUser1;

    DWORD dwUser2;

    DWORD dwUser3;

    DWORD dwUser4;

} DPSESSIONDESC2, FAR *LPDPSESSIONDESC2;

IDirectPlay2 セッションの能力についての記述を含む。 （DPSESSIONDESC構造体はIDirectPlay2インターフェイスでは使用されない）

dwSize

DPSESSIONDESC2構造体のサイズをバイト単位で指定する。アプリケーションはDPSESSIONDESC2構造体を使用する前にこのメンバを設定しなくてはならない。そうでない場合はエラーとなる。

dwFlags

以下のフラグの組み合わせ。

DPSESSION_JOINDISABLED

	新しいアプリケーションはこのセッションに加わることができない。  DPOPEN_JOINフラグとこのセッション・インスタンスのグローバル・ユニーク識別子（GUID）を指定してIDirectPlay2::Openメソッドを呼び出しても、必ずエラーとなる。このフラグが指定されていなければ、セッション・プレイヤ数の制限に達するまで、新しいリモート・アプリケーションはセッションに参加することができる。

DPSESSION_KEEPALIVE

	リモート・プレイヤがゲームを異常終了したことを自動的に検出する。 これらのプレイヤはセッションから削除される。一時的にネットワークの機能が停止したことによってプレイヤが削除された場合、そのプレイヤが戻ってきたとき、セッションから除外されたことが通知される。詳しくは、システム・メッセージの使用の中のDPSYS_SESSIONLOSTシステム・メッセージについての記述を参照されたい。このフラグが指定されていなければ、DirectPlayはこの機能をサポートしない。

DPSESSION_MIGRATEHOST

	現在のホストが終了する場合、新しいプレイヤの参加を続けることができるように、ホストを別のコンピュータに移そうとする。このフラグが指定されていなければ、ホストは移動せず、新しいプレイヤを作成することはできない。

DPSESSION_NEWPLAYERSDISABLED

	新しいプレイヤをセッションに作成できないことを示す。 アプリケーションがこのセッションに対してIDirectPlay2::CreatePlayer メソッドを呼び出しても、必ずエラーとなる。新しいアプリケーションがセッションに参加することもできない。このフラグが指定されていなければ、セッション・プレイヤ数の制限に達するまでプレイヤを作成することができる。

DPSESSION_NODATAMESSAGES

	IDirectPlay2::SetPlayerData、IDirectPlay2::SetGroupData、IDirectPlay2::SetPlayerName、IDirectPlay2::SetGroupNameメソッドによってリモート・プレイヤ・データやリモート・グループ・データが変更されたとき、システム・メッセージを送信しない。このフラグが指定されていなければ、データの変更を示すメッセージが生成される。

DPSESSION_NOMESSAGEID

	メッセージの送信者と受信者を示すデータをメッセージに付加しない。この情報が重要でなければ、メッセージ・オーバーヘッドを節約することができる。（詳細はIDirectPlay2::Receiveメソッドを参照） このフラグが指定されていなければ、メッセージＩＤが付加される。
guidInstance

セッション・インスタンスのGUID。

guidApplication

セッション・インスタンスで実行するアプリケーションのGUID。これはユニークにアプリケーションを識別するため、DirectPlayは同じアプリケーションを走らせている他のコンピュータにだけ接続する。すべてのアプリケーションに対するセッションを列挙するには、このメンバにGUID_NULLを指定する。

dwMaxPlayers

このセッションで許される最大プレイヤ数。

dwCurrentPlayers

このセッションの現在のプレイヤ数。

lpszSessionName and lpszPassword

セッションの名前とパスワードを含むUnicode文字列へのポインタ。このメンバはIDirectPlay2インターフェイスを使用している場合のみ使用する。

lpszSessionNameA and lpszPasswordA

セッションの名前とパスワードを含むANSI文字列へのポインタ。このメンバはIDirectPlay2Aインターフェイスを使用している場合のみ使用する。

dwReserved1 and dwReserved2

将来のために予約されている。

dwUser1, dwUser2, dwUser3, and dwUser4

セッションのためのアプリケーション固有のデータ。

参照　IDirectPlay2::EnumSessions, IDirectPlay2::GetSessionDesc


システム・メッセージ


DPLMSG_GENERIC

typedef struct {

    DWORD dwType;

} DPL_GENERIC, *LPDPLMSG_GENERIC;

ロビー・クライアントとアプリケーション間で渡されるシステム・メッセージの汎用構造体。

dwType

受け取ったシステム・メッセージの種類を識別する。

DPLSYS_APPTERMINATED

	IDirectPlayLobby::RunApplicationが終了し、アプリケーションが開始したことを表す。

DPLSYS_CONNECTIONSETTINGSREAD

	IDirectPlayLobby::RunApplicationメソッドが接続設定を読み出し、アプリケーションが開始したことを表す。

DPLSYS_DPLAYCONNECTFAILED

	IDirectPlayLobby::RunApplicationがセッションへの接続に失敗し、アプリケーションが開始したことを表す。

DPLSYS_DPLAYCONNECTSUCCEEDED

	IDirectPlayLobby::RunApplicationがセッションを作成して他のアプリケーションを参加させる準備ができたか、セッションへの参加が成功したことにより、アプリケーションが開始したことを表す。


DPMSG_ADDPLAYERTOGROUP

typedef struct{

    DWORD dwType;

    DPID  dpIdGroup;

    DPID  dpIdPlayer;

} DPMSG_ADDPLAYERTOGROUP, *LPDPMSG_ADDPLAYERTOGROUP;

DPSYS_ADDPLAYERTOGROUPおよびDPSYS_DELETEPLAYERFROMGROUPシステム・メッセージの情報を含む。 システムは、プレイヤがグループに追加または削除されたときにこれらのメッセージを送信する。

dwType

メッセージを識別する。このメンバはDPSYS_ADDPLAYERTOGROUPまたはDPSYS_DELETEPLAYERFROMGROUPである。

dpIdGroup

プレイヤが追加または削除されるグループのグループID。

dpIdPlayer

指定されたグループに追加される、または指定されたグループから削除されるプレイヤのプレイヤID。

参照　IDirectPlay2::AddPlayerToGroup, IDirectPlay2::DeletePlayerFromGroup


DPMSG_CREATEPLAYERORGROUP

typedef struct{

    DWORD  dwType;

    DWORD  dwPlayerType;

    DPID   dpId;

    DWORD  dwCurrentPlayers;

    LPVOID lpData;

    DWORD  dwDataSize;

    DPNAME dpnName;

} DPMSG_CREATEPLAYERORGROUP, *LPDPMSG_CREATEPLAYERORGROUP;

DPSYS_CREATEPLAYERORGROUPシステム・メッセージの情報を含む。システムは、プレイヤおよびグループがセッションに作成されたときにこのメッセージを送信する。

dwType

メッセージを識別する。このメンバにはDPSYS_CREATEPLAYERORGROUPがセットされる。

dwPlayerType

メッセージがプレイヤ（DPPLAYERTYPE_PLAYER）とグループ（DPPLAYERTYPE_GROUP）のどちらに適用されるかを示す。

dpId

プレイヤIDとグループIDのどちらが作成されたかを示す。

dwCurrentPlayers

そのセッションでの現在のプレイヤおよびグループの数。そのとき追加されたものも含む。

lpData

このプレイヤまたはグループに関連付けられた、アプリケーション固有のリモート・データへのポインタ。 このメンバーがNULLのときは、リモート・データはない。

dwDataSize

lpData によって参照されるバッファを含むデータのサイズ。

dpnName

プレイヤまたはグループの名前を含む構造体。

参照　IDirectPlay2::CreateGroup, IDirectPlay2::CreatePlayer


DPMSG_DELETEPLAYERFROMGROUP

typedef DPMSG_ADDPLAYERTOGROUP     DMSG_DELETEPLAYERFROMGROUP;

typedef DPMSG_DELETEPLAYERFROMGROUP     *LPDPMSG_DELETEPLAYERFROMGROUP;

DPSYS_DELETEPLAYERFROMGROUPシステム・メッセージの情報を含む。 この構造体メンバのについてはDPMSG_ADDPLAYERTOGROUP構造体を参照されたい。


DPMSG_DESTROYPLAYERORGROUP

typedef struct{

    DWORD  dwType;

    DWORD  dwPlayerType;

    DPID   dpId;

    LPVOID lpLocalData;

    DWORD  dwLocalDataSize;

    LPVOID lpRemoteData;

    DWORD  dwRemoteDataSize;

} DPMSG_DESTROYPLAYERORGROUP, *LPDPMSG_DESTROYPLAYERORGROUP;

DPSYS_DESTROYPLAYERORGROUPシステム・メッセージの情報を含む。 システムは、プレイヤやグループがセッションに削除されたときにこれらのメッセージを送信する。

dwType

メッセージを識別する。このメンバにはDPSYS_DESTROYPLAYERORGROUPがセットされる。

dwPlayerType

メッセージがプレイヤ（DPPLAYERTYPE_PLAYER）とグループ（DPPLAYERTYPE_GROUP）のどちらに適用されるかを示す。

dpId

プレイヤIDとグループIDのどちらが削除されたかを示す。

lpLocalData

このプレイヤまたはグループに関連付けられたローカル・データへのポインタ。

dwLocalDataSize

ローカル・データのサイズ。

lpRemoteData

このプレイヤまたはグループに関連付けられたリモート・データへのポインタ。

dwRemoteDataSize

リモート・データのサイズ。

参照　IDirectPlay2::DestroyGroup, IDirectPlay2::DestroyPlayer


DPMSG_GENERIC

typedef struct{

    DWORD dwType;

} DPMSG_GENERIC, *LPDPMSG_GENERIC;

この構造体はメッセージ処理のために提供される。

dwType

システム・メッセージの種類を識別する。

システム・メッセージを受信したとき（つまり、lpidFromパラメータによって示された値がDPID_SYSMSGに等しいとき）、まず未知のメッセージ・データをDPMSG_GENERIC型にキャストし、次にdwTypeの値に基づいて以後の処理を行う。メッセージの種類が決定されると、以後の処理のために、メッセージを既知のシステム・メッセージのひとつにキャストすることができる。


DPMSG_HOST

typedef DPMSG_GENERIC    DPMSG_HOST;

typedef DPMSG_HOST    *LPDPMSG_HOST;

現在のセッション・ホストがセッションを終了するとき、このメッセージはホスト任務を継承するコンピュータの上のすべてのプレイヤに送信される。


DPMSG_SESSIONLOST

typdef DPMSG_GENERIC    DPMSG_SESSIONLOST;

typedef DPMSG_SESSIONLOST    *LPDPMSG_SESSIONLOST;

セッション中の他のすべてのプレイヤへの接続が失われたとき、DirectPlayによってこのメッセージが生成される。セッションが失われた後は、リモート・プレイヤにメッセージを送ることはできない。しかし、セッションが失われた時点のすべてのデータがまだ有効である。このメッセージを受け取ったら、アプリケーションは速やかに復旧し、終了するべきである。


DPMSG_SETPLAYERORGROUPDATA

typedef struct {

    DWORD  dwType;

    DWORD  dwPlayerType;

    DPID   dpId;

    LPVOID lpData;

    DWORD  dwDataSize;

} DPMSG_SETPLAYERORGROUPDATA, *LPDPMSG_SETPLAYERORGROUPDATA;

C DPSYS_SETPLAYERORGROUPDATAシステム・メッセージの情報を含む。

dwType

メッセージを識別する。このメンバはつねにDPSYS_SETPLAYERORGROUPDATAである。

dwPlayerType

メッセージがプレイヤ（DPPLAYERTYPE_PLAYER）とグループ（DPPLAYERTYPE_GROUP）のどちらに適用されるかを示す。

dpId

データが変更されたプレイヤIDあるいはグループ ID。

lpData

データのアプリケーション特有データ・ブロックへのポインタ。

dwDataSize

lpData によって参照されるバッファを含むデータのサイズ。

システムは、アプリケーションがリモート・プレイヤやリモート・グループのデータを変更したときにこのメッセージを送信する。アプリケーションはこのメッセージからのデータを保存する必要はなく、IDirectPlay2::GetGroupDataまたはIDirectPlay2::GetPlayerDataメソッドにDPGET_REMOTEフラグを指定して呼び出せば、いつでもデータを取り戻すことができる。DPSESSION_NODATAMESSAGESフラグが指定されているセッションでは、このメッセージは生成されない。

参照　IDirectPlay2::GetGroupData, IDirectPlay2::GetPlayerData, IDirectPlay2::SetGroupData, IDirectPlay2::SetPlayerData


DPMSG_SETPLAYERORGROUPNAME

typedef struct {

    DWORD  dwType;

    DWORD  dwPlayerType;

    DPID   dpId;

    DPNAME dpnName;

} DPMSG_SETPLAYERORGROUPNAME, *LPDPMSG_SETPLAYERORGROUPNAME;

DPSYS_SETPLAYERORGROUPNAMEシステム・メッセージの情報を含む。

dwType

メッセージを識別する。このメンバはつねにDPSYS_SETPLAYERORGROUPNAMEである。

dwPlayerType

メッセージがプレイヤ（DPPLAYERTYPE_PLAYER）とグループ（DPPLAYERTYPE_GROUP）のどちらに適用されるかを示す。

dpId

名前が変更されたプレイヤIDあるいはグループID。

dpnName

プレイヤあるいはグループの新しい名前の情報を含む構造体。

システムは、プレイヤやグループの名前が変更されたときにこのメッセージを送信する。アプリケーションはこのメッセージからのデータを保存する必要はなく、IDirectPlay2::GetGroupNameまたはIDirectPlay2::GetPlayerNameメソッドを使用すれば、いつでもデータを取り戻すことができる。DPSESSION_NODATAMESSAGESフラグが指定されているセッションでは、このメッセージは生成されない。

参照　IDirectPlay2::GetGroupName, IDirectPlay2::GetPlayerName, IDirectPlay2::SetGroupName, IDirectPlay2::SetPlayerName


返値

エラー は負の値で表され、複数の値が組み合わされることはない。この表は、すべての IDirectPlay2とIDirectPlayLobbyメソッドによって返される値を示している。それぞれのメソッドが返すエラー値のリストについては、各メソッドの説明を参照されたい。

CLASS_E_NOAGGREGATION

	DirectPlayCreate、DirectPlayLobbyCreate、IDirectPlayLobby::ConnectのpUnkOuterパラメータにNULL以外の値が渡された。

DP_OK

	要求は正常に完了した。

DPERR_ACCESSDENIED

	セッションが満員か、間違ったパスワードが与えられた。

DPERR_ACTIVEPLAYERS

	有効なプレイヤが存在するため、要求された処理が実行できない。

DPERR_ALREADYINITIALIZED

	このオブジェクトはすでに初期化されている。

DPERR_APPNOTSTARTED

	このアプリケーションはまだ開始されていない。

DPERR_BUFFERTOOLARGE

	データ・バッファが大きすぎるため、格納することができない。

DPERR_BUFFERTOOSMALL

	与えられたバッファは、要求したデータを収容するのに十分な大きさではない。

DPERR_BUSY

	DirectPlayメッセージ・キューがいっぱいである。

DPERR_CANTADDPLAYER

	プレイヤをセッションに追加できない。

DPERR_CANTCREATEGROUP

	新しいグループを作成できない。

DPERR_CANTCREATEPLAYER

	新しいプレイヤを作成できない。

DPERR_CANTCREATEPROCESS

	アプリケーションを実行できない。

DPERR_CANTCREATESESSION

	新しいセッションを作成できない。

DPERR_CAPSNOTAVAILABLEYET

	DirectPlayオブジェクトの能力がまだ決定されていない。このエラーは、使用可能なバンド幅と待ち時間の決定にポーリングが必要な接続方式上にDirectPlayオブジェクトがインプリメントされている場合に発生することがある。

DPERR_EXCEPTION

	要求を処理するときに例外が発生した。

DPERR_GENERIC

	定義されていないエラーが状態が発生した。

DPERR_INVALIDFLAGS

	関数に渡されたフラグが無効である。

DPERR_INVALIDINTERFACE

	インターフェイスのパラメータが無効である。

DPERR_INVALIDOBJECT

	DirectPlayオブジェクトのポインタが無効である。

DPERR_INVALIDPARAMS

	関数に渡されたひとつ以上のパラメータが無効である。

DPERR_INVALIDPLAYER

	プレイヤIDは、このゲーム・セッションで有効なプレイヤIDとして認識されない。

DPERR_NOCAPS

	DirectPlayが使おうとしている通信リンクは、この関数では実行できない。

DPERR_NOCONNECTION

	通信リンクが確立されていない。

DPERR_NOINTERFACE

	このインターフェイスはサポートされていない。

DPERR_NOMESSAGES

	受信されたメッセージがない。

DPERR_NONAMESERVERFOUND

	ネームサーバ（ホスト）が見つからない。プレイヤの作成にはホストが必要である。

DPERR_NOPLAYERS

	このセッションには有効なプレイヤがいない。

DPERR_NOSESSIONS

	このゲームには既存のセッションがない。

DPERR_NOTLOBBIED

	IDirectPlayLobby::RunApplicationによってアプリケーションが開始されなかった場合、IDirectPlayLobby::Connectが返すエラー値。

DPERR_OUTOFMEMORY

	要求された処理を実行するのに十分なメモリがない。

DPERR_PLAYERLOST

	セッションに接続していたプレイヤがいなくなった。

DPERR_SENDTOOBIG

	IDirectPlay2::Sendメソッドに渡されたメッセージ・バッファが 許可されているよりも大きい。

DPERR_SESSIONLOST

	セッションへの接続が失われた。

DPERR_TIMEOUT

	指定された時間内に処理が終了しなかった。

DPERR_UNAVAILABLE

	要求された関数は現在有効ではない。

DPERR_UNKNOWNAPPLICATION

	不明なアプリケーションが指定された。

DPERR_UNSUPPORTED

	この関数は現在のバージョンでは有効ではない。

DPERR_USERCANCEL

	IDirectPlay2::Openメソッド呼び出しの途中で、接続プロセスがユーザによってキャンセルされた。


Direct3Dについて

Microsoftの拡張3Dグラフィックス・ソリューションには、Direct3D�およびOpenGLのアプリケーション・プログラミング・インターフェイス（API）が含まれている。

次の図は、Windowsのグラフィックス・システムと、Win32ｮ APIで記述されたアプリケーション、その他のWindowsシステム、およびハードウェアとの関係を示したものである。


Direct3D

Direct3Dは、現在主流となっているパーソナルコンピュータ（PC）をデスクトップやインターネット上で使用するユーザのためにMicrosoftが提供する、リアルタイムでインタラクティブな3D技術である。Direct3Dは高速動作を第一にデザインされている。

Direct3Dは、開発者が必要とするAPIサービスとデバイス非依存性を提供し、ハードウェア・ベンダーには一般的なドライバ・モデルを供給する。Direct3Dによって、パーソナル・コンピュータの製造元は3Dグラフィック環境をすぐにサポートすることができ、エンド・ユーザがシステムにハイエンドな3Dグラフィック環境を追加することも簡単になる。システムはわずかなメモリしか必要としないため、インストール済みのほとんどのコンピュータ・システム上で快適に動作する。

Direct3Dはリアル・タイム 3D グラフィックス・サービスの完全セットであり、ソフトウェア・ベースの高速なレンダリング・パイプライン（変換、照明、ラスタ処理）や、ハードウェア・アクセラレータへの直接的なアクセスを実現する。APIサービスには、統一された高レベルな保持モードAPIと、低レベルな直接モードAPIがあり、Direct3Dを使用して3Dハードウェア・アクセラレータにアクセスするシステムをサポートする。Direct3Dは完全にスケーラブルで、ハードウェアは、Direct3Dによって3Dレンダリング・パイプラインの一部または全部を高速化することができる。Direct3Dは、Zバッファリング、アンチエイリアシング、アルファ・ブレンディング、ミップマップ、エフェクト、正確なパースによるテクスチャ・マッピングなどの、3Dハードウェア・アクセラレータの拡張グラフィックス能力を生かすことができる。Direct3Dは他のDirectXテクノロジーと完全に統合されているため、ビデオ・マッピング、2Dのオーバーレイ・プレーンでの3Dレンダリング、スプライトといった拡張機能も搭載している。これによって、インタラクティブなメディア・タイトルで、シームレスに2Dと3Dのグラフィックスを使用することができる。

Direct3Dのインプリメント方法には、保持モードと直接モードという、まったく異なる ふたつのモードがある。保持モードは、アプリケーションがグラフィック・データを保持する高レベルAPIである。直接モード は、アプリケーションが明示的に実行バッファにデータを出力する低レベルAPIである。

この章では、Direct3Dの直接モードと保持モードについて説明するとともに、Direct3Dを通して利用することができるハードウェア・アブストラクション（抽象化）とエミュレーションについても取り扱う。

保持モード

直接モード

ハードウェア・アブストラクション（抽象化）とエミュレーション


保持モード

Direct3Dの保持モードAPIは、3Dオブジェクトの操作と3Dグラフィックスの処理のために設計されている。保持モードを用いれば、既存の Windowsアプリケーションへの3D機能の追加や、新しい3Dアプリケーションの作成を容易に行うことができる。保持モードに組み込まれているジオメトリ・エンジンは、キーフレーム・アニメーションのような拡張機能をサポートしており、オブジェクト・データベースの作成やオブジェクトの内部構造体の管理を必要としない。つまりアプリケーションは、定義済みの 3D オブジェクトをロードする呼び出しを1回行えば、APIが提供する簡単なメソッドを使用して、リアルタイム・シーンのオブジェクトを内部のジオメトリ・エンジンを意識せずに操作できるようになる。

保持モードは直接モードの上部に組み立てられており、完全にDirectDrawｮアプリケーション・プログラミング・インターフェイス（API）に統合されている。Microsoftは、将来のバージョンのWindowsに保持モードを組み入れる予定である。詳しくは「DirectDraw」および「イントロダクション: Direct3Dの保持モード・オブジェクト」を参照されたい。


直接モード

Direct3Dの直接モードは、Microsoftの低レベル3D APIである。直接モードを用いると、ゲームやその他のハイ・パフォーマンスなマルチメディア・アプリケーションを、Windowsオペレーティング・システム上で実現することができる。

直接モードは、ハードウェア機能へのアクセスを可能にするリアルタイム3Dアクセラレータの上に位置する、薄いレイヤである。また、ハードウェアが提供しない機能についても、最高のソフトウェア・レンダリングを提供する場合がある。直接モードでは、開発者自身のレンダリング技術や操作技術に柔軟性を持たせることができる。

直接モードとは、低レベルでアクセラレータ・ハードウェアと通信するための、デバイスに依存しない方法である。

保持モードと異なり、直接モードはジオメトリ・エンジンを提供しない。このため、直接モードを利用するアプリケーションは、独自のオブジェクトや画面制御ルーチンを用意しなくてはならない。したがって、直接モードを効率的に用いるためには、3Dグラフィックのプログラミングについての十分な知識が必要である。

Direct3DはOLEコンポーネント・オブジェクト・モデル（COM）に基づいており、DirectDrawと完全に統合されている。Microsoftは、将来のバージョンのWindowsにDirect3Dを組み込む予定である。詳しくは「イントロダクション: Direct3Dの直接モード・オブジェクト」を参照されたい。


ハードウェア・アブストラクションとエミュレーション
ハードウェア・アブストラクション(抽象化)とエミュレーション

Direct3D APIは、他のDirectX APIと同様に、ハードウェア・アブストラクション・レイヤ （HAL）の上に組み込まれている。HALはハードウェアのデバイス依存性を隠蔽する。Direct3D HALによってサポートされない部分は、ハードウェア・エミュレーション・レイヤ（HEL）によって補完される。 Direct3D HELは、ハードウェアが提供しない機能をソフトウェア的にエミュレートする。これらのハードウェア・アブストラクション（抽象化）とエミュレーションの組み合わせによって、APIサービスがつねに利用できるようになっている。

Direct3D HALは、DirectDraw HALやGDIディスプレイ・ドライバと完全に統合されている。HALは、MicrosoftのグラフィックAPIへの単一インターフェイスと、3Dアクセラレータの統一されたドライバ・モデルをハードウェア製品に提供する。ハードウェア製品は、Direct3DやDirectDraw、GDI、OpenGLを高速化するドライバ単体のみを用意すればよい。ドライバによって、ハードウェアは、ジオメトリ変換を含む3Dグラフィックスのレンダリング・パイプ、3Dクリッピング、ラスタ処理の全部または一部を高速化することができる。Direct3D HALは、現在利用できるグラフィック・アクセラレータに加え、将来のものにも対応できるように設計されている。


DirectDraw

DirectDrawは、ディスプレイにグラフィックスを表示する最も高速な手段を提供する。DirectDrawは、2Dグラフィックや3Dグラフィック、および動画のためのWindowsを構成するエンジンである。DirectDrawはイメージの描画と移動を非常に高速に行い、スムーズなアニメーションを実現する。このようなDirectDrawの機能によって、高速なゲームやマルチメディア・アプリケーションを作成したり、既存のタイトルのWindowsへの移植を短期間のうちに容易に行うことが可能である。また、DirectDrawは、Microsoftのすべての最新グラフィックス・サブシステムの構成エンジンでもある。DirectDrawを用いれば、Windows GDIやDirect3D、ActiveMovie�、OpenGLによって生成されたイメージをすぐに利用できる。

DirectDrawは、ディスプレイ・ハードウェア上に位置する薄いレイヤである。DirectDrawによって、高速ブロック転送、補完ストレッチ、オーバーレイなど、Windows向けに設計されたグラフィック・アクセラレータの強力な機能を簡単に利用することができる。また、色空間変換もサポートし、ビデオの再生を高速に行うことが可能である。Direct3Dと同様に、DirectDrawは、デバイスに依存せずにハードウェアと通信する方法である。MicrosoftのMS-DOSｮでは、ターゲットとなるデバイスにコードを合わせなくてはならなかった。しかしDirectDrawでは、DirectDrawに対応したすべてのハードウェアについて、ハイ・パフォーマンスな結果を得ることができる。

DirectDrawはCOMベースのAPIである。Microsoftは、将来のバージョンのWindowsにDirectDrawを組み込む予定である。詳しくは「DirectDrawについて」を参照されたい。


OpenGL

OpenGLは、ハイ・エンドなCAD/CAMで用いられる精密な3D技術で、モデリング、アニメーション、シミュレーション、科学的な画像処理などの、3Dイメージのレンダリングを行う。OpenGLはWindowsNTで提供され、Windows95上でも動作する。Windows95でOpenGLを利用するには、Win32ワークステーション上でWin32 OpenGLが実行されている必要がある。現在のOpenGLは、OpenGL用に設計されたクライアント・ドライバ・モデルによって、OpenGLの機能をサポートしたハイ・エンドなハードウェアを利用している。将来のバージョンでは、Direct3Dを補完するハードウェア・ソリューションを提供し、Direct3D APIを通して低価格な3Dハードウェア（OpenGLが必要とする精密な条件をサポートしたもの）を利用できるようにする予定である。


Direct3Dアーキテクチャ

この章には、Direct3Dコンポーネントとその他のDirectXコンポーネントやオペレーティング・システム、およびシステム・ハードウェアとの関係についての総合的な情報が記載されている。ここでは以下のトピックについて説明する。

Direct3Dのビジョン

レンダリング・エンジン

実行バッファ

変換モジュール

照明モジュール

ラスタ処理モジュール

色とフォグ

ステートとステート・オーバーライド

Direct3Dファイル・フォーマット


Direct3Dのビジョン

Direct3Dは、 Windowsが動作するコンピュータ上で、ワールドワイドなゲームやインタラクティブな3Dグラフィックスを実現するために設計されている。Direct3Dは、デバイスに依存した3Dビデオ・ディスプレイ・ハードウェアへのアクセスを、デバイスに依存しない方法で提供する役割を担っている。アプリケーションは、テクスチャ・マッピングや正確な透視投影、アルファ・ブレンディングなどがほどこされた3Dプリミティブを描画するとき、ハードウェアに依存した特別なプロシージャの呼び出しをインプリメントする必要はない。プリミティブを設定するだけで、Direct3Dがハードウェアとの描画インターフェイスとなる。Direct3Dのバッファ管理システムはDirectDrawと完全に統合されており、DirectDrawは、3Dレンダリングのターゲットとしても、テクスチャ・マップのソースとしても使用することができる。このため、たとえば、モーション・ビデオ・マッピング、2Dのオーバーレイ・プレーンでの3Dのレンダリング、 スプライトなどを実現することもできる。

Direct3Dは、ジオメトリ変換、3Dクリッピング、照明効果を含む、標準的なハードウェア・アクセラレーション規格を提供するものとして設計されている。Direct3Dを用いれば、最適化された3Dレンダリング・パイプラインのすべてをソフトウェア的にインプリメントすることができる。このパイプラインの一部または全部の任意のプロセスは、ハードウェア・アクセラレータによって処理することが可能である。このためDirect3Dアプリケーションは、 新しいハードウェアが開発されたときには、より優れたハードウェア・アクセラレーションを利用することができる。

Direct3DはDirectDrawと完全に統合されている。DirectDrawドライバのCOMインターフェイスでもDirect3DのCOMインターフェイスでも、同じ基本オブジェクトにアクセスすることができる。詳しくは「DirectDrawとDirect3Dの統合」を参照されたい。DirectDrawの3Dサーフェスのサポートについては、「3Dサーフェスのサポート」を参照されたい。

このセクションの情報の多くは、Direct3Dのインプリメントについて詳しく説明している。保持モードのインターフェイスを用いる場合は、この情報が直接適用されることはない。しかし、直接モードのインターフェイスを利用する場合には、これらのインプリメントの詳細をよく理解しておく必要がある。また、保持モードを用いるときは、システム・アーキテクチャについての理論的な基礎知識が役に立つであろう。


レンダリング・エンジン

Direct3Dアーキテクチャは、３つの独立モジュールから構成される、仮想3Dレンダリング・エンジンに基づいている。

変換モジュール。３つの4行4列の行列を使用して、ジオメトリ変換処理を行うモジュールである。行列のひとつはビューポート変換のため、ひとつはワールド座標変換のため、ひとつは射影変換のために用いられる。このモジュールは任意の射影をサポートし、透視投影や平行投影によるビューを実現する。

照明モジュール。 このモジュールは幾何的な光源計算を行い、全体の光、光の方向、ポイントライトやスポットライトの光源をサポートする。

ラスタ処理モジュール。このモジュールは、シーンのレンダリングにジオメトリ・モジュールと照明モジュールの出力結果を使用する。生成されたシーンは、ディスプレイ・リストに基づいた伸縮可能なフォーマットであり、2Dや3Dのプリミティブをサポートする。

次の図は、レンダリング・エンジンの３つのモジュールが、どのように他のDirect3Dアーキテクチャと作用するかを示している。

ラスタ処理モジュールは、下図に示すようにDirectDrawに作用する。Direct3Dは、レンダリングのターゲットやテクスチャのソースとして、DirectDrawサーフェスを使用する。

各モジュールは、ハードウェア的に高速化することも、ソフトウェア的にエミュレートすることも可能である。また、Direct3Dに問い合わせて、エミュレーション・モードで動作しているコンポーネントを確かめることができる。これらのモジュールが同時に使用されるときは、Direct3Dのレンダリング・パイプラインを形成する。

この３つのモジュールは動的にロードすることが可能であり、レンダリングされたフレーム間で変更することができる。このため、新しいモジュールを作成し、ハードウェア・アクセラレーションや他のレンダリング効果を実現することができる。Direct3Dが使う変換モジュールはひとつであるが、照明モジュールとラスタ処理モジュールは、ふたつから選択することができる。これによって、たとえば、照明モジュールを切り替えるだけでよりリアルなシーンをレンダリングできる可能性があり、特に照明効果やレンダリングにおいて、大きな柔軟性を保つことができる。ISVが、独自の特殊効果を実現するラスタ処理モジュールを供給することも可能である。


実行バッファ

レンダリング・エンジンの３つのモジュールは、Direct3D APIを用いて設定した状態をそれぞれ保持している。すべての状態が設定されると、レンダリング・エンジンは、実行バッファとして知られるディスプレイ・リストを処理できるようになる。アプリケーションが実行バッファを明確に意識するのは、直接モードの場合だけである。保持モード・アプリケーションは、それよりも高いレベルで動作する。

実行バッファは、完全に自己内包型の、独立した情報のパケットである。実行バッファには頂点リストが含まれており、その後に命令ストリームが続く。命令ストリームは、オペレーション・コード（オペコード）と、このオペコードが操作するデータから構成されている。Direct3Dのオペコードは、D3DOPCODE列挙型に定義されている。実行バッファ内の命令は、D3DINSTRUCTION構造体に格納されており、オペコード、各命令データ・ユニットのサイズ、その後に続く関連データ・ユニットの数が含まれている。

実行バッファのフォーマットを下図に示す。

命令は、頂点への光源の適用方法や、頂点のレンダリング方法を定義している。最も一般的な命令のひとつにトライアングル・リスト（D3DOP_TRIANGLE）がある。これは頂点リスト中の頂点を参照する三角形プリミティブのリストである。命令ストリームに含まれるすべてのプリミティブは頂点リスト中の頂点しか参照しないため、プリミティブの頂点が視錐台の外部にある場合、変換モジュールにそのバッファ全体を無視させることは簡単である。

実行バッファのサイズはハードウェアによって決定される。このサイズを取得するには、IDirect3DDevice::GetCapsメソッドを呼び出し、D3DDEVICEDESC構造体のdwMaxBufferSizeメンバを調べる。ソフトウェア・ドライバを使用している場合、一般的に、最適な実行バッファのサイズは64Kバイトである。このとき、最も有効にセカンダリ・キャッシュが利用される。しかし、アプリケーションがハードウェア・アクセラレーションを利用する場合は、実行バッファのサイズをもっと小さくし、プライマリ・キャッシュを使うべきである。

実行バッファを操作している間は、照明モジュール、または照明モジュールと変換モジュールの両方を無効にすることができる。この場合、頂点リストを解析する方法が変更され、レンダリング・パイプラインのラスタ処理段階でのみ、変換や照明処理をほどこした頂点を使うことができるようになる。各実行バッファでは、ひとつのタイプの頂点情報しか使用できないことに注意すること。

実行バッファと状態変化に加えて、Direct3Dはもうひとつの呼び出し機構を備えている。変換モジュールも照明モジュールも、ダイレクトに呼び出すことができる。この機能は、方形境界線のテストで変換モジュールを使うときなど、ラスタ処理を必要としない場合に便利である。


変換モジュール

変換モジュールには、ビューポート、ビューイング行列、ワールド行列、射影行列の、4つの変更可能なレジスタがある。これらのパラメータのひとつが変更されると、新しい変換行列が計算され、変換モジュールが保持している行列に設定される。変換行列は、3Dオブジェクトの頂点のセットの回転と射影を定義し、モデル座標から2Dウィンドウへ変換する。

アプリケーションは変換行列を直接に設定することもできるが、できるだけ避けるべきである。最適化された変換計算を使う結合フェーズでは、変換行列のクラス分けが何度も行われる。しかし、アプリケーションが行列を指定すると、クラス分けの実行が妨げられてしまう。

ディスプレイ・リストは、たくさんの異なるタイプの頂点情報をサポートする。

ラスタ処理のみをサポートするハードウェアでは、アプリケーションはD3DTLVERTEX構造体を使用するべきである。D3DTLVERTEX構造体は変換や照明処理を行った後の頂点を示しているため、スクリーン座標と色を含んでいる。ハードウェアが変換操作をサポートする場合、アプリケーションはD3DLVERTEX構造体を使用する。この構造体は、データと、光源をソフトウェア的に処理するときに設定される色の情報を含んでいる。クリッピングを必要とするモデル座標データをアプリケーションが提供するとき、D3DLVERTEX構造体によって、適切な頂点が定義される。ハードウェアが光源をサポートする場合は、アプリケーションは単純にD3DVERTEX構造体を利用すればよい。このタイプの頂点には、レンダリングの間に変換や照明処理が適用される。ソフトウェア・エミュレーション・ドライバは、これらのすべてのタイプの頂点情報をサポートする。

変換モジュールにはふたつのタイプのメソッドがある。ひとつは変換モジュールの状態を設定するものであり、もうひとつは、変換モジュールを直接使用して、頂点セットを操作するものである。変換モジュールの直接呼び出しは、境界線のボリュームをテストしたり、ベクトル・セットを変換するときに便利である。これらの操作は、現在の変換行列を用いて、ジオメトリ変換を実行する。また、現在のビューに対してクリッピング・テストを行うこともできる。変換モジュールを直接呼び出す関数群は、すべて、D3DTRANSFORMDATA構造体を使用する。

変換についての一般的な情報は、保持モードのビューポートについて説明したセクション「変換」で得ることができる。フレーム内での変換については「変換」を参照されたい。どちらのセクションも保持モードのAPIについて説明しているが、変換のアーキテクチャと数式は、保持モードと直接モードの両方に適用することができる。変換で用いられる数学的知識の概要については「3D変換」を参照されたい。


照明モジュール

照明モジュールは、現在の光源やアンビエント・ライト、そしてマテリアルについてのスタックを保持している。

照明モジュールを直接使用する場合、このモジュール（D3DLIGHTINGELEMENT構造体）に入力されたデータの各要素には、方向ベクトルと位置（ポイントライトやスポットライトのような、局所的な光源のため）が含まれている。

サポートする光源モデルは、モノクロおよびRGBのふたつである。D3DLIGHTDATA構造体メンバのD3DLIGHTINGELEMENT構造体の後には、つねにカラー・フィールドが格納される。

モノクロ光源モデル（�ランプ�光源モデルと呼ばれることもある）は、ひとつの陰影値を計算するために、それぞれの光源のグレー要素を使用する。RGB光源モデルでは、色の計算のために光源とマテリアルの色要素をフルに用い、よりリアルな結果を生成する。

光を反射しないマテリアルでは光度を拡散して影を表現する。影の範囲は、0（アンビエント・ライトのみ）から1（光度が最大の光）である。光を反射する要素を持つマテリアルでは、次の方程式により、光の反射と拡散の両方を結合して影を計算する。

この陰影値は（ハードウェアのカラー・ルックアップ・テーブルにある色も、ソフトウェア的に実装されたルックアップ・テーブルにある色でも）ランプをあらかじめ計算してから用いるように設計されている。この計算済みのランプは、ふたつの部分に分けられている。計算されたランプの最初の3/4は拡散した色のランプで、その範囲はアンビエント・カラー（環境光色）から最も暗い色までである。最後の4分の1には、最も暗い色から最も明るい色の範囲のランプが続く。レンダリングにおいては、陰影値はランプのサイズによってスケーリングされ、必要な色を取得するインデックスとして用いられる。

パックされたRGBカラーは、次のように定義されている。

#define RGB_MAKE (red, green, blue) \

 ((red)   << 16) | \

 ((green) << 8)  | \

 (blue))

また、パックされたRGBAカラーの定義を以下に示す。

#define RGBA_MAKE(red, green, blue, alpha) \

(((alpha) << 24) | \

 ((red)   << 16) | \

 ((green) << 8)  | \

 (blue))

Direct3Dの色は、次のように定義されている。

typedef unsigned long D3DCOLOR;

光源のタイプは、D3DLIGHTTYPE列挙型のメンバのひとつ、すなわち、D3DLIGHT_DIRECTIONAL、D3DLIGHT_POINT、D3DLIGHT_PARALLELPOINT、D3DLIGHT_SPOT、D3DLIGHT_GLSPOTのいずれかでなくてはならない。この列挙型は、D3DLIGHT構造体の一部である。この構造体には、他にD3DCOLORVALUE構造体が含まれており、光源の色を指定している。赤、緑、青の要素の値の範囲は、一般に0から1までである。ランプ光源モデルの値は、次の等式に基づいている。

各要素には0から1の範囲外の値も指定可能で、（ダーク・ライトのように）照明効果を拡張することができる。D3DLIGHT構造体が保持する方向ベクトルは、モデルから光源までの方向を表している。このベクトルは、有向光源のために標準に戻さなくてはならない。ベクトルはすべてワールド座標で指定する。これらのベクトルは、現在のワールド行列によってモデル座標に変換される。このため、ベクトルをワールド座標に変換することなく、効率的にモデルに照明効果を施すことができる。ポイントライトやスポットライトでは、範囲パラメータは、有効な光源の範囲を示している。この範囲の外部にある頂点には、光が当たらないことになる。光の強さは2次減衰係数によって変化する。光の当たっている頂点から光源までの距離をdとすると、次の方程式が成立する。

D3DLIGHT構造体の残りのメンバ（dvThetaおよびdvPhi）は、それぞれ、スポットライトで用いる影と光線の角度を定義する。減少係数（dvFalloff）は、スポットライトの影と光線の間に適用される。

照明モジュールには、状態を設定するメソッドと、照明モジュールを直接呼び出すメソッドの、ふたつのタイプのメソッドがある。

変換モジュールと同様に、照明モジュールを直接呼び出すことも可能である。すべての照明モジュール関数の呼び出しには、D3DLIGHTDATA構造体が用いられる。


ラスタ処理モジュール

ラスタ処理モジュールは、実行呼び出し、すなわち、実行バッファをレンダリングする呼び出しを処理する。実行バッファの命令は、ラスタ処理モジュールの状態を設定する。

実行バッファは、最初に変換モジュールによって処理される。変換モジュールは、各頂点情報に基づいて変換する。クリッピングが有効になり、その対象となるビューポートのパラメータによってクリッピング情報が生成される。ここでビュー内に頂点がひとつもない場合、バッファ全体が無効にされることがある。次に、照明モジュールによって頂点が処理され、実行バッファの指示にしたがって色が設定される。最後にラスタ処理モジュールが命令ストリームを解析し、生成された頂点情報を用いてプリミティブをレンダリングする。アプリケーションがIDirect3DDevice::Executeメソッドを呼び出すと、システムは、頂点リストが変換だけを必要としているのか、または変換と照明を必要としているのかを判定する。これらの操作が完了した後に命令リストが解読され、レンダリングが行われる。

スクリーン座標の範囲は、デバイス（スクリーンまたはウィンドウ）の左上(0, 0)から、デバイスの右下(幅�1, 高さ�1)までである。深度の範囲は0（視錐台のフロント）から1（バック）までである。ふたつの三角形がふたつの頂点を共有している場合、ラスタ処理は、共有された点の接線に沿ったピクセルを複数回レンダリングすることがないように行われる。ラスタライザは、三角形の３つの頂点の並び順を判定し、裏面の三角形を取り除く。レンダリングされる三角形は、その頂点が時計回りの向きに並んでいるものだけである。


色とフォグ

Direct3Dにおける色とは、頂点やテクスチャ、マテリアル、面、照明、パレットの特性を示している。

このセクションでは、Direct3Dのパレットと、反射光の色が取り得る値について説明する。

パレット・エントリ

フォグ


パレット・エントリ

アプリケーションは、IDirect3DRM::CreateDeviceFromSurfaceを用いてDirectDrawサーフェスを描画することができる。Direct3Dアプリケーションは、不必要な色を無効にするため、DirectDrawのプライマリ・サーフェスにDiretDrawパレットをアタッチしなくてはならない。このSDKのDirect3Dサンプル・コードでは、ウィンドウがWM_ACTIVATEメッセージを受け取るたびに、プライマリ・サーフェスに対してパレットをアタッチしている。Direct3Dが8ビットのDirectDrawサーフェスのパレットに対して行った変更を追跡するには、IDirectDrawPalette::GetEntriesメソッドを使用する。

アプリケーションは、次の３つのフラグを使用して、どのようにパレット・エントリをシステムと共有するかを指定することができる。

D3DPAL_FREE	自由に使うことができるエントリである。
D3DPAL_READONLY	設定することができないエントリである。
D3DPAL_RESERVED	使用できないエントリである。
これらのフラグは、Win32標準のPALETTEENTRY構造体のpeFlagsメンバに設定する（パレットの共有方法を指定するには、D3DRMPALETTEENTRY構造体のD3DRMPALETTEFLAGS列挙型メンバを使うこともできる）。RGBレンダリングにおいてもモノクロ（ランプ）レンダリングにおいても、アプリケーションはこれらのフラグを使用することができる。RGBレンダリングでは、読み取り専用のパレットを提供したとしても、ランプ・レンダリングよりも望ましい結果を得ることができる。


フォグ

フォグは、D3DTLVERTEX構造体のspecularメンバに指定された色の、アルファ要素部分である。反射光は実際はRGBFカラーであると考えれば、�F�とは�fog�のFを指している。

モノクロ照明モードでのフォグは、その色が黒いとき、または光源がないときにだけ正確に動作する。光源がないときには、フォグが何色であっても同じ結果となる。

フォグ・モードには、リニア、指数、平方指数の３つのモードがある。現状では、リニア・フォグ・モードのみがサポートされている。

リニア・フォグを用いるときは、フォグ効果の開始点と終了点を指定する。フォグ効果は指定された開始点から始まり、終了点で最大密度に達するまで、比例的に増加する。

指数フォグ・モードは、わずかに認識できる程度のフォグから始まり、最大密度まで幾何級数的に増加する。指数フォグ・モードでは次の公式が成立する。

平方指数フォグ・モードでは、指数フォグ・モードよりも急速にフォグ効果が増加する。次の公式が成立する。

これらの公式においてeは自然対数の底を示し、その値は約2.71828である。フォグは透明度を表す基準である（ フォグの値が小さいほど、オブジェクトは見えにくくなる）。

アプリケーションが指数フォグ・モードを使用する場合、フォグの密度が0.5であるとすると、次の例に示すように、カメラから0.8の距離にある位置のフォグの値は0.6703になる。


ステートとステート・オーバーライド

Direct3Dは、現在の状態の設定にしたがって、実行バッファ中のデータを解析する。アプリケーションは、システムにデータをレンダリングするように指示する前に状態をセットアップする。D3DSTATE構造体には、このアーキテクチャを示唆する次の３つの列挙型が含まれている。D3DTRANSFORMSTATETYPEは変換モジュールの状態を設定する。また、D3DLIGHTSTATETYPEは照明モジュールの状態を、D3DRENDERSTATETYPEはラスタ処理モジュールの状態を設定する。

それぞれの状態は、読み取り専用を示すBOOL値のフラグを持っている。このフラグがTRUEの場合、それ以上の変更は行われない。

アプリケーションは、D3DSTATE_OVERRIDEマクロを使用して、読み取り専用状態を無効にすることができる。この機能によってアプリケーションは、実行バッファを再利用し、システムの状態を変えることでその動作を変更することができる。Direct3Dの保持モードでは、ステート・オーバーライドを利用して実行されるタスクがある。ステート・オーバーライドを用いないと、実行バッファを完全に再構築する必要が生じてしまう。たとえば、メッシュのマテリアルをフレームのマテリアルに置き換えるとき、保持モードAPIはステート・オーバーライドを利用する。

アプリケーションは、 グロー・シェーディング・モードをロックまたはアンロックするときにもD3DSTATE_OVERRIDEマクロを使用することができる。この例を以下に示す（シェーディング・モードのレンダリング・ステートはD3DRENDERSTATETYPE列挙型のD3DRENDERSTATE_SHADEMODEメンバで定義される）。

OP_STATE_RENDER(2, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_SHADEMODE, D3DSHADE_GOURAUD, lpBuffer);

    STATE_DATA(D3DSTATE_OVERRIDE(D3DRENDERSTATE_SHADEMODE), TRUE, lpBuffer);

OP_STATE_RENDERマクロは、D3DOP_STATERENDERオペコードを暗黙に使用する。D3DOP_STATERENDERオペコードはD3DOPCODE列挙型のメンバのひとつである。また、D3DSHADE_GOURAUDはD3DSHADEMODE列挙型のメンバのひとつである。

実行バッファを処理した後、シェーディング・モードを変更できるようにするために、アプリケーションはもう1度3DSTATE_OVERRIDEマクロを使用することができる。

    STATE_DATA(D3DSTATE_OVERRIDE(D3DRENDERSTATE_SHADEMODE), FALSE, lpBuffer);

OP_STATE_RENDERとSTATE_DATAマクロは、DirectX SDKのMiscフォルダにあるD3dmacs.hで定義されている。これらのマクロについては、「Step 5: 直接モードのレンダリング・ステートの設定」でも説明している。


Direct3Dファイル・フォーマット

Direct3Dのファイル・フォーマットは、メッシュ、テクスチャ、アニメーション・セット、ユーザ定義オブジェクトを格納し、アプリケーション間で簡単に3D情報を交換することが可能である。アニメーション・セットのサポートによって、定義済みのパスを保存し、リアルタイムに再生することができる。また、インスタンスや階層構造もサポートされており、ひとつのファイルのデータをひとつのオブジェクト（メッシュなど）にしか格納していない場合でも、そのオブジェクトに対して複数の参照を持つことが可能である。

Direct3Dのファイル名には、拡張子.xが付加されている。このDirectX�ソフトウェア開発キット（SDK）には、Autodesk 3D Studioが生成する.3dsファイルや、Direct3Dの以前のバージョンが生成する.xofファイルをコンバートするための変換ツール（Conv3ds.exeおよびConvxof.exe）が含まれている。

Direct3Dの保持モードAPIは、Direct3Dファイル・フォーマットをネイティブに使用し、アプリケーションに定義済みのオブジェクトをロードしたり、アプリケーションがリアルタイムに生成したメッシュ情報を書き込んだりできる。


3Dプログラミングの基礎技術

以下のセクションでは、3Dグラフィックスを組み込んだプログラムを書く前に理解しておかなくてはならない、いくつかの技術的なコンセプトについて説明する。これらのセクションでは、座標系や変換について総合的に取り扱っている。ここでは、モデル、照明、ビューのパラメータなどの幅広いアーキテクチャの詳細については説明していない。これらのトピックについて詳しくは、「Direct3Dの保持モード・オブジェクト」を参照されたい。

3Dグラフィックスに精通した開発者も、Direct3Dの保持モードに特有な情報を得るために、このセクションに目を通していただきたい。


3D座標系

3Dグラフィックスには、左手座標系と右手座標系の2種類の デカルト座標系がある。どちらの座標系でも、正方向のx軸は右を向き、正方向のy軸は上を向いている。正方向のz座標がどちらを向いているかは、左手または右手の指を正のx軸方向に向け、それを正のy軸方向に回転させることによって知ることができる。親指の示す方向が、自分を指していてもそうでなくても、その座標系での正のz軸の向きである。

このセクションでは、アプリケーションで利用することができる Direct3D座標系と座標のタイプについて説明する。

Direct3Dの座標系

U座標とV座標


Direct3Dの座標系

Direct3Dは左手座標系を採用している。つまり、以下の図に示すように、正方向のz軸はビューアの奥を向いている。

左手座標系では、ビューアのどの軸を基準としても、回転は時計回りに行われる。

もし右手座標系を用いる必要がある場合 （たとえば、右利きのユーザ向けのアプリケーションを作成している場合）は、Direct3Dに渡されるデータを少し変更すればよい。

システムが前面から時計回りに辿るように、三角形の頂点の順番を反対にする。言い換えれば、頂点v0、v1、v2があるとき、v0、v2、v1としてDirect3Dに渡す。

射影行列をZ軸方向に�1スケーリングする。このためには、D3DMATRIX構造体の_13、_33、_43メンバの符号を反転する。


U座標とV座標

Direct3Dはテクスチャ座標も使用する。これらの座標（uおよびv）は、オブジェクト上にテクスチャを貼り付けるときに利用される。vベクトルは、テクスチャの方向または向きを示し、z軸に沿っている。uベクトル（または上ベクトル）は、一般に、原点 [0,0,0] を始点としてy軸に沿っている。u座標およびv座標について詳しくは、「IDirect3DRMWrapインターフェイス」を参照されたい。


3D変換

3Dグラフィックスを操作するプログラムでは、次の場合にジオメトリ変換を用いることができる。

あるオブジェクトの、別のオブジェクトに対する相対位置を表現する場合。

オブジェクトの回転、削除、サイズ変更を行う場合。

視点、方向、透視投影を変更する場合。

任意の点を他の点に変換するには、4行4列の行列を利用する。次の例では、行列を用いて、点(x, y, z)を新しい点(x�, y�, z�)に変換する。

この例では、点(x�, y�, z�)を生成するために、点 (x, y, z)と行列に対して以下の操作が行われる。

最も一般的な変換には、移動、回転、およびスケーリングがある。一度に複数の変換計算を行うには、それらの効果を生み出す複数の行列をひとつの行列にまとめればよい。たとえば、ひとつの行列を作成して、点の並びの移動と回転を行うことができる。

行列は、列を順番に並べて指定する。たとえば、次の行列を配列で表現する場合を考える。

この行列を示す配列は次のようになる。

D3DMATRIX scale = {

    D3DVAL(s),    0,            0,            0,

    0,            D3DVAL(s),    D3DVAL(t),    0,

    0,            0,            D3DVAL(s),    D3DVAL(v),

    0,            0,            0,            D3DVAL(1)

};

このセクションでは、Direct3Dを通してアプリケーションから利用できる3D変換について説明する。

移動

回転

スケーリング

変換については、このドキュメントの他の部分でも取り扱っている。保持モードにおけるビューポートについて説明したセクション「変換」には、変換についての一般的な情報が記載されている。フレーム変換については「変換」を参照されたい。どちらのセクションも保持モードのAPIについて説明しているが、変換のアーキテクチャと数式は、保持モードと直接モードの両方に適用することができる。さらに、セクション「Direct3Dアーキテクチャ」には、変換モジュールについて説明した「変換モジュール」というセクションが含まれている。


移動

次の変換は、点(x, y, z)を新しい点(x�, y�, z�)に移動する。


回転

このセクションで説明している変換は、左手座標系における場合を想定しているため、他のシステムで使用される変換行列とは異なる可能性がある。

次の変換は、点(x, y, z)をx軸を基準として回転させ、新しい点(x�, y�, z�)を生成する。

次の変換では、y軸を基準として点を回転させる。

次の変換では、z軸を基準として点を回転させる。

上記の行列中のギリシャ文字のシータ（θ）は、回転角度をラジアンで表したものである。角度は、回転軸に沿って原点を眺めた場合、時計周りに測定した値が用いられる。


スケーリング

次の変換は、点(x, y, z)をx、yおよびz軸方向に任意の割合でスケーリングし、新しい点(x�, y�, z�)を生成する。


ポリゴン

Direct3Dの3次元オブジェクトは、メッシュで構成されている。メッシュとは面の集合であり、それぞれの面は単純なポリゴンで表現される。ポリゴンの基本型は三角形である。保持モードアプリケーションは３つ以上の頂点を持つポリゴンを扱うことができるが、それらはシステムによって、オブジェクトがレンダリングされる前に三角形に変換される。直接モードアプリケーションは、三角形を使用しなくてはならない。

このセクションでは、アプリケーションでDirect3Dポリゴンを使用する方法について説明する。

幾何的条件

面法線と頂点法線

シェーディング・モード

三角形の補完要素


幾何的条件

三角形は、凸状かつ平面であるという、レンダリングで要求される ふたつの条件をつねに満たしているため、扱いやすい形のポリゴンである。ポリゴンの任意のふたつの頂点を結ぶ線が、つねにそのポリゴンの内部にあるとき、ポリゴンは凸状であるという。

三角形の３つの頂点は平面を表すが、そこに別の頂点を追加することによって、容易に立体ポリゴンを作成することができる。


面法線と頂点法線

メッシュ上のそれぞれの面には、垂直な面を示す法線ベクトルがある。法線ベクトルの向きは、頂点が定義されている順序と、座標系が右手座標系と左手座標系のどちらであるかによって決定される。法線ベクトルがビューアに向かっている側が面の表である。Direct3Dでは、面の表のみが視錐台である。またDirect3Dでは、表から面を見た場合、必ず時計回りに頂点が定義されている。

Direct3Dアプリケーションは、面法線を指定する必要はない。必要時には、システムが自動的に面法線を計算する。システムが面法線を使用するのは、フラット・シェーディング・モードの場合である。フォン・シェーディング・モードとグロー・シェーディング・モードの場合、および光源やテクスチャ効果を制御する場合には、システムは頂点法線を使用する。


シェーディング・モード

フラット・シェーディング・モードでは、システムは、ひとつの頂点の色をプリミティブの他の面全体に複製する。グロー・シェーディング・モードとフォン・シェーディング・モードでは、頂点法線を用いてポリゴン・オブジェクトの外観をスムーズにし、その間のスペースには隣接した頂点の色と輝度が挿入される。フォン・シェーディング・モードでは、システムが面の各ピクセルに適切なシェーディング値を計算する。

Note

フォン・シェーディング・モードは、現在はサポートされていない。

グロー・シェーディング・モードは、オブジェクト外観をスムーズに表示し、計算上効率的である。このため、多くのアプリケーションは グロー・シェーディング・モードを利用する。しかし、グロー・シェーディング・モードは、フォン・シェーディング・モードでは起こらない細かなミスを 生じることがある。たとえば、下図に示すように面に完全にスポットライトが当たっている場合、グロー・シェーディング・モードとフォン・シェーディング・モードでは全く異なった結果を引き起こす。

この場合、フォン・シェーディング・モードでは、各ピクセルの値を計算してスポットライトを表示する。頂点の間にピクセルを挿入する グロー・シェーディング・モードでは、スポットライトを全く無視してしまい、スポットライトが存在しないかのように面がレンダリングされる。

フラット・シェーディング・モードでは、次のようなピラミッドは、面と面が接している辺（エッジ）がシャープに表示され、システムが自動的に面法線を生成する。しかし、グロー・シェーディング・モードやフォン・シェーディング・モードでは、陰影値が辺の周辺に補完され、最終的には曲面で構成された外観となる。

グロー・シェーディング・モードやフォン・シェーディング・モードを用いて曲面を表示し、さらにシャープな辺を持ったオブジェクトも含めたい場合、アプリケーションは、辺が必要な面のすべての交線について、頂点法線を複製しなくてはならない。

グロー・シェーディング・モードは、ひとつのオブジェクト上に曲面と平面を含めることを可能にするだけでなく、平面に当たった光をフラット・シェーディング・モードよりもリアルに表現する。フラット・シェーディング・モードの面の色は均一であるが、グロー・シェーディング・モードでは、面を正確に暗くすることができる。この効果は、すぐ近くに光源がある場合に顕著である。 ほとんどのDirect3Dアプリケーションに適切なシェーディング・モードは、グロー・シェーディング・モードである。


三角形の補完要素

システムは、面をレンダリングする際、三角形全体にその頂点の特徴を適用する。

色

反射光

フォグ

アルファ

三角形に加えられた特徴は、現在のシェーディング・モードによって調整される。

フラット	何も補完されない。その代わり、三角形の最初の頂点の色が面全体に適用される。
グロー	３つの頂点の間にリニア補完が行われる。
フォン	現在の照明を用い、面の各ピクセルについて頂点のパラメータが再評価される。フォン・シェーディング・モードは現状ではサポートされていない。
色と反射光の補完要素は別々に扱われ、カラー・モデルに依存する。RGBカラー方式（D3DCOLOR_RGB）では、システムは、赤、緑、青の色要素を使用する。モノクロ・モデル（D3DCOLOR_MONO）では、システムは、頂点の色の青の要素だけを使用する。

たとえば、頂点1の色の赤の要素が0.8で、頂点2の赤の要素が0.4のとき、 このふたつの頂点を結ぶ線の中心のピクセルにシステムが割り当てる赤の要素は、グロー・シェーディング・モードのRGBカラー・モデルでは0.6である。

色のアルファ要素は、独立した補完要素として取り扱われる。これは、デバイス・ドライバが、テクスチャ・ブレンディングまたは点彩法の、ふたつの異なる方法によって透明度をインプリメントできるためである。

アプリケーションは、現在のデバイス・ドライバがサポートする 補完形式を取得するために、D3DPRIMCAPSのdwShadeCapsメンバを参照することができる。


三角形の展開図と扇形

サーフェス全体を記述するには、各三角形の頂点をすべて指定するのではなく、展開図や扇形を使用することができる。たとえば次のような展開図を定義する場合、必要な頂点は7つだけである。

システムは、最初の三角形を描画するために頂点v0、v1、v2を使用する。2番目の三角形にはv1、v3、v2を、3番目の三角形にはv3、v4、v2を用いる。2番目の三角形の頂点は順番になっていないが、これはすべての三角形が時計回りの向きに描画されるためである。

扇形は展開図と似ているが、すべての三角形がひとつの頂点を共有する点が異なっている。

システムは、頂点v0、v1、v2を用いて最初の三角形を描画する。2番目の三角形の描画には、頂点v0、v2、v3を使用する。

展開図や扇形を使用するには、D3DTRIANGLE構造体のwFlagsメンバにフラグを指定する。


ベクトル、頂点、クォータニオン

Direct3Dでは、頂点は位置と向きを示している。プリミティブ中の各頂点は、位置を示すベクトル、向きを示す法線ベクトル、テクスチャの座標、および色によって記述される（保持モードでは、これらの値はD3DRMVERTEX構造体に格納される）。

クォータニオンは、ベクトルを定義する[x, y, z]値に4つめの要素を追加する。これは、3D回転で一般的に用いられている行列メソッドに代わるものである。クォータニオンは、3D空間の軸と、その軸に沿った回転を表している。たとえばクォータニオンは、軸(1, 1, 2)と1ラジアンの回転を示すことができる。クォータニオンは役に立つ情報を保持しているが、その真価は合成と補完というふたつの操作を実行するときに発揮される。

クォータニオンの合成は、クォータニオンを結合するようなものである。つまり、ふたつのクォータニオンの結合（q1 o q2）とは、「回転2によって軸2を基準として回転した後、回転1によって軸1を基準として回転する」ことである。数学的には、q1とq2の合成をQ = q1 o q2と表記する。したがってQは、q2とq1を適用して得た1本の軸に沿った回転を示している。

クォータニオン補完を使用すると、アプリケーションは、ある軸や向きから別の軸や向きへのパスを、スムーズかつ合理的に計算することができる。

合成と補完を同時に用いる場合、クォータニオンは、ジオメトリ計算を行う簡単な方法を提供する。この方法は、一見複雑そうに見える。たとえば、与えられた向きに回転する計算について考える。このためには、軸2を基準としてr2度の回転を行った後、軸1の回りをr2度回転させればよいとする。しかし、最終的なクォータニオンはわかっていない。合成を用いると、ふたつの回転を組み合わせ、結果としてひとつのクォータニオンを得ることができる。その後、スムーズに移行するために、元のクォータニオンから合成されたクォータニオンを補完へ行うことができる。

Direct3Dの保持モードは、クォータニオンの操作を支援するいくつかの関数を用意している。たとえばD3DRMQuaternionFromRotation関数は、回転軸を定義するベクトルに回転値を追加し、D3DRMQUATERNION構造体で示されるクォータニオンに結果を返す。さらに、D3DRMQuaternionMultiply関数はクォータニオンを合成し、D3DRMQuaternionSlerp関数はふたつのクォータニオンの間で球体のリニア補完を行う。

保持モード・アプリケーションでは、ベクトルやクォータニオンを扱うタスクを簡略化するため、以下の関数群を利用することができる。

D3DRMQuaternionFromRotation
D3DRMQuaternionMultiply
D3DRMQuaternionSlerp
D3DRMVectorAdd
D3DRMVectorCrossProduct
D3DRMVectorDotProduct
D3DRMVectorModulus
D3DRMVectorNormalize
D3DRMVectorRandom
D3DRMVectorReflect
D3DRMVectorRotate
D3DRMVectorScale
D3DRMVectorSubtract


浮動小数点精度

Direct3Dでは、他のDirectXアーキテクチャと同様に、53ビットの浮動小数点精度が用いられる。アプリケーションでこの精度を変更する必要がある場合は、計算が完了したときに53ビットに戻さなくてはならない。そうしないと、デフォルトの値に依存するシステムのコンポーネントは、処理ができなくなる。


パフォーマンスの最適化

3Dグラフィックスを用いたリアルタイム・アプリケーションを作成する開発者はすべて、パフォーマンスの最適化に関心を持っている。このセクションでは、コードから最高のパフォーマンスを得るためのガイドラインを提供する。

このガイドラインの以下のセクションは、すべての Direct3D アプリケーションに適用することができる。

実行時のクリッピング・テスト

プリミティブのバッチ処理

テクスチャのサイズ

トライアングル・フラグ

Direct3Dアプリケーションは、ランプ・ドライバ（モノクロ・カラー・モデルのため）とRGBドライバのいずれかを使用することができる。以下のセクションで述べられているパフォーマンスは、ランプ・ドライバについて適用される。

ランプ・パフォーマンスのヒント

ランプ・テクスチャ

Zバッファ

コピー・モード


実行時のクリッピング・テスト

アプリケーションはIDirect3DDevice::Executeメソッドを使用して、自動クリッピングを用いて、またはクリッピングを行わずに、プリミティブをレンダリングすることができる。変換やラスタ処理段階でのクリッピング・テストはプロセスの実行速度を遅くするため、クリッピングを行わずにこのメソッドを使用したほうが、クリッピング・フラグを設定した場合よりも高速である。自動クリッピングを行うアプリケーションでは、レンダリング・データが視錐台に完全に収まることを保証しなくてはならない。このための最適な方法は、単純な結合ボリュームをモデルに適用し、それを最初に変換することである。この変換結果を参照すれは、データ全体を無効にするかどうか（データが領域の外部にある場合）、クリッピングを行わないバージョンのIDirect3DDevice::Executeメソッドを用いるかどうか（すべてのデータが領域内に存在する場合）、クリッピング・フラグを使用するかどうか（データの一部が領域内にある場合）を決定することができる。直接モードでは、D3DSTATUS構造体のフラグを利用して、これらの機能をひとつの実行バッファ中に用意する。そしてD3DOPCODE列挙型のD3DOP_BRANCHFORWARDメンバを指定し、結合ボリュームが領域外にあるときには変換をスキップするようにする。Direct3Dの保持モードでは、実行バッファの使用を高速化するため、自動的にこの機能を利用する。


プリミティブのバッチ処理

実行中に最高のレンダリング・パフォーマンスを得るためには、プリミティブをバッチ処理し、レンダリング・ステートの変更をできるだけ少なくする。たとえば、ふたつのテクスチャを持つオブジェクトがあるとき、まず最初のテクスチャを使う三角形をグループ化し、続いて、テクスチャを変更するために必要なレンダリング・ステートを設定する。そして、ふたつめのテクスチャを使うすべての三角形をグループ化する。Direct3Dをサポートする最も単純なハードウェアは、ハードウェア・アブストラクション・レイヤ（HAL）を通して、レンダリング・ステートやプリミティブのバッチ処理を行う。バッチ命令が効率的であるほど、実行中にHALが呼び出されることが少なくなる。


テクスチャのサイズ

テクスチャ・マッピングのパフォーマンスは、メモリの速度に大きく依存する。テクスチャのキャッシュ・パフォーマンスを最大にするためには、たくさんの方法が考えられる。

テクスチャを小さくする。テクスチャが小さいほど、CPUのセカンダリ・キャッシュに保持される可能性が高くなる。

プリミティブごとに異なるテクスチャを使用しない。また、使用するテクスチャの順にポリゴンをグループ化しておくようにする。

できる限り正方形のテクスチャを用いる。寸法が256×256のテクスチャが最も高速である。たとえば、4枚の128×128のテクスチャを用いる場合は、同じパレットを使用するようにし、256×256のテクスチャ1枚に収めるとよい。このテクニックによって、テクスチャ・スワッピングの回数を減らすこともできる。多くのテクスチャを必要としないアプリケーションは、当然、256×256のテクスチャを使用するべきではない。なぜなら、前述したように、テクスチャはできるだけ小さく抑えたほうがよいからである。


トライアングル・フラグ

D3DTRIANGLE構造体のwFlagsメンバには、システムが三角形の一部や扇形を構成する際に、頂点を再利用できるようにするフラグが設定されている。これらのフラグを有効に使うと、場合にもよるが、はるかに高速に動かすことができる。

アプリケーションは次のふたつのフラグを使用して、ドライバにアクセラレーションの方法を示唆することができる。

D3DTRIFLAG_STARTFLAT(len)

	現在の三角形が取り出されると、ドライバも、展開図や扇形から、後に続く三角形をlenが示す数だけ取り出すことができる。

D3DTRIFLAG_ODDとD3DTRIFLAG_EVEN

	ドライバは、三角形からひとつの新しい頂点だけを再ロードすればよく、他のふたつの頂点はレンダリングされた最新の三角形から再利用する。
可能な限り最高のパフォーマンスを得るには、アプリケーションから、D3DTRIFLAG_STARTFLATフラグと、D3DTRIFLAG_ODDフラグまたはD3DTRIFLAG_EVENの両方を使用する。

D3DTRIFLAG_STARTFLATフラグをチェックしないドライバもあるので、このフラグを使用するには注意が必要である。このフラグをチェックしないドライバを使うアプリケーションでは、レンダリングされるはずのポリゴンがレンダリングされない場合がある。

アプリケーションは、D3DTRIFLAG_ODDやD3DTRIFLAG_EVENフラグを用いる前に、 D3DTRIFLAG_STARTフラグを指定しなくてはならない。D3DTRIFLAG_STARTフラグを使用すると、ドライバはすべての三角頂点を再ロードする。D3DTRIFLAG_STARTフラグを指定した後の三角形は、D3DTRIFLAG_ODDとD3DTRIFLAG_EVENフラグを用いて辺を共有することができる。

デバッグ・バージョンのSDKは、D3DTRIFLAG_ODDとD3DTRIFLAG_EVENフラグを有効にしている。

詳しくは「三角形の展開図と扇形」を参照されたい。


ランプ・パフォーマンスのヒント

モノクロ（ランプ）・ドライバを使用する場合、アプリケーションは、できる限り最高のパフォーマンスを得るために次のテクニックを適用するべきである。

すべてのテクスチャで同じパレットを共有する。

パレットの色数をできるだけ少なくする。64色以下が最適である。

マテリアルのランプ・サイズを16以下にする。

すべてのマテリアル（テクスチャ・ハンドルを除く）を同一にし、テクスチャがカラーリングを指定できるようにする。たとえば、すべてのマテリアルを白くして、反射パワーを等しく保つ。多くのアプリケーションでは、ひとつのシーンにふたつ以上のマテリアルは必要ない。ひとつは光が反射しているオブジェクトであり、もうひとつは反射しないオブジェクトである。

できる限りテクスチャを小さくする。

複数の小さなテクスチャは、256×256ピクセルの1枚のテクスチャに合わせる。

小さな三角形はグロー・シェーディング・モードで、大きな三角形はフラット・シェーディング・モードでレンダリングする。

ひとつ以上のパレットを使用する必要がある開発者は、ひとつのパレットをマスター・パレットとして用い、他のパレットはマスター・パレットのサブセットを含むように設計すれば、コードを最適化することができる。


ランプ・テクスチャ

ランプ・ドライバを使うアプリケーションでは、テクスチャの色数を固定するべきである。モノクロのテクスチャで用いられる色は、レンダリングの過程でそれぞれ独自のルックアップ・テーブルを必要とする。シーンのレンダリング中に非常に多くの色を使用するアプリケーションの場合、システムはたくさんのルックアップ・テーブルを参照しなくてはならず、キャッシュが十分に働かない。また、テクスチャ同士でなるべく色を共有するようにするべきである。8ビット以上の色数をサポートしたランプ・ドライバを使う場合でも、アプリケーションのすべてのテクスチャはひとつのパレットに合わせるのが理想的である。


Zバッファ

ランプ・ドライバを使用するアプリケーションは、シーンが前から後ろへレンダリングされるようにZバッファリングを用いてテクスチャを処理すると、パフォーマンスを向上させることができる。テクスチャを適用し、Zバッファを利用したプリミティブには、基準となるスキャンライン上でZバッファについてのプレテストが行われる。前もってレンダリングされたポリゴンのためにスキャンラインが隠れている場合は、システムがポリゴンを高速かつ効率的に取り除く。Zバッファリングによってパフォーマンスは改善されるが、このテクニックは、シーンが何度もオーバードローを必要とするときに最も効果的である。オーバードローとは、スクリーン・ピクセルが描画される平均回数を示す。オーバードローを正確に計算することは困難だが、近似値を求めることは可能である。オーバードローの平均が2よりも小さいときは、Zバッファリングをオフにすると最高のパフォーマンスを得ることができる。

また、プリミティブにZテストを行うことによって、つまり、Zバッファについて与えられたプリミティブ・リストをテストすることによって、アプリケーションのパフォーマンスを向上することができる。これにより、対応する矩形範囲の取得が高速に行われるようになる。

保持モードAPIは、Zバッファの最適化を容易にするため、前から後ろへ自動的にシーンを並べ替える。さらに保持モードは、ある程度の三角形を含むメッシュについては、プリミティブのZテストも行う。

指定したドライバのオーバードロー性能を試すために、このSDKのD3dtest.exeアプリケーションを用いてフィル・レートのテストを行うことができる（フィル・レート・テストでは、4つのトンネルを、前から後ろ、または後ろから前へ、選択された設定で描画する）。

高速なパーソナル・コンピュータでは、ソフトウェア的にシステム・メモリにレンダリングしたほうが、ビデオ・メモリへのレンダリングよりも速いことが少なくない。ただしこの場合、ダブル・バッファリングやハードウェア・アクセラレータの操作を行うことができないというデメリットがある。システム・メモリにもビデオ・メモリにもレンダリングすることができ、どちらが高速であるかをテストするルーチンを含んでいれば、アプリケーションは実行時のシステムに最適なアプローチを利用することができる。このSDKのDirect3Dサンプル・コードは、上記の方法を実現している。スピードをテストする方法は他にないため、この両方の手順をインプリメントする必要がある。コンピュータによってスピードは全く異なり、メイン・メモリの構造や使用されているグラフィック・アダプタの種類に依存する。D3dtest.exeは、システム・メモリのビデオ・メモリに対するスピードのテストに使用することはできるが、ユーザのパーソナル・コンピュータのパフォーマンスを予測することはできない。

Direct3Dのすべてのサンプルは、systemmemoryコマンドライン・オプションを指定すると、システム・メモリを利用して動作する。このオプションはコードの開発上有用である。これによって、アプリケーションを失敗（fail）させる際、システムを停止せずにレンダリングを中断する方法を知ることができる。たとえばDirectDrawは、システム・メモリ・サーフェスにWIN16ロックをかけることはない（WIN16ロックは、GDIやUSERへのアクセスをシリアル化し、IDirectDrawSurface2::LockとIDirectDrawSurface2::Unlockメソッドの呼び出しの間にWindowsをシャット・ダウンする。IDirectDrawSurface2::GetDCとIDirectDrawSurface2::ReleaseDCの呼び出しの間についても同様である）。


コピー・モード

ランプ・ドライバを用いるアプリケーションは、D3DTEXTUREBLEND列挙型のD3DTBLEND_COPYテクスチャ・ブレンディング・モードを指定すると、パフォーマンスを改善できる場合がある。

コピー・モードを利用するには、アプリケーションのテクスチャは、プライマリ・サーフェスと同じピクセル・フォーマットやパレットを使わなくてはならない。コピー・モードは光を適用せず、単純にピクセルをスクリーンにコピーする。すでに光源を施したテクスチャを用いるシーンでは、このテクニックが役に立つ。

8ビット・カラーの光源がないモノクロ・モデルを使うアプリケーションは、コピー・モードによってパフォーマンスが向上する。しかし16ビット・カラーを使用する場合は、テクスチャを調整する場合とそれほど変わらないスピードになる。16ビット・カラーでは、テクスチャのサイズが8ビットの場合の2倍になり、余計な負荷がキャッシュにかかるため、パフォーマンスは8ビットのテクスチャよりもわずかに低下する。この場合にも、システムのパフォーマンスを確認するためにD3dtest.exeを利用することができる。


保持モードの概要


保持モードについて

このセクションでは、Direct3Dの保持モードについて説明する。保持モードは、パーソナル・コンピュータ上で3Dグラフィックスを実現するためにMicrosoftが提供するソリューションである。3D環境を作成し、リアルタイムに処理したい場合は、Direct3Dの保持モードAPIを使用するべきである。

Direct3DはDirectDrawと完全に統合されている。DirectDrawオブジェクトは、DirectDrawとDirect3Dの両方の状態を保持している。アプリケーションは、IDirectDraw::QueryInterfaceメソッドを用いて、DirectDrawオブジェクトのIDirect3Dインターフェイスを取得することができる。Direct3DとDirectDrawの統合について詳しくは、「Direct3Dドライバ・インターフェイス」を参照されたい。

保持モードの基礎にある概念は、以前に3Dグラフィックスのコードを書いたことのある開発者にとっては馴染み深いものだろう。しかし、初めて3Dプログラミングを行う開発者は、「イントロダクション: Direct3Dの保持モード・オブジェクト」と「3Dプログラミングの基礎技術」を十分に理解する必要がある。これから3Dプログラミングを始める開発者も、始めたばかりの開発者も、このSDKに含まれているサンプル・コードを注意深く読んでいただきたい。サンプル・コードは、実際のアプリケーションに保持モードを実装する方法を示している。

このセクションは、3D プログラミングへのイントロダクションである。ここでは、Microsoftの 3D グラフィックス に対する ソリューションと、3 次元上の点を操作するために必要な、いくつかの技術的な予備知識について説明する。これは、Direct3Dの保持モードのプログラミングの初歩について説明したものではない。保持モードのプログラミングについては、「Direct3Dの保持モードのチュートリアル」を参照されたい。


イントロダクション: Direct3Dの保持モード・オブジェクト

Direct3Dの保持モードへのアクセスは、わずかな数のオブジェクトを通して行われる。以下の表にこれらのオブジェクトをリストアップし、それぞれについて簡単に説明する。

オブジェクト	説明
Direct3DRMAnimation	主にDirect3DRMFrameオブジェクトを参照するときに、どのように変換に手を加えるかを定義するオブジェクトである。このオブジェクトは、Direct3DRMVisual、Direct3DRMLight、Direct3DRMViewportオブジェクトの位置や向き、スケールをアニメーションするために使うことができる。
Direct3DRMAnimationSet	Direct3DRMAnimationオブジェクトをグループ化するオブジェクトである。
Direct3DRMDevice	レンダリングの出力先の可視ディスプレイを示すオブジェクトである。
Direct3DRMFace	メッシュ上のひとつのポリゴンを表すオブジェクトである。
Direct3DRMFrame	このオブジェクトは、シーンにオブジェクトを配置し、ビジュアル・オブジェクトの位置や向きを定義する。
Direct3DRMLight	このオブジェクトは、5種類の光源のひとつを定義し、シーンのビジュアル・オブジェクトを彩色するために用いられる。
Direct3DRMMaterial	このオブジェクトは、サーフェスがどのように光を反射するかを定義する。
Direct3DRMMesh	ポリゴンの面のセットを含むオブジェクトである。面や頂点のグループを操作するために使うことができる。
Direct3DRMMeshBuilder	このオブジェクトによって、メッシュにある個々の頂点や面を操作することができる。
Direct3DRMObject	Direct3Dの他のすべての保持モード・オブジェクトが用いる基本クラスである。すべてのオブジェクトに共通な特徴を保持している。
Direct3DRMPickedArray	このオブジェクトは、与えられた2Dの点に対応するビジュアル・オブジェクトを識別する。
Direct3DRMShadow	陰影を定義するオブジェクトである。
Direct3DRMTexture	色の付いたピクセルが矩形に並んだオブジェクトである。
Direct3DRMUserVisual	システムが提供しない機能を実現するため、アプリケーションが定義するオブジェクトである。
Direct3DRMViewport	このオブジェクトは、3Dシーンがどのように2Dウィンドウにレンダリングされるかを定義する。
Direct3DRMVisual	シーンにレンダリングすることができるオブジェクトである。ビジュアル・オブジェクトは可視状態でなくてもよい。たとえば、フレームをビジュアル・オブジェクトとして追加することもできる。
Direct3DRMWrap	このオブジェクトは、面やメッシュのテクスチャ座標を計算する。
多くのオブジェクトは、配列オブジェクトと呼ばれる配列にグループ化することができる。配列オブジェクトによって、グループ全体に操作を適用することが容易になる。配列オブジェクトを使うことができるCOMインターフェイスには、GetElementとGetSizeメソッドが含まれている。これらのメソッドは、配列要素へのポインタと配列のサイズを受け取る。配列インターフェイスについて詳しくは、「IDirect3DRM配列インターフェイス」を参照されたい。


オブジェクトとインターフェイス

IObjectName::QueryInterfaceは、オブジェクトがそのインターフェイスをサポートしている場合のみ、有効なインターフェイスへのポインタを取得する。したがって、IDirect3DRMDevice::QueryInterfaceを呼び出してIDirect3DRMWinDeviceインターフェイスを受け取ることはできるが、IDirect3DRMVisualインターフェイスを受け取ることはできない。

オブジェクト名	サポートされるインターフェイス
Direct3DRMAnimation	IDirect3DRMAnimation
Direct3DRMAnimationSet	IDirect3DRMAnimationSet
Direct3DRMDevice	IDirect3DRMDevice, IDirect3DRMWinDevice
Direct3DRMFace	IDirect3DRMFace
Direct3DRMFrame	IDirect3DRMFrame, IDirect3DRMVisual
Direct3DRMLight	IDirect3DRMLight
Direct3DRMMaterial	IDirect3DRMMaterial
Direct3DRMMesh	IDirect3DRMMesh, IDirect3DRMVisual
Direct3DRMMeshBuilder	IDirect3DRMMeshBuilder, IDirect3DRMVisual
Direct3DRMShadow	IDirect3DRMShadow, IDirect3DRMVisual
Direct3DRMTexture	IDirect3DRMTexture, IDirect3DRMVisual
Direct3DRMUserVisual	IDirect3DRMUserVisual, IDirect3DRMVisual
Direct3DRMViewport	IDirect3DRMViewport
Direct3DRMWrap	IDirect3DRMWrap
次のサンプル コードでは、ひとつのDirect3DRMDeviceオブジェクトにふたつのインターフェイスを生成する方法を説明している。 IDirect3DRM::CreateObjectメソッドは、初期化されていないDirect3DRMDeviceオブジェクトを生成する。オブジェクトの初期化は、IDirect3DRMDevice::InitFromClipperメソッドによって行われる。IDirect3DRMDevice::QueryInterfaceメソッドの呼び出しは、Direct3DRMDeviceオブジェクトへのふたつめのインターフェイス（WM_PAINTおよびWM_ACTIVATEメッセージへの応答時に用いられるIDirect3DRMWinDeviceインターフェイス）を生成する。

d3drmapi->CreateObject(CLSID_CDirect3DRMDevice, NULL,

    IID_IDirect3DRMDevice,(LPVOID FAR*)&dev1);

dev1->InitFromClipper(lpDDClipper, IID_IDirect3DRMDevice,

    r.right, r.bottom);

dev1->QueryInterface(IID_IDirect3DRMWinDevice, (LPVOID*) &dev2);

ふたつのインターフェイスが同一のオブジェクトを参照しているかどうかを判定するには、それぞれのインターフェイスについてQueryInterfaceメソッドを呼び出し、返されるポインタの値を比較する。ポインタの値が等しい場合、インターフェイスは同じオブジェクトを参照している。

Direct3Dのすべての保持モード・オブジェクトは、前述したリスト中のインターフェイスに加え、IDirect3DRMObjectインターフェイスとIUnknownインターフェイスをサポートしている。しかし、IDirect3DRMObjectオブジェクトは配列オブジェクトを提供しない。配列オブジェクトは、必要がないため、クラス識別子（CLSID）を持っていない。IDirect3DRM::CreateObjectメソッドの呼び出しでは、配列オブジェクトを作成することはできない。その代わり、各インターフェイスについて以下の生成メソッドを使用する。

配列インターフェイス	生成メソッド
IDirect3DRMDeviceArray	IDirect3DRM::GetDevices
IDirect3DRMFaceArray	IDirect3DRMMeshBuilder::GetFaces
IDirect3DRMFrameArray	IDirect3DRMPickedArray::GetPick
	または IDirect3DRMFrame::GetChildren
IDirect3DRMLightArray	IDirect3DRMFrame::GetLights
IDirect3DRMPickedArray	IDirect3DRMViewport::Pick
IDirect3DRMViewportArray	IDirect3DRM::CreateFrame
IDirect3DRMVisualArray	IDirect3DRMFrame::GetVisuals


オブジェクトと参照カウント

オブジェクトが生成されると、つねにその参照カウントがインクリメントされる。アプリケーションがオブジェクトの子を作成したり、メソッドがオブジェクトへのポインタを返したりするたびに、システムはそのオブジェクトの参照カウントを増加させる。オブジェクトは、参照カウントが0になるまで削除されることはない。

アプリケーションは、シーンのルートオブジェクトについてのみ、参照カウントを保持する必要がある。他のオブジェクトの参照カウントは、自動的にシステムが管理する。アプリケーションは、終了する前にシーンやビューポート、デバイスを解放するだけでよい（アプリケーションがビューポートを解放すると、システムは自動的にカメラの参照カウントを処理する）。理論的には、新しいビューポートをデバイスに追加する場合のように、アプリケーションはデバイスを解放せずにビューポートを解放することができる。しかし、デバイスを解放するときは、同様にビューポートも解放しなくてはならない。

子オブジェクトやビジュアル・オブジェクトの参照カウントは、フレームに追加されるときに増やされる。IDirect3DRMFrame::AddChildメソッドを使用して、ある親オブジェクトから別の親に子オブジェクトを移動すると、システムは自動的に参照カウントを操作する。

アプリケーションがビジュアル・オブジェクトをシーンにロードした後は、シーンがオブジェクトの参照カウントを管理する。アプリケーションにとっては、ビジュアル・オブジェクトはもう不要となり、解放することができる。

ラップの作成と適用は、どのオブジェクトの参照カウントも増加させない。ラッピングは、単にテクスチャの座標を計算するだけの便利なメソッドにすぎないためである。


IDirect3DRMインターフェイス

アプリケーションは、IDirect3DRMインターフェイスのメソッドを用いて、Direct3DRMオブジェクトを作成し、システム・レベルの変数を使用することができる。このインターフェイスのメソッドについては、「IDirect3DRM」を参照されたい。

IDirect3DRMインターフェイスのメソッドは、以下のオブジェクトを生成することができる。

アニメーションとアニメーション・セット

デバイス

面（face）

フレーム

初期化されていない一般オブジェクト

光

マテリアル

メッシュとメッシュ ビルダ

陰影

テクスチャ

ユーザ・ビジュアル

ビューポート

ラップ


IDirect3DRMAnimationとIDirect3DRMAnimationSetインターフェイス

保持モードのアニメーションは、キーのセットで定義される。キーとは、スケーリング操作、向き、あるいは位置に関連付けられたタイム値である。Direct3DRMAnimationオブジェクトは、タイム値によってどのように変換処理が行われるかを定義するものである。アニメーションは、Direct3DRMFrameオブジェクト上で動作するように設定することができる。このためDirect3DRMAnimationオブジェクトは、Direct3DRMVisual、Direct3DRMLight、およびDirect3DRMViewport オブジェクトの位置・向きのアニメーションやスケーリングに使用することができる。

IDirect3DRMAnimation::AddPositionKey、 IDirect3DRMAnimation::AddRotateKey、IDirect3DRMAnimation::AddScaleKeyメソッドは、それぞれ任意の単位のタイム値を設定する。たとえば、アプリケーションがタイム値99のポジション・キーを追加した場合、タイム値49の新しいポジション・キーは、アニメーションの（0から始まる）開始時点と最初のポジション・キーのちょうど中間でイベントを生成する。

アニメーションは、IDirect3DRMAnimation::SetTimeメソッドの呼び出しによって制御される。このメソッドは、ビジュアル・オブジェクトを新しい位置と向きに変換し、最も近いキーのスケールに設定する。アニメーション・キーを追加するメソッドにおいて、IDirect3DRMAnimation::SetTimeのタイム値は、アプリケーションがすでに追加したキーの位置に基づいた任意の値である。

Direct3DRMAnimationSetオブジェクトは、Direct3DRMAnimationSetオブジェクトをグループ化することができる。これによって、アニメーション・セット中のすべてのアニメーションは同じタイム・パラメータを共有し、複雑なアニメーションの再生が簡略化される。アプリケーションは、IDirect3DRMAnimationSet::AddAnimationメソッドを用いてアニメーションをアニメーション・セットに追加することができる。アニメーションを削除するには、IDirect3DRMAnimationSet::DeleteAnimationメソッドを使用する。アニメーション・セットは、IDirect3DRMAnimationSet::SetTimeメソッドの呼び出しによって制御される。

関連情報については、「IDirect3DRMAnimation」および「IDirect3DRMAnimationSet」インターフェイスを参照されたい。


IDirect3DRMDeviceとIDirect3DRMDeviceArrayインターフェイス

レンダリングされたすべての出力形式は、出力デバイスと関連していなくてはならない。デバイス・オブジェクトは、レンダリングの出力先の可視ディスプレイを表している。

レンダリングの動作は、指定された出力デバイスのタイプに依存する。デバイスに複数のビューポートを定義し、同時に表示されるシーンに異なる視点を与えることもできる。また、デバイスはいくつでも指定でき、同じシーンに複数の出力先を用意することも可能である。

保持モードは、スクリーンやウィンドウ、またはアプリケーション・メモリに直接レンダリングするデバイスをサポートする。

関連情報については「IDirect3DRMDevice」を参照されたい。

このセクションでは、Direct3Dイメージを出力デバイスに表示する際に有効なオプションについて説明する。

クオリティ

カラー・モデル

ウィンドウ管理


クオリティ

シーンやその構成要素は、デバイスによって、リアルさをさまざまに変えてレンダリングすることができる。各メッシュは独自のクオリティを持っているが、メッシュが利用できるクオリティの上限はデバイスに依存する。

アプリケーションは、IDirect3DRMDevice::SetQualityや IDirect3DRMMeshBuilder::SetQualityメソッドを用いて、デバイスのレンダリング精度を変更することができる。デバイスのレンダリング精度を取得するには、IDirect3DRMDevice::GetQualityやIDirect3DRMMeshBuilder::GetQualityメソッドを使用する。


カラー・モデル

保持モードは、RGBモデルとモノクロ（ランプ）モデルのふたつのカラー・モデルをサポートする。カラー・モデルを取得するためには、アプリケーションからIDirect3DRMDevice::GetColorModelメソッドを使用する。

RGBモデルは、色を赤、緑、青の光の組み合わせとして扱い、色の付いた複数の光源をサポートする。シーンで使われる色数には制限がない。このモデルは、8、16、24、32ビットのディスプレイで利用することができる。ディスプレイの表示可能色数が24ビットよりも少ないと、色解像度の制限によって階段状に階調が変化するのが目立つバンディング（マッハバンドとも呼ぶ）が発生する場合がある。これは、オプションのディザ処理を用いることで回避することができる。

モノクロ・モデルでも複数の光源はサポートされるが、その色要素は無視される。それぞれの光源は、グレーの光度で設定される。頂点のRGBカラーは輝度として解釈され、（グロー・シェーディング・モードでは）異なる明るさで頂点の間を補完する。モノクロ・モデルでは、シーン上のオブジェクトの色数が制限される。システム・パレットの空きエントリをすべて使い尽くすと、システム内部のパレット・マネージャは、指定された色に最も近い色をパレット内から探す。モノクロ・モデルは、RGBモデルと同様に、8、16、24、32ビットのディスプレイで使用することができる。（ただし、モノクロ・モデルは8ビットのテクスチャしかサポートしない。）RGBモデルの代わりにモノクロ・モデルを使用する利点は、パフォーマンスが向上することだけである。

Direct3Dデバイスのカラー・モデルは、変更することができない。アプリケーションは、必要なカラー・モデルをサポートしたドライバを識別するために、IDirect3D::EnumDevicesメソッドかIDirect3D::FindDeviceメソッドを使用し、デバイス作成メソッドの中でそのドライバを指定しなくてはならない。


ウィンドウ管理

正しい操作を行うために、オペレーティング・システムからWM_MOVEやWM_PAINT、WM_ACTIVATEメッセージを受け取ったとき、アプリケーションは、IDirect3DRMWinDevice::HandlePaintおよびIDirect3DRMWinDevice::HandleActivateメソッドを使用してDirect3Dに通知しなくてはならない。

関連情報については「IDirect3DRMWinDevice」を参照されたい。


IDirect3DRMFaceとIDirect3DRMFaceArray インターフェイス

面は、メッシュ上のひとつのポリゴンを表している。アプリケーションは、IDirect3DRMFace::SetColor、 IDirect3DRMFace::SetColorRGB、IDirect3DRMFace::SetTexture、 IDirect3DRMFace::SetMaterialメソッドを使用して、面の色やテクスチャ、マテリアルを設定することができる。

面は、IDirect3DRMFace::AddVertexやIDirect3DRMFace::AddVertexAndNormalIndexedメソッドによって、頂点から構成される。アプリケーションから面の頂点を読み取るには、IDirect3DRMFace::GetVerticesやIDirect3DRMFace::GetVertexメソッドを使用する。

関連情報については「IDirect3DRMFace」を参照されたい。


IDirect3DRMFrameとIDirect3DRMFrameArrayインターフェイス

フレームという用語は、オブジェクトの物理フレームを参照していることから来ている。保持モードにおけるフレームの役割は、ウィンドウ・システムにおけるウィンドウの役割に似ている。オブジェクトは、単にワールド空間に置かれるのではなく、関連する参照フレームとの空間的なリレーションシップ（相互関係）を記述することによってシーンに配置される。フレームはオブジェクトをシーンに配置する。また、ビジュアル・オブジェクトを表示するときには、フレームから位置や向きを取得する。

保持モードのシーンは、親フレームを持たないフレーム、つまり、フレーム階層のトップにあるフレームによって定義される。このフレームは、ルート・フレームと呼ばれる。シーンは、他のすべてのオブジェクトへの参照フレームも定義している。

シーンは、他のすべてのオブジェクトについて参照フレームを定義している。第1パラメータにNULLを指定してIDirect3DRM::CreateFrame関数を呼び出し、シーンを作成することができる。

フレームを操作するためには、Direct3Dの左手座標系を理解しなくてはならない。座標系について詳しくは「3D座標系」を参照されたい。

関連情報については「IDirect3DRMFrame」を参照されたい。

このセクションでは、フレームとその使用法について説明する。

階層

変換

動き（モーション）

コールバック関数


階層

シーンのフレームは階層構造になっている。フレームは親フレームや子フレームを持つことができる。親フレームを持たないフレームはルート・フレームと呼ばれ、シーンを定義する。

子フレームは、親フレームに対して相対的な位置と向きを示している。親フレームが移動すると、子フレームも移動する。

フレームの位置や向きは、シーン上の他のフレームからの相対値で設定することができる。絶対位置を設定する必要がある場合は、ルート・フレームからの相対値が使用できる。また、ある親フレームからフレームを削除し、IDirect3DRMFrame::AddChildメソッドにより、いつでも他のフレームに追加することができる。子フレームを完全に削除するにはIDirect3DRMFrame::DeleteChildメソッドを使用する。子フレームや親フレームを取得するには、IDirect3DRMFrame::GetChildrenやIDirect3DRMFrame::GetParentメソッドを使用する。

フレームは、他のフレームのビジュアル・オブジェクトとして追加でき、与えられた階層構造を、シーン全体に渡って何度も利用することが可能になる。新しい階層はインスタンスと呼ばれる。パフォーマンスの低下を防ぐため、親フレームを子フレームに入れ込まないように注意が必要である。保持モードは、実行時に巡回階層のチェックを行わない。巡回階層の作成は、IDirect3DRMFrameインターフェイスのメソッドではできず、フレームをビジュアル・オブジェクトとして追加するときにのみ可能である。


変換

フレームの位置や向きは、親フレームから相対的に考えることもできる。この場合、線形変換によって親フレームから子フレームへの相対ベクトルを取得し、親フレームへの相対ベクトルを求める。

変換は4行4列の行列によって表現される。座標を示すには、[x, y, z, 1]のように列の要素を使用する。

子フレームにおける座標をvchildとすると、同じ座標を親フレームで表す式は、次のように定義される。

vparent=vchildTchild
Tchildは、子フレームの変換行列である。

子フレームからルート・フレームまでのすべての親フレームの変換は、子フレームがワールド座標を生成する変換と結び付けられている。このワールド変換は、レンダリングの前に、子フレーム上のビジュアル・オブジェクトに対して適用される。子フレームに対する相対座標は、モデル座標と呼ばれることがある。ワールド変換が行われた座標は、ワールド座標と呼ばれる。

フレームの変換は、IDirect3DRMFrame::AddTransform、IDirect3DRMFrame::AddScale、IDirect3DRMFrame::AddRotation、IDirect3DRMFrame::AddTranslationの各メソッドによって、直接変更することができる。それぞれのメソッドにはD3DRMCOMBINETYPE列挙型のメンバを渡し、どのようにアプリケーションが提供した行列を現在のフレームの行列と合成するかを指定する。

IDirect3DRMFrame::GetRotationとIDirect3DRMFrame::GetTransformメソッドは、フレームの回転軸と変換行列を取得する。フレームの回転を変更するには、IDirect3DRMFrame::SetRotationメソッドを利用する。

ワールド座標とモデル座標を変換するには、IDirect3DRMFrame::TransformとIDirect3DRMFrame::InverseTransformメソッドを使用する。

変換についての総合的な情報は、ビューポートについて説明したセクション「変換」で得ることができる。変換モジュールについては、「Direct3Dアーキテクチャ」に含まれる「変換モジュール」セクションで取り扱っている。変換計算の概要については、「3D変換」を参照されたい。


動き（モーション）

各フレームは固有の回転や速度で動く。回転も移動もしないフレームでは、これらの属性は0である。これらの属性は、シーンをレンダリングしてオブジェクトを動かす前に使用され、単純なアニメーションを作成することもできる。


コールバック関数

フレームは、より複雑なアニメーションを実現するため、コールバック関数をサポートしている。アプリケーションが登録したコールバック関数は、モーション属性が適用される前にフレームから呼び出される。階層に複数のフレームがあり、それぞれがコールバック関数に関連付けられている場合は、子フレームの前に親フレームが呼び出される。このような階層では、コールバック関数のすべてが呼び出されるまで、レンダリングは実行されない。

コールバック関数を追加するには、IDirect3DRMFrame::AddMoveCallbackメソッドを使用する。コールバック関数を削除するには、IDirect3DRMFrame::DeleteMoveCallbackメソッドを使用する。

これらのコールバック関数を用いると、プログラム済みのアニメーション・シーケンスに新しい位置や向きを設定したり、シーン上の他のオブジェクトの位置によってビジュアル・オブジェクトの動作を動的にインプリメントすることができる。


IDirect3DRMLightとIDirect3DRMLightArrayインターフェイス

シーンをリアルに見せるためには、照明効果を利用する。システムは、シーンの光源に対するオブジェクトの向きに基づいて、すべてのオブジェクトを彩色する。オブジェクトの色は、レンダリング中に各光源の影響を考慮して決定される。すべての光源は色と輝度を持っており、別々に変化させることができる。

アプリケーションはフレームに光をアタッチし、シーンに光源を与えることができる。フレームにアタッチされた光は、シーン上のビジュアル・オブジェクトを明るくする。フレームは、光の位置と向きの両方を提供する。言い換えれば、光はアタッチされたフレームの原点から広がっていく。アプリケーションは、光源がアタッチされたフレームを動かしたり回転することによって、光源の移動や方向転換を簡単に実現することができる。

ビューポートはそれぞれひとつ以上の光源をもっている。しかし、ひとつの光源がひとつ以上のビューポートに保持されることはない。Direct3Dコンポーネントの相互作用について詳しくは、「オブジェクトの結合性」を参照されたい。

現状では、保持モードは、アンビエント（環境光） 、ディレクショナル、パラレル・ポイント、ポイント、スポットライトの5種類の光源を提供している。

IDirect3DRMLightインターフェイスのメソッドのリファレンスは、「IDirect3DRMLight」を参照されたい。

このセクションでは、Direct3Dで利用することができる照明効果とその使い方について説明する。

アンビエント （環境光）

ディレクショナル

パラレル・ポイント

ポイント

スポットライト


アンビエント（環境光）

アンビエント光源は、オブジェクトの向き、位置、サーフェスの特性などと関係なく、シーン上のすべてを照らす光である。シーンのすべての場所を同じ光度で照らすため、アタッチされたフレームの位置や向きは重要でない。ひとつのシーンには、複数のアンビエント・ライトが結合されている。


ディレクショナル

有向光源は向きを持つが、位置は持っていない。フレームにアタッチされるとすべてのオブジェクトを同じ輝度で照らし、光源がオブジェクトからずっと離れた位置にあるような効果を与える。ディレクショナル光源は、太陽のような遠く離れた光源をシミュレートするために利用される。


パラレル・ポイント

パラレル・ポイント光源はパラレル・ライトでオブジェクトを照らすが、光の向きは光源の位置から決定される。つまり、パラレル・ポイント光源にはディレクショナル光源のように向きがあり、さらに位置も持っている。たとえば、パラレル・ポイント光源の両側にメッシュがある場合、光源に面しているほうのメッシュが明るくなる。パラレル・ポイント光源のレンダリング・スピードは、ディレクショナル光源と同等である。


ポイント

ポイント光源は、光源から放射状に光を放つ。光が当たる面や法線のそれぞれについて、新しい光のベクトルを計算する必要があるため、パラレル・ポイント光源よりも計算時間がかかる。しかし、より正確な照明効果が実現できるので、リアルな表示が要求される場合に利用するべきである。


スポットライト

スポットライト光源は円錐状の光を生成する。光は、円錐の内部にあるオブジェクトにのみ当てられる。円錐はふたつの輝度を生成する。中央の明るい部分（明部）はポイント光源と同じ働きをし、周囲の薄暗い部分（暗影部）は、その周辺の暗い影とマージされる。このふたつの部分の角度は、IDirect3DRMLight::GetPenumbra、IDirect3DRMLight::GetUmbra、IDirect3DRMLight::SetPenumbra、およびIDirect3DRMLight::SetUmbraによって個々に指定することができる。


IDirect3DRMMaterialインターフェイス

マテリアルは、サーフェスがどのように光を反射するかを定義する。マテリアルには、光を反射するかの放射特性（emissive）と反射特性（specular）のふたつの構成要素がある。反射の明るさは、強度の設定によって決定される。強度の値は反射のハイライト部分の鮮明度を決定する。強度が5のときは金属的な外観になり、それ以上の値では、より柔らかい外観となる。

アプリケーションからマテリアルの放射特性を制御するには、IDirect3DRMMaterial::GetEmissiveとIDirect3DRMMaterial::SetEmissiveメソッドを使用する。反射特性はIDirect3DRMMaterial::GetSpecularとIDirect3DRMMaterial::SetSpecularメソッドによって、強度はIDirect3DRMMaterial::GetPowerとIDirect3DRMMaterial::SetPowerメソッドを用いて制御する。

IDirect3DRMMaterialインターフェイスのメソッドのリファレンスは、「IDirect3DRMMaterial」を参照されたい。


IDirect3DRMMeshとIDirect3DRMMeshBuilderインターフェイス

メッシュとは、ポリゴンの面のセットで構成されたビジュアル・オブジェクトである。メッシュは頂点のセットと面のセットを定義する（面は頂点とメッシュの法線によって定義される）。いくつかの面で使われている頂点や法線を変更すると、それを共有するすべての面の外観が変更される。

メッシュの頂点は、メッシュ上の面の位置を定義する。また、テクスチャ・マップの2D座標を決定するためにも用いられる。

保持モードでは、IDirect3DRMMeshとIDirect3DRMMeshBuilderのふたつのCOMインターフェイスを利用してメッシュを操作することができる。IDirect3DRMMeshインターフェイスは非常に高速で、モーフィングのように頻繁にメッシュが変化する場合は、これを使用するべきである。IDirect3DRMMeshBuilderは、IDirect3DRMMeshインターフェイスの上部に組み込まれている。IDirect3DRMMeshBuilderインターフェイスは個々の面や頂点を操作する際に便利であるが、システムはレンダリングを実行する前に、Direct3DRMMeshBuilderオブジェクトをDirect3DRMMeshオブジェクトに変換しなくてはならない。メッシュが全く変化しない、あるいは滅多に変化しない場合は、この変換がパフォーマンスに与える影響は無視できる程度のものである。

いくつかの頂点や面に同じ特性（マテリアルやテクスチャ）を割り当てる必要があるアプリケーションでは、IDirect3DRMMeshインターフェイスを用いてグループ化することができる。ふたつの異なるグループで頂点を共有したい場合（たとえば、メッシュ上の隣接した面の色が異なる場合）は、それぞれのグループで頂点を複製しなくてはならない。IDirect3DRMMesh::AddGroupメソッドは、面の集合にグループ識別子をアサインする。この識別子は、その後の呼び出しでグループを参照するために使用することができる。

アプリケーションは、IDirect3DRMMeshBuilderとIDirect3DRMMeshインターフェイスによって、３つ以上の表面を持つ面を作成することができる。また、たとえば、レンダリングするハードウェアが64Ｋバイトの制限を持っており、メッシュのサイズがそれよりも大きい場合には、これらのインターフェイスはメッシュを自動的に複数のバッファに分割する。これらの機能のために、Direct3DRMMeshとDirect3DRMMeshBuilderのAPIはDirect3D APIから離れたものになっている。

メッシュに頂点や面を個々に追加するには、IDirect3DRMMeshBuilder::AddVertex、IDirect3DRMMeshBuilder::AddFace、およびIDirect3DRMMeshBuilder::AddFacesメソッドを使うことができる。

IDirect3DRMMesh::SetGroupColor、IDirect3DRMMesh::SetGroupColorRGB、IDirect3DRMMesh::SetGroupTexture、IDirect3DRMMesh::SetGroupMaterialの各メソッドを用いると、面の色やテクスチャ、マテリアルの特性を個々に定義することができる。これらはメッシュ上のそれぞれの面について設定することも、すべての面について1度に設定することも可能である。

メッシュをレンダリングするには、まずIDirect3DRMFrame::AddVisualメソッドを使用して、メッシュをフレームに追加しなくてはならない。メッシュのインスタンスを複数生成して、ひとつのメッシュを複数のフレームに追加することができる。

アプリケーションは、IDirect3DRMMesh::SetGroupQualityメソッドの呼び出しで指定することにより、フラット、グロー、フォンの３つの陰影モードを使用することができる（ただし、現状ではフォン・シェーディング・モードはサポートされていない）。このメソッドには、D3DRMRENDERQUALITY列挙型の値を指定する。シェーディングモードについて詳しくは「ポリゴン」を参照されたい。

アプリケーションは、法線（ひとつのベクトルでなくてはならない）を設定することができる。また、IDirect3DRMMeshBuilder::GenerateNormalsメソッドにより、周囲の面の面法線を平均して法線を計算することもできる。


Direct3DRMObject

Direct3DRMObjectは、システムのすべてのオブジェクトに共通な基本クラスである。Direct3DRMObjectオブジェクトは、すべてのオブジェクトに共通な特性を備えている。

Direct3DRMObjectオブジェクトは、COMオブジェクトとしてインスタンス生成が行われる。各オブジェクトは、IUnknownインターフェイスに加え、一般的なメソッドの標準セットを含んでいる。

オブジェクトを作成するには、まずDirect3DRMCreate関数を呼び出し、Direct3Dの保持モード・オブジェクトのインスタンスを生成しなくてはならない。次にアプリケーションは、オブジェクトを作成するインターフェイスのメソッドを呼び出し、オブジェクトに固有のパラメータを指定する。たとえば、Direct3DRMAnimationオブジェクトを作成するにはIDirect3DRM::CreateAnimationメソッドの呼び出しを行う。作成メソッドは新しいオブジェクトを作成し、パラメータで渡されたデータから、いくつかのオブジェクトの属性を初期化し、そのオブジェクトを返す。パラメータで指定されない属性にはデフォルトの値を与えておく。アプリケーションは、このオブジェクトのインターフェイスを指定して属性を変更し、オブジェクトの使用を開始することができる。

すべてのオブジェクトは、アプリケーション定義の32ビットのデータを格納することができる。保持モードでは、このデータが解析されたり変更されたりすることはない。アプリケーションからこのデータを読み取るには、IDirect3DRMObject::GetAppDataメソッドを使用する。データの書き込みには、IDirect3DRMObject::SetAppDataメソッドを使うことができる。アプリケーションが各Direct3DRMFrameオブジェクトの構造体を保持していれば、このデータを取得するのは簡単である。たとえば、IDirect3DRMFrame::GetParentメソッドを呼び出してDirect3DRMFrameオブジェクトを受け取る場合、アプリケーションはプライベートな構造体へのポインタを用い、時間のかかる検索を行わずに容易にデータを取得することができる。

アプリケーションの構築を補助するために、またはアプリケーションのユーザ・インターフェイスの1部として、オブジェクトに名前を割り当てたいことがあるだろう。オブジェクトの名前を設定・取得するには、IDirect3DRMObject::SetNameとIDirect3DRMObject::GetNameメソッドを使用する。

アプリケーション固有のデータの使い方のもうひとつの例として、アプリケーションがメッシュ上の面をサブセットにグループ化したい場合（たとえば、フロントとバックの集合にグループ化する場合）が考えられる。このとき、ある面がどちらのグループに属すかを記憶するために、アプリケーション定義のデータを利用することができる。

アプリケーションは、オブジェクトが破棄されるときに呼び出す関数を指定することができる。この関数が呼び出されたとき、アプリケーションは、オブジェクトに関連付けられたメモリを解放しなくてはならない。関数を指定するには、 IDirect3DRMObject::AddDestroyCallbackメソッドを使用する。以前にこのメソッドによって登録された関数を削除するには、IDirect3DRMObject::DeleteDestroyCallbackメソッドを呼び出す。

コールバック関数は、オブジェクトが破棄されるときだけ呼び出される。つまり、オブジェクトの参照カウントが0に達し、システムがオブジェクトのメモリを解放しようとしているときである。アプリケーションがオブジェクトについての付加情報を保持している場合、このコールバック関数を利用して、データを破棄してよいことをアプリケーション自身に通知することができる。

関連情報については「IDirect3DRMObject」を参照されたい。


IDirect3DRMPickedArrayインターフェイス

2D座標をビューポートに渡し、シーン上のビジュアル・オブジェクトを見つけるプロセスをピッキングという。IDirect3DRMPickedArrayインターフェイスを取得するには、IDirect3DRMViewport::Pickメソッドを使用することができる。それからIDirect3DRMPickedArray::GetPickメソッドを呼び出して、IDirect3DRMFrameArrayインターフェイスとビジュアル・オブジェクトを受け取ることができる。フレームの配列は、階層を経てビジュアル・オブジェクトに到達するパス、つまりビジュアル・オブジェクトの親フレームの階層リストである。階層のトップにある親フレームは、配列の先頭に格納される。


IDirect3DRMShadowインターフェイス

アプリケーションは、IDirect3DRM::CreateShadowメソッドを呼び出すだけで、初期化済みの使用可能な陰影を生成することができる。IDirect3DRMShadowインターフェイスの存在によって、IDirect3DRM::CreateObjectメソッドを用いて陰影を作成するアプリケーションは、その初期化をIDirect3DRMShadow::Initを呼び出して行うことができる。


IDirect3DRMTextureインターフェイス

テクスチャは、色付きのピクセルが矩形に並んだものである（矩形は必ずしも正方形でなくてもよいが、システムが最も効率的に動作するのは正方形の場合である）。テクスチャはテクスチャ・マッピングの面として使うこともできるが、この場合は正方形でなくてはならない。

IDirect3DRMTextureインターフェイスは、実際はDirectDrawSurfaceオブジェクトへのインターフェイスであり、特別なDirect3Dのテクスチャ・オブジェクトというわけではない。Direct3DのテクスチャとDirectDrawのサーフェスの関係については、「Direct3Dテクスチャ・インターフェイス」を参照されたい。

アプリケーションは、D3DRMIMAGE構造体からテクスチャを作成するために、IDirect3DRM::CreateTextureメソッドを使うことができる。また、IDirect3DRM::CreateTextureFromSurfaceメソッドによってDirectDrawサーフェスからテクスチャを作成することもできる。さらに、IDirect3DRM::LoadTextureメソッドを用いると、ファイルからテクスチャをロードすることができる。この場合、テクスチャはWindowsのビットマップ（.bmp）か、ポータブル・ピクスマップ・フォーマット（.ppm）でなくてはならない。

各面のテクスチャ座標は、その特定の面にマッピングされるテクスチャのリージョンを定義している。アプリケーションは、テクスチャ座標を計算するためにラップを利用することができる。詳しくは「IDirect3DRMWrapインターフェイス 」を参照されたい。

このインターフェイスのメソッドのリファレンスは、「IDirect3DRMTexture」を参照されたい。

このセクションでは、Direct3Dがサポートするテクスチャの種類と使い方を説明する。

デカール

テクスチャの色

ミップマップ

テクスチャ・フィルタリング

テクスチャの透明化


デカール

テクスチャは、ビジュアル・オブジェクトとして直接レンダリングすることができる。このように用いられるテクスチャは、 デカールとして知られている。デカールとは保持モードで採用された用語である。デカールは、ビューポートと一致した矩形にレンダリングされる。この矩形は、オプションとして、デカールの立体位置によるスケーリングが可能である。IDirect3DRMTexture::SetDecalSizeメソッドを使用すると、フレームに対して相対的に定義された矩形からデカールのサイズを設定することができる。（アプリケーションは、IDirect3DRMTexture::GetDecalSizeメソッドによってデカールのサイズを知ることができる。）その後、デカールは変換され、透視投影される。

デカールの原点は、アプリケーションから設定および取得することができる。これにはIDirect3DRMTexture::SetDecalOriginやIDirect3DRMTexture::GetDecalOriginメソッドを用いる。原点は、デカールの左上隅からのオフセットで表される。デフォルトの原点は[0, 0]である。レンダリングの際には、デカールの原点はフレームの位置に合わせられる。


テクスチャの色

テクスチャのレンダリングで用いられる色数を取得・設定するには、IDirect3DRMTexture::SetColorsとIDirect3DRMTexture::GetColorsメソッドを利用する。

RGBカラー・モデルを用いるアプリケーションでは、8ビット、24ビット、32ビットのテクスチャを使用することができる。しかし、モノクロ（ランプ）・カラー・モデルを用いる場合には、8ビットのテクスチャのみ使用できる。

シーンに光を適用するとき、それぞれの色の影が使用される。使われている影の数の設定や取得を行うには、アプリケーションからIDirect3DRMTexture::SetShadesやIDirect3DRMTexture::GetShadesメソッドを呼び出す。

Direct3DRMTextureオブジェクトは、テクスチャがレンダリングされる元となるビットマップを定義するためにD3DRMIMAGE構造体を使用する。アプリケーションがD3DRMIMAGE構造体を提供すれば、レンダリング中に簡単にテクスチャを動かしたり変更できる。


ミップマップ

ミップマップとは連続したテクスチャを示し、各テクスチャは、同じイメージにフィルタをかけて徐々に低解像度にしたものである。ミップマップは、計算上低コストにテクスチャのレンダリング精度を高める手段である。ミップマップ中のフィルタされたイメージやレベルは、前のレベルよりも小さくなっていく。ミップマップは、IDirect3DRMDevice::SetTextureQualityメソッドを呼び出してテクスチャをフィルタリングするときに指定することができる。

ミップマップの作成について詳しくは「ミップマップ」を参照されたい。


テクスチャ・フィルタリング

テクスチャが面にマッピングされた後は、テクスチャ要素（テクセル）が最終イメージの個々のピクセルと一致することは滅多にない。最終イメージ中のピクセルは、テクセルの大きな集合体か、ひとつのテクセルの小部分に相当する。ピクセルにテクセルの値を補完する方法を指定するには、テクスチャ・フィルタリングを利用する。

アプリケーションは、IDirect3DRMDevice::SetTextureQualityメソッドとD3DRMTEXTUREQUALITY列挙型を使用して、テクスチャ・フィルタリング・モードを指定することができる。


テクスチャの透明化

透明なテクスチャを生成するにはIDirect3DRMTexture::SetDecalTransparencyメソッドを利用する。テクスチャを透明化する他の方法としては、DirectDrawがサポートするカラー・キーを使用する方法がある。カラー・キーとは、ブロック転送やオーバーレイ操作における、転送元あるいは転送先部分の色または色の範囲である。これらの色は、つねに上書きされるようにも、決して変更されないようにも指定することができる。

DirectDrawのカラー・キー・サポートについて詳しくは、「カラー・キーイング」を参照されたい。

関連情報については「IDirect3DRMTexture」を参照されたい。


IDirect3DRMUserVisualインターフェイス

ユーザ・ビジュアル・オブジェクトは、シーンやレンダリングに追加することができるアプリケーション定義のデータである。一般的には、カスタマイズされたレンダリング・モジュールが使用する。たとえばアプリケーションは、ユーザ・ビジュアル・オブジェクトとしてシーンにサウンドを追加し、再生中にサウンドをレンダリングすることができる。

ユーザ・ビジュアル・オブジェクトを作成するにはIDirect3DRM::CreateUserVisualメソッドを使用する。また、IDirect3DRMUserVisual::Initメソッドは、ユーザ・ビジュアル・オブジェクトの初期化を行う。


IDirect3DRMViewportとIDirect3DRMViewportArrayインターフェイス

ビューポートは、3Dシーンがどのように2Dウィンドウにレンダリングされるかを定義する。ビューポートは、オブジェクトがレンダリングされるデバイス上の矩形領域を定義する。

このインターフェイスのメソッドのリファレンスは、「 IDirect3DRMViewport」を参照されたい。

このセクションでは、ビューポートとその構成要素、使用上のテクニックについて説明する。

カメラ

視錐台

変換

ピッキング


カメラ

ビューポートはDirct3DRMFrameをカメラとして使用する。カメラ・フレームは、レンダリングされるシーン、表示位置および方向を定義する。ビューポートは、カメラ・フレームの正のz軸上にある可視オブジェクトだけを、y軸上の正方向にレンダリングする。

アプリケーションは、与えられたビューポートにカメラをセットするために、IDirect3DRMViewport::SetCameraメソッドを用いることができる。このメソッドは、ビューポートの位置、方向、向きをカメラ・フレームに設定する。現在のカメラの設定を取得するには、 IDirect3DRMViewport::GetCameraメソッドを呼び出す。


視錐台

視錐台は、ビューポートのカメラに対して相対的に配置された、シーン上の3Dボリュームである。視錐台の中にあるオブジェクトは可視状態である。透視投影では、前方クリップ面と後方クリップ面の間の仮想ピラミッドのボリュームを指す。

カメラはピラミッドの頂点にあり、頂点から底辺の中央に向かってz軸が延びている。前方クリップ面はカメラから距離Dの位置にある。また、後方クリップ面は、前方クリップ面から距離Fの位置にある。これらの値は、IDirect3DRMViewport::SetFront、IDirect3DRMViewport::SetBack、IDirect3DRMViewport::GetFront、およびIDirect3DRMViewport::GetBackメソッドを呼び出して設定・取得することができる。前方クリップ面の高さは2hで、ビューのフィールドを定義する。hの値を設定・取得するには、IDirect3DRMViewport::SetFieldおよびIDirect3DRMViewport::GetFieldメソッドを使用する。

ビューの角度Aは次の等式によって定義される。カメラ・アングルが特定されているとき、この式によってhの値を計算することができる。

視錐台のピラミッドは、透視投影の場合にのみ適用される。平行投影においては、視錐台は立方体になる。ビューのタイプ（あるいは投影方法）はD3DRMPROJECTIONTYPE列挙型で定義されており、IDirect3DRMViewport::GetProjectionおよびIDirect3DRMViewport::SetProjectionメソッドで使われる。


変換

3D座標のオブジェクトを2Dウィンドウにレンダリングするためには、オブジェクトをカメラ・フレーム内に変換しなくてはならない。そこで、4つの要素を持つ同質の座標[x y z w]を求めるため、射影行列が用いられる。座標[x y z w]は、3要素の座標[x/w y/w z/w]を取得するために使われる。[x/w y/w]はウィンドウが使用する座標である。また、z/wは奥行きを0から1の範囲で示し、0は前方クリップ面、1は後方クリップ面となる。射影行列は、透視変換の後にオブジェクトのスケーリングと移動を結合したものである。

次の行列が射影行列である。この等式において、hは視錐台の半分の高さ、Fは後方クリップ面のz座標、Dは前方クリップ面のz座標を示している。

Direct3Dでは、射影行列の4,4要素に負の値を設定することはできない。

次の行列は、ウィンドウ・スケーリングを行う（スケールはウィンドウのサイズと位置に依存する）。この公式では、sはウィンドウのスケーリング係数、oはウィンドウの原点である。

次の行列はビュー行列である。これは、射影行列とウィンドウ行列の合成、言い換えればPとWの積である。

スケーリング係数と原点sx、sy、ox、oyは、[-h -h D]から[h h D]までのリージョンがウィンドウの高さや幅に正確にフィットするように選択される。

スクリーン座標からワールド座標、また逆にワールド座標からスクリーン座標にベクトルを変換するには、IDirect3DRMViewport::TransformやIDirect3DRMViewport::InverseTransformメソッドを使用する。次の例のように、アプリケーションは、これらのメソッドを利用してドラッグをサポートすることができる。

/*

 * Drag a frame by [delta_x delta_y] pixels in the view.

 */

void DragFrame(LPDIRECT3DRMVIEWPORT view,

    LPDIRECT3DRMFRAME frame,

    LPDIRECT3DRMFRAME scene,

    int delta_x, int delta_y)

{

    D3DVECTOR p1;

    D3DRMVECTOR4D p2;

    frame->GetPosition(scene, &p1);

    view->Transform(&p2, &p1);

    p2.x += delta_x * p2.w;

    p2.y += delta_y * p2.w;

    view->InverseTransform(&p1, &p2);

    frame->SetPosition(scene, p1.x, p1.y, p1.z);

}

ビューポート変換を用いると、ワールド座標でのオブジェクトの移動距離をカメラから奥行きまでの距離と一致させることができる。IDirect3DRMViewport::Transformメソッドの結果は、4つの要素を持つベクトルで表されることに注意されたい。これによって、カメラの位置に限りなく近い座標で生じる問題を回避することができる。

ビューポートの射影行列が生成する3D座標は、視錐台の内部の点だけを明確にしている。投影後の点[x y z w]については、以下の等式が成立する。

フレーム変換については「変換」を参照されたい。また、変換モジュールについては「Direct3Dアーキテクチャ」のセクション「変換モジュール」で説明している。変換計算の概要については、「3D変換」を参照されたい。


ピッキング

ピッキングとは、ビューポートのウィンドウで、2D座標からシーン上のビジュアル・オブジェクトを探索するプロセスである。アプリケーションはIDirect3DRMViewport::Pickメソッドを使用して、シーン上の最も近いオブジェクト、またはオブジェクトの重なり順のリストを取得することができる。


IDirect3DRMVisualとIDirect3DRMVisualArray インターフェイス

ビジュアル・オブジェクトは、シーン上にレンダリングすることができるオブジェクトである。ビジュアル・オブジェクトが可視になるのは、そのシーンのフレームに追加されたときだけである。アプリケーションは、IDirect3DRMFrame::AddVisualメソッドを用いてビジュアル・オブジェクトをフレームに追加する。フレームは、レンダリングに備え、ビジュアル・オブジェクトに位置と向きを提供する。

ビジュアル・オブジェクトのグループを操作するには、IDirect3DRMVisualArrayインターフェイスを使用しなくてはならない。IDirect3DRMVisual COMインターフェイスは存在するが、メソッドを何も持っていない。

最も一般的なビジュアル・オブジェクトのタイプは、Direct3DRMMeshBuilderとDirect3DRMTextureオブジェクトである。


IDirect3DRMWrapインターフェイス

ラップは、面やメッシュのテクスチャ座標の計算に使用することができる。ラップを作成するには、アプリケーションは、ラップのタイプや参照フレーム、原点、方向ベクトル、上ベクトルを指定しなくてはならない。また、スケーリング係数とテクスチャ座標の原点も指定する必要がある。

アプリケーションは、IDirect3DRM::CreateWrapメソッドを呼び出してIDirect3DRMWrapインターフェイスを生成する。このインターフェイスには、IDirect3DRMWrap::ApplyとIDirect3DRMWrap::ApplyRelativeのふたつの特有なメソッドが含まれている。IDirect3DRMWrap::Applyは、オブジェクトの頂点にラップを適用する。IDirect3DRMWrap::ApplyRelativeは、適用されたラップの頂点を変換する。

サンプルでは、方向ベクトル（vベクトル）はz軸に沿い、上ベクトル（uベクトル）はy軸に沿っている。原点は[0, 0, 0]である。

IDirect3DRMWrapインターフェイスのメソッドのリファレンスは「IDirect3DRMWrap」を参照されたい。

このセクションでは、ラッピング・フラグと4つのラッピング・タイプについて説明する。

ラッピング・フラグ

平面

円柱

球体

クロム


ラッピング・フラグ

D3DRMMAPPING型には、D3DRMMAP_WRAPUフラグとD3DRMMAP_WRAPVフラグが含まれている。これらのフラグによって、ラスタライザがテクスチャ座標を解析する方法が決定される。ラスタライザは、つねにテクスチャ座標間の最短距離（つまり直線）補完する。この直線のパスと、有効なuおよびv座標の値は、ラッピング・フラグの使い方によって異なる。フラグの片方あるいは両方がセットされると、直線は、uまたはv方向のテクスチャの辺に沿って、円柱状かドーナツ状の形状かのようにラップアラウンドされる。

ラッピング・フラグがセットされていない平面ラッピング・モードでは、uまたはv座標で指定された平面には、テクスチャが無限にタイリングされる。この場合、有効なuおよびv座標値は1.0以上である。点(0.1, 0.1)と(0.9, 0,9)を結ぶ最短の直線は、点(0.5, 0.5)を通過する。

D3DRENDERSTATE_WRAPUまたはD3DRENDERSTATE_WRAPVのいずれかがセットされた場合、テクスチャは円周1.0の終わりのない円筒形になる。1.0以上のテクスチャ座標は、ラップされていない範囲内のみ有効である。テクスチャ座標間の最短距離はラッピング・フラグによって異なる。D3DRENDERSTATE_WRAPUがセットされているときは、点(0.1, 0.1)から(0.9, 0.9)までの最短の直線は、点（0, 0.5）を通過する。

D3DRENDERSTATE_WRAPUとD3DRENDERSTATE_WRAPVフラグの両方がセットされたときは、テクスチャは円環体（ドーナツ）状になる。システムは閉鎖しているため、1.0以上のテクスチャ座標は無効である。点(0.1, 0.1)から(0.9, 0.9)までの最短の直線は、点(0, 0)を通過する。

無効領域にあったテクスチャ座標を有効領域に収めたとしても、そのときの動作は保証されていない。

一般にアプリケーションは、テクスチャの交線が面の辺と一致しないとき、円柱状にラップするためにラッピング・フラグをセットする。ひとつの面にテクスチャの半分以上が使用される場合には、ラッピング・フラグは設定しない。


平面

平面ラップでは、テクスチャは、オブジェクト上にストレッチされたゴムのようにオブジェクトの面に一致する。

次の等式により、ベクトル[x y z]から[u v]座標が求められる。

u=sux�ou
v=svy�ov
これらの公式において、sはウィンドウのスケーリング係数、oはウィンドウの原点を示している。アプリケーションは、1組のスケーリング係数と、uおよびvが有効な値を取るようにxとyを0から1の範囲にマップするためのオフセットを決定しなくてはならない。


円柱

円柱ラップでは、テクスチャは円柱の回りを包む紙のように扱われ、その左端は右端につながっている。オブジェクトは円周の中央に配置され、オブジェクトのサーフェスに合わせてテクスチャが変形される。

下図は、円柱テクスチャ・マップにおける各ベクトルの効果を示したものである。

方向ベクトルは円柱の軸を示し、上ベクトルは円筒の外側のu = 0である点を示す。システムは、ベクトル[x y z]に対するテクスチャの[u v]座標を計算するために、次の等式を使用する。

通常、uはスケーリングされないままである。vが有効な値を取るようにzを0から1の範囲にマップして、vのスケーリングと変換が行われる。


球体

球体ラップでは、ベクトル[x y 0]とx軸の角度から（円柱ラップと同様に）u座標が求められる。v座標は、ベクトル[x y z]とz軸の角度から求められる。このマッピングでは、z軸上に歪みが生じることに注意が必要である。

これは次の等式で表される。

ここでは、スケーリングされていないuとvの範囲はつねに0から1であるため、スケーリング係数とテクスチャの原点は必要とされないことが多い。


クロム

クロム・ラップは、テクスチャがオブジェクト上に反射して見えるようにテクスチャ座標を割り当てる。クロム・ラップは参照フレームの位置を取得し、反射ベクトルを計算するためにメッシュの頂点法線を使用する。その後、メッシュを取り囲む仮想の球体を利用して、反射ベクトルの交線からテクスチャのuおよびv座標を計算する。これによって、球体に何がラップされていても、メッシュに反射効果が与えられる。


Direct3Dの保持モードのチュートリアル

WindowsベースのDirect3Dの保持モード・アプリケーションを作成するためには、異なるふたつの環境を設定しなくてはならない。ひとつは、デバイス、ビューポート、色解像度といったWindows環境であり、もうひとつは、モデル、テクスチャ、光源、位置といった仮想環境である。このチュートリアルでは、簡単な保持モード・アプリケーションの全コードを紹介している。下図は、動作中のアニメーションのフレームのひとつである。

このチュートリアルは、以下のセクションに分けられている。

Helworld.cについて

マクロ定義とグローバル変数

Windowsのセットアップと初期化

デバイス・ ドライバの列挙

3D環境のセットアップ

レンダリング・ループ

シーンの作成

終了処理


Helworld.cについて

アプリケーションに3Dグラフィックスを導入することは簡単ではないが、決して不可能な仕事ではない。このドキュメントには、Direct3Dの保持モード・アプリケーションの作成に必要なすべてのコードが記載されている。このチュートリアルのコードを、ひとつの.cファイルにコピーすれば、コンパイルして実行することができる（ただし、コンパイラがDirectX SDKのディレクトリにあるSphere3.xファイルを見つけることができ、さらに、Hello.ppmという名前のビットマップ ファイルが用意されていること）。このサンプルでは、3D効果を実現するコードのほとんどは個々の関数に分けられているため、自身の経験に応じて、システムの一部に少しずつ変更を加えることができる。より複雑なDirect3Dの機能をインプリメントするためには、SDKのサンプルを参照するとよい。

このセクションでは、簡単なDirect3Dの保持モード・アプリケーションを開発する上での問題点について、いくつか説明する。

サンプルの制限

スタティック・ライブラリ

DirectDrawのウィンドウ・モード


サンプルの制限

このチュートリアルには、Helworld.cサンプル・コードが含まれている。Helworld.cは、球体を作成し、それにテクスチャを貼り付け、ウィンドウ内で回転させる。このアプリケーションをビルドするために必要なソース・ファイルは、Helworld.cだけである。この他に、DirectX SDKのディレクトリにコピーされたShpere3.xというメッシュ・ファイルと、Hello.ppmという名前のビットマップファイルが必要である。

このサンプルは、DirectX SDKの一部であるGlobeサンプルに基づいているが、説明のためにより簡略化されている。SDKに含まれる他のDirect3D保持モードのサンプルと同様、Globeサンプルには、Rmmain.cppというファイルと数多くのヘッダ・ファイルのインクルードが必要であったが、Helworld.cでは、Rmmain.cppの関連した箇所をC++からCに書き直し、ソース コード中に組み込んでいる。

このチュートリアルで紹介しているコードは、そのまま製品のコードに適用できるわけではない。このプログラムでユーザができることは、プログラムを実行し、終了し、実行中にウィンドウを最小化することだけである。処理をわかりやすくするために、ほとんどのエラー・チェックは省略されている。このサンプルの意図は、画面に�Hello, world!�を表示するだけの有名なプログラムが示すところと類似しており、できるだけわかりやすく、3Dグラフィックスの出力を行うことである。


スタティック・ライブラリ

Direct3Dの保持モード・アプリケーションは、スタティック・ライブラリWinmn.libとD3drm.libをリンクする必要がある。


DirectDrawのウィンドウ・モード

ほとんどすべてのDirect3Dアプリケーションは、DirectDrawを用いてスクリーンにグラフィックスを表示する。これらのアプリケーションは、DirectDrawのフルスクリーン・モード（排他モード）またはウィンドウ・モードのいずれかを使用する。

フルスクリーン・モードには、パフォーマンスや便利さにおいていくつかの利点があるが、ウィンドウ・モードで書かれたコードのほうが、デバッグははるかに容易である。開発者の多くは、最初はウィンドウ・モードでコードを記述し、ほとんどのバグが改修された開発の最終段階で、フルスクリーン・モードに移行する方法を取るだろう。


マクロ定義とグローバル変数

以下のコードは、Helworld.cサンプルの最初の部分である。Helwold.cは、このアプリケーションをビルドするために必要な唯一のファイルであり、他のヘッダ・ファイルやソース・ファイルは不要である。

INITGUIDは、他のインクルードやマクロ定義よりも前にdefineされていなくてはならない。これは、DirectXを初めて操作する開発者が間違いやすい、大切なポイントである。

/////////////////////////////////////////////////////////////////////

//

//  Copyright (C) 1996 Microsoft Corporation. All Rights Reserved.

//

//  File: Helworld.c

//

//  "Globe" SDKサンプルに基づいた、簡単なDirect3D保持モードのサンプル

//

/////////////////////////////////////////////////////////////////////

#define INITGUID                // 他のマクロ定義やインクルードの前に

                                // 定義しなくてはならない

#include <windows.h>

#include <malloc.h>             // memsetの呼び出しに必要

#include <d3drmwin.h>

#define MAX_DRIVERS 5           // D3Dドライバの最大数

// グローバル変数

LPDIRECT3DRM lpD3DRM;           // Direct3DRMオブジェクト

LPDIRECTDRAWCLIPPER lpDDClipper;// DirectDrawClipperオブジェクト

struct _myglobs {

    LPDIRECT3DRMDEVICE dev;     // Direct3DRMデバイス

    LPDIRECT3DRMVIEWPORT view;  // シーンが表示されるDirect3DRMビューポート

    LPDIRECT3DRMFRAME scene;    // 他のオブジェクトが配置されるマスター・フレーム

    LPDIRECT3DRMFRAME camera;   // ユーザのPOVを示すフレーム

    GUID DriverGUID[MAX_DRIVERS];     // 有効なD3DドライバのGUID

    char DriverName[MAX_DRIVERS][50]; // 有効なD3Dドライバの名前

    int  NumDrivers;                  // 有効なD3Dドライバの数

    int  CurrDriver;                  // 現在使われているD3Dドライバの数

    BOOL bQuit;                 // プログラムが終了しようとしている

    BOOL bInitialized;          // すべてのD3DRMオブジェクトが初期化された

    BOOL bMinimized;            // ウィンドウが最小化された

    int BPP;                    // 現在のディスプレイ・モードのビット深度

} myglobs;

// 関数のプロトタイプ

static BOOL InitApp(HINSTANCE, int);

long FAR PASCAL WindowProc(HWND, UINT, WPARAM, LPARAM);

static BOOL EnumDrivers(HWND win);

static HRESULT WINAPI enumDeviceFunc(LPGUID lpGuid,

    LPSTR lpDeviceDescription, LPSTR lpDeviceName,

    LPD3DDEVICEDESC lpHWDesc, LPD3DDEVICEDESC lpHELDesc,

    LPVOID lpContext);

static DWORD BPPToDDBD(int bpp);

static BOOL CreateDevAndView(LPDIRECTDRAWCLIPPER lpDDClipper,

    int driver, int width, int height);

static BOOL SetRenderState(void);

static BOOL RenderLoop(void);

static BOOL MyScene(LPDIRECT3DRMDEVICE dev, LPDIRECT3DRMVIEWPORT view,

    LPDIRECT3DRMFRAME scene, LPDIRECT3DRMFRAME camera);

void MakeMyFrames(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,

    LPDIRECT3DRMFRAME * lplpLightFrame1,

    LPDIRECT3DRMFRAME * lplpWorld_frame);

void MakeMyLights(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,

    LPDIRECT3DRMFRAME lpLightFrame1,

    LPDIRECT3DRMLIGHT * lplpLight1, LPDIRECT3DRMLIGHT * lplpLight2);

void SetMyPositions(LPDIRECT3DRMFRAME lpScene,

    LPDIRECT3DRMFRAME lpCamera, LPDIRECT3DRMFRAME lpLightFrame1,

    LPDIRECT3DRMFRAME lpWorld_frame);

void MakeMyMesh(LPDIRECT3DRMMESHBUILDER * lplpSphere3_builder);

void MakeMyWrap(LPDIRECT3DRMMESHBUILDER sphere3_builder,

                LPDIRECT3DRMWRAP * lpWrap);

void AddMyTexture(LPDIRECT3DRMMESHBUILDER lpSphere3_builder,

                  LPDIRECT3DRMTEXTURE * lplpTex);

static void CleanUp(void);


Windowsのセットアップと初期化

このセクションでは、Helworld.cサンプル・コードにインプリメントされている、Windowsプログラムの標準的なセットアップと初期化関数について説明する。

WinMain関数

InitApp関数

メイン・ウィンドウ・プロシージャ


WinMain関数

Helworld.cのWinMain関数には、DirectDrawやDirect3Dの保持モードを利用するアプリケーションに特有なコードが少しだけ含まれている。InitApp関数とCleanUp関数はWindowsプログラムの標準的な部分であるが、Helworld.cでは、さらにいくつかの特別なタスクを実行する。Direct3Dにおいて、WinMain関数が行う最も重要な処理は、RenderLoop関数の呼び出しである。RenderLoop関数は、アニメーションのそれぞれのフレームを描画するために必要である。RenderLoop関数について詳しくは「レンダリング・ループ」を参照されたい。

/////////////////////////////////////////////////////////////////////

//

// WinMain

// アプリケーションを初期化し、メッセージ・ループを開始する。

// メッセージ・ループは、終了メッセージを受け取るまでシーンをレンダリングする。

//

/////////////////////////////////////////////////////////////////////

int PASCAL

WinMain (HINSTANCE this_inst, HINSTANCE prev_inst, LPSTR cmdline,

    int cmdshow)

{

    MSG     msg;

    HACCEL  accel = NULL;

    int     failcount = 0;  // RenderLoopが失敗した回数

    prev_inst;

    cmdline;

    // ウィンドウを作成し、レンダリングを開始するために必要なすべてのオブジェクトを

    // 初期化する。

    if (!InitApp(this_inst, cmdshow))

        return 1;

    while (!myglobs.bQuit) {

        // 処理するメッセージがなくなるまで、メッセージ・キューを監視する。

        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {

            if (!TranslateAccelerator(msg.hwnd, accel, &msg)) {

                TranslateMessage(&msg);

                DispatchMessage(&msg);

            }

        }

        // アプリケーションが最小化されておらず、終了しようともしておらず、かつ

        // D3DRMが初期化されていれば、レンダリングを開始する。

        if (!myglobs.bMinimized && !myglobs.bQuit &&

             myglobs.bInitialized) {

            // フレームのレンダリングを試みる。レンダリングが2回以上失敗したら、

            // 実行を中断する。

            if (!RenderLoop())

                ++failcount;

            if (failcount > 2) {

                CleanUp();

                break;

            }

        }

    }

    return msg.wParam;

}


InitApp関数

Helwold.cの初期化関数は、ほとんどのWindowsアプリケーションと同様に、ウィンドウ・クラスを登録し、メイン・アプリケーション・ウィンドウを作成する。その後、DirectDrawやDirect3Dを用いるアプリケーションに特有の処理を行う。

InitApp関数は、まず、現在のディスプレイのピクセル当たりのビット数を取得する。この値は、アプリケーションがレンダリングの品質を設定する際に使用される。詳しくは「レンダリング・ステートの設定」を参照されたい。

その後、どのDirect3Dドライバが有効であるかを決定し、適切なドライバを選択するために、ローカル定義のEnumDrivers関数を呼び出す。ドライバの列挙について詳しくは、「デバイス・ドライバの列挙」を参照されたい。

次に、Direct3DRMCreate関数を呼び出し、IDirect3DRMインターフェイスを作成する。このインターフェイスは、シーンやカメラ・フレームを作成したり、カメラをシーンに設置するため、IDirect3DRM::CreateFrameやIDirect3DRMFrame::SetPositionを呼び出すときに使用される。

DirectDrawClipperオブジェクトは、3Dシーンの可視部分を制御するクリッピング プレーンの管理を簡単にする。Helworld.cでは、IDirectDrawClipperインターフェイスを作成するためにDirectDrawCreateClipper関数を呼び出し、IDirectDrawClipper::SetHWndメソッドを使用して、クリッピング情報を取得するウィンドウのハンドルを設定する。

そして、ローカル定義のCreateDevAndView関数を呼び出し、Direct3Dデバイスとビューポートを作成する。この関数について詳しくは「デバイスとビューポートの作成」を参照されたい。

Direct3Dアプリケーションがサポートするすべての構造体の初期化が完了すると、3Dシーンを細かく構成することができるようになる。この処理はMyScene関数が行っている。MyScene関数について詳しくは「デバイスとビューポートの作成」を参照されたい。

最後にInitApp関数は、標準的な初期化関数と同様に、ウィンドウの表示と更新を行う。

/////////////////////////////////////////////////////////////////////

//

// InitApp

// ウィンドウを作成し、レンダリングを開始するために必要なすべてのオブジェクトを

// 初期化する。

//

/////////////////////////////////////////////////////////////////////

static BOOL

InitApp(HINSTANCE this_inst, int cmdshow)

{

    HWND win;

    HDC hdc;

    WNDCLASS wc;

    RECT rc;

    // セットアップを行い、ウィンドウ・クラスを登録する。

    wc.style = CS_HREDRAW | CS_VREDRAW;

    wc.lpfnWndProc = WindowProc;

    wc.cbClsExtra = 0;

    wc.cbWndExtra = sizeof(DWORD);

    wc.hInstance = this_inst;

    wc.hIcon = LoadIcon(this_inst, "AppIcon");

    wc.hCursor = LoadCursor(NULL, IDC_ARROW);

    wc.hbrBackground = (HBRUSH)GetStockObject(BLACK_BRUSH);

    wc.lpszMenuName = NULL;

    wc.lpszClassName = "D3DRM Example";

    if (!RegisterClass(&wc))

        return FALSE;

    // グローバル変数を初期化する。

    memset(&myglobs, 0, sizeof(myglobs));

    // ウィンドウを作成する。

    win =

        CreateWindow

        (   "D3DRM Example",            // ウィンドウ・クラス

            "Hello World (Direct3DRM)", // タイトルバー

            WS_VISIBLE | WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU |

                 WS_MINIMIZEBOX | WS_MAXIMIZEBOX,

            CW_USEDEFAULT,              // 初期x座標

            CW_USEDEFAULT,              // 初期y座標

            300,                        // 初期の幅

            300,                        // 初期の高さ

            NULL,                       // 親ウィンドウ

            NULL,                       // メニュー・ハンドル

            this_inst,                  // プログラムのインスタンス・ハンドル

            NULL                        // 作成パラメータ

        );

    if (!win)

        return FALSE;

    // 現在のディスプレイのピクセル当たりのビット数を記憶する。

    hdc = GetDC(win);

    myglobs.BPP = GetDeviceCaps(hdc, BITSPIXEL);

    ReleaseDC(win, hdc);

    // D3Dドライバを列挙し、ひとつを選択する。

    if (!EnumDrivers(win))

        return FALSE;

    // D3DRMオブジェクトとD3DRMオブジェクトを作成する。

    lpD3DRM = NULL;

    Direct3DRMCreate(&lpD3DRM);

    // マスター・シーンのフレームとカメラ・フレームを作成する。

    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, NULL, &myglobs.scene);

    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, myglobs.scene,

        &myglobs.camera);

    myglobs.camera->lpVtbl->SetPosition(myglobs.camera, myglobs.scene,

        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0));

    // DirectDrawClipperオブジェクトを作成し、ウィンドウと関連付ける。

    DirectDrawCreateClipper(0, &lpDDClipper, NULL);

    lpDDClipper->lpVtbl->SetHWnd(lpDDClipper, 0, win);

    // 選択されたD3Dドライバを用いてD3DRMデバイスを作成する。

    GetClientRect(win, &rc);

    if (!CreateDevAndView(lpDDClipper, myglobs.CurrDriver, rc.right,

            rc.bottom)) {

        return FALSE;

    }

    // レンダリングされるシーンを作成する。

    if (!MyScene(myglobs.dev, myglobs.view, myglobs.scene,

            myglobs.camera))

        return FALSE;

    myglobs.bInitialized = TRUE;  // 初期化完了

    // ウィンドウを表示する。

    ShowWindow(win, cmdshow);

    UpdateWindow(win);

    return TRUE;

}


メイン・ウィンドウ・プロシージャ

Helworld.cサンプルのメイン・ウィンドウ・プロシージャは非常に単純である。実際は、このサンプルはユーザの入力を全く受け付けないアプリケーションとなる。

ウィンドウ・プロシージャは、WM_DESTROYメッセージを受け取るとCleanUp関数を呼び出す。

またWM_ACTIVATEメッセージを受け取ったときには、ウィンドウ・プロシージャはIDirect3DRMWinDeviceを取得し、アクティブなレンダリング・ウィンドウの色を正しく表示するためにIDirect3DRMWinDevice::HandleActivateメソッドの呼び出しを行う。同様に、WM_PAINTメッセージに応答して、ウィンドウ・プロシージャはIDirect3DRMWinDevice::HandlePaintメソッドを呼び出す。

/////////////////////////////////////////////////////////////////////

//

// WindowProc

// メイン・ウィンドウのメッセージ・ハンドラ

//

/////////////////////////////////////////////////////////////////////

LONG FAR PASCAL WindowProc(HWND win, UINT msg,

    WPARAM wparam, LPARAM lparam)

{

    RECT r;

    PAINTSTRUCT ps;

    LPDIRECT3DRMWINDEVICE lpD3DRMWinDev;

    switch (msg)    {

    case WM_DESTROY:

        CleanUp();

        break;

    case WM_ACTIVATE:

        {

        // このメッセージを処理する、ウィンドウ固有のD3DRMウィンドウ・デバイスを

        // 作成する。

        LPDIRECT3DRMWINDEVICE lpD3DRMWinDev;

        if (!myglobs.dev)

            break;

        myglobs.dev->lpVtbl->QueryInterface(myglobs.dev,

            &IID_IDirect3DRMWinDevice, (void **) &lpD3DRMWinDev);

        lpD3DRMWinDev->lpVtbl->HandleActivate(lpD3DRMWinDev,

            (WORD) wparam);

        lpD3DRMWinDev->lpVtbl->Release(lpD3DRMWinDev);

        }

        break;

    case WM_PAINT:

        if (!myglobs.bInitialized || !myglobs.dev)

            return DefWindowProc(win, msg, wparam, lparam);

        // このメッセージを処理する、ウィンドウ固有のD3DRMウィンドウ・デバイスを

        // 作成する。

        if (GetUpdateRect(win, &r, FALSE)) {

            BeginPaint(win, &ps);

            myglobs.dev->lpVtbl->QueryInterface(myglobs.dev,

                &IID_IDirect3DRMWinDevice, (void **) &lpD3DRMWinDev);

            if (FAILED(lpD3DRMWinDev->lpVtbl->HandlePaint(lpD3DRMWinDev,

                ps.hdc)))

            lpD3DRMWinDev->lpVtbl->Release(lpD3DRMWinDev);

            EndPaint(win, &ps);

        }

        break;

    default:

        return DefWindowProc(win, msg, wparam, lparam);

    }

    return 0L;

}


デバイス・ドライバの列挙

Direct3Dを利用するアプリケーションは、必ず、有効なドライバを列挙し、必要な操作を行うために最適なドライバを選択しなければならない。以下のセクションでは、この処理を実行する関数について個々に説明する。

EnumDrivers関数

enumDeviceFuncコールバック関数

BPPToDDBDヘルパ関数


EnumDrivers関数

EnumDrivers関数は、InitApp関数がアプリケーションのシーンとカメラを生成する直前に呼び出される。

IDirect3D COMインターフェイスは、実際にはDirectDrawオブジェクトへのインターフェイスである。したがって、この列挙関数は、最初にDirectDrawCreate関数を呼び出してDirectDrawオブジェクトを生成する。続いてEnumDrivers関数は、QueryInterfaceメソッドを用いてIDirect3Dインターフェイスを生成する。C言語でQueryInterfaceをインプリメントする場合、第2パラメータには、（C++でのインプリメントのように）定数そのものを単に指定するのではなく、インターフェイスの識別子のアドレスを渡さなくてはならない。

ドライバの列挙は、IDirect3D::EnumDevicesメソッドによって行われる。IDirect3D::EnumDevicesメソッドは、ローカルに定義されたenumDeviceFuncコールバック関数を利用する。このコールバック関数について詳しくは、「enumDeviceFuncコールバック関数」を参照されたい。

IDirect3D::EnumDevicesはDirect3Dメソッドであり、Direct3DRMメソッドではないことに注意が必要である。保持モードのAPIには、列挙を行うメソッドは存在しない。これは、ひとつのアプリケーションで保持モードと直接モードの両方を使用する場合の良い例である。

/////////////////////////////////////////////////////////////////////

//

// EnumDrivers

// 有効なD3Dドライバを列挙し、ひとつを選択する。

//

/////////////////////////////////////////////////////////////////////

static BOOL

EnumDrivers(HWND win)

{

    LPDIRECTDRAW lpDD;

    LPDIRECT3D lpD3D;

    HRESULT rval;

    // DirectDrawオブジェクトを作成し、ドライバの列挙に用いるDirect3D

    // インターフェイスを問い合わせる。

    DirectDrawCreate(NULL, &lpDD, NULL);

    rval = lpDD->lpVtbl->QueryInterface(lpDD, &IID_IDirect3D,

        (void**) &lpD3D);

    if (rval != DD_OK) {

        lpDD->lpVtbl->Release(lpDD);

        return FALSE;

    }

    // enumDeviceFuncのドライバ選択コードを初期化するため、CurrDriverに

    // -1を設定し、ドライバを列挙する。

    myglobs.CurrDriver = -1;

    lpD3D->lpVtbl->EnumDevices(lpD3D, enumDeviceFunc,

        &myglobs.CurrDriver);

    // 少なくとも有効なドライバがひとつはあることを保証する。

    if (myglobs.NumDrivers == 0) {

        return FALSE;

    }

    lpD3D->lpVtbl->Release(lpD3D);

    lpDD->lpVtbl->Release(lpDD);

    return TRUE;

}


enumDeviceFuncコールバック関数

enumDeviceFunk関数は、D3DENUMDEVICESCALLBACK型のコールバック関数である。D3DENUMDEVICESCALLBACK型はヘッダ・ファイルD3dcaps.hに定義されている。システムはこの関数に、インストールされている各Direct3Dドライバの識別子と名前、およびハードウェアとエミュレートされたドライバの能力を通知する。

コールバック関数は、D3DDEVICEDESC構造体のdcmColorModelメンバを使用して、ハードウェアと列挙されたドライバのどちらを調べるかを決定する。このメンバにハードウェアが設定されている場合、関数はハードウェアの性能を調べる。

次に、コールバック関数は、列挙されたドライバが現在のカラー ・ビット数でレンダリングを行うことができるかどうかを判定する。不可能な場合はD3DENUMRET_OKを返し、そのドライバに関する残りの処理をスキップして、次のドライバの列挙を続ける。コールバック関数は、ローカル定義のBPPToDDBD関数を用い、通知されたカラー ・ビット数と、InitApp関数でのGetDeviceCaps関数の呼び出しによって取得された色解像度とを比較する（BPPToDDBDはbits-per-pixel to DirectDraw bit-depthの略である）。BPPToDDBD関数のコードについては、「BPPToDDBDヘルパ関数」を参照されたい。

列挙されたドライバについて簡単なテストを行った後は、D3DDEVICEDESC構造体の他のメンバを判定する。コールバック関数は、ソフトウェア エミュレーションよりもハードウェアを、モノクロ・ライトよりもRGBライトを選択する。

/////////////////////////////////////////////////////////////////////

//

// enumDeviceFunc

// 使用可能なD3Dドライバの名前とGUIDを記憶するコールバック関数。

// ドライバを選択し、*lpContextに設定する。

//

/////////////////////////////////////////////////////////////////////

static HRESULT

WINAPI enumDeviceFunc(LPGUID lpGuid, LPSTR lpDeviceDescription,

    LPSTR lpDeviceName, LPD3DDEVICEDESC lpHWDesc,

    LPD3DDEVICEDESC lpHELDesc, LPVOID lpContext)

{

    static BOOL hardware = FALSE; // 現在の開始ドライバはハードウェアである

    static BOOL mono = FALSE;     // 現在の開始ドライバはモノクロ光源である

    LPD3DDEVICEDESC lpDesc;

    int *lpStartDriver = (int *)lpContext;

    // どのデバイス記述を調べるかを決定する。

    lpDesc = lpHWDesc->dcmColorModel ? lpHWDesc : lpHELDesc;

    // 現在のディスプレイのビット深度では、このドライバがレンダリングを行えない場合、

    // ドライバをスキップして列挙を続行する。

    if (!(lpDesc->dwDeviceRenderBitDepth & BPPToDDBD(myglobs.BPP)))

        return D3DENUMRET_OK;

    // このドライバの名前とGUIDを記憶する。

    memcpy(&myglobs.DriverGUID[myglobs.NumDrivers], lpGuid,

        sizeof(GUID));

    lstrcpy(&myglobs.DriverName[myglobs.NumDrivers][0], lpDeviceName);

    // ソフトウェアよりもハードウェアを、モノクロ光源よりもRGB光源を選択する。

    if (*lpStartDriver == -1) {

        // これが最初の有効なドライバである。

        *lpStartDriver = myglobs.NumDrivers;

        hardware = lpDesc == lpHWDesc ? TRUE : FALSE;

        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;

    } else if (lpDesc == lpHWDesc && !hardware) {

        // このドライバはハードウェアであり、開始ドライバはソフトウェアである。

        *lpStartDriver = myglobs.NumDrivers;

        hardware = lpDesc == lpHWDesc ? TRUE : FALSE;

        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;

    } else if ((lpDesc == lpHWDesc && hardware ) ||

               (lpDesc == lpHELDesc && !hardware)) {

        if (lpDesc->dcmColorModel == D3DCOLOR_MONO && !mono) {

            // このドライバと開始ドライバは同じ種類である。開始ドライバはRGB光源

            // だったのに対し、このドライバはモノクロである。

            *lpStartDriver = myglobs.NumDrivers;

            hardware = lpDesc == lpHWDesc ? TRUE : FALSE;

            mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;

        }

    }

    myglobs.NumDrivers++;

    if (myglobs.NumDrivers == MAX_DRIVERS)

        return (D3DENUMRET_CANCEL);

    return (D3DENUMRET_OK);

}


BPPToDDBDヘルパ関数

enumDeviceFuncコールバック関数は、BPPToDDBDヘルパ関数を用いて、現在のデバイスがサポートする色解像度を、列挙されたドライバのカラー・ビット数と比較できる形式に変換する。enumDeviceFuncについて詳しくは、「enumDeviceFuncコールバック関数」を参照されたい。

/////////////////////////////////////////////////////////////////////

//

// BPPToDDBD

// ピクセル当たりのビット数をDirectDrawのビット深度に変換する。

//

/////////////////////////////////////////////////////////////////////

static DWORD

BPPToDDBD(int bpp)

{

    switch(bpp) {

        case 1:

            return DDBD_1;

        case 2:

            return DDBD_2;

        case 4:

            return DDBD_4;

        case 8:

            return DDBD_8;

        case 16:

            return DDBD_16;

        case 24:

            return DDBD_24;

        case 32:

            return DDBD_32;

        default:

            return 0;

    }

}


3D環境のセットアップ

このセクションでは、Helworld.cのコードのうち、3D環境を構築する部分について説明する。以下のセクションは、この処理を実行するためのふたつの関数について説明している。

デバイスとビューポートの作成

レンダリング・ステートの設定

これらの関数は、3D環境にオブジェクトやフレーム、光を配置するものではない。シーンの作成は、MyScene関数と、MyScene関数が呼び出す関数群によって実現される。3D環境にシーンを設定する方法については、「シーンの作成」を参照されたい。


デバイスとビューポートの作成

Direct3Dデバイスとビューポートは、アプリケーションの初期化の一環として作成される。InitApp関数は、DirectDrawClipperオブジェクトを生成した後、DirectDrawClipperオブジェクトと選択されたドライバ、およびクライアント矩形の寸法をパラメータとして、CreateDevAndView関数を呼び出す。

CreateDevAndView関数は、列挙プロセスで選択されたドライバを使用して、IDirect3DRM::CreateDeviceFromClipperメソッドによってDirect3DRMデバイスを作成する。このIDirect3DRMDeviceインターフェイスは、デバイスの幅および高さを取得するIDirect3DRMDevice::GetWidthとIDirect3DRMDevice::GetHeightメソッドの呼び出しで使われる。CreateDevAndView関数は、デバイスの幅や高さの情報を受け取った後、IDirect3DRM::CreateViewportメソッドを呼び出してIDirect3DRMViewportインターフェイスを取得する。

次にCreateDevAndView関数がIDirect3DRMViewport::SetBackメソッドによってビューポートの後方クリップ面を設定すると、ローカル定義のSetRenderState関数が呼び出される。SetRenderState関数については、次のセクション「レンダリング・ステートの設定」で説明する。

/////////////////////////////////////////////////////////////////////

//

// CreateDevAndView

// 指定されたD3DドライバでとサイズでD3DRMデバイスとビューポートを作成する。

//

/////////////////////////////////////////////////////////////////////

static BOOL

CreateDevAndView(LPDIRECTDRAWCLIPPER lpDDClipper, int driver,

    int width, int height)

{

    HRESULT rval;

    // 指定されたD3Dドライバを用い、このウィンドウからD3DRMデバイスを作成する。

    lpD3DRM->lpVtbl->CreateDeviceFromClipper(lpD3DRM, lpDDClipper,

        &myglobs.DriverGUID[driver], width, height, &myglobs.dev);

    // カメラ・フレームを使ってD3DRMビューポートを作成する。背景の深さを大きな数に

    // 設定する。幅と高さはだいたい調節されているので、デバイスから取得する。

    width = myglobs.dev->lpVtbl->GetWidth(myglobs.dev);

    height = myglobs.dev->lpVtbl->GetHeight(myglobs.dev);

    rval = lpD3DRM->lpVtbl->CreateViewport(lpD3DRM, myglobs.dev,

        myglobs.camera, 0, 0, width, height, &myglobs.view);

    if (rval != D3DRM_OK) {

        myglobs.dev->lpVtbl->Release(myglobs.dev);

        return FALSE;

    }

    rval = myglobs.view->lpVtbl->SetBack(myglobs.view, D3DVAL(5000.0));

    if (rval != D3DRM_OK) {

        myglobs.dev->lpVtbl->Release(myglobs.dev);

        myglobs.view->lpVtbl->Release(myglobs.view);

        return FALSE;

    }

    // レンダリングの品質、塗りつぶしモード、光源の状態、カラー・シェーディングの情報を

    // 設定する。

    if (!SetRenderState())

        return FALSE;

    return TRUE;

}


レンダリング・ステートの設定

Direct3Dはステート・マシンである。アプリケーションは、照明モジュール、レンダリング・モジュール、および変換モジュールの状態を設定し、それらを通してデータを送出する。この仕組みを意識することは、直接モードにとっては不可欠であるが、保持モードでは部分的に隠蔽されている。保持モード・アプリケーションは、SetRenderState関数によって、レンダリング・ステートを簡単に設定することができる。

まず、SetRenderState関数は、光をオン、塗りつぶしモードをソリッドにし、グロー・シェーディング・モードを用いるように指定して、IDirect3DRMDevice::SetQualityメソッドの呼び出しを行う。このとき、ディザ・モードやテクスチャの品質を変更する必要があるアプリケーションは、IDirect3DRMDevice::SetDitherメソッドやIDirect3DRMDevice::SetTextureQualityメソッドを呼び出すことができる。

この関数の残りの部分はswitch文で、現在のデバイスがサポートする色解像度の値によってパラメータを変え、IDirect3DRMDevice::SetShades、IDirect3DRM::SetDefaultTextureColors、およびIDirect3DRM::SetDefaultTextureShadesメソッドを呼び出している。

/////////////////////////////////////////////////////////////////////

//

// SetRenderState

// レンダリングの品質と陰影情報を設定する。

//

/////////////////////////////////////////////////////////////////////

BOOL

SetRenderState(void)

{

    HRESULT rval;

    // レンダリングの品質（光源のトグル、塗りつぶしモード、陰影モード）を設定する。

    rval = myglobs.dev->lpVtbl->SetQuality(myglobs.dev,

        D3DRMLIGHT_ON | D3DRMFILL_SOLID | D3DRMSHADE_GOURAUD);

    if (rval != D3DRM_OK) {

        return FALSE;

    }

    // ディザ・モードを変更したい場合、ここでSetDitherを呼び出す。

    // テクスチャの品質をD3DRMTEXTURE_NEAREST（デフォルト）以外にしたい場合、

    // ここでSetTextureQualityを呼び出す。

    // 現在のピクセル当たりのビット数に基づいて、陰影モードを設定する。

    switch (myglobs.BPP) {

        case 1:

            if (FAILED(myglobs.dev->lpVtbl->SetShades(myglobs.dev, 4)))

                goto shades_error;

            if (FAILED(lpD3DRM->lpVtbl->

                    SetDefaultTextureShades(lpD3DRM, 4)))

                goto shades_error;

            break;

        case 16:

            if (FAILED(myglobs.dev->lpVtbl->SetShades(myglobs.dev, 32)))

                goto shades_error;

            if (FAILED(lpD3DRM->lpVtbl->

                    SetDefaultTextureColors(lpD3DRM, 64)))

                goto shades_error;

            if (FAILED(lpD3DRM->lpVtbl->

                    SetDefaultTextureShades(lpD3DRM, 32)))

                goto shades_error;

            break;

        case 24:

        case 32:

            if (FAILED(myglobs.dev->lpVtbl->

                    SetShades(myglobs.dev, 256)))

                goto shades_error;

            if (FAILED(lpD3DRM->lpVtbl->

                    SetDefaultTextureColors(lpD3DRM, 64)))

                goto shades_error;

            if (FAILED(lpD3DRM->lpVtbl->

                    SetDefaultTextureShades(lpD3DRM, 256)))

                goto shades_error;

            break;

    }

    return TRUE;

shades_error:

    return FALSE;

}


レンダリング・ループ

WinMain関数は、次のフレームを描画するため、RenderLoop関数を呼び出す。RenderLoop関数は、いくつかの単純な処理を実行する。

IDirect3DRMFrame::Moveメソッドを呼び出し、階層下のすべてのフレームの回転や速度の適用を行う。

IDirect3DRMViewport::Clearメソッドを呼び出し、現在のビューポートを背景色でクリアする。

IDirect3DRMViewport::Renderメソッドを呼び出し、現在のシーンをビューポートにレンダリングする。

IDirect3DRMDevice::Updateメソッドを呼び出し、レンダリングされたイメージをスクリーンにコピーする。

/////////////////////////////////////////////////////////////////////

//

// RenderLoop

// ビューポートをクリアして次のフレームをレンダリングし、ウィンドウを更新する。

//

/////////////////////////////////////////////////////////////////////

static BOOL

RenderLoop()

{

    HRESULT rval;

    // 現在のシーンを確認する。

    rval = myglobs.scene->lpVtbl->Move(myglobs.scene, D3DVAL(1.0));

    if (rval != D3DRM_OK) {

        return FALSE;

    }

    // ビューポートをクリアする。

    rval = myglobs.view->lpVtbl->Clear(myglobs.view);

    if (rval != D3DRM_OK) {

        return FALSE;

    }

    // シーンをビューポートにレンダリングする。

    rval = myglobs.view->lpVtbl->Render(myglobs.view, myglobs.scene);

    if (rval != D3DRM_OK) {

        return FALSE;

    }

    // ウィンドウを更新する。

    rval = myglobs.dev->lpVtbl->Update(myglobs.dev);

    if (rval != D3DRM_OK) {

        return FALSE;

    }

    return TRUE;

}


シーンの作成

3D環境のセットアップ（ドライバの選択、3Dデバイスとビューポートの作成、レンダリング・ステートの設定など）が完了すると、Helworld.cは、この3D環境にオブジェクトやフレーム、光を配置するための関数群を呼び出す。

MyScene関数

MakeMyFrames 関数

MakeMyLights 関数

SetMyPositions 関数

MakeMyMesh 関数

MakeMyWrap 関数

AddMyTexture 関数


MyScene関数

Helworld.cのMyScene関数は、DirectX SDKのすべてのDirect3Dサンプルにインプリメントされている、BuildScene関数に相当する。アプリケーションのオブジェクトをテクスチャや照明効果とともに表示する処理は、すべてこの関数内で行われる。

MyScene関数は、作成されるシーンの各特性を設定する、ローカル定義の関数群を呼び出す。これらの関数を以下に示す。

MakeMyFrames関数

MakeMyLights関数

SetMyPositions関数

MakeMyMesh関数

MakeMyWrap関数

AddMyTexture関数

これらの関数がビジュアル・オブジェクトのセットアップを完了すると、MyScene関数はIDirect3DRMFrame::AddVisualメソッドを呼び出し、オブジェクトを3D環境のworldフレームに追加する。その後は作成されたインターフェイスは不要になるため、繰り返しReleaseメソッドを呼び出して、すべてのインターフェイスを解放することができる。

/////////////////////////////////////////////////////////////////////

//

// MyScene

// フレーム、光源、メッシュ、テクスチャを作成する関数を呼び出す。完了したら、すべての

// インターフェイスを解放する。

//

/////////////////////////////////////////////////////////////////////

BOOL

MyScene(LPDIRECT3DRMDEVICE dev, LPDIRECT3DRMVIEWPORT view,

    LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera)

{

    LPDIRECT3DRMFRAME lpLightframe1 = NULL;

    LPDIRECT3DRMFRAME lpWorld_frame = NULL;

    LPDIRECT3DRMLIGHT lpLight1      = NULL;

    LPDIRECT3DRMLIGHT lpLight2      = NULL;

    LPDIRECT3DRMTEXTURE lpTex       = NULL;

    LPDIRECT3DRMWRAP lpWrap         = NULL;

    LPDIRECT3DRMMESHBUILDER lpSphere3_builder = NULL;

    MakeMyFrames(lpScene, lpCamera, &lpLightframe1, &lpWorld_frame);

    MakeMyLights(lpScene, lpCamera, lpLightframe1, &lpLight1,

        &lpLight2);

    SetMyPositions(lpScene, lpCamera, lpLightframe1, lpWorld_frame);

    MakeMyMesh(&lpSphere3_builder);

    MakeMyWrap(lpSphere3_builder, &lpWrap);

    AddMyTexture(lpSphere3_builder, &lpTex);

    // マテリアルを作成する必要がある場合（たとえば、光り輝く面を作成する場合）、

    // ここでCreateMaterialとSetMaterialを呼び出す。

    // これでビジュアル・オブジェクトが作成されたので、ワールド・フレームに追加する。

    lpWorld_frame->lpVtbl->AddVisual(lpWorld_frame,

        (LPDIRECT3DRMVISUAL) lpSphere3_builder);

    lpLightframe1->lpVtbl->Release(lpLightframe1);

    lpWorld_frame->lpVtbl->Release(lpWorld_frame);

    lpSphere3_builder->lpVtbl->Release(lpSphere3_builder);

    lpLight1->lpVtbl->Release(lpLight1);

    lpLight2->lpVtbl->Release(lpLight2);

    lpTex->lpVtbl->Release(lpTex);

    lpWrap->lpVtbl->Release(lpWrap);

    return TRUE;

}


MakeMyFrames関数

MyScene関数はMakeMyFrames関数を呼び出し、Helworld.cで用いられるディレクショナル光源フレームやワールド・フレームを作成する。MakeMyFrames関数は、IDirect3DRM::CreateFrameメソッドを呼び出して、この処理を実行する。

/////////////////////////////////////////////////////////////////////

//

// MakeMyFrames

// シーンで使用するフレームを作成する。

//

/////////////////////////////////////////////////////////////////////

void MakeMyFrames(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,

    LPDIRECT3DRMFRAME * lplpLightFrame1,

    LPDIRECT3DRMFRAME * lplpWorld_frame)

{

    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, lpScene, lplpLightFrame1);

    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, lpScene, lplpWorld_frame);

}


MakeMyLights関数

MyScene関数はMakeMyLights関数を呼び出し、Helworld.cで用いられる有向光源やアンビエント・ライトを作成する。MakeMyLights関数はIDirect3DRM::CreateLightRGBとIDirect3DRMFrame::AddLightメソッドを呼び出し、方向を持った明るい光源を生成し、それをフレームに追加する。また、薄暗いアンビエント・ライトを生成し、シーン全体に追加する（アンビエント・ライトは、つねにシーン全体に関連付けられる）。

/////////////////////////////////////////////////////////////////////

//

// MakeMyLights

// シーンで使用する光源を作成する。

//

/////////////////////////////////////////////////////////////////////

void MakeMyLights(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,

    LPDIRECT3DRMFRAME lpLightFrame1,

    LPDIRECT3DRMLIGHT * lplpLight1, LPDIRECT3DRMLIGHT * lplpLight2)

{

    lpD3DRM->lpVtbl->CreateLightRGB(lpD3DRM, D3DRMLIGHT_DIRECTIONAL,

        D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9), lplpLight1);

    lpLightFrame1->lpVtbl->AddLight(lpLightFrame1, *lplpLight1);

    lpD3DRM->lpVtbl->CreateLightRGB(lpD3DRM, D3DRMLIGHT_AMBIENT,

        D3DVAL(0.1), D3DVAL(0.1), D3DVAL(0.1), lplpLight2);

    lpScene->lpVtbl->AddLight(lpScene, *lplpLight2);

}


SetMyPositions関数

MyScene関数はSetMyPositions関数を呼び出し、Helworld.cが使うフレームの位置と向きを設定する。SetMyPositions関数は、この処理をIDirect3DRMFrame::SetPositionおよびIDirect3DRMFrame::SetOrientationメソッドの呼び出しによって実行する。IDirect3DRMFrame::SetRotationメソッドは、球体が追加されるフレームに回転を設定する。

/////////////////////////////////////////////////////////////////////

//

// SetMyPositions

// 光源、カメラ、ワールド・フレームの位置と向きを設定する。

// 球体の回転を設定する。

//

/////////////////////////////////////////////////////////////////////

void SetMyPositions(LPDIRECT3DRMFRAME lpScene,

    LPDIRECT3DRMFRAME lpCamera, LPDIRECT3DRMFRAME lpLightFrame1,

    LPDIRECT3DRMFRAME lpWorld_frame)

{

    lpLightFrame1->lpVtbl->SetPosition(lpLightFrame1, lpScene,

        D3DVAL(2), D3DVAL(0.0), D3DVAL(22));

    lpCamera->lpVtbl->SetPosition(lpCamera, lpScene,

        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0));

    lpCamera->lpVtbl->SetOrientation(lpCamera, lpScene,

        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1),

        D3DVAL(0.0), D3DVAL(1), D3DVAL(0.0));

    lpWorld_frame->lpVtbl->SetPosition(lpWorld_frame, lpScene,

        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(15));

    lpWorld_frame->lpVtbl->SetOrientation(lpWorld_frame, lpScene,

        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1),

        D3DVAL(0.0), D3DVAL(1), D3DVAL(0.0));

    lpWorld_frame->lpVtbl->SetRotation(lpWorld_frame, lpScene,

        D3DVAL(0.0), D3DVAL(0.1), D3DVAL(0.0), D3DVAL(0.05));

}


MakeMyMesh関数

MyScene関数は、Helworld.cで使われる球状のメッシュをロードし、セットするためにMakeMyMesh関数を呼び出す。MekeMyMesh関数はIDirect3DRM::CreateMeshBuilderメソッドを呼び出してIDirect3DRMMeshBuilderインターフェイスを生成する。次に、IDirect3DRMMeshBuilder::Load、IDirect3DRMMeshBuilder::Scale、そしてIDirect3DRMMeshBuilder::SetColorRGBメソッドを呼び出し、Sphere3.xファイルが 示すメッシュを用意する（Sphere3.xファイルは、サンプル・コードが使用するメディアのひとつとしてDirectX SDKに収録されている）。

/////////////////////////////////////////////////////////////////////

//

// MakeMyMesh

// MeshBuilderオブジェクトを作成し、ロード、スケーリング、メッシュの色付けを行う。

//

/////////////////////////////////////////////////////////////////////

void MakeMyMesh(LPDIRECT3DRMMESHBUILDER * lplpSphere3_builder)

{

    lpD3DRM->lpVtbl->CreateMeshBuilder(lpD3DRM, lplpSphere3_builder);

    (*lplpSphere3_builder)->lpVtbl->Load(*lplpSphere3_builder,

        "sphere3.x", NULL, D3DRMLOAD_FROMFILE, NULL, NULL);

    (*lplpSphere3_builder)->lpVtbl->Scale(*lplpSphere3_builder,

        D3DVAL(2), D3DVAL(2), D3DVAL(2));

    // 予想外のテクスチャ・ブレンディングを避けるため、球体を白に設定する。

    (*lplpSphere3_builder)->lpVtbl->SetColorRGB(*lplpSphere3_builder,

        D3DVAL(1), D3DVAL(1), D3DVAL(1));

}


MakeMyWrap関数

MyScene関数はMakeMyWrap関数を呼び出してテクスチャ座標を作成し、MakeMyMesh関数がロードした球体に適用する。MakeMyWrap関数は、球体を含む方形境界線を取得するためにIDirect3DRMMeshBuilder::GetBoxメソッドを呼び出し、その方形境界線のサイズをIDirect3DRM::CreateWrapメソッドの呼び出し時に使用する。IDirect3DRMWrapメソッドは円柱のテクスチャ・ラップを作成し、IDirect3DRMWrapインターフェイスを取得する。テクスチャ座標を球体に適用するには、IDirect3DRMWrap::Applyメソッドの呼び出しを行う。

/////////////////////////////////////////////////////////////////////

//

// MakeMyWrap

// ラップを作成し、テクスチャに適用する。

//

/////////////////////////////////////////////////////////////////////

void MakeMyWrap(LPDIRECT3DRMMESHBUILDER sphere3_builder,

                LPDIRECT3DRMWRAP * lpWrap)

{

    D3DVALUE miny, maxy, height;

    D3DRMBOX box;

    sphere3_builder->lpVtbl->GetBox(sphere3_builder, &box);

    maxy = box.max.y;

    miny = box.min.y;

    height = maxy - miny;

    lpD3DRM->lpVtbl->CreateWrap

        (lpD3DRM, D3DRMWRAP_CYLINDER, NULL,

        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0),

        D3DVAL(0.0), D3DVAL(1.0), D3DVAL(0.0),

        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1.0),

        D3DVAL(0.0), D3DDivide(miny, height),

        D3DVAL(1.0), D3DDivide(-D3DVAL(1.0), height),

        lpWrap);

    (*lpWrap)->lpVtbl->Apply(*lpWrap, (LPDIRECT3DRMOBJECT)

        sphere3_builder);

}


AddMyTexture関数

MyScene関数はAddMyTexture関数を呼び出して、テクスチャのロードや球体への関連付けを行う。AddMyTexture関数は、IDirect3DRM::LoadTextureメソッドを用い、Hello.ppmという名前のビットマップをロードする。それからIDirect3DRMMeshBuilder::SetTextureを呼び出し、ビットマップを球体に貼り付ける。Hello.ppmは256×256の256色ビットマップである。

/////////////////////////////////////////////////////////////////////

//

// AddMyTexture

// ラップを作成し、テクスチャに適用する。

//

/////////////////////////////////////////////////////////////////////

void AddMyTexture(LPDIRECT3DRMMESHBUILDER lpSphere3_builder,

    LPDIRECT3DRMTEXTURE * lplpTex)

{

    lpD3DRM->lpVtbl->LoadTexture(lpD3DRM, "hello.ppm", lplpTex);

    // デフォルト（16）以外のカラー深度が必要な場合、ここで

    // IDirect3DRMTexture::SetShadesを呼び出す。

    lpSphere3_builder->lpVtbl->SetTexture(lpSphere3_builder, *lplpTex);

}


終了処理

Helworld.cは、WM_DESTROYメッセージを受け取ったとき、またはRenderLoop関数の呼び出しに何度か失敗したとき、CleanUp関数を呼び出す。

/////////////////////////////////////////////////////////////////////

//

// CleanUp

// すべてのD3DRMオブジェクトを解放し、bQuitフラグをセットする。

//

/////////////////////////////////////////////////////////////////////

void

CleanUp(void)

{

    myglobs.bInitialized = FALSE;

    myglobs.scene->lpVtbl->Release(myglobs.scene);

    myglobs.camera->lpVtbl->Release(myglobs.camera);

    myglobs.view->lpVtbl->Release(myglobs.view);

    myglobs.dev->lpVtbl->Release(myglobs.dev);

    lpD3DRM->lpVtbl->Release(lpD3DRM);

    lpDDClipper->lpVtbl->Release(lpDDClipper);

    myglobs.bQuit = TRUE;

}


直接モードの概要


直接モードについて

このセクションでは、Microsoftの低レベル3D APIである直接モードについて説明する。Direct3Dの直接モードは、ゲームやその他のハイ・パフォーマンスなマルチメディア・アプリケーションを、Microsoft Windows オペレーティング・システム上に構築する必要のある開発者にとって理想的なものである。直接モード・アプリケーションは、デバイスに依存しない方法でアクセラレータ・ハードウェアと直接通信する。Direct3Dの保持モードは、直接モードの最上部に組み立てられている。

一般に、保持モードの代わりに直接モードを利用する開発者は、ハイ・パフォーマンスなプログラミングの手法に精通しており、さらに、3Dグラフィックスについての十分な知識も持っているかもしれない。そのような開発者でも、「3Dプログラミングの基礎技術」は一読する必要がある。このセクションでは、システムを効率的に制御するために知っておかなくてはならない、Direct3Dのインプリメントの詳細について説明している。Direct3Dのアーキテクチャ全体については「Direct3Dアーキテクチャ」で取り扱っている。「Direct3Dアーキテクチャ」は、直接モードの開発者にとって不可欠なドキュメントである。直接モードの概要を知りたい場合は、「イントロダクション: Direct3Dの直接モード・オブジェクト」を参照されたい。しかし、直接モードについての最高の情報源は、おそらく、このSDKに含まれているサンプル・コードであろう。サンプル コードには、実際のアプリケーションでDirect3Dの直接モードを動作させる方法が説明されている。

このセクションは、Direct3Dの直接モード・プログラミングの初歩を説明したものではない。その情報については、「Direct3Dの直接モードのチュートリアル」を参照されたい。


イントロダクション: Direct3Dの直接モード・オブジェクト

Direct3Dの直接モードは、オブジェクトの作成やデータの設定、オブジェクト同士の結合を行うAPIから成り立っている。Direct3Dの保持モードは、直接モードの最上部に組み立てられている。システム全体の構成や、直接モードに特有の構成については、「Direct3Dアーキテクチャ」を参照されたい。

次の表は、直接モードの8つのオブジェクト型、そのコンポーネント・オブジェクト・モデル（COM）インターフェイス、およびそれぞれについての説明を示している。

オブジェクト型	COMインターフェイスと説明
インターフェイス	IDirect3Dインターフェイス
	COMインターフェイス オブジェクト
デバイス	IDirect3DDeviceインターフェイス
	ハードウェア・デバイス
テクスチャ	IDirect3DTextureインターフェイス
	イメージを含むDirectDrawサーフェス
マテリアル	IDirect3DMaterialインターフェイス
	色やテクスチャなどの、サーフェスの特性
光源	IDirect3DLightインターフェイス
	光源
ビューポート	IDirect3DViewportインターフェイス
	描画するスクリーン・リージョン
行列	IDirect3DDeviceインターフェイス
	4行4列の変換行列
実行バッファ	IDirect3DExecuteBufferインターフェイス
	頂点データのリストとレンダリング方法の指示
レンダリングは実行バッファによって行われる。このバッファには、頂点のデータとオペコードが含まれている。オペコードは、解読されると、レンダリング エンジンにイメージを生成するように指示する。実行バッファ COMオブジェクトには、ポインタと、バッファ・フォーマットについての説明だけが含まれている。このバッファは動的に確保され、グラフィック カードのメモリ内に保持することができる。

各オブジェクトは、以下の形式のひとつ以上の組み合わせで用いるのが効果的である。

COMオブジェクト。

COMオブジェクト中のデータを効率的に格納した構造体。この形式は一般的に、実際のCOMオブジェクトのコピー・データである。

ハンドル。この場合、データはハードウェア上に保持され、ハードウェアから操作することができる。

次の表は、Direct3Dの各オブジェクトが存在できる形式を示している。

	COMインターフェイス	構造体	ハンドル
デバイス	×
テクスチャ	×	×	×
マテリアル	×	×	×
光源	×	×
ビューポート	×
行列	×	×	×
実行バッファ	×	×


Direct3Dオブジェクト型

このセクションでは、Direct3Dのオブジェクト型とインターフェイスについて説明する。アプリケーションは、次の大まかな順序で、Direct3Dオブジェクトとインターフェイスを作成することができる。

IDirect3Dインターフェイス オブジェクト
Deviceオブジェクト
Textureオブジェクト
Materialオブジェクト
Lightオブジェクト
Viewportオブジェクト
Execute-bufferオブジェクト


IDirect3Dインターフェイス

IDirect3Dインターフェイスは、DirectDrawオブジェクトへのインターフェイスである。IDirect3Dインターフェイスを生成するには、次のようにIDirectDraw2::QueryInterfaceメソッドの呼び出しを行う。

lpDirectDraw->QueryInterface(

    IID_IDirect3D,  // IDirect3DインターフェイスのID

    lpD3D);         // Direct3Dオブジェクトのアドレス

IDirect3Dインターフェイスによって参照されるオブジェクトは、ビューポート、光源、マテリアル、およびデバイスのリストを含んでいる。IDirect3Dのメソッドは、他のオブジェクトを作成したり、Direct3Dデバイスを見つけるために使用することができる。


Direct3DDeviceインターフェイス
IDirect3DDeviceインターフェイス

IDirect3DDeviceインターフェイスは、DirectDrawSurfaceオブジェクトへのインターフェイスである。IDirect3DDeviceインターフェイスを生成するには、バックバッファのIDirectDrawSurface2::QueryInterfaceメソッドの呼び出しを行う。次の例では、IDirectDraw::CreateSurfaceとIDirectDrawSurface::GetAttachedSurfaceメソッドを呼び出し、バック・バッファのサーフェスを取得する。IDirectDraw2とIDirectDrawSurface2インターフェイスでこのアクションを実行するには、QueryInterfaceメソッドを用いて新しいインターフェイスへのポインタを要求する。

lpDirectDraw->CreateSurface(

    lpDDSurfDesc,   // DDSURFACEDESC構造体へのポインタ

    lpFrontBuffer,  // DIRECTDRAWSURFACE構造体へのポインタ

    pUnkOuter);     // NULL

lpFrontBuffer->GetAttachedSurface(

    &ddscaps,         // DDSCAPS構造体へのポインタ

    &lpBackBuffer);   // DIRECTDRAWSURFACE構造体へのポインタ

lpBackBuffer->QueryInterface(

    GUIDforID3DDevice,   // IDirect3DDeviceインターフェイスのID

    lpD3DDevice);        // DIRECT3DDEVICEオブジェクトへのポインタ

バックバッファのためのIDirectDrawSurface::QueryInterfaceメソッドの呼び出しで指定する最初のパラメータは、IDirect3DDeviceインターフェイスを示す、グローバル・レベルで唯一の識別子（GUID）である。このGUIDは、IDirect3D::EnumDevicesメソッドの呼び出しによって取得することができる。システムは、IDirect3D::EnumDevices関数の呼び出しの中でアプリケーションが提供するD3DENUMDEVICESCALLBACKコールバック関数を呼び出すとき、このGUIDを供給する。

Direct3Dのデバイス・オブジェクトは、インターフェイス・リストに存在し（あるいは「属し」）、自身の実行バッファとビューポートのリストを持っている。また、テクスチャやマテリアルのリストも含んでおり、それらはリスト中の次のテクスチャやマテリアルへのポインタと、前のデバイスへのポインタの両方を保持している。この階層構造について詳しくは「オブジェクトの結合性」を参照されたい。

IDirect3DDeviceインターフェイスのメソッドはハードウェア能力を通知し、ビューポート・リストの維持、マテリアルオブジェクトの操作、実行バッファ・オブジェクトの実行を行う。

行列はハンドルとしてのみ取得することができる。Direct3Dの行列を作成するにはIDirect3DDevice::CreateMatrixメソッドを呼び出し、IDirect3DDevice::SetMatrixメソッドによって行列の内容を設定することができる。行列のハンドルは実行バッファで用いられる。


IDirect3DTextureインターフェイス

テクスチャは、色付きのピクセルが矩形に並んだものである（矩形は必ずしも正方形でなくてもよいが、システムが最も効率的に動作するのは正方形の場合である）。テクスチャはテクスチャ・マッピングの面として使うこともできるが、この場合は正方形でなくてはならない。RGBカラー・モデルを用いるアプリケーションでは、8、24、32ビットのテクスチャを使用することができる。モノクロ（ランプ）・カラー・モデルでは、8ビットのテクスチャのみが使える。

IDirect3DTextureインターフェイスは、DirectDrawSurfaceオブジェクトへのインターフェイスである。IDirect3DTextureインターフェイスを生成するには、IDirectDrawSurface2::QueryInterfaceメソッドを使用してIID_IDirect3DTextureを指定する。Direct3DのテクスチャとDirectDrawのサーフェスの関係について詳しくは、「Direct3Dテクスチャ・インターフェイス」を参照されたい。

以下の例では、IDirect3DTextureインターフェイスの作成方法と、IDirect3DTexture::GetHandleおよびIDirect3DTexture::Loadメソッドを用いてテクスチャをロードする方法を示している。

lpDDS->QueryInterface(IID_IDirect3DTexture,

    lpD3DTexture);  // DIRECT3DTEXTUREオブジェクトへのポインタ

lpD3DTexture->GetHandle(

    lpD3DDevice,    // DIRECT3DDEVICEオブジェクトへのポインタ

    lphTexture);    // D3DTEXTUREHANDLEへのポインタ

lpD3DTexture->Load(

    lpD3DTexture);  // DIRECT3DTEXTUREオブジェクトへのポインタ

テクスチャ・オブジェクトはインターフェイス・リストに含まれており、デバイス・リスト中の次のテクスチャと、関連付けられたデバイスの、両方を指すポインタを持っている（この階層構造について詳しくは「オブジェクトの結合性」を参照されたい）。テクスチャ・ハンドルはマテリアルや実行バッファで用いられ、ビューポートではZバッファとして使われる。テクスチャのロードとアンロード、ハンドルの取得、パレット変化の取得には、IDirect3DTextureインターフェイスが使用できる。

このセクションでは、Direct3Dのテクスチャとその使い方を説明している。

テクスチャ・ラッピング

テクスチャ・フィルタリングとブレンディング

ミップマップ

透明化と半透明化


テクスチャ・ラッピング

それぞれの面のテクスチャ座標は、テクスチャがマッピングされる領域を定義している。アプリケーションは、テクスチャ座標を計算するためにラップを使うことができる。

テクスチャ座標の解析の方法をラスタライザに指定するために、アプリケーションは（D3DRENDERSTATETYPE列挙型から）D3DRENDERSTATE_WRAPUやD3DRENDERSTATE_WRAPVレンダリング・ステートを使用する。ラスタライザは、つねに最短距離のテクスチャ座標、すなわち直線を補完する。この直線のパスと、有効なuおよびv座標の値は、ラッピング・フラグの使い方によって異なる。前述のフラグの片方あるいは両方がセットされると、直線は、uまたはv方向のテクスチャの辺に沿って、円柱状かドーナツ状の形状を持つかのようにラップアラウンドされる。

ラッピング・フラグがセットされていないフラット・ラッピング・モードでは、uまたはv座標で指定された平面には、テクスチャが無限にタイリングされる。この場合、有効なuおよびv座標値は1.0以上である。点(0.1, 0.1)と(0.9, 0,9)を結ぶ最短の直線は、点(0.5, 0.5)を通過する。

D3DRENDERSTATE_WRAPUまたはD3DRENDERSTATE_WRAPVのいずれかがセットされた場合、テクスチャは円周1.0の終わりのない円筒形になる。1.0以上のテクスチャ座標は、ラップされていない範囲内のみ有効である。テクスチャ座標間の最短距離はラッピング・フラグによって異なる。D3DRENDERSTATE_WRAPUがセットされているときは、点(0.1, 0.1)から(0.9, 0.9)までの最短の直線は、点（0, 0.5）を通過する。

D3DRENDERSTATE_WRAPUとD3DRENDERSTATE_WRAPVフラグの両方がセットされたときは、テクスチャは円環状（ドーナツ状）になる。システムは閉じているため、1.0以上のテクスチャ座標は無効である。点(0.1, 0.1)から(0.9, 0.9)までの最短の直線は、点(0, 0)を通過する。

無効領域にあったテクスチャ座標を有効領域に収めたとしても、そのときの動作は保証されていない。

一般にアプリケーションは、テクスチャの交線が面の辺と一致しないとき、円柱状にラップするためにラッピング・フラグをセットする。ひとつの面にテクスチャの半分以上が適用される場合には、ラッピング・フラグは設定しない。

ラッピングについて詳しくは、「イントロダクション: Direct3Dの保持モード・オブジェクト」の「IDirect3DRMWrapインターフェイス」を参照されたい。


テクスチャ・フィルタリングとブレンディング

テクスチャがサーフェスにマッピングされた後は、テクスチャ要素（テクセル）が最終イメージの個々のピクセルと一致することは滅多にない。最終イメージ中のピクセルは、テクセルの大きな集合体か、ひとつのテクセルの小部分に相当する。ピクセルにテクセルの値を補完する方法を指定するには、テクスチャ・フィルタリングを利用する。

使用するテクスチャ・フィルタリングは、（D3DRENDERSTATETYPE列挙型から）D3DRENDERSTATE_TEXTUREMAGとD3DRENDERSTATE_TEXTUREMINレンダリング・ステートを用いて指定する。

D3DRENDERSTATE_TEXTUREMAPBLENDレンダリング・ステートでは、テクスチャ・ブレンディングのタイプを指定することができる。テクスチャ・ブレンディングは、テクスチャの色と適用先のサーフェスの色を混ぜ合わせる。この手段は、半透明の外観を実現する場合に効果的である。しかし、テクスチャ・ブレンディングは、予期しない色を生成する場合がある。これを防ぐためには、マテリアルの色を白くするのが最良の方法である。テクスチャ・ブレンディングのオプションは、D3DTEXTUREBLEND列挙型に示されている。

転送元と転送先の色を混合する方法を指定するには、D3DRENDERSTATE_SRCBLENDとD3DRENDERSTATE_DESTBLENDレンダリング・ステートを使用する。混色オプション（混色ファクターと呼ばれる）は、D3DBLEND列挙型に示されている。


ミップマップ

ミップマップとは連続したテクスチャを示し、各テクスチャは、同じイメージにフィルタをかけて徐々に低解像度にしたものである。ミップマップは、計算上低コストにテクスチャのレンダリング精度を高める手段である。ミップマップ中のフィルタされたイメージやレベルは、前のレベルよりも小さくなっていく。

D3DTEXTUREFILTER列挙型の適切なフィルタ・モードを指定してテクスチャ・フィルタリングを行うとき、ミップマップを使用することができる。デバイスがどのタイプのミップマップをサポートしているかを知るには、D3DPRIMCAPS構造体のdwTextureFilterCapsメンバが示しているフラグをチェックすればよい。

DirectDrawでのミップマップの作成方法について詳しくは「ミップマップ」を参照されたい。


透明化と半透明化

すでに述べたようにテクスチャを透明または半透明に表示するには、テクスチャ・ブレンディングを利用する。さらに、アルファ・チャネルや（D3DRENDERSTATETYPE列挙型の）D3DRENDERSTATE_BLENDENABLEレンダリング・ステートを用いることもできる。

透明、半透明にするためのより直接的なアプローチとして、DirectDrawがサポートするカラー・キーを利用する方法がある。カラー・キーとは、ブロック転送やオーバーレイ操作における、転送元あるいは転送先部分の色または色の範囲である。これらの色は、つねに上書きされるようにも、決して変更されないようにも指定することができる。

DirectDrawのカラー・キー・サポートについて詳しくは「カラー・キーイング」を参照されたい。


IDirect3DMaterialインターフェイス

IDirect3DMaterialインターフェイスを生成するには、IDirect3D::CreateMaterialメソッドの呼び出しを行う。次の例は、IDirect3DMaterialインターフェイスの生成方法を示している。そして、IDirect3DMaterial::SetMaterialやIDirect3DMaterial::GetHandleメソッドを用い、マテリアルの設定とハンドルの取得を行っている。

lpDirect3D->CreateMaterial(

    lplpDirect3DMaterial,  // 新しいマテリアルへのポインタ

    pUnkOuter);            // NULL

lpDirect3DMaterial->SetMaterial(

    lpD3DMat);             // D3DMATERIAL構造体へのポインタ

lpDirect3DMaterial->GetHandle(

    lpD3DDevice,           // DIRECT3DDEVICE構造体へのポインタ

    lpD3DMat);             // D3DMATERIAL構造体へのポインタ

マテリアルオブジェクトはインターフェイス・リストに含まれており、デバイス・リスト中の次のマテリアルへのポインタと、関連付けられたデバイスへのポインタの両方を持っている（この階層構造について詳しくは「オブジェクトの結合性」を参照されたい）。マテリアルには色が含まれており、テクスチャ・ハンドルを持っている場合もある。マテリアルハンドルは、実行バッファの中で使われたり、ビューポートの背景を設定するために使用される。IDirect3DMaterialインターフェイスを用いると、マテリアルの取得や設定、ハンドルの取得、色の保存を行うことができる。


IDirect3DLightインターフェイス

IDirect3Dlightインターフェイスを作成するには、IDirect3D::CreateLightメソッドを呼び出す。次の例はIDirect3Dlightインターフェイスの作成方法を示している。また、作成後にはIDirect3DLight::SetLightメソッドを呼び出し、光源を設定する。

lpDirect3D->CreateLight(

    lplpDirect3DLight,  // 新しい光源へのポインタ

    pUnkOuter);         // NULL

lpDirect3DLight->SetLight(

    lpLight);    // D3DLIGHT構造体へのポインタ

光源オブジェクトはインターフェイス・リストとビューポート・リストに含まれている。IDirect3Dlightインターフェイスを使用して、光源の取得や設定を行うことができる。


IDirect3DViewportインターフェイス

IDirect3DViewportインターフェイスは、IDirect3D::CreateViewportメソッドを呼び出して生成する。次の例は、IDirect3DViewportインターフェイスの作成方法を示している。また、この例は、IDirect3DDevice::AddViewportメソッドによるビューポートの追加のしかたや、IDirect3DViewport::SetViewport、IDirect3DViewport::SetBackground、IDirect3DViewport::AddLightメソッドを用いてビューポートをセットアップする方法も説明している。

lpDirect3D->CreateViewport(

    lplpDirect3DViewport,  // 新しいビューポートへのポインタ

    pUnkOuter);            // NULL

lpD3DDevice->AddViewport(

    lpD3DViewport)         // ビューポートをデバイスにアタッチする

lpD3DViewport->SetViewport(

    lpData);               // スクリーン上のビューポートの位置を設定する

                           // D3DVIEWPORT構造体へのポインタ

lpD3DViewport->SetBackground(

    lphMat);               // 背景のD3DMATERIALHANDLE構造体へのポインタ

lpD3DViewport->AddLight(

    lpD3DLight);           // 光源オブジェクトへのポインタ

ビューポートはインターフェイス・リストとデバイス・リストに含まれている。オブジェクトは、スクリーン・データとともに光源リストを保持しており、背景のマテリアルハンドルやテクスチャ・ハンドルを持つ場合もある。IDirect3DViewportインターフェイスを使用して、背景やビューポートの取得と設定、光源の追加と削除、頂点の変換を行うことができる。


IDirect3DExecuteBufferインターフェイス

実行バッファには頂点リストが含まれており、その後に命令ストリームが続く。命令ストリームは、オペレーション・コード（オペコード）と、このオペコードが操作するデータから構成されている。実行バッファの説明は「実行バッファ」を参照されたい。

IDirect3DExecuteBufferインターフェイスを作成するには、IDirect3DDevice::CreateExecuteBufferメソッドの呼び出しを行う。

lpD3DDevice->CreateExecuteBuffer(

    lpDesc,       // DIRECT3DEXECUTEBUFFERDESC構造体へのポインタ

    lplpDirect3DExecuteBuffer,  // Direct3DExecuteBufferオブジェクトへの

                                // ポインタを受け取るためへのポインタ

    pUnkOuter);   // NULL

実行バッファはデバイス・リストに含まれている。実際のバッファ領域を確保するには、IDirect3DDevice::CreateExecuteBufferメソッドを使用する。このバッファ領域は、ハードウェア・デバイス上に存在することもある。

実行バッファは、IDirect3DExecuteBuffer::Lock、IDirect3DExecuteBuffer::Unlock、IDirect3DExecuteBuffer::SetExecuteDataメソッドを使用することによって、頂点とオペコードを含むふたつの連続した配列で埋め尽くされる。

lpD3DExBuf->Lock(

    lpDesc);.      // DIRECT3DEXECUTEBUFFERDESC構造体へのポインタ

//  .

//  .  Store contents through the supplied address

//  .

lpD3DExBuf->Unlock();

lpD3DExBuf->SetExecuteData(

    lpData);       // D3DEXECUTEDATA構造体へのポインタ

この例の最後にはIDirect3DExecuteBuffer::SetExecuteDataメソッドの呼び出しを行っている。このメソッドは、Direct3Dにバッファ内のふたつの配列の位置を渡す。配列の位置は、IDirect3DExecuteBuffer::Lockメソッドが返すアドレスからの相対位置で指定する。

実行データの取得や設定、ロック、アンロック、最適化、および実行バッファの検証を行うには、IDirect3DExecuteBufferインターフェイスを使用する。


オブジェクトの結合性

次の図は、ただひとつのデバイスがどのように実行バッファやビューポートを所有しているか、ただひとつのビューポートがどのように各光源を保持しているかを示したものである。

マテリアルやテクスチャのオブジェクトは、ひとつ以上のデバイスに関連付けることができる。次の図に示される各ノードは、リストの先頭へのポインタを保持している（ただし図の中にはポインタは表示されていない）。どのテクスチャのノードからも、どのマテリアルのノードからも、そのオブジェクトの先頭や関連したデバイスへのポインタを取得することができる。

インターフェイスやデバイス、テクスチャのオブジェクトを作成するにはQueryInterfaceメソッドを呼び出す。マテリアル、光源、ビューポートのオブジェクトは、IDirect3Dインターフェイスのメソッドを呼び出して作成することができる。実行バッファや行列は、IDirect3DDeviceインターフェイスによって作成される。インターフェイス・オブジェクト（Direct3D object）には、作成されたすべてのデバイスやビューポート、光源、マテリアルのオブジェクトのリストが保持されるが、実行バッファやテクスチャのオブジェクトは含まれない。


シーンの管理

すべての直接モード・アプリケーションは、レンダリングを実行する前にIDirect3DDevice::BeginSceneメソッドを呼び出さなくてはならない。また、レンダリングが完了したときには、IDirect3DDevice::EndSceneメソッドを呼び出す必要がある。アプリケーションは、今後の3Dハードウェア上で動作させるために、これらのメソッドを正しく使用しなくてはならない。

シーンは頂点と描画プリミティブ（三角形、直線、点）の集合体である。頂点は、動画やアニメーションのひとつのフレームを描画するために使用される。IDirect3DDevice::BeginSceneメソッドはシーンの始まりを（したがってフレームの開始も）示し、IDirect3DDevice::EndSceneメソッドはシーンとフレームの終了を通知する。ひとつのフレームの描画に使われる実行バッファ命令は、1度のIDirect3DDevice::BeginSceneとIDirect3DDevice::EndSceneの呼び出しの間にまとめなくてはならない。

このセクションは以下のトピックについて説明している。

陰面消去

2Dと3Dの相互作用

シーン管理プロシージャ


陰面消去

3Dアクセラレータの派生クラスでは、従来のZバッファを用いた陰面消去は行われない。これらのアクセラレータを正しくサポートするためには、IDirect3DDevice::BeginSceneとIDirect3DDevice::EndSceneメソッドを使用する必要がある。内部タイリングやポリゴン・ソートなど、陰面消去のための数多くの機能をインプリメントしたアクセラレータもあるが、それらには共通の特徴がある。それは、陰面消去のためには、ひとつのフレームのジオメトリ・データベース全体のコピーを処理しなくてはならないということだ。

ひとつのフレームのジオメトリ変換をすべて処理するために、新しいアクセラレータではシーン・キャプチャをサポートする必要がある。つまり新しいアクセラレータは、後の処理のために、実行バッファを介して渡されるジオメトリ情報を記憶しなくてはならない。隠面に対する処理が正常に行われることを保証するため、ひとつのフレームに出されるすべての描画命令は、1回のIDirect3DDevice::BeginSceneとIDirect3DDevice::EndScene呼び出しの間にまとめなくてはならない。ひとつのフレームの構成中に、複数回のIDirect3DDevice::BeginSceneとIDirect3DDevice::EndSceneメソッドが呼び出されると、異なるシーンのコンテキストで実行された三角形へ、隠れたオブジェクトが与える作用をアクセラレータが正しく解決することができなくなる。

アプリケーションは、たとえ別のコンテキストの三角形に影響を与える隠しサーフェスがない場合でも、複数回に渡って IDirect3DDevice::BeginSceneやIDirect3DDevice::EndSceneメソッドを呼び出してはいけない。アクセラレータによっては、陰面消去のためだけでなく、高精度なレンダリング効果を実現するためにシーン・キャプチャを利用する場合がある。たとえば、シーン・キャプチャをサポートしたアクセラレータには、影や半透明オブジェクトをレンダリングできるものがあるかもしれない。このような効果は、フレームのジオメトリ・データベース全体を処理するアクセラレータの能力に依存しており、複数のIDirect3DDevice::BeginSceneとIDirect3DDevice::EndSceneコンテキストがある場合には動作しない。


2Dと3Dの相互作用

シーン・キャプチャを実行するアクセラレータでは、IDirect3DDevice::BeginSceneからIDirect3DDevice::EndSceneメソッドまでの3Dの描画操作の間に、2Dの描画操作（ブロック転送や直接書き込みなど）を含めることができない場合がある。この制限を持つアクセラレータは、DirectDrawの能力ビットDDCAPS2_NO2DDURING3DSCENEによって示される。アプリケーションはこのビットをチェックし、DirectDrawのブロック転送やロック、GetDCメソッドの呼び出しは、IDirect3DDevice::EndSceneの呼び出しが行われるまで待たなくてはならない。


シーン管理プロシージャ

以下のリストに説明するステップを踏むことによって、アプリケーションは、すべての3Dアクセラレータ（シーンのキャプチャを実行するものも含む）で正確にレンダリングを行うことができる。これらのステップは、前述したセクションで概説されている情報を要約している。

1	ひとつのフレームの描画プリミティブを含む実行バッファを実行する前に、1度IDirect3DDevice::BeginSceneメソッドを呼び出し、実行後には最後にIDirect3DDevice::EndSceneメソッドを呼び出す。

2	DirectDrawの能力を示すビットDDCAPS2_NO2DDURING3DSCENEをチェックする。このビットがセットされていたら、IDirect3DDevice::BeginSceneの呼び出しからIDirect3DDevice::EndSceneの呼び出しまでの間に、レンダリング・サーフェスに対してDirectDrawのブロック転送やロック、GetDCメソッドを使用しないようにする。これらの2D操作は、IDirect3DDevice::EndSceneを呼び出した後に実行することができる。

3	IDirect3DDevice::Executeメソッドが制御を戻しても、ひとつの実行バッファに含まれるレンダリング・プリミティブのすべてがターゲット・サーフェスにレンダリングされたと見なしてはいけない。シーン・キャプチャ・カードは、シーンが完了するまで（つまり、IDirect3DDevice::EndSceneメソッドが呼び出されるまで）レンダリングを延期する。


Direct3Dの直接モードのチュートリアル

WindowsベースのDirect3Dの直接モード・アプリケーションを作成するには、DirectDrawとDirect3Dオブジェクトを生成し、レンダリング・ステートを設定し、実行バッファを設定し、そのバッファを実行する。このセクションは、単純な直接モードのアプリケーションのインプリメントについて、順を追って説明したチュートリアルである。このチュートリアルのサンプル・コードは、SDKの一部である。

このSDKが提供するサンプルの中のD3dmain.cppファイルは、他のすべての直接モードのサンプルの基本として用いられている。D3dmain.cppには、Windowsフレームワークの標準の初期化処理、メッセージ・ループの設定、およびメッセージ処理のためのウィンドウ・プロシージャの作成が含まれているが、さらに、Direct3Dの直接モード・アプリケーションに特有な処理もいくつか行っている。以下のセクションでは、この処理について説明する。

Step 1: 初期化の開始

Step 2: DirectDrawおよびDirect3Dオブジェクトの作成

Step 3: デバイス作成コールバック関数のセットアップ

Step 4: ビューポートの初期化

Step 5: 直接モードのレンダリング・ステートの設定

Step 6: 初期化の完了

Step 7: レンダリング・ループの実行

Step 8: 終了処理

このSDKの中の直接モードのサンプルには、ここには記載されていないコードがいくつか含まれている。特にこのSDKには、D3Dapp関数として呼び出されるヘルパ関数のコレクションが含まれており、独自の直接モードのアプリケーションを記述する場合に役立つであろう。このドキュメントではヘルパ関数を頻繁に参照しているが、そのすべてについてカバーしているわけではない。ヘルパ関数は 、ソース・ファイル D3dapp.c、Ddcalls.c 、D3dcalls.c 、Texture.c および  Misc.c でインプリメントされている。ソース・ファイル Stats.cpp は、フレーム・レートやスクリーン・モードの情報をスクリーンに送る。

D3main.cpp を用いるすべてのサンプルは、その動作をカスタマイズできるようにするために、以下の関数をインプリメントしなくてはならない。

InitScene

InitView

RenderScene

ReleaseView

ReleaseScene

OverrideDefaults

さらに、サンプルはSetMouseCallback関数やSetKeyboardCallback関数を呼び出し、マウスやキーボードからの入力を取得する。


Step 1: 初期化の開始

D3dmain.cppのWinMain関数が行う最初のタスクは、ローカルに定義されたAppInit関数を呼び出し、アプリケーション・ウィンドウを作成し、レンダリングの開始に必要なすべてのオブジェクトを初期化する。また、WinMain関数はD3dmain.cppにメッセージ・ポンプをインプリメントし、ローカル定義のRenderLoop関数とCleanUpAndPostQuit関数を呼び出す。AppInit関数は、処理を補足する他の関数群を呼び出し、これらの関数は、さらに別の関数群の呼び出しを行う。このチュートリアルのほとんどは、初期化関数のグループについて取り扱っている。

Windowsアプリケーションの標準的な初期化処理を実行し、グローバル変数をデフォルトの設定で初期化した後、AppInit関数はInitScene関数を呼び出す。3Dmain.cppを使う各サンプルは、それぞれInitScene関数をインプリメントしなくてはならない。Oct1.cのような単純なサンプル・アプリケーションでは、InitScene関数は何もせず、TRUEを返すだけである。Tunnel.cなど、もっと複雑なサンプルが使うInitScene関数は、メモリを確保し、点を生成し、グローバル変数を取得する。

最後にAppInit関数は、D3dmain.cppにインプリメントされているCreateD3DApp関数を呼び出す。CreateD3DApp関数によって呼び出される関数群は、初期化処理の多くの部分を受け持っている。


Step 2: DirectDrawおよびDirect3Dオブジェクトの作成

D3dmain.cppのCreateD3DApp関数は、レンダリングが開始される前にDirectDrawとDirect3Dオブジェクトを初期化する役割を持つ。CreateD3DApp関数が呼び出すローカル関数のうち重要なものは、D3DAppCreateFromHWND、D3DAppGetRenderState、OverrideDefaults、D3DAppSetRenderState、ReleaseView、InitViewの各関数である。D3Dappで始まる名前の関数は、D3Dappシリーズのヘルパ関数の一部である。

WinMain関数に渡されるコマンド・ライン・オプションと同じものが、CreateD3DApp関数にも渡される。有効なオプションは、-systemmemoryと-emulationである。-systemmemoryオプションは、デバッグ専用に用いられる。-emulationオプションを指定すると、アプリケーションはDirectDrawやDirect3Dのハードウェア・アクセラレータを使用しない。

CreateD3DApp関数は、テクスチャを生成するためにD3DAppAddTexture関数を呼び出す。すると、D3DAppAddTexture関数は、ソース・テクスチャのサーフェスとオブジェクトをシステム・メモリ内に生成する。ハードウェアがビデオ・メモリを持っている場合は、初期状態では空のテクスチャ・サーフェスをビデオ・メモリ内に生成する。ソース・テクスチャは、転送先のテクスチャ・サーフェスにロードされた後で破棄される。この2段階のプロセスによって、デバイスは、ビデオ・メモリに転送されるときにテクスチャ・マップを圧縮または再フォーマットすることができる。サンプル・コードでは、IDirect3DTextureインターフェイスを取得するためにIDirectDrawSurface::QueryInterfaceメソッドを呼び出し、IDirect3DTexture::Loadメソッドを用いてテクスチャをロードする。テクスチャ・ハンドルのリストを作成するには、IDirect3DTexture::GetHandleメソッドを使用する。

テクスチャのリストを作成した後、CreateD3DApp関数は、レンダリングの開始に必要なDirectDrawとDirect3Dオブジェクトを生成する。サンプル・コードでは、D3DAppCreateFromHWNDヘルパ関数を使用している。D3DAppCreateFromHWND関数は、ソース・ファイルD3dapp.c、D3dcalls.c、Texture.c、Ddcalls.cにインプリメントされている関数群を利用する。

まず、D3DAppCreateFromHWND関数は、DirectDrawEnumerateとDirectDrawCreate関数を用いてDirectDrawオブジェクトの生成と初期化を行う。ここでグローバル変数の値を設定し、IDirectDraw::EnumDisplayModesメソッドを呼び出してディスプレイ・モードを列挙する。

新しいアプリケーションの多くは、IDirectDrawインターフェイスの代わりにIDirectDraw2インターフェイスを利用する。このドキュメントのサンプル・コードは、IDirectDrawインターフェイスを使用している。リファレンスのセクションでIDirectDrawメソッドを調べるときは、新しいバージョンのメソッドを参照されたい。つまり、IDirectDraw::EnumDisplayModesの代わりにIDirectDraw2::EnumDisplayModesを調べればよい。

次に、D3DAppCreateFromHWND関数はDirect3Dオブジェクトを生成し、Direct3Dデバイス・ドライバを列挙する。Direct3Dオブジェクトの生成には、IID_IDirect3Dインターフェイスの識別子を渡してIDirectDraw::QueryInterfaceメソッドを呼び出す。デバイス・ドライバを列挙するには、IDirect3D::EnumDevicesメソッドを使用する。

しかし、IDirect3D::EnumDevicesの呼び出しは、Direct3Dデバイス・ドライバを見つけるための最も簡単で最良な方法であるとは言えない。直接モードのアプリケーションのほとんどは、列挙ルーチンのセットアップの代わりにIDirect3D::FindDeviceメソッドを利用する。このメソッドは、望ましいデバイスの能力を指定するだけで、システムが使用可能なドライバを調べ、最初にマッチしたデバイスの識別子（GUID）を返す。システムはつねに最初にハードウェアをチェックし、ハードウェアとソフトウェアの両方のデバイスが要求された能力をサポートする場合は、ハードウェア・デバイスのGUIDを返す。

デバイス・ドライバとディスプレイ・モード（フルスクリーンかウィンドウか）を選択した後、D3DAppCreateFromHWND関数は、そのディスプレイ・モードのためのフロント・バッファとバック・バッファを作成する。アプリケーションがウィンドウで動作するかフルスクリーンで動作するか、また、ビデオ・メモリとシステム・メモリのどちらを使用するかによって、コードの内容は異なってくる。ウィンドウで実行されるアプリケーションでは、IDirectDraw::CreateClipperメソッドを呼び出してDirectDrawClipperオブジェクトを生成し、IDirectDrawClipper::SetHWndメソッドによってオブジェクトをウィンドウに関連付け、IDirectDrawSurface::SetClipperメソッドによってフロント・バッファにアタッチする。

次にD3DAppCreateFromHWND関数はフロント・バッファにパレットが設定されているかどうかをチェックする。設定されている場合には、そのパレットを初期化する。最初にIDirectDraw::CreatePaletteメソッドを使用してパレットを作成し、次にIDirectDrawSurface::SetPaletteメソッドを呼び出して、それをフロント・サーフェスとバック・サーフェスのパレットとして設定する。

ここでコードはIDirectDraw::CreateSurfaceメソッドの呼び出しを行い、Zバッファを作成する。IDirectDrawSurface::AddAttachedSurfaceによってZバッファをバック・バッファにアタッチし、Zバッファがビデオ・メモリにあるかどうかを判定するためにIDirectDrawSurface::GetSurfaceDescメソッドを使用する。

次にIDirect3DDeviceインターフェイスを生成し、これを用いてテクスチャ・フォーマットを列挙する。サンプルは、インターフェイスを生成するためにIDirectDrawSurface::QueryInterfaceメソッドを呼び出し、IDirect3DDevice::EnumTextureFormatsメソッドによってテクスチャ・フォーマットを列挙している。テクスチャの列挙が完了すると、CreateD3DApp が同じ関数群を呼び出し、テクスチャのロードと、テクスチャ・ハンドルのリストの作成を行う。

デバイスの色解像度と、適切なディスプレイ・モードをフィルタするトータル・ビデオ・メモリを使用した後は、デバイス作成コールバック関数をセットアップする。このコールバック関数については「Step 3: デバイス作成コールバック関数のセットアップ」を参照されたい。

デバイス作成コールバック関数のセットアップが完了すると、D3DAppCreateFromHWND関数はアプリケーションのレンダリング・ステートを設定する。レンダリング・ステートについては「Step 5: 直接モードのレンダリング・ステートの設定」で説明している。

必要なDirect3Dオブジェクトを生成し、レンダリング・ステートのセットアップを行うと、だいたいの処理が終わったことになる。D3DAppCreateFromHWND関数は、フロント・バッファとバック・バッファの矩形をクライアント領域全体に設定するローカル関数を呼び出し、アプリケーションが初期化され、レンダリングが実行できることを示すフラグを設定して、TRUEを返す。

D3DAppCreateFromHWND関数の最後は、エラー処理を行う部分である。呼び出しに失敗したときには、エラー処理コードはエラー・ラベルにジャンプして終了する。この部分では、デバイスを破棄するコールバック関数を呼び出す。アプリケーションがフルスクリーン・モードで実行されている場合は、ディスプレイ・モードと協調レベルをリセットする。そして、生成されたすべてのDirect3DオブジェクトとDirectDrawオブジェクトを解放し、FALSEを返す。


Step 3: デバイス作成コールバック関数のセットアップ

D3DAppCreateFromHWND関数の第3パラメータは、AfterDeviceCreated関数としてD3dmain.cppにインプリメントされているコールバック関数のアドレスである。AfterDeviceCreated関数はDirect3Dビューポートを作成し、それをD3DAppCreateFromHWND関数に返す。

最初にIDirect3D::CreateViewportメソッドを呼び出してビューポートを作成し、IDirect3DDevice::AddViewportによっていちばん新しいDirect3Dデバイスにビューポートを追加する。D3DVIEWPORT構造体の中のビューポートのサイズを初期化した後、ビューポートをそのサイズに設定するために、IDirect3DViewport::SetViewportメソッドの呼び出しを行う。

次に、AfterDeviceCreated関数はInitView関数を呼び出す。InitView関数は、D3dmain.cppが最初の方で呼び出すInitScene関数と同様に、D3dmain.cppを使用する各サンプルでインプリメントしなくてはならない。InitView関数のインプリメントの例は「Step 4: ビューポートの初期化」で説明されている。

InitView関数の呼び出しといくつかのメニュー・アイテムの変更の後、CleanUpAndPostQuit関数を呼び出してAfterDeviceCreated関数は終了する。CleanUpAndPostQuit関数については「Step 8: 終了処理」を参照されたい。


Step 4: ビューポートの初期化

D3dmain.cppを使用するサンプル・コードは、それぞれ、ビューポートのセットアップと実行バッファの作成を行うInitView関数をインプリメントしなくてはならない。このセクションでは、Oct1.cサンプルにおけるInitView関数のインプリメントについて説明する。

まずInitView関数は、マテリアルやマテリアルのハンドル（マテリアル・ハンドル）、テクスチャ・ハンドルをいくつか作成し初期化する。マテリアルを作成するにはIDirect3D::CreateMaterialメソッドを使用する。また、IDirect3DMaterial::SetMaterialメソッドを呼び出し、初期化したばかりのマテリアルのデータを設定する。このマテリアルをビューポートの背景に設定するには、IDirect3DMaterial::GetHandleとIDirect3DViewport::SetBackgroundメソッドを用いる。

これでInitView関数は、ビューポートのビュー、ワールド、マテリアルの投影の設定を行った。マテリアルを作成し、設定するために、InitView関数はMAKE_MATRIXマクロを使用する。MAKE_MATRIXマクロはD3dmacs.hで次のように定義されている。

#define MAKE_MATRIX(lpDev, handle, data) \

    if (lpDev->lpVtbl->CreateMatrix(lpDev, &handle) != D3D_OK) \

        return FALSE; \

    if (lpDev->lpVtbl->SetMatrix(lpDev, handle, &data) != D3D_OK) \

        return FALSE

見てわかる通りMAKE_MATRIXは、IDirect3DDevice::CreateMatrixとIDirect3DDevice::SetMatrixメソッドをシングル・ステップで呼び出すだけの便利なマクロである。

次にInitView関数は、実行バッファの作成とセットアップを行う。D3DEXECUTEBUFFERDESC構造体のメンバを初期化してから、IDirect3DDevice::CreateExecuteBufferメソッドを呼び出して実行バッファを作成し、内容を設定するためIDirect3DExecuteBuffer::Lockメソッドによってバッファをロックする。

InitView関数は、D3dmacs.hで定義されているOP_STATE_TRANSFORMとSTATE_DATAマクロを使用して実行バッファを設定する。これらのマクロについては「Step 5: 直接モードのレンダリング・ステートの設定」を参照されたい。そのセクションには、実行バッファの操作について、より多くの情報が記載されている。

実行バッファがセットアップされると、InitView関数はIDirect3DExecuteBuffer::Unlockメソッドを呼び出してバッファをアンロックし、IDirect3DExecuteBuffer::SetExecuteDataメソッドによってバッファにデータを設定する。IDirect3DDevice::BeginScene、IDirect3DDevice::Execute、IDirect3DDevice::EndSceneメソッドを用いて実行バッファを実行する。その後はこの実行バッファを使用することはないので、IDirect3DExecuteBuffer::Release関数を呼び出すことができる。

ここでInitView関数は、ふたつのマテリアルをセットアップする。これには、以前にマテリアルを設定したときと同じ手順を用いる。マテリアルの作成にはIDirect3D::CreateMaterialメソッドを使用し、マテリアルのデータを設定するには、（D3DMATERIAL構造体のメンバを設定した後に）IDirect3DMaterial::SetMaterialメソッドを呼び出す。さらにIDirect3DMaterial::GetHandleメソッドを用いてマテリアルへのハンドルを取得する。このハンドルは、新しいマテリアルに光を当てるため、D3DLIGHTSTATETYPE列挙型のD3DLIGHTSTATE_MATERIALメンバとともに後で使用される。

そしてInitView関数は、頂点のセットアップを行う。浮動小数点の値をD3DVERTEX構造体のD3DVALUEメンバに変換するため、コードはD3DVALPマクロを利用している。また、各頂点の法線ベクトルのx座標を正規化するため、D3DRMVectorNormalize関数も使用する。

頂点のセットアップが完了すると、InitView関数は別の実行バッファを作成し、頂点をコピーして実行データを設定する。しかし、この時点では実行バッファは実行されない。実行バッファの実行は、レンダリング・ループの中で行われる。

最後に、InitView関数はOct1.cの光源をセットアップする。D3DLIGHT構造体を初期化した後、IDirect3D::CreateLight、IDirect3DLight::SetLight、およびIDirect3DViewport::AddLightメソッドを呼び出してビューポートに光源を追加する。


Step 5: 直接モードのレンダリング・ステートの設定

D3dcalls.cソース・ファイルにあるD3DAppISetRenderState関数は、現在のビューポートのレンダリング・ステートや光の状態を設定する実行バッファの作成と実行を行う。D3DAppCreateFromHWND関数は、D3dapp.cからD3DAppISetRenderState関数を呼び出す。一般的にサンプル・コードは、設定やリセットが必要になるたびにD3DAppISetRenderState関数の呼び出しを行う。このセクションでは、D3DAppISetRenderState関数を（エラー・チェックのコードを除いて）紹介する。

D3DAppISetRenderState関数は、D3DEXECUTEBUFFERDESC構造体やD3DEXECUTEDATA構造体を含むいくつかのローカル変数を設定した後、IDirect3DDevice::CreateExecuteBufferメソッドを使用して実行バッファを作成する。実行バッファが作成されると、その中身を設定するためにIDirect3DExecuteBuffer::Lockメソッドを呼び出してバッファをロックする。

BOOL D3DAppISetRenderState()

{

D3DEXECUTEBUFFERDESC debDesc;

D3DEXECUTEDATA d3dExData;

LPDIRECT3DEXECUTEBUFFER lpD3DExCmdBuf = NULL;

LPVOID lpBuffer, lpInsStart;

size_t size;

// 要求されたサイズの実行バッファを作成し、内容を設定できるようにロックする。

size = 0;

size += sizeof(D3DINSTRUCTION) * 3;

size += sizeof(D3DSTATE) * 17;

memset(&debDesc, 0, sizeof(D3DEXECUTEBUFFERDESC));

debDesc.dwSize = sizeof(D3DEXECUTEBUFFERDESC);

debDesc.dwFlags = D3DDEB_BUFSIZE;

debDesc.dwBufferSize = size;

LastError = d3dappi.lpD3DDevice->lpVtbl->CreateExecuteBuffer(

    d3dappi.lpD3DDevice, &debDesc, &lpD3DExCmdBuf, NULL);

LastError = lpD3DExCmdBuf->lpVtbl->Lock(lpD3DExCmdBuf, &debDesc);

memset(debDesc.lpData, 0, size);

lpInsStart = debDesc.lpData;

lpBuffer = lpInsStart;

IDirect3DDevice::CreateExecuteBufferメソッドの中のd3dappi.lpD3DDeviceパラメータは、Direct3DDeviceオブジェクトへのポインタである。debDesc変数（D3DEXECUTEBUFFERDESC構造体）のlpDataメンバは、実行バッファ内の実際のデータへのポインタである。

さて、D3DAppISetRenderState関数は、レンダリング・ステートの設定を行う。処理を簡単にするために、D3DAppISetRenderState関数はOP_STATE_DATAマクロを使用している。このマクロはPUTD3DINSTRUCTIONマクロを呼び出す。これらふたつのマクロは、このSDKのD3dmacs.hヘッダ・ファイルで以下のように定義されている。

#define PUTD3DINSTRUCTION(op, sz, cnt, ptr) \

    ((LPD3DINSTRUCTION) ptr)->bOpcode = op; \

    ((LPD3DINSTRUCTION) ptr)->bSize = sz; \

    ((LPD3DINSTRUCTION) ptr)->wCount = cnt; \

    ptr = (void *)(((LPD3DINSTRUCTION) ptr) + 1)

#define OP_STATE_RENDER(cnt, ptr) \

    PUTD3DINSTRUCTION(D3DOP_STATERENDER, sizeof(D3DSTATE), cnt, ptr)

PUTD3DINSTRUCTIONマクロの引数はD3DINSTRUCTION構造体のメンバより少ないことに注意が必要である。OP_STATE_RENDERマクロのPUTD3DINSTRUCTIONの第1パラメータD3DOP_STATERENDERは、D3DOPCODE列挙型中のオペコードのひとつである。2番目のパラメータはD3DRENDERSTATETYPE構造体へのポインタとD3DSTATE構造体のサイズを示している。

やはりD3dmacs.hで定義されるSTATE_DATAマクロは、レンダリング・ステートを操作する。このマクロはD3DSTATE構造体へのポインタとD3DRENDERSTATETYPE列挙型の値を必要とする。

#define STATE_DATA(type, arg, ptr) \

    ((LPD3DSTATE) ptr)->drstRenderStateType = (D3DRENDERSTATETYPE)type; \

    ((LPD3DSTATE) ptr)->dwArg[0] = arg; \

    ptr = (void *)(((LPD3DSTATE) ptr) + 1)

D3DAppISetRenderState関数から抜粋した次のコードでは、OP_STATE_RENDERとSTATE_DATAマクロを使用して、14個のレンダリング・ステートを設定している。d3dapprsは、D3dapp.hヘッダ・ファイルで定義されたD3DAppRenderState構造体である。

OP_STATE_RENDER(14, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_SHADEMODE, d3dapprs.ShadeMode, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_TEXTUREPERSPECTIVE,

        d3dapprs.bPerspCorrect, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_ZENABLE, d3dapprs.bZBufferOn &&

        d3dappi.ThisDriver.bDoesZBuffer, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_ZWRITEENABLE, d3dapprs.bZBufferOn,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_ZFUNC, D3DCMP_LESSEQUAL, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_TEXTUREMAG, d3dapprs.TextureFilter,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_TEXTUREMIN, d3dapprs.TextureFilter,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_TEXTUREMAPBLEND, d3dapprs.TextureBlend,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_FILLMODE, d3dapprs.FillMode, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_DITHERENABLE, d3dapprs.bDithering,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_SPECULARENABLE, d3dapprs.bSpecular,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_ANTIALIAS, d3dapprs.bAntialiasing,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_FOGENABLE, d3dapprs.bFogEnabled,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_FOGCOLOR, d3dapprs.FogColor, lpBuffer);

OP_STATE_RENDERとSTATE_DATAマクロは、光源の状態を３つ設定する。OP_EXITマクロは、D3DOPCODE列挙型からD3DOP_EXITオペコードを取り出すために、PUTD3DINSTRUCTIONマクロを呼び出すだけである。

OP_STATE_LIGHT(3, lpBuffer);

    STATE_DATA(D3DLIGHTSTATE_FOGMODE, d3dapprs.bFogEnabled ?

        d3dapprs.FogMode : D3DFOG_NONE, lpBuffer);

    STATE_DATA(D3DLIGHTSTATE_FOGSTART,

        *(unsigned long*)&d3dapprs.FogStart, lpBuffer);

    STATE_DATA(D3DLIGHTSTATE_FOGEND, *(unsigned long*)&d3dapprs.FogEnd,

        lpBuffer);

OP_EXIT(lpBuffer);

レンダリング・ステートの設定が完了すると、D3DAppISetRenderState関数は、IDirect3DExecuteBuffer::Unlockメソッドを呼び出して実行バッファをアンロックする。また、IDirect3DExecuteBuffer::SetExecuteDataによって実行データを設定する。最後に、IDirect3DDevice::BeginScene、IDirect3DDevice::Execute、IDirect3DDevice::EndSceneメソッドを呼び出して、シーンを開始し、実行バッファを実行し、再びシーンを終了する。

LastError = lpD3DExCmdBuf->lpVtbl->Unlock(lpD3DExCmdBuf);

memset(&d3dExData, 0, sizeof(D3DEXECUTEDATA));

d3dExData.dwSize = sizeof(D3DEXECUTEDATA);

d3dExData.dwInstructionOffset = (ULONG) 0;

d3dExData.dwInstructionLength = (ULONG) ((char*)lpBuffer -

    (char*)lpInsStart);

lpD3DExCmdBuf->lpVtbl->SetExecuteData(lpD3DExCmdBuf, &d3dExData);

LastError =

    d3dappi.lpD3DDevice->lpVtbl->BeginScene(d3dappi.lpD3DDevice);

LastError =

    d3dappi.lpD3DDevice->lpVtbl->Execute(d3dappi.lpD3DDevice,

        lpD3DExCmdBuf, d3dappi.lpD3DViewport);

LastError = d3dappi.lpD3DDevice->lpVtbl->EndScene(d3dappi.lpD3DDevice);

D3DAppISetRenderStateは、実行バッファを終わりまで実行すると終了する。次にIDirect3DExecuteBuffer::Releaseメソッドを読んで、リターンする。

lpD3DExCmdBuf->lpVtbl->Release(lpD3DExCmdBuf);

return TRUE;

}


Step 6: 初期化の完了

WinMain関数内のAppInit関数から呼び出されるCreateD3DApp関数は、Direct3Dアプリケーションの土台のほとんどを作成するが、それで終わりではない。D3dmain.cppがレンダリング・ループを呼び出す前に、CreateD3DApp関数はあと少しのタスクを完了しなくてはならない。

CreateD3DApp関数は、現在のレンダリング・ステートをアプリケーション・ローカルなD3DAppRenderState構造体にコピーした後、OverrideDefaults関数を呼び出す。OverrideDefaults関数は、D3dmain.cppを使用するすべてのアプリケーションがサポートしなくてはならない関数のひとつである。OverrideDefaults関数ではほとんど何も行わないアプリケーションもある。たとえばOct1.cサンプルは、デフォルトのタイトル文字列を"Octagon D3D Example"に置き換えるだけである。

次にCreateD3DApp関数は、D3DAppSetRenderState関数を呼び出す。D3DAppSetRenderState関数は、保存されたレンダリング・ステートの状態をチェックし、（もしレンダリング・ステートに何も設定されていなかったら）リセットするか、D3DAppISetRenderState関数の呼び出しの前に保存するかを判定する。D3DAppISetRenderState関数については「Step 5: 直接モードのレンダリング・ステートの設定」で取り扱っている。

レンダリング・ループを開始する前の最後のステップとして、CreateD3DApp関数はReleaseViewとInitView関数の呼び出しを行う。これらの関数は、OverrideDefaults関数と同様に、各サンプル・アプリケーションがインプリメントする。ReleaseView関数は、InitView関数の呼び出しで作成されたオブジェクトを解放するだけである（InitView関数の呼び出しは2度目である。最初の呼び出しは、AfterDeviceCreatedコールバック関数が行っている）。このInitView関数の最後の呼び出しで、（デバイス作成時から変更が加えられている場合は）ビューポートの再セットアップを行い、サンプルの実行バッファを再構築する。InitView関数について詳しくは「Step 4: ビューポートの初期化」を参照されたい。

これでD3dmain.cppのCreateD3DApp関数が終了する。それだけでなく、AppInit関数の終了でもある。初期化処理が完了したので、コードはレンダリング・ループを開始できる。


Step 7: レンダリング・ループの実行

アプリケーションの初期化の後、D3dmain.cppのWinMain関数はメッセージ・ループをセットアップする。コードは、通知されるメッセージがなくなるまでメッセージ・キューを監視し、その後RenderLoop関数の呼び出す。RenderLoop関数はD3dmain.cppに定義されている。WinMain関数はRenderLoop関数が失敗できる回数を保持しており、3回以上失敗したときには、アプリケーションは終了する。

RenderLoop関数はシーンの次のフレームをレンダリングし、ウィンドウの更新を行う。

RenderLoop関数の最初のタスクは、可能であれば失われたDirectDrawサーフェスを復元することである。失われたサーフェスを識別するためにはIDirectDrawSurface::IsLostメソッドを呼び出し、IDirectDrawSurface::Restoreメソッドによってそれを復元する。それからRenderLoop関数は、IDirect3DRMViewport::Clearメソッドを呼び出してバック・バッファをクリアし、Zバッファが有効である場合は、それもクリアする。

そして、RenderLoop関数は、D3dmain.cppを使用するサンプル・アプリケーションがインプリメントするRenderScene関数を呼び出す。サンプルのRenderScene関数は、複雑な場合を考慮に入れたものと、Oct1.cのように簡単なインプリメントのものがある。その後、RenderScene関数は、IDirect3DDevice::BeginScene、IDirect3DDevice::Execute、およびIDirect3DDevice::EndSceneメソッドを呼び出し、実行バッファを実行する。また、IDirect3DExecuteBuffer::GetExecuteDataメソッドによって新しい実行データを取得し、スクリーンの範囲を更新し、ローカル定義のTickScene関数を呼び出す。TickScene関数はIDirect3DDevice::SetMatrixを用いて視点を変更する。

最後にRenderLoop関数は、D3DAppRenderExtentsヘルパ関数を呼び出して、フロント・バッファとバック・バッファの変更された部分を調べ、バック・バッファからフロント・バッファへブロック転送またはフリップを行う。


Step 8: 終了処理

復帰できないエラーが発生したり、WM_QUITまたはMENU_EXITメッセージを受け取ったときは、アプリケーションはCleanUpAndPostQuit関数を呼び出す。CleanUpAndPostQuit関数は簡単なエラー・チェックを行いReleaseScene関数を呼び出す。ReleaseScene関数は、D3dmain.cppを利用するサンプル・アプリケーションがインプリメントしなくてはならない関数のうち、最後のものである。このときアプリケーションは、残っているオブジェクトを破棄し、メモリを解放する。Oct1.cのような簡単なアプリケーションでは、ReleaseScene関数は単なるスタブに過ぎない。

最後に、CleanUpAndPostQuit関数はPostQuitMessage関数を呼び出して、アプリケーションを終了する。


Direct3DRMCreate

HRESULT Direct3DRMCreate(LPDIRECT3DRM FAR * lplpD3DRM);

Direct3DRMオブジェクトのインスタンスを作成する。

成功するとDP_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DRM

呼び出しが成功した場合、有効なDirect3DRMポインタが入るポインタのアドレス。

参照　Direct3DRMObject


D3DRMColorGetAlpha

D3DVALUE D3DRMColorGetAlpha(D3DCOLOR d3drmc);

色のアルファ要素を取得する。

成功するとアルファ値を返す。失敗すると0を返す。

d3drmc

アルファ要素を取得する色。

参照　D3DRMColorGetBlue, D3DRMColorGetGreen, D3DRMColorGetRed


D3DRMColorGetBlue

D3DVALUE D3DRMColorGetBlue(D3DCOLOR d3drmc);

色の青要素を取得する。

成功すると青色値を返す。失敗すると0を返す。

d3drmc

青要素を取得する色。

参照　D3DRMColorGetAlpha, D3DRMColorGetGreen,

 D3DRMColorGetRed


D3DRMColorGetGreen

D3DVALUE D3DRMColorGetGreen(D3DCOLOR d3drmc);

色の緑要素を取得する。

成功すると緑色値を返す。失敗すると0を返す。

d3drmc

緑要素を取得する色。

参照　D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetRed


D3DRMColorGetRed

D3DVALUE D3DRMColorGetRed(D3DCOLOR d3drmc);

色の赤要素を取得する。

成功すると赤色値を返す。失敗すると0を返す。

d3drmc

赤要素を取得する色。

参照　D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetGreen


D3DRMCreateColorRGB

D3DCOLOR D3DRMCreateColorRGB(D3DVALUE red, D3DVALUE green,

    D3DVALUE blue);

与えられた赤、緑および青要素から RGB 色を作成する。

成功すると新しいRGB値を返す。失敗すると0を返す。

red, green, blue

RGB色の構成要素。

参照　D3DRMCreateColorRGBA


D3DRMCreateColorRGBA

D3DCOLOR D3DRMCreateColorRGBA(D3DVALUE red, D3DVALUE green,

    D3DVALUE blue, D3DVALUE alpha);

与えられた赤、緑、青色、およびアルファ要素から RGBA 色を作成する。

成功すると新しいRGBA値を返す。失敗すると0を返す。

red, green, blue, alpha

RGBA色の構成要素。

参照　D3DRMCreateColorRGB


D3DRMFREEFUNCTION

typedef VOID (*D3DRMFREEFUNCTION)(LPVOID lpArg);

typedef D3DRMFREEFUNCTION *LPD3DRMFREEFUNCTION;

メモリを解放する。この関数の実体はアプリケーションで定義される。

返値はない。

lpArg

アプリケーション定義のデータのアドレス。

標準Cランタイム・ルーチンでは不十分な場合、アプリケーションは、独自のメモリ解放関数を定義することができる。


D3DRMMALLOCFUNCTION

typedef LPVOID (*D3DRMMALLOCFUNCTION)(DWORD dwSize);

typedef D3DRMMALLOCFUNCTION *LPD3DRMMALLOCFUNCTION;

メモリを割り当てる。この関数の実体はアプリケーションで定義される。

成功すると、割り当てられたメモリのアドレスを返す。失敗すると0を返す。

dwSize

割り当てられるメモリの大きさをバイト単位で指定する。

標準Cランタイム・ルーチンでは不十分な場合、アプリケーションは、独自のメモリ割り当て関数を定義することができる。


D3DRMMatrixFromQuaternion

void D3DRMMatrixFromQuaternion (D3DRMMATRIX4D mat,

   LPD3DRMQUATERNION lpquat);

回転を示す行列を計算する。

返値はない。

mat

関数が制御を返すとき、計算された行列が入るアドレス。（D3DRMMATRIX4D型は配列である）

lpquat

D3DRMQUATERNION構造体へのポインタ。.


D3DRMQuaternionFromRotation

LPD3DRMQUATERNION D3DRMQuaternionFromRotation(LPD3DRMQUATERNION lpquat,

    LPD3DVECTOR lpv, D3DVALUE theta);

指定された軸を中心に、指定された角度（ラジアン単位）の回転を行う。

成功すると、第1パラメータとして渡された4次行列へのポインタを返す。失敗すると0を返す。

lpquat

操作結果を受け取るD3DRMQUATERNION 構造体。

lpv

回転の軸を指定するD3DVECTOR 構造体のアドレス。

theta

lpv パラメータによって指定された軸の周りを回転する角度（ラジアン単位）。


D3DRMQuaternionMultiply

LPD3DRMQUATERNION D3DRMQuaternionMultiply(LPD3DRMQUATERNION lpq,

    LPD3DRMQUATERNION lpa, LPD3DRMQUATERNION lpb);

ふたつのベクトルの積を計算する。

成功すると、第1パラメータとして渡された構造体へのポインタを返す。失敗すると0を返す。

lpq

乗算の結果を受け取るD3DRMQUATERNION 構造体のアドレス。

lpa, lpb

掛け合わせるD3DRMQUATERNION 構造体。


D3DRMQuaternionSlerp

LPD3DRMQUATERNION D3DRMQuaternionSlerp(LPD3DRMQUATERNION lpq,

    LPD3DRMQUATERNION lpa, LPD3DRMQUATERNION lpb, D3DVALUE alpha);

球面線形補間を使用してふたつの構造体を補完する。

成功すると、第1パラメータとして渡された構造体を返す。失敗すると0を返す。

lpq

補完した結果を受け取るD3DRMQUATERNION 構造体。

lpa, lpb

補完の開始位置と終了位置として用いられるD3DRMQUATERNION構造体。

alpha

lpaとlpbの間に補完する距離を示す、0から1の間の値。


D3DRMREALLOCFUNCTION

typedef LPVOID (*D3DRMREALLOCFUNCTION)(LPVOID lpArg,

    DWORD dwSize);

typedef D3DRMREALLOCFUNCTION *LPD3DRMREALLOCFUNCTION;

メモリの再割り当てを行う。この関数の実体はアプリケーションで定義される。

成功すると、再割り当てされたメモリのアドレスを返す。失敗すると0を返す。

lpArg

アプリケーション定義のデータ。

dwSize

再割り当てするメモリのサイズをバイト単位で指定する。

標準Cランタイム・ルーチンでは不十分な場合、アプリケーションは、独自のメモリ再割り当て関数を定義できる。


D3DRMVectorAdd

LPD3DVECTOR D3DRMVectorAdd(LPD3DVECTOR lpd, LPD3DVECTOR lps1,

    LPD3DVECTOR lps2);

ふたつのベクトルを加算する。

成功すると、第1パラメータとして渡されたベクトルを返す。失敗すると0を返す。

lpd

加算の結果を受け取るD3DVECTOR構造体。

lps1, lps2

加算されるD3DVECTOR構造体。


D3DRMVectorCrossProduct

LPD3DVECTOR D3DRMVectorCrossProduct(LPD3DVECTOR lpd, LPD3DVECTOR lps1,

    LPD3DVECTOR lps2);

ふたつのベクトルの外積を計算する。

成功すると、第1パラメータとして渡されたベクトルを返す。失敗すると0を返す。

lpd

外積の結果を受け取るD3DVECTOR構造体。

lps1,  lps2

外積が計算されるD3DVECTOR構造体。


D3DRMVectorDotProduct

D3DVALUE D3DRMVectorDotProduct(LPD3DVECTOR lps1, LPD3DVECTOR lps2);

ベクトルの内積を返す。

成功すると内積の結果を返す。失敗すると0を返す。

lps1,  lps2

内積が計算されるD3DVECTOR構造体。


D3DRMVectorModulus

D3DVALUE D3DRMVectorModulus(LPD3DVECTOR lpv);

以下の式にしたがってベクトルの長さを返す。

成功するとD3DVECTOR構造体に長さを返す。失敗すると0を返す。

lpv

長さを計算するD3DVECTOR構造体。


D3DRMVectorNormalize

LPD3DVECTOR D3DRMVectorNormalize(LPD3DVECTOR lpv);

絶対値が1になるようにベクトルをスケーリングする。

成功すると、第1パラメータとして渡されたベクトルを返す。たとえばゼロ・ベクトルが渡された場合など、エラーが発生すると0を返す。

lpv

スケーリング操作の結果を受け取るD3DVECTOR構造体。


D3DRMVectorRandom

LPD3DVECTOR D3DRMVectorRandom(LPD3DVECTOR lpd);

ランダムなベクトル・ユニットを返す。

成功すると、第1パラメータとして渡されたベクトルを返す。失敗すると0を返す。

lpd

ランダムなベクトル・ユニットを受け取るD3DVECTOR 構造体。


D3DRMVectorReflect

LPD3DVECTOR D3DRMVectorReflect(LPD3DVECTOR lpd, LPD3DVECTOR lpRay,

    LPD3DVECTOR lpNorm);

指定された法線について、光線を反射する。

成功すると、第1パラメータとして渡されたベクトルを返す。失敗すると0を返す。

lpd

処理結果を受け取るD3DVECTOR構造体。

lpRay

法線で反射されるD3DVECTOR構造体。

lpNorm

lpRayで指定された光線を反射する法線を示す、D3DVECTOR構造体。


D3DRMVectorRotate

LPD3DVECTOR D3DRMVectorRotate(LPD3DVECTOR lpr, LPD3DVECTOR lpv,

    LPD3DVECTOR lpaxis, D3DVALUE theta);

指定された軸を中心にベクトルを回転させる。

成功すると、第1パラメータとして渡されたベクトルを返す。失敗すると0を返す。

lpr

処理結果を受け取るD3DVECTOR 構造体。

lpv

与えられた軸の回りを回転するD3DVECTOR構造体。

lpaxis

回転の軸を示すD3DVECTOR 構造体。

theta

ラジアン単位での回転角度。


D3DRMVectorScale

LPD3DVECTOR D3DRMVectorScale(LPD3DVECTOR lpd, LPD3DVECTOR lps,

    D3DVALUE factor);

３つの軸について同じ比率で、ベクトルをスケーリングする。

成功すると第1パラメータとして渡されたベクトルを返す。失敗すると0を返す。

lpd

処理結果を受け取るD3DVECTOR構造体。

lps

スケーリングされるD3DVECTOR構造体。

factor

縮尺係数。この値が1のとき、スケーリングは行われない。この値が2のときは2倍になる。


D3DRMVectorSubtract

LPD3DVECTOR D3DRMVectorSubtract(LPD3DVECTOR lpd, LPD3DVECTOR lps1,

    LPD3DVECTOR lps2);

ふたつのベクトル間で減算を行う。

成功すると、第1パラメータとして渡されたベクトルを返す。失敗すると0を返す。

lpd

処理結果を受け取るD3DVECTOR構造体。

lps1

lps2 が引かれるD3DVECTOR構造体。

lps2

lps1 から引くD3DVECTOR構造体。


コールバック関数


D3DRMDEVICEPALETTECALLBACK

void (*D3DRMDEVICEPALETTECALLBACK)

    (LPDIRECT3DRMDEVICE lpDirect3DRMDev, LPVOID lpArg, DWORD dwIndex,

    LONG red, LONG green, LONG blue);

パレット・エントリを列挙する。このコールバック関数の実体はアプリケーションで定義される。

返値はない。

lpDirect3DRMDev

このデバイスの IDirect3DRMDevice インターフェイス。

lpArg

コールバック関数に渡されるアプリケーション定義のデータ。

dwIndex

列挙されたパレット・エントリのインデックス。

red, green, blue

指定されたパレット・インデックスの赤、緑、青要素。

システムはコールバック関数を呼び出す順序を決定するため、まず階層のトップ・レベルにあるオブジェクトを検索する。次に、それらが作成された順番にコールバック関数を呼び出す。


D3DRMFRAMEMOVECALLBACK

void (*D3DRMFRAMEMOVECALLBACK)(LPDIRECT3DRMFRAME lpD3DRMFrame,

    LPVOID lpArg, D3DVALUE delta);

フレームの移動や更新時に、アプリケーションがカスタマイズしたアルゴリズムを適用できるようにする。フレーム・レートを変更するためにこのコールバック関数を使用することができる。このコールバック関数の実体はアプリケーションで定義される。

返値はない。

lpD3DRMFrame

変更しようとしているDirect3DRMFrameオブジェクト。

lpArg

コールバック関数に渡されるアプリケーション定義のデータ。

delta

変化量。フレームの位置を変更するには、移動と回転というふたつの要素がある。各要素における変更はvelocity_of_component × deltaで表される。これらの一方または両方の速度は、任意のフレームに比例して設定することができる。しかしシステムは、デルタ時間を適用するため、自動的に親フレームに比例した速度に変換する。.

アプリケーションは、親フレームに比例してフレームの加速を合成することができる。そのためには、各瞬間において、子フレームの速度をアプリケーション自身に比例した (1ティックあたりaユニット) × 1 にセットしなくてはならない。ここで、aは要求された加速度である。これはティック当たりの a × delta と等しい。内部的には、子フレームに比例したティック当たりの a × delta は、親フレームに比例した (v + (a × delta)) ユニットに変換される。このとき、vは、親に対する現在の子フレームの速度を相対的に示したものである。

このコールバック関数を追加・削除するには、IDirect3DRMFrame::AddMoveCallbackおよびIDirect3DRMFrame::DeleteMoveCallbackメソッドを使用する。

システムは、コールバック関数を呼び出す順序を決定するため、まず階層のトップ・レベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を呼び出す。


D3DRMLOADCALLBACK

void (*D3DRMLOADCALLBACK) (LPDIRECT3DRMOBJECT lpObject, REFIID ObjectGuid,

    LPVOID lpArg);

IDirect3DRM::Loadメソッド内部でオブジェクトのロードを行う。このコールバック関数の実体はアプリケーションで定義される。

返値はない。

lpObject

ロードされるDirect3DRMObject。

ObjectGuid

ロードされるオブジェクトのグローバル・ユニーク識別子（GUID）。

lpArg

コールバック関数に渡されるアプリケーション定義のデータ。

システムはコールバック関数を呼び出す順序を決定するため、まず階層のトップ・レベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を呼び出す。

参照　IDirect3DRM::Load


D3DRMLOADTEXTURECALLBACK

HRESULT (*D3DRMLOADTEXTURECALLBACK) (char *tex_name, void *lpArg,

    LPDIRECT3DRMTEXTURE *lpD3DRMTex);

Loadメソッドの内部で、テクスチャ・ファイル（もしくはリソース）の実際の読み込みを行う。このコールバック関数の実体はアプリケーションで定義される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

tex_name

テクスチャ名。

lpArg

アプリケーション固有のデータ。

lpD3DRMTex

Direct3DRMTextureオブジェクト。

アプリケーションは、Windowsビットマップ（ .bmp ）やポータブル・ピクスマップ（ .ppm ） P6 形式以外のテクスチャのサポートをインプリメントするため、このコールバック関数を使用することができる。

システムは、コールバック関数を呼び出す順序を決定するため、まず階層のトップ・レベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を呼び出す。

参照　IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load


D3DRMOBJECTCALLBACK

void (*D3DRMOBJECTCALLBACK)(LPDIRECT3DRMOBJECT lpD3DRMobj,

    LPVOID lpArg);

IDirect3DRM::EnumerateObjectsメソッドの呼び出しに応答するオブジェクトを列挙する。このコールバック関数の実体はアプリケーション定義である。

返値はない。

lpD3DRMobj

オブジェクトを列挙するIDirect3DRMObjectインターフェイス。アプリケーションは、列挙された各オブジェクトについてReleaseメソッドを呼び出さなくてはならない。

lpArg

コールバック関数に渡されるアプリケーション定義のデータ。

システムはコールバック関数を呼び出す順序を決定するため、まず階層のトップ・レベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を呼び出す。

参照　IDirect3DRM::EnumerateObjects


D3DRMUPDATECALLBACK

void (*D3DRMUPDATECALLBACK)(LPDIRECT3DRMDEVICE lpobj, LPVOID lpArg,

    int iRectCount, LPD3DRECT d3dRectUpdate);

デバイスが変更されたときアプリケーションに警告する。このコールバック関数の実体はアプリケーション定義である。

返値はない。

lpobj

コールバック関数を適用するDirect3DRMDeviceオブジェクト。

lpArg

コールバック関数に渡されるアプリケーション定義のデータ。

iRectCount

d3dRectUpdateパラメータに指定された矩形の数。

d3dRectUpdate

更新される領域を表す、ひとつ以上のD3DRECT構造体の配列。座標はデバイス単位で指定される。

システムは、コールバック関数を呼び出す順序を決定するため、まず階層のトップ・レベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を呼び出す。

参照　IDirect3DRMDevice::AddUpdateCallback, IDirect3DRMDevice::DeleteUpdateCallback, IDirect3DRMDevice::Update


D3DRMUSERVISUALCALLBACK

int (*D3DRMUSERVISUALCALLBACK)(LPDIRECT3DRMUSERVISUAL lpD3DRMUV,

    LPVOID lpArg, D3DRMUSERVISUALREASON lpD3DRMUVreason,

    LPDIRECT3DRMDEVICE lpD3DRMDev, LPDIRECT3DRMVIEWPORT lpD3DRMview);

ユーザ・ビジュアルオブジェクトを提供するアプリケーションに、実行バッファを実行する必要があることを通知する。このコールバック関数の実体はアプリケーション定義である。

lpD3DRMUVreasonパラメータにD3DRMUSERVISUAL_CANSEEが指定され、ユーザ・ビジュアル・オブジェクトがビューポート内で可視状態のときは、TRUEを返す。そうでなければFALSEを返す。lpD3DRMUVreason パラメータにD3DRMUSERVISUAL_RENDERが指定されているときは、アプリケーション定義の返値となる。この場合、つねにTRUEを返すのが安全である。

lpD3DRMUV

Direct3DRMUserVisualオブジェクト。

lpArg

コールバック関数に渡されるアプリケーション定義のデータ。

lpD3DRMUVreason

D3DRMUSERVISUALREASON列挙型のメンバのひとつ。

D3DRMUSERVISUAL_CANSEE

	ユーザ・ビジュアル・オブジェクトが ビューポート内で可視状態であれば、アプリケーションはTRUEを返す。この場合、アプリケーションは、lpD3DRMview パラメータで指定されたデバイスを使用する。

D3DRMUSERVISUAL_RENDER

	アプリケーションは、ユーザ・ビジュアル・エレメントをレンダリングしなくてはならない。この場合、アプリケーションは、lpD3DRMDevパラメータで指定されたデバイスを使う。
lpD3DRMDev

Direct3DRMUserVisualオブジェクトをレンダリングするために使われるDirect3DRMDeviceオブジェクト。

lpD3DRMview

Direct3DRMUserVisual オブジェクトが可視状態かどうかを決定するために使われる Direct3DRMViewport オブジェクト。

システムはコールバック関数を呼び出す順序を決定するため、まず階層のトップ・レベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を呼び出す。

参照　IDirect3DRMUserVisual::Init


D3DRMWRAPCALLBACK

void (*D3DRMWRAPCALLBACK)(LPD3DVECTOR lpD3DVector,

    int* lpU, int* lpV, LPD3DVECTOR lpD3DRMVA, LPD3DVECTOR lpD3DRMVB,

    LPVOID lpArg);

このコールバック関数はサポートされていない。


IDirect3DRM 配列インターフェース
IDirect3DRM配列インターフェイス

配列インターフェイスを用いると、アプリケーションは、オブジェクトを配列にグループ化して簡単にグループ全体に処理を適用することができる。以下の配列インターフェイスを使用することができる。

IDirect3DRMArray
IDirect3DRMDeviceArray
IDirect3DRMFaceArray
IDirect3DRMFrameArray
IDirect3DRMLightArray
IDirect3DRMPickedArray
IDirect3DRMViewportArray
IDirect3DRMVisualArray


IDirect3DRMArray

IDirect3DRMArrayインターフェイスはオブジェクトのグループを管理する。通常、アプリケーションはこのインターフェイスを直接使わず、このインターフェイスから派生した配列オブジェクトを利用する。このセクションは、IDirect3DRMArrayインターフェイス・メソッドのリファレンスである。

IDirect3DRMArrayインターフェイスはGetSizeメソッドをサポートする。

すべてのCOMインターフェイスと同様、IDirect3DRMArrayインターフェイスはIUnknownインターフェイス・メソッドを継承する。このインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release


IDirect3DRMArray::GetSize

DWORD GetSize();

Direct3DRMArray オブジェクトのサイズを、オブジェクト単位で取得する。

サイズを返す。


IDirect3DRMDeviceArray

デバイス・オブジェクトをグループ化するには、IDirect3DRMDeviceArrayインターフェイスのメソッドを利用する。このセクションは、IDirect3DRMDeviceArrayインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMDeviceとIDirect3DRMDeviceArray インターフェイス.」を参照すること。

IDirect3DRMDeviceArray インターフェイスは、次のメソッドをサポートする。

GetElement
GetSize
IDirect3DRMDeviceArray インターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMDeviceArrayインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
 Direct3DRMDeviceArrayオブジェクトは、 IDirect3DRM::GetDevices methodメソッドの呼び出しによって取得される。


IDirect3DRMDeviceArray::GetElement

HRESULT GetElement(DWORD index, LPDIRECT3DRMDEVICE * lplpD3DRMDevice);

Direct3DRMDeviceArrayオブジェクトから指定された要素を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

配列要素。

lplpD3DRMDevice

IDirect3DRMDevice インターフェイスへのポインタ。


IDirect3DRMDeviceArray::GetSize

DWORD GetSize();

Direct3DRMDeviceArray オブジェクトに含まれる要素数を取得する。

要素数を返す。


IDirect3DRMFaceArray

メッシュ上の面をグループ化するには、IDirect3DRMFaceArrayインターフェイスのメソッドを利用する。このセクションは、IDirect3DRMFaceArrayインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMFaceとIDirect3DRMFaceArrayインターフェイス」を参照すること。

IDirect3DRMFaceArrayインターフェイスは、次のメソッドをサポートする。

GetElement
GetSize
IDirect3DRMFaceArrayインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは、次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMFaceArrayインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMFaceArrayオブジェクトは IDirect3DRMMeshBuilder::GetFacesメソッドの呼び出しによって取得される。


IDirect3DRMFaceArray::GetElement

HRESULT GetElement(DWORD index, LPDIRECT3DRMFACE * lplpD3DRMFace);

Direct3DRMFaceArrayオブジェクトから指定された要素を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

配列要素。

lplpD3DRMFace

IDirect3DRMFaceインターフェイスへのポインタ。


IDirect3DRMFaceArray::GetSize

DWORD GetSize();

Direct3DRMFaceArrayオブジェクトに含まれる要素数を取得する。

要素数を返す。


IDirect3DRMFrameArray

フレーム・オブジェクトをグループ化するには、IDirect3DRMFrameArrayインターフェイスのメソッドを利用する。このセクションは、IDirect3DRMFrameArrayインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMFrameとIDirect3DRMFrameArrayインターフェイス」を参照すること。

IDirect3DRMFrameArrayインターフェイスは、次のメソッドをサポートする。

GetElement
GetSize
IDirect3DRMFrameArrayインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは、次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IIDirect3DRMFrameArrayインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMFrameArrayオブジェクトは、IDirect3DRMPickedArray::GetPickまたはIDirect3DRMFrame::GetChildrenメソッドの呼び出しによって取得される。


IDirect3DRMFrameArray::GetElement

HRESULT GetElement(DWORD index, LPDIRECT3DRMFRAME * lplpD3DRMFrame);

Direct3DRMFrameArrayオブジェクトから指定された要素を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

配列要素。

lplpD3DRMFrame

IDirect3DRMFrame インターフェイスへのポインタを受け取るアドレス。


IDirect3DRMFrameArray::GetSize

DWORD GetSize();

Direct3DRMFrameArrayオブジェクトに含まれている要素数を取得する。

要素数を返す。


IDirect3DRMLightArray

光源オブジェクトをグループ化するには、IDirect3DRMLightArrayインターフェイスのメソッドを利用する。このセクションは、IDirect3DRMLightArrayインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMLightとIDirect3DRMLightArrayインターフェイス」を参照すること。

IDirect3DRMLightArrayインターフェイスは、次のメソッドをサポートする。

GetElement
GetSize
IDirect3DRMLightArrayインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMLightArrayインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMFrameArrayオブジェクトは、 IDirect3DRMFrame::GetLightsメソッドの呼び出しによって取得される。


IDirect3DRMLightArray::GetElement

HRESULT GetElement(DWORD index, LPDIRECT3DRMLIGHT * lplpD3DRMLight);

Direct3DRMLightArray オブジェクトから指定された要素を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

配列要素。

lplpD3DRMLight

IDirect3DRMLightインターフェイスへのポインタを受け取るアドレス。


IDirect3DRMLightArray::GetSize

DWORD GetSize();

Direct3DRMLightArray オブジェクトに含まれている要素数を取得する。

要素数を返す。


IDirect3DRMPickedArray

ピック・オブジェクトをグループ化するには、IDirect3DRMPickedArrayインターフェイスのメソッドを利用する。このセクションは、IDirect3DRMPickedArrayインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMPickedArrayインターフェイス」を参照すること。

IDirect3DRMPickedArrayインターフェイスは、次のメソッドをサポートする。

GetPick
GetSize
IDirect3DRMPickedArrayインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMPickedArrayインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMPickedArrayオブジェクトは、IDirect3DRMViewport::Pickメソッドの呼び出しによって取得される。


IDirect3DRMPickedArray::GetPick

HRESULT GetPick(DWORD index, LPDIRECT3DRMVISUAL * lplpVisual,

    LPDIRECT3DRMFRAMEARRAY * lplpFrameArray,

    LPD3DRMPICKDESC lpD3DRMPickDesc);

指定されたピックによって交差するDirect3DRMVisualとDirect3DRMFrameオブジェクトを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

情報を取得するピックを識別する、ピック配列へのインデックス。

lplpVisual

指定されたピックに関連付けられたDirect3DRMVisual オブジェクトのポインタのアドレス。

lplpFrameArray

指定されたピックに関連付けられたDirect3DRMFrameArrayオブジェクトのポインタのアドレス。

lpD3DRMPickDesc

ピックの位置、面、取得するオブジェクトのグループ識別子を指定するD3DRMPICKDESC構造体へのアドレス。

参照　IDirect3DRMViewport::Pick


IDirect3DRMPickedArray::GetSize

DWORD GetSize();

Direct3DRMPickedArray オブジェクトに含まれている要素数を取得する。

要素数を返す。


IDirect3DRMViewportArray

ビューポート・オブジェクトをグループ化するには、IDirect3DRMViewportArrayインターフェイスのメソッドを利用する。このセクションはIDirect3DRMViewportArrayインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMViewportとIDirect3DRMViewportArrayインターフェイス」を参照すること。

IDirect3DRMViewportArrayインターフェイスは次のメソッドをサポートする。

GetElement
GetSize
IDirect3DRMViewportArrayインターフェイスは、すべてのCOMインターフェイスと同様、IUnknown インターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMViewportArray インターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMViewportArrayオブジェクトは、 IDirect3DRM::CreateFrameメソッドの呼び出しによって取得される。


IDirect3DRMViewportArray::GetElement

HRESULT GetElement(DWORD index, LPDIRECT3DRMVIEWPORT * lplpD3DRMViewport);

Direct3DRMViewportArray オブジェクトから指定された要素を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

配列要素。

lplpD3DRMViewport

IDirect3DRMViewportインターフェイスを受け取るアドレスへのポインタ。


IDirect3DRMViewportArray::GetSize

DWORD GetSize();

Direct3DRMViewportArray オブジェクトに含まれている要素数を取得する。

要素数を返す。


IDirect3DRMVisualArray

ビジュアル・オブジェクトをグループ化するには、IDirect3DRMVisualArrayインターフェイスのメソッドを利用する。このセクションは、IDirect3DRMVisualArrayインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMVisualとIDirect3DRMVisualArrayインターフェイス」を参照すること。

GetElement
GetSize
IDirect3DRMVisualArrayインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMVisualArrayインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMVisualArrayオブジェクトは IDirect3DRMFrame::GetVisuals method.メソッドの呼び出しによって取得される。


IDirect3DRMVisualArray::GetElement

HRESULT GetElement(DWORD index, LPDIRECT3DRMVISUAL * lplpD3DRMVisual);

Direct3DRMVisualArrayオブジェクトから指定された要素を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

配列要素。

lplpD3DRMVisual

IDirect3DRMVisual インターフェイスを受け取るポインタ。


IDirect3DRMVisualArray::GetSize

DWORD GetSize();

Direct3DRMVisualArray オブジェクトに含まれている要素数を取得する。

要素数を返す。


IDirect3DRM

IDirect3DRMインターフェイスは、Direct3DRMオブジェクトを作成し、システム・レベルの変数を操作するために用いられる。このセクションは、IDirect3DRMインターフェイスのメソッドのリファレンスである。概念についての概要は、「IDirect3DRMインターフェイス」を参照すること。

IDirect3DRM インターフェイス・メソッドは、以下のグループに分類することができる。

アニメーション	CreateAnimation
	CreateAnimationSet
デバイス	CreateDevice
	CreateDeviceFromClipper
	CreateDeviceFromD3D
	CreateDeviceFromSurface
	GetDevices
列挙	EnumerateObjects
面（フェイス）	CreateFace
フレーム	CreateFrame
光源	CreateLight
	CreateLightRGB
マテリアル	CreateMaterial
メッシュ	CreateMesh
	CreateMeshBuilder
その他	CreateObject
	CreateUserVisual
	GetNamedObject
	Load
	Tick
パス検索	AddSearchPath
	GetSearchPath
	SetSearchPath
陰影	CreateShadow
テクスチャ	CreateTexture
	CreateTextureFromSurface
	LoadTexture
	LoadTextureFromResource
	SetDefaultTextureColors
	SetDefaultTextureShades
ビューポート	CreateViewport
ラップ	CreateWrap
IDirect3DRMインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
IDirect3DRM COMインターフェイスは、Direct3DRMCreateの呼び出しによって作成される。


IDirect3DRM::AddSearchPath

HRESULT AddSearchPath(LPCSTR lpPath);

現在のファイル検索パスの最後にディレクトリのリストを追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpPath

現在の検索パスに追加するパスを指定する、NULLで終わる文字列へのポインタ。

Windowsでは、パスはセミコロン（;）で区切ったディレクトリのリストでなくてはならない。

参照　IDirect3DRM::SetSearchPath


IDirect3DRM::CreateAnimation

HRESULT CreateAnimation(LPDIRECT3DRMANIMATION * lplpD3DRMAnimation);

空の Direct3DRMAnimationオブジェクトを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DRMAnimation

呼び出しが成功したときにIDirect3DRMAnimationインターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateAnimationSet

HRESULT CreateAnimationSet (LPDIRECT3DRMANIMATIONSET * lplpD3DRMAnimationSet);

空のDirect3DRMAnimationSetオブジェクトを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DRMAnimationSet

呼び出しが成功したときに「IDirect3DRMAnimationSet」インターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateDevice

HRESULT CreateDevice(DWORD dwWidth, DWORD dwHeight,

    LPDIRECT3DRMDEVICE* lplpD3DRMDevice);

Windows上には実装されていない。


IDirect3DRM::CreateDeviceFromClipper

HRESULT CreateDeviceFromClipper(LPDIRECTDRAWCLIPPER lpDDClipper,

    LPGUID lpGUID, int width, int height,

    LPDIRECT3DRMDEVICE * lplpD3DRMDevice);

指定されたDirectDrawClipperオブジェクトを使ってDirect3DRM Windowsデバイスを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpDDClipper

DirectDrawClipper オブジェクトのアドレス。

lpGUID

グローバル・ユニーク識別子（GUID）のアドレス。このパラメータにはNULLを指定することができる。

width , height

作成されるデバイスの幅と高さ。

lplpD3DRMDevice

呼び出しが成功したときにIDirect3DRMDevice インターフェイスを受け取るポインタへのポインタ。

lpGUID パラメータにNULLを指定すると、システムはデバイスの性能を調べる。これは、ユーザが新しいハードウェアをインストールしたときにもつねに動作するため、直接モード・デバイスの作成方法として推奨されている。

システムは、内部のデバイス列挙の呼び出しの中で、D3DPRIMCAPS構造体から次のフラグを使うことによってデフォルトの設定を構成する。

D3DPCMPCAPS_LESSEQUAL
D3DPMISCCAPS_CULLCCW
D3DPRASTERCAPS_FOGVERTEX
D3DPSHADECAPS_ALPHAFLATSTIPPLED
D3DPTADDRESSCAPS_WRAP
D3DPTBLENDCAPS_COPY D3DPTBLENDCAPS_MODULATE
D3DPTEXTURECAPS_PERSPECTIVE D3DPTEXTURECAPS_TRANSPARENCY
D3DPTFILTERCAPS_NEAREST
ハードウェア・デバイスが見つからないときは、モノクロ（ランプ）のソフトウェア・ドライバがロードされる。このデフォルト設定のリストにマッチしない特別な要求を持つアプリケーションは、lpGUIDにNULLを指定する代わりにデバイスを列挙するべきである。


IDirect3DRM::CreateDeviceFromD3D

HRESULT CreateDeviceFromD3D(LPDIRECT3D lpD3D,

    LPDIRECT3DDEVICE lpD3DDev, LPDIRECT3DRMDEVICE * lplpD3DRMDevice);

指定されたDirect3Dオブジェクトを使って Direct3DRM Windowsデバイスを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3D

Direct3Dインスタンス。

lpD3DDev

Direct3Dデバイス・オブジェクト。

lplpD3DRMDevice

呼び出しが成功したときにIDirect3DRMDeviceインターフェイスへのポインタを受け取るポインタ。


IDirect3DRM::CreateDeviceFromSurface

HRESULT CreateDeviceFromSurface(LPGUID lpGUID, LPDIRECTDRAW lpDD,

    LPDIRECTDRAWSURFACE lpDDSBack,

    LPDIRECT3DRMDEVICE * lplpD3DRMDevice);

指定された DirectDrawサーフェスから、レンダリングに用いるWindowsデバイスを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpGUID

指定するデバイス・ドライバのグローバル・ユニーク識別子（GUID）のアドレス。このパラメータにNULLが指定されると、デフォルトのデバイス・ドライバが使用される。

lpDD

DirectDrawサーフェスの元になるDirectDrawオブジェクト。

lpDDSBack

バック・バッファを表すDirectDrawSurfaceオブジェクト。

lplpD3DRMDevice

呼び出しが成功したときにIDirect3DRMDeviceインターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateFace

HRESULT CreateFace(LPDIRECT3DRMFACE * lplpd3drmFace);

IDirect3DRMFaceインターフェイスのインスタンスを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpd3drmFace

呼び出しが成功したときにIDirect3DRMFaceインターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateFrame

HRESULT CreateFrame(LPDIRECT3DRMFRAME lpD3DRMFrame,

    LPDIRECT3DRMFRAME* lplpD3DRMFrame);

指定された親フレームに新しい子フレームを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMFrame

新しいフレームの親フレーム。

lplpD3DRMFrame

呼び出しが成功したときにIDirect3DRMFrameインターフェイスを受け取るポインタへのポインタ。

子フレームは親フレームの動作属性を継承する。たとえば親フレームが指定された速度で動いている場合、子フレームも同じ速度で動く。また、親フレームが回転していれば、子フレームも親フレームの原点を中心として回転する。親フレームを持たないフレームはシーンと呼ばれる。シーンを作成するには、親フレームとしてNULL を指定すればよい。アプリケーションは、親を持たないフレームを作った後に、IDirect3DRMFrame::AddChild methodメソッド を用いてそのフレームを親フレームに関連付けることができる。

参照　IDirect3DRMFrame::AddChild


IDirect3DRM::CreateLight

HRESULT CreateLight(D3DRMLIGHTTYPE d3drmltLightType,

    D3DCOLOR cColor, LPDIRECT3DRMLIGHT* lplpD3DRMLight);

指定されたタイプと色で新しい光源を作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmltLightType

D3DRMLIGHTTYPE列挙型で与えられる光源のタイプのひとつ。

cColor

光の色。

lplpD3DRMLight

呼び出しが成功したときにIDirect3DRMLightインターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateLightRGB

HRESULT CreateLightRGB(D3DRMLIGHTTYPE ltLightType, D3DVALUE vRed,

    D3DVALUE vGreen, D3DVALUE vBlue, LPDIRECT3DRMLIGHT* lplpD3DRMLight);

指定されたタイプと色で新しい光源を作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

ltLightType

D3DRMLIGHTTYPE列挙型で与えられる光源のタイプのひとつ。

vRed, vGreen, vBlue

光の色。

lplpD3DRMLight

呼び出しが成功したときにIDirect3DRMLightインターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateMaterial

HRESULT CreateMaterial(D3DVALUE vPower,

    LPDIRECT3DRMMATERIAL * lplpD3DRMMaterial);

指定された反射特性でマテリアルを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

vPower

反射のハイライト部分の鮮明度。この値に5を指定すると、レンダリングされた表面は金属のような外観になり、それ以上の値ではもっと柔らかい外観となる。

lplpD3DRMMaterial

呼び出しが成功したときにIDirect3DRMMaterialインターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateMesh

HRESULT CreateMesh(LPDIRECT3DRMMESH* lplpD3DRMMesh);

面を持たない新しいメッシュ・オブジェクトを作成する。メッシュはフレームに加えられるまで表示されない。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DRMMesh

呼び出しが成功したときにIDirect3DRMMeshインターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateMeshBuilder

HRESULT CreateMeshBuilder(LPDIRECT3DRMMESHBUILDER* lplpD3DRMMeshBuilder);

新しいメッシュ作成オブジェクトを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DRMMeshBuilder

呼び出しが成功したときにIDirect3DRMMeshBuilderインターフェイスへのポインタを受け取るアドレス。


IDirect3DRM::CreateObject

HRESULT CreateObject(REFCLSID rclsid, LPUNKNOWN pUnkOuter,

    REFIID riid, LPVOID FAR* ppv);

初期化されていない新しいオブジェクトを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rclsid

新しいオブジェクトのクラス識別子。

pUnkOuter

COM集成化機能に対応する。

riid

作成されるオブジェクトのインターフェイス識別子。

ppv

メソッドが制御を戻したときにオブジェクトを受け取るポインタへのポインタ。

このメソッドにより作成されたオブジェクトは、アプリケーションによって初期化されなくてはならない（IDirect3DRMインターフェイスの他の作成メソッドは、自動的にオブジェクトを初期化する）。 新しいオブジェクトを初期化するには、Initメソッドを使用する。Initメソッドの呼び出しは、オブジェクトについて1回のみ行う。

アプリケーションは、このメソッドを用いてDirect3DRMオブジェクトの集合体をインプリメントできる。


IDirect3DRM::CreateShadow

HRESULT CreateShadow(LPDIRECT3DRMVISUAL lpVisual,

    LPDIRECT3DRMLIGHT lpLight, D3DVALUE px, D3DVALUE py, D3DVALUE pz,

    D3DVALUE nx, D3DVALUE ny, D3DVALUE nz,

    LPDIRECT3DRMVISUAL * lplpShadow);

指定されたビジュアルと光源を用い、指定された平面に投影させて陰影を作成する。陰影は、ビジュアルを含むフレームに追加されるビジュアルである。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpVisual

陰影の元になる Direct3DRMVisual オブジェクト。

lpLight

光源となるIDirect3DRMLightインターフェイス。

px, py, pz

陰影が投影される平面。

nx, ny, nz

陰影が投影される平面の法線。

lplpShadow

呼び出しが成功したとき、陰影ビジュアルへ有効なポインタで初期化されるポインタへのポインタ。


IDirect3DRM::CreateTexture

HRESULT CreateTexture(LPD3DRMIMAGE lpImage,

    LPDIRECT3DRMTEXTURE* lplpD3DRMTexture);

メモリ上のイメージからテクスチャを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpImage

テクスチャのソースを表すD3DRMIMAGE構造体。

lplpD3DRMTexture

呼び出しが成功したときにIDirect3DRMTextureインターフェイスを受け取るポインタへのポインタ。

テクスチャがレンダリングされるたび、Direct3DRMのバッファにコピーされたメモリではなく、イメージに関連付けられたメモリが用いられる。このためイメージは、レンダリングのターゲットとしてもテクスチャとしても使用することができる。


IDirect3DRM::CreateTextureFromSurface

HRESULT CreateTextureFromSurface(LPDIRECTDRAWSURFACE lpDDS,

    LPDIRECT3DRMTEXTURE * lplpD3DRMTexture);

指定された DirectDrawサーフェスからテクスチャを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpDDS

テクスチャを含むDirectDrawSurfaceオブジェクト。

lplpD3DRMTexture

呼び出しが成功したときにIDirect3DRMTextureインターフェイスへのポインタを受け取るアドレス。


IDirect3DRM::CreateUserVisual

HRESULT CreateUserVisual(D3DRMUSERVISUALCALLBACK fn,

    LPVOID  lpArg, LPDIRECT3DRMUSERVISUAL * lplpD3DRMUV);

アプリケーション定義のビジュアル・オブジェクトを作成する。作成後、ビジュアル・オブジェクトをシーンに追加し、アプリケーション定義のハンドラを用いてレンダリングできる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

fn

アプリケーション定義のD3DRMUSERVISUALCALLBACKコールバック関数。

lpArg

コールバック関数に渡される、アプリケーション定義のデータ。

lplpD3DRMUV

呼び出しが成功したときにIDirect3DRMUserVisualインターフェイスを受け取るポインタへのポインタ。


IDirect3DRM::CreateViewport

HRESULT CreateViewport(LPDIRECT3DRMDEVICE lpDev,

    LPDIRECT3DRMFRAME lpCamera, DWORD dwXPos,

    DWORD dwYPos, DWORD dwWidth, DWORD dwHeight,

    LPDIRECT3DRMVIEWPORT* lplpD3DRMViewport);

デバイス上の (dwXPos, dwYPos) から (dwXPos + dwWidth, dwYPos + dwHeight) にビューポートを作成する。位置はデバイス座標で表される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpDev

ビューポートが作成されるデバイス。

lpCamera

ビューの位置と方向を記述するフレームへのポインタ。

dwXPos, dwYPos, dwWidth, および dwHeight

ビューの位置とサイズをデバイス座標で示す。

lplpD3DRMViewport

呼び出しが成功したときにIDirect3DRMViewportインターフェイスを受け取るポインタへのポインタ。

ビューポートは、カメラを含むシーン上にオブジェクトを配置する。ビューの方向と上ベクトルはカメラから取得される。


IDirect3DRM::CreateWrap

HRESULT CreateWrap(D3DRMWRAPTYPE type, LPDIRECT3DRMFRAME lpRef,

    D3DVALUE ox, D3DVALUE oy, D3DVALUE oz, D3DVALUE dx, D3DVALUE dy,

    D3DVALUE dz, D3DVALUE ux, D3DVALUE uy, D3DVALUE uz, D3DVALUE ou,

    D3DVALUE ov, D3DVALUE su, D3DVALUE sv,

    LPDIRECT3DRMWRAP* lplpD3DRMWrap);

面やメッシュにテクスチャ座標を割り当てるために使用するラップ機能を作成する。ラップの原点はベクトル [ox oy oz] 、z軸は [dx dy dz] 、y軸は [ux uy uz] で与えられる。2Dベクトル [ou ov] と [su sv] は、ラップの結果に適用されるテクスチャの原点と縮尺係数を示す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

type

D3DRMWRAPTYPE列挙型メンバのひとつ。

lpRef

ラップのための参照フレームへのポインタ。

ox, oy, oz

ラップの原点。

dx, dy, dz

ラップのz軸。

ux, uy, uz

ラップのy軸。

ou, ov

テクスチャの原点。

su, sv

テクスチャの縮尺係数。

lplpD3DRMWrap

呼び出しが成功したときにIDirect3DRMWrapインターフェイスを受け取るポインタへのポインタ。

参照　IDirect3DRMWrap


IDirect3DRM::EnumerateObjects

HRESULT EnumerateObjects(D3DRMOBJECTCALLBACK func, LPVOID lpArg);

アクティブなDirect3DRMオブジェクトのそれぞれについて、funcパラメータで示されるコールバック関数を呼び出す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

func

各DIRECT3DRMOBJECTオブジェクトについて、アプリケーション定義の引数とともに呼び出される、アプリケーション定義のD3DRMOBJECTCALLBACKコールバック関数。

lpArg

コールバック関数に渡される、アプリケーション定義のデータ。


IDirect3DRM::GetDevices

HRESULT GetDevices(LPDIRECT3DRMDEVICEARRAY* lplpDevArray);

システムで作成されたすべての Direct3DRM デバイスを返す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpDevArray

Direct3DRMデバイスの配列を受け取るポインタ。Direct3DRMDeviceArrayオブジェクトについての情報は、「IDirect3DRMDeviceArrayインターフェイス」を参照すること。


IDirect3DRM::GetNamedObject

HRESULT GetNamedObject(const char * lpName,

    LPDIRECT3DRMOBJECT* lplpD3DRMObject);

名前を指定して、一致するDirect3DRMObject を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpName

検索するオブジェクトの名前。

lplpD3DRMObject

呼び出しが成功したときに、一致したDirect3DRMObjectのポインタへのポインタ。


IDirect3DRM::GetSearchPath

HRESULT GetSearchPath(DWORD * lpdwSize, LPSTR lpszPath);

現在のファイル検索パスを返す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpdwSize

パスの要素数へのポインタ。このパラメータにNULLを指定することはできない。

lpszPath

検索パスを示す、NULLで終わる文字列。このパラメータにNULLを指定すると、lpdwSizeパラメータによって示される場所に必要な文字列のサイズを返す。

参照　IDirect3DRM::SetSearchPath


IDirect3DRM::Load

HRESULT Load(LPVOID lpvObjSource, LPVOID lpvObjID,

    LPIID * lplpGUIDs, DWORD dwcGUIDs, D3DRMLOADOPTIONS d3drmLOFlags,

    D3DRMLOADCALLBACK d3drmLoadProc, LPVOID lpArgLP,

    D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc, LPVOID lpArgLTP,

    LPDIRECT3DRMFRAME lpParentFrame);

オブジェクトをロードする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpvObjSource

ロードするオブジェクトのソースへのポインタ。d3drmLOFlagsパラメータが示すソース・フラグによって、ファイル、リソース、メモリ・ブロック、またはストリームを指定する。

lpvObjID

ロードするオブジェクトの名前または位置へのポインタ。このパラメータは、d3drmLOFlagsパラメータが示す識別子フラグによって解釈される。D3DRMLOAD_BYPOSITIONフラグを指定した場合、このパラメータは、ファイルの中のオブジェクトの順序を示すDWORD値へのポインタである。このパラメータにはNULLを指定することもできる。

lplpGUIDs

ロードするインターフェイス識別子の配列へのポインタ。たとえば、このパラメータがIID_IDirect3DRMMeshBuilderとIID_IDirect3DRMAnimationSetを含む配列のとき、すべてのアニメーション・セットとメッシュ・ビルダー・オブジェクトがロードされる。

dwcGUIDs

lplpGUIDs パラメータで指定された配列の要素数。

d3drmLOFlags

ロード・オプションを示すD3DRMLOADOPTIONS型の値。

d3drmLoadProc

指定されたオブジェクトをシステムが読み出すとき呼び出される、D3DRMLOADCALLBACK コールバック関数。

lpArgLP

D3DRMLOADCALLBACK コールバック関数に渡される、アプリケーション定義のデータ。

d3drmLoadTextureProc

D3DRMLOADTEXTURECALLBACKコールバック関数。これは、特別なフォーマットを必要とするオブジェクトが用いるテクスチャを読み出すときに呼び出される。このパラメータにはNULLを指定することができる。

lpArgLTP

D3DRMLOADTEXTURECALLBACKコールバック関数に渡される、アプリケーション定義のデータのアドレス。

lpParentFrame

親フレーム。このパラメータの情報は、Direct3DRMAnimationSetやDirect3DRMFrameオブジェクトが作成されるときは親にNULLが指定されるため、このパラメータは、これらのオブジェクトをロードする際に有用である。このパラメータにはNULLを指定することができる。


IDirect3DRM::LoadTexture

HRESULT LoadTexture(const char * lpFileName,

    LPDIRECT3DRMTEXTURE* lplpD3DRMTexture);

指定されたファイルからテクスチャをロードする。このテクスチャは、ピクセル当たり8、24、または32ビットのビット数を持つことができる。また、テクスチャはWindowsビットマップ（.bmp）かポータブル・ピクスマップ（.ppm）P6形式のいずれかでなくてはならない。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpFileName

.bmpまたは.ppmファイルの名前を指定する。

lplpD3DRMTexture

呼び出しが成功したときに、有効なDirect3DRMTextureポインタへのポインタ。


IDirect3DRM::LoadTextureFromResource

HRESULT LoadTextureFromResource(HRSRC rs,

    LPDIRECT3DRMTEXTURE * lplpD3DRMTexture);

指定されたリソースからテクスチャをロードする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rs

リソースのハンドル。

lplpD3DRMTexture

呼び出しが成功したときに、有効なDirect3DRMTextureポインタへのポインタ。


IDirect3DRM::SetDefaultTextureColors

HRESULT SetDefaultTextureColors(DWORD dwColors);

Direct3DRMTextureオブジェクトで使用されるデフォルトの色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

dwColors

色の数。

このメソッドは、IDirect3DRM::CreateTextureメソッドの前に呼び出されたときにのみテクスチャの色に反映される。すでに作成されたテクスチャに対しては効果がない。


IDirect3DRM::SetDefaultTextureShades

HRESULT SetDefaultTextureShades(DWORD dwShades);

Direct3DRMTextureオブジェクトで使用されるデフォルトの陰影を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

dwShades

陰影の数。

このメソッドは、IDirect3DRM::CreateTextureメソッドの前に呼び出されたときにのみテクスチャの陰影に反映される。すでに作成されたテクスチャに対しては効果がない。


IDirect3DRM::SetSearchPath

HRESULT SetSearchPath(LPCSTR lpPath);

ファイル検索パスを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpPath

検索パスとして設定するパスを示す、NULLで終わる文字列。

デフォルトの検索パスは環境変数D3DPATHの値から取り出される。この環境変数が設定されていない場合、検索パスは空になる。ファイルをオープンするとき、システムはまずカレントディレクトリを探し、次に検索パス中のすべてのディレクトリをチェックする。

参照　IDirect3DRM::GetSearchPath


IDirect3DRM::Tick

HRESULT Tick(D3DVALUE d3dvalTick);

Direct3DRM システム・ハートビートを行う。このメソッドが呼び出されると、すべての可動フレームの位置は現在の動作属性にしたがって更新され、シーンが現在のデバイスにレンダリングされる。また、関連したコールバック関数が適切なときに呼び出される。このメソッドは、レンダリング・サイクルが完了したときに制御を返す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3dvalTick

IDirect3DRMFrame::SetRotationとIDirect3DRMFrame::SetVelocityメソッドの速度および回転ステップ。

シーンのレンダリングに柔軟性を持たせるため、直接モードの他のメソッドを用いてこのメソッドをインプリメントすることもできる。


IDirect3DRMAnimation

アプリケーションはIDirect3DRMAnimationインターフェイスのメソッドを利用して、位置、向き、ビジュアル・オブジェクトのスケーリング、光源、ビューポートのアニメーションを行うことができる。このセクションは、IDirect3DRMAnimationインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMAnimationとIDirect3DRMAnimationSetインターフェイス」を参照すること。

IDirect3DRMAnimationインターフェイスのメソッドは以下のグループに分類することができる。

キー	AddPositionKey
	AddRotateKey
	AddScaleKey
	DeleteKey
その他	SetFrame
	SetTime
オプション	GetOptions
	SetOptions
IDirect3DRMAnimationインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらにIDirect3DRMAnimationインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMAnimationオブジェクトは、IDirect3DRM::CreateAnimationメソッドの呼び出しによって取得できる。


IDirect3DRMAnimation::AddPositionKey

HRESULT AddPositionKey(D3DVALUE rvTime, D3DVALUE rvX,

    D3DVALUE rvY, D3DVALUE rvZ);

アニメーションに位置キーを加える。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvTime

アニメーションの中で位置キーを設定するときの時間。0を原点とする任意の単位の時間を指定することができる。最後のキーのrvTimeの値が99のとき、rvTimeが49であるキーがアニメーションのちょうど中間である。

rvX, rvY, rvZ

位置。

このメソッドによって移動変換が行われるようになる。変換を含む行列計算については、「3D変換」を参照すること。

参照　IDirect3DRMAnimation::DeleteKey


IDirect3DRMAnimation::AddRotateKey

HRESULT AddRotateKey(D3DVALUE rvTime, D3DRMQUATERNION *rqQuat);

アニメーションに回転キーを追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvTime

アニメーションの中で回転キーを設定するときの時間。0を基準とする任意の単位の時間を指定することができる。最後のキーのrvTimeの値が99のとき、rvTimeが49であるキーがアニメーションのちょうど中間である。

rqQuat

回転を表す4次元行列。

このメソッドによって、回転変換が適用される。変換を含む行列計算については、「3D変換」を参照すること。

参照　IDirect3DRMAnimation::DeleteKey


IDirect3DRMAnimation::AddScaleKey

HRESULT AddScaleKey(D3DVALUE rvTime, D3DVALUE rvX, D3DVALUE rvY,

    D3DVALUE rvZ);

アニメーションにスケール・キーを追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvTime

アニメーションの中でスケール・キーを記憶するときの時間。0を原点とする任意の単位の時間を指定できる。最後のキーのrvTimeの値が99のとき、rvTimeが49であるキーがアニメーションのちょうど中間である。

rvX, rvY, rvZ

縮尺係数。.

このメソッドによって、縮尺変換が適用される。変換を含む行列計算については、「3D変換」を参照すること。

参照　IDirect3DRMAnimation::DeleteKey


IDirect3DRMAnimation::DeleteKey

HRESULT DeleteKey(D3DVALUE rvTime);

キーをアニメーションから削除する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvTime

アニメーションから削除されるキーを識別する時間。


IDirect3DRMAnimation::GetOptions

D3DRMANIMATIONOPTIONS GetOptions();

アニメーション・オプションを取得する。

アニメーション・オプションを示すD3DRMANIMATIONOPTIONS型の値を返す。

参照　IDirect3DRMAnimation::SetOptions


IDirect3DRMAnimation::SetFrame

HRESULT SetFrame(LPDIRECT3DRMFRAME lpD3DRMFrame);

アニメーションにフレームを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMFrame

アニメーションに設定するフレームを指定する変数のアドレス。


IDirect3DRMAnimation::SetOptions

HRESULT SetOptions(D3DRMANIMATIONOPTIONS d3drmanimFlags);

アニメーション・オプションを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmanimFlags

アニメーション・オプション指定するD3DRMANIMATIONOPTIONS型の値のアドレス。

参照　IDirect3DRMAnimation::GetOptions


IDirect3DRMAnimation::SetTime

HRESULT SetTime(D3DVALUE rvTime);

アニメーションに現在の時間を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvTime

アニメーションに設定する新しい現在の時間。0を原点とする任意の単位の時間を指定することができる。最後のキーのrvTimeの値が99のとき、rvTimeが49であるキーがアニメーションのちょうど中間である。


IDirect3DRMAnimationSet

アプリケーションは、Direct3DRMAnimationオブジェクトをグループ化するためにIDirect3DRMAnimationSetインターフェイスのメソッドを使用することができる。このインターフェイスによって複雑なアニメーションの流れを再生することが簡単になる。このセクションは、IDirect3DRMAnimationSetインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMAnimationとIDirect3DRMAnimationSetインターフェイス」を参照すること。

IDirect3DRMAnimationSetインターフェイスのメソッドは、以下のグループに分類することができる。

追加、ロード、削除	AddAnimation
	DeleteAnimation
	Load
時間	SetTime
IDirect3DRMAnimationSetインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMAnimationSetインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMAnimationSetオブジェクトは、IDirect3DRM::CreateAnimationSetメソッドの呼び出しによって取得できる。


IDirect3DRMAnimationSet::AddAnimation

HRESULT AddAnimation(LPDIRECT3DRMANIMATION lpD3DRMAnimation);

アニメーションをアニメーション・セットに追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMAnimation

アニメーション・セットに追加するDirect3DRMAnimationオブジェクト。


IDirect3DRMAnimationSet::DeleteAnimation

HRESULT DeleteAnimation(LPDIRECT3DRMANIMATION lpD3DRMAnimation);

アニメーションをアニメーション・セットから削除する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMAnimation

アニメーション・セットから削除されるDirect3DRMAnimationオブジェクト。


IDirect3DRMAnimationSet::Load

HRESULT Load(LPVOID lpvObjSource, LPVOID lpvObjID,

    D3DRMLOADOPTIONS d3drmLOFlags,

    D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc, LPVOID lpArgLTP,

    LPDIRECT3DRMFRAME lpParentFrame);

アニメーション・セットをロードする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpvObjSource

オブジェクトがロードされるソースへのポインタ。d3drmLOFlagsパラメータが示すソース・フラグによって、ファイル、リソース、メモリ・ブロック、またはストリームを指定する。

lpvObjID

ロードするオブジェクトの名前または位置へのポインタ。このパラメータは、d3drmLOFlagsパラメータが示す識別子フラグによって解釈される。D3DRMLOAD_BYPOSITIONフラグを指定した場合、このパラメータは、ファイルの中のオブジェクトの順序を示すDWORD値へのポインタである。このパラメータにはNULLを指定することもできる。

d3drmLOFlags

ロード・オプションを示すD3DRMLOADOPTIONS型の値。

d3drmLoadTextureProc

D3DRMLOADTEXTURECALLBACKコールバック関数。これは、特別なフォーマットを必要とするオブジェクトが用いるテクスチャを読み出すときに呼び出される。このパラメータにはNULLを指定することができる。

lpArgLTP

D3DRMLOADTEXTURECALLBACKコールバック関数に渡される、アプリケーション定義のデータ。

lpParentFrame

親フレームのアドレス。このパラメータは、アニメーションセットのフレームが、親フレームをNULLとして作成されてしまうっことを防止する 。

デフォルトでは、このメソッドはlpvObjSourceパラメータで指定されるファイルの最初のアニメーション・セットをロードする。


IDirect3DRMAnimationSet::SetTime

HRESULT SetTime(D3DVALUE rvTime);

アニメーションの現在の時間を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvTime

新しい時間


IDirect3DRMDevice

アプリケーションと出力デバイスの相互通信のためにIDirect3DRMDeviceインターフェイスのメソッドを使用する。このセクションは、IDirect3DRMDeviceインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMDeviceとIDirect3DRMDeviceArrayインターフェイス」を参照すること。

IDirect3DRMDeviceインターフェイス・メソッドは、以下のグループに分類することができる。

バッファ・カウント	GetBufferCount
	SetBufferCount
カラー・モデル	GetColorModel
ディザリング	GetDither
	SetDither
初期化	Init
	InitFromClipper
	InitFromD3D
その他	GetDirect3DDevice
	GetHeight
	GetTrianglesDrawn
	GetViewports
	GetWidth
	GetWireframeOptions
	Update
通知	AddUpdateCallback
	DeleteUpdateCallback
レンダリングの品質	GetQuality
	SetQuality
陰影	GetShades
	SetShades
テクスチャの品質	GetTextureQuality
	SetTextureQuality
IDirect3DRMDeviceインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMDeviceインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMDeviceオブジェクトは、IDirect3DRM::CreateDeviceメソッドの呼び出しによって取得される。


IDirect3DRMDevice::AddUpdateCallback

HRESULT AddUpdateCallback(D3DRMUPDATECALLBACK d3drmUpdateProc, LPVOID arg);

デバイスが変更されたときにアプリケーションに通知するコールバック関数を追加する。アプリケーションがIDirect3DRMDevice::Updateを呼び出すと、システムはこのコールバック関数を呼び出す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmUpdateProc

アプリケーション定義のD3DRMUPDATECALLBACKコールバック関数のアドレス。

arg

更新コールバック関数に渡されるアプリケーション定義のデータ。

参照　IDirect3DRMDevice::DeleteUpdateCallback, IDirect3DRMDevice::Update, D3DRMUPDATECALLBACK


IDirect3DRMDevice::DeleteUpdateCallback

HRESULT DeleteUpdateCallback(D3DRMUPDATECALLBACK d3drmUpdateProc,

    LPVOID arg);

IDirect3DRMDevice::AddUpdateCallbackメソッドによって追加された更新コールバック関数を削除する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmUpdateProc

アプリケーション定義のD3DRMUPDATECALLBACKコールバック関数のアドレス。

arg

更新コールバック関数に渡されるプライベートなデータ。

参照　IDirect3DRMDevice::AddUpdateCallback, IDirect3DRMDevice::Update, D3DRMUPDATECALLBACK


IDirect3DRMDevice::GetBufferCount

DWORD GetBufferCount();

IDirect3DRMDevice::SetBufferCountメソッドによって設定された値を取得する。

バッファの数を返す。1はシングル・バッファ、2は2重バッファ、以下3重、4重となる。


IDirect3DRMDevice::GetColorModel

D3DCOLORMODEL GetColorModel();

デバイスのカラー・モデルを取得する。

Direct3D カラー・モデル（RGB あるいはモノクロ）を示す D3DCOLORMODEL列挙型から値を返す。

参照　カラー・モデル


IDirect3DRMDevice::GetDirect3DDevice

HRESULT GetDirect3DDevice(LPDIRECT3DDEVICE * lplpD3DDevice);

直接モードのデバイスへのポインタを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DDevice

直接モードのデバイス・オブジェクトへのポインタで初期化されるポインタのアドレス。


IDirect3DRMDevice::GetDither

BOOL GetDither();

デバイスのディザ・フラグを取得する。

ディザ・フラグがセットされている場合はTRUE、そうでないときはFALSEを返す。

参照　IDirect3DRMDevice::SetDither


IDirect3DRMDevice::GetHeight

DWORD GetHeight();

デバイスの高さをピクセル単位で取得する。

高さを返す。


IDirect3DRMDevice::GetTrianglesDrawn

DWORD GetTrianglesDrawn();

デバイスの作成時からデバイスに描かれたポリゴンの数を取得する。

ポリゴンの数を返す。

ポリゴンの数には、隠面消去されたものも含まれる。ビューポートの外側に配置されたために無視されたポリゴンの数は含まれていない。


IDirect3DRMDevice::GetQuality

D3DRMRENDERQUALITY GetQuality();

デバイスのレンダリング品質を取得する。

D3DRMRENDERQUALITY型で示される列挙型メンバのひとつ以上を返す。

参照　IDirect3DRMDevice::SetQuality


IDirect3DRMDevice::GetShades

DWORD GetShades();

陰影の数を取得する。この数は、使用されている色数で表現される。

陰影の数を返す。

参照　IDirect3DRMDevice::SetShades


IDirect3DRMDevice::GetTextureQuality

D3DRMTEXTUREQUALITY GetTextureQuality();

デバイスの現在のテクスチャ品質パラメータを取得する。テクスチャの品質は、RGBデバイスにのみ適用される。

D3DRMTEXTUREQUALITY列挙型メンバのひとつを返す。

参照　IDirect3DRMDevice::SetTextureQuality


IDirect3DRMDevice::GetViewports

HRESULT GetViewports(LPDIRECT3DRMVIEWPORTARRAY* lplpViewports);

デバイスのビューポートを示す Direct3DRMViewportArrayオブジェクトを構築する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpViewports

呼び出しが成功したときに、有効なDirect3DRMViewportArrayオブジェクトでが入るポインタへのポインタ。


IDirect3DRMDevice::GetWidth

DWORD GetWidth();

デバイスの幅をピクセルで取得する。このメソッドは便利な関数である。

幅を返す。


IDirect3DRMDevice::GetWireframeOptions

DWORD GetWireframeOptions();

指定されたデバイスのワイヤーフレーム・オプションを取得する。

以下の値のビットORが返される。

D3DRMWIREFRAME_CULL

	裏面のフレームは描画されない。

D3DRMWIREFRAME_HIDDENLINE

	ワイヤーフレームでレンダリングされた線が、前面のオブジェクトによって隠される。


IDirect3DRMDevice::Init

HRESULT Init(ULONG width, ULONG height);

Windows上には実装されていない。


IDirect3DRMDevice::InitFromClipper

HRESULT InitFromClipper(LPDIRECTDRAWCLIPPER lpDDClipper,

    LPGUID lpGUID, int width, int height);

指定された DirectDrawClipperオブジェクトからデバイスを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpDDClipper

初期化データとして用いられるDirectDrawClipperオブジェクトのアドレス。

lpGUID

インターフェイス識別子として使用されるグローバル・ユニーク識別子（GUID）。

width, height

デバイスの幅と高さ。


IDirect3DRMDevice::InitFromD3D

HRESULT InitFromD3D(LPDIRECT3D lpD3D, LPDIRECT3DDEVICE lpD3DIMDev);

Direct3D直接モード・オブジェクトと直接モード・デバイスを指定して、直接モード・デバイスを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3D

保持モード・デバイスを初期化するために使うDirect3直接モード・オブジェクトへのポインタ。

lpD3DIMDev

保持モード・デバイスを初期化するために使う直接モード ・デバイス。


IDirect3DRMDevice::SetBufferCount

HRESULT SetBufferCount(DWORD dwCount);

アプリケーションによって現在使用されているバッファの数を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

dwCount

バッファの数を指定する。1はシングル・バッファ、2は2重バッファ、以下3重、4重となる。。デフォルトは1であり、シングル・バッファ・ウィンドウの処理を行う。

2重バッファや3重バッファを使用するアプリケーションは、システムが使用中のバッファの数を通知するためこのメソッドを使用しなくてはならない。これによってシステムは、各フレームについてクリアおよび更新すべきウィンドウの数を計算することができる。

参照　IDirect3DRMDevice::GetBufferCount


IDirect3DRMDevice::SetDither

HRESULT SetDither(BOOL bDither);

デバイスのディザ・フラグを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

bDither

デバイスの新しいディザ・モード。デフォルトはTRUEである。

参照　IDirect3DRMDevice::GetDither


IDirect3DRMDevice::SetQuality

HRESULT SetQuality (D3DRMRENDERQUALITY rqQuality);

デバイスのレンダリング品質を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rqQuality

D3DRMRENDERQUALITY型によって表される列挙型メンバ。デフォルトの設定はD3DRMRENDER_FLATである。

レンダリング品質は、デバイスのレンダリング・サーフェス上で実行されるレンダリングの品質の最大値である。各メッシュは独自の品質を持つが、メッシュに有効な最高品質とは、デバイスに有効な品質と同じである。異なったデバイスには、異なった品質を指定することができる。たとえば、プレビューのためのデバイスは一般に品質が低いが、最終的な表示に用いられるデバイスは、もっと高い品質のものである。

参照　IDirect3DRMDevice::GetQuality


IDirect3DRMDevice::SetShades

HRESULT SetShades(DWORD ulShades);

陰影の度合いを設定する。この数は、使用されている色数で表現される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

ulShades

新しい陰影の度合い。このパラメータは2の累乗でなくてはならない。デフォルトは32である。

参照　IDirect3DRMDevice::GetShades


IDirect3DRMDevice::SetTextureQuality

HRESULT SetTextureQuality(D3DRMTEXTUREQUALITY tqTextureQuality);

デバイスのテクスチャ品質を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

tqTextureQuality

D3DRMTEXTUREQUALITY列挙型のメンバのひとつ。デフォルトはD3DRMTEXTURE_NEARESTである。

参照　IDirect3DRMDevice::GetTextureQuality


IDirect3DRMDevice::Update

HRESULT Update();

ディスプレイにレンダリングされたイメージを複製する。また、デバイス・ドライバにハートビート関数を提供する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

このメソッドが呼び出されるたびに、システムはアプリケーション定義のD3DRMUPDATECALLBACKコールバック関数を呼び出す。コールバック関数を追加するには、IDirect3DRMDevice::AddUpdateCallbackメソッドを使用する。

参照　IDirect3DRMDevice::AddUpdateCallback, D3DRMUPDATECALLBACK


IDirect3DRMFace

アプリケーションは、メッシュ上のひとつのポリゴンと互いにやり取りするためにIDirect3DRMFaceインターフェイスのメソッドを使用する。このセクションは、IDirect3DRMFaceインターフェイス・メソッドのリファレンスである。概念についての概要は、IDirect3DRMFaceとIDirect3DRMFaceArrayインターフェイスを参照すること。

IDirect3DRMFaceインターフェイス・メソッドは、以下のグループに分類することができる。

色	GetColor
	SetColor
	SetColorRGB
マテリアル	GetMaterial
	SetMaterial
テクスチャ	GetTexture
	GetTextureCoordinateIndex
	GetTextureCoordinates
	GetTextureTopology
	SetTexture
	SetTextureCoordinates
	SetTextureTopology
頂点と法線	AddVertex
	AddVertexAndNormalIndexed
	GetNormal
	GetVertex
	GetVertexCount
	GetVertexIndex
	GetVertices
IDirect3DRMFaceインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMFaceインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMFaceオブジェクトは、IDirect3DRM::CreateFaceメソッドの呼び出しによって取得される。


IDirect3DRMFace::AddVertex

HRESULT AddVertex(D3DVALUE x, D3DVALUE y, D3DVALUE z);

Direct3DRMFaceオブジェクトに頂点を追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

x, y, z

新しい頂点位置のx、y、z座標。


IDirect3DRMFace::AddVertexAndNormalIndexed

HRESULT AddVertexAndNormalIndexed(DWORD vertex, DWORD normal);

頂点と法線をDirect3DRMFaceオブジェクトに追加する。このとき、メッシュ・ビルダに含まれる頂点のインデックスと法線のインデックスを使用する。面、頂点、法線は、Direct3DRMMeshBuilderオブジェクトの1部でなくてはならない。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

vertex, normal

追加する頂点と法線のインデックス。


IDirect3DRMFace::GetColor

D3DCOLOR GetColor();

Direct3DRMFaceオブジェクトの色を取得する。

色を返す。

参照　IDirect3DRMFace::SetColor


IDirect3DRMFace::GetMaterial

HRESULT GetMaterial(LPDIRECT3DRMMATERIAL* lplpMaterial);

Direct3DRMFaceオブジェクトのマテリアルを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpMaterial

面に適用されているDirect3DRMMaterialオブジェクトへのポインタを受け取る変数へのポインタ。

参照　IDirect3DRMFace::SetMaterial


IDirect3DRMFace::GetNormal

HRESULT GetNormal(D3DVECTOR *lpNormal);

Direct3DRMFaceオブジェクトの法線を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpNormal

面の法線ベクトルを受け取るD3DVECTOR構造体。


IDirect3DRMFace::GetTexture

HRESULT GetTexture(LPDIRECT3DRMTEXTURE* lplpTexture);

Direct3DRMFaceオブジェクトに適用されたテクスチャを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpTexture

面に適用されたテクスチャへのポインタを受け取る変数。

参照　IDirect3DRMFace::SetTexture


IDirect3DRMFace::GetTextureCoordinateIndex

int GetTextureCoordinateIndex(DWORD dwIndex);

面のメッシュにある頂点のインデックスをテクスチャ座標で取得する。このインデックスは、dwIndexパラメータで指定されたインデックスに対応する。

インデックスを返す。

dwIndex

面にある頂点のインデックス。


IDirect3DRMFace::GetTextureCoordinates

HRESULT GetTextureCoordinates(DWORD index, D3DVALUE *lpU,

    D3DVALUE *lpV);

Direct3DRMFaceオブジェクト中の頂点のテクスチャ座標を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

頂点のインデックス。

lpU, lpV

頂点のテクスチャ座標を受け取る変数。


IDirect3DRMFace::GetTextureTopology

HRESULT GetTextureTopology(BOOL *lpU, BOOL *lpV);

Direct3DRMFaceオブジェクトのテクスチャ位相を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpU, lpV

面の円柱ラップ・フラグにしたがって、設定またはクリアされる変数のアドレス。

参照　IDirect3DRMFace::SetTextureTopology


IDirect3DRMFace::GetVertex

HRESULT GetVertex(DWORD index, D3DVECTOR *lpPosition,

    D3DVECTOR *lpNormal);

Direct3DRMFaceオブジェクト中の頂点の位置と法線を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

頂点のインデックス。

lpPosition, lpNormal

頂点の位置と法線を受け取るD3DVECTOR構造体。


IDirect3DRMFace::GetVertexCount

int GetVertexCount();

Direct3DRMFaceオブジェクトの頂点の数を取得する。

頂点の数を返す。


IDirect3DRMFace::GetVertexIndex

int GetVertexIndex (DWORD dwIndex);

面のメッシュにある頂点のインデックスを取得する。このインデックスはdwIndexパラメータで指定されたインデックスに対応する。

インデックスを返す。

dwIndex

面にある頂点のインデックス。


IDirect3DRMFace::GetVertices

HRESULT GetVertices(DWORD *lpdwVertexCount, D3DVECTOR *lpPosition,

    D3DVECTOR *lpNormal);

Direct3DRMFaceオブジェクト中のそれぞれの頂点について、位置と法線ベクトルを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpdwVertexCount

頂点の数を受け取る変数。このパラメータにNULLを指定することはできない。

lpPosition, lpNormal

頂点の位置と法線ベクトルを受け取るD3DVECTOR構造体の配列へのポインタ。両方ともNULLの場合、このメソッドはlpdwVertexCountパラメータに頂点の数を格納する。


IDirect3DRMFace::SetColor

HRESULT SetColor(D3DCOLOR color);

Direct3DRMFaceオブジェクトの色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

color

設定する色。

参照　IDirect3DRMFace::GetColor


IDirect3DRMFace::SetColorRGB

HRESULT SetColorRGB(D3DVALUE red, D3DVALUE green, D3DVALUE blue);

Direct3DRMFaceオブジェクトの色をR, G, B値で設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

red, green, blue

赤、緑、青の色要素。


IDirect3DRMFace::SetMaterial

HRESULT SetMaterial(LPDIRECT3DRMMATERIAL lpD3DRMMaterial);

Direct3DRMFaceオブジェクトにマテリアルをセットする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMMaterial

マテリアルのアドレス。

参照　IDirect3DRMFace::GetMaterial


IDirect3DRMFace::SetTexture

HRESULT SetTexture(LPDIRECT3DRMTEXTURE lpD3DRMTexture);

Direct3DRMFaceオブジェクトにテクスチャをセットする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMTexture

テクスチャ。

参照　IDirect3DRMFace::GetTexture


IDirect3DRMFace::SetTextureCoordinates

HRESULT SetTextureCoordinates(DWORD vertex, D3DVALUE u, D3DVALUE v);

Direct3DRMFaceオブジェクト中の頂点のテクスチャ座標を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

vertex

設定する頂点のインデックス。たとえば、面が三角形のとき、頂点は0、1、2となる。

u, v

指定された頂点に割り当てるテクスチャ座標。


IDirect3DRMFace::SetTextureTopology

HRESULT SetTextureTopology(BOOL cylU, BOOL cylV);

Direct3DRMFaceオブジェクトにテクスチャ位相を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

cylU, cylV

テクスチャがuとvのどちらの次元で円柱位相を持っているかを示す。

参照　IDirect3DRMFace::GetTextureTopology


IDirect3DRMFrame

アプリケーションは、フレーム（オブジェクトのフレームの参照）と互いにやり取りするためにIDirect3DRMFrameインターフェイスのメソッドを使用する。このセクションは、IDirect3DRMFrameインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMFrameとIDirect3DRMFrameArrayインターフェイス」を参照すること。

IDirect3DRMFrameインターフェイス・メソッドは、以下のグループに分類することができる。

背景	GetSceneBackground
	GetSceneBackgroundDepth
	SetSceneBackground
	SetSceneBackgroundDepth
	SetSceneBackgroundImage
	SetSceneBackgroundRGB
色	GetColor
	SetColor
	SetColorRGB
フォグ	GetSceneFogColor
	GetSceneFogEnable
	GetSceneFogMode
	GetSceneFogParams
	SetSceneFogColor
	SetSceneFogEnable
	SetSceneFogMode
	SetSceneFogParams
階層	AddChild
	DeleteChild
	GetChildren
	GetParent
	GetScene
光源	AddLight
	DeleteLight
	GetLights
ロード	Load
マテリアルモデル	GetMaterialMode
	SetMaterialMode
位置と移動	AddMoveCallback
	AddRotation
	AddScale
	AddTranslation
	DeleteMoveCallback
	GetOrientation
	GetPosition
	GetRotation
	GetVelocity
	LookAt
	Move
	SetOrientation
	SetPosition
	SetRotation
	SetVelocity
分類	GetSortMode
	GetZbufferMode
	SetSortMode
	SetZbufferMode
テクスチャ	GetTexture
	GetTextureTopology
	SetTexture
	SetTextureTopology
変換	AddTransform
	GetTransform
	InverseTransform
	Transform
ビジュアル・オブジェクト	AddVisual
	DeleteVisual
	GetVisuals
IDirect3DRMFrameインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMFrameインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMFrameオブジェクトは、IDirect3DRM::CreateFrameメソッドの呼び出しによって取得される。


IDirect3DRMFrame::AddChild

HRESULT AddChild(LPDIRECT3DRMFRAME lpD3DRMFrameChild);

フレーム階層に子フレームを追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMFrameChild

子フレームとして追加するDirect3DRMFrameオブジェクト。

子フレームとして追加するフレームがすでに親を持っている場合、このメソッドは、新しい親フレームに追加する前に以前の親フレームを取り除く。

オブジェクト変換を維持するため、AddChildメソッドを使用する前にIDirect3DRMFrame::GetTransformメソッドを呼び出し、オブジェクトの変換行列を取得するべきである。そうすれば、フレームを追加した後も変換を付けられる。


IDirect3DRMFrame::AddLight

HRESULT AddLight(LPDIRECT3DRMLIGHT lpD3DRMLight);

フレームに光源を追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMLight

フレームに追加するDirect3DRMLightオブジェクトを示す変数のアドレス。


IDirect3DRMFrame::AddMoveCallback

HRESULT AddMoveCallback(D3DRMFRAMEMOVECALLBACK d3drmFMC, VOID * lpArg);

特別な移動処理のためにコールバック関数を追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmFMC

アプリケーション定義の D3DRMFRAMEMOVECALLBACK コールバック関数。

lpArg

コールバック関数に渡されるアプリケーション定義のデータ。

参照　IDirect3DRMFrame::Move,

IDirect3DRMFrame::DeleteMoveCallback


IDirect3DRMFrame::AddRotation

HRESULT AddRotation(D3DRMCOMBINETYPE rctCombine, D3DVALUE rvX,

    D3DVALUE rvY, D3DVALUE rvZ, D3DVALUE rvTheta);

rvThetaが示すラジアン単位の角度分、(rvX, rvY, rvZ) に対して回転させる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rctCombine

新しい回転を現在の現在のフレーム変換と合成する方法を示す、D3DRMCOMBINETYPE列挙型のメンバ。

rvX, rvY, rvZ

回転軸。

rvTheta

ラジアン単位で示した回転角度。

指定された回転は、このIDirect3DRMFrameインターフェイスによって識別されるフレームの変換行列だけを変更する。このメソッドは、レンダリングのタイミングごとに行列を変更するIDirect3DRMFrame::SetRotationとは異なり、フレーム上のオブジェクトの変更は1回のみ行う。

参照　3D変換, IDirect3DRMFrame::SetRotation


IDirect3DRMFrame::AddScale

HRESULT AddScale(D3DRMCOMBINETYPE rctCombine, D3DVALUE rvX,

    D3DVALUE rvY, D3DVALUE rvZ);

(rvX, rvY, rvZ)によってフレームのローカル変換をスケーリングする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rctCombine

新しい縮尺を現在のフレーム変換と合成する方法を示す、D3DRMCOMBINETYPE列挙型のメンバ。

rvX, rvY, rvZ

x、y、z方向の縮尺係数を定義する。

指定された変換は、このIDirect3DRMFrameインターフェイスによって識別されるフレームの変換行列だけを変更する。

参照　3D変換


IDirect3DRMFrame::AddTransform

HRESULT AddTransform(D3DRMCOMBINETYPE rctCombine,

    D3DRMMATRIX4D rmMatrix);

rctCombineパラメータの値に従い、フレームのローカル座標をアフィン変換する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rctCombine

新しい変換を現在の変換と合成する方法を示す、D3DRMCOMBINETYPE列挙型のメンバ。

rmMatrix

合成される変換行列を定義するD3DRMMATRIX4D配列のメンバ。

変換には4行4列の行列を指定するが、アフィン変換を利用するため、最後の列は[0 0 0 1]の転置行列でなくてはならない。

指定された変換は、このIDirect3DRMFrameインターフェイスによって識別されるフレームの変換行列だけを変更する。

参照　3D変換


IDirect3DRMFrame::AddTranslation

HRESULT AddTranslation(D3DRMCOMBINETYPE rctCombine, D3DVALUE rvX,

    D3DVALUE rvY, D3DVALUE rvZ);

(rvX, rvY, rvZ)による変換をフレームのローカル座標系に追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rctCombine

新しい変換を現在の変換と合成する方法を示す、D3DRMCOMBINETYPE列挙型のメンバ。

rvX, rvY, rvZ

x、y、z方向の位置変更を定義する。

指定された変換は、このIDirect3DRMFrameインターフェイスによって識別されるフレームの変換行列だけを変更する。

参照　3D変換


IDirect3DRMFrame::AddVisual

HRESULT AddVisual(LPDIRECT3DRMVISUAL lpD3DRMVisual);

フレームにビジュアル・オブジェクトを追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMVisual

フレームに追加するDirect3DRMVisualオブジェクトを示す変数。

ビジュアル・オブジェクトは、メッシュとテクスチャを含む。フレームにビジュアル・オブジェクトが追加されると、フレームがビューに存在すればオブジェクトは可視状態となる。ビジュアル・オブジェクトはフレームから参照される。


IDirect3DRMFrame::DeleteChild

HRESULT DeleteChild(LPDIRECT3DRMFRAME lpChild);

フレームを階層から削除する。フレームが参照されていなければ、すべての子フレーム、光源、メッシュとともに破棄される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpChild

子フレームとして使われているDirect3DRMFrameオブジェクトを示す変数。

参照　階層


IDirect3DRMFrame::DeleteLight

HRESULT DeleteLight(LPDIRECT3DRMLIGHT lpD3DRMLight);

光源をフレームから削除し、光源が参照されていなければ破棄する。フレームから光源が取り除かれると、その光源は、フレームがあったシーン上のメッシュに効果を与えなくなる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMLight

削除するDirect3DRMLightオブジェクトを示す変数。


IDirect3DRMFrame::DeleteMoveCallback

HRESULT DeleteMoveCallback(D3DRMFRAMEMOVECALLBACK d3drmFMC,

    VOID * lpArg);

特別な移動処理を実行したコールバック関数を削除する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmFMC

アプリケーション定義のD3DRMFRAMEMOVECALLBACKコールバック関数。

lpArg

コールバック関数に渡されたアプリケーション定義のデータへのポインタ。

参照　IDirect3DRMFrame::AddMoveCallback, IDirect3DRMFrame::Move


IDirect3DRMFrame::DeleteVisual

HRESULT DeleteVisual(LPDIRECT3DRMVISUAL lpD3DRMVisual);

フレームからビジュアル・オブジェクトを削除する。ビジュアル・オブジェクトが参照されていなければ破棄する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMVisual

削除するDirect3DRMVisualオブジェクトを示す変数のアドレス。


IDirect3DRMFrame::GetChildren

HRESULT GetChildren(LPDIRECT3DRMFRAMEARRAY* lplpChildren);

Direct3DRMFrameArrayオブジェクトの形式で子フレームのリストを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpChildren

呼び出しが成功したときに、有効なDirect3DRMFrameArrayポインタが入るポインタのアドレス。

参照　Direct3DRMFrameArray, 階層


IDirect3DRMFrame::GetColor

D3DCOLOR GetColor();

フレームの色を取得する。

Direct3DRMFrameオブジェクトの色を返す。

参照　IDirect3DRMFrame::SetColor


IDirect3DRMFrame::GetLights

HRESULT GetLights(LPDIRECT3DRMLIGHTARRAY* lplpLights);

Direct3DRMLightArrayオブジェクトの形式でフレームの光源リストを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「 Direct3D保持モードの返値」を参照すること。

lplpLights

呼び出しが成功したときに、有効なDirect3DRMLightArrayポインタが入るポインタのアドレス。

参照　IDirect3DRMLightArray


IDirect3DRMFrame::GetMaterialMode

D3DRMMATERIALMODE GetMaterialMode();

フレームのマテリアルモードを取得する。

現在のマテリアルモードを示すD3DRMMATERIALMODE列挙型メンバのひとつを返す。

参照　IDirect3DRMFrame::SetMaterialMode


IDirect3DRMFrame::GetOrientation

HRESULT GetOrientation(LPDIRECT3DRMFRAME lpRef, LPD3DVECTOR lprvDir,

    LPD3DVECTOR lprvUp);

フレームの向きを取得する。この方向は、指定された参照フレームから相対的に表される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpRef

参照として用いられるDirect3DRMFrameオブジェクトを示す変数。

lprvDir, lprvUp

フレームのz軸とy軸の方向を受け取るD3DVECTOR構造体。

参照　IDirect3DRMFrame::SetOrientation


IDirect3DRMFrame::GetParent

HRESULT GetParent(LPDIRECT3DRMFRAME* lplpParent);

現在のフレームの親フレームを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpParent

フレームの親を示すDirect3DRMFrameオブジェクトへのポインタを受け取るポインタのアドレス。現在のフレームが親フレームの場合、このポインタにはNULLが設定される。


IDirect3DRMFrame::GetPosition

HRESULT GetPosition(LPDIRECT3DRMFRAME lpRef, LPD3DVECTOR lprvPos);

指定された参照フレームからの、フレームの相対位置を取得する（たとえば、このメソッドはフレームの参照からの距離を取得する）。距離は、一次元のサイズとしてではなく、ベクトルとしてlprvPosパラメータに格納される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpRef

参照として用いられるDirect3DRMFrameオブジェクトを示す変数。

lprvPos

フレームの位置を受け取るD3DVECTOR構造体。

参照　IDirect3DRMFrame::SetPosition


IDirect3DRMFrame::GetRotation

HRESULT GetRotation(LPDIRECT3DRMFRAME lpRef, LPD3DVECTOR lprvAxis,

    LPD3DVALUE lprvTheta);

フレームの回転を取得する。回転は、指定された参照フレームから相対的に表される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpRef

参照として用いられるDirect3DRMFrameオブジェクトを示す変数。

lprvAxis

フレームの回転軸を受け取るD3DVECTOR構造体。

lprvTheta

フレームの回転をラジアン単位で受け取る変数。

参照　IDirect3DRMFrame::SetRotation, 変換


IDirect3DRMFrame::GetScene

HRESULT GetScene(LPDIRECT3DRMFRAME* lplpRoot);

指定されたフレームを含む階層のルート・フレームを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpRoot

シーンの最上位フレームを示すDirect3DRMFrameオブジェクトを受け取るポインタへのポインタ。


IDirect3DRMFrame::GetSceneBackground

D3DCOLOR GetSceneBackground();

シーンの背景色を取得する。

色を返す。


IDirect3DRMFrame::GetSceneBackgroundDepth

HRESULT GetSceneBackgroundDepth(

    LPDIRECTDRAWSURFACE * lplpDDSurface);

シーンの現在の背景深度バッファを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpDDSurface

現在の背景深度バッファを示すDirectDrawサーフェスのアドレスが入るポインタのアドレス。

参照　IDirect3DRMFrame::SetSceneBackgroundDepth


IDirect3DRMFrame::GetSceneFogColor

D3DCOLOR GetSceneFogColor();

シーンのフォグの色を取得する。

フォグの色を返す。


IDirect3DRMFrame::GetSceneFogEnable

BOOL GetSceneFogEnable();

このシーンで、現在フォグが有効であるかどうかを返す。

フォグが有効であればTRUE、そうでなければFALSEを返す。


IDirect3DRMFrame::GetSceneFogMode

D3DRMFOGMODE GetSceneFogMode();

このシーンの現在のフォグ・モードを返す。

現在のフォグ・モードを示すD3DRMFOGMODE列挙型のメンバのひとつを返す。


IDirect3DRMFrame::GetSceneFogParams

HRESULT GetSceneFogParams(D3DVALUE * lprvStart, D3DVALUE * lprvEnd,

    D3DVALUE * lprvDensity);

このシーンの現在のフォグ・パラメータを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lprvStart, lprvEnd, lprvDensity

フォグの始点、終点、密度の値を受け取る変数。


IDirect3DRMFrame::GetSortMode

D3DRMSORTMODE GetSortMode();

子フレームを処理するために使われる分類モードを取得する。

分類モードを示すD3DRMSORTMODE列挙型のメンバを返す。

参照　IDirect3DRMFrame::SetSortMode


IDirect3DRMFrame::GetTexture

HRESULT GetTexture(LPDIRECT3DRMTEXTURE* lplpTexture);

指定されたフレームのテクスチャを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpTexture

フレームのテクスチャを示すDirect3DRMTextureオブジェクトを受け取るポインタへのポインタ。

参照　IDirect3DRMFrame::SetTexture


IDirect3DRMFrame::GetTextureTopology

HRESULT GetTextureTopology(BOOL * lpbWrap_u, BOOL * lpbWrap_v);

指定されたフレーム上のオブジェクトにマップされるときの、テクスチャの位相特性を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpbWrap_u, lpbWrap_v

結果を受け取る変数。テクスチャがu方向やv方向にマップされるとき、それぞれの変数にTRUEが設定される。

参照　IDirect3DRMFrame::SetTextureTopology


IDirect3DRMFrame::GetTransform

HRESULT GetTransform(D3DRMMATRIX4D rmMatrix);

4行4列のアフィン行列としてフレームのローカル変換を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rmMatrix

フレーム変換を取得するD3DRMMATRIX4D配列。このパラメータは配列を示すので、実際にはアドレスである。

参照　3D変換


IDirect3DRMFrame::GetVelocity

HRESULT GetVelocity(LPDIRECT3DRMFRAME lpRef, LPD3DVECTOR lprvVel,

    BOOL fRotVel);

指定された参照フレームに対する、フレームの相対速度を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpRef

参照として用いられるDirect3DRMFrameオブジェクトを示す変数。

lprvVel

フレームの速度を受け取るD3DVECTOR構造体のアドレス。

fRotVel

一次元の速度を取得する場合オブジェクトの回転速度が考慮に入れられるかどうかを示すフラグ。このパラメータにTRUEを指定するとオブジェクトの回転速度が計算に含められる。

参照　IDirect3DRMFrame::SetVelocity


IDirect3DRMFrame::GetVisuals

HRESULT GetVisuals(LPDIRECT3DRMVISUALARRAY* lplpVisuals);

フレーム上のビジュアルのリストを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpVisuals

呼び出しが成功したときに、有効なDirect3DRMVisualArray ポインタで初期化されるポインタのアドレス。


IDirect3DRMFrame::GetZbufferMode

D3DRMZBUFFERMODE GetZbufferMode();

Zバッファ・モードを取得する。すなわち、Zバッファリングが有効か無効かを示す。

D3DRMZBUFFERMODE列挙型のメンバのひとつを返す。

参照　IDirect3DRMFrame::SetZbufferMode


IDirect3DRMFrame::InverseTransform

HRESULT InverseTransform(D3DVECTOR *lprvDst, D3DVECTOR *lprvSrc);

lprvSrcパラメータが示すベクトルをワールド座標からモデル座標に変換し、結果をlprvDstパラメータに返す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lprvDst

変換結果を受け取るD3DVECTOR構造体。

lprvSrc

変換のソースとなるD3DVECTOR構造体。

参照　IDirect3DRMFrame::Transform, 3D変換


IDirect3DRMFrame::Load

HRESULT Load(LPVOID lpvObjSource, LPVOID lpvObjID,

    D3DRMLOADOPTIONS d3drmLOFlags,

    D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc, LPVOID lpArgLTP);

Direct3DRMFrameオブジェクトをロードする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpvObjSource

オブジェクトがロードされるソース。d3drmLOFlagsパラメータが示すソース・フラグによって、ファイル、リソース、メモリ・ブロック、またはストリームを指定する。

lpvObjID

ロードするオブジェクトの名前または位置。このパラメータはd3drmLOFlagsパラメータが示す識別子フラグによって解釈される。D3DRMLOAD_BYPOSITIONフラグを指定した場合、このパラメータはファイルの中のオブジェクトの順序を示すDWORD値へのポインタである。このパラメータにはNULLを指定することもできる。

d3drmLOFlags

ロード・オプションを示すD3DRMLOADOPTIONS型の値。

d3drmLoadTextureProc

D3DRMLOADTEXTURECALLBACK コールバック関数。これは、特別なフォーマットを必要とするオブジェクトが用いるテクスチャを読み出すときに呼び出される。このパラメータにはNULLを指定することができる。

lpArgLTP

D3DRMLOADTEXTURECALLBACKコールバック関数に渡される、アプリケーション定義のデータ。

デフォルトでは、このメソッドは lpvObjSource パラメータで指定されたファイルの中の最初のフレーム階層をロードする。このメソッドを呼び出すフレームは、新しいフレーム階層の親になる。


IDirect3DRMFrame::LookAt

HRESULT LookAt(LPDIRECT3DRMFRAME lpTarget, LPDIRECT3DRMFRAME lpRef,

    D3DRMFRAMECONSTRAINT rfcConstraint);

指定された参照フレームと比較して、フレームを目標フレームに向け、与えられた条件で回転をロックする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpTarget, lpRef

目標および参照として用いられるDirect3DRMFrameオブジェクトを示す変数。

rfcConstraint

回転軸を指定するD3DRMFRAMECONSTRAINT列挙型のメンバ。


IDirect3DRMFrame::Move

HRESULT Move(D3DVALUE delta);

与えられた階層中のすべてのフレームに回転と速度を適用する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

delta

変更する速度と回転の量。


IDirect3DRMFrame::SetColor

HRESULT SetColor(D3DCOLOR rcColor);

フレームの色を設定する。D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEのとき、フレーム上のメッシュにこの色が使用される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rcColor

フレームの新しい色。

参照　IDirect3DRMFrame::GetColor, IDirect3DRMFrame::SetMaterialMode


IDirect3DRMFrame::SetColorRGB

HRESULT SetColorRGB(D3DVALUE rvRed, D3DVALUE rvGreen,

    D3DVALUE rvBlue);

フレームの色を設定する。D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEのとき、フレーム上のメッシュにこの色が使用される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvRed, rvGreen, rvBlue

フレームの新しい色。各色要素は0から1の範囲になくてはならない。

参照　IDirect3DRMFrame::SetMaterialMode


IDirect3DRMFrame::SetMaterialMode

HRESULT SetMaterialMode(D3DRMMATERIALMODE rmmMode);

フレームのマテリアルモードを設定する。マテリアルモードは、フレームにレンダリングされるビジュアルのマテリアル情報のソースを決定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rmmMode

D3DRMMATERIALMODE列挙型メンバーのひとつ。

参照　IDirect3DRMFrame::GetMaterialMode


IDirect3DRMFrame::SetOrientation

HRESULT SetOrientation(LPDIRECT3DRMFRAME lpRef, D3DVALUE rvDx,

    D3DVALUE rvDy, D3DVALUE rvDz, D3DVALUE rvUx, D3DVALUE rvUy,

    D3DVALUE rvUz);

フレームを並べる。z方向が方向ベクトル[rvDx, rvDy, rvDz]に沿い、y方向がベクトル[rvUx, rvUy, rvUz]に並ぶようにする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpRef

参照として用いられるDirect3DRMFrame オブジェクトを示す変数。

rvDx, rvDy, rvDz

フレームの新しいz軸。

rvUx, rvUy, rvUz

フレームの新しいy軸。

デフォルトでは、フレームは方向ベクトル[0, 0, 1]と上ベクトル[0, 1, 0]を持っている。

[rvUx, rvUy, rvUz]が[rvDx, rvDy, rvDz]と平行な場合は、D3DRMERR_BADVALUEエラー値が返される。それ以外の場合は、渡された[rvUx, rvUy, rvUz]ベクトルが[rvDx, rvDy, rvDz]に垂直な平面上に投影される。

参照　IDirect3DRMFrame::GetOrientation


IDirect3DRMFrame::SetPosition

HRESULT SetPosition(LPDIRECT3DRMFRAME lpRef, D3DVALUE rvX, D3DVALUE rvY,

    D3DVALUE rvZ);

参照フレームからのフレームの相対位置を設定する。フレームは、参照フレームからの距離が[rvX, rvY, rvZ]の場所に配置される。親フレームの中に子フレームが作成されるときは、親フレームの[0, 0, 0]の位置に置かれる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpRef

参照として用いられるDirect3DRMFrameオブジェクトを示す変数のアドレス。

rvX, rvY, rvZ

フレームの新しい位置。

参照　IDirect3DRMFrame::GetPosition


IDirect3DRMFrame::SetRotation

HRESULT SetRotation(LPDIRECT3DRMFRAME lpRef, D3DVALUE rvX, D3DVALUE rvY,

    D3DVALUE rvZ, D3DVALUE rvTheta);

フレームの回転軸と回転角度を設定する。この設定はIDirect3DRM::Tickまたは IDirect3DRMFrame::Moveメソッドが呼び出されるたびに適用される。方向ベクトル[rvX, rvY, rvZ]は、参照フレームで定義される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpRef

参照として用いられるDirect3DRMFrameオブジェクトを示す変数。

rvX, rvY, rvZ

回転軸となるベクトル。

rvTheta

ラジアン単位の回転角度。

フレーム上のオブジェクトを1回しか変更しないIDirect3DRMFrame::AddRotationメソッドと異なり、このメソッドは、指定された回転によってレンダリングのタイミングごとに変換行列を変更する。

参照　IDirect3DRMFrame::AddRotation, IDirect3DRMFrame::GetRotation


IDirect3DRMFrame::SetSceneBackground

HRESULT SetSceneBackground(D3DCOLOR rcColor);

シーンの背景色をセットする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rcColor

背景の新しい色。


IDirect3DRMFrame::SetSceneBackgroundDepth

HRESULT SetSceneBackgroundDepth(LPDIRECTDRAWSURFACE lpImage);

シーンの背景深度バッファを指定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpImage

シーンの新しい背景深度を格納するDirectDrawサーフェス。

イメージの深度は16でなくてはならない。イメージとビューポートのサイズが異なっている場合、まず、イメージがスケーリングされる。背景深度バッファのアニメーションで最高のパフォーマンスを得るためには、イメージのサイズがビューポートと同じでなくてはならない。これによって、余分なオーバーヘッドなしに、深度バッファをイメージ・メモリから直接更新することができる。

参照　IDirect3DRMFrame::GetSceneBackgroundDepth


IDirect3DRMFrame::SetSceneBackgroundImage

HRESULT SetSceneBackgroundImage(LPDIRECT3DRMTEXTURE lpTexture);

シーンの背景イメージを指定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpTexture

新しい背景シーンを含むDirect3DRMTextureオブジェクト。

イメージのサイズや色数がビューポートと異なっていると、まず、イメージがスケーリングされるか、適当な色数に変換される。背景のアニメーションで最高のパフォーマンスを得るためには、イメージのサイズと色数がビューポートと同じでなくてはならない。これによって、余分なオーバーヘッドなしに、背景をイメージ・メモリから直接レンダリングすることができる。


IDirect3DRMFrame::SetSceneBackgroundRGB

HRESULT SetSceneBackgroundRGB(D3DVALUE rvRed, D3DVALUE rvGreen,

    D3DVALUE rvBlue);

シーンの背景色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvRed, rvGreen, rvBlue

背景の新しい色。


IDirect3DRMFrame::SetSceneFogColor

HRESULT SetSceneFogColor(D3DCOLOR rcColor);

シーンのフォグの色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rcColor

フォグの新しい色。


IDirect3DRMFrame::SetSceneFogEnable

HRESULT SetSceneFogEnable(BOOL bEnable);

フォグを有効または無効にする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

bEnable

フォグの新しい状態。


IDirect3DRMFrame::SetSceneFogMode

HRESULT SetSceneFogMode(D3DRMFOGMODE rfMode);

フォグ・モードを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rfMode

新しいフォグ・モードを示すD3DRMFOGMODE列挙型のメンバのひとつ。

参照　IDirect3DRMFrame::SetSceneFogParams


IDirect3DRMFrame::SetSceneFogParams

HRESULT SetSceneFogParams(D3DVALUE rvStart, D3DVALUE rvEnd,

    D3DVALUE rvDensity);

このシーンの現在のフォグ・パラメータを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvStart, rvEnd

リニアフォグ・モードでの、フォグの開始と終了位置。これらの設定は、最初にフォグ効果が現れるカメラからの距離と、フォグが最大密度に達する距離を決定する。

rvDensity

指数フォグ・モードでのフォグの密度。この値は０から１までの範囲でなくてはならない。

参照　D3DRMFOGMODE, IDirect3DRMFrame::SetSceneFogMode


IDirect3DRMFrame::SetSortMode

HRESULT SetSortMode(D3DRMSORTMODE d3drmSM);

子フレームを処理するために使われる分類モードをセットする。このメソッドは、隠面除去のアルゴリズムを変更するために用いることができる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmSM

分類モードを指定するD3DRMSORTMODE列挙型のメンバのひとつ。デフォルト値はD3DRMSORT_FROMPARENTである。

参照	IDirect3DRMFrame::GetSortMode


IDirect3DRMFrame::SetTexture

HRESULT SetTexture(LPDIRECT3DRMTEXTURE lpD3DRMTexture);

フレームのテクスチャを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMTexture

使用されるDirect3DRMTextureオブジェクトを示す変数。

D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEのとき、テクスチャはフレーム上のメッシュのために使用される。フレームのテクスチャを無効にするには、テクスチャにNULLを指定する。

参照　IDirect3DRMFrame::GetTexture, IDirect3DRMFrame::SetMaterialMode


IDirect3DRMFrame::SetTextureTopology

HRESULT SetTextureTopology(BOOL bWrap_u, BOOL bWrap_v);

フレーム上のオブジェクトの、テクスチャ座標の位相特性を定義する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

bWrap_u, bWrap_v

設定する値を示す引数。ｕ方向またはｖ方向にテクスチャをマップするとき、対応する引数にTRUEを設定する。

参照　IDirect3DRMFrame::GetTextureTopology


IDirect3DRMFrame::SetVelocity

HRESULT SetVelocity(LPDIRECT3DRMFRAME lpRef, D3DVALUE rvX,

    D3DVALUE rvY, D3DVALUE rvZ, BOOL fRotVel);

指定されたフレームの、参照フレームからの相対速度を設定する。IDirect3DRM::TickまたはIDirect3DRMFrame::Moveメソッドの呼び出しが成功するたび、フレームはベクトル[rvX, rvY, rvZ]によって移動される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpRef

参照として用いられるDirect3DRMFrameオブジェクトを示す変数。

rvX, rvY, および rvZ

フレームの新しい速度。

fRotVel

一次元の速度を設定する場合、オブジェクトの回転速度を考慮に入れるかどうかを指定するフラグ。このパラメータがTRUEのとき、オブジェクトの回転速度が計算に含められる 。

参照　IDirect3DRMFrame::GetVelocity


IDirect3DRMFrame::SetZbufferMode

HRESULT SetZbufferMode(D3DRMZBUFFERMODE d3drmZBM);

Zバッファ・モードを設定する。すなわち、Zバッファリングを有効または無効にする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmZBM

Zバッファ・モードを指定するD3DRMZBUFFERMODE列挙型のメンバのひとつ。デフォルト値はD3DRMZBUFFER_FROMPARENTである。

参照　IDirect3DRMFrame::GetZbufferMode


IDirect3DRMFrame::Transform

HRESULT Transform(D3DVECTOR *lpd3dVDst, D3DVECTOR *lpd3dVSrc);

lpd3dVSrcパラメータが示すベクトルをモデル座標からワールド座標に変換し、結果をlpd3dVDstパラメータに返す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpd3dVDst

変換処理の結果を受け取るD3DVECTOR構造体。

lpd3dVSrc

変換処理されるD3DVECTOR構造体。

参照　IDirect3DRMFrame::InverseTransform, 3D変換


IDirect3DRMLight

アプリケーションは、光源と互いにやり取りするためにIDirect3DRMLightインターフェイスのメソッドを使用する。このセクションは、IDirect3DRMLightインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMLightとIDirect3DRMLightArrayインターフェイス」を参照すること。

IDirect3DRMLightインターフェイス・メソッドは、以下のグループに分類することができる。

減衰	GetConstantAttenuation
	GetLinearAttenuation
	GetQuadraticAttenuation
	SetConstantAttenuation
	SetLinearAttenuation
	SetQuadraticAttenuation
色	GetColor
	SetColor
	SetColorRGB
有効範囲	GetEnableFrame
	SetEnableFrame
光源タイプ	GetType
	SetType
明度	GetRange
	SetRange
スポット光源・オプション	GetPenumbra
	GetUmbra
	SetPenumbra
	SetUmbra
IDirect3DRMLightインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMLightインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMLightオブジェクトは、IDirect3DRM::CreateLightおよびIDirect3DRM::CreateLightRGBメソッドの呼び出しによって取得される。


IDirect3DRMLight::GetColor

D3DCOLOR GetColor();

現在のDirect3DRMLightオブジェクトの色を取得する。

色を返す。

参照　IDirect3DRMLight::SetColor


IDirect3DRMLight::GetConstantAttenuation

D3DVALUE GetConstantAttenuation();

Direct3DRMLightオブジェクトの減衰定数を取得する。

減衰定数を返す。

減衰定数の値は反比例的に光強度に影響を与える。たとえば、減衰定数が2のとき、光の強度は半分に低下する。

参照　IDirect3DRMLight::SetConstantAttenuation


IDirect3DRMLight::GetEnableFrame

HRESULT GetEnableFrame(LPDIRECT3DRMFRAME * lplpEnableFrame);

光源を設定するのに有効なフレームを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpEnableFrame

現在のDirect3DRMFrameオブジェクトの有効なフレームを受け取るポインタへのポインタ。

参照　IDirect3DRMLight::SetEnableFrame


IDirect3DRMLight::GetLinearAttenuation

D3DVALUE GetLinearAttenuation();

光源の1次減衰係数を取得する。

1次減衰係数を返す。

参照　IDirect3DRMLight::SetLinearAttenuation


IDirect3DRMLight::GetPenumbra

D3DVALUE GetPenumbra();

スポットライトの暗影部の角度を取得する。

暗影部の値を返す。

参照　IDirect3DRMLight::SetPenumbra


IDirect3DRMLight::GetQuadraticAttenuation

D3DVALUE GetQuadraticAttenuation();

光源の2次減衰係数を取得する。

2次減衰係数を返す。

参照　IDirect3DRMLight::SetQuadraticAttenuation


IDirect3DRMLight::GetRange

D3DVALUE GetRange();

現在のDirect3DRMLightオブジェクトの範囲を取得する。

範囲を示す値を返す。

参照　IDirect3DRMLight::SetRange


IDirect3DRMLight::GetType

D3DRMLIGHTTYPE GetType();

指定されたの光源のタイプを取得する。

D3DRMLIGHTTYPE列挙型のメンバのひとつを返す。

参照　IDirect3DRMLight::SetType


IDirect3DRMLight::GetUmbra

D3DVALUE GetUmbra();

Direct3DRMLightオブジェクトの明部の角度を取得する。

明部の角度を返す。

参照　IDirect3DRMLight::SetUmbra


IDirect3DRMLight::SetColor

HRESULT SetColor(D3DCOLOR rcColor);

指定された光源の色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rcColor

光源の新しい色。

参照　IDirect3DRMLight::GetColor


IDirect3DRMLight::SetColorRGB

HRESULT SetColorRGB(D3DVALUE rvRed, D3DVALUE rvGreen,

    D3DVALUE rvBlue);

指定された光源の色をR, B, Gそれぞれの値で設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvRed, rvGreen, rvBlue

光源の新しい色。


IDirect3DRMLight::SetConstantAttenuation

HRESULT SetConstantAttenuation(D3DVALUE rvAtt);

光源の減衰係数を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvAtt

新しい減衰係数。

減衰定数の値は反比的に光強度に影響を与える。たとえば、減衰定数が2のとき、光の強度は半分に低下する。

参照　IDirect3DRMLight::GetConstantAttenuation


IDirect3DRMLight::SetEnableFrame

HRESULT SetEnableFrame(LPDIRECT3DRMFRAME lpEnableFrame);

光源の有効フレームを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpEnableFrame

光源の有効フレームへのポインタ。このフレームには親フレームと同様の光源となる。

参照　IDirect3DRMLight::GetEnableFrame


IDirect3DRMLight::SetLinearAttenuation

HRESULT SetLinearAttenuation(D3DVALUE rvAtt);

光源の1次減衰係数を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvAtt

新しい減衰係数。

参照　IDirect3DRMLight::GetLinearAttenuation


IDirect3DRMLight::SetPenumbra

HRESULT SetPenumbra(D3DVALUE rvAngle);

円錐の暗影部の角度をセットする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvAngle

新しい暗影部の角度。この角度は暗部の角度より大きいか、等しくなくてはいけない。暗影部の角度を明部の角度よりも小さく設定した場合、暗影部は明部と同じ角度になる。デフォルト値は0.5ラジアンである。

参照　IDirect3DRMLight::GetPenumbra


IDirect3DRMLight::SetQuadraticAttenuation

HRESULT SetQuadraticAttenuation(D3DVALUE rvAtt);

光源の2次減衰係数を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvAtt

新しい減衰係数。

参照　IDirect3DRMLight::GetQuadraticAttenuation


IDirect3DRMLight::SetRange

HRESULT SetRange(D3DVALUE rvRange);

光源の範囲をセットする。光源は、範囲の中にあるオブジェクトにのみ効果を与える。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvRange

新しい範囲。デフォルト値は256である。

参照　IDirect3DRMLight::GetRange


IDirect3DRMLight::SetType

HRESULT SetType(D3DRMLIGHTTYPE d3drmtType);

光源のタイプを変更する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmtType

新しい光源タイプをD3DRMLIGHTTYPE列挙型のメンバのひとつで指定する。

参照　IDirect3DRMLight::GetType


IDirect3DRMLight::SetUmbra

HRESULT SetUmbra(D3DVALUE rvAngle);

円錐の明部の角度を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvAngle

新しい明部の角度。この角度は、暗影部の角度よりも小さいか、等しくなくてはいけない。明部の角度を暗影部の角度より大きく設定した場合、明部は暗影部と同じ角度となる。デフォルト値は0.4ラジアンである。

参照　IDirect3DRMLight::GetUmbra


IDirect3DRMMaterial

アプリケーションは、マテリアルオブジェクトと互いにやり取りするためにIDirect3DRMMaterialインターフェイスのメソッドを使用する。このセクションは、IDirect3DRMMaterialインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMMaterialインターフェイス」を参照すること。

IDirect3DRMMaterialインターフェイス・メソッドは、以下のグループに分類することができる。

放射	GetEmissive
	SetEmissive
反射指数の強度	GetPower
	SetPower
反射	GetSpecular
	SetSpecular
IDirect3DRMMaterialインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMMaterialインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMMaterialオブジェクトは、IDirect3DRM::CreateMaterialメソッドの呼び出しによって取得される。


IDirect3DRMMaterial::GetEmissive

HRESULT GetEmissive(D3DVALUE *lpr, D3DVALUE *lpg, D3DVALUE *lpb);

マテリアルの放射特性の設定を取得する。この特性の設定は、色とオブジェクトが発散する光の強度を示す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpr, lpg, lpb

メソッドが制御を返すとき、放射の赤、緑、青の色要素を受け取るアドレス。

参照　IDirect3DRMMaterial::SetEmissive


IDirect3DRMMaterial::GetPower

D3DVALUE GetPower();

指定されたマテリアルでの反射指数のパワーを取得する。

反射指数のパワーを示す値を返す。

参照　IDirect3DRMMaterial::SetPower


IDirect3DRMMaterial::GetSpecular

HRESULT GetSpecular(D3DVALUE *lpr, D3DVALUE *lpg, D3DVALUE *lpb);

マテリアルの反射ハイライトの色を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpr, lpg, lpb

メソッドが制御を返すとき、反射ハイライトの赤、緑、青の色要素を受け取るアドレス。

参照　IDirect3DRMMaterial::SetSpecular


IDirect3DRMMaterial::SetEmissive

HRESULT SetEmissive(D3DVALUE r, D3DVALUE g, D3DVALUE b);

マテリアルの放射特性を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

r, g, b

放射の色の赤、緑、青要素。

参照　IDirect3DRMMaterial::GetEmissive


IDirect3DRMMaterial::SetPower

HRESULT SetPower(D3DVALUE rvPower);

マテリアルの反射指数を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvPower

新しい反射指数。

参照　IDirect3DRMMaterial::GetPower


IDirect3DRMMaterial::SetSpecular

HRESULT SetSpecular(D3DVALUE r, D3DVALUE g, D3DVALUE b);

マテリアルの反射ハイライトの色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

r, g, b

反射ハイライトの色の赤、緑、青の各要素。

参照　IDirect3DRMMaterial::GetSpecular


IDirect3DRMMesh

アプリケーションは、メッシュのグループと互いにやり取りするためにIDirect3DRMMeshインターフェイスのメソッドを使用する。このセクションはIDirect3DRMMeshインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMMeshとIDirect3DRMMeshBuilderインターフェイス」を           参照すること。

色	GetGroupColor
	SetGroupColor
	SetGroupColorRGB
作成と情報	AddGroup
	GetBox
	GetGroup
	GetGroupCount
マテリアル	GetGroupMaterial
	SetGroupMaterial
その他	Scale
	Translate
レンダリング品質	GetGroupQuality
	SetGroupQuality
テクスチャ・マッピング	GetGroupMapping
	SetGroupMapping
テクスチャ	GetGroupTexture
	SetGroupTexture
頂点の位置	GetVertices
	SetVertices
IDirect3DRMMeshインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMMeshインターフェイスはIDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMFrameオブジェクトは、IDirect3DRM::CreateMeshメソッドの呼び出しによって取得される。


IDirect3DRMMesh::AddGroup

HRESULT AddGroup(unsigned vCount, unsigned fCount,

    unsigned vPerFace, unsigned *fData, D3DRMGROUPINDEX *returnId);

面の集合をグループ化し、そのグループの識別子を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

vCount, fCount

グループに含まれる頂点と面の数。

vPerFace

すべての面が同じ数の頂点を持つ場合、面当たりの頂点の数。グループ中の面が持つ頂点の数が一定でないときは、このパラメータに0を指定しなくてはならない。

fData

面データのアドレス。vPerFaceパラメータに値が設定されている場合、このデータは単に、グループの頂点配列へのインデックス・リストである。vPerFaceが0のときは、頂点インデックスよりも、その面の頂点の数を示す整数値を優先しなくてはならない。たとえば、vPerFaceが0で、グループを構成する面が三角形と四角形である場合、データは次のようになる。[ 3, インデックス, インデックス, インデックス, 4, インデックス, インデックス, インデックス, インデックス, 3, インデックス, インデックス, インデックス, ...]

returnId

メソッドが制御を返すとき、グループの識別子を受け取る変数へのポインタ。

新しく追加されたグループには、以下のデフォルトの特性が与えられる。

白

テクスチャなし

反射なし

頂点配列の各頂点の位置、法線、色は0

頂点の位置を設定するには、IDirect3DRMMesh::SetVertices メソッドを使用する。


IDirect3DRMMesh::GetBox

HRESULT GetBox(D3DRMBOX * lpD3DRMBox);

Direct3DRMMeshオブジェクトを含む方形範囲を取得する。方形範囲は、それぞれの次元のモデル座標の最小値と最大値を示す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMBox

方形範囲の座標を受け取るD3DRMBOX構造体。


IDirect3DRMMesh::GetGroup

HRESULT GetGroup(D3DRMGROUPINDEX id, unsigned *vCount,

    unsigned *fCount, unsigned *vPerFace, DWORD *fDataSize,

    unsigned *fData);

指定されたグループに関連付けられているデータを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使用して生成されたものでなくてはならない。

vCount, fCount

メソッドが制御を返すとき、グループの頂点の数と面の数を受け取る変数のアドレス。これらのパラメータにはNULLを指定することができる。

vPerFace

メソッドが制御を返すとき、面当たりの頂点の数を受け取る変数のアドレス。これらのパラメータにはNULLを指定することができる。

fDataSize

fDataパラメータが指すバッファの中の、符号なし要素の数を示す変数のアドレス。このパラメータにNULLを指定することはできない。

fData

メソッドが制御を返すとき、グループの面データを格納するバッファのアドレス。このデータの形式は、IDirect3DRMMesh::AddGroupメソッドの呼び出しで指定したものと同じである。このパラメータがNULLのとき、必要なバッファのサイズがfDataSizeパラメータに返される。


IDirect3DRMMesh::GetGroupColor

D3DCOLOR GetGroupColor(D3DRMGROUPINDEX id);

グループの色を取得する。

成功した場合、色を示すD3DCOLOR値を返す。そうでない場合は0を返す。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

参照　IDirect3DRMMesh::SetGroupColor, IDirect3DRMMesh::SetGroupColorRGB


IDirect3DRMMesh::GetGroupCount

unsigned GetGroupCount();

指定されたDirect3DRMMeshオブジェクトのグループの数を取得する。

成功した場合はグループの数を返す。そうでなければ0を返す。


IDirect3DRMMesh::GetGroupMapping

D3DRMMAPPING GetGroupMapping(D3DRMGROUPINDEX id);

Direct3DRMMeshオブジェクト中のグループに対して、どのようにテクスチャがマップされるかを取得する。

成功すると、グループへのテクスチャのマップ方法を示すD3DRMMAPPING値のひとつを返す。失敗すると0を返す。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

参照　IDirect3DRMMesh::SetGroupMapping


IDirect3DRMMesh::GetGroupMaterial

HRESULT GetGroupMaterial(D3DRMGROUPINDEX id,

    LPDIRECT3DRMMATERIAL *returnPtr);

Direct3DRMMeshグループに関連付けられたマテリアルへのポインタを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

returnPtr

メソッドが制御を戻すとき、グループのIDirect3DRMMaterialインターフェイスを受け取る変数へのポインタへのポインタ。

参照　IDirect3DRMMesh::SetGroupMaterial


IDirect3DRMMesh::GetGroupQuality

D3DRMRENDERQUALITY GetGroupQuality(D3DRMGROUPINDEX id);

指定されたグループのレンダリング品質を取得する。

成功するとD3DRMRENDERQUALITYで示される列挙型の値を返す。失敗すると0を返す。これらの値には、オブジェクトのシェーディング・モードや照明モード、塗りつぶしモードが含まれている。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

参照　IDirect3DRMMesh::SetGroupQuality


IDirect3DRMMesh::GetGroupTexture

HRESULT GetGroupTexture(D3DRMGROUPINDEX id,

    LPDIRECT3DRMTEXTURE *returnPtr);

グループに関連付けられたテクスチャへのポインタを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

returnPtr

メソッドが制御を返すとき、グループのIDirect3DRMTextureインターフェイスを受け取る変数へのポインタへのポインタ。

参照　IDirect3DRMMesh::SetGroupTexture


IDirect3DRMMesh::GetVertices

HRESULT GetVertices(D3DRMGROUPINDEX id, DWORD index,

    DWORD count, D3DRMVERTEX *returnPtr);

指定されたグループの頂点位置を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

index

頂点位置を取得する始点を示すD3DRMVERTEX構造体の配列のインデックス。

count

indexパラメータが示すインデックスに続いて取得する、D3DRMVERTEX構造体（頂点）の数。このパラメータにNULLを指定することはできない。

returnPtr

メソッドが制御を返すときに頂点位置を受け取るD3DRMVERTEX構造体の配列。このパラメータにNULLを指定すると、必要なD3DRMVERTEX構造体の数をcountパラメータに格納する。

参照　IDirect3DRMMesh::SetVertices


IDirect3DRMMesh::Scale

HRESULT Scale(D3DVALUE sx, D3DVALUE sy, D3DVALUE sz);

モデル座標のx軸、y軸、z軸に対し、与えられた縮尺係数によってDirect3DRMMeshオブジェクトをスケーリングする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

sx, sy, sz

x軸、y軸、z軸に沿って適用される縮尺係数。


IDirect3DRMMesh::SetGroupColor

HRESULT SetGroupColor(D3DRMGROUPINDEX id, D3DCOLOR value);

Direct3DRMMeshオブジェクト中のグループの色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

value

グループの色。

参照　IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColorRGB


IDirect3DRMMesh::SetGroupColorRGB

HRESULT SetGroupColorRGB(D3DRMGROUPINDEX id, D3DVALUE red,

    D3DVALUE green, D3DVALUE blue);

RGB値を使用して、Direct3DRMMeshオブジェクト中のグループの色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

red, green, blue

グループの色の赤、緑、青の各要素。

参照　IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColor


IDirect3DRMMesh::SetGroupMapping

HRESULT SetGroupMapping(D3DRMGROUPINDEX id, D3DRMMAPPING value);

Direct3DRMMeshオブジェクト中のグループにマッピングを設定する。マッピングは、どのようにテクスチャが面にマップされるかを決定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

value

グループのマッピングを指定するD3DRMMAPPING型の値。

参照　IDirect3DRMMesh::GetGroupMapping


IDirect3DRMMesh::SetGroupMaterial

HRESULT SetGroupMaterial(D3DRMGROUPINDEX id, LPDIRECT3DRMMATERIAL value);

Direct3DRMMeshオブジェクト中のグループにマテリアルを関連付ける。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

value

Direct3DRMMeshオブジェクトに関連付けるIDirect3DRMMaterialインターフェイスのアドレス。

参照　IDirect3DRMMesh::GetGroupMaterial


IDirect3DRMMesh::SetGroupQuality

HRESULT SetGroupQuality(D3DRMGROUPINDEX id, D3DRMRENDERQUALITY value);

指定されたグループのレンダリング品質を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

value

D3DRMRENDERQUALITY型で表される列挙型の値。これらの値には、オブジェクトのシェーディング・モードや照明モード、塗りつぶしモードが含まれている。

参照　IDirect3DRMMesh::GetGroupQuality


IDirect3DRMMesh::SetGroupTexture

HRESULT SetGroupTexture(D3DRMGROUPINDEX id, LPDIRECT3DRMTEXTURE value);

Direct3DRMMeshオブジェクト中のグループにテクスチャを関連付ける。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

value

Direct3DRMMeshオブジェクトに関連付けるIDirect3DRMTextureインターフェイスのアドレス。

参照　IDirect3DRMMesh::GetGroupTexture


IDirect3DRMMesh::SetVertices

HRESULT SetVertices(D3DRMGROUPINDEX id, unsigned index,

    unsigned count, D3DRMVERTEX *values);

指定されたグループの頂点の位置を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

id

グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。

index

頂点位置を設定する始点を示す、valuesパラメータの配列へのインデックス。

count

index パラメータが示すインデックスに続いて設定する、頂点の数。

values

設定する頂点位置を示すD3DRMVERTEX構造体の配列。

頂点情報はグループごとに持つ。ふたつの異なったグループ間で頂点を共有する必要がある場合（たとえば、メッシュ上の隣接した面の色が異なるとき）、両方のグループで頂点をコピーしなくてはならない。

参照　IDirect3DRMMesh::GetVertices


IDirect3DRMMesh::Translate

HRESULT Translate(D3DVALUE tx, D3DVALUE ty, D3DVALUE tz);

Direct3DRMMeshオブジェクト中の頂点の位置に、指定されたオフセットを追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

tx, ty, tz

各頂点位置のx座標、y座標、z座標に追加されるオフセット。


IDirect3DRMMeshBuilder

アプリケーションは、メッシュオブジェクトと互いにやり取りするためにIDirect3DRMMeshBuilderインターフェイスのメソッドを使用する。このセクションは、IDirect3DRMMeshBuilderインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMMeshとIDirect3DRMMeshBuilderインターフェイス」を参照すること。

IDirect3DRMMeshBuilderインターフェイス・メソッドは、以下のグループに分類することができる。

色	GetColorSource
	SetColor
	SetColorRGB
	SetColorSource
作成と情報	GetBox
面	AddFace
	AddFaces
	CreateFace
	GetFaceCount
	GetFaces
ロード	Load
メッシュ	AddMesh
	CreateMesh
その他	AddFrame
	AddMeshBuilder
	ReserveSpace
	Save
	Scale
	SetMaterial
	Translate
法線	AddNormal
	GenerateNormals
	SetNormal
遠近	GetPerspective
	SetPerspective
レンダリング品質	GetQuality
	SetQuality
テクスチャ	GetTextureCoordinates
	SetTexture
	SetTextureCoordinates
	SetTextureTopology
頂点	AddVertex
	GetVertexColor
	GetVertexCount
	GetVertices
	SetVertex
	SetVertexColor
	SetVertexColorRGB
IDirect3DRMMeshBuilderインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMMeshBuilderインターフェイスはIDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMMeshBuilderオブジェクトは、IDirect3DRM::CreateMeshBuilderメソッドの呼び出しによって取得される。


IDirect3DRMMeshBuilder::AddFace

HRESULT AddFace(LPDIRECT3DRMFACE lpD3DRMFace);

面をDirect3DRMMeshBuilderオブジェクトに追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMFace

追加する面のアドレス。

ひとつの面は、1度にひとつのメッシュにしか存在することはできない。


IDirect3DRMMeshBuilder::AddFaces

HRESULT AddFaces(DWORD dwVertexCount, D3DVECTOR * lpD3DVertices,

    DWORD normalCount, D3DVECTOR *lpNormals, DWORD *lpFaceData,

    LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray);

複数の面をDirect3DRMMeshBuilderオブジェクトに追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

dwVertexCount

頂点の数。

lpD3DVertices

頂点の位置を格納する D3DVECTOR 構造体の配列のベース・アドレスへのポインタ。

normalCount

法線の数。

lpNormals

法線の位置を格納する D3DVECTOR 構造体の配列のベース・アドレスへのポインタ。

lpFaceData

それぞれの面について、頂点配列へのインデックスに続く頂点の数を含むパラメータ。normalCountが0でない場合、このパラメータには頂点の数を設定しなくてはならない。そして頂点の数の後には、その数だけインデックスのペアが続く。ペアの最初は頂点配列へのインデックス、2番目は法線配列へのインデックスを示す。インデックスのリストの最後には0を設定しなくてはならない。

lplpD3DRMFaceArray

新たに作成された面へのポインタを格納する、IDirect3DRMFaceArrayインターフェイスへのポインタのアドレス。


IDirect3DRMMeshBuilder::AddFrame

HRESULT AddFrame(LPDIRECT3DRMFRAME lpD3DRMFrame);

フレームのコンテンツをDirect3DRMMeshBuilderオブジェクトに追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMFrame

フレームのアドレス。このフレームのコンテンツが追加される。

この処理を行っても、元フレームが変更または参照されることはない。


IDirect3DRMMeshBuilder::AddMesh

HRESULT AddMesh(LPDIRECT3DRMMESH lpD3DRMMesh);

メッシュをDirect3DRMMeshBuilderオブジェクトに追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMMesh

追加するメッシュのアドレス。


IDirect3DRMMeshBuilder::AddMeshBuilder

HRESULT AddMeshBuilder(LPDIRECT3DRMMESHBUILDER lpD3DRMMeshBuild);

Direct3DRMMeshBuilderオブジェクトのコンテンツを、他のDirect3DRMMeshBuilderオブジェクトに追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMMeshBuild

Direct3DRMMeshBuilderオブジェクトのアドレス。このオブジェクトのコンテンツが追加される。

この処理を行っても、もとのDirect3DRMMeshBuilderオブジェクトが変更または参照されることはない。


IDirect3DRMMeshBuilder::AddNormal

int AddNormal(D3DVALUE x, D3DVALUE y, D3DVALUE z);

法線をDirect3DRMMeshBuilderオブジェクトに追加する。

法線のインデックスを返す。

x, y, z

新しい法線の方向を示すx、y、zの各要素。


IDirect3DRMMeshBuilder::AddVertex

int AddVertex(D3DVALUE x, D3DVALUE y, D3DVALUE z);

頂点をDirect3DRMMeshBuilderオブジェクトに追加する。

頂点のインデックスを返す。

x, y, z

新しい頂点の位置を示すx、y、zの各要素。


IDirect3DRMMeshBuilder::CreateFace

HRESULT CreateFace(LPDIRECT3DRMFACE* lplpD3DRMFace);

頂点を持たない面を新しく作成し、Direct3DRMMeshBuilderオブジェクトに追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DRMFace

作成された面へのポインタを格納するIDirect3DRMFaceインターフェイスへのポインタのアドレス。


IDirect3DRMMeshBuilder::CreateMesh

HRESULT CreateMesh(LPDIRECT3DRMMESH* lplpD3DRMMesh);

Direct3DRMMeshBuilderオブジェクトから新しいメッシュを作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DRMMesh

IDirect3DRMMeshインターフェイスへのポインタを受け取るアドレス。


IDirect3DRMMeshBuilder::GenerateNormals

HRESULT GenerateNormals();

Direct3DRMMeshBuilderオブジェクトを処理し、頂点法線を生成する。頂点法線は、各頂点に接する面法線の平均である。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

連続した面の法線を平均すると、ゼロ法線が生成される。


IDirect3DRMMeshBuilder::GetBox

HRESULT GetBox(D3DRMBOX *lpD3DRMBox);

Direct3DRMMeshBuilderオブジェクトを含む矩形範囲を取得する。矩形範囲は、それぞれの次元のモデル座標の最小値と最大値を示す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMBox

矩形範囲を受け取るD3DRMBOX構造体。


IDirect3DRMMeshBuilder::GetColorSource

D3DRMCOLORSOURCE GetColorSource();

Direct3DRMMeshBuilderオブジェクトのカラー・ソースを取得する。カラー・ソースは面でも頂点でもよい。

D3DRMCOLORSOURCE列挙型メンバのひとつを返す。

参照　IDirect3DRMMeshBuilder::SetColorSource


IDirect3DRMMeshBuilder::GetFaceCount

int GetFaceCount();

Direct3DRMMeshBuilderオブジェクト中の面の数を取得する。

面の数を返す。


IDirect3DRMMeshBuilder::GetFaces

HRESULT GetFaces(LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray);

Direct3DRMMeshBuilderオブジェクトの面を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DRMFaceArray

面のアドレスを受け取るIDirect3DRMFaceArrayインターフェイスへのポインタのアドレス。


IDirect3DRMMeshBuilder::GetPerspective

BOOL GetPerspective();

Direct3DRMMeshBuilderオブジェクトで、遠近補正が有効になっているかどうかを取得する。

遠近補正が有効であればTRUE、そうでなければFALSEを返す。


IDirect3DRMMeshBuilder::GetQuality

D3DRMRENDERQUALITY GetQuality();

Direct3DRMMeshBuilderオブジェクトのレンダリング品質を取得する。

メッシュのレンダリング品質を示すD3DRMRENDERQUALITY列挙型のメンバのひとつを返す。

参照	IDirect3DRMMeshBuilder::SetQuality


IDirect3DRMMeshBuilder::GetTextureCoordinates

HRESULT GetTextureCoordinates(DWORD index, D3DVALUE *lpU,

    D3DVALUE *lpV);

Direct3DRMMeshBuilderオブジェクト中の指定された、頂点のテクスチャ座標を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

頂点のインデックス。

lpU, lpV

メソッドが制御を返すとき、頂点のテクスチャ座標を受け取る変数。

参照	IDirect3DRMMeshBuilder::SetTextureCoordinates


IDirect3DRMMeshBuilder::GetVertexColor

D3DCOLOR GetVertexColor(DWORD index);

Direct3DRMMeshBuilderオブジェクト中の指定された頂点の色を取得する。

色を返す。

index

頂点のインデックス。

参照	IDirect3DRMMeshBuilder::SetVertexColor


IDirect3DRMMeshBuilder::GetVertexCount

int GetVertexCount();

Direct3DRMMeshBuilderオブジェクト中の頂点の数を取得する。

頂点の数を返す。


IDirect3DRMMeshBuilder::GetVertices

HRESULT GetVertices(DWORD *vcount, D3DVECTOR *vertices,

    DWORD *ncount, D3DVECTOR *normals, DWORD *face_data_size,

    DWORD *face_data);

Direct3DRMMeshBuilder オブジェクトの頂点、法線、面データを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

vcount

頂点の数を受け取る変数のアドレス。

vertices

Direct3DRMMeshBuilderオブジェクトの頂点を受け取るD3DVECTOR構造体の配列。

ncount

法線の数を受け取る変数。

normals

Direct3DRMMeshBuilderオブジェクトの法線を受け取るD3DVECTOR 構造体の配列。

face_data_size

face_dataパラメータが示すバッファのサイズを指定する変数。このサイズはDWORD値単位で与えられる。このパラメータにNULLを指定することはできない。

face_data

Direct3DRMMeshBuilderオブジェクトの面データ。このデータは、NULLで終わるということを除けば、IDirect3DRMMeshBuilder::AddFaces メソッドで指定するものと同じ形式である。このパラメータがNULLのとき、面バッファが必要とするサイズがface_data_sizeパラメータに返される。


IDirect3DRMMeshBuilder::Load

HRESULT Load(LPVOID lpvObjSource, LPVOID lpvObjID,

    D3DRMLOADOPTIONS d3drmLOFlags,

    D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc, LPVOID lpvArg);

Direct3DRMMeshBuilderオブジェクトをロードする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpvObjSource

ロードするオブジェクトのソース。d3drmLOFlagsパラメータが示すソース・フラグによって、ファイル、リソース、メモリ・ブロック、またはストリームを指定する。

lpvObjID

ロードするオブジェクトの名前または位置。このパラメータはd3drmLOFlagsパラメータが示す識別子フラグによって解釈される。D3DRMLOAD_BYPOSITIONフラグを指定した場合、このパラメータはファイルの中のオブジェクトの順序を示すDWORD値へのポインタである。このパラメータにはNULLを指定することもできる。

d3drmLOFlags

ロード・オプションを示すD3DRMLOADOPTIONS型の値。

d3drmLoadTextureProc

D3DRMLOADTEXTURECALLBACKコールバック関数。これは、特別なフォーマットを必要とするオブジェクトが用いるテクスチャを読み出すときに呼び出される。このパラメータにはNULLを指定することができる。

lpvArg

D3DRMLOADTEXTURECALLBACKコールバック関数に渡される、アプリケーション定義のデータ。

デフォルトでは、このメソッドはlpvObjSourceパラメータで指定されたソースから最初のメッシュをロードする。


IDirect3DRMMeshBuilder::ReserveSpace

HRESULT ReserveSpace(DWORD vertexCount, DWORD normalCount,

    DWORD faceCount);

頂点、法線、面の数を指定して、Direct3DRMMeshBuilderオブジェクト中に領域を確保する。これによって、システムがより効率的にメモリを使えるようになる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

vertexCount, normalCount, faceCount

頂点、法線、面のために割り当てる領域の数。


IDirect3DRMMeshBuilder::Save

HRESULT Save(const char * lpFilename,

    D3DRMXOFFORMAT d3drmXOFFormat, D3DRMSAVEOPTIONS d3drmSOContents);

Direct3DRMMeshBuilderオブジェクトを保存する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpFilename

作成されるファイル名前へのポインタ。ファイル名の拡張子は.Xでなくてはならない。

d3drmXOFFormat

D3DRMXOFFORMAT列挙型のD3DRMXOF_TEXT値。

d3drmSOContents

保存オプションを表すD3DRMSAVEOPTIONS型の値。


IDirect3DRMMeshBuilder::Scale

HRESULT Scale(D3DVALUE sx, D3DVALUE sy, D3DVALUE sz);

モデル座標のx軸、y軸、z軸に与えられた縮尺係数によって、Direct3DRMMeshBuilderオブジェクトをスケーリングする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

sx, sy, sz

x軸、y軸、z軸に沿って適用される縮尺係数。


IDirect3DRMMeshBuilder::SetColor

HRESULT SetColor(D3DCOLOR color);

Direct3DRMMeshBuilderオブジェクトのすべての面に、指定された色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

color

面の色。


IDirect3DRMMeshBuilder::SetColorRGB

HRESULT SetColorRGB(D3DVALUE red, D3DVALUE green, D3DVALUE blue);

Direct3DRMMeshBuilderオブジェクトのすべての面に、指定された色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

red, green, blue

設定する色の赤、緑、青の各要素。


IDirect3DRMMeshBuilder::SetColorSource

HRESULT SetColorSource(D3DRMCOLORSOURCE source);

Direct3DRMMeshBuilderオブジェクトのカラー・ソースを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

source

新しく使用するカラー・ソースを示すD3DRMCOLORSOURCE列挙型のメンバ。

参照　IDirect3DRMMeshBuilder::GetColorSource


IDirect3DRMMeshBuilder::SetMaterial

HRESULT SetMaterial(LPDIRECT3DRMMATERIAL lpIDirect3DRMmaterial);

Direct3DRMMeshBuilderオブジェクトのすべての面にマテリアルを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpIDirect3DRMmaterial

Direct3DRMMeshBuilderオブジェクトのIDirect3DRMMaterialインターフェイス。


IDirect3DRMMeshBuilder::SetNormal

HRESULT SetNormal(DWORD index, D3DVALUE x, D3DVALUE y, D3DVALUE z);

Direct3DRMMeshBuilderオブジェクトで指定された頂点の法線ベクトルを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

設定する法線のインデックス。

x, y, z

指定した法線に割り当てるベクトルのx、y、zの各要素。


IDirect3DRMMeshBuilder::SetPerspective

HRESULT SetPerspective(BOOL perspective);

Direct3DRMMeshBuilderオブジェクトの、遠近補正テクスチャ・マッピングを有効または無効にする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

perspective

メッシュのテクスチャ・マッピングに遠近補正を適用する場合はTRUE、そうでなければFALSEを指定する。


IDirect3DRMMeshBuilder::SetQuality

HRESULT SetQuality(D3DRMRENDERQUALITY quality);

Direct3DRMMeshBuilderオブジェクトのレンダリング品質を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

quality

新しく使用するレンダリング品質を示す、D3DRMRENDERQUALITY列挙型のメンバ。

参照　IDirect3DRMMeshBuilder::GetQuality


IDirect3DRMMeshBuilder::SetTexture

HRESULT SetTexture(LPDIRECT3DRMTEXTURE lpD3DRMTexture);

Direct3DRMMeshBuilderオブジェクトのすべての面のテクスチャを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMTexture

必要なDirect3DRMTextureオブジェクト。


IDirect3DRMMeshBuilder::SetTextureCoordinates

HRESULT SetTextureCoordinates(DWORD index, D3DVALUE u, D3DVALUE v);

Direct3DRMMeshBuilderオブジェクトの指定された頂点のテクスチャ座標を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

設定する頂点のインデックス。

u,  v

指定されたメッシュ頂点に割り当てるテクスチャ座標。

参照　IDirect3DRMMeshBuilder::GetTextureCoordinates


IDirect3DRMMeshBuilder::SetTextureTopology

HRESULT SetTextureTopology(BOOL cylU, BOOL cylV);

Direct3DRMMeshBuilderオブジェクトのテクスチャ位相を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

cylU, cylV

u次元とv次元の位相フラグ。u次元またはv次元に円柱位相を持たせる場合はTRUE、そうでなければFALSEを指定する。


IDirect3DRMMeshBuilder::SetVertex

HRESULT SetVertex(DWORD index, D3DVALUE x, D3DVALUE y, D3DVALUE z);

Direct3DRMMeshBuilderオブジェクトの指定された頂点の位置を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

設定する頂点のインデックス。

x, y, z

指定された頂点に割り当てる位置のx、y、zの各要素。


IDirect3DRMMeshBuilder::SetVertexColor

HRESULT SetVertexColor(DWORD index, D3DCOLOR color);

Direct3DRMMeshBuilderオブジェクトの、指定された頂点の色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

設定する頂点のインデックス。

color

指定された頂点に割り当てる色。

参照　IDirect3DRMMeshBuilder::GetVertexColor


IDirect3DRMMeshBuilder::SetVertexColorRGB

HRESULT SetVertexColorRGB(DWORD index, D3DVALUE red,

    D3DVALUE green, D3DVALUE blue);

Direct3DRMMeshBuilderオブジェクトの、指定された頂点の色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

index

設定する頂点のインデックス。

red, green, blue

頂点に割り当てる色の赤、緑、青の各要素。


IDirect3DRMMeshBuilder::Translate

HRESULT Translate(D3DVALUE tx, D3DVALUE ty, D3DVALUE tz);

Direct3DRMMeshBuilderオブジェクトの頂点の位置に、指定されたオフセットを追加する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

tx, ty, tz

各頂点位置のx、y、z座標それぞれに追加されるオフセット。


IDirect3DRMObject

アプリケーションはDirect3DRMオブジェクトのスーパー・クラスとやり取りするため、IDirect3DRMObjectインターフェイスのメソッドを使用する。このセクションはIDirect3DRMObjectインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMObjectインターフェイス」を参照すること。

IDirect3DRMObjectインターフェイス・メソッドは、以下のグループに分類することができる。

アプリケーション固有のデータ	GetAppData
	SetAppData
複製	Clone
名前	GetClassName
	GetName
	SetName
通知	AddDestroyCallback
	DeleteDestroyCallback
IDirect3DRMObjectインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
Direct3DRMObjectオブジェクトは、適切なQueryInterfaceメソッドを呼び出すことにより、どのDirect3DRMオブジェクトからでも取得することができる。すべてのDirect3DRMオブジェクトは、IDirect3DRMObjectインターフェイス・メソッドを継承する。


IDirect3DRMObject::AddDestroyCallback

HRESULT AddDestroyCallback(D3DRMOBJECTCALLBACK lpCallback,

    LPVOID lpArg);

オブジェクトが破棄されるときに呼び出される関数を登録する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpCallback

オブジェクトが破棄されるときに呼び出される、ユーザ定義のコールバック関数。

lpArg

コールバック関数に渡される、アプリケーション定義のデータ。この関数はオブジェクトが破棄された後に呼び出されるため、引数としてオブジェクトを渡してはならない。


IDirect3DRMObject::Clone

HRESULT Clone(LPUNKNOWN pUnkOuter, REFIID riid, LPVOID *ppvObj);

オブジェクトの複製を作成する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

pUnkOuter

COM集成化機能に対応するために存在するパラメータ。

riid

複製するオブジェクトの識別子。

ppvObj

メソッドが制御を返すとき、オブジェクトの複製を格納するアドレス。


IDirect3DRMObject::DeleteDestroyCallback

HRESULT DeleteDestroyCallback(D3DRMOBJECTCALLBACK d3drmObjProc,

    LPVOID lpArg);

IDirect3DRMObject::AddDestroyCallbackメソッドによって登録された関数を削除する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmObjProc

オブジェクトが破棄されるときに呼び出される、ユーザ定義のD3DRMOBJECTCALLBACKコールバック関数。

lpArg

コールバック関数に渡される、アプリケーション定義のデータのアドレス。


IDirect3DRMObject::GetAppData

DWORD GetAppData();

オブジェクトから、アプリケーション固有の32ビット・データを取得する。デフォルト値は0である。

アプリケーションによって定義されたデータ値を返す。

参照　IDirect3DRMObject::SetAppData


IDirect3DRMObject::GetClassName

HRESULT GetClassName(LPDWORD lpdwSize, LPSTR lpName);

オブジェクトのクラス名を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpdwSize

lpNameパラメータが示すバッファのサイズがバイト単位で入る変数のアドレス。

lpName

メソッドが制御を返すとき、クラス名を示すNULLで終わる文字列へのポインタ。このパラメータがNULLの場合、lpdwSizeパラメータには文字列に必要なサイズが設定される。


IDirect3DRMObject::GetName

HRESULT GetName(LPDWORD lpdwSize, LPSTR lpName);

オブジェクト名を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpdwSize

lpNameパラメータが示すバッファのサイズがバイト単位で入る変数。

lpName

メソッドが制御を返すとき、オブジェクトの名前を示すNULLで終わる文字列へのポインタ。このパラメータがNULLの場合、lpdwSizeパラメータには文字列に必要なサイズが設定される。

参照　IDirect3DRMObject::SetName


IDirect3DRMObject::SetAppData

HRESULT SetAppData(DWORD ulData);

オブジェクトにアプリケーション固有の32ビット・データを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

ulData

オブジェクトに格納されるユーザ定義のデータ。

参照　IDirect3DRMObject::GetAppData


IDirect3DRMObject::SetName

HRESULT SetName(const char * lpName);

オブジェクトの名前を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpName

オブジェクトの名前を示すユーザ定義のデータ。

参照　IDirect3DRMObject::GetName


IDirect3DRMShadow

アプリケーションは、Direct3DRMShadowオブジェクトを初期化するためにIDirect3DRMShadowインターフェイスのメソッドを使用する。アプリケーションがIDirect3DRM::CreateShadowメソッドを呼び出すときは、この初期化は不要である。初期化が必要なのは、IDirect3DRM::CreateObjectメソッドを呼び出して陰影を生成する場合だけである。

このセクションはIDirect3DRMShadowインターフェイス・メソッドのリファレンスである。概念についての概要は、IDirect3DRMShadowインターフェイスを参照すること。

IDirect3DRMShadowインターフェイスは、Initメソッドをサポートする。

IDirect3DRMShadowインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMShadowインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMShadowオブジェクトは、IDirect3DRM::CreateShadowメソッドの呼び出しによって取得される。


IDirect3DRMShadow::Init

HRESULT Init(LPDIRECT3DRMVISUAL lpD3DRMVisual,

    LPDIRECT3DRMLIGHT lpD3DRMLight, D3DVALUE px, D3DVALUE py,

    D3DVALUE pz, D3DVALUE nx, D3DVALUE ny, D3DVALUE nz);

Direct3DRMShadowオブジェクトを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMVisual

陰影付けるDirect3DRMVisualオブジェクト。

lpD3DRMLight

陰影の元になる光源を提供するDirect3DRMLightオブジェクト。

px, py, pz

陰影が付けられる平面上の点の座標。

nx, ny, nz

陰影が付けられる平面上の法線ベクトルの座標。


IDirect3DRMTexture

アプリケーションは、テクスチャと互いにやり取りするためにIDirect3DRMTextureインターフェイスのメソッドを使用する。テクスチャは矩形のピクセル配列である。このセクションは、IDirect3DRMTextureインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMTextureインターフェイス」を参照すること。

IDirect3DRMTextureインターフェイス・メソッドは、以下のグループに分類することができる。

色	GetColors
	SetColors
デカール	GetDecalOrigin
	GetDecalScale
	GetDecalSize
	GetDecalTransparency
	GetDecalTransparentColor
	SetDecalOrigin
	SetDecalScale
	SetDecalSize
	SetDecalTransparency
	SetDecalTransparentColor
イメージ	GetImage
初期化	InitFromFile
	InitFromResource
	InitFromSurface
レンダラー通知	Changed
陰影	GetShades
	SetShades
IDirect3DRMTextureインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMTextureインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMTextureオブジェクトは、IDirect3DRM::CreateTextureメソッドの呼び出しによって取得できる。


IDirect3DRMTexture::Changed

HRESULT Changed(BOOL bPixels, BOOL bPalette);

アプリケーションがテクスチャのピクセルやパレットを変更したことをレンダラーに通知する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

bPixels

ピクセルが変更されたときはTRUEを設定する。

bPalette

パレットが変更されたときはTRUEを設定する。


IDirect3DRMTexture::GetColors

DWORD GetColors();

テクスチャのレンダリングで使われる最大色数を取得する。

色数を返す。

このメソッドは、テクスチャの作成に使われたイメージの色数ではなく、これまでにテクスチャに設定された色の数を返す。したがって、通常返される色の数は、IDirect3DRMTexture::SetColorsメソッドで明示的にテクスチャの色を変更しない限り、IDirect3DRM::SetDefaultTextureColorsメソッドを呼び出して設定した色と同じである。

参照　IDirect3DRMTexture::SetColors


IDirect3DRMTexture::GetDecalOrigin

HRESULT GetDecalOrigin(LONG * lplX, LONG * lplY);

デカールの現在の原点を取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplX, lplY

メソッドが制御を返すとき、デカールの原点を受け取る変数。

参照　IDirect3DRMTexture::SetDecalOrigin


IDirect3DRMTexture::GetDecalScale

DWORD GetDecalScale();

指定されたデカールのスケーリング特性を取得する。

成功するとスケーリング特性を返す。失敗すると�１を返す。

参照	IDirect3DRMTexture::SetDecalScale


IDirect3DRMTexture::GetDecalSize

HRESULT GetDecalSize(D3DVALUE *lprvWidth, D3DVALUE *lprvHeight);

デカールのサイズを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lprvWidth, lprvHeight

メソッドが制御を返すときにデカールの幅と高さを受け取る変数。

参照　IDirect3DRMTexture::SetDecalSize


IDirect3DRMTexture::GetDecalTransparency

BOOL GetDecalTransparency();

デカールの透明度特性を取得する。

デカールに透明色があればTRUE、なければFALSEを返す。

参照　IDirect3DRMTexture::SetDecalTransparency


IDirect3DRMTexture::GetDecalTransparentColor

D3DCOLOR GetDecalTransparentColor();

デカールの透明色を取得する。

透明色の値を返す。

参照　IDirect3DRMTexture::SetDecalTransparentColor


IDirect3DRMTexture::GetImage

D3DRMIMAGE * GetImage();

テクスチャの作成に用いられたイメージのアドレスを返す。

現在のテクスチャの作成に用いられたD3DRMIMAGE構造体へのポインタを返す。


IDirect3DRMTexture::GetShades

DWORD GetShades();

テクスチャをレンダリングする際、それぞれの色で使われる陰影の数を取得する。

陰影の数を返す。

参照　IDirect3DRMTexture::SetShades


IDirect3DRMTexture::InitFromFile

HRESULT InitFromFile(const char *filename);

指定されたファイルの情報を使ってテクスチャを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

filename

初期化情報を取り出すファイルを指定する文字列。

初期化するテクスチャは、IDirect3DRM::CreateObjectを用いて作成しておかなくてはならない。

参照　IDirect3DRMTexture::InitFromResource, IDirect3DRMTexture::InitFromSurface


IDirect3DRMTexture::InitFromResource

HRESULT InitFromResource(HRSRC rs);

指定されたリソースからDirect3DRMTextureオブジェクトを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rs

リソースのハンドルを指定する。

参照　IDirect3DRMTexture::InitFromFile, IDirect3DRMTexture::InitFromSurface


IDirect3DRMTexture::InitFromSurface

HRESULT InitFromSurface(LPDIRECTDRAWSURFACE lpDDS);

指定されたDirectDrawサーフェスのデータを使用してテクスチャを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpDDS

初期化情報を取り出すDirectDrawサーフェス。

参照　IDirect3DRMTexture::InitFromFile, IDirect3DRMTexture::InitFromResource


IDirect3DRMTexture::SetColors

HRESULT SetColors(DWORD ulColors);

テクスチャのレンダリングに使用する最大色数を設定する。このメソッドが必要なのは、ランプ・カラー・モデルだけである。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

ulColors

色数。デフォルト値は8である。

参照　IDirect3DRMTexture::GetColors


IDirect3DRMTexture::SetDecalOrigin

HRESULT SetDecalOrigin(LONG lX, LONG lY);

デカールの原点を、デカールの左上からのオフセットとして設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lX, lY

新しい原点をデカール座標で指定する。デフォルトの原点は[0, 0]である。

レンダリングときには、デカールの原点はそのフレームの位置にマップされる。たとえば、十字のデカールの原点はデカールの中央に、下向きの矢印の原点は底辺の中央にセットされる。

参照　IDirect3DRMTexture::GetDecalOrigin


IDirect3DRMTexture::SetDecalScale

HRESULT SetDecalScale(DWORD dwScale);

デカールの縮尺特性をセットする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

dwScale

このパラメータにTRUEを指定すると、深度を考慮に入れてデカールをスケーリングする。FALSEを指定すると、深度情報は無視される。デフォルト値はTRUEである。

参照　IDirect3DRMTexture::GetDecalScale


IDirect3DRMTexture::SetDecalSize

HRESULT SetDecalSize(D3DVALUE rvWidth, D3DVALUE rvHeight);

デカールが深度によってスケーリングされているとき、使用されるデカールのサイズを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvWidth, rvHeight

デカールの新しい幅と高さをモデル座標で指定する。デフォルトのサイズは[1, 1]である。

参照　IDirect3DRMTexture::GetDecalSize


IDirect3DRMTexture::SetDecalTransparency

HRESULT SetDecalTransparency(BOOL bTransp);

デカールの透明度特性をセットする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

bTransp

デカールが透明色を持つときはTRUE、不透明色を持つときはFALSEを指定する。デフォルト値はFALSEである。

参照　IDirect3DRMTexture::GetDecalTransparency


IDirect3DRMTexture::SetDecalTransparentColor

HRESULT SetDecalTransparentColor(D3DCOLOR rcTransp);

デカールに透明色を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rcTransp

新しい透明色。デフォルトの透明色は黒である。

参照　IDirect3DRMTexture::GetDecalTransparentColor


IDirect3DRMTexture::SetShades

HRESULT SetShades(DWORD ulShades);

レンダリング時にテクスチャの各色で使用される陰影の最大の数を設定する。

レンダリングのとき、テクスチャの陰影の最大の数をそれぞれの色の用途にセットする。このメソッドを必要とするのは、ランプ・カラー・モデルだけである。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

ulShades

陰影の新しい数。この値は2の累乗である。デフォルト値は16である。

参照　IDirect3DRMTexture::GetShades


IDirect3DRMUserVisual

アプリケーションは、Direct3DRMUserVisualオブジェクトを初期化するためにIDirect3DRMUserVisualインターフェイスのメソッドを使用する。アプリケーションがIDirect3DRM::CreateUserVisualメソッドを呼び出すときは、この初期化は不要である。初期化が必要なのは、 IDirect3DRM::CreateObjectメソッドを呼び出してビジュアル・オブジェクトを生成する場合だけである。このセクションは、IDirect3DRMUserVisualインターフェイス・メソッドのリファレンスである。概念についての概要は、IDirect3DRMUserVisualインターフェイスを参照すること。

IDirect3DRMUserVisualインターフェイスはInitメソッドをサポートする。

IDirect3DRMUserVisualインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMUserVisualインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMUserVisualオブジェクトは、IDirect3DRM::CreateUserVisualメソッドの呼び出しによって取得される。


IDirect3DRMUserVisual::Init

HRESULT Init(D3DRMUSERVISUALCALLBACK d3drmUVProc, void * lpArg);

Direct3DRMUserVisualオブジェクトを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

d3drmUVProc

アプリケーション定義のD3DRMUSERVISUALCALLBACK コールバック関数。

lpArg

コールバック関数に渡されるアプリケーション定義のデータへのポインタ。

アプリケーションはIDirect3DRM::CreateUserVisualメソッドを呼び出し、ユーザ・ビジュアル・オブジェクトの作成と初期化を同時に行うことができる。IDirect3DRMUserVisual::Initを呼び出す必要があるのは、IDirect3DRM::CreateObjectメソッドによってユーザ・ビジュアル・オブジェクトを作成した場合だけである。


IDirect3DRMViewport

アプリケーションは、ビューポート・オブジェクトと互いにやり取りするためにIDirect3DRMViewportインターフェイスのメソッドを使用する。このセクションはIDirect3DRMViewportインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMViewportとIDirect3DRMViewportArrayインターフェイス」を参照すること。

IDirect3DRMViewportインターフェイス・メソッドは、以下のグループに分類することができる。

カメラ	GetCamera
	SetCamera
クリッピング・プレーン	GetBack
	GetFront
	GetPlane
	SetBack
	SetFront
	SetPlane
サイズ	GetHeight
	GetWidth
ビューのフィールド	GetField
	SetField
初期化	Init
その他	Clear
	Configure
	ForceUpdate
	GetDevice
	GetDirect3DViewport
	Pick
	Render
オフセット	GetX
	GetY
射影タイプ	GetProjection
	SetProjection
スケーリング	GetUniformScaling
	SetUniformScaling
変換	InverseTransform
	Transform
IDirect3DRMViewportインターフェイスは、すべてのCOMインターフェイスと同様IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMViewportインターフェイスはIDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMViewportオブジェクトは、IDirect3DRM::CreateViewportメソッドの呼び出しによって取得される。


IDirect3DRMViewport::Clear

HRESULT Clear();

現在の背景色で、指定されたビューポートをクリアする。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。


IDirect3DRMViewport::Configure

HRESULT Configure(LONG lX, LONG lY, DWORD dwWidth, DWORD dwHeight);

ビューポートの原点とサイズを再設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lX, lY

ビューポートの新しい位置。

dwWidth, dwHeight

ビューポートの新しい幅と高さ。

lX + dwWidthがデバイスの幅より大きい場合、lY + dwHeightがデバイスの高さより大きい場合、あるいはlX、lY、dwWidth、dwHeightのいずれかが0以下である場合、このメソッドはD3DRMERR_BADVALUEを返す。


IDirect3DRMViewport::ForceUpdate

HRESULT ForceUpdate(DWORD dwX1, DWORD dwY1, DWORD dwX2,

    DWORD dwY2);

ビューポートの領域を強制的に更新する。指定された領域は、次回のIDirect3DRMDevice::Updateメソッドの呼び出しでスクリーンにコピーされる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

dwX1, dwY1

更新領域の左上隅の座標。

dwX2, dwY2

更新領域の右下隅の座標。

システムは、指定された矩形よりも大きなリージョンを更新することがある。場合によっては、ウィンドウ全体が更新されることもある。


IDirect3DRMViewport::GetBack

D3DVALUE GetBack();

ビューポートの後方クリップ面 の位置を取得する。

位置を示す値を返す。

参照　IDirect3DRMViewport::SetBack, 視錐台


IDirect3DRMViewport::GetCamera

HRESULT GetCamera(LPDIRECT3DRMFRAME *lpCamera);

ビューポートのカメラを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpCamera

カメラを表すDirect3DRMFrameオブジェクトが入る変数へのポインタ。

参照　IDirect3DRMViewport::SetCamera, カメラ


IDirect3DRMViewport::GetDevice

HRESULT GetDevice(LPDIRECT3DRMDEVICE *lpD3DRMDevice);

ビューポートと関連付けられたデバイスを取得する

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMDevice

Direct3DRMDeviceオブジェクトが入る変数。


IDirect3DRMViewport::GetDirect3DViewport

HRESULT GetDirect3DViewport(LPDIRECT3DVIEWPORT * lplpD3DViewport);

現在のDirect3DRMViewportに対応するDirect3Dビューポートを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lplpD3DViewport

Direct3DViewportオブジェクトへのポインタが入るポインタ。


IDirect3DRMViewport::GetField

D3DVALUE GetField();

ビューポートのビュー・フィールドを取得する。

ビューのフィールドを示す値を返す。

参照　IDirect3DRMViewport::SetField, 視錐台


IDirect3DRMViewport::GetFront

D3DVALUE GetFront();

ビューポートの前方クリップ面の位置を取得する。

位置を示す値を返す。

参照　IDirect3DRMViewport::SetFront, 視錐台


IDirect3DRMViewport::GetHeight

DWORD GetHeight();

ビューポートの高さをピクセル単位で取得する。

高さをピクセル単位で返す。


IDirect3DRMViewport::GetPlane

HRESULT GetPlane(D3DVALUE *lpd3dvLeft, D3DVALUE *lpd3dvRight,

    D3DVALUE *lpd3dvBottom, D3DVALUE *lpd3dvTop);

前方クリップ面上のビューポートのサイズを取得する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpd3dvLeft, lpd3dvRight, lpd3dvBottom, lpd3dvTop

前方クリップ面上のビューポートのサイズを受け取る変数のアドレス。

参照　IDirect3DRMViewport::SetPlane


IDirect3DRMViewport::GetProjection

D3DRMPROJECTIONTYPE GetProjection();

ビューポートの射影タイプを取得する。ビューポートには、平行投影と透視投影のどちらでも用いることができる。

D3DRMPROJECTIONTYPE列挙型のメンバのひとつを返す。

参照　IDirect3DRMViewport::SetProjection


IDirect3DRMViewport::GetUniformScaling

BOOL GetUniformScaling();

ウィンドウのサイズより大きな表示ボリュームをスケーリングするために用いられる、縮尺特性を取得する。

ビューポートが一定の比率でスケーリングされる場合はTRUE、そうでなければFALSEを返す。

参照　IDirect3DRMViewport::SetUniformScaling


IDirect3DRMViewport::GetWidth

DWORD GetWidth();

ビューポートの幅をピクセル単位で取得する。

幅をピクセル単位で返す。


IDirect3DRMViewport::GetX

LONG GetX();

デバイス上のビューポート始点のx座標オフセットを取得する。

xオフセットを返す。


IDirect3DRMViewport::GetY

LONG GetY();

デバイスの上のビューポート始点のy座標オフセットを取得する。

yオフセットを返す。


IDirect3DRMViewport::Init

HRESULT Init(LPDIRECT3DRMDEVICE lpD3DRMDevice,

    LPDIRECT3DRMFRAME lpD3DRMFrameカメラ, DWORD xpos, DWORD ypos,

    DWORD width, DWORD height);

Direct3DRMViewportオブジェクトを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMDevice

このビューポートに関連付けられたDirectD3DRMDeviceオブジェクト。

lpD3DRMFrameカメラ

このビューポートに関連付けられたカメラ・フレーム。

xpos,  ypos

ビューポートの左上隅のx座標およびy座標。

width, height

ビューポートの幅と高さ。


IDirect3DRMViewport::InverseTransform

HRESULT InverseTransform(D3DVECTOR * lprvDst, D3DRMVECTOR4D * lprvSrc);

lprvSrcパラメータが示すベクトルをワールド座標からモデル座標に変換し、結果をlprvDstパラメータに返す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lprvDst

メソッドが制御を返すときに処理結果を受け取るD3DVECTOR構造体。

lprvSrc

変換されるD3DRMVECTOR4D構造体。


IDirect3DRMViewport::Pick

HRESULT Pick(LONG lX, LONG lY,

    LPDIRECT3DRMPICKEDARRAY* lplpVisuals);

深度によって分類されたオブジェクト（関連があれば面も）のリストを見つけ出す。取得した配列には、ルートからオブジェクトを含むフレームに到達するまでの階層パスが格納される。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lX, lY

ピッキングに使われる座標。

lplpVisuals

呼び出しが成功したとき、IDirect3DRMPickedArrayインターフェイスへの有効なポインタが入るポインタへのポインタ。


IDirect3DRMViewport::Render

HRESULT Render(LPDIRECT3DRMFRAME lpD3DRMFrame);

フレーム階層を、指定されたビューポートにレンダリングする。指定されたフレーム上のビジュアルと、その下の階層のフレームだけがレンダリングされる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpD3DRMFrame

レンダリングするフレーム階層を示すDirect3DRMFrameオブジェクトを示す変数へのポインタ。


IDirect3DRMViewport::SetBack

HRESULT SetBack(D3DVALUE rvBack);

ビューポートの後方クリップ面の位置を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvBack

後方クリップ面の新しい位置。

参照　IDirect3DRMViewport::GetBack, IDirect3DRMViewport::SetFront, 視錐台


IDirect3DRMViewport::SetCamera

HRESULT SetCamera(LPDIRECT3DRMFRAME lpCamera);

カメラフレームをビューポートに設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpCamera

カメラを示すDirect3DRMFrameオブジェクトを指す変数。

このメソッドは、ビューポートの位置、方向、向きを指定されたカメラ・フレームと同じに設定する。ビューは、カメラ・フレームの正のz軸方向に沿って、正のy軸の上方向に向けられる。

参照　IDirect3DRMViewport::GetCamera, カメラ


IDirect3DRMViewport::SetField

HRESULT SetField(D3DVALUE rvField);

ビューポートにビューのフィールドを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvField

ビューの新しいフィールド。デフォルト値は0.5である。この値に0以下を指定すると、このメソッドはD3DRMERR_BADVALUEエラーを返す。

参照　IDirect3DRMViewport::GetField, 視錐台


IDirect3DRMViewport::SetFront

HRESULT SetFront(D3DVALUE rvFront);

ビューポートの前方クリップ面の位置を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvFront

前方クリップ面の新しい位置。

デフォルト値は1.0である。0以下の値が渡されると、このメソッドはD3DRMERR_BADVALUEエラーを返す。

参照　IDirect3DRMViewport::GetFront, 視錐台


IDirect3DRMViewport::SetPlane

HRESULT SetPlane(D3DVALUE rvLeft, D3DVALUE rvRight, D3DVALUE rvBottom,

    D3DVALUE rvTop);

カメラのz軸に対するビューポートのサイズを前方クリップ面に設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

rvLeft, rvRight, rvBottom, rvTop

ビューポートの最小のx座標 、最大のx座標、最小のy座標、最大のy座標。

中央に調整されたビューポートを指定するIDirect3DRMViewport::SetFieldメソッドと異なり、このメソッドによって、任意の比率と位置のビューポートを指定することができる。たとえば、分離した視錐台を構築して、右目や左目のステレオ・ビューをインプリメントすることができる。

参照　IDirect3DRMViewport::GetPlane, IDirect3DRMViewport::SetField


IDirect3DRMViewport::SetProjection

HRESULT SetProjection(D3DRMPROJECTIONTYPE rptType);

ビューポートに射影タイプを設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、｢Direct3D保持モードの返値｣を参照すること。

rptType

D3DRMPROJECTIONTYPE列挙型のメンバのひとつ。

参照　IDirect3DRMViewport::GetProjection


IDirect3DRMViewport::SetUniformScaling

HRESULT SetUniformScaling(BOOL bScale);

表示ボリュームをウィンドウのサイズよりも大きくスケーリングするときに用いられる、縮尺特性を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、｢Direct3D保持モードの返値｣を参照すること。

bScale

新しい縮尺特性。このパラメータにTRUEを指定すると、水平方向と垂直方向に同じ縮尺係数が使用される。そうでなければ、表示ボリュームをウィンドウに一致させるため、異なる縮尺係数が用いられる。デフォルトの設定はTRUEである。

通常このメソッドは、バンディングをサポートするためにIDirect3DRMViewport::SetPlaneメソッドとともに使用される。

参照　IDirect3DRMViewport::GetUniformScaling


IDirect3DRMViewport::Transform

HRESULT Transform(D3DRMVECTOR4D * lprvDst, D3DVECTOR * lprvSrc);

lprvSrcパラメータが示すベクトルをワールド座標からスクリーン座標に変換し、結果をlprvDstパラメータに返す。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、｢Direct3D保持モードの返値｣を参照すること。

lprvDst

変換操作の出力先となるD3DRMVECTOR4D構造体。

lprvSrc

変換処理のソースとなるD3DVECTOR構造体。

変換結果には、4要素の同種のベクトルが返される。以下の方程式が真であれば、結果のベクトルが示す点は可視状態である。


IDirect3DRMWinDevice

アプリケーションは、ウィンドウ・プロシージャでウィンドウ・メッセージに応答するためにIDirect3DRMWinDeviceインターフェイスのメソッドを使用する。このセクションはIDirect3DRMWinDeviceインターフェイス・メソッドのリファレンスである。概念についての概要は、「ウィンドウ管理」を参照すること。

IDirect3DRMWinDeviceインターフェイス・メソッドは、以下のグループに分類することができる。

HandleActivate
HandlePaint
IDirect3DRMWinDeviceインターフェイスは、すべてのCOMインターフェイスと同様、IUnknown インターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
Direct3DRMWinDeviceオブジェクトは、IID_IDirect3DRMWinDeviceを指定してIDirect3DRM::QueryInterfaceメソッド呼び出すか、IDirect3DRM::CreateDeviceFromD3Dのようなメソッドを使用すれば取得できる。Direct3DRMWinDeviceオブジェクトのメソッドは、IDirect3DRMDeviceから継承される。


IDirect3DRMWinDevice::HandleActivate

HRESULT HandleActivate(WORD wParam);

WindowsのWM_ACTIVATEメッセージに応答する。これにより、アクティブなレンダリング・ウィンドウで色を正しく保つことができる。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、｢Direct3D保持モードの返値｣を参照すること。

wParam

メッセージ処理プロシージャに渡される、WM_ACTIVATEのWPARAMパラメータ。


IDirect3DRMWinDevice::HandlePaint

HRESULT HandlePaint(HDC hDC);

WindowsのWM_PAINTメッセージに応答する。hDCパラメータは、WindowsのBeginPaint関数に渡されるPAINTSTRUCT構造体から取得される。このメソッドは、デバイス上に作成されたビューポートの外側の領域を再描画することがあるため、ウィンドウ内のアプリケーション領域を再描画する前に必ず呼び出す必要がある。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

hDC

デバイス・コンテキスト（DC）のハンドル。


IDirect3DRMWrap

アプリケーションは、ラップ・オブジェクトとやり取りするためにIDirect3DRMWrapインターフェイスのメソッドを使用する。このセクションはIDirect3DRMWrapインターフェイス・メソッドのリファレンスである。概念についての概要は、「IDirect3DRMWrapインターフェイス」を参照すること。

IDirect3DRMWrapインターフェイス・メソッドは、以下のグループに分類することができる。

初期化	Init
ラップ	Apply
	ApplyRelative
IDirect3DRMWrapインターフェイスは、すべてのCOMインターフェイスと同様、IUnknownインターフェイス・メソッドを継承する。IUnknownインターフェイスは次の３つのメソッドをサポートする。

AddRef
QueryInterface
Release
さらに、IDirect3DRMWrapインターフェイスはIDirect3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
Direct3DRMWrapオブジェクトは、IDirect3DRM::CreateWrapメソッドの呼び出しによって取得される。


IDirect3DRMWrap::Apply

HRESULT Apply(LPDIRECT3DRMOBJECT lpObject);

Direct3DRMWrapオブジェクトをその出力先オブジェクトに適用する。一般に出力先オブジェクトは、面またはメッシュである。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

lpObject

出力先オブジェクトのアドレス。

参照　IDirect3DRM::CreateWrap


IDirect3DRMWrap::ApplyRelative

HRESULT ApplyRelative(LPDIRECT3DRMFRAME frame,

    LPDIRECT3DRMOBJECT mesh);

オブジェクトの頂点にラップを設定する。最初に各頂点にフレームのワールド変換を行い、次にラップの参照フレームの逆ワールド変換を設定する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、「Direct3D保持モードの返値」を参照すること。

frame

ラッピングするオブジェクトを含むDirect3DRMFrameオブジェクト。

mesh

適用するDirect3DRMWrapオブジェクト。

参照　IDirect3DRM::CreateWrap


IDirect3DRMWrap::Init

HRESULT Init(D3DRMWRAPTYPE d3drmwt, LPDIRECT3DRMFRAME lpd3drmfRef,

    D3DVALUE ox, D3DVALUE oy, D3DVALUE oz,

    D3DVALUE dx, D3DVALUE dy, D3DVALUE dz,

    D3DVALUE ux, D3DVALUE uy, D3DVALUE uz,

    D3DVALUE ou, D3DVALUE ov, D3DVALUE su, D3DVALUE sv);

Direct3DRMWrapオブジェクトを初期化する。

成功するとD3DRM_OK、失敗するとエラーを返す。返値の一覧については、｢Direct3D保持モードの返値｣を参照すること。

d3drmwt

D3DRMWRAPTYPE列挙型のメンバのひとつ。

lpd3drmfRef

このDirect3DRMWrapオブジェクトの参照フレームを示すDirect3DRMFrameオブジェクトのアドレス。

ox, oy, oz

ラップの原点。

dx, dy, dz

ラップのz軸。

ux, uy, uz

ラップのy軸。

ou, ov

テクスチャの原点。

su および sv

テクスチャの縮尺係数。

参照　IDirect3DRM::CreateWrap


構造体


D3DRMBOX

typedef struct _D3DRMBOX {

    D3DVECTOR min, max;

}D3DRMBOX;

typedef D3DRMBOX *LPD3DRMBOX;

IDirect3DRMMesh::GetBoxやIDirect3DRMMeshBuilder::GetBoxメソッドで取得する矩形範囲を定義する。

min, #max

矩形範囲を定義する値。これらの値はD3DVECTOR構造体である。

参照　D3DVECTOR, IDirect3DRMMesh::GetBox, IDirect3DRMMeshBuilder::GetBox


D3DRMIMAGE

typedef struct _D3DRMIMAGE {

    int                width, height;

    int                aspectx, aspecty;

    int                depth;

    int                rgb;

    int                bytes_per_line;

    void*              buffer1;

    void*              buffer2;

    unsigned long      red_mask;

    unsigned long      green_mask;

    unsigned long      blue_mask;

    unsigned long      alpha_mask;

    int                palette_size;

    D3DRMPALETTEENTRY* palette;

}D3DRMIMAGE;

typedef D3DRMIMAGE, *LPD3DRMIMAGE;

IDirect3DRM::CreateTextureメソッドによってテクスチャにアタッチされるイメージを記述する。IDirect3DRMTexture::GetImageは、このイメージのアドレスを返す。

width およびheight

ピクセル単位でのイメージの幅と高さ。

aspectx およびaspecty

非正方形ピクセルのアスペクト比。

depth

ピクセル当たりのビット数。

rgb

このメンバがFALSEの場合、ピクセルはパレットのインデックスを示す。このメンバがTRUEのときは、ピクセルはコード化されたRGB値である。

bytes_per_line

1ライン当たりのバイト数。この値は4の倍数である。

buffer1

レンダリングが行われるメモリ（最初のバッファ）のアドレス。

buffer2

2重バッファリングの2番目のレンダリング・バッファ。シングル・バッファリングのときはNULLを設定する。

red_mask, #green_mask, #blue_mask, #alpha_mask

rgbがTRUEのとき、これらのメンバはピクセルの赤、緑、青部分のマスクである。rgbがFALSEのときは、パレット中で重要な赤、緑、青の各要素ビットのマスクである。たとえば多くの SVGAディスプレイでは、使用する赤、緑、青の度合は64であるため、すべてのマスクは0xfcにセットされる。

palette_size

パレット・エントリの数。

palette

rgbがFALSEの場合、このメンバはパレット・エントリを示すD3DRMPALETTEENTRY構造体のアドレスである。

参照　IDirect3DRM::CreateTexture, IDirect3DRMTexture::GetImage


D3DRMLOADMEMORY

typedef struct _D3DRMLOADMEMORY {

    LPVOID lpMemory;

    DWORD  dSize;

} D3DRMLOADMEMORY, *LPD3DRMLOADMEMORY;

アプリケーションがD3DRMLOAD_FROMMEMORYを指定してIDirect3DRM::Loadメソッド（または他のLoadメソッド）を呼び出したときにロードされるリソースを示す。

lpMemory

ロードされるメモリ・ブロック。

dSize

ロードされるメモリ・ブロックのサイズをバイト単位で示す。

参照　IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load, D3DRMLOADOPTIONS, D3DRMLOADRESOURCE


D3DRMLOADRESOURCE

typedef struct _D3DRMLOADRESOURCE {

    HMODULE hModule;

    LPCTSTR lpName;

    LPCTSTR lpType;

} D3DRMLOADRESOURCE, *LPD3DRMLOADRESOURCE;

アプリケーションがD3DRMLOAD_FROMRESOURCEを指定してIDirect3DRM::Loadメソッド（または他のLoadメソッドのひとつ）を呼び出したときにロードされるリソースを示す。

hModule

ロードされるリソースを含むモジュールのハンドル。リソースが呼び出し元の実行可能ファイルにアタッチされているときは、このメンバにNULLを指定する。

lpName

ロードされるリソースの名前。たとえば、リソースがメッシュであれば、このメンバにメッシュ・ファイルの名前を指定する。

lpType

リソースを識別するユーザ定義のタイプ。

lpNameやlpTypeメンバの上位ワードが0の場合、下位ワードは、その名前の整数識別子または指定されたリソースのタイプを示す。そうでなければ、これらのパラメータはNULLで終わる文字列へのロング・ポインタである。文字列の先頭文字がシャープ記号（#）のときは、残りの文字はリソースの名前やタイプの整数識別子を示す10進数を表す。たとえば、文字列�#258�は整数識別子258を表す。名前の代わりに整数識別子を参照すれば、リソースが必要とするメモリの量を減らすことができる。

D3DRMLOAD_FROMRESOURCEを指定してLoadメソッドを呼び出せば、アプリケーションでリソースを探したりアンロックする必要はない。この場合、システムが自動的にその処理を行う。

参照　IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load, D3DRMLOADMEMORY, D3DRMLOADOPTIONS


D3DRMPALETTEENTRY

typedef struct _D3DRMPALETTEENTRY {

    unsigned char red;

    unsigned char green;

    unsigned char blue;

    unsigned char flags;

}D3DRMPALETTEENTRY;

typedef D3DRMPALETTEENTRY, *LPD3DRMPALETTEENTRY;

D3DRMIMAGE構造体で使用されるカラー・パレットを記述する。この構造体は、D3DRMIMAGE構造体のrgbメンバにFALSEが指定されているときのみ利用される（TRUEが指定されているときは、RGB値が用いられる）。

red, #green, #blue

パレットを定義する原色要素を定義する値。0から255の範囲の値を指定することができる。

flags

レンダリング時にパレットがどのように使用されるかを定義する値。この値はD3DRMPALETTEFLAGS列挙型のメンバのひとつである。

参照　D3DRMIMAGE, D3DRMPALETTEFLAGS


D3DRMPICKDESC

typedef struct _D3DRMPICKDESC {

    ULONG       ulFaceIdx;

    LONG        lGroupIdx;

    D3DVECTOR   vPosition;

} D3DRMPICKDESC, *LPD3DRMPICKDESC;

IDirect3DRMPickedArray::GetPickメソッドによって取得された、ピックの位置、面、グループ識別子を格納する。

ulFaceIdx

取得されたオブジェクトの面のインデックス。

lGroupIdx

取得されたオブジェクトのグループ識別子。

vPosition

取得されたオブジェクトの位置を示す値。この値はD3DVECTOR構造体である。

参照　D3DVECTOR, IDirect3DRMPickedArray::GetPick


D3DRMQUATERNION

typedef struct _D3DRMQUATERNION {

    D3DVALUE   s;

    D3DVECTOR  v;

}D3DRMQUATERNION;

typedef D3DRMQUATERNION, *LPD3DRMQUATERNION;

IDirect3DRMAnimation::AddRotateKeyメソッドで用いられる回転を記述する。また、Direct3Dの数学関数のいくつかでも使用される。

参照　IDirect3DRMAnimation::AddRotateKey, D3DRMQuaternionFromRotation, D3DRMQuaternionMultiply, D3DRMQuaternionSlerp, D3DRMMatrixFromQuaternion


D3DRMVECTOR4D

typedef struct _D3DRMVECTOR4D {

    D3DVALUE x;

    D3DVALUE y;

    D3DVALUE z;

    D3DVALUE w;

}D3DRMVECTOR4D;

typedef D3DRMVECTOR4D, *LPD3DRMVECTOR4D;

スクリーン座標を記述する。この構造体は、IDirect3DRMViewport::Transformメソッドによる変換の出力先として、およびIDirect3DRMViewport::InverseTransformメソッドによる変換のソースとして使用される。

x, #y, #z, #w

D3DVALUE型の値。変換結果が入る。

参照　IDirect3DRMViewport::Transform, IDirect3DRMViewport::InverseTransform


D3DRMVERTEX

typedef struct _D3DRMVERTEX{

    D3DVECTOR position;

    D3DVECTOR normal;

    D3DVALUE  tu, tv;

    D3DCOLOR  color;

} D3DRMVERTEX;

Direct3DRMMeshオブジェクト中の頂点を記述する。

position

頂点の位置。

normal

頂点の法線ベクトル。

tu および #tv

頂点の水平および垂直テクスチャ座標。

color

頂点の色。

参照　IDirect3DRMMesh::GetVertices, IDirect3DRMMesh::SetVertices


列挙型


D3DRMCOLORSOURCE

typedef enum _D3DRMCOLORSOURCE{

    D3DRMCOLOR_FROMFACE,

    D3DRMCOLOR_FROMVERTEX

} D3DRMCOLORSOURCE;

Direct3DRMMeshBuilderオブジェクトのカラー・ソースを記述する。カラー・ソースを設定するには、IDirect3DRMMeshBuilder::SetColorSource を使用する。カラー・ソースを取得するには、IDirect3DRMMeshBuilder::GetColorSourceメソッドを使用する。

D3DRMCOLOR_FROMFACE

オブジェクトのカラー・ソースは面である。

D3DRMCOLOR_FROMVERTEX

オブジェクトのカラー・ソースは頂点である。

参照　IDirect3DRMMeshBuilder::SetColorSource, IDirect3DRMMeshBuilder::GetColorSource


D3DRMCOMBINETYPE

typedef enum _D3DRMCOMBINETYPE{

    D3DRMCOMBINE_REPLACE,

    D3DRMCOMBINE_BEFORE,

    D3DRMCOMBINE_AFTER

} D3DRMCOMBINETYPE;

ふたつの行列の合成方法を指定する。

D3DRMCOMBINE_REPLACE

与えられた行列により、フレームの現在の行列を置き換える。

D3DRMCOMBINE_BEFORE

与えられた行列とフレームの現在の行列の積を求める。計算においては、与えられた行列が現在の行列よりも先に指定される。

D3DRMCOMBINE_AFTER

与えられた行列とフレームの現在の行列の積を求める。計算においては、与えられた行列が現在の行列の後に指定される。

行列の乗算は可換ではないため、与えられた行列と現在の行列を掛け合わせる順序は重要である。

参照　IDirect3DRMFrame::AddRotation, IDirect3DRMFrame::AddScale, IDirect3DRMFrame::AddTransform, IDirect3DRMFrame::AddTranslation


D3DRMFILLMODE

typedef enum _D3DRMFILLMODE {

    D3DRMFILL_POINTS    = 0 * D3DRMLIGHT_MAX,

    D3DRMFILL_WIREFRAME = 1 * D3DRMLIGHT_MAX,

    D3DRMFILL_SOLID     = 2 * D3DRMLIGHT_MAX,

    D3DRMFILL_MASK      = 7 * D3DRMLIGHT_MAX,

    D3DRMFILL_MAX       = 8 * D3DRMLIGHT_MAX

} D3DRMFILLMODE;

D3DRMRENDERQUALITY型の定義で使われる列挙型のひとつ。

D3DRMFILL_POINTS

点のみを塗りつぶす。最小の塗りつぶしモード。

D3DRMFILL_WIREFRAME

ワイヤーフレームを塗る。

D3DRMFILL_SOLID

立体オブジェクトを塗る。

D3DRMFILL_MASK

マスクを使用して塗る。

D3DRMFILL_MAX

塗りつぶしモードの最大値。

参照　D3DRMLIGHTMODE, D3DRMSHADEMODE, D3DRMRENDERQUALITY


D3DRMFOGMODE

typedef enum _D3DRMFOGMODE{

    D3DRMFOG_LINEAR,

    D3DRMFOG_EXPONENTIAL,

    D3DRMFOG_EXPONENTIALSQUARED

} D3DRMFOGMODE;

カメラからの距離が広がるにつれ、フォグ効果がどのくらいの速さでどのように強くなるかを示す。

D3DRMFOG_LINEAR

フォグ効果は、始点から終点までの間に比例的に強くなる。次の公式で表わされる。

現在サポートされているフォグ・モードは、これだけである。

D3DRMFOG_EXPONENTIAL

フォグ効果は、指数関数的に強くなる。次の公式で表わされる 。

D3DRMFOG_EXPONENTIALSQUARED

フォグ効果は、距離の2乗に比例して指数関数的に強くなる。次の公式で表わされる。

フォグは視界の基準と見なされることに注意しなくてはならない。方程式のひとつから求められるフォグ値が低いほど、オブジェクトは見えにくくなる。

フォグの密度、始点、終点は、IDirect3DRMFrame::SetSceneFogParams メソッドによって指定することができる。指数フォグ・モードの方程式では、eは自然対数の底を表し、その値は約2.71828である。

参照　IDirect3DRMFrame::SetSceneFogMode, IDirect3DRMFrame::SetSceneFogParams


D3DRMFRAMECONSTRAINT

typedef enum _D3DRMFRAMECONSTRAINT {

    D3DRMCONSTRAIN_Z,

    D3DRMCONSTRAIN_Y,

    D3DRMCONSTRAIN_X

} D3DRMFRAMECONSTRAINT;

Direct3DRMFrameオブジェクトを表示するときに強制的に回転する軸を記述する。この列挙型はIDirect3DRMFrame::LookAtメソッドによって使用される。

D3DRMCONSTRAIN_Z

xおよびy回転のみ使用する。

D3DRMCONSTRAIN_Y

xおよびz回転のみ使用する。

D3DRMCONSTRAIN_X

yおよびz回転のみ使用する。

参照　IDirect3DRMFrame::LookAt


D3DRMLIGHTMODE

typedef enum _D3DRMLIGHTMODE {

    D3DRMLIGHT_OFF      = 0 * D3DRMSHADE_MAX,

    D3DRMLIGHT_ON       = 1 * D3DRMSHADE_MAX,

    D3DRMLIGHT_MASK     = 7 * D3DRMSHADE_MAX,

    D3DRMLIGHT_MAX      = 8 * D3DRMSHADE_MAX

} D3DRMLIGHTMODE;

D3DRMRENDERQUALITY型の定義で使われる列挙型のひとつ。

D3DRMLIGHT_OFF

光源はオフである。

D3DRMLIGHT_ON

光源はオンである。

D3DRMLIGHT_MASK

光源はマスクを使用する。

D3DRMLIGHT_MAX

光源モードの最大値。

参照　D3DRMFILLMODE, D3DRMSHADEMODE, D3DRMRENDERQUALITY


D3DRMLIGHTTYPE

typedef enum _D3DRMLIGHTTYPE{

    D3DRMLIGHT_AMBIENT,

    D3DRMLIGHT_POINT,

    D3DRMLIGHT_SPOT,

    D3DRMLIGHT_DIRECTIONAL,

    D3DRMLIGHT_PARALLELPOINT

} D3DRMLIGHTTYPE;

IDirect3DRM::CreateLightメソッドの呼び出しで、光源タイプを定義する。

D3DRMLIGHT_AMBIENT

アンビエント光源。

D3DRMLIGHT_POINT

ポイント 光源。

D3DRMLIGHT_SPOT

スポットライト光源。

D3DRMLIGHT_DIRECTIONAL

有向光源。

D3DRMLIGHT_PARALLELPOINT

パラレル・ポイント光源。


D3DRMMATERIALMODE

typedef enum _D3DRMMATERIALMODE{

    D3DRMMATERIAL_FROMMESH,

    D3DRMMATERIAL_FROMPARENT,

    D3DRMMATERIAL_FROMFRAME

} D3DRMMATERIALMODE;

マテリアルモードを示す。この型は、IDirect3DRMFrame::GetMaterialModeメソッドによって取得され、IDirect3DRMFrame::SetMaterialModeメソッドによって設定される。

D3DRMMATERIAL_FROMMESH

マテリアル情報はビジュアル・オブジェクト（メッシュ）そのものから取得される。これはデフォルト設定である。

D3DRMMATERIAL_FROMPARENT

マテリアル情報は、色やテクスチャ情報とともに親フレームから継承される。

D3DRMMATERIAL_FROMFRAME

マテリアル情報はフレームから取得され、ビジュアル・オブジェクトが保持していた以前の情報をオーバーライドする。

参照　IDirect3DRMFrame::GetMaterialMode, IDirect3DRMFrame::SetMaterialMode


D3DRMPALETTEFLAGS

typedef enum _D3DRMPALETTEFLAGS {

    D3DRMPALETTE_FREE,

    D3DRMPALETTE_READONLY,

    D3DRMPALETTE_RESERVED

} D3DRMPALETTEFLAGS;

D3DRMPALETTEENTRY構造体での色の使用方法を定義する。

D3DRMPALETTE_FREE

レンダラーはこのエントリを自由に使用できる。

D3DRMPALETTE_READONLY

固定されているが、レンダラーが使うことができる。

D3DRMPALETTE_RESERVED

レンダラーが使うことはできない。

参照　D3DRMPALETTEENTRY


D3DRMPROJECTIONTYPE

typedef enum _D3DRMPROJECTIONTYPE{

    D3DRMPROJECT_PERSPECTIVE,

    D3DRMPROJECT_ORTHOGRAPHIC

} D3DRMPROJECTIONTYPE;

Direct3DRMViewportオブジェクトで使用される射影タイプを定義する。この列挙型は、IDirect3DRMViewport::GetProjectionとIDirect3DRMViewport::SetProjectionメソッドによって用いられる。

D3DRMPROJECT_PERSPECTIVE

透視投影。

D3DRMPROJECT_ORTHOGRAPHIC

平行投影。

参照　IDirect3DRMViewport::GetProjection, IDirect3DRMViewport::SetProjection


D3DRMRENDERQUALITY

typedef enum _D3DRMSHADEMODE {

    D3DRMSHADE_FLAT        = 0,

    D3DRMSHADE_GOURAUD     = 1,

    D3DRMSHADE_PHONG       = 2,

    D3DRMSHADE_MASK        = 7,

    D3DRMSHADE_MAX         = 8

} D3DRMSHADEMODE;

typedef enum _D3DRMLIGHTMODE {

    D3DRMLIGHT_OFF          = 0 * D3DRMSHADE_MAX,

    D3DRMLIGHT_ON           = 1 * D3DRMSHADE_MAX,

    D3DRMLIGHT_MASK         = 7 * D3DRMSHADE_MAX,

    D3DRMLIGHT_MAX          = 8 * D3DRMSHADE_MAX

} D3DRMLIGHTMODE;

typedef enum _D3DRMFILLMODE {

    D3DRMFILL_POINTS        = 0 * D3DRMLIGHT_MAX,

    D3DRMFILL_WIREFRAME     = 1 * D3DRMLIGHT_MAX,

    D3DRMFILL_SOLID         = 2 * D3DRMLIGHT_MAX,

    D3DRMFILL_MASK          = 7 * D3DRMLIGHT_MAX,

    D3DRMFILL_MAX           = 8 * D3DRMLIGHT_MAX

} D3DRMFILLMODE;

typedef DWORD D3DRMRENDERQUALITY;

#define D3DRMRENDER_WIREFRAME   (D3DRMSHADE_FLAT+D3DRMLIGHT_OFF+D3DRMFILL_WIREFRAME)

#define D3DRMRENDER_UNLITFLAT   (D3DRMSHADE_FLAT+D3DRMLIGHT_OFF+D3DRMFILL_SOLID)

#define D3DRMRENDER_FLAT        (D3DRMSHADE_FLAT+D3DRMLIGHT_ON+D3DRMFILL_SOLID)

#define D3DRMRENDER_GOURAUD     (D3DRMSHADE_GOURAUD+D3DRMLIGHT_ON+D3DRMFILL_SOLID)

#define D3DRMRENDER_PHONG       (D3DRMSHADE_PHONG+D3DRMLIGHT_ON+D3DRMFILL_SOLID)

Direct3DRMMeshオブジェクトのシェーディング・モード、光源モード、塗りつぶしモードを結合する。

D3DRMSHADEMODE, D3DRMLIGHTMODE, D3DRMFILLMODE

シェーディング、光源、塗りつぶしモードを示す。

D3DRMRENDER_WIREFRAME

辺のみを表示する。

D3DRMRENDER_UNLITFLAT

光源なしのフラット・シェーディング。

D3DRMRENDER_FLAT

フラット・シェーディング。

D3DRMRENDER_GOURAUD

グーロー・シェーディング。

D3DRMRENDER_PHONG

フォン・シェーディング。このシェーディング・モードは現在はサポートされていない。

参照　IDirect3DRMMesh::GetGroupQuality, IDirect3DRMMesh::SetGroupQuality


D3DRMSHADEMODE

typedef enum _D3DRMSHADEMODE {

    D3DRMSHADE_FLAT     = 0,

    D3DRMSHADE_GOURAUD  = 1,

    D3DRMSHADE_PHONG    = 2,

    D3DRMSHADE_MASK     = 7,

    D3DRMSHADE_MAX      = 8

} D3DRMSHADEMODE;

D3DRMRENDERQUALITY 型の定義で使われる列挙型のひとつ。

参照　D3DRMFILLMODE, D3DRMLIGHTMODE, D3DRMRENDERQUALITY


D3DRMSORTMODE

typedef enum _D3DRMSORTMODE {

    D3DRMSORT_FROMPARENT,

    D3DRMSORT_NONE,

    D3DRMSORT_FRONTTOBACK,

    D3DRMSORT_BACKTOFRONT

} D3DRMSORTMODE;

シーン上にどのように子フレームが分類されるかを示す。

D3DRMSORT_FROMPARENT

子フレームは親フレームのソート順序を継承する。これはデフォルト設定である。

D3DRMSORT_NONE

子フレームはソートされない。

D3DRMSORT_FRONTTOBACK

子フレームは前から後ろへソートされる。

D3DRMSORT_BACKTOFRONT

子フレームは後ろから前へソートされる。

参照　IDirect3DRMFrame::GetSortMode,

IDirect3DRMFrame::SetSortMode


D3DRMTEXTUREQUALITY

typedef enum _D3DRMTEXTUREQUALITY{

    D3DRMTEXTURE_NEAREST,

    D3DRMTEXTURE_LINEAR,

    D3DRMTEXTURE_MIPNEAREST,

    D3DRMTEXTURE_MIPLINEAR,

    D3DRMTEXTURE_LINEARMIPNEAREST,

    D3DRMTEXTURE_LINEARMIPLINEAR

} D3DRMTEXTUREQUALITY;

IDirect3DRMDevice::SetTextureQualityやIDirect3DRMDevice::GetTextureQualityメソッドで用いられるテクスチャ品質を記述する。

D3DRMTEXTURE_NEAREST

テクスチャ上の最も近いピクセルを選択する。

D3DRMTEXTURE_LINEAR

最も近い4つのピクセルを線形に補完する。

D3DRMTEXTURE_MIPNEAREST

D3DRMTEXTURE_NEARESTに似ているが、テクスチャの代わりに適切なミップマップを使用する。

D3DRMTEXTURE_MIPLINEAR

D3DRMTEXTURE_ LINEARに似ているが、テクスチャの代わりに適切なミップマップを使用する。

D3DRMTEXTURE_LINEARMIPNEAREST

D3DRMTEXTURE_ MIPNEARESTに似ているが、最も近いふたつのミップマップ間を補完する。

D3DRMTEXTURE_LINEARMIPLINEAR

D3DRMTEXTURE_ MIPLINEARに似ているが、最も近いふたつのミップマップ間を補間する。


D3DRMUSERVISUALREASON

typedef enum _D3DRMUSERVISUALREASON {

    D3DRMUSERVISUAL_CANSEE,

    D3DRMUSERVISUAL_RENDER

} D3DRMUSERVISUALREASON;

システムがD3DRMUSERVISUALCALLBACKコールバック関数を呼び出した理由を定義する。

D3DRMUSERVISUAL_CANSEE

ユーザ・ビジュアルオブジェクトがビューポート上で可視状態であれば、コールバック関数はTRUEを返さなくてはならない。

D3DRMUSERVISUAL_RENDER

コールバック関数はユーザ・ビジュアル・オブジェクトをレンダリングしなくてはならない。

参照　D3DRMUSERVISUALCALLBACK


D3DRMWRAPTYPE

typedef enum _D3DRMWRAPTYPE{

    D3DRMWRAP_FLAT,

    D3DRMWRAP_CYLINDER,

    D3DRMWRAP_SPHERE,

    D3DRMWRAP_CHROME

} D3DRMWRAPTYPE;

IDirect3DRM::CreateWrapメソッドによって作成されるDirect3DRMWrapオブジェクトのタイプを定義する。またIDirect3DRMWrap::Initメソッドの呼び出しの中で、Direct3DRMWrapオブジェクトを初期化するためにこの列挙型を使用することができる。

D3DRMWRAP_FLAT

平面ラップ。

D3DRMWRAP_CYLINDER

円柱ラップ。

D3DRMWRAP_SPHERE

球体ラップ。

D3DRMWRAP_CHROME

ラップは、テクスチャがオブジェクト上で反射されるようにテクスチャ座標を割り当てる。

参照　IDirect3DRM::CreateWrap, IDirect3DRMWrap::Init, IDirect3DRMWrapインターフェイス


D3DRMXOFFORMAT

typedef enum _D3DRMXOFFORMAT{

    D3DRMXOF_BINARY,

    D3DRMXOF_COMPRESSED,

    D3DRMXOF_TEXT

} D3DRMXOFFORMAT;

IDirect3DRMMeshBuilder::Saveメソッドで使用されるファイル・タイプを定義する。

D3DRMXOF_BINARY

ファイルはバイナリ・フォーマットである。これはデフォルト設定である。

D3DRMXOF_COMPRESSED

現在はサポートされていない。

D3DRMXOF_TEXT

ファイルはテキスト・フォーマットである。

D3DRMXOF_BINARYとD3DRMXOF_TEXT設定を同時に使用することはできない。

参照　IDirect3DRMMeshBuilder::Save


D3DRMZBUFFERMODE

typedef enum _D3DRMZBUFFERMODE {

    D3DRMZBUFFER_FROMPARENT,

    D3DRMZBUFFER_ENABLE,

    D3DRMZBUFFER_DISABLE

} D3DRMZBUFFERMODE;

Zバッファが有効かどうかを示す。

D3DRMZBUFFER_FROMPARENT

フレームは親フレームからZバッファの設定を継承する。これはデフォルト設定である。

D3DRMZBUFFER_ENABLE

Zバッファは有効である。

D3DRMZBUFFER_DISABLE

Zバッファは無効である。

参照　IDirect3DRMFrame::GetZbufferMode, IDirect3DRMFrame::SetZbufferMode


その他の型


D3DRMANIMATIONOPTIONS

typedef DWORD D3DRMANIMATIONOPTIONS;

#define D3DRMANIMATION_CLOSED             0x02L

#define D3DRMANIMATION_LINEARPOSITION     0x04L

#define D3DRMANIMATION_OPEN               0x01L

#define D3DRMANIMATION_POSITION           0x00000020L

#define D3DRMANIMATION_SCALEANDROTATION   0x00000010L

#define D3DRMANIMATION_SPLINEPOSITION     0x08L

アニメーションの再生方法を定義する値を指定する。IDirect3DRMAnimation::GetOptionsやIDirect3DRMAnimation::SetOptionsで用いられる。

D3DRMANIMATION_CLOSED

アニメーションは繰り返し再生され、終点に達すると開始点に戻ってループする。閉じられたアニメーションでは、アニメーションの最後のキーは最初のキーの繰り返しでなくてはならない。この繰り返しキーを利用して、ループするアニメーションにおける最後と最初のキー間の時間の差が表される。

D3DRMANIMATION_LINEARPOSITION

アニメーションの位置は線形に設定される。

D3DRMANIMATION_OPEN

アニメーションは1回だけ再生され、停止する。

D3DRMANIMATION_POSITION

アニメーションの位置行列によって、他のメソッドが設定するどんな変換行列も上書される。

D3DRMANIMATION_SCALEANDROTATION

アニメーションの縮尺と回転行列によって、他のメソッドが設定するどんな変換行列も上書きされる。

D3DRMANIMATION_SPLINEPOSITION

アニメーションの位置はスプラインで設定される。


D3DRMCOLORMODEL

typedef D3DCOLORMODEL D3DRMCOLORMODEL;

デバイスがインプリメントするカラー・モデルを示す。詳細についてはD3DCOLORMODEL列挙型を参照すること。

参照　D3DCOLORMODEL


D3DRMLOADOPTIONS

typedef DWORD D3DRMLOADOPTIONS;

#define D3DRMLOAD_FROMFILE             0x00L

#define D3DRMLOAD_FROMRESOURCE         0x01L

#define D3DRMLOAD_FROMMEMORY           0x02L

#define D3DRMLOAD_FROMSTREAM           0x03L

#define D3DRMLOAD_BYNAME               0x10L

#define D3DRMLOAD_BYPOSITION           0x20L

#define D3DRMLOAD_BYGUID               0x30L

#define D3DRMLOAD_FIRST                0x40L

#define D3DRMLOAD_INSTANCEBYREFERENCE  0x100L

#define D3DRMLOAD_INSTANCEBYCOPYING    0x200L

IDirect3DRM::Load、 IDirect3DRMAnimationSet::Load、IDirect3DRMFrame::Load、およびIDirect3DRMMeshBuilder::Loadメソッドのオプションを定義する。これらのオプションは、オブジェクトがロードされる方法を変更する。

ソース・フラグ

D3DRMLOAD_FROMFILE

ファイルからロードする。これはデフォルト設定である。

D3DRMLOAD_FROMRESOURCE

リソースからロードする。このフラグを指定した場合、Loadメソッドの呼び出しのlpvObjSourceパラメータは、D3DRMLOADRESOURCE構造体を指さなくてはならない。

D3DRMLOAD_FROMMEMORY

メモリからロードする。このフラグを指定した場合、Loadメソッドの呼び出しの lpvObjSource パラメータは、D3DRMLOADMEMORY構造体を指さなくてはならない。

D3DRMLOAD_FROMSTREAM

ストリームからロードする。

識別子フラグ

D3DRMLOAD_BYNAME

指定された名前を使用してオブジェクトをロードする。

D3DRMLOAD_BYPOSITION

与えられた、0から始まる位置に、スタンド・アロンのオブジェクトをロードする（つまり、ファイル中のn番目のオブジェクトをロードする）。スタンド・アロンのオブジェクトは他のオブジェクトを含むことができるが、他のオブジェクトに含まれることはない。

D3DRMLOAD_BYGUID

指定されたグローバル・ユニーク識別子（GUID）を使用してオブジェクトをロードする。

D3DRMLOAD_FIRST

これはデフォルト設定である。与えられたタイプのスタンド・アロンのオブジェクトをロードする（たとえば、アプリケーションがIDirect3DRMMeshBuilder::Loadを呼び出す場合はメッシュをロードする）。スタンド・アロンのオブジェクトは他のオブジェクトを含むことができるが、他のオブジェクトに含まれることはない。

インスタンス・フラグ

D3DRMLOAD_INSTANCEBYREFERENCE

指定された名前と同じ名前のオブジェクトが存在するかどうかをチェックする。存在する場合、新しいオブジェクトを作成する代わりに、そのオブジェクトのインスタンスを使用する。

D3DRMLOAD_INSTANCEBYCOPYING

指定された名前と同じ名前のオブジェクトが存在するかどうかをチェックする。存在する場合、新しいオブジェクトを作成する代わりに、そのオブジェクトをコピーする。

各Loadメソッドは、lpvObjSourceパラメータを使用してオブジェクトのソースを指定し、lpvObjIDパラメータによってオブジェクトを識別する。システムはソース・フラグの選択に基づいてlpvObjSourceパラメータを解釈する。そして、識別子フラグの選択に基づいてlpvObjIDパラメータの内容を解釈する。

インスタンス・フラグは、パラメータの解釈方法には何も変更を加えない。D3DRMLOAD_INSTANCEBYREFERENCEフラグを用いると、新しいオブジェクトを作成することなく同じファイルを2回ロードすることができる。オブジェクトが名前を持っていない場合、D3DRMLOAD_INSTANCEBYREFERENCEフラグをセットすると、D3DRMLOAD_INSTANCEBYCOPYINGフラグをセットしたときと同じ効果を得ることができる。ローダは、同一のオブジェクトが存在しても、各名前なしオブジェクトを新しいオブジェクトとして作成する。


D3DRMMAPPING

typedef DWORD D3DRMMAPPING, D3DRMMAPPINGFLAG;

static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPU = 1;

static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPV = 2;

static const D3DRMMAPPINGFLAG D3DRMMAP_PERSPCORRECT = 4;

テクスチャのグループへのマッピング方法を定義する値。IDirect3DRMMesh::GetGroupMappingやIDirect3DRMMesh::SetGroupMappingメソッドによって用いられる。

D3DRMMAPPINGFLAG

D3DRMMAPPINGと型が同じ。

D3DRMMAP_WRAPU

u方向にテクスチャをラップする。

D3DRMMAP_WRAPV

v方向にテクスチャをラップする。

D3DRMMAP_PERSPCORRECT

テクスチャ・ラッピングは遠近補正される。

D3DRMMAP_WRAPUとD3DRMMAP_WRAPVフラグは、ラスタライザがテクスチャ座標を解釈する方法を決定する。ラスタライザはつねに、テクスチャ座標で最も短い距離、つまり直線を補完する。この直線のパスと、uおよびv座標の有効値は、ラッピング・フラグの使い方によって異なる。一方または両方のフラグがセットされると、直線はuまたはv方向のテクスチャの辺をラップ・アラウンドする。この場合、テクスチャは円柱状かドーナツ上の位相を持っているかのように見える。詳細については「IDirect3DRMWrapインターフェイス」を参照すること。

参照　Direct3DRMWrapインターフェイス, IDirect3DRMMesh::GetGroupMapping, IDirect3DRMMesh::SetGroupMapping


D3DRMMATRIX4D

typedef D3DVALUE D3DRMMATRIX4D[4][4];

変換を行列として表す。行列エントリは、D3DRMMATRIX4D[row][column]から構成される。

参照　IDirect3DRMFrame::AddTransform, IDirect3DRMFrame::GetTransform


D3DRMSAVEOPTIONS

typedef DWORD D3DRMSAVEOPTIONS;

#define D3DRMXOFSAVE_NORMALS 1

#define D3DRMXOFSAVE_TEXTURECOORDINATES 2

#define D3DRMXOFSAVE_MATERIALS 4

#define D3DRMXOFSAVE_TEXTURENAMES 8

#define D3DRMXOFSAVE_ALL 15

#define D3DRMXOFSAVE_TEMPLATES 16

IDirect3DRMMeshBuilder::Saveメソッドのオプションを定義する。

D3DRMXOFSAVE_NORMALS

基本的な面に加え、法線ベクトルを保存する。

D3DRMXOFSAVE_TEXTURECOORDINATES

基本的な面に加え、テクスチャ座標を保存する。

D3DRMXOFSAVE_MATERIALS

基本的な面に加え、マテリアルを保存する。

D3DRMXOFSAVE_TEXTURENAMES

基本的な面に加え、テクスチャの名前を保存する。

D3DRMXOFSAVE_ALL

基本的な面に加え、法線ベクトル、テクスチャ座標、マテリアル、テクスチャの名前を保存する。

D3DRMXOFSAVE_TEMPLATES

ファイルのテンプレートを保存する。デフォルトではテンプレートは保存されない。


返値

Direct3D保持モードのコンポーネント・オブジェクト・モデル（COM） インターフェイス・メソッドは、次の値を返す。

D3DRM_OK

	成功。

D3DRMERR_BADALLOC

	メモリ不足。

D3DRMERR_BADDEVICE

	デバイスはレンダラーと互換性がない。

D3DRMERR_BADFILE

	データファイルが不正。

D3DRMERR_BADMAJORVERSION

	DLLのメジャー・バージョンが不正。

D3DRMERR_BADMINORVERSION

	DLLのマイナー・バージョンが不正。

D3DRMERR_BADOBJECT

	引数にはオブジェクトが必要。

D3DRMERR_BADTYPE

	不正な型の引数が渡された。

D3DRMERR_BADVALUE

	不正な値の引数が渡された。

D3DRMERR_FACEUSED

	面はメッシュ上で使用済みである。

D3DRMERR_FILENOTFOUND

	ファイルを開くことができない。

D3DRMERR_NOTDONEYET

	実装されていない。

D3DRMERR_NOTFOUND

	指定された平面にオブジェクトが見つからない。

D3DRMERR_UNABLETOEXECUTE

	プロシージャを実行できない。


D3DDivide

D3DDivide(a, b)    (float)((double) (a) / (double) (b))

除算を行う。

割り算の商を返す。

a､b

式の分母と分子。

参照　D3DMultiply


D3DMultiply

D3DMultiply(a, b)    ((a) * (b))

乗算を行う。

2値の積を返す。

a､b

掛け合わされる値。

参照　D3DDivide


D3DRGB

D3DRGB(r, g, b) \

    (0xff000000L | ( ((long)((r) * 255)) << 16) | \

    (((long)((g) * 255)) << 8) | (long)((b) * 255))

RGB成分値を色の値に変換する。

RGB成分値をD3DCOLOR値に変換する。

r , g, b

色の赤(red)、緑(green)および青(blue)の要素。これらの値は、0から1の範囲の浮動小数点型である。

参照　D3DRGBA


D3DRGBA

D3DRGBA(r, g, b, a) \

    ((((long)((a) * 255)) << 24) | (((long)((r) * 255)) << 16) |

    (((long)((g) * 255)) << 8) | (long)((b) * 255))

RGBA成分値を色の値に変換する。

RGBA成分値をD3DCOLOR値に変換する。

r, g, b, a

色の赤(red)、緑(green)、青(blue)およびアルファ(alpha)の要素。

参照　D3DRGB


D3DSTATE_OVERRIDE

D3DSTATE_OVERRIDE(type) ((DWORD) (type) + D3DSTATE_OVERRIDE_BIAS)

ラスタ変換、ライティング、変換モジュールの状態をオーバーライドする。アプリケーションは、状態のロックと解除をこのマクロで行うことができる。

返値はない。

type

オーバーライドの状態。このパラメータはD3DTRANSFORMSTATETYPE、D3DLIGHTSTATETYPE、 D3DRENDERSTATETYPE 型のメンバのひとつである。

たとえば、STATE_DATAマクロ(DirectX SDKのサンプルコードのMisc/D3dmacs.hファイルで定義)を使い、D3DSTATE_OVERRIDEでD3DRENDERSTATE_SHADEMODEのレンダリングの状態のロックと解除を行う。

//  明度モードをロック

STATE_DATA(D3DSTATE_OVERRIDE(D3DRENDERSTATE_SHADEMODE), TRUE, lpBuffer);

//  リードオンリーでないとき、明度モードを実行しロック解除する

STATE_DATA(D3DSTATE_OVERRIDE(D3DRENDERSTATE_SHADEMODE), FALSE, lpBuffer);

レンダリングの状態のオーバーライドについての詳細は、「ステートとステート・オーバーライド」を参照すること。


D3DVAL

D3DVAL(val)    ((float)val)

D3DVALUE型の値に変換する。

変換後の値を返す。

val

変換される値。

参照　D3DVALP


D3DVALP

D3DVALP(val, prec)    ((float)val)

精度を変換する。

変換後の値を返す。

val

変換される値。

prec

無効。

D3DVALマクロの精度は、値の小数部分に対し16ビットである。

参照　D3DVAL


RGB_GETBLUE

RGB_GETBLUE(rgb)    ((rgb) & 0xff)

D3DCOLOR 値から青成分を取り出す。

青成分を返す。

rgb

青成分を取り出す色のD3DCOLOR値。


RGB_GETGREEN

RGB_GETGREEN(rgb)    (((rgb) >> 8) & 0xff)

D3DCOLOR値から緑成分を取り出す。

緑成分を返す。

rgb

緑成分を取り出す色のD3DCOLOR値。


RGB_GETRED

RGB_GETRED(rgb)    (((rgb) >> 16) & 0xff)

D3DCOLOR値から赤成分を取り出す。

赤成分を返す。

rgb

赤成分を取り出す色のD3DCOLOR値。


RGB_MAKE

RGB_MAKE(r, g, b)    ((D3DCOLOR) (((r) << 16) | ((g) << 8) | (b)))

成分値からRGB色を作成する。

色の値を返す。

r, g, b

作成される色の赤、緑、青の要素。値の範囲は0から255。


RGB_TORGBA

RGB_TORGBA(rgb)    ((D3DCOLOR) ((rgb) | 0xff000000))

RGB成分値からRGBA色を作成する。

RGBA色を返す。

rgb

RGBA色に変換するRGB色。

参照　RGBA_TORGB


RGBA_GETALPHA

RGBA_GETALPHA(rgb)    ((rgb) >> 24)

RGBAのD3DCOLOR値よりアルファ成分を取り出す。

アルファ成分値を返す。

rgb

アルファ成分を取り出す色のD3DCOLOR値。


RGBA_GETBLUE

RGB_GETBLUE(rgb)    ((rgb) & 0xff)

RGBAのD3DCOLOR値より青成分を取り出す。

青成分値を返す。

rgb

青成分を取り出す色のD3DCOLOR値。


RGBA_GETGREEN

RGB_GETGREEN(rgb)    (((rgb) >> 8) & 0xff)

RGBAのD3DCOLOR値より緑成分を取り出す。

緑成分値を返す。

rgb

緑成分を取り出す色のD3DCOLOR値。


RGBA_GETRED

RGB_GETRED(rgb)    (((rgb) >> 16) & 0xff)

RGBAのD3DCOLOR値より赤成分を取り出す。

赤成分値を返す。

rgb

赤成分を取り出す色のD3DCOLOR値。


RGBA_MAKE

RGBA_MAKE(r, g, b, a)   \

    ((D3DCOLOR) (((a) << 24) | ((r) << 16) | ((g) << 8) | (b)))

赤、緑、青、アルファ成分値より、RGBAのD3DCOLOR値を作成する。

色を返す。

r, g, b, a

作成されるRGBA色の赤、緑、青、アルファ成分値。


RGBA_SETALPHA

RGBA_SETALPHA(rgba, x)    (((x) << 24) | ((rgba) & 0x00ffffff))

RGBAのD3DCOLOR値にアルファ成分を設定する。

アルファ成分値が設定されたRGBA色を返す。

rgba

アルファ成分値が設定されるRGBA色。

x

設定するアルファ成分値。


RGBA_TORGB

RGBA_TORGB(rgba)    ((D3DCOLOR) ((rgba) & 0xffffff))

RGBAのD3DCOLOR成分値からアルファ成分を除いて、RGBのD3DCOLOR値を作成する。

RGB色を返す。

rgba

RGB色に変換するRGBA色。

参照　RGB_TORGBA


コールバック関数


D3DENUMDEVICESCALLBACK

typedef HRESULT (FAR PASCAL * LPD3DENUMDEVICESCALLBACK)

    (LPGUID lpGuid, LPSTR lpDeviceDescription,

    LPSTR lpDeviceName, LPD3DDEVICEDESC lpD3DHWDeviceDesc,

    LPD3DDEVICEDESC lpD3DHELDeviceDesc, LPVOID lpUserArg);

インストールされているDirect3Dデバイスを列挙するコールバック関数のプロトタイプ定義。

アプリケーションは、以下の値のいずれかを返す。

D3DENUMRET_CANCEL

	列挙を中止する。

D3DENUMRET_OK

	列挙を継続する。
lpGuid

グローバル・ユニーク識別子(GUID)へのポインタ。

lpDeviceDescription

デバイスの注釈へのポインタ。

lpDeviceName

デバイス名へのポインタ。

lpD3DHWDeviceDesc

Direct3Dデバイス・ハードウェア情報のD3DDEVICEDESC構造体へのポインタ。

lpD3DHELDeviceDesc

Direct3Dデバイス・エミュレーション情報のD3DDEVICEDESC構造体へのポインタ。

lpUserArg

このコールバック関数に渡されるアプリケーション定義データへのポインタ。

コールバック関数を呼び出す順序を決定するとき、システムは最初に最も高い階層のオブジェクトを検索して、次にそれらが作成された順序でコールバック関数を呼び出す。


D3DENUMTEXTUREFORMATSCALLBACK

typedef HRESULT (WINAPI* LPD3DENUMTEXTUREFORMATSCALLBACK)

    (LPDDSURFACEDESC lpDdsd, LPVOID lpUserArg);

テクスチャ・フォーマットを列挙するコールバック関数のプロトタイプ定義。

lpDdsd

テクスチャ情報を含むDirectDrawSurfaceオブジェクトへのポインタ。

lpUserArg

このコールバック関数に渡されるアプリケーション定義データへのポインタ。

コールバック関数を呼び出す順序を決定するとき、システムは最初に最も高い階層のオブジェクトを検索して、次にそれらが作成された順序でコールバック関数を呼び出す。


D3DVALIDATECALLBACK

typedef HRESULT (WINAPI* LPD3DVALIDATECALLBACK)

    (LPVOID lpUserArg, DWORD dwOffset);

アプリケーションが、IDirect3DExecuteBuffer::Validateメソッドを呼び出すときに与えられるアプリケーション定義コールバック関数である。このメソッドとは、エラーを検出したときに実行バッファのチェックやバッファのオフセットを返すデバッグ・ルーチンである。

lpUserArg

このコールバック関数に渡されるアプリケーション定義データへのポインタ。

dwOffset

システムがエラーを検出した実行バッファのオフセット。

コールバック関数を呼び出す順序を決定するとき、システムは最初に最も高い階層のオブジェクトを検索して、次にそれらが作成された順序でコールバック関数を呼び出す。


IDirect3D

IDirect3Dインターフェイスのメソッドを使うと、Direct3Dオブジェクトを作成したり、環境設定したりすることができる。この節では、IDirect3Dインターフェイスのメソッドについて説明する。概略については、「IDirect3Dインターフェイス」を参照すること。

IDirect3Dインターフェイスのメソッドは、次のグループからなる。

生成	CreateLight
	CreateMaterial
	CreateViewport
列挙	EnumDevices
初期化	FindDevice
	Initialize
IDirect3Dインターフェイスは、すべての COM インターフェイスのように、 IUnknown インターフェイス・メソッドを継承する。 IUnknown インターフェイスがサポートするメソッドは、次の通り。

AddRef
QueryInterface
Release


IDirect3D::CreateLight

HRESULT CreateLight(LPDIRECT3DLIGHT* lplpDirect3DLight,

    IUnknown* pUnkOuter);

Direct3DLightオブジェクトを割り当てる。このオブジェクトは、IDirect3DViewport::AddLightメソッドを使うとビューポートと結合することができる。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lplpDirect3DLight

成功すれば、IDirect3DLightインターフェイスへのポインタが設定されるポインタ。

pUnkOuter

このパラメータはCOM集成化機能と将来、互換性を取るためのものである。IDirect3D::CreateLightメソッドはこのパラメータがNULL以外のときエラーを返す。


IDirect3D::CreateMaterial

HRESULT CreateMaterial(LPDIRECT3DMATERIAL* lplpDirect3DMaterial,

    IUnknown* pUnkOuter);

Direct3DMaterialオブジェクトを割り当てる。

成功すれば、D3D_OKを返す。返値の一覧は、「Direct3D 直接モードの返値」を参照すること。

lplpDirect3DMaterial

呼び出しに成功すれば、IDirect3DMaterial インターフェイスへのポインタのアドレス。

pUnkOuter

このパラメータは、COM全体を将来、拡張するためのものである。IDirect3D::CreateMaterialメソッドは、このパラメータがNULL以外のときエラーを返す。


IDirect3D::CreateViewport

HRESULT CreateViewport(LPDIRECT3DVIEWPORT* lplpD3DViewport,

    IUnknown* pUnkOuter);

Direct3DViewportオブジェクトを生成する。このビューポートは、IDirect3DDevice::AddViewportメソッドで使用されるDirect3Dデバイスオブジェクトと結合される。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lplpD3DViewport

呼び出しに成功すれば、IDirect3DViewport インターフェイスへのポインタのアドレス。

pUnkOuter

このパラメータは、COM全体を将来、拡張するためのものである。IDirect3D::CreateViewportメソッドは、このパラメータがNULL以外のときエラーを返す。


IDirect3D::EnumDevices

HRESULT EnumDevices(LPD3DENUMDEVICESCALLBACK lpEnumDevicesCallback,

    LPVOID lpUserArg);

システムにインストールされているDirect3Dデバイス・ドライバすべてを列挙する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpEnumDevicesCallback

検出されるたびに呼び出される列挙処理のD3DENUMDEVICESCALLBACK コールバック関数へのポインタ。

lpUserArg

コールバック関数に渡すアプリケーション定義データへのポインタ。


IDirect3D::FindDevice

HRESULT FindDevice(LPD3DFINDDEVICESEARCH lpD3DFDS,

    LPD3DFINDDEVICERESULT lpD3DFDR);

指定された性質のデバイスを検出し、その情報を取得する。

成功すればD3D_OKが返される。返値については、「Direct3D 直接モードの返値」を参照すること。

lpD3DFDS

取得するデバイスを示すD3DFINDDEVICESEARCH構造体のポインタ。

lpD3DFDR

検出時にデバイスを示すD3DFINDDEVICERESULT 構造体のポインタ。


IDirect3D::Initialize

HRESULT Initialize(REFIID lpREFIID);

このメソッドは、COMプロトコルの一貫性を保つためのものである。

Direct3Dオブジェクトが生成されるときに初期化されるため、DDERR_ALREADYINITIALIZEDを返す。

lpREFIID

ユニバーサル・ユニーク識別子(UUID)へのポインタを返す。


IDirect3DDevice

IDirect3DDeviceインターフェイスのメソッドを使うと、Direct3Dオブジェクトの能力を回復したり設定したりすることができる。この節では、IDirect3DDeviceインターフェイスのメソッドについて説明する。概略については、「IDirect3DDeviceインターフェイス」を参照すること。

IDirect3DDeviceインターフェイスのメソッドは、次のグループからなる。

実行	CreateExecuteBuffer
	Execute
情報	EnumTextureFormats
	GetCaps
	GetDirect3D
	GetPickRecords
	GetStats
配列	CreateMatrix
	DeleteMatrix
	GetMatrix
	SetMatrix
その他	Initialize
	Pick
	SwapTextureHandles
シーン	BeginScene
	EndScene
ビューポート	AddViewport
	DeleteViewport
	NextViewport
IDirect3DDeviceインターフェイスは、すべての COM インターフェイスと同じく、 IUnknown インターフェイス・メソッドを継承する。 IUnknown インターフェイスがサポートするメソッドは、次の通り。

AddRef
QueryInterface
Release
Direct3DDeviceオブジェクトは、3D画面として生成されたDirectDrawSurfaceオブジェクトからIDirect3DDevice::QueryInterface メソッドを適切に呼び出すことで取得される。


IDirect3DDevice::AddViewport

HRESULT AddViewport(LPDIRECT3DVIEWPORT lpDirect3DViewport);

指定されたビューポートを、デバイスに配置されたビューポート・オブジェクトのリストに追加する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDirect3DViewport

Direct3Ddeviceオブジェクトに配置されたIDirect3DViewportインターフェイスへのポインタ。


IDirect3DDevice::BeginScene

HRESULT BeginScene();

シーンを開始する。

成功するとD3D_OKを返す。

アプリケーションは必ず、レンダリングの実行前にこのメソッドを呼び出すこと。また、レンダリング終了時には、IDirect3DDevice::EndSceneを呼び出すこと。

参照　IDirect3DDevice::EndScene


IDirect3DDevice::CreateExecuteBuffer

HRESULT CreateExecuteBuffer(LPDIRECT3DEXECUTEBUFFERDESC lpDesc,

    LPDIRECT3DEXECUTEBUFFER* lplpDirect3DExecuteBuffer,

    IUnknown* pUnkOuter);

表示リストに実行バッファを割り当てる。このリストは、ハードウェアのDMAによりVRAMに読み込まれる。頂点のインデックスを持つバッファ内のすべてのディスプレイ・プリミティブは、それらの頂点を同じバッファ内に持たなければならない。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDesc

生成されたDirect3DExecuteBufferオブジェクトを示すD3DEXECUTEBUFFERDESC構造体へのポインタ。このバッファのサイズが足りずオブジェクトが生成されないときには、呼び出しに失敗する。

lplpDirect3DExecuteBuffer

新しいDirect3DExecuteBufferオブジェクトへのポインタへのポインタ。

pUnkOuter

このパラメータは、COM全体を将来、拡張するためのものである。IDirect3DDevice::CreateExecuteBufferメソッドは、このパラメータがNULL以外のときエラーを返す。

D3DEXECUTEBUFFERDESC構造体は、生成された実行バッファを記述する。少なくともアプリケーションは、必要とされるサイズを指定しなければならない。アプリケーションが能力メンバのDEBCAPS_VIDEO_MEMORYを指定すると、Direct3Dは、ビデオ・メモリに実行バッファを保持しようとする。

アプリケーションはIDirect3DExecuteBuffer::Lockメソッドを使うと、メモリの移動を要求することができる。このメソッドが戻ったとき、データがシステム・メモリまたはビデオ・メモリのどちらかにあるかを表すD3DEXECUTEBUFFERDESC構造体の構成に合わせられる。


IDirect3DDevice::CreateMatrix

HRESULT CreateMatrix(LPD3DMATRIXHANDLE lpD3DMatHandle);

行列を作成する。

成功すればD3D_OK、失敗すれば、次の値を返す。

DDERR_INVALIDPARAMS
lpD3DMatHandle

作成された行列のハンドル変数へのポインタ。バッファのサイズが足りずに行列を生成できないときは、この呼び出しに失敗する。

参照　IDirect3DDevice::DeleteMatrix、 IDirect3DDevice::SetMatrix


IDirect3DDevice::DeleteMatrix

HRESULT DeleteMatrix(D3DMATRIXHANDLE d3dMatHandle);

行列のハンドルを削除する。この行列のハンドルは、IDirect3DDevice::CreateMatrixメソッドで作成されたものでなければならない。

成功すればD3D_OK、失敗すれば、次の値を返す。

DDERR_INVALIDPARAMS
d3dMatHandle

削除される行列のハンドル。

参照　IDirect3DDevice::CreateMatrix、 IDirect3DDevice::SetMatrix


IDirect3DDevice::DeleteViewport

HRESULT DeleteViewport(LPDIRECT3DVIEWPORT lpDirect3DViewport);

デバイスに関連したビューポート・オブジェクトのリストから、指定されたビューポートを削除する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDirect3DViewport

Direct3DDeviceオブジェクトから切り離すDirect3DViewportオブジェクトへのポインタ。


IDirect3DDevice::EndScene

HRESULT EndScene();

IDirect3DDevice::BeginScene メソッドの呼び出しにより開始されたシーンを終了する。

成功すればD3D_OKが返る。

参照　IDirect3DDevice::BeginScene


IDirect3DDevice::EnumTextureFormats

HRESULT EnumTextureFormats(

    LPD3DENUMTEXTUREFORMATSCALLBACK lpd3dEnumTextureProc,

    LPVOID lpArg);

現在のドライバでサポートされているテクスチャ型のリストを列挙する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpd3dEnumTextureProc

列挙処理として各テクスチャ型で呼び出されるD3DENUMTEXTUREFORMATSCALLBACKコールバック関数へのポインタ。

lpArg

コールバック関数に渡されるアプリケーション定義データへのポインタ。


IDirect3DDevice::Execute

HRESULT Execute(LPDIRECT3DEXECUTEBUFFER lpDirect3DExecuteBuffer,

    LPDIRECT3DVIEWPORT lpDirect3DViewport, DWORD dwFlags);

バッファを実行する。

成功すればD3D_OK、失敗すれば、次の値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDirect3DExecuteBuffer

実行される実行バッファへのポインタ。

lpDirect3DViewport

表示される実行バッファの変換コンテキストを記述するDirect3DViewportオブジェクトへのポインタ。

dwFlags

バッファのオブジェクトをクリッピングするかを指定するフラグ。このパラメータは、次の値のいずれかである。

D3DEXECUTE_CLIPPED

	ビューポートの外にあるプリミティブをクリッピングする。

D3DEXECUTE_UNCLIPPED

	ビューポートの中にすべてのプリミティブを含む(クリッピングしない)。
参照　D3DEXECUTEDATA、D3DINSTRUCTION、IDirect3DExecuteBuffer::Validate


IDirect3DDevice::GetCaps

HRESULT GetCaps(LPD3DDEVICEDESC lpD3DHWDevDesc,

    LPD3DDEVICEDESC lpD3DHELDevDesc);

Direct3DDeviceオブジェクトの情報を取得する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpD3DHWDevDesc

デバイスのハードウェア情報を含むD3DDEVICEDESC構造体へのポインタ。

lpD3DHELDevDesc

与えられているソフトウェアのエミュレーション情報を含むD3DDEVICEDESC構造体へのポインタ。

このメソッドは、ディスプレイのデバイス情報は取得しない。この情報を取得するには、IDirectDraw2::GetCapsメソッドを使用する。


IDirect3DDevice::GetDirect3D
Direct3DDevice::GetDirect3D

HRESULT GetDirect3D(LPDIRECT3D* lpD3D);

現在のIDirect3D インターフェイスを取得する。

成功すればD3D_OKを返し、その他のときはエラーである。返値については、「Direct3D 直接モードの返値」を参照すること。

lpD3D

メソッドが返すインターフェイスへのポインタ。


IDirect3DDevice::GetMatrix

HRESULT GetMatrix(D3DMATRIXHANDLE lpD3DMatHandle,

    LPD3DMATRIX lpD3DMatrix);

行列ハンドルから行列を取得する。この行列ハンドルは、IDirect3DDevice::CreateMatrix メソッドにより作成されたものでなければならない。

成功すればD3D_OK、失敗すれば、次の値を返す。

DDERR_INVALIDPARAMS
lpD3DMatHandle

取得する行列変数へのポインタ。

lpD3DMatrix

メソッドが返す行列を含むD3DMATRIX構造体へのポインタ。

参照　IDirect3DDevice::CreateMatrix、IDirect3DDevice::DeleteMatrix、IDirect3DDevice::SetMatrix


IDirect3DDevice::GetPickRecords

HRESULT GetPickRecords(LPDWORD lpCount,

    LPD3DPICKRECORD lpD3DPickRec);

デバイスレコードを取得する。

成功すればD3D_OKを返す。

lpCount

取得するD3DPICKRECORD構造体の数が入る変数へのポインタ。

lpD3DPickRec

メソッドが返すD3DPICKRECORD構造体の配列へのポインタ。

一般的なアプリケーションは、このメソッドを２回呼び出す。最初の呼び出しでは、２番目のパラメータにはNULLを設定し１番目のパラメータにD3DPICKRECORD構造体の件数を取得する。アプリケーションは、この構造体用に必要なメモリを確保し、２番目のパラメータ用に新たにメモリを確保して、再度このメソッドを呼び出す。


IDirect3DDevice::GetStats

HRESULT GetStats(LPD3DSTATS lpD3DStats);

デバイスの情報を取得する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpD3DStats

情報を示すD3DSTATS構造体へのポインタ。


IDirect3DDevice::Initialize

HRESULT Initialize(LPDIRECT3D lpd3d, LPGUID lpGUID,

    LPD3DDEVICEDESC lpd3ddvdesc);

デバイスを初期化する。

成功すればD3D_OKを返し、その他のときはエラーである。返値については、「Direct3D 直接モードの返値」を参照すること。

lpd3d

初期化するDirect3D デバイスへのポインタ。

lpGUID

インターフェイス識別子であるグローバル・ユニーク識別子(GUID)へのポインタ。

lpd3ddvdesc

初期化するDirect3DDeviceオブジェクトを示すD3DDEVICEDESC構造体へのポインタ。


IDirect3DDevice::NextViewport

HRESULT NextViewport(LPDIRECT3DVIEWPORT lpDirect3DViewport,

    LPDIRECT3DVIEWPORT* lplpDirect3DViewport, DWORD dwFlags);

デバイスに関連したビューポートを列挙する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDirect3DViewport

Direct3DDeviceオブジェクトに関連したビューポートのリストの中のビューポートへのポインタ。

lplpDirect3DViewport

Direct3DDeviceオブジェクトに関連したビューポートのリストの中の次のビューポートへのポインタ。

dwFlags

ビューポートのリストより取得するビューポートを指定するフラグ。デフォルトはD3DNEXT_NEXT。

D3DNEXT_HEAD	リストの最初の項目を取得。
D3DNEXT_NEXT	リストの次の項目を取得。
D3DNEXT_TAIL	リストの最後の項目を取得。


IDirect3DDevice::Pick

HRESULT Pick(LPDIRECT3DEXECUTEBUFFER lpDirect3DExecuteBuffer,

    LPDIRECT3DVIEWPORT lpDirect3DViewport, DWORD dwFlags,

    LPD3DRECT lpRect);

レンダリングを行わず実行バッファを実行し、lpRectパラメータで指定された矩形内にあるプリミティブへのオフセットのzオーダー・リストを返す。

Direct3DExecuteBuffer オブジェクトがロックされているときは、この呼び出しは失敗する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

D3DERR_EXECUTE_LOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDirect3DExecuteBuffer

取得されたｚオーダーリストからの実行バッファへのポインタ。

lpDirect3DViewport

Direct3DDeviceオブジェクトに配置されたビューポートリストの中のビューポートへのポインタ。

dwFlags

このメソッドのために現在定義されているフラグはない。

lpRect

取り出されるデバイス座標領域を示すD3DRECT構造体へのポインタ。

lpRectパラメータで指定された構造体のx1とx2メンバが等しく、y1とy2メンバが等しいとき、ピクセルだけ取り出される。座標はデバイス・ピクセルで指定される。

すべてのDirect3DExecuteBufferオブジェクトは、このメソッドを成功させるためDirect3DDeviceオブジェクトに関連付けなければならない。

参照　IDirect3DDevice::GetPickRecords


IDirect3DDevice::SetMatrix

HRESULT SetMatrix(D3DMATRIXHANDLE d3dMatHandle,

    LPD3DMATRIX lpD3DMatrix);

行列ハンドルへ行列を加える。この行列ハンドルは、IDirect3DDevice::CreateMatrix メソッドで作成したものでなければならない。

成功すればD3D_OK、失敗すれば、次の値を返す。

DDERR_INVALIDPARAMS
d3dMatHandle

設定される行列ハンドル。

lpD3DMatrix

設定される行列を示すD3DMATRIX構造体へのポインタ。

行列のハンドルを含む実行バッファ内を変換する。IDirect3DDevice::SetMatrixメソッドは実行バッファをロック、ロック解除せずにこの配列を変更できる。

参照　IDirect3DDevice::CreateMatrix、 IDirect3DDevice::GetMatrix、 IDirect3DDevice::DeleteMatrix


IDirect3DDevice::SwapTextureHandles

HRESULT SwapTextureHandles(LPDIRECT3DTEXTURE lpD3DTex1,

    LPDIRECT3DTEXTURE lpD3DTex2);

ふたつのテクスチャハンドルを交換する。

成功すればD3D_OKを返す。

lpD3DTex1および lpD3DTex2

メソッドが戻ったとき、交換されるテクスチャのハンドルへのポインタ。

このメソッドは、通常アプリケーションがオブジェクトの集合体の中ですべてのテクスチャを変更するとき使われる。


IDirect3DExecuteBuffer

IDirect3DExecuteBufferインターフェイスのメソッドを使うと、Direct3D実行バッファのセットアップや制御を行うことができる。この節は、このインターフェイスのメソッドについて説明する。概略については、「IDirect3DExecuteBufferインターフェイス」を参照すること。

IDirect3DExecuteBufferインターフェイスのメソッドは、次のグループからなる。

データの実行	GetExecuteData
	SetExecuteData
ロックと解除	Lock
	Unlock
その他	Initialize
	Optimize
	Validate
IDirect3DExecuteBufferインターフェイスは、すべての COM インターフェイスと同じく、 IUnknown インターフェイス・メソッドを継承する。 IUnknown インターフェイスがサポートするメソッドは、次の通り。

AddRef
QueryInterface
Release


IDirect3DExecuteBuffer::GetExecuteData

HRESULT GetExecuteData(LPD3DEXECUTEDATA lpData);

Direct3DExecuteBufferオブジェクトの実行データの状態を取得する。実行データは、Direct3DExecuteBufferオブジェクトの記述に使用される。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

D3DERR_EXECUTE_LOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpData

Direct3DExecuteBufferオブジェクトの現在の実行データの状態が設定されたD3DEXECUTEDATA 構造体へのポインタ。

Direct3DExecuteBufferオブジェクトがロックされているときは、この呼び出しは失敗する。

参照　IDirect3DExecuteBuffer::SetExecuteData


IDirect3DExecuteBuffer::Initialize

HRESULT Initialize(LPDIRECT3DDEVICE lpDirect3DDevice,

    LPD3DEXECUTEBUFFERDESC lpDesc);

このメソッドは、COMプロトコルへの準拠用に提供される。

Direct3DExecuteBufferバッファが生成時に初期化されるためDDERR_ALREADYINITIALIZEDを返す。

lpDirect3DDevice

Direct3D オブジェクトを示すデバイスへのポインタ。

lpDesc

生成されたDirect3DExecuteBufferオブジェクトを記述するD3DEXECUTEBUFFERDESC構造体へのポインタ。バッファのサイズが足りないときは、呼び出しは失敗する。


IDirect3DExecuteBuffer::Lock

HRESULT Lock(LPD3DEXECUTEBUFFERDESC lpDesc);

実行バッファのコマンドへのポインタを取得する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

D3DERR_EXECUTE_LOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING
lpDesc

D3DEXECUTEBUFFERDESC構造体へのポインタ。メソッドが返ったとき､lpDataメンバには、アプリケーションがアクセスする時点のデータへのポインタが設定される。このデータは、システムやビデオ・メモリに存在し、dwCapsメンバにより示される。アプリケーションは、IDirect3DExecuteBuffer::Lockメソッドを使うとDirect3Dがシステムやビデオ・メモリ間でのデータ転送を要求できる。

Direct3DExecuteBufferオブジェクトがロックされていると、この呼び出しは失敗する。たとえば、他のスレッドがバッファをアクセス中だったり、このバッファに発生したIDirect3DDevice::Executeメソッドがまだ完了していないときに起こる。

参照　IDirect3DExecuteBuffer::Unlock


IDirect3DExecuteBuffer::Optimize

HRESULT Optimize();

現在サポートしていない。


IDirect3DExecuteBuffer::SetExecuteData

HRESULT SetExecuteData(LPD3DEXECUTEDATA lpData);

Direct3DExecuteBufferオブジェクトの実行データの状態を設定する。実行データは、Direct3DExecuteBufferオブジェクトの内容を示すために使用される。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

D3DERR_EXECUTE_LOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpData

実行バッファのレイアウトを示すD3DEXECUTEDATA構造体へのポインタ。

Direct3DExecuteBufferオブジェクトがロックされているときは、この呼び出しは失敗する。

参照　IDirect3DExecuteBuffer::GetExecuteData


IDirect3DExecuteBuffer::Unlock

HRESULT Unlock();

実行バッファのコマンドへのポインタを解放する。ただしこのポインタは、バッファをIDirect3DDevice::Executeメソッドでロックしたものでなければならない。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

D3DERR_EXECUTE_NOT_LOCKED
DDERR_INVALIDOBJECT
参照　IDirect3DExecuteBuffer::Lock


IDirect3DExecuteBuffer::Validate

HRESULT Validate(LPDWORD lpdwOffset, LPD3DVALIDATECALLBACK lpFunc,

    LPVOID lpUserArg, DWORD dwReserved);

現在、実装されていない。


IDirect3DLight

IDirect3DLightインターフェイスのメソッドを使うと、光源情報の取得や設定を行うことができる。この節では、IDirect3Dlightインターフェイスのメソッドについて説明する。概略については、「IDirect3DLightインターフェイス」を参照すること。

IDirect3DLightインターフェイスのメソッドは、次のグループからなる。

取得と設定	GetLight
	SetLight
初期化	Initialize
IDirect3DLightインターフェイスは、すべての COM インターフェイスのように、 IUnknown インターフェイス・メソッドを継承する。 IUnknown インターフェイスがサポートするメソッドは、次の通り。

AddRef
QueryInterface
Release


IDirect3DLight::GetLight

HRESULT GetLight(LPD3DLIGHT lpLight);

Direct3DLightオブジェクトの光源情報を取得する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpLight

現在の光源データが設定されたD3DLIGHT構造体へのポインタ。

参照　IDirect3DLight::SetLight


IDirect3DLight::Initialize

HRESULT Initialize(LPDIRECT3D lpDirect3D);

このメソッドは、COMプロトコルの一貫性を保つためのものである。

Direct3DLightオブジェクトを生成時に初期化するため、DDERR_ALREADYINITIALIZEDが返る。

lpDirect3D

Direct3Dオブジェクトを示すDirect3D構造体へのポインタ。


IDirect3DLight::SetLight

HRESULT SetLight(LPD3DLIGHT lpLight);

Direct3DLightオブジェクトの光源情報を設定する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpLight

現在の光源データを設定するために使用されるD3DLIGHT構造体へのポインタ。

参照　IDirect3DLight::GetLight


IDirect3DMaterial

IDirect3DMaterialインターフェイス・メソッドを使うと、マテリアルを取得したり特性を設定したりすることができる。この節では、IDirect3Dmaterialインターフェイスについて説明する。概略については、「IDirect3DMaterialインターフェイス」を参照すること。

IDirect3DMaterialインターフェイスのメソッドは、次のグループからなる。

色の予約	Reserve
	Unreserve
マテリアル	GetMaterial
	SetMaterial
その他	GetHandle
	Initialize
IDirect3DMaterialインターフェイスは、すべての COM インターフェイスのように、 IUnknown インターフェイス・メソッドを継承する。 IUnknown インターフェイスがサポートするメソッドは、次の通り。

AddRef
QueryInterface
Release


IDirect3DMaterial::GetHandle

HRESULT GetHandle(LPDIRECT3DDEVICE lpDirect3DDevice,

    LPD3DMATERIALHANDLE lpHandle);

Direct3DMaterialオブジェクトのマテリアルのハンドルを取得する。このハンドルは、すべてのDirect3D API呼び出しで、マテリアルの参照のために使用される。マテリアルは、1度にひとつのデバイスで使用できる。

デバイスが破棄されたとき、マテリアルはデバイスから切り離される。

成功すればD3D_OKを返し、その他のときは、DDERR_INVALIDOBJECT返す。

lpDirect3DDevice

使用されているマテリアルのDirect3DDeviceオブジェクトへのポインタ。

lpHandle

Direct3DMaterialオブジェクトに対応するマテリアルのハンドルが設定される変数へのポインタ。


IDirect3DMaterial::GetMaterial

HRESULT GetMaterial(LPD3DMATERIAL lpMat);

Direct3DMaterialオブジェクトのマテリアル・データを取得する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpMat

現在のマテリアルの特性が設定されるD3DMATERIAL構造体へのポインタ。

参照　IDirect3DMaterial::SetMaterial


IDirect3DMaterial::Initialize

HRESULT Initialize(LPDIRECT3D lpDirect3D);

このメソッドは、COMプロトコルの一貫性を保つためのものである。

Direct3DMaterialオブジェクトを生成時に初期化するため、DDERR_ALREADYINITIALIZEDが返る。

lpDirect3D

Direct3Dオブジェクトを示すDirect3D構造体へのポインタ。


IDirect3DMaterial::Reserve

HRESULT Reserve();

現在、実装されていない。


IDirect3DMaterial::SetMaterial

HRESULT SetMaterial(LPD3DMATERIAL lpMat);

Direct3DMaterialオブジェクトのマテリアル・データを設定する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpMat

マテリアル特性が設定されるD3DMATERIAL構造体へのポインタ。

参照　IDirect3DMaterial::GetMaterial


IDirect3DMaterial::Unreserve

HRESULT Unreserve();

現在、実装されていない。


IDirect3DTexture

IDirect3DTextureインターフェイスのメソッドを使うと、テクスチャの取得や特性の設定を行うことができる。この節では、IDirect3Dtextureインターフェイスのメソッドについて説明する。概略については、「IDirect3DTextureインターフェイス」を参照すること。

IDirect3DTextureインターフェイスのメソッドは、次のグループからなる。

ハンドル	GetHandle
初期化	Initialize
ロード	Load
	Unload
パレット情報	PaletteChanged
IDirect3DTextureインターフェイスは、すべての COM インターフェイスのように、 IUnknown インターフェイス・メソッドを継承する。 IUnknown インターフェイスがサポートするメソッドは、次の通り。

AddRef
QueryInterface
Release
Direct3DTextureオブジェクトを取得するには、テクスチャマップとして生成されたDirectDrawSurfaceオブジェクトからIDirect3D::QueryInterfaceメソッドを呼び出す。


IDirect3DTexture::GetHandle

HRESULT GetHandle(LPDIRECT3DDEVICE lpDirect3DDevice,

    LPD3DTEXTUREHANDLE lpHandle);

Direct3DTextureオブジェクトのテクスチャのハンドルを取得する。このハンドルは、すべてのDirect3D API呼び出しで、テクスチャの参照に使用される。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

D3DERR_BADOBJECT
DDERR_INVALIDPARAMS
lpDirect3DDevice

ロードされているテクスチャのDirect3DDeviceオブジェクトへのポインタ。

lpHandle

Direct3DTextureオブジェクトに対応するテクスチャのハンドルが設定される変数へのポインタ。


IDirect3DTexture::Initialize

HRESULT Initialize(LPDIRECT3DDEVICE lpD3DDevice,

    LPDIRECTDRAWSURFACE lpDDSurface);

このメソッドは、COMプロトコルの一貫性を保つためのものである。

Direct3DTextureオブジェクトを生成時に初期化するため、DDERR_ALREADYINITIALIZEDが返る。

lpDirect3D

Direct3Dオブジェクトを示すDirect3D構造体へのポインタ。

lpDDSurface

このオブジェクト上のDirectDrawへのポインタ。


IDirect3DTexture::Load

HRESULT Load(LPDIRECT3DTEXTURE lpD3DTexture);

DDSCAPS_ALLOCONLOADフラグにより生成されたテクスチャをロードする。サーフェスがこのメソッドを使ってロードされるまで、メモリは割り当てられない。

成功すれば、D3D_OKを返し、その他のときはエラーである。返値については、「Direct3D 直接モードの返値」を参照すること。

lpD3DTexture

ロードされるテクスチャへのポインタ。

参照　IDirect3DTexture::Unload


IDirect3DTexture::PaletteChanged

HRESULT PaletteChanged(DWORD dwStart, DWORD dwCount);

サーフェス上のパレットが変更されたことをドライバに通知する。

成功すれば、D3D_OKを返し、その他のときはエラーである。返値については、「Direct3D 直接モードの返値」を参照すること。

dwStart

変更された先頭のパレットのインデックス。

dwCount

変更されたパレットの個数。

このメソッドは、アプリケーションがビデオクリップの再生やパレットの変更を要求するのに特に便利である。


IDirect3DTexture::Unload

HRESULT Unload();

現在のテクスチャをアンロードする。

成功すればD3D_OKを返し、その他のときはエラーである。返値については、「Direct3D 直接モードの返値」を参照すること。

参照　IDirect3DTexture::Load


IDirect3DViewport

IDirect3DViewportインターフェイスのメソッドを使うと、ビューポートの取得やプロパティの設定を行うことができる。この節では、IDirect3DViewportインターフェイスのメソッドについて説明する。概略については、「IDirect3DViewportインターフェイス」を参照すること。

IDirect3DViewportインターフェイスのメソッドは、次のグループからなる。

背景	GetBackground
	GetBackgroundDepth
	SetBackground
	SetBackgroundDepth
初期化	Initialize
光源	AddLight
	DeleteLight
	LightElements
	NextLight
マテリアルとビューポート	Clear
	GetViewport
	SetViewport
変換	TransformVertices
IDirect3DViewportインターフェイスは、すべての COM インターフェイスのように、 IUnknown インターフェイス・メソッドを継承する。 IUnknown インターフェイスがサポートするメソッドは、次の通り。

AddRef
QueryInterface
Release


IDirect3DViewport::AddLight

HRESULT AddLight(LPDIRECT3DLIGHT lpDirect3DLight);

ビューポートに関連したDirect3DLightオブジェクトのリストに、指定された光源を追加する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDirect3DLight

Direct3DDeviceオブジェクトに関連したDirect3DLightオブジェクトへのポインタ。


IDirect3DViewport::Clear

HRESULT Clear(DWORD dwCount, LPD3DRECT lpRects, DWORD dwFlags);

現在の背景マテリアルのビューポートやビューポート上の矩形範囲を消去する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
dwCount

lpRectsパラメータに指定される矩形の数。

lpRects

D3DRECT構造体の配列へのポインタ。

dwFlags

消去の対象を示すフラグ。レンダリング対象、Zバッファまたはその両方。

D3DCLEAR_TARGET	背景マテリアル(設定されているとき)のレンダリング対象。
D3DCLEAR_ZBUFFER	Zバッファか、そこに設定されている現在の背景深度(設定されているとき)。


IDirect3DViewport::DeleteLight

HRESULT DeleteLight(LPDIRECT3DLIGHT lpDirect3DLight);

ビューポートに関連したDirect3DLightオブジェクトのリストから、指定された光源を削除する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDirect3DLight

Direct3DDeviceオブジェクトから切り離す、Direct3DLightオブジェクトへのポインタ。


IDirect3DViewport::GetBackground

HRESULT GetBackground(LPD3DMATERIALHANDLE lphMat, LPBOOL lpValid);

ビューポートに関連した現在の背景からマテリアルのハンドルを取得する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lphMat

背景として使用されているマテリアルのハンドルへのポインタ。

lpValid

背景がビューポートに関連していることを示すために設定される変数へのポインタ。このパラメータがFALSEのとき、ビューポートに関連する背景はない。

参照　IDirect3DViewport::SetBackground


IDirect3DViewport::GetBackgroundDepth

HRESULT GetBackgroundDepth(LPDIRECTDRAWSURFACE* lplpDDSurface,

    LPBOOL lpValid);

ビューポートに関連した現在の背景深度を表すDirectDrawサーフェス・オブジェクトを取得する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lplpDDSurface

背景深度を表すDirectDrawSurfaceオブジェクトへのポインタへのポインタ。

lpValid

ビューポートに関連付けられた背景深度がないときFALSEが設定される変数へのポインタ。

参照　IDirect3DViewport::SetBackgroundDepth


IDirect3DViewport::GetViewport

HRESULT GetViewport(LPD3DVIEWPORT lpData);

ビューポートのビューポート・レジスタを取得する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpData

ビューポートを取得するD3DVIEWPORT構造体へのポインタ。

参照　IDirect3DViewport::SetViewport


IDirect3DViewport::Initialize

HRESULT Initialize(LPDIRECT3D lpDirect3D);

このメソッドは、COMプロトコルの一貫性を保つためのものである。

Direct3DViewportオブジェクトを生成時に初期化するため、DDERR_ALREADYINITIALIZEDが返る。

lpDirect3D

Direct3Dオブジェクトを示すDirect3D構造体へのポインタ。


IDirect3DViewport::LightElements

HRESULT LightElements(DWORD dwElementCount, LPD3DLIGHTDATA lpData);

現在、実装されていない。


IDirect3DViewport::NextLight

HRESULT NextLight(LPDIRECT3DLIGHT lpDirect3DLight,

    LPDIRECT3DLIGHT* lplpDirect3DLight, DWORD dwFlags);

ビューポートに関連したDirect3DLightオブジェクトを列挙する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDirect3DLight

Direct3DDeviceオブジェクトに関連した光源リストの中の光源へのポインタ。

lplpDirect3DLight

Direct3DDeviceオブジェクトに関連した光源リストの中から要求された光源を含むポインタへのポインタ。要求される光源は、dwFlagsパラメータで指定される。

dwFlags

光源リストから取得する光源を指定するフラグ。デフォルトとして、D3DNEXT_NEXTが設定される。

D3DNEXT_HEAD	リストの最初の項目。
D3DNEXT_NEXT	リストの次の項目。
D3DNEXT_TAIL	リストの最後の項目。


IDirect3DViewport::SetBackground

HRESULT SetBackground(D3DMATERIALHANDLE hMat);

ビューポートに関連した背景を設定する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
hMat

背景として使用されるマテリアルのハンドル。

参照　IDirect3DViewport::GetBackground


IDirect3DViewport::SetBackgroundDepth

HRESULT SetBackgroundDepth(LPDIRECTDRAWSURFACE lpDDSurface);

ビューポートの背景深度を設定する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpDDSurface

背景深度を表すDirectDrawSurfaceオブジェクトへのポインタ。

IDirect3DViewport::Clearメソッドが呼ばれ、D3DCLEAR_ZBUFFERフラグが指定されているとき、指定された深度がZバッファに設定される。深度は16ビットでなければならない。

参照　IDirect3DViewport::GetBackgroundDepth


IDirect3DViewport::SetViewport

HRESULT SetViewport(LPD3DVIEWPORT lpData);

ビューポートのビューポート・レジスタを設定する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
lpData

新規ビューポートを示すD3DVIEWPORT構造体へのポインタ。

参照　IDirect3DViewport::GetViewport


IDirect3DViewport::TransformVertices

HRESULT TransformVertices(DWORD dwVertexCount,

    LPD3DTRANSFORMDATA lpData, DWORD dwFlags, LPDWORD lpOffscreen);

変換行列により頂点セットを変換する。

成功すればD3D_OK、失敗すれば、次の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
dwVertexCount

itパラメータの中の変換される頂点数。

lpData

変換される頂点を含むD3DTRANSFORMDATA構造体へのポインタ。

dwFlags

以下のフラグの内ひとつ。これらのフラグの使い方については、後述の説明を参照すること。

D3DTRANSFORM_CLIPPED
D3DTRANSFORM_UNCLIPPED
lpOffscreen

変換後、頂点がスクリーン外のとき、0以外の値が設定される変数へのポインタ。

itパラメータがD3DTRANSFORM_CLIPPEDのとき、このメソッドは、変換された頂点が視錐台の中にあれば、頂点の変換に現在の変換行列を使う。頂点がクリッピングされるときは、itの中のD3DLVERTEX構造体に対応する部分が入る。その他のときは、スクリーン座標が設定される。変換された座標のクリッピング交点は、itに返る。もしitが0以外のときは、頂点がスクリーン外でビューポートにかからない。D3DTRANSFORMDATA構造体のdrExtentメンバも、変換後の頂点の2D矩形範囲に設定される。

itパラメータがD3DTRANSFORM_UNCLIPPEDのとき、このメソッドは頂点の変換に現在の変換行列を使う。この場合、システムは視錐台の中に変換後の座標があると仮定する。D3DTRANSFORMDATA構造体のdrExtentメンバ変換後の座標の矩形範囲に設定される。

D3DTRANSFORMDATA構造体のdwClipメンバは、変換モジュールがビューの大きさを考慮しクリッピングが必要かどうか決定することを助ける。変換前に高度なソフトウェアで、矩形や球の範囲がビューの大きさで十分であるか何度もテストすることができる。クリッピングのテストでは、スキップされたり、ビューの大きさの外側が十分であるか、全体をスキップさせたりする。


構造体


D3DBRANCH

typedef struct _D3DBRANCH {

    DWORD dwMask;

    DWORD dwValue;

    BOOL  bNegate;

    DWORD dwOffset;

} D3DBRANCH, *LPD3DBRANCH;

実行バッファの中にある条件付きの命令を実行する。この構造体は、分岐構造体である。

dwMask

分岐のためのビットマスク。このマスクは、論理積命令によりドライバ状態マスクと結合できる。結果がdwValueメンバで指定された値に等しく、bNegateメンバがFALSEの場合、分岐する。

使用可能なドライバ状態マスクのリストは、D3DSTATUS構造体のdwStatus メンバを参照すること。

dwValue

dwMaskメンバで示された命令と比較するアプリケーション定義の値。

bNegate

TRUEで、比較結果の反転。

dwOffset

分岐先へのオフセット。終了のときは、0を指定する。


D3DCOLORVALUE

typedef struct _D3DCOLORVALUE {

    union {

        D3DVALUE r;

        D3DVALUE dvR;

    };

    union {

        D3DVALUE g;

        D3DVALUE dvG;

    };

    union {

        D3DVALUE b;

        D3DVALUE dvB;

    };

    union {

        D3DVALUE a;

        D3DVALUE dvA;

    };

} D3DCOLORVALUE;

D3DLIGHTとD3DMATERIAL構造体で使うカラー値を定義する。

dvR, dvG, dvB, dvA

色の要素である赤、緑、青、アルファを指定するD3DVALUE型の値。


D3DDEVICEDESC

typedef struct _D3DDeviceDesc {

    DWORD	dwSize;

    DWORD	dwFlags;

    D3DCOLORMODEL	dcmColorModel;

    DWORD	dwDevCaps;

    D3DTRANSFORMCAPS	dtcTransformCaps;

    BOOL	bClipping;

    D3DLIGHTINGCAPS	dlcLightingCaps;

    D3DPRIMCAPS	dpcLineCaps;

    D3DPRIMCAPS	dpcTriCaps;

    DWORD	dwDeviceRenderBitDepth;

    DWORD	dwDeviceZBufferBitDepth;

    DWORD	dwMaxBufferSize;

    DWORD	dwMaxVertexCount;

} D3DDEVICEDESC,	*LPD3DDEVICEDESC;

現在のデバイスについての情報が設定される。この構造体は、IDirect3DDevice::GetCaps等のメソッドで現在のデバイスを問い合わせるために使われる。

dwSize

この構造体のバイト単位のサイズ。

dwFlags

この構造体の有効なデータが設定されているメンバを識別するフラグ。

D3DDD_BCLIPPING

	bClippingメンバが有効。

D3DDD_COLORMODEL

	dcmColorModelメンバが有効。

D3DDD_DEVCAPS

	dwDevCapsメンバが有効。

D3DDD_LIGHTINGCAPS

	dlcLightingCapsメンバが有効。

D3DDD_LINECAPS

	dpcLineCapsメンバが有効。

D3DDD_MAXBUFFERSIZE

	dwMaxBufferSizeメンバが有効。

D3DDD_MAXVERTEXCOUNT

	dwMaxVertexCountメンバが有効。

D3DDD_TRANSFORMCAPS

	dtcTransformCapsメンバが有効。

D3DDD_TRICAPS

	dpcTriCapsメンバが有効。
dcmColorModel

デバイスのカラー・モデルを指定しているD3DCOLORMODEL列挙型メンバのひとつ。

dwDevCaps

デバイスの能力を識別するフラグ。

D3DDEVCAPS_EXECUTESYSTEMMEMORY

	システム・メモリを実行バッファに使用可能。

D3DDEVCAPS_EXECUTEVIDEOMEMORY

	ビデオ・メモリを実行バッファに使用可能。

D3DDEVCAPS_FLOATTLVERTEX

	変換後の頂点データを浮動小数点で取得。

3DDEVCAPS_SORTDECREASINGZ

	深度の減少方向にソートされたデータが必要。

D3DDEVCAPS_SORTEXACT

	精密にソートされたデータが必要。

D3DDEVCAPS_SORTINCREASINGZ

	Z増加方向にソートされたデータが必要。

D3DDEVCAPS_TEXTURESYSTEMMEMORY

	システム・メモリからテクスチャを取得可能。

D3DDEVCAPS_TEXTUREVIDEOMEMORY

	デバイスメモリからテクスチャを取得可能。

D3DDEVCAPS_TLVERTEXSYSTEMMEMORY

	頂点を変換したり明るくするため、システム・メモリをバッファに使用可能。

D3DDEVCAPS_TLVERTEXVIDEOMEMORY

	頂点を変換したり明るくするため、ビデオ・メモリをバッファに使用可能。
dtcTransformCaps

デバイスの変換能力を指定するD3DTRANSFORMCAPS構造体のメンバのひとつ。

bClipping

デバイスが3Dクリッピングを実行可能であれば、TRUEとなる。

dlcLightingCaps

デバイスの光源能力を指定するD3DLIGHTINGCAPS構造体のメンバのひとつ。

dpcLineCaps､dpcTriCaps

線や三角形を描画するため、デバイスのサポート情報を定義するD3DPRIMCAPS構造体。

dwDeviceRenderBitDepth

デバイスのレンダリング・ビット深度。次のDirectDrawビット深度定数DDBD_8、DDBD_16、DBD_24、DDBD_32の内ひとつ以上を設定できる。

dwDeviceZBufferBitDepth

デバイスのZバッファのビット深度。次のDirectDrawビット深度定数DDBD_8、DDBD_16、DDBD_24、DDBD_32の内ひとつ以上を設定できる。

dwMaxBufferSize

このデバイスの実行バッファの最大サイズ。このメンバが0のときは、アプリケーションはどのようなサイズでも使用可能である。

dwMaxVertexCount

このデバイスの最大頂点数。

参照　D3DCOLORMODEL、D3DFINDDEVICERESULT、D3DLIGHTINGCAPS、D3DPRIMCAPS、D3DTRANSFORMCAPS


D3DEXECUTEBUFFERDESC

typedef struct _D3DExecuteBufferDesc {

    DWORD  dwSize;

    DWORD  dwFlags;

    DWORD  dwCaps;

    DWORD  dwBufferSize;

    LPVOID lpData;

} D3DEXECUTEBUFFERDESC;

typedef D3DEXECUTEBUFFERDESC *LPD3DEXECUTEBUFFERDESC;

IDirect3DDevice::CreateExecuteBufferやIDirect3DExecuteBuffer::Lockのようなメソッドのため実行バッファ情報を示す。

dwSize

この構造体のバイト単位のサイズ。

dwFlags

この構造体の有効なデータが設定されているメンバを識別するフラグ。

D3DDEB_BUFSIZE	dwBufferSizeメンバが有効。
D3DDEB_CAPS	dwCapsメンバが有効。
D3DDEB_LPDATA	lpDataメンバが有効。
dwCaps

実行バッファのメモリ中の位置。

3DDEBCAPS_MEM

	D3DDEBCAPS_SYSTEMMEMORYと D3DDEBCAPS_VIDEOMEMORYの論理和(OR)。

D3DDEBCAPS_SYSTEMMEMORY

	実行バッファのデータはシステム・メモリに存在する。

D3DDEBCAPS_VIDEOMEMORY

	実行バッファのデータはデバイスメモリに存在する。
dwBufferSize

実行バッファのバイト単位のサイズ。

lpData

バッファ・データへのポインタ。


D3DEXECUTEDATA

typedef struct _D3DEXECUTEDATA {

    DWORD     dwSize;

    DWORD     dwVertexOffset;

    DWORD     dwVertexCount;

    DWORD     dwInstructionOffset;

    DWORD     dwInstructionLength;

    DWORD     dwHVertexOffset;

    D3DSTATUS dsStatus;

} D3DEXECUTEDATA, *LPD3DEXECUTEDATA;

IDirect3DDevice::Executeメソッドのため、データを指定する。このメソッドが呼ばれ変換が終了するとき、dwInstructionOffsetメンバで指定された値で始まる命令リストが解析されて表示される。

dwSize

この構造体のバイト単位のサイズ。

dwVertexOffset

頂点リストのオフセット。

dwVertexCount

実行する頂点数。

dwInstructionOffset

実行命令リストのオフセット。

dwInstructionLength

実行命令の長さ。

dwHVertexOffset

アプリケーションがクリッピングを必要とするスクリーン座標データで与えられるときに使用される同質の頂点のオフセット。

dsStatus

変換終了後使用されるスクリーン範囲を格納する値。この値は、D3DSTATUS構造体である。

参照　D3DSTATUS


D3DFINDDEVICERESULT

typedef struct _D3DFINDDEVICERESULT {

    DWORD         dwSize;

    GUID          guid;

    D3DDEVICEDESC ddHwDesc;

    D3DDEVICEDESC ddSwDesc;

} D3DFINDDEVICERESULT, *LPD3DFINDDEVICERESULT;

アプリケーションがIDirect3D::FindDeviceメソッドを呼び出し、取得するデバイスを識別する。

dwSize

この構造体のバイト単位のサイズ。

guid

検出されたデバイスのグローバル・ユニーク識別子(GUID)。

ddHwDesc､ddSwDesc

検出されたハードウェアとソフトウェアのデバイスを示すD3DDEVICEDESC構造体。

参照　D3DFINDDEVICESEARCH


D3DFINDDEVICESEARCH

typedef struct _D3DFINDDEVICESEARCH {

    DWORD         dwSize;

    DWORD         dwFlags;

    BOOL          bHardware;

    D3DCOLORMODEL dcmColorModel;

    GUID          guid;

    DWORD         dwCaps;

    D3DPRIMCAPS   dpcPrimCaps;

} D3DFINDDEVICESEARCH, *LPD3DFINDDEVICESEARCH;

アプリケーションが検出したいデバイスの特性を示す。この構造体は、IDirect3D::FindDeviceメソッドを呼び出すために使われる。

dwSize

この構造体のバイト単位のサイズ。

dwFlags

アプリケーションが検出したいデバイス型を定義するフラグ。このメンバには、次の値の内ひとつ以上が設定できる。

D3DFDS_ALPHACMPCAPS

	この構造体のdpcPrimCapsメンバとして指定されたD3DPRIMCAPS構造体のdwAlphaCmpCapsメンバと一致する。

D3DFDS_COLORMODEL

	この構造体のdcmColorModelメンバで指定されたカラー・モデルと一致する。

D3DFDS_DSTBLENDCAPS

	この構造体のdpcPrimCapsメンバとして指定されたD3DPRIMCAPS構造体のdwDestBlendCapsメンバと一致する。

D3DFDS_GUID

	この構造体のguidメンバで指定されたグローバル・ユニーク識別子(GUID)と一致する。

D3DFDS_HARDWARE

	この構造体のbHardwareメンバに与えられているハードウェアかソフトウェアの取得内容と一致する。

D3DFDS_LINES

	D3DDEVICEDESC構造体のdpcLineCapsメンバで指定された D3DPRIMCAPS構造体と一致する。

D3DFDS_MISCCAPS

	この構造体のdpcPrimCapsメンバとして指定されたD3DPRIMCAPS構造体のdwMiscCapsメンバと一致する。

D3DFDS_RASTERCAPS

	この構造体のdpcPrimCapsメンバとして指定されたD3DPRIMCAPS構造体のdwRasterCapsメンバと一致する。

D3DFDS_SHADECAPS

	この構造体のdpcPrimCaps メンバとして指定されたD3DPRIMCAPS構造体のdwShadeCapsメンバと一致する。

D3DFDS_SRCBLENDCAPS

	この構造体のdpcPrimCapsメンバとして指定されたD3DPRIMCAPS構造体のdwSrcBlendCapsメンバと一致する。

D3DFDS_TEXTUREBLENDCAPS

	この構造体のdpcPrimCapsメンバとして指定されたD3DPRIMCAPS構造体の dwTextureBlendCapsメンバと一致する。

D3DFDS_TEXTURECAPS

	この構造体のdpcPrimCaps メンバとして指定された D3DPRIMCAPS構造体のdwTextureCapsメンバと一致する。

D3DFDS_TEXTUREFILTERCAPS

	この構造体のdpcPrimCapsメンバとして指定されたdwTextureCaps 構造体の dwTextureFilterCaps メンバと一致する。

D3DFDS_TRIANGLES

	D3DDEVICEDESC 構造体の dwTextureFilterCapsメンバで指定された D3DPRIMCAPS構造体と一致する。

D3DFDS_ZCMPCAPS

	この構造体のdpcPrimCapsメンバとして指定されたD3DPRIMCAPS構造体のdwZCmpCapsメンバと一致する。
bHardware

取得するデバイスが、ハードウェアかソフトウェアのどちらであるかを指定するフラグ。このメンバがTRUEのときは、ハードウェアのラスタを取得する。そして、ハードウェア・アクセラレーションを行う。このフラグを使用するアプリケーションは、dwFlagsメンバにD3DFDS_HARDWAREビットを設定すること。

dcmColorModel

ランプやRGBカラー・モデルで取得するデバイスを指定するD3DCOLORMODEL列挙型メンバのひとつ。

guid

検出するデバイスのグローバル・ユニーク識別子(GUID)。

dwCaps

能力のフラグ。

dpcPrimCaps

それぞれのプリミティブ型のためのデバイスの能力を示すD3DPRIMCAPS構造体を指定する。

参照　D3DFINDDEVICERESULT


D3DHVERTEX

typedef struct _D3DHVERTEX {

    DWORD        dwFlags;

    union {

        D3DVALUE hx;

        D3DVALUE dvHX;

    };

    union {

        D3DVALUE hy;

        D3DVALUE dvHY;

    };

    union {

        D3DVALUE hz;

        D3DVALUE dvHZ;

    };

} D3DHVERTEX, *LPD3DHVERTEX;

アプリケーションにクリッピングするために必要なスクリーン座標が与えられるとき、使用される同次頂点を定義する。この構造体は、D3DTRANSFORMDATA構造体の一部である。

dwFlags

同次頂点のクリッピング状態を定義するフラグ。このメンバは、D3DTRANSFORMDATA構造体のdwClipメンバのフラグをひとつ以上設定できる。

dvHX、 dvHY、 dvHZ

同次座標への変換を指定するD3DVALUE型の値。これらの座標は、頂点を示す。


D3DINSTRUCTION

typedef struct _D3DINSTRUCTION {

    BYTE bOpcode;

    BYTE bSize;

    WORD wCount;

} D3DINSTRUCTION, *LPD3DINSTRUCTION;

実行バッファ中の命令を定義する。ディスプレイ・リストは、可変長命令のリストより作成される。それぞれの命令は、共通な命令ヘッダで始まり、その命令のパラメータが続く。

bOpcode

D3DOPCODE 列挙型のメンバとして指定されるレンダリング命令。

bSize

命令データユニットのサイズ。このメンバは、順次に次の命令に飛ぶために使われる。

wCount

設定する命令データ数。このメンバは、三角形のメッシュでできている三角形のような、似た命令をまとめる時に使われる。


D3DLIGHT

typedef struct _D3DLIGHT {

    DWORD         dwSize;

    D3DLIGHTTYPE  dltType;

    D3DCOLORVALUE dcvColor;

    D3DVECTOR     dvPosition;

    D3DVECTOR     dvDirection;

    D3DVALUE      dvRange;

    D3DVALUE      dvFalloff;

    D3DVALUE      dvAttenuation0;

    D3DVALUE      dvAttenuation1;

    D3DVALUE      dvAttenuation2;

    D3DVALUE      dvTheta;

    D3DVALUE      dvPhi;

} D3DLIGHT, *LPD3DLIGHT;

IDirect3DLight::SetLightやIDirect3DLight::GetLightのようなメソッドを呼ぶための、光源型を決定する。

dwSize

この構造体のバイト単位のサイズ。

dltType

光源の型。この値は、D3DLIGHTTYPE列挙型のメンバのひとつである。

dcvColor

光源の色。このメンバは、D3DCOLORVALUE構造体である。

dvPosition､dvDirection

ワールド空間での光源の位置や範囲。

dvRange

光源の有効範囲。

dvFalloff

明部(dvThetaメンバで指定される角度)と暗影部の外枠(dvPhiメンバで指定される角度)の間で輝度が減衰する。半影内の点での輝度は、次の方程式で示される。

この方程式では、rhoは、照射軸とスポットライト地点との角度を表す。

dvAttenuation0

一定の輝度。光源とdvRangeメンバにより与えられた停止点の間で減衰しない光源レベルを指定する。

dvAttenuation1

リニアに減衰する輝度。輝度は、dvRangeメンバにより与えられた停止点の間の中間で、この値の50パーセントである。

dvAttenuation2

2次減衰率に従って減衰する輝度。

dvTheta

スポットライトの内角(ラジアン)。照らされたスポットライトは視錐台である。

dvPhi

スポットライトの外角(ラジアン)。この視錐台の外側の点は、スポットライトに照らされない。

システムは、距離による光源の減衰を計算するため減衰を3種とも使用する。次の方程式は、減衰の設定方法を示す。このとき値dは、照射されている頂点と光源の間の距離を表す。

光源についての詳細は、「照明モジュール」を参照すること。

参照　D3DLIGHTTYPE


D3DLIGHTDATA

typedef struct _D3DLIGHTDATA {

    DWORD                dwSize;

    LPD3DLIGHTINGELEMENT lpIn;

    DWORD                dwInSize;

    LPD3DTLVERTEX        lpOut;

    DWORD                dwOutSize;

} D3DLIGHTDATA, *LPD3DLIGHTDATA;

IDirect3DViewport::LightElementsメソッドへの呼び出しにおける光源地点と色を示す。

dwSize

この構造体のバイト単位のサイズ。

lpIn

入力地点と法線ベクトルを指定するD3DLIGHTINGELEMENT 構造体へのポインタ。

dwInSize

次の入力要素への移動量。これは、アプリケーションが要素をインライン処理し、例外データを格納するために提供される。

lpOut

出力色を指定するD3DTLVERTEX 構造体へのポインタ。

dwOutSize

次の出力色までの移動量。これは、アプリケーションが色をインライン処理し、例外データを格納するために提供される。


D3DLIGHTINGCAPS

typedef struct _D3DLIGHTINGCAPS {

    DWORD dwSize;

    DWORD dwCaps;

    DWORD dwLightingModel;

    DWORD dwNumLights;

} D3DLIGHTINGCAPS, *LPD3DLIGHTINGCAPS;

デバイスの光源能力を示す。この構造体は、D3DDEVICEDESC構造体のメンバである。

dwSize

この構造体のバイト単位のサイズ。

dwCaps

光源モジュールの能力を示すフラグ。次のフラグが定義されている。

D3DLIGHTCAPS_DIRECTIONAL

	有向光をサポートする。

D3DLIGHTCAPS_GLSPOT

	Open-GLスタイルのスポットライトをサポートする。

D3DLIGHTCAPS_PARALLELPOINT

	パラレル・ポイント光をサポートする。

D3DLIGHTCAPS_POINT

	ポイント光源をサポートする。

D3DLIGHTCAPS_SPOT

	スポットライトをサポートする。
dwLightingModel

光源モデルが、RGBかモノクロであるかを定義するフラグ。次のフラグが定義される。

D3DLIGHTINGMODEL_MONO	モノクロ光源モデル。
D3DLIGHTINGMODEL_RGB	RGB光源モデル。
dwNumLights

使用できる光源数。


D3DLIGHTINGELEMENT

typedef struct _D3DLIGHTINGELEMENT {

    D3DVECTOR dvPosition;

    D3DVECTOR dvNormal;

} D3DLIGHTINGELEMENT, *LPD3DLIGHTINGELEMENT;

モデル空間内の照明位置を示す。この構造体は、D3DLIGHTDATA構造体の一部である。

dvPosition

モデル空間での照明位置を指定する値。この値は、D3DVECTOR構造体である。

dvNormal

法線ベクトルを指定する値。この値は、D3DVECTOR構造体である。

参照　D3DLIGHTDATA、IDirect3DViewport::LightElements


D3DLINE

typedef struct _D3DLINE {

    union {

        WORD v1;

        WORD wV1;

    };

    union {

        WORD v2;

        WORD wV2;

    };

} D3DLINE, *LPD3DLINE;

D3DOPCODE列挙型でのD3DOP_LINEオペコードのための直線を示す。

wV1､wV2

頂点のインデックス。

描画される線数より1つ少ない、連続した頂点のリストを使って線は描画される。


D3DLINEPATTERN

typedef struct _D3DLINEPATTERN {

    WORD wRepeatFactor;

    WORD wLinePattern;

} D3DLINEPATTERN;

直線パターンを示す。これらの値は、D3DRENDERSTATETYPE列挙型でのD3DRENDERSTATE_LINEPATTERNレンダリング状態により使用される。

wRepeatFactor

パターン開始の準備として、開始前に使用されるwLinePatternメンバで指定されたパターンのビット数。

wLinePattern

ライン・パターンを指定するビット。たとえば、値1100110011001100は、ドット・ラインを生成する。


D3DLVERTEX

typedef struct _D3DLVERTEX {

    union {

        D3DVALUE x;

        D3DVALUE dvX;

    };

    union {

        D3DVALUE y;

        D3DVALUE dvY;

    };

    union {

        D3DVALUE z;

        D3DVALUE dvZ;

    };

    DWORD        dwReserved;

    union {

        D3DCOLOR color;

        D3DCOLOR dcColor;

    };

    union {

        D3DCOLOR specular;

        D3DCOLOR dcSpecular;

    };

    union {

        D3DVALUE tu;

        D3DVALUE dvTU;

    };

    union {

        D3DVALUE tv;

        D3DVALUE dvTV;

    };

} D3DLVERTEX, *LPD3DLVERTEX;

変換されていない照明された頂点を定義する(色と同等のモデル座標)。ハードウェアが変換した頂点を使用するとき、アプリケーションは、この構造体を使う。この構造体には、ソフトウェアの光源により設定されたデータと色が含まれる。

dvX, dvY, dvZ

頂点の同次座標を指定するD3DVALUE型の値。

dwReserved

予約済み。0でなければならない。

dcColor､dcSpecular

頂点の色と投影を指定するD3DCOLOR型の値。

dvTU､dvTV

頂点のテクスチャ座標を指定するD3DVALUE型の値。


D3DMATERIAL

typedef struct _D3DMATERIAL {

    DWORD             dwSize;

    union {

        D3DCOLORVALUE diffuse;

        D3DCOLORVALUE dcvDiffuse;

    };

    union {

        D3DCOLORVALUE ambient;

        D3DCOLORVALUE dcvAmbient;

    };

    union {

        D3DCOLORVALUE specular;

        D3DCOLORVALUE dcvSpecular;

    };

    union {

        D3DCOLORVALUE emissive;

        D3DCOLORVALUE dcvEmissive;

    };

    union {

        D3DVALUE      power;

        D3DVALUE      dvPower;

    };

    D3DTEXTUREHANDLE  hTexture;

    DWORD             dwRampSize;

} D3DMATERIAL, *LPD3DMATERIAL;

IDirect3DMaterial::GetMaterialやIDirect3DMaterial::SetMaterialメソッドの呼び出しのマテリアルの特性を指定する。

dwSize

この構造体のバイト単位のサイズ。

dcvDiffuse、 dcvAmbient、 dcvSpecular、 dcvEmissive

それぞれ、マテリアルの拡散色、包囲色、投影色、放射色を指定する値。これらの値は、D3DCOLORVALUE構造体である。

dvPower

投影のハイライトの強さを指定するD3DVALUE型の値。

hTexture

テクスチャ・マップのハンドル。

dwRampSize

色の傾斜の大きさ。単色の(傾斜)ドライバでは、背景に指定されたマテリアルのために、この値は1以下でなければならない。その他のとき、背景は表示されない。この動きは、背景に指定されたテクスチャがdwRampSizeメンバが1以上でマテリアルを結合しているときにも表れる。

テクスチャのハンドルを取得するには、ドライバのテクスチャをロードする。これは、デバイスにロードされるときにのみ使われる。

参照　IDirect3DMaterial::GetMaterial、IDirect3DMaterial::SetMaterial


D3DMATRIX

typedef struct _D3DMATRIX {

    D3DVALUE _11, _12, _13, _14;

    D3DVALUE _21, _22, _23, _24;

    D3DVALUE _31, _32, _33, _34;

    D3DVALUE _41, _42, _43, _44;

} D3DMATRIX, *LPD3DMATRIX;

IDirect3DDevice::GetMatrixやIDirect3DDevice::SetMatrixのようなメソッドのための行列を示す。

Direct3Dで、投影行列の_44要素は負数を設定できない。アプリケーションでこの位置に負数を使う必要がある場合、その代わりに-1で投影行列全体を縮尺する。

参照　IDirect3DDevice::GetMatrix、IDirect3DDevice::SetMatrix


D3DMATRIXLOAD

typedef struct _D3DMATRIXLOAD {

    D3DMATRIXHANDLE hDestMatrix;

    D3DMATRIXHANDLE hSrcMatrix;

} D3DMATRIXLOAD, *LPD3DMATRIXLOAD;

D3DOPCODE列挙型のD3DOP_MATRIXLOADオペコードのためのオペランド・データを示す。

hDestMatrix ､ hSrcMatrix

転送先と転送元の行列のハンドル。

参照　D3DOPCODE


D3DMATRIXMULTIPLY

typedef struct _D3DMATRIXMULTIPLY {

    D3DMATRIXHANDLE hDestMatrix;

    D3DMATRIXHANDLE hSrcMatrix1;

    D3DMATRIXHANDLE hSrcMatrix2;

} D3DMATRIXMULTIPLY, *LPD3DMATRIXMULTIPLY;

D3DOPCODE列挙型のD3DOP_MATRIXMULTIPLYオペコードのためのオペランド・データを示す。

hDestMatrix

計算結果を格納する行列のハンドル。

hSrcMatrix1 ､ hSrcMatrix2

1番目と2番目の計算対象の行列のハンドル。

参照　D3DOPCODE


D3DPICKRECORD

typedef struct _D3DPICKRECORD {

    BYTE     bOpcode;

    BYTE     bPad;

    DWORD    dwOffset;

    D3DVALUE dvZ;

} D3DPICKRECORD, *LPD3DPICKRECORD;

IDirect3DDevice::GetPickRecordsメソッド用に、実行バッファの選択プリミティブについての情報を返す。

bOpcode

選択プリミティブのオペコード。

bPad

Padバイト。

dwOffset

検出された選択プリミティブの実行バッファの先頭からのオフセット。

dvZ

選択プリミティブの深度。

選択プリミティブのx、y座標は、選択レコードで生成されるIDirect3DDevice::Pickメソッドにより指定される。

参照　IDirect3DDevice::GetPickRecords、 IDirect3DDevice::Pick


D3DPOINT

typedef struct _D3DPOINT {

    WORD wCount;

    WORD wFirst;

} D3DPOINT, *LPD3DPOINT;

D3DOPCODE列挙型のD3DOP_POINTオペコードのオペランド・データを示す。

wCount

頂点の数。

wFirst

最初の頂点のインデックス。

頂点は、頂点リストにより描画される。

参照　D3DOPCODE


D3DPRIMCAPS

typedef struct _D3DPrimCaps {

    DWORD dwSize;

    DWORD dwMiscCaps;

    DWORD dwRasterCaps;

    DWORD dwZCmpCaps;

    DWORD dwSrcBlendCaps;

    DWORD dwDestBlendCaps;

    DWORD dwAlphaCmpCaps;

    DWORD dwShadeCaps;

    DWORD dwTextureCaps;

    DWORD dwTextureFilterCaps;

    DWORD dwTextureBlendCaps;

    DWORD dwTextureAddressCaps;

    DWORD dwStippleWidth;

    DWORD dwStippleHeight;

} D3DPRIMCAPS, *LPD3DPRIMCAPS;

それぞれのプリミティブ型の能力を定義する。デバイスの生成時やデバイスの能力を取得するときに使用される。この構造体は、D3DDEVICEDESC構造体の中のいくつかのメンバを定義する。

dwSize

この構造体のバイト単位のサイズ。

dwMiscCaps

このプリミティブの総体的な能力。このメンバには、次の値のひとつ以上を設定できる。

D3DPMISCCAPS_CONFORMANT

	デバイスは、OpenGL標準に準じている。

D3DPMISCCAPS_CULLCCW

	デバイスは、D3DRENDERSTATE_CULLMODE状態で選択した左回りをサポートする(三角形のプリミティブの場合のみ)。D3DCULL列挙型のD3DCULL_CCWメンバに対応する。

D3DPMISCCAPS_CULLCW

	デバイスは、D3DRENDERSTATE_CULLMODE状態で選択した右回りの三角形をサポートする(三角形のプリミティブの場合のみ)。D3DCULL列挙型のD3DCULL_CCWメンバに対応する。

D3DPMISCCAPS_CULLNONE

	デバイスは、選択している三角形を実行できない。D3DCULL列挙型のD3DCULL_NONEメンバに対応する。

D3DPMISCCAPS_LINEPATTERNREP

	デバイスは、D3DLINEPATTERN構造体のwRepeatFactorメンバに1以上の値を使用できる(直線描画のプリミティブの場合のみ)。

D3DPMISCCAPS_MASKPLANES

	デバイスは、色のビットマスクを実行できる。

D3DPMISCCAPS_MASKZ

	デバイスは、ピクセル処理でZバッファの修正を可能としたり不可能としたりする。
dwRasterCaps

ラスタ描画の能力情報。このメンバには、次の値をひとつ以上設定できる。

D3DPRASTERCAPS_DITHER

	デバイスは、色の再現力を良くするためにディザ表示できる。

D3DPRASTERCAPS_FOGTABLE

	デバイスは、ピクセルの深さを指すフォグ値を変換する取得テーブルと照合して、フォグ値を算出する。

D3DPRASTERCAPS_FOGVERTEX

	デバイスは、照明処理の間中、D3DTLVERTEX構造体のspecularメンバで与えられたD3DCOLOR値のアルファ成分中の値を計算する。そして、ラスタの間中、フォグ値を書き換える。

D3DPRASTERCAPS_PAT

	ドライバは、パターン描画を処理できる。(D3DRENDERSTATE_LINEPATTERNや D3DRENDERSTATE_STIPPLEPATTERNレンダリング状態のひとつでの線描や塗りつぶし)プリミティブ用に照会される。

D3DPRASTERCAPS_ROP2

	デバイスは、R2_COPYPEN以外のラスタ処理をサポートできる。

D3DPRASTERCAPS_STIPPLE

	デバイスは、半透明をシミュレートするポリゴンを点描できる。

D3DPRASTERCAPS_SUBPIXEL

	デバイスは、一番近い整数型のピクセル座標でなく、Z、色、テクスチャのデータのサブピクセル配置で処理する。これは、Zのブリード線を避けるのを助ける(色のジッタとピクセルのテクスチャ値も)。これらは、有効としたり無効としたりできない(デバイスは、サブピクセル配置を実行したり、しなかったりする)。このビットは、レンダリングの質を決定することのできるDirect3Dクライアントに提供される。

D3DPRASTERCAPS_SUBPIXELX

	デバイスは、X軸に沿ったサブピクセル配置であり、整数型のY軸の走査線を積み上げたものである。サブピクセル配置についての詳細は、D3DPRASTERCAPS_SUBPIXELを参照すること。

D3DPRASTERCAPS_XOR

	デバイスは排他的論理和処理(XOR)をサポートする。このフラグが設定されず、D3DPRIM_RASTER_ROP2が設定されている場合は、排他的論理和処理がサポートされていなければならない。

D3DPRASTERCAPS_ZTEST

	デバイスはZテスト処理を実行できる。これは、効果的にプリミティブをレンダリングし、レンダリングされたどのようなZピクセルでも表示する。
dwZCmpCaps

ドライバが実行可能な関数を比較するZバッファ。このメンバは、次の値をひとつ以上設定できる。

D3DPCMPCAPS_ALWAYS

	つねにZテストを通す。

D3DPCMPCAPS_EQUAL

	新規のZが現在のZと等しい場合、Zテストを通す。

D3DPCMPCAPS_GREATER

	新規のZが現在のZより大きい場合、Zテストを通す。

D3DPCMPCAPS_GREATEREQUAL

	新規のZが現在のZより大きいか等しい場合、Zテストを通す。

D3DPCMPCAPS_LESS

	新規のZが現在のZより小さい場合、Zテストを通す。

D3DPCMPCAPS_LESSEQUAL

	新規のZが現在のZより小さいか等しい場合、Zテストを通す。

D3DPCMPCAPS_NEVER

	つねにZテストを失敗する。

D3DPCMPCAPS_NOTEQUAL

	新規のZが現在のZと等しくない場合、Zテストを通す。
dwSrcBlendCaps

ソースのブレンディング情報。このメンバは、次の値をひとつ以上設定できる(RGBA値のソースとデスティネーションは、それぞれsとdで表す)。

D3DPBLENDCAPS_BOTHINVSRCALPHA

	ソースのブレンディング係数(1-As, 1-As, 1-As, 1-As)とデスティネーションのブレンディング係数(As, As, As, As)。デスティネーションのブレンディングの選択は、無効となる。

D3DPBLENDCAPS_BOTHSRCALPHA

	ソースのブレンディング係数(As, As, As, As)とデスティネーションのブレンディング係数(1-As, 1-As, 1-As, 1-As)。デスティネーションのブレンディングの選択は、無効となる。

D3DPBLENDCAPS_DESTALPHA

	ブレンディング係数(Ad, Ad, Ad, Ad)。

D3DPBLENDCAPS_DESTCOLOR

	ブレンディング係数(Rd, Gd, Bd, Ad)。

D3DPBLENDCAPS_INVDESTALPHA

	ブレンディング係数(1-Ad, 1-Ad, 1-Ad, 1-Ad)。

D3DPBLENDCAPS_INVDESTCOLOR

	ブレンディング係数(1-Rd, 1-Gd, 1-Bd, 1-Ad)。

D3DPBLENDCAPS_INVSRCALPHA

	ブレンディング係数(1-As, 1-As, 1-As, 1-As)。

D3DPBLENDCAPS_INVSRCCOLOR

	ブレンディング係数(1-Rd, 1-Gd, 1-Bd, 1-Ad)。

D3DPBLENDCAPS_ONE

	ブレンディング係数(1, 1, 1, 1)。

D3DPBLENDCAPS_SRCALPHA

	ブレンディング係数(As, As, As, As)。

D3DPBLENDCAPS_SRCALPHASAT

	ブレンディング係数(f, f, f, 1)、f = min(As, 1-Ad)。

D3DPBLENDCAPS_SRCCOLOR

	ブレンディング係数(Rs, Gs, Bs, As)。

D3DPBLENDCAPS_ZERO

	ブレンディング係数(0, 0, 0, 0)。
dwDestBlendCaps

デスティネーション混合情報。このメンバは、dwSrcBlendCapsメンバで定義された能力情報と同じである。

dwAlphaCmpCaps

ドライバが実行可能な関数を比較するアルファ・テスト。このメンバは、dwZCmpCapsメンバで定義された能力情報と同じである。

dwShadeCaps

デバイスが実行できるシェーディング処理。一般的に、デバイスが与えられたコマンド(D3DOP_TRIANGLEのような)を実行できる場合は、D3DSHADE_FLATモード(D3DSHADEMODE列挙型で指定されるような)をサポートする。このフラグは、グロー・シェーディングとフォン・シェーディングをサポートするドライバや、３つのカラー生成モードにそれぞれサポートされるアルファ・カラー・コンポーネントを指定する。アルファ要素が与えられたモードでサポートされない場合、そのモードで生成された色のアルファ値は必ず255になる。この数値が、アルファの最大値(アルファが最強)である。

三角形の色、ハイライト投影、フォグ、アルファ成分にはそれぞれ、デバイス・ドライバがアプリケーションに通知する能力フラグがある。

このフラグは、シェーディング・モード、カラー・モデル、そして混合や点描される色のアルファ成分で更新される。詳細は、「ポリゴン」を参照すること。

このメンバは、次の値をひとつ以上設定できる。

D3DPSHADECAPS_ALPHAFLATBLEND

D3DPSHADECAPS_ALPHAFLATSTIPPLED

	デバイスは、透過的にそれぞれ混合や点描された平面(D3DSHADEMODE列挙型のD3DSHADE_FLAT)のアルファ成分をサポートできる。これらのモードで、ひとつの要素のためのアルファ色成分は、要素の最初の頂点の色の1部分として与えられる。

D3DPSHADECAPS_ALPHAGOURAUDBLEND

D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED

	デバイスは、透過的にそれぞれ混合や点描されたグロー(D3DSHADEMODE列挙型のD3DSHADE_GOURAUD)のアルファ成分をサポートできる。これらのモードでは、アルファ色成分は頂点にあたえられ、他の色成分とともに書き込まれる。

D3DPSHADECAPS_ALPHAPHONGBLEND

D3DPSHADECAPS_ALPHAPHONGSTIPPLED

	デバイスは、透過的にそれぞれ混合や点描されたフォン(D3DSHADEMODE列挙型のD3DSHADE_PHONG)のアルファ成分をサポートできる。これらのモードで、頂点パラメータは赤、緑、青の色成分の適応する光源効果がピクセル単位に再評価される。

D3DPSHADECAPS_COLORFLATMONO

D3DPSHADECAPS_COLORFLATRGB

	デバイスは、D3DCOLOR_MONOとD3DCOLOR_RGBカラーモードの平面シェーディングの色付けがサポートできる。これらのモードでは、ひとつの要素の色成分は、要素の最初の頂点の色として与えられる。モノクロ光源モードで、色の青成分だけが書き換えられる。RGB光源モードでは、赤、緑、青成分が書き換えられる。

D3DPSHADECAPS_COLORGOURAUDMONO

D3DPSHADECAPS_COLORGOURAUDRGB

	デバイスは、D3DCOLOR_MONOとD3DCOLOR_RGBカラーモードのグロー・シェーディングの色付けがサポートできる。これらのモードで、ひとつの要素のためのアルファ色成分は頂点にあたえられ、他の色成分とともに平面を渡って書き込まれる。モノクロ光源モードで、色の青成分だけは、書き換えられる。RGB光源モードでは、赤、緑、青成分は書き換えられる。

D3DPSHADECAPS_COLORPHONGMONO

D3DPSHADECAPS_COLORPHONGRGB

	デバイスは、D3DCOLOR_MONOとD3DCOLOR_RGBカラーモードのフォン・シェーディングの色付けがサポートできる。これらのモードで、頂点パラメータはピクセル単位に再評価される。光源効果は、RGBモードの赤、緑、青の色成分で適応される。フォン・シェーディングは現在サポートされていない。

D3DPSHADECAPS_FOGFLAT

D3DPSHADECAPS_FOGGOURAUD

D3DPSHADECAPS_FOGPHONG

	デバイスは、平面、グロー、フォンモードでフォグをサポートできる。フォン・シェーディングは、現在サポートされていない。

D3DPSHADECAPS_SPECULARFLATMONO

D3DPSHADECAPS_SPECULARFLATRGB

	デバイスは、D3DCOLOR_MONOとD3DCOLOR_RGBカラーモードの平面シェーディングのハイライト投影をサポートできる。

D3DPSHADECAPS_SPECULARGOURAUDMONO

D3DPSHADECAPS_SPECULARGOURAUDRGB

	デバイスは、D3DCOLOR_MONOとD3DCOLOR_RGBカラーモードのグロー・シェーディングのハイライト投影をサポートできる。

D3DPSHADECAPS_SPECULARPHONGMONO

D3DPSHADECAPS_SPECULARPHONGRGB

	デバイスは、D3DCOLOR_MONOとD3DCOLOR_RGBカラーモードのフォン・シェーディングのハイライト投影をサポートできる。
dwTextureCaps

混合テクスチャ・マッピング情報。このメンバは、次の値をひとつ以上設定できる。

D3DPTEXTURECAPS_ALPHA

	D3DTEX_DECALとD3DTEX_MODULATEテクスチャフィルターモードのRGBAテクスチャをサポートする。この機能が設定されていない場合、RGBテクスチャのみが、これらのモードでサポートされる。このフラグの設定を無視すると、アルファは使用可能なD3DTEX_DECAL_MASK、D3DTEX_DECAL_ALPHA、D3DTEX_MODULATE_ALPHAフィルタモードでサポートされる。

D3DPTEXTURECAPS_BORDER

	境界線に沿ってテクスチャ・マッピング をサポートする。

D3DPTEXTURECAPS_PERSPECTIVE

	透視投影がサポートされる。

D3DPTEXTURECAPS_POW2

	このフラグが設定された場合、ミップマップでないテクスチャは、2乗で指定された幅と高さを持たなければならない(ミップマップ・テクスチャは、必ず2乗次元でなければならない)。

D3DPTEXTURECAPS_SQUAREONLY

	テクスチャは、すべて矩形でなければならない。

D3DPTEXTURECAPS_TRANSPARENCY

	透過テクスチャがサポートされる(現在の透過色でないこれらのテクスチャsのみ描画される)。
dwTextureFilterCaps

テクスチャのマッピング情報。このメンバは、次の値をひとつ以上設定できる。

D3DPTFILTERCAPS_LINEAR

	ピクセルを取り巻くテクセルの2×2領域に重み付けされた平均値。これは、拡大と縮小の両方で使用される。拡大か縮小がサポートされているときは、両方がサポートされていなければならない。

D3DPTFILTERCAPS_LINEARMIPLINEAR

	D3DPRIM_TEX_MIP_LINEARと同様だが、ふたつの近似ミップマップを書き換える。

D3DPTFILTERCAPS_LINEARMIPNEAREST

	D3DPRIM_TEX_MIP_NEARESTと同様だが、ふたつの近似ミップマップを書き換える。

D3DPTFILTERCAPS_MIPLINEAR

	D3DPRIM_TEX_LINEARと同様だが、選択テクセルに対応するミップマップを使用する。

D3DPTFILTERCAPS_MIPNEAREST

	D3DPRIM_TEX_NEARESTと同様だが、選択テクセルに対応するミップマップを使用する。

D3DPTFILTERCAPS_NEAREST

	ピクセル値の近似座標のテクセルが使用される。これは、拡大と縮小の両方で使用される。拡大か縮小がサポートされているときは、両方がサポートされていなければならない。
dwTextureBlendCaps

テクスチャ混合情報。テクスチャ混合モードを指定するためD3DTEXTUREBLEND列挙型を照会する。このメンバは、次の値をひとつ以上設定できる。

D3DPTBLENDCAPS_COPY

	テクスチャ混合モードのコピー(D3DTEXTUREBLEND列挙型よりD3DTBLEND_COPY)をサポートする。

D3DPTBLENDCAPS_DECAL

	デカール・テクスチャ混合モード(D3DTEXTUREBLEND列挙型よりD3DTBLEND_DECAL)をサポートする。

D3DPTBLENDCAPS_DECALALPHA

	デカール・アルファ・テクスチャ混合モード(D3DTEXTUREBLEND列挙型よりD3DTBLEND_DECALALPHA)をサポートする。

D3DPTBLENDCAPS_DECALMASK

	デカール・マスク・テクスチャ混合モード(D3DTEXTUREBLEND列挙型よりD3DTBLEND_DECALMASK)をサポートする。

D3DPTBLENDCAPS_MODULATE

	変調テクスチャ混合モード(D3DTEXTUREBLEND列挙型よりD3DTBLEND_MODULATE)をサポートする。

D3DPTBLENDCAPS_MODULATEALPHA

	変調アルファ・テクスチャ混合モード(D3DTEXTUREBLEND列挙型よりD3DTBLEND_MODULATEALPHA)をサポートする。

D3DPTBLENDCAPS_MODULATEMASK

	変調マスク・テクスチャ混合モード(D3DTEXTUREBLEND列挙型よりD3DTBLEND_MODULATEMASK)をサポートする。
dwTextureAddressCaps

テクスチャのアドレス情報。このメンバは、次の値をひとつ以上設定できる。

D3DPTADDRESSCAPS_CLAMP

	デバイスは、テクスチャの固定が可能である。

D3DPTADDRESSCAPS_MIRROR

	デバイスは、テクスチャの反転が可能である。

D3DPTADDRESSCAPS_WRAP

	デバイスは、テクスチャの張り付けが可能である。
dwStippleWidth ､ dwStippleHeight

サポートされた点描の最大幅と高さ(32×32以上)。


D3DPROCESSVERTICES

typedef struct _D3DPROCESSVERTICES {

    DWORD dwFlags;

    WORD  wStart;

    WORD  wDest;

    DWORD dwCount;

    DWORD dwReserved;

} D3DPROCESSVERTICES, *LPD3DPROCESSVERTICES;

頂点情報のドライバによる処理方法を示す。これは、D3DOPCODE列挙型の中のD3DOP_PROCESSVERTICESオペコードで使用される。

dwFlags

ドライバによる頂点の処理方法を指定する次のフラグを、ひとつ以上設定する。

D3DPROCESSVERTICES_COPY

	頂点情報は、ドライバに再利用される。実行バッファの中の頂点情報が再利用されると、ドライバは頂点を処理する必要がなくなり、その結果、処理速度が改善される。

D3DPROCESSVERTICES_NOCOLOR

	頂点は色付けされない。

D3DPROCESSVERTICES_OPMASK

	D3DPROCESSVERTICES_NOCOLORや D3DPROCESSVERTICES_UPDATEEXTENTSの実行でdwFlagsメンバの他のフラグのビットマスクを指定する。

D3DPROCESSVERTICES_TRANSFORM

	頂点は変換される。

D3DPROCESSVERTICES_TRANSFORMLIGHT

	頂点は変換され照明効果も与えられる。

D3DPROCESSVERTICES_UPDATEEXTENTS

	更新された変換後の頂点の範囲。この情報はD3DSTATUS構造体のdrExtentメンバに返る。
wStart

ソースの最初の頂点のインデックス。

wDest

ローカル・バッファの最初の頂点のインデックス。

dwCount

処理される頂点数。

dwReserved

予約済み。0でなければならない。

参照　D3DOPCODE


D3DRECT

typedef struct _D3DRECT {

    union {

        LONG x1;

        LONG lX1;

    };

    union {

        LONG y1;

        LONG lY1;

    };

    union {

        LONG x2;

        LONG lX2;

    };

    union {

        LONG y2;

        LONG lY2;

    };

} D3DRECT, *LPD3DRECT;

矩形の定義。

lX1 ､lY1

矩形の左上隅の座標。

lX2 ､lY2

矩形の右下隅の座標。

参照　D3DRMUPDATECALLBACK、 IDirect3DDevice::Pick、IDirect3DViewport::Clear


D3DSPAN

typedef struct _D3DSPAN {

    WORD wCount;

    WORD wFirst;

} D3DSPAN, *LPD3DSPAN;

D3DOPCODE列挙型でのD3DOP_SPANオペコード用に、頂点のスパンを定義する。スパンは、等しいy値を持つ頂点を結んで張られる面である。y値が変わると、新しいスパンが作られる。

wCount

スパンの数。

wFirst

最初の頂点のインデックス。

参照　D3DOPCODE


D3DSTATE

typedef struct _D3DSTATE {

    union {

        D3DTRANSFORMSTATETYPE dtstTransformStateType;

        D3DLIGHTSTATETYPE     dlstLightStateType;

        D3DRENDERSTATETYPE    drstRenderStateType;

    };

    union {

        DWORD                 dwArg[1];

        D3DVALUE              dvArg[1];

    };

} D3DSTATE, *LPD3DSTATE;

D3DOPCODE 列挙型の中のD3DOP_STATETRANSFORM、D3DOP_STATELIGHTとD3DOP_STATERENDERオペコード用のレンダリング状態を指定する。この構造体の最初のメンバは、関連した列挙型である。2番目のメンバは、その型のための値である。

dtstTransformStateType、 dlstLightStateType、 drstRenderStateType

レンダリング状態で指定されるD3DTRANSFORMSTATETYPE、D3DLIGHTSTATETYPE、D3DRENDERSTATETYPE 列挙型のメンバのひとつ。

dvArg

この構造体の最初のメンバで指定された型の値。

参照　D3DLIGHTSTATETYPE、 D3DOPCODE、 D3DRENDERSTATETYPE、 D3DTRANSFORMSTATETYPE、 D3DVALUE


D3DSTATS

typedef struct _D3DSTATS {

    DWORD dwSize;

    DWORD dwTrianglesDrawn;

    DWORD dwLinesDrawn;

    DWORD dwPointsDrawn;

    DWORD dwSpansDrawn;

    DWORD dwVerticesProcessed;

} D3DSTATS, *LPD3DSTATS;

IDirect3DDevice::GetStats メソッドにより使用される統計情報を含む。

dwSize

この構造体のバイト単位のサイズ。

dwTrianglesDrawn, dwLinesDrawn, dwPointsDrawn, dwSpansDrawn

デバイスの生成以後描画された三角形、線、点、スパンの数。

dwVerticesProcessed

デバイスの生成以後処理された頂点の数。

参照　IDirect3DDevice::GetStats


D3DSTATUS

typedef struct _D3DSTATUS {

    DWORD   dwFlags;

    DWORD   dwStatus;

    D3DRECT drExtent;

} D3DSTATUS, *LPD3DSTATUS;

実行バッファの現在の状態を指定する。この構造体は、D3DEXECUTEDATA 構造体の一部やD3DOPCODE 列挙型の中のD3DOP_SETSTATUSオペコードで使用される。

dwFlags

ステータス、範囲、またはその両方であることを指定する次のフラグのひとつを設定する。

D3DSETSTATUS_STATUS

	ステータスを設定。

D3DSETSTATUS_EXTENTS

	drExtentメンバで指定された範囲を設定。

D3DSETSTATUS_ALL

	ステータスと範囲の両方を設定。
dwStatus

クリッピング・フラグ。このメンバは、次のフラグのひとつ以上を設定する。

組み合わせと一般フラグ

D3DSTATUS_CLIPINTERSECTION

	すべてのCLIPINTERSECTIONフラグの組み合わせ。

D3DSTATUS_CLIPUNIONALL

	すべてのCLIPUNIONフラグの組み合わせ。

D3DSTATUS_DEFAULT

	D3DSTATUS_CLIPINTERSECTIONと D3DSTATUS_ZNOTVISIBLEフラグの組み合わせ。この値が、デフォルトである。

D3DSTATUS_ZNOTVISIBLE

クリップ交差フラグ

D3DSTATUS_CLIPINTERSECTIONBACK

	視錐台の後方クリップ面の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONBOTTOM

	視錐台の下の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONFRONT

	視錐台の前方クリップ面の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONGEN0～D3DSTATUS_CLIPINTERSECTIONGEN5

	アプリケーション定義のクリップ面の論理積をとる。

D3DSTATUS_CLIPINTERSECTIONLEFT

	視錐台の左側の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONRIGHT

	視錐台の右側の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONTOP

	視錐台の上の頂点のクリッピング・フラグの論理積をとる。
クリップ結合フラグ

D3DSTATUS_CLIPUNIONBACK

	D3DCLIP_BACKと同じ。

D3DSTATUS_CLIPUNIONBOTTOM

	D3DCLIP_BOTTOMと同じ。

D3DSTATUS_CLIPUNIONFRONT

	D3DCLIP_FRONTと同じ。

D3DSTATUS_CLIPUNIONGEN0～D3DSTATUS_CLIPUNIONGEN5

	D3DCLIP_GEN0～D3DCLIP_GEN5と同じ。

D3DSTATUS_CLIPUNIONLEFT

	D3DCLIP_LEFTと同じ。

D3DSTATUS_CLIPUNIONRIGHT

	D3DCLIP_RIGHTと同じ。

D3DSTATUS_CLIPUNIONTOP

	D3DCLIP_TOPと同じ。
基本クリッピング・フラグ

D3DCLIP_BACK

	視錐台の背面によりクリッピングされる。

D3DCLIP_BOTTOM

	視錐台の底面によりクリッピングされる。

D3DCLIP_FRONT

	視錐台の前面によりクリッピングされる。

D3DCLIP_LEFT

	視錐台の左側面によりクリッピングされる。

D3DCLIP_RIGHT

	視錐台の右側面によりクリッピングされる。

D3DCLIP_TOP

	視錐台の上底面によりクリッピングされる。

D3DCLIP_GEN0～D3DCLIP_GEN5

	アプリケーション定義のクリップ面。
drExtent

すべての頂点をその内に含む矩形を定義するD3DRECT構造体。たとえば、D3DPROCESSVERTICES 構造体の中で設定されるD3DPROCESSVERTICES_UPDATEEXTENTSフラグを取得するD3DOP_PROCESSVERTICESオペコードの出力を含む領域を定義する。

状態は実行状態であり、各実行の間に更新される。矩形の大きさは、各実行で増大するが収縮しない。D3DOP_SETSTATUSオペコードによりリセットできる。

参照　D3DEXECUTEDATA、 D3DOPCODE、 D3DRECT


D3DTEXTURELOAD

typedef struct _D3DTEXTURELOAD {

    D3DTEXTUREHANDLE hDestTexture;

    D3DTEXTUREHANDLE hSrcTexture;

} D3DTEXTURELOAD, *LPD3DTEXTURELOAD;

D3DOPCODE列挙型の中のD3DOP_TEXTURELOADオペコードのオペランド・データを指定する。

hDestTexture

転送先テクスチャのハンドル。

hSrcTexture

転送元テクスチャのハンドル。

テクスチャは、hDestTextureとhSrcTextureメンバが同じ大きさか調べる。


D3DTLVERTEX

typedef struct _D3DTLVERTEX {

    union {

        D3DVALUE sx;

        D3DVALUE dvSX;

    };

    union {

        D3DVALUE sy;

        D3DVALUE dvSY;

    };

    union {

        D3DVALUE sz;

        D3DVALUE dvSZ;

    };

    union {

        D3DVALUE rhw;

        D3DVALUE dvRHW;

    };

    union {

        D3DCOLOR color;

        D3DCOLOR dcColor;

    };

    union {

        D3DCOLOR specular;

        D3DCOLOR dcSpecular;

    };

    union {

        D3DVALUE tu;

        D3DVALUE dvTU;

    };

    union {

        D3DVALUE tv;

        D3DVALUE dvTV;

    };

} D3DTLVERTEX, *LPD3DTLVERTEX;

D3DLIGHTDATA 構造体の変換や照明の頂点(カラーのスクリーン座標)を定義する。

dvSX, dvSY, dvSZ

スクリーン座標で頂点を指定するD3DVALUE型の値。

dvRHW

D3DVALUE型の値。この値は、１をZ軸に沿った原点からオブジェクトへの距離で割った値である。

dcColor ､ dcSpecular

頂点の色と投影を指定するD3DCOLOR型の値。

dvTU ､ dvTV

頂点のテクスチャ指定するD3DVALUE型の値。

参照　D3DLIGHTDATA


D3DTRANSFORMCAPS

typedef struct _D3DTransformCaps {

    DWORD dwSize;

    DWORD dwCaps;

} D3DTRANSFORMCAPS, *LPD3DTRANSFORMCAPS;

デバイスの変換能力を指定する。この構造体は、D3DDEVICEDESC構造体の一部である。

dwSize

この構造体のバイト単位のサイズ。

dwCaps

変換中のシステムがクリッピングするかどうかを指定するフラグ。このメンバは、0または次のフラグが設定できる。

D3DTRANSFORMCAPS_CLIP	システムは変換中にクリッピングする。


D3DTRANSFORMDATA

typedef struct _D3DTRANSFORMDATA {

    DWORD        dwSize;

    LPVOID       lpIn;

    DWORD        dwInSize;

    LPVOID       lpOut;

    DWORD        dwOutSize;

    LPD3DHVERTEX lpHOut;

    DWORD        dwClip;

    DWORD        dwClipIntersection;

    DWORD        dwClipUnion;

    D3DRECT      drExtent;

} D3DTRANSFORMDATA, *LPD3DTRANSFORMDATA;

IDirect3DViewport::TransformVerticesメソッド用の変換情報を持つ。

dwSize

この構造体のバイト単位のサイズ。

lpIn

変換される頂点へのポインタ。これは、D3DLVERTEX構造体である。

dwInSize

変換される頂点の間隔。

lpOut

変換された頂点へのポインタ。

dwOutSize

出力頂点の間隔。

lpHOut

均質変換された頂点を含む値へのポインタ。この値は、D3DHVERTEX 構造体である。

wClip

頂点がどのようにクリッピングされるかを指定するフラグ。このメンバには、次の値をひとつ以上設定する。

D3DCLIP_BACK

	視錐台の背面によりクリッピングされる。

D3DCLIP_BOTTOM

	視錐台の底面によりクリッピングされる。

D3DCLIP_FRONT

	視錐台の前面によりクリッピングされる。

D3DCLIP_GEN0 through D3DCLIP_GEN5

	アプリケーション定義のクリップ面。

D3DCLIP_LEFT

	視錐台の左側面によりクリッピングされる。

D3DCLIP_RIGHT

	視錐台の右側面によりクリッピングされる。

D3DCLIP_TOP

	視錐台の上底面によりクリッピングされる。
dwClipIntersection

クリッピング・フラグの交差を示すフラグ。このメンバには、次の値をひとつ以上設定する。

D3DSTATUS_CLIPINTERSECTIONBACK

	視錐台の後方クリップ面の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONBOTTOM

	視錐台の下の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONFRONT

	視錐台の前方クリップ面の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONGEN0～D3DSTATUS_CLIPINTERSECTIONGEN5

	アプリケーション定義のクリップ面の論理積をとる。

D3DSTATUS_CLIPINTERSECTIONLEFT

	視錐台の左側の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONRIGHT

	視錐台の右側の頂点のクリッピング・フラグの論理積をとる。

D3DSTATUS_CLIPINTERSECTIONTOP

	視錐台の上の頂点のクリッピング・フラグの論理積をとる。
dwClipUnion

クリッピング・フラグの結合を示すフラグ。このメンバには、次の値をひとつ以上設定する。

D3DSTATUS_CLIPUNIONBACK

	D3DCLIP_BACKと同じ。

D3DSTATUS_CLIPUNIONBOTTOM

	D3DCLIP_BOTTOMと同じ。

D3DSTATUS_CLIPUNIONFRONT

	D3DCLIP_FRONTと同じ。

D3DSTATUS_CLIPUNIONGEN0～D3DSTATUS_CLIPUNIONGEN5

	D3DCLIP_GEN0～D3DCLIP_GEN5と同じ。

D3DSTATUS_CLIPUNIONLEFT

	D3DCLIP_LEFTと同じ。

D3DSTATUS_CLIPUNIONRIGHT

	D3DCLIP_RIGHTと同じ。

D3DSTATUS_CLIPUNIONTOP

	D3DCLIP_TOPと同じ。
drExtent

変換後の頂点の範囲を決定する値。この構造体は、ジオメトリ変換後のスクリーン範囲の変換モジュールによりセットされる。クリッピングされるため、この範囲は視錐台内部の頂点だけを含む。この値はD3DRECT構造体である。

各入力頂点は、ジオメトリ・モデル空間での[x y z]座標で与えられた３つのベクトル頂点である。dwInSizeメンバは、各頂点が、例外データをインラインで格納するためのアプリケーションを許可する頂点間を移動する量を与える。

変換モジュールにより生成された頂点は、16ビット精度値として格納される。クリッピングは、与えられた変換後の頂点をクリッピングする視錐台プレーンの包含的論理和で設定された整数ビット・フィールドとして扱われる。

参照　IDirect3DViewport::TransformVertices


D3DTRIANGLE

typedef struct _D3DTRIANGLE {

    union {

        WORD v1;

        WORD wV1;

    };

    union {

        WORD v2;

        WORD wV2;

    };

    union {

        WORD v3;

        WORD wV3;

    };

    WORD     wFlags;

} D3DTRIANGLE, *LPD3DTRIANGLE;

すべての三角形の基本型を指定する。三角形は、基本的なレンダリング要素である。

関連情報は、D3DOPCODE列挙型のD3DOP_TRIANGLEメンバを参照すること。

wV1、 wV2、 wV3

三角形を指定する頂点。

wFlags

使用可能な三角形のエッジを定義するフラグ(この情報は、ワイヤフレーム・モードでのみ有効)。このメンバには、次の値をひとつ以上設定する。

エッジ・フラグ

D3DTRIFLAG_EDGEENABLE1

	エッジv1�v2を定義する。

D3DTRIFLAG_EDGEENABLE2

	エッジv2�v3を定義する。

D3DTRIFLAG_EDGEENABLE3

	エッジv3�v1を定義する。

D3DTRIFLAG_EDGEENABLETRIANGLE

	すべてのエッジを定義する。
展開図と扇形フラグ

D3DTRIFLAG_EVEN

	現在の三角形のv1�v2エッジは、直前の三角形のv3�v1エッジに合わせられる。v1は直前のv1に、v2は直前のv3となる。

D3DTRIFLAG_ODD

	現在の三角形のv1�v2エッジは、直前の三角形のv2�v3エッジに合わせられる。v1は直前のv3に、v2は直前のv2となる。

D3DTRIFLAG_START

	展開図や扇形を開始して、３つの頂点をロードする。

D3DTRIFLAG_STARTFLAT(len)

	この三角形が切り抜かれたとき、その後の三角形の指定された数を切り抜く。この長さは、0より大きく30より小さい。
この構造体は、すべての三角形を塗りつぶすために直接使用できる。平面シェーディングで、色と投影成分は最初の頂点から取得する。３つの頂点インデックスのv1、v2、v3は、実行バッファの開始の頂点リストの中の頂点インデックスである。

使用可能なエッジは、ワイヤフレーム・モードで可視状態である。アプリケーションがワイヤフレームの三角形を表示するとき、2回エッジを描くのを避けるため、隣り合うどちらかのエッジが使用可能となる。

The D3DTRIFLAG_ODDとD3DTRIFLAG_EVENフラグは、通常の三角形の展開図か扇形の中の三角形の位置を参照する。三角形の展開図が5つの三角形の場合、次のフラグで展開図を決定できる。

D3DTRIFLAG_START
D3DTRIFLAG_ODD
D3DTRIFLAG_EVEN
D3DTRIFLAG_ODD
D3DTRIFLAG_EVEN
同様に、次のフラグで5つの三角形の扇形を決定できる。

D3DTRIFLAG_START
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
次のフラグで、5つの三角形の平面三角形の扇形を決定できる。

D3DTRIFLAG_STARTFLAT(4)
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
参照　三角形の展開図と扇形


D3DVECTOR

typedef struct _D3DVECTOR {

    union {

        D3DVALUE x;

        D3DVALUE dvX;

    };

    union {

        D3DVALUE y;

        D3DVALUE dvY;

    };

    union {

        D3DVALUE z;

        D3DVALUE dvZ;

    };

} D3DVECTOR, *LPD3DVECTOR;

多くのDirect3DとDirect3DRMメンバと構造体のベクトルを定義する。

dvX、 dvY、 dvZ

ベクトルを指定するD3DVALUE型の値。

参照　D3DLIGHT、 D3DLIGHTINGELEMENT、 D3DRMBOX、 D3DRMQUATERNION、 D3DRMVERTEX


D3DVERTEX

typedef struct _D3DVERTEX {

    union {

        D3DVALUE x;

        D3DVALUE dvX;

    };

    union {

        D3DVALUE y;

        D3DVALUE dvY;

    };

    union {

        D3DVALUE z;

        D3DVALUE dvZ;

    };

    union {

        D3DVALUE nx;

        D3DVALUE dvNX;

    };

    union {

        D3DVALUE ny;

        D3DVALUE dvNY;

    };

    union {

        D3DVALUE nz;

        D3DVALUE dvNZ;

    };

    union {

        D3DVALUE tu;

        D3DVALUE dvTU;

    };

    union {

        D3DVALUE tv;

        D3DVALUE dvTV;

    };

} D3DVERTEX, *LPD3DVERTEX;

変換と投影をしない頂点を定義する(正規方向ベクトルでのモデル座標)。

関連情報については、D3DOPCODE列挙型の中のD3DOP_TRIANGLEメンバを参照すること。

dvX、 dvY、 dvZ

均質な座標で頂点を指定するD3DVALUE型の値。

dvNX、 dvNY、 および dvNZ

正規座標で頂点を指定するD3DVALUE 型の値。

dvTU ､ dvTV

頂点のテクスチャを指定するD3DVALUE型の値。

参照　D3DVALUE


D3DVIEWPORT

typedef struct _D3DVIEWPORT {

    DWORD    dwSize;

    DWORD    dwX;

    DWORD    dwY;

    DWORD    dwWidth;

    DWORD    dwHeight;

    D3DVALUE dvScaleX;

    D3DVALUE dvScaleY;

    D3DVALUE dvMaxX;

    D3DVALUE dvMaxY;

    D3DVALUE dvMinZ;

    D3DVALUE dvMaxZ;

} D3DVIEWPORT, *LPD3DVIEWPORT;

目に見える3Dボリュームと2Dスクリーン領域を定義する。3Dボリュームは、IDirect3DViewport::GetViewportとIDirect3DViewport::SetViewport メソッドで投射される。

ビューポートが変更されると、ドライバは新しい変換行列を構築する。

ビューポートの座標と配列は、デバイスの左上からの相対値である。

dwSize

この構造体のバイト単位のサイズ。

dwX ､ dwY

ビューポートの左上隅の座標。

dwWidth ､ dwHeight

ビューポートの配列。

dvScaleX ､ dvScaleY

スクリーンに均質なスケール比を指定するD3DVALUE型の値。

dvMaxX、 dvMaxY、 dvMinZ、 dvMaxZ

x、y、zの均質座標の最大値と最小値を指定するD3DVALUE型の値。

参照　D3DVALUE、 IDirect3DViewport::GetViewport、 IDirect3DViewport::SetViewport


列挙型


D3DBLEND

typedef enum _D3DBLEND {

    D3DBLEND_ZERO            = 1,

    D3DBLEND_ONE             = 2,

    D3DBLEND_SRCCOLOR        = 3,

    D3DBLEND_INVSRCCOLOR     = 4,

    D3DBLEND_SRCALPHA        = 5,

    D3DBLEND_INVSRCALPHA     = 6,

    D3DBLEND_DESTALPHA       = 7,

    D3DBLEND_INVDESTALPHA    = 8,

    D3DBLEND_DESTCOLOR       = 9,

    D3DBLEND_INVDESTCOLOR    = 10,

    D3DBLEND_SRCALPHASAT     = 11,

    D3DBLEND_BOTHSRCALPHA    = 12,

    D3DBLEND_BOTHINVSRCALPHA = 13,

} D3DBLEND;

D3DRENDERSTATETYPE列挙型の中のD3DRENDERSTATE_DESTBLEND値のためにサポートされたブレンディング・モードを定義する。次のメンバの中で、ソースとデスティネーションのRGBA値は、それぞれ記述子s､dで表される。

D3DBLEND_ZERO

ブレンディング係数は、(0, 0, 0, 0)。

D3DBLEND_ONE

ブレンディング係数は、(1, 1, 1, 1)。

D3DBLEND_SRCCOLOR

ブレンディング係数は、(Rs, Gs, Bs, As)。

D3DBLEND_INVSRCCOLOR

ブレンディング係数は、(As, As, As, As, 1-As)。

D3DBLEND_SRCALPHA

ブレンディング係数は、(As, As, As, As)。

D3DBLEND_INVSRCALPHA

ブレンディング係数は、(1-As, 1-As, 1-As)。

D3DBLEND_DESTALPHA

ブレンディング係数は、(Ad, Ad, Ad, Ad)。

D3DBLEND_INVDESTALPHA

ブレンディング係数は、(1-Ad, 1-Ad, 1-Ad, 1-Ad)。

D3DBLEND_DESTCOLOR

ブレンディング係数は、(Rd, Gd, Bd, Ad)。

D3DBLEND_INVDESTCOLOR

ブレンディング係数は、(1-Rd, 1-Gd, 1-Bd, 1-Ad)。

D3DBLEND_SRCALPHASAT

ブレンディング係数は、(f, f, f, 1)。f = min(As, 1-Ad)

D3DBLEND_BOTHSRCALPHA

ソースのブレンディング係数は、(As, As, As, As)。デスティネーションブレンディング係数は、(1-As, 1-As, 1-As, 1-As)。デスティネーションのブレンディング節は、無効となる。

D3DBLEND_BOTHINVSRCALPHA

ソースのブレンディング係数は、(1-As, 1-As, 1-As, 1-As) 。デスティネーションのブレンディング係数は、(As, As, As, As) 。デスティネーションのブレンディング節は、無効となる。


D3DCMPFUNC

typedef enum _D3DCMPFUNC {

    D3DCMP_NEVER        = 1,

    D3DCMP_LESS         = 2,

    D3DCMP_EQUAL        = 3,

    D3DCMP_LESSEQUAL    = 4,

    D3DCMP_GREATER      = 5,

    D3DCMP_NOTEQUAL     = 6,

    D3DCMP_GREATEREQUAL = 7,

    D3DCMP_ALWAYS       = 8,

} D3DCMPFUNC;

D3DRENDERSTATETYPE列挙型の中のD3DRENDERSTATE_ZFUNCとD3DRENDERSTATE_ALPHAFUNC 値のためにサポートされた比較関数を定義する。

D3DCMP_NEVER

つねにテストは失敗する。

D3DCMP_LESS

新しいピクセル値が、現在のピクセル値より小さいときに応じる。

D3DCMP_EQUAL

新しいピクセル値が、現在のピクセル値と等しいときに応じる。

D3DCMP_LESSEQUAL

新しいピクセル値が、現在のピクセル値以下のときに応じる。

D3DCMP_GREATER

新しいピクセル値が、現在のピクセル値より大きいときに応じる。

D3DCMP_NOTEQUAL

新しいピクセル値が、現在のピクセル値と等しくないときに応じる。

D3DCMP_GREATEREQUAL

新しいピクセル値が、現在のピクセル値以上のときに応じる。

D3DCMP_ALWAYS

つねにテストを実行する。


D3DCOLORMODEL

typedef enum _D3DCOLORMODEL {

    D3DCOLOR_MONO = 1,

    D3DCOLOR_RGB  = 2,

} D3DCOLORMODEL;

そのシステムのカラー・モデルを定義する。

D3DCOLOR_MONO

モノクロモデル(または、ランプモデル)を使用する。このモデルで、頂点色の青の値は、頂点の輝度を定義するために使用される。

D3DCOLOR_RGB

完全なRGBモデルを使用する。

参照　D3DDEVICEDESC、 D3DFINDDEVICESEARCH、 D3DLIGHTSTATETYPE、 IDirect3DRMDevice::GetColorModel


D3DCULL

typedef enum _D3DCULL {

    D3DCULL_NONE = 1,

    D3DCULL_CW   = 2,

    D3DCULL_CCW  = 3,

} D3DCULL;

サポートする切り抜きモードを定義する。ジオメトリにレンダリングするときの面の切り抜き方法を定義する。

D3DCULL_NONE

切り抜きはしない。

D3DCULL_CW

右回りに切り抜く。

D3DCULL_CCW

左回りに切り抜く。

参照　D3DPRIMCAPS、D3DRENDERSTATETYPE


D3DFILLMODE

typedef enum _D3DFILLMODE {

    D3DFILL_POINT     = 1,

    D3DFILL_WIREFRAME = 2,

    D3DFILL_SOLID     = 3

} D3DFILLMODE;

塗りつぶしモードを指定する定数を設定する。これらの値は、D3DRENDERSTATETYPE列挙型の中のD3DRENDERSTATE_FILLMODEレンダリング状態のために使用される。

D3DFILL_POINT

点で塗りつぶす。

D3DFILL_WIREFRAME

ワイヤーフレームで塗りつぶす。

D3DFILL_SOLID

面で塗りつぶす。


D3DFOGMODE

typedef enum _D3DFOGMODE {

    D3DFOG_NONE   = 0,

    D3DFOG_EXP    = 1,

    D3DFOG_EXP2   = 2,

    D3DFOG_LINEAR = 3

} D3DFOGMODE;

フォグ・モードを指定する定数を設定する。これらの値は、D3DRENDERSTATETYPE列挙型の中のD3DRENDERSTATE_FOGTABLEMODEレンダリング状態のために使用される。

D3DFOG_NONE

フォグ効果はない。

D3DFOG_EXP

次の方程式の対数で、フォグ効果が増す。

D3DFOG_EXP2

次の方程式の対数2乗で、フォグ効果が増す。

D3DFOG_LINEAR

次の方程式の始点と終点の間で線形に、フォグ効果が増す。

これは、現在サポートされている唯一のフォグ・モードである。

フォグは、透明度を表す基準である。この場合、フォグの値が小さいほど、オブジェクトが見えなくなる。


D3DLIGHTSTATETYPE

typedef enum _D3DLIGHTSTATETYPE {

    D3DLIGHTSTATE_MATERIAL   = 1,

    D3DLIGHTSTATE_AMBIENT    = 2,

    D3DLIGHTSTATE_COLORMODEL = 3,

    D3DLIGHTSTATE_FOGMODE    = 4,

    D3DLIGHTSTATE_FOGSTART   = 5,

    D3DLIGHTSTATE_FOGEND     = 6,

    D3DLIGHTSTATE_FOGDENSITY = 7,

} D3DLIGHTSTATETYPE;

D3DOP_STATELIGHTオペコード用の光源状態を定義する。これは、D3DSTATE 構造体の一部である型を列挙する。

D3DLIGHTSTATE_MATERIAL

最後の色とラスタ化の間の値の度合いを算出するため使用して、照明が当てられるマテリアルを定義する。デフォルト値はNULLである。

D3DLIGHTSTATE_AMBIENT

色と現在の光源の度合いを設定する。アプリケーションがこの値を指定したときは、パラメータとして光源を指定しない。デフォルト値は0である。

D3DLIGHTSTATE_COLORMODEL

D3DCOLORMODEL列挙型のメンバのひとつ。デフォルト値はD3DCOLOR_RGBである。

D3DLIGHTSTATE_FOGMODE

D3DFOGMODE列挙型のメンバのひとつ。デフォルト値はD3DFOG_NONEである。

D3DLIGHTSTATE_FOGSTART

フォグの開始値を定義する。デフォルト値は1.0である。

D3DLIGHTSTATE_FOGEND

フォグの終了値を定義する。デフォルト値は100.0である。

D3DLIGHTSTATE_FOGDENSITY

フォグに設定する深度を定義する。デフォルト値は1.0である。

参照　D3DOPCODE ､ D3DSTATE


D3DLIGHTTYPE

typedef enum _D3DLIGHTTYPE {

    D3DLIGHT_POINT         = 1,

    D3DLIGHT_SPOT          = 2,

    D3DLIGHT_DIRECTIONAL   = 3,

    D3DLIGHT_PARALLELPOINT = 4,

    D3DLIGHT_GLSPOT        = 5,

} D3DLIGHTTYPE;

光源型を定義する。この列挙型はD3DLIGHT 構造体の一部である。

D3DLIGHT_POINT

光源はポイントである。

D3DLIGHT_SPOT

光源はスポットライトである。

D3DLIGHT_DIRECTIONAL

光源は有向光である。

D3DLIGHT_PARALLELPOINT

光源はパラレル・ポイントである。

D3DLIGHT_GLSPOT

光源はGL型のスポットライトである。

参照　IDirect3DRMLightとIDirect3DRMLightArrayインターフェイス


D3DOPCODE

typedef enum _D3DOPCODE {

    D3DOP_POINT           = 1,

    D3DOP_LINE            = 2,

    D3DOP_TRIANGLE        = 3,

    D3DOP_MATRIXLOAD      = 4,

    D3DOP_MATRIXMULTIPLY  = 5,

    D3DOP_STATETRANSFORM  = 6,

    D3DOP_STATELIGHT      = 7,

    D3DOP_STATERENDER     = 8,

    D3DOP_PROCESSVERTICES = 9,

    D3DOP_TEXTURELOAD     = 10,

    D3DOP_EXIT            = 11,

    D3DOP_BRANCHFORWARD   = 12,

    D3DOP_SPAN            = 13,

    D3DOP_SETSTATUS       = 14,

} D3DOPCODE;

実行バッファのオペコードを含む。

D3DOP_POINT

レンダラーに点を送る。オペランド・データは、D3DPOINT構造体で指定される。

D3DOP_LINE

レンダラーに線を送る。オペランド・データは、D3DLINE構造体で指定される。

D3DOP_TRIANGLE

レンダラーに三角形を送る。オペランド・データはD3DTRIANGLE構造体で指定される。

D3DOP_MATRIXLOAD

レンダリング・エンジンにデータ転送するトリガーとなる。オペランド・データはD3DMATRIXLOAD構造体で指定される。

D3DOP_MATRIXMULTIPLY

レンダリング・エンジンにデータ転送するトリガーとなる。オペランド・データはD3DMATRIXMULTIPLY構造体で指定される。

D3DOP_STATETRANSFORM

変換モジュール用のレンダリング・エンジンに、内部状態変数の値を設定する。オペランド・データは、変数であるトークンと新しい値である。トークンは、内部状態変数を示す。この変数値には、新しい値が設定される。これらの変数についての詳細は、D3DSTATE構造体とD3DTRANSFORMSTATETYPE列挙型を参照すること。

D3DOP_STATELIGHT

光源モジュール用のレンダリング・エンジンに内部状態変数の値を設定する。オペランド・データは、変数であるトークンと新しい値である。トークンは、内部状態変数を示す。この変数値には、新しい値が設定される。これらの変数についての詳細は、D3DSTATE構造体とD3DLIGHTSTATETYPE列挙型を参照すること。

D3DOP_STATERENDER

レンダリングモジュール用のレンダリング・エンジンに内部状態変数の値を設定する。オペランド・データは、変数であるトークンと新しい値である。トークンは、内部状態変数を示す。この変数値には、新しい値が設定される。これらの変数についての詳細は、D3DSTATE構造体とD3DRENDERSTATETYPE列挙型を参照すること。

D3DOP_PROCESSVERTICES

頂点の光源と変換を設定する。オペランド・データは、D3DPROCESSVERTICES構造体で指定される。

D3DOP_TEXTURELOAD

レンダリング・エンジンにデータを転送するトリガーとなる。オペランド・データは、D3DTEXTURELOAD構造体で指定される。

D3DOP_EXIT

到達したリストの終了に到達した事を示す。

D3DOP_BRANCHFORWARD

実行バッファの分岐を可能とする。詳細は、D3DBRANCH構造体を参照すること。

D3DOP_SPAN

同じY値の点のリストからスパンを張る。詳細は、D3DSPAN構造体を参照すること。

D3DOP_SETSTATUS

実行バッファの状態をリセットする。詳細は、D3DSTATUS構造体を参照すること。

実行バッファはふたつの部分頂点配列(位置、法線ベクトル、テクスチャ座標)とオペコード/オペランドのグループの配列を持つ。ひとつのオペコードは、その後に続けていくつかのオペランドを持つことができる。システムは、各オペランドで関連するオペコードを簡単に実行する。

参照　D3DINSTRUCTION


D3DRENDERSTATETYPE

typedef enum _D3DRENDERSTATETYPE {

    D3DRENDERSTATE_TEXTUREHANDLE      = 1,

    D3DRENDERSTATE_ANTIALIAS          = 2,

    D3DRENDERSTATE_TEXTUREADDRESS     = 3,

    D3DRENDERSTATE_TEXTUREPERSPECTIVE = 4,

    D3DRENDERSTATE_WRAPU              = 5,

    D3DRENDERSTATE_WRAPV              = 6,

    D3DRENDERSTATE_ZENABLE            = 7,

    D3DRENDERSTATE_FILLMODE           = 8,

    D3DRENDERSTATE_SHADEMODE          = 9,

    D3DRENDERSTATE_LINEPATTERN        = 10,

    D3DRENDERSTATE_MONOENABLE         = 11,

    D3DRENDERSTATE_ROP2               = 12,

    D3DRENDERSTATE_PLANEMASK          = 13,

    D3DRENDERSTATE_ZWRITEENABLE       = 14,

    D3DRENDERSTATE_ALPHATESTENABLE    = 15,

    D3DRENDERSTATE_LASTPIXEL          = 16,

    D3DRENDERSTATE_TEXTUREMAG         = 17,

    D3DRENDERSTATE_TEXTUREMIN         = 18,

    D3DRENDERSTATE_SRCBLEND           = 19,

    D3DRENDERSTATE_DESTBLEND          = 20,

    D3DRENDERSTATE_TEXTUREMAPBLEND    = 21,

    D3DRENDERSTATE_CULLMODE           = 22,

    D3DRENDERSTATE_ZFUNC              = 23,

    D3DRENDERSTATE_ALPHAREF           = 24,

    D3DRENDERSTATE_ALPHAFUNC          = 25,

    D3DRENDERSTATE_DITHERENABLE       = 26,

    D3DRENDERSTATE_BLENDENABLE        = 27,

    D3DRENDERSTATE_FOGENABLE          = 28,

    D3DRENDERSTATE_SPECULARENABLE     = 29,

    D3DRENDERSTATE_ZVISIBLE           = 30,

    D3DRENDERSTATE_SUBPIXEL           = 31,

    D3DRENDERSTATE_SUBPIXELX          = 32,

    D3DRENDERSTATE_STIPPLEDALPHA      = 33,

    D3DRENDERSTATE_FOGCOLOR           = 34,

    D3DRENDERSTATE_FOGTABLEMODE       = 35,

    D3DRENDERSTATE_FOGTABLESTART      = 36,

    D3DRENDERSTATE_FOGTABLEEND        = 37,

    D3DRENDERSTATE_FOGTABLEDENSITY    = 38,

    D3DRENDERSTATE_STIPPLEENABLE      = 39,

    D3DRENDERSTATE_STIPPLEPATTERN00   = 64,

       // 点描パターンの01から30を省略

    D3DRENDERSTATE_STIPPLEPATTERN31   = 95,

} D3DRENDERSTATETYPE;

D3DOP_STATERENDERオペコード用のレンダリング状態を設定する。この列挙型は、D3DSTATE構造体の一部である。次の記述に記載された値は、この構造体の2番目のメンバに設定される。

D3DRENDERSTATE_TEXTUREHANDLE

テクスチャのハンドル。デフォルト値はNULLである。

D3DRENDERSTATE_ANTIALIAS

アンチエイリアシング要素の端。デフォルト値はFALSEである。

D3DRENDERSTATE_TEXTUREADDRESS

D3DTEXTUREADDRESS列挙型のメンバのひとつ。デフォルト値はD3DTADDRESS_WRAPである。

D3DRENDERSTATE_TEXTUREPERSPECTIVE

TRUEのとき、透視修正。デフォルト値はFALSEである。

D3DRENDERSTATE_WRAPU

TRUEのとき、u方向に張り付ける。デフォルト値はFALSEである。

D3DRENDERSTATE_WRAPV

TRUEのとき、v方向に張り付ける。デフォルト値はFALSEである。

D3DRENDERSTATE_ZENABLE

TRUEのとき、Zバッファの比較テストを可能にする。デフォルト値はFALSEである。

D3DRENDERSTATE_FILLMODE

D3DFILLMODE列挙型のメンバのひとつ。デフォルト値はD3DFILL_SOLIDである。

D3DRENDERSTATE_SHADEMODE

D3DSHADEMODE列挙型のメンバのひとつ。デフォルト値はD3DSHADE_GOURAUDである。

D3DRENDERSTATE_LINEPATTERN

D3DLINEPATTERN構造体である。デフォルト値はwRepeatPattern用に0で、wLinePattern用に0である。

D3DRENDERSTATE_MONOENABLE

TRUEのとき、モノクロ・レンダリングを可能とする。デフォルト値はFALSEである。デバイスがRGBレンダリングをサポートしていないとき、TRUEである。アプリケーションは、デバイスがRGBレンダリングをサポートしているかをD3DDEVICEDESC構造体のdcmColorModelメンバを使用して調べることができる

D3DRENDERSTATE_ROP2

TRUEのときモノクロ・レンダリングを可能とする。デフォルト値はFALSEである。デバイスがRGBレンダリングをサポートしていないとき、TRUEである。アプリケーションは、デバイスがRGBレンダリングをサポートしているかをD3DDEVICEDESC構造体のdcmColorModelメンバを使用して調べることができる。

与えられたピクセルを表示サーフェスのピクセルに書き込む方法を指定する、16 ROP2バイナリラスタ処理のひとつ。デフォルト値は、R2_COPYPENである。アプリケーションは、サポートされる追加ラスタ処理を決定するD3DPRIMCAPS構造体のdwRasterCapsメンバのD3DPRASTERCAPS_ROP2フラグが使用できる。

D3DRENDERSTATE_PLANEMASK

ULONG型の物理プレーンマスク。デフォルト値は、0である。

D3DRENDERSTATE_ZWRITEENABLE

TRUEのとき、Z書き込みを可能とする。デフォルト値は、TRUEである。このメンバは、アプリケーションにシステムが新しいZ値でZバッファを更新するのを防ぐ事を許可する。

D3DRENDERSTATE_ALPHATESTENABLE

アルファ・テストを可能とするためTRUE。デフォルト値は、FALSEである。このメンバは、アプリケーションにアルファ値の基準となるピクセルの受け取りや受け取り拒否の停止を許可する。

D3DRENDERSTATE_LASTPIXEL

TRUEのとき、線の最後のピクセルを描画するのを止める。デフォルト値は、TRUEである。

D3DRENDERSTATE_TEXTUREMAG

D3DTEXTUREFILTER列挙型のメンバのひとつ。デフォルト値は、D3DFILTER_NEARESTである。

D3DRENDERSTATE_TEXTUREMIN

D3DTEXTUREFILTER列挙型のメンバのひとつ。デフォルト値は、D3DFILTER_NEARESTである。

D3DRENDERSTATE_SRCBLEND

D3DBLEND列挙型のメンバのひとつ。デフォルト値はD3DBLEND_ONEである。

D3DRENDERSTATE_DESTBLEND

D3DBLEND列挙型のメンバのひとつ。デフォルト値はD3DBLEND_ZEROである。

D3DRENDERSTATE_TEXTUREMAPBLEND

D3DTEXTUREBLEND列挙型のメンバのひとつ。デフォルト値はD3DTBLEND_MODULATEである。

D3DRENDERSTATE_CULLMODE

D3DCULL列挙型のメンバのひとつ。デフォルト値はD3DCULL_CCWである。ソフトウェアのレンダリングは、固定の切り抜き順序を持ち、切り抜きモードの変更はサポートしない。

D3DRENDERSTATE_ZFUNC

D3DCMPFUNC列挙型のメンバのひとつ。デフォルト値はD3DCMP_LESSEQUALである。このメンバは、アプリケーションにカメラからの距離を基準とするピクセルの受け取りや受け取り拒否を許可する。

D3DRENDERSTATE_ALPHAREF

アルファ・テストが可能なとき、テストされるピクセルに対する参照アルファ値を指定する値。この値の型はD3DFIXEDである。デフォルト値は0である。

D3DRENDERSTATE_ALPHAFUNC

D3DCMPFUNC列挙型のメンバのひとつ。デフォルト値は、D3DCMP_ALWAYSである。このメンバは、アプリケーションにアルファ値を基準とするピクセルの受け取りや受け取り拒否を許可する。

D3DRENDERSTATE_DITHERENABLE

TRUEのときディザリングを可能とする。デフォルト値はFALSEである。

D3DRENDERSTATE_BLENDENABLE

TRUEのときアルファの混合を可能とする。デフォルト値はFALSEである。

D3DRENDERSTATE_FOGENABLE

TRUEのときフォグを可能とする。デフォルト値はFALSEである。

D3DRENDERSTATE_SPECULARENABLE

TRUEのとき透過を可能とする。デフォルト値はTRUEである。

D3DRENDERSTATE_ZVISIBLE

TRUEのときZ検査を可能とする。デフォルト値はFALSEである。Z検査とは、描画するポリゴンを見つけるためZバッファに対してテストされる、すべてのポリゴンのグループのスクリーン空間に描かれるポリゴンでの切り抜き技のことである。

D3DRENDERSTATE_SUBPIXEL

TRUEのときサブピクセルの訂正を可能とする。デフォルト値はFALSEである。

D3DRENDERSTATE_SUBPIXELX

TRUEのときXだけの訂正を可能とする。デフォルト値はFALSEである。

D3DRENDERSTATE_STIPPLEDALPHA

TRUEのとき点描されたアルファを可能とする。デフォルト値はFALSEである。

D3DRENDERSTATE_FOGCOLOR

D3DCOLOR型の値。デフォルト値は0である。

D3DRENDERSTATE_FOGTABLEMODE

D3DFOGMODE列挙型のメンバのひとつ。デフォルト値はD3DFOG_NONEである。

D3DRENDERSTATE_FOGTABLESTART

フォグ・テーブルの開始。これは線形フォグ・モードのため開始されたフォグ効果の位置である。

D3DRENDERSTATE_FOGTABLEEND

フォグ・テーブルの終了。これは、線形フォグ・モードの最大密度に到達したフォグ効果の位置である。

D3DRENDERSTATE_FOGTABLEDENSITY

線形フォグ・モードの最大フォグ密度を設定する。この値の範囲は、0から1である。

D3DRENDERSTATE_STIPPLEENABLE

デバイス・ドライバへの点描を可能とする。点描されたアルファが可能なとき、現在の点描パターンを無効としなければならない。

D3DRENDERSTATE_STIPPLEPATTERN00～D3DRENDERSTATE_STIPPLEPATTERN31

点描パターン。それぞれのレンダリング状態は、点描パターンの分離線に適応される。

参照　D3DOPCODE、 D3DSTATE


D3DSHADEMODE

typedef enum _D3DSHADEMODE {

    D3DSHADE_FLAT    = 1,

    D3DSHADE_GOURAUD = 2,

    D3DSHADE_PHONG   = 3,

} D3DSHADEMODE;

D3DRENDERSTATETYPE列挙型のD3DRENDERSTATE_SHADEMODEレンダリング状態用にサポートされるシェーディング・モードを指定する。

D3DSHADE_FLAT

平面シェーディング・モード。三角形の最初の頂点の色は、表面の色を決定するために使用される。

D3DSHADE_GOURAUD

グロー・シェーディング・モード。表面の色は、三角形の３つの頂点間で書き込まれた線形により決定される。

D3DSHADE_PHONG

フォン・シェーディング・モード。このモードは、現在サポートされていない。

参照　D3DRENDERSTATETYPE


D3DTEXTUREADDRESS

typedef enum _D3DTEXTUREADDRESS {

    D3DTADDRESS_WRAP   = 1,

    D3DTADDRESS_MIRROR = 2,

    D3DTADDRESS_CLAMP  = 3,

} D3DTEXTUREADDRESS;

D3DRENDERSTATETYPE列挙型のD3DRENDERSTATE_TEXTUREADDRESSレンダリング状態のためサポートされるテクスチャ・アドレスを指定する。

D3DTADDRESS_WRAP

D3DRENDERSTATETYPE列挙型の

D3DRENDERSTATE_WRAPUとD3DRENDERSTATE_WRAPVレンダリング状態が使用される。これが、デフォルトで設定される。

D3DTADDRESS_MIRROR

タイリング・テクスチャのアドレスと等しい。(D3DRENDERSTATE_WRAPUでもD3DRENDERSTATE_WRAPVでもないとき)それは、すべての整数接合フリッピングされたテクスチャを除く。たとえばテクスチャは、0と1の間のu値で、正規アドレスである。1と2の間では、フリップ(反転)される。また2と3の間では、再び正規に戻る。

D3DTADDRESS_CLAMP

テクスチャ座標が1.0より大きければ、1.0が設定される。0.0より小さければ、0.0が設定される。

D3DRENDERSTATE_WRAPUとD3DRENDERSTATE_WRAPVレンダリング状態を使用するための詳細は、「IDirect3DTextureインターフェイス」を参照すること。

参照　D3DRENDERSTATETYPE


D3DTEXTUREBLEND

typedef enum _D3DTEXTUREBLEND {

    D3DTBLEND_DECAL         = 1,

    D3DTBLEND_MODULATE      = 2,

    D3DTBLEND_DECALALPHA    = 3,

    D3DTBLEND_MODULATEALPHA = 4,

    D3DTBLEND_DECALMASK     = 5,

    D3DTBLEND_MODULATEMASK  = 6,

    D3DTBLEND_COPY          = 7,

} D3DTEXTUREBLEND;

サポートされるテクスチャ混合モードを定義する。この列挙型は、D3DRENDERSTATETYPE列挙型のD3DRENDERSTATE_TEXTUREMAPBLENDレンダリング状態により使用される。

D3DTBLEND_DECAL

デカール。テクスチャ混合モードがサポートされる。このモードでは、テクスチャのRGBとアルファ値は、テクスチャで使用されていない色を置換する。

D3DTBLEND_MODULATE

変調。テクスチャ混合モードがサポートされる。このモードでは、テクスチャのRGB値は、テクスチャで使用されていないRGB値を繰り返す。テクスチャのアルファ値は、テクスチャで使用されていない色のアルファ値を置換する。

D3DTBLEND_DECALALPHA

デカール・アルファ。テクスチャ混合モードがサポートされる。このモードでは、テクスチャのRGBとアルファ値は、次の方程式でテクスチャで使用されていない色で混合される。

この方程式で、Cは色、Aはアルファ、tはテクスチャ、oは元のオブジェクト(混合前の)を表す。

D3DTBLEND_DECALALPHAモードで、テクスチャのアルファ値は、テクスチャで使用されていない色のアルファ値を置換する。

D3DTBLEND_MODULATEALPHA

変調アルファのテクスチャ混合モードがサポートされる。このモードで、テクスチャのRGB値は、RGB値を増やし、テクスチャのアルファ値も増やす。

D3DTBLEND_DECALMASK

デカール・マスクのテクスチャ混合モードがサポートされる。

D3DTBLEND_MODULATEMASK

変調マスクのテクスチャ混合モードがサポートされる。

D3DTBLEND_COPY

複写テクスチャ混合モードがサポートされる。

変調は、光源とテクスチャの作用と相乗する。色は、0以上1以下の値で指定される。そして、テクスチャやソースより輝度の低い色に合わせて、一緒に生成された個々の色を変調する。その成分のソースのひとつが白(1)のとき、輝度の低い色成分は減少しない。同様に、オブジェクトに対応するテクスチャが、白(1、1、1)のとき、テクスチャの色は、維持され、変更されない。


D3DTEXTUREFILTER

typedef enum _D3DTEXTUREFILTER {

    D3DFILTER_NEAREST          = 1,

    D3DFILTER_LINEAR           = 2,

    D3DFILTER_MIPNEAREST       = 3,

    D3DFILTER_MIPLINEAR        = 4,

    D3DFILTER_LINEARMIPNEAREST = 5,

    D3DFILTER_LINEARMIPLINEAR  = 6,

} D3DTEXTUREFILTER;

D3DRENDERSTATETYPE列挙型のD3DRENDERSTATE_TEXTUREMAGレンダリング状態を使用する、サポートされたテクスチャ・フィルタ・モードを定義する。

D3DFILTER_NEAREST

要求されたピクセル値に最も近い座標のテクセルが使用される。これは、拡大と縮小の両方で用いられる。拡大か縮小がサポートされているときは、両方がサポートされていなければならない。

D3DFILTER_LINEAR

2×2の領域の重さの平均。テクセル環境の要求されたピクセルが使用される。これは拡大と縮小の両方で用いられる。拡大か縮小がサポートされているときは、両方がサポートされていなければならない。

D3DFILTER_MIPNEAREST

D3DFILTER_NEARESTと同様だが、選択テクセル固有のミップマップを使用する。

D3DFILTER_MIPLINEAR

D3DFILTER_LINEARと同様だが、選択テクセル固有のミップマップを使用する。

D3DFILTER_LINEARMIPNEAREST

D3DFILTER_MIPNEARESTと同様だが、ふたつの近似ミップマップで作り替える。

D3DFILTER_LINEARMIPLINEAR

D3DFILTER_MIPLINEARと同様だが、ふたつの近似ミップマップで作り替える。


D3DTRANSFORMSTATETYPE

typedef enum _D3DTRANSFORMSTATETYPE {

    D3DTRANSFORMSTATE_WORLD      = 1,

    D3DTRANSFORMSTATE_VIEW       = 2,

    D3DTRANSFORMSTATE_PROJECTION = 3,

} D3DTRANSFORMSTATETYPE;

D3DOPCODE列挙型のD3DOP_STATETRANSFORMオペコード用に変換状態を指定する。この列挙型は、D3DSTATE構造体の一部である。

D3DTRANSFORMSTATE_WORLD

D3DTRANSFORMSTATE_VIEW

D3DTRANSFORMSTATE_PROJECTION

変換するワールド、ビュー、投影の配列を定義する。デフォルト値は、NULLである(同一の配列)。

参照　D3DOPCODE、 D3DRENDERSTATETYPE


その他の型


D3DCOLOR

typedef DWORD D3DCOLOR, D3DCOLOR, *LPD3DCOLOR;

この型は、基本的な Direct3Dの色型である。

参照　D3DRGB、 D3DRGBA


D3DVALUE

typedef float D3DVALUE, *LPD3DVALUE;

この型は、基本的なDirect3Dの分数データ型である。


返値

エラーは負数値で表され、組み合わされることはない。次に、すべてのDirect3Dメソッドにより返される値の一覧を示す。個々のメソッドの返値については、各メソッドの記述を参照すること。

D3D_OK

D3DERR_BADMAJORVERSION

D3DERR_BADMINORVERSION

D3DERR_EXECUTE_CLIPPED_FAILED

D3DERR_EXECUTE_CREATE_FAILED

D3DERR_EXECUTE_DESTROY_FAILED

D3DERR_EXECUTE_FAILED

D3DERR_EXECUTE_LOCK_FAILED

D3DERR_EXECUTE_LOCKED

D3DERR_EXECUTE_NOT_LOCKED

D3DERR_EXECUTE_UNLOCK_FAILED

D3DERR_LIGHT_SET_FAILED

D3DERR_MATERIAL_CREATE_FAILED

D3DERR_MATERIAL_DESTROY_FAILED

D3DERR_MATERIAL_GETDATA_FAILED

D3DERR_MATERIAL_SETDATA_FAILED

D3DERR_MATRIX_CREATE_FAILED

D3DERR_MATRIX_DESTROY_FAILED

D3DERR_MATRIX_GETDATA_FAILED

D3DERR_MATRIX_SETDATA_FAILED

D3DERR_SCENE_BEGIN_FAILED

D3DERR_SCENE_END_FAILED

D3DERR_SCENE_IN_SCENE

D3DERR_SCENE_NOT_IN_SCENE

D3DERR_SETVIEWPORTDATA_FAILED

D3DERR_TEXTURE_CREATE_FAILED

D3DERR_TEXTURE_DESTROY_FAILED

D3DERR_TEXTURE_GETSURF_FAILED

D3DERR_TEXTURE_LOAD_FAILED

D3DERR_TEXTURE_LOCK_FAILED

D3DERR_TEXTURE_LOCKED

D3DERR_TEXTURE_NO_SUPPORT

D3DERR_TEXTURE_NOT_LOCKED

D3DERR_TEXTURE_SWAP_FAILED

D3DERR_TEXTURE_UNLOCK_FAILED


DirectX 3 に関する新しい情報

現在のMicrosoftｮ DirectInput� は、ジョイスティックばかりでなくマウスおよびキーボード入力デバイスもサポートしている。マウスおよびキーボードに対するAPIは、COMのオブジェクトおよびインターフェースを用いる。 DirectInputは、マウスおよびキーボード・データに対して標準Win32 APIよりも高速にアクセスできる。

Windows 95に組み込まれたDirectInput 1.0によって、デジタル・ジョイスティック・デバイスへのアクセスが可能になった。これはjoyGetPosExなどのいくつかのAPI、キャリブレーション用アプレット(joy.cpl)、およびデジタル・ジョイスティック・デバイスのサポートを可能としたVJOYD.VXDを基本とするドライバ・モデルから構成されている。

バージョン 1.0のリリース以来、DirectX SDKに関して最も改良の要求が多かった点のひとつは、マウスおよびキーボード・データへのアクセスをこれまでのWindowsよりもさらに高速化するということであった。それが本バージョンのDirectInputが目標としたことである。DiectInput 3.0により、マウスおよびキーボード・データに対してさらに高速なアクセスが可能になる。DirectInput 1.0 とは異なり、DirectInput 3.0 のマウスおよびキーボードに対するAPIは、COMオブジェクトおよびインターフェイスを使用している。

DirectInputの将来のバージョンでは、ジョイスティック・デバイスに対してCOMが付加されることになる。フォース フィードバックをサポートするジョイスティック・デバイスに対しては、 DirectInputでもそのサポートが付加される。汎用入力デバイス(特定のDirectInputインターフェイスにより直接サポートされていないデバイス)をサポートする機能も付加される。


DirectInput概要

Windows DirectX SDK により、高度なコンピュータゲームを作成することができる。DirectInputは、入力デバイス・データへの高速で便利なアクセスを可能とするDirectX SDKコンポーネントである。

本章の目的は、バージョン3.0のDirectInput アプリケーション・プログラミング・インターフェイスおよびCOMインターフェイスについて説明することである。ここではマウスおよびキーボード入力のサポートに必要なAPIとCOMインターフェイスについてのみ説明し、DirectInput 1.0については触れない。


DirectInput によるジョイスティクのサポート
DirectInputによるジョイスティックのサポート

DirectInput APIは、アナログおよびデジタル・ジョイスティックに対して高速かつ整合性のあるアクセスを提供する。このAPIは、 Microsoft Win32ｮ ソフトウェア開発キット (SDK)のジョイスティックAPIとの整合性を維持しているが、デバイス・ドライバ・モデルの変更により応答性および信頼性が改善されている。DirectInputデバイス・ドライバは、標準およびOEM供給のジョイスティックの設定や以前設定されたジョイスティックのキャリブレーション情報をレジストリに格納する。

本節では、ジョイスティックをサポートするDirectInput関数とメッセージおよび構造体について説明し、 Win32ジョイスティックAPIからの変更点を明らかにする。DirectInput APIは、タッチスクリーンやタブレット、ライトペンといった絶対座標系内で位置を追跡する他の補助入力デバイスにも適用される。機能拡張により、ラダー・ペダル、フライト・ヨーク、バーチャル・リアリティ・ヘッドギアなど他のデバイスに対するサポートも提供される。各デバイスは最大6本の運動軸、視点ハットおよび32個のボタンを用いることができる。

DirectInput関数を用いて、ジョイスティックおよびジョイスティック・ドライバの能力を活かしたアプリケーションをデザインすることができる。また、位置およびボタン情報をジョイスティックから取得することができる。

この節ではDirectInputコンポーネントが提供するジョイスティック・サポートについての情報を扱う。

ジョイスティックの機能

ジョイスティックのキャリブレーションおよびテスト

ジョイスティックの位置


ジョイスティックの機能

DirectInputサービスは、オペレーティング・システム起動時にロードされる。DirectInputはアナログおよびデジタルのジョイスティックをサポートする。アナログ・ジョイスティックは、よりリアルタイムな応答を必要とし、デジタル・ジョイスティックよりも大きな負荷をシステムに与える。DirectInputサービスは、異なる構成のアナログ・ジョイスティックを複数同時にモニタすることができる。その構成は、最大4本の運動軸を追跡し最大4つのボタンを用いるアナログ・ジョイスティック2基から、2本の運動軸を追跡し最大4つのボタンを用いるアナログ・ジョイスティック4基までの範囲に渡る。またデジタル・ジョイスティックについては同時に最大16基モニタできる。1基あたり、運動軸は最大6本、ボタンは最大32個までである。

ジョイスティックが追跡する各運動軸には作動範囲がある。作動範囲とは、ジョイスティックのハンドルをニュートラルまたは静止状態の位置から動かせる一番離れた点までの距離である。

ジョイスティック・ドライバは最大16のミニドライバをサポートし、各ミニドライバはひとつのジョイスティックをサポートする。joyGetNumDevs関数を用いることにより、ジョイスティック・ドライバがサポートするジョイスティック数を調べることができる。この関数はドライバがサポート可能なジョイスティック数を指定する符号なし整数を返す。ジョイスティックがサポートされていない場合は0を返す。

アプリケーションは、joyGetPosEx関数を用いることにより、コンピュータにジョイスティックが接続されているかどうか調べることができる。この関数は、指定されたデバイスが接続されていればJOYERR_NOERROR、そうでなければJOYERR_UNPLUGGEDを返す。

各ジョイスティックには、アプリケーションから利用可能な機能がいくつか存在する。その機能は、joyGetDevCaps関数を用いて調べることができる。この関数は、ジョイスティックの有効な運動軸や座標系の最小値および最大値、ジョイスティック上のボタン数といったジョイスティックの機能をJOYCAPS構造体に代入する。

注意

joyGetNumDevsの返値は、システムに接続されたジョイスティック数ではなく、システムがサポートするジョイスティック数を示す。


ジョイスティックのキャリブレーションおよびテスト

作動範囲やボタンなど、ジョイスティックのキャリブレーションおよびテストをするために、Microsoft Windowsｮ 95のコントロールパネルにはジョイスティック・アプリケーションがある。ユーザは、このアプリケーションから以下のジョイスティックを選択できる。

一般的なジョイスティック

OEMジョイスティック

カスタム・ジョイスティック

このアプリケーションにより、各ジョイスティックに対して、最大6本の運動軸、32のボタンおよび視点ハットのキャリブレーションが可能となる。キャリブレーション情報はレジストリに格納されるので、再キャリブレーションすることなくジョイスティックを別のものに取り替えることができる。ユーザが新たなジョイスティックをキャリブレーションしたりリストから選択したりすると、キャリブレーション用アプリケーションは選択されたジョイスティックおよびキャリブレーション情報についてレジストリを更新し、それをジョイスティック・ドライバに通知する。

さらにこのアプリケーションは、joyConfigChanged関数を用いることにより、特定のジョイスティックに対し、影響のあるレジストリ変更情報を通知することができる。


ジョイスティックの位置

joyGetPosEx関数を用いることにより、位置およびボタン情報をジョイスティックから取得することができる。この関数は、位置のx、y、z座標を含めてWin32 APIの旧ジョイスティック関数から返される位置情報を取得することができる。最大4つのボタンに対する状態情報を取得することも可能である。またjoyGetPosEx関数により、以下の情報へアクセスできる。

4、5、6番目の軸（r、uおよびv）の状態

ラダー情報

視点ハット

最大32個のボタンの状態情報

キャリブレーションされていない(得られたままの)ジョイスティックのデータ

定義されている値の範囲で評価されたデータ

中心にある評価データ

ジョイスティックのニュートラル位置周囲のデッドゾーンを含めた評価データ


DirectInputによるキーボードおよびマウスのサポート

この節ではDirectInputコンポーネントが提供するキーボードおよびマウスのサポートについて説明する。

DirectInput オブジェクト

DirectInputDeviceオブジェクト

マウス・デバイスからのデータ取得

キーボード・デバイスからのデータ取得

キーボード・スキャンコード

日本語キーボード


DirectInput オブジェクト

DirectInputオブジェクトはDirectInputサブシステムを表す。アプリケーションはDirectInputCreate APIを呼び出してDirectInputオブジェクトを作成する。 DirectInputCreate APIは、IDirectInputインターフェイスを返す。

IDirectInputインターフェイスへのポインタが得られると、DirectInputが動作可能な入力デバイスを列挙することができる。入力デバイスはIDirectInput::EnumDevicesメソッドにより列挙される。


DirectInputDevice オブジェクト

DirectInputDeviceオブジェクトは、マウスやキーボードその他の入力デバイスを表す。アプリケーションはIDirectInput::CreateDeviceメソッドを呼び出してDirectInputDeviceオブジェクトを作成する。 IDirectInput::CreateDeviceメソッドは、IDirectInputDeviceインターフェイスを返す。

IDirectInput::CreateDeviceの第一のパラメータはインスタンスGUIDで、これはインターフェイスが作成されるデバイスのインスタンスを識別する。DirectInputにはあらかじめ定義されているふたつのインスタンスGUIDがある。GUID_SysMouseおよびGUID_SysKeyboardであり、それぞれユーザの主マウス、主キーボードを表す。


マウス・デバイスからのデータの取得
マウス・デバイスからのデータ取得

マウス・デバイスからのデータを取得するには、c_dfDIMouseデータ・フォーマットでIDirectInputDevice::SetDataFormatを呼び出す。マウス・デバイスから返されるデータは、スクリーン座標ではなくマウスが移動したユニット数を基にしている。これらのマウス・ユニットはマウス・ハードウェア(ミッキーとも呼ばれる)から返される実際の値を基にしている。DirectInputはそのデータを修正、加工することはない。マウス・データをそのまま返すだけである。

マウスから返されるデータは相対データ、絶対データのいずれでもよい。マウスは相対的なデバイスなので、デフォルトでは相対データが返される。マウス・デバイスの軸モードは、返されるデータが相対であるか絶対であるかを指定する。これはIDirectInputDevice::SetPropertyメソッドを介して変更可能なデバイス・プロパティである。軸モードを絶対にセットするには、REFGUIDパラメータをDIPROP_AXISMODEにしてIDirectInputDevice::SetPropertyを呼び出す。そして、 DIPROPDWORD構造体のdwDataフィールドをDIPROPAXISMODE_ABSにセットする。

マウス・デバイスに対する軸モードが相対にセットされているとき、軸座標は特定の軸にそってデバイスが移動したマウスユニット数を表す。負の値は、マウスがx軸にそって左方へ、y軸にそって上方へ、あるいはz軸にそって後方へ移動したことを示す。正の値は、マウスがx軸にそって右方へ、y軸にそって下方へ、あるいはz軸にそって前方へ移動したことを示す。

注意すべきなのは、マウスには絶対位置という考え方が存在しないという点である。その結果、絶対座標はDirectInputから得られたすべての相対移動を単に合計したものとなる。これは絶対座標の数値には意味がないことを示しており、マウス・ポインタのスクリーン座標とは無関係である。アプリケーションは、絶対座標を未知の原点に対する相対座標であるとして扱う。 たとえば、アプリケーションはデバイスの認識直後にそのときの絶対位置を記録し、それを「仮想原点」として保持することができる。そして以降はそこからマウスが移動した相対距離を計算するために、IDirectInputDevice::GetDeviceStateあるいはIDirectInputDevice::GetDeviceDataを介してデバイスから取得される絶対座標から仮想原点との差をとる(これを次のIDirectInputDevice::Unacquireまで続ける)。純粋な相対デバイス(マウスなど)における絶対座標は、以前に記録された位置との比較を行うときにだけ意味がある。

マウスの現在の状態を取得するためには、ポインタをDIMOUSESTATE構造体へセットしてIDirectInputDevice::GetDeviceStateを呼び出す。マウスの状態にはマウスの位置や各ボタンの状態といった情報がある。

マウスからバッファ・データを取得するには、DIDEVICEOBJECTDATA構造体の配列を作成し、ポインタおよび配列のサイズを含む変数をIDirectInputDevice::GetDeviceDataへ渡さなければならない。入力待ち行列にデータがなくなるかあるいは配列が埋まってしまうまで、DirectInputは最も古いマウス・データから配列に入れていく。 IDirectInputDevice::GetDeviceDataから返されるサイズ変数は実際に使用されている配列要素数である。マウスからバッファ・データを取得する際、単一のDIDEVICEOBJECTDATA構造体に与えられるデータはマウス上の単一オブジェクトの状態に関する変更点である。たとえば、典型的なマウスには4つのオブジェクト、すなわち入力ソースが存在する。x軸、y軸、ボタン0、ボタン1である。ユーザがボタン0を押しマウスを斜め方向に移動すると、 IDirectInputDevice::GetDeviceDataに渡されるDIDEVICEOBJECTDATA構造体の配列には3つの要素が代入されている。ボタン0が押されたことを示す要素、x軸方向の変化があったことを示す要素、およびy軸方向の変化があったことを示す要素である。 IDirectInputDevice::GetDeviceDataの呼び出しの後、アプリケーションは、あらかじめ定義されている定数とDIDEVICEOBJECTDATA構造体のdwOfsフィールドとを比較することにより､配列中の要素がどのオブジェクトを参照しているかを知ることができる。比較に用いる定数は、DIMOFS_BUTTON0、 DIMOFS_BUTTON1、DIMOFS_BUTTON2、 DIMOFS_BUTTON3、DIMOFS_X、DIMOFS_Y、およびDIMOFS_Zである。これらの定数は、 DIMOUSESTATE構造体での値のオフセットを参照する。これらの定数を用いて、DIDEVICEOBJECTDATA構造体のデータがマウス上のどのオブジェクトを参照しているかを正確に知ることができる。そのオブジェクトに対する実データは構造体のdwDataフィールドに存在する。ボタン・オブジェクトについてはdwDataの下位バイトだけが有意である。このバイトの上位ビットは、そのボタンが押されるとセットされ、離されるとクリアされる。

Scrawlサンプル・アプリケーションは、バッファ・データを収集しIDirectInputDevice::GetDeviceDataから取得した情報を処理する方法のひとつを示したものである｡

データがIDirectInputDevice::GetDeviceDataから取得されている場合のみ、時刻付きのマウス・データが利用可能となる。

アプリケーションは、デバイスを認識してデータを取得する前に、マウス・デバイスの協調レベルをセットしなければならない｡そのためには、必要な協調レベルを示すフラグをセットしてIDirectInputDevice::SetCooperativeLevelを呼び出す。Windows 95環境下では、マウス・デバイスに対して以下の協調レベルがサポートされている。DISCL_BACKGROUND | DISCL_NONEXCLUSIVE、DISCL_FOREGROUND | DISCL_NONEXCLUSIVE、およびDISCL_FOREGROUND | DISCL_EXCLUSIVEである。DirectInput 3.0ではDISCL_BACKGROUND | DISCL_EXCLUSIVE協調レベルはマウス・デバイスに対してサポートされていない。各協調レベルの意味に関する詳細な情報については、これらの協調型定数についての記述を参照すること。

DirectXの将来バージョンでは、Windows NT上でDirectInputがサポートされるようになる。だが、Windows NTではマウス・デバイスに対してDISCL_FOREGROUND | DISCL_EXCLUSIVEしかサポートされない。マウス・ドライバのサポートレベルによっては、Windows 95上のDirectInputでもDISCL_FOREGROUND | DISCL_EXCLUSIVEだけのサポートに限定される可能性がある。したがって、あるだけすべてのプラットフォームおよびマウス・ドライバ上でアプリケーションを実行する必要がある場合にはこの協調レベルを用いるべきであり、またWindows NT対応のDINPUT.DLLプレリリース・バージョン(DirectX 3.0 SDKのExtrasディレクトリにある)を用いたテストが必要である。Windows NTバージョンのDirectInput(およびマウス・ドライバがサポートされていないWindows 95バージョンのDirectInput)はWindows 95バージョンよりも頻繁にDIERR_INPUTLOSTを通知するので、これらのケースを処置するようにアプリケーションを書かなければならない。

IDirectInputDevice::GetDeviceDataまたはIDirectInputDevice::GetDeviceStateによりマウス・デバイスからデータを取得する前に、IDirectInputDevice::Acquireを呼び出してデバイスを認識しておかなければならない。アプリケーションが中断されたり入力フォーカスを失ったりするときには、IDirectInputDevice::Unacquireを呼び出してアプリケーションからマウス・デバイスを解放することが推奨される。アプリケーション・メニューあるいはシステム・メニューが選択されるか、またはウィンドウがリサイズあるいは移動される場合も、デバイスを解放しなければならない。アプリケーションの中断が解除されたりアプリケーションが入力フォーカスを再度獲得したりするときには、アプリケーションはIDirectInputDevice::Acquireを呼び出してマウス・デバイスを認識し直す必要がある。

アプリケーションがDISCL_FOREGROUNDモードでマウスを使用している場合、IDirectInputDevice::GetDeviceDataまたは IDirectInputDevice::GetDeviceStateからのDIERR_INPUTLOST返値をチェックすることが推奨される。アプリケーションがフォーカスを失う際、DirectInputは自動的にマウスを解放するため、DIERR_INPUTLOST返値を受け取った場合アプリケーションはマウス・デバイスの認識を再度行うべきである。しかし、どのようなタイプのエラーが発生した際でも無条件にDirectInputデバイスを認識し直させるようなアプリケーションを書いてはならない。認識できないデバイスを認識しようとして無限ループに陥る可能性があるからである。

アプリケーションがDISCL_NONEXCLUSIVEモードでマウスにアクセスしている場合、マウス・データはDirectInput経由とWindowsマウス・メッセージ経由の両方から取得される。アプリケーションがDISCL_EXCLUSIVEモードでマウスにアクセスしている場合、マウス・データはDirectInputを介してのみ取得可能となる。Windowsマウス・メッセージには使用できるデータが含まれない。

Scrawlサンプルアプリケーションは、マウス・デバイスを認識および解放する適切な方法の例である。


キーボード・デバイスからのデータ取得

キーボード・デバイスからデータを取得するには、 IDirectInputDevice::SetDataFormatをc_dfDIKeyboardデータ・フォーマットで呼び出さなければならない。DirectInputは、インターナショナル・キーボード上に存在する追加キーばかりでなく拡張キーボード上の各キーに対しても定数を定義している。ほとんどの場合、これらの定数は実際にはPC拡張スキャンコードである。これらのキー定数はDIK_で始まり、dinput.hで定義されている。NECキーボードはPC拡張キーボードとは異なるスキャンコードをサポートしているので、DirectInputはNECキースキャンコードを可能なかぎりPC拡張スキャンコードに変換している。より詳細な情報については、キーボード・スキャンコード.を参照のこと。

キーボードの現在の状態を取得するためには、256バイトの構造体を宣言し、そのポインタをIDirectInputDevice::GetDeviceState メソッドへ渡さなければならない。 IDirectInputDevice::GetDeviceStateメソッドはWindowsのGetKeyboardState関数と同様の機能を果たす。デバイスの状態はこの256バイトの配列に格納され、各バイトはひとつのキーの状態に対応する。たとえば、DIK_ENTER番目のバイトの上位ビットがセットされている場合、Enterキーが押されている。しかしGetKeyboardStateとは異なり、DirectInputはバイトの上位ビットしか使用しない。上位ビットがセットされている場合、そのキーが押されていることを示す。そうでなければ、キーは押されていない。

キーボードからバッファ・データを取得するには、DIDEVICEOBJECTDATA構造体の配列を作成し、ポインタおよびこの配列のサイズを含む変数をIDirectInputDevice::GetDeviceDataに渡さなければならない。入力待ち行列にデータがなくなるかあるいは配列が埋まってしまうまで、DirectInputは最も古いキーボード・データから配列に入れていく。 IDirectInputDevice::GetDeviceDataから返されるサイズ変数は実際に使用されている配列要素数である。キーボードからバッファ・データを取得する際、単一のDIDEVICEOBJECTDATA構造体に与えられるデータはキーボード上の単一オブジェクトの状態に関する変更点である。キーボード上の各キーまたはボタンはオブジェクトを表す。ユーザが ﾒA�キーを押して離し、続いてﾒR�キーを押すと、 IDirectInputDevice::GetDeviceDataへ渡されたDIDEVICEOBJECTDATA構造体の配列には3つの要素が代入される。�A�キーが押されたことを示す要素、 ﾒA�キーが離されたことを示す要素、および ﾒR�キーが押されたことを示す要素である。 IDirectInputDevice::GetDeviceDataの呼び出しの後、アプリケーションは、あらかじめ定義されているDIK_*定数とDIDEVICEOBJECTDATA構造体のdwOfsフィールドを比較して、配列中の要素がどのオブジェクト(またはキー)を参照しているかを知ることができる。またDIK_*定数を用いて、DIDEVICEOBJECTDATA構造体のデータがキーボード上のどのオブジェクトを参照しているかを正確に知ることができる。オブジェクトの実データは構造体のdwDataフィールドに存在する。キーボード上のキーのようなボタンオブジェクトについてはdwDataの下位バイトだけが有意である。このバイトの上位ビットは、キーが押されるとセットされ、キーが離されるとクリアされる。

データがIDirectInputDevice::GetDeviceData.により取得されている場合のみ、時刻付きのキーボード・データが利用可能となる。

アプリケーションは、デバイスを認識してデータを取得する前に、キーボード・デバイスの協調レベルをセットしなければならない｡ そのためには、必要な協調レベルを示すフラグをセットしてIDirectInputDevice::SetCooperativeLevelを呼び出す。Windows 95環境下では、キーボード・デバイスに対して以下の協調レベルがサポートされている。 DISCL_BACKGROUND | DISCL_NONEXCLUSIVE、DISCL_FOREGROUND | DISCL_NONEXCLUSIVEである。DirectInput 3.0ではDISCL_BACKGROUND | DISCL_EXCLUSIVE、DISCL_FOREGROUND | DISCL_EXCLUSIVE協調レベルはキーボード・デバイスに対してサポートされていない。これは、キーボード・データがつねにDirectInputとWindowsメッセージとを通して受信されることを意味する。各協調レベルの意味に関する詳細な情報については、これらの協調型定数についての記述を参照すること。

DirectXの将来バージョンでは、Windows NT上でDirectInputがサポートされるようになる。だが、Windows NTではキーボード・デバイスに対してDISCL_FOREGROUND | DISCL_NONEXCLUSIVEしかサポートされない。アプリケーションをWindows NTで実行する必要がある場合、キーボードへのアクセスにはこの協調レベルを使うことになる。キーボードドライバのサポートレベルによっては、Windows 95上のDirectInputでもDISCL_FOREGROUND | DISCL_NONEXCLUSIVEだけのサポートに限定される可能性がある。したがって、あるだけすべてのプラットフォームおよびキーボードドライバ上でアプリケーションを実行する必要がある場合、この協調レベルを用いるべきである。

IDirectInputDevice::GetDeviceDataまたはIDirectInputDevice::GetDeviceState,によりキーボード・デバイスからデータを取得する前に、IDirectInputDevice::Acquireを呼び出してデバイスを認識しておかなければならない。アプリケーションが中断されたり入力フォーカスを失ったりするときには、IDirectInputDevice::Unacquireを呼び出してアプリケーションからキーボード・デバイスを解放することが推奨される。アプリケーション・メニューあるいはシステム・メニューが選択されるか、またはウィンドウがリサイズあるいは移動される場合も、デバイスを解放しなければならない。アプリケーションの中断が解除されたりアプリケーションが入力フォーカスを再度獲得したりするときには、アプリケーションはIDirectInputDevice::Acquireを呼び出してキーボード・デバイスを認識し直す必要がある。

アプリケーションがDISCL_FOREGROUNDモードでキーボードを使用している場合、IDirectInputDevice::GetDeviceDataまたは IDirectInputDevice::GetDeviceState.からのDIERR_INPUTLOST返値をチェックすることが推奨される。アプリケーションがフォーカスを失う際、DirectInputは自動的にキーボードを解放するため、DIERR_INPUTLOST返値を受け取った場合アプリケーションはキーボード・デバイスの認識を再度行うべきである。しかし、どのようなタイプのエラーが発生した際でも無条件にDirectInputデバイスを認識し直させるようなアプリケーションを書いてはならない。認識できないデバイスを認識しようとして無限ループに陥る可能性があるからである。


キーボード・スキャンコード

キーボードには、アプリケーション側で注意しておかなければならない点がいくつかある。物理的なキーボード・レイアウトに合わせてユーザがキーの割り当てを再設定できるようなアプリケーションを作成することが推奨されるのである。

このことを説明するため、キーボードの基本レイアウトをUS PC拡張キーボードとする。あるキーが存在しないというときは、そのキーはUS PC拡張キーボードには存在するが説明しているキーボードには存在しないことを意味する。あるキーが追加されたと示されるとき、そのキーはUS PC拡張キーボードには存在しないが説明しているキーボードには存在することを意味する。

すべてのPC拡張キーボードが新たなWindowsキー(DIK_LWIN、DIK_RWIN、およびDIK_APPS）をサポートしているわけではない。これらのキーが物理的に利用可能かどうかを知る方法はない。

DIK_PAUSEキーコードは存在しないということに注意を要する。PC拡張キーボードはDIK_PAUSEというスキャンコードを生成するのではなく、DIK_LCONTROLおよびDIK_NUMLOCKスキャンコードの組み合わせでﾒPause�を生成している。

ラップトップあるいはその他の小型コンピュータは、フルセットのキーボードを実装していないことがよくある。かわりにいくつかのキー（典型的にはテンキー）は他のキーと共通になっており、補助的なモード・キーにより選択される。このモード・キー自体はスキャンコードを生成しない。

キーボードのサブタイプがPC XTあるいはPC ATキーボードの場合、次のキーは利用できない。DIK_F11、DIK_F12およびすべての拡張キー(DIK_*値が0x80以上)。その上、PC XTキーボードにはDIK_SYSRQが存在しない。

日本語キーボード、特にNEC PC-98キーボードには、USキーボードとは実質的に異なるキーセットが含まれる。詳細については日本語キーボードを参照すること。


日本語キーボード

日本語キーボードとUSキーボードとの間には実質的な相違が存在する。以下の表では、各タイプの日本語キーボードで利用可能な付加キーをリストアップしている。またUSキーボードで利用可能ではあるがいくつかの日本語キーボードには存在しないキーもリストアップする。

また、NEC PC-98キーボードではDIK_CAPSLOCKおよびDIK_KANAキーがプッシュ・ボタンではなくトグル・ボタンになっているものがあることに注意すること。これらは、最初に押されると押されたというイベントを生成し、次に押されると離されたというイベントを生成する。

キーボード	付加キー	存在しないキー
DOS/V 106キーボード,  NEC PC-98 106キーボード	DIK_AT DIK_CIRCUMFLEX DIK_COLON DIK_CONVERT DIK_KANA DIK_KANJI DIK_NOCONVERT DIK_YEN	DIK_APOSTROPHE DIK_EQUALS DIK_GRAVE
NEC PC-98スタンダードキーボード NEC PC-98ラップトップキーボード	DIK_AT DIK_CIRCUMFLEX DIK_COLON DIK_F13, F14, F15 DIK_KANA DIK_KANJI DIK_NOCONVERT DIK_NUMPADCOMMA DIK_NUMPADEQUALS DIK_STOP DIK_UNDERLINE DIK_YEN	DIK_APOSTROPHE DIK_BACKSLASH DIK_EQUALS DIK_GRAVE  DIK_NUMLOCK DIK_NUMPADENTER DIK_RCONTROL DIK_RMENU DIK_RSHIFT  DIK_SCROLL
AXキーボード	DIK_AX DIK_CONVERT DIK_KANJI DIK_NOCONVERT DIK_YEN	DIK_RCONTROL DIK_RMENU
J-3100キーボード	DIK_KANA DIK_KANJI DIK_NOLABEL DIK_YEN	DIK_RCONTROL DIK_RMENU


DirectInputリファレンス


マクロ


DIDFT_GETINSTANCE

BYTE DIDFT_GETINSTANCE(

DWORD dwType)

オブジェクト・インスタンス番号コードをデータ・フォーマット・タイプから抽出する。詳細はDirectInputデータ・フォーマット・タイプを参照すること。

dwType

DirectInputデータ・フォーマット・タイプ。


DIDFT_GETTYPE

BYTE DIDFT_GETTYPE(

DWORD dwType)

オブジェクトタイプ・コードをデータ・フォーマットから抽出する。詳細はDirectInputデータ・フォーマット・タイプを参照すること。

dwType

DirectInputデータ・フォーマット・タイプ。


DISEQUENCE_COMPARE

BOOL DISEQUENCE_COMPARE(

DWORD dwSequence1, cmp,

DWORD dwSequence2)

ふたつのDirectInput順序番号を回り込みを考慮して比較する。

dwSequence1

比較する最初の順序番号。

cmp

次の比較演算子のひとつ。 "=="、 "!="、 "<"、 ">"、 "<="、 ">="。

dwSequence2

比較する二番目の順序番号。

返値

第一パラメータと第二パラメータとの順序関係が、第二パラメータで指定した比較演算子と一致した場合、0でない値を返す。

例

次の例はdwSequence1がdwSequence2より時系列的に先行するかをチェックする。

if (DISEQUENCE_COMPARE(dwSequence1, <, dwSequence2)) {

...

}

次の例はdwSequence1がdwSequence2より時系列的に後続または同時であるかをチェックする。

if (DISEQUENCE_COMPARE(dwSequence1, >=, dwSequence2)) {

...

}


GET_DIDEVICE_SUBTYPE

BYTE GET_DIDEVICE_SUBTYPE(

DWORD dwDevType)

デバイスのサブタイプ・コードをデバイス・タイプ記述コードから抽出する。サブタイプ・コードの解釈はデバイスのプライマリ・タイプに依存する。詳細はDirectInputデバイス・タイプ記述コードを参照すること。

dwDevType

DirectInputデバイス・タイプ記述コード。


GET_DIDEVICE_TYPE

BYTE GET_DIDEVICE_TYPE(

DWORD dwDevType)

デバイス・タイプコードをデバイス・タイプ記述コードから抽出する。詳細はDirectInputデバイス・タイプ記述コードを参照すること。

dwDevType

DirectInputデバイス・タイプ記述コード。


MAKEDIPROP

整数プロパティを作成するヘルパマクロ。

整数プロパティはMicrosoftにより定義されている。カスタム・プロパティを実装したいベンダーは、GUIDを用いること。


関数


DirectInputCreate

HRESULT DirectInputCreate(

HINSTANCE hinst,

DWORD dwVersion,

LPDIRECTINPUT * lplpDirectInput,

LPUNKNOWN punkOuter);

IDirectInput COMインターフェイスをサポートするDirectInputオブジェクトを作成するために呼び出される。正常に呼び出されると、関数は*lplpDirectInputにおける新たなオブジェクトへポインタを返す。

この関数をpunkOuter = NULLで呼び出すことは、 CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput, lplpDirectInput)を介してオブジェクトを作成しInitializeで初期化することと同等である。

この関数をpunkOuter != NULLで呼び出すことは、 CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInput)を介してオブジェクトを作成することと同等である。集成化されたオブジェクトは手作業で初期化しなければならない。

このサービスにはANSIバージョンおよびUNICODEバージョンが別に存在する。ANSIバージョンはIDirectInputAインターフェイスをサポートするオブジェクトを作成し、UNICODEバージョンはIDirectInputWインターフェイスをサポートするオブジェクトを作成する。文字セットが問題となる他のシステム・サービスについては、ヘッダファイルのマクロはDirectInputCreateを適切な文字セットにマッピングする。

hinst

DirectInputオブジェクトを作成しているアプリケーションまたはDLLのインスタンス・ハンドル。

dwVersion

使用されたdinput.hヘッダファイルのバージョン番号。この値はDIRECTINPUT_VERSIONでなければならない。

DirectInputはこの値を用いて、どのバージョンのDirectInputに対してアプリケーションまたはDLLが設計されたのかを知る。

lplpDirectInput

正常実行される場合、IDirectInputインターフェイスへのポインタをどこに返すかを指し示す。

punkOuter

OLE集成化機能が未知の制御へのポインタ。インターフェイスが集成化されていない場合は0。ほとんどの呼び出し側は0を渡す。

集成化が要求された場合、*lplpDirectInputに返されるオブジェクトはIUnknownへのポインタである。 OLE集成体が要求するIDirectInputへのポインタではないことに注意。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作が正常終了した。

DIERR_INVALIDPARAM = E_INVALIDARG: lplpDirectInputパラメータが有効なポインタではない。

DIERR_OUTOFMEMORY = E_OUTOFMEMORY: メモリが不足している。

DIERR_OLDDIRECTINPUTVERSION: DirectInputのバージョンが古い。

DIERR_BETADIRECTINPUTVERSION: サポート外であるDirectInputベータ・バージョンに対してアプリケーションが書かれていた。


joyConfigChanged

MMRESULT joyConfigChanged(

DWORD dwFlags);

レジストリに新たなジョイスティックの設定があることをジョイスティック・ドライバに通知する。

この関数は、ユーザがジョイスティックのキャリブレーションあるいは再キャリブレーションを行うとき、または別のジョイスティック・デバイスが選択されるときに、コントロールパネルにあるジョイスティック・キャリブレーションのプロパティから呼び出される。

OEMのジョイスティック・キャリブレーション・アプリケーションのように、アプリケーションがジョイスティックのパフォーマンスをカスタマイズするように設計されている場合、現在選択されているジョイスティックに対するレジストリのJOYSTICK USER値が変更されたことを、この関数を用いてジョイスティックドライバに通知することができる。JOYSTICK USER値はレジストリのHKEY_LOCAL_MACHINE部分にある。

dwFlags

予約されており、0にセットしておかなければならない。

返値

成功すれば JOYERR_NOERROR 、失敗すれば次のエラーを返す。

JOYERR_NOCANDO
JOYERR_REGISTRYNOTVALID


joyGetDevCaps

MMRESULT joyGetDevCaps(

UINT uJoyID,

LPJOYCAPS pjc,

UINT cbjc);

デバイスの持つ機能をジョイスティックに照会する。

この関数を用いて、ドライバがサポートするジョイスティック・デバイス数を知ることができる。

uJoyID

照会されるジョイスティックの識別子。JOYSTICKID1またはJOYSTICKID2である。

pjc

ジョイスティック機能を含むJOYCAPS構造体のアドレス。

cbjc

JOYCAPS構造体のサイズをバイト数で示す。

返値

成功すれば JOYERR_NOERROR 、失敗すれば次のエラーを返す。

MMSYSERR_INVALPARAM
MMSYSERR_NODRIVER  JOYERR_REGISTRYNOTVALID
参照　JOYCAPS, joyGetNumDevs


joyGetNumDevs

UINT joyGetNumDevs(VOID);

ジョイスティック・ドライバがサポートしているジョイスティック数をドライバから取得する。

指定されたジョイスティックがコンピュータに物理的に接続されているかどうかを調べるには、joyGetPosEx関数を用いる。

返値

ドライバがサポートするジョイスティック数を返す。ドライバが存在しなければ0を返す。

参照　joyGetDevCaps


joyGetPosEx

MMRESULT joyGetPosEx(UINT uJoyID, LPJOYINFOEX pji);

位置およびボタン状態をジョイスティックから取得する。

この関数を呼び出す前に、JOYINFOEX構造体のdwFlags要素にひとつ以上のフラグをセットして、アプリケーションが照会する項目を指定しなければならない。

この関数により、ラダーペダル、視点ハット、多数のボタンを持つデバイスといった拡張デバイスおよび最大6軸を用いた座標系へのアクセスが可能となる。

uJoyID

照会されるジョイスティックの識別子。

pji

ジョイスティックの拡張位置情報およびボタン状態を含むJOYINFOEX構造体のアドレス。

返値

成功すれば JOYERR_NOERROR 、失敗すれば次のエラーを返す。

JOYERR_UNPLUGGED
MMSYSERR_BADDEVICEID
MMSYSERR_INVALPARAM
MMSYSERR_NODRIVER
参照　JOYINFOEX


コールバック関数


DIEnumDeviceObjectsProc

BOOL CALLBACK DIEnumDeviceObjectsProc(

LPCDIDEVICEOBJECTINSTANCE lpddoi,

LPVOID pvRef);

IDirectInputDevice::EnumObjectsメソッドで用いられるコールバック関数。

lpddoi

列挙されているオブジェクトを記述するDIDEVICEOBJECTINSTANCE構造体のアドレス。

pvRef

IDirectInputDevice::EnumObjects関数において与えられている、アプリケーションにより定義された値を指定する。

返値

DIENUM_CONTINUE	列挙を継続する

DIENUM_STOP	列挙を中止する


DIEnumDevicesProc

BOOL CALLBACK DIEnumDevicesProc(

LPDIDEVICEINSTANCE lpddi,

LPVOID pvRef

);

IDirectInput::EnumDevicesメソッドで用いられるコールバック関数。

lpddi

列挙されているデバイスを記述するDIDEVICEINSTANCE構造体のアドレス。

pvRef

IDirectInput::EnumDevices関数で与えられた、アプリケーション定義のデータのアドレス。

返値

DIENUM_CONTINUE	列挙を継続する

DIENUM_STOP	列挙を中止する


IClassFactory

IClassFactoryインターフェイスはOLEサポートに必要とされる。詳細な情報についてはOLEマニュアルを参照すること。DirectInputを用いるアプリケーションのほとんどは、OLEクラスファクトリと直接通信する必要はない。


IClassFactory::AddRef

HRESULT AddRef(

LPCLASSFACTORY lpClassFactory);

インターフェイスに対する参照カウントをインクリメントする。OLEマニュアルのIUnknown::AddRefを参照すること。

返値

オブジェクト参照カウントを返す。


IClassFactory::CreateInstance

HRESULT CreateInstance(

LPCLASSFACTORY lpClassFactory,

LPUNKNOWN punkOuter,

REFIID riid,

LPVOID * ppvOut);

新たなDirectInputオブジェクトを指定されたインターフェイスで作成する。OLEマニュアルのIClassFactory::CreateInstanceを参照すること。新たに作成されたオブジェクトはまだ初期化されていないことに注意。

punkOuter

OLE集成化機能が未知の制御へのポインタ、またはインターフェイスが集成化されていない場合は0。ほとんどの呼び出し側は0を渡す。

riid

必要なインターフェイス。このパラメータは有効なインターフェイス識別子を指し示す必要がある。

ppvOut

正常実行される場合、作成されたインターフェイスへのポインタをどこに返すかを指し示す。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

S_OK: 操作は正常終了した。

E_INVALIDARG: ppvOutパラメータは有効なポインタでない。

CLASS_E_NOAGGREGATION: 集成化機能がサポートされていない。

E_OUTOFMEMORY: メモリが不足している。

E_NOINTERFACE: 指定されたインターフェイスはサポートされていない。


IClassFactory::LockServer

HRESULT LockServer(

LPCLASSFACTORY lpClassFactory,

BOOL fLock);

DLLロック・カウントをインクリメントまたはデクリメントする。DLLロック・カウントが0でない場合は、メモリから削除されない。OLEマニュアルのIClassFactory::LockServerを参照すること。

fLock

TRUEである場合、ロック・カウントをインクリメントする。 FALSEである場合、ロック・カウントをデクリメントする。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

S_OK: 操作は正常終了した。

E_OUTOFMEMORY: メモリが不足している。


IClassFactory::QueryInterface

HRESULT QueryInterface(

LPCLASSFACTORY lpClassFactory,

REFIID riid,

LPVOID * ppvObj);

オブジェクト上の他のインターフェイスにクライアント・アクセスを与える。OLEマニュアルのIUnknown::QueryInterfaceを参照すること。

riid

必要なインターフェイスIID。

ppvObj

得られるインターフェイスへのポインタを受け取る。

返値

COMエラーコードを返す。


IClassFactory::Release

HRESULT Release(LPCLASSFACTORY lpClassFactory);

インターフェイスに対する参照カウントをデクリメントする。オブジェクトの参照カウントが0になる場合、そのオブジェクトはメモリから解放される。OLEマニュアルのIUnknown::Releaseを参照すること。

返値

オブジェクト参照カウントを返す。


IDirectInput

DirectInputオブジェクトはDirectInputサブシステムを表し、単一入力デバイスを表すDirectInputDeviceオブジェクトを作成する。


IDirectInput::AddRef

DWORD AddRef(

LPDIRECTINPUT lpDirectInput);

IDirectInputが継承するIUnknownインターフェイスの一部。関連のあるCOMオブジェクトの参照カウントを増やすために用いられる。オブジェクトが最初に作成される際に、参照カウントは1にセットされる。AddRefが呼び出されるたびに参照カウントはインクリメントされ、Releaseが呼び出されるたびに参照カウントはデクリメントされる。参照カウントが0になると、そのオブジェクトは解放される。

lpDirectInput

このメンバが呼び出されたDirectInputオブジェクトを指し示す。

返値

新たな参照カウントを持つDWORD。


IDirectInput::CreateDevice

HRESULT CreateDevice(

LPDIRECTINPUT lpDirectInput,

REFGUID rguid,

LPDIRECTINPUTDEVICE *lplpDirectInputDevice,

LPUNKNOWN * pUnkOuter);

GUIDが指定するデバイスのインスタンスを作成し初期化する。

この関数をpunkOuter = NULLで呼び出すことは、 CoCreateInstance(&CLSID_DirectInputDevice, NULL, CLSCTX_INPROC_SERVER, riid, lplpDirectInputDevice)を介してオブジェクトを作成しInitializeで初期化することと同等である。

この関数をpunkOuter != NULLで呼び出すことは、 CoCreateInstance(&CLSID_DirectInputDevice, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput, lplpDirectInput)を介してオブジェクトを作成することと同等である。集成化されたオブジェクトは手作業で初期化されなければならない。

lpDirectInput

このメンバが呼び出されたDirectInputオブジェクトを指し示す。

rguid

必要な入力デバイスを表すGUIDへの参照。このGUIDはEnumDevicesメソッドを通して取得されるか、あるいはあらかじめ定義されているGUIDのひとつである。

lplpDirectInputDevice

正常に実行される場合、 IDirectInputDeviceインターフェイス・ポインタを指し示す。

punkOuter

OLE集成化機能が未知の制御へのポインタ、またはインターフェイスが集成化されていない場合は0。ほとんどの呼び出し側は0を渡す。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常終了した。

DIERR_INVALIDPARAM = E_INVALIDARG: ppvOutパラメータは有効なポインタでない。

DIERR_OUTOFMEMORY = E_OUTOFMEMORY: メモリが不足している。

DIERR_NOINTERFACE = E_NOINTERFACE: 指定されたインターフェイスはこのオブジェクトによりサポートされていない。

DIERR_DEVICENOTREG: デバイス・インスタンスが、DirectInputで登録されているデバイスに相当しない。


IDirectInput::EnumDevices

HRESULT EnumDevices(

LPDIRECTINPUT lpDirectInput,

DWORD dwDevType,

LPDIENUMCALLBACK lpCallback,

LPVOID pvRef,

DWORD dwFlags);

コンピュータに現在接続されているか、あるいは接続可能なデバイスを列挙する。たとえばフライト・スティックをシステムにインストールしたが現時点ではコンピュータに接続していないといった場合があるため、接続されているデバイスだけを列挙するかインストールされているデバイスすべてを列挙するかを示すフラグをdwFlagsパラメータにセットする。フラグ DIEDFL_ATTACHEDONLYがセットされていないと、インストールされているデバイスすべてが列挙される。列挙するデバイスのタイプをフィルタとして渡すこともできる。

アプリケーションが定義するコールバック関数は、lpCallbackパラメータのIDirectInput::EnumDevicesへ渡される。この関数は、列挙されたデバイスすべてに対して呼び出される。コールバックでは、デバイス・タイプとそのニックネーム、および製品GUIDとそのニックネームが、各デバイスに与えられる。単一の入力デバイスに複数のDirectInputデバイス・タイプの機能がある場合は、サポートする各デバイス・タイプに対して値が返される（たとえば、内蔵マウスをもつキーボードは、キーボードおよびマウスとして列挙される。しかし、製品GUIDは各デバイスに対して同一である）。

このリリースのDirectInputでは、マウスおよびキーボード・デバイスのみが列挙されている。

lpDirectInput

このメンバが呼び出されたDirectInputオブジェクトを指し示す。

dwDevType

デバイス・タイプ・フィルタ。0である場合は、すべてのデバイス・タイプが列挙される。そうでない場合はDIDEVTYPE_*値となり、列挙されるデバイス・タイプを示す。このリリースのDirectInputでは、マウス・デバイスおよびキーボードだけが列挙される。

lpCallback

各DirectInputデバイスの記述とともに呼び出される、アプリケーション定義コールバック関数を指し示す。

BOOL CALLBACK DIEnumDevicesProc(LPDIDEVICEINSTANCE lpddi,

LPVOID pvRef)

lpddi

このデバイス・インスタンスを記述する構造体を指し示す。

pvRef

EnumDevicesに与えられる、アプリケーション定義データを指し示す。

pvRef

呼び出されるたびに列挙コールバックへ渡される、呼び出し側により定義された32ビット・コンテキストを指し示す。

dwFlags

現在定義されているフラグは次のひとつだけである。

DIEDFL_ATTACHEDONLY- 現在接続されているデバイスのみを列挙する。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常終了した。コールバックが途中で列挙を中止した場合、列挙は正常終了したと見なされることに注意。

DIERR_INVALIDPARAM = E_INVALIDARG:   flパラメータに無効なフラグがあったか、あるいはコールバックが無効なステータス・コードを返した。


IDirectInput::GetDeviceStatus

HRESULT GetDeviceStatus(

LPDIRECTINPUT lpDirectInput,

REFGUID rguidInstance);

このメンバは、指定されたデバイスが現在DirectInputに接続されているかをチェックする。デバイスが接続されている場合にはOKを、されていない場合にはエラーを返す。

lpDirectInput

このメンバが呼び出されたDirectInputオブジェクトを指し示す。

rguidInstance

ステータスをチェックするデバイスのインスタンスを識別する。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: デバイスは接続されている。

DI_NOTATTACHED = S_FALSE: デバイスは接続されていない。

DIERR_GENERIC = E_FAIL:  デバイスが接続されているかをDirectInputは確定できなかった。

DIERR_INVALIDPARAM = E_INVALIDARG:  デバイスは存在しない。


IDirectInput::Initialize

HRESULT Initialize(

LPDIRECTINPUT lpDirectInput,

HINSTANCE hinst,

DWORD dwVersion);

DirectInputオブジェクトを初期化する。DirectInputオブジェクト・デバイスが作成されるとDirectInputCreateメソッドが自動的に初期化を行うため、通常はアプリケーションからこの関数を呼び出す必要はない。

hinst

DirectInputオブジェクトを作成しているアプリケーションまたはDLLのインスタンス・ハンドル。

dwVersion

使用されたdinput.hヘッダファイルのバージョン番号。この値はDIRECTINPUT_VERSIONでなければならない。

DirectInputはこの値を用いて、どのバージョンのDirectInputに対してアプリケーションまたはDLLが設計されたのかを確定する。

返値

COMエラーコードを返す。以下のエラーコードは返されるすべてのコードとは限らない。

DI_OK = S_OK: デバイスは接続されている。

DIERR_OLDDIRECTINPUTVERSION: DirectInputのバージョンが古い。

DIERR_BETADIRECTINPUTVERSION: サポート外であるDirectInputベータ・バージョンに対してアプリケーションが書かれていた。


IDirectInput::QueryInterface

HRESULT QueryInterface(

LPDIRECTINPUT lpDirectInput,

REFIID riid,

LPVOID FAR* ppvObj);

IDirectInputが継承するIUnknownインターフェイスの一部。アプリケーションが使用しようとしているインターフェイスをそのオブジェクトがサポートしているかどうか問い合わせるために用いる。問い合わせた特定のCOMインターフェイスをオブジェクトがサポートしている場合、アプリケーションはそのインターフェイスを直ちに使用し始めることができる。必要なインターフェイスがサポートされている場合、アプリケーションのppvObjパラメータにポインタが返される。アプリケーションがそのインターフェイスを使用しないか、あるいは使用を終了した場合は、Releaseを呼び出してインターフェイスを解放しなければならない。このメンバにより、既存あるいは将来の機能と衝突、干渉することなくDirectInputオブジェクトを拡張できる。詳細については、OLEマニュアルのIUnknown::QueryInterfaceを参照すること。

lpDirectInput

このメンバが呼び出されたDirectInputオブジェクトを指し示す。

riid

必要なインターフェイスを識別するインターフェイス識別子(IID)を指し示す。

ppvObj

問い合わせが正常に実行される場合返されるインターフェイス・ポインタが代入される位置を指し示す。

返値

DI_OK

DIERR_INVALIDPARAM

DIERR_NOINTERFACE


IDirectInput::Release

DWORD Release(

LPDIRECTINPUT lpDirectInput);

IDirectInputが継承するIUnknownインターフェイスの一部。関連のあるCOMオブジェクトの参照カウントを減らすために用いられる。オブジェクトが最初に作成されるとき、参照カウントは1にセットされる。AddRefが呼び出されるたびに参照カウントはインクリメントされ、Releaseが呼び出されるたびに参照カウントはデクリメントされる。参照カウントが0になると、そのオブジェクトは解放される。詳細については、OLEマニュアルの IUnknown::QueryInterfaceを参照すること。

lpDirectInput

このメンバが呼び出されたDirectInputオブジェクトを指し示す。

返値

新たな参照カウントを含むDWORD。この返値はデバッグ用途にだけ使用されることに注意。


IDirectInput::RunControlPanel

HRESULT RunControlPanel(

LPDIRECTINPUT lpDirectInput,

HWND hwndOwner,

DWORD dwFlags);

ユーザが新たな入力デバイスをインストールしたりセットアップを修正したりできるよう、WindowsのDirectInputコントロールパネルを実行するために用いられる。サードパーティのコントロールパネルは実行しない。

lpDirectInput

このメンバが呼び出されたDirectInputオブジェクトを指し示す。

hwndOwner

後続のUIに対する親ウィンドウとして用いられるウィンドウ・ハンドルを識別する。NULLは親ウィンドウが存在しないことを示す。

dwFlags

現時点ではフラグは定義されていない。このパラメータは0でなければならない。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: デバイスは接続されている。


IDirectInputDevice

IDirectInputDeviceインターフェイスは、入力デバイスのインスタンスからデータを取得するために用いる。


IDirectInputDevice::Acquire

HRESULT Acquire(

LPDIRECTINPUTDEVICE lpDirectInputDevice);

入力デバイスへのアクセスを取得する。GetDeviceStateまたはGetDeviceDataを呼び出す前に、デバイスを認識しておかなければならない。デバイス認識には参照カウントが存在せず、デバイスが二度認識されて一度解放された場合、デバイスは解放された状態になる。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

返値

COMエラーコードを返す。以下のエラーコードは、返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常終了した。

S_FALSE: デバイスはすでに認識されている。この値は正常コードであることに注意すること。

DIERR_INPUTLOST: デバイスへのアクセスが与えられていない。

DIERR_INVALIDPARAM = E_INVALIDARG:  デバイスは選択されたデータ・フォーマット形式ではない。


IDirectInputDevice::AddRef

DWORD AddRef(LPDIRECTINPUTDEVICE lpDirectInputDevice);

IDirectInputDeviceが継承するIUnknownインターフェイスの一部。関連のあるCOMオブジェクトの参照カウントを増やすために用いられる。オブジェクトが最初に作成される際に、参照カウントは1にセットされる。AddRefが呼び出されるたびに参照カウントはインクリメントされ、Releaseが呼び出されるたびに参照カウントはデクリメントされる。参照カウントが0になると、そのオブジェクトは解放される。詳細については、OLEマニュアルの IUnknown::AddRefを参照すること。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

返値

新たな参照カウントを含むDWORD。


IDirectInputDevice::GetCapabilities

HRESULT GetCapabilities(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

LPDIDEVCAPS lpDIDevCaps);

入力デバイスの情報を取得する。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

lpDIDevCaps

この関数が情報を返すDIDEVCAPS構造体を指し示す。このメソッドを呼び出す前に、構造体のサイズをdwSizeフィールドで指定しておかなければならない。

参照　DIDEVCAPS

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常終了した。

DIERR_INVALIDPARAM = E_INVALIDARG:  lpDIDevCapsパラメータが有効なポインタではない。


IDirectInputDevice::GetDeviceData

HRESULT GetDeviceData(

LPDIRECTINPUTDEVICE  lpDirectInputDevice,

DWORD cbObjectData,

LPDIDEVICEOBJECTDATA rgdod,

LPDWORD pdwInOut,

DWORD fl);

DirectInputデバイスからバッファ・データを取得する。

デバイス・データ取得の前に、SetCooperativeLevelに協調レベルを、SetDataFormatにデータ・フォーマットをそれぞれセットし、Acquireでデバイスを認識しておかなければならない。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

cbObjectData

DIDEVICEOBJECTDATA構造体のサイズをバイトで示したもの。

rgdod

バッファ・データを受け取るためのDIDEVICEOBJECTDATA構造体の配列。*pdwInOut要素で構成されていなければならない。

このパラメータがNULLの場合、バッファ・データはどこにも格納されないが、それ以外の動作は行われる。

pdwInOut

最初はrgdodにより指し示される配列の要素数。呼び出し後は実際に得られた要素数。

fl

データ取得の方法を制御するフラグ。0あるいは以下のフラグである。

DIGDD_PEEK: バッファから項目を削除しない。後続のGetDeviceDataは同じデータを読み取る。通常は、データは読み取られた後バッファから削除される。

返値

DI_OK = S_OK: すべてのデータは正常に取得された。データが取得されたか、またどれぐらいの量のデータが取得されたかを知るために、アプリケーションが*pdwInOutの出力値をチェックする必要があることに注意。この値が0のときは、バッファが空であることを示す。

DI_BUFFEROVERFLOW = S_FALSE: データは正常に取得されたが、デバイスのバッファ・サイズが十分でなかったためデータがいくつか失われた。この場合、バッファ・データの取得回数を増やすか、デバイス・バッファのサイズを大きくしなければならない。この返値はバッファがオーバーフローした後IDirectInputDevice::GetDeviceDataを最初に呼び出すときだけ返される。このコードは正常ステータス・コードであることに注意。

DIERR_NOTACQUIRED: デバイスが認識されていない。

DIERR_INPUTLOST: デバイスへのアクセスが中断された。アプリケーションはデバイスを再認識しなければならない。

DIERR_INVALIDPARAM= E_INVALIDARG: 無効なパラメータが存在した。

例

次の例では、10個のバッファ・データ要素を読み取り、読み取り後デバイス・バッファからそれらを削除する。

DIDEVICEOBJECTDATA rgdod[10];

DWORD dwItems = 10;

hres = IDirectInputDevice_GetDeviceData(

pdid,

sizeof(DIDEVICEOBJECTDATA),

rgdod,

&dwItems,

0);

if (SUCCEEDED(hres)) {

// バッファは正常にフラッシュされた

// dwItems = フラッシュされた要素数

if (hres == DI_BUFFEROVERFLOW) {

// バッファがオーバーフローした

}

}

rgdodにNULLを渡し項目数として無限大を指定すると、バッファはフラッシュされ、フラッシュされた項目数が返される。

dwItems = INFINITE;

hres = IDirectInputDevice_GetDeviceData(

pdid,

sizeof(DIDEVICEOBJECTDATA),

NULL,

&dwItems,

0);

if (SUCCEEDED(hres)) {

// バッファは正常にフラッシュされた．

// dwItems = フラッシュされた要素数

if (hres == DI_BUFFEROVERFLOW) {

// バッファがオーバーフローした。

}

}

rgdodにNULLを渡して項目数として無限大を指定し、デバイス・バッファからデータを削除しないようにすると、デバイス・バッファの要素数を問い合わせるのと同じことになる。

dwItems = INFINITE;

hres = IDirectInputDevice_GetDeviceData(

pdid,

sizeof(DIDEVICEOBJECTDATA),

NULL,

&dwItems,

DIGDD_PEEK);

if (SUCCEEDED(hres)) {

// dwItems = バッファの要素数

if (hres == DI_BUFFEROVERFLOW) {

// バッファのオーバーフローが起こった

// すべてのデータが正常にキャプチャされたわけではない

}

}

rgdodにNULLを渡し項目を全く要求しないと、バッファのオーバーフローが起こったかどうか問い合わせるのと同じことになる。

dwItems = 0;

hres = IDirectInputDevice_GetDeviceData(

pdid,

sizeof(DIDEVICEOBJECTDATA),

NULL,

&dwItems,

0);

if (hres == DI_BUFFEROVERFLOW) {

// バッファのオーバーフローが起こった

}


IDirectInputDevice::GetDeviceInfo

HRESULT GetDeviceInfo(

LPDIRECTINPUTDEVICE 	lpDirectInputDevice,

LPDIDEVICEINSTANCE 	pdidi)

デバイスの識別情報を取得する。

パラメータ

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

pdidi

デバイスの識別情報を受け取る。このメソッドを呼び出す前に、呼び出し側はDIDEVICEINSTANCE構造体のdwSizeフィールドを初期化しなければならない。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

DIERR_INVALIDPARAM = E_INVALIDARG: ひとつ以上のパラメータが無効であった。


IDirectInputDevice::GetDeviceState

HRESULT GetDeviceState(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

DWORD cbData,

LPVOID lpvData);

DirectInputデバイスから即時データを取得する。

デバイス・データ取得の前に、SetCooperativeLevelに協調レベルを、SetDataFormatにデータ・フォーマットをそれぞれセットし、Acquireでデバイスを認識しておかなければならない。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

cbData

lpvDataにより指し示されるバッファのサイズをバイトで示したもの。

lpvData

デバイスの現在の状態を受け取る構造体を指し示す。データのフォーマットは、あらかじめIDirectInputDevice::SetDataFormatを呼び出すことで決められる。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

E_PENDING: デバイスにはまだデータが存在しない。デバイスの中には(たとえばUSBジョイスティック)、デバイスがオンになる時刻とデバイスがデータを送信し始める時刻の間に待ち時間を要するものがある。このウォームアップ時間中、GetDeviceStateはE_PENDINGを返す。データが利用可能になると、イベント通知ハンドルにシグナルが送られる。

DIERR_NOTACQUIRED: デバイスが認識されていない。

DIERR_INPUTLOST:  デバイスへのアクセスが中断された。アプリケーションはデバイスを再認識しなければならない。

DIERR_INVALIDPARAM= E_INVALIDARG:  lpvDataパラメータが有効なポインタでないか、前回のSetDataFormat呼び出しでセットされたデータサイズとcbDataパラメータとが一致しない。


IDirectInputDevice::GetObjectInfo

HRESULT GetObjectInfo(

LPDIRECTINPUTDEVICE 	lpDirectInputDevice,

LPDIDEVICEOBJECTINSTANCE pdidoi,

DWORD dwObj,

DWORD dwHow)

オブジェクトに関する情報を得る。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

pdidoi

オブジェクトに関する情報を受け取る。このメソッドを呼び出す前に、呼び出し側はDIDEVICEOBJECTINSTANCE構造体のdwSizeフィールドを初期化しなければならない。

dwObj

プロパティがアクセスされるオブジェクトを識別する。

dwHow

dwObjの解釈方法を識別する。

参照　DIPROPHEADER

返値

COMエラーコードを返す。以下のエラーコードは例証的であると意図されており、返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

DIERR_INVALIDPARAM = E_INVALIDARG: 無効なパラメータが存在する。

DIERR_OBJECTNOTFOUND:  指定されたオブジェクトが存在しない。


IDirectInputDevice::GetProperty

HRESULT GetProperty(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

REFGUID rguidProp,

LPDIPROPHEADER pdiph);

入力デバイスに関する情報を取得する。いくつかのプロパティはIDirectInputDevice::SetPropertyメソッドの呼び出しでセットされる。それ以外は読み出し専用である。IDirectInputDevice::SetPropertyメソッドのセット可能なプロパティのリストを参照すること。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

rguidProp

取得されるプロパティの識別子。あらかじめ定義されているDIPROP_*値のひとつか、プロパティを識別するGUIDへのポインタ(C++を使用する場合は参照) 。

以下のプロパティが入力デバイスに対してあらかじめ定義されている。

DIPROP_AXISMODE

DIPROP_BUFFERSIZE

DIPROP_GRANULARITY

DIPROP_RANGE

これらのプロパティそれぞれの詳細については、構造体および定数の節で個々のプロパティの記述を参照すること。

pdiph

プロパティに依存する構造体のDIPROPHEADER部を指し示す。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

DIERR_INVALIDPARAM = E_INVALIDARG:  pdiphパラメータが有効なポインタでないか、dwHowフィールドが無効か、あるいはdwHowがDIPH_DEVICEにセットされていながらdwObjフィールドが0でない。

DIERR_OBJECTNOTFOUND:  指定されたオブジェクトが存在しない。

DIERR_UNSUPPORTED = E_NOTIMPL:デバイスまたはオブジェクトがプロパティをサポートしていない。

例

以下のC言語コードの一部は、DIPROP_BUFFERSIZEプロパティの値の取得方法を示している。

DIPROPDWORD dipdw;

HRESULT hres;

dipdw.diph.dwSize = sizeof(DIPROPDWORD);

dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);

dipdw.diph.dwObj  = 0;                   // デバイスのプロパティ

dipdw.diph.dwHow = DIPH_DEVICE;

hres = IDirectInputDevice_GetProperty(pdid, DIPROP_BUFFERSIZE, &dipdw.diph);

if (SUCCEEDED(hres)) {

// dipdw.dwDataにプロパティの値が入る

}


IDirectInputDevice::EnumObjects

HRESULT EnumObjects(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

LPDIENUMDEVICEOBJECTSCALLBACK lpCallback,

LPVOID pvRef,

DWORD fl);

入力デバイスにおいて利用可能な入力ソース(軸、ボタンなど)を列挙する。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

lpCallback

DirectInputDeviceオブジェクトを受け取るアプリケーションにより定義されたコールバック関数を指し示す。

BOOL CALLBACK DIEnumDeviceObjectsProc(

LPCDIDEVICEOBJECTINSTANCE lpddoi,

LPVOID pvRef);

pvRef

コールバックに対する参照データ(コンテキスト)。

fl

列挙されるオブジェクトのタイプを指定するフラグ。データ・フォーマット・タイプの組み合わせであることもある。DirectInputデータ・フォーマット・タイプを参照すること。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。コールバックが途中で列挙を中止した場合、列挙は正常終了したと見なされることに注意。

DIERR_INVALIDPARAM = E_INVALIDARG:   flパラメータに無効なフラグがあったか、あるいはコールバックが無効なステータス・コードを返した。


IDirectInputDevice::Initialize

HRESULT Initialize(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

HINSTANCE hinst,

DWORD dwVersion,

REFGUID rguid);

DirectInputDeviceオブジェクトを初期化する。

このメソッドが正常に実行されなかった場合、オブジェクトは状態が不定であると見なされる。続けてそのオブジェクトを使用するには再度初期化の必要があることに注意。

IDirectInput::CreateDeviceメソッドはデバイスを作成すると自動的にそれを初期化するため、通常はアプリケーションからこの関数を呼び出す必要はない。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

hinst

DirectInputDeviceオブジェクトを作成しているアプリケーションまたはDLLのインスタンス・ハンドル。DirectInputは、この値を用いてアプリケーションあるいはDLLが認証されているかどうかを知る。

dwVersion

使用されたdinput.hヘッダファイルのバージョン番号。この値はDIRECTINPUT_VERSIONでなければならない。

DirectInputはこの値を用いて、どのバージョンのDirectInputに対してアプリケーションまたはDLLが設計されたのかを確定する。

rguid

インターフェイスに関連のあるデバイスのインスタンスを識別する。IDirectInput::EnumDevicesメソッドを用いて、システムがどのインスタンスGUIDをサポートしているかを知ることができる。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: デバイスは接続されている。

DIERR_OLDDIRECTINPUTVERSION: DirectInputのバージョンが古い。

DIERR_BETADIRECTINPUTVERSION: サポート外であるDirectInputベータ・バージョンに対してアプリケーションが書かれていた。

S_FALSE: デバイスはrguidに渡されたインスタンスGUIDですでに初期化されていた。

DIERR_ACQUIRED: デバイスは認識されているが初期化できなかった。


IDirectInputDevice::QueryInterface

HRESULT QueryInterface(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

REFIID riid,

LPVOID FAR* ppvObj);

IDirectInputDeviceが継承するIUnknownインターフェイスの一部。アプリケーションが使用しようとしているインターフェイスをそのオブジェクトがサポートしているかどうか問い合わせるために用いる。問い合わせた特定のCOMインターフェイスをオブジェクトがサポートしている場合、アプリケーションはそのインターフェイスを直ちに使用し始めることができる。必要なインターフェイスがサポートされている場合、アプリケーションのppvObjパラメータにポインタが返される。アプリケーションがそのインターフェイスを使用しないか、あるいは使用を終了した場合は、Releaseを呼び出してインターフェイスを解放しなければならない。このメンバにより、既存あるいは将来の機能と衝突、干渉することなくDirectInputオブジェクトを拡張できる。詳細については、OLEマニュアルのIUnknown::QueryInterfaceを参照すること。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

riid

必要なインターフェイスを識別するインターフェイスID(IID)を指し示す。

ppvObj

問い合わせが正常に実行された場合返されるインターフェイス・ポインタが代入される位置を指し示す。

返値

DI_OK

DIERR_INVALIDPARAM

DIERR_NOINTERFACE


IDirectInputDevice::Release

DWORD Release(LPDIRECTINPUTDEVICE lpDirectInputDevice);

IDirectInputDeviceが継承するIUnknownインターフェイスの一部。関連のあるCOMオブジェクトの参照カウントを減らすために用いられる。オブジェクトが最初に作成されるとき、参照カウントは1にセットされる。AddRefが呼び出されるたびに参照カウントはインクリメントされ、Releaseが呼び出されるたびに参照カウントはデクリメントされる。参照カウントが0になると、そのオブジェクトは解放される。詳細については、OLEマニュアルの IUnknown::QueryInterfaceを参照すること。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

返値

新たな参照カウントを含むDWORD。この返値はデバッグ用途にだけ使用されることに注意。


IDirectInputDevice::RunControlPanel

HRESULT RunControlPanel(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

HWND hwndOwner,

DWORD dwFlags);

デバイスに関連づけられたコントロールパネルを実行する。デバイスに関連づけられたコントロールパネルが存在しない場合、デフォルトのデバイス・コントロールパネルが起動される。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

hwndOwner

後続のUIに対する親ウィンドウとして用いられるウィンドウ・ハンドルを識別する。NULLは親ウィンドウが存在しないことを示す。

dwFlags

現時点ではフラグは定義されていない。このパラメータは0でなければならない。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。


IDirectInputDevice::SetCooperativeLevel

HRESULT SetCooperativeLevel(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

HWND hwnd,

DWORD dwFlags);

デバイスのインスタンスに対して協調レベルを確立する。協調レベルは、デバイスのインスタンスが他のインスタンスやシステムの他の部分とどのように相互作用するかを決定する。

システム・マウスが排他モードで認識されている場合、デバイスが解放されるまでマウス・カーソルがスクリーンから見えなくなることに注意。

IDirectInputDevice::Acquireでデバイスを認識する前に、このメソッドを呼び出さなければならない。

hwnd

デバイスと関連するウィンドウ。 DISCL_FOREGROUNDフラグが渡されている場合、このパラメータはNULL以外でなければならない。このウィンドウはトップレベルでなければならない。DirectInputデバイスにおいてアクティブである間にウィンドウを閉じるとエラーになる。

dwFlags

デバイスと関連する協調レベルを記述するフラグ。

DISCL_*フラグについては別途文書化されている。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

DIERR_INVALIDPARAM = E_INVALIDARG: hwndパラメータに無効なウィンドウ・ハンドルあるいは無効なフラグまたはフラグの組み合わせが渡された。


IDirectInputDevice::SetDataFormat

HRESULT SetDataFormat(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

LPCDIDATAFORMAT lpdf);

DirectInputデバイスに対するデータ・フォーマットをセットする。データ・フォーマットはデバイスが認識される前にセットする必要がある。データ・フォーマットのセットはただ一度だけでなければならない。データ・フォーマットはデバイスが認識されている間は変更することができない。データ・フォーマットのセットに失敗すると、データ・フォーマット情報はすべて失われる。そのためデバイスが認識される前に有効なデータ・フォーマットをセットしておかなければならない。アプリケーションは通常、あらかじめ定義されているデータ・フォーマットであるc_dfDIMouseまたは c_dfDIKeyboardのいずれかを用いる。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

lpdf

DirectInputDeviceが返すデータ・フォーマットを記述する構造体を指し示す。

返値

COMエラーコードを返す。以下のエラーコードは実例を示すことを意図しており、返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

DIERR_INVALIDPARAM = E_INVALIDARG: lpdfパラメータは有効なポインタではない。

DIERR_ACQUIRED: デバイスが認識されている間はデータ・フォーマットを変更することができない。


IDirectInputDevice::SetEventNotification

HRESULT SetEventNotification(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

HANDLE Event);

デバイス状態の変更時にセットされるイベントを指定する。イベント通知をオフにするためにも用いられる。

IDirectInputDeviceオブジェクトがすでに選択しているイベントに対しCloseHandleを呼び出すとエラーになる。そのため、イベント・ハンドルを閉じる前に、hEventパラメータをNULLにセットしてIDirectInputDevice::SetEventNotificationを呼び出さなければならない。

デバイスが認識されている間はイベント通知ハンドルを変更することはできない。

関数が正常に実行された場合、アプリケーションは、他のWin32イベント・ハンドルと同様の方法でイベント・ハンドルを用いることができる。使用法の例を以下に示す。Win32ウェイト関数を用いる際の情報については、Win32 SDKおよび関連のマニュアルを参照すること。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

hEvent

デバイス状態の変更時にセットされるイベントへのハンドル。DirectInputはデバイスの状態が変化するときにハンドルをSetEventする。

手動リセット・イベントのハンドルを作成するには、 CreateEvent関数を用いる。イベントを自動リセット・イベントとして作成した場合、ウェイト時間を過ぎるとOSが自動的にイベントをリセットする。イベントを手動リセット・イベントとして作成した場合、ResetEventを呼び出してリセットするのはアプリケーションの役割となる。DirectInputはイベント通知ハンドルを得るためにResetEventを呼び出すことはしない。ほとんどのアプリケーションではイベントを自動リセット・イベントとして作成する。

hEventがNULLの場合、通知は不可能となる。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

DIERR_ACQUIRED: IDirectInputDeviceオブジェクトは認識されている。IDirectInputDevice::Unacquireを呼び出して、通知状態の変更前にデバイスを解放しなければならない。

DIERR_HANDLEEXISTS: IDirectInputDeviceオブジェクトには、イベント通知ハンドルがすでに存在する。DirectInputでは、ひとつのIDirectInputDeviceオブジェクトに対しサポートされるイベント通知ハンドルはひとつだけである。

E_INVALIDARG: イベント・ハンドルではない。

例

ハンドルが現時点でセットされているかどうか、ブロッキングせずにチェックする。

dwResult = WaitForSingleObject(hEvent, 0);

if (dwResult == WAIT_OBJECT_0) {

// イベントがセットされた

// イベントが自動リセットとして作成された場合、

// それもまたリセットされる

}

次の例では、イベントがセットされるまで無制限にブロッキングしている。この手法は決して推奨できない。ウェイト時間が過ぎるまで、スレッドがシステム(特にWindowsメッセージ)に対して応答しないからである。

dwResult = WaitForSingleObject(hEvent, INFINITE);

if (dwResult == WAIT_OBJECT_0) {

// イベントがセットされた

// イベントが自動リセットとして作成された場合、

// それもまたリセットされる

}

メッセージ・ベースでイベントをふたつ用いているアプリケーションの典型的なメッセージ・ループが次の例である。

HANDLE ah[2] = { hEvent1, hEvent2 };

while (TRUE) {

dwResult = MsgWaitForMultipleObjects(2, ah, FALSE,

INFINITE, QS_ALLINPUT);

switch (dwResult) {

case WAIT_OBJECT_0:

// イベント1がセットされた

// イベントが自動リセットとして作成された場合、

// それもまたリセットされる

ProcessInputEvent1();

break;

case WAIT_OBJECT_0 + 1:

// イベント2がセットされた

// イベントが自動リセットとして作成された場合、

// それもまたリセットされる

ProcessInputEvent2();

break;

case WAIT_OBJECT_0 + 2:

// Windowsメッセージを受け取った

// メッセージがなくなるまで処理を行う

while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)){

if (msg.message == WM_QUIT) {

goto exitapp;

}

TranslateMessage(&msg);

DispatchMessage(&msg);

}

break;

default:

// 予期しないエラー

Panic();

break;

}

}

メッセージ・ベースでないアプリケーションでイベントをふたつ用いている場合の典型的なアプリケーション・ループが次の例である。

HANDLE ah[2] = { hEvent1, hEvent2 };

DWORD dwWait = 0;

while (TRUE) {

dwResult = MsgWaitForMultipleObjects(2, ah, FALSE,	 dwWait, QS_ALLINPUT);

dwWait = 0;

switch (dwResult) {

case WAIT_OBJECT_0:

// イベント1がセットされた

// イベントが自動リセットとして作成された場合、

// それもまたリセットされる

ProcessInputEvent1();

break;

case WAIT_OBJECT_0 + 1:

// イベント2がセットされた

// イベントが自動リセットとして作成された場合、

// それもまたリセットされる

ProcessInputEvent2();

break;

case WAIT_OBJECT_0 + 2:

// Windowsメッセージを受け取った

// メッセージがなくなるまで処理を行う

while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)){

if (msg.message == WM_QUIT) {

goto exitapp;

}

TranslateMessage(&msg);

DispatchMessage(&msg);

}

break;

default:

// 待っている入力やメッセージは存在しない

// ゲームのフレームを決める

// ゲームがアイドル状態の場合、次のウェイトに対して

// 入力やメッセージを無制限に待ち続けるよう指示する

if (!DoGame()) {

dwWait = INFINITE;

}

break;

}

}


IDirectInputDevice::SetProperty

HRESULT SetProperty(

LPDIRECTINPUTDEVICE lpDirectInputDevice,

REFGUID rguid,

LPCDIPROPHEADER pdiph);

デバイスの挙動を定義するプロパティをセットする。セット可能なプロパティには入力バッファ・サイズや軸モードなどがある。これらのプロパティの現在値は、IDirectInputDevice::GetPropertyメソッドの呼び出しで取得できる。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

rguidProp

セットされるプロパティの識別子。あらかじめ定義されているDIPROP_*値のいずれか、あるいはプロパティを識別するGUIDへのポインタ(C++の場合は参照) 。

以下のプロパティが入力デバイスに対してあらかじめ定義されている。

DIPROP_AXISMODE

DIPROP_BUFFERSIZE

これらのプロパティそれぞれの詳細については、構造体および定数の節で個々のプロパティ記述を参照すること。

pdiph

プロパティに依存する構造体のDIPROPHEADER部を指し示す。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

DI_PROPNOEFFECT = S_FALSE: 操作は正常に終了したが無効である。たとえば、軸が存在しないデバイスで軸モードを変更するとこの値を返す。

DIERR_INVALIDPARAM = E_INVALIDARG:  pdiphパラメータが有効なポインタでないか、dwHowフィールドが無効か、あるいはdwHowがDIPH_DEVICEにセットされていながらdwObjフィールドが0でない。

DIERR_OBJECTNOTFOUND:  指定されたオブジェクトが存在しない。

DIERR_UNSUPPORTED = E_NOTIMPL:デバイスまたはオブジェクトがプロパティをサポートしていない。


IDirectInputDevice::Unacquire

HRESULT Unacquire(

LPDIRECTINPUTDEVICE lpDirectInputDevice);

デバイスへのアクセスを解放する。

lpDirectInputDevice

このメンバが呼び出されたDirectInputデバイス・オブジェクトを指し示す。

返値

COMエラーコードを返す。以下のエラーコードは返されるコードのすべてとは限らない。

DI_OK = S_OK: 操作は正常に終了した。

S_FALSE: オブジェクトは現在認識されていない。以前に入力を失ったためである可能性がある。これは正常コードであることに注意。


構造体


DIDATAFORMAT

typedef struct {

    DWORD dwSize;

    DWORD dwObjSize;

    DWORD dwFlags;

    DWORD dwDataSize;

    DWORD dwNumObjs;

    LPDIOBJECTDATAFORMAT rgodf;

} DIDATAFORMAT;

IDirectInputDevice::SetDataFormatメソッドが、デバイスのデータ・フォーマットをセットするのに用いる。通常はアプリケーションがDIDATAFORMAT構造体を作成する必要はなく、あらかじめグローバルとして定義されているデータ、 c_dfDIMouseあるいはc_dfDIKeyboardのいずれかを用いることができる。

dwSize

DIOBJECTDATAFORMAT構造体のサイズ。

dwObjSize

DIDATAOBJECTFORMAT構造体のサイズ。

dwFlags

データ・フォーマットの他の属性を記述するフラグ。

以下のフラグが定義されている。

DIDF_RELAXIS: 軸を相対モードにセットする。このフラグをデータ・フォーマットでセットすることは、 IDirectInputDevice::SetPropertyを介して手作業で軸モードプロパティをセットすることと同等である。このフラグをDIDF_ABSAXISと組み合わせることはできない。

DIDF_ABSAXIS: 軸を絶対モードにセットする。このフラグをデータ・フォーマットでセットすることは、 IDirectInputDevice::SetPropertyを介して手作業で軸モードプロパティをセットすることと同等である。このフラグをDIDF_RELAXISと組み合わせることはできない。

dwDataSize

デバイスが返すデバイス・データのサイズ。この値は4の倍数でなければならず、オブジェクトリストで指定されているオブジェクトすべてについてdwOfs値を越えていなければならない。

dwNumObjs

rgodf配列におけるオブジェクト数。

rgodf

DIOBJECTDATAFORMAT構造体の配列へのポインタで、それぞれの構造体はあるオブジェクト・データがデバイス・データにおいてどのように通知されるべきかを記述している。同じ場所にふたつの異なる情報が置かれているか、または同一の情報が2ヶ所に置かれていると、rgodfはエラーとなる。

例

以下の宣言では、2軸（絶対座標で通知される）およびふたつのボタンを利用するアプリケーションで用いられるデータ・フォーマットをセットしている。

// アプリケーションは以下の構造体を用いてデバイス・データを読み込むと仮定する

typedef struct MYDATA {

LONG  lX;                   // X軸

LONG  lY;                   // Y軸

BYTE  bButtonA;             // ボタン

BYTE  bButtonB;             // 別のボタン

BYTE  bPadding[2];          // サイズがdwordの倍数でなければならない

} MYDATA;

// そして以下のデータ・フォーマットを用いることができる

DIOBJECTDATAFORMAT rgodf[] = {

  { &GUID_XAxis,    FIELD_OFFSET(MYDATA, lX),       0,   DIDFT_AXIS | DIDFT_ANYINSTANCE, },

  { &GUID_YAxis,    FIELD_OFFSET(MYDATA, lY),       0,   DIDFT_AXIS | DIDFT_ANYINSTANCE, },

  { &GUID_Button,   FIELD_OFFSET(MYDATA, bButtonA), 0, DIDFT_BUTTON | DIDFT_ANYINSTANCE, },

  { &GUID_Button,   FIELD_OFFSET(MYDATA, bButtonB), 0, DIDFT_BUTTON | DIDFT_ANYINSTANCE, },

};

#define numObjects (sizeof(rgodf) / sizeof(rgodf[0]))

DIDATAFORMAT df = {

sizeof(DIDATAFORMAT),       // この構造体

sizeof(DIOBJECTDATAFORMAT), // オブジェクト・データ・フォーマットのサイズ

DIDF_ABSAXIS,               // 絶対軸座標

sizeof(MYDATA),             // デバイス・データサイズ

numObjects,                 // オブジェクト数

rgodf,                      // これで終わり

};


DIDEVCAPS

typedef struct {

    DWORD dwSize;

    DWORD dwDevType;

    DWORD dwFlags;

    DWORD dwAxes;

    DWORD dwButtons;

    DWORD dwPOVs;

} DIDEVCAPS;

IDirectInputDevice::GetCapabilitiesメソッドにより用いられ、デバイスのプロパティを返す。

dwSize

構造体のサイズをバイトで指定する。IDirectInputDevice::GetCapabilitiesを呼び出す前に初期化しなければならない。

dwDevType

デバイス・タイプ指定子。このフィールドの記述については、DirectInputデバイス・タイプ記述コードを参照すること。

dwFlags

デバイスに関連するフラグ。以下のフラグが定義されている。

DIDC_ATTACHED: デバイスは物理的に接続されている。

DIDC_POLLEDDEVICE: デバイスは割り込み駆動型ではなくポーリング型である。データを得るためにはアプリケーションが明示的にIDirectInputDevice::GetDeviceStateを呼び出さなければならない。バッファリングおよびイベント通知は効果がない。

dwAxes

デバイス上で利用可能な軸の数を指定する。

dwButtons

デバイス上で利用可能なボタンの数を指定する。

dwPOVs

デバイス上で利用可能な視点コントローラの数を指定する。DirectInputバージョン3.0では利用されない。


DIDEVICEINSTANCE

typedef struct {

    DWORD dwSize;

    GUID guidInstance;

    GUID guidProduct;

    DWORD dwDevType;

    TCHAR tszInstanceName[MAX_PATH];

    TCHAR tszProductName[MAX_PATH];

} DIDEVICEINSTANCE;

IDirectInput::EnumDevicesおよび IDirectInputDevice::GetDeviceInfoメソッドにより用いられ、特定のデバイス・インスタンスに関する情報を返す。

dwSize

構造体のサイズをバイト数で示す。

guidInstance

一意的な識別子で、デバイスのインスタンスを識別する。アプリケーションはこのインスタンスGUIDを設定ファイルに保存し、後に利用できる。インスタンスGUIDはマシン固有であり、あるマシンから得られたインスタンスGUIDは別のマシンのインスタンスGUIDとは無関係である。

guidProduct

製品を識別する一意的な識別子。この識別子はデバイスの製造会社が定める。

dwDevType

デバイス・タイプ指定子。このフィールドの記述については、DirectInputデバイス・タイプ記述コードを参照すること。

tszProductName[MAX_PATH]

製品のニックネーム。たとえば、� Frobozz Industries SuperStick 5X"。

tszInstanceName[MAX_PATH]

インスタンスのニックネーム。たとえば、�Joystick 1"。


DIDEVICEOBJECTDATA

typedef struct {

    DWORD dwOfs;

    DWORD dwData;

    DWORD dwTimeStamp;

    DWORD dwSequence;

} DIDEVICEOBJECTDATA;

IDirectInputDevice::GetDeviceDataメソッドにより用いられ、バッファ・デバイス情報そのものを返す。

dwOfs

データが通知されるオブジェクトの現在のデータ・フォーマットへのオフセット。言い換えると、IDirectInputDevice::GetDeviceState を介してデータが得られたときdwDataが格納された場所である。

あらかじめ定義されているデータ・フォーマットに対し、dwOfsフィールドは次のようになる。

デバイスがマウスとしてアクセスされている場合、DIMOFS_*値のひとつ。

デバイスがキーボードとしてアクセスされている場合、DIK_*値のひとつ。

カスタムデータ・フォーマットがセットされている場合、カスタムデータ・フォーマットに対する相対オフセット。

dwData

デバイスから得られたデータ。このデータのフォーマットはデバイスのタイプに依存するが、どんな場合にもデータはそのままの形式で通知される。

DIDFT_AXIS: デバイスが相対軸モードである場合、相対軸運動が通知される。デバイスが絶対軸モードである場合、絶対軸座標が通知される。

DIDFT_BUTTON: dwDataの下位バイトのみが意味を持つ。ボタンが押されると下位バイトの上位ビットがセットされ、ボタンが離されるとクリアされる。

dwTimeStamp

ミリ秒単位で動くティック・カウンタで、これに合わせてイベントが生成される。現在のシステムのティック・カウンタは、 GetTickCountシステム関数を呼び出して得る。この値はおよそ50日で一巡することに注意。

dwSequence

このイベントのDirectInput順序番号。すべてのDirectInputイベントには増加する順序番号が割り当てられている。これにより、異なるデバイスからのイベントを時系列的にソートできる。この値は一巡すると元に戻るので、ふたつの順序番号を比較する際には注意を要する。 DISEQUENCE_COMPAREマクロを用いてこの比較を安全に実行することができる。


DIDEVICEOBJECTINSTANCE

typedef struct {

    DWORD dwSize;

    GUID guidType;

    DWORD dwOfs;

    DWORD dwType;

    DWORD dwFlags;

    TCHAR tszName[MAX_PATH];

} DIDEVICEOBJECTINSTANCE;

IDirectInputDevice::EnumObjectsメソッドにより用いられ、デバイス上の特定のオブジェクト(軸、ボタンなど)に関する情報をコールバック関数に返す。

dwSize

構造体のサイズをバイト数で示す。この構造体において妥当なフィールド数を知るために、アプリケーションがこの値をチェックすることがある。DirectInput 3.0については、この値はsizeof(DIDEVICEOBJECTINSTANCE)となる。将来バージョンのDirectInputではより大きな値を返す可能性もある。

guidType

オブジェクトのタイプを示す識別子。このフィールドはオプションである。存在する場合は以下の値のうちのひとつである。

GUID_XAxis: コントローラの水平軸。たとえばマウスの水平移動を示すこともある。

GUID_YAxis: コントローラの垂直軸。たとえばマウスの垂直移動を示すこともある。

GUID_ZAxis: コントローラの前後の軸。たとえばマウスのZ輪の回転を示すこともある。

GUID_Button: マウスのボタン。

GUID_Key: キーボードのキー。

他のオブジェクト・タイプも今後定義される可能性がある(たとえば、GUID_Fire、GUID_Throttle、GUID_SteeringWheel）。

dwOfs

このオブジェクトが通知するデータを最も効率よく得られる、データ・フォーマット内でのオフセット。カスタムデータ・フォーマットを構築するアプリケーションに対してだけ有意である。ほとんどのアプリケーションではこの値は使用されない。

dwType

オブジェクトを記述するデバイス・タイプ指定子。オブジェクト・タイプ(軸、ボタンなど)を記述するDIDFT_*フラグの組み合わせで、上位バイトにはオブジェクト・インタンス番号が入る。オブジェクト・インスタンス番号を抽出するにはDIDFT_GETINSTANCEマクロを用いる。

dwFlags

現時点ではフラグは何も定義されていない。

tszName[MAX_PATH]

オブジェクトの名称。たとえば�X-Axis" や �Right Shift"。


DIMOUSESTATE

typedef struct {

    LONG lX;

    LONG lY;

    LONG lZ;

    BYTE rgbButtons[4];

} DIMOUSESTATE;

IDirectInputDevice::GetDeviceStateメソッドにより用いられ、マウス・デバイスあるいはマウスとしてアクセスされる非マウス・デバイスの状態を返す。c_dfDIMouseデータ・フォーマットを渡してIDirectInputDevice::SetDataFormatを呼び出し、マウス・スタイルのアクセスができるようデバイスを準備しておかなければならない。

マウスは相対軸デバイスであるため、マウスの軸の絶対軸位置は単に相対移動の累計であることに注意。その結果、他の絶対軸位置と比較するときを除いて、絶対軸位置の値は無意味である。

lX

マウスのx軸に関する情報。デバイスが相対軸モードである場合、マウスのx軸方向の変位。デバイスが絶対軸モードである場合、マウスのx軸方向の絶対位置。

lY

マウスのy軸に関する情報。デバイスが相対軸モードである場合、マウスのy軸方向の変位。デバイスが絶対軸モードである場合、マウスのy方向の絶対位置。

lZ

マウスのz軸に関する情報。デバイスが相対軸モードである場合、マウスのz軸方向の変位。デバイスが絶対軸モードである場合、マウスのz軸方向の絶対位置。

マウスにz軸がなければ、この値は0となる。

rgbButtons[4]

ボタンの状態の配列。相当するボタンが押されている場合、上位ビットがセットされる。


DIOBJECTDATAFORMAT

typedef struct {

    const GUID * pguid;

    DWORD dwOfs;

    DWORD dwType;

    DWORD dwFlags;

} DIOBJECTDATAFORMAT;

IDirectInputDevice::SetDataFormatメソッドが、デバイス内の単一オブジェクトに対してデータ・フォーマットをセットするのに用いる。データ・フォーマットは複数のDIOBJECTDATAFORMAT構造体から構成され、各オブジェクト(軸、ボタンなど)に対してひとつの構造体が当てられる。これらの構造体の配列は、IDirectInputDevice::SetDataFormatに渡されるDIDATAFORMAT構造体が持つ。通常はアプリケーションがDIOBJECTDATAFORMAT構造体の配列を作成する必要はなく、この構造体に対し設定があらかじめ定義されているc_dfDIMouseまたは c_dfDIKeyboardのいずれかを用いる。

pguid

軸、ボタンあるいは他の入力ソースに対する識別子。データ・フォーマットを要求する際にこのフィールドをNULLにセットすると、どのようなタイプのオブジェクトでもいいという意味になる。

dwOfs

入力ソースに対するデータが格納されるデータ・パケット内でのオフセットで、軸のようなDWORDサイズのデータについては4の倍数でなければならない。もしくは、ボタンに対して並べられたバイト・アラインメントの値。

dwType

オブジェクトを記述するデバイス・タイプ指定子。これは、オブジェクトタイプ(軸、ボタンなど)を記述するDIDFT_*フラグの組み合わせで、上位バイトにはオブジェクト・インタンス番号が入る。データ・フォーマットを要求する際に、任意のインスタンスが許容されることを示すために、インスタンス部分をDIDFT_ANYINSTANCEにセットすることができる。

dwFlags

現時点ではフラグは何も定義されていない。このフィールドは0でなければならない。

例

次のオブジェクト・データ・フォーマット指定では、DirectInputが最初の利用可能な軸を選択し、値をデバイス・データとしてオフセット4にDWORDで通知する。

DIOBJECTDATAFORMAT dfAnyAxis = {

0,                      // ワイルドカード

4,                      // オフセット

DIDFT_AXIS | DIDFT_ANYINSTANCE, // どの軸でもかまわない

0,                      // 0でなければならない

};

次のオブジェクト・データ・フォーマット指定では、デバイスのX軸をデバイス・データとしてオフセット12にDWORDで格納する。デバイスに複数のX軸が存在する場合、最初に利用可能なものが選択される。

DIOBJECTDATAFORMAT dfAnyXAxis = {

&GUID_XAxis,            // X軸でなければならない

12,                     // オフセット

DIDFT_AXIS | DIDFT_ANYINSTANCE, // どのX軸でもかまわない

0,                      // 0でなければならない

};

次のオブジェクト・データ・フォーマット指定では、 DirectInputが最初の利用可能なボタンを選択し、その値のBYTEの上位ビットをデバイス・データとしてオフセット16に通知する。

DIOBJECTDATAFORMAT dfAnyButton = {

0,                      // ワイルドカード

16,                     // オフセット

DIDFT_BUTTON | DIDFT_ANYINSTANCE, // どのボタンでもかまわない

0,                      // 0でなければならない

};

次のオブジェクト・データ・フォーマット指定では、 DirectInputが最初の利用可能なﾒFire�ボタンを選択し、その値のBYTEの上位ビットをデバイス・データとしてオフセット17に通知する。

デバイスにﾒFire�ボタンが存在しない場合、このデータ・フォーマットはセット不可能である。

DIOBJECTDATAFORMAT dfAnyButton = {

&GUID_FireButton,       // オブジェクトタイプ

17,                     // オフセット

DIDFT_BUTTON | DIDFT_ANYINSTANCE, // どのボタンでもかまわない

0,                      // 0でなければならない

};

次のオブジェクト・データ・フォーマット指定では、 デバイスのボタン0をデバイス・データとしてオフセット18に格納されるBYTEの上位ビットとして通知する。

デバイスにボタン0が存在しない場合、このデータ・フォーマットはセット不可能である。

DIOBJECTDATAFORMAT dfButton0 = {

0,                      // ワイルドカード

18,                     // オフセット

DIDFT_BUTTON | DIDFT_MAKEINSTANCE(0), // ボタン0

0,                      // 0でなければならない

};


DIPROPDWORD

typedef struct {

    DIPROPHEADER 	diph;

    DWORD 	dwData;

} DIPROPDWORD;

DWORDプロパティへのアクセスに用いられる汎用構造体。

diph

以下のように初期化しておかなければならない。

dwSize = (DIPROPDWORD)のサイズ。

dwHeaderSize = (DIPROPHEADER)のサイズ。

dwObj = オブジェクト識別子。

dwHow = dwObjの解釈方法。

dwData

SetPropertyでは、この構造体にはこのプロパティにセットされる値が含まれる。GetPropertyでは、この構造体はプロパティの値を受け取る。


DIPROPHEADER

typedef struct {

    DWORD 	dwSize;

    DWORD	dwHeaderSize;

    DWORD 	dwObj;

    DWORD	dwHow;

} DIPROPHEADER;

すべてのプロパティ構造体の先頭に置かれる汎用構造体。

dwSize

含んでいる構造体のサイズ。

dwHeaderSize

DIPROPHEADER構造体のサイズ。

dwObj

プロパティがアクセスされるオブジェクトを識別する。

dwHowフィールドがDIPH_DEVICEである場合は0。

dwHowフィールドがDIPH_BYOFFSETである場合、プロパティがアクセスされようとしているオブジェクトの現在のデータ・フォーマットへのオフセット。

dwHowフィールドがDIPH_BYIDである場合、前回のIDirectInputDevice::EnumObjectsの呼び出しから返されたDIDEVICEOBJECTINSTANCEのdwTypeフィールドに返されるオブジェクト・タイプまたはインスタンス識別子。

dwHow

dwObjの解釈方法を指定する。


DIPROPRANGE

typedef struct {

    DIPROPHEADER diph;

    LONG lMin;

    LONG lMax;

} DIPROPRANGE;

DIPROP_RANGEプロパティが、軸などのオブジェクトの範囲のセットや取得に用いる。デバイスの範囲が無制限である場合、通知される範囲はlMin = DIPROPRANGE_NOMINおよびlMax = DIPROPRANGE_NOMAXとなる。範囲が無制限であるデバイスでは回り込みが行われることに注意。

diph

以下のように初期化しておかなければならない。

dwSize = (DIPROPRANGE)のサイズ。

dwHeaderSize = (DIPROPHEADER)のサイズ。

dwObj = オブジェクト識別子。

dwHow = dwObjの解釈方法。

lMin

範囲の下限。

lMax

範囲の上限。


JOYCAPS

typedef struct {

    WORD wMid;

    WORD wPid;

    CHAR szPname[MAXPNAMELEN];

    UINT wXmin;

    UINT wXmax;

    UINT wYmin;

    UINT wYmax;

    UINT wZmin;

    UINT wZmax;

    UINT wNumButtons;

    UINT wPeriodMin;

    UINT wPeriodMax;

\\  以下のメンバは以前のバージョンのWindowsでは存在しなかった

    UINT wRmin;

    UINT wRmax;

    UINT wUmin;

    UINT wUmax;

    UINT wVmin;

    UINT wVmax;

    UINT wCaps;

    UINT wMaxAxes;

    UINT wNumAxes;

    UINT wMaxButtons;

    CHAR szRegKey[MAXPNAMELEN];

    CHAR szOEMVxD[MAXOEMVXD];

} JOYCAPS;

指定されたジョイスティックの機能に関する情報。

wMid

製造者識別子。

wPid

製品識別子。

szPname

ジョイスティックの製品名が含まれる、NULLで終わる文字列。

wXmin、wXmax

x座標値の最小値および最大値。

wYmin、wYmax

y座標値の最小値および最大値。

wZmin、wZmax

z座標値の最小値および最大値。

wNumButtons

ジョイスティックのボタン数。

wPeriodMin、wPeriodMax

アプリケーションがジョイスティックを捕捉したときにサポートされるポーリング周期の最小値および最大値。

wRmin、wRmax

ラダー値の最小値および最大値。ラダーは4番目の運動軸である。

wUmin、wUmax

u座標(5番目の軸)値の最小値および最大値。

wVmin、wVmax

v座標(6番目の軸)値の最小値および最大値。

wCaps

ジョイスティックの機能。以下のフラグは、ジョイスティックが持ち得る個々の機能を定義する。

JOYCAPS_HASPOV

	ジョイスティックは視点情報を持つ。

JOYCAPS_HASR

	ジョイスティックはラダー(4番目の軸)情報を持つ。

JOYCAPS_HASU

	ジョイスティックはu座標(5番目の軸)情報を持つ。

JOYCAPS_HASV

	ジョイスティックはv座標(6番目の軸)情報を持つ。

JOYCAPS_HASZ

	ジョイスティックはz座標情報を持つ。

JOYCAPS_POV4DIR

	ジョイスティックの 視点は離散値をサポートする（中央、前、後、左および右）。

JOYCAPS_POVCTS

	ジョイスティックの視点は連続的な方位角をサポートする。
wMaxAxes

ジョイスティックがサポートする軸の最大数。

wNumAxes

ジョイスティックにより現在使用されている軸数。

wMaxButtons

ジョイスティックがサポートするボタンの最大数。

szRegKey

ジョイスティックに対するレジストリ・キーを含む、NULLで終わる文字列。

szOEMVxD

ジョイスティックドライバOEMを識別する、NULLで終わる文字列。

参照　joyGetDevCaps


JOYINFOEX

typedef struct joyinfoex_tag {

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwXpos;

    DWORD dwYpos;

    DWORD dwZpos;

    DWORD dwRpos;

    DWORD dwUpos;

    DWORD dwVpos;

    DWORD dwButtons;

    DWORD dwButtonNumber;

    DWORD dwPOV;

    DWORD dwReserved1;

    DWORD dwReserved2;

} JOYINFOEX;

ジョイスティックの位置、視点の位置およびボタンの状態に関する拡張情報。

dwSize

この構造体のサイズをバイト数で示す。

dwFlags

この構造体に格納された情報が有効であるかを示すフラグ｡有効な情報を含まない要素は0にセットされる｡以下のフラグが定義されている。

JOY_RETURNALL

	JOY_RETURNRAWDATAを除くすべてのJOY_RETURN値をセットすることと同等である｡

JOY_RETURNBUTTONS

	dwButtons要素には、各ジョイスティックのボタンの状態に関する有効な情報が含まれる。

JOY_RETURNCENTERED

	各軸の変位の中央値にジョイスティックのニュートラル位置を置く。

JOY_RETURNPOV

	dwPOV要素には、離散的な単位を用いて示される視点コントロールに関する有効な情報が含まれる。

JOY_RETURNPOVCTS

	The dwPOV要素には、連続的で100分の1度を単位として示される視点コントロールに関する有効な情報が含まれる。

JOY_RETURNR

	The dwRpos要素には、有効なラダーペダル情報が含まれる。これは4番目の軸が存在することを示す｡

JOY_RETURNRAWDATA

	キャリブレーションされていないジョイスティックの指示値がこの構造体に格納されていることを示す｡

JOY_RETURNU

	dwUpos要素には、ジョイスティックの5番目の軸が使用可能であれば、この軸に関する有効なデータが含まれる。そうでない場合は0が返される。

JOY_RETURNV

	dwVpos要素には、ジョイスティックの6番目の軸が使用可能であれば、この軸に関する有効なデータが含まれる。そうでない場合は0が返される。

JOY_RETURNX

	dwXpos要素には、ジョイスティックのx座標に関する有効なデータが含まれる。

JOY_RETURNY

	dwYpos 要素には、ジョイスティックのy座標に関する有効なデータが含まれる。

JOY_RETURNZ

	dwZpos 要素には、ジョイスティックのz座標に関する有効なデータが含まれる。

JOY_USEDEADZONE

	ジョイスティックのニュートラル位置の範囲を拡張し、この範囲をデッドゾーンと呼ぶ。ジョイスティックドライバはデッドゾーン内のすべての位置に対して定数値を返す。
以下のフラグは、ジョイスティックをキャリブレーションするためのデータを提供し、カスタム・キャリブレーション・アプリケーションを対象とするものである。

JOY_CAL_READ3

	x、y、z座標を読み込み、そのままの値をdwXpos、dwYpos、dwZpos要素にそれぞれ格納する。

JOY_CAL_READ4

	ラダー情報およびx、y、z座標を読み込み、そのままの値をdwRpos、dwXpos、dwYpos、dwZpos要素にそれぞれ格納する。

JOY_CAL_READ5

	ラダー情報およびx、y、z、u座標を読み込み、そのままの値をdwRpos、dwXpos、dwYpos、dwZpos、dwUpos要素にそれぞれ格納する。

JOY_CAL_READ6

	ジョイスティックミニドライバが存在し情報を提供している場合は、v軸データをそのまま読み込む。そうでなければ0を返す。

JOY_CAL_READALWAYS

	ドライバがデバイスを検知しない場合であっても、ジョイスティックのポートを読み込む。

JOY_CAL_READRONLY

	ジョイスティックミニドライバが存在しデータを提供する場合はラダー情報を読み込み、そのままの値をdwRpos要素に格納する。そうでなければ0を返す。

JOY_CAL_READUONLY

	ジョイスティックミニドライバが存在しデータを提供する場合はu座標を読み込み、そのままの値をdwUpos要素に格納する。そうでなければ0を返す。

JOY_CAL_READVONLY

	ジョイスティックミニドライバが存在しデータを提供する場合はv座標を読み込み、そのままの値をdwVpos要素に格納する。そうでなければ0を返す。

JOY_CAL_READXONLY

	x座標を読み込み、そのままの値をdwXpos要素に格納する。

JOY_CAL_READXYONLY

	x、y座標を読み込み、そのままの値をdwXpos、dwYpos要素にそれぞれ格納する。

JOY_CAL_READYONLY

	y座標を読み込み、そのままの値をdwYpos要素に格納する。

JOY_CAL_READZONLY

	z座標を読み込み、そのままの値をdwZpos要素に格納する。
dwXpos、dwYpos、dwZpos

それぞれ、現在のx座標、y座標、z座標。

dwRpos

ジョイスティックの4番目の軸であるラダーの現在の位置。

dwUpos、dwVpos

それぞれ、5番目、6番目の軸の位置。

dwButtons

32のジョイスティックボタンの現在の状態。この要素の値はJOY_BUTTONnflagsの任意の組み合わせにセットされる。ここでnは1から32までの値である｡それぞれの値は押されているボタンに相当する。

dwButtonNumber

現在押されているボタン要素。

dwPOV

現在の視点コントロールの位置。この要素に対する値は0から35,900までの範囲内にある。これらの値は、各視角を度単位で表し100倍したものである。

dwReserved1、dwReserved2

予約されているため使用しない。

dwSize要素の値は、 joyGetPosEx関数に渡される際には、この要素の構造体に対するバージョン番号を識別するためにも用いられる。

視点コントロールを持つデバイスのほとんどは、5つの位置しか持たない。 JOY_RETURNPOVフラグがセットされているとき、これらの位置は以下のJOY_POV定数を用いて通知される｡

視点に関する位置	注釈
JOY_POVBACKWARD	視点ハットが後ろ側にある。値18,000は180.00度の方向を表す｡
JOY_POVCENTERED	視点ハットはニュートラル位置にある。値-1は、視点ハットが角度を通知していないことを意味する。
JOY_POVFORWARD	視点ハットは前側にある。値0は0.00度の方向を表す。
JOY_POVLEFT	視点ハットは左側にある。値27,000は270.00度の方向を表す。
JOY_POVRIGHT	視点ハットは右側にある。値9,000は90.00度の方向を表す。
Windows 95のデフォルトのジョイスティックドライバでは、現時点ではこれらの5 つの離散的な方向がサポートされている。定義された視点の値しかアプリケーションで用いることができない場合､JOY_RETURNPOVフラグを用いなければならない｡他の値の角度をアプリケーションで用いることができる場合､ 利用可能であれば連続的なデータをJOY_RETURNPOVCTSフラグを用いて取得しなければならない｡またJOY_RETURNPOVCTSフラグは、JOY_RETURNPOVフラグとともに用いられるJOY POV定数もサポートしている。

参照　joyGetPosEx


グローバル変数


c_dfDIKeyboard

あらかじめ定義されているDIDATAFORMAT構造体で、キーボード・デバイスを記述する。このオブジェクトはDINPUT.LIBライブラリファイルで与えられている。

この構造体へのポインタはIDirectInputDevice::SetDataFormatへ渡され、そのデバイスがキーボード形式でアクセスされることを示す。


c_dfDIMouse

あらかじめ定義されているDIDATAFORMAT構造体で、マウス・デバイスを記述する。このオブジェクトはDINPUT.LIBライブラリファイルで与えられている。

この構造体へのポインタはIDirectInputDevice::SetDataFormatへ渡され、そのデバイスがマウス形式でアクセスされることを示す。


GUID_SysKeyboard

あらかじめ定義されているDirectInputのインスタンスGUIDで、デフォルトのシステムキーボードをつねに参照する。この値は、システムキーボードに対するインターフェイスを作成するためにIDirectInput::CreateDeviceへ渡されることもある。


GUID_SysMouse

あらかじめ定義されているDirectInputのインスタンスGUIDで、デフォルトのシステムマウスをつねに参照する。この値は、システムマウスに対するインターフェイスを作成するためにIDirectInput::CreateDeviceへ渡されることもある。


定数


DIPROP_AXISMODE

あらかじめ定義されているプロパティで、軸データモードのセットあるいは取得に用いられる。この設定は、特定のオブジェクトに対してというよりはデバイス全体に適用されるので、dwHowフィールドはDIPH_DEVICEでなければならない。

このプロパティはDIPROPDWORD構造体を用いる。DIPROPDWORD構造体のpdiphフィールドはDIPROPHEADER構造体へのポインタでなければならない。dwDataフィールドは軸モードを含むか、あるいは受け取ることになる。

DIPROPHEADER構造体のdwObjフィールドは0でなければならず、これはこのプロパティ設定が特定のオブジェクトではなくデバイス全体に適用されることを示す。dwSizeフィールドにはDIPROPDWORD構造体のサイズをセットしなければならない。

DIPROPDWORD構造体のdwDataフィールドは以下の値のひとつ。

DIPROPAXISMODE_ABS: 絶対座標で軸位置を通知する。軸移動は時間について累計される。

DIPROPAXISMODE_REL: 軸位置を相対座標で通知する。軸移動は、前回軸位置を要求したときとの差として通知される。


DIPROP_BUFFERSIZE

あらかじめ定義されているプロパティで、デバイス入力バッファサイズのセットや取得に用いられる。

この設定は、特定のオブジェクトに対してというよりはデバイス全体に適用されるので、dwHowフィールドはDIPH_DEVICEでなければならない。

このプロパティはDIPROPDWORD構造体を用いる。DIPROPDWORD構造体のpdiphフィールドはDIPROPHEADER構造体へのポインタでなければならない。dwDataフィールドはバッファサイズを含むか、あるいは受け取ることになる。

DIPROPHEADER構造体のdwObjフィールドは0でなければならず、これはこのプロパティ設定が特定のオブジェクトではなくデバイス全体に適用されることを示す。dwSizeフィールドにはDIPROPDWORD構造体のサイズをセットしなければならない。

アプリケーションがデバイスからバッファ・データを読みとらない場合には、DIPROPDWORD構造体のdwDataフィールドが0にセットされる。または、用いるバッファのサイズを示すために0以外の値もとりうる。

バッファサイズをセットする際に、dwDataが示すバッファサイズがデバイスでサポートするには大きすぎる場合、とりうる最大のバッファサイズにセットされる。必要なバッファサイズがセットされたかを知るには、バッファサイズプロパティを取得し、その結果をセットしようとした値と比較しなければならない。


DIPROP_GRANULARITY

あらかじめ定義されたプロパティで、オブジェクトの最小単位を取得する。

このプロパティはDIPROPDWORD構造体を用いる。DIPROPDWORD構造体のpdiphフィールドはDIPROPHEADER構造体へのポインタでなければならない。dwDataフィールドは最小単位を受け取ることになる。

DIPROPHEADER構造体のdwObjフィールドは、最小単位が取得されるオブジェクトに対する識別子でなければならない。dwSizeフィールドにはDIPROPDWORD構造体のサイズをセットしなければならない。

最小単位の値は、オブジェクトが移動を通知できる最小の距離である。ほとんどの軸オブジェクトの最小単位は1であり、任意の値をとりうることを意味する。これよりも大きい最小単位を持つ軸もある。たとえば、マウス上のZ-回転輪軸の最小単位は20で、通知される位置変化はすべて20の倍数であることを意味する。言い換えると、ユーザがZ-回転輪をゆっくり回転すると、デバイスは位置0、20そして40というように通知する。

これは読み出し専用のプロパティである。


DIPROP_RANGE

あらかじめ定義されているプロパティで、オブジェクトから通知される値の範囲を取得する。

このプロパティはDIPROPRANGE構造体を用いる。DIPROPRANGE構造体のpdiphフィールドはDIPROPHEADER構造体へのポインタでなければならない。

DIPROPHEADER構造体のdwObjフィールドは範囲が取得されるオブジェクトに対する識別子でなければならない。dwSizeフィールドにはDIPROPRANGE構造体のサイズをセットしなければならない。

これは読み出し専用のプロパティである。


DISCL_BACKGROUND

SetCooperativeLevelへのパラメータで、バックグラウンド・アクセスが必要であることを示す。バックグラウンド・アクセスが与えられると、関連のあるウィンドウがアクティブ・ウィンドウでないときも含めデバイスはいつでも認識可能である。

DISCL_FOREGROUNDとDISCL_BACKGROUNDのうちいずれかがIDirectInputDevice::SetCooperativeLevelに渡されなければならない。両方を渡したりいずれも渡さない場合はエラーとなる。現バージョンのDirectInputでは排他的なバックグラウンド・アクセスが許されていないことに注意。


DISCL_EXCLUSIVE

SetCooperativeLevelへのパラメータで、排他的アクセスが必要であることを示す。排他的アクセスが与えられると、デバイスの他のインスタンスは、認識されているデバイスへの排他的アクセスは得られない。しかし、他のアプリケーションが排他的アクセスを得ている場合であっても、デバイスへの非排他的なアクセスはつねに許されていることに注意すること(「排他的」という語はここでは誤った言い回しであるが、DirectDrawにおける類似の概念と比較するために取り上げられている)。

WM_ENTERSIZEMOVEおよび WM_ENTERMENULOOPメッセージを受け取った際に、マウスあるいはキーボード・デバイスを排他モードで認識するアプリケーションはデバイスを解放することを強く推奨する。さもないと、ユーザはメニュー操作やウィンドウの移動・リサイズができなくなる。

DISCL_EXCLUSIVEとDISCL_NONEXCLUSIVEのうちのいずれかをSetCooperativeLevelに渡されなければならない。両方を渡したりいずれも渡さない場合はエラーとなる。現バージョンのDirectInputでは排他的アクセスにはフォアグラウンド・アクセスが必要となる。


DISCL_FOREGROUND

SetCooperativeLevelへのパラメータで、フォアグラウンド・アクセスが必要であることを示す。フォアグラウンド・アクセスが与えられると、関連のあるウィンドウがフォアグラウンドでアクティブでなくなるとデバイスは自動的に解放される。

DISCL_FOREGROUNDとDISCL_BACKGROUNDのうちいずれかがIDirectInputDevice::SetCooperativeLevelに渡されなければならない。両方を渡したりいずれも渡さない場合はエラーとなる。


DISCL_NONEXCLUSIVE

SetCooperativeLevelへのパラメータで、非排他的アクセスが必要であることを示す。デバイスへのアクセスは、同一のデバイスにアクセスしている他のアプリケーションに干渉しない。

DISCL_EXCLUSIVEとDISCL_NONEXCLUSIVEのうちいずれかがIDirectInputDevice::SetCooperativeLevelに渡されなければならない。両方を渡したりいずれも渡さない場合はエラーとなる。


JOYINFOEXキーボード・デバイス定数

キーボード・デバイス定数はdinput.hに定義されており、キーボード・デバイスのデータパケット(256バイトの配列)内でのオフセットを表している。各オフセットの値は、指定されたデータが格納されている配列要素の相対位置を識別する。そのオフセットの位置にあるデータは、キーボードのキーに対応している。一般に、これらの値はDIDEVICEOBJECTDATA、DIOBJECTDATAFORMAT、あるいはDIDEVICEOBJECTINSTANCE構造体のdwOfsメンバで使用される。また、要素を指定して配列にアクセスする際の添字としても用いられる。

一般的なキーボード・デバイス定数を以下に示す（昇順）。

DIK_ESCAPE	Escキー

DIK_1	1 キー

DIK_2 	2 キー

DIK_3 	3 キー

DIK_4 	4 キー

DIK_5 	5 キー

DIK_6 	6 キー

DIK_7 	7 キー

DIK_8 	8 キー

DIK_9 	9 キー

DIK_0 	0 キー

DIK_MINUS 	メインキーボードの - キー

DIK_EQUALS 	= キー

DIK_BACK 	Backspaceキー

DIK_TAB 	Tabキー

DIK_Q 	Q キー

DIK_W 	W キー

DIK_E 	E キー

DIK_R 	R キー

DIK_T 	T キー

DIK_Y 	Y キー

DIK_U 	U キー

DIK_I 	I キー

DIK_O 	O キー

DIK_P 	P キー

DIK_LBRACKET 	[ キー

DIK_RBRACKET 	] キー

DIK_RETURN 	メインキーボードの Enter キー

DIK_LCONTROL 	左Ctrlキー

DIK_A 	Aキー

DIK_S 	S キー

DIK_D 	D キー

DIK_F 	F キー

DIK_G 	G キー

DIK_H 	H キー

DIK_J 	J キー

DIK_K 	K キー

DIK_L 	L キー

DIK_SEMICOLON 	; キー

DIK_APOSTROPHE 	アポストロフィー (') キー

DIK_GRAVE 	accent grave (`) キー

DIK_LSHIFT 	左Shiftキー

DIK_BACKSLASH 	\ キー

DIK_Z 	Z キー

DIK_X 	X キー

DIK_C 	C キー

DIK_V 	V キー

DIK_B 	B キー

DIK_N 	N キー

DIK_M 	M キー

DIK_COMMA 	, キー

DIK_PERIOD 	メインキーボードの . キー

DIK_SLASH 	メインキーボードの  / キー

DIK_RSHIFT 	右Shiftキー

DIK_MULTIPLY 	テンキーの * キー

DIK_LMENU 	左Altキー

DIK_SPACE 	スペースバー

DIK_CAPITAL 	Caps Lockキー

DIK_F1 	F1 キー

DIK_F2 	F2 キー

DIK_F3 	F3 キー

DIK_F4 	F4 キー

DIK_F5 	F5 キー

DIK_F6 	F6 キー

DIK_F7 	F7 キー

DIK_F8 	F8 キー

DIK_F9 	F9 キー

DIK_F10 	F10キー

DIK_NUMLOCK 	Num Lockキー

DIK_SCROLL 	Scroll Lockキー

DIK_NUMPAD7 	テンキーの7キー

DIK_NUMPAD8 	テンキーの8 キー

DIK_NUMPAD9 	テンキーの 9 キー

DIK_SUBTRACT 	テンキーの - キー

DIK_NUMPAD4 	テンキーの 4 キー

DIK_NUMPAD5 	テンキーの 5 キー

DIK_NUMPAD6 	テンキーの 6 キー

DIK_ADD 	テンキーの + キー

DIK_NUMPAD1 	テンキーの 1 キー

DIK_NUMPAD2 	テンキーの 2 キー

DIK_NUMPAD3 	テンキーの 3 キー

DIK_NUMPAD0 	テンキーの 0 キー

DIK_DECIMAL 	テンキーの . キー

DIK_F11 	F11キー

DIK_F12 	F12キー

DIK_NUMPADENTER	テンキーのEnterキー

DIK_RCONTROL 	右Ctrlキー

DIK_DIVIDE 	テンキーの / キー

DIK_SYSRQ 	SysRqキー

DIK_RMENU 	右Altキー

DIK_HOME 	Homeキー

DIK_UP 	上矢印キー

DIK_PRIOR 	PgUpキー

DIK_LEFT 	左矢印キー

DIK_RIGHT 	右矢印キー

DIK_END 	Endキー

DIK_DOWN 	下矢印キー

DIK_NEXT 	PgDnキー

DIK_INSERT 	Insertキー

DIK_DELETE 	Deletキー

DIK_LWIN 	左Windowsキー

DIK_RWIN 	右Windowsキー

DIK_APPS 	AppMenuキー


マウス・デバイス定数

DIMOFS_BUTTON0

DIMOUSESTATE構造体の先頭に対するマウスボタン0の状態のオフセット。この値は、DIDEVICEOBJECTDATA構造体のdwOfsフィールドとして返され、データがマウスボタン0に適用されることを示す。

DIMOFS_BUTTON1

DIMOUSESTATE構造体の先頭に対するマウスボタン1の状態のオフセット。この値は、DIDEVICEOBJECTDATA構造体のdwOfsフィールドとして返され、データがマウスボタン1に適用されることを示す。

DIMOFS_BUTTON2

DIMOUSESTATE構造体の先頭に対するマウスボタン2の状態のオフセット。この値は、DIDEVICEOBJECTDATA構造体のdwOfsフィールドとして返され、データがマウスボタン2に適用されることを示す。

DIMOFS_BUTTON3

DIMOUSESTATE構造体の先頭に対するマウスボタン3の状態のオフセット。この値は、DIDEVICEOBJECTDATA構造体のdwOfsフィールドとして返され、データがマウスボタン3に適用されることを示す。

DIMOFS_X

DIMOUSESTATE構造体の先頭に対するマウスのx方向の位置のオフセット。この値は、DIDEVICEOBJECTDATA構造体のdwOfsフィールドとして返され、データがマウスのx方向の位置に適用されることを示す。

DIMOFS_Y

DIMOUSESTATE構造体の先頭に対するマウスのy方向の位置のオフセット。この値は、DIDEVICEOBJECTDATA構造体のdwOfsフィールドとして返され、データがマウスのy方向の位置に適用されることを示す。

DIMOFS_Z

DIMOUSESTATE構造体の先頭に対するマウスのz方向の位置のオフセット。この値は、DIDEVICEOBJECTDATA構造体のdwOfsフィールドとして返され、データがマウスのz方向の位置に適用されることを示す。


DirectInputデバイス・タイプ記述コード

DirectInputデバイス・タイプ記述コードはDIDEVICEINSTANCE構造体で用いられる。デバイス・タイプ記述コードの最下位バイトはデバイス・タイプを指定する。

DIDEVTYPE_MOUSE: マウスあるいはマウスに類似したデバイス(トラックボールなど)。

DIDEVTYPE_KEYBOARD: キーボードあるいはキーボードに類似したデバイス。

下位から2番目のバイトはデバイスのサブタイプを指定する。

マウスタイプのデバイスについては、次のサブタイプが定義されている:

DIDEVTYPEMOUSE_UNKNOWN: サブタイプを確定できない。

DIDEVTYPEMOUSE_TRADITIONAL: 伝統的なマウス。

DIDEVTYPEMOUSE_FINGERSTICK: フィンガースティック。

DIDEVTYPEMOUSE_TOUCHPAD: デバイスはタッチパッドである。

DIDEVTYPEMOUSE_TRACKBALL: デバイスはトラックボールである。

キーボードタイプのデバイスについては、次のサブタイプが定義されている:

DIDEVTYPEKEYBOARD_PCXT: IBM PC/XT 83キー キーボード。

DIDEVTYPEKEYBOARD_OLIVETTI: オリベッティ102キー キーボード。

DIDEVTYPEKEYBOARD_PCAT: IBM PC/AT 84キー キーボード。

DIDEVTYPEKEYBOARD_PCENH: IBM PC拡張101/102キーまたはMicrosoftナチュラルキーボード。

DIDEVTYPEKEYBOARD_NOKIA1050: Nokia 1050キーボード。

DIDEVTYPEKEYBOARD_NOKIA9140: Nokia 9140キーボード。

DIDEVTYPEKEYBOARD_NEC98: 日本語NEC PC98キーボード。

DIDEVTYPEKEYBOARD_NEC98LAPTOP: 日本語NEC PC98ラップトップキーボード。

DIDEVTYPEKEYBOARD_NEC98106: 日本語NEC PC98 106キー キーボード。

DIDEVTYPEKEYBOARD_JAPAN106: 日本語106キー キーボード。

DIDEVTYPEKEYBOARD_JAPANAX: 日本語 AXキーボード。

DIDEVTYPEKEYBOARD_J3100: 日本語 J3100キーボード。


DirectInputデータ・フォーマット・タイプ

DirectInputデータ・フォーマット・タイプはデバイスにおける単一オブジェクトの属性を記述する。デバイスにおけるオブジェクトは軸、ボタンあるいは他の入力ソースとなりうる。

DIDFT_ALL

このフラグはIDirectInputDevice::EnumObjectsに対してのみ有効となる。すべてのオブジェクトはタイプに関わらず列挙される。このフラグを他のフラグと組み合わせることができない。

DIDFT_RELAXIS

オブジェクトは相対軸である。相対軸とは、前回通知された位置からの増分量としてデータを通知するものである。相対軸は一般的には無制限の範囲をサポートしている。軸は連続的な数値を通知する必要がない。たとえば、軸はその位置を20の倍数で通知することもあるが、これは軸の最小単位が20であることを示す。軸のDIPROP_GRANULARITYプロパティははその軸の最小単位を通知する。

相対軸デバイスには絶対座標が存在しない。むしろ、通知される絶対座標は単に、デバイスが認識されている間にそのデバイスにより通知される相対座標の合計である。結果として、相対軸オブジェクトから得られた絶対座標は、他の絶対座標と比較される場合のみ意味を持つ。たとえば、ボタンが押されているときにアプリケーションが絶対的値を記録し、ボタンが離されるとそれを取得すると仮定する。このふたつの値の差をとることにより、アプリケーションは、ボタンが押された位置と離された位置との間の距離を計算することができる。

相対軸上で絶対的値の原点をセットしたり取得したりすることは不可能なので、アプリケーションはデバイスを認識した直後に絶対位置を記録するべきである。この値は仮想原点となる。それ以降の呼び出しについてはすべて、この原点を基に絶対位置が考慮される。

DIDFT_ABSAXIS

オブジェクトは絶対軸である。絶対軸とは、絶対位置としてデータを通知するものである。

絶対軸は一般的には有限の範囲をサポートしている。

軸は連続的な数値を通知する必要がない。たとえば、軸はその位置を20の倍数で通知することもあるが、これは軸の最小単位が20であることを示す。軸のDIPROP_GRANULARITYプロパティははその軸の最小単位を通知する。

DIDFT_AXIS

このフラグはIDirectInputDevice::EnumObjectsに対してのみ有効となる。すべての軸は、絶対的・相対的に関わらず列挙される。

DIDFT_PSHBUTTON

オブジェクトはプッシュボタンである。プッシュボタンは、ユーザが押しているときは下がっていると通知され、ユーザが離すと上がっていると通知される。

DIDFT_TGLBUTTON

オブジェクトはトグルボタンである。トグルボタンはユーザが押しているときには下がっていると通知され、次にユーザがボタンを押すまでは、押されていると通知され続ける。

DIDFT_BUTTON

オブジェクトはプッシュボタンかトグルボタンである。


返値

エラーは負の値で表され、組み合わせることはない。この表では、すべてのDirectInput関数により返されうるエラーを列挙してある。各関数が返しうるエラーコードのリストについては、個々の関数の注釈を参照すること。

JOYERR_NOCANDO

	ジョイスティックドライバはレジストリからのデバイス情報を更新できない。

JOYERR_NOERROR

	要求は正常終了した。

JOYERR_REGISTRYNOTVALID

	レジストリのひとつ以上のジョイスティックエントリに無効なデータが含まれる。

JOYERR_UNPLUGGED

	指定されたジョイスティックはコンピュータに接続されていない。

MMSYSERR_BADDEVICEID

	指定されたジョイスティックの識別子が無効である｡

MMSYSERR_INVALPARAM

	無効なパラメータが渡された。

MMSYSERR_NODRIVER

	ジョイスティックドライバが存在しない。


DirectSetup について

DirectSetupは、 簡単なアプリケーション・プログラミング・インターフェース(API)で、１度呼び出すだけでDirectX� 3 のコンポーネントをインストールできる。DirectX 3は複雑なプロダクトなので、インストールも複雑な作業を要する。したがってDirectX 3を手作業でインストールするべきではない。

さらに、DirectSetupを使用することで、DirectPlayLobbyオブジェクトを用いるアプリケーションに必要なレジストリ情報を自動的にインストールできる。このレジストリ情報は、DirectPlayLobbyオブジェクトがアプリケーションを起動する際に必要となる。

DirectSetupは３つのAPI関数を備えているが、そのうちアプリケーション開発者にとって有益なのはふたつだけである。それ以外のひとつ、DirectXDeviceDriverSetupは、DirectXデバイス・ドライバをインストールしようとする人のためのもので、このマニュアルでは言及しない。


DirectSetupの概要

このセクションでは、DirectSetupのコンポーネントに関する一般的な情報を述べる。

・DirectXSetup関数の使用
・DirectXアプリケーションのインストール準備
・AutoPlayの稼動


DirectXSetup関数の使用

DirectXに依存するアプリケーションおよびゲームは、そのシステム・コンポーネントを、通常のアプリケーションのインストールに加えてインストールする。このインストールにはDirectXSetupAPI関数を用いる。この関数は、DirectXのインストール中にディスプレイおよびオーディオ・ドライバを(必要に応じて)更新し、DirectXをサポートする。DirectXSetupは、プロダクトに添付されるDsetup.dllで各アプリケーションに提供されている。DirectSetupの宣言文はDsetup.hにある。

DirectXSetupを使用するアプリケーションは、\Redist\Directxディレクトリの内容のみでなく、Redistディレクトリの全内容を配布しなければならない。DirectXSetupによりDirectDrawｮといった単一のDirectXコンポーネントをインストールできるが、これは推奨できない。なぜならDirectXコンポーネントは相互依存性のある設計になっているので、ディスクスペースの節約にはならないからである。DirectXコンポーネントを１つだけ用いる場合でも、アプリケーションはDirectX全体の機能を配布しなければならない。


DirectX アプリケーションのインストール準備

アプリケーションとDirectXファイルをユーザのシステムにインストールする準備をしたら、続けてセットアップ・プログラムを作成する必要がある。セットアップ・プログラムは、アプリケーションに必要なファイルのリストアップ、必要なディスク容量の決定、適切なDirectXのインストールの3つの作業を行う。そして配布媒体にディレクトリを作成し、アプリケーションの全ファイルおよび付加されたDirectXコンポーネントをこのディレクトリに置く。次にこれらのステップを説明する。

セットアップ・プログラムの作成

アプリケーション・ディレクトリのセットアップ


セットアップ・プログラムの作成

このSDKに添付されているのは、ユーザ用のセットアップ・プログラムの例である。\Dxsdk\Sdk\Samples\SetupディレクトリにあるDinstallという名のセットアップ・プログラムには、Rockemというサンプル・プログラムを選択されたディレクトリにインストールする方法の説明がある。またDirectXSetup関数を使用する具体的な方法の説明もある。

以下のステップでは、ユーザのコンピュータで動作するようにDinstall.cプログラムを修正する方法を示す。

1	エディタでDinstall.cを開く。

2	ユーザのシステム上にインストールしたいアプリケーションのファイル・リストを提供すること。ユーザの用途にあうようにDinstall.cファイルにあるリストを修正するには、ﾓcopy_listﾓを検索し、この構造体に存在するファイル・リストをユーザ用のファイル・リストに変更する。

Dinstallはデフォルト・ディレクトリにファイルをインストールする。アプリケーションのファイルをサブディレクトリにインストールしたい場合は、Dinstall.cを修正する。

3	Dinstall.cプログラムは、アプリケーションを正常にインストールするのに十分なハードディスクの空き容量があるかどうかを判定できない。ただし、ユーザのもつコードを入力すればこの機能を付加することができる。このコードを入力する場所はDinstall.cファイルに2箇所あるが、そこはﾓIND_DISK_MSGﾓを検索すれば探すことができる。

4	DirectXSetupのlpszRootPath パラメータは、配布媒体上のDsetup*.dllファイル(Dsetup.dll、Dsetup6e.dll、Dsetup6j.dll、Dsetupe.dllおよびDsetupj.dll)およびDirectXディレクトリへのパスを指定する。特に理由がない限り、これらのダイナミックリンクライブラリ、およびこのディレクトリは実行用(コンパイル後)Dinstallと同じディレクトリになければならない。これらのすべてのファイルおよびディレクトリが同じディレクトリに存在する場合、lpszRootPathパラメータの値はNULLでよい。これにより、アプリケーションのルートからコンパクトディスクあるいはフロッピーディスク上へファイルが移動する際にパスが変わっても、DirectXSetupは正常に機能することができる。

たとえば、Dinstall.exe、Dsetup*.dllおよびDirectxディレクトリが、テスト段階の間はD:\Funstuffというアプリケーション・ディレクトリにあると仮定する。そして、ファイルをコンパクトディスク上に焼き付ける際に、それらのファイルをルートに置くと仮定する。 lpszRootPath パラメータがﾓ\FUNSTUFFﾓにセットされていると、コンパクトディスクにあるセットアップ・プログラム(Dinstall.exe)は正常に機能しない。しかしlpszRootPath パラメータがNULLにセットされていれば、両方のセットアップ・プログラムが機能する。なぜならば、Dsetup*.dllおよびDirectxディレクトリへのパスはカレント・ディレクトリに存在するからである。

Dinstall.exeがあるディレクトリ以外の場所にDsetup*.dllファイルおよびDirectxディレクトリをおく場合、DirectXSetupに正しいパラメータを渡し、Dsetup.dllを正しくインストールする必要がある。DirectXSetupのlpszRootPath パラメータにはDsetup.dllへのフルパスが含まれなければならない。さらに、LoadLibraryおよびGetProcAddressというWin32ｮの関数をセットアップ・プログラムで用いると、Dsetup.dllの位置を知ることができる。

セットアップ・ダイアログボックスの内容は、Dinstall.rcリソース・ファイルで与えられるデータによって決定される。アプリケーションの名称およびグラフィックスを表示するには、このリソース・ファイルに対して以下の変更を行う。

1	エディタでDinstall.rcを開く。

2	ファイルに含まれるすべてのﾓRockemﾓを検索し、個人のアプリケーション名に変更する。

3	セットアップおよびリブート・ダイアログボックスで表示されるグラフィックスは、リソース・ファイルにおいてはSignon.bmpおよびReboot.bmpである。個人のビットマップ・ファイルにこれらの名称をつけるか、あるいは個人のビットマップの名称に合うようにリソース・ファイルでの名称を変更することができる。

4	実行用Dinstallに対するアイコンはリソース・ファイルにおいてはSetup.icoと呼ばれ、SETUP_ICONで指定される。個人のアイコン・ファイルの名称をSetup.icoとするか、あるいは個人のアイコン・ファイルの名称にあうようにリソース・ファイルにおける名称を変更することができる。

5	オプションとして、個人のアプリケーションをインストールするデフォルトディレクトリを変更することができる。これを行うには、ﾓIDS_DEFAULT_GAME_DIRﾓ(リソース・ファイルでは2箇所存在する)を検索し、デフォルト・ディレクトリのパスを変更する。

個人のアプリケーションの用途にあうように、Dinstall.cおよびDinstall.rcファイルを修正した後、それらを実行用Dinstall.exeへコンパイルすることができる。この実行ファイルの名称を変更することもできる(たとえばSetup.exe)。


アプリケーション・ディレクトリのセットアップ

個人のアプリケーションをコンパクトディスクあるいはフロッピーディスクに移す前に、セットアップ・プログラムのテストのためのアプリケーション・ディレクトリを作成しておく。アプリケーション・ディレクトリにはすべてのアプリケーション・ファイル、セットアップ・プログラム、DirectXファイルおよびドライバが含まれることになる。

アプリケーション・ディレクトリをセットアップするために、次のステップを実行すること。

1	個人のアプリケーション・ファイルすべてを含むディレクトリを作成する。必要であればサブディレクトリを作成し、適切なアプリケーション・ファイルをサブディレクトリに置くようにする。

2	作成した実行用セットアップ・ファイルをアプリケーション・ディレクトリのルートへコピーする。

3	MS-DOSプロンプトで、xcopyコマンドを用いて、DirectX 3 コンパクトディスク上のRedistディレクトリを、アプリケーション・ディレクトリのルートへコピーする。たとえば、アプリケーションのルートディレクトリがD:\FungameでE:ドライブがCD-ROMドライブである場合、次のようにタイプする。

xcopy /s e:\redist\*.* d:\fungame

注意　　DirectXSetup関数およびDxsetup.exeファイルが正常に動作するためには、DirectX 3 SDK上に配置されたRedistディレクトリの全内容がアプリケーション・ディレクトリのルートになければならない。

適切なファイルすべてをルートアプリケーション・ディレクトリへコピーすると、以下のようになる。

 ドライブ D: のボリュームラベルは SYSTEM

 ディレクトリは D:\FUNGAME

.              <DIR>        96-07-26  6:43 .

..             <DIR>        96-07-26  6:43 ..

DIRECTX        <DIR>        96-07-26  6:43 directx

DSETUP   DLL        22,016  96-07-26  4:38 dsetup.dll

DSETUP6E DLL        36,224  96-07-26  4:38 dsetup6e.dll

DSETUP6J DLL        36,224  96-07-26  4:38 dsetup6j.dll

DSETUPE  DLL        42,496  96-07-26  4:38 dsetupe.dll

DSETUPJ  DLL        42,496  96-07-26  4:38 dsetupj.dll

DINSTALL DLL       168,960  96-07-26  4:38 dinstall.dll

YOURFILE EXE        96,442  96-07-26  4:39 yourfile.exe

YOURFILE DAT     1,508,228  96-07-26  4:39 yourfile.dat

...


AutoPlayの稼動

AutoPlayコンパクトディスク・タイトルを作成するには、DirectX 3 SDKコンパクトディスクのルート・ディレクトリにあるAutorun.infファイルを個人のアプリケーション・ディレクトリのルートへコピーする。このテキストファイルには以下のような情報が含まれる。

[autorun]

OPEN=SETUP.EXE

アプリケーションのセットアップ・プログラム名がSetup.exeであれば、このファイルを変更する必要はない。それ以外の場合は、このファイルを編集し、個人のセットアップ・プログラム名を入れなければならない。Autorun.infファイルに関する詳細な情報については、Autorun.infファイル.を参照すること。


DirectSetup リファレンス


関数


DirectXRegisterApplication

int WINAPI DirectXRegisterApplication(HWND hWnd,

    LPDIRECTXREGISTERAPP lpDXRegApp);

ISVゲームをDirectPlayLobbyを用いて動作するアプリケーションとして登録する。

正常に実行されればTRUE を、そうでなければFALSEを返す。FALSEを返すときGetLastErrorというWin32の関数を使用すると拡張エラー情報を得ることができる。

hWnd

親ウィンドウのハンドル。このパラメータがNULLになっていると、デスクトップが親ウィンドウとなる。

lpDXRegApp

レジストリ・エントリを含むDIRECTXREGISTERAPP構造体のアドレス。


DirectXSetup

int WINAPI DirectXSetup(HWND hWnd, LPSTR lpszRootPath,

    DWORD dwFlags);

ひとつまたはそれ以上のDirectXコンポーネントをインストールする。

正常に実行されればSUCCESSを返し、そうでなければエラーを返す。返値コードのリストについては、返値を参照すること。

hWnd

セットアップダイアログボックスの親ウィンドウのハンドル。

lpszRootPath

DirectXコンポーネントファイルのルートパスを含む文字列のアドレス。この文字列は、Dsetup.dllファイルを含むディレクトリへのフルパスを指定しなければならない(通常はRedist)。カレント・ディレクトリにDsetup.dllおよびDirectxディレクトリが含まれているのが確かであれば、このパラメータはNULLである。

dwFlags

どのDirectXコンポーネントがインストールされるかを示す、ひとつまたはそれ以上のフラグ。全体をインストールする(DSETUP_DIRECTX)ことを推奨する。

DSETUP_D3D	Direct3D�をインストールする。
DSETUP_DDRAW	DirectDrawをインストールする。
DSETUP_DDRAWDRV	DirectDrawデバイス・ドライバをインストールする。
DSETUP_DINPUT	DirectInput�をインストールする。
DSETUP_DIRECTX	すべてのDirectX コンポーネントをインストールする。
DSETUP_DIRECTXSETUP	DirectXSetup DLLをインストールする。
DSETUP_DPLAY	DirectPlayｮをインストールする。
DSETUP_DPLAYSP	DirectPlayサービス・プロバイダをインストールする。
DSETUP_DSOUND	DirectSoundｮをインストールする。
DSETUP_DSOUNDDRV	DirectSoundデバイス・ドライバをインストールする。
DSETUP_DVIDEO	DirectVideoをインストールする。
DSETUP_PROMPTFORDRIVERS	ディスプレイおよびオーディオ・デバイス・ドライバを置き換える前に確認を行う。
DSETUP_RESTOREDRIVERS	ディスプレイおよびオーディオ・ドライバを復元する。
セットアップ・プログラムでDirectXSetupを使用する前に、ユーザのシステムに最低5 MBの空きディスク容量があることを確認すること。これは適切なファイルをセットアップするためにDirectXが必要とする最大の容量である(ただしユーザのシステムにDirectXファイルがすでに存在する場合は不要)。


構造体


DIRECTXREGISTERAPP

typedef struct _DIRECTXREGISTERAPP {

    DWORD  dwSize;

    DWORD  dwFlags;

    LPSTR  lpszApplicationName;

    LPGUID lpGUID;

    LPSTR  lpszFilename;

    LPSTR  lpszCommandLine;

    LPSTR  lpszPath;

    LPSTR  lpszCurrentDirectory;

} DIRECTXREGISTERAPP, *PDIRECTXREGISTERAPP, *LPDIRECTXREGISTERAPP;

DirectPlayLobbyで動作するアプリケーションに必要なレジストリ・エントリを持つ。

dwSize

構造体のサイズ。

dwFlags

将来の使用のために予約されている。

lpszApplicationName

アプリケーションの名称。

lpGUID

アプリケーションのグローバル・ユニーク識別子(GUID)。

lpszFilename

呼び出される実行ファイルの名称。

lpszCommandLine

実行ファイルに対するコマンドラインでの引数。

lpszPath

実行ファイルのパス。

lpszCurrentDirectory

カレント・ディレクトリを示す。通常はlpszPath と同じ。


返値

DirectXSetup関数は以下の値を返す。

DSETUPERR_BADSOURCESIZE

	ファイルサイズを検証できなかったか、誤りであった。

DSETUPERR_BADSOURCETIME

	ファイルの日付および時刻を検証できなかったか、誤りであった。

DSETUPERR_BADWINDOWSVERSION

	DirectXはこのバージョンのWindowsをサポートしていない。

DSETUPERR_CANTFINDDIR

	セットアップ・プログラムが作業ディレクトリを探し出せなかった。

DSETUPERR_CANTFINDINF

	必要な .inf ファイルを探し出せなかった。

DSETUPERR_INTERNAL

	内部エラーが起こった。

DSETUPERR_NOCOPY

	ファイルのバージョンを検証できなかったか、誤りであった。

DSETUPERR_NOTPREINSTALLEDONNT

	システムのWindows NTのバージョンにはDirectX 3コンポーネントが一切インストールされていない。

DSETUPERR_OUTOFDISKSPACE

	インストール中にセットアップ・プログラムがディスク容量を使い果たした。

DSETUPERR_SOURCEFILENOTFOUND

	必要なソースファイルのうちのひとつを探し出せなかった。

DSETUPERR_UNKNOWNOS

	サポートされていないバージョンのOSである。

DSETUPERR_USERHITCANCEL

	アプリケーションが完全にインストールされる前に、Cancelボタンが押された。

SUCCESS

	セットアップの正常終了。再起動の必要がなければ、0が返される。
	セットアップの正常終了。再起動の必要があれば、1が返される。


AutoPlayについて

Microsoftｮ AutoPlayはMicrosoft Windowsｮ オペレーティング・システムの一機能である。AutoPlayは、Windowsプラットフォーム用に設計された製品をインストール、構成するのに必要な手続きを自動化するもので、コンパクト・ディスク(CD)で配布されている。AutoPlayの入っているディスクをWindowsが動作しているコンピュータのCD-ROMドライブに挿入すると、AutoPlayはディスク上のアプリケーションを自動的に起動し、選択された製品をインストール、構成および実行する。

Autoplayを用いて、MS-DOSｮ オペレーティング・システム、Windows 3.0、Windows 3.1、Windows 95またはWindows NTｮのいずれかをベースにして動作するCD-ROMアプリケーションを、Windows上でインストールおよび実行することができる。そのCD-ROM製品にMicrosoft Windows 95のロゴを表示させたい場合には、AutoPlayを用いることが必要になる。

注意

MS-DOS、Windows 95以前のバージョンのWindows、およびWindows NT バージョン3.51およびそれ以前のものはAutoPlayをサポートしていない。しかしAutoPlayをCDに加えても、これらのオペレーティング・システムが動作しているコンピュータの動作は妨げられたり影響を受けたりしない。


AutoPlayの動作について

AutoPlayの動作は次にあげる３つの条件を必要とする。

Windows 95およびWindows NTの32ビットCD-ROMデバイス・ドライバのセット。これらのデバイス・ドライバは、ユーザがCDをCD-ROMドライブに挿入したことを検知する（ただしMS-DOSあるいは以前のバージョンのWindowsのデバイス・ドライバは検知を行わない）。

CD上のAutorun.infファイル。 Windows 95あるいはWindows NTが動作するコンピュータのCD-ROMドライブにディスクを挿入すると、システムは直ちにディスクにPCのファイルシステムが存在するかどうかをチェックする。存在する場合には、システムはAutorun.infという名称のファイルを探す。このファイルはAutoPlayが実行するアプリケーションを指定し、さらに他の情報をも保有することができる。このファイルの詳細については、Autorun.infファイルを参照すること。

CD上のスタートアップ・アプリケーション。Autorun.infファイルで指定すればディスク上の任意のアプリケーションを起動できるが、一般的には起動またはインストール機能を実行する。新たに作ったスタートアップ・アプリケーションを使うと、製品のインストール、アンインストールおよび実行プロセスを制御することができる。


Autorun.infファイル

Autorun.infファイルはCDのルート・ディレクトリにあるテキストファイルである。このファイルには、ディスクでのスタートアップ・アプリケーション（ディスクをCD-ROMドライブに挿入すると自動的に動作するアプリケーション）の名称や、Windowsユーザ・インターフェイスにおいてAutoPlay動作可能なCDであることを示すアイコンが含まれる。またAutorun.infファイルには、ショートカット・メニューに加えたいオプションのメニューコマンドも含まれている。このショートカット・メニューは、CD-ROMアイコンをマウスで右クリックすると表示される。

Autorun.infファイルには最低でも3行のテキストが含まれ、スタートアップ・アプリケーションおよびアイコンを識別する。以下に例を示す。

[autorun]

open=filename.exe

icon=filename.ico

[autorun] セクションは、それに続く行をAutoPlayコマンドとして識別する。 [autorun] セクションはすべてのAutorun.infファイルに必要である。 openコマンドはスタートアップ・アプリケーションのパスおよびファイル名を指定し、 iconコマンドはアイコン情報を含むファイルを指定する。

Autorun.infファイルに、RISCプロセッサ上で動作しているWindows NT 4.0のアーキテクチャ特有のセクションを含めることもできる。そのためには、それぞれのタイプのプロセッサ・アーキテクチャにあわせて、そのアーキテクチャで実行したいスタートアップ・アプリケーションのファイル名を含むAutorun.infファイルにセクションを加える。x86アーキテクチャには、標準 [autorun] 行を用いる。MIPSアーキテクチャ上でアプリケーションを実行する場合には [autorun.mips] 、Alphaアーキテクチャ上のアプリケーションには  [autorun.alpha] 、PowerPCアーキテクチャには [autorun.ppc] を用いる。コンピュータ・アーキテクチャにより異なるスタートアップ・アプリケーションを実行するAutorun.infファイルの作成法の例を、以下に示す。

[autorun]

open=filename.exe

icon=filename.ico

[autorun.mips]

open=filenam2.exe

icon=filename.ico

[autorun.alpha]

open=filenam3.exe

icon=filename.ico

[autorun.ppc]

open=filenam4.exe

icon=filename.ico

シェルは最初にアーキテクチャ固有のセクションをチェックする。セクションを見つけられなかった場合は、 [autorun] セクションの情報を利用する。セクションを見つけるとシェルは他のセクションをすべて無視してしまうので、それぞれのセクションがアーキテクチャのすべての情報を持っていることを確認する必要がある。


AutoPlayアプリケーションを書く上でのアドバイス

このセクションではAutoPlayアプリケーションを書く上で必要な以下のアドバイスについて説明する。

スタートアップ・アプリケーションのオープン

バックグラウンドでのロード

ハードディスク空間の節約

レジストリの使用

NoDriveTypeAutoRun値のセット


スタートアップ・アプリケーションのオープン

AutoPlayCDをドライブに挿入するとすぐに、スタートアップ・アプリケーションが立ち上がる。これには、Autorun.infファイルのopenコマンドに、高速にロードできる小型のスタートアップ・アプリケーションを指定する。そのアプリケーションには、実行するタイトルの表示やキャンセル・ボタンなどを備えておく。


バックグラウンドでのロード

スタートアップ・アプリケーションが、処理を続けていいかどうかをダイアログ・ボックスで聞くと、ユーザは通常OKをクリックする。このとき、ユーザがボタンを押すまでの時間を利用して、バックグラウンドでスタートアップ・アプリケーションのロードを始める別スレッドを起動させておくと、時間を有効に利用できる。これにより、アプリケーションのロード時間がかなり短縮される。


ハードディスク空間の節約

ハードディスク領域には限りがある。ここではハードディスクを節約するためのアドバイスをいくつか挙げる。

インストール用アプリケーションを実行せず、CDから直接アプリケーションを実行する。

アプリケーションがハードディスクドライブを必要とする場合は、実行に必要な機能コンポーネントのみをインストールする。さらに、これらのコンポーネントをハードディスクからアンインストールする方法も準備しておく。アプリケーションのアンインストールに関する詳細な情報については、マイクロソフト Win32 ソフトウェア開発キット (SDK)に添付されているマニュアルを参照すること。

アプリケーションがハードディスクドライブをデータキャッシュとして利用する必要がある場合、タイトルまたはゲームの終了時にキャッシュ内のデータを消去するオプションのソフトをスタートアップ・アプリケーション内に用意しておく。


レジストリの使用

レジストリは、初期化情報(.ini)およびコンフィギュレーション・ファイルに替わるWindowsの機能である。レジストリを操作するAPIに関する情報については、Win32 SDKに添付されているマニュアルを参照すること。

製品が初期化情報を登録していると、その情報はレジストリに格納され、後から取り出すことが可能になる。アプリケーションはレジストリ中の情報を見て、製品をインストールする必要があるかどうかを決めることができる。製品のレジストリエントリが存在しない場合は（つまり製品が使われる最初のとき）、セットアップのオプションを一覧するダイアログボックスを表示させる。製品がレジストリに登録済みの場合、製品はすでにインストールされているため、セットアップオプションを省略できる。

システムレジストリを変更すると、フロッピーディスクからAutorun.infファイルを読み込ませることが可能となる。フロッピーディスクでAutoPlayを動作させても意味はないが、Autorun.infファイルをCDに焼き付ける前のデバッグには役立つ。AutoPlayはCDでだけ一般配布する予定である。AutoPlayをフロッピーディスクで動作するようにするには、次の手続きを実行すること。

1	レジストリエディタ (Regedit.exe) において「編集(E)」をクリックし、その後で「検索(F)」をクリックする。

2	検索ダイアログで以下に示す語をタイプし「次を検索(F)」をクリックする。

NoDriveTypeAutoRun

3	「編集(E)」をクリックし、その後「変更(M)」をクリックする。

4	NoDriveTypeAutoRun 値のデータを0000 95 00 00 00 から 0000 91 00 00 00に変更し、OKをクリックする。

以上で、任意のドライブ上でAutoPlayが稼動する。しかし、フロッピーディスク上にインストールされているときは、AutoPlayを手作業で起動しなければならない。これを行うには、フロッピーディスクアイコンをダブルクリックあるいはマウスで右クリックし、その後AutoPlayをクリックする。

5	Autorun.inf のテストが完了した後、NoDriveTypeAutoRunの値を0000 95 00 00 00にリセットする。

重要事項

フロッピーディスクでAutoPlayを動作させると、コンピュータウィルスを簡単に蔓延させることができてしまう。一般配布されているフロッピーディスクにAutorun.infファイルが入っていたら、ウィルスの存在を疑う必要がある。

NoDriveTypeAutoRun値に関する詳細な情報については、NoDriveTypeAutoRun値のセットを参照すること。


NoDriveTypeAutoRun値のセット

レジストリにあるNoDriveTypeAutoRun値は、タイプREG_BINARYの4バイト長のバイナリデータの値である。この値の最初のバイトは、AutoPlay作業から除外される種々のドライブを表す。このバイトの初期設定は0x95で、これは認識されないタイプのドライブであるDRIVE_UNKNOWN、DRIVE_REMOVEABLEおよびDRIVE_FIXEDのメディアタイプをAutoPlay適用対象から除外する。またAutoPlayの動作にフロッピーディスクドライブを利用するには、ビット2を0にリセットするか、または残りの初期設定をそのままにしておくよう値0x91を指定するかのどちらかを行う必要がある。レジストリ値の変更法に関する情報については、レジストリの使用を参照すること。ビット、ビットマスク定数およびドライブに関する簡単な注釈の表は次の通りである。

ビット番号	ビットマスク定数	注釈
0 (最下位ビット)	DRIVE_UNKNOWN	認識されないドライブタイプ。
1	DRIVE_NO_ROOT_DIR	ルートディレクトリが存在しない。
2	DRIVE_REMOVEABLE	ディスクをドライブ(フロッピーディスク)から取り外せる。
3	DRIVE_FIXED	ディスクをドライブ(ハードディスク)から取り外せない。
4	DRIVE_REMOTE	ネットワークドライブ。
5	DRIVE_CDROM	CD-ROMドライブ。
6	DRIVE_RAMDISK	RAMディスク。
7 (最上位ビット)		将来の利用のために予約されている。
注意

Windows NTについては、変更を有効にする前にWindows Explorerを再起動しなければならない。


AutoPlayの抑制

CDを挿入する際にSHIFTキーを押さえると、ディスク上のAutorun.infファイルが解析・実行されるのを手作業で抑制できる。Windows NTバージョン4.0およびWindows 95でInternet Explorerバージョン4.0を用いているユーザは、自動的にAutoPlayを抑制することができる。この機能は、スタートアップ・アプリケーションの中でユーザにAutorun.infファイルの入っているディスクを挿入させる必要があるときなどに使う。この場合、スタートアップ・アプリケーション実行中に別アプリケーションを実行させるAutoplay機能は不要である。スタートアップ・アプリケーションがフォアグラウンドにあるときAutoPlayを抑制するには、以下のコードをセットアップ初期化コードに加える。

uMessage - RegisterWindowMessage(TEXT("QueryCancelAutoPlay"));

そして以下のコードをセットアップ・ウィンドウ・プロシージャに加える。

if(msg == uMessage)

{

    // return 1 to cancel AutoPlay

    // return 0 to allow AutoPlay

    return 1L;

}


MS-DOSアプリケーションのAutoPlay

また、AutoPlayを用いて、MS-DOSベースのアプリケーションをWindows MS-DOSセッションでインストール、構成および実行できる。MS-DOSベースの各アプリケーションに対し独自のアイコン、Config.sysファイルおよびAutoexec.batファイルを設定することができる。

WindowsはMS-DOSアプリケーションのための正しい設定ファイルを作成する。またスタートアップ・アプリケーションはMS-DOSアプリケーションをウィンドウ内で起動できるようにする。スタートアップ・アプリケーションは必要に応じてそのMS-DOSアプリケーションの再起動をWindowsに指示でき、アプリケーションが閉じると直ちにWindowsへ制御を返すことができる。


リファレンス


コマンド


defaulticon

defaulticon=path\iconname.ico

アイコン情報を持つファイルへのCD上の絶対パスを指定する。このアイコンはWindowsユーザ・インターフェイスにおいてAutoPlay動作可能なCDを表す。

path\iconname.ico

アイコン情報のあるファイルの絶対パスおよびファイル名。bmp、exeあるいはdllファイルを指定することもできる。ファイルに複数のアイコンが含まれる場合、使用ファイル側でアイコンのリソース番号(インデックス)を指定する。

icon および defaulticon コマンドがAutorun.infファイルにある場合、AutoPlayはdefaulticonコマンドで指定されたアイコンを使用する。

ドライブにAutoPlay動作可能なCDがない場合、システムはドライブの表示にデフォルトのアイコンを用いる。

参照　icon


icon

icon=filename.ico

Windowsユーザ・インターフェイスにおいてAutoPlay動作可能なCDを表すアイコンの情報を持つファイルを指定する。このコマンドで指定されるファイル名は、open コマンドで指定されるファイル名と同じディレクトリになければならない。

filename.ico

アイコン情報を含むファイルの名称。また.bmp、.exeあるいは.dllファイルを指定することもできる。ファイルに複数のアイコンが含まれる場合、用いるファイルでアイコンのリソース番号(インデックス)を指定すること。

ドライブがAutoPlay動作可能なCDを含まない場合、システムはドライブの表示にデフォルトのアイコンを用いる。

次の例では、CDを表す２番目のアイコンがファイルで指定されている。最初のアイコンのインデックスは0にセットされている。

icon=filename.exe 1

参照　defaulticon


open

open=dir\filename.exe

CD-ROMドライブにCDを挿入したとき、AutoPlayが実行するアプリケーションのパスとファイル名を指定する。

dir\filename.exe

CDの挿入時、実行可能ファイルを実行したりドキュメントを開いたりするパスおよびファイル名。ファイルがドキュメントの場合、Windowsは指定されたドキュメントに関連づけられたアプリケーションを起動する。パスが指定されていない場合、WindowsはCD上のルートディレクトリでファイルを検索する。相対パスを指定して、そのファイルをサブディレクトリに置くこともできる。

アプリケーション実行時にAutoPlayが渡すコマンドラインパラメータを付加することもできる。

このコマンドを使用してスタートアップ・アプリケーションを開くことで、ユーザからの応答をその場で受け取れる。スタートアップ・アプリケーションの詳細については、スタートアップ・アプリケーションのオープンを参照すること。


shell

shell=verb

ショートカット・メニューのデフォルトエントリを、指定されたカスタムコマンドに変更する。

verb

カスタムコマンドの省略形。カスタムコマンドはAutorun.infファイルで定義されていなければならない。

AutoPlayはAutoPlay動作可能なディスクのデフォルトメニュー項目である。

ユーザがCDを表すアイコンをダブルクリックすると、verbで示されるコマンドが実行される。

参照  shell\verb


shell\verb

shell\verb\command=filename.exe

shell\verb=Menu Item Name

アイコンのショートカット・メニューに示されているカスタムコマンドを指定する。まず1行目で、コマンドを実行する実行可能ファイルを指定する。2番目の行でショートカット・メニューのカスタムエントリを指定する。

verb

コマンドの省略形。このパラメータは実行可能ファイル名とメニュー項目をコマンドに関連づける。このパラメータにはブランクを含むことはできない。 Autorun.infファイルでMenu Item Nameを省略しない限り、verbはショートカット・メニューに表示されない。

filename.exe

カスタムコマンドを実行するアプリケーションのファイル名。

Menu Item Name

大小文字およびスペースを含むメニュー項目テキスト。メニュー項目中の1文字の前にアンパサンド文字(&)をつけることにより、そのメニュー項目のショートカットキーもセットできる。

Windowsユーザ・インターフェイスでは、アイコンをマウスで右クリックするとショートカット・メニューがあらわれる。Autorun.infファイルがCD上に存在する場合、Windowsはそのディスクのアイコンのショートカット・メニューに、AutoPlayを自動的に付加する。 またAutoPlayがデフォルトで起動されるようセットする。アイコンをダブルクリックすると、open コマンドで指定されているものがすべて起動される。

コマンドReadMeを製品のショートカット・メニューに付加し、文字“Mﾓをショートカットキーにする場合には、以下をAutorun.infファイルに加えておくこと。

shell\readit\command=notepad abc\readme.txt

shell\readit=Read &Me

参照  shell,、 open


英数

HAL

ハードウェア・アブストラクション・レイヤ。デバイス固有の実装からアプリケーションを保護する、ハードウェアやデバイス・ドライバのメカニズムにより構成される。アプリケーションから要求された機能を現在のハードウェアが実装していない場合、その機能はソフトウェアがエミュレートする。

HEL

ハードウェア・エミュレーション・レイヤ。ハードウェアがサポートしない機能のソフトウェア・ベースによるエミュレーションを提供する。

Zバッファ（z-buffer）

シーン上の各ピクセルの深度を格納したバッファ。Z値の小さいピクセルはZ値の大きいピクセルを上書きする。


あ

アタッチ （attach）

複数のDirectDrawSurfaceオブジェクトを、Zバッファによる3Dページ・フリッピングで必要とされるような複合構造体に接続すること。アタッチは双方向的ではなく、またサーフェスをそれ自身にアタッチすることはできない。（システム・メモリで）エミュレートされたサーフェスは、エミュレーションでないサーフェスにはアタッチできない。片方のサーフェスがテクスチャ・マップでない限り、ふたつのサーフェスは同じサイズでなくてはならない。

アルファ・エッジ・ブレンド（alpha edge blend）

アルファ・ブレンディング（およびアルファ・チャネル情報）の用法のひとつ。ピクセルの適用範囲に基づいてエッジを混色することにより、エイリアシングを減少させる方法である。

アルファ・カラー・コンポーネント（alpha color component）

不透明度を示す値を含む32ビットの色構成要素。この場合、ピクセルごとの色要素（たとえばARGB）にそれぞれのアルファ（不透明度）値が付加されている。一般的ではないが、特別に用意されたアルファ・サーフェスにピクセルごとのアルファ値をまとめて保持している場合もある。

アルファ・チャネル（alpha channel）

ピクセルごとに色要素（たとえばARGB）の値とともに用意された

イメージの不透明度を定義する値。または独立したアルファ・サーフェスに格納された、ピクセル当たりの不透明度値。または、サーフェス全体の不透明度値。

アルファ定数（alpha constant）

サーフェス全体に適用される不透明度（アルファ値）。

暗影部 （penumbra）

スポットライト光円錐周囲の薄暗い部分。明部を取り囲み、周辺の暗い影をマージする。

参照　明部、スポットライト

アンビエント（ambient）

シーン上のオブジェクトの向き、位置、サーフェスの特性に関わらず、シーン全体を照らす光源。シーンのすべての場所を同じ光度で照らすため、アタッチされたフレームの位置や向きは重要でない。ひとつのシーンでは、複数のアンビエント光源が結合されている。

色空間（color space）

色をエンコードしたり表示したりする、いくつかの異なるメソッドのいずれかを指す。最も一般的なカラー・スペースのタイプは、RGBとYUVのふたつである。

色空間変換（color-space conversion）

ひとつのカラー・スペースから他のカラー・スペースに色を変換する技術。ビデオ・ソースのYUVカラーからディスプレイのRGBカラーへの変換が典型的である。

オーディオ・ストリーム（audio stream）

“ミキシングされた、またはミキシングされる可能性のある”サウンド・データ。DirectSoundは、再生中の各セカンダリ・サウンド・バッファからオーディオ・ストリームをミキシングし、結果をプライマリ・サウンド・バッファに出力する。プライマリ・サウンド・バッファは、サウンド・ハードウェアにオーディオ・データを供給する。

オーバードロー（overdraw）

スクリーン・ピクセルが描画される平均回数。

オーバーレイ・サーフェス（overlay surface）

メモリ上の概念的な矩形領域。格納されているイメージ情報は、転送先プライマリ・サーフェスのイメージ情報をカバーする。オーバーレイは、他のすべてのスクリーン要素のトップにあると想定されている。

オーバーレイZオーダー（overlay z-order）

オーバーレイがクリッピングされる順番を決定する。これにより、ハードウェア・スプライト・システムがDirectDrawのもとで実装される。

オフスクリーン・サーフェス（off-screen surface）

メモリ上の概念的な矩形領域。一般的に、表示前にバックバッファへブロック転送されるビットマップを格納するために用いられる。通常、スプライトを格納するのに利用される。

オペコード （opcode）

実行バッファの頂点の解析方法やシステム状態の変更方法を定義した命令コード。


か

カメラ（camera）

表示位置と方向を定義するため、ビューポートが用いるDirect3DRMFrameオブジェクト。ビューポートは、カメラ・フレームの正のz軸上にある可視オブジェクトだけを、y軸上の正方向にレンダリングする。

カラー・キー（color key）

透明効果や半透明効果のために用いられる色を示した値。たとえばハードウェアのブリット機能を使用する場合、カラー・キーとして設定された色を除く矩形領域ピクセルすべてがブロック転送される。これによって、矩形でないスプライトがサーフェス上に作成される。

カラー・テーブル（color table）

n色のカラー値の配列（通常はRGB三原色）。

カレント・プレイ・ポジション（current play position）

DirectSoundバッファ内の、サウンドが再生される位置。

カレント・ライト・ポジション（current write position）

DirectSoundバッファの中で、安全にデータを変更することができる位置。

クォータニオン （quaternion）

ベクトルを定義する、[x, y, z]値の4番目の要素。クォータニオンは、3D回転で一般的に利用されていた行列メソッドに取って代わるものである。

クリッパ（clipper）

DirectDrawClipperオブジェクト。

クリップ・リスト（clip list）

サーフェスの可視領域を示す矩形のリスト。すでにウィンドウ・ハンドルがDirectDrawClipperオブジェクトに結びつけられているときは、クリップ・リストを設定することはできない。

グループ（group）

DirectPlayセッションにおいて、ひとつのセットとしてまとめられるプレーヤの集合。

後方クリップ面（back clipping plane）

視錐台の奥行きの限界。この先にあるオブジェクトはレンダリングされない。

参照　前方クリップ面


さ

サービス・プロバイダ（service provider）

DirectPlayが利用する、ネットワーク通信を行うダイナミック・リンク・ライブラリ。サービス・プロバイダは、メッセージの送受信に必要なネットワーク固有のコードを備えている。オンライン・サービスも含めたあらゆる組織は、特化されたハードウェアや通信媒体のためのサービス・プロバイダを供給することができる。

サーフェス（surface）

視覚イメージを保持するメモリ。しばしばディスプレイ・メモリを指すが、システム・メモリであってもよい。

参照　複合サーフェス、オフスクリーン・サーフェス、オーバーレイ・サーフェス、プライマリ・サーフェス

サウンド・バッファ（sound buffer）

DirectSoundオーディオ・データを格納するメモリ。サウンド・バッファはプライマリでもセカンダリでもよく、また、スタティックでもストリームでもよい。

参照カウント（reference count）

コンポーネント・オブジェクト・モデル（COM）オブジェクトをコントロールするためのカウンタ。オブジェクトが作成されると、参照カウントは1に設定される。インターフェイスがオブジェクトに結びつけられるたびに参照カウントはインクリメントされ、その接続が切断されると、参照カウントはデクリメントされる。参照カウントが0になったとき、オブジェクトは破棄され、そのオブジェクトへのすべてのインターフェイスは無効となる。

シーン（scene）

仮想環境を構成するオブジェクト全体のセット。可視オブジェクト、サウンド、光、フレームを含む。Direct3Dでは、ルート・フレームに含まれるオブジェクトのセットを指す。

参照　ルート・フレーム

視錐台（viewing frustrum）

ビューポートのカメラに対して相対的に配置されたシーンの立体。視錐台の中にあるオブジェクトは可視状態である。透視投影では、前方クリップ面と後方クリップ面の間の仮想的なピラミッド型を指す。平行投影においては立方体になる。

実行バッファ（execute buffer）

3Dシーンを記述する、完全に自己内包型の、独立した情報パケット。実行バッファには、後に命令ストリームが続く頂点のリストが含まれている。命令ストリームは、オペレーションコード（オペコード）と、このオペコードが操作するデータから構成されている。

伸長（stretching）

異なるサイズの転送先にイメージをブリットすること。この操作を直接サポートするハードウェアもある。

スタティック・サウンド・バッファ（static sound buffer）

完全なサウンドを格納しているメモリ。サウンド全体を一度にバッファに書きこめるため、便利である。

スティッキー・フォーカス（sticky focus）

DirectSoundにおいて、オーナー・アプリケーションが入力フォーカスを持っていないときでもサウンドを再生できる能力。たとえば、DirectSoundアプリケーションは、ユーザーが他のアプリケーションを動かしているときでも、サウンド・バッファを再生し続けることができる。

ストライド・アラインメント（stride alignment）

DirectXでは、ストライドとは、あるラスタ・ラインと次のラスタ・ラインとの間のオフセットを指す。ストライド・アラインメントは、ディスプレイ・メモリ・サーフェスをセットアップする際の重要な設計要素となる場合がある。

ストリーム・サウンド・バッファ（streaming sound buffer）

長いサウンドを再生することができる、小さなサウンド・バッファ。アプリケーションは、オーディオ・データを再生しながら動的にバッファにロードする。たとえばアプリケーションは、3秒のオーディオ・データを保持できるバッファを2分のサウンドを再生するために使用することができる。ストリーム・バッファは、スタティック・バッファよりもはるかに少ないメモリしか必要としない。

スポットライト （spotlight）

円錐状の光を放つ光源。円錐の中にあるオブジェクトだけが照らされる。円錐はふたつの輝度を生成する。中央の明るい部分（明部）はポイント光源と同じ働きをし、周囲の薄暗い部分（暗影部）は、周辺の暗い影とマージされる。

セカンダリ・サウンド・バッファ（secondary sound buffer）

オーディオ・メモリにおいて、アプリケーションを通して再生される個々のサウンドを格納した部分。サウンドは、1回のイベントとして再生することも、ループ・サウンドとして繰り返し再生することもできる。また、セカンダリ・バッファは、有効なサウンド・バッファ・メモリより長いサウンドを再生することも可能である。このバッファは、再生しようとしているサウンドの一部分を格納するキューとしての役割を持っている。

セッション（session）

DirectPlayで、互いに通信しているリモート・マシン上のアプリケーションのインスタンス。

前方クリップ面（front clipping plane）

視錐台の前面の限界。前方クリップ面よりもカメラに近い位置にあるオブジェクトはレンダリングされない。前方クリップ面の高さは、ビューのフィールドを定義する。

参照　後方クリップ面


た

頂点（vertex）

3D空間の点。

ティアリング（tearing）

スクリーンのリフレッシュ・レートがアプリケーションのフレーム・レートと同期していないときに起こる、表示がうねるように見える現象。ひとつのフレームの上部が別のフレームの下部と同時に表示され、ふたつのイメージの間に裂け目が生じる。

テクスチャ（texture）

Direct3Dにおいて、ビジュアル・オブジェクトに適用される、ピクセルが矩形に並んだ配列。

テクスチャ座標（texture coordinates）

各テクスチャのテクセルに、オブジェクト上の各頂点がどう関連づけられるか決定する座標。

テクスチャ・ブレンディング（texture blending）

テクスチャの色をマップ先のサーフェスの色と組み合わせる技術。

テクスチャ・マッピング（texture mapping）

テクスチャをオブジェクトに貼りつけること。テクスチャは平面イメージだがオブジェクトはそうでない場合が多いので、テクスチャ座標とラッピング・フラグを用いてテクスチャをオブジェクトのサーフェスにマップしなくてはならない。

参照　テクスチャ座標、ラップ

テクセル（texel）

テクスチャの単一の要素。テクスチャがオブジェクトに適用されたとき、テクセルがスクリーンのピクセルに対応することはめったにない。アプリケーションは、テクセルがどうピクセル間を補間するか制御するために、テクスチャ・フィルタリングを使用することができる。

デカール（decal）

ビジュアル・オブジェクトとして直接レンダリングされるテクスチャ。ビューポートと一致した矩形にレンダリングされる。

転送元カラー・キー（source color key）

ブロック転送においてコピーされない色、または、オーバーレイにおいて出力先に表示されない色。

転送先カラー・キー（destination color key）

ブロック転送においては、置き換えられる色。オーバーレイにおいては、転送先のサーフェス上の覆い隠される色。


は

配列オブジェクト （array object）

ひとつの配列にまとめられたオブジェクトのグループ。配列オブジェクトによりグループ全体をより簡単に操作できる。配列オブジェクトを利用できるCOMのインターフェイスには、GetElementメソッドとGetSizeメソッドが用意されている。これらのメソッドはそれぞれ、配列要素へのポインタ、配列のサイズを取得する。

バック・バッファ（back buffer）

プライマリ・サーフェスが現在の可視イメージを表示している間に、ビットマップその他のイメージを描きこんでおける、不可視サーフェス。

幅（width）

メモリに格納されたビットマップ内で、あるラインの始点とそのラインの終点とを示すふたつの距離。この距離はメモリ上のビットマップの幅しか表さず、矩形メモリなどと違ってビットマップの次の線の始点まで達するのに必要な補足メモリを含まない。

パラレル・ポイント（parallel point）

パラレル・ライトでオブジェクトを照らす光源だが、光の向きはパラレル・ポイント光源の位置から決定される。たとえば、パラレル・ポイント光源の両側にメッシュがある場合、光源に面しているほうのメッシュが明るくなる。

パレット （palette）

オブジェクトやアプリケーションが使用する色のセット。DirectXでは、DirectDrawPaletteオブジェクトを指す。

パレット・インデックス（palette index）

色を選択するために用いられる、パレット・テーブル配列への整数インデックス。

パワー（power）

素材の反射特性で、スペキュラー・ハイライトの鮮明度を決定する値。この値が5のときは金属的な外観になり、それ以上のときはもっと柔らかそうな外観になる。

反射特性（specular property）

光源の反射に対応した光るオブジェクト上の光点がどのように表示されるかを決定する、素材の特性。反射特性は、素材がどう光を反射するか決定するふたつの特性のうちのひとつである。

参照　放射特性

パン値（pan value）

左右のオーディオ・チャネルの相対音量。100分の1デシベル単位で表される。

ビューポート （viewport）

3Dシーンがどのように2Dウィンドウにレンダリングされるかを定義した矩形。またオブジェクトがレンダリングされる、デバイス上の領域も定義する。

ピッキング（pick）

ビューポートでの2D座標のシーンでビジュアル・オブジェクトを探索すること。

ピッチ（pitch）

メモリに格納されたビットマップ内で、ある線の始点と次の線の始点とを示すふたつの距離。DirectDrawでは、すべてのディスプレイ・メモリがひとつの線形ブロックとして配置されるとは限らないので、メモリ・ピッチとメモリ幅の違いは重要である。たとえば矩形のメモリでは、ディスプレイ・メモリのピッチには、ビットマップ幅に加えキャッシュの一部が含まれる場合がある。

参照　幅

複合サーフェス（complex surface）

DirectDrawSurfaceオブジェクトで、ルート・サーフェスにアタッチされるものをまとめて指す語。複合サーフェス構造体は、ルートが破棄されるときにのみ破棄することができる。

フリッピング・サーフェス（flipping surface）

フリッピング可能なメモリ。

参照　フリップ

フリップ（flip）

バック・バッファとフロント・バッファのアドレスを交換するプロセス。実際にはバック・バッファのイメージがフロント・バッファに交換され、それによってイメージが表示される。

フレーム（frame）

シーン上でのオブジェクトの配置の元になる、非表示の枠。オブジェクトは、関連した参照フレームに対する空間的関係を指定することによって、シーン上に配置される。ビジュアル・オブジェクトは、その位置や向きをフレームから取得する。また、動画やアニメーション中のひとつのイメージもフレームから取得される。

フロント・バッファ（front buffer）

フリッピング・チェーンの最初のバッファ。多くの場合、可視状態のプライマリ・サーフェスを指す。そうでないときは、テクスチャのフリッピング・チェーンのように、3Dエンジンがテクスチャを取得するサーフェスのことである。この場合はプライマリ・サーフェスではなく、表示もされない。フリッピング・オーバーレイ・サーフェスではフロント・バッファは表示されるが、これは単にプライマリ・サーフェスにオーバーレイされたサーフェスにすぎない。

参照　プライマリ・サーフェス

ブリット（blit）

ビットブロック転送。

ブレンディング係数（blend factor）

テクスチャ・ブレンディングにおいて、各色要素がどのように混色されるかを示す係数。

ブレンディング・モード（blend mode）

テクスチャがどのようにマップ先のサーフェスの色と混色されるかを決定するアルゴリズム。

プライマリ・サーフェス（primary surface）

モニター上に表示されるイメージを含んだメモリ領域。DirectXでは、プライマリ・サーフェスはプライマリDirectDrawSurfaceオブジェクトによって表される。

プライマリ・サウンド・バッファ（primary sound buffer）

ゲーム中でユーザーの耳に聞こえる音を持つバッファ。一般にはセカンド・バッファからのサウンドをミキシングするのに用いるが、カスタム・ミキシングやその他の特別な動作を行うため、ダイレクトにアクセスすることもできる。

プレイヤ（player）

DirectPlayセッションの参加者。各プレイヤは、プレイヤ間のメッセージ交換を可能にするプレイヤIDに関連づけられる。

プレイヤID（player ID）

DirectPlayセッションの各参加者に関連づけられるユニークな識別子。プレイヤの作成時に割り当てられる。アプリケーションはプレイヤIDを使用して、プレイヤ間でメッセージを交換することができる。ホストにはつねにDPID_SYSMSGプレイヤIDが割り当てられる。

ページ・フリッピング（page flipping）

参照　フリップ

ホスト（host）

DirectPlayにおいて、IDがDPID_SYSMSGである仮想プレイヤー。システム・メッセージや、セッション中のすべてのプレイヤーに通知されるメッセージは、ホストによって処理される。

ポイント（point）

原点から全方向均等に光を放つ光源。

放射設定（emissive setting）

参照　放射特性

放射特性（emissive property）

素材の特性のひとつ。素材が光を放射するかどうかを示す。放射特性は、素材の光の反射のしかたを決定するふたつの特性のうちのひとつである。

参照　反射特性

法線ベクトル（normal vector）

面の向きを定義する、サーフェスから垂直にのびる架空の光線。


ま

マテリアル（material）

面がどのように光を反射するかを決定する特性。素材には、放射特性（光を放射するかどうか）と反射特性のふたつの構成要素がある。反射の明るさは、強度の設定によって決定される。

ミキシング （mixing）

DirectSoundにおいて、再生中のサウンド・バッファを合成し、結果をプライマリ・サウンド・バッファに書きこむプロセス。サウンド・ハードウェアにオーディオ・データを出力する。処理時間が実用に耐えるかを考えなければ、ミキシングされ得るバッファの数に制限はない。

ミップマップ（mipmap）

連続したテクスチャ。各テクスチャは、同じイメージにフィルタをかけて徐々に低解像度にしたものである。可視オブジェクトが観測者の近くにあるときには高解像度イメージが用いられ、オブジェクトが遠ざかる（そして小さくなる）にしたがって、より低解像度のイメージが用いられる。

明部（umbra）

スポットライトの円錐状の光で、中央の明るい部分。ポイント光源と同じ動作をすることもある。

参照　暗影部、スポットライト

メッシュ（mesh）

単純なポリゴンで表現される面のセット。

面（face）

メッシュ中のひとつのポリゴン。

モードX （Mode X）

スタンダードVGAモード13が提供するハイブリッドなディスプレイ・モード。このモードでは、VGAアダプタのEGAマルチプル・ビデオ・プレーン・システムによって（Mode 13で使用できる64Kのかわりに）256Kまでのディスプレイ・メモリを使うことができる。

モデル座標（model coordinates）

子フレームに対する相対座標。

参照　ワールド座標


や

有向（directional）

フレームにアタッチされる光源だが、すべてのオブジェクトを同じ輝度で照らし、光源がオブジェクトから無限遠の位置にあるような効果を与える。有向光源は向きを持つが位置を持たず、一般に、太陽のような遠く離れた光源をシミュレートするために用いられる。

有効フレーム（enable frame）

光源を適用することができるフレーム。


ら

ラップ（wrap）

面やメッシュのテクスチャ座標の計算に用いるプロシージャ。基本的なラッピング・タイプには、フラット、円柱、球体、クロムがある。

ルート・フレーム（root frame）

Direct3Dにおいて、親フレームを持たないフレーム。フレーム階層のトップにあるフレーム。ルート・フレームは、シーンを構成するオブジェクト全体のセットを含んでいる。

参照　シーン

レイテンシ （latency）

サウンド・バッファが再生されてから、スピーカが実際にサウンドを鳴らすまでの遅延時間。DirectSoundミキサのレイテンシは、一般に20ミリ秒である。

ロビー・クライアント（lobby client）

ユーザのコンピュータに関連づけられたロビー管理ルーチン。アプリケーションのラウンチ、ユーザー・インターフェイスのアップデート、ロビー・サーバとの通信を含む。

ロビー・サーバ（lobby server）

リモート・サーバに関連づけられたロビー管理ルーチン。ロビー・サーバは、特定のアプリケーションに接続したユーザーに関するすべての情報を調整する。


わ

ワールド座標（world coordinates）

ルート・フレームに対する相対座標。

参照　モデル座標