DirectX スタート ページ

DirectX 7.0

目的

Microsoft® DirectX® は、魅力的なマルチメディア アプリケーションを作成するためのバックステージ パスである。

用途

DirectX には、プログラミングのための汎用的なアプローチが 2 つ用意されている。それが、DirectX Foundation と DirectX Media である。

DirectX Foundation は、ゲームや高性能なマルチメディア アプリケーションを作成するための、下位レベルの API (Application Programming Interfaces) セットである。これには、2 次元 (2-D) および 3 次元 (3-D) の高性能なグラフィック、サウンド、音楽、入力、フィードバックなどのサポートや、マルチプレーヤー ゲームなどに対するネットワーク通信のサポートが含まれている。

DirectX Media は、マルチメディアを採用した Web コンテンツやスタンドアロン アプリケーションを作成するための、上位レベルの API セットである。DirectX Media は DirectX Foundation を基盤として構築されていて、柔軟性は劣るものの、より豊富な機能セットを提供する。

対象開発者

DirectX を使用できるのは、C/C++ プログラマおよび Visual Basic プログラマである。

実行時の要件

DirectX は、Microsoft Windows® 95、Windows 98、および Windows 2000 の環境で使用できる。

DirectX Foundation の紹介

DirectX、ドキュメントの慣例事項、新機能、および C/C++ と Visual Basic での DirectX API の使用に関する、一般的な情報。

DirectX Foundation のコンポーネント

DirectX Foundation を構成する各コンポーネントに関する情報。

DirectX サンプル

DirectX Foundation の各コンポーネントのサンプル情報へのクイック リンク。

DirectX チュートリアル

各コンポーネントのチュートリアル情報へのクイック リンク。

フィードバック

エラー レポートと機能要求を Microsoft 社に直接送信する。

Built on 2000年4月13日


法的情報

DirectX 7.0
プログラマーズ リファレンス

本書に記載されている情報は、URL およびインターネット Web サイトの参照も含めて、予告なしに変更されることがあります。本書で例として取りあげる企業、組織、製品、人物、およびイベントはすべて架空のものです。実在の企業、組織、製品、人物、またはイベントとの関連性を示唆するものではありません。本書の使用にあたっては、お客様の責任において、適用されるすべての著作権法に従ってください。著作権法による権利の制限内にとどまらず、また、使用目的にかかわらず、Microsoft Corporation からの書面による許可なく、本書の一部または全部を無断で複製したり、検索システムに格納または導入したり、あるいはいかなる形式や手段 (電子的、機械的、複写、録音、その他) でも配信することはできません。

Microsoft は、本書の内容に関連する特許、特許申請、商標、著作権、その他の知的所有権を有する場合があります。Microsoft からのライセンス契約文書で明示的に規定されていない限り、本書を入手しても Microsoft から上記特許、商標、著作権、その他の知的所有権のいずれのライセンスを取得したことにもなりません。

© 1995-1999 Microsoft Corporation.All rights reserved.

Microsoft、MS-DOS、Windows Windows NT、ActiveX、Direct3D、DirectAnimation、DirectDraw、DirectInput、DirectMusic、DirectPlay、DirectShow、DirectSound、DirectX、Natural、および Win32 は、米国およびその他の各国における Microsoft Corporation の登録商標または商標です。

Roland GS Sound Set/Microsoft (P) 1996 Roland Corporation U.S.

Roland は Roland Corporation の登録商標です。

本書に記載されている実在の会社名および製品名は、各社の商標です。

著作権に関する注意

特別な注意 : Roland GS Sound Set/Microsoft、つまり "サンプル セット" にはローランド サウンドキャンバス サウンド セットが組み込まれています。米国 Roland Corporation は、サンプル セットとそれに関連するすべての著作権を保有しています。さらに、サンプル セットの使用は、Microsoft のオペレーティング システム製品およびアプリケーション製品でのみ許可されています。

Microsoft の使用許諾契約書の条項で、サンプル セットに関して米国 Roland Corporation または Microsoft によって明白に許可されていない権利は、すべてローランドが保有します。

サンプル セットの再頒布は、Microsoft オペレーティング システム製品の統合コンポーネントとして、Microsoft の使用許諾契約書の条項に従って、ソフトウェア アプリケーションと一緒に行う場合にのみ認められます。サンプル セットをその他の用途に使用する場合は、米国 Roland Corporation からの別の書面による許可が必要となります。

米国 Roland Corporation の法的権限を持つ代表者による書面による事前承認なく、サンプル セットをハードウェア ROM または同様のデバイスで、使用、複写、または再頒布することはできません。サンプル セットは、ほかの楽器と一緒に再頒布することはできません。"楽器" とは、ライセンスされた Microsoft オペレーティング システムを実行しているコンピュータに直接接続しなくても、音楽のサウンドを生成することができるデバイスのことです。いかなる環境においても、サンプル セットを修正することは許可されていません。


DirectX Foundation の紹介

Microsoft® DirectX® Foundation は、ゲームおよびその他のハイパフォーマンスなマルチメディア アプリケーションを作成するための下位レベルなアプリケーション プログラミング インターフェイス (API) のセットである。Microsoft® DirectX® Foundation は、2 次元 (2D) と 3 次元 (3D) のグラフィックス、サウンドとミュージック、入力、フォース フィードバック、およびマルチプレーヤ ゲームなどのアプリケーション用のネットワーク通信をサポートする。

ここでは、DirectX Foundation の概要に関する情報を以下のトピックに分けて説明する。

  • DirectX のヘルプについて
  • DirectX Foundation の新機能
  • DirectX Foundation のコンポーネント
  • DirectX サンプル
  • DirectX チュートリアル
  • DirectX ツール
  • C および C++ のプログラミング項目
  • Visual Basic プログラミングについて
  • 参考資料


DirectX のヘルプについて

ここでは、C、C++、および Microsoft® Visual Basic® での Microsoft® DirectX® アプリケーション開発について説明する。

DirectX は C と C++ の両方を完全にサポートしている。ここでは、C++ 構文を頻繁に使用するが、いくつかの例やチュートリアル (サンプル アプリケーションも同様) では C を使用している。さらに、以下のトピックは DirectX で C を使用する方法を示している。

  • マクロ定義の使用
  • C からの COM オブジェクトへのアクセス

ここでは、情報をわかりやすく示すために、言語情報を表す場合、[C++] (「C または C++」を意味する) と表示する。Visual Basic に対しては [Visual Basic] と表示する。C++ に関する概念の説明は、構文を必要に応じて変更することで C にも有効である。

ここでは、プログラミング環境に関する情報だけを表示できるように、言語のフィルタリング機能を実装している。このトピックも含む多くのトピックのタイトル バーの左上には、ポップアップする言語選択用のボタンがある。このボタンをクリックすることにより、C++ (および C) または Visual Basic のいずれかの説明を表示できる。[すべて表示] をクリックすると、両言語に対する言語固有の情報を参照できる。選択する言語とは関係なく、すべての言語に関する情報 (一般的な概念など) は常に参照できる。

[C++]

このテキストは、言語選択用のボタンから [C++] または [すべて表示] をクリックしたときだけ表示される。

[Visual Basic]

このテキストは、言語選択用のボタンから [Visual Basic] または [すべて表示] をクリックしたときだけ表示される。

トピックのタイトル バーにあるボタンの説明を以下に示す。

ボタン | 説明
L | そのトピックで言語のフィルタリングが可能なことを示す。メニュー上で表示可能なプログラミング言語を選択する。
+ | 詳細情報があることを表し、それらのトピックへのリンクを提供する。[参照] として示される。
! | リファレンスを使用するための動作環境を示す。以前は、[対応情報] として示されていた。この情報には、オペレーティング システムのバージョン、ヘッダー情報などが含まれる。

以下の表記は説明や簡単なコードのほか、メソッド、関数、およびその他の API 要素の構文で使用される。

表記 | 意味
Italic text (斜体文字列) | 実際のコードでは具体的な名前または値に置き換えなければならない部分を表す。たとえば、本文に SetCursorPos(X, Y) と書かれていた場合、実際のコードでは X および Y の部分には具体的な値を入れなければならない。
Bold text (太字文字列) | プログラミング インターフェイスや言語などでの関数、プロシージャ、構造体、マクロ、インターフェイス、メソッド、データ型、およびその他のキーワードを表す。
[] | 省略可能なパラメータを示す。
... | 直前の項目を繰り返し記述できることを示す。
FULL BOLD CAPITALS (すべて太字の大文字) | 多くの型 (タイプ) と構造体の名前に使用される。
FULL CAPITALS (すべて大文字) | 列挙値、フラグ、および定数に使用される。
monospace (モノスペース) | サンプル コードまたは構文であることを示す。
. . . | サンプル アプリケーションでの省略部分を示す。


DirectX Foundation の新機能

DirectX 7.0 の新機能のいくつかを以下に示す。

  • 新しい Visual Basic タイプ ライブラリにより、主な DirectX の機能をその環境で開発されたアプリケーションで利用できる。
  • Microsoft® Direct3D® 直接モード API は、デバイス状態のブロック、ジオメトリ ブレンディング、キューブ環境マップ、ユーザー定義のクリップ面などの多くの新機能を提供する。詳細については、「DirectX 7.0 での直接モードの変更点」を参照すること。
  • 新しい Direct3DX ユーティリティ ライブラリは、Direct3D と Microsoft® DirectDraw® の最上位にあるヘルパー層として利用でき、3D グラフィックス開発の一般的なタスクを簡略化する。
  • Microsoft® DirectMusic® は、Downloadable Sounds level 2 規格をサポートする。
  • Microsoft® DirectInput® は、現時点で 8 つまでのマウス ボタン、キーボードへの排他アクセス、フォース フィードバック エフェクトの遅延開始をサポートする。新しいメソッドではフォース フィードバック エフェクト ファイルの読み書きができ、Force Editor アプリケーションを使ってエフェクトを作成することができる。
  • Microsoft® DirectSound® は、拡張されたハードウェア ボイス管理を提供する。
  • 新しい 3D オーディオ処理アルゴリズムにより、DirectSound での CPU 使用率が効率化される。
  • DirectDraw のステレオ サポートが、アクティブ デバイスに追加された。
  • Microsoft® DirectPlay® ロビー アプリケーションは、リップル ラウンチを提供する。
  • ヘルプ ファイルが拡張され、言語固有の情報を表示するための動的なフィルタリング機能が用意された。
  • 多くのサンプル アプリケーションを提供する。


DirectX Foundation のコンポーネント

DirectX Foundation は以下のコンポーネントで構成される。

  • Direct3D は、上位レベルの保持モード インターフェイスと下位レベルの直接モード インターフェイスを提供する。保持モード インターフェイスを使うと、完全な 3D グラフィック システムを簡単に実装することができ、直接モード インターフェイスを使うと、レンダリング パイプラインをアプリケーションから完全に制御することが可能になる。直接モードの詳細については、「Direct3D 直接モードについて」を参照すること。保持モードの詳細については、「Direct3D 保持モードの紹介」を参照すること。
  • Direct3D には今回、ヘルパー層の Direct3DX ユーティリティ ライブラリが用意され、3D グラフィックス開発の一般的なタスクを簡略化することができる。「Direct3DX ユーティリティ ライブラリについて」を参照すること。
  • DirectDraw は、オフスクリーン ディスプレイ メモリ内に置かれたビットマップへの直接アクセスや、ハードウェアのブリット機能、バッファ フリッピング機能などへの超高速アクセスを提供することにより、ハードウェアおよびソフトウェアのアニメーション技術の質を向上させる。詳細については、「DirectDraw について」を参照すること。
  • DirectInput は、あらゆる種類の入力とフォース フィードバック デバイスをサポートする。詳細については、「DirectInput について」を参照すること。
  • DirectMusic は、メッセージ ベースのデータと共に機能し、音楽再生、およびリアルタイム アレンジやさまざまな演奏を伴う DLS ベースのサウンド エフェクト用に完全なシステムを提供する。DirectX のこのコンポーネントの詳細については、「DirectMusic について」を参照すること。
  • DirectPlayは、モデムまたはネットワークを介したゲーム間接続を容易に行えるようにする。詳細については、「DirectPlay について」を参照すること。
  • DirectSetup は、一度の呼び出しでインストールを完了できる DirectX プロシージャを提供する。詳細については、「DirectSetup について」を参照すること。
  • DirectSound は、ウェーブ サウンドを再生でき、ハードウェアとソフトウェアのミキシング、3D ポジショニング、およびサウンド キャプチャをサポートする。詳細については、「DirectSound について」を参照すること。


DirectX サンプル

生きたサンプルからコードを学ぶことこそ、DirectX を理解するための最も良い方法である。サンプル アプリケーションは DirectX SDK の Dxf\Samples\Multimedia フォルダに置かれており、Platform SDK のリファレンスの DirectX サンプル コードにもコードが記述してある。

このサンプルの簡単な概要は以下の各コンポーネントに示されている。

  • Direct3D 直接モードのツールとサンプル
  • Direct3DX ユーティリティ ライブラリ サンプル
  • DirectDraw のツールとサンプル
  • DirectInput のツールとサンプル
  • DirectMusic サンプル
  • DirectPlay のツールとサンプル
  • DirectSetup サンプル
  • DirectSound のツールとサンプル


DirectX チュートリアル

DirectX のコンポーネントごとのチュートリアルには、各コンポーネントの基本的な実装方法が順を追って示されている。コード パスと説明から、API の使い方と注意点を理解することができる。

各コンポーネントごとのチュートリアルは以下のとおりである。

  • Direct3D 直接モード チュートリアル
  • DirectDraw チュートリアル
  • DirectInput チュートリアル
  • DirectMusic チュートリアル
  • DirectPlay チュートリアル
  • DirectSound チュートリアル


DirectX ツール

以下のツールは、DirectX アプリケーションの開発とトラブルシューティングに利用できる。

  • DirectX Caps Viewer
  • DirectX Diagnostic Tool
  • DirectX Property Sheet

参照

  • Direct3D 直接モード ツール
  • DirectDraw ツール
  • DirectInput ツール
  • DirectPlay ツール


DirectX Caps Viewer

説明

DirectX Caps Viewer ツールは、DirectX のすべてのコンポーネントのデバイスと機能を列挙する。

パス

実行可能ファイル : (SDK ルート)\Bin\DXUtils\DXCapsViewer.exe

ユーザーズ ガイド

ツリー ビューでトピックを選択する。右側のペインに情報が表示される。


DirectX Diagnostic Tool

説明

DirectX Diagnostic Tool は、コンポーネントが正常に機能しているかどうかをテストするだけでなく、システムとシステムにインストールされている DirectX コンポーネントの情報を収集する。DirectX SDK と共にインストールされるこのツールの特別バージョンを使うことにより、開発者は DirectX 開発チームに問題を直接報告できる。

パス

実行可能ファイル : (SDK ルート)\Bin\DXUtils\Dxdiag.exe

ユーザーズ ガイド

DirectX Diagnostic Tool には独自のヘルプ ファイルが用意されており、[Help] ボタンをクリックするとアクセスできる。


DirectX Property Sheet

説明

コントロール パネルのこのコンポーネントは、システムで利用可能な DirectX コンポーネント、ドライバ、およびハードウェア機能についての情報を取得する。また、DirectX 直接リンク ライブラリ (DLL) のデバッグ バージョンで生成されるデバッグ出力量を設定したり、テスト用にハードウェア アクセラレーション機能を無効にするために使用することもできる。

パス

コントロール パネルの [DirectX] アイコンをダブルクリックする。


C および C++ のプログラミング項目

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

ここでは、DirectX Foundation API のあらゆるプログラミングに関する一般的な項目を紹介する。説明する内容は以下のとおりである。

  • コンポーネント オブジェクト モデル
  • コールバック関数の使用
  • バージョン チェック
  • DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル
  • DirectX アプリケーションのデバッグ


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

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

DirectX API の大部分は、COM を基本とするオブジェクトとインターフェイスで構成されている。COM は、インターフェイスの再利用に重点を置いたオブジェクト ベースのシステムのための土台である。また、任意の数のインターフェイスの構築を可能にするインターフェイス仕様でもある。

DirectX アプリケーションは、COM オブジェクトのインスタンスから構築される。オブジェクトとは、インターフェイスからアクセスするハードウェアやデータを表すブラック ボックスのようなものと考えることができる。コマンドは、COM インターフェイスのメソッドからオブジェクトに送信される。たとえば、ディスプレイ アダプタの現在の表示モードを DirectDraw オブジェクトから取得するには、IDirectDraw7 インターフェイスの IDirectDraw7::GetDisplayMode メソッドを呼び出す。

オブジェクトは、実行時にほかのオブジェクトにバインドし、バインド先オブジェクトが提供するインターフェイスの実装を利用することができる。また、COM オブジェクトだとわかっているオブジェクトがあり、そのオブジェクトによりサポートされているインターフェイスも知っていれば、そのオブジェクトが実行できるサービスをアプリケーション (または別のオブジェクト) から調べることができる。すべての COM オブジェクトが継承するメソッドの 1 つである QueryInterface メソッドを使うと、オブジェクトがどのインターフェイスをサポートしているかを調べ、サポートされているインターフェイスへのポインタを取得することができる。詳細については、「IUnknown インターフェイス」を参照すること。

DirectX の COM プログラミングの詳細については、以下のトピックを参照すること。

  • IUnknown インターフェイス
  • C++ と COM インターフェイス
  • 新しいインターフェイスの取得
  • インターフェイス メソッドの名前と構文
  • C からの COM オブジェクトへのアクセス
  • マクロ定義の使用


IUnknown インターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

COM オブジェクトはいずれも、IUnknown というインターフェイスをサポートする。このインターフェイスは、オブジェクトの寿命を制御する機能およびオブジェクトに実装されるほかのインターフェイスを取得する機能を DirectX に提供する。IUnknown は、次の 3 つのメソッドを持つ。

  • AddRef。どれかのインターフェイスまたはほかのアプリケーションがオブジェクトにバインドしてきたときに、オブジェクトの参照カウントをインクリメントする。
  • QueryInterface。特定のインターフェイスへのポインタを要求することにより、オブジェクトがサポートしている機能について問い合わせる。
  • Release。オブジェクトの参照カウントをデクリメントする。参照カウントが 0 になると、そのオブジェクトは解放される。

AddRef メソッドと Release メソッドは、オブジェクトの参照カウントを管理する。たとえば、DirectDrawSurface オブジェクトを作成したとする。作成直後、このオブジェクトの参照カウントは 1 に設定される。このオブジェクトのインターフェイスへのポインタを返す関数を作成する場合は、返すポインタを使って AddRef を呼び出し、ポインタを返すたびに参照カウントをインクリメントしておくようにしなければならない。また、AddRef を呼び出した場合は、必ず対応する Release を呼び出さなければならない。ポインタを破棄するには、その前にそのポインタを使って Release を呼び出さなければならない。オブジェクトの参照カウントが 0 になると、オブジェクトは破棄され、そのオブジェクトへのインターフェイスはすべて無効になる。

QueryInterface メソッドは、オブジェクトが指定されたインターフェイスをサポートしているかどうかを調べる。目的のインターフェイスがサポートされていた場合は、そのインターフェイスへのポインタが返される。このポインタを取得できたら、そのインターフェイスが持つ各種メソッドを使ってオブジェクトとやり取りできるようになる。正常にインターフェイスへのポインタが返された場合、QueryInterface はその内部で AddRef を呼び出して参照カウントをインクリメントしている。このため、QueryInterface により取得したポインタを破棄するときは、その前にアプリケーションから Release を呼び出して参照カウントをデクリメントしておかなければならない。

動作環境

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降が必要。
ヘッダー : unknwn.h で宣言。


IUnknown::AddRef

IUnknown::AddRef メソッドは、オブジェクトの参照カウントを 1 だけ増加させる。

ULONG AddRef();

パラメータ

パラメータなし。

戻り値

新しい参照カウント値を返す。この値は、診断およびテストを目的として使うためだけに用意されたものである。

注意

オブジェクトを作成すると、作成したオブジェクトの参照カウントは 1 に設定される。その後、アプリケーションがそのオブジェクトのインターフェイスを取得するか、または AddRef メソッドを呼び出すたびに、オブジェクトの参照カウントは 1 ずつ増加する。Release メソッドを呼び出すと、オブジェクトの参照カウントは 1 だけ減少する。

動作環境

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降が必要。
ヘッダー : unknwn.h で宣言。


IUnknown::QueryInterface

IUnknown::QueryInterface メソッドは、指定された COM インターフェイスがオブジェクトによりサポートされているかどうかを調べる。インターフェイスがサポートされていた場合は、オブジェクトの参照カウントが 1 だけ増加する。アプリケーションは、このメソッドの呼び出し直後からそのインターフェイスを使用できるようになる。

HRESULT QueryInterface(
  REFIID riid,
  LPVOID* obp
);

パラメータ

riid
要求するインターフェイスの参照識別子。
obp
目的のインターフェイスがサポートされていた場合に、インターフェイスへのポインタが格納されるポインタ変数のアドレス。

戻り値

メソッドが成功すれば、S_OK が返される。

メソッドが失敗すれば、E_NOINTERFACE または E_POINTER が返される。また、コンポーネントの中には、これらのエラー値に対する個別の定義をヘッダー ファイルに格納しているものもある。たとえば、DirectInput では DIERR_NOINTERFACE と E_NOINTERFACE は同じ値である。

注意

このメソッドの呼び出しにより取得したインターフェイスを実際に使用する必要がない場合は、取得したインターフェイスの Release メソッドを呼び出してインターフェイスを解放しなければならない。QueryInterface メソッドにより、Microsoft およびサード パーティ各社は、既存の機能や将来追加される機能と衝突することなくオブジェクトを拡張できるようになる。

動作環境

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降が必要。
ヘッダー : unknwn.h で宣言。


IUnknown::Release

IUnknown::Release メソッドは、オブジェクトの参照カウントを 1 だけ減少させる。

ULONG Release();

パラメータ

パラメータなし。

戻り値

新しい参照カウント値を返す。この値は、診断およびテストを目的として使うためだけに用意されたものである。

注意

オブジェクトは、参照カウントが 0 になると解放される。AddRef メソッドを呼び出すと、オブジェクトの参照カウントは 1 だけ増加する。

IUnknown::AddRef または IUnknown::QueryInterface を呼び出したか、または DirectDrawCreate などのオブジェクト作成関数を呼び出して明示的に作成したインターフェイスがある場合は、必ずこのメソッドを呼び出してインターフェイスを解放しなければならない。インターフェイスだけを解放するのに必要な処理は、このメソッドの呼び出しである。

動作環境

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降が必要。
ヘッダー : unknwn.h で宣言。


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

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

COM インターフェイスは、C++ でいうところの抽象基本クラスのようなものである。つまり、一連の特徴や意味は定義するものの、具体的な実装は定義せず、状態データも一切関連付けられていない。C++ の抽象基本クラスでは、すべでのメソッドが純粋仮想関数として定義され、コードは一切割り当てられない。

C++ の純粋仮想関数と COM インターフェイスは、どちらも vtable と呼ばれる機構を使用する。vtable には、インターフェイスを実装するために必要なすべての関数のアドレスが格納される。アプリケーションまたはオブジェクト内でこれらの関数を使用したい場合は、QueryInterface メソッドを呼び出して、目的のオブジェクトにそのインターフェイスがあるかどうかを調べ、そのインターフェイスへのポインタを取得すればよい。QueryInterface を呼び出した後、このオブジェクトはアプリケーションやオブジェクトに vtable へのポインタを送る。このメソッドがオブジェクトによって実装される各種インターフェイス メソッドを呼び出せるのも、vtable へのポインタを使っているためである。このメカニズムにより、オブジェクトが使用するプライベート データと呼び出し側のクライアントの処理は完全に切り離される。

COM オブジェクトと C++ のオブジェクトのもう 1 つの類似点は、メソッドの最初の引数がインターフェイス (C++ の場合はクラス) の名前であることだ。これは、C++ では this 引数と呼ばれる。COM オブジェクトと C++ のオブジェクトはバイナリレベルで完全に互換性があるため、コンパイラは、COM インターフェイスを C++ の抽象クラスと同じように扱い、同じ構文を持つことを前提に処理する。このため、コードの複雑さは軽減される。たとえば、C++ での this 引数は、既に解釈されたパラメータとして扱われてコード化されず、vtable を使った間接的な呼び出しも C++ では暗黙的に処理される。


新しいインターフェイスの取得

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

COM では、オブジェクトの機能を更新する際には、既存インターフェイスのメソッドを変更するのではなく、新しい機能を実現するための新しいインターフェイスを追加するように定められている。COM 上に構築されたオブジェクトは、既存インターフェイスを変更せずに残しておくことで、古いアプリケーションとの互換性を失うことのないまま、サービス内容を自由に拡張できる。

DirectX のコンポーネントは、この試みに従って開発されている。たとえば、DirectDraw コンポーネントでは、IDirectDrawSurface、IDirectDrawSurface2、IDirectDrawSurface3、IDirectDrawSurface4、および IDirectDrawSurface7 の 5 つのインターフェイスのいずれを使っても、DirectDrawSurface オブジェクトにアクセスできるようになっている。これらの各インターフェイスは、それより以前のバージョンで提供されていたメソッドを無変更でサポートするが、新しい機能をサポートするために新しいメソッドを追加している。

アプリケーションで新しい機能が必要なければ、新しいインターフェイスを取得する必要はない。新しいインターフェイスが提供する機能を利用したい場合は、そのインターフェイスのグローバル ユニーク識別子 (GUID) を指定して、対象オブジェクトの IUnknown::QueryInterface メソッドを呼び出さなければならない。インターフェイスの GUID は、対応するヘッダー ファイル内で宣言されている。

次の例は、新しいインターフェイスがサポートされているかどうかを調べる方法を示している。

LPDIRECTDRAW    lpDD1;
LPDIRECTDRAW2   lpDD2;

ddrval = DirectDrawCreate( NULL, &lpDD1, NULL );
if( FAILED(ddrval))
    goto ERROROUT;

// IDirectDraw2 インターフェイスがあるかどうかを問い合わせる。
ddrval = lpDD1->QueryInterface(IID_IDirectDraw2, (void **)&lpDD2);
if( FAILED(ddrval))
    goto ERROROUT;

// IDirectDraw2 があることがわかったので、元のインターフェイスを解放する。
lpDD1->Release();

まれに、新しいインターフェイスが、旧バージョンのインターフェイスでサポートされていたメソッドの一部をサポートしない場合もある。その一例として、IDirect3DDevice2 インターフェイスが挙げられる。旧バージョンのインターフェイスで提供されていた機能を必要とするアプリケーションでは、前の例で示したのと同じ方法で、旧バージョンのインターフェイスの GUID を使って、古いインターフェイスを取得すればよい。


インターフェイス メソッドの名前と構文

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

このドキュメントでは、COM インターフェイスのメソッドをすべて C++ のクラス名で示す。この命名規則を採用したのは、記述に一貫性を持たせるためと、複数の DirectX オブジェクトが同じ名前のメソッドを持つ場合に (QueryInterface、AddRef、Release など)、ほかのオブジェクトのメソッドとの区別を明確にするためである。このような表記規則だからといって、これらのメソッドが C++ でしか使用できないというわけではない。

メソッドの構文にも C++ の表記を用いている。このため、引数にはインターフェイスへの this ポインタが含まれていない。C でプログラミングする場合は、必ずどのメソッドにもインターフェイスへのポインタを指定しなければならない。次に示す例は、C++ の表記での IDirectDraw7::GetCaps メソッドの構文である。

HRESULT GetCaps(
  LPDDCAPS lpDDDriverCaps,
  LPDDCAPS lpDDHELCaps
);

C の表記では、同じメソッドの構文が次のようになる。

HRESULT GetCaps(
  LPDIRECTDRAW7 lpDD,
  LPDDCAPS lpDDDriverCaps,
  LPDDCAPS lpDDHELCaps
);

引数 lpDD には、DirectDraw オブジェクトを表す DirectDraw インターフェイスへのポインタを指定する。


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

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

COM インターフェイスのメソッドは、C プログラムからも呼び出すことができる。C からインターフェイス メソッドを呼び出す場合には、以下の 2 点について注意しなければならない。

  • メソッドの最初の引数には、既に生成されており、そのメソッドを呼び出すオブジェクトへのポインタ (引数 this) を指定する。
  • インターフェイスが持つ各メソッドを参照するには、オブジェクトの vtable へのポインタを使用する。

次の例は、C で IDirectDraw7::CreateSurface メソッドを呼び出して、DirectDraw オブジェクトに関連付けられたサーフェスを作成している。

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

引数 lpDD は、新しいサーフェスが関連付けられる DirectDraw オブジェクトを参照している。このメソッドの呼び出しは、サーフェス情報構造体 (&ddsd) に値を格納し、新しいサーフェスへのポインタ (&lpDDS) を返す。

IDirectDraw7::CreateSurface メソッドを呼び出すには、まず、DirectDraw オブジェクトの vtable への参照を外し、さらに vtable からメソッドへの参照を外す。このメソッドの最初のパラメータは既に作成されており、このメソッドを呼び出す DirectDraw オブジェクトへの参照を指定する。

COM オブジェクトのメソッドを呼び出す方法の C と C++ での違いを示すために、同じメソッドを C++ で示す (C++ では、暗黙的に lpVtbl への参照が外され、this ポインタも暗黙的に渡される)。

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


マクロ定義の使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

DirectX インターフェイスのヘッダー ファイルの多くには、各メソッド用のマクロ定義が記述されている。これらのマクロは、プログラミング時にメソッドを簡単に使えるようにするために用意されたものだが、C、C++ のいずれでプログラミングしている場合でも、__cplusplus が定義されているかどうかに応じて、メソッドの呼び出しをそのとき使用している構文に即した適切な形に展開してくれるという利点もある。

次の例では、IDirectDraw7::CreateSurface メソッドの呼び出しに IDirectDraw7_CreateSurface マクロを使用している。最初のパラメータは、既に生成されており、このメソッドを起動する DirectDraw オブジェクトへの参照である。

ret = IDirectDraw7_CreateSurface (lpDD, &ddsd, &lpDDS,
    NULL);

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


コールバック関数の使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

DirectX には、ハードウェア リソースやアプリケーションで利用可能なその他の項目を列挙するために使用するメソッドが数多く用意されている。これらのメソッドは、基本的にすべて同じ方法で機能する。

プロトタイプのコールバック関数は、各 DirectX コンポーネントで示されている。アプリケーションは、これらのプロトタイプと同じ戻り値とパラメータで関数を宣言する。コールバック関数は CALLBACK、WINAPI、または FAR PASCAL タイプとして宣言される。これらはすべて同等である。

アプリケーションが列挙メソッドを呼び出す場合は、実装された適切なコールバック関数へのポインタを提供する。メソッドは、列挙する項目ごとに 1 回関数を呼び出し、項目についての情報を渡す。関数内で、アプリケーションはこの情報を使用し、リストの構築や特定のデバイス能力の検索といったあらゆるタスクを実行できる。すべての項目が列挙されるか、またはコールバック関数が列挙の終了を示す値 (コールバック関数の戻り型により、FALSE または指定された HRESULT) を返すと、列挙メソッドは戻る。

例については、「DirectInput デバイスの列挙」を参照すること。


バージョン チェック

ユーザーのシステムで現在実行中の DirectX のバージョンにおける機能を調整するために、アプリケーション側で現在インストールされている DirectX のバージョンを確認しなければならない場合がある。

DirectX ソフトウェア開発キットには、(SDK ルート) \Samples\Multimedia\DXMisc\Src\GetDXVer にソース コード付きのサンプル アプリケーションが用意されている。これはシステムに DirectX が存在するかどうかを確認し、DirectX が存在する場合にはそのバージョンを確認する。各 DirectX の新しいバージョンは以前のバージョンの機能をすべてサポートするが、アプリケーションが将来的なバージョンでも動作するよう、特定のバージョンまたはそれ以降のバージョンで必ずテストすること。

また、QueryInterface を使って特定の機能をテストすることもできる。たとえば、アプリケーション全般は DirectX 3.0 以降のバージョンで動作するように設計されているが、オプションのフォース フィードバック エフェクトが DirectX 5.0 以降のバージョンだけでサポートされるとする。この場合、IDirectInputDevice インターフェイスを取得してから IDirectInputDevice2 に問い合わせることにより、フォース フィードバックがサポートされるかどうかを確認できる。

さまざまな理由から、アプリケーション側で現在実行されているオペレーティング システムのバージョンの確認が必要な場合もある。コンポーネントや Windows オペレーティング システムの将来のバージョンに容易に移行できるようにするには、アプリケーションが対応する最も古いバージョンを確認し、それ以降のバージョンでのインストールと実行を行えるようにする。Windows 2000 には DirectX 7.0 の機能またはそれ以上のものが備えられているので、開発者は Windows 2000 またはそれ以上のものを検出し、検出された場合はそこでアプリケーションが動作するようなコードを記述する必要がある。逆に、検出されたバージョンが Windows ＮＴ 4.0 の場合、ＤｉｒｅｃｔＸ 7.0 の機能は利用できない。

次のサンプル関数は、オペレーティング システムがパラメータの示すバージョン (メジャー バージョン、マイナー バージョン、サービス パック) と同じ、またはそれ以降の場合に TRUE を返す。

BOOL bIsWindowsVersionOK(DWORD dwMajor, DWORD dwMinor, WORD dwSPMajor)
{
    OSVERSIONINFO osvi;

    // OSVERSIONINFO 構造体を初期化する。//
    ZeroMemory(&osvi, sizeof(OSVERSIONINFO));

    osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);
    GetVersionEx((OSVERSIONINFO*)&osvi);

    // メジャー バージョンをチェックする。
    if (osvi.dwMajorVersion > dwMajor)
        return TRUE;
    else if (osvi.dwMajorVersion == dwMajor)
    {
        // マイナー バージョンをチェックする。
        if (osvi.dwMinorVersion > dwMinor)
            return TRUE;
        else if (osvi.dwMinorVersion == dwMinor)
        {
            // サービス パックをチェックする。
            if (dwSPMajor && osvi.dwPlatformId ==
                    VER_PLATFORM_WIN32_NT)
            {
                HKEY    hKey;
                DWORD   dwCSDVersion;
                DWORD   dwSize;
                BOOL    fMeetsSPRequirement = FALSE;

                if (RegOpenKeyEx (HKEY_LOCAL_MACHINE,
                        "System\\CurrentControlSet\\Control\\Windows",
                        0,
                        KEY_QUERY_VALUE,
                        &hKey) == ERROR_SUCCESS)
                {
                    dwSize = sizeof(dwCSDVersion);
                    if (RegQueryValueEx (hKey,
                            "CSDVersion",
                            NULL,
                            NULL,
                            (unsigned char*)&dwCSDVersion,
                            &dwSize) == ERROR_SUCCESS)
                    {
                        fMeetsSPRequirement =
                                (LOWORD(dwCSDVersion)  >= dwSPMajor);
                    }
                    RegCloseKey(hKey);
                }

                return fMeetsSPRequirement;
            }
            return TRUE;
        }
    }
    return FALSE;
}


DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

ここでは、DirectX アプリケーションのコンパイル時に考慮すべき点について説明する。説明する内容は以下のとおりである。

  • コンパイルの準備
  • コンポーネントのバージョン定数


コンパイルの準備

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

この SDK に含まれている各サンプルには、それ用のソース ファイル、プロジェクト リソース、リンカなどの設定情報を記述した Microsoft® Visual C++® のプロジェクト ファイル (MDP ファイル) が用意されている。しかし、サンプルを確実にコンパイルし、リンクするには、サンプルをコンパイルする開発者が若干設定作業を行わなければならない場合もある。また、独自に新しいプロジェクトを作成する場合は、そのプロジェクト用の設定情報を開発者が自分で用意しなければならない。(サンプルについては、必要なライブラリに関する情報を提供する目的で、汎用的な makefile も用意してある。Microsoft Visual C++ 以外のコンパイラを使ってサンプルをコンパイルする場合は、この makefile を参照した上で、各自が使用している環境に合わせて適宜このファイルを修正すること。) ここでは、DirectX のサンプルにも、開発者が独自に開発する DirectX アプリケーションにも該当する内容を説明する。

Visual C++ でプロジェクト ファイルを開いた後、アプリケーションをコンパイルする前にいくつかの設定値をチェックしなければならない。以降の説明は、Microsoft Visual C++ 5.0 および 4.2 に有効であるが、Visual C++ のほかのバージョンおよびその他のコンパイラでも同等の設定値を設定できるはずである。Version 5.0 または 4.2 の Visual C++ を使っていない場合、これらの設定値を変更する方法については、使用している開発環境で提供されるドキュメントを参照すること。

注 : 以降の説明ではデフォルトのインストール パス (C:\Mssdk\Include および C:\Mssdk\Lib) を使い、ファイルの場所を記述する。インストール パスは異なる場合もある。

インクルード ファイルの検索パス

ヘッダー ファイルのパスが正しいこと、および DirectX のヘッダー ファイルのディレクトリがコンパイラに最初に検索されるパスになっていることを確認すること。インクルード パスを確認するには、［ツール］ メニューの ［オプション］ をクリックし、［ディレクトリ］ タブをクリックする。これにより、次のようなダイアログ ボックスが表示される。

ここでリストの先頭に表示されているパスが、最新の DirectX のヘッダー ファイルを置いているフォルダになっていなければならない。このデフォルト パスは、C:\Mssdk\Include である。このパスが表示されていない場合は、それをリストに追加し、［ディレクトリ］ タブ内のツールバー コントロールを使ってそのパスをリストの先頭へ移動すること。

リンカの検索パス

リンカがリンク ライブラリを検索する際に使用する検索パスと、その検索順を確認すること。リンクの検索パスのリストも、[ディレクトリ] タブで確認できる。これを行うには、インクルード ファイルの場合と同様に [ツール] メニューの [オプション] をクリックし、[ディレクトリ] タブをクリックする。ダイアログ ボックスが表示されたら、［表示するディレクトリ］ ドロップダウン リスト ボックスの ［ライブラリ ファイル］ をクリックする。これにより表示されたリストの先頭のパスが、最新の DirectX のリンク ライブラリを置いているフォルダになっていなければならない。このデフォルト パスは、C:\Mssdk\Lib である。(ボーランド用のリンク ライブラリは、デフォルト フォルダの下の Borland フォルダに用意されている。)

プロジェクトのリンク ライブラリ

この設定値はプロジェクト ファイル内で指定されるため、サンプルと一緒に提供されたプロジェクト ファイルを使用する場合は、この設定を確認する必要はない。新規アプリケーションの場合は、確認が必要である。確認するには、[プロジェクト] メニューの [設定] をクリックする (Visual C++ 4.2 では、[ビルド] メニューの [設定] をクリックする)。このコマンドを実行すると、次のようなダイアログ ボックスが表示される。

DirectX を使用するアプリケーションは、必ず Dxguid.lib インクルード ライブラリをリンクする。このライブラリは、すべての DirectX Foundation COM インターフェイスのためのグローバル ユニーク識別子 (GUID) を定義している (単独のソース モジュール内で、その他のすべてのインクルードに先立って INITGUID を定義してから、ステートメントを定義するという方法をとってもよい)。さらに、アプリケーションが適切な標準 DirectX リンク ライブラリにリンクされることも確認しなければならない。次の表に示すのは、利用可能な各種 DirectX 基本コンポーネントと、それに対応するリンク ライブラリの一覧である。

コンポーネント | リンク ライブラリ (*.lib)
Direct3D 直接モード | D3dim.lib、D3du.lib
Direct3DX ユーティリティ ライブラリ | D3dx.lib、D3dxd.lib (デバッグ)
Direct3D 保持モード | D3drm.lib、D3dxof.lib
DirectDraw | Ddraw.lib
DirectInput | Dinput.lib
DirectMusic | なし。
DirectPlay | Dplayx.lib
DirectSetup | Dsetup.lib
DirectSound | Dsound.lib
(すべてのコンポーネント) | Dxguid.lib


コンポーネントのバージョン定数

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

DirectX の以前のバージョンとの互換性を保持するため、いくつかの DirectX コンポーネントはヘッダー ファイルにさまざまな API 要素を定義している。通常、影響される要素は、バージョン固有の構造体の能力やフラグ セットである。いくつかのヘッダー ファイル部分は、プリプロセッサが不必要な定義を除外するプリプロセッサ条件文で囲まれている。定義された定数の値は、コンポーネントの特定のバージョンを識別する。値が未定義の場合、ヘッダーはヘッダー ファイルが記述された DirectX のバージョンを識別する値を設定する。DirectDraw のヘッダー ファイル (ddraw.h) の例を次に示す。

#ifndef   DIRECTDRAW_VERSION
#define   DIRECTDRAW_VERSION 0x0700
#endif /* DIRECTDRAW_VERSION */

これらの定数にほかの値を定義すると、以前のバージョンのコンポーネントでこのコンポーネントよりも新しいバージョンのヘッダー ファイルを使用することができる。たとえば、DirectX 3.0 バージョンの DirectDraw のコンパイルに最新のヘッダー ファイルを使用するには、DIRECTDRAW_VERSION に 0x0300 を定義する。開発環境で定数の値を設定したり、ヘッダー ファイルそのものの値を変更したりできる。


DirectX アプリケーションのデバッグ

ここでは、C および C++ アプリケーションのデバッグについて説明する。説明する内容は以下のとおりである。

  • デバッグと DLL 製品
  • シンボル情報


デバッグと DLL 製品

DirectX SDK インストール プログラムは、DirectX ダイナミックリンク ライブラリ (DLL) のデバッグ ビルドまたはリテール ビルドのいずれかのインストール オプションを提供する。

[Visual Basic]

Visual Basic で開発している場合は、アプリケーションの実行がさらに遅くなる恐れがあるため、DLL のデバッグ バージョンをインストールする利点はない。

[C++]

C++ でソフトウェアを開発している場合は、DLL のデバッグ バージョンをインストールするとよい。DLL のデバッグ バージョンには内部データ構造を検証する追加コードがあり、プログラムの実行中に (Microsoft® Win32® OutputDebugString 関数を使って) デバッグのエラー メッセージを出力する。エラーが発生すると、問題の詳細がデバッグ出力される。DLL のデバッグ バージョンはリテール バージョンよりも動作が遅いが、アプリケーションのデバッグにはリテール バージョンよりも役立つ。アプリケーションを出荷する場合は、リテール バージョンを出荷すること。

デバッグ メッセージを確認するには、ウィンドウ内やリモート コンピュータにデバッグ出力が表示されるよう、システムの構成を設定する。Visual C++ などの開発環境だと、この設定が可能である。設定の詳細は環境についてのドキュメントを確認すること。


シンボル情報

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Visual Basic プログラミングについて」を参照すること。

[C++]

デバッグ用のビルドを使用する場合は、デバッガが関連するすべてのシンボリック情報を確実に見つけられるようにするために、以下に示す場所にシンボル ファイルを置いておかなければならない。

OS | デバッガ | .pdb ファイルの場所 | .dbg ファイルの場所
Windows 95、Windows 98 | Visual C++ | バイナリと同じディレクトリ | バイナリと同じディレクトリ
Windows NT、Windows 2000 | Visual C++ | バイナリと同じディレクトリ | %SystemRoot%\Symbols\<binary extension>\
Windows NT、Windows 2000 | NTSD/KD | %SystemRoot%\Symbols\<binary extension>\ | %SystemRoot%\Symbols\<binary extension>\

注 : Microsoft® Windows NT® および Windows 2000® で Visual C++ 開発システムを使ってデバッグする場合は、開発ツールの WIN32API Splitsym を使用してはならない。WIN32API Splitsym は、プライベート シンボリック情報を <binary>.dbg ファイルからバイナリ エクステンションのシンボル ディレクトリ (%SystemRoot%\Symbols\Dll\ など) にコピーし、バイナリ ディレクトリからは元のファイルを削除してしまう。Visual C++ を使用するには、プライベート シンボリック情報のファイル (<binary>.dbg) がバイナリ ファイルと同じディレクトリに置かれている必要がある。したがって、デバッグ用のビルドを使用する場合は、プライベート シンボリック情報のコピーだけを行い、削除を行ってはならない。これが問題となるのは、Windows NT および Windows 2000 で Visual C++ を使用する場合だけである。その他のデバッグ情報については、Visual C++ のドキュメントおよび Windows 2000 Driver Development Kit (DDK) のドキュメントを参照すること。


Visual Basic プログラミングについて

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

ここでは、DirectX® for Visual Basic® を使用してアプリケーションを開発する方法を記述する。

以下のトピックについて説明する。

  • タイプ ライブラリの参照
  • DirectX オブジェクトの作成
  • GUID の使用
  • メソッドへの配列の受け渡し
  • フラグの使用
  • ビット マスクの使用
  • DirectX 列挙
  • Visual Basic エラー トラッピング
  • DirectX クラスのリファレンス


タイプ ライブラリの参照

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

プロジェクトで DirectX for Visual Basic を使用するためには、まずそのプロジェクトにタイプ ライブラリへのアクセス権があることを確認する必要がある。

Visual Basic で [プロジェクト] メニューの [参照設定] をクリックする。[参照設定] ダイアログ ボックスが表示される。[DirectX 7 for Visual Basic Type Library] の左側のチェック ボックスをオンにし、[OK] をクリックする。


DirectX オブジェクトの作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

DirectX for Visual Basic アプリケーションのすべてで、DirectX7 オブジェクトが必要である。これは、各 DirectX コンポーネントに対して主要なオブジェクトを作成するときに使用するメソッドの親オブジェクトである。DirectX7 には、Direct3D の計算を実行するメソッドなど、その他にも多数のメソッドがある。

DirectX7 オブジェクトは、次の例のように新しいオブジェクトとして宣言するだけで取得できる。

Public gObjDX As New DirectX7

DirectSound などの DirectX コンポーネントを作成するには、まずそのオブジェクトの変数を宣言し、適切な DirectX7 作成メソッドを呼び出して作成したオブジェクトをその変数に設定する。次に、例を示す。

Public gObjDSound As DirectSound
Set gObjDSound = DirectX7.DirectSoundCreate

次のオブジェクトは、DirectX の主要なコンポーネントであり、DirectX7 のメソッドを使用して作成する。

コンポーネント | オブジェクト | DirectX7 作成メソッド
Direct3D 保持モード | Direct3DRM | Direct3DRMCreate
DirectDraw | DirectDraw7 | DirectDrawCreate
DirectInput | DirectInput | DirectInputCreate
DirectMusic | DirectMusicComposer | DirectMusicComposerCreate
 | DirectMusicLoader | DirectMusicLoaderCreate
 | DirectMusicPerformance | DirectMusicPerformanceCreate
DirectPlay | DirectPlay4 | DirectPlayCreate
 | DirectPlayLobby | DirectPlayLobbyCreate
DirectSound | DirectSound | DirectSoundCreate
 | DirectSoundCapture | DirectSoundCaptureCreate

その他の主要な DirectX コンポーネントの Direct3D 直接モードは、DirectDraw7.GetDirect3D メソッドを呼び出して取得する必要のある Direct3D7 オブジェクトにより表される。


GUID の使用

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

DirectX の基になっているコンポーネント オブジェクト モデル (COM) でよく使用されるグローバル ユニーク識別子 (GUID) は、通常 DirectX for Visual Basic では表示できない。しかし、いくつかの場所では表示できる。その場合、それらは数値ではなく文字列として扱われる。

新しい GUID を取得する必要がある場合は、Vbguidgen.exe (SDK の \Samples\Multimedia\VBSamples\DXMisc\Bin フォルダに格納されている) を実行し、[Copy] ボタンをクリックする。GUID を Visual Basic アプリケーションに貼り付けて、その周りに疑問符を設定する。

DirectX7.CreateNewGuid メソッドを使用して実行時に GUID を生成することもできる。

アプリケーションで定義した GUID は、次のように DirectPlay プログラムで使用できる (ただし、SessionData は初期化された DirectPlaySessionData オブジェクトである)。

Const guidApp = "{AC330441-9B71-11D2-9AAB-0020781461AC}"
Call SessionData.SetGuidApplication(guidApp)

DirectX メソッドの中には、GUID メンバが格納されたデータ タイプを返すものがある。これらの GUID のフォーマットは、例と同じ文字列フォーマットである。

DirectX は、特定のプロパティやその他のエンティティに対して多数の GUID を定義しており、メソッドの中には、このように事前に定義された GUID のいずれかで受け渡しをしなければならないものがある。それには、前の例のように、(C++ ヘッダー ファイルの) 実際の値を文字列として渡す。しかし、一般的にはもっと簡単に、ドキュメント化した文字列エイリアスで受け渡しをする。たとえば、DirectInput.CreateDevice メソッドを使用すれば、標準キーボードのデバイスを作成するとき、実際の GUID ではなく "GUID_SysKeyboard" で受け渡しをすることが可能である。


メソッドへの配列の受け渡し

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

いくつかの DirectX メソッドでは、指定されていない型のデータが返される。たとえば、DirectSoundCaptureBuffer.ReadBuffer メソッドの buffer パラメータには Any 型のデータが返される。

一般には、そのようなメソッドからデータがバイト配列として返されると都合がよい。Visual Basic 配列では実データの前に別の情報が含まれているので、配列の名前をメソッドに渡すことは簡単ではない。そのため、次例のように配列の最初の要素を渡す必要がある。ここで、dsCaptureBuffer は DirectSoundCaptureBuffer オブジェクト、buffer は 0 ベースのバイト配列、nBytes は読み込まれたバイト数が格納される Long 型データである。

ReDim buffer(nBytes)
Call dsCaptureBuffer.ReadBuffer(0, nBytes, buffer(0), 0)

ただし、メソッドの中には実際にユーザーが入力したデータの配列をパラメータとして受け渡すものがあるので注意すること (たとえば、「DirectInputDevice.SetDataFormat」を参照すること)。この場合、次例のように配列の先頭の要素ではなく配列自体を受け渡す必要がある。ここで、formatArray は DIOBJECTDATAFORMAT 型の配列である。

MyDevice.SetDataFormat(diDataFormat, formatArray())


フラグの使用

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

DirectX for Visual Basic の多くのオブジェクト メソッドでは、flags パラメータや、それに似た名前のパラメータが使用される。また、型の中にはフラグを含むメンバを持つものもある。メソッド呼び出しの多様な動作を制御したり、デバイス能力などの詳細を報告するときに使用する。

フラグは 1 ビットの情報である。特定の動作または能力があるかないかを指定したり、報告する。関連フラグ セットは、一般に各ビットを共有しないメンバを列挙することで表す (ただし、フラグの中にはほかのフラグと組み合わせて表すものもある)。

各フラグは 1 ビットで表されるので、複数のフラグを組み合わせて 1 つの値で表すことができる。たとえば、DirectInput デバイスの協調レベルをフォアグラウンドと排他の両方に設定したいとする。それには、次のように論理演算 Or を使用して 2 つのフラグを組み合わせる。

' diDevice は DirectInputDevice オブジェクト、hwnd はウィンドウ ハンドルである。
diDevice.SetCooperativeLevel(hwnd, _
    DISCL_FOREGROUND Or DISCL_EXCLUSIVE)

ほとんどの場合、論理演算子 Or を使用して複数のフラグを組み合わせる演算は、加算演算子を使用してフラグを合計する演算と等価である。しかし、いくつかのフラグはビットの組み合わせを表していることから、フラグを合計する演算はあまり賢い選択であるとは言えない。次の例で、フラグ CF_PURPLE は CF_RED と CF_BLUE の組み合わせを表している。

Enum COLORFLAGS
    CF_RED    = 1
    CF_BLUE   = 2
    CF_PURPLE = 3
    CF_GREEN  = 4
End Enum

Dim Color As Integer
Color = CF_RED Or CF_PURPLE

ここで、Color の値は 3 である。CF_RED は、CF_PURPLE にその値が既に含まれているので余計である。

一方、次の演算では不正な値が設定される。

' これは間違いである !
Color = CF_RED + CF_PURPLE

ここで、変数に 4 が設定され、CF_GREEN と等価になる。

ユーザーは、フラグの値を取得したら、And 論理演算を使用して個別のフラグの設定値を抽出できる。フラグ値にフラグ定数で表されたビットが含まれている場合、And 演算により 0 以外の値が返されるとき、そのフラグは "オン" である。And 演算で 0 が返された場合、そのフラグは "オフ" である。たとえば、次の呼び出しは、DIDEVCAPS 型の変数に返される能力の入力デバイスが物理的にシステムにアタッチされているかどうかを判定する。

Dim IsAttached As Boolean
IsAttached = diDevCaps.lFlags And DIDC_ATTACHED

次例のように、等価であるかどうかをテストしてはならない。

' これは、間違いである !
IsAttached = (diDevCaps.lFlags = DIDC_ATTACHED)

このようにすると正しく機能しない理由は、lFlags には DIDC_FORCEFEEDBACK などのほかビットも含まれているかもしれないからである (「CONST_DIDEVCAPSFLAGS」を参照すること)。


ビット マスクの使用

DDSURFACEDESC2 など、DirectX 型の中にはビット マスクとして機能する Long 型メンバを持つものがある。一般に、これらのメンバには 16 進形式で値を割り当てる。しかし、Visual Basic は通常 16 進定数を一番短いタイプに変換しようとする。そのため、たとえば &HFF は –1 値を持つ Integer 型データに変換される。Long 型データが返されると予想している DirectX for Visual Basic にこの値が返されると、それは &HFFFFFFFF に変換されてしまう。

16 進のビット マスクを適切に変換するためには、次のように式の後にアンパサンド (&) をもう 1 つ設定する。

DDSD.ddpfPixelFormat.lRBitMask = &HFF&


DirectX 列挙

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

ほとんどの DirectX アプリケーションは、通常初期化時に、使用可能なリソースを列挙する必要がある。たとえば、DirectDraw を使用するアプリケーションは使用可能な表示モードを判定する必要があり、または DirectInput を使用するアプリケーションはジョイスティックで使用可能なボタンや軸を列挙する必要がある。

DirectX for Visual Basic では、アプリケーションが列挙オブジェクトを取得すると自動的に列挙が処理される。列挙オブジェクトが作成されると、コレクションが構築される。このコレクションはオブジェクトが存在する限り存在し、列挙オブジェクトのメソッドを使用してアクセスできる。

列挙オブジェクトの中には、DirectX7 オブジェクトから取得しなければならないものがある。たとえば、DirectSound デバイスを列挙するには、DirectX7.GetDSEnum メソッドを呼び出す。コレクションから適切なデバイスの GUID を取得した後でなければ、DirectSound オブジェクトを作成することはできない。

その他の列挙オブジェクトは、DirectX コンポーネント オブジェクトから取得される。たとえば、DirectInput オブジェクトを取得すれば、DirectInput.GetDIEnumDevices メソッドを呼び出して入力デバイスの列挙オブジェクトを取得できる。

次のサンプル コードでは、システムにアタッチされているすべての入力デバイスが列挙される。ただし、di は DirectInput オブジェクトである。

Dim diEnum As DirectInputEnumDevices
Set diEnum = di.GetDIEnumDevices(0, DIEDFL_ATTACHEDONLY)

DirectInputEnumDevices オブジェクトの 2 つのメソッドを使用すれば、アタッチされたデバイスを繰り返し検索し、特定の能力を持つデバイスを検索したり、またはほかの処理を実行できる。次の例では、デバイスの名前をリスト ボックスに設定する。

Dim diDevice As DirectInputDeviceInstance
Dim X As Integer

For X = 1 To diEnum.GetCount
    Set diDevice = diEnum.GetItem(X)
    Call List1.AddItem(diDevice.ProductName)
Next X

ただし、DirectX 列挙により作成されたコレクションはすべて 1 ベースである。


Visual Basic エラー トラッピング

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

C 言語や C++ では、すべてのメソッドの呼び出しで HRESULT 値が返される。アプリケーションは、戻り値を調べて、それに基づいて処理を行ったり、またはそれを無視することができる。

DirectX for Visual Basic でのエラー処理は、まったく異なる。Visual Basic では、メソッド呼び出しは成功するか、失敗するかのいずれかである。Visual Basic には、S_FALSE などの正の HRESULT 値と等価の成功コードはない。呼び出しが失敗した場合、エラーが発生し、アプリケーションにエラー ハンドラがない限り処理は終了する。エラー番号は、Visual Basic のグローバル オブジェクト Err に設定される。各メソッドで発生する可能性のあるエラーのほとんどは、このドキュメントのメソッドのリファレンス ページに掲載している。

次の例では、gObjDPlay は DirectPlay4 オブジェクトである。DirectPlay4.CreatePlayer 呼び出しが失敗すると、FAILEDCREATEPLAYER ラベルから処理が続行される。

Function GetPlayerID(PlayerName As String, PlayerHandle As String) _
        as Long

  On Error GoTo FAILEDCREATEPLAYER
  GetPlayerID = gObjDPlay.CreatePlayer(PlayerName, PlayerHandle, 0, 0)
  On Error GoTo 0

  ' このセクションのコードは、CreatePlayer が成功した場合にのみ実行される。
  .
  .
  .
  Exit Function

FAILEDCREATEPLAYER:

  If Err.Number = DPERR_INVALIDPLAYER Then
      MsgBox ("Not a valid player.")
  Else
      MsgBox("Unidentified player creation error.")
  End If
  GetPlayerID = 0

End Function


DirectX クラスのリファレンス

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

ここでは、DirectX のすべてのコンポーネントに共通の以下のクラスに関するリファレンスを提供する。

  • DirectX7
  • DirectXEvent


DirectX7

DirectX7 クラスは、DirectX コンポーネント技術の最初の入口として機能する。このクラスには、DirectDraw®、Direct3D®、DirectSound®、DirectInput®、DirectPlay®、および DirectMusic® アプリケーション プログラミング インターフェイスのメイン オブジェクトを作成するメソッドが含まれる。また、さまざまな DirectX コンポーネントで使用されるグローバル メソッドも含まれている。

一般に、このクラスのインスタンスは DirectX アプリケーションで最初に作成されるオブジェクトである。これは、次の例のようにオブジェクト変数を New として宣言することで取得できる。

Public objDX7 As New DirectX7

DirectX7 クラスのメソッドは、以下のグループにまとめることができる。

オブジェクト作成 | Direct3DRMCreate
 | DirectDrawCreate
 | DirectInputCreate
 | DirectMusicComposerCreate
 | DirectMusicLoaderCreate
 | DirectMusicPerformanceCreate
 | DirectPlayCreate
 | DirectPlayLobbyCreate
 | DirectSoundCaptureCreate
 | DirectSoundCreate
列挙 | GetDDEnum
 | GetDSCaptureEnum
 | GetDSEnum
カラー管理 | ColorGetAlpha
 | ColorGetBlue
 | ColorGetGreen
 | ColorGetRed
 | CreateColorRGB
 | CreateColorRGBA
ベクトル管理 | VectorAdd
 | VectorCopy
 | VectorCrossProduct
 | VectorDotProduct
 | VectorModulus
 | VectorNormalize
 | VectorRandom
 | VectorReflect
 | VectorRotate
 | VectorScale
 | VectorSubtract
頂点管理 | CreateD3DLVertex
 | CreateD3DTLVertex
 | CreateD3DVertex
行列 | CopyMatrix
 | IdentityMatrix
 | MatrixFromQuaternion
 | MatrixMultiply
 | ProjectionMatrix
 | QuaternionMultiply
 | QuaternionRotation
 | QuaternionSlerp
 | RotateXMatrix
 | RotateYMatrix
 | RotateZMatrix
 | ViewMatrix
 | ZeroMatrix
その他 | CreateEvent
 | CreateNewGuid
 | DestroyEvent
 | GetWindowRect
 | SetEvent
 | SystemBpp
 | TickCount


DirectX7.ColorGetAlpha

DirectX7.ColorGetAlpha メソッドは、色のアルファ成分を取得する。

object.ColorGetAlpha(color As Long) As Single

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
color
アルファ成分を取得する色。値の範囲は、0～255 である。

戻り値

成功すれば、アルファ値を返す。失敗すれば、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.ColorGetBlue、DirectX7.ColorGetGreen、DirectX7.ColorGetRed


DirectX7.ColorGetBlue

DirectX7.ColorGetBlue メソッドは、色の青成分を取得する。

object.ColorGetBlue(color As Long) As Single

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
color
青成分を取得する色。値の範囲は、0～255 である。

戻り値

成功すれば、青の値を返す。失敗すれば、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.ColorGetAlpha、DirectX7.ColorGetGreen、DirectX7.ColorGetRed


DirectX7.ColorGetGreen

DirectX7.ColorGetGreen メソッドは、色の緑成分を取得する。

object.ColorGetGreen(color As Long) As Single

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
color
緑成分を取得する色。値の範囲は、0～255 である。

戻り値

成功すれば、緑の値を返す。失敗すれば、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.ColorGetAlpha、DirectX7.ColorGetBlue、DirectX7.ColorGetRed


DirectX7.ColorGetRed

DirectX7.ColorGetRed メソッドは、色の赤成分を取得する。

object.ColorGetRed(color As Long) As Single

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
color
赤成分を取得する色。値の範囲は、0～255 である。

戻り値

成功すれば、赤の値を返す。失敗すれば、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.ColorGetAlpha、DirectX7.ColorGetGreen、DirectX7.ColorGetBlue


DirectX7.CopyMatrix

DirectX7.CopyMatrix メソッドは、ソース行列を宛先行列にコピーする。

object.CopyMatrix(mDest As D3DMATRIX, _
    mSrc As D3DMATRIX)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
行列のコピーが格納される D3DMATRIX 型。
mSrc
コピーされるソース行列の D3DMATRIX 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.CreateColorRGB

DirectX7.CreateColorRGB メソッドは、指定された赤、緑、青の成分から RGB 色を作成する。

object.CreateColorRGB(r As Single, _
    g As Single, _
    b As Single) As Long

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
r、g、および b
RGB 色の成分。

戻り値

成功すれば、新しい RGB 値を返す。失敗すれば、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.CreateColorRGBA


DirectX7.CreateColorRGBA

DirectX7.CreateColorRGBA メソッドは、指定された赤、緑、青、アルファ成分から RGBA 色を作成する。

object.CreateColorRGBA(r As Single, _
    g As Single, _
    b As Single, _
    a As Single) As Long

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
r、g、b、および a
RGBA 色の成分。値の範囲は、0～1 である。

戻り値

成功すれば、新しい RGBA 値を返す。失敗すれば、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.CreateColorRGB


DirectX7.CreateD3DLVertex

DirectX7.CreateD3DLVertex メソッドは、それぞれが頂点成分を表す値を使用して D3DLVERTEX 型を設定する。

object.CreateD3DLVertex(x As Single, _
    y As Single, _
    z As Single, _
    color As Long, _
    specular As Long, _
    tu As Single, _
    tv As Single, _
    v As D3DLVERTEX)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
x、y、および z
頂点の x、y、z 座標を示す値。
color および specular
頂点のディフューズ色とスペキュラ色の RGBA 表記法を指定する値。DirectX7.CreateColorRGBA メソッドを使用すれば、個別の赤、緑、青、アルファ成分から目的のカラー値を生成できる。
tu および tv
頂点の u および v テクスチャ座標を記述した値。
v
指定された頂点のコンポーネント データが設定された D3DLVERTEX 型の変数。

エラー コード

失敗すればエラーが発生し、Err.Number にエラー コードが設定される。

参照

DirectX7.CreateD3DVertex、DirectX7.CreateD3DTLVertex


DirectX7.CreateD3DTLVertex

DirectX7.CreateD3DTLVertex メソッドは、別個の頂点成分を表すそれぞれの値を使用して、D3DTLVERTEX 型を設定する。

object.CreateD3DTLVertex(sx As Single, _
    sy As Single, _
    sz As Single, _
    rhw As Single, _
    color As Long, _
    specular As Long, _
    tu As Single, _
    tv As Single, _
    v As D3DTLVERTEX)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
sx、sy、および sz
スクリーン座標で頂点の位置を記述した値。
rhw
頂点の同次 W の逆数。
color および specular
頂点のディフューズ色とスペキュラ色の RGBA 表記法を指定する値。DirectX7.CreateColorRGBA メソッドを使用すれば、個別の赤、緑、青、アルファ成分から目的のカラー値を生成できる。
tu および tv
頂点の u および v テクスチャ座標を記述した値。
v
指定された頂点の成分データが設定された D3DTLVERTEX 型の変数。

エラー コード

失敗すればエラーが発生し、Err.Number にエラー コードが設定される。

参照

DirectX7.CreateD3DVertex、DirectX7.CreateD3DTLVertex


DirectX7.CreateD3DVertex

DirectX7.CreateD3DVertex メソッドは、別個の頂点成分を表すそれぞれの値を使用して D3DVERTEX 型を設定する。

object.CreateD3DVertex(x As Single, _
    y As Single, _
    z As Single, _
    nx As Single, _
    ny As Single, _
    nz As Single, _
    tu As Single, _
    tv As Single, _
    v As D3DVERTEX)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
x、y、および z
頂点の x、y、z 座標を示す値。
nx、ny、および nz
頂点の正規ベクトルの方向を記述した値。
tu および tv
頂点の u および v テクスチャ座標を記述した値。
v
指定された頂点の成分データが設定された D3DVERTEX 型の変数。

エラー コード

失敗すればエラーが発生し、Err.Number にエラー コードが設定される。

参照

DirectX7.CreateD3DLVertex、DirectX7.CreateD3DTLVertex


DirectX7.CreateEvent

DirectX7.CreateEvent メソッドは、フォームに実装されたイベント オブジェクトへのハンドルを返す。

object.CreateEvent(event As DirectXEvent) As Long

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
event
フォームに実装された DirectXEvent オブジェクト。

戻り値

成功すれば、作成されたイベントへのハンドルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DirectX からの通知を受け取るためには、DirectXEvent オブジェクトがフォームにより実装されていなければならない。作成されたイベント ハンドルは、DirectSound、DirectMusic、DirectPlay、および DirectInput の通知メソッドで使用される。

DirectX は、イベント オブジェクトを、該当するイベントが発生したら信号を送るように自動的に設定する。DirectX7.SetEvent メソッドを使用すれば、イベントを手動でも設定できる。これは、イベント処理コードをテストするときに行われる。

作成したイベントはすべて、作成元アプリケーションにより DirectX7.DestroyEvent を呼び出して明示的に破棄する必要がある。この要件を満たさなければ、未定義の動作が行われる可能性がある。

参照

DirectX7.SetEvent、DirectX7.DestroyEvent、DirectSoundBuffer.SetNotificationPositions、DirectSoundCaptureBuffer.SetNotificationPositions、DirectInputDevice.SetEventNotification、DirectPlayLobby3.SetLobbyMessageEvent、DirectMusicPerformance.SetNotificationHandle


DirectX7.CreateNewGuid

DirectX7.CreateNewGuid メソッドは、グローバル ユニーク識別子を生成する。

object.CreateNewGuid() As String

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、GUID を文字列形式で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectX7.DestroyEvent

DirectX7.DestroyEvent メソッドは、DirectX7.CreateEvent メソッドにより作成されたイベント ハンドルを削除する。

object.DestroyEvent(eventid As Long)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
eventid
DirectX7.CreateEvent から返された破棄するイベントのハンドル。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.Direct3DRMCreate

DirectX7.Direct3DRMCreate メソッドは、Direct3DRM3 オブジェクトのインスタンスを作成する。

object.Direct3DRMCreate() As Direct3DRM3

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、Direct3DRM3 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.DirectDrawCreate

DirectX7.DirectDrawCreate メソッドは、DirectDraw7 オブジェクトを作成する。

object.DirectDrawCreate(guid As String) As DirectDraw7

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
guid
作成するドライバを表すグローバル ユニーク識別子 (GUID) のアドレス。空の文字列を指定すればアクティブなディスプレイ ドライバを示し、次のフラグのいずれかを指定すればデバッグのためにアクティブなディスプレイ ドライバの動作を制限できる。
DDCREATE_EMULATIONONLY
DirectDraw オブジェクトは、すべての機能で列挙を使用する。ハードウェアでサポートされている機能は使用しない。
DDCREATE_HARDWAREONLY
DirectDraw オブジェクトは、ハードウェアでサポートされていない機能は列挙しない。サポートされていない機能が必要なメソッドを呼び出そうとすると失敗し、DDERR_UNSUPPORTED を返す。

戻り値

成功すれば、DirectDraw7 オブジェクトへのリファレンスを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.DirectInputCreate

DirectX7.DirectInputCreate メソッドは、DirectInput オブジェクトを作成する。

object.DirectInputCreate() As DirectInput

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectInput オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_BETADIRECTINPUTVERSION
DIERR_INVALIDPARAM
DIERR_OLDDIRECTINPUTVERSION
DIERR_OUTOFMEMORY


DirectX7.DirectMusicComposerCreate

DirectX7.DirectMusicComposerCreate メソッドは、コンポーザ オブジェクトを作成するときに使用される。

object.DirectMusicComposerCreate() As DirectMusicComposer

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

このメソッドは、DirectMusicComposer オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.DirectMusicLoaderCreate

DirectX7.DirectMusicLoaderCreate メソッドを使用して、ローダー オブジェクトを作成するときに使用される。

object.DirectMusicLoaderCreate() As DirectMusicLoader

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

このメソッドは、DirectMusicLoader オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.DirectMusicPerformanceCreate

DirectX7.DirectMusicPerformanceCreate メソッドは、パフォーマンス オブジェクトを作成するときに使用される。

object.DirectMusicPerformanceCreate() _
    As DirectMusicPerformance

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

このメソッドは、DirectMusicPerformance オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.DirectPlayCreate

DirectX7.DirectPlayCreate メソッドは、DirectPlay4 オブジェクトを作成する。

object.DirectPlayCreate(guid As String) As DirectPlay4

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
guid
DirectPlay4 オブジェクトにバインドされるサービス プロバイダを指定する GUID、または空の文字列。「注意」を参照すること。

戻り値

成功すれば、DirectPlay4 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

guid パラメータが空の文字列の場合、DirectPlay 接続は初期化されないので、アプリケーションは DirectPlay4.InitializeConnection を呼び出す必要がある。

参照

GUID の使用


DirectX7.DirectPlayLobbyCreate

DirectX7.DirectPlayLobbyCreate メソッドは、DirectPlayLobby3 オブジェクトを作成する。

object.DirectPlayLobbyCreate() As DirectPlayLobby3

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectPlayLobby3 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.DirectSoundCaptureCreate

DirectX7.DirectSoundCaptureCreate メソッドは、DirectSoundCapture オブジェクトを作成する。

object.DirectSoundCaptureCreate(guid As String) _
    As DirectSoundCapture

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
guid
サウンド キャプチャ デバイスを指定する GUID。このパラメータの値は、DirectX7.GetDSCaptureEnum を呼び出して返される GUID でなければならない。デフォルトのデバイスを指定するときは、このパラメータに空の文字列を指定する。

戻り値

成功すれば、DirectSoundCapture オブジェクトへのリファレンスを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY

注意

このメソッドは、全二重がサポートされていないサウンド カードの場合失敗する。DirectX7.DirectSoundCreate を呼び出すと、サポートされていないキャプチャ周波数がキャプチャ デバイスに設定され、DirectX7.DirectSoundCaptureCreate が失敗する。


DirectX7.DirectSoundCreate

DirectX7.DirectSoundCreate メソッドは、DirectSound オブジェクトを作成する。

object.DirectSoundCreate(guid As String) As DirectSound

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
guid
サウンド キャプチャ デバイスを指定する GUID。このパラメータの値は、DirectSoundEnum.GetGuid を呼び出すことにより返される GUID でなければならない。デフォルトのデバイスを指定するときは、このパラメータに空の文字列を指定する。

戻り値

成功すれば、DirectSound オブジェクトへのリファレンスを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_NODRIVER
DSERR_OUTOFMEMORY


DirectX7.GetDDEnum

DirectX7.GetDDEnum メソッドは、プライマリ DirectDraw ディスプレイ デバイスや非ディスプレイ デバイス (2D 能力のない 3D アクセラレータなど) がインストールされている場合に、それを列挙するときに使用される DirectDrawEnum オブジェクトを作成する。

object.GetDDEnum() As DirectDrawEnum

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawEnum オブジェクトへのリファレンスを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DDERR_OUTOFMEMORY エラー値が設定される。


DirectX7.GetDSCaptureEnum

DirectX7.GetDSCaptureEnum メソッドは、システムにインストールされている DirectSoundCapture オブジェクトを列挙するときに使用される DirectSoundEnum オブジェクトを生成する。

object.GetDSCaptureEnum() As DirectSoundEnum

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectSoundEnum オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_OUTOFMEMORY が設定される。

参照

DirectX7.GetDSEnum


DirectX7.GetDSEnum

DirectX7.GetDSEnum メソッドは、システムにインストールされている DirectSound ドライバを列挙するときに使用される DirectSoundEnum オブジェクトを作成する。

object.GetDSEnum() As DirectSoundEnum

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectSoundEnum オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_OUTOFMEMORY が設定される。

参照

DirectX7.GetDSCaptureEnum


DirectX7.GetWindowRect

DirectX7.GetWindowRect メソッドは、ウィンドウのクライアント領域を記述した矩形を取得する。

object.GetWindowRect(hwnd As Long, r As RECT)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
hwnd
クライアント領域の矩形を取得するウィンドウのウィンドウ ハンドル。
r
メソッドが成功した場合にウィンドウのクライアント領域が設定される RECT 型の変数。

エラー コード

失敗すればエラーが発生し、Err.Number にエラー コードが設定される。


DirectX7.IdentityMatrix

DirectX7.IdentityMatrix メソッドは、単位行列を作成する。

object.IdentityMatrix(mDest As D3DMATRIX)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
操作結果である D3DMATRIX 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

単位行列は、[1,1][2,2][3,3][4,4] 係数に 1.0 が設定されていること除いて、すべての係数が 0.0 の行列である。単位行列は、頂点に適用されてもそれらが変更されないという点で特別である。単位行列は、頂点値を変更して回転、平行移動、および 4×4 行列で表現できるその他の変換を行う行列の起点として使用される。


DirectX7.MatrixFromQuaternion

DirectX7.MatrixFromQuaternion メソッドは、クオータニオンが表す回転の行列を算出する。

object.MatrixFromQuaternion(matrix As D3DMATRIX, _
    quat As D3DRMQUATERNION)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
matrix
関数が戻ったときに算出された行列。
quat
D3DRMQUATERNION 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.MatrixMultiply

DirectX7.MatrixMultiply メソッドは、2 つの行列の積を算出する。

object.MatrixMultiply(mDest As D3DMATRIX, _
    mA As D3DMATRIX, _
    mB As D3DMATRIX)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
mA 行列と mB 行列の積が格納される D3DMATRIX 型。
mA
被乗数として指定する D3DMATRIX 型。
mB
乗数として指定する D3DMATRIX 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

これを適合可能にするには、mA 行列の列数と mB 行列の行数を同じにする必要がある。


DirectX7.ProjectionMatrix

DirectX7.ProjectionMatrix メソッドは、近くと遠くのクリップ面と、視野の角度を設定する。

object.ProjectionMatrix(mDest As D3DMATRIX, _
    nearPlane As Single, _
    farPlane As Single, _
    fov As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
新しく作成された射影行列。
nearPlane
近くのクリップ面までの距離。単位は、アプリケーションに固有である。
farPlane
遠くのクリップ面までの距離。単位は、アプリケーションに固有である。
fov
視野の角度 (ラジアン単位)。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

fov は、射影機の中心から前方クリップ面の中心への直線と、射影機の中心から前方クリップ面の最上部への直線を描画し、その結果の角度を 2 倍にすることで算出できる。


DirectX7.QuaternionMultiply

DirectX7.QuaternionMultiply メソッドは、2 つのクオータニオン タイプの積を算出する。

object.QuaternionMultiply(quat As D3DRMQUATERNION, _
    quatA As D3DRMQUATERNION, _
    quatB As D3DRMQUATERNION)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
quat
乗算の積が格納される D3DRMQUATERNION 型。
quatA および quatB
乗算する D3DRMQUATERNION 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.QuaternionRotation

DirectX7.QuaternionRotation メソッドは、指定軸を回転軸とした指定ラジアン数の回転を表すクオータニオンを取得する。

object.QuaternionRotatation(quat As D3DRMQUATERNION, _
    axis As D3DVECTOR, _
    theta As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
quat
操作結果が格納される D3DRMQUATERNION 型。
axis
回転の軸を指定する D3DVECTOR 型。
theta
axis パラメータにより指定された軸を回転軸として回転するラジアン数。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.QuaternionSlerp

DirectX7.QuaternionSlerp メソッドは、球線形補間を使用して 2 つのクオータニオン タイプ間を線形補間する。

object.QuaternionSlerp(quat As D3DRMQUATERNION, _
    quatA As D3DRMQUATERNION, _
    quatB As D3DRMQUATERNION, _
    alpha As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
quat
補間が格納される D3DRMQUATERNION 型。
quatA および quatB
それぞれ補間の起点と終点として使用する D3DRMQUATERNION 型。
alpha
quatA と quatB 間を線形補間するときの程度を指定する 0～1 の値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.RotateXMatrix

DirectX7.RotateXMatrix メソッドは、x 軸を回転軸として点 (x,y,z) を回転して、新しい点 (x', y', z') を生成する。

object.RotateXMatrix(mDest As D3DMATRIX, _
    radians As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
変換結果が格納される D3DMATRIX。
radians
回転の角度 (ラジアン単位)。角度は、回転軸から原点を見て時計回りに計測する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.RotateYMatrix、DirectX7.RotateZMatrix.


DirectX7.RotateYMatrix

DirectX7.RotateYMatrix メソッドは、y 軸を回転軸として点 (x,y,z) を回転して、新しい点 (x', y', z') を生成する。

object.RotateYMatrix(mDest As D3DMATRIX, _
    radians As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
変換結果が格納される D3DMATRIX。
radians
回転の角度 (ラジアン単位)。角度は、回転軸から原点を見て時計回りに計測する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.RotateXMatrix、DirectX7.RotateZMatrix.


DirectX7.RotateZMatrix

DirectX7.RotateZMatrix メソッドは、z 軸を回転軸として点 (x,y,z) を回転して、新しい点 (x', y', z') を生成する。

object.RotateZMatrix(mDest As D3DMATRIX, _
    radians As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
変換結果が格納される D3DMATRIX。
radians
回転の角度 (ラジアン単位)。角度は、回転軸から原点を見て時計回りに計測する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectX7.RotateYMatrix、DirectX7.RotateXMatrix.


DirectX7.SetEvent

DirectX7.SetEvent は、イベント オブジェクトの状態を信号発信済みに設定する。

object.SetEvent(eventid As Long)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
eventid
信号発信済みとして設定するイベント ハンドル。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドは、DirectX7.CreateEvent により作成されたイベント ハンドルを使用して呼び出す必要がある。

DirectX は、該当するイベントが発生すると、作成されたすべてのイベント オブジェクトを信号発信済みに自動設定する。このメソッドは、主にテスト時の使用を目的としている。


DirectX7.SystemBpp

DirectX7.SystemBpp メソッドは、システムのピクセルあたりのカレント ビット数を返す。

object.SystemBpp() As Long

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、システムのピクセルあたりのカレント ビット数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.TickCount

DirectX7.TickCount メソッドは、システムのティック数を返す。

object.TickCount() As Long

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、システムのティック数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorAdd

DirectX7.VectorAdd メソッドは、2 つのベクトルを加算する。

object.VectorAdd(v As D3DVECTOR, _
    vA As D3DVECTOR, _
    vB As D3DVECTOR)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
v
加算結果が格納される D3DVECTOR 型。
vA および vB
加算する D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorCopy

DirectX7.VectorCopy メソッドは、ベクトルをコピーする。

object.VectorCopy(vDest As D3DVECTOR, _
    vSrc As D3DVECTOR)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
vDest
コピー先 D3DVECTOR。
vSrc
コピー元 D3DVECTOR。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorCrossProduct

DirectX7.VectorCrossProduct メソッドは、2 つのベクトル引数の外積を算出する。

object.VectorCrossProduct(v As D3DVECTOR, _
    vA As D3DVECTOR, _
    vB As D3DVECTOR)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
v
外積が格納される D3DVECTOR 型。
vA および vB
外積を算出する D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorDotProduct

DirectX7.VectorDotProduct メソッドは、ベクトルの内積を返す。

object.VectorDotProduct(vA As D3DVECTOR, _
    vB As D3DVECTOR) As Single

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
vA および vB
内積を算出する D3DVECTOR 型。

戻り値

成功すれば、内積の結果を返す。失敗した場合は、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorModulus

DirectX7.VectorModulus メソッドは、ベクトルの大きさを返す。

object.VectorModulus(vA As D3DVECTOR) As Single

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
vA
長さを返す D3DVECTOR 型。

戻り値

成功すれば、D3DVECTOR 型の長さを返す。失敗すれば、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドは、次の式を使用してベクトルの大きさを算出する。


DirectX7.VectorNormalize

DirectX7.VectorNormalize メソッドは、絶対値を 1 としてベクトルをスケーリングする。

object.VectorNormalize(v As D3DVECTOR)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
v
スケーリング処理の結果が格納される D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorRandom

DirectX7.VectorRandom メソッドは、ランダムの単位ベクトルを返す。

object.VectorRandom(v As D3DVECTOR)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
v
ランダムの単位ベクトルが格納される D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorReflect

DirectX7.VectorReflect メソッドは、指定された法線に対する反射ベクトルを返す。

object.VectorReflect(vDest As D3DVECTOR, _
    vRay As D3DVECTOR, _
    vNormal As D3DVECTOR)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
vDest
処理結果が格納される D3DVECTOR 型。
vRay
法線に対して反射する D3DVECTOR 型。
vNormal
vRay に指定したベクトルを反射するときに基準となる法線を指定した D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorRotate

DirectX7.VectorRotate メソッドは、指定された軸を回転軸としてベクトルを回転する。成功した場合、正規化したベクトルを返す。

object.VectorRotate(vDest As D3DVECTOR, _
    vA As D3DVECTOR, _
    vAxis As D3DVECTOR, _
    theta As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
vDest
正規化の結果が格納される D3DVECTOR 型。
vA
指定された軸を回転軸として回転される D3DVECTOR 型。
vAxis
回転軸である D3DVECTOR 型。
theta
回転角度 (ラジアン単位)。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorScale

DirectX7.VectorScale メソッドは、ベクトルを 3 本の軸すべてに一様にスケーリングする。

object.VectorScale(vDest As D3DVECTOR, _
    vA As D3DVECTOR, _
    factor As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
vDest
処理結果が格納される D3DVECTOR 型。
vA
スケーリング対象の D3DVECTOR 型。
factor
スケーリング係数。値が 1 の場合、スケーリングは変わらない。値が 2 の場合、スケーリングは 2 倍になる。以下同様である。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.VectorSubtract

DirectX7.VectorSubtract メソッドは、2 つのベクトルの差分をとる。

object.VectorSubtract(v As D3DVECTOR, _
    vA As D3DVECTOR, _
    vB As D3DVECTOR)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
v
処理結果が格納される D3DVECTOR 型。
vA
vB を除算する D3DVECTOR 型。
vB
vA から除算する D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.ViewMatrix

DirectX7.ViewMatrix メソッドは、指定されたカメラの位置に基づいてビュー行列を作成する。

object.ViewMatrix(mDest As D3DMATRIX, _
    vFrom As D3DVECTOR, _
    vTo As D3DVECTOR, _
    vUp As D3DVECTOR, _
    roll As Single)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
新たに作成されるビュー行列。
vFrom
カメラの位置を定義する D3DVECTOR 型。
vTo
カメラの目視対象を定義した D3DVECTOR 型。
vUp
カレント ワールドの高さを定義した D3DVECTOR 型。通常は、[0, 1, 0] である。
roll
目視方向を回転軸とした時計回りの回転 (ラジアン単位)。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectX7.ZeroMatrix

DirectX7.ZeroMatrix メソッドは、行列のすべてのメンバに 0 を設定する。

object.ZeroMatrix(mDest As D3DMATRIX)

パラメータ

object
DirectX7 オブジェクトを表すオブジェクト式。
mDest
処理結果が格納される D3DMATRIX 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectXEvent

DirectXEvent クラスは、DirectSound、DirectMusic、DirectPlay、および DirectInput で使用するイベント オブジェクトを作成する。DirectXEvent オブジェクトは、クラスをフォームに実装することで作成される。このクラスの目的は、通知イベントを処理するためのコールバック メソッドを提供することにある。

DirectXEvent クラスには、DirectXEvent.DXCallback というメソッドが 1 つだけある。


DirectXEvent.DXCallback

DirectXEvent.DXCallback メソッドは、イベント ハンドルにコールバック ルーチンを提供する。

object.DXCallback(eventid As Long)

パラメータ

object
DirectXEvent オブジェクトを表すオブジェクト式。
eventid
イベントへのハンドル。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

フォームに DirectXEvent を実装するときは、DirectXEvent.DXCallback メソッドも実装する必要がある。[Object] ボックスの [DirectXEvent] と [Procedures/Events] ボックスの [DXCallback] をクリックすると、[Code] ウィンドウにメソッドの宣言と終了コードが自動的に設定される。次に、メソッドの形式を示す。

Private Sub DirectXEvent_DXCallBack(ByVal eventid as Long)
  ' 各自のイベント処理コードを追加する。
  .
  .
  .
End Sub

このメソッドに渡すイベント ハンドルは、ユーザーが DirectX7.CreateEvent を使用して作成したものである。

参照

DirectX7.SetEvent


参考資料

Windows プログラミングに関する一般情報、および DirectX を説明するときに使用したグラフィックやマルチメディアの概念や用語については、以下の資料を参照すること。

  • Bargen 氏、Bradley 氏、および Peter Donnelly 氏著の『Inside DirectX』、Microsoft Press 社により 1998 年に出版。
  • Begault 氏、Durand R. 氏著の『3-D Sound for Virtual Reality and Multimedia』、Academic Press 社により 1994 年に出版。
  • Blinn 氏、James 氏著の『Jim Blinn's Corner: A Trip Down the Graphics Pipeline』、Morgan Kaufmann 社により 1996 年に出版。
  • Foley 氏、James D. 氏著の『Computer Graphics: Principles and Practice』、Addison-Wesley 社により 1991 年に出版 (第 2 版)。
  • Hearn 氏、Donald 氏、および M. Pauline Baker 氏著の『Computer Graphics』、Prentice-Hall 社により 1986 年に出版。
  • Kientzle 氏、Tim 氏著の『A Programmer's Guide to Sound』、Addison-Wesley Developers Press 社により 1998 年に出版。
  • Petzold 氏、Charles 氏著の『Programming Windows 98』、Microsoft Press 社により 1998 年に出版 (第 5 版)。
  • Thompson 氏、Nigel 氏著の『3D Graphics Programming for Windows 95』、Microsoft Press 社により 1996 年に出版。
  • Watt 氏、Alan H. 氏、および Mark Watt 氏著の『Advanced Animation and Rendering Techniques』、Addison-Wesley 社により 1992 年に出版。

COM に関する概念や用語の詳細については、以下の資料を参照すること。

  • Brockschmidt 氏、Kraig 氏著の『Inside OLE 2』、Microsoft Press 社により 1995 年に出版 (第 2 版)。
  • Rogerson 氏、Dale E. 氏著の『Inside COM』、Microsoft Press 社により 1997 年に出版。

DirectX 7 を使用する際のノウハウやヒントなどを含む最新の技術文書については、http://www.microsoft.com/japan/developer/directx/ の「Technical Articles」を参照すること。


Direct3D 直接モード

Direct3D® 直接モード アプリケーション プログラミング インターフェイス (API) は、DirectX® の 3 次元 (3D) グラフィックス コンポーネントの一部である。ここでは、Direct3D 直接モードについて、以下のトピックに分けて説明する。

  • Direct3D 直接モードについて
  • Direct3D 直接モードを使用する理由
  • 直接モードの基礎知識
  • Direct3D 直接モード アーキテクチャ
  • Direct3D 直接モードの要点
  • Direct3D 直接モード チュートリアル
  • Direct3D 直接モード リファレンス
  • Direct3D 直接モードのツールとサンプル


Direct3D 直接モードについて

Direct3D は、Microsoft® Windows® 搭載のコンピュータ上で世界に通用するゲームやインタラクティブ 3D グラフィックスを使えるようにすることを目的に設計されている。Direct3D では、3D ビデオディスプレイ ハードウェアへのデバイスに依存したアクセスを、デバイスに依存しない方法で行うことができる。Direct3D は 3D ハードウェア向けの描画インターフェイスである。

Direct3D には、直接モードおよび保持モードの 2 つのモードがある。保持モードは、短時間での開発を必要としたり、階層構造やアニメーション用に保持モードがサポートする機能を利用するプログラマ向けの、上位レベル 3D API (application programming interface) である。

Direct3D 直接モードは、ゲームやその他の高性能マルチメディア アプリケーションを Windows オペレーティング システムに移植する必要がある開発者には理想的な下位レベル 3D API である。直接モードは、アクセラレータ ハードウェアと下位レベルでやり取りするアプリケーションのための方法で、デバイスには依存しない。Direct3D 保持モードは、直接モードの上位に構築されている。

次に示すのは、Direct3D の最新機能である。

  • 切り替え可能な深度バッファリング (Z バッファまたは W バッファを使用)
  • フラットおよびグーロー シェーディング
  • 複数の光源とライト タイプ
  • ミップマッピングなど、マテリアルおよびテクスチャの完全サポート
  • 強力なソフトウェア エミュレーション ドライバ
  • トランスフォームとクリッピング
  • ハードウェア非依存性
  • Windows 95、Windows 98、および Windows 2000 の完全サポート
  • Intel の MMX アーキテクチャのサポート

保持モードの代わりに直接モードを使用する開発者は、一般にはハイパフォーマンス プログラミングの経験があり、3D グラフィックスを経験しているかもしれない。この SDK 付属のサンプル コードは、直接モードについて理解するための最良の情報源である。サンプル コードは、実際のアプリケーションでの Direct3D 直接モードの使用方法を示す。


Direct3D 直接モードを使用する理由

直接モードのワールド管理は、頂点、ポリゴン、およびこれらを制御するコマンドに基づいて行われる。これによって、トランスフォーム、ライティング、ラスタ化 3D グラフィックス パイプラインに直接アクセスできる。ハードウェア アクセラレーションを利用してレンダリングできない場合、Direct3D は強力なソフトウェア エミュレーション機能を提供する。既存の 3D アプリケーションを持つ開発者や、アプリケーションとハードウェア間に可能な限り薄いレイヤを置いて最高のパフォーマンスを実現する必要のある開発者は、保持モードではなく直接モードを使用するとよい。

Direct3D 直接モードでは、シンプルで直接的なメソッドを使用して 3D シーンを設定およびレンダリングできる。レンダリング メソッドの主要セットは DrawPrimitive メソッドと呼ばれる。これらのメソッドにより、アプリケーションではメソッドの呼び出しを 1 回行うだけで、シーンの 1 つまたは複数のオブジェクトをレンダリングできる。これらのメソッドの詳細については、「DrawPrimitive メソッド」を参照すること。

直接モードでは、3D ハードウェアへの接続の際に発生するオーバーヘッドが低い。この接続を実現するためにはかなりの作業を要する。つまり、トランスフォームやライティングを実行するには明示的な呼び出しを行わなければならず、必要な行列はすべて提供し、存在するハードウェアの種類やその機能を調べる必要もある。


直接モードの基礎知識

以下のセクションでは、3D グラフィックスを組み込むプログラムを作成する前に理解しておく必要があるいくつかの技術的概念について説明する。これらの内容は一般的なものである。特定のトピックについては、「Direct3D 直接モード アーキテクチャ」および「Direct3D 直接モードの要点」を参照すること。

3D グラフィックスを作成した経験がある場合は、以下のセクションで Direct3D に特定の情報を参照できる。

このセクションには以下のトピックがある。

  • 3D 座標系とジオメトリ
  • 行列とトランスフォーム


3D 座標系とジオメトリ

Direct3D アプリケーションをプログラミングするには、3D ジオメトリ原理について理解している必要がある。このセクションでは、3D シーンの作成において最も重要なジオメトリ原理について説明する。以下のトピックについて記述する。

  • 3D 座標系
  • 3D プリミティブ
  • 三角形ラスタ化ルール
  • シェーディング

これらのトピックを参照すれば、Direct3D アプリケーションで用いる基本概念について簡単かつ十分に理解できる。これらのトピックの詳細については、「参考資料」を参照すること。


3D 座標系

一般に、3D グラフィックス アプリケーションではデカルト座標系の左手座標系と右手座標系のどちらかを使用する。どちらの座標系でも、x 軸の正方向は右側であり、y 軸の正方向は上方である。z 軸の正方向は、x 軸 の正方向に左手または右手の指を向け、それを y 軸の正の方向に回転した方向になる。親指の方向、手前または奥が、この座標系での z 軸の正方向である。

Direct3D では左手座標系を使用する。右手座標系に基づくアプリケーションを移植する場合は、Direct3D に渡すデータに 2 つの変更を加える必要がある。

  • 三角形の頂点の順序を反転し、システムが前から時計回りにたどれるようにする。つまり、頂点が v0、v1、v2 であるとすると、Direct3D に v0、v2、v1 として渡す。
  • ビュー行列を使用して、ワールド空間を z 軸方向に -1 だけスケーリングする。そのためには、ビュー行列に使用する D3DMATRIX 構造体の _31、_32、_33、および _34 の各メンバの符号を反転する (Visual Basic アプリケーションの場合も、D3DMATRIX 型の対応するメンバに対して同様の処理を実行できる)。

3D ソフトウェアでは、これらの座標系以外にもさまざまな座標系が使用されることもある。左手座標系と右手座標系は最もよく使用される座標系である。しかし、3D モデリング プログラムでは、y 軸がビューアの手前または奥を指し、z 軸が上方を指している座標系が使用されることも珍しくない。この場合、右手座標系は、どの軸 (x、y、または z) の正方向もビューアに近づく方向として定義される。左手座標系は、どの軸 (x、y、または z) の正方向もビューアから離れる方向として定義される。z 軸が上方を指している左手座標系を使用したモデリング プログラムを移植する場合は、既に説明した手順に加え、頂点データをすべて回転する必要がある。

3D 座標系で定義されたオブジェクトにおいて重要な操作は、平行移動、回転、およびスケーリングである。これらの基本的なトランスフォームを組み合わせてトランスフォーム行列を作成できる。詳細については、「3D トランスフォーム」を参照すること。

これらの操作を組み合わせるとき、その結果はその操作の順序に依存すること、つまり行列を乗算する順序が重要であることに注意する。


3D プリミティブ

3D プリミティブとは、単一の 3D 構成要素を形成する頂点の集合である。最も単純なプリミティブは、3D 座標系にある点の集合である。これを点リストと呼ぶ。

多くの場合、3D プリミティブはポリゴンである。ポリゴンとは、少なくとも 3 つの頂点が結ばれた閉じた 3D 図形である。最も単純なポリゴンは三角形である。三角形の 3 つの頂点はすべて同一平面上にあるため、Direct3D では三角形を使用してほとんどのポリゴンを形成する。同一平面上にない頂点のレンダリングは効率が悪い。三角形を組み合わせて大きく複雑なポリゴンやメッシュを形成できる。

次の図は立方体を示す。2 つの三角形で立方体の各面が形成されている。三角形の集合全体で 1 つのキューブ プリミティブが形成されている。プリミティブのサーフェスにテクスチャとマテリアルを適用して、プリミティブを単一のソリッド フォームのように表示できる。詳細については、「マテリアル」および「テクスチャ」を参照すること。

また、三角形を使用して、サーフェスが滑らかな曲線のように見えるプリミティブを作成できる。次の図は、三角形で球をシミュレートする方法を示す。マテリアルを適用すると、レンダリングしたときに曲面に見える。これは、特にグーロー シェーディングを使用する場合に当てはまる。詳細については、「グーロー シェーディング」を参照すること。


三角形ラスタ化ルール

頂点に指定された点はスクリーン上のピクセルと正確に一致しないことが多い。この場合、Direct3D は三角形ラスタ化ルールを適用して、どのピクセルが与えられた三角形に当てはまるかを決める。

Direct3D では、ジオメトリを塗りつぶすのに、左上フィリング変換を使用する。この変換は、GDI および OpenGL の矩形に使用する変換と同じである。Direct3D では、ピクセルの中心が重要なポイントである。ピクセルの中心が三角形の内部にある場合、そのピクセルはその三角形の一部である。ピクセルの中心は整数座標にある。

ここで説明する、Direct3D の三角形ラスタ化ルールが、利用可能なすべてのハードウェアに当てはまるとは限らない。現在のハードウェアを調べてみると、このルールの実装において若干の違いが見つかることもある。

次の図は、左上の角が (0, 0) で右下の角が (5, 5) の矩形を示す。この矩形は、予想されるとおり 25 ピクセルを占めている。矩形の幅は、右から左を減算した値で定義される。高さは、下から上を現在した値で定義される。

左上フィリング変換では、上は水平スパンの垂直位置座標を表し、左はあるスパン内のピクセルの水平位置座標を表す。エッジは、水平でない限り上のエッジではありえない。一般に、ほとんどの三角形では左エッジと右エッジがあるだけである。

左上フィリング変換によって、三角形がピクセルの中心を通過するときの Direct3D の処理が決まる。次の図は、頂点が (0, 0)、(5, 0)、(5, 5) の三角形と、頂点が (0, 5)、(0, 0)、(5, 5) の三角形を示す。この場合、前者の三角形は 15 ピクセルを占めるが、後者の三角形は 10 ピクセルしか占めない。共有しているエッジが前者の三角形の左のエッジだからである。

たとえば、左上の角が (0.5, 0.5) で右下の角が (2.5, 4.5) の矩形を定義する場合、この矩形の中心点は (1.5, 2.5) になる。Direct3D ラスタライザでこの矩形をラスタ化すると、各ピクセルの中心は明らかに 4 つの三角形のそれぞれの内部に存在し、左上フィリング変換は不要になる。次の図にこれを示す。矩形内部にあるピクセルには、Direct3D がそのピクセルを入れる三角形に対応したラベルが付けられている。

上の例の矩形を左上の角が (1.0, 1.0)、右下の角が (3.0, 5.0)、中心点が (2.0, 3.0) になるように移動すると、Direct3D は左上フィリング変換を適用する。次の図に示すように、この矩形内部のピクセルのほとんどは、2 つ以上の三角形の間の境界をまたがる。

どちらの矩形でも、同じピクセルが影響を受ける。


シェーディング

このセクションでは、3D ポリゴンのシェーディングを制御するために Direct3D で使用する技法について説明する。

  • シェーディング モード
  • シェーディング モードの比較
  • シェーディング モードの設定
  • 面法線ベクトルと頂点法線ベクトル
  • 三角形補間要素


シェーディング モード

ポリゴンのレンダリングに使用するシェーディング モードは、ポリゴンの表示に大きな影響を与える。シェーディング モードによって、ポリゴンの面の点の色とライティングの強度が決まる。現在、Direct3D では以下の 2 つのシェーディング モードをサポートしている。

  • フラット シェーディング
  • グーロー シェーディング


シェーディング モードの比較

フラット シェーディング モードの場合、次のピラミッドは隣接する面の間に鋭いエッジがあるように表示される。しかし、グーロー シェーディング モードでは、シェーディング値がエッジ全体に補間され、最終的にサーフェスは曲面のようになる。

グーロー シェーディング モードでは、フラット シェーディング モードの場合よりも、平坦なサーフェスでもよりリアル見える。フラット シェーディング モードの場合、サーフェスの色は一様であるが、グーロー シェーディング モードでは面全体でライティングを適切に弱めることができる。このエフェクトは、近くに点光源がある場合に特にはっきりする。

グーロー シェーディングは、フラット シェーディングで現れるポリゴン間の鋭いエッジを滑らかにする。ただし、グーロー シェーディングでは、マッハ バンドが生じる。マッハ バンドとは、隣接するポリゴンで色や光がスムーズにブレンドされていない帯を指す。オブジェクトのポリゴンの数を増やしたり、スクリーン解像度を高めたり、アプリケーションの色深度を上げることで、アプリケーション側でマッハ バンドを減らすことができる。

グーロー シェーディングでは、小さな部分でミスが生じることがある。次の図に例を示す。ここでは、スポット ライトが 1 枚のポリゴンの表面にだけ当てられている。

この場合、グーロー シェーディングが頂点間を補間することからスポット ライトがすべて失われ、まるでスポット ライトが存在しないかのように面がレンダリングされている。


シェーディング モードの設定

[C++]

Direct3D では、一度に 1 つのシェーディング モードしか選択できない。デフォルトでは、グーロー シェーディングが選択されている。C++ では、IDirect3DDevice7::SetRenderState メソッドを呼び出してシェーディング モードを変更できる。dwRenderStateType パラメータを D3DRENDERSTATE_SHADEMODE に設定する。dwRenderState パラメータには D3DSHADEMODE 列挙のメンバを設定する。次のサンプル コードは、Direct3D アプリケーションの現在のシェーディング モードを、フラット シェーディング モードまたはグーロー シェーディング モードに設定する方法を示す。

// フラット シェーディングに設定する。
// このコードでは、lpDev が IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
hr = lpDev->SetRenderState(D3DRENDERSTATE_SHADEMODE, D3DSHADE_FLAT);
if(FAILED(hr))
{
    // エラー処理コード
}

// グーロー シェーディングに設定する (Direct3D のデフォルト設定)。
hr = lpDev->SetRenderState(D3DRENDERSTATE_SHADEMODE,
                            D3DSHADE_GOURAUD);
if(FAILED(hr))
{
    // エラー処理コード
}
[Visual Basic]

Direct3D では、一度に 1 つのシェーディング モードしか選択できない。デフォルトでは、グーロー シェーディングが選択されている。Visual Basic では、Direct3DDevice7.SetRenderState メソッドを呼び出してシェーディング モードを変更できる。state パラメータを D3DRENDERSTATE_SHADEMODE に設定する。renderstate パラメータには、CONST_D3DSHADEMODE 列挙のメンバを設定する。次のサンプル コードは、Direct3D アプリケーションの現在のシェーディング モードを、フラット シェーディング モードまたはグーロー シェーディング モードに設定する方法を示す。

' フラット シェーディングに設定する。
' このコードでは、d3dDev が Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
On Local Error Resume Next
Call d3dDev.SetRenderState(D3DRENDERSTATE_SHADEMODE, _
                           D3DSHADE_FLAT)

' エラーを調べる。
If Err.Number <> DD_OK Then
    ' エラー処理
End If

' グーロー シェーディングに設定する (Direct3D のデフォルト設定)。
Call d3dDev.SetRenderState(D3DRENDERSTATE_SHADEMODE, _
                           D3DSHADE_GOURAUD)

If Err.Number <> DD_OK Then
    ' エラー処理
End If


面法線ベクトルと頂点法線ベクトル

メッシュの各面には、垂直の法線ベクトルがある。法線ベクトルの方向は、頂点が定義されている順序と、座標系が左手座標系か右手座標系かによって決まる。面の法線ベクトルは面の前面から離れる方向に向く。Direct3D では、面の前面のみ表示される。前面とは、各頂点が時計回りの順に定義された面である。

前面以外の面は背面である。Direct3D では、背面が常にレンダリングされるわけではない。これを背面カリングと言う (カリング モードを変更すれば背面をレンダリングできる)。詳細については、「カリング ステート」を参照すること。

Direct3D アプリケーションでは面法線を指定する必要はない。必要なときはシステムで自動的に計算される。システムでは、フラット シェーディング モードで面法線を使用する。グーロー シェーディング モードでは頂点法線を使用する。また、Direct3D はライティング エフェクトとテクスチャ エフェクトの制御にも頂点法線を使用する。

[C++]

C++ で記述された Direct3D アプリケーションでは、通常、頂点に D3DVERTEX 構造体を使用する。D3DVERTEX 構造体のメンバで、頂点の位置座標と方向を指定する。頂点の方向は頂点法線ベクトルで示される。次のコードは、頂点法線を含め頂点の値を設定する方法を示す。法線ベクトルはビューポートの方向を向き、ビューポートはワールド座標系の原点にある。この例では、頂点の位置座標はワールド座標で指定されている。

D3DVERTEX lpVertices[3];

// 1 つの頂点は 1 つの構造体で一度に指定できる。
lpVertices[0].x = 0;
lpVertices[0].y = 5;
lpVertices[0].z = 5;
lpVertices[0].nx = 0;    // 法線ベクトルの x 成分。
lpVertices[0].ny = 0;    // 法線ベクトルの y 成分。
lpVertices[0].nz = -1;   // 原点の裏の法線を指す。
lpVertices[0].tu = 0;    // テクスチャを使用する場合にのみ使用。
lpVertices[0].tv = 0;    // テクスチャを使用する場合にのみ使用。

// 頂点は、いくつかの D3DOVERLOADS マクロを使用することにより、
// 頂点ごとに 1 行のコードで指定することもできる。
lpVertices[1] = D3DVERTEX(D3DVECTOR(-5,-5,5),D3DVECTOR(0,0,-1),0,0);
lpVertices[2] = D3DVERTEX(D3DVECTOR(5,-5,5),D3DVECTOR(0,0,-1),0,0);
[Visual Basic]

Visual Basic で記述された Direct3D アプリケーションでは、通常、頂点に D3DVERTEX 型を使用する。D3DVERTEX 構造体のメンバで、頂点の位置座標と方向を指定する。頂点の方向は頂点法線ベクトルで示される。次のコードは、頂点法線を含め頂点の値を設定する方法を示す。法線ベクトルはビューポートの方向を向き、ビューポートはワールド座標系の原点にある。この例では、頂点の位置座標はワールド座標で指定されている。

D3DVERTEX Vertices(3)

' 1 つの頂点には、一度に 1 つの構造体メンバを指定できる。
Vertices(0).x = 0
Vertices(0).y = 5
Vertices(0).z = 5
Vertices(0).nx = 0    ' 法線ベクトルの x 成分。
Vertices(0).ny = 0;    ' 法線ベクトルの y 成分。
Vertices(0).nz = -1;   ' 原点の裏の法線を指す。
Vertices(0).tu = 0;    ' テクスチャを使用する場合にのみ使用。
Vertices(0).tv = 0;    ' テクスチャを使用する場合にのみ使用。

グーロー シェーディングをポリゴンに適用するとき、Direct3D では頂点法線を使用して光源とサーフェス間の角度を計算する。Direct3D では、頂点の色と強度の値を計算し、プリミティブのサーフェス全体のすべての点に対してこの値を補間する。Direct3D では、この角度を使用してライティングの強度の値を計算する。角度が大きいほど、サーフェスを照らす光が弱くなる。

平坦なオブジェクトを作成する場合、次の図に示すように、頂点法線をサーフェスに対して垂直に設定する。2 つの三角形で構成される平坦なサーフェスが定義されている。

しかし、通常はオブジェクトが三角形ストリップで構成され、それらの三角形が同一平面上にないことが多い。ストリップのすべての三角形全体に滑らかなシェーディングを施すには、まず頂点に関係付けられている各ポリゴンのサーフェスについて、面法線ベクトルを計算するのが簡単である。頂点法線は、その周りの各サーフェスの法線からの角度が等しくなるように設定できる。ただし、この方法はプリミティブが複雑な場合には効率的でないことがある。

この方法について次の図で説明する。この図では、S1 と S2 の 2 つのサーフェスがあり、上から見るとエッジが重なっている。S1 と S2 の法線ベクトルは青色で示す。頂点法線ベクトルは赤色で示す。S1 の面法線と頂点法線ベクトルのなす角度は、S2 の面法線と頂点法線のなす角度と同じである。これら 2 つのサーフェスにライトを当て、グーロー シェーディングで陰影を付けると、サーフェス間のエッジの陰影が滑らかになって丸みを帯びる。

頂点法線が、関係付けられているサーフェスのうち 1 つの方へ傾いている場合、光源と面の角度に応じてサーフェス上の点に対する光の強度が増加または減少する。この例を次の図で示す。この図でも、サーフェスのエッジは重なっている。頂点法線は S1 の方に傾いているので、S1 と光源の角度は、頂点法線と 2 つの面法線の角度が等しい場合よりも小さくなる。

グーロー シェーディングを使用して、鋭いエッジのあるオブジェクトを 3D シーンに表示できる。このためには、次の図に示すように、鋭いエッジが必要な、面が交差する位置座標 2 つの頂点でそれぞれの面と同じ法線ベクトルが必要だ。

[C++]

IDirect3DDevice7::DrawPrimitive または IDirect3DDevice7::DrawIndexedPrimitive メソッドを使用してシーンをレンダリングする場合、エッジが鋭いオブジェクトは、三角形ストリップではなく三角形リストとして定義する。オブジェクトを三角形ストリップとして定義すると、Direct3D ではそのオブジェクトを複数の三角形の面で構成された単一のポリゴンとして扱う。グーロー シェーディングは、ポリゴンの面全体および隣接する面との間の両方に適用される。その結果、オブジェクトの面の境が滑らかにシェーディングされる。三角形リストは、一連の独立した三角形の面から構成されるポリゴンなので、Direct3D ではポリゴンの各面にグーロー シェーディングを適用する。ただし、面と面の境にはグーロー シェーディングは適用されない。三角形リストの複数の三角形が隣接している場合、その三角形の間には鋭いエッジが表示される。

[Visual Basic]

Direct3DDevice7.DrawPrimitive または Direct3DDevice7.DrawIndexedPrimitive メソッドを使用してシーンをレンダリングする場合、エッジが鋭いオブジェクトは、三角形ストリップではなく三角形リストとして定義する。オブジェクトを三角形ストリップとして定義すると、Direct3D ではそのオブジェクトを複数の三角形の面で構成された単一のポリゴンとして扱う。グーロー シェーディングは、ポリゴンの面全体および隣接する面との間の両方に適用される。その結果、オブジェクトの面の境が滑らかにシェーディングされる。三角形リストは、一連の独立した三角形の面から構成されるポリゴンなので、Direct3D ではポリゴンの各面にグーロー シェーディングが適用される。ただし、面と面の境にはグーロー シェーディングは適用されない。三角形リストの複数の三角形が隣接している場合、その三角形の間には鋭いエッジが表示される。

また、エッジが鋭いオブジェクトをレンダリングするとき、フラット シェーディングに変更する方法もある。これはコンピュータには最も効率的であるが、グーロー シェーディングを適用したオブジェクトよりもリアリティに欠けるオブジェクトがシーンに表示される可能性がある。


三角形補間要素

システムでは、面をレンダリングするとき三角形全体で三角形の頂点の特性を補間する。三角形補間要素は次のとおりである。

  • 色
  • スペキュラ
  • アルファ

これらの三角形補間要素はすべて、現在のシェーディング モードによって変わる。

フラット | 補間は行われない。その代わり、三角形の最初の頂点の色が面全体に適用される。
グーロー | 線形補間が 3 つの頂点すべての間で実行される。

色補間要素とスペキュラ補間要素の処理は色モデルによって異なる。RGB 色モデルの場合、システムでは赤色、緑色、および青色成分を使用して補間を行う。モノクロ モデル、つまりランプ モデルの場合、システムでは頂点の色の青色成分のみ使用する。

色のアルファ成分は、別の補間要素として扱われる。理由は、テクスチャ ブレンディングと点描の 2 つの異なる方法で、デバイス ドライバが透明化を実行するためである。

C++ アプリケーションでは、D3DPRIMCAPS 構造体の dwShadeCaps メンバを使用して、現在のドライバがサポートしている補間の種類を決定する。同様に、Visual Basic アプリケーションでは、D3DPRIMCAPS 型の lShadeCaps メンバを使用してこの情報を利用する。


行列とトランスフォーム

Direct3D の行列を使用して、ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォームを定義する。3D グラフィックスのプログラミング未経験者は、ここの内容を学習してプログラムを始めるための重要な概念を理解しておく必要がある。3D プログラミングの経験者は、ここの内容は省略したり、以下のトピックについて簡単に目を通すだけでよい。

  • 行列
  • 3D トランスフォーム


行列

ここでの説明は、ユーザーが Direct3D で作業を行うために充分な行列についての基本的な知識を習得していることを前提としています。詳細については、「3D トランスフォーム」を参照すること。

Direct3D では、行列は 4ｴ4 同次行列で表され、C++ の場合は D3DMATRIX 構造体、Visual Basic の場合は D3DMATRIX 型で定義される。

[C++]

D3DMATRIX 構造体の D3D_OVERLOADS (D3DMATRIX (D3D_OVERLOADS)) を実装して、かっこ ("()") 演算子が使用できる。この演算子を使用すれば、行列の値に簡単にアクセスできる。名前で構造体メンバを参照する必要はなく、行および列番号でメンバを参照でき、必要に応じてこの番号をインデックスとして使用できる。このインデックスは 0 から始まり、たとえば、3 行 2 列の要素は M(2, 1) になる。D3D_OVERLOADS 演算子を使用するには、D3dtypes.h ヘッダー ファイルをインクルードする前に D3D_OVERLOADS を定義する。

また、D3dutil.cpp ソース ファイルには、行列の作成および連結を行うヘルパー関数がある。ヘルパー関数はそのまま使用できる。また、ヘルパー関数を基に独自の行列処理関数を作成することもできる。

[C++,Visual Basic]


3D トランスフォーム

Direct3D では、行列を使用して 3D トランスフォームを行う。このセクションでは、行列が 3D トランスフォームを作成する方法、トランスフォームによく使用される行列、および行列を組み合わせて複数のトランスフォームを行うある行列を生成する方法について説明する。説明するトピックは次のとおりである。

  • 3D トランスフォームについて
  • 平行移動
  • 回転
  • スケーリング
  • 行列連結

Direct3D 直接モードでのトランスフォームの詳細については、「ジオメトリ パイプライン」を参照すること。


3D トランスフォームについて

3D グラフィックスを処理するプログラムでは、ジオメトリ トランスフォームを使用して次のことができる。

  • オブジェクトの位置座標をほかのオブジェクトとの相対位置座標で表す。
  • オブジェクトを回転、およびサイズを変更する。
  • 位置座標視点、ビュー方向、およびパースペクティブを変更する。

4×4 行列を使用すると、任意の点を別の点にトランスフォームできる。次の例では、行列を使用して点 (x, y, z) をトランスフォームし、新しい点 (x', y', z') を生成する。

(x, y, z) に対する次の操作と行列を実行して点 (x', y', z') を生成する。

最も一般的なトランスフォームは、平行移動、回転、およびスケーリングである。これらのエフェクトを生成する行列を組み合わせて単一の行列を作成し、いくつかのトランスフォームを同時に計算できる。たとえば、一連の点を移動して回転させる単一の行列を作成できる。詳細については、「行列連結」を参照すること。

行列は、行と列の順序で記述する。頂点を各軸に対して均一にスケーリングする (一様なスケーリングと呼ばれる) 行列は、数学的には次のように表記される。

[C++]

C++ の場合、Direct3D 直接モードでは、D3DMATRIX 構造体を使用して行列を 2 次元配列として宣言する。次の例は、一様なスケーリングを行う行列として機能するように D3DMATRIX 構造体を初期化する方法を示す。

D3DMATRIX scale = {
    D3DVAL(s),    0,            0,            0,
    0,            D3DVAL(s),    0,            0,
    0,            0,            D3DVAL(s),    0,
    0,            0,            0,            D3DVAL(1)
};
[Visual Basic]

Visual Basic の場合、Direct3D 直接モードでは、D3DMATRIX 型を使用して 2 次元配列として宣言された行列を使用する。次の例は、一様なスケーリングを行う行列として機能するように D3DMATRIX 型を初期化する方法を示す。

Dim ScaleMatrix As D3DMATRIX

' この例では、s は Single 型の変数である
With ScaleMatrix
.rc11 = s
.rc22 = s
.rc33 = s
.rc44 = 1
End With


平行移動

次のトランスフォームは、点 (x, y, z) を新しい点 (x', y', z') に平行移動する。

[C++]

C++ では、独自の平行移動行列を作成できる。次の例は、頂点を平行移動するための行列を作成する関数のソース コードを示す。

D3DMATRIX Translate(const float dx, const float dy, const float dz)
{
D3DMATRIX ret = D3DUtil_SetIdentityMatrix(); // d3dutil.h に宣言される。
ret(3, 0) = dx;
ret(3, 1) = dy;
ret(3, 2) = dz;
return ret;
}    // 移動終了
[Visual Basic]

Visual Basic では、独自の平行移動行列を作成できる。また、この SDK 付属の Math.bas ファイルにある TranslateMatrix ヘルパー サブルーチンを使用することもできる。次の例は、TranslateMatrix サブルーチンのソース コードを示す。

Sub TranslateMatrix(m As D3DMATRIX, v As D3DVECTOR)
Call dx.IdentityMatrix(m) ' DirectX7 オブジェクトのメソッド。
m.rc41 = v.x
m.rc42 = v.y
m.rc43 = v.z
End Sub


回転

ここでは、左手座標系のトランスフォームについて説明する。したがって、これまでのトランスフォーム行列とは異なる場合もある。詳細については、「3D 座標系」を参照すること。

次のトランスフォームは、点 (x, y, z) を x 軸 を中心に回転して新しい点 (x', y', z') を生成する。

次のトランスフォームは、点を y 軸を中心に回転する。

次のトランスフォームは、点を z 軸を中心に回転する。

これらの行列の例では、ギリシャ文字シータ (θ) は、回転角度をラジアン単位で表している。角度は、回転軸を中心にして原点方向を向いた時計回りで測定したものである。

[C++]

C++ アプリケーションでは、D3dutil.cpp ファイル内の D3DUtil_SetRotateXMatrix、D3DUtil_SetRotateYMatrix、および D3DUtil_SetRotateZMatrix ヘルパー関数を使用して回転行列を作成する (D3dutil.cpp ファイルはこの SDK に付属している)。次は、D3DUtil_SetRotateXMatrix ヘルパー関数のサンプル コードである。

VOID D3DUtil_SetRotateXMatrix( D3DMATRIX& mat, FLOAT fRads )
{
D3DUtil_SetIdentityMatrix( mat );
mat._22 =  cosf( fRads );
mat._23 =  sinf( fRads );
mat._32 = -sinf( fRads );
mat._33 =  cosf( fRads );
}v
[Visual Basic]

Visual Basic アプリケーションでは、DirectX7.RotateXMatrix、DirectX7.RotateYMatrix、および DirectX7.RotateZMatrix メソッドを使用して回転行列を作成できる。

たとえば、x 軸を中心に回転する行列を手動で作成する場合は、次のようなソース コードになる。

Sub CreateXRotation(ret As D3DMATRIX, rads As Single)
    Dim cosine As Single
    Dim sine As Single
    cosine = Cos(rads)
    sine = Sin(rads)

    Call dx.IdentityMatrix(ret) ' DirectX7 オブジェクトのメソッド。

    ret.rc22 = cosine
    ret.rc23 = sine
    ret.rc32 = -sine
    ret.rc33 = cosine
End Sub


スケーリング

次のトランスフォームは、x、y、および z 方向の任意の値で点 (x, y, z) を新しい点 (x', y', z') にスケーリングする。


行列連結

行列を使用する主な利点の 1 つは、複数の行列を乗算してそれらのエフェクトを組み合わせることができるということである。つまり、モデルを回転し、次に別の位置座標に移動する場合、2 つの行列を適用する必要はない。その代わり、回転行列と平行移動行列を乗算して、すべてのエフェクトを持つ合成行列を生成する。この処理は行列連結と呼ばれ、次の公式で記述できる。

この公式では、C は作成する合成行列で、M1 ～ Mn は行列 C に含まれる個々のトランスフォームである。ほとんどの場合、2 つまたは 3 つの行列を連結するが、数に制限はない。

C++ アプリケーションでは、DirectX SDK. に付属する D3dmath.cpp ソース ファイルを使用できる。このファイルには行列を乗算する D3DMath_MatrixMultiply ヘルパー関数がある。Visual Basic アプリケーションの場合は、この SDK に付属する Math.bas ファイルの MatrixMult サブルーチンを使用できる。

行列を乗算するときは順序に注意する。この順序は重要である。上の公式は、行列連結の "左から右" 規則を反映している。つまり、合成行列を作成するために使用する行列の視覚エフェクトは、左から右の順で現われる。一般的なワールド トランスフォーム行列の例を次に示す。お決まりの "空飛ぶ円盤" 用のワールド トランスフォーム行列を作成すると仮定する。UFO をその中心 (モデル空間の y 軸) を軸として回転し、シーン内の任意の位置座標に移動する。このエフェクトを実現するには、次の式のように、まず平行移動行列を作成し、次にこの行列を回転行列で乗じる。

この公式では、Ry は y 軸を中心に回転する行列で、Tw はワールド座標の任意の位置座標への平行移動である。

これらの行列を乗算する順序は重要である。2 つのスカラー値を乗算する場合とは異なり、行列の乗算は可換的ではない。平行移動行列と回転行列を逆の順序で乗算すると、UFO がワールド空間位置座標に移動してから、ワールド座標の原点を中心に回転するというエフェクトが生じてしまう。

どのような行列を作成する場合でも、期待どおりのエフェクトを実現するためには "左から右" 規則を忘れてはならない。


Direct3D 直接モード アーキテクチャ

ここでは、Direct3D® 直接モードのドキュメントの構成に関する高度な内容について説明する。説明するトピックは次のとおりである。

  • 直接モード アーキテクチャの概要
  • 直接モード オブジェクト タイプ
  • 直接モード COM インターフェイス


直接モード アーキテクチャの概要

Direct3D アプリケーションでは、保持モードと直接モードのいずれの場合でも、同じような方法でグラフィックス ハードウェアとのやり取りを行う。HAL (ハードウェア エミュレーション レイヤ) と相互作用する前に、ソフトウェア エミュレーションを利用する場合または利用しない場合がある。Direct3D は DirectDraw® オブジェクトへのインターフェイスであるため、HAL は DirectDraw/Direct3D HAL と呼ばれる。

Direct3D は、DirectX® の DirectDraw コンポーネントと密接に統合されている。DirectDraw サーフェスは、レンダリング ターゲット (フロントおよびバック サーフェス) や Z バッファとして使用される。実際、Direct3D インターフェイスは、DirectDraw オブジェクトへのインターフェイスである。


直接モード オブジェクト タイプ

Direct3D 直接モードは、一連のオブジェクトから成る。C++ では、これらのオブジェクトを利用してバーチャル世界を操作したり、Direct3D アプリケーションを構築することができる。Visual Basic アプリケーションの場合も、DirectX for Visual Basic にはオブジェクト モデルに多少の違いがあるものの、最終的にはこれらのオブジェクトにアクセスする。

[C++]
DirectDraw オブジェクト
DirectDraw オブジェクトは、Direct3D の機能を提供する。IDirect3D、IDirect3D2、IDirect3D3、および IDirect3D7 は、DirectDraw オブジェクトへのインターフェイスである。DirectDraw オブジェクトはディスプレイ デバイスを表し、ディスプレイ デバイスは Direct3D の最も重要な機能の多くを実装していることから、Direct3D の機能は DirectDraw に組み込まれている。IDirect3D7 インターフェイスは、従来のものとはまったく異なるオブジェクトへのインターフェイスである。詳細については、「Direct3D インターフェイス」を参照すること。Direct3D の場合と同様、どのメソッドを使用して DirectDraw オブジェクトを作成するかによって、使用できるインターフェイスは異なる。

DirectDrawCreateEx 関数を呼び出して、最新の Direct3D インターフェイスをサポートする DirectDraw オブジェクトを作成する。詳細については、「Direct3D インターフェイス」を参照すること。

DirectDrawSurface オブジェクト
3D 機能 (DDSCAPS_3DDEVICE) を使用して作成した DirectDrawSurface オブジェクトは、サーフェスをレンダリング ターゲットとして使用する Direct3D デバイス オブジェクトを作成するために使用できる。アプリケーションでは、IDirect3D7::CreateDevice メソッドを呼び出してサーフェスからデバイスを作成する。

テクスチャマッピング機能を使用して作成した DirectDrawSurface オブジェクトには、Direct3D アプリケーションでシーン内のオブジェクトにテクスチャを適用する際に使用するビットマップが含まれる。アプリケーションでは、サーフェスの IDirectDrawSurface7 インターフェイスへのポインタを使用して Direct3D へのテクスチャを特定する。アプリケーションでは、IDirectDraw7::CreateSurface メソッドを呼び出すことにより、テクスチャを作成してそのインターフェイス ポインタを取得する (この点については以前のバージョンとは異なり、以前はこのメソッドでテクスチャを作成し、IUnknown::QueryInterface メソッドを呼び出してサーフェスの IDirect3DTexture2 インターフェイスを取得し、IID_IDirect3DTexture2 参照識別子を指定した)。

詳細については、「テクスチャ」を参照すること。

Direct3DDevice オブジェクト
Direct3DDevice オブジェクトは、直接モード アプリケーションのレンダリング ステートをカプセル化して格納する。Direct3D デバイスは、レンダリング ターゲットとして使用するサーフェスには依存せず、このデバイスを使用して複数のレンダリング ターゲット サーフェスをレンダリングすることができる (DirectX 5.0 以前ではできなかった)。DirectX 7.0 では、推奨デバイス オブジェクトは IDirect3DDevice7 インターフェイスである。Direct3D アプリケーションでは、IDirect3D7::CreateDevice メソッドを呼び出してデバイスを作成し、IDirect3DDevice7 インターフェイスへのポインタを取得できる。この方法で作成したデバイス オブジェクトのみ、最新のインターフェイスを公開する。詳細については、「デバイス インターフェイス」および「Direct3D デバイス」を参照すること。

従来とは異なり、IDirect3DDevice7 インターフェイスを公開するデバイス オブジェクトは、マテリアル、ライト、およびビューポートごとに個別のオブジェクトを使用しない。DirectX 7.0 では、このようなオブジェクトは実際には廃止されている。その代わり、これら従来のオブジェクトの機能をデバイスの内部データ構造の一部として提供するメソッドが、新しいインターフェイスに含まれている。

Direct3DVertexBuffer オブジェクト
Direct3DVertexBuffer オブジェクトはメモリ バッファであり、このオブジェクトには IDirect3DDevice7 インターフェイスの頂点バッファ レンダリング メソッドでレンダリングされる頂点が含まれる。頂点バッファを従来の実行バッファ アーキテクチャと混同してならない。頂点バッファには Direct3DDevice オブジェクトによって処理される頂点データのみ含まれ、レンダリングのパフォーマンスを改善する機能が提供される。頂点バッファを作成して、そのインターフェイスを取得するには、IDirect3D7::CreateVertexBuffer メソッドを呼び出す。

詳細については、「頂点バッファ」を参照すること。

[Visual Basic]

DirectX for Visual Basic では、Direct3D 直接モードでのプログラミング用に以下のクラスを公開している。

DirectX7 クラス
DirectX7 クラスは、Direct3D7、DirectDraw7 オブジェクトなど、その他すべてのコンポーネントレベルのオブジェクトを作成するために使用するオブジェクトを定義する。
DirectDraw7 クラス
DirectDraw7 クラスの役割は、ディスプレイ デバイスを表す、Direct3D7 クラスを生成する、およびレンダリング用のテクスチャとレンダリング ターゲット サーフェスを作成することである。DirectDraw7 クラスのオブジェクトを作成するには、DirectX7.DirectDrawCreate メソッドを呼び出す。
DirectDrawSurface7 クラス
DirectDrawSurface7 クラスは、表示用またはテクスチャ処理用の画像データ、あるいは Direct3D デバイスのレンダリング ターゲットとしての画像データを格納するたメモリを表す。DirectDraw7.CreateSurface メソッドを呼び出して空のサーフェスを作成するか、DirectDraw7.CreateSurfaceFromFile メソッドを呼び出してサーフェスを作成し、そのサーフェスにビットマップ ファイルから画像データをロードする。
Direct3D7 クラス
Direct3D7 クラスは、シーンをレンダリングするのに必要なオブジェクトを作成および操作する、Direct3D の機能を提供するオブジェクトを定義する。Direct3D7 クラスのオブジェクトを作成するには、DirectDraw7.GetDirect3D メソッドを呼び出す。
Direct3DDevice7 クラス
Direct3DDevice7 クラスは、Visual Basic で記述された直接モード アプリケーションのレンダリング ステート、ライティングとマテリアルのステート、およびビューポート パラメータをカプセル化して格納するオブジェクトを定義する。Direct3DDevice7 クラスのオブジェクトを作成するには、Direct3D7.CreateDevice メソッドを呼び出す。詳細については、「Direct3D デバイス」、「ライティングとマテリアル」、および「ビューポートとクリッピング」を参照すること。
Direct3DEnumDevices クラス
Direct3DEnumDevices クラスは、システムのレンダリング デバイスを列挙するオブジェクトを定義する。Direct3DEnumDevices クラスのオブジェクトを作成するには、Direct3D7.GetDevicesEnum メソッドを呼び出す。
Direct3DEnumPixelFormats クラス
Direct3DEnumPixelFormats クラスは、指定デバイス用にシステムでサポートされているピクセル フォーマットを列挙するオブジェクトを定義する。Direct3DEnumPixelFormats クラスのオブジェクトを作成するには、Direct3D7.GetEnumZBufferFormats または Direct3DDevice7.GetTextureFormatsEnum メソッドを呼び出す。
Direct3DVertexBuffer7 クラス
Direct3DVertexBuffer7 クラスは、頂点のメモリ バッファとして機能するオブジェクトを定義する。メモリ バッファ内の頂点は、Direct3DDevice7 クラスの頂点バッファ レンダリング メソッドを使用してレンダリングできる。Direct3D7.CreateVertexBuffer メソッドを呼び出して頂点バッファを作成する。

詳細については、「頂点バッファ」を参照すること。


直接モード COM インターフェイス

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、COM インターフェイスは公開されない。

[C++]

Direct3D 直接モード API は、主に次の COM インターフェイスで構成される。

IDirect3D7 | ルート インターフェイス。ほかのインターフェイスの取得に使用する。
IDirect3DDevice7 | DrawPrimitive ベースのプログラミング用 3D デバイス。
IDirect3DVertexBuffer7 | 頂点バッファを処理するインターフェイス。

DirectX の旧バージョンとの下位互換性を保つため、DirectX 7.0 では、従来のインターフェイスのバージョンをすべてサポートしている。ただし、新しいオブジェクトは最新のインターフェイスのみサポートする。詳細については、「Direct3D インターフェイス」および「デバイス インターフェイス」を参照すること。


Direct3D 直接モードの要点

Direct3D 直接モードは、オブジェクトを生成し、データを埋め込み、各オブジェクトを連結する比較的少数の API 要素から構成されている。API は COM に基づいている。直接モード API は、Direct3D ドライバの上部にある非常に薄いレイヤである。

このセクションでは、Direct3D 直接モードのコンポーネントの技術的な内容について説明する。説明するトピックは次のとおりである。

  • DirectX 7.0 での直接モードの変更点
  • Direct3D と DirectDraw
  • Direct3D デバイス
  • ジオメトリ パイプライン
  • ライティングとマテリアル
  • 頂点フォーマット
  • テクスチャ
  • 深度バッファ
  • ステンシル バッファ
  • 頂点バッファ
  • 共通のテクノロジと特殊効果
  • GUID
  • パフォーマンスの最適化
  • トラブルシューティング


DirectX 7.0 での直接モードの変更点

[Visual Basic]
Visual Basic アプリケーションのサポート
DirectX 7.0 のその他のコンポーネントと同様、Direct3D 直接モードでは現在、Visual Basic アプリケーションにサービスを提供する。このサービスの提供は、Visual Basic アプリケーションから DirectX ランタイムにデータを配置するクラス セットによって実現している。また、この SDK のドキュメントからは、Visual Basic 開発者も対象となっている。
[C++]

DirectX 7.0 では、旧リリースの DirectX のオブジェクトとインターフェイスを公開およびサポートすることにより、後方互換性を維持している。ただし、IDirect3D7 および IDirect3DDevice7 の 2 つの主要な Direct3D インターフェイスが DirectX 7.0 の構成要素として追加されている。これらのインターフェイスは、旧リリースのオブジェクトとは異なる新しいオブジェクトへのインターフェイスである。旧バージョンの DirectX のオブジェクトと比較した場合、これらの新しいオブジェクトにはいくつかの新機能があり、パフォーマンス向上を実現し、簡単に拡張することができる。

ハードウェア アクセラレーションによるトランスフォーム & ライティング
現在 Direct3D では、3D アクセラレータを利用してハードウェアでのトランスフォーム & ライティング処理を高速化している。対応ハードウェアが使用可能な場合、IDirect3D7::EnumDevices メソッドによって、対応する D3DDEVICEDESC7 構造体の dwDevCaps メンバに D3DDEVCAPS_HWTRANSFORMANDLIGHT 能力フラグを設定する。詳細については、「TnLHAL デバイス」を参照すること。
キューブ環境マップによる環境マッピング
現在 Direct3D および DirectDraw では、環境マッピングで使用する特殊なテクスチャ マップをサポートしており、これをキューブ環境マップと呼ぶ。キューブ環境マップを実行するときは、シーンのオブジェクトに適用する画像を含む 6 面テクスチャを使用する。キューブ環境マップにより、アプリケーションではリアルな環境マッピングを簡単に実行でき、動的な環境マッピングも可能である。
API の変更点
Direct3D for DirectX 7.0 では、ライティング、マテリアル、およびビューポートのパラメータをデバイス インターフェイスに移動する。したがって、これらのパラメータを処理する個別のオブジェクトは必要なく、そのインターフェイスも必要ない。これらのパラメータを処理するために、いくつかのメソッドが IDirect3DDevice7 インターフェイスに追加されている。

現在、頂点バッファはストライド頂点で使用できる。これは、IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドを新しい IDirect3DVertexBuffer7 インターフェイスに追加することで実現されている。

ジオメトリ ブレンディング
Direct3D ジオメトリ パイプラインを使用するアプリケーションでは、新たにサポートされるジオメトリ ブレンディングを利用できる。ジオメトリ ブレンディングは、特にキャラクタなどシーン内の個々のオブジェクトをリアルに表現する "スキニング" エフェクトを施す。詳細については、「ジオメトリ ブレンディング」を参照すること。
デバイス ステート ブロック
IDirect3DDevice7 インターフェイスを対象とするアプリケーションでは、プログラム可能なステート変更セットを利用でき、これをステート ブロックと呼ぶ。ステート ブロックにより、Direct3D アプリケーションではデバイスのステート変更を共通の順序で、固有の識別子、つまりブロック ハンドルを持つ構成要素に記録できる。アプリケーションでは、ブロック ハンドルを使用して、以前に記録されたステート ブロックを 1 回のメソッド呼び出しで実行できる。ステート ブロックにより、呼び出しを最小限に抑えてデバイス ステートを変更できるほかにも、デバイスでは実行を最適化するためにステート変更のプリコンパイル済みセットをキャッシュしておくことができる。これにより通常はパフォーマンスが向上する。詳細については、「ステート ブロック」を参照すること。
テクスチャ管理の向上
Direct3D テクスチャ マネージャが、アプリケーション側で管理下のテクスチャに優先順位を付けることができるように拡張されている。Direct3D では、テクスチャの優先順位に従って、メモリに保持するテクスチャや、メモリから削除するテクスチャを決定する。
Visual Basic アプリケーションのサポート
DirectX 7.0 のその他のコンポーネントと同様、Direct3D 直接モードでは現在、Visual Basic アプリケーションにサービスを提供する。このサービスの提供は、Visual Basic アプリケーションから DirectX ランタイムにデータを配置するクラス セットによって実現している。また、この SDK のドキュメントからは、Visual Basic 開発者も対象となっている。
拡張ソフトウェア エミュレーション
Direct3D は、CPU でサポートされる特殊な命令を使用できるように最適化されている。サポートされる命令セットには、いくつかの AMD プロセッサの AMD 3D-Now! 命令セットや、多くの Itel プロセッサでサポートされる MMX 命令セットなどがある。これらの命令セットが使用可能な場合、Direct3D では 3D-Now! 命令セットを利用してトランスフォーム & ライティング処理を高速化し、MMX 命令セット利用してラスタ化を高速化する。Direct3D のトランスフォーム & ライティング パイプラインを使用するアプリケーションでは、この機能によって自動的に高速処理が実現する。

Direct3D オブジェクトの新しいセットへの移行では多少の犠牲が生じる。Direct3D オブジェクトは、サポートするインターフェイスの名前には関係なく、旧リリースで対応するオブジェクトとは異なるもので、同じインターフェイスをサポートしていない。IUnknown::QueryInterface を使用しても、新しいインターフェイスをサポートするオブジェクトからは従来のインターフェイスを取得できない。また、従来のオブジェクトから新しいインターフェイスを問い合わせることもできない。これらの処理の実行は失敗し、E_NOINTERFACE が返される。

レンダリングに実行バッファを使用する既存のアプリケーションでは、その実行バッファ アーキテクチャを破棄しない限り、新しいオブジェクトを使用することはできない。実行バッファ アーキテクチャを破棄しないのであれば、従来のオブジェクト (引き続きサポートされる予定) を使用しなければならない。実際、実行バッファのレンダリングは一般には行われなくなっている。このことから、実行バッファの使用については、このドキュメントでは説明しない。


Direct3D と DirectDraw

このセクションでは、Direct3D と DirectDraw の密接な関係について説明する。説明するトピックは次のとおりである。

  • DirectDraw オブジェクトと Direct3D
  • Direct3D インターフェイス
  • Direct3D へのアクセス
  • Direct3D の従属オブジェクトの作成
  • DirectDraw 協調レベルと FPU 精度


DirectDraw オブジェクトと Direct3D

Direct3D は、COM オブジェクトとインターフェイスによって実装される。C++ で記述されたアプリケーションからはこれらのインターフェイスとオブジェクトに直接アクセスできるが、Visual Basic アプリケーションの場合は、Visual Basic アプリケーションから DirectX ランタイムにデータを配置する、DirectX for Visual Basic クラスとして現れるコード レイヤとの相互処理を行う。ここでは、C++ に固有の情報として、DirectDraw と Direct3D 間の重要な関係について説明する。さらに、その後で、DirectX for Visual Basic で公開されるクラス間の同様の関係について詳しく説明する。

[C++]

Direct3D インターフェイスは、実際には DirectDraw オブジェクトへのインターフェイスである。DirectDraw では、DirectDraw と Direct3D の両方のステートをカプセル化する単一の統一オブジェクトを使用できる。DirectDraw オブジェクトは、アプリケーションで最初に作成され、最後に解放されるオブジェクトである。DirectDraw オブジェクトはディスプレイ デバイスを表し、ディスプレイ デバイスは Direct3D の最も重要な機能の多くを実装していることから、Direct3D の機能は DirectDraw に組み込まれている。

注 : DirectX 7.0 では、Direct3D にアクセスする DirectDraw オブジェクトを 2 つの方法で作成できる。1 つは新しい DirectDrawCreateEx 関数を使用する方法で、もう 1 つは旧リリースの DirectX の DirectDrawCreate 関数を使用する方法である。DirectDrawCreateEx 関数は、DirectX 7.0 の Direct3D インターフェイスの最新セットを公開できる DirectDraw オブジェクトを作成する。一方、DirectDrawCreate 関数も DirectDraw オブジェクトを作成するが、このオブジェクトは DirectX 7.0 の機能をサポートする Direct3D インターフェイスを生成することはできない。このドキュメントでは、すべてのアプリケーションで DirectDrawCreateEx 関数を使用して DirectDraw オブジェクトが作成されることを前提とする。詳細については、「Direct3D インターフェイス」および「デバイス インターフェイス」を参照すること。

つまり、Direct3D ドライバのステートの寿命は DirectDraw オブジェクトの寿命と同じである。Direct3D インターフェイスを解放しても、Direct3D ドライバのステートは破壊されない。このステートが破壊されるのは、DirectDraw 参照の場合でも Direct3D 参照の場合でも、DirectDraw オブジェクトへの参照がすべて解放されるときである。したがって、DirectDraw ドライバ インターフェイスへの参照を保持している間に Direct3D インターフェイスをいったん解放しても、その後で再び Direct3D インターフェイスを問い合わせると、Direct3D のステートが保持されている。

DirectDrawCreateEx 関数で作成した DirectDraw オブジェクトには、単一の Direct3D インターフェイス IDirect3D7 が含まれる (従来の DirectDrawCreate 関数で作成した DirectDraw オブジェクトの場合は、従来のインターフェイス IDirect3D、IDirect3D2、および IDirect3D3 がサポートされる。これらのインターフェイスは現在は使用されていないが、後方互換性のために提供される)。新しいアプリケーションでは、IDirect3D7 インターフェイスを使用してほかの Direct3D オブジェクトを作成する必要がある。詳細については、「Direct3D インターフェイス」を参照すること。

[Visual Basic]

DirectDraw と Direct3D は、実際のところ、基本的には同じルート オブジェクトであり、同じコードを多数共有するにもかかわらず、DirectX for Visual Basic ではこれらのオブジェクトの使用方法に応じて、機能的に異なるクラスとして公開される。DirectX for Visual Basic では、アプリケーションでオブジェクトを作成するときの基になる DirectDraw7 および Direct3D7 クラスを使用する。(このトピックの C++ の部分で説明したように) DirectDraw と Direct3D の基本となる関係は、Visual Basic の内部からでも明らかである。グローバル DirectX7 クラスには、DirectDraw7 オブジェクトを作成するメソッドが含まれているが、Direct3D 用の同様のメソッドは含まれていない。その代わり、DirectDraw7 クラスは Direct3D7 クラスを取得するメソッドを定義し、このメソッドは DirectDraw7.GetDirect3D と呼ばれる。これら 2 つのクラスは、実際には DirectX 内の同じオブジェクトを参照するためである。

GetDirect3D メソッドは新しいオブジェクトを作成しない。その代わり、Direct3D 関連機能を公開する新しいクラスを作成する。このとき公開されるのは、このクラスを作成した DirectDraw オブジェクトによって提供される Direct3D 関連機能である。

DirectDraw7 クラスにはディスプレイ デバイス用の 2D 機能があり、Direct3D7 クラスにはデバイス用の 3D 機能がある。DirectDraw7 クラスを使用して、Direct3D クラスでレンダリング ターゲット、深度バッファ、およびテクスチャに使用するサーフェスを作成する。その後、Direct3D クラスを使用して、頂点バッファ、列挙クラスなど Direct3D オブジェクトで必要となる従属オブジェクトを作成する。


Direct3D インターフェイス

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、アプリケーションへの COM インターフェイスは直接には公開されない。

[C++]

Direct3D オブジェクトの機能を利用するには、インターフェイス IDirect3D、IDirect3D2、IDirect3D3、および IDirect3D7 を使用する。このセクションでは、DirectX 7.0 で導入された IDirect3D7 インターフェイスから順に IDirect3D インターフェイスまで、これら 3 つのインターフェイスの概要について説明する。

IDirect3D7 インターフェイス
IDirect3D7 インターフェイスは、名前からは従来のものと同じような印象を受けるが、実際にはまったく新しい Direct3D オブジェクトへのインターフェイスを表す。このオブジェクトは DrawPrimitive アーキテクチャをサポートおよび拡張するが、このトピックで既に説明した従来のインターフェイスはサポートしない。アプリケーションは、DirectDrawCreateEx 関数を呼び出して作成された DirectDraw オブジェクトの QueryInterface メソッドを呼び出すことによって、IDirect3D7 インターフェイスへのポインタを取得する。

IDirect3D7 インターフェイスは、アプリケーションでのレンダリング デバイスおよび頂点バッファの作成、ピクセル フォーマットの列挙など、IDirect3D3 インターフェイスと同じ機能を多数サポートしている。このインターフェイスは、テクスチャ作成機能を追加するため、テクスチャ インターフェイスについて DirectDraw サーフェスを問い合わせる必要はなくなる。

IDirect3D7 とその他のインターフェイスとの大きな違いは、ライティング、マテリアル、またはビューポート オブジェクトを作成するメソッドがないことである。このことは、IDirect3DDevice7 インターフェイスでの処理に反映されており、ライティング、マテリアル、およびビューポート パラメータを個別のオブジェクトとしてではなく、デバイスの内部データ構造の一部として組み込む。

IDirect3D7 オブジェクトは、「DirectX 7.0 での直接モードの変更点」で説明する機能をサポートする。

アプリケーションは、新しい IDirectDraw7 インターフェイスの QueryInterface メソッドを使用して IDirect3D7 インターフェイスへのポインタを取得する。詳細については、「Direct3D へのアクセス」を参照すること。

IDirect3D2 および IDirect3D3 インターフェイス
アプリケーションは、(新しい DirectDrawCreateEx 関数とは対照的に) DirectDrawCreate 関数で作成された DirectDraw オブジェクトから従来の IDirect3D2 および IDirect3D3 インターフェイスへのポインタを取得する。これらのインターフェイスは、DirectDraw オブジェクトの QueryInterface メソッドを呼び出して取得する。これらのインターフェイスを使用することにより、アプリケーションは、特定の DirectDraw オブジェクトがサポートする Direct3D デバイスのタイプを検出して列挙できる。また、これらのインターフェイスは、ビューポート、マテリアル、ライティングなどその他の Direct3D 直接モード オブジェクトの作成に必要なメソッドも公開する (ライティング、マテリアル、およびビューポートを個別のオブジェクトとして扱うという概念は、IDirect3D7 インターフェイスでは廃止されている)。

IDirect3D2 と IDirect3D との最も重要な違いは、IDirect3D2 が IDirect3D2::CreateDevice メソッドを実装しているという点である。このメソッドは、DrawPrimitive をサポートする Direct3D デバイスを作成する。IDirect3D2::CreateDevice メソッドで作成されるデバイスの詳細については、「Direct3D デバイス」を参照すること。

IDirect3D2 インターフェイスと同様、IDirect3D3 インターフェイスは Direct3D プログラミングの DrawPrimitive スタイルをサポートしている。さらに、IDirect3D3 インターフェイスは、IDirect3DDevice3 インターフェイスを導入することで DrawPrimitive スタイルの機能を拡張する。このインターフェイスにより、柔軟な頂点フォーマット、頂点バッファ、および新しいテクスチャ機能の概念が導入されている。詳細については、「頂点フォーマット」、「テクスチャ」、「頂点バッファ」、および「レンダリング」を参照すること。

アプリケーションは、QueryInterface メソッドを使用して DirectDraw オブジェクトから IDirect3D3 インターフェイスへのポインタを取得する。

IDirect3D インターフェイス
IDirect3D インターフェイスは、実行バッファの使用をサポートする。このインターフェイスは、既存のコードとの互換性のために用意されている。新しいアプリケーションでは IDirect3D7 インターフェイスを使用する。アプリケーションで実行バッファを使用している場合は、DirectX 7.0 が提供する機能には移行できない。詳細については、「DirectX 7.0 での直接モードの変更点」を参照すること。


Direct3D へのアクセス

[C++]

C++ で記述された Direct3D アプリケーションでは、起動時に、Direct3D の最新機能を利用するために IDirect3D7 インターフェイスへのポインタを取得しなければならない。以下の手順に従って、IDirect3D7 インターフェイスへのポインタを取得する。

IDirect3D7 インターフェイスへのポインタを取得するには

  1. DirectDrawCreateEx を呼び出して DirectDraw デバイスを作成する。アプリケーションでは、DirectDrawCreateEx 関数を使用して、IDirect3D7 をサポートする DirectDraw オブジェクトを作成しなければならない。DirectDrawCreate 関数で作成した DirectDraw オブジェクトは、IDirect3D7 インターフェイスをサポートしない。
  2. IUnknown::QueryInterface メソッドを呼び出して IDirect3D7 インターフェイスへのポインタを取得する。

次の図は、これらの手順を示し、その過程を従来のアプリケーションで必要なものに関連させている。

注 : この図に示すように、DirectDraw コンポーネントは 2 つの COM オブジェクトから構成されている。DirectDrawCreateEx 関数を呼び出して作成される、DirectDraw7 と呼ばれる最新のオブジェクトのみ、IDirect3D7 インターフェイスを公開する。DirectDraw7 オブジェクトは、従来の Direct3D インターフェイスは公開しない。従来の Direct3D が必要なアプリケーションでは、DirectDrawCreate メソッドを使用して DirectDraw オブジェクトを作成し、その後でそのインターフェイスを問い合わせなければならない。

次のコードは、DirectDraw7 オブジェクトの作成方法と、IDirect3D7 インターフェイスの問い合わせ方法を示す。

LPDIRECTDRAW7   lpDD;               // IDirectDraw7 インターフェイス。
LPDIRECT3D7     lpD3D;              // IDirect3D7 インターフェイス。
HRESULT hr;

// IDirect3D7 インターフェイスを取得する。
// 現在のディスプレイ ドライバを使用する。
hr = DirectDrawCreateEx (NULL, (void **)&lpDD, IID_IDirectDraw7, NULL);
if (FAILED (hr))
{
    // エラー処理コード。
}

// D3D インターフェイスを取得する。
hr = lpDD->QueryInterface (IID_IDirect3D7, (void **)&lpD3D);
if (FAILED (hr))
{
    // エラー処理コード
}
[Visual Basic]

Visual Basic で記述された Direct3D アプリケーションでは、起動時に、Direct3D 機能を利用するために Direct3D7 クラスへの参照を取得しなければならない。以下の手順に従って参照を取得する。

Direct3D7 クラスへの参照を取得するには

  1. DirectX7.DirectDrawCreate を呼び出して DirectDraw7 クラス オブジェクトを作成する。
  2. DirectDraw7.GetDirect3D メソッドを呼び出して、Direct3D7 クラスへの DirectDraw オブジェクトの参照を取得する。

次の図は、これらの手順を示す。

次のコードは、DirectDraw7 クラス オブジェクトから Direct3D7 クラスを取得する方法を示す。

' Direct3D7 クラスへの参照を取得する。
'
' この例では、dx は DirectX7 クラスへの有効な参照である。
On Local Error Resume Next
Dim ddraw As DirectDraw7
Dim d3d As Direct3D7

' デフォルトの DirectDraw7 オブジェクトを作成する。
Set ddraw = dx.DirectDrawCreate("")
If (Err.Number <> DD_OK) Then
' エラー処理
End If

' DirectDraw7 オブジェクトから Direct3D7 参照を取得する。
Set d3d = ddraw.GetDirect3D
If (Err.Number <> DD_OK) Then
' エラー処理
End If


Direct3D の従属オブジェクトの作成

[C++]

C++ で記述されたアプリケーションでは、IDirect3D7 インターフェイスを使用して、Direct3D レンダリング デバイスと頂点バッファを作成する。Direct3D アプリケーションでは、IDirect3D7::CreateDevice メソッドを呼び出してレンダリング デバイスを作成する。詳細については、「Direct3D デバイス」を参照すること。レンダリング デバイスには、レンダリング、ライティング、マテリアル、およびビューポート ステートが含まれる。

IDirect3D7::CreateVertexBuffer メソッドを呼び出してビューポート オブジェクトを作成する。頂点バッファには、頂点データの単純な配列よりもすばやくレンダリングを行うために特別に用意された頂点データが含まれる。詳細については、「頂点バッファ」を参照すること。

[Visual Basic]

Visual Basic で記述されたアプリケーションでは、Direct3D7 クラスのメソッドを使用して、Direct3D レンダリング デバイスと頂点バッファを作成する。Direct3D アプリケーションでは、Direct3D7.CreateDevice メソッドを呼び出してレンダリング デバイスを作成する。詳細については、「Direct3D デバイス」を参照すること。レンダリング デバイスには、レンダリング、ライティング、マテリアル、およびビューポート ステートが含まれる。

Direct3D7.CreateVertexBuffer メソッドを呼び出して頂点バッファを作成する。頂点バッファには、頂点データの単純な配列よりもすばやくレンダリングを行うために特別に用意された頂点データが含まれる。詳細については、「頂点バッファ」を参照すること。


DirectDraw 協調レベルと FPU 精度

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、浮動小数点単位 (FPU: floating-point unit) 精度の変更をサポートしていない。

[C++]

Direct3D では、常に単精度浮動小数点計算を使用して、3D シーンのレンダリングのパフォーマンスを向上させる。デフォルトでは、IDirect3DDevice7 インターフェイスをサポートするレンダリング デバイスを作成するとき、Direct3D は FPU を単精度、直近値丸めモードで例外無効に設定する。この時点から、そのデバイスが解放されるまでは FPU のステートは変更されないことが前提となり、デバイスが解放されると FPU は倍精度モードにリセットされる。

注 : このようなシステム動作は、従来の IDirect3DDevice3 インターフェイスのものとは異なる。IDirect3DDevice3 を公開するデバイスは、前の IDirectDraw4::SetCooperative メソッドの呼び出しで DirectDraw 協調レベルを設定したときに DDSCL_FPUSETUP フラグが使用されていない場合に限り、各レンダリング パスの FPU モードをチェックする。

倍精度の精度が必要なアプリケーションでは、IDirectDraw7::SetCooperativeLevel メソッドを呼び出して DirectDraw 協調レベルを設定するときに DDSCL_FPUPRESERVE フラグを含めることができる。DDSCL_FPUPRESERVE フラグを使用すると、単精度モードが使用されるが、精度モードを変更する前に FPU のステートが保存され、制御をアプリケーションに返すときに元のモードが復元される (DDSCL_FPUSETUP フラグを使用して再度メソッドを呼び出すと、Direct3D はデフォルトの動作に戻る)。このチェック、保存、および復元処理には明らかに時間がかかり、パフォーマンスに大きく影響することもある。このフラグは、アプリケーションで倍精度を使用する必要があり、アプリケーションでの必要に応じて FPU モードを手動で設定および復元するコードを含めない場合にのみ使用するようにする。

浮動小数点精度はスレッド固有であるため、マルチ スレッド アプリケーションを開発するときは、FPU の精度ステートをチェックして、スレッドごとに設定とリセットが適切に行われているかどうかを確認する必要がある。

重要 一部のダイナミック リンク ライブラリ (DLL) を実行時にロードすると、FPU が倍精度モードにリセットされることがある。Visual C++ などのコンパイラは、C/C++ ランタイム コンポーネントを初期化する _DllMainCrtStartup にデフォルトの DLL エントリ ポイントを設定する。この関数も、FPU 精度モードを倍精度に設定する。アプリケーションが DDSCL_FPUSETUP 協調レベルを設定した後て DLL をロードすると、Direct3D は FPU がリセットされたことを検出できないため、パフォーマンスに影響する。

実行時に DLL をロードする場合は、LoadLibrary Win32 関数が戻った直後と Direct3D 関数を呼び出す前に、FPU 精度をチェックしてリセットする必要がある。精度モードをリセットするには、明示的にリセットするか、DDSCL_FPUSETUP フラグを設定して IDirectDraw7::SetCooperativeLevel メソッドを再度呼び出す。SetCooperativeLevel を使用して FPU 精度モードを設定すると、DirectDraw サーフェイスが失われる。

/ENTRY: リンカ スイッチを使用すれば、コンパイルする DLL のエントリ ポイントを明示的に設定できる。ただし、この場合、C/C++ ランタイムは自動的には初期化されない。

次に示すのは、インライン アセンブリ言語を使用して、FPU 精度の設定をチェックおよび設定するコンソール アプリケーション用のサンプル ソース ファイルである。

#include <windows.h>
#include <math.h>

// この関数は、
// 浮動小数点制御語が、単精度/直近値丸め/例外無効に設定されているかどうかを
// 評価する。設定されていない場合、
// 関数は制御語を変更して条件を設定し、TRUE を返す。
// 古い制御語値は、pwOldCW が
// ポイントするパスバック位置座標に配置する。
BOOL MungeFPCW( WORD *pwOldCW )
{
    BOOL ret = FALSE;
    WORD wTemp, wSave;

    __asm fstcw wSave
    if (wSave & 0x300 ||            // 単精度モードではない。
        0x3f != (wSave & 0x3f) ||   // 例外有効。
        wSave & 0xC00)              // 直近値丸めモードではない。
    {
        __asm
        {
            mov ax, wSave
            and ax, not 300h    ;; 単精度モード。
            or  ax, 3fh         ;; すべての例外無効。
            and ax, not 0xC00   ;; 直近値丸めモード
            mov wTemp, ax
            fldcw   wTemp
        }
        ret = TRUE;
    }
    *pwOldCW = wSave;
    return ret;
}

void RestoreFPCW(WORD wSave)
{
    __asm fldcw wSave
}

void __cdecl main()
{
    WORD wOldCW;
    BOOL bChangedFPCW = MungeFPCW( &wOldCW );
    // MungeFPCW の設定に従って制御語を処理する。
    if ( bChangedFPCW )
        RestoreFPCW( wOldCW );
}


Direct3D デバイス

このセクションでは、Direct3D デバイスの概要について説明する。説明するトピックは次のとおりである。

  • Direct3D デバイスとは
  • Direct3D デバイスの種類
  • デバイス インターフェイス
  • デバイス ステート
  • デバイスの使用
  • AGP サーフェスと Direct3D デバイス


Direct3D デバイスとは

Direct3D デバイスとは、Direct3D のレンダリング コンポーネントである。これはレンダリング ステートをカプセル化して保存する。さらに、Direct3D デバイスは、トランスフォーム & ライティング処理を実行し、DirectDraw サーフェスに画像をラスタライズする。次の図に示すように、Direct3D デバイスのアーキテクチャは、トランスフォーム、ライティング、およびラスタ化モジュールから構成される。

Direct3D デバイスのトランスフォーム & ライティング モジュールを使用せずに、アプリケーション独自のトランスフォーム & ライティング モデルを使用することもできる。詳細については、「頂点フォーマット」を参照すること。

[C++]

C++ には、レンダリングに使用できる IDirect3DDevice、IDirect3DDevice2、IDirect3DDevice3、および IDirect3DDevice7 の 4 つの COM インターフェイスがある。このドキュメントでは、アプリケーションで最新バージョンのインターフェイスを使用することを前提としている。詳細については、「デバイス インターフェイス」を参照すること。

[Visual Basic]

DirectX for Visual Basic では、Direct3DDevice7 クラスを介して Direct3D 直接モードのデバイスにアクセスする。Direct3DDevice7 クラスは、シーンレンダリング メソッドの DrawPrimitive ファミリをサポートする。Direct3DDevice7 オブジェクトは、アプリケーションで必要な場合、さまざまな DirectDraw サーフェスをレンダリング ターゲットとして使用できる。詳細については、「Direct3DDevice7.SetRenderTarget」を参照すること。


Direct3D デバイスの種類

このセクションでは、Direct3D デバイスについて、およびデバイスの各種類について説明する。説明するトピックは次のとおりである。

  • デバイスの種類について
  • HAL デバイス
  • TnLHAL デバイス
  • RGB デバイス
  • リファレンス ラスタライザ
  • 従来のデバイスの種類


デバイスの種類について

Direct3D が現在サポートしている Direct3D デバイスには、HAL デバイス、トランスフォーム & ライティングのアクセラレーションをサポートした TnLHAL デバイス、ソフトウェアエミュレーション RGB デバイス、およびリファレンス ラスタライザの 4 種類がある。最初の 2 種類のデバイスはアプリケーションを出荷するために使用でき、リファレンス ラスタライザは機能テスト用にサポートされている。

[C++]

注 : 旧リリースの DirectX で公開されていた追加デバイスの MMX およびランプ デバイスは現在使用されていない。これらのデバイスは、旧バージョンの Direct3D を対象とする C++ アプリケーションでは現在も使用できるが、最新のインターフェイスではサポートされていない。詳細については、「従来のデバイスの種類」を参照すること。

アプリケーションが作成する Direct3D デバイスは、アプリケーションが動作するハードウェアの機能に対応していなければならない。Direct3D では、コンピュータにインストールされている 3D ハードウェアにアクセスするか、ソフトウェアで 3D ハードウェア機能をエミュレートするかのいずれかの方法で、レンダリング機能を利用する。したがって、Direct3D は、ハードウェア アクセス用およびソフトウェア エミュレーション用の両方のデバイスを備えている。

ハードウェア アクセラレーション デバイスは、ソフトウェア エミュレーション デバイスよりも高いパフォーマンスを実現する。ほとんどの場合、アプリケーションが対象とするのは、何らかのハードウェア アクセラレーションを備えたコンピュータであり、ローエンド コンピュータに対してはソフトウェア エミュレーション機能を使用する。

リファレンス ラスタライザを除き、ソフトウェア デバイスは、常にハードウェア デバイスと同じ機能をサポートしているわけではない。たとえば、ソフトウェア デバイスは、テクスチャを一度に複数のテクスチャ ステージに割り当てる機能をサポートしていない。アプリケーションは、デバイス機能を調べて、サポートされている機能を確認する必要がある。

[C++,Visual Basic]


HAL デバイス

アプリケーションが動作するコンピュータに、Direct3D をサポートするディスプレイ アダプタが装着されている場合、アプリケーションではそのアダプタを 3D 処理に使用する必要がある。Direct3D の HAL デバイスは、ハードウェアのトランスフォーム、ライティング、およびラスタ化モジュールをすべてまたはその一部を実装する。

アプリケーションは、3D カードに直接アクセスするわけではない。アプリケーションは、Direct3D 関数およびメソッドを呼び出す。Direct3D は、ハードウェア アブストラクション レイヤ (HAL) を介してハードウェアにアクセスする。アプリケーションが動作するコンピュータが HAL に対応している場合は、HAL デバイスを使用することで最高のパフォーマンスを実現できる。

[C++]

C++ で HAL デバイスを作成するには、IDirect3D7::CreateDevice を呼び出し、第 1 パラメータとして IID_IDirect3DHALDevice 値を渡す。詳細については、「Direct3D デバイスの作成」を参照すること。

[Visual Basic]

Visual Basic で HAL デバイスを作成するには、Direct3D7.CreateDevice メソッドを呼び出し、第 1 パラメータとして "IID_IDirect3DHALDevice" 文字列定数を渡す。詳細については、「Direct3D デバイスの作成」を参照すること。

注 : ソフトウェアエミュレーション RGB デバイスとは異なり、ハードウェア デバイスは 8 ビット レンダリング ターゲット サーフェスにレンダリングできない。


TnLHAL デバイス

一部の新しい 3D ハードウェアには、トランスフォーム & ライティング処理にハードウェア アクセラレーションを実行して、CPU の作業負荷を解放するものがある。これが可能な場合、アプリケーションでは、このようなデバイスを使用してパフォーマンスを最適化できる。Direct3D の TnLHAL デバイスは、ハードウェアのトランスフォーム、ライティング、およびラスタ化モジュールをすべて実装する。

アプリケーションは、3D カードに直接アクセスするわけではない。アプリケーションは、Direct3D 関数およびメソッドを呼び出す。Direct3D は、ハードウェア アブストラクション レイヤ (HAL) を介してハードウェアにアクセスする。アプリケーションが動作するコンピュータが HAL に対応している場合は、HAL デバイスを使用することで最高のパフォーマンスを実現できる。

[C++]

トランスフォーム & ライティングのハードウェア アクセラレーションを実行できるハードウェア デバイスは、D3DDEVCAPS_HWTRANSFORMANDLIGHT デバイス機能を公開する。C++ で TnLHAL デバイスを作成するには、IDirect3D7::CreateDevice メソッドを呼び出し、第 1 パラメータとして IID_IDirect3DTnLHalDevice 値を渡す。詳細については、「Direct3D デバイスの作成」を参照すること。

[Visual Basic]

トランスフォーム & ライティングのハードウェア アクセラレーションを実行できるハードウェア デバイスは、D3DDEVCAPS_HWTRANSFORMANDLIGHT デバイス機能を公開する。Visual Basic で TnLHAL デバイスを作成するには、Direct3D7.CreateDevice メソッドを呼び出し、第 1 パラメータとして "IID_IDirect3DTnLHALDevice" 文字列定数を渡す。詳細については、「Direct3D デバイスの作成」を参照すること。


RGB デバイス

ユーザーのコンピュータが 3D 操作用の特別なハードウェア アクセラレーションを備えていない場合、アプリケーションはソフトウェアで 3D ハードウェアをエミュレートできる。RGB デバイスは、ソフトウェアで 3D ハードウェアの色機能をエミュレートする。RGB デバイスはソフトウェア エミュレーションなので、HAL デバイスよりも実行速度が遅い。ただし、RGB デバイスは、ユーザーの CPU でサポートされている特別な命令を利用してパフォーマンスを向上させる。サポートされている命令セットには、いくつかの AMD プロセッサの AMD 3D-Now! 命令セットや、多くの Intel プロセッサでサポートされている MMX 命令セットなどがある。Direct3D では、3D-Now! 命令セットを使用してトランスフォーム & ライティング処理を高速化し、MMX 命令セットを使用してラスタ化を高速化する。

[C++]

C++ で記述されたアプリケーションでは、IDirect3D7::CreateDevice メソッドを使用して RGB デバイスを作成する。第 1 パラメータとして IID_IDirect3DRGBDevice を渡す。詳細については、「Direct3D デバイスの作成」を参照すること。

[Visual Basic]

Visual Basic で記述されたアプリケーションでは、Direct3D7.CreateDevice メソッドを使用して RGB デバイスを作成する。第 1 パラメータとして "IID_IDirect3DRGBDevice" 文字列定数を渡す。詳細については、「Direct3D デバイスの作成」を参照すること。


リファレンス ラスタライザ

Direct3D では、リファレンス ラスタライザと呼ばれる、追加のデバイスの種類をサポートしている。RGB デバイスとは異なり、リファレンス ラスタライザはあらゆる Direct3D 機能をサポートしている。これらの機能は処理速度よりも精度を重視してソフトウェアに実装されているため、結果が得られるまでには時間がかかる。リファレンス ラスタライザは、利用可能な場合は特別な CPU 命令を十分に利用するが、市販アプリケーションは対象としていない。リファレンス ラスタライザは、機能テストやデモンストレーションにのみ使用する。

通常、リファレンス ラスタライザは Direct3D によって列挙されない。列挙されるようにするには、HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Direct3D\Drivers レジストリ キーの EnumReference 名前付き値を、ゼロ以外の DWORD 値に設定する。

[C++]

C++ で記述されたアプリケーションでは、IDirect3D7::CreateDevice メソッドを使用して参照デバイスを作成する。第 1 パラメータとして IID_IDirect3DRefDevice を渡す。詳細については、「Direct3D デバイスの作成」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでは、Direct3D7.CreateDevice メソッドを使用して参照デバイスを作成する。第 1 パラメータとして "IID_IDirect3DefDevice" 文字列定数を渡す。詳細については、「Direct3D デバイスの作成」を参照すること。


従来のデバイスの種類

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、以下のデバイスの種類はサポートしていない。

[C++]

旧リリースの DirectX では、MMX デバイスおよびランプ デバイスという 2 つの追加のデバイスの種類をサポートしていた。これらのデバイスは現在のバージョンの DirectX では使用されないが、従来のインターフェイスを介して使用できる。

MMX デバイス

MMX とは、いくつかのマイクロプロセッサがサポートする特別な命令セットである。MMX デバイスを利用することで、マルチメディアおよび 3D 処理のパフォーマンスが向上する。MMX サポートがインストールされている場合、Direct3D はそれを使用してレンダリングの処理速度を上げる。

MMX デバイスは、HAL デバイスのようなハードウェア アクセラレーション デバイスではない。トランスフォーム、ライティング、およびラスタ化モジュールは、ソフトウェアに完全実装される。しかし、MMX デバイスは、他の種類のソフトウェア エミュレーション Direct3D デバイスよりもパフォーマンス面で優れている。

アプリケーションで IDirect3D2 インターフェイスを使用する場合は、明示的に MMX デバイスを作成しなければならない。しかし、IDirect3D3 インターフェイスからは、MMX デバイスと RGB デバイスはまったく同じ機能セットを実装する (「RGB デバイス」を参照すること)。マイクロプロセッサが MMX テクノロジをサポートしている場合、アプリケーションで RGB デバイスを作成しようとすると、Direct3D は自動的に MMX デバイスを作成する。

アプリケーションでは、IDirect3D3::CreateDevice メソッドを呼び出し、第 1 パラメータとして IID_IDirect3DMMXDevice を渡して MMX デバイスを作成する。詳細については、「Direct3D デバイスの作成」を参照すること。ユーザーのコンピュータで MMX テクノロジがサポートされていない場合、アプリケーションが MMX デバイスの作成を明示的に要求すると、CreateDevice は失敗する。

ランプ デバイス

IDirect3D3 または IDirect3D7 インターフェイスを使用して Direct3D ランプ デバイスを作成することはできない。また、IDirect3DDevice3 または IDirect3DDevice7 インターフェイスについて既存のランプ デバイスを問い合わせることもできない。簡単に言えば、ランプ デバイスは、マルチ テクスチャ ブレンディング オプションをサポートしていない。これらの機能をエミュレートするには、MMX または RGB ソフトウェア エミュレーション デバイスを使用する。

ランプ デバイスは、モノクロ ライティングを使用するソフトウェア エミュレーション デバイスである。ユーザーのコンピュータに、別の種類の Direct3D デバイスをサポートするだけの処理能力がない場合、アプリケーションはランプ デバイスを選択できる。ランプ モードでは、トランスフォーム モジュールは完全に利用できるが、カラー ライティングはサポートされていない。ランプ モード デバイスでは、モノクロ グレースケール ライティング用の Direct3D ライティング モジュールのみ使用する。したがって、ランプ モードのライティングには輝度はあるが色はない。グレースケール値は、ライティング色の青成分に格納される。

ランプ モードでは、色マテリアルとテクスチャを使用できる。Direct3D では、マテリアルまたはテクスチャの色をベース カラーとして使用する。白色光 (輝度が最も高い) をマテリアルやテクスチャに当てる場合は、ベース カラーが使用される。ただし、ライティングの強度が最大ではない場合、マテリアルまたはテクスチャの色にグレーや黒が混ざる。アプリケーションでテクスチャをランプ モードで使用する場合、従来の D3DLIGHTSTATETYPE 列挙型の D3DLIGHTSTATE_MATERIAL メンバを設定する必要がある。ランプ モードでは、8 ビットのテクスチャのみ使用できる。

ランプ モードでマテリアルまたはテクスチャのカラー値を制御するには、アプリケーションの作成時に D3DMATERIAL 構造体の dwRampSize メンバを設定する必要がある。Direct3D はマテリアルおよびテクスチャの色をベース カラーとして使用する。dwRampSize メンバの値によって、ライティングの明度に応じた、ベース カラーのグラデーション数が決まる。Direct3D は、dwRampSize メンバで指定されたエントリ数 (1 ベース) の色パレットを作成する。パレットの最大エントリ数は 256 未満 (Windows が使用する予約済み色数を 256 から引いた数) であるため、アプリケーションに必要なグレースケール値の最小数を指定する必要がある。

最適な結果を得るには、アプリケーションのマテリアルの大部分またはすべてのランプ サイズを同じ値にする。Direct3D がパレットのエントリを使い切ると、既存のマテリアルを検索して最も近い色を検出する。ランプ サイズが同じマテリアルのみ一致するものと見なされる。

ランプ デバイスは、主に既存のアプリケーションとの互換性を保つために用意されている。一般に、RGB デバイスをサポートするだけの処理能力がないコンピュータは、3D アプリケーションには不向きである。

アプリケーションで IDirect3D2::CreateDevice メソッドを呼び出し、第 1 パラメータとして IID_IDirect3DRampDevice を渡してランプ デバイスを作成する。詳細については、「Direct3D デバイスの作成」を参照すること。


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

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では COM インターフェイスは使用しない。また、実行バッファを使用したレンダリングはサポートしていない。

[C++]

C++ で記述されたアプリケーションでは、デバイス インターフェイスを使用して、Direct3DDevice オブジェクトのレンダリング ステートとライティング ステートを操作し、レンダリング処理を実行する。Direct3D にはデバイス用の COM インターフェイスとして、IDirect3DDevice、IDirect3DDevice2、IDirect3DDevice3、および IDirect3DDevice7.の 4 つがある。これらのインターフェイスの基本になるのは、最初の 3 つのインターフェイスをすべてまたは IDirect3DDevice7 インターフェイスのみ公開する 2 つの COM オブジェクトのいずれかである。アプリケーションで使用するデバイス オブジェクト、つまりインターフェイスは、そのデバイスの作成に使用するメソッドに完全に依存する。詳細については、「Direct3D デバイスの作成」を参照すること。従来の IDirect3DDevice、IDirect3DDevice2、および IDirect3DDevice3 インターフェイスは、DirectX 7.0 より以前のバージョンの DirectX で公開されている機能とレンダリング機能を表す。このドキュメントでは、これらのオブジェクトを旧デバイスとして扱っている。IDirect3DDevice7 インターフェイスを公開するオブジェクトは、このドキュメントでは新しいデバイスとして扱い、レンダリング機能の最新セットを表す。アプリケーションでは、IUnknown::QueryInterface メソッドを使用しても、これら新旧のインターフェイス間で移行することはできない。これは、旧デバイス オブジェクトが最新機能に対応していないことと、新しいデバイス オブジェクトは後方互換性よりもパフォーマンス最適化のために設計されていることが理由である。Direct3D では、アプリケーションで使用するインターフェイスを事前に選択する必要がある。

このドキュメントでは、一般に、最新インターフェイスが使用されることを前提としている。ただし、以前の実装についての知識が役立つ場合もある。旧バージョンの DirectX で公開されていた IDirect3DDevice インターフェイスは、実行バッファを使用するプログラミング用のメソッドを提供している。実行バッファは、主に後方互換性を保つために提供されていた。それ以降の DirectX のバージョンでは、よりシンプルな DrawPrimitive モデルが使用されるようになり、シーンをレンダリングするためのコードが非常に簡素化されたため、実行バッファは使用されなくなった。DrawPrimitive によるレンダリングは、IDirect3DDevice インターフェイス以降のすべてのインターフェイスで採用されている。DirectX 7.0 の Direct3D 直接モードでは IDirect3DDevice7 インターフェイスが新しく使用されるようになり、作業がより一層簡素化されると同時に、ハードウェア アクセラレーションを利用できるようになった。IDirect3DDevice7 を公開するデバイス オブジェクトでは、何らかのハードウェアで実行している場合ハードウェア アクセラレーションによるトランスフォーム & ライティング処理を実行できる。詳細については、「DirectX 7.0 での直接モードの変更点」を参照すること。これらのインターフェイスは、いくつかの共通のメソッド、特に DrawPrimitive のレンダリングを実行するインターフェイスを共有している。詳細については、「レンダリング」を参照すること。

DirectX 5.0 で IDirect3DDevice2 インターフェイスが導入される以前は、Direct3D デバイスが DirectDrawSurface オブジェクトへのインターフェイスであった。IDirect3DDevice2 および IDirect3DDevice3 インターフェイスが実装するのは、Direct3DDevice オブジェクトが DirectDraw サーフェスからまったく独立しているデバイス オブジェクト モデル、およびライティング、マテリアル、ビューポートなどはシーンをレンダリングするために 1 つまたは複数のデバイスに関連付け可能なオブジェクトであるという概念である。一方、IDirect3DDevice7 インターフェイスは、ライティング、マテリアル、およびビューポート パラメータを個別のオブジェクトからデバイス自体に移動することにより、Direct3D オブジェクトモデルをさらに簡素化している。

注 : IDirect3DDevice3 と IDirect3DDevice7. 間にはインターフェイスのバージョン番号はない。

Direct3D デバイス オブジェクトは DirectDraw サーフェスから独立して、独自に寿命を持っている。したがって、Direct3D デバイス オブジェクトは、アプリケーションで必要な場合にはいつでも、さまざまな DirectDraw サーフェスをレンダリング ターゲットとして使用できる。詳細については、「IDirect3DDevice7::SetRenderTarget」を参照すること。


デバイス ステート

Direct3D デバイスはステート マシンである。つまり、アプリケーションでライティング、レンダリング、およびトランスフォーム モジュールのステートを設定し、レンダリング時にそれらのモジュールを介してデータを渡す。このセクションでは、レンダリング ステート、および Direct3D 直接モードで使用する各レンダリング ステートについて詳しく説明する。また、デバイス ステートのグループを 1 回の呼び出しで処理できるデバイス ステート ブロックについても説明する。説明するトピックは次のとおりである。

  • レンダリング ステート
  • ステート ブロック
[C++]

C++ アプリケーションでは、IDirect3DDevice7::SetRenderState メソッドを使用してほとんどのデバイス ステートを設定する。

[Visual Basic]

Visual Basic で開発されたアプリケーションでは、Direct3DDevice7.SetRenderState メソッドを使用してほとんどのデバイス ステートを設定する。

注 : デバイス ステートには、ユーザー定義クリップ面、トランスフォーム、およびライティング ステートも含まれる。詳細については、「ユーザー定義クリップ面」、「ジオメトリ パイプライン」、および「ライティングとマテリアル」を参照すること。


レンダリング ステート

このセクションでは、レンダリング ステートの概念について説明し、レンダリング ステートとテクスチャ ステージ ステートを比較する。また、さまざまなレンダリング ステートについて詳しく説明する。説明するトピックは以下のとおりである。

  • レンダリング ステートについて
  • カレント テクスチャ
  • アンチエイリアシング ステート
  • テクスチャ アドレッシング ステート
  • テクスチャ ラッピング ステート
  • テクスチャ境界
  • テクスチャ パースペクティブ ステート
  • テクスチャ フィルタリング ステート
  • アウトラインおよび塗りつぶしステート
  • シェーディング ステート
  • フォグ ステート
  • アルファ ブレンディング ステート
  • アルファテスティング ステート
  • テクスチャ ブレンディング ステート
  • カリング ステート
  • 深度バッファリング ステート
  • ランプ ステート
  • サブピクセル補正ステート
  • 面マスク ステート
  • カラー キーイング ステート
  • レンダリング コマンド バッチ処理ステート
  • ステンシル バッファ ステート
  • プリミティブ クリッピング ステート
  • ライティング ステート
  • 範囲の更新ステート
  • アンビエント ライト ステート
  • 頂点色ステート


ステート ブロック

Direct3D 直接モードのステート ブロックとは、デバイス ステートのグループである。これには、レンダリング ステート、ライティングおよびマテリアル パラメータ、トランスフォーム ステート、テクスチャ ステージ ステート、およびカレント テクスチャ情報がある。ステート ブロックは、デバイスの現在のステートのスナップショットとして処理されるか、または明示的に記録され、1 回の呼び出しでデバイスに適用することができる。デバイス ステート ブロックは、アプリケーションで必要となる共通した一連のステート変更を高速化するために、レンダリング デバイスで最適化することができる。また、デバイス ステート ブロックの使用は、単にデバイス ステートの適用を簡素化にもつながる。

このセクションの以下のトピックでは、デバイス ステート ブロックの主要な概念について、およびアプリケーションでの使用方法について説明する。

  • ステート ブロック ハンドル
  • ステート ブロックの記録
  • ステート ブロックの取得
  • ステート ブロックの適用
  • 事前定義するステート ブロックの作成
  • ステート ブロックの削除


デバイスの使用

このセクションでは、Direct3D 直接モードのアプリケーションで Direct3D デバイスを使用する方法について説明する。説明するトピックは次のとおりである。

  • Direct3D デバイスの列挙
  • Direct3D デバイスの作成
  • トランスフォームの設定
  • レンダリング


Direct3D デバイスの列挙

アプリケーションは、アプリケーションの動作環境のハードウェアに問い合わせを行って、そのハードウェアでサポートされている Direct3D デバイスの種類を検出することができる。このセクションでは、Direct3D デバイスの列挙に関して主要な 2 つのタスクについて説明する。説明するトピックは次のとおりである。

  • デバイス列挙の開始
  • 列挙されたデバイスの選択


Direct3D デバイスの作成

パフォーマンスに関する重要事項 指定の Direct3D オブジェクトによって作成されたレンダリング デバイスは、すべて同じ物理リソースを共有する。単一の Direct3D オブジェクトから複数のレンダリング デバイスを作成することは可能であるが、これらはすべて同じハードウェアを共有するため、パフォーマンスが大きく低下する。

[C++]

C++ アプリケーションで Direct3D デバイスを作成するには、まず DirectDrawCreateEx 関数を呼び出して DirectDraw オブジェクトを作成し、IDirect3D7 インターフェイスを取得しなければならない。詳細については、「Direct3D へのアクセス」を参照すること。次に、IDirect3D7::CreateDevice メソッドを呼び出して Direct3D デバイスを作成する。このメソッドは、IDirect3DDevice7 インターフェイスへのポインタをアプリケーションに渡す。

次の図は、C++ で Direct3D デバイスを作成する処理を示す。

注 : 「Direct3D へのアクセス」で説明するように、DirectDraw コンポーネントは 2 つの COM オブジェクトから構成される。最新のオブジェクトは DirectDraw7 と呼ばれ、DirectDrawCreateEx 関数を呼び出すことで作成される。このオブジェクトは、IDirect3D7 インターフェイスを公開する唯一のオブジェクトである。IDirect3DDevice7 インターフェイスを公開する Direct3D デバイスを生成できるのは、このオブジェクトのみである。このようにして作成された Direct3DDevice オブジェクトは、従来の Direct3D インターフェイスを公開しない。以前の Direct3D デバイス インターフェイスを必要とするアプリケーションでは、DirectDrawCreate メソッドを使用して DirectDraw オブジェクトを作成し、次に目的のオブジェクトを作成する必要がある。

次のコードは、IDirect3Device7 インターフェイスをサポートする Direct3D レンダリング デバイスを作成する処理を示す。

LPDIRECTDRAW7    lpDD;              // IDirectDraw7 インターフェイス
LPDIRECT3D7     lpD3D;              // IDirect3D7 インターフェイス
LPDIRECTDRAWSURFACE7  lpddsRender;  // レンダリング サーフェス
LPDIRECT3DDEVICE7     lpd3dDevice;  // D3D デバイス
HRESULT hr;

// DirectDraw インターフェイスを作成する。
// 現在のディスプレイ ドライバを使用する。
hr = DirectDrawCreateEx (NULL, (void **)&lpDD, IID_IDirectDraw7, NULL);
if (FAILED (hr))
{
// エラー処理コード
}

// IDirect3D7 インターフェイスを取得する。
hr =
    lpDD->QueryInterface (IID_IDirect3D7, (void **)&lpD3D);
if (FAILED (hr))
{
// エラー処理コード
}

//
// 簡単にするために、以下のタスクのコードは省略する。
//
// この時点で、アプリケーションの協調レベルを設定する必要がある。
// フルスクリーンで使用する場合は、
// ディスプレイ モードを設定する必要がある。
// ここで、プライマリ サーフェスを作成する。
// この時点で、レンダリング サーフェスを作成する。このコードでは、
// 作成されたレンダリング サーフェスは、
// 変数 lpddsRender によってポイントされているとする。
// Z バッファを使用する場合は、ここで作成する。
// この時点で、Direct3D デバイスの列挙を実行できる。

hr = lpD3D->CreateDevice (IID_IDirect3DHALDevice,
                               lpddsRender,
                               &lpd3dDevice,
                               NULL);

この例では、IDirect3D7::CreateDevice メソッドを呼び出して Direct3D デバイスを作成している。ここでは、呼び出しが成功すると Direct3D HAL デバイスが作成される。

アプリケーションで作成するターゲット DirectDraw レンダリング サーフェスは、Direct3D レンダリング ターゲットとして使用できるように作成する必要がある。そのためには、DDSURFACEDESC2 構造体を IDirectDraw7::CreateSurface メソッドに渡す必要がある。DDSURFACEDESC2 構造体には ddsCaps というメンバがあり、これは DDSCAPS2 型の構造体である。DDSCAPS2 構造体には dwCaps というメンバがあり、これは、IDirectDraw7::CreateSurface を呼び出すときに DDSCAPS_3DDEVICE に設定しなければならない。

レンダリング ターゲット サーフェスをハードウェア アクセラレーション レンダリング デバイスで使用するときは、そのレンダリング ターゲット サーフェスをディスプレイ メモリで作成する必要がある (DDSCAPS_VIDEOMEMORY フラグを使用)。そうでない場合は、システム メモリでレンダリング ターゲット サーフェスを作成する (DDSCAPS_SYSTEMMEMORY フラグを使用)。

注 : 広く使用されている一部のハードウェア デバイスでは、レンダリング ターゲットおよび深度バッファ サーフェスで同じビット深度を使用する必要がある。そのようなハードウェアでは、アプリケーションで 16 ビットのレンダリング ターゲット サーフェスを使用する場合は、アタッチする深度バッファも 16 ビットでなければならない。32 ビットのレンダリング ターゲット サーフェスであれば、32 ビットの深度バッファでなければならない。8 ビットの深度バッファは、必要に応じてステンシル バッファリングに使用できる。

アプリケーションが動作するハードウェアにこのような要件があり、アプリケーションがこれを満たしていない場合、非対応サーフェスを使用するレンダリング デバイスを作成しようとすると失敗する。IDirectDraw7::GetDeviceIdentifier を使用して、この制限があるハードウェアを特定できる。

[Visual Basic]

Direct3D デバイスを作成するには、まず通常の方法で DirectDraw オブジェクトを初期化して、Direct3D7 クラスへの参照を取得する必要がある。詳細については、「Direct3D へのアクセス」を参照すること。次に、Direct3D7::CreateDevice メソッドを呼び出して Direct3D デバイスを作成しなければならない。このメソッドは、Direct3DDevice7 クラス オブジェクトへの参照を返す。

次の図は、Visual Basic で Direct3D デバイスを作成する処理を示す。

次のコードは、Visual Basic で Direct3D デバイスを作成する処理を示す。

' この例では、g_dx 変数に DirectX7 オブジェクトへの
' 有効な参照が格納されている。
Private Sub Test()
On Local Error Resume Next

Dim ddraw As DirectDraw7        ' DirectDraw7 クラス
Dim d3d As Direct3D7            ' Direct3D3 クラス
Dim ddsRender As DirectDrawSurface7 ' レンダリング サーフェス
Dim d3dDev As Direct3DDevice7   '  Direct3D デバイス

' DirectDraw7 オブジェクトを作成する。
' 現在のディスプレイ ドライバを使用する。
Set ddraw = g_dx.DirectDrawCreate("")
If Err.Number <> DD_OK Then
' エラー処理コード
End If

' Direct3D7 オブジェクトを取得する。
Set d3d = ddraw.GetDirect3D
If Err.Number <> DD_OK Then
' エラー処理コード
End If

    '
' 簡単にするために、以下のタスクのコードは省略してある。
    '
' ここで、アプリケーションの協調レベルを設定する必要がある。
' フルスクリーンで使用する場合は、
' ディスプレイ モードを設定する必要がある。
' ここで、プライマリ サーフェスを作成する。
' ここで、レンダリング サーフェスを作成する。このコードでは、
' 作成されたレンダリング サーフェスは、
' 変数 ddsRender によってポイントされているとする。
' Z バッファを使用する場合は、ここで作成する。
' この時点で、Direct3D デバイスの列挙を実行できる。

Set d3dDev = d3d.CreateDevice("IID_IDirect3DHALDevice", ddsRender)
End Sub

このコードでは、Direct3D7.CreateDevice メソッドを呼び出して Direct3D デバイスを作成している。この例では、呼び出しが成功すると Direct3D HAL デバイスが作成される。

アプリケーションで作成するターゲット DirectDraw レンダリング サーフェスは、Direct3D レンダリング ターゲットとして使用できるように作成する必要がある。そのためには、DDSURFACEDESC2 変数を DirectDraw7::CreateSurface メソッドに渡す必要がある。DDSURFACEDESC2 型には、DDSCAPS2 型の ddsCaps というメンバがある。DDSCAPS2 型には lCaps というメンバがあり、これは、DirectDraw7::CreateSurface を呼び出すときに DDSCAPS_3DDEVICE に設定しなければならない。

レンダリング ターゲット サーフェスをハードウェア アクセラレーション レンダリング デバイスで使用するには、そのレンダリング ターゲット サーフェスをディスプレイ メモリで作成する必要がある (DDSCAPS_VIDEOMEMORY フラグを使用)。そうでない場合は、システム メモリでレンダリング ターゲット サーフェスを作成する (DDSCAPS_SYSTEMMEMORY フラグを使用)。

注 : 広く使用されている一部のハードウェアでは、レンダリング ターゲットおよび深度バッファ サーフェスで同じビット深度を使用する必要がある。そのようなハードウェアでは、アプリケーションで 16 ビットのレンダリング ターゲット サーフェスを使用する場合は、アタッチする深度バッファも 16 ビットでなければならない。32 ビットのレンダリング ターゲット サーフェスであれば、32 ビットの深度バッファでなければならない。8 ビットの深度バッファは、必要に応じてステンシル バッファリングに使用できる。

アプリケーションが動作するハードウェアにこのような要件があり、アプリケーションでこれお満たしていない場合、非対応サーフェスを使用するレンダリング デバイスを作成しようとすると失敗する。


トランスフォームの設定

[C++]

C++ では、IDirect3DDevice7::SetTransform メソッドを呼び出してトランスフォームを適用する。たとえば、ビュー トランスフォームを設定するには、次のようなコードを使用する。

    HRESULT hr
    D3DMATRIX  view;

// ビュー行列にデータを設定する。

    hr = lpDev->SetTransform(D3DTRANSFORMSTATE_VIEW, &view);

if(FAILED(hr)){
// エラー処理コード
    }

IDirect3DDevice7::SetTransform を呼び出す場合、第 1 パラメータに設定できる値はいくつかあるが、一般には D3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_VIEW、および D3DTRANSFORMSTATE_PROJECTION を設定する。これらのトランスフォーム ステートは、D3DTRANSFORMSTATETYPE 列挙型に定義されている。また、この列挙には、テクスチャ座標に適用するトランスフォームを設定する D3DTRANSFORMSTATE_TEXTURE1 ～ D3DTRANSFORMSTATE_TEXTURE7 ステートも定義されている。

[Visual Basic]

Visual Basic では、Direct3DDevice7.SetTransform メソッドを呼び出してトランスフォームを適用する。たとえば、ビュー トランスフォームを設定するには、次のようなコードを使用する。

On Local Error Resume Next
Dim view As D3DMATRIX

' ビュー行列にデータを設定する。
Call d3dDev.SetTransform(D3DTRANSFORMSTATE_VIEW, view)

If Err.Number <> DD_OK Then
' エラー処理コード
End If

Direct3DDevice7.SetTransform を呼び出す場合、第 1 パラメータに設定できる値はいくつかあるが、一般には D3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_VIEW、および D3DTRANSFORMSTATE_PROJECTION を設定する。これらのトランスフォーム ステートは、CONST_D3DTRANSFORMSTATETYPE 列挙に定義されている。また、この列挙には、テクスチャ座標に適用するトランスフォームを設定する D3DTRANSFORMSTATE_TEXTURE1 ～ D3DTRANSFORMSTATE_TEXTURE7 ステートも定義されている。


レンダリング

アプリケーションでは、DrawPrimitive ファミリのメソッドを使用して 3D シーンをレンダリングする。従来の実行バッファを使用したレンダリング モデルよりも、DrawPrimitive アーキテクチャを使用することを推奨する。したがって、以下のトピックでは DrawPrimitive を使用したレンダリングについて説明する。

  • 頂点のグループ化
  • シーンの開始と終了
  • サーフェスのクリア
  • プリミティブのレンダリング
  • プリミティブの種類
  • レンダリング ステート


AGP サーフェスと Direct3D デバイス

3D アプリケーションでテクスチャを使用すると、3 D 画像のリアリティが大幅に増す。テクスチャを格納するメモリは、開発者が思うほど豊富ではない。DirectDraw と Direct3D では、AGP (Accelerated Graphics Port) アーキテクチャがサポートされている。AGP アーキテクチャを採用することにより、アプリケーションのメモリ空間で DirectDraw サーフェスを作成できるようになる。その結果、テクスチャを格納するメモリが大幅に拡大する。

AGP アーキテクチャをサポートするのは、Direct3D HAL デバイスのみである。AGP アーキテクチャの使用の詳細については、「非ローカル ビデオ メモリ サーフェスの使用」を参照すること。


ジオメトリ パイプライン

3D アプリケーションを設計するとき、利便性を考慮してミクロンからパーセクまで、あらゆる単位でワールドを定義する。アプリケーションは、このワールドの記述を Direct3D に渡す。この記述には、ワールド内にあるすべてのオブジェクトのサイズと相対位置座標、およびビューアの位置座標と定位が含まれる。Direct3D は、この記述をスクリーン上の一連のピクセルにトランスフォームする。この処理 (ジオメトリの 2 D 画像へのトランスフォーム) のことを、ジオメトリ パイプラインまたはトランスフォーム パイプラインと呼ぶ。

このセクションでは、主に Direct3D におけるジオメトリ パイプラインについて説明する。以下のトピックでは、重要な概念について、およびこれらの概念に対応する Direct3D API の概念について説明する。

  • パイプラインの概要
  • ワールド トランスフォーム
  • ビュー トランスフォーム
  • 射影トランスフォーム
  • ビューポートとクリッピング
  • ラスタライザ


パイプラインの概要

ジオメトリのジオメトリ パイプラインを実行するのは、Direct3D のトランスフォーム エンジンである。これは、ワールド内のモデルとビューアを検出し、スクリーン上に表示できるように頂点を射影し、頂点をビューポートに切り取る (トランスフォーム エンジンは、また、ライティング計算を実行して各頂点のディフューズおよびスペキュラ成分を決定する。詳細については、「ライティングとマテリアル」を参照すること)。

ジオメトリ パイプラインは、頂点を入力として受け取る。トランスフォーム エンジンは、頂点に 3 つのトランスフォーム (ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォーム) を適用し、結果をクリップし、そのすべてをラスタライザに渡す。この一連の処理は次のようになる。

パイプラインの最初の段階ではトランスフォームは適用されず、モデルの頂点はすべてローカル座標系 (これはローカル原点とローカル座標軸である) に対して宣言される。この座標空間を一般にモデル空間と呼び、個々のローカル座標はモデル座標と呼ぶ。

ジオメトリ パイプラインでは、最初にローカル座標系のモデルの頂点が、シーンのすべてのオブジェクトで使用する座標系にトランスフォームされる。頂点をワールド座標系で再度定義し直すことを、ワールド トランスフォームと呼ぶ。この新しい方向は、通常はワールド空間と呼ばれ、ワールド空間の各頂点は、ワールド座標を使用して宣言される。このトランスフォームについては、「ワールド トランスフォーム」で説明する。

次に、3D ワールドを記述する頂点をカメラに対する相対位置座標で定義し直す。つまり、アプリケーションはシーンの視点 (カメラの位置) を選択し、ワールド空間は視点の位置と向きに合わせて再定義される。すなわち、ワールド空間がカメラ空間にトランスフォームされる。これがビュー トランスフォームである。詳細については、「ビュー トランスフォーム」を参照すること。

次の段階では、射影トランスフォームが行われる。パイプラインにおけるこの段階では、通常、遠くのオブジェクトよりも近くのオブジェクトの方が大きく見えるようにするなど、ビューアからの距離を基準にオブジェクトがスケーリングされて、シーンに奥行きが生まれる。このトランスフォームについては、「射影トランスフォーム」で説明する。分かりやすくするために、このドキュメントでは、射影トランスフォーム後の頂点が存在する空間を、射影空間と呼ぶことにする (グラフィックス関連の書籍では、射影空間のことを、遠近補正後同次空間と呼ぶ場合もある)。すべての射影トランスフォームによってシーンのオブジェクトのサイズがスケーリングされるとは限らない。このような射影は、アフィン射影または正射影と呼ばれることもある。

パイプラインの最後の段階では、スクリーン上で見えない頂点がすべて削除される。これにより、ラスタライザは、見えないオブジェクトに関して色とシェーディングの計算を実行する必要がなくなる。この処理はクリッピングと呼ばれ、これについては「ビューポートとクリッピング」で説明する。クリッピングが完了すると、残りの頂点はビューポート パラメータに従ってスケーリングされ、スクリーン座標系にトランスフォームされる。その結果、これらの頂点は、シーンがラスタ化されたときにスクリーンに表示され、スクリーン空間に存在するようになる。


ワールド トランスフォーム

ここでは、ワールド トランスフォームについての基本的な概念を紹介し、Direct3D アプリケーションでワールド トランスフォーム行列を設定する方法について詳しく説明する。説明するトピックは次のとおりである。

  • ワールド トランスフォームとは
  • ワールド行列の設定


ワールド トランスフォームとは

ワールド トランスフォームでは、頂点がモデルのローカル原点に対して定義されるモデル空間から、頂点がシーン内のすべてのオブジェクトに共通する原点に対して定義されるワールド空間に座標をトランスフォームする。基本的には、ワールド トランスフォームによってモデルがワールドに配置されることから、このような名前が付いている。次の図は、ワールド座標系とモデルのローカル座標系の関係を示す。

ワールド トランスフォームでは、平行移動、回転、およびスケーリングをどのように組み合わせても使用できる。トランスフォームの数学上の説明については、「3D トランスフォーム」を参照すること。


ワールド行列の設定

ほかのすべてのトランスフォームと同様、一連のトランスフォーム行列を、個々の効果をすべて含む単一の行列に連結することでワールド トランスフォームを作成する。簡単な例では、あるモデルがワールド原点にあり、そのローカル座標軸がワールド空間と同じ方向に定義されている場合、ワールド行列は単位行列である。さらに一般的には、ワールド行列はワールド空間への平行移動を組み合わせたものであり、必要に応じてモデルを 1 回または何度も回転することができる。

[C++]

次の例は、C++ で記述された架空の 3D モデル クラスに関するものである。ここでは、D3dutil.cpp および D3dmath.cpp ファイル (DirectX SDK に付属) のヘルパー関数を使用して、モデルを方向付ける回転を 3 回行い、さらにワールド空間での位置座標を基準にそのモデルを再配置する平行移動を行うワールド行列を作成する。

/*
* この例では、
* 以下の変数が有効で、初期化されているとする。
 *
* m_vPos 変数は、このモデルのワールド座標での位置座標を格納する
* D3DVECTOR である。
 *
* m_fPitch、m_fYaw、および m_fRoll 変数は、
* 傾斜角、偏揺れ角、および回転角 (ラジアン) で表すモデルの方向を格納する
* D3DVALUE である。
 */

D3DMATRIX C3DModel::MakeWorldMatrix(void)
{
D3DMATRIX matWorld, // 作成するワールド行列。
matTemp,  // 回転用の一時行列。
matRot;   // 最終的な回転行列 (matWorld に適用する)。

// 行列連結に関する "左から右" ルールを使用して、
// 回転を適用する前に
// 平行移動をオブジェクトのワールド位置座標に適用する。
    D3DUtil_SetTranslateMatrix(matWorld, m_vPos);
    D3DUtil_SetIdentityMatrix(matRot);

    //
// 次に、方向付け変数を
// ワールド行列に適用する。
    //
    if(m_fPitch || m_fYaw || m_fRoll)
    {
// 回転行列を作成して結合する。
D3DUtil_SetRotateXMatrix(matTemp, m_fPitch);    // 傾斜
D3DMath_MatrixMultiply(matRot,matRot,matTemp);
D3DUtil_SetRotateYMatrix(matTemp, m_fYaw);      // 偏揺れ
D3DMath_MatrixMultiply(matRot,matRot,matTemp);
D3DUtil_SetRotateZMatrix(matTemp, m_fRoll);     // 回転
D3DMath_MatrixMultiply(matRot,matRot,matTemp);

// 回転行列を適用してワールド行列を完成する。
D3DMath_MatrixMultiply(matWorld, matRot, matWorld);
    }
    return (matWorld);
}

ワールド トランスフォーム行列が準備できたら、この行列を設定するために IDirect3DDevice7::SetTransform メソッドを呼び出して、第 1 パラメータに D3DTRANSFORMSTATE_WORLD フラグを指定する。詳細については、「トランスフォームの設定」を参照すること。

[Visual Basic]

次の例は、架空の 3D モデル クラスに関するものである。ここでは、DirectX7 クラスの関数を使用して、モデルを方向付ける回転を 3 回行い、さらにワールド空間での位置座標を基準にそのモデルを再配置する平行移動を行うワールド行列を作成する。

'
' この例では、
' 以下の変数が有効で、初期化されているとする。
'
'   g_dx 変数には、DirectX7 オブジェクトへの有効な参照が格納される。
'
' m_vPos 変数は、このモデルのワールド座標における位置座標を格納する
' D3DVECTOR である。
'
' m_fPitch、m_fYaw、および m_fRoll は、
' 傾斜角、偏揺れ角、および回転角 (ラジアン) で表すモデルの方向を格納する
' Single 型の変数である。
'
Public Function MakeWorldMatrix() As D3DMATRIX
Dim matWorld As D3DMATRIX   ' 結果として返すワールド行列。
Dim matTemp As D3DMATRIX    ' 各回転を格納するための一時行列。
Dim matRot As D3DMATRIX     ' 回転を表す一時行列。

' matWorld を修正して平行移動行列を作成する。
Call g_dx.IdentityMatrix(matWorld)
matWorld.rc41 = m_vPos.x
matWorld.rc42 = m_vPos.y
matWorld.rc43 = m_vPos.z

Call g_dx.IdentityMatrix(matRot) ' 回転行列を設定する。

    '
' 行列連結の "左から右" ルールを使用して、
' 回転を適用する前に
' 平行移動をオブジェクトのワールド位置座標に適用する。
    '

' 回転行列を作成して結合する。
If (m_sPitch <> 0) Or (m_sYaw <> 0) Or (m_sRoll <> 0) Then
' 最初にX軸回転、
Call g_dx.RotateXMatrix(matTemp, m_sPitch)
Call g_dx.MatrixMultiply(matRot, matRot, matTemp)

' 次にY軸回転、
Call g_dx.RotateYMatrix(matTemp, m_sYaw)
Call g_dx.MatrixMultiply(matRot, matRot, matTemp)

' 最後にZ軸回転。
Call g_dx.RotateZMatrix(matTemp, m_sRoll)
Call g_dx.MatrixMultiply(matRot, matRot, matTemp)

' matWorld に既に存在する平行移動行列に回転行列を適用して、
' ワールド行列を完成する。
Call g_dx.MatrixMultiply(matWorld, matRot, matWorld)
End If

MakeWorldMatrix = matWorld
End Function

ワールド トランスフォーム行列が準備できたら、この行列を設定するために Direct3DDevice7::SetTransform メソッドを呼び出して、第 1 パラメータに D3DTRANSFORMSTATE_WORLD フラグを指定する。詳細については、「トランスフォームの設定」を参照すること。

パフォーマンスの最適化 Direct3D では、設定されたワールド行列およびビュー行列を使用して、いくつかの内部データ構造を構築する。新しいワールド行列またはビュー行列を設定するたびに、関係する内部構造が再計算される。これらの行列をフレームごとに数千回も設定するなど頻繁に設定すると、多大な計算負荷が発生する。必要な計算を最小限に抑えるには、ワールド行列として設定する "ワールドビュー" 行列にワールド行列およびビュー行列を連結し、次にビュー行列を単位行列に設定する。ワールド行列およびビュー行列の各キャッシュ コピーは保持しておくこと。必要に応じてワールド行列を修正、連結、およびリセットできる (Direct3D のサンプルでは、簡潔であることを優先して、この最適化はほとんど用いていない)。


ビュー トランスフォーム

このセクションでは、ビュー トランスフォームの基本的な概念を紹介し、Direct3D アプリケーションでビュー トランスフォーム行列を設定する方法について詳しく説明する。説明するトピックは次のとおりである。

  • ビュー トランスフォームとは
  • ビュー行列の設定


ビュー トランスフォームとは

ビュー トランスフォームとは、ワールド空間に視点を配置し、頂点をカメラ空間にトランスフォームする処理である。カメラ空間では、カメラ (つまり "視点") は原点にあり、ｚ 軸の正方向を向く (Direct3D では左手座標系を使用するため、z はシーンの正方向を向く)。ビュー行列は、ワールド内のオブジェクトを、カメラの位置座標 (カメラ空間の原点) と方向の周囲に再配置する。

ビュー行列は多くの方法で作成できる。すべての方法において、カメラはワールド空間内でいくつかの論理位置座標と方向を持つ。これらの位置座標と方向は、シーン内のモデルに適用するビュー行列を作成する際の始点となる。ビュー行列は、オブジェクトを平行移動および回転して、カメラを原点としたカメラ空間内に位置座標付ける。ビュー行列を作成する方法としては、平行移動行列と各軸に対する回転行列を組み合わせる方法がある。この方法では、次の一般的な行列式が適用される。

この式では、V は作成するビュー行列、T はオブジェクトをワールド内に再配置する平行移動行列、Rx ～ Rz は x、y、および z 軸に沿ってオブジェクトを回転する回転行列である。この平行移動行列と回転行列は、ワールド空間におけるカメラの論理位置座標と方向に基づいている。したがって、ワールドにおいてカメラの論理位置座標が <10,20,100> の場合、平行移動行列は、x 軸に沿って -10 単位、y 軸に沿って -20 単位、z 軸に沿って -100 単位だけオブジェクトを平行移動することになる。この式における回転行列は、カメラの向きに基づいており、カメラ空間の軸がワールド空間からどれくらい回転するかを表す。たとえば、上の例のカメラが真下を向いている場合、次の図に示すように、カメラ空間の z 軸はワールド空間の z 軸から 90°(π/2 ラジアン) だけずれている。

回転行列は、大きさは同じであるが方向が逆の回転を、シーン内のモデルに適用する。このカメラに対するビュー行列は、x 軸を中心とした -90°の回転を含む。回転行列と平行移動行列を組み合わせすることで、シーン内のオブジェクトの位置座標と方向を調整するビュー行列を作成して、オブジェクトの上側にカメラを置いてモデルを上から見下ろすことができる。

別の方法として、複雑なビュー行列を直接作成する方法もある (D3dutil.cpp ソース ファイルにある D3DUTIL_SetViewMatrix ヘルパー関数では、Visual Basic アプリケーションで使用する DirectX7.ViewMatrix メソッドと同様に、この方法を使用する)。この方法では、カメラのワールド空間における位置座標とシーン内の "注視点" を使用して、カメラ空間の座標軸の向きを記述するベクトルを派生させる。注視点からカメラ位置座標を減算して、カメラの方向ベクトル (ベクトル n) 用のベクトルを生成する。次に、ベクトル n とワールド空間の y 軸の外積をとり、正規化して、"右方向" ベクトル (ベクトル u) を生成する。次に、ベクトル u と n の外積をとり、"上方向" ベクトル (ベクトル v) を決める。右方向 (u)、上方向 (v)、およびビュー方向 (n) のベクトルは、ワールド空間におけるカメラ空間の座標軸の方向を記述する。x、y、z の平行移動係数は、カメラ位置座標と u、v、n ベクトルの間の内積の負数をとって計算する。

これらの値を次の行列に入れて、ビュー行列を生成する。

この行列では、u、v、n はそれぞれ上方向、右方向、ビュー方向のベクトルであり、c はカメラのワールド空間位置座標である。この行列には、ワールド空間をカメラ空間にトランスフォームと回転するために必要な要素がすべて格納される。この行列を作成した後、z 軸を中心とする回転行列を作成して、カメラを回転することができる。

この方法の実装については、「ビュー行列の設定」を参照すること。


ビュー行列の設定

[C++]

この SDK 付属の D3dutil.cpp ソース ファイルの D3DUtil_SetViewMatrix ヘルパー関数は、この関数に渡されるカメラ位置座標と注視点に基づいてビュー行列を作成する。この関数は、Magnitude、CrossProduct、および DotProduct D3D_OVERLOADS ヘルパー関数を使用する。

HRESULT D3DUtil_SetViewMatrix( D3DMATRIX& mat, D3DVECTOR& vFrom,
       D3DVECTOR& vAt, D3DVECTOR& vWorldUp )
{
// 奥行きを示す Z 軸の基底ベクトルを取得する。これは、
// 注視点に対する視点とは異なる。
    D3DVECTOR vView = vAt - vFrom;

    FLOAT fLength = Magnitude( vView );
    if( fLength < 1e-6f )
return E_INVALIDARG;

// z 軸の基底ベクトルを正規化する。
    vView /= fLength;

// 内積を取得して、上方向ベクトルに対する、Z 軸の基底ベクトルの
// 射影を計算する。この射影は y 軸の基底ベクトルである。
    FLOAT fDotProduct = DotProduct( vWorldUp, vView );

    D3DVECTOR vUp = vWorldUp - fDotProduct * vView;

// 不正な上方向ベクトルを入力したために
// ベクトルがゼロに近くなった場合は、ベクトルをデフォルト値にする。
    if( 1e-6f > ( fLength = Magnitude( vUp ) ) )
    {
vUp = D3DVECTOR( 0.0f, 1.0f, 0.0f ) - vView.y * vView;

// ベクトルがなおゼロに近ければ、別の軸を利用する。
if( 1e-6f > ( fLength = Magnitude( vUp ) ) )
{
    vUp = D3DVECTOR( 0.0f, 0.0f, 1.0f ) - vView.z * vView;

    if( 1e-6f > ( fLength = Magnitude( vUp ) ) )
return E_INVALIDARG;
}
    }

// y 軸の基底ベクトルを正規化する。
vUp /= fLength;

// x 軸の基底ベクトルは、y 軸および z 軸の基底ベクトルの
// 外積として簡単に求められる。
D3DVECTOR vRight = CrossProduct( vUp, vView );

// 行列の作成を開始する。先頭の 3 行には、
// ビューを注視点で回転するための基底ベクトルを格納する。
    D3DUtil_SetIdentityMatrix( mat );
    mat._11 = vRight.x;    mat._12 = vUp.x;    mat._13 = vView.x;
    mat._21 = vRight.y;    mat._22 = vUp.y;    mat._23 = vView.y;
    mat._31 = vRight.z;    mat._32 = vUp.z;    mat._33 = vView.z;

// 移動値を実行する (回転はまだ視点にある)。
    mat._41 = - DotProduct( vFrom, vRight );
    mat._42 = - DotProduct( vFrom, vUp );
    mat._43 = - DotProduct( vFrom, vView );

    return S_OK;
}

ワールド トランスフォームの場合と同様、IDirect3DDevice7::SetTransform メソッドを呼び出してビュー トランスフォームを設定し、第 1 パラメータに D3DTRANSFORMSTATE_VIEW フラグを指定する。詳細については、「トランスフォームの設定」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでは、DirectX7.ViewMatrix メソッドを使用して、カメラ位置座標、注視点、"上方向" ベクトル (通常は 0,1,0)、およびラジアン単位で指定する回転値に基づいてビュー行列を作成する。

次の Visual Basic コードは、ViewMatrix メソッドの使用方法を示す。

' この例では、g_dx 変数にグローバル DirectX7 オブジェクトへの
' 有効な参照が格納されているとする。
Dim matView  As D3DMATRIX
Dim vFrom As D3DVECTOR, _
vTo As D3DVECTOR, _
vUp As D3DVECTOR

vFrom.x = 0:vFrom.y = 0:vFrom.z = -15
vTo.x = 0:vTo.y = 0:vTo.z = 0
vUp.x = 0:vUp.y = 1:vUp.z = 0

' 行列を初期化して単位行列にする。
g_dx.IdentityMatrix matView

' 0,0,-15 にあるカメラでビュー行列を作成する。
' これは、ワールド原点を指し、vFrom->vTo ベクトルを中心とした回転を行わない。
Call g_dx.ViewMatrix(matView, vFrom, vTo, vUp, 0)

ワールド トランスフォームの場合と同様、Direct3DDevice7::SetTransform メソッドを呼び出してビュー トランスフォームを設定し、第 1 パラメータに D3DTRANSFORMSTATE_VIEW フラグを指定する。詳細については、「トランスフォームの設定」を参照すること。

パフォーマンスの最適化 Direct3D では、設定されたワールド行列およびビュー行列を使用して、いくつかの内部データ構造を構築する。新しいワールド行列またはビュー行列を設定するたびに、関係する内部構造が再計算される。これらの行列をフレームごとに 2 万回も設定するなど頻繁に設定すると、多大な計算負荷が発生する。必要な計算を最小限に抑えるには、ワールド行列として設定する "ワールドビュー" 行列にワールド行列およびビュー行列を連結し、次にビュー行列を単位行列に設定する。ワールド行列およびビュー行列の各キャッシュ コピーは保持しておくこと。必要に応じてワールド行列を修正、連結、およびリセットできる (Direct3D のサンプルでは、簡潔であることを優先して、この最適化はほとんど用いていない)。


射影トランスフォーム

射影トランスフォームは、カメラの内部を制御することと考えることができる。つまり、射影トランスフォームは、カメラのレンズを選ぶことに似ている。このトランスフォームは、3 種類のトランスフォームの中で最も複雑である。射影トランスフォームについては、以下のトピックに分けて説明する。

  • 視錐台
  • 射影トランスフォームとは
  • 射影行列の設定
  • W バッファに有効な射影行列


視錐台

視錐台とは、ビューポートのカメラに対して相対的に配置されたシーン内の 3D 立体である。この立体の形は、カメラ空間からスクリーンにモデルを射影する方法に影響を与える。最も一般的な射影は、パースペクティブ射影である。この射影では、カメラの近くにあるオブジェクトが、カメラの遠くにあるオブジェクトよりも大きく表示される。パースペクティブ ビューの場合、視錐台とは先端にカメラがあるピラミッドと考えると分かりやすい。このピラミッドは、前方および後方クリップ面の間にある。前方および後方クリップ面の間にあるピラミッド内の立体が視錐台である。オブジェクトは、この立体内にあるときにのみ見ることができる。

視錐台は、暗い部屋の中で正方形の窓から外を見ている状況を想像すると分かりやすい。別な表現をすると、前方クリップ面は窓であり、後方クリップ面は視界を最終的に遮るもの、たとえば、街の高層ビル、遠方の山脈、または完全な無の空間である。切頭ピラミッドの内部 (窓から最終的に遮るものまでの間) にあるものはすべて見ることができ、それ以外のものは見ることができない。

視錐台は、z 座標で指定される前方および後方クリップ面の間の距離と fov (視野) で定義される。

この図では、変数 D は、カメラから、ジオメトリ パイプラインの最後の部分 (ビュー トランスフォーム) で定義された空間の原点までの距離である。この空間の周りに視錐台の限界を設定する。この D 変数を使用して射影行列を作成する方法については、「射影トランスフォームとは」を参照すること。


射影トランスフォームとは

射影行列とは、一般に、スケーリングパースペクティブ射影である。射影トランスフォームでは視錐台を立方体にトランスフォームする。視錐台の近くの端は遠くの端よりも小さいので、このトランスフォームにはカメラの近くのオブジェクトを拡大するというエフェクトがあり、これによってシーンに遠近感が生まれる。

視錐台では、射影トランスフォームに必要なカメラとビュー トランスフォームによって定義される空間の原点の間の距離が、D として定義される。パースペクティブ射影を定義する行列では、次のように、最初にこの D 変数を使用する。

ビュー行列は、カメラをシーンの原点に配置する。射影行列では (0, 0, -D) にカメラを配置する必要があるので、射影行列は次の行列を使用してベクトルを z 方向に -D だけ平行移動する。

これら 2 つの行列を乗算すると、次のような合成行列ができる。

次の図は、パースペクティブ トランスフォームが視錐台を新しい座標空間にトランスフォームする方法を示す。視錐台が立方体になること、およびシーンの右上角にあった原点が中心に移動することに注目する。

パースペクティブ トランスフォームでは、x 方向と y 方向の限界は -1 と 1 である。z 方向の限界は、前方面ついては 0 で、後方面については 1 である。

この行列は、カメラから近くのクリップ面までの距離に基づいてオブジェクトを平行移動およびスケーリングする。しかし、この行列は視野 (fov) を考慮せず、遠くのオブジェクトに対して生成する z 値はほとんど同じなので、深度比較が困難になる。この問題を解決するために、次の行列は、ビューポートのアスペクト比を考慮して頂点を調整し、アスペクト比をパースペクティブ射影に合わせる。

この行列では、Zn は近くのクリップ面の z 値である。変数 w、h、Q の意味は、次のとおりである (fovw と fovh は水平方向と垂直方向の視野をラジアンで表している)。

アプリケーションでは、視野角度を使用して x と y の倍率を定義するのは、ビューポートの水平寸法と垂直寸法 (カメラ空間の) を使用するのに比べて不便な場合がある。数学の練習問題として、次に示す w と h 用の 2 つの式ではビューポートの寸法を使用している。これらの式は上の公式と等価である。

これらの式では、Zn は近くのクリップ面の位置座標を表し、Vw と Vh 変数はカメラ空間でのビューポートの幅と高さを表している。

[C++]

C++ アプリケーションでは、幅と高さの寸法は、D3DVIEWPORT7 構造体の dwWidth および dwHeight メンバに直接対応する。

どの式を使用する場合でも、Zn をできるだけ大きな値に設定することが重要である。理由は、カメラに極端に近い z 値は大幅には変化しないため、16 ビットの z バッファを使用する深度比較が困難になるからである。

ワールド トランスフォームおよびビュー トランスフォームと同様、IDirect3DDevice7::SetTransform メソッドを呼び出して射影トランスフォームを設定する。詳細については、「トランスフォームの設定」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでは、幅と高さの寸法は、D3DVIEWPORT7 型の lWidth および lHeight メンバに直接対応する。

どの式を使用する場合でも、Zn をできるだけ大きな値に設定することが重要である。理由は、カメラに極端に近い z 値は大幅には変化しないため、16 ビットの z バッファを使用する深度比較が困難になるからである。

ワールド トランスフォームおよびビュー トランスフォームと同様、Direct3DDevice7.SetTransform メソッドを使用して射影トランスフォームを設定する。詳細については、「トランスフォームの設定」を参照すること。


射影行列の設定

[C++]

C++ で記述された、次の ProjectionMatrix サンプル関数は、水平および垂直視点の角度のほかに、前方および後方クリップ面を設定する 4 つの入力パラメータを受け取る (このコードは、「射影トランスフォームとは」で示すコードと類似している)。視野はπラジアン未満にする必要がある。

D3DMATRIX
ProjectionMatrix(const float near_plane,
// 前方クリップ面までの距離。
const float far_plane,
// 後方クリップ面までの距離。
const float fov_horiz,
// 水平視野の角度 (ラジアン)
const float fov_vert)
// 垂直視野の角度 (ラジアン)
{
float    h, w, Q;

w = (float)1/tan(fov_horiz*0.5);  // 1/tan(x) == cot(x)
h = (float)1/tan(fov_vert*0.5);   // 1/tan(x) == cot(x)
    Q = far_plane/(far_plane - near_plane);

D3DMATRIX ret;
    ZeroMemory(&ret, sizeof(ret));

    ret(0, 0) = w;
    ret(1, 1) = h;
    ret(2, 2) = Q;
    ret(3, 2) = -Q*near_plane;
    ret(2, 3) = 1;
    return ret;
}   // ProjectionMatrix() の終わり

行列を作成した場合、IDirect3DDevice7::SetTransform メソッドを呼び出してその行列を設定し、第 1 パラメータに D3DTRANSFORMSTATE_PROJECTION を指定する必要がある。詳細については、「トランスフォームの設定」を参照すること。

[Visual Basic]

Visual Basic で記述されたアプリケーションでは、「射影トランスフォームとは」で説明するように、自分で射影行列を作成できる。ただし、DirectX7 オブジェクトにはこの方法の実装が含まれており、DirectX7.ProjectionMatrix メソッドによって提供される。

次の Visual Basic コードでは、この DirectX7.ProjectionMatrix の一般的な使用方法を示す。

'
' この例では、g_dx 変数に グローバル DirectX7 オブジェクトへの
' 参照が格納されている。
'
' pi 変数は、
'πの近似値 (3.141592) が格納される Single 型の変数である。
Dim matProj As D3DMATRIX

' 行列を初期化して単位行列にする。
g_dx.IdentityMatrix matProj

' 1 と 1000 にある前方および後方クリップ面、およびπ/2 ラジアン (90°) の視点角度の
' 視錐台を表す
' 射影行列を作成する。
Call g_dx.ProjectionMatrix(matProj, 1, 1000, pi / 2)

行列を作成した場合、Direct3DDevice7::SetTransform メソッドを呼び出してその行列を設定し、第 1 パラメータに D3DTRANSFORMSTATE_PROJECTION を指定する必要がある。詳細については、「トランスフォームの設定」を参照すること。


W バッファに有効な射影行列

Direct3D 直接モードでは、ワールド行列、ビュー行列、および射影行列によってトランスフォームされた頂点の W 要素を利用して、深度バッファまたはフォグ エフェクトの計算を深度をベースに実行できる。このような計算では、射影行列により W をワールド空間 Z で対応する W に正規化する必要がある。つまり、射影行列に 1 ではない (3,4) 係数が含まれる場合、(3,4) 係数の逆数を使用してすべての係数をスケーリングすることで、適切な行列を作成しなければならない。対応していない行列を使用すると、フォグ エフェクトと深度バッファが正しく適用されない (射影トランスフォームとはで推奨する射影行列は、w ベースの計算に対応している)。

次の図は、対応していない射影行列、および同じ行列をスケーリングして視点からの相対視点からの相対位置座標によるフォグが有効になるようにした行列を示す。

上の図では、すべての変数がゼロ以外の値であるとする。視点からの相対視点からの相対位置座標によるフォグの詳細については、「視点からの相対深度 対 Z ベースの深度」を参照すること。w ベースの深度バッファリングについては、「深度バッファとは」を参照すること。

注 : Direct3D では、現在設定されている射影行列が w ベースの深度計算に使用される。その結果、アプリケーションでは Direct3D トランスフォーム パイプラインを使用しない場合でも、希望の w ベース機能を受け取る、対応した射影行列を設定する必要がある。


ビューポートとクリッピング

このセクションでは、ジオメトリ パイプラインの最後の段階のクリッピングについて説明する。これについては、以下のトピックに分けて説明する。

  • ビューポートとは
  • ビューポート矩形
  • クリッピング ボリューム
  • ビューポートのスケーリング
  • ビューポートの使用

Direct3D では、ビューポート パラメータのセットを使用することで、デバイスにクリッピングを実装する。

[C++]

IDirect3DDevice7 インターフェイスは、C++ アプリケーションでデバイスに対するビューポート パラメータの操作を可能にするメソッドを公開する (旧リリースの DirectX では、ビューポートは、COM オブジェクト自体のインターフェイスを公開する個別の COM オブジェクトとして実装されていた)。

[Visual Basic]

Direct3DDevice7 クラスには、Visual Basic アプリケーションでデバイスに対するビューポート パラメータの操作を可能にするメソッドがある。


ビューポートとは

概念上、ビューポートとは 3D シーンが射影される 2D 矩形である (Direct3D の場合、この矩形は、レンダリング ターゲットとして使用される DirectDraw サーフェス内の座標として存在する)。射影トランスフォームは、ビューポートに使用される座標系に頂点をトランスフォームする。

Direct3D でビューポートを使用して、アプリケーションで次の機能を指定する。

  • レンダリングが限定されるスクリーン空間ビューポート
  • シーンがレンダリングされるレンダリング ターゲット サーフェスの深度値の範囲 (通常は 0.0 ～ 1.0)


ビューポート矩形

[C++]

注 : DirectX 7.0 で使用するビューポート構造体は、旧リリースで推奨された D3DVIEWPORT2 構造体とはまったく異なる。次の説明にしっかり目を通したうえで、ビューポート パラメータを適切に使用すること。

C++ のビューポート矩形は、D3DVIEWPORT7 構造体を使用して定義する。D3DVIEWPORT7 構造体は、IDirect3DDevice7 インターフェイスが提供するビューポート操作メソッドのIDirect3DDevice7::SetViewport および IDirect3DDevice7::GetViewport で使用する。D3DVIEWPORT7 構造体には dwX、dwY、dwWidth、および dwHeight の 4 つのメンバがある。これらを使用して、シーンがレンダリングされるレンダリング ターゲット サーフェス領域 "ビューポート矩形" を定義する。

これらの値は、次の図に示すように、転送先の矩形、つまりビューポート矩形に対応する。

D3DVIEWPORT7 構造体の dwX、dwY、dwWidth、および dwHeight メンバに指定する値は、レンダリング ターゲット サーフェスの左上角からのスクリーン座標である。この構造体は、シーンがレンダリングされる深度範囲を示す 2 つの追加メンバ dvMinZ および dvMaxZ を定義する。

DirectX 7.0 で使用するビューポート構造体は、旧リリースで推奨された D3DVIEWPORT2 構造体とはまったく異なる。つまり、D3DVIEWPORT7 構造体は従来の構造体を簡素化したもので、3D 射影空間におけるビューポートのサイズおよび寸法を記述するメンバがなくなっている。大部分のアプリケーションでは、現在存在していないメンバは常に同じ値に設定するが、ビューポートのアスペクト比の調整するためにそれらのメンバを使用するアプリケーションもわずかにある。このエフェクトを正確かつ確実に実行するのは困難である。

Direct3D では、ビューポートのクリッピング ボリュームの範囲は、X 方向については -1.0 ～ 1.0、Y 方向については 1.0 ～ -1.0 と想定している (この値は、過去のアプリケーションで最もよく使用された設定値である)。旧リリースの DirectX と同様、DirectX 7.0 の場合も、射影トランスフォームの際、クリッピングを行う前にビューポートのアスペクト比を調整することができる。このタスクについては、「射影トランスフォーム」で説明する。

注 : D3DVIEWPORT7 構造体の dvMinZ および dvMaxZ メンバの解釈方法は、旧リリースの DirectX の場合とはまったく異なる。dvMinZ および dvMaxZ メンバは、現在はシーンがレンダリングされる深度範囲を示し、クリッピングには使用されない。ほとんどのアプリケーションでは、このメンバを 0.0 と 1.0 に設定して、深度バッファ内の深度値の全範囲にレンダリングしている。場合によっては、別の深度範囲を使用して特殊効果を得ることもできる。たとえば、ゲームのヘッドアップ ディスプレイをレンダリングする場合、両方の値を 0.0 に設定してフォアグラウンドのシーン内のオブジェクトを強制的にレンダリングしたり、両方の値を 1.0 に設定して常にバックグラウンドに存在する必要があるオブジェクトをレンダリングすることができる。

[Visual Basic]

Visual Basic アプリケーションでは、D3DVIEWPORT7 型を使用してビューポート矩形を定義する。D3DVIEWPORT7 型は、Direct3DDevice7 クラスが提供するビューポート操作メソッドの Direct3DDevice7.SetViewport および Direct3DDevice7.GetViewport で使用する。D3DVIEWPORT7 型には lX、lY、lWidth、および lHeight の 4 つのメンバがある。これらを使用して、シーンがレンダリングされるレンダリング ターゲット サーフェス領域 "ビューポート矩形" を定義する。

これらの値は、次の図に示すように、転送先の矩形、つまりビューポート矩形に対応する。

D3DVIEWPORT7 型の lX、lY、lWidth、および lHeight メンバに指定する値は、レンダリング ターゲット サーフェスの左上角からのスクリーン座標である。この型は、シーンがレンダリングされる深度範囲を示す 2 つの追加メンバ minz および maxz を定義する。

Direct3D では、ビューポートのクリッピング ボリュームの範囲は、X 方向については -1.0 ～ 1.0、Y 方向については 1.0 ～ -1.0 と想定している (この値は、過去のアプリケーションで最もよく使用された設定値である)。旧リリースの DirectX と同様、DirectX 7.0 の場合も、射影トランスフォームの際、クリッピングを行う前にビューポートのアスペクト比を調整することができる。このタスクについては、「射影トランスフォーム」で説明する。


クリッピング ボリューム

射影行列の結果によって、射影空間でのクリッピング ボリュームが決まる。Direct3D は、次のようにして、射影空間のクリッピング ボリュームを定義する。

この式では、Xc、Yc、Zc、および Wc は、射影トランスフォームの適用後の頂点座標を表す。クリッピングが有効な場合 (デフォルト設定)、これらの範囲外に x、y、または z 成分を持つ頂点がクリッピングされる。

[C++]

頂点バッファを除き、アプリケーションでは、D3DRENDERSTATE_CLIPPING レンダリング ステートを使用してクリッピングの有効または無効にする。頂点バッファのクリッピング情報は処理中に生成される。詳細については、「頂点の処理」を参照すること。

[Visual Basic]

頂点バッファを除き、アプリケーションでは、D3DRENDERSTATE_CLIPPING レンダリング ステートを使用してクリッピングの有効または無効にする。頂点バッファのクリッピング情報は処理中に生成される。詳細については、「頂点の処理」を参照すること。


ビューポートのスケーリング

[C++]

ビューポート用の D3DVIEWPORT7 構造体の dwX、dwY、dwWidth、および dwHeight メンバに寸法を指定して、レンダリング ターゲット サーフェスのビューポートの位置座標および大きさを定義する。これらの値は、レンダリング ターゲット サーフェスの左上角からのスクリーン座標である。

Direct3D では、ビューポートの位置座標と寸法を使用して頂点をスケーリングし、レンダリングするシーンをターゲット サーフェス上の適切な位置座標に配置する。内部的には、Direct3D は、各頂点に適用される行列にこれらの値を挿入している。

この行列は、ビューポートの寸法および指定の深度範囲に従って頂点をスケーリングし、その頂点をレンダリング ターゲット サーフェスの適切な位置座標にトランスフォームする (また、この行列は、y が下方に増加する左上角のスクリーン原点を反映するために y 座標を "反転" する)。この行列を適用した後も、頂点は同次である。つまり、頂点は依然として [x,y,z,w] 頂点として存在するので、ラスタライザに送る前に頂点を非同次にトランスフォームしなければならない。これは、「ラスタライザ」で説明するように、単純な除算によって行う。

注 : DirectX 7.0 のビューポート スケーリング行列は、頂点をスケーリングする D3DVIEWPORT7 構造体の dvMinZ および dvMaxZ メンバを組み込んで深度範囲 [dvMinZ, dvMaxZ] を合わせる。これは、これらのメンバがクリッピングに使用されていた旧リリースの DirectX のセマンティクスとは異なる。詳細については、「ビューポート矩形」および「クリッピング ボリューム」を参照すること。アプリケーションでは、通常、dvMinZ および dvMaxZ をそれぞれ 0.0 および 1.0 に設定して深度範囲全体へのレンダリングを実行する。ただし、別の値を設定して何らかのエフェクトを得ることもできる。両方の値を 0.0 に設定してすべてのオブジェクトを強制的にフォアグラウンドにレンダリングしたり、両方の値を 1.0 に設定してすべてのオブジェクトをバックグラウンドにレンダリングすることができる。

[Visual Basic]

ビューポート用の D3DVIEWPORT7 型の IX、IY、IWidth、および IHeight メンバに寸法を指定して、レンダリング ターゲット サーフェスのビューポートの位置座標および大きさを定義する。これらの値は、レンダリング ターゲット サーフェスの左上角からのスクリーン座標である。

Direct3D では、ビューポートの位置座標と寸法を使用して頂点をスケーリングし、レンダリングするシーンをターゲット サーフェス上の適切な位置座標に配置する。内部的には、Direct3D は、各頂点に適用される行列にこれらの値を挿入している。

この行列は、ビューポートの寸法および指定の深度範囲に従って頂点をスケーリングし、その頂点をレンダリング ターゲット サーフェスの適切な位置座標にトランスフォームする (また、この行列は、y が下方に増加する左上角のスクリーン原点を反映するために y 座標を "反転" する)。この行列を適用した後も、頂点は同次である。つまり、頂点は依然として [x,y,z,w] 頂点として存在するので、ラスタライザに送る前に頂点を非同次にトランスフォームしなければならない。これは、「ラスタライザ」で説明するように、単純な除算によって行う。


ビューポートの使用

このセクションでは、ビューポートの操作について詳しく説明する。説明するトピックは次のとおりである。

  • ビューポート クリッピング ボリュームの設定
  • ビューポートのクリア
  • 頂点のマニュアル トランスフォーム


ラスタライザ

Direct3D ジオメトリ パイプラインでの処理が終了すると、頂点はレンダリング ターゲット サーフェスのビューポートに適合するようにトランスフォーム、クリッピング、およびスケーリングされ、スクリーン上に描画するためにラスタライザに送る準備がほぼ完了したことになる。しかし、この時点ではまだ頂点は同次であり、ラスタライザは頂点を x、y、z の位置座標と同次 W の逆数 (RHW) という形で受け取ろうとする。次の式で示すように、Direct3D は x、y、z 座標を w 座標で除算することにより、この同次頂点を非同次頂点にトランスフォームし、w 座標を反転することで RHW を算出する。

算出した値は、表示のためにラスタライザに渡される。ラスタライザは x 座標と y 座標を頂点のスクリーン座標として使用し、z バッファリングが可能な場合は z 座標を深度バッファの深度比較に使用する。RHW 値は、フォグ計算、パースペクティブ補正テクスチャ マッピング、および w バッファリング (深度バッファリングの別の方法) に使用される。


ライティングとマテリアル

このセクションでは、Direct3D 直接モードでのアンビエント ライト レベルの使用、および 3D シーン内のオブジェクトへのライティングとマテリアルの適用について説明する。説明するトピックは次のとおりである。

  • ライティングとマテリアルの概要

    Direct3D 直接モード シーンにおける光源とマテリアルの役割について平易な言葉で説明する。

  • Direct3D のライティング モデルと自然光の比較

    Direct3D のライティング モデルについて詳しく説明し、このライティング モデルと自然光を比較する。

  • ライティングとマテリアルのカラー値

    Direct3D 直接モードにおいてライティングとマテリアルで使用する RGBA カラー値について説明する。

  • ダイレクト ライトとアンビエント ライトの比較

    実際の光源とアンビエント ライトの役割を比較する。

  • ライティング エンジンの有効/無効

    Direct3D のライティング エンジンの有効/無効を切り替える方法について説明する。

  • ライト

    Direct3D のライティングについて、およびこのライティングをシーン内で使用する方法について説明する。

  • マテリアル

    Direct3D 直接モードのマテリアルについて、およびこのマテリアルをシーン内で使用する方法について説明する。

  • Direct3D のライティングにおける数学的計算

    Direct3D のライティング モデルで基本となる数学的計算について詳しく説明する。


ライティングとマテリアルの概要

ライティングが有効になっているとき、Direct3D はレンダリングの最終段階としてシーンをラスタライズする際、シーンの光源によって生成されるライティングの色と強度や、シーンのアンビエント ライト レベルのほかにも、現在のマテリアル カラー (および関連付けられたテクスチャ マップのテクセル)、頂点のディフューズ色とスペキュラ色 (指定されている場合) の組み合わせに基づいて、レンダリングする各ピクセルの色を決める。Direct3D のライティングとマテリアルを使用するときは、Direct3D 側で自動的にライティングの詳細を制御するようにできる。ただし、経験を積んだユーザーであれば、必要に応じて自分でライティングを実行できる。

ライティングとマテリアルの処理方法によって、レンダリングしたシーンの表示は大きく異なる。マテリアルは、サーフェスからの反射光の状態を定義する。ダイレクト ライトとアンビエント ライト レベルは、反射光を定義する。Direct3D 側でライティングを制御する場合は、マテリアルを使用してシーンをレンダリングしなければならない。ライティングはシーンのレンダリングにおいては実際には必ずしも必要ではないが、ライティングなしでレンダリングしたシーンは非常に見にくい。ライティングのないシーンをレンダリングした場合は、せいぜいシーンのオブジェクトのシルエットが表示されるだけで、細部は十分に表示されない。


Direct3D のライティング モデルと自然光の比較

自然界では、光源から放射された光は、(何千や何百万ではないにしても) 何百もの物体に反射した末に私たちの目に届く。光は反射するたびに、その一部が物体のサーフェスに吸収されたり、周囲に拡散し、その残りがほかの物体のサーフェスや私たちに向かう。この過程は、光が減衰して消えてなくなるか、または私たちが光が届いたことを知覚するまで繰り返される。しかし、光が何回反射するかなど分かる人がいるだろうか。1 回だけしか反射しない場合もあるだろう。また、百回あるいは何百万回も反射することもあるだろう。

自然光の動きを完全にシミュレートする計算には、あまりにも膨大な時間がかかるため、リアルタイム 3D グラフィックスで使用できないことは明白である。そこで、速度を考慮して、Direct3D のライティング モデルでは自然光の動きを大まかにシミュレートする。Direct3D では、最終的な色を作成する色成分、赤、緑、および青によって光を描く。詳細については、「ライティングとマテリアルのカラー値」を参照すること。Direct3D では、光がサーフェスに反射したとき、光の色とサーフェス自体を数学的に処理することで、最終的にスクリーンに描画される色を作成する。Direct3D で使用するアルゴリズムに関する特定の情報については、「Direct3D のライティングにおける数学的計算」を参照すること。

Direct3D 直接モードのライティング モデルは、大きく分けてアンビエント ライトとダイレクト ライトの 2 つがある。これらは互いに異なる属性を持ち、サーフェスのマテリアルとの相互作用も異なる。アンビエント ライトは、方向も光源も持たず、環境内を散乱している光で、環境光とも言われる。アンビエント ライトの強度は、どの位置座標においても下位レベルに保たれる。アンビエント ライトの適切な例としては、カメラマンが使用する間接照明がある。Direct3D のアンビエント ライトには、自然光と同様、実際の方向や光源はない。あるのは色と強度のみである。実際、アンビエント ライトのレベルは、シーン内の光を発するオブジェクトとはまったく関係しない。アンビエント ライトはスペキュラ反射を起こさない。

ダイレクト ライトは、シーン内の光源が生成する光である。ダイレクト ライトには常に色と強度があり、特定の方向に進む。ダイレクト ライトは、サーフェスのマテリアルと相互作用してスペキュラ ハイライトを生み、その方向はグーロー シェーディングなどのシェーディング アルゴリズムで係数として使用される。ダイレクト ライトの反射は、シーンのアンビエント ライトのレベルに影響を与えない。シーン内のダイレクト ライトを生成する光源にはさまざまな特性があり、それによってシーンをどのように照らすかが異なる。詳細については、「ライト」を参照すること。

さらに、ポリゴンのマテリアルには、ポリゴンが光をどのように反射するかを決める特性がある。マテリアルがどのようにアンビエント ライトを反射するかを示す単一の反射特性を設定し、マテリアルのスペキュラ反射率およびディフューズ反射率を決める個々の特性を設定する。詳細については、「マテリアル」を参照すること。


ライティングとマテリアルのカラー値

Direct3D 直接モードには、色を記述する 4 つの成分 (赤、緑、青、およびアルファ) があり、これらを組み合わせて最終的な色が生成される。C++ の D3DCOLORVALUE 構造体は、これらの各成分を格納する (Visual Basic アプリケーションでは D3DCOLORVALUE 型を使用する)。各メンバは、通常 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲の浮動小数点値である。ライティングとマテリアルでは、共に同じ構造体を使用して色を記述するが、構造体の内部で使用する値は互いに少しずつ異なる。

光源のカラー値は、光源が発する特定の光の成分の量を表す。ライティングではアルファ成分は使用しないため、赤、緑、および青成分のみ考慮すればよい。これらの 3 つの成分は、プロジェクション モニターの赤色、緑色、および青色のレンズに例えることができる。各レンズをオフにしたり (対応するメンバに 0.0 を設定)、できるだけ明るくしたり (1.0 を設定)、その間のレベルを設定する場合がある。各レンズからの色を組み合わせて、最終的なライティングの色を作成する。R:1,0、G:1.0、B:1.0 の組み合わせの場合、白色光になり、R:0.0、G:0,0、B:0.0 の場合は光をまったく放射しないライティングになる。色成分を 1 つだけ放射するライティングを作成して、純粋な赤色、緑色、または青色のライティングを作ることができる。また、色成分の組み合わせによっては、黄色や紫色などの色を放射するライティングを作成することもできる。色成分値を負にして、シーンから明かりをなくすような "暗色光" を作成できる。また、成分に 1.0 より大きな値を設定して、極端に明るいライティングを作成することもできる。

一方、マテリアルの場合、カラー値はそのマテリアルを使用するサーフェスがどのくらい所定の光の成分を反射するかを表す。マテリアルの色成分が R:1,0、G:1.0、B:1,0、A:1.0 の場合、マテリアルはすべての光を反射する。同様に、R:0.0、G:1.0、B:0.0、A:1.0 の場合は、緑色の光をすべて反射する。マテリアルに複数の反射率を指定して、さまざまなエフェクトを作成できる。詳細については、「マテリアル プロパティ」を参照すること。

アンビエント ライトのカラー値は、ダイレクト ライト光源とマテリアルに使用するカラー値とは異なる。詳細については、「ダイレクト ライトとアンビエント ライトの比較」を参照すること。


ダイレクト ライトとアンビエント ライトの比較

ダイレクト ライトとアンビエント ライトは、ともにシーン内のオブジェクトを照らすが、両者は互いに影響し合うことはなく、それぞれが持つエフェクトは大きく異なるもので、これらの操作方法についてもまったく異っている。

[C++]

ダイレクト ライトは、文字どおり、ダイレクトである。ダイレクト ライトは常に方向と色を持ち、これはグーロー シェーディングなどのシェーディング アルゴリズムの係数として使用される。ライティングの種類が異なれば、ダイレクト ライトの放射も異なり、それぞれ特別な減衰エフェクトを生み出す。ダイレクト ライトのライティング パラメータ セットは、IDirect3DDevice7::SetLight メソッドを呼び出して作成する。詳細については、「ライト」を参照すること。

アンビエント ライトは、シーン内のどの位置座標にもエフェクトを及ぼす。アンビエント ライトは、オブジェクトやオブジェクトのシーン内の位置座標にかかわらず、シーン全体を同じ強度の光で照らすライティングと考えることができる。アンビエント ライトはあらゆる位置に存在し、色と強度を持つのみで、位置座標や方向は持たない。アンビエント ライト レベルを設定するには、IDirect3DDevice7::SetRenderState を呼び出し、dwRenderStateType パラメータとして D3DRENDERSTATE_AMBIENT を指定し、dwRenderState パラメータとして希望の RGBA 色を指定する。

アンビエント ライトの色は、RGBA 値の形をとり、各成分は 0 ～ 255 の整数値である (これは、Direct3D 直接モードのほとんどのカラー値とは異なる。詳細については、「ライティングとマテリアルのカラー値」を参照すること)。RGBA_MAKE マクロを使用して、整数から RGBA 値を生成できる。赤、緑、および青成分を組み合わせて、アンビエント ライトの最終的な色を作成する。アルファ成分は色の透明度を制御する。ランプ エミュレーションでは、アンビエント ライトは色を持たないため、アルファ成分は輝度に使用される。ハードウェア アクセラレーションまたは RGB エミュレーションを使用するときは、アルファ成分は無視される。

[Visual Basic]

ダイレクト ライトは、文字どおり、ダイレクトである。ダイレクト ライトは常に方向と色を持ち、これはグーロー シェーディングなどのシェーディング アルゴリズムの係数として使用される。ライティングの種類が異なれば、ダイレクト ライトの放射も異なり、それぞれ特別な減衰エフェクトを生み出す。ダイレクト ライトのライティング パラメータ セットは、Direct3DDevice7.SetLight メソッドを呼び出して設定する。詳細については、「ライト」を参照すること。

アンビエント ライトは、シーン内のどの位置座標にもエフェクトを及ぼす。アンビエント ライトは、オブジェクトやオブジェクトのシーン内の位置座標にかかわらず、シーン全体を同じ強度の光で照らすライティングと考えることができる。アンビエント ライトはあらゆる位置座標に存在し、色と強度を持つのみで、位置座標や方向は持たない。アンビエント ライト レベルを設定するには、Direct3DDevice7.SetRenderState メソッドを呼び出し、state パラメータとして D3DRENDERSTATE_AMBIENT を指定し、renderstate パラメータとして希望の RGBA 色を指定する。

DirectX7.CreateColorRGBA メソッドを使用して、Single 型の値から RGBA 値を生成できる。赤、緑、および青成分を組み合わせて、アンビエント ライトの最終的な色を作成する。アルファ成分は色の透明度を制御する。ランプ エミュレーションでは、アンビエント ライトは色を持たないため、アルファ成分は輝度に使用される。ハードウェア アクセラレーションまたは RGB エミュレーションを使用するときは、アルファ成分は無視される。


ライティング エンジンの有効/無効

[C++]

デフォルトでは、Direct3D は、すべての頂点に対してライティング計算を実行する。この計算は、頂点法線を持たない頂点に対しても実行される (旧リリースの DirectX では、頂点法線を持つ頂点に対してのみライティングが実行された)。ただし、D3DRENDERSTATE_LIGHTING レンダリング ステートを使用してライティングを無効にできる。IDirect3DDevice7::SetRenderState メソッドを呼び出して、第 1 パラメータとして D3DRENDERSTATE_LIGHTING を渡し、第 2 パラメータとして TRUE または FALSE を渡す。ステートを TRUE に設定するとライティングが有効になり (デフォルト)、FALSE を設定すると無効になる。

アプリケーションで頂点バッファを使用する場合は、処理は少しだけ異なるが、次のように簡単である。IDirect3DVertexBuffer7::ProcessVertices または IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドを呼び出すときに D3DVOP_LIGHT フラグを指定するかどうかで、頂点バッファに対してライティングを有効または無効にする。

[Visual Basic]

デフォルトでは、Direct3D は、すべての頂点に対してライティング計算を実行する。この計算は、頂点法線を持たない頂点に対しても実行される。ただし、D3DRENDERSTATE_LIGHTING レンダリング ステートを使用してライティングを無効にできる。Direct3DDevice7.SetRenderState メソッドを呼び出して、第 1 パラメータとして D3DRENDERSTATE_LIGHTING を渡し、第 2 パラメータとして True または False を渡す。ステートを TRUE に設定するとライティングが有効になり (デフォルト)、FALSE を設定すると無効になる。

アプリケーションで頂点バッファを使用する場合は、処理は少しだけ異なるが、次のように簡単である。Direct3DVertexBuffer7.ProcessVertices メソッドを呼び出すときに D3DVOP_LIGHT フラグを指定するかどうかで、頂点バッファに対してライティングを有効または無効にする。


ライト

ライトは、シーンのオブジェクトを照らすために使用する。このセクションでは、ライティングについて、および Direct3D 直接モードでのライトの使用方法について説明する。説明するトピックは次のとおりである。

  • ライト オブジェクトの概要
  • ライト プロパティ
  • ライトの使用


ライト オブジェクトの概要

Direct3D では、ポイント ライト、スポット ライト、およびディレクショナル ライトの 3 種類のライトを使用する。ライト プロパティ セットを作成するときに、使用するライトの種類を選択する。ライト プロパティとそれに伴う計算上のオーバーヘッドは、ライティングの種類によって異なる。Direct3D ライティング モジュールでサポートされる、以下の光源について説明する。

  • ポイント ライト
  • スポット ライト
  • ディレクショナル ライト

注 : DirectX 7.0 では、旧リリースの DirectX で使用したパラレル ポイント ライトは使用しない。

光源とアンビエント ライト レベルを混同しないこと。詳細については、「ダイレクト ライトとアンビエント ライトの比較」、「ライト プロパティ」、および「ライトの使用」を参照すること。


ライト プロパティ

ライト プロパティは、光源の種類と色を決める。使用するライトの種類によって、ライトは減衰と範囲のプロパティやスポット ライト エフェクトのプロパティを持つことができる。しかし、ライトの種類によっては使用できないプロパティもある。Direct3D 直接モードでは、C++ の場合は D3DLIGHT7 構造体、Visual Basic の場合は D3DLIGHT7 型に、すべての種類の光源のライト プロパティに関する情報を保持する。このセクションでは、すべてのライト プロパティについて説明する。説明するトピックは以下のとおりである。

  • ライトの種類
  • ライトの色
  • ライトの位置座標、範囲、および減衰
  • ライトの方向
  • スポット ライト プロパティ

ライト プロパティは、光源がシーン内のオブジェクトをどのように照らすかに影響する。詳細については、「ライトの使用」、「ライト プロパティの設定」、および「Direct3D のライティングにおける数学的計算」を参照すること。


ライトの使用

このセクションでは、Direct3D 直接モード アプリケーションでのライトの使用について説明する。説明するトピックは次のとおりである。

  • ライト プロパティの設定
  • ライトの有効/無効
  • ライト プロパティの取得


マテリアル

このセクションでは、マテリアルと Direct3D 直接モード アプリケーションでのマテリアルの使用方法について説明する。説明するトピックは次のとおりである。

  • マテリアルとは
  • マテリアル プロパティ
  • マテリアルの使用

デフォルトのマテリアル プロパティ アプリケーションで、レンダリング処理にマテリアル プロパティが指定されていない場合は、デフォルトのマテリアルが使用される。デフォルトのマテリアルは、すべてのディフューズ ライト (ほぼ白色) を反射するが、アンビエント反射またはスペキュラ反射は生じず、エミッション色がない。


マテリアルとは

マテリアルは、3D シーンでポリゴンが光をどのように反射するか、またはどのように光を放射するように見えるかを指定する。本質的には、マテリアルは、Direct3D がレンダリングするポリゴンについて次の情報を Direct3D に指示するプロパティの集合である。

  • ポリゴンによるアンビエント ライトとディフューズ ライトの反射方法
  • ポリゴンからのスペキュラ ハイライトの状態
  • ポリゴンが光を発しているように見せるかどうか
[C++]

C++ で記述された、Direct3D 直接モードのアプリケーションでは、D3DMATERIAL7 構造体を使用してマテリアル プロパティを定義する。詳細については、「マテリアル プロパティ」を参照すること。

[Visual Basic]

Visual Basic で記述された、Direct3D 直接モードのアプリケーションでは、D3DMATERIAL7 型を使用してマテリアル プロパティを定義する。詳細については、「マテリアル プロパティ」を参照すること。


マテリアル プロパティ

[C++]

マテリアル プロパティは、マテリアルのディフューズ、アンビエント反射、エミッション、およびスペキュラ ハイライト特性を詳細に指定する。Direct3D は、D3DMATERIAL7 構造体にすべてのマテリアル プロパティを保持する。マテリアル プロパティは、そのマテリアルを使用するポリゴンをラスタ化するときに Direct3D が使用する色に影響する。スペキュラ属性を除き、各プロパティは、マテリアルが所定の種類のライトの赤、緑、および青成分をどのくらい反射するかを表す RGBA 色と、アルファ ブレンディング係数 (RGBA 色のアルファ成分) として指定する。マテリアルのスペキュラ属性は、色および強度で指定する。詳細については、「ライティングとマテリアルのカラー値」を参照すること。

ディフューズ反射とアンビエント反射

D3DMATERIAL7 構造体の dcvDiffuse および dcvAmbient メンバは、シーン内でマテリアルがアンビエント ライトとディフューズ ライトをどのように反射するかを指定する。ほとんどのシーンでは、アンビエント ライトよりもディフューズ ライトの方がずっと多く使用されるため、色の決定においてはディフューズ反射が最も大きく影響する。さらに、ディフューズ ライトは向きを持っているため、その入射角は反射の全体的な強度に影響を与える。ディフューズ反射は、ライトが頂点法線と平行に頂点に当るときが最も強い。入射角が大きくなるにつれて、ディフューズ反射のエフェクトは減少する。次に示すように、反射光の量は入射光と頂点法線がなす角度の余弦である。

アンビエント ライトと同様、アンビエント反射は向きを持たない。アンビエント反射は、レンダリングしたオブジェクトの見かけの色への影響は少ないが、全体の色に影響し、マテリアルから反射するディフューズ ライトがまったくないか、ほんのわずかであるときに最も目立つ。マテリアルのアンビエント反射は、D3DLIGHTSTATE_AMBIENT フラグを指定して IDirect3DDevice7::SetLightState メソッドを呼び出すことでシーンに設定したアンビエント ライトの影響を受ける。

ディフューズ反射およびアンビエント反射は、ともに作用してオブジェクトで知覚される色を決める。これらは通常は同じ値である。たとえば、青色の水晶オブジェクトをレンダリングするには、ディフューズ ライトとアンビエント ライトの青成分のみ反射するマテリアルを作成する。この水晶を白色光で照らされた部屋に置くと青色に見える。しかし、赤色光しかない部屋では、同じ水晶でも黒く見える。これは、水晶のマテリアルが赤色光を反射しないためである。

エミッション

マテリアルを使用して、レンダリングしたオブジェクト自体が光を発しているように見せることができる。D3DMATERIAL7 構造体の dcvEmissive メンバを使用して、エミッション光の色および透明度を指定する。エミッションはオブジェクトの色に影響する。たとえば、暗いマテリアルを明るくし、発光色の一部になることができる。

マテリアルのエミッション属性を使用して、オブジェクトが光を発しているように見せることができる。この方法では、シーンにライトを追加する際のオーバーヘッドが発生しない。青色の水晶の例で、シーン内のほかのオブジェクトにはライトを照らさずに、水晶だけが輝いているように見せる場合は、エミッション属性を使用するとよい。エミッション属性を持つマテリアルが発する光は、シーン内のほかのオブジェクトで反射できる光ではないので注意すること。このエフェクトを得るには、シーン内に追加のライトを配置する必要がある。

スペキュラ反射

スペキュラ反射はオブジェクト上にハイライトを作成し、オブジェクトが輝いているように見せる。D3DMATERIAL7 構造体には、スペキュラ ハイライト色とマテリアルの全体的な輝きを指定する 2 つのメンバが含まれる。dcvSpecular メンバを希望の RGBA 色 (最も一般的な色は白色または明るいグレーである) に設定して、スペキュラ ハイライトの色を決める。dvPower メンバに設定する値は、スペキュラ エフェクトのシャープさを制御する。

スペキュラ ハイライトを使用すると、すばらしいエフェクトが得られる。再び青色の水晶を例として考える。dvPower の値が大きいほど鮮明なスペキュラ ハイライトになり、水晶の輝きが増す。この値が小さいほどエフェクトの及ぶ領域は拡大するが、反射が鈍くなり水晶が霜で覆われたように見える。まったく光沢のないオブジェクトにするには、dvPower メンバをゼロに設定し、dcvSpecular の色を黒に設定する。思いどおりのリアルな表示になるように、さまざまな反射レベルを試してみる。次の図は、2 つの同じモデルを示す。左側のモデルではスペキュラ反射強度を 10 に設定し、右側のモデルではスペキュラ反射を設定していない。

[Visual Basic]

マテリアル プロパティは、マテリアルのディフューズ反射、アンビエント反射、エミッション、およびスペキュラ ハイライト特性を詳細に指定する。Direct3D は、D3DMATERIAL7 型にすべてのマテリアル プロパティを保持する。マテリアル プロパティは、そのマテリアルを使用するポリゴンをラスタ化するときに Direct3D が使用する色に影響する。スペキュラ属性を除き、各プロパティは、マテリアルが所定の種類のライトの赤、緑、および青成分をどのくらい反射するかを表す RGBA 色と、アルファ ブレンディング係数 (RGBA 色のアルファ成分) として指定する。マテリアルのスペキュラ属性は、色および強度で指定する。詳細については、「ライティングとマテリアルのカラー値」を参照すること。

ディフューズ反射とアンビエント反射

D3DMATERIAL7 型の diffuse および ambient メンバは、シーン内でマテリアルがアンビエント ライトとディフューズ ライトをどのように反射するかを指定する。ほとんどのシーンでは、アンビエント ライトよりもディフューズ ライトの方がずっと多く使用されるため、色の決定においてはディフューズ反射が最も大きく影響する。さらに、ディフューズ ライトは向きを持っているため、その入射角は反射の全体的な強度に影響を与える。ディフューズ反射は、ライトが頂点法線と平行に頂点に当るときが最も強い。入射角が大きくなるにつれて、ディフューズ反射のエフェクトは減少する。次に示すように、反射光の量は入射光と頂点法線がなす角度の余弦である。

アンビエント ライトと同様、アンビエント反射は向きを持たない。アンビエント反射は、レンダリングしたオブジェクトの見かけの色への影響は少ないが、全体の色に影響し、マテリアルから反射するディフューズ ライトがまったくないか、ほんのわずかであるときに最も目立つ。マテリアルのアンビエント反射は、D3DRENDERSTATE_AMBIENT フラグを指定して Direct3DDevice7.SetRenderState メソッドを呼び出すことでシーンに設定したアンビエント ライトの影響を受ける。

ディフューズ反射およびアンビエント反射は、ともに作用してオブジェクトで知覚される色を決める。これらは通常は同じ値である。たとえば、青色の水晶オブジェクトをレンダリングするには、ディフューズ ライトとアンビエント ライトの青成分のみ反射するマテリアルを作成する。この水晶を白色光で照らされた部屋に置くと青色に見える。しかし、赤色光しかない部屋では、同じ水晶でも黒く見える。これは、水晶のマテリアルが赤色光を反射しないためである。

エミッション

マテリアルを使用して、レンダリングしたオブジェクト自体が光を発しているように見せることができる。D3DMATERIAL7 型の emissive メンバを使用して、エミッション光の色と透明度を指定する。エミッションはオブジェクトの色に影響する。たとえば、暗いマテリアルを明るくし、エミッション色の一部になることができる。

マテリアルのエミッション属性を使用して、オブジェクトが光を発しているように見せることができる。この方法では、シーンにライトを追加する際のオーバーヘッドが発生しない。青色の水晶の例で、シーン内のほかのオブジェクトにはライトを照らさずに、水晶だけが輝いているように見せる場合は、エミッション属性を使用するとよい。エミッション属性を持つマテリアルが発する光は、シーン内のほかのオブジェクトで反射できる光ではないので注意すること。このエフェクトを得るには、シーン内に追加のライトを配置する必要がある。

スペキュラ反射

スペキュラ反射はオブジェクト上にハイライトを作成し、オブジェクトが輝いているように見せる。D3DMATERIAL7 型には、スペキュラ ハイライト色とマテリアルの全体的な輝きを指定する 2 つのメンバが含まれる。specular メンバを希望の RGBA 色 (最も一般的な色は白色または明るいグレーである) に設定して、スペキュラ ハイライトの色を決める。power メンバに設定する値は、スペキュラ エフェクトのシャープさを制御する。

スペキュラ ハイライトを使用すると、すばらしいエフェクトが得られる。再び青色の水晶を例として考える。power の値が大きいほど鮮明なスペキュラ ハイライトになり、水晶の輝きが増す。この値が小さいほどエフェクトの及ぶ領域は拡大するが、反射が鈍くなり水晶が霜で覆われたように見える。まったく光沢のないオブジェクトにするには、power メンバをゼロに設定し、specular の色を黒に設定する。思いどおりのリアルな表示になるように、さまざまな反射レベルを試してみる。次の図は、2 つの同じモデルを示す。左側のモデルではスペキュラ反射強度を 10 に設定し、右側のモデルではスペキュラ反射を設定していない。


マテリアルの使用

このセクションでは、Direct3D アプリケーションでのマテリアルの使用について説明する。説明するトピックは次のとおりである。

  • マテリアル プロパティの設定
  • マテリアル プロパティの取得


Direct3D のライティングにおける数学的計算

Direct3D は、自然光の振る舞いを評価してライティングをモデル化する。Direct3D ライティング モデルは、ライティングの色、ライティングの進行方向と距離、ビューアの位置座標、およびマテリアルの特性を監視して、面の各頂点で 2 つの色成分を計算する。Direct3D は、これらの色成分を使用して、面のピクセルをラスタ化するときに描画する色を計算する。

注 : すべての計算はモデル空間で行われる。ワールド行列の逆行列を使用してカメラ位置座標と共にライトの位置座標と方向をモデル空間にトランスフォームし、次に逆トランスフォームする。その結果、ワールド行列またはビュー行列によって一様でないスケーリングが生じる場合は、最終的なライティングが不正確になることがある。

このセクションでは、ディフューズ成分とスペキュラ成分を提供するために Direct3D で使用する公式について技術的観点から説明する。Direct3D の方法を理解すれば、Direct3D ライティング モデルが要望に合うかどうかをより正確に判断できるようになる。Direct3D ライティング モデルは、正確さ、効率性、および使いやすさを目指して設計されている。しかし、Direct3D で使用する公式がニーズに合わない場合は、Direct3D ライティング モジュールは使用せず、独自のライティング モデルを実装することもできる。

  • ライトの色の種類とソース
  • 距離の増加によるライトの減衰
  • 反射率モデル
  • スポット ライト フォールオフ モデル
  • フォグ エフェクト


ライトの色の種類とソース

Direct3D の光源は、互いに独立してライティング計算の係数として働く個々のライティング コンポーネントとして、ディフューズ色、アンビエント色、およびスペキュラ色を発する (このライティング モデルは、DirectX 7.0 より前のバージョンで使用したものとは異なる。以前は、すべてのライティング計算に単一のライティング色が使用された)。同様に、システムがレンダリングする頂点は、その頂点フォーマットによって定義された個別のディフューズ色、アンビエント色、スペキュラ色、およびエミッション色を使用する。

[C++]

C++ アプリケーションの場合、これらの頂点色は、D3DRENDERSTATE_COLORVERTEX レンダリング ステートを TRUE に設定したときにのみ、システムによって使用される。頂点の色ソースは選択可能である。つまり、実行時にライティング式の頂点色部分のソースを選択するように設定できる。D3DRENDERSTATE_AMBIENTMATERIALSOURCE、D3DRENDERSTATE_DIFFUSEMATERIALSOURCE、および D3DRENDERSTATE_SPECULARMATERIALSOURCE レンダリング ステートは、ライティング計算においてシステムが描画する色の色ソースを制御する。これらの各レンダリング ステートは、D3DMATERIALCOLORSOURCE 列挙型のメンバに設定できる。これは、色ソースとして現在のマテリアルを使用するか、または頂点の色を使用するかを指定する値を定義する。

[Visual Basic]

Visual Basic の場合、頂点色は、D3DRENDERSTATE_COLORVERTEX レンダリング ステートを TRUE に設定したときにのみ、システムによって使用される。頂点の色ソースは選択可能である。つまり、実行時にライティング式の頂点色部分のソースを選択するように設定できる。D3DRENDERSTATE_AMBIENTMATERIALSOURCE、D3DRENDERSTATE_DIFFUSEMATERIALSOURCE、および D3DRENDERSTATE_SPECULARMATERIALSOURCE レンダリング ステートは、ライティング計算においてシステムが描画する色の色ソースを制御する。これらの各レンダリング ステートは、CONST_D3DMATERIALCOLORSOURCE 列挙のメンバに設定できる。これは、色ソースとして現在のマテリアルを使用するか、または頂点の色を使用するかを指定する値を定義する。


距離の増加によるライトの減衰

[C++]

Direct3D では、ライトで照らされた頂点と光源の間の距離を、ライトの位置座標と頂点の間のベクトルの大きさによって決定する。これを次の公式で表す。

この公式では、D は計算する距離、V はライトで照らされた頂点の位置座標、L は光源の位置座標である。D がライトの範囲 (D3DLIGHT7 構造体の dvRange メンバ) より大きい場合、Direct3D はそれ以上減衰計算を実行せず、ライティング エフェクトを頂点に適用しなくなる。距離がライトの範囲内にある場合は、Direct3D は以下の公式を適用して、距離の増加に伴うポイント ライトおよびスポット ライトのライトの減衰を計算する (ディレクショナル ライトは減衰しない)。

この減衰公式では、A は計算した全減衰、D は光源から頂点までの距離である。dvAttenuation0、dvAttenuation1、および dvAttenuation2 の値は、ライト オブジェクトの D3DLIGHT7 構造体のメンバによって指定される、ライトの減衰定数である。対応するメンバはそれぞれ、dvAttenuation0、dvAttenuation1、および dvAttenuation2 である。

減衰定数は公式では係数になる。これらの係数に簡単な調整を加えることで、さまざまな減衰曲線を生成できる。dvAttenuation0 を 1.0 に設定して、減衰しない光を作成できる (ただし、範囲による制限は受ける)。また、いろいろな値を試してみて、さまざまな減衰エフェクトを出すことができる。

DirectX 6.x の場合、Direct3D の減衰公式では、通常、光源を 1.0、ライトの最大範囲を 0.0 とする範囲で減衰値が計算された。ところが、DirectX 7.x では、ライトの最大範囲における減衰は 0.0 ではない。ライトの範囲内でライトが突然現れるのを防止するために、アプリケーションではライトの範囲を増やすことができる。また、アプリケーションで、ライトの範囲における減衰係数が 0.0 に近づくように減衰定数を設定できる。減衰値を乗算してライトの色の赤、緑、および青成分を算出し、ライトの強度を光が頂点まで進む距離の係数として定めることができる。

ライトの減衰を計算した後、Direct3D では、スポット ライト エフェクト (適用する場合)、サーフェスからの光の反射角度、および現在のマテリアルの反射率を考慮して、その頂点に対するディフューズ成分とスペキュラ成分を算出する。詳細については、「スポット ライト フォールオフ モデル」および「反射率モデル」を参照すること。

[Visual Basic]

Direct3D では、ライティングで照らされた頂点と光源の間の距離を、ライティングの位置座標と頂点の間のベクトルの大きさによって決定する。これを次の公式で表す。

この公式では、D は計算する距離、V はライティングで照らされた頂点の位置座標、L は光源の位置座標である。D がライティングの範囲 (D3DLIGHT7 型の range メンバ) より大きい場合、Direct3D はそれ以上減衰計算を実行せず、ライティング エフェクトを頂点に適用しなくなる。距離がライティングの範囲内にある場合は、Direct3D は以下の公式を適用して、距離の増加に伴うポイント ライトおよびスポット ライトのライトの減衰を計算する (ディレクショナル ライトは減衰しない)。

この減衰公式では、A は計算した全減衰、D は光源から頂点までの距離である。attenuation0、attenuation1、および attenuation2 の値は、ライト オブジェクトの D3DLIGHT7 型のメンバによって指定される、ライティングの減衰定数である。対応するメンバはそれぞれ、attenuation0、attenuation1、および attenuation2 である。

減衰定数は公式では係数になる。これらの係数に簡単な調整を加えることで、さまざまな減衰曲線を生成できる。attenuation0 を 1.0 に設定して、減衰しない光を作成できる (ただし、範囲による制限は受ける)。また、いろいろな値を試してみて、さまざまな減衰エフェクトを出すことができる。

ライティングの最大範囲における減衰は 0.0 ではない。ライティングの範囲内でライティングが突然現れるのを防止するために、アプリケーションではライティングの範囲を増やすことができる。また、アプリケーションで、ライティングの範囲における減衰係数が 0.0 に近づくように減衰定数を設定できる。減衰値を乗算してライティングの色の赤、緑、および青成分を算出し、ライティングの強度を光が頂点まで進む距離の係数として定めることができる。

ライティング減衰を計算した後、Direct3D では、スポット ライト エフェクト (適用する場合)、サーフェスからの光の反射角度、および現在のマテリアルの反射率を考慮して、その頂点に対するディフューズ成分とスペキュラ成分を算出する。詳細については、「スポット ライト フォールオフ モデル」および「反射率モデル」を参照すること。


反射率モデル

すべての減衰エフェクトでライティング強度を調整した後、Direct3D では頂点法線と入射光の方向の角度を仮定して、頂点から反射する残光の量を計算する (ディレクショナル ライトではこの手順は実行されない。距離が増加しても光が減衰しないためである)。

Direct3D ではディフューズとスペキュラの 2 種類の反射を考慮し、異なる公式を使用して各ライティングで反射する光の量を決定する。反射するライティングの量を計算した後、Direct3D はこれらの新しい値を、現在のマテリアルのディフューズ反射率プロパティとスペキュラ反射率プロパティに適用する。この結果として生じるカラー値は、グーロー シェーディングとスペキュラ ハイライト生成のためにラスタライザが使用するディフューズ成分とスペキュラ成分である。

このセクションでは、システムによる反射率の計算方法について説明する。次のトピックは、計算する反射率の種類に対応している。

  • ディフューズ反射モデル
  • スペキュラ反射モデル


スポット ライト フォールオフ モデル

[C++]

スポット ライトは、明るい内部コーンおよび外部コーンの 2 つの部分を持つ光のコーンを放射する。ライティングは、内部コーンの内側が最も明るく、外部コーンの外側にはライティングが存在しない。ライティングの強度は、この 2 つの領域の間で減衰する。一般に、このような減衰をフォールオフと呼ぶ。

頂点を照らす光の量は、頂点が内部コーンの内側にあるか、外部コーンの内側にあるかによって異なる。Direct3D は、スポット ライトの方向ベクトル (L) と頂点からスポット ライトへのベクトル (D) の内積を計算する。この値は、2 つのベクトルがなす角度の余弦に等しく、ライトのコーン角度と比較できる頂点位置座標を示すので、内部コーンまたは外部コーンのどちらに頂点があるかを判断するのに役立つ。次の図は、これら 2 つのベクトルの間の関係を示す。

次に、システムは、この値をスポット ライトの内部および外部コーンの角度の余弦と比較する。ライティングの D3DLIGHT7 構造体の dvTheta および dvPhi メンバは、内部および外部コーンの角度の合計を表す。減衰は、全コーン角度にわたってではなく、ライティングの中心から頂点が離れることによって生じるため、Direct3D はコーン角度を半分に割ってから余弦を計算する。

ベクトル L と D の内積が外部コーンの角度の余弦以下の場合、頂点は外部コーンの外側に存在し、ライティングで照らされない。L と D の内積が内部コーン角度の余弦より大きい場合、頂点は内部コーンの内側に存在し、最大量のライティングで照らされる (ただし、距離の増加による減衰を考慮する)。頂点が 2 つの領域の間にある場合、Direct3D は次の公式を使用して頂点におけるライトのフォールオフを計算する。

この公式では、If はライティングの当たる頂点における (フォールオフ後の) 光の強度、a はベクトル L と D がなす角度、f は外部コーンの角度の半分の角度、q は内部コーンの角度の半分の角度、p はスポット ライトのフォールオフ プロパティ (D3DLIGHT7 構造体の dvFalloff) である。この公式では、頂点における光の強度を定める 0.0 ～ 1.0 の値を求めて、ライティングのフォールオフを示す。ライトから頂点までの距離の係数として減衰も適用される。p 値は、D3DLIGHT7 構造体の dvFalloff メンバに対応し、フォールオフ曲線の形状を制御する。次の図は、dvFalloff 値によってフォールオフ曲線がどのように変化するかを示す。

dvFalloff 値が変化しても実際のライティングに与える影響はわずかであり、dvFalloff 値が 1.0 以外のときに形成されるフォールオフ曲線で若干のパフォーマンス低下が生じるのみである。このような理由から、ほとんどの場合、この値は 1.0 に設定する。

詳細については、「距離の増加によるライトの減衰」を参照すること。

[Visual Basic]

スポット ライトは、明るい内部コーンおよび外部コーンの 2 つの部分を持つ光のコーンを放射する。ライティングは、内部コーンの内側が最も明るく、外部コーンの外側にはライティングが存在しない。ライティングの強度は、この 2 つの領域の間で減衰する。一般に、このような減衰をフォールオフと呼ぶ。

頂点を照らす光の量は、頂点が内部コーンの内側にあるか、外部コーンの内側にあるかによって異なる。Direct3D は、スポット ライトの方向ベクトル (L) と頂点からスポット ライトへのベクトル (D) の内積を計算する。この値は、2 つのベクトルがなす角度の余弦に等しく、ライティングのコーン角度と比較できる頂点位置座標を示すので、内部コーンまたは外部コーンのどちらに頂点があるかを判断するのに役立つ。次の図は、これら 2 つのベクトルの間の関係を示す。

システムは、この値をスポット ライトの内部および外部コーンの角度の余弦と比較する。スポット ライトの D3DLIGHT7 構造体の theta および phi メンバは、内部および外部コーンの角度の合計を表す。減衰は、全コーン角度にわたってではなく、ライティングの中心から頂点が離れることによって生じるため、Direct3D はコーン角度を半分に割ってから余弦を計算する。

ベクトル L と D の内積が外部コーンの角度の余弦以下の場合、頂点は外部コーンの外側に存在し、ライティングで照らされない。L と D の内積が内部コーン角度の余弦より大きい場合、頂点は内部コーンの内側に存在し、最大量のライティングで照らされる (ただし、距離の増加による減衰を考慮する)。頂点が 2 つの領域の間にある場合、Direct3D は次の公式を使用して頂点におけるライティングのフォールオフを計算する。

この公式では、If はライティングされている頂点における (フォールオフ後の) 光の強度、a はベクトル L と D がなす角度、f は外部コーンの角度の半分の角度、q は内部コーンの角度の半分の角度、p はスポット ライトのフォールオフ プロパティ (D3DLIGHT7 型の falloff) である。この公式では、頂点における光の強度を定める 0.0 ～ 1.0 の値を求めて、ライトのフォールオフを示す。ライティングから頂点までの距離の係数として減衰も適用される。p 値は、D3DLIGHT7 型の falloff メンバに対応し、フォールオフ曲線の形状を決定する。次の図は、falloff 値によってフォールオフ曲線がどのように変化するかを示す。

falloff 値が変化しても実際のライティングに与える影響はわずかであり、falloff 値が 1.0 以外のときに形成されるフォールオフ曲線で若干のパフォーマンス低下が生じるのみである。このような理由から、ほとんどの場合、この値は 1.0 に設定する。

詳細については、「距離の増加によるライトの減衰」を参照すること。


フォグ エフェクト

Direct3D のトランスフォーム & ライティング エンジンでは、ライティング中にフォグ エフェクトを作成できる。このようなフォグは、フォグ情報が、ラスタ化される頂点のアルファ成分に配置されることから、通常は "頂点フォグ" と呼ばれる。詳細については、「フォグ」および「頂点フォグ」を参照すること。


頂点フォーマット

このセクションでは、Direct3D で頂点を指定するために理解しておく必要がある概念について説明し、頂点を宣言するためにアプリケーションで使用できる各種フォーマットの情報について説明する。説明するトピックは次のとおりである。

  • 頂点フォーマットについて
  • 未トランスフォーム 未ライティングの頂点
  • 未トランスフォーム ライティング済みの頂点
  • トランスフォーム済み ライティング済みの頂点
  • ストライド頂点フォーマット
[C++]

注 : Direct 6.0 より前は、Direct3D ジオメトリ パイプラインのどの部分が使用されているかによって、アプリケーションでは 3 つの頂点タイプ D3DVERTEX、D3DLVERTEX、および D3DTLVERTEX のいずれかを使用する必要があった。DirectX 6.0 以降、より柔軟な頂点フォーマットが導入され、以前よりも多くの方法で頂点を宣言できるようになっているが、あらかじめ定義された構造体を使用して、「未トランスフォーム 未ライティングの頂点」、「未トランスフォーム ライティング済みの頂点」、および「トランスフォーム済み ライティング済みの頂点」を記述することもできる。詳細については、このセクションの各頂点タイプのトピックを参照すること。

[C++,Visual Basic]


頂点フォーマットについて

Direct3D 直接モードのアプリケーションでは、複数の方法でモデルの頂点を定義できる。柔軟な頂点定義 ("柔軟な頂点フォーマット" とも呼ぶ) がサポートされていることから、必要な頂点成分のみアプリケーションで使用し、使用しない頂点成分は削除できる。必要な頂点成分のみ使用できるので、アプリケーションでメモリを節約でき、モデルのレンダリングに必要な処理帯域幅を最小限に抑えることができる。柔軟な頂点フォーマット フラグを組み合わせて使用して、頂点のフォーマット方法を指定する。

[C++]

C++ アプリケーションでは、IDirect3DDevice7 インターフェイスのレンダリング メソッドにより、これらのフラグの組み合わせを受け取るメソッドを使用でき、その組み合わせを使用してプリミティブのレンダリング方法を決める。基本的には、これらのフラグは、アプリケーションでどの頂点成分 (位置座標、頂点ブレンディング ウェイト (重み)、法線、色、およびテクスチャ座標の数とフォーマット) を使用するかをシステムに知らせ、また、Direct3D でレンダリング パイプラインのどの部分を頂点成分に適用するかを間接的に知らせる。さらに、特定の頂点フォーマット フラグの有無によって、メモリに存在する頂点成分フィールドと、省略した頂点成分をシステムに知らせる。

デバイスの制限を調べるには、D3DFVFCAPS_DONOTSTRIPELEMENTS および D3DFVFCAPS_TEXCOORDCOUNTMASK 柔軟な頂点フォーマット フラグについてデバイスを問い合わせる。詳細については、「D3DDEVICEDESC7 構造体の dwFVFCaps メンバ」を参照すること。

注 : アプリケーションでIDirect3DDevice7::DrawPrimitiveStrided または IDirect3DDevice7::DrawIndexedPrimitiveStrided メソッドを使用する場合は、これは少し異なる。詳細については、「ストライド頂点フォーマット」を参照すること。

頂点のフォーマット方法に関するシステム条件の中で重要なのは、データの表示順序である。次の図は、メモリ内のすべての頂点成分の順序とそれに関係するデータ型を示す。

注 : DirectX 7.0 では、テクスチャ座標はさまざまな方法で宣言でき、最少 1 要素の座標、最大 3 要素のテクスチャ座標 (2D 射影テクスチャ座標の場合) を使用してテクスチャを処理できる。詳細については、「テクスチャ座標フォーマット」を参照すること。マクロの D3DFVF_TEXCOORDSIZEn セットを使用して、頂点フォーマットで使用するテクスチャ座標フォーマットを識別するためのビット パターンを作成する。

実際のアプリケーションで、すべての単一コンポーネントを使用するとは限らない。RHW (同次 W の逆数) と頂点法線フィールドは互いに排他的である。また、ほとんどのアプリケーションで 8 つのテクスチャ座標セットをすべて使用するとも限らない。しかし、それでも柔軟性はある。あるフラグを別のフラグと併用する場合には、いくつかの制限がある。これらの制限はほとんど常識で判断できる。たとえば、D3DFVF_XYZ フラグと D3DFVF_XYZRHW フラグは併用できない。この場合、未トランスフォームの頂点とトランスフォームされた頂点の両方を使用して、1 つの頂点の位置座標を定義することになるからである。詳細については「柔軟な頂点フォーマット フラグ」の各フラグの説明を参照すること。

[Visual Basic]

Visual Basic の Direct3DDevice7 クラスには、これらのフラグを組み合わせを受け取るメソッドがあり、この組み合わせを使用してプリミティブのレンダリング方法を決める。基本的には、これらのフラグは、アプリケーションでどの頂点成分 (位置座標、頂点ブレンディング ウェイト (重み)、法線、色、およびテクスチャ座標の数とフォーマット) を使用するかをシステムに知らせ、また、Direct3D でレンダリング パイプラインのどの部分を頂点成分に適用するかを間接的に知らせる。さらに、特定の頂点フォーマット フラグの有無によって、メモリに存在する頂点成分フィールドと、省略した頂点成分をシステムに知らせる。

デバイスの制限を調べるには、D3DFVFCAPS_DONOTSTRIPELEMENTS および D3DFVFCAPS_TEXCOORDCOUNTMASK 柔軟な頂点フォーマット フラグについてデバイスを問い合わせる。詳細については、「D3DDEVICEDESC7 型の lFVFCaps メンバ」を参照すること。

頂点のフォーマット方法に関するシステム条件の中で重要なのは、データの表示順序である。次の図は、メモリ内のすべての頂点成分の順序とそれに関係するデータ型を示す。

テクスチャ座標はさまざまなフォーマットで宣言でき、最少 1 要素の座標、最大 3 要素のテクスチャ座標 (2D 射影テクスチャ座標の場合) を使用してテクスチャを処理できる。Math.bas からヘルパー関数の D3DFVF_TEXCOORDSIZEn セットを使用して、頂点フォーマットで使用するテクスチャ座標フォーマットを識別するためのビット パターンを作成する。Math.bas の Visual Basic コード モジュールが、この SDK に付属している。

実際のアプリケーションで、すべての単一コンポーネントを使用するとは限らない。RHW (同次 W の逆数) と頂点法線フィールドは互いに排他的である。また、ほとんどのアプリケーションで 8 つのテクスチャ座標セットをすべて使用するとも限らない。しかし、それでも柔軟性はある。あるフラグを別のフラグと併用する場合には、いくつかの制限がある。これらの制限はほとんど常識で判断できる。たとえば、D3DFVF_XYZ フラグと D3DFVF_XYZRHW フラグは併用できない。この場合、未トランスフォームの頂点とトランスフォーム済みの頂点の両方を使用して、1 つの頂点の位置座標を定義することになるからである。詳細については「柔軟な頂点フォーマット フラグ」の各フラグの説明を参照すること。


未トランスフォーム 未ライティングの頂点

レンダリング メソッドに渡す頂点記述に D3DFVF_XYZ (または D3DFVF_XYZBn フラグのいくつか) および D3DFVF_NORMAL フラグがある場合、「未トランスフォーム 未ライティングの頂点」タイプが指定されている。「未トランスフォーム 未ライティングの頂点」を使用すると、アプリケーションは Direct3D にその内部アルゴリズムを使用してすべてのトランスフォーム & ライティング処理を実行するよう効率的に要求できる (必要であれば、D3DRENDERSTATE_LIGHTING レンダリング ステートを FALSE に設定して、レンダリングするプリミティブに対して Direct3D ライティング エンジンを無効にできる)。

この頂点タイプは、アプリケーションで独自のトランスフォーム & ライティング エンジンを実装する必要がないので、ほとんどのアプリケーションで使用される。ただし、システムによって自動的に計算が実行されるため、各頂点に対していくらかの情報を指定しておく必要がある。

  • 未トランスフォームのモデル座標で頂点を指定する必要がある (モデル座標頂点は、ワールドに対してではなく、モデルのローカル原点に対する相対位置座標に配置される)。次に、システムは、ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォームをモデル座標に適用してシーン内に頂点を配置し、頂点の画面上での最終位置座標を決定する。
  • よりリアルなライティング エフェクトを出すために、頂点法線を含める (頂点法線を含んでいない頂点をライティングで照らす場合、その頂点は 0 の内積を使用する。つまり、その頂点は入射光を受けないものとして処理される)。システムは、カレント マテリアルに加えて、頂点法線を使用してライティング計算を実行する。詳細については、「面法線ベクトルと頂点法線ベクトル」、「ライティングとマテリアル」、および「Direct3D のライティングにおける数学的計算」を参照すること。
[C++]

これらの条件以外では、その他の頂点成分を柔軟に使用 (または無視) できる。たとえば、ディフューズまたはスペキュラ色を未トランスフォームの頂点に含めることができる (これは DirectX 6.0 以前ではできなかった)。各頂点に個々の色を含めると、マテリアル カラーのみ使用したライティング計算を実行するよりも、ずっと繊細で柔軟なシェーディング エフェクトが得られる。ただし、この場合、D3DRENDERSTATE_COLORVERTEX レンダリング ステートを使用して個々の頂点色を有効にする必要がある。また、未トランスフォーム 未ライティングの頂点には、最大 8 つまでテクスチャ座標セットを含めることができる。

アプリケーションでは、頂点に対して従来の D3DVERTEX 構造体も使用できる。実際、この頂点フォーマットを識別するショートカット マクロが、d3dtypes.h ヘッダー ファイルに定義されている。

#define D3DFVF_VERTEX ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_TEX1 )

D3DVERTEX 構造体がアプリケーションの要件に合わないときは、その要件を満たすように独自に定義できる。ただし、どの頂点成分がアプリケーションで必要であるかに注意し、必ず正しく順序付けた構造体を宣言して、必要な順序で頂点成分が表示されるようにしなければならない。次のコードは、位置座標、頂点法線、ディフューズ色、および 2 つのテクスチャ座標セットを含む有効な頂点フォーマット構造体を宣言する。

//
// この頂点の頂点フォーマット記述は、
// (D3DFVF_XY | D3DFVF_NORMAL |// D3DFVF_DIFFUSE | D3DFVF_TEX2)
// になる。
//
typedef struct _UNLITVERTEX {
float x, y, z;        // 位置座標

float nx, ny, nz;     // 法線

DWORD dwDiffuseRGBA;  // ディフューズ色

float tu1,    // テクスチャ座標
tv1;

float tu2,
tv2;
} UNLITVERTEX, *LPUNLITVERTEX;

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZ、D3DFVF_NORMAL、D3DFVF_DIFFUSE、および D3DFVF_TEX2 の組み合わせになる。IDirect3DDevice7::DrawPrimitive などのレンダリング メソッドは、頂点配列のアドレスを void 型のポインタとして受け取るので、レンダリング メソッドを呼び出すときは、頂点配列ポインタを LPVOID データ型にキャストしなければならない。

詳細については、「頂点フォーマットについて」を参照すること。

[Visual Basic]

これらの条件以外では、その他の頂点成分を柔軟に使用 (または無視) できる。たとえば、ディフューズまたはスペキュラ色を未トランスフォームの頂点に含めることができる (これは DirectX 6.0 以前ではできなかった)。各頂点に個々の色を含めると、マテリアル カラーのみ使用したライティング計算を実行するよりも、ずっと繊細で柔軟なシェーディング エフェクトが得られる。ただし、この場合、D3DRENDERSTATE_COLORVERTEX レンダリング ステートを使用して個々の頂点色を有効にする必要がある。また、未トランスフォーム 未ライティングの頂点には、最大 8 つまでテクスチャ座標セットを含めることができる。Visual Basic アプリケーションでは、頂点に D3DVERTEX 型を使用できる。

D3DVERTEX 型がアプリケーションの要件に合わないときは、その要件を満たすように独自に定義ができる。ただし、どの頂点成分がアプリケーションで必要であるかに注意し、必ず正しく順序付けた構造体を宣言して、必要な順序で頂点成分が表示されるようにしなければならない。次のコードは、位置座標、頂点法線、ディフューズ色、および 2 つのテクスチャ座標セットを含む有効な頂点フォーマット構造体を宣言する。

'
// この頂点の頂点フォーマット記述は、
// (D3DFVF_XYZ Or D3DFVF_NORMAL Or D3dFVF_DIFFUSE Or D3DFVF_TEX2)(D3DFVF_XYZ Or D3DFVF_NORMAL Or
// になる。
'
Type UNLITVERTEX
x As Single ' 位置座標
y As Single
z As Single

nx As Single ' 法線
ny As Single
nz As Single

DiffuseRGBA As Long  ' ディフューズ色

tu1 As Single ' テクスチャ座標
tv1 As Single

tu2 As Single ' テクスチャ座標
tv2 As Single
End Type

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZ、D3DFVF_NORMAL、D3DFVF_DIFFUSE、および D3DFVF_TEX2 の組み合わせになる。Direct3DDevice7.DrawPrimitive などのレンダリング メソッドは、頂点配列の第 1 要素を型 Any として受け取り、すべての種類の頂点フォーマットを格納する。

詳細については、「頂点フォーマットについて」を参照すること。


未トランスフォーム ライティング済みの頂点

Direct3D レンダリング メソッドで使用する頂点フォーマット記述に D3DFVF_XYZ フラグを含め、D3DFVF_NORMAL フラグを含めていない場合、その頂点は「未トランスフォーム ライティング済みの頂点」として識別される (フラグの依存および排他関係の詳細については、「柔軟な頂点フォーマット フラグ」を参照すること)。

「未トランスフォーム ライティング済みの頂点」を使用すると、アプリケーションは Direct3D に頂点に対するライティング計算を実行しないように要求するが、Direct3D は以前に設定されたワールド行列、ビュー行列、および射影行列を使用して頂点をトランスフォームする。ライティング計算は実行されないので、頂点法線は必要ない。システムは、各頂点のディフューズ成分とスペキュラ成分をシェーディングに使用する。これらの色は任意に指定しても、独自のライティング公式を使用して計算してもよい。ディフューズ成分またはスペキュラ成分を含めない場合は、デフォルト カラーが使用される。ディフューズ色のデフォルト値は 0xFFFFFFFF で、スペキュラ色のデフォルト値は 0x0 である。

位置座標といくらかの色情報を含めるという点を除いては、その他の頂点タイプと同様、未ライティングの頂点フォーマットにテクスチャ座標セットを含めたり、無視することができる。

[C++]

C++ アプリケーションでは、頂点に対して従来の D3DLVERTEX 構造体も使用できる。d3dtypes.h ヘッダー ファイルには、D3DLVERTEX 構造体のフォーマットを記述するために使用できる、次のヘルパー マクロが定義されている。

#define D3DFVF_LVERTEX ( D3DFVF_XYZ | D3DFVF_RESERVED1 | D3DFVF_DIFFUSE | \
 D3DFVF_SPECULAR | D3DFVF_TEX1 )

ここで注意するのは、ヘルパー マクロには D3DLVERTEX 構造体を使用することをシステムに指示する D3DFVF_RESERVED1 フラグが含まれており、この構造体には dwReserved メンバが含まれていることである。D3DLVERTEX を使用するときにこのメンバが必要なのは、頂点フォーマットには通常予約済みのフィールドが含まれていないためである。D3DFVF_RESERVED1 フラグは、頂点の位置座標とディフューズ色頂点成分の間に未使用の DWORD が存在することをシステムに知らせる。

D3DLVERTEX 構造体にアプリケーションで必要なすべてのフィールドが含まれていない場合は、別の構造体を定義することができる。新しい構造体を宣言するときは、必ず頂点成分が正しい順序になるようにする。次のコードは、ディフューズ頂点色、スペキュラ頂点色、および 3 つのテクスチャ座標セットを持つ、未トランスフォームでライティング済みの有効な頂点を宣言する。

//
// この頂点の頂点フォーマット記述は、
// (D3DFVF_XYZ | D3DFVF_DIFFUSE |// D3DFVF_SPECULAR | D3DFVF_TEX3)
// になる。
//
typedef struct _LITVERTEX {
float x, y, z;        // 位置座標

DWORD dwDiffuseRGBA;  // ディフューズ色

DWORD dwSpecularRGBA; // スペキュラ色

float tu1,    // テクスチャ座標
tv1;

float tu2,
tv2;

float tu3,
tv3;
} LITVERTEX, *LPLITVERTEX;

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZ、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX3 の組み合わせになる。IDirect3DDevice7::DrawPrimitive などのレンダリング メソッドは、頂点配列のアドレスを void 型のポインタとして受け取るので、レンダリング メソッドを呼び出すときは、頂点配列ポインタを LPVOID データ型にキャストしなければならない。

詳細については、「頂点フォーマットについて」を参照すること。

[Visual Basic]

Visual Basic で記述されたアプリケーションでは、独自の頂点フォーマットを定義しても、ライティングのある頂点に D3DLVERTEX 型を使用してもよい。D3DLVERTEX 型にアプリケーションで必要なすべてのフィールドが含まれていない場合は、別の型を定義することができる。新しい構造体を宣言するときは、必ず頂点成分が正しい順序になるようにする。次のコードは、ディフューズ頂点色、スペキュラ頂点色、および 3 つのテクスチャ座標セットを持つ、未トランスフォームでライティング済みの有効な頂点を宣言する。

'
// この頂点の頂点フォーマット記述は、
// (D3DFVF_XYZ Or D3DFVF_DIFFUSE Or D3DFVF_SPECULAR Or D3DFVF_TEX3)(D3DFVF_XYZ Or D3DFVF_DIFFUSE Or
// になる。
'
Type LITVERTEX
x As Single ' 位置座標
y As Single
z As Single

DiffuseRGBA As Long ' ディフューズ色

SpecularRGBA As Long ' スペキュラ色

tu1 As Single ' テクスチャ座標
tv1 As Single

tu2 As Single
tv2 As Single

tu3 As Single
tv3 As Single
End Type

この構造体での頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZ、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX3 の組み合わせになる。Direct3DDevice7.DrawPrimitive などのレンダリング メソッドは、頂点配列の第 1 要素を型 Any として受け取り、すべての種類の頂点フォーマットを格納する。

詳細については、「頂点フォーマットについて」を参照すること。


トランスフォーム済み ライティング済みの頂点

頂点フォーマット記述に D3DFVF_XYZRHW フラグを含めた場合、アプリケーションで「トランスフォーム済み ライティング済みの頂点」を使用することがシステムに通知される。これは、Direct3D でワールド行列、ビュー行列、または射影行列を使用して頂点をトランスフォームせず、ライティング計算も実行しないことを意味している。つまり、Direct3D は、アプリケーションでこれらの処理が実行済みであると見なす (これにより、既存の 3D アプリケーションを Direct3D 直接モードに移植するとき、トランスフォーム済み ライティング済みの頂点がそのまま使える)。要するに、Direct3D は、「トランスフォーム済み ライティング済みの頂点」をまったく変更せず、ドライバに直接渡してラスタ化を実行する。

未トランスフォームの頂点とライティングに関連付けられている頂点フォーマット フラグ (D3DFVF_XYZ と D3DFVF_NORMAL) は、D3DFVF_XYZRHW がある場合は使用できない。フラグの依存および排他関係の詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。

頂点位置座標を指定するときは、トランスフォーム済みのものを指定しなければならない。x と y の値はスクリーン座標内に存在している必要があり、z は Z バッファで使用されるピクセルの深度値でなければならない。z 値は 0.0 ～ 1.0 の値である。0.0 はビューアに最も近い位置座標で、1.0 は可視領域内の最も遠い位置座標である。「トランスフォーム済み ライティング済みの頂点」は、位置座標のすぐ後に RHW 値 (同次 W の逆数) を含んでいなければならない。RHW は、射影空間内で頂点が存在する同次点 (x、y、z、w) からの W 座標の逆数である (この値は、z 軸に沿った、視点から頂点までの距離になることが多い)。

位置座標と RHW の条件を除けば、この頂点フォーマットは、「未トランスフォーム ライティング済みの頂点」と同じである。これまでの説明を以下にまとめる。

  • このフォーマットの場合、ライティング計算は実行されないので、頂点法線は必要ない。
  • ディフューズ色またはスペキュラ色を指定できる。これを指定しない場合は、両方のコンポーネントに 0xFFFFFFFF が使用される。
  • テクスチャ座標セットは、最大 8 つまで使用できる。また、使用しなくてもよい。
[C++]

C++ で記述されたアプリケーションでは、「トランスフォーム済み ライティング済みの頂点」に対して従来の D3DTLVERTEX 構造体も使用できる。d3dtypes.h ヘッダー ファイルには、D3DTLVERTEX 構造体で宣言する頂点フォーマットを記述するために使用できる、次のヘルパー マクロが定義されている。

#define D3DFVF_TLVERTEX ( D3DFVF_XYZRHW | D3DFVF_DIFFUSE | D3DFVF_SPECULAR | \
  D3DFVF_TEX1 )

必要なフィールドが D3DTLVERTEX 構造体に含まれていないことがある。このような場合、必要なフィールドを含む別の構造体を定義できるが、必ず頂点成分を正しい順序で配置すること。次のコードは、ディフューズ頂点色、スペキュラ頂点色、およびテクスチャ座標セットを 1 つだけ持つ、トランスフォーム済みでライティングのある有効な頂点を宣言する。

//
// この頂点の頂点フォーマット記述は、
// (D3DFVF_XYZRHW | D3DFVF_DIFFUSE |// D3DFVF_SPECULAR | D3DFVF_TEX1)
// になる。
//
typedef struct _TRANSLITVERTEX {
    float x, y;   // スクリーン座標

    float z;      // Z バッファ深度

    float rhw;    // 同次 W の逆数

    DWORD dwDiffuseRGBA;  // ディフューズ色

    DWORD dwSpecularRGBA; // スペキュラ色

    float tu1,    // テクスチャ座標
  tv1;
} TRANSLITVERTEX, *LPTRANSLITVERTEX;

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZRHW、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX1 の組み合わせになる。IDirect3DDevice7::DrawPrimitive などのレンダリング メソッドは、頂点配列のアドレスを void 型のポインタとして受け取るので、レンダリング メソッドを呼び出すときは、頂点配列ポインタを LPVOID データ型にキャストしなければならない。

詳細については、「頂点フォーマットについて」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでは、「トランスフォーム済み ライティング済みの頂点」に対して従来の D3DTLVERTEX 型も使用できる。必要なフィールドが D3DTLVERTEX 型に含まれていないことがある。このような場合、必要なフィールドを含む別の構造体を定義できるが、必ず頂点成分を正しい順序で配置すること。次のコードは、ディフューズ頂点色、スペキュラ頂点色、およびテクスチャ座標セットを 1 つだけ持つ、トランスフォーム済みでライティングのある有効な頂点を宣言する。

'
' この頂点の頂点フォーマット記述は、
' (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE Or (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE Or
' D3DFVF_SPECULAR Or D3DFVF_TEX1) である。
'
Type TRANSLITVERTEX
x As Single ' スクリーン座標
y As Single

z As Single ' z バッファ深度

rhw As Single ' 同次 W の逆数

DiffuseRGBA As Long ' ディフューズ色

dwSpecularRGBA As Long ' スペキュラ色

tu1 As Single ' テクスチャ座標
tv1 As Single
End Type

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZRHW、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX1 の組み合わせになる。Direct3DDevice7.DrawPrimitive などのレンダリング メソッドは、頂点配列の第 1 要素を型 Any として受け取り、すべての種類の頂点フォーマットを格納する。

詳細については、「頂点フォーマットについて」を参照すること。


ストライド頂点フォーマット

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、ストライド頂点はサポートしていない。

[C++]

ストライド頂点フォーマットには、IDirect3DDevice7::DrawPrimitiveStrided、IDirect3DDevice7::DrawIndexedPrimitiveStrided、および IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドで使用する、未トランスフォームの頂点、「未トランスフォーム ライティング済みの頂点」、または「未トランスフォーム 未ライティングの頂点」を表すフィールドが含まれる。ストライド頂点フォーマットは、トランスフォームされた頂点には使用できない。"通常" の頂点は、必要な頂点成分を物理的にすべて含む構造体である。これとは異なり、"ストライド" 頂点は、頂点成分へのポインタを含む構造体で、頂点成分自体を含むわけではない。

この間接的なアクセスは、DrawPrimitiveStrided、DrawIndexedPrimitiveStrided、および ProcessVerticesStrided メソッドが受け取る D3DDRAWPRIMITIVESTRIDEDDATA 構造体によって行われる。ストライド頂点は、非ストライド頂点と同様に柔軟な頂点フォーマット フラグを組み合わせて記述する。しかし、非ストライド頂点とは異なり、これら使用するフラグは、指定のフィールドがメモリ内に存在することを示すのではなく (D3DDRAWPRIMITIVESTRIDEDDATA にはこれらのフラグがすべて含まれる)、どの構造体メンバをアプリケーションで使用するかを示す。これらのフラグに対する制約は、非ストライド頂点の場合と同じである。詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。

D3DDRAWPRIMITIVESTRIDEDDATA 構造体には 12 個の D3DDP_PTRSTRIDE 構造体が含まれ、それぞれの構造体は頂点の位置座標、法線、ディフューズ色、スペキュラ色、およびテクスチャ座標セットを表す。各 D3DDP_PTRSTRIDE 構造体には、データ配列へのポインタと、その配列のストライドが含まれる。これら 12 個の構造体による間接的なアクセスにより、アプリケーションは頂点成分をどのようにでも配置できる。たとえば、次の図に示すように、頂点成分ごとに異なる配列を使用できる。

対応する D3DDP_PTRSTRIDE 構造体の lpvData メンバは、頂点成分の配列があるバッファのアドレスを含む。各配列の各要素は 1 つの頂点に対する 1 つのコンポーネントを表し、このコンポーネントはいくつかの浮動小数点値 (位置座標、法線、およびテクスチャ座標) または 1 つの RGBA 値 (ディフューズ色とスペキュラ色) から成る。各配列には、レンダリングする頂点 1 つにつき 1 つのエントリがある。D3DDP_PTRSTRIDE 構造体の dwStride メンバには、配列内のエントリ間のメモリ ストライドをバイト数で設定しなければならない。次の表は、コンポーネントとそれに対応するストライドを示す。

コンポーネント | ストライド
未トランスフォームの位置座標 | 3 ～ 6 つの浮動小数点値 (x,y,z, と 0 ～ 3 つのブレンド ウェイト)
頂点法線 | 3 つの浮動小数点値 (nx,ny,nz)
ディフューズ色 | 1 つの DWORD (RGBA)
スペキュラ色 | 1 つの DWORD (RGBA)
テクスチャ座標 | 1、2、3、または 4 つの浮動小数点値 (第 1、第 2、第 3、または第 4 テクスチャ座標)

注 : DirectX 7.0 では、テクスチャ座標は複数のフォーマットで宣言でき、最少 1 つの座標、最大 3 つのテクスチャ座標 (2D 射影テクスチャ座標の場合) を使用してテクスチャを処理できる。詳細については、「テクスチャ座標フォーマット」を参照すること。マクロの D3DFVF_TEXCOORDSIZEn セットを使用して、頂点フォーマットで使用するテクスチャ座標フォーマットを識別するためのビット パターンを作成する。

場合によっては、インタリーブ配列に頂点成分の一部またはすべてを含めることもある。ストライド頂点フォーマットでは、これを簡単に行うことができる。たとえば、アプリケーションで頂点位置座標と法線コンポーネントをインタリーブした場合、メモリ レイアウトと D3DDP_PTRSTRIDE 構造体の対応する設定は、次のように表すことができる。

この場合、D3DDP_PTRSTRIDE 構造体の lpvData メンバは同一バッファ内の 2 つの位置座標をポイントし、ストライドはインタリーブされたコンポーネントの幅を結合した値に設定される。もちろん、これは特定のインタリーブ スキームに限定されるものではない。データ ポインタとそのストライドを正しく設定していれば、どのようなインタリーブ スキームでも可能である。


テクスチャ

テクスチャは、コンピュータでリアルな 3D 画像を生成するための強力なツールである。Direct3D では、多彩なテクスチャ機能をサポートしており、高度なテクスチャ技術を簡単に利用できる。このセクションでは、Direct3D でのテクスチャの用途とその使用方法について説明する。説明するトピックは次のとおりである。

  • 基本的なテクスチャ処理の概念
  • テクスチャ座標
  • テクスチャ サーフェス オブジェクト
  • テクスチャ フィルタリング
  • テクスチャ ラッピング
  • テクスチャ ブレンディング
  • テクスチャ圧縮
  • 自動テクスチャ管理
  • テクスチャ処理におけるハードウェア制約

テクスチャについての知識があり、その使用方法についても理解している場合は、「基本的なテクスチャ処理の概念」は省略してもよい。ただし、Direct3D では現在のところ、テクスチャ インターフェイスを使用して、多くのパワフルなテクスチャ機能を利用するという点を覚えておくこと。したがって、「テクスチャ サーフェス オブジェクト」に目を通しておくとよい。


基本的なテクスチャ処理の概念

このセクションでは、Direct3D でのテクスチャ処理の理解に必要な最も基本的な概念について説明する。説明するトピックは次のとおりである。

  • テクスチャとは
  • テクスチャ アドレッシング モード
  • テクスチャ インターフェイスとテクスチャ ハンドル
  • パレット化テクスチャ


テクスチャとは

これまではコンピュータで生成する 3D 画像は、当時としては一般に高度なものではあったが、プラスチックが光っているように見える傾向があった。当時の 3D 画像には、傷、ひび、指紋、汚れなどを 3D オブジェクトでリアルに表現する方法がなかった。近年、開発者の間では、コンピュータでよりリアルな 3D 画像を生成するためのツールとして、テクスチャが広く使用されるようになっている。

基本的には、テクスチャとは単にピクセル カラーのビットマップである。この意味では、テクスチャという用語は、コンピュータ グラフィックス分野においては特定の定義を持つ。テクスチャという言葉から連想する意味は、普通、オブジェクトの色の模様とオブジェクトの粗さや滑らかさの両方をいう。Direct3D のテクスチャでは、オブジェクトに "凹凸" は追加しない。テクスチャ、つまり色のパターンによって、オブジェクトに凹凸があるように見せるだけである。

Direct3D のテクスチャは単なるビットマップであるため、ビットマップでさえあれば Direc3D プリミティブに適用できる。たとえば、アプリケーションでは、木目模様に見えるオブジェクトを作成して操作することができる。丘を形成する 3D プリミティブ セットに、芝生、土、岩を適用できる。その結果、本物のような丘の斜面ができあがる。テクスチャ処理では、また、道路脇の標識、崖の岩層などのエフェクトを作成したり、大理石の床を作成することもできる。

さらに、Direct3D は、テクスチャ ブレンディング (透明度あり/なし) やライト マッピングなど、より高度なテクスチャ技法もサポートしている。これらの技法については、「テクスチャ ブレンディング」および「テクスチャによるライト マッピング」を参照すること。

アプリケーションで HAL デバイス、MMX デバイス、または RGB デバイス (「Direct3D デバイスの種類」を参照すること) を作成する場合は、8 ビット、16 ビット、24 ビット、または 32 ビット テクスチャを使用できる。モノクロ (またはランプ) デバイスを使用する従来のアプリケーションでは、8 ビット テクスチャを使用しなければならない。


テクスチャ アドレッシング モード

このセクションでは、Direct3D テクスチャ アドレッシング モードの用途およびその使用方法について説明する。説明するトピックは次のとおりである。

  • テクスチャ アドレッシング モードとは
  • ラップ テクスチャ アドレッシング モードについて
  • ミラー テクスチャ アドレッシング モードについて
  • クランプ テクスチャ アドレッシング モードについて
  • 境界色テクスチャ アドレッシング モードについて
  • テクスチャ アドレッシング モードの設定と取得
  • テクスチャ アドレッシング モードとテクスチャ ラッピング
  • テクスチャ アドレッシングにおけるデバイス制限


テクスチャ インターフェイスとテクスチャ ハンドル

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、テクスチャ ハンドルは使用しない。

[C++]

テクスチャ ハンドルは、現在は一般には使用されていない。テクスチャ ハンドルは、IDirect3D および IDirect3D2 インターフェイスを利用するアプリケーションで使用されていた。

IDirect3D7 インターフェイス (および従来の IDirect3D3 インターフェイス) では、テクスチャ サーフェスへのインターフェイス ポインタによってテクスチャを作成および使用する。IDirectDraw7::CreateSurface メソッドを呼び出してテクスチャ サーフェスを作成すると、テクスチャ サーフェス インターフェイス ポイントを取得できる。Direct3D では、プリミティブに一度に最大 8 つまでテクスチャをブレンディングできる。詳細については、「テクスチャ サーフェス オブジェクト」を参照すること。


パレット化テクスチャ

[C++]

Direct3D デバイスは、アタッチされたパレットを使用するテクスチャ サーフェスからのテクスチャ処理をサポートする。このタイプのテクスチャのことを "パレット化テクスチャ" と呼ぶ。パレット化テクスチャは DirectDrawSurface オブジェクトである。このオブジェクトは、DDSCAPS_TEXTURE 機能によって生成され、DDPF_PALETTEINDEXEDn ピクセル フォーマット (n は 1、2、4、または 8) のいずれかを使用する。この機能は、テクスチャの作成に使用する DDSURFACEDESC2 構造体 (および、この記述に含まれる DDPIXELFORMAT 構造体) に含まれている。すべてのパレット化サーフェスと同様、色ではなく各ピクセルが、アタッチされた DirectDrawPalette オブジェクト内に保持される値のテーブルへのインデックスになる。パレット化サーフェスの作成および使用の詳細については、DirectDraw ドキュメントの「サーフェス」および「パレット」を参照すること。テクスチャ関連デバイス機能をチェックする場合と同様、IDirect3DDevice7::EnumTextureFormats メソッドを呼び出して、サポートされているテクスチャ ピクセル フォーマットを必ず確認すること。

パレット化テクスチャを準備するには

  1. ここで説明したように、DirectDraw と Direct3D の機能をチェックする。
  2. DDSCAPS_TEXTURE 機能を含み、DDPF_PALETTEINDEXEDn ピクセル フォーマットのいずれかを使用するサーフェスを必要な大きさで作成する。
  3. DirectDrawPalette オブジェクトを作成し、初期化する。詳細については、DirectDraw ドキュメントの「パレット」を参照すること (アルファ専用パレット化テクスチャを使用するには、パレットを作成するときに DDPCAPS_ALPHA 機能を含める。詳細については、IDirectDraw7::CreatePalette のリファレンスを参照すること)。
  4. テクスチャ サーフェスに対して IDirectDrawSurface7::SetPalette メソッドを呼び出して、パレットをサーフェスにアタッチする。

注 : パレット化テクスチャ サーフェスを作成したが、パレットをアタッチしなかった場合、レンダリング中に Direct3D 直接モード内でアプリケーションのアクセス違反が発生する。

パレット化テクスチャで使用するパレットは、色データのみ使用する必要はない。場合によっては、デバイスが、アルファ情報を含むテクスチャ パレットをサポートしていることもある。その場合、IDirectDraw7::GetCaps メソッドを呼び出すと、DirectDraw は DDPCAPS_ALPHA パレット能力フラグを公開する。このフラグは、関連する DDCAPS 構造体の dwPalCaps メンバにある。レンダリング デバイスでアルファ対応パレット化テクスチャからのテクスチャ処理を実行できる場合、IDirect3DDevice7::GetCaps を呼び出すと、このレンダリング デバイスは D3DPTEXTURECAPS_ALPHAPALETTE 機能を公開する (D3DPTEXTURECAPS_ALPHAPALETTE フラグは、この呼び出しで渡す D3DDEVICEDESC7 構造体に含まれる 2 つの D3DPRIMCAPS 構造体にある)。

[Visual Basic]

Direct3D デバイスは、アタッチされたパレットを使用するテクスチャ サーフェスからのテクスチャ処理をサポートする。このタイプのテクスチャのことを "パレット化テクスチャ" と呼ぶ。パレット化テクスチャは DirectDrawSurface オブジェクトである。このオブジェクトは、DDSCAPS_TEXTURE 機能によって生成され、DDPF_PALETTEINDEXEDn ピクセル フォーマット (n は 1、2、4、または 8) のいずれかを使用する。この機能は、テクスチャの作成に使用する DDSURFACEDESC2 型 (および、この記述に含まれる DDPIXELFORMAT 型) に含まれている。すべてのパレット化サーフェスと同様、色ではなく各ピクセルが、アタッチされた DirectDrawPalette オブジェクト内に保持される値のテーブルへのインデックスになる。パレット化サーフェスの作成および使用の詳細については、DirectDraw ドキュメントの「サーフェス」および「パレット」を参照すること。テクスチャ関連デバイス機能をチェックする場合と同様、Direct3DDevice7.GetTextureFormatsEnum メソッドによって取得した Direct3DEnumPixelFormats クラスを使用して、サポートされているテクスチャ ピクセル フォーマットを必ず確認すること。

パレット化テクスチャを準備するには

  1. ここで説明したように、DirectDraw と Direct3D の機能をチェックする。
  2. DDSCAPS_TEXTURE 機能を含み、DDPF_PALETTEINDEXEDn ピクセル フォーマットのいずれかを使用するサーフェスを必要な大きさで作成する。
  3. DirectDrawPalette オブジェクトを作成し、初期化する。詳細については、DirectDraw ドキュメントの「パレット」を参照すること (アルファ専用パレット化テクスチャを使用するには、パレットを作成するときに DDPCAPS_ALPHA 機能を含める。詳細については、DirectDraw7.CreatePalette のリファレンスを参照すること)。
  4. テクスチャ サーフェスに対して DirectDrawSurface7.SetPalette メソッドを呼び出して、パレットをサーフェスにアタッチする。

注 : パレット化テクスチャ サーフェスを作成したが、パレットをアタッチしなかった場合、レンダリング中に Direct3D 直接モード内でアプリケーションのアクセス違反が発生する。

パレット化テクスチャで使用するパレットは、色データのみ使用する必要はない。場合によっては、デバイスが、アルファ情報を含むテクスチャ パレットをサポートしていることもある。その場合、DirectDraw7,GetCaps メソッドを呼び出すと、DirectDraw は DDPCAPS_ALPHA パレット能力フラグを公開する。このフラグは、関連する DDCAPS 型の ｌPalCaps メンバにある。レンダリング デバイスでアルファ対応パレット化テクスチャからのテクスチャ処理を実行できる場合、Direct3DDevice7.GetCaps を呼び出すと、このレンダリング デバイスは D3DPTEXTURECAPS_ALPHAPALETTE 機能を公開する (D3DPTEXTURECAPS_ALPHAPALETTE フラグは、この呼び出しで渡す D3DDEVICEDESC7 型に含まれる 2 つの D3DPRIMCAPS 型にある)。


テクスチャ座標

以下のトピックでは、テクスチャ座標の概念、テクスチャ座標フォーマット、およびテクスチャ座標フォーマットを操作する Direct3D サービスについて説明する。

  • テクスチャ座標について
  • テクセルとピクセル間の直接マッピング
  • テクスチャ座標フォーマット
  • テクスチャ座標処理


テクスチャ座標について

ほとんどのテクスチャは、ビットマップと同様、カラー値の 2 次元配列である (キューブ環境マップ テクスチャは除く。詳細については、「キューブ環境マップ」を参照すること)。個々のカラー値は、テクスチャ要素またはテクセルと呼ばれる。各テクセルは、テクスチャ内の一意のアドレスを持つ。このアドレスは、それぞれ u と v で表される行と列の番号であると考えることができる。

テクスチャ座標はテクスチャ空間にある。つまり、テクスチャ座標は、テクスチャ内の (0,0) を基準にした相対位置座標に存在する。テクスチャを 3D 空間のプリミティブに適用するとき、そのテクセル アドレスをオブジェクト座標にマッピングしなければならない。その後、このアドレスをスクリーン座標、つまりピクセル位置座標に平行移動する必要がある。

Direct3D は、テクスチャ空間のテクセルをスクリーン空間のピクセルに直接マッピングする。これにより、中間の手順が省略されるので効率が上がる。このマッピング処理は、実際は逆マッピングである。つまり、スクリーン空間の各ピクセルについて、テクスチャ空間の対応するテクセル位置座標が計算される。この点またはこの周囲でテクスチャ色がサンプリングされる。このサンプリング処理は、テクスチャ フィルタリングと呼ばれる。詳細については、「テクスチャ フィルタリング」を参照すること。

テクスチャの各テクセルは、テクセル座標で指定できる。しかし、テクセルをプリミティブにマッピングするためには、Direct3D は、すべてのテクスチャのすべてのテクセルに対して同一のアドレス範囲を必要とする。したがって、すべてのテクセル アドレスが 0.0 ～ 1.0 の範囲にある包括的アドレス指定スキームが使用される。2D デカルト座標が x、y 座標で指定されるのと同様、Direct3D では u と v の値でテクスチャ座標を指定する (実際には、0.0 ～ 1.0 の範囲外のテクスチャ座標を処理することも可能で、テクスチャ アドレッシングで設定するパラメータを使用してこの処理を行う。詳細については、「テクスチャ アドレッシング モード」を参照すること)。

この結果、同一のテクスチャ アドレスを異なるテクスチャの異なるテクセルにマッピングできる。次の図では、テクスチャ アドレス (0.5,1.0) を使用している。しかし、これらのテクスチャはサイズが異なるため、テクスチャ アドレスは異なるテクセルにマッピングされる。左側のテクスチャ 1 は 5x5 である。テクスチャ アドレス (0.5,1.0) はテクセル (2,4) にマッピングされる。右側のテクスチャ 2 は 7x7 である。テクスチャ アドレス (0.5,1.0) はテクセル (3,6) にマッピングされる。

次の図は、簡単なテクセル マッピング処理を示す (実際、これは非常に単純な例である。詳細については、「テクセルとピクセル間の直接マッピング」を参照すること)。

この例では、図の左側のピクセルを理想化して色付きの正方形で示す。このピクセルの 4 つの角のアドレスは、オブジェクト空間の 3D プリミティブにマッピングされる。ピクセルの形状は、3D 空間のプリミティブの形状と表示角度が原因で歪むことが多い。次に、ピクセルの角に対応する、プリミティブ上のサーフェス領域の角が、テクスチャ空間にマッピングされる。このマッピング処理によってピクセルの形状が再び歪むが、これが一般的である。ピクセルの最終的なカラー値は、ピクセルがマッピングされる領域のテクセルから計算される。テクスチャ フィルタリング メソッドを設定するときに Direct3D がピクセル カラーを得るために使用するメソッドを決める。詳細については、「テクスチャ フィルタリング」を参照すること。

アプリケーションは、テクスチャ座標を直接頂点に割り当てることができる。詳細については、C++ の D3DVERTEX 構造体 (または Visual Basic の D3DVERTEX 型) のリファレンスを参照すること。この機能によって、プリミティブにマッピングするテクスチャの部分を決めることができる。たとえば、次の図のテクスチャとまったく同じサイズの矩形プリミティブを作成する場合を考える。この例では、アプリケーションでテクスチャ全体を壁全体にマッピングする。アプリケーションがプリミティブの頂点に割り当てるテクスチャ座標は、(0.0,0.0)、(1.0,0.0)、(1.0,1.0)、および (0.0,1.0) である。

壁の高さを半分にすると仮定する。このためには、小さな壁に合わせてテクスチャを歪めるか、Direct3D がテクスチャの下半分を使用するようにテクスチャ座標を割り当てることができる。

小さな壁に合わせてテクスチャを歪めたり、スケーリングしたりする場合、使用するテクスチャ フィルタリング メソッドによって画質が変わる。詳細については、「テクスチャ フィルタリング」を参照すること。

Direct3D で小さな壁に対してテクスチャの下半分を使用するようにテクスチャ座標を割り当てる場合、アプリケーションがこのプリミティブの頂点に割り当てるテクスチャ座標は、(0.0,0.0)、(1.0,0.0)、(1.0,0.5)、および (0.0,0.5) になる。Direct3D は、テクスチャの下半分を壁に適用する。

頂点のテクスチャ座標が 1.0 を超えていてもかまわない。0.0 ～ 1.0 の範囲外のテクスチャ座標を頂点に割り当てるときは、テクスチャ アドレッシング モードも設定しなければならない。詳細については、「テクスチャ アドレッシング モード」を参照すること。


テクセルとピクセル間の直接マッピング

スクリーン上のピクセルにテクセルを直接マッピングするなど、アプリケーションでは通常、シーン内のジオメトリにテクスチャを適用する必要がある。たとえば、テクスチャ内のテキストをシーン内のオブジェクトに表示する必要があるアプリケーションを考える。テクスチャ内のテキスト情報をはっきりと表示するには、テクスチャを施すジオメトリが、テクスチャ フィルタリングによって崩れていないテクセルを確実に受け取るための何らかの方法が必要である。これが行われないと、ぼんやりした画像になったり、ポイントサンプルテクスチャ フィルタリングの場合にはエッジが粗くなる可能性がある。

Direct3D では、画像とテクスチャのフィルタリングをサポートする一方で、ピクセルとテクスチャのサンプリング ルールは、ピクセルとテクスチャのサンプリングを単一化するように慎重に定義されているため、テクスチャのテクセルを取得してスクリーン上のピクセルに直接マッピングする処理は、重要で通常は困難になることが多い。そのため、頂点に対する浮動小数点テクスチャ座標が、ラスタライザで使用する整数ピクセル座標にどのようにマッピングされるかについて十分に理解しておく必要がある。

Direct3D では、次の計算を実行して、浮動小数点テクスチャ座標をテクセル アドレスにマッピングする。

この公式では、Tx と Ty は水平方向と垂直方向の出力テクセル座標、u と v は頂点に対する水平方向と垂直方向のテクスチャ座標である。Mx と My 要素は、現在のミップマップ レベルでの水平方向と垂直方向のテクセル数を表す (説明の後半では、テクセルとピクセル間の水平方向マッピングについて解説する。垂直方向マッピングは水平方向マッピングと同じである)。

テクスチャ座標の上限と下限の 0.0 と 1.0 をこれらの公式に代入すると、テクスチャ座標 0.0 は反復テクスチャ マップの最初と最後のテクセル間の中間点にマッピングされる。テクスチャ座標 1.0 は、現在の反復テクスチャ マップの最後のテクセルと次の反復テクスチャ マップ間の中間点にマッピングされる。テクセル幅が 4 の反復テクスチャで、ミップマップ レベルが 0 の場合、座標 0.0 と 1.0 は、次の図に示すようにマッピングされる。

マッピングについて理解しておくと、単純なバイアスをスクリーン空間のジオメトリ座標に適用して、各テクセルを対応するピクセルに強制的にマッピングすることができる。たとえば、4 つの辺があるポリゴン (つまり "四角形") で、前のテクスチャの各テクセルをスクリーン上の 1 つだけのピクセルにマッピングする場合、ジオメトリ座標でピクセルを強制的にオーバーラップして、各テクセルの中心を各ピクセルの中心に効果的に配置する必要がある。この結果、アプリケーションで多くの場合必要な 1 対 1 マッピングになる。

テクセル幅が 4 のテクスチャをピクセル座標 0 ～ 3 にマッピングするには、それぞれスクリーン空間座標 –0.5 ～ 3.5 とテクスチャ座標 0.0 ～1.0 を持つ、4 辺から成るポリゴンを (2 つの三角形を基に) 描画する。たとえば、スクリーン座標 0.0 にあるピクセルを例として考える。0.0 は最初の頂点 (-0.5) から 0.5 ピクセルだけ離れた位置座標にあり、合計幅が 4.0 であることから、反復テクスチャの座標は 0.125 になる (公式を思い出すこと)。これをテクスチャ サイズ 4 を基にスケーリングすると 0.5 になる。バイアスを 0.5 だけ減じるとテクスチャ アドレスが 0.0 になる。これは、マップ内の最初のテクセルに完全に対応する。

要約すると、テクスチャ座標はテクスチャ マップを両側で均等にオーバーラップする。テクスチャのサイズが 4 の場合、次のようなマッピングになる。

ピクセル座標は、テクセルの場合と同様に正規化される。したがって、頂点がレンダリング先のピクセルをオーバーラップし、その頂点でテクスチャ座標 0.0 と 1.0 を使用する場合、2 つが一列に並ぶ。両方のサイズがほぼ同じで適切に整列していれば、次の図に示すように、これらはテクセルとピクセル間で正確に対応する。


テクスチャ座標フォーマット

Direct3D のテクスチャ座標には、1、2、3、または 4 つの浮動小数点要素を含めて、さまざまな大きさのテクスチャを処理できる。1D テクスチャ (大きさが 1 x n のテクスチャ サーフェス) の場合、1 つのテクスチャ座標で処理される。最も一般的な 2D テクスチャの場合は、通常 u と v と呼ばれる 2 つのテクスチャ座標によって処理される。Direct3D では、キューブ環境マップという 3D テクスチャを 1 種類のみサポートしている。キューブ環境マップは、実際には 3D ではないが、3 要素ベクトルによって処理される。詳細については、「キューブ環境マップ」を参照すること。

[C++]

「頂点フォーマットについて」で説明するように、アプリケーションでは頂点フォーマット内のテクスチャ座標を符号化する。頂点フォーマットにはテクスチャ座標の複数のセットを含めることができる。D3DFVF_TEX0 ～ D3DFVF_TEX8 柔軟な頂点フォーマット フラグを使用して、テクスチャ座標を含めないか、最大 8 つのセットまで含めることを指定する。

各テクスチャ座標セットには、1 ～4 つの要素を含めることができる。D3DFVF_TEXTUREFORMAT1 ～ D3DFVF_TEXTUREFORMAT4 フラグは、特定のテクスチャ座標セット内にある要素の個数を記述するが、これらのフラグは単独では使用しない。その代わり、これらのフラグは、頂点フォーマットの特定のテクスチャ座標セットで使用される要素の個数を記述するビット パターンの作成のために、マクロの D3DFVF_TEXCOORDSIZEn セットで使用する。これらのマクロは、要素数を定義する座標セットのインデックスを識別するパラメータを 1 つ受け取る。次の図は、これらのマクロの使用方法を示す。

// この頂点フォーマットには、2 つのテクスチャ座標セットが含まれている。1 つ目のセット (インデックス 0) には 2 つの要素があり、
// 2 つ目のセットには要素が 1 つある。
//
// この頂点フォーマットは次のように記述される。
// dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL |
// D3DFVF_DIFFUSE | D3DFVF_TEX2 |
// D3DFVF_TEXCOORDSIZE2(0) | D3DFVF_TEXCOORDSIZE1(1);
//
typedef struct CVF {
D3DVECTOR position;
D3DVECTOR normal;
D3DCOLOR  diffuse;
float     u, v;   // 1 つ目のセット、2D
float     t;      // 2 つ目のセット、1D
} CustomVertexFormat;
[Visual Basic]

「頂点フォーマットについて」で説明するように、アプリケーションでは頂点フォーマット内のテクスチャ座標を符号化する。頂点フォーマットにはテクスチャ座標の複数のセットを含めることができる。D3DFVF_TEX0 ～ D3DFVF_TEX8 柔軟な頂点フォーマット フラグを使用して、テクスチャ座標を含めないか、最大 8 つのセットまで含めることを指定する。

各テクスチャ座標セットには、1 ～4 つの要素を含めることができる。この SDK 付属の Math.bas ソース ファイルにあるヘルパー関数 D3DFVF_TEXCOORDSIZEn セットを使用して、頂点フォーマットの特定のテクスチャ座標セットで使用される要素の個数を記述するビット パターンを作成する。これらのマクロは、要素数を定義する座標セットのインデックスを識別するパラメータを 1 つ受け取る。次の図は、これらのマクロの使用方法を示す。

Private Sub Form_Load()
' この頂点フォーマットには、2 つのテクスチャ座標セットが含まれている。
' 1 つ目のセット (インデックス 0) には 2 つの要素があり、2 つ目のセットには要素が 1 つある。
'
' この頂点フォーマットは次のように記述される。
'     lFVF = D3DFVF_XYZ Or D3DFVF_NORMAL Or _
'            D3DFVF_DIFFUSE Or D3DFVF_TEX2 Or _
'            D3DFVF_TEXCOORDSIZE2(0) Or D3DFVF_TEXCOORDSIZE1(1)
'
Type CustomVertexFormat
position As D3DVECTOR
normal As D3DVECTOR
diffuse  As D3DVECTOR
' 1 つ目のセット、2D
u As Single
v As Single
' 2 つ目のセット、1D
t As Single
End Type

注 : キューブ環境マップを除き、ラスタライザでは 3 つ以上の要素を使用してテクスチャを処理することはできない。アプリケーションではテクスチャ座標に最大 3 つまで要素を指定できるが、これが可能なのは、テクスチャがキューブ マップの場合か、D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグが使用されている場合のみである。D3DTTFF_PROJECTED フラグが使用されている場合、ラスタライザは最初の 2 つの要素を 3 つ目 (または n つ目) の要素で除算する。詳細については、「テクスチャ座標トランスフォーム」を参照すること。


テクスチャ座標処理

このセクションでは、Direct3D でサポートするテクスチャ座標処理について説明する。説明するトピックは次のとおりである。

  • テクスチャ座標処理の流れ
  • テクスチャ座標の自動生成
  • テクスチャ座標トランスフォーム
  • テクスチャ座標処理の使用


テクスチャ サーフェス オブジェクト

このセクションでは、以下に示すように、テクスチャ インターフェイス ポインタによる作成およびレンダリングについて説明する。

  • テクスチャ サーフェス オブジェクトの取得
  • テクスチャ サーフェスを使用したレンダリング


テクスチャ サーフェス オブジェクトの取得

[C++]

テクスチャとは単に DirectDraw サーフェス オブジェクトであり、IDirectDrawSurface7 インターフェイスを公開する。テクスチャ インターフェイスへのポインタを取得するために最初にすることは、DDSCAPS_TEXTURE 機能セットを使用して DirectDraw サーフェスを作成することである。「サーフェスの作成」および「DDSCAPS2」を参照すること。

サーフェスを作成すると、アプリケーションはテクスチャ サーフェスの IDirectDrawSurface7 インターフェイスへのポインタを取得する。サーフェス インターフェイスのメソッドを使用して、その他のサーフェスの場合と同様に、そのサーフェスに含まれるデータを操作できる。テクスチャの IDirectDrawSurface7 は、テクスチャの識別子として機能する。つまり、IDirect3DDevice7 インターフェイスのテクスチャ関連メソッドはすべて、このインターフェイスへのポインタを受け取る。

注 : IDirect3DDevice7::Load メソッドを使用して、画像をテクスチャにロードする。このメソッドを呼び出してビデオ メモリにテクスチャをロードする方が、ブリット処理よりも推奨される。

[Visual Basic]

テクスチャとは単に DirectDraw サーフェス オブジェクトであり、DirectDrawSurface7 クラスによって表される。テクスチャを取得するために最初にすることは、DDSCAPS_TEXTURE 機能セットを使用して DirectDraw サーフェスを作成することである。「サーフェスの作成」および「DDSCAPS2」を参照すること。

サーフェスを作成すると、アプリケーションではサーフェス クラス オブジェクトへの参照を取得する。DirectDrawSurface7 のメソッドを使用して、その他のサーフェスの場合と同様に、そのサーフェスに含まれるデータを操作できる。テクスチャは、アプリケーションが保持する DirectDrawSurface7 クラスへの参照によって識別される。Direct3DDevice7 クラスのテクスチャ関連メソッドはすべて、このクラス参照をパラメータとして受け取る。

注 : Direct3DDevice7.Load メソッドを使用して、画像をテクスチャにロードする。このメソッドを呼び出してビデオ メモリにテクスチャをロードする方が、ブリット処理よりも推奨される。


テクスチャ サーフェスを使用したレンダリング

Direct3D では、テクスチャ ステージという概念を用いてマルチ テクスチャ ブレンディングをサポートする。テクスチャ ステージごとに、テクスチャとそのテクスチャで実行可能な処理がある。テクスチャ ステージのテクスチャは、カレント テクスチャの集まりを形成する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。各テクスチャのステートは、そのテクスチャ ステージにカプセル化される。

[C++]

C++ アプリケーションでは、各テクスチャのステートは IDirect3DDevice7::SetTextureStageState メソッドで設定する必要がある。第 1 パラメータの値としてステージ番号 (0 ～ 7) を渡す。第 2 パラメータの値には、D3DTEXTURESTAGESTATETYPE 列挙型のメンバを設定する。最後のパラメータは、特定のテクスチャ ステートについてのステート値である。

テクスチャ インターフェイス ポインタを使用して、最大 8 つのテクスチャのブレンドをレンダリングできる。IDirect3DDevice7::SetTexture メソッドを呼び出してカレント テクスチャを設定する。Direct3D は、レンダリングするプリミティブに対して、カレント テクスチャをすべてブレンドする。

注 : SetTexture メソッドは、割り当てられるテクスチャ サーフェスの参照カウントを増分する。テクスチャが不要になった場合、該当するステージのテクスチャを NULL に設定する必要がある。これを行わなかった場合、サーフェスは解放されず、メモリ リークが発生する。

IDirect3DDevice7::SetRenderState メソッドを呼び出して、カレント テクスチャのテクスチャ ラッピング ステートを設定できる。第 1 パラメータの値として、D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 から値を 1 つ渡す。また、D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 フラグの組み合わせを使用して、u または v 方向のラッピングを有効にする。

また、テクスチャ パースペクティブ ステートとテクスチャ フィルタリング ステートを設定することもできる。「テクスチャ パースペクティブ ステート」、「テクスチャ フィルタリング」、および「テクスチャ フィルタリング ステート」を参照すること。

[Visual Basic]

Visual Basic では、各テクスチャのステートは Direct3DDevice7.SetTextureStageState メソッドで設定する必要がある。第 1 パラメータの値としてステージ番号 (0 ～ 7) を渡す。第 2 パラメータの値には、CONST_D3DTEXTURESTAGESTATETYPE 列挙のメンバのメンバを設定する。最後のパラメータは、特定のテクスチャ ステートについてのステート値である。

アプリケーションでは、最大 8 つのテクスチャのブレンドをレンダリングできる。Direct3DDevice7.SetTexture メソッドを呼び出してカレント テクスチャを設定する。Direct3D は、レンダリングするプリミティブに対して、カレント テクスチャをすべてブレンドする。

注 : テクスチャが不要になった場合、該当するステージのテクスチャを Nothing に設定する必要がある。これを行わなかった場合、アプリケーションを閉じたときにサーフェス用のメモリが失われることがある。

Direct3DDevice7.SetRenderState メソッドを呼び出して、カレント テクスチャのテクスチャ ラッピング ステートを設定できる。第 1 パラメータの値として、D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 の値を 1 つ渡す。また、D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 フラグ (CONST_D3D 列挙から) の組み合わせを使用して、u または v 方向のラッピングを有効にする。

また、テクスチャ パースペクティブ ステートとテクスチャ フィルタリング ステートを設定することもできる。「テクスチャ パースペクティブ ステート」、「テクスチャ フィルタリング」、および「テクスチャ フィルタリング ステート」を参照すること。


テクスチャ フィルタリング

Direct3D はプリミティブをレンダリングするとき、3D プリミティブを 2D スクリーンにマッピングする。プリミティブがテクスチャを持っている場合、Direct3D はそのテクスチャを使用して、プリミティブの 2D レンダリング画像の各ピクセルの色を生成しなければならない。プリミティブのスクリーン上の画像のすべてのピクセルに対して、テクスチャからカラー値を取得しなければならない。この処理をテクスチャ フィルタリングと呼ぶ。

テクスチャ フィルタリング処理を実行するとき、使用するテクスチャは通常拡大または縮小される。つまり、テクスチャは、それ自体よりも大きなまたは小さなプリミティブ画像にマッピングされる。テクスチャの拡大によって、多数のピクセルが 1 つのテクセルにマッピングされることがある。この結果、画像が粗くなることがある。テクスチャの縮小では、多くの場合、単一のピクセルが多数のテクセルにマッピングされる。この結果、画像が不鮮明になったり、ぎざぎざができることがある。これらの問題を解決するには、ピクセルの色になるようにテクセル色のブレンディングを実行する必要がある。

Direct3D では、テクスチャ フィルタリングの複雑な処理を簡素化する。Direct3D では、線形フィルタリング、異方性フィルタリング、およびミップマップ フィルタリングの 3 種類のテクスチャ フィルタリングを使用できる。テクスチャ フィルタリングを選択しない場合、Direct3D では最近点サンプリングという方法を使用する。

それぞれのテクスチャ フィルタリングには、長所と短所がある。たとえば、線形テクスチャ フィルタリングを使用した場合、最終的な画像でエッジがぎざぎざになったり、画質が粗くなることがある。しかし、このフィルタリングはオーバーヘッドが少ない。一方、ミップマップによるフィルタリングを使用すると、通常は最良の結果が得られる。特に、異方性フィルタリングと組み合わせて使用した場合はそうである。しかし、このフィルタリングは、Direct3D がサポートする方法の中で最もメモリを必要とするものである。

[C++]

テクスチャ インターフェイス ポインタを使用するアプリケーションでは、IDirect3DDevice7::SetTextureStageState メソッドを呼び出して現在のテクスチャ フィルタリング方法を設定する必要がある。第 1 パラメータの値には、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) を設定する。第 2 パラメータの値として、D3DTSS_MAGFILTER、D3DTSS_MINFILTER、または D3DTSS_MIPFILTER のいずれかを渡す。第 3 パラメータには、D3DTEXTUREMAGFILTER、D3DTEXTUREMINFILTER、または D3DTEXTUREMIPFILTER 列挙型のメンバを設定する。

[Visual Basic]

Visual Basic アプリケーションでは、Direct3DDevice7.SetTextureStageState メソッドを呼び出して現在のテクスチャ フィルタリング方法を設定する必要がある。第 1 パラメータの値には、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) を設定する。第 2 パラメータの値として、D3DTSS_MAGFILTER、D3DTSS_MINFILTER、または D3DTSS_MIPFILTER のいずれかを渡す。第 3 パラメータには、CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMINFILTER、または CONST_D3DTEXTUREMIPFILTER 列挙型のメンバを設定する。

このセクションでは、Direct3D でサポートするテクスチャ フィルタリング方法について説明する。説明するトピックは次のとおりである。

  • 最近点サンプリング
  • 線形テクスチャ フィルタリング
  • 異方性テクスチャ フィルタリング
  • ミップマップによるテクスチャ フィルタリング
[C++]

注 : D3DRENDERSTATETYPE 列挙型にあるテクスチャ フィルタリング ステートは、テクスチャ ステージ ステートに置き換えられているが、このレンダリング ステートを使用しても IDirect3DDevice7::SetRenderState (IDirect3DDevice2 バージョンとは対照的に) の実行が失敗することはない。その代わり、システムでは、このレンダリング ステートのエフェクトをマルチ テクスチャ カスケードの最初のステージ (ステージ 0) にマッピングする。アプリケーションでは、従来のレンダリング ステートをそれと対応するテクスチャ ステージ ステートと併用しないこと。予期せぬ結果が生じるおそれがある。


最近点サンプリング

アプリケーションでは、テクスチャ フィルタリングを使用する必要はない。Direct3D は、テクセル アドレスを計算 (このアドレスは整数でないことが多い) したり、この値に最も近い整数アドレスを持つテクセルの色を単にコピーするように設定できる。この処理を最近点サンプリングと呼ぶ。テクスチャのサイズがスクリーン上のプリミティブの画像のサイズとほぼ同じ場合には、この方法によってテクスチャは高速で効率的に処理できる。両方のサイズの差が大きい場合は、テクスチャを拡大したり、縮小する必要がある。このような処理を実行した結果、画像が粗くなったり、ぎざぎざができたり、不鮮明になることがある。

[C++]

C++ アプリケーションでは、IDirect3DDevice7::SetTextureStageState メソッドを呼び出して最近点サンプリングを選択できる。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータを D3DTSS_MAGFILTER、D3DTSS_MIMIFILTER、または D3D_MIPFILTER に設定する。D3DTEXTUREMAGFILTER、D3DTEXTUREMINFILTER、または D3DTEXTUREMIPFILTER 列挙型のメンバを次のパラメータの値として渡して、拡大、縮小、またはミップマップ フィルタを設定する。

詳細については、「テクスチャ フィルタリング ステート」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでは、Direct3DDevice7.SetTextureStageState メソッドを呼び出して最近点サンプリングを選択できる。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータを D3DTSS_MAGFILTER、D3DTSS_MIMIFILTER、または D3D_MIPFILTER に設定する。CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMINFILTER、または CONST_D3DTEXTUREMIPFILTER 列挙のメンバを次のパラメータに渡して、拡大、縮小、またはミップマップ フィルタを設定する。

詳細については、「テクスチャ フィルタリング ステート」を参照すること。

最近点サンプリングは注意して使用すること。2 つのテクセル間の境界でテクスチャがサンプリングされる際、場合によっては不自然なグラフィックス効果が生じることがある。この境界とは、サンプリング対象のテクセルが次のテクセルに移るときの、テクスチャに沿った位置座標 (u または v) である。ポイント サンプリングを使用するとき、システムではサンプル テクセルを 1 つ選択するか、別のテクセルを選択する。これにより、境界が交差している際は結果がテクセル間で不意に変化することがある。この影響から、表示されるテクスチャの中に、好ましくない不自然なグラフィックス エフェクトが現れることがある (線形フィルタリングを使用した場合、結果テクセルは隣接テクセル間で計算され、テクスチャ インデックスが境界に沿って移るのに従って滑らかにブレンドされる)。

このようなエフェクトは、非常に小さなテクスチャを非常に大きなポリゴンにマッピングする (多くの場合 "拡大" と呼ぶ) ときに発生する可能性がある。たとえば、チェッカー盤のようなテクスチャでポイント サンプリングを使用すると、チェッカー盤は拡大されてエッジが際立つ。対照的に、線形テクスチャ フィルタリングを使用した場合は、チェッカー盤の色がポリゴン全体にわたって滑らかに変化した画像ができあがる。

ほとんどの場合、最良の結果を得るためには、最近点サンプリングの使用をできるだけ避けるようにする。最近のハードウェアのほとんどは、線形フィルタリング用に最適化されているため、パフォーマンスが低下することはない。ただし、テクスチャを使用して読みやすいテキスト文字を表示する場合など、希望のエフェクトを出すためにどうしても最近点サンプリングを使用しなければならない場合は、テクセル境界でサンプリングを行わないように心がけ、思わぬエフェクトが生じないよう細心の注意を払う必要がある。次の図は、不自然なグラフィックス効果がどのようなものであるかを示す。

グループ内の右上にある 2 つの四角形が隣接する四角形とは異なることに注意する。このような不自然なグラフィックス効果を避けるためには、まず 最近点サンプリングに関する Direct3D テクスチャ サンプリング ルールについて理解する必要がある。Direct3D では、[0.0, 1.0] (0.0 ～ 1.0 まで含む) の範囲内の浮動小数点テクスチャ座標を、[–0.5, n – 0.5] の範囲内の整数テクセル空間値にマッピングする。ここで、n はテクスチャの所定の大きさでのテクセル数である。結果のテクスチャ インデックスは、最も近い整数に丸められる。このマッピングにより、テクスチャ境界ではサンプリングの誤差が生じる場合がある。

簡単な例として、D3DTADDRESS_WRAP テクスチャ アドレッシング モードでポリゴンをレンダリングする場合を考えてみる。Direct3D のマッピングを使用すると、u テクスチャ インデックスは、4 テクセル幅のテクスチャに対して、次のようにマッピングされる。

この図で、テクスチャ座標 0.0 と 1.0 は、テクセル間の境界上に正確に位置する。Direct3D のマッピング用のメソッドを使用すると、テクスチャ座標は [–0.5, 4 – 0.5] の範囲内にマッピングされる。ここで、4 はテクスチャの幅である。この場合、サンプリングされるのは、テクスチャ インデックス 1.0 の 0 番目のテクセルである。ただし、テクスチャ座標が 1.0 よりもわずかに少ない場合には、サンプリングされるのは 0 番目のテクセルではなく、n 番目のテクセルになる。

これは、つまり、テクスチャ座標 0.0 と 1.0 を持つ小さなテクスチャを、スクリーン空間に配列された三角形上で最近点フィルタリングによって拡大すると、その結果、テクスチャ マップがテクセル間の境界でサンプリングされる際の対象となるピクセルになる、という意味である。テクスチャ座標の計算の誤差がわずかな場合であっても、テクスチャ マップのテクセル エッジに対応する、レンダリング画像の領域に沿って不自然な効果が現れる。

このように浮動小数点テクスチャ座標を整数テクセルに完璧に正確にマッピングするのは、困難な作業であり、計算負荷も大きいが、このような処理を一般には行う必要はない。ほとんどのハードウェア実装では、三角形内の各ピクセル位置座標におけるテクスチャ座標の計算に反復処理を用いる。この方法を使用すると、反復処理間で誤差が均等に累積されていくため、これらの誤差がいくらかは目立たなくなる。

Direct3D リファレンス ラスタライザでは、各ピクセル位置座標でのテクスチャ インデックスの計算に直接評価法を用いる。直接評価は反復処理とは異なり、処理上の誤差がよりランダムなエラー分布を示す。この結果、境界上ではより顕著なサンプリング エラーが発生する。これは、リファレンス ラスタライザによってこの処理が正確に実行されないためである (繰り返しになるが、浮動小数点テクスチャ座標の処理は、困難かつ計算負荷が非常に大きい)。

最近点フィルタリングは、必要な場合にのみ使用するとよい。これを使用する必要がある場合は、テクスチャ座標を境界位置座標から少しだけオフセットして不自然な効果の発生を防ぐことが推奨される。


線形テクスチャ フィルタリング

Direct3D では、バイリニア フィルタリングと呼ばれる線形テクスチャ フィルタリングを使用する。最近点サンプリングと同様、バイリニア テクスチャ フィルタリングでは最初にテクセル アドレスを計算するが、通常、この値が整数アドレスになることはない。整数アドレスでない場合は、最近点サンプリングと同様、計算したアドレスに最も近い整数アドレスを持つテクセルが検索される。さらに、Direct3D レンダリング モジュールでは、サンプリングした最近点の上下左右にあるテクセルの加重平均を計算する。

[C++]

IDirect3DDevice7::SetTextureStageState メソッドを呼び出して、バイリニア テクスチャ フィルタリングを選択する。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。拡大フィルタを設定する場合は、第 2 パラメータの値として D3DTEXTUREMAGFILTER を渡す。縮小フィルタを設定する場合は、第 2 パラメータの値として D3DTEXTUREMINFILTER を渡す。ミップマップ フィルタを設定する場合は、第 2 パラメータの値として D3DTEXTUREMIPFILTER を渡す。第 3 パラメータを、拡大フィルタを設定する場合は D3DTFG_LINEAR、縮小フィルタを設定する場合は D3DTFN_LINEAR、ミップマップ フィルタを設定する場合は D3DTFP_LINEAR にそれぞれ設定する。詳細については、「テクスチャ フィルタリング ステート」を参照すること。

[Visual Basic]

Direct3DDevice7.SetTextureStageState メソッドを呼び出して、バイリニア テクスチャ フィルタリングを選択する。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータに、CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMINFILTER、または CONST_D3DTEXTUREMIPFILTER 列挙のメンバを渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータを、拡大フィルタを設定する場合は D3DTFG_LINEAR、縮小フィルタを設定する場合は D3DTFN_LINEAR、ミップマップ フィルタを設定する場合は D3DTFP_LINEAR をそれぞれ設定する。詳細については、「テクスチャ フィルタリング ステート」を参照すること。


異方性テクスチャ フィルタリング

異方性とは、スクリーン平面に対して角度をなして位置座標したサーフェスを持つ 3D オブジェクトのテクセルの可視的なゆがみである。異方性プリミティブからのピクセルをテクセルにマッピングするとき、プリミティブの形状がゆがむ。Direct3D では、テクスチャ空間に逆マッピングされるスクリーン ピクセルの伸長度 (長さ÷幅) としてピクセルの異方性を測定する。

[C++]

異方性テクスチャ フィルタリングは、線形テクスチャ フィルタリングまたはミップマップ テクスチャ フィルタリングと併用することで、レンダリング結果を向上させることができる。IDirect3DDevice7::SetTextureStageState メソッドを呼び出して、異方性テクスチャ フィルタリングを有効にする。第 1 パラメータの値には、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) を設定する。拡大フィルタを設定する場合は、第 2 パラメータの値として D3DTEXTUREMAGFILTER を渡す。縮小フィルタを設定する場合は、第 2 パラメータの値として D3DTEXTUREMINFILTER を渡す。第 3 パラメータには、拡大フィルタを設定する場合は D3DTFG_ANISOTROPIC、縮小フィルタを設定する場合は D3DTFN_ANISOTROPIC をそれぞれ設定する。詳細については、「テクスチャ フィルタリング ステート」を参照すること。

また、異方性の度合いをゼロより大きな値に設定する必要がある。これを設定するには、IDirect3DDevice7::SetTextureStageState メソッドを呼び出す。第 1 パラメータには、異方性の度合いを設定するテクスチャの整数インデックス番号 (0 ～ 7) を設定する。第 2 パラメータには、D3DTSS_MAXANISOTROPY を渡す。最後のパラメータは、異方性の度合いでなければならない。

異方性の度合いを 1 に設定すると、異方性フィルタリングが無効になる (1 より大きな値を設定すると、異方性フィルタリングが有効になる)。異方性の度合いとして設定可能な値の範囲を判別するには、D3DPRIMCAPS 構造体の D3DPRASTERCAPS_ANISOTROPY フラグをチェックする。

[Visual Basic]

異方性テクスチャ フィルタリングは、線形テクスチャ フィルタリングまたはミップマップ テクスチャ フィルタリングと併用することで、レンダリング結果を向上させることができる。Direct3DDevice7.SetTextureStageState メソッドを呼び出して、異方性テクスチャ フィルタリングを有効にする。第 1 パラメータには、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) を設定する。第 2 パラメータには、CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMINFILTER、または CONST_D3DTEXTUREMIPFILTER 列挙のメンバを渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータには、拡大フィルタを設定する場合は D3DTFG_ANISOTROPIC、縮小フィルタを設定する場合は D3DTFN_ANISOTROPIC をそれぞれ設定する。詳細については、「テクスチャ フィルタリング ステート」を参照すること。

また、異方性の度合いをゼロより大きな値に設定する必要がある。これを設定するには、Direct3DDevice7.SetTextureStageState メソッドを呼び出す。第 1 パラメータには、異方性の度合いを設定するテクスチャの整数インデックス番号 (0 ～ 7) を設定する。第 2 パラメータには、D3DTSS_MAXANISOTROPY を渡す。最後のパラメータは、異方性の度合いでなければならない。

異方性の度合いを 1 に設定すると、異方性フィルタリングが無効になる (1 より大きな値を設定すると、異方性フィルタリングが有効になる)。異方性の度合いとして設定可能な値の範囲を調べるには、D3DPRIMCAPS 構造体の D3DPRASTERCAPS_ANISOTROPY フラグをチェックする。


ミップマップによるテクスチャ フィルタリング

ミップマップ テクスチャは、シーンのレンダリングに必要な時間を短縮するために 3D シーンで使用される。また、ミップマップ テクスチャを使用すると、シーンのリアリティが増す。しかし、ミップマップ テクスチャを使用するにはメモリが大量に必要となることが多い。

このセクションでは、以下のトピックに示すように、3D シーンでのミップマップ テクスチャの使用に関する基本事項について説明する。

  • ミップマップとは
  • ミップマップ セットの作成
  • ミップマップの選択と表示


テクスチャ ラッピング

このセクションでは、3D プリミティブへのテクスチャ ラッピングについて説明する。説明するトピックは次のとおりである。

  • テクスチャ ラッピングとは
  • テクスチャ ラッピングの使用

注 : テクスチャ ラッピングをテクスチャ アドレッシング モードと混同しないこと。詳細については、「テクスチャ アドレッシング モードとテクスチャ ラッピング」および「テクスチャ アドレッシング モード」を参照すること。


テクスチャ ラッピングとは

テクスチャ ラッピングとは、簡単に言えば、Direct3D で各頂点に対して指定されたテクスチャ座標を使用して、テクスチャ処理したポリゴンをラスタ化する際の基本的な方法を変更する処理である (テクスチャ ラッピングを "ラップ" テクスチャ アドレッシング モードと混同しないこと。詳細については、「テクスチャ アドレッシング モードとテクスチャ ラッピング」を参照すること)。ポリゴンのラスタ化中に、システムはポリゴンの各頂点のテクスチャ座標の間を補間して、ポリゴンのすべてのピクセルに使用するテクセルを決める。通常、システムはテクスチャを 2D 平面として扱い、テクスチャ内の点 A から 点 B までの最短経路をとることで新しいテクセルを補間する。点 A が u, v 位置座標 (0.8, 0,1) で、点 B が (0.1,.9) の場合、補間の線は次のようになる。

上の図では、AB 間の最短距離がテクスチャの中央を通っている。u または v のテクスチャ座標のラッピングを有効にすると、u および v 方向でのテクスチャ座標間の最短経路を Direct3D が認識する方法が変化する。定義では、0.0 と 1.0 が同じ位置座標を占めると仮定して、テクスチャ ラッピングによってラスタライザがテクスチャ座標間の最短経路をとる。最後のビットは扱いにくいが、次のように考えるとわかりやすい。一方向のテクスチャ ラッピングを有効にすると、システムはテクスチャがあたかも円柱の周囲に「巻き付いて」いるかのようにテクスチャを扱う。例えば、次の図を考える。

上の図は、u 方向のラッピングによって、システムによるテクスチャ座標の補間方法がどのように変化するかを示す。この例で使用した同じ点を「正常な」または巻き付けていないテクスチャに使用すると、点 A と B の最短距離がテクスチャの中心を通っていないことがわかる。今度は、最短距離は、0.0 と 1.0 が共に位置座標する境界を通っている。V 方向のラッピングも同様である。側面が下になっている円柱の周囲にテクスチャを「巻き付け」ているだけである。u および v の両方向のラッピングの場合は少し複雑である。この場合は、トーラスやドーナツを想像するとよい。

テクスチャ ラッピングを実際に使用した最も一般的なアプリケーションは、環境マッピングの実行である。通常、環境マッピングでテクスチャ処理したオブジェクトは非常に反射的であり、シーンのオブジェクトの周囲に画像が反映する。これを説明するため、四方が壁で囲まれた部屋を考える。壁にはそれぞれ R、G、B、および Y という文字が付けてあり、それに対応する赤色、緑色、青色、および黄色で塗られている。このような単純な部屋の環境マッピングであれば、次のようになる。

この部屋の天井が、4 面からなる非常に反射しやすい柱で支えられているとする。この柱に環境マッピングを実行するのは非常に簡単である。しかし、壁の文字と色をそのまま柱が反射しているように見せるのは簡単なことではない。次の図は、上方の頂点の近くのテクスチャ座標を適用した、柱のワイヤ フレームを示す (ラッピングがこのテクスチャのエッジを横切る「継ぎ目」は、点線で示す)。

u 方向でラッピングが有効になっているので、テクスチャ処理した柱には、環境マッピングからの色とシンボルが正しく表示されており、テクスチャの前面の「継ぎ目」では、ラスタライザがテクスチャ座標間の最短経路を正しく選択している (u 座標 0.0 と 1.0 が同じ位置座標を占めるという前提で)。次に、テクスチャ処理した柱を示す。

テクスチャ ラッピングが有効でない場合、ラスタライザにより、本物そっくりに反射した画像を生成するのに必要な方向において補間が実行されない。逆に、柱の前面部分では、u 座標の 0.175 および 0.875 間のテクセルが、テクスチャの中心を通るときに水平方向で圧縮され、エフェクトが壊れる。


テクスチャ ラッピングの使用

[C++]

C++ アプリケーションの場合、テクスチャ ラッピングを有効にする処理は、Direct3D デバイス インターフェイスのバージョンによって異なる。アプリケーションで IDirect3DDevice7 インターフェイスを使用する場合は、頂点で使用されるテクスチャ座標セットに対してテクスチャ ラッピングを有効にし、テクスチャ ステージ ステート自体に対して有効にするわけではない。この場合、IDirect3DDevic7::SetRenderState メソッドを呼び出し、第 1 パラメータとして D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 の列挙値のいずれかを渡して、ラッピングの適用先テクスチャ座標セットを指定する。第 2 パラメータに D3DWRAPCOORD_0 ～ D3DWRAPCOORD_3 フラグを指定して、対応する方向のテクスチャ ラッピングを有効にするか、これらのフラグを組み合わせて複数の方向のラッピングを有効にする。フラグを省略すると、対応する方向でのテクスチャ ラッピングが無効になる。テクスチャ座標の特定のセットに対してテクスチャ ラッピングを無効にするには、対応するレンダリング ステートの値を 0 に設定する。

アプリケーションで従来の IDirect3DDevice2 インターフェイスを使用する場合でも、SetRenderState メソッドを呼び出してテクスチャ ラッピングを有効にできる。しかし、このインターフェイスでは、D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 はサポートされていない。これらの代わりとして、D3DRENDERSTATE_WRAPU または D3DRENDERSTATE_WRAPV 値を第 1 パラメータに使用する。第 2 パラメータで TRUE を指定するとラッピングが有効になり、FALSE を指定するとラッピングが無効になる。

注 : IDirect3DDevice7 インターフェイスは、D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 に置き換えられた従来の D3DRENDERSTATE_WRAPU および D3DRENDERSTATE_WRAPV レンダリング ステートも認識する。これらの旧レンダリング ステートを SetRenderState の IDirect3DDevice7 バージョンに渡すと、テクスチャ座標の最初のセットの u および v テクスチャ ラッピングに影響する。

[Visual Basic]

Visual Basic の場合、頂点で使用されるテクスチャ座標セットに対して、テクスチャ ラッピングを有効にする。Direct3DDevice7.SetRenderState メソッドを呼び出してテクスチャ ラッピングを有効にし、第 1 パラメータとして D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 列挙値のいずれかを渡して、ラッピングの適用先テクスチャ座標セットを指定する。第 2 パラメータには D3DWRAPCOORD_0 ～ D3DWRAPCOORD_3 フラグ (CONST_D3D 列挙から) を使用して、対応する方向のテクスチャ ラッピングを有効にするか、これらのフラグを組み合わせて複数の方向のラッピングを有効にする。フラグを省略すると、対応する方向でのテクスチャ ラッピングが無効になる。テクスチャ座標の特定のセットに対してテクスチャ ラッピングを無効にするには、対応するレンダリング ステートの値を 0 に設定する。


テクスチャ ブレンディング

Direct3D では、テクスチャをプリミティブの色とブレンドして半透明エフェクトを生成できる。また、複数のテクスチャを 1 つのプリミティブにブレンドすることもできる。このセクションでは、テクスチャ ブレンディングの実行方法について説明する。説明するトピックは次のとおりである。

  • アルファ テクスチャ ブレンディング
  • マルチパス テクスチャ ブレンディング
  • マルチ テクスチャ ブレンディング
  • テクスチャによるライト マッピング
[C++]

C++ アプリケーションでテクスチャ ブレンディングを使用する場合は、まず、ユーザーのハードウェアでテクスチャ ブレンディングがサポートされているかどうかをプログラムで調べる必要がある。これらのサポート情報については、D3DPRIMCAPS 構造体の dwTextureCaps メンバを調べる。テクスチャ ブレンディング機能についてユーザーのハードウェアに問い合わせる方法の詳細については、「IDirect3DDevice7::GetCaps」および「D3DDEVICEDESC7」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでテクスチャ ブレンディングを使用する場合は、まず、ユーザーのハードウェアでテクスチャ ブレンディングがサポートされているかどうかをプログラムで調べる必要がある。これらのサポート情報については、D3DPRIMCAPS 型の lTextureCaps メンバを調べる。テクスチャ ブレンディング機能についてユーザーのハードウェアに問い合わせる方法の詳細については、「Direct3DDevice7.GetCaps」および「D3DDEVICEDESC7」を参照すること。


アルファ テクスチャ ブレンディング

Direct3D では、プリミティブをレンダリングするとき、プリミティブのマテリアルおよびライティング情報に基づいてプリミティブの色を生成する。詳細については、「ライティングとマテリアル」を参照すること。アプリケーションでテクスチャ ブレンディングが有効になっている場合、Direct3D は 1 つまたは複数のテクスチャのテクセル色をプリミティブのカレント色とブレンドする。Direct3D では、次の公式を使用して、プリミティブの画像の各ピクセルに対する最終色を決める。

この公式で、FinalColor は、ターゲット レンダリング サーフェスに出力されるピクセル カラーである。TexelColor は、カレント ピクセルに対応するテクセルの色を表す。Direct3D でピクセルをテクセルにマッピングする方法の詳細については、「テクスチャ フィルタリング」を参照すること。SourceBlendFactor は、最終色に適用するテクセル色の割合を決めるために Direct3D が使用する計算値である。PixelColor は、プリミティブの画像内のカレント ピクセルの色である。DestBlendFactor は、最終色で使用されるカレント ピクセルの色の割合を表す。SourceBlendFactor と DestBlendFactor の値の範囲は、0.0 と 1.0 を含む 0.0 ～ 1.0 である。

上の公式から分かるように、SourceBlendFactor が 1.0 で DestBlendFactor が 0.0 の場合、テクスチャはまったく透明度がないものとしてレンダリングされる。SourceBlendFactor が 0.0 で DestBlendFactor が 1.0 の場合は、テクスチャは完全に透明になる。これらの係数に上記以外の値を設定した場合は、テクスチャはある程度の透明をもって色とブレンドされる。

テクスチャのすべてのテクセルは、赤色、緑色、および青色のカラー値を持っている。デフォルトでは、Direct3D はテクセルのアルファ値を SourceBlendFactor として使用する。したがって、アプリケーションでは、テクスチャのアルファ値を設定することでテクスチャの透明度を制御できる。

[C++]

C++ で開発するアプリケーションでは、D3DRENDERSTATE_SRCBLEND および D3DRENDERSTATE_DESTBLEND レンダリング ステートを使用してブレンディング係数を制御する。IDirect3DDevice7::SetRenderState メソッドを呼び出し、第 1 パラメータの値として D3DRENDERSTATE_SRCBLEND または D3DRENDERSTATE_DESTBLEND のいずれかを渡す。第 2 パラメータは、D3DBLEND 列挙型のメンバでなければならない。

[Visual Basic]

Visual Basic アプリケーションでは、D3DRENDERSTATE_SRCBLEND および D3DRENDERSTATE_DESTBLEND レンダリング ステートを使用してブレンディング係数を制御できる。Direct3DDevice7.SetRenderState メソッドを呼び出して、第 1 パラメータにレンダリング ステートのいずれかを渡す。第 2 パラメータは、CONST_D3DBLEND 列挙のメンバでなければならない。


マルチパス テクスチャ ブレンディング

Direct3D アプリケーションでは、マルチ レンダリング パスで各種テクスチャをプリミティブに適用して、数多くの特殊効果を実現できる。この処理は一般にマルチパス テクスチャ ブレンディングと呼ばれる。マルチパス テクスチャ ブレンディングの一般的な用途は、いくつかの異なるテクスチャから複数の色を適用して、複雑なライティングおよびシェーディング モデルのエフェクトをエミュレートすることである。これをライト マッピングと呼ぶ。詳細については、「テクスチャによるライト マッピング」を参照すること。

注 : デバイスによっては、単一のパスで、複数のテクスチャをプリミティブに適用できる場合もある。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

ユーザーのハードウェアでマルチ テクスチャ ブレンディングがサポートされていない場合でも、アプリケーションでは、マルチパス テクスチャ ブレンディングを使用して同じ視覚エフェクトを実現できる。ただし、マルチ テクスチャ ブレンディングを使用した場合には可能なフレーム レートを維持することはできない。

[C++]

C++ アプリケーションでマルチ テクスチャ ブレンディングを実行するには

  1. IDirect3DDevice7::SetTexture メソッドを呼び出して、テクスチャ ステージ 0 にテクスチャを設定する。
  2. IDirect3DDevice7::SetTextureStageState メソッドを使用して、希望の色およびアルファ ブレンディング引数と処理を選択する (マルチパス テクスチャ ブレンディング用の最適な設定はデフォルト設定である)。
  3. シーン内の適切なオブジェクトをレンダリングする。
  4. 次のテクスチャをテクスチャ ステージ 0 に設定する。
  5. D3DRENDERSTATE_SRCBLEND および D3DRENDERSTATE_DESTBLEND レンダリング ステートを設定して、ブレンド元およびブレンド先のブレンディング係数を必要に応じて調整する。これらのパラメータに基づいて、新しいテクスチャがレンダリング ターゲット サーフェス内の既存のピクセルでブレンドされる。
  6. 必要に応じて、ほかのテクスチャに対して手順 3、4、および 5 を繰り返す。
[Visual Basic]

Visual Basic アプリケーションでマルチ テクスチャ ブレンディングを実行するには

  1. Direct3DDevice7.SetTexture メソッドを呼び出して、テクスチャ ステージ 0 にテクスチャを設定する。
  2. Direct3DDevice7.SetTextureStageState メソッドを使用して、希望の色およびアルファ ブレンディング引数と処理を選択する (マルチパス テクスチャ ブレンディング用の最適な設定はデフォルト設定である)。
  3. シーン内の適切なオブジェクトをレンダリングする。
  4. 次のテクスチャをテクスチャ ステージ 0 に設定する。
  5. D3DRENDERSTATE_SRCBLEND および D3DRENDERSTATE_DESTBLEND レンダリング ステートを設定して、ブレンド元およびブレンド先のブレンディング係数を必要に応じて調整する。これらのパラメータに基づいて、新しいテクスチャがレンダリング ターゲット サーフェス内の既存のピクセルでブレンドされる。
  6. 必要に応じて、ほかのテクスチャに対して手順 3、4、および 5 を繰り返す。


マルチ テクスチャ ブレンディング

Direct3D では、単一のパスで、最大 8 つのテクスチャをプリミティブにブレンドできる。マルチ テクスチャ ブレンディングを使用すれば、Direct3D アプリケーションのフレーム レートを大幅に上げることができる。アプリケーションは、マルチ テクスチャ ブレンディングを採用して、テクスチャ、影、スペキュラ ライト、ディフューズ ライトなどの特殊効果を単一パスで適用できる。

マルチ テクスチャをブレンドするには、アプリケーションでそれらのテクスチャをカレント テクスチャ セットに割り当て、次にブレンディング ステージを作成する。以下のトピックでは、これらの手順の実行方法について説明する。

  • テクスチャ ステージとテクスチャ ブレンディング カスケード
  • テクスチャ ブレンディング処理と引数
  • カレント テクスチャの割り当て
  • ブレンディング ステージの作成


テクスチャによるライト マッピング

3D シーンをリアルにレンダリングするには、光源がシーンの表示に与えるエフェクトを考慮しなければならない。フラット シェーディングやグーロー シェーディングなどの技術はこの点で貴重なツールであるが、これらの技術だけでは不十分である。Direct3D は、マルチパス テクスチャ ブレンディングとマルチ テクスチャ ブレンディングをサポートしている。これらの機能によって、シェーディング技術だけでレンダリングしたシーンよりもずっとリアルなシーンをレンダリングできる。1 つまたは複数のライト マップを利用すれば、プリミティブにライティングと影の領域をマップできる。

ライト マップとは、3D シーンのライティングについての情報を含むテクスチャまたはテクスチャ グループのことである。このライティング情報をライト マップのアルファ値、カラー値、またはその両方に格納できる。

マルチパス テクスチャ ブレンディングを使用してライト マッピングを実現する場合は、最初のパスでプリミティブにライト マップをレンダリングする必要がある。また、第 2 のパスを使用して、ベース テクスチャをレンダリングする必要がある。ただし、スペキュラ ライト マッピングは除く。スペキュラ ライト マップの場合は、最初にベース テクスチャをレンダリングし、次にライト マップを追加する。

マルチ テクスチャ ブレンディングによって、1 つのパスでライト マップとベース テクスチャの両方をレンダリングできる。ユーザーのハードウェアでマルチ テクスチャ ブレンディングがサポートされている場合は、ライト マッピングを行うときにこのブレンディングを利用するようにする。これによって、アプリケーションのパフォーマンスが大幅に向上する。

ライト マップを使用すれば、Direct3D アプリケーションでは、プリミティブをレンダリングするときにさまざまなライティング エフェクトを生成できる。モノクロ ライティングやカラー ライティングをシーンにマッピングできるほかにも、スペキュラ ハイライトやディフューズ ライトなどの細かなエフェクトを追加できる。

Direct3D テクスチャ ブレンディングを使用してライト マッピングを実行する方法については、以下のトピックで説明する。

  • モノクロ ライト マップ
  • カラー ライティング マップ
  • スペキュラ ライト マップ
  • ディフューズ ライト マップ


テクスチャ圧縮

DirectDraw には、3D モデルのテクスチャに使用するサーフェス圧縮機能がある。圧縮テクスチャ サーフェスのデータの作成および操作については、DirectDraw ドキュメントの「圧縮したテクスチャ サーフェス」を参照すること。

[C++]

アプリケーションでレンダリング デバイスを作成した後、IDirect3DDevice7::EnumTextureFormats メソッドを呼び出して、圧縮テクスチャ サーフェスからのテクスチャ処理をデバイスがサポートするかどうかを調べることができる。このメソッドは、D3DEnumPixelFormatsCallback コールバック関数を呼び出す。この関数は、テクスチャ マップ用にデバイスがサポートするピクセル フォーマットごとに準備する。列挙されるピクセル フォーマットで DXT1、DXT2、DXT3、DXT4、または DXT5 の 4 文字コード (FOURCCs) を使用する場合、デバイスはそのフォーマットを使用する圧縮テクスチャ サーフェスから直接テクスチャを得ることができる。この場合、IDirect3DDevice7::SetTexture メソッドを呼び出して、Direct3D で圧縮テクスチャ サーフェスを直接使用できる。デバイスが圧縮テクスチャ サーフェスからのテクスチャ処理をサポートしない場合でも、テクスチャ データを圧縮フォーマット サーフェス内に格納できる。ただし、圧縮テクスチャをテクスチャとして使用する前に、サポートされるフォーマットに変換しなければならない。DirectDraw のブリット メソッドの IDirectDrawSurface7::Blt およびIDirectDrawSurface7::BltFast は、圧縮フォーマットから標準 RGBA フォーマットへの変換を自動的に実行する。情報の損失を最小限に抑えるには、圧縮フォーマットと一致する転送先ピクセル フォーマットを選択するようにする。たとえば、ARGB:1555 は DXT1 の転送先フォーマットには適しているが、DXT3 には ARGB:4444 の方が適している。DXT3 には 4 ビットのアルファ情報が含まれるためである。

[Visual Basic]

アプリケーションでレンダリング デバイスを作成した後、Direct3DDevice7.GetTextureFormatsEnum メソッドを呼び出して、圧縮テクスチャ サーフェスからのテクスチャ処理をデバイスがサポートするかどうかを調べることができる。このメソッドは、Direct3DEnumPixelFormats クラス オブジェクトへの参照を返す。このクラス オブジェクトは、サポートされているテクスチャ サーフェス ピクセル フォーマットについての情報を取得するためのメソッドを公開する。Direct3DEnumPixelFormats.GetItem メソッドは、サポートされているテクスチャ フォーマットを記述する DDPIXELFORMAT 型に値を設定する。列挙されるピクセル フォーマットで DXT1、DXT2、DXT3、DXT4、または DXT5 の 4 文字コード (FOURCCs) を使用する場合、デバイスはそのフォーマットを使用する圧縮テクスチャ サーフェスから直接テクスチャを得ることができる。この場合、Direct3DDevice7.SetTexture メソッドを呼び出して、Direct3D で圧縮テクスチャ サーフェスを直接使用できる。デバイスが圧縮テクスチャ サーフェスからのテクスチャ処理をサポートしない場合でも、テクスチャ データを圧縮フォーマット サーフェス内に格納できる。ただし、圧縮テクスチャをテクスチャとして使用する前に、サポートされるフォーマットに変換しなければならない。DirectDraw のブリット メソッドの DirectDrawSurface7.Blt および DirectDrawSurface7.BltFast は、圧縮フォーマットから標準 RGBA フォーマットへの変換を自動的に実行する。情報の損失を最小限に抑えるには、圧縮フォーマットと一致する転送先ピクセル フォーマットを選択するようにする。たとえば、ARGB:1555 は DXT1 の転送先フォーマットには適しているが、DXT3 には ARGB:4444 の方が適している。DXT3 には 4 ビットのアルファ情報が含まれるためである。


自動テクスチャ管理

テクスチャ管理とは、要するに、ある時点においてどのテクスチャがレンダリングに必要であるかを判断し、それらのテクスチャをビデオ メモリに確実にロードする処理である。ほかのアルゴリズムと同様、テクスチャ管理スキームもその複雑さはさまざまであるが、どのようなアプローチでテクスチャ管理を行う場合であっても、以下に示すタスクが重要である。

  • 使用可能なテクスチャ メモリの量の追跡
  • 現時点でレンダリングに必要なテクスチャと必要でないテクスチャの計算
  • 既存のテクスチャ サーフェスのうち、ほかのテクスチャ画像に再ロードできるテクスチャ サーフェスの判断、また破棄する必要があるサーフェス、および新しいテクスチャ サーフェスで置き換える必要があるサーフェスの判断

従来は、Direct3D アプリケーション自体でテクスチャ管理を行う必要があった。DirectX 6.0 の Direct3D 直接モードで導入された、システムによるテクスチャ管理により、Direct3D ではテクスチャ管理が効率的かつインテリジェントに行われ、テクスチャはパフォーマンス最適化のために確実にロードされる (Direct3D が管理するテクスチャ サーフェスを "管理下のテクスチャ" と呼ぶこともある)。

テクスチャ マネージャは、least-recently-used (LRU) アルゴリズムを用いて、削除する必要があるテクスチャを判断する。このアルゴリズムでは、テクスチャの最終使用時を示すタイムスタンプを利用してテクスチャを追跡する。メモリから削除するテクスチャが 2 つある場合、テクスチャの優先度に基づいてテクスチャが削除される。2 つのテクスチャの優先度が同じ場合は、最終使用時が新しい方のテクスチャが削除される。ただし、2 つのテクスチャでタイムスタンプが同じ場合は、優先度の低いテクスチャが先に削除される。

[C++]

テクスチャ サーフェスを作成するとき、その自動テクスチャ管理を要求する。C++ アプリケーションで管理下のテクスチャを取得するには、関連する DDSCAPS2 構造体の dwCaps2 メンバに DDSCAPS2_TEXTUREMANAGE または DDSCAPS2_D3DTEXTUREMANAGE フラグを含むテクスチャ サーフェスを作成するだけでよい。ただし、テクスチャの作成場所を指定することはできない。管理下のテクスチャを作成するときには、DDSCAPS_SYSTEMMEMORY または DDSCAPS_VIDEOMEMORY フラグは使用できない。管理下のテクスチャを作成した後、IDirect3DDevice7::SetTexture メソッドを呼び出して、その管理下のテクスチャをレンダリング デバイスのテクスチャ カスケードのステージに設定できる。

テクスチャ サーフェスに対して IDirectDrawSurface7::SetPriority メソッドを呼び出して、管理下のテクスチャに優先度を割り当てることができる。

[Visual Basic]

テクスチャを作成するときに、そのテクスチャの自動テクスチャ管理を要求する。Visual Basic から管理下のテクスチャを取得するには、関連する DDSCAPS2 型の lCaps2 メンバに DDSCAPS2_TEXTUREMANAGE または DDSCAPS2_D3DTEXTUREMANAGE フラグを含むテクスチャ サーフェスを作成する。ただし、テクスチャの作成場所を指定することはできない。管理下のテクスチャを作成するときには、DDSCAPS_SYSTEMMEMORY または DDSCAPS_VIDEOMEMORY フラグは使用できない。管理下のテクスチャを作成した後、Direct3DDevice7.SetTexture メソッドを呼び出して、その管理下のテクスチャをレンダリング デバイスのテクスチャ カスケードのステージに設定できる。

テクスチャ サーフェスに対して DirectDrawSurface7.SetPriority メソッドを呼び出して、管理下のテクスチャに優先度を割り当てることができる。

Direct3D では、必要に応じてテクスチャをビデオ メモリに自動的にダウンロードできる (システムは、非ローカル ビデオ メモリやその他の要素が使用可能であるかどうかによって、管理下のテクスチャをローカルまたは非ローカル ビデオ メモリにキャッシュする。管理下のテクスチャがキャッシュされる場所は、アプリケーションに通知されない。自動テクスチャ管理を利用する際に、この情報は必要ない)。アプリケーションで使用するテクスチャがビデオ メモリに収まらないほどある場合、Direct3D はビデオ メモリから古いテクスチャを削除して、新しいテクスチャ用の領域を確保する。削除したテクスチャを再度使用する場合、システムはオリジナル システム メモリ テクスチャ サーフェスを使用して、テクスチャをビデオ メモリ キャッシュに再ロードする。テクスチャの再ロードは、アプリケーションのパフォーマンスにわずかではあるが影響を与え、パフォーマンスの低下は避けられない。

テクスチャ サーフェスをブリットまたはロックすることで、テクスチャのオリジナル システム メモリ コピーを動的に変更できる。"汚れた" サーフェスが検出された場合 (ブリットの完了後、またはサーフェスのロック解除時)、テクスチャ マネージャはテクスチャのビデオ メモリ コピーを自動的に更新する。このときのパフォーマンスは、削除されたテクスチャを再ロードする場合と同様である。

[C++]

ゲームで新しいレベルに移る際、アプリケーションでビデオ メモリからすべての管理下のテクスチャをフラッシュしなければならないときがある。IDirect3D7::EvictManagedTextures メソッドを呼び出して、すべての管理下のテクスチャを削除するよう明示的に要求できる。このメソッドを呼び出すと、キャッシュされているローカルまたは非ローカル ビデオ メモリ テクスチャが Direct3D によって破棄されるが、オリジナル システム メモリ コピーはそのまま残る。

[Visual Basic]

ゲームで新しいレベルに移る際、アプリケーションでビデオ メモリからすべての管理下のテクスチャをフラッシュしなければならないときがある。Direct3D7.EvictManagedTextures メソッドを呼び出して、すべての管理下のテクスチャを削除するよう明示的に要求できる。このメソッドを呼び出すと、キャッシュされているローカルまたは非ローカル ビデオ メモリ テクスチャが Direct3D によって破棄されるが、オリジナル システム メモリ コピーはそのまま残る。


テクスチャ処理におけるハードウェア制約

現在のハードウェアで、Direct3D インターフェイスによって可能になる機能をすべて利用できるとは限らない。プログラムでユーザーのハードウェアをテストし、レンダリング方法を調整する必要がある。

3D アクセラレータ カードの多くは、ブレンディング ユニットへの引数としてディフューズ反復値をサポートしていない。しかし、テクスチャ ブレンディングを実行する際、プログラムで反復色データを導入できる。

3D ハードウェアによっては、ブレンディング ステージを最初のテクスチャに関連付けることができない場合もある。このようなアダプタの場合、アプリケーションではカレント テクスチャ セットの 2 番目および 3 番目のステージでブレンディングを実行する必要がある。

[C++]

現時点では多くのハードウェアで制約があるため、IDirect3DDevice7 が提供するマルチ テクスチャ ブレンディング インターフェイスによるトライリニア ミップマップ補間を実行できるディスプレイ アダプタは少数である。特に、D3DTSS_MIPFILTER テクスチャ ステージ ステートを D3DTFP_LINEAR に設定できるものはほとんどない。アプリケーションでマルチパス テクスチャ ブレンディングを使用して同じエフェクトを得るか、広くサポートされている D3DTFP_POINT ミップマップ フィルタ モードを使用するとよい。

[Visual Basic]

現時点では多くのハードウェアで制約があるため、Visual Basic の Direct3DDevice7 クラスが提供するマルチ テクスチャ ブレンディング インターフェイスによるトライリニア ミップマップ補間を実行できるディスプレイ アダプタは少数である。特に、D3DTSS_MIPFILTER テクスチャ ステージ ステートを D3DTFP_LINEAR に設定できるものはほとんどない。アプリケーションでマルチパス テクスチャ ブレンディングを使用して同じエフェクトを得るか、広くサポートされている D3DTFP_POINT ミップマップ フィルタ モードを使用するとよい。


深度バッファ

このセクションでは、深度バッファを使用して隠線と隠面を消す方法について説明する。説明するトピックは次のとおりである。

  • 深度バッファとは
  • 深度バッファの使用
[C++]

Direct3D 直接モードの C++ チュートリアルでは、深度バッファの使用方法についての追加情報がある。詳細については、「チュートリアル 2 : 深度バッファを追加する (C++)」を参照すること。

[Visual Basic]

Direct3D 直接モードの Visual Basic チュートリアルでは、深度バッファの使用方法についての追加情報がある。詳細については、「チュートリアル 2 : 深度バッファを追加する (Visual Basic)」を参照すること。


深度バッファとは

z バッファまたは w バッファと呼ばれる深度バッファとは、Direct3D で使用する奥行き情報を格納する DirectDraw サーフェスのことである。Direct3D が 3D シーンをターゲット サーフェスにレンダリングするとき、アタッチされた深度バッファ サーフェスのメモリを作業空間として使用して、ラスタ化したポリゴンのピクセルが互いにどのように覆い合うのかを判定できる。Direct3D は、オフスクリーン DirectDraw サーフェスを、最終的なカラー値を書き込むターゲットとして使用する。レンダリング ターゲット サーフェスにアタッチした深度バッファ サーフェスは、シーンでの可視的ピクセルそれぞれの「深さ」を Direct3D に知らせる深度情報の格納に使用する。

深度バッファリングを有効にして 3D シーンをラスタ化するとき、レンダリング サーフェス上の各点が調べられる。深度バッファの値は、点の z 座標または同次 w 座標 (射影空間の点の (x,y,z,w) 位置座標の) でありうる。z 値を使用する深度バッファは「Z バッファ」と呼ばれ、w 値を使用する深度バッファは「W バッファ」と呼ばれる。どちらの種類の深度バッファにも、それぞれの利点と欠点があるが、これについては後述する。

テストの最初に、深度バッファの深度値をシーンで可能な最大値にセットする。レンダリング サーフェス上のカラー値は、背景のカラー値またはその点の背景テクスチャのカラー値にセットする。シーンの各ポリゴンを調べて、レンダリング サーフェス上のカレント座標 (x,y) と交差するかどうかを確かめる。交差すれば、カレント点での深度値 (Z バッファの z 座標または W バッファの w 座標) をテストして、深度バッファに既に格納されている深度値よりも小さいかどうかを確かめる。ポリゴンの深度値の方が小さければ、その値が深度バッファに格納され、そのポリゴンからのカラー値がレンダリング サーフェス上のカレント点に書き込まれる。その点でのポリゴンの深度値の方が大きければ、リストの次のポリゴンが調べられる。次の図に、この処理を示す。

[C++]

注 : ほとんどのアプリケーションではこの機能を使用しないが、深度バッファに入る値とレンダリング ターゲット サーフェスを判定するために Direct3D が使用するこの比較を変更できる。これを行うには、D3DRENDERSTATE_ZFUNC レンダリング ステートの値を変更すること。

[Visual Basic]

注 : ほとんどのアプリケーションではこの機能を使用しないが、深度バッファに入る値とレンダリング ターゲット サーフェスを判定するために Direct3D が使用するこの比較を変更できる。これを行うには、D3DRENDERSTATE_ZFUNC レンダリング ステートの値を変更すること。

現在では、市販のほとんどすべての 3D アクセラレータが、z バッファリングをサポートしており、Z バッファが最も一般的な深度バッファの種類になっている。しかし、Z バッファにも欠点がある。使用する数学的処理が原因で、Z バッファに生成される z 値は、Z バッファの範囲 (通常 0.0 から 1.0) 全体に均等に分散されない傾向がある。特に、遠くのクリップ面と近くのクリップ面の間の比率は、z 値の不均一な分散に強い影響を与える。近くの平面の距離に対する遠くの平面の距離の比率を 100% とした場合、深度バッファ範囲の 90% がシーンの深度範囲の最初の 10% に費やされる。娯楽や風景のシミュレーション用の典型的なアプリケーションでは、比率 (遠くの平面 / 近くの平面) がどこでも 1000 から 10000 の間である必要がある。比率が 1000 の場合、深度バッファ範囲の98% が深度範囲の最初の 2% に費やされ、比率が高くなるにつれて分散ステートが悪くなる。これによって、遠くのオブジェクトでサーフェス ディテールが隠れてしまうことがある。これは、特に 16 ビット深度 (最も一般的なビット深度) バッファを使用する場合に顕著である。

一方、W 深度バッファでは、Z バッファの場合よりも、近くのクリップ面と遠くのクリップ面の間の分散がより均等である。したがって、遠くのクリップ面と近くのクリップ面の距離の比率が問題にならないという利点がある。これによって、アプリケーションは大きな最大範囲をサポートできる。ただし、視点に近い正確な深度バッファリングといっても相対的なものである。W 深度バッファは完璧ではなく、近くのオブジェクトのサーフェス ディテールが隠れることがある。もう 1 つの欠点は、ハードウェア サポートに関係することである。つまり、w バッファリングはハードウェアで z バッファリングほど広くはサポートされていない。

[C++]

DirectDraw の HEL では、Direct3D またはその他の 3D レンダリング ソフトウェア用の深度バッファを作成できる。HEL は、16 ビット深度バッファをサポートする。この 3D アクセラレータ用の DirectDraw デバイス ドライバでは、DDSCAPS_ZBUFFER フラグを開示しているので、ディスプレイ メモリの深度バッファを作成できる。IDirect3D7::EnumZBufferFormats メソッドを呼び出して、サポートされている深度バッファのビット深度を問い合わせることができる。

Z バッファ サーフェスをどの時点で作成しても、アプリケーションは、Direct3D システムをシャットダウンするまで Z バッファへのポインタを保持しなければならない。プログラムでは、レンダリング サーフェスを解放する直前に Z バッファ サーフェスを解放しなければならない。

[Visual Basic]

DirectDraw の HEL では、Direct3D またはその他の 3D レンダリング ソフトウェア用の深度バッファを作成できる。HEL は、16 ビット深度バッファをサポートする。この 3D アクセラレータ用の DirectDraw デバイス ドライバでは、DDSCAPS_ZBUFFER フラグを開示しているので、ディスプレイ メモリの深度バッファを作成できる。Direct3D7.GetEnumZBufferFormats メソッドを呼び出して、サポートされている深度バッファのビット深度を問い合わせることができる。GetEnumZBufferFormats メソッドは、深度バッファ用にサポートされているピクセル フォーマットを含む Direct3DEnumPixelFormats クラス オブジェクトへの参照を返す。

z バッファリングには、レンダリングのときにオーバーヘッドがある。Z バッファを使用するときに、レンダリングを最適化するために使用できるさまざまな技術がある。詳細については、「Z バッファのパフォーマンス」を参照すること。

注 : 深度値の実際の解釈は、3D レンダラによって異なる。


深度バッファの使用

以下のトピックでは、一般的な深度バッファの使用方法について説明する。

  • 深度バッファのサポート状況の問い合わせ
  • 深度バッファの作成
  • 深度バッファリングの有効化
  • 深度バッファのクリア
  • 深度バッファへの書き込みアクセスの変更
  • 深度バッファ比較関数の変更
  • Z バイアスの使用

参照

深度バッファとは、深度バッファを追加する (C++)、チュートリアル 2: 深度バッファを追加する (Visual Basic)


深度バッファのサポート状況の問い合わせ

ほかの機能でも同様だが、アプリケーションで使用するドライバが深度バッファリングをサポートしていると決めてかからないこと。常にドライバの機能を調べる必要がある。z ベースの深度バッファリングはほとんどのデバイスでサポートされているが、w ベースの深度バッファリングは一部のデバイスでしかサポートされていない (深度バッファリングの一般情報については、「深度バッファとは」を参照すること)。サポートされていないスキームを有効にしようとすると、ドライバは別の深度バッファリングに頼ったり、場合によってはすべての深度バッファリングを無効にし、その結果、レンダリング後のシーンに深度ソートによる不自然な効果が現れることがある。

Direct3D デバイスを作成する前にアプリケーションで使用するディスプレイ デバイスについて DirectDraw に照会することで、深度バッファのサポートを調べることができる。DirectDraw オブジェクトから深度バッファリングをサポートしているとの報告があれば、この DirectDraw オブジェクトから作成するハードウェア デバイスは z バッファリングをサポートする (しかし、このドライバが w バッファリングをサポートするかどうかはわからない)。

[C++]

C++ で一般的な深度バッファリングのサポート状況を問い合わせるには

  1. アプリケーションで使用するディスプレイ デバイスに対して、DirectDraw オブジェクトの IDirectDraw7::GetCaps メソッドを呼び出して、初期化した DDCAPS 構造体をパラメータとして渡す。この呼び出しの後、DDCAPS 構造体に DirectDraw のハードウェアおよびエミュレーション機能についての情報が入る。
  2. 第 1 パラメータとして渡した構造体の ddsCaps メンバを調べる。このメンバ (DDSCAPS2 構造体) に DDSCAPS_ZBUFFER フラグが含まれる場合、このデバイスでは z バッファを利用した深度バッファリングをサポートしている。
[Visual Basic]

Visual Basic で一般的な深度バッファリングのサポート状況を問い合わせるには

  1. アプリケーションで使用するディスプレイ デバイスに対して、DirectDraw オブジェクトの DirectDraw7.GetCaps メソッドを呼び出して、DDCAPS 型の変数をパラメータとして渡す。この呼び出しの後、DDCAPS 構造体に DirectDraw のハードウェアおよびエミュレーション機能についての情報が入る。
  2. 第 1 パラメータとして渡した変数の ddsCaps メンバを調べる。このメンバ (DDSCAPS2 型) に DDSCAPS_ZBUFFER フラグが含まれる場合、このデバイスでは z バッファを利用した深度バッファリングをサポートしている。

ドライバで z バッファがサポートされていることが分かったら、次は w バッファのサポート状況を調べることができる。z バッファはすべてのソフトウェア ラスタライザでサポートされているが、w バッファはリファレンス ラスタライザでしかサポートされていない。これでは、実際のアプリケーションではほとんど使用できない。アプリケーションで使用するデバイスがどのような種類でも、w ベース深度バッファリングを有効にする前に、w バッファのサポート状況を調べる必要がある。

[C++]

C++ アプリケーションで w バッファのサポート状況を調べるには

  1. デバイスを作成した後 (HAL またはエミュレーション)、IDirect3DDevice7::GetCaps メソッドを呼び出して、初期化した D3DDEVICEDESC7 構造体を渡す。
  2. この呼び出しの後、プリミティブのレンダリングに関するドライバのサポートの情報が dpcTriCaps と dpcLineCaps メンバ (D3DPRIMCAPS 構造体) に入る。
  3. これらの構造体の dwRasterCaps メンバに D3DPRASTERCAPS_WBUFFER フラグが含まれている場合、ドライバは当該のプリミティブ種類に対する W 深度バッファリングをサポートする。
[Visual Basic]

Visual Basic で w バッファのサポート状況を調べるには

  1. デバイス (HAL またはエミュレーション) を作成した後、Direct3DDevice7.GetCaps メソッドを呼び出して、D3DDEVICEDESC7 型の変数をパラメータとして渡す。
  2. この呼び出しの後、dpcTriCaps および dpcLineCaps メンバ (D3DPRIMCAPS 型) に、プリミティブのレンダリングに関するドライバでのサポート情報が入る。
  3. dpcTriCaps および dpcLineCaps の lRasterCaps メンバに D3DPRASTERCAPS_WBUFFER フラグが含まれている場合、ドライバではそのプリミティブの種類に対して w ベース深度バッファリングをサポートしている。


深度バッファの作成

通常、アプリケーションの起動シーケンス中に深度バッファを作成した後で、レンダリング用に Direct3D デバイス オブジェクトを作成する。次の手順を実行して、深度バッファ サーフェスを作成し、レンダリング ターゲット サーフェスにアタッチする。

[C++]

C++ アプリケーションで深度バッファを作成するには

  1. IDirect3D7::EnumZBufferFormats メソッドを呼び出して、デバイスがサポートする深度バッファ ピクセル フォーマットを判断する。
  2. DDSURFACEDESC2 構造体を準備して、レンダリング ターゲット サーフェスの大きさに適合し、DDSCAPS_ZBUFFER フラグを含み、サポートされる深度バッファ ピクセル フォーマット (ステップ 1 で取得) を使用する DirectDraw サーフェスを記述する。
  3. アプリケーションで使用するレンダリング デバイスの種類に応じて、ビデオ メモリまたはシステム メモリのどちらかにサーフェスを作成する。(「注意」を参照すること。
  4. IDirectDrawSurface7::AddAttachedSurface メソッドを使用して、深度バッファ サーフェスをレンダリング サーフェスにアタッチする。

深度バッファ サーフェスを作成し、レンダリング ターゲット サーフェスにアタッチした後、IDirect3D7::CreateDevice メソッドを呼び出してレンダリング ターゲット サーフェスとその深度バッファを使用するレンダリング デバイスを作成する。

アプリケーションでハードウェア ドライバ (HAL デバイス) を使用するときは、DDSCAPS_VIDEOMEMORY サーフェス機能を利用してビデオ メモリに深度バッファを作成する。ソフトウェア エミュレーション ドライバ (MMX または RGB デバイス) を使用するときは、DDSCAPS_SYSTEMMEMORY サーフェス機能を利用してシステム メモリに深度バッファを作成する。該当する種類のメモリで深度バッファの作成が失敗した場合、CreateDevice メソッドも失敗する。

注 : 広く使用されている一部のハードウェアでは、レンダリング ターゲットおよび深度バッファ サーフェスで同じビット深度を使用する必要がある。そのようなハードウェアでは、アプリケーションで 16 ビットのレンダリング ターゲット サーフェスを使用する場合は、アタッチする深度バッファも 16 ビットでなければならない。32 ビットのレンダリング ターゲット サーフェスであれば、32 ビットの深度バッファでなければならない。8 ビットの深度バッファは、必要に応じてステンシル バッファリングに使用できる。

アプリケーションが動作するハードウェアにこのような要件があり、アプリケーションがこれを満たしていない場合、非対応サーフェスを使用するレンダリング デバイスを作成しようとすると失敗する。DirectDraw メソッドの IDirectDraw7::GetDeviceIdentifier を使用して、この制限があるハードウェアを特定できる。

[Visual Basic]

Visual Basic アプリケーションで深度バッファを作成するには

  1. Direct3D7.GetEnumZBufferFormats メソッドを呼び出して、サポートされている深度バッファ フォーマットを列挙できる Direct3DEnumPixelFormats オブジェクトへの参照を取得する。デバイスでサポートされている深度バッファ ピクセル フォーマットについて、この列挙オブジェクに問い合わせる。
  2. DDSURFACEDESC2 型を準備して、レンダリング ターゲット サーフェスの大きさと一致し、DDSCAPS_ZBUFFER フラグを含み、サポートされる深度バッファ ピクセル フォーマット (手順 2 で取得) を使用する DirectDraw サーフェスを記述する。
  3. アプリケーションで使用するレンダリング デバイスの種類に応じて、ビデオ メモリまたはシステム メモリのどちらかにサーフェスを作成する。(「注意」を参照すること。
  4. DirectDrawSurface7.AddAttachedSurface メソッドを使用して、深度バッファ サーフェスをレンダリング サーフェスにアタッチする。

深度バッファ サーフェスを作成し、レンダリング ターゲット サーフェスにアタッチした後、Direct3D7.CreateDevice メソッドを呼び出して、レンダリング ターゲット サーフェスとその深度バッファを使用するレンダリング デバイスを作成する。

アプリケーションでハードウェア ドライバ (HAL デバイス) を使用するときは、DDSCAPS_VIDEOMEMORY サーフェス機能を利用してビデオ メモリに深度バッファを作成する。ソフトウェア エミュレーション ドライバ (MMX または RGB デバイス) を使用するときは、DDSCAPS_SYSTEMMEMORY サーフェス機能を利用してシステム メモリに深度バッファを作成する。該当する種類のメモリで深度バッファの作成が失敗した場合、CreateDevice メソッドも失敗する。

注 : 広く使用されている一部のハードウェアでは、レンダリング ターゲットおよび深度バッファ サーフェスで同じビット深度を使用する必要がある。そのようなハードウェアでは、アプリケーションで 16 ビットのレンダリング ターゲット サーフェスを使用する場合は、アタッチする深度バッファも 16 ビットでなければならない。32 ビットのレンダリング ターゲット サーフェスであれば、32 ビットの深度バッファでなければならない。8 ビットの深度バッファは、必要に応じてステンシル バッファリングに使用できる。

アプリケーションが動作するハードウェアにこのような要件があり、アプリケーションがこれを満たしていない場合、非対応サーフェスを使用するレンダリング デバイスを作成しようとすると失敗する。DirectDraw メソッドの DirectDraw7.GetDeviceIdentifier および関連するオブジェクト (DirectDrawIdentifier) を使用して、この制限があるハードウェアを特定できる。


深度バッファリングの有効化

[C++]

深度バッファを作成した後 (「深度バッファの作成」で説明)、IDirect3DDevice7::SetRenderState メソッドを呼び出して深度バッファリングを有効にする。D3DRENDERSTATE_ZENABLE レンダリング ステートを設定して深度バッファを有効にする。z バッファリングを有効にするには D3DZB_TRUE (または TRUE) を、w バッファリングを有効にするには D3DZB_USEW を、深度バッファリングを無効にするには D3DZB_FALSE (または FALSE) をそれぞれ設定する。

注 : w バッファリングを使用するには、アプリケーションで Direct3D トランスフォーム パイプラインを使用しない場合であっても、対応する射影行列を設定しなければならない。適切な射影行列の設定については、「W バッファに有効な射影行列」を参照すること (「射影トランスフォームとは」で説明する射影行列は適切なものである)。

[Visual Basic]

深度バッファを作成した後 (「深度バッファの作成」で説明)、Direct3DDevice7.SetRenderState メソッドを呼び出して深度バッファリングを有効にする。D3DRENDERSTATE_ZENABLE レンダリング ステートを設定して深度バッファリングを有効にする。z バッファリングを有効にするには CONST_D3DZBUFFERTYPE 列挙の D3DZB_TRUE メンバを、w バッファリングを有効にするには D3DZB_USEW を、深度バッファリングを無効にするには D3DZB_FALSE をそれぞれ設定する。

注 : w バッファリングを使用するには、アプリケーションで Direct3D 変換パイプラインを使用しない場合であっても、対応する射影行列を設定しなければならない。適切な射影行列の設定については、「W バッファに有効な射影行列」を参照すること (「射影トランスフォームとは」で説明する射影行列は適切なものである)。


深度バッファのクリア

[C++]

多くの C++ アプリケーションでは、新しいフレームをレンダリングする前に深度バッファをクリアする。IDirect3DDevice7::Clear メソッドを呼び出すことにより、Direct3D で深度バッファを明示的にクリアできる。Clear メソッドでは、dvZ パラメータに任意の深度値を指定できる。

DirectDraw を使用して深度バッファをクリアすることもできる。これをクリアするには、深度バッファ サーフェスの IDirectDrawSurface7::Blt メソッドを呼び出す。DDBLT_DEPTHFILL フラグは、ブリットによって深度バッファをクリアすることを示す。このフラグを指定するときは、IDirectDrawSurface7::Blt メソッドに渡す DDBLTFX 構造体を初期化し、その dwFillDepth メンバを必要な深度に設定しなければならない。

3D アクセラレータ用の DirectDraw デバイス ドライバがハードウェアでの深度バッファのクリアをサポートしている場合、そのドライバは DDCAPS_BLTDEPTHFILL フラグを報告し、DDBLT_DEPTHFILL ブリットを処理しなければならない。深度埋め込みブリットの転送先サーフェスは、深度バッファ サーフェスでなければならない。

[Visual Basic]

多くの Visual Basic アプリケーションでは、新しいフレームをレンダリングする前に深度バッファをクリアする。Direct3DDevice7.Clear メソッドを呼び出すことにより、Direct3D で深度バッファを明示的にクリアできる。Clear メソッドでは、z パラメータに任意の深度値を指定できる。

DirectDraw を使用して深度バッファをクリアすることもできる。これをクリアするには、深度バッファ サーフェスの DirectDrawSurface7.Blt メソッドを呼び出す。DDBLT_DEPTHFILL フラグは、ブリットによって深度バッファをクリアすることを示す。このフラグを指定するときは、DirectDrawSurface7.Blt メソッドに渡される DDBLTFX 型がその lFill メンバを必要な深度に設定する。

3D アクセラレータ用の DirectDraw デバイス ドライバがハードウェアでの深度バッファのクリアをサポートしている場合、そのドライバは DDCAPS_BLTDEPTHFILL フラグを報告し、DDBLT_DEPTHFILL ブリットを処理しなければならない。深度埋め込みブリットの転送先サーフェスは、深度バッファ サーフェスでなければならない。


深度バッファへの書き込みアクセスの変更

デフォルトでは、Direct3D システムは深度バッファへの書き込みが許されている。ほとんどのアプリケーションでは深度バッファへの書き込みを有効にしたままであるが、Direct3D システムによる深度バッファへの書き込みを禁止することによって、特殊効果を生成することができる。

[C++]

C++ で深度バッファへの書き込みを無効にするには、dwRenderStateType パラメータを D3DRENDERSTATE_ZWRITEENABLE に設定し、dwRenderState パラメータを 0 に設定して IDirect3DDevice7::SetRenderState メソッドを呼び出す。

[Visual Basic]

Visual Basic アプリケーションで深度バッファへの書き込みを無効にするには、state パラメータを D3DRENDERSTATE_ZWRITEENABLE に設定し、renderstate パラメータを 0 に設定して Direct3DDevice7.SetRenderState メソッドを呼び出す。


深度バッファ比較関数の変更

[C++]

デフォルトでは、レンダリング サーフェスの深度テストを行うとき、Direct3D システムは、各点に対応する深度値 (z または w) が深度バッファの既存の値より小さい場合、レンダリング ターゲット サーフェスを更新する。C++ アプリケーションで、システムによる深度値の比較方法を変更するには、dwRenderStateType パラメータを D3DRENDERSTATE_ZFUNC に設定して IDirect3DDevice7::SetRenderState メソッドを呼び出す。dwRenderState パラメータには、D3DCMPFUNC 列挙型の値のいずれかを設定する。

[Visual Basic]

デフォルトでは、レンダリング サーフェスの深度テストを行うとき、Direct3D システムは、各点に対応する深度値 (z または w) が深度バッファの既存の値より小さい場合、レンダリング ターゲット サーフェスを更新する。Visual Basic アプリケーションで、システムによる深度値の比較方法を変更するには、state パラメータを D3DRENDERSTATE_ZFUNC に設定して Direct3DDevice7.SetRenderState メソッドを呼び出す。renderstate パラメータには、CONST_D3DCMPFUNC 列挙の値のいずれかを設定する。


Z バイアスの使用

3D 空間で同一平面上にあるポリゴンは、それぞれのポリゴンに Z バイアスを追加することで、あたかも同一平面上にないように表示することができる。この技術は、シーン内の影を正しく表示するために使用されることが多い。たとえば、壁上の影の深度値が壁の深度値と同じになる可能性がある。最初に壁をレンダリングし、次に影をレンダリングすると、影が見えないか、または深度による不自然な効果が見える。同一平面上のオブジェクトのレンダリング順を逆にすると、これとは逆のエフェクトが得られるが、深度による不自然な効果が残ったままであることが多い。

[C++]

C++ アプリケーションでは、同一平面上のポリゴン セットをレンダリングする際にシステムが使用する z 値にバイアスを追加することで、同一平面上のポリゴンを正しくレンダリングできる。z バイアスをポリゴン セットに追加するには、レンダリングの直前に IDirect3DDevice7::SetRenderState メソッドを呼び出す。このとき、dwRenderStateType パラメータを D3DRENDERSTATE_ZBIAS に設定し、dwRenderState パラメータを 0 と 16 を含む 0 ～ 16 の値に設定する。z バイアス値が高いほど、同一平面上のほかのポリゴンと共に表示するとき、レンダリングするポリゴンが見える可能性が高くなる。

[Visual Basic]

Visual Basic アプリケーションでは、同一平面上のポリゴン セットをレンダリングする際にシステムが使用する z 値にバイアスを追加することで、同一平面上のポリゴンを正しくレンダリングできる。z バイアスをポリゴン セットに追加するには、レンダリングの直前に Direct3DDevice7.SetRenderState メソッドを呼び出す。このとき、第 1 パラメータを D3DRENDERSTATE_ZBIAS に設定し、第 2 パラメータを 0 と 16 を含む 0 ～ 16 の値に設定する。z バイアス値が高いほど、同一平面上のほかのポリゴンと共に表示するとき、レンダリングするポリゴンが見える可能性が高くなる。


ステンシル バッファ

このセクションでは、ステンシル バッファの目的と使用方法について説明する。説明するトピックは次のとおりである。

  • ステンシル バッファとは
  • ステンシル バッファの動作
  • ステンシル バッファのカスタマイズ


ステンシル バッファとは

ステンシル バッファは、レンダリング ターゲット サーフェスのピクセルごとの描画を有効または無効にする。このバッファの最も基本的なレベルでは、アプリケーションがレンダリングした画像の部分をマスクで覆うことが可能になり、その画像が表示されない。アプリケーションはディゾルブ、デカーリング、およびアウトライニングなどの特殊効果のためにステンシル バッファを使用することが多い。詳細については、「ステンシル バッファ技術」を参照すること。

[C++]

ステンシル バッファ情報は、Z バッファ データに埋め込まれている。IDirect3D7::EnumZBufferFormats メソッドを呼び出して、ユーザーのハードウェアがステンシル バッファをサポートしているかどうかを調べることができる。このメソッドは、深度バッファ フォーマットを DDPIXELFORMAT 構造体でアプリケーションに渡す。関連情報は、dwZBufferBitDepth、dwStencilBitDepth、dwZBitMask、および dwStencilBitMask メンバに含まれている。

デバイスでのステンシル バッファ制限を調べるには、サポートされているステンシル バッファ処理について D3DDEVICEDESC7 構造体の dwStencilCaps メンバに問い合わせる。

[Visual Basic]

ステンシル バッファ情報は、Z バッファ データに埋め込まれている。アプリケーションでは、Direct3D7.GetEnumZBufferFormats メソッドを呼び出して、ユーザーのハードウェアがステンシル バッファをサポートしているかどうかを調べ、次に、このメソッドが返す Direct3DEnumPixelFormats オブジェクトを使用して、サポートされている各深度バッファ ピクセル フォーマットについての情報を取得する。Direct3DenumPixelFormats.GetItem メソッドは、それぞれ DDPIXELFORMAT 型で深度バッファ フォーマットを取得する。関連情報は、lZBufferBitDepth、lStencilBitDepth、lZBitMask、および lStencilBitMask メンバに含まれている。

デバイスでのステンシル バッファ制限を調べるには、サポートされているステンシル バッファ処理について D3DDEVICEDESC7 型の lStencilCaps メンバに問い合わせる。


ステンシル バッファの動作

[C++]

Direct3D は、ステンシル バッファの内容をピクセルごとに調べる。ステンシル バッファの対応する値、ステンシル参照値、およびステンシル マスク値を使用して、ターゲット サーフェスの各ピクセルに対するテストを行う。テストにパスすると、Direct3D はアクションを実行する。このテストは次の手順で実行される。

  1. ステンシル参照値とステンシル マスクの AND をとる。
  2. カレント ピクセルに対するステンシル バッファ値とステンシル マスクの AND をとる。
  3. 比較関数を使用して、手順 1 と手順 2 の結果を比較する。

擬似コードで記述すると、これらの手順は次のようになる。

(StencilRef & StencilMask) CompFunc (StencilBufferValue & StencilMask)

ここで、StencilBufferValue は、カレント ピクセルに対するステンシル バッファの内容である。この擬似コードでは、& 記号は論理積演算子を表している。StencilMask はステンシル マスク、StencilRef はステンシル参照値を表している。CompFunc は比較関数である。

このステンシル テストにパスすると、カレント ピクセルはターゲット サーフェスに書き込まれるが、失敗した場合は無視される。デフォルトの比較処理は、各ビット操作の結果にかかわらず、ピクセルを書き込むことである (D3DCMP_ALWAYS)。この動作を変更するには、希望の比較関数を指定する D3DCMPFUNC 列挙型のメンバのいずれかを渡して、D3DRENDERSTATE_STENCILFUNC レンダリング ステートの値を変更する。

[Visual Basic]

Direct3D は、ステンシル バッファの内容をピクセルごとに調べる。ステンシル バッファの対応する値、ステンシル参照値、およびステンシル マスク値を使用して、ターゲット サーフェスの各ピクセルに対するテストを行う。テストにパスすると、Direct3D はアクションを実行する。このテストは次の手順で実行される。

  1. ステンシル参照値とステンシル マスクの AND をとる。
  2. カレント ピクセルに対するステンシル バッファ値とステンシル マスクの AND をとる。
  3. 比較関数を使用して、手順 1 と手順 2 の結果を比較する。

擬似コードで記述すると、これらの手順は次のようになる。

(StencilRef And StencilMask) CompFunc (StencilBufferValue And StencilMask)

ここで、StencilBufferValue は、カレント ピクセルに対するステンシル バッファの内容である。StencilMask はステンシル マスク、StencilRef はステンシル参照値を表している。CompFunc は比較関数である。

このステンシル テストにパスすると、カレント ピクセルはターゲット サーフェスに書き込まれるが、失敗した場合は無視される。デフォルトの比較処理は、各ビット操作の結果にかかわらず、ピクセルを書き込むことである (D3DCMP_ALWAYS)。この動作を変更するには、D3DRENDERSTATE_STENCILFUNC レンダリング ステートの値を変更して、希望の比較関数を指定する CONST_D3DCMPFUNC 列挙のメンバのいずれかを渡す。


ステンシル バッファのカスタマイズ

アプリケーションでは、ステンシル バッファの処理をカスタマイズできる。アプリケーションでは、比較関数、ステンシル マスク、およびステンシル参照値を設定できる。また、ステンシル テストにパスした場合または失敗した場合に実行する Direct3D の処理を制御することもできる。詳細については、「ステンシル バッファ ステート」を参照すること。


頂点バッファ

このセクションでは、Direct3D アプリケーションにおいて頂点バッファを理解し使用するのに必要な概念を説明する。説明するトピックは次のとおりである。

  • 頂点バッファとは
  • 頂点バッファの記述
  • デバイスの種類と頂点処理の要件
  • 頂点バッファの使用


頂点バッファとは

[C++]

頂点バッファとは、IDirect3DVertexBuffer7 インターフェイスで表される、頂点データを含む単なるメモリ バッファである。頂点バッファは、トランスフォーム済みの頂点、未トランスフォームの頂点、ライティング済みの頂点、未ライティングの頂点など、IDirect3DDevice7 インターフェイスの頂点バッファ レンダリング メソッドでレンダリング可能なあらゆる種類の頂点を含むことができる。頂点バッファ内の頂点を処理して、トランスフォーム、ライティング、クリッピング フラグの生成などの処理を実行できる (トランスフォームは常に実行される)。

[Visual Basic]

頂点バッファとは、Direct3DVertexBuffer7 クラスで表される、頂点データを含む単なるメモリ バッファである。頂点バッファは、トランスフォーム済みの頂点、未トランスフォームの頂点、ライティング済みの頂点、未ライティングの頂点など、Direct3DDevice7 クラスの頂点バッファ レンダリング メソッドでレンダリング可能なあらゆる種類の頂点を含むことができる。頂点バッファ内の頂点を処理して、トランスフォーム、ライティング、クリッピング フラグの生成などの処理を実行できる (トランスフォームは常に実行される)。

頂点バッファは柔軟なので、トランスフォームされたジオメトリを再使用するための理想的なステージ ポイントとなる。単一の頂点バッファを作成して、頂点をトランスフォーム、ライティングを適用、およびその頂点バッファに頂点を切り取り、たとえインタリーブされたレンダリング ステートが変化した場合でも、シーンのモデルを何度も再トランスフォームせずにレンダリングできる。これは、マルチ テクスチャを使用するモデルのレンダリングにおいて非常に有用である。ジオメトリを一度トランスフォームすれば、要求されたテクスチャの変更に合わせてインタリーブして、必要に応じてその一部をレンダリングできる。頂点を処理した後で変更したレンダリング ステートは、次に頂点を処理するときに有効になる。詳細については、「頂点の処理」を参照すること。

頂点バッファのジオメトリを最適化すれば、頂点操作とレンダリングについて最高のパフォーマンスを得ることができる。詳細については、「頂点バッファの最適化」を参照すること。

[C++]

注 : 内部的には、頂点バッファは、DirectDrawSurface オブジェクトをメモリ管理サービスに使用する。その結果、頂点バッファ メモリにアクセスするセマンティクスは、DirectDrawSurface オブジェクトのセマンティクスに類似する。実際、IDirect3DVertexBuffer7::Lock メソッドは、IDirectDrawSurface7::Lock メソッドと同じフラグを受け取る。詳細については、「頂点バッファの内容へのアクセス」を参照すること。

[Visual Basic]

注 : 内部的には、頂点バッファは、DirectDrawSurface オブジェクトをメモリ管理サービスに使用する。その結果、頂点バッファ メモリにアクセスするセマンティクスは、DirectDrawSurface オブジェクトのセマンティクスに類似する。実際、Direct3DVertexBuffer7.Lock メソッドは、DirectDrawSurface7.Lock メソッドと同じフラグを受け取る。詳細については、「頂点バッファの内容へのアクセス」を参照すること。


頂点バッファの記述

[C++]

頂点バッファの記述は、能力について行う。頂点バッファは、システム メモリ内にだけ存在できるのか、書き込み操作だけに使用されるのか、頂点バッファが含むことができる頂点の種類と数、頂点バッファが作成されてから最適化されたかどうかなどを記述する。これらの特性はすべて D3DVERTEXBUFFERDESC 構造体の中に保持される。

[Visual Basic]

頂点バッファの記述は、能力について行う。頂点バッファは、システム メモリ内にだけ存在できるのか、書き込み操作だけに使用されるのか、頂点バッファが含むことができる頂点の種類と数、頂点バッファが作成されてから最適化されたかどうかなどを記述する。これらの特性はすべて D3DVERTEXBUFFERDESC 型に保持される。

頂点バッファの記述は、頂点バッファの作成方法をシステムに知らせたり、または既存のバッファの作成方法 (あるいは、バッファが作成されて以降最適化されたかどうか) をアプリケーションに知らせる。新しい頂点バッファを作成するには、完全な記述を指定しなければならない。また、空の記述構造体を渡すと、以前作成した頂点バッファの能力がシステムにより記入される。これらのタスクの詳細については、「頂点バッファの作成」および「頂点バッファの記述の取得」を参照すること。

[C++]

ほとんどの DirectX 構造体に共通の dwSize メンバは、構造体バージョンの識別に使用されるため、どのメソッドで構造体を使用する場合でも、まず、このメンバを構造体サイズに設定しなければならない。dwCaps 構造体メンバは、一般的な能力フラグを含む。D3DVBCAPS_SYSTEMMEMORY フラグは、システムが頂点バッファをシステム メモリ内に作成する (または作成済みである) ことを示す。アプリケーションでソフトウェア レンダリング デバイスまたは HAL デバイス (IID_IDirect3DHALDevice) を使用する場合は、明示的にシステム メモリ頂点バッファを作成する。そうでない場合は、フラグを省略して、最良の作成場所の判断をシステムに任せる。明示的なシステム メモリ頂点バッファの詳細については、「デバイスの種類と頂点処理の要件」を参照すること。

dwCaps に D3DVBCAPS_WRITEONLY フラグを指定すると、頂点バッファ メモリを書き込み操作にのみ使用することがシステムに通知される。これによりドライバは、処理とレンダリングをできるだけ高速にする最良のメモリ位置座標に頂点データを配置することをやめる。このフラグを使用する頂点バッファからの読み出しでは、メモリ アクセス時間が非常に低速になることがある。D3DVBCAPS_WRITEONLY フラグを使用しないと、一部の処理とレンダリングの速度を犠牲にするが、読み出し操作が非効率的になる位置座標にドライバがデータを置くことは少なくなる。フラグを何も指定しないと、アプリケーションは頂点バッファ内でデータの読み出し操作と書き込み操作を行うものと見なされる。

注 : D3DVBCAPS_OPTIMIZED フラグは、頂点バッファの作成時には使用されない。システムは、頂点バッファを最適化するときにこの能力フラグを設定する。

最後の 2 つの D3DVERTEXBUFFERDESC 構造体メンバは、その他の能力を記述する。dwFVF メンバには、バッファに含めることができる頂点の種類を識別する柔軟な頂点フォーマット フラグの組み合わせが含まれる。頂点バッファの容量は、dwNumVertices メンバで指定する、頂点バッファに収めることができる頂点の合計数によって測定される。

[Visual Basic]

lCaps メンバは、一般的な能力フラグを含む。D3DVBCAPS_SYSTEMMEMORY フラグは、システムが頂点バッファをシステム メモリ内に作成する (または作成済みである) ことを示す。アプリケーションでソフトウェア レンダリング デバイスまたは HAL デバイス (IID_IDirect3DHALDevice) を使用する場合は、明示的にシステム メモリ頂点バッファを作成する。そうでない場合は、フラグを省略して、最良の作成場所の判断をシステムに任せる。明示的なシステム メモリ頂点バッファの詳細については、「デバイスの種類と頂点処理の要件」を参照すること。

lCaps に D3DVBCAPS_WRITEONLY フラグを指定すると、頂点バッファ メモリを書き込み操作にのみ使用することがシステムに通知される。これによりドライバは、処理とレンダリングをできるだけ高速にする最良のメモリ位置座標に頂点データを配置することをやめる。このフラグを使用する頂点バッファからの読み出しでは、メモリ アクセス時間が非常に低速になることがある。D3DVBCAPS_WRITEONLY フラグを使用しないと、一部の処理とレンダリングの速度を犠牲にするが、読み出し操作が非効率的になる位置座標にドライバがデータを置くことは少なくなる。フラグを何も指定しないと、アプリケーションは頂点バッファ内でデータの読み出し操作と書き込み操作を行うものと見なされる。

注 : D3DVBCAPS_OPTIMIZED フラグは、頂点バッファの作成時には使用されない。システムは、頂点バッファを最適化するときにこの能力フラグを設定する。

最後の 2 つの D3DVERTEXBUFFERDESC メンバは、その他の能力を記述する。lFVF メンバには、バッファに含めることができる頂点の種類を識別する柔軟な頂点フォーマット フラグの組み合わせが含まれる。頂点バッファの容量は、lNumVertices メンバで指定する、頂点バッファに収めることができる頂点の合計数によって測定される。


デバイスの種類と頂点処理の要件

トランスフォームやライティングなどの頂点処理のパフォーマンスは、頂点バッファのメモリ内での位置座標と、使用されるレンダリング デバイスの種類に大きく依存する。頂点バッファを作成すると、アプリケーションはその頂点バッファへのメモリ アロケーションを制御できる。頂点バッファの記述に D3DVBCAPS_SYSTEMMEMORY 能力フラグが設定されているときは、システム メモリに頂点バッファが作成される。この能力フラグを使用しない場合は、頂点バッファ用のメモリの最良の割り当て場所をデバイス ドライバが決定し、このようにして決定されたメモリのことを多くの場合 "ドライバ最適化" メモリと呼ぶ。ドライバ最適化メモリとしては、ローカル ビデオ メモリ、非ローカル ビデオ メモリ、またはシステム メモリが指定される。

[C++]

IDirect3DDevice7::DrawPrimitiveVB、IDirect3DDevice7::DrawIndexedPrimitiveVB、または IDirect3DVertexBuffer7::ProcessVertices メソッドを呼び出すと、Direct3D は頂点処理を適用する。これらの頂点処理には、トランスフォーム、ライティングなどがある。これらの呼び出しのパフォーマンスは、メモリ内でのバッファの位置座標、およびその位置座標が特定の種類のデバイス (ハードウェアまたはソフトウェア) に対して最適なものであるかどうかによって異なる。

[Visual Basic]

Direct3DDevice7.DrawPrimitiveVB、Direct3DDevice7.DrawIndexedPrimitiveVB、または Direct3DVertexBuffer7.ProcessVertices メソッドを呼び出すと、Direct3D は頂点処理を適用する。これらの頂点処理には、トランスフォーム、ライティングなどがある。これらの呼び出しのパフォーマンスは、メモリ内でのバッファの位置座標、およびその位置座標が特定の種類のデバイス (ハードウェアまたはソフトウェア) に対して最適なものであるかどうかによって異なる。

頂点バッファがシステム メモリにあるか、ドライバ最適化メモリにあるかを調べる必要があるのは、テクスチャの場合と同じ理由からである。テクスチャの場合、ハードウェア ラスタ化には、ドライバ最適化メモリに割り当てられたテクスチャが最適で、ソフトウェア ラスタ化には、システム メモリに割り当てられたテクスチャが最適である。同様に、ハードウェアにおける頂点処理 (トランスフォームやライティングなど) に最適なのは、ドライバ最適化メモリに割り当てられた頂点バッファで、ソフトウェアでの頂点処理に最適なのは、システム メモリに割り当てられた頂点バッファである。

注 : ProcessVertices メソッドによる頂点処理は、常にソフトウェアで実行する必要があるため、転送元頂点バッファは常にシステム メモリに割り当てられる必要がある。アプリケーションで転送先頂点バッファを直接ロックして読み出さない限り、また、ProcessVertices (頂点バッファ レンダリング メソッドが呼び出されたとき、頂点バッファからの読み取りを要求する) の呼び出しでクリッピングが要求される場合には、転送先頂点バッファはドライバ最適化メモリに割り当てることができる。

アプリケーションが独自の頂点処理を実行する (および、トランスフォーム済みで、ライティングが適用され、クリッピングされた頂点を頂点バッファ レンダリング メソッドに渡す) 場合、アプリケーションはドライバ最適化メモリに割り当てられた頂点バッファに頂点を直接書き込むことができる。この方法により、以降の冗長なコピー処理を防止する。ただし、ドライバ最適化メモリからホストによって実行される読み取り処理は、非常に処理速度が遅いことがあるため、アプリケーションが頂点バッファからデータを読み返す場合には、この方法はうまく機能しない。したがって、アプリケーションで処理中に読み取り、またはバッファへのデータ書き込みを不規則に実行する必要がある場合は、システム メモリに頂点バッファを割り当てるとよい。

Direct3D 頂点処理機能を使用する場合 (未トランスフォームの頂点を頂点バッファ レンダリング メソッドに渡して)、デバイスの種類に応じてハードウェアまたはソフトウェアのいずれかで処理が実行できる。デバイスが TnLHAL デバイス (IID_IDirect3DTnLHALDevice) の場合、頂点処理はハードウェアで行われるため、最高のパフォーマンスを得るにはドライバ最適化メモリに頂点バッファを作成する。デバイスが HAL デバイス (IID_IDirect3DHALDevice) の場合、頂点処理はソフトウェアで行われるため、システム メモリに頂点バッファを作成する。RGB デバイス (IID_IDirect3DRGBDevice) でレンダリングする場合は、すべての頂点バッファをシステム メモリに割り当てる。

[C++]

次の C++ コードは、頂点バッファを作成および処理するときに適用するロジックをまとめたものである。

if (ソフトウェアのラスタ化)
システム メモリの頂点バッファを使用する。(D3DVBCAPS_SYSTEMMEMORY)
else if (アプリケーションの頂点処理)
if (アプリケーションで読み取りおよび不規則な書き込みを行わない)
ドライバ最適化メモリの頂点バッファを使用する。
else
システム メモリの頂点バッファを使用する。(D3DVBCAPS_SYSTEMMEMORY)
else // Direct3D の頂点処理。
if (TnLHAL デバイス)
ドライバ最適化メモリの頂点バッファを使用する。
else if (HAL デバイス)
システム メモリの頂点バッファを使用する。(D3DVBCAPS_SYSTEMMEMORY)
[Visual Basic]

次の Visual Basic コードは、頂点バッファを作成および処理するときに適用するロジックをまとめたものである。

If (ソフトウェアのラスタ化) Then
システム メモリの頂点バッファを使用する。(D3DVBCAPS_SYSTEMMEMORY)
Else If (アプリケーションの頂点処理) Then
If (アプリケーションで読み取りおよび不規則な書き込みを行わない) Then
ドライバ最適化メモリの頂点バッファを使用する。
Else
システム メモリの頂点バッファを使用する。(D3DVBCAPS_SYSTEMMEMORY)
Else // Direct3D の頂点処理。
If (TnLHAL デバイス) Then
ドライバ最適化メモリの頂点バッファを使用する。
Else If (HAL デバイス)
システム メモリの頂点バッファを使用する。(D3DVBCAPS_SYSTEMMEMORY)
End If


頂点バッファの使用

以下のトピックでは、アプリケーションが頂点バッファで実行する一般的なタスクについて説明する。

  • 頂点バッファの作成
  • 頂点バッファの内容へのアクセス
  • 頂点の処理
  • 頂点バッファの最適化
  • 頂点バッファからのレンダリング
  • 頂点バッファの記述の取得


頂点バッファの作成

[C++]

次の図は、C++ で 1 つの頂点バッファを作成するために必要な手順を示す。

注 : 「Direct3D へのアクセス」で説明するように、DirectDraw コンポーネントは 2 つの COM オブジェクトから構成される。DirectDraw7 と呼ばれる最新のオブジェクトは、DirectDrawCreateEx 関数を呼び出して作成され、IDirect3D7 インターフェイスを公開する唯一のオブジェクトである。また、このオブジェクトは、IDirect3DVertexBuffer7 インターフェイスを公開する頂点オブジェクトを生成できる唯一のオブジェクトでもある。このように作成された Direct3DDevice オブジェクトは、従来の Direct3D インターフェイスを公開しない。アプリケーションで従来の Direct3D オブジェクトを使用する必要がある場合は、DirectDrawCreate メソッドを使用して DirectDraw オブジェクトを作成してから、従来のオブジェクトを作成しなければならない。

4 つのパラメータを受け取る IDirect3D7::CreateVertexBuffer メソッドを呼び出して、頂点バッファ オブジェクトを作成する。第 1 パラメータは、希望の頂点フォーマット、バッファ サイズ、および一般能力を記述する D3DVERTEXBUFFERDESC 構造体のアドレスである。これらの能力については、「頂点バッファの記述」で説明する。通常、システムは、頂点バッファに最適なメモリ位置座標 (システムまたはディスプレイ メモリ) を自動的に割り当てる。ただし、ソフトウェア デバイスまたは HAL デバイス (IID_IDirect3DHALDevice) は、明示的なシステム メモリの頂点バッファでのみ使用できる。詳細については、「デバイスの種類と頂点処理の要件」を参照すること。

CreateVertexBuffer が受け取る第 2 パラメータは、呼び出しが成功したときに頂点バッファ オブジェクトの新しい IDirect3DVertexBuffer7 インターフェイスへのポインタが格納される変数のアドレスである。第 3 パラメータは、頂点バッファに、表示領域外にある頂点のクリッピング情報を (クリップ フラグ形式で) 含めることができるかどうかを指定する。このパラメータを 0 に設定すると、"クリッピング可能" な頂点バッファが作成される。D3DDP_DONOTCLIP フラグを含めると、クリップ フラグを含めることができない頂点バッファが作成される。D3DDP_DONOTCLIP フラグが適用されるのは、トランスフォーム済みの頂点を頂点バッファに含めるよう指示した場合 (D3DFVF_XYZRHW フラグが記述構造体の dwFVF メンバに含まれている) のみである。未トランスフォームの頂点 (D3DFVF_XYZ フラグ) をバッファに含めるよう指示した場合は、CreateVertexBuffer メソッドは D3DDP_DONOTCLIP フラグを無視する。クリッピング フラグは追加メモリを占有するため、クリッピング可能な頂点バッファは、クリッピング フラグを含めない頂点バッファよりも若干大きくなる。リソースは頂点バッファが作成されるときに割り当てられるため、クリッピング可能な頂点バッファは先に要求しておかなければならない。

注 : クリップ フラグを含むことができる頂点バッファを作成しても、必ずしも頂点の処理中にクリップ フラグを生成するよう要求したり、レンダリング中にクリップ フラグを適用するよう要求しなくてもよい。各頂点バッファ レンダリング メソッドは、D3DDP_DONOTCLIP フラグを受け取ると、レンダリング時にクリッピング処理を行わない。また、IDirect3DVertexBuffer7::ProcessVertices メソッドは D3DVOP_CLIP フラグを受け取るが、これを指定していないことで、頂点の処理中にシステムがクリップ フラグを生成することを防止できる。

クリップ フラグをサポートしないで作成された頂点バッファにクリップ フラグを生成することはできない。この場合、IDirect3DVertexBuffer7::ProcessVertices メソッドを使用してクリップ フラグを生成しようとすると、デバッグ ビルドに失敗し、D3DERR_INVALIDVERTEXFORMAT が返される。クリップ フラグを含まないトランスフォーム済み頂点バッファからレンダリングするとき、レンダリング メソッドはクリッピングの要求を無視する。

CreateVertexBuffer が受け取る最後のパラメータは、将来の COM 集約機能との互換性のために用意されている。現在、集約はサポートされていないため、このパラメータは NULL に設定しておく。

次の C++ コードは、頂点バッファの作成方法を示す。

    /*
* この例では、g_lpD3D 変数は Direct3D オブジェクトによって公開される
* IDirect3D7 インターフェイスのアドレスで、
* g_vbVertexBuffer は LPD3DVERTEXBUFFER7 型の変数であり、
* fIsATLHardwareDevice 変数は、アプリケーションを初期化したときに設定される
*  BOOL 変数である。
     */

    D3DVERTEXBUFFERDESC vbdesc;
    ZeroMemory(&vbdesc, sizeof(D3DVERTEXBUFFERDESC));
    vbdesc.dwSize= sizeof(D3DVERTEXBUFFERDESC);
    vbdesc.dwCaps        = 0L;
    vbdesc.dwFVF         = D3DFVF_VERTEX;
    vbdesc.dwNumVertices = NUM_FLAG_VERTICES;

// これがトランスフォーム & ライティングに対応したハードウェア デバイスでない場合、
// 頂点バッファは必ずシステム メモリを使用する。
if( !fIsATLHardwareDevice )
        vbdesc.dwCaps |= D3DVBCAPS_SYSTEMMEMORY;

// クリッピング可能頂点バッファを作成する。
    if(FAILED(g_lpD3D->CreateVertexBuffer(&vbdesc,
                                          &g_pvbVertexBuffer, 0L,
                                          NULL)))
        return E_FAIL;
[Visual Basic]

次の図は、Visual Basic で 1 つの頂点バッファを作成するために必要な手順を示す。

Visual Basic では、4 つのパラメータを受け取る Direct3D7.CreateVertexBuffer メソッドを呼び出して、頂点バッファ オブジェクトを作成する。第 1 パラメータは、希望の頂点フォーマット、バッファ サイズ、および一般能力を記述する D3DVERTEXBUFFERDESC 型のアドレスである。これらの能力については、「頂点バッファの記述」で説明する。通常、システムは、頂点バッファに最適なメモリ位置座標 (システムまたはディスプレイ メモリ) を自動的に割り当てる。ただし、ソフトウェア デバイスまたは HAL デバイス (IID_IDirect3DHALDevice) は、明示的なシステム メモリの頂点バッファでのみ使用できる。詳細については、「デバイスの種類と頂点処理の要件」を参照すること。

第 2 パラメータは、頂点バッファに、表示領域外にある頂点のクリッピング情報を (クリップ フラグ形式で) 含めることができるかどうかを指定する。このパラメータを 0 に設定すると、"クリッピング可能" な頂点バッファが作成される。D3DDP_DONOTCLIP フラグを含めると、クリップ フラグを含めることができない頂点バッファが作成される。D3DDP_DONOTCLIP フラグが適用されるのは、トランスフォーム済みの頂点を頂点バッファに含めるよう指示した (D3DFVF_XYZRHW フラグが記述の lFVF メンバに含まれる) 場合のみである。未トランスフォームの頂点 (D3DFVF_XYZ フラグ) をバッファに含めるよう指示した場合、CreateVertexBuffer メソッドは D3DDP_DONOTCLIP フラグを無視する。クリッピング フラグは追加メモリを占有するため、クリッピング可能な頂点バッファは、クリッピング フラグを含めない頂点バッファよりも若干大きくなる。リソースは頂点バッファが作成されるときに割り当てられるため、クリッピング可能な頂点バッファは先に要求しておかなければならない。

呼び出しが成功すると、CreateVertexBuffer メソッドは新しい Direct3DVertexBuffer7 オブジェクトへの参照を返す。

注 : クリップ フラグを含むことができる頂点バッファを作成しても、必ずしも頂点の処理中にクリップ フラグを生成するよう要求したり、レンダリング中にクリップ フラグを適用するよう要求しなくてもよい。各頂点バッファ レンダリング メソッドは、D3DDP_DONOTCLIP フラグを受け取ると、レンダリング時にクリッピング処理を行わない。また、Direct3DVertexBuffer7.ProcessVertices メソッドは D3DVOP_CLIP フラグを受け取るが、これを指定していないことで、頂点の処理中にシステムがクリップ フラグを生成することを防止できる。

クリップ フラグをサポートしないで作成された頂点バッファにクリップ フラグを生成することはできない。この場合、Direct3DVertexBuffer7.ProcessVertices メソッドを使用してクリップ フラグを生成しようとすると、デバッグ ビルドに失敗し、D3DERR_INVALIDVERTEXFORMAT エラーが返される。クリップ フラグを含まないトランスフォーム済み頂点バッファからレンダリングするとき、レンダリング メソッドはクリッピングの要求を無視する。

次の Visual Basic コードは、頂点バッファの作成方法を示す。

    '
' この例では、g_D3D 変数は Direct3D7 オブジェクトへの参照で、
' g_VertexBuffer は Direct3DVertexBuffer7 オブジェクトへの
' 参照である。
    '
On Local Error Resume Next

Dim VBDesc As D3DVERTEXBUFFERDESC
VBDesc.lFVF = D3DFVF_VERTEX
VBDesc.lNumVertices = NUM_FLAG_VERTICES

' クリッピング可能頂点バッファを作成する。
Set g_VertexBuffer = g_D3D.CreateVertexBuffer(VBDesc, D3DDP_DEFAULT)

If Err.Number <> DD_OK Then
' エラー処理コード
End If


頂点バッファの内容へのアクセス

[C++]

頂点バッファ オブジェクトを使うと、頂点データに割り当てられたメモリにアプリケーションが直接アクセスできる。IDirect3DVertexBuffer7::Lock メソッドを呼び出して頂点バッファ メモリへのポインタを取得し、次に必要に応じてメモリにアクセスして新しい頂点データをバッファに設定するか、既に設定されているデータを読み出す。

IDirect3DVertexBuffer7::Lock メソッドは 3 つのパラメータを受け取る。第 1 パラメータの dwFlags は、メモリのロック方法をシステムに知らせる。このパラメータは、バッファ内のデータにアプリケーションがどのようにアクセスするかを知らせるために使用できる (読み取り専用または書き込み専用アクセスを指定できる。これにより、ドライバはメモリをロックして、要求されているアクセス タイプで最高のパフォーマンスを提供する。ヒントは必須ではないが、状況によってはメモリ アクセスのパフォーマンスを改善できる)。頂点バッファは DirectDrawSurface オブジェクトを使用して頂点データを格納するため、IDirect3DVertexBuffer7::Lock が受け取るフラグは IDirectDrawSurface7::Lock メソッドのフラグと同じで、結果も同じである。

Lock メソッドが受け取る第 2 パラメータ lplpData は、LPVOID 変数のアドレスで、呼び出しが成功した場合は、頂点バッファ メモリを指す有効なポインタが設定される。最後のパラメータ lpdwSize は、呼び出しが返された後、lplpData が指すバッファのバイト単位でのサイズが設定される変数のアドレスである。アプリケーションがバッファ サイズの情報を必要としない場合は、lpdwSize に NULL を設定できる。

パフォーマンスに関する注意 : アプリケーションが頂点バッファ メモリからの読み取りのみを行う場合は、DDLOCK_READONLY フラグを使用する。このフラグを含めると、Direct3D が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。DDLOCK_READONLY フラグでロックしたメモリに書き込むことは可能であるが、予期せぬ結果になることがある。また、D3DVBCAPS_WRITEONLY フラグで作成した頂点バッファから読み出そうとすると、バッファを読み出し専用にロックした場合でも極端に低速になることがある。

C++ の場合、頂点バッファに割り当てられているメモリに直接アクセスする。このとき、目的のメモリには正しくアクセスするよう注意すること。そうでないと、不正なメモリがレンダリングされるおそれがある。アプリケーションで使用する頂点フォーマットのストライドを利用して、割り当てられているバッファの頂点から次の頂点に移動する。頂点バッファ メモリ自体は、柔軟な頂点フォーマットで指定された頂点の単純な配列である。アプリケーションで従来の頂点構造体の D3DVERTEX、D3DLVERTEX、および D3DTLVERTEX を使用する場合、ストライドは単にバイト単位の構造体のサイズである。従来のフォーマットと異なる頂点フォーマットを使用している場合は、定義した任意の頂点フォーマット構造体のストライドを使用する。頂点バッファの記述に含まれる柔軟な頂点フォーマット フラグを調べることで、実行時に各頂点のストライドを計算できる。次の表は、各頂点成分のサイズを示す。

頂点フォーマット フラグ | サイズ
D3DFVF_DIFFUSE | sizeof(DWORD)
D3DFVF_NORMAL | sizeof(float) × 3
D3DFVF_SPECULAR | sizeof(DWORD)
D3DFVF_TEXn | sizeof(float) × 2 × n
D3DFVF_XYZ | sizeof(float) × 3
D3DFVF_XYZRHW | sizeof(float) × 4

頂点フォーマットに存在するテクスチャ座標の数は、D3DFVF_TEXn フラグで記述される (n は 0 ～ 8 までの値)。頂点フォーマットのテクスチャ座標セットは、float 変数 2 個分の空間を占めるため、その数のテクスチャ座標に要求されるメモリを計算するには、テクスチャ座標セットの数にテクスチャ座標 1 セットのサイズを乗ずる。

特定の頂点にアクセスするには、合計頂点ストライドを使用して、メモリ ポインタを必要なだけインクリメントまたはデクリメントする。

[Visual Basic]

頂点バッファを使用すると、Visual Basic アプリケーションでは、頂点バッファ内の頂点データを簡単に更新できる。頂点バッファ内のデータにアクセスするには、Direct3DVertexBuffer7.Lock メソッドを呼び出す。Lock メソッドには、メモリのロック方法をシステムに知らせる flags パラメータがある。flags パラメータは、バッファ内のデータにアプリケーションがどのようにアクセスするかを知らせる。(読み取り専用または書き込み専用アクセスを要求できる。これにより、ドライバはメモリをロックして、要求されているアクセス タイプで最高のパフォーマンスを提供する。ヒントは必須ではないが、状況によってはメモリ アクセスのパフォーマンスを改善できる)。頂点バッファは DirectDrawSurface オブジェクトを使用して頂点データを格納するため、Direct3DVertexBuffer7.Lock が受け取るフラグは、DirectDrawSurface7.Lock メソッドのフラグと同じで、結果も同じである。

パフォーマンスの注意 : アプリケーションが頂点バッファ メモリからの読み取りのみを行う場合は、DDLOCK_READONLY フラグを使用する。このフラグを含めると、Direct3D が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。DDLOCK_READONLY フラグでロックしたメモリに書き込むことは可能であるが、予期せぬ結果になることがある。また、D3DVBCAPS_WRITEONLY フラグで作成した頂点バッファから読み出そうとすると、バッファを読み出し専用にロックした場合でも極端に低速になることがある。

頂点バッファをロックすると、Direct3DVertexBuffer7.GetVertices メソッドを呼び出して、頂点バッファの現在の内容を配列に入れることができる。第 1 パラメータには、必要なバッファ内にある最初の頂点の 0 から始まるインデックスを設定し、第 2 パラメータには、取得する頂点の合計数を設定する。最後のパラメータには、呼び出し後に要求されるデータを入れる頂点バッファと同じ頂点フォーマットを使用する配列内の最初の要素を設定しなければならない。

頂点バッファ メモリ自体は、柔軟な頂点フォーマットで指定された頂点の単純な配列である。頂点フォーマットに存在するテクスチャ座標の数は、D3DFVF_TEXn フラグで記述される (n は 0 ～ 8 の値)。頂点フォーマットのテクスチャ座標セットは、Single 変数 2 個分の空間を占めるため、その個数のテクスチャ座標で必要なメモリを計算するには、テクスチャ座標セットの個数にテクスチャ座標 1 セット分のサイズを乗ずる。

頂点バッファをロックした後でその内容を変更するには、配列の内容を変更し、次に Direct3DVertexBuffer7.SetVertices メソッドを呼び出して頂点をバッファにコピーする。頂点バッファ処理やレンダリング処理を実行する前に、Direct3DVertexBuffer7.Unlock メソッドで頂点バッファをロック解除する必要もある。


頂点の処理

[C++]

オプションで、ライティング、クリップ フラグの生成、および範囲の更新などの頂点操作も適用できる。IDirect3DVertexBuffer7 インターフェイスは、頂点処理用の IDirect3DVertexBuffer7::ProcessVertices メソッドを公開する。転送元バッファではなく転送先頂点バッファの ProcessVertices メソッドを呼び出して、頂点を転送元頂点バッファから転送先頂点バッファに処理する。このメソッドが受け取る 7 つのパラメータには、実行する操作、転送元頂点バッファの IDirect3DVertexBuffer7 インターフェイスの位置座標、頂点操作を行うレンダリング デバイス、およびメソッドのターゲットとなる頂点の位置座標と数を記述する。呼び出しの後、転送先バッファには処理された頂点データが設定されるが、転送元バッファは変化しない。

頂点の処理を準備するときは、第 1 パラメータ dwVertexOp に行いたい頂点操作を設定する。D3DVOP_TRANSFORM フラグは必ず含めなければならず、含めないとメソッドは失敗する。残りの操作はオプションである。頂点の処理に、頂点のライティング、クリップ フラグの生成、範囲の更新など、オプションのフラグはどのような組み合わせでも含めることができる。

第 2 パラメータ dwDestIndex と第 3 パラメータ dwCount は、頂点が置かれる転送先バッファのインデックスと、処理されて転送先バッファ内に置かれる頂点の合計数を表わす。第 4 パラメータ lpSrcBuffer には、転送される頂点を含む頂点バッファ オブジェクトの IDirect3DVertexBuffer7 のアドレスを設定する。dwSrcIndex は、メソッドが頂点処理を開始する位置座標を示すインデックスを指定する (処理の対象となる転送元の頂点の合計数は dwCount パラメータで指定される)。lpD3DDevice パラメータには、頂点を処理するレンダリング デバイスの IDirect3DDevice7 インターフェイスのアドレスを設定する。

最後のパラメータ dwFlags は、メソッドの特殊処理オプションを指定する。このパラメータを 0 に設定すると、デフォルトの頂点処理が実行され、D3DPV_DONOTCOPYDATA を設定すると、何らかの状況において処理が最適化される。dwFlags を 0 に設定すると、転送元頂点バッファの頂点フォーマットの頂点成分は、頂点処理の影響を受けずに転送元頂点バッファからコピーされるか (転送元バッファにある場合)、0 に設定される。ただし、D3DPV_DONOTCOPYDATA を使用することにより、転送元バッファの頂点フォーマットの頂点成分は、ProcessVertices の呼び出しの一部として計算されずにそのまま残る。ProcessVertices メソッドを呼び出して、ライトを当てていない頂点をトランスフォーム (このメソッドの D3DVOP_TRANSFORM 頂点処理を利用) する場合を考えてみる。転送先頂点バッファで D3DFVF_TLVERTEX 頂点フォーマットを使用している場合、D3DPV_DONOTCOPYDATA フラグを指定すると、転送先バッファのディフューズ、スペキュラ、およびテクスチャ座標コンポーネントは無視される。その結果、システムには頂点のトランスフォームのみ要求することになり、処理とデータ転送のオーバーヘッドが軽くなる。D3DPV_DONOTCOPYDATA を指定していない場合は、アプリケーションで不必要であるにもかかわらず、ライティングおよびテクスチャ座標コンポーネントが転送先バッファにコピーされる。D3DPV_DONOTCOPYDATA フラグは、頂点処理の際にシステムで必要となる作業量を軽減するのに有効なフラグである。ProcessVertices を使用するアプリケーションでは、スタティック頂点成分を転送先頂点バッファに直接コピーできるため、システム側で転送元バッファから転送先バッファにコピーする必要はなくなる。

デバイスでの頂点処理の制限を調べるには、サポートされている頂点処理能力について、D3DDEVICEDESC7 構造体の dwVertexProcessingCaps メンバを問い合わせる。

[Visual Basic]

オプションで、ライティング、クリップ フラグの生成、および範囲の更新などの頂点操作も適用できる。Direct3DVertexBuffer7 クラスには、頂点を処理する Direct3DVertexBuffer7.ProcessVertices メソッドがある。転送元バッファではなく転送先頂点バッファの ProcessVertices メソッドを呼び出して、頂点を転送元頂点バッファから転送先頂点バッファに処理する。このメソッドには 7 つのパラメータがあり、実行する操作、転送元 Direct3DVertexBuffer7 オブジェクトへの参照、頂点処理を実行するレンダリング デバイス、およびメソッドの対象となる頂点の位置座標と個数をそれぞれ記述する。呼び出しの後、転送先バッファには処理された頂点データが設定されるが、転送元バッファは変化しない。

頂点の処理をするときは、第 1 パラメータ vertexOp に実行する頂点処理を設定する。D3DVOP_TRANSFORM フラグは必ず含めなければならず、含めないとメソッドは失敗する。残りの操作はオプションである。頂点の処理に、頂点のライティング、クリップ フラグの生成、範囲の更新など、オプションのフラグはどのような組み合わせでも含めることができる。

第 2 パラメータ destIndex および第 3 パラメータ count は、頂点が配置される転送先バッファのインデックス、および処理されて転送先バッファに配置される頂点の合計数をそれぞれ表わす。第 4 パラメータ srcBuffer には、転送される頂点を含む Direct3DVertexBuffer7 オブジェクトを設定する必要がある。srcIndex は、メソッドが頂点処理を開始する位置座標を示すインデックスを指定する (処理の対象となる転送元の頂点の合計数は count パラメータで指定される)。dev パラメータには、頂点を処理する Direct3DDevice7 オブジェクトを設定する。

最後のパラメータ flags は、メソッドの特殊処理オプションを指定する。このパラメータを 0 に設定すると、デフォルトの頂点処理が実行され、D3DPV_DONOTCOPYDATA を設定すると、何らかの状況において処理が最適化される。flags を 0 に設定すると、転送元頂点バッファの頂点フォーマットの頂点成分は、頂点処理の影響を受けずに転送元頂点バッファからコピーされるか (転送元バッファにある場合)、0 に設定される。ただし、D3DPV_DONOTCOPYDATA を使用することにより、転送元バッファの頂点フォーマットの頂点成分は、ProcessVertices の呼び出しの一部として計算されずにそのまま残る。ProcessVertices メソッドを呼び出して、ライトを当てていない頂点をトランスフォーム (このメソッドの D3DVOP_TRANSFORM 頂点処理を利用) する場合を考えてみる。転送先頂点バッファで D3DFVF_TLVERTEX 頂点フォーマットを使用している場合、D3DPV_DONOTCOPYDATA フラグを指定すると、転送先バッファのディフューズ、スペキュラ、およびテクスチャ座標コンポーネントは無視される。その結果、システムに頂点のトランスフォームのみ要求することになり、処理とデータ転送のオーバーヘッドが軽くなる。D3DPV_DONOTCOPYDATA を指定していない場合は、アプリケーションで不必要であるにもかかわらず、ライティングおよびテクスチャ座標コンポーネントが転送先バッファにコピーされる。D3DPV_DONOTCOPYDATA フラグは、頂点処理の際にシステムで必要となる作業量を軽減するのに有効なフラグである。ProcessVertices を使用するアプリケーションでは、スタティック頂点成分を転送先頂点バッファに直接コピーできるため、システム側で転送元バッファから転送先バッファにコピーする必要はなくなる。

デバイスでの頂点処理の制限を調べるには、サポートされている頂点処理能力について、D3DDEVICEDESC7 型の lVertexProcessingCaps メンバを問い合わせる。

互換性のある頂点フォーマットを使用した頂点バッファを作成するように注意すること。少なくとも、転送元バッファは未トランスフォームの頂点を含み (バッファ記述の頂点フォーマットに D3DFVF_XYZ フラグを使用)、転送先バッファはトランスフォームされた頂点を含むものとする (D3DFVF_XYZRHW フラグを使用)。ライティングまたはクリッピング サービスのために、転送元と転送先の頂点フォーマットは適切なフィールドを含むことが要求される。たとえば、頂点フォーマットに頂点法線を含めていない場合は、頂点のライティングを要求しないこと。同様に、クリッピング機能なしで作成された転送先頂点バッファに、システムがクリップ フラグを生成するよう要求することはできない。互換性のないバッファで操作を行おうとすると、デバッグ ビルドの場合、失敗する。

アプリケーションで頂点バッファからレンダリングを実行する場合は、頂点バッファ メソッドを使用する必要がある。

転送元または転送先の頂点バッファがロックされているときは、頂点を処理することはできない。


頂点バッファの最適化

頂点バッファを最適化すると、システムはバッファの内容を修正し、頂点の処理またはレンダリングのパフォーマンスが良好になる。頂点がどのように最適化されるかは、プラットフォーム固有であり、変更されることがある。このため、最適化された頂点バッファの内容をロックしたり、アクセスすることはできない。

[C++]

ハードウェアおよびソフトウェアの両方のパフォーマンスは、頂点バッファを最適化することで改善できる。頂点バッファの最適化は、頂点バッファがハードウェアまたはソフトウェアの頂点処理のどちらのために使用されているかによって異なる。D3DVBCAPS_SYSTEMMEMORY フラグを指定して作成した頂点バッファは、ソフトウェア頂点処理に対して最適化され、IDirect3DVertexBuffer7::ProcessVertices メソッドまたは HAL デバイス (TnLHAL デバイスとは対照的) の頂点バッファ レンダリング メソッドでのみ使用できる。D3DVBCAPS_SYSTEMMEMORY フラグ (ドライバ最適化メモリ用) を指定しないで作成した頂点バッファは、ハードウェア頂点処理に対して最適化され、したがって、TnLHAL デバイスのレンダリング メソッドでのみ使用できる。最適化された頂点バッファは、IDirect3DVertexBuffer7::ProcessVertices または IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドの転送先バッファとして使用することはできない。

IDirect3DVertexBuffer7::Optimize メソッドを呼び出して頂点バッファを最適化する。頂点バッファを最適化すると、頂点操作とレンダリングのパフォーマンスが改善される。IDirect3DVertexBuffer7::Optimize メソッドは 2 つのパラメータを受け取るが、そのうち 1 つだけが使用される。lpD3DDevice パラメータに頂点を最適化するデバイスのアドレスを設定し、最後のパラメータに 0 を設定する。ロックされた頂点バッファは、アンロックするまで最適化できない。

頂点を最適化されたフォーマットに保つことによりパフォーマンスを改善できる。ただし、最適化された頂点バッファは、スタティック ジオメトリだけに使用する。頂点バッファを一度最適化すると、最適化された内容を変更するためにロックすることはできないからである。最適化された頂点バッファは、IDirect3DVertexBuffer7::ProcessVertices メソッドおよび頂点バッファ レンダリング メソッドでのみ使用できる。

[Visual Basic]

ハードウェアおよびソフトウェアの両方のパフォーマンスは、頂点バッファを最適化することで改善できる。頂点バッファの最適化は、頂点バッファがハードウェアまたはソフトウェアの頂点処理のどちらのために使用されているかによって異なる。D3DVBCAPS_SYSTEMMEMORY フラグを指定して作成した頂点バッファは、ソフトウェア頂点処理に対してのみ最適化され、Direct3DVertexBuffer7.ProcessVertices メソッドまたは HAL デバイス (TnLHAL デバイスとは対照的) の頂点バッファ レンダリング メソッドでのみ使用できる。D3DVBCAPS_SYSTEMMEMORY フラグ (ドライバ最適化メモリ用) を指定しないで作成した頂点バッファは、ハードウェア頂点処理に対して最適化され、したがって、TnLHAL デバイスのレンダリング メソッドでのみ使用できる。最適化された頂点バッファは、Direct3DVertexBuffer7.ProcessVertices メソッドの転送先バッファとして使用することはできない。

Direct3DVertexBuffer7.Optimize メソッドを呼び出して頂点バッファを最適化する。頂点バッファを最適化すると、頂点処理およびレンダリングのパフォーマンスが改善される。Direct3DVertexBuffer7.Optimize メソッドはパラメータを 1 つ受け取る。このパラメータには、頂点の最適化の対象となる Direct3DDevice7 オブジェクトを設定する。ロックされている頂点バッファは、ロック解除するまで最適化することはできない。

頂点を最適化されたフォーマットに保つことによりパフォーマンスを改善できる。ただし、最適化された頂点バッファは、スタティック ジオメトリだけに使用する。頂点バッファを一度最適化すると、最適化された内容を変更するためにロックすることはできないからである。最適化された頂点バッファは、Direct3DVertexBuffer7.ProcessVertices メソッドおよび頂点バッファ レンダリング メソッドでのみ使用できる。


頂点バッファからのレンダリング

「レンダリング」で説明するように、レンダリング デバイスでは、頂点バッファからプリミティブをレンダリングするためのメソッドを利用できる。これらのメソッドは、その他のほとんどのレンダリング メソッドとほぼ同様の機能を持つが、頂点バッファ オブジェクトを指定するパラメータに若干の違いがある。

以下のトピックでは、一般的なレンダリング状況について、および頂点バッファ レンダリング メソッドの呼び出しに関する特定の問題について説明する。

  • 頂点バッファ レンダリングについて
  • 頂点バッファ レンダリング メソッドの呼び出し


頂点バッファの記述の取得

[C++]

アプリケーションでは、しばしば、実行時に既存の頂点バッファについての情報を取得することが必要になる。Direct3D では、IDirect3DVertexBuffer7::GetVertexBufferDesc メソッドを使用してこの情報を取得する。このメソッドは、現在の記述を取得する頂点バッファの IDirect3DVertexBuffer7 インターフェイスを使用して呼び出す。

GetVertexBufferDesc メソッドはパラメータを 1 つだけ受け取る。このパラメータには、適切に初期化された D3DVERTEXBUFFERDESC 構造体のアドレスを設定する。構造体を初期化するには、dwSize メンバを構造体のバイト単位のサイズに設定し、残りのメンバは 0 に設定する。メソッドが返ると、頂点バッファ機能、バッファ内の頂点フォーマット、バッファが含むことができる頂点の合計数についての情報が構造体に設定されている。

注 : 頂点バッファを最適化すると、D3DVBCAPS_OPTIMIZED 能力フラグがD3DVERTEXBUFFERDESC 構造体の dwCaps メンバに設定される。このフラグが設定されているときは、頂点バッファはロックできない。最適化された頂点バッファの内容は、レンダリング メソッドおよび頂点バッファ処理メソッド (IDirect3DVertexBuffer7::ProcessVertices および IDirect3DVertexBuffer7::ProcessVerticesStrided) 以外では使用できない。

一般的な情報については、「頂点バッファの記述」を参照すること。

[Visual Basic]

アプリケーションでは、しばしば、実行時に既存の頂点バッファについての情報を取得することが必要になる。Direct3D では、Direct3DVertexBuffer7.GetVertexBufferDesc メソッドを使用して、Visual Basic アプリケーションでこの情報を取得できるようにする。

GetVertexBufferDesc メソッドはパラメータを 1 つだけ受け取る。このパラメータには、D3DVERTEXBUFFERDESC 型の適切な変数を設定する。このメソッドが返ると、構造体には、頂点バッファの能力、バッファの頂点フォーマット、およびバッファに含まれる頂点の合計数についての情報が入る。

注 : 頂点バッファを最適化すると、D3DVBCAPS_OPTIMIZED 能力フラグが、GetVertexBufferDesc によって取得される D3DVERTEXBUFFERDESC 型の lCaps メンバに設定される。このフラグが設定されているときは、頂点バッファはロックできない。最適化された頂点バッファの内容は、レンダリング メソッドおよび Direct3DVertexBuffer7.ProcessVertices メソッド以外では使用できない。

一般的な情報については、「頂点バッファの記述」を参照すること。


共通のテクノロジと特殊効果

Direct3D は、3D シーンをよりリアルに表示するための強力なツール群を提供している。このセクションでは、Direct3D で生成できる一般的な特殊効果について説明する。生成できるエフェクトの範囲は、ここで説明するエフェクトに限定されるものではない。説明するトピックは次のとおりである。

  • フォグ
  • ジオメトリ ブレンディング
  • ユーザー定義クリップ面
  • 環境マッピング
  • バンプ マッピング
  • ビルボード化
  • 雲、煙、蒸気
  • 火、炎、爆発など
  • モーション ブラー
  • ステンシル バッファ技術
  • カラー ライティング
  • アンチエイリアシング


フォグ

以下のトピックでは、フォグについて、および Direct3D アプリケーションでの各種フォグ機能の使用について説明する。

  • フォグの概要
  • フォグ公式
  • フォグ パラメータ
  • フォグ ブレンディング
  • フォグ カラー
  • ピクセル フォグ
  • 頂点フォグ


フォグの概要

3D シーンにフォグを追加することにより、よりリアルな情景を表現したり、雰囲気を出したり、遠くの景色をぼかすことができる。Direct3D 直接モードは、ピクセル フォグと頂点フォグという 2 つのフォグ モデルをサポートする。この 2 つは、それぞれ固有の機能とプログラミング インターフェイスを持つ。

フォグは、基本的には、シーン内のオブジェクトの深度または視点からの距離に基づき、シーン内のオブジェクトの色と選択したフォグ カラーをブレンドして実現する。オブジェクトが遠ざかるに従い、元の色とフォグ カラーのブレンドが増し、シーンに浮かぶ小さい粒子、つまり "フォグ" によってオブジェクトの表示がぼけていく。次の画面は、フォグなしで描画したシーンと、フォグを有効にして描画した同じシーンを示す。

上の図で、左側のシーンには明瞭な水平線があり、その向こうには実世界では見えるはずの風景が見えない。右側のシーンでは背景色と同一のフォグ カラーを使用して水平線がぼかされ、ポリゴンが遠方では消えるように見える。個別のフォグ エフェクトとクリエイティブなシーン デザインとを組み合わせると、シーン内のオブジェクトの色を和らげ、雰囲気を増すことができる。

Direct3D は、シーンにフォグを追加するために、アプリケーションに 2 つの方法を提供する。ピクセル フォグと頂点フォグであり、フォグ エフェクトをどのように適用するかに従って名付けられている。詳細については、「ピクセル フォグ」および「頂点フォグ」を参照すること。簡単に言えば、ピクセル フォグ ("テーブル フォグ" とも呼ばれる) はデバイス ドライバで実現され、頂点フォグは Direct3D ライティング エンジンで実現される。

注 : 頂点フォグおよびピクセル フォグのいずれを使用している場合でも、アプリケーションではフォグ エフェクトが正しく適用されるよう適切な射影行列を用意する必要がある。この制約は、Direct3D トランスフォーム & ライティング エンジンを使用しないアプリケーションにも当てはまる。適切な行列の作成方法の詳細については、「W バッファに有効な射影行列」を参照すること。


フォグ公式

[C++]

C++ アプリケーションでは、Direct3D で距離に応じてフォグ エフェクトの計算を変更することにより、フォグがシーンのオブジェクトの色に与える影響を制御できる。D3DFOGMODE 列挙型には、3 つのフォグ公式を識別するメンバが含まれている。すべての式は、アプリケーションが設定するパラメータを与えられ、距離の関数としてフォグ係数を計算する。距離自体がどのように計算されるかは、範囲ベースのフォグが有効であるかどうかと、射影行列により変化する。詳細については、「視点からの相対深度 対 Z ベースの深度」および「範囲ベースのフォグ」を参照すること。

[Visual Basic]

Visual Basic で記述されたアプリケーションでは、Direct3D で距離に応じてフォグ エフェクトの計算を変更することにより、フォグがシーンのオブジェクトの色に与える影響を制御できる。CONST_D3DFOGMODE 列挙には、3 つのフォグ公式を識別するメンバが含まれている。すべての式は、アプリケーションが設定するパラメータを与えられ、距離の関数としてフォグ係数を計算する。距離自体がどのように計算されるかは、範囲ベースのフォグが有効であるかどうかと、射影行列により変化する。詳細については、「視点からの相対深度 対 Z ベースの深度」および「範囲ベースのフォグ」を参照すること。

D3DFOG_LINEAR

この線形公式で、start はフォグ エフェクトが始まる距離、end はフォグ エフェクトがそれ以上増加しなくなる距離、d はシーンの範囲内での深度 (または視点からの距離) を表す。オブジェクトが遠方になるに従って d の値が増加する。線形公式はピクセル フォグと頂点フォグの両方でサポートされるが、指数公式は、現在、ピクセル フォグを使用するときだけサポートされる。

D3DFOG_EXP

D3DFOG_EXP2

上の 2 つの指数公式で、e は自然対数の底 (約 2.71828)、density は 0.0 から 1.0 の範囲の任意のフォグ密度、d はシーンの範囲内での深度 (または視点からの距離) である。

注 : システムは、頂点のスペキュラ色のアルファ成分にフォグ係数を格納する。アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、フォグ係数を手動で挿入しておくと、レンダリング時にシステムがそのフォグ係数を適用する。

次の図では、公式のパラメータに共通の値を使用して、これらの公式をグラフに示す。

Direct3D がフォグ エフェクトを計算するときは、上の等式の 1 つのフォグ係数を次に示すブレンディング公式で使用する。

この公式は、現在のポリゴン Ci の色をフォグ係数 f により効果的にスケーリングし、その積を、フォグ係数のビット反転によりスケーリングしたフォグ カラー Cf に加算する。結果として得られるカラー値は、フォグ カラーと元の色のブレンドであり、距離の係数でもある。この公式は、DirectX 7,0 がサポートするすべてのデバイスに適用される。従来からのランプ デバイスに対しては、フォグ係数はディフューズ色成分とスペキュラ色成分をスケーリングし、0.0 から 1.0 の範囲内 (0.0 と 1.0 を含む) に収める。フォグ係数は、通常、前方クリップ面を 1.0 として始まり、後方クリップ面を 0.0 として減少する。


フォグ パラメータ

[C++]

フォグ パラメータは、デバイス レンダリング ステートによって制御される。ピクセル フォグおよび頂点フォグではともに、「フォグ公式」で説明するフォグ公式をすべてサポートしている。D3DFOGMODE 列挙型は、Direct3D で使用するフォグ公式を識別する定数を定義する。D3DRENDERSTATE_FOGTABLEMODE レンダリング ステートは、Direct3D がピクセル フォグに使用するフォグ モードを制御し、D3DRENDERSTATE_FOGVERTEXMODE レンダリング ステートは頂点フォグのモードを制御する。

線形フォグ公式を使用するときは、D3DRENDERSTATE_FOGSTART および D3DRENDERSTATE_FOGEND レンダリング ステートを使用して開始距離および終了距離を設定する。これらの値をシステムがどのように解釈するかは、アプリケーションでピクセル フォグおよび頂点フォグのどちらを使用しているかによって異なる。ピクセル フォグを使用している場合は、z ベースまたは w ベースの深度が使用される (z ベースおよび w ベースの深度の詳細については、「視点からの相対深度 対 Z ベースの深度」を参照すること)。次の表にまとめる。

フォグの種類 | フォグの開始/終了単位
ピクセル (Z) | デバイス空間 [0.0,1.0]
ピクセル (W) | カメラ空間
頂点 | カメラ空間

D3DRENDERSTATE_FOGDENSITY レンダリング ステートは、指数フォグ公式が有効なときに適用されるフォグ密度を制御する。フォグ密度は、本質的には加重係数であり、指数の距離値を 0.0 から 1.0 (0.0 と 1.0 を含む) にスケーリングする。

システムがフォグ ブレンディングに使用する色は、D3DRENDERSTATE_FOGCOLOR デバイス レンダリング ステートを使用して制御する。詳細については、「フォグ カラー」および「フォグ ブレンディング」を参照すること。

[Visual Basic]

フォグ パラメータは、デバイス レンダリング ステートによって制御される。ピクセル フォグおよび頂点フォグではともに、「フォグ公式」で説明するフォグ公式をすべてサポートしている。CONST_D3DFOGMODE 列挙には、Direct3D で使用するフォグ公式を識別する定数が定義されている。D3DRENDERSTATE_FOGTABLEMODE レンダリング ステートは、Direct3D がピクセル フォグに使用するフォグ モードを制御し、D3DRENDERSTATE_FOGVERTEXMODE レンダリング ステートは頂点フォグのモードを制御する。

線形フォグ公式を使用するときは、D3DRENDERSTATE_FOGSTART および D3DRENDERSTATE_FOGEND レンダリング ステートを使用して開始距離および終了距離を設定する。これらの値をシステムがどのように解釈するかは、アプリケーションでピクセル フォグおよび頂点フォグのどちらを使用しているかによって異なる。ピクセル フォグを使用している場合は、z ベースまたは w ベースの深度が使用される (z ベースおよび w ベースの深度の詳細については、「視点からの相対深度 対 Z ベースの深度」を参照すること)。次の表にまとめる。

フォグの種類 | フォグの開始/終了単位
ピクセル (Z) | デバイス空間 [0.0,1.0]
ピクセル (W) | カメラ空間
頂点 | カメラ空間

D3DRENDERSTATE_FOGDENSITY レンダリング ステートは、指数フォグ公式が有効なときに適用されるフォグ密度を制御する。フォグ密度は、本質的には加重係数であり、指数の距離値を 0.0 から 1.0 (0.0 と 1.0 を含む) にスケーリングする。

システムがフォグ ブレンディングに使用する色は、D3DRENDERSTATE_FOGCOLOR デバイス レンダリング ステートで制御される。DirectX7.CreateColorRGB メソッドを使用して、このレンダリング ステートに有効なカラー値を生成する。詳細については、「フォグ カラー」および「フォグ ブレンディング」を参照すること。


フォグ ブレンディング

[C++]

フォグ ブレンディングとは、「フォグ公式」で説明するように、シーンに表示する最終色を生成するために、フォグおよびオブジェクトの色にフォグ係数を適用することである。D3DRENDERSTATE_FOGENABLE レンダリング ステートは、フォグ ブレンディングを制御する。次のコードで示すように、このレンダリング ステートを TRUE に設定して (デフォルトは FALSE) フォグ ブレンディングを有効にする。

//
// この例では、g_lpDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。
HRESULT hr;
hr = g_lpDevice->SetRenderState(
                     D3DRENDERSTATE_FOGENABLE,
                     TRUE);
if FAILED(hr)
    return hr;

フォグ ブレンディングは、ピクセル フォグと頂点フォグの両方に対して有効にしなければならない。これらの種類のフォグの使用方法については、「ピクセル フォグ」および「頂点フォグ」を参照すること。

[Visual Basic]

フォグ ブレンディングとは、「フォグ公式」で説明するように、シーンに表示する最終色を生成するために、フォグおよびオブジェクトの色にフォグ係数を適用することである。D3DRENDERSTATE_FOGENABLE レンダリング ステートは、フォグ ブレンディングを制御する。次のコードで示すように、このレンダリング ステートを TRUE に設定して (デフォルトは FALSE) フォグ ブレンディングを有効にする。

'
' この例では、g_d3dDevice に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納されている。
'
On Local Error Resume Next

Call g_d3dDevice.SetRenderState( _
D3DRENDERSTATE_FOGENABLE, _
True);

If Err.Number <> DD_OK Then
' エラー処理コード
End If

フォグ ブレンディングは、ピクセル フォグと頂点フォグの両方に対して有効にしなければならない。これらの種類のフォグの使用方法については、「ピクセル フォグ」および「頂点フォグ」を参照すること。


フォグ カラー

[C++]

ピクセル フォグと頂点フォグの両方のフォグ カラーは、D3DRENDERSTATE_FOGCOLOR レンダリング ステートを使用して設定する。レンダリング ステート値は、RGBA 色 (アルファ成分は無視される) として指定する任意の RGB 色である。

次の C++ コードは、フォグ カラーを白に設定する。

/* この例では、g_lpD3DDevice 変数は IDirect3DDevice7 インターフェイスへの
* 有効なポインタである。
 */
HRESULT hr;

hr = g_lpd3dDevice->SetRenderState(
                    D3DRENDERSTATE_FOGCOLOR,
                    0x00FFFFFF); // 上位 8 ビットは使用されない。

if(FAILED(hr))
    return hr;
[Visual Basic]

ピクセル フォグおよび頂点フォグの両方のフォグ カラーは、D3DRENDERSTATE_FOGCOLOR レンダリング ステートを使用して設定する。レンダリング ステート値には、DirectX7.CreateColorRGB メソッドが返す RGB 色を指定できる。

次の Visual Basic コードは、フォグ カラーを白に設定する。

'
' この例では、g_d3dDevice 変数は Direct3DDevice7 オブジェクトへの
' 有効な参照で、
' g_dx は DirectX7 オブジェクトへの有効な参照である。
'
On Local Error Resume Next

Call g_d3dDevice.SetRenderState( _
D3DRENDERSTATE_FOGCOLOR, _
g_dx.CreateColorRGB(1#, 1#, 1#))

If Err.Number <> DD_OK Then
' エラー処理コード
End If


ピクセル フォグ

このセクションでは、ピクセル フォグの概念について、および Direct3D アプリケーションでの使用について説明する。説明するトピックは次のとおりである。

  • ピクセル フォグについて
  • 視点からの相対深度 対 Z ベースの深度
  • ピクセル フォグの使用


頂点フォグ

このセクションでは、頂点フォグについて、および Direct3D アプリケーションでの使用について詳しく説明する。説明するトピックは次のとおりである。

  • 頂点フォグについて
  • 範囲ベースのフォグ
  • 頂点フォグの使用


ジオメトリ ブレンディング

このセクションでは、DirectX 7.0 の新機能、ジオメトリ ブレンディングについて説明する。説明するトピックは次のとおりである。

  • ジオメトリ ブレンディングについて
  • ブレンディング トランスフォームとレンダリング ステート
  • ブレンディングの重み
  • ジオメトリ ブレンディングの使用


ジオメトリ ブレンディングについて

DirectX 7.0 の Direct3D 直接モードでは、ジョイント部が滑らかにブレンドされている各ポリゴンを、特にキャラクタをレンダリングすることで、シーンを一層リアルに表現することができる (これらのエフェクトを一般には "スキニング" と呼ぶ)。このエフェクトは、追加の "ワールド" トランスフォーム行列を頂点の単一セットに適用し、その結果生成される複数のトランスフォーム後の頂点間で線形ブレンドを実行してレンダリング用のジオメトリの単一セットを生成することで実現される。次に示すのは、Bend サンプルによってレンダリングされたバナナに基づく画像である。

この画像は、ジオメトリ ブレンディングの処理がどのようなものであるかを示す。1 回のレンダリングの呼び出しで、システムはバナナの頂点を取得し、この頂点に対して回転しないトランスフォームと単純な回転のトランスフォームを 1 回ずつ実行して、その結果 "曲がった" バナナを生成する。システムは、頂点法線 (ライティングが有効な場合) だけでなく頂点位置座標もブレンドする。アプリケーションは 2 つのブレンディング方法に限定されるわけではない。Direct3D は、最大 4 つの異なるワールド行列 (標準ワールド行列の D3DTRANSFORMSTATE_WORLD など) 間でジオメトリをブレンドできる。

[C++]

注 : ライティングが有効になっている場合、頂点法線が、対応するワールドビュー行列の逆行列によってトランスフォームされる。この際、重み付けは、頂点位置座標の計算の場合と同様に行われる。D3DRENDERSTATE_NORMALIZENORMALS レンダリング ステートが TRUE に設定されている場合は、結果の法線ベクトルがシステムによって正規化される。

可動結合部のあるモデルの場合、ジオメトリ ブレンディングを使用せずに部分ごとにレンダリングされることが多い。たとえば、人間の腕の 3D モデルを考える。最も単純にして、腕には身体につながる上腕と手につながる下腕がある。2 本の腕はともに肘につながっており、下腕はこの位置座標で回転する。アプリケーションで腕をレンダリングする場合、上腕と下腕の頂点データは保持され、それぞれに個別のワールド トランスフォーム行列が適用される。次のコードはこのことを示す。

typedef struct _Arm {
D3DVERTEX upper_arm_verts[200];
D3DMATRIX matWorld_Upper;

D3DVERTEX lower_arm_verts[200];
D3DMATRIX matWorld_Lower;
} ARM, *LPARM;

ARM MyArm; // これは初期化する必要がある。

腕をレンダリングするには、次のコードで示すように、レンダリングの呼び出しを 2 回実行する。

// 上腕をレンダリングする。
d3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD, &MyArm.matWorld_Upper );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, D3DFVF_VERTEX,
MyArm.upper_arm_verts, 200, 0 );

// 下腕をレンダリングして、腕を関節でつなぐワールド行列を更新する。
// 肘でπ/4 ラジアン (45°) ずつ回転するようにする。
MyArm.matWorld_Lower = RotateMyArm(MyArm.matWorld, pi/4);
d3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD, &MyArm.matWorld_Lower );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, D3DFVF_VERTEX,
MyArm.lower_arm_verts, 200, 0 );
[Visual Basic]

注 : ライティングが有効になっている場合、頂点法線が、対応するワールドビュー行列の逆行列によってトランスフォームされる。この際、重み付けは、頂点位置座標の計算の場合と同様に行われる。D3DRENDERSTATE_NORMALIZENORMALS レンダリング ステートが TRUE に設定されている場合は、結果の法線ベクトルがシステムによって正規化される。

可動結合部のあるモデルの場合、ジオメトリ ブレンディングを使用せずに部分ごとにレンダリングされることが多い。たとえば、人間の腕の 3D モデルを考える。最も単純にして、腕には身体につながる上腕と手につながる下腕がある。2 本の腕はともに肘につながっており、下腕はこの位置座標で回転する。アプリケーションで腕をレンダリングする場合、上腕と下腕の頂点データは保持され、それぞれに個別のワールド トランスフォーム行列が適用される。次のコードはこのことを示す。

Type Arm
upper_arm_verts(200) As D3DVERTEX
matWorld_Upper As D3DMATRIX

lower_arm_verts(200) As D3DVERTEX
matWorld_Lower As D3DMATRIX
End Type

Dim MyArm As Arm ' これは初期化する必要がある。

腕をレンダリングするには、次のコードで示すように、レンダリングの呼び出しを 2 回実行する。

' 上腕をレンダリングする。
Call d3DDevice.SetTransform(D3DTRANSFORMSTATE_WORLD, MyArm.matWorld_Upper)
Call d3DDevice.DrawPrimitive(D3DPT_TRIANGLELIST, D3DFVF_VERTEX, _
MyArm.upper_arm_verts, 200, 0)

' 下腕をレンダリングして、腕を関節でつなぐワールド行列を更新する。
' 肘でπ/4 ラジアン (45°) ずつ回転するようにする。
MyArm.matWorld_Lower = RotateMyArm(MyArm.matWorld, pi / 4)
Call d3DDevice.SetTransform(D3DTRANSFORMSTATE_WORLD, MyArm.matWorld_Lower)
Call d3DDevice.DrawPrimitive(D3DPT_TRIANGLELIST, D3DFVF_VERTEX, _
MyArm.lower_arm_verts, 200, 0)

次の画像は、Bend サンプルでレンダリングしたバナナを、このテクニックを使用するために修正したものである。

ブレンドされたジオメトリと、ブレンドされていないジオメトリの違いは明らかである。この例でもその違いははっきり分かる。実際のアプリケーションでは、各モデルを "ジョイント" しても、それほどジョイント部が目立つことはない。しかし、ジョイント部が見苦しく表示されることもある。これは、モデル デザイナにとって今後の課題である。

Direct3D のジオメトリ ブレンディングでは、従来のセグメント モデル シナリオを使用することもできる。ジオメトリ ブレンディングを使用する場合にも負荷がかかる。つまり、分割されている個々のオブジェクトの表示品質を上げるためにレンダリング時にブレンディング計算が行われた末、これが適用される。これらの追加処理による影響を最小限に抑えるために、Direct3D ジオメトリ パイプラインは、可能な限りオーバーヘッドを発生させないでジオメトリをブレンドできるように最適化される。アプリケーションでは Direct3D のジオメトリ ブレンディング サービスを有効に使用することで、パフォーマンスへの深刻な影響を避けながら、キャラクタをより本物らしく表現することができる。


ブレンディング トランスフォームとレンダリング ステート

[C++]

IDirect3DDevice7::SetTransform および IDirect3DDevice7::SetTransform メソッドは、ジオメトリがブレンドされる際の行列を識別する D3DTRANSFORMSTATETYPE 列挙型の D3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_WORLD1、D3DTRANSFORMSTATE_WORLD2、および D3DTRANSFORMSTATE_WORLD3 メンバを認識する (D3DTRANSFORMSTATE_WORLD メンバが "D3DTRANSFORMSTATE_WORLD0" として認識されることもある)。

D3DRENDERSTATETYPE 列挙型には、ジオメトリ ブレンディングを有効にして制御する D3DRENDERSTATE_VERTEXBLEND レンダリング ステートが含まれる。このレンダリング ステートの有効値は、D3DVERTEXBLENDFLAGS 列挙型によって定義される。この列挙型には、D3DVBLEND_DISABLE、D3DVBLEND_1WEIGHT、D3DVBLEND_2WEIGHT、D3DVBLEND_3WEIGHT メンバなどが含まれる。ジオメトリ ブレンディンが有効になっている場合、頂点フォーマットにはブレンディングの適切な加重値が含まれていなければならない。

[Visual Basic]

Direct3DDevice7.SetTransform および Direct3DDevice7.SetTransform メソッドは、ジオメトリがブレンドされる際の行列を識別する CONST_D3DTRANSFORMSTATETYPE 列挙のD3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_WORLD1、D3DTRANSFORMSTATE_WORLD2、および D3DTRANSFORMSTATE_WORLD3 メンバを認識する (D3DTRANSFORMSTATE_WORLD メンバが "D3DTRANSFORMSTATE_WORLD0" として認識されることもある)。

CONST_D3DRENDERSTATETYPE 列挙には、ジオメトリ ブレンディングの有効にして制御する D3DRENDERSTATE_VERTEXBLEND レンダリング ステートが含まれる。このレンダリング ステートの有効値は、CONST_D3DVERTEXBLENDFLAGS 列挙型によって定義される。この列挙型には、D3DVBLEND_DISABLE, D3DVBLEND_1WEIGHT、D3DVBLEND_2WEIGHT、D3DVBLEND_3WEIGHT メンバなどが含まれる。ジオメトリ ブレンディンが有効になっている場合、頂点フォーマットにはブレンディングの適切な加重値が含まれていなければならない。

参照

ブレンディング行列の設定、ジオメトリ ブレンディングの有効化、ブレンディングの重み


ブレンディングの重み

ブレンディングの重み ("ベータの重み" と呼ぶときもある) は、指定されたワールド行列によって頂点が受ける影響の範囲を制御する。ブレンディングの重みとは、0.0 ～ 1.0 の範囲の浮動小数点値であり、頂点フォーマットで符号化される。値が 0.0 の場合、頂点はその行列でブレンドされない。値が 1.0 の場合、頂点は行列の影響をすべて受ける。

[C++]

ジオメトリ ブレンディングの重みは、頂点フォーマットで符号化され、「頂点フォーマットについて」で説明するように、各頂点の位置座標のすぐ後に現れる。Direct3D レンダリング メソッドに指定する頂点記述に D3DFVF_XYZB1 ～ D3DFVF_XYZB5 の柔軟な頂点フォーマット フラグのいずれかを含めることで、頂点フォーマットにブレンディングの重みを指定する。

[Visual Basic]

ジオメトリ ブレンディングの重みは、頂点フォーマットで符号化され、「頂点フォーマットについて」で説明するように、各頂点の位置座標のすぐ後に現れる。Direct3D レンダリング メソッドに指定する頂点記述に D3DFVF_XYZB1 ～ D3DFVF_XYZB5 の柔軟な頂点フォーマット フラグのいずれかを含めることで、頂点フォーマットにブレンディングの重みを指定する。

重み付けされたブレンド行列間で、システムによって線形ブレンドが実行される。次に、正式なブレンディング公式を示す。

この公式では、vBlend は出力頂点であり、v 要素は適用後のワールド行列 (D3DTRANSFORMSTATE_WORLDn) によって生成される頂点である。W 要素は、頂点フォーマット内の対応する重みである。n 個の行列間でブレンドされる頂点は、n–1 個のブレンディングの重みを持つことができる (最後のブレンディング行列を除き、各ブレンディング行列に 1 つの重み)。最後のワールド行列の重みは、この公式では Σ で表すように、重みの合計が 1.0 になるようシステムによって自動的に生成される。この公式は、現在 Direct3D がサポートしているケースに合わせて、次のように簡略化できる。

この公式は、正式なブレンディング公式を、2、3、および 4 つのブレンド行列のケース (現在サポートされているのはこれだけ) に合わせて簡略化したものである。

注 : Direct3D では、最大 5 つのブレンディングの重みを持つ頂点を定義する柔軟な頂点フォーマット記述子を含めることができるが、このリリースの DirectX では 3 つまでしか使用できない。


ジオメトリ ブレンディング

説明するトピックは次のとおりである。

  • ブレンディング用の頂点の定義
  • ブレンディング行列の設定
  • ジオメトリ ブレンディングの有効化


ユーザー定義クリップ面

Direct3D を使用すれば、アプリケーションでは、任意に定義されたクリップ面に従ってジオメトリを切り取ることができる。このトピックでは、ユーザー定義クリップ面について、およびアプリケーションでユーザー定義クリップ面を使用する方法について説明する。

  • ユーザー定義クリップ面とは
  • ユーザー定義クリップ面の使用


ユーザー定義クリップ面とは

ユーザー定義クリップ面を使用すると、アプリケーションでは、任意のクリップ面を適用してシーンのジオメトリをクリッピングすることができる。クリップ面は一般平面式で定義される。システムではこの式をワールド空間のものと見なす。

次の図は、Spheremap サンプルを利用したもので、クリッピングのエフェクトを強調するために若干修正を加えている (サンプルは、ワイヤーフレームでレンダリングするように修正され、背面カリングは無効になっている)。この画像にはクリップ面は適用されていない。

ユーザー定義クリップ面を適用すると、シーンのジオメトリを簡単にクリッピングすることができる。以下の不等式が成り立つ場合、ワールド座標 (x, y, z) の点が面で区切られた半分の空間から切り取られる。

この公式では、A、B、C、および D は、面を定義するためにアプリケーションからシステムに提供される係数である。クリップ面上またはその後方にある点がシーンから切り取られる。次の画像は 2 つのティーポットを示す。2 つの異なる面で切り取られている。

左側のティーポットを切り取った面の係数は [A = -1.0, B = 0.0, C = 0.0, D = 0.0] であり、x >=0 を満たす頂点がすべて切り取られる。右側のティーポットを切り取ったた面は、係数 [A = 1.0, B = 0.0, C = 1.0, D = 0.0] で定義され、z >= 0.0 を満たす頂点がすべて切り取られる。

ジオメトリは、複数の面を使用してクリッピングすることができる。複数のクリップ面を使用する場合、各面によって定義される区切られた空間の組み合わせがレンダリング領域になる。次の画像は、2 つの面でクリッピングされたティーポットを示す。

このティーポットは 2 つの面で切り取られている。1 つは係数 [A = 1.0, B = 0.0, C = 0.0, D = 0.0] の面で、もう 1 つは係数 [A = 0.0, B = -1.0, C = 0.0, D = 0.0] で定義される面である。

[C++]

Direct3D では最大 32 個 (D3DMAXUSERCLIPPLANES) のクリップ面による切り取りが可能であるが、デバイスで最大いくつのクリップ面を使用できるかはまちまちである。この点を間違えないように、現在のデバイス (D3DDEVICEDESC7 構造体の wMaxUserClipPlanes メンバ) のデバイス機能を常にチェックするようにする。

[Visual Basic]

Direct3D では最大 32 個のクリップ面による切り取りが可能であるが、デバイスで最大いくつのクリップ面を使用できるかはまちまちである。この点を間違えないように、現在のデバイス (D3DDEVICEDESC7 型の nMaxUserClipPlanes メンバ) のデバイス機能を常にチェックするようにする。

ここに示す単純なジオメトリ クリッピングも多くの場合は有効な手段として使用されるが、ユーザー定義クリップ面はそれよりもさらに多くの用途を持つ。ユーザー定義クリップ面とステンシル バッファを組み合わせると、キャッピング、干渉テストなどの高度なタスクを実行できる。


ユーザー定義クリップ面の使用

ユーザー定義クリップ面は、簡単に定義、操作、および有効にできる。以下のトピックでは、ユーザー定義クリップ面の共通タスクについて説明する。

  • クリップ面の設定と取得
  • クリップ面の有効/無効


環境マッピング

このセクションでは、Direct3D 直接モードの一般的な 2 種類の環境マッピングの実行について説明する。グラフィックス業界では多種多様な環境マッピングが使用されているが、以下のトピックでは、最も一般的なキューブ環境マップおよび球体環境マッピングについて説明する。

  • 環境マッピングとは
  • キューブ環境マップ
  • 球体環境マッピング


環境マッピングとは

環境マッピングとは、反射性の高いサーフェスをレイ トレーシングを使用せずにシミュレートする方法である。実際、環境マッピングでは、オブジェクトの周囲の景色を含む特殊なテクスチャ マップがそのオブジェクト自体に適用される。その結果、反射性を持つサーフェスには、十分に人の目をごまかせる程度に周囲の景色が映り込む。レイ トレーシングを実行した場合に生じる計算負荷も発生しない。

次の画像は、Spheremap サンプル (C++) のものである。名前から分かるように、このサンプルでは "球体環境マッピング" と呼ばれる環境マッピングを使用している。詳細については、「球体環境マッピング」を参照すること。

このティーポットは周囲の景色を反射しているように見えるが、実際にはテクスチャが適用されている。環境マッピングは、テクスチャ (特殊な計算で求めたテクスチャ座標を組み合わせたもの) を使用するため瞬時に実行される。


キューブ環境マップ

キューブ環境マップでは、オブジェクトの周囲の空間またはライティングのエフェクトがそのオブジェクトの表面に沿って適用される。これは立方体の内部の 6 つの面によって表現される。このセクションでは以下のトピックについて説明する。

  • キューブ環境マップとは
  • キューブ環境マップ サーフェスの作成
  • キューブ環境マップ サーフェスへのアクセス
  • キューブ環境マップのミップマップ化
  • キューブ環境マップへのレンダリング
  • キューブ環境マップのテクスチャ座標


球体環境マッピング

球体環境マッピングは、多くの場合 "球体マッピング" と呼ばれるが、オブジェクトの周囲の空間の画像とライティングのエフェクトをそのオブジェクトの表面に沿って貼り付けていく。このとき、オブジェクトの周囲の空間は、特殊なフォーマットのテクスチャ マップに符号化される。以下のトピックでは、球体マッピングの概念について、および Direct3D アプリケーションでの球体マッピングの使用方法について説明する。

  • 球体環境マップとは
  • 球体環境マップのテクスチャ座標
  • 球体環境マップの適用


バンプ マッピング

ここでは、Direct3D でのバンプ マッピングの実行について説明する。以下のトピックでは、バンプ マッピングを紹介し、その主要な概念を特定および定義し、アプリケーションでのバンプ マッピングの使用方法について説明する。

  • バンプ マッピングとは
  • バンプ マップ ピクセル フォーマット
  • バンプ マッピングの公式
  • バンプ マッピングの使用


バンプ マッピングとは

バンプ マッピングは、少数のポリゴンだけできれいにテッセレートされたオブジェクトの反射状態をシミュレートする、特殊なスペキュラまたはディフューズ環境マッピングである。次の画像は、BumpEarth サンプルに基づいてバンプ マッピングのエフェクトを示す。

左側の地球は、地球の表面の画像でテクスチャ処理され、スペキュラ環境マップが適用されている。右側の地球もまったく同じであるが、バンプ マップが適用されている。2 つ目の地球の画像のポリゴン数は、1 つ目の画像のポリゴン数と変わらない。

Direct3D のバンプ マッピングでは、開発者はデルタ値による輪郭線の情報を提供することから、バンプ マッピングは、正確には "スペキュラまたはディフューズ環境マップのピクセル単位でのテクスチャ座標の補正" と記述できる。輪郭線の情報は、システムによって次のテクスチャ ステージの環境マップの u および v テクスチャ座標に適用される。デルタ値は、バンプ マップ サーフェスのピクセル フォーマットで符号化される。詳細については、「バンプ マップ ピクセル フォーマット」を参照すること。

BumpEarth サンプルでは、高度マップを使用して輪郭線データを格納する。サンプルを開始すると、高度マップ内のピクセルが処理されて適切な u および v が計算される (隣接する 4 つのピクセルを基準にした、各ピクセルの相対高度に基づく)。

注 : 本来、Direct3D では高度マップをサポートしていない。高度マップは、輪郭線データを格納および視覚化するのに便利なフォーマットであるにすぎない。前の画像は高度マップを基づいて作成されたもので、BumpEarth サンプルではこの高度マップを使用して、Direct3D に提供するバンプ マップを生成している。この画像は説明を目的に示したものである。アプリケーションでは輪郭線情報をどのようなフォーマットでも格納でき、また、BumpWaves サンプル のように個々のバンプ マップを生成することもできる。

次は、BumpEarth サンプルで使用する高度マップ画像である。このサンプルでは、これを使用して、バンプ マップ テクスチャのピクセル フォーマットで符号化されるデルタ値を計算する。

バンプ マッピングは、複数のテクスチャ ブレンディング サービスに完全に依存しており、デバイスは少なくとも 2 つのブレンディング ステージ (1 つはバンプ マップ用、もう 1 つは環境マップ用) をサポートしている必要がある。ベース テクスチャ マップを適用するには、最低 3 つのテクスチャ ブレンディング ステージが要求される (最も一般的な場合)。次の図は、テクスチャ ブレンディング カスケードにおける、ベース テクスチャ、バンプ マップ、および環境マップ間の関係を示す。

テクスチャ ステージを適切に用意し、バンプ マッピングを有効にする必要がある。このタスクについては、「バンプ マッピング パラメータの設定」で説明する。


バンプ マップ ピクセル フォーマット

バンプ マップとは、特殊なピクセル フォーマットを使用する DirectDraw サーフェス オブジェクトである。赤、緑、および青の色成分を格納するのではなく、バンプ マップの各ピクセルは、u および v のデルタ値 (Du および Dv) を格納し、輝度 L. を格納するときもある。これらの値は、「バンプ マッピングの公式」で説明するように、システムによって適用される。

[C++]

その他のサーフェスの場合と同様、DDPIXELFORMAT 構造体を使用してバンプ マップ ピクセル フォーマットを指定する。この構造体の dwFlags メンバの DDPF_BUMPDUDV フラグは、バンプ マップ テクスチャのピクセル フォーマットを識別する。このフラグがある場合、dwBumpBitCount、dwBumpDuBitMask、dwBumpDvBitMask、および dwBumpLuminanceBitMask メンバは、バンプ マップのビット深度および各ピクセル コンポーネントのマスク値を記述するために使用できる。

ピクセルの Du および Dv コンポーネントは、–1.0 ～ +1.0 の範囲の符号付き値である。輝度コンポーネントが使用されている場合、この値は 0 ～ 255 の範囲の符号なし整数値である。

注 : IDirect3DDevice7::EnumTextureFormats メソッドを呼び出して、サポートされているバンプ マップ ピクセル フォーマットを列挙する必要がある。詳細については、「バンプ マッピングのサポートの検出」を参照すること。

[Visual Basic]

その他のサーフェスの場合と同様、DDPIXELFORMAT 型を使用してバンプ マップ ピクセル フォーマットを指定する。この型の lFlags メンバの DDPF_BUMPDUDV フラグは、バンプ マップ テクスチャのピクセル フォーマットを識別する。このフラグがある場合、lBumpBitCount、lBumpDuBitMask、lBumpDvBitMask、および lBumpLuminanceBitMask メンバは、バンプ マップのビット深度および各ピクセル コンポーネントのマスク値を記述するために使用できる。

ピクセルの Du および Dv コンポーネントは、–1.0 ～ +1.0 の範囲の符号付き値である。輝度コンポーネントが使用されている場合、この値は 0 ～ 255 の範囲の符号なし整数値である。

注 : サポートされているバンプ マップ ピクセル フォーマットを列挙して、使用するピクセル フォーマットが有効であることを確認する必要がある。Direct3DDevice7.GetTextureFormatsEnum メソッドを呼び出して、テクスチャ フォーマットの Direct3DEnumPixelFormats 列挙クラスへの参照を取得する。この列挙を使用して、バンプ マップ フォーマットなどサポートされているテクスチャ フォーマットの情報を取得する。詳細については、「バンプ マッピングのサポートの検出」


バンプ マッピングの公式

[C++]

Direct3D では、各バンプ マップ ピクセルの Du および Dv コンポーネントに次の公式を適用する。

この公式では、Du および Dv 変数はバンプ マップ ピクセルから直接取得され、出力デルタ値 Du' および Dv' を生成するために 2×2 行列でトランスフォームされる。システムでは、この出力値を使用して、次のテクスチャ ステージの環境マップを処理するテクスチャ座標を修正する。トランスフォーム行列の係数は、D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT10、D3DTSS_BUMPENVMAT01、および D3DTSS_BUMPENVMAT11 テクスチャ ステージ ステートで設定する。

u および v デルタ値のほかにも、システムでは、次のブレンディング ステージの環境マップの色調整に使用する輝度を計算できる。

この公式では、L' は計算される出力輝度である。L 変数はバンプ マップ ピクセルから取得される輝度であり、スケーリング係数 S で乗算され、変数 O の値でオフセットされる。D3DTSS_BUMPENVLSCALE および D3DTSS_BUMPENVLOFFSET テクスチャ ステージ ステートは、公式の変数 S および O の値を制御する。この公式が適用されるのは、バンプ マップを含むステージのテクスチャ ブレンディング処理が D3DTOP_BUMPENVMAPLUMINANCE に設定されている場合のみである。D3DTOP_BUMPENVMAP を使用するときは、L' の値に 1.0 が使用される。

出力デルタ値 Du' および Dv' の計算後、システムでは、これらの値を次のテクスチャ ステージのテクスチャ座標に追加し、選択されている色の輝度を調整して、ポリゴンに適用する色を生成する。

[Visual Basic]

Direct3D では、各バンプ マップ ピクセルの Du および Dv コンポーネントに次の公式を適用する。

この公式では、Du および Dv 変数はバンプ マップ ピクセルから直接取得され、出力デルタ値 Du' および Dv' を生成するために 2×2 行列でトランスフォームされる。システムでは、この出力値を使用して、次のテクスチャ ステージの環境マップを処理するテクスチャ座標を修正する。トランスフォーム行列の係数は、D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT10、D3DTSS_BUMPENVMAT01、および D3DTSS_BUMPENVMAT11 テクスチャ ステージ ステートで設定する。

u および v デルタ値のほかにも、システムでは、次のブレンディング ステージの環境マップの色調整に使用する輝度を計算できる。

この公式では、L' は計算される出力輝度である (L' は、0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲に固定される)。L 変数はバンプ マップ ピクセルから取得される輝度であり、スケーリング係数 S で乗算され、変数 O の値でオフセットされる。D3DTSS_BUMPENVLSCALE および D3DTSS_BUMPENVLOFFSET テクスチャ ステージ ステートは、公式の変数 S および O の値を制御する。この公式が適用されるのは、バンプ マップを含むステージのテクスチャ ブレンディング処理が D3DTOP_BUMPENVMAPLUMINANCE に設定されている場合のみである。D3DTOP_BUMPENVMAP を使用するときは、L' の値に 1.0 が使用される。

出力デルタ値 Du' および Dv' の計算後、システムでは、これらの値を次のテクスチャ ステージのテクスチャ座標に追加し、選択されている色の輝度を調整して、ポリゴンに適用する色を生成する。


バンプ マッピングの使用

このセクションの以下のトピックでは、Direct3D のバンプ マッピングを使用する際に実行しなければならない最も一般的なタスクについて詳しく説明する。

  • バンプ マッピングのサポートの検出
  • バンプ マップ テクスチャの作成
  • バンプ マッピング パラメータの設定


ビルボード化

3D シーンを作成するとき、2D オブジェクトを 3D オブジェクトであるかのように表示することによってパフォーマンスを向上できることがある。この考え方が、ビルボード処理技術の基になっている。

通常の意味でのビルボードは、道路沿いの掲示板のことである。Direct3D アプリケーションは、矩形ソリッドを定義し、それにテクスチャを適用することで、この種のビルボードを簡単に作成、レンダリングできる。3D グラフィックスでの特殊な意味でのビルボードは、これを拡張したものである。この意味でのビルボード処理の目的は、2D オブジェクトを 3D オブジェクトのように見せることである。この技術は、オブジェクトの画像を含むテクスチャを矩形プリミティブに適用することである。このプリミティブは、正面が常にビューアの方を向くように回転される。このオブジェクトの画像は矩形でなくても問題ない。ビルボードの部分を透明にして、表示したくないビルボード画像の部分を不可視にすることができる。

多くのゲームで、アニメーションしたスプライトにビルボード処理が採用されている。たとえば、プレーヤーが 3D の迷路を移動するとき、収集できる武器や褒美が表示される。これらは、矩形プリミティブにテクスチャを適用した典型的な 2D 画像である。ビルボード処理は、ゲームで木や潅木の画像をレンダリングするために使用されることが多い。

ビルボードに画像を適用するときは、最初に、正面がビューアの方を向くように矩形プリミティブを回転しなければならない。次に、このプリミティブを配置場所に平行移動しなければならない。その後、このプリミティブにテクスチャを適用できる。

ビルボード処理は、対称的なオブジェクト、特に垂直軸に対して対称的なオブジェクトの処理に最適である。また、ビルボード処理には、視点の高さがあまり上がらないことが必要である。ユーザーがビルボードを上から見ることが許されている場合、そのオブジェクトが 3D ではなく 2D であることがすぐにわかってしまう。


雲、煙、蒸気

雲、煙、蒸気のたなびきも、すべて、ビルボード処理技術を拡張して作成できる (「ビルボード化」を参照すること)。1 つの軸ではなくて 2 つの軸を中心にビルボードを回転することで、ビューアがビルボードをどの角度からでも見ることができる。通常、アプリケーションでは水平軸と垂直軸を中心にビルボードを回転する。

簡単な雲を作成するため、正面がビューアの方を向くように 1 つまたは 2 つの軸を中心に矩形プリミティブを回転する。次に、雲のようなテクスチャを透明度と共にこのプリミティブに適用する。透明度のあるテクスチャのプリミティブへの適用の詳細については、「テクスチャ ブレンディング」を参照すること。雲をアニメーションするには、一連のテクスチャを連続して適用する。

プリミティブのグループで雲を形成すれば、より複雑な雲を作成できる。この場合、雲の各部分が矩形プリミティブになる。これらのプリミティブをそれぞれ独立に連続的に移動して、動的な霧のように見せることができる。次の図にこれを示す。

煙は、雲と同様の方法で表示する。通常、煙では複雑な雲のように複数のビルボードが必要である。煙は連続してうねったり、上昇するので、立ち昇る煙を形成するビルボードを移動させることが必要である。煙が上昇したり、消散するときは、ビルボードを追加しなければならないことがある。

蒸気のたなびきは、上昇しない煙のようなものである。蒸気は、立ち昇る煙のように徐々に消散する。次の図は、蒸気のたなびきをシミュレートするためにビルボードを使用する技術を示す。


火、炎、爆発など

アプリケーションは Direct3D を使用して、エネルギーを発する自然現象をシミュレーションできる。たとえば、炎のようなテクスチャをビルボード セットに適用して、火を表現できる。これが特に効果的なのは、火のテクスチャを連続的に使用して、燃えるビルボードそれぞれの上の炎をアニメーションする場合である。ビルボードごとにアニメーション再生の速度を変えると、炎のリアリティが増す。混じり合った 3D の炎に見せるには、ビルボードを重ね合わせ、ビルボード上のテクスチャを重ね合わせればよい。

閃光は、シーンのすべてのプリミティブに徐々に明るくなるライト マップを適用してシミュレーションできる。これはオーバーヘッドの高い技術であるが、局所的な炎や閃光のシミュレーションは可能である。つまり、炎や閃光を発するシーンの一部を最初に明るくすることができる。

ほかの技術としては、レンダリング ターゲット領域全体を覆うようにシーンの前面にビルボードを配置する方法がある。プログラムで徐々に白くなるテクスチャをビルボードに適用し、だんだんと透明度を減少させる。時間が経過するとシーン全体が白くなる。これは、炎を作成する方法としてはオーバーヘッドの低い方法である。しかし、この技術を使用すると、単一のポイント ライトの光源から明るい閃光を表現することが困難になることがある。

爆発は、火、閃光、および炎で使用したような 3D シーン手法によって表示できる。たとえば、プログラムでビルボードを使用して、爆発の衝撃波や噴煙を表示できる。同時に、ビルボード セットを使用して炎をシミュレートできる。さらに、シーンの前面に単一のビルボードを配置して、シーン全体に閃光を追加できる。

エネルギー ビームは、ビルボードを使用してシミュレーションできる。また、線リストまたは線ストリップとして定義したプリミティブを使用してもこのビームを表示できる。詳細については、「線リスト」および「線ストリップ」を参照すること。

ビルボードや三角形リストとして定義したプリミティブを使用して、電磁力界を作成できる。三角形リストから電磁力界を作成するには、電磁力界の範囲と同じ空間を占める三角形リストにある分離した三角形のセットを定義すること。ビューアは、三角形どうしの隙間から三角形の背後のシーンを見ることができ、あたかも電磁力界を見ているかのように感じられる。三角形がエネルギーで輝いているように見せるテクスチャを三角形リストに適用する。詳細については、「三角形リスト」および「カレント テクスチャ」を参照すること。


モーション ブラー

3D シーンのオブジェクトの知覚速度は、オブジェクトを不鮮明にすること、およびオブジェクトの後ろにオブジェクト画像の不鮮明な跡を残すことによって高めることができる。Direct3D アプリケーションは、フレームごとにオブジェクトを複数回レンダリングすることでこれを実現できる。

[Visual Basic]

通常、Direct3D アプリケーションはシーンをオフスクリーン バッファにレンダリングすることを思い出してほしい。バッファの内容は、アプリケーションで DirectDrawSurface7.Flip メソッドを呼び出したときにスクリーンに表示される。Direct3D プログラムは、スクリーンにフレームを表示する前にオブジェクトをシーンに複数回レンダリングできる。

アプリケーションで DrawPrimitive メソッドへの呼び出しを複数回行い、同じ 3D オブジェクトを繰り返し渡す。それぞれの呼び出しの前に、オブジェクトの位置座標を少し更新し、ターゲット レンダリング サーフェス上に一連の不鮮明なオブジェクト画像を生成する。オブジェクトが 1 つまたは複数のテクスチャを持っている場合、テクスチャすべてをほとんど透明にしてオブジェクトの最初の画像をレンダリングすると、モーション ブラー エフェクトを高めることができる。オブジェクトのレンダリングのたびに、オブジェクトのテクスチャの透明度が減少する。最終位置座標でオブジェクトをレンダリングするときは、透明度なしでオブジェクトをレンダリングすること。例外は、テクスチャの透明度を必要とするほかのエフェクトにモーション ブラーを追加する場合である。どの場合でも、フレームのオブジェクトの最初の画像が最も透明でなければならない。最後の画像の透明度が最も低くなければならない。

[C++]

ターゲット レンダリング サーフェスに一連のオブジェクト画像をレンダリングし、残りのシーンもレンダリングしたら、IDirectDrawSurface7::Flip メソッドを呼び出してスクリーンにフレームを表示する。

[Visual Basic]

ターゲット レンダリング サーフェスに一連のオブジェクト画像をレンダリングし、残りのシーンもレンダリングしたら、DirectDrawSurface7.Flip メソッドを呼び出してスクリーンにフレームを表示する。

ユーザーがシーンを高速で移動するエフェクトをシミュレーションする場合は、スクリーン全体にモーション ブラーを追加できる。この場合、アプリケーションはフレームごとにシーン全体を複数回レンダリングすることになる。シーンをレンダリングするたびに、視点を少し移動しなければならない。シーンが非常に複雑な場合、フレームごとのシーンのレンダリング回数が増えるので、高速に移動するシーンほどパフォーマンスが低下するのがユーザーに見える。


ステンシル バッファ技術

アプリケーションでステンシル バッファを使用して、画像のピクセルをマスクする。このマスクは、ピクセルを描画するかどうかを制御する。ステンシル バッファの詳細については、「ステンシル バッファ」を参照すること。

Direct3D アプリケーションは、ステンシル バッファを使用して広範な特殊効果を生み出すことができる。頻繁に使用されるエフェクトは以下のとおりである。これらのエフェクトがすべてではないので、注意すること。

  • ディゾルブ、フェード、およびワイプ
  • デカーリング
  • 合成
  • アウトラインとシルエット


ディゾルブ、フェード、およびワイプ

ディゾルブ、ワイプ、およびフェードなどの映画やビデオでよく使われる特殊効果をアプリケーションで利用することが増えている。

ディゾルブでは、フレームが徐々に変わることによってある画像が別の画像にスムーズに移行する。Direct3D はこれと同様のエフェクトを実現するためにマルチ テクスチャ ブレンディングを使用する方法を提供しているが、ディゾルブにステンシル バッファを使用するアプリケーションは、ディゾルブの実行中にこのテクスチャ ブレンディング機能をほかのエフェクトに利用できる。

ディゾルブを実行するとき、アプリケーションは 2 つの異なる画像をレンダリングしなければならない。アプリケーションはステンシル バッファを使用して、レンダリング ターゲット サーフェスに各画像のどのピクセルを描画するのかを制御する。一連のステンシル マスクを定義して、連続するフレームのステンシル バッファにこれらのマスクをコピーできる。別の方法として、最初のフレーム用の基本ステンシル マスクを定義し、このマスクを増分して変更することもできる。

ディゾルブの最初で、最初の画像のほとんどのピクセルがテストにパスするようにステンシル関数とステンシル マスクをアプリケーションで設定する。最後の画像のほとんどのピクセルは、ステンシル テストに失敗しなければならない。フレームが続くにつれて、最初の画像のピクセルでテストにパスするピクセルが徐々に少なくなるように、ステンシル マスクを更新する。フレームが続くにつれて、最後の画像のピクセルでテストに失敗するピクセルが徐々に少なくなる。このように、任意のディゾルブ パターンを使用してディゾルブを実行できる。

フェード インまたはフェード アウトは、ディゾルブの特殊なケースである。フェード インするときは、ステンシル バッファを使用して、黒色の (または白色の) 画像から 3D シーンのレンダリングにディゾルブする。フェード アウトはこれと逆で、3D シーンのレンダリングから始まって、黒色の (または白色の) 画像にディゾルブする。フェードには、どのようなパターンでも使用できる。

Direct3D アプリケーションは、ワイプにも同様な技術を使用する。たとえば、アプリケーションは左から右へのワイプを実行する。最後の画像は、最初の画像の上に徐々にスライドするように左から右に移動する。ディゾルブの場合と同様、連続フレームのステンシル バッファにロードする一連のステンシル マスクを定義するか、続けて最初のステンシル マスクを修正する必要がある。このステンシル マスクは、最初の画像のピクセルの書き込みを無効にし、最後の画像のピクセルの書き込みを有効にするために使用する。

ワイプの順序とは逆の順序で最後の画像のピクセルを読み出さなければならないという点で、ワイプはディゾルブよりも少し複雑である。つまり、ワイプが左から右に移動する場合、アプリケーションは最後の画像のピクセルを右から左に読み出さなければならない。


デカーリング

Direct3D アプリケーションは、デカーリング技術を使用して、レンダリング ターゲット サーフェスに特定のプリミティブのどのピクセルを描画するかを制御する。プログラムでデカールをプリミティブの画像に適用して、同一平面上のポリゴンを正しくレンダリングできるようにする。

たとえば、タイヤの跡と黄色の線を道路に適用するとき、この跡は直接道路の上に表示しなければならない。しかし、この跡と道路の z 値は同一である。したがって、深度バッファでは、両者をはっきりと区別できない。背後のプリミティブのピクセルが前面のプリミティブ上にレンダリングされたり、その逆のレンダリングが行われる場合がある。この結果、画像はフレームごとに揺れる。このエフェクトを "Z ファイティング" または "フリマリング" と呼ぶ。

この問題を解決するには、ステンシルを使用して、デカールが表示される背面プリミティブの部分のマスクを外す。z バッファリングをオフにして、レンダリング ターゲット サーフェスのマスクで覆っている領域に前面プリミティブの画像をレンダリングする。

マルチ テクスチャ ブレンディングを使用してこの問題を解決することもできるが、この方法を使用すると、アプリケーションで生成できる他の特殊効果の数が制限される。ステンシル バッファを使用してデカールを適用すると、ほかのエフェクトに対するテクスチャ ブレンディング ステージの制限が解放される。


合成

アプリケーションでステンシル バッファを使用して、2D または 3D 画像を 3D シーンに合成できる。ステンシル バッファのマスクを使用して、レンダリング ターゲット サーフェスの領域を遮蔽する。次に、テキストやビットマップなどの格納 2D 情報を遮蔽領域に書き込むことができる。別の方法として、追加 3D プリミティブをレンダリング ターゲット サーフェスのステンシル マスクされた領域にレンダリングできる。この場合、シーン全体をレンダリングすることもできる。

ゲームでは、複数の 3D シーンを合成することが多い。たとえば、運転ゲームでは通常バックミラーを表示する。バックミラーには、運転者の背後の 3D シーンの表示が含まれる。したがって、バックミラーは、本質的には運転者の前方の風景と合成された 第 2 の 3D シーンと言える。


アウトラインとシルエット

ステンシル バッファは、アウトラインやシルエットなどのより抽象的なエフェクトに使用することもできる。

プログラムで、プリミティブと同じ形状であるが少し小さいステンシル マスクをプリミティブの画像に適用すると、画像はプリミティブのアウトラインだけになる。次に画像のステンシル マスクをした領域を一様な色で埋めて、プリミティブが浮き上がって見えるようにすることができる。

レンダリングするプリミティブとステンシル マスクが同じサイズで同じ形状である場合、本来プリミティブが存在する場所に "穴" ができる。この "穴" を黒色で埋めると、プリミティブのシルエットを生成できる。


カラー ライティング

[C++]

D3DLIGHT7 構造体 (dcvDiffuse、dcvSpecular、dcvAmbient) の色に関連するメンバは、D3DCOLORVALUE 構造体である。これらの構造体で定義する色は、一般には 0 ～ 1 の範囲の RGBA 値であり、0 が黒に相当する。たいていは光色がこの範囲になるようにするが、特殊効果をねらうときには、この範囲外の値を使用することもできる。たとえば、大きな値の色を設定して、シーンを台なしにするほど強い光を作ることができる。また、色を負の値に設定して、暗色光を作ることができる。暗い光は、シーンで劇的な影を強めたりその他のエフェクトに有用である。

[Visual Basic]

D3DLIGHT7 型 (diffuse、specular、ambient) の色に関連するメンバは、D3DCOLORVALUE 型である。これらの型で定義する色は、一般には 0 ～ 1 の範囲の RGBA 値であり、0 が黒に相当する。たいていは光色がこの範囲になるようにするが、特殊効果をねらうときには、この範囲外の値を使用することもできる。たとえば、大きな値の色を設定して、シーンを台なしにするほど強い光を作ることができる。また、色を負の値に設定して、暗色光を作ることができる。暗い光は、シーンで劇的な影を強めたりその他のエフェクトに有用である。


アンチエイリアシング

アンチエイリアシングとは、"ギザギザ" (正確に水平または垂直でない線を描く場合に使用される階段状のピクセル) を減らすために使用する技法のことである。3 次元シーンの場合、この不自然な効果は異なる色のポリゴン間の境界線上でもっとも目立つ。アンチエイリアシングは、ピクセルを効果的に境界線上でブレンドして、シーンの外観をより自然にする。

Direct3D でサポートするアンチエイリアシング技術は、エッジ アンチエイリアシングおよびフルシーン アンチエイリアシングの 2 種類がある。どちらのアンチエイリアシングがアプリケーションによいかは、パフォーマンスと視覚的品質の要件に依存する。

  • エッジ アンチエイリアシング
  • フルシーン アンチエイリアシング

注 : アプリケーションでアンチエイリアシングを使用する場合は、DDSCAPS2_HINTANTIALIASING フラグでレンダリング ターゲット サーフェスを作成する必要がある。このフラグを省略すると、アンチエイリアシングを有効にしたときにパフォーマンスが低下したり、アンチエイリアシングが実行されないことがある。


エッジ アンチエイリアシング

エッジ アンチエイリアシングでは、シーンをレンダリングした後、オブジェクトの凸状シルエットを線にアンチエイリアシングするために再レンダリングする。システムは辺を再描画し、ぼかして、不自然な効果を縮小する。

[C++]

デバイスがエッジ アンチエイリアシングをサポートしている場合は、D3DPRIMCAPS 構造体 (IDirect3DDevice7::GetCaps メソッドを呼び出して設定する) に D3DPRASTERCAPS_ANTIALIASEDGES 能力フラグが公開される。この場合、D3DRENDERSTATE_EDGEANTIALIAS レンダリング ステートを TRUE に設定し、次に IDirect3DDevice7::DrawPrimitive、および D3DPT_LINESTRIP または D3DPT_LINELIST プリミティブ タイプのいずれかを使用して、シーン内のエッジのみ再描画する。エッジ アンチエイリアシングの動作は、線以外のプリミティブについては定義されていないため、アンチエイリアシングが完了したら、D3DRENDERSTATE_EDGEANTIALIAS を FALSE に設定して機能を確実に無効にする。

[Visual Basic]

デバイスがエッジ アンチエイリアシングをサポートしている場合は、D3DPRIMCAPS 型 (Direct3DDevice7.GetCaps メソッドを呼び出して設定する) に D3DPRASTERCAPS_ANTIALIASEDGES 能力フラグが公開される。この場合、D3DRENDERSTATE_EDGEANTIALIAS レンダリング ステートを True に設定して、次に Direct3DDevice7.DrawPrimitive、および D3DPT_LINESTRIP または D3DPT_LINELIST プリミティブ タイプのいずれかを使用して、シーン内のエッジのみ再描画する。エッジ アンチエイリアシングの動作は、線以外のプリミティブについては定義されていないため、アンチエイリアシングが完了したら、D3DRENDERSTATE_EDGEANTIALIAS を False に設定して機能を確実に無効する。

シーンの中のすべてのエッジを再描画すると、大きな不自然な効果を生じさせずにすむが、計算量が膨大になる。また、この方法ではどのエッジをアンチエイリアシングするべきか判断が困難なこともある。再描画するのにもっとも重要なエッジは、非常に異なる色の領域の間のエッジ (たとえば影のエッジ)、または非常に異なるマテリアルの間の境界である。ほぼ同じ色の 2 つのポリゴンの間のエッジをアンチエイリアシングすることは、エフェクトがないわりに計算量は膨大である。こうした理由により、現在のハードウェアがサポートする場合は、フルシーン アンチエイリアシングが好ましいことが多い。詳細については、「フルシーン アンチエイリアシング」を参照すること。


フルシーン アンチエイリアシング

フルシーン アンチエイリアシングとは、シーン内の各ポリゴンのエッジをシングル パスでラスタライズしてぼかすことを指す。2 つめのパスは必要ない。フルシーン アンチエイリアシングは (サポートされている場合)、三角形および三角形のグループにのみ影響する。Direct3D サービスを使用して、線にアンチエイリアシングを適用することはできない。

[C++]

ハードウェアによっては、ソートしたポリゴンをアプリケーションが後ろから前へレンダリングするときだけしか、フルシーン アンチエイリアシングを適用できない。これが現在のデバイスに当てはまるかどうかを調べるには、IDirect3DDevice7::GetCaps メソッドを呼び出してデバイス機能を取得する。呼び出した後で、関連付けられた D3DPRIMCAPS 構造体の dwRasterCaps メンバをチェックする。デバイスがアンチエイリアシングに対して後ろから前へのレンダリングを要求している場合は、D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT 能力フラグが dwRasterCaps に示されている。ポリゴンの順序にかかわらずデバイスがアンチエイリアシングを行える場合は、D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT フラグが示されている。どちらのフラグもない場合は、デバイスがフルシーン アンチエイリアシングを行えないことを示す。

ポリゴンをソートする必要があるかどうか調べた後で、D3DRENDERSTATE_ANTIALIAS レンダリング ステートを D3DANTIALIAS_SORTDEPENDENT または D3DANTIALIAS_SORTINDEPENDENT にセットして、シーンを描画する。

フルシーン アンチエイリアシングが必要なくなったら、D3DRENDERSTATE_ANTIALIAS を D3DANTIALIAS_NONE に設定して無効にする。

[Visual Basic]

ハードウェアによっては、ソートしたポリゴンをアプリケーションが後ろから前へレンダリングするときだけしか、フルシーン アンチエイリアシングを適用できない。これが現在のデバイスに当てはまるかどうかを調べるには、Direct3DDevice7.GetCaps メソッドを呼び出してデバイス機能を取得する。この呼び出しの後、関連付けられている D3DPRIMCAPS 型の lRasterCaps メンバを調べる。デバイスが後方から前方へのレンダリングをアンチエイリアシングに要求している場合は、D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT 能力フラグが lRasterCaps に公開される。ポリゴンの順序にかかわらずデバイスがアンチエイリアシングを実行できる場合は、D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT フラグが公開される。どちらのフラグもない場合は、デバイスがフルシーン アンチエイリアシングを行えないことを示す。

ポリゴンをソートする必要があるかどうかを調べた後、D3DRENDERSTATE_ANTIALIAS レンダリング ステートを D3DANTIALIAS_SORTDEPENDENT または D3DANTIALIAS_SORTINDEPENDENT に設定して、シーンを描画する。

フルシーン アンチエイリアシングが必要なくなったら、D3DRENDERSTATE_ANTIALIAS を D3DANTIALIAS_NONE に設定して無効にする。


GUID

[C++]

Direct3D では、グローバル ユニーク識別子 (GUID) を使用して、インターフェイスの各部を識別する。QueryInterface メソッドを使用して、オブジェクトがインターフェイスをサポートしているかどうか確かめるには、対象となるインターフェイスを、その GUID を使用して特定する｡

GUID をアプリケーションでうまく使用するには、そのほかすべての include および define 文に先立って INITGUID を定義するか、または DXGUID.LIB ライブラリをリンクしなければならない。INITGUID は、ソース モジュールのどれか 1 つだけで定義する｡

GUID は、アプリケーションが C または C++ のどちらで書かれているかによって使い方が違うので注意する。C の場合は、GUID (たとえば、&IID_IDirect3D) にポインタを渡すが、C++ では参照を渡す (単に IID_IDirect3D)。

[Visual Basic]

DirectX のその他のコンポーネントと同様、Direct3D コンポーネントはグローバル ユニーク識別子、つまり GUID (globally unique identifiers) を使用して API の各部を識別する。DirectX for Visual Basic では、GUID が必要な場合、たとえば、DirectX7.DirectDrawCreate メソッドを呼び出して DirectDraw7 オブジェクトを作成する場合は GUID を文字列として使用する。

詳細については、「GUID の使用」を参照すること。


パフォーマンスの最適化

3D グラフィックスを使ったリアルタイム アプリケーションを作成する開発者なら、だれでもパフォーマンスの最適化に関心がある。このセクションでは、コードから最高のパフォーマンスを得るためのガイドラインを示す。

以下のセクションのガイドラインは、あらゆる Direct3D アプリケーションに適用できる。

  • データベースとカリング
  • プリミティブのバッチ処理
  • ライティングのヒント
  • テクスチャのサイズ
  • 一般的なパフォーマンスのヒント
  • Z バッファのパフォーマンス


データベースとカリング

信頼性の高いオブジェクトのデータベースを構築することは、Direct3D の優れたパフォーマンスを得るキーになる。これは、ラスタ化やハードウェアの改良よりも重要である。

管理可能な最低のポリゴン数を維持しなければならない。少数ポリゴンの設計では、最初はポリゴンの少ないモデルを作り、開発プロセスの後半にパフォーマンスを犠牲にしなくてもできそうだと感じたらポリゴンを追加する。ポリゴンの総数は 2,500 近辺を維持するようにする。"最速のポリゴンは描画しないポリゴン" であることを忘れないこと。


プリミティブのバッチ処理

実行中に最高のレンダリング パフォーマンスを得るには、プリミティブをバッチ処理し、レンダリング ステートの変更をできるだけ少なくする。たとえば、2 つのテクスチャを持つオブジェクトがあるとき、まず最初のテクスチャを使う三角形をグループ化し、続いて、テクスチャを変更するのに必要なレンダリング ステートを設定する。そして、2 番目のテクスチャを使う三角形をすべてグループ化する。Direct3D をサポートする最も単純なハードウェアでは、ハードウェア アブストラクション レイヤ (HAL) を通して、レンダリング ステートやプリミティブのバッチ処理を行う。バッチ命令が効率的であるほど、実行中に HAL が呼び出されることが少なくなる


ライティングのヒント

ライティングは、各レンダリング フレームで全頂点で負荷がかかるので、アプリケーションでのライトの使用に細心の注意を払うことで、大幅なパフォーマンスの向上を達成することができる。以下にあげるヒントの大部分は、"もっとも速いコードは、決して呼び出されることのないコードである" という標語から導かれたものである。

  • 光源の使用をできるだけ控える。全体的レベルのライティングだけでよい場合は、新しい光源を追加するのではなく、アンビエント ライトを使用する (負荷が軽い)。
  • ディレクショナル ライトの方が、ポイント ライトやスポット ライトよりも負荷が軽い。ディレクショナル ライトの場合、光の進行方向は一定であり、頂点ごとに計算する必要はない。
  • スポット ライトの方が、ポイント ライトよりも負荷が軽い。光のコーンの外側領域の計算がすばやくできるからである。スポット ライトの方が負荷が軽いかどうかは、どれだけのシーンをスポット ライトで照射するかで決まる。
  • 照射する必要がある部分のみに光を制限するために範囲パラメータを使用する。すべてのライト タイプは、範囲外になるとかなり早く出て行く。
  • スペキュラ ハイライトは負荷がほぼ倍増するため、必要なときにのみ使用する。D3DRENDERSTATE_SPECULARENABLE レンダリング ステートは、できる限り 0 (デフォルト値) に設定しておく。マテリアルを定義するときは、スペキュラ強度値をゼロに設定して、マテリアルのスペキュラ ハイライトをオフする必要がある。スペキュラ色を 0,0,0 に設定するだけでは不十分である。


テクスチャのサイズ

テクスチャ マッピングのパフォーマンスは、メモリの速度に大きく依存する。テクスチャのキャッシュ パフォーマンスを最大にするには、たくさんの方法が考えられる。

  • テクスチャを小さくする。テクスチャが小さいほど、メインの CPU のセカンダリ キャッシュに保持される可能性が高くなる。
  • プリミティブごとにテクスチャを変更しない。また、使用するテクスチャの順にポリゴンをグループ化しておく。
  • できる限り正方形のテクスチャを使用する。寸法が 256x256 のテクスチャが最速である。たとえば、128x128 のテクスチャを 4 つ使用する場合は、同じパレットを使用し、それらのテクスチャを 1 つの 256x256 のテクスチャに収めるようにする。このテクニックによって、テクスチャ スワッピングの回数を減らすこともできる。アプリケーションで少数のテクスチャしか必要でない場合は、256x256 のテクスチャは使用しない。既に説明したように、テクスチャはできるだけ小さくした方がよいからである。


一般的なパフォーマンスのヒント

いくつかの一般的なガイドラインに従えば、アプリケーションのパフォーマンスを高めることができる。

  • 必要なときだけクリアする。
  • ステートの変化を最小限にする。
  • 必要なときだけ透視修正を使う。
  • 可能なら小さなテクスチャを使う。
  • 不相応なシステム リソースの共有が必要な特殊効果は目立たないように弱める。
  • アプリケーションのパフォーマンスを常にテストする。
  • アプリケーションが、ハードウェア アクセラレーションとソフトウェア エミュレーションの両方で良好に動作するようにする。


Z バッファのパフォーマンス

ランプ ドライバを使用するアプリケーションでは、シーンが前から後ろへレンダリングされるように、z バッファリングを使ってテクスチャを処理すると、パフォーマンスを向上させることができる。テクスチャを適用し、Z バッファを利用したプリミティブでは、基準となるスキャンライン上で Z バッファについてのプレテストが行われる。前もってレンダリングされたポリゴンのスキャンラインが隠れている場合は、システムがポリゴンを高速かつ効率的に取り除く。z バッファリングによってパフォーマンスは改善されるが、この手法はシーンで何度もオーバードローが必要なときに最も効果的である。オーバードローとは、スクリーン ピクセルの平均描画回数である。オーバードローを正確に計算するのは難しいが、近似値を求めることは可能である。オーバードローの平均が 2 よりも小さいときは、z バッファリングをオフにし、背面から前面にシーンをレンダリングすれば最高のパフォーマンスが得られる。

[C++]

レンダリングの前に表示テストを実行して、アプリケーションのパフォーマンスを改善することもできる。Direct3D 直接モードには、これを行うための IDirect3DDevice7::ComputeSphereVisibility メソッドがある。ComputeSphereVisibility メソッドは、指定されたポリゴン セットについての情報を提供する。このメソッドによって、ジオメトリが表示不能であることが通知された場合は、オブジェクトのレンダリングを回避することもできる。

[Visual Basic]

レンダリングの前に表示テストを実行して、アプリケーションのパフォーマンスを改善することもできる。Direct3D 直接モードには、これを行うための Direct3DDevice7.ComputeSphereVisibility メソッドがある。ComputeSphereVisibility メソッドは、指定されたポリゴン セットについての情報を提供する。このメソッドによって、ジオメトリが表示不能であることが通知された場合は、オブジェクトのレンダリングを回避することもできる。

高速のパーソナル コンピュータでは、ソフトウェア的にシステム メモリにレンダリングした方が、ビデオ メモリへのレンダリングよりも速いことが少なくない。ただし、この場合は、ダブル バッファリングやハードウェア アクセラレータによるクリア処理を使用できないというデメリットがある。システム メモリにもビデオ メモリにもレンダリングすることができ、どちらが高速かをテストするルーチンがあれば、アプリケーションでは、現行システムで最適な手法を利用できる。この SDK の Direct3D サンプル コードでは、この方法を実現している。ただし、スピードをテストする方法が他にないので、この両方の手順を実現する必要がある。コンピュータによってスピードはまったく異なり、メイン メモリのアーキテクチャや使用されているグラフィックス アダプタの種類に依存する。


トラブルシューティング

ここでは、Direct3D プログラムを作成するときによく経験する共通カテゴリの問題点と、それを防ぐための方法を記述する。

  • デバイスの作成
  • ライティング済みの頂点の使用
  • 何も表示されない
  • デバッグ
  • ボーランド浮動小数点の初期化
  • パラメータ妥当性の検証


デバイスの作成

デバイスの生成中にアプリケーションが失敗した場合は、以下のようなエラーがないかどうかを調べる。

  • DirectDraw サーフェスを作成するとき、DDSCAPS_3DDEVICE を指定しているか。
  • パレット化したデバイスを使うとき、パレットをアタッチしているか。
  • Z バッファを使うとき、レンダリング ターゲットにアタッチしているか。
  • デバイスの能力、特にレンダリングの深度を確実にチェックしているか。
  • システム メモリとビデオ メモリのどちらを使っているのか。
  • レジストリが壊れていないか。


ライティング済みの頂点の使用

[C++]

D3DLVERTEX 構造体に類似する、ライティング済みの頂点を使用するアプリケーションでは、D3DRENDERSTATE_LIGHTING レンダリング ステートを FALSE に設定して Direct3D ライティング エンジンを無効にする必要がある。デフォルトでは、ライティングが有効になっている場合、入力頂点にゼロ以外のカラー値が含まれていても、法線ベクトルを含んでいない頂点の色は 0 (黒) に設定される。D3DLVERTEX などライトを当てた頂点は、本来、頂点法線を含んでいないため、ライティング エンジンが有効になっていると Direct3D に渡される色情報がレンダリング時に失われる。

独自のライティングを実行するアプリケーションにとっては、頂点色が重要な要素であることは明らかである。デフォルト値の使用を避けるために、D3DRENDERSTATE_LIGHTING を FALSE に設定すること。

[Visual Basic]

D3DLVERTEX 型に類似する、ライティング済みの頂点を使用するアプリケーションでは、D3DRENDERSTATE_LIGHTING レンダリング ステートを FALSE に設定して Direct3D ライティング エンジンを無効にする必要がある。デフォルトでは、ライティングが有効になっている場合、入力頂点にゼロ以外のカラー値が含まれていても、法線ベクトルを含んでいない頂点の色は 0 (黒) に設定される。D3DLVERTEX などライトを当てた頂点は、本来、頂点法線を含んでいないため、ライティング エンジンが有効になっていると Direct3D に渡される色情報がレンダリング時に失われる。

独自のライティングを実行するアプリケーションにとっては、頂点色が重要な要素であることは明らかである。デフォルト値の使用を避けるために、D3DRENDERSTATE_LIGHTING を False に設定すること。


何も表示されない

アプリケーションは動作しているのに何も表示されない場合は、以下のようなエラーがないかどうか調べる。

  • 三角形が変質していないか。
  • 三角形がカリングされていないか。
  • トランスフォームに内部的な矛盾がないか。
  • 三角形が表示されるようにビューポート設定が指定されているかどうかを調べる。


デバッグ

[Visual Basic]

注 : ここでは、C または C++ でのアプリケーション開発について説明する。

[C++]

Direct3D アプリケーションのデバッグは難しいかもしれない。すべての返り値を調べる (Direct3D プログラミングの中でも特に大切なことであり、ハードウェア実装に違いによって大きく異なる) ほかにも、以下の手法を試してみる。

  • デバッグ DLL に切り換える。
  • 強制的にソフトウェア オンリー デバイスにして、使用可能でもハードウェア アクセラレーションを停止する。
  • サーフェスを強制的にシステム メモリに入れる。
  • ウィンドウで動作するオプションを作成し、内蔵されたデバッガを使えるようにする。

前のリストにある 2 番目と 3 番目のオプションは、Win16 のロックを防ぐのに役に立つ。そうしないと、デバッガがハングすることがある。

また、以下のエントリを WIN.INI に追加してみる。

[Direct3D]
debug=3
[DirectDraw]
debug=3


ボーランド浮動小数点の初期化

[Visual Basic]

注 : ここでは、C または C++ でのアプリケーション開発について説明する。

[C++]

Borland 社製のコンパイラは、Direct3D と互換性のない方法で浮動小数点の例外を報告する。この問題を解決するには、次のように _matherr() 例外ハンドラをインクルードしなければならない。

// Borland 浮動小数点の初期化
#include <math.h>
#include <float.h>

void initfp(void)
{
// 浮動小数点の例外を無効にする。
    _control87(MCW_EM,MCW_EM);
}

int _matherr(struct _exception  *e)
{
e;               // 警告を受け取るダミー参照
return 1;    // エラー処理は終わった
}


パラメータ妥当性の検証

[Visual Basic]

注 : ここでは、C または C++ でのアプリケーション開発について説明する。

[C++]

パフォーマンス上の理由により、Direct3D 直接モードのデバッグ バージョンはリテール バージョンより頻繁に、実行時のパラメータ妥当性検証を行う。リテール バージョンは妥当性検証をまったく行わないこともある。Debug 版の妥当性検証を利用すれば、低速のデバッグ ランタイム コンポーネントで堅牢なデバッグを実行した後で、Retail 版を使用してパフォーマンスを調整し、最終リリースを実現できる。

いくつかの Direct3D 直接モード メソッドが受け取ることができる値には制限があるにもかかわらず、これらの制限は Direct3D 直接モード ランタイムのデバッグ バージョンがチェックし強制するだけであることが多い。アプリケーションは、これらの制限を順守しなければならない。そうしないと、Direct3D のリテール バージョンを実行したときに、予期できない (また、非常に好ましくない) 結果が発生することがある。たとえば、IDirect3DDevice7::DrawPrimitive メソッドが受け取るパラメータ (dwVertexCount) は、メソッドがレンダリングする頂点の数を示す。メソッドが受け取ることができるのは 0 から 65,535 (0x0000 から 0xFFFF) の間の値だけである。Direct3D のデバッグ バージョンで 65,536 (制限より 1 大きい) を渡すと、メソッドは失敗し、エラー ログにエラー メッセージを書き出し、アプリケーションにエラー値を返す。しかし、リテール バージョン ランタイムを実行中に同じエラーが発生した場合は、動作は予測できない。パフォーマンス上の理由により、メソッドはパラメータを検証しないため、パラメータが有効でない場合は、結果は完全な状況依存で予測できない動作となる。ある場合には呼び出しが動作し、別の場合には呼び出しによって Direct3D のメモリに障害が発生する。無効な呼び出しが特定のハードウェア構成と DirectX バージョンで正常に動作することもあるが、他のハードウェアまたは将来のリリースの DirectX でも機能が継続する保証はない。

Retail 版の Direct3D 直接モード ランタイムでの実行中に、説明できないようなエラーが発生した場合は、Debug 版でテストして、アプリケーションが無効なパラメータを渡していないかどうかを詳しく調べる。


Direct3D 直接モード チュートリアル

ここでは、Direct3D® 直接モードの基本的な機能を C/C++ または Visual Basic アプリケーションに実装する方法についてステップ バイ ステップで説明するチュートリアルを提供する。各チュートリアルは、この SDK の \Samples\Multimedia\D3DIM\Tutorials ディレクトリで提供される一連のサンプル ファイルと対応し、コードの流れに沿って説明する。サンプル コードを参照しながらチュートリアルを読み進めていくことを勧める。

  • Direct3D 直接モードの C/C++ チュートリアル
  • Direct3D 直接モード Visual Basic チュートリアル


Direct3D 直接モードの C/C++ チュートリアル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

ここでは、Direct3D を使用する方法について、共通のタスクの各タスクを必要なステップに分けて説明する。場合によっては、理解しやすくするために、ステップがさらに細かいステップに分かれている。次のチュートリアルを提供する。

  • チュートリアル 1 : 単一の三角形をレンダリングする
  • チュートリアル 2 : 深度バッファを追加する
  • チュートリアル 3 : さまざまなプリミティブ スタイルを使用する
  • チュートリアル 4 : デバイス列挙を使用する
  • チュートリアル 5 : テクスチャ マップを使用する

注 : 各チュートリアルのサンプル ファイルは C++ で記述されている。C コンパイラを使用している場合、サンプル ファイルに適切な変更を加えて、エラーなくコンパイルできるようにしなければならない。少なくとも、インターフェイス メソッドには、vtable ポインタと this ポインタを追加する必要がある。

添付されているサンプル コード中のコメントには、SDK のソース ファイルとは異なるものもある。変更は、コードの動作が変わるのを避けるため、コメントだけに限定し、簡潔にするためだけに行っている。


チュートリアル 1 : 単一の三角形をレンダリングする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

Direct3D を使用するには、まず、アプリケーション ウィンドウを作成した後、DirectDraw® と Direct3D 関連オブジェクトを作成し、初期化する。ユーザーは、オブジェクトが実装している COM インターフェイスを使用してオブジェクトを処理し、シーンのレンダリングに必要な従属オブジェクトを生成する。このチュートリアルで使用するサンプル プロジェクト Triangle は、最も単純なシーンである。単一の三角形をレンダリングするタスクを通してこれらのタスクを具体的に示す。サンプル プロジェクト Triangle では、次のステップを使用して、Direct3D をセット アップし、シーンをレンダリングして、最後にシャット ダウンを行う。

  • ステップ 1 : ウィンドウを作成する
  • ステップ 2 : システム オブジェクトを初期化する
  • ステップ 3 : シーンを初期化する
  • ステップ 4 : システム メッセージを監視する
  • ステップ 5 : シーンをレンダリングおよび表示する
  • ステップ 6 : シャットダウン

上記のステップに加えて、Triangle では、ウィンドウ アプリケーションに共通する標準的なタスクをいくつか実行する。このタスクは難しいものではない。サンプル Triangle (および、ほかのすべてのウィンドウ アプリケーションのサンプル) では、必要に応じて次のタスクを実行している。

  • ウィンドウの移動を処理する
  • ウィンドウのサイズ変更を処理する


ステップ 1 : ウィンドウを作成する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

いずれの Windows アプリケーションでも、実行時に、まず行わなければならないことは、アプリケーション ウィンドウを作成し、ユーザー インターフェイスを表示することである。これに従い、Triangle では、WinMain 関数の実行開始時に、次のコードを使用してウィンドウの初期化を実行している。

INT WINAPI WinMain( HINSTANCE hInst, HINSTANCE, LPSTR strCmdLine, INT )
{
    // ウィンドウ クラスを登録する。
    WNDCLASS wndClass = { CS_HREDRAW | CS_VREDRAW, WndProc, 0, 0, hInst,
                          LoadIcon( hInst, MAKEINTRESOURCE(IDI_MAIN_ICON)),
                          LoadCursor(NULL, IDC_ARROW),
                          (HBRUSH)GetStockObject(WHITE_BRUSH), NULL,
                          TEXT("Render Window") };
    RegisterClass( &wndClass );

    // メイン ウィンドウを作成する。
    HWND hWnd = CreateWindow( TEXT("Render Window"),
                              TEXT("D3D Tutorial: Drawing One Triangle"),
                              WS_OVERLAPPEDWINDOW, CW_USEDEFAULT,
                              CW_USEDEFAULT, 300, 300, 0L, 0L, hInst, 0L );
    ShowWindow( hWnd, SW_SHOWNORMAL );
    UpdateWindow( hWnd );

上記のコードは、標準的な Windows プログラミングであり、ここでは主に、全体を説明するために記述している。このサンプルでは、最初に、"Render Window" というウィンドウ クラスの定義および登録を行っている。このウィンドウ クラスは、サイズ イベントによって再描画を行い、リソースとしてアプリケーション提供アイコンを使用し、バックグラウンドを白色にするよう定義されている。クラスの登録後、サンプル コードは、登録クラスを使用する基本的な最上位レベルのウィンドウを作成する。このウィンドウは、幅 300 ピクセル、高さ 300 ピクセルのクライアント領域を持ち、メニューと子ウィンドウは持たない。このサンプルでは、WS_OVERLAPPEDWINDOW ウィンドウ スタイルを使用して、ウィンドウ アプリケーションに共通する [最小化]、[最大化]、および [閉じる] ボックスの付いたウィンドウを作成する。(サンプルをフルスクリーン モードで実行する場合は、ウィンドウ スタイル に WS_EX_TOPMOST を使用するとよい)。このウィンドウが作成されると、サンプル コードは Win32® 標準関数を呼び出して、ウィンドウの表示と更新を行う。

アプリケーション ウィンドウの準備が終了すると、DirectX® の主要オブジェクトのセット アップを開始することができる。これが、「ステップ 2 : システム オブジェクトを初期化する」の説明内容である。


ステップ 2 : システム オブジェクトを初期化する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーション ウィンドウを作成すると、DirectX プライマリ オブジェクトの初期化を開始できる。このオブジェクトのサービスを利用して、シーンのレンダリングを行う。Direct3D アプリケーションにとって、初期化とは、DirectDraw、レンダリング サーフェス、レンダリング デバイス、およびビューポートを作成および構成することを意味する。理解しやすくするため、サンプル Triangle では、システム オブジェクト初期化コードとシーン初期化コードを別々にしている。その結果、ジオメトリ、アプリケーションに特有なデータ構造体、マテリアルなどの Direct3D のセカンダリ オブジェクトが、シーンと共に初期化されている。これは必須ではなく、コードをより簡単にするために行ったものである。

サンプル Triangle は、ウィンドウの作成後に、アプリケーション定義関数 Initialize3Denvironment を WinMain から呼び出してシステム初期化を実行する。そうしたオブジェクトの準備は複雑ではないが、コードはやや長くなり、1 個所だけで説明することはできない。そこで、Initialize3Denvironment 関数がとるステップを以下に示す。

  • ステップ 2.1 : DirectDraw を初期化する
  • ステップ 2.2 : DirectDraw サーフェスをセットアップする
  • ステップ 2.3 : Direct3D を初期化する
  • ステップ 2.4 : ビューポートを準備する

注 : サンプル コード Triangle は、WM_CREATE などのシステム生成メッセージに応答するのではなく、アプリケーション ウィンドウの作成直後に WinMain 関数の内部からメソッドを呼び出して初期化を行う。これは、プラットフォーム間で異なる可能性のあるシステム メッセージの指示に依存するのを避けるためである。


ステップ 3 : シーンを初期化する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

Direct3D に関連するプライマリ オブジェクトの DirectDraw オブジェクト、レンダリング デバイス、およびビューポートを作成したら、次はジオメトリの設定、マテリアルの準備、およびアプリケーションで使用するトランスフォーム行列の設定を行い、シーンの初期化を開始する。サンプル Triangle では、アプリケーション定義関数の App_InitDeviceObjects を使用し、シーンを初期化する次のステップを実行している。

  • ステップ 3.1 : ジオメトリを準備する
  • ステップ 3.2 : マテリアルと初期ライティング ステートをセット アップする
  • ステップ 3.3 : 座標トランスフォーム行列を準備、設定する


ステップ 4 : システム メッセージを監視する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーション ウィンドウの作成および DirectX オブジェクトの作成に続き、シーンの初期化を終了すると、いつでもシーンをレンダリングできる状態になる。通常、Windows アプリケーションはメッセージ ループのシステム メッセージを監視し、キューにメッセージがなければいつでもフレームのレンダリングを行う。サンプル Triangle も、同じようにメッセージ ループに対して次のコードを使用する。

    BOOL bGotMsg;
    MSG  msg;
    PeekMessage( &msg, NULL, 0U, 0U, PM_NOREMOVE );
    g_bReady = TRUE;

    while( WM_QUIT != msg.message  )
    {
        // アプリケーションがアクティブな場合は、PeekMessage() を使用する。これにより、アイドル時間を使用して、
        // シーンのレンダリングをすることができる。それ以外の場合には、GetMessage() を使用して、CPU 時間の浪費を避ける。
        if( g_bActive )
            bGotMsg = PeekMessage( &msg, NULL, 0U, 0U, PM_REMOVE );
        else
            bGotMsg = GetMessage( &msg, NULL, 0U, 0U );

        if( bGotMsg )
        {
                TranslateMessage( &msg );
                DispatchMessage( &msg );
        }
        else
        {
            // アイドル時間の間にフレームをレンダリングする (待機中のメッセージなし)。
            if( g_bActive && g_bReady )
                Render3DEnvironment();
        }
    }

上記のコードでは、グローバル フラグ変数の g_bActive を使用してアクティブになる時点を追跡し、別の変数の g_bReady を使用して、すべてのシステム オブジェクトが、シーンのレンダリングの準備ができていることを示す。アプリケーションでは、ウィンドウが表示されていない場合は常に g_bActive を FALSE に設定し、シーンのレンダリングに使用するオブジェクトの再作成が必要な場合は常に g_bReady 変数を FALSE に設定する。(後者については、「ウィンドウのサイズ変更を処理する」で説明する)。

アプリケーションは、アクティブなときにメッセージ キューをチェックして、待機中のメッセージがないかどうかを確認する。キューにメッセージがある場合は、ほかの Windows アプリケーションと同様にメッセージをディスパッチする。キューにメッセージがない場合は、アプリケーション定義関数 Render3DEnvironment を呼び出して、シーンのフレームをレンダリングする。これが、「ステップ 5 : シーンをレンダリング、表示する」の説明内容である。


ステップ 5 : シーンをレンダリング、表示する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションは、システム メッセージを処理していなければいつでも、シーンのフレームのレンダリングを行うことができる。サンプル Triangle は、メッセージ キューが空の場合に必ず、 WinMain からアプリケーション定義関数 Render3Denvironment を呼び出して、シーンのレンダリングを行う。Render3DEnvironment 関数は、このタスクを次の 3 つの下位ステップに分割する。

  • ステップ 5.1 : シーンを更新する
  • ステップ 5.2 : シーンをレンダリングする
  • ステップ 5.3 : ディスプレイを更新する


ステップ 6 : シャットダウン

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションは、実行中のある時点で、シャット ダウンしなければならない。DirectX アプリケーションをシャット ダウンするとは、アプリケーション ウィンドウを破壊するだけでなく、アプリケーションが使用しているすべての DirectX オブジェクトの割り当てを解除し、オブジェクトへのポインタを無効にすることを意味する。Triangle では、WM_DESTROY メッセージを受け取ったときに、Cleanup3Denvironment というアプリケーション定義関数を呼び出して、このクリーンアップ (整理作業) を行っている。

HRESULT Cleanup3DEnvironment()
{
    // シーンに作成されたすべてのオブジェクトのクリーンアップを行う。
    App_DeleteDeviceObjects( g_pd3dDevice );

    // アプリケーションが使用していた DDraw とD3D のオブジェクトを解放する。
    if( g_pD3D )           g_pD3D->Release();
    if( g_pddsBackBuffer ) g_pddsBackBuffer->Release();
    if( g_pddsPrimary )    g_pddsPrimary->Release();

    // D3DDEVICE を解放する際に安全チェックを行う。RefCount はゼロのはずである。
    if( g_pd3dDevice )
        if( 0 < g_pd3dDevice->Release() )
            return E_FAIL;

    // DDRAW を解放する際に安全チェックを行う。RefCount はゼロのはずである。
    if( g_pDD )
        if( 0 < g_pDD->Release() )
            return E_FAIL;

    g_pd3dDevice     = NULL;
    g_pD3D           = NULL;
    g_pddsBackBuffer = NULL;
    g_pddsPrimary    = NULL;
    g_pDD            = NULL;

    return S_OK;
}

上記の関数は、各オブジェクトに対して IUnknown::Release メソッドを呼び出して、アプリケーションが使用している DirectX オブジェクトの割り当てを解除している。このチュートリアルは COM 規則に従っているため、ほとんどのオブジェクトに対する参照カウントはゼロのはずで、自動的にメモリから削除される。

シャット ダウンするとき以外にも、ユーザーがデスクトップ解像度や色深度を変更したときなどの通常の実行時に、使用中の DirectX オブジェクトを破棄して再作成する必要が生じることもある。そのため、必要な場合に呼び出すことができるよう、アプリケーションのクリーンアップ コードを 1 箇所に維持しておくと便利である。


ウィンドウの移動を処理する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

ウィンドウで実行される DirectX アプリケーションは、ウィンドウに対するブリットがデスクトップの正しい位置に現れるように、ウィンドウのクライアント領域の位置を追跡しなければならない。この追跡を怠ると、グラフィックスがアプリケーション ウィンドウの外側に現れ、ユーザーを混乱させることになる。サンプル Triangle は、次に示すように、システムがウィンドウ プロシージャに送る WM_MOVE メッセージに応答する。

 .
 .
 .
    case WM_MOVE:
        // 移動メッセージは、プライマリ サーフェスにバック バッファをブリットするのに使用する。
        // 画面の矩形を更新するために追跡する必要がある。
        if( g_bActive && g_bReady )
            OnMove( (SHORT)LOWORD(lParam), (SHORT)HIWORD(lParam) );
        break;
 .
 .
 .

g_bActive 変数は、ウィンドウ プロシージャの別の箇所で設定されてウィンドウがアクティブかどうかを示し、ウィンドウが最小化されている場合には FALSE に設定される。変数 g_bReady には、アプリケーションが使用中の DirectX オブジェクトを再作成しているときを除いて、TRUE が設定される。この 2 つの変数が共に TRUE である場合に、次のアプリケーション定義関数 OnMove が呼び出される。

VOID OnMove( INT x, INT y )
{
    DWORD dwWidth  = g_rcScreenRect.right - g_rcScreenRect.left;
    DWORD dwHeight = g_rcScreenRect.bottom - g_rcScreenRect.top;
    SetRect( &g_rcScreenRect, x, y, x + dwWidth, y + dwHeight );
}

この関数は、グローバル変数 g_rcScreenRect のサイズを単に再計算するものである。このチュートリアルでは、「ステップ 5.3 : ディスプレイを更新する」でディスプレイを更新するときに、このグローバル変数を目的の矩形として使用している。


ウィンドウのサイズ変更を処理する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

ウィンドウで実行される DirectX アプリケーションは、システムが送るすべての WM_SIZE メッセージに応答しなければならない。レンダリング ターゲット サーフェスは、通常、メモリの節約のために最小限に維持されている。その最小サイズは、通常、ウィンドウのクライアント領域のサイズとなる。ウィンドウ サイズが大きくなった場合、レンダリング ターゲット サーフェスと関連オブジェクトを破棄して、適切なサイズで再作成する必要が生じる。実際には、アプリケーションがこの処理を実行するのは、ウィンドウが大きくなった場合だけでよい。ウィンドウ サイズが小さくなった場合には、その程度に応じて、ビューポートを調節し、ブリットのサイズを縮小することにより対応できる。このチュートリアルでは、理解しやすくするため、WM_SIZE メッセージを受け取ると必ず使用しているオブジェクトを破棄して、再作成するようにしている。

         .
         .
         .
        case WM_SIZE:
            // ウィンドウが使用可能かどうかの確認を行う。
            // アクティブ フラグに対応する値を設定する。
            if( SIZE_MAXHIDE==wParam || SIZE_MINIMIZED==wParam )
                g_bActive = FALSE;
            else g_bActive = TRUE;

            // 新しいウィンドウ サイズにより、新しいバック バッファ サイズが必要になる。
            // これを行う最も簡単な方法は、すべてを解放し、再作成することである。
            // 注 ：  ウィンドウが大きくなりすぎた場合には、メモリ不足になり、
            // 終了する必要が生じる可能性がある。この単純なアプリケーションは、
            // エラー メッセージを表示しないで終了するが、
            // 実際のアプリケーションでは、もっとうまく動作する必要がある。
            if( g_bActive && g_bReady )
            {
                g_bReady = FALSE;
                if( FAILED( Cleanup3DEnvironment() ) )
                    DestroyWindow( hWnd );
                if( FAILED( Initialize3DEnvironment( hWnd ) ) )
                    DestroyWindow( hWnd );
                g_bReady = TRUE;
            }
            break;
         .
         .
         .

上記のコードでは、グローバル変数を設定して、使用中の DirectX オブジェクトが無効化されていることを、コードのほかの部分に通知していることに注意する。さらに、このコードは、アプリケーションのシャット ダウン時にも呼び出されるアプリケーション定義関数 Cleanup3Denvironment を呼び出している。アプリケーションの終了については、「ステップ 6 : シャットダウン」で説明する。


チュートリアル 2 : 深度バッファを追加する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

Direct3D アプリケーションでは、シーンのオブジェクトを正しく表示するのに、深度バッファに依存することが多い。概念的な概要については、「深度バッファ」を参照すること。深度バッファを使用するには、サポートされている深度バッファ フォーマットを列挙し、深度バッファ サーフェスを作成し、レンダリング ターゲット サーフェスに深度バッファ サーフェスをアタッチした後、レンダリング デバイスの深度バッファリングを有効にしなければならない。

このチュートリアルでは、サンプル プロジェクト Triangle のコードを使用しながら説明する。このコードでは、最も一般的にサポートされている深度バッファのタイプである、z バッファが使用されている。サンプル ZBuffer は、次のステップを実行して、z バッファを使用する。

  • ステップ 1 : 深度バッファ フォーマットを列挙する
  • ステップ 2 : 深度バッファを作成する
  • ステップ 3 : 深度バッファをアタッチする
  • ステップ 4 : 深度バッファリングを有効にする

注 : ZBuffer サンプルのコードは、Triangle のコードとほとんど同じである。このチュートリアルでは、Zbuffer に特有な深度バッファ コードだけを取り上げ、Direct3D のセット アップ、レンダリング、シャット ダウン、Windows メッセージの処理は説明しないものとする。これらのタスクについては、「チュートリアル 1 : 単一の三角形をレンダリングする」を参照すること。

レンダリング デバイスによっては、深度バッファをメモリの特定の場所に位置させる必要があるため、レンダリング デバイスを作成する前に、深度バッファ サーフェスを作成し、レンダリング ターゲット サーフェスにアタッチする必要がある。


ステップ 1 : 深度バッファ フォーマットを列挙する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

レンダリング デバイスが深度バッファをサポートしているのであれば、深度バッファの作成前に、どのような深度バッファ フォーマットをサポートしているかを確認しておかなければならない。IDirect3D7::EnumZBufferFormats メソッドを呼び出して、デバイスでサポートしている深度バッファ フォーマットを列挙する。サンプル ZBuffer では、次のコードを使用して、深度バッファ フォーマットを列挙している。

    //-------------------------------------------------------------------------
    // バックバッファを作成してから d3ddevice を作成するまでに
    // Z バッファを作成する。
    //
    // 注 :  Z バッファの作成前に、アプリケーションでは、
    // D3DPRASTERCAPS_ZBUFFERLESSHSR フラグのデバイス能力をチェックする場合もある。
    // フラグは、z バッファなしに、HSR (hidden-surface-removal) を
    // 行うことができるハードウェアに対して TRUE になる。そうしたデバイスに対しては、z バッファを作成する必要はない。
    //-------------------------------------------------------------------------

    DDPIXELFORMAT ddpfZBuffer;
    g_pD3D->EnumZBufferFormats( *pDeviceGUID,
                                 EnumZBufferCallback, (VOID*)&ddpfZBuffer );

EnumZBufferFormats メソッドは、フォーマットを列挙する対象となるデバイスのグローバル ユニーク識別子 (GUID)、コールバック関数のアドレス、およびコールバック関数に渡される任意のデータ構造体のアドレスを受け付ける。ユーザーが提供するコールバック関数は、D3DEnumPixelFormatsCallback 関数プロトタイプに従わなければならない。システムは、コールバック関数が D3DENUMRET_CANCEL を返さない限り、指定されたコールバック関数を、サポートされている各深度バッファ フォーマットに対して一度ずつ呼び出す。サンプル ZBuffer は、次のようなコールバック関数を処理する。

static HRESULT WINAPI EnumZBufferCallback( DDPIXELFORMAT* pddpf,
                                           VOID* pddpfDesired )
{
    // このチュートリアルでの対象は Z バッファのみで、
    // ほかのフォーマット (DDPF_STENCILBUFFER など) が列挙されてもすべて無視する。また、
    // アプリケーションでは、Z バッファの深度 (16 ビットなど) を調べ、
    // その結果に基づいて選択することもできる。このチュートリアルでは、最初に列挙された
    // フォーマットを選択する。
    if( pddpf->dwFlags == DDPF_ZBUFFER )
    {
        memcpy( pddpfDesired, pddpf, sizeof(DDPIXELFORMAT) );

        // D3DENUMRET_CANCEL を返して検索を終了する。
        return D3DENUMRET_CANCEL;
    }

    // D3DENUMRET_OK を返して検索を続行する。
    return D3DENUMRET_OK;
}

システムがこのコールバック関数を呼び出すときには、深度バッファのピクセル フォーマットを記述する DDPIXELFORMAT 構造体のアドレスを渡す。dwFlags メンバには、深度バッファ ビットを含む任意のピクセル フォーマットに対して DDPF_ZBUFFER が格納される。その場合、dwZBufferBitDepth メンバに深度情報に予約されているピクセル フォーマット中のビット数を表す整数が格納され、dwZBitMask メンバが関連ビットをマスクする。

このチュートリアルでは、理解しやすくするため、最も一般的なタイプの深度バッファである z バッファだけを使用している。システムが列挙するほかのフォーマット (DDPF_STENCILBUFFER など) は、すべて無視する。アプリケーションは、z バッファのビット深度 (8、16、24、32 ビット) をチェックして、ビット深度に基づいた選択を行うこともできる。適切なフォーマットが見つかると、このコールバック関数は、与えられた DDPIXELFORMAT 構造体を 2 番目のパラメータで渡されたアドレス (これも、DDPIXELFORMAT 構造体) にコピーし、列挙を終了させるため D3DENUMRET_CANCEL を返す。

深度バッファのフォーマットを決定すると、そのフォーマットを使用する DirectDrawSurface を作成することができる。これが、「ステップ 2 : 深度バッファを作成する」の説明内容である。


ステップ 2 : 深度バッファを作成する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

ここで、深度バッファ フォーマットの選択を終了したので、深度バッファとなる DirectDrawSurface オブジェクトを作成することができる。サーフェスのピクセル フォーマットは、列挙によって決定されたものであるが、サーフェスの寸法は、アタッチされるレンダリング ターゲット サーフェスと同一にしなければならない。サンプル ZBuffer では、このタスクに対して次のコードを使用する。

    // 適切な Z バッファ フォーマットが見つかると、
    // 列挙中に dwSize フィールドが正しく設定される。適切な Z バッファ フォーマットが見つからなかった場合は、問題があるため終了する。
    if( sizeof(DDPIXELFORMAT) != ddpfZBuffer.dwSize )
        return E_FAIL;

    // レンダリング ターゲットから z バッファのサイズを取得する。
    // z バッファのサーフェス記述をセット アップする。
    ddsd.dwFlags        = DDSD_CAPS|DDSD_WIDTH|DDSD_HEIGHT|DDSD_PIXELFORMAT;
    ddsd.ddsCaps.dwCaps = DDSCAPS_ZBUFFER;
    ddsd.dwWidth        = g_rcScreenRect.right - g_rcScreenRect.left;
    ddsd.dwHeight       = g_rcScreenRect.bottom - g_rcScreenRect.top;
    memcpy( &ddsd.ddpfPixelFormat, &ddpfZBuffer, sizeof(DDPIXELFORMAT) );

    // ハードウェア デバイスの場合、Z バッファをビデオ メモリ内に作成しなければならない。ソフトウェア デバイスの場合は、
    // Z バッファをシステム メモリ内に作成する。
    if( IsEqualIID( *pDeviceGUID, IID_IDirect3DHALDevice ) )
        ddsd.ddsCaps.dwCaps |= DDSCAPS_VIDEOMEMORY;
    else
        ddsd.ddsCaps.dwCaps |= DDSCAPS_SYSTEMMEMORY;

    // Z バッファを作成してアタッチする。実際のアプリケーションでは、
    // ここでエラー処理を行う (DDERR_OUTOFVIDEOMEMORY が発生する場合がある)。ただし、
    // このチュートリアルでは、このエラー処理を行わずに終了する。
    if( FAILED( hr = g_pDD->CreateSurface( &ddsd, &g_pddsZBuffer, NULL ) ) )
        return hr;

上記のコードは、設定済みのグローバル変数から計算されたレンダリング ターゲット サーフェスの寸法を使用して、深度バッファ用の DDSURFACEDESC2 構造体を準備しているだけである。前のステップ「ステップ 1 : 深度バッファ フォーマットを列挙する」で取得したピクセル フォーマット情報は、サーフェス記述にコピーされる。

注 : ハードウェア デバイスでは、深度バッファをメモリ内でのその位置に関係なく使用できる。ハードウェア デバイスの使用時には、サーフェス能力フラグ DDSCAPS_VIDEOMEMORY および DDSCAPS_SYSTEMMEMORY を省略して、バッファの最適位置をデバイスに決定させるのが最善である。しかし、ソフトウェア デバイスは、深度バッファがシステム メモリに存在しないと、作成することができない。上記のコードでは、ソフトウェア デバイスである可能性をチェックして、必要に応じて DDSCAPS_SYSTEMMEMORY フラグを含めるようにしている。

サーフェス記述の準備ができると、このコードでは、IDirectDraw7::CreateSurface メソッドを呼び出して新しい深度バッファ サーフェスを作成する。深度バッファを作成した後、その深度バッファをレンダリング ターゲットとして使用されるサーフェスにアタッチできる。この処理については、「ステップ 3 : 深度バッファをアタッチする」で説明する。


ステップ 3 : 深度バッファをアタッチする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

深度バッファを作成したら、レンダリング ターゲットとして使用されるサーフェスにアタッチする必要がある。これを行うには、レンダリング ターゲット サーフェスの IDirectDrawSurface7::AddAttachedSurface メソッドを呼び出す。サンプル ZBuffer では、次のコードを使用してこの処理を実行する。

    // バック バッファに Z バッファをアタッチする。
    if( FAILED( hr = g_pddsBackBuffer->AddAttachedSurface( g_pddsZBuffer ) ) )
        return hr;

深度バッファをレンダリング ターゲット サーフェスにアタッチすると、深度バッファリングが有効になっている場合、システムは常に、この深度バッファを自動的に使用する。これについては、「ステップ 4 : 深度バッファリングを有効にする」で説明する。


ステップ 4 : 深度バッファリングを有効にする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

深度バッファをレンダリング ターゲット サーフェスにアタッチすると、レンダリング ターゲットからレンダリング デバイスを作成することができる。

アプリケーションで深度バッファを使用する場合、ビューポートおよび深度バッファの両方をクリアする必要がある。深度バッファをクリアするには、IDirect3DDevice7::Clear メソッドに D3DCLEAR_ZBUFFER フラグを指定する。

    pd3dDevice->Clear( 0, NULL, D3DCLEAR_TARGET|D3DCLEAR_ZBUFFER,
                       0x000000ff, 1.0f, 0L );

レンダリング デバイスが用意されると、そのデバイスの D3DRENDERSTATE_ZENABLE レンダリング ステートを設定して、深度バッファリングを有効にすることができる。D3DZBUFFERTYPE 列挙型には、深度バッファのレンダリング ステートを設定するメンバが含まれている。D3DZB_TRUE メンバ (または TRUE) により、z バッファリングを有効にする。サンプル ZBuffer は、アプリケーション定義関数 App_Render でのシーンのレンダリング中に、z バッファリングを有効にしている。次のコードは、App_Render からの該当部分の抜粋である。

    // z バッファリングを有効にする (注 :  実際にはこの処理をフレームごとに行う必要はない)。
    pd3dDevice->SetRenderState( D3DRENDERSTATE_ZENABLE, TRUE );

このチュートリアルでは、フレーム単位に深度バッファリングを有効にしているが、これは必須ではない。実際のアプリケーションでは、シーンの初期化中に D3DRENDERSTATE_ZENABLE レンダリング ステートを設定しておき、深度バッファリングを無効にしたり、深度バッファリングの別のタイプを選択するときにだけ変更するのが普通である。

注 : D3DZBUFFERTYPE 列挙型には、準拠ハードウェアでの W ベースの深度比較を有効にする D3DZB_USEW 値が含まれる。詳細については、「深度バッファ」を参照すること。


チュートリアル 3 : さまざまなプリミティブ スタイルを使用する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

ここでは、Direct3D のさまざまな描画プリミティブの呼び出しを使用してポリゴンをレンダリングする方法について説明する。このチュートリアルで使用するプリミティブは、少なくとも 3 つの頂点を持つ閉じた 3 次元 (3D) オブジェクトとしてのポリゴンである。

このチュートリアルでは、特に一連のプリミティブ (壁セグメント、円錐、立方体) にジオメトリを準備する方法を示す。つまり、ビューポイントを回転する方法や、行列を連結して立方体の平行移動、回転、およびスケーリングなどの 3D トランスフォームを実行する方法について説明する。

  • ステップ 1 : シーンのジオメトリを初期化する
  • ステップ 2 : シーンをレンダリング、表示する

3D プリミティブの詳細については、「3D プリミティブ」を参照すること。

注 : DrawPrims アプリケーションのコードは、Triangle で使用するコードに類似している。このチュートリアルでは、ジオメトリの準備、および DrawPrims アプリケーション固有のレンダリング コードにのみ重点を置き、Direct3D のセットアップ、シャットダウン、またはシステム イベントの処理については触れない。これらのタスクの詳細については、「チュートリアル 1 : 単一の三角形をレンダリングする」を参照すること。

ここでは、深度バッファを使用してシーンの深度情報を格納する。深度バッファを使用するには、サポートされている深度バッファ フォーマットを列挙し、深度バッファ サーフェスを作成し、その深度バッファ サーフェスをレンダリング ターゲット サーフェスにアタッチし、レンダリング デバイスに対して深度バッファリングを有効にする必要がある。これらのタスクの詳細については、「チュートリアル 2 : 深度バッファを追加する」を参照すること。


ステップ 1 : シーンのジオメトリを初期化する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、アプリケーション定義の App_InitDeviceObjects メソッドでプリミティブにジオメトリを用意する。App_InitDeviceObjects は、各オブジェクトに一連の頂点を定義し、グローバル定義されたデータ構造体に各プリミティブの頂点情報を格納する。頂点情報は、レンダリング時に DrawPrimitive メソッドで使用される。

技術的には、この時点でジオメトリを設定する必要はない。レンダリング メソッドを呼び出す前にいつでも設定できる。

  • ステップ 1.1 : 壁セグメントを準備する
  • ステップ 1.2 : 円錐を準備する
  • ステップ 1.3 : 立方体を準備する

プリミティブの種類の詳細については、「プリミティブの種類」を参照すること。

Direct3D における頂点の指定方法の詳細については、「頂点フォーマット」を参照すること。

注 : 特定のプリミティブに用意するジオメトリの順序は、シーンのオブジェクトのレイアウトに影響しない。


ステップ 2 : シーンをレンダリング、表示する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

シーンのオブジェクトを正しく表示および操作するには、シーンの視点を定義し、ビュー行列を作成し、必要なトランスフォームを実行し、完成したシーンをレンダリングする必要がある。これらのタスクについては、次のステップで説明する。

  • ステップ 2.1 : ビューポイントを定義する
  • ステップ 2.2 : ビュー行列を作成および設定する
  • ステップ 2.3 : 3D トランスフォームを実行する
  • ステップ 2.4 : シーンをレンダリングする

シーンのレンダリングの詳細については、「プリミティブのレンダリング」を参照すること。


チュートリアル 4 : デバイス列挙を使用する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

デバイス列挙が便利なのは、ハードウェアがサポートする Direct3D デバイスについて、アプリケーションからハードウェアに問い合わせることができる点である。その結果、特定のハードウェア構成を活用したアプリケーションを構築したり、システムのハードウェアがサポートする特定の構成をユーザー側での選択に任せることができる。ここでは、ドライバ、ディスプレイ モード、およびデバイスを列挙し、さらに各デバイスでサポートされるディスプレイ モードのリストを作成する。

基本的に、デバイス列挙には大きく分けて 2 つのステップがあり、(1) デバイス列挙を初期化して実行する、(2) 列挙されたデバイスの選択、という処理を行う。

ここでは、この処理を次の項に分けて説明する。

  • ステップ 1 : デバイス列挙を初期化して実行する
  • ステップ 2 : 列挙されたデバイスの選択

Direct3D デバイスの詳細については、「Direct3D デバイス」を参照すること。

デバイスの列挙の詳細については、「Direct3D デバイスの列挙」を参照すること。

注 : Enumeration アプリケーションで使用するコードは、Triangle アプリケーションのコードに類似している。このチュートリアルでは、Enumeration アプリケーション固有のデバイス列挙コードにのみ重点を置き、Direct3D のセットアップ、シーン ジオメトリの準備、シャットダウン、またはシステム イベントの処理については触れない。これらのタスクの詳細については、「チュートリアル 1 : 単一の三角形をレンダリングする」を参照すること。

ここでは、深度バッファを使用してシーンの深度情報を格納する。深度バッファを使用するには、サポートされている深度バッファ フォーマットを列挙し、深度バッファ サーフェスを作成し、その深度バッファ サーフェスをレンダリング ターゲット サーフェスにアタッチし、レンダリング デバイスに対して深度バッファリングを有効にする必要がある。これらのタスクの詳細については、「チュートリアル 2 : 深度バッファを追加する」を参照すること。

ここでは、一連の円錐プリミティブを描く。プリミティブの描画方法の詳細については、「チュートリアル 3 : さまざまなプリミティブ スタイルを使用する」を参照すること。


ステップ 1 : デバイス列挙を初期化して実行する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

Enumeration アプリケーションは、次の構造体を使用して、列挙された Direct3D デバイスについての情報を保持する。

struct D3DDEVICEINFO
{
    // D3D デバイス情報。
    CHAR           strDesc[40];
    GUID*          pDeviceGUID;
    D3DDEVICEDESC7 ddDeviceDesc;
    BOOL           bHardware;

    // DDraw ドライバ情報。
    GUID*          pDriverGUID;
    DDCAPS         ddDriverCaps;
    DDCAPS         ddHELCaps;

    // DDraw モード情報。
    DDSURFACEDESC2 ddsdMode;
    BOOL           bFullscreen;

    // 内部使用の場合 (アプリケーションではこれらは必要ない)。
    GUID           guidDevice;
    GUID           guidDriver;
    DDSURFACEDESC2 ddsdModes[100];
    DWORD          dwNumModes;
    DWORD          dwCurrentMode;
    BOOL           bDesktopCompatible;
};

Enumeration アプリケーションでは、次の呼び出しによって列挙を初期化する。

INT UserDlgSelectDriver( HWND hwndParent )
{
    // ドライバ、デバイス、およびモードを列挙する。
    DirectDrawEnumerateEx( DriverEnumCallback, NULL,
                           DDENUM_ATTACHEDSECONDARYDEVICES |
                           DDENUM_DETACHEDSECONDARYDEVICES |
                           DDENUM_NONDISPLAYDEVICES );

上記のコードでは、システムで使用できるドライバ、デバイス、およびディスプレイ モードを列挙するのに DirectDrawEnumerateEx メソッドを使用している。第 1 パラメータ DriverEnumCallback, は、列挙される個々の DirectDraw で有効な HAL の記述で呼び出される DDEnumCallbackEx 関数のアドレスである。

アプリケーションのデバイス列挙プロセスは、次のステップに分かれる。

  • ステップ 1.1 : ドライバ情報を列挙する
  • ステップ 1.2 : ディスプレイ モード情報を列挙する
  • ステップ 1.3 : デバイス情報を列挙する

デバイス列挙を使用するアプリケーションの最初のステップは、DirectDraw ドライバへの参照の取得である。ドライバ列挙については、「ステップ 1.1 : ドライバ情報を列挙する」で説明する。

デバイス列挙の開始の詳細については、「デバイス列挙の開始」を参照すること。


ステップ 2 : 列挙されたデバイスの選択

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

列挙されたデバイスを選択するときは、通常、次のステップを実行する。

  • ステップ 2.1 : デバイスを取得する
  • ステップ 2.2 : デバイスをテストする

列挙されたデバイスの選択の詳細については、「列挙されたデバイスの選択」を参照すること。


チュートリアル 5 : テクスチャ マップを使用する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、テクスチャを使用した簡単な 3D シーンの描画方法について説明する。本来、Direct3D テクスチャとは、ピクセル カラーのビットマップである。このため、Direct3D プリミティブには、あらゆるビットマップ イメージを適用できる。テクスチャは、ジオメトリを変更することなく 3D オブジェクトをリアルに表現できる、簡単で効果的な方法である。テクスチャをこのように活用すれば、色、粗さ、透過性、および滑らかさのパターンとイリュージョンを加えてプリミティブの質を向上させることができる。特に、ここでは、ファイル ベースのビットマップからテクスチャを作成する方法や、テクスチャを使用して立方体をレンダリングする方法について説明する。

現在 Direct3D ではテクスチャ ハンドルが廃止されている。このため、テクスチャを作成および使用するときは、テクスチャ サーフェスのインタフェース ポインタを利用する。詳細については、「テクスチャ インターフェイスとテクスチャ ハンドル」を参照すること。

3D シーンのプリミティブにテクスチャを追加するには、次のステップを実行する。

  • ステップ 1 : テクスチャ サーフェスを準備する
  • ステップ 2 : テクスチャ サーフェスを作成する
  • ステップ 3 : テクスチャ プリミティブのレンダリング

Direct3D では拡張テクスチャ機能セットをサポートしており、高度なテクスチャ処理技術を簡単に利用できる。テクスチャ、および Direct3D でのテクスチャの使用方法と最適化方法の詳細については、「テクスチャ」を参照すること。

注 : Texture アプリケーションのコードは、Triangle アプリケーションのコードに類似している。このチュートリアルでは、Texture アプリケーション固有のテクスチャ コードにのみ重点を置き、Direct3D のセットアップ、シーン ジオメトリの準備、シャットダウン、またはシステム イベントの処理については触れない。これらのタスクの詳細については、「チュートリアル 1 : 単一の三角形をレンダリングする」を参照すること。

ここでは立方体を描く。プリミティブの描画方法の詳細については、「チュートリアル 3 : さまざまなプリミティブ スタイルを使用する」を参照すること。

ここでは、列挙を使用してテクスチャ フォーマットを列挙する。列挙の技術および原理の詳細については、「チュートリアル 4 : デバイス列挙を使用する」を参照すること。


ステップ 1 : テクスチャ サーフェスを準備する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

3D シーンでシステム管理下のテクスチャを正しく準備するには、次のステップを実行する。

  • ステップ 1.1 : テクスチャ座標を設定する
  • ステップ 1.2 : テクスチャ サーフェスを準備する
  • ステップ 1.3 : テクスチャ管理を有効にする
  • ステップ 1.4 : テクスチャ フォーマットを列挙する

プリミティブにテクスチャを作成する前に、テクスチャ座標に沿ってプリミティブの頂点を定義する必要がある。このタスクについては、「ステップ 1.1: テクスチャ座標を設定する」で説明する。


ステップ 2 : テクスチャ サーフェスを作成する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

準備したサーフェスからテクスチャ サーフェスを作成するタスクについて、次のステップに分けて説明する。

  • ステップ 2.1 : レンダリング ターゲットを取得する
  • ステップ 2.2 : 新しいサーフェスを作成する
  • ステップ 2.3 : レンダリング サーフェスにコピーする

テクスチャ サーフェス オブジェクトは、単純な DirectDraw サーフェス オブジェクトである。テクスチャ サーフェスの詳細については、「テクスチャ サーフェス オブジェクト」を参照すること。

テクスチャ サーフェスを作成する前に、デバイスのレンダリング ターゲットを取得する必要がある。この処理については、「ステップ 2.1 : レンダリング ターゲットを取得する」で説明する。


ステップ 3 : テクスチャ プリミティブのレンダリング

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

テクスチャ処理されたプリミティブとテクスチャ処理されていないプリミティブのレンダリングには 1 つだけ違いがある。それは、テクスチャ処理されたプリミティブの場合、レンダリングの際にテクスチャを設定する必要があるという点である。

次のコードは Texture アプリケーションのコードの一部である。このコードでは、テクスチャ サーフェス g_pddsTexture1 を使用して立方体の前面および背面を描画している。

    pd3dDevice->SetTexture( 0, g_pddsTexture1 );
    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX,
                               g_pCubeVertices+0, 4, NULL );
    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX,
                               g_pCubeVertices+4, 4, NULL );

IDirect3DDevice7::SetTexture メソッドは、デバイスで指定されたステージにテクスチャを割り当てる。このチュートリアルではマルチ テクスチャ ブレンディングを使用しないため、SetTexture の第 1 パラメータを 0 にしてステージ識別子に 0 を指定している。第 2 パラメータは、テクスチャとして設定する IDirectDrawSurface7 オブジェクトを指定する。

立方体の上面と底面、および左側面と右側面にも同じプロシージャを使用して、それぞれ g_pddsTexture2 と g_pddsTexture3 を設定する。この方法については、SDK 付属の Texture アプリケーションを参照すること。

テクスチャのレンダリングの詳細については、「テクスチャ サーフェスを使用したレンダリング」を参照すること。

マルチ テクスチャ ブレンディングの詳細については、「マルチ テクスチャ ブレンディング」を参照すること。


Direct3D 直接モード Visual Basic チュートリアル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

この Microsoft® Visual Basic® チュートリアルでは、一般的なタスクを実行する簡単な Direct3D® アプリケーションの作成方法について説明する。これらのチュートリアルでは、DirectX® SDK に添付されている Direct3D のサンプル ファイルを使用する。次のチュートリアルを提供する。

  • チュートリアル 1 : 単一の三角形をレンダリングする
  • チュートリアル 2 : 深度バッファを追加する
  • チュートリアル 3 : さまざまなプリミティブ スタイルを使用する
  • チュートリアル 4 : デバイス列挙を使用する
  • チュートリアル 5 : テクスチャ マップを使用する


チュートリアル 1 : 単一の三角形をレンダリングする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

Visual Basic で Direct3D を使用するには、まず、アプリケーション ウィンドウからフォームを作成した後、DirectDraw® と Direct3D 関連オブジェクトを作成し、初期化する。これらのオブジェクトは、定義済みのメソッドによって操作する。また、これらのメソッドを使って、完成シーンのレンダリングに必要な従属オブジェクトの初期化も行う。

このチュートリアルでは、可能な限り単純なシーン、つまり単一の三角形を表示する手順を示す。メイン フォームのプロパティをセット アップした後、サンプル Triangle で、Direct3D デバイス オブジェクトのレンダリング、ライティング、ビューポート、マテリアル、モデルのジオメトリなど、DirectDraw と Direct3D の初期化方法を詳しく説明する。次に、三角形をフレームごとにレンダリングしたり、Y 軸を中心に少しずつ回転する方法を示すサブルーチンを示す。

サンプル Triangle では、次のステップを使って、DirectDraw と Direct3D をセット アップし、シーンをレンダリングする。

  • ステップ 1 : フォームを作成する
  • ステップ 2 : システム オブジェクトを初期化する
  • ステップ 3 : シーンを初期化する
  • ステップ 4 : レンダリング ループを実行する
  • ステップ 5 : シャット ダウンを行う

注 : サンプル Triangle の Visual Basic コードでは、DirectDraw および Direct3D の初期化コードとアプリケーション固有のコードが別々になっているが、これは必須ではなく、理解しやすくするために行ったものである。


ステップ 1 : フォームを作成する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

Visual Basic フォームは、アプリケーション ウィンドウの役割を果たす。次の方法でフォームのプロパティを設定する。

BorderStyle     =   1  '実線
Caption         =   "Triangle"
ClientHeight    =   3195
ClientLeft      =   5415
ClientTop       =   3300
ClientWidth     =   3720
LinkTopic       =   "Form1"
MaxButton       =   0   'False
MinButton       =   0   'False
ScaleHeight     =   213
ScaleMode       =   0  'ユーザー
ScaleWidth      =   254
StartUpPosition =   3  'Windows のデフォルト

アプリケーション ウィンドウを表示するには、Form_Load プロシージャに次の行を追加する。

Me.Show

アプリケーション ウィンドウの準備が終了すると、DirectX の主要オブジェクトのセット アップを開始することができる。これが、「ステップ 2 : システム オブジェクトを初期化する」の説明内容である。


ステップ 2 : システム オブジェクトを初期化する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

アプリケーション ウィンドウを作成すると、シーンのレンダリングに必要な DirectX 主要オブジェクトの初期化を開始できる。Direct3D アプリケーションにとって、初期化とは、DirectDraw、レンダリング サーフェス、レンダリング デバイス、ビューポートを作成および構成することを意味する。

サンプル Triangle では、Form_Load プロシージャという名前のアプリケーション定義サブルーチン InitDDraw でシステムの初期化を行う。InitDDraw サブルーチンで実行されるステップを以下に示す。

  • ステップ 2.1 : DirectDraw を初期化する
  • ステップ 2.2 : DirecｔDraw サーフェスをセット アップする
  • ステップ 2.3 : Direct3D を初期化する
  • ステップ 2.4 : ビューポートを準備する


ステップ 3 : シーンを初期化する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

Direct3D 関連のプライマリ オブジェクトである、DirectDraw オブジェクト、レンダリング デバイス、およびビューポートを作成すると、マテリアルの準備、トランスフォーム行列の構成、およびアプリケーションが使用するジオメトリのセット アップを行い、シーンの初期化を開始できる。サンプル Triangle では、次のステップを実行してシーンを初期化する。

  • ステップ 3.1 : マテリアルと初期ライティング ステートをセット アップする
  • ステップ 3.2 : 座標トランスフォーム行列を準備、設定する
  • ステップ 3.3 : ジオメトリを準備する


ステップ 4 : レンダリング ループを実行する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

アプリケーション ウィンドウの作成と DirectX オブジェクトの作成に続き、シーンの初期化を終了すると、いつでもシーンのレンダリングを行える状態になる。サンプル Triangle のレンダリング ループでは、アプリケーション定義サブルーチン RenderScene と FrameMove を呼び出してシーンをレンダリングする。

Do While g_bRunning = True
CNT = CNT + 1
RenderScene
FrameMove (CNT / 360)

g_dx.GetWindowRect Me.hWnd, g_rcDest

j = g_ddsPrimary.Blt(g_rcDest, g_ddsBackBuffer, g_rcSrc, DDBLT_WAIT)
If j <> DD_OK Then
MsgBox "転送元矩形を転送先サーフェスにコピーできません。" & _
Chr$(13) & Hex(j)
End
End If
DoEvents
Loop

レンダリング ループは無限に続くように見えるが、Form_Unload プロシージャがトリガされると終了する。詳細については、「ステップ 5 : シャット ダウンを行う」を参照すること。

シーンをレンダリングするレンダリング ループは、次のステップに分けられる。

  • ステップ 4.1 : シーンを更新する
  • ステップ 4.2 : シーンをレンダリングする
  • ステップ 4.3 : ディスプレイを更新する
  • ステップ 4.4 : DoEvents を呼び出す


ステップ 5 : シャット ダウンを行う

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

サンプル Triangle では、以下に示す簡単なコードを使ってシャット ダウンを行う。

Private Sub Form_Unload(Cancel As Integer)
g_bRunning = False
End Sub

上記のコードでは、Form_Unload プロシージャがグローバル変数 g_bRunning を false に設定し、これによってレンダリング ループを終了する。


チュートリアル 2 : 深度バッファを追加する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

Direct3D アプリケーションでは、シーンのオブジェクトを正しく表示するのに、深度バッファに依存することが多い。概念的な概要については、「深度バッファ」を参照すること。深度バッファを使用するには、サポートされている深度バッファ フォーマットを列挙し、深度バッファ サーフェスを作成して、レンダリング ターゲット サーフェスに深度バッファ サーフェスをアタッチした後、レンダリング デバイスの深度バッファリングを有効にしなければならない。

サンプル ZBuffer では、次のステップを実行して、z バッファを使用する。

  • ステップ 1 : 深度バッファ フォーマットを列挙する
  • ステップ 2 : 深度バッファを作成する
  • ステップ 3 : 深度バッファをアタッチする
  • ステップ 4 : 深度バッファリングを有効にする

z バッファは、レンダリングされる各ピクセルのステート、すなわちレンダリングするピクセルが表示される深度を保持する。これにより、他のピクセル上でピクセルをレンダリングする場合、既にレンダリングされているピクセルの後ろに表示するかどうかを決定できる。

注 : サンプル ZBuffer のコードは、ほとんど、Triangle のコードと同一である。このチュートリアルでは、Zbuffer に特有な深度バッファ コードだけを取り上げ、Direct3D のセット アップ、レンダリング、シャット ダウン、アプリケーションによって起動されるイベントの処理については説明しないものとする。これらのタスクの詳細については、「チュートリアル 1 : 単一の三角形をレンダリングする」を参照すること。

レンダリング デバイスによっては、深度バッファをメモリの特定の場所に位置させる必要があるため、レンダリング デバイスを作成する前に、深度バッファ サーフェスを作成し、レンダリング ターゲット サーフェスにアタッチする必要がある。


ステップ 1 : 深度バッファ フォーマットを列挙する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

レンダリング デバイスが深度バッファをサポートしている場合、深度バッファの作成前に、どのような深度バッファ フォーマットをサポートしているかを確認しておかなければならない。Direct3D7.GetEnumZBufferFormats メソッドを呼び出して、デバイスがサポートしている深度バッファ フォーマットを列挙する。サンプル ZBuffer では、次のコードを使用して、深度バッファ フォーマットを列挙している。

' バックバッファの作成後、Direct3D デバイスを作成する前に、
' ｚ バッファを作成する。注 ：z バッファの作成前に、アプリケーションが、
' D3DPRASTERCAPS_ZBUFFERLESSHSR フラグでデバイス能力をチェックする場合がある。このフラグは、
' z バッファなしに、HSR (hidden-surface-removal) を行うことができるハードウェアに対して真になる。
' そうしたデバイスに対しては、z バッファを作成する必要はない。
    '
Dim ddpfZBuffer As DDPIXELFORMAT
Dim d3dEnumPFs As Direct3DEnumPixelFormats

Set g_d3d = g_dd.GetDirect3D
Set d3dEnumPFs = g_d3d.GetEnumZBufferFormats("IID_IDirect3DRGBDevice")

GetEnumZBufferFormats メソッドは、フォーマットを列挙する対象となるデバイスのグローバル ユニーク識別子 (GUID) を受け付ける。ZBuffer アプリケーションでは、GUID をコード中に書き込んで使用しているが、実際のアプリケーションでは、レンダリング デバイスの GUID を確認するテスト メカニズム、IID_IDirect3DRGBDevice または IID_IDirect3DHALDevice のいずれかを実装する。

ここで、デバイスのフォーマットが列挙されるので、サポートされる深度バッファ フォーマットを確認できる。

Dim I As Long

For I = 1 To d3dEnumPFs.GetCount()
Call d3dEnumPFs.GetItem(I, ddpfZBuffer)
If ddpfZBuffer.lFlags = DDPF_ZBUFFER Then
Exit For
End If
Next I

Direct3DEnumPixelFormats.GetItem を呼び出すと、2 番目の引数によって、深度バッファのピクセル フォーマットを示す DDPIXELFORMAT 型を渡す。メンバ IFlags には、深度バッファ ビットを含む任意のピクセル フォーマットに対して DDPF_ZBUFFER が格納される。最初の引数によって、GetItem は列挙されたフォーマットにインデックスを作成する。適切なフォーマットが見つかった場合、GetItem はそのピクセル フォーマットを ddpfZBuffer パラメータ、DDPIXELFORMAT 型に保存し、ループが終了する。

このチュートリアルでは、理解しやすくするため、最も一般的なタイプの深度バッファである z バッファだけを使用している。システムが列挙するほかのフォーマット (DDPF_STENCILBUFFER など) は、すべて無視する。アプリケーションは、z バッファのビット深度 (8、16、24、32 ビット) をチェックして、ビット深度に基づいた選択を行うこともできる。

深度バッファのフォーマットを決定すると、そのフォーマットを使用する DirectDrawSurface を作成することができる。これが、「ステップ 2 : 深度バッファを作成する」の説明内容である。


ステップ 2 : 深度バッファを作成する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここで、深度バッファ フォーマットの選択を終了したので、深度バッファとなる DirectDrawSurface オブジェクトを作成することができる。サーフェスのピクセル フォーマットは、列挙によって決定されたものであるが、サーフェスの寸法は、アタッチされるレンダリング ターゲット サーフェスと同一にしなければならない。サンプル ZBuffer では、このタスクに対して次のコードを使用する。

g_ddsd.lFlags = DDSD_CAPS Or DDSD_WIDTH Or DDSD_HEIGHT Or DDSD_PIXELFORMAT
    g_ddsd.ddsCaps.lCaps = DDSCAPS_ZBUFFER
g_ddsd.lWidth = g_rcDest.Right - g_rcDest.Left
g_ddsd.lHeight = g_rcDest.Bottom - g_rcDest.Top
g_ddsd.ddpfPixelFormat = ddpfZBuffer

上記のコードは、設定済みのグローバル変数から計算されたレンダリング ターゲット サーフェスの寸法を使用して、深度バッファ用の DDSURFACEDESC2 型を準備しているだけである。最終的には、前のステップのステップ 1 : 深度バッファ フォーマットを列挙する」で取得したピクセル フォーマット情報が、サーフェス記述にコピーされる。

g_ddsd.ddpfPixelFormat = ddpfZBuffer

注 : ハードウェア デバイスは、深度バッファを、メモリ中の位置に関係なく使用することができる。ハードウェア デバイスの使用時には、サーフェス能力フラグ DDSCAPS_VIDEOMEMORY および DDSCAPS_SYSTEMMEMORY を省略して、バッファの最適位置をデバイスに決定させるのが最善である。しかし、ソフトウェア デバイスは、深度バッファがシステム メモリに存在しないと、作成することができない。サンプル ZBuffer の次のコードでは、DDSCAPS_SYSTEMMEMORY フラグをセットしているが、実際のアプリケーションでは、サーフェス メモリがシステム メモリとディスプレイ メモリのどちらに存在するかを確認する、簡単な検索メカニズムを実装する必要がある。

' サーフェスがディスプレイ メモリに存在する場合、DDSCAPS_VIDEOMEMORY と指定する。
' 詳細については、SDK のドキュメントを参照すること。
g_ddsd.ddsCaps.lCaps = g_ddsd.ddsCaps.lCaps Or DDSCAPS_SYSTEMMEMORY

サーフェス記述の準備ができたら、コードは DirectDraw7.CreateSurface メソッドを呼び出して、新しい深度バッファ サーフェスを作成する。

Set g_ddsZBuffer = g_dd.CreateSurface(g_ddsd)

作成された深度バッファは、「ステップ 3 : 深度バッファをアタッチする」で説明するように、レンダリング ターゲットとして使用されるサーフェスにアタッチすることができる。


ステップ 3 : 深度バッファをアタッチする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

深度バッファを作成したら、レンダリング ターゲットとして使用されるサーフェスにアタッチする必要がある。これは、レンダリング ターゲット サーフェスの DirectDrawSurface7.AddAttachedSurface メソッドを呼び出して行う。サンプル ZBuffer では、次のコードを使用してこの処理を実行する。

' バックバッファに Z バッファをアタッチする。
g_ddsBackBuffer.AddAttachedSurface g_ddsZBuffer

深度バッファをレンダリング ターゲット サーフェスにアタッチすると、深度バッファリングが有効になっている場合、システムは常に、この深度バッファを自動的に使用する。これについては、「ステップ 4 : 深度バッファリングを有効にする」で説明する。


ステップ 4 : 深度バッファリングを有効にする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

深度バッファをレンダリング ターゲット サーフェスにアタッチすると、レンダリング ターゲットからレンダリング デバイスを作成することができる。

深度バッファを使用するアプリケーションでは、ビューポートと深度バッファの両方をクリアする必要がある。深度バッファをクリアするには、Direct3DDevice7.Clear メソッドで D3DCLEAR_ZBUFFER フラグを指定する。

g_d3dDevice.Clear 1, g_d3drcViewport(), D3DCLEAR_TARGET Or D3DCLEAR_ZBUFFER, &HFF, 1, 0

レンダリング デバイスが用意されると、そのデバイスの D3DREMDERSTATE_ZENABLE レンダリング ステートを設定して、深度バッファリングを有効にすることができる。CONST_D3DZBUFFERTYPE 列挙型には、深度バッファのレンダリング ステートを設定するメンバが含まれている。メンバ D3DZB_TRUE (または TRUE) により、z バッファリングを有効にする。サンプル Zbuffer は、アプリケーション定義サブルーチン RenderScene でのシーンのレンダリング中に、z バッファリングを有効にしている。次のコードは、RenderScene からの該当部分の抜粋である。

g_d3dDevice.SetRenderState D3DRENDERSTATE_ZENABLE, D3DZB_TRUE

このチュートリアルでは、フレーム単位に深度バッファリングを有効にしているが、これは必須ではない。実際のアプリケーションでは、シーンの初期化中に D3DRENDERSTATE_ZENABLE レンダリング ステートを設定しておき、深度バッファリングを無効にしたり、深度バッファリングの別のタイプを選択するときにだけ変更するのが普通である。

注 : D3DZBUFFERTYPE 列挙型は、準拠ハードウェア上での w ベースの深度照合を有効にする D3DZB_USEW 値を含んでいる。詳細については、「深度バッファ」を参照すること。


チュートリアル 3 : さまざまなプリミティブ スタイルを使用する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、Direct3D Visual Basic によって提供される、さまざまな描画プリミティブ呼び出しを使ってポリゴンをレンダリングする方法を示す。このチュートリアルのプリミティブは、閉じたポリゴンの、少なくとも 3 頂点で識別される 3D オブジェクトである。このチュートリアルでは、サンプル DrawPrims を使用する。

このチュートリアルでは主に、一連のプリミティブ (壁セグメント、円錐、立方体) のジオメトリを準備する方法、視点を回転する方法、および行列連結を使って 3D トランスフォーム (立方体の平行移動、回転、スケール) を実行する方法について説明する。

  • ステップ 1 : シーン ジオメトリを初期化する
  • ステップ 2 : シーンをレンダリング、表示する

3D プリミティブの詳細については、「3D プリミティブ」を参照すること。

注 : サンプル DrawPrims のコードは、サンプル Triangle のコードに類似している。このチュートリアルでは、ジオメトリの準備と、サンプル DrawPrim に特有なレンダリング コードだけを取り上げ、Direct3d のセット アップ、シャット ダウン、システム イベントの処理については説明しないものとする。これらのタスクについては、「チュートリアル 1 : 単一の三角形をレンダリングする」を参照すること。

このチュートリアルでは、深度バッファを使ってシーンの深度情報を保存する。深度バッファを使用するには、サポートされている深度バッファ フォーマットを列挙し、深度バッファ サーフェスを作成して、レンダリング ターゲット サーフェスに深度バッファ サーフェスをアタッチした後、レンダリング デバイスの深度バッファリングを有効にしなければならない。これらのタスクについては、「チュートリアル 2 : 深度バッファを追加する」を参照すること。


ステップ 1 : シーン ジオメトリを初期化する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、アプリケーション定義サブルーチン InitGeometry でプリミティブのジオメトリを準備する。InitGeometry は、各オブジェクトの頂点を定義し、各プリミティブの頂点情報をグローバルに定義されたデータ構造体に保持する。この頂点情報は、レンダリング時にDrawPrimitive メソッド によって使用される。

技術的には、この時点でジオメトリのセット アップを行う必要はない。ジオメトリのセット アップは、メソッドの呼び出し前に随時実行できる。

  • ステップ 1.1 : 壁セグメントを準備する
  • ステップ 1.2 : 円錐を準備する
  • ステップ 1.3 : 立方体を準備する

プリミティブの種類の詳細については、「プリミティブの種類」を参照すること。

Direct3D での頂点の指定については、「頂点フォーマット」を参照すること。

注 : プリミティブのジオメトリを準備した順序は、シーン内のオブジェクトのレイアウトには影響しない。


ステップ 2 : シーンをレンダリング、表示する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

シーン内のオブジェクトを適切に表示および操作するには、シーンのビューを更新し、必要なトランスフォームを行い、完成したシーンをレンダリングする必要がある。これらのタスクについては、次のステップで説明する。

  • ステップ 2.1 : シーンを更新する
  • ステップ 2.2 : 3D トランスフォームを実行する
  • ステップ 2.3 : シーンをレンダリングする

プリミティブのレンダリングについては、「プリミティブのレンダリング」を参照すること。


チュートリアル 4 : デバイス列挙を使用する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

デバイス列挙を使用すると、ハードウェアがサポートする Direct3D デバイスを照会することができる。これにより、特定のハードウェア構成を使用するアプリケーションを作成したり、ユーザーのハードウェアでサポートされる構成を選択することができる。このチュートリアルでは、システムのドライバ、ディスプレイ モード、およびデバイスを列挙し、各デバイスでサポートされるディスプレイ モードのリストを作成する。

基本的に、デバイス列挙は次の 2 つのステップ、(1) デバイス列挙の開始と終了、(2) 列挙されたデバイスの選択、に分けることができる。

このチュートリアルでは、これらのステップが以下のステップに対応する。

  • ステップ 1 : デバイス列挙を開始、終了する
  • ステップ 2 : 列挙されたデバイスの選択

Direct3D デバイスの詳細については、「Direct3D デバイス」を参照すること。

デバイスの列挙については、「Direct3D デバイスの列挙」を参照すること。

注 : サンプル Enumeration のコードは、サンプル Triangle のコードに類似している。このチュートリアルでは、サンプル Enumeration に特有なデバイス列挙コードだけを取り上げ、Direct3D のセット アップ、シーン ジオメトリの準備、シャット ダウン、システム イベントの処理については説明しないものとする。これらのタスクについては、「チュートリアル 1 : 単一の三角形をレンダリングする」を参照すること。

このチュートリアルでは、深度バッファを使ってシーンの深度情報を保存する。深度バッファを使用するには、サポートされている深度バッファ フォーマットを列挙し、深度バッファ サーフェスを作成して、レンダリング ターゲット サーフェスに深度バッファ サーフェスをアタッチした後、レンダリング デバイスの深度バッファリングを有効にしなければならない。これらのタスクについては、「チュートリアル 2 : 深度バッファを追加する」を参照すること。

このチュートリアルでは、一連の円錐プリミティブを描画する。プリミティブの描画については、チュートリアル 3 : さまざまなプリミティブ スタイルを使用する」を参照すること。


ステップ 1 : デバイス列挙を開始、終了する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでは、列挙クラスへの参照を取得することによって列挙を開始する。このチュートリアルでは、次の列挙クラスへの参照を宣言する必要がある。

  • DirectDrawEnum
  • DirectDrawEnumModes
  • Direct3DEnumDevices

アプリケーションのデバイス列挙処理は、以下のステップに分けることができる。

  • ステップ 1.1 : ドライバ情報を列挙する
  • ステップ 1.2 : ディスプレイ モード情報を列挙する
  • ステップ 1.3 : デバイス情報を列挙する

デバイス列挙を使用するアプリケーションの最初のステップは、DirectDraw ドライバへの参照の取得である。サンプル Enumeration では、次のアプリケーション定義サブルーチン呼び出しを使って、DirectDraw で使用できるドライバを列挙する。

' ドライバ情報を取得する。
EnumDriver

ドライバの列挙については、「ステップ 1.1 :ドライバ情報を列挙する」で説明する。

デバイス列挙の開始については、「デバイス列挙の開始」を参照すること。


ステップ 2 : 列挙されたデバイスの選択

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

通常、次のステップによって列挙されたデバイスの選択。

  • ステップ 2.1 : デバイスを取得する
  • ステップ 2.2 : デバイスをテストする

サンプル Enumeration では、次のアプリケーション定義サブルーチン呼び出しを使って、列挙されたデバイスを選択し、そのデバイスでサポートされているディスプレイ モードのリストを作成する。

' 列挙されたデバイスを選択し、そのデバイスで
' サポートされるディスプレイ モードのリストを作成する。
SelectDisplayModes

列挙されたデバイスの取得については、ステップ 2.1 : デバイスを取得する」で説明する。

列挙されたデバイスの選択については、「列挙されたデバイスの選択」を参照すること。


チュートリアル 5 : テクスチャ マップを使用する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、テクスチャを使って簡単な 3Ｄ シーンを描画する方法について説明する。基本的に、Direct3D テクスチャはピクセル カラーのビットマップなので、Direct3D プリミティブにビットマップ イメージを適用することができる。テクスチャは簡単に使用でき、3Ｄ オブジェクトのジオメトリを変更することなく、3D シーンをよりリアルに見せることができる。このように、テクスチャを使用すると、プリミティブのカラー パターンとイリュージョン、粗さや滑らかさ、透過性を強化できる。このチュートリアルでは、ファイル ベースのビットマップからテクスチャを作成する方法と、テクスチャを適用した立方体のプリミティブをレンダリングする方法を中心に説明する。

Direct3D for Visual Basic では、テクスチャ ハンドルを使用しないので注意する。その代わりに、テクスチャ サーフェスの作成時にテクスチャ サーフェス オブジェクトへの参照を取得する。

3D シーンでプリミティブにテクスチャを追加するには、次のステップを実行する。

  • ステップ 1 : テクスチャを適用したサーフェスを作成する
  • ステップ 2 : テクスチャを適用したプリミティブをレンダリングする

Direct3D では、広範なテクスチャリング機能をサポートしているので、開発者は高度なテクスチャリング技法を容易に利用することができる。テクスチャの使用法と Direct3D での最適化については、「テクスチャ」を参照すること。

注 : サンプル Texture のコードは、サンプル Triangle のコードに類似している。このチュートリアルでは、サンプル Texture に特有なコードだけを取り上げ、Direct3D のセット アップ、シーン ジオメトリの準備、シャット ダウン、システム イベントの処理については説明しないものとする。これらのタスクについては、チュートリアル 1 : 単一の三角形をレンダリングする」を参照すること。

サンプル Texture では、立方体のプリミティブを描画する。プリミティブの描画方法については、「チュートリアル 3 : さまざまなプリミティブ スタイルを使用する」を参照すること。

サンプル Texture では、テクスチャ フォーマットの列挙を使用する。列挙の原理と方法については、「チュートリアル 4 : デバイス列挙を使用する」を参照すること。


ステップ 1 : テクスチャを適用したサーフェスを作成する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

Direct3D for Visual Basic では、テクスチャの作成と管理タスクが大幅に単純化されてる。3D シーンでシステムの管理下のテクスチャを準備、作成、および実装するには、次のステップを実行する。

  • ステップ 1.1 : テクスチャ座標を設定する
  • ステップ 1.2 : テクスチャ サーフェスを準備する
  • ステップ 1.3 : テクスチャ フォーマットを列挙する
  • ステップ 1.4 : テクスチャに新規サーフェスを作成する

プリミティブにテクスチャを作成する前に、プリミティブの頂点と、そのテクスチャ座標を定義する必要がある。このタスクについては、「ステップ 1.1 : テクスチャ座標を設定する」で説明する。


ステップ 2 : テクスチャを適用したプリミティブをレンダリングする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

テクスチャを適用したプリミティブと適用していないプリミティブをレンダリングする際の相違は、テクスチャを適用したプリミティブは、レンダリング時にテクスチャを設定しなければならないことだけである。

サンプル Texture の次のコードでは、テクスチャ サーフェス g_ddsTexture1: を使って、立方体の前面と背面を描画する。

g_d3dDevice.SetTexture 0, g_ddsTexture1
Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX, g_vCube(0), _
4, D3DDP_DEFAULT)
Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX, g_vCube(4), _
4, D3DDP_DEFAULT)

立方体の上面と底面、および左面と右面にも、それぞれ g_ddsTexture2 と g_ddsTexture3 を設定して、同じ手順を実行する必要がある。この手順については、SDK のサンプル Texture コードを参照すること。

Direct3DDevice7.SetTexture メソッドは、デバイスの所定のステージにテクスチャを割り当てる。このチュートリアルでは、マルチ テクスチャ ブレンディングを使用しないので、ステージ識別子となる最初のパラメータ SetTexture が 0 になっている。2 番目のパラメータは、テクスチャとして設定される DirectDrawSurface7 オブジェクトを示す。

テクスチャ サーフェスを使ったレンダリングについては、「テクスチャ サーフェスを使用したレンダリング」を参照すること。

マルチ テクスチャのブレンドについては、「マルチ テクスチャ ブレンディング」を参照すること。


Direct3D 直接モード リファレンス

ここでは、C/C++ および Microsoft Visual Basic® プログラミング言語で Microsoft® Direct3D® 直接モードが提供するアプリケーション プログラミング インターフェイス (API) 要素のリファレンス情報を記述する。リファレンス情報は以下の言語別に構成される。

  • Direct3D 直接モード C/C++ リファレンス
  • Direct3D 直接モード Visual Basic リファレンス


Direct3D 直接モード C/C++ リファレンス

ここでは、Direct3D 直接モードが提供する API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • インターフェイス
  • D3D_OVERLOADS
  • コールバック関数
  • マクロ
  • 構造体
  • 列挙型
  • その他の型
  • 柔軟な頂点フォーマット フラグ
  • 戻り値


インターフェイス

ここでは、Direct3D 直接モードが提供する COM インターフェイスのリファレンス情報を記述する。Direct3D 直接モードで使用される主なインターフェイスは、以下のとおりである。

  • IDirect3D7
  • IDirect3DDevice7
  • IDirect3DVertexBuffer7

注 : Direct3D では、テクスチャ用の個別のインターフェイスは不要である。現在、Direct3D のすべてのテクスチャ関連メソッドは、サーフェスがテクスチャ能力 (DDSCAPS_TEXTURE) を使用して作成されていれば IDirectDrawSurface7 インターフェイスへのポインタを受け取るようになっている。

実行バッファを必要とするアプリケーションでは、DirectX の旧リリースで提供されていたインターフェイスを使用しなければならない。

DirectX の従来のリリースで提供されていたスタブ メソッドのうちの一部は、現在提供されていない。詳細については、「実装されていないメソッド」を参照すること。

新しい IDirect3DDevice7 インターフェイスには、IDirect3DLight、IDirect3DMaterial3、および IDirect3DViewport3 インターフェイスに代わって使用されるメソッドが含まれる。詳細については、「廃止されたインターフェイス」を参照すること。これらのインターフェイスについてのドキュメントは、DirectX の旧リリースから入手できる。


IDirect3D7

アプリケーションは、IDirect3D7 インターフェイスのメソッドを使って、Direct3D オブジェクトを作成し、オブジェクトの環境をセット アップする。ここでは、IDirect3D7 インターフェイスのメソッドについてのリファレンス情報を記述する。概要については、「Direct3D インターフェイス」を参照すること。

IDirect3D7 インターフェイスは、DirectDraw オブジェクトから QueryInterface メソッドを呼び出すことにより得られる。

IDirect3D7 インターフェイスのメソッドは、以下のグループにまとめることができる。

生成 | CreateDevice
 | CreateVertexBuffer
列挙 | EnumDevices
 | EnumZBufferFormats
その他 | EvictManagedTextures

IDirect3D7 インターフェイスは、IDirect3D3 インターフェイスを簡略化したものであり、デバイスおよび頂点バッファを作成する場合を除いては、オブジェクト作成用メソッドが必要ない。IDirect3D3 インターフェイスとは異なり、IDirect3D7 には IDirect3D7::CreateLight、IDirect3D7::CreateMaterial、および IDirect3D7::CreateViewport メソッドが存在しない。これらのメソッドの機能性は、現在では IDirect3DDevice7 インターフェイスに含まれている。

すべての COM インターフェイスと同様、IDirect3D7 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3D7、LPDIRECT3D3、LPDIRECT3D2、および LPDIRECT3D 型は、IDirect3D7、IDirect3D7、IDirect3D2、および IDirect3D インターフェイスへのポインタとして定義される。

typedef struct IDirect3D    *LPDIRECT3D;
typedef struct IDirect3D2   *LPDIRECT3D2;
typedef struct IDirect3D3   *LPDIRECT3D3;
typedef struct IDirect3D7   *LPDIRECT3D7;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

Direct3D へのアクセス、Direct3D と DirectDraw


IDirect3D7::CreateDevice

IDirect3D7::CreateDevice メソッドは、DrawPrimitive メソッドに使用するために、Direct3D デバイスを生成する。

HRESULT CreateDevice(
  REFCLSID rclsid,
  LPDIRECTDRAWSURFACE7 lpDDS,
  LPDIRECT3DDEVICE7 *  lplpD3DDevice,
);

パラメータ

rclsid
新しいデバイスに対するクラス識別子。この値は、IID_IDirect3DTnLHalDevice、IID_IDirect3DHALDevice、IID_IDirect3DMMXDivice、または IID_IDirect3DRGBDevice である。ランプ エミュレーション デバイス用の IID_IDirect3DRampDevice は、IDirect3D2 以降のインターフェイスではサポートされない。ランプ エミュレーションを用いるときは、従来の IDirect3D2 インターフェイスを用いること。
lpDDS
デバイスのレンダリング ターゲットとなる DirectDrawSurface オブジェクトの IDirectDrawSurface7 インターフェイスのアドレス。DDSCAPS_3DDEVICE 能力を用いてサーフェスは 3-D デバイスとして生成された。
lplpD3DDevice
メソッドが返ったときに、新しい IDirect3DDevice7 インターフェイスをポイントするポインタのアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合には、DDERR_INVALIDPARAMS を返す。

注意

特定の Direct3D オブジェクトによって生成されるレンダリング デバイスは、同じ物理リソースを共有する。アプリケーションで単一の Direct3D オブジェクトから複数のレンダリング デバイスを作成できる場合でも、これらのデバイスは同じハードウェアを共有するため、パフォーマンスが著しく低下する。

従来の IDirect3D3 インターフェイスでは、このメソッドは IDirectDrawSurface4 および IDirect3DDevice3 インターフェイスへのポインタを受け取った。

IDirect3D7::CreateDevice を呼び出すと、DirectDraw サーフェス オブジェクトとは別個のデバイス オブジェクトを作成できる。このデバイスは、DirectDraw サーフェスをレンダリング ターゲットとして使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7、Direct3D デバイスの作成、Direct3D デバイス


IDirect3D7::CreateVertexBuffer

IDirect3D7::CreateVertexBuffer メソッドは、頂点バッファ オブジェクトを作成する。

HRESULT CreateVertexBuffer(
  LPD3DVERTEXBUFFERDESC    lpVBDesc,
  LPDIRECT3DVERTEXBUFFER7* lplpD3DVertexBuffer,
  DWORD dwFlags
);

パラメータ

lpVBDesc
頂点バッファが受け取る頂点のフォーマットおよび個数を記述する D3DVERTEXBUFFERDESC 構造体のアドレス。
lplpD3DVertexBuffer
新しい頂点バッファの IDirect3DVertexBuffer7 インターフェイスへのポインタを受け取る変数のアドレス。
dwFlags
このメソッドのために現在定義されているフラグはない。このパラメータには 0 を設定する。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

CLASS_E_NOAGGREGATION
D3DERR_INVALIDVERTEXFORMAT
D3DERR_VBUF_CREATE_FAILED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

このメソッドは、IDirect3D3 インターフェイスと共に導入された。IDirect3D3 の一部として、このメソッドは従来の IDirect3DVertexBuffer インターフェイスへのポインタおよび dwFlags パラメータに指定されるフラグを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DVertexBuffer7、頂点バッファ


IDirect3D7::EnumDevices

IDirect3D7::EnumDevices メソッドは、システムにインストールされている Direct3D デバイス ドライバをすべて列挙する。

HRESULT EnumDevices(
  LPD3DENUMDEVICESCALLBACK7 lpEnumDevicesCallback,
  LPVOID lpUserArg
);

パラメータ

lpEnumDevicesCallback
条件が一致するたびに列挙プロシージャが呼び出す D3DEnumDevicesCallback7 コールバック関数のアドレス。
lpUserArg
コールバック関数に渡されるアプリケーション定義データのアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

IDirect3D3 インターフェイスでは、このメソッドは D3DEnumDevicesCallback 関数へのポインタを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3D7::EnumZBufferFormats

IDirect3D7::EnumZBufferFormats メソッドは、指定されたデバイスがサポートしている深度バッファ フォーマットを列挙する。

HRESULT EnumZBufferFormats(
  REFCLSID riidDevice,
  LPD3DENUMPIXELFORMATSCALLBACK lpEnumCallback,
  LPVOID   lpContext
);

パラメータ

riidDevice
深度バッファ フォーマットが列挙されるデバイスのグローバル ユニーク識別子への参照。
lpEnumCallback
サポートされている深度バッファ フォーマットごとに呼び出される D3DEnumPixelFormatsCallback コールバック関数のアドレス。
lpContext
コールバック関数に渡されるアプリケーション定義データ。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3D7::EvictManagedTextures

IDirect3D7::EvictManagedTextures メソッドは、ローカルまたは非ローカル ビデオ メモリから管理下のテクスチャをすべて削除する。

HRESULT EvictManagedTextures();

パラメータ

なし。

戻り値

D3D_OK を返す。

注意

このメソッドを使用すると、Direct3D は、DDSCAPS2_TEXTUREMANAGE または DDSCAPS2_D3DTEXTUREMANAGE フラグで作成されたテクスチャ サーフェスを、ローカルまたは非ローカル ビデオ メモリから削除する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

自動テクスチャ管理


IDirect3DDevice7

IDirect3DDevice7 インターフェイスには、アプリケーションで DrawPrimitive ベースのレンダリングを可能にするメソッドがある。この点については、IDirect3DDevice インターフェイスの場合、アプリケーションが実行バッファを使用してレンダリングするのと対照的である。IDirect3D7::CreateDevice メソッドを呼び出すことにより、Direct3DDevice オブジェクトを作成して、このインターフェイスへのポインタを取得できる。

概要については、「Direct3D デバイス」および「DrawPrimitive メソッド」を参照すること。

IDirect3DDevice7 インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetCaps
 | GetDirect3D
 | GetInfo
デバイス ステート | ApplyStateBlock
 | BeginStateBlock
 | CaptureStateBlock
 | CreateStateBlock
 | DeleteStateBlock
 | EndStateBlock
 | GetClipStatus
 | GetRenderState
 | GetRenderTarget
 | GetStateData
 | GetTransform
 | SetClipStatus
 | SetRenderState
 | SetRenderTarget
 | SetStateData
 | SetTransform
ライティングとマテリアル | GetLight
 | GetLightEnable
 | GetMaterial
 | LightEnable
 | SetLight
 | SetMaterial
その他 | ComputeSphereVisibility
 | MultiplyTransform
レンダリング | DrawIndexedPrimitive
 | DrawIndexedPrimitiveStrided
 | DrawIndexedPrimitiveVB
 | DrawPrimitive
 | DrawPrimitiveStrided
 | DrawPrimitiveVB
シーン | BeginScene
 | EndScene
テクスチャ | EnumTextureFormats
 | GetTexture
 | GetTextureStageState
 | Load
 | PreLoad
 | SetTexture
 | SetTextureStageState
 | ValidateDevice
ユーザー定義クリップ面 | GetClipPlane
 | SetClipPlane
ビューポート | Clear
 | GetViewport
 | SetViewport

すべての COM インターフェイスと同様、IDirect3DDevice7 インターフェイスはIUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

このインターフェイスは、デバイス ステート ブロック用のメソッドを加えることで IDirect3DDevice3 インターフェイスを拡張している。デバイス ステート ブロックにより、アプリケーションが要求する共通した一連のステート変化をすばやく実行できる。また、IDirect3DDevice7 インターフェイスには、デバイス内のビューポート、ライト、およびマテリアルを操作するメソッドがあり、これらのメソッドが IDirect3DViewport3、IDirect3DMaterial3、および IDirect3DLight インターフェイスに代わって使用される。

このインターフェイスと以前の IDirect3DDevice3 インターフェイスで共通する多くのメソッドでは、受け取るパラメータに若干の違いがある。IDirect3DDevice3 インターフェイス メソッドは IDirectDrawSuface3 インターフェイスへのポインタをパラメータとして受け取り、IDirect3DDevice7 インターフェイス メソッドは IDirectDrawSurface7 インターフェイスへのポインタを受け取る。これまで IDirect3DVertexBuffer または IDirect3DTexture2 インターフェイスへのポインタを受け取っていたメソッドは、現在では IDirect3DVertexBuffer7 または IDirectDrawSurface7 インターフェイスへのポインタを受け取るようになっている。インターフェイスに追加されたビューポート、マテリアル、およびライティング用のメソッドは、新しい構造体へのポインタを受け取る。これらの構造体については、それぞれの新しいメソッドのリファレンス ページで説明する。

このインターフェイスは、実行バッファと共に使用することを考慮していないので、実行バッファ関連のメソッドは一切持っていない。実行バッファについては、旧リリースの DirectX のドキュメントを参照すること。

LPDIRECT3DDEVICE2、LPDIRECT3DDEVICE3、または LPDIRECT3DDEVICE7 データ型を使用して、IDirect3DDevice2、IDirect3DDevice3、または IDirect3DDevice7 インターフェイスへのポインタを格納する変数を宣言できる。d3d.h ヘッダー ファイルは、以下のコードでこれらのデータ型を宣言している。

typedef struct IDirect3DDevice2    *LPDIRECT3DDEVICE2;
typedef struct IDirect3DDevice3    *LPDIRECT3DDEVICE3;
typedef struct IDirect3DDevice7    *LPDIRECT3DDEVICE7;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

Direct3D デバイス、レンダリング


IDirect3DDevice7::ApplyStateBlock

IDirect3DDevice7::ApplyStateBlock メソッドは、既存のデバイス ステート ブロックをレンダリング デバイスに適用する。

HRESULT ApplyStateBlock(
  DWORD dwBlockHandle
);

パラメータ

dwBlockHandle
実行するデバイス ステート ブロックへのハンドル。これは前に呼び出した IDirect3DDevice7::EndStateBlock メソッドによって返される。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INBEGINSTATEBLOCK
D3DERR_INVALIDVERTEXTYPE

注意

アプリケーションで別のブロックを記録しているときに、デバイス ステート ブロックを適用することはできない。

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

レンダリング デバイスのステートに影響するすべての処理と同様、ステート ブロックの適用は、シーンのレンダリング中、つまり IDirect3DDevice7::BeginScene メソッドを呼び出してから IDirect3DDevice7::EndScene を呼び出すまでの間に行うことを推奨する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::BeginStateBlock、IDirect3DDevice7::EndStateBlock、IDirect3DDevice7::CaptureStateBlock、IDirect3DDevice7::CreateStateBlock、IDirect3DDevice7::DeleteStateBlock、ステート ブロック


IDirect3DDevice7::BeginScene

IDirect3DDevice7::BeginScene メソッドはシーンを開始する。アプリケーションでは、レンダリングを実行する前には必ずこのメソッドを呼び出し、レンダリングの終了時および再度 IDirect3DDevice7::BeginScene を呼び出す前には必ず IDirect3DDevice7::EndScene を呼び出す。

HRESULT BeginScene();

パラメータ

なし。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。Direct3D 直接モードのエラー値およびその説明については、「戻り値」を参照すること。

注意

BeginScene メソッドが失敗すると、デバイスはシーンを開始できないため、IDirect3DDevice7::EndScene メソッドを呼び出す必要はない。実際、その前の BeginScene の呼び出しが失敗すると、IDirect3DDevice7::EndScene メソッドの呼び出しも失敗する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::EndScene、シーンの開始と終了


IDirect3DDevice7::BeginStateBlock

IDirect3DDevice7::BeginStateBlock メソッドは、Direct3D にデバイス ステート ブロックの記録を開始するように知らせる。

HRESULT BeginStateBlock();

パラメータ

なし。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INBEGINSTATEBLOCK
DDERR_OUTOFMEMORY

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

アプリケーションでは、このメソッドを呼び出す前に IDirect3DDevice7::ValidateDevice メソッドを呼び出して、記録するすべてのステートが有効であることを確認できる。

ステート ブロック (IDirect3DDevice7::BeginStateBlock を呼び出してから IDirect3DDevice7::EndStateBlock を呼び出すまで) に記録できるメソッドは以下のとおりである。

  • IDirect3DDevice7::LightEnable
  • IDirect3DDevice7::SetClipPlane
  • IDirect3DDevice7::SetLight
  • IDirect3DDevice7::SetMaterial
  • IDirect3DDevice7::SetRenderState
  • IDirect3DDevice7::SetTexture
  • IDirect3DDevice7::SetTextureStageState
  • IDirect3DDevice7::SetTransform
  • IDirect3DDevice7::SetViewport

ステート ブロック内では、ステート変更の順序は保証されない。ステート ブロックで同じステートが複数回指定された場合、使用されるのは最後の値のみである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::ApplyStateBlock、IDirect3DDevice7::EndStateBlock、IDirect3DDevice7::CaptureStateBlock、IDirect3DDevice7::CreateStateBlock、IDirect3DDevice7::DeleteStateBlock、ステート ブロック


IDirect3DDevice7::CaptureStateBlock

IDirect3DDevice7::CaptureStateBlock メソッドは、既存のステート ブロック内の値を、デバイスに現在設定されている値に更新する。

HRESULT CaptureStateBlock(
  DWORD dwBlockHandle
);

パラメータ

dwBlockHandle
現在のデバイス ステートを取り込むステート ブロックへのハンドル。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、標準のエラー コードを返すか、ステート ブロックの記録中であれば D3DERR_INBEGINSTATEBLOCK を返す。

注意

このメソッドは、既存のステート ブロックに含まれるステートの更新後の値を取り込む。デバイス全体のステートは取り込まない。詳細については、「ステート ブロックの取得」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::ApplyStateBlock、IDirect3DDevice7::BeginStateBlock、IDirect3DDevice7::CreateStateBlock、IDirect3DDevice7::EndStateBlock、IDirect3DDevice7::DeleteStateBlock、ステート ブロック、ステート ブロックの取得


IDirect3DDevice7::CreateStateBlock

IDirect3DDevice7::CreateStateBlock メソッドは、すべてのデバイス ステート、頂点関連のステート、またはピクセル関連のステートの現在の値を含む新しいステート ブロックを作成する。

HRESULT CreateStateBlock(
  D3DSTATEBLOCKTYPE d3dsbType,
  LPDWORD lpdwBlockHandle
);

パラメータ

d3dsbType
メソッドで取り込むステート データの種類。このパラメータは、D3DSTATEBLOCKTYPE 列挙型に定義される値のいずれかに設定する。
lpdwBlockHandle
メソッドが成功した場合に、ステート ブロックのハンドルを格納する変数のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INBEGINSTATEBLOCK
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

頂点関連のデバイス ステートとは、一般にはシステムの頂点の処理方法に影響するステートをいう。ピクセル関連のステートとは、ラスタ化におけるシステムのピクセルまたは深度バッファの処理方法に影響するデバイス ステートをいう。ステートによっては両方に属する場合もある。個々のステートの詳細については、「事前定義するステート ブロックの作成」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::ApplyStateBlock、IDirect3DDevice7::BeginStateBlock、IDirect3DDevice7::CaptureStateBlock、IDirect3DDevice7::EndStateBlock、IDirect3DDevice7::DeleteStateBlock、ステート ブロック


IDirect3DDevice7::Clear

IDirect3DDevice7::Clear メソッドは、ビューポート (またはビューポート内の矩形セット) を特定の RGBA 色にクリア、深度バッファをクリア、およびステンシル バッファを削除する。このメソッドは、従来の IDirect3DViewport3 インターフェイスが公開したクリアメソッドに代わって使用される。

HRESULT Clear(
  DWORD     dwCount,
  LPD3DRECT lpRects,
  DWORD     dwFlags,
  DWORD     dwColor,
  D3DVALUE  dvZ,
  DWORD     dwStencil
);

パラメータ

dwCount
lpRects の配列にある矩形の数。lpRects を NULL に設定する場合は、このパラメータを 0 に設定する。
lpRects
クリアする矩形を記述する D3DRECT 構造体の配列。矩形をレンダリング ターゲットの寸法に設定すると、サーフェス全体がクリアされる。各矩形は、レンダリング ターゲット サーフェス上の点に対応するスクリーン座標を使用する。座標はビューポートの矩形の境界でクリップされる。このパラメータを NULL に設定すると、ビューポート矩形全体をクリアすることになる。
dwFlags
クリアするサーフェスを示すフラグ。このパラメータは、次のフラグの任意の組み合わせを取ることができるが、フラグを最低 1 つは使わなければならない。
D3DCLEAR_TARGET
レンダリング ターゲットをクリアして、dwColor パラメータの色にする。
D3DCLEAR_STENCIL
ステンシル バッファをクリアして、dwStencil パラメータの値にする。
D3DCLEAR_ZBUFFER
深度バッファをクリアして、dvZ パラメータの値にする。
dwColor
レンダリング ターゲット サーフェスをクリアする 32 ビット RGBA カラー値。
dvZ
このメソッドが深度バッファに保存する新しい z 値。このパラメータには 0.0 から 1.0 までの値を使用できる (Z ベースまたは W ベースの深度バッファの場合)。0.0 はビューアに最も近い距離、1.0 は最も遠い距離を表す。
dwStencil
各ステンシル バッファのエントリに保存する整数値。このパラメータには 0 から 2n-1 までの値を使用できる。n はステンシル バッファのビット深度。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_STENCILBUFFER_NOTPRESENT
D3DERR_VIEWPORTHASNODEVICE
D3DERR_ZBUFFER_NOTPRESENT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

このメソッドは、レンダリング ターゲットに深度バッファがアタッチされていないときに D3DCLEAR_ZBUFFER または D3DCLEAR_STENCIL フラグを指定すると失敗する。同様に、深度バッファ フォーマットにステンシル バッファ情報が含まれていない場合、D3DCLEAR_STENCIL フラグを指定すると、このメソッドは失敗する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DDevice7::ComputeSphereVisibility

IDirect3DDevice7::ComputeSphereVisibility メソッドは、このデバイスの現在のビューポートにおける球の配列の可視性 (完全、一部、不可視) を計算する。

HRESULT ComputeSphereVisibility(
  LPD3DVECTOR lpCenters,
  LPD3DVALUE  lpRadii,
  DWORD       dwNumSpheres,
  DWORD       dwFlags,
  LPDWORD     lpdwReturnValues
);

パラメータ

lpCenters
ワールド空間座標における、各球の中心点を記述する D3DVECTOR 構造体の配列。
lpRadii
各球の半径を表す D3DVALUE 変数の配列。
dwNumSpheres
球の数。0 より大きな値を設定する。
dwFlags
現在は使用されていない。0 を設定する。
lpdwReturnValues
DWORD 値の配列。この配列は初期化の必要はないが、テストされる球ごとに DWORD を含むことができる大きさがなければならない。このメソッドが返ると、配列の各要素には、このデバイスの現在のビューポートにおける球の可視性を示すフラグの組み合わせが格納される。球の可視性が完全の場合、lpdwReturnValues の対応するエントリは 0 になる。以下に示すフラグを組み合わせて配列に与えることができる。

基本クリッピング フラグ

D3DCLIP_BACK
すべての頂点を視錐台の背面でクリッピングする。
D3DCLIP_BOTTOM
すべての頂点を視錐台の底面でクリッピングする。
D3DCLIP_FRONT
すべての頂点を視錐台の前面でクリッピングする。
D3DCLIP_LEFT
すべての頂点を視錐台の左側面でクリッピングする。
D3DCLIP_RIGHT
すべての頂点を視錐台の右側面でクリッピングする。
D3DCLIP_TOP
すべての頂点を視錐台の上面でクリッピングする。
D3DCLIP_GEN0 through D3DCLIP_GEN5
すべての頂点を対応するアプリケーション定義クリップ面でクリッピングする。

組み合わせと一般フラグ

D3DSTATUS_CLIPINTERSECTIONALL
すべての CLIPINTERSECTION フラグの組み合わせ。
D3DSTATUS_CLIPUNIONALL
すべての CLIPUNION フラグの組み合わせ。
D3DSTATUS_DEFAULT
D3DSTATUS_CLIPINTERSECTIONALL と D3DSTATUS_ZNOTVISIBLE フラグの組み合わせ。この値が、デフォルトである。
D3DSTATUS_ZNOTVISIBLE
レンダリングされたプリミティブが不可視であることを示す。このフラグは、Z チェックを使用するレンダリングを実行する際、システムによって設定またはクリアされる (D3DRENDERSTATE_ZVISIBLE を参照すること)。

クリップ交差フラグ

D3DSTATUS_CLIPINTERSECTIONBACK
視錐台の後方クリップ面の頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONBOTTOM
視錐台の下の頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONFRONT
視錐台の前方クリップ面の頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5
アプリケーション定義クリップ面のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONLEFT
視錐台の左側の頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONRIGHT
視錐台の右側の頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONTOP
視錐台の上の頂点のクリップ フラグの論理積をとる。

クリップ結合フラグ

D3DSTATUS_CLIPUNIONBACK
D3DCLIP_BACK と同じ。
D3DSTATUS_CLIPUNIONBOTTOM
D3DCLIP_BOTTOM と同じ。
D3DSTATUS_CLIPUNIONFRONT
D3DCLIP_FRONT と同じ。
D3DSTATUS_CLIPUNIONGEN0 through D3DSTATUS_CLIPUNIONGEN5
D3DCLIP_GEN0 から D3DCLIP_GEN5 と同じ。
D3DSTATUS_CLIPUNIONLEFT
D3DCLIP_LEFT と同じ。
D3DSTATUS_CLIPUNIONRIGHT
D3DCLIP_RIGHT と同じ。
D3DSTATUS_CLIPUNIONTOP
D3DCLIP_TOP と同じ。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDMATRIX
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

球の可視性は、ワールド、ビュー、および射影の合成行列の逆行列を使って視錐台をモデル空間に逆トランスフォームすることにより計算する。この合成行列を逆行列にトランスフォームできない場合 (行列式が 0 の場合) は、メソッドは失敗し、D3DERR_INVALIDMATRIX を返す。

次の C コードは、ComputeSphereVisibility の使用方法を示す。

D3DVECTOR center = {0,0,0};
D3DVALUE  radius = 1;
DWORD result = 0;

res = m_pd3dDevice->ComputeSphereVisibility(&center, &radius, 1, 0, &result);

if (res == D3D_OK)
{
    if (result & D3DSTATUS_CLIPINTERSECTIONALL)
    {
        // 球が外側にある。
        if (result & D3DSTATUS_CLIPINTERSECTIONLEFT)
            printf("Sphere left outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONRIGHT)
            printf("Sphere right outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONTOP)
            printf("Sphere top outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONBOTTOM)
            printf("Sphere bottom outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONFRONT)
            printf("Sphere front outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONBACK)
            printf("Sphere back outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN0)
            printf("Sphere gen0 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN1)
            printf("Sphere gen1 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN2)
            printf("Sphere gen2 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN3)
            printf("Sphere gen3 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN4)
            printf("Sphere gen4 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN5)
            printf("Sphere gen5 outside\n");
        }
    else
    if (result & D3DSTATUS_CLIPUNIONALL)
    {
        // 球が視錘台と交差する。
        if (result & D3DSTATUS_CLIPUNIONLEFT)
            printf("Sphere left intersect\n");
        if (result & D3DSTATUS_CLIPUNIONRIGHT)
            printf("Sphere right intersect\n");
        if (result & D3DSTATUS_CLIPUNIONTOP)
            printf("Sphere top intersect\n");
        if (result & D3DSTATUS_CLIPUNIONBOTTOM)
            printf("Sphere bottom intersect\n");
        if (result & D3DSTATUS_CLIPUNIONFRONT)
            printf("Sphere front intersect\n");
        if (result & D3DSTATUS_CLIPUNIONBACK)
            printf("Sphere back intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN0)
            printf("Sphere gen0 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN1)
            printf("Sphere gen1 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN2)
            printf("Sphere gen2 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN3)
            printf("Sphere gen3 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN4)
            printf("Sphere gen4 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN5)
            printf("Sphere gen5 intersect\n");
    }
    else
    {
        printf("Sphere is inside\n");
    }
}
else
    printf("Invalid return value\n");

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DDevice7::DeleteStateBlock

IDirect3DDevice7::DeleteStateBlock メソッドは、以前に記録したデバイス ステート ブロックを削除する。

HRESULT DeleteStateBlock (
  DWORD dwBlockHandle
);

パラメータ

dwBlockHandle
削除するデバイス ステート ブロックへのハンドル。これは前に呼び出した IDirect3DDevice7::EndStateBlock メソッドによって返される。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INBEGINSTATEBLOCK
D3DERR_INVALIDVERTEXTYPE

注意

別のステート ブロックの記録中に、デバイス ステート ブロックを削除することはできない。

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::ApplyStateBlock、IDirect3DDevice7::BeginStateBlock、IDirect3DDevice7::CaptureStateBlock、IDirect3DDevice7::CreateStateBlock、IDirect3DDevice7::EndStateBlock、ステート ブロック


IDirect3DDevice7::DrawIndexedPrimitive

IDirect3DDevice7::DrawIndexedPrimitive メソッドは、頂点の配列へのインデックスに基づいて、指定されたジオメトリ プリミティブをレンダリングする。

HRESULT DrawIndexedPrimitive(
  D3DPRIMITIVETYPE d3dptPrimitiveType,
  DWORD  dwVertexTypeDesc,
  LPVOID lpvVertices,
  DWORD  dwVertexCount,
  LPWORD lpwIndices,
  DWORD  dwIndexCount,
  DWORD  dwFlags
);

パラメータ

d3dptPrimitiveType
このコマンドによってレンダリングされるプリミティブの型。これは、D3DPRIMITIVETYPE 列挙型のメンバの 1 つでなければならない。

D3DPRIMITIVETYPE の D3DPT_POINTLIST メンバはインデックス付けされない。

dwVertexTypeDesc
このプリミティブ セットの頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせ。
lpvVertices
プリミティブ シーケンスで使用される頂点のリストへのポインタ。
dwVertexCount
リスト中の頂点数を定義する。

このパラメータの使用方法は、IDirect3DDevice7::DrawPrimitive メソッドの dwVertexCount パラメータとは異なる。IDirect3DDevice7::DrawPrimitive メソッドでは、dwVertexCount パラメータは描画すべき頂点数を与えるが、このメソッドは lpvVertices パラメータが指す配列の合計頂点数を与える。IDirect3DDevice7::DrawIndexedPrimitive を呼び出すときには、dwIndexCount パラメータで描画すべき頂点数を指定する。

lpwIndices
レンダリングするジオメトリを作成するときに、指定された頂点リストへのインデックス付けをするのに使用される WORD のリストへのポインタ。
dwIndexCount
ジオメトリを作成するのに用意するインデックス数を指定する。許容される最大インデックス数は D3DMAXNUMVERTICES (0xFFFF) である。
dwFlags
待機せずにプリミティブをレンダリングする場合はゼロ、または以下のフラグを指定する。
D3DDP_WAIT
メソッドは、ポリゴンがカードに送られるとすぐに返るのではなく、レンダリングが終わるまで待つ。(シーン キャプチャ カードでは、カードからの応答があり次第、メソッドは返る。) このフラグはデバッグによく使用される。アプリケーションは、シーンを先に進める前に確実に更新しておくためにも、このフラグを使用するべきではない。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

注意

レンダリングする頂点が、指定した頂点フォーマットと一致していることを確認する。パフォーマンス上の理由から、Direct3D は頂点のサイズおよびストライドと提供された柔軟な頂点フォーマットとの照合を行わない。これが一致していないと、メモリ障害が発生しやすい。

このメソッドは、頂点バッファからのレンダリングには使用せず、代わりに頂点バッファ メソッドを使用する。

このメソッドは、従来のインターフェイスで使用されたメソッドとは異なり、dwFlags パラメータで D3DDP_DONOTCLIP、D3DDP_DONOTLIGHT、および D3DDP_DONOTUPDATEEXTENTS フラグを受け取らない。これらのフラグの機能性は、現在では D3DRENDERSTATE_CLIPPING、D3DRENDERSTATE_LIGHTING、および D3DRENDERSTATE_EXTENTS レンダリング ステートによって使用できる。

極端に大きな頂点配列の非常に小さな部分集合である頂点をレンダリングするのに、このメソッドを使用しないこと。このメソッドは、レンダリングする頂点の位置座標や数に関係なく、指定されたバッファのすべての頂点をトランスフォームする。したがって、数千もの頂点を格納する配列を渡して、そのうち数百の頂点しかレンダリングしないような場合は、アプリケーションのパフォーマンスが著しく低下する。大きなバッファから少数の頂点をレンダリングする必要がある場合は、Direct3D 頂点バッファ レンダリング メソッドを使用する。詳細については、「頂点バッファ」を参照すること。

このメソッドは、対応する IDirect3DDevice2 インターフェイスのものとは、第 2 パラメータとして D3DVERTEXTYPE 列挙型のメンバではなく、柔軟な頂点フォーマットの記述子を使用する点が異なる。D3DVERTEXTYPE のメンバのいずれかを使用しようとすると、このメソッドは失敗し、DDERR_INVALIDPARAMS を返す。詳細については、「頂点フォーマット」を参照すること。

DirectX の現在のバージョンでは、IDirect3DDevice7::DrawIndexedPrimitive が必要以上に大きな更新矩形を生成することがある。多数の頂点数を処理するときには、これはアプリケーションのパフォーマンスに悪影響を与える。D3DTLVERTEX 頂点を使用して、システムで必要以上の頂点を処理する場合は、D3DDP_DONOTCLIP および D3DDP_DONOTUPDATEEXTENTS フラグを使用してこの問題を解決する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::DrawPrimitive、IDirect3DDevice7::DrawPrimitiveStrided、IDirect3DDevice7::DrawPrimitiveVB、IDirect3DDevice7::DrawIndexedPrimitiveStrided、IDirect3DDevice7::DrawIndexedPrimitiveVB


IDirect3DDevice7::DrawIndexedPrimitiveStrided

IDirect3DDevice7::DrawIndexedPrimitiveStrided メソッドは、ストライド頂点の配列へのインデックスに基づいて、ジオメトリ プリミティブをレンダリングする。詳細情報については、「ストライド頂点フォーマット」を参照すること。

HRESULT DrawIndexedPrimitiveStrided(
  D3DPRIMITIVETYPE d3dptPrimitiveType,
  DWORD  dwVertexTypeDesc,
  LPD3DDRAWPRIMITIVESTRIDEDDATA lpVertexArray,
  DWORD  dwVertexCount,
  LPWORD lpwIndices,
  DWORD  dwIndexCount,
  DWORD  dwFlags
);

パラメータ

d3dptPrimitiveType
このコマンドによってレンダリングされるプリミティブの型。これは、D3DPRIMITIVETYPE 列挙型のメンバの 1 つでなければならない。

D3DPRIMITIVETYPE の D3DPT_POINTLIST メンバにはインデックスがない。

dwVertexTypeDesc
このプリミティブの頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせ。
lpVertexArray
このプリミティブの頂点成分のポインタおよびメモリ ストライドを格納する D3DDRAWPRIMITIVESTRIDEDDATA 構造体のアドレス。このときのフォーマットは、dwVertexTypeDesc のフラグで指定するフォーマットである。
dwVertexCount
リスト中の頂点数を定義する。

このパラメータの使用方法は、IDirect3DDevice7::DrawPrimitive メソッドの dwVertexCount パラメータとは異なる。IDirect3DDevice7::DrawPrimitive メソッドでは、dwVertexCount パラメータは描画すべき頂点数を与えるが、このメソッドは lpVertexArray パラメータが指す配列の合計頂点数を与える。IDirect3DDevice7::DrawIndexedPrimitiveStrided を呼び出すときには、dwIndexCount パラメータで描画すべき頂点数を指定する。

lpwIndices
レンダリングするジオメトリを作成するときに、指定された頂点リストへのインデックス付けをするのに使用される WORD のリストへのポインタ。
dwIndexCount
ジオメトリを作成するのに用意するインデックス数を指定する。許容される最大インデックス数は D3DMAXNUMVERTICES (0xFFFF) である。
dwFlags
待機せずにプリミティブをレンダリングする場合はゼロ、または以下のフラグを指定する。
D3DDP_WAIT
メソッドは、ポリゴンがカードに送られるとすぐに返るのではなく、レンダリングが終わるまで待つ。(シーン キャプチャ カードでは、カードからの応答があり次第、メソッドは返る。) このフラグはデバッグによく使用される。アプリケーションは、シーンを先に進める前に確実に更新しておくためにも、このフラグを使用するべきではない。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

注意

レンダリングする頂点が、指定した頂点フォーマットと一致していることを確認する。パフォーマンス上の理由から、Direct3D は頂点のサイズおよびストライドと提供された柔軟な頂点フォーマットとの照合を行わない。これが一致していないと、メモリ障害が発生しやすい。

このメソッドは、頂点バッファからのレンダリングには使用せず、代わりに頂点バッファ メソッドを使用する。

このメソッドは、従来のインターフェイスで使用されたメソッドとは異なり、dwFlags パラメータで D3DDP_DONOTCLIP、D3DDP_DONOTLIGHT、および D3DDP_DONOTUPDATEEXTENTS フラグを受け取らない。これらのフラグの機能性は、現在では D3DRENDERSTATE_CLIPPING、D3DRENDERSTATE_LIGHTING、および D3DRENDERSTATE_EXTENTS レンダリング ステートによって使用できる。

このメソッドは、トランスフォームされた頂点をサポートしない。したがって、D3DFVF_XYZRHW 頂点フォーマット記述子を dwVertexTypeDesc パラメータに含めると、メソッドは失敗し、D3DERR_INVALIDVERTEXTYPE を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::DrawPrimitive、IDirect3DDevice7::DrawPrimitiveStrided、IDirect3DDevice7::DrawPrimitiveVB、IDirect3DDevice7::DrawIndexedPrimitive、IDirect3DDevice7::DrawIndexedPrimitiveVB、ストライド頂点フォーマット


IDirect3DDevice7::DrawIndexedPrimitiveVB

IDirect3DDevice7::DrawIndexedPrimitiveVB メソッドは、頂点バッファ内の頂点の配列に対するインデックスに基づき、ジオメトリ プリミティブをレンダリングする。

HRESULT DrawIndexedPrimitiveVB(
  D3DPRIMITIVETYPE        d3dptPrimitiveType,
  LPDIRECT3DVERTEXBUFFER7 lpd3dVertexBuffer,
  DWORD  dwStartVertex,
  DWORD  dwNumVertices,
  LPWORD lpwIndices,
  DWORD  dwIndexCount,
  DWORD  dwFlags
);

パラメータ

d3dptPrimitiveType
このコマンドによってレンダリングされるプリミティブの型。これは、D3DPRIMITIVETYPE 列挙型のメンバの 1 つでなければならない。

D3DPRIMITIVETYPE の D3DPT_POINTLIST メンバはインデックス付けされない。

lpd3dVertexBuffer
頂点の配列を格納する頂点バッファの IDirect3DVertexBuffer7 インターフェイスのアドレス。頂点は、トランスフォームされていてもいなくても、最適化されていてもいなくてもよい。
dwStartVertex
頂点バッファ内のレンダリングされる最初の頂点のインデックス
dwNumVertices
頂点バッファ内のレンダリングされる頂点の合計個数。
lpwIndices
頂点バッファ内の頂点へのインデックス付けに使用される、WORD の配列のアドレス。配列の値は、範囲 [0, dwNumVertices – 1] で頂点をインデックス付けする必要がある。
dwIndexCount
lpwIndices. における配列内のインデックス数。許容される最大インデックス数は D3DMAXNUMVERTICES (0xFFFF) である。
dwFlags
待機せずにプリミティブをレンダリングする場合はゼロ、または以下のフラグを指定する。
D3DDP_WAIT
メソッドは、ポリゴンがカードに送られるとすぐに返るのではなく、レンダリングが終わるまで待つ。(シーン キャプチャ カードでは、カードからの応答があり次第、メソッドは返る。) このフラグはデバッグによく使用される。アプリケーションは、シーンを先に進める前に確実に更新しておくためにも、このフラグを使用するべきではない。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

注意

レンダリングする頂点が、指定した頂点フォーマットと一致していることを確認する。パフォーマンス上の理由から、Direct3D は頂点のサイズおよびストライドと提供された柔軟な頂点フォーマットとの照合を行わない。これが一致していないと、メモリ障害が発生しやすい。

頂点バッファからレンダリングするときは、頂点バッファ メソッドを使用する必要がある。

このメソッドは、従来のインターフェイスで使用されたメソッドとは異なり、dwFlags パラメータで D3DDP_DONOTCLIP、D3DDP_DONOTLIGHT、および D3DDP_DONOTUPDATEEXTENTS フラグを受け取らない。これらのフラグの機能性は、現在では D3DRENDERSTATE_CLIPPING、D3DRENDERSTATE_LIGHTING、および D3DRENDERSTATE_EXTENTS レンダリング ステートによって使用できる。

ソフトウェア デバイス (MMX および RGB デバイス) は、ローカルまたは非ローカルであるかどうかにかかわらず、ビデオ メモリから頂点バッファをレンダリングすることはできない。ソフトウェア デバイスを使用して頂点バッファをレンダリングするには、頂点バッファがシステム メモリに存在しなければならない。ハードウェア デバイスは、システム メモリまたはビデオ メモリのどちらの頂点バッファからでも、レンダリングすることができる。

頂点バッファがロックされているときはレンダリングすることはできない。ロックされた頂点バッファを使用して IDirect3DDevice7::DrawIndexedPrimitiveVB または IDirect3DDevice7::DrawPrimitiveVB メソッドを呼び出そうとすると失敗し、D3DERR_VERTEXBUFFERLOCKED が返される。

IDirect3DDevice3 インターフェイスでは、このメソッドは従来の IDirect3DVertexBuffer インターフェイスへのポインタを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::DrawPrimitive、IDirect3DDevice7::DrawPrimitiveStrided、IDirect3DDevice7::DrawPrimitiveVB、IDirect3DDevice7::DrawIndexedPrimitive、IDirect3DDevice7::DrawIndexedPrimitiveStrided


IDirect3DDevice7::DrawPrimitive

IDirect3DDevice7::DrawPrimitive メソッドは、指定の型の図形プリミティブのシーケンスとして、頂点の指定の配列をレンダリングする。

HRESULT DrawPrimitive(
  D3DPRIMITIVETYPE dptPrimitiveType,
  DWORD  dwVertexTypeDesc,
  LPVOID lpvVertices,
  DWORD  dwVertexCount,
  DWORD  dwFlags
);

パラメータ

dptPrimitiveType
このコマンドによってレンダリングされるプリミティブの型。これは、D3DPRIMITIVETYPE 列挙型のメンバの 1 つでなければならない。
dwVertexTypeDesc
このプリミティブのセットに対する頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせ。
lpvVertices
プリミティブ シーケンス中で使用する頂点の配列へのポインタ。
dwVertexCount
配列中の頂点数。許容される最大頂点数は D3DMAXNUMVERTICES (0xFFFF) である。
dwFlags
待機せずにプリミティブをレンダリングする場合はゼロ、または以下のフラグを指定する。
D3DDP_WAIT
メソッドは、ポリゴンがカードに送られるとすぐに返るのではなく、レンダリングが終わるまで待つ。(シーン キャプチャ カードでは、カードからの応答があり次第、メソッドは返る。) このフラグはデバッグによく使用される。アプリケーションは、シーンを先に進める前に確実に更新しておくためにも、このフラグを使用するべきではない。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

注意

レンダリングする頂点が、指定した頂点フォーマットと一致していることを確認する。パフォーマンス上の理由から、Direct3D は頂点のサイズおよびストライドと提供された柔軟な頂点フォーマットとの照合を行わない。これが一致していないと、メモリ障害が発生しやすい。

このメソッドは、頂点バッファからのレンダリングには使用せず、代わりに頂点バッファ メソッドを使用する。

このメソッドは、従来のインターフェイスで使用されたメソッドとは異なり、dwFlags パラメータで D3DDP_DONOTCLIP、D3DDP_DONOTLIGHT、および D3DDP_DONOTUPDATEEXTENTS フラグを受け取らない。これらのフラグの機能性は、現在では D3DRENDERSTATE_CLIPPING、D3DRENDERSTATE_LIGHTING、および D3DRENDERSTATE_EXTENTS レンダリング ステートによって使用できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::DrawPrimitiveStrided、IDirect3DDevice7::DrawPrimitiveVB、IDirect3DDevice7::DrawIndexedPrimitive、IDirect3DDevice7::DrawIndexedPrimitiveStrided、IDirect3DDevice7::DrawIndexedPrimitiveVB


IDirect3DDevice7::DrawPrimitiveStrided

IDirect3DDevice7::DrawPrimitiveStrided メソッドは、指定したストライド頂点の配列をジオメトリ プリミティブ シーケンスとしてレンダリングする。詳細情報については、ストライド頂点フォーマットを参照すること。

HRESULT DrawPrimitiveStrided(
  D3DPRIMITIVETYPE dptPrimitiveType,
  DWORD  dwVertexTypeDesc,
  LPD3DDRAWPRIMITIVESTRIDEDDATA lpStrideData,
  DWORD  dwVertexCount,
  DWORD  dwFlags
);

パラメータ

dptPrimitiveType
このコマンドによってレンダリングされるプリミティブの型。これは、D3DPRIMITIVETYPE 列挙型のメンバの 1 つでなければならない。
dwVertexTypeDesc
頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせ。
lpStrideData
このプリミティブの頂点成分のポインタおよびメモリ ストライドを格納する D3DDRAWPRIMITIVESTRIDEDDATA 構造体のアドレス。このときのフォーマットは、dwVertexTypeDesc のフラグで指定するフォーマットである。
dwVertexCount
lpVertexArray における配列内の頂点数。許容される最大頂点数は D3DMAXNUMVERTICES (0xFFFF) である。
dwFlags
待機しないでプリミティブをレンダリングする場合はゼロ、そうでない場合は以下のフラグを指定する。
D3DDP_WAIT
メソッドは、ポリゴンがカードに送られるとすぐに返るのではなく、レンダリングが終わるまで待つ。(シーン キャプチャ カードでは、カードからの応答があり次第、メソッドは返る。) このフラグはデバッグによく使用される。アプリケーションは、シーンを先に進める前に確実に更新しておくためにも、このフラグを使用するべきではない。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

注意

レンダリングする頂点が、指定した頂点フォーマットと一致していることを確認する。パフォーマンス上の理由から、Direct3D は頂点のサイズおよびストライドと提供された柔軟な頂点フォーマットとの照合を行わない。これが一致していないと、メモリ障害が発生しやすい。

このメソッドは、頂点バッファからのレンダリングには使用せず、代わりに頂点バッファ メソッドを使用する。

このメソッドは、従来のインターフェイスで使用されたメソッドとは異なり、dwFlags パラメータで D3DDP_DONOTCLIP、D3DDP_DONOTLIGHT、および D3DDP_DONOTUPDATEEXTENTS フラグを受け取らない。これらのフラグの機能性は、現在では D3DRENDERSTATE_CLIPPING、D3DRENDERSTATE_LIGHTING、および D3DRENDERSTATE_EXTENTS レンダリング ステートによって使用できる。

このメソッドは、トランスフォームされた頂点をサポートしない。したがって、D3DFVF_XYZRHW 頂点フォーマット記述子を dwVertexTypeDesc パラメータに含めると、メソッドは失敗し、D3DERR_INVALIDVERTEXTYPE を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::DrawPrimitive、IDirect3DDevice7::DrawPrimitiveVB、IDirect3DDevice7::DrawIndexedPrimitive、IDirect3DDevice7::DrawIndexedPrimitiveStrided、IDirect3DDevice7::DrawIndexedPrimitiveVB、ストライド頂点フォーマット


IDirect3DDevice7::DrawPrimitiveVB

IDirect3DDevice7::DrawPrimitiveVB メソッドは、頂点バッファ内の頂点の配列をジオメトリ プリミティブ シーケンスとしてレンダリングする。

HRESULT DrawPrimitiveVB(
  D3DPRIMITIVETYPE        d3dptPrimitiveType,
  LPDIRECT3DVERTEXBUFFER7 lpd3dVertexBuffer,
  DWORD dwStartVertex,
  DWORD dwNumVertices,
  DWORD dwFlags
);

パラメータ

d3dptPrimitiveType
このコマンドによってレンダリングされるプリミティブの型。これは、D3DPRIMITIVETYPE 列挙型のメンバの 1 つでなければならない。
lpd3dVertexBuffer
頂点の配列を格納する頂点バッファの IDirect3DVertexBuffer7 インターフェイスのアドレス。頂点は、トランスフォームされていてもいなくても、最適化されていてもいなくてもよい。
dwStartVertex
プリミティブ中の最初の頂点のインデックス値。始点インデックスとして可能な最大値は D3DMAXNUMVERTICES (0xFFFF) である。デバッグ ビルドでは、この制限値を超える始点インデックスを指定すると、メソッドは失敗し、DDERR_INVALIDPARAMS を返す。
dwNumVertices
レンダリングする頂点数。許容される最大頂点数は D3DMAXNUMVERTICES (0xFFFF) である。
dwFlags
待機しないでプリミティブをレンダリングする場合はゼロ、そうでない場合は以下のフラグを指定する
D3DDP_WAIT
メソッドは、ポリゴンがカードに送られるとすぐに返るのではなく、レンダリングが終わるまで待つ。(シーン キャプチャ カードでは、カードからの応答があり次第、メソッドは返る。) このフラグはデバッグによく使用される。アプリケーションは、シーンを先に進める前に確実に更新しておくためにも、このフラグを使用するべきではない。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

注意

レンダリングする頂点が、指定した頂点フォーマットと一致していることを確認する。パフォーマンス上の理由から、Direct3D は頂点のサイズおよびストライドと提供された柔軟な頂点フォーマットとの照合を行わない。これが一致していないと、メモリ障害が発生しやすい。

頂点バッファからレンダリングするときは、頂点バッファ メソッドを使用する必要がある。

このメソッドは、従来のインターフェイスで使用されたメソッドとは異なり、dwFlags パラメータで D3DDP_DONOTCLIP、D3DDP_DONOTLIGHT、および D3DDP_DONOTUPDATEEXTENTS フラグを受け取らない。これらのフラグの機能性は、現在では D3DRENDERSTATE_CLIPPING、D3DRENDERSTATE_LIGHTING、および D3DRENDERSTATE_EXTENTS レンダリング ステートによって使用できる。

ソフトウェア デバイス (MMX および RGB デバイス) は、ローカルまたは非ローカルであるかどうかにかかわらず、ビデオ メモリから頂点バッファをレンダリングすることはできない。ソフトウェア デバイスを使用して頂点バッファをレンダリングするには、頂点バッファがシステム メモリに存在しなければならない。ハードウェア デバイスは、システム メモリまたはビデオ メモリのどちらの頂点バッファからでも、レンダリングすることができる。

頂点バッファがロックされているときはレンダリングすることはできない。ロックされた頂点バッファを使用して IDirect3DDevice7::DrawIndexedPrimitiveVB または IDirect3DDevice7::DrawPrimitiveVB メソッドを呼び出そうとすると失敗し、D3DERR_VERTEXBUFFERLOCKED が返される。

IDirect3DDevice3 インターフェイスでは、このメソッドは従来の IDirect3DVertexBuffer インターフェイスへのポインタを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::DrawPrimitive、IDirect3DDevice7::DrawPrimitiveStrided、IDirect3DDevice7::DrawIndexedPrimitive、IDirect3DDevice7::DrawIndexedPrimitiveStrided、IDirect3DDevice7::DrawIndexedPrimitiveVB


IDirect3DDevice7::EndScene

IDirect3DDevice7::EndScene メソッドは、IDirect3DDevice7::BeginScene メソッドの呼び出しによって開始されたシーンを終了する。

HRESULT EndScene();

パラメータ

なし。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。

注意

このメソッドが成功すると、シーンがレンダリングされ、レンダリング後のシーンがデバイス サーフェスに保持される。

シーンのレンダリングが正常に開始している場合、別のシーンのレンダリングを開始するために IDirect3DDevice7::BeginScene メソッドを呼び出すには、その前にこのメソッドを呼び出す必要がある(BeginScene メソッドの呼び出しが失敗している場合はシーンのレンダリングは開始していないため、このメソッドを呼び出す必要はない)。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::BeginScene、シーンの開始と終了


IDirect3DDevice7::EndStateBlock

IDirect3DDevice7::EndStateBlock メソッドは、デバイス ステート ブロックの記録を停止してステート ブロックのハンドルを取得するように Direct3D に指示する。

HRESULT EndStateBlock(
  LPDWORD lpdwBlockHandle
);

パラメータ

lpdwBlockHandle
記録を終了するデバイス ステート ブロックのハンドルを格納する変数のアドレス。この値は、IDirect3DDevice7::ApplyStateBlock および IDirect3DDevice7::DeleteStateBlock メソッドで使用される。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_NOTINBEGINSTATEBLOCK
DDERR_INVALIDPARAMS

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::ApplyStateBlock、IDirect3DDevice7::BeginStateBlock、IDirect3DDevice7::CaptureStateBlock、IDirect3DDevice7::CreateStateBlock、IDirect3DDevice7::DeleteStateBlock、ステート ブロック


IDirect3DDevice7::EnumTextureFormats

IDirect3DDevice7::EnumTextureFormats メソッドは、サポートされているテクスチャ フォーマットのリストに対する現在のドライバを調べる。

HRESULT EnumTextureFormats(
  LPD3DENUMPIXELFORMATSCALLBACK lpd3dEnumPixelProc,
  LPVOID lpArg
);

パラメータ

lpd3dEnumPixelProc
列挙プロシージャがテクスチャ フォーマットごとに呼び出す D3DEnumPixelFormatsCallback コールバック関数のアドレス。
lpArg
コールバック関数に渡されるアプリケーション定義データのアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

IDirect3DDevice2 インターフェイスの場合、このメソッドは、D3DEnumPixelFormatsCallback ではなく、従来の D3DEnumTextureFormatsCallback 関数へのポインタを受け取る。

このメソッドは、一部のデバイスに新しく実装されたテクスチャ フォーマットを列挙できない場合がある。列挙されないテクスチャ フォーマットを必要とするアプリケーションでは、そのフォーマットのサーフェスを作成しようと試みる。作成できた場合は、そのフォーマットがサポートされる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DDevice7::GetCaps

IDirect3DDevice7::GetCaps メソッドは、Direct3D のデバイスの能力を検索して取り出す。

HRESULT GetCaps(
  LPD3DDEVICEDESC7 lpD3DDevDesc,
);

パラメータ

lpD3DDevDesc
デバイスのハードウェア機能を格納する D3DDEVICEDESC7 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、ディスプレイ デバイスの能力を検索しない。この情報を検索するには、IDirectDraw7::GetCaps メソッドを使用する。

このインターフェイスの旧バージョンの場合、このメソッドは従来の D3DDEVICEDESC 構造体へのポインタを受け取ることにより、ハードウェア アブストラクション レイヤ (HAL) デバイスおよびハードウェア エミュレーション レイヤ (HEL) の能力も同時に取得していた。IDirect3DDevice7 インターフェイスでは、このメソッドはメソッド呼び出しが行われているデバイスの能力のみ取得する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DDevice7::GetClipPlane

IDirect3DDevice7::GetClipPlane メソッドは、デバイスのユーザー定義クリップ面の係数を取得する。

HRESULT GetClipPlane(
  DWORD dwIndex,
  D3DVALUE* pPlaneEquation
);

パラメータ

dwIndex
平面方程式の係数を取得するクリップ面のインデックス。
pPlaneEquation
一般平面方程式においてクリップ面の係数を表す値の、4 要素で構成される配列のアドレス。「注意」を参照すること。

戻り値

成功すれば D3D_OK を返す。

失敗すれば DDERR_INVALIDPARAMS を返す。このエラーは、dwIndex の値がデバイスでサポートされる最大クリップ面インデックスを超えているか、pPlaneEquation の配列が 4 つの浮動小数点値を格納するほど大きくないことを示す。

注意

このメソッドで取得する係数は、一般平面方程式の形をとる。pPlaneEquation の配列の値が配列内での順に A、B、C、および D とラベル付けされている場合、これらの値は一般平面方程式が Ax + By + Cz + D = 0 となるように適用される。Ax + By + Cz + Dw >= 0 である場合、同次座標 (x, y, z, w) の点は面のハーフ空間に表示される。クリップ面上または背後に存在する点はシーンからクリッピングされる。

このメソッドで使用される平面方程式はワールド空間に存在し、その前に呼び出す IDirect3DDevice7::SetClipPlane メソッドによって設定される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetClipPlane、D3DRENDERSTATE_CLIPPLANEENABLE、ユーザー定義クリップ面


IDirect3DDevice7::GetClipStatus

IDirect3DDevice7::GetClipStatus メソッドは、現在のクリップ ステータスを取得する。

HRESULT GetClipStatus(
  LPD3DCLIPSTATUS lpD3DClipStatus
);

パラメータ

lpD3DClipStatus
現在のクリップ ステータスを記述する D3DCLIPSTATUS 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合には、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetClipStatus


IDirect3DDevice7::GetDirect3D

IDirect3DDevice7::GetDirect3D メソッドは、このデバイスの Direct3D オブジェクトを検索して取り出す。

HRESULT GetDirect3D(
  LPDIRECT3D7 *lplpD3D
);

パラメータ

lplpD3D
メソッドが返ったときに、Direct3D オブジェクトの IDirect3D7 インターフェイスへのポインタを受け取るアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D 直接モードの戻り値」を参照すること。

注意

このインターフェイスの旧バージョンでは、このメソッドは従来の IDirect3D3 インターフェイスへのポインタを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DDevice7::GetInfo

IDirect3DDevice7::GetInfo メソッドは、レンダリング デバイス情報を取得する。この情報は、Direct3D 関連または基本となるデバイス ドライバに関連するものである。

HRESULT GetInfo(
  DWORD  dwDevInfoID,
  LPVOID pDevInfoStruct,
  DWORD  dwSize
);

パラメータ

dwDevInfoID
pDevInfoStruct のデバイス情報の構造体のタイプを示すフラグ。このパラメータは、以下のフラグのいずれかに設定できる。
D3DDEVINFOID_TEXTUREMANAGER
pDevInfoStruct の構造体は、ドライバで行われるテクスチャ管理についての情報を格納する D3DDEVINFO_TEXTUREMANAGER 構造体である。ドライバでテクスチャ管理が行われていない場合は、Direct3D によるテクスチャ管理についての情報が取得される。
D3DDEVINFOID_D3DTEXTUREMANAGER
pDevInfoStruct の構造体は、Direct3D によるテクスチャ管理についての情報を格納する D3DDEVINFO_TEXTUREMANAGER 構造体である。
D3DDEVINFOID_TEXTURING
pDevInfoStruct の構造体は、アプリケーションのテクスチャ処理アクティビティについての情報を格納する D3DDEVINFO_TEXTURING 構造体である。
pDevInfoStruct
呼び出しが成功した場合に、指定されたデバイス情報を受け取る構造体のアドレス。構造体のタイプおよび格納されたデータの解釈方法は、dwDevInfoID のフラグによって決まる。
dwSize
pDevInfoStruct の構造体のバイト単位でのサイズ。

戻り値

成功すれば D3D_OK を返す。このメソッドは、DirectX のリテール ビルドで S_FALSE を返す。

失敗すれば、次のいずれかのエラー値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドを使用すると、ドライバでは特定の種類の情報およびそれに対応する構造体を宣言できる。これらについては、この SDK では説明されていない。

このメソッドは同期して実行されるが、この実行速度が遅い場合はアプリケーションのパフォーマンスが低下することがある。シーンのレンダリング中 (IDirect3DDevice7::BeginScene を呼び出してから IDirect3DDevice7::EndScene を呼び出すまで) は、このメソッドを呼び出してはならない。

このメソッドは、製品開発時のパフォーマンス追跡およびデバッグに使用する (DirectX のデバッグ バージョン)。このメソッドが成功して S_FALSE を返しても、デバイス データを取得していないときがある。ホスト システムに DirectX ランタイムのリテール バージョンがインストールされている場合には、このようなことが起こる。

動作環境

Windows NT:Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

D3DDEVINFO_TEXTUREMANAGER


IDirect3DDevice7::GetLight

IDirect3DDevice7::GetLight メソッドは、このデバイスで使用する一連のライト プロパティを取得する。

HRESULT GetLight(
  DWORD dwLightIndex,
  LPD3DLIGHT7 lpLight
);

パラメータ

dwLightIndex
取得するライト プロパティ セットのゼロベース インデックス。
lpLight
取得したライティング パラメータ セットを格納する D3DLIGHT7 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。lpLight パラメータが無効な場合、このメソッドは DDERR_INVALIDPARAMS を返す。

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

旧インターフェイスとは異なり、IDirect3DDevice7 インターフェイスはライティング オブジェクトを使用しない。このメソッド、およびこのメソッドにおけるライト プロパティ セットを記述する D3DLIGHT7 構造体は、旧バージョンのデバイス インターフェイスでのライティング セマンティクスに代わるものである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetLight、IDirect3DDevice7::GetLightEnable、IDirect3DDevice7::LightEnable


IDirect3DDevice7::GetLightEnable

IDirect3DDevice7::GetLightEnable メソッドは、デバイス内のライティング パラメータ セットのアクティビティ ステータス (有効/無効) を取得する。

HRESULT GetLightEnable(
  DWORD dwLightIndex,
  BOOL* pbEnable
);

パラメータ

dwLightIndex
このメソッドの対象となるライティング パラメータ セットのゼロベース インデックス。
pbEnable
指定されたライティング パラメータのステータスを格納する変数のアドレス。呼び出しの後、このアドレスの値がゼロ以外の場合は、指定されたライティング パラメータが有効であることを示し、0 の場合は無効であることを示す。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。Direct3D 直接モードのエラーの一覧およびその説明については、「戻り値」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetLight、IDirect3DDevice7::LightEnable、IDirect3DDevice7::SetLight


IDirect3DDevice7::GetMaterial

IDirect3DDevice7::GetMaterial メソッドは、デバイスの現在のマテリアル プロパティを取得する。

HRESULT GetMaterial(
  LPD3DMATERIAL7 lpMaterial
);

パラメータ

lpMaterial
現在設定されているマテリアル プロパティを格納する D3DMATERIAL7 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。lpMaterial パラメータが無効な場合、このメソッドは DDERR_INVALIDPARAMS を返す。

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

旧インターフェイスとは異なり、IDirect3DDevice7 インターフェイスはマテリアルのハンドルを使用しない。このメソッド、およびこのメソッドにおけるマテリアル プロパティを記述する D3DMATERIAL7 構造体は、旧バージョンのデバイス インターフェイスでのマテリアルハンドルのセマンティクスに代わるものである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetMaterial


IDirect3DDevice7::GetRenderState

IDirect3DDevice7::GetRenderState メソッドは、単一の Direct3DDevice レンダリング ステート パラメータを取得する。

HRESULT GetRenderState(
  D3DRENDERSTATETYPE dwRenderStateType,
  LPDWORD lpdwRenderState
);

パラメータ

dwRenderStateType
調査対象のデバイス ステート変数。このパラメータは、D3DRENDERSTATETYPE 列挙型の任意のメンバにすることができる。
lpdwRenderState
メソッドが返ったときに、Direct3DDevice レンダリング ステートを受け取る変数のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合には、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetRenderState


IDirect3DDevice7::GetRenderTarget

IDirect3DDevice7::GetRenderTarget メソッドは、レンダリングの対象として用いられる DirectDraw サーフェスへのポインタを検索して取り出す。

HRESULT GetRenderTarget(
  LPDIRECTDRAWSURFACE7 *lplpRenderTarget
);

パラメータ

lplpRenderTarget
このデバイスにおけるレンダリング ターゲット サーフェスの IDirectDrawSurface7 インターフェイスへのポインタを受け取るアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合には、DDERR_INVALIDPARAMS を返す。

注意

IDirect3DDevice3 インターフェイスでは、このメソッドは従来の IDirectDrawSurface4 インターフェイスへのポインタを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetRenderTarget


IDirect3DDevice7::GetStateData

IDirect3DDevice7::GetStateDate メソッドは実装されていない。

HRESULT GetStateData(
  DWORD dwState,
  LPVOID* lplpStateData
);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DDevice7::GetTexture

IDirect3DDevice7::GetTexture メソッドは、デバイスの、指定のステージに割り当てられたテクスチャを検索して取り出す。

HRESULT GetTexture(
  DWORD dwStage,
  LPDIRECTDRAWSURFACE7 * lplpTexture
);

パラメータ

dwStage
検索して取り出すテクスチャのステージ識別子。ステージ識別子はゼロをベースとする。現在、デバイスは最大 8 セットまでテクスチャを持つことができる。したがって、dwStage に許容される最大値は 7 である。
lplpTexture
呼び出しが成功したときに、指定されたテクスチャの IDirectDrawSurface7 インターフェイスへのポインタを格納する変数のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

従来の IDirect3DDevice3 インターフェイスでは、このメソッドは IDirect3DTexture2 インターフェイスへのポインタを受け取る。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetTexture、IDirect3DDevice7::GetTextureStageState、IDirect3DDevice3::SetTextureStageState、テクスチャ


IDirect3DDevice7::GetTextureStageState

IDirect3DDevice7::GetTextureStageState メソッドは、現在割り当てられているテクスチャ ステート値を検索して取り出す。

HRESULT GetTextureStageState(
  DWORD   dwStage,
  D3DTEXTURESTAGESTATETYPE dwState,
  LPDWORD lpdwValue
);

パラメータ

dwStage
ステートを取得する対象となるテクスチャのステージ識別子。ステージ識別子はゼロをベースとする。現在、デバイスは最大 8 セットまでテクスチャを持つことができる。したがって、dwStage で許容される最大値は 7 である。
dwState
検索され取り出されるテクスチャのステート。このパラメータは、D3DTEXTURESTAGESTATETYPE 列挙型の任意のメンバにすることができる。
lpdwValue
取得したステート値を格納する変数のアドレス。取り出された値の意味は dwState パラメータで決まる。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetTextureStageState、IDirect3DDevice7::GetTexture、IDirect3DDevice7::SetTexture、テクスチャ


IDirect3DDevice7::GetTransform

IDirect3DDevice7::GetTransform メソッドは、トランスフォーム ステートを記述する行列を取得する。

HRESULT GetTransform(
  D3DTRANSFORMSTATETYPE dtstTransformStateType,
  LPD3DMATRIX lpD3DMatrix
);

パラメータ

dtstTransformStateType
変更対象のデバイス ステート変数。このパラメータには、D3DTRANSFORMSTATETYPE 列挙型の任意のメンバを設定できる。
lpD3DMatrix
トランスフォームを記述する D3DMATRIX 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合には、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetTransform


IDirect3DDevice7::GetViewport

IDirect3DDevice7::GetViewport メソッドは、デバイスに現在設定されているビューポート パラメータを取得する。

HRESULT GetViewport(
  LPD3DVIEWPORT7 lpViewport
);

パラメータ

lpViewport
呼び出しが成功した場合に、現在のビューポート パラメータを格納する D3DVIEWPORT7 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。lpViewport パラメータが無効な場合、このメソッドは DDERR_INVALIDPARAMS を返す。

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::SetViewport


IDirect3DDevice7::LightEnable

IDirect3DDevice7::LightEnable メソッドは、デバイス内のライティング パラメータ セットを有効または無効にする。

HRESULT LightEnable(
  DWORD dwLightIndex,
  BOOL bEnable
);

パラメータ

dwLightIndex
このメソッドの対象となるライティング パラメータ セットのゼロベース インデックス。
bEnable
ライティング パラメータ セットが有効または無効のいずれであるかを示す値。このパラメータに TRUE を設定すると、指定されたインデックスのパラメータのライトが有効になり、FALSE を設定すると無効になる。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。Direct3D 直接モードのエラー値の一覧およびその説明については、「戻り値」を参照すること。

注意

dwLightIndex の値をデバイス内で現在割り当てられているライト プロパティの範囲外の値に設定すると、LightEnable メソッドは以下のプロパティでライトを作成し、有効なステートを bEnable で指定された値に設定する。

Member | デフォルト
dltType | D3DLIGHT_DIRECTIONAL
dcvDiffuse | (R:1, G:1, B:1, A:0)
dcvSpecular | (R:0, G:0, B:0, A:0)
dcvAmbient | (R:0, G:0, B:0, A:0)
dvPosition | (0, 0, 0)
dvDirection | (0, 0, 1)
dvRange | 0
dvFalloff | 0
dvAttenuation0 | 0
dvAttenuation1 | 0
dvAttenuation2 | 0
dvTheta | 0
dvPhi | 0

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetLight、IDirect3DDevice7::GetLightEnable、IDirect3DDevice7::SetLight、ライティングとマテリアル


IDirect3DDevice7::Load

IDirect3DDevice7::Load メソッドは、転送先テクスチャの指定されたポイントまたはキューブ環境マップの面に、転送元テクスチャの矩形領域をロードする。

HRESULT Load(
  LPDIRECTDRAWSURACE7 lpDestTex,
  LPPOINT lpDestPoint,
  LPDIRECTDRAWSURACE7 lpSrcTex,
  LPRECT lprcSrcRect,
  DWORD dwFlags
);

パラメータ

lpDestTex
転送元テクスチャから画像データを受け取るテクスチャの IDirectDrawSurface7 インターフェイスのアドレス。転送先テクスチャはキューブ環境マップでもよい。キューブ環境マップやミップマップなどの複合テクスチャの場合、このパラメータは最上位サーフェスをポイントしなければならない。
lpDestPoint
このメソッドで画像データを転送先テクスチャにロードする際のポイントを記述する POINT 構造体のアドレス。転送先ポイントを転送先テクスチャの原点にする場合は、このパラメータを NULL に設定する。
lpSrcTex
ロードする画像データを格納するテクスチャの IDirect3DTexture7 インターフェイスのアドレス。キューブ環境マップやミップマップなどの複合テクスチャの場合、このパラメータは最上位サーフェスをポイントしなければならない。
lprcSrcRect
メソッドでロードする転送元テクスチャ内の領域を記述する RECT 構造体のアドレス。転送元矩形が転送元テクスチャ全体を含む場合は、このパラメータを NULL に設定する。
dwFlags
キューブ環境マップの場合、画像データを受け取る転送先テクスチャの面を示す値。このパラメータには、以下のフラグの組み合わせを設定できる。
0
転送先テクスチャが管理下のテクスチャの場合に必要。
DDSCAPS2_CUBEMAP_ALLFACES
転送元テクスチャ内の画像データをすべての面にロードする。
DDSCAPS2_CUBEMAP_NEGATIVEX、DDSCAPS2_CUBEMAP_NEGATIVEY、および DDSCAPS2_CUBEMAP_NEGATIVEZ
負方向の x、y、または z 面に画像データをロードする。
DDSCAPS2_CUBEMAP_POSITIVEX, DDSCAPS2_CUBEMAP_POSITIVEY, or DDSCAPS2_CUBEMAP_POSITIVEZ
正方向の x、y、または z 面に画像データをロードする。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

転送先テクスチャは、これを作成したレンダリング デバイスのみでなく、どのレンダリング デバイスでも使用できる。ハードウェア デバイスでは、ロード処理はハードウェア アクセラレーションで実行される。

テクスチャをビデオ メモリにロードする場合は、ブリット処理で行うよりもこのメソッドを呼び出した方がよい。

このメソッドは、すべてのミップレベル、キューブマップ面、パレット、およびカラー キーを転送元テクスチャから転送先テクスチャにコピーする。

このメソッドを使用してミップマップをロードする場合は、以下の特別事項が適用される。

  • 転送先テクスチャは、転送元テクスチャに格納されたミップレベルのサブセットでもよい。この場合、両方のテクスチャに共通のミップレベルのみコピーされる。これは、テクスチャ LOD を実装する場合に便利である。2 つのミップレベルのみ使用してビデオ メモリ テクスチャを作成し、次にこのメソッドを使用して、ミップレベル全体を構成する転送元テクスチャから 2 つのレベルをコピーできる。
  • 転送元および転送先サーフェスのポインタは、最上位サーフェスをポイントしなければならない。
  • ミップマップのサブ矩形をロードする場合、サブ矩形はミップマップ チェーンの最上位サーフェスを参照し、それぞれの下位ミップレベルに対して 2 つに分割される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DDevice7::MultiplyTransform

IDirect3DDevice7::MultiplyTransform メソッドは、デバイスのワールド行列、ビュー行列、または射影行列に、指定された行列を乗算する。乗算の順は、lpD3Dmatrix 掛ける dtstTransformStateType である。

HRESULT MultiplyTransform(
  D3DTRANSFORMSTATETYPE dtstTransformStateType,
  LPD3DMATRIX lpD3DMatrix
);

パラメータ

dtstTransformStateType
変更するデバイス行列を指定する D3DTRANSFORMSTATETYPE 列挙型のメンバ。最も一般的な設定は D3DTRANSFORMSTATE_WORLD で、ワールド行列を変更するが、必要であれば、ビュー行列や射影行列を変更するように指定することもできる。
lpD3DMatrix
現在のトランスフォームを変更する D3DMATRIX 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合には、DDERR_INVALIDPARAMS を返す。

注意

アプリケーションが、トランスフォームの階層構造を使って動作するために、MultiplyTransform メソッドを使用することも考えられる。たとえば、腕を表すジオメトリとトランスフォームは、以下の階層で構成することもある。

shoulder_transformation
    upper_arm geometry
    elbow transformation
        lower_arm geometry
        wrist transformation
            hand geometry

アプリケーションでは、この階層をレンダリングするために以下の一連の呼び出しを行うことができる (このコードでは一部のパラメータのみ示す)。

IDirect3DDevice7::SetTransform(D3DTRANSFORMSTATE_WORLD,
    shoulder_transform)
IDirect3DDevice7::DrawPrimitive(upper_arm)
IDirect3DDevice7::MultiplyTransform(D3DTRANSFORMSTATE_WORLD,
    elbow_transform)
IDirect3DDevice7::DrawPrimitive(lower_arm)
IDirect3DDevice7::MultiplyTransform(D3DTRANSFORMSTATE_WORLD,
    wrist_transform)
IDirect3DDevice7::DrawPrimitive(hand)

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::DrawPrimitive、IDirect3DDevice7::SetTransform


IDirect3DDevice7::PreLoad

IDirect3DDevice7::Preload メソッドは、Direct3D テクスチャ マネージャに管理下のテクスチャをビデオ メモリにロードするよう指示する。

HRESULT PreLoad(
  LPDIRECTDRAWSURFACE7 lpddsTexture
);

パラメータ

lpddsTexture
メモリにロードするテクスチャの IDirectDrawSurface7 インターフェイスのアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、管理下のテクスチャをビデオ メモリに強制的にロードする。使用できるビデオ メモリが十分にない場合、システムはその他のテクスチャを削除してメモリを確保した後、テクスチャをロードする。ロードするテクスチャは管理下のテクスチャでなければならない (DDSCAPS2_TEXTUREMANAGE または DDSCAPS2_D3DTEXTUREMANAGE フラグで作成されたもの)。これ以外の場合には、メソッドは失敗し、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

自動テクスチャ管理


IDirect3DDevice7::SetClipPlane

IDirect3DDevice7::SetClipPlane メソッドは、デバイスのユーザー定義クリップ面の係数を設定する。

HRESULT SetClipPlane(
  DWORD dwIndex,
  D3DVALUE* pPlaneEquation
);

パラメータ

dwIndex
平面方程式の係数を設定するクリップ面のインデックス。
pPlaneEquation
一般平面方程式におけるクリップ面係数を表す値を格納する、4 要素で構成される配列のアドレス。「注意」を参照すること。

戻り値

成功すれば D3D_OK を返す。

失敗すれば DDERR_INVALIDPARAMS を返す。このエラーは、dwIndex の値がデバイスによってサポートされる最大クリップ面インデックスを超えているか、pPlaneEquation の配列が 4 つの浮動小数点値を格納するほど大きくないことを示す。

注意

このメソッドで設定する係数は、一般平面方程式の形をとる。pPlaneEquation の配列の値が配列内での順に A、B、C、および D とラベル付けされている場合、これらの値は一般平面方程式が Ax + By + Cz + D = 0 になるように適用される。Ax + By + Cz + Dw >= 0 である場合、同次座標 (x, y, z, w) の点は平面のハーフ空間に表示される。クリップ面上または背後に存在する点はシーンからクリッピングされる。

このメソッドで使用される平面方程式は、ワールド空間に存在する。

このメソッドは、設定されたクリップ面の平面方程式を有効にはしない。クリップ面を有効にするには、DWORD 値の対応するビットを D3DRENDERSTATE_CLIPPLANEENABLE レンダリング ステートに設定する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetClipPlane、D3DRENDERSTATE_CLIPPLANEENABLE、ユーザー定義クリップ面


IDirect3DDevice7::SetClipStatus

IDirect3DDevice7::SetClipStatus メソッドは、現在のクリップ ステータスを設定する。

HRESULT SetClipStatus(
  LPD3DCLIPSTATUS lpD3DClipStatus
);

パラメータ

lpD3DClipStatus
クリップ ステータスの新しい設定値を記述する D3DCLIPSTATUS 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合には、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetClipStatus


IDirect3DDevice7::SetLight

IDirect3DDevice7::SetLight メソッドは、このデバイスのライト プロパティ セットを割り当てる。

HRESULT SetLight(
  DWORD dwLightIndex,
  LPD3DLIGHT7 lpLight
);

パラメータ

dwLightIndex
設定するライト プロパティ セットのゼロベース インデックス。インデックスに既にライト プロパティ セットが存在する場合、lpLight. の新しいプロパティで上書きされる。
lpLight
設定するライティング パラメータを格納する D3DLIGHT7 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

従来のインターフェイスとは異なり、IDirect3DDevice7 インターフェイスはライティング オブジェクトを使用しない。このメソッド、およびこのメソッドにおけるライト プロパティ セットを記述する D3DLIGHT7 構造体は、旧バージョンのデバイス インターフェイスでのライティング セマンティクスに代わるものである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetLight、IDirect3DDevice7::GetLightEnable、IDirect3DDevice7::LightEnable


IDirect3DDevice7::SetMaterial

IDirect3DDevice7::SetMaterial メソッドは、デバイスのマテリアル プロパティを設定する。

HRESULT SetMaterial(
  LPD3DMATERIAL7 lpMaterial
);

パラメータ

lpMaterial
設定するマテリアル プロパティを記述する D3DMATRIAL7 構造体のアドレス。

戻り値

成功すれば D3D_OK 返す。

失敗すればエラーを返す。lpMaterial パラメータが無効な場合、このメソッドは DDERR_INVALIDPARAMS を返す。

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

従来のインターフェイスとは異なり、IDirect3DDevice7 インターフェイスはマテリアル ハンドルを使用しない。このメソッド、およびこのメソッドにおけるマテリアル プロパティを記述する D3DMATERIAL7 構造体は、旧バージョンのデバイス インターフェイスでのマテリアルハンドルのセマンティクスに代わるものである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetMaterial


IDirect3DDevice7::SetRenderState

IDirect3DDevice7::SetRenderState メソッドは、単一の Direct3DDevice レンダリング ステート パラメータを設定する。

HRESULT SetRenderState(
  D3DRENDERSTATETYPE dwRenderStateType,
  DWORD dwRenderState
);

パラメータ

dwRenderStateType
変更対象のデバイス ステート変数。このパラメータは、D3DRENDERSTATETYPE 列挙型の任意のメンバにすることができる。
dwRenderState
Direct3D デバイス レンダリング ステートの新しい値。このパラメータの意味は、dwRenderStateType の指定値に依存する。たとえば、dwRenderStateType が D3DRENDERSTATE_SHADEMODE である場合、第 2 パラメータは D3DSHADEMODE 列挙型のメンバのいずれかになる。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合、DDERR_INVALIDPARAMS を返す。

注意

テクスチャ ステートを設定するには、従来のテクスチャ関連レンダリング ステートではなく、IDirect3DDevice7::SetTextureStageState メソッドを使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetRenderState、IDirect3DDevice7::SetTransform、レンダリング ステートについて


IDirect3DDevice7::SetRenderTarget

IDirect3DDevice7::SetRenderTarget メソッドは、レンダリング ターゲットとして新しい DirectDraw サーフェスの方向に、レンダリング出力を簡単に指定することをアプリケーションに許可する。

HRESULT SetRenderTarget(
  LPDIRECTDRAWSURFACE7 lpNewRenderTarget,
  DWORD dwFlags
);

パラメータ

lpNewRenderTarget
新しいレンダリング ターゲットとなるサーフェス オブジェクトの IDirectDrawSurface7 インターフェイスのアドレス。このサーフェスは DDSCAPS_3DDEVICE 能力と共に、生成されなければならない。
dwFlags
現在は使用されていない。ゼロを設定する。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。エラーは次の値のいずれかである。

DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

注意

現在のレンダリング ターゲットに深度バッファがない場合、深度バッファがある新しいレンダリング ターゲット サーフェスを設定するためにこのメソッドを使用することはできない。同様に、このメソッドは、深度バッファがないレンダリング ターゲットから深度バッファがあるレンダリング ターゲットに切り替えるために使用することもできない。このような処理を実行しようとするとデバッグ ビルドで失敗し、リテール ビルドでは信頼できない動作が発生することがある。新旧のレンダリング ターゲットでは共に深度バッファを使用するため、新しいレンダリング ターゲットに深度バッファをアタッチすると、その深度バッファは内容が古い深度バッファを置き換える。

従来のインターフェイスにおけるこのメソッドの実装とは異なり、IDirect3DDevice7::SetRenderTarget はデバイスの現在のマテリアルまたはビューポートを無効にしない。

能力は、レンダリング ターゲット サーフェスのプロパティの変化によっては変わらない。Direct3D HAL およびソフトウェア ラスタライザは、アプリケーションに対して一度だけ能力を公開する。システムは、目的のサーフェスのフォーマットにより異なる能力セットを提示することはできない。

複数の深度バッファがレンダリング ターゲットにアタッチされていると、この関数は失敗する。

IDirect3DDevice3 インターフェイスでは、このメソッドは従来の IDirect3DrawSurface4 インターフェイスへのポインタを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetRenderTarget


IDirect3DDevice7::SetStateData

IDirect3DDevice7::SetStateData メソッドは実装されていない。

HRESULT SetStateData(
  DWORD dwState,
  LPVOID lpStateData
);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DDevice7::SetTexture

IDirect3DDevice7::SetTexture メソッドは、テクスチャを、デバイスの指定されたステージに割り当てる。

HRESULT SetTexture(
  DWORD dwStage,
  LPDIRECTDRAWSURFACE7 lpTexture
);

パラメータ

dwStage
テクスチャを設定するステージ識別子。ステージ識別子は 0 から始まる。現在、デバイスは最大 8 セットまでテクスチャを持つことができる。したがって、dwStage に指定できる最大値は 7 である。
lpTexture
設定するテクスチャの IDirectDrawSurfece7 インターフェイスのアドレス。ミップマップやキューブ環境マップなどの複合テクスチャの場合、このパラメータは最上位サーフェスをポイントしなければならない。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、割り当てられているテクスチャ サーフェスの参照カウントをインクリメントする。テクスチャが不要になった場合は、該当するステージのテクスチャを NULL に設定しなければならない。これを行わないと、サーフェスが解放されずメモリ リークが発生する。

ソフトウェア デバイスは、1 つのテクスチャを一度に複数のテクスチャ ステージに割り当てることはサポートしていない。

IDirect3DDevice3 インターフェイスでは、このメソッドは IDirect3DTexture2 インターフェイスへのポインタを使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetTexture、IDirect3DDevice7::GetTextureStageState、IDirect3DDevice7::SetTextureStageState、テクスチャ


IDirect3DDevice7::SetTextureStageState

IDirect3DDevice7::SetTextureStageState メソッドは、現在割り当てられているテクスチャのステート値を設定する。

HRESULT SetTextureStageState(
  DWORD dwStage,
  D3DTEXTURESTAGESTATETYPE dwState,
  DWORD dwValue
);

パラメータ

dwStage
ステート値を設定するテクスチャのステージ識別子。ステージ識別子は 0 から始まる。現在、デバイスは最大 8 セットまでテクスチャを持つことができる。したがって、dwStage に指定できる最大値は 7 である。
dwState
設定するテクスチャ ステート。このパラメータは、D3DTEXTURESTAGESTATETYPE 列挙型の任意のメンバにすることができる。
dwValue
設定するステート値。この値の意味は dwState パラメータで決まる。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

テクスチャ ステートの設定にはこのメソッドを使用し、従来のテクスチャ関連レンダリング ステートは使用しない。詳細については、「レンダリング ステートについて」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetTextureStageState、IDirect3DDevice7::GetTexture、IDirect3DDevice7::SetTexture、テクスチャ


IDirect3DDevice7::SetTransform

IDirect3DDevice7::SetTransform メソッドは、単一の Direct3D デバイスのトランスフォーム関連ステートを設定する。

HRESULT SetTransform(
  D3DTRANSFORMSTATETYPE dtstTransformStateType,
  LPD3DMATRIX lpD3DMatrix
);

パラメータ

dtstTransformStateType
変更対象のデバイス ステート変数。このパラメータには、D3DTRANSFORMSTATETYPE 列挙型のどのメンバでも設定できる。
lpD3DMatrix
現在のトランスフォームを変更する D3DMATRIX 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。このメソッドは、引数の 1 つが無効な場合には、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetTransform、IDirect3DDevice7::SetRenderState


IDirect3DDevice7::SetViewport

IDirect3DDevice7::SetViewport メソッドは、デバイスのビューポート パラメータを設定する。

HRESULT SetViewport(
  LPD3DVIEWPORT7 lpViewport
);

パラメータ

lpViewport
設定するビューポート パラメータを格納する D3DVIEWPORT7 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すればエラーを返す。lpViewport パラメータが無効な場合、このメソッドは DDERR_INVALIDPARAMS を返す。

注意

このメソッドは IDirect3DDevice7 インターフェイスと共に導入された。

D3DVIEWPORT7 構造体で記述するビューポート パラメータが、レンダリング ターゲット サーフェス内に存在できない領域を記述している場合、メソッドは失敗し、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetViewport


IDirect3DDevice7::ValidateDevice

IDirect3DDevice7::ValidateDevice メソッドは、現在設定されているテクスチャのブレンディング操作と引数に対し、デバイスが 1 回の処理でレンダリングできる能力を報告する。

HRESULT ValidateDevice(
  LPDWORD lpdwPasses
);

パラメータ

lpdwPasses
マルチパス レンダリングによって希望のエフェクトを完成するためのレンダリング パスの数を格納するアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
D3DERR_CONFLICTINGTEXTUREFILTER
D3DERR_CONFLICTINGTEXTUREPALETTE
D3DERR_TOOMANYOPERATIONS
D3DERR_UNSUPPORTEDALPHAARG
D3DERR_UNSUPPORTEDALPHAOPERATION
D3DERR_UNSUPPORTEDCOLORARG
D3DERR_UNSUPPORTEDCOLOROPERATION
D3DERR_UNSUPPORTEDFACTORVALUE
D3DERR_UNSUPPORTEDTEXTUREFILTER
D3DERR_WRONGTEXTUREFORMAT

注意

現在のハードウェアが、必ずしも操作と引数の可能なすべての組み合わせを実装している必要はない。特定のブレンディング操作が与えられた引数でできるかどうかは、必要なブレンディング操作を設定し、ValidateDevice メソッドを呼び出すことにより確認することができる。

ValidateDevice メソッドは、現在設定されているレンダリング ステート、テクスチャ、テクスチャ ステージのステートを使って、呼び出された時点での確認を行う。この呼び出しの後でこれらの要素に変更があると、それまでの確認結果は無効になるので、シーンのレンダリングをする前にこのメソッドを再度呼び出さなければならない。

ディフーズ反復値の引数または処理 (D3DTA_DIFFUSE または D3DTOP_BLENDDIFFUSEALPHA) としての使用は、現在のハードウェアではほとんどサポートされていない。ほとんどのハードウェアでは、直前のテクスチャ操作ステージにおける色データの反復値を導入している程度である。

各ステージのテクスチャ (D3DTA_TEXTURE) は、第 2 引数ではなく第 1 引数として指定するようにする。

多くのカードは、任意のテクスチャのステージにおけるディフーズ値やスカラー値の使用はサポートしていない。これらは最初か最後のテクスチャのブレンディング ステージでのみ使用できることが多い。

アルファの色チャネルへの複製、入力反転など以上の能力がある最初のテクスチャにブレンディング ユニットを関連付けるカードは少ない。したがって、アプリケーションでは、可能な場合、2 つ目のテクスチャ ステージのみ使用しなければならないときがある。このようなハードウェアでは、最初のユニットはデフォルト ステートにあると仮定され、D3DTOP_SELECTARG1 処理で第 1 カラー引数は D3DTA_TEXTURE に設定される。

色操作に比べより複雑で実質的にも異なる、出力されたアルファ値に対する操作をサポートするハードウェアは、さらに少ない。

ハードウェアによっては、D3DTA_TFACTOR および D3DTA_DIFFUSE の同時使用をサポートしていない場合もある。

また多くのカードは、マルチテクスチャとミップマップ トライリニア フィルタリングの同時使用はサポートしない。マルチ テクスチャ ブレンディング処理におけるテクスチャに対してトライリニア フィルタリングが要求された場合、妥当性検証が失敗すると、トライリニア フィルタリングはオフになり再検証が行われる。このような場合には、代わりにマルチパス レンダリングを実行することができる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DDevice7::GetTextureStageState、IDirect3DDevice7::SetTextureStageState


IDirect3DVertexBuffer7

アプリケーションでは、IDirect3DVertexBuffer7 インターフェイスのメソッドを使用して、IDirect3DDevice7::DrawPrimitiveVB および IDirect3DDevice7::DrawIndexedPrimitiveVB レンダリング メソッドで用いる頂点の集合を操作する。ここでは、このインターフェイスのメソッドについてのリファレンス情報を記述する。概要については、「頂点バッファ」を参照すること。

IDirect3DVertexBuffer インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetVertexBufferDesc
頂点データ | Lock
 | Optimize
 | ProcessVertices
 | ProcessVerticesStrided
 | Unlock

IDirect3DVertexBuffer7 インターフェイスは、ストライド頂点フォーマットをサポートする IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドを加えることで、IDirect3DVertexBuffer インターフェイスを拡張している。

すべての COM インターフェイスと同様、IDirect3DVertexBuffer7 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DVERTEXBUFFER7 および LPDIRECT3DVERTEXBUFFER データ型は、IDirect3DVertex7 および IDirect3DVertexBuffer インターフェイスへのポインタとして定義される。

typedef struct IDirect3DVertexBuffer *LPDIRECT3DVERTEXBUFFER;
typedef struct IDirect3DVertexBuffer7 *LPDIRECT3DVERTEXBUFFER7;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

頂点バッファ


IDirect3DVertexBuffer7::GetVertexBufferDesc

IDirect3DVertexBuffer7::GetVertexBufferDesc メソッドは、頂点バッファの記述を検索して取り出す。

HRESULT GetVertexBufferDesc(
  LPD3DVERTEXBUFFERDESC lpVBDesc
);

パラメータ

lpVBDesc
頂点バッファの記述を格納する D3DVERTEXBUFFERDESC 構造体のアドレス。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、DDERR_INVALIDPARAMS または別のエラー値を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。


IDirect3DVertexBuffer7::Lock

IDirect3DVertexBuffer7::Lock メソッドは、頂点バッファをロックして、頂点バッファ メモリへのポインタを取得する。

HRESULT Lock(
  DWORD   dwFlags,
  LPVOID* lplpData,
  LPDWORD lpdwSize
);

パラメータ

dwFlags
頂点バッファのロックの方法を示すフラグ。
DDLOCK_EVENT
現在は実装されていない。
DDLOCK_NOSYSLOCK
可能であれば、Win16Mutex (Win16Lock とも言われる) は用いない。
DDLOCK_READONLY
ロックされたメモリは読み出し専用であることを示す。
DDLOCK_SURFACEMEMORYPTR
頂点バッファへの有効なメモリ ポインタが返されることを示す。これはデフォルトである。
DDLOCK_WAIT
ロックが即座にできない場合、メソッドはロックできるまで、または、別のエラーが生じるまでリトライする。
DDLOCK_WRITEONLY
ロックされたメモリは書き込み専用であることを示す。
DDLOCK_DISCARDCONTENTS
DirectX 7.0 の新機能。Direct3D 頂点バッファのロックでのみ使用。ロック中に頂点バッファの内容が保証されないことを示す。このフラグを使用すると、Direct3D またはドライバが代替メモリ領域を頂点バッファとして提供するようになる。このフラグは、頂点バッファの内容をクリアして新しいデータを格納する場合に便利である。
DDLOCK_NOOVERWRITE
DirectX 7.0 の新機能。Direct3D 頂点バッファのロックでのみ使用。ロック中に最初のフレーム (このフラグが指定されていない場合は最後のロック) が修正されているため、頂点バッファの DrawPrimitive 呼び出しで参照された頂点が存在しないことを示す。このフラグは、頂点バッファにデータのみ追加する場合に便利である。
lplpData
呼び出しが成功したときに、頂点バッファ メモリのアドレスを格納する変数のアドレス。
lpdwSize
lplpData の頂点バッファ メモリのサイズを格納する変数のアドレス。バッファ サイズが不要であれば NULL を設定する。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_VERTEXBUFFEROPTIMIZED
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

注意

頂点バッファをロックした後は、IDirect3DVertexBuffer7::Unlock を呼び出すまでこのメモリにアクセスできる。

ロックされた頂点バッファからレンダリングすることはできない。ロックされた頂点バッファを使用して IDirect3DDevice7::DrawIndexedPrimitiveVB または IDirect3DDevice7::DrawPrimitiveVB メソッドを呼び出すと失敗し、D3DERR_VERTEXBUFFERLOCKED が返される。

このメソッドは、IDirect3DVertexBuffer7::Unlock メソッドを呼び出すまで、Win16Mutex をホールドさせることがしばしばある。GUI デバッガは、Win16Mutex がホールドされている間は動作しない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DVertexBuffer7::Unlock、頂点バッファの内容へのアクセス


IDirect3DVertexBuffer7::Optimize

IDirect3DVertexBuffer7::Optimize メソッドは、最適化されていない頂点バッファをトランスフォームして最適化する。

HRESULT Optimize(
  LPDIRECT3DDEVICE7 lpD3DDevice,
  DWORD dwFlags
);

パラメータ

lpD3DDevice
この頂点バッファを最適化する対象となるデバイスの IDirect3DDevice7 インターフェイスのアドレス。
dwFlags
現在は使用されていない。ゼロを設定する。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_VERTEXBUFFEROPTIMIZED
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

従来の IDirect3DVertexBuffer インターフェイスでは、このメソッドは IDirect3DDevice3 インターフェイスへのポインタを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

頂点バッファの最適化、頂点バッファ


IDirect3DVertexBuffer7::ProcessVertices

IDirect3DVertexBuffer7::ProcessVertices メソッドは、トランスフォームされていない頂点を処理して、トランスフォームまたは最適化された頂点バッファにする。

HRESULT ProcessVertices(
  DWORD dwVertexOp,
  DWORD dwDestIndex,
  DWORD dwCount,
  LPDIRECT3DVERTEXBUFFER7 lpSrcBuffer,
  DWORD dwSrcIndex,
  LPDIRECT3DDEVICE7       lpD3DDevice,
  DWORD dwFlags
);

パラメータ

dwVertexOp
元のバッファから転送された頂点をメソッドが処理する方法を定義するフラグ。次のフラグの任意の組み合わせを指定することができる。
D3DVOP_CLIP
頂点をトランスフォームし、視錐台の外側に出るあらゆる頂点をクリップする。このフラグは、(D3DDP_DONOTCLIP フラグで作成されたなどの) クリッピング情報を含まない頂点バッファには使用できない。
D3DVOP_EXTENTS
頂点をトランスフォームし、頂点がレンダリングされたら、スクリーン矩形の範囲を更新する。このフラグを使用すると潜在的にパフォーマンスが向上する可能性があるが、IDirect3DDevice7::GetClipStatus が返す範囲に対して、頂点のレンダリングの際にその頂点を考慮した更新が行われない。
D3DVOP_LIGHT
頂点をライティングする。
D3DVOP_TRANSFORM
ワールド行列、ビュー行列、射影行列を使って頂点をトランスフォームする。このフラグは常に設定する必要がある。
dwDestIndex
処理の後、頂点の配置先となる頂点バッファ (このバッファ) へのインデックス。
dwCount
元のバッファにある、処理する頂点の数。
lpSrcBuffer
元の頂点バッファの IDirect3DVertexBuffer7 インターフェイスのアドレス。
dwSrcIndex
元の頂点バッファにある、処理する頂点のうち、最初の頂点のインデックス
lpD3DDevice
頂点のトランスフォームに使用するデバイスの IDirect3DDevice7 インターフェイスのアドレス。
dwFlags
処理オプション。デフォルト処理に対してはこのパラメータを 0 に設定する。D3DPV_DONOTCOPYDATA に設定すると、現在の頂点の処理に無関係な頂点データをコピー先バッファにコピーするのを防ぐことができる。詳細については、「頂点の処理」を参照すること。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDVERTEXFORMAT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

注意

dwVertexOp パラメータには常に D3DVOP_TRANSFORMED フラグを含めること。このフラグを含めていないと、メソッドが失敗し、DDERR_INVALIDPARAMS を返す。

IDirect3DVertexBuffer インターフェイスでは、このメソッドは IDirect3DDevice3 および IDirect3DVertexBuffer インターフェイスへのポインタを受け取った。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

頂点の処理、頂点バッファ


IDirect3DVertexBuffer7::ProcessVerticesStrided

IDirect3DVertexBuffer::ProcessVerticesStrided メソッドは、未トランスフォームの頂点をトランスフォーム済みまたは最適化済み頂点バッファにする。

HRESULT ProcessVerticesStrided(
  DWORD dwVertexOp,
  DWORD dwDestIndex,
  DWORD dwCount,
  LPD3DDRAWPRIMITIVESTRIDEDDATA lpStrideData,
  DWORD dwVertexTypeDesc,
  LPDIRECT3DDEVICE7 lpD3DDevice,
  DWORD dwFlags
);

パラメータ

dwVertexOp
元のバッファから転送された頂点をメソッドが処理する方法を定義するフラグ。次のフラグの任意の組み合わせを指定することができる。
D3DVOP_CLIP
頂点をトランスフォームし、視錐台の外側に出るあらゆる頂点をクリップする。このフラグは、(D3DDP_DONOTCLIP フラグで作成されたなどの) クリッピング情報を含まない頂点バッファには使用できない。
D3DVOP_EXTENTS
頂点をトランスフォームし、頂点がレンダリングされたら、スクリーン矩形の範囲を更新する。このフラグを使用すると潜在的にパフォーマンスが向上する可能性があるが、IDirect3DDevice7::GetClipStatus が返す範囲に対して、頂点のレンダリングの際にその頂点を考慮した更新が行われない。
D3DVOP_LIGHT
頂点をライティングする。
D3DVOP_TRANSFORM
ワールド行列、ビュー行列、射影行列を使って頂点をトランスフォームする。このフラグは常に設定する必要がある。
dwDestIndex
処理の後、頂点の配置先となる頂点バッファ (このバッファ) へのインデックス。
dwCount
元のバッファにある、処理する頂点の数。
lpStrideData
このプリミティブの頂点成分のポインタおよびメモリ ストライドを格納する D3DDRAWPRIMITIVESTRIDEDDATA 構造体のアドレス。
dwVertexTypeDesc
頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせ。
lpD3DDevice
頂点のトランスフォームに使用するデバイスの IDirect3DDevice7 インターフェイスのアドレス。
dwFlags
処理オプション。デフォルト処理に対してはこのパラメータを 0 に設定する。D3DPV_DONOTCOPYDATA に設定すると、現在の頂点の処理に無関係な頂点データをコピー先バッファにコピーするのを防ぐことができる。詳細については、「頂点の処理」を参照すること。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_INVALIDVERTEXFORMAT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

注意

dwVertexOp パラメータには常に D3DVOP_TRANSFORM フラグを含めること。このフラグを含めていないと、メソッドが失敗し、DDERR_INVALIDPARAMS を返す。

このメソッドは、IDirect3DVertexBuffer7 インターフェイスと共に導入された。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DVertexBuffer7::ProcessVertices、頂点の処理、頂点バッファ


IDirect3DVertexBuffer7::Unlock

IDirect3DVertexBuffer7::Unlock メソッドは、前にロックした頂点バッファのロックを解除する。

HRESULT Unlock();

パラメータ

なし。

戻り値

成功すれば D3D_OK を返す。

失敗すれば、次のいずれかの値を返す。

D3DERR_VERTEXBUFFEROPTIMIZED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEBUSY
DDERR_SURFACELOST

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3d.h で宣言。

参照

IDirect3DVertexBuffer7::Lock、頂点バッファの内容へのアクセス


実装されていないメソッド

以下のメソッドは、DirectX の旧バージョンでは使用されていたが、その最新バージョンのインターフェイスでは実装されていない。インターフェイス全体が廃止されている場合もある。このようなインターフェイスについては、旧バージョンの DirectX に記載されている。

以前のスタブ メソッド。以下のメソッドは実装されず、どのインターフェイスにおいてもサポートされていない。

IDirect3D::Initialize

IDirect3DMaterial::Initialize

IDirect3DMaterial::Reserve

IDirect3DMaterial::Unreserve

IDirect3DTexture::Initialize

IDirect3DTexture::Unload

廃止されたメソッド。以下のメソッドは、最新バージョンのインターフェイスではサポートされていない。

IDirect3D3::CreateLight

IDirect3D3::CreateMaterial

IDirect3D3::CreateViewport

IDirect3DDevice3::GetStats

IDirect3DDevice3::GetLightState

IDirect3DDevice3::SetLightState

置き換えられたビューポート メソッド。以下のメソッドについては、IDirect3DDevice7::GetViewport および IDirect3DDevice7::SetViewport メソッドが代わって使用される。

IDirect3DDevice3::AddViewport

IDirect3DDevice3::DeleteViewport

IDirect3DDevice3::GetCurrentViewport

IDirect3DDevice3::NextViewport

IDirect3DDevice3::SetCurrentViewport

廃止された単一頂点レンダリング メソッド。以下のメソッドは、IDirect3DDevice7 インターフェイスではサポートされていない。

IDirect3DDevice3::Begin

IDirect3DDevice3::BeginIndexed

IDirect3DDevice3::End

IDirect3DDevice3::Index

IDirect3DDevice3::Vertex


廃止されたインターフェイス

実行バッファを使用したレンダリングをサポートする IDirect3DDevice および IDirect3DExecuteBuffer インターフェイスは廃止されている。これらのインターフェイスについては、旧リリースの DirectX のドキュメントを参照すること。

IDirect3DLight、IDirect3DMaterial3、および IDirect3DViewport3 インターフェイスは、IDirect3DDevice3 インターフェイスより新しいインターフェイスではサポートされていない。これらのインターフェイスの機能性は、現在ではデバイス インターフェイス自体 (IDirect3DDevice7) に含まれている。

IDirect3DLight インターフェイスは廃止されている。このインターフェイスの機能性は、現在では IDirect3DDevice7 インターフェイスに含まれている。この 2 つのインターフェイスの関係は以下のように要約される。

IDirect3DLight::GetLight および IDirect3DLight::GetLight
IDirect3DDevice7::GetLight および IDirect3DDevice7::SetLight メソッドが代わって使用される。
IDirect3DLight::Initialize
サポートされない。

以下のメソッドは、廃止された IDirect3DMaterial3 インターフェイスのメソッドである。必要に応じて IDirect3DDevice7 インターフェイスのメソッドとの相関関係を示している。

IDirect3DMaterial3::GetHandle
サポートされない。マテリアル ハンドルは IDirect3DDevice7 インターフェイスでは使用されない。
IDirect3DMaterial3::GetMaterial および IDirect3DMaterial3::SetMaterial
IDirect3DDevice7::GetMaterial および IDirect3DDevice7::SetMaterial メソッドが代わって使用される。

以下の一覧は、廃止された IDirect3DViewport3 インターフェイスのメソッドを示す。上のマテリアル関連メソッドの一覧と同様、IDirect3DDevice7 で対応するメソッドについても示す。

IDirect3DViewport3::GetBackground および IDirect3DViewport3::SetBackground
サポートされない。バックグラウンド マテリアルは IDirect3DDevice7 インターフェイスでは使用されない。
IDirect3DViewport3::GetBackgroundDepth、IDirect3DViewport3::GetBackgroundDepth2、IDirect3DViewport3::SetBackgroundDepth、および IDirect3DViewport3::SetBackgroundDepth2
サポートされない。
IDirect3DViewport3::AddLight、IDirect3DViewport3::NextLight、および IDirect3DViewport3::DeleteLight
個々のライトのパラメータには、IDirect3DDevice7::GetLight および IDirect3DDevice7::SetLight メソッドでアクセスする。ライトの有効/無効を個別に切り替えるには、IDirect3DDevice7::GetLightEnable および IDirect3DDevice7::LightEnable メソッドを使用する。
IDirect3DViewport3::LightElements
サポートされない。
IDirect3DViewport3::Clear および IDirect3DViewport3::Clear2
IDirect3DDevice7::Clear メソッドが代わって使用される。
IDirect3DViewport3::GetViewport、IDirect3DViewport3::GetViewport2、IDirect3DViewport3::SetViewport、および IDirect3DViewport3::SetViewport2
IDirect3DDevice7::GetViewport および IDirect3DDevice7::SetViewport メソッドが代わって使用される。
IDirect3DViewport3::Initialize
サポートされない。
IDirect3DViewport3::TransformVertices
サポートされない。頂点バッファを使用して頂点を手動でトランスフォームする。


D3D_OVERLOADS

D3D_OVERLOADS を定義することで、C++ のプログラマは、ここに記述された拡張機能を利用して、Direct3D 直接モード アプリケーションのコードを簡略化することができる。D3D_OVERLOADS の利用は DirectX® 5.0 と共に導入された。ここでは D3D_OVERLOADS 拡張機能のリファレンスを記述する。

これらの拡張機能は、C++ のリンクを使用して定義しなければならない。D3D_OVERLOADS が定義され、d3dtypes.h または d3d.h のインクルードの前後に extern "C" があると、リンク エラーが発生する。たとえば、以下の構文では D3D_OVERLOADS 機能を C でリンクするために、リンク エラーが発生する。

#define D3D_OVERLOADS
extern "C" {
#include <d3d.h>
};

D3D_OVERLOADS 拡張機能は、以下のグループにまとめることができる。

コンストラクタ | D3DVERTEX
 | D3DTLVERTEX
 | D3DVECTOR
 | D3DVERTEX
演算子 | アクセス許可演算子
 | 加算演算子
 | 代入演算子
 | ビットごとの等価演算子
 | D3DMATRIX
 | 除算演算子
 | 乗算演算子
 | 減算演算子
 | 単項演算子
 | ベクトル支配演算子
ヘルパー関数 | CrossProduct
 | DotProduct
 | Magnitude
 | Max
 | Maximize
 | Min
 | Minimize
 | Normalize
 | SquareMagnitude


D3D_OVERLOADS コンストラクタ

ここでは、D3D_OVERLOADS C++ 拡張機能が提供するコンストラクタのリファレンスを記述する。

  • D3DVERTEX
  • D3DTLVERTEX
  • D3DVECTOR
  • D3DVERTEX

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


D3DLVERTEX コンストラクタ

D3DLVERTEX 構造体の D3D_OVERLOADS コンストラクタは、C++ でライティング済みの頂点を作成するときに便利である。

_D3DLVERTEX() { }
_D3DLVERTEX(const D3DVECTOR& v,
            D3DCOLOR _color, D3DCOLOR _specular,
            float _tu, float _tv)
    { x = v.x; y = v.y; z = v.z; dwReserved = 0;
      color = _color; specular = _specular;
      tu = _tu; tv = _tv;
    }

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


D3DTLVERTEX コンストラクタ

D3DTLVERTEX 構造体の D3D_OVERLOADS コンストラクタは、C++ でトランスフォーム済みライティング済みの頂点を作成するときに便利である。

_D3DTLVERTEX() { }
_D3DTLVERTEX(const D3DVECTOR& v, float _rhw,
             D3DCOLOR _color, D3DCOLOR _specular,
             float _tu, float _tv)
    { sx = v.x; sy = v.y; sz = v.z; rhw = _rhw;
      color = _color; specular = _specular;
      tu = _tu; tv = _tv;
    }

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


D3DVECTOR コンストラクタ

D3DVECTOR 構造体の D3D_OVERLOADS コンストラクタは、C++ でベクトルを作成するときに便利である。

_D3DVECTOR() { }
_D3DVECTOR(D3DVALUE f);
_D3DVECTOR(D3DVALUE _x, D3DVALUE _y, D3DVALUE _z);
_D3DVECTOR(const D3DVALUE f[3]);

このコンストラクタは、以下のように定義される。

inline _D3DVECTOR::_D3DVECTOR(D3DVALUE f)
    {    x = y = z = f; }

inline _D3DVECTOR::_D3DVECTOR(D3DVALUE _x, D3DVALUE _y, D3DVALUE _z)
    {     x = _x; y = _y; z = _z; }

inline _D3DVECTOR::_D3DVECTOR(const D3DVALUE f[3])
    {     x = f[0]; y = f[1]; z = f[2]; }

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


D3DVERTEX コンストラクタ

D3DVERTEX 構造体の D3D_OVERLOADS コンストラクタは、C++ でライティング済みの頂点を作成するときに便利である。

_D3DVERTEX() { }
_D3DVERTEX(const D3DVECTOR& v, const D3DVECTOR& n, float _tu, float _tv)
    { x = v.x; y = v.y; z = v.z;
      nx = n.x; ny = n.y; nz = n.z;
      tu = _tu; tv = _tv;
    }

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


D3D_OVERLOADS 演算子

ここでは、D3D_OVERLOADS C++ 拡張機能が提供する演算子のリファレンス情報を記述する。

  • アクセス許可演算子
  • 加算演算子
  • 代入演算子
  • ビットごとの等価演算子
  • D3DMATRIX
  • 除算演算子
  • 乗算演算子
  • 減算演算子
  • 単項演算子
  • ベクトル支配演算子

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


アクセス許可演算子 (D3D_OVERLOADS)

ブラケット ("[ ]") 演算子は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。アクセスの許可には空のブラケット ("[ ]") を、ベクトルの x 要素にアクセスするには "v[0]" を、y 要素にアクセスするには "v[1]" を、z 要素にアクセスするには "v[2]" を、それぞれ使用することができる。これらの演算子は、以下のように定義される。

const D3DVALUE&operator[ ](int i) const;
D3DVALUE&operator[ ](int i);

inline const D3DVALUE&
_D3DVECTOR::operator[ ](int i) const
{
    return (&x)[i];
}

inline D3DVALUE&
_D3DVECTOR::operator[ ](int i)
{
    return (&x)[i];
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


加算演算子 (D3D_OVERLOADS)

この 2 項演算子は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。加算演算子は、以下のように定義される。

_D3DVECTOR operator + (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline _D3DVECTOR
operator + (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR(v1.x+v2.x, v1.y+v2.y, v1.z+v2.z);
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


代入演算子 (D3D_OVERLOADS)

代入演算子は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。スカラーおよびベクトルの両形式の "*=" および "/=" 演算子が実装されている(ベクトルにおける乗算および除算はメンバに対する演算である)。

_D3DVECTOR& operator += (const _D3DVECTOR& v);
_D3DVECTOR& operator -= (const _D3DVECTOR& v);
_D3DVECTOR& operator *= (const _D3DVECTOR& v);
_D3DVECTOR& operator /= (const _D3DVECTOR& v);
_D3DVECTOR& operator *= (D3DVALUE s);
_D3DVECTOR& operator /= (D3DVALUE s);

代入演算子は、以下のように定義される。

inline _D3DVECTOR&
_D3DVECTOR::operator += (const _D3DVECTOR& v)
{
   x += v.x;   y += v.y;   z += v.z;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator -= (const _D3DVECTOR& v)
{
   x -= v.x;   y -= v.y;   z -= v.z;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator *= (const _D3DVECTOR& v)
{
   x *= v.x;   y *= v.y;   z *= v.z;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator /= (const _D3DVECTOR& v)
{
   x /= v.x;   y /= v.y;   z /= v.z;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator *= (D3DVALUE s)
{
   x *= s;   y *= s;   z *= s;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator /= (D3DVALUE s)
{
   x /= s;   y /= s;   z /= s;
   return *this;
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


ビットごとの等価演算子 (D3D_OVERLOADS)

この 2 項演算子は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。ビットごとの等価演算子は以下のように定義される。

int operator == (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline int
operator == (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return v1.x==v2.x && v1.y==v2.y && v1.z == v2.z;
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


D3DMATRIX (D3D_OVERLOADS)

D3DMATRIX 構造体の D3D_OVERLOADS 実装には、かっこ ("()") 演算子が含まれている。この演算子は、C++ プログラマに対して行列中の値にアクセスする便利な方法を提供する。C++ では、構造体のメンバの参照は、名前ではなく行および列番号で行うことができ、必要に応じてそれらの番号をインデックスとして使用できる。

typedef struct _D3DMATRIX {
#if (defined __cplusplus) && (defined D3D_OVERLOADS)
    union {
        struct {
#endif

            D3DVALUE        _11, _12, _13, _14;
            D3DVALUE        _21, _22, _23, _24;
            D3DVALUE        _31, _32, _33, _34;
            D3DVALUE        _41, _42, _43, _44;

#if (defined __cplusplus) && (defined D3D_OVERLOADS)
        };
        D3DVALUE m[4][4];
    };
    _D3DMATRIX() { }

    D3DVALUE& operator()(int iRow, int iColumn) { return m[iRow][iColumn]; }
    const D3DVALUE& operator()(int iRow, int iColumn) const { return m[iRow][iColumn]; }
#endif
} D3DMATRIX, *LPD3DMATRIX;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

D3DMATRIX


除算演算子 (D3D_OVERLOADS)

この 2 項演算子は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。この演算子はスカラーおよびベクトルの両方の形式で実装されている。除算演算子は、以下のように定義される。

_D3DVECTOR operator / (const _D3DVECTOR& v, D3DVALUE s);
_D3DVECTOR operator / (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline _D3DVECTOR
operator / (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR(v1.x/v2.x, v1.y/v2.y, v1.z/v2.z);
}

inline _D3DVECTOR
operator / (const _D3DVECTOR& v, D3DVALUE s)
{
   return _D3DVECTOR(v.x/s, v.y/s, v.z/s);
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


乗算演算子 (D3D_OVERLOADS)

この 2 項演算子は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。この演算子はスカラーおよびベクトルの両方の形式で実装されている。乗算演算子は、以下のように定義される。

_D3DVECTOR operator * (const _D3DVECTOR& v, D3DVALUE s);
_D3DVECTOR operator * (D3DVALUE s, const _D3DVECTOR& v);
_D3DVECTOR operator * (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline _D3DVECTOR
operator * (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR(v1.x*v2.x, v1.y*v2.y, v1.z*v2.z);
}

inline _D3DVECTOR
operator * (const _D3DVECTOR& v, D3DVALUE s)
{
   return _D3DVECTOR(s*v.x, s*v.y, s*v.z);
}

inline _D3DVECTOR
operator * (D3DVALUE s, const _D3DVECTOR& v)
{
   return _D3DVECTOR(s*v.x, s*v.y, s*v.z);
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


減算演算子 (D3D_OVERLOADS)

この 2 項演算子は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。減算演算子は、以下のように定義される。

_D3DVECTOR operator - (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline _D3DVECTOR
operator - (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR(v1.x-v2.x, v1.y-v2.y, v1.z-v2.z);
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


単項演算子 (D3D_OVERLOADS)

この単項演算子は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。単項演算子は、以下のように定義される。

_D3DVECTOR operator + (const _D3DVECTOR& v);
_D3DVECTOR operator - (const _D3DVECTOR& v);

inline _D3DVECTOR
operator + (const _D3DVECTOR& v)
{
   return v;
}

inline _D3DVECTOR
operator - (const _D3DVECTOR& v)
{
   return _D3DVECTOR(-v.x, -v.y, -v.z);
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


ベクトル支配演算子 (D3D_OVERLOADS)

この 2 項演算子群は、D3D_OVERLOADS 拡張機能のオーバーロード演算子である。ベクトル v1 の任意の要素が、v2 の対応する要素よりも大きい場合、前者が後者を支配する。したがって、指定した 2 つのベクトルのどちらも他方を支配しないという状態が起こり得る。

int operator < (const _D3DVECTOR& v1, const _D3DVECTOR& v2);
int operator <= (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

ベクトル支配演算子は、以下のように定義される。

inline int
operator < (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return v1[0] < v2[0] && v1[1] < v2[1] && v1[2] < v2[2];
}

inline int
operator <= (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return v1[0] <= v2[0] && v1[1] <= v2[1] && v1[2] <= v2[2];
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3D_OVERLOADS ヘルパー関数

ここでは、D3D_OVERLOADS C++ 拡張機能が提供するヘルパー関数のリファレンス情報を記述する。

  • CrossProduct
  • DotProduct
  • Magnitude
  • Max
  • Maximize
  • Min
  • Minimize
  • Normalize
  • SquareMagnitude

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


CrossProduct

このヘルパー関数は、指定したベクトルの外積を返す。CrossProduct は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

_D3DVECTOR CrossProduct (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

この関数は、以下のように定義される。

inline _D3DVECTOR
CrossProduct (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
    _D3DVECTOR result;

    result[0] = v1[1] * v2[2] - v1[2] * v2[1];
    result[1] = v1[2] * v2[0] - v1[0] * v2[2];
    result[2] = v1[0] * v2[1] - v1[1] * v2[0];

    return result;
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

DotProduct


DotProduct

このヘルパー関数は、指定したベクトルの内積を返す。DotProduct は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

D3DVALUE DotProduct (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

この関数は、以下のように定義される。

inline D3DVALUE
DotProduct (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return v1.x*v2.x + v1.y * v2.y + v1.z*v2.z;
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

CrossProduct


Magnitude

このヘルパー関数は、指定したベクトルの絶対値を返す。Magnitude は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

D3DVALUE Magnitude (const _D3DVECTOR& v);

この関数は、以下のように定義される。

inline D3DVALUE
Magnitude (const _D3DVECTOR& v)
{
   return (D3DVALUE) sqrt(SquareMagnitude(v));
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

SquareMagnitude


Max

このヘルパー関数は、指定したベクトルの最大要素を返す。Max は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

D3DVALUE Max (const _D3DVECTOR& v);

この関数は、以下のように定義される。

inline D3DVALUE
Max (const _D3DVECTOR& v)
{
   D3DVALUE ret = v.x;
   if (ret < v.y) ret = v.y;
   if (ret < v.z) ret = v.z;
   return ret;
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

Min


Maximize

このヘルパー関数は、指定した 2 つのベクトルの最大成分で構成されるベクトルを返す。Maximize は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

_D3DVECTOR Maximize (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

この関数は、以下のように定義される。

inline _D3DVECTOR
Maximize (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR( v1[0] > v2[0] ? v1[0] : v2[0],
                      v1[1] > v2[1] ? v1[1] : v2[1],
                      v1[2] > v2[2] ? v1[2] : v2[2]);
}

注意

以下のような関数で、Maximize および Minimize 関数を使用して点の集合を囲むボックスを計算できる。

    void
    ComputeBoundingBox(const D3DVECTOR *pts, int N, D3DVECTOR *min, D3DVECTOR *max)
    {
        int i;
        *min = *max = pts[0];
        for (i = 1; i < N; i += 1)
        {
            *min = Minimize(*min, pts[i]);
            *max = Maximize(*max, pts[i]);
        }
    }

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

Minimize


Min

このヘルパー関数は、指定したベクトルの最小要素を返す。Min は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

D3DVALUE Min (const _D3DVECTOR& v);

この関数は、以下のように定義される。

inline D3DVALUE
Min (const _D3DVECTOR& v)
{
   D3DVALUE ret = v.x;
   if (v.y < ret) ret = v.y;
   if (v.z < ret) ret = v.z;
   return ret;
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

Max


Minimize

このヘルパー関数は、指定した 2 つのベクトルの最小要素を含むベクトルを返す。Minimize は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

_D3DVECTOR Minimize (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

この関数は、以下のように定義される。

inline _D3DVECTOR
Minimize (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR( v1[0] < v2[0] ? v1[0] : v2[0],
                      v1[1] < v2[1] ? v1[1] : v2[1],
                      v1[2] < v2[2] ? v1[2] : v2[2]);
}

注意

以下のような関数で、Maximize および Minimize 関数を使用して点の集合を囲むボックスを計算できる。

    void
    ComputeBoundingBox(const D3DVECTOR *pts, int N, D3DVECTOR *min, D3DVECTOR *max)
    {
        int i;
        *min = *max = pts[0];
        for (i = 1; i < N; i += 1)
        {
            *min = Minimize(*min, pts[i]);
            *max = Maximize(*max, pts[i]);
        }
    }

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

Maximize


Normalize

このヘルパー関数は、指定したベクトルの正規化した形式 (すなわち、ソースと同じ方向を持つ単位長ベクトル) を返す。Normalize は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

_D3DVECTOR Normalize (const _D3DVECTOR& v);

この関数は、以下のように定義される。

inline _D3DVECTOR
Normalize (const _D3DVECTOR& v)
{
   return v / Magnitude(v);
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。


SquareMagnitude

このヘルパー関数は、指定したベクトルの絶対値の 2 乗を返す。SquareMagnitude は、D3D_OVERLOADS を定義する C++ プログラマが使用できる拡張機能セットの一部である。

D3DVALUE SquareMagnitude (const _D3DVECTOR& v);

この関数は、以下のように定義される。

inline D3DVALUE
SquareMagnitude (const _D3DVECTOR& v)
{
   return v.x*v.x + v.y*v.y + v.z*v.z;
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3d.h で宣言。

参照

Magnitude


コールバック関数

ここでは、Direct3D 直接モードを使用する場合に実装が必要となることがあるコールバック関数のリファレンス情報を記述する。以下の関数が実装される。

  • D3DEnumDevicesCallback7
  • D3DEnumPixelFormatsCallback


D3DEnumDevicesCallback7

D3DEnumDevicesCallback7 は、Direct3D7::EnumDevices メソッドのアプリケーション定義コールバック関数である。

HRESULT CALLBACK D3DEnumDevicesCallback7(
  LPSTR lpDeviceDescription,
  LPSTR lpDeviceName,
  LPD3DDEVICEDESC7 lpD3DDeviceDesc,
  LPVOID lpContext
);

パラメータ

lpDeviceDescription
デバイスのテクスチャ記述のアドレス。
lpDeviceName
デバイス名のアドレス。
lpD3DDeviceDesc
Direct3D デバイスのハードウェア能力を含む D3DDEVICEDESC7 構造体のアドレス。
lpContext
このコールバック関数に渡すアプリケーション定義データのアドレス。

戻り値

列挙を繰り返す場合、アプリケーションは D3DENUMRET_OK を返さなければならない。キャンセルする場合は D3DENUMRET_CANCEL を返す。

注意

このコールバック関数は、IDirect3D3 より新しいすべてのインターフェイスの D3DEnumDevicesCallback コールバックに代わって使用される。

コールバック関数を呼び出す順序を決定するとき、システムは最初に最も高い階層のオブジェクトを検索して、次にそれらが作成された順序でコールバック関数を呼び出す。

データ型 PD3DENUMDEVICESCALLBACK7 は、このコールバック関数へのポインタとして定義されている。

typedef HRESULT (CALLBACK * LPD3DENUMDEVICESCALLBACK7)(
  LPSTR lpDeviceDescription, LPSTR lpDeviceName,
  LPD3DDEVICEDESC7, LPVOID);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要

バージョン :DirectX 7.0 が必要。
ヘッダー : d3dcaps.h で宣言。


D3DEnumPixelFormatsCallback

D3DEnumPixelFormatsCallback は、IDirect3D3::EnumZBufferFormats および IDirect3DDevice3::EnumTextureFormats メソッドのアプリケーション定義コールバック関数である。

HRESULT CALLBACK D3DEnumPixelFormatsCallback(
  LPDDPIXELFORMAT lpDDPixFmt,
  LPVOID          lpContext
);

パラメータ

lpDDPixFmt
列挙されるピクセル フォーマットを記述する DDPIXELFORMAT 構造体のアドレス。
lpContext
呼び出し元から関数に渡されるアプリケーション定義データのアドレス。

戻り値

列挙を繰り返す場合、アプリケーションは D3DENUMRET_OK を返さなければならない。キャンセルする場合は D3DENUMRET_CANCEL を返す。

注意

データ型 LPD3DENUMPIXELFORMATSCALLBACK は、このコールバック関数へのポインタとして定義されている。

typedef HRESULT (WINAPI* LPD3DENUMPIXELFORMATSCALLBACK)(LPDDPIXELFORMAT lpDDPixFmt, LPVOID lpContext);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dcaps.h で宣言。


廃止されたコールバック関数

Direct3D のヘッダー ファイルは、廃止されたコールバック関数や新しいコールバック関数が代わって使用されるようになったコールバック関数を、後方互換性を維持するために宣言している。廃止されていても、そのドキュメントは旧リリースの DirectX から入手できる。

D3DEnumDevicesCallback
廃止され、D3DEnumDevicesCallback7 コールバック関数が代わって使用される。
D3DEnumTextureFormatsCallback
廃止され、D3DEnumPixelFormatsCallback コールバック関数が代わって使用される。
D3DValidateCallback
廃止されている。この関数および実行バッファのレンダリングについては、旧リリースの DirectX のドキュメントを参照すること。


マクロ

ここでは、Direct3D 直接モードが提供するマクロのリファレンス情報を記述する。

  • D3DCLIPPLANEn
  • D3DDivide
  • D3DFVF_TEXCOORDSIZEn
  • D3DMultiply
  • D3DRGB
  • D3DRGBA
  • D3DVAL
  • D3DVALP
  • RGB_GETBLUE
  • RGB_GETGREEN
  • RGB_GETRED
  • RGB_MAKE
  • RGB_TORGBA
  • RGBA_GETALPHA
  • RGBA_GETBLUE
  • RGBA_GETGREEN
  • RGBA_GETRED
  • RGBA_MAKE
  • RGBA_SETALPHA
  • RGBA_TORGB


D3DCLIPPLANEn

D3DCLIPPLANEn マクロは、ユーザー定義クリップ面を有効にするビット パターンを定義する。このマクロは、D3DRENDERSTATE_CLIPPLANEENABLE レンダリング ステート値の設定を簡素化するために定義されている。

#define D3DCLIPPLANE0 (1 << 0)
#define D3DCLIPPLANE1 (1 << 1)
#define D3DCLIPPLANE2 (1 << 2)
#define D3DCLIPPLANE3 (1 << 3)
#define D3DCLIPPLANE4 (1 << 4)
#define D3DCLIPPLANE5 (1 << 5)
#define D3DCLIPPLANE6 (1 << 6)
#define D3DCLIPPLANE7 (1 << 7)

パラメータ

なし。

注意

ユーザー定義クリップ面は、D3DRENDERSTATE_CLIPPLANEENABLE レンダリング ステートに設定される DWORD 値に 1 つまたは複数のビット (つまり 0 ではない) が格納されている場合に有効になる。レンダリング ステート値の DWORD に重要性はなく、システムはその値を番号として解釈しない。その代わり、DWORD を解析し、対応するビットが設定されたクリップ面を有効にする。ビット 0 は最初のクリップ面 (インデックス 0) を制御し、ビット 1 は 2 番目の面を制御する、という順で面は制御される。

これらのマクロで作成するビット パターンは、論理和演算子で結合することで、同時に複数のクリップ面を有効にできる。この組み合わせからマクロのいずれかを省くだけで、そのインデックスのクリップ面を簡単に無効にできる。

参照

D3DRENDERSTATE_CLIPPLANEENABLE


D3DDivide

D3DDivide マクロは、2 数の除算を行う。

D3DDivide(a, b)    (float)((double) (a) / (double) (b))

パラメータ

a and b
式の被除数と除数。

戻り値

除算の商を返す。

動作環境

Windows NT/2000 :WindowsNT 4.0 Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DMultiply


D3DFVF_TEXCOORDSIZEn

D3DFVF_TEXCOORDSIZEn マクロは、柔軟な頂点フォーマットの記述内でテクスチャ座標フォーマットの識別に使用されるビット パターンを構築する。このマクロの結果は、論理和演算子を使用して柔軟な頂点フォーマット内で結合できる。

D3DFVF_TEXCOORDSIZE1(CoordIndex) (D3DFVF_TEXTUREFORMAT1 << (CoordIndex*2 + 16))
D3DFVF_TEXCOORDSIZE2(CoordIndex) (D3DFVF_TEXTUREFORMAT2)
D3DFVF_TEXCOORDSIZE3(CoordIndex) (D3DFVF_TEXTUREFORMAT3 << (CoordIndex*2 + 16))
D3DFVF_TEXCOORDSIZE4(CoordIndex) (D3DFVF_TEXTUREFORMAT4 << (CoordIndex*2 + 16))

パラメータ

CoordIndex
テクスチャ座標サイズ (1、2、3、または 4 次元) が適用されるテクスチャ座標セットを識別する値。

注意

以下の柔軟な頂点フォーマットの記述は、位置座標、法線、ディフーズ色、スペキュラ色、および 2 つのテクスチャ座標セットを持つ頂点フォーマットを識別する。1 つ目のテクスチャ座標セットには単一の要素が含まれ、2 つ目のセットには 2 つの要素が含まれる。

DWORD dwFVF;
dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE | D3DFVF_SPECULAR |
        D3DFVF_TEXCOORDSIZE1(0) |  \\ 1 つ目のテクスチャ座標セット (インデックス 0) に 1D テクスチャ座標を使用する。
        D3DFVF_TEXCOORDSIZE2(1);   \\ 2 つ目のテクスチャ座標セット (インデックス 1) に 2D テクスチャ座標を使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3dtypes.h で宣言。


D3DMultiply

D3DMultiply マクロは、2 数の乗算を行う。

D3DMultiply(a, b)    ((a) * (b))

パラメータ

a and b
掛け合わす値。

戻り値

乗算の積を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DDivide


D3DRGB

D3DRGB マクロは、指定の RGB 値を使用して色を初期化する。

D3DRGB(r, g, b) \
    (0xff000000L | ( ((long)((r) * 255)) << 16) | \
    (((long)((g) * 255)) << 8) | (long)((b) * 255))

パラメータ

r, g, and b
色の赤 (red)、緑 (green)、および青 (blue) の成分。これらの値は 0 から 1 の範囲にある浮動小数点値である。

戻り値

指定された RGB 値に対応する D3DCOLOR 値を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DRGBA


D3DRGBA

D3DRGBA マクロは、指定の RGBA 値を使用して色を初期化する。

D3DRGBA(r, g, b, a) \
    ((((long)((a) * 255)) << 24) |
    (((long)((r) * 255)) << 16) |
    (((long)((g) * 255)) << 8) | (long)((b) * 255))

パラメータ

r, g, b, and a
色の赤 (red)、緑 (green)、青 (blue)、およびアルファ (alpha) の成分。

戻り値

指定された RGBA 値に対応する D3DCOLOR 値を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DRGB


D3DVAL

D3DVAL マクロは、D3DVALUE 型の値を生成する。

D3DVAL(val)    ((float)val)

パラメータ

val
トランスフォーム対象の値。

戻り値

トランスフォーム後の値を返す。

動作環境

Windows NT/2000 :Winsows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DVALP


D3DVALP

D3DVALP マクロは、指定された精度の値を生成する。

D3DVALP(val, prec)    ((float)val)

パラメータ

val
トランスフォーム対象の値。
prec
無効。

戻り値

トランスフォーム後の値を返す。

注意

D3DVAL マクロが実装する精度は、値の小数部に対して 16 ビットである。

動作環境

Windows NT/2000 :Windows NT 4.0 SP 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DVAL


RGB_GETBLUE

RGB_GETBLUE マクロは、D3DCOLOR 値の青成分を取得する。

RGB_GETBLUE(rgb)    ((rgb) & 0xff)

パラメータ

rgb
青成分を取り出す色のインデックス。

戻り値

青成分を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGB_GETGREEN

RGB_GETGREEN マクロは、D3DCOLOR 値の緑成分を取得する。

RGB_GETGREEN(rgb)    (((rgb) >> 8) & 0xff)

パラメータ

rgb
緑成分を取り出す色のインデックス。

戻り値

緑成分を返す。

動作環境

Windows NT/2000 :Winsows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGB_GETRED

RGB_GETRED マクロは、D3DCOLOR 値の赤成分を取得する。

RGB_GETRED(rgb)    (((rgb) >> 16) & 0xff)

パラメータ

rgb
赤成分を取り出す色のインデックス。

戻り値

赤成分を返す。

動作環境

Windows NT/2000 :Winsows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGB_MAKE

RGB_MAKE マクロは、指定された値から RGB 色を作成する。

RGB_MAKE(r, g, b)    ((D3DCOLOR) (((r) << 16) |
    ((g) << 8) | (b)))

パラメータ

r, g, and b
作成する色の赤 (red)、緑 (green)、青 (blue) の成分。0 から 255 の整数値を指定する。

戻り値

カラーを返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGB_TORGBA

RGB_TORGBA マクロは、指定された RGB 色から RGBA 色を生成する。

RGB_TORGBA(rgb)    ((D3DCOLOR) ((rgb) | 0xff000000))

パラメータ

rgb
RGBA 色にトランスフォームする RGB 色。

戻り値

RGBA 色を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

RGBA_TORGB


RGBA_GETALPHA

RGBA_GETALPHA マクロは、RGBA D3DCOLOR 値のアルファ成分を取得する。

RGBA_GETALPHA(rgb)    ((rgb) >> 24)

パラメータ

rgb
アルファ成分を取り出す色のインデックス。

戻り値

アルファ成分を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGBA_GETBLUE

RGBA_GETBLUE マクロは、RGBA D3DCOLOR 値の青成分を取得する。

RGBA_GETBLUE(rgb)    ((rgb) & 0xff)

パラメータ

rgb
青成分を取り出す色のインデックス。

戻り値

青成分を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGBA_GETGREEN

RGBA_GETGREEN マクロは、RGBA D3DCOLOR 値の緑成分を取得する。

RGBA_GETGREEN(rgb)    (((rgb) >> 8) & 0xff)

パラメータ

rgb
緑成分を取り出す色のインデックス。

戻り値

緑成分を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGBA_GETRED

RGBA_GETRED マクロは、RGBA D3DCOLOR 値の赤成分を取得する。

RGBA_GETRED(rgb)    (((rgb) >> 16) & 0xff)

パラメータ

rgb
赤成分を取り出す色のインデックス。

戻り値

赤成分を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGBA_MAKE

RGBA_MAKE マクロは、指定された赤、緑、青、およびアルファ成分から RGBA D3DCOLOR 値を生成する。

RGBA_MAKE(r, g, b, a)   \
 ((D3DCOLOR) (((a) << 24) | ((r) << 16) | ((g) << 8) | (b)))

パラメータ

r, g, b, and a
作成する RGBA 色の赤 (red)、緑 (green)、青 (blue)、およびアルファ (alpha) の成分。

戻り値

カラーを返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGBA_SETALPHA

RGBA_SETALPHA マクロは、RGBA D3DCOLOR 値のアルファ成分を設定する。

RGBA_SETALPHA(rgba, x) (((x) << 24) | ((rgba) & 0x00ffffff))

パラメータ

rgba
アルファ成分を設定する RGBA 色。
x
設定するアルファ成分値。

戻り値

アルファ成分が設定された RGBA 色を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


RGBA_TORGB

RGBA_TORGB マクロは、カラーのアルファ成分を取り除くことで、指定された RGBA D3DCOLOR 値から RGB D3DCOLOR 値を生成する。

RGBA_TORGB(rgba)    ((D3DCOLOR) ((rgba) & 0xffffff))

パラメータ

rgba
RGB 色にトランスフォームする RGBA 色。

戻り値

RGB 色を返す。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

RGB_TORGBA


廃止されたマクロ

D3DSTATE_OVERRIDE マクロは、廃止された実行バッファ レンダリング アーキテクチャで使用されていた。廃止後も、Direct3D ヘッダー ファイルは後方互換性を維持するためにマクロを宣言する。このマクロおよび実行バッファの詳細については、旧リリースの DirectX のドキュメントを参照すること。


構造体

ここでは、Direct3D 直接モードで使用する以下の構造体について説明する。

  • D3DCLOPSTATUS
  • D3DCOLORVALUE
  • D3DDEVICEDESC
  • D3DDEVINFO_TEXTUREMANAGER
  • D3DDEVINFO_TEXTURING
  • D3DDP_PTRSTRIDE
  • D3DDRAWPRIMITIVESTRIDEDDATA
  • D3DLIGHT
  • D3DLINEPATTERN
  • D3DVERTEX
  • D3DMATERIAL
  • D3DMATRIX
  • D3DPRIMCAPS
  • D3DRECT
  • D3DTLVERTEX
  • D3DVECTOR
  • D3DVERTEX
  • D3DVERTEXBUFFERDESC
  • D3DVIEWPORT2

注 : すべての DirectX 構造体用のメモリは、使用する前に 0 に初期化する必要がある。さらに、dwSize メンバを含むすべての構造体は、使用前に、このメンバに構造体のサイズをバイト単位で設定しておかなければならない。次の例では、これらのタスクを共通の構造体 DDCAPS で実行している。

DDCAPS ddcaps; // まだ、使用できない。

ZeroMemory(&ddcaps, sizeof(ddcaps));
ddcaps.dwSize = sizeof(ddcaps);

// これで、構造体は使用可能になった。
.
.


D3DCLIPSTATUS

D3DCLIPSTATUS 構造体は、現在のクリップ ステータスおよびクリップ領域のエクステントを記述する。この構造体は DirectX 5.0 で導入された。

typedef struct _D3DCLIPSTATUS {
    DWORD dwFlags;
    DWORD dwStatus;
    float minx, maxx;
    float miny, maxy;
    float minz, maxz;
} D3DCLIPSTATUS, *LPD3DCLIPSTATUS;

メンバ

dwFlags
この構造体が 2D 領域、3D 領域、またはクリップ ステータスを記述するかどうかを表すフラグ。このメンバは、以下のフラグの 1 つ以上にすることができる。
D3DCLIPSTATUS_STATUS
この構造体は現在のクリップ ステータスを記述する。
D3DCLIPSTATUS_EXTENTS2
この構造体は現在の 2D 領域を記述する。このフラグは D3DCLIPSTATUS_EXTENTS3 と組み合わせることはできない。
D3DCLIPSTATUS_EXTENTS3
現在は実装されていない。
dwStatus
現在のクリップ ステータスを記述する。このメンバは、次のフラグの 1 つ以上を設定する。

組み合わせと一般フラグ

D3DSTATUS_CLIPINTERSECTIONALL
すべての CLIPINTERSECTION フラグの組み合わせ。
D3DSTATUS_CLIPUNIONALL
すべての CLIPUNION フラグの組み合わせ。
D3DSTATUS_DEFAULT
D3DSTATUS_CLIPINTERSECTIONALL と D3DSTATUS_ZNOTVISIBLE フラグの組み合わせ。この値が、デフォルトである。
D3DSTATUS_ZNOTVISIBLE
レンダリングされたプリミティブが不可視であることを示す。このフラグは、Z チェックを使用するレンダリングを実行する際、システムによって設定またはクリアされる (D3DRENDERSTATE_ZVISIBLE を参照すること)。

クリップ交差フラグ

D3DSTATUS_CLIPINTERSECTIONBACK
視錐台の後方クリップ面と比較される頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONBOTTOM
視錐台の下と比較される頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONFRONT
視錐台の前方クリップ面と比較される頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5
アプリケーション定義クリップ面の論理積をとる。
D3DSTATUS_CLIPINTERSECTIONLEFT
視錐台の左側と比較される頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONRIGHT
視錐台の右側と比較される頂点のクリップ フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONTOP
視錐台の上と比較される頂点のクリップ フラグの論理積をとる。

クリップ結合フラグ

D3DSTATUS_CLIPUNIONBACK
D3DCLIP_BACK と同じ。
D3DSTATUS_CLIPUNIONBOTTOM
D3DCLIP_BOTTOM と同じ。
D3DSTATUS_CLIPUNIONFRONT
D3DCLIP_FRONT と同じ。
D3DSTATUS_CLIPUNIONGEN0 through 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 through D3DCLIP_GEN5
アプリケーション定義クリップ面。
minx、maxx、miny、maxy、minz、maxz
現在のクリップ領域の X、Y、Z の範囲。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::GetClipStatus、IDirect3DDevice7::SetClipStatus


D3DCOLORVALUE

D3DCOLORVALUE 構造体は、D3DMATERIAL7 構造体のカラーの値を記述する。

typedef struct _D3DCOLORVALUE {
    union {
        D3DVALUE r;
        D3DVALUE dvR;
    };
    union {
        D3DVALUE g;
        D3DVALUE dvG;
    };
    union {
        D3DVALUE b;
        D3DVALUE dvB;
    };
    union {
        D3DVALUE a;
        D3DVALUE dvA;
    };
} D3DCOLORVALUE;

メンバ

dvR、dvG、dvB、および dvA
色成分の赤、緑、青、およびアルファを指定する D3DVALUE 型の値。一般にこれらの値は 0 から 1 までの値で、0 は黒である。

注意

特殊なエフェクトを出すために、この構造体のメンバを 0 から 1 の範囲外の値に設定することができる。1 より大きい値は、シーンを洗い流すような強い光を生む。マイナスの値は暗い光を生み、実際には光をシーンから除いてしまう。詳細については、「カラー ライティング」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DDEVICEDESC7

D3DDEVICEDESC7 構造体には、現在のデバイスの情報が含まれる。この構造体は、IDirect3DDevice7::GetCaps などのメソッドで現在のデバイスを問い合わせるために使用される。

この構造体は IDirect3DDevice3 より新しいすべてのデバイス インターフェイスで D3DDEVICEDESC 構造体に代わって使用される。

typedef struct _D3DDeviceDesc7 {
    DWORD        dwDevCaps;
    D3DPRIMCAPS  dpcLineCaps;
    D3DPRIMCAPS  dpcTriCaps;
    DWORD        dwDeviceRenderBitDepth;
    DWORD        dwDeviceZBufferBitDepth;
    DWORD        dwMinTextureWidth, dwMinTextureHeight;
    DWORD        dwMaxTextureWidth, dwMaxTextureHeight;
    DWORD        dwMaxTextureRepeat;
    DWORD        dwMaxTextureAspectRatio;
    DWORD        dwMaxAnisotropy;
    D3DVALUE     dvGuardBandLeft;
    D3DVALUE     dvGuardBandTop;
    D3DVALUE     dvGuardBandRight;
    D3DVALUE     dvGuardBandBottom;
    D3DVALUE     dvExtentsAdjust;
    DWORD        dwStencilCaps;
    DWORD        dwFVFCaps;
    DWORD        dwTextureOpCaps;
    WORD         wMaxTextureBlendStages;
    WORD         wMaxSimultaneousTextures;
    DWORD        dwMaxActiveLights;
    D3DVALUE     dvMaxVertexW;
    GUID         deviceGUID;
    WORD         wMaxUserClipPlanes;
    WORD         wMaxVertexBlendMatrices;
    DWORD        dwVertexProcessingCaps;
    DWORD        dwReserved1;
    DWORD        dwReserved2;
    DWORD        dwReserved3;
    DWORD        dwReserved4;
} D3DDEVICEDESC7, *LPD3DDEVICEDESC7;

メンバ

dwDevCaps
デバイスの能力を識別するフラグ。
D3DDEVCAPS_CANBLTSYSTONONLOCAL
デバイスは、システムメモリ テクスチャから非ローカル ビデオメモリ テクスチャへのブリットをサポートする。

このフラグは DirectX 7.0 で導入された。

D3DDEVCAPS_CANRENDERAFTERFLIP
デバイスはページ フリップの後で、レンダリング コマンドを待つこともできる。このフラグはアプリケーション動作を変えるものではない。単にデバイスが比較的高速であることを示すものである。

このフラグは DirectX 5.0 で導入された。

D3DDEVCAPS_DRAWPRIMTLVERTEX
デバイスは、DrawPrimitive 対応ハードウェア アブストラクション レイヤ (HAL) をエクスポートする。

このフラグは DirectX 5.0 で導入された。

D3DDEVCAPS_EXECUTESYSTEMMEMORY
デバイスは、システム メモリから実行バッファを使用できる。
D3DDEVCAPS_EXECUTEVIDEOMEMORY
デバイスは、ビデオ メモリから実行バッファを使用できる。
D3DDEVCAPS_FLOATTLVERTEX
トランスフォーム後の頂点データを浮動小数点で取得。
D3DDEVCAPS_HWRASTERIZATION
デバイスには、シーンのラスタ化用のハードウェア アクセラレーションがある。
D3DDEVCAPS_HWTRANSFORMANDLIGHT
デバイスは、ハードウェアでトランスフォーム & ライティングをサポートする。

このフラグは DirectX 7.0 で導入された。

D3DDEVCAPS_SEPARATETEXTUREMEMORIES
デバイスは、ステージごとに別々のテクスチャ メモリ プールを使用する。テクスチャはその生成時に、DDSURFACEDESC2 構造体の dwTextureStage メンバを適切なステージ識別子に設定することにより、明示的にテクスチャ ステージに割り当てなければならない。
D3DDEVCAPS_SORTDECREASINGZ
深度の減少方向にソートされたデータが必要。
D3DDEVCAPS_SORTEXACT
精密にソートされたデータが必要。
D3DDEVCAPS_SORTINCREASINGZ
深度の増加方向にソートされたデータが必要。
D3DDEVCAPS_TEXTURENONLOCALVIDMEM
デバイスは、非ローカル ビデオ (AGP) メモリからテクスチャを取得できる。

このフラグは DirectX 5.0 で導入された。AGP メモリの詳細については、DirectDraw ドキュメントの「非ローカル ビデオ メモリ サーフェスの使用」を参照すること。

D3DDEVCAPS_TEXTURESYSTEMMEMORY
システム メモリからテクスチャを取得可能。
D3DDEVCAPS_TEXTUREVIDEOMEMORY
デバイス メモリからテクスチャを取得可能。
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY
トランスフォーム済みライティング済みの頂点用に、システム メモリをバッファに使用可能。
D3DDEVCAPS_TLVERTEXVIDEOMEMORY
トランスフォーム済みライティング済みの頂点用に、ビデオ メモリをバッファに使用可能。
dpcLineCaps および dpcTriCaps
線の描画や三角形プリミティブのデバイスのサポート情報を定義する D3DPRIMCAPS 構造体。
dwDeviceRenderBitDepth
デバイスのレンダリング ビット深度。このメンバには、DirectDraw ビット深度定数 DDBD_8、DDBD_16、DDBD_24、または DDBD_32 のいずれかまたは複数を指定できる。
dwDeviceZBufferBitDepth
デバイスの深度バッファのビット深度。このメンバには、DirectDraw ビット深度定数 DDBD_8、DDBD_16、DDBD_24、または DDBD_32 のいずれかまたは複数を指定できる。
dwMinTextureWidth、dwMinTextureHeight
このデバイスのテクスチャの最小の幅と高さ。
dwMaxTextureWidth、dwMaxTextureHeight
このデバイスのテクスチャの最大の幅と高さ。
dwMaxTextureRepeat
正規化した後のテクスチャ インデックスの整数ビットの全範囲。D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE ビットが設定されている場合、デバイスは、テクスチャ アドレッシング モードが適用されるまでテクスチャ サイズによるスケーリングを行わない。これが設定されていない場合は、デバイスはテクスチャ サイズ (最大詳細レベル) によるテクスチャ インデックスのスケーリングを実行してから補間を行う。
dwMaxTextureAspectRatio
ハードウェアによってサポートされる、テクスチャの最大アスペクト比。通常は 2 の累乗。
dwMaxAnisotropy
D3DTSS_MAXANISOTROPY テクスチャステージ ステートの最大有効値。
dvGuardBandLeft、dvGuardBandTop、dvGuardBandRight および dvGuardBandBottom
ガードバンド クリッピング領域の画面空間座標。この矩形内かつビューポート矩形の外側にある座標は自動的にクリッピングされる。
dvExtentsAdjust
矩形の外辺をアンチエイリアス カーネルに適合させるためのピクセル数。
dwStencilCaps
サポートされているステンシル バッファ操作を指定するフラグ。ステンシル操作は 3 種類のステンシル バッファ操作レンダリング ステート (D3DRENDERSTATE_STENCILFAIL、D3DRENDERSTATE_STENCILPASS、D3DRENDERSTATE_STENCILFAILZFAIL) に対しては、すべて有効であると見なされる。
D3DSTENCILCAPS_DECR
D3DSTENCILOP_DECR 処理をサポートする。
D3DSTENCILCAPS_DECRSAT
D3DSTENCILOP_DECRSAT 処理をサポートする。
D3DSTENCILCAPS_INCR
D3DSTENCILOP_INCR 処理をサポートする。
D3DSTENCILCAPS_INCRSAT
D3DSTENCILOP_INCRSAT 処理をサポートする。
D3DSTENCILCAPS_INVERT
D3DSTENCILOP_INVERT 処理をサポートする。
D3DSTENCILCAPS_KEEP
D3DSTENCILOP_KEEP 処理をサポートする。
D3DSTENCILCAPS_REPLACE
D3DSTENCILOP_REPLACE 処理をサポートする。
D3DSTENCILCAPS_ZERO
D3DSTENCILOP_ZERO 処理をサポートする。
dwFVFCaps
柔軟な頂点フォーマット能力
D3DFVFCAPS_DONOTSTRIPELEMENTS
頂点要素は削除しない方がよい。つまり、頂点フォーマットが現在のレンダリング ステートで使用されない要素を含んでいても、頂点を再度生成する必要はない。この能力フラグが指定されていない場合、頂点フォーマットから不要な要素を削除すると、パフォーマンスが向上する。
D3DFVFCAPS_TEXCOORDCOUNTMASK
dwFVFCaps の下位 WORD をマスクする。このビットは、WORD データ型にキャストされ、デバイスが複数のテクスチャ ブレンディングに同時に使用できるテクスチャ座標セットの総数を示す(どの頂点に対しても最大 8 つのテクスチャ座標セットを使用できるが、デバイスでは指定された個数のテクスチャ座標セットのみブレンディングする)。
dwTextureOpCaps
このデバイスがサポートするテクスチャ操作を記述するフラグの組み合わせ。次のフラグが定義される。
D3DTEXOPCAPS_ADD
D3DTOP_ADD テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSIGNED
D3DTOP_ADDSIGNED テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSIGNED2X
D3DTOP_ADDSIGNED2X テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSMOOTH
D3DTOP_ADDSMOOTH テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDCURRENTALPHA
D3DTOP_BLENDCURRENTALPHA テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDDIFFUSEALPHA
D3DTOP_BLENDDIFFUSEALPHA テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDFACTORALPHA
D3DTOP_BLENDFACTORALPHA テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDTEXTUREALPHA
D3DTOP_BLENDTEXTUREALPHA テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDTEXTUREALPHAPM
D3DTOP_BLENDTEXTUREALPHAPM テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_BUMPENVMAP
D3DTOP_BUMPENVMAP テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_BUMPENVMAPLUMINANCE
D3DTOP_BUMPENVMAPLUMINANCE テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_DISABLE
D3DTOP_DISABLE テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_DOTPRODUCT3
D3DTOP_DOTPRODUCT3 テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE
D3DTOP_MODULATE テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE2X
D3DTOP_MODULATE2X テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE4X
D3DTOP_MODULATE4X テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEINVALPHA_ADDCOLOR テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATEINVCOLOR_ADDALPHA テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_PREMODULATE
D3DTOP_PREMODULATE テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_SELECTARG1
D3DTOP_SELECTARG1 テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_SELECTARG2
D3DTOP_SELECTARG2 テクスチャブレンディング処理がサポートされる。
D3DTEXOPCAPS_SUBTRACT
D3DTOP_SUBTRACT テクスチャブレンディング処理がサポートされる。
wMaxTextureBlendStages
サポートされるテクスチャブレンディング ステージの最大数。
wMaxSimultaneousTextures
テクスチャ ブレンディング ステージに同時にバインドできるテクスチャの最大数。「注意」を参照すること。
dwMaxActiveLights
同時にアクティブにできるライトの最大数。
dvMaxVertexW
デバイスがサポートする最大 W ベース深度値。
deviceGUID
デバイスのグローバル ユニーク識別子 (GUI)。IID_IDirect3DHALDevice、IID_IDirect3DTnLHalDevice、または IID_IDirect3DRGBDevice のいずれか。
wMaxUserClipPlanes
サポートされるユーザー定義クリップ面の最大数。このメンバは 0 から D3DMAXUSERCLIPPLANES までの範囲になる。

ユーザー定義クリップ面の操作には、IDirect3DDevice7::GetClipPlane および IDirect3DDevice7::SetClipPlane メソッドを使用する。

wMaxVertexBlendMatrices
複数の行列による頂点ブレンディングを実行する際にデバイスが適用する配列の最大数。
dwVertexProcessingCaps
頂点の処理能力。
D3DVTXPCAPS_TEXGEN
デバイスはテクスチャ座標を生成できる。
D3DVTXPCAPS_MATERIALSOURCE7
デバイスは選択可能な頂点色ソースをサポートする。詳細については、「ライトの色の種類とソース」を参照すること。
D3DVTXPCAPS_VERTEXFOG
デバイスは頂点フォグをサポートする。
D3DVTXPCAPS_DIRECTIONALLIGHTS
デバイスはディレクショナル ライトをサポートする。
D3DVTXPCAPS_POSITIONALLIGHTS
デバイスは局部ライト (ポイント ライト、スポット ライトなど) をサポートする。
D3DVTXPCAPS_LOCALVIEWER
デバイスはローカル ビューアをサポートする。
dwReserved1 から dwReserved4
予約済み。

注意

wMaxTextureBlendStages および wMaxSimultaneousTextures メンバは類似しているように思えるが、互いに異なる情報を含んでいる。wMaxTextureBlendStages メンバは、現在のデバイスでサポートされるテクスチャブレンディング ステージの総数を示す。wMaxSimultaneousTextures メンバは、IDirect3DDevice7::SetTexture メソッドによってこれらのステージのうち何個のステージでテクスチャをバインドできるかを示す。

ドライバでは、この構造体に値を設定すると、能力の取得に使用するインターフェイス (IDirect3DDevice7 など) が実行バッファをサポートしていなくても、実行バッファ能力の値を設定できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3dcaps.h で宣言。

参照

D3DPRIMCAPS


D3DDEVINFO_TEXTUREMANAGER

D3DDEVINFO_TEXTUREMANAGER 構造体は、テクスチャ マネージャの現在のステートについての情報を格納する。この構造体は IDirect3DDevice7::GetInfo メソッドで使用される。

typedef struct _D3DDEVINFO_TEXTUREMANAGER {
    BOOL    bThrashing;
    DWORD   dwNumEvicts;
    DWORD   dwNumVidCreates;
    DWORD   dwNumTexturesUsed;
    DWORD   dwNumUsedTexInVid;
    DWORD   dwWorkingSet;
    DWORD   dwWorkingSetBytes;
    DWORD   dwTotalManaged;
    DWORD   dwTotalBytes;
    DWORD   dwLastPri;
} D3DDEVINFO_TEXTUREMANAGER, *LPD3DDEVINFO_TEXTUREMANAGER;

メンバ

bThrashing
スラッシング ステート。最後のフレームでスラッシングが発生した場合は TRUE、そうでない場合は FALSE。
dwNumEvicts
最後のフレームで削除されたテクスチャの個数。
dwNumVidCreates
最後のフレームでビデオ メモリに作成されたテクスチャの個数。
dwNumTexturesUsed
最後のフレームで使用されたテクスチャの総数。
dwNumUsedTexInVid
最後のフレームで使用されたビデオ メモリ テクスチャの個数。
dwWorkingSet
ビデオ メモリに現在存在するテクスチャの個数。
dwWorkingSetBytes
ビデオ メモリに存在するテクスチャによって現在割り当てられているバイト数。
dwTotalManaged
管理下のテクスチャの総数。
dwTotalBytes
管理下のテクスチャに割り当てられている総バイト数。
dwLastPri
最後に削除されたテクスチャの優先順位。

注意

ビデオ メモリ (ローカルまたは非ローカル) に存在する、最後のフレームで使用されたテクスチャの比率を求めるには、dwNumUsedTexInVid および dwNumTexturesUsed の値を使用する。以下に示すコードは、この計算方法を示す。

// この例では、d3dtminfo 変数は
// IDirect3DDevice7::GetInfo の呼び出しによって格納された D3DDEVINFO_TEXTUREMANAGER 構造体である。

DWORD dwHitRate;

// ビデオ メモリ内で使用されたテクスチャの比率を取得する。
dwHitRate = (d3dtminfo.dwNumUsedTexInVid * 100) / d3dtminfo.dwNumTexturesUsed;

参照

IDirect3DDevice7::GetInfo


D3DDEVINFO_TEXTURING

D3DDEVINFO_TEXTURING 構造体は、アプリケーションのテクスチャ処理アクティビティについての情報を格納する。この構造体は IDirect3DDevice7::GetInfo メソッドで使用される。

typedef struct _D3DDEVINFO_TEXTURING {
    DWORD   dwNumLoads;
    DWORD   dwApproxBytesLoaded;
    DWORD   dwNumPreLoads;
    DWORD   dwNumSet;
    DWORD   dwNumCreates;
    DWORD   dwNumDestroys;
    DWORD   dwNumSetPriorities;
    DWORD   dwNumSetLODs;
    DWORD   dwNumLocks;
    DWORD   dwNumGetDCs;
} D3DDEVINFO_TEXTURING, *LPD3DDEVINFO_TEXTURING;

メンバ

dwNumLoads
IDirect3DDevice7::Load メソッドの呼び出しによってテクスチャがロードされた回数。
dwApproxBytesLoaded
IDirect3DDevice7::Load メソッドの呼び出しによってロードされたおよそのバイト数。
dwNumPreLoads
IDirect3DDevice7::PreLoad メソッドの呼び出しによって管理下のテクスチャが明示的にロードされた回数。
dwNumSet
IDirect3DDevice7::SetTexture メソッドの呼び出しによってテクスチャがテクスチャブレンディング ステージに設定された回数。
dwNumCreates
アプリケーションによって作成されたテクスチャ サーフェスの個数。
dwNumDestroys
アプリケーションによって破棄 (解放) されたテクスチャの個数。
dwNumSetPriorities
IDirectDrawSurface7::SetPriority メソッドの呼び出しによってテクスチャ管理優先順位が設定された回数。
dwNumSetLODs
IDirectDrawSurface7::SetLOD メソッドの呼び出しによってミップマップの最大詳細レベルが設定された回数。
dwNumLocks
IDirectDrawSurface7::Lock メソッドの呼び出しによってテクスチャ サーフェスがロックされた回数。
dwNumGetDCs
IDirectDrawSurface7::GetDC メソッドの呼び出しによってテクスチャ サーフェスのデバイス コンテキストが取得された回数。

参照

IDirect3DDevice7::GetInfo


D3DDP_PTRSTRIDE

D3DDP_PTRSTRIDE 構造体は、柔軟な頂点フォーマット コンポーネント配列のアドレスと、配列中の次の要素へのストライドを含む。この構造体は D3DDRAWPRIMITIVESTRIDEDDATA 構造体に含まれる。

typedef struct _D3DDP_PTRSTRIDE {
    LPVOID lpvData;
    DWORD  dwStride;
} D3DDP_PTRSTRIDE;

メンバ

lpvData
データ配列のアドレス。
dwStride
配列の要素間のメモリ ストライド。

注意

この構造体は、(D3DLVERTEX 構造体など) 混成頂点フォーマット、または明確に分離された頂点成分配列で使用できる。混成頂点フォーマットでは、lpvData は特定のコンポーネントをポイントし、dwStride は混成形式のストライドをバイト単位で表す。頂点成分を 1 つだけ含む配列の場合、dwStride は配列の各要素のストライドになる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DDRAWPRIMITIVESTRIDEDDATA、ストライド頂点フォーマット


D3DDRAWPRIMITIVESTRIDEDDATA

D3DDRAWPRIMITIVESTRIDEDDATA 構造体は、柔軟な頂点フォーマット コンポーネントを含む。

typedef struct D3DDRAWPRIMITIVESTRIDEDDATA  {
    D3DDP_PTRSTRIDE position;
    D3DDP_PTRSTRIDE normal;
    D3DDP_PTRSTRIDE diffuse;
    D3DDP_PTRSTRIDE specular;
    D3DDP_PTRSTRIDE textureCoords[D3DDP_MAXTEXCOORD];
} D3DDRAWPRIMITIVESTRIDEDDATA , *LPD3DDRAWPRIMITIVESTRIDEDDATA;

メンバ

position および normal
D3DDP_PTRSTRIDE 構造体。頂点の集合の位置座標ベクトルおよび法線ベクトルの配列をポイントする (各ベクトルは 3 要素で構成される浮動小数点の配列)。
diffuse および specular
D3DDP_PTRSTRIDE 構造体。頂点集合のディフーズ色およびスペキュラ色情報を指す。それぞれの色成分は 8-8-8-8 RGBA 値である。
textureCoords
8 要素で構成される、D3DDP_PTRSTRIDE 構造体の配列。配列のそれぞれの要素は、頂点集合のテクスチャ座標配列である。指定されたテクスチャ ステージに対してどのテクスチャ座標配列を使用するかは、D3DTSS_TEXCOORDINDEX ステージ ステート値で IDirect3DDevice7::SetTextureStageState メソッドを呼び出して決定する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DDP_PTRSTRIDE、ストライド頂点フォーマット、頂点フォーマット


D3DLIGHT7

D3DLIGHT7 構造体は、ライト プロパティのセットを定義する。この構造体は IDirect3DDevice7::GetLight および IDirect3DDevice7::SetLight メソッドで使用される。

typedef struct _D3DLIGHT7 {
    D3DLIGHTTYPE    dltType;
    D3DCOLORVALUE   dcvDiffuse;
    D3DCOLORVALUE   dcvSpecular;
    D3DCOLORVALUE   dcvAmbient;
    D3DVECTOR       dvPosition;
    D3DVECTOR       dvDirection;
    D3DVALUE        dvRange;
    D3DVALUE        dvFalloff;
    D3DVALUE        dvAttenuation0;
    D3DVALUE        dvAttenuation1;
    D3DVALUE        dvAttenuation2;
    D3DVALUE        dvTheta;
    D3DVALUE        dvPhi;
} D3DLIGHT7, *LPD3DLIGHT7;

メンバ

dltType
光源の型。この値は D3DLIGHTTYPE 列挙型のメンバのいずれかである。
dcvDiffuse
光源が放出するディフーズ色。このメンバは D3DCOLORVALUE 構造体である。
dcvSpecular
光源が放出するスペキュラ色。このメンバは D3DCOLORVALUE 構造体である。
dcvAmbient
光源が放出するアンビエント色。このメンバは D3DCOLORVALUE 構造体である。
dvPosition
ワールド空間での光源の位置座標。このメンバは、ディレクショナル ライトにおいては意味がなく、このケースでは無視される。
dvDirection
ワールド空間で光が指す方向。このメンバは、ディレクショナル ライトおよびスポット ライトの場合にのみ意味を持つ。このベクトルは正規化する必要はないが、ゼロでない長さを持たねばならない。
dvRange
光源の有効距離。このメンバの最大許容値は D3DLIGHT_RANGE_MAX で、FLT_MAX の平方根として定義される。このメンバはディレクショナル ライトには影響しない。
dvFalloff
スポット ライトの内部コーン (dvTheta で指定される角度) と外部コーンの外側エッジ (dvPhi で指定される角度) との間で輝度がフォールオフする。この機能は、DirectX 5.0 には実装されていない。dvFalloff の値によるスポット ライトの変化の詳細については、「スポット ライト フォールオフ モデル」を参照すること。

ライティングに対するフォールオフの影響は微妙である。さらに、フォールオフ曲線を描くと多少の性能上のロスを被る。これらの理由により、多くの開発者はこの値を 1.0 にセットする。

dvAttenuation0、dvAttenuation1、および dvAttenuation2
光の輝度が距離によってどのように変化するかを指定する値 (ディレクショナル ライトは減衰しない)。これらのメンバは減衰定数を表す。これらの減衰値による光の変化の詳細については、「距離の増加によるライトの減衰」を参照すること。これらのメンバに有効な値の範囲は 0.0 から無限大である。
dvTheta
スポット ライトの内部コーン、つまり十分に光で照らされているスポット ライト コーンの角度をラジアン単位で表す。この値は、0 から dvPhi による指定値の範囲になければならない。
dvPhi
スポット ライトの外円錐の外側のエッジを定義する角度をラジアン単位で表す。この円錐の外側にある点はスポット ライトでライティングされない。この値は 0 から pi の範囲になければならない。

注意

DirectX 7.0 で導入されたこの構造体は、旧バージョンの DirectX で使用された D3DLIGHT2 および D3DLIGHT 構造体に代わって使用される。

この構造体が D3DLIGHT2 構造体と異なるのは、ライトのディフーズ色、スペキュラ色、およびアンビエント色を個々にメンバに指定する点である。各カラー値は、Direct3D 直接モードのライティング モジュールでシーンのライティングを決定する際に使用される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::GetLight、IDirect3DDevice7::SetLight、D3DLIGHTTYPE、ライティングとマテリアル


D3DLINEPATTERN

D3DLINEPATTERN 構造体は、直線パターンを示す。これらの値は、D3DRENDERSTATETYPE 列挙型の D3DRENDERSTATE_LINEPATTERN レンダリング ステートによって使用される。

typedef struct _D3DLINEPATTERN {
    WORD wRepeatFactor;
    WORD wLinePattern;
} D3DLINEPATTERN;

メンバ

wRepeatFactor
wLinePattern メンバで指定する 1 および 0 の連続を繰り返す回数。これによって、アプリケーションでは線パターンを伸縮できる。
wLinePattern
線パターンを指定するビット。たとえば、以下の値は、ドットラインを生成する。1100110011001100.

注意

線パターンは線の描き方を指定する。線パターンは、起点の位置に関係なく常に同じである (これは点描とは異なる。点描はオブジェクトのレンダリング方法、つまり透過性の表現方法に影響する)。

線パターンは、線に沿って、オン/オフするピクセルの 16 ピクセルのパターンを指定する。wRepeatFactor メンバで wLinePattern に入れるときのピクセルの繰り返し数を指定する。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 およびそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DLVERTEX

D3DLVERTEX 構造体は、「未トランスフォーム ライティング済みの頂点」 (色付きのモデル座標) を定義する。Direct3D で頂点トランスフォームを処理する場合は、この構造体を使用する必要がある。この構造体は、ソフトウェア ライティングが設定するデータと色だけを格納する。

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 型の値。

注意

D3DRENDERSTATE_SPECULARENABLE が TRUE の場合、テクスチャ カスケードとアルファ ブレンディングの間、ベース カラーにスペキュラ成分が追加される。ただし、DirectX 7.0 では D3DTA_SPECULAR フラグを設定すると、テクスチャ色の処理中に、適用するスペキュラ成分を割り当てることができる。詳細については、「テクスチャ引数フラグ」を参照すること。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DTLVERTEX、D3DVERTEX


D3DMATERIAL7

D3DMATERIAL7 構造体は、IDirect3DDevice7::GetMaterial および IDirect3DDevice7::SetMaterial メソッドの呼び出しのマテリアル プロパティを指定する。

typedef struct _D3DMATERIAL7 {
    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;
    };
} D3DMATERIAL7, *LPD3DMATERIAL7;

メンバ

dcvDiffuse、dcvAmbient、dcvSpecular、および dcvEmissive
それぞれ、マテリアルのディフーズ色、アンビエント色、スペキュラ色、エミッション色を指定する値。これらの値は D3DCOLORVALUE 構造体である。
dvPower
スペキュラ ハイライトの鮮明度を指定する D3DVALUE 型の値。マテリアルのスペキュラ ハイライトをオフにするには、このメンバを 0 に設定する。スペキュラ色成分を 0 に設定するだけでは不十分である。

注意

DirectX 7.0 で導入されたこの構造体は、旧バージョンの DirectX で使用された D3DMATERIAL 構造体に代わって使用される。

この構造体が従来の D3DMATERIAL 構造体と異なるのは、テクスチャ ハンドル (テクスチャ処理されたビューポート バックグラウンド) または従来のランプ ソフトウェア デバイスのランプ サイズをサポートしない点である。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::GetMaterial、IDirect3DDevice7::SetMaterial、ライティングとマテリアル


D3DMATRIX

D3DMATRIX 構造体は、IDirect3DDevice7::MultiplyTransform、IDirect3DDevice7::GetTransform、IDirect3DDevice7::SetTransform などのメソッドの行列を記述する。

C++ プログラマは、かっこ ("()") 演算子を格納するこの構造体の拡張版を使用することができる。詳細については、「D3DMATRIX (D3D_OVERLOADS)」を参照すること。

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;

注意

Direct3D では、射影行列の _34 要素は負にできない。ここで負の値を使用する必要がある場合は、代わりに射影行列全体を -1 で基準化する。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::MultiplyTransform、IDirect3DDevice7::GetTransform、IDirect3DDevice7::SetTransform


D3DPRIMCAPS

D3DPRIMCAPS 構造体は、それぞれのプリミティブ型の能力を定義する。デバイスの生成時やデバイスの能力を取得するときに使用される。この構造体は、D3DDEVICEDESC7 構造体の一部のメンバを定義する。

typedef struct _D3DPrimCaps {
    DWORD dwSize;               // 構造体のサイズ。
    DWORD dwMiscCaps;           // その他の能力。
    DWORD dwRasterCaps;         // ラスタ能力。
    DWORD dwZCmpCaps;           // Z 比較能力。
    DWORD dwSrcBlendCaps;       // ソース ブレンディング能力。
    DWORD dwDestBlendCaps;      // デスティネーション ブレンディング能力。
    DWORD dwAlphaCmpCaps;       // アルファ テスト比較能力。
    DWORD dwShadeCaps;          // シェーディング能力。
    DWORD dwTextureCaps;        // テクスチャ能力。
    DWORD dwTextureFilterCaps;  // テクスチャ フィルタリング能力。
    DWORD dwTextureBlendCaps;   // テクスチャ ブレンディング能力。
    DWORD dwTextureAddressCaps; // テクスチャ アドレッシング能力。
    DWORD dwStippleWidth;       // 点描の幅。
    DWORD dwStippleHeight;      // 点描の高さ。
} D3DPRIMCAPS, *LPD3DPRIMCAPS;

メンバ

dwSize
この構造体のバイト単位のサイズ。このメンバは構造体が使われる前に初期化しなければならない。
dwMiscCaps
このプリミティブの総体的な能力。このメンバは、次の値を 1 つ以上設定できる。
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
デバイスは、ピクセル操作の深度バッファ変更を有効にしたり、無効にしたりできる。
dwRasterCaps
ラスタ描画の能力情報。このメンバは、次の値を 1 つ以上設定できる。
D3DPRASTERCAPS_ANISOTROPY
デバイスは異方性フィルタリングをサポートする。詳細については、D3DRENDERSTATETYPE 構造体の「D3DRENDERSTATE_ANISOTROPY」を参照すること。

このフラグは DirectX 5.0 で導入された。

D3DPRASTERCAPS_ANTIALIASEDGES
デバイスは、オブジェクトの輪郭線が凸状になるようなアンチエイリアス線を作ることができる。詳細については、D3DRENDERSTATETYPE 構造体の「D3DRENDERSTATE_EDGEANTIALIAS」を参照すること。

このフラグは DirectX 5.0 で導入された。

D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT
デバイスは、ポリゴンのソート順 (後方から前方、または前方から後方) に依存するアンチエイリアシングをサポートする。アプリケーションは、アンチエイリアシングが生じることに備え、正しい順序でポリゴンを作図しなければならない。詳細については、「D3DANTIALIASMODE」列挙型を参照すること。

このフラグは DirectX 5.0 で導入された。

D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT
デバイスは、ポリゴンのソート順によらないアンチエイリアシングをサポートする。詳細については、「D3DANTIALIASMODE」列挙型を参照すること。

このフラグは DirectX 5.0 で導入された。

D3DPRASTERCAPS_DITHER
デバイスは、色の再現力を良くするためにディザ表示できる。
D3DPRASTERCAPS_FOGRANGE
デバイスは範囲準拠のフォグをサポートする。範囲準拠のフォグでは、シーンにおけるオブジェクトの深さ (z 座標) ではなく、オブジェクトのビューアからの距離でフォグ エフェクトを計算する。詳細については、「範囲ベースのフォグ」を参照すること。

このフラグは DirectX 5.0 で導入された。

D3DPRASTERCAPS_FOGTABLE
デバイスは、ピクセルの深さを指すフォグ値をトランスフォームする取得テーブルと照合して、フォグ値を算出する。
D3DPRASTERCAPS_FOGVERTEX
デバイスはライティング処理の間フォグ値を計算し、D3DTLVERTEX 構造体の specular メンバで与えられた D3DCOLOR 値のアルファ成分中の値に置き換え、ラスタの間フォグ値を補間する。
D3DPRASTERCAPS_MIPMAPLODBIAS
デバイスは詳細レベル (LOD) バイアス調整をサポートする。これらのバイアス調整で、アプリケーションがミップマップを普通よりもすっきりとまたはあまり鋭くなく見せることができるようになる。ミップマップの LOD バイアスの詳細については、「D3DRENDERSTATE_MIPMAPLODBIAS」を参照すること。
D3DPRASTERCAPS_PAT
ドライバは、パターン描画を処理できる。(D3DRENDERSTATE_LINEPATTERN や D3DRENDERSTATE_STIPPLEPATTERN レンダリング ステートの 1 つでの線描や塗りつぶし) プリミティブ用に照会される。
D3DPRASTERCAPS_ROP2
デバイスは、R2_COPYPEN 以外のラスタ化をサポートできる。
D3DPRASTERCAPS_STIPPLE
デバイスは、半透明をシミュレートするポリゴンを点描できる。
D3DPRASTERCAPS_SUBPIXEL
デバイスは、一番近い整数型のピクセル座標でなく、Z、色、テクスチャのデータのサブピクセル配置で処理する。これは、Z のブリード線を避けるのを助ける (色のジッタとピクセルのテクスチャ値も)。有効および無効に対応するステートはなく、デバイスはサブピクセル配置を実行するかしないかのいずれかである。このビットは、より高品質なレンダリングの決定のために存在する。
D3DPRASTERCAPS_SUBPIXELX
デバイスは、X 軸に沿ったサブ ピクセル配置であり、整数型の Y 軸の走査線を積み上げたものである。サブ ピクセル配置についての詳細は、D3DPRASTERCAPS_SUBPIXELを参照すること。
D3DPRASTERCAPS_TRANSLUCENTSORTINDEPENDENT
デバイスは、ポリゴンのソート順に依存しない半透明表示をサポートする。詳細については、「D3DRENDERSTATE_TRANSLUCENTSORTINDEPENDENT」を参照すること。
D3DPRASTERCAPS_WBUFFER
デバイスは W を使用する深度バッファリングをサポートする。詳細については、「深度バッファ」を参照すること。
D3DPRASTERCAPS_WFOG
デバイスは w 準拠のフォグをサポートする。W ベースのフォグは、パースペクティブ射影行列が指定された場合に使用されるが、アフィン射影では現在でも Z ベースのフォグが使用される。[3][4] 要素にゼロ以外の値がある射影行列がパースペクティブ射影行列と見なされる。
D3DPRASTERCAPS_XOR
デバイスは排他的論理和処理 (XOR) をサポートする。このフラグではなく D3DPRIM_RASTER_ROP2 を設定する場合は、排他的論理和処理がサポートされている必要がある。
D3DPRASTERCAPS_ZBIAS
デバイスは z バイアス値をサポートする。これらは平面を共有するポリゴンを別のものに見せるよう、ポリゴンに割り当てられた整数値である。詳細については、D3DRENDERSTATETYPE 列挙型の「D3DRENDERSTATE_ZBIAS」を参照すること。

このフラグは DirectX 5.0 で導入された。

D3DPRASTERCAPS_ZBUFFERLESSHSR
デバイスは、隠れサーフェスの除去 (HRS) を実行可能であり、このとき、ポリゴンのソートや、深度バッファの割り付けを必要としない。これにより、より多くのビデオ メモリをテクスチャ用に使うことができる。隠れサーフェス除去に使用するメソッドはハードウェアの機能に依存し、アプリケーション透過である。

Z バッファなしの HRS が実行されるのは、深度バッファがレンダリングターゲット サーフェスにアタッチされてなく、かつ深度バッファの比較テストが有効になっている場合 (つまり、D3DRENDERSTATE_ZENABLE 列挙定数に関連付けられたステート値が TRUE に設定されている場合) である。

D3DPRASTERCAPS_ZFOG
デバイスは W ベースのフォグをサポートする。

このフラグは DirectX 7.0 で導入された。

D3DPRASTERCAPS_ZTEST
デバイスは Z テスト処理を実行できる。これは、効果的にプリミティブをレンダリングし、Z ピクセルがレンダリングされたかどうかを示す。
dwZCmpCaps
Z バッファ比較能力。このメンバは、次の値を 1 つ以上設定できる。
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
ドライバは D3DBLEND_BOTHSRCALPHA ブレンディング モードをサポートする (このブレンディング モードは DirectX 6.0 以降では廃止されている。詳細については、「D3DBLEND」を参照すること)。
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 メンバで定義された能力フラグを含む。このメンバが D3DPCMPCAPS_ALWAYS 能力だけ、または D3DPCMPCAPS_NEVER 能力だけしかもっていない場合、ドライバはアルファ テストをサポートしない。それ以外の場合、このフラグにより、アルファ テストをサポートする個々の比較を指定する。
dwShadeCaps
シェーディング処理能力。一般的に、デバイスが (D3DOP_TRIANGLE など) 指定されたコマンドをサポートしている場合、そのデバイスは D3DSHADE_FLAT モード (D3DSHADEMODE 列挙型で指定される) をサポートすると見なされる。このフラグは、デバイスがグーロー シェーディングおよびフォン シェーディングをサポートするかどうか、および 3 つのカラー生成モードに対してそれぞれアルファ成分がサポートされるかどうかを指定する。アルファ成分が与えられたモードでサポートされない場合、そのモードで生成された色のアルファ値は必ず 255 になる。この数値が、アルファの最大値 (アルファが最強) である。フォン シェーディングは、現在サポートされていない。

モノクロ シェーディング モードでは、スペキュラ成分の青チャネルが白の輝度として解釈される (これは D3DRENDERSTATE_MONOENABLE レンダリング ステートで制御される)。

三角形の色、スペキュラ ハイライト、フォグ、およびアルファ成分には、それぞれ能力フラグがあり、アプリケーションは、そのフラグを使用して、デバイス ドライバがそれらをどのように実装しているかを知ることができる。このフラグは、シェーディング モード、色モデル、またはカラーのアルファ成分がブレンディングされるか点描されるかによって変更される。詳細については、「3D プリミティブ」を参照すること。

このメンバは、次の値を 1 つ以上設定できる。

D3DPSHADECAPS_ALPHAFLATBLEND
デバイスは、フラット ブレンディングおよび点描された透過性に対してそれぞれアルファ成分をサポートできる (D3DSHADEMODE 列挙型の D3DSHADE_FLAT ステート)。これらのモードでは、プリミティブのアルファ成分は、プリミティブの最初の頂点のカラーの一部として与えられる。
D3DPSHADECAPS_ALPHAFLATSTIPPLED
デバイスは、フラット ブレンディングおよび点描された透過性に対してそれぞれアルファ成分をサポートできる (D3DSHADEMODE 列挙型の D3DSHADE_FLAT ステート)。これらのモードでは、プリミティブのアルファ成分は、プリミティブの最初の頂点のカラーの一部として与えられる。
D3DPSHADECAPS_ALPHAGOURAUDBLEND
デバイスは、透過的にそれぞれ混合や点描されたグーロー (D3DSHADEMODE 列挙型の D3DSHADE_GOURAUD ステート) のアルファ成分をサポートできる。これらのモードでは、プリミティブのアルファ成分は頂点で与えられ、ほかの色成分と共に面に沿って補間される。
D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED
デバイスは、透過的にそれぞれ混合や点描されたグーロー (D3DSHADEMODE 列挙型の D3DSHADE_GOURAUD ステート) のアルファ成分をサポートできる。これらのモードでは、プリミティブのアルファ成分は頂点で与えられ、ほかの色成分と共に面に沿って補間される。
D3DPSHADECAPS_ALPHAPHONGBLEND
デバイスは、透過的にそれぞれ混合や点描されたフォン (D3DSHADEMODE 列挙型の D3DSHADE_PHONG) のアルファ成分をサポートできる。これらのモードで、頂点パラメータは赤、緑、青の色成分の光源エフェクトを適用して、ピクセル単位に再評価される。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_ALPHAPHONGSTIPPLED
デバイスは、透過的にそれぞれ混合や点描されたフォン (D3DSHADEMODE 列挙型の D3DSHADE_PHONG ステート) のアルファ成分をサポートできる。これらのモードで、頂点パラメータは赤、緑、青の色成分の光源エフェクトを適用して、ピクセル単位に再評価される。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_COLORFLATMONO
デバイスは、D3DCOLOR_MONO および D3DCOLOR_RGB 色モデルのそれぞれにおいて、カラー フラット シェーディングをサポートできる。これらのモードでは、プリミティブに対する色成分はプリミティブの最初の頂点の色の一部として与えられる。モノクロ ライティング モデルでは、カラーの青成分のみ補間され、RGB ライティング モデルでは赤、緑、および青成分が補間される。
D3DPSHADECAPS_COLORFLATRGB
デバイスは、D3DCOLOR_MONO および D3DCOLOR_RGB 色モデルのそれぞれにおいて、カラー フラット シェーディングをサポートできる。これらのモードでは、プリミティブに対する色成分はプリミティブの最初の頂点の色の一部として与えられる。モノクロ ライティング モデルでは、カラーの青成分のみ補間され、RGB ライティング モデルでは赤、緑、および青成分が補間される。
D3DPSHADECAPS_COLORGOURAUDMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、カラー グーロー シェーディングをサポートできる。これらのモードでは、プリミティブに対する色成分は頂点で与えられ、ほかの色成分と共に面に沿って補間される。モノクロ ライティング モデルでは、カラーの青成分のみ補間され、RGB ライティング モデルでは赤、緑、および青成分が補間される。
D3DPSHADECAPS_COLORGOURAUDRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、カラー グーロー シェーディングをサポートできる。これらのモードでは、プリミティブに対する色成分は頂点で与えられ、ほかの色成分と共に面に沿って補間される。モノクロ ライティング モデルでは、カラーの青成分のみ補間され、RGB ライティング モデルでは赤、緑、および青成分が補間される。
D3DPSHADECAPS_COLORPHONGMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、カラー フォン シェーディングをサポートできる。これらのモードでは、頂点パラメータはピクセル単位に再評価される。光源エフェクトは、RGB モデルの場合は赤、緑、青成分に適用され、モノクロ モデルの場合は青成分にのみ適用される。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_COLORPHONGRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、カラー フォン シェーディングをサポートできる。これらのモードでは、頂点パラメータはピクセル単位に再評価される。光源エフェクトは、RGB モデルの場合は赤、緑、青成分に適用され、モノクロ モデルの場合は青成分にのみ適用される。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_FOGFLAT
デバイスは、フラット、グーロー、フォン シェーディング モードでフォグをサポートできる。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_FOGGOURAUD
デバイスは、フラット、グーロー、フォン シェーディング モードでフォグをサポートできる。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_FOGPHONG
デバイスは、フラット、グーロー、フォン シェーディング モードでフォグをサポートできる。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_SPECULARFLATMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのフラット シェーディングのスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_SPECULARFLATRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのフラット シェーディングのスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_SPECULARGOURAUDMONO
デバイスは、D3DCOLOR_MONO および D3DCOLOR_RGB 色モデルのグーロー シェーディングのスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_SPECULARGOURAUDRGB
デバイスは、D3DCOLOR_MONO および D3DCOLOR_RGB 色モデルのグーロー シェーディングのスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_SPECULARPHONGMONO
デバイスは、D3DCOLOR_MONO および D3DCOLOR_RGB 色モデルのフォン シェーディングのスペキュラ ハイライトをサポートできる。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_SPECULARPHONGRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのフォン シェーディングのスペキュラ ハイライトをサポートできる。フォン シェーディングは、現在サポートされていない。
dwTextureCaps
混合テクスチャ マッピング能力。このメンバは、次の値を 1 つ以上設定できる。
D3DPTEXTURECAPS_ALPHA
D3DTBLEND_DECAL と D3DTBLEND_MODULATE テクスチャ フィルタ モードの RGBA テクスチャをサポートする。この能力が設定されていない場合は、RGB テクスチャのみこれらのモードでサポートされる。このフラグの設定を無視すると、アルファは使用可能な D3DTBLEND_DECALMASK、D3DTBLEND_DECALALPHA、D3DTBLEND_MODULATE_ALPHA フィルタ モードでサポートされる。
D3DPTEXTURECAPS_ALPHAPALETTE
パレットにアルファ情報を含むパレット化 テクスチャ サーフェスをサポートする (DDCAPS 構造体の「DDPCAPS_ALPHA」を参照すること)。
D3DPTEXTURECAPS_BORDER
D3DPTADDRESSCAPS_BORDER が代わって使用される。
D3DPTEXTURECAPS_COLORKEYBLEND
デバイスは、D3DRENDERSTATE_COLORKEYBLENDENABLE レンダリング ステートを使用してアルファ ブレンディング カラー キーイングをサポートする。
D3DPTEXTURECAPS_CUBEMAP
キューブ環境マップをサポートする。この能力フラグは DirectX 7.0 で導入された。
D3DPTEXTURECAPS_NONPOW2CONDITIONAL
場合によっては、大きさが 2 の累乗でないテクスチャの使用をサポートする。以下の条件をすべて満たす場合、この能力を公開するデバイスではこのようなテクスチャを使用できる。
  • テクスチャ ステージのテクスチャ アドレッシング モードが D3DTADDRESS_CLAMP に設定されている。
  • テクスチャ ステージのテクスチャ ラッピングが無効になっている (D3DRENDERSTATE_WRAPn を 0 に設定)。
  • ミップマッピングが使用されていない (ミップマップ化テクスチャの大きさは 2 の累乗でなければならない)。
D3DPTEXTURECAPS_PERSPECTIVE
パースペクティブ補正がサポートされる。
D3DPTEXTURECAPS_POW2
ミップマップ化されていないすべてのテクスチャの幅および高さは 2 の累乗で指定する必要がある (ミップマップ化テクスチャは、常に 2 の累乗の大きさでなければならない)。
D3DPTEXTURECAPS_PROJECTED
D3DTTFF_PROJECTED テクスチャ トランスフォーム フォグをサポートする。この能力が適用されている場合、デバイスはトランスフォーム済みテクスチャ座標を最後のテクスチャ座標で分割する。
D3DPTEXTURECAPS_SQUAREONLY
テクスチャは、すべて正方形でなければならない。
D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE
テクスチャ インデックスは、補間実行前には、テクスチャ サイズに合わせてスケーリングされない。

このフラグは DirectX 7.0 で導入された。

D3DPTEXTURECAPS_TRANSPARENCY
テクスチャ透過性がサポートされる (現在の透過色でないこれらのテクセルのみ描画される)。
dwTextureFilterCaps
テクスチャフィルタリング能力。一般的なテクスチャフィルタリング フラグは、どのテクスチャフィルタリング モードをサポートするかを示し、D3DTSS_MAGFILTER、D3DTSS_MINFILTER、または D3DTSS_MIPFILTER テクスチャステージ ステートに設定される。ステージ単位のフィルタリング能力は、IDirect3DDevice7 インターフェイスでマルチテクスチャ ブレンディングを実行する際にテクスチャ ステージでサポートするフィルタリング モードを示す。このメンバは、次に示す一般、およびステージ単位フィルタリング フラグを任意に組み合わせたものである。

一般的なテクスチャフィルタリング フラグ

D3DPTFILTERCAPS_LINEAR
バイリニア フィルタリング。最も近い座標を持つテクセルを選択した後、4 つの周辺テクセルを使用して重み付き平均を算出し、最終的な色を決定する。これは、拡大と縮小の両方で使用される。拡大または縮小のいずれかがサポートされている場合は、その両方がサポートされている必要がある。
D3DPTFILTERCAPS_LINEARMIPLINEAR
ミップマップ間のトライリニア補間。バイリニア フィルタリングを 2 つの最近接ミップマップ間に実行した後、2 色の間を線形的に補間して最終的な色を決定する。
D3DPTFILTERCAPS_LINEARMIPNEAREST
2 つのポイントサンプル ミップマップの間の線形補間。2 つの最も近いミップマップ レベルから最近接テクセルを選択した後、その 2 つのテクセル間に線形補間を実行する。
D3DPTFILTERCAPS_MIPLINEAR
バイリニア フィルタリングを結果に適用する、最近接ミップマッピング。最も近い座標を持つ適切なミップマップからテクセルを選択した後、4 つの周辺テクセルを使用して重み付き平均を算出し、最終的な色を決定する。
D3DPTFILTERCAPS_MIPNEAREST
最近接ミップマッピング。目的のピクセル値に最も近い座標を持つ適切なミップマップからテクセルを選択する。
D3DPTFILTERCAPS_NEAREST
ポイント サンプリング。希望のピクセル値に最も近い座標を持つテクセルを使用する。これは、拡大と縮小の両方で使用される。拡大または縮小のいずれかがサポートされている場合は、その両方がサポートされている必要がある。

ステージ単位テクスチャ フィルタリング フラグ

D3DPTFILTERCAPS_MAGFAFLATCUBIC
デバイスは、ステージ単位でのテクスチャ拡大のため平面キューブ フィルタリングをサポートする。平面キューブ拡大フィルタは、D3DTEXTUREMAGFILTER 列挙型のメンバ D3DTFG_FLATCUBIC で表される。
D3DPTFILTERCAPS_MAGFANISOTROPIC
デバイスは、ステージ単位でのテクスチャ拡大のため、異方性フィルタリングをサポートする。異方性拡大フィルタは、D3DTEXTUREMAGFILTER 列挙型のメンバ D3DTFG_ANISOTROPIC で表される。
D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC
デバイスは、ステージ単位でのテクスチャ拡大のため、ガウス キューブ フィルタリングをサポートする。ガウス キューブ拡大フィルタは、D3DTEXTUREMAGFILTER 列挙型のメンバ D3DTFG_GAUSSIANCUBIC で表される。
D3DPTFILTERCAPS_MAGFLINEAR
デバイスは、ステージ単位でのテクスチャ拡大のため、バイリニア補間フィルタリングをサポートする。バイリニア補間拡大フィルタは、D3DTEXTUREMAGFILTER 列挙型のメンバ D3DTFG_LINEAR で表される。
D3DPTFILTERCAPS_MAGFPOINT
デバイスは、ステージ単位でのテクスチャ拡大のため、ポイントサンプル フィルタリングをサポートする。ポイントサンプル拡大フィルタは、D3DTEXTUREMAGFILTER 列挙型のメンバ D3DTFG_POINT で表される。
D3DPTFILTERCAPS_MINFANISOTROPIC
デバイスは、ステージ単位でのテクスチャ縮小のため、異方性フィルタリングをサポートする。異方性縮小フィルタは、D3DTEXTUREMINFILTER 列挙型の D3DTFN_ANISOTROPIC メンバで表される。
D3DPTFILTERCAPS_MINFLINEAR
デバイスは、ステージ単位でのテクスチャ縮小のため、バイリニア補間フィルタリングをサポートする。バイリニア補間縮小フィルタは、D3DTEXTUREMINFILTER 列挙型のメンバ D3DTFN_LINEAR で表される。
D3DPTFILTERCAPS_MINFPOINT
デバイスは、ステージ単位でのテクスチャ縮小のため、ポイントサンプル フィルタリングをサポートする。ポイントサンプル縮小フィルタは、D3DTEXTUREMINFILTER 列挙型のメンバ D3DTFN_POINT で表される。
D3DPTFILTERCAPS_MIPFLINEAR
デバイスは、ステージ単位でのミップマップのため、トライリニア補間フィルタリングをサポートする。トライリニア補間ミップマップ フィルタは、D3DTEXTUREMIPFILTER 列挙型のメンバ D3DTFP_LINEAR で表される。
D3DPTFILTERCAPS_MIPFPOINT
デバイスは、ステージ単位でのミップマップのため、ポイント サンプル フィルタリングをサポートする。ポイント サンプル ミップマップ フィルタは、D3DTEXTUREMIPFILTER 列挙型のメンバ D3DTFP_POINT で表される。
dwTextureBlendCaps
使用しない。

旧リリースの DirectX では、このメンバに、現在は廃止されている D3DRENDERSTATE_TEXTUREMAPBLEND レンダリング ステートによるデバイスのテクスチャブレンディング適用能力についての情報が格納された。DirectX 7.0 デバイスのテクスチャブレンディング能力についての情報は、D3DDEVICEDESC7 構造体の dwTextureOpCaps メンバで公開されている。

dwTextureAddressCaps
テクスチャのアドレス能力。このメンバは、次の値を 1 つ以上設定できる。
D3DPTADDRESSCAPS_BORDER
デバイスは、D3DRENDERSTATE_BORDERCOLOR テクスチャ ステージ ステートで指定される境界色を [0.0, 1.0] 範囲外の座標に設定できる。
D3DPTADDRESSCAPS_CLAMP
デバイスは、テクスチャの固定が可能である。
D3DPTADDRESSCAPS_INDEPENDENTUV
デバイスは、テクスチャの U 座標と V 座標のテクスチャアドレッシング モードを分離できる。この能力は、D3DTSS_ADDRESSU および D3DTSS_ADDRESSV レンダリング ステート値に対応する。

このフラグは DirectX 5.0 で導入された。

D3DPTADDRESSCAPS_MIRROR
デバイスは、テクスチャの反転が可能である。
D3DPTADDRESSCAPS_WRAP
デバイスは、テクスチャの張り付けが可能である。
dwStippleWidth および dwStippleHeight
サポートされた点描の最大幅と高さ (最高 32×32 まで)。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dcaps.h で宣言。


D3DRECT

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
矩形の右下隅の座標。

動作環境

Windows NT/2000 : Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::Clear


D3DTLVERTEX

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;

パラメータ

dvSX、dvSY、および dvSZ
スクリーン座標の頂点を記述する D3DVALUE 型の値。表示される z 値の範囲内に頂点を置くためには、dvSZ の取り得る最大値は 0.99999 までである。
dvRHW
D3DVALUE 型の値で、同次座標 (x,y,z,w) の同次 w の逆数である。この値は、原点からオブジェクトまでの z 軸に沿った距離で 1 を除算した値にしばしば一致する。
dcColor および dcSpecular
頂点の色およびスペキュラ成分を記述する D3DCOLOR 型の値。
dvTU および dvTV
頂点のテクスチャ座標を記述する D3DVALUE 型の値。

注意

Direct3D は、現在のビューポート パラメータ (D3DVIEWPORT7 構造体の dwX、dwY、dwWidth、および dwHeight メンバ) を使用して D3DTLVERTEX 頂点をクリッピングする。システムは z 座標を常に [0, 1] にクリッピングする。これらの頂点をクリッピングしないようにするには、レンダリング メソッドを呼び出すときに D3DDP_DONOTCLIP フラグを使用する。

D3DRENDERSTATE_SPECULARENABLE が TRUE の場合、テクスチャ カスケードとアルファ ブレンディングの間、ベース カラーにスペキュラ成分が追加される。ただし、DirectX 7.0 では D3DTA_SPECULAR フラグを設定すると、テクスチャ色の処理中に、適用するスペキュラ成分を割り当てることができる。詳細については、「テクスチャ引数フラグ」を参照すること。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DLVERTEX、D3DVERTEX


D3DVECTOR

D3DVECTOR 構造体は、多くの Direct3D と Direct3DRM メソッドと構造体のベクトルを定義する。

typedef struct _D3DVECTOR {
    union {
        D3DVALUE x;
        D3DVALUE dvX;
    };
    union {
        D3DVALUE y;
        D3DVALUE dvY;
    };
    union {
        D3DVALUE z;
        D3DVALUE dvZ;
    };
} D3DVECTOR, *LPD3DVECTOR;

メンバ

dvX、dvY、および dvZ
ベクトルを指定する D3DVALUE 型の値。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DVERTEX

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;

メンバ

dvX、dvY、および dvZ
頂点の同次座標を指定する D3DVALUE 型の値。
dvNX、dvNY、および dvNZ
正規座標で頂点を指定する D3DVALUE 型の値。
dvTU および dvTV
頂点のテクスチャ座標を指定する D3DVALUE 型の値。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DLVERTEX、D3DTLVERTEX、D3DVALUE


D3DVERTEXBUFFERDESC

D3DVERTEXBUFFERDESC 構造体は、頂点バッファ オブジェクトのプロパティを記述する。この構造体は IDirect3D7::CreateVertexBuffer および IDirect3DVertexBuffer7::GetVertexBufferDesc メソッドで使用される。

typedef struct _D3DVERTEXBUFFERDESC {
    DWORD dwSize;
    DWORD dwCaps;
    DWORD dwFVF;
    DWORD dwNumVertices;
} D3DVERTEXBUFFERDESC, *LPD3DVERTEXBUFFERDESC;

メンバ

dwSize
この構造体のバイト単位のサイズ。このメンバは構造体が使われる前に初期化しなければならない。
dwCaps
頂点バッファを記述し、その頂点バッファが最適化された頂点データを保持できるかどうかを示す能力フラグ。このパラメータは、以下に示すフラグの任意の組み合わせで作られる。
(なし)
頂点バッファは、ドライバが効率的なリード動作を実行するために選択したメモリであれば、どのメモリに作成してもよい。
D3DVBCAPS_DONOTCLIP
頂点バッファはクリッピング情報を保持することはできない。
D3DVBCAPS_OPTIMIZED
頂点バッファは、最適化された頂点データを保持できる (このフラグは、新しい頂点バッファの作成時には使用されない)。
D3DVBCAPS_SYSTEMMEMORY
頂点バッファは、システム メモリに作成しなければならない。この能力は、ソフトウェア デバイス (MMX または RGB デバイス) または HAL デバイス (IID_IDirect3DHALDevice) を使用して頂点バッファをレンダリングする場合に使用する。
D3DVBCAPS_WRITEONLY
頂点バッファへの書き込み操作しか実行できないことをシステムに知らせる。このフラグを使用することにより、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行する。この能力を利用して作成した頂点バッファから読み出しを行おうとすると、パフォーマンスが低下することがある。
dwFVF
バッファ内の頂点の頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせ。
dwNumVertices
この頂点バッファが保持できる頂点の数の最大値。許容される最大頂点数は D3DMAXNUMVERTICES (0xFFFF) である。

注意

ソフトウェア デバイス (MMX および RGB デバイス) は、ローカルまたは非ローカルであるかどうかにかかわらず、ビデオ メモリから頂点バッファをレンダリングすることはできない。ソフトウェア デバイスを使用して頂点バッファをレンダリングするには、頂点バッファがシステム メモリに存在しなければならない。ハードウェア デバイスは、システム メモリまたはビデオ メモリのどちらの頂点バッファからでも、レンダリングすることができる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

頂点バッファの記述、頂点バッファ


D3DVIEWPORT7

D3DVIEWPORT7 構造体は、3D ボリュームが射影されるレンダリング ターゲット サーフェスのウィンドウの大きさを定義する。この構造体は IDirect3DDevice7::GetViewport および IDirect3DDevice7::SetViewport メソッドで使用される。

typedef struct _D3DVIEWPORT7{
    DWORD       dwX;
    DWORD       dwY;
    DWORD       dwWidth;
    DWORD       dwHeight;
    D3DVALUE    dvMinZ;
    D3DVALUE    dvMaxZ;
} D3DVIEWPORT7, *LPD3DVIEWPORT7

メンバ

dwX および dwY
レンダリング ターゲット サーフェス上のビューポートの左上隅を表すピクセル座標。サーフェスのサブセットにレンダリングするのでなければ、これらのメンバは 0 に設定できる。
dwWidth および dwHeight
レンダリングの対象となるサーフェス上のビューポートの大きさをピクセル単位で表す。サーフェスのサブセットに限定してレンダリングするのでなければ、これらのメンバにはレンダリング ターゲット サーフェスの大きさをセットする。
dvMinZ および dvMaxZ
シーンをレンダリングする深度範囲を記述する D3DVALUE 型の値ほとんどのアプリケーションでは、これらの値をそれぞれ 0.0 および 1.0 に設定する。これらのメンバの値の解釈は、従来の D3DVIEWPORT2 構造体で対応するメンバの場合とはまったく異なる。DirectX 7.0 では、射影行列の適用後にクリッピングが行われる。詳細については、「クリッピング ボリューム」および「射影トランスフォーム」を参照すること。

注意

DirectX 7.0 で導入されたこの構造体は、旧バージョンの DirectX で使用された D3DVIEWPORT2 および D3DVIEWPORT 構造体に代わって使用される。

dwX、dwY、dwWidth および dwHeight メンバは、レンダリングの対象となるサーフェス上のビューポートの位置と大きさを記述する。通常、アプリケーションは対象となるサーフェス全体のレンダリングを実行するので、640 x 480 のサーフェスでレンダリングを行う場合には、これらのメンバはそれぞれ 0、0、640、480 の値を取る。一般に、dvMinZ および dvMaxZ は 0.0 および 1.0 に設定されるが、ほかの値を設定して特殊エフェクトを出すこともできる。たとえば、両方の値を 0.0 に設定すると、シーンのフォアグラウンドにオブジェクトがレンダリングされる。また、両方の値を 1.0 に設定すると、オブジェクトがバックグラウンドにレンダリングされる。

デバイスのビューポート パラメータが変更されると (IDirect3DDevice7::SetViewport メソッドの呼び出しにより)、ドライバは新しいトランスフォーム配列を作成する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DVALUE、IDirect3DDevice7::GetViewport、IDirect3DDevice7::SetViewport、クリッピング ボリューム、ビューポートとクリッピング


廃止された構造体

以下の構造体は廃止されている。廃止された構造体が提供していた機能性は、現在では IDirect3DDevice7 インターフェイスおよびそれに関連する構造体に含まれている。これらの関連性を以下にまとめる。

D3DDEVICEDESC
IDirect3DDevice7::GetCaps メソッドで使用される D3DDEVICEDESC7 構造体が代わって使用される。
D3DHVERTEX
サポートされない。
D3DFINDDEVICESEARCH および D3DFINDDEVICERESULT
廃止されている。
D3DLIGHT および D3DLIGHT2
IDirect3DDevice7::GetLight および IDirect3DDevice7::SetLight メソッドで使用される D3DLIGHT7 構造体が代わって使用される。
D3DLIGHTDATA
サポートされない。
D3DLIGHTINGELEMENT
サポートされない。
D3DMATERIAL
IDirect3DDevice7::GetMaterial および IDirect3DDevice7::SetMaterial メソッドで使用される D3DMATERIAL7 構造体が代わって使用される。
D3DSTATE
サポートされない。
D3DSTATS
サポートされない。
D3DTRANSFORMCAPS
サポートされない。
D3DTRANSFORMDATA
サポートされない。
D3DVIEWPORT および D3DVIEWPORT2
IDirect3DDevice7::GetViewport および IDirect3DDevice7::SetViewport メソッドで使用される D3DVIEWPORT7 構造体が代わって使用される。

実行バッファ レンダリング、および以下の関連する構造体は、DirectX 7.0 では廃止されていると見なす。これらの構造体の詳細については、旧リリースの DirectX のドキュメントを参照すること。

  • D3DBRANCH
  • D3DEXECUTEBUFFERDESC
  • D3DEXECUTEDATA
  • D3DINSTRUCTION
  • D3DLINE
  • D3DMATRIXLOAD
  • D3DMATRIXMULTIPLY
  • D3DPICKRECORD
  • D3DPOINT
  • D3DPROCESSVERTICES
  • D3DSPAN
  • D3DSTATUS
  • D3DTEXTURELOAD
  • D3DTRIANGLE


列挙型

ここでは、Direct3D 直接モードで使用される以下の列挙型について説明する。

  • D3DANTIALIASMODE
  • D3DBLEND
  • D3DCMPFUNC
  • D3DCULL
  • D3DFILLMODE
  • D3DFOGMODE
  • D3DLIGHTTYPE
  • D3DMATERIALCOLORSOURCE
  • D3DPRIMITIVETYPE
  • D3DRENDERSTATETYPE
  • D3DSHADEMODE
  • D3DSTATEBLOCKTYPE
  • D3DSTENCILOP
  • D3DTEXTUREADDRESS
  • D3DTEXTUREMAGFILTER
  • D3DTEXTUREMINFILTER
  • D3DTEXTUREMIPFILTER
  • D3DTEXTUREOP
  • D3DTEXTURESTAGESTATETYPE
  • D3DTEXTURETRANSFORMFLAGS
  • D3DTRANSFORMSTATETYPE
  • D3DVERTEXBLENDFLAGS
  • D3DVERTEXTYPE
  • D3DZBUFFERTYPE


D3DANTIALIASMODE

D3DANTIALIASMODE 列挙型は、D3DRENDERSTATETYPE 列挙型の D3DRENDERSTATE_ANTIALIAS 値に対してサポートされるアンチエイリアシング モードを定義する。これらの値は、フルシーン アンチエイリアシングに対する設定値のみ定義する (詳細については、「アンチエイリアシング」を参照すること)。

typedef enum _D3DANTIALIASMODE {
    D3DANTIALIAS_NONE          = 0,
    D3DANTIALIAS_SORTDEPENDENT = 1,
    D3DANTIALIAS_SORTINDEPENDENT = 2
    D3DANTIALIAS_FORCE_DWORD     = 0x7fffffff,
} D3DANTIALIASMODE;
D3DANTIALIAS_NONE
アンチエイリアシングは実行されない。これがデフォルト設定である。
D3DANTIALIAS_SORTDEPENDENT
アンチエイリアシングは、ポリゴンのソート順 (後方から前方、または前方から後方) に従って行われる。アプリケーションは、アンチエイリアシングが生じることに備え、正しい順序でポリゴンを作図しなければならない。
D3DANTIALIAS_SORTINDEPENDENT
アンチエイリアシングは、ポリゴンのソート順に依存しない。
D3DANTIALIAS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DBLEND

D3DBLEND 列挙型は、D3DRENDERSTATETYPE 列挙型の 3DRENDERSTATE_DESTBLEND 値に対してサポートされるブレンディング モードを定義する。以下のメンバの説明では、ソースおよびディスティネーションの RGBA 値は添字 s および d によって示される。

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_FORCE_DWORD   = 0x7fffffff,
} D3DBLEND;
D3DBLEND_ZERO
ブレンディング係数は、(0, 0, 0, 0)。
D3DBLEND_ONE
ブレンディング係数は、(1, 1, 1, 1)。
D3DBLEND_SRCCOLOR
ブレンディング係数は、(Rs, Gs, Bs, As)。
D3DBLEND_INVSRCCOLOR
ブレンディング係数は、(1-Rs, 1-Gs, 1-Bs, 1-As)。
D3DBLEND_SRCALPHA
ブレンディング係数は、(As, As, As, As)。
D3DBLEND_INVSRCALPHA
ブレンディング係数は、(1-As, 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
廃止されている。DirectX 6.0 およびそれ以降では、ソースおよびデスティネーションのブレンディング係数に D3DBLEND_SRCALPHA と D3DBLEND_INVSRCALPHA をそれぞれ別の呼び出しで設定することにより、同じ効果を得ることができる。
D3DBLEND_BOTHINVSRCALPHA
ソースのブレンディング係数は (1-As, 1-As, 1-As, 1-As) で、デスティネーションのブレンディング係数は (As, As, As, As) である。デスティネーションのブレンディングの選択は無効になる。このブレンディング モードは、D3DRENDERSTATE_SRCBLEND レンダリング ステートでのみサポートされる。
D3DBLEND_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DCMPFUNC

D3DCMPFUNC 列挙型は、D3DRENDERSTATE_ZFUNC、D3DRENDERSTATE_ALPHAFUNC、および D3DRENDERSTATE_STENCILFUNC レンダリング ステートに対してサポートされる比較関数を定義する。

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,
    D3DCMP_FORCE_DWORD   = 0x7fffffff,
} D3DCMPFUNC;
D3DCMP_NEVER
常にテストは失敗する。
D3DCMP_LESS
新しいピクセル値が、現在のピクセル値より小さいときに応じる。
D3DCMP_EQUAL
新しいピクセル値が、現在のピクセル値と等しいときに応じる。
D3DCMP_LESSEQUAL
新しいピクセル値が、現在のピクセル値以下のときに応じる。
D3DCMP_GREATER
新しいピクセル値が、現在のピクセル値より大きいときに応じる。
D3DCMP_NOTEQUAL
新しいピクセル値が、現在のピクセル値と等しくないときに応じる。
D3DCMP_GREATEREQUAL
新しいピクセル値が、現在のピクセル値以上のときに応じる。
D3DCMP_ALWAYS
常にテストはパスする。
D3DCMP_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DCULL

D3DCULL 列挙型は、D3DRENDERSTATE_CULLMODE レンダリング ステートで使用されるカリング モードを定義する。ジオメトリにレンダリングするときの面のカリング方法を定義する。

typedef enum _D3DCULL {
    D3DCULL_NONE = 1,
    D3DCULL_CW   = 2,
    D3DCULL_CCW  = 3,
    D3DCULL_FORCE_DWORD   = 0x7fffffff,
} D3DCULL;
D3DCULL_NONE
カリングはしない。
D3DCULL_CW
右回りに切り抜く。
D3DCULL_CCW
左回りに切り抜く。
D3DCULL_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DPRIMCAPS、D3DRENDERSTATETYPE


D3DFILLMODE

D3DFILLMODE 列挙型は、塗りつぶしモードを指定する定数を設定する。これらの値は、D3DRENDERSTATETYPE 列挙型の D3DRENDERSTATE_FILLMODE レンダリング ステートで使用される。

typedef enum _D3DFILLMODE {
    D3DFILL_POINT     = 1,
    D3DFILL_WIREFRAME = 2,
    D3DFILL_SOLID     = 3
    D3DFILL_FORCE_DWORD   = 0x7fffffff,
} D3DFILLMODE;
D3DFILL_POINT
点で塗りつぶす。
D3DFILL_WIREFRAME
ワイヤフレームで塗りつぶす。この塗りつぶしモードは、DrawPrimitive メソッド使用時、クリップされたプリミティブでは動作しない。
D3DFILL_SOLID
面で塗りつぶす。
D3DFILL_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DFOGMODE

D3DFOGMODE 列挙型は、フォグ モードを指定する定数を設定する。これらの値は、D3DRENDERSTATETYPE 列挙型の D3DRENDERSTATE_FOGTABLEMODE および D3DRENDERSTATE_FOGVERTEXMODE レンダリング ステートで使用される。

typedef enum _D3DFOGMODE {
    D3DFOG_NONE   = 0,
    D3DFOG_EXP    = 1,
    D3DFOG_EXP2   = 2,
    D3DFOG_LINEAR = 3
    D3DFOG_FORCE_DWORD   = 0x7fffffff,
} D3DFOGMODE;
D3DFOG_NONE
フォグ エフェクトはない。
D3DFOG_EXP
次の方程式の指数で、フォグ エフェクトが増す。

D3DFOG_EXP2
次の方程式の指数の 2 乗で、フォグ エフェクトが増す。

D3DFOG_LINEAR
次の方程式の始点と終点の間で線形に、フォグ エフェクトが増す。

これは、現在サポートされている唯一のフォグ モードである。

D3DFOG_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

モノクロ (ランプ) ライティング モードでは、フォグはその色が黒の場合に限り正常に機能する (ライトが存在しない場合はあらゆるフォグ カラーが機能する。この場合、すべてのフォグ カラーが事実上黒だからである)。

詳細については、「フォグ」を参照すること。

注 : フォグは、透明度を表す基準である。この場合、フォグの値が小さいほど、オブジェクトが見えなくなる。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DLIGHTTYPE

D3DLIGHTTYPE 列挙型は、光源型を定義する。この列挙型は D3DLIGHT7 構造体で使用される。

typedef enum _D3DLIGHTTYPE {
    D3DLIGHT_POINT         = 1,
    D3DLIGHT_SPOT          = 2,
    D3DLIGHT_DIRECTIONAL   = 3,
    D3DLIGHT_FORCE_DWORD   = 0x7fffffff,
} D3DLIGHTTYPE;
D3DLIGHT_POINT
光源は点である。光は空間内の点を持ち、全方向に光をエミッションする。
D3DLIGHT_SPOT
ライトはスポット ライトである。このライトは、照射がコーン内に制限される点を除いては、ポイント ライトに類似する。このライト タイプには、方向、およびコーンの形状を決めるその他のパラメータがいくつかある。これらのパラメータについては、「D3DLIGHT7」構造体を参照すること。
D3DLIGHT_DIRECTIONAL
ライトはディレクショナル ライトである。これは無限大の距離で点光源を用いることに等しい。
D3DLIGHT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

ディレクショナル ライトはポイント ライトより処理は多少速いが、結果についてはポイント ライトの方が上である。スポット ライトは面白い視覚エフェクトを出すが、計算上高価である。

パラレル ポイント ライトは DirectX 7.0 以降ではサポートされない。したがって、この列挙型は従来の D3DLIGHT_PARALLELPOINT メンバを含んでいない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DMATERIALCOLORSOURCE

D3DMATERIALCOLORSOURCE 列挙型は、ライティング計算のために色または色成分にアクセスする必要がある位置を定義する。

typedef enum _D3DMATERIALCOLORSOURCE {
    D3DMCS_MATERIAL    = 0,
    D3DMCS_COLOR1      = 1,
    D3DMCS_COLOR2      = 2,
    D3DMCS_FORCE_DWORD = 0x7fffffff,
} D3DMATERIALCOLORSOURCE;
D3DMCS_MATERIAL
現在のマテリアルの色を使用する。
D3DMCS_COLOR1
ディフーズ頂点色を使用する。
D3DMCS_COLOR2
スペキュラ頂点色を使用する。
D3DMCS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙が定義する値は、以下のレンダリング ステートで使用される。

  • D3DRENDERSTATE_DIFFUSEMATERIALSOURCE
  • D3DRENDERSTATE_SPECULARMATERIALSOURCE
  • D3DRENDERSTATE_AMBIENTMATERIALSOURCE
  • D3DRENDERSTATE_EMISSIVEMATERIALSOURCE

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3dtypes.h で宣言。


D3DPRIMITIVETYPE

D3DPRIMITIVETYPE 列挙型は、DrawPrimitive メソッドがサポートするプリミティブを列挙する。この型は DirectX 5.0 で導入された。

typedef enum _D3DPRIMITIVETYPE {
    D3DPT_POINTLIST     = 1,
    D3DPT_LINELIST      = 2,
    D3DPT_LINESTRIP     = 3,
    D3DPT_TRIANGLELIST  = 4,
    D3DPT_TRIANGLESTRIP = 5,
    D3DPT_TRIANGLEFAN   = 6
    D3DPT_FORCE_DWORD   = 0x7fffffff,
} D3DPRIMITIVETYPE;
D3DPT_POINTLIST
頂点を別個の点の集積としてレンダリングする。
D3DPT_LINELIST
別個の線分のリストとして頂点をレンダリングする。このプリミティブ タイプを使用する呼び出しは、カウントが 2 より小さいか、奇数の場合は失敗する。
D3DPT_LINESTRIP
頂点を単一のポリラインとしてレンダリングする。このプリミティブ タイプを使用する呼び出しは、カウントが 2 より小さい場合は失敗する。
D3DPT_TRIANGLELIST
別個の三角形の連続として指定の頂点をレンダリングする。各 3 頂点のグループは個別に三角形を定義する。このプリミティブ タイプを使用する呼び出しは、カウントが 3 より小さいか、3 の倍数でない場合は失敗する。

裏面の選択は、現在のワインディング順レンダリング ステートによって影響される。

D3DPT_TRIANGLESTRIP
頂点を三角形の展開図としてレンダリングする。このプリミティブ タイプを使用する呼び出しは、カウントが 3 より小さい場合は失敗する。背面カリング フラグは、偶数番号の三角形で自動的に反転する。
D3DPT_TRIANGLEFAN
頂点を三角形の扇形としてレンダリングする。このプリミティブ タイプを使用する呼び出しは、カウントが 3 より小さい場合は失敗する。
D3DPT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

三角形ストリップまたは三角形ファンを使用する方が、三角形リストを使用するより効率がよい。詳細については、「三角形ストリップ」および「三角形ファン」を参照すること。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::DrawIndexedPrimitive、IDirect3DDevice7::DrawIndexedPrimitiveStrided、IDirect3DDevice7::DrawIndexedPrimitiveVB、IDirect3DDevice7::DrawPrimitive、IDirect3DDevice7::DrawPrimitiveStrided、IDirect3DDevice7::DrawPrimitiveVB、プリミティブの種類


D3DRENDERSTATETYPE

D3DRENDERSTATETYPE 列挙型は、IDirect3DDevice7::SetRenderState および IDirect3DDevice7::GetRenderState メソッドによって設定および取得されるレンダリング ステートを定義する。

typedef enum _D3DRENDERSTATETYPE {
    D3DRENDERSTATE_ANTIALIAS          = 2,    // アンチエイリアシング モード。
    D3DRENDERSTATE_TEXTUREPERSPECTIVE = 4,    // パースペクティブ補正。
    D3DRENDERSTATE_ZENABLE            = 7,    // Z テストを有効にする。
    D3DRENDERSTATE_FILLMODE           = 8,    // 塗りつぶしモード。
    D3DRENDERSTATE_SHADEMODE          = 9,    // シェーディング モード。
    D3DRENDERSTATE_LINEPATTERN        = 10,   // 直線パターン。
    D3DRENDERSTATE_ZWRITEENABLE       = 14,   // Z 書き込みを有効にする。
    D3DRENDERSTATE_ALPHATESTENABLE    = 15,   // アルファ テストを有効にする。
    D3DRENDERSTATE_LASTPIXEL          = 16,   // 最後のピクセルを直線で描く。
    D3DRENDERSTATE_SRCBLEND           = 19,   // ソースのブレンディング係数。
    D3DRENDERSTATE_DESTBLEND          = 20,   // デスティネーションのブレンディング係数。
    D3DRENDERSTATE_CULLMODE           = 22,   // 背面カリング モード。
    D3DRENDERSTATE_ZFUNC              = 23,   // Z 比較機能。
    D3DRENDERSTATE_ALPHAREF           = 24,   // 参照アルファ値。
    D3DRENDERSTATE_ALPHAFUNC          = 25,   // アルファ比較機能。
    D3DRENDERSTATE_DITHERENABLE       = 26,   // ディザリングを有効にする。
    D3DRENDERSTATE_ALPHABLENDENABLE   = 27,   // アルファ ブレンディングを有効にする。
    D3DRENDERSTATE_FOGENABLE          = 28,   // フォグを有効にする。
    D3DRENDERSTATE_SPECULARENABLE     = 29,   // スペキュラ ハイライトを有効にする。
    D3DRENDERSTATE_ZVISIBLE           = 30,   // Z チェックを有効にする。
    D3DRENDERSTATE_STIPPLEDALPHA      = 33,   //点描アルファを有効にする。
    D3DRENDERSTATE_FOGCOLOR           = 34,   // フォグ カラー。
    D3DRENDERSTATE_FOGTABLEMODE       = 35,   // フォグ モード。
    D3DRENDERSTATE_FOGTABLESTART      = 36,   // フォグ テーブル開始 (D3DRENDERSTATE_FOGSTART と同じ)。
    D3DRENDERSTATE_FOGTABLEEND        = 37,   // フォグ テーブル終了 (D3DRENDERSTATE_FOGEND と同じ)。
    D3DRENDERSTATE_FOGTABLEDENSITY    = 38,   // フォグ テーブル密度 (D3DRENDERSTATE_FOGDENSITY と同じ)。
    D3DRENDERSTATE_FOGSTART           = 36,   // フォグ開始 (頂点とピクセル フォグに対して)。
    D3DRENDERSTATE_FOGEND             = 37,   // フォグ終了 (頂点とピクセル フォグに対して)。
    D3DRENDERSTATE_FOGDENSITY         = 38,   // フォグ密度 (頂点とピクセル フォグに対して)。
    D3DRENDERSTATE_EDGEANTIALIAS      = 40,   // アンチエイリアス エッジ。
    D3DRENDERSTATE_COLORKEYENABLE     = 41,   // カラー キー透過を有効にする。
    D3DRENDERSTATE_ZBIAS              = 47,   // Z バイアス。
    D3DRENDERSTATE_RANGEFOGENABLE     = 48,   // 範囲ベースのフォグを有効にする。
    D3DRENDERSTATE_STENCILENABLE      = 52,   // ステンシル処理を有効または無効にする。
    D3DRENDERSTATE_STENCILFAIL        = 53,   // ステンシル処理。
    D3DRENDERSTATE_STENCILZFAIL       = 54,   // ステンシル処理。
    D3DRENDERSTATE_STENCILPASS        = 55,   // ステンシル処理。
    D3DRENDERSTATE_STENCILFUNC        = 56,   // ステンシル比較関数。
    D3DRENDERSTATE_STENCILREF         = 57,   // ステンシル テストの参照値。
    D3DRENDERSTATE_STENCILMASK        = 58,   // ステンシル テストで使用されるマスク値。
    D3DRENDERSTATE_STENCILWRITEMASK   = 59,   // ステンシル バッファ書き込みマスク。
    D3DRENDERSTATE_TEXTUREFACTOR      = 60,   // テクスチャ係数。
    D3DRENDERSTATE_WRAP0              = 128,  // 1 番目のテクスチャ座標セットのラップ フラグ。
       // ここでは 1 から 6 のラップ レンダリング ステートは省略。
    D3DRENDERSTATE_WRAP7              = 135,  // 最後のテクスチャ座標セットのラップ フラグ。
    D3DRENDERSTATE_CLIPPING            = 136, // プリミティブのクリッピングを有効または無効にする。
    D3DRENDERSTATE_LIGHTING            = 137, // ライティングを有効または無効にする。
    D3DRENDERSTATE_EXTENTS             = 138, // スクリーン範囲の更新を有効または無効にする。
    D3DRENDERSTATE_AMBIENT             = 139, // シーンのアンビエント色。
    D3DRENDERSTATE_FOGVERTEXMODE       = 140, // 頂点フォグのフォグ モード。
    D3DRENDERSTATE_COLORVERTEX         = 141, // 頂点単位の色を有効または無効にする。
    D3DRENDERSTATE_LOCALVIEWER         = 142, // パースペクティブ スペキュラ ハイライトを有効または無効にする。
    D3DRENDERSTATE_NORMALIZENORMALS    = 143, // 頂点法線の自動正規化を有効にする。
    D3DRENDERSTATE_COLORKEYBLENDENABLE = 144, // アルファ ブレンディング カラー キーを有効または無効にする。
    D3DRENDERSTATE_DIFFUSEMATERIALSOURCE  = 145, // 頂点単位のディフーズ色の位置。
    D3DRENDERSTATE_SPECULARMATERIALSOURCE = 146, // 頂点単位のスペキュラ色の位置。
    D3DRENDERSTATE_AMBIENTMATERIALSOURCE  = 147, // 頂点単位のアンビエント色の位置。
    D3DRENDERSTATE_EMISSIVEMATERIALSOURCE = 148, // 頂点単位のエミッション色の位置。
    D3DRENDERSTATE_VERTEXBLEND              = 151, // 複数の行列による頂点ブレンディング モード。
    D3DRENDERSTATE_CLIPPLANEENABLE          = 152, // 1 つまたは複数のユーザー定義クリッピプ面を有効にする
    D3DRENDERSTATE_FORCE_DWORD        = 0x7fffffff,
} D3DRENDERSTATETYPE;
D3DRENDERSTATE_ANTIALIAS
希望のタイプのフルシーン アンチエイリアシングを指定する D3DANTIALIASMODE 列挙型のメンバのいずれか。デフォルト値は、D3DANTIALIAS_NONE である。詳細については、「フルシーン アンチエイリアシング」および「アンチエイリアシング ステート」を参照すること。

フルシーン アンチエイリアシングは、D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT または D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT 能力を示すデバイスに限り、有効にすることができる。

D3DRENDERSTATE_TEXTUREPERSPECTIVE
TRUE を設定すると、パースペクティブ補正テクスチャ マッピングが有効になる (「パースペクティブ補正」を参照すること)。デフォルト値は TRUE である。IDirect3DDvice3 より前のインターフェイスでは、デフォルト値は FALSE である。詳細については、「テクスチャ パースペクティブ ステート」を参照すること。
D3DRENDERSTATE_ZENABLE
D3DZBUFFERTYPE 列挙型のメンバの 1 つとしての深度バッファ ステート。Z バッファリングを有効にするには D3DZB_TRUE、w バッファリングを有効にするには D3DZB_USEW、深度バッファリングを無効にするには D3DZB_FALSE を、それぞれ設定する。

レンダリングの対象となるサーフェスに深度バッファがアタッチされている場合、このレンダリング ステートのデフォルト値は D3DZB_TRUE であり、それ以外の場合は D3DZB_FALSE である。

D3DRENDERSTATE_FILLMODE
D3DFILLMODE 列挙型のメンバのいずれかまたは複数。デフォルト値は D3DFILL_SOLID である。
D3DRENDERSTATE_SHADEMODE
D3DSHADEMODE 列挙型のメンバのいずれかまたは複数。デフォルト値は D3DSHADE_GOURAUD である。
D3DRENDERSTATE_LINEPATTERN
D3DLINEPATTERN 構造体。デフォルト値は wRepeatPattern が 0 で、wLinePattern が 0 である。
D3DRENDERSTATE_ZWRITEENABLE
深度バッファへの書き込みを有効にするには TRUE に設定する。デフォルト値は TRUE である。アプリケーションはこのメンバを利用することにより、システムが新しい深度値で深度バッファを更新してしまうのを防ぐことができる。FALSE の場合、レンダリング ステート D3DRENDERSTATE_ZFUNC (深度バッファリングが行われていると仮定) に従って深度比較が実行されるが、深度値はバッファに書き込まれない。
D3DRENDERSTATE_ALPHATESTENABLE
アルファ テストを可能にするには、TRUE。デフォルト値は FALSE である。このメンバを使用すると、アルファ値に基づいてピクセルを受け取るか拒否するかを判断するテストをオフにできる。

入ってくるアルファ値は、D3DRENDERSTATE_ALPHAFUNC レンダリング ステートにより提供される比較関数を用いて参照アルファ値と比較される。このモードが可能になると、テストが成功した場合に限り、アルファ ブレンディングが起きる。

D3DRENDERSTATE_LASTPIXEL
直線や三角形の最後のピクセルを描画可能とするには、FALSE に設定する。デフォルト値は TRUE である。
D3DRENDERSTATE_SRCBLEND
D3DBLEND 列挙型のメンバのいずれか。デフォルト値は D3DBLEND_ONE である。
D3DRENDERSTATE_DESTBLEND
D3DBLEND 列挙型のメンバの 1 つ。デフォルト値は D3DBLEND_ZERO である。
D3DRENDERSTATE_CULLMODE
背面を向ける三角形を切り取る必要が生じた場合に、その方法を指定する。D3DCULL 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DCULL_CCW である。
D3DRENDERSTATE_ZFUNC
D3DCMPFUNC 列挙型のメンバのいずれか。デフォルト値は D3DCMP_LESSEQUAL である。このメンバは、アプリケーションにカメラからの距離を基準とするピクセルの受け取りや受け取り拒否を許可する。

ピクセルの深度値を深度バッファの値と比較する。ピクセルの深度値が比較関数で許可された場合にピクセルが書き込まれる。

深度値が深度バッファに書き込まれるのは、レンダリング ステートが TRUE の場合だけである。

この深度テストに失敗した方が、ソフトウェアによるラスタ化や多くのハードウェア アクセラレータの処理は速くなる。これは、ピクセルのレンダリング処理を行わない場合には、テクスチャをフィルタ処理したり変調したりする必要がなくなるためである。

D3DRENDERSTATE_ALPHAREF
アルファ テストが有効に設定されている場合に、ピクセルをテストするための基準アルファ値を指定する値。これは、DWORD レンダリング ステート値の下位 8 ビットにあたる 8 ビット値である。値は 0x00000000 から 0x000000FF の範囲内である。
D3DRENDERSTATE_ALPHAFUNC
D3DCMPFUNC 列挙型のメンバのいずれか。デフォルト値は、D3DCMP_ALWAYS である。このメンバは、アプリケーションにアルファ値を基準とするピクセルの受け取りや受け取り拒否を許可する。
D3DRENDERSTATE_DITHERENABLE
TRUE のとき、ディザリングを可能とする。デフォルト値は FALSE である。
D3DRENDERSTATE_ALPHABLENDENABLE
アルファ ブレンドによる透明化を有効にする場合、TRUE にセットする。デフォルト値は FALSE である。このメンバは従来の D3DRENDERSTATE_BLENDENABLE レンダリング ステートに代わって使用される。詳細については、「注意」を参照すること。

DirectX 5.0 以前では、このレンダリング ステートを利用して、ソフトウェア ラスタライザはカラー キー検索とアルファ ブレンディングの切り替えを行っていた。現在は D3DRENDERSTATE_COLORKEYENABLE レンダリング ステートを使用して、カラー キーイングを切り替える (ハードウェアは、アルファ ブレンディングの切り替えにのみ、D3DRENDERSTATE_BLENDENABLE レンダリング ステートを使用してきた)。

アルファ ブレンディングのタイプは D3DRENDERSTATE_SRCBLEND と D3DRENDERSTATE_DESTBLEND レンダリング ステートによって決定される。D3DRENDERSTATE_COLORKEYENABLE と共に D3DRENDERSTATE_ALPHABLENDENABLE を使用すれば、アルファ ブレンディングの微妙なコントロールが可能になる。

D3DRENDERSTATE_ALPHABLENDENABLE は、D3DTEXTUREBLEND 列挙型により指定されるテクスチャ ブレンディング モードには影響を与えない。テクスチャ ブレンディングは、論理的にはピクセル パイプラインの D3DRENDERSTATE_ALPHABLENDENABLE 部分よりずっと前に行われる。両者が相互に関連するのは、D3DTEXTUREBLEND フェーズ後のポリゴンに残るアルファ部分が、D3DRENDERSTATE_ALPHABLENDENABLE フェーズでフレーム バッファの内容との相互作用を制御するために使われることがあるだけである。

アプリケーションは、D3DDEVICEDESC7 構造体の 3DDEVCAPS_DRAWPRIMTLVERTEX フラグを調べて、このレンダリング ステートがサポートされているかどうかをチェックしなければならない。

D3DRENDERSTATE_FOGENABLE
TRUE はフォグ ブレンディングを可能にする。デフォルト値は FALSE である。詳細については、「フォグ ブレンディング」および「フォグ」を参照すること。
D3DRENDERSTATE_SPECULARENABLE
TRUE はスペキュラ ハイライトを可能にする。デフォルト値は FALSE である。IDirect3DDevice3 より前のインターフェイスでは、デフォルト値は TRUE である。

スペキュラ ハイライトは、光の当たっているオブジェクトの各頂点がそのオブジェクトの原点にあるかのように算出される。これは、オブジェクトが原点の周囲でモデル化され、光源とオブジェクト間の距離が比較的に大きい場合に限り、予測値を与える。

このメンバが TRUE に設定されている場合、テクスチャ カスケードとアルファ ブレンディングの間でベース カラーにスペキュラ色が追加される。

D3DRENDERSTATE_ZVISIBLE
サポートされない。
D3DRENDERSTATE_STIPPLEDALPHA
TRUE のとき、点描アルファを可能とする。デフォルト値は FALSE である。

現在のソフトウェア ラスタライザは、このレンダリング ステートを無視する。現在のハードウェアがこのレンダリング ステートをサポートするかどうかを調べるには、D3DPRIMCAPS 構造体の D3DPSHADECAPS_ALPHAFLATSTIPPLED フラグを使用する。

D3DRENDERSTATE_FOGCOLOR
D3DCOLOR 型の値。デフォルト値は 0 である。詳細については、「フォグ カラー」を参照すること。
D3DRENDERSTATE_FOGTABLEMODE
ピクセル フォグに使用されるフォグ式。D3DFOGMODE 列挙型のメンバのいずれかを設定する。デフォルト値は D3DFOG_NONE である。詳細については、「ピクセル フォグ」を参照すること。
D3DRENDERSTATE_FOGTABLESTART
D3DRENDERSTATE_FOGSTART にマッピングする。
D3DRENDERSTATE_FOGTABLEEND
D3DRENDERSTATE_FOGEND にマッピングする。
D3DRENDERSTATE_FOGTABLEDENSITY
このレンダリング ステートは D3DRENDERSTATE_FOGDENSITY レンダリング ステートにマッピングする。
D3DRENDERSTATE_FOGSTART
線形フォグ モードにおける、ピクセルまたは頂点フォグ エフェクトの開始深度。頂点フォグの場合、深度はワールド空間で指定される。ピクセル フォグの場合は、デバイス空間 [0.0, 1.0] またはワールド空間のいずれかで指定される。ピクセル フォグでは、フォグ計算に Z が使用される場合はこれらの値はデバイス空間にあり、目との相対フォグ (W フォグ) が使用される場合はワールド空間にある。詳細については、「フォグ パラメータ」および「視点からの相対深度 対 Z ベースの深度」を参照すること。

このレンダリング ステートの値は浮動小数点値である。IDirect3DDevice7::SetRenderState および IDirect3DDevice7::SetRenderState は DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。

lpd3dDevice->SetRenderState( D3DRENDERSTATE_FOGSTART, *((LPDWORD) (&fFogStart)) );
D3DRENDERSTATE_FOGEND
線形フォグ モードにおける、ピクセルまたは頂点フォグ エフェクトの終了深度。頂点フォグの場合、深度はワールド空間で指定される。ピクセル フォグの場合は、デバイス空間 [0.0, 1.0] またはワールド空間のいずれかで指定される。ピクセル フォグでは、フォグ計算に Z が使用される場合はこれらの値はデバイス空間にあり、目との相対フォグ (W フォグ) が使用される場合はワールド空間にある。詳細については、「フォグ パラメータ」および「視点からの相対深度 対 Z ベースの深度」を参照すること。

このレンダリング ステートの値は浮動小数点値である。IDirect3DDevice7::SetRenderState および IDirect3DDevice7::SetRenderState は DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。

lpd3dDevice->SetRenderState( D3DRENDERSTATE_FOGDENSITY, *((LPDWORD) (&fFogDensity)) );
D3DRENDERSTATE_FOGDENSITY
指数フォグ モード (D3DFOG_EXP および D3DFOG_EXP2) で使用するピクセルまたは頂点フォグのフォグ密度。有効な密度は 0.0 から 1.0 の範囲内である。デフォルト値は 1,0 である。詳細については「フォグ パラメータ」を参照すること。

このレンダリング ステートの値は浮動小数点値である。IDirect3DDevice7::SetRenderState および IDirect3DDevice7::SetRenderState は DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。

lpd3dDevice->SetRenderState( D3DRENDERSTATE_FOGDENSITY, *((LPDWORD) (&fFogDensity)) );
D3DRENDERSTATE_EDGEANTIALIAS
TRUE は、オブジェクトの凸面の輪郭を形成する線をアンチエイリアスする。デフォルト値は FALSE である。詳細については、「エッジ アンチエイリアシング」および「アンチエイリアシング ステート」を参照すること。TRUE の場合、レンダリングの対象となるのは線のみで、シーン内のポリゴンの外側エッジに限定される。このレンダリング ステートが設定されていて、三角形または点が描画されると、その動作は不定である。アンチエイリアシングは、隣接ピクセルの値の平均値を取ることによって実行される。アンチエイリアシングを行うのは最良のやり方ではないが、効率的ではある。この種の操作をサポートするハードウェアは普及しつつある。

エッジ アンチエイリアシングは、D3DPRASTERCAPS_ANTIALIASEDGES 能力を示すデバイスに限り、有効にすることができる。

D3DRENDERSTATE_COLORKEYENABLE
TRUE は、カラー キー透過を可能にする。デフォルト値は FALSE である。このレンダリング ステートを D3DRENDERSTATE_ALPHABLENDENABLE で使用すると、ブレンディングの微調整が可能になる。

アプリケーションでは D3DDEVICEDESC7 構造体の D3DDEVCAPS_DRAWPRIMTLVERTEX フラグを調べて、このレンダリング ステートがサポートされているかどうかをチェックする。

カラー キー透過が有効な場合、DDSD_CKSRCBLT フラグで作成されたテクスチャ サーフェスのみ影響を受ける。DDSD_CKSRCBLT フラグで作成されていないサーフェスは、カラー キー透過のエフェクトを示す。

D3DRENDERSTATE_ZBIAS
物理的には同一面上にあるポリゴンが別々に存在するように見せる、0 から 16 までの範囲の整数値。Z バイアス値が高いポリゴンは、Z バイアス値が低いポリゴンより手前に表示されるため、描画順序を決めるソートを実行する必要はない。たとえば、値 1 を持つポリゴンは、値 0 のポリゴンよりも手前に見える。デフォルト値は 0 である。詳細については、「深度バッファの使用」を参照すること。
D3DRENDERSTATE_RANGEFOGENABLE
TRUE を設定すると、範囲ベースの頂点フォグが有効になる (デフォルト値は FALSE。この場合は深度に基づくフォグが使用される)。範囲準拠のフォグでは、シーンにおけるオブジェクトの深さ (z 座標) ではなく、オブジェクトのビューアからの距離でフォグ エフェクトを計算する。範囲準拠のフォグでは、通常すべてのフォグ計算メソッドが動くが、計算に深さでなく範囲を使う点だけが異なる。

範囲はフォグ計算に使うのに正しい要素であるが、範囲が計算上高価となる一方、深さは通常計算済みなので、代って深さが広く使われる。深度を使用してフォグを計算すると、周辺オブジェクトのフォグ エフェクトが視点の移動と共に変化するという好ましくない影響が出る。この場合、深度は変化するが範囲は一定のままである。

このレンダリング ステートは D3DVERTEX 頂点に対してのみ作用する。D3DLVERTEX または D3DTLVERTEX 頂点を指定する場合、RGBF フォグ値の F (フォグ) 要素が範囲について補正済みでなければならない。

現在のところ、ピクセル単位での範囲ベースのフォグをサポートするハードウェアは存在しないため、範囲補正は頂点フォグでのみ行われる。詳細については、「範囲ベースのフォグ」および「頂点フォグ」を参照すること。

D3DRENDERSTATE_STENCILENABLE
TRUE の場合はステンシル操作が可能になり、FALSE では無効になる。デフォルト値は FALSE である。詳細については、「ステンシル バッファ」を参照すること。
D3DRENDERSTATE_STENCILFAIL
ステンシル テストに失敗したときに実行するステンシル操作。これには D3DSTENCILOP 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DSTENCILOP_KEEP である。詳細については、「ステンシル バッファ」を参照すること。
D3DRENDERSTATE_STENCILZFAIL
ステンシル テストにパスし、深度テスト (Z テスト) に失敗した場合に実行するステンシル操作。これには D3DSTENCILOP 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DSTENCILOP_KEEP である。詳細については、「ステンシル バッファ」を参照すること。
D3DRENDERSTATE_STENCILPASS
ステンシル テストおよび深度 (Z) テストの両方にパスした場合に実行するステンシル操作。これには D3DSTENCILOP 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DSTENCILOP_KEEP である。詳細については、「ステンシル バッファ」を参照すること。
D3DRENDERSTATE_STENCILFUNC
ステンシル テストのための比較関数。これには D3DCMPFUNC 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DCMP_ALWAYS である。

比較関数は、ステンシル バッファの要素を基準値と比較するために使われる。この比較は、基準値のビットと、ステンシル マスク (D3DRENDERSTATE_STENCILMASK レンダリング ステートにより設定) に設定されたステンシル バッファ要素にのみ適用される。TRUE の場合、ステンシル テストにパスする。

D3DRENDERSTATE_STENCILREF
ステンシル テストのための整数基準値。デフォルト値は 0 である。
D3DRENDERSTATE_STENCILMASK
基準値と、それぞれのステンシル バッファ要素に適用し、ステンシル テストのための有効ビットを決定するマスク。デフォルト マスクは 0xFFFFFFFF である。
D3DRENDERSTATE_STENCILWRITEMASK
ステンシル バッファに書き込む値に適用する書き込みマスク。デフォルト マスクは 0xFFFFFFFF である。
D3DRENDERSTATE_TEXTUREFACTOR
D3DTA_TFACTOR テクスチャブレンディング引数、または D3DTOP_BLENDFACTORALPHA テクスチャブレンディング操作を用いたマルチテクスチャ ブレンディングで使用される色。関連する値は D3DCOLOR 変数である。
D3DRENDERSTATE_WRAP0 から D3DRENDERSTATE_WRAP7
複数のテクスチャ座標セットに対するテクスチャラッピング動作。これらのレンダリング ステートの有効値として、D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 フラグを組み合わせることができる。これらの値を設定すると、指定されたテクスチャに対して 1、2、3、および 4 次元方向 (s、ｔ、ｒ、および q 方向と呼ばれる場合もある) のラッピングが実行される。これらのレンダリング ステートのデフォルト値は 0 である (全方向のラッピングが無効)。詳細については、「テクスチャ ラッピング」を参照すること。
D3DRENDERSTATE_CLIPPING
TRUE を設定すると、Direct3D によるプリミティブのクリッピングが有効になる。FALSE を設定すると無効になる。デフォルト値は TRUE である。
D3DRENDERSTATE_LIGHTING
TRUE を設定すると、Direct3D のライティングが有効になる。FALSE を設定すると無効になる。デフォルト値は TRUE である。頂点法線を含む頂点のみ正しくライトが当てられ、法線を含まない頂点ではすべてのライティング計算で 0 の内積が使用される。
D3DRENDERSTATE_EXTENTS
TRUE を設定すると、レンダリングの呼び出しごとにスクリーン範囲が更新される。FALSE を設定すると、スクリーン範囲の更新が無効になる。デフォルト値は FALSE である。
D3DRENDERSTATE_AMBIENT
アンビエント ライトの色。この値は D3DCOLOR 型である。デフォルト値は 0 である。このレンダリング ステートは、従来の D3DLIGHTSTATE_AMBIENT ライト ステートに類似する。
D3DRENDERSTATE_FOGVERTEXMODE
頂点フォグ用のフォグ式。D3DFOGMODE 列挙型のメンバのいずれかを設定する。デフォルト値は D3DFOG_NONE である。詳細については、「頂点フォグ」を参照すること。このレンダリング ステートは、従来の D3DLIGHTSTATE_FOGVERTEXMODE ライティング ステートに類似する。
D3DRENDERSTATE_COLORVERTEX
TRUE を設定すると、頂点単位の色が有効になる。FALSE を設定すると無効になる。デフォルト値は TRUE である。頂点単位の色を有効にすると、個々の頂点に定義された色がライティング計算に含まれるようになる。このレンダリング ステートは、従来の D3DLIGHTSTATE_COLORVERTEX ライティング ステートに類似する。

詳細については、以下のレンダリング ステートを参照すること。

  • D3DRENDERSTATE_DIFFUSEMATERIALSOURCE
  • D3DRENDERSTATE_SPECULARMATERIALSOURCE
  • D3DRENDERSTATE_AMBIENTMATERIALSOURCE
  • D3DRENDERSTATE_EMISSIVEMATERIALSOURCE
D3DRENDERSTATE_LOCALVIEWER
TRUE を設定すると、カメラとの相対角度に依存したスペキュラ ハイライトが有効になる。FALSE を設定すると、直行スペキュラ ハイライトが使用される。デフォルト値は TRUE である。正射影を使用するアプリケーションでは FALSE に指定すること。
D3DRENDERSTATE_NORMALIZENORMALS
TRUE を設定すると、頂点法線の自動正規化が有効になる。FALSE を設定すると無効になる。デフォルト値は FALSE である。この機能を有効にすると、頂点がカメラ空間にトランスフォームされた後で頂点法線が正規化されるが、計算負荷が大きい。
D3DRENDERSTATE_COLORKEYBLENDENABLE
TRUE を設定すると、アルファ ブレンディング カラー キーイングが有効になる。FALSE を設定すると無効になる。アルファ ブレンディング カラー キー モードは、一致するテクスチャ サンプルのアルファおよびカラーを 0 に設定する。アプリケーションでは、アルファテストおよびアルファ ブレンディング モードを設定して、必要な破棄およびアルファ ブレンディング結果の両方、またはそのいずれかを行う必要がある。
D3DRENDERSTATE_DIFFUSEMATERIALSOURCE
ライティング計算に使用されるディフーズ色のソース。有効値は D3DMATERIALCOLORSOURCE 列挙型のメンバである。デフォルト値は D3DMCS_COLOR1。このレンダリング ステートの値が使用されるのは、D3DRENDERSTATE_COLORVERTEX レンダリング ステートが TRUE に設定されている場合のみである。
D3DRENDERSTATE_SPECULARMATERIALSOURCE
ライティング計算に使用されるスペキュラ色のソース。有効値は D3DMATERIALCOLORSOURCE 列挙型のメンバである。デフォルト値は D3DMCS_COLOR2。
D3DRENDERSTATE_AMBIENTMATERIALSOURCE
ライティング計算に使用されるアンビエント色のソース。有効値は D3DMATERIALCOLORSOURCE 列挙型のメンバである。デフォルト値は D3DMCS_COLOR2。
D3DRENDERSTATE_EMISSIVEMATERIALSOURCE
ライティング計算に使用されるエミッション色のソース。有効値は D3DMATERIALCOLORSOURCE 列挙型のメンバである。デフォルト値は D3DMCS_MATERIAL。
D3DRENDERSTATE_VERTEXBLEND
ジオメトリがある場合、ジオメトリ ブレンディングを実行するために使用する行列の個数。有効値は D3DVERTEXBLENDFLAGS 列挙型のメンバである。デフォルト値は D3DVBLEND_DISABLE。詳細については、「ジオメトリ ブレンディング」を参照すること。
D3DRENDERSTATE_CLIPPLANEENABLE
ユーザー定義クリップ面を有効または無効にする。有効値は、各ビットのステータス (設定の有無) によって対応するユーザー定義クリップ面の起動ステートを切り替える、任意の DWORD である。最下位ビット (ビット 0) はインデックス 0 の最初のクリップ面を制御し、後続ビットはそれより上位のインデックスのクリップ面の起動を制御する。ビットが設定されている場合、シーンのレンダリング中に適切なクリップ面が適用される。デフォルト値は 0 である。

クリップ面を簡単に有効にできるように、D3dtypes.h ヘッダー ファイルには D3DCLIPPLANEn マクロが宣言されている。

D3DRENDERSTATE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

D3DRENDERSTATE_BLENDENABLE メンバは D3DRENDERSTATE_ALPHABLENDENABLE メンバに置き換えられている。意味がより明瞭になるように名前も変更されている。以前のアプリケーションとの互換性を維持するために、D3DRENDERSTATE_ALPHABLENDENABLE に対応するものとして D3DRENDERSTATE_BLENDENABLE 定数が宣言されている。

#define D3DRENDERSTATE_BLENDENABLE  D3DRENDERSTATE_ALPHABLENDENABLE

Direct3D は、アプリケーションでの便宜を考慮して、(D3DRENDERSTATE_WRAPn ステート値の 1 つを明示的に使用する代わりに) D3DRENDERSTATE_WRAPBIAS 定数を定義し、テクスチャ座標セットのゼロ始点整数値に基づいて、テクスチャ ラッピングを有効にしたり、無効にしたりする。次の例のように、D3DRENDERSTATE_WRAPBIAS 値をテクスチャ座標セットのゼロ始点インデックスに加算して、そのインデックスに対応する D3DRENDERSTATE_WRAPn 値を計算する。

// 変数 dwIndex のインデックスに対応するテクスチャ座標セットを
// 使用するテクスチャに対して、U/V ラッピングを有効にする。
HRESULT hr = lpD3DDevice->SetRenderState(
    dwIndex + D3DRENDERSTATE_WRAPBIAS,
    D3DWRAP_0 | D3DWRAP1);

// dwIndexが 3 の場合、加算の結果の値は、
// D3DRENDERSTATE_WRAP3 (131) に等しくなる。

D3dtypes.h 内の D3DRENDERSTATETYPE の宣言には、DirectX 7.0 インターフェイスでサポートされない従来のレンダリング ステートが含まれている。詳細については、「廃止されたレンダリング ステート」を参照すること。

    D3DRENDERSTATE_TEXTUREHANDLE      = 1,    // テクスチャ ハンドル。
    D3DRENDERSTATE_TEXTUREADDRESS     = 3,    // テクスチャ アドレス。
    D3DRENDERSTATE_WRAPU              = 5,    // u 方向のラップ。
    D3DRENDERSTATE_WRAPV              = 6,    // v 方向のラップ。
    D3DRENDERSTATE_MONOENABLE         = 11,   // モノ レンダリングが有効。
    D3DRENDERSTATE_ROP2               = 12,   // ラスタ化。
    D3DRENDERSTATE_PLANEMASK          = 13,   // 物理的平面マスク。
    D3DRENDERSTATE_TEXTUREMAG         = 17,   // 置き換えられている。
    D3DRENDERSTATE_TEXTUREMIN         = 18,   // 置き換えられている。
    D3DRENDERSTATE_TEXTUREMAPBLEND    = 21,   // マップのブレンディング モード。
    D3DRENDERSTATE_SUBPIXEL           = 31,   // サブピクセル補正が有効。
    D3DRENDERSTATE_SUBPIXELX          = 32,   // x サブピクセル補正が有効。
    D3DRENDERSTATE_STIPPLEENABLE      = 39,   // 点描が有効。
    D3DRENDERSTATE_BORDERCOLOR        = 43,   // 境界色。
    D3DRENDERSTATE_TEXTUREADDRESSU    = 44,   // u テクスチャ アドレッシング モード。
    D3DRENDERSTATE_TEXTUREADDRESSV    = 45,   // v テクスチャ アドレッシング モード。
    D3DRENDERSTATE_MIPMAPLODBIAS      = 46,   // ミップマップ LOD バイアス。
    D3DRENDERSTATE_ANISOTROPY         = 49,   // 最大異方性。
    D3DRENDERSTATE_FLUSHBATCH         = 50,   // DP バッチ処理の明示的フラッシュ (DX5 のみ)。
    D3DRENDERSTATE_TRANSLUCENTSORTINDEPENDENT=51, / /ソート非依存型透明性が有効。
    D3DRENDERSTATE_STIPPLEPATTERN00   = 64,   // 点描パターンの最初の線。
       // ここでは、点描パターンの 01 から 30 までを省略。
    D3DRENDERSTATE_STIPPLEPATTERN31   = 95,   // 点描パターンの最後の線。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::SetRenderState、IDirect3DDevice7::GetRenderState、レンダリング ステート


D3DSHADEMODE

D3DSHADEMODE 列挙型は、D3DRENDERSTATETYPE 列挙型の D3DRENDERSTATE_SHADEMODE レンダリング ステート用に、サポートされるシェーディング モードを指定する。

typedef enum _D3DSHADEMODE {
    D3DSHADE_FLAT         = 1,
    D3DSHADE_GOURAUD      = 2,
    D3DSHADE_PHONG        = 3,
    D3DSHADE_FORCE_DWORD  = 0x7fffffff,
} D3DSHADEMODE;
D3DSHADE_FLAT
フラット シェーディング モード。三角形の最初の頂点の色が、表面の色を決定するために使われる。この色は三角形全体にわたってむらなく適用される。つまり、補間されない。
D3DSHADE_GOURAUD
グーロー シェーディング モード。表面の色は、三角形の 3 つの頂点間で、線形補間により決定される。
D3DSHADE_PHONG
現在はサポートされていない。
D3DSHADE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DRENDERSTATETYPE


D3DSTATEBLOCKTYPE

D3DSTATEBLOCK 列挙型は、IDirect3DDevice7::CreateStateBlock メソッドで使用する、デバイス ステートの論理グループを定義する。

typedef enum _D3DSTATEBLOCKTYPE{
    D3DSBT_ALL           = 1,
    D3DSBT_PIXELSTATE    = 2,
    D3DSBT_VERTEXSTATE   = 3,
    D3DSBT_FORCE_DWORD   = 0xffffffff
} D3DSTATEBLOCKTYPE;
D3DSBT_ALL
すべてのデバイス ステートを取り込む。
D3DSBT_PIXELSTATE
ピクセル関連のデバイス ステートのみ取り込む。
D3DSBT_VERTEXSTATE
頂点関連のデバイス ステートのみ取り込む。
D3DSBT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

D3DSBT_PIXELSTATE および D3DSBT_VERTEXSTATE 値は、異なる論理グループのデバイス ステートをそれぞれ識別するが、ステートによっては両方のグループに共通するものもある。各グループで定義されるステートの詳細については、「事前定義するステート ブロックの作成」を参照すること。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::CreateStateBlock


D3DSTENCILOP

D3DSTENCILOP 列挙型は、D3DRENDERSTATE_STENCILFAIL、D3DRENDERSTATE_STENCILZFAIL、および D3DRENDERSTATE_STENCILPASS レンダリング ステートのステンシル処理を記述する。

typedef enum _D3DSTENCILOP {
    D3DSTENCILOP_KEEP           = 1,
    D3DSTENCILOP_ZERO           = 2,
    D3DSTENCILOP_REPLACE        = 3,
    D3DSTENCILOP_INCRSAT        = 4,
    D3DSTENCILOP_DECRSAT        = 5,
    D3DSTENCILOP_INVERT         = 6,
    D3DSTENCILOP_INCR           = 7,
    D3DSTENCILOP_DECR           = 8,
    D3DSTENCILOP_FORCE_DWORD    = 0x7fffffff
} D3DSTENCILOP;
D3DSTENCILOP_KEEP
ステンシル バッファ内の項目を更新しない。これがデフォルト値である。
D3DSTENCILOP_ZERO
ステンシル バッファ内の項目を 0 に設定する。
D3DSTENCILOP_REPLACE
ステンシル バッファ内の項目を基準値で置き換える。
D3DSTENCILOP_INCRSAT
ステンシル バッファ内の項目の値を、最大値に達するまで増加させる。ステンシル バッファの最大値については、「注意」を参照すること。
D3DSTENCILOP_DECRSAT
ステンシル バッファ内の項目の値を 0 になるまで減少させる。
D3DSTENCILOP_INVERT
ステンシル バッファ内の項目のビットを反転する。
D3DSTENCILOP_INCR
ステンシル バッファ内の項目の値を増加させ、その値が最大値を超えると 0 に戻す。ステンシル バッファの最大値については、「注意」を参照すること。
D3DSTENCILOP_DECR
ステンシル バッファ内の項目の値を減少させ、その値が 0 より小さくなると最大値に戻す。
D3DSTENCILOP_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

ステンシル バッファの項目は 0 から 2n -1 までの範囲の整数値である。n はステンシル バッファのビット深度。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DRENDERSTATETYPE、ステンシル バッファ


D3DTEXTUREADDRESS

D3DTEXTUREADDRESS 列挙型は、D3DTSS_ADDRESS、D3DTSS_ADDRESSU、および D3DTSS_ADDRESSV テクスチャ ステージ ステートでテクスチャ アドレッシング モードを設定する際にサポートされるモードを記述する。

typedef enum _D3DTEXTUREADDRESS {
    D3DTADDRESS_WRAP         = 1,
    D3DTADDRESS_MIRROR       = 2,
    D3DTADDRESS_CLAMP        = 3,
    D3DTADDRESS_BORDER       = 4,
    D3DTADDRESS_FORCE_DWORD  = 0x7fffffff,
} D3DTEXTUREADDRESS;
D3DTADDRESS_WRAP
すべての整数接合点でテクスチャを貼り合わせる。たとえば、u の値が 0 から 3 までの場合、テクスチャは 3 回繰り返され、ミラーリングは行われない。
D3DTADDRESS_MIRROR
すべての整数接合点でテクスチャのフリッピングが起こることを除けば、D3DTADDRESS_WRAP と同様である。たとえば、u の値が 0 から 1 の範囲にある場合、テクスチャの処理は通常どおりに行われるが、1 から 2 の範囲にある場合はフリップ (ミラー化) が行われ、2 から 3 の範囲の場合は再び通常の処理が行われる。以後、このパターンが繰り返される。
D3DTADDRESS_CLAMP
範囲 [0.0, 1.0] の外側のテクスチャ座標が、それぞれ、0.0 と 1.0 のテクスチャ色に設定される。
D3DTADDRESS_BORDER
[0.0, 1.0] の範囲外にあるテクスチャ座標は境界色に設定される。これは D3DRENDERSTATETYPE 列挙型の D3DRENDERSTATE_BORDERCOLOR に対応する新しいレンダリング ステートである。
D3DTADDRESS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

D3DRENDERSTATE_WRAPU および D3DRENDERSTATE_WRAPV レンダリング ステートの使用の詳細については、「テクスチャ」を参照すること。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DRENDERSTATETYPE


D3DTEXTUREMAGFILTER

D3DTEXTUREMAGFILTER 列挙型は、テクスチャ ステージのテクスチャ拡大フィルタ モードを定義する。

typedef enum _D3DTEXTUREMAGFILTER {
    D3DTFG_POINT        = 1,
    D3DTFG_LINEAR       = 2,
    D3DTFG_FLATCUBIC    = 3,
    D3DTFG_GAUSSIANCUBIC= 4,
    D3DTFG_ANISOTROPIC  = 5,
    D3DTFG_FORCE_DWORD  = 0x7fffffff,
} D3DTEXTUREMAGFILTER;
D3DTFG_POINT
点フィルタリング。希望のピクセル値に最も近い座標を持つテクセルを使用する。
D3DTFG_LINEAR
バイリニア補間フィルタリング。希望のピクセルを囲む 2 ｘ 2 領域のテクセルの重み付き平均を使用する。
D3DTFG_FLATCUBIC
現在サポートされていない。使用不可。
D3DTFG_GAUSSIANCUBIC
現在サポートされていない。使用不可。
D3DTFG_ANISOTROPIC
異方性テクスチャ フィルタリング。テクスチャ ポリゴンとスクリーン平面間の角度の相違により起こる歪みを補正する。
D3DTFG_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

テクスチャ ステージの拡大フィルタを設定するには、IDirect3DDevice7::SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MAGFILTER 値を指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DTEXTUREMINFILTER、D3DTEXTUREMIPFILTER、テクスチャ フィルタリング


D3DTEXTUREMINFILTER

D3DTEXTUREMINFILTER 列挙型は、テクスチャ ステージのテクスチャ縮小フィルタ モードを定義する。

typedef enum _D3DTEXTUREMINFILTER {
    D3DTFN_POINT        = 1,
    D3DTFN_LINEAR       = 2,
    D3DTFN_ANISOTROPIC  = 3,
    D3DTFN_FORCE_DWORD  = 0x7fffffff,
} D3DTEXTUREMINFILTER;
D3DTFN_POINT
点フィルタリング。希望のピクセル値に最も近い座標を持つテクセルを使用する。
D3DTFN_LINEAR
バイリニア補間フィルタリング。希望のピクセルを囲む 2 x 2 領域のテクセルの重み付き平均を使用する。
D3DTFN_ANISOTROPIC
異方性テクスチャ フィルタリング。テクスチャ ポリゴンとスクリーン平面間の角度の相違により起こる歪みを補正する。
D3DTFN_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

テクスチャ ステージの拡大フィルタを設定するには、IDirect3DDevice7::SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MINFILTER 値を指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DTEXTUREMAGFILTER、D3DTEXTUREMIPFILTER、テクスチャ フィルタリング


D3DTEXTUREMIPFILTER

D3DTEXTUREMIPFILTER 列挙型は、テクスチャ ステージのテクスチャ ミップマップ フィルタ モードを定義する。

typedef enum _D3DTEXTUREMIPFILTER {
    D3DTFP_NONE         = 1,
    D3DTFP_POINT        = 2,
    D3DTFP_LINEAR       = 3,
    D3DTFP_FORCE_DWORD  = 0x7fffffff,
} D3DTEXTUREMIPFILTER;
D3DTFP_NONE
ミップマップ処理を無効にする。ラスタライザは代わりに拡大フィルタを使用する。
D3DTFP_POINT
最近点ミップマップ フィルタ。ラスタライザは最も近いミップマップ テクスチャのテクセルからの色を使用する。
D3DTFP_LINEAR
トライリニア ミップマップ補間。ラスタライザは、最も近いミップマップ テクスチャ 2 点からのテクセルを使用してピクセル色を線形補間する。
D3DTFP_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

テクスチャ ステージの拡大フィルタを設定するには、IDirect3DDevice7::SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MIPFILTER 値を指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DTEXTUREMAGFILTER、D3DTEXTUREMIPFILTER、テクスチャ フィルタリング


D3DTEXTUREOP

D3DTEXTUREOP 列挙型は、ステージ単位でのテクスチャ ブレンディング操作を定義する。この列挙型のメンバは、D3DTSS_COLOROP または D3DTSS_ALPHAOP 値で IDirect3DDevice7::SetTextureStageState メソッドを呼び出して色処理またはアルファ処理を設定する際に使用される。

typedef enum _D3DTEXTUREOP {
    D3DTOP_DISABLE    = 1,
    D3DTOP_SELECTARG1 = 2,
    D3DTOP_SELECTARG2 = 3,
    D3DTOP_MODULATE   = 4,
    D3DTOP_MODULATE2X = 5,
    D3DTOP_MODULATE4X = 6,
    D3DTOP_ADD        = 7,
    D3DTOP_ADDSIGNED  = 8,
    D3DTOP_ADDSIGNED2X  =  9,
    D3DTOP_SUBTRACT     = 10,
    D3DTOP_ADDSMOOTH    = 11,
    D3DTOP_BLENDDIFFUSEALPHA    = 12,
    D3DTOP_BLENDTEXTUREALPHA    = 13,
    D3DTOP_BLENDFACTORALPHA     = 14,
    D3DTOP_BLENDTEXTUREALPHAPM  = 15,
    D3DTOP_BLENDCURRENTALPHA    = 16,
    D3DTOP_PREMODULATE            = 17,
    D3DTOP_MODULATEALPHA_ADDCOLOR = 18,
    D3DTOP_MODULATECOLOR_ADDALPHA = 19,
    D3DTOP_MODULATEINVALPHA_ADDCOLOR = 20,
    D3DTOP_MODULATEINVCOLOR_ADDALPHA = 21,
    D3DTOP_BUMPENVMAP           = 22,
    D3DTOP_BUMPENVMAPLUMINANCE  = 23,
    D3DTOP_DOTPRODUCT3          = 24,
    D3DTOP_FORCE_DWORD = 0x7fffffff,
} D3DTEXTUREOP;
制御メンバ
D3DTOP_DISABLE
このテクスチャ ステージ、およびより高いインデックスを持つステージからの出力をすべて無効にする。テクスチャ マッピングを無効にするには、これを最初のテクスチャ ステージ (ステージ 0) の色処理として設定する。色処理が有効な場合はアルファ処理を無効にできない。色ブレンディングが有効な場合、アルファ処理を D3DTOP_DISABLE に設定すると、不定の動作が生じる。
D3DTOP_SELECTARG1
このテクスチャ ステージの最初の色、またはアルファ引数を変更せずに出力として使用する。この操作は、D3DTSS_COLOROP テクスチャ ステージ ステートで使用すると色引数に影響を与え、D3DTSS_ALPHAOP で使用した場合にはアルファ引数に影響を与える。

D3DTOP_SELECTARG2
このテクスチャ ステージの 2 番目の色、またはアルファ引数を変更せずに出力として使用する。この操作は、D3DTSS_COLOROP テクスチャ ステージ ステートで使用すると色引数に影響を与え、D3DTSS_ALPHAOP で使用した場合にはアルファ引数に影響を与える。

変調メンバ
D3DTOP_MODULATE
引数コンポーネントを一緒に乗算する。

D3DTOP_MODULATE2X
引数コンポーネントを乗算し、その積を左に 1 ビットだけシフト (2 で乗算するのと同じ) して明るくする。

D3DTOP_MODULATE4X
引数コンポーネントを乗算し、その積を左に 2 ビットだけシフト (4 で乗算するのと同じ) して明るくする。

加算および減算メンバ
D3DTOP_ADD
引数コンポーネントを加算する。

D3DTOP_ADDSIGNED
バイアス値 -0.5 を引数コンポーネントに加算し、値の有効範囲を -0.5 から 0.5 にする。

D3DTOP_ADDSIGNED2X
バイアス値 -0.5 を引数コンポーネントに加算し、その積を左に 1 ビットだけシフトする。

D3DTOP_SUBTRACT
第 1 引数の要素から、対応する第 2 引数の要素を減算する。

D3DTOP_ADDSMOOTH
第 1 および第 2 引数を加算し、次にその積を合計から減算する。

線形アルファ ブレンディング メンバ
D3DTOP_BLENDDIFFUSEALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDTEXTUREALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDFACTORALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDCURRENTALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDTEXTUREALPHAPM
あらかじめ乗算されたアルファを使用するテクスチャ ステージの線形ブレンディングを実行する。

スペキュラ マッピング メンバ
D3DTOP_PREMODULATE
現在のテクスチャ ステージと次のテクスチャ ステージの間で変調を行う。
D3DTOP_MODULATEALPHA_ADDCOLOR
第 1 引数のアルファを使用して第 2 引数のカラーを調整し、その結果を第 1 引数に加算する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATECOLOR_ADDALPHA
引数を調整し、第 1 引数のアルファを加算する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR に類似しているが、第 1 引数のアルファの逆数を使用する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA に類似しているが、第 1 引数の色の逆数を使用する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

バンプ マッピング メンバ
D3DTOP_BUMPENVMAP
次のテクスチャ ステージの環境マップ (輝度なし) による、ピクセル単位のバンプ マッピングを実行する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。
D3DTOP_BUMPENVMAPLUMINANCE
次のテクスチャ ステージの環境マップ (輝度あり) による、ピクセル単位のバンプ マッピングを実行する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。
D3DTOP_DOTPRODUCT3
各引数の要素を (符号付要素として) 変調して積を加算し、得られた合計値をすべての色チャネルに、アルファを含めて複製する。この操作がサポートされるのは色操作とアルファ操作に対してである。

その他のメンバ
D3DTOP_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

上の式では、SRGBA はテクスチャ操作で作成される RGBA 色、Arg1 および Arg2 はテクスチャ引数の完全 RGBA 色である。引数の個々の要素は、下付き文字を付けて表記される。たとえば、引数 1 のアルファ要素は Arg1A として表される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::GetTextureStageState、IDirect3DDevice7::SetTextureStageState、D3DTEXTURESTAGESTATETYPE


D3DTEXTURESTAGESTATETYPE

D3DTEXTURESTAGESTATETYPE 列挙型はテクスチャ ステージ ステートを定義する。この列挙型のメンバは、テクスチャ ステート値を取得および設定するために IDirect3DDevice7::GetTextureStageState および IDirect3DDevice7::SetTextureStageState メソッドで使用する。

typedef enum _D3DTEXTURESTAGESTATETYPE {
    D3DTSS_COLOROP        = 1,
    D3DTSS_COLORARG1      = 2,
    D3DTSS_COLORARG2      = 3,
    D3DTSS_ALPHAOP        = 4,
    D3DTSS_ALPHAARG1      = 5,
    D3DTSS_ALPHAARG2      = 6,
    D3DTSS_BUMPENVMAT00   = 7,
    D3DTSS_BUMPENVMAT01   = 8,
    D3DTSS_BUMPENVMAT10   = 9,
    D3DTSS_BUMPENVMAT11   = 10,
    D3DTSS_TEXCOORDINDEX  = 11,
    D3DTSS_ADDRESS        = 12,
    D3DTSS_ADDRESSU       = 13,
    D3DTSS_ADDRESSV       = 14,
    D3DTSS_BORDERCOLOR    = 15,
    D3DTSS_MAGFILTER      = 16,
    D3DTSS_MINFILTER      = 17,
    D3DTSS_MIPFILTER      = 18,
    D3DTSS_MIPMAPLODBIAS  = 19,
    D3DTSS_MAXMIPLEVEL    = 20,
    D3DTSS_MAXANISOTROPY  = 21,
    D3DTSS_BUMPENVLSCALE  = 22,
    D3DTSS_BUMPENVLOFFSET = 23,
    D3DTSS_TEXTURETRANSFORMFLAGS = 24,
    D3DTSS_FORCE_DWORD   = 0x7fffffff,
} D3DTEXTURESTAGESTATETYPE;
D3DTSS_COLOROP
テクスチャ ステージ ステートはテクスチャ色の混合操作であり、D3DTEXTUREOP 列挙型のメンバにより識別される。最初のテクスチャ ステージ (ステージ 0) のデフォルト値は D3DTOP_MODULATE であり、それ以外のすべてのステージのデフォルト値は D3DTOP_DISABLE である。
D3DTSS_COLORARG1
テクスチャ ステージ ステートは、そのステージに対する最初の色引数であり、テクスチャ引数フラグにより識別される。デフォルト引数は D3DTA_TEXTURE である。
D3DTSS_COLORARG2
テクスチャ ステージ ステートは、そのステージに対する 2 番目の色引数であり、テクスチャ引数フラグにより識別される。デフォルト引数は D3DTA_CURRENT である。
D3DTSS_ALPHAOP
テクスチャ ステージ ステートは、テクスチャ アルファ ブレンディング処理であり、D3DTEXTUREOP 列挙型のメンバによって識別される。最初のテクスチャ ステージ (ステージ 0) のデフォルト値は D3DTOP_SELECTARG1 であり、それ以外のすべてのステージのデフォルト値は D3DTOP_DISABLE である。

DirectX 6.0 では、このステージにおけるデフォルトの動作は、テクスチャ処理として記述されない。その代わり、アルファ ブレンディングの動作は、D3DRENDERSTATE_TEXTUREMAPBLEND レンダリング ステートの動作を D3DTBLEND_MODULATE の値と一致させる。

D3DTSS_ALPHAARG1
テクスチャ ステージ ステートは、そのステージに対する最初のアルファ引数であり、テクスチャ引数フラグにより識別される。デフォルトの引数は D3DTA_TEXTURE である。ステージにテクスチャが設定されていない場合は D3DTA_DIFFUSE がデフォルトの引数となる。
D3DTSS_ALPHAARG2
テクスチャステージ ステートは、ステージの 2 番目のアルファ引数であり、テクスチャ引数フラグにより識別される。デフォルト引数は D3DTA_CURRENT である。
D3DTSS_BUMPENVMAT00
テクスチャ ステージ ステートは、バンプ マッピング行列の [0][0] 係数に対する D3DVALUE である。デフォルト値は 0 である。
D3DTSS_BUMPENVMAT01
テクスチャ ステージ ステートは、バンプ マッピング行列の [0][1] 係数に対する D3DVALUE である。デフォルト値は 0 である。
D3DTSS_BUMPENVMAT10
テクスチャ ステージ ステートは、バンプ マッピング行列の [1][0] 係数に対する D3DVALUE である。デフォルト値は 0 である。
D3DTSS_BUMPENVMAT11
テクスチャ ステージ ステートは、バンプ マッピング行列の [1][1] 係数に対する D3DVALUE である。デフォルト値は 0 である。
D3DTSS_TEXCOORDINDEX
このテクスチャ ステージで使用するために設定されたテクスチャ座標インデックス。デフォルトのインデックスは 0。このステートには、テクスチャ ステージで使用する、各頂点の座標セットのゼロベース インデックスを設定する (頂点 1 個に対して最大 8 組までのテクスチャ座標を設定できる)。頂点が、指定されたインデックスのテクスチャ座標セットを含んでいない場合は、u および v 座標 (0,0) がデフォルトで使用される。

また、アプリケーションでは、(設定されるインデックスとの論理和として) 以下のフラグのいずれかを設定して、テクスチャ トランスフォーム用の入力テクスチャ座標を自動的に生成するよう Direct3D に要求できる。ゼロに分解する D3DTSS_TCI_PASSTHRU を除いて、設定されるインデックスと以下のフラグのいずれかを使用すると、テクスチャ ラッピング モードの決定にインデックスが厳密に使用される。このフラグは環境マッピングを行う場合には特に有効である。

D3DTSS_TCI_PASSTHRU
頂点フォーマット内の指定されたテクスチャ座標を使用する。この値はゼロに分解する。
D3DTSS_TCI_CAMERASPACENORMAL
このステージのテクスチャ トランスフォームの入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点法線を使用する。
D3DTSS_TCI_CAMERASPACEPOSITION
このステージのテクスチャ トランスフォームの入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点位置座標を使用する。
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
このステージのテクスチャ トランスフォームの入力テクスチャ座標として、カメラ空間にトランスフォームされた反射ベクトルを使用する。反射ベクトルは入力頂点位置座標と法線ベクトルから計算される。
D3DTSS_ADDRESS
D3DTEXTUREADDRESS 列挙型のメンバ。u 座標と v 座標の両方で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_ADDRESSU
D3DTEXTUREADDRESS 列挙型のメンバ。u 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_ADDRESSV
D3DTEXTUREADDRESS 列挙型のメンバ。v 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_BORDERCOLOR
[0.0,1.0] の範囲の外にあるテクスチャ座標のラスタ化を実行するときに使用する色を記述する D3DCOLOR 値。デフォルト色は 0x00000000 である。
D3DTSS_MAGFILTER
テクスチャをプリミティブにレンダリングするときに使用するテクスチャ拡大フィルタを示す D3DTEXTUREMAGFILTER 列挙型のメンバ。デフォルト値は D3DTFG_POINT である。
D3DTSS_MINFILTER
D3DTEXTUREMINFILTER 列挙型のメンバで、テクスチャをプリミティブ上へレンダリングするときに使用するテクスチャ拡大フィルタを示す。デフォルト値は D3DTFN_POINT である。
D3DTSS_MIPFILTER
テクスチャをプリミティブにレンダリングするときに使用するテクスチャ拡大フィルタを示す D3DTEXTUREMIPFILTER 列挙型のメンバ。デフォルト値は D3DTFP_NONE である。
D3DTSS_MIPMAPLODBIAS
ミップマップ詳細バイアスのレベル。これを利用すると、テクスチャに質量感を与えたり、ぼやけた感じを与えることができる。デフォルトは 0。このステージの値は浮動小数点値である。IDirect3DDevice7::SetTextureStageState および IDirect3DDevice7::GetTextureStageState は DWORD 値を使用するため、以下のコード例で示すように、値を格納した変数をキャストしなければならない。
lpd3dDevice->SetTextureStageState( D3DTSS_MIPMAPLODBIAS, *((LPDWORD) (&fBias)) );
D3DTSS_MAXMIPLEVEL
アプリケーションで許容する最大ミップマップ詳細レベル ミップマップ チェーンの先頭を始点とするインデックスとして表現される (低い値の方が、ミップマップ チェーン内の高い詳細レベルを表す)。ゼロがデフォルト値で、全レベルが使用可能であることを示す。ゼロ以外の値は、指定されたインデックスより高い詳細レベルのミップマップを表示しないことを示す。
D3DTSS_MAXANISOTROPY
異方性レベルの最大値。デフォルト値は 1 である。
D3DTSS_BUMPENVLSCALE
バンプ マップ輝度に使用する D3DVALUE スケール。デフォルト値は 0 である。
D3DTSS_BUMPENVLOFFSET
バンプマップ輝度の D3DVALUE オフセット。デフォルト値は 0 である。
D3DTSS_TEXTURETRANSFORMFLAGS
テクスチャ ステージのテクスチャ座標のトランスフォームを制御する D3DTEXTURETRANSFORMFLAGS 列挙型のメンバ。デフォルトは D3DTTFF_DISABLE である。
D3DTSS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、および D3DTSS_BUMPENVMAT11 バンプ マッピング行列係数の有効範囲は、-8.0 以上 8.0 未満である。この範囲は、数学的には [-8.0,8.0) と表記する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DTEXTURETRANSFORMFLAGS

D3DTEXTURETRANSFORMFLAGS 列挙型は、D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートで使用される値を定義する。

typedef enum _D3DTEXTURETRANSFORMFLAGS {
    D3DTTFF_DISABLE         = 0,
    D3DTTFF_COUNT1          = 1,
    D3DTTFF_COUNT2          = 2,
    D3DTTFF_COUNT3          = 3,
    D3DTTFF_COUNT4          = 4,
    D3DTTFF_PROJECTED       = 256,
    D3DTTFF_FORCE_DWORD     = 0x7fffffff,
} D3DTEXTURETRANSFORMFLAGS;
D3DTTFF_DISABLE
テクスチャ座標はラスタライザに直接渡される。
D3DTTFF_COUNT1
ラスタライザは 1D テクスチャ座標を想定する。
D3DTTFF_COUNT2
ラスタライザは 2D テクスチャ座標を想定する。
D3DTTFF_COUNT3
ラスタライザは 3D テクスチャ座標を想定する。
D3DTTFF_COUNT4
ラスタライザは 4D テクスチャ座標を想定する。
D3DTTFF_PROJECTED
テクスチャ座標は、ラスタライザに渡される前に最後の要素ですべて分割される。たとえば、このフラグが D3DTTFF_COUNT3 と共に指定されている場合、1 番目および 2 番目のテクスチャ座標はラスタライザに渡される前に 3 番目の座標で分割される。
D3DTTFF_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン :DirectX 7.0 が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DTSS_TEXTURETRANSFORMFLAGS、テクスチャ座標トランスフォーム


D3DTRANSFORMSTATETYPE

D3DTRANSFORMSTATETYPE 列挙型は、IDirect3DDevice7::GetTransform および IDirect3DDevice7::SetTransform メソッドで使用されるトランスフォーム ステート値を記述する。

typedef enum _D3DTRANSFORMSTATETYPE {
    D3DTRANSFORMSTATE_WORLD        = 1,
    D3DTRANSFORMSTATE_VIEW         = 2,
    D3DTRANSFORMSTATE_PROJECTION   = 3,
    D3DTRANSFORMSTATE_WORLD1       = 4,
    D3DTRANSFORMSTATE_WORLD2       = 5,
    D3DTRANSFORMSTATE_WORLD3       = 6,
    D3DTRANSFORMSTATE_TEXTURE0     = 16,
    D3DTRANSFORMSTATE_TEXTURE1     = 17,
    D3DTRANSFORMSTATE_TEXTURE2     = 18,
    D3DTRANSFORMSTATE_TEXTURE3     = 19,
    D3DTRANSFORMSTATE_TEXTURE4     = 20,
    D3DTRANSFORMSTATE_TEXTURE5     = 21,
    D3DTRANSFORMSTATE_TEXTURE6     = 22,
    D3DTRANSFORMSTATE_TEXTURE7     = 23,
    D3DTRANSFORMSTATE_FORCE_DWORD  = 0x7fffffff,
} D3DTRANSFORMSTATETYPE;
D3DTRANSFORMSTATE_WORLD
ワールド トランスフォーム行列として設定されるトランスフォーム行列を識別する。デフォルト値は NULL である (単位行列)。
D3DTRANSFORMSTATE_WORLD1
頂点フォーマットで指定された対応する行列およびブレンディング (ベータ) 加重値を用いる頂点ブレンディングに使用される、以降のトランスフォーム行列を識別する。
D3DTRANSFORMSTATE_WORLD2
頂点フォーマットで指定された対応する行列およびブレンディング (ベータ) 加重値を用いる頂点ブレンディングに使用される、以降のトランスフォーム行列を識別する。
D3DTRANSFORMSTATE_WORLD3
頂点フォーマットで指定された対応する行列およびブレンディング (ベータ) 加重値を用いる頂点ブレンディングに使用される、以降のトランスフォーム行列を識別する。
D3DTRANSFORMSTATE_VIEW
ビュー トランスフォーム行列として設定されるトランスフォーム行列を識別する。デフォルト値は NULL である (単位行列)。
D3DTRANSFORMSTATE_PROJECTION
射影トランスフォーム行列として設定されるトランスフォーム行列を識別する。デフォルト値は NULL である (単位行列)。
D3DTRANSFORMSTATE_TEXTURE0 through D3DTRANSFORMSTATE_TEXTURE7
指定されたテクスチャ ステージに設定されるトランスフォーム行列を識別する。
D3DTRANSFORMSTATE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::GetTransform、IDirect3DDevice7::SetTransform


D3DVERTEXBLENDFLAGS

D3DVERTEXBLENDFLAGS 列挙型は、複数の行列による頂点ブレンディングの際に適用される数値または行列を制御するためのフラグを定義する。この型のメンバは、D3DRENDERSTATE_VERTEXBLEND レンダリング ステートで使用される。

typedef enum _D3DVERTEXBLENDFLAGS {
    D3DVBLEND_DISABLE  = 0,
    D3DVBLEND_1WEIGHT  = 1,
    D3DVBLEND_2WEIGHTS = 2,
    D3DVBLEND_3WEIGHTS = 3,
} D3DVERTEXBLENDFLAGS;

メンバ

D3DVBLEND_DISABLE
頂点ブレンディングを無効にする。D3DTRANSFORMSTATE_WORLD トランスフォーム ステートによって指定されるワールド配列のみ適用する。
D3DVBLEND_1WEIGHT
D3DTRANSFORMSTATE_WORLD および D3DTRANSFORMSTATE_WORLD1 トランスフォーム ステートによって設定される 2 つの行列間での頂点ブレンディングを有効にする。
D3DVBLEND_2WEIGHTS
D3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_WORLD1、および D3DTRANSFORMSTATE_WORLD2 トランスフォーム ステートによって設定される 3 つの行列間で頂点ブレンディングを有効にする。
D3DVBLEND_3WEIGHTS
D3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_WORLD1、D3DTRANSFORMSTATE_WORLD2、および D3DTRANSFORMSTATE_WORLD3 トランスフォーム ステートによって設定される 4 つの行列間で頂点ブレンディングを有効にする。

注意

ジオメトリ ブレンディング (複数の行列による頂点ブレンディング) では、各頂点のブレンディング (ベータ) 加重値を持つ頂点フォーマットを使用しなければならない。

参照

D3DRENDERSTATETYPE、D3DTRANSFORMSTATETYPE、IDirect3DDevice7::SetTransform、ジオメトリ ブレンディング


D3DVERTEXTYPE

D3DVERTEXTYPE 列挙型は、従来の IDirect3DDevice3、IDirect3DDevice2、および IDirect3DDevice インターフェイスがサポートしていた頂点タイプを一覧する。アプリケーションで IDirect3DDevice7 などの IDirect3DDevice3 より新しいインターフェイスを使用する場合、柔軟な頂点フォーマット フラグが D3DVERTEXTYPE 列挙型に代わって使用される。

typedef enum _D3DVERTEXTYPE {
    D3DVT_VERTEX       = 1,
    D3DVT_LVERTEX      = 2,
    D3DVT_TLVERTEX     = 3
    D3DVT_FORCE_DWORD  = 0x7fffffff,
} D3DVERTEXTYPE;
D3DVT_VERTEX
配列内の頂点はすべて D3DVERTEX 型である。これを設定すると、プリミティブにはレンダリングの際にトランスフォーム、ライティング、およびクリッピングが適用される。
D3DVT_LVERTEX
配列内の頂点はすべて D3DLVERTEX 型である。このオプションを使用した場合、プリミティブにはレンダリングの際にトランスフォームが適用される。
D3DVT_TLVERTEX
配列内の頂点はすべて D3DTLVERTEX 型である。ラスタ化はこのデータにのみ適用される。
D3DVT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

頂点フォーマット


D3DZBUFFERTYPE

D3DZBUFFERTYPE 列挙型は、D3DRENDERSTATE_ZENABLE レンダリング ステートで使用する深度バッファ形式を記述する。

typedef enum _D3DZBUFFERTYPE {
    D3DZB_FALSE        = 0,
    D3DZB_TRUE         = 1,
    D3DZB_USEW         = 2,
    D3DZB_FORCE_DWORD  = 0x7fffffff,
} D3DZBUFFERTYPE;
D3DZB_FALSE
深度バッファの使用を無効にする。
D3DZB_TRUE
z バッファの使用を可能にする。
D3DZB_USEW
w バッファの使用を可能にする。
D3DZB_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

D3DZB_FALSE と D3DZB_TRUE 値は、以前 D3DRENDERSTATE_ZENABLE で使用されていた TRUE、FALSE マクロと入れ替え可能である。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 6.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

IDirect3DDevice7::SetRenderState、深度バッファ


廃止された列挙型

以下の列挙型は廃止されている。これらの列挙型の詳細については、旧リリースの DirectX のドキュメントを参照すること。

  • D3DOPCODE
  • D3DLIGHTSTATETYPE
  • D3DTEXTUREBLEND
  • D3DTEXTUREFILTER


廃止されたレンダリング ステート

d3dtypes.h に宣言される D3DRENDERSTATETYPE 列挙型には多数のレンダリング ステートが含まれているが、その多くは DirectX 7.0 リリースでは廃止されている。このようなレンダリング ステートは、DirectX 7.0 インターフェイスではサポートされず、既存のアプリケーションとの後方互換性を維持するためにのみ宣言されている。これらのレンダリング ステートを IDirect3DDevice7 インターフェイスで使用しようとすると失敗し、DDERR_INVALIDPARAMS が返される。従来のインターフェイスで使用されていたレンダリング ステートの使用については、従来の Direct SDK で説明されている。

  • D3DRENDERSTATE_ANISOTROPY
  • D3DRENDERSTATE_BORDERCOLOR
  • D3DRENDERSTATE_FLUSHBATCH
  • D3DRENDERSTATE_MIPMAPLODBIAS
  • D3DRENDERSTATE_MONOENABLE
  • D3DRENDERSTATE_PLANEMASK
  • D3DRENDERSTATE_ROP2
  • D3DRENDERSTATE_STIPPLEENABLE
  • D3DRENDERSTATE_STIPPLEPATTERN00 から D3DRENDERSTATE_STIPPLEPATTERN31
  • D3DRENDERSTATE_SUBPIXEL
  • D3DRENDERSTATE_SUBPIXELX
  • D3DRENDERSTATE_TEXTUREADDRESS
  • D3DRENDERSTATE_TEXTUREADDRESSU
  • D3DRENDERSTATE_TEXTUREADDRESSV
  • D3DRENDERSTATE_TEXTUREHANDLE
  • D3DRENDERSTATE_TEXTUREMAG
  • D3DRENDERSTATE_TEXTUREMAPBLEND
  • D3DRENDERSTATE_TEXTUREMIN
  • D3DRENDERSTATE_TRANSLUCENTSORTINDEPENDENT
  • D3DRENDERSTATE_WRAPU
  • D3DRENDERSTATE_WRAPV


その他の型

ここでは、構造体でも列挙型でもない、以下の Direct3D 直接モードの型を説明する。

  • D3DCOLOR
  • D3DFIXED
  • D3DVALUE


D3DCOLOR

D3DCOLOR 型は、基本的な Direct3D の色型である。

typedef DWORD D3DCOLOR, D3DCOLOR, *LPD3DCOLOR;

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。

参照

D3DRGB、D3DRGBA


D3DFIXED

D3DFIXED 型は 16:16 固定小数点値を表現するために使われる。

typedef LONG D3DFIXED;

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 5.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


D3DVALUE

D3DVALUE 型は、基本的な Direct3D の分数データ型である。

typedef float D3DVALUE, *LPD3DVALUE;

動作環境

Windows NT/2000 :Windows NT 4.0 SP3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 2.0 以降が必要。
ヘッダー : d3dtypes.h で宣言。


柔軟な頂点フォーマット フラグ

Direct3D 直接モードはフラグの値を使って、DrawPrimitive 準拠のレンダリングで使用する頂点フォーマットを表現する。d3dtypes.h ヘッダー ファイルは、以下に示すように、頂点フォーマットを明示的に記述するフラグを宣言する。また、これらのフラグの一般的な組み合わせとしての機能を持つヘルパー マクロを提供する。詳細については、「頂点フォーマットについて」を参照すること。

柔軟な頂点フォーマット (FVF) フラグ
D3DFVF_DIFFUSE
頂点フォーマットがディフーズ色成分を含む。
D3DFVF_NORMAL
頂点フォーマットが頂点法線ベクトルを含む。このフラグを、D3DFVF_XYZRHW と共に使用することはできない。
D3DFVF_SPECULAR
頂点フォーマットがスペキュラ色成分を含む。
D3DFVF_XYZ
頂点フォーマットが未トランスフォーム頂点の位置座標を含む。このフラグを、D3DFVF_XYZRHW と共に使用することはできない。このフラグを使用する場合は、同時に頂点法線と頂点色成分 (D3DFVF_DIFFUSE または D3DFVF_SPECULAR) を指定するか、または少なくとも 1 セットのテクスチャ座標 (D3DFVF_TEX1 から D3DFVF_TEX8) を含める必要がある。
D3DFVF_XYZRHW
頂点フォーマットが、トランスフォームされた頂点の位置座標を含む。このフラグを D3DFVF_XYZ または D3DFVF_NORMAL フラグと同時に使用することはできない。このフラグを使用する場合は、同時に頂点色成分 (D3DFVF_DIFFUSE または D3DFVF_SPECULAR) を指定するか、または少なくとも 1 セットのテクスチャ座標 (D3DFVF_TEX1 から D3DFVF_TEX8) を含める必要がある。
D3DFVF_XYZB1 から D3DFVF_XYZB5
頂点フォーマットは、位置座標データ、および複数の行列による頂点ブレンディング処理用の加重 (ベータ) 値の対応数を含む。現在、Direct3D では最大 3 つの加重値 (および 4 つのブレンディング行列) でブレンディングが可能である。
テクスチャ関連 FVF フラグ
D3DFVF_TEX0 から D3DFVF_TEX8
この頂点に対応するテクスチャ座標セットの番号。これらのフラグに対応する数字は連続番号になっていない。
D3DFVF_TEXTUREFORMAT1 から D3DFVF_TEXTUREFORMAT4
テクスチャ座標セットを定義する値の番号。D3DFVF_TEXTUREFORMAT1 は 1 次元座標を示し、D3DFVF_TEXTUREFORMAT2 は 2 次元座標を示し、という順に以下続く。このフラグが単独で使用されることはまれで、D3DFVF_TEXCOORDSIZEn マクロと共に使用される。
ヘルパー マクロ
D3DFVF_LVERTEX
頂点フォーマットは D3DLVERTEX 頂点タイプに対応する。
D3DFVF_TLVERTEX
頂点フォーマットは D3DTLVERTEX 頂点タイプに対応する。
D3DFVF_VERTEX
頂点フォーマットは D3DVERTEX 頂点タイプに対応する。
マスク値
D3DFVF_POSITION_MASK
位置座標ビットを抽出するマスク。
D3DFVF_RESERVED0 and D3DFVF_RESERVED2
柔軟な頂点フォーマットの予約ビットを抽出するためのマスク値。使用不可。
D3DFVF_RESERVED1,
このビットは、システムが D3DLVERTEX 処理をエミュレートすることを示すために予約されている。このフラグを使用する場合は、D3DFVF_XYZ、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX1 フラグも同時に使用しなければならない。これは、D3DFVF_LVERTEX ヘルパー マクロを使うのと実質的に同じである。
D3DFVF_TEXCOUNT_MASK
テクスチャ フラグ ビットを抽出するためのマスク値。
その他
D3DFVF_TEXCOUNT_SHIFT
頂点のテクスチャ座標数を識別する整数値を何ビット分シフトするかを示す数。この値は、たとえば次のように使用する。
    DWORD dwNumTextures = 1;  // 頂点には座標セットが 1 つだけある。

    // FVF の組み合わせを作るときに、値をシフトさせて使用する。
    dwFVF = dwNumTextures<<D3DFVF_TEXCOUNT_SHIFT;

    /*
     * シフト後の値を使い、ここで FVF の組み合わせを作成する。
     */

よく使われるフラグの組み合わせ例を次に示す。

    // ライティングされ、テクスチャの付かない、軽い未トランスフォーム頂点。
    // グーロー シェーディングあり。
    dwFVF = ( D3DFVF_XYZ | D3DFVF_DIFFUSE );

    // ライティングなし、テクスチャなし、グーロー シェーディングあり。
    // 頂点ごとにマテリアル ディフーズ色が指定されている未トランスフォーム頂点。
    dwFVF = ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE );

    // ライティング マップに準拠した未トランスフォーム済みライティング済みの頂点。
    dwFVF = ( D3DFVF_XYZ | D3DFVF_TEX2 );

    // ライティング マップに準拠したライティングを使用するトランスフォーム済み頂点。
    // rhw と共有。
    dwFVF = ( D3DFVF_XYZRHW | D3DFVF_TEX2 );

    // 未ライティングで、2 つのテクスチャ座標を備えた、色付きの
    // 頂点。
    dwFVF = ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE |
              D3DFVF_SPECULAR | D3DFVF_TEX2 );

参照

頂点フォーマットについて、ジオメトリ ブレンディング


テクスチャ引数フラグ

デバイスに対応するそれぞれのテクスチャ ステージは 2 つのテクスチャ引数を持つことができ、これらの引数はテクスチャの色とアルファ チャネルに影響を与える。テクスチャ引数を取得または設定するには、IDirect3DDevice7::SetTextureStageState または IDirect3DDevice7::GetTextureStageState メソッドを呼び出し、D3DTEXTURESTAGESTATETYPE 列挙型の D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHAARG1、または D3DTSS_ALPHAARG2 メンバを指定する。

次に示すフラグ (引数と修正子にまとめられている) をテクスチャ ステージの色とアルファ引数と共に使用することができる。引数フラグと修正子を組み合わせることはできるが、2 つの引数フラグを組み合わせることはできない。

引数フラグ
D3DTA_CURRENT
テクスチャ引数は前のブレンディング ステージの結果である。最初のテクスチャ ステージ (ステージ 0) の場合、この引数は D3DTA_DIFFUSE と同等である。前のブレンディング ステージがバンプマップ テクスチャ (D3DTOP_BUMPENVMAP 処理) を使用している場合、バンプマップ テクスチャの前のステージからテクスチャが選択される (s が現在のテクスチャ ステージを表し、s – 1 にバンプマップ テクスチャがある場合、この引数はテクスチャ ステージ s – 2 からの結果出力になる)。
D3DTA_DIFFUSE
テクスチャ引数は、グーロー シェーディング処理中に頂点成分から補間して得られたディフーズ色である。頂点がディフーズ色を含まない場合のデフォルト色は 0xFFFFFFFF である。
D3DTA_SELECTMASK
すべての引数に対応するマスク値。テクスチャ引数の設定には使用しない。
D3DTA_TEXTURE
テクスチャ引数は、このテクスチャ ステージのテクスチャ色である。これが有効なのは、ステージの最初の色とアルファ引数に対してのみである (D3DTEXTURESTAGESTATETYPE の 3DTSS_COLORARG1 メンバと 3DTSS_ALPHAARG1 メンバ)。
D3DTA_TFACTOR
テクスチャ引数は、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートを使用して前回 IDirect3DDevice7::SetRenderState を呼び出したときのテクスチャ係数セットである。
D3DTA_SPECULAR
テクスチャ引数は、グーロー シェーディング処理中に頂点成分から補間されたスペキュラ色である。頂点がスペキュラ色を含んでいない場合、デフォルト色は 0xFFFFFFFF である。
修正子フラグ
D3DTA_ALPHAREPLICATE
操作が完了する前に、アルファ情報をすべての色チャネルにコピーする。
D3DTA_COMPLEMENT
引数の逆数を取る。たとえば、引数の結果が変数 x ならば、その値は 1.0 - x になる。


戻り値

エラーは、負の値で表されるので、組み合わせることができない。この表は、すべての Direct3D 直接モード メソッドが返すことのできる値をまとめたものである。各メソッドが返す値の一覧については、各メソッドについての説明を参照すること。

D3D_OK
エラーは発生していない。
D3DERR_BADMAJORVERSION
要求したサービスはこの主要バージョンの DirectX では使用できない (主要バージョンとは DirectX 6.0 などの主要リリースのことである)。
D3DERR_BADMINORVERSION
要求したサービスはこの主要バージョンの DirectX で使用可能であるが、このマイナー バージョンでは使用できない。Microsoft から最新のコンポーネント ランタイムを入手すること (マイナー バージョンとは Direct 6.1 などのセカンダリ リリースのことである)。
D3DERR_COLORKEYATTACHED
アプリケーションが透過用カラー キーを使用するサーフェスでテクスチャを作成しようとした。
D3DERR_CONFLICTINGTEXTUREFILTER
現在のテクスチャ フィルタは一緒に使用できない。
D3DERR_CONFLICTINGTEXTUREPALETTE
現在のテクスチャは同時に使用できない。一般にマルチテクスチャ デバイスにおいて、同時に有効にされたパレット化テクスチャで同じパレットを共有する必要がある場合に発生する。
D3DERR_CONFLICTINGRENDERSTATE
現在設定されているレンダリング ステートは一緒に使用できない。
D3DERR_DEVICEAGGREGATED
IDirect3DDevice7::SetRenderTarget メソッドが、レンダリング ターゲット サーフェスから取得されたデバイスで呼び出された。
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_INBEGIN
シーンのレンダリング中であるため、要求された処理が実行できない。シーンが完了してから IDirect3DDevice7::EndScene メソッドを呼び出した後、再度試してみる。
D3DERR_INBEGINSTATEBLOCK
ステート ブロックの記録中であるため、処理が実行できない。IDirect3DDevice7::EndStateBlock メソッドを呼び出してレコーディングを完了した後、再度試してみる。
D3DERR_INITFAILED
新しいデバイスを初期化できなかったため、レンダリング デバイスを作成できなかった。
D3DERR_INVALID_DEVICE
要求されたデバイスの種類が有効でない。
D3DERR_INVALIDCURRENTVIEWPORT
現在選択されているビューポートが有効でない。
D3DERR_INVALIDMATRIX
現在設定されているワールド行列、ビュー行列、または射影行列の組み合わせが無効であるため (行列を組み合わせた結果、行列式が 0 になる)、要求された処理を実行できなかった。
D3DERR_INVALIDPALETTE
サーフェスに関連付けられているパレットが無効である。
D3DERR_INVALIDPRIMITIVETYPE
アプリケーションで指定したプリミティブの種類が無効である。
D3DERR_INVALIDRAMPTEXTURE
ランプ モードが使われ、現在のマテリアルのテクスチャ ハンドルは、レンダリング ステートとして設定された現在のテクスチャ ハンドルに適合しない。
D3DERR_INVALIDSTATEBLOCK
ステート ブロック ハンドルが無効である。
D3DERR_INVALIDVERTEXFORMAT
アプリケーションで指定した柔軟な頂点フォーマット フラグの組み合わせが有効でない。
D3DERR_INVALIDVERTEXTYPE
アプリケーションで指定した頂点の種類が無効である。
D3DERR_LIGHT_SET_FAILED
ライティング オブジェクへのライティング パラメータの設定が失敗した。
D3DERR_LIGHTHASVIEWPORT
ライティング オブジェクトが別のビューポートに関連付けられているため、要求された処理が失敗した。
D3DERR_LIGHTNOTINTHISVIEWPORT
ライティング オブジェクトがこのビューポートに関連付けられていないため、要求された処理が失敗した。
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_NOCURRENTVIEWPORT
ビューポート パラメータが設定されていないため取得できなかった。
D3DERR_NOTINBEGIN
シーンのレンダリングが開始していないため、要求されたレンダリング処理を完了できなかった。IDirect3DDevice7::BeginScene を呼び出してレンダリングを開始し、再度試してみる。
D3DERR_NOTINBEGINSTATEBLOCK
要求された処理はステート ブロックの記録中にのみ有効であるため、その処理を完了できなかった。IDirect3DDevice7::BeginStateBlock メソッドを呼び出して再度試してみる。
D3DERR_NOVIEWPORTS
現在デバイスにはビューポートが関連付けられていないため、要求された処理が失敗した。
D3DERR_SCENE_BEGIN_FAILED
シーンのレンダリングが開始できなかった。
D3DERR_SCENE_END_FAILED
シーンのレンダリングを完了できなかった。
D3DERR_SCENE_IN_SCENE
IDirect3DDevice7::EndScene メソッドの呼び出しによって前回のシーンが完了していないため、シーンのレンダリングが開始できなかった。
D3DERR_SCENE_NOT_IN_SCENE
前の IDirect3DDevice7::BeginScene メソッドの呼び出しによってシーンが開始していないため、シーンのレンダリングを完了できなかった。
D3DERR_SETVIEWPORTDATA_FAILED
ビューポート パラメータを設定できなかった。
D3DERR_STENCILBUFFER_NOTPRESENT
レンダリング ターゲット サーフェスにステンシル バッファがアタッチしていないため、要求されたステンシル バッファ処理を完了できなかった。
D3DERR_SURFACENOTINVIDMEM
レンダリング ターゲット サーフェスがビデオ メモリ内に見つからないため、デバイスを作成できなかった (ハードウェア アクセラレーション デバイスには、ビデオ メモリ内のレンダリング ターゲット サーフェスが必要である)。
D3DERR_TEXTURE_BADSIZE
現在のテクスチャの大きさが無効である。2 の累乗の大きさを持つテクスチャが必要なデバイスで、それ以外の大きさのテクスチャを使用しようとした場合に発生する。
D3DERR_TEXTURE_CREATE_FAILED
ドライバからテクスチャのテクスチャ ハンドルを取得できなかった。
D3DERR_TEXTURE_DESTROY_FAILED
デバイスがテクスチャ メモリの割り当てを解除できなかった。
D3DERR_TEXTURE_GETSURF_FAILED
テクスチャ作成に使用する DirectDraw サーフェスを取得できなかった。
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
テクスチャ サーフェスをロック解除できなかった。
D3DERR_TOOMANYOPERATIONS
アプリケーションで、デバイス サポート以上のテクスチャフィルタリング処理を要求している。
D3DERR_TOOMANYPRIMITIVES
デバイスは、1 回だけの受け渡しでは指定された個数のプリミティブをレンダリングできない。
D3DERR_UNSUPPORTEDALPHAARG
アルファ チャネルに指定されたテクスチャブレンディング引数のうち、デバイスでサポートしていない引数がある。
D3DERR_UNSUPPORTEDALPHAOPERATION
アルファ チャネルに指定されたテクスチャブレンディング処理のうち、デバイスでサポートしていない処理がある。
D3DERR_UNSUPPORTEDCOLORARG
カラー値に指定されたテクスチャブレンディング引数のうち、デバイスでサポートしていない引数がある。
D3DERR_UNSUPPORTEDCOLOROPERATION
カラー値に指定されたテクスチャブレンディング処理のうち、デバイスでサポートしていない処理がある。
D3DERR_UNSUPPORTEDFACTORVALUE
指定されたテクスチャ係数値がデバイスでサポートされていない。
D3DERR_UNSUPPORTEDTEXTUREFILTER
指定されたテクスチャ フィルタがデバイスでサポートされていない。
D3DERR_VBUF_CREATE_FAILED
頂点バッファを作成できなかった。頂点バッファを割り当てるのに十分なメモリがない場合に発生する。
D3DERR_VERTEXBUFFERLOCKED
頂点バッファがロックされているため、要求された処理を完了できなかった。
D3DERR_VERTEXBUFFEROPTIMIZED
頂点バッファが最適化されているため、要求された処理を完了できなかった (最適化された頂点バッファの内容は、ドライバ固有でプライベートと見なされる)。
D3DERR_VERTEXBUFFERUNLOCKFAILED
頂点バッファ メモリがオーバランしたため、頂点バッファをロック解除できなかった。アプリケーションで頂点バッファのサイズ以上の書き込みを実行しないように注意すること。
D3DERR_VIEWPORTDATANOTSET
ビューポート パラメータが未設定であるため、要求された処理を完了できなかった。IDirect3DDevice7::SetViewport メソッドを呼び出してビューポート パラメータを設定し、再度試してみる。
D3DERR_VIEWPORTHASNODEVICE
この値は IDirect3DDevice3 およびそれ以前のインターフェイスでのみ使用される。IDirect3DDevice7 インターフェイスでは、このエラー値は使用されない。

ビューポートがデバイスに関連付けられていないため、要求された処理を完了できなかった。IDirect3DDevice3::AddViewport メソッドを呼び出してビューポートをレンダリング デバイスに関連付けて、再度試してみる。

D3DERR_WRONGTEXTUREFORMAT
テクスチャ サーフェスのピクセル フォーマットが有効でない。
D3DERR_ZBUFF_NEEDS_SYSTEMMEMORY
指定されたデバイスではシステムメモリの深度バッファ サーフェスが必要なため、要求された処理を完了できなかった (ソフトウェア レンダリング デバイスでは、システムメモリの深度バッファが必要である)。
D3DERR_ZBUFF_NEEDS_VIDEOMEMORY
指定されたデバイスではビデオ メモリの深度バッファ サーフェスが必要なため、要求された処理を完了できなかった (ハードウェア アクセラレーション デバイスでは、ビデオメモリの深度バッファが必要である)。
D3DERR_ZBUFFER_NOTPRESENT
レンダリング ターゲット サーフェスにアタッチされた深度バッファがないため、要求された処理を完了できなかった。


Direct3D 直接モード Visual Basic リファレンス

ここでは、Direct3D® 直接モードが提供する API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • クラス
  • 型
  • 列挙
  • 柔軟な頂点フォーマット フラグ
  • テクスチャ引数フラグ
  • エラー コード


クラス

ここでは、Direct3D 直接モードが提供するクラスのリファレンスを記述する。以下のクラスについて説明する。

  • Direct3D7
  • Direct3DDevice7
  • Direct3DEnumDevices
  • Direct3DEnumPixelFormats
  • Direct3DVertexBuffer7


Direct3D7

アプリケーションは、Direct3D7 クラスのメソッドを使って、Direct3D オブジェクトを作成し、オブジェクトの環境をセットアップする。また、Direct3D7 クラスを使って、頂点バッファを作成したり、テクスチャ マップや深度バッファ フォーマットを列挙することができる。ここでは、Direct3D7 クラスのメソッドのリファレンスを提供する。

Direct3D7 クラスは、DirectDraw7 オブジェクトから GetDirect3D メソッドを呼び出すことにより取得される。

Direct3D7 クラスのメソッドは、以下のグループにまとめることができる。

生成 | CreateDevice
 | CreateVertexBuffer
列挙 | GetDevicesEnum
 | GetEnumZBufferFormats
その他 | EvictManagedTextures
 | GetDirectDraw

参照

Direct3D へのアクセス、Direct3D と DirectDraw


Direct3D7.CreateDevice

Direct3D7.CreateDevice メソッドは、DrawPrimitive メソッドで使用するために、Direct3D デバイスを生成する。

object.CreateDevice( _
    guid As String, _
    surf As DirectDrawSurface7) As Direct3DDevice7

パラメータ

object
Direct3D7 オブジェクトを表すオブジェクト式。
guid
新規デバイスの GUID。この値は、列挙された GUID 文字列、"IID_Direct3DHALDevice" または "IID_Direct3DRGBDevice" 文字列定数にすることができる。このメソッドは、テストまたは機能デモンストレーション用の基準デバイスを作成する "IID_Direct3DRefDevice" も受け取る。
surf
デバイスのレンダリング ターゲットとなる DirectDrawSurface オブジェクト用の DirectDrawSurface7 オブジェクト。DDSCAPS_3DDEVICE 能力を用いてサーフェスは 3D デバイスとして生成された。

戻り値

メソッドが成功すると、Direct3DDevice7 オブジェクトへの参照を返す。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は、Err.Number に DDERR_INVALIDPARAMS が設定される。

注意

指定された Direct3D7 オブジェクトによって作成されたレンダリング デバイスはすべて、同じ物理リソースを共有する。複数のレンダリング デバイスで同じハードウェアを共有するので、単一の Direct3D7 オブジェクトから複数のレンダリング デバイスを作成できるが、パフォーマンスが大幅に低下する。

Direct3D7.CreateDevice を呼び出すと、DirectDraw サーフェス オブジェクトとは別個のデバイス オブジェクトを作成できる。このデバイスは、DirectDraw サーフェスをレンダリング ターゲットとして使用する。

参照

Direct3DDevice7、Direct3D デバイスの作成、Direct3D デバイス


Direct3D7.CreateVertexBuffer

Direct3D7.CreateVertexBuffer メソッドは、頂点バッファ オブジェクトを作成する。

object.CreateVertexBuffer( _
    desc As D3DVERTEXBUFFERDESC, _
    flags As CONST_D3DDPFLAGS) As Direct3DVertexBuffer7

パラメータ

object
Direct3D7 オブジェクトを表すオブジェクト式。
desc
頂点バッファが含む頂点のフォーマットと数を記述する D3DVERTEXBUFFERDESC 型。
flags
CONST_D3DDPFLAGS 列挙の定数の 1 つ (クリッピング値を表す柔軟な頂点フォーマット フラグ)。このパラメータ値を 0 に設定して未トランスフォーム頂点またはトランスフォーム済頂点のクリッピング情報を含むことのできる頂点バッファを作成したり、D3DDP_DONOTCLIP フラグを使ってトランスフォーム済頂点を含むがクリッピング情報は格納しない頂点バッファを作成する。

戻り値

メソッドが成功すると、Direct3DVertexBuffer7 オブジェクトへの参照を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_INVALIDVERTEXFORMAT
D3DERR_VBUF_CREATE_FAILED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

参照

Direct3DVertexBuffer7、頂点バッファ


Direct3D7.EvictManagedTextures

Direct3D7.EvictManagedTextures メソッドは、管理下のすべてのテクスチャをローカルあるいは非ローカル ビデオ メモリから削除する。

object.EvictManagedTextures()

パラメータ

object
Direct3D7 オブジェクトを表すオブジェクト式。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。

注意

このメソッドにより、Direct3D は、DDSCAPS2_TEXTUREMANAGE または DDSCAPS2_D3DTEXTUREMANAGE フラグと共に作成された任意のテクスチャ サーフェスを、ローカルあるいは非ローカル ビデオ メモリから削除する。

参照

自動テクスチャ管理


Direct3D7.GetDevicesEnum

Direct3D7.GetDevicesEnum メソッドは、Direct3DEnumDevices オブジェクトを作成する。

object.GetDevicesEnum() As Direct3DEnumDevices

パラメータ

object
Direct3D7 オブジェクトを表すオブジェクト式。

戻り値

メソッドが成功すると、Direct3DEnumDevices オブジェクトを返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


Direct3D7.GetDirectDraw

Direct3D7.GetDirectDraw メソッドは、Direct3D オブジェクトに関連付けられた DirectDraw7 オブジェクトを取得する。

object.GetDirectDraw() As DirectDraw7

パラメータ

object
Direct3D7 オブジェクトを表すオブジェクト式。

戻り値

メソッドが成功すると、DirectDraw7 オブジェクトへの参照を返す。

Error Codes

メソッドが失敗したするとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_OUTOFMEMORY

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。


Direct3D7.GetEnumZBufferFormats

Direct3D7.GetEnumZBufferFormats メソッドは、Direct3DEnumPixelFormats オブジェクトを作成する。

object.GetEnumZBufferFormats( _
    guid As String) As Direct3DEnumPixelFormats

パラメータ

object
Direct3D7 オブジェクトを表すオブジェクト式。
guid
その深度バッファ フォーマットが列挙されるデバイスのグローバル ユニーク識別子。

戻り値

メソッドが成功すると、Direct3DEnumPixelFormats オブジェクトへの参照を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。


Direct3DDevice7

Direct3DDevice7 クラスは、アプリケーションが DrawPrimitive によるレンダリングを実行するためのメソッドを提供する。デバイスを作成するには、Direct3D7.CreateDevice メソッドを呼び出す。

概要については、「Direct3D デバイス」および「DrawPrimitive メソッド」を参照すること。

Direct3DDevice7 クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetCaps
 | GetDirect3D
 | GetInfo
 | GetDeviceGuid
デバイス ステート | ApplyStateBlock
 | BeginStateBlock
 | CaptureStateBlock
 | CreateStateBlock
 | DeleteStateBlock
 | EndStateBlock
 | GetClipStatus
 | GetRenderState
 | GetRenderStateSingle
 | GetRenderTarget
 | GetTransform
 | SetClipStatus
 | SetRenderState
 | SetRenderStateSingle
 | SetRenderTarget
 | SetTransform
ライティングとマテリアル | GetMaterial
 | GetLight
 | GetLightEnable
 | LightEnable
 | SetMaterial
 | SetLight
その他 | ComputeSphereVisibility
 | MultiplyTransform
レンダリング | DrawIndexedPrimitive
 | DrawIndexedPrimitiveVB
 | DrawPrimitive
 | DrawPrimitiveVB
シーン | BeginScene
 | EndScene
テクスチャ | GetTexture
 | GetTextureFormatsEnum
 | GetTextureStageState
 | GetTextureStageStateSingle
 | Load
 | PreLoad
 | SetTexture
 | SetTextureStageState
 | SetTextureStageStateSingle
 | ValidateDevice
ユーザー定義クリップ面 | GetClipPlane
 | SetClipPlane
ビューポート | Clear
 | GetViewport
 | SetViewport

このクラスには、柔軟な頂点フォーマット、頂点バッファ、および可視性計算をサポートするメソッドも含まれる。

参照

Direct3D デバイス、レンダリング


Direct3DDevice7.ApplyStateBlock

Direct3DDevice7.ApplyStateBlock メソッドは、既存のデバイス ステート ブロックをレンダリング デバイスに適用する。

object.ApplyStateBlock( _
    blockHandle As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
blockHandle
適用されるデバイス ステート ブロックのハンドル。Direct3DDevice7.EndStateBlock メソッドによって返される。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に DDERR_INVALIDPARAMS が設定され、blockHandle パラメータが無効であるか、マクロの記録中であるかを示す。

注意

アプリケーションが他のブロックを記録している間は、デバイス ステート ブロックを適用できない。

このメソッドは Direct3DDevice7 インターフェイスと共に導入された。

レンダリング デバイスのステートに影響するすべての処理同様、シーンのレンダリング時、つまり Direct3DDevice7.BeginScene メソッドを呼び出してから Direct3DDevice7.EndScene メソッドを呼び出す前に、ステート ブロックを適用することを勧める。

参照

Direct3DDevice7.BeginStateBlock、Direct3DDevice7.CaptureStateBlock、Direct3DDevice7.CreateStateBlock、Direct3DDevice7.DeleteStateBlock、Direct3DDevice7.EndStateBlock、ステート ブロック


Direct3DDevice7.BeginScene

Direct3DDevice7.BeginScene メソッドはシーンを開始する。アプリケーションは、レンダリングを実行する前にこのメソッドを呼び出さなければならない。また、レンダリングが完了し、再度 Direct3DDevice7.BeginScene を呼び出す前には、Direct3DDevice7.EndScene を呼び出さなければならない。

object.BeginScene()

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。

注意

BeginScene メソッドが失敗すると、デバイスはシーンを開始できないので、Direct3DDevice7.EndScene メソッドを呼び出す必要はない。BeginScene が失敗した場合は、その後に Direct3DDevice7.EndScene メソッドを呼び出すと失敗する。

参照

Direct3DDevice7.EndScene


Direct3DDevice7.BeginStateBlock

Direct3DDevice7.BeginStateBlock メソッドは、Direct3D にデバイス ステート ブロックの記録を開始するよう指示する。

object.BeginStateBlock()

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

アプリケーションは、このメソッドを呼び出す前に、Direct3DDevice7.ValidateDevice メソッドを呼び出して、記録されたすべてのステートが有効かどうかを確認することができる。

ステート ブロック (Direct3DDevice7.BeginStateBlock を呼び出してから Direct3DDevice7.EndStateBlock を呼び出すまでの間) には、次のメソッドを記録できる。

  • Direct3DDevice7.LightEnable
  • Direct3DDevice7.SetClipPlane
  • Direct3DDevice7.SetLight
  • Direct3DDevice7.SetMaterial
  • Direct3DDevice7.SetRenderState
  • Direct3DDevice7.SetTexture
  • Direct3DDevice7.SetTextureStageState
  • Direct3DDevice7.SetTransform
  • Direct3DDevice7.SetViewport

ステート ブロックでのステート変化の順序は保証されない。ステート セットで同じステートを何度も指定した場合、最後の値が使用される。

参照

Direct3DDevice7.EndStateBlock、Direct3DDevice7.CaptureStateBlock、Direct3DDevice7.CreateStateBlock、Direct3DDevice7.DeleteStateBlock、Direct3DDevice7.ApplyStateBlock、ステート ブロック


Direct3DDevice7.CaptureStateBlock

Direct3DDevice7.CaptureStateBlock メソッドは、既存のステート ブロックの値を、現在そのデバイスに設定されている値に更新する。

object.CaptureStateBlock( _
    blockHandle As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
blockHandle
現在のデバイス ステートをキャプチャするステート ブロックのハンドル。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_INBEGINSTATEBLOCK
D3DERR_INOVERLAYSTATEBLOCK

注意

このメソッドは、既存のステート ブロックに、更新されたステートの値をキャプチャする。デバイスのステート全体をキャプチャするのではない。詳細については、「ステート ブロックの取得」を参照すること。

参照

Direct3DDevice7.ApplyStateBlock、Direct3DDevice7.BeginStateBlock、Direct3DDevice7.CreateStateBlock、Direct3DDevice7.EndStateBlock、Direct3DDevice7.DeleteStateBlock、ステート ブロック


Direct3DDevice7.CreateStateBlock

Direct3DDevice7.CreateStateBlock メソッドは、すべてのデバイス ステート、頂点関連ステート、ピクセル関連ステートの現在の値を含む新しいステート ブロックを作成する。

object.CreateStateBlock( _
  d3dsbType As CONST_D3DSTATEBLOCKTYPE, _
  blockHandle As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
d3dsbType
メソッドによってキャプチャされるステート データの型。CONST_D3DSTATEBLOCKTYPE 列挙で定義された値の 1 つにすることができる。
blockHandle
メソッドが成功した場合のステート ブロック ハンドルを含む変数。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_INBEGINSTATEBLOCK
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

頂点関連ステートとは、通常システムが頂点を処理する方法に関するステートを指す。ピクセル関連ステートとは、通常システムがラスタ化時にピクセルまたは深度バッファ データを処理する方法に関するステートを指す。一部のステートは両方のグループに属する。各グループのステートについては、「事前定義するステート ブロックの作成」を参照すること。

参照

Direct3DDevice7.ApplyStateBlock、Direct3DDevice7.BeginStateBlock、Direct3DDevice7.CaptureStateBlock、Direct3DDevice7.EndStateBlock、Direct3DDevice7.DeleteStateBlock、ステート ブロック


Direct3DDevice7.Clear

Direct3DDevice7.Clear メソッドは、ビューポート (あるいはビューポート内の矩形のセット) をクリアして特定の RGBA 色にしたり、深度バッファをクリアしたり、ステンシル バッファを削除したりする。

object.Clear( _
    count As Long, _
    recs() As D3DRECT, _
    flags As CONST_D3DCLEARFLAGS, _
    color As Long, _
    z As Single, _
    stencil As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
count
recs の配列にある矩形の数。
recs()
クリアする矩形を記述する D3DRECT 型の配列。矩形をレンダリング ターゲットの寸法に設定すると、サーフェス全体がクリアされる。各矩形は、レンダリング ターゲット サーフェス上の点に対応するスクリーン座標を使用する。座標はビューポートの矩形の境界でクリップされる。
flags
クリアするサーフェスを示すフラグ。このパラメータは、次のフラグの任意の組み合わせを取ることができるが、フラグを最低 1 つは使わなければならない。
D3DCLEAR_TARGET
レンダリング ターゲットをクリアして、color パラメータの色にする。
D3DCLEAR_STENCIL
ステンシル バッファをクリアして、stencil パラメータの値にする。
D3DCLEAR_ZBUFFER
深度バッファをクリアして、z パラメータの値にする。
color
レンダリング ターゲット サーフェスをクリアするのに使う、RGBA カラー値。DirectX7.CreateColorRGBA メソッドを呼び出して適切な値を作成することができる。
z
このメソッドが深度バッファに保存する新しい z 値。このパラメータには、0.0 から 1.0 までの値 (両端の値を含む) を使用できる (z または w 深度バッファの場合)。0.0 はビューアに最も近い距離、1.0 は最も遠い距離を表す。
stencil
各ステンシル バッファのエントリに保存する整数値。このパラメータには 0 から 2n-1 までの値 (両端の値を含む) を使用できる。n は、ステンシル バッファのビット深度である。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_STENCILBUFFER_NOTPRESENT
D3DERR_VIEWPORTHASNODEVICE
D3DERR_ZBUFFER_NOTPRESENT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、レンダリング ターゲットに深度バッファがアタッチされていないときに D3DCLEAR_ZBUFFER または D3DCLEAR_STENCIL フラグを指定すると失敗する。また、深度バッファのフォーマットにステンシル バッファの情報が含まれていないときに、D3DCLEAR_STENCIL フラグを指定すると失敗する。


Direct3DDevice7.ComputeSphereVisibility

Direct3DDevice7.ComputeSphereVisibility メソッドは、このデバイスの現在のビューポート内における球の可視性 (完全、一部、不可視) を計算する。

object.ComputeSphereVisibility( _
    center As D3DVECTOR, _
    radius As Single) As Long

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
center
ワールド空間座標で、球の中心点を記述する D3DVECTOR 型の配列。
radius
球の半径。

戻り値

メソッドが成功すると、CONST_D3DCLIPFLAGS 列挙のフラグの組み合わせを返す。これにより、デバイスの現在のビューポート内における球の可視性を示す。戻り値が 0 ("内側" フラグの組み合わせ) の場合、その球の可視性は完全になる。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

球の可視性は、ワールド、ビュー、および射影の合成行列の逆行列を使って視錐台をモデル空間に逆トランスフォームすることにより計算する。もしこの合成行列が逆行列にトランスフォームできない時 (行列式がゼロのとき) は、メソッドは失敗し、DDERR_GENERIC を返す。


Direct3DDevice7.DeleteStateBlock

Direct3DDevice7.DeleteStateBlock メソッドは、以前に記録されたデバイス ステート ブロックを削除する。

object.DeleteStateBlock( _
  blockHandle As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
blockHandle
削除するデバイス ステート ブロック (Direct3DDevice7.EndStateBlock メソッドによって返されたデバイス ステート ブロック) のハンドル。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に DDERR_INVALIDPARAMS が設定されて、blockHandle パラメータが無効であるか、マクロの記録中であるかを示す。

注意

ほかのデバイス ステート ブロックの記録中は、デバイス ステート ブロックを削除できない。

参照

Direct3DDevice7.BeginStateBlock、Direct3DDevice7.CaptureStateBlock、Direct3DDevice7.CreateStateBlock、Direct3DDevice7.EndStateBlock、Direct3DDevice7.ApplyStateBlock、ステート ブロック


Direct3DDevice7.DrawIndexedPrimitive

Direct3DDevice7.DrawIndexedPrimitive メソッドは、頂点の配列へのインデックスに基づいて、指定されたジオメトリ プリミティブをレンダリングする。

object.DrawIndexedPrimitive( _
    d3Dpt As CONST_D3DPRIMITIVETYPE, _
    d3dfvf As CONST_D3DFVFFLAGS, _
    vertices As Any, _
    vertexCount As Long, _
    indices() As Integer, _
    IndicesCount As Long, _
    flags As CONST_D3DDPFLAGS)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
d3Dpt
このコマンドによってレンダリングされるプリミティブの型。これは、CONST_D3DPRIMITIVETYPE 列挙の定数の 1 つでなければならない。

CONST_D3DPRIMITIVETYPE の D3DPT_POINTLIST メンバには、インデックスがないことに注意する。

d3dfvf
使用する頂点フォーマットを記述するCONST_D3DFVFFLAGS 列挙の柔軟な頂点フォーマット フラグの組み合わせ。
vertices
プリミティブ シーケンスで使用する頂点配列の最初の要素。
vertexCount
vertices 配列の頂点数を定義する。

このパラメータは、Direct3DDevice7.DrawPrimitive メソッドにおける vertexCount パラメータとは異なる使い方をされることに注意する。Direct3DDevice7.DrawPrimitive メソッドでは、vertexCount パラメータは描画すべき頂点数を与えるが、このメソッドは vertices パラメータが指す配列の合計頂点数を与える。Direct3DDevice7.DrawIndexedPrimitive メソッドを呼び出すときには、IndicesCount パラメータで描画すべき頂点数を指定する。

indices()
レンダリングするジオメトリを作成するときに、指定した頂点リストへのインデックス付けに使用される配列。この配列の値によって、0 から dwNumVertices – 1 の範囲で頂点にインデックスを付けなければならない。
IndicesCount
ジオメトリを作成するのに用意するインデックス数を指定する。許可されたインデックスの最大数は 65535 (&HFFFF)。
flags
プリミティブの描画方法を定義する CONST_D3DDPFLAGS の定数の 1 つ。

エラー コード

メソッドが失敗すると、エラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_WASSTILLDRAWING
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

レンダリングする頂点のフォーマットは、指定した頂点フォーマットと一致しなければならない。パフォーマンス上の理由から、Direct3D は、頂点のサイズとストライドが、指定された柔軟な頂点フォーマットと一致するかどうかを確認しない。これらが一致しない場合、メモリに障害が発生する可能性がある。

頂点バッファからレンダリングする場合には、このメソッドの代わりに、頂点バッファ メソッドを使用する。

DirectX の現在のバージョンでは、Direct3DDevice7.DrawIndexedPrimitive は時折、厳密に必要とされるよりも大きい更新矩形を生成することがある。多数の頂点数を処理するときには、これはアプリケーションのパフォーマンスに悪影響を与える。D3DTLVERTEX 頂点を使用する場合、システムが必要以上の頂点を処理するときには、D3DDP_DONOTCLIP と D3DDP_DONOTUPDATEEXTENTS フラグを使ってこの問題を解決するべきである。

参照

Direct3DDevice7.DrawPrimitive、Direct3DDevice7.DrawPrimitiveVB、Direct3DDevice7.DrawIndexedPrimitiveVB


Direct3DDevice7.DrawIndexedPrimitiveVB

Direct3DDevice7.DrawIndexedPrimitiveVB メソッドは、頂点バッファ内の頂点配列へのインデックスに基づいて、ジオメトリ プリミティブをレンダリングする。

object.DrawIndexedPrimitiveVB( _
    d3Dpt As CONST_D3DPRIMITIVETYPE, _
    vertexBuffer As Direct3DVertexBuffer7, _
    StartVertex As Long, _
    NumVertices As Long, _
    indexArray() As Integer, _
    indexcount As Long, _
    flags As CONST_D3DDPFLAGS)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
d3Dpt
このコマンドによってレンダリングされるプリミティブの型。これは、CONST_D3DPRIMITIVETYPE 列挙の定数の 1 つでなければならない。

CONST_D3DPRIMITIVETYPE の D3DPT_POINTLIST メンバには、インデックスがないことに注意する。

vertexBuffer
頂点の配列を含む頂点バッファに対する Direct3DVertexBuffer7 オブジェクト。頂点は、トランスフォームされていてもいなくても、最適化されていてもいなくてもよい。
StartVertex
レンダリングされる頂点バッファ内の最初の頂点のインデックス。
NumVertices
レンダリングされる頂点バッファ内の頂点総数。
indexArray()
頂点バッファ内の頂点へのインデックス付けに使用される配列。この配列の値によって、StartVertex から StartVertex + NumVertices – 1 の範囲で頂点にインデックスを付けなければならない。
indexcount
indexArray() 配列内のインデックス数。許可されたインデックスの最大数は 65535 (＆HFFFF)。
flags
プリミティブの描画方法を定義する CONST_D3DDPFLAGS 列挙の定数の 1 つ。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

レンダリングする頂点のフォーマットは、指定した頂点フォーマットと一致しなければならない。パフォーマンス上の理由から、Direct3D は、頂点のサイズとストライドが、指定された柔軟な頂点フォーマットと一致するかどうかを確認しない。これらが一致しない場合、メモリに障害が発生する可能性がある。

頂点バッファからレンダリングする場合は、頂点バッファ メソッドを使用しなければならない。

リファレンス ラスタライザを除いて、ソフトウェア デバイスは、ローカルであるか非ローカルであるかにかかわらず、ビデオ メモリの頂点バッファからレンダリングすることはできない。ソフトウェア デバイスを使用して頂点バッファをレンダリングするには、頂点バッファがシステム メモリに存在しなければならない。ハードウェア デバイスは、システム メモリまたはビデオ メモリのどちらの頂点バッファからでも、レンダリングすることができる。

頂点バッファがロックされているときはレンダリングすることはできない。ロックされた頂点バッファを使って Direct3DDevice7.DrawIndexedPrimitiveVB または Direct3DDevice7.DrawPrimitiveVB メソッドを呼び出そうとすると失敗し、D3DERR_VERTEXBUFFERLOCKED を返す。

参照

Direct3DDevice7.DrawPrimitive、Direct3DDevice7.DrawPrimitiveVB、Direct3DDevice7.DrawIndexedPrimitive


Direct3DDevice7.DrawPrimitive

Direct3DDevice7.DrawPrimitive メソッドは、指定の型のジオメトリ プリミティブのシーケンスとして、頂点の指定の配列をレンダリングする。

object.DrawPrimitive( _
    d3Dpt As CONST_D3DPRIMITIVETYPE, _
    d3dfvf As CONST_D3DFVFFLAGS, _
    vertices As Any, _
    vertexCount As Long, _
    flags As CONST_D3DDPFLAGS)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
d3Dpt
このコマンドによってレンダリングされるプリミティブの型。これは、CONST_D3DPRIMITIVETYPE 列挙の定数の 1 つでなければならない。

CONST_D3DPRIMITIVETYPE の D3DPT_POINTLIST メンバには、インデックスがないことに注意する。

d3dfvf
使用する頂点フォーマットを記述する CONST_D3DFVFFLAGS 列挙の柔軟な頂点フォーマット フラグの組み合わせ。
vertices
プリミティブ シーケンスで使用する頂点配列の最初の要素。
vertexCount
頂点配列内の頂点数を定義する。許可された頂点の最大数は、65535 (&HFFFF)。
flags
プリミティブの描画方法を定義する CONST_D3DDPFLAGS 列挙の定数の 1 つ。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_WASSTILLDRAWING
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

頂点バッファからレンダリングする場合には、このメソッドの代わりに頂点バッファ メソッドを使用する。

レンダリングする頂点のフォーマットは、指定した頂点フォーマットと一致しなければならない。パフォーマンス上の理由から、Direct3D は、頂点のサイズとストライドが、指定された柔軟な頂点フォーマットと一致するかどうかを確認しない。これらが一致しない場合、メモリに障害が発生する可能性がある。

参照

Direct3DDevice7.DrawPrimitiveVB、Direct3DDevice7.DrawIndexedPrimitive、Direct3DDevice7.DrawIndexedPrimitiveVB


Direct3DDevice7.DrawPrimitiveVB

Direct3DDevice7.DrawPrimitiveVB メソッドは、ジオメトリ プリミティブのシーケンスとして、頂点バッファ内の頂点の配列をレンダリングする。

object.DrawPrimitiveVB( _
    d3dpt As CONST_D3DPRIMITIVETYPE, _
    vertexBuffer As Direct3DVertexBuffer7, _
    startVertex As Long, _
    numVertices As Long, _
    flags As CONST_D3DDPFLAGS)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
d3dpt
このコマンドによってレンダリングされるプリミティブの型。これは、CONST_D3DPRIMITIVETYPE 列挙の定数の 1 つでなければならない。

CONST_D3DPRIMITIVETYPE の D3DPT_POINTLIST メンバには、インデックスがないことに注意する。

vertexBuffer
頂点の配列を含む頂点バッファに対する Direct3DVertexBuffer7 オブジェクト。頂点は、トランスフォームされていてもいなくても、最適化されていてもいなくてもよい。
startVertex
プリミティブ中の最初の頂点のインデックス値。最大可能始点インデックスは 65535 (&HFFFF)。
numVertices
レンダリングする頂点数。許可された頂点の最大数は、65535 (＆HFFFF)。
flags
プリミティブの描画方法を定義する CONST_D3DDPFLAGS 列挙の定数の 1 つ。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_WASSTILLDRAWING
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

レンダリングする頂点のフォーマットは、指定した頂点フォーマットと一致しなければならない。パフォーマンス上の理由から、Direct3D は、頂点のサイズとストライドが、指定された柔軟な頂点フォーマットと一致するかどうかを確認しない。これらが一致しない場合、メモリに障害が発生する可能性がある。

頂点バッファからレンダリングする場合には、頂点バッファ メソッドを使用しなければならない。

リファレンス ラスタライザを除いて、ソフトウェア デバイスはビデオ メモリ (ローカルまたは非ローカル) の頂点バッファからレンダリングすることはできない。ソフトウェア デバイスを使用して頂点バッファをレンダリングするには、頂点バッファがシステム メモリに存在しなければならない。ハードウェア デバイスは、システム メモリまたはビデオ メモリのどちらの頂点バッファからでも、レンダリングすることができる。

頂点バッファがロックされているときはレンダリングすることはできない。ロックされた頂点バッファを使って Direct3DDevice7.DrawIndexedPrimitiveVB または Direct3DDevice7.DrawPrimitiveVB メソッドを呼び出そうとすると失敗し、D3DERR_VERTEXBUFFERLOCKED を返す。

参照

Direct3DDevice7.DrawPrimitive、Direct3DDevice7.DrawIndexedPrimitive、Direct3DDevice7.DrawIndexedPrimitiveVB


Direct3DDevice7.EndScene

Direct3DDevice7.EndScene メソッドは、Direct3DDevice7.BeginScene メソッドによって開始されたシーンを終了する。

object.EndScene()

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。

注意

このメソッドが成功すると、シーンがレンダリングされ、デバイス サーフェスがレンダリングされたシーンを保持する。

シーンのレンダリングが開始された後で、次のシーンのレンダリングを開始するために Direct3DDevice7.BeginScene メソッドを呼び出す前に、このメソッドを呼び出さなければならない (BeginScene メソッドが失敗した場合、シーンは開始されないので、このメソッドを呼び出す必要はない)。

参照

Direct3DDevice7.BeginScene


Direct3DDevice7.EndStateBlock

Direct3DDevice7.EndStateBlock メソッドは、デバイス ステート ブロックの記録を中止し、ブロック ハンドルを取得するよう Direct3D に指示する。

object.EndStateBlock( _
    blockHandle As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
blockHandle
完成したデバイス ステート ブロックのハンドルを含む変数。この値は、Direct3DDevice7.ApplyStateBlock および Direct3DDevice7.DeleteStateBlock メソッドで使用される。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に DDERR_INVALIDPARAMS が設定され、blockHandle パラメータが無効であるか、Direct3DDevice7.BeginStateBlock メソッドが呼び出されていないことを示す。

参照

Direct3DDevice7.ApplyStateBlock、Direct3DDevice7.BeginStateBlock、ct3DDevice7.CaptureStateBlock、Direct3DDevice7.CreateStateBlock、Direct3DDevice7.DeleteStateBlock、ステート ブロック


Direct3DDevice7.GetCaps

Direct3DDevice7.GetCaps メソッドは、Direct3D デバイスの能力を取得する。

object.GetCaps( _
    desc As D3DDEVICEDESC7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
desc
デバイスのハードウェア性能を格納する D3DDEVICEDESC7 型。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

このメソッドは、ディスプレイ デバイスの能力を取得しない。この情報を取得するには、DirectDraw7.GetCaps メソッドを使用する。


Direct3DDevice7.GetClipPlane

Direct3DDevice7.GetClipPlane メソッドは、デバイスのユーザー定義クリップ面の係数を取得する。

object.GetClipPlane( _
  Index As Long, _
  a As Single, _
  b As Single, _
  c As Single, _
  d As Single)

パラメータ

Index
平面式係数を取得するクリップ面のインデックス。
a, b, c, and d
クリップ面の係数を表す値。一般的な平面式で示される。「注意」を参照すること。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に DDERR_INVALIDPARAMS が設定される。このエラーは、Index の値が、デバイスでサポートされる最大クリップ面インデックス数を越えることを示す。

注意

このメソッドでは、一般的な平面式で係数を返す。Ax + By + Cz + D = 0 になるように、a、b、c、および d の値が一般的な平面式に代入される。Ax + By + Cz + Dw >= 0 の場合、同一の座標 (x、y、z、w) を持つ点が、平面の半分の空間で可視になる。クリップ面上または背後にある点は、シーンからクリップされる。

このメソッドで使用される平面式はワールド空間にあり、Direct3DDevice7.SetClipPlane メソッドによって設定される。

参照

Direct3DDevice7.SetClipPlane、D3DRENDERSTATE_CLIPPLANEENABLE、ユーザー定義クリップ面


Direct3DDevice7.GetClipStatus

Direct3DDevice7.GetClipStatus メソッドは、現在のクリップ ステータスを取得する。

object.GetClipStatus(clipStatus As D3DCLIPSTATUS)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
clipStatus
現在のクリップ ステータスを記述する D3DCLIPSTATUS 型。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.SetClipStatus


Direct3DDevice7.GetDeviceGuid

Direct3DDevice7.GetDeviceGuid メソッドは、デバイスのグローバル ユニーク識別子 (GUID) を String 型で取得する。

object.GetDeviceGuid() As String

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。

戻り値

デバイスの GUID を String 型で返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。

参照

Direct3D デバイスの種類


Direct3DDevice7.GetDirect3D

Direct3DDevice7.GetDirect3D メソッドは、このデバイスの Direct3D オブジェクトを取得する。

object.GetDirect3D() As Direct3D7

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。

戻り値

メソッドが成功すると、Direct3D7 オブジェクトへの参照を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。


Direct3DDevice7.GetInfo

Direct3DDevice7.GetInfo メソッドは、レンダリング デバイスに関する情報を取得する。Direct3D または基礎となるデバイス ドライバに関する情報を取得できる。

object.GetInfo( _
    lDevInfoID As CONST_D3DDEVINFOID, _
    DevInfoType As Any, _
    lSize As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
lDevInfoID
DevInfoType パラメータのデータ型を示す CONST_D3DDEVINFOID 列挙のフラグ。
DevInfoType
メソッドが成功した場合に、指定されたデバイスの情報を含む変数。この変数のデータ型と、データの解釈方法については、lDevInfoID のフラグによって決まる。
lSize
DevInfoType で示される型のサイズ (バイト数)。Visual Basic 関数 Len によって返される 。

戻り値

なし。

エラー コード

メソッドが失敗すると、S_FALSE を返して、そのデバイスが情報の照会をサポートしていないことを示すか、次のいずれかのエラー コードを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドを使って、この SDK のドキュメントには記載されていない特定の情報型、および対応する構造体をドライバが宣言できる。

このメソッドは同期的に実行されるので、低速実行時にはアプリケーションのパフォーマンスが低下する場合がある。シーンのレンダリング時 (Direct3DDevice7.BeginScene を呼び出してから Direct3DDevice7.EndScene を呼び出すまでの間) はこのメソッドを呼び出してはならない。

このメソッドは、製品開発時に (DirectX のデバッグ バージョンで) パフォーマンスの追跡とデバッグのために使用する。このメソッドは、デバイス データを取得することなく成功する場合がある。ホスト システムに DirectX ランタイムのリテール バージョンがインストールされている場合にこのような状況が発生する。

参照

D3DDEVINFO_TEXTUREMANAGER


Direct3DDevice7.GetLight

Direct3DDevice7.GetLight メソッドは、このデバイスで使用されるライト プロパティを取得する。

object.GetLight( _
    LightIndex As Long, _
    Light As D3DLIGHT7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
LightIndex
取得されるライト プロパティのゼロベースのインデックス。
Light
取得されるライティング パラメータを格納する D3DLIGHT7 型。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.SetLight、Direct3DDevice7.GetLightEnable、Direct3DDevice7.LightEnable、マテリアル


Direct3DDevice7.GetLightEnable

Direct3DDevice7.GetLightEnable メソッドは、ライトの状態 (有効または無効) を取得する。

object.GetLightEnable( _
    LightIndex As Long) As Boolean

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
LightIndex
このメソッドの対象となるライティング パラメータのゼロベースのインデックス。

戻り値

メソッドが成功すると、ライトの状態を示す値を返す。指定されたライトが有効の場合は TRUE、無効の場合は FALSE を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number にエラー コードが設定される。設定されるエラー コードのリストについては、Direct3D 直接モードの「エラー コード」を参照すること。

参照

Direct3DDevice7.GetLight、Direct3DDevice7.LightEnable、Direct3DDevice7.SetLight、ライティングとマテリアル


Direct3DDevice7.GetMaterial

Direct3DDevice7.GetMaterial メソッドは、デバイスの現在のマテリアル プロパティを取得する。

object.GetMaterial(  _
    Material As D3DMATERIAL7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
Material
現在のマテリアル プロパティを格納する D3DMATERIAL7 型。

エラー コード

メソッドが失敗するエラーが発生し、Err.Number に DDERR_INVALIDPARAMS が設定され、Material パラメータが無効であることを示す。

参照

Direct3DDevice7.SetMaterial、ライティングとマテリアル


Direct3DDevice7.GetRenderState

Direct3DDevice7.GetRenderState メソッドは、デバイスのレンダリング ステート値を取得する。

object.GetRenderState( _
    state As CONST_D3DRENDERSTATETYPE) As Long

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
state
調査対象のデバイス ステート変数。このパラメータは、CONST_D3DRENDERSTATETYPE 列挙の任意の定数にすることができる。

戻り値

メソッドが成功すると、指定されたレンダリング ステートの現在の値を返す。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.SetRenderState


Direct3DDevice7.GetRenderStateSingle

Direct3DDevice7.GetRenderStateSingle メソッドは、デバイスのレンダリング ステート値を取得する。

object.GetRenderStateSingle( _
    state As CONST_D3DRENDERSTATESINGLE) As Single

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
state
調査対象のデバイス ステート変数。このパラメータは、CONST_D3DRENDERSTATESINGLE 列挙の任意の定数にすることができる。

戻り値

メソッドが成功すると、指定されたレンダリング ステートの現在の値を返す。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.SetRenderState、Direct3DDevice7.SetRenderStateSingle


Direct3DDevice7.GetRenderTarget

Direct3DDevice7.GetRenderTarget メソッドは、レンダリング ターゲットとして使用されている DirectDrawSurface7 オブジェクトを取得する。

object.GetRenderTarget() As DirectDrawSurface7

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。

戻り値

メソッドが成功すると、レンダリング ターゲット サーフェス (DirectDrawSurface7 オブジェクト) への参照を返す。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.SetRenderTarget


Direct3DDevice7.GetTexture

Direct3DDevice7.GetTexture メソッドは、デバイスの、指定のステージに割り当てられたテクスチャを取得する。

object.GetTexture(stage As Long) As DirectDrawSurface7

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
stage
取得するテクスチャのステージ識別子。ステージ識別子はゼロをベースとする。現在、デバイスは 8 セットまでのテクスチャを持つことができるので、stage に許される最大値は 7 である。

戻り値

メソッドが成功すると、指定されたテクスチャの DirectDrawSurface7 オブジェクトを返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

参照

Direct3DDevice7.SetTexture、Direct3DDevice7.GetTextureStageState、Direct3DDevice7.SetTextureStageState、テクスチャ


Direct3DDevice7.GetTextureFormatsEnum

Direct3DDevice7.GetTextureFormatsEnum メソッドは、Direct3DEnumPixelFormats オブジェクトを取得する。

object.GetTextureFormatsEnum() As Direct3DEnumPixelFormats

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。

戻り値

メソッドが成功すると、Direct3DEnumPixelFormats オブジェクトへの参照を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

デバイスがそのテクスチャでサポートするピクセル フォーマットの情報を取得するには、Direct3DEnumPixelFormats オブジェクトのメソッドを使用する。


Direct3DDevice7.GetTextureStageState

Direct3DDevice7.GetTextureStageState メソッドは、現在割り当てられているテクスチャ ステート値を取得する。

object.GetTextureStageState( _
    stage As Long, _
    state As CONST_D3DTEXTURESTAGESTATETYPE) As Long

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
stage
ステートを取得するテクスチャのステージ識別子。ステージ識別子はゼロをベースとする。現在、デバイスは 8 セットまでのテクスチャを持つことができるので、stage に許される最大値は 7 である。
state
取得されるテクスチャのステート。このパラメータは、CONST_D3DTEXTURESTAGESTATETYPE 列挙の任意の定数にすることができる。

戻り値

メソッドが成功すると、ステート値を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

参照

Direct3DDevice7.SetTextureStageState、Direct3DDevice7.GetTexture、Direct3DDevice7.SetTexture、テクスチャ


Direct3DDevice7.GetTextureStageStateSingle

Direct3DDevice7.GetTextureStageStateSingle メソッドは、現在割り当てられているテクスチャのステート値を、Single 型で取得する。

object.GetTextureStageStateSingle( _
    stage As Long, _
    state As CONST_D3DTEXTURESTAGESINGLE) As Single

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
stage
ステートを取得するテクスチャのステージ識別子。ステージ識別子はゼロをベースとする。現在、デバイスは 8 セットまでのテクスチャを持つことができるので、stage に許される最大値は 7 である。
state
取得されるテクスチャのステート。このパラメータは、CONST_D3DTEXTURESTAGESINGLE 列挙の任意の定数にすることができる。

戻り値

メソッドが成功すると、ステート値を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

参照

Direct3DDevice7.SetTextureStageState、Direct3DDevice7.SetTextureStageStateSingle、Direct3DDevice7.GetTexture、Direct3DDevice7.SetTexture、テクスチャ


Direct3DDevice7.GetTransform

Direct3DDevice7.GetTransform メソッドは、トランスフォーム ステートを記述する行列を取得する。

object.GetTransform( _
    transformType As CONST_D3DTRANSFORMSTATETYPE, _
    matrix As D3DMATRIX)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
transformType
変更対象のデバイス ステート変数。このパラメータは、CONST_D3DTRANSFORMSTATETYPE 列挙の任意の定数にすることができる。
matrix
トランスフォームを記述する D3DMATRIX 型。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.SetTransform


Direct3DDevice7.GetViewport

Direct3DDevice7.GetViewport メソッドは、デバイスに現在設定されているビューポート パラメータを取得する。

object.GetViewport( _
    Viewport As D3DVIEWPORT7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
Viewport
メソッドが作成した場合に、現在のビューポート パラメータを格納する D3DVIEWPORT7 型。

戻り値

メソッドが失敗するとエラーが発生し,Viewport パラメータが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.SetViewport


Direct3DDevice7.LightEnable

Direct3DDevice7.LightEnable メソッドは、デバイスのライティング パラメータを有効または無効にする。

object.LightEnable( _
    LightIndex As Long, _
    bEnable As Boolean)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
LightIndex
このメソッドの対象となるライティング パラメータのゼロベースのインデックス。
bEnable
ライティング パラメータが有効か無効かを示す値。ゼロ以外の値に設定すると、指定されたインデックスにあるパラメータのライティングが有効になり、ゼロに設定すると無効になる。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number にエラー コードが設定される。Direct3D 直接モードのエラー コードとその説明については、「エラー コード」を参照すること。

注意

LightIndex の値を、デバイスで現在割り当てられているライト プロパティの範囲外の値にした場合、LightEnable メソッドによって次のプロパティの光源が作成され、有効ステートが Enable で指定した値に設定される。

メンバ | デフォルト
dltType | D3DLIGHT_DIRECTIONAL
dcvDiffuse | (R:1, G:1, B:1, A:0)
dcvSpecular | (R:0, G:0, B:0, A:0)
dcvAmbient | (R:0, G:0, B:0, A:0)
dvPosition | (0, 0, 0)
dvDirection | (0, 0, 1)
dvRange | 0
dvFalloff | 0
dvAttenuation0 | 0
dvAttenuation1 | 0
dvAttenuation2 | 0
dvTheta | 0
dvPhi | 0

参照

Direct3DDevice7.GetLight、Direct3DDevice7.GetLightEnable、Direct3DDevice7.SetLight、ライティングとマテリアル


Direct3DDevice7.Load

Direct3DDevice7.Load メソッドは、転送元テクスチャの矩形領域を、転送先テクスチャの指定された点、またはキューブ環境マップ内の面にロードする。

object.Load( _
    DestTex As DirectDrawSurface7, _
    xDest As Long, _
    yDest As Long, _
    SrcTex  As DirectDrawSurface7, _
    rcSrcRect As RECT, _
    flags As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
DestTex
転送元テクスチャからイメージ データを受け取る DirectDrawSurface7 クラス。キューブ環境マップやミップマップなどの複合テクスチャ サーフェスでは、最上位サーフェスでなければならない。
xDest and yDest
このメソッドによってイメージ データがロードされる転送先テクスチャ上の点の x 座標と y 座標。
SrcTex
ロードされるイメージ データを格納する DirectDrawSurface7 クラス。キューブ環境マップやミップマップなどの複合テクスチャ サーフェスでは、最上位サーフェスでなければならない。
rcSrcRect
このメソッドによってロードされる転送元テクスチャの領域を記述する RECT 型のアドレス。転送元の矩形が転送元テクスチャ全体をカバーする場合、またはこのメソッドを使って、管理下のテクスチャを明示的にロードする場合、このパラメータを Nothing に設定する。
flags
キューブ環境マップで、イメージ データを受け取る転送先テクスチャの面を示す値。このパラメータは、以下に示すフラグの任意の組み合わせで作られる。
0
転送先テクスチャが管理下のテクスチャの場合に必要。
DDSCAPS2_CUBEMAP_ALLFACES
転送元テクスチャにあるイメージ デーがすべての面にロードされる。
DDSCAPS2_CUBEMAP_NEGATIVEX, DDSCAPS2_CUBEMAP_NEGATIVEY、または DDSCAPS2_CUBEMAP_NEGATIVEZ
負の x、y、z 面がイメージ データを受け取る。
DDSCAPS2_CUBEMAP_POSITIVEX, DDSCAPS2_CUBEMAP_POSITIVEY, or DDSCAPS2_CUBEMAP_POSITIVEZ
正の x、y、z 面がイメージ データを受け取る。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

転送先テクスチャは、そのテクスチャを作成したレンダリング デバイスだけでなく、任意のレンダリング デバイスで使用できる。ハードウェア デバイスでは、ロード処理はハードウェア アクセラレーションになる。

ビット処理の場合、このメソッドを呼び出してテクスチャをビデオ メモリにロードする方が望ましい。

このメソッドは、すべてのレベルのミップマップ、キューブ マップ面、パレットおよびカラー キーを転送元テクスチャから転送先テクスチャにコピーする。

このメソッドを使ってミップマップをロードする場合、以下の点に注意する。

  • 転送先テクスチャ サーフェスを、転送元テクスチャに含まれるミップ レベルのサブセットにすることができる。この場合、両方のテクスチャに共通のミップ レベルだけがコピーされる。これは、テクスチャ LOD を実装する際に有効である。2 ミップ レベルだけのビデオ メモリ テクスチャを作成し、このメソッドを使って、すべてのミップ レベルで構成された転送元テクスチャからこれらのレベルをコピーすることができる。
  • 転送元および転送先サーフェス ポインタは、最上位サーフェスを指さなければならない。
  • ミップマップのサブ矩形をロードする場合、サブ矩形はミップマップ チェーンの最上位サーフェスに適用され、下位ミップ レベルごとに 2 つに分割される。


Direct3DDevice7.MultiplyTransform

Direct3DDevice7.MultiplyTransform メソッドは、デバイスのワールド、ビュー、射影行列に、指定された行列を乗算する。乗算の順は、matrix かける dstTransformStateType である。

object.MultiplyTransform( _
    dstTransformStateType As CONST_D3DTRANSFORMSTATETYPE, _
    matrix As D3DMATRIX)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
dstTransformStateType
修正するデバイス 行列を示す。このパラメータは、CONST_D3DTRANSFORMSTATETYPE 列挙の任意の定数にすることができる。最も一般的な設定は D3DTRANSFORMSTATE_WORLD で、ワールド行列を変更するが、必要であれば、ビュー行列や射影行列を変更するように指定することもできる。
matrix
現在のトランスフォームを修正する D3DMATRIX 型。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。このメソッドは、引数のいずれかが無効な場合には、DDERR_INVALIDPARAMS を返す。

注意

アプリケーションが、トランスフォームの階層を津かテ動作するために、MultiplyTransform メソッドを使用することも考えられる。たとえば、腕を表すジオメトリとトランスフォームは、以下の階層で構成することもある。

shoulder_transformation
    upper_arm geometry
    elbow transformation
        lower_arm geometry
        wrist transformation
            hand geometry

アプリケーションは、この階層をレンダリングするのに、以下の一連の呼び出しを使用してもよい (この擬似コードでは、すべてのパラメータは示していない)。

Direct3DDevice7.SetTransform(D3DTRANSFORMSTATE_WORLD,
    shoulder_transform)
Direct3DDevice7.DrawPrimitive(upper_arm)
Direct3DDevice7.MultiplyTransform(D3DTRANSFORMSTATE_WORLD,
    elbow_transform)
Direct3DDevice7.DrawPrimitive(lower_arm)
Direct3DDevice7.MultiplyTransform(D3DTRANSFORMSTATE_WORLD,
    wrist_transform)
Direct3DDevice7.DrawPrimitive(hand)

参照

Direct3DDevice7.DrawPrimitive、Direct3DDevice7.SetTransform


Direct3DDevice7.PreLoad

Direct3DDevice7.Preload メソッドは、管理下のテクスチャをビデオ メモリにロードするよう Direct3D テクスチャ マネージャに指示する。

object.PreLoad( _
  Texture As DirectDrawSurface7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
Texture
メモリにロードされる DirectDrawSurface7 オブジェクトへの参照。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドを使用すると、管理下のテキスチャが強制的にビデオ メモリにロードされるので、十分なビデオ メモリがない場合、システムはメモリを確保するために他のテクスチャを削除してから、指定されたテクスチャをロードする。ロードするテクスチャは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE または DDSCAPS2_D3DTEXTUREMANAGE フラグによって作成されたテクスチャ) でなければならない。これらの条件が満たされない場合は、メソッドが失敗し、DDERR_INVALIDPARAMS を返す。

参照

自動テクスチャ管理


Direct3DDevice7.SetClipPlane

Direct3DDevice7.SetClipPlane メソッドは、デバイスのユーザー定義クリップ面の係数を設定する。

object.SetClipPlane( _
  Index As Long, _
  a As Single, _
  b As Single, _
  c As Single, _
  d As Single)

パラメータ

Index
平面式係数を取得するクリップ面のインデックス。
a, b, c, and d
クリップ面の係数を一般的な平面式で表す値。「注意」を参照すること。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に DDERR_INVALIDPARAMS が設定される。このエラーは、Index の値が、そのデバイスでサポートされる最大クリップ面インデックス数を越えることを示す。

注意

このメソッドでは、一般的な平面式で係数を返す。Ax + By + Cz + D = 0 になるように、a、b、c、および d の値が一般的な平面式に代入される。Ax + By + Cz + Dw >= 0 の場合、同一の座標 (x、y、z、w) を持つ点が、平面の半分の空間で可視になる。クリップ面上または背後にある点は、シーンからクリップされる。

このメソッドで使用される平面式はワールド空間にある。

このメソッドは、設定されているクリップ面を有効にするものではない。クリップ面を有効にするには、D3DRENDERSTATE_CLIPPLANEENABLE レンダリング ステートを使用する。

参照

Direct3DDevice7.GetClipPlane、D3DRENDERSTATE_CLIPPLANEENABLE、ユーザー定義クリップ面


Direct3DDevice7.SetClipStatus

Direct3DDevice7.SetClipStatus メソッドは、現在のクリップ ステータスを設定する。

object.SetClipStatus(clipStatus As D3DCLIPSTATUS)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
clipStatus
クリップ ステータスの新しい設定値を記述する D3DCLIPSTATUS 型。

エラー コード

メソッドが失敗するとエラーが発生し、clipStatus パラメータが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

参照

Direct3DDevice7.GetClipStatus


Direct3DDevice7.SetLight

Direct3DDevice7.SetLight メソッドは、デバイスにライティング パラメータを割り当てる。

object.SetLight( _
    LightIndex As Long, _
    Light As D3DLIGHT7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
LightIndex
設定されるライティング パラメータの 0 から始まるインデックス。このインデックスに既にライト プロパティが存在する場合、新しいプロパティが上書きされる。
Light
設定されるライティング パラメータを格納する D3DLIGHT7 型。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

参照

Direct3DDevice7.GetLight、Direct3DDevice7.GetLightEnable、Direct3DDevice7.LightEnable、ライティングとマテリアル


Direct3DDevice7.SetMaterial

Direct3DDevice7.SetMaterial メソッドは、デバイスのマテリアル プロパティを設定する。

object.SetMaterial( _
  mat As D3DMATERIAL7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
mat
設定されるマテリアル プロパティを記述する D3DMATERIAL7 型。

エラー コード

メソッドが成功すると、D3D_OK を返す。

メソッドが失敗すると、エラーを返す。mat パラメータが無効の場合、メソッドは DDERR_INVALIDPARAMS を返す。

参照

Direct3DDevice7.GetMaterial


Direct3DDevice7.SetRenderState

Direct3DDevice7.SetRenderState メソッドは、デバイスのレンダリング ステートに Long 型の値を設定する。

object.SetRenderState( _
    state As CONST_D3DRENDERSTATETYPE, _
    renderstate As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
state
変更対象のデバイス ステート変数。このパラメータは、CONST_D3DRENDERSTATETYPE 列挙の任意の定数にすることができる。
renderstate
新しいレンダリング ステート値。このパラメータの意味は state で指定した値による。たとえば、ｓtate が D3DRENDERSTATE_SHADEMODE である場合には、この第 2 パラメータは、CONST_D3DSHADEMODE 列挙の定数の 1 つになる。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.GetRenderState、Direct3DDevice7.SetTransform


Direct3DDevice7.SetRenderStateSingle

Direct3DDevice7.SetRenderStateSingle メソッドは、デバイスのレンダリング ステートに Single 型の値を設定する。

object.SetRenderStateSingle( _
    state As CONST_D3DRENDERSTATESINGLE, _
    renderstate As Single)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
state
変更対象のデバイス ステート変数。このパラメータは、CONST_D3DRENDERSTATESINGLE 列挙の任意の定数にすることができる。
renderstate
新しいレンダリング ステート値。このパラメータの意味は state で指定した値による。たとえば、state が D3DRENDERSTATE_SHADEMODE である場合には、この第 2 パラメータは、CONST_D3DSHADEMODE 列挙の定数の 1 つになる。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は、Err.Number に DDERR_INVALIDPARAMS が設定される。

参照

Direct3DDevice7.GetRenderState、Direct3DDevice7.GetRenderStateSingle、Direct3DDevice7.SetTransform


Direct3DDevice7.SetRenderTarget

Direct3DDevice7.SetRenderTarget メソッドは、レンダリング ターゲットとして新しい DirectDraw サーフェスの方向に、レンダリング出力を簡単に指定することをアプリケーションに許す。

object.SetRenderTarget(surface As DirectDrawSurface7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
surface
既に作成されている、新しいレンダリング ターゲットとなるサーフェス オブジェクトに対する DirectDrawSurface7 オブジェクト。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

能力は、レンダリング ターゲット サーフェスのプロパティの変化によっては変わらない。Direct3D HAL およびソフトウェア ラスタライザともに、アプリケーションに能力を示す機会は一度だけである。システムは、目的のサーフェスのフォーマットにより異なる能力のセットを提示することはできない。

新しいレンダリング ターゲットに深度バッファがアタッチされている場合、コンテキストの古い z バッファが置き換えられる。それ以外の場合は、古い z バッファのアタッチが解除され、z バッファリングが無効になる。

複数の深度バッファがレンダリング ターゲットにアタッチされていると、この関数は失敗する。

参照

Direct3DDevice7.GetRenderTarget


Direct3DDevice7.SetTexture

Direct3DDevice7.SetTexture メソッドは、デバイスの指定されたステージにテクスチャを割り当てる。

object.SetTexture( _
    stage As Long, _
    texture As DirectDrawSurface7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
stage
テクスチャを設定するステージ識別子。ステージ識別子はゼロをベースとする。現在、デバイスは 8 セットまでのテクスチャを持つことができるので、stage に許される最大値は 7 である。
texture
設定されるテクスチャの DirectDrawSurface7 オブジェクト。キューブ環境マップなどの複合テクスチャでは、最上位サーフェスでなければならない。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

テクスチャが不要になった場合、該当するステージのテクスチャを Nothing に設定する必要がある。この処理を行わないと、アプリケーションの終了時に、そのサーフェスのメモリが失われる。

ソフトウェア デバイスは、1 つのテクスチャを一度に複数のテクスチャ ステージに割り当てることはサポートしていない。

参照

Direct3DDevice7.GetTexture、Direct3DDevice7.GetTextureStageState、Direct3DDevice7.SetTextureStageState、テクスチャ


Direct3DDevice7.SetTextureStageState

Direct3DDevice7.SetTextureStageState メソッドは、現在割り当てられているテクスチャのステート値を設定する。

object.SetTextureStageState( _
    stage As Long, _
    state As CONST_D3DTEXTURESTAGESTATETYPE, _
    value As Long)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
stage
ステート値を設定するテクスチャのステージ識別子。ステージ識別子はゼロをベースとする。現在、デバイスは 8 セットまでのテクスチャを持つことができるので、stage に許される最大値は 7 である。
state
設定するテクスチャ ステート。このパラメータは、CONST_D3DTEXTURESTAGESTATETYPE 列挙の任意の定数にすることができる。
value
設定するステート値。この値の意味は state パラメータで決まる。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

従来のテクスチャ関連レンダリング ステートを設定するには、このメソッドを使用してテクスチャ ステートを設定する必要がある。詳細については、「レンダリング ステートについて」を参照すること。

参照

Direct3DDevice7.GetTextureStageState、Direct3DDevice7.GetTexture、Direct3DDevice7.SetTexture、テクスチャ


Direct3DDevice7.SetTextureStageStateSingle

Direct3DDevice7.SetTextureStageStateSingle メソッドは、現在割り当てられているテクスチャのステート値を設定する。

object.SetTextureStageStateSingle( _
    stage As Long, _
    state As CONST_D3DTEXTURESTAGESINGLE, _
    value As Single)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
stage
ステート値を設定するテクスチャのステージ識別子。ステージ識別子はゼロをベースとする。現在、デバイスは 8 セットまでのテクスチャを持つことができるので、stage に許される最大値は 7 である。
state
設定するテクスチャ ステート。このパラメータは、CONST_D3DTEXTURESTAGESINGLE 列挙の任意の定数にすることができる。
value
設定するステート値。この値の意味は state パラメータで決まる。

Error Codes

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

従来のテクスチャ関連レンダリング ステートを設定するには、このメソッドを使用してテクスチャ ステートを設定する必要がある。詳細については、「レンダリング ステートについて」を参照すること。

参照

Direct3DDevice7.GetTextureStageStateSingle、Direct3DDevice7.GetTextureStageState、Direct3DDevice7.GetTexture、Direct3DDevice7.SetTexture、テクスチャ


Direct3DDevice7.SetTransform

Direct3DDevice7.SetTransform メソッドは、デバイスの単一のトランスフォーム関連ステートを設定する。

object.SetTransform( _
    transformType As CONST_D3DTRANSFORMSTATETYPE, _
    matrix As D3DMATRIX)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
transformType
変更対象のデバイス ステート変数。このパラメータは、CONST_D3DTRANSFORMSTATETYPE 列挙の任意の定数にすることができる。
matrix
現在の情報を修正する D3DMATRIX 型。

エラー コード

メソッドが失敗するとエラーが発生し、パラメータのいずれかが無効の場合は Err.Number に DDERR_INVALIDPARAMS が設定される。

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

参照

Direct3DDevice7.GetTransform、Direct3DDevice7.SetRenderState


Direct3DDevice7.SetViewport

Direct3DDevice7.SetViewport メソッドは、デバイスのビューポート パラメータを設定する。

object.SetViewport( _
    viewport As D3DVIEWPORT7)

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。
viewport
設定されたビューポート パラメータを格納する D3DVIEWPORT7 型。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に DDERR_INVALIDPARAMS が設定されて、viewport パラメータが無効であることを示す。

注意

D3DVIEWPORT7 型に格納された viewport パラメータが、レンダリング ターゲット サーフェス内に存在しない領域を示す場合、このメソッドは失敗し、DDERR_INVALIDPARAMS を返す。

参照

Direct3DDevice7.GetViewport


Direct3DDevice7.ValidateDevice

Direct3DDevice7.ValidateDevice メソッドは、現在設定されているテクスチャのブレンディング操作とパラメータに対し、デバイスが 1 回の処理でレンダリングできる能力を報告する。

object.ValidateDevice() As Long

パラメータ

object
Direct3DDevice7 オブジェクトを表すオブジェクト式。

戻り値

メソッドが成功すると、マルチパス レンダリングによってレンダリングを完了するために必要な回数を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
D3DERR_CONFLICTINGTEXTUREFILTER
D3DERR_TOOMANYOPERATIONS
D3DERR_UNSUPPORTEDALPHAARG
D3DERR_UNSUPPORTEDALPHAOPERATION
D3DERR_UNSUPPORTEDCOLORARG
D3DERR_UNSUPPORTEDCOLOROPERATION
D3DERR_UNSUPPORTEDFACTORVALUE
D3DERR_UNSUPPORTEDTEXTUREFILTER
D3DERR_WRONGTEXTUREFORMAT

注意

現在のハードウェアが、必ずしも操作と引数の可能なすべての組み合わせを実装している必要はない。特定のブレンディング操作が与えられたパラメータでできるかどうかは、必要なブレンディング操作を設定し、ValidateDevice メソッドを呼び出すことにより確認できる。

ValidateDevice メソッドは、現在設定されているレンダリング ステート、テクスチャ、テクスチャ ステージのステートを使って、呼び出された時点での確認を行なう。この呼び出しの後でこれらの要素に変更があると、それまでの確認結果は無効になるので、シーンのレンダリングをする前にこのメソッドを再度呼び出さなければならない。

ディフーズ反復値の使用は、引数としても操作としても (D3DTA_DIFFUSE または D3DTOP_BLENDDIFFUSEALPHA)、現在のハードウェアではまれにしかサポートされていない。ほとんどのハードウェアでは、直前のテクスチャ操作ステージにおけるカラーデータの反復値を導入している程度である。

各ステージのテクスチャ (D3DTA_TEXTURE) は、できるだけ、第 2 引数ではなく第 1 引数として指定する。

多くのカードは、任意のテクスチャのステージにおけるディフーズ値やスカラー値の使用はサポートしていない。これらは最初か最後のテクスチャのブレンディング ステージでのみ使えることが多い。

実際には多くのカードは、アルファ値を色チャネルへ複製したり入力を反転する以上のことができるような、最初のテクスチャと関連付けられたブレンディング ユニットを持っていない。そのため、アプリケーションでは、できれば 2 番目のテクスチャ ステージだけを使用することが必要になるかもしれない。このようなハードウェアでは、最初のユニットはデフォルト ステートにあると仮定され、D3DTOP_SELECTARG1 オペレーションの第 1 色引数は D3DTA_TEXTURE に設定される。

色操作に比べより複雑で実質的にも異なる、出力されたアルファ値に対する操作をサポートするハードウェアは、さらに少ない。

いくつかのハードウェアは、D3DTA_TFACTOR と D3DTA_DIFFUSE の同時使用をサポートしない。

また多くのカードは、マルチ テクスチャとミップマップ トライリニア フィルタリングの同時使用はサポートしない。マルチ テクスチャのブレンディング操作の中でテクスチャをトライリニア フィルタリングする要求があって、確認が失敗した場合は、トライリニア フィルタリングをやめて再度確認を行う。このようなケースでは、代わりに複数回のレンダリングをするのが最良であろう。

参照

Direct3DDevice7.GetTextureStageState、Direct3DDevice7.SetTextureStageState


Direct3DEnumDevices

アプリケーションは、Direct3DEnumDevices クラスのメソッドを使って、システムに存在する Direct3D デバイスの情報を取得する。Direct3DEnumDevices クラスは、Direct3D7.GetDevicesEnum メソッドによって取得される。

Direct3DEnumDevices クラスのメソッドは、以下のグループにまとめることができる。

デバイスの数 | GetCount
デバイス情報 | GetDescription
 | GetGuid
 | GetDesc
 | GetName


Direct3DEnumDevices.GetCount

Direct3DEnumDevices.GetCount メソッドは、システムにインストールされている Direct3D デバイスの数を返す。

object.GetCount() As Long

パラメータ

object
Direct3DEnumDevices オブジェクトを表すオブジェクト式。

戻り値

メソッドが成功すると、システムにインストールされている Direct3D デバイスの数を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。


Direct3DEnumDevices.GetDesc

Direct3DEnumDevices.GetDesc メソッドは、要求された Direct3D デバイスの能力を返す。

object.GetDesc(index As Long, hwDesc As D3DDEVICEDESC7)

パラメータ

object
Direct3DEnumDevices オブジェクトを表すオブジェクト式。
index
システムに複数の Direct3D デバイスがある場合、このパラメータによってデバイスを識別する。
hwDesc
Direct3D デバイスのハードウェア能力を格納する D3DDEVICEDESC7 型。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。


Direct3DEnumDevices.GetDescription

Direct3DEnumDevices.GetDescription メソッドは、要求された Direct3D デバイスの簡単な説明を返す。

object.GetDescription(index As Long) As String

パラメータ

object
Direct3DEnumDevices オブジェクトを表すオブジェクト式。
index
列挙されたデバイスのインデックス。この値は、1 から Direct3DEnumDevices.GetCount メソッドによって返される値の範囲になる。

戻り値

メソッドが成功すると、列挙されたデバイスの簡単な説明を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。設定されるエラー コードのリストについては、Direct3D 直接モードの「エラー コード」を参照すること。


Direct3DEnumDevices.GetGuid

Direct3DEnumDevices.GetDescription メソッドは、要求された Direct3D デバイスのグローバル ユニーク識別子 (GUID) を返す。

object.GetGuid(index As Long) As String

パラメータ

object
Direct3DEnumDevices オブジェクトを表すオブジェクト式。
index
列挙されたデバイスのインデックス。この値は、1 から Direct3DEnumDevices.GetCount メソッドによって返される値の範囲になる。

戻り値

メソッドが成功すると、列挙されたデバイスのグローバル ユニーク識別子を表す文字列ラベル、"IID_IDirect3DHALDevice"、"IID_IDirect3DTnLHalDevice"、または "IID_IDirect3DRGBDevice" を返す。この値は、連続する Direct3D7.CreateDevice メソッドの呼び出しによってデバイスを作成する際に使用される。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。設定されるエラー コードのリストについては、Direct3D 直接モードの「エラー コード」を参照すること。


Direct3DEnumDevices.GetName

Direct3DEnumDevices.GetName メソッドは、要求された Direct3D device デバイスの名前を返す。

object.GetName(index As Long) As String

パラメータ

object
Direct3DEnumDevices オブジェクトを表すオブジェクト式。
index
列挙されたデバイスのインデックス。この値は、1 から Direct3DEnumDevices.GetCount メソッドによって返される値の範囲になる。

戻り値

メソッドが成功すると、デバイスの名前を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。設定されるエラー コードのリストについては、「Direct3D 直接モードのエラー コード」を参照すること。


Direct3DEnumPixelFormats

アプリケーションは、Direct3DEnumPixelFormats クラスのメソッドを使用して、レンダリング デバイスでサポートされるピクセル フォーマットに関する情報を取得する。Direct3DEnumPixelFormats クラスは、Direct3DDevice7.GetTextureFormatsEnum および Direct3D7.GetEnumZBufferFormats メソッドによって取得される。

このクラスには、次の 2 つのメソッドがある。

  • GetCount
  • GetItem


Direct3DEnumPixelFormats.GetCount

Direct3DEnumPixelFormats.GetCount メソッドは、Direct3D デバイスでサポートされるピクセル フォーマットの数を返す。

object.GetCount() As Long

パラメータ

object
Direct3DEnumPixelFormats オブジェクトを表すオブジェクト式。

戻り値

メソッドが成功すると、サポートされるピクセル フォーマットの数を返す。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。


Direct3DEnumPixelFormats.GetItem

Direct3DEnumPixelFormats.GetItem メソッドは、指定されたピクセル フォーマットの説明を返す。

object.GetItem(index As Long, _
    pixelFormat As DDPIXELFORMAT)

パラメータ

object
Direct3DEnumPixelFormats オブジェクトを表すオブジェクト式。
index
説明を取得するピクセル フォーマット。
pixelFormat
列挙されたピクセル フォーマットを記述する DDPIXELFORMAT 型。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。


Direct3DVertexBuffer7

アプリケーションは、Direct3DVertexBuffer7 クラスのメソッドを使用して、Direct3DDevice7.DrawPrimitiveVB および Direct3DDevice7.DrawIndexedPrimitiveVB レンダリング メソッドで用いる頂点の集合を操作する。ここでは、このクラスのメソッドのリファレンスを提供する。概要については、「頂点バッファ」を参照すること。

Direct3DVertexBuffer7 クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetVertexBufferDesc
頂点データ | GetVertices
 | Lock
 | Optimize
 | ProcessVertices
 | SetVertices
 | Unlock

参照

頂点バッファ


Direct3DVertexBuffer7.GetVertexBufferDesc

Direct3DVertexBuffer7.GetVertexBufferDesc メソッドは、頂点バッファの記述を取得する。

object.GetVertexBufferDesc(desc As D3DVERTEXBUFFERDESC)

パラメータ

object
Direct3DVertexBuffer7 オブジェクトを表すオブジェクト式。
desc
頂点バッファの記述が格納される D3DVERTEXBUFFERDESC 型。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に DDERR_INVALIDPARAMS または別のエラー コードが設定される。


Direct3DVertexBuffer7.GetVertices

Direct3DVertexBuffer7.GetVertices メソッドは、頂点バッファ内の頂点を返す。

object.GetVertices(startIndex As Long, _
    count As Long, _
    verts As Any)

パラメータ

object
Direct3DVertexBuffer7 オブジェクトを表すオブジェクト式。
startIndex
頂点バッファ内で頂点が取得される開始インデックス。
count
処理される頂点数。
verts
取得された頂点が格納される配列の最初の要素。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number が設定される。


Direct3DVertexBuffer7.Lock

Direct3DVertexBuffer7.Lock メソッドは、頂点バッファをロックする。

object.Lock(flags As CONST_DDLOCKFLAGS)

パラメータ

object
Direct3DVertexBuffer7 オブジェクトを表すオブジェクト式。
flags
頂点バッファ メモリのロック方法を示す、CONST_DDLOCKFLAGS 列挙の次の定数の 1 つ。
DDLOCK_NOSYSLOCK
可能であれば、Win16Mutex (Win16Lock とも言われる) は用いない。
DDLOCK_READONLY
ロックされたメモリは読み出し専用であることを示す。
DDLOCK_WAIT
ロックが即座にできない場合、メソッドはロックできるまで、あるいは、別のエラーが生じるまでリトライする。
DDLOCK_WRITEONLY
ロックされたメモリは書き込み専用であることを示す。
DDLOCK_DISCARDCONTENTS
Direct3D 頂点バッファのロックのみで使用する。ロック中に頂点バッファの内容が保証されないことを示す。これにより、Direct3D またはドライバが、別のメモリ領域を頂点バッファとして供給できる。頂点バッファの内容をクリアしたい場合や、新しいデータを格納する場合に有効である。
DDLOCK_NOOVERWRITE
Direct3D 頂点バッファのみで使用する。ロック中に、フレーム (またはこのフラグのない最後のロック) の始めが修正されてから、頂点バッファの DrawPrimitive 呼び出しで頂点が参照されていないことを示す。頂点バッファにデータを追加するだけの場合に有効である。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_VERTEXBUFFEROPTIMIZED
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

頂点バッファがロックされているときに、バッファ内のデータを操作するには、Direct3DVertexBuffer7.GetVertices および Direct3DVertexBuffer7.SetVertices メソッドを使用する。頂点バッファのロック後、対応する Direct3DVertexBuffer7.Unlock を呼び出すまで、このメモリにアクセスすることができる。

頂点バッファがロックされているときはレンダリングすることはできない。ロックされた頂点バッファを使って Direct3DDevice7.DrawIndexedPrimitiveVB または Direct3DDevice7.DrawPrimitiveVB メソッドを呼び出そうとすると失敗し、D3DERR_VERTEXBUFFERLOCKED を返す。

このメソッドは、Direct3DVertexBuffer7.Unlock メソッドを呼び出すまで、Win16Mutex をホールドさせることがしばしばある。GUI デバッガは、Win16Mutex がホールドされている間は動作しない。

参照

Direct3DVertexBuffer7.Unlock、頂点バッファの内容へのアクセス


Direct3DVertexBuffer7.Optimize

Direct3DVertexBuffer7.Optimize メソッドは、最適化されていない頂点バッファを最適化された頂点バッファにトランスフォームする。

object.Optimize(dev As Direct3DDevice7)

パラメータ

object
Direct3DVertexBuffer7 オブジェクトを表すオブジェクト式。
dev
頂点バッファを最適化するデバイスの Direct3DDevice7 オブジェクト。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_VERTEXBUFFEROPTIMIZED
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

参照

頂点バッファの最適化、頂点バッファ


Direct3DVertexBuffer7.ProcessVertices

Direct3DVertexBuffer7.ProcessVertices メソッドは、トランスフォームされていない頂点を処理して、トランスフォーム済みまたは最適化された頂点バッファに入れる。

object.ProcessVertices( _
    vertexOp As CONST_D3DVOPFLAGS, _
    destIndex As Long, _
    count As Long, _
    srcBuffer As Direct3DVertexBuffer7, _
    srcIndex As Long, _
    dev As Direct3DDevice7, _
    flags As CONST_D3DPROCESSVERTICESFLAGS)

パラメータ

object
Direct3DVertexBuffer7 オブジェクトを表すオブジェクト式。
vertexOp
元のバッファから転送された頂点をメソッドが処理する方法を定義するフラグ。CONST_D3DVOPFLAGS 列挙の定数の任意の組み合わせを指定することができる。
destIndex
処理した後、頂点を置く先の頂点バッファ (このバッファ) へのインデックス。
count
元のバッファにある、処理する頂点の数。
srcBuffer
元の頂点バッファの Direct3DVertexBuffer7 オブジェクト。
srcIndex
元の頂点バッファにある、処理する頂点のうち、最初の頂点のインデックス
dev
頂点をトランスフォームするのに使うデバイスの Direct3DDevice7 オブジェクト。
flags
処理オプション。このパラメータは、CONST_D3DPROCESSVERTICESFLAGS 列挙のメンバの 1 つに設定する。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

D3DERR_INVALIDVERTEXFORMAT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

注意

vertexOp パラメータには、常に D3DVOP_TRANSFORMED フラグを含めること。このフラグを含めないと、メソッドは失敗し、DDERR_INVALIDPARAMS を返す。

参照

頂点の処理、頂点バッファ


Direct3DVertexBuffer7.SetVertices

Direct3DVertexBuffer7.SetVertices メソッドは、ロックされた頂点バッファ内の頂点を設定する。

object.SetVertices(startIndex As Long, _
    count As Long, _
    verts As Any)

パラメータ

object
Direct3DVertexBuffer7 オブジェクトを表すオブジェクト式。
startIndex
頂点を設定する頂点バッファ内のゼロベースのインデックス。
count
verts 配列に含まれる頂点の数。
verts
頂点データを格納するバッファの最初の要素。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number にエラー コードが設定される。Direct3D 直接モードのエラー コードとその説明については、「エラー コード」を参照すること。

注意

頂点バッファ内の頂点を操作する前に、Direct3DVertexBuffer7.Lock メソッドを呼び出して頂点バッファをロックしなければならない。

参照

Direct3DVertexBuffer7.GetVertices、Direct3DVertexBuffer7.Lock


Direct3DVertexBuffer7.Unlock

Direct3DVertexBuffer7.Unlock メソッドは、頂点バッファのロックを解除する。

object.Unlock()

パラメータ

object
Direct3DVertexBuffer7 オブジェクトを表すオブジェクト式。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEBUSY
DDERR_SURFACELOST

トラッピング エラーについては、「Visual Basic エラー トラッピング」を参照すること。

参照

Direct3DVertexBuffer7.Lock、頂点バッファの内容へのアクセス


型

ここでは、Direct3D 直接モードで使用する以下の型について説明する。

  • D3DCLIPSTATUS
  • D3DCOLORVALUE
  • D3DDEVICEDESC7
  • D3DDEVINFO_TEXTUREMANAGER
  • D3DDEVINFO_TEXTURING
  • D3DLIGHT7
  • D3DLINEPATTERN
  • D3DLVERTEX
  • D3DMATERIAL7
  • D3DMATRIX
  • D3DPRIMCAPS
  • D3DRECT
  • D3DTLVERTEX
  • D3DVECTOR
  • D3DVERTEX
  • D3DVERTEXBUFFERDESC
  • D3DVIEWPORT2


D3DCLIPSTATUS

D3DCLIPSTATUS 型は、現在のクリップ ステータスおよびクリップ領域のエクステントを記述する。

Type D3DCLIPSTATUS
    lFlags As Long
    lStatus As Long
    maxx As Single
    maxy As Single
    maxz As Single
    minx As Single
    miny As Single
    minz As Single
End Type

メンバ

lFlags
この型が 2D 領域、3D 領域、またはクリップ ステータスを記述するかどうかを表すフラグ。このメンバは、CONST_D3DCLIPSTATUSFLAGS 列挙の以下のフラグの組み合わせにすることができる。
D3DCLIPSTATUS_STATUS
型は現在のクリップ ステータスを記述する。
D3DCLIPSTATUS_EXTENTS2
型は現在の 2D 領域を記述する。このフラグは D3DCLIPSTATUS_EXTENTS3 と組み合わせることはできない。
D3DCLIPSTATUS_EXTENTS3
現在は実装されていない。
lStatus
現在のクリップ ステータスを記述する。このメンバは、CONST_D3DCLIPFLAGS 列挙の次の定数の 1 つ以上にすることができる。

組み合わせと一般フラグ

D3DSTATUS_CLIPINTERSECTIONALL
すべての CLIPINTERSECTION フラグの組み合わせ。
D3DSTATUS_CLIPUNIONALL
すべてのCLIPUNION フラグの組み合わせ。
D3DSTATUS_DEFAULT
D3DSTATUS_CLIPINTERSECTIONALL と D3DSTATUS_ZNOTVISIBLE フラグの組み合わせ。この値が、デフォルトである。
D3DSTATUS_ZNOTVISIBLE
レンダリングされたプリミティブが不可視であることを示す。このフラグは、z チェックを使うレンダリングが有効化された時点で、システムによりセット、またはクリアされる (D3DRENDERSTATE_ZVISIBLE 参照)。

クリップ交差フラグ

D3DSTATUS_CLIPINTERSECTIONBACK
視錐台の後方クリップ面と比較して、頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONBOTTOM
視錐台の下と比較して、頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONFRONT
視錐台の前方クリップ面と比較して、頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5
アプリケーション定義のクリップ面のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONLEFT
視錐台の左側面と比較して、頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONRIGHT
視錐台の右側面と比較して、頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONTOP
視錐台の上と比較して、頂点のクリッピング フラグの論理積をとる。

クリップ結合フラグ

D3DSTATUS_CLIPUNIONBACK
D3DCLIP_BACK と同じ。
D3DSTATUS_CLIPUNIONBOTTOM
D3DCLIP_BOTTOM と同じ。
D3DSTATUS_CLIPUNIONFRONT
D3DCLIP_FRONT と同じ。
D3DSTATUS_CLIPUNIONGEN0 through 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 through D3DCLIP_GEN5
アプリケーション定義のクリップ面。
maxx、minx、maxy、miny、maxz、minz
現在のクリップ領域の X、Y、Z の範囲。

参照

Direct3DDevice7.GetClipStatus、Direct3DDevice7.SetClipStatus


D3DCOLORVALUE

D3DCOLORVALUE 型は、D3DLIGHT7 と D3DMATERIAL7 型のカラー値を記述する。

Type D3DCOLORVALUE
    a As Single
    b As Single
    g As Single
    r As Single
End Type

メンバ

a、b、g および r
色の赤 (red)、緑 (green)、青 (blue)、およびアルファ (alpha) の要素を示す値。これらの値は一般に 0 か ら 1 の範囲に分布し、0 は黒である。

注意

なにか変わったエフェクトを盛り込むために、この型のメンバの値を 0 から 1 の範囲の外に設定することもできる。1 より大きい値は、シーンを洗い流すような強い光を産む。マイナスの値は暗い光を産み、実際には光をシーンから除いてしまう。詳細については、「カラー ライティング」を参照のこと。


D3DDEVICEDESC7

D3DDEVICEDESC7 型には、現在のデバイスに関する説明が格納される。この型は、Direct3DDevice7.GetCaps 等のメソッドで現在のデバイスを照会するために使われる。

Type D3DDeviceDesc7
    dpcLineCaps As D3DPRIMCAPS
    dpcTriCaps As D3DPRIMCAPS
    dvExtentsAdjust As Single
    dvGuardBandBottom As Single
    dvGuardBandLeft As Single
    dvGuardBandRight As Single
    dvGuardBandTop As Single
    dvMaxVertexW As Single
    lDevCaps As CONST_D3DDEVICEDESCCAPS
    lDeviceRenderBitDepth As Long
    lDeviceZBufferBitDepth As Long
    lFVFCaps As CONST_D3DFVFCAPSFLAGS
    lMaxActiveLights As Long
    lMaxAnisotropy As Long
    lMaxTextureAspectRatio As Long
    lMaxTextureHeight As Long
    lMaxTextureRepeat As Long
    lMaxTextureWidth As Long
    lMinTextureHeight As Long
    lMinTextureWidth As Long
    lStencilCaps As CONST_D3DSTENCILCAPSFLAGS
    lTextureOpCaps As CONST_D3DTEXOPCAPSFLAGS
    lVertexProcessingCaps As CONST_D3DVTXPCAPS
    nMaxSimultaneousTextures As Integer
    nMaxTextureBlendStages As Integer
    nMaxUserClipPlanes As Integer
    nMaxVertexBlendMatrices As Integer
End Type

メンバ

dpcLineCaps および dpcTriCaps
線や三角形を描画するため、デバイスのサポート情報を定義する D3DPRIMCAPS 型。
dvExtentsAdjust
矩形の外辺をアンチエイリアス カーネルに適合させるためのピクセル数。
dvGuardBandBottom、dvGuardBandLeft、dvGuardBandTop および dvGuardBandRight
ガードバンド クリッピング領域の画面空間座標。この座標で指定される矩形内にあり、かつ、ビューポートを表す矩形の外側に位置する座標はクリッピングされる。
dvMaxVertexW
デバイスがサポートする W 準拠深度の最大値。
lDevCaps
デバイスの能力を示す CONST_D3DDEVICEDESCCAPS 列挙の定数の 1 つ。
lDeviceRenderBitDepth
デバイスのレンダリング ビット深度。CONST_DDBITDEPTHFLAGS 列挙の次の定数 DDBD_8、DDBD_16、DDBD_24、DDBD_32 のうち、1 つ以上を設定できる。
lDeviceZBufferBitDepth
デバイスの深度バッファ ビット深度。CONST_DDBITDEPTHFLAGS 列挙の次の定数 DDBD_8、DDBD_16、DDBD_24、DDBD_32 のうち、1 つ以上を設定できる。
lFVFCaps
このデバイスによってサポートされる頂点フォーマットを示す CONST_D3DFVFCAPSFLAGS の定数の組み合わせ。
lMaxActiveLights
同時にアクティブにすることができるライトの最大数。
lMaxAnisotropy
D3DTSS_MAXANISOTROPY テクスチャ ステージ ステートの最大有効値。
lMaxTextureAspectRatio
ハードウェアがサポートするテクスチャの最大アスペクト比。通常は 2 のべき乗の値を取る。
lMaxTextureWidth、lMaxTextureHeight
このデバイスのテクスチャの最大の幅と高さ。
lMaxTextureRepeat
正規化された後のテクスチャ インデックスの整数部 (小数点以下を含まない) ビットの全範囲。D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE フラグがセットされると、テクスチャ アドレス モードが適用されるまで、デバイスはテクスチャ サイズに合わせてテクスチャ インデックスのスケーリングを行うのを延期する。このビットがセットされない場合は、デバイスは補間の前に、テクスチャ サイズ (詳細レベル最大値) に従ってテクスチャ インデックスのスケーリングを実行する。
lMinTextureWidth、lMinTextureHeight
このデバイスのテクスチャの最小の幅と高さ。
lStencilCaps
サポートされるステンシル バッファ操作を示す CONST_D3DSTENCILCAPSFLAGS 列挙の定数。ステンシル操作は 3 種類のステンシル バッファ操作レンダリング ステート (D3DRENDERSTATE_STENCILFAIL、D3DRENDERSTATE_STENCILPASS、D3DRENDERSTATE_STENCILFAILZFAIL) に対しては、すべて有効であるとみなされる。
lTextureOpCaps
デバイスによってサポートされるテクスチャ操作を記述する CONST_D3DTEXOPCAPSFLAGS 列挙の定数の組み合わせ。
lVertexProcessingCaps
頂点の処理能力を示す CONST_D3DVTXPCAPS 列挙の定数の組み合わせ。
nMaxSimultaneousTextures
デバイスのテクスチャ ブレンディング ステージに同時にバインド可能なテクスチャの最大数。「注意」を参照すること。
nMaxTextureBlendStages
デバイスがサポートするテクスチャ ブレンディング ステージの最大数。
nMaxUserClipPlanes
サポートされるユーザー定義クリップ面の最大数。0 から 31 の範囲になる。

ユーザー定義クリップ面は、Direct3DDevice7.GetClipPlane および Direct3DDevice7.SetClipPlane メソッドを使って操作される。

nMaxVertexBlendMatrices
ジオメトリ ブレンディングの実行時にデバイスが適用可能な行列の最大数。

注意

メンバ wMaxTextureBlendStages と wMaxSimultaneousTextures は一見したところ非常によく似ているが、含んでいる情報は異なる。メンバ wMaxTextureBlendStages が現在のデバイスがサポートするテクスチャ ブレンディング ステージの総数を示すのに対し、メンバ wMaxSimultaneousTextures は、これらのステージのうち何個が Direct3DDevice7.SetTexture メソッドを使用してテクスチャをバインドできるかを示す。

参照

CONST_D3DCOLORMODEL、D3DPRIMCAPS


D3DDEVINFO_TEXTUREMANAGER

テクスチャ マネージャの現在のステートに関する情報を格納する D3DDEVINFO_TEXTUREMANAGER 型。この型は、Direct3DDevice7.GetInfo メソッドで使用される。

Type D3DDEVINFO_TEXTUREMANAGER
    bThrashing As Boolean
    lLastPri As Long
    lNumEvicts As Long
    lNumTexturesUsed As Long
    lNumUsedTexInVid As Long
    lNumVidCreates As Long
    lTotalBytes As Long
    lTotalManaged As Long
    lWorkingSet As Long
    lWorkingSetBytes As Long
End Type

メンバ

bThrashing
スラッシング 状態。最後のフレームでスラッシングが発生した場合は TRUE、発生しなかった場合は FALSE になる。
lLastPri
最後に削除するテクスチャの優先順位。
lNumEvicts
最後のフレームで削除されたテクスチャの数。
lNumTexturesUsed
最後のフレームで使用されたテクスチャの総数。
lNumUsedTexInVid
最後のフレームで使用されえたビデオ メモリ テクスチャの数。
lNumVidCreates
最後のフレームでビデオ メモリに作成されたテクスチャの数。
lTotalBytes
管理下のテクスチャに割り当てられた総バイト数。
lTotalManaged
管理下のテクスチャの総数。
lWorkingSet
ビデオ メモリに現在存在するテクスチャの数。
lWorkingSetBytes
ビデオ メモリに存在するテクスチャに現在割り当てられているバイト数。

注意

lNumUsedTexInVid および lNumTexturesUsed の値を使って、最後のフレームでビデオ メモリ (ローカルまたは非ローカル) に存在するテクスチャが使用された割合 (パーセント) を確認できる。次のコードは、この割合の計算方法を示す。

' この例では、d3dtminfo 変数は、Direct3DDevice7.GetInfo メソッドによって埋め込まれる
' D3DDEVINFO_TEXTUREMANAGER 構造体になる。
Dim lHitRate As Long

' ビデオ メモリに存在するテクスチャが使用されたパーセントを取得する。
lHitRate = (d3dtminfo.lNumUsedTexInVid * 100) / d3dtminfo.lNumTexturesUsed

参照

Direct3DDevice7.GetInfo


D3DDEVINFO_TEXTURING

D3DDEVINFO_TEXTURING 型は、アプリケーションのテクスチャリング アクティビティに関する情報を格納する。この型は、Direct3DDevice7.GetInfo メソッドで使用される。

Type D3DDEVINFO_TEXTURING
  lApproxBytesLoaded As Long
  lNumCreates As Long
  lNumDestroys As Long
  lNumGetDCs As Long
  lNumLoads As Long
  lNumLocks As Long
  lNumPreLoads As Long
  lNumSet As Long
  lNumSetLODs As Long
  lNumSetPriorities As Long
End Type

メンバ

lApproxBytesLoaded
Direct3DDevice7.Load メソッドによってロードされるバイト数 (概数)。
lNumCreates
アプリケーションによって作成されるテクスチャの数。
lNumDestroys
アプリケーションによって破棄 (解放) されるテクスチャの数。
lNumGetDCs
DirectDrawSurface7.GetDC メソッドによってテクスチャ サーフェスのデバイス コンテキストが取得された回数。
lNumLoads
Direct3DDevice7.Load メソッドによってテクスチャがロードされた回数。
lNumLocks
DirectDrawSurface7.Lock メソッドによってテクスチャ サーフェスがロックされた回数。
lNumPreLoads
Direct3DDevice7.PreLoad メソッドによって管理下のテクスチャが明示的にロードされた回数。
lNumSet
Direct3DDevice7.SetTexture メソッドによってテクスチャ ブレンディング ステージにテクスチャが設定された回数。
lNumSetLODs
DirectDrawSurface7.SetLOD メソッドによって最大ミップマップ詳細レベルが設定された回数。
lNumSetPriorities
DirectDrawSurface7.SetPriority メソッドによってテクスチャ管理優先順位が設定された回数。

参照

Direct3DDevice7.GetInfo


D3DLIGHT7

D3DLIGHT7 型は、Direct3DDevice7.SetLight および Direct3DDevice7.GetLight などのメソッドを呼び出すための、光源型を決定する。

Type D3DLIGHT7
    ambient As D3DCOLORVALUE
    attenuation0 As Single
    attenuation1 As Single
    attenuation2 As Single
    diffuse As D3DCOLORVALUE
    direction As D3DVECTOR
    dltType As CONST_D3DLIGHTTYPE
    falloff As Single
    phi As Single
    position As D3DVECTOR
    range As Single
    specular As D3DCOLORVALUE
    theta As Single
End Type

メンバ

ambient
光によって放射されるアンビエント色。このメンバは、D3DCOLORVALUE 型である。
attenuation0、attenuation1 および attenuation2
距離による光の輝度の変化を指定する値 (ディレクショナル ライトは減衰には影響されない)。これらの減衰係数によって光がどのように影響を受けるかについては、「距離の増加によるライトの減衰」を参照すること。これらのメンバの有効値は、0.0 以上である。
diffuse
光によって放射されるディフューズ色。このメンバは、D3DCOLORVALUE 型である。
direction
ワールド空間での光源の範囲。このメンバは、ディレクショナル ライトおよびスポット ライトの場合にのみ意味を持つ。このベクトルは正規化する必要はないが、ゼロでない長さを持たねばならない。
dltType
光源の型。この値は、次の CONST_D3DLIGHTTYPE 列挙のメンバの 1 つになる。
falloff
スポット ライトの内円錐 (theta メンバで指定される角度) と外円錐の外枠 (phi メンバで指定される角度) の間で輝度が減少する。スポット ライトが falloff の値によってどのように影響を受けるかについての詳細は、「スポット ライト フォールオフ モデル」を参照すること。

ライティングに対するフォールオフの影響は微妙である。さらに、フォールオフ曲線を描くと多少の性能上のロスを被る。これらの理由により、多くの開発者はこの値を 0 にセットする。

phi
スポット ライトの外円錐の外側のエッジを定義する角度をラジアン単位で表す。この円錐の外側にある点はスポット ライトでライティングされない。この値は 0 から pi の範囲になければならない。
position
ワールド空間での光源の位置。このメンバは、ディレクショナル ライトにおいては意味がなく、このケースでは無視される。
range
光源の有効距離。このメンバの最大許容値は D3DLIGHT_RANGE_MAX で、FLT_MAX の平方根として定義される。このメンバはディレクショナル ライトには影響しない。
specular
光によって放射されるスペキュラ色。このメンバは、D3DCOLORVALUE 型である。
theta
スポット ライトの内円錐をラジアン単位で表す。つまり、スポット ライトが明瞭に照らす円錐である。この値は 0 から、phi メンバで指定される値の範囲になければならない。

注意

ライティングに関する詳しい情報については、「ライト」を参照すること。


D3DLINEPATTERN

D3DLINEPATTERN 型は、直線パターンを示す。これらの値は、CONST_D3DRENDERSTATETYPE 列挙での D3DRENDERSTATE_LINEPATTERN レンダリング ステートにより使用される。

Type D3DLINEPATTERN
    linePattern Long
    repeatFactor As Long
End Type

メンバ

linePattern
ラインパターンを指定するビット。たとえば、値 1100110011001100 は、ドットラインを生成する。1100110011001100.
repeatFactor
linePattern メンバで指定されている 1 の連続と 0 の連続を繰り返す回数。この反復ファクタは、アプリケーションにライン パターンを「延ばす」ことを可能にする。

注意

線パターンは線の描き方を指定する。線パターンは描き出す始点の位置にかかわらず常に同じである (これはオブジェクトをどうレンダリングするか、すなわちどう透明度を模擬するかに影響する点描と異なる点である)。

線パターンは、線に沿って、オン/オフするピクセルの 16 ピクセルのパターンを指定する。repeatFactor メンバで linePattern に入れる時のピクセルの繰り返し数を指定する。


D3DLVERTEX

D3DLVERTEX 型は、「未トランスフォームライティング済みの頂点」 (色付きのモデル座標) を定義する。アプリケーションは、Direct3D が頂点トランスフォームを処理する場合、この型を使用する必要がある。この型は、ソフトウェア ライトが設定するデータと色だけを格納する。

Type D3DLVERTEX
    color As Long
    specular As Long
    tu As Single
    tv As Single
    x As Single
    y As Single
    z As Single
End Type

メンバ

color および specular
頂点の色とスペキュラ成分を指定する値。
tu および tv
頂点のテクスチャ座標 を指定する値。
x、y および z
頂点のモデル座標を指定する値。

注意

D3DRENDERSTATE_SPECULARENABLE が TRUE の場合、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ成分が追加される。ただし、DirectX 7.0 では、D3DTA_SPECULAR フラグをセットすることにより、テクスチャ色の処理時に適用するスペキュラ成分を割り当てることができる。さらに詳細な情報については、「テクスチャ引数フラグ」を参照すること。

参照

D3DTLVERTEX、D3DVERTEX


D3DMATERIAL7

D3DMATERIAL7 型は、Direct3DDevice7.GetMaterial および Direct3DDevice7.SetMaterial メソッドの呼び出しで、マテリアル プロパティを指定する。

Type D3DMATERIAL7
    ambient As D3DCOLORVALUE
    diffuse As D3DCOLORVALUE
    emissive As D3DCOLORVALUE
    power As Single
    specular As D3DCOLORVALUE
End Type

メンバ

ambient、diffuse、emissive および specular
それぞれ、マテリアルのアンビエント色、ディフューズ色、エミッション色、スペキュラ色を指定する値。これらの値は、D3DCOLORVALUE 型である。
power
スペキュラ ハイライトの鮮明度を指定する値。

注意

マテリアルのためのスペキュラ ハイライトを止めるには、Power メンバを 0 にセットする。スペキュラ色成分の設定を 0 にするだけでは十分ではない。

参照

Direct3DDevice7.GetMaterial、Direct3DDevice7.SetMaterial


D3DMATRIX

D3DMATRIX 型は、Direct3DDevice7.MultiplyTransform、Direct3DDevice7.GetTransform、および Direct3DDevice7.SetTransform などのようなメソッドのための行列を示す。

Type D3DMATRIX
    rc11 As Single
    rc12 As Single
    rc13 As Single
    rc14 As Single
    rc21 As Single
    rc22 As Single
    rc23 As Single
    rc24 As Single
    rc31 As Single
    rc32 As Single
    rc33 As Single
    rc34 As Single
    rc41 As Single
    rc42 As Single
    rc43 As Single
    rc44 As Single
End Type

注意

Direct3D では、射影行列の rc34 要素は負にできない。ユーザーのアプリケーションが、その位置で負の値を使用する必要がある場合には、代わりに射影行列全体を -1 で基準化する必要がある。

参照

Direct3DDevice7.MultiplyTransform、Direct3DDevice7.GetTransform、Direct3DDevice7.SetTransform


D3DPRIMCAPS

D3DPRIMCAPS 型は、それぞれのプリミティブ型の能力を定義する。デバイスの生成時やデバイスの能力を取得するときに使用される。この型は、D3DDEVICEDESC7 型の中のいくつかのメンバを定義する。

Type D3DPrimCaps
    lAlphaCmpCaps As CONST_D3DCAPSCMP
    lDestBlendCaps As CONST_D3DCAPSBLEND
    lMiscCaps As CONST_D3DCAPSMISC
    lRasterCaps As CONST_D3DCAPSRASTER
    lReserved1 As Long
    lShadeCaps As CONST_D3DCAPSSHADE
    lSrcBlendCaps As CONST_D3DCAPSBLEND
    lStippleHeight As Long
    lStippleWidth As Long
    lTextureAddressCaps As CONST_D3DCAPSTEXTUREADDRESS
    lTextureCaps As CONST_D3DCAPSTEXTURE
    lTextureFilterCaps As CONST_D3DCAPSTEXTUREFILTER
    lZCmpCaps As CONST_D3DCAPSCMP
End Type

メンバ

lAlphaCmpCaps
ドライバが実行可能なアルファ テスト比較関数。このメンバが D3DPCMPCAPS_ALWAYS 能力だけ、または D3DPCMPCAPS_NEVER 能力だけしかもっていない場合、ドライバはアルファ テストをサポートしない。それ以外の場合、このフラグにより、アルファ テストをサポートする個々の比較を指定する。このメンバは、CONST_D3DCAPSCMP 列挙の定数の 1 つ以上にすることができる。
lDestBlendCaps
転送先ブレンディング能力を記述する CONST_D3DCAPSBLEND 列挙の値の組み合わせ。
lMiscCaps
このプリミティブの総体的な能力。このメンバは、CONST_D3DCAPSMISC 列挙の値の 1 つ以上にすることができる。
lRasterCaps
ラスタ描画の能力情報。このメンバは、CONST_D3DCAPSRASTER 列挙の定数の 1 つ以上にすることができる。
lReserved1
予約済み。使用不可。
lShadeCaps
デバイスが実行できるシェーディング処理。一般的に、デバイスが与えられたコマンド (D3DOP_TRIANGLE のような) を実行できる場合は、D3DSHADE_FLAT モード (CONST_D3DSHADEMODE 列挙型で指定されるような) をサポートする。このフラグは、グーロー シェーディングとフォン シェーディングをサポートするドライバや、3 つのカラー生成モードにそれぞれサポートされるアルファ色を指定する。アルファ成分が与えられたモードでサポートされない場合、そのモードで生成された色のアルファ値は必ず 255 になる。この数値が、アルファの最大値 (アルファが最強) である。

三角形の色、スペキュラ ハイライト、フォグ、およびアルファ成分には、それぞれ能力フラグがあり、アプリケーションは、そのフラグを使用して、デバイス ドライバがそれらをどのように実装しているかを知ることができる。このフラグは、シェーディング モード、カラー モデル、あるいは色のアルファ成分が混合されるかもしくは点描されるかによって変更される。詳細については、「3D プリミティブ」を参照すること。

このメンバは、CONST_D3DCAPSSHADE 列挙の定数の 1 つ以上にすることができる。

lSrcBlendCaps
転送元ブレンディング能力。このメンバは、転送先ブレンディング能力を記述する CONST_D3DCAPSBLEND 列挙の値の組み合わせにすることができる。
lStippleWidth および lStippleHeight
サポートされた点描の最大幅と高さ (最高 32 × 32 まで)。
lTextureAddressCaps
テクスチャのアドレス能力。このメンバは、CONST_D3DCAPSTEXTUREADDRESS 列挙の定数の 1 つ以上にすることができる。
lTextureCaps
混合テクスチャ マッピング能力。このメンバは、CONST_D3DCAPSTEXTURE 列挙の定数の 1 つ以上にすることができる。
lTextureFilterCaps
テクスチャ マップのフィルタリング能力。一般テクスチャ フィルタリング フラグは、D3DTSS_MAGFILTER、D3DTSS_MINFILTER、または D3DTSS_MIPFILTER テクスチャ ステージ ステートに対して、どのテクスチャ フィルタリング モードがサポートされ、設定可能であるかを反映する。このメンバは、CONST_D3DCAPSTEXTUREFILTER 列挙の一般およびステージ単位テクスチャ フィルタリング定数の任意の組み合わせにすることができる。
lZCmpCaps
ドライバが実行可能な関数を比較する Z バッファ。このメンバは、lAlphaCmpCaps メンバで定義された CONST_D3DCAPSCMP と同じ定数を含むことができる。


D3DRECT

D3DRECT 型は、矩形の定義である。

Type D3DRECT {
    x1 As Long
    x2 As Long
    y1 As Long
    y2 As Long
End Type

メンバ

x1 および y1
矩形の左上隅の座標。
x2 および y2
矩形の右下隅の座標。

参照

Direct3DDevice7.Clear


D3DTLVERTEX

D3DTLVERTEX 型は、「トランスフォーム済みライティング済みの頂点」 (色情報付きスクリーン座標) を定義する。

Type D3DTLVERTEX
    color As Long
    rhw As Single
    specular As Long
    sx As Single
    sy As Single
    sz As Single
    tu As Single
    tv As Single
End Type

メンバ

color および specular
頂点の色およびスペキュラ成分を記述する値。
rhw
同次座標 (x,y,z,w) の同次 w の逆数。この値は、原点からオブジェクトまでの z 軸に沿った距離で 1 を除算した値にしばしば一致する。
sx、sy および sz
頂点をスクリーン座標で示す値。表示される z 値の範囲内に頂点を置くためには、SZ の取り得る最大値は 1,0 までである。
tu および tv
頂点のテクスチャ座標を示す値。

注意

D3DRENDERSTATE_SPECULARENABLE が True の場合、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ成分が追加される。ただし、DirectX 7.0 では、D3DTA_SPECULAR フラグをセットすることにより、テクスチャ色処理時に適用するスペキュラ成分を割り当てることができる。詳細については、「テクスチャ引数フラグ」を参照すること。

参照

D3DLVERTEX、D3DVERTEX


D3DVECTOR

D3DVECTOR 型は、多くの Direct3D メソッドとタイプのベクトルを定義する。

Type D3DVECTOR
    x As Single
    y As Single
    z As Single
End Type

メンバ

x、y および z
ベクトルを指定する値。

参照

D3DLIGHT7


D3DVERTEX

D3DVERTEX 型は、「未トランスフォーム未ライティングの頂点」を定義する (正規方向ベクトルでのモデル座標)。

Type D3DVERTEX
    nx As Single
    ny As Single
    nz As Single
    tu As Single
    tv As Single
    x As Single
    y As Single
    z As Single
End Type

メンバ

x、y および z
頂点の同次座標を指定する値。
nx、ny および nz
頂点の正規座標を指定する値。
tu および tv
頂点のテクスチャ座標を指定する値。

参照

D3DLVERTEX、D3DTLVERTEX


D3DVERTEXBUFFERDESC

D3DVERTEXBUFFERDESC 型は、頂点バッファ オブジェクトのプロパティを記述する。この型は、Direct3D7.CreateVertexBuffer および Direct3DVertexBuffer7.GetVertexBufferDesc メソッドで使用される。

Type D3DVERTEXBUFFERDESC
    lCaps As CONST_D3DVBCAPSFLAGS
    lFVF As CONST_D3DFVFFLAGS
    lNumVertices As Long
End Type

メンバ

lCaps
頂点バッファを記述し、その頂点バッファが最適化された頂点データを保持できるかどうかを示す能力フラグ。このパラメータは、CONST_D3DVBCAPSFLAGS 列挙の定数の任意の組み合わせにすることができる。
lFVF
このバッファ内の頂点の頂点フォーマットを記述する CONST_D3DFVFFLAGS 列挙の定数の組み合わせ。
lNumVertices
この頂点バッファが保持できる頂点の数の最大値。

注意

ソフトウェア デバイス (MMX デバイスおよび RGB デバイス) は、ローカルであるか非ローカルであるかにかかわらず、ビデオ メモリの頂点バッファからレンダリングすることはできない。ソフトウェア デバイスを使用して頂点バッファをレンダリングするには、頂点バッファがシステム メモリに存在しなければならない。ハードウェア デバイスは、システム メモリまたはビデオ メモリのどちらの頂点バッファからでも、レンダリングすることができる。

参照

頂点バッファの記述、頂点バッファ


D3DVIEWPORT7

D3DVIEWPORT7 型は、3D ボリュームが射影する、レンダリング ターゲット サーフェスのウィンドウ サイズを定義する。この型は、Direct3DDevice7.GetViewport および Direct3DDevice7.SetViewport メソッドで使用される。

Type D3DVIEWPORT7
    lHeight As Long
    lWidth As Long
    lX As Long
    lY As Long
    maxz As Single
    minz As Single
End Type

メンバ

lHeight および lWidth
レンダリングの対象となるサーフェス上のビューポートの大きさをピクセル単位で表す。サーフェスのサブセットに限定してレンダリングするのでなければ、これらのメンバにはレンダリングの対象サーフェスの大きさをセットする。
lX および lY
レンダリングの対象となるサーフェス上のビューポートの左上隅を表すピクセル座標。サーフェスのサブセットにレンダリングするのでなければ、これらのメンバは、ゼロにセットしてよい。
minz および maxz
シーンをレンダリングする深度の範囲を示す値 (DirectX 7.0 では、射影行列の値によって深度ベースのクリッピングを行うので注意する)。ほとんどのアプリケーションでは、これらの値を 0.0 と 1.0 に設定するが、両方とも 0.0 に設定して、シーンの前面でオブジェクトをレンダリングすることもできる。DirectX 7.0 では、射影行列を適用した後でクリッピングが行われる。詳細については、「クリッピング ボリューム」と「射影トランスフォーム」を参照すること。

注意

lX、lY、lWidth および lHeight メンバは、レンダリングの対象となるサーフェス上のビューポートの位置と大きさを記述する。通常、アプリケーションは対象となるサーフェス全体のレンダリングを実行するので、640Χ480 のサーフェスでレンダリングを行う場合には、これらのメンバはそれぞれ 0、0、640、480 の値を取る。minz と maxz は通常 0.0 と 1.0 に設定されるが、それ以外の値に設定して特殊なエフェクトを生成することもできる。たとえば、これらの値を両方とも 0.0 に設定すると、シーンの前面でオブジェクトがレンダリングされ、両方とも 1.0 に設定すると、背面でレンダリングされる。

Direct3DDevice7.SetViewport メソッドによってデバイスのビューポート パラメータを変更した場合、ドライバは新しいトランスフォーム行列を作成する。

参照

Direct3DDevice7.GetViewport、Direct3DDevice7.SetViewport、クリッピング ボリューム、ビューポートとクリッピング


列挙

ここでは、Direct3D 直接モードで使用される以下の列挙について説明する。

  • CONST_D3D
  • CONST_D3DANTIALIASMODE
  • CONST_D3DBLEND
  • CONST_D3DCAPSBLEND
  • CONST_D3DCAPSCMP
  • CONST_D3DCAPSMISC
  • CONST_D3DCAPSRASTER
  • CONST_D3DCAPSSHADE
  • CONST_D3DCAPSTEXTURE
  • CONST_D3DCAPSTEXTUREADDRESS
  • CONST_D3DCAPSTEXTUREFILTER
  • CONST_D3DCLEARFLAGS
  • CONST_D3DCLIPFLAGS
  • CONST_D3DCLIPPLANEFLAGS
  • CONST_D3DCLIPSTATUSFLAGS
  • CONST_D3DCMPFUNC
  • CONST_D3DCOLORMODEL
  • CONST_D3DCULL
  • CONST_D3DDEVICEDESCCAPS
  • CONST_D3DDEVICEDESCFLAGS
  • CONST_D3DDEVINFOID
  • CONST_D3DDPFLAGS
  • CONST_D3DFILLMODE
  • CONST_D3DFOGMODE
  • CONST_D3DFVFCAPSFLAGS
  • CONST_D3DFVFFLAGS
  • CONST_D3DIMERR
  • CONST_D3DLIGHTTYPE
  • CONST_D3DMATERIALCOLORSOURCE
  • CONST_D3DPRIMITIVETYPE
  • CONST_D3DPROCESSVERTICESFLAGS
  • CONST_D3DRENDERSTATESINGLE
  • CONST_D3DRENDERSTATETYPE
  • CONST_D3DSHADEMODE
  • CONST_D3DSTATEBLOCKTYPE
  • CONST_D3DSTENCILCAPSFLAGS
  • CONST_D3DSTENCILOP
  • CONST_D3DTAFLAGS
  • CONST_D3DTEXCOORDINDEXFLAGS
  • CONST_D3DTEXOPCAPSFLAGS
  • CONST_D3DTEXTUREADDRESS
  • CONST_D3DTEXTUREMAGFILTER
  • CONST_D3DTEXTUREMINFILTER
  • CONST_D3DTEXTUREMIPFILTER
  • CONST_D3DTEXTUREOP
  • CONST_D3DTEXTURESTAGESINGLE
  • CONST_D3DTEXTURESTAGESTATETYPE
  • CONST_D3DTEXTURETRANSFORMFLAGS
  • CONST_D3DTRANSFORMSTATETYPE
  • CONST_D3DVBCAPSFLAGS
  • CONST_D3DVERTEXBLENDFLAGS
  • CONST_D3DVOPFLAGS
  • CONST_D3DVTXPCAPS
  • CONST_D3DZBUFFERTYPE


CONST_D3D

CONST_D3D 列挙は、さまざまな定数を定義する。

Enum CONST_D3D
    D3DDP_MAXTEXCOORD =8
    D3DRENDERSTATE_WRAPBIAS = 128
    D3DWRAPCOORD_0 = 1
    D3DWRAPCOORD_1 = 2
    D3DWRAPCOORD_2 = 4
    D3DWRAPCOORD_3 = 8
End Enum
D3DDP_MAXTEXCOORD
頂点に使用可能なテクスチャ座標の最大値。
D3DRENDERSTATE_WRAPBIAS
テクスチャ ステージのゼロベースのインデックスに追加して、Direct3DDevice7.SetRenderState および Direct3DDevice7.SetRenderState メソッドで使用するために有効な D3DRENDERSTATE_WRAPn 値を生成する値。
D3DWRAPCOORD_0 through D3DWRAPCOORD_3
指定されたテクスチャの第一、第二、第三、第四ディメンジョンの方向 (s、t、r、q 方向とも言う) にラップする。これらの値は、D3DRENDERSTATE_WRAP0 から D3DRENDERSTATE_WRAP7 レンダリング ステートで使用する。


CONST_D3DANTIALIASMODE

CONST_D3DANTIALIASMODE 列挙は、CONST_D3DRENDERSTATETYPE 列挙の D3DRENDERSTATE_ANTIALIAS 値に対して、サポートされているアンチエイリアシング モードを定義する。これらの値は、プリミティブのエッジ アンチエイリアシングに対する設定値を定義する (詳細については、「アンチエイリアシング」を参照すること)。

Enum CONST_D3DANTIALIASMODE
    D3DANTIALIAS_NONE          = 0
    D3DANTIALIAS_SORTDEPENDENT = 1
    D3DANTIALIAS_SORTINDEPENDENT = 2
End Enum
D3DANTIALIAS_NONE
アンチエイリアシングは実行されない。これがデフォルト設定である。
D3DANTIALIAS_SORTDEPENDENT
アンチエイリアシングは、ポリゴンのソート順 (後方から前方、あるいは前方から後方) に依存する。アプリケーションは、アンチエイリアシングが生じることに備え、正しい順序でポリゴンを作図しなければならない。
D3DANTIALIAS_SORTINDEPENDENT
アンチエイリアシングは、ポリゴンのソート順に依存しない。


CONST_D3DBLEND

CONST_D3DBLEND 列挙は、CONST_D3DRENDERSTATETYPE 列挙の D3DRENDERSTATE_DESTBLEND 値に対して、サポートされているブレンディング モードを定義する。以下のメンバの説明では、ソースとディスティネーションの RGBA 値は、添え字の s および d によって示される。

Enum CONST_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
End Enum
D3DBLEND_ZERO
ブレンディング係数は、(0, 0, 0, 0)。
D3DBLEND_ONE
ブレンディング係数は、(1, 1, 1, 1)。
D3DBLEND_SRCCOLOR
ブレンディング係数は、(Rs, Gs, Bs, As)。
D3DBLEND_INVSRCCOLOR
ブレンディング係数は、(1-Rs, 1-Gs, 1-Bs, 1-As)。
D3DBLEND_SRCALPHA
ブレンディング係数は、(As, As, As, As)。
D3DBLEND_INVSRCALPHA
ブレンディング係数は、(1-As, 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
サポートされていない。
D3DBLEND_BOTHINVSRCALPHA
ソース ブレンディング係数は、(1-As, 1-As, 1-As, 1-As)。デスティネーション ブレンディング係数は、(As, As, As, As)。デスティネーション混合節は、無効となる。

注意

DirectX 6.0 以降のDirect3D では、D3DBLEND_BOTHSRCALPHA はサポートされていない。D3DBLEND_SRCALPHA と D3DBLEND_INVSRCALPHA を個別に設定する必要がある。


CONST_D3DCAPSBLEND

CONST_D3DCAPSBLEND 列挙は、デバイスのブレンディング能力を定義する。これらの値は、D3DPRIMCAPS 型の lSrcBlendCaps および lDestBlendCaps メンバで使用される。

Enum CONST_D3DCAPSBLEND
    D3DPBLENDCAPS_BOTHINVSRCALPHA =4096
    D3DPBLENDCAPS_BOTHSRCALPHA =2048
    D3DPBLENDCAPS_DESTALPHA =64
    D3DPBLENDCAPS_DESTCOLOR =256
    D3DPBLENDCAPS_INVDESTALPHA =128
    D3DPBLENDCAPS_INVDESTCOLOR =512
    D3DPBLENDCAPS_INVSRCALPHA =32
    D3DPBLENDCAPS_INVSRCCOLOR =8
    D3DPBLENDCAPS_ONE =2
    D3DPBLENDCAPS_SRCALPHA =16
    D3DPBLENDCAPS_SRCALPHASAT =1024
    D3DPBLENDCAPS_SRCCOLOR =4
    D3DPBLENDCAPS_ZERO =1
End Enum
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)。


CONST_D3DCAPSCMP

CONST_D3DCAPSCMP 列挙は、深度バッファ比較とアルファ テスティングの比較能力を定義する。これらのフラグは、D3DPRIMCAPS 型の lZCmpCaps および lAlphaCmpCaps メンバで使用される。

Enum CONST_D3DCAPSCMP
    D3DPCMPCAPS_ALWAYS = 128
    D3DPCMPCAPS_EQUAL = 4
    D3DPCMPCAPS_GREATER = 16
    D3DPCMPCAPS_GREATEREQUAL = 64
    D3DPCMPCAPS_LESS = 2
    D3DPCMPCAPS_LESSEQUAL = 8
    D3DPCMPCAPS_NEVER = 1
    D3DPCMPCAPS_NOTEQUAL = 32
End Enum
D3DPCMPCAPS_ALWAYS
常に比較を通す。
D3DPCMPCAPS_EQUAL
新規の値が現在の値と等しい場合、比較を通す。
D3DPCMPCAPS_GREATER
新規の値が現在の値より大きい場合、比較を通す。
D3DPCMPCAPS_GREATEREQUAL
新規の値が現在の値より大きいか等しい場合、比較を通す。
D3DPCMPCAPS_LESS
新規の値が現在の値より小さい場合、比較を通す。
D3DPCMPCAPS_LESSEQUAL
新規の値が現在の値より小さいか等しい場合、比較を通す。
D3DPCMPCAPS_NEVER
常に比較は失敗する。
D3DPCMPCAPS_NOTEQUAL
新規の値が現在の値と異なる場合、比較を通す。


CONST_D3DCAPSMISC

CONST_D3DCAPSMISC 列挙は、D3DPRIMCAPS 型の lMiscCaps メンバで使用される能力フラグを定義する。

Enum CONST_D3DCAPSMISC
    D3DPMISCCAPS_CONFORMANT = 8
    D3DPMISCCAPS_CULLCCW = 64
    D3DPMISCCAPS_CULLCW = 32
    D3DPMISCCAPS_CULLNONE = 16
    D3DPMISCCAPS_LINEPATTERNREP = 4
    D3DPMISCCAPS_MASKPLANES = 1
    D3DPMISCCAPS_MASKZ = 2
End Enum
D3DPMISCCAPS_CONFORMANT
デバイスは、OpenGL 標準に準じている。
D3DPMISCCAPS_CULLCCW
ドライバは、D3DRENDERSTATE_CULLMODE ステートで選択した左回りをサポートする (三角形のプリミティブの場合のみ)。CONST_D3DCULL 列挙の D3DCULL_CCW 定数に対応する。
D3DPMISCCAPS_CULLCW
デバイスは、D3DRENDERSTATE_CULLMODE ステートで選択した右回りの三角形をサポートする (三角形のプリミティブの場合のみ)。CONST_D3DCULL 列挙のD3DCULL_CW 定数に対応する。
D3DPMISCCAPS_CULLNONE
デバイスは、選択している三角形を実行できない。CONST_D3DCULL 列挙の D3DCULL_NONE 定数に対応する。
D3DPMISCCAPS_LINEPATTERNREP
使用しない。
D3DPMISCCAPS_MASKPLANES
デバイスは、色のビットマスクを実行できる。
D3DPMISCCAPS_MASKZ
デバイスは、ピクセル操作の深度バッファ変更を有効にしたり、無効にしたりできる。


CONST_D3DCAPSRASTER

CONST_D3DCAPSRASTER 列挙は、D3DPRIMCAPS 型の lRasterCaps メンバで使用される能力フラグを定義する。

Enum CONST_D3DCAPSRASTER
    D3DPRASTERCAPS_ANISOTROPY = 131072
    D3DPRASTERCAPS_ANTIALIASEDGES = 4096
    D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT = 1024
    D3DPRASTERCAPS_DITHER= 1
    D3DPRASTERCAPS_FOGRANGE = 65536
    D3DPRASTERCAPS_FOGTABLE = 256
    D3DPRASTERCAPS_FOGVERTEX = 128
    D3DPRASTERCAPS_MIPMAPLODBIAS = 8192
    D3DPRASTERCAPS_PAT = 8
    D3DPRASTERCAPS_ROP2 = 2
    D3DPRASTERCAPS_STIPPLE = 512
    D3DPRASTERCAPS_SUBPIXEL= 32
    D3DPRASTERCAPS_SUBPIXELX = 64
    D3DPRASTERCAPS_XOR = 4
    D3DPRASTERCAPS_ZBIAS = 16384
    D3DPRASTERCAPS_ZBUFFERLESSHSR = 32768
    D3DPRASTERCAPS_ZTEST = 16
End Enum
D3DPRASTERCAPS_ANISOTROPY
デバイスは非等方性 (anisotropic) フィルタリングをサポートする。
D3DPRASTERCAPS_ANTIALIASEDGES
デバイスは、オブジェクトの輪郭線が凸状になるようなアンチエイリアス線を作ることができる。
D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT
デバイスは、ポリゴンのソート順 (後方から前方、または前方から後方) に依存するアンチエイリアシングをサポートする。アプリケーションは、アンチエイリアシングが生じることに備え、正しい順序でポリゴンを作図しなければならない。詳細については、CONST_D3DANTIALIASMODE 列挙の項を参照すること。
D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT
デバイスは、ポリゴンのソート順によらないアンチエイリアシングをサポートする。詳細については、CONST_D3DANTIALIASMODE 列挙の項を参照すること。
D3DPRASTERCAPS_DITHER
デバイスは、色の再現力を良くするためにディザ表示できる。
D3DPRASTERCAPS_FOGRANGE
デバイスは範囲ベースのフォグをサポートする。範囲ベースのフォグでは、シーンにおけるオブジェクトの深さ (z 座標) ではなく、オブジェクトのビューアからの距離でフォグ エフェクトを計算する。詳細については、「範囲ベースのフォグ」を参照すること。
D3DPRASTERCAPS_FOGTABLE
デバイスは、ピクセルの深さを指すフォグ値をトランスフォームする取得テーブルと照合して、フォグ値を算出する。
D3DPRASTERCAPS_FOGVERTEX
デバイスはライティング処理の間フォグ値を計算し、D3DTLVERTEX 型の specular メンバで与えられた値のアルファ成分中の値に置き換え、ラスタの間フォグ値を補間する。
D3DPRASTERCAPS_MIPMAPLODBIAS
デバイスは詳細レベル (LOD) バイアス調整をサポートする。これらのバイアス調整で、アプリケーションがミップマップを普通よりもすっきりとあるいはあまり鋭くなく見せることができるようになる。ミップマップでの LOD バイアスの詳細については、D3DTSS_MIPMAPLODBIAS を参照すること。
D3DPRASTERCAPS_PAT
ドライバは、プリミティブ用に照会されるパターン描画を処理できる。
D3DPRASTERCAPS_ROP2
デバイスは、R2_COPYPEN 以外のラスタ化をサポートできる。
D3DPRASTERCAPS_STIPPLE
デバイスは、半透明をシミュレートするポリゴンを点描できる。
D3DPRASTERCAPS_SUBPIXEL
デバイスは、一番近い整数型のピクセル座標でなく、Z、色、テクスチャのデータのサブピクセル配置で処理する。これは、Z のブリード線を避けるのを助ける (色のジッタとピクセルのテクスチャ値も)。これらは、有効としたり無効としたりできない (デバイスは、サブピクセル配置を実行したり、しなかったりする)。このビットは、レンダリングの質を決定することのできる Direct3D クライアントに提供される。
D3DPRASTERCAPS_SUBPIXELX
デバイスは、X 軸に沿ったサブ ピクセル配置であり、整数型の Y 軸の走査線を積み上げたものである。
D3DPRASTERCAPS_WBUFFER
デバイスは w 準拠の深度バッファリングをサポートする。詳細については、「深度バッファ」を参照すること。
D3DPRASTERCAPS_WFOG
デバイスは w 準拠のフォグをサポートする。w 準拠のフォグはパースペクティブ射影行列が指定された場合に使用されるが、アフィン射影では現在でも z 準拠フォグを使用する。システムは、[3][4] 要素がゼロ以外の値を持つ射影行列をパースペクティブ射影行列であるとみなす。
D3DPRASTERCAPS_XOR
デバイスは、排他的論理和 (XOR) GDI ラスタ化をサポートする。このフラグが設定されず、D3DPRIM_RASTER_ROP2 が設定されている場合は、排他的論理和処理がサポートされていなければならない。
D3DPRASTERCAPS_ZBIAS
デバイスは z バイアス値をサポートする。これらは平面を共有するポリゴンを別のものに見せるよう、ポリゴンに割り当てられた整数値である。詳細については、CONST_D3DRENDERSTATETYPE 列挙の「D3DRENDERSTATE_ZBIAS」を参照のこと。
D3DPRASTERCAPS_ZBUFFERLESSHSR
デバイスは、隠れサーフェスの除去 (HRS) を実行可能であり、このとき、ポリゴンのソートや、深度バッファの割り付けを必要としない。これにより、より多くのビデオ メモリをテクスチャ用に使うことができる。隠れサーフェス除去に使用するメソッドはハードウェアの機能に依存し、アプリケーション透過である。

Z バッファなしの HRS が実行されるのは、レンダリングの対象となるサーフェスに深度バッファがアタッチされておらず、かつ、深度バッファの比較テストが有効化されている場合 (つまり、D3DRENDERSTATE_ZENABLE 列挙定数に付随するステート値が TRUE にセットされている場合) である。

D3DPRASTERCAPS_ZTEST
デバイスは Z テスト処理を実行できる。これは、効果的にプリミティブをレンダリングし、レンダリングされたどのような Z ピクセルでも表示する。


CONST_D3DCAPSSHADE

CONST_D3DCAPSSHADE 列挙は、D3DPRIMCAPS 型の lShadeCaps メンバで使用されるポリゴン シェーディング能力フラグを定義する。

Enum CONST_D3DCAPSSHADE
    D3DPSHADECAPS_ALPHAFLATBLEND = 4096
    D3DPSHADECAPS_ALPHAFLATSTIPPLED = 8192
    D3DPSHADECAPS_ALPHAGOURAUDBLEND = 16384
    D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED = 32768
    D3DPSHADECAPS_ALPHAPHONGBLEND = 65536
    D3DPSHADECAPS_ALPHAPHONGSTIPPLED = 131072
    D3DPSHADECAPS_COLORFLATMONO = 1
    D3DPSHADECAPS_COLORFLATRGB = 2
    D3DPSHADECAPS_COLORGOURAUDMONO = 4
    D3DPSHADECAPS_COLORGOURAUDRGB = 8
    D3DPSHADECAPS_COLORPHONGMONO = 16
    D3DPSHADECAPS_COLORPHONGRGB = 32
    D3DPSHADECAPS_FOGFLAT = 262144
    D3DPSHADECAPS_FOGGOURAUD = 524288
    D3DPSHADECAPS_FOGPHONG = 1048576
    D3DPSHADECAPS_SPECULARFLATMONO = 64
    D3DPSHADECAPS_SPECULARFLATRGB = 128
    D3DPSHADECAPS_SPECULARGOURAUDMONO = 256
    D3DPSHADECAPS_SPECULARGOURAUDRGB = 512
    D3DPSHADECAPS_SPECULARPHONGMONO = 1024
    D3DPSHADECAPS_SPECULARPHONGRGB = 2048
End Enum
D3DPSHADECAPS_ALPHAFLATBLEND
デバイスは、透過的にそれぞれ混合や点描されたフラット (CONST_D3DSHADEMODE 列挙の D3DSHADE_FLAT ステート) のアルファ成分をサポートできる。これらのモードで、1 つの要素のためのアルファ色成分は、要素の最初の頂点の色の一部分として与えられる。
D3DPSHADECAPS_ALPHAFLATSTIPPLED
デバイスは、透過的にそれぞれ混合や点描されたフラット (CONST_D3DSHADEMODE 列挙の D3DSHADE_FLAT ステート) のアルファ成分をサポートできる。これらのモードで、1 つの要素のためのアルファ色成分は、要素の最初の頂点の色の一部分として与えられる。
D3DPSHADECAPS_ALPHAGOURAUDBLEND
デバイスは、透過的にそれぞれ混合や点描されたグーロー (CONST_D3DSHADEMODE 列挙の D3DSHADE_GOURAUD ステート) のアルファ成分をサポートできる。これらのモードでは、アルファ色成分は頂点に与えられ、他の色成分と共に補間される。
D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED
デバイスは、透過的にそれぞれ混合や点描されたグーロー (CONST_D3DSHADEMODE 列挙の D3DSHADE_GOURAUD ステート) のアルファ成分をサポートできる。これらのモードでは、アルファ色成分は頂点に与えられ、他の色成分と共に補間される。
D3DPSHADECAPS_ALPHAPHONGBLEND
デバイスは、透過的にそれぞれ混合や点描されたフォン (CONST_D3DSHADEMODE 列挙の D3DSHADE_PHONG ステート) のアルファ成分をサポートできる。これらのモードで、頂点パラメータは赤、緑、青の色成分の光源エフェクトを適用して、ピクセル単位に再評価される。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_ALPHAPHONGSTIPPLED
デバイスは、透過的にそれぞれ混合や点描されたフォン (CONST_D3DSHADEMODE 列挙の D3DSHADE_PHONG ステート) のアルファ成分をサポートできる。これらのモードで、頂点パラメータは赤、緑、青の色成分の光源エフェクトを適用して、ピクセル単位に再評価される。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_COLORFLATMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、色付きフラット シェーディングをサポートできる。これらのモードでは、プリミティブに対する色成分はプリミティブの最初の頂点の色の一部として与えられる。モノクロ ライティング モードで補間される色成分は青だけであり、RGB ライティング モードでは、赤、緑、青の各色成分が補間される。
D3DPSHADECAPS_COLORFLATRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、色付きフラット シェーディングをサポートできる。これらのモードでは、プリミティブに対する色成分はプリミティブの最初の頂点の色の一部として与えられる。モノクロ ライティング モードで補間される色成分は青だけであり、RGB ライティング モードでは、赤、緑、青の各色成分が補間される。
D3DPSHADECAPS_COLORGOURAUDMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、色付きグーロー シェーディングをサポートできる。これらのモードでは、プリミティブに対する色成分は頂点で与えられ、他の色成分と共に面に沿って補間される。モノクロ ライティング モードで補間される色成分は青だけであり、RGB ライティング モードでは、赤、緑、青の各色成分が補間される。
D3DPSHADECAPS_COLORGOURAUDRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、色付きグーロー シェーディングをサポートできる。これらのモードでは、プリミティブに対する色成分は頂点で与えられ、他の色成分と共に面に沿って補間される。モノクロ ライティング モードで補間される色成分は青だけであり、RGB ライティング モードでは、赤、緑、青の各色成分が補間される。
D3DPSHADECAPS_COLORPHONGMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、色付きフォン シェーディングをサポートできる。これらのモードでは、頂点パラメータはピクセル単位に再評価される。光源エフェクトは、RGB モードの赤、緑、青の色成分で適用される。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_COLORPHONGRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのそれぞれについて、色付きフォン シェーディングをサポートできる。これらのモードでは、頂点パラメータはピクセル単位に再評価される。光源エフェクトは、RGB モードの赤、緑、青の色成分で適用される。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_FOGFLAT
デバイスは、フラット、グーロー、フォン モードでフォグをサポートできる。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_FOGGOURAUD
デバイスは、フラット、グーロー、フォン モードでフォグをサポートできる。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_FOGPHONG
デバイスは、フラット、グーロー、フォン モードでフォグをサポートできる。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_SPECULARFLATMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのフラット シェーディングのスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_SPECULARFLATRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのフラット シェーディングのスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_SPECULARGOURAUDMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのグーロー シェーディングのスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_SPECULARGOURAUDRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのグーロー シェーディングのスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_SPECULARPHONGMONO
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのフォン シェーディングのスペキュラ ハイライトをサポートできる。フォン シェーディングは、現在サポートされていない。
D3DPSHADECAPS_SPECULARPHONGRGB
デバイスは、D3DCOLOR_MONO と D3DCOLOR_RGB 色モデルのフォン シェーディングのスペキュラ ハイライトをサポートできる。フォン シェーディングは、現在サポートされていない。


CONST_D3DCAPSTEXTURE

CONST_D3DCAPSTEXTURE 列挙は、D3DPRIMCAPS 型の lTextureCaps メンバで使用されるテクスチャリング能力フラグを定義する。

Enum CONST_D3DCAPSTEXTURE {
    D3DPTEXTURECAPS_ALPHA = 4
    D3DPTEXTURECAPS_BORDER = 16
    D3DPTEXTURECAPS_COLORKEYBLEND = 4096
    D3DPTEXTURECAPS_CUBEMAP = 1024
    D3DPTEXTURECAPS_NONPOW2CONDITIONAL = 256
    D3DPTEXTURECAPS_PERSPECTIVE = 1
    D3DPTEXTURECAPS_POW2 = 2
    D3DPTEXTURECAPS_SQUAREONLY = 32
    D3DPTEXTURECAPS_TRANSPARENCY = 8
End Enum
D3DPTEXTURECAPS_ALPHA
D3DTEX_DECAL と D3DTEX_MODULATE テクスチャ フィルタ モードの RGBA テクスチャをサポートする。この能力が設定されていない場合、RGB テクスチャのみが、これらのモードでサポートされる。このフラグの設定を無視すると、アルファは使用可能な D3DEX_DECAL_MASK、D3DTEX_DECAL_ALPHA、D3DEX_MODULATE_ALPHA フィルタ モードでサポートされる。
D3DPTEXTURECAPS_ALPHAPALETTE
パレットがアルファ情報を含むパレット化テクスチャ サーフェスをサポートする (DDCAPS 型の DDPCAPS_ALPHAを参照)。
D3DPTEXTURECAPS_COLORKEYBLEND
デバイスは、D3DRENDERSTATE_COLORKEYBLENDENABLE レンダリング ステートの使用により、カラー キーのアルファ ブレンディングをサポートする。
D3DPTEXTURECAPS_CUBEMAP
キューブ環境マップをサポートする。
D3DPTEXTURECAPS_BORDER
D3DPTADDRESSCAPS_BORDER に置き換えられた。
D3DPTEXTURECAPS_PERSPECTIVE
パースペクティブ補正がサポートされる。
D3DPTEXTURECAPS_PROJECTED
D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグをサポートする。適用されると、デバイスはトランスフォームされたテクスチャ座標を最後のテクスチャ座標で除算する。
D3DPTEXTURECAPS_NONPOW2CONDITIONAL
2 のべき乗でない大きさのテクスチャを条件付でサポートする。この能力を持つデバイスは、次の条件をすべて満たす場合に、このようなテクスチャを使用できる。
  • テクスチャ ステージのテクスチャ アドレッシング モードが D3DTADDRESS_CLAMP にセットされている。
  • テクスチャ ステージに対するテクスチャ ラッピングが無効になっている (D3DRENDERSTATE_WRAPn がゼロに設定されている)。
  • ミップマップを使用していない (ミップマップ テクスチャは、2 のべき乗の大きさでなければならない)。
D3DPTEXTURECAPS_POW2
このフラグがセットされた場合、ミップマップでないテクスチャはすべて、2 のべき乗で指定された幅と高さを持たなければならない (ミップマップ テクスチャはすべて、2 のべき乗の大きさでなければならないことに注意する)。
D3DPTEXTURECAPS_SQUAREONLY
テクスチャは、すべて正方形でなければならない。
D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE
テクスチャ インデックスは、補間実行前には、テクスチャ サイズに合わせてスケーリングされない。
D3DPTEXTURECAPS_TRANSPARENCY
Texture transparency is supported.透過テクスチャがサポートされる (現在の透過色でないこれらのテクセルのみ描画される)。


CONST_D3DCAPSTEXTUREADDRESS

CONST_D3DCAPSTEXTUREADDRESS 列挙は、D3DPRIMCAPS 型の lTextureAddressCaps メンバで使用されるテクスチャ アドレッシング能力フラグを定義する。

Enum CONST_D3DCAPSTEXTUREADDRESS
    D3DPTADDRESSCAPS_BORDER = 8
    D3DPTADDRESSCAPS_CLAMP = 4
    D3DPTADDRESSCAPS_INDEPENDENTUV = 16
    D3DPTADDRESSCAPS_MIRROR = 2
    D3DPTADDRESSCAPS_WRAP = 1
End Enum
D3DPTADDRESSCAPS_BORDER
デバイスは、D3DTSS_BORDERCOLOR テクスチャ ステージ ステートの指定に従い、[0.0, 1.0] 範囲外の座標に境界色を設定することをサポートする。この性能は、D3DTADDRESS_BORDER テクスチャ アドレッシング モードに対応する。
D3DPTADDRESSCAPS_CLAMP
デバイスは、テクスチャの固定が可能である。
D3DPTADDRESSCAPS_INDEPENDENTUV
デバイスは、テクスチャの U 座標と V 座標のテクスチャ アドレッシング モードを分離できる。この性能は、D3DTSS_ADDRESSU および D3DTSS_ADDRESSV レンダリング ステート値に対応する。
D3DPTADDRESSCAPS_MIRROR
デバイスは、テクスチャの反転が可能である。
D3DPTADDRESSCAPS_WRAP
デバイスは、テクスチャの張り付けが可能である。


CONST_D3DCAPSTEXTUREFILTER

CONST_D3DCAPSTEXTUREFILTER 列挙は、D3DPRIMCAPS 型の lTextureFilterCaps で使用されるテクスチャ フィルタリング能力フラグを定義する。

Enum CONST_D3DCAPSTEXTUREFILTER
    D3DPTFILTERCAPS_LINEAR = 2
    D3DPTFILTERCAPS_LINEARMIPLINEAR = 32
    D3DPTFILTERCAPS_LINEARMIPNEAREST = 16
    D3DPTFILTERCAPS_MAGFAFLATCUBIC = 134217728
    D3DPTFILTERCAPS_MAGFANISOTROPIC = 67108864
    D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC =  268435456
    D3DPTFILTERCAPS_MAGFLINEAR = 16777216
    D3DPTFILTERCAPS_MAGFPOINT = 8388608
    D3DPTFILTERCAPS_MINFANISOTROPIC = 1024
    D3DPTFILTERCAPS_MINFLINEAR = 512
    D3DPTFILTERCAPS_MINFPOINT = 256
    D3DPTFILTERCAPS_MIPFLINEAR = 131072
    D3DPTFILTERCAPS_MIPFPOINT = 65536
    D3DPTFILTERCAPS_MIPLINEAR = 8
    D3DPTFILTERCAPS_MIPNEAREST = 4
    D3DPTFILTERCAPS_NEAREST = 1
End Enum

一般テクスチャ フィルタリング フラグ

D3DPTFILTERCAPS_LINEAR
バイリニア フィルタリング。最も近い座標を持つテクセルを選択した後、4 つの周辺テクセルを使用して重み付き平均を算出し、最終的な色を決定する。これは、拡大と縮小の両方で使用される。拡大か縮小がサポートされている時は、両方がサポートされていなければならない。
D3DPTFILTERCAPS_LINEARMIPLINEAR
ミップマップ間のトライリニア補間。バイリニア フィルタリングを 2 つの最近接ミップマップ間に実行した後、2 色の間を線形的に補間して最終的な色を決定する。
D3DPTFILTERCAPS_LINEARMIPNEAREST
サンプリングされたミップマップの 2 点間の線形補間。2 つの最も近いミップマップ レベルから最近接テクセルを選択した後、その 2 つのテクセル間に線形補間を実行する。
D3DPTFILTERCAPS_MIPLINEAR
バイリニア フィルタリングを結果に適用する、最近接ミップマッピング。最も近い座標を持つ適切なミップマップからテクセルを選択した後、4 つの周辺テクセルを使用して重み付き平均を算出し、最終的な色を決定する。
D3DPTFILTERCAPS_MIPNEAREST
最近接ミップマッピング。目的のピクセル値に最も近い座標を持つ適切なミップマップからテクセルを選択する。
D3DPTFILTERCAPS_NEAREST
ポイント サンプリング。希望のピクセル値に最も近い座標を持つテクセルを使用する。これは、拡大と縮小の両方で使用される。拡大か縮小がサポートされている時は、両方がサポートされていなければならない。

ステージ単位テクスチャ フィルタリング フラグ

D3DPTFILTERCAPS_MAGFAFLATCUBIC
デバイスは、ステージ単位でのテクスチャ拡大のため平面キューブ フィルタリングをサポートする。平面キューブ拡大フィルタは、CONST_D3DTEXTUREMAGFILTER 列挙のメンバ D3DTFG_FLATCUBIC で表される。
D3DPTFILTERCAPS_MAGFANISOTROPIC
デバイスは、ステージ単位でのテクスチャ拡大のため、非等方性フィルタリングをサポートする。非等方性拡大フィルタは、CONST_D3DTEXTUREMAGFILTER 列挙のメンバ D3DTFG_ANISOTROPIC で表される。
D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC
デバイスは、ステージ単位でのテクスチャ拡大のため、ガウス キューブ フィルタリングをサポートする。ガウス キューブ拡大フィルタは、CONST_D3DTEXTUREMAGFILTER 列挙のメンバ D3DTFG_GAUSSIANCUBIC で表される。
D3DPTFILTERCAPS_MAGFLINEAR
デバイスは、ステージ単位でのテクスチャ拡大のため、バイリニア補間フィルタリングをサポートする。バイリニア補間拡大フィルタは、CONST_D3DTEXTUREMAGFILTER 列挙のメンバ D3DTFG_LINEAR で表される。
D3DPTFILTERCAPS_MAGFPOINT
デバイスは、ステージ単位でのテクスチャ拡大のため、ポイント サンプル フィルタリングをサポートする。ポイント サンプル拡大フィルタは、CONST_D3DTEXTUREMAGFILTER 列挙のメンバ D3DTFG_POINT で表される。
D3DPTFILTERCAPS_MINFANISOTROPIC
デバイスは、ステージ単位でのテクスチャ縮小のため、非等方性フィルタリングをサポートする。非等方性縮小フィルタは、CONST_D3DTEXTUREMINFILTER 列挙のメンバ D3DTFN_ANISOTROPIC で表される。
D3DPTFILTERCAPS_MINFLINEAR
デバイスは、ステージ単位でのテクスチャ縮小のため、バイリニア補間フィルタリングをサポートする。バイリニア補間縮小フィルタは、CONST_D3DTEXTUREMINFILTER 列挙のメンバ D3DTFN_LINEAR で表される。
D3DPTFILTERCAPS_MINFPOINT
デバイスは、ステージ単位でのテクスチャ縮小のため、ポイント サンプル フィルタリングをサポートする。ポイント サンプル縮小フィルタは、CONST_D3DTEXTUREMINFILTER 列挙のメンバ D3DTFN_POINT で表される。
D3DPTFILTERCAPS_MIPFLINEAR
デバイスは、ステージ単位でのミップマップのため、トライリニア補間フィルタリングをサポートする。トライリニア補間ミップマップ フィルタは、CONST_D3DTEXTUREMIPFILTER 列挙のメンバ D3DTFP_LINEAR で表される。
D3DPTFILTERCAPS_MIPFPOINT
デバイスは、ステージ単位でのミップマップのため、ポイント サンプル フィルタリングをサポートする。ポイント サンプル ミップマップ フィルタは、CONST_D3DTEXTUREMIPFILTER 列挙のメンバ D3DTFP_POINT で表される。


CONST_D3DCLEARFLAGS

CONST_D3DCLEARFLAGS 列挙は、Direct3DDevice7.Clear メソッドの動作を決めるフラグを定義する。

Enum CONST_D3DCLEARFLAGS
    D3DCLEAR_ALL = 7
    D3DCLEAR_STENCIL = 4
    D3DCLEAR_TARGET = 1
    D3DCLEAR_ZBUFFER = 2
End Enum
D3DCLEAR_ALL
レンダリング ターゲット、ステンシル バッファ、および深度バッファ サーフェスをクリアする。
D3DCLEAR_STENCIL
ステンシル バッファをクリアして、stencil パラメータの値にする。
D3DCLEAR_TARGET
レンダリング ターゲットをクリアして、color パラメータの色にする。
D3DCLEAR_ZBUFFER
深度バッファをクリアして、ｚ パラメータの値にする。


CONST_D3DCLIPFLAGS

CONST_D3DCLIPFLAGS 列挙は、Direct3DDevice7.ComputeSphereVisibility メソッドによって返されるクリッピング フラグを定義する。

Enum CONST_D3DCLIPFLAGS
    D3DSTATUS_CLIPINTERSECTIONALL = 17891328
    D3DSTATUS_CLIPUNIONALL = 17891328
    D3DSTATUS_DEFAULT = 34668544
    D3DSTATUS_ZNOTVISIBLE = 16777216
    D3DSTATUS_CLIPINTERSECTIONBACK = 131072
    D3DSTATUS_CLIPINTERSECTIONBOTTOM = 32768
    D3DSTATUS_CLIPINTERSECTIONFRONT = 65536
    D3DSTATUS_CLIPINTERSECTIONGEN0 = 262144
    ' D3DSTATUS_CLIPINTERSECTIONGEN1 to D3DSTATUS_CLIPINTERSECTIONGEN4
    ' omitted here for brevity.
    D3DSTATUS_CLIPINTERSECTIONGEN5 = 8388608
    D3DSTATUS_CLIPINTERSECTIONLEFT = 4096
    D3DSTATUS_CLIPINTERSECTIONRIGHT = 8192
    D3DSTATUS_CLIPINTERSECTIONTOP = 16384
    D3DSTATUS_CLIPUNIONBACK = 32
    D3DSTATUS_CLIPUNIONBOTTOM = 8
    D3DSTATUS_CLIPUNIONFRONT = 16
    D3DSTATUS_CLIPUNIONGEN0 = 64
    ' D3DSTATUS_CLIPUNIONGEN1 to D3DSTATUS_CLIPUNIONGEN4
    ' omitted here for brevity.
    D3DSTATUS_CLIPUNIONGEN5 = 2048
    D3DSTATUS_CLIPUNIONLEFT = 1
    D3DSTATUS_CLIPUNIONRIGHT = 2
    D3DSTATUS_CLIPUNIONTOP = 4
    D3DCLIP_BACK = 32
    D3DCLIP_BOTTOM = 8
    D3DCLIP_FRONT = 16
    D3DCLIP_GEN0 = 64
    ' D3DCLIP_GEN1 to D3DCLIP_GEN4 omitted here for brevity.
    D3DCLIP_GEN5 = 2048
    D3DCLIP_LEFT = 1
    D3DCLIP_RIGHT = 2
    D3DCLIP_TOP = 4
End Enum

組み合わせと一般フラグ

D3DSTATUS_CLIPINTERSECTIONALL
すべての CLIPINTERSECTION フラグの組み合わせ。
D3DSTATUS_CLIPUNIONALL
すべての CLIPUNION フラグの組み合わせ。
D3DSTATUS_DEFAULT
D3DSTATUS_CLIPINTERSECTIONALL と D3DSTATUS_ZNOTVISIBLE フラグの組み合わせ。この値が、デフォルトである。
D3DSTATUS_ZNOTVISIBLE
レンダリングされたプリミティブが不可視であることを示す。このフラグは、z チェックを使うレンダリングが有効化された時点で、システムによりセット、またはクリアされる (D3DRENDERSTATE_ZVISIBLE 参照)。

クリップ交差フラグ

D3DSTATUS_CLIPINTERSECTIONBACK
視錐台の後方クリップ面の頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONBOTTOM
視錐台の下の頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONFRONT
視錐台の前方クリップ面の頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5
アプリケーション定義のクリップ面のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONLEFT
視錐台の左側の頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONRIGHT
視錐台の右側の頂点のクリッピング フラグの論理積をとる。
D3DSTATUS_CLIPINTERSECTIONTOP
視錐台の上の頂点のクリッピング フラグの論理積をとる。

クリップ結合フラグ

D3DSTATUS_CLIPUNIONBACK
D3DCLIP_BACK と同じ。
D3DSTATUS_CLIPUNIONBOTTOM
D3DCLIP_BOTTOM と同じ。
D3DSTATUS_CLIPUNIONFRONT
D3DCLIP_FRONT と同じ。
D3DSTATUS_CLIPUNIONGEN0 through 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 through D3DCLIP_GEN5
すべての頂点を対応するアプリケーション定義クリップ面でクリッピングする。


CONST_D3DCLIPPLANEFLAGS

CONST_D3DCLIPPLANEFLAGS 列挙は、D3DRENDERSTATE_CLIPPLANEENABLE レンダリング ステートで使用されるフラグを定義する。

Type CONST_D3DCLIPPLANEFLAGS
    D3DCPF_DISABLEALL = 0
    D3DCPF_ENABLEPLANE0 = 1
    '
    ' D3DCPF_ENABLEPLANE1 to D3DCPF_ENABLEPLANE30 ommitted here.
    '
    D3DCPF_ENABLEPLANE31 = -2147483648
End Type
D3DCPF_DISABLEALL
すべてのクリップ面を無効にする。このフラグを他のフラグと組み合わせて使用することはできない。
D3DCPF_ENABLEPLANE0 through D3DCPF_ENABLEPLANE31
対応するインデックスにあるクリップ面を有効にする。この値を組み合わせて、複数のクリップ面を同じに有効にすることができる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DCLIPSTATUSFLAGS

CONST_D3DCLIPSTATUSFLAGS 列挙は、D3DCLIPSTATUS 型で使用されるフラグを定義する。

Enum CONST_D3DCLIPSTATUSFLAGS
    D3DCLIPSTATUS_EXTENTS2 = 2
    D3DCLIPSTATUS_EXTENTS3 = 4
    D3DCLIPSTATUS_STATUS = 1
End Enum
D3DCLIPSTATUS_EXTENTS2
型は現在の 2D 領域を記述する。このフラグは D3DCLIPSTATUS_EXTENTS3 と組み合わせることはできない。
D3DCLIPSTATUS_EXTENTS3
現在は実装されていない。
D3DCLIPSTATUS_STATUS
型は現在のクリップ ステータスを記述する。


CONST_D3DCMPFUNC

CONST_D3DCMPFUNC 列挙は、D3DRENDERSTATE_ZFUNC、D3DRENDERSTATE_ALPHAFUNC、および D3DRENDERSTATE_STENCILFUNC レンダリング ステートのためにサポートされる比較関数を定義する。

Enum CONST_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
End Enum
D3DCMP_NEVER
常にテストは失敗する。
D3DCMP_LESS
新しいピクセル値が、現在のピクセル値より小さいときに応じる。
D3DCMP_EQUAL
新しいピクセル値が、現在のピクセル値と等しいときに応じる。
D3DCMP_LESSEQUAL
新しいピクセル値が、現在のピクセル値以下のときに応じる。
D3DCMP_GREATER
新しいピクセル値が、現在のピクセル値より大きいときに応じる。
D3DCMP_NOTEQUAL
新しいピクセル値が、現在のピクセル値と等しくないときに応じる。
D3DCMP_GREATEREQUAL
新しいピクセル値が、現在のピクセル値以上のときに応じる。
D3DCMP_ALWAYS
常にテストはパスする。


CONST_D3DCOLORMODEL

CONST_D3DCOLORMODEL 列挙は、システムが動作するカラー モデルを定義するのに使われる。ドライバはどちらかのフラグ、または両方のフラグを、D3DDEVICEDESC7 型の CONST_COLORMODEL メンバを使って示すことができる。

Enum CONST_D3DCOLORMODEL
    D3DCOLOR_MONO = 1
    D3DCOLOR_RGB = 2
End Enum
D3DCOLOR_MONO
モノクロ モデル (ランプ モデル) を使用する。このモデルで、頂点色の青の値は、頂点の輝度を定義するために使用される。
D3DCOLOR_RGB
完全な RGB モデルを使用する


CONST_D3DCULL

CONST_D3DCULL 列挙は、D3DRENDERSTATE_CULLMODE レンダリング ステートのためにサポートされるカリング モードを定義する。ジオメトリにレンダリングするときの面のカリング方法を定義する。

Enum CONST_D3DCULL
    D3DCULL_NONE = 1
    D3DCULL_CW   = 2
    D3DCULL_CCW  = 3
End Enum
D3DCULL_NONE
カリングはしない。
D3DCULL_CW
右回りにカリングする。
D3DCULL_CCW
左回りにカリングする。

参照

D3DPRIMCAPS、CONST_D3DRENDERSTATETYPE


CONST_D3DDEVICEDESCCAPS

CONST_D3DDEVICEDESCCAPS 列挙は、D3DDEVICEDESC7 型の lDevCaps メンバで使用されるデバイス能力フラグを定義する。

Enum CONST_D3DDEVICEDESCCAPS
    D3DDEVCAPS_CANBLTSYSTONONLOCAL = 131072
    D3DDEVCAPS_CANRENDERAFTERFLIP = 2048
    D3DDEVCAPS_DRAWPRIMTLVERTEX = 1024
    D3DDEVCAPS_FLOATTLVERTEX = 1
    D3DDEVCAPS_HWRASTERIZATION = 524288
    D3DDEVCAPS_HWTRANSFORMANDLIGHT = 65536
    D3DDEVCAPS_SEPARATETEXTUREMEMORIES = 16384
    D3DDEVCAPS_SORTDECREASINGZ = 4
    D3DDEVCAPS_SORTEXACT = 8
    D3DDEVCAPS_SORTINCREASINGZ = 2
    D3DDEVCAPS_TEXTURENONLOCALVIDMEM = 4096
    D3DDEVCAPS_TEXTURESYSTEMMEMORY = 256
    D3DDEVCAPS_TEXTUREVIDEOMEMORY = 512
    D3DDEVCAPS_TLVERTEXSYSTEMMEMORY = 64
    D3DDEVCAPS_TLVERTEXVIDEOMEMORY = 128
End Enum
D3DDEVCAPS_CANBLTSYSTONONLOCAL
デバイスは、システム メモリ テクスチャから非ローカル ビデオ メモリ テクスチャへのブリットをサポートする。
D3DDEVCAPS_CANRENDERAFTERFLIP
デバイスはページ フリップの後で、レンダリング コマンドを待つこともできる。アプリケーションはこのフラグがセットされても、その動作を変えるべきではない。この能力は、単にデバイスが相対的に速いことを意味するのみである。
D3DDEVCAPS_DRAWPRIMTLVERTEX
デバイスは、DrawPrimitive アウェア HAL をエクスポートする。
D3DDEVCAPS_FLOATTLVERTEX
デバイスは、トランスフォーム後の頂点データを浮動小数点で取得する。
D3DDEVCAPS_HWRASTERIZATION
デバイスに、シーンのラスタ化用のハードウェア アクセラレーション機能がある。
D3DDEVCAPS_HWTRANSFORMANDLIGHT
デバイスは、ハードウェアでのトランスフォーム & ライティングをサポートする。
D3DDEVCAPS_SEPARATETEXTUREMEMORIES
デバイスは、ステージごとに別々のテクスチャ メモリ プールを使用する。テクスチャは、生成時に、DDSURFACEDESC2 型の lTextureStage メンバに適切なステージ識別子を設定して、明示的にテクスチャ ステージに割り当てておかなければならない。
D3DDEVCAPS_SORTDECREASINGZ
深度の減少方向にソートされたデータが必要。
D3DDEVCAPS_SORTEXACT
精密にソートされたデータが必要。
D3DDEVCAPS_SORTINCREASINGZ
深度の増加方向にソートされたデータが必要。
D3DDEVCAPS_TEXTURENONLOCALVIDMEM
デバイスは、非ローカル ビデオ (AGP) メモリを取得できる。AGP メモリの詳細は、DirectDraw ドキュメントの「非ローカル ビデオ メモリ サーフェスの使用」を参照すること。
D3DDEVCAPS_TEXTURESYSTEMMEMORY
システム メモリからテクスチャを取得可能。
D3DDEVCAPS_TEXTUREVIDEOMEMORY
デバイス メモリからテクスチャを取得可能。
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY
トランスフォーム済みライティング済みの頂点用に、システム メモリをバッファに使用可能。
D3DDEVCAPS_TLVERTEXVIDEOMEMORY
トランスフォーム済みライティング済みの頂点用に、ビデオ メモリをバッファに使用可能。


CONST_D3DDEVICEDESCFLAGS

CONST_D3DDEVICEDESCFLAGS 列挙は、D3DDEVICEDESC7 型の lFlags メンバで使用されるフラグを定義する。

Enum CONST_D3DDEVICEDESCFLAGS
    D3DDD_BCLIPPING = 16
    D3DDD_DEVCAPS = 2
    D3DDD_DEVICERENDERBITDEPTH = 128
    D3DDD_DEVICEZBUFFERBITDEPTH = 256
    D3DDD_LIGHTINGCAPS = 8
    D3DDD_LINECAPS = 32
    D3DDD_MAXBUFFERSIZE = 512
    D3DDD_MAXVERTEXCOUNT = 1024
    D3DDD_TRANSFORMCAPS = 4
    D3DDD_TRICAPS = 64
End Enum
D3DDD_BCLIPPING
D3DDEVICEDESC7 型の lClipping メンバが有効。
D3DDD_DEVCAPS
D3DDEVICEDESC7 型の lDevCaps メンバが有効。
D3DDD_DEVICERENDERBITDEPTH
D3DDEVICEDESC7 型の lDeviceRenderBitDepth メンバが有効。
D3DDD_DEVICEZBUFFERBITDEPTH
D3DDEVICEDESC7 型の lDeviceZBufferBitDepth メンバが有効。
D3DDD_LIGHTINGCAPS
D3DDEVICEDESC7 型の dlcLightingCaps メンバが有効。
D3DDD_LINECAPS
D3DDEVICEDESC7 型の dpcLineCaps メンバが有効。
D3DDD_MAXBUFFERSIZE
D3DDEVICEDESC7 型の lMaxBufferSize メンバが有効。
D3DDD_MAXVERTEXCOUNT
D3DDEVICEDESC7 型の lMaxVertexCount メンバが有効。
D3DDD_TRANSFORMCAPS
D3DDEVICEDESC7 型の lTransformCaps メンバが有効。
D3DDD_TRICAPS
D3DDEVICEDESC7 型の dpcTriCaps メンバが有効。


CONST_D3DDEVINFOID

CONST_D3DDEVINFOID 列挙は、Direct3DDevice7.GetInfo メソッドで使用されるフラグを定義する。

Enum CONST_D3DDEVINFOID
    D3DDEVINFOID_D3DTEXTUREMANAGER = 2
    D3DDEVINFOID_TEXTUREMANAGER = 1
    D3DDEVINFOID_TEXTURING = 3
End Enum
D3DDEVINFOID_D3DTEXTUREMANAGER
GetInfo メソッドの DevInfoType パラメータにある型は、Direct3D によって実行されるテクスチャ管理の情報を格納する D3DDEVINFO_TEXTUREMANAGER 型である。
D3DDEVINFOID_TEXTUREMANAGER
GetInfo メソッドの DevInfoType パラメータにある型は、ドライバによって実行されるテクスチャ管理の情報を格納する D3DDEVINFO_TEXTUREMANAGER 型である。ドライバがテクスチャを管理しない場合、Direct3D によって実行されるテクスチャ管理の情報が取得される。
D3DDEVINFOID_TEXTURING
GetInfo メソッドの DevInfoType パラメータにある型は、アプリケーションのテクスチャリング アクティビティの情報を格納する D3DDEVINFO_TEXTURING 型である。

参照

Direct3DDevice7.GetInfo


CONST_D3DDPFLAGS

CONST_D3DDPFLAGS 列挙は、Direct3D のレンダリング メソッドの動作を決めるフラグを定義する。これらのフラグは、Direct3DDevice7.DrawPrimitive、Direct3DDevice7.DrawIndexedPrimitive、Direct3DDevice7.DrawPrimitiveVB、および Direct3DDevice7.DrawIndexedPrimitiveVB で使用される。

Enum CONST_D3DDPFLAGS
    D3DDP_DEFAULT = 0
    D3DDP_WAIT = 1
End Enum
D3DDP_DEFAULT
通常のレンダリングを行う (ポリゴンがカードに送られるとすぐに返る)。
D3DDP_WAIT
メソッドは、ポリゴンがカードに送られるとすぐに返るのではなく、レンダリングが終わるまで待つ。(シーン キャプチャ カードでは、カードからの応答があり次第、メソッドは返る)。このフラグはデバッグによく使われる。アプリケーションは、シーンを先に進める前に確実に更新しておくためにも、このフラグを使うべきではない。


CONST_D3DFILLMODE

CONST_D3DFILLMODE 列挙は、塗りつぶしモードを指定する定数を設定する。これらの値は、CONST_D3DRENDERSTATETYPE 列挙の CONST_D3DFILLMODE レンダリング ステートのために使用される。

Enum CONST_D3DFILLMODE
    D3DFILL_POINT     = 1
    D3DFILL_WIREFRAME = 2
    D3DFILL_SOLID     = 3
End Enum
D3DFILL_POINT
点で塗りつぶす。
D3DFILL_WIREFRAME
ワイヤフレームで塗りつぶす。この塗りつぶしモードは、DrawPrimitive メソッド使用時、クリップされたプリミティブでは動作しない。
D3DFILL_SOLID
面で塗りつぶす。


CONST_D3DFOGMODE

CONST_D3DFOGMODE 列挙は、フォグ モードを指定する定数を設定する。これらの値は、CONST_D3DRENDERSTATETYPE 列挙の D3DRENDERSTATE_FOGTABLEMODE および D3DRENDERSTATE_FOGVERTEXMODE レンダリング ステートで使用される。

Enum CONST_D3DFOGMODE
    D3DFOG_NONE   = 0
    D3DFOG_EXP    = 1
    D3DFOG_EXP2   = 2
    D3DFOG_LINEAR = 3
End Enum
D3DFOG_NONE
フォグ エフェクトはない。
D3DFOG_EXP
次の方程式の指数で、フォグ エフェクトが増す。

D3DFOG_EXP2
次の方程式の指数の 2 乗で、フォグ エフェクトが増す。

D3DFOG_LINEAR
次の方程式の始点と終点の間で線形に、フォグ エフェクトが増す。

これは、現在サポートされている唯一のフォグモードである。

注意

モノクロ (ランプ) ライティング モードでは、フォグはその色が黒の場合に限り正常に機能する (ライトが存在しない場合には、すべてのフォグ カラーが機能する。その場合には、すべてのフォグ カラーが実際上は黒だからである)。

フォグの詳細については、「フォグ」を参照すること。

注 : フォグは、透明度を表す基準である。この場合、フォグの値が小さいほど、オブジェクトが見えなくなる。


CONST_D3DFVFCAPSFLAGS

CONST_D3DFVFCAPSFLAGS 列挙は、D3DDEVICEDESC7 型の lFVFCaps メンバで使用される値を定義する。

Enum CONST_D3DFVFCAPSFLAGS
    D3DFVFCAPS_DONOTSTRIPELEMENTS = 524288
    D3DFVFCAPS_TEXCOORDCOUNTMASK = 65535
End Enum
D3DFVFCAPS_DONOTSTRIPELEMENTS
デバイスは、頂点要素のストリップを要求しない。すなわち、頂点フォーマットが、現在のレンダリング ステートで使用されない要素を格納していても、頂点を再生成する必要はない。この能力フラグが存在しない場合、頂点フォーマットから不要な要素を削除すると、パフォーマンスが向上する。
D3DFVFCAPS_TEXCOORDCOUNTMASK
D3DDEVICEDESC7 型の lFVFCaps メンバの下位 16 ビットをマスクするのに使用する。結果を整数型の変数に設定し、デバイスが複数のテクスチャ ブレンディングで同時に使用できるテクスチャ 座標セットの総数を計算する (1 つの頂点に最大 8 つの頂点座標セットを使用できるが、デバイスはブレンディングに指定された数のテクスチャ座標セットしか使用できない)。

注意

以下の Visual Basic コードでは、lFVFCaps メンバの下位 16 ビットをマスクして、デバイスが複数のテクスチャ ブレンディングで同時に使用できるテクスチャ座標セットの総数を指定する。

Dim HALdesc As D3DDEVICEDESC7, HELdesc As D3DDEVICEDESC7
Dim iTexCoords As Integer

' d3ddevice 変数は、有効な Direct3DDevice3 オブジェクトへの
' 参照と見なされる。
Call d3ddevice.GetCaps(HALDesc, HELDesc)

' 下位 16 ビットをマスクして整数型変数に設定する。
iTexCoords = (HALDesc.lFVFCaps And D3DFVFCAPS_TEXCOORDCOUNTMASK)


CONST_D3DFVFFLAGS

CONST_D3DFVFFLAGS 列挙は、DrawPrimitive レンダリング メソッドで使用される柔軟な頂点フォーマット フラグを定義する。詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。


CONST_D3DIMERR

CONST_D3DIMERR 列挙は、システムによって起動されるエラー コードで、不要なものを定義する。これらのエラー コードについては、「エラー コード」を参照すること。


CONST_D3DLIGHTTYPE

CONST_D3DLIGHTTYPE 列挙は、光源の型を示すフラグを定義する。これらのフラグは、D3DLIGHT7 型の lType メンバで使用される。

Enum CONST_D3DLIGHTTYPE
    D3DLIGHT_DIRECTIONAL = 3
    D3DLIGHT_POINT = 1
    D3DLIGHT_SPOT = 2
End Enum
D3DLIGHT_DIRECTIONAL
光源はディレクショナルである。これは無限大の距離で点光源を用いることに等しい。
D3DLIGHT_POINT
光源は点である。光は空間内の点を持ち、全方向に光を放射する。
D3DLIGHT_SPOT
光源はスポット ライトである。この光は、照射が円錐内に制限されている以外は光点に似ている。この光源の型は方向、およびその他の円錐の形を決める数個のパラメータを持つ。これらのパラメータについては、D3DLIGHT7 型を参照すること。


CONST_D3DMATERIALCOLORSOURCE

CONST_D3DMATERIALCOLORSOURCE 列挙は、ライティング計算に使用する色または色成分の位置を定義する。

Enum CONST_D3DMATERIALCOLORSOURCE
    D3DMCS_MATERIAL    = 0
    D3DMCS_COLOR1      = 1
    D3DMCS_COLOR2      = 2
End Enum
D3DMCS_MATERIAL
現在のマテリアルの色を使用する。
D3DMCS_COLOR1
ディフーズ頂点色を使用する。
D3DMCS_COLOR2
スペキュラ頂点色を使用する。

注意

この列挙で定義された値は、D3DRENDERSTATE_DIFFUSEMATERIALSOURCE、D3DRENDERSTATE_SPECULARMATERIALSOURCE、D3DRENDERSTATE_AMBIENTMATERIALSOURCE、および D3DRENDERSTATE_EMISSIVEMATERIALSOURCE レンダリング ステートで使用される。


CONST_D3DPRIMITIVETYPE

CONST_D3DPRIMITIVETYPE 列挙は、DrawPrimitive メソッドでサポートされるプリミティブを列挙する。

Enum CONST_D3DPRIMITIVETYPE
    D3DPT_POINTLIST     = 1
    D3DPT_LINELIST      = 2
    D3DPT_LINESTRIP     = 3
    D3DPT_TRIANGLELIST  = 4
    D3DPT_TRIANGLESTRIP = 5
    D3DPT_TRIANGLEFAN   = 6
End Enum
D3DPT_POINTLIST
頂点を別個の点の集積としてレンダリングする。
D3DPT_LINELIST
別個の線分のリストとして頂点をレンダリングする。このプリミティブ型を使用する呼び出しは、カウントが 2 より小さいか、奇数の場合に失敗に終わる。
D3DPT_LINESTRIP
頂点を単一のポリラインとしてレンダリングする。このプリミティブ型を使用する呼び出しは、カウントが 2 より小さい場合に失敗に終わる。
D3DPT_TRIANGLELIST
別個の三角形の連続として指定の頂点をレンダリングする。各 3 頂点のグループが別個の三角形を定義する。このプリミティブ型を使用する呼び出しは、カウントが 3 より小さい場合、あるいは 3 で割り切れない場合に失敗に終わる。

裏面の選択は、現在のワインディング順レンダリング ステートによって影響される。

D3DPT_TRIANGLESTRIP
頂点を三角形ストリップとしてレンダリングする。このプリミティブ型を使用する呼び出しは、カウントが 3 より小さい場合に失敗に終わる。裏面削除フラグは自動的に、偶数番の三角形上で反転する。
D3DPT_TRIANGLEFAN
頂点を三角形ファンとしてレンダリングする。このプリミティブ型を使用する呼び出しは、カウントが 3 より小さい場合に失敗に終わる。

注意

別個の三角形の連続よりも (重複する頂点の数を減らせるので) 三角形ストリップや扇形を使用した方が効率が良いことが多い。三角形ストリップや扇形の定義に関する概要と詳しい情報については、「三角形ストリップ」と「三角形ファン」を参照すること。

参照

Direct3DDevice7.DrawIndexedPrimitive、Direct3DDevice7.DrawPrimitive、プリミティブの種類


CONST_D3DPROCESSVERTICESFLAGS

CONST_D3DPROCESSVERTICESFLAGS 列挙は、Direct3DVertexBuffer7.ProcessVertices メソッドで使用されるフラグを定義する。

Enum CONST_D3DPROCESSVERTICESFLAGS
    D3DPV_DEFAULT = 0
    D3DPV_DONOTCOPYDATA = 1
End Enum
D3DPV_DEFAULT
現在の頂点操作を使って標準の頂点の処理を行う。
D3DPV_DONOTCOPYDATA
現在の頂点の処理によって影響を受ける頂点データだけを転送先バッファに入れる。

参照

Direct3DVertexBuffer7.ProcessVertices、頂点の処理


CONST_D3DRENDERSTATESINGLE

CONST_D3DRENDERSTATESINGLE 列挙は、Direct3DDevice7.SetRenderStateSingle と Direct3DDevice7.GetRenderStateSingle メソッドによって設定および取得されるデバイス レンダリング ステートを定義する。

Type CONST_D3DRENDERSTATESINGLE
    D3DRENDERSTATE_FOGDENSITY = 38
    D3DRENDERSTATE_FOGEND     = 37
    D3DRENDERSTATE_FOGSTART   = 36
End Type
D3DRENDERSTATE_FOGDENSITY
指数フォグ モード (D3DFOG_EXP と D3DFOG_EXP2) で使用するピクセル フォグのためのフォグ密度。密度の有効な値は 0.0 から 1.0 の範囲内である。デフォルト値は 1,0 である。詳細については、「フォグ パラメータ」を参照すること。
D3DRENDERSTATE_FOGEND
線形フォグ モードで、ピクセル フォグ エフェクトが開始する深度と終了する深度。深度は、頂点フォグの場合はワールド空間で、ピクセル フォグの場合はデバイス空間 [0.0、1.0] またはワールド空間のいずれかで指定する。ピクセル フォグの場合、システムがフォグ計算に ｚ を使用するときにはデバイス空間で、目から相対的なフォグ (w フォグ)を使用するときにはワールド空間で指定する。詳細については、「フォグ パラメータ」と「視点からの相対深度 対 Z ベースの深度」を参照すること。

これらのレンダリング ステートによって、カメラに近い位置のフォグ エフェクトを除外することが可能になる。たとえば、開始深度に 0.3 を設定すると、0.0 から 0.299 の範囲の深度に対するフォグ エフェクトが除外され、終了深度に 0.7 を設定すると、0.701 から 1.0 の範囲の深度に対するフォグ エフェクトが除外される。

D3DRENDERSTATE_FOGSTART
線形フォグ モードで、ピクセル フォグ エフェクトが開始する深度と終了する深度。深度は、頂点フォグの場合はワールド空間で、ピクセル フォグの場合はデバイス空間 [0.0、1.0] またはワールド空間のいずれかで指定する。ピクセル フォグの場合、システムがフォグ計算に ｚ を使用するときにはデバイス空間で、目から相対的なフォグ (w フォグ)を使用するときにはワールド空間で指定する。詳細については、「フォグ パラメータ」と「視点からの相対深度 対 Z ベースの深度」を参照すること。

これらのレンダリング ステートによって、カメラに近い位置のフォグ エフェクトを除外することが可能になる。たとえば、開始深度に 0.3を設定すると、0.0 から 0.299 の範囲の深度に対するフォグ エフェクトが除外され、終了深度に 0.7 を設定すると、0.701 から 1.0 の範囲の深度に対するフォグ エフェクトが除外される。

参照

Direct3DDevice7.SetRenderStateSingle、Direct3DDevice7.GetRenderStateSingle


CONST_D3DRENDERSTATETYPE

CONST_D3DRENDERSTATETYPE 列挙は、Direct3DDevice7.SetRenderState と Direct3DDevice7.GetRenderState メソッドで設定および取得されるデバイス レンダリング ステートを定義する。

Enum CONST_D3DRENDERSTATETYPE
    D3DRENDERSTATE_ALPHABLENDENABLE      = 27
    D3DRENDERSTATE_ALPHAFUNC             = 25
    D3DRENDERSTATE_ALPHAREF              = 24
    D3DRENDERSTATE_ALPHATESTENABLE       = 15
    D3DRENDERSTATE_AMBIENT               = 139
    D3DRENDERSTATE_AMBIENTMATERIALSOURCE = 147
    D3DRENDERSTATE_ANTIALIAS             = 2
    D3DRENDERSTATE_CLIPPING              = 136
    D3DRENDERSTATE_CLIPPLANEENABLE       = 152
    D3DRENDERSTATE_COLORKEYBLENDENABLE   = 144
    D3DRENDERSTATE_COLORKEYENABLE        = 41
    D3DRENDERSTATE_COLORVERTEX           = 141
    D3DRENDERSTATE_CULLMODE              = 22
    D3DRENDERSTATE_DESTBLEND             = 20
    D3DRENDERSTATE_DIFFUSEMATERIALSOURCE = 145
    D3DRENDERSTATE_DITHERENABLE          = 26
    D3DRENDERSTATE_EDGEANTIALIAS         = 40
    D3DRENDERSTATE_EMISSIVEMATERIALSOURCE= 148
    D3DRENDERSTATE_EXTENTS            = 138
    D3DRENDERSTATE_FILLMODE           = 8
    D3DRENDERSTATE_FOGCOLOR           = 34
    D3DRENDERSTATE_FOGENABLE          = 28
    D3DRENDERSTATE_FOGTABLEMODE       = 35
    D3DRENDERSTATE_FOGVERTEXMODE      = 140
    D3DRENDERSTATE_LASTPIXEL          = 16
    D3DRENDERSTATE_LIGHTING           = 137
    D3DRENDERSTATE_LINEPATTERN        = 10
    D3DRENDERSTATE_LOCALVIEWER        = 142
    D3DRENDERSTATE_NORMALIZENORMALS   = 143
    D3DRENDERSTATE_RANGEFOGENABLE     = 48
    D3DRENDERSTATE_SHADEMODE          = 9
    D3DRENDERSTATE_SPECULARENABLE     = 29
    D3DRENDERSTATE_SPECULARMATERIALSOURCE = 146
    D3DRENDERSTATE_SRCBLEND           = 19
    D3DRENDERSTATE_STENCILENABLE      = 52
    D3DRENDERSTATE_STENCILFAIL        = 53
    D3DRENDERSTATE_STENCILFUNC        = 56
    D3DRENDERSTATE_STENCILMASK        = 58
    D3DRENDERSTATE_STENCILPASS        = 55
    D3DRENDERSTATE_STENCILREF         = 57
    D3DRENDERSTATE_STENCILWRITEMASK   = 59
    D3DRENDERSTATE_STENCILZFAIL       = 54
    D3DRENDERSTATE_STIPPLEDALPHA      = 33
    D3DRENDERSTATE_TEXTUREFACTOR      = 60
    D3DRENDERSTATE_TEXTUREPERSPECTIVE = 4
    D3DRENDERSTATE_VERTEXBLEND        = 151
    D3DRENDERSTATE_WRAP0              = 128
    ' Wrap render states 1 through 6 omitted here.
    D3DRENDERSTATE_WRAP7              = 135
    D3DRENDERSTATE_ZBIAS              = 47
    D3DRENDERSTATE_ZENABLE            = 7
    D3DRENDERSTATE_ZFUNC              = 23
    D3DRENDERSTATE_ZVISIBLE           = 30
    D3DRENDERSTATE_ZWRITEENABLE       = 14
End Type
D3DRENDERSTATE_ALPHABLENDENABLE
アルファ ブレンドによる透明化を有効にする場合、TRUE にセットする。デフォルト値は FALSE である。古い D3DRENDERSTATE_BLENDENABLE レンダリング ステートは、このメンバにより置き換えられた。詳細は注意を参照のこと。

D3DRENDERSTATE_COLORKEYENABLE レンダリング ステートを利用して、カラー キー検索の切り替えを実行できる (ハードウェア ラスタライザはいつも D3DRENDERSTATE_BLENDENABLE レンダリング ステートをアルファ ブレンディング切り替え専用に使ってきた)。

アルファ ブレンディングのタイプは D3DRENDERSTATE_SRCBLEND と D3DRENDERSTATE_DESTBLEND レンダリング ステートによって決定される。D3DRENDERSTATE_COLORKEYENABLE と共に D3DRENDERSTATE_ALPHABLENDENABLE を使用すれば、アルファ ブレンディングの微妙なコントロールが可能になる。

アプリケーションは、D3DDEVICEDESC7 型の 3DDEVCAPS_DRAWPRIMTLVERTEX フラグを調べて、このレンダリング ステートがサポートされているかどうかをチェックしなければならない。

D3DRENDERSTATE_ALPHAFUNC
CONST_D3DCMPFUNC 列挙の定数の 1 つ。デフォルト値は D3DCMP_ALWAYS である。このメンバは、アプリケーションにアルファ値を基準とするピクセルの受け取りや受け取り拒否を許可する。
D3DRENDERSTATE_ALPHAREF
アルファ テストが有効に設定されている場合に、ピクセルをテストするための基準アルファ値を指定する値。この値は、0 から 1 の範囲の 16:16 固定小数点値にすることができる (1,0 は 0x00010000 で表される)。デフォルト値は 0,0 である。
D3DRENDERSTATE_ALPHATESTENABLE
アルファ テストを可能にするには、TRUE。デフォルト値は FALSE である。このメンバは、アプリケーションに、アルファ値を基準にしたピクセルの受け取りや受け取り拒否を行うテストの停止を許可する。

入ってくるアルファ値は、D3DRENDERSTATE_ALPHAFUNC レンダリング ステートにより提供される比較関数を用いて参照アルファ値と比較される。このモードが可能になると、テストが成功した場合に限り、アルファ ブレンディングが起きる。

D3DRENDERSTATE_AMBIENT
アンビエント ライトの色。デフォルト値は 0 である。このレンダリング ステートは、従来の D3DLIGHTSTATE_AMBIENT ライティング ステートに似ている。
D3DRENDERSTATE_AMBIENTMATERIALSOURCE
ライティング計算に使用するアンビエント色のソース。有効な値は、CONST_D3DMATERIALCOLORSOURCE 列挙のメンバ。デフォルト値は D3DMCS_COLOR2 である。
D3DRENDERSTATE_ANTIALIAS
フルシーン アンチエイリアシングの要求された型を指定する CONST_D3DANTIALIASMODE 列挙のメンバの 1 つ。デフォルト値は D3DANTIALIAS_NONE である。詳細については、「フルシーン アンチエイリアシング」と「アンチエイリアシング ステート」を参照すること。

フルシーン アンチエイリアシングは、D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT または D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT 能力を示すデバイスに限り、有効にすることができる。

D3DRENDERSTATE_CLIPPING
Direct3D によるプリミティブのクリッピングを可能にする場合はゼロ以外の値、不可にする場合はゼロに設定する。デフォルト値はゼロ以外の値である。
D3DRENDERSTATE_CLIPPLANEENABLE
ユーザー定義のクリップ面を使用可能または不可にする。有効な値は、CONST_D3DCLIPPLANEFLAGS 列挙の値の組み合わせ。指定された列挙の値に対応するクリップ面が使用可能になる。デフォルトの値は D3DCPF_DISABLEALL である。
D3DRENDERSTATE_COLORKEYBLENDENABLE
アルファブレンドによるカラー キーイングを可能にする場合はゼロ以外の値に、不可にする場合はゼロに設定する。アルファブレンドによるカラー キー モードでは、適合するテクスチャ サンプルのアルファと色をゼロに設定する。アプリケーションで、希望通りの破棄またはアルファブレンド結果を得るためには、アルファ テストとアルファ ブレンド モードを設定する必要がある。
D3DRENDERSTATE_COLORKEYENABLE
TRUE は、カラー キー透過を可能にする。デフォルト値は FALSE である。D3DRENDERSTATE_ALPHABLENDENABLE と共にこのレンダリング ステートを使って、微細なブレンディング制御を取り入れることができる。

アプリケーションは、3DDEVICEDESC7 型の D3DDEVCAPS_DRAWPRIMTLVERTEX フラグを調べて、このレンダリング ステートがサポートされているかどうかをチェックする必要がある。

カラー キー透過が有効の場合、DDSD_CKSRCBLT フラグによって作成されたテクスチャ サーフェスだけが影響を受ける。DDSD_CKSRCBLT フラグなしで作成されたサーフェスには、カラー キー透過エフェクトが表れる。

D3DRENDERSTATE_COLORVERTEX
頂点単位カラーを有効にするにはゼロ以外の値に、無効にするにはゼロに設定する。デフォルト値はゼロ以外の値である。頂点単位カラーを使用すると、各頂点に定義されたカラーをライティング計算で使用することができる。

参照「D3DRENDERSTATE_DIFFUSEMATERIALSOURCE」、「D3DRENDERSTATE_SPECULARMATERIALSOURCE」、「D3DRENDERSTATE_AMBIENTMATERIALSOURCE」、および「D3DRENDERSTATE_EMISSIVEMATERIALSOURCE」

D3DRENDERSTATE_CULLMODE
背面を向ける三角形を切り取る必要が生じた場合に、その方法を指定する。この値は、CONST_D3DCULL 列挙の定数の 1 つに設定できる。デフォルト値は D3DCULL_CCW である。
D3DRENDERSTATE_DESTBLEND
CONST_D3DBLEND 列挙の定数の 1 つ。デフォルト値は D3DBLEND_ZERO である。
D3DRENDERSTATE_DIFFUSEMATERIALSOURCE
ライティング計算で使用するディフューズ色のソース。有効な値は、CONST_D3DMATERIALCOLORSOURCE 列挙のメンバ。デフォルト値は D3DMCS_COLOR1 である。このレンダリング ステートの値は、D3DRENDERSTATE_COLORVERTEX レンダリング ステートがゼロ以外の値に設定されている場合のみ使用される。
D3DRENDERSTATE_DITHERENABLE
TRUE のとき、ディザリングを可能とする。デフォルト値は FALSE である。
D3DRENDERSTATE_EDGEANTIALIAS
TRUE は、オブジェクトの凸面の輪郭を形成する線をアンチエイリアスする。デフォルト値は FALSE である。詳細については、「エッジ アンチエイリアシング」と「アンチエイリアシング ステート」を参照すること。TRUE に設定した場合、アプリケーションは、直線のみをレンダリングするべきである。また、レンダリングの対象は、シーン内のポリゴンの外辺に限定する。このレンダリング ステートが設定されていて、三角形または点が描画されると、その動作は不定である。アンチエイリアシングは、単に、隣接するピクセル値の平均値をとることによって実行される。アンチエイリアシングを行うのは最良のやり方ではないが、効率的ではある。この種の操作をサポートするハードウェアは普及しつつある。

エッジ アンチエイリアシングは、D3DPRASTERCAPS_ANTIALIASEDGES 能力を示すデバイスに限り、有効にすることができる。

D3DRENDERSTATE_EMISSIVEMATERIALSOURCE
ライティング計算で使用するエミッション色のソース。有効な値は、CONST_D3DMATERIALCOLORSOURCE 列挙のメンバ。デフォルト値は D3DMCS_MATERIAL である。
D3DRENDERSTATE_EXTENTS
レンダリング呼び出しごとにスクリーン範囲を更新する場合はゼロ以外の値に、更新しない場合はゼロに設定する。デフォルト値はゼロである。
D3DRENDERSTATE_FILLMODE
CONST_D3DFILLMODE 列挙の 1 つ以上の定数。デフォルト値は D3DFILL_SOLID である。
D3DRENDERSTATE_FOGCOLOR
DirectX7.CreateColorRGB メソッドによって返される、RGB 色を示す Long 型の値。デフォルト値は 0 である。詳細については、「フォグ カラー」を参照すること。
D3DRENDERSTATE_FOGENABLE
TRUE はフォグ ブレンディングを可能にする。デフォルト値は FALSE である。詳細については、「フォグ ブレンディング」と「フォグ」を参照すること。

これらのレンダリング ステートによって、カメラに近い位置のフォグ エフェクトを除外することが可能になる。たとえば、開始深度に 0.3 を設定すると、0.0 から 0.299 の範囲の深度に対するフォグエフェクトが除外され、終了深度に 0.7 を設定すると、0.701 から 1.0 の範囲の深度に対するフォグ エフェクトが除外される。

D3DRENDERSTATE_FOGTABLEMODE
ピクセル フォグに使用されるフォグ式。CONST_D3DFOGMODE 列挙の定数の 1 つに設定する。デフォルト値は D3DFOG_NONE である。詳細については、「ピクセル フォグ」を参照すること。
D3DRENDERSTATE_FOGVERTEXMODE
ピクセル フォグに使用されるフォグ式。CONST_D3DFOGMODE 列挙のメンバの 1 つに設定する。デフォルト値は D3DFOG_NONE である。詳細については、「頂点フォグ」を参照すること。
D3DRENDERSTATE_LASTPIXEL
直線や三角形の最後のピクセルを描画可能とするには、FALSE に設定する。デフォルト値は TRUE である。
D3DRENDERSTATE_LIGHTING
Direct3D のライティングを有効にする場合はゼロ以外の値に、無効にする場合はゼロに設定する。デフォルト値はゼロ以外の値である。頂点法線を含む頂点だけが正しく照らされ、法線を含まない頂点はライティング計算で 0 の内積を使用する。
D3DRENDERSTATE_LINEPATTERN
ライン パターン。D3DLINEPATTERN 型によって有効な値を定義する。D3DLINEPATTERN のメンバのデフォルト値は、repeatPattern および linePattern ともに 0 である。
D3DRENDERSTATE_LOCALVIEWER
カメラとの相対角度に依存したスペキュラ ハイライトを有効にする場合はゼロ以外の値に、正スペキュラ ハイライトを使用する場合はゼロに設定する。デフォルト値はゼロで、カメラとの相対角度に依存したスペキュラ ハイライトを使用する。正射影を使用するアプリケーションではゼロに設定する必要がある。
D3DRENDERSTATE_NORMALIZENORMALS
頂点法線の自動正規化を有効にする場合にはゼロ以外の値に、無効にする場合はゼロに設定する。デフォルト値はゼロである。この機能を有効にすると、頂点法線をカメラ空間にトランスフォームした後で、頂点法線を自動的に正規化できる。
D3DRENDERSTATE_RANGEFOGENABLE
範囲準拠の頂点フォグを有効にするには TRUE に設定する (デフォルト値は FALSE で、深度準拠のフォグを使用する)。範囲ベースのフォグでは、シーンにおけるオブジェクトの深さ (z 座標) ではなく、オブジェクトのビューアからの距離でフォグ エフェクトを計算する。範囲ベースのフォグでは、通常すべてのフォグ計算メソッドが動くが、計算に深さでなく範囲を使う点だけが異なる。

範囲はフォグ計算に使うのに正しい要素であるが、範囲が計算上高価となる一方、深さは通常計算済みなので、代って深さが広く使われる。フォグ計算に深さを使うと、周辺のオブジェクトのフォグの様子が目の回転と共に変化するという好ましくない影響がでる。このケースでは、深さは変わるが範囲は一定のままである。

このレンダリング ステートは D3DVERTEX 頂点だけで機能する。D3DLVERTEX または D3DTLVERTEX 頂点を指定すると、RGBF フォグ値の F (フォグ) 要素は、範囲に関して常に修正されなければならない。

現在ピクセル単位での範囲ベースのフォグをサポートするハードウェアはないので、範囲の修正は頂点フォグにのみ提供される。詳細については、「範囲ベースのフォグ」と「頂点フォグ」を参照すること。

D3DRENDERSTATE_SHADEMODE
D3DSHADEMODE 列挙のメンバの 1 つ以上の値。デフォルト値は D3DSHADE_GOURAUD である。
D3DRENDERSTATE_SPECULARENABLE
TRUE はスペキュラ ハイライトを可能にする。デフォルト値は TRUE である。

スペキュラ ハイライトは、光の当たっているオブジェクトの各頂点がそのオブジェクトの原点にあるかのように算出される。これは、オブジェクトが原点の周囲でモデル化され、光源とオブジェクト間の距離が比較的に大きい場合に限り、予測値を与える。

このメンバを TRUE に設定すると、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ色が追加される。

D3DRENDERSTATE_SPECULARMATERIALSOURCE
ライティング計算で使用するスペキュラ色のソース。有効な値は、CONST_D3DMATERIALCOLORSOURCE 列挙のメンバ。デフォルト値は D3DMCS_COLOR2 である。
D3DRENDERSTATE_SRCBLEND
CONST_D3DBLEND 列挙の定数の 1 つ。デフォルト値は D3DBLEND_ONE である。
D3DRENDERSTATE_STENCILENABLE
TRUE の場合はステンシル操作が可能になり、FALSE では無効になる。デフォルト値は FALSE である。詳細については、「ステンシル バッファ」を参照すること。
D3DRENDERSTATE_STENCILFAIL
ステンシル テストに失敗したときに実行するステンシル操作。CONST_D3DSTENCILOP 列挙の定数の 1 つにすることができる。デフォルト値は D3DSTENCILOP_KEEP である。詳細については、「ステンシル バッファ」を参照すること。
D3DRENDERSTATE_STENCILFUNC
ステンシル テストのための比較関数。CONST_D3DCMPFUNC 列挙の定数の 1 つにすることができる。デフォルト値は D3DCMP_ALWAYS である。

比較関数は、ステンシル バッファの要素を基準値と比較するために使われる。この比較は、基準値のビットと、ステンシル マスク (D3DRENDERSTATE_STENCILMASK レンダリング ステートにより設定) に設定されたステンシル バッファ要素にのみ適用される。比較の結果が真であれば、ステンシル テストは成功である。

D3DRENDERSTATE_STENCILMASK
基準値と、それぞれのステンシル バッファ要素に適用し、ステンシル テストのための有効ビットを決定するマスク。デフォルト マスクは 0xFFFFFFFF である。
D3DRENDERSTATE_STENCILPASS
ステンシル テストと深度テスト (z テスト) の両方に成功した場合に実行するステンシル操作。CONST_D3DSTENCILOP 列挙の定数の 1 つにすることができる。デフォルト値は D3DSTENCILOP_KEEP である。詳細については、「ステンシル バッファ」を参照すること。
D3DRENDERSTATE_STENCILREF
ステンシル テストのための整数基準値。デフォルト値は 0 である。
D3DRENDERSTATE_STENCILWRITEMASK
ステンシル バッファに書き込む値に適用する書き込みマスク。デフォルト マスクは 0xFFFFFFFF である。
D3DRENDERSTATE_STENCILZFAIL
ステンシル テストに成功し、深度テスト (z テスト) に失敗した場合に実行するステンシル操作。CONST_D3DSTENCILOP 列挙の定数の 1 つにすることができる。デフォルト値は D3DSTENCILOP_KEEP である。詳細については、「ステンシル バッファ」を参照すること。
D3DRENDERSTATE_STIPPLEDALPHA
TRUE のとき、点描アルファを可能とする。デフォルト値は FALSE である。

現在のソフトウェア ラスタライザは、このレンダリング ステートを無視する。現在のハードウェアがこのレンダリング ステートをサポートするかどうかを調べるには、D3DPRIMCAPS 型の D3DPSHADECAPS_ALPHAFLATSTIPPLED フラグを使う。

D3DRENDERSTATE_TEXTUREFACTOR
D3DTA_TFACTOR テクスチャ ブレンディング引数、または D3DTOP_BLENDFACTORALPHA テクスチャ ブレンディング操作を用いたマルチ テクスチャ ブレンディングで使用される色。
D3DRENDERSTATE_TEXTUREPERSPECTIVE
TRUE のとき、パースペクティブ補正マッピングを可能とする (パースペクティブ補正」を参照すること)。デフォルト値は TRUE である。詳細については、「テクスチャ パースペクティブ ステート」を参照すること。
D3DRENDERSTATE_VERTEXBLEND
ジオメトリ ブレンディングに使用される行列の数。有効な値は、CONST_D3DVERTEXBLENDFLAGS 列挙のメンバ。デフォルト値は D3DVBLEND_DISABLE である。詳細については、「ジオメトリ ブレンディング」を参照すること。
D3DRENDERSTATE_WRAP0 through D3DRENDERSTATE_WRAP7
複数のテクスチャ座標セットを使用する際のテクスチャ ラッピング動作を指定する。これらのレンダリング ステートの有効な値は、CONST_D3D 列挙の D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 フラグの任意の組み合わせこれにより、指定されたテクスチャの第一、第二、第三、第四ディメンジョンの方向 (s、t、r、q 方向とも言う) にラップする。デフォルト値は 0 (すべての方向でラッピング無効) である。詳細については、「テクスチャ ラッピング」を参照すること。
D3DRENDERSTATE_ZBIAS
0 から 16 までの範囲の整数値であり、物理的に同一の面にあるポリゴンが分離して見えるようにする。描画順序のソーティングを行わなくても、高い Z バイアス値を持つポリゴンは、低い値を持つポリゴンよりも手前に見える。たとえば、値 1 を持つポリゴンは、値 0 のポリゴンよりも手前に見える。デフォルト値はゼロである。詳細については、「深度バッファの使用」を参照すること。
D3DRENDERSTATE_ZENABLE
深度バッファリング ステート。CONST_D3DZBUFFERTYPE 列挙の定数の 1 つ。z バッファリングを有効にするには D3DZB_TRUE、w バッファリングを有効にするには D3DZB_USEW、深度バッファリングを無効にするには D3DZB_FALSEを、それぞれ設定する。

レンダリングの対象となるサーフェスに深度バッファがアタッチされている場合、このレンダリング ステートのデフォルト値は D3DZB_TRUE であり、それ以外の場合は D3DZB_FALSE である。

D3DRENDERSTATE_ZFUNC
CONST_D3DCMPFUNC 列挙の定数の 1 つ。デフォルト値は D3DCMP_LESSEQUAL である。このメンバは、アプリケーションにカメラからの距離を基準とするピクセルの受け取りや受け取り拒否を許可する。

ピクセルの深度値を深度バッファの値と比較する。ピクセルの深度値が比較関数で許可された場合にピクセルが書き込まれる。

深度値が深度バッファに書き込まれるのは、レンダリング ステート D3DRENDERSTATE_ZWRITEENABLE が TRUE の場合だけである。

この深度テストに失敗した方が、ソフトウェアによるラスタ化や多くのハードウェア アクセラレータの処理は速くなる。これは、ピクセルのレンダリング処理を行わない場合には、テクスチャをフィルタ処理したり変調したりする必要がなくなるためである。

D3DRENDERSTATE_ZVISIBLE
使用しない。
D3DRENDERSTATE_ZWRITEENABLE
深度バッファへの書き込みを有効にするには TRUE に設定する。デフォルト値は TRUE である。アプリケーションはこのメンバを利用することにより、システムが新しい深度値で深度バッファを更新してしまうのを防ぐことができる。このステートを FALSE に設定すると、レンダリング ステート D3DRENDERSTATE_ZFUNC (深度のバッファリングが行われていると仮定) に従って深度比較は実行されるが、深度値がバッファに書き込まれることはない。

注意

Direct3D は、アプリケーションでの便宜を考慮して、(D3DRENDERSTATE_WRAPn ステート値の 1 つを明示的に使用する代わりに) D3DRENDERSTATE_WRAPBIAS 定数を定義し、テクスチャ座標セットのゼロ始点整数値に基づいて、テクスチャ ラッピングを有効にしたり、無効にしたりする。次の例のように、D3DRENDERSTATE_WRAPBIAS 値をテクスチャ座標セットのゼロベース インデックスに加算して、そのインデックスに対応する D3DRENDERSTATE_WRAPn 値を計算する。

On Local Error Resume Next

' 変数 lIndex のインデックスに対応するテクスチャ座標セットを
' 使用するテクスチャに対して、U/V ラッピングを有効にする。
Call d3dDevice.SetRenderState( _
lIndex + D3DRENDERSTATE_WRAPBIAS, _
D3DWRAPCOORD_0 Or D3DWRAPCOORD_1)

' lIndexが 3 の場合、加算の結果の値は、
' D3DRENDERSTATE_WRAP3 (131) に等しくなる。
If Err.Number <> DD_OK Then
' エラー処理コード
End If


CONST_D3DSHADEMODE

CONST_D3DSHADEMODE 列挙は、CONST_D3DRENDERSTATETYPE 列挙の D3DRENDERSTATE_SHADEMODE レンダリング ステート用に、サポートされるシェーディング モードを指定する。

Enum CONST_D3DSHADEMODE
    D3DSHADE_FLAT         = 1
    D3DSHADE_GOURAUD      = 2
    D3DSHADE_PHONG        = 3
End Enum
D3DSHADE_FLAT
フラット シェーディング モード。三角形の最初の頂点の色が、表面の色を決定するために使われる。この色は三角形全体に対して一定である。すなわち補間されない。
D3DSHADE_GOURAUD
グーロー シェーディング モード。表面の色は、三角形の 3 つの頂点間で、線形補間により決定される。
D3DSHADE_PHONG
フォン シェーディング モード。このモードは、現在サポートされていない。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DSTATEBLOCKTYPE

CONST_D3DSTATEBLOCK 列挙型は、Direct3DDevice7.CreateStateBlock メソッドで使用するために、デバイス ステートの論理グループを定義する。

Type D3DSTATEBLOCKTYPE
    D3DSBT_ALL = 1
    D3DSBT_PIXELSTATE = 2
    D3DSBT_VERTEXSTATE = 3
End Type
D3DSBT_ALL
すべてのデバイス ステートをキャプチャする。
D3DSBT_PIXELSTATE
ピクセル関連のデバイス ステートだけをキャプチャする。
D3DSBT_VERTEXSTATE
頂点関連のデバイス ステートだけをキャプチャする。

注意

D3DSBT_PIXELSTATE と D3DSBT_VERTEXSTATE の両方に属するデバイス ステートもあるが、これらの値は異なる論理グループを示す。各グループに属するステートについては、「事前定義するステート ブロックの作成」を参照すること。

参照

Direct3DDevice7.CreateStateBlock


CONST_D3DSTENCILCAPSFLAGS

CONST_D3DSTENCILCAPSFLAGS 列挙は、D3DDEVICEDESC7 型の lStencilCaps メンバで使用されるステンシル バッファ能力フラグを定義する。

Enum CONST_D3DSTENCILCAPSFLAGS
    D3DSTENCILCAPS_DECR = 128
    D3DSTENCILCAPS_DECRSAT = 16
    D3DSTENCILCAPS_INCR = 64
    D3DSTENCILCAPS_INCRSAT = 8
    D3DSTENCILCAPS_INVERT = 32
    D3DSTENCILCAPS_KEEP = 1
    D3DSTENCILCAPS_REPLACE = 4
    D3DSTENCILCAPS_ZERO = 2
End Enum
D3DSTENCILCAPS_DECR
D3DSTENCILOP_DECR ステンシル バッファ操作をサポートする。
D3DSTENCILCAPS_DECRSAT
D3DSTENCILOP_DECRSAT ステンシル バッファ操作をサポートする。
D3DSTENCILCAPS_INCR
D3DSTENCILOP_INCR ステンシル バッファ操作をサポートする。
D3DSTENCILCAPS_INCRSAT
D3DSTENCILOP_INCRSAT ステンシル バッファ操作をサポートする。
D3DSTENCILCAPS_INVERT
D3DSTENCILOP_INVERT ステンシル バッファ操作をサポートする。
D3DSTENCILCAPS_KEEP
D3DSTENCILOP_KEEP ステンシル バッファ操作をサポートする。
D3DSTENCILCAPS_REPLACE
D3DSTENCILOP_REPLACE ステンシル バッファ操作をサポートする。
D3DSTENCILCAPS_ZERO
D3DSTENCILOP_ZERO ステンシル バッファ操作をサポートする。


CONST_D3DSTENCILOP

D3DSTENCILOP 列挙型は、D3DRENDERSTATE_STENCILFAIL、D3DRENDERSTATE_STENCILZFAIL、および D3DRENDERSTATE_STENCILPASS レンダリング ステートのためのステンシル操作を定義する。

Enum CONST_D3DSTENCILOP
    D3DSTENCILOP_DECR = 8
    D3DSTENCILOP_DECRSAT = 5
    D3DSTENCILOP_INCR = 7
    D3DSTENCILOP_INCRSAT = 4
    D3DSTENCILOP_INVERT = 6
    D3DSTENCILOP_KEEP = 1
    D3DSTENCILOP_REPLACE = 3
    D3DSTENCILOP_ZERO = 2
End Enum
D3DSTENCILOP_DECR
ステンシル バッファ内の項目の値を減少させ、新しい値がゼロ未満になった場合はラッピングして最大値に戻る。
D3DSTENCILOP_DECRSAT
ステンシル バッファ内の項目の値を、ゼロに達するまで減少させる。
D3DSTENCILOP_INCRSAT
ステンシル バッファ内の項目の値を、最大値に達するまで増加させる。ステンシル バッファの最大値に関しては、「注意」を参照すること。
D3DSTENCILOP_INVERT
ステンシル バッファ内の項目のビットを反転する。
D3DSTENCILOP_INCR
ステンシル バッファ内の項目の値を増加させ、最大値を超過した場合はラッピングしてゼロに戻る。ステンシル バッファの最大値に関しては、「注意」を参照すること。
D3DSTENCILOP_KEEP
ステンシル バッファ内の項目を更新しない。これがデフォルト値である。
D3DSTENCILOP_REPLACE
ステンシル バッファ内の項目を基準値で置き換える。
D3DSTENCILOP_ZERO
ステンシル バッファ内の項目をゼロに設定する。

注意

ステンシル バッファ項目は 0 から 2n -1 までの範囲の整数値を取る。ここで、n はステンシル バッファのビット深度である。

参照

CONST_D3DRENDERSTATETYPE、ステンシル バッファ


CONST_D3DTAFLAGS

CONST_D3DTAFLAGS 列挙は、テクスチャ ブレンディング ステージを定義するために使用されるテクスチャ引数フラグを指定する。詳細については、「テクスチャ引数フラグ」を参照すること。


CONST_D3DTEXCOORDINDEXFLAGS

CONST_D3DTEXCOORDINDEXFLAGS 列挙は、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートで設定されたインデックス値と組み合わせて使用される値を定義する。

Type CONST_D3DTEXCOORDINDEXFLAGS
    D3DTSS_TCI_CAMERASPACENORMAL = 65536
    D3DTSS_TCI_CAMERASPACEPOSITION = 131072
    D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR = 196608
    D3DTSS_TCI_PASSTHRU = 0
End Type
D3DTSS_TCI_CAMERASPACENORMAL
このステージのテクスチャ トランスフォームで、入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点法線を使用する。
D3DTSS_TCI_CAMERASPACEPOSITION
このステージのテクスチャ トランスフォームで、入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点位置座標を使用する。
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
このステージのテクスチャ トランスフォームで、入力テクスチャ座標として、カメラ空間にトランスフォームされた反射ベクトルを使用する。反射ベクトルは、入力頂点位置座標と頂点法線によって計算される。
D3DTSS_TCI_PASSTHRU
ベクトル フォーマットに含まれる指定されたテクスチャ座標を使用する。

注意

この列挙の値 (0 になる D3DTSS_TCI_PASSTHRU を除く) は、システムが D3DTSS_TEXCOORDINDEX で設定されたインデックス値をどのように使用するかによって異なる。通常、D3DTSS_TEXCOORDINDEX で設定された値は、テクスチャのアドレス指定に使用されるテクスチャ座標を制御する。ただし、D3DTSS_TCI_CAMERASPACENORMAL、D3DTSS_TCI_CAMERASPACEPOSITION、または D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR 値 (設定されたインデックスとの論理 和) がある場合、システムはこのインデックスをテクスチャ ラッピング モードの指定だけに使用する。

この列挙の値は、環境マッピングのテクスチャ座標を自動生成するアプリケーションで有効である。

参照

テクスチャ座標の自動生成の構成


CONST_D3DTEXOPCAPSFLAGS

CONST_D3DTEXOPCAPSFLAGS 列挙は、D3DDEVICEDESC7 型の lTextureOpCaps メンバで使用されるテクスチャ ブレンディング操作能力を定義する。

Enum CONST_D3DTEXOPCAPSFLAGS
    D3DTEXOPCAPS_ADD = 64
    D3DTEXOPCAPS_ADDSIGNED = 128
    D3DTEXOPCAPS_ADDSIGNED2X = 256
    D3DTEXOPCAPS_ADDSMOOTH = 1024
    D3DTEXOPCAPS_BLENDCURRENTALPHA = 32768
    D3DTEXOPCAPS_BLENDDIFFUSEALPHA = 2048
    D3DTEXOPCAPS_BLENDFACTORALPHA = 8192
    D3DTEXOPCAPS_BLENDTEXTUREALPHA = 4096
    D3DTEXOPCAPS_BLENDTEXTUREALPHAPM = 16384
    D3DTEXOPCAPS_BUMPENVMAP = 2097152
    D3DTEXOPCAPS_BUMPENVMAPLUMINANCE = 4194304
    D3DTEXOPCAPS_DISABLE = 1
    D3DTEXOPCAPS_DOTPRODUCT3 = 8388608
    D3DTEXOPCAPS_MODULATE = 8
    D3DTEXOPCAPS_MODULATE2X = 16
    D3DTEXOPCAPS_MODULATE4X = 32
    D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR = 131072
    D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA = 262144
    D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR = 524288
    D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA = 1048576
    D3DTEXOPCAPS_PREMODULATE = 65536
    D3DTEXOPCAPS_SELECTARG1 = 2
    D3DTEXOPCAPS_SELECTARG2 = 4
    D3DTEXOPCAPS_SUBTRACT = 512
End Enum
D3DTEXOPCAPS_ADD
デバイスは D3DTOP_ADD テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_ADDSIGNED
デバイスは D3DTOP_ADDSIGNED テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_ADDSIGNED2X
デバイスは D3DTOP_ADDSIGNED2X テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_ADDSMOOTH
デバイスは D3DTOP_ADDSMOOTH テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_BLENDCURRENTALPHA
デバイスは D3DTOP_BLENDCURRENTALPHA テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_BLENDDIFFUSEALPHA
デバイスは D3DTOP_BLENDDIFFUSEALPHA テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_BLENDFACTORALPHA
デバイスは D3DTOP_BLENDFACTORALPHA テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_BLENDTEXTUREALPHA
デバイスは D3DTOP_BLENDTEXTUREALPHA テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_BLENDTEXTUREALPHAPM
デバイスは D3DTOP_BLENDTEXTUREALPHAPM テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_BUMPENVMAP
デバイスは D3DTOP_BUMPENVMAP テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_BUMPENVMAPLUMINANCE
デバイスは D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_DISABLE
デバイスは D3DTOP_DISABLE テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_DOTPRODUCT3
デバイスは D3DTOP_DOTPRODUCT3 テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_MODULATE
デバイスは D3DTOP_MODULATE テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_MODULATE2X
デバイスは D3DTOP_MODULATE2X テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_MODULATE4X
デバイスは D3DTOP_MODULATE4X テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR
デバイスは D3DTOP_MODULATEALPHA_ADDCOLOR テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA
デバイスは D3DTOP_MODULATEALPHA_ADDCOLOR テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR
デバイスは D3DTOP_MODULATEINVALPHA_ADDCOLOR テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA
デバイスは D3DTOP_MODULATEINVCOLOR_ADDALPHA テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_PREMODULATE
デバイスは D3DTOP_PREMODULATE テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_SELECTARG1
デバイスは D3DTOP_SELECTARG1 テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_SELECTARG2
デバイスは D3DTOP_SELECTARG2 テクスチャ ブレンディング操作をサポートする。
D3DTEXOPCAPS_SUBTRACT
デバイスは D3DTOP_SUBTRACT テクスチャ ブレンディング操作をサポートする。


CONST_D3DTEXTUREADDRESS

CONST_D3DTEXTUREADDRESS 列挙は、D3DTSS_ADDRESS、D3DTSS_ADDRESSU、および D3DTSS_ADDRESSV テクスチャ ステージ ステートでテクスチャ アドレッシング モードを設定する際に、サポートされるモードを記述する。

Enum CONST_D3DTEXTUREADDRESS
    D3DTADDRESS_WRAP         = 1
    D3DTADDRESS_MIRROR       = 2
    D3DTADDRESS_CLAMP        = 3
    D3DTADDRESS_BORDER       = 4
End Enum
D3DTADDRESS_WRAP
すべての整数接合点でテクスチャを貼り合わせる。たとえば、u の値が 0 から 3 まで変化する範囲でテクスチャは 3 回繰り返される。ミラーリングは行わない。
D3DTADDRESS_MIRROR
すべての整数接合点でテクスチャのフリッピングが起こることを除けば、D3DTADDRESS_WRAP と同様である。u の値が 0 から 1 の範囲でテクスチャは通常の方法でアドレッシングされるが、1 から 2 の範囲ではフリッピング (ミラーリング) が起こり、2 から 3 の範囲では通常のテクスチャに戻る。以後、このパターンが繰り返される。
D3DTADDRESS_CLAMP
範囲 [0.0, 1.0] の外側のテクスチャ座標が、それぞれ、0.0 と 1.0 のテクスチャ色に設定される。
D3DTADDRESS_BORDER
範囲 [0.0, 1.0] の外側のテクスチャ座標が、CONST_D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_BORDERCOLOR テクスチャ ステージ ステートで設定された境界色で描かれる。

参照

CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DTEXTUREMAGFILTER

CONST_D3DTEXTUREMAGFILTER 列挙は、テクスチャ ステージのテクスチャ拡大フィルタリング モードを定義する。

Enum CONST_D3DTEXTUREMAGFILTER
    D3DTFG_POINT        = 1
    D3DTFG_LINEAR       = 2
    D3DTFG_FLATCUBIC    = 3
    D3DTFG_GAUSSIANCUBIC= 4
    D3DTFG_ANISOTROPIC  = 5
End Enum
D3DTFG_POINT
点フィルタリング。希望のピクセル値に最も近い座標を持つテクセルを使用する。
D3DTFG_LINEAR
バイリニア補間フィルタリング。希望のピクセルを囲む 2 Χ 2 領域のテクセルの重み付き平均を使用する。
D3DTFG_FLATCUBIC
現在サポートされていない。使用不可。
D3DTFG_GAUSSIANCUBIC
現在サポートされていない。使用不可。
D3DTFG_ANISOTROPIC
非等方性テクスチャ フィルタリング。テクスチャ ポリゴンとスクリーン平面間の角度の相違により起こる歪みを補正する。

注意

テクスチャ ステージの拡大フィルタを設定する時は、D3DTSS_MAGFILTER 値を第 2 パラメータとし、この列挙のメンバの 1 つを第 3 パラメータとして Direct3DDevice7.SetTextureStageState メソッドを呼び出す。

参照

CONST_D3DTEXTUREMINFILTER、CONST_D3DTEXTUREMIPFILTER、テクスチャ フィルタリング


CONST_D3DTEXTUREMINFILTER

CONST_D3DTEXTUREMINFILTER 列挙は、テクスチャ ステージのテクスチャ縮小フィルタリング モードを定義する。

Enum CONST_D3DTEXTUREMINFILTER
    D3DTFN_POINT        = 1
    D3DTFN_LINEAR       = 2
    D3DTFN_ANISOTROPIC  = 3
End Enum
D3DTFN_POINT
点フィルタリング。希望のピクセル値に最も近い座標を持つテクセルを使用する。
D3DTFN_LINEAR
バイリニア補間フィルタリング。希望のピクセルを囲む 2 × 2 領域のテクセルの重み付き平均を使用する。
D3DTFN_ANISOTROPIC
非等方性テクスチャ フィルタリング。テクスチャ ポリゴンとスクリーン平面間の角度の相違により起こる歪みを補正する。

注意

テクスチャ ステージの拡大フィルタを設定するときは、D3DTSS_MINFILTER 値を第 2 パラメータとし、この列挙のメンバの 1 つを第 3 パラメータとして Direct3DDevice7.SetTextureStageState メソッドを呼び出す。

参照

CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMIPFILTER、テクスチャ フィルタリング


CONST_D3DTEXTUREMIPFILTER

CONST_D3DTEXTUREMIPFILTER 列挙は、テクスチャ ステージのテクスチャ ミップマップ フィルタリング モードを定義する。

Enum CONST_D3DTEXTUREMIPFILTER
    D3DTFP_NONE         = 1
    D3DTFP_POINT        = 2
    D3DTFP_LINEAR       = 3
End Enum
D3DTFP_NONE
ミップマップ処理を無効にする。ラスタライザは代わりに拡大フィルタを使用する。
D3DTFP_POINT
最近点ミップマップ フィルタ。ラスタライザは最も近いミップマップ テクスチャのテクセルからの色を使用する。
D3DTFP_LINEAR
トライリニア ミップマップ補間。ラスタライザは、最も近いミップマップ テクスチャ 2 点からのテクセルを使用してピクセル色を線形補間する。

注意

テクスチャ ステージの拡大フィルタを設定する時は、D3DTSS_MIPFILTER 値を第 2 パラメータとし、この列挙のメンバの 1 つを第 3 パラメータとして Direct3DDevice7.SetTextureStageState メソッドを呼び出す。

参照

CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMIPFILTER、テクスチャ フィルタリング


CONST_D3DTEXTUREOP

CONST_D3DTEXTUREOP 列挙は、ステージ単位テクスチャ ブレンディング操作を定義する。この型の定数は、D3DTSS_COLOROP または D3DTSS_ALPHAOP 値を使用して Direct3DDevice7.SetTextureStageState メソッドを呼び出し、色操作やアルファ操作を設定するときに使われる。

Enum CONST_D3DTEXTUREOP
    D3DTOP_DISABLE    = 1
    D3DTOP_SELECTARG1 = 2
    D3DTOP_SELECTARG2 = 3
    D3DTOP_MODULATE   = 4
    D3DTOP_MODULATE2X = 5
    D3DTOP_MODULATE4X = 6
    D3DTOP_ADD        = 7
    D3DTOP_ADDSIGNED  = 8
    D3DTOP_ADDSIGNED2X  =  9
    D3DTOP_SUBTRACT     = 10
    D3DTOP_ADDSMOOTH    = 11
    D3DTOP_BLENDDIFFUSEALPHA    = 12
    D3DTOP_BLENDTEXTUREALPHA    = 13
    D3DTOP_BLENDFACTORALPHA     = 14
    D3DTOP_BLENDTEXTUREALPHAPM  = 15
    D3DTOP_BLENDCURRENTALPHA    = 16
    D3DTOP_PREMODULATE            = 17
    D3DTOP_MODULATEALPHA_ADDCOLOR = 18
    D3DTOP_MODULATECOLOR_ADDALPHA = 19
    D3DTOP_MODULATEINVALPHA_ADDCOLOR = 20
    D3DTOP_MODULATEINVCOLOR_ADDALPHA = 21
    D3DTOP_BUMPENVMAP           = 22
    D3DTOP_BUMPENVMAPLUMINANCE  = 23
    D3DTOP_DOTPRODUCT3          = 24
End Enum
制御定数
D3DTOP_DISABLE
このテクスチャ ステージ、および、より高いインデックスを持つステージからの出力をすべて無効にする。テクスチャ マッピングを無効にするには、この操作を最初のテクスチャ ステージ (ステージ 0) に対して設定する。色操作が有効のときに、アルファ操作を無効にすることはできない。色ブレンディングが有効のときにアルファ操作を D3DTOP_DISABLE に設定すると、その動作は不定である。
D3DTOP_SELECTARG1
このテクスチャ ステージの最初の色、またはアルファ引数を変更せずに出力として使用する。この操作は、D3DTSS_COLOROP テクスチャ ステージ ステートで使用すると色引数に影響を与え、D3DTSS_ALPHAOP で使用した場合にはアルファ引数に影響を与える。

D3DTOP_SELECTARG2
このテクスチャ ステージの 2 番目の色、またはアルファ引数を変更せずに出力として使用する。この操作は、D3DTSS_COLOROP テクスチャ ステージ ステートで使用すると色引数に影響を与え、D3DTSS_ALPHAOP で使用した場合にはアルファ引数に影響を与える。

変調定数
D3DTOP_MODULATE
引数要素を一緒に乗算する。

D3DTOP_MODULATE2X
引数要素を乗算し、積を左に 1 ビットだけシフト (2 で乗算するのと同じエフェクト) して明るくする。

D3DTOP_MODULATE4X
引数要素を乗算し、積を左に 2 ビットだけシフト (4 で乗算するのと同じエフェクト) して明るくする。

加算および減算定数
D3DTOP_ADD
引数要素を加算する。

D3DTOP_ADDSIGNED
バイアス値 -0.5を引数要素に加算し、値の有効範囲を -0.5 から 0.5 とする。

D3DTOP_ADDSIGNED2X
バイアス値 -0.5 を引数要素に加算し、その結果を左へ 1 ビットだけシフトする。

D3DTOP_SUBTRACT
第 1 引数の要素から、対応する第 2 引数の要素を減算する。

D3DTOP_ADDSMOOTH
第 1 引数と第 2 引数を加算し、次に、第 1 引数と第 2 引数の積を合計値から引き算する。

線形アルファ ブレンディング定数
D3DTOP_BLENDDIFFUSEALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDTEXTUREALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDFACTORALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDCURRENTALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDTEXTUREALPHAPM
あらかじめ乗算処理されたアルファを用いるテクスチャ ステージの、線形ブレンディングを行う。

スペキュラ マッピング定数
D3DTOP_PREMODULATE
現在のテクスチャ ステージと次のテクスチャ ステージの間で変調を行う。
D3DTOP_MODULATEALPHA_ADDCOLOR
第 1 引数のアルファを使用して第 2 引数の色を変調し、その結果を第 1 引数に加算する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATECOLOR_ADDALPHA
引数を変調してから、第 1 引数のアルファを加算する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR に類似しているが、第 1 引数のアルファの逆数を使用するところが異なる。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA に類似しているが、第 1 引数の色の逆数を使用するところが異なる。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

バンプ マッピング定数
D3DTOP_BUMPENVMAP
次のテクスチャ ステージの環境マップ (輝度なし) を使用して、ピクセル単位でバンプ マッピングを実行する。
D3DTOP_BUMPENVMAPLUMINANCE
次のテクスチャ ステージの環境マップ (輝度あり) を使用して、ピクセル単位でバンプ マッピングを実行する。
D3DTOP_DOTPRODUCT3
各引数の要素を (符号付要素として) 変調して積を加算し、得られた合計値をすべての色チャネルに、アルファを含めて複製する。この操作は、色操作 (D3DTSS_COLOROP) でのみサポートされる。

注意

上記の式において、SRGBA はテクスチャ操作で作成される RGBA 色であり、Arg1 と Arg2 はテクスチャ引数の完全な RGBA 色である。引数の個々の要素は、下付き文字を付けて表記される。たとえば、引数 1 のアルファ要素は、Arg1A と表現される。

参照

Direct3DDevice7.GetTextureStageState、Direct3DDevice7.SetTextureStageState、CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DTEXTURESTAGESINGLE

CONST_D3DTEXTURESTAGESINGLE 列挙は、Single 型の値を受け付けるテクスチャ ステージ ステートを定義する。この列挙の定数は、テクスチャ ステート値を取得および設定する Direct3DDevice7.GetTextureStageStateSingle メソッドと Direct3DDevice7.SetTextureStageStateSingle メソッドで使用される。

Enum CONST_D3DTEXTURESTAGESINGLE
    D3DTSS_BUMPENVLOFFSET = 23
    D3DTSS_BUMPENVLSCALE  = 22
    D3DTSS_BUMPENVMAT00   = 7
    D3DTSS_BUMPENVMAT01   = 8
    D3DTSS_BUMPENVMAT10   = 9
    D3DTSS_BUMPENVMAT11   = 10
    D3DTSS_MIPMAPLODBIAS  = 19
End Enum
D3DTSS_BUMPENVMAT00
テクスチャ ステージ ステートは、バンプ マッピング行列の [0][0] 係数に対する値である。デフォルト値は 0 である。
D3DTSS_BUMPENVMAT01
テクスチャ ステージ ステートは、バンプ マッピング行列の [0][1] 係数に対する値である。デフォルト値は 0 である。
D3DTSS_BUMPENVMAT10
テクスチャ ステージ ステートは、バンプ マッピング行列の [1][0] 係数に対する値である。デフォルト値は 0 である。
D3DTSS_BUMPENVMAT11
テクスチャ ステージ ステートは、バンプ マッピング行列の [1][1] 係数に対する値である。デフォルト値は 0 である。
D3DTSS_BUMPENVLSCALE
バンプ マップ輝度用にスケールする。デフォルト値は 0 である。
D3DTSS_BUMPENVLOFFSET
バンプ マップ輝度用にオフセットする。デフォルト値は 0 である。
D3DTSS_MIPMAPLODBIAS
ミップマップ詳細バイアスのレベル。これを利用すると、テクスチャに質量感を与えたり、ぼやけた感じを与えることができる。デフォルト値は 0 である。

注意

バンプ マッピング行列係数 D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、および D3DTSS_BUMPENVMAT11 が取り得る有効な値の範囲は、-8.0 以上 8.0 未満である。この範囲を数学的には [-8.0,8.0] と表記する。

参照

Direct3DDevice7.GetTextureStageStateSingle、Direct3DDevice7.SetTextureStageStateSingle


CONST_D3DTEXTURESTAGESTATETYPE

CONST_D3DTEXTURESTAGESTATETYPE 列挙は、テクスチャ ステージ ステートを定義する。この列挙の定数は、テクスチャ ステート値を取得および設定する Direct3DDevice7.GetTextureStageState メソッドと Direct3DDevice7.SetTextureStageState メソッドで使用される。

Enum CONST_D3DTEXTURESTAGESTATETYPE
    D3DTSS_ADDRESS        = 12
    D3DTSS_ADDRESSU       = 13
    D3DTSS_ADDRESSV       = 14
    D3DTSS_ALPHAARG1      = 5
    D3DTSS_ALPHAARG2      = 6
    D3DTSS_ALPHAOP        = 4
    D3DTSS_BORDERCOLOR    = 15
    D3DTSS_COLORARG1      = 2
    D3DTSS_COLORARG2      = 3
    D3DTSS_COLOROP        = 1
    D3DTSS_MAGFILTER      = 16
    D3DTSS_MAXANISOTROPY  = 21
    D3DTSS_MAXMIPLEVEL    = 20
    D3DTSS_MINFILTER      = 17
    D3DTSS_MIPFILTER      = 18
    D3DTSS_TEXCOORDINDEX  = 11
    D3DTSS_TEXTURETRANSFORMFLAGS = 24
End Enum
D3DTSS_ADDRESS
CONST_D3DTEXTUREADDRESS 列挙のメンバ。u 座標と v 座標の両方で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_ADDRESSU
CONST_D3DTEXTUREADDRESS 列挙のメンバ。u 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_ADDRESSV
CONST_D3DTEXTUREADDRESS 列挙のメンバ。v 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_ALPHAARG1
テクスチャ ステージ ステートは、そのステージに対する最初のアルファ引数であり、テクスチャ引数フラグにより識別される。デフォルト引数は D3DTA_TEXTURE である。該当ステージにテクスチャが設定されていない場合のデフォルト引数は D3DTA_DIFFUSE である。
D3DTSS_ALPHAARG2
テクスチャ ステージ ステートは、そのステージに対する 2 番目のアルファ引数であり、テクスチャ引数フラグにより識別される。デフォルト引数は D3DTA_CURRENT である。
D3DTSS_ALPHAOP
テクスチャ ステージ ステートは、テクスチャ アルファ ブレンディング操作であり、CONST_D3DTEXTUREOP 列挙の定数の 1 つによって識別される最初のテクスチャ ステージ (ステージ ゼロ) のデフォルト値は D3DTOP_SELECTARG1、それ以外のすべてのステージのデフォルト値は D3DTOP_DISABLE である。
D3DTSS_BORDERCOLOR
[0.0,1.0] の範囲の外にあるテクスチャ座標のラスタ化を実行するときに使用する色を記述する値。デフォルト色は 0x00000000 である。
D3DTSS_COLORARG1
テクスチャ ステージ ステートは、そのステージに対する最初の色引数であり、テクスチャ引数フラグにより識別される。デフォルト引数は D3DTA_TEXTURE である。
D3DTSS_COLORARG2
テクスチャ ステージ ステートは、そのステージに対する 2 番目の色引数であり、テクスチャ引数フラグにより識別される。デフォルト引数は D3DTA_CURRENT である。
D3DTSS_COLOROP
テクスチャ ステージ ステートは、テクスチャ色ブレンディング操作であり、CONST_D3DTEXTUREOP 列挙の定数の 1 つによって識別される。最初のテクスチャ ステージ (ステージ ゼロ) のデフォルト値は D3DTOP_MODULATE、それ以外のすべてのステージのデフォルト値は D3DTOP_DISABLE である。
D3DTSS_MAGFILTER
テクスチャをプリミティブにレンダリングするときに使用されるテクスチャ拡大フィルタを示す CONST_D3DTEXTUREMAGFILTER 列挙のメンバ。デフォルト値は D3DTFG_POINT である。
D3DTSS_MAXANISOTROPY
非等方性レベルの最大値。デフォルト値は 1 である。
D3DTSS_MAXMIPLEVEL
アプリケーションが使用可能な最大詳細レベル ミップマップ。ゼロがデフォルト値で、全レベルが使用可能であることを示す。
D3DTSS_MINFILTER
テクスチャをプリミティブにレンダリングするときに使用されるテクスチャ拡大フィルタを示す CONST_D3DTEXTUREMINFILTER 列挙のメンバ。デフォルト値は D3DTFN_POINT である。
D3DTSS_MIPFILTER
テクスチャをプリミティブにレンダリングするときに使用されるテクスチャ拡大フィルタを示す CONST_D3DTEXTUREMIPFILTER 列挙のメンバ。デフォルト値は D3DTFP_NONE である。
D3DTSS_TEXCOORDINDEX
このテクスチャ ステージで使用するために設定されたテクスチャ座標インデックス。デフォルト インデックスは 0 である。このステートは、テクスチャ ステージが使用する、各頂点に対するテクスチャ セットの、ゼロ ベースのインデックスに設定する (頂点 1 個に対して最大 8 セットまでのテクスチャ座標を設定できる)。頂点が、指定されたインデックスのテクスチャ座標セットを持たない場合は、システムはデフォルトとして、u、v 座標 (0,0) を使用する。

このステートに指定したインデックスに CONST_D3DTEXCOORDINDEXFLAGS 列挙のフラグを組み込んで、システムがインデックス値を解釈する方法を変更することができる。詳細については、「テクスチャ座標の自動生成の構成」を参照すること。

D3DTSS_TEXTURETRANSFORMFLAGS
このテクスチャ ステージのテクスチャ座標のトランスフォームを制御する CONST_D3DTEXTURETRANSFORMFLAGS 列挙のメンバ。デフォルト値は D3DTTFF_DISABLE である。


CONST_D3DTEXTURETRANSFORMFLAGS

CONST_D3DTEXTURETRANSFORMFLAGS 列挙は、D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートで使用される。

Type CONST_D3DTEXTURETRANSFORMFLAGS
    D3DTTFF_COUNT1          = 1
    D3DTTFF_COUNT2          = 2
    D3DTTFF_COUNT3          = 3
    D3DTTFF_COUNT4          = 4
    D3DTTFF_DISABLE         = 0
    D3DTTFF_PROJECTED       = 256
End Type
D3DTTFF_COUNT1
ラスタライザは、テクスチャ座標を 1D 座標と見なす。
D3DTTFF_COUNT2
ラスタライザは、テクスチャ座標を 2D 座標と見なす。
D3DTTFF_COUNT3
ラスタライザは、テクスチャ座標を 3D 座標と見なす。
D3DTTFF_COUNT4
ラスタライザは、テクスチャ座標を 4D 座標を見なす。
D3DTTFF_DISABLE
テクスチャ座標が直接ラスタライザに渡される。
D3DTTFF_PROJECTED
テクスチャ座標をラスタライザに渡す前に、常に最後の要素で除算する。たとえば、D3DTTFF_COUNT3 フラグでこのフラグが指定されている場合、テクスチャ座標がラスタライザに渡される前に、1 番目と 2 番目のテクスチャ座標が 3 番目のテクスチャ座標によって除算される。

参照

D3DTSS_TEXTURETRANSFORMFLAGS


CONST_D3DTRANSFORMSTATETYPE

CONST_D3DTRANSFORMSTATETYPE 列挙は、トランスフォーム ステートを記述する値を定義する。

Enum CONST_D3DTRANSFORMSTATETYPE
    D3DTRANSFORMSTATE_WORLD        = 1
    D3DTRANSFORMSTATE_WORLD1       = 4,
    D3DTRANSFORMSTATE_WORLD2       = 5,
    D3DTRANSFORMSTATE_WORLD3       = 6,
    D3DTRANSFORMSTATE_VIEW         = 2
    D3DTRANSFORMSTATE_PROJECTION   = 3
    D3DTRANSFORMSTATE_TEXTURE0     = 16
    D3DTRANSFORMSTATE_TEXTURE1     = 17
    D3DTRANSFORMSTATE_TEXTURE2     = 18
    D3DTRANSFORMSTATE_TEXTURE3     = 19
    D3DTRANSFORMSTATE_TEXTURE4     = 20
    D3DTRANSFORMSTATE_TEXTURE5     = 21
    D3DTRANSFORMSTATE_TEXTURE6     = 22
    D3DTRANSFORMSTATE_TEXTURE7     = 23
End Enum
D3DTRANSFORMSTATE_WORLD
トランスフォームするワールド、ビュー、射影の行列を定義する。デフォルト値は Nothing である (同一の行列)。
D3DTRANSFORMSTATE_VIEW
トランスフォームするワールド、ビュー、射影の行列を定義する。デフォルト値は Nothing である (同一の行列)。
D3DTRANSFORMSTATE_PROJECTION
トランスフォームするワールド、ビュー、射影の行列を定義する。デフォルト値は Nothing である (同一の行列)。
D3DTRANSFORMSTATE_WORLD1
頂点フォーマットで指定された行列とブレンディングの重み (ベータ) 値を使って頂点をブレンドする、後続のトランスフォーム行列を識別する。
D3DTRANSFORMSTATE_WORLD2
頂点フォーマットで指定された行列とブレンディングの重み (ベータ) 値を使って頂点をブレンドする、後続のトランスフォーム行列を識別する。
D3DTRANSFORMSTATE_WORLD3
頂点フォーマットで指定された行列とブレンディングの重み (ベータ) 値を使って頂点をブレンドする、後続のトランスフォーム行列を識別する。
D3DTRANSFORMSTATE_TEXTURE0 through D3DTRANSFORMSTATE_TEXTURE7
指定されたテクスチャ ステージに設定されているトランスフォーム行列を識別する。

参照

CONST_D3DRENDERSTATETYPE、ジオメトリ ブレンディング


CONST_D3DVBCAPSFLAGS

CONST_D3DVBCAPSFLAGS 列挙は、D3DVERTEXBUFFERDESC 型の lCaps メンバで使用される頂点バッファ能力フラグを定義する。

Enum CONST_D3DVBCAPSFLAGS
    D3DVBCAPS_DEFAULT = 0
    D3DVBCAPS_DONOTCLIP = 1
    D3DVBCAPS_OPTIMIZED = 2147483648
    D3DVBCAPS_SYSTEMMEMORY = 2048
    D3DVBCAPS_WRITEONLY = 65536
End Enum
D3DVBCAPS_DEFAULT
頂点バッファは、ドライバが効率的なリード動作を実行するために選択したメモリであれば、どのメモリに作成してもよい。
D3DVBCAPS_DONOTCLIP
頂点バッファは、クリッピング情報を保持できない。
D3DVBCAPS_OPTIMIZED
頂点バッファは、最適化された頂点データを保持する (このフラグは、新しい頂点バッファの作成時には使用されない)
D3DVBCAPS_SYSTEMMEMORY
頂点バッファは、システム メモリに作成しなければならない。ソフトウェア デバイス (MMX または RGB デバイス) や HAL デバイス (IID_IDirect3DHALDevice) を使ってレンダリングされる頂点バッファには、このフラグを使用する。
D3DVBCAPS_WRITEONLY
アプリケーションが頂点バッファに対して書き込みのみ行うことを、システムに示す。このフラグを使用することにより、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行する。この能力を利用して作成した頂点バッファから読み出しを行おうとすると、パフォーマンスが低下することがある。


CONST_D3DVERTEXBLENDFLAGS

CONST_D3DVERTEXBLENDFLAGS 列挙は、ジオメトリ ブレンディング時に適用される行列数を制御するフラグを定義する。この列挙のメンバは、D3DRENDERSTATE_VERTEXBLEND レンダリング ステートで使用される。

Enum CONST_D3DVERTEXBLENDFLAGS
    D3DVBLEND_1WEIGHT = 1
    D3DVBLEND_2WEIGHTS = 2
    D3DVBLEND_3WEIGHTS = 3
    D3DVBLEND_DISABLE = 0
End Enum
D3DVBLEND_1WEIGHT
D3DTRANSFORMSTATE_WORLD と D3DTRANSFORMSTATE_WORLD1 トランスフォーム ステートで設定された 2 つの行列間での頂点ブレンディングが可能。
D3DVBLEND_2WEIGHTS
D3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_WORLD1、および D3DTRANSFORMSTATE_WORLD2 トランスフォーム ステートで設定された 3 つの行列間での頂点ブレンディングが可能。
D3DVBLEND_3WEIGHTS
D3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_WORLD1、D3DTRANSFORMSTATE_WORLD2、および D3DTRANSFORMSTATE_WORLD3 トランスフォーム ステートで設定された 4 つの行列間での頂点ブレンディングが可能。
D3DVBLEND_DISABLE
頂点ブレンディングは使用できない。D3DTRANSFORMSTATE_WORLD トランスフォーム ステートで指定されたワールド行列だけに使用する。

注意

ジオメトリ ブレンディング (複数の行列による頂点ブレンディング) では、各頂点のブレンディングの重み (ベータ) 値を含む頂点フォーマットを使用する必要がある。

参照

CONST_D3DRENDERSTATETYPE、CONST_D3DTRANSFORMSTATETYPE、Direct3DDevice7.SetTransform、ジオメトリ ブレンディング


CONST_D3DVOPFLAGS

CONST_D3DVOPFLAGS 列挙は、Direct3DVertexBuffer7.ProcessVertices メソッドの vertexOp パラメータで使用される頂点操作フラグを定義する。

Enum CONST_D3DVOPFLAGS
    D3DVOP_CLIP      = 2
    D3DVOP_EXTENTS   = 4
    D3DVOP_LIGHT     = 1024
    D3DVOP_TRANSFORM = 1
End Enum
D3DVOP_CLIP
頂点をトランスフォームし、視錐台の外側に出るあらゆる頂点をクリップする。このフラグは、(たとえば D3DDP_DONOTCLIP フラグで作られたような) クリッピング情報を含まない頂点バッファに使ってはならない。
D3DVOP_EXTENTS
頂点をトランスフォームし、頂点がレンダリングされたら、スクリーン矩形の範囲を更新する。このフラグを使用するとパフォーマンスが向上する可能性があるが、Direct3DDevice7.GetClipStatus で返される範囲に対して、この呼び出しでレンダリングされたデータを考慮した更新が行われなくなる。
D3DVOP_LIGHT
頂点をライティングする。
D3DVOP_TRANSFORM
ワールド行列、ビュー行列、射影行列を使って頂点をトランスフォームする。このフラグは常に設定する必要がある。


CONST_D3DVTXPCAPS

CONST_D3DVTXPCAPS 列挙は、デバイスが D3DDEVICEDESC7 型の lVertexProcessingCaps メンバで公開する頂点の処理能力を示すフラグを定義する。

Type CONST_D3DVTXPCAPS
    D3DVTXPCAPS_DIRECTIONALLIGHTS = 8
    D3DVTXPCAPS_MATERIALSOURCE7 = 2
    D3DVTXPCAPS_NONLOCALVIEWER = 32
    D3DVTXPCAPS_POSITIONALLIGHTS = 16
    D3DVTXPCAPS_TEXGEN = 1
    D3DVTXPCAPS_VERTEXFOG = 4
End Type
D3DVTXPCAPS_DIRECTIONALLIGHTS
デバイスはディレクショナル ライトをサポートする。
D3DVTXPCAPS_MATERIALSOURCE7
デバイスは選択可能な頂点色ソースをサポートする。詳細については、「ライトの色の種類とソース」を参照すること。
D3DVTXPCAPS_NONLOCALVIEWER
デバイスは正スペキュラ ハイライトをサポートする。この機能は、D3DRENDERSTATE_LOCALVIEWER レンダリング ステートを FALSE に設定することによって使用できる。
D3DVTXPCAPS_POSITIONALLIGHTS
デバイスは局部ライト (ポイント ライトやスポット ライトなど) をサポートする。
D3DVTXPCAPS_TEXGEN
デバイスはテクスチャ座標を生成できる。
D3DVTXPCAPS_VERTEXFOG
デバイスは頂点フォグをサポートする。

参照

D3DDEVICEDESC7


CONST_D3DZBUFFERTYPE

CONST_D3DZBUFFERTYPE 列挙は、D3DRENDERSTATE_ZENABLE レンダリング ステートで使用する深度バッファ フォーマットを記述する。

Enum CONST_D3DZBUFFERTYPE
    D3DZB_FALSE        = 0
    D3DZB_TRUE         = 1
    D3DZB_USEW         = 2
End Enum
D3DZB_FALSE
深度バッファの使用を無効にする。
D3DZB_TRUE
z バッファの使用を可能にする。
D3DZB_USEW
w バッファの使用を可能にする。

注意

D3DZB_FALSE と D3DZB_TRUE 値は、以前 D3DRENDERSTATE_ZENABLE で使われていた TRUE、FALSE マクロと入れ替え可能である。

参照

Direct3DDevice7.SetRenderState、深度バッファ


柔軟な頂点フォーマット フラグ

Direct3D 直接モードはフラグの値を使って、DrawPrimitive 準拠のレンダリングで使用する頂点フォーマットを表現する。CONST_D3DFVFFLAGS 列挙には、次に列記するフラグが定義されており、これにより頂点フォーマットを明示的に記述できる。また、この列挙は、これらのフラグのよく使われる組み合わせをヘルパー マクロとして提供している。詳細については、「頂点フォーマットについて」を参照すること。

柔軟な頂点フォーマット (FVF) フラグ
D3DFVF_DIFFUSE
頂点フォーマットがディフューズ色成分を含む。
D3DFVF_LVERTEX
頂点フォーマットは D3DLVERTEX 頂点タイプに対応する。
D3DFVF_NORMAL
頂点フォーマットが頂点法線ベクトルを含む。このフラグを、D3DFVF_XYZRHW と共に使うことはできない。
D3DFVF_SPECULAR
頂点フォーマットがスペキュラ色成分を含む。
D3DFVF_TLVERTEX
頂点フォーマットは D3DTLVERTEX 頂点タイプに対応する。
D3DFVF_VERTEX
頂点フォーマットは D3DVERTEX 頂点タイプに対応する。
D3DFVF_XYZ
頂点フォーマットが未トランスフォーム頂点の位置座標を含む。このフラグを、D3DFVF_XYZRHW と共に使うことはできない。このフラグを使用する場合は、同時に頂点法線と頂点色成分 (D3DFVF_DIFFUSE または D3DFVF_SPECULAR) を指定するか、または、少なくとも 1 セットのテクスチャ座標 (D3DFVF_TEX1 から D3DFVF_TEX8) を含める必要がある。
D3DFVF_XYZRHW
頂点フォーマットが、トランスフォームされた頂点の位置座標を含む。このフラグを D3DFVF_XYZ または D3DFVF_NORMAL フラグと同時に使用することはできない。このフラグを使用する場合は、同時に頂点色成分 (D3DFVF_DIFFUSE または D3DFVF_SPECULAR) を指定するか、または、少なくとも 1 セットのテクスチャ座標 (D3DFVF_TEX1 から D3DFVF_TEX8) を含める必要がある。
D3DFVF_XYZB1 から D3DFVF_XYZB5
頂点フォーマットが、位置座標データと、複数の行列による頂点ブレンディング操作で使用する重み (ベータ) 値の数を含む。現在、Direct3D は最高 3 つの重み値 (と 4 つのブレンディング行列) を使ってブレンドを行うことができる。
テクスチャ関連 FVF フラグ
D3DFVF_TEX0 through D3DFVF_TEX8
この頂点に対応するテクスチャ座標セットの番号。これらのフラグに対応する数字は連続番号になっていない。

参照

頂点フォーマットについて、ジオメトリ ブレンディング


テクスチャ引数フラグ

デバイスに対応するそれぞれのテクスチャ ステージは 2 つのテクスチャ引数を持つことができ、これらの引数はテクスチャの色とアルファ チャネルに影響を与える。テクスチャ引数を設定および取得するには、それぞれ Direct3DDevice7.SetTextureStageState メソッドと Direct3DDevice7.GetTextureStageState メソッド を呼び出して、CONST_D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHAARG1 または D3DTSS_ALPHAARG2 定数を指定する。

次に示すフラグ (引数と修正子にまとめられている) をテクスチャ ステージの色とアルファ引数と共に使用することができる。引数フラグと修正子を組み合わせることはできるが、2 つの引数フラグを組み合わせることはできない。

引数フラグ
D3DTA_CURRENT
テクスチャ引数は前のブレンディング ステージの結果である。最初のテクスチャ ステージ (ステージ ゼロ) では、この引数はデフォルト値 D3DTA_DIFFUSE を取る。前のブレンディング ステージでバンプマップ テクスチャ (D3DTOP_BUMPENVMAP 操作) を使用する場合、システムはバンプマップ テクスチャの前のステージからテクスチャを選択する(現在のテクスチャ ステージを s とすると、s – 1 にバンプマップ テクスチャが含まれ、この引数がテクスチャ ステージ s – 2 の出力となる)。
D3DTA_DIFFUSE
テクスチャ引数は、グーロー シェーディング処理中に頂点成分から補間して得られたディフューズ色である。頂点がディフューズ色を含まない場合のデフォルト色は 0xFFFFFFFF である。
D3DTA_SELECTMASK
すべての引数に対応するマスク値。テクスチャ引数の設定には使用しない。
D3DTA_SPECULAR
テクスチャ引数は、グーロー シェーディング処理中に頂点成分から補間して得られたディフューズ色である。頂点がスペキュラ色を含まない場合のデフォルト色は 0xFFFFFFFF である。
D3DTA_TEXTURE
テクスチャ引数は、このテクスチャ ステージのテクスチャ色である。これが有効なのは、ステージの最初の色とアルファ引数に対してのみである (ＣＯＮＳＴ_Ｄ3DTEXTURESTAGESTATETYPE の D3DTSS_COLORARG1 メンバと D3DTSS_ALPHAARG1 定数)。このブレンディング引数を使用するステージにテクスチャが設定されていない場合、システムはデフォルトでカラー値 Ｒ、G、B とアルファをそれぞれ 1.0 に設定する。
D3DTA_TFACTOR
テクスチャ引数は、前回 D3DRENDERSTATE_TEXTUREFACTOR レンダリング ステート値を使って Direct3DDevice7.SetRenderState を呼び出した時のテクスチャ ファクタ セットである。
修正子フラグ
D3DTA_ALPHAREPLICATE
操作が完了する前に、アルファ情報をすべての色チャネルにコピーする。
D3DTA_COMPLEMENT
引数の逆数を取る。たとえば、引数の結果が変数 x ならば、その値は 1.0 - x になる。


エラー コード

CONST_D3DIMERR 列挙で定義されるエラー コードは、負の値で表され、組み合わせて使用することはできない。この表は、すべての Direct3D 直接モード メソッドが生成できるエラー コードをまとめたものである。各メソッドが返すことのできる値の一覧については、メソッドの個々の記述を参照すること。

D3D_OK
エラーは発生していない。
D3DERR_BADMAJORVERSION
要求されたサービスは、DirectX のこのメジャー バージョンでは使用できない (「メジャー バージョン」とは、DirectX 6.0 などの一次リリースを指す)。
D3DERR_BADMINORVERSION
要求されたサービスは、DirectX のこのメジャー バージョンでは使用できるが、このマイナー バージョンでは使用できない。最新バージョンのランタイム コンポーネントは Microsoft から入手できる (「マイナー バージョン」とは、DirectX 6.1 などの二次リリースを指す)。
D3DERR_COLORKEYATTACHED
透過性のためのカラー キーを使用するサーフェスでテクスチャを作成しようとした。
D3DERR_CONFLICTINGTEXTUREFILTER
現在のテクスチャ フィルタを同時に使用することはできない。
D3DERR_CONFLICTINGTEXTUREPALETTE
現在のテクスチャを同時に使用することはできない。通常、マルチテクスチャ デバイスで、有効なすべてのパレット化テクスチャで同じパレットを共有しようとするとこのエラーが発生する。
D3DERR_CONFLICTINGRENDERSTATE
現在設定されているレンダリング ステートを同時に使用することはできない。
D3DERR_DEVICEAGGREGATED
レンダリング ターゲット サーフェスから取得されたデバイスで Direct3DDevice7.SetRenderTarget メソッドが呼び出された。
D3DERR_INITFAILED
新しいデバイスを初期化できなかったため、レンダリング デバイスを作成できなかった。
D3DERR_INBEGIN
シーンのレンダリング時に要求された操作を完了できなかった。シーンが完了し、Direct3DDevice7.EndScene メソッド (または同等の機能を持つメソッド) を呼び出してから再試行すること。
D3DERR_INBEGINSTATEBLOCK
ステート ブロックへのステート記録時に操作を完了できなかった。Direct3DDevice7.EndStateBlock メソッドを呼び出して再試行し、記録を完了すること。
D3DERR_INOVERLAYSTATEBLOCK
ステート ブロックのオーバーレイ時に操作を完了できなかった。ステート ブロックのオーバーレイを削除してから再試行すること。
D3DERR_INVALID_DEVICE
要求されたデバイスのタイプが無効である。
D3DERR_INVALIDCURRENTVIEWPORT
現在選択されているビューポートが無効である。
D3DERR_INVALIDMATRIX
現在設定されているワールド、ビュー、および射影行列の組み合わせが無効のため (この組み合わせでは行列式がゼロになる)、要求された操作を完了できなかった。
D3DERR_INVALIDPALETTE
サーフェスに関連付けられたサーフェスが無効である。
D3DERR_INVALIDPRIMITIVETYPE
アプリケーションによって指定されたプリミティブが無効である。
D3DERR_INVALIDRAMPTEXTURE
ランプ モードが使われ、現在のマテリアルのテクスチャ ハンドルは、レンダリング ステートとして設定された現在のテクスチャ ハンドルに適合しない。
D3DERR_INVALIDSTATEBLOCK
ステート ブロック ハンドルが無効である。
D3DERR_INVALIDVERTEXFORMAT
アプリケーションによって指定された柔軟な頂点フォーマット フラグの組み合わせが無効である。
D3DERR_INVALIDVERTEXTYPE
アプリケーションによって指定された頂点のタイプが無効である。
D3DERR_LIGHT_SET_FAILED
ライティング オブジェクトのライティング パラメータを設定しようとしたが失敗した。
D3DERR_LIGHTHASVIEWPORT
ライティング オブジェクトが別のビューポートに関連付けられているため、要求された操作が失敗した。
D3DERR_LIGHTNOTINTHISVIEWPORT
ライティング オブジェクトがこのビューポートに関連付けられていないため、要求された操作が失敗した。
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_NOCURRENTVIEWPORT
ビューポート パラメータが設定されていないため取得できなかった。
D3DERR_NOTINBEGIN
シーンのレンダリングが開始されていないため、要求されたレンダリング操作を完了できなかった。Direct3DDevice7.BeginScene を呼び出してレンダリングを開始してから再試行すること。
D3DERR_NOTINBEGINSTATEBLOCK
要求された操作はステート ブロックの記録中のみ有効なので、操作を完了できなかった。Direct3DDevice7.BeginStateBlock メソッドを呼び出して再試行すること。
D3DERR_NOVIEWPORTS
デバイスに関連付けられたビューポートがないため、要求された操作が失敗した。
D3DERR_SCENE_BEGIN_FAILED
シーンのレンダリングを開始できなかった。
D3DERR_SCENE_END_FAILED
シーンのレンダリングを完了できなかった。
D3DERR_SCENE_IN_SCENE
前のシーンが Direct3DDevice7.EndScene メソッドによって完了されていないので、シーンのレンダリングを開始できなかった。
D3DERR_SCENE_NOT_IN_SCENE
Direct3DDevice7.BeginScene メソッドによってシーンが開始されていないので、シーンのレンダリングを完了できなかった。
D3DERR_SETVIEWPORTDATA_FAILED
ビューポート パラメータを設定できなかった。
D3DERR_STENCILBUFFER_NOTPRESENT
レンダリング ターゲット サーフェスにアタッチされたステンシル バッファがないので、要求されたステンシル バッファ操作を完了できなかった。
D3DERR_SURFACENOTINVIDMEM
レンダリング ターゲット サーフェスがビデオ メモリに存在しないので、デバイスを作成できなかった (ハードウェア アクセラレーション デバイスではビデオ メモリにレンダリング ターゲット サーフェスが存在しなければならない)。
D3DERR_TEXTURE_BADSIZE
現在のテクスチャのサイズが無効である。2 のべき乗の大きさのテクスチャが必要なデバイスで、2 のべき乗でない大きさのテクスチャを使用しようとすると、このエラーが発生する可能性がある。
D3DERR_TEXTURE_CREATE_FAILED
テクスチャに対するテクスチャ ハンドルをドライバから取得できなかった。
D3DERR_TEXTURE_DESTROY_FAILED
デバイスがテクスチャに対するメモリの割り当てを削除できなかった。
D3DERR_TEXTURE_GETSURF_FAILED
テクスチャの作成に使用する DirectDraw サーフェスを取得できなかった。
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
テクスチャ サーフェスのロックを解除できなかった。
D3DERR_TOOMANYOPERATIONS
デバイスがサポートしている数より多くのテクスチャ フィルタリング操作をアプリケーションが要求している。
D3DERR_TOOMANYPRIMITIVES
このデバイスでは、要求された量のプリミティブを単一パスでレンダリングできない。
D3DERR_UNSUPPORTEDALPHAARG
指定されたアルファ チャネルのテクスチャ ブレンディング引数のいずれかをデバイスがサポートしていない。
D3DERR_UNSUPPORTEDALPHAOPERATION
指定されたアルファ チャネルのテクスチャ ブレンディング操作のいずれかをデバイスがサポートしていない。
D3DERR_UNSUPPORTEDCOLORARG
指定されたカラー値のテクスチャ ブレンディング引数のいずれかをデバイスがサポートしていない。
D3DERR_UNSUPPORTEDCOLOROPERATION
指定されたカラー値のテクスチャ ブレンディング操作のいずれかをデバイスがサポートしていない。
D3DERR_UNSUPPORTEDFACTORVALUE
指定されたテクスチャ係数値をデバイスがサポートしていない。
D3DERR_UNSUPPORTEDTEXTUREFILTER
指定されたテクスチャ フィルタをデバイスがサポートしていない。
D3DERR_VBUF_CREATE_FAILED
頂点バッファを作成できなかった。頂点バッファに割り当てる十分なメモリがない可能性がある。
D3DERR_VERTEXBUFFERLOCKED
頂点バッファがロックされているため、要求された操作を完了できなかった。
D3DERR_VERTEXBUFFEROPTIMIZED
頂点バッファが最適化されていないため、要求された操作を完了できなかった (最適化された頂点バッファの内容はドライバ固有で、プライベートと見なされる)。
D3DERR_VERTEXBUFFERUNLOCKFAILED
頂点バッファのメモリがオーバーランしたので、頂点バッファのロックを解除できなかった。頂点バッファのサイズを越える書き込みを行っていないかどうか確認すること。
D3DERR_VIEWPORTDATANOTSET
ビューポート パラメータが設定されていないため、要求された操作を完了できなかった。Direct3DDevice7.SetViewport メソッドを呼び出してビューポート パラメータを設定してから再試行すること。
D3DERR_VIEWPORTHASNODEVICE
ビューポートがデバイスに関連付けられていないため、要求された操作を完了できなかった。
D3DERR_WRONGTEXTUREFORMAT
テクスチャ サーフェスのピクセル フォーマットが無効である。
D3DERR_ZBUFF_NEEDS_SYSTEMMEMORY
指定されたデバイスではシステム メモリに深度バッファ サーフェスが存在しなければならないので、要求された操作を完了できなかった (ソフトウェア レンダリング デバイスではシステム メモリに深度バッファが存在しなければならない)。
D3DERR_ZBUFF_NEEDS_VIDEOMEMORY
指定されたデバイスではビデオ メモリに深度バッファ サーフェスが存在しなければならないので、要求された操作を完了できなかった (ハードウェア アクセラレーション デバイスではビデオ メモリに深度バッファが存在しなければならない)。
D3DERR_ZBUFFER_NOTPRESENT
レンダリング ターゲット サーフェスに深度バッファがアタッチされていないので、要求された操作を完了できなかった。


Direct3D 直接モードのツールとサンプル

ここでは、Microsoft® DirectX® SDK のサンプル アプリケーションについて説明する。このサンプル アプリケーションの目的は、Microsoft® Direct3D® 直接モードの使用方法を示ことである。説明する内容は以下のとおりである。

  • Direct3D 直接モード ツール
  • Direct3D 直接モード C++ サンプル
  • Direct3D 直接モード Visual Basic サンプル


Direct3D 直接モード ツール

ここでは、DirectX Software Development Kit (SDK) で提供される以下のツールについて説明する。

  • MFCTex ツール


MFCTex ツール

説明

MFCTex とは、マルチ テクスチャ ブレンディングを適用する前にプレビューできるインタラクティブ ツールである。このツールによって、希望のエフェクトを得るために必要なコードを生成することもできる。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Mfctex

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Mfctex.exe

ユーザーズ ガイド

ビットマップを 3 つまで選択し、テキスト ボックスとドロップダウン リストを使ってパラメータを変更する。2 つしか使用しない場合は、Texture File テキスト ボックスの 1 つを空白にしておく。

アプリケーションで使用するエフェクトが得られたら、View Code をクリックし、Direct3D Texture Stage Code ダイアログ ボックスからすべてのテキストをコピーする。

変更可能なパラメータの詳細については、「マルチ テクスチャ ブレンディング」を参照すること。


Direct3D 直接モード C++ サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

ここでは、DirectX SDK で提供されるサンプルアプリケーションについて説明する。ここで説明されるアプリケーションの主たる目的は、Direct3D 直接モードの使用方法を示すことである。次のサンプルについて説明する。

  • Bend サンプル
  • Billboard サンプル
  • Boids サンプル
  • BumpEarth サンプル
  • BumpWaves サンプル
  • ClipMirror サンプル
  • Compress サンプル
  • D3DFrame ライブラリ
  • Dolphin サンプル
  • EnumTex サンプル
  • EnvCube サンプル
  • Filter サンプル
  • Fireworks サンプル
  • Flare サンプル
  • LightMap サンプル
  • Lights サンプル
  • MFCFog サンプル
  • MipMap サンプル
  • MTexture サンプル
  • ScreenSaver サンプル
  • ShadowVol サンプル
  • ShadowVol2 サンプル
  • Spheremap サンプル
  • StencilDepth サンプル
  • StencilMirror サンプル
  • VBuffer サンプル
  • VideoTex サンプル
  • WBuffer サンプル
  • XFile サンプル

注 : サンプル プログラムの大部分は、メニュー バーのない共通インターフェイス (D3DFrame ライブラリ にある) を使用している。通常のMicrosoft Windows® 機能 (最小化、最大化、リストア、サイズ変更、閉じる) に加えて、このインターフェイスは、次のコマンドをサポートしている。

キー / 入力 | コマンド
Esc | Quit
F1 | Help/About ダイアログ ボックス (これらのキー入力を表示)
F2 | デバイス オプション
Alt + Enter | フルスクリーンとウィンドウ モードを切り替える「
右マウス ボタン | オプション ポップアップ メニューを表示

デバイス オプション ダイアログ ボックスを使用して、実行時に、ドライバ、Direct3D デバイス、ディスプレイ モード (フルスクリーンのみ) を変更できる。すべてのデバイスが、あらゆるディスプレイ深度のウィンドウ レンダリングをサポートしているわけではない。3D ハードウェアのビデオ メモリには限りがあり、あるディスプレイ モードとウィンドウ サイズを使用すると、容量を超えてしまうことがある。どちらの場合でも、サンプルはメッセージを表示して、ソフトウェア ラスタライザにデフォルト設定する。

DirectX サンプルには Microsoft® Visual C++® プロジェクト ワークスペース ファイルが含まれているが、サンプルが正しくコンパイルされるよう、開発環境で他の設定を確かめる必要が生じる場合もある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。

See Also

「Direct3D 直接モードの C/C++ チュートリアル 」を参照すること。


Bend サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Bend サンプルでは、サーフェス スキニングと呼ばれる技法を示す。3D オブジェクトが表示され、y 軸の周りを回転して、曲がるように見える。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Bend

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Bend.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

このサンプルは、オブジェクトの 2 つの静的コピーを使用してサーフェス スキニング エフェクトを出している。2 つのコピーのうち 1 つは、ある軸を中心に回転している。各フレームで 2 つのオブジェクトの頂点はマージされ、第三のオブジェクトにブレンドされる。サンプル プログラムは、頂点の第三のセットから導かれたオブジェクトを表示する。

このサンプルは、Direct3D サンプル フレームワークを使用してビルドされた。


Billboard サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Billboard サンプルでは、ビルボーディング技法を示す。ビルボーディングとは、2D スプライトを 3D に見せる方法である。この技法は、煙、雲、水蒸気の軌跡、エネルギー ブラストなどに使用することもできる。詳細については、「共通のテクノロジと特殊効果」を参照すること。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Billboard

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Billboard.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

このサンプルは、木立のある草原を表示する。木々は 3D オブジェクトのように見える。しかし、これらは、実際には 2D テクスチャ ビットマップで、見えない矩形ポリゴンにブレンドされている。

サンプル プログラムを実行すると、視点が変化する。視点が変化するたびに、木々が描画されるすべてのビルボード ポリゴンは回転して、ビューアの方を向く。次に、プログラムは、木々のイメージをビルボード ポリゴンにブレンドする。木々は、あらゆる角度から見ることができるため、3D であるかのように見える。ただし、詳しく調べると、木々はすべての角度からまったく同じに見えることがわかる。多くのアプリケーションで、ユーザーがこの小さな欠点に気づくことはない。

影も、2D テクスチャである。

このサンプルは、Direct3D サンプル フレームワークを使用してビルドされた。


Boids サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Boids サンプルは、Direct3D アプリケーションを記述する方法を示す。このサンプルでは、フロッキング アルゴリズムを使用して、単純な背景の上で 3D オブジェクトのグループを動かす。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Boids

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Boids.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

Boids サンプルは、3D 環境を作成し、その中でオブジェクトのグループをアニメーションするための基本を示す。


BumpEarth サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

BumpEarth サンプルでは、Direct3D のバンプ マッピング能力を示す。バンプ マッピングとは、粗いサーフェスの外観をレンダリングする際に使用されるテクスチャ ブレンディング技法である。

パス

ソースファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\BumpEarth

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\BumpEarth.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

グラフィックス ハードウェアがバンプ マッピングをサポートしない場合、このサンプルを実行しようとすると、Direct3D はバンプ マッピングがサポートされていないことを告げるメッセージを表示する。この問題を解決するには、(SDK ルート))\Samples\Multimedia\D3dim\Bin\Enablerefrast.reg を実行して、リファレンス ラスタライザを有効にする。

プログラミング上の注意

バンプ マッピングは高度なマルチテクスチャ ブレンディング技法で、凸凹のサーフェスの外観をレンダリングするのに使用される。バンプ マップ自体はテクスチャで、補正のためのデータを保存している。

このサンプル プログラムにおいて、世界地図はテクスチャである。マップ テクスチャとバンプ マップ テクスチャがサンプルによって球にブレンドされ、高解像度の地形図が得られる。

詳細については、「バンプ マッピング」と「BumpWaves サンプル」を参照すること。

このサンプルは、Direct3D サンプル フレームワークを使用してビルドされた。


BumpWaves サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

BumpWaves サンプルでは、バンプ マッピングを使って波の反射をシミュレートする。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\BumpWaves

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\BumpWaves.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

グラフィックス ハードウェアがバンプ マッピングをサポートしない場合、このプログラムを実行しようとすると、Direct3D はバンプ マッピングがサポートされていないことを告げるメッセージを表示する。この問題を解決するには、リファレンス ラスタライザを有効にする。リファレンス ラスタライザを有効にするには、(SDK ルート)\Samples\Multimedia\D3dim\Bin\Enablerefrast.reg を実行する。

プログラミング上の注意

詳細については、「バンプ マッピング」と「BumpEarth サンプル」を参照すること。

このサンプルは、Direct3D サンプル フレームワークを使用してビルドされた。


ClipMirror サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

ClipMirror サンプルでは、クリップ面を使って平面ミラーを実装する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\ClipMirror

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\ClipMirror.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

シーンはミラーで反射され、2 番目のパスでレンダリングされる。反射されたジオメトリがミラーの境界内にのみ表示されるように、ミラーの角とカメラの視点を使って、クリップ面のカスタム セットを定義する。


Compress サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basicについては、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Compress サンプルでは、DDS ファイル形式を圧縮されたテクスチャ サーフェスにロードする方法を示す。DDS テクスチャは、DirectX SDK のDirectDraw ツールに含まれている DxTex プログラムを使用して作成できる。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Compress

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Compress.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

ファイル フォーマットが DDS と呼ばれるのは、情報を DirectDrawSurface にカプセル化するからである。データは、一致するフォーマットのサーフェスに直接読み込める。

ReadDDSTexture 関数は、DDS サーフェスが、ファイルからどのように読み込まれるかを示す。

DDS ファイルのフォーマットは、次のとおりである。

DWORD dwMagic | (0x20534444、または "DDS ")
DDSURFACEDESC2 ddsd | サーフェスのフォーマットに関する情報
BYTE bData1[] | 主サーフェスのデータ
[BYTE bData2[] | 追加サーフェスのデータがあれば、続く

このフォーマットは読み書きが簡単で、DXTn 圧縮だけでなく、アルファやマルチ ミップ レベルなどの機能もサポートする。DXTn 圧縮を使用する場合、5 つの圧縮タイプのどれかになる。「圧縮したテクスチャ サーフェス」を参照すること。

テクスチャが読み込まれた後、レンダラーがサポートするピクセル フォーマットを選択する必要がある。サンプルでは、サポートされているピクセル フォーマットが列挙され、連結リストに格納される。ピクセル フォーマットを収集してから、FindBestPixelFormatMatch 関数を使用して、最も適合するピクセル フォーマットをリストから探す。

リファレンス ラスタライザなど、一部の Direct3D デバイスや一部のハードウェア デバイスでは、圧縮テクスチャを直接レンダリングできる。これを直接サポートしないレンダラーでは、圧縮サーフェスを非圧縮サーフェスにブリットする必要がある。関数 BltToUncompressedSurface は、この方法を示している。


D3DFrame ライブラリ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照する。

[C++]

説明

D3D フレームワークとは、Direct3D 直接モード サンプルを作成するために使用された C++ クラスの集合であり、Direct3D API の一部ではない。フレームワークを作成および使用したのは、Direct3D サンプルの一貫性と明瞭性を保つためである。フレームワーク クラスの使用については、アプリケーションにより、適切である場合とそうでない場合がある。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\D3DFrame

実行可能ファイル :無し.

ユーザーズ ガイド

D3DFrame は、スタティック ライブラリとしてコンパイルする。このライブラリは、他の Direct3D 直接モード サンプルをビルドするために使用する。

プログラミング上の注意

フレームワークは、DirectDraw ドライバ、Direct3D デバイス、および各デバイスで利用可能なディスプレイ モードを列挙するクラスから構成される。サンプルは、これらのクラスを使用して、Direct3D を初期化し実行する。また、これらのクラスは、ユーザー インターフェイスをサンプル全体に一貫して提供する。さらに、フレームワークには、テクスチャのロードや管理を実行するクラスの集合が含まれる。

Direct3D フレームワークには、デバッグ、Direct3D オブジェクトの操作、およびDirect3D プログラミングに共通の数学的演算を実行するための多くのマクロや関数も含まれている。


Dolphin サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Dolphin サンプルは、アニメーションされたモデルとテクスチャを使用する単純な 3D アプリケーションである。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Dolphin

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Dophin.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

イルカを 3 つのメッシュとしてロードし、線形補間して最終的なメッシュを作成する。


EnumTex サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

EnumTex サンプルでは、テクスチャ フォーマットの列挙方法の中から、推奨される方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Dolphin

実行可能ファイル :なし

ユーザーズ ガイド

このサンプルでは、目に見える処理は実行されないため、SDK には実行可能ファイルは含まれない。

プログラミング上の注意

新しいテクスチャ フォーマットを使用する際に、アプリケーションとの互換性を維持できるように、テクスチャを正確に列挙することが重要である。このサンプル コードでは、その列挙方法を示す。


EnvCube サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、キューブ マッピングの実装方法を示す。キューブ マッピングとは、DirectX 7.0 で実装された新しい環境マッピング技法である。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\EnvCube

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\EnvCube.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

キューブ マップとは、シーンを 6 つの直行方向にレンダリングして作成された、特殊なテクスチャ サーフェスである。キューブ マップは、従来の環境マッピング エフェクトに使用される。


Filter サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Filter サンプルでは、Direct3D がサポートするテクスチャ フィルタリング技法を示す。Direct3D テクスチャ フィルタリング技法により、アプリケーションはレンダリングされたプリミティブの外観に、より一層のリアリティを加えることができる。詳細については、「テクスチャ フィルタリング」を参照すること。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Filter

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Filter.exe

ユーザーズ ガイド

サンプルを起動すると、テクスチャ付きの 2 つの矩形プリミティブが表示される。

F1 キーを押すと [About] ダイアログ ボックスに表示される通常のコマンドに加えて、このプログラムにはメイン メニューがある。

[File] メニューでは、プログラムの一時停止と再開、Direct3D デバイスの変更、プログラムの終了が選択できる。アプリケーションの一時停止と再開は、Enter キーを押すことによっても行える。

[Left Pane] メニューは、サンプルがスクリーンの左側で 3D プリミティブの拡大縮小を行うのに使用する、テクスチャ フィルタリング方法を制御する。また、エッジ アンチエイリアシングや異方性テクスチャ フィルタリングのオプションもある。これらのオプションのエフェクトを見るには、ソフトウェア リファレンス ラスタライザを有効にする必要がある。リファレンス ラスタライザを有効にするには、(SDK ルート)\Samples\Multimedia\D3dim\Bin\Enablerefrast.reg を実行する。

[Right Pane] メニューにより、サンプルがスクリーンの右側でプリミティブのレンダリングを行うとき、拡大縮小に使用するフィルタリング方法を設定できる。

プログラミング上の注意

このサンプルは、最近点サンプリング、線形フィルタリングおよび異方性テクスチャ フィルタリングを示し、異方性の有効化と無効化の方法を示している。さらに、エッジ アンチエイリアシングを有効にする方法も示している。


Fireworks サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Fireworks サンプルは、花火の爆発をシミュレートする粒子のシステムを実装している。粒子は、ゲームで、煙や火花、爆発などのエフェクトを出すためによく使用される。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Fireworks

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Fireworks.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

花火の爆発は、粒子のシステムによってシミュレートされている。粒子は、部分的に透明な球のテクスチャ マップを使用してレンダリングされている。粒子の位置と色はパラメータ化された方程式によって決まり、フレームごとに更新される。


Flare サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Flare サンプルでは、アルファ ブレンディングを使用してレンズ フレア エフェクトを作成する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Flare

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Flare.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

このサンプルでは、レンズ フレアは各フレアの位置を決める数学関数によってシミュレートされている。フレアは追加アルファ ブレンディングを使用することでレンダリングされ、火花のエフェクトを得るためにアニメーションされる。


LightMap サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、複雑なライティング エフェクトを得るためのマルチテクスチャリングおよびマルチパス技法の使用方法を示す。部屋の中に揺れ動くライトがあり、動くたびに動的に壁や天井を照らす。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\LightMap

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Lightmap.exe

ユーザーズ ガイド

[Options] メニューで、マルチパスまたはマルチテクスチャ ブレンディングを選択する。ハードウェアがサポートしていなければ、マルチ テクスチャ ブレンディングは利用できない。

他に利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

このサンプルに「真の」ライティングは存在せず、すべてライト マップで行われる。ライト マップは、実際のライティングよりずっと早いため、ゲームに盛んに使用されている。さらに、実際のライティングの場合、頂点のみで計算するため、高度なテッセレーションが必要となる。


Lights サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

Lights サンプルでは、さまざまなタイプの Direct3D のライティングの点灯方法と移動方法を示す。ライティングはシーンを照らしながらその周りを飛び、数秒ごとに新しいライト タイプに切り替わる。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Lights

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Lights.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

このサンプルは、利用可能な種類のライトそれぞれに対して、ライト プロパティをセット アップする方法を示す。また、フレームごとにライトの位置を動的に決定する方法も示す。


MFCFog サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

MFCFog サンプルでは、フォグを有効にした地形の上を飛行し、さまざまなフォグ パラメータのエフェクトを確認する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\MFCFog

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Mfcfog.exe

ユーザーズ ガイド

パラメータを変更するには、コントロールを使用する。パラメータの詳細については、「フォグ」を参照すること。エフェクトは、フルスクリーン モードで最も顕著になる。

プログラミング上の注意

地形を使用するゲームでは、通常フォグを使用して、遠くにあるオブジェクトのレンダリングを行わなくてもすむようにする。


MipMap サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、z 軸に沿って前後に動く 2 つのレンガの壁を示す。一方の壁はミップマッピングを使用し、他方の壁は使用していないため、ミップマッピングの利点を並べて比較することができる。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\MipMap

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Mipmap.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

このサンプルは D3DFrame のテクスチャ コードを使用していない。しかし、ミップマッピングされたテクスチャのロードや構築に必要な実装をすべて示している。


MTexture サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

MTexture サンプルでは、マルチテクスチャリングの使用方法を示す。シーンは、ベース テクスチャとスポット ライト テクスチャを持つ複数の壁のある部屋で構成され、それぞれが異なる組み合わせのテクスチャ座標を使用している。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\MTexture

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Mtexture.exe

ユーザーズ ガイド

Press 利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

このサンプルは、IDirect3DDevice7::SetTextureStageState メソッドを使用したマルチテクスチャ ステージのプログラミング方法を示している。このメソッドを使用して、数十ものエフェクトを得ることができる。このサンプルでは、そのうちの 1 つ、モノクロ ライト マッピングを示しているが、これは現在、ゲームでたいへん広く使用されている。


ScreenSaver サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

ScreenSaver サンプルでは、Direct3D スクリーン セーバーの作成方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\ScreenSaver

実行可能ファイル :無し

ユーザーズ ガイド

コードをコンパイルすると、D3DBend.scr ファイルが出力される。この出力ファイルをダブルクリックすると、スクリーン セーバーが表示される。Windows の [画面のプロパティ] ダイアログ ボックスでこのスクリーン セーバーを使用できるようにするには、\Windows\System ディレクトリにコピーする。

プログラミング上の注意

起動コードは Scrnsave.lib にある。

スクリーン セーバーのコンパイルについては、『Platform SDK User Interface Services』の「Screen Saver Library」 を参照すること。


ShadowVol サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

ShadowVol サンプルでは、シャドウ ボリュームを実装するためにステンシル バッファを作成および使用する方法を示す。シャドウ ボリュームを使用することで、任意の形のオブジェクトの影を、別の任意の形のオブジェクトにキャストすることができる。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\ShadowVol

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Shadowvol.exe

ユーザーズ ガイド

このサンプルは、ステンシル バッファをサポートするデバイスでのみ実行できる。

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

シャドウ ボリュームは、かなり高度な技法である。

シャドウ ボリュームを作成するには

  1. シャドウ ボリュームを包含するポリゴンの面の集合を構築する。
  2. 次に、ステンシル バッファを使用して、シャドウ ボリュームの前面をレンダリングする。
  3. 続いて、ステンシル バッファをセット アップして、裏面のレンダリングを行うが、このとき、ステンシル バッファから値を差し引く。この後、ステンシル バッファにはキャストされた影のマスクが含まれる。
  4. ステンシル バッファをマスクとして使用し、大きな灰色または黒の矩形を描画すると、フレーム バッファは影によって更新される。


ShadowVol2 サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

ShadowVol2 サンプルでは、シャドウ ボリュームを実装するためにステンシル バッファの作成および使用方法を示す。シャドウ ボリュームは、任意の複雑なオブジェクトに影をキャストするために使用する。これは、ShadowVol サンプルの拡張版である。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\ShadowVol2

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Shadowvol2.exe

ユーザーズ ガイド

このサンプルは、ステンシル バッファをサポートするデバイスでのみ実行される。

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

[Shadow Modes] メニューでは、次のオプションが使用できる。

  • [Draw Shadows] : 影のレンダリングを有効にするには、このオプションをチェックする。
  • [Show Shadow Volumes] : 影の代わりに、影を計算するためのシャドウ ボリュームを描画する。
  • [Draw Shadow Volume Caps] : これをオンにすると、シャドウ ボリュームの最後のサーフェスが描画される。
  • [1 Bit Stencil Mode] : 1 ビットのステンシル バッファのみを使用する、異なったアルゴリズムを使用する。このとき、影が重ならないようにする。デバイスが 1 ビットのステンシルのみをサポートする場合、このモードをオフにすることはできない。
  • [Z Order Shadow Vols] : 1 ビット モードにおいては、シャドウ ボリュームは前から後ろにレンダリングする必要がある。そのため、このオプションがチェックされていないと、レンダリングが不正確になることがある。

プログラミング上の注意

シャドウ ボリュームは、任意の非平面サーフェスに影をキャストする技法である。このエフェクトは、光源と影をキャストするオブジェクトに関してシャドウ ボリュームを構築することで得られる。このサンプルでは、光源は平面上の点の周りを回転するディレクショナル ライトである。シャドウ ボリュームは、影をキャストするオブジェクトの頂点をライトに対し垂直な平面上にキャストして計算する。平面におけるこれらの点の 2D 凸閉包を見つけ、その 2D 閉包を光の方向に押し出して 3D のシャドウ ボリュームを形成する。シャドウ ボリュームは、影に入るすべてのジオメトリをカバーする程度まで遠くまで延びる必要がある。この特別なシャドウ ボリュームの計算を行うには、影をキャストするオブジェクトが凸状オブジェクトでなければならない。

レンダリングは次のように行う。

  1. 普通にジオメトリのレンダリングを行う。
  2. z バッファまたは色バッファに書き込むことなくシャドウ ボリュームのレンダリングを行う。

    ここではアルファ ブレンディングを使用して、色バッファへの書き込みを避けている。シャドウ ボリュームが表示される場所はすべて、ステンシル バッファにマークする。

  3. 次に、カル オーダーを逆転し、シャドウ ボリュームの裏面をレンダリングする。今度は、ステンシル バッファの、カバーされたピクセルのマークをすべて解除する。

    これらのピクセルは z テストをパスしており、したがって、シャドウ ボリュームの背後で見える。つまり、影にならない。マークされたまま残っているピクセルは、シャドウ ボリュームの前面境界と裏面境界の内側にある。つまり、影になる。

  4. これらのピクセルは、ビューポートをカバーする大きな黒い矩形にブレンドされ、影を生成する。


Spheremap サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルは、3D オブジェクトをロードし、球マップを使用してレンダリングする。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\Spheremap

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Spheremap.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

球マップ自体は、特別な、あらかじめ構築されたテクスチャ マップで、環境の 180 度ビューを含む。フレームのレンダリングを行う前に、オブジェクトの法線を使用して、オブジェクトの各頂点のテクスチャ座標を計算する。レンダリングすると、オブジェクトが環境を反射しているように見える。


StencilDepth サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

StencilDepth サンプルでは、ステンシル バッファを使ってシーンの深度構造を視覚化する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\StencilDepth

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\StencilDepth.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには F1 キーを押すか、メニューから選択する。


StencilMirror サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

StencilMirror サンプルでは、ステンシル バッファを使って、シーン内で任意の形の平面ミラーを実装する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\StencilMirror

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\StencilMirror.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。


VBuffer サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、頂点バッファの使用方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\VBuffer

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\VBuffer.exe

ユーザーズ ガイド

利用可能なコマンドを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

頂点バッファが導入される前は、ジオメトリのレンダリングを行うのに、DrawPrimitive 関数に渡す頂点の配列を使用していた。頂点バッファは便利ではあるが、個別に作成、ロック、フィル、ロック解除を行ってから、新しい DrawPrimitiveVB 関数でレンダリングを行う必要がある。


VideoTex サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

VideoTex サンプルでは、テクスチャ マップとして .avi ファイルを使用する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\VideoTex

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\Videotex.exe

ユーザーズ ガイド

一般的なコマンドのリストを調べるには、F1 キーを押すか、メニューから選択する。

プログラミング上の注意

このプログラムは、各面にマッピングされる .avi テクスチャを持つ立方体を描画する。テクスチャのサーフェスは、DDSCAPS2_HINTDYNAMIC フラグを使用しなければならない。


WBuffer サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

WBuffer サンプルでは、w バッファリングの使用方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\WBuffer

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\WBuffer.exe

ユーザーズ ガイド

通常のコマンド一覧を参照するには、F1 キーを押すか、メニューから選択する。他に、W (サポートされていれば、w バッファリング)、Z (z バッファリング)、または N (バッファリングなし) を押して、バッファリングのメカニズムを変更することができる。z バッファリングを使用するときに表示されるアーティファクトに注意すること。

プログラミング上の注意

w バッファリングは、z バッファリングに代わる深度バッファリングで、z バッファリングで不自然な効果が生成される場合に使用する。w バッファリングは、深度バッファを量子化する際に優れた働きをする。


XFile サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、.x ファイルをロードおよびレンダリングする方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Src\XFile

実行可能ファイル :(SDK ルート)\Samples\Multimedia\D3dim\Bin\XFile.exe

ユーザーズ ガイド

このサンプルを実行すると、[Open File] ダイアログ ボックスが表示される。D3DIM サンプル ディレクトリのメディア フォルダに、いくつかの .x ファイルがある。ディレクトリ内に同じ名前の .bmp ファイルがある場合、その bmp が自動的にオブジェクトのテクスチャとして使用される。

利用可能なコマンドを調べるには、F1 キーを押す。また、[File] メニューから別のファイルをロードすることができる。

プログラミング上の注意

オブジェクトをロードするとテクスチャが上下逆さに表示されることがあるが、これは、オブジェクトがテクスチャをロードする方法に起因する。Direct3D の以前のバージョンでは、ビットマップを上下逆さにロードしていたため、いくつかの .x ファイルでは、作者が座標を逆にして対処していた。


Direct3D 直接モード Visual Basic サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

ここでは、DirectX® SDK のサンプル アプリケーションについて説明する。ここで説明するアプリケーションの主たる目的は、Direct3D® コンポーネントを直接モードで使用する方法を示すことである。次のサンプル プログラムについて説明する。

  • Billboard サンプル
  • Fireworks サンプル
  • IMControl サンプル
  • MipMap サンプル
  • PPlane サンプル
  • Tunnel サンプル
  • VBuffer サンプル
  • XFile サンプル

サンプル プログラムの多くは、IMControl カスタム コントロールを共通のレンダリング カンバスとして使用する。このコントロールでは、F5 キーでデバイス オプション ダイアログ ボックスを呼び出す。このダイアログ ボックスを使用して、実行時に、ドライバ、Direct3D デバイス、ディスプレイ モード (フルスクリーンのみ) を変更できる。

「Direct3D 直接モード Visual Basic チュートリアル 」を参照すること。


Billboard サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

説明

このサンプルでは、ビルボーディング技法を示す。ビルボーディングとは、2D スプライトを 3D に見せる方法である。この技法は、煙、雲、水蒸気の軌跡、エネルギー ブラストなどに使用することもできる。詳細については、「共通のテクノロジと特殊効果」を参照すること。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Src\Billboard

実効可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_Billboard.exe

ユーザーズ ガイド

デバイスまたはディスプレイ モードを変更するには、F5 キーを押す。

プログラミング上の注意

このサンプルは、木立のある草原を表示する。木々は 3D オブジェクトのように見える。しかし、これらは、実際には 2D テクスチャ ビットマップで、見えない矩形ポリゴンにブレンドされている。

サンプル プログラムを実行すると、視点が変化する。視点が変化するたびに、木々が描画されるビルボード ポリゴンはすべて回転して、ビューアの方を向く。次に、プログラムは、木々のイメージをビルボード ポリゴンにブレンドする。木々をあらゆる角度から見ることができるため、3D であるかのように見える。ただし、詳しく調べると、木々はすべての角度からまったく同じに見えることがわかる。多くのアプリケーションで、ユーザーがこの小さな欠点に気づくことはない。

影も、2D テクスチャである。


Fireworks サンプル

[C++]

この目では、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

説明

このサンプルでは、3D 粒子を使用して花火の爆発をシミュレートする。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Src\Fireworks

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_Fireworks.exe

ユーザーズ ガイド

デバイスまたはディスプレイを変更するには、F5 キーを押す。

プログラミング上の注意

Fireworks サンプルでは、Direct3D 直接モード テクスチャとアルファ ブレンディングを使用する簡単な粒子システムを示す。各粒子は、部分的に透明な玉のテクスチャ マップとしてレンダリングされている。


IMControl サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

説明

このサンプルは、3D シーンをレンダリングするアプリケーションで使用できるコントロールで、多くの Visual Basic Direct3D サンプルで使用されている。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Src\Imcontrol

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Bin\Imcontrol.exe

ユーザーズ ガイド

Imcontrol.ocx を 3D アプリケーションに統合する方法については、「Billboard サンプル」を参照すること。他の多くのサンプルでもこのコントロールを使用する。

プログラミング上の注意

このコントロールは、フルスクリーンおよびウィンドウ モードで DirectDraw と Direct3D の初期化を処理し、F5 キーによってデバイスや構成を変更するダイアログ ボックスを表示できるようにする。


MipMap サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

説明

MipMap サンプルは、ミップマップ テクスチャを示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Src\Mipmap

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_MipMap.exe

ユーザーズ ガイド

デバイスまたはディスプレイ モードを変更するには、F5 キーを押す。

プログラミング上の注意

このサンプルでは、2 組のポリゴンを比較する。1 組目には単一の固定テクスチャが適用され、もう 1 組は一連のミップマップ テクスチャを使用する。


PPlane サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

説明

PPlane サンプルは、紙飛行機を平面上でアニメーションする。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Src\PPlane

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_pplanes.exe

ユーザーズ ガイド

デバイスまたはディスプレイ モードを変更するには、F5 キーを押す。


Tunnel サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

説明

Tunnel サンプルは、トンネル内の航行をシミュレートする。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Src\Tunnel

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_tunnel.exe

ユーザーズ ガイド

デバイスまたはディスプレイ モードを変更するには、F5 キーを押す。


VBuffer サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

説明

このサンプルでは、頂点バッファの使用方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Src\VBuffer

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_vertexBuffer.exe

ユーザーズ ガイド

デバイスまたはディスプレイ モードを変更するには、F5 キーを押す。

プログラミング上の注意

頂点バッファが導入される前は、ジオメトリのレンダリングを行うのに、DrawPrimitive 呼び出しに渡す頂点の配列を使用していた。頂点バッファは便利であるが、個別に作成、ロック、フィル、ロック解除を行ってから、新しい DrawPrimitiveVB 呼び出しでレンダリングを行う必要がある。


XFile サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モード C++ サンプル」を参照すること。

[Visual Basic]

説明

XFile サンプルは DirectX フォーマットにある 3D イメージ用のビューアである。

パス

ソースファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Src\XFile

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_XFile.exe

ユーザーズ ガイド

ファイルをロードするには、[File] メニューから [Open] を選択する。(SDK ルート)\Samples\Multimedia\VBSamples\D3DRM\media フォルダにはいくつかのサンプル x ファイルがある。イメージを回転するには、ウィンドウ内でマウスをドラッグする。イメージを回転 (スピン) するには、マウスをドラッグして放すか、矢印キーを押す。イメージを近づけたり遠ざけるには、プラス キーとマイナス キーを使用する。オブジェクトの外観を変更するには、[Fill Options] メニューと [Shade Options] メニューを使用する。

プログラミング上の注意

ファイルをロードするための主な機能は、XFileClass で提供される。XFileClass は、Direct3D 保持モードを使用する。


Direct3DX ユーティリティ ライブラリ [C++]

Direct3DX ユーティリティ ライブラリは、DirectX® の 3 次元 (3D) グラフィック コンポーネントの一部である。Direct3DX ユーティリティ ライブラリに関する情報について、以下のトピックに分けて説明する。

  • Direct3DX ユーティリティ ライブラリについて
  • Direct3DX ユーティリティ ライブラリを使用する理由
  • Direct3DX ユーティリティ ライブラリ アーキテクチャ
  • Direct3DX ユーティリティ ライブラリの要点
  • Direct3DX ユーティリティ ライブラリ リファレンス
  • Direct3DX ユーティリティ ライブラリ サンプル


Direct3DX ユーティリティ ライブラリについて

Direct3DX ユーティリティ ライブラリのアプリケーション プログラミング インターフェイス (API) は、COM を基にしており、DirectX 7.0 の Direct3D® コンポーネントと DirectDraw® コンポーネントの最上位にあるヘルパー層である。これは、アプリケーションが静的にリンク可能なヘッダー ファイル セットとライブラリ (d3dx.lib または d3dxd.lib) として設計されている。

アプリケーションで Direct3DX ユーティリティ ライブラリにより提供される機能を利用するには、d3dx.lib をリンクする必要がある。しかし、デバッグ アプリケーションの場合は、ライブラリのデバッグ バージョン d3dxd.lib をリンクするとよい。このデバック バージョンは、パラメータやデータ構造体の有効性を検査し、デバッグ エラー メッセージを出力する。エラーが発生すると、デバッグ出力は問題点についてより詳細な説明を提供する。デバッグ ライブラリの実行速度はリテイル バージョンのライブラリ (d3dx.lib) よりも遅いが、アプリケーションをデバッグするにはとても便利である。

Direct3DX ユーティリティ ライブラリは、3D グラフィック開発者のタスクの中で共通するものを簡易化したヘルパー関数を提供している。このユーティリティ ライブラリは Direct3D 直接モードに付属しているので、これを使用するには Direct3D 直接モードの主要部分を理解していることが必要である。

ユーティリティ ライブラリは、Direct3D 直接モードを迅速かつ有効に使用したい開発者のために設計された。退屈なタスクを一部取り除き、ショートカットのツールキットを提供することで、開発者がアプリケーションやゲームの開発そのものにすぐに集中できるようにしている。

Direct3DX ユーティリティ ライブラリは、デバイス設定の列挙、デバイスのセットアップ、フルスクリーン モードとウィンドウ モード共通の実行、サイズ変更処理の実行、ベクトルや行列の演算の計算、およびイメージ ファイル ロード処理やテクスチャ作成処理の簡易化のヘルパー機能を提供している。また、簡単な形状、スプライト、キューブ マップを描画するための関数も提供している。ただし、Direct3DX はシーン階層を提供していなかったり、または X ファイルをサポートしていない。

ユーティリティ ライブラリでは、少なくともユーザーのシステムに DirectX 7.0 がインストールされていることが必要である。Direct3DX ユーティリティ ライブラリは、複数のモニタ設定をサポートしている。ただし、Direct3DX オブジェクトはマルチスレッドについては保証されていない。マルチスレッド化アプリケーションは、Direct3DX オブジェクトにアクセスするには、それ自体のロックと同期プリミティブを追加する必要がある。

D3DX_DEFAULT は事前に定義された値であり、Direct3DX アプリケーション プログラミング インターフェイス (API) のパラメータ、または列挙関数やハンドルであるメンバ関数のパラメータとして使用できる。リファレンスの節で、D3DX_DEFAULT を使用できる場所や、各状況での解釈方法について示す。

D3DX_DEFAULT_FLOAT は D3DX_DEFAULT に似ているが、これは浮動小数点パラメータで使用する。


Direct3DX ユーティリティ ライブラリを使用する理由

3D レンダリングのパフォーマンスを良くするために Direct3D 直接モードを使用する場合、Direct3DX ユーティリティ ライブラリを使用すれば即座にそれに取りかかることができる。開発者が、そのタスクの中でもパフォーマンス関係やアプリケーション特有のタスクに集中したいとき、ユーティリティ ライブラリを利用すれば生産性が向上する。Direct3DX ユーティリティ ライブラリを使用すれば、次のタスクが簡易化される。

  • DirectDraw オブジェクトと Direct3D デバイスのセットアップ。
  • 簡単なジオメトリ図形の描画。
  • テクスチャに対するハードウェアの独立性の実現。
  • 複数サーフェス フォーマットのカラー変換の提供。
  • テクスチャ ファイル (BMP、TGA、DDS) のロード。
  • 環境マップ用のキューブ マップ テクスチャの作成。
  • スプライト機能 (回転、アルファ、スケーリング、歪み) のサポート。
  • 共通の 3D 算術演算の実行。

そのため、Direct3D 直接モードを基にしたタスク エンジンがある場合に、いくつかのヘルパー機能を追加しなければならないとき、Direct3DX ユーティリティ ライブラリが実用的な選択肢となる。

一般に、ユーティリティ ライブラリの各コンポーネントは再利用可能、また互換可能なように設計されている。たとえば、Direct3DX ユーティリティ ライブラリで作成されたオブジェクトだけでなく、任意の Direct3DDevice オブジェクトや DirectDrawSurface オブジェクトでもスプライトを使用できる。同じように、Direct3DX ユーティリティ ライブラリにより提供されているその他の機能を使用しなくても、算術関数や形状作成アプリケーション プログラミング インターフェイス (API) を使用できる。

最後に、Direct3D 以外のグラフィック API を基にしたアプリケーションやゲームをポーティングする場合は、Direct3DX ユーティリティ ライブラリで提供されている機能を使えばより簡単に移行できる。


Direct3DX ユーティリティ ライブラリ アーキテクチャ

ここでは、Direct3DX ユーティリティ ライブラリの構造体について高度な情報を提供する。説明するトピックは次のとおりである。

  • Direct3DX ユーティリティ ライブラリ アーキテクチャの概要
  • Direct3DX ユーティリティ ライブラリのインターフェイスとオブジェクト タイプ


Direct3DX ユーティリティ ライブラリ アーキテクチャの概要

Direct3DX ユーティリティ ライブラリは、DirectX 7.0 の Direct3D コンポーネントと DirectDraw コンポーネントの最上位にあるヘルパー層である。これは、初期化、テクスチャ マップ、スプライトなどの機能で構成されており、大部分はそれぞれお互いに独立している。

ユーティリティ ライブラリの機能をつなぐアプリケーション プログラミング インターフェイス (API) は、初期化関数の D3DXInitialize 関数と D3DXUninitialize 関数だけである。

次図に、Direct3DX ユーティリティ ライブラリと Direct3D や DirectDraw との関係を示す。

注 : D3DXInitialize は、Direct3DX ユーティリティ ライブラリ API を使用する前に呼び出す必要がある。また、アプリケーションを終了する前に D3DXUninitialize を呼び出して、Direct3DX により割り当てられたリソースを解放する必要がある。


Direct3DX ユーティリティ ライブラリのインターフェイスとオブジェクト タイプ

Direct3DX ユーティリティ ライブラリは、次の COM インターフェイスを定義している。

ID3DXContext | 状態設定、テクスチャ作成、表示更新で使用されるルート インターフェイス。
ID3DXMatrixStack | シーン階層の実装時に使用されるヘルパー インターフェイス。
ID3DXSimpleShape | 描画プリミティブ ベースのレンダリングで使用される頂点バッファ インターフェイス。

Direct3DX ユーティリティ ライブラリで最も基本となるオブジェクトは、D3DXDevice オブジェクトである。このオブジェクトは、(D3DXContext オブジェクトや D3DXMatrixStack オブジェクトと異なり) 作成できず、インターフェイスもない。これは、ただシステムで使用可能な Direct3DX デバイス リストへのインデックスとして参照されるだけである。D3DXDevice オブジェクトは、レンダリングするドライバと、そのドライバの能力を表している。

詳細については、「Direct3DX デバイス」を参照すること。

ID3DXContext インターフェイスは、D3DXContext オブジェクトを表している。各 D3DXDevice オブジェクトに複数の D3DXContext オブジェクトを作成できる。

D3DXDevice オブジェクトは、次のオブジェクトをカプセル化する。

  • DirectDraw オブジェクト
  • Direct3D オブジェクト
  • Direct3DDevice オブジェクト
  • レンダリングに必要なクリッパーやサーフェスなどのさまざまな Direct3D オブジェクトと DirectDraw オブジェクト。

D3DXContext オブジェクトを作成すると、ゲームやアプリケーションの前のオブジェクトがすべて作成される。これらのカプセル化されたオブジェクトをそれぞれ実装するインターフェイスへのポインタをコンテキスト オブジェクトから取得するには、次のメソッドを呼び出す。

  • ID3DXContext::GetDD
  • ID3DXContext::GetD3D
  • ID3DXContext::GetD3DDevice

D3DXContext オブジェクトは、特定の D3DXDevice オブジェクトのレンダリング コンテキストとして見なすことができる。

ID3DXMatrixStack インターフェイスは、D3DXMatrixStack オブジェクトを表している。D3DXMatrixStack は、変換階層を操作できるように行列スタックを実装する行列スタック オブジェクトである。ID3DXMatrixStack インターフェイスは、このオブジェクトを完全に定義している。

ID3DXSimpleShape インターフェイスは、形状オブジェクトのすべてで使用できる。

  • D3DXBox
  • D3DXCylinder
  • D3DXPolygon
  • D3DXSphere
  • D3DXTeapot
  • D3DXTorus

Direct3DX により提供されている形状オブジェクトについては、次のトピックを参照すること。

  • 形状描画関数
  • 簡単なジオメトリ図形

形状オブジェクトには、形状を定義する形状データ (頂点やインデックスの情報) が格納されている。ID3DXSimpleShape インターフェイスを使用することで、形状を描画したり、形状オブジェクトから頂点やインデックスの情報を直接取得することができる。


Direct3DX ユーティリティ ライブラリの要点

Direct3DX ユーティリティ ライブラリは、オブジェクトを作成、カプセル化、操作するアプリケーション プログラミング インターフェイス (API) 要素により構成されている。

ここでは、Direct3DX ユーティリティ ライブラリの MYRIAD コンポーネントについての技術情報を示す。説明するトピックは次のとおりである。

  • Direct3DX および Direct3D
  • Direct3DX コンテキスト
  • Direct3DX デバイス
  • Direct3DX 行列スタック
  • ハードウェア アクセラレート レベル
  • スプライトのサポート
  • テクスチャ マップのサポート
  • 簡単なジオメトリ図形
  • 3D 算術のサポート

一般に、Direct3DX ユーティリティ ライブラリを構成するヘルパー コンポーネント (スプライトのサポート、テクスチャ マップのサポート、簡単なジオメトリ図形、および 3D 算術のサポート) は、お互いに独立している。これにより、特定のサブコンポーネントのカスタム バージョンを実装しなくても、必要な機能のみを簡単に利用できる。


Direct3DX および Direct3D

Direct3DX インターフェイスと基底の Direct3D インターフェイスには、密接な関係がある。

説明するトピックは次のとおりである。

  • Direct3DX を使用して Direct3D と DirectDraw を初期化する
  • Direct3DX を使用して Direct3D と DirectDraw にアクセスする

DirectDraw と Direct3D 間の密接な関係の背景については、「Direct3D と DirectDraw」を参照すること。


Direct3DX を使用して Direct3D と DirectDraw を初期化する

Direct3DX ユーティリティ ライブラリでは、Direct3D と DirectDraw を初期化できる。

Direct3D は、COM オブジェクトと COM インターフェイスにより実装される。Direct3D インターフェイスは、ディスプレイ デバイスを表す DirectDraw オブジェクトへのインターフェイスである。アプリケーションの DirectDraw オブジェクトと Direct3DDevice オブジェクトは、コンテキスト オブジェクトを作成することで Direct3DX により 1 ステップで作成される。

    if(FAILED(hr = D3DXCreateContextEx(D3DX_DEFAULT, 0, g_hwnd, NULL, D3DX_DEFAULT, 0,
        D3DX_DEFAULT, 0, 1, D3DX_DEFAULT, D3DX_DEFAULT, D3DX_DEFAULT, &g_pd3dx)))
    {
        return hr;
    }

サンプル コードが示すように、D3DXCreateContextEx 関数は ID3DXContext インターフェイスへのポインタのアドレスを返す。ただし、D3DXCreateContext 関数も ID3DXContext インターフェイスへのポインタのアドレスを返す。D3DXCreateContext 関数と D3DXCreateContextEx 関数の違いについては、リファレンス ページを参照すること。

コンテキストや、コンテキストによる Direct3D オブジェクトや DirectDraw オブジェクトのラッピング方法については、「Direct3DX コンテキスト」を参照すること。

Direct3DX では、ほかにも便利で、また時間を節約できる初期化機能を提供している。この方法では、システム内のさまざまなデバイスの能力が列挙される。デバイスや Direct3DX に固有のデバイス列挙については、「Direct3DX デバイス」を参照すること。


Direct3DX を使用して Direct3D と DirectDraw にアクセスする

コンテキスト オブジェクトを取得すれば、カプセル化されたオブジェクトにアクセスできる。

IDirect3DDevice7 インターフェイスへのポインタを取得するには、ID3DXContext::GetD3DDevice メソッドを使用する。

    m_pd3dDevice = g_pd3dx->GetD3DDevice();
    if (m_pd3dDevice == NULL)
        return E_FAIL;

IDirect3D7 インターフェイスへのポインタを取得するには、ID3DXContext::GetD3D メソッドを使用する。

    m_pd3d = g_pd3dx->GetD3D();
    if (m_pd3d == NULL)
        return E_FAIL;

IDirectDraw7 インターフェイスへのポインタを取得するには、ID3DXContext::GetDD メソッドを使用する。

    m_pdd = g_pd3dx->GetDD();
    if (m_pdd == NULL)
        return E_FAIL;

このように取得したインターフェイスは、アプリケーションで使用できる。たとえば、次のコードでは取得した IDirect3DDevice7 インターフェイスへのポインタ m_pd3dDevice を使用して、ディザリング、スペキュラ エフェクト、ライティング、z バッファ使用を有効にしている。

    hr = m_pd3dDevice->SetRenderState(D3DRENDERSTATE_DITHERENABLE, TRUE);

    hr = m_pd3dDevice->SetRenderState(D3DRENDERSTATE_SPECULARENABLE, TRUE);

    hr = m_pd3dDevice->SetRenderState(D3DRENDERSTATE_LIGHTING, TRUE);

    hr = m_pd3dDevice->SetRenderState(D3DRENDERSTATE_ZENABLE, TRUE);


Direct3DX コンテキスト

Direct3DX コンテキスト オブジェクトとその使用法については、次のトピックを参照すること。

  • Direct3DX コンテキスト オブジェクトとは?
  • Direct3DX を使用してサーフェスをクリアする
  • Direct3DX を使用してシーンを更新する


Direct3DX コンテキスト オブジェクトとは?

Direct3DX コンテキスト オブジェクトは、ディスプレイ デバイスでレンダリングするときに必要なさまざまな Direct3D オブジェクトや DirectDraw オブジェクトをすべてカプセル化した COM オブジェクトである。これは、次のメソッドのいずれかを使用して作成する。

  • D3DXCreateContext
  • D3DXCreateContextEx

コンテキスト オブジェクトを作成すると、Direct3D と DirectDraw を初期化するために DirectX アプリケーションで必要なタスクが減る。コンテキスト オブジェクトを一度作成すれば、Direct3DDevice オブジェクトや DirectDrawSurface オブジェクトなどのさまざまな Direct3D オブジェクトや DirectDraw オブジェクトをこのコンテキスト オブジェクトから間接的に取得できる。

コンテキスト オブジェクトでは、カプセル化バッファのフリッピング (ブリット) も可能であり、ID3DXContext::UpdateFrame メソッドからのマルチバッファ レンダリングをサポートしている。

ID3DXContext::DrawDebugText メソッドや ID3DXContext::Resize メソッドも、DirectX アプリケーションに共通のタスクを簡易化する。

また、ID3DXContext インターフェイスはさまざまなレンダリング関連バッファをクリアするメソッドを提供している。特定のメソッドの詳細については、「ID3DXContext」を参照すること。


Direct3DX を使用してサーフェスをクリアする

多くの C++ アプリケーションは、新しい各フレームをレンダリングする前に深度バッファをクリアする。ID3DXContext::Clear メソッドを使用すれば、Direct3DX ユーティリティ ライブラリで深度バッファを明示的にクリアできる。

    hr = g_pD3DX->Clear(D3DCLEAR_TARGET|D3DCLEAR_ZBUFFER);
    if (FAILED(hr))
        return hr;

Clear メソッドを使用すれば、クリアするサーフェスを指定できる。このコードでは、レンダリング ターゲットと深度バッファの両方がクリアされる。


Direct3DX を使用してシーンを更新する

Direct3DX ユーティリティ ライブラリでは、ページ フリッピングまたはブリット機能のいずれかを使用してシーンのフレームを更新する。

    hr = g_pD3DX->UpdateFrame(D3DX_UPDATE_NOVSYNC);

このコードでは、ID3DXContext::UpdateFrame メソッドを使用して、D3DX_UPDATE_NOVSYNC フラグを設定してフレームを更新している。その結果、この呼び出しでは、ドライバがフルスクリーン モードで垂直同期 (vsync) を待たなければフリッピングできない場合はブリッドを使用するように指定される。


Direct3DX デバイス

Direct3DX デバイスについて、次のトピックで説明する。

  • Direct3DX デバイスとは?
  • Direct3DX デバイスの列挙
  • Direct3DX デバイスの問い合わせ


Direct3DX デバイスとは?

Direct3DX デバイスは、Direct3D デバイスにより提供されている機能に基づいて拡張されている。Direct3DX ユーティリティ ライブラリは、DirectDraw オブジェクトと Direct3DDevice オブジェクトの機能をカプセル化するデバイス構成の D3DXDevice オブジェクトを定義して実装する。この設計により、開発者には便宜性と柔軟性が提供される。

たとえば、システムに 1 つの Direct3D 対応グラフィック アダプタがある場合、そのシステムには D3DXDevice オブジェクトが最大で 4 つある可能性がある。

  • プライマリ ディスプレイ デバイスの DirectDraw + Direct3DRGBDevice
  • プライマリ ディスプレイ デバイスの DirectDraw + Direct3DHALDevice
  • プライマリ ディスプレイ デバイスの DirectDraw + Direct3DTnLHALDevice (アダプタが TnL Hal をサポートしている場合)
  • プライマリ ディスプレイ デバイスの DirectDraw + Direct3DreferenceDevice

また、システムに 3D アクセラレータ カードがある場合、そのシステムには D3DXDevice オブジェクトが最大で 5 つある可能性がある。

Direct3DX は、複数のモニタ設定もサポートしている。そのため、システムに 2 つのグラフィック アダプタがある場合、そのシステムには D3DXDevice オブジェクトが最大で 8 つある可能性がある。

  • プライマリ ディスプレイ デバイスの DirectDraw + Direct3DRGBDevice
  • プライマリ ディスプレイ デバイスの DirectDraw + Direct3DHALDevice
  • プライマリ ディスプレイ デバイスの DirectDraw + Direct3DTnLHALDevice (アダプタが TnL Hal をサポートしている場合)
  • プライマリ ディスプレイ デバイスの DirectDraw + Direct3DReferenceDevice
  • セカンダリ ディスプレイ デバイスの DirectDraw + Direct3DRGBDevice
  • セカンダリ ディスプレイ デバイスの DirectDraw + Direct3DRGBDevice
  • セカンダリ ディスプレイ デバイスの DirectDraw + Direct3DTnLHALDevice (アダプタが TnL Hal をサポートしている場合)
  • セカンダリ ディスプレイ デバイスの DirectDraw + Direct3DReferenceDevice

Direct3D デバイスの一般情報については、「Direct3D デバイス」を参照すること。


Direct3DX デバイスの列挙

特定のディスプレイ デバイスを構成しているコンポーネントや、システムのデバイスを列挙するために Direct3DX ユーティリティ ライブラリにより提供されている機能について詳しく説明する。

Direct3D アプリケーションが Direct3DX ユーティリティ ライブラリを使用するためのグラフィック設定 (ディスプレイ デバイス) は、次のコンポーネントにより構成されている。

  • ディスプレイ モニタ
  • 2D グラフィック デバイス
  • 3D グラフィック デバイス

これらのコンポーネントがあれば、広範囲のディスプレイ オプションを特定のシステムで使用できる。たとえば、あるシステムで複数のモニタを使用できる。2D グラフィック デバイスは、ビデオ アクセラレートを使用することも、使用しないことも可能である。3D グラフィック デバイスは必要な数だけ RAMP、RGB、REFERENCE、HW、または TL HW デバイスを使用できる。

デバイス タイプの詳細については、Direct3D 直接モードのドキュメントの「Direct3D デバイスの種類」を参照すること。

ほとんどの場合、ディスプレイ オプションの組み合わせがすべてシステムでサポートされるわけではない。一般に、3D カードは特定のモニタに接続される。また、2D エンジンのエミュレーションを選択すると、3D エンジンのハードウェアを選択できなくなる。このような競合を解決し、有効なハードウェア設定を判定するには、アプリケーションでシステムのデバイスを列挙する必要がある。

例として、システム上の DirectDraw デバイスの数を判定し、DirectDraw デバイスごとにその最上位ハードウェア アクセラレートを選択するコードを示す。結果として、選択したデバイスに対応するデバイス リストへのインデックス リストが返される。

    dwNumDevices = D3DXGetDeviceCount();

    hr = D3DXGetDeviceDescription( 0, &pDeviceList[0] );

    GUID guidLastUniqueDeviceId = pDeviceList[0].ddDeviceID;
    cNumDDObjs = 1;
    indexOfChosenD3DXDevices[0] = 0; // start by picking the first device

    for( i = 1; i < dwNumDevices; i++ )
    {
        hr = D3DXGetDeviceDescription( i, &pDeviceList[i] );

        if( pDeviceList[i].ddDeviceID != guidLastUniqueDeviceId )
        {
            guidLastUniqueDeviceId = pDeviceList[i].ddDeviceID;
            cNumDDObjs++;
            indexOfChosenD3DXDevices[cNumDDObjs-1] = i;
        }
        else
        {
            int currIndex = indexOfChosenD3DXDevices[cNumDDObjs-1];
            if( pDeviceList[i].hwLevel > pDeviceList[currIndex].hwLevel )
            {
                indexOfChosenD3DXDevices[cNumDDObjs-1] = i;
            }
        }
    }

この例では、D3DXGetDeviceCount 関数を使用してシステムで列挙可能なデバイスの数を取得している。また、D3DXGetDeviceDescription 関数を使用して、列挙されたデバイスの記述を取得して、そのインデックス値によりデバイスを識別している。

注 : Direct3DX ユーティリティ ライブラリを使用する場合は、適切なデフォルト値が Direct3DX コンテキスト オブジェクトに組み込まれるので、アプリケーションからデバイスを列挙する必要はない。

D3DXCreateContext 関数と D3DXCreateContextEx 関数の両者には、デフォルト デバイスを作成するためのパラメータがある。しかし、高度なゲームやアプリケーションでは、ユーザーがこれまでに使用したことのあるグラフィックをカスタマイズできるように、すべてのデバイスを列挙する。


Direct3DX デバイスの問い合わせ

Direct3DX ユーティリティ ライブラリ関数を使用してデバイスで実行可能なビデオ モード クエリとサーフェス フォーマット クエリについて説明する。

次のメソッドを使用すれば、特定のデバイスでサポートされているさまざまなビデオ モードを問い合わせることができる。

  • D3DXGetCurrentVideoMode
  • D3DXGetMaxNumVideoModes
  • D3DXGetVideoMode

次のコードは、あるデバイスでサポートされているビデオ モードを順番に参照する。

    dwNumVidModes = D3DXGetMaxNumVideoModes( D3DX_DEFAULT,
                                             D3DX_GVM_REFRESHRATE );
    D3DX_VIDMODEDESC VidMode;

    for( i = 0; i<dwNumVidModes; i++ )
    {
        hr = D3DXGetVideoMode( D3DX_DEFAULT, D3DX_GVM_REFRESHRATE, i,
                               &VidMode );
    }

この例では、D3DX_GVM_REFRESHRATE フラグを使用して、ディスプレイ デバイスにより指定されているリフレッシュ レートを取得する。

現在のビデオ モードの設定値を取得する場合は、次のコードを使用する。

    D3DX_VIDMODEDESC CurrVidMode;
    D3DXGetCurrentVideoMode( D3DX_DEFAULT, &CurrVidMode );

D3DXGetDeviceCaps 関数を使用すれば、Direct3DX デバイスの能力を問い合わせることができる。D3DXGetDeviceCaps 関数からは、DirectDraw サーフェスの能力と共に Direct3D デバイスの能力が返される。また、多くのビデオ カードにはビデオ モードを基にさまざまな能力があるので、D3DXGetDeviceCaps 関数では入力パラメータとして D3DX_VIDMODEDESC 構造体を使用する。

次のコードでは、デバイスの能力を取得する。

    DDCAPS DDHELCaps;
    DDCAPS DDHALCaps;
    D3DDEVICEDESC7 D3DCaps;
    hr = D3DXGetDeviceCaps( D3DX_DEFAULT,
                            NULL,
                            &D3DCaps,
                            &DDHALCaps,
                            &DDHELCaps );

また、さまざまなサーフェス クラスの Direct3DX デバイスによりサポートされている既知のサーフェス フォーマットに関する情報を要求できる。

  • 既知のサーフェス フォーマットについては、D3DX_SURFACECLASS により列挙されるタイプを参照すること。
  • Direct3DX によりサポートされているさまざまなサーフェス フォーマットについては、D3DX_SURFACEFORMAT により列挙されるタイプを参照すること。

次のメソッドを使用すれば、Direct3DX デバイスのサポート サーフェス フォーマットを問い合わせることができる。

  • D3DXGetMaxSurfaceFormats
  • D3DXGetSurfaceFormat

次のコードは、あるデバイスでサポートされているサーフェス フォーマットを順番に参照する。

    DWORD dwNumSurfaceFormats =
    D3DXGetMaxSurfaceFormats( D3DX_DEFAULT, NULL, D3DX_SC_COLORTEXTURE);

    D3DX_SURFACEFORMAT SurfaceFormat;
    for( i=0; i<dwNumSurfaceFormats; i++ )
    {
        hr = D3DXGetSurfaceFormat( D3DX_DEFAULT, NULL, D3DX_SC_COLORTEXTURE,
                                   i, &SurfaceFormat );
    }

この例では、D3DX_SC_COLORTEXTURE フラグを使用して、色情報があり、またテクスチャ マップで使用できるサーフェスをすべて指定している。


Direct3DX 行列スタック

Direct3DX ユーティリティ ライブラリでは、COM オブジェクトから行列スタックを操作する。

ここでは、次のトピックについて説明する。

  • 行列スタックとは?
  • シーン階層の実装


行列スタックとは?

Direct3DX ユーティリティ ライブラリは、ID3DXMatrixStack インターフェイスを提供している。これは、行列スタックに対して行列をプッシュしたり、ポップするための機能である。行列スタックを実装すると、変換階層をたどりながら行列を効率的に追跡できる。

Direct3DX ユーティリティ ライブラリは、行列スタックを使用して変換操作を行列として保存する。ID3DXMatrixStack インターフェイスのさまざまなメソッドでは、現在の行列や、スタックの一番上にある行列を使用する。現在の行列をクリアするには、ID3DXMatrixStack::LoadIdentity メソッドを使用する。現在のトランスフォーム行列としてロードする特定の行列を明示的に指定する必要がある場合は、ID3DXMatrixStack::LoadMatrix メソッドを使用する。現在の行列を指定した行列により乗算するには、ID3DXMatrixStack::MultMatrix メソッドまたは ID3DXMatrixStack::MultMatrixLocal メソッドのいずれかを呼び出す。

ID3DXMatrixStack::Pop メソッドを使用すれば前のトランスフォーム行列に戻ることが可能であり、またID3DXMatrixStack::Push メソッドを使用すればトランスフォーム行列をスタックに追加できる。

行列スタックの個別の行列は、Direct3DX ユーティリティ ライブラリの D3DXMATRIX 構造体により定義された 4 × 4 同次行列として表される。


シーン階層の実装

行列スタックを使用すれば、階層モデルの構築が容易になるので、より単純な一連のオブジェクトから複雑なオブジェクトを構築できる。

シーン (または変換) 階層は、通常ツリー データ構造により表される。ツリー データ構造の各ノードに、行列が 1 つずつ格納されている。特定の行列は、ノードの親から子への座標系における変化を表している。たとえば、人間の腕をモデリングする場合は、次の階層を実装する。

この階層で、Body 行列は身体をワールドに配置する。UpperArm 行列には肩の回転、LowerArm 行列には肘の回転、そして Hand 行列には手首の回転が格納される。ワールドに対する手の相対的位置を判定するには、ただ Body から Hand までの行列をすべて乗算するだけでよい。

この階層は、各ノードに子ノードが 1 つずつしかなく、とても単純である。手をもっと細かくモデリングする場合は、5 本の指を追加する。それぞれの指は、Hand の子として階層に追加できる。

ここで、シーンを描画するために深度優先順序 (1 つのパスをできる限り深いノードまでたどり、それから別の分岐先をたどる) で腕の形状全体をたどる場合は、セグメント化されたレンダリングのシーケンスを実行する。たとえば、手と指をレンダリングするには、次のパターンを実装する。

  1. 行列スタックに Hand 行列をプッシュする。
  2. 手を描画する。
  3. 行列スタックに Finger 1 行列をプッシュする。
  4. 第 1 指を描画する。
  5. Finger 1 行列をスタックからポップする。
  6. 行列スタックに Finger 2 行列をプッシュする。
  7. 第 2 指を描画する。
  8. Finger 2 行列をスタックからポップする。
  9. 行列スタックに Finger 3 行列をプッシュする。このように、すべての指をレンダリングするまで処理を続ける。

指のレンダリングが完了したら、Hand 行列をスタックからポップする。

例として、この基本処理のコードを示す。ツリー データ構造の深度優先検索時にノードが出現したら、その行列を行列スタックの一番上にプッシュする。

MatrixStack->Push();
MatrixStack->MultMatrix(pNode->matrix);

ノードの操作が終了したら、その行列を行列スタックの一番上からポップする。

MatrixStack->Pop();

このように、行列スタックの一番上の行列が常にカレント ノードのワールド トランスフォームを表している。そのため、各ノードを描画する前に、Direct3D 行列を設定する必要がある。

pD3DDevice->SetTransform(D3DTRANSFORMSTATE_WORLD, *MatrixStack->GetTop());

Direct3DX 行列スタックで実行可能な特定のメソッドの詳細については、「ID3DXMatrixStack」を参照すること。


ハードウェア アクセラレート レベル

ここでは、Direct3DX ユーティリティ ライブラリについてハードウェア アクセラレート レベルの概念を紹介し、一般的な使用法をいくつか説明する。

  • ハードウェア アクセラレート レベルについて
  • ハードウェア アクセラレート レベルのテスト

ハードウェア アクセラレート レベルのリファレンス リストについては、「ハードウェア アクセラレート レベル定数」を参照すること。


ハードウェア アクセラレート レベルについて

Direct3DX ハードウェア アクセラレート レベル定数は、実際のデバイス インデックスが必要な場合に使用可能な事前に定義されたインデックスである。たとえば、ハードウェア アクセラレート レベル定数は、ID3DXContext::GetDeviceIndex メソッドで使用できる。各定数は、ハードウェア アクセラレートのさまざまなレベルを示している。

ハードウェア アクセラレート レベル定数は、グローバルな D3DXGetDeviceDescription 関数により取得される明示的なデバイス インデックスの代わりに使用する。

DirectDraw プライマリ デバイス上の Direct3DX デバイスのいずれかに要求されたハードウェア アクセラレート レベルがサポートされている場合は、それが使用される。サポートされていない場合は、Direct3DX で検索して最初に一致したデバイスが使用される。もちろん、特定のシステムでハードウェア アクセラレート レベル定数のいずれについても、一致したデバイスが存在しない可能性もある。このような値を Direct3DX API に渡しても、ただ API で障害が発生し、一致しなければ受け付け不可であることが報告されるだけである。

ハードウェア アクセラレート レベル定数をデバイス インデックスとして使用してもよいのは、ハードウェア アクセラレートの特定のレベルがアプリケーションにより要求された場合に、コンピュータ上に複数のデバイスがあってそのどれを使用してもかまわないときだけである。


ハードウェア アクセラレート レベルのテスト

アプリケーションの中には、さまざまなハードウェア アクセラレート レベルに対して特定のデバイスをテストしなければならないものもある。

DescribeDevice( DWORD index )
{
    D3DX_DEVICEDESC devDesc;

    hr = D3DXGetDeviceDescription( index, &devDesc );

    if (D3DX_HWLEVEL_2D == devDesc.hwLevel)
    {
        // 何か処理を行う。
    }
    else if (D3DX_HWLEVEL_RASTER == devDesc.hwLevel)
    {
        // 何か処理を行う。
    }
    else if (D3DX_HWLEVEL_REFERENCE == devDesc.hwLevel)
    {
        // 何か処理を行う。
    }
    else if (D3DX_HWLEVEL_TL == devDesc.hwLevel)
    {
        // 何か処理を行う。
    }
    else    // D3DX_DEFAULT == devDesc.hwLevel
        // 何か処理を行う。

このコードでは、デバイス インデックスを使用して、そのデバイスについて記述したハードウェア アクセラレート フラグを検索している。


スプライトのサポート

Direct3DX ユーティリティ ライブラリにより提供されているスプライト ヘルパーのアプリケーション プログラミング インターフェイス (API) を使用すれば、3D ハードウェアを使用して 2D スタイルのスプライトをレンダリングできる。スプライト レンダリングは 3D ハードウェア用に設計されているので、パフォーマンス面からソフトウェア エミュレーションで使用することはお勧めしない。

スプライトは、その下の背景イメージを邪魔することなく操作可能なオブジェクトである。Direct3DX ユーティリティ ライブラリの用語では、スプライトはレンダリング ターゲットに転送可能な 2D イメージとして大まかに定義される。

ここでは、スプライトでの操作に Direct3DX ユーティリティ ライブラリを使用するときにアプリケーションで実行される共通のタスクについて説明する。

  • スプライトを描画するための準備
  • 単純なスプライトの描画
  • トランスフォームされたスプライトの描画

Direct3DX ユーティリティ ライブラリにより提供されているスプライト機能の詳細については、「スプライト ヘルパー関数」を参照すること。


スプライトを描画するための準備

ここでは、Direct3DX ユーティリティ ライブラリを使用してスプライトを描画する前に必要な準備について、詳しく説明する。

レンダリング ターゲットにスプライトを転送する前に、適切なメソッドを呼び出して、シーンを開始し、レンダリング ターゲットをクリアする。

    hr = m_pd3dDevice->BeginScene();

    hr = m_pd3dx->Clear(D3DCLEAR_TARGET|D3DCLEAR_ZBUFFER);

スプライトをレンダリングするために、D3DXPrepareDeviceForSprite 関数を呼び出してラスタライザを初期化する。一般に、この関数はレンダリングするすべてのスプライトに対して一度呼び出すだけでよい。ただし、レンダリング状態が D3DXDrawSpriteSimple 呼び出しの範囲外で変更される場合は、D3DXPrepareDeviceForSprite を再度呼び出す必要がある。

    ::D3DXPrepareDeviceForSprite(m_pd3dDevice);

ソース テクスチャ上のどこにスプライトを表示するかを定義する RECT 構造体をセットアップする。

    RECT srcRect;

スプライトを使用する場合、イメージはピクチャのグリッドから構成されることがよくある。この場合、ソースの RECT 構造体はフレームごとに異なる小矩形となる。たとえば、ピクチャのグリッドが 10 列と 6 行とする。x 座標を判定するには m_currentFrame % 10 (ただし、m_currentFrame はカレント フレーム) を計算する。y 座標を判定するには m_currentFrame / 10 を計算する。

    int iX = (m_currentFrame % 10);
    int iY = (m_currentFrame / 10);

各フレームは 64 ピクセル×64 ピクセルのセルに区切られる。

    srcRect.left = iX * 64;
    srcRect.top  = iY * 64;

ソースの RECT 構造体の各サブフレームは、幅が 64 ピクセルで、高さが 48 ピクセルである。

    srcRect.right  = srcRect.left + 64;
    srcRect.bottom = srcRect.top  + 48;

ここで、カレント ビューポートを取得する。

    D3DVIEWPORT7 viewport;
    hr = m_pd3dDevice->GetViewport(&viewport);

次に、このビューポートを RECT 構造体に変換する。

    RECT rectViewport;
    rectViewport.left   = viewport.dwX;
    rectViewport.top    = viewport.dwY;
    rectViewport.right  = viewport.dwX + viewport.dwWidth;
    rectViewport.bottom = viewport.dwY + viewport.dwHeight;

非回転レンダリング ターゲットをビューポートの中心とする。

    D3DXVECTOR3 pointDest;
    pointDest.x = (float)viewport.dwX + (float)viewport.dwWidth  / 2.0f;
    pointDest.y = (float)viewport.dwY + (float)viewport.dwHeight / 2.0f;

この時点で、Direct3DX ユーティリティ ライブラリにより提供されているスプライト描画関数のいずれかを呼び出せば、スプライトを描画できる。

  • D3DXDrawSpriteSimple
  • D3DXDrawSpriteTransform
  • D3DXDrawSprite3D

スプライトの描画方法については、「単純なスプライトの描画」および「トランスフォームされたスプライトの描画」を参照すること。

スプライトを描画した後、適切なメソッドを呼び出してシーンを終了し、フレームを更新すること。

    hr = m_pd3dDevice->EndScene();

    hr = m_pd3dx->UpdateFrame(D3DX_DEFAULT);


単純なスプライトの描画

単純なスプライトを描画するときに Direct3DX ユーティリティ ライブラリがどのように役に立つかを示す。

次のコードは、単純なスプライトを描画する。

    hr = ::D3DXDrawSpriteSimple(
            m_ptex,                     // テクスチャ
            m_pd3dDevice,               // 3D デバイス
            &pointDest,                 // 宛先の点 (中心)
            (float)m_dwAlpha/255.0f,    // アルファ
            m_fScaleCurrent,            // スケール
            m_fRotationCurrent,         // 回転
            NULL,                       // オフセット
            &srcRect                    // ソースの小矩形
            );

このコードでは、D3DXDrawSpriteSimple 関数によるスプライトの描画方法を示している。この関数では、スケーリング、回転、アルファ ブレンディング、モニタリング、配置の機能がサポートされている。シャーリングやパースペクティブなどより広い範囲のエフェクトについては、D3DXDrawSpriteTransform 関数を使用すること。


トランスフォームされたスプライトの描画

ここでは、Direct3DX ユーティリティ ライブラリを使用して、トランスフォームされたスプライトを描画する方法について詳しく説明する。

次のコードでは、スケーリングによりトランスフォームされたスプライトを構築して、描画する。

    D3DXMATRIX matScale;
    D3DXMatrixScaling(&matScale, m_fScaleCurrent, m_fScaleCurrent, 1);

    D3DXMATRIX matTransform;
    D3DXBuildSpriteTransform(&matTransform, &rectViewport, m_fRotationCurrent);

    D3DXMATRIX mat;
    mat = matScale * matTransform;

    hr = ::D3DXDrawSpriteTransform(
            m_ptex,         // テクスチャ
            m_pd3dDevice,   // 3D デバイス
            &mat,           // 行列
            (BYTE)m_dwAlpha,// アルファ
            &srcRect        // ソースの小矩形
            );

次のコードでは、回転、平行移動、およびスケーリングによりトランスフォームされたスプライトを構築して、描画する。

    D3DXMATRIX matScaleToSize;
    D3DXMatrixScaling(&matScaleToSize, 64, 48, 1);

    D3DXMATRIX matRotate;
    D3DXMatrixRotationZ(&matRotate, m_fRotationCurrent);

    D3DXMATRIX matTranslate;
    D3DXMatrixTranslation(&matTranslate, (float)pointDest.x, (float)pointDest.y, 0);

    D3DXMATRIX matScale;
    D3DXMatrixScaling(&matScale, m_fScaleCurrent, m_fScaleCurrent, 1);

    D3DXMATRIX mat;
    mat = matScaleToSize * matRotate * matScale * matTranslate;

    hr = ::D3DXDrawSpriteTransform(
           m_ptex,         // テクスチャ
           m_pd3dDevice,   // 3D デバイス
           &mat,           // 行列
           (BYTE)m_dwAlpha,// アルファ
           &srcRect        // ソースの小矩形
           );


テクスチャ マップのサポート

ここでは、Direct3DX ユーティリティ ライブラリにより提供されているテクスチャ マップのサポートについて説明する。

  • Direct3DX テクスチャの理解
  • テクスチャ ファイルの理解
  • テクスチャの作成
  • テクスチャのロード
  • キューブ マップ テクスチャの作成
  • ミップマップの生成
  • フィルタリング オプションの理解

Direct3DX ユーティリティ ライブラリにより提供されているテクスチャ マップ機能の詳細については、「テクスチャ関数」を参照すること。


Direct3DX テクスチャの理解

Direct3DX ユーティリティ ライブラリは、できる限り高いハードウェアからの独立性を実現するために、広範囲のテクスチャ マップ機能を提供している。Direct3DX は、選択されたデバイスの能力を自動的に検索し、そのデバイスと互換性のあるテクスチャを構築する。

テクスチャは、システム上の 3D ハードウェアで使用するために特別に作成された DirectDrawSurface オブジェクトである。Direct3DX ユーティリティ ライブラリを使用してテクスチャを作成すれば、そのテクスチャはハードウェアでまずサポートされる。

Direct3DX ユーティリティ ライブラリのテクスチャ マップ機能を使用すれば、次の操作が可能になる。

  • テクスチャ フォーマットの変換。
  • キューブ マップ テクスチャの作成。
  • テクスチャの作成、ファイルからのロード。
  • テクスチャの作成。
  • ミップマップの生成。
  • フィルタリング。
  • サーフェスからのテクスチャのロード。

D3DX_SURFACEFORMAT 標準テクスチャ タイプのいずれかでテクスチャを作成した場合、Direct3DX ユーティリティ ライブラリを使用すればその他すべての標準テクスチャ タイプに変換できる。標準テクスチャ タイプには、16 ビットと 32 ビットの ARGB、フルセットの RGB タイプ、いくつかの圧縮フォーマットなどが含まれる。


テクスチャ ファイルの理解

Direct3DX ユーティリティ ライブラリを使用すれば、BMP、DIB、TGA、および DDS のファイル フォーマットからテクスチャをロードできる。テクスチャはロードされてから、カレント ラスタライザの制約に合ったサイズとフォーマットに変換される。このように、Direct3DX ユーティリティ ライブラリを使用すればテクスチャを簡単に作成、操作できる。

テクスチャ作成関数から返される IDirectDrawSurface7 インターフェイスへのポインタは、IDirect3DDevice7::SetTexture メソッドで直接使用できる。

イメージのサイズを変更する必要がある場合、そのイメージはバイリニア フィルタリングによりサーフェス全体を覆うように伸ばされる。

発生する可能性があるサイズ変更エラーを回避するために 256×256 (またはそれ以下) の平方のテクスチャを 2 つ使用することをお勧めする。Direct3DX がカレント ハードウェアで操作するために特定のテクスチャを変更する必要があるかどうかは、D3DXCheckTextureRequirements 関数を使用して判断する。

サイズやフォーマットの変更が必要な場合、パフォーマンスが低下する可能性がある。広範囲のハードウェア プラットフォームでイメージの品質を最大限に保つためには、24 ビットの RGB または 32 ビットの ARGB を使用する。


テクスチャの作成

Direct3DX ユーティリティ ライブラリを使用すると、D3DXCreateTexture 関数によりテクスチャを「空の」テクスチャとして作成できる (各ピクセルは 0 値により初期化される)。

また、BMP、DIB、TGA、および DDS ファイル フォーマットのロードをサポートした D3DXCreateTextureFromFile 関数を使用すれば 1 回の呼び出しでテクスチャをロードし、作成することもできる。

たとえば、次の呼び出しではビットマップ ファイル (texture.bmp) がロードされる。

    IDirectDrawSurface7 *m_ptex;
    m_pd3dDevice = m_pd3dx->GetD3DDevice();

    hr = D3DXCreateTextureFromFile(
            m_pd3dDevice,
            NULL,                   // dwFlags
            NULL,                   // 自動設定幅
            NULL,                   // 自動設定高さ
            NULL,                   // 自動設定サーフェス タイプ
            NULL,                   // Palette へのポインタ
            &m_ptex,                // 返されるテクスチャへのポインタ
            NULL,                   // 返されるミップマップ数
            "texture.bmp",          // テクスチャのファイル名
            D3DX_FT_DEFAULT);       // デフォルトのスケーリング

ただし、D3DXCreateTextureFromFile 関数により作成されたサーフェスは、ラスタライズ デバイスの要件に合わせるためにサイズやフォーマットが変更されている。結果として、このように作成されたサーフェスでは、高さ、幅、ミップマップ レベル、そしてサーフェスのピクセル フォーマットでさえデバイスごとに異なる可能性があるので、IDirectDrawSurface7::Lock を呼び出すことはお勧めしない。

D3DXCreateTexture 関数や D3DXCreateTextureFromFile 関数により作成されたサーフェスにピクセルを転送するときは、D3DXLoadTextureFromSurface 関数や D3DXLoadTextureFromFile 関数を使用することをお勧めする。これらの関数は、さまざまなフォーマットをすべて処理し、適切な再サンプリング操作を実行するように設計されている。


テクスチャのロード

D3DXLoadTextureFromSurface 関数と D3DXLoadTextureFromFile 関数は、既存のテクスチャを新しいデータにより更新するためのパラメータがある。たとえば、次のコードは D3DXLoadTextureFromFile 関数呼び出しによりテクスチャをロードする。

    hr = D3DXLoadTextureFromFile(
        m_pD3DDev,
        pFace,                      // ロード先
        D3DX_DEFAULT,               // すべてのミップ レベル
        pszTex,                     // ロード元
        NULL,                       // ロード元全体
        NULL,                       // ロード先全体
        D3DX_FT_DEFAULT);

RECT 構造体パラメータを使用する場合 (たとえば、ロード先矩形の一部またはロード元矩形の一部のみを更新したい場合)、Direct3DX ユーティリティ ライブラリにより提供されているシナリオのヘルパー機能を使用すれば、ロード元矩形やロード先矩形のサイズがラスタライザの制約により変更されることはない。

Direct3DX は RECT 構造体を自動的に解釈し任意のサイズ変更を行うので、アプリケーションではまるでテクスチャをサイズ変更していないように RECT 構造体をセットアップするとよい。アプリケーションは、この簡単な方法により Direct3DX でのサイズ変更処理を無視できる。ただし、Direct3DX を使用しないでサーフェスを作成する場合は、RECT 構造体がそのサーフェスの実ピクセル サイズに対応していなければならない。


キューブ マップ テクスチャの作成

キューブ マップ テクスチャの作成処理は、通常のテクスチャの作成処理と似ている。ただし、通常のテクスチャ属性のほかに、キューブ マップのどのサーフェスを作成するかを指定できる。

次のコードでは、D3DXCreateCubeMapTexture 関数を使用してキューブ マップ テクスチャを作成する。

    DWORD w = 256, h = 256;
    D3DX_SURFACEFORMAT sf = D3DX_SF_A8R8G8B8;

    hr = D3DXCreateCubeMapTexture(
                    m_pD3DDev,
                    0,                              // フラグ
                    DDSCAPS2_CUBEMAP_ALLFACES,      // サーフェス
                    0,                              // 空のサーフェスの色
                    &w,                             // 幅
                    &h,                             // 高さ
                    &sf,                            // サーフェス フォーマット
                    NULL,                           // パレット
                    &m_pEnvTex,                     // 結果のサーフェス
                    NULL);                          // ミップマップ レベル数

ここで、キューブ マップのサーフェスをロードする。

    DDSCAPS2 ddsCaps;
    ZeroMemory(&ddsCaps, sizeof(ddsCaps));
    for (i = 0; i < 6; i++)
    {
        DWORD FacesArray[] =
        {
            DDSCAPS2_CUBEMAP_POSITIVEX,
            DDSCAPS2_CUBEMAP_NEGATIVEX,
            DDSCAPS2_CUBEMAP_POSITIVEY,
            DDSCAPS2_CUBEMAP_NEGATIVEY,
            DDSCAPS2_CUBEMAP_POSITIVEZ,
            DDSCAPS2_CUBEMAP_NEGATIVEZ
        };

キューブ マップの各サーフェスにファイル インデックスをマッピングする。

        DWORD FileIndex[] =
        {
            2, 0, 5, 4, 1, 3
        };

次のコードを使用して、正しいサーフェスを検索する。

        LPDIRECTDRAWSURFACE7 pFace;
        if (i != 0)
        {
            ddsCaps.dwCaps2 = FacesArray[i];
            if (FAILED(hr = m_pEnvTex->GetAttachedSurface(&ddsCaps, &pFace)))
                return hr;
        }

最後に、特別なケースである 0 サーフェスのキューブ マップを補正する必要がある。0 サーフェスのキューブ マップは、最上位の環境マップと同じである。

        else
        {
            pFace = m_pEnvTex;
            pFace->AddRef();
        }

デフォルトでは、キューブ マップの 6 サーフェスすべてが作成される。また、空のサーフェスで使用する色を指定することもできる。これにより、キューブ マップのサーフェスのいくつかが 1 つの色で適切に表されるときはメモリを節約できる。たとえば、キューブ マップ セットを使用して高速道路の照明から自動車のボンネットに対する反射をシミュレートする場合、必要なのは POSITIVE_Y サーフェスだけである。残りのサーフェスは、黒色で作成できる。


ミップマップの生成

デフォルトで、Direct3DX ユーティリティ ライブラリにより提供されているテクスチャ作成メソッドは、ラスタライザがミップマップをサポートしている限りテクスチャのミップマップを生成する。ただし、D3DX_TEXTURE_NOMIPMAP フラグを使用すればミップマップの生成を無効にできる。

次のコードは、D3DX_TEXTURE_NOMIPMAP フラグを設定して、ミップマップをサポートしないテクスチャを作成する。

    DWORD flags = D3DX_TEXTURE_NOMIPMAP;
    pFlags = &flags;

    hr = D3DXCreateTexture(
            pd3dDevice,         // 渡される d3ddevice
            pFlags,             // オプションのロード
            pWidth,             // 幅
            pHeight,            // 高さ
            pTmpPixelFormat,    // 目的のピクセル フォーマット
            NULL,               // パレット
            &pSurf,             // 返されるサーフェス
            pNumMipMaps);       // ミップマップ レベル数

次のコードは、作成されたテクスチャに対し、ミップマップがサポートされているかどうかを問い合わせる。

    DDCAPS ddcaps;
    ZeroMemory(&ddcaps, sizeof(ddcaps));
    ddcaps.dwSize = sizeof(ddcaps);

    hr = pDD->GetCaps(&ddcaps, NULL);
    if (SUCCEEDED(hr))
    {
    // ミップマップがサポートされているかどうかをチェックする。
        if (!(*pFlags & D3DX_TEXTURE_NOMIPMAP))
        {
            if (!(ddcaps.ddsCaps.dwCaps & DDSCAPS_MIPMAP))
            {
                // ミップマップを無効にする。
                *pFlags |= D3DX_TEXTURE_NOMIPMAP;
            }
        }
    }

D3DXLoadTextureFromSurface 関数と D3DXLoadTextureFromFile 関数を使用すれば、更新したい特定のミップマップ レベルを指定できる。ミップマップ レベルとして D3DX_DEFAULT を指定すると、最上位のレベルが更新されるので、その他のミップマップ レベルはそれに合わせて自動的に更新される。

ミップマップの個別のレベルを細かく更新しければならないアプリケーションでは、明示的なミップマップ レベルを Direct3DX テクスチャ ロード メソッドに渡す。また、IDirectDrawSurface7::Blt メソッドや IDirectDrawSurface7::Lock メソッドを直接使用してサーフェスを修正するアプリケーションは、必要に応じてミップマップ レベルを更新する。


フィルタリング オプションの理解

Direct3DX ユーティリティ ライブラリは、バイリニア フィルタリング (D3DX_FT_LINEAR) とポイント サンプリング フィルタリング (D3DX_FT_POINT) の 2 種類のフィルタリングをサポートしている。より品質の高いサイズ変更やミップマップ生成が必要な場合は、バイリニア フィルタリング (D3DX_FT_LINEAR) を選択する。より高速の処理が必要な場合は、ポイント サンプリング フィルタリング (D3DX_FT_POINT) を選択する。

注 : いくつかの特別なケースでは、内部にテキストがあるイメージでぼやけないようにするために、ポイント サンプリングを使用してミップマップ化を無効にするとよい。


簡単なジオメトリ図形

形状描画関数のいずれかを使用して形を作成した場合、ID3DXSimpleShape COM インターフェイスへのポインタ アドレスがパラメータで返される。このインターフェイスを使用すれば、頂点情報 (頂点バッファに格納) やインデックス情報を取得できる。

  • ID3DXSimpleShape::GetIndices
  • ID3DXSimpleShape::GetVB

形状を描画するには、ID3DXSimpleShape インターフェイスで ID3DXSimpleShape::Draw メソッドを呼び出す。

Direct3DX ユーティリティ ライブラリにより提供されている 3D 形状描画アプリケーション プログラミング インターフェイス (API) を使用すれば、次の簡単なジオメトリ図形を描画できる。

  • 立方体
  • 円柱/円錐
  • トーラス
  • N 角形ポリゴン
  • 球体
  • ティーポット

形状を作成する前に、テクスチャ座標の数を指定できる。そうすると、Direct3DX により頂点バッファに適切な領域が割り当てられる。

詳細については、「形状描画関数」を参照すること。


3D 算術のサポート

Direct3DX ユーティリティ ライブラリの算術関数では、3D グラフィックで一般に使用される算術演算がすべてサポートされている。C++ プログラマは、一般的な 3D データ タイプについて拡張可能で、また柔軟性のあるテンプレート クラスを使用できる。

次のクラスが実装されている。

  • D3DXCOLOR
  • D3DXMATRIX
  • D3DXPLANE
  • D3DXQUATERNION
  • D3DXVECTOR2
  • D3DXVECTOR3
  • D3DXVECTOR4

注 : このデータ タイプは、C++ ではクラスであり、C では構造体である。

詳細については、「算術関数」および「C++ 固有の機能」を参照すること。


Direct3DX ユーティリティ ライブラリ リファレンス

ここでは、Direct3DX ユーティリティ ライブラリが提供するアプリケーション プログラミング インターフェイス (API) 要素のリファレンス情報を記述する。リファレンス情報は、次のカテゴリに分類される。

  • インターフェイス
  • 関数
  • マクロ
  • 構造体
  • C++ 固有の機能
  • 列挙型
  • ハードウェア アクセラレート レベル定数
  • 戻り値


インターフェイス

ここでは、Direct3DX ユーティリティ ライブラリが提供する COM インターフェイスのリファレンス情報を記述する。Direct3DX により提示されているインターフェイスは、次のとおりである。

  • ID3DXContext
  • ID3DXMatrixStack
  • ID3DXSimpleShape


ID3DXContext

アプリケーションは、ID3DXContext インターフェイスの各メソッドを使用して、シーンをレンダリングするために必要なさまざまな Direct3D オブジェクトや DirectDraw オブジェクトをすべてカプセル化する。ここでは、このインターフェイスのメソッドのリファレンスを記述する。

ID3DXContext インターフェイスは、D3DXCreateContext 関数または D3DXCreateContextEx 関数を呼び出して取得する。

ID3DXContext インターフェイスのメソッドは、以下のグループにまとめることができる。

バッファ管理 | GetBackBuffer
 | GetBufferSize
 | GetNumBackBuffers
 | GetPrimary
 | GetZBuffer
 | Resize
情報 | GetDD
 | GetD3D
 | GetD3DDevice
その他 | GetCreationFlags
 | GetDeviceIndex
 | GetNumBits
 | GetRefreshRate
 | UpdateFrame
 | DrawDebugText
サーフェス管理 | RestoreSurfaces
ビューポート | Clear
 | SetClearColor
 | SetClearDepth
 | SetClearStencil
ウィンドウ管理 | GetFocusWindow
 | GetWindow

ID3DXContext インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

PD3DXCONTEXT 型は、ID3DXContext インターフェイスへのポインタとして定義されている。

typedef struct ID3DXContext *PD3DXCONTEXT;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。


ID3DXContext::Clear

ID3DXContext::Clear メソッドは、カレント ビューポートの指定されたサーフェスをクリアする。

HRESULT Clear(
  DWORD ClearFlags
);

パラメータ

ClearFlags
クリアするサーフェスを示すフラグ。このパラメータは、次のパラメータのいくつかを組み合わせて指定できるが、必ず 1 つは指定する必要がある。
D3DCLEAR_TARGET
レンダリング ターゲットをクリアする。
D3DCLEAR_STENCIL
ステンシル バッファをクリアする。
D3DCLEAR_ZBUFFER
深度バッファをクリアする。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DERR_STENCILBUFFER_NOTPRESENT
D3DERR_VIEWPORTHASNODEVICE
D3DERR_ZBUFFER_NOTPRESENT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

レンダリング ターゲットに深度バッファがアタッチされていない場合、D3DCLEAR_ZBUFFER フラグまたは D3DCLEAR_STENCIL フラグを指定すると、このメソッドは失敗する。同様に、深度バッファ フォーマットにステンシル バッファ情報が格納されていない場合に D3DCLEAR_STENCIL フラグを指定すると、このメソッドは失敗する。

このメソッドは、カレント ビューポートに対してクリアを行う。ID3DXContext::SetClearColor メソッドにはビューポートをクリアして設定する色を、ID3DXContext::SetClearDepth メソッドには深度バッファをクリアして設定する値を、ID3DXContext::SetClearStencil メソッドにはステンシル バッファをクリアして設定する値を指定する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::SetClearColor、ID3DXContext::SetClearDepth、ID3DXContext::SetClearStencil


ID3DXContext::DrawDebugText

ID3DXContext::DrawDebugText メソッドは、NULL で終わる文字列をレンダリング バッファに描画する。

HRESULT DrawDebugText(
  float topLeftX,
  float topLeftY,
  D3DCOLOR color,
  LPSTR pString
);

パラメータ

topLeftX
レンダリング ターゲットに描画する文字列の左上角の x 座標。
topLeftY
レンダリング ターゲットに描画する文字列の左上角の y 座標。
color
レンダリング ターゲットに描画する文字列の色を指定する D3DCOLOR 型。
pString
レンダリング ターゲットに描画する NULL で終わる文字列へのポインタ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NULLPOINTER
D3DXERR_FAILEDDRAWTEXT
DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

このメソッドは、開発時のデバッグや情報収集のために提供している。

このメソッドの座標パラメータやカラー (color) パラメータの範囲は、それぞれ 0.0～1.0 である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。


ID3DXContext::GetBackBuffer

ID3DXContext::GetBackBuffer メソッドは、コンテキスト バッファによりカプセル化されたバック バッファを取得する。

LPDIRECTDRAWSURFACE7 GetBackBuffer(
  DWORD dwWhich
);

パラメータ

dwWhich
返されるバック バッファ オブジェクトのインデックス。

戻り値

成功すれば、IDirectDrawSurface7 インターフェイスへのポインタを返す。

失敗すれば、NULL を返す。

注意

コンテキスト オブジェクトによりカプセル化されたバッファでは参照回数が保持されているので注意すること。そのため、アプリケーション終了前やサイズ変更時に、アプリケーションでバッファを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetBufferSize、ID3DXContext::GetNumBackBuffers、ID3DXContext::Resize


ID3DXContext::GetBufferSize

ID3DXContext::GetBufferSize メソッドは、コンテキスト オブジェクトによりカプセル化されたカレント バッファのサイズを返す。

HRESULT GetBufferSize(
  LPDWORD width,
  LPDWORD height
);

パラメータ

width
このメソッドが戻った後、このパラメータはバッファの幅 (ピクセル単位) が格納された DWORD 値をポイントしている。
height
このメソッドが戻った後、このパラメータはバッファの高さ (ピクセル単位) が格納された DWORD 値をポイントしている。

戻り値

S_OK を返す。

注意

コンテキスト オブジェクトによりカプセル化されたバッファでは参照回数が保持されているので注意すること。そのため、アプリケーション終了前やサイズ変更時に、アプリケーションでバッファを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetPrimary、ID3DXContext::Resize


ID3DXContext::GetCreationFlags

ID3DXContext::GetCreationFlags メソッドは、このコンテキスト オブジェクトを作成するときに使用するフラグを取得する。

DWORD GetCreationFlags();

パラメータ

なし。

戻り値

コンテキスト オブジェクトを作成するときに使用するフラグを示す DWORD 値を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateContext、D3DXCreateContextEx


ID3DXContext::GetD3D

ID3DXContext::GetD3D メソッドは、IDirect3D7 インターフェイスへのポインタを取得する。

LPDIRECT3D7 GetD3D();

パラメータ

なし。

戻り値

成功すれば、IDirect3D7 インターフェイスへのポインタを返す。

失敗すれば、NULL を返す。

注意

アプリケーションは、このメソッドにより返された IDirect3D7 インターフェイスを使用して Direct3D 関数を呼び出す。

コンテキスト オブジェクトによりカプセル化された Direct3D オブジェクトでは参照回数が保持されているので注意すること。そのため、アプリケーションで必要なくなったら、アプリケーションで IDirect3D7 インターフェイスを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。


ID3DXContext::GetD3DDevice

ID3DXContext::GetD3DDevice メソッドは、IDirect3DDevice7 インターフェイスへのポインタを取得する。

LPDIRECT3DDEVICE7 GetD3DDevice();

パラメータ

なし。

戻り値

成功すれば、IDirect3DDevice7 インターフェイスへのポインタを返す。

失敗すれば、NULL を返す。

注意

アプリケーションは、このメソッドにより返された IDirect3DDevice7 インターフェイスを使用して Direct3DDevice メソッドを呼び出す。

コンテキスト オブジェクトによりカプセル化された Direct3DDevice オブジェクトでは参照回数が保持されているので注意すること。そのため、アプリケーションで必要なくなったら、アプリケーションで IDirect3DDevice7 インターフェイスを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。


ID3DXContext::GetDD

ID3DXContext::GetDD メソッドは、IDirectDraw7 インターフェイスへのポインタを取得する。

LPDIRECTDRAW7 GetDD();

パラメータ

なし。

戻り値

成功すれば、IDirectDraw7 インターフェイスへのポインタを返す。

失敗すれば、NULL を返す。

注意

アプリケーションは、このメソッドにより返された IDirectDraw7 インターフェイスを使用して DirectDraw メソッドを呼び出す。

コンテキスト オブジェクトによりカプセル化された DirectDraw オブジェクトでは参照回数が保持されているので注意すること。そのため、アプリケーションで必要なくなったら、アプリケーションで IDirectDraw7 インターフェイスを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。


ID3DXContext::GetDeviceIndex

ID3DXContext::GetDeviceIndex メソッドは、デバイスのハードウェア レベルのインデックスを返す。

HRESULT GetDeviceIndex(
  LPDWORD pIndex,
  LPDWORD hwLevel
);

パラメータ

pIndex
このメソッドが戻った後、パラメータは指定したデバイスのインデックスと一致した DWORD 値をポイントしている。
hwLevel
このメソッドが戻った後、パラメータは事前に定義したハードウェア アクセラレート レベル定数のいずれかと一致した DWORD 値をポイントしている。「注意」を参照すること。

戻り値

S_OK を返す。

注意

実際のデバイス インデックスが必要な場合、事前に定義されたハードウェア アクセラレート レベル定数を使用できる。それらは、Direct3DX により実際のインデックス値に変換される。定義済みハードウェア レベルは、アクセラレートのさまざまなレベルにアクセスできる簡単で便利な方法である。この定数リストについては、以下を参照すること。

D3DX_HWLEVEL_REFERENCE
D3DX_HWLEVEL_2D
D3DX_HWLEVEL_RASTER
D3DX_HWLEVEL_TL
D3DX_DEFAULT

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetD3DDevice


ID3DXContext::GetFocusWindow

ID3DXContext::GetFocusWindow メソッドは、関連付けられたフォーカス ウィンドウへのハンドルを取得する。

HWND GetFocusWindow();

パラメータ

なし。

戻り値

関連付けられたフォーカス ウィンドウへのハンドル (HWND) を返す。

注意

フォーカス ウィンドウとは、現在キーボード入力を受け付けているウィンドウである。これは、常にアクティブ ウィンドウ、アクティブ ウィンドウの子孫、または NULL のいずれかである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetWindow


ID3DXContext::GetNumBackBuffers

ID3DXContext::GetNumBackBuffers メソッドは、コンテキスト オブジェクトによりカプセル化されたバック バッファの数を返す。

DWORD GetNumBackBuffers();

パラメータ

なし。

戻り値

バック バッファの数を示す DWORD 値を返す。

注意

コンテキスト オブジェクトによりカプセル化されたバッファでは参照回数が保持されているので注意すること。そのため、アプリケーション終了前やサイズ変更時に、アプリケーションでバッファを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetBackBuffer、ID3DXContext::Resize


ID3DXContext::GetNumBits

ID3DXContext::GetNumBits メソッドは、コンテキスト オブジェクトによりカプセル化された DirectDrawSurface オブジェクトのピクセル フォーマットを記述した値を返す。

HRESULT GetNumBits(
  LPDWORD colorBits,
  LPDWORD depthBits,
  LPDWORD alphaBits,
  LPDWORD stencilBits
);

パラメータ

colorBits
カレント ディスプレイ モードの色深度へのポインタ。
depthBits
z バッファのビット深度へのポインタ。
alphaBits
アルファ バッファのビット深度へのポインタ。
stencilBits
ステンシル バッファのビット深度へのポインタ。

戻り値

S_OK を返す。

注意

stencilBits パラメータは、ステンシル情報の z バッファの各ピクセルにより確保されるビットの数を指定する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetZBuffer


ID3DXContext::GetPrimary

ID3DXContext::GetPrimary メソッドは、コンテキスト オブジェクトによりカプセル化されたフロント バッファを返す。

LPDIRECTDRAWSURFACE7 GetPrimary();

パラメータ

なし。

戻り値

成功すれば、IDirectDrawSurface7 インターフェイスへのポインタを返す。

失敗すれば、NULL を返す。

注意

コンテキスト オブジェクトによりカプセル化されたバッファでは参照回数が保持されているので注意すること。そのため、アプリケーション終了前やサイズ変更時に、アプリケーションでバッファを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetBufferSize、ID3DXContext::Resize


ID3DXContext::GetRefreshRate

ID3DXContext::GetRefreshRate メソッドは、リフレッシュ レートを返す。

DWORD GetRefreshRate();

パラメータ

なし。

戻り値

カレント ディスプレイ モードのリフレッシュ レートを示す DWORD 値を返す。

注意

リフレッシュ レートの値が 0 であれば、アダプタ障害を示す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。


ID3DXContext::GetWindow

ID3DXContext::GetWindow メソッドは、関連付けられたウィンドウへのハンドルを取得する。

HWND GetWindow();

パラメータ

なし。

戻り値

関連付けられたウィンドウへのハンドル (HWND) を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetFocusWindow


ID3DXContext::GetZBuffer

ID3DXContext::GetZBuffer メソッドは、コンテキスト オブジェクトによりカプセル化された z バッファを返す。

LPDIRECTDRAWSURFACE7 GetZBuffer();

パラメータ

なし。

戻り値

IDirectDrawSurface7 インターフェイスへのポインタを返す。

失敗すれば、NULL を返す。

注意

コンテキスト オブジェクトによりカプセル化されたバッファでは参照回数が保持されているので注意すること。そのため、アプリケーション終了前やサイズ変更時に、アプリケーションでバッファを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetBufferSize、ID3DXContext::Resize


ID3DXContext::Resize

ID3DXContext::Resize メソッドは、コンテキスト オブジェクトによりカプセル化されたバッファのディメンジョンを変更する。

HRESULT Resize(
  DWORD width,
  DWORD height
);

パラメータ

width
バッファの新しい幅。
height
バッファの新しい高さ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_CANNOTRESIZEFULLSCREEN
D3DXERR_INVALIDPARAMETER
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE

注意

コンテキスト オブジェクトによりカプセル化されたバッファでは参照回数が保持されているので注意すること。そのため、アプリケーション終了前やサイズ変更時に、アプリケーションでバッファを解放する必要がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::GetBufferSize


ID3DXContext::RestoreSurfaces

ID3DXContext::RestoreSurfaces メソッドは、データが喪失した場合にサーフェスをリストアする。

HRESULT RestoreSurfaces();

パラメータ

なし。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

注意

このメソッドは、プライマリ (フロント バッファ) サーフェス、バック バッファ サーフェス、z バッファ サーフェスをリストアする。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

IDirectDrawSurface7::Restore


ID3DXContext::SetClearColor

ID3DXContext::SetClearColor メソッドは、レンダリング ターゲットのサーフェスをクリアして設定する色を設定する。

HRESULT SetClearColor(
  D3DCOLOR color
);

パラメータ

color
レンダリング ターゲットのサーフェスをクリアして設定する値を示す D3DCOLOR 型。デフォルト値は、0 である。

戻り値

S_OK を返す。

注意

このメソッドで色を指定するとき、次のように D3DRGBA マクロを使用できる。

    hr = m_pD3DX->SetClearColor(D3DRGBA(0.5f,0.0f,0.0f,0));

このメソッドでレンダリング ターゲット サーフェスの色を設定した後、ID3DXContext::Clear メソッドを呼び出せばビューポートをこの色にクリアできる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::Clear、ID3DXContext::SetClearDepth、ID3DXContext::SetClearStencil


ID3DXContext::SetClearDepth

ID3DXContext::SetClearDepth メソッドは、深度バッファ サーフェスをクリアして設定する値を設定する。

HRESULT SetClearDepth(
  float z
);

パラメータ

z
深度バッファに格納される新しい z 値。このパラメータの範囲は 0.0 以上 1.0 以下である (z ベースまたは w ベースの深度バッファ)。値が 0.0 であればビューアへの距離が最も近く、1.0 であれば最も遠い。デフォルト値は、1.0f である。

戻り値

S_OK を返す。

注意

このメソッドにより深度バッファに格納される z 値を設定した後、ID3DXContext::Clear メソッドを呼び出せば、深度バッファ サーフェスをこの値にクリアできる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::Clear、ID3DXContext::SetClearColor、ID3DXContext::SetClearStencil


ID3DXContext::SetClearStencil

ID3DXContext::SetClearStencil メソッドは、ステンシル バッファ サーフェスをクリアして設定する値を設定する。

HRESULT SetClearStencil(
  DWORD dwClearValue
);

パラメータ

dwClearValue
各ステンシル バッファ エントリに格納する DWORD 値。このパラメータの範囲は、0 以上 2n-1 以下である。ただし、n はステンシル バッファのビット深度である。デフォルト値は、0 である。

戻り値

S_OK を返す。

注意

このメソッドによりステンシル値を設定した後、ID3DXContext::Clear メソッドを呼び出せば、ステンシル バッファ サーフェスをこの値にクリアできる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXContext::Clear、ID3DXContext::SetClearColor、ID3DXContext::SetClearDepth


ID3DXContext::UpdateFrame

ID3DXContext::UpdateFrame メソッドは、ページ フリッピングまたはブリットのいずれかによりフレームを更新する。

HRESULT UpdateFrame(
  DWORD flags
);

パラメータ

flags
フレーム更新オプションを指定するフラグ。「注意」を参照すること。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING
DDERR_WRONGMODE

注意

flags パラメータで D3DX_UPDATE_NOVSYNC フラグが設定されている場合に、フルスクリーン モードで垂直同期 (vsync) を待たなければドライバでフリッピングできないとき、ブリットが使用される。

詳細については、フリッピング サーフェスを参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

IDirectDrawSurface7::Blt、IDirectDrawSurface7::Flip


ID3DXMatrixStack

アプリケーションは、行列スタックを使用するとき、ID3DXMatrixStack インターフェイスのメソッドを使用する。ここでは、このインターフェイスのメソッドのリファレンスを記述する。

ID3DXMatrixStack インターフェイスは、D3DXCreateMatrixStack 関数を呼び出して取得する。

ID3DXMatrixStack インターフェイスのメソッドは、以下のグループにまとめることができる。

行列操作 | MultMatrix
 | MultMatrixLocal
その他 | GetTop
 | LoadIdentity
 | LoadMatrix
 | Pop
 | Push
回転 | RotateAxis
 | RotateAxisLocal
 | RotateYawPitchRoll
 | RotateYawPitchRollLocal
スケーリング | Scale
 | ScaleLocal
平行移動 | Translate
 | TranslateLocal

ID3DXMatrixStack インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

Iunknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


ID3DXMatrixStack::GetTop

ID3DXMatrixStack::GetTop メソッドは、スタックの一番上にある現在の行列を返す。

D3DXMATRIX* GetTop();

パラメータ

なし。

戻り値

現在の行列を表す D3DXMATRIX 構造体へのポインタを返す。

注意

このメソッドにより返される D3DXMATRIX ポインタは、それ以降のスタック操作でも有効であるとは保証されていない。

このメソッドは、スタックの一番上から現在の行列を削除しないで、ただ返すだけである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::Pop、ID3DXMatrixStack::Push


ID3DXMatrixStack::LoadIdentity

ID3DXMatrixStack::LoadIdentity メソッドは、現在の行列に単位行列をロードする。

HRESULT LoadIdentity();

パラメータ

なし。

戻り値

S_OK を返す。

注意

単位行列は、[1,1][2,2][3,3][4,4] 係数に 1.0 が設定されていること除いて、すべての係数が 0.0 の行列である。単位行列は、頂点に適用されてもそれらが変更されないという点で特別である。単位行列は、頂点値を変更して回転、平行移動、および 4 × 4 行列で表現できるその他の変換を行う行列の起点として使用される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::LoadMatrix


ID3DXMatrixStack::LoadMatrix

ID3DXMatrixStack::LoadMatrix メソッドは、現在の行列に指定された行列をロードする。

HRESULT LoadMatrix(
  const D3DXMATRIX* pMat
);

パラメータ

pMat
現在の行列にロードされる D3DXMATRIX 構造体へのポインタ。

戻り値

成功すれば S_OK を返し、失敗すれば D3DXERR_NULLPOINTER を返す。

注意

このメソッドは、スタックに項目を追加するのではなく、現在の行列を指定された行列に置き換える。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::LoadIdentity


ID3DXMatrixStack::MultMatrix

ID3DXMatrixStack::MultMatrix メソッドは、現在の行列と指定された行列の積を算出する。

HRESULT MultMatrix(
  const D3DXMATRIX* pMat
);

パラメータ

pMat
現在の行列に積算する D3DXMATRIX 構造体へのポインタ。

戻り値

成功すれば S_OK を返し、失敗すれば D3DXERR_NULLPOINTER を返す。

注意

このメソッドは、現在の行列に指定された行列を積算する (変換は現在のワールド原点を中心として行われる)。

    m_stack[m_currentPos] = m_stack[m_currentPos] * *pMat;

このメソッドは、スタックに項目を追加するのではなく、現在の行列を、現在の行列と指定された行列の積算に置き換える。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::MultMatrixLocal


ID3DXMatrixStack::MultMatrixLocal

ID3DXMatrixStack::MultMatrixLocal メソッドは、指定された行列と現在の行列の積を算出する。

HRESULT MultMatrixLocal(
  const D3DXMATRIX* pMat
);

パラメータ

pMat
現在の行列と積算する D3DXMATRIX 構造体へのポインタ。

戻り値

成功すれば S_OK を返し、失敗すれば D3DXERR_NULLPOINTER を返す。

注意

このメソッドは、指定された行列に現在の行列を積算する (変換はオブジェクトのローカル原点を中心として行われる)。

    m_stack[m_currentPos] = *pMat * m_stack[m_currentPos];

このメソッドは、スタックに項目を追加するのではなく、現在の行列を、指定された行列と現在の行列の積算に置き換える。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::MultMatrix


ID3DXMatrixStack::Pop

ID3DXMatrixStack::Pop メソッドは、スタックの一番上から現在の行列を削除する。

HRESULT Pop();

パラメータ

なし。

戻り値

S_OK を返す。

注意

このメソッドは、スタックの一番上から現在の行列を削除して、行列をスタックの一番上に進めて、スタックの項目カウントを 1 だけ減らす。スタックの現在の項目カウントが 0 の場合、このメソッドは何も処理を行わないで戻る。スタックの現在の項目カウントが 1 の場合、このメソッドはスタックを空にする。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::GetTop、ID3DXMatrixStack::Push


ID3DXMatrixStack::Push

ID3DXMatrixStack::Push メソッドは、行列をスタックに追加する。

HRESULT Push();

パラメータ

なし。

戻り値

成功すれば S_OK を返し、失敗すれば D3DXERR_NOMEMORY を返す。

注意

このメソッドは、現在の行列を複写して、スタックの項目カウントを 1 だけ増やす。項目がもっと追加されると、スタックは動的に拡大される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::GetTop、ID3DXMatrixStack::Pop


ID3DXMatrixStack::RotateAxis

ID3DXMatrixStack::RotateAxis メソッドは、現在の行列と算出された回転行列の積を算出する。

HRESULT RotateAxis(
  const D3DXVECTOR3* pV,
  float angle
);

パラメータ

pV
軸の角度を指定する D3DXVECTOR3 構造体へのポインタ。
angle
回転角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

成功すれば S_OK を返し、失敗すれば D3DXERR_NULLPOINTER を返す。

注意

このメソッドは、現在の行列に算出された回転行列を積算する。これは、指定した軸に対して反時計回りに指定した角だけ回転させる (回転は、現在のワールド原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixRotationAxis( &tmp, pV, angle );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::RotateAxisLocal、ID3DXMatrixStack::RotateYawPitchRoll、ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateAxisLocal

ID3DXMatrixStack::RotateAxisLocal メソッドは、算出された回転行列と現在の行列の積を算出する。

HRESULT RotateAxisLocal(
  const D3DXVECTOR3* pV,
  float angle
);

パラメータ

pV
軸の角度を指定する D3DXVECTOR3 構造体へのポインタ。
angle
回転角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

成功すれば S_OK を返し、失敗すれば D3DXERR_NULLPOINTER を返す。

注意

このメソッドは、算出された回転行列に現在の行列を積算する。これは、指定した軸に対して反時計回りに指定した角だけ回転させる (回転は、オブジェクトのローカル原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixRotationAxis( &tmp, pV, angle );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::RotateAxis、ID3DXMatrixStack::RotateYawPitchRoll、ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateYawPitchRoll

ID3DXMatrixStack::RotateYawPitchRoll メソッドは、現在の行列と算出された回転行列 (指定された偏揺れ角、傾斜角、および回転角により構成される) の積を算出する。

HRESULT RotateYawPitchRoll(
  float yaw,
  float pitch,
  float roll
);

パラメータ

yaw
y 軸の偏揺れ角 (ラジアン単位)。
pitch
x 軸の傾斜角 (ラジアン単位)。
roll
z 軸の回転角 (ラジアン単位)。

戻り値

S_OK を返す。

注意

このメソッドは、現在の行列に算出された回転行列を積算する。すべての角度は反時計回りであり、回転は現在のワールド原点を中心として行われる。

    D3DXMATRIX tmp;

    D3DXMatrixRotationYawPitchRoll( &tmp, yaw, pitch, roll );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::RotateAxis、ID3DXMatrixStack::RotateAxisLocal、ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateYawPitchRollLocal

ID3DXMatrixStack::RotateYawPitchRollLocal メソッドは、算出された回転行列 (指定された偏揺れ角、傾斜角、および回転角から構成される) と現在の行列の積を算出する。

HRESULT RotateYawPitchRollLocal(
  float yaw,
  float pitch,
  float roll
);

パラメータ

yaw
y 軸の偏揺れ角 (ラジアン単位)。
pitch
x 軸の傾斜角 (ラジアン単位)。
roll
z 軸の回転角 (ラジアン単位)。

戻り値

S_OK を返す。

注意

このメソッドは、算出された回転行列に現在の行列を積算する。すべての角度は反時計回りであり、回転はオブジェクトのローカル原点を中心として行われる。

    D3DXMATRIX tmp;

    D3DXMatrixRotationYawPitchRoll( &tmp, yaw, pitch, roll );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::RotateAxis、ID3DXMatrixStack::RotateAxisLocal、ID3DXMatrixStack::RotateYawPitchRoll


ID3DXMatrixStack::Scale

ID3DXMatrixStack::Scale メソッドは、現在の行列と算出されたスケール行列 (指定された点 (x、y、z) から構成される) の積を算出する。

HRESULT Scale(
  float x,
  float y,
  float z
);

パラメータ

x
x 方向のスケーリング コンポーネント。
y
y 方向のスケーリング コンポーネント。
z
z 方向のスケーリング コンポーネント。

戻り値

S_OK を返す。

注意

このメソッドは、現在の行列に算出されたスケール行列を積算する (変換は現在のワールド原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixScaling( &tmp, x, y, z );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::ScaleLocal


ID3DXMatrixStack::ScaleLocal

ID3DXMatrixStack::ScaleLocal メソッドは、算出されたスケール行列 (指定された点 (x、y、z) から構成される) と現在の行列の積を算出する。

HRESULT Scale(
  float x,
  float y,
  float z
);

パラメータ

x
x 方向のスケーリング コンポーネント。
y
y 方向のスケーリング コンポーネント。
z
z 方向のスケーリング コンポーネント。

戻り値

S_OK を返す。

注意

このメソッドは、算出されたスケール行列に現在の行列を積算する (変換はオブジェクトのローカル原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixScaling( &tmp, x, y, z );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::Scale


ID3DXMatrixStack::Translate

The ID3DXMatrixStack::Translate メソッドは、現在の行列と算出された平行移動行列 (指定された係数 (x、y、z) により決定される) の積を算出する。

HRESULT Translate(
  float x,
  float y,
  float z
);

パラメータ

x
x 方向の平行移動係数。
y
y 方向の平行移動係数。
z
z 方向の平行移動係数。

戻り値

S_OK を返す。

注意

このメソッドは、現在の行列に算出された平行移動行列を積算する (変換は、現在のワールド原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixTranslation( &tmp, x, y, z );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::TranslateLocal


ID3DXMatrixStack::TranslateLocal

ID3DXMatrixStack::TranslateLocal メソッドは、算出された平行移動行列 (指定された係数 (x、y、z) により決定される) と現在の行列の積を算出する。

HRESULT TranslateLocal(
  float x,
  float y,
  float z
);

パラメータ

x
x 方向の平行移動係数。
y
y 方向の平行移動係数。
z
z 方向の平行移動係数。

戻り値

S_OK を返す。

注意

このメソッドは、算出された平行移動行列に現在の行列を積算する (変換は、オブジェクトのローカル原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixTranslation( &tmp, x, y, z );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

ID3DXMatrixStack::Translate


ID3DXSimpleShape

ID3DXSimpleShape インターフェイスは、次のグローバル関数のいずれかにより形を描画することにより取得される。

  • D3DXCreateBox
  • D3DXCreateCylinder
  • D3DXCreatePolygon
  • D3DXCreateSphere
  • D3DXCreateTeapot
  • D3DXCreateTorus

ID3DXSimpleShape インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetIndices
 | GetVB
レンダリング | Draw

ID3DXSimpleShape インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

Iunknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。


ID3DXSimpleShape::Draw

ID3DXSimpleShape::Draw メソッドは、形状オブジェクトを描画するときに使用する。

HRESULT Draw();

パラメータ

なし。

戻り値

成功すれば、D3D_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NULLPOINTER
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

注意

この関数は、形状描画関数のいずれかにより生成された頂点バッファを描画するときに使用する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

IDirect3DDevice7::DrawIndexedPrimitive、IDirect3DDevice7::DrawPrimitive


ID3DXSimpleShape::GetIndices

ID3DXSimpleShape::GetIndices メソッドは、形状オブジェクトからインデックス情報を取得するときに使用する。

DWORD GetIndices(
  LPWORD* ppIndices
);

パラメータ

ppIndices
メソッドが戻った後、このパラメータはインデックス リストへのポインタのアドレスを保持している。

戻り値

インデックス リストのインデックス数を返す。

注意

IDirect3DDevice7::DrawIndexedPrimitiveVB メソッドにより描画された形にのみインデックス リストがある。形が IDirect3DDevice7::DrawPrimitiveVB メソッドにより描画されている場合、このメソッドは 0 を返し、ppIndices には NULL を設定する。D3DXCreateBox、D3DXCreateCylinder、D3DXCreatePolygon、D3DXCreateSphere 関数はインデックス リストを使用しないが、D3DXCreateTeapot 関数と D3DXCreateTorus 関数はインデックス リストを使用する。

インデックス リストの値は、レンダリングするジオメトリ図形を作成する場合に、頂点リストにインデックスを設定するとき使用する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

IDirect3DDevice7::DrawIndexedPrimitive


ID3DXSimpleShape::GetVB

ID3DXSimpleShape::GetVB メソッドは、形状オブジェクトから頂点情報を取得するときに使用する。

LPDIRECT3DVERTEXBUFFER7 GetVB();

パラメータ

なし。

戻り値

IDirect3DVertexBuffer7 インターフェイスへのポインタを返す。

注意

このメソッドを使用すると頂点バッファの参照回数が増えるので、終了時に返された頂点バッファに対して Release を呼び出すこと。

形状描画メソッドのいずれかを使用して形を描画するとき、テクスチャ座標の数を指定できる。指定すると、Direct3DX により頂点バッファに適切な領域が割り当てられる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

頂点バッファ


関数

ここでは、Direct3DX ユーティリティ ライブラリで使用される関数へのリンクを示す。

  • 汎用関数
  • 算術関数
  • 形状描画関数
  • スプライト ヘルパー関数
  • テクスチャ関数


汎用関数

Direct3DX ユーティリティ ライブラリにより提供されている汎用関数を使用すれば、デバイス、ビデオ モード、およびサーフェス フォーマットの問い合わせ、Direct3DX のセットアップやシャットダウン、コンテキストの作成、サーフェスやピクセル フォーマットの作成などの多くの基本機能を実行できる。

汎用関数は、以下のグループにまとめることができる。

作成 | D3DXCreateContext
 | D3DXCreateContextEx
デバイス | D3DXGetDeviceCaps
 | D3DXGetDeviceCount
 | D3DXGetDeviceDescription
初期化 | D3DXInitialize
 | D3DXUninitialize
その他 | D3DXGetErrorString
モード | D3DXGetCurrentVideoMode
 | D3DXGetMaxNumVideoModes
 | D3DXGetVideoMode
サーフェス | D3DXGetMaxSurfaceFormats
 | D3DXGetSurfaceFormat
 | D3DXMakeDDPixelFormat
 | D3DXMakeSurfaceFormat


D3DXCreateContext

D3DXCreateContext 関数は、指定されたデバイスを初期化する。

HRESULT D3DXCreateContext(
  DWORD deviceIndex,
  DWORD flags,
  HWND hwnd,
  DWORD width,
  DWORD height,
  LPD3DXCONTEXT* ppCtx
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。このパラメータに D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のあるアクセラレート レベルの最高レベルによりデバイスが初期化される。指定可能なすべての値のリストについては、「ハードウェア アクセラレート レベル定数」を参照すること。
flags
有効なフラグは、D3DX_CONTEXT_FULLSCREEN と D3DX_CONTEXT_OFFSCREEN である。これらのフラグを両方共指定することはできない。フラグを指定しない場合、コンテキストによりデフォルトのウィンドウ モードが適用される。
hwnd
デバイス ウィンドウ。「注意」を参照すること。
width
ウィンドウの幅 (ピクセル単位) または D3DX_DEFAULT。「注意」を参照すること。
height
ウィンドウの高さ (ピクセル単位) または D3DX_DEFAULT。「注意」を参照すること。
ppCtx
選択したデバイスでレンダリングするときに使用するコンテキスト オブジェクトへのポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NOZBUFFER
D3DXERR_NOZBUFFERAVAILABLE
D3DXERR_NULLPOINTER
DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCLIPPERATTACHED
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

注意

アプリケーションがウィンドウ モードで動作している場合、hwnd は有効なウィンドウでなければならない (NULL または D3DX_DEFAULT は指定できない)。また、width または height のいずれかが D3DX_DEFAULT の場合、両方の値に hwnd クライアント領域のディメンジョンのデフォルト値が設定される。

アプリケーションがフルスクリーン モードで動作している場合、hwnd は有効なウィンドウでなければならない (NULL または D3DX_DEFAULT は指定できない)。また、width または height のいずれかが D3DX_DEFAULT の場合、デフォルト値として width には 640 ピクセルが、height には 480 ピクセルが設定される。

アプリケーションがオフスクリーン モードで動作している場合、hwnd は NULL または D3DX_DEFAULT でなければならない。width または height のいずれかが D3DX_DEFAULT の場合は、エラーが返される。

D3DXCreateContext 関数は、使用可能な Direct3DX 初期化関数の中で最も簡単なものである。パラメータは、D3DXCreateContextEx 関数のパラメータの照合サブセットと同じように処理される。D3DXCreateContext 関数にない D3DXCreateContextEx パラメータは、D3DX_DEFAULT として処理される。

メモ D3DXCreateContext 関数で作成されるコンテキストでは、マルチ モニタ システムがサポートされていない。マルチ モニタのサポートについては、D3DXCreateContextEx 関数を参照すること。

すべての関数について、D3DXCreateContext が障害発生時に安全であると考えてはならない。サポートされているデバイスの能力は、パラメータ値を選択するためのガイドとして使用すること。パラメータの組み合わせの中には、うまく動作しないものが必ず存在する。

D3DXCreateContext 関数によりセットアップされるデフォルト射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateContextEx


D3DXCreateContextEx

D3DXCreateContextEx 関数は、指定したデバイスを初期化する。ただし、これは D3DXCreateContext 関数によりも高度な初期化関数である。

HRESULT D3DXCreateContextEx(
  DWORD deviceIndex,
  DWORD flags,
  HWND hwnd,
  HWND hwndFocus,
  DWORD numColorBits,
  DWORD numAlphaBits,
  DWORD numDepthbits,
  DWORD numStencilBits,
  DWORD numBackBuffers,
  DWORD width,
  DWORD height,
  DWORD refreshRate,
  LPD3DXCONTEXT* ppCtx
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。このパラメータに D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のあるアクセラレート レベルの最高レベルによりデバイスが初期化される。指定可能なすべての値のリストについては、ハードウェア アクセラレート レベル定数」を参照すること。
flags
有効なフラグは、D3DX_CONTEXT_FULLSCREEN と D3DX_CONTEXT_OFFSCREEN である。これらのフラグを両方共指定することはできない。フラグを指定しない場合、コンテキストによりデフォルトのウィンドウ モードが適用される。
hwnd
デバイス ウィンドウ。「注意」を参照すること。
hwndFocus
「注意」を参照すること。デバイス ウィンドウからキーボード メッセージを受け取るウィンドウ。デバイス ウィンドウは、フォーカス ウィンドウの子ウィンドウである。このパラメータは、マルチ モニタ アプリケーションで有用である。
numColorBits
カラー ビット数。ウィンドウ モードで D3DX_DEFAULT を指定すると、カレント デスクトップの色深度が選択される。フルスクリーン モードの場合、D3DX_DEFAULT を選択すると、16 ビット カラーが使用される。
numAlphaBits
アルファ チャネルに確保されているビット数。D3DX_DEFAULT を指定すると、0 が選択される。
numDepthbits
深度バッファに確保されているビット数。D3DX_DEFAULT を指定すると、使用可能な深度ビット数の中で最も高い値が選択される。「注意」を参照すること。
numStencilBits
ステンシル バッファに確保されているビット数。D3DX_DEFAULT を指定すると、使用可能なステンシル ビット数の中で最も高い値が選択される。「注意」を参照すること。
numBackBuffers
バック バッファ数、またはD3DX_DEFAULT。「注意」を参照すること。
width
ウィンドウの幅 (ピクセル単位)、またはD3DX_DEFAULT。「注意」を参照すること。
height
ウィンドウの高さ (ピクセル単位)、または D3DX_DEFAULT。「注意」を参照すること。
refreshRate
リフレッシュ レート。ウィンドウ モードとオフスクリーン モードの場合、このパラメータは無視される。D3DX_DEFAULT は、DirectDraw にアプリケーションに合った値を選択させることを意味している。
ppCtx
選択したデバイスのレンダリングで使用するコンテキスト オブジェクトへのポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NOZBUFFER
D3DXERR_NOZBUFFERAVAILABLE
D3DXERR_NULLPOINTER
DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCLIPPERATTACHED
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

注意

アプリケーションがウィンドウ モードで動作している場合、hwnd は有効なウィンドウでなければならない。hwndFocus パラメータは、NULL または D3DX_DEFAULT でなければならない。また、width または height パラメータのいずれかが D3DX_DEFAULT の場合、両方の値に hwnd クライアント領域のディメンジョンのデフォルト値が設定される。numBackBuffers に D3DX_DEFAULT を指定すると、1 が使用される。そのためバック バッファを 1 つ指定する必要がある。

アプリケーションがフルスクリーン モードで動作している場合、hwnd または hwndFocus のいずれかが有効なウィンドウでなければならない (両方共に NULL または D3DX_DEFAULT を指定することはできない)。hwnd が NULL または D3DX_DEFAULT の場合、デフォルト デバイス ウィンドウが hwndFocus の子ウィンドウとして作成される。また、width または height のいずれかが D3DX_DEFAULT の場合、デフォルト値として width には 640 ピクセルが、height には 480 ピクセルが設定される。numBackBuffers に D3DX_DEFAULT を指定すると、1 が使用される。そのためバック バッファを 1 つ指定する必要がある。

アプリケーションがオフスクリーン モードで動作している場合、hwnd と hwndFocus は NULL または D3DX_DEFAULT でなければならない。width または height のいずれかが D3DX_DEFAULT の場合は、エラーが返される。numBackBuffers に D3DX_DEFAULT を指定すると、0 が使用される。そのため、追加のバック バッファを指定でない。

numDepthBits パラメータと numStencilBits パラメータが両方共 D3DX_DEFAULT の場合、Direct3DX はまず使用可能なステンシル ビット数の最高値を選択する。次に、選択したステンシル ビットについて、使用可能な深度ビット数の最高値を選択する。numStencilBits パラメータまたは numDepthBits パラメータのいずれかだけが D3DX_DEFAULT の場合、そのデフォルト パラメータで使用可能なビット数の最高値が、固定パラメータで要求されたビット数をサポートしたフォーマットから選択される。

すべての関数について、D3DXCreateContextEx が障害発生時に安全であると考えてはならない。サポートされているデバイスの能力は、パラメータ値を選択するためのガイドとして使用すること。パラメータの組み合わせの中には、うまく動作しないものが必ず存在する。

D3DXCreateContextEx 関数によりセット アップされるデフォルト射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateContext


D3DXGetCurrentVideoMode

D3DXGetCurrentVideoMode 関数は、指定されたデバイスのカレント ビデオ モードを取得する。

HRESULT D3DXGetCurrentVideoMode(
  DWORD deviceIndex,
  D3DX_VIDMODEDESC* pVidMode
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。このパラメータに D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のある最高のアクセラレート レベルに基づいてデバイスが指定される。
pVidMode
カレント ディスプレイ モードの記述が返される D3DX_VIDMODEDESC 構造体へのポインタ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX
D3DXERR_NULLPOINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXGetMaxNumVideoModes、D3DXGetVideoMode


D3DXGetDeviceCaps

D3DXGetDeviceCaps 関数は、ディスプレイ モードでデバイスのすべての能力を表示する。

HRESULT D3DXGetDeviceCaps(
  DWORD deviceIndex,
  D3DX_VIDMODEDESC* pVidMode,
  D3DDEVICEDESC7* pD3DCaps,
  DDCAPS* pDDHALCaps,
  DDCAPS* pDDHELCaps
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。このパラメータに D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のある最高のアクセラレート レベルに基づいてデバイスが指定される。
pVidMode
ディスプレイ モードを記述した D3DX_VIDMODEDESC 構造体へのポインタ。このパラメータが NULL の場合、Direct3DX はデバイスのカレント ディスプレイ モードでの能力を返す。
pD3DCaps
選択したデバイスの Direct3D 能力を記述した D3DDEVICEDESC7 構造体へのポインタ。NULL を指定すると、このパラメータは無視される。
pDDHALCaps
DirectDraw ハードウェア アブストラクション レイヤ (HAL) 能力を記述した DDCAPS 構造体へのポインタ。NULL を指定すると、このパラメータは無視される。
pDDHELCaps
DirectDraw ハードウェア エミュレーション レイヤ (HEL) 能力を記述した DDCAPS 構造体へのポインタ。NULL を指定すると、このパラメータは無視される。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_CAPSNOTSUPPORTED
D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_FAILEDGETCAPS
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXGetDeviceCount、D3DXGetDeviceDescription


D3DXGetDeviceCount

D3DXGetDeviceCount 関数は、使用可能なDirect3DX デバイスの最大数を返す。

DWORD D3DXGetDeviceCount();

パラメータ

なし。

戻り値

使用可能な Direct3DX デバイスの最大数。

注意

エラーがある場合、この関数は 0 を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXGetDeviceCaps、D3DXGetDeviceDescription


D3DXGetDeviceDescription

D3DXGetDeviceDescription 関数は、指定したデバイスの記述を取得する。

HRESULT D3DXGetDeviceDescription(
  DWORD deviceIndex,
  D3DX_DEVICEDESC* pd3dxDeviceDesc
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。デバイスのインデックスは、0 から始まる。このパラメータで D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のある最高のアクセラレート レベルに基づいてデバイスが指定される。
pd3dxDeviceDesc
指定されたデバイスの能力が設定された D3DX_DEVICEDESC 構造体へのポインタ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX
D3DXERR_NULLPOINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXGetDeviceCaps、D3DXGetDeviceCount


D3DXGetErrorString

D3DXGetErrorString 関数は、HRESULT が設定されたエラー文字列を印刷する。

void D3DXGetErrorString(
  HRESULT hr,
  DWORD strLength,
  LPSTR pStr
);

パラメータ

hr
解読する HRESULT エラー コード。
strLength
渡される文字列の長さ。
pStr
文字列の出力。ただし、渡される文字列は、strLength パラメータで指定された適切な長さでなければならない。

戻り値

なし。

注意

D3DXGetErrorString 関数は、Win32、DirectX 6.0、および Direct3DX のエラー メッセージを印刷する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXGetMaxNumVideoModes

D3DXGetMaxNumVideoModes 関数は、ビデオ モードの最大数を返す。

DWORD D3DXGetMaxNumVideoModes(
  DWORD deviceIndex,
  DWORD flags
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。このパラメータに D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のある最高のアクセラレート レベルに基づいてデバイスが指定される。
flags
このパラメータにより D3DX_GVM_REFRESHRATE フラグが設定されない限り、リフレッシュ レートは無視される。リフレッシュ レートを無視させたい場合、このパラメータに 0 を設定する。

戻り値

成功すれば、ビデオ モードの最大数を返す。

失敗すれば、0 を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXGetCurrentVideoMode、D3DXGetVideoMode


D3DXGetMaxSurfaceFormats

D3DXGetMaxSurfaceFormats 関数は、指定したビデオ モードでデバイスによりサポートされているサーフェス フォーマットの最大数を返す。

DWORD D3DXGetMaxSurfaceFormats(
  DWORD deviceIndex,
  D3DX_VIDMODEDESC* pDesc,
  DWORD surfClassFlags
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。このパラメータに D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のある最高のアクセラレート レベルに基づいてデバイスが指定される。
pDesc
サポートされているサーフェス フォーマットが要求されたときのディスプレイ モードを記述した D3DX_VIDMODEDESC 構造体へのポインタ。このパラメータが NULL の場合、カレント ディスプレイ モードと見なされる。
surfClassFlags
サポートされたフォーマットが要求されているサーフェス クラスを示す D3DX_SURFACECLASS 列挙型のメンバ。

戻り値

成功すれば、指定したビデオ モードでデバイスによりサポートされているサーフェス フォーマットの最大数を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXGetSurfaceFormat


D3DXGetSurfaceFormat

D3DXGetSurfaceFormat 関数は、このデバイスでサポートされているサーフェス フォーマットのいずれかを記述する。

HRESULT D3DXGetSurfaceFormat(
  DWORD deviceIndex,
  D3DX_VIDMODEDESC* pDesc,
  DWORD surfClassFlags,
  DWORD surfaceIndex,
  D3DX_SURFACEFORMAT* pFormat
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。このパラメータに D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のある最高のアクセラレート レベルに基づいてデバイスが指定される。
pDesc
サポートされているサーフェス フォーマットが要求されたときのディスプレイ モードを記述した D3DX_VIDMODEDESC 構造体へのポインタ。このパラメータが NULL の場合、カレント ディスプレイ モードと見なされる。
surfClassFlags
サポートされたフォーマットが要求されているサーフェス クラスを示す D3DX_SURFACECLASS 列挙型のメンバ。
surfaceIndex
取得するサーフェス フォーマットを示す DWORD 値。インデックスは、0 で始まる。
pFormat
D3DX_SURFACEFORMAT 列挙型のメンバ (返されたサーフェス フォーマット) へのポインタ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX
D3DXERR_INVALIDPARAMETER
D3DXERR_NULLPOINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXGetMaxSurfaceFormats


D3DXGetVideoMode

D3DXGetVideoMode 関数は、このデバイスの特定のビデオ モードを記述する。

HRESULT D3DXGetVideoMode(
  DWORD deviceIndex,
  DWORD flags,
  DWORD modeIndex,
  D3DX_VIDMODEDESC* pModeList
);

パラメータ

deviceIndex
デバイスを指定するインデックス値。このパラメータに D3DX_DEFAULT を指定すると、プライマリ サーフェスに関係のある最高のアクセラレート レベルに基づいてデバイスが指定される。
flags
このパラメータで D3DX_GVM_REFRESHRATE が設定されていない限り、リフレッシュ レートは無視される。リフレッシュ レートを無視させたい場合、このパラメータに 0 を設定する。
modeIndex
デバイスを指定する DWORD 値。インデックスは、0 で始まる。
pModeList
デバイスのディスプレイ モードの記述により返される D3DX_VIDMODEDESC 構造体へのポインタ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX
D3DXERR_INVALIDPARAMETER
D3DXERR_NULLPOINTER

注意

D3DXGetVideoMode 関数により実行されるクエリは、ディスプレイ アダプタから DirectX へそのサポート内容を知らせるためのモード リストを指定するだけである。リストのすべてのビデオ モードについて D3DXCreateContext 関数や D3DXCreateContextEx 関数がうまく機能するとは保証されていない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXGetMaxNumVideoModes、D3DXGetMaxNumVideoModes


D3DXInitialize

D3DXInitialize 関数は、Direct3DX を初期化する。

HRESULT D3DXInitialize();

パラメータ

なし。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NOMEMORY
D3DXERR_STARTUPFAILED

注意

D3DXInitialize 関数は、Direct3DX アプリケーションにより最初に呼び出される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXUninitialize


D3DXMakeDDPixelFormat

D3DXMakeDDPixelFormat 関数は、要求された Direct3DX サーフェス フォーマットに基づいて DDPIXELFORMAT 構造体を返す。

HRESULT D3DXMakeDDPixelFormat(
  D3DX_SURFACEFORMAT d3dxFormat,
  DDPIXELFORMAT* pddpf
);

パラメータ

d3dxFormat
D3DX_SURFACEFORMAT 列挙型のメンバ (サーフェス フォーマット) へのポインタ。
pddpf
指定されたサーフェス フォーマットと一致するピクセル フォーマットを記述して返す DDPIXELFORMAT 構造体へのポインタ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NULLPOINTER
D3DXERR_INVALIDPARAMETER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMakeSurfaceFormat


D3DXMakeSurfaceFormat

D3DXMakeSurfaceFormat 関数は、指定された DDPIXELFORMAT 構造体に対応するサーフェス フォーマットを判定する。

D3DX_SURFACEFORMAT D3DXMakeSurfaceFormat(
  DDPIXELFORMAT* pddpf
);

パラメータ

pddpf
DDPIXELFORMAT 構造体へのポインタ。

戻り値

pddpf パラメータに対応する D3DX_SURFACEFORMAT 列挙型のメンバ。

注意

pddpf パラメータが NULL の場合、またはそれが未確認ピクセル フォーマットの場合、D3DXMakeSurfaceFormat 関数は D3DX_SF_UNKNOWN を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMakeDDPixelFormat


D3DXUninitialize

D3DXUninitialize 関数は、Direct3DX で使用されたリソースを解放する。

HRESULT D3DXUninitialize();

パラメータ

なし。

戻り値

成功すれば、S_OK を返す。失敗すれば、D3DXERR_D3DXNOTSTARTEDYET を返す。

注意

D3DXUninitialize 関数は、Direct3DX アプリケーションにより最後に呼び出される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXInitialize


算術関数

Direct3DX ユーティリティ ライブラリにより提供されている算術ライブラリには、基本的な算術演算と複雑な 3D 算術演算の両方を計算する関数がある。

3D 算術アプリケーション関数は、以下のグループにまとめることができる。

カラー | D3DXColorAdd
 | D3DXColorAdjustContrast
 | D3DXColorAdjustSaturation
 | D3DXColorLerp
 | D3DXColorModulate
 | D3DXColorNegative
 | D3DXColorScale
 | D3DXColorSubtract
作成 | D3DXCreateMatrixStack
平面 | D3DXPlaneDot
 | D3DXPlaneDotCoord
 | D3DXPlaneDotNormal
 | D3DXPlaneIntersectLine
 | D3DXPlaneFromPointNormal
 | D3DXPlaneFromPoints
 | D3DXPlaneTransform
クオータニオン | D3DXQuaternionBaryCentric
 | D3DXQuaternionConjugate
 | D3DXQuaternionDot
 | D3DXQuaternionExp
 | D3DXQuaternionIdentity
 | D3DXQuaternionInverse
 | D3DXQuaternionIsIdentity
 | D3DXQuaternionLength
 | D3DXQuaternionLengthSq
 | D3DXQuaternionLn
 | D3DXQuaternionMultiply
 | D3DXQuaternionNormalize
 | D3DXQuaternionRotationAxis
 | D3DXQuaternionRotationMatrix
 | D3DXQuaternionRotationYawPitchRoll
 | D3DXQuaternionSlerp
 | D3DXQuaternionSquad
 | D3DXQuaternionToAxisAngle
2D ベクトル | D3DXVec2Add
 | D3DXVec2BaryCentric
 | D3DXVec2CCW
 | D3DXVec2Dot
 | D3DXVec2Hermite
 | D3DXVec2Length
 | D3DXVec2LengthSq
 | D3DXVec2Lerp
 | D3DXVec2Maximize
 | D3DXVec2Minimize
 | D3DXVec2Normalize
 | D3DXVec2Scale
 | D3DXVec2Subtract
 | D3DXVec2Transform
 | D3DXVec2TransformCoord
 | D3DXVec2TransformNormal
3D ベクトル | D3DXVec3Add
 | D3DXVec3BaryCentric
 | D3DXVec3Cross
 | D3DXVec3Dot
 | D3DXVec3Hermite
 | D3DXVec3Length
 | D3DXVec3LengthSq
 | D3DXVec3Lerp
 | D3DXVec3Maximize
 | D3DXVec3Minimize
 | D3DXVec3Normalize
 | D3DXVec3Scale
 | D3DXVec3Subtract
 | D3DXVec3Transform
 | D3DXVec3TransformCoord
 | D3DXVec3TransformNormal
4D 行列 | D3DXMatrixAffineTransformation
 | D3DXMatrixfDeterminant
 | D3DXMatrixIdentity
 | D3DXMatrixInverse
 | D3DXMatrixIsIdentity
 | D3DXMatrixLookAt
 | D3DXMatrixLookAtLH
 | D3DXMatrixMultiply
 | D3DXMatrixOrtho
 | D3DXMatrixOrthoLH
 | D3DXMatrixOrthoOffCenter
 | D3DXMatrixOrthoOffCenterLH
 | D3DXMatrixPerspective
 | D3DXMatrixPerspectiveLH
 | D3DXMatrixPerspectiveFov
 | D3DXMatrixPerspectiveFovLH
 | D3DXMatrixPerspectiveOffCenter
 | D3DXMatrixPerspectiveOffCenterLH
 | D3DXMatrixReflect
 | D3DXMatrixRotationAxis
 | D3DXMatrixRotationQuaternion
 | D3DXMatrixRotationX
 | D3DXMatrixRotationY
 | D3DXMatrixRotationYawPitchRoll
 | D3DXMatrixRotationZ
 | D3DXMatrixScaling
 | D3DXMatrixShadow
 | D3DXMatrixTransformation
 | D3DXMatrixTranslation
 | D3DXMatrixTranspose
4D ベクトル | D3DXVec4Add
 | D3DXVec4BaryCentric
 | D3DXVec4Cross
 | D3DXVec4Dot
 | D3DXVec4Hermite
 | D3DXVec4Length
 | D3DXVec4LengthSq
 | D3DXVec4Lerp
 | D3DXVec4Maximize
 | D3DXVec4Minimize
 | D3DXVec4Normalize
 | D3DXVec4Scale
 | D3DXVec4Subtract
 | D3DXVec4Transform

メモ すべての算術関数は、入力パラメータと出力パラメータの両方で同じオブジェクトを使用できる。また、出力パラメータは通常戻り値として返されるので、ある算術関数の出力を別の算術関数のパラメータとして使用できる。


D3DXColorAdd

D3DXColorAdd 関数は、2 つのカラー値を加算して、新しいカラー値を作成する。

D3DXCOLOR* D3DXColorAdd(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC1,
  const D3DXCOLOR* pC2
);

パラメータ

pOut
演算結果である D3DXCOLOR 構造体へのポインタ。
pC1
ソースの D3DXCOLOR 構造体へのポインタ。
pC2
ソースの D3DXCOLOR 構造体へのポインタ。

戻り値

2 つのカラー値の合計である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorAdd 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXColorModulate、D3DXColorSubtract


D3DXColorAdjustContrast

D3DXColorAdjustContrast 関数は、指定した色のコントラスト値を調整する。

D3DXCOLOR* D3DXColorAdjustContrast(
  D3DXCOLOR* pOut,
  D3DXCOLOR* pC,
  float c
);

パラメータ

pOut
演算結果である D3DXCOLOR 構造体へのポインタ。
pC
ソースの D3DXCOLOR 構造体へのポインタ。
c
コントラスト値。このパラメータは、50% グレーと指定カラー pC の間で線形補間する。c 値に制限値はない。このパラメータが 0 の場合、返される色は 50% グレーである。このパラメータが 1 の場合、返される色はオリジナル カラーである。

戻り値

関数は、コントラスト調整結果の D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorAdjustContrast 関数を別の関数のパラメータとして使用できる。

この関数は、50% グレーと指定コントラスト値の間で D3DXCOLOR 構造体の赤 (red)、緑 (green)、青 (blue) の色成分を補間する。

    pOut->r = 0.5f + c * (pC->r - 0.5f);

c が 0 より大きく 1 未満の場合、コントラストは小さくなる。c が 1 より大きい場合、コントラストは大きくなる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXColorAdjustSaturation


D3DXColorAdjustSaturation

D3DXColorAdjustSaturation 関数は、指定された色の飽和値を調整する。

D3DXCOLOR* D3DXColorAdjustSaturation(
  D3DXCOLOR* pOut,
  D3DXCOLOR* pC,
  float s
);

パラメータ

pOut
演算結果である D3DXCOLOR 構造体へのポインタ。
pC
ソースの D3DXCOLOR 構造体へのポインタ。
s
飽和値。このパラメータは、グレー スケールに変換された色とオリジナル カラー pC の間で線形補間する。s 値に制限値はない。s が 0 の場合、返される色はグレー スケールの色である。s が 1 の場合、返される色はオリジナル カラーである。

戻り値

関数は、飽和調整結果の D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorAdjustSaturation 関数を別の関数のパラメータとして使用できる。

この関数は、未飽和カラーと指定カラーの間で D3DXCOLOR 構造体の赤 (red)、緑 (green)、青 (blue) の色成分を補間する。

    // 輝度に対する各成分の係数の適切な値。
    // ITU-R 勧告 BT.709 に記載された NTSC 標準に基づく。
    float grey = pC->r * 0.2125f + pC->g * 0.7154f + pC->b * 0.0721f;

    pOut->r = grey + s * (pC->r - grey);

s が 0 より大きく 1 未満の場合、飽和は小さくなる。s が 1 より大きい場合、飽和は大きくなる。

グレー スケールの色は、r = g = b = 0.2125*r + 0.7154*g + 0.0721*b として算出される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXColorAdjustContrast


D3DXColorLerp

D3DXColorLerp 関数は、線形補間を使用して、カラー値を作成する。

D3DXCOLOR* D3DXColorLerp(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC1,
  const D3DXCOLOR* pC2,
  float s
);

パラメータ

pOut
演算結果である D3DXCOLOR 構造体へのポインタ。
pC1
ソースの D3DXCOLOR 構造体へのポインタ。
pC2
ソースの D3DXCOLOR 構造体へのポインタ。
s
このパラメータは、pC1 と pC2 の 2 つの色を両方共 4D ベクトルとして処理し、それらの間で線形補間する。s 値に制限値はない。

戻り値

関数は、線形補間結果の D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorLerp 関数を別の関数のパラメータとして使用できる。

この関数は、2 つの指定された色の間で D3DXCOLOR 構造体の赤 (red)、緑 (green)、青 (blue) の色成分とアルファ成分を補間する。

    pOut->r = pC1->r + s * (pC2->r - pC1->r);

A カラーと B カラーの間で線形補間する場合に、s が 0 のとき、結果カラーは A となる。s が 1 のとき、結果カラーは B となる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXColorModulate、D3DXColorNegative、D3DXColorScale


D3DXColorModulate

D3DXColorModulate 関数は、指定された 2 つの色を混合する。

D3DXCOLOR* D3DXColorModulate(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC1,
  const D3DXCOLOR* pC2
);

パラメータ

pOut
演算結果である D3DXCOLOR 構造体へのポインタ。
pC1
ソースの D3DXCOLOR 構造体へのポインタ。
pC2
ソースの D3DXCOLOR 構造体へのポインタ。

戻り値

関数は、混合結果である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorModulate 関数を別の関数のパラメータとして使用できる。

この関数は、照合色成分を積算することで、指定された 2 つの色を混合する。

    pOut->r = pC1->r * pC2->r;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXColorLerp、D3DXColorNegative、D3DXColorScale


D3DXColorNegative

D3DXColorNegative 関数は、指定されたカラー値の負の色を作成する。

D3DXCOLOR* D3DXColorNegative(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC
);

パラメータ

pOut
演算結果である D3DXCOLOR 構造体へのポインタ。
pC
ソースの D3DXCOLOR 構造体へのポインタ。

戻り値

関数は、指定されたカラー値の負の色である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorNegative 関数を別の関数のパラメータとして使用できる。

この関数は、指定された D3DXCOLOR 構造体の色成分から 1.0 を除算することで負のカラー値を返す。

    pOut->r = 1.0f - pC->r;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXColorLerp、D3DXColorModulate、D3DXColorScale


D3DXColorScale

D3DXColorScale 関数は、カラー値をスケーリングする。

D3DXCOLOR* D3DXColorScale(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC,
  float s
);

パラメータ

pOut
演算結果である D3DXCOLOR 構造体へのポインタ。
pC
ソースの D3DXCOLOR 構造体へのポインタ。
s
スケーリング係数。色を 4D ベクトルのように処理して、それをスケーリングする。s 値に制限値はない。s が 1 の場合、返される色はオリジナル カラーである。

戻り値

関数は、スケーリングされたカラー値である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorScale 関数を別の関数のパラメータとして使用できる。

この関数は、指定された D3DXCOLOR 構造体の色成分に指定されたスケーリング係数を積算することで、スケーリングしたカラー値を算出する。

    pOut->r = pC->r * s;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXColorLerp、D3DXColorModulate、D3DXColorNegative


D3DXColorSubtract

D3DXColorSubtract 関数は、2 つのカラー値を減算して、新しいカラー値を作成する。

D3DXCOLOR* D3DXColorSubtract(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC1,
  const D3DXCOLOR* pC2
);

パラメータ

pOut
演算結果である D3DXCOLOR 構造体へのポインタ。
pC1
ソースの D3DXCOLOR 構造体へのポインタ。
pC2
ソースの D3DXCOLOR 構造体へのポインタ。

戻り値

この関数は、2 つのカラー値の差分である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorSubtract 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXColorAdd


D3DXCreateMatrixStack

D3DXCreateMatrixStack 関数は、ID3DXMatrixStack インターフェイスのインスタンスを作成する。

HRESULT D3DXCreateMatrixStack(
  DWORD flags,
  ID3DXMatrixStack** ppStack
);

パラメータ

flags
実装されていない。0 を指定すること。
ppStack
関数が成功した場合は、ID3DXMatrixStack インターフェイス ポインタが設定されるポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXMatrixAffineTransformation

D3DXMatrixAffineTransformation 関数は、アフィン トランスフォーム行列を構築する。

D3DXMATRIX* D3DXMatrixAffineTransformation(
  D3DXMATRIX* pOut,
  float scaling,
  const D3DXVECTOR3* pRotationCenter,
  const D3DXQUATERNION* pRotation,
  const D3DXVECTOR3* pTranslation
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
scaling
スケーリング係数
pRotationCenter
回転の中心を識別する点である D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合、それは単位元として処理される。
pRotation
回転処理を指定する D3DXQUATERNION 構造体へのポインタ。この引数が NULL の場合、それは単位元として処理される。
pTranslation
変換方法を表した D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合、それは単位元として処理される。

戻り値

アフィン トランスフォーム行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixAffineTransformation 関数は、Ms * Mrc-1 * Mr * Mrc * Mt 式によりアフィン トランスフォーム行列を算出する。ここで、Ms はスケール行列、Mrc は回転行列の中心、Mr は回転行列、Mt はトランスフォーム行列である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixAffineTransformation 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXMatrixfDeterminant

D3DXMatrixfDeterminant 関数は、指定された行列の行列式を返す。

float D3DXMatrixfDeterminant(
  const D3DXMATRIX* pM
);

パラメータ

pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

行列の値、行列式。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXMatrixIdentity

D3DXMatrixIdentity 関数は、単位行列を作成する。

D3DXMATRIX* D3DXMatrixIdentity(
  D3DXMATRIX* pOut
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。

戻り値

単位行列である D3DXMATRIX 構造体へのポインタ。

注意

単位行列は、[1,1][2,2][3,3][4,4] 係数に 1 が設定されていること除いて、すべての係数が 0 の行列である。単位行列は、頂点に適用されてもそれらが変更されないという点で特別である。単位行列は、頂点値を変更して回転、平行移動、および 4 × 4 行列で表現できるその他の変換を行う行列の起点として使用される。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixIdentity 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixIsIdentity


D3DXMatrixInverse

D3DXMatrixInverse 関数は、指定された行列の逆元を算出する。

D3DXMATRIX* D3DXMatrixInverse(
  D3DXMATRIX* pOut,
  float* pfDeterminant,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pfDeterminant
この関数が戻った後、このパラメータは指定された行列 pM の行列値である float 値をポイントしている。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

指定された行列の逆元である D3DXMATRIX 構造体へのポインタ。

注意

行列の逆変換が失敗すると、D3DXMatrixInverse 関数から NULL が返される。ただし、pfDeterminant パラメータが NULL 以外の場合は pM の行列値が返される。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixInverse 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXMatrixIsIdentity

D3DXMatrixIsIdentity 関数は、指定された行列が単位行列であるかどうかを判定する。

BOOL D3DXMatrixIsIdentity(
  const D3DXMATRIX* pM
);

パラメータ

pM
単位行列であるかどうかを判定する D3DXMATRIX 構造体へのポインタ。

戻り値

指定された行列が単位行列である場合、この関数は TRUE を返す。それ以外の場合は、FALSE を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixIdentity


D3DXMatrixLookAt

D3DXMatrixLookAt 関数は、右手座標系目視行列 (right-handed, look-at matrix) を構築する。

D3DXMATRIX* D3DXMatrixLookAt(
  D3DXMATRIX* pOut,
  const D3DXVECTOR3* pEye,
  const D3DXVECTOR3* pAt,
  const D3DXVECTOR3* pUp
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pEye
視点を定義した D3DXVECTOR3 構造体へのポインタ。この値は、平行移動時に使用される。
pAt
カメラの目視対象を定義した D3DXVECTOR3 構造体へのポインタ。
pUp
カレント ワールドの上方、一般には [0, 1, 0] を定義した D3DXVECTOR3 構造体へのポインタ。

戻り値

右手座標系目視行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixLookAt 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixLookAtLH


D3DXMatrixLookAtLH

D3DXMatrixLookAtLH 関数は、左手座標系目視行列 (left-handed, look-at matrix) を構築する。

D3DXMATRIX* D3DXMatrixLookAtLH(
  D3DXMATRIX* pOut,
  const D3DXVECTOR3* pEye,
  const D3DXVECTOR3* pAt,
  const D3DXVECTOR3* pUp
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pEye
視点を定義した D3DXVECTOR3 構造体へのポインタ。この値は、平行移動時に使用される。
pAt
カメラの目視対象を定義した D3DXVECTOR3 構造体へのポインタ。
pUp
カレント ワールドの上方 (高さ)、一般には [0, 1, 0] を定義した D3DXVECTOR3 構造体へのポインタ。

戻り値

左手座標系目視行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixLookAtLH 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixLookAt


D3DXMatrixMultiply

D3DXMatrixMultiply 関数は、指定された 2 つの行列の積を算出する。

D3DXMATRIX* D3DXMatrixMultiply(
  D3DXMATRIX* pOut,
  const D3DXMATRIX* pM1,
  const D3DXMATRIX* pM2
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pM1
ソースの D3DXMATRIX 構造体へのポインタ。
pM2
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

2 つの行列の積である D3DXMATRIX 構造体へのポインタ。

注意

結果は、変換 M1 後の変換 M2 の結果を表す (Out = M1 * M2)。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixMultiply 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionMultiply


D3DXMatrixOrtho

D3DXMatrixOrtho 関数は、右手座標系正射影 (正規直交変換) 行列を構築する。

D3DXMATRIX* D3DXMatrixOrtho(
  D3DXMATRIX* pOut,
  float w,
  float h,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
w
ビュー ボリュームの幅。
h
ビュー ボリュームの高さ。
zn
ビュー ボリュームの最小 z 値。
zf
ビュー ボリュームの最大 z 値。

戻り値

右手座標系正射影行列である D3DXMATRIX 構造体へのポインタ。

注意

直行行列とは、行列の逆変換が行列の転調と等価である逆変換可能な行列である。

D3DXMatrixOrtho 関数のパラメータはすべて、カメラ空間での距離である。パラメータは、ビュー ボリュームのディメンジョンを記述している。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixOrtho 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenter、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoLH

D3DXMatrixOrthoLH 関数は、左手座標系正射影 (正規直交変換) 行列を構築する。

D3DXMATRIX* D3DXMatrixOrthoLH(
  D3DXMATRIX* pOut,
  float w,
  float h,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
w
ビュー ボリュームの幅。
h
ビュー ボリュームの高さ。
zn
ビュー ボリュームの最小 z 値。
zf
ビュー ボリュームの最大 z 値。

戻り値

左手座標系正射影行列である D3DXMATRIX 構造体へのポインタ。

注意

直行行列とは、行列の逆変換が行列の転調と等価である逆変換可能な行列である。

D3DXMatrixOrthoLH 関数のパラメータはすべて、カメラ空間での距離である。パラメータは、ビュー ボリュームのディメンジョンを記述している。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixOrthoLH 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixOrtho、D3DXMatrixOrthoOffCenter、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenter

D3DXMatrixOrthoOffCenter 関数は、カスタマイズされた右手座標系正射影 (正規直交変換) 行列を構築する。

D3DXMATRIX* D3DXMatrixOrthoOffCenter(
  D3DXMATRIX* pOut,
  float l,
  float r,
  float t,
  float b,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
l
ビュー ボリュームの最小 x 値。
r
ビュー ボリュームの最大 x 値。
t
ビュー ボリュームの最小 y 値。
b
ビュー ボリュームの最大 y 値。
zn
ビュー ボリュームの最小 z 値。
zf
ビュー ボリュームの最大 z 値。

戻り値

右手座標系正射影行列である D3DXMATRIX 構造体へのポインタ。

注意

直行行列とは、行列の逆変換が行列の転調と等価である逆変換可能な行列である。

D3DXMatrixOrtho 関数は、D3DXMatrixOrthoOffCenter 関数を使用して同じ射影を作成するための D3DXMatrixOrthoOffCenter 関数の特別なケースである。l = -w/2、r = w/2、b = -h/2、t = h/2 という値を使用すること。

D3DXMatrixOrthoOffCenter 関数のパラメータはすべて、カメラ空間での距離である。パラメータは、ビュー ボリュームのディメンジョンを記述している。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixOrthoOffCenter 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixOrtho、D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenterLH

D3DXMatrixOrthoOffCenterLH 関数は、カスタマイズされた左手座標系正射影 (正規直交変換) 行列を構築する。

D3DXMATRIX* D3DXMatrixOrthoOffCenterLH(
  D3DXMATRIX* pOut,
  float l,
  float r,
  float t,
  float b,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
l
ビュー ボリュームの最小 x 値。
r
ビュー ボリュームの最大 x 値。
t
ビュー ボリュームの最小 y 値。
b
ビュー ボリュームの最大 y 値。
zn
ビュー ボリュームの最小 z 値。
zf
ビュー ボリュームの最大 z 値。

戻り値

左手座標系正射影行列である D3DXMATRIX 構造体へのポインタ。

注意

直行行列とは、行列の逆変換が行列の転調と等価である逆変換可能な行列である。

D3DXMatrixOrthoLH 関数は、D3DXMatrixOrthoOffCenterLH 関数を使用して同じ射影を作成するための D3DXMatrixOrthoOffCenterLH 関数の特別なケースである。l = -w/2、r = w/2、b = -h/2、t = h/2 という値を使用すること。

D3DXMatrixOrthoOffCenterLH 関数のパラメータはすべて、カメラ空間での距離である。パラメータは、ビュー ボリュームのディメンジョンを記述している。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixOrthoOffCenterLH 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixOrtho、D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenter


D3DXMatrixPerspective

D3DXMatrixPerspective 関数は、右手座標系パースペクティブ射影行列を構築する。

D3DXMATRIX* D3DXMatrixPerspective(
  D3DXMATRIX* pOut,
  float w,
  float h,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
w
近くのビュー平面でのビュー ボリュームの幅。
h
近くのビュー平面でのビュー ボリュームの高さ。
zn
近くのビュー平面の z 値。
zf
遠くのビュー平面の z 値。

戻り値

右手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixPerspective 関数のパラメータはすべて、カメラ空間での距離である。パラメータは、ビュー ボリュームのディメンジョンを記述している。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspective 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFov、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenter、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFov

D3DXMatrixPerspectiveFov 関数は、指定された視界に基づいて右手座標系パースペクティブ射影行列を構築する。

D3DXMATRIX* D3DXMatrixPerspectiveFov(
  D3DXMATRIX* pOut,
  float fovy,
  float aspect,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
fovy
視界 (ラジアン単位)。
aspect
アスペクト比。
zn
近くのビュー平面の z 値。
zf
遠くのビュー平面の z 値。

戻り値

右手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveFov 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixPerspective、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenter、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFovLH

D3DXMatrixPerspectiveFovLH 関数は、指定された視界に基づいて左手座標系パースペクティブ射影行列を構築する。

D3DXMATRIX* D3DXMatrixPerspectiveFovLH(
  D3DXMATRIX* pOut,
  float fovy,
  float aspect,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
fovy
視界 (ラジアン単位)。
aspect
アスペクト比。
zn
近くのビュー平面の z 値。
zf
遠くのビュー平面の z 値。

戻り値

左手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveFovLH 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixPerspective、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFov、D3DXMatrixPerspectiveOffCenter、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveLH

D3DXMatrixPerspectiveLH 関数は、左手座標系パースペクティブ射影行列を構築する。

D3DXMATRIX* D3DXMatrixPerspectiveLH(
  D3DXMATRIX* pOut,
  float w,
  float h,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
w
近くのビュー平面でのビュー ボリュームの幅。
h
近くのビュー平面でのビュー ボリュームの高さ。
zn
近くのビュー平面の z 値。
zf
遠くのビュー平面の z 値。

戻り値

左手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixPerspectiveLH 関数のパラメータはすべて、カメラ空間での距離である。パラメータは、ビュー ボリュームのディメンジョンを記述している。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveLH 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixPerspective、D3DXMatrixPerspectiveFov、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenter、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenter

D3DXMatrixPerspectiveOffCenter 関数は、カスタマイズされた右手座標系パースペクティブ射影行列を構築する。

D3DXMATRIX* D3DXMatrixPerspectiveOffCenter(
  D3DXMATRIX* pOut,
  float l,
  float r,
  float t,
  float b,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
l
近くのビュー平面の x 値。
r
遠くのビュー平面の x 値。
t
近くのビュー平面の y 値。
b
遠くのビュー平面の y 値。
zn
近くのビュー平面の z 値。
zf
遠くのビュー平面の z 値。

戻り値

右手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixPerspectiveOffCenter 関数のパラメータはすべて、カメラ空間での距離である。パラメータは、ビュー ボリュームのディメンジョンを記述している。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveOffCenter 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixPerspective、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFov、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenterLH

D3DXMatrixPerspectiveOffCenterLH 関数は、カスタマイズされた左手座標系パースペクティブ射影行列を構築する。

D3DXMATRIX* D3DXMatrixPerspectiveOffCenterLH(
  D3DXMATRIX* pOut,
  float l,
  float r,
  float t,
  float b,
  float zn,
  float zf
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
l
近くのビュー平面の x 値。
r
遠くのビュー平面の x 値。
t
近くのビュー平面の y 値。
b
遠くのビュー平面の y 値。
zn
近くのビュー平面の z 値。
zf
遠くのビュー平面の z 値。

戻り値

左手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixPerspectiveOffCenterLH 関数のパラメータはすべて、カメラ空間での距離である。パラメータは、ビュー ボリュームのディメンジョンを記述している。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveOffCenterLH 関数を別の関数のパラメータとして使用できる。

D3DXCreateContext 関数と D3DXCreateContextEx 関数によりセットアップされたデフォルトの射影行列は、pi/2 ラジアンの視域 (fov) での左手座標系パースペクティブ射影である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixPerspective、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFov、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenter


D3DXMatrixReflect

D3DXMatrixReflect 関数は、平面の座標系を反映した行列を構築する。

D3DXMATRIX* D3DXMatrixReflect(
  D3DXMATRIX* pOut,
  const D3DXPLANE* pPlane
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pPlane
ソースの D3DXPLANE 構造体へのポインタ。

戻り値

指定された平面の座標系を反映した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixReflect 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXMatrixRotationAxis

D3DXMatrixRotationAxis 関数は、任意の軸を回転軸として回転した行列を構築する。

D3DXMATRIX* D3DXMatrixRotationAxis(
  D3DXMATRIX* pOut,
  const D3DXVECTOR3* pV,
  float angle
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pV
軸の角度を識別する D3DXVECTOR3 構造体へのポインタ。
angle
回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

指定された軸を回転軸として回転した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationAxis 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationQuaternion

D3DXMatrixRotationQuaternion 関数は、クオータニオンから行列を構築する。

D3DXMATRIX* D3DXMatrixRotationQuaternion(
  D3DXMATRIX* pOut,
  const D3DXQUATERNION* pQ
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pQ
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

指定されたクオータニオンから構築された D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationQuaternion 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationX

D3DXMatrixRotationX 関数は、x 軸を回転軸として回転した行列を構築する。

D3DXMATRIX* D3DXMatrixRotationX(
  D3DXMATRIX* pOut,
  float angle
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
angle
回転角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

x 軸を回転軸として回転した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationX 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationY

D3DXMatrixRotationY 関数は、y 軸を回転軸として回転した行列を構築する。

D3DXMATRIX* D3DXMatrixRotationY(
  D3DXMATRIX* pOut,
  float angle
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
angle
回転角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

y 軸を回転軸として回転した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationY 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationYawPitchRoll

D3DXMatrixRotationYawPitchRoll 関数は、指定された偏揺れ角、傾斜角、および回転角により行列を構築する。

D3DXMATRIX* D3DXMatrixRotationYawPitchRoll(
  D3DXMATRIX* pOut,
  float yaw,
  float pitch,
  float roll,
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
yaw
y 軸の偏揺れ角 (ラジアン単位)。
pitch
x 軸の傾斜角 (ラジアン単位)。
roll
z 軸の回転角 (ラジアン単位)。

戻り値

指定された偏揺れ角、傾斜角、および回転角を持つ D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationYawPitchRoll 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationZ


D3DXMatrixRotationZ

D3DXMatrixRotationZ 関数は、z 軸を回転軸として回転した行列を構築する。

D3DXMATRIX* D3DXMatrixRotationZ(
  D3DXMATRIX* pOut,
  float angle
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
angle
回転角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

z 軸を回転軸として回転した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationZ 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll


D3DXMatrixScaling

D3DXMatrixScaling 関数は、x 軸、y 軸、z 軸に沿ってスケーリングした行列を構築する。

D3DXMATRIX* D3DXMatrixScaling(
  D3DXMATRIX* pOut,
  float sx,
  float sy,
  float sz,
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
sx
x 軸に沿って適用されるスケーリング係数。
sy
y 軸に沿って適用されるスケーリング係数。
sz
z 軸に沿って適用されるスケーリング係数。

戻り値

スケーリングされた行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixScaling 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXMatrixShadow

D3DXMatrixShadow 関数は、図形を平面に変換する行列を構築する。

D3DXMATRIX* D3DXMatrixShadow(
  D3DXMATRIX* pOut,
  const D3DXVECTOR4* pLight,
  const D3DXPLANE* pPlane
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pLight
ライトの位置を記述した D3DXVECTOR4 構造体へのポインタ。
pPlane
ソースの D3DXPLANE 構造体へのポインタ。

戻り値

図形を平面に変換する D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixShadow 関数は、ライトから影を変換するように、図形を平面に変換する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixShadow 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXMatrixTransformation

D3DXMatrixTransformation 関数は、トランスフォーム行列を構築する。

D3DXMATRIX* D3DXMatrixTransformation(
  D3DXMATRIX* pOut,
  const D3DXVECTOR3* pScalingCenter,
  const D3DXQUATERNION* pScalingRotation,
  const D3DXVECTOR3* pScaling,
  const D3DXVECTOR3* pRotationCenter,
  const D3DXQUATERNION* pRotation,
  const D3DXVECTOR3* pTranslation,
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pScalingCenter
スケーリングの中心を識別する D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合、それは単位元として処理される。
pScalingRotation
スケーリング回転を指定する D3DXQUATERNION 構造体へのポインタ。この引数が NULL の場合、これは単位元として処理される。
pScaling
スケーリング ベクトルである D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合、それは単位元として処理される。
pRotationCenter
回転の中心を識別する D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合、それは単位元として処理される。
pRotation
回転を指定する D3DXQUATERNION 構造体へのポインタ。この引数が NULL の場合、それは単位元として処理される。
pTranslation
平行移動を表す D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合、それは単位元として処理される。

戻り値

トランスフォーム行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixTransformation 関数は、Msc-1 * Msr-1 * Ms * Msr * Msc * Mrc-1 * Mr * Mrc * Mt 式によりトランスフォーム行列を計算する。ただし、Msc は中心のスケーリング行列、Msr はスケーリング回転行列、Ms はスケーリング行列、Mrc は回転行列の中心、Mr は回転行列、Mt は平行移動行列である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixTransformation 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixAffineTransformation


D3DXMatrixTranslation

D3DXMatrixTranslation 関数は、指定されたオフセットを使用して行列を構築する。

D3DXMATRIX* D3DXMatrixTranslation(
  D3DXMATRIX* pOut,
  float x,
  float y,
  float z,
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
x
x 座標のオフセット。
y
y 座標のオフセット。
z
z 座標のオフセット。

戻り値

変換された行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixTranslation 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXMatrixTranspose

D3DXMatrixTranspose 関数は、指定された行列の転調行列を返す。

D3DXMATRIX* D3DXMatrixTranspose(
  D3DXMATRIX* pOut,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXMATRIX 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

指定された行列の転調行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixTranspose 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXPlaneDot

D3DXPlaneDot 関数は、平面と 4D ベクトルの内積を算出する。

float D3DXPlaneDot(
  const D3DXPLANE* pP,
  const D3DXVECTOR4* pV
);

パラメータ

pP
ソースの D3DXPLANE 構造体へのポインタ。
pV
D3DXVECTOR4 構造体へのポインタ。

戻り値

指定された平面と 4D ベクトルの内積。

注意

平面 (a, b, c, d) と 4D ベクトル (x, y, z, w) を指定した場合、この関数の戻り値は a*x + b*y + c*z + d*w となる。D3DXPlaneDot 関数は、平面と同次座標の関係を判断するときに有用である。たとえば、この関数を使用すれば、特定の座標が特定の平面上にあるかどうか、または特定の座標が特定の平面のどちら側にあるかを判断できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXPlaneDotCoord、D3DXPlaneDotNormal


D3DXPlaneDotCoord

D3DXPlaneDotCoord 関数は、平面と 3D ベクトルの内積を算出する。ベクトルの w パラメータは、1 であると見なされる。

float D3DXPlaneDotCoord(
  const D3DXPLANE* pP,
  const D3DXVECTOR3* pV
);

パラメータ

pP
ソースの D3DXPLANE 構造体へのポインタ。
pV
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された平面と 3D ベクトルの内積。

注意

平面 (a, b, c, d) と 3D ベクトル (x, y, z) を指定した場合、この関数の戻り値は a*x + b*y + c*z + d*1 となる。D3DXPlaneDotCoord 関数は、平面と 3D 空間の座標の関係を判断するときに有用である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXPlaneDot、D3DXPlaneDotNormal


D3DXPlaneDotNormal

D3DXPlaneDotNormal 関数は、平面と 3D ベクトルの内積を算出する。ベクトルの w パラメータは、0 であると見なされる。

float D3DXPlaneDotNormal(
  const D3DXPLANE* pP,
  const D3DXVECTOR3* pV
);

パラメータ

pP
ソースの D3DXPLANE 構造体へのポインタ。
pV
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された平面と 3D ベクトルの内積。

注意

平面 (a, b, c, d) と 3D ベクトル (x, y, z) を指定した場合、この関数の戻り値は a*x + b*y + c*z + d*0 となる。D3DXPlaneDotNormal 関数は、平面の法線と別の平面の角度を判断するときに有用である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXPlaneDot、D3DXPlaneDotCoord


D3DXPlaneFromPointNormal

D3DXPlaneFromPointNormal 関数は、点と法線から平面を構築する。

D3DXPLANE* D3DXPlaneFromPointNormal(
  D3DXPLANE* pOut,
  const D3DXVECTOR3* pPoint,
  const D3DXVECTOR3* pNormal
);

パラメータ

pOut
処理結果である D3DXPLANE 構造体へのポインタ。
pPoint
D3DXVECTOR3 構造体へのポインタ。これは、平面を構築するときに使用する点である。
pNormal
D3DXVECTOR3 構造体へのポインタ。これは、平面を構築するときに使用する法線である。

戻り値

指定された点と法線から構築した D3DXPLANE 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneFromPointNormal 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXPlaneFromPoints


D3DXPlaneFromPoints

D3DXPlaneFromPoints 関数は、3 点から平面を構築する。

D3DXPLANE* D3DXPlaneFromPoints(
  D3DXPLANE* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2,
  const D3DXVECTOR3* pV3
);

パラメータ

pOut
処理結果である D3DXPLANE 構造体へのポインタ。
pV1
D3DXVECTOR3 構造体へのポインタ。これは、平面を構築するときに使用する点の 1 つである。
pV2
D3DXVECTOR3 構造体へのポインタ。これは、平面を構築するときに使用する点の 1 つである。
pV3
D3DXVECTOR3 構造体へのポインタ。これは、平面を構築するときに使用する点の 1 つである。

戻り値

指定された点から構築した D3DXPLANE 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneFromPoints 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXPlaneFromPointNormal


D3DXPlaneIntersectLine

D3DXPlaneIntersectLine 関数は、平面と直線の交線を見つける。

D3DXVECTOR3* D3DXPlaneIntersectLine(
  D3DXVECTOR3* pOut,
  const D3DXPLANE* pP,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

パラメータ

pOut
指定された平面と直接の交線を識別する D3DXVECTOR3 構造体へのポインタ。
pP
ソースの D3DXPLANE 構造体へのポインタ。
pV1
起点を定義したソースの D3DXVECTOR3 構造体へのポインタ。
pV2
終点を定義したソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された平面と直線の交線である D3DXVECTOR3 構造体へのポインタ。

注意

直線が平面に対して平行の場合、NULL が返される。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneIntersectLine 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXPlaneTransform

D3DXPlaneTransform 関数は、指定された行列により平面を変換する。

D3DXPLANE* D3DXPlaneTransform(
  D3DXPLANE* pOut,
  const D3DXPLANE* pP,
  const D3DXMATRIX* pM
);

パラメータ

pOut
処理結果である D3DXPLANE 構造体へのポインタ。
pP
ソースの D3DXPLANE 構造体へのポインタ。
pM
ソースの D3DMATRIX 構造体へのポインタ。

戻り値

変換された平面を表す D3DXPLANE 構造体へのポインタ。

注意

行列 pM は、アフィン変換でなければならない。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneTransform 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXQuaternionBaryCentric

D3DXQuaternionBaryCentric 関数は、重心座標のクオータニオンを返す。

D3DXQUATERNION* D3DXQuaternionBaryCentric(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2,
  const D3DXQUATERNION* pQ3,
  const D3DXQUATERNION* pQ4,
  float f,
  float g
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ1
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ2
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ3
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ4
ソースの D3DXQUATERNION 構造体へのポインタ。
f
加重係数。「注意」を参照すること。
g
加重係数。「注意」を参照すること。

戻り値

重心座標の D3DXQUATERNION 構造体へのポインタ。

注意

重心座標を計算するために、D3DXQuaternionBaryCentric 関数は Slerp(Slerp(Q1, Q2, f+g)、Slerp(Q1, Q3, f+g)、g/(f+g)) という一連の球線形補間を行う。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionBaryCentric 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXQuaternionConjugate

D3DXQuaternionConjugate 関数は、指定されたクオータニオンの共役を返す。

D3DXQUATERNION* D3DXQuaternionConjugate(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

指定されたクオータニオンの共役である D3DXQUATERNION 構造体へのポインタ。

注意

クオータニオン (x, y, z, w) が指定された場合、D3DXQuaternionConjugate 関数はクオータニオン (-x, -y, -z, w) を返す。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionConjugate 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionInverse


D3DXQuaternionDot

D3DXQuaternionDot 関数は、2 つのクオータニオンの内積を返す。

float D3DXQuaternionDot(
  D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2
);

パラメータ

pQ1
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ2
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

2 つのクオータニオンの内積。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXQuaternionExp

D3DXQuaternionExp 関数は、指数関数を計算する。

D3DXQUATERNION* D3DXQuaternionExp(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

指数関数である D3DXQUATERNION 構造体へのポインタ。

注意

D3DXQuaternionExp 関数は、w == 0 の単一クオータニオンでのみ機能する。

この関数は、次のように実装される。

q = (0, theta * v)

exp(q) = (cos(theta), sin(theta) * v)

D3DXQuaternionExp 関数と D3DXQuaternionLn 関数は、D3DXQuaternionSquad 関数を使用するときに有用である。クオータニオン キー セット (q0, q1, q2, ..., qn) を指定すると、隣接セグメントをまたいで接線を連続させるために、次のように内部四角形の点 (a1, a2, a3, ..., an-1) を計算できる。

        a1    a2    a3
  q0    q1    q2    q3    q4

a[i] = q[i] * exp( -(ln(inv(q[i])*q[i+1]) + ln(inv(q[i])*q[i-1])) / 4 )

(a1, a2, a3, ...) が計算されたら、この結果を使用し、曲線に沿って補間できる。

qt = Squad(t, q[i], a[i], a[i+1], q[i+1])

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionExp 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionLn、D3DXQuaternionSquad


D3DXQuaternionIdentity

D3DXQuaternionIdentity 関数は、単位クオータニオンを返す。

D3DXQUATERNION* D3DXQuaternionIdentity(
  D3DXQUATERNION* pOut
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。

戻り値

単位クオータニオンである D3DXQUATERNION 構造体へのポインタ。

注意

クオータニオン (x, y, z, w) を指定した場合、D3DXQuaternionIdentity 関数はクオータニオン (0, 0, 0, 1) を返す。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionIdentity 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionIsIdentity


D3DXQuaternionInverse

D3DXQuaternionInverse 関数は、指定されたクオータニオンを共役して、再正規化する。

D3DXQUATERNION* D3DXQuaternionInverse(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

指定されたクオータニオンの逆クオータニオンである D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionInverse 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionConjugate、D3DXQuaternionNormalize


D3DXQuaternionIsIdentity

D3DXQuaternionIsIdentity 関数は、指定されたクオータニオンが単位クオータニオンであるかどうかを判断する。

BOOL D3DXQuaternionIsIdentity(
  const D3DXQUATERNION* pQ
);

パラメータ

pQ
単位クオータニオンであるかどうかを判定する D3DXQUATERNION 構造体へのポインタ。

戻り値

指定されたクオータニオンが単位クオータニオンの場合、この関数は TRUE を返す。それ以外の場合は、FALSE を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionIdentity


D3DXQuaternionLength

D3DXQuaternionLength 関数は、指定されたクオータニオンの長さを返す。

float D3DXQuaternionLength(
  const D3DXQUATERNION* pQ
);

パラメータ

pQ
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

クオータニオンの長さ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionLengthSq


D3DXQuaternionLengthSq

D3DXQuaternionLengthSq 関数は、指定されたクオータニオンの長さの 2 乗を返す。

float D3DXQuaternionLengthSq(
  const D3DXQUATERNION* pQ
);

パラメータ

pQ
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

クオータニオンの長さの 2 乗。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionLength


D3DXQuaternionLn

D3DXQuaternionLn 関数は、自然対数を計算する。

D3DXQUATERNION* D3DXQuaternionLn(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

自然対数である D3DXQUATERNION 構造体へのポインタ。

注意

D3DXQuaternionLn 関数は、単位クオータニオンでのみ機能する。

この関数は、次のように実装される。

q = (cos(theta), sin(theta) * v)

|v| = 1

ln(q) = (0, theta * v)

D3DXQuaternionExp 関数と D3DXQuaternionLn 関数は、D3DXQuaternionSquad 関数を使用するとき有用である。クオータニオン キー セット (q0, q1, q2, ..., qn) を指定すると、隣接セグメントをまたいで接線を連続させるために、次のように内部四角形の点 (a1, a2, a3, ..., an-1) を計算できる。

        a1    a2    a3
  q0    q1    q2    q3    q4

a[i] = q[i] * exp( -(ln(inv(q[i])*q[i+1]) + ln(inv(q[i])*q[i-1])) / 4 )

(a1, a2, a3, ...) が計算されたら、この結果を使用し、曲線に沿って補間できる。

qt = Squad(t, q[i], a[i], a[i+1], q[i+1])

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionLn 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionExp、D3DXQuaternionSquad


D3DXQuaternionMultiply

D3DXQuaternionMultiply 関数は、2 つのクオータニオンを積算する。

D3DXQUATERNION* D3DXQuaternionMultiply(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ1
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ2
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

2 つのクオータニオンの積である D3DXQUATERNION 構造体へのポインタ。

注意

結果は、回転 Q1 の後に回転 Q2 を実行した結果を示している (Out = Q2 * Q1)。ただし、実際の出力は Q2*Q1 である (Q1*Q2 ではない)。このようにすると、回転行列を表すまた別の方法として単位クオータニオンを見なすことができるので、D3DXQuaternionMultiply 関数では D3DXMatrixMultiply と同じ意味論が保たれる。

D3DXQuaternionMultiply 関数と D3DXMatrixMultiply 関数の両方共、同じ順序で変換が結合される。たとえば、mX と mY が qX と qY と同じ回転を表しているものと仮定すると、m と q は両方共同じ回転を表すことになる。

D3DXMatrixMultiply(&m, &mX, &mY);

D3DXQuaternionMultiply(&q, &qX, &qY);

クオータニオンの積算は、可換性がない。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionMultiply 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXMatrixMultiply


D3DXQuaternionNormalize

D3DXQuaternionNormalize 関数は、指定されたクオータニオンの法線を返す。

D3DXQUATERNION* D3DXQuaternionNormalize(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
ソースの D3DXQUATERNION 構造体へのポインタ。

戻り値

指定されたクオータニオンの法線である D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionNormalize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionInverse


D3DXQuaternionRotationAxis

D3DXQuaternionRotationAxis 関数は、任意の軸を回転軸として指定されたクオータニオンを回転する。

D3DXQUATERNION* D3DXQuaternionRotationAxis(
  D3DXQUATERNION* pOut,
  const D3DXVECTOR3* pV,
  float angle
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pV
軸の角度を識別する D3DXVECTOR3 構造体へのポインタ。
angle
回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

指定された軸を回転軸として回転した D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionRotationAxis 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionRotationMatrix、D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationMatrix

D3DXQuaternionRotationMatrix 関数は、回転行列からクオータニオンを構築する。

D3DXQUATERNION* D3DXQuaternionRotationMatrix(
  D3DXQUATERNION* pOut,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

指定された回転行列から構築された D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionRotationMatrix 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionRotationAxis、D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationYawPitchRoll

D3DXQuaternionRotationYawPitchRoll 関数は、指定された偏揺れ角、傾斜角、および回転角によりクオータニオンを構築する。

D3DXQUATERNION* D3DXQuaternionRotationYawPitchRoll(
  D3DXQUATERNION* pOut,
  float yaw,
  float pitch,
  float roll
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
yaw
y 軸の偏揺れ角 (ラジアン単位)。
pitch
x 軸の傾斜角 (ラジアン単位)。
roll
z 軸の回転角 (ラジアン単位)。

戻り値

偏揺れ角、傾斜角、および回転角を持つ D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionRotationYawPitchRoll 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionRotationAxis、D3DXQuaternionRotationMatrix


D3DXQuaternionSlerp

D3DXQuaternionSlerp 関数は、球線形補間を使用して 2 つのクオータニオン間を補間する。

D3DXQUATERNION* D3DXQuaternionSlerp(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2,
  float t
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ1
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ2
ソースの D3DXQUATERNION 構造体へのポインタ。
t
この値は、指定された 2 つのクオータニオン間を補間する範囲を指定する。

戻り値

補間結果である D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionSlerp 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXQuaternionSquad

D3DXQuaternionSquad 関数は、球四角形補間を使用して、クオータニオン間を補間する。

D3DXQUATERNION* D3DXQuaternionSquad(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2,
  const D3DXQUATERNION* pQ3,
  const D3DXQUATERNION* pQ4,
  float t
);

パラメータ

pOut
演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ1
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ2
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ3
ソースの D3DXQUATERNION 構造体へのポインタ。
pQ4
ソースの D3DXQUATERNION 構造体へのポインタ。
t
このパラメータは、クオータニオン間を補間する範囲を指定する。

戻り値

球四角形補間の結果である D3DXQUATERNION 構造体へのポインタ。

注意

関数は、Slerp(Slerp(Q1, Q4, t)、Slerp(Q2, Q3, t)、2t(1-t)) の一連の球線形補間演算を使用する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionSquad 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXQuaternionExp、D3DXQuaternionLn


D3DXQuaternionToAxisAngle

D3DXQuaternionToAxisAngle 関数は、クオータニオンの軸と回転角度を計算する。

void D3DXQuaternionToAxisAngle(
  const D3DXQUATERNION* pQ,
  D3DXVECTOR3* pAxis,
  float* pAngle
);

パラメータ

pQ
ソースの D3DXQUATERNION 構造体へのポインタ。
pAxis
この関数が戻ると、このパラメータはクオータニオンの軸を識別する D3DXVECTOR3 構造体をポイントしている。
pAngle
この関数が戻ると、このパラメータはクオータニオンの回転角度 (ラジアン単位) を識別する float 値をポイントしている。

戻り値

なし。

注意

この関数は、単位クオータニオンが渡されるものと仮定している。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec2Add

D3DXVec2Add 関数は、2 つの 2D ベクトルを加算する。

D3DXVECTOR2* D3DXVec2Add(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
ソースの D3DXVECTOR2 構造体へのポインタ。
pV2
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの合計である D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Add 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Subtract、D3DXVec2Scale


D3DXVec2BaryCentric

D3DXVec2BaryCentric 関数は、指定された 2D ベクトルを使用して重心座標の点を返す。

D3DXVECTOR2* D3DXVec2BaryCentric(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2,
  D3DXVECTOR2* pV3,
  float f,
  float g
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
ソースの D3DXVECTOR2 構造体へのポインタ。
pV2
ソースの D3DXVECTOR2 構造体へのポインタ。
pV3
ソースの D3DXVECTOR2 構造体へのポインタ。
f
加重係数。「注意」を参照すること。
g
加重係数。「注意」を参照すること。

戻り値

重心座標の D3DXVECTOR2 構造体へのポインタ。

注意

D3DXVec2BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部や周辺の点を理解する方法を提供している。この関数は、V1 + f(V2-V1) + g(V3-V1) 方程式を使用して算出した点を返す。

平面 V1V2V3 の任意の点は、重心座標 (f,g) で表すことができる。パラメータ f は、V2 の結果に対する加重を制御し、パラメータ g は、V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 && g>=0 && 1-f-g>=0) の場合、点は三角形 V1V2V3 内にある。
  • (f==0 && g>=0 && 1-f-g>=0) の場合、点は直線 V1V3 上にある。
  • (f>=0 && g==0 && 1-f-g>=0) の場合、点は直線 V1V2 上にある。
  • If (f>=0 && g>=0 && 1-f-g==0) の場合、点は直線 V2V3 上にある。

重心座標は、一般的な座標の形式である。ここで重心座標を使用するときは、単に座標系の変更を表している。デカルト座標で真のものは、重心座標でも真である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2BaryCentric 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec2CCW

D3DXVec2CCW 関数は、2 つの 2D ベクトルの外積を算出して z コンポーネントを返す。

float D3DXVec2CCW(
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

パラメータ

pV1
ソースの D3DXVECTOR2 構造体へのポインタ。
pV2
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

z コンポーネント。

注意

この関数は、((x1,y1,0) cross (x2,y2,0)); 式または次のコードに基づいて外積を算出することで、z コンポーネントを判定する。

pV1->x * pV2->y - pV1->y * pV2->x

z コンポーネントの値が正の場合、V2 は V1 に対して反時計回りである。この情報は、背面のカリングで役に立つ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Dot


D3DXVec2Dot

D3DXVec2Dot 関数は、2 つの 2D ベクトルの内積を算出する。

float D3DXVec2Dot(
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

パラメータ

pV1
ソースの D3DXVECTOR2 構造体へのポインタ。
pV2
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

内積。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2CCW


D3DXVec2Hermite

D3DXVec2Hermite 関数は、指定された 2D ベクトルを使用してエルミートのスプライン補間を実行する。

D3DXVECTOR2* D3DXVec2Hermite(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pT1,
  const D3DXVECTOR2* pV2,
  const D3DXVECTOR2* pT2,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
位置ベクトルのソース D3DXVECTOR2 構造体へのポインタ。
pT1
接線ベクトルのソース D3DXVECTOR2 構造体へのポインタ。
pV2
位置ベクトルのソース D3DXVECTOR2 構造体へのポインタ。
pT2
接線ベクトルのソース D3DXVECTOR2 構造体へのポインタ。
s
加重係数。「注意」を参照すること。

戻り値

エルミートのスプライン補間の結果である D3DXVECTOR2 構造体へのポインタ。

注意

D3DXVec2Hermite 関数は、エルミートのスプライン補間を使用して (positionA, tangentA) から (positionB, tangentB) へ補間する。この関数は、位置 V1 と接線 T1 の間 (s が 0 の場合) と、位置 V2 と接線 T2 の間 (s が 1 の場合) を補間する。

エルミートのスプラインは、曲線がすべての制御点を通過するので、アニメーションを制御する場合に有用である。また、位置や接線がセグメントの終点で明示的に指定されているので、起点と接線が最終セグメントの終点の値に一致するようにしている限り、C2 連続曲線を簡単に作成できる。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Hermite 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec2Length

D3DXVec2Length 関数は、指定された 2D ベクトルの長さを返す。

float D3DXVec2Length(
  const D3DXVECTOR2* pV
);

パラメータ

pV
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

ベクトルの長さ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2LengthSq


D3DXVec2LengthSq

D3DXVec2LengthSq 関数は、指定された 2D ベクトルの長さの 2 乗を返す。

float D3DXVec2LengthSq(
  const D3DXVECTOR2* pV
);

パラメータ

pV
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

ベクトルの長さの 2 乗。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Length


D3DXVec2Lerp

D3DXVec2Lerp 関数は、2 つの 2D ベクトル間で線形補間を実行する。

D3DXVECTOR2* D3DXVec2Lerp(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
ソースの D3DXVECTOR2 構造体へのポインタ。
pV2
ソースの D3DXVECTOR2 構造体へのポインタ。
s
この値は、指定された 2 つのベクトル間を線形補間する。

戻り値

線形補間の結果である D3DXVECTOR2 構造体へのポインタ。

注意

この関数は、V1 + s(V2-V1) 式を基に線形補間を実行する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Lerp 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec2Maximize

D3DXVec2Maximize 関数は、指定された 2 つの 2D ベクトルの最大のコンポーネントから作成した 2D ベクトルを返す。

D3DXVECTOR2* D3DXVec2Maximize(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
ソースの D3DXVECTOR2 構造体へのポインタ。
pV2
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最大のコンポーネントから作成した D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Maximize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Minimize


D3DXVec2Minimize

D3DXVec2Minimize 関数は、指定された 2 つの 2D ベクトルの最小のコンポーネントから作成した 2D ベクトルを返す。

D3DXVECTOR2* D3DXVec2Minimize(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
ソースの D3DXVECTOR2 構造体へのポインタ。
pV2
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最小のコンポーネントから作成した D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Minimize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Maximize


D3DXVec2Normalize

D3DXVec2Normalize 関数は、指定された 2D ベクトルを正規化したベクトルを返す。

D3DXVECTOR2* D3DXVec2Normalize(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

指定されたベクトルを正規化した D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Normalize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec2Scale

D3DXVec2Scale 関数は、指定された 2D ベクトルをスケーリングする。

D3DXVECTOR2* D3DXVec2Scale(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV
ソースの D3DXVECTOR2 構造体へのポインタ。
s
スケーリング値。

戻り値

スケーリングされたベクトルである D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Scale 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Add、D3DXVec2Subtract


D3DXVec2Subtract

D3DXVec2Subtract 関数は、2 つの 2D ベクトルを減算する。

D3DXVECTOR2* D3DXVec2Subtract(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
ソースの D3DXVECTOR2 構造体へのポインタ。
pV2
ソースの D3DXVECTOR2 構造体へのポインタ。

戻り値

2 つのベクトルの差分である D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Subtract 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Add、D3DXVec2Scale


D3DXVec2Transform

D3DXVec2Transform 関数は、指定された行列により 2D ベクトル を変換する。

D3DXVECTOR4* D3DXVec2Transform(
  D3DXVECTOR4** pOut,
  const D3DXVECTOR2* pV,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
ソースの D3DXVECTOR2 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

変換されたベクトルの D3DXVECTOR4 構造体へのポインタ。

注意

この関数は、指定されたベクトル pV (x, y, 0, 1) を指定された行列 pM により変換する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Transform 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2TransformCoord、D3DXVec2TransformNormal


D3DXVec2TransformCoord

D3DXVec2TransformCoord 関数は、指定された行列により 2D ベクトルを変換し、その結果を w = 1 に射影する。

D3DXVECTOR2* D3DXVec2TransformCoord(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV
ソースの D3DXVECTOR2 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

変換されたベクトルである D3DXVECTOR2 構造体へのポインタ。

注意

この関数は、指定されたベクトル pV (x, y, 0, 1) を指定された行列により pM 変換し、その結果を w=1 に射影する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2TransformCoord 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Transform、D3DXVec2TransformNormal


D3DXVec2TransformNormal

D3DXVec2TransformNormal 関数は、指定された行列により 2D ベクトル法線を変換する。

D3DXVECTOR2* D3DXVec2TransformNormal(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXVECTOR2 構造体へのポインタ。
pV
ソースの D3DXVECTOR2 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

変換されたベクトルである D3DXVECTOR2 構造体へのポインタ。

注意

この関数は、指定されたベクトル pV のベクトル法線 (x, y, 0, 0) を指定された行列 pM により変換する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2TransformNormal 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec2Transform、D3DXVec2TransformCoord


D3DXVec3Add

D3DXVec3Add 関数は、2 つの 3D ベクトルを追加する。

D3DXVECTOR3* D3DXVec3Add(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
ソースの D3DXVECTOR3 構造体へのポインタ。
pV2
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された 2 つの 3D ベクトルの合計である D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Add 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Subtract、D3DXVec3Scale


D3DXVec3BaryCentric

D3DXVec3BaryCentric 関数は、指定された 3D ベクトルを使用して重心座標の点を返す。

D3DXVECTOR3* D3DXVec3BaryCentric(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2,
  D3DXVECTOR3* pV3,
  float f,
  float g
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
ソースの D3DXVECTOR3 構造体へのポインタ。
pV2
ソースの D3DXVECTOR3 構造体へのポインタ。
pV3
ソースの D3DXVECTOR3 構造体へのポインタ。
f
加重係数。「注意」を参照すること。
g
加重係数。「注意」を参照すること。

戻り値

重心座標の D3DXVECTOR3 構造体へのポインタ。

注意

D3DXVec3BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部や周辺の点を理解する方法を提供している。この関数は、V1 + f(V2-V1) + g(V3-V1) 方程式を使用して算出した点を返す。

平面V1V2V3 の任意の点は、重心座標 (f,g) で表すことができる。パラメータ f は、V2 の結果に対する加重を制御し、パラメータ g は、V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 && g>=0 && 1-f-g>=0) の場合、点は三角形 V1V2V3 内にある。
  • (f==0 && g>=0 && 1-f-g>=0) の場合、点は直線 V1V3 上にある。
  • (f>=0 && g==0 && 1-f-g>=0) の場合、点は直線 V1V2 上にある。
  • (f>=0 && g>=0 && 1-f-g==0) の場合、点は直線 V2V3 上にある。

重心座標は、一般的な座標の形式である。ここで重心座標を使用するときは、単に座標系の変更を表している。デカルト座標で真のものは、重心座標でも真である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3BaryCentric 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec3Cross

D3DXVec3Cross 関数は、2 つの 3D ベクトルの外積を算出する。

D3DXVECTOR3* D3DXVec3Cross(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
ソースの D3DXVECTOR3 構造体へのポインタ。
pV2
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

2 つの 3D ベクトルの外積である D3DXVECTOR3 構造体へのポインタ。

注意

この関数は、次のコードを使用して外積を算出する。

    D3DXVECTOR3 v;

    v.x = pV1->y * pV2->z - pV1->z * pV2->y;
    v.y = pV1->z * pV2->x - pV1->x * pV2->z;
    v.z = pV1->x * pV2->y - pV1->y * pV2->x;

    *pOut = v;

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Cross 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Dot


D3DXVec3Dot

D3DXVec3Dot 関数は、2 つの 3D ベクトルの内積を算出する。

float D3DXVec3Dot(
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

パラメータ

pV1
ソースの D3DXVECTOR3 構造体へのポインタ。
pV2
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

内積。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Cross


D3DXVec3Hermite

D3DXVec3Hermite 関数は、指定された 3D ベクトルを使用してエルミートのスプライン補間を実行する。

D3DXVECTOR3* D3DXVec3Hermite(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pT1,
  const D3DXVECTOR3* pV2,
  const D3DXVECTOR3* pT2,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
位置ベクトルのソース D3DXVECTOR4 構造体へのポインタ。
pT1
接線ベクトルのソース D3DXVECTOR4 構造体へのポインタ。
pV2
位置ベクトルのソース D3DXVECTOR4 構造体へのポインタ。
pT2
接線ベクトルのソース D3DXVECTOR4 構造体へのポインタ。
s
加重係数。「注意」を参照すること。

戻り値

エルミートのスプライン補間の結果である D3DXVECTOR3 構造体へのポインタ。

注意

D3DXVec3Hermite 関数は、エルミートのスプライン補間を使用して (positionA, tangentA) から (positionB, tangentB) へ補間する。この関数は、位置 V1 と接線 T1 の間 (s が 0 の場合) と、位置 V2 と接線 T2 の間 (s が 1 の場合) を補間する。

エルミートのスプラインは、曲線がすべての制御点を通過するので、アニメーションを制御する場合に有用である。また、位置や接線がセグメントの終点で明示的に指定されているので、起点と接線が最終セグメントの終点の値に一致するようにしている限り、C2 連続曲線を簡単に作成できる。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Hermite 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec3Length

D3DXVec3Length 関数は、指定された 3D ベクトルの長さを返す。

float D3DXVec3Length(
  const D3DXVECTOR3* pV
);

パラメータ

pV
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

ベクトルの長さ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3LengthSq


D3DXVec3LengthSq

D3DXVec3LengthSq 関数は、指定された 3D ベクトルの長さの 2 乗を返す。

float D3DXVec3LengthSq(
  const D3DXVECTOR3* pV
);

パラメータ

pV
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

ベクトルの長さの 2 乗。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Length


D3DXVec3Lerp

D3DXVec3Lerp 関数は、2 つの 3D ベクトル間で線形補間を実行する。

D3DXVECTOR3* D3DXVec3Lerp(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
ソースの D3DXVECTOR3 構造体へのポインタ。
pV2
ソースの D3DXVECTOR3 構造体へのポインタ。
s
この値は、指定された 2 つのベクトル間を線形補間する。

戻り値

線形補間の結果である D3DXVECTOR3 構造体へのポインタ。

注意

この関数は、V1 + s(V2-V1) 式に基づいて線形補間を実行する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Lerp 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec3Maximize

D3DXVec3Maximize 関数は、指定された 2 つの 3D ベクトルの最大のコンポーネントから作成した 3D ベクトルを返す。

D3DXVECTOR3* D3DXVec3Maximize(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
ソースの D3DXVECTOR3 構造体へのポインタ。
pV2
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最大のコンポーネントから作成された D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Maximize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Minimize


D3DXVec3Minimize

D3DXVec3Minimize 関数は、指定された 2 つの 3D ベクトルの最小コンポーネントから作成した 3D ベクトルを返す。

D3DXVECTOR3* D3DXVec3Minimize(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
ソースの D3DXVECTOR3 構造体へのポインタ。
pV2
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最小コンポーネントから作成された D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Minimize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Maximize


D3DXVec3Normalize

D3DXVec3Normalize 関数は、指定された 3D ベクトルを正規化したベクトルを返す。

D3DXVECTOR3* D3DXVec3Normalize(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

指定されたベクトルを正規化した D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Normalize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec3Scale

D3DXVec3Scale 関数は、指定された 3D ベクトルをスケーリングする。

D3DXVECTOR3* D3DXVec3Scale(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
ソースの D3DXVECTOR3 構造体へのポインタ。
s
スケーリング値。

戻り値

スケーリングされたベクトルである D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Scale 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Add、D3DXVec3Subtract


D3DXVec3Subtract

D3DXVec3Subtract 関数は、2 つの 3D ベクトルを減算する。

D3DXVECTOR3* D3DXVec3Subtract(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
ソースの D3DXVECTOR3 構造体へのポインタ。
pV2
ソースの D3DXVECTOR3 構造体へのポインタ。

戻り値

2 つのベクトルの差分である D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Subtract 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Add、D3DXVec3Scale


D3DXVec3Transform

D3DXVec3Transform 関数は、指定された行列により 3D ベクトルを変換する。

D3DXVECTOR4* D3DXVec3Transform(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR3* pV,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
ソースの D3DXVECTOR3 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

変換されたベクトルの D3DXVECTOR4 構造体へのポインタ。

注意

この関数は、指定されたベクトル pV (x, y, z, 1) を指定された行列 pM により変換する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Transform 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3TransformCoord、D3DXVec3TransformNormal


D3DXVec3TransformCoord

D3DXVec3TransformCoord 関数は、指定された行列により 3D ベクトルを変換し、その結果を w = 1 に射影する。

D3DXVECTOR3* D3DXVec3TransformCoord(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
ソースの D3DXVECTOR3 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

変換されたベクトルである D3DXVECTOR3 構造体へのポインタ。

注意

この関数は、指定されたベクトル pV (x, y, z, 1) を指定された行列により pM 変換し、その結果を w=1 に射影する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3TransformCoord 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Transform、D3DXVec3TransformNormal


D3DXVec3TransformNormal

D3DXVec3TransformNormal 関数は、指定された行列により 3D ベクトル法線を変換する。

D3DXVECTOR3* D3DXVec3TransformNormal(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
ソースの D3DXVECTOR3 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

変換されたベクトルである D3DXVECTOR3 構造体へのポインタ。

注意

この関数は、指定されたベクトル pV のベクトル法線 (x, y, z, 0) を指定された行列 pM により変換する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3TransformNormal 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec4Add

D3DXVec4Add 関数は、2 つの 4D ベクトルを加算する。

D3DXVECTOR4* D3DXVec4Add(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
ソースの D3DXVECTOR4 構造体へのポインタ。
pV2
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの合計である D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Add 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec4Subtract、D3DXVec4Scale


D3DXVec4BaryCentric

D3DXVec4BaryCentric 関数は、指定された 4D ベクトルを使用して重心座標の点を返す。

D3DXVECTOR4* D3DXVec4BaryCentric(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2,
  const D3DXVECTOR4* pV3,
  float f,
  float g
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
ソースの D3DXVECTOR4 構造体へのポインタ。
pV2
ソースの D3DXVECTOR4 構造体へのポインタ。
pV3
ソースの D3DXVECTOR4 構造体へのポインタ。
f
加重係数。「注意」を参照すること。
g
加重係数。「注意」を参照すること。

戻り値

重心座標の D3DXVECTOR4 構造体へのポインタ。

注意

D3DXVec4BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部や周辺の点を理解する方法を提供している。この関数は、V1 + f(V2-V1) + g(V3-V1) 方程式を使用して算出した点を返す。

平面 V1V2V3 の任意の点は、重心座標 (f,g) で表すことができる。パラメータ f は、V2 の結果に対する加重を制御し、パラメータ g は、V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 && g>=0 && 1-f-g>=0) の場合、点は三角形 V1V2V3 内にある。
  • (f==0 && g>=0 && 1-f-g>=0) の場合、点は直線 V1V3 上にある。
  • (f>=0 && g==0 && 1-f-g>=0) の場合、点は直線 V1V2 上にある。
  • (f>=0 && g>=0 && 1-f-g==0) の場合、点は直線 V2V3 上にある。

重心座標は、一般的な座標の形式である。ここで重心座標を使用するときは、単に座標系の変更を表している。デカルト座標で真のものは、重心座標でも真である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4BaryCentric 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec4Cross

D3DXVec4Cross 関数は、4D で外積を算出する。

D3DXVECTOR4* D3DXVec4Cross(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2,
  const D3DXVECTOR4* pV3
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
ソースの D3DXVECTOR4 構造体へのポインタ。
pV2
ソースの D3DXVECTOR4 構造体へのポインタ。
pV3
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

外積である D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Cross 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec4Dot


D3DXVec4Dot

D3DXVec4Dot 関数は、2つの 4D ベクトルの内積を算出する。

float D3DXVec4Dot(
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

パラメータ

pV1
ソースの D3DXVECTOR4 構造体へのポインタ。
pV2
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

内積。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec4Cross


D3DXVec4Hermite

D3DXVec4Hermite 関数は、指定された 4D ベクトルを使用して、エルミートのスプライン補間を実行する。

D3DXVECTOR4* D3DXVec4Hermite(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pT1,
  const D3DXVECTOR4* pV2,
  const D3DXVECTOR4* pT2,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
位置ベクトルのソース D3DXVECTOR4 構造体へのポインタ。
pT1
接線ベクトルのソース D3DXVECTOR4 構造体へのポインタ。
pV2
位置ベクトルのソース D3DXVECTOR4 構造体へのポインタ。
pT2
接線ベクトルのソース D3DXVECTOR4 構造体へのポインタ。
s
加重係数。「注意」を参照すること。

戻り値

エルミートのスプライン補間の結果である D3DXVECTOR4 構造体へのポインタ。

注意

D3DXVec4Hermite 関数は、エルミートのスプライン補間を使用して (positionA, tangentA) から (positionB, tangentB) へ補間する。この関数は、位置 V1 と接線 T1 の間 (s が 0 の場合) と、位置 V2 と接線 T2 の間 (s が 1 の場合) を補間する。

エルミートのスプラインは、曲線がすべての制御点を通過するので、アニメーションを制御する場合に有用である。また、位置や接線がセグメントの終点で明示的に指定されているので、起点と接線が最終セグメントの終点の値に一致するようにしている限り、C2 連続曲線を簡単に作成できる。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Hermite 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec4Length

D3DXVec4Length 関数は、指定された 4D ベクトルの長さを返す。

float D3DXVec4Length(
  const D3DXVECTOR4* pV
);

パラメータ

pV
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

ベクトルの長さ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec4LengthSq


D3DXVec4LengthSq

D3DXVec4LengthSq 関数は、指定された 4D ベクトルの長さの 2 乗を返す。

float D3DXVec4LengthSq(
  const D3DXVECTOR4* pV
);

パラメータ

pV
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

ベクトルの長さの 2 乗。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec4Length


D3DXVec4Lerp

D3DXVec4Lerp 関数は、2 つの 4D ベクトル間を線形補間する。

D3DXVECTOR4* D3DXVec4Lerp(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
ソースの D3DXVECTOR4 構造体へのポインタ。
pV2
ソースの D3DXVECTOR4 構造体へのポインタ。
s
この値は、指定された 2 つのベクトル間を線形補間する。

戻り値

線形補間の結果である D3DXVECTOR4 構造体へのポインタ。

注意

この関数は、V1 + s(V2-V1) 式を基に線形補間を実行する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Lerp 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec4Maximize

D3DXVec4Maximize 関数は、指定された 2 つの 4D ベクトルの最大のコンポーネントから作成した 4D ベクトルを返す。

D3DXVECTOR4* D3DXVec4Maximize(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
ソースの D3DXVECTOR4 構造体へのポインタ。
pV2
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最大のコンポーネントから作成した D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Maximize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec4Minimize


D3DXVec4Minimize

D3DXVec4Minimize 関数は、指定された 2 つの 4D ベクトルの最小のコンポーネントから作成した 4D ベクトルを返す。

D3DXVECTOR4* D3DXVec4Minimize(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
ソースの D3DXVECTOR4 構造体へのポインタ。
pV2
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最小のコンポーネントから作成した D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Minimize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec4Maximize


D3DXVec4Normalize

D3DXVec4Normalize 関数は、指定された 4D ベクトルを正規化したベクトルを返す。

D3DXVECTOR4* D3DXVec4Normalize(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

指定されたベクトルを正規化した D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Normalize 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXVec4Scale

D3DXVec4Scale 関数は、指定された 4D ベクトルをスケーリングする。

D3DXVECTOR4* D3DXVec4Scale(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV,
  float s
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
ソースの D3DXVECTOR4 構造体へのポインタ。
s
スケーリング値。

戻り値

スケーリングされたベクトルである D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Scale 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec4Add、D3DXVec4Subtract


D3DXVec4Subtract

D3DXVec4Subtract 関数は、2 つの 4D ベクトルを減算する。

D3DXVECTOR4* D3DXVec4Subtract(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
ソースの D3DXVECTOR4 構造体へのポインタ。
pV2
ソースの D3DXVECTOR4 構造体へのポインタ。

戻り値

2 つのベクトルの差分である D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Subtract 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXVec3Add、D3DXVec3Scale


D3DXVec4Transform

D3DXVec4Transform 関数は、指定された行列により 4D ベクトル を変換する。

D3DXVECTOR4* D3DXVec4Transform(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV,
  const D3DXMATRIX* pM
);

パラメータ

pOut
演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
ソースの D3DXVECTOR4 構造体へのポインタ。
pM
ソースの D3DXMATRIX 構造体へのポインタ。

戻り値

変換された 4D ベクトルの D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Transform 関数を別の関数のパラメータとして使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。
ライブラリ : d3dx.lib を使用。


形状描画関数

Direct3DX ユーティリティ ライブラリにより提供されている 3D 形状描画アプリケーション プログラミング インターフェイス (API) では、簡単な図形の形を描画するための関数が提供されている。

ここでは、次の Direct3DX グローバル関数について説明する。

  • D3DXCreateBox
  • D3DXCreateCylinder
  • D3DXCreatePolygon
  • D3DXCreateSphere
  • D3DXCreateTeapot
  • D3DXCreateTorus

すべての形は、頂点バッファとして返される。形が頂点バッファなので、フレキシブルな頂点フォーマット タイプは、頂点バッファ自体を問い合わせることにより見つけることができる。各頂点バッファには頂点が設定されており、それらはすべてプリミティブを三角形リストとして描画するときに使用できる。

詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。


D3DXCreateBox

D3DXCreateBox 関数は、指定されたディメンジョンのボックス (立方体) を作成する。

HRESULT D3DXCreateBox(
  LPDIRECT3DDEVICE7 pDevice,
  float width,
  float height,
  float depth,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

パラメータ

pDevice
デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
width
x 軸方向のボックスの幅。
height
y 軸方向のボックスの高さ。
depth
z 軸方向のボックスの深度。
numTexCoords
出力頂点バッファの目的のテクスチャ座標数。デフォルト値は 1 である。このパラメータには、D3DX_DEFAULT を入力可能である。
ppShape
出力頂点バッファの ID3DXSimpleShape インターフェイスへのポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

注意

この関数は、後でアプリケーションにより描画したり、操作するときに使用できる頂点バッファを返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateCylinder、D3DXCreatePolygon、D3DXCreateSphere、D3DXCreateTeapot、D3DXCreateTorus


D3DXCreateCylinder

D3DXCreateCylinder 関数は、指定されたディメンジョンの円柱を作成する。

HRESULT D3DXCreateCylinder(
  LPDIRECT3DDEVICE7 pDevice,
  float baseRadius,
  float topRadius,
  float height,
  DWORD numSlices,
  DWORD numStacks,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

パラメータ

pDevice
デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
baseRadius
円柱の底面の半径。デフォルト値は、1.0f である。このパラメータは、0.0f 以上でなければならない。
topRadius
円柱の上面の半径。デフォルト値は、1.0f である。このパラメータは、0.0f 以上でなければならない。
height
円柱の高さ。デフォルト値は、1.0f である。このパラメータは、0.0f 以上でなければならない。
numSlices
主軸を回転軸としたスライスの数。デフォルト値は 8 である。このパラメータには、D3DX_DEFAULT を入力可能である。
numStacks
主軸に沿ったスタック数。デフォルト値は 8 である。このパラメータには、D3DX_DEFAULT を入力可能である。
numTexCoords
出力頂点バッファの目的のテクスチャ座標数。デフォルト値は 1 である。このパラメータには、D3DX_DEFAULT を入力可能である。
ppShape
出力頂点バッファの ID3DXSimpleShape インターフェイスへのポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

注意

この関数は、後でアプリケーションにより描画したり、操作するときに使用できる頂点バッファを返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateBox、D3DXCreatePolygon、D3DXCreateSphere、D3DXCreateTeapot、D3DXCreateTorus


D3DXCreatePolygon

D3DXCreatePolygon 関数は、n 辺のポリゴンを作成する。

HRESULT D3DXCreatePolygon(
  LPDIRECT3DDEVICE7 pDevice,
  float sideSize,
  DWORD numSides,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

パラメータ

pDevice
デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
sideSize
辺の長さ。
numSides
辺の数。
numTexCoords
出力頂点バッファの目的のテクスチャ座標数。デフォルト値は 1 である。このパラメータには、D3DX_DEFAULT を入力可能である。
ppShape
出力頂点バッファの ID3DXSimpleShape インターフェイスへのポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

注意

この関数は、後でアプリケーションにより描画したり、操作するときに使用できる頂点バッファを返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateBox、D3DXCreateCylinder、D3DXCreateSphere、D3DXCreateTeapot、D3DXCreateTorus


D3DXCreateSphere

D3DXCreateSphere 関数は、指定されたディメンジョンの球を作成する。

HRESULT D3DXCreateSphere(
  LPDIRECT3DDEVICE7 pDevice,
  float radius,
  DWORD numSlices,
  DWORD numStacks,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

パラメータ

pDevice
デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
radius
球の半径。デフォルト値は、1.0f である。このパラメータは、0.0f 以上でなければならない。
numSlices
主軸を回転軸としたスライスの数。デフォルト値は 8 である。このパラメータには、D3DX_DEFAULT を入力可能である。
numStacks
主軸に沿ったスタック数。デフォルト値は 8 である。このパラメータには、D3DX_DEFAULT を入力可能である。
numTexCoords
出力頂点バッファの目的のテクスチャ座標数。デフォルト値は 1 である。このパラメータには、D3DX_DEFAULT を入力可能である。
ppShape
出力頂点バッファの ID3DXSimpleShape インターフェイスへのポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

注意

この関数は、後でアプリケーションにより描画したり、操作するときに使用できる頂点バッファを返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateBox、D3DXCreateCylinder、D3DXCreatePolygon、D3DXCreateTeapot、D3DXCreateTorus


D3DXCreateTeapot

D3DXCreateTeapot 関数は、ティーポットを作成する。

HRESULT D3DXCreateTeapot(
  LPDIRECT3DDEVICE7 pDevice,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

パラメータ

pDevice
デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
numTexCoords
出力頂点バッファの目的のテクスチャ座標数。デフォルト値は 1 である。このパラメータには、D3DX_DEFAULT を入力可能である。
ppShape
出力頂点バッファの ID3DXSimpleShape インターフェイスへのポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

注意

この関数は、後でアプリケーションにより描画したり、操作するときに使用できる頂点バッファを返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateBox、D3DXCreateCylinder、D3DXCreatePolygon、D3DXCreateSphere、D3DXCreateTorus


D3DXCreateTorus

D3DXCreateTorus 関数は、指定されたディメンジョンのトーラスを作成する。

HRESULT D3DXCreateTorus(
  LPDIRECT3DDEVICE7 pDevice,
  float innerRadius,
  float outerRadius,
  DWORD numSides,
  DWORD numRings,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

パラメータ

pDevice
デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
innerRadius
トーラスの内部の半径。デフォルト値は、1.0f である。このパラメータは、0.0f 以上でなければならない。
outerRadius
トーラスの外部の半径。デフォルト値は、1.0f である。このパラメータは、0.0f 以上でなければならない。
numSides
横断面の辺の数。デフォルト値は 8 である。このパラメータには、D3DX_DEFAULT を入力可能である。
numRings
トーラスを構成する環の数。デフォルト値は 8 である。このパラメータには、D3DX_DEFAULT を入力可能である。
numTexCoords
出力頂点バッファの目的のテクスチャ座標数。デフォルト値は 1 である。このパラメータには、D3DX_DEFAULT を入力可能である。
ppShape
出力頂点バッファの ID3DXSimpleShape インターフェイスへのポインタのアドレス。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

注意

D3DXCreateTorus メソッドは、中心が (0, 0, 0) で軸が z 軸方向のドーナツ型の図形 (トーラス) を描画する。このトーラスの内部の半径は横断面の半径 (小さい方の半径)、外部の半径は中央の穴の半径である。

この関数は、後でアプリケーションにより描画したり、操作するときに使用できる頂点バッファを返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxshapes.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateBox、D3DXCreateCylinder、D3DXCreatePolygon、D3DXCreateSphere、D3DXCreateTeapot


スプライト ヘルパー関数

Direct3DX ユーティリティ ライブラリにより提供されているスプライト ヘルパーのアプリケーション プログラミング インターフェイス (API) は、スプライト レンダリングを行う関数を提供している。

ここでは、次の Direct3DX グローバル関数について説明する。

  • D3DXBuildSpriteTransform
  • D3DXDrawSpriteSimple
  • D3DXDrawSpriteTransform
  • D3DXDrawSprite3D
  • D3DXPrepareDeviceForSprite

メモ C++ プログラマは Direct3DX スプライト ライブラリのデフォルト値を使用できる。詳細については、各関数の説明を参照すること。


D3DXBuildSpriteTransform

D3DXBuildSpriteTransform 関数は、-0.5 から +0.5 までの中軸を持つ矩形から、画面の特定の RECT 構造体への変換に対応する行列を作成する。また、その RECT 構造体に対して回転の角度も指定できる。

void D3DXBuildSpriteTransform(
  D3DXMATRIX* pMatrixTransform,
  const RECT* prectDest,
  float angleRad = 0.0f,
  const D3DXVECTOR2* pOffset
);

パラメータ

pMatrixTransform
結果行列である D3DXMATRIX 構造体へのポインタ。この行列は、prectDest パラメータ、angleRad パラメータ、pOffset パラメータにより指定された変換に対応した新しい値が設定されて返される。
prectDest
スプライトのターゲット矩形へのポインタで、スクリーン座標でのスプライトの位置を示す。スプライトは、この RECT 構造体を囲むように広げられる。
angleRad
RECT の中心を中心とした回転の角度で、スプライトの回転角度を示す。回転は、スプライトの中心を中心として適用される。それは、反時計回りにラジアン単位で指定する。度数からラジアンへ変換する方法については、「D3DXToRadian」を参照すること。
pOffset
回転の中心として使用するソース RECT の中心からのオフセットを定義した D3DXVECTOR2 構造体へのポインタ。このパラメータは、回転でスプライトの中心として処理されるスプライトの中心点からのオフセットを示す。デフォルトにより、NULL 値は (0, 0) ベクトルと等価となる。

戻り値

なし。

注意

D3DXBuildSpriteTransform 関数は、D3DXDrawSpriteTransform 関数を使用するためのヘルパー関数として提供されている。

ただし、C プログラマは angleRad パラメータにデフォルト値を指定できないので注意すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxsprite.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXDrawSpriteSimple

D3DXDrawSpriteSimple 関数は、スプライトを Direct3D デバイスにレンダリングする。この関数は、IDirect3DDevice7::BeginScene 関数を呼び出した後で、IDirect3DDevice7::EndScene 関数を呼び出す前に呼び出す必要がある。

HRESULT D3DXDrawSpriteSimple(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXVECTOR3* ppointDest,
  float alpha = 1.0f,
  float scale = 1.0f,
  float angleRad = 0.0f,
  const D3DXVECTOR2* pOffset = NULL,
  const RECT *pSourceRect = NULL
);

パラメータ

pd3dTexture
スプライトのソース イメージとして使用するサーフェスを示し、テクスチャが格納されているサーフェスの IDirectDrawSurface7 インターフェイスへのポインタ。これが NULL の場合、アプリケーションがテクスチャ ステージ 0 に対して IDirect3DDevice7::SetTexture を既に呼び出していると見なされる。
pd3dDevice
IDirect3DDevice7 インターフェイスへのポインタ。スプライトは、このデバイスに対してレンダリングされる。レンダリング状態はこのデバイスに対してセットアップされていると見なされる (「D3DXPrepareDeviceForSprite」を参照すること)。
ppointDest
D3DXVECTOR3 構造体へのポインタ。スプライトの注視点。このベクトルは、スプライトの中心をレンダリングする位置をスクリーン座標で示す。ベクトルの各コンポーネントは、スクリーン空間内になければならない。一般に、ベクトルの z コンポーネントは 0 に設定される。しかし、z バッファを使用しているアプリケーションは、背景から前景にレンダリングしないで、任意の値を指定することができる。
alpha
スプライトの不透明度を示し、スプライトに適用されるアルファ値。1.0 は全体的に不透明であり、0.0 は全体的に透明であることを意味する。ただし、アルファを使用する場合は、アーティファクト (人工物) がレンダリングされないようにするために、背景から前景へレンダリングすること。このアルファ値は、テクスチャ イメージ内に存在するアルファ (存在する場合) と組み合わせられる。
scale
レンダリングするイメージのサイズを指定し、ソース RECT に適用する一様のスケール。デフォルト値は 1.0 であり、スプライトをソースと同じ幅と高さでレンダリングする。
angleRad
RECT の中心を中心とした回転の角度で、スプライトの回転角度を示す。回転は、スプライトの中心を中心として適用される。それは、反時計回りにラジアン単位で指定する。度数からラジアンへ変換する方法については、「D3DXToRadian」を参照すること。
pOffset
回転の中心として使用するソース RECT の中心からのオフセットを定義した D3DXVECTOR2 構造体へのポインタ。このパラメータは、ppointDest パラメータと angleRad パラメータでスプライトの中心として処理されるスプライトの中心点からのオフセットを示す。
pSourceRect
ソース テクスチャの中でスプライトに使用する部分を示す RECT 構造体へのポインタ。このパラメータが NULL の場合、ソース イメージ全体がスプライトで使用される。一方、代わりにソース イメージの小矩形を指定できる。ソース テクスチャが Direct3DX を使用して作成されている場合、RECT 構造体はオリジナル イメージの座標で指定する。そのため、Direct3D カレント デバイスでイメージが機能するように Direct3DX により行われた伸張やスケーリングは必要ない。また、ミラーリングについては、この RECT 構造体の left、top パラメータと right、bottom パラメータを入れ替えるだけで簡単に指定できる。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

C プログラマは、alpha、scale、angleRad、pOffset、および pSourceRect パラメータでデフォルト値を使用でない。

D3DXDrawSpriteSimple 関数は、ソース イメージを 3D レンダリング デバイスにブリッドする。この関数は、pd3dTexture パラメータが NULL 以外の場合、最初のレンダリング ステージでそのパラメータを指定して IDirect3DDevice7::SetTexture を呼び出すだけである。

この関数は、スケーリング、回転、アルファ ブレンディング、ミラーリング、および配置をサポートしている。シャーリングや遠近法などより広い範囲のエフェクトについては、D3DXDrawSpriteTransform 関数を使用すること。

この関数は、D3DXPrepareDeviceForSprite がデバイスで呼び出された、または呼び出し元のアプリケーションが別の方法でレンダリング状態を適切に準備したと仮定している。

回転角度は、ラジアン単位で指定される。回転もスケーリングも、スプライトの中心を中心として適用される。この場合、スプライトの中心は、スプライトの幅と高さの半分に、オフセット パラメータを加えたものになる。スプライトの中心をイメージの中心とは違うものにしたい場合、オフセット パラメータを使用する。

レンダリング先の点は、スプライトの中心を置く位置を示す。2D レンダリングと 3D レンダリングを混合するような上級ユーザーは、それらの座標が完全に変換されていると見なされることを覚えておくこと (つまり、スクリーン空間で、ppointDest パラメータの z コンポーネントを適切に設定する必要がある)。一般に、上級ユーザーはもっと制御するため、代わりに D3DXDrawSprite3D 関数を使用する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxsprite.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXDrawSpriteTransform、D3DXDrawSprite3D、D3DXPrepareDeviceForSprite


D3DXDrawSpriteTransform

D3DXDrawSpriteTransform 関数は、指定行列により変換されたスプライトをレンダリングするためのメカニズムを提供している。この関数は、IDirect3DDevice7::BeginScene 関数を呼び出した後で、IDirect3DDevice7::EndScene 関数を呼び出す前に呼び出す必要がある。

HRESULT D3DXDrawSpriteTransform(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXMATRIX* pMatrixTransform,
  float alpha = 1.0f,
  const RECT* pSourceRect = NULL
);

パラメータ

pd3dTexture
スプライトのソース イメージとして使用するサーフェスを示し、テクスチャが格納されているサーフェスの IDirectDrawSurface7 インターフェイスへのポインタ。これが NULL の場合、アプリケーションがテクスチャ ステージ 0 に対して IDirect3DDevice7::SetTexture を既に呼び出していると見なされる。
pd3dDevice
Direct3D レンダリング デバイスの IDirect3DDevice7 インターフェイスへのポインタ。レンダリング状態がセットアップされていると見なされる。詳細については、「D3DXPrepareDeviceForSprite」を参照すること。
pMatrixTransform
デフォルトの -.5 から +.5 までの矩形に適用される変換を指定した 4 x 4 行列の D3DXMATRIX 構造体へのポインタ。この行列は、スプライトをスクリーン空間に変換する。デフォルトで、スプライトは (-0.5, -0.5) から (+0.5, +0.5) までに置かれている。簡単に回転できるように中心は原点に合わせられ、またスケーリングしやすいように幅と高さは 1 とされている。
alpha
スプライトに適用されるアルファ値。1.0 は全体的に不透明であり、0.0 は全体的に透明であることを意味する。ただし、アルファを使用する場合は、アーティファクト (人工物) がレンダリングされないようにするために、背景から前景へレンダリングすること。また、半透明のオブジェクトが交差しないようにすること。このアルファ値は、テクスチャ イメージ内に存在するアルファ (存在する場合) と組み合わせられる。
pSourceRect
ソース テクスチャの中でスプライトに使用する部分を示す RECT 構造体へのポインタ。このパラメータが NULL の場合、ソース イメージ全体がスプライトで使用される。一方、代わりにソース イメージの小矩形を指定できる。ソース テクスチャが Direct3DX を使用して作成されている場合、RECT 構造体はオリジナル イメージの座標で指定する。そのため、Direct3D カレント デバイスでイメージが機能するように Direct3DX により行われた伸張やスケーリングは必要ない。また、X と Y のミラーリングについては、この RECT 構造体の left、top パラメータと right、bottom パラメータを入れ替えるだけで簡単に指定できる。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

C プログラマは、alpha パラメータと pSourceRect パラメータでデフォルト値を使用できない。

この D3DXDrawSpriteTransform 関数は、行列で指定可能なエフェクト、アルファ ブレンディング、小矩形の選択機能 (ソースの小矩形の値が NULL のときは、テクスチャ全体が使用されることを意味する) をサポートしている。スプライトを総合的に制御するには、D3DXDrawSprite3D 関数を使用する。

この関数は、4 x 4 行列を指定して、デフォルトの RECT 構造体の点を変換し (left=-.5、top=-.5、right=+.5、bottom=+.5)、ソース イメージを Direct3D レンダリング デバイスに変換する。このデフォルトの RECT 構造体は、簡単に回転できるように中心が原点に合わせられている。また、これらのディメンジョンは、スケーリングしやすいように幅と高さを 1 にして作成されている。

この関数は、pd3dTexture パラメータが NULL 以外の場合、最初のレンダリング ステージでそのパラメータを指定して IDirect3DDevice7::SetTexture を呼び出すだけである。この関数は、D3DXPrepareDeviceForSprite がデバイスで呼び出された、または呼び出し元のアプリケーションが別の方法でレンダリング状態を適切に準備したと仮定している。

この関数は、変換された点の w 値 (同次座標) が 1 以外の場合、それを逆変換し、その値を Direct3D に D3DTLVERTEX 構造体の rhw フィールドとして渡すので注意すること。w 値が 0 の場合、rhw として 1 を使用する。

行列が (0, 0, 0, 1) 原点を中心とする単位正方形に適用されると、これらの座標はスクリーン空間に完全に変換されているものと見なされる。上級ユーザーには、z 要素と w 要素を D3DTLVERTEX 構造体で Direct3D 直接モードに渡すことをお勧めする。w 要素は、rhw 要素に変換される。w 値が 0 のとき、rhw 値は 1 となる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxsprite.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXBuildSpriteTransform


D3DXDrawSprite3D

4 点を指定すると、D3DXDrawSprite3D 関数はこれらの点を内包するスプライトを描画する。これらの点は、スクリーン座標で指定する。この関数は、IDirect3DDevice7::BeginScene 関数を呼び出した後で、IDirect3DDevice7::EndScene 関数を呼び出す前に呼び出す必要がある。

HRESULT D3DXDrawSprite3D(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXVECTOR4 quad[4],
  float alpha = 1.0f,
  const RECT* pSourceRect = NULL,
);

パラメータ

pd3dTexture
スプライトのソース イメージとして使用するサーフェスを示し、テクスチャが格納されているサーフェスの IDirectDrawSurface7 インターフェイスへのポインタ。これが NULL の場合、アプリケーションがテクスチャ ステージ 0 に対して IDirect3DDevice7::SetTexture を既に呼び出していると見なされる。
pd3dDevice
Direct3D レンダリング デバイスの IDirect3DDevice7 インターフェイスへのポインタ。レンダリング状態がセットアップされていると見なされる。詳細については、「D3DXPrepareDeviceForSprite」を参照すること。
quad
スクリーン座標の 4 点の配列を左上、右上、右下、左下の順序で表した D3DXVECTOR4 構造体の配列。この関数は、これらのベクトルに w 値が含まれている場合、その値を逆にして、rhw 値として渡す (逆同次座標)。IDirect3DDevice7::DrawPrimitive メソッドに渡す D3DTLVERTEX の z 座標と rhw 座標は、z 座標と w 座標が使用される。
alpha
スプライトに適用されるアルファ値。1.0 は全体的に不透明であり、0.0 は全体的に透明であることを意味する。ただし、アルファを使用する場合は、アーティファクト (人工物) がレンダリングされないようにするために、背景から前景へレンダリングすること。また、半透明のオブジェクトが交差しないようにすること。このアルファ値は、テクスチャ イメージ内に存在するアルファ (存在する場合) と組み合わせられる。
pSourceRect
ソース テクスチャの中でスプライトに使用する部分を示す RECT 構造体へのポインタ。このパラメータが NULL の場合、ソース イメージ全体がスプライトで使用される。一方、代わりにソース イメージの小矩形を指定できる。ソース テクスチャが Direct3DX を使用して作成されている場合、RECT 構造体はオリジナル イメージの座標で指定する。そのため、Direct3D カレント デバイスでイメージが機能するように Direct3DX により行われた伸張やスケーリングは必要ない。また、X と Y のミラーリングについては、この RECT 構造体の left、top パラメータと right、bottom パラメータを入れ替えるだけで簡単に指定できる。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

C プログラマは、alpha パラメータと pSourceRect パラメータでデフォルト値を使用できない。

D3DXDrawSprite3D 関数を、非頂点三角形で使用することはお勧めしない。

この関数は、テクスチャを 3D 多角四角形にレンダリングする。四角形 ABCD を 2 つの三角形 ABC と ACD に分割し、IDirect3DDevice7::DrawPrimitive メソッドを呼び出してレンダリングする。

高度なアプリケーションでもっと豊富な制御機能が必要な場合には、IDirect3DDevice7::DrawPrimitive メソッドを参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxsprite.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXPrepareDeviceForSprite

D3DXPrepareDeviceForSprite 関数は、デバイスを別のスプライト ヘルパー関数で使用できるように準備するため、多数のレンダリング状態を設定する。特に、アルファ ブレンディングと双一次フィルタリングをセットアップする。パラメータは、z バッファを有効にするかどうかを制御する。

HRESULT D3DXPrepareDeviceForSprite(
  LPDIRECT3DDEVICE7 pd3dDevice,
  BOOL ZEnable = FALSE
);

パラメータ

pd3dDevice
Direct3DX スプライト サービスで使用するために準備する Direct3D デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
ZEnable
スプライトにより z バッファ サーフェスをチェックし、それをレンダリングの一部として更新するかどうかを示すフラグ。通常のアプリケーションでスプライトは背景から前景へとレンダリングされるので、デフォルト値は FALSE である。2D と 3D を混合するような高度なアプリケーションで、この値を TRUE に設定する。ZEnable が FALSE の場合、またはアルファ ブレンディングを使用している場合、スプライトは背景から前景へとレンダリングする必要がある。

戻り値

成功すれば、S_OK を返す。失敗すれば、D3DXERR_NULLPOINTER を返す。

注意

C プログラマは、ZEnable パラメータでデフォルト値を使用できない。

この関数を呼び出して、D3DXDrawSpriteSimple 関数と D3DXDrawSprite3D 関数が適切に機能するために必要なすべてのレンダリング状態をセットアップする。ただし上級ユーザーは、デバイスにセットアップされたレンダリング状態とテクスチャ状態を D3DXDrawSpriteSimple 関数と D3DXDrawSprite3D 関数で使用する場合に、この関数を呼び出さないこともある。

メモ D3DXPrepareDeviceForSprite 関数は、レンダリング状態を修正するが、フレームごとに頻繁に呼び出されると 3D ハードウェアのパフォーマンスに悪影響を与える可能性がある。レンダリング状態が (D3DXDrawSpriteSimple 関数や D3DXDrawSprite3D 関数を呼び出す以外の方法で) 変更された場合、D3DXDrawSpriteSimple 関数や D3DXDrawSprite3D 関数を呼び出す前にこの関数を再度呼び出す必要がある。

D3DXPrepareDeviceForSprite 関数は、レンダリングの最初のテクスチャ ステージを修正し、デバイス全体のレンダリング状態をいくつか修正する。次に、そのリストを示す。

    SetTextureStageState(0, D3DTSS_COLORARG1,         D3DTA_TEXTURE);
    SetTextureStageState(0, D3DTSS_COLOROP,           D3DTOP_SELECTARG1);
    SetTextureStageState(0, D3DTSS_ALPHAARG1,         D3DTA_TEXTURE);
    SetTextureStageState(0, D3DTSS_ALPHAARG2,         D3DTA_DIFFUSE);
    SetTextureStageState(0, D3DTSS_ALPHAOP,           D3DTOP_MODULATE);
    SetTextureStageState(0, D3DTSS_MINFILTER,         D3DTFN_LINEAR);
    SetTextureStageState(0, D3DTSS_MAGFILTER,         D3DTFG_LINEAR);

    SetRenderState(D3DRENDERSTATE_SRCBLEND,           D3DBLEND_SRCALPHA);
    SetRenderState(D3DRENDERSTATE_DESTBLEND,          D3DBLEND_INVSRCALPHA);
    SetRenderState(D3DRENDERSTATE_ALPHABLENDENABLE,   TRUE);

ZEnable パラメータの値に基づいて、次のいずれかが呼び出される。

    SetRenderState(D3DRENDERSTATE_ZENABLE,            FALSE);

または

    SetRenderState(D3DRENDERSTATE_ZENABLE,            TRUE);

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxsprite.h で宣言。
ライブラリ : d3dx.lib を使用。


テクスチャ関数

Direct3DX ユーティリティ ライブラリにより提供されているテクスチャ処理アプリケーション プログラミング インターフェイス (API) では、テクスチャ フォーマットの変換、テクスチャの作成とロード、テクスチャのフィルタリング、ミップマップの生成を行うための関数が提供されている。

テクスチャ処理 API の関数は、以下のグループにまとめることができる。

作成 | D3DXCreateCubeMapTexture
 | D3DXCreateTexture
 | D3DXCreateTextureFromFile
ロード | D3DXLoadTextureFromFile
 | D3DXLoadTextureFromMemory
 | D3DXLoadTextureFromSurface
その他 | D3DXCheckTextureRequirements


D3DXCheckTextureRequirements

D3DXCheckTextureRequirements 関数は、テクスチャ作成に関する情報を返す。この関数を使用すれば、Direct3DDevice カレント デバイスで機能している最も近いサーフェス タイプを簡単に判定できる。理想のテクスチャのフォーマット、幅、高さ、およびミップマップ フラグを指定すると、選択したデバイスで機能している最も近いサーフェス タイプが返される。

HRESULT D3DXCheckTextureRequirements(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
);

パラメータ

pd3dDevice
テクスチャに関連付けられている Direct3D デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
pFlags
DWORD 値へのポインタ。ミップマップを生成しない場合、このパラメータにより D3DX_TEXTURE_NOMIPMAP フラグを指定する。この値に、NULL を指定することも可能である。ミップマップ生成がサポートされていない場合は、D3DX_TEXTURE_NOMIPMAP フラグが返される。
pWidth
幅を示す DWORD 値へのポインタ (ピクセル単位)。0 または D3DX_DEFAULT を指定した場合、幅はファイルから取得される。このパラメータは、補正された幅を返す。
pHeight
高さを示す DWORD 値へのポインタ (ピクセル単位)。0 または D3DX_DEFAULT を指定した場合、高さはファイルから取得される。このパラメータは、補正された高さを返す。
pPixelFormat
D3DX_SURFACEFORMAT 列挙型のメンバへのポインタ。このパラメータの入力値は、適切なテクスチャ フォーマットである。戻り値は、ハードウェアでサポートされている最も近いテクスチャ フォーマットである。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NULLPOINTER

注意

この関数は、D3DXCreateTexture 関数、D3DXCreateTextureFromFile 関数、および D3DXCreateCubeMapTexture 関数で必要なサイズ変更やフォーマット変換を判定するときに役に立つ。ほとんどの場合、この手順を実行しなくても作成関数を直接使用できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。


D3DXCreateCubeMapTexture

D3DXCreateCubeMapTexture 関数は、空白のキューブ マップ テクスチャを作成する。

HRESULT D3DXCreateCubeMapTexture(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  DWORD cubefaces,
  D3DCOLOR colorEmptyFaces,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps
);

パラメータ

pd3dDevice
テクスチャに関連付けられている Direct3D デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
pFlags
DWORD 値へのポインタ。ミップマップを生成しない場合、このパラメータにより D3DX_TEXTURE_NOMIPMAP フラグを指定する。この値に、NULL を指定することも可能である。ミップマップ生成がサポートされていない場合は、D3DX_TEXTURE_NOMIPMAP フラグが返される。
cubefaces
このパラメータには、生成するキューブ マップのサーフェスを指定できる。詳細については、「注意」を参照すること。
colorEmptyFaces
このパラメータの D3DCOLOR 型には、キューブ マップで不明のサーフェス (cubefaces パラメータで指定されなかったサーフェス) の位置を確保するために 1 つの A8R8G8B8 カラーを指定できる。
pWidth
幅を示す DWORD 値へのポインタ (ピクセル単位)。0 または D3DX_DEFAULT を指定した場合、幅はファイルから取得される。このパラメータは、補正された幅を返す。
pHeight
高さを示す DWORD 値へのポインタ (ピクセル単位)。0 または D3DX_DEFAULT を指定した場合、高さはファイルから取得される。このパラメータは、補正された高さを返す。
pPixelFormat
サーフェス フォーマットを示す D3DX_SURFACEFORMAT 列挙型のメンバへのポインタ。このパラメータには、D3DX_DEFAULT を入力できない。このパラメータでは、使用されているサーフェス フォーマットが返される。
pDDPal
パレット化サーフェスに設定されている (存在する場合) DirectDraw パレットの IDirectDrawPalette インターフェイスへのポインタ。これは、非パレット化サーフェスの場合、設定されていても無視される。そのため、結果サーフェスが 8 ビットのパレット化サーフェスの場合は、使用するパレットを指定できる。
ppDDSurf
指定内容やカレント ハードウェアに一致し、作成されたテクスチャの DirectDrawSurface オブジェクトへのポインタのアドレス。
pNumMipMaps
DWORD 値へのポインタ。キューブ マップの特定のサーフェスに対して生成されたミップマップの数。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DERR_TEXTURE_NO_SUPPORT
D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NULLPOINTER
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_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

注意

キューブ マップは、最大で 6 サーフェスを持つ。また、不明のサーフェスで使用する色を 1 つ指定できる。反射の錯視や屈折を作成するためにキューブ マップを使用する方法の詳細については、Direct3D 直接モードのドキュメントを参照すること。

cubefaces パラメータに D3DX_DEFAULT、0、DDSCAPS2_CUBEMAP_ALLFACES を指定した場合は、キューブ マップの 6 サーフェスすべてを作成するように指示される。DDSCAPS2_CUBEMAP_POSITIVEX、DDSCAPS2_CUBEMAP_NEGATIVEX、DDSCAPS2_CUBEMAP_POSITIVEY、DDSCAPS2_CUBEMAP_NEGATIVEY、DDSCAPS2_CUBEMAP_POSITIVEZ、または DDSCAPS2_CUBEMAP_NEGATIVEZ は、任意に組み合わせて指定できる。

pFlags パラメータがミップマップを作成しないように特に設定されていない限り、最低レベル サイズの 1x1 に達するまでミップマップは生成される。

ミップマップの詳細については、ミップマップによるテクスチャ フィルタリング を参照すること。

幅、高さ、ピクセル フォーマットは、使用可能なハードウェアに基づいて変わる。たとえば、ミップマップ ディメンジョンは 2 の累乗でなければならず、また幅は正方形テクスチャの高さと等しくなければならない。さらに、指定されたピクセル フォーマットを使用できない場合、最適に適合される。

この関数は、サイズとピクセル フォーマットをカレント デバイスの要件に合わせて調整したサーフェスを作成する。このサーフェスは、テクスチャ管理のマークが付けられたシステム メモリである。詳細については、Direct3D 直接モードのドキュメントを参照すること。

作成されたサーフェスは、幅パラメータと高さパラメータにより指定されたサーフェスよりも大きかったり、小さかったりする。選択されたピクセル フォーマットが、渡されたフォーマットでない場合もある。しかし、実際の幅、高さ、ピクセル フォーマットに注意を払わなければならないのは、この関数により返されたサーフェスに直接アクセスする場合だけである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateTexture


D3DXCreateTexture

D3DXCreateTexture 関数は、空のテクスチャ オブジェクトを作成する。

HRESULT D3DXCreateTexture(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps
);

パラメータ

pd3dDevice
テクスチャに関連付けられている Direct3D デバイスの IDirect3DDevice7 インターフェイス。
pFlags
DWORD 値へのポインタ。ミップマップを生成しない場合、このパラメータにより D3DX_TEXTURE_NOMIPMAP フラグを指定する。この値に、NULL を指定することも可能である。ミップマップ生成がサポートされていない場合は、D3DX_TEXTURE_NOMIPMAP フラグが返される。
pWidth
幅を示す DWORD 値へのポインタ (ピクセル単位)。このパラメータは、補正された幅を返す。
pHeight
高さを示す DWORD 値へのポインタ (ピクセル単位)。このパラメータは、補正された高さを返す。
pPixelFormat
D3DX_SURFACEFORMAT 列挙型のメンバへのポインタ。このパラメータでは、D3DX_DEFAULT は有効でない。このパラメータの入力値は、適切なテクスチャ フォーマットである。戻り値は、ハードウェアでサポートされている最も近いテクスチャ フォーマットである。
pDDPal
パレット化サーフェスに設定されている (存在する場合) DirectDraw パレットの IDirectDrawPalette インターフェイスへのポインタ。これは、非パレット化サーフェスの場合、設定されていても無視される。そのため、結果サーフェスが 8 ビットのパレット化サーフェスの場合は、使用するパレットを指定できる。
ppDDSurf
指定内容やカレント ハードウェアに一致し、作成されたテクスチャの DirectDrawSurface オブジェクトへのポインタのアドレス。
pNumMipMaps
DWORD 値へのポインタ。キューブ マップの特定のサーフェスに対して生成されたミップマップの数。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NULLPOINTER
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_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

注意

pFlags パラメータがミップマップを作成しないように特に設定されていない限り、最低レベル サイズの 1 x 1 に達するまでミップマップは生成される。

ミップマップの詳細については、「ミップマップによるテクスチャ フィルタリング」を参照すること。

幅、高さ、ピクセル フォーマットは、使用可能なハードウェアに基づいて変わる。たとえば、ミップマップ ディメンジョンは 2 の累乗でなければならず、また幅は正方形テクスチャの高さと等しくなければならない。さらに、指定されたピクセル フォーマットを使用できない場合、最適に適合される。

この関数は、サイズとピクセル フォーマットをカレント デバイスの要件に合わせて調整したサーフェスを作成する。このサーフェスは、テクスチャ管理のマークが付けられたシステム メモリである。詳細については、Direct3D 直接モードのドキュメントを参照すること。

作成されたサーフェスは、幅パラメータと高さパラメータにより指定されたサーフェスよりも大きかったり、小さかったりする。選択されたピクセル フォーマットが、渡されたフォーマットでない場合もある。しかし、実際の幅、高さ、ピクセル フォーマットに注意を払わなければならないのは、この関数により返されたサーフェスに直接アクセスする場合だけである (ただし、サーフェスのプロパティはデバイスごとに異なるので、直接アクセスすることはお勧めしない)。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateCubeMapTexture


D3DXCreateTextureFromFile

D3DXCreateTextureFromFile 関数は、スタンドアロン ファイルまたはリソースからテクスチャ オブジェクトを作成する。

HRESULT D3DXCreateTextureFromFile(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps,
  LPSTR pSrcName,
  D3DX_FILTERTYPE filterType
);

パラメータ

pd3dDevice
テクスチャに関連付けられた Direct3D デバイスの IDirect3DDevice7 インターフェイス。
pFlags
DWORD 値へのポインタ。ミップマップを生成しない場合、このパラメータにより D3DX_TEXTURE_NOMIPMAP フラグを指定する。この値に、NULL を指定することも可能である。ミップマップ生成がサポートされていない場合は、D3DX_TEXTURE_NOMIPMAP フラグが返される。
pWidth
幅を示す DWORD 値へのポインタ (ピクセル単位)。0 または D3DX_DEFAULT を指定した場合、幅はファイルから取得される。このパラメータは、補正された幅を返す。
pHeight
高さを示す DWORD 値へのポインタ (ピクセル単位)。0 または D3DX_DEFAULT を指定した場合、高さはファイルから取得される。このパラメータは、補正された高さを返す。
pPixelFormat
D3DX_SURFACEFORMAT 列挙型のメンバへのポインタ。このパラメータでは、D3DX_DEFAULT は有効でない。このパラメータの入力値は、適切なテクスチャ フォーマットである。戻り値は、ハードウェアでサポートされている最も近いテクスチャ フォーマットである。D3DX_SF_UNKNOWN を指定すると、ビットマップに最も近いピクセル フォーマットが選択される。
pDDPal
パレット化サーフェスに設定されている (存在する場合) DirectDraw パレットの IDirectDrawPalette インターフェイスへのポインタ。これは、非パレット化サーフェスの場合、設定されていても無視される。
ppDDSurf
指定内容やカレント ハードウェアに一致し、作成されたテクスチャの DirectDrawSurface オブジェクトへのポインタのアドレス。
pNumMipMaps
DWORD 値へのポインタ。生成されたミップマップの数。
pSrcName
ファイル名文字列へのポインタ。BMP、DIB、DDS のファイル タイプがサポートされている。詳細については、「注意」を参照すること。
filterType
サイズの変更やミップマップの生成が必要なときに使用するフィルタリング関数を示す D3DX_FILTERTYPE 列挙型のメンバ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、NULL または次のいずれかの値を返す。

D3DERR_TEXTURE_NO_SUPPORT
D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDFILEFORMAT
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
D3DXERR_UNSUPPORTEDFILEFORMAT
DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOTFOUND
DDERR_NOTLOCKED
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

注意

実行可能ファイルのリソース部分でサポートされているのは、BMP ファイルと DIB ファイルだけである。

pSrcName パラメータで、16bpp、24bpp、32bpp の正のカラーと 8bpp のパレット化の場合は TGA がサポートされている。また、8bpp と 16bpp のグレー スケールもサポートされている。前の TGA フォーマットである RLE バージョンもサポートされている。ただし TGA ファイルでは、カラー キー化したアルファや左方乗法されたアルファは現在サポートされていない。

pSrcName パラメータに数値 ID を指定した場合、D3DXLoadTextureFromFile 関数に実行可能ファイルのリソースからビットマップ イメージをロードするように指示される。それ以外の場合、pSrcName はファイル名であると見なされる。ただし、D3DXCreateTextureFromFile 関数では文字列ポインタがファイル名として扱われるので、文字列のリソース名は使用できない。

pFlags パラメータがミップマップを作成しないように特に設定されていない限り、最低レベル サイズの 1 x 1 に達するまでミップマップは生成される。

ミップマップの詳細については、「ミップマップによるテクスチャ フィルタリング」を参照すること。

幅、高さ、ピクセル フォーマットは、使用可能なハードウェアに基づいて変わる。たとえば、ミップマップ ディメンジョンは 2 の累乗でなければならず、また幅は正方形テクスチャの高さと等しくなければならない。さらに、指定されたピクセル フォーマットを使用できない場合、最適に適合される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXLoadTextureFromFile


D3DXLoadTextureFromFile

D3DXLoadTextureFromFile 関数は、テクスチャをファイルからミップマップ レベルにロードし、必要なカラー変換や再スケーリングを実行する。

HRESULT D3DXLoadTextureFromFile(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPSTR pSrcName,
  RECT* pSrcRect,
  RECT* pDestRect,
  D3DX_FILTERTYPE filterType
);

パラメータ

pd3dDevice
テクスチャに関連付けられている Direct3D デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
pTexture
D3DXCreateTextureFromFile 関数または D3DXCreateTexture 関数のいずれかにより作成された DirectDrawSurface へのポインタ。このパラメータは、テクスチャ サーフェス オブジェクトをポイントする。
mipMapLevel
ミップマップ レベルを示す。「注意」を参照すること。
pSrcName
ファイル名文字列へのポインタ。BMP、DIB、DDS のファイル タイプがサポートされている。詳細については、「注意」を参照すること。
pSrcRect
ロード元の矩形を識別する RECT 構造体へのポインタ。このパラメータに NULL を指定した場合は、サーフェス全体が使用される。
pDestRect
ロード先の矩形を識別する RECT 構造体へのポインタ。このパラメータに NULL を指定した場合は、サーフェス全体が使用される。
filterType
ミップマップ生成時に使用されるフィルタを示す D3DX_FILTERTYPE 列挙型のメンバ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、NULL または次のいずれかの値を返す。

D3DERR_TEXTURE_NO_SUPPORT
D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDFILEFORMAT
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
D3DXERR_UNSUPPORTEDFILEFORMAT
DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOTFOUND
DDERR_NOTLOCKED
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

注意

この関数は、ファイルからサーフェスへピクセルをコピーするためのメカニズムを提供する。

次に、mipMapLevel パラメータで考慮すべき事柄を示す。

  • 指定したミップマップ レベルが存在しない場合、エラーが返される。
  • D3DX_DEFAULT が指定されている場合に、同数のミップマップ レベルが存在するとき、すべてのロード元ミップマップ レベルがロードされる。
  • ミップマップ レベルがロード元ファイルにはあり、ロード先サーフェスにない場合、最上位レベルが使用される。
  • ミップマップ レベルがロード先サーフェスにはあり、ロード元ファイルにない場合、拡大が行われる。
  • ロード元ファイルとロード先サーフェスのミップマップ レベルの数が等しくない場合、拡大が行われる。

pSrcName パラメータで、16bpp、24bpp、32bpp の正のカラーと 8bpp のパレット化の場合は TGA がサポートされている。また、8bpp と 16bpp のグレー スケールもサポートされている。前の TGA フォーマットである RLE バージョンもサポートされている。ただし TGA ファイルでは、カラー キー化したアルファや左方乗法されたアルファは現在サポートされていない。

ロード先サーフェスが Direct3DX により作成された場合、RECT 構造体はそのサーフェスのオリジナル座標で指定される。

この関数は、D3DX_SURFACEFORMAT 構造体により記述可能なすべてのサーフェス フォーマットについて、カラー変換の全範囲をサポートしている。また、フィルタリングした再スケーリングを実装したり、ミップマップを自動更新する。

pDestRect をオリジナル イメージの空間に設定すれば、アプリケーションは D3DXCreateTexture 関数の中でサーフェスがどのようにサイズ変更されても心配しなくてもよい。たとえば、イメージが 100 x 150 ピクセルの場合、構成が異なれば 128 x 256 になったり 256 x 256 になる。どちらの場合も、第 2 象限を更新するときに使用する RECT 構造体はサイズ変更が行われていないときのように (0, 0, 50, 75) となる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXCreateTextureFromFile、D3DXLoadTextureFromMemory、D3DXLoadTextureFromSurface


D3DXLoadTextureFromMemory

D3DXLoadTextureFromMemory 関数は、ミップマップ レベルをメモリからロードし、必要なカラー変換を実行する。

HRESULT D3DXLoadTextureFromMemory(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPVOID pMemory,
  LPDIRECTDRAWPALETTE pDDPal,
  D3DX_SURFACEFORMAT srcPixelFormat,
  DWORD srcPitch,
  RECT* pDestRect,
  D3DX_FILTERTYPE filterType
);

パラメータ

pd3dDevice
テクスチャに関連付けられている Direct3D デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
pTexture
D3DXCreateTextureFromFile 関数または D3DXCreateTexture 関数のいずれかにより作成された DirectDrawSurface へのポインタ。このパラメータは、テクスチャ サーフェス オブジェクトをポイントする。
mipMapLevel
ミップマップ レベルを示す。「注意」を参照すること。
pMemory
テクスチャのロード元メモリへのポインタ。
pDDPal
メモリでパレット化がサポートされている場合、アプリケーションからオプションで渡される DirectDraw パレットの IDirectDrawPalette インターフェイスへのポインタ。
srcPixelFormat
ロード元のピクセル フォーマットを示す D3DX_SURFACEFORMAT 列挙型のメンバへのポインタ。
srcPitch
メモリのピッチまたは D3DX_DEFAULT。このパラメータは、srcPixelFormat パラメータが基になっている。
pDestRect
ロード先矩形を識別する RECT 構造体へのポインタ。このパラメータに NULL を指定した場合は、サーフェス全体が使用される。
filterType
ミップマップ生成時に使用されるフィルタを示す D3DX_FILTERTYPE 列挙型のメンバ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST
DDERR_UNSUPPORTED

注意

この関数は、メモリからサーフェスへいくつかのピクセルをコピーするためのメカニズムを提供する。

ロード先サーフェスが Direct3DX により作成された場合、RECT 構造体はそのサーフェスのオリジナル座標で指定される。

次に、mipMapLevel パラメータで考慮すべき事柄を示す。

  • 指定したミップマップ レベルが存在しない場合、エラーが返される。
  • D3DX_DEFAULT が指定されている場合に、同数のミップマップ レベルが存在するとき、すべてのロード元ミップマップ レベルがロードされる。
  • ミップマップ レベルがロード元メモリにはあり、ロード先サーフェスにない場合、最上位レベルが使用される。
  • ミップマップ レベルがロード先サーフェスにはあり、ロード元メモリにない場合、拡大が行われる。
  • ロード元メモリとロード先サーフェスのミップマップ レベルの数が等しくない場合、拡大が行われる。

この関数は、ロード元メモリがすべてロードされているものと仮定している。

この関数は、D3DX_SURFACEFORMAT 構造体により記述可能なすべてのサーフェス フォーマットについて、カラー変換の全範囲をサポートしている。また、フィルタリングした再スケーリングを実装したり、ミップマップを自動更新する。

pDestRect をオリジナル イメージの空間に設定すれば、アプリケーションは D3DXCreateTexture 関数の中でサーフェスがどのようにサイズ変更されても心配しなくてもよい。たとえば、イメージが 100 x 150 ピクセルの場合、構成が異なれば 128 x 256 になったり 256 x 256 になる。どちらの場合も、第 2 象限を更新するときに使用する RECT 構造体はサイズ変更が行われていないときのように (0, 0, 50, 75) となる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXLoadTextureFromFile、D3DXLoadTextureFromSurface


D3DXLoadTextureFromSurface

D3DXLoadTextureFromSurface 関数は、テクスチャを DirectDrawSurface からミップマップ レベルにロードし、必要なカラー変換を実行する。

HRESULT D3DXLoadTextureFromSurface(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPDIRECTDRAWSURFACE7 pSurfaceSrc,
  RECT* pSrcRect,
  RECT* pDestRect,
  D3DX_FILTERTYPE filterType
);

パラメータ

pd3dDevice
テクスチャに関連付けられている Direct3D デバイスの IDirect3DDevice7 インターフェイスへのポインタ。
pTexture
D3DXCreateTextureFromFile 関数または D3DXCreateTexture 関数のいずれかにより作成された DirectDrawSurface へのポインタ。このパラメータは、テクスチャ サーフェス オブジェクトをポイントする。
mipMapLevel
ミップマップ レベルを示す。「注意」を参照すること。
pSurfaceSrc
ロード元サーフェスの IDirectDrawSurface7 インターフェイスへのポインタ。ロード元ピクセルが格納されたサーフェス オブジェクト。
pSrcRect
ロード元矩形を識別する RECT 構造体へのポインタ。このパラメータに NULL を指定した場合は、サーフェス全体が使用される。
pDestRect
ロード先矩形を識別する RECT 構造体へのポインタ。このパラメータに NULL を指定した場合は、サーフェス全体が使用される。
filterType
サイズ変更やミップマップ生成が必要なときに使用されるフィルタ関数を示す D3DX_FILTERTYPE 列挙型のメンバ。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST
DDERR_UNSUPPORTED

注意

この関数は、あるサーフェスから別のサーフェスへコピーするためのメカニズムを提供する。

次に、mipMapLevel パラメータで考慮すべき事柄を示す。

  • 指定したミップマップ レベルが存在しない場合、エラーが返される。
  • D3DX_DEFAULT が指定されている場合に、同数のミップマップ レベルが存在するとき、すべてのロード元ミップマップ レベルがロードされる。
  • ミップマップ レベルがロード元サーフェスにはあり、ロード先サーフェスにない場合、最上位レベルが使用される。
  • ミップマップ レベルがロード先サーフェスにはあり、ロード元サーフェスにない場合、拡大が行われる。
  • ロード元サーフェスとロード先サーフェスのミップマップ レベルの数が等しくない場合、拡大が行われる。

ロード元サーフェスやロード先サーフェスが Direct3DX により作成された場合、RECT 構造体はそのサーフェスのオリジナル座標で指定される。

この関数は、D3DX_SURFACEFORMAT 構造体により記述可能なすべてのサーフェス フォーマットについて、カラー変換の全範囲をサポートしている。また、フィルタリングした再スケーリングを実装したり、ミップマップを自動更新する。

pDestRect をオリジナル イメージの空間に設定すれば、アプリケーションは D3DXCreateTexture 関数の中でサーフェスがどのようにサイズ変更されても心配しなくてもよい。たとえば、イメージが 100 x 150 ピクセルの場合、構成が異なれば 128 x 256 になったり 256 x 256 になる。どちらの場合も、第 2 象限を更新するときに使用する RECT 構造体はサイズ変更が行われていないときのように (0, 0, 50, 75) となる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。
ライブラリ : d3dx.lib を使用。

参照

D3DXLoadTextureFromFile、D3DXLoadTextureFromMemory


マクロ

ここでは、Direct3DX ユーティリティ ライブラリが提供するマクロのリファレンス情報を記述する。

  • D3DXToDegree
  • D3DXToRadian


D3DXToDegree

D3DXToDegree マクロは、ラジアンを度数に変換する。

D3DXToDegree( radian ) ((radian) * (180.0f / D3DX_PI))

パラメータ

radian
度数に変換する値 (ラジアン単位)。

戻り値

マクロは、ラジアン値を度数で返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。

参照

D3DXToRadian


D3DXToRadian

D3DXToRadian マクロは、度数をラジアンに変換する。

D3DXToRadian( degree ) ((degree) * (D3DX_PI / 180.0f))

パラメータ

degree
ラジアンに変換する値 (度数)。

戻り値

マクロは、度数値をラジアン単位で返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。

参照

D3DXToDegree


構造体

ここでは、Direct3DX ユーティリティ ライブラリで使用される以下の構造体について記述する。

  • D3DX_DEVICEDESC
  • D3DX_VIDMODEDESC
  • D3DXCOLOR
  • D3DXMATRIX
  • D3DXPLANE
  • D3DXQUATERNION
  • D3DXVECTOR2
  • D3DXVECTOR3
  • D3DXVECTOR4


D3DX_DEVICEDESC

D3DX_DEVICEDESC 構造体は、3D でレンダリングできるデバイスを記述する。

typedef struct _D3DX_DEVICEDESC {
  DWORD       deviceIndex;
  DWORD       hwLevel;
  GUID        ddGuid;
  GUID        d3dDeviceGuid;
  GUID        ddDeviceID;
  char        driverDesc[D3DX_DRIVERDESC_LENGTH];
  HMONITOR    monitor;
  BOOL        onPrimary;
} D3DX_DEVICEDESC;

メンバ

deviceIndex
デバイスの一意の番号 (DWORD)。
hwLevel
関係のあるアクセラレート レベル。これは、事前に定義されたデバイス インデックスの 1 つであり、情報提供のためだけにこの構造体に用意されている。システムにデバイスが複数あるときは、同じ hwLevel となる。D3DX ユーティリティ ライブラリで特定のデバイスを参照するには、代わりに deviceIndex メンバの値を使用する。
ddGuid
DirectDraw グローバル ユニーク識別子 (GUID)。
d3dDeviceGuid
Direct3DDevice の GUID。
ddDeviceID
IDirectDraw7::GetDeviceIdentifier の GUID。この GUID は、特定ビデオ カードの特定ドライバ バージョンに対して一意である。
driverDesc
ドライバを記述した文字列。可能な最大文字列長は 256 文字である。
monitor
このデバイスにより使用されるビデオ モニタのハンドル (マルチ モニタ特有)。マルチ モニタ システムで複数のモニタを使用するデバイスでは、このフィールドにさまざまな値が報告される。そのためマルチ モニタ システムについてテストするとき、アプリケーションは Direct3DX デバイス リストの複数のモニタ ハンドルを検索する。
onPrimary
デバイスがプライマリ モニタ上にあるかどうかを示す (マルチ モニタ特有)。

注意

次のステートメントは、driverDesc 文字配列パラメータで使用される定数を定義する。

#define D3DX_DRIVERDESC_LENGTH    256

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。


D3DX_VIDMODEDESC

D3DX_VIDMODEDESC 構造体は、ディスプレイ モードを記述する。

typedef struct  _D3DX_VIDMODEDESC {
  DWORD width;
  DWORD height;
  DWORD bpp;
  DWORD refreshRate;
} D3DX_VIDMODEDESC;

メンバ

width
画面の幅。
height
画面の高さ。
bpp
ピクセルあたりのビット数。
refreshRate
リフレッシュ レート。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。


D3DXCOLOR

D3DX_DEVICEDESC 構造体は、カラー値を記述する。

typedef struct D3DXCOLOR {
  FLOAT r, g, b, a;
} D3DXCOLOR;

メンバ

r
色の赤成分。
g
色の緑成分。
b
色の青成分。
a
色のアルファ成分。

注意

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXCOLOR 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。

参照

D3DXColorNegative、D3DXColorAdd、D3DXColorSubtract、D3DXColorScale、D3DXColorModulate、D3DXColorLerp


D3DXMATRIX

D3DXMATRIX 構造体は、行列を記述する。

typedef struct D3DXMATRIX {
  union
  {
    float m[4][4];
  };
} D3DXMATRIX;

注意

Direct3DX で射影行列の m23 要素には、負の値を設定できない。アプリケーションは、この要素で負の値を使用しなければならない場合、その代わりに射影行列全体を –1 によりスケーリングする。

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXMATRIX 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。

参照

D3DXMatrixIdentity、D3DXMatrixIsIdentity、D3DXMatrixfDeterminant、D3DXMatrixMultiply、D3DXMatrixTranspose、D3DXMatrixInverse、D3DXMatrixScaling、D3DXMatrixTranslation、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationZ、D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationYawPitchRoll、D3DXMatrixTransformation、D3DXMatrixAffineTransformation、D3DXMatrixLookAt、D3DXMatrixPerspective、D3DXMatrixPerspectiveFov、D3DXMatrixPerspectiveOffCenter、D3DXMatrixOrtho、D3DXMatrixOrthoOffCenter、D3DXMatrixShadow、D3DXMatrixReflect


D3DXPLANE

D3DXPLANE 構造体は、平面を記述する。

typedef struct D3DXPLANE {
  float a, b, c, d;
} D3DXPLANE;

メンバ

a
一般平面式のクリップ面の a 係数。「注意」を参照すること。
b
一般平面式のクリップ面の b 係数。「注意」を参照すること。
c
一般平面式のクリップ面の c 係数。「注意」を参照すること。
d
一般平面式のクリップ面の d 係数。「注意」を参照すること。

注意

D3DXPLANE 構造体のメンバは、一般平面式の形式をとる。メンバは、ax + by + cz + dw = 0 といった一般平面式に適合する。

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXPLANE 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた単項演算子や 2 項演算子が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。

参照

D3DXPlaneDot、D3DXPlaneDotCoord、D3DXPlaneDotNormal、D3DXPlaneIntersectLine、D3DXPlaneFromPointNormal、D3DXPlaneFromPoints、D3DXPlaneTransform


D3DXQUATERNION

D3DXQUATERNION 構造体は、クオータニオンを記述する。

typedef struct D3DXQUATERNION {
  float x, y, z, w;
} D3DXQUATERNION;

メンバ

x
x コンポーネント。
y
y コンポーネント。
z
z コンポーネント。
w
w コンポーネント。

注意

クオータニオンは、ベクトルを定義した [x, y, z] 値に第 4 元を追加し、任意の 4D ベクトルを生成する。次に、単位クオータニオンの各元が軸/角度の回転にどのように関係しているかを示す (ただし、q は単位クオータニオン (x, y, z, w) を表し、axis は正規化され、theta は軸を回転軸とした CCW 回転である)。

q.x = sin(theta/2) * axis.x
q.y = sin(theta/2) * axis.y
q.z = sin(theta/2) * axis.z
q.w = cos(theta/2)

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXQUATERNION 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。

参照

D3DXPlaneDot、D3DXPlaneDotCoord、D3DXPlaneDotNormal、D3DXPlaneIntersectLine、D3DXPlaneFromPointNormal、D3DXPlaneFromPoints、D3DXPlaneTransform


D3DXVECTOR2

D3DXVECTOR2 構造体は、2 次元 (2D) 空間のベクトルを記述する。

typedef struct D3DXVECTOR2 {
  float x, y;
} D3DXVECTOR2;

メンバ

x
x コンポーネント。
y
y コンポーネント。

注意

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXVECTOR2 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。

参照

D3DXVec2Length、D3DXVec2LengthSq、D3DXVec2Dot、D3DXVec2CCW、D3DXVec2Add、D3DXVec2Subtract、D3DXVec2Minimize、D3DXVec2Maximize、D3DXVec2Scale、D3DXVec2Lerp、D3DXVec2Normalize、D3DXVec2Hermite、D3DXVec2Hermite、D3DXVec2Transform、D3DXVec2TransformCoord、D3DXVec2TransformNormal


D3DXVECTOR3

D3DXVECTOR3 構造体は、3 次元 (3D) 空間のベクトルを記述する。

typedef struct D3DXVECTOR3 {
  float x, y, z;
} D3DXVECTOR3;

メンバ

x
x コンポーネント。
y
y コンポーネント。
z
z コンポーネント。

注意

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXVECTOR3 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

D3DXVec3Length、D3DXVec3LengthSq、D3DXVec3Dot、D3DXVec3Cross、D3DXVec3Add、D3DXVec3Subtract、D3DXVec3Minimize、D3DXVec3Maximize、D3DXVec3Scale、D3DXVec3Lerp、D3DXVec3Normalize、D3DXVec3Hermite、D3DXVec3BaryCentric、D3DXVec3Transform、D3DXVec3TransformCoord、D3DXVec3TransformNormal

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。


D3DXVECTOR4

D3DXVECTOR4 構造体は、4 次元 (4D) 空間のベクトルを記述する。

typedef struct D3DXVECTOR4 {
  float x, y, z, w;
} D3DXVECTOR4;

メンバ

x
x コンポーネント。
y
y コンポーネント。
z
z コンポーネント。
w
w コンポーネント。

注意

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXVECTOR4 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxmath.h で宣言。

参照

D3DXVec4Length、D3DXVec4LengthSq、D3DXVec4Dot、D3DXVec4Add、D3DXVec4Subtract、D3DXVec4Minimize、D3DXVec4Maximize、D3DXVec4Scale、D3DXVec4Lerp、D3DXVec4Cross、D3DXVec4Normalize、D3DXVec4Hermite、D3DXVec4BaryCentric、D3DXVec4Transform


C++ 固有の機能

C++ プログラマは、Direct3DX ユーティリティ ライブラリにより提供されているコンストラクタのオーバーロード機能、演算子のオーバーロード機能、型変換の拡張機能を利用できる。次の構造体には、拡張機能が実装されている。

  • D3DXCOLOR 拡張機能
  • D3DXMATRIX 拡張機能
  • D3DXPLANE 拡張機能
  • D3DXQUATERNION 拡張機能
  • D3DXVECTOR2 拡張機能
  • D3DXVECTOR3 拡張機能
  • D3DXVECTOR4 拡張機能


D3DXCOLOR 拡張機能

D3DX_DEVICEDESC は、次の演算子オーバーロードと型変換を提供している。

#ifdef __cplusplus
public:
  D3DXCOLOR() {}
  D3DXCOLOR( DWORD argb );
  D3DXCOLOR( const float * );
  D3DXCOLOR( const D3DCOLORVALUE& );
  D3DXCOLOR( float r, float g, float b, float a );

  // 変換
  operator DWORD () const;

  operator float * ();
  operator const float * () const;

  operator D3DCOLORVALUE * ();
  operator const D3DCOLORVALUE * () const;

// 代入演算子
  D3DXCOLOR& operator += ( const D3DXCOLOR& );
  D3DXCOLOR& operator -= ( const D3DXCOLOR& );
  D3DXCOLOR& operator *= ( float );
  D3DXCOLOR& operator /= ( float );

// 単項演算子
  D3DXCOLOR operator + () const;
  D3DXCOLOR operator - () const;

// 2 項演算子
  D3DXCOLOR operator + ( const D3DXCOLOR& ) const;
  D3DXCOLOR operator - ( const D3DXCOLOR& ) const;
  D3DXCOLOR operator * ( float ) const;
  D3DXCOLOR operator / ( float ) const;

  friend D3DXCOLOR operator * (float, const D3DXCOLOR& );

  BOOL operator == ( const D3DXCOLOR& ) const;
  BOOL operator != ( const D3DXCOLOR& ) const;

#endif //__cplusplus


D3DXMATRIX 拡張機能

D3DXMATRIX 構造体は、次の演算子オーバーロードと型変換を提供している。

#ifdef __cplusplus
public:
  D3DXMATRIX() {};
  D3DXMATRIX( const float * );
  D3DXMATRIX( const D3DMATRIX& );
  D3DXMATRIX( float m00, float m01, float m02, float m03,
              float m10, float m11, float m12, float m13,
              float m20, float m21, float m22, float m23,
              float m30, float m31, float m32, float m33 );

  // アクセス許可
  float& operator () ( UINT iRow, UINT iCol );
  float  operator () ( UINT iRow, UINT iCol ) const;

  // 演算子の型変換
  operator float* ();
  operator const float* () const;

  operator D3DMATRIX* ();
  operator const D3DMATRIX* () const;

// 代入演算子
  D3DXMATRIX& operator *= ( const D3DXMATRIX& );
  D3DXMATRIX& operator += ( const D3DXMATRIX& );
  D3DXMATRIX& operator -= ( const D3DXMATRIX& );
  D3DXMATRIX& operator *= ( float );
  D3DXMATRIX& operator /= ( float );

// 単項演算子
  D3DXMATRIX operator + () const;
  D3DXMATRIX operator - () const;

// 2 項演算子
  D3DXMATRIX operator * ( const D3DXMATRIX& ) const;
  D3DXMATRIX operator + ( const D3DXMATRIX& ) const;
  D3DXMATRIX operator - ( const D3DXMATRIX& ) const;
  D3DXMATRIX operator * ( float ) const;
  D3DXMATRIX operator / ( float ) const;

  friend D3DXMATRIX operator * ( float, const D3DXMATRIX& );

  BOOL operator == ( const D3DXMATRIX& ) const;
  BOOL operator != ( const D3DXMATRIX& ) const;

#endif //__cplusplus

  union
  {
    float m[4][4];
#ifdef __cplusplus
    struct
    {
      float m00, m01, m02, m03;
      float m10, m11, m12, m13;
      float m20, m21, m22, m23;
      float m30, m31, m32, m33;
    };
#endif //__cplusplus


D3DXPLANE 拡張機能

D3DXPLANE 構造体は、次の演算子オーバーロードと型変換を提供している。

#ifdef __cplusplus
public:
  D3DXPLANE() {}
  D3DXPLANE( const float* );
  D3DXPLANE( float a, float b, float c, float d );

  // 変換
  operator float* ();
  operator const float* () const;

// 単項演算子
  D3DXPLANE operator + () const;
  D3DXPLANE operator - () const;

// 2 項演算子
  BOOL operator == ( const D3DXPLANE& ) const;
  BOOL operator != ( const D3DXPLANE& ) const;

#endif //__cplusplus


D3DXQUATERNION 拡張機能

D3DXQUATERNION 構造体は、次の演算子オーバーロードと型変換を提供している。

#ifdef __cplusplus
public:
  D3DXQUATERNION() {}
  D3DXQUATERNION( const float * );
  D3DXQUATERNION( float x, float y, float z, float w );

  // 変換
  operator float* ();
  operator const float* () const;

// 代入演算子
  D3DXQUATERNION& operator += ( const D3DXQUATERNION& );
  D3DXQUATERNION& operator -= ( const D3DXQUATERNION& );
  D3DXQUATERNION& operator *= ( const D3DXQUATERNION& );
  D3DXQUATERNION& operator *= ( float );
  D3DXQUATERNION& operator /= ( float );

// 単項演算子
  D3DXQUATERNION  operator + () const;
  D3DXQUATERNION  operator - () const;

// 2 項演算子
  D3DXQUATERNION operator + ( const D3DXQUATERNION& ) const;
  D3DXQUATERNION operator - ( const D3DXQUATERNION& ) const;
  D3DXQUATERNION operator * ( const D3DXQUATERNION& ) const;
  D3DXQUATERNION operator * ( float ) const;
  D3DXQUATERNION operator / ( float ) const;

  friend D3DXQUATERNION operator * (float, const D3DXQUATERNION& );

  BOOL operator == ( const D3DXQUATERNION& ) const;
  BOOL operator != ( const D3DXQUATERNION& ) const;

#endif //__cplusplus


D3DXVECTOR2 拡張機能

D3DXVECTOR2 構造体は、次の演算子オーバーロードと型変換を提供している。

#ifdef __cplusplus
public:
  D3DXVECTOR2() {};
  D3DXVECTOR2( const float * );
  D3DXVECTOR2( float x, float y );

  // 変換
  operator float* ();
  operator const float* () const;

// 代入演算子
  D3DXVECTOR2& operator += ( const D3DXVECTOR2& );
  D3DXVECTOR2& operator -= ( const D3DXVECTOR2& );
  D3DXVECTOR2& operator *= ( float );
  D3DXVECTOR2& operator /= ( float );

// 単項演算子
  D3DXVECTOR2 operator + () const;
  D3DXVECTOR2 operator - () const;

// 2 項演算子
  D3DXVECTOR2 operator + ( const D3DXVECTOR2& ) const;
  D3DXVECTOR2 operator - ( const D3DXVECTOR2& ) const;
  D3DXVECTOR2 operator * ( float ) const;
  D3DXVECTOR2 operator / ( float ) const;

  friend D3DXVECTOR2 operator * ( float, const D3DXVECTOR2& );

  BOOL operator == ( const D3DXVECTOR2& ) const;
  BOOL operator != ( const D3DXVECTOR2& ) const;

public:
#endif //__cplusplus


D3DXVECTOR3 拡張機能

D3DXVECTOR3 構造体は、次の演算子オーバーロードと型変換を提供している。

#ifdef __cplusplus
public:
  D3DXVECTOR3() {};
  D3DXVECTOR3( const float * );
  D3DXVECTOR3( const D3DVECTOR& );
  D3DXVECTOR3( float x, float y, float z );

  // 変換
  operator float* ();
  operator const float* () const;

  operator D3DVECTOR* ();
  operator const D3DVECTOR* () const;

// 代入演算子
  D3DXVECTOR3& operator += ( const D3DXVECTOR3& );
  D3DXVECTOR3& operator -= ( const D3DXVECTOR3& );
  D3DXVECTOR3& operator *= ( float );
  D3DXVECTOR3& operator /= ( float );

// 単項演算子
  D3DXVECTOR3 operator + () const;
  D3DXVECTOR3 operator - () const;

// 2 項演算子
  D3DXVECTOR3 operator + ( const D3DXVECTOR3& ) const;
  D3DXVECTOR3 operator - ( const D3DXVECTOR3& ) const;
  D3DXVECTOR3 operator * ( float ) const;
  D3DXVECTOR3 operator / ( float ) const;

  friend D3DXVECTOR3 operator * ( float, const struct D3DXVECTOR3& );

  BOOL operator == ( const D3DXVECTOR3& ) const;
  BOOL operator != ( const D3DXVECTOR3& ) const;

public:
#endif //__cplusplus


D3DXVECTOR4 拡張機能

D3DXVECTOR4 構造体は、次の演算子オーバーロードと型変換を提供している。

#ifdef __cplusplus
public:
  D3DXVECTOR4() {};
  D3DXVECTOR4( const float* );
  D3DXVECTOR4( float x, float y, float z, float w );

  // 変換
  operator float* ();
  operator const float* () const;

// 代入演算子
  D3DXVECTOR4& operator += ( const D3DXVECTOR4& );
  D3DXVECTOR4& operator -= ( const D3DXVECTOR4& );
  D3DXVECTOR4& operator *= ( float );
  D3DXVECTOR4& operator /= ( float );

// 単項演算子
  D3DXVECTOR4 operator + () const;
  D3DXVECTOR4 operator - () const;

// 2 項演算子
  D3DXVECTOR4 operator + ( const D3DXVECTOR4& ) const;
  D3DXVECTOR4 operator - ( const D3DXVECTOR4& ) const;
  D3DXVECTOR4 operator * ( float ) const;
  D3DXVECTOR4 operator / ( float ) const;

  friend D3DXVECTOR4 operator * ( float, const D3DXVECTOR4& );

  BOOL operator == ( const D3DXVECTOR4& ) const;
  BOOL operator != ( const D3DXVECTOR4& ) const;

public:
#endif //__cplusplus


列挙型

ここでは、Direct3DX ユーティリティ ライブラリで使用されている次の列挙型について記述する。

  • D3DX_FILTERTYPE
  • D3DX_SURFACECLASS
  • D3DX_SURFACEFORMAT


D3DX_FILTERTYPE

D3DX_FILTERTYPE 列挙型は、Direct3DX テクスチャ関数のフィルタリング タイプを定義する。

typedef enum _D3DX_FILTERTYPE {
  D3DX_FT_POINT    = 0x01,
  D3DX_FT_LINEAR   = 0x02,
  D3DX_FT_DEFAULT  = D3DX_DEFAULT
} D3DX_FILTERTYPE;
D3DX_FT_POINT
点サンプリングのみ。フィルタリングは行わない。
D3DX_FT_LINEAR
バイリニア フィルタリング。
D3DX_FT_DEFAULT
デフォルトのフィルタリング タイプ。

注意

D3DX_FILTERTYPE 列挙型のメンバは、ミップマップ生成時のさまざまなフィルタリング タイプである。

Direct3DX では、バイリニア (D3DX_FT_LINEAR) と点サンプリング (D3DX_FT_POINT) の 2種類のフィルタリングをサポートしている。サイズ変更やミップマップ生成でより高い品質を求めるなら、バイリニア フィルタリングを選択する。より速い処理速度を求めるなら、D3DX_FT_POINT を選択する。

メモ いくつかの特別なケースでは、内部にテキストがあるイメージでぼやけないようにするために、点サンプリングとミップマップ化の無効を行うとよい。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。

参照

D3DXLoadTextureFromMemory、D3DXLoadTextureFromSurface


D3DX_SURFACECLASS

D3DX_SURFACECLASS 列挙型は、既知のユーザーが情報を取得したサーフェス クラスを定義する。

typedef enum _D3DX_SURFACECLASS {
  D3DX_SC_DEPTHBUFFER       = 0x01,
  D3DX_SC_STENCILBUFFER     = 0x02,
  D3DX_SC_COLORTEXTURE      = 0x04,
  D3DX_SC_BUMPMAP           = 0x08,
  D3DX_SC_LUMINANCEMAP      = 0x10,
  D3DX_SC_COLORRENDERTGT    = 0x20
} D3DX_SURFACECLASS;
D3DX_SC_DEPTHBUFFER
DDPF_ZPIXELS フラグまたは DDPF_ZBUFFER フラグを設定するすべての ddpf。
D3DX_SC_STENCILBUFFER
DDPF_STENCILBUFFER フラグを設定するすべての ddpf。
D3DX_SC_COLORTEXTURE
内部に色情報を持っており、テクスチャ処理で使用可能なすべてのサーフェス。
D3DX_SC_BUMPMAP
DDPF_BUMPLUMINANCE フラグまたは DDPF_BUMPDUDV フラグを設定するすべての ddpf。
D3DX_SC_LUMINANCEMAP
DDPF_BUMPLUMINANCE フラグまたは DDPF_LUMINANCE フラグを設定するすべての ddpf。
D3DX_SC_COLORRENDERTGT
色情報を持っており、レンダリング ターゲットとして使用可能なすべてのサーフェス。

注意

デバイスによりさまざまなサーフェス クラスにサポートされているさまざまなサーフェス フォーマットを問い合わせることができる。

D3DX_SURFACECLASS 列挙型のメンバは、使用法に応じて分類された 2 次元 (2D) サーフェスのさまざまなタイプである。ただし、それらの数字は重複している。たとえば、D3DX_SC_STENCILBUFFER と D3DX_SC_DEPTHBUFFER は重複している (DirectX 7.0 の実装では、ステンシル ビットと深度ビットは同じピクセル フォーマットに属するため)。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。

参照

D3DXGetMaxSurfaceFormats、D3DXGetSurfaceFormat


D3DX_SURFACEFORMAT

D3DX_SURFACEFORMAT 列挙型は、列挙可能なさまざまなタイプのサーフェス フォーマットを定義している。次に、すべての Direct3DX サーフェス クラスを示す。

typedef enum _D3DX_SURFACEFORMAT {
  D3DX_SF_UNKNOWN    = 0,
  D3DX_SF_R8G8B8     = 1,
  D3DX_SF_A8R8G8B8   = 2,
  D3DX_SF_X8R8G8B8   = 3,
  D3DX_SF_R5G6B5     = 4,
  D3DX_SF_R5G5B5     = 5,
  D3DX_SF_PALETTE4   = 6,
  D3DX_SF_PALETTE8   = 7,
  D3DX_SF_A1R5G5B5   = 8,
  D3DX_SF_X4R4G4B4   = 9,
  D3DX_SF_A4R4G4B4   =10,
  D3DX_SF_L8         =11,
  D3DX_SF_A8L8       =12,
  D3DX_SF_U8V8       =13,
  D3DX_SF_U5V5L6     =14,
  D3DX_SF_U8V8L8     =15,
  D3DX_SF_UYVY       =16,
  D3DX_SF_YUY2       =17,
  D3DX_SF_DXT1       =18,
  D3DX_SF_DXT3       =19,
  D3DX_SF_DXT5       =20,
  D3DX_SF_R3G3B2     =21,
  D3DX_SF_A8         =22,
  D3DX_SF_TEXTUREMAX =23,

  D3DX_SF_Z16S0      =256,
  D3DX_SF_Z32S0      =257,
  D3DX_SF_Z15S1      =258,
  D3DX_SF_Z24S8      =259,
  D3DX_SF_S1Z15      =260,
  D3DX_SF_S8Z24      =261,
  D3DX_SF_DEPTHMAX   =262,

  D3DX_SF_FORCEMAX  = (DWORD)(-1)
} D3DX_SURFACEFORMAT;
D3DX_SF_UNKNOWN
サーフェス フォーマットは不明である。
D3DX_SF_R8G8B8
24 ビットの RGB ピクセル フォーマット。
D3DX_SF_A8R8G8B8
32 ビットのアルファのある ARGB ピクセル フォーマット。
D3DX_SF_X8R8G8B8
32 ビットの RGB ピクセル フォーマット。ただし、色ごとに 8 ビットが確保されている。
D3DX_SF_R5G6B5
16 ビットの RGB ピクセル フォーマット。
D3DX_SF_R5G5B5
16 ビットのピクセル フォーマット。ただし、色に 5 ビットが、透明度に 1 ビットが確保されている。
D3DX_SF_PALETTE4
サーフェスは、4 ビットのインデックス付きカラーである。
D3DX_SF_PALETTE8
サーフェスは、8 ビットのインデックス付きカラーである。
D3DX_SF_A1R5G5B5
16 ビットのピクセル フォーマット。ただし、色に 5 ビットが、アルファ (透明なテクセル) に 1 ビットが確保されている。
D3DX_SF_X4R4G4B4
16 ビットの RGB ピクセル フォーマット。ただし、色ごとに 4 ビットが確保されている。
D3DX_SF_A4R4G4B4
16 ビットの ARGB ピクセル フォーマット。
D3DX_SF_L8
8 ビットの輝度のみ。
D3DX_SF_A8L8
16 ビットのアルファ輝度。
D3DX_SF_U8V8
16 ビットのバンプマップ フォーマット。
D3DX_SF_U5V5L6
16 ビットの輝度のあるバンプマップ フォーマット。
D3DX_SF_U8V8L8
24 ビットの輝度のあるバンプマップ フォーマット。
D3DX_SF_UYVY
UYVY フォーマット (PC98準拠)。
D3DX_SF_YUY2
YUY2 フォーマット (PC98準拠)。
D3DX_SF_DXT1
S3 テクスチャの圧縮方法 1。
D3DX_SF_DXT3
S3 テクスチャの圧縮方法 3。
D3DX_SF_DXT5
S3 テクスチャの圧縮方法 5。
D3DX_SF_R3G3B2
8 ビットの RGB テクスチャ フォーマット。
D3DX_SF_A8
8 ビットのアルファのみ。
D3DX_SF_TEXTUREMAX
最後のテクスチャ フォーマット。
D3DX_SF_Z16S0
16 ビットの z バッファのビット深度。
D3DX_SF_Z32S0
32 ビットの z バッファのビット深度。
D3DX_SF_Z15S1
16 ビットの深度バッファ フォーマット。ステンシル バッファに 1 ビットが確保されている。
D3DX_SF_Z24S8
32 ビットの深度バッファ。ステンシル バッファに 8 ビットが確保されている。
D3DX_SF_S1Z15
16 ビットの深度バッファ。ステンシル バッファに 1 ビットが確保されている (LSB)。
D3DX_SF_S8Z24
32 ビットの深度バッファ。ステンシル バッファに 8 ビットが確保されている (LSB)。
D3DX_SF_DEPTHMAX
最大深度バッファのピクセル フォーマット。
D3DX_SF_FORCEMAX
最大値を強制適用。

注意

Direct3DX には DDPIXELFORMAT はないので注意すること。代わりに、D3DX_SURFACEFORMAT 列挙値がピクセル フォーマットを示す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
バージョン : DirectX 7.0 が必要。
ヘッダー : d3dxcore.h で宣言。

参照

D3DXGetMaxSurfaceFormats、D3DXGetSurfaceFormat


ハードウェア アクセラレート レベル定数

Direct3DX ハードウェア アクセラレート レベル定数は、事前に定義されたハードウェア アクセラレート レベルを表し、デバイス インデックス (DWORD) が必要な場所でデフォルト値として使用できる。以下に、Direct3DX ユーティリティ ライブラリにより提供されているすべてのハードウェア アクセラレート レベル定数を示す。

D3DX_DEFAULT
プライマリ DirectDraw デバイスで使用可能な最高のアクセラレート レベル。
D3DX_HWLEVEL_RASTER
ラスタライズ アクセラレート。ほとんどの場合、これが最も有用なレベルとなる。
D3DX_HWLEVEL_REFERENCE
リファレンス実装。これは、最低のアクセラレート レベルである。
D3DX_HWLEVEL_TL
変換とライティングのアクセラレート。
D3DX_HWLEVEL_2D
2D アクセラレートのみ。このレベルを指定すると、RGB ラスタライザが実装される。


戻り値

エラーは、32 ビットの値で表される。以下に、Direct3DX のメソッドや関数から返される値を示す。各メソッドや関数から返される値については、それぞれの説明を参照すること。

D3DXERR_BADD3DXCONTEXT
Direct3DX コンテキストが無効であるため、要求された処理が失敗した。
D3DXERR_BITBLTFAILED
BitBlt メソッドの呼び出しが失敗した。
D3DXERR_CANNOTRESIZEFULLSCREEN
フルスクリーン モードでサイズ変更は行われないため、要求された処理が失敗した。
D3DXERR_CANNOTRESIZENONWINDOWED
ウィンドウ化されていないコンテキストではサイズ変更は行われないため、要求された処理が失敗した。
D3DXERR_CAPSNOTSUPPORTED
要求されたデバイス能力がサポートされていない。
D3DXERR_COLORDEPTHTOOLOW
Direct3DX は 16 ビット以上の色深度しかサポートしていないため、要求された処理が失敗した。
D3DXERR_COULDNTUPDATECAPS
ディスプレイ モード変更後、能力データベースの更新が失敗した。
D3DXERR_D3DXNOTSTARTEDYET
Direct3DX が初期化されていなかったため、要求された処理が失敗した。D3DXInitialize 関数を呼び出して、もう一度試みることで、Direct3DX を初期化する。
D3DXERR_ENUMFORMATSFAILED
サーフェス フォーマットの列挙時にエラーが発生した。
D3DXERR_FAILEDDRAWTEXT
テキストは、サーフェスへのレンダリングに失敗した。
D3DXERR_FAILEDGETCAPS
デバイスの能力を取得できなかった。
D3DXERR_FAILEDQUATSLERP
2 つのクオータニオン間のスラープ (slerping) 処理が失敗した。
D3DXERR_FRONTBUFFERALREADYEXISTS
フロント バッファが既に存在していたため、要求された処理が失敗した。
D3DXERR_FULLSCREENPRIMARYEXISTS
アプリケーションがプライマリ サーフェスをフルスクリーン モードで使用しているため、要求された処理が失敗した。
D3DXERR_GETDCFAILED
デバイス情報を取得できなかった。
D3DXERR_IFLERROR
イメージ ファイルのロード ライブラリでエラーが発生した。
D3DXERR_INITFAILED
Direct3DX は、それ自体の初期化に失敗した。
D3DXERR_INVALIDD3DXDEVICEINDEX
渡されたデバイス インデックスが無効であったため、要求された処理が失敗した。
D3DXERR_INVALIDFILEFORMAT
ファイル フォーマットが無効である。
D3DXERR_INVALIDMODE
ディスプレイ モードが無効であるため、要求された処理が失敗した。
D3DXERR_INVALIDPARAMETER
パラメータのいずれか、またはいくつかが無効であるため、要求された処理が失敗した。
D3DXERR_MIPLEVELABSENT
このサーフェスにそのようなミップマップ レベルがないため、要求された処理が失敗した。
D3DXERR_NOBACKBUFFERAVAILABLE
バック バッファ サーフェスが作成されていないため、要求された処理が失敗した。
D3DXERR_NODIRECTDRAWAVAILABLE
要求された処理は、DirectDraw オブジェクトが作成されていないので失敗した。
D3DXERR_NODIRECT3DAVAILABLE
要求された処理は、Direct3D オブジェクトが作成されていないので失敗した。
D3DXERR_NODIRECT3DDEVICEAVAILABLE
要求された処理は、Direct3D デバイスが作成されていないので失敗した。
D3DXERR_NOMATCHFOUND
適切に一致するものが見つからなかった。
D3DXERR_NOMEMORY
システムでメモリ不足のため、要求された処理が失敗した。
D3DXERR_NOPRIMARYAVAILABLE
プライマリ サーフェスが作成されていないため、要求された処理が失敗した。
D3DXERR_NOTEXTURE
このテクスチャをバックアップするサーフェスがないため、要求された処理が失敗した。
D3DXERR_NOTINITIALIZED
Direct3DX が初期化されていないため、要求された処理が失敗した。
D3DXERR_NOZBUFFER
z バッファ サーフェスが作成されなかった。
D3DXERR_NOZBUFFERAVAILABLE
z バッファ サーフェスが作成されていないため、要求された処理が失敗した。
D3DXERR_NULLPOINTER
パラメータとして NULL ポインタが渡されたため、要求された処理が失敗した。
D3DXERR_STARTUPFAILED
Direct3DX は起動に失敗した。
D3DXERR_SURFACENOTPALETTED
サーフェスがパレット化されていないため、要求された処理が失敗した。
D3DXERR_UNSUPPORTEDFILEFORMAT
イメージ ファイル フォーマットが未確認のため、要求された処理が失敗した。


Direct3DX ユーティリティ ライブラリ サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。DirectX for Visual Basic には、Direct3DX ユーティリティ ライブラリに対するサポートは含まれていない。

[C++]

ここでは、DirectX SDK に含まれている以下のサンプル アプリケーションについて簡単に説明する。これらのサンプルは、主に Direct3DX ユーティリティ ライブラリの使い方を示すためのものである。

  • EnvMap サンプル
  • Gravity サンプル
  • Particle サンプル
  • Sprite サンプル
  • Tentacle サンプル
  • TrivFS サンプル
  • TrivWin サンプル

DirectX のサンプルには Microsoft® Visual C++® のプロジェクト ワークスペース ファイルが含まれているが、これらのサンプルを正しくコンパイルするには、開発環境のほかの設定を確認しなければならない場合がある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。

すべての Direct3DX サンプルは、C および C++ 開発者に配慮して記述されている。


EnvMap サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。DirectX for Visual Basic には、Direct3DX ユーティリティ ライブラリに対するサポートは含まれていない。

[C++]

説明

EnvMap サンプルは、キューブ環境マップを示している。

パス

ソース : (SDK ルート)\Samples\Multimedia\D3dx\Src\EnvMap

実行可能ファイル : (SDK ルート)\Samples\Multimedia\D3dx\Bin\EnvMap.exe

ユーザーズ ガイド

ユーザー入力は不要である。

プログラミング上の注意

このサンプルは、キューブ内に反射球体を描画することにより、反射エフェクトを作成する方法を示している。キューブ マップは、6 つの直交方向内でシーンをレンダリングすることによって作成される、特別なテクスチャのサーフェスである。伝統的な環境マップ エフェクトが使用されている。

このサンプルでは、Direct3DX ユーティリティ ライブラリのヘルパー クラスを使用している。


Gravity サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。DirectX for Visual Basic には、Direct3DX ユーティリティ ライブラリに対するサポートは含まれていない。

[C++]

説明

Gravity サンプルは、宇宙の中心に渦巻く粒子の群れを表示する。

パス

ソース : (SDK ルート)\Samples\Multimedia\D3dx\Src\Gravity

実行可能ファイル : (SDK ルート)\Samples\Multimedia\D3dx\Bin\Gravity.exe

ユーザーズ ガイド

ユーザー入力は不要である。

プログラミング上の注意

このサンプルは、3-D 環境を作成し、その中でオブジェクトのグループをアニメーション化する方法の基本を示している。ここでは、さまざまなライティング エフェクトを使用している。このサンプルはまた、形状作成用のメソッドと、Direct3DX の行列スタックの使い方を示している。

このサンプルでは、Direct3DX ユーティリティ ライブラリのヘルパー クラスを使用している。


Particle サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。DirectX for Visual Basic には、Direct3DX ユーティリティ ライブラリに対するサポートは含まれていない。

[C++]

説明

Particle サンプルは、ビルボード エフェクトの使い方を示している。

パス

ソース : (SDK ルート)\Samples\Multimedia\D3dx\Src\Particle

実行可能ファイル : (SDK ルート)\Samples\Multimedia\D3dx\Bin\Particle.exe

ユーザーズ ガイド

以下のキーを使用して、表示を制御する。NumLock を有効にしておく必要がある。

移動 | W、S
スライド | 方向キー
回転 | テンキーの 4、6
ピッチ | テンキーの 2、8
色の変更 | Space
地面の切り替え | G
反射の切り替え | R
場所の切り替え | Enter
一時停止 | Pause
終了 | Esc

プログラミング上の注意

表示される各粒子は、実際にはテクスチャ マップが適用されたビルボード面である。ライティング エフェクトと地面上の反射が実装されている。

このサンプルでは、Direct3DX ユーティリティ ライブラリのヘルパー クラスを使用している。


Sprite サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。DirectX for Visual Basic には、Direct3DX ユーティリティ ライブラリに対するサポートは含まれていない。

[C++]

説明

Sprite サンプルは、3-D エンジンを使用して古典的な 2-D スプライト操作を実行する方法を示している。

パス

ソース : (SDK ルート)\Samples\Multimedia\D3dx\Src\Sprite

実行可能ファイル: (SDK ルート)\Samples\Multimedia\D3dx\Bin\Sprite.exe

ユーザーズ ガイド

ユーザー入力は不要である。

プログラミング上の注意

このサンプルでは、Direct3DX ユーティリティ ライブラリのヘルパー クラスを使用している。


Tentacle サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。DirectX for Visual Basic には、Direct3DX ユーティリティ ライブラリに対するサポートは含まれていない。

[C++]

説明

Tentacle サンプルを使用すると、3-D 環境を対話型で操作することができる。

パス

ソース : (SDK ルート)\Samples\Multimedia\D3dx\Src\Tentacle

実行可能ファイル : (SDK ルート)\Samples\Multimedia\D3dx\Bin\Tentacle.exe

ユーザーズ ガイド

キーボードによる制御 (NumLock を有効にしておくこと)

移動 | W、S
スライド | 方向キー
回転 | テンキーの 4、6
ピッチ | テンキーの 2、8
ロール | テンキーの 7、9
ワイヤーフレームの切り替え | F2
終了 | Esc

マウスによる制御

左腕の回転 | 左ボタン
右腕の回転 | 右ボタン
土台の回転 | 左ボタン + 右ボタン
左腕のひねり | Shift + 左ボタン
右腕のひねり | Shift + 右ボタン
土台のひねり | Shift + 左ボタン + 右ボタン
左指の伸縮 | Ctrl + 左ボタン
右指の伸縮 | Ctrl + 右ボタン

プログラミング上の注意

このプログラムは、DirectX 7.0 の新しい機能である頂点ブレンディングおよびユーザー クリップ面を示している。また、反射エフェクトとレンズ フレアを表示する。

このサンプルでは、Direct3DX ユーティリティ ライブラリのヘルパー クラスを使用している。


TrivFS サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。DirectX for Visual Basic には、Direct3DX ユーティリティ ライブラリに対するサポートは含まれていない。

[C++]

説明

TrivFS サンプルは、三角形を y 軸上で回転する。

パス

ソース : (SDK ルート)\Samples\Multimedia\D3dx\Src\TrivFS

実行可能ファイル : (SDK ルート)\Samples\Multimedia\D3dx\Bin\TrivFS.exe

ユーザーズ ガイド

ユーザー入力は不要である。

プログラミング上の注意

このサンプルは、Direct3DX ユーティリティ ライブラリを使用して、フルスクリーンのアプリケーションを初期化する方法を示している。


TrivWin サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。DirectX for Visual Basic には、Direct3DX ユーティリティ ライブラリに対するサポートは含まれていない。

[C++]

説明

TrivWin サンプルは、三角形を y 軸上で回転する。

パス

ソース : (SDK ルート)\Samples\Multimedia\D3dx\Src\TrivWin

実行可能ファイル : (SDK ルート)\Samples\Multimedia\D3dx\Bin\TrivWin.exe

ユーザーズ ガイド

ユーザー入力は不要である。

プログラミング上の注意

このサンプルは、Direct3DX ユーティリティ ライブラリを使用して、ウィンドウ化されたアプリケーションを初期化する方法を示している。

このサンプルでは、Direct3DX ユーティリティ ライブラリのヘルパー クラスを使用している。


Direct3D 保持モードのドキュメント

Direct3D 保持モード バージョン 6.0 とそのドキュメントは、この SDK に含まれている。Direct3D 保持モードの今後のバージョン アップは予定されていない。

Direct3D 保持モードは DirectX Foundation の一部ではないが、C、C++、および Visual Basic で記述したアプリケーションで、Direct3D 保持モードの機能とサービスを使用することができる。Direct3D 保持モード API のドキュメントは、この SDK に含まれている。詳細については、「Direct3D 保持モードの紹介」を参照すること。

注 : Direct3D 保持モードのドキュメントには、C および C++ 開発者のための完全な概要とリファレンス、および Visual Basic 開発者のための新しいリファレンス マテリアルが含まれている。


DirectDraw

ここでは、DirectX® アプリケーション プログラミング インターフェイス (API) の DirectDraw® コンポーネントについて記述する。以下のトピックについて説明する。

  • DirectDraw について
  • DirectDraw を使用する理由
  • グラフィックスの基本概念の理解
  • DirectDraw アーキテクチャ
  • DirectDraw の要点
  • DirectDraw チュートリアル
  • DirectDraw リファレンス
  • DirectDraw のツールとサンプル


DirectDraw について

DirectDraw® は、DirectX® アプリケーション プログラミング インターフェイス (API) のコンポーネントであり、ディスプレイ メモリ、ハードウェア ブリット (ブロック転送)、ハードウェア オーバーレイのサポート、およびフリッピング サーフェスのサポートなどの直接操作を可能にする。DirectDraw は、既存の Microsoft® Windows® ベースのアプリケーションやデバイス ドライバとの互換性を維持しながら、これらの機能を提供する。

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

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

DirectDraw は、デバイスに依存したディスプレイ メモリへのアクセスを、デバイスに依存しない方法で提供する。DirectDraw がディスプレイ メモリを管理する。アプリケーションは、ハードウェア実装に関する標準的ないくつかの基本的デバイス従属性 (たとえば RGB、YUV のカラー フォーマット、ラスタ ライン間のピッチなど) を認識するだけでよい。ブリットを使用したり、パレット レジスタを操作するために、特別なプロシージャを呼び出す必要はない。DirectDraw を使うと、異なるタイプのディスプレイ ハードウェアが持つブリットや、カラー圧縮の復元能力をフルに引き出しながら、しかもハードウェアの特定の部分に依存することなく、ディスプレイ メモリを容易に操作することができる。

DirectDraw は、Windows 95 やそれ以降のバージョン、および Windows NT® 4.0や Windows 2000 が動作するコンピュータ上に、最上級のゲーム グラフィックスを提供する。


DirectDraw を使用する理由

DirectDraw コンポーネントは、Windows グラフィックス プログラマに多くの強力な機能を提供する。

  • DirectDraw のハードウェア アブストラクション レイヤ (HAL) は、ディスプレイ ハードウェアやビデオ メモリを直接動作させるために、一貫性のあるインターフェイスを提供する。これを用いて、システム ハードウェアから最大のパフォーマンスを得ることができる。
  • DirectDraw では、可能な限り、ビデオ ハードウェアの機能を使って、その能力を発揮させる。たとえば、ビデオ カードがハードウェア ブリットをサポートする場合、DirectDraw はビデオ カードにブリットを任せることで、大きくパフォーマンスを向上させる。さらに、DirectDraw ではハードウェア エミュレーション レイヤ (HEL) を提供して、ハードウェアに実装されていない機能をサポートする。
  • DirectDraw は Windows システムの提供する 32 ビット メモリ アドレス指定やフラット メモリ モデルの利点を受けられる。DirectDraw は、ビデオやシステムのメモリを小さなセグメントとしてではなく、ストレージの大きなブロックとして提示する。セグメント (オフセットのアドレス指定) を使ったことがあれば、この“フラット”メモリ モデルの理解は簡単である。
  • DirectDraw は、フルスクリーン アプリケーションでの複数バック バッファによるページ フリッピングの実現を容易にする。詳細については、「ページ フリッピングとバック バッファリング」を参照すること。
  • ウィンドウまたはフルスクリーン アプリケーションでのクリッピングのサポート。
  • 3D での Z バッファのサポート。
  • Z オーダリング付きのハードウェア支援オーバーレイのサポート。
  • イメージ伸縮ハードウェアへのアクセス。
  • 標準および改良型ディスプレイ デバイス メモリ領域への同時アクセス。
  • その他の機能として、カスタム、動的パレット、排他的ハードウェア アクセス、および解像度の切り替えなどがある。

これらの機能を組み合わせれば、標準的な Windows GDI ベースのアプリケーションや MS-DOS アプリケーションについて、簡単にその性能を向上させることが可能となる。


グラフィックスの基本概念の理解

ここでは、DirectDraw を使ったグラフィックス プログラミングの概要について説明する。ここで説明する個々の概念は、技術的ではない概要で始まり、DirectDraw がそれをどのようにサポートするかについて多少の具体的説明を加えながら説明する。

ここでの内容を理解するのに、グラフィックスの専門家である必要はない。グラフィックスの基本概念を理解しているのあれば、さらに詳しく説明している「DirectDraw の要点」に直接進んでもよい。C や C++、または Visual Basic の Windows プログラミングの知識があれば、ここでの内容はさほど理解が困難ではない。以下のトピックを読み終えれば、基本的な DirectDraw グラフィックス プログラミングの概念を十分に理解することができる。

次の項目について記述する。

  • デバイスに依存しないビットマップ
  • 描画サーフェス
  • ブリット
  • ページ フリッピングとバック バッファリング
  • 矩形について


デバイスに依存しないビットマップ

Windows そして DirectX は、ネイティブなグラフィックス ファイル フォーマットとして、デバイスに依存しないビットマップ (DIB) を使う。DIB とは、イメージのディメンジョン、それが使う色数、それらの色を記述する値、および個々のピクセルを記述するデータなどの情報を含むファイルである。なお DIB には、ファイル圧縮、有意カラー (すべての色が使用されない場合)、およびイメージの物理的ディメンジョン (印刷される場合) といった、あまり使われないパラメータもある。通常、DIB ファイルの拡張子は ".bmp" であるが、".dib" の場合もある。

[C++]

DIB は Windows プログラミングで広く普及しているため、プラットフォーム SDK には、DirectX で利用できる多くの関数が含まれている。次の例は、Win32® 関数と DirectX 関数を組み合わせて DirectX サーフェスに DIB をロードするアプリケーション定義の関数である。これは、プラットフォーム SDK の DirectX API 内の Ddutil.cpp ファイルに含まれている。

extern "C" IDirectDrawSurface * DDLoadBitmap(IDirectDraw *pdd,
    LPCSTR szBitmap, int dx, int dy)
{
    HBITMAP             hbm;
    BITMAP              bm;
    DDSURFACEDESC       ddsd;
    IDirectDrawSurface *pdds;

    //
    //  ここが Win32 部分。
    //  ビットマップをリソースとしてロードする。
    //  失敗すると、ファイルとしてロードする。
   //
    hbm = (HBITMAP)LoadImage(
            GetModuleHandle(NULL), szBitmap,
            IMAGE_BITMAP, dx, dy, LR_CREATEDIBSECTION);

    if (hbm == NULL)
        hbm = (HBITMAP)LoadImage(
                NULL, szBitmap, IMAGE_BITMAP, dx, dy,
                LR_LOADFROMFILE|LR_CREATEDIBSECTION);

    if (hbm == NULL)
        return NULL;

    //
    // ビットマップのサイズを取得する。
    //
    GetObject(hbm, sizeof(bm), &bm);

    //
    // ここで、DirectX 関数の呼び出しに戻る。
    // このビットマップの DirectDrawSurface を作成する。
    //
    ZeroMemory(&ddsd, sizeof(ddsd));
    ddsd.dwSize = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT |DDSD_WIDTH;
    ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
    ddsd.dwWidth = bm.bmWidth;
    ddsd.dwHeight = bm.bmHeight;

    if (pdd->CreateSurface(&ddsd, &pdds, NULL) != DD_OK)
        return NULL;

    DDCopyBitmap(pdds, hbm, 0, 0, 0, 0);

    DeleteObject(hbm);

    return pdds;
}

DIB ファイルの詳細については、プラットフォーム SDK を参照すること。

[C++,Visual Basic]


描画サーフェス

描画サーフェスは、スクリーン上にイメージ (正確にはビットマップ) として表示されるビデオ データを受け取る。多くの Windows プログラムは、GetDC (GetDC は、デバイス コンテキスト (DC) の取得を表す) などの Win32 関数を使って描画サーフェスにアクセスし、デバイス コンテキストを取得することで、スクリーン上に描画を行っている。しかし、Win32 グラフィックス関数は、グラフィックス デバイス インターフェイス (GDI) から提供されている。GDI は、標準の Windows アプリケーションがスクリーン上に描画するために使用するアブストラクション レイヤを提供するシステム コンポーネントである。

GDI のデメリットは、ワープロや表計算アプリケーションなどビジネス アプリケーションでの利用を目的として設計されている点であり、ハイパフォーマンス マルチメディア ソフトウェアとして設計されているのではないことにある。GDI では、ビデオ メモリではなくシステム メモリのビデオ バッファにアクセスし、ビデオ カードが持っている機能を利用することもない。つまり、GDI は、多くのビジネス アプリケーションではその威力を発揮するが、マルチメディア ソフトやゲーム ソフトにおいては、そのパフォーマンスが非常に低下する。

これに対して DirectDraw は、実際のビデオ メモリを表す描画サーフェスを提供している。このため、DirectDraw を使ってビデオ カード上のメモリに直接書き込むことができ、グラフィックス ルーチンを高速化できる。これらのサーフェスは連続したメモリのブロックとして表され、そこでのアドレス指定が容易になる。

詳細については、「サーフェス」を参照すること。


ブリット

blit は "bit block transfer" の略記であり、メモリのある場所から別の場所にデータのブロックを転送するプロセスである。グラフィックス プログラマはブリットを使用して、メモリ中のある場所から別の場所にグラフィックスを転送する。ブリットは、後で説明するスプライト アニメーションを実行するため利用されることもある。

DirectDraw のブリットの詳細については、「サーフェスへのブリット」を参照すること。


ページ フリッピングとバック バッファリング

ページ フリッピングは、マルチメディアやアニメーション、ゲームなどのソフトウェアで主要となる。ソフトウェア ページ フリッピングは、アニメーションを紙の束で行う方法に似ている。各ページごとに、アニメ作家は人物をわずかに変化させ、フレームを早くフリップさせるとその絵はアニメーションのように見える。

ソフトウェアでのページ フリッピングは、このプロセスとよく似ている。最初に、アニメ作家の紙を次のページにフリップするように、スクリーンに“フリップ”する一連の DirectDraw サーフェスをセット アップする。最初のサーフェスはプライマリ サーフェスと呼ばれ、それに続くサーフェスはバック バッファと呼ばれる。最初にアプリケーションはバック バッファに書き込み、次にバック バッファがスクリーン上に現れるようプライマリ サーフェスをフリップさせる。システムがイメージを表示している間、ソフトウェアは再びバック バッファに書き込む。このプロセスはアニメーションの間続き、すばやく効率的にイメージをアニメーションさせる。

DirectDraw は、比較的単純なダブルバッファ スキーム (1 つのバック バッファを持つプライマリ サーフェス) から、追加のバック バッファを付加したより高度なスキームまで、ページ フリッピング スキームのセット アップを容易にする。詳細については、「DirectDraw チュートリアル」および「フリッピング サーフェス」を参照すること。


矩形について

DirectDraw および Windows プログラミングから、スクリーン上のオブジェクトは境界矩形で参照される。境界矩形の端は常に画面の端と平行であるため、矩形は左上角と右下角の 2 点で記述される。大部分のアプリケーションでは、スクリーンへのブリットやヒット検出を行うために用いられる境界矩形の情報伝達に RECT 構造体が使用される。

[C++]

RECT 構造体の定義を以下に示す。

typedef struct tagRECT {
    LONG    left;    // これは、左上の角の x 座標。
    LONG    top;     // これは、左上の角の y 座標。
    LONG    right;   // これは、右下の角の x 座標。
    LONG    bottom;  // これは、右下の角の y 座標。
} RECT, *PRECT, NEAR *NPRECT, FAR *LPRECT;
[Visual Basic]

Visual Basic における RECT 型の定義を以下に示す。

Type RECT
    Left As Long     ' これは、左上の角の x 座標。
    Top As Long      ' これは、左上の角の y 座標。
    Right As Long    ' これは、右下の角の x 座標。
    Bottom As Long   ' これは、右下の角の y 座標。
End Type

上記の例で、left および top メンバは、境界矩形の左上角の x 座標と y 座標を表す。同様に、right および bottom メンバは、右下角の座標を構成する。次の図は、これらの値を視覚的に説明している。

効率、一貫性、使いやすさなどのために、すべての DirectDraw ブリット関数は矩形範囲を使用する。しかし、透過型ブリットを使用することにより、非矩形のブリットも行える。詳細については、「透過型ブリット」を参照すること。


DirectDraw アーキテクチャ

ここでは、DirectDraw コンポーネントとその他の DirectX コンポーネント間の関係、オペレーティング システム、およびシステム ハードウェアについて説明する。次の項目について記述する。

  • DirectDraw アーキテクチャの概要
  • DirectDraw オブジェクト タイプ
  • ハードウェア アブストラクション レイヤ (HAL)
  • ソフトウェア エミュレーション
  • システムの統合


DirectDraw アーキテクチャの概要

マルチメディア ソフトウェアは、ハイパフォーマンスなグラフィックスを要求する。Microsoft は、DirectDraw によりデバイスの独立性を保ちながら、GDI を使う場合よりもはるかにハイレベルの効率とスピードを持つグラフィックス重視の Windows アプリケーションを開発できるようにする。DirectDraw では、以下にあげるような主要タスクを実行するためのツールを提供する。

  • 複数のディスプレイ サーフェスの操作
  • ビデオ メモリへの直接アクセス
  • ページ フリッピング
  • バック バッファリング
  • パレットの管理
  • クリッピング

さらに、DirectDraw により実行時にディスプレイ ハードウェアの能力を照会することができるようになり、ホスト コンピュータのハードウェア能力における最適なパフォーマンスを提供する。

他の DirectX コンポーネントと同様、DirectDraw は可能なかぎりハードウェアを最大限利用しようとする。また、ハードウェア サポートを利用できない場合、大部分の機能のソフトウェア エミュレーションを提供する。デバイスの独立性は、ハードウェア アブストラクション レイヤ (HAL) を利用することにより可能となる。HAL の詳細については、「ハードウェア アブストラクション レイヤ (HAL)」を参照すること。

[C++]

DirectDraw コンポーネントは、COM ベースのインターフェイスからサービスを提供する。最新のインターフェイスは、IDirectDraw7、IDirectDrawSurface7、IDirectDrawPalette、IDirectDrawClipper、および IDirectDrawVideoPort である。これらのインターフェイスの他に、DirectDraw は従来のバージョンすべてをサポートしている。DirectDraw コンポーネントには、IDirectDraw3、IDirectDraw5、または IDirectDraw6 インターフェイスというバージョンはない (IDirectDraw2 から IDirectDraw4、および IDirectDraw4 から IDirectDraw7 にインターフェイス バージョンはスキップした)。

プラットフォーム SDK の DirectX API でアプリケーションを作成するために理解すべき COM 概念については、「コンポーネント オブジェクト モデル」を参照すること。

DirectDraw オブジェクトはディスプレイ アダプタを表し、IDirectDraw、IDirectDraw2、IDirectDraw4、および IDirectDraw7 インターフェイスからそのメソッドを公開する。大部分の場合、DirectDrawCreateEx 関数を使って最新の DirectDraw オブジェクトを作成するが、CoCreateInstance COM 関数を使って作成することもできる。詳細については、「CoCreateInstance を用いた DirectDraw オブジェクトの作成」を参照すること。

DirectDraw オブジェクトを作成した後、IDirectDraw7::CreateSurface メソッドを呼び出して、そのオブジェクトのサーフェスを作成することができる。サーフェスはディスプレイ ハードウェア上のメモリを表すが、ビデオ メモリとシステム メモリのいずれにも存在することができる。DirectDraw は、他のインターフェイスから、パレット、クリッピング (ウィンドウ アプリケーションでよく利用する)、およびビデオ ポートにおけるサポートを拡張する。

[Visual Basic]

DirectDraw コンポーネントは、DirectX for Visual Basic タイプ ライブラリのクラスからサービスを提供する。最新バージョンでは、このようなクラスとして、DirectDraw7、DirectDrawSurface7、DirectDrawPalette、DirectDrawClipper がある。

また、タイプ ライブラリによって、ドライバ、モードおよびサーフェスの列挙に使用されるオブジェクトも提供する。このようなオブジェクトとしては、DirectDrawEnum、DirectDrawEnumModes、および DirectDrawEnumSurfaces がある。

DirectDraw7 クラスから作成された DirectDraw オブジェクトは、ディスプレイ アダプタを表す。このオブジェクトを作成するには、グローバル DirectX7 オブジェクトの DirectDrawCreate メソッドを使用する。

DirectDraw オブジェクトを作成した後、DirectDraw7.CreateSurface メソッドを呼び出して、そのオブジェクトのサーフェスを作成することができる。サーフェスはディスプレイ ハードウェア上のメモリを表すが、ビデオ メモリとシステム メモリのいずれにも存在することができる。DirectDraw は、他のインターフェイスから、パレットおよびクリッピング (ウィンドウ アプリケーションでよく利用する) におけるサポートを拡張する。


DirectDraw オブジェクト タイプ

DirectDraw は、共に作用するいくつかのオブジェクトで構成されると考えられる。ここでは、オブジェクト タイプごとに、DirectDraw コンポーネントを用いる場合に使用するオブジェクトについて簡単に説明する。詳細については、「DirectDraw の要点」を参照すること。

[C++]

DirectDraw コンポーネントは、以下のオブジェクトを使用する。

DirectDraw オブジェクト
DirectDraw オブジェクトは、すべての DirectDraw アプリケーションの中核となるものである。作成する最初のオブジェクトであり、関連する他のすべてのオブジェクトを作成するために使用するからである。DirectDraw オブジェクトを作成するには、DirectDrawCreateEX 関数を呼び出す。DirectDraw オブジェクトは、IDirectDraw、IDirectDraw2、IDirectDraw4、および IDirectDraw7 インターフェイスからその機能を公開する。詳細については、「DirectDraw オブジェクト」を参照すること。
DirectDrawSurface オブジェクト
DirectDrawSurface オブジェクト (単に "サーフェス" とも呼ばれる) は、メモリ中のある領域を表す。その領域には、イメージとしてモニタ上に表示するか、または他のサーフェスに転送するデータが保持されている。サーフェスを作成するには、たいてい DirectDraw オブジェクトの IDirectDraw7::CreateSurface メソッドを呼び出す。作成したサーフェスは、そのオブジェクトと関連付けられる。DirectDrawSurface オブジェクトは、IDirectDrawSurface、IDirectDrawSurface2、IDirectDrawSurface3、IDirectDrawSurface4、および IDirectDrawSurface7 インターフェイスからその機能を公開する。詳細については、「サーフェス」を参照すること。
DirectDrawPalette オブジェクト
DirectDrawPalette オブジェクト (単に“パレット”とも呼ばれる) は、サーフェスと共に使う 16 ないし 256 カラー インデックス付きパレットを表す。このオブジェクトには、サーフェス内の値と関連付けられたカラーを記述する一連のインデックス RGB トリプレットが含まれている。8 ビット以上のピクセル フォーマット深度を使うサーフェスと共にパレットを使用することはできない。DirectDrawPalette オブジェクトを作成するには、IDirectDraw7::CreatePalette メソッドを呼び出す。DirectDrawPalette オブジェクトは、IDirectDrawPalette インターフェイスからその機能を公開する。詳細については、「パレット」を参照すること。
DirectDrawClipper オブジェクト
DirectDrawClipper オブジェクト (単に “クリッパー” とも呼ばれる) は、サーフェスのある部分やサーフェスの境界を越えてブリットが行われるのを阻止する。クリッパーを作成するには、IDirectDraw7::CreateClipper メソッドを呼び出す。DirectDrawClipper オブジェクトは、IDirectDrawClipper インターフェイスからその機能を公開する。詳細については、「クリッパー」を参照すること。
DirectDrawVideoPort オブジェクト
DirectDrawVideoPort オブジェクトは、いくつかのシステムに存在するビデオ ポートハードウェアを表す。このハードウェアにより、CPU にアクセスしたり、PCI バスを使用せずにフレーム バッファに直接アクセスすることができる。DirectDrawVideoPort オブジェクトを作成するには、IID_IDDVideoPortContainer 参照識別子を指定して DirectDraw オブジェクトの QueryInterface メソッドを呼び出す。DirectDrawVideoPort オブジェクトは、IDDVideoPortContainer および IDirectDrawVideoPort インターフェイスからその機能を公開する。詳細については、「ビデオ ポート」を参照すること。
[Visual Basic]

DirectDraw コンポーネントは、以下のオブジェクトを使用する。

DirectDraw オブジェクト
DirectDraw オブジェクトは、すべての DirectDraw アプリケーションの中核となるものである。作成する最初のオブジェクトであり、関連する他のすべてのオブジェクトを作成するために使用するからである。DirectDraw オブジェクトを作成するには、DirectX7.DirectDrawCreate メソッドを呼び出す。DirectDraw は、DirectDraw7 オブジェクトのメソッドからその機能を公開する。詳細については、「DirectDraw オブジェクト」を参照すること。
DirectDrawSurface オブジェクト
DirectDrawSurface オブジェクト (単に "サーフェス" とも呼ばれる) は、メモリ中のある領域を表す。その領域には、イメージとしてモニタ上に表示するか、または他のサーフェスに転送するデータが保持されている。サーフェスを作成するには、たいてい DirectDraw オブジェクトの DirectDraw7.CreateSurface メソッドを呼び出す。作成したサーフェスは、そのオブジェクトと関連付けられる。DirectDrawSurface オブジェクトは、DirectDrawSurface7 オブジェクトのメソッドからその機能を公開する。詳細については、「サーフェス」を参照すること。
DirectDrawPalette オブジェクト
DirectDrawPalette オブジェクト (単に“パレット”とも呼ばれる) は、サーフェスと共に使う 16 ないし 256 カラー インデックス付きパレットを表す。このオブジェクトには、サーフェス内の値と関連付けられたカラーを記述する一連のインデックス RGB トリプレットが含まれている。8 ビット以上のピクセル フォーマット深度を使うサーフェスと共にパレットを使用することはできない。DirectDrawPalette オブジェクトを作成するには、DirectDraw7.CreatePalette メソッドを呼び出す。DirectDrawPalette オブジェクトは、DirectDrawPalette インターフェイスからその機能を公開する。詳細については、「パレット」を参照すること。
DirectDrawClipper オブジェクト
DirectDrawClipper オブジェクト (単に“クリッパー”とも呼ばれる) は、サーフェスのある部分やサーフェスの境界を越えてブリットが行われるのを阻止する。クリッパーを作成するには、DirectDraw7.CreateClipper メソッドを呼び出す。DirectDrawClipper オブジェクトは、DirectDrawClipper インターフェイスからその機能を公開する。詳細については、「クリッパー」を参照すること。


ハードウェア アブストラクション レイヤ (HAL)

DirectDraw は、ハードウェア アブストラクション レイヤ (HAL) からデバイスの独立性を提供する。HAL は、デバイス メーカーから提供されるデバイス固有のインターフェイスで、DirectDraw はそれを使ってディスプレイ ハードウェアを直接動作させる。アプリケーションは、HAL とは決して相互作用しない。むしろ HAL の提供するインフラを使って、DirectDraw はアプリケーションがグラフィックスを表示するために使うインターフェイスやメソッドの一貫したセットを示す。デバイス メーカーは、Windows のもとでは 16 ビット コード、32 ビット コードの組み合わせで HAL を実装する。Windows NT/Windows 2000 のもとでは、HAL は常に 32 ビット コードで実装される。HAL は、ディスプレイ ドライバの一部であったり、ドライバ作成者の定義するプライベート インターフェイスからディスプレイ ドライバと通信する個別 DLL となることもできる。

DirectDraw HAL は、チップ メーカー、ボード製作者、または OEM 業者により実装される。HAL は、デバイス依存のコードを実装するだけで、エミュレーションは行わない。ある機能がハードウェアにより実行されないとしても、HAL はそれをハードウェア能力とみなして報告しない。さらに、HAL はパラメータを確認しないので、HAL が起動される前に DirectDraw がこのパラメータを確認する。


ソフトウェア エミュレーション

ハードウェアがハードウェア アブストラクション レイヤ (HAL) を通してある機能をサポートしない場合、DirectDraw はそれをエミュレートしようとする。このエミュレートされた機能は、ハードウェア エミュレーション レイヤ (HEL) から提供される。HAL と同様に、HEL はその能力を DirectDraw に提供する。また HAL 同様、アプリケーションは決して直接 HEL に作用しない。その結果、ある機能がハードウェアによるか、または HEL からサポートされるかどうかに関わりなく、ほとんどすべての主要機能が透過型サポートとなる。

ソフトウェア エミュレーションは、明らかにハードウェア機能が提供するパフォーマンスには及ばない。C++ の IDirectDraw7::GetCaps メソッド または Visual Basic の DirectDraw7.GetCaps メソッドを使って、ハードウェアのサポートする機能を照会することができる。アプリケーションの初期設定時にこれらの能力を調べると、アプリケーション パラメータを調整することができ、ハードウェア パフォーマンスのさまざまなレベルに最適なパフォーマンスを提供できる。

ハードウェアによりサポートされた機能とエミュレーションの組み合わせによっては、エミュレーションだけの場合よりパフォーマンスが落ちる場合がある。たとえば、ディスプレイ デバイス ドライバが DirectDraw をサポートし、伸縮ブリットをサポートしない場合、ビデオ メモリ サーフェスから伸縮ブリットを行うと、著しいパフォーマンスの低下がみられる。このパフォーマンスの低下が生じるのは、ビデオ メモリの方がシステム メモリよりも遅い場合が多く、ビデオ メモリ サーフェスにアクセスするときに CPU が待たされるからである。アプリケーションがハードウェアでサポートしない機能を使うときは、システム メモリにサーフェスを作成した方がいい場合がある。これにより、CPU がビデオ メモリにアクセスするときに生じるパフォーマンスの低下を避けることができる。

詳細については、「ハードウェア アブストラクション レイヤ (HAL)」を参照すること。


システムの統合

以下に示す図は、グラフィックス デバイス インターフェイス (GDI)、ハードウェア アブストラクション レイヤ (HAL)、ハードウェア エミュレーション レイヤ (HEL)、およびハードウェアと DirectDraw との関係である。

このように、DirectDraw オブジェクトは GDI と共に存在する。どちらも、デバイス依存のアブストラクション レイヤからハードウェアに直接アクセスすることができる。GDI とは異なり、DirectDraw はできるかぎり、常に特別なハードウェア機能を利用しようとする。ハードウェアが、ある機能をサポートしない場合、DirectDraw は HEL を使ってその機能をエミュレートしようとする。DirectDraw は、デバイス コンテキストの形でサーフェス メモリを提供できるので、サーフェス オブジェクトと共に作用するための GDI 関数を使用できる。


DirectDraw の要点

ここでは、DirectX® の DirectDraw® コンポーネントの一般的な説明が提供されている。以下の項目について記述する。

  • 協調レベル
  • ディスプレイ モード
  • DirectDraw オブジェクト
  • サーフェス
  • パレット
  • クリッパー
  • マルチモニタ システム
  • DirectDraw の高度なトピック


協調レベル

ここでは、協調レベルの概要と一般的な使用状況について説明する。以下の項目について記述する。

  • 協調レベルについて
  • 協調レベルのテスト


協調レベルについて

協調レベルは、DirectDraw がどのようにディスプレイと相互作用し、ディスプレイに影響を与えるイベントに対してどのように反応するかを記述する。DirectDraw の協調レベルを設定するには、C++ の IDirectDraw7::SetCooperativeLevel メソッドまたは Visual Basic の DirectDraw7.SetCooperativeLevel メソッドを使用する。大部分のアプリケーションでは DirectDraw の協調レベルを使用して、ディスプレイへ排他アクセスを行うフルスクリーン プログラムとして実行するか、またはウィンドウ アプリケーションとして実行するかを決める。ただし、DirectDraw の協調レベルには、次のようなエフェクトもある。

  • DirectDraw がモード X 解像度を利用できるようにする。詳細については、「モード X モードとモード 13 ディスプレイ モード」を参照すること。
  • ユーザーが、CTRL + ALT + DEL (排他モードだけ) を押した場合、DirectDraw がディスプレイの排他コントロールを解放したり、リブートしたりするのを阻止する。
  • 起動イベントに応じて、DirectDraw がアプリケーションを最小化または最大化できるようにする。

標準協調レベルは、DirectDraw アプリケーションがウィンドウ アプリケーションとして動作することを示す。この協調レベルでは、プライマリ サーフェスのパレットを変更したり、ページ フリッピングを実行することはできない。

アプリケーションは、複数のウィンドウで DirectDraw を使用することができるので、アプリケーションが DDSCL_NORMAL モードを要求している場合、IDirectDraw7::SetCooperativeLevel および DirectDraw7.SetCooperativeLevel にはウィンドウ ハンドルを指定する必要はない。C++ では ウィンドウ ハンドルに NULL を、Visual Basic では Nothing を渡すことで、通常の Windows モードですべてのウィンドウを同時に使用することができる。

フルスクリーンかつ排他協調レベルでは、ハードウェアを最大限利用できる。このモードでは、カスタム パレットや動的パレットの設定、ディスプレイ解像度の変更、およびページ フリッピングの実現ができる。排他 (フルスクリーン) モードでは、他のアプリケーションがサーフェスを割り当てることを防ぐ必要がなく、DirectDraw や GDI を使用することも排除しなくていい。ただし、排他モードでは、排他アクセスを持つ現在のアプリケーション以外のアプリケーションがディスプレイ モードやパレットを変更することを防ぐ。

DirectDraw は、必要な SetCooperativeLevel メソッドから登録されたウィンドウ ハンドルに WM_ACTIVATEAPP メッセージを送りながら、フルスクリーン (排他モードのアプリケーション) に対するウィンドウ起動イベントのコントロールを取得する。DirectDraw は、起動イベントを最上位ウィンドウだけに送る。アプリケーションが起動イベント メッセージを要求する子ウィンドウを作成する場合、作成者の責任で子ウィンドウをサブクラス化する。

SetCooperativeLevel は、プロセスとウィンドウ ハンドル間の結合を保持する。プロセスで SetCooperativeLevel を呼び出すと、そのプロセスとウィンドウ間に結合ができる。同じプロセス内で異なるゼロ以外のウィンドウ ハンドルを与えて再び呼び出すと、DDERR_HWNDALREADYSET エラー値が返される。アプリケーションによっては、DirectSound® が DirectDraw と異なるウィンドウ ハンドルを指定したときにこのエラーを受け取ることがある。どちらも、同一の最上位アプリケーションのウィンドウ ハンドルを指定しなければならない。

[C++]

注 : Microsoft Foundation Classes (MFC) を使用している開発者は、SetCooperativeLevel メソッドに与えられるウィンドウ ハンドルが、そのアプリケーションの最上位ウィンドウ (子ウィンドウから派生したウィンドウではない) を識別しなくてはならないことに注意する。MFC アプリケーションの最上位ウィンドウ ハンドルを取得するには、以下のコードを使用できる。

    HWND hwndTop = AfxGetMainWnd()->GetSafeHwnd();

「マルチモニタ システム」も参照すること。

[C++,Visual Basic]


協調レベルのテスト

開発者は、アプリケーションで使用するサーフェスをリストアしたり再作成すべきことを通知するために、WM_ACTIVATEAPP や WM_DISPLAYCHANGE などのメッセージを使用することがある。このような場合、アプリケーションでは不必要なときにアクションを取得し、必要なときにはアクションを取得しない。C++ のIDirectDraw7::TestCooperativeLevel メソッドまたは Visual Basic のDirectDraw7.TestCooperativeLevel メソッドにより、アプリケーションは DirectDraw オブジェクトの協調レベルにおける詳細情報を取得でき、何事もなく実行を続けられる適切なステップを取得できる。

アプリケーションがサーフェスをリストアでき (既にリストアが行われていない場合)、実行を続けられると、TestCooperativeLevel メソッドは DD_OK を返して成功する。また、失敗のコードは、アプリケーションで使用する協調レベルとは異なって判断される。

フルスクリーン アプリケーション

排他的なデバイス アクセスを失う場合 (たとえば、ユーザーが ALT + TAB を押して現在のアプリケーションを切り替える場合)、フルスクリーン アプリケーションは DDERR_NOEXCLUSIVEMODE 戻り値を受け取る。この場合、アプリケーションは、メソッドが DD_OK (排他モードが返されたことを意味する) を返すときだけ終了するループ内の TestCooperativeLevel を呼び出す。アプリケーションでは、ループ内の不必要なサイクルを阻止するために CPU を制御しない。このため、Windows では、WaitMessage や Sleep Win32 関数といった関数をサポートする。

あらゆる既存のサーフェスは、IDirectDrawSurface7::Restore、C++ の IDirectDraw7::RestoreAllSurfaces メソッドまたは Visual Basic の DirectDrawSurface7.Restore メソッドを呼び出すことでリストアされ、サーフェスが表示される前にコンテンツが再ロードされなくてはならない。

ウィンドウ アプリケーション

ウィンドウ アプリケーション以外のアプリケーションで排他的なデバイス アクセスを取得している場合、ウィンドウ アプリケーション (標準協調レベルを使用している) は、DDERR_EXCLUSIVEMODEALREADYSET を受け取る。この場合、排他アクセスのあるアプリケーションがそのアクセスを失うまで、アクションは取得されない。この状況は、フルスクリーン アプリケーションの場合と類似する。ウィンドウ アプリケーションは、TestCooperativeLevel がサーフェスのリストアや再ロードの前に DD_OK を返すまで、ループする。前述したように、このアプリケーションのようなループでは、ループ中に CPU の制御を周期的に行わず、不必要な CPU サイクルの使用を避けるべきである。

ディスプレイ モードが変更されると、TestCooperativeLevel メソッドは DDERR_WRONGMODE をウィンドウ アプリケーションに返す。この場合、このアプリケーションでは、実行を続ける前にあらゆるサーフェスを破棄して再作成しなくてはならない。


ディスプレイ モード

ここでは、DirectDraw ディスプレイ モードの一般的な説明をする。次の項目について記述する。

  • ディスプレイ モードについて
  • サポートされるディスプレイの決定
  • ディスプレイ モードの設定
  • ディスプレイ モードのリストア
  • モード X モードとモード 13 ディスプレイ モード
  • 高解像度とトゥルーカラー ビット深度のサポート


ディスプレイ モードについて

ディスプレイ モードとは、ディスプレイ ハードウェアがプライマリ サーフェスからモニタに送る、グラフィックスのディメンジョンやビット深度を記述するハードウェア設定のことである。ディスプレイ モードは、それを定義する特性、すなわち幅、高さ、およびビット深度で記述される。たとえば、大部分のディスプレイ アダプタは、幅が 640 ピクセルで高さが 480 ピクセルのグラフィックスを表示できる。ここで、各ピクセルは 8 ビットのデータである。このディスプレイ モードは、640 × 480 × 8 と略記することができる。ディスプレイ モードのディメンジョンが大きくなるか、ビット深度が増加すると、さらにディスプレイ メモリが必要となる。

ディスプレイ モードには、パレット化と非パレット化の 2 つのタイプがある。パレット化ディスプレイ モードでは、個々のピクセルが関連付けられたパレットへのインデックスを表す値になる。ディスプレイ モードのビット深度は、パレットに入れる色数を決める。たとえば、8 ビットのパレット化ディスプレイ モードでは、各ピクセルが 0 から 255 の値になる。このようなモードでは、パレットには 256 のエントリを含めることができる。

非パレット化ディスプレイ モードは、名前からわかるようにパレットを使用しない。非パレット化ディスプレイ モードのビット深度は、ピクセルを記述するために使用される全ビット数を示す。

プライマリ サーフェスおよびプライマリ フリッピング チェーンの任意のサーフェスは、ディスプレイ モードのディメンジョン、ビット深度、およびピクセル フォーマットに適合する。詳細については、「ピクセル フォーマット」を参照すること。


サポートされるディスプレイの決定

[C++]

ディスプレイ ハードウェアには数多くの種類があるため、すべてのデバイスがすべてのディスプレイ モードをサポートすることはない。与えられたシステムでサポートされるディスプレイ モードを決めるには、IDirectDraw7::EnumDisplayModes メソッドを呼び出す。該当する値やフラグを設定すると、EnumDisplayModes メソッドはサポートされるすべてのディスプレイ モードを列挙するか、指定した個々のディスプレイ モードがサポートされていることを確認する。このメソッドの最初のパラメータ dwFlags は、メソッドに対する追加オプションを管理する。たいていの場合、dwFlags を 0 に設定して追加オプションを無視する。2 番目のパラメータ lpDDSurfaceDesc は、確認すべき与えられたディスプレイ モードを記述する DDSURFACEDESC2 構造体のアドレスである。通常、このパラメータを NULL に設定して、すべてのモードの列挙を要求する。3 番目のパラメータ lpContext は、DirectDraw がコールバック関数に渡すポインタである。コールバック関数に追加データが必要でない場合は、このパラメータを NULL に設定する。最後に、lpEnumModesCallback パラメータを、サポートされたモードごとに DirectDraw が呼び出すコールバック関数のアドレスに設定する。

EnumDisplayModes を呼び出すときに与えるコールバック関数は、EnumModesCallback 関数のプロトタイプと適合しなければならない。ハードウェアがサポートする各ディスプレイ モードで、DirectDraw は 2 つのパラメータを渡してコールバック関数を呼び出す。最初のパラメータは、サポートされる 1 つのディスプレイ モードを記述する DDSURFACEDESC2 構造体のアドレスである。2 番目のパラメータは、もしあれば、EnumDisplayModes を呼び出すときに指定したアプリケーション定義のデータのアドレスとする。

DDSURFACEDESC2 構造体の値を調べて、それが記述するディスプレイ モードを決める。主要な構造体のメンバは、dwWidth、dwHeight、および ddpfPixelFormat メンバである。dwWidth と dwHeight メンバは、ディスプレイ モードのディメンジョンを記述する。ddpfPixelFormat メンバは、モードのビット深度に関する情報を含む DDPIXELFORMAT 構造体である。

DDPIXELFORMAT 構造体は、モードのビット深度を記述する情報を伝達し、ディスプレイ モードがパレットを使用しているかどうかを伝える。dwFlags メンバに DDPF_PALETTEINDEXED1、DDPF_PALETTEINDEXED2、DDPF_PALETTEINDEXED4、または DDPF_PALETTEINDEXED8 フラグがあると、ディスプレイ モードのビット深度は 1、2、4、または 8 ビットとなり、各ピクセルは関連付けられたパレットへのインデックスとなる。dwFlags が DDPF_RGB ならば、ディスプレイ モードは非パレット化となり、そのビット深度は DDPIXELFORMAT 構造体の dwRGBBitCount メンバに与えられる。

[Visual Basic]

ディスプレイ ハードウェアには数多くの種類があるため、すべてのデバイスがすべてのディスプレイ モードをサポートすることはない。与えられたシステムでサポートされるディスプレイ モードを決めるには、DirectDraw7.GetDisplayModesEnum メソッドを呼び出す。このメソッドは、サポートされるディスプレイ モードの列挙を取得するのに使用される DirectDrawEnumModes オブジェクトを返す。該当する値やフラグを設定すると、GetDisplayModesEnum メソッドは、DirectDrawEnumModes オブジェクトにサポートされるすべてのディスプレイ モードのリストを埋め込むか、または指定した個々のディスプレイ モードがサポートされていることを確認する。このメソッドの最初のパラメータ flags は、メソッドに対する追加オプションを管理する。たいていの場合、flags を DDEDM_DEFAULT に設定して追加オプションを無視する。2 番目のパラメータ ddsd は、確認すべき与えられたディスプレイ モードを記述する DDSURFACEDESC2 型のアドレスである。通常、このパラメータを Nothing に設定して、すべてのモードの列挙を要求する。

GetDisplayModesEnum メソッドによって DirectDrawEnumModes オブジェクトが返されると、DirectDrawEnumModes.GetCount メソッドを呼び出して、サポートされるディスプレイ モードで使用可能なモードの数を確認できる。次に、DirectDrawEnumModes.GetItem を呼び出して、DirectDrawEnumModes オブジェクトに含まれるディスプレイ モードのリストから個々のディスプレイ モードの説明を取得する。

GetItem メソッドによって取得された DDSURFACEDESC2 型の値を調べて、それが記述するディスプレイ モードを決める。主要なタイプのメンバは、lWidth、lHeight、および ddpfPixelFormat メンバである。lWidth と lHeight メンバは、ディスプレイ モードのディメンジョンを記述する。ddpfPixelFormat メンバは、モードのビット深度に関する情報を含む DDPIXELFORMAT 型である。

DDPIXELFORMAT 型は、モードのビット深度を記述する情報を伝達し、ディスプレイ モードがパレットを使用しているかどうかを伝える。lFlags メンバに DDPF_PALETTEINDEXED1、DDPF_PALETTEINDEXED2、DDPF_PALETTEINDEXED4、または DDPF_PALETTEINDEXED8 フラグがあると、ディスプレイ モードのビット深度は 1、2、4、または 8 ビットとなり、各ピクセルは関連付けられたパレットへのインデックスとなる。lFlags が DDPF_RGB ならば、ディスプレイ モードは非パレット化となり、そのビット深度は DDPIXELFORMAT 型の lRGBBitCount メンバに与えられる。


ディスプレイ モードの設定

ディスプレイ モードを設定するには、C++ の IDirectDraw7::SetDisplayMode メソッドまたは Visual Basic の DirectDraw7.SetDisplayMode メソッドを使用する。SetDisplayMode メソッドは、設定するモードのディメンジョン、ビット深度、およびリフレッシュ レートを記述する 4 つのパラメータを受け取る。このメソッドでは、5 番目のパラメータを用いて、与えられたモードに対する特別なオプションを示す。現在、オプションはモード 13 とモード X 320 × 200 × 8 ディスプレイ モードを区別するためだけに使用されている。

[C++]

望ましいディスプレイ モードのビット深度を指定できるが、そのビット深度に対して使用するディスプレイ ハードウェアのピクセル フォーマットを指定することはできない。現在のビット深度に対して使用するディスプレイ ハードウェアの RGB ビットマスクを決めるには、ディスプレイ モードを設定してから IDirectDraw7::GetDisplayMode を呼び出す。現在のディスプレイ モードがパレット化でなければ、正確な赤、緑、および青のビットを決めるために、DDPIXELFORMAT の dwRBitMask、dwGBitMask、および dwBBitMask メンバのマスク値を調べることができる。詳細については、「ピクセル フォーマット マスク」を参照すること。

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

DirectDraw の排他 (フルスクリーン) モードでは、他のアプリケーションが DirectDrawSurface オブジェクトを割り当てられたり、DirectDraw や GDI 機能も利用可能となる。ただし、排他モード以外のアプリケーションがディスプレイ モードやパレットを変更することはできない。

注 : アプリケーション ウィンドウを作成したスレッドからは、IDirectDraw7::SetDisplayMod メソッドだけを呼び出せる。単一のスレッド化されたアプリケーション (大部分はそうである) に対しては、この制限は問題にならない。

[Visual Basic]

望ましいディスプレイ モードのビット深度を指定できるが、そのビット深度に対して使用するディスプレイ ハードウェアのピクセル フォーマットを指定することはできない。現在のビット深度に対して使用するディスプレイ ハードウェアの RGB ビットマスクを決めるには、ディスプレイ モードを設定してから DirectDraw7.GetDisplayMode を呼び出す。現在のディスプレイ モードがパレット化でなければ、正確な赤、緑、および青のビットを決めるために、DDPIXELFORMAT の ｌRBitMask、ｌGBitMask、および ｌBBitMask メンバのマスク値を調べることができる。詳細については、「ピクセル フォーマット マスク」を参照すること。

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

DirectDraw の排他 (フルスクリーン) モードでは、他のアプリケーションが DirectDrawSurface オブジェクトを割り当てられたり、DirectDraw や GDI 機能も利用可能となる。ただし、排他モード以外のアプリケーションがディスプレイ モードやパレットを変更することはできない。


ディスプレイ モードのリストア

[C++]

IDirectDraw7::RestoreDisplayMode メソッドを呼び出して、ディスプレイ ハードウェアを元のモードに明示的にリストアすることができる。ディスプレイ モードが IDirectDraw7::SetDisplayMode を呼び出すことで設定され、またアプリケーションが排他協調レベルであるとき、元のディスプレイ モードはアプリケーションの協調レベルが通常に戻されるときに自動的にリセットされる (この機能は最初に IDirectDraw2 インターフェイスに提供され、そのインターフェイスの新バージョンすべてに提供される)。

IDirectDraw インターフェイスを使用しているときは、RestoreDisplayMode メソッドを使って常にディスプレイ モードを明示的にリストアしなくてはならない。

[Visual Basic]

DirectDraw7.RestoreDisplayMode メソッドを呼び出して、ディスプレイ ハードウェアを元のモードに明示的にリストアすることができる。ディスプレイ モードが DirectDraw7.SetDisplayMode を呼び出すことで設定され、またアプリケーションが排他協調レベルであるとき、元のディスプレイ モードはアプリケーションの協調レベルが通常に戻されるときに自動的にリセットされる。


モード X モードとモード 13 ディスプレイ モード

DirectDraw は、モード 13 モードおよびモード X ディスプレイ モードをサポートする。モード 13 は線形フリッピングができず、320 × 200 でピクセルあたり 8 ビットのパレット化モードである。このモードは、16 進 BIOS モード番号 13 で広く知られている。13. 詳細については、「モード 13 サポート」を参照すること。モード Xは、標準 VGA モード 13 から派生したハイブリッド ディスプレイ モードである。このモードでは、VGA ディスプレイ アダプタの EGA マルチ ビデオ面システムにより、256 KB までのディスプレイ メモリを使うことができる (モード 13 では 64 KB まで)。

DirectDraw はすべてのディスプレイ カードに対して、2 つのモード X モード (320×200×8 と 320×240×8) を提供する。また、線形低解像度モードをサポートするカードもある。線形低解像度モードではプライマリ サーフェスをロックして、直接アクセスできる。モード X モードではプライマリ サーフェスへ直接アクセスできない。

[C++]

モード X モードは、IDirectDraw7::SetCooperativeLevel メソッドを呼び出すときに、アプリケーションが DDSCL_ALLOWMODEX、DDSCL_FULLSCREEN、および DDSCL_EXCLUSIVE フラグを使用する場合にだけ利用することができる。DDSCL_ALLOWMODEX が指定されていない場合、IDirectDraw7::EnumDisplayModes メソッドはモード X モードを列挙せず、またモード X モードが要求されると IDirectDraw7::SetDisplayMode メソッドは失敗する。

Windows 95 および Windows NT/Windows 2000 は、モード X モードを最適にサポートしない。したがって、アプリケーションがモード X モードの場合、プライマリ サーフェスをロックしたり、ブリットするための IDirectDrawSurface7::Lock や IDirectDrawSurface7::Blt メソッドを使用することはできない。またプライマリ サーフェスで IDirectDrawSurface7::GetDC メソッドを使用することも、スクリーン DC で GDI を使用することもできない。モード X モードは、DDSCAPS2 構造体の DDSCAPS_MODEX フラグで示される。この構造体は、IDirectDrawSurface7::GetCaps および IDirectDraw7::EnumDisplayModes メソッドで返される DDSURFACEDESC2 構造体の一部である。

[Visual Basic]

モード X モードは、DirectDraw7.SetCooperativeLevel メソッドを呼び出すときに、アプリケーションが DDSCL_ALLOWMODEX、DDSCL_FULLSCREEN、および DDSCL_EXCLUSIVE フラグを使用する場合にだけ利用することができる。協調レベルの設定時に DSCL_ALLOWMODEX が指定されていない場合、DirectDraw7.GetDisplayModesEnum メソッドはモード X モードを列挙せず、モード X モードが要求されると DirectDraw7.SetDisplayMode メソッドは失敗する。

Windows 95 および Windows NT/Windows 2000 は、モード X モードを最適にサポートしない。したがって、アプリケーションがモード X モードの場合、プライマリ サーフェスをロックしたり、プライマリ サーフェスにブリット転送するための DirectDrawSurface7.Lock や DirectDrawSurface7.Blt メソッドを使用することはできない。またプライマリ サーフェスで DirectDrawSurface7.GetDC メソッドを使用することも、スクリーン DC で GDI を使用することもできない。モード X モードは、DDSCAPS2 型の DDSCAPS_MODEX フラグで示される。この型は、DirectDrawSurface7.GetCaps および DirectDrawEnumModes メソッドで返される DDSURFACEDESC2 型の一部である。


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

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

また、DirectDraw は、トゥルーカラー サーフェスの HEL ブリットもサポートする。ディスプレイ デバイスがこれらの解像度でブリットをサポートする場合は、ディスプレイ メモリ間のブリットにハードウェア ブリットが使われ、それ以外の場合は HEL が使用される。

[C++]

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

[Visual Basic]

DirectDraw は、インストールされたモニタのディスプレイ制限に対応したディスプレイ モードのリストをチェックする。DirectDraw が要求されたモードをユーザーのモニタで表示できないと決定する場合、DirectDraw7.SetDisplayMode メソッドの呼び出しは失敗する。また、DirectDraw7.GetDisplayModesEnum メソッドを呼び出したときに列挙されるのは、インストールされたモニタがサポートするモードだけである。


DirectDraw オブジェクト

ここでは、DirectDraw オブジェクトについて、および IDirectDraw、IDirectDraw2、IDirectDraw4、または IDirectDraw7 インターフェイスからオブジェクトを操作する方法について説明する。次の項目について記述する。

  • DirectDraw オブジェクトとは?
  • IDirectDraw7 での新機能
  • 親オブジェクトと子オブジェクトの有効期間
  • プロセスごとの複数の DirectDraw オブジェクト
  • CoCreateInstance を用いた DirectDraw オブジェクトの作成


DirectDraw オブジェクトとは?

[C++]

DirectDraw オブジェクトは、すべての DirectDraw アプリケーションの中心であり、また Direct3D® アプリケーションで欠く事のできない部分でもある。DirectDraw オブジェクトは作成する最初のオブジェクトであり、このオブジェクトから関連する他のすべてのオブジェクトが作成される。DirectX 7.0 では、最新バージョンの DirectDraw オブジェクトを作成するために新しいメソッドが導入された。DirectDrawCreateEx 関数は、最新の Direct3D インターフェイスを公開する DirectDraw オブジェクトを作成する。以前のバージョンでは、DirectDrawCreate 関数を呼び出して DirectDraw オブジェクトを作成する。この関数は、IDirectDraw インターフェイスを返す。異なるバージョンのインターフェイス (IDirectDraw7 など) で新しい機能を利用したい場合は、それを実行できるかどうかを照会することができる (「IDirectDraw7 インターフェイスの取得」を参照すること)。DirectX 7.0 では、DirectDrawCreate を使って DirectDraw オブジェクトを作成した後で、IDirectDraw7 インターフェイスを照会することもできるが、Direct3D の新機能はサポートしない。Direct3D の新機能を使用するには、DirectDrawCreateEx 関数を使って IDirectDraw7 インターフェイスを取得しなければならない。複数の DirectDraw オブジェクトを作成できる (システムにインストールされた各ディスプレイ デバイスに対して 1 つ) ことに注意する。

[Visual Basic]

DirectDraw オブジェクトは、すべての DirectDraw アプリケーションの中心であり、また Direct3D® アプリケーションで欠く事のできない部分でもある。DirectDraw オブジェクトは作成する最初のオブジェクトであり、このオブジェクトから関連する他のすべてのオブジェクトが作成される。Visual Basic では、DirectX7.DirectDrawCreate メソッドを呼び出して、最新バージョンの Direct3D インターフェイスを公開する DirectDraw7 オブジェクトを作成する。

DirectDraw オブジェクトは、ディスプレイ デバイスを表す。また、オブジェクトの作成されたディスプレイ デバイスが、ハードウェア アクセラレーションをサポートする場合、それを利用する。個々の固有の DirectDraw オブジェクトは、ディスプレイ デバイスを操作したり、作成するオブジェクトに依存する (または、"接続する") サーフェス パレット、およびクリッパーなどのオブジェクトを作成できる。たとえば、サーフェスを作成するには、C++ の IDirectDraw7::CreateSurface メソッドまたは Visual Basic の DirectDraw7.CreateSurface メソッドを呼び出す。あるいは、サーフェスに適用するパレット オブジェクトが必要な場合は、C++ の IDirectDraw7::CreatePalette メソッドまたは Visual Basic のDirectDraw7.CreatePalette メソッドを呼び出す。さらに、IDirectDraw7 インターフェイスと DirectDraw7 オブジェクトはクリッパー オブジェクトを作成する同様なメソッドを公開する。

DirectDraw オブジェクトに関して、同時に 2 つ以上のインスタンスを作成できる。最も単純な例としては、Windows 95 または Windows NT 4.0 以前のシステム上で 2 つのモニタを使う場合がある。これらのオペレーティング システム自体は、デュアル モニタをサポートしないが、ディスプレイ デバイスそれぞれに DirectDraw HAL を記述することができる。Windows と GDI が認識するディスプレイ デバイスは、デフォルトの DirectDraw オブジェクトのインスタンスを作成するときに用いられるものである。そうでないデバイスは、第 2 のディスプレイ デバイスのグローバル ユニーク識別子 (GUID) を使って作成された、独立したもう 1 つの DirectDraw オブジェクトによりアドレス指定される。この GUID は、C++ の DirectDrawEnumerate 関数または Visual Basic の DirectDrawEnum.GetGuid メソッドを使って取得できる。

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


IDirectDraw7 での新機能

[C++]

ここでは、IDirectDraw7 インターフェイスの提供する新しい機能について詳しく説明し、これまで用いられてきた IDirectDraw4 との動作の違いについて説明する (IDirectDraw5 および IDirectDraw6 インターフェイスというバージョンはないので、IDirectDraw4 が IDirectDraw7 の直前のバージョンになる)。次の項目について記述する。

  • IDirectDraw7 の新機能
  • IDirectDraw7 インターフェイスの取得

IDirectDraw7 インターフェイスと以前のバージョンの最も大きな違いは、Direct3D との密接な統合である。DirectX の従来のバージョンでは、IDirect3DTexture インターフェイスによってテクスチャを作成したが、DirectX 7.0 では、IDirectDrawSurface7 インターフェイスに、以下に示すようなテクスチャ管理メソッドが組み込まれた。

  • IDirectDrawSurface7::SetPriority
  • IDirectDrawSurface7::GetPriority
  • IDirectDrawSurface7::SetLOD
  • IDirectDrawSurface7::GetLOD

その他、ステレオ フリッピング サーフェス、リフレッシュ レートの列挙、およびキューブ環境マップのサポートなども追加された。

[C++,Visual Basic]


IDirectDraw7 の新機能

[C++]

DirectX 7.0 の IDirectDraw7 インターフェイスに追加された新しいメソッドはないが、IDirectDraw7 と Direct3D の統合が強化されている。IDirectDraw7 オブジェクトは IDirect3D インターフェイスに対する QueryInterface をサポートしているが、同レベルのインターフェイスに対してしか QueryInterface を呼び出すことはできない。すなわち、DirectDraw オブジェクトから IDirect3D7 を取得したら、そのオブジェクトからそれ以前の Direct3D インターフェイスを取得することはできない。同様に、DirectDraw オブジェクトから以前の Direct3D インターフェイスを取得したら、そのオブジェクトから IDirect3D7 を取得することはできない。

さらに、IDirectDraw7 によって作成されたサーフェスで、Direct3D 関連の QueryInterface 呼び出しを行うことはできない (このような呼び出しを行うと E_NOINTERFACE が返される)。アプリケーションは、IDirectDraw4 以前のバージョンによって作成されたサーフェスからのみ IDirect3DTexture インターフェイスを取得できる。

以上のような理由から、従来の Direct3D インターフェイスを使用する場合は DirectDraw 7.0 インターフェイスは使用できないし、DirectX 7.0 Direct3D インターフェイスを使用する場合には DirectX 7.0 DirectDraw インターフェイスを使用する必要がある。

今回のバージョンでは、IDirectDraw7 インターフェイスを取得するための新しい DirectDraw オブジェクト作成関数、DirectDrawCreateEx が追加された。詳細については、次の「IDirectDraw7 インターフェイスの取得」で説明する。

[C++,Visual Basic]


IDirectDraw7 インターフェイスの取得

[C++]

DirectX 7.0 では、IDirectDraw7 インターフェイスを作成するための新しい関数、DirectDrawCreateEx が導入された。DirectDraw および Direct3D の新機能をサポートする最新バージョンの DirectDraw オブジェクトを作成するには、この関数を使用しなければならない。IDirectDraw7 インターフェイスは、IDirectDraw4 インターフェイスに置き換えられる。この新しいインターフェイスを取得するには、次の C++ の例に示すように DirectDrawCreateEx 関数を使う。

// DirectDraw を初期化する。

LPDIRECTDRAW7 lpDD7;
HRESULT hr;
if (FAILED(hr = DirectDrawCreateEx(NULL, (VOID**)&lpDD7, IID_IDirectDraw7, NULL)))
    return FALSE;

if (FAILED(hr = lpDD7->SetCooperativeLevel(NULL, DDSCL_NORMAL)))
    return FALSE;

IDirectDraw7 インターフェイスを取得した後、そのメソッドを呼び出して、新機能、パフォーマンスの改善、および異なる動作を活用する。新しいインターフェイスのリリースと共に、従来のメソッドがいくつか変更される。そのため、インターフェイス メソッドの新旧バージョン (たとえば IDirectDraw4 と IDirectDraw7) を混用すると、予測不可能な結果が生じる。

[Visual Basic]

Visual Basic では、DirectX7.DirectDrawCreate メソッドによって DirectDraw オブジェクトを取得する。


親オブジェクトと子オブジェクトの有効期間

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectDraw プログラミングで使うすべてのオブジェクト (DirectDraw オブジェクト、サーフェス パレット、クリッパーなど) は、アプリケーションのような他のオブジェクトがそれを必要とするかぎり、メモリ内に存在するだけである。オブジェクトの有効期間とは、オブジェクトがメモリに作成されて配置された瞬間から、オブジェクトが解放された後にメモリから削除されるまでの時間である。すべての DirectX コンポーネントに従うコンポーネント オブジェクト モデル (COM) では、1 つのオブジェクトがサービスを必要とする他のオブジェクトの数を調査し続けることを指示する。この数は参照カウントと呼ばれ、オブジェクトの有効期間を決定する。また、COM では、IUnknown::AddRef および IUnknown::Release メソッドを使ってオブジェクトを調べ、アプリケーションが参照カウントを明示的に管理することができる。COM の規則に従い、これらのメソッドを使って確認すること。

オブジェクトに対する参照カウントを管理するには、誰もが IUnknown メソッドを使用できる。また、DirectDraw オブジェクトは内部で参照カウントを使う。IDirectDraw7 (IDirectDraw2 や IDirectDraw と対照に) インターフェイスを使って、サーフェスのような "子" オブジェクトを作成する場合、子は "親" の DirectDraw オブジェクトの IUnknown::AddRef メソッドを使用して、親の参照カウントをインクリメントする。

アプリケーションでオブジェクトが必要なくなると、参照カウントをデクリメントする Release メソッドを呼び出す。参照カウントがゼロになると、そのオブジェクトはメモリから削除される。子オブジェクトの参照カウントがゼロになると、親の IUnknown::Release メソッドを呼び出して、親のサービスを必要とするオブジェクトが少なくとも 1 つあることを示す。

IDirectDraw7::CreateSurface の呼び出しで作成するフリッピング チェーンのバックバッファ サーフェスのように暗に割り当てられたオブジェクトでは、そのオブジェクトの親の DirectDrawSurface オブジェクトが解放されると、自動的に割り当てが削除される。また、アプリケーション ウィンドウを作成するスレッドから、DirectDraw オブジェクトだけを解放できる。単一のスレッド化されたアプリケーションに対して、この制限は 1 つのスレッドだけが存在するように明らかに適用されない。アプリケーションで、アタッチ状態の DirectDrawClipper オブジェクトを使用する 2 つのサーフェス (CreateSurface の呼び出しで作成された) のプライマリ フリッピング チェーンを作成した場合、これらのオブジェクトを確実に解放するコードは以下のようになる。

// この例では、g_lpDDraw、g_lpDDSurface、および
// g_lpDDClip がオブジェクトに対する有効なポインタとなる。
void ReleaseDDrawObjects(void)
{
// DirectDraw オブジェクト ポインタが有効な場合、
// そのオブジェクトとポインタは安全に解放される。
    if(g_lpDDraw)
    {
// DirectDraw オブジェクトを解放する (子が IDirectDraw2
// や IDirectDraw から作成された場合、この呼び出しは
// 安全とはならない。この場合の詳細情報は、
// 以下に示すメモを参照すること)。
        g_lpDDraw->Release(), g_lpDDraw = NULL;

// ここでは、サーフェスに割り当てられるクリッパーを解放する
        if(g_lpDDClip)
            g_lpDDClip->Release(), g_lpDDClip = NULL;

// ここでは、プライマリ フリッピング チェーンを解放する。フリッピングチェーン サーフェスが
//  CreateSurface の呼び出しで作成されたために、
// これは唯一有効となることに
// 注意する。そのサーフェスが明示的に作成されて
// アタッチされるならば、解放も明示的に
// されなくてはならない。
        if(g_lpDDSurface)
            g_lpDDSurface->Release(), g_lpDDSurface = NULL;
    }
}

注 : DirectDraw インターフェイスの以前のバージョン (正確には、IDirectDraw2 と IDirectDraw) は、大部分の最新のインターフェイスとは異なる動作をする。以前のインターフェイスを使用している場合、親自体が解放されると、DirectDraw は自動的にすべての子オブジェクトを解放する。そのため、これらの古いインターフェイスを使用する場合は、オブジェクトを解放する順序が重要になる。この場合、DirectDraw オブジェクト自体を解放する (または、クリーンアップする親により、そのオブジェクトすべてを解放しない) 前に、DirectDraw オブジェクトの子を解放しなくてはならない。DirectDraw オブジェクトは子オブジェクトを解放するので、子を解放する前に親を解放してしまうと、親オブジェクトが子オブジェクトを解放したときに無効となったポインタが参照できなくなり、メモリに障害を受けやすくなる。

オブジェクトが必要なくなると、古いアプリケーションは子オブジェクトの自動解放に頼り、いくつかのオブジェクトを正しく解放できなくなる場合がある。この場合、この習慣があらゆる悪影響を引き起こす訳ではないが、IDirectDraw7 インターフェイスを使うときはメモリ リークの原因となることがある。


プロセスごとの複数の DirectDraw オブジェクト

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectDraw では、プロセスは必要な回数だけ DirectDrawCreate 関数を呼び出すことができる。呼び出しごとに、固有の異なる DirectDraw オブジェクトへの固有の異なるインターフェイスが返される。個々の DirectDraw オブジェクトは要求通りに使用することができ、オブジェクト間には従属性がない。まさに、個々のオブジェクトは、固有のプロセスから作成されたかのように動作するのである。

DirectDraw オブジェクトは、互いに独立している。作成された DirectDrawSurface、DirectDrawPalette、DirectDrawClipper の各オブジェクトは、他の DirectDraw オブジェクトと共に使用することはできない。これらのオブジェクトは、DirectDraw オブジェクトが破棄されるときに自動的に解放される場合があるからである。他の DirectDraw オブジェクトと共に使用した場合、親オブジェクトが破棄されると機能が停止してしまう可能性があり、その他の DirectDraw オブジェクトに誤動作が生じる。

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


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

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

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

  1. アプリケーションの開始時に NULL を指定して CoInitialize を呼び出し、COM を初期化する。
    if (FAILED(CoInitialize(NULL)))
    return FALSE;
  2. CoCreateInstance と IDirectDraw7::Initialize メソッドを使って DirectDraw オブジェクトを作成する。
    ddrval = CoCreateInstance(&CLSID_DirectDraw,
    NULL, CLSCTX_ALL, &IID_IDirectDraw7, &lpdd);
if(!FAILED(ddrval))
    ddrval = IDirectDraw7_Initialize(lpdd, NULL);

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

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

アプリケーションを終了する前に、CoUninitialize 関数で COM ライブラリを閉じること。

CoUninitialize () ;


サーフェス

ここでは、DirectDrawSurface オブジェクトについて説明する。次の項目について記述する。

  • サーフェスの基本概念
  • サーフェスの作成
  • フリッピング サーフェス
  • サーフェスへのブリット
  • サーフェスの消失とリストア
  • サーフェスの COM 参照カウント セマンティクス
  • サーフェスの列挙
  • サーフェス特性の更新
  • サーフェス メモリへの直接アクセス
  • ガンマ コントロールとカラー コントロール
  • オーバーレイ サーフェス
  • 圧縮したテクスチャ サーフェス
  • プライベート サーフェス データ
  • サーフェス固有値
  • 非ローカル ビデオ メモリ サーフェスの使用
  • サーフェス コンテキストとデバイス コンテキスト


サーフェスの基本概念

ここでは、DirectDrawSurface オブジェクトに関連する概念について説明する。次の項目について記述する。

  • サーフェスとは?
  • サーフェス インターフェイス
  • 幅とピッチ
  • カラー キーイング
  • ピクセル フォーマット


サーフェスとは?

サーフェスまたは DirectDrawSurface オブジェクトは、ディスプレイ メモリの線形領域を表す。通常、サーフェスはディスプレイ カードのディスプレイ メモリに常駐しているが、システム メモリに存在することもできる。DirectDrawSurface オブジェクト作成の過程で特に指示されないかぎり、DirectDraw オブジェクトは、要求される能力で最高のパフォーマンスが得られる場所に DirectDrawSurface オブジェクトを置く。DirectDrawSurface オブジェクトは、ディスプレイ カード上の特化されたプロセッサを有効に利用でき、システム CPU と並行してタスクを実行する。

[C++]

IDirectDraw7::CreateSurface メソッドを使用すると、1 つのサーフェス オブジェクト、複合サーフェス フリッピング チェーン、あるいは 3 次元サーフェスを作成することができる。CreateSurface メソッドは要求されたサーフェスまたはフリッピング チェーンを作成し、プライマリ サーフェスの IDirectDrawSurface7 インターフェイスへのポインタを取得する。このインターフェイスから、オブジェクトはその機能を公開する。

IDirectDrawSurface7 インターフェイスにより、IDirectDrawSurface7::BltFast などのブリット メソッドからメモリに間接的にアクセスできる。サーフェス オブジェクトは、GDI 関数で使えるディスプレイへのデバイス コンテキストを提供できる。さらに、IDirectDrawSurface7 メソッドを使うと、ディスプレイ メモリに直接アクセスすることができる。たとえば、IDirectDrawSurface7::Lock メソッドを使ってディスプレイ メモリをロックして、そのサーフェスに対応するアドレスを取得することができる。ディスプレイ メモリのアドレスは、表示されるフレーム バッファ メモリ (プライマリ サーフェス) や、非表示のバッファ (オフスクリーン、またはオーバーレイ サーフェス) を指したりすることもある。通常、非表示のバッファはディスプレイ メモリに常駐するが、ハードウェア制限により要求されたり、DirectDraw がソフトウェアのエミュレーションを行ったりする場合、システム メモリに作成されることもある。さらに、IDirectDrawSurface7 インターフェイスは、パレットの設定や取得に使ったり、あるいはフリッピング チェーンやオーバーレイなどの特定のタイプやサーフェスと共に作用したりするために使う他のメソッドを拡張する。

[Visual Basic]

DirectDraw7.CreateSurface メソッドを使用すると、1 つのサーフェス オブジェクト、複合サーフェス フリッピング チェーン、あるいは 3 次元サーフェスを作成することができる。CreateSurface メソッドは要求されたサーフェスまたはフリッピング チェーンを作成し、プライマリ サーフェスの IDirectDrawSurface7 インターフェイスへのポインタを取得する。このインターフェイスから、オブジェクトはその機能を公開する。

DirectDrawSurface7 オブジェクトにより、DirectDrawSurface7.BltFast などのブリット メソッドからメモリに間接的にアクセスできる。サーフェス オブジェクトは、GDI 関数で使えるディスプレイへのデバイス コンテキストを提供できる。さらに、DirectDrawSurface7 メソッドを使うと、ディスプレイ メモリに直接アクセスすることができる。たとえば、DirectDrawSurface7.Lock メソッドを使ってディスプレイ メモリをロックして、そのサーフェスを取得できる。ディスプレイ メモリは、表示されるフレーム バッファ メモリ (プライマリ サーフェス) や、非表示のバッファ (オフスクリーン、またはオーバーレイ サーフェス) になることもある。通常、非表示のバッファはディスプレイ メモリに常駐するが、ハードウェア制限により要求されたり、DirectDraw がソフトウェアのエミュレーションを行ったりする場合、システム メモリに作成されることもある。さらに、IDirectDrawSurface7 インターフェイスは、パレットの設定や取得に使ったり、あるいはフリッピング チェーンやオーバーレイなどの特定のタイプやサーフェスと共に作用したりするために使う他のメソッドを拡張する。

次に示す図から、すべてのサーフェスは DirectDraw オブジェクトにより作成され、パレットと密接に関連して用いられることもあることがわかる。個々のサーフェス オブジェクトにパレットを割り当てられるが、パレットは深度が 8 ビット以下のピクセル フォーマットを使うプライマリ サーフェス以外では要求されない。


サーフェス インターフェイス

[C++]

DirectDrawSurface オブジェクトは、IDirectDrawSurface、IDirectDrawSurface2、IDirectDrawSurface3、IDirectDrawSurface4、および IDirectDrawSurface7 インターフェイスからその機能を公開する。個々の新しいインターフェイス バージョンでは、以前のバージョンと同じユーティリティだけでなく、新しいメソッドから利用できる追加オプションを提供する。

IDirectDraw7::CreateSurface メソッド (または、IDirectDraw7 からの他の作成メソッド) を呼び出してサーフェスを作成する場合、サーフェスの IDirectDrawSurface7 インターフェイスへのポインタを受け取る。この動作は DirectX の以前のバージョンとは異なる。IDirectDraw7 インターフェイスの導入前は、CreateSurface メソッドがサーフェスの IDirectDrawSurface インターフェイスへポインタを提供していた。新しいバージョンのインターフェイスから提供される新機能を利用するには、新しいバージョンをクエリーしなくてはならない。IDirectDraw7 はこの場合には使用できないが、選択するならばインターフェイスで提供される以前のバージョンを参照できる。

[Visual Basic]

DirectDrawSurface オブジェクトは、DirectDrawSurface7 クラスから作成される。DirectDraw7.CreateSurface メソッドを呼び出すと、DirectDrawSurface オブジェクトが返される。


幅とピッチ

幅とピッチという単語からある程度想像できるが、非常に重要な (そして、明らかな違い) 意味がある。そのため、それぞれの意味と、DirectDraw が幅とピッチを記述するために使う値の判断方法を理解しなくてはならない。

[C++]

DirectDraw では、DDSURFACEDESC2 構造体を使ってサーフェスを記述する情報を伝達する。他にも、このディメンジョンのメモリ内での表示方法と同様に、この構造体はサーフェスのディメンジョンの情報を含むために定義される。この構造体では dwHeight メンバと dwWidth メンバを使い、サーフェスの論理的なディメンジョンを記述する。この 2 つのメンバはピクセル単位で測定される。そのため、640 × 480 のサーフェスに対する dwHeight 値と dwWidth 値は、8 ビットのパレット化サーフェスや 24 ビットの RGB サーフェスに関係なく同じになる。

DDSURFACEDESC2 構造体には、サーフェスが lPitch メンバからどのようにメモリ内に表示されるかという情報が含まれる。lPitch メンバの値は、サーフェスのメモリ ピッチ (または、ストライドと呼ばれる) を記述する。ピッチは、2 つのメモリ アドレス間 (あるビットマップ ラインの始点と次のビットマップ ラインの始点) の距離であり、単位はバイトである。ピッチはピクセルではなくバイト単位で測定されるために、640 × 480 × 8 のサーフェスは、異なるピクセル フォーマットの同じディメンジョンのサーフェスよりも非常に異なるピッチの値を持つ。さらに、ピッチの値は DirectDraw がキャッシュとして確保されるバイトを反映することもあるので、単にピッチをピクセルごとにバイト数を掛けた幅であると仮定することはできない。次の図で、幅とピッチにおける違いを説明する。

[Visual Basic]

DirectDraw では、DDSURFACEDESC2 型を使ってサーフェスを記述する情報を伝達する。他にも、このディメンジョンのメモリ内での表示方法と同様に、この構造体はサーフェスのディメンジョンの情報を含むために定義される。この構造体では lHeight メンバと Width メンバを使い、サーフェスの論理的なディメンジョンを記述する。この 2 つのメンバはピクセル単位で測定される。そのため、640 × 480 のサーフェスに対する lHeight 値と lWidth 値は、8 ビットのパレット化サーフェスや 24 ビットの RGB サーフェスに関係なく同じになる。

DDSURFACEDESC2 型には、サーフェスが lPitch メンバからどのようにメモリ内に表示されるかという情報が含まれる。lPitch メンバの値は、サーフェスのメモリ ピッチ (または、ストライド と呼ばれる) を記述する。ピッチは、2 つのメモリ アドレス間 (あるビットマップ ラインの始点と次のビットマップ ラインの始点) の距離であり、単位はバイトである。ピッチはピクセルではなくバイト単位で測定されるために、640 × 480 × 8 のサーフェスは、異なるピクセル フォーマットの同じディメンジョンのサーフェスよりも非常に異なるピッチの値を持つ。さらに、ピッチの値は DirectDraw がキャッシュとして確保されるバイトを反映することもあるので、単にピッチをピクセルごとにバイト数を掛けた幅であると仮定することはできない。次の図で、幅とピッチにおける違いを説明する。

上記の図では、フロント バッファとバック バッファはどちらも 640 × 480 × 8 で、キャッシュは 384 × 480 × 8 である。

[C++]

サーフェス メモリに直接アクセスする場合、ピッチの値が役立つ。たとえば、IDirectDrawSurface7::Lock メソッドを呼び出した後に、関連付けられた DDSURFACEDESC2 構造体の lpSurface メンバには、そのサーフェスのロックされた領域の左上ピクセルのアドレスが含まれ、lPitch メンバはサーフェス ピッチとなる。ピクセルごとのバイト数により、サーフェス ポインタをインクリメントしたりデクリメントすることで、左右にピクセルをアクセスできる。また、ピッチの値を現在のサーフェス ポインタに追加したり、もしくはそのポインタから減じたりすると、上下に移動できる。

サーフェスに直接アクセスする場合、サーフェスのディメンジョンに対して割り当てられたメモリの範囲内に置くことと、キャッシュに対して確保されたあらゆるメモリの外に置くことに注意する。さらに、サーフェスのポインタだけをロックする場合、サーフェスをロックするときに指定する矩形の範囲内に置かなくてはならない。これに従わないと、予測不可能な結果が生じる。サーフェス メモリに直接レンダリングする場合、常に Lock メソッド (または、IDirectDrawSurface7::GetDC メソッド) から返されるピッチを使う。単に、ディスプレイ モードに基づくピッチを仮定して使用してはならない。他の原因により正常に動作しなくなったいくつかのディスプレイ アダプタ上でアプリケーションが動作する場合、問題が生じる可能性がある。

[Visual Basic]

サーフェス メモリに直接アクセスする場合、ピッチの値が役立つ。たとえば、DirectDrawSurface7.Lock メソッドを呼び出すと、lPitch メンバはサーフェス ピッチとなる。ピクセルごとのバイト数により、サーフェス ポインタをインクリメントしたりデクリメントすることで、左右にピクセルをアクセスできる。また、ピッチの値を現在のサーフェス ポインタに追加したり、もしくはそのポインタから減じたりすると、上下に移動できる。

サーフェスに直接アクセスする場合、サーフェスのディメンジョンに対して割り当てられたメモリの範囲内に置くことと、キャッシュに対して確保されたあらゆるメモリの外に置くことに注意する。さらに、サーフェスのポインタだけをロックする場合、サーフェスをロックするときに指定する矩形の範囲内に置かなくてはならない。これに従わないと、予測不可能な結果が生じる。サーフェス メモリに直接レンダリングする場合、Lock メンバ (または DirectDrawSurface7.GetDC メソッド) によって返されたピッチを常に使用する。単に、ディスプレイ モードに基づくピッチを仮定して使用してはならない。他の原因により正常に動作しなくなったいくつかのディスプレイ アダプタ上でアプリケーションが動作する場合、問題が生じる可能性がある。

詳細については、「サーフェス メモリへの直接アクセス」を参照すること。


カラー キーイング

DirectDraw は、ブリットおよびオーバーレイ サーフェスの転送元、転送先カラー キーイングをサポートする。カラー キーにより、あるイメージを他のサーフェスの上部へ選択的に表示できるため、あるピクセルだけを前方の矩形から表示したり、後方の矩形にオーバーライトできる。

[C++]

IDirectDrawSurface7::SetColorKey メソッドを呼び出すことにより、単一のカラー キーまたは転送元か転送先カラー キーイングの色域を与えることができる。

[Visual Basic]

DirectDrawSurface7.SetColorKey メソッドを呼び出すことにより、単一のカラー キーまたは転送元か転送先カラー キーの色域を与えることができる。

カラー キーイングの詳細については、次の項目を参照すること。

  • オーバーレイ カラー キー
  • 透過型ブリット


ピクセル フォーマット

[C++]

ピクセル フォーマットは、サーフェス メモリ中の各ピクセルのデータをどのように判断するかを指示する。DirectDraw は DDPIXELFORMAT 構造体を用いて、さまざまのピクセル フォーマットを記述する。DDPIXELFORMAT には、ピクセル フォーマットの特徴を記述するメンバが含まれる。次にこの特徴について示す。

  • パレット化または非パレット化ピクセル フォーマット
  • 非パレット化の場合、ピクセル フォーマットは RGB であるか YUV であるか
  • ビット深度
  • ピクセル フォーマットのコンポーネントに対するビットマスク

既存のサーフェスのピクセル フォーマットに関する情報を取得するには、IDirectDrawSurface7::GetPixelFormat メソッドを呼び出す。

[Visual Basic]

ピクセル フォーマットは、サーフェス メモリ中の各ピクセルのデータをどのように判断するかを指示する。DirectDraw は DDPIXELFORMAT 型を用いて、さまざまのピクセル フォーマットを記述する。DDPIXELFORMAT には、ピクセル フォーマットの特徴を記述するメンバが含まれる。次にこの特徴について示す。

  • パレット化または非パレット化ピクセル フォーマット
  • 非パレット化の場合、ピクセル フォーマットは RGB であるか YUV であるか
  • ビット深度
  • ピクセル フォーマットのコンポーネントに対するビットマスク

既存のサーフェスのピクセル フォーマットに関する情報を取得するには、DirectDrawSurface7.GetPixelFormat メソッドを呼び出す。


サーフェスの作成

DirectDrawSurface オブジェクトはサーフェスを表す。通常、サーフェスはディスプレイ メモリに常駐するが、ディスプレイ メモリが満杯であったり明示的に要求される場合には、システム メモリに存在させることができる。

[C++]

1 つのサーフェスを作成したり、同時に複数のサーフェス (複合サーフェス) を作成するには、IDirectDraw7::CreateSurface メソッドを使う。CreateSurface を呼び出す場合、サーフェスのディメンジョンを指定する。このディメンジョンでは、サーフェスが単一サーフェスであるか複合サーフェスであるか、およびピクセル フォーマット (サーフェスがインデックス パレットを使用しない場合) を示す。これらすべての特性は DDSURFACEDESC2 構造体に含まれており、そのアドレスは呼び出し時に送る。ハードウェアが要求された能力をサポートできなかったり、そのリソースが事前に別の DirectDrawSurface オブジェクトに割り当てられている場合、その呼び出しは失敗する。

[Visual Basic]

1 つのサーフェスを作成したり、同時に複数のサーフェス (複合サーフェス) を作成するには、DirectDraw7.CreateSurface メソッドを使う。CreateSurface を呼び出す場合、サーフェスのディメンジョンを指定する。このディメンジョンでは、サーフェスが単一サーフェスであるか複合サーフェスであるか、およびピクセル フォーマット (サーフェスがインデックス パレットを使用しない場合) を示す。これらすべての特性は DDSURFACEDESC2 型に含まれており、そのアドレスは呼び出し時に送る。ハードウェアが要求された能力をサポートできなかったり、そのリソースが事前に別の DirectDrawSurface オブジェクトに割り当てられている場合、その呼び出しは失敗する。

単一サーフェスまたは複合サーフェスの作成は、数行のコードですむ簡単なタスクである。サーフェスを作成するために必要となるいくつかの一般的な状況 (または、一般的でない状況) を示す。以下の状況について説明する。

  • プライマリ サーフェスの作成
  • オフスクリーン サーフェスの作成
  • 複合サーフェスとフリッピング チェーンの作成
  • ワイド サーフェスの作成
  • クライアント メモリ サーフェスの作成
[C++]

クライアント メモリ サーフェス以外のすべてのサーフェスにおけるデフォルトでは、DirectDraw はローカル ビデオ メモリにサーフェスを作成しようとする。サーフェスを保持するために利用できるローカル ビデオ メモリが十分でなければ、DirectDraw は非ローカル ビデオ メモリ (AGP を装備したシステム) を利用しようとする。そして、他のすべてのメモリ タイプが利用できなければ、システム メモリに頼ろうとする。サーフェスをあるタイプのメモリに作成するよう明示的に要求するには、IDirectDraw7::CreateSurface を呼び出すときに該当するフラグを関連付けられた DDSCAPS2 構造体に含める。

[Visual Basic]

クライアント メモリ サーフェス以外のすべてのサーフェスにおけるデフォルトでは、DirectDraw はローカル ビデオ メモリにサーフェスを作成しようとする。サーフェスを保持するために利用できるローカル ビデオ メモリが十分でなければ、DirectDraw は非ローカル ビデオ メモリ (AGP を装備したシステム) を利用しようとする。そして、他のすべてのメモリ タイプが利用できなければ、システム メモリに頼ろうとする。サーフェスをあるタイプのメモリに作成するよう明示的に要求するには、DirectDraw7.CreateSurface を呼び出すときに該当するフラグを関連付けられた DDSCAPS2 型に含める。


プライマリ サーフェスの作成

プライマリ サーフェス とは、現在モニタに表示されているサーフェスであり、DDSCAPS_PRIMARYSURFACE フラグで識別することができる。個々の DirectDraw オブジェクトに対してプライマリ サーフェスは 1 つしか存在しない。

プライマリ サーフェスを作成する場合、ディメンジョンおよびピクセル フォーマットは、現在のディスプレイ モードに暗に適合することを思い出すこと。したがって、これはサーフェスのディメンジョンやピクセル フォーマットを宣言する必要のない場合の 1 つである。つまり、これらの値を指定すると、その情報が現在のディスプレイ モードと適合していてしても、呼び出しは失敗して、DDERR_INVALIDPARAMS を返す。

[C++]

次の例では、プライマリ サーフェスの作成に関係する DDSURFACEDESC2 構造体のメンバをどのように準備するかについて示す。

DDSURFACEDESC2 ddsd;
ddsd.dwSize = sizeof(ddsd);

// どのメンバが有効か DirectDraw に伝える。
ddsd.dwFlags = DDSD_CAPS;

// プライマリ サーフェスを要求する。
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;

プライマリ サーフェスを作成すると、IDirectDrawSurface7::GetSurfaceDesc メソッドを呼び出してディメンジョンやピクセル フォーマットについての情報を取得することができる。

[Visual Basic]

次の例では、プライマリ サーフェスの作成に関係する DDSURFACEDESC2 型のメンバをどのように準備するかについて示す。

Dim ddsd As DDSURFACEDESC2

' どのメンバが有効か DirectDraw に伝える。
ddsd.lFlags = DDSD_CAPS

' プライマリ サーフェスを要求する。
ddsd.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE

プライマリ サーフェスを作成すると、DirectDrawSurface7.GetSurfaceDesc メソッドを呼び出してディメンジョンやピクセル フォーマットについての情報を取得することができる。

「ディスプレイ モード」も参照すること。


オフスクリーン サーフェスの作成

[C++]

オフスクリーン サーフェスは、後でプライマリ サーフェスあるいはバック バッファにブリットされるビットマップをキャッシュするために使われることがある。DDSD_WIDTH および DDSD_HEIGHT フラグを設定し、対応する値を dwWidth および dwHeight メンバに与えることで、オフスクリーン サーフェスのディメンジョンを宣言する。さらに、付随する DDSCAPS2 構造体に DDSCAPS_OFFSCREENPLAIN フラグを設定しなくてはならない。

デフォルトでは、DirectDraw はディスプレイ メモリにサーフェスを作成しようとする。うまくいかなければ、システム メモリにサーフェスを作成する。DDSCAPS2 構造体の dwCaps メンバに DDSCAPS_SYSTEMMEMORY または DDSCAPS_VIDEOMEMORY フラグを設定することで、明示的にディスプレイ メモリまたはシステム メモリを選択できる。指定された位置にサーフェスを作成できない場合、メソッドはエラーを返して失敗する。

次に示す例は、簡単なオフスクリーン サーフェスの作成の方法を示す。

DDSURFACEDESC2 ddsd;
ddsd.dwSize = sizeof(ddsd);

// どのメンバが有効か DirectDraw に伝える。
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH;

// 簡単なオフスクリーン サーフェスを要求する。
// サイズは 100 × 100 ピクセルである。
//
// (作成するオフスクリーン サーフェスが
// プライマリ サーフェスのピクセル フォーマットに
// 適合すると仮定する。)
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
ddsd.dwHeight = 100;
ddsd.dwWidth = 100;

また、ピクセル フォーマットがプライマリ サーフェスのピクセル フォーマットと異なるサーフェスも作成できる。ただし、この場合には、システム メモリの使用が制限されるという弱点がある。次に示すコードでは、8 ビット パレット化サーフェス (現在のディスプレイ モードがピクセルごとに 8 ビット以外であると仮定する) を作成するために、DDSURFACEDESC2 構造体メンバを準備する方法について示す。

ZeroMemory(&ddsd, sizeof(ddsd));
ddsd.dwSize  = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH | DDSD_PIXELFORMAT;
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN | DDSCAPS_SYSTEMMEMORY;
ddsd.dwHeight = 100;
ddsd.dwWidth  = 100;
ddsd.ddpfPixelFormat.dwSize  = sizeof(DDPIXELFORMAT);
ddsd.ddpfPixelFormat.dwFlags = DDPF_RGB | DDPF_PALETTEINDEXED8;

// 8 ビット サーフェスに対するビット深度を設定するが、
// あらゆる RGB マスク値を指定してはならない。パレット化サーフェスに対して、
// マスク値は 0 でなければならない。
ddsd.ddpfPixelFormat.dwRGBBitCount = 8;
[Visual Basic]

オフスクリーン サーフェスは、後でプライマリ サーフェスあるいはバック バッファにブリットされるビットマップをキャッシュするために使われることがある。DDSD_WIDTH および DDSD_HEIGHT フラグを設定し、対応する値を IWidth および IHeight メンバに与えることで、オフスクリーン サーフェスのディメンジョンを宣言する。さらに、付随する DDSCAPS2 型に DDSCAPS_OFFSCREENPLAIN フラグを設定しなくてはならない。

デフォルトでは、DirectDraw はディスプレイ メモリにサーフェスを作成しようとする。うまくいかなければ、システム メモリにサーフェスを作成する。DDSCAPS2 型の lCaps メンバに DDSCAPS_SYSTEMMEMORY または DDSCAPS_VIDEOMEMORY フラグを設定することで、明示的にディスプレイ メモリまたはシステム メモリを選択できる。指定された位置にサーフェスを作成できない場合、メソッドはエラーを返して失敗する。

次に示す例は、簡単なオフスクリーン サーフェスの作成の方法を示す。

Dim ddsd As DDSURFACEDESC2

' どのメンバが有効か DirectDraw に伝える。
ddsd.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH

' 簡単なオフスクリーン サーフェスを要求する。
' サイズは 100 × 100 ピクセルである。
'
' (作成するオフスクリーン サーフェスが
' プライマリ サーフェスのピクセル フォーマットに
' 適合すると仮定する。
ddsd.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
ddsd.lHeight = 100
ddsd.lWidth = 100

また、ピクセル フォーマットがプライマリ サーフェスのピクセル フォーマットと異なるサーフェスも作成できる。ただし、この場合には、システム メモリの使用が制限されるという弱点がある。次に示すコードでは、8 ビット パレット化サーフェス (現在のディスプレイ モードがピクセルごとに 8 ビット以外であると仮定する) を作成するために、DDSURFACEDESC2 型のメンバを準備する方法について示す。

ddsd.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH Or DDSD_PIXELFORMAT
ddsd.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_SYSTEMMEMORY
ddsd.lHeight = 100
ddsd.lWidth = 100
ddsd.ddpfPixelFormat.lFlags = DDPF_RGB Or DDPF_PALETTEINDEXED8

' 8 ビット サーフェスに対するビット深度を設定するが、
' あらゆる RGB マスク値を指定してはならない。パレット化サーフェスに対して、
' マスク値は 0 でなければならない。
ddsd.ddpfPixelFormat.lRGBBitCount = 8

DirectX の以前のバージョンでは、オフスクリーン サーフェスの最大幅はプライマリ サーフェスの幅に制限されていた。DirectX 5.0 では、ディスプレイ ハードウェアがサポートできるのであれば、必要なだけ広いサーフェスを作成することができる。ただし、幅の広いオフスクリーン サーフェスを宣言する場合には注意が必要である。ビデオ カードメモリが要求された広さのサーフェスを保持できない場合、サーフェスはシステム メモリに作成される。明示的にビデオ メモリを選択し、ハードウェアがそれをサポートできない場合、その呼び出しは失敗する。詳細については、「ワイド サーフェスの作成」を参照すること。


複合サーフェスとフリッピング チェーンの作成

[C++]

また、複合サーフェスを作成することもできる。複合サーフェスは、IDirectDraw7::CreateSurface メソッドの呼び出しで作成されたサーフェスの集合である。CreateSurface を呼び出すときに DDSCAPS_COMPLEX フラグを設定すると、DirectDraw は明示的に指定されたサーフェス以外に、暗に 1 つ以上のサーフェスを作成する。複合サーフェスは、単一サーフェスと同様に管理することができる。すなわち、IDirectDraw::Release メソッドの呼び出しですべてのサーフェスを解放することができ、また、IDirectDrawSurface7::Restore メソッドの呼び出しですべてのサーフェスをリストアすることができる。ただし、暗に作成されたサーフェスのアタッチは解除できない。詳細については、「IDirectDrawSurface7::DeleteAttachedSurface」を参照すること。

[Visual Basic]

また、複合サーフェスを作成することもできる。複合サーフェスは、DirectDraw7.CreateSurface メソッドの呼び出しで作成されたサーフェスの集合である。CreateSurface を呼び出すときに DDSCAPS_COMPLEX フラグを設定すると、DirectDraw は明示的に指定されたサーフェス以外に、暗に 1 つ以上のサーフェスを作成する。複合サーフェスは、単一サーフェスと同様に管理することができる。すなわち、DirectDrawSurface7.Restore メソッドの呼び出しですべてのサーフェスをリストアできる。ただし、暗に作成されたサーフェスのアタッチは解除できない。詳細については、「DirectDrawSurface7.DeleteAttachedSurface」を参照すること。

作成可能なもっとも有用な複合サーフェスの 1 つは、フリッピング チェーンである。通常、フリッピング チェーンはプライマリ サーフェス、および 1 つ以上のバック バッファからなる。DDSCAPS_FLIP フラグは、サーフェスがフリッピング チェーンの一部であることを示す。この方法でフリッピング チェーンを作成するには、DDSCAPS_COMPLEX フラグも設定しなくてはならない。

[C++]

次の例では、プライマリ サーフェス フリッピング チェーンの作成方法を示す。

DDSURFACEDESC2 ddsd2;
ddsd2.dwSize = sizeof(ddsd2);

// どのメンバが有効か DirectDraw に伝える。
ddsd2.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;

// 1 つのバック バッファと共に、
// プライマリ サーフェスを要求する。
ddsd2.ddsCaps.dwCaps = DDSCAPS_COMPLEX | DDSCAPS_FLIP |
DDSCAPS_PRIMARYSURFACE;
ddsd2.dwBackBufferCount = 1;

上記の例は、ダブルバッファ フリッピング環境を構築するものである。すなわち、IDirectDrawSurface7::Flip メソッドを呼び出すと、プライマリ サーフェスとバック バッファのサーフェス メモリが交換される。DDSURFACEDESC2 構造体の dwBackBufferCount メンバの値に 2 を指定すると、2 つのバック バッファが作成される。また、Flip を呼び出すごとにサーフェスが循環パターンで循環し、トリプル バッファ フリッピング環境を提供する。詳細については、「フリッピング サーフェス」を参照すること。

[Visual Basic]

次の例では、プライマリ サーフェス フリッピング チェーンの作成方法を示す。

Dim ddsd2 As DDSURFACEDESC2

' どのメンバが有効か DirectDraw に伝える。
ddsd2.lFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT

' 1 つのバック バッファと共に、
' プライマリ サーフェスを要求する。
ddsd2.ddsCaps.lCaps = DDSCAPS_COMPLEX Or DDSCAPS_FLIP Or _
DDSCAPS_PRIMARYSURFACE;
ddsd2.lBackBufferCount = 1

上記の例は、ダブルバッファ フリッピング環境を構築するものである。すなわち、DirectDrawSurface7.Flip メソッドを呼び出すと、プライマリ サーフェスとバック バッファのサーフェス メモリが交換される。DDSURFACEDESC2 型の IBackBufferCount メンバの値に 2 を指定すると、2 つのバック バッファが作成される。また、Flip を呼び出すごとにサーフェスが循環パターンで循環し、トリプル バッファフリッピング環境を提供する。詳細については、「フリッピング サーフェス」を参照すること。

注 : 3D レンダリング ターゲットとして使用されるサーフェスから成るフリッピング チェーンを作成するには、DDSCAPS_COMPLEX および DDSCAPS_FLIP フラグのほかに、サーフェス記述の DDSCAPS_3DDEVICE 能力フラグを必ず含むこと。

[C++]

IDirectDraw3 以前のインターフェイスでの CreateSurface メソッドとは異なり、深度バッファにアタッチされたレンダリング ターゲット サーフェスのフリッピング チェーンを作成するために、IDirectDraw7::CreateSurface を使用できない。IDirectDraw7::CreateSurface メソッドが受け取る DDSURFACEDESC2 構造体に、深度バッファビット深度を指定するフィールドを含むことはできない。このため、アプリケーションでは明示的に深度バッファ サーフェスを作成し、そのサーフェスをバックバッファ レンダーリング ターゲットにアタッチしなくてはならない。詳細については、Direct3D 直接モードの「深度バッファ」を参照すること。


ワイド サーフェスの作成

DirectDraw により、プライマリ サーフェスよりも幅の広いオフスクリーン サーフェスをビデオ メモリに作成できる。これが可能なのは、ディスプレイ デバイスがワイド サーフェスをサポートするときだけである。

[C++]

ワイド サーフェスがサポートされているかどうかを調べるには、IDirectDraw7::GetCaps を呼び出してから、その際に一緒に送った最初の DDCAPS 構造体の dwCaps2 メンバに DDCAPS2_WIDESURFACES フラグがあるかどうかを探す。このフラグがあると、プライマリ サーフェスよりも幅の広いビデオ メモリ オフスクリーン サーフェスを作成することができる。

DDCAPS2_WIDESURFACES フラグが存在しないときに、ビデオ メモリにワイド サーフェスを作成しようとすると、失敗して DDERR_INVALIDPARAMS を返す。たとえそのドライバが DDCAPS2_WIDESURFACES フラグを明らかにしたとしても、極端に大きなサーフェスを作成しようとすると、失敗する可能性があることに注意すること。

常に、ワイド サーフェスはシステム メモリ サーフェス、ビデオ ポート サーフェス、および実行バッファでサポートされる。

[Visual Basic]

ワイド サーフェスがサポートされているかどうかを調べるには、DirectDraw7.GetCaps を呼び出してから、その際に一緒に送った最初の DDCAPS 型の Caps2 メンバに DDCAPS2_WIDESURFACES フラグがあるかどうかを探す。このフラグがあると、プライマリ サーフェスよりも幅の広いビデオ メモリ オフスクリーン サーフェスを作成することができる。

DDCAPS2_WIDESURFACES フラグが存在しないときに、ビデオ メモリにワイド サーフェスを作成しようとすると、失敗して DDERR_INVALIDPARAMS を返す。たとえそのドライバが DDCAPS2_WIDESURFACES フラグを明らかにしたとしても、極端に大きなサーフェスを作成しようとすると、失敗する可能性があることに注意すること。

ワイド サーフェスは、常にシステム メモリ サーフェスでサポートされる。


クライアント メモリ サーフェスの作成

クライアント メモリ サーフェスは、簡単な DirectDrawSurface オブジェクトであり、イメージ データを保持するためにアプリケーションが以前に割り当てられたシステム メモリを使用する。このようなサーフェスを作成することは一般的ではないが、作成するのは簡単である。既存のメモリバッファ上の DirectDraw サーフェス機能を使う必要のあるアプリケーションでは役立つ。

[C++]

サーフェスの作成時に、DirectDraw ではサーフェスのピクセル フォーマットと同様に、サーフェスのディメンジョン (ピクセル単位) とサーフェスのピッチ (バイト単位) についての情報が必要となる。ただし、クライアント メモリに関するこの情報は、作成されるサーフェスを DirectDraw に伝えない他のタイプのサーフェスにおける作成とは異なり、既にサーフェスを作成していることを DirectDraw に伝える。IDirectDraw7::CreateSurface メソッドに渡す DDSURFACEDESC2 構造体に、割り当てられたバッファのメモリ アドレスを足す特性を設定できる。

クライアント メモリ サーフェスは、一般的なシステム メモリ サーフェスのように動作する。ただし例外として、DirectDraw は必要のなくなったサーフェス メモリを解放しようとはしない。メモリを割り当てられたクライアントの解放は、アプリケーションが行う。

次の例では、メモリを割り当てる場合について説明し、64 × 64 ピクセルの 24 ビット RGB サーフェスに対する DirectDrawSurface オブジェクトを作成する。

// この例では、g_lpDD4 が有効な IDirectDraw7 インターフェイス ポインタとなる。

#define WIDTH  64 // ピクセル単位。
#define HEIGHT 64
#define DEPTH  3  // バイト単位 (3 バイト ==24 ビット )。

    HRESULT hr;
    LPVOID  lpSurface  = NULL;
    HLOCAL  hMemHandle = NULL;
    DDSURFACEDESC2 ddsd2;
    LPDIRECTDRAWSURFACE7 lpDDS;

    // 64 × 64 のメモリを割り当てる (ピクセル バッファごとに 24 ビット)。
    // バッファが不要になると、アプリケーションにより
    //           このバッファが解放される。
    if (lpSurface = malloc((size_t)WIDTH*HEIGHT*DEPTH))
        ZeroMemory(lpSurface, (DWORD)WIDTH*HEIGHT*DEPTH);
    else
        return DDERR_OUTOFMEMORY;

    // サーフェスの記述を初期化する。
    ZeroMemory(&ddsd2, sizeof(DDSURFACEDESC2));
    ZeroMemory(&ddsd2.ddpfPixelFormat, sizeof(DDPIXELFORMAT));
    ddsd2.dwSize = sizeof(ddsd2);
    ddsd2.dwFlags = DDSD_WIDTH | DDSD_HEIGHT | DDSD_LPSURFACE |
                    DDSD_PITCH | DDSD_PIXELFORMAT | DDSD_CAPS;
    ddsd2.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN |
                           DDSCAPS_SYSTEMMEMORY;
    ddsd2.dwWidth = WIDTH;
    ddsd2.dwHeight= HEIGHT;
    ddsd2.lPitch  = (LONG)DEPTH * WIDTH;
    ddsd2.lpSurface = lpSurface;

    // ピクセル フォーマットを 24 ビット RGB (8-8-8) にセット アップする。
    ddsd2.ddpfPixelFormat.dwSize = sizeof(DDPIXELFORMAT);
    ddsd2.ddpfPixelFormat.dwFlags= DDPF_RGB;
    ddsd2.ddpfPixelFormat.dwRGBBitCount = (DWORD)DEPTH*8;
    ddsd2.ddpfPixelFormat.dwRBitMask    = 0x00FF0000;
    ddsd2.ddpfPixelFormat.dwGBitMask    = 0x0000FF00;
    ddsd2.ddpfPixelFormat.dwBBitMask    = 0x000000FF;

    // サーフェスを作成する。
    hr = g_lpDD->CreateSurface(&ddsd2, &lpDDS, NULL);
    return hr;
[Visual Basic]

サーフェスの作成時に、DirectDraw ではサーフェスのピクセル フォーマットと同様に、サーフェスのディメンジョン (ピクセル単位) とサーフェスのピッチ (バイト単位) についての情報が必要となる。ただし、クライアント メモリに関するこの情報は、作成されるサーフェスを DirectDraw に伝えない他のタイプのサーフェスにおける作成とは異なり、既にサーフェスを作成していることを DirectDraw に伝える。DirectDraw7.CreateSurface メソッドに渡す DDSURFACEDESC2 型に、割り当てられたバッファのメモリ アドレスを足す特性を設定できる。

クライアント メモリ サーフェスは、一般的なシステム メモリ サーフェスのように動作する。ただし例外として、DirectDraw は必要のなくなったサーフェス メモリを解放しようとはしない。メモリを割り当てられたクライアントの解放は、アプリケーションが行う。

次の例では、メモリを割り当てる場合について説明し、64 × 64 ピクセルの 24 ビット RGB サーフェスに対する DirectDrawSurface を作成する。

'この例では、dd が有効な DirectDraw7 オブジェクトとなる。

Const cWIDTH = 64 'ピクセル単位
Const cHEIGHT = 64
Const cDEPTH = 3 'バイト単位 (3 バイト = 24 ビット)

Dim ddsd2 As DDSURFACEDESC2
Dim dds As DirectDrawSurface7
Private Sub Form_Load()

' サーフェスの記述を初期化する。
With ddsd2
.lFlags = DDSD_WIDTH Or DDSD_HEIGHT Or DDSD_PITCH Or DDSD_PIXELFORMAT Or DDSD_CAPS
.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_SYSTEMMEMORY
.lWidth = cWIDTH
.lHeight = cHEIGHT
.lPitch = cDEPTH * cWIDTH
' ピクセル フォーマットを 24 ビット RGB (8-8-8) にセット アップする。
With .ddpfPixelFormat
.lFlags = DDPF_RGB
.lRGBBitCount = cDEPTH * 8
.lRBitMask = &HFF0000
.lGBitMask = &HFF00&
.lBBitMask = &HFF&
End With
End With

' サーフェスを作成する。
Set dds = dd.CreateSurface(ddsd2)

End Sub


フリッピング サーフェス

DirectDraw のすべてのサーフェスは、フリッピング サーフェスとして構築される。フリッピング サーフェスとは、フロント バッファとバック バッファ間でスワップすることのできるメモリの一部にすぎない (通常、この構成要素はフリッピング チェーンと呼ばれる。) ほとんどの場合、フロント バッファはプライマリ サーフェスであるが、必ずしもそうである必要はない。

[C++]

一般に、IDirectDrawSurface7::Flip メソッドを用いてサーフェス フリッピング処理を要求する場合、プライマリ サーフェスとバック バッファに対するサーフェス メモリへのポインタはスワップされる。フリッピングは、サーフェス メモリをコピーすることではなく、メモリを参照するためにディスプレイ デバイスの使用するポインタを切り替えることで実行される (DirectDraw がフリッピングをエミュレートしているときは例外である。この場合は、単にサーフェスをコピーする。バック バッファがディスプレイ メモリに適合しない場合や、ハードウェアが DirectDraw をサポートしない場合、DirectDraw はフリッピング処理をエミュレートする)。フリッピング チェーンにプライマリ サーフェスと 1 つ以上のバック バッファがある場合、次の図に示すように、ポインタは循環的パターンで切り替えられる。

[Visual Basic]

一般に、DirectDrawSurface7.Flip メソッドを用いてサーフェス フリッピング処理を要求する場合、プライマリ サーフェスとバック バッファに対するサーフェス メモリはスワップされる。フリッピングは、サーフェス メモリをコピーすることではなく、メモリを参照するためにディスプレイ デバイスの使用するサーフェスを切り替えることで実行される (DirectDraw がフリッピングをエミュレートしているときは例外である。この場合は、単にサーフェスをコピーする。バック バッファがディスプレイ メモリに適合しない場合や、ハードウェアが DirectDraw をサポートしない場合、DirectDraw はフリッピング処理をエミュレートする)。フリッピング チェーンにプライマリ サーフェスと 1 つ以上のバック バッファがある場合、次の図に示すように、サーフェスは循環的パターンで切り替えられる。

DirectDraw オブジェクトにアタッチされているが、フリッピング チェーンの一部ではない他のサーフェスは、Flip メソッドが呼び出されても影響を受けない。

[C++]

DirectDraw は、オブジェクト自体をスワップするのではなく、DirectDrawSurface オブジェクト内のサーフェス メモリ ポインタをスワップすることで、サーフェスのフリッピングを行うことを思い出すこと。このため、常に同じ DirectDrawSurface オブジェクト (すなわちフリッピング チェーンを作成したときにバック バッファであった DirectDrawSurface オブジェクト) を使用して、任意のタイプのフリッピング スキームでバック バッファにブリットする。反対に、常にフロントサーフェスの Flip メソッドを呼び出して、フリッピング処理を実行する。

プライマリ サーフェス フリッピング チェーンや表示されるオーバーレイ サーフェス フリッピング チェーンなどの表示されるサーフェスと共に作用する場合、DDFLIP_WAIT フラグが含まれていなければ Flip メソッドは非同期となる。このような表示されるサーフェスでは、ハードウェアで実際のフリッピング処理が生じる前に、Flip メソッドが戻る可能性がある (ハードウェアは次の垂直リフレッシュが起こるまで、フリッピングを行わないためである)。実際のフリッピング処理がペンディング中に、IDirectDrawSurface7::Lock、IDirectDrawSurface7::Blt、IDirectDrawSurface7::BltFast、または IDirectDrawSurface7::GetDC メソッドを呼び出して、現在表示されているサーフェスの背後のバック バッファをロックしたり、ブリットすることはできない。フリッピング処理がペンディング中にこれらのメソッドを呼び出そうとすると、失敗して DDERR_WASSTILLDRAWING を返す。ただし、トリプル バッファ スキームを使用している場合、最後のバッファは利用可能のままである。

[Visual Basic]

DirectDraw は、オブジェクト自体をスワップするのではなく、DirectDrawSurface オブジェクト内のサーフェス メモリをスワップすることで、サーフェスのフリッピングを行うことを思い出すこと。このため、常に同じ DirectDrawSurface オブジェクト (すなわちフリッピング チェーンを作成したときにバック バッファであった DirectDrawSurface オブジェクト) を使用して、任意のタイプのフリッピング スキームでバック バッファにブリットする。反対に、常にフロントサーフェスの Flip メソッドを呼び出して、フリッピング処理を実行する。

プライマリ サーフェス フリッピング チェーンや表示されるオーバーレイ サーフェス フリッピング チェーンなどの表示されるサーフェスと共に作用する場合、DDFLIP_WAIT フラグが含まれていなければ Flip メソッドは非同期となる。このような表示されるサーフェスでは、ハードウェアで実際のフリッピング処理が生じる前に、Flip メソッドが戻る可能性がある (ハードウェアは次の垂直リフレッシュが起こるまで、フリッピングを行わないためである)。実際のフリッピング処理がペンディング中に、DirectDrawSurface7.Lock、DirectDrawSurface7.Blt、DirectDrawSurface7.BltColorFill、DirectDrawSurface7.BltFast、DirectDrawSurface7.BltFx、DirectDrawSurface7.BltToDC または DirectDrawSurface7.GetDC メソッドを呼び出して、現在表示されているサーフェスの背後のバック バッファをロックしたり、ブリットすることはできない。フリッピング処理がペンディング中にこれらのメソッドを呼び出そうとすると、失敗して DDERR_WASSTILLDRAWING を返す。ただし、トリプル バッファ スキームを使用している場合、最後のバッファは利用可能のままである。


サーフェスへのブリット

ここでは、ある DirectDraw サーフェスから他へ、またはサーフェスのある部分から他へピクセルをコピーすることについて説明する。

以下の項目について記述する。

  • ブリットについて
  • BltFast によるブリット
  • Blt によるブリット
  • ブリットのタイミング
  • 透過型ブリット
  • カラー フィル
  • マルチ ウィンドウへのブリット


ブリットについて

[C++]

イメージを DirectDraw サーフェスへコピーするには、IDirectDrawSurface7::Blt と IDirectDrawSurface7::BltFast の 2 つのメソッドを使用できる (IDirectDrawSurface7::BltBatch メソッドは、DirectX のこのバージョンでは実装されていない)。これらのメソッドは転送先サーフェスで呼び出され、パラメータとして転送元サーフェスを受け取る。転送先および転送元サーフェスは 1 つかつ同じサーフェスであることも可能である。DirectDraw では、オーバーライトの前にすべての転送元ピクセルを保持するため、オーバーラップの心配はない。

実装された 2 つのメソッドでは、Blt がより柔軟性に富み、BltFast がより速い。ただしこれは、ハードウェア ブリットのない場合に限る。ハードウェアのブリット能力を決定するには、IDirectDraw7::GetCaps メソッドの lpDDDriverCaps パラメータが取得する DDCAPS 構造体を使用する。dwCaps メンバに DDCAPS_BLT がある場合、ハードウェアには少なくとも最低のブリット能力がある。

[Visual Basic]

イメージを DirectDraw サーフェスにコピーするには、DirectDrawSurface7.Blt、DirectDrawSurface7.BltColorFill、DirectDrawSurface7.BltFast、DirectDrawSurface7.BltFx および DirectDrawSurface7.BltToDC の 5 つのメソッドを使用できる。これらのメソッドは転送先サーフェスで呼び出され、パラメータとして転送元サーフェスを受け取る。転送先および転送元サーフェスは 1 つかつ同じサーフェスであることも可能である。DirectDraw では、オーバーライトの前にすべての転送元ピクセルを保持するため、オーバーラップの心配はない。

実装された 2 つのメソッドでは、Blt がより柔軟性に富み、BltFast がより速い。ただしこれは、ハードウェア ブリットのない場合に限る。ハードウェアのブリット能力を決定するには、DirectDraw7.GetCaps メソッドの hwCaps パラメータが取得する DDCAPS 型を使用する。lCaps メンバに DDCAPS_BLT がある場合、ハードウェアには少なくとも最低のブリット能力がある。


BltFast によるブリット

[C++]

IDirectDrawSurface7::BltFast を使用する場合、コピーされるピクセル (または、サーフェスすべてを指定する NULL) および転送先サーフェスの x 座標と y 座標から、転送元サーフェスの有効な矩形を与えることができる。転送元矩形は転送先サーフェスの左上隅に適合できなくてはならないか、または呼び出しが DDERR_INVALIDRECT の戻り値で失敗する。BltFast は、アタッチ状態のクリッパーがあるサーフェスでは使用できない。

BltFast を使用する場合、伸縮、ミラーリング、または他のエフェクトは実行できない。

BltFast の例

次の例では、オフスクリーン サーフェス (lpDDSOffOne) からのピクセルをプライマリ サーフェス (lpDDSPrimary) にコピーする。フラグは、ブリットが解放されるとすぐにオペレーションの発生を確保し、転送元イメージの透過型ピクセルはコピーされない (これらのフラグの意味については、「ブリットのタイミング」および「透過型ブリット」を参照すること)。

lpDDSPrimary->BltFast(
        100, 200,    // 転送先の左上 xy
        lpDDSOffOne, // 転送元サーフェス
        NULL,        // 転送元矩形 = サーフェス全体
        DDBLTFAST_WAIT | DDBLTFAST_SRCCOLORKEY );
[Visual Basic]

DirectDrawSurface7.BltFast を使用する場合、転送元サーフェスの有効な矩形を与え (またはサーフェスすべてを意味する空の RECT 型を指定する)、および転送先サーフェスの x 座標と y 座標からコピーすることができる。転送元矩形は転送先サーフェスの左上隅に適合できなくてはならない。さもなければ、呼び出しが DDERR_INVALIDRECT の戻り値で失敗する。BltFast は、アタッチ状態のクリッパーがあるサーフェスでは使用できない。

BltFast を使用する場合、伸縮、ミラーリング、または他のエフェクトは実行できない。

BltFast の例

次の例では、オフスクリーン サーフェス (DDSOffOne) からのピクセルをプライマリ サーフェス (DDSPrimary) にコピーする。フラグは、ブリットが解放されるとすぐにオペレーションの発生を確保し、転送元イメージのキーで抜かれたピクセルはコピーされない (これらのフラグの意味については、「ブリットのタイミング」および「透過型ブリット」を参照すること)。

DDSPrimary.BltFast 100, 200, DDSOffOne, SrcRect, DDBLTFAST_WAIT Or DDBLTFAST_SRCCOLORKEY


Blt によるブリット

[C++]

IDirectDrawSurface7::Blt メソッドを使用する場合、転送元サーフェス (または、サーフェスすべてを指定する NULL) の有効な矩形、およびコピーされる転送元イメージへの転送先サーフェスの矩形を与える (NULL は、サーフェスすべてをカバーすることを意味する)。クリッパーが転送先サーフェスにアタッチされる場合、転送先矩形の境界はサーフェスの外側に配置でき、クリッピングが実行される。クリッパーのない場合は、転送先矩形がサーフェスの内側に完全に配置されるか、他のメソッドが DDERR_INVALIDRECT で失敗する (クリッピングの詳細については、「クリッパー」を参照すること)。

スケーリング

Blt メソッドは、転送元イメージのサイズを転送先矩形と適合するように自動的に再スケーリングする。サイズの再スケーリングをしたくない場合は、最良のパフォーマンスのために、転送元および転送先矩形が正確に同じサイズであることを確認するか、IDirectDrawSurface7:BltFast を使用する (「BltFast によるブリット」を参照すること)。

スケーリングに対するハードウェア アクセラレータは、デバイスに対する DDCAPS 構造体の dwFXCaps メンバの DDFXCAPS_BLT* フラグに依存する。たとえば、デバイスに DDFXCAPS_BLTSTRETCHX ではなく DDFXCAPS_BLTSTRETCHXN 能力がある場合、転送元矩形の x 軸が整数倍のときはアシストできるが、整数倍以外の (任意の) スケーリングがなされているときはアシストできない。

また、デバイスでは、ピクセルの単純な掛け算や削除よりも、補間によりスケーリングを行う算術スケーリングをサポートする場合がある。たとえば、軸が 1/3 増加する場合、ピクセルは塗り直され、その軸の 1/3 ピクセルごとの増加により生成される元のイメージにより近い近似値が与えられる。

アプリケーションは、Blt に渡される DDBLTFX 構造体の dwDDFX メンバにある DDBLTFX_ARITHSTRETCHY フラグの設定以外は、ドライバによるスケーリングのタイプを制御できない。このフラグは、y 軸で算術伸縮を行うことを要求する。DirectDraw API では、x 軸の算術拡大と算術縮小は現在サポートしていないが、ドライバはデフォルトでこれらを実行できる。

他のエフェクト

Blt を使用する際、スケーリング以外の特定のエフェクトを必要としない場合は、lpDDBltFx パラメータとして NULL を渡すことができる。それ以外は、DDBLTFX 構造体で指定される様々なエフェクトを選択できる。また同時に、HEL がカラー フィルとミラーリングをサポートするので、これらは常に利用できる。他の大部分のエフェクトはハードウェア サポートによる。

HEL のエフェクト能力をすべて見るには、DirectX SDK で提供される DDraw Caps ユーティリティを実行し、HEL メニューから HEL FX Caps を選択する。様々なフラグの説明は、「DDCAPS」を参照すること。また、IDirectDraw7::GetCaps メソッドを使用して、各自のアプリケーションにおける HEL 能力もチェックできる。

IDirectDrawSurface7::Blt メソッドに渡される DDBLTFX 構造体にあるメンバの 1 つの値を要求するエフェクトを指定する場合、構造体のメンバが有効であることを示す適切なフラグも dwFlags パラメータに含まなくてはならない。

DDBLTFX の dwFlags メンバにおけるフラグの設定だけを要求するエフェクトもある。このうちの 1 つは DDBLTFX_NOTEARING である。このフラグは、アニメーションされたイメージをフロント バッファに直接ブリットするときに使用できるため、ブリットはスクリーン リフレッシュおよびテアリングの可能性と同時に発生できる。また、ミラーリングと回転もフラグを使用して設定される。

ブリット エフェクトには、BitBlt のような GDI 関数で使用される一般的なラスタ処理 (ROP) が含まれる。HEL がサポートする ROP は SRCCOPY (デフォルト)、BLACKNESS、および WHITENESS だけである。他の ROP をサポートするハードウェアは、ドライバに対する DDCAPS 構造体で試すことができる。Blt メソッドと共に標準的なあらゆる ROP を使用したい場合は、DDBLTFX 構造体の dwROP メンバの ROP にフラグを立てる。

DDBLTFX 構造体の dwDDROP メンバは、ROP の特質を DirectDraw に指定するためにある。しかし、現時点で定義されている ROP はない。

アルファ値と Z 値

DirectDraw ブリットでは、不透明度と深度値を現時点ではサポートしていない。アルファ値がピクセル フォーマットに格納される場合、アルファ値は転送先矩形のあらゆるアルファ値に単にオーバーライトする。アルファ バッファと Z バッファからの値は無視される。アルファ チャネル と Z バッファ ("dwAlpha" と "dwZ" で始まる名前のメンバ) で行う DDBLTFX 構造体のメンバ、および Blt に対応するフラグは使用されない。そして、DDBLTFX 構造体の dwDDFX メンバの DDBLTFX_ZBUFFERBASEDEST および DDBLTFX_ZBUFFERRANGE フラグに提供する。

現時点では、Z バッファは Direct3D アプリケーションでしか使用されないが、IDirectDrawSurface7::Blt を使用して DDBLT_DEPTHFILL フラグを設定することにより、Z バッファ サーフェスの深度値を設定できる。詳細については、Direct3D 直接モードの「深度バッファのクリア」を参照すること。

Direct3D のアルファ チャネルおよび Z バッファの使用については、次の項目を参照すること。

  • アルファ ブレンディング ステート
  • 深度バッファとは

Blt の例

次に示す例では、lpDDS が有効な IDirectDrawSurface7 ポインタであると仮定して、左から右に矩形をミラーリングすることによりサーフェス内に左右対称のイメージを作成する。

RECT     rcSource, rcDest;
DDBLTFX  ddbltfx;

ZeroMemory(&ddbltfx, sizeof(ddbltfx));
ddbltfx.dwSize = sizeof(ddbltfx);
ddbltfx.dwDDFX = DDBLTFX_MIRRORLEFTRIGHT;

rcSource.top = 0; rcSource.left = 0;
rcSource.bottom = 100; rcSource.right = 200;
rcDest.top = 0; rcDest.left = 201;
rcDest.bottom = 100; rcDest.right = 401;

HRESULT hr = lpDDS->Blt(&rcDest,
                        lpDDS,
                        &rcSource,
                        DDBLT_WAIT | DDBLT_DDFX,
                        &ddbltfx);
[Visual Basic]

DirectDrawSurface7.Blt メソッドを使用する場合、転送元サーフェス (またはサーフェスすべてを指定する空の RECT) の有効な矩形、およびコピーされる転送元イメージへの転送先サーフェスの矩形を与えることができる (空の RECT は、サーフェスすべてをカバーすることを意味する)。クリッパーが転送先サーフェスにアタッチされる場合、転送先矩形の境界はサーフェスの外側に配置でき、クリッピングが実行される。クリッパーのない場合は、転送先矩形がサーフェスの内側に完全に配置されるか、他のメソッドが DDERR_INVALIDRECT で失敗する。(クリッピングについては、「クリッパー」を参照すること)。

スケーリング

Blt メソッドは、転送元イメージのサイズを転送先矩形と適合するように自動的に再スケーリングする。サイズの再スケーリングをしたくない場合は、最良のパフォーマンスのために、転送元および転送先矩形が正確に同じサイズであることを確認するか、DirectDrawSurface7.BltFast を使用する (「BltFast によるブリット」を参照すること)。

スケーリングに対するハードウェア アクセラレータは、デバイスに対する DDCAPS 型の lFXCaps メンバの DDFXCAPS_BLT* フラグに依存する。たとえば、デバイスに DDFXCAPS_BLTSTRETCHX ではなく DDFXCAPS_BLTSTRETCHXN 能力がある場合、転送元矩形の x 軸が整数倍のときはアシストできるが、整数倍以外の (任意の) スケーリングがなされているときはアシストできない。

また、デバイスでは、ピクセルの単純な掛け算や削除よりも、補間によりスケーリングを行う算術スケーリングをサポートする場合がある。たとえば、軸が 1/3 倍に増加する場合、ピクセルは塗り直され、その軸の 1/3 ピクセルごとの増加により生成される元のイメージにより近い近似値が与えられる。

アプリケーションは、Blt に渡される DDBLTFX 型の lDDFX メンバにある DDBLTFX_ARITHSTRETCHY フラグの設定以外は、ドライバによるスケーリングのタイプを制御できない。このフラグは、y 軸で算術伸縮を行うことを要求する。DirectDraw API では、x 軸の算術拡大と算術縮小は現在サポートしていないが、ドライバはデフォルトでこれらを実行できる。

他のエフェクト

スケーリング以外の特定のエフェクトを必要としない場合は、DirectDrawSurface7.BltFx メソッドを使用する。このメソッドでは、DDBLTFX 型で指定される様々なエフェクトを選択できる。また同時に、HEL がカラー フィルとミラーリングをサポートするので、これらは常に利用できる。他の大部分のエフェクトはハードウェア サポートによる。

HEL のエフェクト能力をすべて見るには、DirectX SDK で提供される Ddraw Caps ユーティリティを実行し、HEL メニューから HEL FX Caps を選択する。様々なフラグの説明は、「DDCAPS」を参照すること。また、DirectDraw7.GetCaps メソッドを使用して、各自のアプリケーションにおける HEL 能力もチェックできる。

DirectDrawSurface7.BltFx メソッドに渡される DDBLTFX 型にあるメンバの 1 つの値を要求するエフェクトを指定する場合、型のメンバが有効であることを示す適切なフラグも flags パラメータに含まなくてはならない。

DDBLTFX の IDDFX メンバにおけるフラグの設定だけを要求するエフェクトもある。このうちの 1 つは DDBLTFX_NOTEARING である。このフラグは、アニメーションされたイメージをフロント バッファに直接ブリットするときに使用できるため、ブリットはスクリーン リフレッシュおよびテアリングの可能性と同時に発生できる。また、ミラーリングと回転もフラグを使用して設定される。

ブリット エフェクトには、BitBlt のような GDI 関数で使用される一般的なラスタ処理 (ROP) が含まれる。HEL がサポートする ROP は SRCCOPY (デフォルト)、BLACKNESS、および WHITENESS だけである。他の ROP をサポートするハードウェアは、ドライバに対する DDCAPS 型で試すことができる。Blt メソッドと共に標準的なあらゆる ROP を使用したい場合は、DDBLTFX 型の IROP メンバの ROP にフラグを立てる。

DDBLTFX 型の IDDROP メンバは、ROP の特質を DirectDraw に指定するためにある。しかし、現時点で定義されている ROP はない。

アルファ値と Z 値

DirectDraw ブリットでは、不透明度と深度値を現時点ではサポートしていない。アルファ値がピクセル フォーマットに格納される場合、アルファ値は転送先矩形のあらゆるアルファ値に単にオーバーライトする。アルファ バッファと Z バッファからの値は無視される。アルファ チャネルと Z バッファ ("lAlpha" と "lZ" で始まる名前のメンバ) で行う DDBLTFX 型のメンバ、および Blt に対応するフラグは使用されない。そして、DDBLTFX 型の lDDFX メンバの DDBLTFX_ZBUFFERBASEDEST および DDBLTFX_ZBUFFERRANGE フラグに提供する。

現時点では、Z バッファは Direct3D アプリケーションでしか使用されないが、IDirectDrawSurface7.Blt を使用して DDBLT_DEPTHFILL フラグを設定することにより、Z バッファ サーフェスの深度値を設定できる。詳細については、Direct3D 直接モードの「深度バッファのクリア」を参照すること。

Direct3D のアルファ チャネルおよび Z バッファの使用については、次の項目を参照すること。

  • アルファ ブレンディング ステート
  • 深度バッファとは

Blt の例

次に示す例では、DDS が有効な DirectDrawSurface7 オブジェクトであると仮定して、左から右に矩形をミラーリングすることによりサーフェス内に左右対称のイメージを作成する。

rcSource As RECT
rcDest As RECT
ddbltfx As ddbltfx

ddbltfx.lDDFX = DDBLTFX_MIRRORLEFTRIGHT

rcSource.Top = 0
rcSource.Left = 0
rcSource.Bottom = 100
rcSource.Right = 200
rcDest.Top = 0
rcDest.Left = 201
rcDest.Bottom = 100
rcDest.Right = 401

dds.BltFx rcDest, dds, rcSource, DDBLT_WAIT Or DDBLT_DDFX, ddbltfx


ブリットのタイミング

[C++]

IDirectDrawSurface7::Blt または IDirectDrawSurface7::BltFast を使用してピクセルをサーフェスへコピーする場合、ハードウェア ブリットがコマンドを受け取る準備ができていないために、メソッドが DDERR_WASSTILLDRAWING で失敗する場合がある。

ブリットが正常に終了するのを待つ間に行うべき急ぎのタスクがないのなら、Blt の dwFlags パラメータに DDBLT_WAIT フラグを指定したり、BltFast に対して同値の DDBLTFAST_WAIT フラグを指定できる。このプラグは、ブリットが終わるまで (または、DDERR_WASSTILLDRAWING 以外のエラーが生じるまで) アプリケーションは待ち状態になる。

Blt は他のフラグ (DDBLT_ASYNC) も使える。このフラグは、ハードウェアの FIFO (ファースト イン、ファースト アウト) 待ち行列能力を利用し、アプリケーションは待ち状態にならない。

[Visual Basic]

DirectDrawSurface7.Blt、DirectDrawSurface7.BltColorFill、DirectDrawSurface7.BltFast、DirectDrawSurface7.BltFx または DirectDrawSurface7.BltToDC のいずれかを使用してピクセルをサーフェスにコピーする場合、ハードウェア ブリットがコマンドを受け取る準備ができていないために、メソッドが DDERR_WASSTILLDRAWING で失敗する場合がある。

ブリットが正常に終了するのを待つ間に行うべき急ぎのタスクがないのなら、Blt の dwFlags パラメータに DDBLT_WAIT フラグを指定したり、BltFast に対して同値の DDBLTFAST_WAIT フラグを指定できる。このプラグは、ブリットが終わるまで (または、DDERR_WASSTILLDRAWING 以外のエラーが生じるまで) アプリケーションは待ち状態になる。

Blt は他のフラグ (DDBLT_ASYNC) も使える。このフラグは、ハードウェアの FIFO (ファースト イン、ファースト アウト) 待ち行列能力を利用し、アプリケーションは待ち状態にならない。


透過型ブリット

ここでは、矩形イメージの一部を選択的にコピーするブリットの使用と、転送元および転送先カラー キーの使用の理論と実践について示す。

理論には次の項目が含まれる。

  • 透過型ブリットとは?

DirectDraw の透過型ブリットの実行における情報については、次の項目を参照すること。

  • カラー キー フォーマット
  • カラー キーの設定
  • カラー キーによるブリット


カラー フィル

[C++]

単色でサーフェス全体または一部を埋めるには、DDBLT_COLORFILL フラグと共に IDirectDrawSurface7::Blt メソッドを使用する。この技術により、すばやく領域を消去したり、固定色のバックグラウンドを描画できる。

次に示す例では、ピクセル フォーマットから青の数値を取得した後に、青色でサーフェス全体を埋める。

/* lpDDS が IDirectDrawSurface7 インターフェイスへの
有効な値であると仮定する。 */

HRESULT ddrval;
DDPIXELFORMAT ddpf;

ddpf.dwSize = sizeof(ddpf);
if (SUCCEEDED(lpDSS->GetPixelFormat(&ddpf))
{
    DDBLTFX ddbltfx;

    ddbltfx.dwSize = sizeof(ddbltfx);
    ddbltfx.dwFillColor = ddpf.dwBBitMask; // 純粋な青。

    ddrval = lpDDS->Blt(
        NULL,        // 転送先はサーフェス全体。
        NULL,        // 転送元サーフェスなし。
        NULL,        // 転送元矩形なし。
        DDBLT_COLORFILL, &ddbltfx);

    switch(ddrval)
    {
        case DDERR_WASSTILLDRAWING:
            .
            .
            .
        case DDERR_SURFACELOST:
            .
            .
            .
        case DD_OK:
            .
            .
            .
        default:
    }
}
[Visual Basic]

単色でサーフェス全体または一部を埋めるには、DirectDrawSurface7.BltColorFill メソッドを使用する。この技術により、すばやく領域を消去したり、固定色のバックグラウンドを描画できる。


マルチ ウィンドウへのブリット

DirectDraw オブジェクトおよび DirectDrawClipper オブジェクトを使用すると、標準協調レベルで実行するアプリケーションにより作成されるマルチ ウィンドウにブリットできる。詳細については、「マルチ ウィンドウでのクリッパーの使用」を参照すること。

互いのプライマリ サーフェスにブリットする複数の DirectDraw オブジェクトを作成することは、勧められない。


サーフェスの消失とリストア

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

[C++]

ディスプレイ モードが変更されたり、別のアプリケーションがディスプレイ カードへの排他アクセスを受け取り、そのディスプレイ カードに割り当てられたサーフェス メモリをすべて解放した場合、サーフェスは消失する。IDirectDrawSurface7::Restore メソッドは、消失したサーフェスを再作成し、DirectDrawSurface オブジェクトへ再接続する。アプリケーションで 1 つ以上のサーフェスを使用する場合、IDirectDraw7::RestoreAllSurfaces メソッドを呼び出すことで、一度にすべてのサーフェスをリストアできる。

[Visual Basic]

ディスプレイ モードが変更されたり、別のアプリケーションがディスプレイ カードへの排他アクセスを受け取り、そのディスプレイ カードに割り当てられたサーフェス メモリをすべて解放した場合、サーフェスは消失する。DirectDrawSurface7.Restore メソッドは、消失したサーフェスを再作成し、DirectDrawSurface オブジェクトへ再接続する。アプリケーションで 1 つ以上のサーフェスを使用する場合、DirectDraw7.RestoreAllSurfaces メソッドを呼び出すことで、一度にすべてのサーフェスをリストアできる。

サーフェスのリストアでは、消失する前のサーフェスに存在する可能性のあるビットマップを再ロードしない。以前に保持したグラフィックスは、完全に再構成しなくてはならない。


サーフェスの COM 参照カウント セマンティクス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

COM に準拠するということは、DirectDraw が参照カウントを使ってオブジェクトの有効期間を管理するための一定の規則に従うことを意味する。COM の概念については、COM のドキュメントを参照すること。DirectDraw 関連の説明については、「親オブジェクトと子オブジェクトの有効期間」を参照すること。

COM の規則によると、インターフェイス ポインタを別の変数に設定したり、別のオブジェクトに渡すことによってコピーした場合、そのオブジェクトに対する別の参照になるので、変更を反映させるには、そのインターフェイスの IUnknown::AddRef メソッドを呼び出さなければならない。DirectDraw オブジェクトを操作する際には、COM の参照カウント規則に従うだけでなく、DirectDraw が参照カウントを内部で更新する仕組みを理解しておく必要がある。クリッパーやパレット関連のメソッドはそれらのオブジェクトの参照カウントのみを変更するが、一部の DirectDraw メソッドは関連するサーフェスの参照カウントも変更する (複合サーフェス フリッピング チェーン関連のメソッドの多くはこれに該当する)。このような仕組みを理解しておくと、アプリケーションの安定性が向上し、メモリ リークを防止することができる。ここでは、次の項目について記述する。

  • 参照カウントの増減
  • 複合サーフェスの参照カウント
  • サーフェスの解放

注 : DirectDraw オブジェクトの参照カウントについては、このトピックで説明するメソッド等との関係の他にも、いくつか注意しなければならないことがある。詳細については、「DirectDraw オブジェクト」の「親オブジェクトと子オブジェクトの有効期間」を参照すること。


参照カウントの増減

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

いくつかの DirectDraw メソッドはサーフェスの参照カウントを変更するが、サーフェスに関連付けられた他のオブジェクトに影響を与えるメソッドもある。ここでは前者を「サーフェスのみ変更」、後者を「クロスオブジェクト変更」と言う。

サーフェスのみ変更
「サーフェスのみ変更」の場合、その名の示す通り、サーフェス オブジェクトの参照カウントだけが変更される。たとえば、IDirectDraw7::EnumSurfaces メソッドを使って、特定の条件を満たす現在のサーフェスを列挙した場合、メソッドが指定されたコールバック関数を起動すると、IDirectDrawSurface7 インターフェイスへのポインタが渡されるが、アプリケーションがポインタを受け取る前に、そのオブジェクトの参照カウントがインクリメントされる。従って、オブジェクトの処理が完了したら、そのオブジェクトを解放しなければならない。通常、コールバック ルーチンの終りで解放するか、そのオブジェクトを保持する必要がある場合には後で解放する。

その他、フリッピング チェーンなどの複合サーフェスでも、サーフェスのみ変更が適用される。複合サーフェスはサーフェスの集合であるが、大部分の場合 DirectDraw では単一のオブジェクトとして扱われるので、参照カウントの扱いには注意を要する。すなわち、IDirectDrawSurface7::GetAttachedSurface および IDirectDrawSurface7::AddAttachedSurface メソッドはサーフェスの参照カウントをインクリメントし、IDirectDrawSurface7::DeleteAttachedSurface メソッドはデクリメントする。これらのメソッドによって、現在のサーフェスにアタッチされているサーフェスの参照カウントが変更されることはない。詳細については、これらのメソッドのリファレンスと、「複合サーフェスの参照カウント」を参照すること。

クロスオブジェクト変更
「クロスオブジェクト変更」は、クリッパーやパレットなど、そのサーフェスに対するタスクを実行する別のオブジェクトとサーフェスが関連付けられている場合に適用される。

IDirectDrawSurface7::SetClipper や IDirectDrawSurface7::SetPalette メソッドは、アタッチされているオブジェクトの参照カウントをインクリメントする。オブジェクトがアタッチされると、サーフェスがそれらのオブジェクトを管理するが、サーフェスが解放されると、アタッチされたオブジェクトも自動的に解放される (このため、アプリケーションによっては、これらの呼び出しが成功してからオブジェクトを解放する。これは確実で有効な方法である)。

クリッパーやパレットがサーフェスにアタッチされると、IDirectDrawSurface7::GetClipper や IDirectDrawSurface7::GetPalette メソッドを呼び出して、それらを再度取得することができる。これらのメソッドはインターフェイス ポインタのコピーを返すので、取得されたオブジェクトの参照カウントが暗にインクリメントされる。インターフェイスの処理が完了したら、忘れずにそのインターフェイスを解放しなければならない。オブジェクトがアタッチされたサーフェスが、そのオブジェクトに対する参照を保持している限り、インターフェイスの示すオブジェクトが解放されない。


複合サーフェスの参照カウント

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

フリッピング チェーンなどの複合サーフェスの操作に使用するメソッドはすべて、サーフェス インターフェイス ポインタを使うので、サーフェスの参照カウントに影響を与える。複合サーフェスは、実際には単一サーフェスの集合なので、参照カウントの処理にはいくつかの注意が必要である。まず、IDirectDrawSurface7::GetAttachedSurface メソッドは、現在のサーフェスにアタッチされたサーフェスへのサーフェス インターフェイスを返す。取得されるインターフェイスの参照カウントをインクリメントしてからインターフェイスを返すので、不要になった場合にはそのインターフェイスを解放する必要がある。IDirectDrawSurface7::AddAttachedSurface メソッドは、新しいサーフェスを現在のサーフェスにアタッチする。また、AddAttachedSurface メソッドは、アタッチされたサーフェスのカウントをインクリメントする。チェーンからサーフェスを削除して、暗にその参照カウントをデクリメントするには、IDirectDrawSurface7::DeleteAttachedSurface メソッドを使用する。

これらのメソッドで注意しなければならないのは、複合サーフェスを構成する他のオブジェクトの参照カウントは変更されないことである。GetAttachedSurface メソッドは、取得するサーフェスの参照カウントをインクリメントするだけで、そのサーフェスがアタッチされたサーフェスのカウントには影響しない (IUnknown::AddRef メソッドを暗に呼び出す場合も同様である)。したがって、複合サーフェスでは、従属サーフェスの参照カウントがゼロになる前に、プライマリ サーフェスの参照カウントがゼロになる。プライマリ サーフェスの参照カウントがゼロになると、そのサーフェスにアタッチされた他のサーフェスは、参照カウントの現在の値に関係なく解放される (木の幹を切ると木全体が倒れるのと似ている。この場合、プライマリ サーフェスが幹である)。プライマリ サーフェスの割り当てが削除された後で従属サーフェスにアクセスしようとすると、メモリに障害が発生する。

このような問題が発生するのを防ぐため、プライマリ サーフェスを解放する前に、すべての従属サーフェスを解放する必要がある。アプリケーションが保持している参照を追跡し、プライマリ サーフェスへの参照が保持されていることを確認してから、従属サーフェスにアクセスする方法が確実である。


サーフェスの解放

[C++]

すべての COM インターフェイスと同様、必要のなくなったサーフェスは IDirectDrawSurface7::Release メソッドを呼び出して解放しなくてはならない。

個別に作成する個々のサーフェスは、明示的に解放する必要がある。ただし、フリッピング チェーンのように、IDirectDraw7::CreateSurface の呼び出しで暗に複数のサーフェスを作成した場合は、そのフロント バッファを解放するだけでよい。この場合、バック バッファ サーフェスを指すポインタは暗に解放され、その解放以降は使うことができなくなる。

バック バッファ サーフェスを暗に解放した場合、チェーン内のほかのサーフェスの参照カウントは変更されない。

[Visual Basic]

必要のなくなったサーフェスは、Nothing に設定することによって解放しなければならない。

個別に作成する個々のサーフェスは、明示的に解放する必要がある。ただし、フリッピング チェーンのように、IDirectDraw7::CreateSurface の呼び出しで暗に複数のサーフェスを作成した場合は、そのフロント バッファを解放するだけでよい。この場合、バック バッファ サーフェスは暗に解放され、以後使うことができなくなる。


サーフェスの列挙

[C++]

IDirectDraw7::EnumSurfaces メソッドを呼び出すことにより、DirectDraw はさまざまな方法でサーフェスを列挙できる。EnumSurfaces メソッドにより、提供されたサーフェスの記述に適合または不適合であるサーフェスを検索することができる。DirectDraw は、個々の列挙されたサーフェスに対して呼び出す EnumSurfacesCallback を呼び出す。

検索には 2 つの一般的な方法がある。DirectDraw オブジェクトが既に作成しているサーフェスを検索する方法、および DirectDraw オブジェクトがそのとき (サーフェスの記述と利用可能なメモリを与えるとき) に作成できるサーフェスを検索する方法である。メソッドの dwFlags パラメータの組み合わせフラグにより、検索タイプを指定できる。

既存サーフェスの列挙 これは列挙のもっとも一般的なタイプである。dwFlags パラメータで、DDENUMSURFACES_DOESEXIST 検索タイプ フラグと組み合わせフラグの 1 つ (DDENUMSURFACES_MATCH、DDENUMSURFACES_NOMATCH、または DDENUMSURFACES_ALL) の組み合わせを指定する EnumSurfaces を呼び出すと、既存サーフェスを列挙できる。既存サーフェスをすべて列挙している場合、lpDDSD パラメータを NULL に設定できる。または、そのパラメータを検索するサーフェスを記述するために初期化された DDSURFACEDESC2 構造体のアドレスにも設定できる。3 番目のパラメータ (lpContext) は、4 番目のパラメータ (lpEnumSurfacesCallback) に指定する列挙関数へ渡すアドレスに設定する。

次のコードでは、この呼び出しが DirectDraw オブジェクトの既存サーフェスをすべて列挙する場合を説明する。

HRESULT ddrval;
  ddrval = lpDD->EnumSurfaces(DDENUMSURFACES_DOESEXIST |
                              DDENUMSURFACES_ALL, NULL, NULL,
                              EnumCallback);
  if (FAILED(ddrval))
      return FALSE;

特定の記述に適合する既存サーフェスを検索する場合、DirectDraw では提供されたサーフェスを記述する個々のメンバと、既存サーフェスの個々のメンバを比較して適合を決定する。完全に適合したものだけが列挙される。DirectDraw では、列挙されたサーフェスの参照カウントをインクリメントするので、参照カウントを使用しない場合 (または、処理する場合) は、サーフェスの解放を確認すること。

利用可能なサーフェスの列挙 このタイプの列挙は、既存サーフェスの列挙よりも一般的ではない。しかし、サーフェスを作成しようとする前にサポートされる場合の決定には有用である。この検索を実行するには、IDirectDraw7::EnumSurfaces を呼び出すときに、DDENUMSURFACES_CANBECREATED と DDENUMSURFACES_MATCH フラグを組み合わせる (他のフラグの組み合わせでは無効となる)。呼び出しに使用する DDSURFACEDESC2 構造体は、DirectDraw で使用するサーフェス特性の情報を含むために初期化しなくてはならない。

特別なピクセル フォーマットを使用するサーフェスを列挙するには、DDSURFACEDESC2 構造体の dwFlags メンバに DDSD_PIXELFORMAT フラグを含む。さらに、サーフェスを記述する DDPIXELFORMAT 構造体を初期化して、その dwFlags メンバを要求されるピクセル フォーマット フラグ (DDPF_RGB、DDPF_YUV、または両方) を含むために設定する。他のピクセル フォーマット値は設定しなくてもよい。

DDSURFACEDESC2 構造体に DDSD_HEIGHT フラグと DDSD_WIDTH フラグを含む場合、dwHeight と dwWidth メンバで要求されるディメンジョンを指定できる。これらのフラグを含まない場合は、DirectDraw がプライマリ サーフェスのディメンジョンを使用する。

次のコードでは、この呼び出しが 96 × 96 の RGB や YUV サーフェスに対する有効なサーフェス特性のすべてを列挙する場合を説明する。

    DDSURFACEDESC2 ddsd;
    HRESULT        ddrval;
    ZeroMemory(&ddsd, sizeof(ddsd));

    ddsd.dwSize  = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS | DDSD_PIXELFORMAT |
                   DDSD_HEIGHT | DDSD_WIDTH;
    ddsd.ddpfPixelFormat.dwFlags = DDPF_YUV | DDPF_RGB;
    ddsd.dwHeight = 96;
    ddsd.dwWidth  = 96;

    ddrval = lpDD->EnumSurfaces(
                     DDENUMSURFACES_CANBECREATED | DDENUMSURFACES_MATCH,
                     &ddsd, NULL, EnumCallback);
    if (ddrval != DD_OK)
        return FALSE;

DirectDraw が利用可能なサーフェスを列挙する場合、実際には、要求された特性を持つ一時的なサーフェスを作成しようとする。その作成が成功すると、次に DirectDraw は作用される特性だけに提供される EnumSurfacesCallback 関数を呼び出す。つまり、一時的なサーフェスへのポインタには、コールバック関数を提供しない。サーフェスが列挙されない場合に、サーフェスがサポートされていないと仮定することはない。DirectDraw が一時的なサーフェスを作成しようとして、呼び出すときにのメモリ制約のために失敗した可能性もある。このため、ドライバが実際にサーフェスをサポートしていても、これらの特性が列挙されないのである。

[Visual Basic]

DirectDraw7.GetSurfacesEnum メソッドを呼び出すことにより、DirectDraw はさまざまな方法でサーフェスを列挙できる。GetSurfacesEnum メソッドにより、提供されたサーフェスの記述に適合または不適合であるサーフェスを検索することができる。このメソッドは、個々のサーフェス記述を照会する DirectDrawEnumSurfaces オブジェクトを作成する。

検索には 2 つの一般的な方法がある。DirectDraw オブジェクトが既に作成しているサーフェスを検索する方法、および DirectDraw オブジェクトがそのとき (サーフェスの記述と利用可能なメモリを与えるとき) に作成できるサーフェスを検索する方法である。メソッドの ｆlags パラメータの組み合わせフラグにより、検索タイプを指定できる。

既存サーフェスの列挙 これは列挙のもっとも一般的なタイプである。ｆlags パラメータで、DDENUMSURFACES_DOESEXIST 検索タイプ フラグと組み合わせフラグの 1 つ (DDENUMSURFACES_MATCH、DDENUMSURFACES_NOMATCH、または DDENUMSURFACES_ALL) の組み合わせを指定する GetSurfacesEnum を呼び出すと、既存サーフェスを列挙できる。既存サーフェスをすべて列挙している場合、desc パラメータを Nothing に設定できる。または、そのパラメータを検索するサーフェスを記述するために初期化された DDSURFACEDESC2 型のアドレスにも設定できる。

次のコードでは、この呼び出しが DirectDraw オブジェクトの既存サーフェスをすべて列挙する場合を説明する。ここでは、dd が有効な DirectDraw7 オブジェクト、ddEnumSurfaces が有効な DirectDrawEnumSurfaces オブジェクトとする。

Set ddEnumSurfaces = dd.GetSurfacesEnum(DDENUMSURFACES_DOESEXIST Or _
DDENUMSURFACES_ALL, ddsd2)

特定の記述に適合する既存サーフェスを検索する場合、DirectDraw では提供されたサーフェスを記述する個々のメンバと、既存サーフェスの個々のメンバを比較して適合を決定する。完全に適合したものだけが DirectDrawEnumSurfaces オブジェクトに埋め込まれる。

利用可能なサーフェスの列挙 このタイプの列挙は、既存サーフェスの列挙よりも一般的ではない。しかし、サーフェスを作成しようとする前にサポートされる場合の決定には有用である。この検索を実行するには、DirectDraw7.GetSurfacesEnum を呼び出すときに、DDENUMSURFACES_CANBECREATED と DDENUMSURFACES_MATCH フラグを組み合わせる (他のフラグの組み合わせでは無効となる)。呼び出しに使用する DDSURFACEDESC2 型は、DirectDraw で使用するサーフェス特性の情報を含むために初期化しなくてはならない。

特別なピクセル フォーマットを使用するサーフェスを列挙するには、DDSURFACEDESC2 型の lFlags メンバに DDSD_PIXELFORMAT フラグを含む。さらに、サーフェスを記述する DDPIXELFORMAT 型を初期化して、その lFlags メンバを要求されるピクセル フォーマット フラグ (DDPF_RGB、DDPF_YUV、または両方) を含むために設定する。他のピクセル フォーマット値は設定しなくてもよい。

DDSURFACEDESC2 型に DDSD_HEIGHT フラグと DDSD_WIDTH フラグを含む場合、lHeight と lWidth メンバで要求されるディメンジョンを指定できる。これらのフラグを含まない場合は、DirectDraw がプライマリ サーフェスのディメンジョンを使用する。

次のコードでは、この呼び出しが 96 × 96 の RGB や YUV サーフェスに対する有効なサーフェス特性のすべてを列挙する場合を説明する。

Dim ddsd As DDSURFACEDESC2

ddsd.lFlags = DDSD_CAPS Or DDSD_PIXELFORMAT Or
DDSD_HEIGHT Or DDSD_WIDTH
ddsd.ddpfPixelFormat.lFlags = DDPF_YUV Or DDPF_RGB
ddsd.lHeight = 96
ddsd.lWidth  = 96

Set ddEnumSurfaces = dd.GetSurfacesEnum(DDENUMSURFACES_CANBECREATED Or _
DDENUMSURFACES_MATCH, ddsd)

DirectDraw が利用可能なサーフェスを列挙する場合、実際には、要求された特性を持つ一時的なサーフェスを作成しようとする。その作成が成功すると、次に DirectDraw は DirectDrawEnumSurfaces オブジェクトに作用される特性だけを埋め込む。サーフェスが列挙されない場合に、サーフェスがサポートされていないと仮定することはない。DirectDraw が一時的なサーフェスを作成しようとして、呼び出すときにのメモリ制約のために失敗した可能性もある。このため、ドライバが実際にサーフェスをサポートしていても、これらの特性が列挙されないのである。


サーフェス特性の更新

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

既存サーフェスの特性を更新するには、IDirectDrawSurface7::SetSurfaceDesc メソッドを使う。このメソッドを使うと、DirectDrawSurface オブジェクトのサーフェス メモリのピクセル フォーマットや位置を、アプリケーションが明示的に割り当てたシステム メモリに変更できる。この機能により、サーフェスはコピーせずに、以前に割り当てたバッファのデータを使用できるようになる。新しいサーフェス メモリはクライアント アプリケーションで割り当てられる。この場合、クライアント アプリケーションでその割り当てを削除しなくてはならない。

IDirectDrawSurface7::SetSurfaceDesc メソッドを呼び出す場合、lpddsd パラメータは、新しいサーフェス メモリとそのメモリへのポインタを記述する DDSURFACEDESC2 構造体のアドレスとしなくてはならない。この構造体の中では、サーフェス メモリ、ディメンジョン、ピッチ、およびピクセル フォーマットの位置の有効メンバを反映する dwFlags メンバを設定できるだけである。したがって、dwFlags には、有効な構造体メンバを示すために設定する DDSD_WIDTH、DDSD_HEIGHT、DDSD_PITCH、DDSD_LPSURFACE、および DDSD_PIXELFORMAT フラグの組み合わせしか持てない。

構造体に値を設定する前に、サーフェスを保持するためのメモリを割り当てなくてはならない。このとき、割り当てるメモリのサイズが重要となる。サーフェスの幅や高さを適応するための十分なメモリを割り当てるだけでなく、QWORD (8 バイト) の倍数であるサーフェス ピッチの場所をとるためにも十分なものでなければならない。ピッチはピクセル単位ではなくバイト単位であることを思い出すこと。

構造体にサーフェスの値を設定する場合、lpSurface メンバは割り当てるメモリへのポインタであり、dwHeight および dwWidth メンバには、サーフェスのディメンジョンをピクセル単位で記述する。サーフェスのディメンジョンを指定するときは、サーフェス ピッチも反映させるために lPitch メンバを埋め込まなければならない。ピッチは QWORD の倍数でなくてはならない。同様に、ピッチを指定するときは、幅の値も指定する必要がある。最後に、ddpfPixelFormat メンバは、サーフェスのピクセル フォーマットを記述する。lpSurface メンバ以外でこれらのメンバに値を指定しないと、メソッドは現在のサーフェスから使用している値をデフォルトとして使う。

IDirectDrawSurface7::SetSurfaceDesc を使用する際に、注意すべき制限がある。その制限のいくつかは常識的なものである。たとえば、DDSURFACEDESC2 構造体の lpSurface メンバは、システム メモリへの有効なポインタでなくてはならない (現時点では、メソッドはビデオ メモリ ポインタをサポートしていない)。また、dwWidth および dwHeight メンバは、ゼロでない値でなくてはならない。最後に、プライマリ サーフェスや最初のフリッピング チェーンのサーフェスを再割り当てすることはできない。

複数の DirectDrawSurface オブジェクトに同一メモリを設定できる。しかし、サーフェス オブジェクトがメモリに割り当てられている間に、そのメモリの割り当てを削除しないよう注意する必要がある。

SetSurfaceDesc メソッドを正しく使用しないと、予測不可能な結果を生じる場合がある。DirectDrawSurface オブジェクトでは、このオブジェクトで割り当てていないサーフェス メモリの割り当ては削除しない。したがって、サーフェス メモリが必要でなくなった場合、プログラマが割り当てを削除する。ただし、SetSurfaceDesc が呼び出された場合、DirectDraw はサーフェスの作成時に暗に割り当てた元のサーフェス メモリを解放する。


サーフェス メモリへの直接アクセス

[C++]

フレーム バッファまたはオフスクリーン サーフェス メモリに直接アクセスするには、IDirectDrawSurface7::Lock メソッドを使う。このメソッドを呼び出す場合、lpDestRect パラメータは、直接アクセスしようとするサーフェス上の矩形を記述する RECT 構造体へのポインタとする。サーフェス全体をロックするには、lpDestRect を NULL に設定する。また、サーフェスの一部だけをカバーする RECT を指定することもできる。2 つの矩形が重ならなければ、2 つのスレッドまたは 2 つのプロセスは、サーフェスの複数の矩形を同時にロックすることができる。

Lock メソッドでは、サーフェス メモリに正しくアクセスするために必要となるすべての情報を、DDSURFACEDESC2 構造体に埋め込む。この構造体には、ピッチ (またはストライド) およびサーフェスのピクセル フォーマット (プライマリ サーフェス のピクセル フォーマットと異なる場合) に関する情報が含まれている。サーフェス メモリへのアクセスが終了すると、IDirectDrawSurface7::Unlock メソッドを呼び出して、ロックを解除する。

サーフェスをロックしている間、そのコンテンツを直接操作することができる。サーフェス メモリを直接レンダリングするときの一般的な問題を避けるためのヒントを、以下のリストで示す。

  • 一定のディスプレイ ピッチを仮定しない。常に、IDirectDrawSurface4::Lock メソッドが返すピッチ情報を調べること。このピッチは、サーフェス メモリの位置、ディスプレイ カードのタイプ、あるいは DirectDraw ドライバのバージョンといったさまざまな理由により変化する。詳細については、「幅とピッチ」を参照すること。
  • ロックを解除されたサーフェスへのブリットを確認する。ロックされたサーフェスで DirectDraw ブリット メソッドを呼び出すと、失敗して DDERR_SURFACEBUSY または DDERR_LOCKEDSURFACES を返す。同様に、ディスプレイ メモリに存在するロックされたサーフェスで GDI ブリット関数を呼び出すと、エラー値を返さずに失敗する。
  • サーフェスがロックされている間、アプリケーションのアクティビティは制限される。サーフェスがロックされている間、DirectDraw が Win16Mutex (Win16Lock ともいう) を保持している場合があるので、安全にサーフェス メモリへアクセスできる。Win16Mutex は、IDirectDrawSurface7::Lock と IDirectDrawSurface7::Unlock の呼び出しの間に Windows をシャットダウンして、GDI および USER ダイナミックリンク ライブラリへのアクセスを逐次化する。IDirectDrawSurface7::GetDC メソッドは暗に Lock を呼び出し、IDirectDrawSurface7::ReleaseDC メソッドは暗に Unlock を呼び出す。
  • ディスプレイ メモリに対して連続するデータを常にコピーする (Windows 95 および Windows 98 ではページ フォールト ハンドラ Vflatd.386 を使って、バンクスイッチ メモリを使ったディスプレイ カードに対する仮想フラットフレーム バッファを実装する。このハンドラにより、これらのディスプレイ デバイスは DirectDraw に連続したフレーム バッファを渡すことができる。ディスプレイ メモリに対して不連続のデータをコピーすると、コピーがメモリ バンクにスパンする場合に、システムが一時停止を起こす可能性がある)。

Lock メソッドの呼び出し時に DDLOCK_NOSYSLOCK フラグを含めない限り、通常はサーフェスをロックすると、DirectDraw は Win16Mutex を取得することになる。Win16Mutex の間、Windows を含むすべてのアプリケーションは実行を中止する。Win16Mutex がアプリケーションの実行を停止するので、ロック中は標準デバッガを使うことができない。ただし、カーネル デバッガはこの間も使用することができる。DirectDraw では、プライマリ サーフェスをロックする際は常に Win16Mutex を取得する。

IDirectDrawSurface7::Lock を呼び出したときにブリット中であれば、ロックを取得できないので、このメソッドは直ちにエラーを返す。このエラーを回避するには、ロックが成功して取得されるまでメソッドを待たせる DDLOCK_WAIT フラグを使う。

プライマリ サーフェスの部分ロックは、ソフトウェア カーソルの表示と衝突する。カーソルがロックされた矩形を横切る場合、カーソルはロックの継続時間の間隠される。カーソルが矩形を横切らない場合、ロックの継続時間の間固まる。サーフェス全体がロックされていると、これらのエフェクトのどちらも発生しない。

[Visual Basic]

フレーム バッファまたはオフスクリーン サーフェス メモリに直接アクセスするには、DirectDrawSurface7.Lock メソッドを使う。このメソッドを呼び出す場合、r パラメータは、直接アクセスしようとするサーフェス上の矩形を記述する RECT 型とする。サーフェス全体をロックするには、空の RECT を渡す。また、サーフェスの一部だけをカバーする RECT を指定することもできる。

Lock メソッドでは、サーフェス メモリに正しくアクセスするために必要となるすべての情報を、DDSURFACEDESC2 型に埋め込む。この型には、ピッチ (またはストライド) およびサーフェスのピクセル フォーマット (プライマリ サーフェス のピクセル フォーマットと異なる場合) に関する情報が含まれている。サーフェス メモリへのアクセスが終了すると、DirectDrawSurface7.Unlock メソッドを呼び出して、ロックを解除する。

サーフェスをロックしている間、そのコンテンツを直接操作することができる。サーフェス メモリを直接レンダリングするときの一般的な問題を避けるためのヒントを、以下のリストで示す。

  • 一定のディスプレイ ピッチを仮定しない。常に、DirectDrawSurface7.Lock メソッドが返すピッチ情報を調べること。このピッチは、サーフェス メモリの位置、ディスプレイ カードのタイプ、あるいは DirectDraw ドライバのバージョンといったさまざまな理由により変化する。詳細については、「幅とピッチ」を参照すること。
  • ロックを解除されたサーフェスへのブリットを確認する。ロックされたサーフェスで DirectDraw ブリット メソッドを呼び出すと、失敗して DDERR_SURFACEBUSY または DDERR_LOCKEDSURFACES を返す。同様に、ディスプレイ メモリに存在するロックされたサーフェスで GDI ブリット関数を呼び出すと、エラー値を返さずに失敗する。
  • サーフェスがロックされている間、アプリケーションのアクティビティは制限される。サーフェスがロックされている間、DirectDraw が Win16Mutex (Win16Lock ともいう) を保持している場合があるので、安全にサーフェス メモリへアクセスできる。Win16Mutex は、DirectDrawSurface7.Lock と DirectDrawSurface7.Unlock の呼び出しの間に Windows をシャットダウンして、GDI および USER ダイナミックリンク ライブラリへのアクセスを逐次化する。DirectDrawSurface7.GetDC メソッドは暗に Lock を呼び出し、DirectDrawSurface7.ReleaseDC メソッドは暗に Unlock を呼び出す。
  • ディスプレイ メモリに対して連続するデータを常にコピーする (Windows 95 および Windows 98 ではページ フォールト ハンドラ Vflatd.386 を使って、バンクスイッチ メモリを使ったディスプレイ カードに対する仮想フラットフレーム バッファを実装する。このハンドラにより、これらのディスプレイ デバイスは DirectDraw に連続したフレーム バッファを渡すことができる。ディスプレイ メモリに対して不連続のデータをコピーすると、コピーがメモリ バンクにスパンする場合に、システムが一時停止を起こす可能性がある)。

Lock メソッドの呼び出し時に DDLOCK_NOSYSLOCK フラグを含めない限り、通常はサーフェスをロックすると、DirectDraw は Win16Mutex を取得することになる。Win16Mutex の間、Windows を含むすべてのアプリケーションは実行を中止する。Win16Mutex がアプリケーションの実行を停止するので、ロック中は標準デバッガを使うことができない。ただし、カーネル デバッガはこの間も使用することができる。DirectDraw では、プライマリ サーフェスをロックする際は常に Win16Mutex を取得する。

DirectDrawSurface7.Lock を呼び出したときにブリット中であれば、ロックを取得できないので、このメソッドは直ちにエラーを返す。このエラーを回避するには、ロックが成功して取得されるまでメソッドを待たせる DDLOCK_WAIT フラグを使う。

プライマリ サーフェスの部分ロックは、ソフトウェア カーソルの表示と衝突する。カーソルがロックされた矩形を横切る場合、カーソルはロックの継続時間の間隠される。カーソルが矩形を横切らない場合、ロックの継続時間の間固まる。サーフェス全体がロックされていると、これらのエフェクトのどちらも発生しない。


ガンマ コントロールとカラー コントロール

ここでは、DirectDrawSurface オブジェクトで使用されるガンマ コントロールとカラー コントロール インターフェイスについて説明する。以下の項目について記述する。

  • ガンマ コントロールとカラー コントロールとは?
  • ガンマ コントロールの使用
  • カラー コントロールの使用
[C++]

注 ： 単一のサーフェスで IDirectDrawGammaControl と IDirectDrawColorControl インターフェイスの両方を使用してはならない。同時に使用してしまうと、これらのエフェクトが得られなくなる。

[Visual Basic]

注 ： 単一のサーフェスで DirectDrawGammaControl と DirectDrawColorControl インターフェイスの両方を使用してはならない。同時に使用してしまうと、これらのエフェクトが得られなくなる。


ガンマ コントロールとカラー コントロールとは?

[C++]

ガンマ コントロールとカラー コントロールから、サーフェス自体のコンテンツに影響を与えることなく、DirectDrawSurface オブジェクトでシステムがサーフェスのコンテンツを表示する方法を変更できる。これらのコントロールは、DirectDraw がスクリーン上でレンダリングされる前にサーフェスを残すのと同様、データに適用する非常に単純なフィルタと考えられる。サーフェス オブジェクトは、サーフェスのコンテンツがフィルタされるのを調節するためにメソッドを公開する IDirectDrawGammaControl、および IDirectDrawColorControl インターフェイスを実現する。どちらかのインターフェイスへのポインタを取得するには、IID_IDirectDrawGammaControl、もしくは IID_IDirectDrawColorContro 参照識別子を指定するターゲット インターフェイスの IUnknown::QueryInterface メソッドを使用する。

IDirectDrawGammaControl インターフェイスにより表されたガンマ コントロールは、システムが表示する実際のレベルにサーフェス特有の赤、緑、および青のレベル マップを動的に変更できる。ガンマ レベルを設定することで、エフェクトを付けるフレーム バッファに新しいイメージをブリットせずに、ユーザーのスクリーンにフラッシュ カラー (ユーザーの特徴を出すときの赤、新しい項目を取得するときの緑など) を適用できる。もしくは、カラー レベルを調節して、フレーム バッファのイメージにカラー バイアスを適用できる。このインターフェイスはカラー コントロール インターフェイスと似ているが、非常に使いやすいため、ゲーム アプリケーションで選択するとよい。詳細については、「ガンマ コントロールの使用」を参照すること。

IDirectDrawColorControl インターフェイスにより、テレビで見られるカラー コントロールのようなサーフェスの色を制御できる。IDirectDrawColorControl とテレビ上の実際の制御間における類似は間違いではない。つまり、このインターフェイスは、ブロードキャスト ビデオをオーバーレイ サーフェス内で見るために調節するには非常に適しているため、色以上に類似したコントロールを提供しなくてはならないことを意味する。カラー コントロールを使用すると、ユーザーは色相、飽和、コントラストなどのビデオ特性を変更できる。詳細については、「カラー コントロールの使用」を参照すること。

[Visual Basic]

ガンマ コントロールとカラー コントロールから、サーフェス自体のコンテンツに影響を与えることなく、DirectDrawSurface オブジェクトでシステムがサーフェスのコンテンツを表示する方法を変更できる。これらのコントロールは、DirectDraw がスクリーン上でレンダリングされる前にサーフェスを残すのと同様、データに適用する非常に単純なフィルタと考えられる。DirectDrawGammaControl および DirectDrawColorControl オブジェクトは、サーフェスのコンテンツがフィルタされるのを調節するためのメソッドを提供する。これらのオブジェクトは、ターゲット サーフェスの DirectDrawSurface7.GetDirectDrawColorControl および DirectDrawSurface7.GetDirectDrawGammaControl メソッドを使って作成できる。

DirectDrawGammaControl クラスにより表されたガンマ コントロールは、システムが表示する実際のレベルにサーフェス特有の赤、緑、および青のレベル マップを動的に変更できる。ガンマレベルを設定することで、エフェクトを付けるフレーム バッファに新しいイメージをブリットせずに、ユーザーのスクリーンにフラッシュカラー (ユーザーの特徴を出すときの赤、新しい項目を取得するときの緑など) を適用できる。もしくは、カラーレベルを調節して、フレーム バッファのイメージにカラーバイアスを適用できる。このインターフェイスはカラー コントロール インターフェイスと似ているが、非常に使いやすいため、ゲーム アプリケーションで選択するとよい。詳細については、「ガンマ コントロールの使用」を参照すること。

DirectDrawColorControl インターフェイスにより、テレビで見られるカラー コントロールのようなサーフェスの色を制御できる。DirectDrawColorControl とテレビ上の実際の制御間における類似は間違いではない。つまり、このインターフェイスは、TV で放映されたビデオをオーバーレイ サーフェス内で見るために調整するには非常に適しているため、色以上に類似したコントロールを提供しなくてはならないことを意味する。カラー コントロールを使用すると、ユーザーは色相、飽和、コントラストなどのビデオ特性を変更できる。詳細については、「カラー コントロールの使用」を参照すること。


ガンマ コントロールの使用

[C++]

IID_IDirectDrawGammaControl 参照識別子でサーフェスを照会することにより取得する IDirectDrawGammaControl インターフェイスでは、ディスプレイに対するデジタル-アナログ コンバータ (DAC) にピクセルが送られる前に、サーフェスからピクセルの赤、緑、および青の色成分に影響を与えるランプ レベルを操作できる。すべてのサーフェス タイプでは IDirectDrawGammaControl インターフェイスをサポートするが、プライマリ サーフェス上のガンマを調節できるだけである。プライマリ サーフェス以外のサーフェス上の IDirectDrawGammaControl::GetGammaRamp または IDirectDrawGammaControl::SetGammaRamp を呼び出そうとすると失敗する。

ここでは、ランプ レベルの一般的な概念と、IDirectDrawGammaControl のメソッドからこれらのレベルと共に作用する情報について説明する。以下の項目について記述する。

[Visual Basic]

DirectDrawSurface7.GetDirectDrawGammaControl を呼び出すことによって取得する DirectDrawGammaControl オブジェクトでは、ディスプレイに対するデジタル-アナログ コンバータ (DAC) にピクセルが送られる前に、サーフェスからピクセルの赤、緑、および青の色成分に影響を与えるランプ レベルを操作できる。すべてのサーフェス タイプでは DirectDrawGammaControl オブジェクトをサポートするが、プライマリ サーフェス上のガンマを調節できるだけである。プライマリ サーフェス以外のサーフェス上の DirectDrawGammaControl.GetGammaRamp または DirectDrawGammaControl.SetGammaRamp を呼び出そうとすると失敗する。

ここでは、ランプ レベルの一般的な概念と、DirectDrawGammaControl のメソッドからこれらのレベルと共に作用する情報について説明する。以下の項目について記述する。

  • ガンマ ランプ レベルについて
  • ガンマ ランプ サポートの検出
  • ガンマ ランプ レベルの設定と取得


カラー コントロールの使用

[C++]

IDirectDrawColorControl インターフェイスから、サーフェスのカラー コントロールを設定し取得できる。このインターフェイスは、IID_IDirectDrawColorControl 参照識別子を使用して DirectDrawSurface オブジェクトを照会することにより検索できる。

カラー コントロールの情報は DDCOLORCONTROL 構造体で表される。この構造体は、そのインターフェイスの 2 つのメソッド (IDirectDrawColorControl::SetColorControls および IDirectDrawColorControl::GetColorControls) と共に使用される。最初の構造体メンバ (dwSize) は、それを使用する前に構造体のサイズをバイト単位で設定しなくてはならない。次のメンバ (dwFlags) を使用するには、カラー コントロールを設定または取得しているかどうかによる。新しいカラー コントロールを設定している場合、dwFlags を該当するフラグの組み合わせに設定し、設定した有効データを含む他の構造体メンバのどれかを示す。ただし、カラー コントロールを取得している場合は、それを使用する前に dwFlags を設定しなくてもよい。このメンバには、IDirectDrawColorControl::GetColorControls メソッドが戻った後に、どのメンバが有効となるかを伝えるフラグを含むからである。

残りの DDCOLORCONTROL 構造体メンバには、輝度、コントラスト、色相、飽和、鮮明度、ガンマ、および使用する色かどうかを記述する値が含まれる。この構造体には、ガンマ修正についての情報があることに注意する。これは相対的な輝度に影響を与える単一のガンマ値であり、IDirectDrawGammaControl インターフェイスから提供されるガンマ調節機能と区別すること。

[Visual Basic]

DirectDrawColorControl オブジェクトから、サーフェスのカラー コントロールを設定し取得できる。このオブジェクトは、DirectDrawSurface7.GetDirectDrawColorControl を呼び出すことにより取得できる。

カラー コントロールの情報は、DDCOLORCONTROL 型で表される。この型は、そのオブジェクトの 2 つのメソッド (DirectDrawColorControl.SetColorControls および DirectDrawColorControl.GetColorControls) と共に使用される。

残りの DDCOLORCONTROL 型メンバには、輝度、コントラスト、色相、飽和、鮮明度、ガンマ、および使用する色かどうかを記述する値が含まれる。この型には、ガンマ修正についての情報があることに注意する。これは相対的な輝度に影響を与える単一のガンマ値であり、DirectDrawGammaControl インターフェイスから提供されるガンマ調節機能と区別すること。


オーバーレイ サーフェス

ここでは、DirectDraw オーバーレイ サーフェスのサポートについて説明する。次の項目について記述する。

  • オーバーレイ サーフェスの概要
  • 主要な DDCAPS メンバとフラグ
  • 転送元矩形と転送先矩形
  • 境界とサイズ アライメント
  • 最小および最大伸縮係数
  • オーバーレイ カラー キー
  • オーバーレイ サーフェスの配置
  • オーバーレイ サーフェスの作成
  • オーバーレイ Z オーダ
  • フリッピング オーバーレイ サーフェス
[C++]

オーバーレイ サーフェスの実現については、「チュートリアル 6:オーバーレイ サーフェスの使用」を参照すること。

[C++,Visual Basic]


オーバーレイ サーフェスの概要

単にオーバーレイと呼ばれるオーバーレイ サーフェスは、ハードウェアによりサポートされた特殊な能力を持つサーフェスである。オーバーレイ サーフェスは、プライマリ サーフェスにブリットしたりプライマリ サーフェスのコンテンツを変更せずに、ライブ ビデオや録画ビデオ、あるいは静止ビットマップをプライマリ サーフェス上に表示するためによく使われる。オーバーレイ サーフェスのサポートは、ハードウェアだけで提供される。DirectDraw は、ディスプレイ デバイス ドライバが報告する任意の能力をサポートする。DirectDraw は、オーバーレイ サーフェスをエミュレートしない。

オーバーレイ サーフェスは、描画したりモニタの前に配置する透明なプラスティック片に似ている。オーバーレイがモニタの前にあると、オーバーレイとプライマリ サーフェスのコンテンツを共に見ることができる。オーバーレイを削除しても、プライマリ サーフェスのコンテンツは変わらない。実際、オーバーレイの機構は、透明なプラスティックと非常によく似た動作である。オーバーレイ サーフェスを表示すると、それをどこにどのように表示するかをデバイス ドライバに伝えていることになる。ディスプレイ デバイスがモニタに走査線を描いている間、プライマリ サーフェスの各ピクセルの位置を調べて、その位置でオーバーレイを表示すべきかどうかを調べる。表示するときは、ディスプレイ デバイスが、対応するピクセルをオーバーレイ サーフェスのデータで置き換える。次にこの図を示す。

ディスプレイ アダプタはこの方法を使用して、モニタ上にプライマリ サーフェスとオーバーレイの合成画を作成し、どちらのサーフェスのコンテンツを変更することなく、透過性と伸縮エフェクトを提供する。合成されたサーフェスはビデオ ストリームに挿入され、モニタに直接送られる。この高速処理とピクセル置換はハードウェアレベルで処理されるため、オーバーレイを表示するときに著しいパフォーマンスの低下は見られない。さらに、この方法は、異なるピルセル フォーマットのあるプライマリ サーフェスとオーバーレイ サーフェスを継ぎ目なく合成することもできる。

[C++]

オーバーレイ サーフェスを作成するには、関連付けられた DDSCAPS2 構造体に DDSCAPS_OVERLAY フラグを指定し、IDirectDraw7::CreateSurface メソッドを呼び出す。オーバーレイ サーフェスはビデオ メモリだけに作成することができるため、DDSCAPS_VIDEOMEMORY フラグも含めなくてはならない。他のタイプのサーフェスと同様、該当するフラグを含めることで、単一オーバーレイまたは複数のオーバーレイ サーフェスからなるフリッピング チェーンを作成することができる。

[Visual Basic]

オーバーレイ サーフェスを作成するには、関連付けられた DDSCAPS2 型に DDSCAPS_OVERLAY フラグを指定し、DirectDraw7.CreateSurface メソッドを呼び出す。オーバーレイ サーフェスはビデオ メモリだけに作成することができるため、DDSCAPS_VIDEOMEMORY フラグも含めなくてはならない。他のタイプのサーフェスと同様、該当するフラグを含めることで、単一オーバーレイまたは複数のオーバーレイ サーフェスからなるフリッピング チェーンを作成することができる。


主要な DDCAPS メンバとフラグ

[C++]

サポートされたオーバーレイ機能についての情報を取得するには、IDirectDraw7::GetCaps メソッドを呼び出す。このメソッドは、すべての機能を記述している情報を DDCAPS 構造体に埋め込む。

ハードウェア機能を報告する場合、デバイス ドライバは dwCaps 構造体のメンバにフラグを設定し、いつ与えられたタイプの制限がハードウェアにより強制されるかを示す。ドライバの能力を取得してから、どの制限が適用するのかを dwCaps メンバのフラグで調べる。DDCAPS 構造体には、オーバーレイ サーフェスに対するハードウェア制限を記述した情報を伝達する 9 つのメンバがある。以下の表は、オーバーレイに関連したメンバと対応するフラグを示す。

メンバ | フラグ
dwMaxVisibleOverlays | このメンバは常に有効
dwCurrVisibleOverlays | このメンバは常に有効
dwAlignBoundarySrc | DDCAPS_ALIGNBOUNDARYSRC
dwAlignSizeSrc | DDCAPS_ALIGNSIZESRC
dwAlignBoundaryDest | DDCAPS_ALIGNBOUNDARYDEST
dwAlignSizeDest | DDCAPS_ALIGNSIZEDEST
dwAlignStrideAlign | DDCAPS_ALIGNSTRIDE
dwMinOverlayStretch | DDCAPS_OVERLAYSTRETCH
dwMaxOverlayStretch | DDCAPS_OVERLAYSTRETCH

dwMaxVisibleOverlays および dwCurrVisibleOverlays メンバは、ハードウェアが表示することのできるオーバーレイの最大数、およびその中で現在表示状態にある数についての情報を伝達する。

さらに、ハードウェアは dwAlignBoundarySrc、dwAlignSizeSrc、dwAlignBoundaryDest、dwAlignSizeDest、および dwAlignStrideAlign メンバにある矩形の位置やサイズ アライメントの制限を報告する。これらのメンバの値は、オーバーレイ サーフェスを表示するときに、転送元および転送先矩形のサイズや位置をどのようにするかを指示する。詳細については、「転送元矩形と転送先矩形」および「境界とサイズ アライメント」を参照すること。

また、ハードウェアは dwMinOverlayStretch および dwMaxOverlayStretch メンバの伸縮係数を報告する。詳細については、「最小および最大伸縮係数」を参照すること。

[Visual Basic]

サポートされたオーバーレイ機能についての情報を取得するには、DirectDraw7.GetCaps メソッドを呼び出す。このメソッドは、すべての機能を記述している情報を DDCAPS 型に埋め込む。

ハードウェア機能を報告する場合、デバイス ドライバは ｌCaps 構造体のメンバにフラグを設定し、いつ与えられたタイプの制限がハードウェアにより強制されるかを示す。ドライバの能力を取得してから、どの制限が適用するのかを ｌCaps メンバのフラグで調べる。DDCAPS 型には、オーバーレイ サーフェスに対するハードウェア制限を記述した情報を伝達する 9 つのメンバがある。以下の表は、オーバーレイに関連したメンバと対応するフラグを示す。

メンバ | フラグ
lMaxVisibleOverlays | このメンバは常に有効
lCurrVisibleOverlays | このメンバは常に有効
lAlignBoundarySrc | DDCAPS_ALIGNBOUNDARYSRC
lAlignSizeSrc | DDCAPS_ALIGNSIZESRC
lAlignBoundaryDest | DDCAPS_ALIGNBOUNDARYDEST
lAlignSizeDest | DDCAPS_ALIGNSIZEDEST
lAlignStrideAlign | DDCAPS_ALIGNSTRIDE
lMinOverlayStretch | DDCAPS_OVERLAYSTRETCH
lMaxOverlayStretch | DDCAPS_OVERLAYSTRETCH

ｌMaxVisibleOverlays および lCurrVisibleOverlays メンバは、ハードウェアが表示することのできるオーバーレイの最大数、およびその中で現在表示状態にある数についての情報を伝達する。

さらに、ハードウェアは lAlignBoundarySrc、lAlignSizeSrc、lAlignBoundaryDest、lAlignSizeDest、および lAlignStrideAlign メンバにある矩形の位置やサイズ アライメントの制限を報告する。これらのメンバの値は、オーバーレイ サーフェスを表示するときに、転送元および転送先矩形のサイズや位置をどのようにするかを指示する。詳細については、「転送元矩形と転送先矩形」および「境界とサイズ アライメント」を参照すること。

また、ハードウェアは lMinOverlayStretch および lMaxOverlayStretch メンバの伸縮係数を報告する。詳細については、「最小および最大伸縮係数」を参照すること。


転送元矩形と転送先矩形

[C++]

オーバーレイ サーフェスを表示するには、dwFlags パラメータに DDOVER_SHOW フラグを指定して、オーバーレイ サーフェスの IDirectDrawSurface7::UpdateOverlay メソッドを呼び出す。このメソッドでは、lpSrcRect および lpDestRect パラメータに転送元矩形と転送先矩形を指定する。転送元矩形は、プライマリ サーフェスで表示状態のオーバーレイ サーフェス上の矩形を記述する。メソッドがサーフェスすべてを使用するように要求するには、lpSrcRect パラメータを NULL に設定する。転送先矩形は、オーバーレイ サーフェスが表示されるプライマリ サーフェス部分を記述する。

[Visual Basic]

オーバーレイ サーフェスを表示するには、flags パラメータに DDOVER_SHOW フラグを指定して、DirectDrawSurface7.UpdateOverlay メソッドを呼び出す。このメソッドでは、RECT および rectD パラメータに転送元矩形と転送先矩形を指定する。転送元矩形は、プライマリ サーフェスで表示状態のオーバーレイ サーフェス上の矩形を記述する。メソッドがサーフェスすべてを使用するように要求するには、RECT パラメータに空の RECT を渡す。転送先矩形は、オーバーレイ サーフェスが表示されるプライマリ サーフェス部分を記述する。

さらに、DirectDrawSurface7.UpdateOverlayFx メソッドを呼び出すことにより、オーバーレイにエフェクトを追加することができる。ddoverfx パラメータで設定されたオーバーレイ エフェクトを使用するには、flags パラメータに DDOVER_DDFX フラグを設定しなければならない。

転送元矩形と転送先矩形は、同一サイズである必要はない。転送先矩形を転送元矩形より小さくまたは大きく指定することもでき、ハードウェアでは表示するときに適切にオーバーレイを収縮したり伸縮したりする。

オーバーレイ サーフェスを表示するには、両矩形のサイズや位置を調整しなければならないことがある。調整が必要かどうかは、デバイス ドライバの制限による。詳細については、「境界とサイズ アライメント」および「最小および最大伸縮係数」を参照すること。


境界とサイズ アライメント

[C++]

さまざまなハードウェアの制限により、デバイス ドライバによっては、オーバーレイ サーフェスを表示するために使用する転送元および転送先矩形の位置やサイズに制限を受ける場合がある。デバイスに対してどの制限があてはまるかを知るには、IDirectDraw7::GetCaps メソッドを呼び出してから、DDCAPS 構造体の dwCaps メンバにオーバーレイ関連のフラグを調べる。次の表で境界とサイズ アライメントに特有なメンバとフラグを示す。

カテゴリ | フラグ | メンバ
境界 (位置) 制限 | DDCAPS_ALIGNBOUNDARYSRC | dwAlignBoundarySrc
 | DDCAPS_ALIGNBOUNDARYDEST | dwAlignBoundaryDest
サイズ制限 | DDCAPS_ALIGNSIZESRC | dwAlignSizeSrc
 | DDCAPS_ALIGNSIZEDEST | dwAlignSizeDest

制限には、境界制限とサイズ制限の 2 つのタイプがある。両タイプの制限ともピクセル (バイトではない) で表され、転送元および転送先矩形に適用することができる。また、これらの制限は、オーバーレイやプライマリ サーフェスのピクセル フォーマットによりさまざまである。

境界制限は、転送元および転送先矩形をどこに配置できるかに影響を与える。dwAlignBoundarySrc および dwAlignBoundaryDest メンバの値は、対応する矩形の左上角のアライメントを伝える。矩形の左上角の x 座標 (RECT 構造体の left メンバ) は、報告された値の倍数でなければならない。

サイズ制限は、転送元および転送先矩形の有効な幅に影響を与える。dwAlignSizeSrc および dwAlignSizeDest メンバの値は、対応する矩形の幅のアライメントをピクセル単位で伝える。矩形は、報告された値の倍数のピクセル幅を持たなければならない。要求された最小の伸縮係数に従うために矩形を伸縮する場合、常に伸縮された矩形のサイズがなお連続されていなければならない。矩形を伸縮した後、最小伸縮係数を保持するためには、幅のアライメントを切り捨てるのではなく切り上げる。詳細については、「最小および最大伸縮係数」を参照すること。

[Visual Basic]

さまざまなハードウェアの制限により、デバイス ドライバによっては、オーバーレイ サーフェスを表示するために使用する転送元および転送先矩形の位置やサイズに制限を受ける場合がある。デバイスに対してどの制限があてはまるかを知るには、DirectDraw7.GetCaps メソッドを呼び出してから、DDCAPS 型の lCaps メンバにオーバーレイ関連のフラグを調べる。次の表で境界とサイズ アライメントに特有なメンバとフラグを示す。

カテゴリ | フラグ | メンバ
境界 (位置) 制限 | DDCAPS_ALIGNBOUNDARYSRC | lAlignBoundarySrc
 | DDCAPS_ALIGNBOUNDARYDEST | lAlignBoundaryDest
サイズ制限 | DDCAPS_ALIGNSIZESRC | lAlignSizeSrc
 | DDCAPS_ALIGNSIZEDEST | lAlignSizeDest

制限には、境界制限とサイズ制限の 2 つのタイプがある。両タイプの制限ともピクセル (バイトではない) で表され、転送元および転送先矩形に適用することができる。また、これらの制限は、オーバーレイやプライマリ サーフェスのピクセル フォーマットによりさまざまである。

境界制限は、転送元および転送先矩形をどこに配置できるかに影響を与える。lAlignBoundarySrc および lAlignBoundaryDest メンバの値は、対応する矩形の左上角のアライメントを伝える。矩形の左上角の x 座標 (RECT 型の left メンバ) は、報告された値の倍数でなければならない。

サイズ制限は、転送元および転送先矩形の有効な幅に影響を与える。lAlignSizeSrc および lAlignSizeDest メンバの値は、対応する矩形の幅のアライメントをピクセル単位で伝える。矩形は、報告された値の倍数のピクセル幅を持たなければならない。要求された最小の伸縮係数に従うために矩形を伸縮する場合、常に伸縮された矩形のサイズがなお連続されていなければならない。矩形を伸縮した後、最小伸縮係数を保持するためには、幅のアライメントを切り捨てるのではなく切り上げる。詳細については、「最小および最大伸縮係数」を参照すること。


最小および最大伸縮係数

[C++]

ハードウェアの制限により、デバイスによっては、対応する転送元矩形と比較して転送先矩形の幅が制限を受ける場合がある。DirectDraw は、これらの制限を伸縮係数として伝える。伸縮係数とは、転送元矩形と転送先矩形の幅の比率である。ドライバが伸縮係数についての情報を提供する場合、IDirectDraw7::GetCaps メソッドを呼び出した後、ドライバは DDCAPS 構造体に DDCAPS_OVERLAYSTRETCH フラグを設定する。伸縮係数は 1000 を掛けて報告されるため、1300 の値は実際には 1.3 を意味することに注意する (750 は 0.75 になる)。

[Visual Basic]

ハードウェアの制限により、デバイスによっては、対応する転送元矩形と比較して転送先矩形の幅が制限を受ける場合がある。DirectDraw は、これらの制限を伸縮係数として伝える。伸縮係数とは、転送元矩形と転送先矩形の幅の比率である。ドライバが伸縮係数についての情報を提供する場合、DirectDraw7.GetCaps メソッドを呼び出した後、ドライバは DDCAPS 型に DDCAPS_OVERLAYSTRETCH フラグを設定する。伸縮係数は 1000 を掛けて報告されるため、1300 の値は実際には 1.3 を意味することに注意する (750 は 0.75 になる)。

オーバーレイ転送先矩形の伸縮や収縮に制限を受けないデバイスでは、最小および最大伸縮係数 0 を報告する場合がある。

最小伸縮係数は、転送先矩形が転送元矩形と比較してどの程度幅が広くなければならないか、または狭くなければならないかを伝える。最小伸縮係数が 1000 よりも大きければ、その比率だけ転送先矩形の幅を広げなければならない。たとえば、ドライバが 1300 を報告すると、転送先矩形の幅が転送元矩形の幅の少なくとも 1.3 倍になるようにしなければならない。同様に、最小伸縮係数が 1000 よりも小さければ、転送先矩形は転送元矩形よりもその比率だけ小さくなる可能性があることを示す。

最大伸縮係数は、転送先矩形の幅を伸縮することのできる最大比率を伝える。たとえば、最大伸縮係数が 2000 の場合、転送先矩形は転送元矩形の 2 倍まで (2 倍を超えない) の幅を指定することができる。最大伸縮係数が 1000 よりも小さい場合、オーバーレイを表示するために転送先矩形の幅をその比率だけ収縮しなければならない。

伸縮した後、転送先矩形はデバイスの要求するサイズ アライメント制限に従う必要がある。このため、サイズ アライメントする前に転送先矩形を伸縮するとよい。詳細については、「境界とサイズ アライメント」を参照すること。

ハードウェアでは、転送先矩形の高さを調整しなくてもいい。アスペクト比を保持するため、ネガティブな結果を引き起こすことなく転送先矩形の高さを増やすことができる。


オーバーレイ カラー キー

[C++]

他のタイプのサーフェスと同様、オーバーレイ サーフェスは、サーフェス間の透過型ブリット処理を制御するための転送元および転送先カラー キーを使用する。オーバーレイ サーフェスはブリットで表示されないので、IDirectDrawSurface7::UpdateOverlay メソッドを呼び出すときに、プライマリ サーフェス上へのオーバーレイ サーフェス表示方法を制御するには、別の方法が必要となる。これは、オーバーレイ カラー キーにより埋め込まれる。オーバーレイ カラー キーには、そのブリット関連の対応するカラー キーと同様、IDirectDrawSurface7::SetColorKey メソッドを呼び出して設定する転送元のバージョンと転送先のバージョンがある (詳細については、「カラー キーの設定」を参照すること)。転送元または転送先オーバーレイ カラー キーを設定するには、DDCKEY_SRCOVERLAY または DDCKEY_DESTOVERLAY フラグを使用する。オーバーレイ サーフェスは、ブリットとオーバーレイ カラー キーの両方を使い、ブリット処理とオーバーレイ表示処理を適切に制御することができる。2 つのタイプのカラー キーは、互いに矛盾し合うことはない。

IDirectDrawSurface7::UpdateOverlay メソッドは、転送元オーバーレイ カラー キーを用いて、プライマリ サーフェスのコンテンツが見えるように、オーバーレイ サーフェスのどのピクセルが透明であるべきかを決める。同様に、このメソッドは転送先オーバーレイ カラー キーを用いて、表示するときにオーバーレイ サーフェスにより隠蔽されるプライマリ サーフェス部分を決める。この結果として生じるビジュアル エフェクトは、ブリット関連のカラー キーにより作成されるエフェクトと同じである。

[Visual Basic]

他のタイプのサーフェスと同様、オーバーレイ サーフェスは、サーフェス間の透過型ブリット処理を制御するための転送元および転送先カラー キーを使用する。オーバーレイ サーフェスはブリットで表示されないので、DirectDrawSurface7.UpdateOverlay メソッドを呼び出すときに、プライマリ サーフェス上へのオーバーレイ サーフェス表示方法を制御するには、別の方法が必要となる。これは、オーバーレイ カラー キーにより埋め込まれる。オーバーレイ カラー キーは、そのブリット関連の対応するカラー キーと同様、DirectDrawSurface7.SetColorKey メソッドを呼び出して設定する転送元のバージョンと転送先のバージョンがある (詳細については、「カラー キーの設定」を参照すること)。転送元または転送先オーバーレイ カラー キーを設定するには、DDCKEY_SRCOVERLAY または DDCKEY_DESTOVERLAY フラグを使用する。オーバーレイ サーフェスは、ブリットとオーバーレイ カラー キーの両方を使い、ブリット処理とオーバーレイ表示処理を適切に制御することができる。2 つのタイプのカラー キーは、互いに矛盾し合うことはない。

DirectDrawSurface7.UpdateOverlay メソッドは、転送元オーバーレイ カラー キーを用いて、プライマリ サーフェスのコンテンツが見えるように、オーバーレイ サーフェスのどのピクセルが透明であるべきかを決める。同様に、このメソッドは転送先オーバーレイ カラー キーを用いて、表示するときにオーバーレイ サーフェスにより隠蔽されるプライマリ サーフェス部分を決める。この結果として生じるビジュアル エフェクトは、ブリット関連のカラー キーにより作成されるエフェクトと同じである。


オーバーレイ サーフェスの配置

[C++]

IDirectDrawSurface7::UpdateOverlay メソッドを呼び出して最初にオーバーレイを表示した後、IDirectDrawSurface7::SetOverlayPosition メソッドを呼び出して転送先矩形を更新することができる。

指定した位置がハードウェアにより強制される境界アライメント制限に従っていることを確認する。詳細については、「境界とサイズ アライメント」を参照すること。また、SetOverlayPosition はクリッピングを行わないことを思い出すこと。したがって、オーバーレイがターゲット サーフェスの縁をはみ出る可能性のある座標を使用すると、メソッドは失敗して DDERR_INVALIDPOSITION を返す。

[Visual Basic]

DirectDrawSurface7.UpdateOverlay メソッドを呼び出して最初にオーバーレイを表示した後、DirectDrawSurface7.SetOverlayPosition メソッドを呼び出して転送先矩形を更新することができる。

指定した位置がハードウェアにより強制される境界アライメント制限に従っていることを確認する。詳細については、「境界とサイズ アライメント」を参照すること。また、SetOverlayPosition はクリッピングを行わないことを思い出すこと。したがって、オーバーレイがターゲット サーフェスの縁をはみ出る可能性のある座標を使用すると、メソッドは失敗して DDERR_INVALIDPOSITION を返す。


オーバーレイ サーフェスの作成

[C++]

すべてのサーフェスと同様、IDirectDraw7::CreateSurface メソッドを呼び出してオーバーレイ サーフェスを作成できる。オーバーレイを作成するには、関連付けらた DDSCAPS2 構造体に DDSCAPS_OVERLAY フラグを含める。

オーバーレイのサポートは、ディスプレイ デバイスによって実にさまざまである。そのため、与えられたピクセル フォーマットが大部分のドライバでサポートされるのかどうかの保証はない。したがって、さまざまなピクセル フォーマットを処理する準備をしておかなければならない。ドライバでサポートする非 RGB フォーマットについての情報は、IDirectDraw7::GetFourCCCodes メソッド呼び出して要求することができる。

[Visual Basic]

すべてのサーフェスと同様、DirectDraw7.CreateSurface メソッドを呼び出してオーバーレイ サーフェスを作成できる。オーバーレイを作成するには、関連付けらた DDSCAPS2 型に DDSCAPS_OVERLAY フラグを含める。

オーバーレイのサポートは、ディスプレイ デバイスによって実にさまざまである。そのため、与えられたピクセル フォーマットが大部分のドライバでサポートされるのかどうかの保証はない。したがって、さまざまなピクセル フォーマットを処理する準備をしておかなければならない。ドライバでサポートする非 RGB フォーマットについての情報は、DirectDraw7.GetFourCCCodes メソッド呼び出して要求することができる。

オーバーレイ サーフェスを作成しようとする場合、最適なピクセル フォーマットでサーフェスを作成するようにし、与えられたピクセル フォーマットがサポートされていない場合は、他のピクセル フォーマットにする。

オーバーレイ サーフェス フリッピング チェーンを作成できる。詳細については、「複合サーフェスとフリッピング チェーンの作成」を参照すること。


オーバーレイ Z オーダ

[C++]

オーバーレイ サーフェスは、他のスクリーン コンポーネントすべての上位に位置するものと仮定されている。しかし、複数のオーバーレイ サーフェスを表示する場合、これらのオーバーレイをビジュアルに整える何らかの方法が必要になる。DirectDraw ではオーバーレイ Z オーダをサポートし、オーバーレイが互いにクリップする順序を管理する。Z オーダの値は、プライマリ サーフェスから見る人までの概念距離を表す。その値は、プライマリ サーフェスのすぐ上の 0 から、見る人のできるだけ近くにある 40 億までの範囲となる。いかなるオーバーレイでも、同一の Z オーダを共用することはできない。Z オーダの値を設定するには、IDirectDrawSurface7::UpdateOverlayZOrder メソッドを呼び出す。

転送先カラー キーは、プライマリ サーフェスのビットだけに影響され、他のオーバーレイに遮られたオーバーレイには影響されない。転送元カラー キーは、Z オーダがオーバーレイに対して指定されているかどうかに関わりなくそこで作用する。

指定された Z オーダのないオーバーレイは、Z オーダが 0 であるとみなされる。指定された Z オーダのないオーバーレイは、プリイマリ サーフェス上の同じ領域にオーバーレイすると、予測不可能な動作が生じる。

DirectDraw オブジェクトは、他のアプリケーションによって表示されたオーバーレイの Z オーダーを調査しない。

注 ： WM_KILLFOCUS メッセージに対する応答で UpdateOverlayZOrder を呼び出すことにより、複数のオーバーレイ サーフェスにおける以前のクリッピングを確保できる。このメッセージを受け取る場合、DDOVERZ_SENDTOBACK に設定する dwFlags パラメータで UpdateOverlayZOrder メソッドを呼び出し、オーバーレイ サーフェスを最後の Z オーダー位置に設定する。

[Visual Basic]

オーバーレイ サーフェスは、他のスクリーン コンポーネントすべての上位に位置するものと仮定されている。しかし、複数のオーバーレイ サーフェスを表示する場合、これらのオーバーレイをビジュアルに整える何らかの方法が必要になる。DirectDraw ではオーバーレイ Z オーダをサポートし、オーバーレイが互いにクリップする順序を管理する。Z オーダの値は、プライマリ サーフェスから見る人までの概念距離を表す。その値は、プライマリ サーフェスのすぐ上の 0 から、見る人のできるだけ近くにある 40 億までの範囲となる。いかなるオーバーレイでも、同一の Z オーダを共用することはできない。Z オーダの値を設定するには、DirectDrawSurface7.UpdateOverlayZOrder メソッドを呼び出す。

転送先カラー キーは、プライマリ サーフェスのビットだけに影響され、他のオーバーレイに遮られたオーバーレイには影響されない。転送元カラー キーは、Z オーダがオーバーレイに対して指定されているかどうかに関わりなくそこで作用する。

指定された Z オーダのないオーバーレイは、Z オーダが 0 であるとみなされる。指定された Z オーダのないオーバーレイは、プリイマリ サーフェス上の同じ領域にオーバーレイすると、予測不可能な動作が生じる。

DirectDraw オブジェクトは、他のアプリケーションによって表示されたオーバーレイの Z オーダーを調査しない。

注 ： WM_KILLFOCUS メッセージに対する応答で UpdateOverlayZOrder を呼び出すことにより、複数のオーバーレイ サーフェスにおける以前のクリッピングを確保できる。このメッセージを受け取る場合、DDOVERZ_SENDTOBACK に設定する dwFlags パラメータで UpdateOverlayZOrder メソッドを呼び出し、オーバーレイ サーフェスを最後の Z オーダー位置に設定する。


フリッピング オーバーレイ サーフェス

[C++]

他のタイプのサーフェスと同様に、オーバーレイ フリッピング チェーンを作成できる。オーバーレイ フリッピング チェーンを作成した後、IDirectDrawSurface7::Flip メソッドを呼び出してフリッピングを行う。詳細については、「フリッピング サーフェス」を参照すること。

オーバーレイ サーフェス付きのビデオを表示するソフトウェア デコーダは、DDFLIP_ODD や DDFLIP_EVEN フラグを使用して、人工的な動きを減らす機能の Flip メソッドを呼び出す。ドライバが奇偶フリッピングをサポートするとき、ドライバ能力を取得した後で、DDCAPS 構造体に DDCAPS2_CANFLIPODDEVEN フラグが設定される。そのフラグが設定される場合、IDirectDrawSurface7::UpdateOverlay メソッドを呼び出すときに DDOVER_BOB フラグを使用すると、人工的な動きを最小化するために "Bob" アルゴリズムを使うようドライバに指定できる。その後、DDFLIP_ODD または DDFLIP_EVEN フラグを指定して Flip を呼び出す場合、ドライバはジッタリング異常を補正するために自動的にオーバーレイ転送元矩形を調整する。

[Visual Basic]

他のタイプのサーフェスと同様に、オーバーレイ フリッピング チェーンを作成できる。オーバーレイ フリッピング チェーンを作成した後、DirectDrawSurface7.Flip メソッドを呼び出してフリッピングを行う。詳細については、「フリッピング サーフェス」を参照すること。

オーバーレイ サーフェス付きのビデオを表示するソフトウェア デコーダは、DDFLIP_ODD や DDFLIP_EVEN フラグを使用して、人工的な動きを減らす機能の Flip メソッドを呼び出す。ドライバが奇偶フリッピングをサポートするとき、ドライバ能力を取得した後で、DDCAPS 型に DDCAPS2_CANFLIPODDEVEN フラグが設定される。そのフラグが設定される場合、DirectDrawSurface7.UpdateOverlay メソッドを呼び出すときに DDOVER_BOB フラグを使用すると、人工的な動きを最小化するために "Bob" アルゴリズムを使うようドライバに指定できる。その後、DDFLIP_ODD または DDFLIP_EVEN フラグを指定して Flip を呼び出す場合、ドライバはジッタリング異常を補正するために自動的にオーバーレイ転送元矩形を調整する。

ハードウェア能力を取得するときに、ドライバが DDCAPS2_CANFLIPODDEVEN フラグを設定していない場合、DDOVER_BOB フラグを指定した UpdateOverlay は失敗する。

Bob アルゴリズムについては、「共通のビデオの問題の回避方法」を参照すること。


圧縮したテクスチャ サーフェス

[C++]

サーフェスには、3D オブジェクトのテクスチャリングに対して使用するビットマップを含めることができる。サーフェスを作成する場合は、DDSCAPS 構造体の dwFlags メンバに DDSCAPS_TEXTURE フラグを指定しなくてはならない。

[Visual Basic]

サーフェスには、3D オブジェクトのテクスチャリングに対して使用するビットマップを含めることができる。サーフェスを作成する場合は、DDSCAPS2 型の lCaps メンバに DDSCAPS_TEXTURE フラグを指定しなくてはならない。

Direct3D 直接モードにおけるテクスチャリングの使用については、Direct3D 直接モードの「テクスチャ」を参照すること。

テクスチャにより消費されるメモリ容量を削除するために、DirectDraw ではテクスチャ サーフェスの圧縮をサポートする。

いくつかの Direct3D デバイスは、圧縮したテクスチャ サーフェスをネイティブにサポートする。このようなデバイスで圧縮したサーフェスを作成し、そのデバイスにデータをロードしてしまえば、他のテクスチャ サーフェスと同様に Direct3D でサーフェスを使用できる。テクスチャが 3D サーフェス オブジェクトにマップされる場合、Direct3D は圧縮の復元を処理する。

他のデバイスでは、圧縮したテクスチャ サーフェスを最初からサポートしない。このようなデバイスを使用すると、圧縮したサーフェスを使用して、ディスク上のテクスチャや現在使用中のメモリ以外にロードされるテクスチャを表現するときに役立つことに気づくであろう。Direct3D にテクスチャを与える前に、DirectDraw を使用して圧縮したテクスチャを圧縮していないフォーマットに変換できる。

DirectDraw のテクスチャ圧縮については、次の項目を参照すること。

  • 圧縮したテクスチャの作成
  • 圧縮したテクスチャの復元
  • 圧縮したテクスチャへのブリットにおける透過性
  • 圧縮したテクスチャ フォーマット

Direct3D 直接モードで圧縮したテクスチャの使用については、Direct3D 直接モードの「テクスチャ圧縮」を参照すること。


圧縮したテクスチャの作成

[C++]

サーフェスの作成時に DDSURFACEDESC2 構造体に圧縮したテクスチャ サーフェスを記述するには、次に示すステップを行うこと。

  • あらゆるテクスチャと同様に、DDSCAPS 構造体の dwFlags メンバに DDSCAPS_TEXTURE フラグを指定する。
  • DDPIXELFORMAT 構造体の dwFourCC メンバを後で記述される DXT コードの 1 つに設定する。
  • DDPIXELFORMAT の dwFlags メンバに DDPF_FOURCC を含める。DDPF_RGB フラグを設定してはいけない。
  • 4 の倍数のピクセルの幅と高さを指定する。

イメージ データを圧縮したテクスチャ サーフェスにロードするには、2 通りの方法がある。

  • 一般的な RGB または ARGB サーフェスを作成し、そのサーフェスに一般的なビットマップをロードする。そして、IDirectDrawSurface7::Blt または IDirectDrawSurface7::BltFast を使用して、圧縮していないサーフェスから圧縮したサーフェスへブリットする。DirectDraw が圧縮を行う。
  • ファイルから圧縮したデータをロードし、サーフェス メモリにそのデータを直接コピーする (「サーフェス メモリへの直接アクセス」を参照すること)。SDK で提供される DirectX Texture ツール (Dxtex.exe) を使用すると、圧縮したテクスチャ (DDS) ファイルの作成と変換を行える。また、各自の DDS ファイルを作成できたり、圧縮したサーフェスからデータをコピーするか、各自のルーチンを使用して一般的なビットマップ データを圧縮したフォーマットの 1 つに変換できる。

注 ： 圧縮したサーフェスで IDirectDrawSurface7::Lock または IDirectDrawSurface7::GetSurfaceDesc を呼び出す場合、DDSD_LINEARSIZE フラグが DDSURFACEDESC 構造体の dwFlags メンバに設定されており、dwLinearSize メンバに圧縮したサーフェス データを含むために割り当てられたバイト数が含まれていなくてはならない。dwLinearSize パラメータは lPitch パラメータとの共用体なので、これらのパラメータは DDSD_LINEARSIZE および DDSD_PITCH フラグのように相互に排他となる。

[Visual Basic]

サーフェスの作成時に DDSURFACEDESC2 型に圧縮したテクスチャ サーフェスを記述するには、次に示すステップを行うこと。

  • あらゆるテクスチャと同様に、DDSCAPS2 型の lCaps メンバに DDSCAPS_TEXTURE フラグを指定する。
  • DDPIXELFORMAT 型の lFourCC メンバを後で記述される DXT コードの 1 つに設定する。
  • DDPIXELFORMAT の lFlags メンバに DDPF_FOURCC を含める。DDPF_RGB フラグを設定してはいけない。
  • 4 の倍数のピクセルの幅と高さを指定する。

イメージ データを圧縮したテクスチャ サーフェスにロードするには、2 通りの方法がある。

  • 一般的な RGB または ARGB サーフェスを作成し、そのサーフェスに一般的なビットマップをロードする。そして、DirectDrawSurface7.Blt または DirectDrawSurface7.BltFast を使用して、圧縮していないサーフェスから圧縮したサーフェスへブリットする。DirectDraw が圧縮を行う。
  • ファイルから圧縮したデータをロードし、サーフェス メモリにそのデータを直接コピーする (「サーフェス メモリへの直接アクセス」を参照すること)。SDK で提供される DirectX Texture ツール (Dxtex.exe) を使用すると、圧縮したテクスチャ (DDS) ファイルの作成と変換を行える。また、各自の DDS ファイルを作成できたり、圧縮したサーフェスからデータをコピーするか、各自のルーチンを使用して一般的なビットマップ データを圧縮したフォーマットの 1 つに変換できる。

注 : 圧縮したサーフェスで DirectDrawSurface7.Lock または DirectDrawSurface7.GetSurfaceDesc を呼び出す場合、DDSD_LINEARSIZE フラグが DDSURFACEDESC2 型の lFlags メンバに設定されており、lLinearSize メンバに圧縮されたサーフェス データを含むために割り当てられたバイト数が含まれていなくてはならない。lLinearSize パラメータは lPitch パラメータとの共用体なので、これらのパラメータは DDSD_LINEARSIZE および DDSD_PITCH フラグのように相互に排他となる。

この利点は、アプリケーション自体で特定のフォーマットに対するサーフェスの特定の幅と高さに必要なストレージ容量を計算せずに、圧縮したサーフェスのコンテンツをファイルにコピーできることにある。

圧縮したテクスチャの 5 つのタイプを以下の表に示す。データが格納される方法 (各自で圧縮ルーチンを記述する場合だけに必要となる) の詳細については、「圧縮したテクスチャ フォーマット」を参照すること。

FOURCC | 説明 | アルファ値事前掛け算済み?
DXT1 | 不透明/1 ビット アルファ | n/a
DXT2 | 明示的なアルファ | Yes
DXT3 | 明示的なアルファ | No
DXT4 | 補間したアルファ | Yes
DXT5 | 補間したアルファ | No

注 ： 値事前掛け算済みではないフォーマットから値事前掛け算済みのフォーマットにブリットする場合、DirectDraw はアルファ値を基に色をスケールする。値事前掛け算済みのファーマットから値事前掛け算済みではないフォーマットへのブリットはサポートされない。値事前掛け算済みのアルファ転送元から値事前掛け算済みではないアルファ転送先へのブリットを試すと、メソッドが DDERR_INVALIDPARAMS を返す値事前掛け算済みのアルファ転送元からアルファのない転送先へブリットすると、アルファでスケールされる転送元色成分は同様にコピーされる。


圧縮したテクスチャの復元

テクスチャ サーフェスの圧縮と同様、圧縮したテクスチャの復元は DirectDraw ブリット サービスから行える。HEL がシステム メモリ間の圧縮を復元するブリットを行うため、これらは常にサポートされる。同様に、HEL では管理下のテクスチャのブリットを常に実行する (DDSCAPS2_TEXTUREMANAGE 能力)。これ以外の状況には、次の段落で示す制限がある。

転送先サーフェスに DDSCAPS_OFFSCREENPLAIN 能力があれば、ドライバがビデオ メモリ サーフェスの作成をサポートし、圧縮したビデオ メモリ サーフェスから圧縮していないビデオやシステム メモリ サーフェスへのブリットにおける圧縮の復元を行う。

圧縮したシステム メモリ サーフェスから圧縮していないビデオ メモリ サーフェスへのブリットは多くの場合サポートされず、ドライバが圧縮したテクスチャをサポートする場合でもサポートされない。これは、圧縮したシステム メモリ サーフェスの圧縮の復元と、ビデオ メモリ サーフェスへのコンテンツの移動が不可能であることを示しているわけではない。単に、追加のステップを必要とするだけである。

ビデオ メモリへのシステム メモリ サーフェスの圧縮の復元

  1. 必要なディメンジョンとピクセル フォーマットのシステム メモリに、圧縮していないオフスクリーン プレーン サーフェスを作成する。
  2. 圧縮したシステム メモリ サーフェスから圧縮していないシステム メモリ サーフェスにブリットする (この場合、DirectDraw HEL が圧縮の復元を実行する)。
  3. 圧縮していないサーフェスから圧縮していないビデオ メモリ サーフェスにブリットする。


圧縮したテクスチャへのブリットにおける透過性

DirectDraw では、プレーン RGB サーフェスからアルファ付きの圧縮したテクスチャを作成する特別なトリックを提供する。転送元カラー キーが転送元 RGB サーフェスで提供される場合、DirectDraw は転送先の色の全ピクセルに 0 のアルファ値を割り当てる。DXT1 テクスチャはピクセルごとに 1 ビットのアルファ情報だけを所有するため、この技術は DXT1 テクスチャの作成に特に役立つ。

注 ： この技術を制御するためにフラグは必要ない。圧縮したテクスチャにあらゆる透過性の必要がない場合は、転送元サーフェスに転送元カラー キーを設定しないこと。


圧縮したテクスチャ フォーマット

ここでは、圧縮したテクスチャ フォーマットの内部組織について説明する。圧縮したテクスチャを使用する場合、DirectDraw が圧縮したテクスチャ間の変換を処理するため、これらの情報を詳しく知る必要はない。しかし、圧縮したサーフェスデータを直接処理する場合は、この情報が役立つはずである。

DirectDraw では、テクスチャ マップを 4 × 4 のテクセル ブロックに分割するために圧縮フォーマットを使用する。テクスチャに透過性が含まれない場合 (不透明)、または透過性が 1 ビット アルファで指定される場合、8 バイト ブロックがテクスチャ マップ ブロックを現す。テクスチャ マップに透過型テクセルが含まれない場合、アルファ チャネルを使用して 16 バイト ブロックがテクスチャ マップ ブロックを現す。

この 2 つのフォーマットについては、次のセクションで説明する。

  • 不透明と 1 ビット アルファ テクスチャ
  • アルファ チャネルによるテクスチャ

注 ： あらゆる単一のテクスチャでは、16 テクセルのグループごとに 64 ビットまたは 128 ビットとして格納されるデータを指定しなくてはならない。64 ビット ブロック (つまり、フォーマット DXT1) がテクスチャ用に使用される場合、いくつかのテクスチャのブロックごとに不透明と 1 ビット アルファ フォーマットを組み合わせることができる。つまり、色 0 と色 1 の符号なし整数の大きさの比較は、16 テクセルの各ブロックごとに実行される。

128 ビット ブロックを使用する場合、テクスチャ全体にアルファ チャネルを明示的 (フォーマット DXT2 または DXT3) または補間したモード (フォーマット DXT4 または DXT5) で指定しなくてはならない。色も同様に、補間したモードが 8 の補間したアルファか、ブロックを基に使用される 6 の補間したアルファモードのどちらかを選択されることに注意すること。さらに、アルファ 0 とアルファ 1 の大きさの比較は、ブロックごとに行われる。


プライベート サーフェス データ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

サーフェスと共にあらゆる種類のアプリケーション固有データを格納できる。たとえば、ゲームのマップを示すサーフェスには、地域情報を含む場合がある。

サーフェスでは、1 つ以上のプライベート データ バッファを所有できる。各バッファは、サーフェスにデータをアタッチする際に指定する GUID で識別される。

プライベート サーフェス データを格納するには、IDirectDrawSurface7::SetPrivateData メソッドを使用する。このメソッドは、転送元バッファ、データのサイズ、データ用にアプリケーションで定義した GUID へのポインタを渡す。随意に、転送元データは COM オブジェクトのフォームに存在できる。この場合、オブジェクトの lUnknown インターフェイス ポインタにポインタを渡し、DDSPD_IUNKNOWNPOINTER フラグを設定する。他のフラグ (DDSPD_VOLATILE) は、サーフェスのコンテンツを変更しない限り有効なサーフェスにデータがアタッチされていることを示す (詳細については、「サーフェス固有値」を参照すること)。

SetPrivateData はデータに対して内部バッファを割り当て、データをコピーする。その後で、転送元バッファまたはオブジェクトを安全に解放できる。内部バッファまたはインターフェイス参照は、IDirectDrawSurface7::FreePrivateData の呼び出し時に解放される。サーフェスが解放されると、この処理は自動的に発生する。

サーフェスに対するプライベートデータを取得するには、正確なサイズのバッファを割り当て、SetPrivateData でデータに割り当てられた GUID を渡す IDirectDrawSurface7::GetPrivateData メソッドを呼び出さなくてはならない。このバッファを使用するあらゆる動的メモリの解放については、各自で責任を持つ。データが COM オブジェクトの場合、このメソッドは Iunknown ポインタを取得する。

割り当てるバッファのサイズが分からない場合、最初に *lpcbBufferSize にゼロを入れて GetPrivateData を呼び出す。このメソッドが DDERR_MOREDATA で失敗した場合、*lpcbBufferSize に必要なバイト数を返す。


サーフェス固有値

[C++]

サーフェスの固有値により、サーフェスが変更したかどうかを決定できる。DirectDraw がサーフェスを作成する場合、DirectDraw では IDirectDrawSurface7::GetUniquenessValue メソッドを使用して取得し格納できる固有値を割り当てる。そして、サーフェスが変更したかどうかを決定するときは常に、このメソッドを再び呼び出し、古い値に対して新しい値を比較する。値が異なる場合、サーフェスは変更している。

GetUniquenessValue により返される真の値が 0 でない限り、値は不適切となる。DirectDraw がサーフェスが制御以上のプロセスで変更されたことに気づくと、サーフェスにこの値を割り当てる。GetUniquenessValue が 0 を返すと、単にサーフェスの状態が未確定であるが分かる。

サーフェスの固有値を変更するために、アプリケーションは IDirectDrawSurface7::ChangeUniquenessValue メソッドを使用できる。たとえば、サーフェス自体を変更せずにサーフェスの固有値を変更するアプリケーションまたはコンポーネントからこのメソッドが呼び出され、変更の他のいくつかのプロセスに通知する。しかし、大部分のアプリケーションでは固有値の変更の必要はない。

[Visual Basic]

サーフェスの固有値により、サーフェスが変更したかどうかを決定できる。DirectDraw がサーフェスを作成する場合、DirectDraw では DirectDrawSurface7.GetUniquenessValue メソッドを使用して取得し格納できる固有値を割り当てる。そして、サーフェスが変更したかどうかを決定するときは常に、このメソッドを再び呼び出し、古い値に対して新しい値を比較する。値が異なる場合、サーフェスは変更している。

GetUniquenessValue により返される真の値が 0 でない限り、値は不適切となる。DirectDraw がサーフェスが制御以上のプロセスで変更されたことに気づくと、サーフェスにこの値を割り当てる。GetUniquenessValue が 0 を返すと、単にサーフェスの状態が未確定であるが分かる。

サーフェスの固有値を変更するために、アプリケーションは DirectDrawSurface7.ChangeUniquenessValue メソッドを使用できる。たとえば、サーフェス自体を変更せずにサーフェスの固有値を変更するアプリケーションまたはコンポーネントからこのメソッドが呼び出され、変更の他のいくつかのプロセスに通知する。しかし、大部分のアプリケーションでは固有値の変更の必要はない。


非ローカル ビデオ メモリ サーフェスの使用

DirectDraw は、非ローカル ビデオ メモリでサーフェスを作成するために AGP (Advanced Graphics Port) アーキテクチャをサポートする。AGP を装備したシステムでは、ローカル ビデオ メモリが満杯である場合や非ローカル ビデオ メモリが明示的に要求されている場合に、装備されている AGP の実装タイプにより、DirectDraw は非ローカル ビデオ メモリを使用する。

[C++]

現時点では、"実行モデル" および "DMA モデル " として知られている 2 つの AGP アーキテクチャ実装がある。実行モデルの実装では、ディスプレイ デバイスは非ローカル ビデオ メモリ サーフェスとローカル ビデオ メモリ サーフェスで同一の機能をサポートする。その結果、ハードウェア能力を取得するために IDirectDraw7::GetCaps メソッドを呼び出すと、DDCAPS 構造体の dwNLVBCaps、dwNLVBCaps2、dwNLVBCKeyCaps、dwNLVBFXCaps、および dwNLVBRops メンバにあるブリット関連のフラグは、ローカル ビデオ メモリの場合と同一になる。実行モデルでは、ローカル ビデオ メモリが満杯になると、呼び出しで特に指定がない限り、DirectDraw は自動的に非ローカル ビデオ メモリに頼ろうとする。

DMA モデルの実装では、非ローカル ビデオ メモリ サーフェスからのブリットやテクスチャリングのサポートが制限される。ディスプレイ デバイスが DMA モデルを使用する場合、デバイス能力を取得するときに dwCaps2 メンバに DDCAPS2_NONLOCALVIDMEMCAPS フラグが設定される。DMA モデルでは、DDCAPS 構造体の dwNLVBCaps、dwNLVBCaps2、dwNLVBCKeyCaps、dwNLVBFXCaps、および dwNLVBRops メンバに含まれるブリット関連のフラグは、サポートする機能を記述する。DMA モデルでは、ローカル ビデオ メモリが満杯のときに、呼び出しが明示的にローカル ビデオ メモリを要求しない限り、DirectDraw は自動的にテクスチャ サーフェスだけに対して非ローカル ビデオ メモリに頼る。このような方法で処理されるのはテクスチャ サーフェスだけである。その他のタイプのサーフェスはすべて、呼び出しが明示的に非ローカル メモリを要求しない限り、非ローカル ビデオ メモリに作成できない。

DMA モデルの実装では、非ローカル ビデオ メモリ サーフェスからのテクスチャリングに対するサポートはさまざまである。ドライバが非ローカル ビデオ メモリ サーフェスからのテクスチャリングをサポートする場合、IDirect3DDevice7::GetCaps メソッドを呼び出して 3D ドライバ能力を取得するときに、D3DDEVCAPS_TEXTURENONLOCALVIDMEM フラグが設定される。

[Visual Basic]

現時点では、"実行モデル" および "DMA モデル " として知られている 2 つの AGP アーキテクチャ実装がある。実行モデルの実装では、ディスプレイ デバイスは非ローカル ビデオ メモリ サーフェスとローカル ビデオ メモリ サーフェスで同一の機能をサポートする。その結果、ハードウェア能力を取得するために DirectDraw7.GetCaps メソッドを呼び出すと、DDCAPS 型の lNLVBCaps、lNLVBCaps2、lNLVBCKeyCaps、lNLVBFXCaps および lNLVBRops メンバにあるブリット関連のフラグは、ローカル ビデオ メモリの場合と同一になる。実行モデルでは、ローカル ビデオ メモリが満杯になると、呼び出しで特に指定がない限り、DirectDraw は自動的に非ローカル ビデオ メモリに頼ろうとする。

DMA モデルの実装では、非ローカル ビデオ メモリ サーフェスからのブリットやテクスチャリングのサポートが制限される。ディスプレイ デバイスが DMA モデルを使用する場合、デバイス能力を取得するときに lCaps2 メンバに DDCAPS2_NONLOCALVIDMEMCAPS フラグが設定される。DMA モデルでは、DDCAPS 型の lNLVBCaps、lNLVBCaps2、lNLVBCKeyCaps、lNLVBFXCaps、および lNLVBRops メンバに含まれるブリット関連のフラグは、サポートする機能を記述する。DMA モデルでは、ローカル ビデオ メモリが満杯のときに、呼び出しが明示的にローカル ビデオ メモリを要求しない限り、DirectDraw は自動的にテクスチャ サーフェスだけに対して非ローカル ビデオ メモリに頼る。このような方法で処理されるのはテクスチャ サーフェスだけである。その他のタイプのサーフェスはすべて、呼び出しが明示的に非ローカル メモリを要求しない限り、非ローカル ビデオ メモリに作成できない。

DMA モデルの実装では、非ローカル ビデオ メモリ サーフェスからのテクスチャリングに対するサポートはさまざまである。ドライバが非ローカル ビデオ メモリ サーフェスからのテクスチャリングをサポートする場合、Direct3DDevice7.GetCaps メソッドを呼び出して 3D ドライバ能力を取得するときに、D3DDEVCAPS_TEXTURENONLOCALVIDMEM フラグが設定される。


サーフェス コンテキストとデバイス コンテキスト

DirectDraw と GDI サービスを混ぜ合わせて DirectDraw サーフェスのコンテキストを処理することが、役に立つ場合がある。DirectDraw は、デバイス コンテキストから DirectDraw サーフェスにアクセスでき、そのサーフェスのデバイス コンテキストを与えるサーフェスを取得できるメソッドを提供する。ここでは、次の項目でこれらの機能を詳しく説明する。

  • サーフェスに対するデバイス コンテキストの取得
  • デバイス コンテキストによるサーフェスの検出


サーフェスに対するデバイス コンテキストの取得

[C++]

GDI 関数により DirectDraw サーフェス オブジェクトのコンテンツを変更する場合、GDI 互換のデバイス コンテキスト ハンドルを取得しなくてはならない。これは、DrawText Win32 関数を呼び出して DirectDraw サーフェスのテキストを表示する場合に役立つ。この関数は、パラメータとしてデバイス コンテキストに対するハンドルを受け取る。サーフェスに対する IDirectDrawSurface7::GetDC メソッドを呼び出すことで、そのサーフェスに対する GDI 互換のデバイス コンテキストを取得できる。次の例でこの方法を示す。

// この例では、lpDDS4 変数が IDirectDrawSurface7
// インターフェイスに対する有効なポインタとなる。

  HDC     hdc;
  HRESULT HR;

  hr = lpDDS7->GetDC(&hdc);
  if(FAILED(hr))
      return hr;

// ここで、DrawText やいくつかの他の GDI 関数を
// 呼び出す。

  lpDDS7->ReleaseDC(hdc);

サーフェスのデバイス コンテキストが必要なくなったときに、IDirectDrawSurface7::ReleaseDC メソッドを呼び出していることに注意する。IDirectDrawSurface7::GetDC メソッドでは、サーフェスをロックするために IDirectDrawSurface7::Lock メソッドの内部バージョンが必要となるので、このステップが要求される。IDirectDrawSurface7::ReleaseDC メソッドが呼び出されるまで、そのサーフェスはロックされたままである。

[Visual Basic]

GDI 関数により DirectDraw サーフェス オブジェクトのコンテンツを変更する場合、GDI 互換のデバイス コンテキスト ハンドルを取得しなくてはならない。サーフェスに対する DirectDrawSurface7.GetDC メソッドを呼び出すことで、そのサーフェスに対する GDI 互換のデバイス コンテキストを取得できる。

サーフェスのデバイス コンテキストが必要なくなったときに、DirectDrawSurface7.ReleaseDC メソッドを呼び出していることに注意する。DirectDrawSurface7.GetDC メソッドでは、サーフェスをロックするために DirectDrawSurface7.Lock メソッドの内部バージョンが必要となるので、このステップが要求される。DirectDrawSurface7.ReleaseDC メソッドが呼び出されるまで、そのサーフェスはロックされたままである。


デバイス コンテキストによるサーフェスの検出

[C++]

IDirectDraw7::GetSurfaceFromDC メソッドを呼び出すことにより、サーフェスに対するデバイス コンテキストからサーフェスの IDirectDrawSurface7 インターフェイスへのポインタを取得できる。この機能は、コンポーネント アプリケーションや ActiveX® コントロールで非常に役立つ。この場合、実行時に描画するためのデバイス コンテキストを一般的に与えられるが、IDirectDrawSurface7 インターフェイスで明らかにされる機能を利用することができる。

デバイス コンテキストは、DirectDraw オブジェクトと関係のないメモリを識別する可能性がある。また、デバイス コンテキストは、他の DirectDraw オブジェクトすべてに対するサーフェスを識別する可能性もある。後者の場合は、複数のモニタを使用するシステムで発生しやすい。デバイス コンテキストが DirectDraw オブジェクトで作成しなかったサーフェスを識別しない場合、メソッドは DDERR_NOTFOUND を返して失敗する。

次のサンプルコードで、非常に簡単な場合を説明する。

// この例では、hdc 変数がビデオ メモリ デバイス コンテキストに
// 対する有効なハンドルとなる。
// lpDD 変数は、有効な IDirectDraw7 インターフェイス ポインタである。

LPDIRECTDRAWSURFACE7 lpDDS;
HRESULT hr;

hr = lpDD->GetSurfaceFromDC(hdc, &lpDDS);
if(SUCCEEDED(hr)) {
// このサーフェスのインターフェイスを使用する。
}
else if(DDERR_NOTFOUND == hr) {
    OutputDebugString("HDC not from this DirectDraw surface\n");
 }
[Visual Basic]

DirectDraw7.GetSurfaceFromDC メソッドを呼び出すことにより、サーフェスに対するデバイス コンテキストからサーフェスの DirectDrawSurface7 オブジェクトを取得できる。この機能は、コンポーネント アプリケーションや ActiveX® コントロールで非常に役立つ。この場合、実行時に描画するためのデバイス コンテキストを一般的に与えられるが、DirectDrawSurface7 オブジェクトで明らかにされる機能を利用することができる。

デバイス コンテキストは、DirectDraw オブジェクトと関係のないメモリを識別する可能性がある。また、デバイス コンテキストは、他の DirectDraw オブジェクトすべてに対するサーフェスを識別する可能性もある。デバイス コンテキストが DirectDraw オブジェクトで作成しなかったサーフェスを識別しない場合、メソッドは DDERR_NOTFOUND を返して失敗する。

次のサンプルコードで、非常に簡単な場合を説明する。

' この例では、hdc 変数がビデオ メモリ デバイス コンテキストに
' 対する有効なハンドルとなる。
' DD 変数は有効な DirectDraw7 オブジェクトである。

Dim dds As DirectDrawSurface7

Set dds = dd.GetSurfaceFromDC(hDC)

If Err.Number = DDERR_NOTFOUND Then
MsgBox "hDC not from this DirectDraw surface"
End If


パレット

ここでは、DirectDrawPalette オブジェクトについて説明する。次の項目について記述する。

  • パレットとは?
  • パレット タイプ
  • 非プライマリ サーフェスでのパレットの設定
  • パレットの共有
  • パレット アニメーション


パレットとは?

パレット化サーフェスは、有意な表示をするためにパレットを必要とする。パレット化サーフェスはカラー インデックス付きサーフェスとも呼ばれ、個々の番号がピクセルを表す番号の集合となる。番号の値は、個々のピクセルを表示するときにどの色を使用すべきかを DirectDraw に伝えるカラー テーブル へのインデックスである。単にパレットとも呼ばれる DirectDrawPalette オブジェクトは、カラー テーブルを簡単に制御する手段を提供する。16 ビット以上のピクセル フォーマットを使用するサーフェスは、パレットを使用しない。

DirectDrawPalette オブジェクトは、インデックス付きカラー テーブルを表す。このカラー テーブルには、カラーインデックス付きサーフェスで用いる 2、4、16、または 256 のエントリがある。パレットの個々のエントリは、サーフェス内でピクセルを表示するときに使用する色を記述する RGB トリプレットである。カラー テーブルには、使用する色を表す 16 ビット、または 24 ビット RGB トリプレットが含まれている。16 色パレットでは、テーブルに別の 256 色パレットへのインデックスを含むこともできる。テクスチャ、オフスクリーン サーフェス、およびオーバーレイ サーフェスに対してパレットがサポートされており、いずれもプライマリ サーフェスと同じパレットである必要はない。

[C++]

IDirectDraw7::CreatePalette を呼び出すことで、パレットを作成できる。このメソッドは、パレット オブジェクトの IDirectDrawPalette インターフェイスへのポインタを取得する。このインターフェイスのメソッドを使い、パレット エントリの操作、オブジェクトの能力に関する情報の取得、またはオブジェクトの初期化ができる (CoCreateInstance COM 関数を使ってオブジェクトを作成した場合)。

サーフェスの IDirectDrawSurface7::SetPalette メソッドを呼び出すことにより、サーフェスにパレットを適用できる。1 つのパレットを複数のサーフェスに適用することができる。

DirectDrawPalette オブジェクトは、8 ビット パレットのエントリ 0、およびエントリ 255 を取得する。ただし、DDPCAPS_ALLOW256 フラグを指定して、これらのエントリを利用することを要求しない場合にかぎる。

パレット エントリを取得するには、IDirectDrawPalette::GetEntries メソッドを使用する。エントリを変更するには、IDirectDrawPalette::SetEntries メソッドを使用する。

SDK の Ddutil.cpp ソース ファイルには、パレットと共に作用するためにアプリケーションで定義された便利な関数が含まれている。詳細については、ソース ファイルの DDLoadPalette 関数を参照すること。

[Visual Basic]

DirectDraw7.CreatePalette メソッドを呼び出すことで、パレットを作成できる。このメソッドは、DirectDrawPalette オブジェクトを返す。このオブジェクトのメソッドを使い、パレット エントリの操作およびオブジェクトの能力に関する情報の取得ができる。

サーフェスの DirectDrawSurface7.SetPalette メソッドを呼び出すことにより、サーフェスにパレットを追加できる。1 つのパレットを複数のサーフェスに適用することができる。

DirectDrawPalette オブジェクトは、8 ビット パレットのエントリ 0、およびエントリ 255 を取得する。ただし、DDPCAPS_ALLOW256 フラグを指定して、これらのエントリを利用することを要求しない場合にかぎる。

パレット エントリを取得するには、DirectDrawPalette.GetEntries メソッドを使用する。エントリを変更するには、DirectDrawPalette.SetEntries メソッドを使用する。


パレット タイプ

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

さらに、インデックス パレット と呼ばれるカラー テーブルをまったく含まないパレットも作成できる。インデックス パレットには、カラー テーブルの代わりに、別のパレットのカラー テーブルにおける位置を表すインデックス値が含まれる。

[C++]

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

ブリット処理中に、DirectDraw はインデックス パレット エントリを逆参照しないことに注意すること。

[Visual Basic]

インデックス パレットを作成するには、DirectDraw7.CreatePalette メソッドを呼び出すときに、DDPCAPS_8BITENTRIES フラグを指定する。たとえば、4 ビットのインデックス パレットを作成するには、DDPCAPS_4BIT および DDPCAPS_8BITENTRIES の両方のフラグを指定する。また、インデックス パレットを作成する場合、PALETTEENTRY 型の配列よりも、バイト配列を渡す。


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

パレットは、あらゆるパレット化サーフェス (プライマリ、バック バッファ、オフスクリーン プレーン、テクスチャ マップ) にアタッチすることができるが、システム パレットに影響を与えるのは、プライマリ サーフェス にアタッチされたパレットだけである。注意すべき重要な点は、DirectDraw ブリットが色変換を実行しないということである。つまり、ブリットの転送元あるいは転送先サーフェスにアタッチされたすべてのパレットが、無視されるのである。

非プライマリ サーフェス パレットは、Direct3D アプリケーションによる使用を目的としている。


パレットの共有

[C++]

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

注 ： 同じパレットの同一サーフェス上で IDirectDrawSurface7::SetPalette を何回か続けて呼び出す場合、そのパレットの参照カウントは 1 回しかインクリメントされない。繰り返しの呼び出しは、パレットの参照カウントに影響を与えないからである。

[Visual Basic]

パレットは、複数のサーフェス間で共有することができる。同一のパレットをフリッピング チェーンのフロント バッファとバック バッファに設定したり、複数のテクスチャ サーフェス間で共有することができる。


パレット アニメーション

パレット アニメーションとは、サーフェスを表示したときに、それ自体の外観を変更するためにサーフェスのパレットを修正するプロセスを指す。繰り返しパレットを変更することにより、実際にサーフェスのコンテンツを変更しなくても、サーフェスが変更したように見せることができる。このため、パレット アニメーションでは、コンテンツを変えずにごくわずかなオーバーヘッドで、サーフェスの外観を修正する手段を提供する。

簡単にパレット アニメーションを実現するには、以下の 2 つの方法がある。

  • 単一パレット内でのパレット エントリの修正
  • 複数パレット間の切り替え
[C++]

最初の方法を使う場合、アニメーションしようとする色に対応する個別のパレット エントリを変更し、それから IDirectDrawPalette::SetEntries メソッドを 1 回呼び出してエントリをリセットする。

2 番目の方法は、2 つ以上の DirectDrawPalette オブジェクトが必要になる。この方法を使う場合、IDirectDrawSurface7::SetPalette メソッドを呼び出して、サーフェス オブジェクトごとに 1 つのパレット オブジェクトをアタッチしながら、アニメーションを実行する。

どちらの方法もハードウェア依存ではないので、アプリケーションに最適に機能すると思われる方を選択するといい。

特定の情報やパレット アニメーションの実現例については、「チュートリアル 5 : パレットの動的変更」を参照すること。

[Visual Basic]

最初の方法を使う場合、アニメーションしようとする色に対応する個別のパレット エントリを変更し、それから DirectDrawPalette.SetEntries メソッドを 1 回呼び出してエントリをリセットする。

2 番目の方法は、2 つ以上の DirectDrawPalette オブジェクトが必要になる。この方法を使う場合、DirectDrawSurface7.SetPalette メソッドを呼び出して、サーフェス オブジェクトごとに 1 つのパレット オブジェクトをアタッチしながら、アニメーションを実行する。

どちらの方法もハードウェア依存ではないので、アプリケーションに最適に機能すると思われる方を選択するといい。


クリッパー

ここでは、DirectDrawClipper オブジェクトについて説明する。次の項目について記述する。

  • クリッパーとは?
  • クリップ リスト
  • DirectDrawClipper オブジェクトの共有
  • 非依存の DirectDrawClipper オブジェクト
  • CoCreateInstance を用いた DirectDrawClipper オブジェクトの作成
  • システム カーソルでのクリッパーの使用
  • マルチ ウィンドウでのクリッパーの使用


クリッパーとは?

クリッパーあるいは DirectDrawClipper オブジェクトにより、境界矩形またはいくつかの境界矩形のリストで示される、サーフェスの選択した部分をブリットすることができる (「クリップ リスト」を参照すること)。

クリッパーの一般的な使用は、スクリーンまたはウィンドウの境界を定義することである。たとえば、スプライトがスクリーンの縁から入ってくるような表示について考えてみる。スプライトがスクリーン上に突然現れるのではなく、滑らかに (縁から) 見えてくるようにする。クリッパー オブジェクトがないと、DirectDraw により全スプライトをブリットできない。これは、スプライトの一部が転送先サーフェスの外側に配置される場合があるためである。転送先サーフェス バッファへスプライトのピクセル値を連続してコピーすることは、間違った表示やメモリ アクセス障害の原因となることがある。クリップ リストとしてのスクリーン矩形があるクリッパーにより、DirectDraw はブリットを実行するようなストライプのトリム方法が分かり、可視部分だけがコピーされる。

次の図でこのタイプのクリッピングを示す。

また、クリッパー オブジェクトを使うと、転送先サーフェス内のある領域を書き込み可能として指定できる。DirectDraw は、指定したクリッピング矩形の外にあるピクセルを保護しながら、これらの領域のブリット処理をクリップする。

次の図でこのクリッパーの使用について示す。


クリップ リスト

[C++]

クリップ リストは、ピクセル座標ごとの 1 つ以上の RECT 構造体から成る。DirectDraw は、あらゆるサーフェスにアタッチされる DirectDrawClipper オブジェクトを使ってクリップ リストを管理する。

IDirectDrawSurface7::Blt メソッドは、クリップ リストの矩形だけにデータをコピーする。たとえば、サーフェスの右上の部分がクリップ リストの矩形により排除され、アプリケーションがクリップされたサーフェスの全領域にブリットした場合、DirectDraw は 2 つのブリットを効果的に実行する。次に示す図のように、1 つはサーフェスの左上角、もう 1 つはサーフェスの下半分である。

[Visual Basic]

クリップ リストは、ピクセル座標ごとの 1 つ以上の RECT 型から成る。DirectDraw は、あらゆるサーフェスにアタッチされる DirectDrawClipper オブジェクトを使ってクリップ リストを管理する。

DirectDrawSurface7.Blt メソッドは、クリップ リストの矩形だけにデータをコピーする。たとえば、サーフェスの右上の部分がクリップ リストの矩形により排除され、アプリケーションがクリップされたサーフェスの全領域にブリットした場合、DirectDraw は 2 つのブリットを効果的に実行する。次に示す図のように、1 つはサーフェスの左上角、もう 1 つはサーフェスの下半分である。

サーフェスのクリップ リストは手動で管理できる。または、プライマリ サーフェス に対しては DirectDraw が自動的にクリップ リストを管理する。

[C++]

クリップ リストを各自で管理するには、RGNDATA 構造体のフォームに矩形のリストを作成し、これを IDirectDrawClipper::SetClipList メソッドに渡す。

プライマリ サーフェスに対するクリップ リストを DirectDraw で管理するには、ターゲット ウィンドウのハンドルを指定する IDirectDrawClipper::SetHWnd メソッドを呼び出し、ウィンドウ (フルスクリーン ウィンドウでも) にクリッパーをアタッチする。これより、クリッピング領域をウィンドウのクライアント領域に設定でき、ウィンドウのサイズ変更やカバーの有無によりクリップ リストが自動的に更新されたことを確認できる。

[Visual Basic]

クリップ リストを各自で管理するには、RECT 型の配列のフォームに矩形のリストを作成し、DirectDrawClipper.SetClipList メソッドに渡す。

プライマリ サーフェスに対するクリップ リストを DirectDraw で管理するには、ターゲット ウィンドウのハンドルを指定する DirectDrawClipper.SetHWnd メソッドを呼び出し、ウィンドウ (フルスクリーン ウィンドウでも) にクリッパーをアタッチする。これより、クリッピング領域をウィンドウのクライアント領域に設定でき、ウィンドウのサイズ変更やカバーの有無によりクリップ リストが自動的に更新されたことを確認できる。

ウィンドウ ハンドルを用いてクリッパーを設定する場合、追加の矩形を設定することはできない。

オーバーレイ ハードウェアがクリッピングをサポートし、かつ転送先カラー キーイング がアクティブでない場合にだけ、オーバーレイ サーフェスに対するクリッピングがサポートされる。


DirectDrawClipper オブジェクトの共有

[C++]

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

注 ： 同一のサーフェス上で同一の DirectDrawClipper オブジェクトに対して IDirectDrawSurface7::SetClipper を何回も続けて呼び出す場合、そのオブジェクトの参照カウントは 1 回だけインクリメントされる。繰り返しの呼び出しは、オブジェクトの参照カウントに影響を与えないからである。

[Visual Basic]

DirectDrawClipper オブジェクトは、複数のサーフェス間で共有することができる。たとえば、フリッピング チェーンのフロント バッファおよびバック バッファの両方に、同一の DirectDrawClipper オブジェクトを設定することができる。アプリケーションが DirectDrawSurface7.SetClipper メソッドを使ってサーフェスに DirectDrawClipper オブジェクトをアタッチすると、サーフェスはそのオブジェクトの参照カウント をインクリメントする。


非依存の DirectDrawClipper オブジェクト

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

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

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

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


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

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectDrawClipper オブジェクトは、COM 準拠のクラスファクトリを完全にサポートする。さらに、標準的な DirectDrawCreateClipper 関数と IDirectDraw7::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 オブジェクトへのポインタを指す。

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

アプリケーションを終了する前に、CoUninitialize 関数で COM ライブラリを閉じること。


システム カーソルでのクリッパーの使用

DirectDraw アプリケーションでは、ユーザーがマウスを使ってナビゲートできる方法を提供しなくてはならない場合がある。ページ フリッピングを使うフルスクリーン排他モードのアプリケーションでは、唯一、手動でマウス カーソルを実現する方法がある。すなわち、DirectInput® または Windows マウス メッセージに応答することにより、デバイスから取得されるデータに基づいてスプライトを移動する方法である。ただし、ページ フリッピングを使わないあらゆるアプリケーションでは、依然としてシステムのマウス カーソル サポートを使うことができる。

システム マウス カーソルを使用する場合、プライマリ サーフェスの一部にブリットを行うと、グラフィックスの異常に悩まされることがある。この異常は、システムで残されたかのように見えるマウス カーソルの一部として現れる。

[C++]

DirectDrawClipper オブジェクトは、ブリット処理中にマウス カーソルのイメージが " 邪魔になる " ことを阻止することで、これらの異常が現れないようにできる。これは比較的簡単に実現できる。そのためには、IDirectDraw7::CreateClipper メソッドを呼び出して、DirectDrawClipper オブジェクトを作成する。そして、IDirectDrawClipper::SetHWnd メソッドを用いて、クリッパーへアプリケーションのウィンドウ ハンドルを割り当てる。クリッパーがアタッチされると、IDirectDrawSurface7::Blt メソッドを用いてプライマリ サーフェスで実行する繰り返しのブリットでは、異常が現れなくなる。

IDirectDrawSurface7::BltFast メソッド、そして、IDirectDrawSurface、IDirectDrawSurface2、および IDirectDrawSurface3 インターフェイスに対応するメソッドは、クリッパーのアタッチ状態のサーフェスに作用しないことに注意する。

[Visual Basic]

DirectDrawClipper オブジェクトは、ブリット処理中にマウス カーソルのイメージが " 邪魔になる " ことを阻止することで、これらの異常が現れないようにできる。これは比較的簡単に実現できる。そのためには、DirectDraw7.CreateClipper メソッドを呼び出して、DirectDrawClipper オブジェクトを作成する。そして、DirectDrawClipper.SetHWnd メソッドを用いて、クリッパーへアプリケーションのウィンドウ ハンドルを割り当てる。クリッパーがアタッチされると、DirectDrawSurface7.Blt メソッドを用いてプライマリ サーフェスで実行する繰り返しのブリットでは、異常が現れなくなる。


マルチ ウィンドウでのクリッパーの使用

DirectDrawClipper オブジェクトを使い、標準協調レベルで実行するアプリケーションにより作成された複数のウィンドウにブリットすることができる。

[C++]

このためには、プライマリ サーフェス付きの 1 つの DirectDraw オブジェクトを作成する。その後、DirectDrawClipper オブジェクトを作成し、IDirectDrawSurface7::SetClipper メソッドを呼び出してプライマリ サーフェスに割り当てる。ウィンドウのクライアント領域だけをブリットするには、プライマリ サーフェスにブリットする前に、IDirectDrawClipper::SetHWnd メソッドを呼び出してウィンドウのクライアント領域にクリッパーを設定する。別のウィンドウのクライアント領域にブリットしなくてはならないときは、常に新しいターゲット ウィンドウ ハンドルを用いて IDirectDrawClipper::SetHWnd メソッドを再度呼び出す。

[Visual Basic]

このためには、プライマリ サーフェス付きの 1 つの DirectDraw オブジェクトを作成する。その後、DirectDrawClipper オブジェクトを作成し、DirectDrawSurface7.SetClipper メソッドを呼び出してプライマリ サーフェスに割り当てる。ウィンドウのクライアント領域だけをブリットするには、プライマリ サーフェスをブリットする前に、DirectDrawClipper.SetHWnd メソッドを呼び出してウィンドウのクライアント領域にクリッパーを設定する。別のウィンドウのクライアント領域にブリットしなくてはならないときは、常に新しいターゲット ウィンドウ ハンドルを用いて DirectDrawClipper.SetHWnd メソッドを再度呼び出す。

互いのプライマリ サーフェスにブリットする複数の DirectDraw オブジェクトを作成することは、勧められない。前述の技術で、1 つの DirectDraw オブジェクトで複数のクライアント領域にブリットする効率的で確実な方法を提供する。


マルチモニタ システム

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

Windows 98 と Windows NT 2000 では、1 つのシステム上で複数のディスプレイ デバイスとモニタをサポートする。マルチモニタ アーキテクチャ (通常は "MultiMon" と呼ばれる) は、2 つ以上のディスプレイ デバイスとモニタからディスプレイ領域を使用するオペレーティング システムを可能にし、単一の論理的なデスクトップを作成する。たとえば、2 つのモニタの MultiMon システムでは、ユーザーがどちらかのモニタ上にアプリケーションを表示できたり、1 つのモニタからもう 1 つのモニタにウィンドウをドラッグすることもできる。DirectDraw ではこのアーキテクチャをサポートし、アプリケーションは MultiMon システムを用いた複数のディスプレイ デバイス上のハードウェアに直接アクセスできる。

注 ： ヌル デバイス上で作成されたりプライマリ サーフェスに直接レンダリングされない限り、フルスクリーンではない DirectDraw アプリケーションは MultiMon と共に自動的に機能し、ユーザーはあるモニタから他のモニタへウィンドウをドラッグできる。ただし、ウィンドウが完全にプライマリ ディスプレイ内にある場合だけ、DirectDraw はハードウェア アクセラレータを利用する。DirectDraw のウィンドウ アプリケーションでは、各モニタに対して別の DirectDraw オブジェクトとサーフェスを維持し、MultiMon に対して個別に設計することを勧める。詳細については、「MultiMon システムのデバイスとアクセラレータ」を参照すること。

ここでは、マルチモニタをサポートするシステム上での DirectDraw の使用について説明する。次の項目について記述する。

  • MultiMon システムにおけるデバイスの列挙
  • マルチ モニタの DirectDraw オブジェクト
  • フォーカス ウィンドウとデバイス ウィンドウ
  • MultiMon システムのデバイスとアクセラレータ
  • MultiMon によるフルスクリーン DirectDraw アプリケーションのデバッグ

DirectX SDK にある Multimon.h ヘッダー ファイルにより、Windows 98 のマルチモニタ関数を記述したコードが、MultiMon をサポートしないオペレーティング システム上でコンパイルおよび実行できる。

次のサンプル アプリケーションでは、DirectDraw の MultiMon の実装について説明する。

  • Multimon サンプル


MultiMon システムにおけるデバイスの列挙

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectDrawEnumerateEx 関数を使用すると、マルチモニタを用いたシステム上のデバイスを列挙できる。マルチモニタは、列挙されるべき DirectDraw デバイスのタイプを決定するフラグを指定する。この関数では、列挙されたデバイスごとにアプリケーション定義された DDEnumCallbackEx 関数を呼び出す。

DirectDrawEnumerateEx 関数は、Windows 98、および Windows NT 2000 とそれ以降のオペレーティング システムでサポートされる。また、DirectX 6.0 以降のバージョンでコンパイルされたアプリケーションは、Ddraw.lib で利用できる。関数へ静的にリンクするアプリケーションは常に DirectX 6.0 以降のバージョンで実行し、常に Windows 98 および Windows NT 2000 以降の DirectX のあらゆるバージョンで実行する。Windows 95 の DirectX の以前のバージョンで実行する場合、このようなアプリケーションは失敗する。

アプリケーションに DirectX 5.0 以前のバージョンの実行が必要な場合、DirectDrawEnumerateEx が利用可能であれば参照のために GetProcAddress を使用すべきである。次にこの方法についての例を示す。

    HINSTANCE h = LoadLibrary("ddraw.dll");

// ddraw.dll が検索パスに存在しない場合、
// おそらく DirectX はインストールされないので、失敗する。
    if (!h)
        return FALSE;

// 取得する関数のバージョンを知らなければならない
// ことに注意する (次に示すテキストを参照)。
// この例では、ANSI バージョンを使用する。
    LPDIRECTDRAWENUMERATEEX lpDDEnumEx;
    lpDDEnumEx = (LPDIRECTDRAWENUMERATEEX) GetProcAddress(h,"DirectDrawEnumerateExA");

// 関数がある場合、その関数を呼び出して、
// デスクトップにアタッチされるすべてのディスプレイ デバイスと
// 非ディスプレイ DirectDraw デバイスを列挙する。
    if (lpDDEnumEx)
        lpDDEnumEx(Callback, NULL,
            DDENUM_ATTACHEDSECONDARYDEVICES |
            DDENUM_NONDISPLAYDEVICES
            );
    else
    {
        /*
* DirectDraw の古いバージョンで実行する必要がある。
* したがって MultiMon はサポートされない。Fall back on
* 単一のモニタ システム上の標準的なデバイスを列挙するには、
* DirectDrawEnumerate に頼る。
         */
        DirectDrawEnumerate(OldCallback,NULL);

/* OldCallback 関数を DDEnumCallbackEx に対する
* ラッパーとすると便利であることに注意する。
         *
* このような関数は次のようにする。
* BOOL FAR PASCAL OldCallback (GUID FAR *lpGUID,
*        LPSTR pDesc,
*        LPSTR pName,
*        LPVOID pContext)
         *    {
*   return Callback (lpGUID,pDesc,pName,pContext,NULL) ;
         *    }
         */
    }

// LoadLibrary () の呼び出しでライブラリがロードされ場合、
// そのライブラリを活用するには、// FreeLibrary () を使用しなくてはならない。
    FreeLibrary(h);

上記の例では、実行時やロード時に Ddraw.dll にリンクするアプリケーション対して作用する。

DirectDrawEnumerateEx 関数の ANSI、または Unicode バージョンのどちらかのアドレスを取得しなくてはならないことに注意する。この関数は、アプリケーションで使用する文字列型に依存する。対応するコールバック関数を宣言する場合、文字列のパラメータに対する LPTSTR データ型を使用する。_UNICODE シンボルか ANSI 文字列のどちらかを宣言する場合、LPTSTR データ型は Unicode 文字列を使用するためにコンパイルする。LPTSTR データ型を使用することにより、アプリケーションで使用する文字列型にかかわらず、その関数は正確にコンパイルしなければならない。


マルチ モニタの DirectDraw オブジェクト

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

ヌルやデフォルトのディスプレイ ドライバに対して記述された DirectDraw のウィンドウ アプリケーションは、MultiMon 上で機能する。しかし、MultiMon のために最適化されるアプリケーションでは、列挙コールバックに返される GUID を使用し、各デバイスに対して別の DirectDraw オブジェクトを作成する (「MultiMon システムにおけるデバイスの列挙」を参照すること)。

ＤｉｒｅｃｔＤｒａｗ オブジェクトの作成時にアプリケーションで GUID を指定したか NULL を指定したかによって、MultiMon の動作が変わる場合がある。最も分かりやすい例としては、アプリケーションで NULL を指定した場合、DirectDraw は常にカーソルをプライマリ モニタにクリップする。

MultiMon システム上で協調レベルを複数回設定することは避けること。フルスクリーンから一般的なモードに切り替えなくてはならない場合は、新しい DirectDraw オブジェクトを作成することが最善である。

ALT + TAB キーにアプリケーションを応答させるには、アプリケーションがデフォルトのウィンドウ プロシージャを使用しないようにする。この機能を利用するには、SETFOCUS メッセージを受け取るたびに、デバイス ウィンドウがフォーカスを親ウィンドウに変更しなければならない。

全 DirectDraw オブジェクトは同時に解放することを勧める。セカンダリ デバイスや複数のデバイスだけを解放する場合、プライマリ デバイスは元のデスクトップ モードに戻るが、タスクバーだけは再描画され、DirectDraw のプライマリ サーフェスは存在したままである。DirectDraw オブジェクトの解放およびそのオブジェクトの再作成を最初に行わないで、このサーフェスに描画することはできない。


フォーカス ウィンドウとデバイス ウィンドウ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

フルスクリーン排他モードで 1 つまたはそれ以上のモニタを使用する各 DirectDraw アプリケーションには、キーボード入力を受け取るウィンドウとなる単一のフォーカス ウィンドウが必要である。

フルスクリーン DirectDraw サーフェスを保持する各デバイスは、DirectDraw オブジェクトとデバイス ウィンドウにより現されなくてはならない。デバイス ウィンドウは、ウィンドウに適合するようにサイズ変更され、他のすべてのウィンドウ上に配置されるウィンドウである。

単一のモニタ アプリケーションには、デバイスとフォーカス ウィンドウ間の区別はない。これらは 1 つかつ同じである。ただし、マルチモニタ アプリケーションには各モニタ用のデバイス ウィンドウを設定する必要があり、各 DirectDraw オブジェクトにアプリケーションのフォーカス ウィンドウを通知させなくてはならない。また、フォーカス ウィンドウは、1 つのモニタに対するデバイス ウィンドウとしても役立つ。他のデバイス ウィンドウはフォーカス ウィンドウの子となるため、ユーザーが子ウィンドウの 1 つをクリックする場合、アプリケーションは最小化しない。

注 : MultiMon アプリケーションで複数の排他ウィンドウを作成する場合、入力フォーカス ウィンドウをデバイスの親ウィンドウとして指定する必要がある。そうしないと、アプリケーションは適切な入力を取得できない。

参照

  • フォーカス ウィンドウの設定
  • デバイス ウィンドウの設定


フォーカス ウィンドウの設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

フォーカス ウィンドウを設定するには、各 DirectDraw オブジェクトに対して IDirectDraw7::SetCooperativeLevel メソッドを呼び出す。ウィンドウ ハンドル (通常のアプリケーション ウィンドウ ハンドル) に渡し、次に示すように DDSCL_SETFOCUSWINDOW フラグを設定する。

/* lpDD が有効な IDirectDraw インターフェイス ポインタであり、
hWnd が有効なウィンドウ ハンドルであると仮定する。 */

HRESULT ddrval = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_SETFOCUSWINDOW );

フォーカス ウィンドウは、すべてのデバイスに対して同じでなくてはならない。


デバイス ウィンドウの設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

デバイス ウィンドウを設定するには、2 通りの方法がある。

  • 各自でウィンドウを作成し、そのハンドルをモニタを示す DirectDraw オブジェクトの IDirectDraw7::SetCooperativeLevel メソッドに DDSCL_SETDEVICEWINDOW、DDSCL_FULLSCREEN、および DDSCL_EXCLUSIVE フラグを設定して渡す。これはフルスクリーン ウィンドウを作成し、モニタに対するデバイス ウィンドウとして設定する。アプリケーションはウィンドウに対するマウス メッセージを受け取る。ウィンドウの破棄は適切なときに各自で行う。SetCooperativeLevel に渡すウィンドウは、フォーカス ウィンドウ (同じデバイス上の場合だけに可能)、またはフォーカス ウィンドウの子とすべきである。
  • DirectDraw がウィンドウを作成する。フォーカス ウィンドウ ハンドルを SetCooperativeLevel に渡し、DDSCL_CREATEDEVICEWINDOW、DDSCL_FULLSCREEN、および DDSCL_EXCLUSIVE フラグを設定する。DirectDraw では、フォーカス ウィンドウの子となるデフォルトのデバイス ウィンドウを作成する。DirectDraw ではこのウィンドウを管理し、適切なときに破棄する。アプリケーションでは、ウィンドウのあらゆるマウス メッセージを受け取れない。

次の例では、lpDD が現す DirectDraw オブジェクトに対する既存のデバイス ウィンドウを設定する。

/* lpDD が有効な IDirectDraw インターフェイス ポインタであり、
hWnd が適切なデバイス ウィンドウへのハンドルであると仮定する。 */

HRESULT hr = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_SETDEVICEWINDOW | DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN );

次の例では、DirectDraw が作成したデフォルトのデバイス ウィンドウを設定する。この場合、hWnd は既存のフォーカス ウィンドウへのハンドルとなる。

HRESULT hr = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_CREATEDEVICEWINDOW | DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN );

フォーカス ウィンドウはデバイス ウィンドウではないが、SetCooperativeLevel の呼び出しでフォーカス ウィンドウとデバイス ウィンドウの両方としてウィンドウを設定できない。最初にフォーカス ウィンドウとして設定してから、デバイス ウィンドウとして設定する。ただし、同じデバイス上のフォーカス ウィンドウとデフォルトのデバイス ウィンドウは、SetCooperativeLevel の呼び出しで設定できる。次の例でこの方法について示す。

HRESULT hr = lpDD->SetCooperativeLevel(
        hwndFocus,
        DDSCL_SETFOCUSWINDOW | DDSCL_FULLSCREEN |
        DDSCL_EXCLUSIVE | DDSCL_CREATEDEVICEWINDOW);

この例では、既存のウィンドウ (おそらくアプリケーション ウィンドウ) がフォーカス ウィンドウとして設定され、DirectDraw がデフォルトのデバイス ウィンドウを作成する。


MultiMon システムのデバイスとアクセラレータ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

フルスクリーン排他モードの DirectDraw オブジェクトは、プライマリ デバイスまたはセカンダリ デバイス上で実行するかどうかにかかわらず、ハードウェア アクセラレータを利用する。ただし、ディスプレイ デバイス全域でグラフィックス オペレーションをスパンするために、ビルトイン サポートを使用できない。適切なデバイスでオペレーションを実行することは、アプリケーションで行う。

標準協調レベルが設定されると、ウィンドウがプライマリ デバイスの全ディスプレイ領域内の場合だけ、DirectDraw はハードウェア アクセラレータを使用する。ウィンドウが 2 つ以上のモニタに不規則に広がる場合、すべてのブリットが列挙され、パフォーマンスがかなり低下する。ハードウェア バッファでは他のハードウェアが制御するディスプレイ サーフェスにブリットできないため、これはやむをえないことである。

ヌル デバイスに対して DirectDraw オブジェクトを作成する限り、NULL が lpGUID パラメータとして DirectDrawCreate に渡される。DirectDraw では、配置されるかどうかにかかわらず全ウィンドウへブリットする。ただし、デバイスが実際の GUID で作成される場合 (クリッパーを使用する場合)、プライマリ サーフェスの縁に交差するブリット オペレーションはクリップされたり、DDERR_INVALIDRECT を返して失敗する。

注 ： MultiMon アプリケーションのウィンドウにブリットしている場合、セカンダリ モニタの論理的な位置がプライマリ モニタの左側になると、負の座標が有効となる。

ウィンドウ MultiMon アプリケーションのパフォーマンスを向上させるには、各デバイスに対する DirectDraw を作成し、各デバイスに並行してオフスクリーン サーフェスを維持し、各デバイスに常駐するウィンドウの一部のトラックを保ち、各デバイスへ別々のブリットを実行しなければならない。


MultiMon によるフルスクリーン DirectDraw アプリケーションのデバッグ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

フルスクリーン DirectDraw アプリケーションのデバッグ中のコードからステップするリモート デバッグではなく、マルチモニタ システムを使用できる。

DirectDraw 出力のために、開発環境とセカンダリ モニタに対するプライマリ モニタを使用すべきである。また、Control Panel の DirectX プロパティ シートから設定するレジストリも変更できる。DirectDraw ページでは、Advanced Settings をクリックし、Enable Multi-Monitor Debugging チェックボックスを選択する。この設定により、DirectDraw はアプリケーションがフォーカスを失ったときに最小化されるのを回避できる。

Windows 98 では、サーフェスのロック時にコードからステップできない。詳細については、「サーフェス メモリへの直接アクセス」を参照すること。


DirectDraw の高度なトピック

ここでは、DirectDraw の高度なトピックを説明して、DirectDraw の概要を補足する。次の項目について記述する。

  • モード 13 サポート
  • DMA サポートの利用
  • ウィンドウ モードでの DirectDraw パレットの使用
  • ビデオ ポート
  • リフレッシュ レートの列挙
  • フリッピングとブリットの状態取得
  • ディスプレイ ハードウェア能力の決定
  • ディスプレイ メモリでのビットマップの格納
  • トリプル バッファリング
  • DirectDraw アプリケーションとウィンドウ スタイル
  • フレーム バッファの色空間へのトゥルー RGB 色の適合
  • フルスクリーン モードでのウィンドウの表示


モード 13 サポート

ここでは、DirectDraw モード 13 グラフィックス モードサポートについて説明する。次の項目について記述する。

  • モード 13 について
  • モード 13 の設定
  • モード 13 とサーフェス能力
  • モード 13 の使用


モード 13 について

DirectDraw は、モード 13 (16 進 BIOS モード番号) の名で広く知られる線形フリッピング不能な 320 × 200 × 8 ビット/ピクセル パレット化モードへのアクセスをサポートする。DirectDraw は、このモードをモード X モードと同様に取り扱うが、モード 13 の物理的特質により課される重要な違いもある。


モード 13 の設定

[C++]

モード 13 には、モード X と同様な列挙やモード設定動作がある。DirectDraw は、DDSCL_ALLOWMODEX フラグが IDirectDraw7::SetCooperativeLevel メソッドに渡された場合にかぎり、モード 13 を列挙する。

他のすべてのモードと同様にモード 13 ディスプレイ モードは列挙されるが、IDirectDraw7::EnumDisplayModes を呼び出す前にサーフェス能力を調べる。これを行うには、IDirectDraw7::GetCaps を呼び出して、メソッドが戻った後に DDSCAPS2 構造体の DDSCAPS_STANDARDVGAMODE フラグを調べる。このフラグが存在しなければ、モード 13 がサポートされていないということであり、DDEDM_STANDARDVGAMODES フラグで列挙しようとすることは失敗して、DDERR_INVALIDPARAMS が返される。

現在、EnumDisplayModes メソッドは新しい列挙フラグ DDEDM_STANDARDVGAMODES をサポートする。これにより、DirectDraw は 320 × 200 × 8 モード X モードの他にモード 13 を列挙できるようになる。新しい IDirectDraw7::SetDisplayMode のフラグとして DDSDM_STANDARDVGAMODE があり、モード 13 を 320 × 200 × 8 モード X と区別するために渡さなくてはならない。

[Visual Basic]

モード 13 には、モード X と同様な列挙やモード設定動作がある。DirectDraw は、DDSCL_ALLOWMODEX フラグが DirectDraw7.SetCooperativeLevel メソッドに渡された場合にかぎり、モード 13 を列挙する。

他のすべてのモードと同様にモード 13 ディスプレイ モードは列挙されるが、DirectDraw7.GetDisplayModesEnum を呼び出す前にサーフェス能力を調べる。これを行うには、DirectDraw7.GetCaps を呼び出して、メソッドが戻った後に DDSCAPS2 型の DDSCAPS_STANDARDVGAMODE フラグを調べる。このフラグが存在しなければ、モード 13 がサポートされていないということであり、DDEDM_STANDARDVGAMODES フラグで列挙しようとすることは失敗して、DDERR_INVALIDPARAMS が返される。

現在、GetDisplayModesEnum メソッドは新しい列挙フラグ DDEDM_STANDARDVGAMODES をサポートする。これにより、DirectDraw は 320 × 200 × 8 モード X モードの他にモード 13 を列挙できるようになる。新しい DirectDraw7.SetDisplayMode のフラグとして DDSDM_STANDARDVGAMODE があり、モード 13 を 320 × 200 × 8 モード X と区別するために渡さなくてはならない。

ビデオ カードによっては、線形アクセラレータ 320 × 200 × 8 モードが提供されていることに注意する。そのようなカードでは、DirectDraw がモード 13 を列挙せずに、代わりとして線形モードを列挙する。この場合、SetDisplayMode に DDSDM_STANDARDVGAMODE フラグを渡してモード 13 を設定すると、このメソッドは成功するが、線形モードが使われるようになる。これは、線形低解像度モードがモード X モードをオーバーライドする方法に類似する。


モード 13 とサーフェス能力

[C++]

DirectDraw がアプリケーションの EnumModesCallback コールバック関数を呼び出すと、関連する DDSURFACEDESC や DDSURFACEDESC2 構造体の ddsCaps メンバには、列挙されているモードを反映するフラグが含まれる。モード X に対しては DDSCAPS_MODEX、モード 13 に対しては DDSCAPS_STANDARDVGAMODE となる。これらのフラグは、互いに排他である。これらビットが両方とも設定されてない場合は、モードは線形アクセラレータ モードということになる。これは、IDirectDraw7::GetDisplayMode メソッドから取得されたフラグにも当てはまる。

[Visual Basic]

DirectDraw がアプリケーションの DirectDraw7.GetDisplayModesEnum メソッドを呼び出すと、関連する DDSURFACEDESC2 型の ddsCaps メンバには、列挙されているモードを反映するフラグが含まれる。モード X に対しては DDSCAPS_MODEX、モード 13 に対しては DDSCAPS_STANDARDVGAMODE となる。これらのフラグは、互いに排他である。これらビットが両方とも設定されてない場合は、モードは線形アクセラレータ モードということになる。これは、DirectDraw7.GetDisplayMode メソッドから取得されたフラグにも当てはまる。


モード 13 の使用

[C++]

モード X モードとは異なりモード 13 は線形モードなので、DirectDraw はアプリケーションにフレーム バッファへの直接アクセスを与えることができる。IDirectDrawSurface7::Lock、IDirectDrawSurface7::Blt、および IDirectDrawSurface7::BltFast メソッドを呼び出して、プライマリ サーフェスへの直接アクセスを取得する。

モード 13 を使用すると、DirectDraw は、プライマリ サーフェスへのバック バッファのコンテンツにおける直接コピーとして実現されるエミュレートした IDirectDrawSurface7::Flip をサポートする。Blt または BltFast を使用することで、プライマリ サーフェスにバックバッファのすべて、または一部をコピーすることにより、自分でこれをエミュレートできる。

[Visual Basic]

モード X モードとは異なりモード 13 は線形モードなので、DirectDraw はアプリケーションにフレーム バッファへの直接アクセスを与えることができる。DirectDrawSurface7.Lock、DirectDrawSurface7.Blt、および DirectDrawSurface7.BltFast メソッドを呼び出して、プライマリ サーフェスへの直接アクセスを取得する。

モード 13 を使用すると、DirectDraw は、プライマリ サーフェスへのバック バッファのコンテンツにおける直接コピーとして実現されるエミュレートした DirectDrawSurface7.Flip をサポートする。Blt または BltFast を使用することで、プライマリ サーフェスにバックバッファのすべて、または一部をコピーすることにより、自分でこれをエミュレートできる。

[C++]

Lock およびモード 13 に関して、1 つ警告すべきことがある。DirectDraw は、モード 13VGA フレーム バッファへの直接線形アクセスを可能にするが、バッファが常にアドレス 0xA0000 にあるとしてはならない。DirectDraw が、0xA0000 ではないフレーム バッファへの別名の仮想メモリポインタを返すことがあるからである。同様に、モード 13 サーフェスのピッチが 320 であるとしてはならない。アクセラレータ 320 × 200 × 8 モードをサポートするディスプレイ カードでは、異なるピッチをよく使用するからである。

[Visual Basic]

Lock およびモード 13 に関して、1 つ警告すべきことがある。モード 13 サーフェスのピッチが 320 であるとしてはならない。アクセラレータ 320 × 200 × 8 モードをサポートするディスプレイ カードでは、異なるピッチをよく使用するからである。


ステレオ ビュー

以下のトピックでは、DirectX 7.0 でサポートされるステレオ ビューについて説明する。

  • ステレオ ビューについて
  • ステレオ ビュー ディスプレイ デバイスについて
  • サポートされるステレオ ビュー モードの決定
  • ステレオ ビューの実装

ステレオ ビューは、フルスクリーン排他モードでのみサポートされる。ウィンドウではステレオ モードはサポートされない。

詳細については、「ディスプレイ モード」と「サーフェス」を参照すること。


ステレオ ビューについて

ステレオ ビュー、あるいは立体表示では、わずかに異なる角度でとらえられた 2 つのシーン イメージを表示することにより、3D エフェクトを生成する。2D 表示でステレオ ビューを実現するには、左眼と右眼に別々のイメージを割り当てて処理する。ステレオ ビューを実現する最も一般的な方法は、左のイメージと右のイメージを多重化する方法である。この方法では、左のイメージと右のイメージを高速で交互に表示する。適切なエフェクトを生成するには、一方の眼のビューを表示している間は、もう一方の眼のビューを表示しないようにする。

ステレオ ビュー機能を利用するには、アプリケーションがステレオ ビューをサポートし、ハードウェアにステレオ データを送信できるアプリケーション プログラミング インターフェイス (API) を使用しなければならない。DirectDraw では、2 つのサーフェスを1 つのステレオ ペアのイメージとして作成し、管理する。また、グラフィックス チップやグラフィックス カードのメーカーから、使用可能なハードウェアやステレオ対応ドライバが提供されていなければならない。ステレオ ディスプレイ メーカーの提供するステレオ ディスプレイ デバイスも必要である。

ステレオ ディスプレイ デバイスには、単純な赤と青の平面レンズ、液晶ディスプレイ (LCD) シャッター レンズ、および複雑な自動ステレオグラフィックス ディスプレイなど、さまざまな種類がある。必要なハードウェアおよびソフトウェア コンポーネントはデバイスによって異なるので、単一のステレオ ビュー ソリューションをサポートするのは困難である。このため、DirectDraw では、ディスプレイ デバイス準拠のグラフィックス ディスプレイ ドライバを使ってステレオ ビューを実装しなければならない。

ステレオ ディスプレイ デバイスには、対応するグラフィックス カードが必要である。グラフィックス カードのドライバは、デバイス固有のメモリ レイアウトやスキャン条件を処理できなければならない。スキャン条件には、ディスプレイとの同期が含まれる。たとえば、シャッター レンズでは、左のシャッターが開いているときには左のイメージを、右のシャッターが開いているときには右のイメージを表示する。


ステレオ ビュー ディスプレイ デバイスについて

DirectDraw は、能動および受動 3D ステレオ ビュー ディスプレイ デバイスの両方をサポートする。以下のトピックでは、DirectDraw が能動および受動ディスプレイ デバイスをどのように処理するかについて説明する。

  • 能動ディスプレイ デバイス
  • 受動ディスプレイ デバイス


サポートされるステレオ ビュー モードの決定

[C++]

ハードウェアがステレオ ビューをサポートするかどうかは、DDCAPS2_STEREO フラグによって調べることができる。このフラグは、DirectDraw オブジェクトによって公開されるハードウェア能力を示す DDCAPS 構造体の dwCaps2 メンバに設定される。現在のディスプレイ モードが、ステレオ ビューをサポートするディスプレイ モードではない場合もあるので注意すること。

特定のディスプレイ モードでステレオ ビューをサポートするかどうかを確認するには、IDirectDraw7::EnumDisplayModes メソッドを使ってサポートされるディスプレイ モードを列挙する。ハードウェアによってサポートされる各ディスプレイ モードに対して、DirectDraw は EnumModesCallback プロトタイプと照合するコールバック関数を呼び出す。このコールバック関数の最初の引数は、サポートされるディスプレイ モードの 1 つを示す DDSURFACEDESC2 構造体のアドレスである。DDSURFACEDESC2 構造体の ddsCaps メンバの dwCaps2 フィールドに、DDSCAPS2_STEREOSURFACELEFT フラグが設定されているかどうかを調べる。このフラグが設定されていると、そのディスプレイ モードはステレオ ビューをサポートする。

IDirectDraw7::GetDisplayMode メソッドを使って現在のディスプレイ モードを取得し、返された DDSURFACEDESC2 構造体のステレオ ビュー能力を調べることもできる。

[Visual Basic]

ハードウェアがステレオ ビューをサポートしているかどうかを確認するには、DDCAPS2_STEREO フラグを調べる。このフラグは、DirectDraw オブジェクトによって公開されるハードウェア能力を示す DDCAPS 型の lNLVBCaps2 メンバに設定される。DDCAPS2_STEREO フラグは、CONST_DDCAPS2FLAGS 列挙のメンバである。現在のディスプレイ モードが、ステレオ ビューをサポートするディスプレイ モードではない場合もあるので注意すること。

特定のディスプレイ モードでステレオ ビューをサポートするかどうかを確認するには、DirectDraw7.GetDisplayModesEnum メソッドを使ってサポートされるディスプレイ モードを列挙する。method.このメソッドは、DirectDrawEnumModes オブジェクトを返す。サポートされるディスプレイ モードを記述する DDSURFACEDESC2 型を取得するには、DirectDrawEnumModes.GetItem メソッドを呼び出す。DDSURFACEDESC2 型の ddsCaps メンバの lCaps2 フィールドに、DDSCAPS2_STEREOSURFACELEFT フラグが設定されているかどうかを調べる。このフラグがセットされていると、そのディスプレイ モードはステレオ ビューをサポートする。

DirectDraw7.GetDisplayMode メソッドを使って現在のディスプレイ モードを取得し、返された DDSURFACEDESC2 型のステレオ ビュー能力を調べることもできる。

ディスプレイ モードの列挙については、「サポートされるディスプレイの決定」を参照すること。


ステレオ ビューの実装

DirectDraw を初期化してディスプレイ モードを列挙し、ステレオ ビューがサポートされていることを確認したら、DirectDraw のステレオ ビュー サポートを利用できる。最初に、ステレオ ビュー フリッピング チェーンに対してサーフェスを宣言する必要がある。

[C++]
LPDIRECTDRAWSURFACE7 pFrontBuffer;
LPDIRECTDRAWSURFACE7 pBackBuffer;
LPDIRECTDRAWSURFACE7 pBackBufferLeft;

次に、ステレオ ビューをサポートするサーフェスを記述する DDSURFACEDESC2 構造体を準備する。

DDSURFACEDESC2 ddsd2 = {sizeof(ddsd2)};

ddsd2.dwFlags = DDSDS_CAPS|DDSD_BACKBUFFERCOUNT;
ddsd2.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE|
                       DDSCAPS_3DDEVICE;
ddsd2.dwBackBufferCount =1;
ddsd2.ddsCaps.dwCaps2 = DDSCAPS2_STEREOSURFACELEFT;
ddsd2.ddsCaps.dwCaps3 = ddsd2.ddsCaps.dwCaps4 =0;

DDSCAPS_PRIMARYSURFACE フラグが指定されていないと、サーフェスの記述で DDSCAPS2_STEREOSURFACELEFT を指定できない。これは、アプリケーションが別のサーフェスでステレオ フリッピング チェーンを作成し、IDirectDrawSurface7::AddAttachedSurface メソッドを呼び出してアタッチするのを防ぐためである。DDSCAPS2_STEREOSURFACELEFT が能力フラグとして指定されている場合、プライマリ チェーンの各バッファに 2 つのサーフェスが作成される。たとえば、dwBackBufferCount = N の場合、2 * (N+1) サーフェスが作成される。これらのサーフェスの一方には DDSCAPS2_STEREOSURFACELEFT 能力フラグが設定され、もう一方には設定されない。

[Visual Basic]
Dim ddsFrontBuffer As DirectDrawSurface7
Dim ddsBackBuffer As DirectDrawSurface7
Dim ddsBackBufferLeft As DirectDrawSurface7

次に、ステレオ ビューをサポートするサーフェスを記述する DDSURFACEDESC2 型を準備する。

Dim ddsd2 As DDSURFACEDESC2

ddsd2.lFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT
ddsd2.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE Or DDSCAPS_3DDEVICE
ddsd2.lBackBufferCount = 1
ddsd2.ddsCaps.lCaps2 = DDSCAPS2_STEREOSURFACELEFT
ddsd2.ddsCaps.lCaps3 = ddsd2.ddsCaps.lCaps4 = 0

DDSCAPS_PRIMARYSURFACE フラグが指定されていないと、サーフェスの記述で DDSCAPS2_STEREOSURFACELEFT を指定できない。これは、アプリケーションが別のサーフェスでステレオ フリッピング チェーンを作成し、DirectDrawSurface7.AddAttachedSurface メソッドを呼び出してアタッチするのを防ぐためである。DDSCAPS2_STEREOSURFACELEFT が能力フラグとして指定されている場合、プライマリ チェーンの各バッファに 2 つのサーフェスが作成される。たとえば、lBackBufferCount = N の場合、2 * (N+1) サーフェスが作成される。これらのサーフェスの一方には DDSCAPS2_STEREOSURFACELEFT 能力フラグが設定され、もう一方には設定されない。

サーフェスは、次の図に示すようにしてアタッチされ、ラベルが付けられる。

アプリケーションが DDSCAPS_3DDEVICE を指定すると、この能力フラグはチェーン内のすべてのサーフェスにコピーされるので注意すること。

[C++]

ここで、プライマリ サーフェスを作成する。

pDD7->CreateSurface(&ddsd2, &pFrontBuffer, NULL);

ddsd2.ddsCaps.dwCaps = DDSCAPS_BACKBUFFER;
pFrontBuffer->GetAttachedSurface(&ddsd2.ddsCaps, &pBackBuffer);

ddsd2.ddsCaps.dwCaps = 0;
ddsd2.ddsCaps.dwCaps2 = DDSCAPS2_STEREOSURFACELEFT;
pBackBuffer->GetAttachedSurface(&ddsd2.ddsCaps, &pBackBufferLeft);

上記のコードでは、IDirectDrawSurface7::GetAttachedSurface メソッドによって、ステレオ ビュー フリッピング チェーンにアタッチされたサーフェスを取得する。

while(running)
{
RenderRightImage(pBackBuffer);
RenderLeftImage(pBackBufferLeft);

pFrontBuffer->Flip(NULL,DDFLIP_WAIT|DDFLIP_STEREO);
}

上記のコードでは、アプリケーション定義関数 RenderRightImage および RenderLeftImage によって、ステレオ イメージをレンダリングする。

DDFLIP_STEREO フラグが IDirectDrawSurface7::Flip メソッドに渡されると、2 つのサーフェスがドライバに渡される。これらのサーフェスが、新しいステレオ ペアになる。DirectDraw は、DDSCAPS2_STEREOSURFACELEFT サーフェスがアタッチされたサーフェスでのみこのフラグを使用できる。

[Visual Basic]

ここで、プライマリ サーフェスを作成する。

Set ddsFrontBuffer = dd.CreateSurface(ddsd2)

ddsd2.ddsCaps.lCaps = DDSCAPS_BACKBUFFER
Set ddsBackBuffer = ddsFrontBuffer.GetAttachedSurface(ddsd2.ddsCaps)

ddsd2.ddsCaps.lCaps = 0
ddsd2.ddsCaps.lCaps2 = DDSCAPS2_STEREOSURFACELEFT
Set ddsBackBufferLeft = ddsBackBuffer.GetAttachedSurface(ddsd2.ddsCaps)

上記のコードでは、DirectDrawSurface7.GetAttachedSurface メソッドを使って、ステレオ ビュー フリッピング チェーンにアタッチされたサーフェスを取得する。

Do While g_bRunning

RenderRightImage ddsBackBuffer      ' 右のイメージをレンダリングする。
RenderLeftImage ddsBackBufferLeft   ' 左のイメージをレンダリングする。

ddsFrontBuffer.Flip Nothing, DDFLIP_WAIT Or DDFLIP_STEREO

Loop

上記のコードでは、アプリケーション定義関数 RenderRightImage と RenderLeftImage によって、ステレオ イメージをレンダリングする。

DDFLIP_STEREO フラグが DirectDrawSurface7.Flip メソッドに渡されると、2 つのサーフェスがドライバに渡される。これらのサーフェスが、新しいステレオ ペアになる。DirectDraw は、DDSCAPS2_STEREOSURFACELEFT サーフェスがアタッチされたサーフェスでのみこのフラグを使用できる。

DDFLIP_STEREO フラグが Flip メソッドに渡されなかった場合、ドライバに対するサーフェス フリッピング呼び出しによって 1 つのサーフェスだけが指定される。これにより、ステレオ ビューは必要ないことをドライバに示す。

フリッピング チェーンの詳細については、「フリッピング サーフェス」の概要のトピックを参照すること。


DMA サポートの利用

ここでは、特定のタスクでパフォーマンスを向上させるために、直接メモリ アクセス (DMA) をサポートするデバイスの利用方法について説明する。次の項目について記述する。

  • DMA デバイス サポートについて
  • DMA サポートのテスト
  • DMA の一般的シナリオ
  • DMA の使用


DMA デバイス サポートについて

システム メモリ サーフェスで、ブリット処理 (または他の処理) を実行できるディスプレイ デバイスもある。これらの処理は、通常、直接メモリ アクセス (DMA) 処理と呼ばれる。DMA サポートを利用すると、ある処理の組み合わせをアクセラレータできる。たとえば、このようなデバイスでは、次のフレームを準備するためにプロセスを使用している間、システム メモリからビデオ メモリへのブリットを実行できる。このような機能を使うには、ある応答が必要となる。ここでは、これらのタスクについて詳しく説明する。


DMA サポートのテスト

[C++]

DMA 処理を使用する前に、デバイスに対する DMA サポートをテストする必要がある。デバイスが DMA をサポートしている場合、どの程度のサポートが提供されるのかを調べる。まず、IDirectDraw7::GetCaps メソッドを呼び出してドライバ能力を取得する。次に、関連付けられた DDCAPS 構造体の dwCaps メンバに DDCAPS_CANBLTSYSMEM フラグがあるかどうかを調べる。このフラグが設定されていれば、デバイスが DMA をサポートしていることになる。

通常、DMA がサポートされることがわかると、ドライバが DMA をどの程度サポートするのかも調べなくてはならない。そのためには、システムからビデオ、ビデオからシステム、およびシステムからシステムへのブリット処理についての情報を持つ構造体の他のメンバを調べる。これらの能力は、ブリットとその能力タイプにより名付けられた 12 の DDCAPS 構造体メンバで提供される。次の表でこれらの新メンバを示す。

システムからビデオ | ビデオからシステム | システムからシステム
dwSVBCaps | dwVSBCaps | dwSSBCaps
dwSVBCKeyCaps | dwVSBCKeyCaps | dwSSBCKeyCaps
dwSVBFXCaps | dwVSBFXCaps | dwSSBFXCaps
dwSVBRops | dwVSBRops | dwSSBRops

たとえば、システムからビデオへのブリット能力フラグは、dwSVBCaps、dwSVBCKeyCaps、dwSVBFXCaps、および dwSVBRops メンバにより提供される。同様に、ビデオからシステムへのブリット能力は "dwVSB" で始まる名前のメンバにあり、システムからシステムへのブリット能力は "dwSSB" メンバにある。これらのメンバのフラグを調べると、ブリット カテゴリに対するハードウェア サポートのレベルを決定できる。

これらのメンバにあるフラグは、dwCaps、dwCKeyCaps、および dwFXCaps メンバのブリット タイプを考慮したこれらのメンバに含まれるブリット関連フラグと類似している。たとえば、dwSVBCaps メンバには、dwCaps メンバで調べたフラグと同じフラグで指定された一般的なブリット能力が含まれる。同様に、dwSVBRops、dwVSBRops、および dwSSBRops メンバにあるラスタ処理値は、与えられたタイプのブリット処理によりサポートされるラスタ処理についての情報を提供する。

これらのメンバにおける主要機能の 1 つは、非同期 DMA ブリット処理をサポートする。ドライバがサーフェス間の非同期 DMA ブリットをサポートする場合、dwSVBCaps、dwVSBCaps、または dwSSBCaps メンバに DDCAPS_BLTQUEUE フラグが設定される (通常、システム メモリからビデオ メモリ サーフェスに対する最良のサポートとなる)。このフラグがこれらのメンバにないと、ドライバでは非同期 DMA ブリット処理をサポートしない。

[Visual Basic]

DMA 処理を使用する前に、デバイスに対する DMA サポートをテストする必要がある。デバイスが DMA をサポートしている場合、どの程度のサポートが提供されるのかを調べる。まず、DirectDraw7.GetCaps メソッドを呼び出してドライバ能力を取得する。次に、関連付けられた DDCAPS 型の lCaps メンバに DDCAPS_CANBLTSYSMEM フラグがあるかどうかを調べる。このフラグが設定されていれば、デバイスが DMA をサポートしていることになる。

通常、DMA がサポートされることがわかると、ドライバが DMA をどの程度サポートするのかも調べなくてはならない。そのためには、システム カラービデオ、ビデオからシステム、およびシステム カラーシステムへのブリット処理についての情報を持つ構造体の他のメンバを調べる。これらの能力は、ブリットとその能力タイプにより名付けられた 12 の DDCAPS 構造体メンバで提供される。次の表でこれらの新メンバを示す。

システムからビデオ | ビデオからシステム | システムからシステム
lSVBCaps | lVSBCaps | lSSBCaps
lSVBCKeyCaps | lVSBCKeyCaps | lSSBCKeyCaps
lSVBFXCaps | lVSBFXCaps | lSSBFXCaps
lSVBRops | lVSBRops | lSSBRops

たとえば、システムからビデオへのブリット能力フラグは、lSVBCaps、lSVBCKeyCaps、lSVBFXCaps および lSVBRops メンバにより提供される。同様に、ビデオからシステムへのブリット能力は "ｌVSB" で始まる名前のメンバにあり、システムからシステムへのブリット能力は "ｌSSB" メンバにある。これらのメンバのフラグを調べると、ブリット カテゴリに対するハードウェア サポートのレベルを決定できる。

これらのメンバにあるフラグは、ｌCaps、ｌCKeyCaps、および ｌFXCaps メンバのブリット タイプを考慮したこれらのメンバに含まれるブリット関連フラグと類似している。たとえば、ｌSVBCaps メンバには、ｌCaps メンバで調べたフラグと同じフラグで指定された一般的なブリット能力が含まれる。同様に、ｌSVBRops、ｌVSBRops、および ｌSSBRops メンバにあるラスタ処理値は、与えられたタイプのブリット処理によりサポートされるラスタ処理についての情報を提供する。

これらのメンバにおける主要機能の 1 つは、非同期 DMA ブリット処理をサポートする。ドライバがサーフェス間の非同期 DMA ブリットをサポートする場合、ｌSVBCaps、ｌVSBCaps、または ｌSSBCaps メンバに DDCAPS_BLTQUEUE フラグが設定される (通常、システム メモリからビデオ メモリ サーフェスに対する最良のサポートとなる)。このフラグがこれらのメンバにないと、ドライバでは非同期 DMA ブリット処理をサポートしない。


DMA の一般的シナリオ

SRCCOPY ラスタ処理を利用するシステム メモリからビデオ メモリへの転送は、ハードウェアでサポートするブリット処理の典型的なタイプである (プラットフォーム SDK で説明する SRCCOPY ラスタ処理により、転送元矩形内のデータが転送先矩形に直接コピーできる)。このような処理における通常の利用では、次の処理の準備として、システム メモリ サーフェスの大きな集合からビデオ メモリ サーフェスにテクスチャを移動する。システムからビデオへの DMA 転送は、プロセッサ コントロール転送 (たとえば、HEL ブリット) とほぼ同じ速度であるが、ホスト プロセッサと並行に動作できるので非常に役立つ。


DMA の使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

ハードウェア転送では、アプリケーションでよく使う仮想アドレスではなく物理メモリ アドレスを使う。デバイス ドライバによっては、サーフェスの物理メモリ アドレスを要求することがある。この機構は、IDirectDrawSurface7::PageLock メソッドで実現される。デバイス ドライバがページ ロックを要求しない場合、IDirectDraw7::GetCaps メソッドを呼び出してハードウェア能力を取得するときに DDCAPS2_NOPAGELOCKREQUIRED フラグが設定される。

サーフェスをページ ロックすることで、システムがサーフェスの物理メモリが他の目的で使用されることを阻止できる。また、サーフェスの物理アドレスが、対応する IDirectDrawSurface7::PageUnlock が呼び出されるまで一定に維持されることも保証される。デバイス ドライバがページ ロックを要求する場合、DirectDraw では、アプリケーションがページ ロックしているシステム メモリ サーフェス上だけで非同期の DMA 処理を認める。このような状況で、IDirectDrawSurface7::PageLock を呼び出さない場合、DirectDraw はソフトウェア エミュレーションを使って転送を行う。大容量のシステム メモリをロックすると、Windows の動作が遅くなることに注意する。したがって、フルスクリーンの排他モード アプリケーションだけで、大容量のシステム メモリに対する IDirectDrawSurface7::PageLock を使い、このようなアプリケーションが最小化された場合に、そのサーフェスのロックを解除することを心掛けることが強く望まれる。もちろん、アプリケーションがリストアされると、システム メモリ サーフェスを再びページ ロックしなければならない。

ページ ロックの管理は、そのすべてをアプリケーション開発者の責任で行う。DirectDraw では、サーフェスをページ ロックしたりページ ロックを解除したりすることはない。つまり、開発者自身が、システム パフォーマンスを低下させることなく、どの程度のメモリを安全にページ ロックできるかを決定しなくてはならない。


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

[C++]

IDirectDrawPalette インターフェイス メソッドは、ディスプレイが排他 (フルスクリーン) モードである場合に、ハードウェアに直接書き込む。ただし、ディスプレイが非排他 (ウィンドウ) モードである場合は、IDirectDrawPalette インターフェイス メソッドが GDI パレット操作関数を呼び出して、他のウィンドウ アプリケーションと協調して作用する。

[Visual Basic]

DirectDrawPalette クラス メソッドは、ディスプレイが排他 (フルスクリーン) モードである場合に、ハードウェアに直接書き込む。ただし、ディスプレイが非排他 (ウィンドウ) モードである場合は、IDirectDrawPalette クラス メソッドが GDI パレット操作関数を呼び出して、他のウィンドウ アプリケーションと協調して作用する。

デスクトップが 8 ビットのパレット化モードで、作成者がプライマリ サーフェスや一般的なウィンドウの作成経験があることを想定して、次の項目について記述する。

  • ウィンドウ モードでのパレット エントリの設定
  • ウィンドウ モードでのパレットの作成
  • ウィンドウ モードでのパレット エントリの設定


ウィンドウ モードでのパレット エントリの設定

[C++]

フルスクリーン排他モード アプリケーションとは異なり、ウィンドウ アプリケーションはほかのアプリケーションとデスクトップ パレットを共有する必要がある。このため、どのパレット エントリを安全に修正でき、どのようにそれらを修正するのかについて、いくつかの制限がある。DirectDrawPalette オブジェクトや GDI に作用する場合に使用する PALETTEENTRY 構造体には、システムが PALETTEENTRY 構造体をどのように判断すべきかについて記述した情報を伝達する peFlags メンバが含まれる。

peFlags メンバは、次に説明する 3 つのタイプのパレット エントリを記述する。

[Visual Basic]

フルスクリーン排他モード アプリケーションとは異なり、ウィンドウ アプリケーションは他のアプリケーションとデスクトップ パレットを共有する必要がある。このため、どのパレット エントリを安全に修正でき、どのようにそれらを修正するのかについて、いくつかの制限がある。DirectDrawPalette オブジェクトや GDI に作用する場合に使用する PALETTEENTRY 型には、システムが PALETTEENTRY 型をどのように判断すべきかについて記述した情報を伝達する flags メンバが含まれる。

flags メンバは、次に説明する 3 つのタイプのパレット エントリを記述する。

  • Windows スタティック エントリ
  • アニメーション エントリ
  • 非アニメーション エントリ

Windows スタティック エントリ

通常モードでは、Windows はシステム カラーとして 0 から 9、および 246 から 255 までのパレット エントリを確保しており、メニュー バー、メニュー テキスト、およびウィンドウの境界などを表示するためにこれらのシステム カラーを使用する。アプリケーションの外観を一定に維持し、他のアプリケーションの外観を損なうことのないように、プライマリ サーフェスに設定したパレットのこれらのエントリを保護する必要がある。開発者が、GetSystemPaletteEntries Win32® 関数を呼び出してシステム パレット エントリを取得し、同一のエントリをカスタム パレットに明示的に設定した後、それをプライマリ サーフェスに割り当てる場合がある。カスタム パレットでシステム パレット エントリを複製したばかりなら作用するが、ユーザーがデスクトップ カラー スキームを変更すると無効になる。

ユーザーがカラー スキームを変更するときに、パレットが損なわれないようにするには、カラー値を指定するのではなく、システム パレットへの参照を提供することで該当するエントリを保護する。このようにして、与えられたエントリに対してシステムがどの色を使用していても、パレットは常に適合し、更新する必要はない。peFlags メンバで使用する PC_EXPLICIT フラグにより、システム パレット エントリを直接参照することができる。このフラグを使用する場合、システムは構造体の他のメンバに色情報があることを仮定しない。PC_EXPLICIT を使用する場合、peRed メンバに望ましいシステム パレット インデックスを設定し、他の色をゼロにする。

[C++]

たとえば、パレットの適切なエントリが常にシステムのカラー スキームに適合するようにするには、以下のコードを使用する。

// 最初と最後の 10 エントリを // システム パレットに適合するように設定する。
PALETTEENTRY pe[256];
ZeroMemory(pe, sizeof(pe));
for(int i=0;i<10;i++){
    pe[i].peFlags  = pe[i+246].peFlags = PC_EXPLICIT;
    pe[i].peRed = i;
    pe[i+246].peRed = i+246;
}

SetSystemPaletteUse Win32 関数を呼び出して、Windows が最初と最後のパレット エントリ (0 と 255) しか使用できないようにすることもできる。この場合、PALETTEENTRY 構造体の 0 と 255 のエントリだけを PC_EXPLICIT に設定する。

アニメーション エントリ

対応する PALETTEENTRY 構造体に PC_RESERVED フラグを使用することで、アニメーションするパレット エントリを指定できる。Windows では、他アプリケーションが論理パレット エントリを物理パレット エントリにマップさせない。このため、アプリケーションがパレットをアニメーションするときに、他のアプリケーションがその色を元に戻さないようにできる。

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

対応する PALETTEENTRY 構造体に PC_NOCOLLAPSE フラグを使用することで、アニメーションしない通常のパレット エントリを指定できる。PC_NOCOLLAPSE フラグは、他の割り当て済みの物理パレット エントリをそのエントリで置き換えないよう Windows に伝える。

[Visual Basic]

SetSystemPaletteUse Win32 関数を呼び出して、Windows が最初と最後のパレット エントリ (0 と 255) しか使用できないようにすることもできる。この場合、PALETTEENTRY 型の 0 と 255 のエントリだけを PC_EXPLICIT に設定する。

アニメーション エントリ

対応する PALETTEENTRY 型に PC_RESERVED フラグを使用することで、アニメーションするパレット エントリを指定できる。Windows では、他アプリケーションが論理パレット エントリを物理パレット エントリにマップさせない。このため、アプリケーションがパレットをアニメーションするときに、他のアプリケーションがその色を元に戻さないようにできる。

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

対応する PALETTEENTRY 型に PC_NOCOLLAPSE フラグを使用することで、アニメーションしない通常のパレット エントリを指定できる。PC_NOCOLLAPSE フラグは、他の割り当て済みの物理パレット エントリをそのエントリで置き換えないよう Windows に伝える。


ウィンドウ モードでのパレットの作成

[C++]

次の例で、非排他 (ウィンドウ) モードで DirectDraw パレットをどのように作成するかを示す。パレットを正しく作用させるために、IDirectDraw7::CreatePalette メソッドに渡した PALETTEENTRY 構造体の 256 エントリのそれぞれをセット アップすることがきわめて重要となる。

LPDIRECTDRAW7        lpDD; // 初期化されていると仮定する。
PALETTEENTRY         pPaletteEntry[256];
int                  index;
HRESULT              ddrval;
LPDIRECTDRAWPALETTE2 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);
[Visual Basic]

次の例で、非排他 (ウィンドウ) モードで DirectDraw パレットをどのように作成するかを示す。パレットを正しく作用させるために、DirectDraw7.CreatePalette メソッドに渡した PALETTEENTRY 型の 256 のエントリのそれぞれをセット アップすることがきわめて重要となる。

Dim pPaletteEntry(255) As PALETTEENTRY
Dim index As Long
Dim ddpal As DirectDrawPalette

' Windows スタティック エントリを設定する。
For index = 0 To 9
' 最初の 10 スタティック エントリ
        pPaletteEntry(index).flags = PC_EXPLICIT
        pPaletteEntry(index).red = index
        pPaletteEntry(index).green = 0
        pPaletteEntry(index).blue = 0

' 最後の 10 スタティック エントリ
pPaletteEntry(index + 246).flags = PC_EXPLICIT
pPaletteEntry(index + 246).red = index + 246
pPaletteEntry(index + 246).green = 0
pPaletteEntry(index + 246).blue = 0
Next

' ここで、プライベート エントリをセット アップする。この例では、
' 利用可能な最初の 16 エントリがアニメーションされる。
    For index = 10 To 25
        pPaletteEntry(index).flags = PC_NOCOLLAPSE Or PC_RESERVED
        pPaletteEntry(index).red = 255
        pPaletteEntry(index).green = 64
        pPaletteEntry(index).blue = 32
    Next

' ここで残りのエントリ (アニメーションしないエントリ) を ' セット アップする。
    For index = 26 To 246
        pPaletteEntry(index).flags = PC_NOCOLLAPSE
        pPaletteEntry(index).red = 25
        pPaletteEntry(index).green = 6
        pPaletteEntry(index).blue = 63
    Next

' すべての 256 エントリを埋め込む。パレットを作成する。
Set ddpal = dd.CreatePalette(DDPCAPS_8BIT, pPaletteEntry())


ウィンドウ モードでのパレット エントリの設定

[C++]

IDirectDraw7::CreatePalette メソッドで使用される PALETTEENTRY 構造体に適用される規則は、IDirectDrawPalette::SetEntries メソッドにも適用される。一般に、PALETTEENTRY 構造体の配列は開発者自身で維持するため、再構築の必要はない。再構築が必要となる場合は、配列を修正した後、パレットの更新時に IDirectDrawPalette::SetEntries を呼び出すこともできる。

多くの場合、非排他 (ウィンドウ) モードであらゆる 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])); // データを取得する場所。
[Visual Basic]

DirectDraw7.CreatePalette メソッドで使用される PALETTEENTRY 型に適用される規則は、DirectDrawPalette.SetEntries メソッドにも適用される。一般に、PALETTEENTRY 型の配列は開発者自身で維持するため、再構築の必要はない。再構築が必要となる場合は、配列を修正した後、パレットの更新時に DirectDrawPalette.SetEntries を呼び出すこともできる。

多くの場合、非排他 (ウィンドウ) モードであらゆる Windows スタティック エントリを設定するべきではない。このモードで設定してしまうと、予測不可能な結果が生じる。唯一の例外は、256 エントリをリセットする場合である。

通常、パレット アニメーションでは、PALETTEENTRY 配列の小さなサブセットだけを変更する。それらのエントリだけを DirectDrawPalette.SetEntries に渡すのである。このような小さいサブセットをリセットする場合は、PC_NOCOLLAPSE と PC_RESERVED フラグで記述されたエントリだけをリセットしなければならない。他のエントリをアニメーションしようとすると予測不可能な結果が生じる。


ビデオ ポート

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

DirectDraw ビデオ ポート拡張機能は、下位レベルのプログラミング インターフェイスであり、主流のマルチメディア プログラマ向けではない。ターゲットとなるカスタマーは、Microsoft DirectShow のような製品を作成する映像ソフト業界である。独自のソフトウェアにビデオ再生機能を付けたいと思う開発者も、ビデオ ポート拡張機能を利用できる。しかし、大部分のソフトウェアに対しては、DirectShow が提供するようなハイレベルのプログラミング インターフェイスの方がより使いやすい。

ここでは、DirectDrawVideoPort オブジェクトについて説明する。次の項目について記述する。

  • ビデオ ポートとは?
  • ビデオ ポート技術の概要
  • DirectDraw ビデオ ポート拡張機能について
  • ビデオ フレームとフィールド
  • HREF、VREF、およびコネクション
  • 垂直帰線消却間隔データ
  • 自動フリッピング
  • 共通のビデオの問題の回避方法
  • ハーフラインにより引き起こされる問題の解決
  • ハードウェア機能の利用


ビデオ ポートとは?

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

DirectDrawVideoPort オブジェクトは、ディスプレイ アダプタの種類により搭載されるビデオ ポート ハードウェアを表す。一般に、ビデオ ポート オブジェクトは、ビデオ ポート ハードウェアがビデオ デコーダから受け取るビデオ信号を、どのような方法でフレーム バッファに直接適用するかを制御する。

複数のビデオ チャネルは、必要な数だけ DirectDrawVideoPort オブジェクトを作成することにより制御される。個々のチャネルを個別に列挙したり構成できるので、個々のチャネルに対するビデオ ハードウェアは同一である必要はない。

詳細については、「ビデオ ポート技術の概要」を参照すること。


ビデオ ポート技術の概要

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

ビデオ ポートはディスプレイ デバイス上のハードウェアであり、CPU や PCI バスをバイパスして、フレーム バッファ内のサーフェスへ直接アクセスできる。直接フレーム バッファ アクセスは、CPU に著しい負担をかけることなく、ライブ ビデオまたは録音ビデオを効率的に再生できる。サーフェス内に入ってしまえば、イメージをオーバーレイとして表示したり、Direct3D テクスチャとして使用したり、キャプチャや他のプロセスから CPU にアクセスできる。次にこの技術を構成するコンポーネントやそのコンポーネントの動作方法についての一般論を説明する。

データ フロー

ビデオ ポートの装備されているマシンでは、ビデオ ストリームのデータが、ビデオ デコーダやビデオ ポートを通してビデオ ソースからフレーム バッファに直接フローする。通常、これらのコンポーネントは、ディスプレイ アダプタ上に共に存在するが、物理的に互いに接続された個別のハードウェア コンポーネント上に分散することもできる。次の図でこのデータフローの例を示す。

ビデオ ソース

ビデオ ポート技術では、ビデオ ソースは厳密にハードウェア ビデオ入力デバイスのことであり、ズーム ビデオ ポート、MPEG コーデック、あるいはその他のハードウェア ソースなどである。これらのソースは、ビデオ デコーダへの物理的なコネクションにより、NTSC、PAL、および SECAM を含むさまざまなフォーマットで信号をブロードキャストする。

ビデオ デコーダ

ビデオ デコーダもまた、ハードウェア コンポーネントである。ビデオ デコーダはビデオ ソースにより提供される情報を解読して、統一規格の接続フォーマットでそれをビデオ ポートに送る。デコーダはビデオ ポートへの物理的なコネクションを所有し、ストリーム クラス ミニドライバからそのサービスを公開する。デコーダはビデオ ポートにビデオ データ、ビデオ クロック、および同期情報を送らなくてはならない。

ビデオ ポート

データ フローパスの他のコンポーネントと同様、ビデオ ポートはハードウェアの 1 つである。ビデオ ポートはディスプレイ アダプタの VGA チップ上に存在し、フレーム バッファに直接アクセスできる。デコーダから送られる情報を受け取り、それを処理してから、表示するフレーム バッファに配置する。処理中に、ビデオ ポートはスケーリング、収縮、カラー コントロール、クロッピングなどのサービスを提供するイメージ データを処理できる。

フレーム バッファ

フレーム バッファは、ビデオ ポートから提供されるビデオ データを受け取る。そのデータを受け取ってしまえば、アプリケーションはイメージ データをプログラムに基づいて操作したり、他の位置にブリットしたり、またオーバーレイを利用してディスプレイ上に表示できる (頻繁に使用される)。


DirectDraw ビデオ ポート拡張機能について

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

DirectDraw は、DirectDrawVideoPort オブジェクトを含むために拡張された。このオブジェクトはビデオ ポート技術を利用して、IDDVideoPortContainer および IDirectDrawVideoPort インターフェイスからサービスを提供する。

DirectDrawVideoPort オブジェクトはビデオ デコーダを制御しない。それは、DirectDraw がビデオ ソースを制御するのではなく、ビデオ デコーダ自体のサービスを提供するからである。つまり、ビデオ ポートの範囲を超えているのである。むしろ、DirectDrawVideoPort オブジェクトは、ビデオ ポート自体を表す。このオブジェクトは、イメージの変更、フリッピングの実行、あるいは他のサービスの実行におけるインターフェイス メソッドから設定されるパラメータを使用することにより、入ってくる信号をモニタしたり、フレーム バッファにイメージ データを渡したりする。

IDirectDraw7::QueryInterface メソッドを呼び出すことで取得できる IDDVideoPortContainer インターフェイスは、その能力に対するハードウェアを照会したり、ビデオ ポート オブジェクトを作成するためのメソッドを提供する。ビデオ ポート オブジェクトを作成するには、IDDVideoPortContainer::CreateVideoPort メソッドを呼び出す。ビデオ ポート オブジェクトは、IDirectDrawVideoPort インターフェイスからその機能を明らかにして、ビデオ ポート ハードウェア自体を操作できるようにする。これらのインターフェイスを使うことにより、ビデオ ポートの能力を調べたり、イメージ データを受け取るオーバーレイ サーフェスを指定したり、ビデオの再生を開始/停止したり、クロッピング、カラー コントロール、スケーリング、収縮などのエフェクトをイメージ データに付けるために処理するハードウェア パラメータを設定できる。

DirectDraw ビデオ ポート拡張機能は、複数の DirectDrawVideoPort オブジェクトを作成することにより、同一マシン上に複数のビデオ ポートを提供する。同一マシン上の複数のビデオ ポートが同じである必要はない。つまり、個々のポートはハードウェアの違いの有無にかかわらず、個別に列挙され、別々に構成される。

DirectX の一般的な考えに従うこの技術により、プログラマはハードウェア機能へ下位レベルのアクセスを行うときに、これらの機能を特定のハードウェア実装の詳細から分離できる。ハイレベルの API ではない。


ビデオ フレームとフィールド

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

ビデオは、インターレイス方式でも非インターレイス方式でも可能である。ビデオ信号がインターレイス方式である場合、個々のビデオ フレーム はイメージ データの 2 つのフィールド からなる。各フィールドは、メージの最初または 2 番目の走査線から始まる 1 行おきの走査線の集合である。奇数フィールド (または、フィールド 1) と呼ばれる最初のフィールドには、最初の走査線とイメージの終わりまでの 1 行おきの走査線に対するデータが含まれる。同様に、偶数フィールド (または、フィールド 2) には、2 番目の走査線から始まる 1 行おきの走査線に対するデータが含まれる。フィールドの "偶数" または "奇数" は、フィールド極性と呼ばれる。

ビデオが非インターレイス方式である場合、個々のフィールドにはフレームの走査線すべてが含まれる。一般に、ビデオ信号は、毎秒 30 フレームの速度で送られる。インターレイス方式ビデオの場合、これは毎秒 60 フィールドの速度で送られる。

フレームを構成するフィールドは、時間で同じ瞬間を反映する必要はない。たとえば、そのフレームが 1/30 秒で区切られる場合、1 つのフレームにおける 2 つのフィールドは 1/60 秒で区切られていることになる。テレビでは個々のフィールドを個別に表示するため、2 つのフィールドが同時に見えることはなく、フィールド間の相違が動きに対するイリュージョンを生じる。


HREF、VREF、およびコネクション

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

モニタまたは他のディスプレイ デバイスがイメージを表示している場合、一般に左から右、上から下へイメージを作成して、スクリーンを下方にスキャンする (1 つのイメージを作成するのに、デバイスがスクリーンの下方へ 2 つずつスキャンすることもある。このタイプのディスプレイは、インターレイス方式ディスプレイと呼ばれる)。ビデオ ストリームには、新しいラインまたは新しいスクリーンを描画するときをディスプレイ デバイスに指示する信号が含まれる。

hsync および vsync とも呼ばれる HREF および VREF は、ディスプレイ デバイスに何をいつ行うかを知らせるビデオ ストリーム内の信号である。HREF は新しいラインを描画することを知らせ、VREF は新しいスクリーンを描画することを知らせる。

たとえば、世界最小のモニタ用ビデオ信号を取り扱っているとする。モニタには 4 走査線しかない (もちろん、これはまったく現実的ではないが、取り扱いが簡単になる)。オシロスコープでは、HREF および VREF 信号が次の図に示すようになるものと考えられる。

上記の図で、HREF および VREF 信号は共に "アクティブ ハイ" である。これは、これらの信号が強調状態 (波形が上昇するとき) のときに、アクティブになると考えられる。これらの信号に対する標準は存在しない。波形が下降する場所 ("ロー" 状態) でアクティブな HREF または VREF の信号を送る場合がある。また、一方がアクティブ ハイでもう一方がアクティブ ローであることもある。上記の図は想像上の例にすぎないが、個々の VREF に対して多数の HREF 信号が存在することに注意する。その理由は、個々の新しいスクリーンに対していくつかの走査線が存在するからである。もちろん、実際のブロードキャストに対する実際のビデオ信号では、1 つの VREF に対して数百の HREF が存在する。

HREF 信号、VREF 信号、およびビデオ データは、物理データ ラインを渡りデコーダからビデオ ポートまで伝達される。多くの場合、ビデオ データ用にいくつかのラインが確保されており、他のラインも HREF 信号や VREF 信号を伝達するための専用として使われている。ただし、これらのデータラインの使用についての標準はない。

コネクションは、ビデオ ポートやデコーダがこれらのデータ ラインの使用を定義するために使うプロトコルである。ビデオ ポートやビデオ デコーダは、さまざまなコネクションをサポートする。DirectDraw ビデオ ポート拡張機能は、GUID (globally-unique identifier) を使って個々のコネクション タイプを識別する。IDDVideoPortContainer::GetVideoPortConnectInfo メソッドを呼び出すことにより、ビデオ ポートがサポートするコネクションを照会できる。IDDVideoPortContainer::CreateVideoPort メソッドを呼び出すことにより、与えられたコネクションをサポートする DirectDrawVideoPort オブジェクトを作成できる。

ビデオ デコーダは DirectDraw ビデオ ポート拡張機能の範囲外であり、それ自体のインターフェイスからサポートされるコネクションを公開することを忘れてはならない。ビデオ ポートがサポートするコネクションを列挙して、その結果をデコーダのサポートするコネクションと比較することで、両方のコンポーネントで理解できる共通コネクション (あるいは、"言葉") を決めることができる。


垂直帰線消却間隔データ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

ブロードキャスト ビデオでは、ビデオ フレーム間に短い時間がある。この間に、ディスプレイ デバイスは次のフレームのためにディスプレイをリフレッシュする。この時間は、垂直帰線消却間隔 (VBI) と呼ばれる。ブロードキャスト ビデオは VBI の間に何もしないのではなく、ビデオ フレームにおける最初の 21 走査線のデータを符号化し、VBI の間にこれらの走査線を送る。このデータはクローズド キャプション (文字放送の一種) やタイムスタンプの記録に利用されることがあるが、他の目的に使うこともできる。

DirectDraw ビデオ ポート拡張機能により、VBI で含まれるデータをサーフェスに送ったり、VBI データのスケーリングをバイパスしたり、フリッピング チェーンの VBI サーフェス間で自動的にフリップすることができる。データがサーフェスに入ってしまえば、必要に応じてサーフェスのメモリに直接アクセスできる。

詳細については、「自動フリッピング」を参照すること。


自動フリッピング

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

フレーム間でスクリーンをリフレッシュするときにテアリング イメージの発生を避けるため、DirectDrawVideoPort オブジェクトは VREF 信号に応じて、そのターゲット オーバーレイ サーフェスを自動的にフリップすることができる。このサービスを利用するには、IDirectDrawVideoPort::SetTargetSurface メソッドでビデオ ポート オブジェクトに設定するターゲット サーフェスが、オーバーレイ サーフェスのフリッピング チェーンにおける最初のサーフェスでなけくてはならない。その後、ビデオ シーケンスを再生するには、関連付けられた DDVIDEOPORTINFO 構造体の dwVPFlags メンバに DDVP_AUTOFLIP フラグを指定して、IDirectDrawVideoPort::StartVideo メソッドを呼び出す。ビデオ ポート ブジェクトは、個々の VREF 信号の受け取りに対してフリッピング チェーンの次のサーフェスにフリップする。ビデオ ポートがインターリービングフィールドである場合、2 つの VREF 信号を受け取るごとに 1 回フリップする。

自動フリッピングを使い、個別の自動フリップ サーフェスに VBI データを送る場合、標準ビデオ サーフェスの場合と同じ数の VBI サーフェスを用意しなければならない。


共通のビデオの問題の回避方法

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

テレビ以外のディスプレイ デバイスで、ブロードキャスト ビデオを表示する場合、特有の問題がいくつか生じる。ここでは、いくつかの一般的な問題について簡単に触れ、続いて DirectDraw ビデオ ポート拡張機能がこれらの問題をどのように解決しようとしているかについて説明する。

NTSC インターレイス方式ディスプレイとインターリーブ メモリ

NTSC 信号は、毎秒約 30 フレーム、または 60 フィールドの速度でブロードキャストする。フレームと同様、NTSC 信号のフィールドはフレーム内の他のフィールドとは独立しており、異なるイメージ データを含むことができる。この動作の詳細については、「ビデオ フレームとフィールド」を参照すること。

フレーム内のフィールドの独立性に起因する問題は、2 つのフィールドがディスプレイに対してインターリーブされるときに生じる。動きの多いビデオでは、1 つのフレームにおける 2 つのフィールドで互いに適合しないイメージを含むことになり、動作異常が生じる。

この動作異常を回避するために、開発者はフィールドの 1 つを破棄するという方法をとることができる。この解決法ではイメージの質が約半分に落ちるが、目的によっては許容範囲内である。この解決法の他によくとられる方法は、表示する際に個々のフィールドを縦に 2 倍に伸ばして個別にフィールドを表示することである。この方法ではイメージの質はよくなるが、フィールドが y 方向に 1 ピクセル分オフセットされるため、アニメーションを再生するときに上下に "ジッター (ぶるぶる振動)" が生じる。

DirectDraw ビデオ ポート拡張機能では、イメージの質を改善するために、"Bob" および "Weave" と呼ばれる 2 つのより高度な技術を使うことができる。両方とも、ビデオ ポート拡張機能と共に使われる DirectDraw オーバーレイ サーフェスによりサポートされている。

最初のアルゴリズム Bob は、フレームの個々のフィールドを個別に表示するメソッドと非常に似ている。ただし、個々のフィールドに対して、オーバーレイの転送元矩形はジッター エフェクトに適応するように調整される。実際、転送元矩形は、スクリーン上のジッターを打ち消しながらフィールドと共に上下する。次の図でこのプロセスを示す。

Weave アルゴリズムは、動画をテレビに変換するためにビデオ産業界で使われる一般的な技術を使い、映画のオリジナル素材に対して最良のイメージ品質を提供する。Bob とは異なり、ビデオ ポート オブジェクトはそれ自体で組み立てていくことはない。このアルゴリズムを実現するには、両フィールドを同時に表示するデフォルト オーバーレイ動作と、カーネル モード ビデオ転送 (Windows NT 2000 と Windows 98 で提供される) を組み合わせなくてはならない。

完全を期すため、ここでアルゴリズムの概略を説明する。動画は、毎秒 24 フレームの速度でビデオがキャプチャされている。動画をテレビに変換する場合、技術者は 3:2 プルダウンと呼ばれる技術を使い、フレーム速度をテレビ放送用に毎秒 30 フレームに変換する。この技術では、必要とされるフィールド数にするために、ビデオ ストリームにおける 4 つの本物のフィールドごとに 1 つの冗長フィールドを挿入している。

組み立てる場合は、このプロセスを逆に行う。3:2 プルダウンが使用される場合、冗長フィールドを削除して元の動画フレームをリストアする。リストアされたフレームを構成するフィールドは、動作異常を生じることなくメモリでインターリーブすることができる。元のフィルム内の編集やリール破損のために、冗長フレームのパターンが変わる場合がある。これらの変化が生じるときにモニタし、動作を更新して新しいパターンに調整する必要がある。

デフォルトでは、オーバーレイ サーフェスは両フィールドを同時に表示する。Weave アルゴリズムを使用している場合はうまく機能するが、ビデオ ポートが Bob アルゴリズムを使用できなくなる。IDirectDrawSurface7::UpdateOverlay メソッドを呼び出すことにより、オーバーレイがビデオ データを処理する方法をプログラムに基づいて変更できる。オーバーレイの動作は、dwFlags パラメータのフラグにより決定される。DDOVER_BOB フラグを指定すると、ビデオ ポートは Bob アルゴリズムを使用する。フラグを指定しなければ、両フィールドを表示する。単に両フィールドを同時に表示すると、ビデオで動作異常が生じることに注意する。


ハーフラインにより引き起こされる問題の解決

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

ビデオ デコーダによっては、偶数フィールドの初めで意味のないデータのハーフラインを出力することがある。この余分なラインがフレーム バッファに書き込まれると、その結果で生じるイメージは歪曲したように見える。このような場合、フレーム バッファに書き込む前に、ビデオ ポート ハードウェアではこのデータを感知して破棄することができる。

IDDVideoPortContainer::GetVideoPortConnectInfo メソッドを使ってコネクション情報を取得する際に、ビデオ ポートがこのデータを破棄できるかどうかを決定できる。ビデオ ポートがハーフラインを破棄できない場合は、DDVPCONNECT_HALFLINE フラグが、サポートされる各コネクションに関連付けられた DDVIDEOPORTCONNECT 構造体の dwFlags メンバに指定される。

ビデオ ポートがハーフラインを破棄できない場合に、2 つのオプションが用意されている。フィールドの 1 つを破棄するか、ビデオ ポート オブジェクトの作成方法やターゲット オーバーレイ サーフェスでイメージを表示する方法を、いくらか調節してハードウェアの制限を回避する。

この問題を回避する方法を説明する。IDDVideoPortContainer::CreateVideoPort メソッドを呼び出してビデオ ポート オブジェクトを作成する場合、関連付けられた DDVIDEOPORTCONNECT 構造体の dwFlags メンバに、DDVPCONNECT_INVERTPOLARITY フラグを含める。これにより、ビデオ ポートはビデオ ストリームのフィールドの極性を反転し、偶数フィールドを奇数フィールドと同じように、または奇数フィールドを偶数フィールドと同じように処理する。反転されてしまうと、偶数フィールドの前のハーフラインは、各フレームの最初の走査線としてフレーム バッファに書き込まれる。意味のないデータを削除するには、必要な座標と共に IDirectDrawVideoPort::StartVideo メソッドを呼び出すことにより、イメージを表示するために使われるオーバーレイ サーフェスの転送元矩形を 1 ピクセル分だけ下に移動させる。この技術を使う場合、偶数フィールドを含むサーフェスに余分な 1 ラインを割り当てなくてはならないことに注意する。


ハードウェア機能の利用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic for DirectX 7.0 ではビデオ ポートをサポートしていない。

[C++]

ビデオ ポート ハードウェアによっては、色調整、イメージの縮小や拡大、VBI データ処理、フィールドのスキップなどの特別な機能をサポートする。HAL は、DDVIDEOPORTCAPS 構造体でフラグを使うことにより、これらの機能についての情報を提供する。マシンのビデオ ポート ハードウェアの能力を取得するには、IDDVideoPortContainer::EnumVideoPorts メソッドを呼び出す。

再生用のこれらの機能を利用するには、IDirectDrawVideoPort::StartVideo メソッドを使う。このメソッドは DDVIDEOPORTINFO 構造体を使い、イメージ データをフレーム バッファに配置したり表示する前に、そのデータを修正するためにハードウェア機能を要求する。この構造体に値やフラグを設定することにより、オーバーレイ サーフェスと共に使用される転送元矩形を指定したり、クロッピング領域を示したり、ハードウェア スケーリングを要求したり、ピクセル フォーマットを設定することができる。

DirectDrawVideoPort オブジェクトは、ビデオ ポート ハードウェア サービスをエミュレートしない。


リフレッシュ レートの列挙

DirectDraw は、モニタから拡張ディスプレイ識別データ (EDID) を読み出し、リフレッシュ レートを列挙する。EDID がないと、DirectDraw はステレオ ビューに必要な高いリフレッシュ レートを使用しようとする。DirectDraw によるステレオ ビューのサポートについては、「ステレオ ビュー」を参照すること。

特定のモードのリフレッシュ レートを取得する必要がある場合は、IDirectDraw7::StartModeTest および IDirectDraw7::EvaluateMode メソッドを使ってそのモードをテストできる。StartModeTest および EvaluateMode が EDID を調べて、モニタがサポートしているモードを確認し、特定のリフレッシュ レートが有効かどうかをユーザーがチェックできるようにすることができる。


フリッピングとブリットの状態取得

[C++]

IDirectDrawSurface7::Flip メソッドが呼び出されると、プライマリ サーフェスとバック バッファが交換される。ただし、この交換は直ぐに行われない。たとえば、前回のフリップが終了していないか成功しなかった場合、このメソッドは DDERR_WASSTILLDRAWING を返す。この SDK に含まれるサンプルでは、IDirectDrawSurface7::Flip の呼び出しは、DD_OK が返されるまでループし続ける。また、IDirectDrawSurface7::Flip の呼び出しも直ぐには完了しない。システムで垂直帰線消去が生じた後に、フリッピングが実行される。

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

前回のフリッピングが終了せずに、呼び出しで DDERR_WASSTILLDRAWING が返る場合、アプリケーションではステータスを再び調べる前に、他のタスクを実行できる。もしくは、次のフリッピングを実行できる。次の例でこの概念を説明する。

while(lpDDSBack->GetFlipStatus(DDGFS_ISFLIPDONE) ==
    DDERR_WASSTILLDRAWING);

    // 前回のフリッピングが終了するまで待つ。アプリケーションは、
    // ここで別のタスクを実行することができる。

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

ブリットが終了したかどうかを判断するために、同じような方法で IDirectDrawSurface7::GetBltStatus メソッドを使うことができる。IDirectDrawSurface7::GetFlipStatus と IDirectDrawSurface7::GetBltStatus はすぐに返るため、アプリケーションで周期的に使用しても、ほとんど速度は低下しない。

[Visual Basic]

DirectDrawSurface7.Flip メソッドが呼び出されると、プライマリ サーフェスとバック バッファが交換される。ただし、この交換は直ぐに行われない。たとえば、前回のフリップが終了していないか成功しなかった場合、このメソッドは DDERR_WASSTILLDRAWING エラーを返す。

DDERR_WASSTILLDRAWING が返されなくなるまで待つアプリケーションは効率が悪い。代わりに、フリッピングが終了したかどうかを決定するバック バッファで DirectDrawSurface7.GetFlipStatus メソッドを呼び出すアプリケーションの関数を作成するべきである。

前回のフリッピングが終了せずに、呼び出しで DDERR_WASSTILLDRAWING が返る場合、アプリケーションではステータスを再び調べる前に、他のタスクを実行できる。もしくは、次のフリッピングを実行できる。次の例でこの概念を説明する。

while(DDSBack.GetFlipStatus(DDGFS_ISFLIPDONE) =
    DDERR_WASSTILLDRAWING)

' 前回のフリッピングが終了するまで待つ。アプリケーションは、
' ここで別のタスクを実行することができる。

DDSPrimary->Flip(NOTHING, 0)

ブリットが終了したかどうかを判断するために、同じような方法で DirectDrawSurface7.GetBltStatus メソッドを使うことができる。DirectDrawSurface7.GetFlipStatus と DirectDrawSurface7.GetBltStatus はすぐに返るため、アプリケーションで周期的に使用しても、ほとんど速度は低下しない。


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

DirectDraw はユーザーのハードウェアがサポートしない DirectDraw 関数を実行するために、ソフトウェア エミュレーションを使う。DirectDraw アプリケーションのパフォーマンスを向上させるには、DirectDraw オブジェクトを作成した後で、ユーザーのディスプレイ ハードウェアの能力を決定する。その後、可能であれば、これらの能力を利用するプログラムを構築する。

[C++]

この能力を決定するには、IDirectDraw7::GetCaps メソッドを使用する。すべてのハードウェア機能がエミュレーションでサポートされるわけではない。ある特定のハードウェアだけでサポートされる機能を利用するには、その機能のないハードウェアのシステムに対して、何らかの代わりの手段を提供する準備も必要である。

[Visual Basic]

この能力を決定するには、DirectDraw7.GetCaps メソッドを使用する。すべてのハードウェア機能がエミュレーションでサポートされるわけではない。ある特定のハードウェアだけでサポートされる機能を利用するには、その機能のないハードウェアのシステムに対して、何らかの代わりの手段を提供する準備も必要である。


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

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

[C++]

多くのディスプレイ アダプタ ハードウェアには、プライマリ サーフェスとバック バッファ以外を格納する十分なメモリがある。ディスプレイ アダプタのメモリにビットマップを格納する利用可能なメモリ容量を決定するには、IDirectDraw7::GetAvailableVidMem メソッドを呼び出す。このメソッドの呼び出し後、lpdwTotal パラメータには、全ディスプレイ メモリ量 (ドライバで保持するプライマリ サーフェスとプライベート キャッシュを除く) が含まれる。そして、lpdwFree パラメータには、現在のディスプレイ メモリの空き容量が含まれる。この空き容量は、lpDDSCaps2 で構造体により指定される能力を適合するサーフェスに割り当てられる。

[Visual Basic]

多くのディスプレイ アダプタ ハードウェアには、プライマリ サーフェスとバック バッファ以外を格納する十分なメモリがある。ディスプレイ アダプタのメモリにビットマップを格納する利用可能なメモリ容量を決定するには、DirectDraw7.GetAvailableTotalMem メソッドを呼び出す。このメソッドは、DDSCAPS2 型で指定された能力と一致するサーフェスの全ディスプレイ メモリ量 (ドライバで保持するプライマリ サーフェスとプライベート キャッシュを除く) を返す。


トリプル バッファリング

[C++]

ある特定の状況、すなわちディスプレイ アダプタに十分なメモリがある場合には、トリプル バッファリングにより、アプリケーションの表示処理を高速化できる。トリプル バッファリングは、1 つのプライマリ サーフェスと 2 つのバック バッファを使用する。次の例で、トリプル バッファリング スキームを初期化する方法を示す。

// lpDDSPrimary と lpDDSBack 変数は、グローバルに宣言した
// 初期化していない LPDIRECTDRAWSURFACE4 変数である。
//
// lpDD 変数は、IDirectDraw4 インターフェイスへのポインタである。

DDSURFACEDESC2 ddsd;
ZeroMemory (&ddsd, sizeof(ddsd));

// 2 つのバック バッファと共にプライマリ サーフェスを作成する。
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)
{
// プライマリ (バック バッファ) に直接アタッチされる // サーフェスを取得する。
    ddsd.ddsCaps.dwCaps = DDSCAPS_BACKBUFFER;
    ddrval = lpDDSPrimary->GetAttachedSurface(&ddsd.ddsCaps,
        &lpDDSBack);
    if(ddrval != DD_OK) ;
// ここでエラー メッセージを表示する。
}

トリプル バッファのフリッピング チェーンにあるサーフェスについて、そのすべてを調査する必要はない。保持していなければならないのは、プライマリ サーフェスとバックバッファ サーフェスへのポインタだけである。プライマリ サーフェスへのポインタは、フリッピング チェーンのサーフェスをフリップするために必要となる。また、バック バッファへのポインタは、ブリットのために必要である。詳細については、「フリッピング サーフェス」を参照すること。

フリッピングが終了せずに、バック バッファのブリットが既に終了している場合、トリプル バッファリングにより、アプリケーションはバック バッファにブリットし続けることができる。フリッピングの実行は同期イベントではない。つまり、あるフリッピングに他のフリッピング以上の時間をとることができる。このため、アプリケーションが 1 つのバック バッファだけを使う場合、IDirectDrawSurface7::Flip メソッドが DD_OK を返すまで待つ間、アイドリング時間がかかる可能性がある。

[Visual Basic]

ある特定の状況、すなわちディスプレイ アダプタに十分なメモリがある場合には、トリプル バッファリングにより、アプリケーションの表示処理を高速化できる。トリプル バッファリングは、1 つのプライマリ サーフェスと 2 つのバック バッファを使用する。次の例で、トリプル バッファリング スキームを初期化する方法を示す。

' DDSPrimary と DDSBack 変数は、
' グローバルに宣言した DIRECTDRAWSURFACE7 変数である。
'
' DD 変数は、DirectDraw7 オブジェクトである。

Dim ddsd As DDSURFACEDESC2

' 2 つのバック バッファと共にプライマリ サーフェスを作成する。
ddsd.lFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT
ddsd.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE Or _
DDSCAPS_FLIP Or DDSCAPS_COMPLEX
ddsd.lBackBufferCount = 2
DDSPrimary = DD.CreateSurface(ddsd)

' フリッピング チェーンの作成に成功すると、
' フリッピングとブリットに必要なサーフェスを取得する。
' プライマリ (バック バッファ) に直接アタッチされるサーフェスを取得する。
ddsd.ddsCaps.lCaps = DDSCAPS_BACKBUFFER
DDSBack = DDSPrimary.GetAttachedSurface(ddsd.ddsCaps)

トリプル バッファのフリッピング チェーンにあるサーフェスについて、そのすべてを調査する必要はない。保持していなければならないのは、プライマリ サーフェスとバックバッファ サーフェスへのポインタだけである。プライマリ サーフェスへのポインタは、フリッピング チェーンのサーフェスをフリップするために必要となる。また、バック バッファへのポインタは、ブリットのために必要である。詳細については、「フリッピング サーフェス」を参照すること。

フリッピングが終了せずに、バック バッファのブリットが既に終了している場合、トリプル バッファリングにより、アプリケーションはバック バッファにブリットし続けることができる。フリッピングの実行は同期イベントではない。つまり、あるフリッピングに他のフリッピング以上の時間をとることができる。このため、アプリケーションが 1 つのバック バッファだけを使う場合、DirectDrawSurface7.Flip メソッドが成功するまで待つ間、アイドリング時間がかかる場合がある。


DirectDraw アプリケーションとウィンドウ スタイル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

アプリケーションがウィンドウ モードで DirectDraw を使う場合、あらゆるウィンドウ スタイルを作成することができる。ただし、フルスクリーン排他モードのアプリケーションでは、予測不可能な動作を生じることなく WS_EX_TOOLWINDOW スタイルを作成することができない。WS_EX_TOOLWINDOW スタイルでは、ウィンドウを DirectDraw のフルスクリーン排他モード アプリケーションで必要とされる最上位ウィンドウとすることができない。

フルスクリーン排他モード アプリケーションでは、適切な表示をするために、WS_EX_TOPMOST 拡張ウィンドウ スタイルと WS_VISIBLE ウィンドウ スタイルを使うようにする。これらのスタイルは、このアプリケーションをウィンドウ Z オーダーの最前列に維持して、GDI がプライマリ サーフェスに描画するのを阻止する。

次の例では、フルスクリーン排他モード アプリケーションで使うウィンドウを確実に準備する方法を示す。

////////////////////////////////////////////////////////
// ウィンドウ クラスの登録とウィンドウの表示
////////////////////////////////////////////////////////
BOOL WINAPI InitApp(INT nWinMode)
{
    WNDCLASSEX wcex;

    wcex.cbSize           =    sizeof(WNDCLASSEX);
    wcex.hInstance        =    g_hinst;
    wcex.lpszClassName    =    g_szWinName;
    wcex.lpfnWndProc      =    WndProc;
    wcex.style            =    CS_VREDRAW|CS_HREDRAW|CS_DBLCLKS;
    wcex.hIcon            =    LoadIcon (NULL, IDI_APPLICATION);
    wcex.hIconSm          =    LoadIcon (NULL, IDI_WINLOGO);
    wcex.hCursor          =    LoadCursor (NULL, IDC_ARROW);
    wcex.lpszMenuName     =    MAKEINTRESOURCE(IDR_APPMENU);
    wcex.cbClsExtra       =    0 ;
    wcex.cbWndExtra       =    0 ;
    wcex.hbrBackground    =    GetStockObject (NULL_BRUSH);

    RegisterClassEx(&wcex);

    g_hwndMain = CreateWindowEx(
                        WS_EX_TOPMOST,
                        g_szWinName,
                        g_szWinCaption,
                        WS_VISIBLE|WS_POPUP,
                        0,0,0,0,
                        NULL,
                        NULL,
                        g_hinst,
                        NULL);

    if(!g_hwndMain)
        return(FALSE);

    SetFocus(g_hwndMain);
    ShowWindow(g_hwndMain, nWinMode);
    UpdateWindow(g_hwndMain);

    return TRUE;
}


フレーム バッファの色空間へのトゥルー RGB 色の適合

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

ディスプレイ デバイスがトゥルー RGB 色 (RGB 888) モードでないときに、アプリケーションでは、フレーム バッファの色空間に RGB 888 をマップする方法を見つけ出すことが必要となる場合がある。たとえば、16 ビットまたは 24 ビット RGB ディスプレイ モードで実行するアプリケーションの場合を考える。ある作品が作成されると、透過型ブリット カラー キーとして使用するために色が確保される。説明のために、ここでは RGB (128,64,255) のような 24 ビット カラーとする。アプリケーションが 16 ビット RGB モードでも実行できるようにするために、16 ビット RGB モードで実行する場合に使用するフレーム バッファの色空間にこの 24 ビットカラーをマップする方法を見つけ出す必要がある。

DirectDraw ではカラー マッチング サービスを行わないが、カラー キーがフレーム バッファにマッピングされる計算におけるいくつかの方法が用意されている。これらの方法は、いずれもかなり複雑である。ほとんどの場合、GDI 内蔵のカラーマッチング サービスを DirectDraw 直接フレーム バッファ アクセスと組み合わせて使用することで、色の値を異なる色空間にマップする方法を決定できる。実際、プラットフォーム SDK の DirectX の例にある Ddutil.cpp ソース ファイルには、このタスクを実行する DDColorMatch というサンプル関数が含まれている。DDColorMatch サンプル関数は、以下の主なタスクを行う。

  1. サーフェスの 0,0 にあるピクセルの色の値を取得する。
  2. 24 ビット RGB 色を記述する COLORREF 構造体を使用して、Win32 SetPixel 関数を呼び出す。
  3. DirectDraw を使用してサーフェスをロックし、フレーム バッファ メモリへのポインタを取得する。
  4. フレーム バッファ (GDI によりステップ 2 で設定された) から実際の色の値を取得し、サーフェスのロックを解除する。
  5. SetPixel を使って、0,0 のピクセルを元の色にリセットする。

DDColorMatch サンプル関数で使用されるプロセスは速くない。速さを意図したものではないからである。ただし、色を異なる RGB 色空間にマップする方法を決定するには信頼性の高い方法である。詳細については、Ddutil.cpp ソース ファイルにある DDColorMatch のソース コードを参照すること。

注 ： SetPixel GDI 関数は入力に対する COLORREF 構造体を受け取るだけなので、この技術は RGB 888 カラーをフレーム バッファのピクセル フォーマットに適合するためだけに作用する。アプリケーションで他のピクセル フォーマットの色を適合しなくてはならない場合、この技術を使用したり、ピクセル フォーマットに対するプライマリ サーフェスを参照する前に、RGB 888 に転送して、手動で色を適合しなければならない。


フルスクリーン モードでのウィンドウの表示

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

フルスクリーン モードでは、DirectDraw は表示を排他的に制御する。このため、GDI によって作成されるダイアログ ボックスやその他のウィンドウは通常表示されない。ただし、特殊な方法を使用すれば、Windows のダイアログ ボックス、HTML ヘルプや、アプリケーション内のその他のウィンドウを表示することができる。

FSWindow サンプルでは、フルスクリーン アプリケーションでダイアログ ボックスを表示および更新する方法や、GDI によって表示されたダイアログ ボックスと同様にマウスやキーボード入力を受け付ける方法を示す。

FSWindow では、通常のダイアログ ウィンドウと同様にダイアログ ボックスが作成されて表示される。

hWndDlg = CreateDialog(g_hInstance,
MAKEINTRESOURCE(IDD_DIALOG_SAMPLE),
hWnd, (DLGPROC) SampleDlgProc);
ShowWindow(hWndDlg, SW_SHOWNORMAL);

もちろん、この時点では、ダイアログ ボックスは隠れている GDI サーフェスによって表示され、Direct Draw によって制御されるプライマリ サーフェスには表示されない。

ハードウェア能力に DDCAPS2_CANRENDERWINDOWED が含まれる場合、(「DDCAPS」参照) ダイアログ ボックスの表示と更新を容易に実行できる。アプリケーションは、IDirectDraw7::FlipToGDISurface メソッドを呼び出すだけで、GDI サーフェスをプライマリ サーフェスにすることができる。それ以後は、GDI が直接フロント バッファにレンダリングされるので、ダイアログ ボックスに対する変更はすべて自動的に表示される。アプリケーションはバック バッファへのレンダリングを続け、各パス上でレンダリング ループによって DirectDraw がバック バッファの内容をフロント バッファにブリットする。フロント バッファがアプリケーション ウィンドウにクリップされ、ダイアログ ボックスがそのウィンドウの一部を覆い隠すので、ダイアログ ボックスが上書きされることはない。

以下のコードは FSWindow_Init 関数の一部である。これにより、クリッパーを作成し、アプリケーション ウィンドウに関連付けて、GDI サーフェスを前面に表示する。

if (ddObject->CreateClipper(0, &ddClipper, NULL) == DD_OK)
ddClipper->SetHWnd(0, hwndAppWindow);
ddObject->FlipToGDISurface();

次に、FSWindow_Update 関数の以下のコードによって、レンダリングされたバック バッファのコンテンツをクリッピング領域にブリットする。

ddFrontBuffer->SetClipper(ddClipper);
ddFrontBuffer->Blt(NULL, ddBackBuffer, NULL, DDBLT_WAIT, NULL);

GDI サーフェスがプライマリ サーフェスなので、Windows によってマウス カーソルが表示される (ただし、アプリケーションが排他協調レベルでマウスによる直接入力を使用している場合は除く)。

DDCAPS2_CANRENDERWINDOWED 能力を持たないハードウェアでは、フルスクリーン モードでのウィンドウの表示と更新処理がやや複雑になる。この場合、GDI によって作成されたウィンドウのイメージをアプリケーションが取得し、フルスクリーン レンダリングが実行された後でバック バッファにブリットする。その後で、バック バッファ全体が通常の方法でフロントにフリップされる。

FSWindow サンプルでは、コンテンツが静的であるか動的であるかに応じて、ウィンドウのディスプレイ メモリにアクセスする 2 つの方法を示す。静的コンテンツの方法の方が、スクリーン デバイス コンテキストではなくメモリ デバイス コンテキストからブリットを行うので、より高速になる。情報表示用のダイアログ ボックスなど、変更しないウィンドウにはこの方法を使用すべきである (ただし、イベントに応答するビットマップを手動で更新しない限り、ボタンが押された状態になるような基本的なアニメーションもユーザーには表示されないので注意すること)。

静的コンテンツの場合、ウィンドウの初期化時に FSWindow が CreateBMPFromWindow 関数を呼び出す。この関数は、ビットマップを作成し、ウィンドウのコンテンツをそのビットマップにブリットする。ビットマップ ハンドルはグローバル変数 hwndFSWindowBMP に格納される。以下に示すように、プライマリ サーフェスを更新しようとすると、常にこのビットマップがバック バッファにブリットされる。

if (FSWindow_IsStatic)
{
hdcMemory = CreateCompatibleDC(NULL);
SelectObject(hdcMemory, hwndFSWindowBMP);
BitBlt(hdcBackBuffer, x, y, cx, cy, hdcMemory, 0, 0, SRCCOPY);
DeleteDC(hdcMemory);
}

これに対し、動的コンテンツの場合は次のコードが実行される。この場合、イメージが GDI サーフェス (hdcScreen デバイス コンテキストで表される) から直接バック バッファにブリットされる。

BitBlt(hdcBackBuffer, x, y, cx, cy, hdcScreen, x, y, SRCCOPY);

上記の座標は、GetWindowRect を呼び出すことによって取得される、GDI サーフェス上のウィンドウの位置とサイズを表す。

DDCAPS2_CANRENDERWINDOWED 能力を持たないハードウェアで FSWindow アプリケーションを実行する場合、GDI サーフェスを使用しないので、Windows はマウス カーソルを表示できない。アプリケーションは、カーソルに関する情報を取得し、フリップの直前のバック バッファ上にその情報を配置することにより、カーソルを表示する。


DirectDraw チュートリアル

ここでは、DirectDraw の基本的な機能を C/C++ または Visual Basic アプリケーションに実装する方法についてステップ バイ ステップで説明するチュートリアルを提供する。各チュートリアルは、この SDK の \Samples\Multimedia\DDraw\Tutorials ディレクトリで提供される一連のサンプル ファイルと対応し、コードの流れに沿って説明する。サンプル コードを参照しながらチュートリアルを読み進めていくことを勧める。

  • DirectDraw C/C++ チュートリアル
  • DirectDraw Visual Basic チュートリアル


DirectDraw C/C++ チュートリアル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

ここでは、次のチュートリアルを使用して、簡単な DirectDraw アプリケーションを実装する方法をステップ バイ ステップで説明する。各チュートリアルは、この SDK が提供する DirectDraw サンプル ファイルを多く使用している。これらのサンプルでは、DirectDraw のセットアップ方法と、一般的なタスクを実行するための DirectDraw メソッドの使用方法を紹介する。

  • チュートリアル 1 : DirectDraw の基礎
  • チュートリアル 2 : バック バッファへのビットマップのロード
  • チュートリアル 3 : オフスクリーン サーフェスからのブリット
  • チュートリアル 4 : カラー キーとビットマップ アニメーション
  • チュートリアル 5 : パレットの動的変更
  • チュートリアル 6 : オーバーレイ サーフェスの使用

注 ： これらのチュートリアルのサンプル ファイルは、C++ で記述されている。C コンパイラを使う場合、うまくコンパイルできるようにファイルを適切に変更する必要がある。少なくとも、インターフェイス メソッドに vtable および this ポインタを追加する必要がある。


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

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

DirectDraw を使用するには、まず始めに、コンピュータ上のディスプレイ アダプタを表す DirectDraw オブジェクトのインスタンスを作成しなければならない。そして、インターフェイス メソッドを使用して、そのオブジェクトを操作する。さらに、アプリケーションをグラフィックス サーフェス上に表示するには、DirectDrawSurface オブジェクトのインスタンスを 1 つ以上作成する必要がある。

これを説明するために、この SDK にある DDEx1 サンプル を次のステップで実行する。

  • ステップ 1 : DirectDraw オブジェクトの作成
  • ステップ 2 : アプリケーション動作の決定
  • ステップ 3 : ディスプレイ モードの変更
  • ステップ 4 : フリッピング サーフェスの作成
  • ステップ 5 : サーフェスへの書き込み
  • ステップ 6 : サーフェスのフリップ
  • ステップ 7 : DirectDraw オブジェクトの割り当て解除

注 ： アプリケーションで GUID をうまく利用するには、他のすべての include 文や define 文の前に INITGUID を定義するか、Dxguid.lib ライブラリにリンクする必要がある。INITGUID の定義は、ソース モジュール中の 1 つだけにする。


ステップ 1 : DirectDraw オブジェクトの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

DirectDraw オブジェクトのインスタンスを作成するには、DDEx1 プログラムの InitApp サンプル関数で示されているように、アプリケーションで DirectDrawCreateEx 関数を使うようにする。DirectDrawCreateEx には 4 つのパラメータがある。最初のパラメータは、ディスプレイ デバイスを表すグローバル ユニーク識別子 (GUID) とする。ほとんどの場合、GUID は NULL に設定され、DirectDraw がシステムのデフォルト ディスプレイ ドライバを使用することを意味する。2 番目のパラメータは、作成された DirectDraw オブジェクトの位置を識別するポインタのアドレスである。3 番目のパラメータは、IDirectDraw7 インターフェイスの参照識別である。このパラメータは IID_IDirectDraw7 に設定する必要がある。4 番目のパラメータは常に NULL に設定され、将来の拡張機能に備える。

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

hRet = DirectDrawCreateEx(NULL, (VOID**)&g_pDD, IID_IDirectDraw7, NULL);
if(hRet == DD_OK)
{
    // g_pDD は有効な DirectDraw オブジェクトである。
}
else
{
    // DirectDraw オブジェクトは作成できなかった。
}

次項 :ステップ 2 : アプリケーション動作の決定


ステップ 2 : アプリケーション動作の決定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

ディスプレイの解像度を変更する前に、少なくとも IDirectDraw7::SetCooperativeLevel メソッドの dwFlags パラメータに DDSCL_EXCLUSIVE および DDSCL_FULLSCREEN フラグを指定する必要がある。これにより、アプリケーションがディスプレイ デバイスを完全に制御できるようになり、他のアプリケーションがディスプレイ アダプタを共有できなくなる。さらに、DDSCL_FULLSCREEN フラグで、アプリケーションを排他 (フルスクリーン) モードに設定する。アプリケーションはデスクトップ全体をカバーしており、アプリケーションだけがスクリーンに書き込むことができる。ただし、デスクトップは利用可能なままである(排他モードで実行するアプリケーションのデスクトップを見るには、DDEx1 を起動して ALT + TAB を押す)。

次の例では、SetCooperativeLevel メソッドの使用方法を示す。

HRESULT       hRet;
LPDIRECTDRAW7 g_pDD;   // 既に DirectDrawCreateEx によって作成されている。

hRet = g_pDD->SetCooperativeLevel(hWnd, DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN);
if (hRet != DD_OK)
{
    // 排他モードは成功した。
}
else
{
    // 排他モードは失敗した。
    // ただし、アプリケーションは実行したままである。
}

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

フルスクリーン (排他協調レベル) を設定している場合、アプリケーションの異常終了を Microsoft® Windows® で判断できるように、アプリケーションのウィンドウ ハンドルを SetCooperativeLevel に渡す。たとえば、一般保護 (GP) エラーが発生し、グラフィックス デバイス インターフェイス (GDI) がバック バッファにフリップされる場合、ユーザーは Windows スクリーンに戻れなくなる。このエラーの発生を回避するために、DirectDraw は、アプリケーション ウィンドウに送られるメッセージをトラップするバックグラウンドで実行するプロセスを提供する。アプリケーションが終了するときに、DirectDraw はこれらのメッセージを使用して判断する。ただし、この機能にはいくつかの制限がある。アプリケーションに対するメッセージを取得するウィンドウ ハンドルを指定する必要がある。つまり、他にもウィンドウを作成する場合、アクティブなウィンドウを指定したことを確認する必要がある。これを指定しないと、GDI で予測不可能な動作が生じたり、Alt + Tab を押しても応答がないといった問題が生じることになる。

次項 :ステップ 3 : ディスプレイ モードの変更


ステップ 3 : ディスプレイ モードの変更

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションの動作を設定した後で、IDirectDraw7::SetDisplayMode メソッドを使ってディスプレイの解像度を変更できる。次の例は、ディスプレイ モードを 640 ｴ 480 ｴ 8 bpp に設定する方法を示す。

HRESULT       hRet;
LPDIRECTDRAW7 g_pDD;   // 既に DirectDrawCreateEx によって作成されている。

hRet = g_pDD->SetDisplayMode(640, 480, 8, 0, 0);
if (hRet != DD_OK)
{
// ディスプレイ モードの変更は成功した。
}
else
{
// ディスプレイ モードは変更できなかった。
// モードがサポートされていないか、他のアプリケーションが
// 排他モードになっている。
}

ディスプレイ モードを設定する場合、ユーザーのハードウェアが高解像度をサポートしていないときに、アプリケーションが大部分のディスプレイ アダプタでサポートされる標準モードに戻れるようにする。たとえば、アプリケーションは、標準バックアップ解像度として 640 × 480 × 8 をサポートするすべてのシステムで実行できるように設計できる。

注 ： 要求される解像度にディスプレイ アダプタを設定できない場合、IDirectDraw7::SetDisplayMode は DDERR_INVALIDMODE エラーを返す。したがって、ディスプレイ モードを設定する前に、IDirectDraw7::EnumDisplayModes メソッドを使ってユーザーのディスプレイ アダプタの能力を決めておかなければならない。

次項 :ステップ 4 :フリッピング サーフェスの作成


ステップ 4 : フリッピング サーフェスの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

ディスプレイ モードを設定した後、アプリケーションを配置するサーフェスを作成しなければならない。DDEx1 の例では、IDirectDraw7::SetCooperativeLevel メソッドを使用して排他 (フルスクリーン) モードを設定する。この結果、サーフェス間でフリップするサーフェスを作成できる。SetCooperativeLevel を使って DDSCL_NORMAL にモードを設定した場合、サーフェス間でブリットするサーフェスだけを作成することができる。フリッピング サーフェスを作成するには、以下のステップ (このステップについては、次に説明する) が必要となる。

  • ステップ 4.1 : サーフェス要件の定義
  • ステップ 4.2 : サーフェスの作成


ステップ 5 : サーフェスへの書き込み

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

プライマリ サーフェスとバック バッファが作成されると、DDEx1 の例では、標準の Windows GDI 関数を使用してバック バッファ サーフェス上に何らかのテキストを書き込む。次に例を示す。

    if (g_pDDSBack->GetDC(&hdc) == DD_OK)
    {
        SetBkColor(hdc, RGB(0, 0, 255));
        SetTextColor(hdc, RGB(255, 255, 0));
        if (phase)
        {
            GetClientRect(hWnd, &rc);
            GetTextExtentPoint(hdc, szMsg, lstrlen(szMsg), &size);
            TextOut(hdc, (rc.right - size.cx) / 2, (rc.bottom - size.cy) / 2,
                    szMsg, sizeof(szMsg) - 1);
            TextOut(hdc, 0, 0, szFrontMsg, lstrlen(szFrontMsg));
            phase = 0;
        }
        else
        {
            TextOut(hdc, 0, 0, szBackMsg, lstrlen(szBackMsg));
            phase = 1;
        }
        g_pDDSBack->ReleaseDC(hdc);
    }

この例では、IDirectDrawSurface7::GetDC メソッドを使ってデバイス コンテキストのハンドルを取得し、内部的にバック バッファをロックする。デバイス コンテキストのハンドルを必要とする Windows 関数を使用しない場合は、IDirectDrawSurface7::Lock および IDirectDrawSurface7::Unlock メソッドを使って、バック バッファをロックしたりロックを解除したりすることができる。

次に、プライマリ バッファ メッセージまたはバック バッファ メッセージのどちらが書き込まれるべきかを phase 変数で決定する。phase 変数が 1 の場合はプライマリ バッファ メッセージが書き込まれて、phase 変数が 0 に設定される。phase 変数が 0 の場合は、バック バッファ メッセージが書き込まれて、phase 変数が 1 に設定される。

メッセージがバック バッファに書き込まれた後、IDirectDrawSurface7::ReleaseDC メソッドによってバック バッファのロックが解除される。

サーフェス メモリ (サーフェスの全体もしくは一部) をロックすると、アプリケーションとシステム ブリットを同時にサーフェス メモリへアクセスできなくなる。このため、アプリケーションがサーフェス メモリへ書き込む間に発生するエラーを回避できる。さらに、サーフェス メモリのロックが解除されるまで、アプリケーションはページ フリップできない。

サーフェスがロックされた後、この例では標準の Windows GDI 関数を使用する。バックグラウンド カラーの設定に SetBkColor、バックグラウンドに配置するテキストの色の選択に SetTextColor、サーフェス上のテキストとバックグラウンド カラーの出力に TextOut を使用している。

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

注 ： IDirectDrawSurface7::Unlock を使ってサーフェスのロックが解除されると、サーフェス メモリへのポインタは無効となる。サーフェス メモリへの有効なポインタを取得するには、再び IDirectDrawSurface7::Lock を使用しなくてはならない。

次項 :ステップ 6 : サーフェスのフリップ


ステップ 6 : サーフェスのフリップ

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

DDEx1 の WM_TIMER メッセージは、バック バッファ.へのフリップに使用される。サーフェス メモリのロックが解除されると、バック バッファをプライマリ サーフェスにフリップする IDirectDrawSurface7::Flip メソッドを使用できるようになる。次に例を示す。

    case WM_TIMER:
        // サーフェスを更新しフリップする。
        if (g_bActive && TIMER_ID == wParam)
        {
            UpdateFrame(hWnd);
            while (TRUE)
            {
                hRet = g_pDDSPrimary->Flip(NULL, 0);
                if (hRet == DD_OK)
                    break;
                if (hRet == DDERR_SURFACELOST)
                {
                    hRet = g_pDDSPrimary->Restore();
                    if (hRet != DD_OK)
                        break;
                }
                if (hRet != DDERR_WASSTILLDRAWING)
                    break;
            }
        }
        break;

この例では、g_pDDSPrimary パラメータがプライマリ サーフェスとそれに関連付けられたバック バッファを指定する。IDirectDrawSurface7::Flip が呼び出されると、フロント サーフェスとバック サーフェスが交換される (サーフェスへのポインタだけが変更され、実際にデータが移動するわけではない)。フリップが成功して DD_OK が返されると、アプリケーションは while ループから抜ける。

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

注 ： IDirectDrawSurface7::Flip を呼び出す場合、フリップはすぐに完了しない。むしろ、システムで垂直帰線が発生した後にフリップが計画される。たとえば、直前のフリップが発生していなければ、IDirectDrawSurface7::Flip は DDERR_WASSTILLDRAWING を返す。この例では、IDirectDrawSurface7::Flip の呼び出しは DD_OK を返すまでループし続ける。

次項 :ステップ 7 : DirectDraw オブジェクトの割り当て解除


ステップ 7 : DirectDraw オブジェクトの割り当て解除

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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

static void
ReleaseAllObjects(void)
{
    if (g_pDD != NULL)
    {
        if (g_pDDSPrimary != NULL)
        {
            g_pDDSPrimary->Release();
            g_pDDSPrimary = NULL;
        }
        g_pDD->Release();
        g_pDD = NULL;
    }
}

アプリケーションは、DirectDraw オブジェクト (g_pDD) および DirectDrawSurface オブジェクト (g_pDDSPrimary) へのポインタが NULL であるかどうかを調べる。次に、DDEx1 は IDirectDrawSurface7::Release メソッドを呼び出し、DirectDrawSurface オブジェクトの参照カウントを 1 だけ減らす。これにより、参照カウントが 0 になるので、DirectDrawSurface オブジェクトは割り当てを解除される。DirectDrawSurface ポインタの値を NULL に設定することにより、このポインタは破棄される。次に、アプリケーションは IDirectDraw7::Release を呼び出し、DirectDraw オブジェクトの参照カウントを 0 まで減らす。これにより、DirectDraw オブジェクトの割り当てを解除する。このポインタの値を NULL に設定することにより、このポインタも破棄される。


チュートリアル 2 : バック バッファへのビットマップのロード

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアル (DDEx2) で説明するサンプルは、チュートリアル 1 で説明した DDEx1 サンプルを拡張したものである。DDEx2 には、ビットマップ ファイルをバック バッファにロードする機能が含まれる。以下のステップでこの新機能を説明する。

  • ステップ 1 : パレットの作成
  • ステップ 2 : パレットの設定
  • ステップ 3 : バック バッファへのビットマップのロード
  • ステップ 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;


ステップ 1 : パレットの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL)
    goto error;

サンプル関数 DDLoadPalette は、\Dxsdk\Sdk\Samples\Misc ディレクトリの Ddutil.cpp ファイルの中にある、共通 DirectDraw 関数の一部である。この SDK の大部分の DirectDraw サンプル ファイルは、このファイルを使っている。このファイルには、ファイルまたはリソースからビットマップやパレットをロードするための関数が含まれる。複数の例題ファイルの中でコードの繰り返しを避けるために、これらの関数は再利用可能な 1 つのファイルにまとめられている。残りの DDExn サンプルと共にコンパイルするファイルのリストに Ddutil.cpp があることを確認すること。

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

次に、DDEx2 は DirectDrawPalette オブジェクトを作成する。次に例を示す。

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

IDirectDraw7::CreatePalette メソッドが戻ると、ddpal パラメータは、DDLoadPalette の呼び出しから返された後の DirectDrawPalette オブジェクトを示す。

ape パラメータは構造体へのポインタで、連続した 2、4、16、または 256 エントリのいずれかを含む。エントリの数は、CreatePalette メソッドの dwFlags パラメータに依存する。この場合、dwFlags パラメータは DDPCAPS_8BIT に設定され、この構造体に 256 エントリがあることを示す。個々のエントリは、4 バイト (赤チャネル、緑チャネル、青チャネル、およびフラグ バイト) で構成される。

次項 :ステップ 2 : パレットの設定


ステップ 2 : パレットの設定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval != DD_OK)
    // SetPalette は失敗した。

IDirectDrawSurface7::SetPalette を呼び出した後、DirectDrawPalette オブジェクトは DirectDrawSurface オブジェクトに関連付けられる。パレットの変更が必要な回数だけ、簡単に新しいパレットを作成し、そのパレットを再設定できる (このチュートリアルではここで示すステップをとるが、パレットの変更には後で説明するような方法もある)。

次項 :ステップ 3 : バック バッファへのビットマップのロード


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

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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

// バック バッファにビットマップをロードする。
ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval != DD_OK)
    // Load failed.

DDReLoadBitmap は、Ddutil.cpp にあるもう 1 つのサンプル関数である。この関数は、ファイルまたはリソースからビットマップを既存の 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 値は、DDSURFACEDESC2 構造体へのポインタである。この構造体は、DirectDraw サーフェスの現在の記述を格納する。この場合、メンバは、DDSD_HEIGHT と DDSD_WIDTH で示されるサーフェスの高さと幅を記述する。IDirectDrawSurface7::GetSurfaceDesc メソッドへの呼び出しは、構造体に該当する値をロードする。DDEx2 では、高さ 480、幅 640 とする。

DDCopyBitmap サンプル関数はサーフェスをロックして、StretchBlt 関数を使い、バック バッファにあてはまるようにビットマップを伸縮または圧縮してコピーする。

if ((hr = pdds->GetDC(&hdc)) == DD_OK)
{
    StretchBlt(hdc, 0, 0, ddsd.dwWidth, ddsd.dwHeight, hdcImage, x, y,
        dx, dy, SRCCOPY);
    pdds->ReleaseDC(hdc);
}

次項 :ステップ 4 : サーフェスのフリップ


ステップ 4 : サーフェスのフリップ

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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


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

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

チュートリアル 2 (DDEx2) のサンプルでは、ビットマップを取得してバック バッファに置き、次にバック バッファとプライマリ バッファ間でフリップする。これは、ビットマップを表示するにはあまり現実的な方法ではない。このチュートリアル (DDEx3) のサンプルでは、2 つのビットマップ (一方は偶数スクリーン用、他方は奇数スクリーン用) が格納された 2 つのオフスクリーン バッファを用いることにより、DDEx2 の能力を拡張する。オフスクリーン サーフェスの内容をバック バッファにコピーするには、IDirectDrawSurface7::BltFast メソッドを使う。そして、バッファをフリップし、次のオフスクリーン サーフェスをバック バッファにコピーする。

DDEx3 で示す新機能を次のステップで説明する。

  • ステップ 1 : オフスクリーン サーフェスの作成
  • ステップ 2 : オフスクリーン サーフェスへのビットマップのロード
  • ステップ 3 : バック バッファへのオフスクリーン サーフェスのブリット


ステップ 1 : オフスクリーン サーフェスの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

次のコードでは、DDEx3 の doInit サンプル関数を追加して、2 つのオフスクリーン バッファを作成する。

// オフスクリーン ビットマップを作成する。
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 で DDSURFACEDESC2 構造体に設定される。サーフェスは、IDirectDraw7::CreateSurface メソッドを使って作成する。

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

また、DDSCAPS_SYSTEMMEMORY または DDSCAPS_VIDEOMEMORY のどちらかの能力を DDSCAPS 構造体に設定することにより、オフスクリーン バッファをシステム メモリまたはディスプレイ メモリに配置することを明示的に要求できる。ディスプレイ メモリにビットマップを保存することにより、オフスクリーン サーフェスとバック バッファ間の転送速度を速めることができる。ビットマップ アニメーションを使う場合に、このことがより重要となる。ただし、オフスクリーン バッファに DDSCAPS_VIDEOMEMORY を指定して、ビットマップ全体を保持するためのディスプレイ メモリが不十分な場合にサーフェスを作成しようとすると、DDERR_OUTOFVIDEOMEMORY エラー値が返される。

次項 :ステップ 2 : オフスクリーン サーフェスへのビットマップのロード


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

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

2 つのオフスクリーン サーフェスが作成されると、DDEx3 は InitSurfaces サンプル関数を使って、Frntback.bmp ファイルのビットマップをサーフェスにロードする。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 ファイルを見ると、一方がもう一方に重なる 2 つのスクリーンでビットマップが構成されていることがわかる。DDCopyButmap 関数は、そのスクリーンが合わさるポイントでビットマップを 2 つに分ける。さらに、最初のビットマップを最初のオフスクリーン サーフェス (lpDDSOne) にロードし、2 番目のビットマップを 2 番目のオフスクリーン サーフェス (lpDDSTwo) にロードする。

次項 :ステップ 3 : バック バッファへのオフスクリーン サーフェスのブリット


ステップ 3 : バック バッファへのオフスクリーン サーフェスのブリット

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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 変数では、バック バッファにブリットされるオフスクリーン サーフェスを決定する。そして、IDirectDrawSurface7::BltFast メソッドを呼び出して、選択されたオフスクリーン サーフェスは左上角の始点 (0,0) からバック バッファにブリットする。rcRect パラメータは RECT 構造体のポインタであり、ブリットされるオフスクリーン サーフェスの左上角と右下角を定義する。最後のパラメータは FALSE (または 0) に設定し、特別な転送フラグを使わないことを示す。

アプリケーションの要求により、IDirectDrawSurface7::Blt メソッドまたは IDirectDrawSurface7::BltFast メソッドのどちらかを使い、オフスクリーン バッファからブリットする。ディスプレイ メモリにあるオフスクリーン プレーン バッファからブリットを実行する場合は、IDirectDrawSurface7::BltFast を使うようにする。ディスプレイ アダプタ上のハードウェア ブリットを使うシステムでは速度を早くできない。しかし、ブリットの実行にハードウェア エミュレーションを使うシステムでは、10 パーセント程度早くなる。このため、ディスプレイ メモリからディスプレイ メモリへのブリットするすべてのディスプレイ処理において、IDirectDrawSurface7::BltFast を使うべきである。ただし、システム メモリからブリットしたり、特別なハードウェア フラグを必要とする場合は、IDirectDrawSurface7::Blt を使用しなくてはならない。

オフスクリーン サーフェスをバック バッファにロードした後、バック バッファとプライマリ サーフェスは、上述のチュートリアルで示した方法とほぼ同様にフリップされる。


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

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

チュートリアル 3 (DDEx3) のサンプルでは、バック バッファにブリットする前に、ビットマップをオフスクリーン バッファに配置する 1 つの簡単な方法を示した。このチュートリアル (DDEx4) のサンプルでは、直前のチュートリアルで説明した技術を使い、バックグラウンドと一連のスプライトをオフスクリーン サーフェスへロードする。そして、IDirectDrawSurface7::BltFast メソッドを使用して、オフスクリーン サーフェスの一部をバック バッファにコピーする。つまり、簡単なビットマップ アニメーションを生成する。

DDEx4 で使用するビットマップ ファイル All.bmp は、黒のバックグラウンドに 60 回転する赤い輪とバックグラウンドで構成される。DDEx4 のサンプルには、回転している輪のスプライトにカラー キーを設定する新しい関数を含む。そして、そのサンプルは、該当するスプライトをオフスクリーン サーフェスからバック バッファへコピーする。

DDEx4 の新機能を次のステップで説明する。

  • ステップ 1 : カラー キーの設定
  • ステップ 2 : 簡単なアニメーションの作成


ステップ 1 : カラー キーの設定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

他の 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 に戻る。呼び出しが戻ると、カラー キー値は DDCOLORKEY 構造体の dwColorSpaceLowValue メンバに配置される。また、dwColorSpaceHighValue メンバにもコピーされる。そして、IDirectDrawSurface7::SetColorKey を呼び出すことで、カラー キーを設定する。

DDSetColorKey および DDColorMatch の CLR_INVALID を参照していることに気付いたかもしれない。DDEx4 で DDSetColorKey の呼び出しにカラー キーとして CLR_INVALID を渡す場合、ビットマップの左上角 (0, 0) のピクセルがカラー キーとして使われる。DDEx4 のビットマップが渡されても、(0, 0) でピクセルの色は灰色がかっているためにあまり意味はない。ただし、DDEx4 サンプルのカラー キーとして (0, 0) でピクセルを使う方法を見たければ、描画アプリケーションで All.bmp ビットマップ ファイルを開き、(0, 0) で 1 つのピクセルを黒に変更する。この変更は必ず保存すること (変更が見られなくなるため)。次に、DDSetColorKey を呼び出す DDEx4 の行を以下のように変更する。

DDSetColorKey(lpDDSOne, CLR_INVALID);

DDEx4 のサンプルを再コンパイルすると、新しいビットマップがあるために、リソース定義ファイルも再コンパイルされることを確認する (確認するには、Ddex4.rc ファイルに 1 つの空間を追加しそれを削除すればよい)。DDEx4 サンプルは、現時点でカラー キーとして黒に設定された (0, 0) でピクセルを使うようになる。

次項 :ステップ 2 : 簡単なアニメーションの作成


ステップ 2 : 簡単なアニメーションの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

DDEx4 のサンプルでは updateFrame サンプル関数を使って、All.bmp ファイルにある赤い輪を使用する簡単なアニメーションを作成する。アニメーションは、三角形に配置され、さまざまなスピードで回転する 3 つの赤い輪からなる。このサンプルでは、Win32 GetTickCount 関数を GetTickCount 関数への最後の呼び出しから経過したミリ秒と比較して、スプライトを再描画するかどうかを決める。これに続いて、まず、IDirectDrawSurface7::BltFast メソッドを使ってオフスクリーン サーフェス (lpDDSOne) からバック バッファにバックグラウンドをブリットしてから、前もって設定したカラー キーを使ってバック バッファにスプライトをブリットし、どのピクセルを透過型にするかを決める。スプライトがバック バッファにブリットされてから、DDEx4 は IDirectDrawSurface7::Flip メソッドを呼び出してバック バッファとプライマリ サーフェスをフリップする。

オフスクリーン サーフェスからバックグラウンドをブリットするために IDirectDrawSurface7::BltFast を使用するときは、転送のタイプを指定する dwTrans パラメータを DDBLTFAST_NOCOLORKEY に設定する。これは、一般的なブリットが不透過性ビットで生じることを示している。その後、赤い輪をバック バッファにブリットするとき、dwTrans パラメータを DDBLTFAST_SRCCOLORKEY に設定する。これは、ブリットが定義された透過性のためのカラー キーで生じることを示している。この場合は、lpDDSOne バッファ内である。

このサンプルでは、毎回、updateFrame からバックグランド全体が再描画される。このサンプルを最適化する 1 つの方法は、赤い輪が回転している間に、変更するバックグラウンドの部分のみを再描画することである。輪はスプライトする矩形の配置やサイズは変更しないので、DDEx4 サンプルを最適化するための簡単な修正ができる。


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

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルで説明するサンプル (DDEx5) は、チュートリアル 4 で説明したサンプル (DDEx4) の修正である。DDEx5 では、アプリケーションの実行中にパレット エントリを動的に変更する方法について示す。DDEx5 の新機能を次のステップで説明する。

  • ステップ 1 : パレット エントリのロード
  • ステップ 2 : パレットの回転


ステップ 1 : パレット エントリのロード

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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 列から開始するように設定する。配列のカラー インデックス値は、ビットマップ サーフェスが配置されるメモリの位置のデータのバイトで決まる。この位置は、DDSURFACEDESC2 構造体の lpSurface メンバによって決まる。このメンバは、ビットマップの 480 行 : 0 列 (y×lPitch + x) に対応するメモリの位置を指す。特定のカラー インデックス値の位置は、1 に設定する。y の値 (行) に lPitch 値 (DDSURFACEDESC2 構造体にある) を掛けて、線形メモリにあるピクセルの実際の位置を求める。

torusColors で設定されたカラー インデックス値は、後でパレット内のどの色を循環させるかを決定する際に使用する。バックグラウンドと赤い輪には共通する色が存在しないため、赤い輪に関連付けられた色のみを循環させる。これが、true であるかどうかを調べるには、配列から "*ddsd.lPitch" を削除して、プログラムを再コンパイルして実行するときに何が起こるかを見る (y×lPitch を行わないと、赤い輪は決して循環せず、バックグラウンドを構成する色にのみインデックスが付き後で循環する)。幅およびピッチについての詳細情報は、「幅とピッチ」を参照すること。

次項 :ステップ 2 : パレットの回転


ステップ 2 : パレットの回転

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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 を調べ続ける。1 に設定されている場合、pe ポインタで指されるパレット エントリの赤、緑、および青の値は循環する。

マークされたすべてのパレット エントリが循環した後、IDirectDrawPalette::SetEntries メソッドを呼び出し、DirectDrawPalette オブジェクトのエントリを変更する。この変更は、プライマリ サーフェスに設定するパレットが作用するとすぐに実行される。

これが終了すると、続いてサーフェスがフリップされる。


チュートリアル 6 : オーバーレイ サーフェスの使用

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、DirectDraw やハードウェアでサポートするオーバーレイ サーフェスをアプリケーションで使用する方法について段階的に説明する。このチュートリアルでは、DirectX SDK サンプルにある Mosquito サンプル アプリケーションを中心に説明する。Mosquito は、オーバーレイ サーフェスのフリッピング チェーンを使用して、デスクトップ上にアニメーションされたビットマップをプライマリ サーフェスにブリットすることなく表示する単純なアプリケーションである。このサンプルは、ハードウェア制限に対応するために必要に応じてオーバーレイ サーフェスの特性を調整する。

Mosquito サンプル アプリケーションは、次のステップで実行する (複雑なタスクは、サブステップに分割してある)。

  • ステップ 1 : プライマリ サーフェスの作成
  • ステップ 2 : ハードウェア オーバーレイ サポートのテスト
  • ステップ 3 : オーバーレイ サーフェスの作成
  • ステップ 4 : オーバーレイ サーフェスの表示
  • ステップ 5 : オーバーレイ表示位置の更新
  • ステップ 6 : オーバーレイ サーフェスの隠蔽


ステップ 1 : プライマリ サーフェスの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

オーバーレイ サーフェスを使用するには、最初に DirectDraw を初期化し、オーバーレイ サーフェスを表示するためのプライマリ サーフェスを作成する。Mosquito では、次のコードでプライマリ サーフェスを作成する。

    // 構造体を初期化し、dwSize メンバを設定する。
    ZeroMemory(&ddsd, sizeof(ddsd));
    ddsd.dwSize = sizeof(ddsd);

    // フラグを設定し、プライマリ サーフェスを作成する。
    ddsd.dwFlags = DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
    ddrval = g_lpdd->CreateSurface(&ddsd, &g_lpddsPrimary, NULL );

上記の例は、使用する DDSURFACEDESC2 構造体の初期化から始まる。次に、プライマリ サーフェスの作成に必要なフラグを設定し、IDirectDraw7::CreateSurface メソッドを呼び出してプライマリ サーフェスを作成する。この呼び出しでは、最初のパラメータが、作成するサーフェスを記述する DDSURFACEDESC2 構造体へのポインタとなる。2 番目のパラメータは、呼び出しが成功した場合の、IDirectDrawSurface7 インターフェイス ポインタを受け取る変数へのポインタとなる。最後のパラメータは NULL に設定し、COM 処理が起こっていないことを示す。

次項 :ステップ 2 : ハードウェア オーバーレイ サポートのテスト


ステップ 2 : ハードウェア オーバーレイ サポートのテスト

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

DirectDraw を初期化した後、デバイスがオーバーレイ サーフェスをサポートすることを確認する必要がある。DirectDraw はオーバーレイをエミュレートしないため、ハードウェア デバイス ドライバがオーバーレイをサポートしない場合には続行できない。オーバーレイ サポートをテストするには、IDirectDraw7::GetCaps メソッドでデバイス ドライバの能力を取得する。この呼び出し後、関連する DDCAPS 構造体の dwFlags メンバで DDCAPS_OVERLAY フラグを探す。このフラグがあれば、ディスプレイ ハードウェアはオーバーレイをサポートする。このフラグがなければ、そのデバイスではオーバーレイ サーフェスを利用できない。

Mosquito サンプル アプリケーションにおける次の例では、ハードウェア オーバーレイ サポートのテスト方法について示す。

BOOL AreOverlaysSupported()
{
    DDCAPS  capsDrv;
    HRESULT ddrval;

    // ドライバ能力を取得し、オーバーレイ サポートを決定する。
    ZeroMemory(&capsDrv, sizeof(capsDrv));
    capsDrv.dwSize = sizeof(capsDrv);

    ddrval = g_lpdd->GetCaps(&capsDrv, NULL);
    if (FAILED(ddrval))
        return FALSE;

    // 現在のモードで、ドライバがオーバーレイをサポートするか？
    // (現在、DirectDraw エミュレーション レイヤはオーバーレイをサポートしていない。
    // ハードウェア サポートがなければ、オーバーレイに関する API は失敗する。
    if (!(capsDrv.dwCaps & DDCAPS_OVERLAY))
        return FALSE;

    return TRUE;
}

上記の例では、IDirectDraw7::GetCaps メソッドを呼び出してデバイス ドライバ能力を取得する。呼び出しの最初のパラメータは、デバイス ドライバの能力を記述する情報で埋め込まれる DDCAPS のアドレスである。アプリケーションは、エミュレーション能力に関する情報を必要としないため、2 番目のパラメータは NULL に設定する。

ドライバ能力を取得した後、この例では、論理演算の AND 処理で dwCaps メンバの DDCAPS_OVERLAY フラグの存在を調べる。フラグがない場合、この例では失敗を示す FALSE を返す。フラグがある場合は、デバイス ドライバがオーバーレイ サーフェスをサポートすることを示す TRUE を返す。

このコードで、他のオーバーレイ サーフェスが他のアプリケーションで使用されていないことを確認するとよい。そのためには、DDCAPS 構造体の dwMaxVisibleOverlays および dwCurrentVisibleOverlays メンバを調べる。

次項 :ステップ 3 : オーバーレイ サーフェスの作成


ステップ 3 : オーバーレイ サーフェスの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

ドライバがオーバーレイ サーフェスをサポートすることがわかったので、オーバーレイ サーフェスを作成できる。デバイスがオーバーレイ サーフェスをサポートするうえで標準となる方法がないので、特定のサイズやピクセル フォーマットのオーバーレイを常に作成できるとは限らない。さらに、1 度でオーバーレイ サーフェスを作成できるとも限らない。したがって、最も望ましい特性を持つオーバーレイ サーフェスから作成し始め、機能するオーバーレイ サーフェスを作成できるまで、構成の特性を落としながら (おそらく、ハードウェア依存ではない) 何度も作成を試みる。

注 ： IDirectDraw7::GetFourCCCodes メソッドを呼び出すことにより、ドライバがオーバーレイ サーフェスをサポートしそうな非 RGB ピクセル フォーマットを記述する FOURCC コードのリストを取得できる。ただし、RGB オーバーレイ サーフェスを使用する場合には、最初にさまざまな共通 RGB フォーマットでサーフェスの作成を試み、うまくいかなければ他のフォーマットで試みるとよい。

Mosquito サンプルでは、" 最良の場合から最悪の場合 " という考えに従ってオーバーレイ サーフェスを作成する。Mosquito では、最初にトリプルバッファのページ フリッピング複合オーバーレイ サーフェスの作成を試みる。その作成に失敗した場合、次に他の共通ピクセル フォーマットで構成を試みる。この場合のコードを次に示す。

    ZeroMemory(&ddsdOverlay, sizeof(ddsdOverlay));
    ddsdOverlay.dwSize = sizeof(ddsdOverlay);

    ddsdOverlay.dwFlags= DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH |
                         DDSD_BACKBUFFERCOUNT| DDSD_PIXELFORMAT;
    ddsdOverlay.ddsCaps.dwCaps = DDSCAPS_OVERLAY | DDSCAPS_FLIP |
                                 DDSCAPS_COMPLEX | DDSCAPS_VIDEOMEMORY;
    ddsdOverlay.dwWidth  =320;
    ddsdOverlay.dwHeight =240;
    ddsdOverlay.dwBackBufferCount=2;

    // グローバル リストにあるピクセル フォーマットの 1 つを用いて、
    // オーバーレイ サーフェスの作成を試みる。
    i=0;
    do{
    ddsdOverlay.ddpfPixelFormat=g_ddpfOverlayFormats[i];
       // オーバーレイ サーフェスの作成を試みる。
       ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
    } while( FAILED(ddrval) && (++i < NUM_OVERLAY_FORMATS) );

上記の例では、DDSURFACEDESC2 構造体の範囲内にフラグと値を設定して、トリプルバッファのページ フリッピング複合オーバーレイ サーフェスを反映する。次に、さまざまな共通ピクセル フォーマットで要求するサーフェスを作成するために、もっとも望ましいものから望ましくないピクセル フォーマットの順にループを実行する。サーフェスが作成できると、ループは終了する。サーフェスを作成する試みがすべて失敗した場合、ディスプレイ ハードウェアにトリプルバッファ スキームをサポートするための十分なメモリがないか、フリッピング オーバーレイ サーフェスをサポートしない可能性がある。この場合、このサンプルでは、単一の非フリッピング オーバーレイ サーフェスを使う要求度の低い構成で作成を試みる。次にこの例を示す。

    // トリプルバッファ複合オーバーレイ サーフェスが作成されない
    // 場合、単一の非フリッピング バッファイで再び作成を試みる。
    if(FAILED(ddrval))
    {
        ddsdOverlay.dwBackBufferCount=0;
        ddsdOverlay.ddsCaps.dwCaps=DDSCAPS_OVERLAY | DDSCAPS_VIDEOMEMORY;
        ddsdOverlay.dwFlags= DDSD_CAPS|DDSD_HEIGHT|DDSD_WIDTH|DDSD_PIXELFORMAT;

        // オーバーレイ サーフェスの作成を試みる。
        ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
        i=0;
        do{
            ddsdOverlay.ddpfPixelFormat=g_ddpfOverlayFormats[i];
            ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
        } while( FAILED(ddrval) && (++i < NUM_OVERLAY_FORMATS) );

        // オーバーレイ サーフェスを作成できない。失敗を返して終了する。
        if (FAILED(ddrval))
            return FALSE;
    }

直前のコードでは、DDSURFACEDESC2 構造体のフラグと値をリセットして、単一の非フリッピング オーバーレイ サーフェスを反映する。サーフェスを作成するために、再度ピクセル フォーマットからループする。作成に成功すると、ループは終了する。この場合でも作成できなければ、サンプルは失敗を示す FALSE を返す。

オーバーレイ サーフェスまたはサーフェスの作成に成功すると、そのサーフェスにビットマップをロードして表示を準備できる。

次項 :ステップ 4 : オーバーレイ サーフェスの表示


ステップ 4 : オーバーレイ サーフェスの表示

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

オーバーレイ サーフェスを作成したら、それを表示できる。ディスプレイ ハードウェアでは、オーバーレイを表示するために使う矩形の位置やピクセル幅にアライメント制限を課す場合がある。さらに、オーバーレイ サーフェスをうまく表示するために、転送先矩形の幅を調整して要求される最小伸縮係数に合うようにする場合がある。Mosquito サンプルでは、オーバーレイ サーフェスを準備してから表示するために次のタスクを実行する。

  • ステップ 4.1 : 最小表示要件の決定
  • ステップ 4.2 : 転送元矩形と転送先矩形のセットアップ
  • ステップ 4.3 : オーバーレイ サーフェスの表示

次項 :ステップ 4.1 : 最小表示要件の決定


ステップ 5 : オーバーレイ表示位置の更新

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

オーバーレイ サーフェスを表示した後、他には何もする必要がないかもしれない。しかし、ソフトウェアによっては、オーバーレイ サーフェスの再配置が必要になる場合もある。Mosquito サンプルでは、IDirectDrawSurface7::SetOverlayPosition メソッドを使ってオーバーレイを再配置する。次に例を示す。

// x 座標および y 座標を設定する。
    .
    .
    .
// x 位置に対するアライメント制限の有無を調べる必要
//  があり、必要であれば調節する。
    if (g_dwOverlayXPositionAlignment)
        dwXAligned = g_nOverlayXPos - g_nOverlayXPos % g_dwOverlayXPositionAlignment;
    else
        dwXAligned = g_nOverlayXPos;

//  オーバーレイを新しい位置に設定する。
    ddrval = g_lpddsOverlay->SetOverlayPosition(dwXAligned, g_nOverlayYPos);
    if (ddrval == DDERR_SURFACELOST)
    {
        if (!RestoreAllSurfaces())
            return;
    }

上記の例では、矩形を連続させることにより、存在する転送先矩形の境界アライメント制限に適合させる。調べるグローバル変数 g_dwOverlayXPositionAlignment は、アプリケーションが IDirectDraw7::GetCaps メソッドを前回呼び出したときに、DDCAPS 構造体の dwAlignBoundaryDest メンバにより報告された値と等しくなるように設定されている (詳細情報は、「ステップ 4.1 : 最小表示要件の決定」を参照すること)。転送先アライメント制限が存在する場合、新しい x 座標をそれに対応してピクセルと連続するように調整する。この要件が満たされない場合は、オーバーレイ サーフェスは表示されない。

新しい x 座標に必要な調整を行った後、IDirectDrawSurface7::SetOverlayPosition メソッドを呼び出してオーバーレイを再配置する。この呼び出しでは、最初のパラメータが連続した x 座標となり、2 番目のパラメータは新しい y 座標となる。これらの値は、オーバーレイの左上角の新しい位置を表す。DirectDraw は、最初にオーバーレイを表示するのに作成した IDirectDrawSurface7::UpdateOverlay メソッドから、既にサーフェスの寸法を取得しているため、幅と高さの情報を受け取らないし、また必要としない。1 つ以上のサーフェスが消失したために呼び出しが失敗すると、この例ではアプリケーションで定義された関数を呼び出して、失われたサーフェスをリストアしてから、そのビットマップを再ロードする。

注 ： ターゲット サーフェスの下側または右側の縁に近すぎる座標を使わないように注意する。IDirectDraw7::SetOverlayPosition メソッドはクリッピングを実行しない。つまり、オーバーレイがターゲット サーフェスの縁をはみ出る可能性のある座標を使用すると、このメソッドは DDERR_INVALIDPOSITION を返して失敗する。

次項 :ステップ 6 : オーバーレイ サーフェスの隠蔽


ステップ 6 : オーバーレイ サーフェスの隠蔽

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

オーバーレイ サーフェスが必要なくなるか、または単にビューから削除したい場合は、該当するフラグを設定して IDirectDrawSurface7::UpdateOverlay メソッドを呼び出すと、サーフェスを隠蔽できる。Mosquito では、アプリケーションを閉じることに備えてオーバーレイを隠蔽する。次にこのコードを示す。

void DestroyOverlay()
{
    if (g_lpddsOverlay){
// UpdateOverlay() に DDOVER_HIDE フラグを使用して
// オーバーレイをディスプレイから削除する。
        g_lpddsOverlay->UpdateOverlay(NULL, g_lpddsPrimary, NULL, DDOVER_HIDE, NULL);
        g_lpddsOverlay->Release();
        g_lpddsOverlay=NULL;
    }
}

上記の例で IDirectDrawSurface7::UpdateOverlay を呼び出す場合、オーバーレイの隠蔽には無関係なため、転送元および転送先矩形は NULL を指定する。同様に、5 番目のパラメータも、オーバーレイ エフェクトを使用しないために NULL とする。2 番目のパラメータは、ターゲット サーフェスへのポインタとなる。最後に、オーバーレイがビューから削除されることを示すために、4 番目のパラメータに DDOVER_HIDE フラグを使用する。

オーバーレイを隠蔽した後、この例では IDirectDrawSurface7 インターフェイスを解放し、NULL に設定することでそのグローバル変数を無効にする。Mosquito サンプル アプリケーションでは、オーバーレイ サーフェスはもはや必要ではない。後でオーバーレイ サーフェスが必要になることがあれば、オーバーレイを解放せずに単に隠蔽しておき、必要に応じて再表示すればよい。


DirectDraw Visual Basic チュートリアル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここでは、次のチュートリアルを使用して、簡単な DirectDraw アプリケーションを実装する方法をステップ バイ ステップで説明する。各チュートリアルでは、この SDK が提供する DirectDraw サンプル ファイルを多く使用している。これらのサンプルでは、DirectDraw のセット アップ方法と、一般的なタスクを実行するための DirectDraw メソッドの使用方法を紹介する。

  • チュートリアル 1 : スクリーンへのブリット
  • チュートリアル 2 : 透過性の使用
  • チュートリアル 3 : フルスクリーン機能の使用
  • チュートリアル 4 : スクリーンの領域へのブリット
  • チュートリアル 5 : DirectDraw デバイスの列挙


チュートリアル 1 : スクリーンへのブリット

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

この最初のチュートリアルでは、ビットマップのディスプレイ アダプタへのブリットについて説明する。このブリット (blit) とは、ビット ブリット (bit block transfer) のことであり、データのブロックをメモリ内のある場所から別の場所に転送するプロセスを指す。グラフィックス プログラマは、ブリットを使用して、メモリ内のある場所から別の場所にグラフィックスを転送する。ブリットは、スプライト アニメーションの実行によく使用される。

DirectDraw を使用するには、まず始めに、コンピュータ上のディスプレイ アダプタを表す DirectDraw オブジェクトのインスタンスを作成しなければならない。そして、メソッドを使用して、そのオブジェクトを操作する。さらに、アプリケーションをグラフィックス サーフェス上に表示するには、DirectDrawSurface オブジェクトのインスタンスを 1 つ以上作成する必要がある。

これを示すため、この SDK に含まれている「チュートリアル 1 : スクリーンへのブリット」のサンプルでは、以下のステップを実行する。

  • ステップ 1 : フォームの作成
  • ステップ 2 : モジュール レベル変数の宣言
  • ステップ 3 : 変数の初期化
  • ステップ 4 : サーフェスのブリット


ステップ 1 : フォームの作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

チュートリアル 1 のブリット サンプルは、フォーム上にピクチャ ボックス コントロールを配置した標準の .exe プロジェクトである。ピクチャ ボックス コントロールは、フォームの左上にあるピクチャ ボックスの左上端に配置される。このピクチャ ボックスは Picture1 と名付けられ、アプリケーションのビットマップ イメージを表示する。

次項 :ステップ 2 :モジュール レベル変数の宣言


ステップ 2 : モジュール レベル変数の宣言

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

Visual Basic で DirectX アプリケーションをコード化する際の最初のステップは、DirectX7 のインスタンス作成である。このオブジェクトには、DirectDraw、DirectSound、Direct3D 直接モード、Direct3D 保持モード、DirectInput、DirectPlay、DirectMusic など、DirectX コンポーネントのスタート オブジェクトの作成に必要なメソッドがすべて含まれている。Direct3D 保持モードの詳細情報は、このドキュメントの Appendix ノードにある。

DirectX7 クラスは、DxVBLib タイプ ライブラリの最上位クラスで、このクラスのオブジェクトは次の文によって作成される。

Dim objDX As New DirectX7

チュートリアル 1 のブリット サンプルに記載されているモジュール レベル変数の宣言には、DirectDraw オブジェクト、DirectDrawSurface オブジェクト、DirectDrawClipper オブジェクト、DirectDraw サーフェス記述タイプ、および初期化情報の保持に使用されるブール変数がある。

次項 :ステップ 3 : 変数の初期化


ステップ 3 : 変数の初期化

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

Form_Load イベントで呼び出される最初のプロシージャは、init プロシージャである。このプロシージャは DirectDraw オブジェクトを作成する。これを実行するには、DirectX7 オブジェクトの DirectX7.DirectDrawCreate メソッドを呼び出し、返されたオブジェクトを、DirectDraw7 クラスのオブジェクト変数として宣言した DirectDraw に設定する。チュートリアル 1 のブリット サンプルでは、これを次の文で実行する。

Set objDD = objDX.DirectDrawCreate("")

このメソッドは文字列引数を 1 つだけ必要とし、空の文字列を渡すとアクティブ ディスプレイ ドライバを指定する。

次に、DirectDraw オブジェクトの DirectDraw7.SetCooperativeLevel メソッドを呼び出して、アプリケーションの動作を指定する必要がある。チュートリアル 1 のブリット サンプルは正規ウィンドウ アプリケーションとして実行され、次の文によって実行する。

Call objDD.SetCooperativeLevel (Me.hwnd, DDSCL_NORMAL)

これでサーフェス作成の準備が完了した。実際にサーフェス オブジェクトを作成する前に、DDSURFACEDESC2 型のメンバを設定して、サーフェスの記述を作成する必要がある。この型のメンバの 1 つとして、ネスト型の ddscaps がある。DDSURFACEDESC2 の lFlags メンバを DDSD_CAPS に設定することで、この型において ddscaps メンバが有効であることを記述することができる。これは、次の文によって実行される。

ddsd1.lFlags = DDSD_CAPS

次に、この型の記述がプライマリ サーフェス用であることを指定する。これは次の文で実行される。

ddsd1.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE

サーフェスの記述を作成したら、セット サーフェスの記述を引数として DirectDraw オブジェクトから CreateSurface メソッドを呼び出し、実際にサーフェス オブジェクトを作成する。チュートリアル 1 のブリット サンプルでは、これは次の文で実行される。

Set objDDPrimSurf = objDD.CreateSurface(ddsd1)

次のサーフェスの作成でもこのサーフェス オブジェクト作成のステップを繰り返すが、そのときは DDSCAPS_OFFSCREENPLAIN フラグをセットして、そのサーフェスがオーバーレイ、テクスチャ、z バッファ、フロントバッファ、バックバッファ、またはアルファ サーフェス以外のオフスクリーン サーフェスであることを指定する。このステップは、平面サーフェスを指定する。次に、CreateSurfaceFromFile メソッドを DirectDraw オブジェクトから呼び出す。このメソッドは、サーフェス オブジェクトを作成してビットマップをサーフェスにロードする。ビットマップの位置は FindMediaDir プロシージャで指定する。これらのステップは、以下の文で示される。

FindMediaDir "lake.bmp"

ddsd2.lFlags = DDSD_CAPS
ddsd2.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
Set objDDSurf = objDD.CreateSurfaceFromFile("lake.bmp", ddsd2)

DirectDrawClipper オブジェクトを作成するには、DirectDraw7.CreateClipper メソッドを呼び出す。クリッパー、つまり DirectDrawClipper オブジェクトを使用して、境界矩形で表されるサーフェスの選択部分にブリットできる。チュートリアル 1 では、Picture1 ピクチャ ボックス コントロールへのブリットについて説明する。これは以下の文で実行される。

Set ddClipper = objDD.CreateClipper(0)
ddClipper.SetHWnd Picture1.hWnd
objDDPrimSurf.SetClipper ddClipper

すべての変数とオブジェクトを初期化したら、bInit 変数を True に設定して blt サブルーチンを呼び出す。

次項 :ステップ 4 :サーフェスのブリット


ステップ 4 : サーフェスのブリット

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

「チュートリアル 1 : スクリーンへのブリット」のサンプルでは、プライマリ サーフェスとロードしたビットマップを持つオフスクリーン サーフェスを作成した。ビットマップをスクリーン上に表示するには、オフスクリーン サーフェスをプライマリ サーフェスにブリットする必要がある。DirectDraw サーフェス オブジェクトのブリット メソッドは、4 つの引数を取り、ブリットが成功したかどうかを示す Long 型を返す。引数のうち 2 つは、転送先サーフェスと転送元サーフェスの境界矩形を指定する RECT 型である。

転送元サーフェスの座標は、オフスクリーン サーフェスの記述の lHeight メンバと lWidth メンバから取得する。転送先矩形を取得するには、さらにいくつかのステップを実行する必要がある。まず始めに、Visual Basic はスクリーンの測定に twip を、DirectX はピクセルを使用するため、転送先矩形を設定する前に、Visual Basic ピクチャ ボックス コントロールの寸法をピクセルに変換する必要がある。これを実行するには、フォームの ScaleMode プロパティを Pixels に設定し、ピクチャ ボックスの幅と高さをフォームの ScaleWidth と ScaleHeight に等しくする。注 : ScaleMode を変更した後もフォームの幅と高さの単位は twip のままだが、ScaleWidth と ScaleHeight の単位はピクセルになっている。チュートリアル 1 のブリット サンプルでは、これを以下の文で実行する。

Picture1.Width = Me.ScaleWidth
Picture1.Height = Me.ScaleHeight

これらの文は Form_Resize イベント内にあり、フォームが最初に表示されサイズ変更されたときに実行される。

さらに、DirectX7.GetWindowRect が呼び出されると、転送先の RECT 型に情報が埋め込まれる。

最後に、プライマリ サーフェス オブジェクトの blt メソッドによって、ブリットが実行される。

ddrval = objDDPrimSurf.blt(r1, objDDSurf, r2, DDBLT_WAIT)

このメソッドの結果、ddrval に格納される Long 型が返される。この変数をチェックすれば、成功または失敗がわかる。メソッドの最後の引数は DDBLT_WAIT フラグである。このフラグは、ブリット機能がビジーの場合は DirectDraw に待機するよう指示し、利用可能な状態になるとサーフェスをブリットするように指示する。


チュートリアル 2 : 透過性の使用

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

チュートリアル 2 では、透過型ブリットを紹介し、チュートリアル 1 で学んだ概念をさらに広げていく。透過型ブリットにより、スプライトをアニメーションするときに、矩形以外の形をブリットしたかのように見せることができる。スプライト イメージは通常は矩形ではないが、ブリットは常に矩形であるため、スプライトの境界矩形内のすべてのピクセルがデータ転送される。透過型ブリットにより、スプライト イメージ部分以外のピクセルは、転送先にイメージがブリットされるときには透過色として転送される。したがって、これらのピクセルによってバックグラウンド イメージ上のピクセルの色が変更されることはない。

スプライトを作成する場合、透過色のカラー キーとして使用する任意の色または色域を選択する。このチュートリアルでは、スプライト イメージ上の転送元カラー キーを使用して、矩形以外の形をブリットしているように見せる。

このチュートリアルでの最初のステップはプライマリ サーフェスの作成であり、この点ではチュートリアル 1 の「ステップ 3 : 変数の初期化」と同じ手順になる。したがって重複を避けるため、このチュートリアルではバック バッファ サーフェスの作成から始める。

透過型ブリットの例を示すため、SDK のチュートリアル 2 では、以下のステップを実行する。

  • ステップ 1 : バック バッファの作成
  • ステップ 2 : サーフェスの初期化
  • ステップ 3 : プライマリ サーフェスへのブリット


ステップ 1 : バック バッファの作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

チュートリアル 2 のサンプルでは、オフスクリーン サーフェスを合成サーフェスとして使用する。オフスクリーン サーフェスは、メモリ内に概念として存在する矩形領域であり、この領域には通常プライマリ サーフェスにブリットされるビットマップが格納される。このバック バッファを使って湖のイメージとスプライトのイメージを格納し、その後合成されたイメージをスクリーンに表示する。このサーフェスは、以下の文で作成される。

'非表示サーフェスを作成し描画する。
'これをシステム メモリ内の合成サーフェスとして使用する。

'高さと幅を指定したいことを示す。
'サーフェスのフォーマット (bits per pixel) は
'プライマリ サーフェスと同じである。
ddsdBackBuffer.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH

'表示されないサーフェスが必要であることと、
'そのサーフェスをビデオ メモリではなくシステム メモリに配置することを示す。
ddsdBackBuffer.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_SYSTEMMEMORY

'サーフェスの高さと幅を
'ピクチャ ボックスと同じになるように指定する (単位はピクセルであることに注意)。
ddsdBackBuffer.lWidth = Picture1.Width
ddsdBackBuffer.lHeight = Picture1.Height

'要求されたサーフェスを作成する。
Set objDDBackBuffer = objDD.CreateSurface(ddsdBackBuffer)

次項 :ステップ 2 : サーフェスの初期化


ステップ 2 : サーフェスの初期化

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

このステップでは、バックグラウンド イメージ用とスプライト イメージ用のさらに 2 つのサーフェスの作成と初期化について説明する。また、スプライト イメージのサーフェスに透過色のカラー キーを指定する。

どちらのサーフェスも DirectDraw7.CreateSurfaceFromFile メソッドを呼び出して作成するオフスクリーン サーフェスである。最初に作成される objDDLakeSurf はバックグラウンド イメージ用のサーフェスであり、その幅と高さは、フォーム上の Picture1 ピクチャ ボックス コントロールと同じである。2 つ目のサーフェス objDDSpriteSurf には、スプライト イメージが含まれ、このスプライト イメージは最終的にバック バッファでバックグラウンド イメージと合成される。これらのサーフェスは以下の文で作成される。

'湖のバックグラウンド イメージをロードする。

'オフスクリーン サーフェスを作成することを示す。
'オフスクリーン サーフェスは、メモリ (ビデオ メモリまたはシステム メモリ) 内にあり、
'ユーザーからは見えないサーフェスである。
ddsdLake.lFlags = DDSD_CAPS Or DDSD_WIDTH Or DDSD_HEIGHT
ddsdLake.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
ddsdLake.lWidth = Picture1.Width
ddsdLake.lHeight = Picture1.Height

'サーフェスを作成し、lake.bmp をサーフェスにロードする。
Set objDDLakeSurf = objDD.CreateSurfaceFromFile("lake.bmp", ddsdLake)

'バックグラウンドを合成サーフェスにコピーする。
RepaintEntireBackground

'飛んでいる犬のスプライト イメージをロードする。

ddsdSprite.lFlags = DDSD_CAPS Or DDSD_WIDTH Or DDSD_HEIGHT
ddsdSprite.lWidth = 64
ddsdSprite.lHeight = 64
ddsdSprite.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN

Set objDDSpriteSurf = objDD.CreateSurfaceFromFile("disk1.bmp", ddsdSprite)

次に、スプライト サーフェスの透過色カラー キーを設定する。カラー キーは DDCOLORKEY 型変数によって指定する。このデータ型には low と high の 2 つのメンバがあり、いずれも Long 型である。カラー キーとして使用する値の範囲を指定するか、または両方のメンバに同じ値を渡せば単色を指定することができる。チュートリアル 2 のサンプルでは、high と low の両方のメンバの値が 0 であり、塗りつぶした黒をカラー キーとすることを示す。カラー キーをサーフェス上に設定するには、DirectDrawSurface7.SetColorKey メソッドを呼び出す。

サーフェス上で指定できるカラー キーには、以下の 2 つの種類がある。転送元カラー キーは、(ブリット時に) 転送先サーフェスにコピーされない、または (オーバーレイ時に) 転送先サーフェスには表示されない色である。転送先カラー キーは、(ブリット時に) 転送先サーフェス上で置き換えられる、または (オーバーレイ時に) 転送先サーフェス上でカバーされる色である。チュートリアル 2 のサンプルでは、転送元カラー キーを使用する。カラー キーの設定には、以下のステップを実行する。

'スプライトの透過色を設定する。

Dim key As DDCOLORKEY

key.low = 0
key.high = 0

'スプライト オブジェクトに透過色を割り当てる。
'DDCKEY_SRCBLT は、blt の実行時に、
'透過色はブリット先のサーフェスではなく
'転送元のサーフェスに関連付けられることを指定する。
objDDSpriteSurf.SetColorKey DDCKEY_SRCBLT, key

次項 : ステップ 3 : プライマリ サーフェスへのブリット


ステップ 3 : プライマリ サーフェスへのブリット

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

単純なスプライト アニメーションをスクリーン上に表示するには、いくつかのステップが必要である。スプライト サーフェスとバックグラウンド イメージがバック バッファに合成され、その後バック バッファがプライマリ サーフェスにブリットされる。アニメーションを作成するには、スプライト サーフェスをバック バッファにブリットするときに、転送先矩形の位置を継続的に動かす。チュートリアル 2 では、アプリケーションの実行中に、DoFrame プロシージャがスプライト サーフェスの位置を更新し、バックグラウンド イメージを再描画する。また、アニメーションの毎秒のフレーム数 (fps) を表示するためのコードがいくつかある。

始めに、単純なタイマ ループを実装してスプライトの配置角度を計算する。

t2 = Timer
If t1 <> 0 Then
    a = a + (t2 - t1) * 100
    If a > 360 Then a = a - 360
End If
t1 = t2

次に、作成したサーフェスがまだ制御できていることを確認する。ディスプレイ アダプタの制御が別のプリケーションに移った場合はサーフェスが消失することがあり、そのときはリストアする必要がある。チュートリアル 2 のサンプルには、DirectDraw オブジェクトの協調レベルをテストし、サーフェスをリストアする必要があるかどうかを決定する単純な関数 ExModeActive が含まれる。これを、以下のコードで示す。

Dim bRestore As Boolean
bRestore = False
Do Until ExModeActive
    DoEvents
    bRestore = True
Loop

DoEvents
If bRestore Then
    bRestore = False
    objDD.RestoreAllSurfaces
End If

次に、コードのスモール ビットを実装して、スプライト アニメーションの毎秒のフレーム数 (fps) を表示する。これは、アプリケーションを効率化し、アプリケーションに潜む障害を発見するのに役立つ。

'FPS を計算する。
i = i + 1
If i = 30 Then
    tNow = Timer
    If tNow <> tLast Then
       fps = 30 / (Timer - tLast)
       tLast = Timer
       i = 0
       Me.Caption = "DD Transparency    Frames per Second =" + Format$(fps, "#.0")
    End If
End If

次に、スプライトを配置する位置の x 座標と y 座標を計算する。

x = Cos((a / 360) * 2 * 3.141) * Picture1.Width / 8
y = Sin((a / 360) * 2 * 3.141) * Picture1.Height / 8
x = x + Picture1.Width / 2
y = y + Picture1.Height / 2

スプライトの直前の位置は RECT 型に保持されているため、バックグラウンド サーフェスの中で影響を受けた部分のみを再描画することができる。この結果、サーフェス全体を継続的にブリットする必要がなくなり、アプリケーションのパフォーマンスが向上する。次に、スプライトの新しい位置を決定し、スプライト サーフェスをバック バッファにブリットする。

'必要な部分のバックグラウンドだけを再描画して、
'最後のフレームからバックグラウンドを取り除く。
Dim rClean As RECT
If lastX <> 0 Then
    rClean.Left = lastX
    rClean.Top = lastY
    rClean.Right = lastX + ddsdSprite.lWidth
    rClean.Bottom = lastY + ddsdSprite.lHeight
    Call objDDBackBuffer.BltFast(lastX, lastY, objDDLakeSurf, rClean, DDBLTFAST_WAIT)
End If

lastX = x
lastY = y

'スプライトをバックバッファにブリットする。
'その際、転送元のカラー キーを使用し、
'blt の完了を待って移動を開始する。
Dim rtemp As RECT
rtemp.Left = x
rtemp.Top = y
rtemp.Right = x + ddsdSprite.lWidth
rtemp.Bottom = y + ddsdSprite.lHeight

objDDBackBuffer.Blt rtemp, objDDSpriteSurf, rSprite, DDBLT_KEYSRC Or DDBLT_WAIT

最後に、DirectX7.GetWindowRect メソッドを呼び出してピクチャボックス コントロールの矩形座標を取得し、DirectDrawSurface7.Blt メソッドを呼び出してバック バッファをプライマリ サーフェスにブリットする。

Call objDX.GetWindowRect(Picture1.hWnd, rPrim)

Call objDDScreen.Blt(rPrim, objDDBackBuffer, rBackBuffer, DDBLT_WAIT)


チュートリアル 3 : フルスクリーン機能の使用

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここでは、フルスクリーン DirectDraw アプリケーションの作成例を示す。このチュートリアルは、「チュートリアル 2 : 透過性の使用」とほぼ同様であるが、このチュートリアルではフルスクリーン内で実行するため、実装内容が少し異なる。このチュートリアルでは主に、プライマリ サーフェスにバック バッファを再ブリットする代わりに、複合サーフェスとフリッピング チェーンの概念を使用する。フルスクリーン アプリケーションは、以下のステップによって作成される。

  • ステップ 1 : 協調レベルとディスプレイ モードの設定
  • ステップ 2 : 複合サーフェスの作成
  • ステップ 3 : サーフェスの初期化
  • ステップ 4 : ページ フリッピングによるディスプレイの更新


ステップ 1 : 協調レベルとディスプレイ モードの設定

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectDraw でフルスクリーン アプリケーションを作成する最初のステップとして、DirectDraw オブジェクトの協調レベルとディスプレイ モードを設定する。協調レベルの設定によって、アプリケーションの最上位レベルの動作が決まる。このアプリケーションは、プライマリ ディスプレイに排他アクセスを行って、フル スクリーンで実行させたい。注 : フルスクリーン モードで実行するには、排他アクセスも必要である。さらに、標準 VGA Mode 13 から派生する Mode X を使用できるようにする。協調レベルは、以下の呼び出しによって設定する。

Set dd = dx.DirectDrawCreate("")
Me.Show
Call dd.SetCooperativeLevel(Me.hWnd, DDSCL_FULLSCREEN Or DDSCL_ALLOWMODEX Or DDSCL_EXCLUSIVE)

協調レベルを設定した後、DirectDraw7.SetDisplayMode メソッドを呼び出して、このアプリケーションのディスプレイ モードを設定する。

dd.SetDisplayMode 640, 480, 16, 0, DDSDM_DEFAULT

最初の 2 つのパラメータはモードの高さと幅である。3 つ目のパラメータはピクセルごとのビット数 (bpp) である。次のパラメータはリフレッシュ レートで、0 を指定してドライバのデフォルト リフレッシュ レートを要求する。最後のパラメータは追加オプションであり、DDSDM_DEFAULT は Mode X を Mode 13 で代用しないでモードを設定する。

次項 :ステップ 2 : 複合サーフェスの作成


ステップ 2 : 複合サーフェスの作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

チュートリアル 2 では、オフスクリーンのバック バッファ サーフェスが、バックグラウンド イメージとスプライト イメージの合成サーフェスとして使用された。このチュートリアルでは、バック バッファを複合サーフェスの部分として使用する。複合サーフェスとは DirectDraw7.CreateSurface メソッドへの単一呼び出しによって作成される一連のサーフェスを指す。CreateSurface を呼び出す際に DDSCAPS_COMPLEX フラグが設定されている場合、DirectDraw は、明示的に指定されたサーフェス以外に 1 つまたは複数のサーフェスを暗黙のうちに作成する。

複合サーフェスの中で最も便利なものの 1 つが、flipping chain である。通常、フリッピング チェーンは primary surface と 1 つ以上の back buffers. で構成される。DDSCAPS_FLIP フラグは、サーフェスがフリッピング チェーンの部分であることを示す。この方法でフリッピング チェーンを作成するには、DDSCAPS_COMPLEX フラグが必要である。

チュートリアル 2 のサンプルでは、以下の文によって、バック バッファを 1 つ持つフリッピング チェーンを作成する。

ddsd1.lFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT
ddsd1.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE Or DDSCAPS_FLIP Or DDSCAPS_COMPLEX
ddsd1.lBackBufferCount = 1
Set primary = dd.CreateSurface(ddsd1)

次に、DDSCAPS2 型変数を作成し、DSCAPS_BACKBUFFER フラグを設定して、これがバック バッファのサーフェス記述であることを指定する。そして、作成したバックバッファを DirectDrawSurface7.GetAttachedSurface メソッドを使用して取得する。

Dim caps As DDSCAPS2
caps.lCaps = DDSCAPS_BACKBUFFER
Set backbuffer = primary.GetAttachedSurface(caps)

次項 :ステップ 3 : サーフェスの初期化


ステップ 3 : サーフェスの初期化

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

バックグラウンド イメージとスプライト イメージのためのオフスクリーン サーフェス バッファの初期化は、本質的にはステップ 2 : と同じである。「サーフェスの初期化」は、チュートリアル 2 にある。唯一の相違は、ここではバック バッファのサーフェス記述によってバックグラウンド サーフェスを作成する点である。これは、DirectDrawSurface7.GetSurfaceDesc メソッドを呼び出すことで簡単に取得できる。これは、以下の文で示される。

backbuffer.GetSurfaceDesc ddsd4
ddsd2.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH
ddsd2.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
ddsd2.lWidth = ddsd4.lWidth
ddsd2.lHeight = ddsd4.lHeight
Set lakesurf = dd.CreateSurfaceFromFile("lake.bmp", ddsd2)

次項 :ステップ 4 : ページ フリッピングによるディスプレイの更新


ステップ 4 : ページ フリッピングによるディスプレイの更新

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

このステップは、チュートリアル 2 の「ステップ 3 : プライマリ サーフェスへのブリット」とほぼ同様である。実際、結果は同じだが、このチュートリアルではフルスクリーンで実行される点が異なる。しかし、バック バッファ全体をプライマリ サーフェスに継続的に再ブリットする代わりにバック バッファをフリッピング チェーンの一部として作成したため、ページ フリッピングを使用できる。

Page flipping は、マルチメディアやアニメーション、ゲームなどのソフトウェアでは重要である。ソフトウェア ページ フリッピングは、紙の束を使ってアニメーションを作成する方法に類似する。ページごとに形を少しずつ変えて描画し、紙をすばやくパタパタめくってアニメーションのように見せる方法である。

このアプリケーションは、バック バッファに書き込みを行い、そしてプライマリ サーフェスをフリップさせてバック バッファをスクリーン上に表示させる。システムがイメージを表示している間に、再びバック バッファへの書き込みを行う。アプリケーションが実行されている間この処理が継続され、イメージをすばやく効率的にアニメーションできる。

バックグラウンド イメージとスプライトをバックバッファにブリットした後、DirectDrawSurface7.Flip メソッドを呼び出してサーフェスをフリップする。

primary.Flip Nothing, DDFLIP_WAIT


チュートリアル 4 : スクリーンの領域へのブリット

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

SDK のチュートリアル 4 は、「チュートリアル 3 : フルスクリーン機能の使用」にスプライト アニメーションを追加したものとほぼ同様である。実際、この 2 つのアプリケーションの相違は、このチュートリアルではアニメーションのフレームが多いビットマップを使用するという点のみである。イメージ ビューアで donut.bmp ファイルを開くと、単一のビットマップであるにもかかわらず、少しずつ視点の異なる数多くのドーナツの形が存在することがわかる。アニメーションは、バック バッファ上でのスプライトの転送先矩形の位置を変更することで実行される。さらに、さまざまな視点のドーナツが循環してブリットされ、スプライトが回転する。

このチュートリアルはチュートリアル 3 に類似しているが、ここではスプライトをアニメーションする方法についても説明する。

  • ステップ 1 : スプライトのアニメーション


ステップ 1 : スプライトのアニメーション

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

donut.bmp イメージに含まれるドーナツの各インスタンスの高さと幅がわかっているため、ビットマップを列と行に分離して、各セルをドーナツの単一イメージにすることができる。

ddsd3.lFlags = DDSD_CAPS
ddsd3.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
Set spritesurf = dd.CreateSurfaceFromFile("donut.bmp ", ddsd3)
spriteWidth = 64
spriteHeight = 64
cols = ddsd3.lWidth / spriteWidth
rows = ddsd3.lHeight / spriteHeight

DirectDrawSurface7.BltFast メソッドをよく見ると、srcRect パラメータは、転送元サーフェス上からブリットされる矩形の左上と右下の点を定義する RECT 型であることがわかる。したがって、スプライト サーフェスの部分つまりセルをランダムに指定すれば、スプライト アニメーションが生成される。

col = currentFrame Mod cols
row = Int(currentFrame / cols)
rSprite.Left = col * spriteWidth
rSprite.Top = row * spriteHeight
rSprite.Right = rSprite.Left + spriteWidth
rSprite.Bottom = rSprite.Top + spriteHeight

'アニメーションされたスプライトをバックバッファに blt する。
ddrval = backbuffer.BltFast(rSprite2.Left, rSprite2.Top, spritesurf, _
         rSprite, DDBLTFAST_SRCCOLORKEY Or DDBLTFAST_WAIT)


チュートリアル 5 : DirectDraw デバイスの列挙

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

チュートリアル 5 のサンプル アプリケーションでは、DirectX for Visual Basic の列挙オブジェクトを使って、DirectDraw デバイスの情報を取得する方法を示す。このアプリケーションは、システムにインストールされている DirectDraw デバイスごとに、ハードウェアおよびソフトウェアの能力、3D ハードウェアおよびソフトウェアの能力、利用可能なディスプレイ モードを報告する。

このチュートリアルは、以下のステップで構成される。

  • ステップ 1 : インストールされている DirectDraw デバイスの取得
  • ステップ 2 : DirectDraw デバイスの能力の表示
  • ステップ 3 : DirectDraw デバイスの 3D 能力の表示
  • ステップ 4 : 利用可能なディスプレイ モードの報告


ステップ 1 : インストールされている DirectDraw デバイスの取得

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectX for Visual Basic では、実行時のディスプレイ ハードウェアの能力を照会し、そのホスト コンピュータのハードウェア能力で可能な最高のパフォーマンスを提供する。これは、DxVBLib タイプ ライブラリの多くの列挙オブジェクトを使用することにより、簡単に実行できる。

最初のステップでは、システム上にインストールされているすべての DirectDraw デバイスを取得する。プライマリ ディスプレイ アダプタ以外に、システムによっては複数のディスプレイ カードがインストールされている場合がある。一般的には、二次的な 3D グラフィックス カードである。インストールされているすべてのデバイスを取得するには、DirectX7.GetDDEnum メソッドを呼び出す。このメソッドは、情報を照会する DirectDrawEnum オブジェクトを返す。DirectDrawEnum オブジェクトのメソッドによって、インストールされているデバイス数と、各デバイスの名称、説明、GUID、およびモニタ ハンドルを取得する。

チュートリアル 5 のサンプル アプリケーションでは、これを以下のコードで実行する。

Dim ddEnum As DirectDrawEnum
Dim strGuid As String

Set ddEnum = m_dx.GetDDEnum()
OutList.AddItem "Display Cards"
For i = 1 To ddEnum.GetCount()
    OutList.AddItem " Index        " + Str(i)
    OutList.AddItem " Description  " + ddEnum.GetDescription(i)
    OutList.AddItem " Name         " + ddEnum.GetName(i)
    OutList.AddItem " GUID         " + ddEnum.GetGuid(i)
    OutList.AddItem ""

    strGuid = ddEnum.GetGuid(i)
    GetDDCaps strGuid
    GetD3DDevices strGuid
    GetDisplayModes strGuid

Next

GetDDCaps、GetD3DDevices、および GetDisplayModes の各プロシージャは、システムにインストールされているデバイスごとに呼び出されることに注意する。

情報は、リスト ボックス コントロールに記載された形で表示される。

次項 : ステップ 2 : DirectDraw デバイスの能力の表示


ステップ 2 : DirectDraw デバイスの能力の表示

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

デバイスの DirectDraw ハードウェアおよびソフトウェアの能力を取得するには、まず DirectDraw オブジェクトを作成して、アプリケーションの協調レベルを設定して DirectDraw7.GetCaps メソッドを呼び出す。このメソッドは 2 つのパラメータを取るが、どちらも DDCAPS 型変数である。このメソッドを呼び出すと、最初のパラメータ hwCaps にハードウェアの能力が格納される。2 つ目のパラメータ helCaps には、ハードウェア エミレーション レイヤ (HEL) の能力が格納される。ハードウェアおよびソフトウェア能力の詳細情報は、「DirectDraw アーキテクチャの概要」を参照すること。

GetCaps メソッドを呼び出した後で、DDCAPS 変数に返されたフラグをチェックし、能力を表示する。

Dim dd As DirectDraw7
Dim hwCaps As DDCAPS   'ハードウェア。
Dim helCaps As DDCAPS  'ソフトウェア エミュレーション。

Set dd = m_dx.DirectDrawCreate(sGuid)
dd.SetCooperativeLevel Me.hWnd, DDSCL_NORMAL

'HW が機能をサポート
'するかどうかを調べるのは良い考えである。
'サポートされない機能は、ソフトウェアを介して
'エミュレートされるが、処理速度はかなり遅くなる。
dd.GetCaps hwCaps, helCaps

'利用可能なビデオ メモリ量。
OutList.AddItem "  HW CAPS"
OutList.AddItem "   total video memory " + Str(hwCaps.lVidMemTotal)
OutList.AddItem "   free video memory " + Str(hwCaps.lVidMemFree)

'パレット サポート。
'ほとんどのアプリケーションは、すべてのカードが
'16bpp をサポートするため、パレットを使用しない。
'速度の観点から 8bpp を使用する場合もある。

lVal = hwCaps.lPalCaps
If (lVal = 0) Then
    OutList.AddItem "   no hw palette support"
End If
If (lVal And DDPCAPS_1BIT) Then
    OutList.AddItem "   palette support 1bpp "
End If
If (lVal And DDPCAPS_2BIT) Then
    OutList.AddItem "   palette support 2bit "
End If

'ガンマ ランプ インターフェイスをサポートするか ?
lVal = hwCaps.ddsCaps.lCaps2
If lVal And DDCAPS2_CANCALIBRATEGAMMA Then
    OutList.AddItem "   supports gamma correction"
Else
    OutList.AddItem "   no support for gamma correction"
End If

Set dd = Nothing

次項 : ステップ 3 : DirectDraw デバイスの 3D 能力の表示


ステップ 3 : DirectDraw デバイスの 3D 能力の表示

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectDraw デバイスの 3D 能力の取得は、このチュートリアルの前のステップとほぼ同様である。まず、Direct3D7 オブジェクトを DirectDraw7 オブジェクトから作成する。次に、Direct3D7.GetDevicesEnum メソッドを呼び出して Direct3DEnumDevices 列挙オブジェクトを作成し、情報を埋め込む。そして、列挙オブジェクトのメソッドを呼び出し、システムの Direct3D デバイスについての情報を取得する。

チュートリアル 5 のサンプルでは、Direct3DEnumDevices.GetDesc メソッドを Direct3D デバイスごとに呼び出して、能力を取得する。次に、D3DDEVICEDESC7 型で能力フラグをチェックすると、その結果がリスト ボックスで報告される。これは、以下の文で示される。

Set dd = m_dx.DirectDrawCreate(sGuid)
Set d3d = dd.GetDirect3D()

OutList.AddItem "   D3D devices"

Set d3denum = d3d.GetDevicesEnum()

OutList.AddItem ""

For i = 1 To d3denum.GetCount()

    d3denum.GetDesc i, hwDesc
    OutList.AddItem "     Guid        " + d3denum.GetGuid(i)
    OutList.AddItem "     Description " + d3denum.GetDescription(i)
    OutList.AddItem "     Name        " + d3denum.GetName(i)
    OutList.AddItem "     Device "
    With hwDesc
        OutList.AddItem "     Max Texture Height  " + Str(.lMaxTextureHeight)
        OutList.AddItem "     Max Texture Width   " + Str(.lMaxTextureWidth)
        If (.lDeviceRenderBitDepth And DDBD_8) Then
            OutList.AddItem "     Supports rendering to 8 bit"
        End If
        If (.lDeviceZBufferBitDepth And DDBD_8) Then
            OutList.AddItem "     Supports  8 bit z buffer"
        End If
        If (.lDevCaps And D3DDEVCAPS_TEXTURENONLOCALVIDMEM) Then
            OutList.AddItem "     Supports AGP textures"
        End If
    End With

次項 : ステップ 4 : 利用可能なディスプレイ モードの報告


ステップ 4 : 利用可能なディスプレイ モードの報告

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ チュートリアル」を参照すること。

[Visual Basic]

ディスプレイ モードとは、ディスプレイ ハードウェアがプライマリ サーフェスからモニタに送るグラフィックスの寸法やビット深度を記述するハードウェア設定のことである。ディスプレイ モードは、幅、高さ、ビット深度といった定義特性によって記述される。たとえば、大部分のディスプレイ アダプタは、幅 640 ピクセルで高さ 480 ピクセルのグラフィックスを表示できる。ここで、各ピクセルは 8 ビットのデータである。このディスプレイ モードは、640×480×8 と表される。ディスプレイ モードの寸法が大きくなったりビット深度が増加すると、より多くのディスプレイ メモリが必要となる。

ディスプレイ モードのサポートは、ディスプレイ アダプタによって異なる。特定のディスプレイ モードがシステム上でサポートされていることを確かめるには、DirectDraw7.GetDisplayModesEnum メソッドを使用して、有効なディスプレイ モードをすべて列挙する。このメソッドは、DisplayModesEnum と呼ばれる DirectDrawEnumModes 列挙オブジェクトを作成し、そこに情報を埋め込む。そして、このオブジェクトを使用して各ディスプレイ モードの記述を取得する。

チュートリアル 5 のサンプルでは、サポートされているディスプレイ モードごとに、DisplayModesEnum オブジェクトのメソッドを呼び出す。

Dim DisplayModesEnum As DirectDrawEnumModes
Dim ddsd2 As DDSURFACEDESC2
Dim dd As DirectDraw7
Set dd = m_dx.DirectDrawCreate(sGuid)
dd.SetCooperativeLevel Me.hWnd, DDSCL_NORMAL
Set DisplayModesEnum = dd.GetDisplayModesEnum(0, ddsd2)
OutList.AddItem " Display Modes"
For i = 1 To DisplayModesEnum.GetCount()
    DisplayModesEnum.GetItem i, ddsd2
    OutList.AddItem "  Index          " + Str(i)
    OutList.AddItem "  Width          " + Str(ddsd2.lWidth)
    OutList.AddItem "  Height         " + Str(ddsd2.lHeight)
    OutList.AddItem "  Bits Per Pixel" + Str(ddsd2.ddpfPixelFormat.lRGBBitCount)
    OutList.AddItem "  Refresh Rate   " + Str(ddsd2.lRefreshRate)
    OutList.AddItem ""
Next


DirectDraw リファレンス

ここでは、Microsoft® DirectDraw® が提供する C/C++ および Microsoft® Visual Basic® のアプリケーション プログラミング インターフェイス (API) 要素のリファレンス情報を記述する。リファレンス情報は以下の言語別に構成される。

  • DirectDraw C/C++ リファレンス
  • DirectDraw Visual Basic リファレンス


DirectDraw C/C++ リファレンス

ここでは、DirectDraw が提供する API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • インターフェイス
  • 関数
  • コールバック関数
  • 構造体
  • 戻り値
  • ピクセル フォーマット マスク
  • 4 文字コード (FOURCC)


インターフェイス

ここでは、DirectDraw コンポーネントで使用するインターフェイスのリファレンス情報を記述する。以下のインターフェイスを説明の対象とする。

  • IDDVideoPortContainer
  • IDirectDraw7
  • IDirectDrawClipper
  • IDirectDrawColorControl
  • IDirectDrawGammaControl
  • IDirectDrawPalette
  • IDirectDrawSurface7
  • IDirectDrawVideoPort


IDDVideoPortContainer

アプリケーションは、IDDVideoPortContainer インターフェイスのメソッドを使って、DirectDrawVideoPort オブジェクトを作成したり処理する。このインターフェイスへのポインタを取得するには、IID_IDDVideoPortContainer 参照識別子を指定して、DirectDraw オブジェクトの IUnknown::QueryInterface メソッドを呼び出す。

IDDVideoPortContainer インターフェイスのメソッドは、以下のグループにまとめることができる。

オブジェクトの作成 | CreateVideoPort
ビデオ ポート | EnumVideoPorts
 | QueryVideoPortStatus
コネクション | GetVideoPortConnectInfo

すべての COM インターフェイスと同様、IDDVideoPortContaine インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDDVIDEOPORTCONTAINER データ型を使用すると、IDDVideoPortContainer インターフェイスへのポインタを含む変数を宣言できる。dvp.h ヘッダー ファイルは、以下のコードで LPDDVIDEOPORTCONTAINER を宣言する。

typedef struct IDDVideoPortContainer    FAR *LPDDVIDEOPORTCONTAINER;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDDVideoPortContainer::CreateVideoPort

IDDVideoPortContainer::CreateVideoPort メソッドは、DirectDrawVideoPort オブジェクトを作成する。

HRESULT CreateVideoPort(
  DWORD dwFlags,
  LPDDVIDEOPORTDESC lpDDVideoPortDesc,
  LPDIRECTDRAWVIDEOPORT FAR *lplpDDVideoPort,
  IUnknown FAR *pUnkOuter
);

パラメータ

dwFlags
ビデオポート コントロール オプションを指定するフラグ。このパラメータには、次のフラグの 1 つを指定する。もしくは、コントロール オプションを必要としない場合は NULL にする。
DDVPCREATE_VBIONLY
このプロセスは、単にビデオ ストリームの VBI 部分を制御する。
DDVPCREATE_VIDEOONLY
このプロセスは、単にビデオ ストリームの VBI でない (ビデオ) 部分を制御する。
lpDDVideoPortDesc
作成する DirectDrawVideoPort オブジェクトを記述する DDVIDEOPORTDESC 構造体のアドレス。
lplpDDVideoPort
呼び出しが成功した場合に、新しい DirectDrawVideoPort オブジェクトの IDirectDrawVideoPort インターフェイスへのポインタを格納する変数のアドレス。
pUnkOuter
COM 処理機能との将来的な互換のためにある。ただし、現時点では、このパラメータを NULL に設定しないと、このメソッドはエラーを返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CURRENTLYNOTAVAIL
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFCAPS
DDERR_OUTOFMEMORY

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDDVideoPortContainer::EnumVideoPorts

IDDVideoPortContainer::EnumVideoPorts メソッドは、ハードウェアが公開するビデオ ポートのうち、提供されたビデオポート記述と互換性があるすべてのビデオ ポートを列挙する。

HRESULT EnumVideoPorts(
  DWORD dwFlags,
  LPDDVIDEOPORTCAPS lpDDVideoPortCaps,
  LPVOID lpContext,
  LPENUMVIDEOCALLBACK lpEnumVideoCallback
);

パラメータ

dwFlags
将来的な使用のために確保されている。このパラメータは 0 でなければならない。
lpDDVideoPortCaps
利用可能なビデオ ポートと照合する DDVIDEOPORTCAPS 構造体のアドレス。このパラメータが NULL の場合、すべてのビデオ ポートが列挙される。
lpContext
個々の列挙メンバに渡される、呼び出し側で定義される構造体のアドレス。
lpEnumVideoCallback
一致するものが見つかるたびに呼び出される EnumVideoCallback 関数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDDVideoPortContainer::GetVideoPortConnectInfo

IDDVideoPortContainer::GetVideoPortConnectInfo メソッドは、すべてのビデオ ポートがサポートするコネクション情報を取得する。

HRESULT GetVideoPortConnectInfo(
  DWORD dwPortId,
  LPDWORD lpNumEntries,
  LPDDVIDEOPORTCONNECT lpConnectInfo
);

パラメータ

dwPortId
取得するコネクション情報に対するビデオ ポートの識別子。
lpNumEntries
lpConnectInfo の配列で保持できるエントリ数を含む変数のアドレス。エントリ数がコネクションの合計数より少ない場合、メソッドは適合するだけのエントリを配列に格納し、コネクションの合計数を示す lpNumEntries で値を設定して、DDERR_MOREDATA を返す。
lpConnectInfo
指定したビデオ ポートでサポートされるコネクション オプションを格納する DDVIDEOPORTCONNECT 構造体の配列のアドレス。このパラメータが NULL の場合、メソッドはビデオ ポートがサポートするコネクションの合計数を示すように lpNumEntries を設定して、DD_OK を返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDDVideoPortContainer::QueryVideoPortStatus

IDDVideoPortContainer::QueryVideoPortStatus メソッドは、DirectDrawVideoPort オブジェクトのステータスを取得する。

HRESULT QueryVideoPortStatus(
  DWORD dwPortId,
  LPDDVIDEOPORTSTATUS lpVPStatus
);

パラメータ

dwPortId
取得するステータス情報に対するビデオ ポートの識別子。
lpVPStatus
指定したビデオ ポートのステータス情報を格納する DDVIDEOPORTSTATUS 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CURRENTLYNOTAVAIL
DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDraw7

アプリケーションは IDirectDraw7 インターフェイスのメソッドを使って、DirectDraw オブジェクトを作成し、システムレベル変数と共に作用する。ここでは、このインターフェイスのメソッドのリファレンスを提供する。概念の概要については、「DirectDraw オブジェクト」を参照すること。

IDirectDraw7 インターフェイスのメソッドは、以下のグループにまとめることができる。

メモリの割り当て | Compact
 | Initialize
協調レベル | SetCooperativeLevel
 | TestCooperativeLevel
オブジェクトの作成 | CreateClipper
 | CreatePalette
 | CreateSurface
デバイス能力 | GetCaps
ディスプレイ モード | EnumDisplayModes
 | GetDisplayMode
 | GetMonitorFrequency
 | RestoreDisplayMode
 | SetDisplayMode
 | WaitForVerticalBlank
ディスプレイ ステータス | GetScanLine
 | GetVerticalBlankStatus
その他 | EvaluateMode
 | GetAvailableVidMem
 | GetDeviceIdentifier
 | GetFourCCCodes
 | StartModeTest
サーフェス管理 | DuplicateSurface
 | EnumSurfaces
 | FlipToGDISurface
 | GetGDISurface
 | GetSurfaceFromDC
 | RestoreAllSurfaces

すべての COM インターフェイスと同様、IDirectDraw7 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectDraw7 インターフェイスは、以前のバージョンよりも柔軟にサーフェスを管理できるメソッドが提供されることにより、インターフェイスの前のバージョンにおける機能を拡張している。IDirectDraw７ インターフェイスのすべてのサーフェス関連メソッドは、IDirectDraw2 インターフェイスにおいて対応するサーフェス関連メソッドとは若干異なるパラメータを受け取る。IDirectDraw2 インターフェイス メソッドが DDSURFACEDESC 構造体を受け取り、IDirectDrawSurface3 インターフェイスを取得する位置では、常にその代わりに IDirectDraw7 のメソッドが DDSURFACEDESC2 構造体を受け取り、IDirectDrawSurface7 インターフェイスを取得する。

IDirectDraw7 は、子オブジェクトの有効期間を指示する COM 規則に準拠して改善された。詳細については、「親オブジェクトと子オブジェクトの有効期間」を参照すること。

LPDIRECTDRAW、LPDIRECTDRAW2、LPDIRECTDRAW4、または LPDIRECTDRAW7 データ型を使用して、IDirectDraw、IDirectDraw2、IDirectDraw4、または IDirectDraw7 インターフェイスへのポインタを含む変数を宣言する。ddraw.h ヘッダー ファイルは、以下のコードでこれらのデータ型を宣言する。

typedef struct IDirectDraw     FAR *LPDIRECTDRAW;
typedef struct IDirectDraw2    FAR *LPDIRECTDRAW2;
typedef struct IDirectDraw4    FAR *LPDIRECTDRAW4;
typedef struct IDirectDraw7    FAR *LPDIRECTDRAW7;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::Compact

IDirectDraw7::Compact メソッドは、現時点では実装されていない。

HRESULT Compact();

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::CreateClipper

IDirectDraw7::CreateClipper メソッドは、DirectDrawClipper オブジェクトを作成する。

HRESULT CreateClipper(
  DWORD dwFlags,
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper,
  IUnknown FAR *pUnkOuter
);

パラメータ

dwFlags
現時点では未使用なので 0 を設定しておく。
lplpDDClipper
呼び出しが成功した場合に、有効な IDirectDrawClipper インターフェイス ポインタを設定する変数のアドレス。
pUnkOuter
COM 処理機能との将来的な互換のためにある。ただし、現時点では、このパラメータを NULL に設定しないと、このメソッドはエラーを返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY

注意

DirectDrawClipper オブジェクトは DirectDrawSurface にアタッチでき、IDirectDrawSurface7::Blt、IDirectDrawSurface7::BltBatch、および IDirectDrawSurface7::UpdateOverlay の処理中に使用できる。

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

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetClipper、IDirectDrawSurface7::SetClipper


IDirectDraw7::CreatePalette

IDirectDraw7::CreatePalette メソッドは、この DirectDraw オブジェクトに対する DirectDrawPalette オブジェクトを作成する。

HRESULT CreatePalette(
  DWORD dwFlags,
  LPPALETTEENTRY lpDDColorArray,
  LPDIRECTDRAWPALETTE FAR *lplpDDPalette,
  IUnknown FAR *pUnkOuter
);

パラメータ

dwFlags
以下のフラグのうち、1 つ以上の値を取る。
DDPCAPS_1BIT
インデックスは 1 ビットである。カラー テーブルには、2 つのエントリがある。
DDPCAPS_2BIT
インデックスは 2 ビットである。カラー テーブルには、4 つのエントリがある。
DDPCAPS_4BIT
インデックスは 4 ビットである。カラー テーブルには、16 のエントリがある。
DDPCAPS_8BIT
インデックスは 8 ビットである。カラー テーブルには、256 のエントリがある。
DDPCAPS_8BITENTRIES
インデックスが 8 ビット カラー インデックスを参照する。DDPCAPS_1BIT、DDPCAPS_2BIT、または DDPCAPS_4BIT フラグを使用する場合、およびターゲット サーフェスが 8 bpp の場合のみ、このフラグは有効となる。個々のカラー エントリは 1 バイト長であり、転送先サーフェスの 8 bpp パレットへのインデックスである。
DDPCAPS_ALPHA
関連付けられた PALETTEENTRY 構造体の peFlags メンバが、単一の 8 ビット アルファ値 (また、peRed、peGreen、および peBlue メンバ) として判断される。このフラグで作成されるパレットは、テクスチャ、つまり、DDSCAPS_TEXTURE 能力フラグで作成されたサーフェスにのみアタッチできる。
DDPCAPS_ALLOW256
このパレットは全 256 エントリを定義できる。
DDPCAPS_INITIALIZE
廃止。DirectDraw は、常に lpDDColorArray で渡された色配列の色でこのパレットを初期化する。
DDPCAPS_PRIMARYSURFACE
プライマリ サーフェスにこのパレットをアタッチする。このパレットのカラー テーブルを変更すると、DDPSETPAL_VSYNC が指定されてサポートされないかぎり、即座にディスプレイに影響を与える。
DDPCAPS_PRIMARYSURFACELEFT
このパレットは、左眼プライマリ サーフェスにアタッチされる。このパレットのカラー テーブルを変更すると、DDPSETPAL_VSYNC が指定されてサポートされないかぎり、即座に左眼ディスプレイに影響を与える。
DDPCAPS_VSYNC
このパレットは、モニタのリフレッシュ レートと同期するように修正できる。
lpDDColorArray
この DirectDrawPalette オブジェクトを初期化する 2、4、16、または 256 PALETTEENTRY 構造体の配列のアドレス。
lplpDDPalette
呼び出しが成功した場合に、有効な IDirectDrawPalette インターフェイス ポインタに設定される変数のアドレス。
pUnkOuter
COM 処理機能との将来的な互換のためにある。ただし、現時点では、このパラメータを NULL に設定しないと、このメソッドはエラーを返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::CreateSurface

IDirectDraw7::CreateSurface メソッドは、この DirectDraw オブジェクトに対する DirectDrawSurface オブジェクトを作成する。

HRESULT CreateSurface(
  LPDDSURFACEDESC2 lpDDSurfaceDesc2,
  LPDIRECTDRAWSURFACE7 FAR *lplpDDSurface,
  IUnknown FAR *pUnkOuter
);

パラメータ

lpDDSurfaceDesc2
要求するサーフェスを記述する DDSURFACEDESC2 構造体のアドレス。このメソッドを呼び出す前に、DDSURFACEDESC2 構造体の未使用メンバをすべて 0 に設定する。DDSCAPS2 構造体は、DDSURFACEDESC2 のメンバである。
lplpDDSurface
呼び出しが成功した場合に、有効な IDirectDrawSurface7 インターフェイス ポインタに設定される変数のアドレス。
pUnkOuter
COM 処理機能との将来的な互換のためにある。ただし、現時点では、このパラメータを NULL に設定しないと、このメソッドはエラーを返す。

戻り値

成功すれば、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_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::DuplicateSurface

IDirectDraw7::DuplicateSurface メソッドは、DirectDrawSurface オブジェクトを複製する。

HRESULT DuplicateSurface(
  LPDIRECTDRAWSURFACE7 lpDDSurface,
  LPLPDIRECTDRAWSURFACE7 FAR *lplpDupDDSurface
);

パラメータ

lpDDSurface
複製するサーフェスの IDirectDrawSurface7 インターフェイスのアドレス。
lplpDupDDSurface
新しく複製する DirectDrawSurface オブジェクトの IDirectDrawSurface7 インターフェイスを格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CANTDUPLICATE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACELOST

注意

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

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::EnumDisplayModes

IDirectDraw7::EnumDisplayModes メソッドは、ハードウェアが DirectDraw オブジェクトを介して公開するディスプレイ モードのうち、提供されたサーフェス記述と互換性があるすべてのディスプレイ モードを列挙する。

HRESULT EnumDisplayModes(
  DWORD dwFlags,
  LPDDSURFACEDESC2 lpDDSurfaceDesc2,
  LPVOID lpContext,
  LPDDENUMMODESCALLBACK2 lpEnumModesCallback
);

パラメータ

dwFlags
DDEDM_REFRESHRATES
異なるリフレッシュ レートでモードを列挙する。IDirectDraw7::EnumDisplayModes は、特定のモードを 2 回以上列挙することはない。このフラグは、モードがユニークかどうかを判断する際にリフレッシュ レートを考慮するかどうかを指定する。
DDEDM_STANDARDVGAMODES
320 × 200 × 8 モード X モード以外に、モード 13 を列挙する。
lpDDSurfaceDesc2
利用可能なモードと照合する DDSURFACEDESC2 構造体のアドレス。このパラメータの値が NULL の場合、すべてのモードが列挙される。
lpContext
個々の列挙メンバに渡すアプリケーション定義構造体のアドレス。
lpEnumModesCallback
一致の見つかるたびに列挙プロシージャが呼び出す EnumModesCallback2 関数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DDSURFACEDESC2 構造体の dwRefreshRate メンバを列挙する。つまり、IDirectDraw::EnumDisplayModes メソッドにはこの能力がない。IDirectDraw7::SetDisplayMode メソッドを使用して新しいモードのリフレッシュ レートを設定する場合は、IDirectDraw7::EnumDisplayModes を使用して dwRefreshRate メンバを列挙しなければならない。

このメソッドは以前のインターフェイスの対応するメソッドとは異なり、EnumModesCallback 関数ではなくパラメータとして EnumModesCallback2 関数のアドレスを受け取る。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::GetDisplayMode、IDirectDraw7::SetDisplayMode、IDirectDraw7::RestoreDisplayMode


IDirectDraw7::EnumSurfaces

IDirectDraw7::EnumSurfaces メソッドは、指定されたサーフェス記述を満たす、既存のまたは可能なサーフェスをすべて列挙する。

HRESULT EnumSurfaces(
  DWORD dwFlags,
  LPDDSURFACEDESC2 lpDDSD2,
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpEnumSurfacesCallback
);

パラメータ

dwFlags
1 つの検索タイプ フラグと 1 つの適合フラグの組み合わせ。検索タイプ フラグは、メソッドによる適合フラグの検索方法を決定する。つまり、lpDDSD2 パラメータの記述を使用して作成できるサーフェスを検索したり、既にその記述に適合する既存のサーフェスを検索できる。適合フラグは、メソッドによるサーフェスの列挙方法として、すべてのサーフェスを列挙する、適合するサーフェスのみ列挙する、または lpDDSD2 パラメータの記述に適合しないサーフェスのみ列挙するかどうかを決定する。

検索タイプ フラグ

DDENUMSURFACES_CANBECREATED
作成可能で検索基準に合う最初のサーフェスを列挙する。このフラグは、DDENUMSURFACES_MATCH フラグとのみ併用できる。
DDENUMSURFACES_DOESEXIST
検索基準に合う既存のサーフェスを列挙する。

適合フラグ

DDENUMSURFACES_ALL
検索基準を満たすサーフェスをすべて列挙する。このフラグは、DDENUMSURFACES_DOESEXIST 検索タイプ フラグとのみ併用できる。
DDENUMSURFACES_MATCH
サーフェス記述に適合するサーフェスを検索する。
DDENUMSURFACES_NOMATCH
サーフェス記述に適合しないサーフェスを検索する。
lpDDSD2
対象のサーフェスを定義する DDSURFACEDESC2 構造体のアドレス。dwFlags に DDENUMSURFACES_ALL フラグがある場合、このパラメータは NULL にする。
lpContext
個々の列挙メンバに渡すアプリケーション定義構造体のアドレス。
lpEnumSurfacesCallback
一致の見つかるたびに列挙プロシージャが呼び出す EnumSurfacesCallback2 関数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

DDENUMSURFACES_CANBECREATED フラグを設定する場合、このメソッドは検索基準に合うサーフェスを一時的に作成しようとする。

DDENUMSURFACES_DOESEXIST フラグを使用している場合、列挙されるサーフェスの参照カウント がインクリメントされる。そのサーフェスを使用しない場合は、個々の列挙の後に、IDirectDrawSurface7::Release を使用してサーフェスを解放しなければならない。サーフェスを使用する場合は、そのサーフェスが不要になったときに解放する。

このメソッドは以前のバージョンのインターフェイスの対応するメソッドとは異なり、EnumSurfacesCallback 関数よりも EnumSurfacesCallback2 関数へのポインタを受け取る。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

サーフェスの列挙


IDirectDraw7::EvaluateMode

IDirectDraw7::EvaluateMode メソッドは、IDirectDraw7::StartModeTest を呼び出した後、各モードのテストのクリアまたは失敗を決定し、テストが完了するまでモードを 1 つずつテストする。

HRESULT EvaluateMode(
  DWORD  dwFlags,
  DWORD  *pSecondsUntilTimeout
);

パラメータ

dwFlags
テストするモードのステータスを示すフラグ。
DDEM_MODEPASSED
モードがテストにクリアした。
DDEM_MODEFAILED
モードがテストに失敗した。
pSecondsUntilTimeout
現在のモードのクリアまたは失敗を明示的に行わない限り、自動的に失敗と見なすまでの秒数を示す値を受け取る DWORD へのポインタ。

戻り値

成功すれば、DD_OK を返す。

失敗または完了の場合は、以下のエラー値のいずれかを返す。

DDERR_TESTFINISHED
DDERR_NEWMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

注意

IDirectDraw7::EvaluateMode メソッドを IDirectDraw7::StartModeTest メソッドと併用すれば、EDID モニタおよびディスプレイ アダプタの組み合わせによって各スクリーン解像度でサポートできる最大リフレッシュ レートを決定できる。

特に IDirectDraw7::StartModeTest は、テスト可能な解像度のセットを作成し、そのセット内の最初の解像度に基づいてモードを表示するよう DirectDraw に命令する。この呼び出しに続く IDirectDraw7::EvaluateMode の呼び出しでは、各モードのテストのクリアまたは失敗を決定して、次のディスプレイ モードのテストに進む。このメソッドは、指定の解像度をサポートする最大リフレッシュ レートから順にテスト可能解像度を 1 つずつテストする。指定の解像度のリフレッシュ レートがテストにクリアすると、それより低いリフレッシュ レートのテストは省略される。

テストが初期化された場合、あるいはモードがテストにクリアまたは失敗した場合、DirectDraw は 15 秒のタイムアウトを設定し直す。アプリケーションでは、dwFlags 引数の値を 0 に設定して IDirectDraw7::EvaluateMode を呼び出すことで、現在のモードがテストにクリアまたは失敗するまでの残り時間を監視できる。IDirectDraw7::EvaluateMode が呼び出された場合のみ、DirectDraw はモードを変更またはテストを終了するので注意すること。ただし、タイムアウト期間の経過後にメソッドが呼び出された場合は、dwFlags 引数の設定値には無関係に、現在のモードは失敗する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::StartModeTest、リフレッシュ レートの列挙


IDirectDraw7::FlipToGDISurface

IDirectDraw7::FlipToGDISurface メソッドは、GDI がプライマリ サーフェス に書き込むサーフェスを作成する。

HRESULT FlipToGDISurface();

パラメータ

なし。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

注意

このメソッドは、ページフリッピング アプリケーションの最後に呼び出すと、GDI が書き込むディスプレイ メモリを表示状態にできる。

このメソッドは、また、GDI サーフェスをプライマリ サーフェスにし、ダイアログ ボックスなどの通常のウィンドウをフルスクリーン モードで表示できるようにする。ハードウェアには DDCAPS2_CANRENDERWINDOWED 能力が必要である。詳細については、「フルスクリーン モードでのウィンドウの表示」を参照すること。

このメソッドは、ステレオ自動フリッピングを無効にする。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::GetGDISurface


IDirectDraw7::GetAvailableVidMem

IDirectDraw7::GetAvailableVidMem メソッドは、利用可能なディスプレイ メモリの総容量、およびサーフェスの与えられたタイプに対するディスプレイ メモリの現在の空き容量を取得する。

HRESULT GetAvailableVidMem(
  LPDDSCAPS2 lpDDSCaps2,
  LPDWORD    lpdwTotal,
  LPDWORD    lpdwFree
);

パラメータ

lpDDSCaps2
掲示されたサーフェスのハードウェア能力を示す DDSCAPS2 構造体のアドレス。
lpdwTotal
バイト単位で表す、利用可能なディスプレイ メモリの総容量を格納する変数のアドレス。取得した値は、総ビデオ メモリ容量を反映する。この容量には、プライマリ サーフェス用およびディスプレイ ドライバが確保するプライベート キャッシュ用のビデオ メモリは含まれない。
lpdwFree
lpDDSCaps2 の構造体で指定する能力に適合するサーフェスに割り当てられる、ディスプレイ メモリの現在の空き容量を格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

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

注意

次の C++ の例では、IDirectDraw7::GetAvailableVidMem を使用して、テクスチャ マップ サーフェスで利用可能なディスプレイ メモリの総容量および空き容量の両方を決定する方法を示す。

// たとえば、lpDD 変数は IDirectDraw インターフェイスへの
// 有効なポインタとなる。
LPDIRECTDRAW7 lpDD;
DDSCAPS2      ddsCaps2;
DWORD         dwTotal;
DWORD         dwFree;
HRESULT       hr;

hr = lpDD->QueryInterface(IID_IDirectDraw7, &lpDD);
if (FAILED(hr))
    return hr;

// 構造体を初期化する。
ZeroMemory(&ddsCaps2, sizeof(ddsCaps2));

ddsCaps2.dwCaps = DDSCAPS_TEXTURE;
hr = lpDD->GetAvailableVidMem(&ddsCaps2, &dwTotal, &dwFree);
if (FAILED(hr))
    return hr;

サーフェスに DDSCAPS_VIDEOMEMORY フラグ セットがある場合、このメソッドは、サーフェスが 3D テクスチャとして使用できるかどうかによって異なるビデオ メモリ容量を返す。サーフェスが 3D テクスチャとして使用できる場合、GetAvailableVidMem メソッドは AGP システムのローカルおよび非ローカル ビデオ メモリの総容量を返す。

このメソッドは、現在のディスプレイメモリの瞬間的な状態だけを提供する。ディスプレイ メモリの空き容量は、サーフェスの作成と解放により変化する。したがって、空きメモリ容量の値は単に近似値として使用すべきである。また、特定のディスプレイ アダプタ カードで 2 つの異なるメモリ タイプを区別しない場合もある。たとえば、アダプタはディスプレイ メモリの同じ部分を使って、Z バッファとテクスチャを格納する場合がある。このため、サーフェスのある特定のタイプ (たとえば、Z バッファ) を割り当てたとき、ほかのタイプのサーフェス (たとえば、テクスチャ) で利用できるディスプレイ メモリの容量に影響する場合がある。したがって、動的使用 (テクスチャ マッピング など) で利用できるメモリ容量を決める前に、アプリケーションの固定リソース (フロントとバック バッファ、および Z バッファなど) を最初に割り当てすることが最良の方法となる。

このメソッドは、IDirectDraw インターフェイスには実装されていない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::GetCaps

IDirectDraw7::GetCaps メソッドは、ハードウェアとハードウェア エミュレーション レイヤ (HEL) に対するデバイス ドライバの能力を格納する。

HRESULT GetCaps(
  LPDDCAPS lpDDDriverCaps,
  LPDDCAPS lpDDHELCaps
);

パラメータ

lpDDDriverCaps
デバイス ドライバが報告するハードウェア能力を格納する DDCAPS 構造体のアドレス。デバイス ドライバ能力を取得しない場合は、このパラメータを NULL に設定する。
lpDDHELCaps
HEL の能力を格納する DDCAPS 構造体のアドレス。HEL の能力を取得しない場合は、このパラメータを NULL に設定する。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

排除するには、2 つのパラメータのいずれかを NULL に設定するだけである。両方のパラメータに NULL を設定すると、メソッドは失敗し、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::GetDeviceIdentifier

IDirectDraw7::GetDeviceIdentifier メソッドは、ドライバについての情報を取得する。このメソッドは、低品質なデバイスやチップセットの動作の回避方法を実装する特定のハードウェア インストールを認識するために使用できるが、使用の際には注意が必要である。

HRESULT GetDeviceIdentifier(
  LPDDDEVICEIDENTIFIER2 lpdddi,
  DWORD dwFlags
);

パラメータ

lpdddi
ドライバ情報を受け取る DDDEVICEIDENTIFIER2 構造体のアドレス。
dwFlags
オプションを指定するフラグ。次のフラグが定義されている。
DDGDI_GETHOSTIDENTIFIER
スタックされた第 2 の 3-D アダプタと共に装備される、システムのホスト (通常は 2-D) アダプタについての情報を返すためにメソッドを引き起こす。このようなアダプタは、アプリケーションにはホスト アダプタの一部であるかのように現れるが、普通は別のカードに配置されている。dwFlags パラメータが 0 の場合、DirectDraw オブジェクトの品質を最も正確に反映するという理由から、スタックされている第 2 アダプタの情報が返される。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、DDERR INVALIDPARAMS を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::GetDisplayMode

IDirectDraw7::GetDisplayMode メソッドは、現在のディスプレイ モードを取得する。

HRESULT GetDisplayMode(
  LPDDSURFACEDESC2 lpDDSurfaceDesc2
);

パラメータ

lpDDSurfaceDesc2
サーフェスの記述を格納する DDSURFACEDESC2 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTEDMODE

注意

アプリケーションがこのメソッドで返された情報をあらかじめ保存して、クリーンアップの際のディスプレイ モードのリストアとして利用することは望ましくない。アプリケーションでは、IDirectDraw7::RestoreDisplayMode メソッドを使用して、クリーンアップの際にモードをリストアする必要がある。これにより、マルチプロセス環境で発生することがある競合を回避できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::SetDisplayMode、IDirectDraw7::RestoreDisplayMode、IDirectDraw7::EnumDisplayModes


IDirectDraw7::GetFourCCCodes

IDirectDraw7::GetFourCCCodes メソッドは、DirectDraw オブジェクトがサポートする FOURCC コードを取得する。また、このメソッドは、サポートされるコード数も取得する。

HRESULT GetFourCCCodes(
  LPDWORD lpNumCodes,
  LPDWORD lpCodes
);

パラメータ

lpNumCodes
lpCodes により示される配列が保持できるエントリ数を含む変数のアドレス。エントリ数が少なすぎてすべてのコードを適応できない場合、lpNumCodes には必要な数が設定され、lpCodes により示される配列には適合するすべてのコードが格納される。
lpCodes
DirectDraw オブジェクトがサポートする FOURCC コードを格納する変数の配列のアドレス。NULL を指定した場合、lpNumCodes はサポートされる FOURCC コードの数に設定され、メソッドが返る。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::GetGDISurface

IDirectDraw7::GetGDISurface メソッドは、GDI がプライマリ サーフェスとして処理するサーフェス メモリを現在示す DirectDrawSurface オブジェクトを取得する。

HRESULT GetGDISurface(
  LPDIRECTDRAWSURFACE7 FAR *lplpGDIDDSSurface
);

パラメータ

lplpGDIDDSSurface
GDI のプライマリ サーフェス メモリを現在制御している、サーフェスの IDirectDrawSurface7 インターフェイスへのポインタを格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::FlipToGDISurface


IDirectDraw7::GetMonitorFrequency

IDirectDraw7::GetMonitorFrequency メソッドは、DirectDraw オブジェクトが動作するモニタの周波数を取得する。

HRESULT GetMonitorFrequency(
  LPDWORD lpdwFrequency
);

パラメータ

lpdwFrequency
ヘルツ単位でモニタ周波数を格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::GetScanLine

IDirectDraw7::GetScanLine メソッドは、モニタ上で現在描画されている走査線を取得する。

HRESULT GetScanLine(
  LPDWORD lpdwScanLine
);

パラメータ

lpdwScanLine
ディスプレイが現在描画している走査線を含む変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS

注意

走査線はゼロベースの整数として報告される。返される走査線の値は 0 から n までの値である。走査線 0 はスクリーン上の最初の可視走査線、走査線 n は最後の可視走査線である。また、垂直帰線消去間隔に生じる任意の走査線もある。したがって、アプリケーションが 640 × 480 で実行され、垂直帰線消去間隔に 12 の走査線がある場合、このメソッドは 0 から 491 の範囲の値を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::GetVerticalBlankStatus、IDirectDraw7::WaitForVerticalBlank


IDirectDraw7::GetSurfaceFromDC

IDirectDraw7::GetSurfaceFromDC メソッドは、サーフェスの GDI デバイス コンテキスト ハンドルに基づいて、そのサーフェスの IDirectDrawSurface7 インターフェイスを取得する。

HRESULT GetSurfaceFromDC(
  HDC hdc,
  LPDIRECTDRAWSURFACE7 * lpDDS
);

パラメータ

hdc
ディスプレイ デバイス コンテキストのハンドル。
lpDDS
呼び出しが成功した場合に、有効な IDirectDrawSurface7 インターフェイス ポインタを格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_NOTFOUND

注意

このメソッドは、DirectDraw オブジェクトに既に関連付けられているサーフェスを識別する、デバイス コンテキスト ハンドルに対してのみ成功する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

サーフェス コンテキストとデバイス コンテキスト


IDirectDraw7::GetVerticalBlankStatus

IDirectDraw7::GetVerticalBlankStatus メソッドは、垂直帰線消去のステータスを取得する。

HRESULT GetVerticalBlankStatus(
  LPBOOL lpbIsInVB
);

パラメータ

lpbIsInVB
垂直帰線消去のステータスを格納する変数のアドレス。垂直帰線消去が発生する場合にこのパラメータは TRUE となり、そうでない場合は FALSE となる。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

垂直帰線消去と同期するには、IDirectDraw7::WaitForVerticalBlank メソッドを使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::GetScanLine、IDirectDraw7::WaitForVerticalBlank


IDirectDraw7::Initialize

IDirectDraw7::Initialize メソッドは、CoCreateInstance COM 関数を使って作成された DirectDraw オブジェクトを初期化する。

HRESULT Initialize(
  GUID FAR *lpGUID
);

パラメータ

lpGUID
インターフェイス識別子として使われるグローバル ユニーク識別子 (GUID) のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_ALREADYINITIALIZED
DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_NODIRECTDRAWSUPPORT
DDERR_OUTOFMEMORY

このメソッドは、コンポーネント オブジェクト モデル (COM) プロトコル準拠で提供される。DirectDraw オブジェクトを作成するために DirectDrawCreate 関数を使用した場合、このメソッドは DDERR_ALREADYINITIALIZED を返す。DirectDraw オブジェクトを作成するために CoCreateInstance を使用するときに IDirectDraw7::Initialize を呼び出していない場合、後で呼び出されるメソッドは DDERR_NOTINITIALIZED を返す。

注意

CoCreateInstance と共に IDirectDraw7::Initialize を使用することについての詳細情報は、「CoCreateInstance を用いた DirectDraw オブジェクトの作成」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::RestoreAllSurfaces

IDirectDraw7::RestoreAllSurfaces メソッドは、DirectDraw オブジェクトに対して作成されたすべてのサーフェスを、その作成順にリストアする。

HRESULT RestoreAllSurfaces();

パラメータ

なし。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは便利である。このメソッドは、この DirectDraw オブジェクトによって作成されたサーフェスごとに効率良く IDirectDrawSurface7::Restore を呼び出す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::Restore、サーフェスの消失とリストア


IDirectDraw7::RestoreDisplayMode

IDirectDraw7::RestoreDisplayMode メソッドは、プライマリ サーフェスのディスプレイ デバイス ハードウェアのモードを、IDirectDraw7::SetDisplayMode メソッドが呼び出される前の状態にリセットする。このメソッドを使うには、排他レベルのアクセスが必要とされる。

HRESULT RestoreDisplayMode();

パラメータ

なし。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::SetDisplayMode、IDirectDraw7::EnumDisplayModes、IDirectDraw7::SetCooperativeLevel


IDirectDraw7::SetCooperativeLevel

IDirectDraw7::SetCooperativeLevel メソッドは、アプリケーションの最上位動作を決定する。

HRESULT SetCooperativeLevel(
  HWND hWnd,
  DWORD dwFlags
);

パラメータ

hWnd
アプリケーションが使用するウィンドウ ハンドル。呼び出すアプリケーションの最上位ウィンドウ ハンドルに設定する (最上位ウィンドウが作成した子ウィンドウに対するハンドルではない)。dwFlags パラメータに DDSCL_NORMAL フラグを指定する場合、このパラメータは NULL となる。
dwFlags
以下のフラグのうち、1 つ以上の値を取る。
DDSCL_ALLOWMODEX
モード X ディスプレイ モードの利用を許可する。DDSCL_EXCLUSIVE と DDSCL_FULLSCREEN フラグが存在する場合だけ、このフラグを使用できる。
DDSCL_ALLOWREBOOT
排他 (フルスクリーン) モード時に、CTRL + ALT + DEL の機能を許可する。
DDSCL_CREATEDEVICEWINDOW
このフラグは、Microsoft® Windows 98 および Windows 2000 でのみサポートされる。DirectDraw が、この DirectDraw オブジェクトのデフォルトの デバイス ウィンドウ を作成および管理することを示す。詳細については、「フォーカス ウィンドウとデバイス ウィンドウ」を参照すること。
DDSCL_EXCLUSIVE
排他レベルを要求する。このフラグは、DDSCL_FULLSCREEN フラグと共に使用しなければならない。
DDSCL_FPUPRESERVE
呼び出し側アプリケーションで FPU の状態を監視し、アプリケーションでの管理のもと Direct3D による FPU の状態を変更しない。このモードでは、Direct3D は、FPU の状態を変更する必要があるたびに FPU の状態を保存および復元する。詳細については、「DirectDraw 協調レベルと FPU 精度」を参照すること。
DDSCL_FPUSETUP
呼び出し側アプリケーションでは、FPU を Direct3D パフォーマンスに最適な状態 (単精度および例外無効) に設定するので、Direct3D で FPU を明示的に毎回設定する必要はない。これはデフォルトの状態である。詳細については、「DirectDraw 協調レベルと FPU 精度」を参照すること。
DDSCL_FULLSCREEN
排他モードを所有する側にプライマリ サーフェス全体に対する責任がある。GDI は無視できる。このフラグは、DDSCL_EXCLUSIVE フラグと共に使用しなければならない。
DDSCL_MULTITHREADED
マルチスレッドの確実な DirectDraw 動作を要求する。これにより、Direct3D が頻繁にグローバル危険域を取得するようになる。
DDSCL_NORMAL
アプリケーションは通常の Microsoft® Windows® アプリケーションとして機能する。このフラグは、DDSCL_ALLOWMODEX、DDSCL_EXCLUSIVE、または DDSCL_FULLSCREEN フラグと共に使用することはできない。
DDSCL_NOWINDOWCHANGES
DirectDraw は、アクティブ時にアプリケーション ウィンドウを最小化または元のサイズに戻すことができない。
DDSCL_SETDEVICEWINDOW
このフラグは、Windows 98 および Windows 2000 でのみサポートされる。hWnd パラメータが、この DirectDraw オブジェクトにおけるデバイス ウィンドウのウィンドウ ハンドルであることを示す。このフラグは、DDSCL_SETFOCUSWINDOW フラグと共に使用することはできない。
DDSCL_SETFOCUSWINDOW
このフラグは、Windows 98 および Windows 2000 でのみサポートされる。hWnd パラメータが、この DirectDraw オブジェクトにおけるフォーカス ウィンドウのウィンドウ ハンドルであることを示す。このフラグは、DDSCL_SETDEVICEWINDOW フラグと共に使用することはできない。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_EXCLUSIVEMODEALREADYSET
DDERR_HWNDALREADYSET
DDERR_HWNDSUBCLASSED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

このメソッドは、アプリケーション ウィンドウを作成した同じスレッドで呼び出されなくてはならない。

アプリケーションでは、DDSCL_EXCLUSIVE または DDSCL_NORMAL フラグのいずれかを設定する必要がある。

他のアプリケーションに対して、大幅なパフォーマンス変化を引き起こす可能性のある関数を呼び出すには、DDSCL_EXCLUSIVE フラグを設定しなくてはならない。詳細については、「協調レベル」を参照すること。

このメソッドおよび IDirectDraw7::SetDisplayMode メソッド間の相互作用は、IDirectDraw でのものとは異なる。詳細については、「ディスプレイ モードのリストア」を参照すること。

Microsoft Foundation Classes (MFC) を使用する場合、このメソッドに渡されるウィンドウ ハンドルは、派生した子ウィンドウではなくアプリケーションの最上位ウィンドウを識別するものでなければならない。MFC アプリケーションの最上位ウィンドウ ハンドルを取得するには、次に示すコードを使用する。

    HWND hwndTop = AfxGetMainWnd()->GetSafeHwnd();

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::SetDisplayMode、IDirectDraw7::Compact、IDirectDraw7::EnumDisplayModes、モード X モードとモード 13 ディスプレイ モード、フォーカス ウィンドウとデバイス ウィンドウ


IDirectDraw7::SetDisplayMode

IDirectDraw7::SetDisplayMode メソッドは、ディスプレイデバイス ハードウェアのモードを設定する。

HRESULT SetDisplayMode(
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwBPP,
  DWORD dwRefreshRate,
  DWORD dwFlags
);

パラメータ

dwWidth、dwHeight
新しいモードの幅と高さ。
dwBPP
新しいモードのビット/ピクセル (bpp)。
dwRefreshRate
新しいモードのリフレッシュ レート。この値を 0 に設定すると、ドライバに対するデフォルト リフレッシュ レートを要求する。
dwFlags
追加オプションを記述するフラグ。現時点で唯一の有効なフラグは DDSDM_STANDARDVGAMODE であり、メソッドでモード X の 320 × 200 × 8 モードではなく、モード 13 を設定できる。別の解像度、ビット深度、またはモード X モードに設定する場合は、このフラグを使用せずにパラメータを 0 に設定する。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

注意

このメソッドは、アプリケーション ウィンドウを作成した同じスレッドで呼び出されなくてはならない。

別のアプリケーションでディスプレイ モードを変更すると、プライマリ サーフェスが消失、メソッドは新しいディスプレイ モードに適合するプライマリ サーフェスが作成し直されるまで DDERR_SURFACELOST を返す。

IDirectDraw インターフェイスの一部として、このメソッドは dwRefreshRate および dwFlags パラメータを含んでいなかった。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::RestoreDisplayMode、IDirectDraw7::GetDisplayMode、IDirectDraw7::EnumDisplayModes、IDirectDraw7::SetCooperativeLevel、ディスプレイ モードの設定、ディスプレイ モードのリストア


IDirectDraw7::StartModeTest

IDirectDraw7::StartModeTest メソッドは、テストを開始して、現在のディスプレイ アダプタおよびモニタの組み合わせについてのリフレッシュ レート情報でシステム レジストリを更新する。通常、このメソッドを呼び出した後、IDirectDraw7::EvaluateMode を呼び出して、テストで表示されたモードのクリアまたは失敗を決定する。

HRESULT StartModeTest(
  LPSIZE   lpModesToTest,
  DWORD    dwNumEntries,
  DWORD    dwFlags
);

パラメータ

lpModesToTest
テストするモードをスクリーン解像度の点から記述する SIZE 要素の配列へのポインタ。
dwNumEntries
lpModesToTest. がポイントする配列の要素数。
dwFlags
現時点で有効なフラグの値は、DDSMT_ISTESTREQUIRED のみである。このフラグを指定した場合、IDirectDraw7::StartModeTest はテストを開始しない。その代わり、lpModesToTest および dwNumEntries によって識別される解像度のテストが可能かどうか、またはテストが必要かどうかを示す値を返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CURRENTLYNOTAVAIL
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOTFOUND
DDERR_TESTFINISHED

DDSMT_ISTESTREQUIRED フラグでメソッドを呼び出した場合、以下の値のいずれかを返す。

DDERR_NEWMODE
DDERR_NODRIVERSUPPORT
DDERR_NOMONITORINFORMATION
DDERR_TESTFINISHED

注意

IDirectDraw7::StartModeTest メソッドを IDirectDraw7::EvaluateMode と併用すれば、EDID モニタおよびディスプレイ アダプタの組み合わせによって各スクリーン解像度でサポートできる最大リフレッシュ レートを決定できる。テストの結果は、システム レジストリに格納され、IDirectDraw7::EnumDisplayMode を DDEDM_REFRESHRATES フラグ セットで呼び出したときの処理に影響する。

特に IDirectDraw7::StartModeTest は、テスト可能な解像度のセットを作成して、そのセット内の最初の解像度に基づいてモードを表示するよう DirectDraw に命令する。この呼び出しに続く IDirectDraw7::EvaluateMode の呼び出しでは、各モードのテストのクリアまたは失敗を決定して、次のディスプレイ モードのテストに進む。

このメソッドは、EDID データを含むモニタに対してのみ成功する。モニタが EDID 準拠でない場合、メソッドはモードのテストを行わず DDERR_TESTFINISHED を返す。EDID テーブルに 60 Hz より高い値がない場合、モードのテストは行われない。100 Hz より高いリフレッシュ レートのテストが行われるのは、EDID テーブルに 85 Hz より高い値がある場合のみである。

(NULL, 0, 0) の引数リストでメソッドを呼び出すと、既存のリフレッシュ レート情報がレジストリから消去される。

テストは、lpModesToTest および dwNumEntries パラメータで記述される配列の解像度における表示のみを保証するものではない。たとえば、640 × 480 解像度を使用して、320 × 200 解像度での最大表示リフレッシュ レートを取得できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::EvaluateMode、リフレッシュ レートの列挙


IDirectDraw7::TestCooperativeLevel

IDirectDraw7::TestCooperativeLevel メソッドは、ウィンドウまたはフルスクリーン アプリケーションに対する DirectDraw デバイスの現在の協調レベル ステータスを報告する。

HRESULT TestCooperativeLevel(void);

パラメータ

なし。

戻り値

成功すれば、DD_OK を返す。この戻り値は、呼び出し側アプリケーションが続行できることを示す。

失敗すれば、以下のエラー値のいずれかを返す。(「注意」参照)。

DDERR_INVALIDOBJECT
DDERR_EXCLUSIVEMODEALREADYSET
DDERR_NOEXCLUSIVEMODE
DDERR_WRONGMODE

注意

このメソッドは、サーフェスのリストアや DirectDraw オブジェクトの再作成を行う通知として WM_ACTIVATEAPP および WM_DISPLAYCHANGE システム メッセージを使用するアプリケーションでは特に便利である。DD_OK 戻り値は、常にアプリケーションが続行できることを示すが、エラー コードの解釈はアプリケーションで使用する協調レベルによって異なる。詳細については、「協調レベルのテスト」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDraw7::WaitForVerticalBlank

IDirectDraw7::WaitForVerticalBlan メソッドは、アプリケーションが垂直帰線消去間隔と共に同期する方法を提供する。

HRESULT WaitForVerticalBlank(
  DWORD dwFlags,
  HANDLE hEvent
);

パラメータ

dwFlags
垂直帰線消去に対しての待機時間を決定する。以下のフラグのうち、1 つの値を取る。
DDWAITVB_BLOCKBEGIN
垂直帰線消去間隔が発生したときに返す。
DDWAITVB_BLOCKBEGINEVENT
垂直帰線消去が発生するときのイベント トリガ。この値は、現時点ではサポートされていない。
DDWAITVB_BLOCKEND
垂直帰線消去間隔が終了して表示するときに返す。
hEvent
垂直帰線消去が発生したときにトリガとなるイベントのハンドル。このパラメータは、現時点では使用できない。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDraw7::GetVerticalBlankStatus、IDirectDraw7::GetScanLine


IDirectDrawClipper

アプリケーションでは、IDirectDrawClipper インターフェイスのメソッドを使用してクリップ リストを管理する。ここでは、このインターフェイスのメソッドのリファレンスを提供する。概念の概要については、「クリッパー」を参照すること。

IDirectDrawClipper インターフェイスのメソッドは、以下のグループにまとめることができる。

メモリの割り当て | Initialize
クリップ リスト | GetClipList
 | IsClipListChanged
 | SetClipList
 | SetHWnd
ハンドル | GetHWnd

すべての COM インターフェイスと同様、IDirectDrawClipper インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWCLIPPER データ型を使用すると、IDirectDrawClipper インターフェイスへのポインタを含む変数を宣言できる。ddraw.h ヘッダー ファイルは、以下のコードでこれらのデータ型を宣言する。

typedef struct IDirectDrawClipper    FAR *LPDIRECTDRAWCLIPPER;

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawClipper::GetClipList

IDirectDrawClipper::GetClipList メソッドは、DirectDrawClipper オブジェクトに関連付けられたクリップ リストのコピーを取得する。クリップ リストをクリップする矩形を渡すことで、クリップ リストのサブセットを選択できる。

HRESULT GetClipList(
  LPRECT lpRect,
  LPRGNDATA lpClipList,
  LPDWORD lpdwSize
);

パラメータ

lpRect
クリップ リストをクリップするために使用する矩形のアドレス。このパラメータを NULL に設定すると、クリップ リスト全体を取得できる。
lpClipList
クリップ リストのコピー結果を受け取る RGNDATA 構造体のアドレス。このパラメータを NULL に設定すると、メソッドはクリップ リスト全体を保持するために必要となるバイト数を lpdwSize で示す変数に格納する。
lpdwSize
クリップ リストのサイズを受け取る変数のアドレス。クリップ リストを取得する場合、このパラメータは lpClipList の示すバッファのサイズとなる。LpClipList が NULL の場合、lpdwSize で示す変数は必要となるバッファのサイズをバイト単位で取得する。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST
DDERR_REGIONTOOSMALL

注意

このメソッドで使用される 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;

これらの構造体の詳細については、プラットフォーム SDK を参照すること。

動作環境

Windows NT/2000 : Windows NT Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawClipper::SetClipList


IDirectDrawClipper::GetHWnd

IDirectDrawClipper::GetHWnd メソッドは、IDirectDrawClipper::SetHWnd メソッドによってこの DirectDrawClipper オブジェクトに以前関連付けられたウィンドウ ハンドルを取得する。

HRESULT GetHWnd(
  HWND FAR *lphWnd
);

パラメータ

lphWnd
IDirectDrawClipper::SetHWnd メソッドにより、この DirectDrawClipper オブジェクトに以前関連付けられたウィンドウ ハンドルのアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ :ddraw.lib を使用。

参照

IDirectDrawClipper::SetHWnd


IDirectDrawClipper::Initialize

IDirectDrawClipper::Initialize メソッドは、CoCreateInstance COM 関数を使用して作成した DirectDrawClipper オブジェクトを初期化する。

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  DWORD dwFlags
);

パラメータ

lpDD
DirectDraw オブジェクトを表す DirectDraw 構造体のアドレス。パラメータを NULL に設定すると、独立した DirectDrawClipper オブジェクトが作成される (DirectDrawCreateClipper 関数を使用する場合と同様)。
dwFlags
現時点では未使用なので 0 を設定しておく。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_ALREADYINITIALIZED
DDERR_INVALIDPARAMS

このメソッドは、コンポーネント オブジェクト モデル (COM) プロトコル準拠で提供される。DirectDrawCreateClipper または IDirectDraw7::CreateClipper メソッドを DirectDrawClipper オブジェクトの作成に使用した場合、このメソッドは DDERR_ALREADYINITIALIZED を返す。

注意

CoCreateInstance と共に IDirectDrawClipper::Initialize を使用する詳細については、「CoCreateInstance を用いた DirectDrawClipper オブジェクトの作成」を参照すること。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IUnknown::AddRef、IUnknown::QueryInterface、IUnknown::Release、IDirectDraw7::CreateClipper


IDirectDrawClipper::IsClipListChanged

IDirectDrawClipper::IsClipListChanged メソッドは、ウィンドウ ハンドルが DirectDrawClipper オブジェクトに関連付けられている場合、クリップ リストのステータスをモニタする。

HRESULT IsClipListChanged(
  BOOL FAR *lpbChanged
);

パラメータ

lpbChanged
クリップ リストが変更された場合、TRUE に設定する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawClipper::SetClipList

IDirectDrawClipper::SetClipList メソッドは、DirectDrawClipper の親オブジェクトをアタッチするサーフェスの IDirectDrawSurface7::Blt、IDirectDrawSurface7::BltBatch、および IDirectDrawSurface7::UpdateOverlay メソッドで使用するクリップ リストを設定または削除する。

HRESULT SetClipList(
  LPRGNDATA lpClipList,
  DWORD dwFlags
);

パラメータ

lpClipList
有効な RGNDATA 構造体のアドレス、または NULL。DirectDrawClipper オブジェクトに関連付けられたクリップ リストが存在し、このパラメータの値が NULL の場合、クリップ リストを削除する。
dwFlags
現時点では未使用なので 0 を設定しておく。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CLIPPERISUSINGHWND
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

ウィンドウ ハンドルが既に DirectDrawClipper オブジェクトに関連付けられている場合、クリップ リストは設定されない。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;

これらの構造体の詳細については、プラットフォーム SDK を参照すること。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawClipper::GetClipList、IDirectDrawSurface7::Blt、IDirectDrawSurface7::BltFast、IDirectDrawSurface7::BltBatch、IDirectDrawSurface7::UpdateOverlay


IDirectDrawClipper::SetHWnd

IDirectDrawClipper::SetHWnd メソッドは、クリッピング情報を取得するために使用するクリッパー オブジェクトのウィンドウ ハンドルを設定する。

HRESULT SetHWnd(
  DWORD dwFlags,
  HWND hWnd
);

パラメータ

dwFlags
現時点では未使用なので 0 を設定しておく。
hWnd
クリッピング情報を取得するウィンドウ ハンドル。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawClipper::GetHWnd


IDirectDrawColorControl

IDirectDrawColorControl インターフェイスのメソッドは、以下のグループにまとめることができる。以下のメソッドがある。

カラー コントロール | GetColorControls
 | SetColorControls

すべての COM インターフェイスと同様、IDirectDrawColorControl インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWCOLORCONTROL データ型を使用すると、IDirectDrawColorControl インターフェイスへのポインタを含む変数を宣言できる。ddraw.h ヘッダー ファイルは、以下のコードでこれらのデータ型を宣言する。

typedef struct IDirectDrawColorControl    FAR *LPDIRECTDRAWCOLORCONTROL;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawColorControl::GetColorControls

IDirectDrawColorControl::GetColorControls メソッドは、指定したオーバーレイやプライマリ サーフェスに関連付けられた現在のカラー コントロール設定を返す。DDCOLORCONTROL 構造体の dwFlags メンバは、サポートされるカラーコントロール オプションを示す。

HRESULT GetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

パラメータ

lpColorControl
指定されたサーフェスの現在のコントロール設定を受け取る DDCOLORCONTROL 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawColorControl::SetColorControls、カラー コントロールの使用、ガンマ コントロールとカラー コントロール


IDirectDrawColorControl::SetColorControls

IDirectDrawColorControl::SetColorControls メソッドは、指定したオーバーレイまたはプライマリ サーフェスに関連付けられたカラーコントロールを設定する。

HRESULT SetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

パラメータ

lpColorControl
指定したサーフェスに適用する新しい値を含む DDCOLORCONTROL 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawColorControl::GetColorControls、カラー コントロールの使用、ガンマ コントロールとカラー コントロール


IDirectDrawGammaControl

アプリケーションは IDirectDrawGammaControl インターフェイスのメソッドを使用して、プライマリ サーフェスの赤、緑、および青ガンマ ランプ レベルを調整する。ここでは、このインターフェイスのメソッドのリファレンスを提供する。このインターフェイスは、DirectDrawSurface オブジェクトによってサポートされる。つまり、IID_IDirectDrawGammaControl 参照識別子を指定して DirectDrawSurface オブジェクトの IUnknown::QueryInterface メソッドを呼び出すことで、このインターフェイスへのポインタを取得できる。

概念の概要については、「ガンマ コントロールとカラー コントロール」を参照すること。

インターフェイスには以下のメソッドがある。

ガンマ ランプ | GetGammaRamp
 | SetGammaRamp

すべての COM インターフェイスと同様、IDirectDrawGammaControl インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWGAMMACONTROL データ型を使用すると、IDirectDrawGammaControl インターフェイスへのポインタを含む変数を宣言できる。ddraw.h ヘッダー ファイルは、以下のコードでこれらのデータ型を宣言する。

typedef struct IDirectDrawGammaControl    FAR *LPDIRECTDRAWGAMMACONTROL;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawGammaControl::GetGammaRamp

IDirectDrawGammaControl::GetGammaRamp メソッドは、プライマリ サーフェスに対する赤、緑、および青ガンマ ランプを取得する。

HRESULT GetGammaRamp(
  DWORD  dwFlags,
  LPGAMMARAMP lpRampData
);

パラメータ

dwFlags
現時点では未使用なので 0 を設定しておく。
lpRampData
現在の赤、緑、および青ガンマ ランプを格納する DDGAMMARAMP 構造体のアドレス。個々の配列は、フレーム バッファの色の値をデジタルアナログ コンバータ (DAC) に渡す色の値にマップする。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawGammaControl::SetGammaRamp、ガンマ コントロールとカラー コントロール


IDirectDrawGammaControl::SetGammaRamp

IDirectDrawGammaControl::SetGammaRamp メソッドは、プライマリ サーフェスに対する赤、緑、および青ガンマ ランプを取得する。

HRESULT SetGammaRamp(
  DWORD  dwFlags,
  LPGAMMARAMP lpRampData
);

パラメータ

dwFlags
ガンマ キャリブレーションを要求するかどうかを示すフラグ。このパラメータを DDSGR_CALIBRATE に設定すると、口径測定器がすべてのシステム上で同一になるように、ディスプレイの物理的性質に従って、ガンマ ランプの調整を要求できる。キャリブレーションを必要としない場合は、このパラメータを 0 に設定する。
lpRampData
新しい赤、緑、および青ガンマ ランプ エントリを含む DDGAMMARAMP 構造体のアドレス。個々の配列は、フレーム バッファの色の値をデジタルアナログ コンバータ (DAC) に渡す色の値にマップする。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

すべてのシステムでガンマ キャリブレーションをサポートするわけではない。ガンマ キャリブレーションをサポートするかどうかを決めるには、IDirectDraw7::GetCaps を呼び出し、メソッドが返した後に関連する DDCAPS 構造体の dwCaps2 メンバを調べる。DDCAPS2_CANCALIBRATEGAMMA 能力フラグが存在すると、ガンマ キャリブレーションはサポートされる。

ガンマ ランプのキャリブレーションでは、いくつかの処理にオーバーヘッドが起こるので、頻繁に使用できない。

ガンマ キャリブレーションをサポートしないシステムで実行する場合は、dwFlags パラメータに DDSGR_CALIBRATE フラグを設定すれば、このメソッドは失敗しない。キャリブレーションせずに新しいガンマ ランプ値を設定すると、メソッドは成功する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawGammaControl::GetGammaRamp、ガンマ コントロールとカラー コントロール


IDirectDrawPalette

アプリケーションは IDirectDrawPalette インターフェイスのメソッドを使って、DirectDrawPalette オブジェクトを作成し、システムレベル変数と共に作用する。ここでは、このインターフェイスのメソッドのリファレンスを提供する。概念の概要については、「パレット」を参照すること。

IDirectDrawPalette インターフェイスのメソッドは、以下のグループにまとめることができる。

メモリの割り当て | Initialize
パレット能力 | GetCaps
パレット エントリ | GetEntries
 | SetEntries

すべての COM インターフェイスと同様、IDirectDrawPalette インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWPALETTE データ型を使用すると、IDirectDrawPalette インターフェイスへのポインタを含む変数を宣言できる。ddraw.h ヘッダー ファイルは、以下のコードでこれらのデータ型を宣言する。

typedef struct IDirectDrawPalette    FAR *LPDIRECTDRAWPALETTE;

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawPalette::GetCaps

IDirectDrawPalette::GetCaps メソッドは、このパレット オブジェクトの能力を取得する。

HRESULT GetCaps(
  LPDWORD lpdwCaps
);

パラメータ

lpdwCaps
パレット能力を定義する DDCAPS 構造体の dwPalCaps メンバからのフラグ。
DDPCAPS_1BIT
DDPCAPS_2BIT
DDPCAPS_4BIT
DDPCAPS_8BIT
DDPCAPS_8BITENTRIES
DDPCAPS_ALPHA
DDPCAPS_ALLOW256
DDPCAPS_PRIMARYSURFACE
DDPCAPS_PRIMARYSURFACELEFT
DDPCAPS_VSYNC

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawPalette::GetEntries

IDirectDrawPalette::GetEntries メソッドは、DirectDrawPalette オブジェクトからのパレット値を照会する。

HRESULT GetEntries(
  DWORD dwFlags,
  DWORD dwBase,
  DWORD dwNumEntries,
  LPPALETTEENTRY lpEntries
);

パラメータ

dwFlags
現時点では未使用なので 0 を設定しておく。
dwBase
順に取得するエントリの先頭。
dwNumEntries
lpEntries に指定するアドレスに適合するパレット エントリの数。個々のパレット エントリの色は、dwStartingEntry パラメータの値から dwCount パラメータの値をマイナス 1 した値まで、順番に返される。(これらの値は、IDirectDrawPalette::SetEntries で設定される)。
lpEntries
パレット エントリのアドレス。DDPCAPS_8BITENTRIES フラグを設定する場合、パレット エントリは 1 バイトごととなる。それ以外の場合は、4 バイトごととなる。個々のフィールドは、色記述となる。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPALETTIZED

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawPalette::SetEntries


IDirectDrawPalette::Initialize

IDirectDrawPalette::Initialize メソッドは、DirectDrawPalette オブジェクトを初期化する。

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  DWORD dwFlags,
  LPPALETTEENTRY lpDDColorTable
);

パラメータ

lpDD
DirectDraw オブジェクトを表す DirectDraw 構造体のアドレス。
dwFlags、lpDDColorTable
現時点では未使用なので 0 を設定しておく。

戻り値

このメソッドは、DDERR_ALREADYINITIALIZED を返す。

このメソッドは、コンポーネント オブジェクト モデル (COM) プロトコル準拠で提供される。DirectDrawPalette オブジェクトは作成時に初期化されるので、このメソッドは常に DDERR_ALREADYINITIALIZED を返す。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IUnknown::AddRef、IUnknown::QueryInterface、IUnknown::Release


IDirectDrawPalette::SetEntries

IDirectDrawPalette::SetEntries メソッドは、DirectDrawPalette オブジェクトのエントリを即座に変更する。

HRESULT SetEntries(
  DWORD dwFlags,
  DWORD dwStartingEntry,
  DWORD dwCount,
  LPPALETTEENTRY lpEntries
);

パラメータ

dwFlags
現時点では未使用なので 0 を設定しておく。
dwStartingEntry
設定される最初のエントリ。
dwCount
変更されるパレット エントリの数。
lpEntries
パレット エントリのアドレス。DDPCAPS_8BITENTRIES フラグを設定する場合、パレット エントリは 1 バイトごととなる。それ以外の場合は、4 バイトごととなる。個々のフィールドは、色記述となる。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOPALETTEATTACHED
DDERR_NOTPALETTIZED
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawPalette::GetEntries、IDirectDrawSurface7::SetPalette


IDirectDrawSurface7

アプリケーションは IDirectDrawSurface7 インターフェイスのメソッドを使って、DirectDrawSurface オブジェクトを作成し、システムレベル変数と共に作用する。ここでは、このインターフェイスのメソッドのリファレンスを提供する。概念の概要については、「サーフェス」を参照すること。

IDirectDrawSurface7 インターフェイスのメソッドは、以下のグループにまとめることができる。

メモリの割り当て | Initialize
 | IsLost
 | Restore
サーフェスのアタッチ | AddAttachedSurface
 | DeleteAttachedSurface
 | EnumAttachedSurfaces
 | GetAttachedSurface
ブリット | Blt
 | BltBatch
 | BltFast
 | GetBltStatus
カラー キーイング | GetColorKey
 | SetColorKey
デバイス コンテキスト | GetDC
 | ReleaseDC
フリッピング | Flip
 | GetFlipStatus
サーフェスのロック | Lock
 | PageLock
 | PageUnlock
 | Unlock
その他 | GetDDInterface
オーバーレイ | AddOverlayDirtyRect
 | EnumOverlayZOrders
 | GetOverlayPosition
 | SetOverlayPosition
 | UpdateOverlay
 | UpdateOverlayDisplay
 | UpdateOverlayZOrder
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
サーフェス能力 | GetCaps
サーフェス クリッパー | GetClipper
 | SetClipper
サーフェス特性 | ChangeUniquenessValue
 | GetPixelFormat
 | GetSurfaceDesc
 | GetUniquenessValue
 | SetSurfaceDesc
サーフェス パレット | GetPalette
 | SetPalette
テクスチャ | GetLOD
 | GetPriority
 | SetLOD
 | SetPriority

すべての COM インターフェイスと同様、IDirectDrawSurface7 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectDrawSurface7 インターフェイスは、よりよいサーフェス管理と使いやすさを備えたメソッドを提供することにより、以前のバージョンのインターフェイス機能を拡張した。このインターフェイスの多くのメソッドは、以前のバージョンのインターフェイスで対応するメソッドとは若干異なるパラメータを受け取る。IDirectDrawSurface3 インターフェイス メソッドが DDSURFACEDESC 構造体や IDirectDrawSurface3 インターフェイスを受け取る場所は常に、代わりに IDirectDrawSurface7 のメソッドが DDSURFACEDESC2 構造体や IDirectDrawSurface7 インターフェイスを受け取る。

LPDIRECTDRAWSURFACE、LPDIRECTDRAWSURFACE2、LPDIRECTDRAWSURFACE3、LPDIRECTDRAWSURFACE4、LPDIRECTDRAWSURFACE7 データ型を使用すると、さまざまな DirectDrawSurface オブジェクト インターフェイスを指す変数を宣言できる。ddraw.h ヘッダー ファイルは、以下のコードでこれらのデータ型を宣言する。

typedef struct IDirectDrawSurface     FAR *LPDIRECTDRAWSURFACE;
typedef struct IDirectDrawSurface2    FAR *LPDIRECTDRAWSURFACE2;
typedef struct IDirectDrawSurface3    FAR *LPDIRECTDRAWSURFACE3;
typedef struct IDirectDrawSurface4    FAR *LPDIRECTDRAWSURFACE4;
typedef struct IDirectDrawSurface7    FAR *LPDIRECTDRAWSURFACE7;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::AddAttachedSurface

IDirectDrawSurface7::AddAttachedSurface メソッドは、指定した Z バッファのサーフェスをこのサーフェスにアタッチする。

HRESULT AddAttachedSurface(
  LPDIRECTDRAWSURFACE7 lpDDSAttachedSurface
);

パラメータ

lpDDSAttachedSurface
サーフェスをアタッチする IDirectDrawSurface7 インターフェイスのアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

注意

このメソッドは、アタッチされるサーフェスの参照カウントをインクリメントする。明示的にサーフェスのアタッチを解除して、参照カウントをデクリメントするには、IDirectDrawSurface7::DeleteAttachedSurface メソッドを使用する。IDirectDraw7::CreateSurface の単一の呼び出しで作成する複合サーフェス とは異なり、このメソッドでアタッチするサーフェスは自動的に解放されない。このようなサーフェスの解放は、アプリケーションの責任となる。

このメソッドでアタッチできるのは、Z バッファのサーフェスのみである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::DeleteAttachedSurface、IDirectDrawSurface7::EnumAttachedSurfaces


IDirectDrawSurface7::AddOverlayDirtyRect

IDirectDrawSurface7::AddOverlayDirtyRect メソッドは、現時点では実装されていない。

HRESULT AddOverlayDirtyRect(
  LPRECT lpRect
);

パラメータ

lpRect
更新する必要がある RECT 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::UpdateOverlayDisplay


IDirectDrawSurface7::Blt

IDirectDrawSurface7::Blt メソッドは、ビット ブリット (ブロック転送) を実行する。このメソッドは、ブリット処理中に Z バッファまたはアルファ ブレンディング (アルファ チャネルを参照) をサポートしない。

HRESULT Blt(
  LPRECT lpDestRect,
  LPDIRECTDRAWSURFACE7 lpDDSrcSurface,
  LPRECT lpSrcRect,
  DWORD dwFlags,
  LPDDBLTFX lpDDBltFx
);

パラメータ

lpDestRect
転送先サーフェス上にブリットする矩形の左上と右下の位置を定義する RECT 構造体のアドレス。このパラメータが NULL の場合、転送先サーフェス全体を使用する。
lpDDSrcSurface
ブリットの転送元である DirectDrawSurface オブジェクトの IDirectDrawSurface7 インターフェイスのアドレス。
lpSrcRect
転送元サーフェス上からブリットする矩形の左上と右下の位置を定義する RECT 構造体のアドレス。このパラメータが NULL の場合、転送元サーフェス全体を使用する。
dwFlags
カラーキー情報を指定する、またはメソッドから特別な動作を要求する、関連付けられた DDBLTFX 構造体の有効メンバを決定するフラグの組み合わせ。以下のフラグが定義されている。

評価フラグ

DDBLT_COLORFILL
転送先サーフェス上の転送先矩形を格納する RGB 色として DDBLTFX 構造体の dwFillColor メンバを使用する。
DDBLT_DDFX
このブリットに対して使用するエフェクトを指定する、DDBLTFX 構造体の dwDDFX メンバを使用する。
DDBLT_DDROPS
Microsoft® Win32® API の部分ではないラスタ処理 (ROPS) を指定する、DDBLTFX 構造体の dwDDROP メンバを使用する。
DDBLT_DEPTHFILL
転送先 Z バッファ サーフェス上の転送先矩形を格納する深度値として、DDBLTFX 構造体の dwFillDepth メンバを使用する。
DDBLT_KEYDESTOVERRIDE
転送先サーフェスのカラー キーとして DDBLTFX 構造体の ddckDestColorkey メンバを使用する。
DDBLT_KEYSRCOVERRIDE
転送元サーフェスのカラー キーとして DDBLTFX 構造体の ddckSrcColorkey メンバを使用する。
DDBLT_ROP
このブリットにおける ROP に DDBLTFX 構造体の dwROP メンバを使用する。これらの ROP は、Win32 API で定義されているものと同じである。
DDBLT_ROTATIONANGLE
サーフェスの回転角 (1/100 度単位で指定される) として DDBLTFX 構造体の dwRotationAngle メンバを使用する。

カラー キー フラグ

DDBLT_KEYDEST
転送先サーフェスに関連付けられたカラー キーを使用する。
DDBLT_KEYSRC
転送元サーフェスに関連付けられたカラー キーを使用する。

動作フラグ

DDBLT_ASYNC
受け取った順序でファーストイン、ファーストアウト (FIFO) ハードウェアから非同期的にこのブリットを実行する。FIFO ハードウェアの空き領域を利用できない場合、呼び出しは失敗する。
DDBLT_DONOTWAIT
DirectX 7.0 で追加。ブリットを実行せずに返す、またはブリットがビジーの場合に DDERR_WASSTILLDRAWING を返す。
DDBLT_WAIT
ブリットがビジーの場合、DDERR_WASSTILLDRAWING 戻り値をすぐに返さずに待機する。そして、ブリットがセット アップされるか、別のエラーが発生したら即座に返す。

廃止されサポートしないフラグ

All DDBLT_ALPHA flag values.
現時点では、実装されていない。
All DDBLT_ZBUFFER flag values
このメソッドは、z 対応のブリット処理を現在サポートしていない。"DDBLT_ZBUFFER" で始まるフラグは、DirectX のこのリリースではサポートしていない。
lpDDBltFx
DDBLTFX 構造体のアドレス。

戻り値

成功すれば、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
DDERR_WASSTILLDRAWING

注意

このメソッドでは、同期または非同期のブリット (後者がデフォルト) を、ディスプレイ メモリ間、ディスプレイ メモリからシステム メモリへ、システム メモリからディスプレイ メモリへ、またはシステム メモリ間のいずれかで実行できる。ブリットは、転送元カラー キーおよび転送先カラー キーを使って実行される。転送元および転送先矩形のサイズが異なる場合は、任意の伸縮や収縮が行われる。

通常、ブリットがビジーの場合、またはブリットをセット アップできなかった場合、IDirectDrawSurface7：:Blt はエラーと共に即座に返る。同期ブリットを要求するには、DDBLT_WAIT フラグを指定する。DDBLT_WAIT フラグを指定すると、ブリットがセット アップされるか、メソッドが返る前に別のエラーが発生するまで、このメソッドは待機する。

RECT 構造体は、right および bottom メンバが排他的であるように定義される。したがって、right から left を引くと矩形の幅と等しくなる。これは、矩形の幅より 1 だけ少ない値ではない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::BltBatch

IDirectDrawSurface7::BltBatch メソッドは、現時点では実装されていない。

HRESULT BltBatch(
  LPDDBLTBATCH lpDDBltBatch,
  DWORD dwCount,
  DWORD dwFlags
);

パラメータ

lpDDBltBatch
ブリット処理におけるパラメータを定義する、最初の DDBLTBATCH 構造体のアドレス。
dwCount
実行するブリット処理の個数。
dwFlags
現時点では未使用なので 0 を設定しておく。

戻り値

成功すれば、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

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::BltFast

IDirectDrawSurface7::BltFast メソッドは、転送元カラー キー または転送先カラー キー を使って、転送元コピー ブリットあるいは透過型ブリットを実行する。

HRESULT BltFast(
  DWORD dwX,
  DWORD dwY,
  LPDIRECTDRAWSURFACE7 lpDDSrcSurface,
  LPRECT lpSrcRect,
  DWORD dwTrans
);

パラメータ

dwX、dwY
転送先サーフェス上にブリットする x 座標と y 座標。
lpDDSrcSurface
ブリットの転送元である DirectDrawSurface オブジェクトの IDirectDrawSurface7 インターフェイスのアドレス。
lpSrcRect
転送元サーフェスからブリットする矩形の左上と右下の角を定義する RECT 構造体のアドレス。
dwTrans
転送のタイプ。以下の転送が定義されている。
DDBLTFAST_DESTCOLORKEY
転送先カラー キーを使用する透過型ブリット。
DDBLTFAST_NOCOLORKEY
非透過型の通常のコピー ブリット。
DDBLTFAST_SRCCOLORKEY
転送元カラー キーを使用する透過型ブリット。
DDBLTFAST_WAIT
ブリットがビジーの場合、DDERR_WASSTILLDRAWING メッセージを返さずに待機する。ブリットがセット アップされるか、あるいは別のエラーが発生すると即座に返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_EXCEPTION
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

ハードウェアが非同期ブリットをサポートする場合、このメソッドは常にそれを試みる。

このメソッドはディスプレイ メモリ サーフェス上だけで作用し、ブリット中はクリップできない。アタッチされたクリッパーがあるサーフェスでこのメソッドを使用すると、呼び出しは失敗し、メソッドは DDERR_UNSUPPORTED を返す。

IDirectDrawSurface7::BltFast のソフトウェア実装は、IDirectDrawSurface7::Blt メソッドより 10 パーセントだけ高速である。ただし、ディスプレイ ハードウェアを使用している場合は、両者の間に速さの違いはない。

通常、ブリットがビジーの場合、およびブリットがセットアップされていない場合、IDirectDrawSurface7::BltFast は即座にエラーを返す。ただし、ブリットがセット アップされるか別のエラーが発生するまで、このメソッドを返さない場合は、DDBLTFAST_WAIT フラグを使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::ChangeUniquenessValue

IDirectDrawSurface7::ChangeUniquenessValue メソッドは、このサーフェスに対する固有値を手動で更新する。

HRESULT ChangeUniquenessValue();

パラメータ

なし。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

サーフェスのコンテンツを変更すると常に、DirectDraw は固有値を自動的に更新する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetUniquenessValue、サーフェス固有値


IDirectDrawSurface7::DeleteAttachedSurface

IDirectDrawSurface7::DeleteAttachedSurface メソッドは、2 つのサーフェス間のアタッチを解除する。

HRESULT DeleteAttachedSurface(
  DWORD dwFlags,
  LPDIRECTDRAWSURFACE7 lpDDSAttachedSurface
);

パラメータ

dwFlags
現時点では未使用なので 0 に設定しておく。
lpDDSAttachedSurface
アタッチを解除する DirectDrawSurface オブジェクトの IDirectDrawSurface7 インターフェイスのアドレス。このパラメータが NULL の場合、アタッチされたすべてのサーフェスのアタッチが解除される。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CANNOTDETACHSURFACE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_SURFACENOTATTACHED

注意

このメソッドは、アタッチを解除するサーフェスの参照カウントをデクリメントする。アタッチを解除するサーフェスの参照カウントがゼロになると、そのサーフェスは消失し、メモリから削除される。

IDirectDrawSurface7::AddAttachedSurface メソッドではなく、DirectDraw によって形成される暗黙的なアタッチは解除できない。フリッピング チェーンからサーフェスのアタッチを解除すると、チェーン中の他のサーフェスを変更する可能性がある。フリッピング チェーンからフロント バッファのアタッチを解除すると、チェーンの中の次のサーフェスがフロント バッファとなり、その次のサーフェスがバック バッファとなる。チェーンからバック バッファのアタッチを解除する場合、次のサーフェスがバック バッファとなる。チェーンからプレーン サーフェスのアタッチを解除する場合、そのチェーンが単に短くなる。フリッピング チェーンに 2 つサーフェスがあるだけで、それらのアタッチを解除する場合、そのチェーンは破棄されて、両サーフェスは元の転送先に戻る。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::Flip


IDirectDrawSurface7::EnumAttachedSurfaces

IDirectDrawSurface7::EnumAttachedSurfaces メソッドは、与えられたサーフェスにアタッチされるすべてのサーフェスを列挙する。

HRESULT EnumAttachedSurfaces(
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpEnumSurfacesCallback
);

パラメータ

lpContext
呼び出しのたびに列挙メンバに渡す、アプリケーション定義構造体のアドレス。
lpEnumSurfacesCallback
このサーフェスにアタッチされる各サーフェスに対して呼び出す EnumSurfacesCallback2 関数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すると、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

注意

このメソッドは、このサーフェスに直接アタッチされたサーフェスだけを列挙する。たとえば、3 つ以上のサーフェスのフリッピング チェーンでは、個々のサーフェスがフリッピング チェーンの次のサーフェスにのみアタッチされるので、1 つのサーフェスのみ列挙される。このような構成では、個々の連続するサーフェス上で EnumAttachedSurfaces を呼び出すと、フリッピング チェーン全体を見ることができる。

このメソッドは以前のバージョンのインターフェイスの対応するメソッドとは異なり、EnumSurfacesCallback 関数よりも EnumSurfacesCallback2 関数へのポインタを受け取る。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::EnumOverlayZOrders

IDirectDrawSurface7::EnumOverlayZOrders メソッドは、指定する転送先のオーバーレイ サーフェスを列挙する。オーバーレイは、フロントからバック、またはバックからフロントの順で列挙される。

HRESULT EnumOverlayZOrders(
  DWORD dwFlags,
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpfnCallback
);

パラメータ

dwFlags
以下のフラグのうち、1 つの値を取る。
DDENUMOVERLAYZ_BACKTOFRONT
バックからフロントの順でオーバーレイを列挙する。
DDENUMOVERLAYZ_FRONTTOBACK
フロントからバックの順でオーバーレイを列挙する。
lpContext
各オーバーレイ サーフェスのコールバック関数に渡す、ユーザー定義コンテキストのアドレス。
lpfnCallback
このサーフェスにオーバーレイされる各サーフェスに対して呼び出す、EnumSurfacesCallback2 コールバック関数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは以前のバージョンのインターフェイスの対応するメソッドとは異なり、EnumSurfacesCallback 関数よりも EnumSurfacesCallback2 関数へのポインタを受け取る。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::Flip

IDirectDrawSurface7::Flip メソッドは、DDSCAPS_BACKBUFFER サーフェスと関連付けられたサーフェス メモリを、フロントバッファ サーフェスと関連付ける。

HRESULT Flip(
  LPDIRECTDRAWSURFACE7 lpDDSurfaceTargetOverride,
  DWORD dwFlags
);

パラメータ

lpDDSurfaceTargetOverride
フリッピング チェーンの任意のサーフェスにおける IDirectDrawSurface7 インターフェイスのアドレス。このパラメータのデフォルトは NULL であり、DirectDraw は互いにアタッチされている順にバッファから循環する。このパラメータが NULL でない場合、DirectDraw はフリッピング チェーンの次のサーフェスの代わりに指定したサーフェスへフリップする。指定したサーフェスがフリッピング チェーンのメンバではない場合、メソッドは失敗する。
dwFlags
指定するフリップ オプションのフラグ
DDFLIP_DONOTWAIT
IDirectDrawSurface7 インターフェイスでは、デフォルトは DDFLIP_WAIT である。デフォルトを無効にする場合、およびアクセラレータがビジーの場合 (DDERR_WASSTILLDRAWING 戻り値で示される) は、DDFLIP_DONOTWAIT を使用する。
DDFLIP_EVEN
オーバーレイ サーフェスでビデオを表示する場合に使用。新しいサーフェスには、ビデオ信号の偶数フィールドからのデータが含まれる。このフラグは、DDFLIP_ODD フラグと共に使用することはできない。
DDFLIP_STEREO
DirectDraw は、メイン ステレオ サーフェスをフリップして表示する。このフラグを設定すると、ステレオ自動フリッピングが有効になる。個々のスクリーンをリフレッシュする間、ハードウェアは自動的に左右のバッファ間をフリップする。
DDFLIP_INTERVAL2
DDFLIP_INTERVAL3
DDFLIP_INTERVAL4
これらのフラグは、各フリップ間を待機する垂直リトレイス数を示す。デフォルト値は 1。DirectDraw では、指定した垂直リトレイス数になるまで、フリップ内の各サーフェスに対する DERR_WASSTILLDRAWING を返す。DDFLIP_INTERVAL2 を設定すると、DirectDraw は 2 番目の垂直同期ごとにフリップする。DDFLIP_INTERVAL3 では 3 番目の同期ごと、DDFLIP_INTERVAL4 では 4 番目の同期ごとにフリップする。

これらのフラグは効率的であるのは、DDCAPS2_FLIPINTERVAL がデバイスに返される DDCAPS 構造体に設定される場合だけである。

DDFLIP_NOVSYNC
次の走査線にできる限り近い物理的なフリップを実行する DirectDraw を引き起こす。2 つのフリップされたサーフェスを含む次の処理では、物理的なフリップが終了したかどうかのチェックは行われない。つまり、この理由から DDERR_WASSTILLDRAWING が返されることはない (その他の理由によって返される場合はある)。このため、アプリケーションではモニタ リフレッシュ レート以上の高周波数でフリップを実行することが可能であるが、目に見える異常が発生する場合がある。

DDCAPS2_FLIPNOVSYNC がデバイスに返される DDCAPS 構造体に設定されない場合、DDFLIP_NOVSYNC はエフェクトがない。

DDFLIP_ODD
オーバーレイ サーフェスでビデオを表示する場合に使用。新しいサーフェスには、ビデオ信号の奇数フィールドからのデータが含まれる。このフラグは、DDFLIP_EVEN フラグと共に使用することはできない。
DDFLIP_WAIT
通常、ディスプレイ ハードウェアの状態が不適切なためにフリップをセット アップできない場合、DDERR_WASSTILLDRAWING エラーが即座に返り、フリップは起こらない。このフラグを設定すると、メソッドはハードウェア アブストラクション レイヤ (HAL) から DDERR_WASSTILLDRAWING エラーを受け取った場合でもフリップを続行しようとする。この場合、メソッドはフリッピング処理が成功するか、DDERR_SURFACEBUSY のような別のエラーが返されるまで返さない。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

IDirectDrawSurface7 の場合、デフォルトでは、このメソッドはアクセラレータが終了するまで待機する。つまり、デフォルト状態では、このメソッドは DDERR_WASSTILLDRAWING を返さない。エラー コードを受け取り、フリップ処理が成功するまで待機しない場合は、DDFLIP_DONOTWAIT フラグを使用する。

このメソッドを呼び出すことができるのは、DDSCAPS_FLIP および DDSCAPS_FRONTBUFFER 能力のあるサーフェスだけである。以前にフロント バッファに関連付けられたディスプレイ メモリは、バック バッファと関連付けられる。

lpDDSurfaceTargetOverride パラメータは、バック バッファがフロント バッファになるべきバッファではないという場合に使用されるが、このような場合はまれである。通常、このパラメータは NULL である。

IDirectDrawSurface7::Flip メソッドは、常に垂直帰線消去と同期する。サーフェスがビデオ ポートに割り当てられていると、このメソッドは表示状態のオーバーレイ サーフェスおよびビデオ ポートのターゲット サーフェスを更新する。

詳細については、「フリッピング サーフェス」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetFlipStatus


IDirectDrawSurface7::FreePrivateData

IDirectDrawSurface7::FreePrivateData メソッドは、このサーフェスに関連付けられた指定するプライベート データを解放する。

HRESULT FreePrivateData(
  REFGUID guidTag
);

パラメータ

guidTag
解放するプライベート データを識別するグローバル ユニーク識別子の (C++) または (C) のアドレスへの参照。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

注意

DirectDraw は、サーフェスが解放されると自動的にこのメソッドを呼び出す。

プライベート データが DDSPD_IUNKNOWNPOINTER フラグを使用して設定されている場合、このメソッドは関連付けられたインターフェイスの IUnknown::Release メソッドを呼び出す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetPrivateData、IDirectDrawSurface7::SetPrivateData


IDirectDrawSurface7::GetAttachedSurface

IDirectDrawSurface7::GetAttachedSurface メソッドは、指定した能力を持つアタッチされたサーフェスを取得し、取得したインターフェイスの参照カウントをインクリメントする。

HRESULT GetAttachedSurface(
  LPDDSCAPS2 lpDDSCaps,
  LPDIRECTDRAWSURFACE7 FAR *lplpDDAttachedSurface
);

パラメータ

lpDDSCaps
サーフェスのハードウェア能力を含む DDSCAPS2 構造体のアドレス。
lplpDDAttachedSurface
取得するサーフェスの IDirectDrawSurface7 インターフェイスへのポインタを受け取る変数のアドレス。取得するサーフェスは、lpDDSCaps パラメータの記述に適合するものである。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST

注意

アタッチは、複数の DirectDrawSurface オブジェクトを複合構造体に接続するために使用される。複合構造体とは、たとえば、Z バッファと共に 3D ページ フリッピングをサポートするために必要な構造体である。要求する能力に適合するアタッチされたサーフェスが 1 つ以上ある場合、このメソッドは失敗する。この場合、アプリケーションではアタッチされたサーフェスを取得するには、IDirectDrawSurface7::EnumAttachedSurfaces メソッドを使用しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::GetBltStatus

IDirectDrawSurface7::GetBltStatus メソッドは、ブリットのステータスを取得する。

HRESULT GetBltStatus(
  DWORD dwFlags
);

パラメータ

dwFlags
以下のフラグのうち、1 つの値を取る。
DDGBS_CANBLT
このサーフェスを必要とするブリットがすぐに実行できるかどうかを問い合わせ、ブリットが完了すると DD_OK を返す。
DDGBS_ISBLTDONE
ブリットが実行されたかどうかを問い合わせ、このサーフェス上の最後のブリットが完了すると DD_OK を返す。

戻り値

成功すれば、ブリットが存在し、DD_OK を返す。

失敗すれば、ブリットがビジーの場合は DDERR_WASSTILLDRAWING、ブリットが存在しない場合は DDERR_NOBLTHW、その他の場合は以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::GetCaps

IDirectDrawSurface7::GetCaps メソッドは、サーフェスの能力を取得する。これらの能力は、ディスプレイ デバイスの能力に関連している必要はない。

HRESULT GetCaps(
  LPDDSCAPS2 lpDDSCaps
);

パラメータ

lpDDSCaps
サーフェスのハードウェア能力を格納する DDSCAPS2 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは IDirectDrawSurface3 インターフェイスの対応するメソッドとは異なり、現在は使用されない DDSCAPS 構造体ではなく DDSCAPS2 構造体へのポインタを受け取る。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::GetClipper

IDirectDrawSurface7::GetPalette メソッドは、このサーフェスに関連付けられた DirectDrawPalette オブジェクトを取得し、返されるクリッパーの参照カウントをインクリメントする。

HRESULT GetClipper(
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper
);

パラメータ

lplpDDClipper
サーフェスに関連付けられた DirectDrawClipper オブジェクトへのポインタのアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPPERATTACHED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::SetClipper


IDirectDrawSurface7::GetColorKey

IDirectDrawSurface7::GetColorKey メソッドは、DirectDrawSurface オブジェクトに対するカラー キー値を取得する。

HRESULT GetColorKey(
  DWORD dwFlags,
  LPDDCOLORKEY lpDDColorKey
);

パラメータ

dwFlags
以下のフラグのいずれかで、どのカラー キーを要求するかを指定する。
DDCKEY_DESTBLT
ブリット処理の転送先カラー キーとして使用されるカラー キーまたは色空間。
DDCKEY_DESTOVERLAY
オーバーレイ処理の転送先カラー キーとして使用されるカラー キーまたは色空間。
DDCKEY_SRCBLT
ブリット処理の転送元カラー キーとして使用されるカラー キーまたは色空間。
DDCKEY_SRCOVERLAY
オーバーレイ処理の転送元カラー キーとして使用されるカラー キーまたは色空間。
lpDDColorKey
DirectDrawSurface オブジェクトの、指定されたカラー キーに対する現在の値を格納する DDCOLORKEY 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOLORKEY
DDERR_NOCOLORKEYHW
DDERR_SURFACELOST
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::SetColorKey


IDirectDrawSurface7::GetDC

IDirectDrawSurface7::GetDC メソッドは、サーフェスに対するデバイス コンテキストの GDI 互換ハンドルを作成する。

HRESULT GetDC(
  HDC FAR *lphDC
);

パラメータ

lphDC
返される、デバイス コンテキストのハンドルのアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

このメソッドは、サーフェスをロックする IDirectDrawSurface7::Lock メソッドの内部バージョンを使用する。IDirectDrawSurface7::ReleaseDC メソッドが呼び出されるまでは、サーフェスはロックされたままである。

ReleaseDC は、GetDC を呼び出す同じスレッドから呼び出す必要がある。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::Lock


IDirectDrawSurface7::GetDDInterface

IDirectDrawSurface7::GetDDInterface メソッドは、サーフェスを作成するために使用された DirectDraw オブジェクトへのインターフェイスを取得する。

HRESULT GetDDInterface(
  LPVOID FAR *lplpDD
);

パラメータ

lplpDD
呼び出しが成功した場合に、有効なインターフェイス ポインタを格納する変数のアドレス。このポインタを IUnknown インターフェイス ポインタへキャストした後に、要求する DirectDraw インターフェイスに対して照会する。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、IDirectDraw インターフェイスには実装されていない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::GetFlipStatus

IDirectDrawSurface7::GetFlipStatus メソッドは、サーフェスがフリッピング プロセスを終えたかどうかを示す。

HRESULT GetFlipStatus(
  DWORD dwFlags
);

パラメータ

dwFlags
以下のフラグのうち、1 つの値を取る。
DDGFS_CANFLIP
このサーフェスを即座にフリップできるかどうかを問い合わせ、フリップが完了したら DD_OK を返す。
DDGFS_ISFLIPDONE
フリップが完了したかどうかを問い合わせ、このサーフェスの最後のフリップが完了したら DD_OK を返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、サーフェスがフリップされていない場合は DDERR_WASSTILLDRAWING を返し、その他の理由による場合は以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::Flip


IDirectDrawSurface7::GetLOD

IDirectDrawSurface7::GetLOD メソッドは、管理ミップマップ サーフェスに現在設定されている最大詳細レベルを取得する。このメソッドは、管理下のテクスチャに対してのみ成功する (「注意」参照)。

HRESULT GetLOD(
    LPDWORD lpdwMaxLOD
);

パラメータ

lpdwMaxLOD
呼び出しが成功した場合に、最大詳細レベルの値を格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

アプリケーションは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE フラグで作成されたテクスチャ) に対してのみ、このメソッドを呼び出すことができる。非管理下のテクスチャに対してこのメソッドを呼び出すと、メソッドは失敗し、DDERR_INVALIDOBJECT を返す。

このメソッドは、ローカル ビデオ メモリにロードするこのチェーンの中で最も詳細なミップマップを Direct3D テクスチャ マネージャに通知する。たとえば、5 レベルのミップマップ チェーンにおいて、lpdwMaxLOD で示す変数の値が 2 の場合、テクスチャ マネージャは指定時間になるとレベル 2 から 4 のミップマップのみローカル ビデオ メモリにロードする。同様に、チェーンの中で最も詳細なミップマップの大きさが 256 × 256 の場合、lpdwMaxLOD の値 2 は、これまでにビデオ メモリ内にある最大のミップマップは 64 × 64 であることを示す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::SetLOD、ミップマップによるテクスチャ フィルタリング、自動テクスチャ管理、テクスチャ


IDirectDrawSurface7::GetOverlayPosition

アクティブに表示状態のオーバーレイ サーフェス (DDSCAPS_OVERLAY フラグが設定されている) が与えられると、IDirectDrawSurface7::GetOverlayPosition メソッドはサーフェスのディスプレイ座標を返す。

HRESULT GetOverlayPosition(
  LPLONG lplX,
  LPLONG lplY
);

パラメータ

lplX、lplY
x 座標と y 座標のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::SetOverlayPosition、IDirectDrawSurface7::UpdateOverlay


IDirectDrawSurface7::GetPalette

IDirectDrawSurface7::GetPalette メソッドは、このサーフェスに関連付けられた DirectDrawPalette オブジェクトを取得し、返されるパレットの参照カウントをインクリメントする。

HRESULT GetPalette(
  LPDIRECTDRAWPALETTE FAR *lplpDDPalette
);

パラメータ

lplpDDPalette
パレット オブジェクトの IDirectDrawPalette インターフェイスへのポインタを格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::SetPalette


IDirectDrawSurface7::GetPixelFormat

IDirectDrawSurface7::GetPixelFormat メソッドは、サーフェスのカラーとピクセル フォーマットを取得する。

HRESULT GetPixelFormat(
  LPDDPIXELFORMAT lpDDPixelFormat
);

パラメータ

lpDDPixelFormat
サーフェスの現在のピクセルおよび色空間フォーマットの詳細記述を格納する DDPIXELFORMAT 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::GetPriority

IDirectDrawSurface7::GetPriority メソッドは、テクスチャのテクスチャ管理優先順位を取得する。このメソッドは、管理下のテクスチャに対してのみ成功する (「注意」参照)。

HRESULT GetPriority(
  LPDWORD lpdwPriority
);

パラメータ

lpdwPriority
呼び出しが成功した場合に、テクスチャ管理優先順位を格納する変数のアドレス。

戻り値

成功すれば、D3D_OK を返す。

失敗すれば、エラー値を返す。パラメータが無効な場合、またはテクスチャが Direct3D で管理されていない場合、メソッドは DDERR_INVALIDOBJECT を返す。

注意

優先順位を使用して、管理下のテクスチャをメモリからいつ削除するかを決定できる。優先順位が低いテクスチャは、優先順位が高いテクスチャより先に削除される。2 つのテクスチャの優先順位が同じ場合は、最終使用時が新しい方のテクスチャがメモリに保持され、もう一方のテクスチャが削除される。

アプリケーションでは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE フラグで作成したもの) でのみ優先順位を設定および取得できる。非管理下のテクスチャに対してこのメソッドを呼び出すと、メソッドは失敗し、DDERR_INVALIDOBJECT を返す。

このメソッドは、IDirectDrawSurface7 インターフェイスによって導入された。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::SetPriority、自動テクスチャ管理、テクスチャ


IDirectDrawSurface7::GetPrivateData

IDirectDrawSurface7::GetPrivateData メソッドは、提供されるバッファへのサーフェスに関連付けられたプライベート データをコピーする。

HRESULT GetPrivateData(
  REFGUID guidTag,
  LPVOID  lpBuffer,
  LPDWORD lpcbBufferSize
);

パラメータ

guidTag
取得するプライベート データを識別するグローバル ユニーク識別子の (C++) または (C) のアドレスへの参照。
lpBuffer
呼び出しが成功した場合に、要求したプライベート データを格納する割り当て済みバッファのアドレス。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
lpcbBufferSize
バイト単位の lpBuffer のバッファ サイズ。この値が実際のプライベート データのサイズよりも小さい (0 など) 場合、メソッドは要求されるバッファ サイズにこのパラメータを設定し、DDERR_MOREDATA を返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_EXPIRED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA
DDERR_NOTFOUND
DDERR_OUTOFMEMORY

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::SetPrivateData、IDirectDrawSurface7::FreePrivateData


IDirectDrawSurface7::GetSurfaceDesc

IDirectDrawSurface7::GetSurfaceDesc メソッドは、現在の状態におけるサーフェス記述を取得する。

HRESULT GetSurfaceDesc(
  LPDDSURFACEDESC2 lpDDSurfaceDesc
);

パラメータ

lpDDSurfaceDesc
このサーフェスの現在の記述を格納する DDSURFACEDESC2 構造体のアドレス。メソッドを呼び出す前に、この構造体の dwSize メンバは、構造体のサイズ (バイト単位) に初期化だけされなくてはならない。つまり、他の準備は必要ない。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

DDSURFACEDESC、DDSURFACEDESC2


IDirectDrawSurface7::GetUniquenessValue

IDirectDrawSurface7::GetUniquenessValue メソッドは、このサーフェスに対する現在の固有値を取得する。

HRESULT GetUniquenessValue(
  LPDWORD lpValue
);

パラメータ

lpValue
呼び出しが成功した場合に、サーフェスの現在の固有値を格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

定義されている固有値だけが 0 になり、サーフェスが DirectDraw による制御を超えて変更されることが多いことを示す。他の固有値は、キャッシュされる前の固有値と異なる場合にだけ重要となる。キャッシュされる値と現在の値が異なる場合は、サーフェスの内容が変更される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::ChangeUniquenessValue、サーフェス固有値


IDirectDrawSurface7::Initialize

IDirectDrawSurface7::Initialize メソッドは、DirectDrawSurface オブジェクトを初期化する。

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  LPDDSURFACEDESC2 lpDDSurfaceDesc
);

パラメータ

lpDD
DirectDraw オブジェクトを表す DirectDraw 構造体のアドレス。
lpDDSurfaceDesc
サーフェスに関連する詳細を格納する DDSURFACEDESC2 構造体のアドレス。

戻り値

メソッドは、DDERR_ALREADYINITIALIZED を返す。

注意

このメソッドは、コンポーネント オブジェクト モデル (COM) プロトコル準拠で提供される。DirectDrawSurface オブジェクトは作成時に初期化されるため、このメソッドは常に DDERR_ALREADYINITIALIZED を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IUnknown::AddRef、IUnknown::QueryInterface、IUnknown::Release


IDirectDrawSurface7::IsLost

IDirectDrawSurface7::IsLost メソッドは、DirectDrawSurface オブジェクトに関連付けられたサーフェス メモリが解放されたかどうかを判断する。

HRESULT IsLost();

パラメータ

なし。

戻り値

成功すれば、メモリが解放されていないため DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

このメソッドを使用して、サーフェス メモリの再割り当てをいつ行うかを決定できる。DirectDrawSurface オブジェクトがサーフェス メモリを消失すると、大部分のメソッドは DDERR_SURFACELOST を返して他のアクションを実行しない。

注意

ディスプレイ カードのモードが変更されると、またはアプリケーションでディスプレイ カードへの排他アクセスを受け取り、ディスプレイ カードに現在割り当てられているサーフェス メモリをすべて解放すると、サーフェスのメモリが消失することがある。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::Restore、サーフェスの消失とリストア


IDirectDrawSurface7::Lock

IDirectDrawSurface7::Lock メソッドは、サーフェス メモリへのポインタを取得する。

HRESULT Lock(
  LPRECT lpDestRect,
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  DWORD dwFlags,
  HANDLE hEvent
);

パラメータ

lpDestRect
ロックされているサーフェスの領域を指定する RECT 構造体のアドレス。このパラメータが NULL の場合、サーフェス全体がロックされる。
lpDDSurfaceDesc
サーフェスに関連する詳細を格納する DDSURFACEDESC2 構造体のアドレス。
dwFlags
以下のフラグが定義されている。
DDLOCK_DONOTWAIT
IDirectDrawSurface7 インターフェイスでは、デフォルトは DDLOCK_WAIT である。デフォルトを無効にする場合、およびアクセラレータがビジーの場合 (DDERR_WASSTILLDRAWING 戻り値で示される) 場合は、DDLOCK_DONOTWAIT を使用する。
DDLOCK_EVENT
現時点では、実装されていない。
DDLOCK_NOOVERWRITE
DirectX 7.0 で追加。Direct3D 頂点バッファのロックにのみ使用する。ロック中にフレームの始点 (または、このフラグを使用しない場合は最後のロック) が変更されるため、Draw*PrimitiveVB の呼び出しに参照される頂点が存在しない示す。このフラグは、頂点バッファにデータを追加するときに便利である。
DDLOCK_NOSYSLOCK
Win16Mutex (Win16Lock と呼ばれる) を使用しない。プライマリ サーフェスをロックしているときは、このフラグは無視される。
DDLOCK_DISCARDCONTENTS
DirectX 7.0 で追加。Direct3D 頂点バッファのロックにのみ使用する。このロック中に頂点バッファの内容を引き継ぐ場所がないことを示す。このフラグを指定すると、Direct3D またはドライバは別のメモリ領域を頂点バッファとして提供できる。このフラグは、頂点バッファの内容を消去して新しいデータを入れるときに便利である。
DDLOCK_OKTOSWAP
このフラグは廃止されており、DDLOCK_DISCARDCONTENTS フラグで置き換えられている。
DDLOCK_READONLY
ロックされているサーフェスは読み込み専用であることを示す。
DDLOCK_SURFACEMEMORYPTR
指定される矩形の上位への有効なメモリ ポインタを返さなくてはならないことを示す。指定される矩形がない場合、サーフェスの上位へのポインタが返される。このフラグはデフォルトである。
DDLOCK_WAIT
ブリット処理中であるためロックを取得できない場合、ロックが取得されるまで、または DDERR_SURFACEBUSY などの別のエラーが発生するまで、メソッドはロックを取得しようと繰り返す。
DDLOCK_WRITEONLY
ロックされているサーフェスが書き込み可能であることを示す。
hEvent
未使用なので NULL を設定しておく。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

注意

このメソッドの利用についての詳細情報は、「サーフェス メモリへの直接アクセス」を参照すること。

IDirectDrawSurface7 の場合、デフォルトでは、このメソッドはアクセラレータが終了するまで待機する。つまり、デフォルト状態では、このメソッドは DDERR_WASSTILLDRAWING を返さない。エラー コードを受け取り、ブリット処理が成功するまで待機しない場合は、DDLOCK_DONOTWAIT フラグを使用する。

サーフェス メモリ ポインタを取得した後、対応する IDirectDrawSurface7::Unlock メソッドが呼び出されるまでサーフェス メモリにアクセスできる。サーフェスのロックが解除されると、サーフェス メモリへのポインタは無効となる。

サーフェスのロックされた領域からブリットするために、DirectDraw ブリット関数を呼び出してはならない。この関数を呼び出した場合、ブリットは DDERR_SURFACEBUSY または DDERR_LOCKEDSURFACES のいずれかを返す。GDI ブリット関数は、ロックされたビデオ メモリ サーフェスで使用した場合は何も返さず失敗する。

DDLOCK_NOSYSLOCK フラグを含まなければ、このメソッドは IDirectDrawSurface7::Unlock メソッドを呼び出すまで、DirectDraw で Win16Mutex (Win16Lock とも呼ばれる) を保持する。GUI デバッガは、Win16Mutex が保持されている間は処理できない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::Unlock、IDirectDrawSurface7::GetDC、IDirectDrawSurface7::ReleaseDC


IDirectDrawSurface7::PageLock

IDirectDrawSurface7::PageLock メソッドは、ダイレクト メモリ アクセス (DMA) によるシステム メモリへのブリット処理中、またはシステム メモリからのブリット処理中に、システム メモリ サーフェスがページ アウトされることを回避する。

HRESULT PageLock(
  DWORD dwFlags
);

パラメータ

dwFlags
現時点では未使用なので 0 を設定しておく。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CANTPAGELOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

注意

DMA サポートを利用するには、このメソッドを呼び出さなくてはならない。このメソッドを呼び出さないと、ブリットはソフトウェア エミュレーションを使って行われる。詳細については、「DMA の使用」を参照すること。

ロックするメモリが多すぎると、オペレーティング システムのパフォーマンスに悪影響を与える。

ロック カウントは個々のサーフェスに対して維持され、サーフェスに対して IDirectDrawSurface7::PageLock が呼び出されるたびにインクリメントされる。IDirectDrawSurface7::PageUnlock が呼び出されると、このカウントはデクリメントされる。ロック カウントが 0 になると、メモリのロックが解除され、オペレーティング システムでページングできるようになる。

このメソッドは、システムメモリ サーフェスに対してだけ作用する。つまり、ディスプレイメモリ サーフェスやエミュレートされるプライマリ サーフェスをページロックすることはできない。アプリケーションがディスプレイ メモリ サーフェスでこのメソッドを呼び出した場合、メソッドは DD_OK を返すだけである。

このメソッドは、IDirectDraw インターフェイスには実装されていない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::PageUnlock


IDirectDrawSurface7::PageUnlock

IDirectDrawSurface7::PageUnlock メソッドは、システムメモリ サーフェスのロックを解除して、ページ アウトできるようにする。

HRESULT PageUnlock(
  DWORD dwFlags
);

パラメータ

dwFlags
現時点では未使用なので 0 を設定しておく。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_CANTPAGEUNLOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPAGELOCKED
DDERR_SURFACELOST

注意

ロック カウントは個々のサーフェスに対して維持され、サーフェスに対して IDirectDrawSurface7::PageLock が呼び出されるたびにインクリメントされる。このカウントは、IDirectDrawSurface7::PageUnlock が呼び出されるとデクリメントされる。ロック カウントが 0 になると、メモリのロックが解除され、オペレーティング システムでページングできるようになる。

このメソッドは、システムメモリ サーフェスに対してだけ作用する。つまり、ディスプレイメモリ サーフェスやエミュレートされるプライマリ サーフェスをページロックすることはできない。アプリケーションがディスプレイメモリ サーフェスでこのメソッドを呼び出した場合、このメソッドは DD_OK を返すだけである。

このメソッドは、IDirectDraw インターフェイスには実装されていない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::PageLock


IDirectDrawSurface7::ReleaseDC

IDirectDrawSurface7::ReleaseDC メソッドは、以前に IDirectDrawSurface7::GetDC メソッドで取得したデバイス コンテキストのハンドルを解放する。

HRESULT ReleaseDC(
  HDC hDC
);

パラメータ

hDC
以前に IDirectDrawSurface7::GetDC で取得したデバイス コンテキストのハンドル。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_UNSUPPORTED

注意

このメソッドは、IDirectDrawSurface7::GetDC メソッドが呼び出されたときに、前もってロックされたサーフェスのロックも解除する。

ReleaseDC は、GetDC を呼び出す同じスレッドから呼び出す必要がある。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetDC


IDirectDrawSurface7::Restore

IDirectDrawSurface7::Restore メソッドは、消失されたサーフェスをリストアする。これは、DirectDrawSurface オブジェクトに関連付けられたサーフェス メモリを解放するときに生じる。

HRESULT Restore();

パラメータ

なし。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

注意

このメソッドは、サーフェスに割り当てられていたメモリをリストアするが、サーフェスの消失前に存在していた可能性があるビットマップは再ロードしない。詳細については、「サーフェスの消失とリストア」を参照すること。

ディスプレイ カードのモードが変更されると、またはアプリケーションでディスプレイ カードへの排他アクセスを受け取り、カードに割り当てられている現在のサーフェス メモリをすべて解放すると、サーフェスが消失する場合がある。DirectDrawSurface オブジェクトでそのサーフェス メモリが消失すると、多くのメソッドは DDERR_SURFACELOST を返し、その他あらゆる機能を実行しなくなる。IDirectDrawSurface7::Restore メソッドは、サーフェス メモリを割り当て直し、DirectDrawSurface オブジェクトに再度アタッチする。

このメソッドの単一の呼び出しを行うと、DirectDrawSurface オブジェクトの関連付けられている暗黙的なサーフェス (バック バッファなど) がリストアされる。暗黙的に作成されたサーフェスをリストアしようとすると、エラーが発生する。IDirectDrawSurface7::Restore は、IDirectDrawSurface7::AddAttachedSurface メソッドによる明示的なアタッチに対しては作用しない。つまり、これらのサーフェスは個別にリストアしなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::IsLost


IDirectDrawSurface7::SetClipper

IDirectDrawSurface7::SetClipper メソッドは、サーフェスにクリッパー オブジェクトをアタッチしたり、サーフェスからクリッパー オブジェクトを削除する。

HRESULT SetClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper
);

パラメータ

lpDDClipper
DirectDrawSurface オブジェクトにアタッチされる DirectDrawClipper オブジェクトの IDirectDrawClipper インターフェイスのアドレス。このパラメータが NULL の場合、現在の DirectDrawClipper オブジェクトはアタッチを解除される。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOCLIPPERATTACHED

注意

クリッパーを最初にサーフェスに設定するときに、このメソッドはクリッパーの参照カウントをインクリメントする。つまり、その後の呼び出しはクリッパーの参照カウントに影響しない。IpDDClipper パラメータとして NULL を渡すと、クリッパーはサーフェスから削除され、クリッパーの参照カウントがデクリメントされる。クリッパーを削除していない場合、サーフェス自体が解放されるときに、サーフェスによってクリッパーへの参照が自動的に解放される。COM 規則により、オブジェクトが不要になると、アプリケーションではクリッパーに対して保持しているあらゆる参照を解放する必要がある。

このメソッドは、プライマリ サーフェスにオーバーレイされるか、ブリットされるサーフェスにより主に使用される。ただし、このメソッドは、どのサーフェス上でも使用できる。DirectDrawClipper オブジェクトがアタッチされ、そこにクリップ リストが関連付けられると、その DirectDrawClipper オブジェクトは親の DirectDrawSurface オブジェクトを含む IDirectDrawSurface7::Blt、IDirectDrawSurface7::BltBatch、および IDirectDrawSurface7::UpdateOverlay 処理で使用される。このメソッドは、また、DirectDrawSurface オブジェクトの現在の DirectDrawClipper オブジェクトのアタッチも解除できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetClipper


IDirectDrawSurface7::SetColorKey

IDirectDrawSurface7::SetColorKey メソッドは、ハードウェアがサーフェス基準ごとにカラー キーをサポートする場合、DirectDrawSurface オブジェクトに対するカラー キー値を設定する。

HRESULT SetColorKey(
  DWORD dwFlags,
  LPDDCOLORKEY lpDDColorKey
);

パラメータ

dwFlags
要求されるカラー キーを決定する。以下のフラグが定義されている。
DDCKEY_COLORSPACE
色空間 を含む構造体。構造体に単一のカラー キーがある場合は設定しない。
DDCKEY_DESTBLT
ブリット処理の転送先カラー キーとして使用するカラー キーまたは色空間。
DDCKEY_DESTOVERLAY
オーバーレイ処理の転送先カラー キーとして使用するカラー キーまたは色空間。
DDCKEY_SRCBLT
ブリット処理の転送元カラー キーとして使用するカラー キーまたは色空間。
DDCKEY_SRCOVERLAY
オーバーレイ処理の転送元カラー キーとして使用するカラー キーまたは色空間。
lpDDColorKey
DirectDrawSurface オブジェクトの新しいカラー キー値を含む DDCOLORKEY 構造体のアドレス。前もって設定したカラー キーを削除するには、この値を NULL にする。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOOVERLAYHW
DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

透過型ブリットおよびオーバーレイに対して、転送先サーフェスの転送先の色および転送元サーフェスの転送元の色を設定すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetColorKey


IDirectDrawSurface7::SetLOD

IDirectDrawSurface7::SetLOD メソッドは、管理ミップマップ サーフェスの最大詳細レベルを設定する。このメソッドは、管理下のテクスチャに対してのみ成功する (「注意」参照)。

HRESULT SetLOD(
    DWORD dwMaxLOD
);
dwMaxLOD
呼び出しが成功した場合に、ミップマップ チェーンに設定する最大詳細レベルの値。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下の値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

アプリケーションでは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE フラグで作成されたもの) に対してのみ、このメソッドを呼び出すことができる。非管理下のテクスチャに対してこのメソッドを呼び出すと、メソッドは失敗し、DDERR_INVALIDOBJECT を返す。

このメソッドは、ローカル ビデオ メモリにロードするこのチェーンの中で最も詳細なミップマップを Direct3D テクスチャ マネージャに通知する。たとえば、5 レベルのミップマップ チェーンにおいて dwMaxLOD を 2 に設定すると、テクスチャ マネージャは指定時間になるとレベル 2 から 4 のミップマップのみローカル ビデオ メモリにロードする。同様に、チェーンの中で最も詳細なミップマップの大きさが 256 × 256 の場合、最大レベルを 2 に設定すると、これまでにビデオ メモリ内にある最大のミップマップは 64 × 64 であることを示すことになる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetLOD、ミップマップによるテクスチャ フィルタリング、自動テクスチャ管理、テクスチャ


IDirectDrawSurface7::SetOverlayPosition

IDirectDrawSurface7::SetOverlayPosition メソッドは、オーバーレイ サーフェスのディスプレイ座標を変更する。

HRESULT SetOverlayPosition(
  LONG lX,
  LONG lY
);

パラメータ

lX、lY
新しい x ディスプレイ座標と y ディスプレイ座標。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetOverlayPosition、IDirectDrawSurface7::UpdateOverlay


IDirectDrawSurface7::SetPalette

IDirectDrawSurface7::SetPalette メソッドは、サーフェスにパレット オブジェクトをアタッチする (または、サーフェスからそのアタッチを解除する)。サーフェスは、すべての連続する処理にこのパレットを使用する。パレットの変更は、リフレッシュ タイミングに関係なく即座に行われる。

HRESULT SetPalette(
  LPDIRECTDRAWPALETTE lpDDPalette
);

パラメータ

lpDDPalette
このサーフェスととも使用されるパレット オブジェクトの IDirectDrawPalette インターフェイスのアドレス。このパラメータが NULL の場合、現在のパレットはアタッチを解除される。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_SURFACELOST
DDERR_UNSUPPORTED

注意

パレットを最初にサーフェスに設定するときに、このメソッドはパレットの参照カウントをインクリメントする。つまり、その後の呼び出しはパレットの参照カウントに影響しない。IpDDPalette パラメータとして NULL を渡すと、パレットはサーフェスから削除され、そのパレットの参照カウントはデクリメントされる。パレットを削除していない場合、サーフェス自体が解放されるときに、サーフェスによってパレットへの参照が自動的に解放される。COM 規則により、オブジェクトが不要になると、アプリケーションではパレットに対して保持しているあらゆる参照を解放する必要がある。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetPalette、IDirectDraw7::CreatePalette


IDirectDrawSurface7::SetPriority

IDirectDrawSurface7::GetPriority メソッドは、このテクスチャのテクスチャ管理優先順位を割り当てる。このメソッドは、管理下のテクスチャに対してのみ成功する (「注意」参照)。

HRESULT SetPriority(
  DWORD dwPriority
);

パラメータ

dwPriority
テクスチャの新しいテクスチャ管理優先順位を指定する値。

戻り値

成功すれば、D3D_OK を返す。

失敗すれば、メソッドはエラーを返す。パラメータが無効な場合、またはテクスチャが Direct3D で管理されていない場合、メソッドは DDERR_INVALIDOBJECT を返す。

注意

このメソッドは、IDirectDrawSurface7 インターフェイスによって導入された。

優先順位を使用して、管理下のテクスチャをメモリからいつ削除するかを決定できる。優先順位が低いテクスチャは、優先順位が高いテクスチャより先に削除される。2 つのテクスチャの優先順位が同じ場合は、最終使用時が新しい方のテクスチャがメモリに保持され、もう一方のテクスチャが削除される。

アプリケーションでは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE フラグで作成したもの) でのみ優先順位を設定および取得できる。非管理下のテクスチャに対してこのメソッドを呼び出すと、メソッドは失敗し、DDERR_INVALIDOBJECT を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetPriority、自動テクスチャ管理、テクスチャ


IDirectDrawSurface7::SetPrivateData

IDirectDrawSurface7::SetPrivateData メソッドは、DirectDraw ではなくアプリケーションでよく使用されるサーフェスとデータを関連付ける。データは値で渡され、データとデータの複数設定は単一のサーフェスと関連付けられる。

HRESULT SetPrivateData(
  REFGUID guidTag,
  LPVOID  lpData,
  DWORD   cbSize,
  DWORD   dwFlags
);

パラメータ

guidTag
設定するプライベート データを識別するグローバル識別子の (C++) または (C) のアドレスへの参照。
lpData
サーフェスに関連付けられるデータを含むバッファのアドレス。
cbSize
バイト単位の lpData におけるバッファ サイズ。
dwFlags
渡されるデータの型を記述したり、サーフェスの変更時に無効となるデータを要求するフラグ。以下のフラグが定義されている。
(none)
フラグが指定されない場合、DirectDraw はバッファ内のデータを保持するメモリを割り当て、新しいバッファにデータをコピーする。DirectDraw によって割り当てられるバッファは、適宜自動的に解放される。
DDSPD_IUNKNOWNPOINTER
IpData のデータは、IUnknown インターフェイスへのポインタである。DirectDraw は、このインターフェイスの IUnknown::AddRef メソッドを自動的に呼び出す。このデータが不要になると、DirectDraw はこのインターフェイスの IUnknown::Release メソッドを自動的に呼び出す。
DDSPD_VOLATILE
lpData のバッファは、サーフェスに変更が加えられていない間のみ有効である。サーフェスの内容が変更されると、その後の IDirectDrawSurface7::GetPrivateData メソッドの呼び出しでは DDERR_EXPIRED が返される。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

DirectDraw は、lpData でメモリを管理しない。このバッファが動的に割り当てられた場合、呼び出し側の責任でメモリを解放する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::GetPrivateData、IDirectDrawSurface7::FreePrivateData


IDirectDrawSurface7::SetSurfaceDesc

IDirectDrawSurface7::SetSurfaceDesc メソッドは、既存のサーフェスの特性を設定する。

HRESULT SetSurfaceDesc(
  LPDDSURFACEDESC2 lpddsd2,
  DWORD dwFlags
);

パラメータ

lpddsd2
新しいサーフェス特性を含む DDSURFACEDESC2 構造体のアドレス。
dwFlags
現時点では未使用なので 0 を設定しておく。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDPARAMS
DDERR_INVALIDOBJECT
DDERR_SURFACELOST
DDERR_SURFACEBUSY
DDERR_INVALIDSURFACETYPE
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDCAPS
DDERR_UNSUPPORTED
DDERR_GENERIC

注意

現在、このメソッドは、明示的なシステムメモリ サーフェスで使用されるサーフェス データ、およびピクセル フォーマットを設定するためだけに使用できる。このメソッドを使用すると、サーフェスは以前に割り当てられたバッファからデータをコピーせずに使用できるので便利である。新しいサーフェス メモリは、クライアント アプリケーションによって割り当てられる。この場合、クライアント アプリケーションでは、その割り当ての解放も行う必要がある。詳細については、「サーフェス特性の更新」を参照すること。

このメソッドを誤って使用すると、予測不可能な動作が生じる。DirectDrawSurface オブジェクトは、そのオブジェクト自体で割り当てていないサーフェス メモリの割り当て解除は行わない。したがって、サーフェス メモリが必要なくなると、開発者がその割り当てを解除しなくてはならない。ただし、このメソッドが呼び出される場合、DirectDraw はサーフェスの作成時に暗に割り当てた元のサーフェス メモリを解放する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::Unlock

IDirectDrawSurface7::Unlock メソッドは、DirectDraw に直接サーフェス処理が完了したことを通知する。

HRESULT Unlock(
  LPRECT lpRect
);

パラメータ

lpRect
IDirectDrawSurface7::Lock メソッドへの対応する呼び出しで、サーフェスをロックするために使用した RECT 構造体のアドレス。IDirectDrawSurface7::Lock メソッドへの対応する呼び出しの lpDestRect パラメータに NULL を渡すことにより、サーフェス全体をロックした場合にかぎり、このパラメータは NULL となる。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOTLOCKED
DDERR_SURFACELOST

注意

異なる転送先矩形のある同じサーフェスに対する IDirectDrawSurface7::Lock の呼び出しは複数回可能なため、lpRect のポインタは IDirectDrawSurface7::Lock および IDirectDrawSurface7:Unlock メソッドの呼び出しにリンクする。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::Lock


IDirectDrawSurface7::UpdateOverlay

IDirectDrawSurface7::UpdateOverlay メソッドは、オーバーレイ サーフェスのビジュアル属性を再配置したり変更する。これらのサーフェスには、DDSCAPS_OVERLAY フラグを設定する必要がある。

HRESULT UpdateOverlay(
  LPRECT lpSrcRect,
  LPDIRECTDRAWSURFACE7 lpDDDestSurface,
  LPRECT lpDestRect,
  DWORD dwFlags,
  LPDDOVERLAYFX lpDDOverlayFx
);

パラメータ

lpSrcRect
オーバーレイとして使用される転送元サーフェスの領域の x、y、幅、および高さを定義する RECT 構造体のアドレス。このパラメータは、オーバーレイを隠蔽する場合や、オーバーレイ サーフェス全体を使用し、かつオーバーレイ サーフェスがデバイス ドライバからの境界およびサイズアライメント制限にも従うことを示す場合に、NULL とする。
lpDDDestSurface
オーバーレイが適用されるサーフェスの IDirectDrawSurface7 インターフェイスのアドレス。
lpDestRect
オーバーレイを移動する転送先サーフェスの領域の x、y、幅、および高さを定義する RECT 構造体のアドレス。このパラメータは、オーバーレイを隠蔽する場合に NULL となる。
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_ARGBSCALEFACTORS
DirectX 7.0 で追加。DDOVERLAYFX 構造体が有効な ARGB スケーリング係数を含むことを示す。
DDOVER_AUTOFLIP
ビデオ ポート VSYNC が発生するたびに、フリッピング チェーンの次のサーフェスを自動的にフリップする。
DDOVER_BOB
インターレイス ビデオ ストリームの個々のフィールドを異常なく個別に表示する。
DDOVER_BOBHARDWARE
BOB 処理は、ソフトウェアまたはエミュレートではなく、ハードウェアを使用して実行される。このフラグは、DDOVER_BOB フラグと共に使用しなくてはならない。
DDOVER_DDFX
IpDDOverlayFx パラメータでオーバーレイ FX フラグを使い、特殊なオーバーレイ エフェクトを定義する。
DDOVER_DEGRADEARGBSCALING
DirectX 7.0 で追加。ARGB スケーリング係数は、ドライバ能力に適合するように下げられる場合がある。
DDOVER_HIDE
このオーバーレイをオフにする。
DDOVER_INTERLEAVED
サーフェス メモリは、インターリーブされたフィールドから成る。
DDOVER_KEYDEST
転送先サーフェスに関連付けられているカラー キーを使用する。
DDOVER_KEYDESTOVERRIDE
転送先サーフェスのカラー キーとして、DDOVERLAYFX 構造体の dckDestColorkey メンバを使用する。
DDOVER_KEYSRC
転送元サーフェスに関連付けられているカラー キーを使用する。
DDOVER_KEYSRCOVERRIDE
転送元サーフェスのカラー キー として、DDOVERLAYFX 構造体の dckSrcColorkey メンバを使用する。
DDOVER_OVERRIDEBOBWEAVE
BOB/WEAVE 決定を、ほかのインターフェイスでオーバーライドしてはならない。
DDOVER_REFRESHALL
エミュレートされたオーバーレイ サーフェスにサーフェス全体を再描画する。
DDOVER_REFRESHDIRTYRECTS
エミュレートされたオーバーレイ サーフェスにすべてのダーティー矩形を再描画する。
DDOVER_SHOW
このオーバーレイをオンにする。
lpDDOverlayFx
使用するエフェクトを記述する DDOVERLAYFX 構造体のアドレス。DDOVER_DDFX フラグを指定しない場合は NULL にできる。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_DEVICEDOESNTOWNSURFACE
DDERR_GENERIC
DDERR_HEIGHTALIGN
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOSTRETCHHW
DDERR_NOTAOVERLAYSURFACE
DDERR_OUTOFCAPS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_XALIGN

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。


IDirectDrawSurface7::UpdateOverlayDisplay

IDirectDrawSurface7::UpdateOverlayDisplay メソッドは、現時点では実装されていない。

HRESULT UpdateOverlayDisplay(
  DWORD dwFlags
);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::AddOverlayDirtyRect


IDirectDrawSurface7::UpdateOverlayZOrder

IDirectDrawSurface7::UpdateOverlayZOrder メソッドは、オーバーレイの z オーダーを設定する。

HRESULT UpdateOverlayZOrder(
  DWORD dwFlags,
  LPDIRECTDRAWSURFACE7 lpDDSReference
);

パラメータ

dwFlags
以下のフラグのうち、1 つの値を取る。
DDOVERZ_INSERTINBACKOF
このオーバーレイをオーバーレイ チェーンの参照オーバーレイの後ろに挿入する。
DDOVERZ_INSERTINFRONTOF
このオーバーレイをオーバーレイ チェーンの参照オーバーレイの前に挿入する。
DDOVERZ_MOVEBACKWARD
このオーバーレイをオーバーレイ チェーンの 1 つ後ろに移動する。
DDOVERZ_MOVEFORWARD
このオーバーレイをオーバーレイ チェーンの 1 つ前に移動する。
DDOVERZ_SENDTOBACK
このオーバーレイをオーバーレイ チェーンの後ろに移動する。
DDOVERZ_SENDTOFRONT
このオーバーレイをオーバーレイ チェーンの前に移動する。
lpDDSReference
オーバーレイ チェーンの相対位置として使用される DirectDraw サーフェスの IDirectDrawSurface7 構造体のアドレス。このパラメータは、DDOVERZ_INSERTINBACKOF および DDOVERZ_INSERTINFRONTOF だけのために必要とされる。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTAOVERLAYSURFACE

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。

参照

IDirectDrawSurface7::EnumOverlayZOrders


IDirectDrawVideoPort

アプリケーションは、ライブ ビデオ データをハードウェア ビデオポートから DirectDraw サーフェスにチャネルするために、IDirectDrawVideoPort インターフェイスのメソッドを利用する。ここでは、このインターフェイスのメソッドのリファレンスを提供する。概念の概要については、「ビデオ ポート」を参照すること。

IDirectDrawVideoPort インターフェイスのメソッドは、以下のグループにまとめることができる。

カラー コントロール | GetColorControls
 | SetColorControls
フィールドと信号 | GetFieldPolarity
 | GetVideoSignalStatus
フリッピング | Flip
 | SetTargetSurface
フォーマット | GetInputFormats
 | GetOutputFormats
タイミングと同期 | GetVideoLine
 | WaitForSync
ビデオ コントロール | StartVideo
 | StopVideo
 | UpdateVideo
ズーム係数 | GetBandwidthInfo

すべての COM インターフェイスと同様、IDirectDrawVideoPort インターフェイスは IUnknown インターフェイスメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWVIDEOPORT データ型を使用すると、IDirectDrawVideoPort インターフェイスへのポインタを含む変数を宣言できる。dvp.h ヘッダー ファイルは、次のコードで LPDIRECTDRAWVIDEOPORT を宣言する。

typedef struct IDirectDrawVideoPort    FAR *LPDIRECTDRAWVIDEOPORT;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::Flip

IDirectDrawVideoPort::Flip メソッドは、新しいサーフェスにビデオの次のフレームを記述するよう DirectDrawVideoPort オブジェクトに指示する。

HRESULT Flip(
  LPDIRECTDRAWSURFACE lpDDSurface,
  DWORD dwFlags
);

パラメータ

lpDDSurface
ビデオの次のフレームを受け取るサーフェスの IDirectDrawSurface インターフェイスのアドレス。このパラメータに NULL を設定すると、サーフェスがアタッチされた順にフリッピング チェーンのサーフェスから循環する。
dwFlags
フリップ オプション フラグ。以下のフラグのうち、いずれかの値を取る。
DDVPFLIP_VIDEO
指定したサーフェスは通常のビデオ データを受け取る。
DDVPFLIP_VBI
指定したサーフェスが垂直帰線消去間隔内のデータだけを受け取る。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、テアリングを防ぐために使用できる。IDirectDrawVideoPort::Flip への呼び出しは非同期である。フリップ処理は、ビデオ信号の垂直帰線消去と常に同期される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::GetBandwidthInfo

IDirectDrawVideoPort::GetBandwidthInfo メソッドは、要求される最小オーバーレイ ズーム係数と、提供される出力ピクセル フォーマットを使うビデオ ポートのデバイス制限を取得する。

HRESULT GetBandwidthInfo(
  LPDDPIXELFORMAT lpddpfFormat,
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwFlags,
  LPDDVIDEOPORTBANDWIDTH lpBandwidth
);

パラメータ

lpddpfFormat
帯域幅情報を取得するための出力ピクセル フォーマットを記述する DDPIXELFORMAT 構造体のアドレス。
dwWidth、dwHeight
オーバーレイまたはビデオ データのディメンジョン。これらのパラメータは、dwFlags パラメータで指定する値に依存する。
dwFlags
どのようにメソッドが dwWidth および dwHeight パラメータを判断するかを示すフラグ。以下のフラグのうち、いずれかの値を取る。
DDVPB_OVERLAY
dwWidth および dwHeight パラメータは、転送元オーバーレイ サーフェスのサイズを示す。ビデオ ポートがオーバーレイ転送元サイズに依存する場合、このフラグを使用する。
DDVPB_TYPE
dwWidth および dwHeight パラメータは、設定されない。メソッドは、関連付けられた DDVIDEOPORTBANDWIDTH 構造体の dwCaps メンバでデバイスの依存タイプを取得する。最初にこのメソッドを呼び出す場合、このフラグを使用する。
DDVPB_VIDEOPORT
dwWidth および dwHeight パラメータは、ビデオ ポートがフレーム バッファに書き込むビデオ データのプレスケール サイズを示す。ビデオ ポートがオーバーレイ ズーム係数に依存する場合、このフラグを使用する。
lpBandwidth
取得された帯域幅およびデバイス情報を格納する DDVIDEOPORTBANDWIDTH 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは通常 2 回呼び出される。最初に呼び出す場合、dwFlags パラメータに DDVPB_TYPE フラグを指定して、デバイスのオーバーレイ依存タイプについての情報を取得する。DDVPB_VIDEOPORT または DDVPB_OVERLAY フラグを使った連続する呼び出しは、デバイスの依存タイプを考慮して判断されなくてはならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::GetColorControls

IDirectDrawVideoPort::GetColorControls メソッドは、ビデオ ポートに関連付けられた現在のカラー コントロール設定を返す。

HRESULT GetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

パラメータ

lpColorControl
ビデオ ポートのカラー コントロールにおける現在の設定を格納する DDCOLORCONTROL 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

注意

DDCOLORCONTROL 構造体の dwFlags メンバは、サポートされるカラー コントロール オプションを示す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::GetFieldPolarity

IDirectDrawVideoPort::GetFieldPolarity メソッドは、ビデオ フィールドの極性を取得する。

HRESULT GetFieldPolarity(
  LPBOOL lpbFieldPolarity
);

パラメータ

lpbFieldPolarity
現在のフィールド極性を示すために設定する変数のアドレス。現在のビデオ フィールドがインターレイス ビデオ信号の偶数フィールドである場合、この値を TRUE に設定する。その他の場合は、この値を FALSE に設定する。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VIDEONOTACTIVE

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::GetInputFormats

IDirectDrawVideoPort::GetInputFormats メソッドは、DirectDrawVideoPort オブジェクトがサポートする入力フォーマットを取得する。

HRESULT GetInputFormats(
  LPDWORD lpNumFormats,
  LPDDPIXELFORMAT lpFormats,
  DWORD dwFlags
);

パラメータ

lpNumFormats
lpFormats の配列で保持できるエントリ数を含む変数のアドレス。この数が全コード数より少ない場合、メソッドは適合するすべてのコードを配列に格納し、全コード数を示すように lpNumFormats の値を設定して、DDERR_MOREDATA を返す。
lpFormats
この DirectDrawVideoPort オブジェクトによってサポートされる入力情報を格納する DDPIXELFORMAT 構造体の配列のアドレス。このパラメータが NULL の場合、メソッドは lpNumFormats をサポートされるフォーマット数に設定して、DD_OK を返す。
dwFlags
ビデオ信号のどの部分に対してフォーマットを列挙するかを指定するフラグ。以下のフラグのうち、いずれかの値を取る。
DDVPFORMAT_VIDEO
ビデオ データのフォーマットを返す。
DDVPFORMAT_VBI
VBI データのフラグを返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

注意

このメソッドは、サポートされるフォーマット数を返すために使用することもできる。この場合は、lpFormats パラメータを NULL に設定する。メソッドが返ると、lpNumFormats の変数にはサポートされる入力フォーマットの合計数が含まれる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::GetOutputFormats

IDirectDrawVideoPort::GetOutputFormats メソッドは、DirectDrawVideoPort オブジェクトが指定した入力フォーマットに対してサポートする、出力フォーマットのリストを取得する。

HRESULT GetOutputFormats(
  LPDDPIXELFORMAT lpInputFormat,
  LPDWORD lpNumFormats,
  LPDDPIXELFORMAT lpFormats,
  DWORD dwFlags
);

パラメータ

lpInputFormat
変換情報を要求する入力フォーマットを記述する DDPIXELFORMAT 構造体のアドレス。
lpNumFormats
lpFromats の配列で保持できるエントリ数を含む変数のアドレス。この数が全コード数より少ない場合、メソッドは適合するすべてのコードを配列に格納し、全コード数を示すように lpNumFormats の値を設定して、DDERR_MOREDATA を返す。
lpFormats
この DirectDrawVideoPort オブジェクトによってサポートされる出力フォーマットを格納する DDPIXELFORMAT 構造体のアドレス。このパラメータが NULL の場合、メソッドはサポートされるフォーマット数に lpNumFormats を設定して、DD_OK を返す。
dwFlags
ビデオ信号のどの部分に対してフォーマットを列挙するかを指定するフラグ。以下のフラグのうち、いずれかの値を取る。
DDVPFORMAT_VIDEO
ビデオ データのフォーマットを返す。
DDVPFORMAT_VBI
VBI データのフラグを返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::GetVideoLine

IDirectDrawVideoPort::GetVideoLine メソッドは、フレーム バッファに現在書き込み中のビデオ ラインを取得する。

HRESULT GetVideoLine(
  LPDWORD lpdwLine
);

パラメータ

lpdwLine
フレーム バッファに現在書込み中のビデオ ラインを示す値を格納する変数のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS
DDERR_VIDEONOTACTIVE

注意

このメソッドが取得する値は、プレスケーリングが発生する前に、フィールドの高さを取得する記述された真のビデオ ラインを反映する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::GetVideoSignalStatus

IDirectDrawVideoPort::GetVideoSignalStatus メソッドは、現在ビデオ ポートに存在するビデオ信号のステータスを取得する。

HRESULT GetVideoSignalStatus(
  LPDWORD lpdwStatus
);

パラメータ

lpdwStatus
ビデオ ポートでのビデオ信号の質を示す戻り値を含む変数のアドレス。値は、以下のコードのうちいずれかの値に設定される。
DDVPSQ_NOSIGNAL
ビデオ ポートにはビデオ信号が存在しない。
DDVPSQ_SIGNALOK
ビデオ ポートに有効なビデオ信号が存在する。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::SetColorControls

IDirectDrawVideoPort::SetColorControls メソッドは、ビデオ ポートに関連付けられたカラー コントロール設定を設定する。

HRESULT SetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

パラメータ

lpColorControl
ビデオ ポートに適用される新しいカラー コントロール設定を含む DDCOLORCONTROL 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


IDirectDrawVideoPort::SetTargetSurface

IDirectDrawVideoPort::SetTargetSurface メソッドは、ライブ ビデオ データおよび/または垂直帰線消去間隔データのストリームを受け取る DirectDraw サーフェス オブジェクトを設定する。

HRESULT SetTargetSurface(
  LPDIRECTDRAWSURFACE lpDDSurface,
  DWORD dwFlags
);

パラメータ

lpDDSurface
ビデオ データを受け取る DirectDrawSurface オブジェクトのアドレス。
dwFlags
ターゲット サーフェスのタイプを指定する値。以下のフラグのうち、1 つの値を取る。
DDVPTARGET_VIDEO
指定するサーフェスは、この目的のために別々のサーフェスがアタッチされていなければ、通常のビデオ データと垂直帰線消去間隔データを受け取る。
DDVPTARGET_VBI
指定するサーフェスは、垂直帰線消去間隔内のデータを受け取る。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawVideoPort::StartVideo、IDirectDrawVideoPort::StopVideo、IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::StartVideo

IDirectDrawVideoPort::StartVideo メソッドは、ハードウェア ビデオ ポートを利用可能にして、現在指定されているサーフェスにビデオ データのフローを開始する。

HRESULT StartVideo(
  LPDDVIDEOPORTINFO lpVideoInfo
);

パラメータ

lpVideoInfo
DDVIDEOPORTINFO 構造体へのポインタのアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawVideoPort::SetTargetSurface、IDirectDrawVideoPort::StopVideo、IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::StopVideo

IDirectDrawVideoPort::StopVideo メソッドは、フレーム バッファへのビデオポート データのフローを止める。

HRESULT StopVideo();

パラメータ

なし。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、メソッドは DDERR_INVALIDOBJECT を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawVideoPort::SetTargetSurface、IIDirectDrawVideoPort::StartVideo、IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::UpdateVideo

IDirectDrawVideoPort::UpdateVideo メソッドは、ビデオ ポートから DirectDrawSurface オブジェクトまでのビデオ データのフローを制御するパラメータを更新する。

HRESULT UpdateVideo(
  LPDDVIDEOPORTINFO lpVideoInfo
);

パラメータ

lpVideoInfo
ビデオ転送パラメータを記述する DDVIDEOPORTINFO 構造体のアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDrawVideoPort::SetTargetSurface、IDirectDrawVideoPort::StartVideo、IDirectDrawVideoPort::StopVideo


IDirectDrawVideoPort::WaitForSync

IDirectDrawVideoPort::WaitForSync メソッドは、VSYNC、または与えられた走査線を描くまで待機する。

HRESULT WaitForSync(
  DWORD dwFlags,
  DWORD dwLine,
  DWORD dwTimeout
);

パラメータ

dwFlags
メソッドがビデオ VSYNC または指定されたライン番号をどのように待機するかを指定するフラグ。以下のフラグのうち、いずれかの値を取る。
DDVPWAIT_BEGIN
垂直帰線消去間隔の開始時に返す。
DDVPWAIT_END
垂直帰線消去間隔の終了時に返す。
DDVPWAIT_LINE
ビデオ カウンタが、dwLine パラメータで指定されたラインに達するか超えるときに返す。
dwLine
プレスケーリングの前に、フィールドの高さを基準にしていつメソッドが返るかを決定するビデオ ライン。dwFlags パラメータが DDVPWAIT_BEGIN または DDVPWAIT_END に設定されている場合、このパラメータは無視される。
dwTimeout
タイムアウトするまでに、メソッドが次のビデオ垂直帰線消去を待機する時間 (ミリ秒)。このパラメータが 0 の場合、メソッドは DDVIDEOPORTDESC の dwMicrosecondsPerField メンバに指定された値の 3 倍の時間待機する。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VIDEONOTACTIVE
DDERR_WASSTILLDRAWING

注意

このメソッドは、呼び出し側が垂直帰線消去間隔、またはビデオ データの任意のラインと同期するのを手伝う。このメソッドは、ビデオ VSYNC が発生するか、またはビデオ ライン カウンタが指定のライン番号に一致するまでスレッドの呼び出しをブロックする。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


関数

ここでは、以下に示す DirectDraw グローバル関数について説明する。

  • DirectDrawCreate
  • DirectDrawCreateEx
  • DirectDrawCreateClipper
  • DirectDrawEnumerate
  • DirectDrawEnumerateEx


DirectDrawCreate

DirectDrawCreate 関数は、DirectDraw オブジェクトのインスタンスを作成する。この関数で作成した DirectDraw オブジェクトでは、最新の Direct3D インターフェイス セットはサポートされない。Direct3D の新機能を公開できる DirectDraw オブジェクトを作成するには、DirectDrawCreateEx 関数を使用する。

HRESULT WINAPI DirectDrawCreate(
  GUID FAR *lpGUID,
  LPDIRECTDRAW FAR *lplpDD,
  IUnknown FAR *pUnkOuter
);

パラメータ

lpGUID
作成されるドライバを表すグローバル ユニーク識別子 (GUID) のアドレス。アクティブ ディスプレイ ドライバを示すには、このパラメータを NULL にする。あるいは、デバッグのためにディスプレイ ドライバの動作を制御するには、以下のフラグの 1 つを渡すことができる。
DDCREATE_EMULATIONONLY
DirectDraw オブジェクトは、すべての機能にエミュレーションを使用する。つまり、ハードウェアサポート機能は利用しない。
DDCREATE_HARDWAREONLY
DirectDraw オブジェクトは、ハードウェアによってサポートされていない機能をエミュレートしない。サポートされていない機能を要求するメソッドを呼び出そうとすると失敗し、DDERR_UNSUPPORTED が返される。
lplpDD
呼び出しが成功した場合に、有効な IDirectDraw インターフェイス ポインタに設定する変数のアドレス。
pUnkOuter
COM 処理機能との将来的な互換のためにある。ただし、現時点では、このパラメータを NULL に設定しないと、このメソッドはエラーを返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_OUTOFMEMORY

注意

この関数は、DirectDraw オブジェクトを初期化しようとする。呼び出しが成功すると、オブジェクトへのポインタを設定する。

マルチ モニタのシステムで lpGUID に NULL を指定すると、標準協調レベルが設定されている場合に、DirectDraw はエミュレーション モードで実行する。これらのシステムでハードウェア アクセラレータを使用するには、デバイスの GUID を指定する。詳細については、「MultiMon システムのデバイスとアクセラレータ」を参照すること。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


DirectDrawCreateEx

DirectDrawCreateEx 関数は、最新の Direct3D インターフェイス セットをサポートする DirectDraw オブジェクトのインスタンスを作成する。DirectX 7.0 で Direct3D の新機能を使用するには、この関数で DirectDraw オブジェクトを作成する。DirectDraw および Direct3D 間の関係の詳細については、「DirectDraw オブジェクトと Direct3D」および「Direct3D へのアクセス」を参照すること。

HRESULT WINAPI DirectDrawCreateEx(
  GUID FAR *lpGUID,
  LPVOID *lplpDD,
  REFIID iid,
  IUnknown FAR *pUnkOuter
);

パラメータ

lpGUID
作成されるドライバを表すグローバル ユニーク識別子 (GUID) のアドレス。アクティブ ディスプレイ ドライバを示すには、このパラメータを NULL にする。また、デバッグのためにディスプレイ ドライバの動作を制御するには、以下のフラグのいずれかを渡すことができる。
DDCREATE_EMULATIONONLY
DirectDraw オブジェクトは、すべての機能にエミュレーションを使用する。つまり、ハードウェアサポート機能は利用しない。
DDCREATE_HARDWAREONLY
DirectDraw オブジェクトは、ハードウェアによってサポートされていない機能をエミュレートしない。サポートされていない機能を要求するメソッドを呼び出そうとすると失敗し、DDERR_UNSUPPORTED が返される。
lplpDD
呼び出しが成功した場合に、有効な IDirectDraw7 インターフェイス ポインタに設定する変数のアドレス。
iid
このパラメータは IID_IDirectDraw7 に設定しなければならない。その他のインターフェイスを指定した場合、この関数は失敗し、DDERR_INVALIDPARAMS を返す。
pUnkOuter
COM 処理機能との将来的な互換のためにある。ただし、現時点では、このパラメータを NULL に設定しないと、このメソッドはエラーを返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_OUTOFMEMORY

注意

この関数は、DirectDraw オブジェクトを初期化しようとする。呼び出しが成功すると、オブジェクトへのポインタを設定する。

マルチ モニタのシステムで lpGUID に NULL を指定すると、標準協調レベルが設定されている場合に、DirectDraw オブジェクトはエミュレーション モードで実行する。これらのシステムでハードウェア アクセラレータを使用するには、デバイスの GUID を指定する。詳細については、「MultiMon システムのデバイスとアクセラレータ」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。


DirectDrawCreateClipper

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

HRESULT WINAPI DirectDrawCreateClipper(
  DWORD dwFlags,
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper,
  IUnknown FAR *pUnkOuter
);

パラメータ

dwFlags
現時点では未使用なので 0 を設定しておく。
lplpDDClipper
新しい DirectDrawClipper オブジェクトのアドレスを格納するポインタのアドレス。
pUnkOuter
COM 処理機能との将来的な互換のためにある。ただし、現時点では、このパラメータを NULL に設定しないと、このメソッドはエラーを返す。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、以下のエラー値のいずれかを返す。

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

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

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

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

IDirectDraw7::CreateClipper


DirectDrawEnumerate

この関数は、DirectDrawEnumerateEx 関数で置き換えられる。

DirectDrawEnumerate 関数は、システムにインストールされているプライマリ DirectDraw ディスプレイ デバイス、および非ディスプレイ デバイス (2D 能力がない 3D アクセラレートなど) を列挙する。NULL エントリは、GDI で共有されるプライマリ ディスプレイ デバイスを常に識別する。

HRESULT WINAPI DirectDrawEnumerate(
  LPDDENUMCALLBACK lpCallback,
  LPVOID lpContext
);

パラメータ

lpCallback
列挙される個々の DirectDraw で有効なハードウェア アブストラクション レイヤ (HAL) の記述で呼び出される DDEnumCallback 関数のアドレス。
lpContext
列挙コールバック関数を呼び出すごとに渡されるアプリケーション定義コンテキストのアドレス。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、DDERR_INVALIDPARAMS を返す。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。

参照

DirectDrawEnumerateEx


DirectDrawEnumerateEx

DirectDrawEnumerateEx 関数は、システム上にインストールされたすべての DirectDraw デバイスを列挙する。NULL エントリは、GDI で共有されるプライマリ ディスプレイ デバイスを常に示す。

HRESULT WINAPI DirectDrawEnumerateEx(
  LPDDENUMCALLBACKEX lpCallback,
  LPVOID lpContext,
  DWORD  dwFlags
);

パラメータ

lpCallback
列挙される個々の DirectDraw で有効なハードウェア アブストラクション レイヤ (HAL) の記述で呼び出される DDEnumCallbackEx 関数のアドレス。
lpContext
列挙コールバック関数を呼び出すごとに渡されるアプリケーション定義値のアドレス。
dwFlags
列挙有効範囲を指定するフラグ。このパラメータは、0 または以下のフラグの組み合わせとする。パラメータの値を 0 にすると、関数はプライマリ ディスプレイ デバイスのみ列挙する。
DDENUM_ATTACHEDSECONDARYDEVICES
関数は、プライマリ デバイス、およびデスクトップにアタッチされるディスプレイ デバイスを列挙する。
DDENUM_DETACHEDSECONDARYDEVICES
関数は、プライマリ デバイス、およびデスクトップにアタッチされないディスプレイ デバイスを列挙する。
DDENUM_NONDISPLAYDEVICES
関数は、プライマリ デバイス、および 2D 能力がない 3D アクセラレータなどの非ディスプレイ デバイスを列挙する。

戻り値

成功すれば、DD_OK を返す。

失敗すれば、DDERR_INVALIDPARAMS を返す。

注意

マルチ モニタのシステムでは、このメソッドはマルチ ディスプレイ デバイスを列挙する。詳細情報は、「マルチモニタ システム」を参照すること。

Windows 98 では、この関数は DirectX 5.0 以降のバージョンがサポートされる。他のオペレーティング システムすべてでは、DirectX 6.0 が必要となる。"DirectDrawEnumerateExA" (ANSI)、または "DirectDrawEnumerateExW" (Unicode) 処理名文字列で GetProcAddress Win32 関数を呼び出すことにより、ddraw.dll ダイナミックリンク ライブラリから DirectDrawEnumerateEx 関数のアドレスを取得できる。GetProcAddress が失敗した場合は、インストールされているオペレーティング システムのバージョンでマルチ モニタがサポートされていない。詳細については、「MultiMon システムにおけるデバイスの列挙」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ddraw.lib を使用。
Unicode : Windows NT/2000 上の Unicode および ANSI バージョンとして実装される。


コールバック関数

ここでは、DirectDraw と共に使用される以下のコールバック関数について説明する。

  • DDEnumCallback
  • DDEnumCallbackEx
  • EnumModesCallback
  • EnumModesCallback2
  • EnumSurfacesCallback
  • EnumSurfacesCallback2
  • EnumSurfacesCallback7
  • EnumVideoCallback


DDEnumCallback

DDEnumCallback 関数は、DirectDrawEnumerate 関数のアプリケーション定義コールバック関数である。

BOOL WINAPI DDEnumCallback(
  GUID FAR *lpGUID,
  LPSTR  lpDriverDescription,
  LPSTR  lpDriverName,
  LPVOID lpContext
);

パラメータ

lpGUID
DirectDraw オブジェクトのユニーク識別子のアドレス。
lpDriverDescription
ドライバ記述を含む文字列のアドレス。
lpDriverName
ドライバ名を含む文字列のアドレス。
lpContext
関数を呼び出すごとにコールバック関数に渡されるアプリケーション定義構造体のアドレス。

戻り値

コールバック関数は、ゼロ以外の値を返して列挙を続行する。

コールバック関数は、ゼロを返して列挙を停止する。

注意

LPDDENUMCALLBACK データ型を使用すると、このコールバック関数へのポインタを含む変数を宣言できる。

UNICODE が定義されると、文字列値は LPSTR ではなく LPWSTR 型として返される。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ユーザー定義。


DDEnumCallbackEx

DDEnumCallbackEx 関数は、DirectDrawEnumerateEx 関数のアプリケーション定義コールバック関数である。

BOOL WINAPI DDEnumCallbackEx(
  GUID FAR *lpGUID,
  LPSTR     lpDriverDescription,
  LPSTR     lpDriverName,
  LPVOID    lpContext,
  HMONITOR  hm
);

パラメータ

lpGUID
DirectDraw オブジェクトのユニーク識別子のアドレス。
lpDriverDescription
ドライバ記述を含む文字列のアドレス。
lpDriverName
ドライバ名を含む文字列のアドレス。
lpContext
関数を呼び出すごとにコールバック関数に渡されるアプリケーション定義構造体のアドレス。
hm
列挙する DirectDraw オブジェクトに関連付けられたモニタへのハンドル。列挙する DirectDraw オブジェクトがプライマリ デバイス、非ディスプレイ デバイス (2D 能力がない 3D アクセラレータなど)、またはデスクトップにアタッチされないデバイスである場合、このパラメータは NULL となる。

戻り値

コールバック関数は、ゼロ以外の値を返して列挙を続行する。

コールバック関数は、ゼロを返して列挙を停止する。

注意

DirectDrawEnumerateEx 関数が完了すると、GUID へのポインタは有効ではなくなる。ポインタではなく、GUID 構造体そのもののコピーを保存しなければならない。そうでないと、DirectDrawCreate 関数が失敗する。

LPDDENUMCALLBACKEX データ型を使用すると、このコールバック関数へのポインタを含む変数を宣言できる。

UNICODE が定義されると、文字列値は LPSTR ではなく LPWSTR 型として返される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ユーザー定義。

参照

MultiMon システムにおけるデバイスの列挙、マルチモニタ システム


EnumModesCallback

EnumModesCallback 関数は、IDirectDraw3::EnumDisplayModes 関数のためのアプリケーションで定義されるコールバック関数である。また、以前のインターフェイスに対応する。

このコールバック関数は、IDirectDraw7::EnumDisplayModes メソッドととも使用される EnumModesCallback2 関数によって置き換えられる。

HRESULT WINAPI EnumModesCallback(
  LPDDSURFACEDESC lpDDSurfaceDesc,
  LPVOID lpContext
);

パラメータ

lpDDSurfaceDesc
モニタ周波数および作成するモードを提供する読み込み専用の DDSURFACEDESC 構造体のアドレス。
lpContext
関数を呼び出すごとにコールバック関数に渡されるアプリケーション定義構造体のアドレス。

戻り値

コールバック関数は、DDENUMRET_OK を返して列挙を続行する。

コールバック関数は、DDENUMRET_CANCEL を返して列挙を停止する。

注意

LPDDENUMMODESCALLBACK データ型を使用すると、このコールバック関数へのポインタを含む変数を宣言できる。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ユーザー定義。


EnumModesCallback2

EnumModesCallback2 関数は、IDirectDraw7::EnumDisplayModes メソッドのアプリケーション定義コールバック関数である。

HRESULT WINAPI EnumModesCallback2(
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  LPVOID lpContext
);

パラメータ

lpDDSurfaceDesc
モニタ周波数および作成するモードを提供する読み込み専用の DDSURFACEDESC2 構造体のアドレス。
lpContext
関数を呼び出すごとにコールバック関数に渡されるアプリケーション定義構造体のアドレス。

戻り値

コールバック関数は、DDENUMRET_OK を返して列挙を続行する。

コールバック関数は、DDENUMRET_CANCEL を返して列挙を停止する。

注意

LPDDENUMMODESCALLBACK2 データ型を使用すると、このコールバック関数へのポインタを含む変数を宣言できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ユーザー定義。


EnumSurfacesCallback

EnumSurfacesCallback 関数は、IDirectDraw2::EnumSurfaces、IDirectDrawSurface3::EnumAttachedSurfaces、および IDirectDrawSurface3::EnumOverlayZOrders メソッド (そして、初期のインターフェイス バージョン) のためのアプリケーションで定義されるコールバック関数である。

HRESULT WINAPI EnumSurfacesCallback(
  LPDIRECTDRAWSURFACE lpDDSurface,
  LPDDSURFACEDESC lpDDSurfaceDesc,
  LPVOID lpContext
);

パラメータ

lpDDSurface
アタッチされるサーフェスに対する IDirectDrawSurface インターフェイスのアドレス。
lpDDSurfaceDesc
アタッチされるサーフェスを記述する DDSURFACEDESC 構造体のアドレス。
lpContext
関数を呼び出すごとにコールバック関数に渡されるアプリケーション定義構造体のアドレス。

戻り値

コールバック関数は、DDENUMRET_OK を返して列挙を続行する。

コールバック関数は、DDENUMRET_CANCEL を返して列挙を停止する。

注意

LPDDENUMSURFACESCALLBACK データ型を使用すると、このコールバック関数へのポインタを含む変数を宣言できる。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ユーザー定義。


EnumSurfacesCallback2

EnumSurfacesCallback2 関数は、IDirectDrawSurface4::EnumAttachedSurfaces および IDirectDrawSurface4::EnumOverlayZOrders メソッドのアプリケーション定義コールバック関数である。

HRESULT WINAPI EnumSurfacesCallback2(
  LPDIRECTDRAWSURFACE7 lpDDSurface,
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  LPVOID lpContext
);

パラメータ

lpDDSurface
アタッチされるサーフェスの IDirectDrawSurface4 インターフェイスのアドレス。
lpDDSurfaceDesc
アタッチされるサーフェスを記述する DDSURFACEDESC2 構造体のアドレス。
lpContext
関数を呼び出すごとにコールバック関数に渡されるアプリケーション定義構造体のアドレス。

戻り値

コールバック関数は、DDENUMRET_OK を返して列挙を続行する。

コールバック関数は、DDENUMRET_CANCEL を返して列挙を停止する。

注意

LPDDENUMSURFACESCALLBACK2 データ型を使用すると、このコールバック関数へのポインタを含む変数を宣言できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ユーザー定義。


EnumSurfacesCallback7

EnumSurfacesCallback7 関数は、IDirectDrawSurface7::EnumAttachedSurfaces および IDirectDrawSurface7::EnumOverlayZOrders メソッドのアプリケーション定義コールバック関数である。

HRESULT WINAPI EnumSurfacesCallback7(
  LPDIRECTDRAWSURFACE7 lpDDSurface,
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  LPVOID lpContext
);

パラメータ

lpDDSurface
アタッチされるサーフェスの IDirectDrawSurface7 インターフェイスのアドレス。
lpDDSurfaceDesc
アタッチされるサーフェスを記述する DDSURFACEDESC2 構造体のアドレス。
lpContext
関数を呼び出すごとにコールバック関数に渡されるアプリケーション定義構造体のアドレス。

戻り値

コールバック関数は、DDENUMRET_OK を返して列挙を続行する。

コールバック関数は、DDENUMRET_CANCEL を返して列挙を停止する。

注意

LPDDENUMSURFACESCALLBACK7 データ型を使用すると、このコールバック関数へのポインタを含む変数を宣言できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ユーザー定義。


EnumVideoCallback

EnumVideoCallback 関数は、IDDVideoPortContainer::EnumVideoPorts メソッドのアプリケーション定義コールバック関数である。

HRESULT WINAPI EnumVideoCallback(
  LPDDVIDEOPORTCAPS lpDDVideoPortCaps,
  LPVOID lpContext
);

パラメータ

lpDDVideoPortCaps
ID、能力などのビデオ ポート情報を含む DDVIDEOPORTCAPS 構造体へのポインタ。このデータは、読み込み専用である。
lpContext
関数を呼び出すごとにメンバに渡される、呼び出し側で定義された構造体へのポインタ。

戻り値

コールバック関数は、DDENUMRET_OK を返して列挙を続行する。

コールバック関数は、DDENUMRET_CANCEL を返して列挙を停止する。

注意

ビデオポートに関連する関数は、EnumVideoCallback 関数から呼び出すことはできない。これを呼び出そうとすると失敗し、DDERR_CURRENTLYNOTAVAIL が返される。

LPDDENUMVIDEOCALLBACK データ型を使用すると、このコールバック関数へのポインタを含む変数を宣言できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。
インポート ライブラリ : ユーザー定義。


構造体

ここでは、DirectDraw と共に使用される以下の構造体について説明する。

  • DDBLTBATCH
  • DDBLTFX
  • DDCAPS
  • DDCOLORCONTROL
  • DDCOLORKEY
  • DDDEVICEIDENTIFIER2
  • DDGAMMARAMP
  • DDOVERLAYFX
  • DDPIXELFORMAT
  • DDSCAPS
  • DDSCAPS2
  • DDSURFACEDESC
  • DDSURFACEDESC2
  • DDVIDEOPORTBANDWIDTH
  • DDVIDEOPORTCAPS
  • DDVIDEOPORTCONNECT
  • DDVIDEOPORTDESC
  • DDVIDEOPORTINFO
  • DDVIDEOPORTSTATUS

注 ：すべての DirectX 構造体におけるメモリは、使用前にゼロに初期化される。また、dwSize メンバを含むすべての構造体は、使用する前にメンバを構造体のサイズにバイト単位で設定しなければならない。以下の例は、共通の構造体 DDCAPS でこれらのタスクを実行している。

DDCAPS ddcaps; //  まだ使用不可能

ZeroMemory(&ddcaps, sizeof(DDCAPS));
ddcaps.dwSize = sizeof(DDCAPS);

//  これで、構造体が使用可能となる
.
.


DDBLTBATCH

DDBLTBATCH 構造体は、ブリット (ブロック転送) 処理を IDirectDrawSurface7::BltBatch メソッドに渡す。

typedef struct _DDBLTBATCH{
    LPRECT              lprDest;
    LPDIRECTDRAWSURFACE lpDDSSrc;
    LPRECT              lprSrc;
    DWORD               dwFlags;
    LPDDBLTFX           lpDDBltFx;
} DDBLTBATCH,FAR *LPDDBLTBATCH;

メンバ

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 構造体の dwDDROP メンバを使用する。
DDBLT_KEYDEST
転送先サーフェスに関連付けられたカラー キーを使用する。
DDBLT_KEYDESTOVERRIDE
転送先サーフェスのカラー キーとして、DDBLTFX 構造体の ddckDestColorkey メンバを使用する。
DDBLT_KEYSRC
転送元サーフェスに関連付けられたカラー キーを使用する。
DDBLT_KEYSRCOVERRIDE
転送元サーフェスのカラー キーとして、DDBLTFX 構造体の ddckSrcColorkey メンバを使用する。
DDBLT_ROP
このブリットにおける ROP に DDBLTFX 構造体の dwROP メンバを使用する。ROPs は Win32 API で定義されるものと同じである。
DDBLT_ROTATIONANGLE
サーフェスの回転角 (1/100°単位で指定) として、DDBLTFX 構造体の dwRotationAngle メンバを使用する。
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 構造体の IpDDSZBufferSrc および dwZBufferOpCode メンバによる Z バッファ ブリットを実行する。各メンバはそれぞれ転送元に対する Z バッファおよび Z バッファ オペコードとして使用する。
lpDDBltFx
追加のブリット エフェクトを指定する DDBLTFX 構造体のアドレス。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDBLTFX

DDBLTFX 構造体は、ラスタ処理 (ROPs)、エフェクト、およびオーバーライド情報を IDirectDrawSurface7::Blt メソッドに渡す。この構造体は、IDirectDrawSurface7::BltBatch メソッドと共に使用する DDBLTBATCH 構造体の一部でもある。

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;
    } DUMMYUNIONNAMEN(1);
    DWORD dwZSrcConstBitDepth;
    union
    {
        DWORD               dwZSrcConst;
        LPDIRECTDRAWSURFACE lpDDSZBufferSrc;
    } DUMMYUNIONNAMEN(2);
    DWORD dwAlphaEdgeBlendBitDepth;
    DWORD dwAlphaEdgeBlend;
    DWORD dwReserved;
    DWORD dwAlphaDestConstBitDepth;
    union
    {
        DWORD               dwAlphaDestConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaDest;
    } DUMMYUNIONNAMEN(3);
    DWORD dwAlphaSrcConstBitDepth;
    union
    {
        DWORD               dwAlphaSrcConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaSrc;
    } DUMMYUNIONNAMEN(4);
    union
    {
        DWORD               dwFillColor;
        DWORD               dwFillDepth;
        DWORD               dwFillPixel;
        LPDIRECTDRAWSURFACE lpDDSPattern;
    } DUMMYUNIONNAMEN(5);
    DDCOLORKEY ddckDestColorkey;
    DDCOLORKEY ddckSrcColorkey;
} DDBLTFX,FAR* LPDDBLTFX;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwDDFX
FX 処理のタイプ。以下の種類が定義される。
DDBLTFX_ARITHSTRETCHY
このブリットに対して、y 軸に沿って算術伸縮を使用する。
DDBLTFX_MIRRORLEFTRIGHT
y 軸上でサーフェスを回転する。このブリットは、サーフェスを左から右にミラー化する。
DDBLTFX_MIRRORUPDOWN
x 軸上でサーフェスを回転する。このブリットは、サーフェスを上から下にミラー化する。
DDBLTFX_NOTEARING
このブリットでテアリングが発生しないようにする。
DDBLTFX_ROTATE180
このブリット中に、サーフェスを時計回りに 180 度回転する。
DDBLTFX_ROTATE270
このブリット中に、サーフェスを時計回りに 270 度回転する。
DDBLTFX_ROTATE90
このブリット中に、サーフェスを時計回りに 90 度回転する。
DDBLTFX_ZBUFFERBASEDEST
この z ブリット中に、転送先 z 値と比較する前の転送元 z 値の各々に dwZBufferBaseDest メンバを追加する。
DDBLTFX_ZBUFFERRANGE
この z ブリット中に、転送元サーフェスからコピーしたビットへの限界を指定する範囲値として dwZBufferLow および dwZBufferHigh メンバを使用する。
dwROP
Win32 ラスタ処理。サポートされるラスタ処理のリストを取得するには、IDirectDraw7::GetCaps メソッドを呼び出す。
dwDDROP
DirectDraw ラスタ処理。
dwRotationAngle
ブリットにおける回転角度。
dwZBufferOpCode
Z バッファ比較。
dwZBufferLow
Z バッファの最低限界。
dwZBufferHigh
Z バッファの最高限界。
dwZBufferBaseDest
Z バッファの転送先基底値。
dwZDestConstBitDepth
転送先 z 定数のビット深度。
dwZDestConst
転送先 Z バッファとして使用する定数。
lpDDSZBufferDest
転送先 Z バッファとして使用するサーフェス。
dwZSrcConstBitDepth
転送元 z 定数のビット深度。
dwZSrcConst
転送元 Z バッファとして使用する定数。
lpDDSZBufferSrc
転送元 Z バッファとして使用するサーフェス。
dwAlphaEdgeBlendBitDepth
アルファ エッジ ブレンドにおけるビット深度定数。
dwAlphaEdgeBlend
エッジ ブレンドで使用するアルファ定数。
dwReserved
将来的な使用のために確保されている。
dwAlphaDestConstBitDepth
転送先アルファ定数のビット深度。
dwAlphaDestConst
転送先アルファ チャネルとして使用する定数。
lpDDSAlphaDest
転送先アルファ チャネルとして使用するサーフェス。
dwAlphaSrcConstBitDepth
転送元アルファ定数のビット深度。
dwAlphaSrcConst
転送元アルファ チャネルとして使用する定数。
lpDDSAlphaSrc
転送元アルファ チャネルとして使用するサーフェス。
dwFillColor
DDBLT_COLORFILL を指定するときに、サーフェスを塗りつぶすために使用する色。この値は、転送先サーフェスのピクセル フォーマットに該当するピクセルでなくてはならない。パレット化サーフェスであればパレット インデックス、16 ビット RGB サーフェスであれば 16 ビット ピクセル値となる。
dwFillDepth
Z バッファにおける深度値。
dwFillPixel
RGBA または RGBZ で塗りつぶすためのピクセル値。RGBZ で塗りつぶすために使用するアプリケーションは、dwFillColor または dwFillDepth ではなく、このメンバを使用する。
lpDDSPattern
パターンとして使用するサーフェス。パターンは、転送元および転送先を組み合わせる特定のブリット処理で使用する。
ddckDestColorkey
転送先カラー キー オーバーライド。
ddckSrcColorkey
転送元カラー キー オーバーライド。

注意

この構造体の集合は、名前のない集合をサポートしないコンパイラで機能するように更新されている。コンパイラが名前のない集合をサポートしない場合は、Ddraw.h ヘッダー ファイルをインクルードする前に NONAMELESSUNION トークンを定義する。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDCAPS

DDCAPS 構造体は、DirectDraw オブジェクトが明らかにするハードウェアの能力を表す。この構造体には、作成できる DirectDrawSurface オブジェクトの種類を記述するこのコンテキストの DDSCAPS 構造体が含まれている。しかし、これらの能力で記述するすべてのサーフェスを同時には作成できない場合がある。この構造体は、IDirectDraw7::GetCaps メソッドで使用される。

Ddraw.h ヘッダー ファイルにはこの構造体の複数のバージョンが含まれる。詳細情報は注意を参照すること。

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  ddsOldCaps;
    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    dwSSBFXCaps;
    DWORD    dwSSBRops[DD_ROP_SPACE];
    DWORD    dwMaxVideoPorts;
    DWORD    dwCurrVideoPorts;
    DWORD    dwSVBCaps2;
    DWORD    dwNLVBCaps;
    DWORD    dwNLVBCaps2;
    DWORD    dwNLVBCKeyCaps;
    DWORD    dwNLVBFXCaps;
    DWORD    dwNLVBRops[DD_ROP_SPACE];
    DDSCAPS2 ddsCaps;
} DDCAPS,FAR* LPDDCAPS;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwCaps
以下に、ドライバ固有の能力を示す。
DDCAPS_3D
ディスプレイ ハードウェアに 3D アクセラレータがある。
DDCAPS_ALIGNBOUNDARYDEST
DirectDraw は、サーフェスの dwAlignBoundaryDest 境界に沿って x 軸があるオーバーレイ転送先矩形のみサポートする。
DDCAPS_ALIGNBOUNDARYSRC
DirectDraw は、サーフェスの dwAlignBoundarySrc 境界に沿って x 軸があるオーバーレイ転送元矩形のみサポートする。
DDCAPS_ALIGNSIZEDEST
DirectDraw は、バイト単位での x 軸のサイズが dwAlignSizeDest の倍数であるオーバーレイ転送先矩形のみサポートする。
DDCAPS_ALIGNSIZESRC
DirectDraw は、ピクセル単位での x 軸のサイズが 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
カラー キーは、一部ハードウェア支援を受ける。このため、他のリソース (CPU またはビデオ メモリ) を使用する可能性がある。このビットが設定されていない場合、ハードウェアのフル サポートが実施される。
DDCAPS_GDI
ディスプレイ ハードウェアは、GDI で共有される。
DDCAPS_NOHARDWARE
ハードウェア サポートがない。
DDCAPS_OVERLAY
ディスプレイ ハードウェアは、オーバーレイをサポートする。
DDCAPS_OVERLAYCANTCLIP
ディスプレイ ハードウェアは、オーバーレイをサポートするが、オーバーレイをクリップすることはできない。
DDCAPS_OVERLAYFOURCC
オーバーレイ ハードウェアは、オーバーレイ処理に色空間の変更を実行できる。
DDCAPS_OVERLAYSTRETCH
オーバーレイ ハードウェアは、伸縮を実行できる。DwMinOverlayStretch および dwMaxOverlayStretch メンバには、有効なデータがある。
DDCAPS_PALETTE
DirectDraw は、プライマリ サーフェスのほか、その他のサーフェスに対しても DirectDrawPalette オブジェクトを作成およびサポートする。
DDCAPS_PALETTEVSYNC
DirectDraw は、垂直リフレッシュと同期するパレットを更新できる。
DDCAPS_READSCANLINE
ディスプレイ ハードウェアは、現在の走査線を返すことができる。
DDCAPS_VBI
ディスプレイ ハードウェアは、垂直帰線消去割り込みを生成できる。
DDCAPS_ZBLTS
ブリット処理と共に Z バッファの使用をサポートする。
DDCAPS_ZOVERLAYS
重なりを制御するオーバーレイの z 値として、IDirectDrawSurface7::UpdateOverlayZOrder メソッドの使用をサポートする。
dwCaps2
以下に、ドライバ固有の能力を示す。
DDCAPS2_AUTOFLIPOVERLAY
オーバーレイは、ビデオ ポート VSYNC が発生するたびにフリッピング チェーンの次のサーフェスに自動的にフリップされる。また、CPU オーバーヘッドを発生させずに、ビデオ ポートおよびオーバーレイからビデオをダブルバッファできる。このオプションは、サーフェスがビデオ ポートからデータを受け取るときだけに有効である。ビデオ ポート データがインターレイスまたはインターリーブされていない場合、ビデオ ポート データは VSYNC が発生するたびにフリップする。データがメモリ内でインターリーブされている場合、データは VSYNC が発生する 1 回おきにフリップする。
DDCAPS2_CANBOBHARDWARE
オーバーレイ ハードウェアは、インターレイス ビデオ ストリームの個々のフィールドを個別に表示できる。
DDCAPS2_CANBOBINTERLEAVED
オーバーレイ ハードウェアは、特別なハードウェア サポートがなければ、通常発生する可能性のある異常を引き起こすことなく、メモリでインターリーブしている間は、インターレイス ビデオ ストリームの個々のフィールドを個別に表示できる。このオプションが有効なのは、サーフェスがビデオ ポートからデータを受け取るとき、およびビデオが垂直方向に少なくとも 2 倍ズームされるときだけである。
DDCAPS2_CANBOBNONINTERLEAVED
オーバーレイ ハードウェアは、特別なハードウェア サポートがなければ、通常発生する可能性のある異常を引き起こすことなく、メモリでインターリーブしていない間は、インターレイス ビデオ ストリームの個々のフィールドを個別に表示できる。このオプションが有効なのは、サーフェスがビデオ ポートからデータを受け取るとき、およびビデオが垂直方向に少なくとも 2 倍ズームされるときだけである。
DDCAPS2_CANCALIBRATEGAMMA
システムには、自動的にガンマ ランプを調整できる口径測定器がインストールされているので、口径測定器がある全システム上で結果が示される。新しいガンマ レベルを設定するときに口径測定器を含めるには、IDirectDrawGammaControl::SetGammaRamp メソッドを呼び出す際に DDSGR_CALIBRATE フラグを使用する。ガンマ ランプのキャリブレーションでは、いくつかの処理にオーバーヘッドが起こるので、頻繁に使用できない。
DDCAPS2_CANDROPZ16BIT
16 ビット RGBZ 値を 16 ビット RGB 値に変換できる (システムでは 8 ビット変換をサポートしていない)。
DDCAPS2_CANFLIPODDEVEN
ドライバは、IDirectDrawSurface7::Flip メソッドと共に使用する DDFLIP_ODD および DDFLIP_EVEN フラグを指定して、奇数および偶数フリップ処理を実行できる。
DDCAPS2_CANMANAGETEXTURE
Direct3D テクスチャ マネージャでは、この能力を使用して管理サーフェスを非ローカル ビデオ メモリに配置するかどうかを決定する。この能力を設定すると、テクスチャ マネージャは管理サーフェスを非ローカル ビデオ メモリに配置する。ローカル ビデオ メモリからのテクスチャ処理を実行できないドライバには、この能力を設定してはならない。
DDCAPS2_CANRENDERWINDOWED
ドライバは、ウィンドウ モードのレンダリングができる。
DDCAPS2_CERTIFIED
ディスプレイ ハードウェアが保証されている。
DDCAPS2_COLORCONTROLPRIMARY
プライマリ サーフェスに、カラー コントロール (ガンマなど) が含まれる。
DDCAPS2_COLORCONTROLOVERLAY
オーバーレイ サーフェスに、カラー コントロール (輝度、鮮明度など) が含まれる。
DDCAPS2_COPYFOURCC
ドライバは、同じ FOURCC の別のサーフェスへの FOURCC サーフェスのブリット処理をサポートする。
DDCAPS2_FLIPINTERVAL
ドライバは、DDFLIP_INTERVAL* フラグに応答する (IDirectDrawSurface7::Flipを参照すること)。
DDCAPS2_FLIPNOVSYNC
ドライバは、DDFLIP_NOVSYNC フラグに応答する (IDirectDrawSurface7::Flip を参照すること)。
DDCAPS2_NO2DDURING3DSCENE
IDirect3DDevice7::BeginScene および IDirect3DDevice7::EndScene メソッドを呼び出す間に Direct3D が使用するあらゆるサーフェスにおいて、IDirectDrawSurface7::Blt、IDirectDrawSurface7::Lock などの 2D 処理は実行できない。
DDCAPS2_NONLOCALVIDMEM
ディスプレイ ドライバは、非ローカル ビデオ メモリのサーフェスをサポートする。
DDCAPS2_NONLOCALVIDMEMCAPS
非ローカル ビデオメモリ サーフェスのブリット能力は、ローカル ビデオメモリ サーフェスのものとは異なる。このフラグが存在する場合、DDCAPS2_NONLOCALVIDMEM フラグも存在する。
DDCAPS2_NOPAGELOCKREQUIRED
ページロックされていないシステムメモリ サーフェスが、DMA ブリット処理をサポートする。
DDCAPS2_PRIMARYGAMMA
プライマリ サーフェスに対するダイナミック ガンマ ランプをサポートする。詳細については、「ガンマ コントロールとカラー コントロール」を参照すること。
DDCAPS2_STEREO
DirectX 7.0 で追加。ディスプレイ デバイスはステレオ グラフィックスをサポートし、ddcaps.dwSVCaps ビット フィールドをオンにする。大部分の DDCAPS2 フラグとは異なり、このフラグは特定のモードで実際にステレオをサポートするかどうかには関係なく、すべてのモードに対して設定される。アプリケーションでは、IDirectDraw7::GetDisplayMode またはIDirectDraw7::EnumDisplayModes を使用して、モードごとにステレオ サポート情報を取得できる。
DDCAPS2_TEXMANINNONLOCALVIDMEM
DirectX 7.0 で追加。Direct3D テクスチャ マネージャでは、この能力を使用して管理サーフェスを非ローカル ビデオ メモリに配置する。この能力を設定すると、テクスチャ マネージャは管理サーフェスを非ローカル ビデオ メモリに配置する。ローカル ビデオ メモリからのテクスチャ処理を実行できないドライバには、この能力を設定してはならない。
DDCAPS2_VIDEOPORT
ディスプレイ ハードウェアは、ライブ ビデオをサポートする。
DDCAPS2_WIDESURFACES
ディスプレイ サーフェスは、プライマリ サーフェスより広いサーフェスをサポートする。
dwCKeyCaps
以下に、カラーキー能力を示す。
DDCKEYCAPS_DESTBLT
カラー キーによる透過型ブリット処理をサポートする。カラー キーは、RGB 色の転送先サーフェスの置換可能なビットを示す。
DDCKEYCAPS_DESTBLTCLRSPACE
色空間による透過型ブリット処理をサポートする。色空間は、RGB 色の転送先サーフェスの置換可能なビットを示す。
DDCKEYCAPS_DESTBLTCLRSPACEYUV
色空間による透過型ブリット処理をサポートする。色空間は、YUV 色の転送先サーフェスの置換可能なビットを示す。
DDCKEYCAPS_DESTBLTYUV
カラー キーによる透過型ブリット処理をサポートする。カラー キーは、YUV 色の転送先サーフェスの置換可能なビットを示す。
DDCKEYCAPS_DESTOVERLAY
カラー キーイングによるオーバーレイをサポートする。カラー キーイングは、RGB 色でオーバーレイされる転送先サーフェスの置換可能なビットである。
DDCKEYCAPS_DESTOVERLAYCLRSPACE
RGB 色の転送先カラー キーとして色空間をサポートする。
DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV
YUV 色の転送先カラー キーとして色空間をサポートする。
DDCKEYCAPS_DESTOVERLAYONEACTIVE
表示状態のオーバーレイ サーフェスに、アクティブな転送先カラー キー値を 1 つだけサポートする。
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
表示状態のオーバーレイ サーフェスに、アクティブな転送元カラー キー値を 1 つだけサポートする。
DDCKEYCAPS_SRCOVERLAYYUV
YUV 色のオーバーレイ サーフェスで転送元カラー キーを使用したオーバーレイをサポートする。
dwFXCaps
以下に、ドライバ固有の伸縮およびエフェクト能力を示す。
DDFXCAPS_BLTALPHA
アルファ ブレンディング ブリット処理をサポートする。
DDFXCAPS_BLTARITHSTRETCHY
ピクセルを 2 乗にして拡大する技術ではなく、ブリット処理中にサーフェスを拡大したり収縮する算術処理を使用する。これは、y 軸 (垂直) に沿って行われる。
DDFXCAPS_BLTARITHSTRETCHYN
ピクセルを 2 乗にして拡大する技術ではなく、ブリット処理中にサーフェスを拡大したり収縮する算術処理を使用する。これは、y 軸 (垂直) に沿って行われ、整数倍伸縮 (× 1、× 2 など) に対してのみ機能する。
DDFXCAPS_BLTFILTER
ドライバは、ラップされたブリットに対してフィルタリングするサーフェスの再構成を行える。
DDFXCAPS_BLTMIRRORLEFTRIGHT
ブリット処理で左右のミラーリングをサポートする。
DDFXCAPS_BLTMIRRORUPDOWN
ブリット処理で上下のミラーリングをサポートする。
DDFXCAPS_BLTROTATION
ブリット処理で任意の回転をサポートする。
DDFXCAPS_BLTROTATION90
ブリット処理で 90 度の回転をサポートする。
DDFXCAPS_BLTSHRINKX
x 軸 (水平) に沿ってサーフェスを任意に収縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSHRINKXN
x 軸 (水平) に沿ってサーフェスを整数倍 (× 1、× 2 など) に収縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSHRINKY
y 軸 (垂直) に沿ってサーフェスを任意に収縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSHRINKYN
y 軸 (垂直) に沿ってサーフェスを整数倍 (× 1、× 2 など) に収縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSTRETCHX
x 軸 (水平) に沿ってサーフェスを任意に伸縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSTRETCHXN
x 軸 (水平) に沿ってサーフェスを整数倍伸縮 (× 1、× 2 など) することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSTRETCHY
y 軸 (垂直) に沿ってサーフェスを任意に伸縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSTRETCHYN
y 軸 (垂直) に沿ってサーフェスを整数倍伸縮 (× 1、× 2 など) することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTTRANSFORM
ブリットされるスプライトに対してジオメトリ トランスフォーム (または、ラップ) をサポートする。現時点では、トランスフォームはブリット処理でサポートされていない。
DDFXCAPS_OVERLAYALPHA
オーバーレイ サーフェスに対するアルファ ブレンディングをサポートする。
DDFXCAPS_OVERLAYARITHSTRETCHY
ピクセルを 2 倍にして拡大する技術ではなく、算術処理を使用してオーバーレイ サーフェスを拡大および収縮する。これは、y 軸 (垂直) に沿って行われる。
DDFXCAPS_OVERLAYARITHSTRETCHYN
ピクセルを 2 倍にして拡大する技術ではなく、算術処理を使用してオーバーレイ サーフェスを拡大および収縮するこれは、y 軸 (垂直) に沿って行われ、整数倍伸縮 (× 1、× 2 など) に対してのみ機能する。
DDFXCAPS_OVERLAYFILTER
ラップされたオーバーレイ スプライトに対してフィルタリングするサーフェスの再構成をサポートする。現時点では、フィルタリングは明示的に表示されるオーバーレイ サーフェス (IDirectDrawSurface7::UpdateOverlay を呼び出すことで表示される) に対してはサポートされていない。
DDFXCAPS_OVERLAYMIRRORLEFTRIGHT
垂直軸に沿ってオーバーレイのミラーリングをサポートする。
DDFXCAPS_OVERLAYMIRRORUPDOWN
水平軸に沿ってオーバーレイのミラーリングをサポートする。
DDFXCAPS_OVERLAYSHRINKX
x 軸 (水平) に沿ってサーフェスを任意に収縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、収縮が可能であることは示さない。
DDFXCAPS_OVERLAYSHRINKXN
x 軸 (水平) に沿ってサーフェスを整数倍収縮 (× 1、× 2 など) することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、収縮が可能であることは示さない。
DDFXCAPS_OVERLAYSHRINKY
y 軸 (垂直) に沿ってサーフェスを任意に収縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、収縮が可能であることは示さない。
DDFXCAPS_OVERLAYSHRINKYN
y 軸 (垂直) に沿ってサーフェスを整数倍収縮 (× 1、× 2 など) することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、収縮が可能であることは示さない。
DDFXCAPS_OVERLAYSTRETCHX
x 軸 (水平) に沿ってサーフェスを任意に伸縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグはサーフェスの能力だけを示し、伸縮が可能であることを示すものではない。
DDFXCAPS_OVERLAYSTRETCHXN
x 軸 (水平) に沿ってサーフェスを整数倍伸縮 (× 1、× 2 など) することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグはサーフェスの能力だけを示し、伸縮が可能であることは示すものではない。
DDFXCAPS_OVERLAYSTRETCHY
y 軸 (垂直) に沿ってサーフェスを任意に伸縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグはサーフェスの能力だけを示し、伸縮が可能であることを示すものではない。
DDFXCAPS_OVERLAYSTRETCHYN
y 軸 (垂直) に沿ってサーフェスを整数倍伸縮 (× 1、× 2 など) することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグはサーフェスの能力だけを示し、伸縮が可能であることを示すものではない。
DDFXCAPS_OVERLAYTRANSFORM
オーバーレイ スプライトに対してジオメトリ トランスフォーム (または、ラップ) をサポートする。現時点では、トランスフォームは明示的に表示されるオーバーレイ サーフェス (IDirectDrawSurface7::UpdateOverlay の呼び出しで表示される) に対してはサポートされていない。
dwFXAlphaCaps
以下に、ドライバ固有のアルファ能力を示す。
DDFXALPHACAPS_BLTALPHAEDGEBLEND
転送元カラーキー サーフェスの縁周りのアルファ ブレンディングをサポートする。ブリット処理に対して使用される。
DDFXALPHACAPS_BLTALPHAPIXELS
ピクセル フォーマットでアルファ情報をサポートする。ピクセル フォーマットのアルファ情報のビット深度は、1、2、4、または 8 である。アルファ値は、増加するにつれてより不透明となる。アルファ情報の深度にかかわらず、0 は常に完全な透過型値となる。ブリット処理に対して使用される。
DDFXALPHACAPS_BLTALPHAPIXELSNEG
ピクセル フォーマットでアルファ情報をサポートする。ピクセル フォーマットのアルファ情報のビット深度は、1、2、4、または 8 である。アルファ値は、増加するにつれてより透過型となる。アルファ情報の深度にかかわらず、0 は常に完全な不透明値となる。このフラグは、DDCAPS_ALPHA が設定されている場合だけに使用できる。ブリット処理に対して使用される。
DDFXALPHACAPS_BLTALPHASURFACES
アルファ専用サーフェスをサポートする。アルファ専用サーフェスのビット深度は、1、2、4、または 8 である。アルファ値は、増加するにつれてより不透明となる。アルファ情報の深度にかかわらず、0 は常に完全な透過型値となる。ブリット処理に対して使用される。
DDFXALPHACAPS_BLTALPHASURFACESNEG
アルファ チャネル は、アルファ値が増加するにつれてより透過型となることを示す。アルファ チャネルデータの深度は、1、2、4、または 8 である。アルファ情報の深度にかかわらず、0 は常に完全な不透明値となる。このフラグは、DDCAPS_ALPHA が設定されている場合にだけ使用できる。ブリット処理に対して使用される。
DDFXALPHACAPS_OVERLAYALPHAEDGEBLEND
転送元カラーキー サーフェスの縁周りのアルファ ブレンディングをサポートする。オーバーレイに対して使用される。
DDFXALPHACAPS_OVERLAYALPHAPIXELS
ピクセル フォーマットでアルファ情報をサポートする。ピクセル フォーマットのアルファ情報のビット深度は、1、2、4、または 8 である。アルファ値は、増加するにつれてより不透明となる。アルファ情報の深度にかかわらず、0 は常に完全な透過型値となる。オーバーレイに対して使用される。
DDFXALPHACAPS_OVERLAYALPHAPIXELSNEG
ピクセル フォーマットでアルファ情報をサポートする。ピクセル フォーマットのアルファ情報のビット深度は、1、2、4、または 8 である。アルファ値は、増加するにつれてより透過型となる。アルファ情報の深度にかかわらず、0 は常に完全な不透明値となる。このフラグは、DDCAPS_ALPHA が設定されている場合だけに使用される。オーバーレイに対して使用される。
DDFXALPHACAPS_OVERLAYALPHASURFACES
アルファ専用サーフェスをサポートする。アルファ専用サーフェスのビット深度は、1、2、4、または 8 である。アルファ値は、増加するにつれてより不透明となる。アルファ情報の深度にかかわらず、0 は常に完全な透過型値となる。オーバーレイに対して使用される。
DDFXALPHACAPS_OVERLAYALPHASURFACESNEG
アルファ値が増加するにつれて、アルファ チャネルがより透過型となることを示す。アルファチャネル データの深度は、1、2、4、または 8 である。アルファ情報の深度にかかわらず、0 は常に完全な不透明値となる。このフラグは、DDCAPS_ALPHA が設定されている場合だけに使用される。オーバーレイに対して使用される。
dwPalCaps
以下に、パレット能力を示す。
DDPCAPS_1BIT
1 ビット カラー エントリ (2 色) を含むパレットをサポートする。
DDPCAPS_2BIT
2 ビット カラー エントリ (4 色) を含むパレットをサポートする。
DDPCAPS_4BIT
4 ビット カラー エントリ (16 色) を含むパレットをサポートする。
DDPCAPS_8BIT
8 ビット カラー エントリ (256 色) を含むパレットをサポートする。
DDPCAPS_8BITENTRIES
インデックスを 8 ビット カラー インデックスに指定する。このフィールドは、DDPCAPS_1BIT、DDPCAPS_2BIT、または DDPCAPS_4BIT 能力が使用される場合、およびターゲット サーフェスが 1 ピクセル当たり 8 ビット (bpp) である場合にのみ有効である。個々のカラー エントリは 1 バイト長であり、転送先サーフェス上の 8 bpp パレットへのインデックスである。
DDPCAPS_ALPHA
アルファ成分を含むパレットをサポートする。アルファ能力パレットでは、パレットに含まれる各 PALETTEENTRY 構造体の peFlags メンバは、単一の 8 ビット アルファ値 (peRed、peGreen、peBlue メンバのデータのほか) として判断される。このフラグで作成されたパレットは、テクスチャ サーフェスにのみアタッチできる。
DDPCAPS_ALLOW256
すべての 256 エントリを定義できるパレットをサポートする。
DDPCAPS_PRIMARYSURFACE
パレットはプライマリ サーフェスにアタッチされる。パレットの変更は、DDPCAPS_VSYNC 能力の指定およびサポートがないかぎり、ディスプレイに即座に反映される。
DDPCAPS_PRIMARYSURFACELEFT
パレットは、左側でプライマリ サーフェスにアタッチされる。パレットの変更は、DDPCAPS_VSYNC 能力の指定およびサポートがないかぎり、ディスプレイに即座に反映される。
DDPCAPS_VSYNC
パレットは、モニタのリフレッシュ レートに同期して変更できる。
dwSVCaps
以下に、ステレオビジョン能力を示す。
DDSVCAPS_RESERVED1, DDSVCAPS_RESERVED2, DDSVCAPS_RESERVED3, DDSVCAPS_RESERVED4
今後のために確保されているフラグ。
DDSVCAPS_STEREOSEQUENTIAL
DirectX 7.0 で追加。ドライバは、現在のモード以外の少なくとも 1 つのモードでステレオを実行できる。アプリケーションでは、IDirectDraw7::GetDisplayMode または IDirectDraw7::EnumDisplayModes を使用して各モードのステレオ情報を取得できる。
dwAlphaBltConstBitDepths
DDBD_2、DDBD_4、または DDBD_8 (1 ピクセル当たり 2、4、または 8 ビットであることを示す)。
dwAlphaBltPixelBitDepths
DDBD_1、DDBD_2、DDBD_4、または DDBD_8 (1 ピクセル当たり 1、2、4、または 8 ビットであることを示す)。
dwAlphaBltSurfaceBitDepths
DDBD_1、DDBD_2、DDBD_4、または DDBD_8 (1 ピクセル当たり 1、2、4、または 8 ビットであることを示す)。
dwAlphaOverlayConstBitDepths
DDBD_2、DDBD_4、または DDBD_8 (1 ピクセル当たり 2、4、または 8 ビットであることを示す)。
dwAlphaOverlayPixelBitDepths
DDBD_1、DDBD_2、DDBD_4、または DDBD_8 (1 ピクセル当たり 1、2、4、または 8 ビットであることを示す)。
dwAlphaOverlaySurfaceBitDepths
DDBD_1、DDBD_2、DDBD_4、または DDBD_8 (1 ピクセル当たり 1、2、4、または 8 ビットであることを示す)。
dwZBufferBitDepths
DDBD_8、DDBD_16、DDBD_24、または DDBD_32 (1 ピクセル当たり 8、16、24、または 32 ビットであることを示す)。このメンバは、DirectX 6.0 以降のバージョンのために取得される。IDirect3D7::EnumZBufferFormats を使用して、サーポートされる深度バッファ フォーマットの情報を取得する。
dwVidMemTotal
バイト単位で表す、デバイス上のディスプレイ メモリの総容量。ただし、プライマリ サーフェス用に確保されているメモリおよびドライバで確保するプライベート データ構造体用のメモリを除く (この値は、IDirectDraw7::GetAvailableVidMem メソッドが知らせる全ビデオ メモリと同じである)。
dwVidMemFree
ディスプレイ メモリを解放する。この値は、dwVidMemTotal の値から、アプリケーションがサーフェス用に現在割り当てているメモリを引いた値と同じである。特定の種類のサーフェス (テクスチャなど) で使用可能なメモリを知らせる GetAvailableVidMem メソッドとは異なり、この値はあらゆる種類のサーフェスに対して使用可能なメモリを示す。
dwMaxVisibleOverlays
表示されるオーバーレイまたはオーバーレイ スプライトの最大数。
dwCurrVisibleOverlays
表示されるオーバーレイまたはオーバーレイ スプライトの現在の数。
dwNumFourCCCodes
FOURCC コードの数。
dwAlignBoundarySrc
ピクセル単位のオーバーレイ サーフェスに対する転送元矩形のアライメント。
dwAlignSizeSrc
ピクセル単位のオーバーレイ サーフェスに対する転送元矩形のサイズ アライメント。オーバーレイ転送元矩形は、この値の倍数のピクセル幅でなくてはならない。
dwAlignBoundaryDest
ピクセル単位のオーバーレイ サーフェスに対する転送先矩形のアライメント。
dwAlignSizeDest
ピクセル単位のオーバーレイ サーフェスに対する転送先矩形のサイズ アライメント。オーバーレイ転送先矩形は、この値の倍数のピクセル幅でなくてはならない。
dwAlignStrideAlign
ストライド アライメント。
dwRops[DD_ROP_SPACE]
サポートされるラスタ処理。
ddsOldCaps
廃止。DirectX 6.0 より前は、このメンバには一般的なサーフェス能力が含まれていた。現在これらのサーフェス能力は、ddsCaps メンバ (DDSCAPS2 構造体) に含まれている。
dwMinOverlayStretch、dwMaxOverlayStretch
1000 倍される最小および最大オーバーレイ伸縮係数。たとえば、1.3 = 1300。
dwMinLiveVideoStretch、dwMaxLiveVideoStretch
廃止。使用しない。
dwMinHwCodecStretch、dwMaxHwCodecStretch
廃止。使用しない。
dwReserved1、dwReserved2、dwReserved3
将来的な使用のために確保されている。
dwSVBCaps
システム メモリからディスプレイ メモリへのブリットに関するドライバ固有の能力。有効フラグは、dwCaps メンバで使用されるブリット関連フラグと等しい。
dwSVBCKeyCaps
システム メモリからディスプレイ メモリへのブリットに関するドライバのカラーキー能力。有効フラグは、dwCKeyCaps メンバで使用されるブリット関連フラグと等しい。
dwSVBFXCaps
システム メモリからディスプレイ メモリへのブリットに関するドライバの FX 能力。有効フラグは、dwFXCaps メンバで使用されるブリット関連フラグと等しい。
dwSVBRops[DD_ROP_SPACE]
システム メモリからディスプレイ メモリへのブリットでサポートされるラスタ処理。
dwVSBCaps
ディスプレイ メモリからシステム メモリへのブリットに関するドライバ固有の能力。有効フラグは、dwCaps メンバで使用されるブリット関連フラグと等しい。
dwVSBCKeyCaps
ディスプレイ メモリからシステム メモリのブリットに関するドライバのカラーキー能力。有効フラグは、dwCKeyCaps メンバで使用されるブリット関連フラグと等しい。
dwVSBFXCaps
ディスプレイ メモリからシステム メモリへのブリットに関するドライバの FX 能力。有効フラグは、dwFXCaps メンバで使用されるブリット関連フラグと等しい。
dwVSBRops[DD_ROP_SPACE]
ディスプレイ メモリからシステム メモリへのブリットでサポートされるラスタ処理。
dwSSBCaps
システム メモリからシステム メモリへのブリットに関するドライバ固有の能力。有効フラグは、dwCaps メンバで使用されるブリット関連フラグと等しい。
dwSSBCKeyCaps
システム メモリからシステム メモリへのブリットに関するドライバのカラーキー能力。有効フラグは、dwCKeyCaps メンバで使用されるブリット関連フラグと等しい。
dwSSBFXCaps
システム メモリからシステム メモリへのブリットに関するドライバの FX 能力。有効フラグは、dwFXCaps メンバで使用されるブリット関連フラグと等しい。
dwSSBRops[DD_ROP_SPACE]
システム メモリからシステム メモリへのブリットでサポートされるラスタ処理。
dwMaxVideoPorts
ライブ ビデオ ポートの最大数。
dwCurrVideoPorts
ライブ ビデオ ポートの現在の数。
dwSVBCaps2
システム メモリからビデオ メモリへのブリットの関する、ドライバ固有の詳細な能力。有効フラグは、dwCaps2 メンバで使用されるブリット関連フラグと等しい。
dwNLVBCaps
非ローカルからローカル ビデオ メモリへのブリットに関するドライバ固有の能力。有効フラグは、dwCaps メンバで使用されるブリット関連フラグと等しい。
dwNLVBCaps2
非ローカルからローカル ビデオ メモリへのブリットの関する、ドライバ固有の詳細な能力。有効フラグは、dwCaps2 メンバで使用されるブリット関連フラグと等しい。
dwNLVBCKeyCaps
非ローカルからローカル ビデオ メモリのブリットに関するドライバのカラーキー能力。有効フラグは、dwCKeyCaps メンバで使用されるブリット関連フラグと等しい。
dwNLVBFXCaps
非ローカルからローカル ビデオ メモリのブリットの関するドライバの FX 能力。有効フラグは、dwFXCaps メンバで使用されるブリット関連フラグと等しい。
dwNLVBRops[DD_ROP_SPACE]
非ローカルからローカル ビデオ メモリへのブリットでサポートされるラスタ処理。
ddsCaps
一般的なサーフェス能力がある DDSCAPS2 構造体。

注意

後方互換性を保つために、Ddraw.h ヘッダー ファイルには DDCAPS 構造体の複数の定義が含まれている。プリプロセッサを渡すバージョンは、DIRECTDRAW_VERSION 定数の値によって決まる。詳細については、「コンポーネントのバージョン定数」を参照すること。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
Windows CE : ddraw.h で宣言。


DDCOLORCONTROL

DDCOLORCONTROL 構造体は、DirectDrawVideoPortObject、オーバーレイ サーフェス、またはプライマリ サーフェスに関連付けられたカラー コントロールを定義する。

typedef struct _DDCOLORCONTROL {
    DWORD   dwSize;
    DWORD   dwFlags;
    LONG    lBrightness;
    LONG    lContrast;
    LONG    lHue;
    LONG    lSaturation;
    LONG    lSharpness;
    LONG    lGamma;
    LONG    lColorEnable;
    DWORD   dwReserved1;
} DDCOLORCONTROL, FAR *LPDDCOLORCONTROL;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなければならない。
dwFlags
以下に、有効なデータを含む構造体メンバを指定するフラグを示す。構造体が IDirectDrawColorControl::GetColorControls メソッドによって返される場合、デバイスでサポートされるオプションも示す。
DDCOLOR_BRIGHTNESS
lBrightness メンバが有効なデータを含む。
DDCOLOR_COLORENABLE
lColorEnable メンバが有効なデータを含む。
DDCOLOR_CONTRAST
lContrast メンバが有効なデータを含む。
DDCOLOR_GAMMA
lGamma メンバが有効なデータを含む。
DDCOLOR_HUE
lHue メンバが有効なデータを含む。
DDCOLOR_SATURATION
lSaturation メンバが有効なデータを含む。
DDCOLOR_SHARPNESS
lSharpness メンバが有効なデータを含む。
lBrightness
IRE 単位 (× 100) で表す輝度。有効範囲は 0 から 10,000。デフォルト値は 750 (7.5 IRE)。
lContrast
IRE 単位 (× 100) で表す輝度における上と下の輝度の相対的差違。有効範囲は 0 から 20,000。デフォルト値は 10,000 (100 IRE)。コントラストを上げると、より暗い輝度は黒っぽくなり、より明るい輝度は白っぽくなる傾向がある。コントラストを下げると、すべての輝度が中間の輝度になるように変化する。
lHue
クロミナンス成分の位相関係。色相は度で指定される。有効範囲は -180 から 180。デフォルト値は 0。
lSaturation
IRE 単位 (× 100) で表すカラー強度。有効範囲は 0 から 20,000。デフォルト値は 10,000 (100 IRE)。
lSharpness
任意の単位の鮮明度。有効範囲は 0 から 10。デフォルト値は 5。
lGamma
輝度に適用されるガンマ修正量を制御する。有効範囲はガンマ単位で 1 から 500。デフォルト値は 1。
lColorEnable
色を使用するかどうかを示すフラグ。このメンバが 0 の場合、色は使用されない。このメンバが 1 の場合は色が使用される。デフォルト値は 1。
dwReserved1
将来的な使用のために確保されている。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
Windows CE : ddraw.h で宣言。


DDCOLORKEY

DDCOLORKEY 構造体は、転送元カラー キー、転送先カラー キー、または色空間を記述する。カラー キーは、上限と下限の範囲値が同じ場合に指定される。この構造体は、IDirectDrawSurface7::GetColorKey および IDirectDrawSurface7::SetColorKey メソッドで使用される。

typedef struct _DDCOLORKEY{
    DWORD dwColorSpaceLowValue;
    DWORD dwColorSpaceHighValue;
} DDCOLORKEY,FAR* LPDDCOLORKEY;

メンバ

dwColorSpaceLowValue
カラー キーとして使用される色範囲の下限値。
dwColorSpaceHighValue
カラー キーとして使用される色範囲の上限値。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDDEVICEIDENTIFIER2

DDDEVICEIDENTIFIER2 構造体は、デバイス情報を取得する IDirectDraw7::GetDeviceIdentifier メソッドに渡される。

typedef struct tagDDDEVICEIDENTIFIER2 {
    char    szDriver[MAX_DDDEVICEID_STRING];
    char    szDescription[MAX_DDDEVICEID_STRING];
    LARGE_INTEGER  liDriverVersion;
    DWORD   dwVendorId;
    DWORD   dwDeviceId;
    DWORD   dwSubSysId;
    DWORD   dwRevision;
    GUID    guidDeviceIdentifier;
    DWORD   dwWHQLLevel;
} DDDEVICEIDENTIFIER2, * LPDDDEVICEIDENTIFIER2;

メンバ

szDriver
ドライバの名前。
szDescription
ドライバの記述。
liDriverVersion
ドライバのバージョン。全 64 ビットより少ないか多いかを正当に比較する。この要素を使用して疑わしいドライバを識別する場合は、注意して行うこと。この目的には guidDeviceIdentifier を使用する。

データは、次のフォームを取得する。

wProduct = HIWORD(liDriverVersion.HighPart)
wVersion = LOWORD(liDriverVersion.HighPart)
wSubVersion = HIWORD(liDriverVersion.LowPart)
wBuild = LOWORD(liDriverVersion.LowPart)
dwVendorId
メーカーの識別子。不明の場合は 0。
dwDeviceId
チップセットのタイプ識別子。不明の場合は 0。
dwSubSysId
サブシステムの識別子。通常、特定のボードを意味する。不明の場合は 0。
dwRevision
チップセットの改訂版レベルの識別子。不明の場合は 0。
guidDeviceIdentifier
ドライバ/チップセット組みの固有識別子。ドライバまたはチップセットへの変更を追跡して、グラフィックス サブシステムのプロファイルを作成し直す場合は、この値を使用する。また、特定の疑わしいドライバを識別する場合にも使用できる。
dwWHQLLevel
デバイス/ドライバのペアの Windows Hardware Quality Lab (WHQL) 認証レベル。

注意

szDriver と szDescription の値は、ユーザーのためだけにある。異なる文字列が同じデバイスに関連していたり、異なるメーカーの同じドライバが異なって記述されることがあるため、これらの値は特定のドライバを識別するために使用するべきではない。

dwVendorId、dwDeviceId、dwSubSysId、および dwRevision メンバは特定のチップセットを識別するために使用できるが、細心の注意が必要である。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDGAMMARAMP

DDGAMMARAMP 構造体は、IDirectDrawGammaControl::GetGammaRamp および IDirectDrawGammaControl::SetGammaRamp メソッド用の赤、緑、および青ランプ データを含む。

typedef struct _DDGAMMARAMP {
    WORD red[256];
    WORD green[256];
    WORD blue[256];
} DDGAMMARAMP, FAR * LPDDGAMMARAMP;

メンバ

red、green、blue
赤、緑、および青のガンマ ランプを記述する 256 WORD 要素の配列。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。

参照

ガンマ コントロールとカラー コントロール


DDOVERLAYFX

DDOVERLAYFX 構造体は、IDirectDrawSurface7::UpdateOverlay メソッドにオーバーライド情報を渡す。

typedef struct _DDOVERLAYFX{
    DWORD dwSize;
    DWORD dwAlphaEdgeBlendBitDepth;
    DWORD dwAlphaEdgeBlend;
    DWORD dwReserved;
    DWORD dwAlphaDestConstBitDepth;
    union
    {
        DWORD               dwAlphaDestConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaDest;
    } DUMMYUNIONNAMEN(1);
    DWORD dwAlphaSrcConstBitDepth;
    union
    {
        DWORD               dwAlphaSrcConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaSrc;
    } DUMMYUNIONNAMEN(2);
    DDCOLORKEY dckDestColorkey;
    DDCOLORKEY dckSrcColorkey;

    DWORD dwDDFX;
    DWORD dwFlags;
} DDOVERLAYFX,FAR *LPDDOVERLAYFX;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwAlphaEdgeBlendBitDepth
アルファ エッジ ブレンドの定数を指定するために使用されるビット深度。
dwAlphaEdgeBlend
エッジ ブレンドに対するアルファとして使用される定数。
dwReserved
将来的な使用のために確保されている。
dwAlphaDestConstBitDepth
転送先のアルファ定数を指定するために使用されるビット深度。
dwAlphaDestConst
転送先のアルファ チャネルとして使用される定数。
lpDDSAlphaDest
転送先のアルファ チャネルとして使用するサーフェスのアドレス。
dwAlphaSrcConstBitDepth
転送元のアルファ定数を指定するために使用されるビット深度。
dwAlphaSrcConst
転送元のアルファ チャネルとして使用する定数。
lpDDSAlphaSrc
転送元のアルファ チャネルとして使用するサーフェスのアドレス。
dckDestColorkey
転送先カラー キー オーバーライド。
dckSrcColorkey
転送元カラー キー オーバーライド。
dwDDFX
以下に、オーバーレイ FX フラグを示す。
DDOVERFX_ARITHSTRETCHY
伸縮を実行する場合、オーバーレイの y 軸に沿って算術伸縮を使用する。
DDOVERFX_MIRRORLEFTRIGHT
垂直軸の周りでオーバーレイをミラー化する。
DDOVERFX_MIRRORUPDOWN
水平軸の周りでオーバーレイをミラー化する。
dwFlags
現在未使用なので 0 を設定しておく。

注意

この構造体の集合は、名前のない集合をサポートしないコンパイラで機能するように更新されている。コンパイラが名前のない集合をサポートしない場合、Ddraw.h ヘッダー ファイルをインクルードする前に NONAMELESSUNION トークンを定義する。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDPIXELFORMAT

DDPIXELFORMAT 構造体は、IDirectDrawSurface7::GetPixelFormat メソッドに対する DirectDrawSurface オブジェクトのピクセル フォーマットを記述する。

typedef struct _DDPIXELFORMAT{
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwFourCC;
    union
    {
        DWORD dwRGBBitCount;
        DWORD dwYUVBitCount;
        DWORD dwZBufferBitDepth;
        DWORD dwAlphaBitDepth;
        DWORD dwLuminanceBitCount;
        DWORD dwBumpBitCount;
    } DUMMYUNIONNAMEN(1);
    union
    {
        DWORD dwRBitMask;
        DWORD dwYBitMask;
        DWORD dwStencilBitDepth;
        DWORD dwLuminanceBitMask;
        DWORD dwBumpDuBitMask;
    } DUMMYUNIONNAMEN(2);
    union
    {
        DWORD dwGBitMask;
        DWORD dwUBitMask;
        DWORD dwZBitMask;
        DWORD dwBumpDvBitMask;
    } DUMMYUNIONNAMEN(3);
    union
    {
        DWORD dwBBitMask;
        DWORD dwVBitMask;
        DWORD dwStencilBitMask;
        DWORD dwBumpLuminanceBitMask;
    } DUMMYUNIONNAMEN(4);
    union
    {
        DWORD dwRGBAlphaBitMask;
        DWORD dwYUVAlphaBitMask;
        DWORD dwLuminanceAlphaBitMask;
        DWORD dwRGBZBitMask;
        DWORD dwYUVZBitMask;
    } DUMMYUNIONNAMEN(5);
} DDPIXELFORMAT, FAR* LPDDPIXELFORMAT;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwFlags
以下に、オプション制御フラグを示す。
DDPF_ALPHA
ピクセル フォーマットは、アルファ専用サーフェスを記述する。
DDPF_ALPHAPIXELS
サーフェスには、ピクセル フォーマットのアルファ チャネル情報がある。
DDPF_ALPHAPREMULT
サーフェスは、あらかじめ増やしたアルファ フォーマットを使用する。つまり、個々のピクセルの色成分は、アルファ成分をあらかじめ掛けられている。
DDPF_BUMPLUMINANCE
ピクセル フォーマットの輝度データは有効である。また、dwLuminanceBitMask メンバは、輝度専用または輝度アルファ サーフェスに対する有効な輝度ビットを記述する。
DDPF_BUMPDUDV
ピクセル フォーマットのバンプマップ データは有効である。バンプマップ情報は、dwBumpBitCount、dwBumpDuBitMask、dwBumpDvBitMask、および dwBumpLuminanceBitMask メンバにある。
DDPF_COMPRESSED
サーフェスは指定されたフォーマットでピクセル データを受け取り、書き込み処理中にそのデータを圧縮する。
DDPF_FOURCC
dwFourCC メンバは有効で、非 RGB ピクセル フォーマットを記述する FOURCC コードを含む。
DDPF_LUMINANCE
ピクセル フォーマットは、輝度専用または輝度アルファ サーフェスを記述する。
DDPF_PALETTEINDEXED1
DDPF_PALETTEINDEXED2
DDPF_PALETTEINDEXED4
DDPF_PALETTEINDEXED8
サーフェスは、1 ビット、2 ビット、4 ビット、または 8 ビットの色でインデックスされている。
DDPF_PALETTEINDEXEDTO8
サーフェスは、1 ビット、2 ビット、4 ビットの色を 8 ビット パレットにインデックスしている。
DDPF_RGB
ピクセル フォーマット構造体の RGB データは有効である。
DDPF_RGBTOYUV
サーフェスは RGB データを受け取り、書き込み処理中に YUV データにそのデータを変換する。書き込むデータのフォーマットは、ピクセル フォーマット構造体に含まれる。DDPF_RGB フラグを設定する。
DDPF_STENCILBUFFER
サーフェスは、Z バッファの個々のピクセルにおけるステンシルと深度情報を符号化する。このフラグは、DDPF_ZBUFFER フラグが同様に指定される場合だけに使用できる。
DDPF_YUV
ピクセル フォーマット構造体の YUV データは有効である。
DDPF_ZBUFFER
ピクセル フォーマットは、Z バッファ専用サーフェスを記述する。
DDPF_ZPIXELS
サーフェスは、ピクセルの z 情報を含む。
dwFourCC
FOURCC コード。詳細情報は、「4 文字コード (FOURCC) 」を参照すること。
dwRGBBitCount
RGB ビット/ピクセル (4、8、16、24、または 32)。
dwYUVBitCount
YUV ビット/ピクセル (4、8、16、24、または 32)。
dwZBufferBitDepth
Z バッファ ビット深度 (8、16、24、または 32)。
dwAlphaBitDepth
アルファ専用サーフェス (DDPF_ALPHA) のためのアルファ チャネル ビット深度 (1、2、4、または 8)。アルファ情報を含むピクセル フォーマットは色データ (DDPF_ALPHAPIXELS) でインターリーブされるため、dwRGBAlphaBitMask メンバのビットをカウントし、アルファ成分のビット深度を取得する。詳細情報は注意を参照すること。
dwLuminanceBitCount
総輝度ビット/ピクセル。このメンバは、輝度専用および輝度アルファ サーフェスだけに適用する。
dwBumpBitCount
バンプマップ サーフェスの総バンプマップ ビット/ピクセル。
dwRBitMask
赤ビットのマスク。
dwYBitMask
Y ビットのマスク。
dwStencilBitDepth
ステンシル バッファのビット深度。このメンバは、ステンシル情報の Z バッファの各ピクセル内で確保されるビットの数を指定する。(z ビットの総数は dwZBufferBitDepth から dwStencilBitDepth を引いた数と等しい)。
dwLuminanceBitMask
輝度ビットのマスク。
dwBumpDuBitMask
バンプマップ U デルタ ビットのマスク。
dwGBitMask
緑ビットのマスク。
dwUBitMask
U ビットのマスク。
dwZBitMask
z ビットのマスク。
dwBumpDvBitMask
バンプマップ V デルタ ビットのマスク。
dwBBitMask
青ビットのマスク。
dwVBitMask
V ビットのマスク。
dwStencilBitMask
各 Z バッファ ピクセル内のステンシル ビットのマスク。
dwBumpLuminanceBitMask
バンプマップ ピクセルの輝度のマスク。
dwRGBAlphaBitMask、dwYUVAlphaBitMask、dwLuminanceAlphaBitMask
アルファ チャネルのマスク。
dwRGBZBitMask、dwYUVZBitMask
z チャネルのマスク。

注意

dwAlphaBitDepth メンバは、アルファ専用ピクセル フォーマット (DDPF_ALPHA) のビット深度を反映する。色成分 (DDPF_ALPHAPIXELS) と共にアルファ成分を含むピクセル フォーマットのために、アルファ ビット深度はさまざまなマスク メンバのビットを数えることで取得される。次のコード例は、与えられたビットマスクのビット セット数を返す。

WORD GetNumberOfBits( DWORD dwMask )
{
    WORD wBits = 0;
    while( dwMask )
    {
        dwMask = dwMask & ( dwMask - 1 );
        wBits++;
    }
    return wBits;
}

この構造体の集合は、名前のない集合をサポートしないコンパイラで機能するように更新されている。コンパイラが名前のない集合をサポートしない場合、Ddraw.h ヘッダー ファイルをインクルードする前に NONAMELESSUNION トークンを定義する。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。

参照

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


DDSCAPS

DDSCAPS 構造体は、DirectDrawSurface オブジェクトの能力を定義する。この構造体は、DDCAPS および DDSURFACEDESC 構造体の一部である。

typedef struct _DDSCAPS{
    DWORD dwCaps;
} DDSCAPS, FAR* LPDDSCAPS;

メンバ

dwCaps
サーフェスの能力。以下のフラグのうち、1 つ以上の値を取る。
DDSCAPS_3D
未対応。代わりに DDSCAPS_3DDEVICE を使用する。
DDSCAPS_3DDEVICE
このサーフェスは 3D レンダリングに使用できる。アプリケーションはこのフラグを使い、デバイスが適切なヒープから割り当てられたオフスクリーン サーフェスのある特定のヒープだけをレンダリングできることを保証する。このフラグがヒープに対して設定されている場合、サーフェスはそのヒープから割り当てられない。
DDSCAPS_ALLOCONLOAD
未使用。
DDSCAPS_ALPHA
このサーフェスはアルファ専用情報を含む。
DDSCAPS_BACKBUFFER
このサーフェスは、サーフェス フリッピング構造のバック バッファである。通常、この能力は、DDSCAPS_FLIP フラグが使用されるときに CreateSurface メソッドで設定される。DDSCAPS_FRONTBUFFER サーフェスの直前のサーフェスだけ、この能力が設定される。DDSCAPS_FLIP フラグの存在、アタッチの順序、および DDSCAPS_FRONTBUFFER と DDSCAPS_BACKBUFFER 能力の欠如により、別のサーフェスがバック バッファとして識別される。この能力が CreateSurface メソッドに送られると、スタンドアロン バック バッファを作成する。このメソッドを呼び出した後、このサーフェスは、フロント バッファ、別のバック バッファ、またはその両方にアタッチしてフリッピング サーフェス構造を形成できる。詳細については、「IDirectDrawSurface7::AddAttachedSurface」を参照すること。DirectDraw では、プリッピング構造にサーフェスはいくつでも存在できる。
DDSCAPS_COMPLEX
複合サーフェスが記述される。複合サーフェスは、2 つ以上のサーフェスから作成される。追加サーフェスは、ルート サーフェスにアタッチされる。複合サーフェスは、ルートを破棄するだけで破棄できる。
DDSCAPS_FLIP
このサーフェスは、サーフェス フリッピング構造の一部である。この能力が CreateSurface メソッドに渡されると、フロント バッファおよび 1 つ以上のバック バッファが作成される。DirectDraw は、フロントバッファ サーフェスに DDSCAPS_FRONTBUFFER ビット、およびフロントバッファ サーフェスに隣接するサーフェスに DDSCAPS_BACKBUFFER ビットを設定する。メソッドの呼び出しが成功するためには、DDSURFACEDESC 構造体の dwBackBufferCount メンバを少なくとも 1 に設定する必要がある。CreateSurface メソッドで複数のサーフェスを作成する場合、DDSCAPS_COMPLEX 能力を常に設定しなくてはならない。
DDSCAPS_FRONTBUFFER
このサーフェスは、サーフェス フリッピング構造のフロント バッファである。このフラグは、一般には DDSCAPS_FLIP 能力を設定する際に CreateSurface メソッドによって設定される。この能力が CreateSurface メソッドに送られると、スタンドアロン フロント バッファが作成される。このサーフェスには DDSCAPS_FLIP 能力がない。このサーフェスは、IDirectDrawSurface7::AddAttachedSurface を使用することにより、バック バッファにアタッチしてフリッピング構造を形成できる。
DDSCAPS_HWCODEC
このサーフェスは、ハードウェアによって圧縮解除されたストリームを持つことができる。
DDSCAPS_LIVEVIDEO
このサーフェスは、ライブ ビデオを受け取ることができる。
DDSCAPS_LOCALVIDMEM
このサーフェスは、非ローカル ビデオ メモリではなく、真のローカル ビデオ メモリに存在する。このフラグを指定するときは、DDSCAPS_VIDEOMEMORY も指定しなければならない。このフラグは、DDSCAPS_NONLOCALVIDMEM フラグと共に使用できない。
DDSCAPS_MIPMAP
このサーフェスは、ミップマップの 1 つのレベルである。このサーフェスは、ほかの DDSCAPS_MIPMAP サーフェスにアタッチしてミップマップを形成できる。このようなミップマップの作成は、いくつかのサーフェスを作成し、それらのサーフェスを IDirectDrawSurface7::AddAttachedSurface メソッドでアタッチすることで明示的に行われるか、CreateSurface メソッドを使用して暗黙的に行われる。この能力を設定する場合、DDSCAPS_TEXTURE も設定しなくてはならない。
DDSCAPS_MODEX
このサーフェスは、320 × 200 または 320 × 240 のモード X サーフェスである。
DDSCAPS_NONLOCALVIDMEM
このサーフェスは、真のローカル ビデオ メモリではなく、非ローカル ビデオ メモリに存在する。このフラグを指定するときは、DDSCAPS_VIDEOMEMORY フラグも指定しなければならない。これは、DDSCAPS_LOCALVIDMEM フラグと共に使用することはできない。
DDSCAPS_OFFSCREENPLAIN
このサーフェスはオフスクリーン サーフェスであり、オーバーレイ、テクスチャ、Z バッファ、フロントバッファ、バックバッファ、またはアルファ サーフェスのいずれでもない。プレーン サーフェスを識別するために使用される。
DDSCAPS_OPTIMIZED
現時点では、実装されていない。
DDSCAPS_OVERLAY
このサーフェスは、オーバーレイであるこのサーフェスが直接表示できるかどうかは、現時点でプライマリ サーフェスにオーバーレイされているかどうかによって決まる。DDSCAPS_VISIBLE を使用して、サーフェスが現時点でオーバーレイされているかどうかを判断できる。
DDSCAPS_OWNDC
このサーフェスは、長時間にわたってデバイス コンテキスト (DC) と関連を持つ。
DDSCAPS_PALETTE
このデバイス ドライバを使用すると、固有の DirectDrawPalette オブジェクトを作成してこのサーフェスにアタッチできる。
DDSCAPS_PRIMARYSURFACE
サーフェスは、プライマリ サーフェスである。このサーフェスは現在の表示内容を表す。
DDSCAPS_STANDARDVGAMODE
このサーフェスは、標準 VGA モード サーフェスであり、モード X サーフェスではない。このフラグは、DDSCAPS_MODEX フラグの組み合わせで使用することはできない。
DDSCAPS_SYSTEMMEMORY
このサーフェス メモリは、システム メモリに割り当てられた。
DDSCAPS_TEXTURE
このサーフェスは、3D テクスチャとして使用できる。ただし、サーフェスが現在 3D テクスチャとして使用されているかどうかを示すものではない。
DDSCAPS_VIDEOMEMORY
このサーフェスは、ディスプレイ メモリにある。
DDSCAPS_VIDEOPORT
このサーフェスは、ビデオ ポートからデータを受け取ることができる。
DDSCAPS_VISIBLE
このサーフェスへの変更はすぐに表示できる。このサーフェスは、オーバーレイの際のオーバーレイや、テクスチャ処理の際のテクスチャ マップに対して設定されるほかにも、プライマリ サーフェスに対して常に設定される。
DDSCAPS_WRITEONLY
サーフェスへの書き込み専用アクセスが許可されている。サーフェスからの読み込みアクセスは、一般保護 (GP) エラーを発生する可能性がある。ただし、このサーフェスからの読み込み結果には意味がある。
DDSCAPS_ZBUFFER
.このサーフェスは、Z バッファである。z バッファには、表示されない情報を含む。代わりに、Z バッファには、どのピクセルが表示され、どのピクセルが表示されないかを決定するのに使用するビット深度情報を含む。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDSCAPS2

DDSCAPS2 構造体は、DirectDrawSurface オブジェクトの能力を定義する。この構造体は、DDSURFACEDESC2 構造体の一部である。

typedef struct _DDSCAPS2 {
    DWORD    dwCaps;
    DWORD    dwCaps2;
    DWORD    dwCaps3;
    DWORD    dwCaps4;
} DDSCAPS2, FAR* LPDDSCAPS2;

メンバ

dwCaps
サーフェスの能力を表す以下のフラグのうち、1 つまたは複数の値を指定する (このメンバのフラグは、DDSCAPS 構造体の対応するメンバのフラグと等しい)。
DDSCAPS_3D
未対応。代わりに DDSCAPS_3DDEVICE を使用する。
DDSCAPS_3DDEVICE
このサーフェスは、3D レンダリングに使用できる。アプリケーションはこのフラグを使い、デバイスが適切なヒープから割り当てられたオフスクリーン サーフェスのある特定のヒープだけをレンダリングできることを保証する。このフラグがヒープに対して設定されている場合、サーフェスはそのヒープから割り当てられない。
DDSCAPS_ALLOCONLOAD
未使用。
DDSCAPS_ALPHA
このサーフェスは、アルファ専用情報を含む。
DDSCAPS_BACKBUFFER
このサーフェスは、サーフェス フリッピング構造のバック バッファである。通常、この能力は、DDSCAPS_FLIP フラグが使用されるときに CreateSurface メソッドで設定される。DDSCAPS_FRONTBUFFER サーフェスの直前のサーフェスだけ、この能力が設定される。DDSCAPS_FLIP フラグの存在、アタッチの順序、および DDSCAPS_FRONTBUFFER と DDSCAPS_BACKBUFFER 能力の欠如により、別のサーフェスがバック バッファとして識別される。この能力が CreateSurface メソッドに送られると、スタンドアロン バック バッファを作成する。このメソッドを呼び出した後、このサーフェスは、フロント バッファ、別のバック バッファ、またはその両方にアタッチしてフリッピング サーフェス構造を形成できる。詳細については、「IDirectDrawSurface7::AddAttachedSurface」を参照すること。DirectDraw では、プリッピング構造にサーフェスはいくつでも存在できる。
DDSCAPS_COMPLEX
複合サーフェスが記述される。複合サーフェスは、2 つ以上のサーフェスから作成される。追加サーフェスは、ルート サーフェスにアタッチされる。複合サーフェスは、ルートを破棄するだけで破棄できる。
DDSCAPS_FLIP
このサーフェスは、サーフェス フリッピング構造の一部である。この能力が CreateSurface メソッドに渡されると、フロント バッファおよび 1 つ以上のバック バッファが作成される。DirectDraw は、フロントバッファ サーフェスに DDSCAPS_FRONTBUFFER ビット、およびフロントバッファ サーフェスに隣接するサーフェスに DDSCAPS_BACKBUFFER ビットを設定する。メソッドの呼び出しが成功するためには、DDSURFACEDESC 構造体の dwBackBufferCount メンバは少なくとも 1 に設定する必要がある。CreateSurface メソッドで複数のサーフェスを作成する場合、DDSCAPS_COMPLEX 能力を常に設定しなくてはならない。
DDSCAPS_FRONTBUFFER
このサーフェスは、サーフェス フリッピング構造のフロント バッファである。このフラグは、一般には DDSCAPS_FLIP 能力を設定する際に CreateSurface メソッドによって設定される。この能力が CreateSurface メソッドに送られると、スタンドアロン フロント バッファが作成される。このサーフェスには DDSCAPS_FLIP 能力がない。このサーフェスは、IDirectDrawSurface7::AddAttachedSurface を使用することにより、バック バッファにアタッチしてフリッピング構造を形成できる。
DDSCAPS_HWCODEC
このサーフェスは、ハードウェアによって圧縮解除されたストリームを持つことができる。
DDSCAPS_LIVEVIDEO
このサーフェスは、ライブ ビデオを受け取ることができる。
DDSCAPS_LOCALVIDMEM
このサーフェスは、非ローカル ビデオ メモリではなく、真のローカル ビデオ メモリに存在する。このフラグを指定するときは、DDSCAPS_VIDEOMEMORY も指定しなければならない。このフラグは、DDSCAPS_NONLOCALVIDMEM フラグと共に使用できない。
DDSCAPS_MIPMAP
このサーフェスは、ミップマップの 1 つのレベルである。このサーフェスは、ほかの DDSCAPS_MIPMAP サーフェスにアタッチしてミップマップを形成できる。このようなミップマップの作成は、いくつかのサーフェスを作成し、それらのサーフェスを IDirectDrawSurface7::AddAttachedSurface メソッドでアタッチすることで明示的に行われるか、CreateSurface メソッドを使用して暗黙的に行われる。この能力を設定する場合、DDSCAPS_TEXTURE も設定しなくてはならない。
DDSCAPS_MODEX
このサーフェスが、320 × 200 または 320 × 240 のモード X サーフェスである。
DDSCAPS_NONLOCALVIDMEM
このサーフェスは、真のローカル ビデオ メモリではなく、非ローカル ビデオ メモリに存在する。このフラグを指定するときは、DDSCAPS_VIDEOMEMORY フラグも指定しなければならない。これは、DDSCAPS_LOCALVIDMEM フラグと共に使用することはできない。
DDSCAPS_OFFSCREENPLAIN
このサーフェスは、オフスクリーン サーフェスであり、オーバーレイ、テクスチャ、Z バッファ、フロントバッファ、バックバッファ、またはアルファ サーフェスのいずれでもない。プレーン サーフェスを識別するために使用される。
DDSCAPS_OPTIMIZED
現時点では、実装されていない。
DDSCAPS_OVERLAY
このサーフェスは、オーバーレイである。このサーフェスが直接表示できるかどうかは、現時点でプライマリ サーフェスにオーバーレイされているかどうかによって決まる。DDSCAPS_VISIBLE を使用して、サーフェスが現時点でオーバーレイされているかどうかを判断できる。
DDSCAPS_OWNDC
このサーフェスは、長時間にわたってデバイス コンテキスト (DC) と関連を持つ。
DDSCAPS_PALETTE
このデバイス ドライバを使用すると、固有の DirectDrawPalette オブジェクトを作成してこのサーフェスにアタッチできる。
DDSCAPS_PRIMARYSURFACE
サーフェスは、プライマリ サーフェスである。このサーフェスは現在の表示内容を表す。
DDSCAPS_STANDARDVGAMODE
このサーフェスは、標準 VGA モード サーフェスであり、モード X サーフェスではない。このフラグは、DDSCAPS_MODEX フラグの組み合わせで使用することはできない。
DDSCAPS_SYSTEMMEMORY
このサーフェス メモリは、システム メモリに割り当てられた。
DDSCAPS_TEXTURE
このサーフェスは、3D テクスチャとして使用できる。ただし、サーフェスが現在 3D テクスチャとして使用されているかどうかを示すものではない。
DDSCAPS_VIDEOMEMORY
このサーフェスは、ディスプレイ メモリにある。
DDSCAPS_VIDEOPORT
このサーフェスは、ビデオ ポートからデータを受け取ることができる。
DDSCAPS_VISIBLE
このサーフェスへの変更はすぐに表示できる。このサーフェスは、オーバーレイの際のオーバーレイや、テクスチャ処理の際のテクスチャ マップに対して設定されるほかにも、プライマリ サーフェスに対して常に設定される。
DDSCAPS_WRITEONLY
サーフェスへの書き込み専用アクセスが許可されている。サーフェスからの読み込みアクセスは、一般保護 (GP) エラーを発生する可能性がある。ただし、このサーフェスからの読み込み結果には意味がある。
DDSCAPS_ZBUFFER
.このサーフェスは、Z バッファである。z バッファには、表示されない情報を含む。代わりに、Z バッファには、どのピクセルが表示され、どのピクセルが表示されないかを決定するのに使用するビット深度情報を含む。
dwCaps2
追加サーフェス能力。このメンバには以下の能力フラグを含めることができる。この構造体を IDirectDrawSurface7::SetSurfaceDesc メソッドで使用する場合は、サーフェス メモリが割り当てられた方法を示す追加フラグを含めることができる。

能力フラグ

DDSCAPS2_CUBEMAP
DirectX 7.0 で追加。このサーフェスは、キューブ環境マップである。このフラグを使用するときは、キューブ環境マップのどのサーフェスを作成するかも指定しなければならない。
DDSCAPS2_CUBEMAP_POSITIVEX
DirectX 7.0 で追加。このフラグは、DDSCAPS2_CUBEMAP フラグととも使用して、キューブ環境マップの正方向の X 面を作成する。
DDSCAPS2_CUBEMAP_NEGATIVEX
DirectX 7.0 で追加。このフラグは、DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの負方向の X 面を作成する。
DDSCAPS2_CUBEMAP_POSITIVEY
DirectX 7.0 で追加。このフラグは、DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの正方向の Y 面を作成する。
DDSCAPS2_CUBEMAP_NEGATIVEY
DirectX 7.0 で追加。このフラグは、DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの負方向の Y 面を作成する。
DDSCAPS2_CUBEMAP_POSITIVEZ
DirectX 7.0 で追加。このフラグは、DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの正方向の Z 面を作成する。
DDSCAPS2_CUBEMAP_NEGATIVEZ
DirectX 7.0 で追加。このフラグは、DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの負方向の Z 面を作成する。
DDSCAPS2_CUBEMAP_ALLFACES
DirectX 7.0 で追加。このフラグは、DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの全 6 面を作成する。
DDSCAPS2_D3DTEXTUREMANAGE
DirectX 7.0 で追加。テクスチャは、Direct3D によって常に管理される。
DDSCAPS2_DONOTPERSIST
DirectX 7.0 で追加。管理サーフェスは、安全に消失できる。
DDSCAPS2_HARDWAREDEINTERLACE
このサーフェスは、非インターレイス方式ハードウェアを使用するビデオ ポートからデータを受け取る。これにより、ドライバは要求がありそうな外部バッファにメモリを割り当てることができる。DDSCAPS_VIDEOPORT および DDSCAPS_OVERLAY フラグも設定しなくてはならない。
DDSCAPS2_HINTANTIALIASING
アプリケーションでアンチエイリアシングを使用する。DDSCAPS_3DDEVICE が同様に設定されている場合にだけ有効である。詳細については、「アンチエイリアシング」を参照すること。
DDSCAPS2_HINTDYNAMIC
このサーフェスは頻繁にロックされること (手続きテクスチャ、ダイナミック ライト マップなどのため) をドライバに示す。このフラグは、テクスチャ サーフェスに対してだけ使用できる (DDSCAPS_TEXTURE フラグは、dwCaps メンバに設定する)。このフラグは、DDSCAPS2_HINTSTATIC または DDSCAPS2_OPAQUE フラグと共に使用できない。
DDSCAPS2_HINTSTATIC
このサーフェスが、ロードにより再び整理されたり再びタイル表示できることをドライバに示す。この処理では、テクスチャのサイズを変更できない。アプリケーションはこれらのビットをロックできるので、この処理は比較的速く、左右対称に実行される (この際パフォーマンスが低下する)。このフラグは、テクスチャ サーフェスに対してだけ使用できる (DDSCAPS_TEXTURE フラグは、dwCaps メンバに設定する)。このフラグは、DDSCAPS2_HINTDYNAMIC または DDSCAPS2_OPAQUE フラグと共に使用できない。
DDSCAPS2_MIPMAPSUBLEVEL
DirectX 7.0 で追加。このフラグを使用すると、ルート サーフェスに複数のミップマップ サーフェスがアタッチされたキューブ マップなどのサーフェス構造においては、EnumAttachedSurfaces よりも GetAttachedSurface の方が簡単に使用できるようになる。このフラグは、ミップマップ化キューブ マップ内の最上位レベル以外のサーフェスすべてに設定する必要がある。これにより、GetAttachedSurface を呼び出したときに最上位レベル サーフェスとアタッチされたミップマップ レベルを区別できる。CreateSurface はこの能力ビットを無視する。
DDSCAPS2_OPAQUE
このサーフェスが、決して再ロックされないことをドライバに示す。ドライバは、再タイル表示および圧縮によって、このサーフェスを自由に最適化できる。このようなサーフェスはロックしたり、ブリット処理で使用することはできない。したがって、この能力でサーフェスをロックまたはブリットしようとすると失敗する。このフラグは、テクスチャ サーフェスに対してだけ使用できる (DDSCAPS_TEXTURE フラグは、dwCaps メンバに設定する)。このフラグは、DDSCAPS2_HINTDYNAMIC または DDSCAPS2_HINTSTATIC フラグと共に使用できない。
DDSCAPS2_STEREOSURFACELEFT
DirectX 7.0 で追加。このサーフェスは、ステレオ フリッピング チェーンの一部である。IDirectDraw7::CreateSurface の呼び出しでこのフラグを設定すると、プライマリ フリッピング チェーンの個々のバッファに対してステレオ サーフェスのペアが作成される。複合フリッピング チェーンを作成する必要がある (バック バッファで)。ステレオ サーフェスの単一セットを作成することはできない。IDirectDrawSurface7::Flip メソッドではバック バッファが必要なため、少なくとも 4 つのサーフェスを作成しなければならない。

また、このフラグを IDirectDraw7::EnumDisplayModes または IDirectDraw7::GetDisplayMode の呼び出しの結果として DDSURFACEDESC 構造体に設定すると、そのモードにおけるステレオのサポートが示される。

DDSCAPS2_TEXTUREMANAGE
ドライバに管理能力がある場合、クライアントはこのテクスチャ サーフェスをドライバで管理することを要求する。ドライバにその能力がない場合は、このテクスチャ サーフェスは Direct3D 直接モード (DirectX 7.0 での新機能) で管理される。このフラグは、テクスチャ サーフェスに対してだけ使用できる (DDSCAPS_TEXTURE フラグは、dwCaps メンバに設定する)。詳細については、Direct3D 直接モードのドキュメントの「自動テクスチャ管理」を参照すること。アプリケーションで Direct3D 保持モードを使用する場合は、このフラグを使用しないこと。代わりに、システム メモリにテクスチャを作成し、それらのテクスチャを保持モードで管理する。
dwCaps3、dwCaps4
現時点では、未使用である。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDSURFACEDESC

DDSURFACEDESC 構造体は、サーフェスの記述を含む。この構造体は、IDirectDraw2::CreateSurface メソッドに渡される。関係するメンバは、サーフェスの個々のタイプにより異なる。

IDirectDraw7 インターフェイスを使用する場合、このサーフェスは DDSURFACEDESC2 構造体によって置き換えられる。

typedef struct _DDSURFACEDESC {
    DWORD          dwSize;
    DWORD          dwFlags;
    DWORD          dwHeight;
    DWORD          dwWidth;
    union
    {
        LONG       lPitch;
        DWORD      dwLinearSize;
    };
    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;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwFlags
オプション制御フラグ。以下のフラグのうち、1 つ以上の値を取る。
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_LINEARSIZE
dwLinearSize メンバは有効である。
DDSD_LPSURFACE
lpSurface メンバは有効である。
DDSD_MIPMAPCOUNT
dwMipMapCount メンバは有効である。
DDSD_PITCH
lPitch メンバは有効である。
DDSD_PIXELFORMAT
ddpfPixelFormat メンバは有効である。
DDSD_REFRESHRATE
dwRefreshRate メンバは有効である。
DDSD_WIDTH
dwWidth メンバは有効である。
DDSD_ZBUFFERBITDEPTH
dwZBufferBitDepth メンバは有効である。
dwHeight、dwWidth
ピクセル単位で作成しようとするサーフェスのディメンジョン。
lPitch
次のラインの開始までのバイト単位の距離。IDirectDrawSurface7::GetSurfaceDesc メソッドを使用する場合、これは戻り値となる。既存のメモリからサーフェスを作成する場合、または IDirectDrawSurface7::SetSurfaceDesc メソッドを呼び出す場合、これは入力値となる。この入力値は DWORD の倍数でなければならない。
dwLinearSize
バッファのサイズ。現時点では、圧縮されたテクスチャ サーフェスのためだけに返される。
dwBackBufferCount
バック バッファの数。
dwMipMapCount
ミップマップ レベルの数。
dwZBufferBitDepth
Z バッファの深度。このメンバは、DirectX 6.0 以降のバージョンのために取得される。IDirect3D7::EnumZBufferFormats を使用して、サポートされる深度バッファ フォーマットの情報を取得する。
dwRefreshRate
リフレッシュ レート (ディスプレイ モードを記述する場合に使用)。この値が 0 の場合、アダプタ デフォルトを示す。
dwAlphaBitDepth
アルファ バッファの深度。
dwReserved
将来的な使用のために確保されている。
lpSurface
関連付けられたサーフェス メモリのアドレス。IDirectDrawSurface7::Lock を呼び出すと、呼び出しが戻った後、このメンバはサーフェス メモリへの有効なポインタを含む。既存のメモリからサーフェスを作成する場合、または IDirectDrawSurface7::SetSurfaceDesc メソッドを使用する場合、このメンバは入力値となる。この入力値とは、呼び出し側アプリケーションによって割り当てられたシステム メモリのアドレスである。アプリケーションがサーフェス メモリの割り当てや管理のために DirectDraw を必要とする場合、このメンバを設定できない。
ddckCKDestOverlay
オーバーレイ サーフェスの転送先カラー キーを記述する DDCOLORKEY 構造体。
ddckCKDestBlt
ブリット処理の転送先カラー キーを記述する DDCOLORKEY 構造体。
ddckCKSrcOverlay
オーバーレイ サーフェスの転送元カラー キーを記述する DDCOLORKEY 構造体。
ddckCKSrcBlt
ブリット処理の転送元カラー キーを記述する DDCOLORKEY 構造体。
ddpfPixelFormat
サーフェスのピクセル フォーマットを記述する DDPIXELFORMAT 構造体。
ddsCaps
サーフェスの能力を含む DDSCAPS 構造体。

注意

この構造体は DDSURFACEDESC2 構造体と類似しているが、DDSCAPS2 構造体ではなく ddsCaps メンバとして DDSCAPS 構造体を含んでいる。DDSURFACEDESC2 とは異なり、この構造体は dwZBufferBitDepth メンバを含む。

動作環境

Windows NT/2000 : Windows NT 4.0 Service Pack 3 またはそれ以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDSURFACEDESC2

DDSURFACEDESC2 構造体は、サーフェスの記述を含む。この構造体は、サーフェス パラメータを IDirectDraw7::CreateSurface および IDirectDrawSurface7::SetSurfaceDesc メソッドに渡すために使用される。この構造体は、また、IDirectDrawSurface7::Lock および IDirectDrawSurface7::GetSurfaceDesc の呼び出しでサーフェス情報を取得するために使用される。関係するメンバは、サーフェスの個々のタイプにより異なる。

typedef struct _DDSURFACEDESC2 {
    DWORD         dwSize;
    DWORD         dwFlags;
    DWORD         dwHeight;
    DWORD         dwWidth;
    union
    {
        LONG      lPitch;
        DWORD     dwLinearSize;
    } DUMMYUNIONNAMEN(1);
    DWORD         dwBackBufferCount;
    union
    {
        DWORD     dwMipMapCount;
        DWORD     dwRefreshRate;
    } DUMMYUNIONNAMEN(2);
    DWORD         dwAlphaBitDepth;
    DWORD         dwReserved;
    LPVOID        lpSurface;
    union
    {
        DDCOLORKEY    ddckCKDestOverlay;
        DWORD         dwEmptyFaceColor;
    } DUMMYUNIONNAMEN(3);
    DDCOLORKEY    ddckCKDestBlt;
    DDCOLORKEY    ddckCKSrcOverlay;
    DDCOLORKEY    ddckCKSrcBlt;
    DDPIXELFORMAT ddpfPixelFormat;
    DDSCAPS2      ddsCaps;
    DWORD         dwTextureStage;
} DDSURFACEDESC2, FAR* LPDDSURFACEDESC2;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwFlags
オプション制御フラグ。以下のフラグのうち、1 つ以上の値を取る。
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_LINEARSIZE
dwLinearSize メンバは有効である。
DDSD_LPSURFACE
IpSurface メンバは有効である。
DDSD_MIPMAPCOUNT
dwMipMapCount メンバは有効である。
DDSD_PITCH
IPitch メンバは有効である。
DDSD_PIXELFORMAT
ddpfPixelFormat メンバは有効である。
DDSD_REFRESHRATE
dwRefreshRate メンバは有効である。
DDSD_TEXTURESTAGE
dwTextureStage メンバは有効である。
DDSD_WIDTH
dwWidth メンバは有効である。
DDSD_ZBUFFERBITDEPTH
廃止。「注意」を参照すること。
dwHeight、dwWidth
ピクセル単位で作成しようとするサーフェスのディメンジョン。
lPitch
次のラインの開始までのバイト単位の距離。IDirectDrawSurface7：:GetSurfaceDesc メソッドを使用する場合、これは戻り値となる。IDirectDrawSurface7::SetSurfaceDesc メソッドと使用する場合、これは入力値となる。この入力値は DWORD の倍数でなくてはならない。詳細情報は注意を参照すること。
dwLinearSize
バッファのサイズ。現時点では、圧縮されたテクスチャサーフェスのためだけに返される。
dwBackBufferCount
バック バッファの数。
dwMipMapCount
ミップマップ レベルの数。
dwRefreshRate
リフレッシュ レート (ディスプレイ モードを記述する場合に使用)。この値が 0 の場合、アダプタ デフォルトを示す。
dwAlphaBitDepth
アルファ バッファの深度。
dwReserved
将来的な使用のために確保されている。
lpSurface
関連付けられたサーフェス メモリのアドレス。IDirectDrawSurface7::Lock を呼び出す場合、このメンバはサーフェス メモリへの有効なポインタとなる。IDirectDrawSurface7::SetSurfaceDesc を呼び出す場合、このメンバは呼び出し側が DirectDrawSurface オブジェクトに明示的に割り当てるシステム メモリへのポインタとなる。詳細情報は注意を参照すること。
ddckCKDestOverlay
オーバーレイ サーフェスの転送先カラー キーを記述する DDCOLORKEY 構造体。
dwEmptyFaceColor
空のキューブマップ面の物理的な色。
ddckCKDestBlt
ブリット処理の転送先カラー キーを記述する DDCOLORKEY 構造体。
ddckCKSrcOverlay
オーバーレイ サーフェスの転送元カラー キーを記述する DDCOLORKEY 構造体。
ddckCKSrcBlt
ブリット処理の転送元カラー キーを記述する DDCOLORKEY 構造体。
ddpfPixelFormat
サーフェスのピクセル フォーマットを記述する DDPIXELFORMAT 構造体。
ddsCaps
サーフェスの能力を含む DDSCAPS2 構造体。
dwTextureStage
マルチテクスチャ カスケード 3D デバイスの特定のステージにテクスチャをバインドするために使用するステージ識別子。すべてのハードウェアに必要ではないが、このメンバの設定は 3-D アクセラレータの多様性に対して、最適なパフォーマンスを与える。明示的に割り当てられたテクスチャを要求するハードウェアは、IDirect3DDevice7::GetCaps メソッドで値を設定する D3DDEVICEDESC 構造体の D3DDEVCAPS_SEPARATETEXTUREMEMORIES 3-D デバイス能力を公開する。

注意

IDirectDrawSurface7::GetSurfaceDesc メソッドを呼び出す場合、lPitch および lpSurface メンバは出力値となる。既存のメモリからサーフェスを作成したり、サーフェス特性を更新している場合、これらのメンバは入力値となる。この入力値は、DirectDraw で使用される呼び出し側のアプリケーションにより割り当てられたメモリのピッチと位置を記述する。DirectDraw は、アプリケーションが割り当てたメモリを管理したり解放しようとしない。詳細については、「クライアント メモリ サーフェスの作成」および「サーフェス特性の更新」を参照すること。

この構造体は DDSURFACEDESC 構造体とほぼ同じであるが、DDSCAPS2 構造体を ddsCaps メンバとして含む。DDSURFACEDESC とは異なり、この構造体は dwZBufferBitDepth メンバを含まない。Z バッファ深度は、ddpfPixelFormat メンバで提供される。

この構造体の集合は、名前のない集合をサポートしないコンパイラでも機能する。コンパイラが名前のない集合をサポートしない場合は、Ddraw.h ヘッダー ファイルをインクルードする前に NONAMELESSUNION トークンを定義する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : ddraw.h で宣言。


DDVIDEOPORTBANDWIDTH

DDVIDEOPORTBANDWIDTH 構造体は、特定のビデオポートとピクセルフォーマット構成と共に使用する場合、オーバーレイ サーフェスの帯域幅特性を記述する。この構造体は、IDirectDrawVideoPort::GetBandwidthInfo メソッドと共に使用される。

typedef struct _DDVIDEOPORTBANDWIDTH {
    DWORD dwSize;
    DWORD dwCaps;
    DWORD dwOverlay;
    DWORD dwColorkey;
    DWORD dwYInterpolate;
    DWORD dwYInterpAndColorkey;
    DWORD dwReserved1;
    DWORD dwReserved2;
} DDVIDEOPORTBANDWIDTH,*LPDDVIDEOPORTBANDWIDTH;

メンバ

dwSize
バイト単位のこの構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwCaps
デバイス依存を指定するフラグ値。このメンバは、以下のいずれか 1 つの値を取る。
DDVPBCAPS_DESTINATION
このデバイスの能力は、オーバーレイの最小伸縮係数の点から記述される。このデバイスに対して提供される帯域幅情報は、転送先オーバーレイ サイズに関連する。
DDVPBCAPS_SOURCE
このデバイスの能力は、要求される転送元オーバーレイサイズの観点から記述される。このデバイスに対して提供される帯域幅情報は、転送元オーバーレイ サイズに関連する。
dwOverlay
オーバーレイがサポートされる場所の伸縮係数、またはオーバーレイ転送元サイズを 1000 倍した値。たとえば、1.3 = 1300、あるいは .75 = 750。
dwColorkey
カラー キーイングのあるオーバーレイがサポートされる伸縮係数、またはオーバーレイ転送元サイズを 1000 倍した値。たとえば、1.3 = 1300、あるいは .75 = 750。
dwYInterpolate
y 軸補間のあるオーバーレイがサポートされる場所の伸縮係数、またはオーバーレイ転送元サイズを 1000 倍した値。たとえば、1.3 = 1300、あるいは .75 = 750。
dwYInterpAndColorkey
y 軸補間およびカラー キーイングのあるオーバーレイがサポートされる場所の伸縮係数、またはオーバーレイ転送元サイズを 1000 倍した値。たとえば、1.3 = 1300、あるいは .75 = 750。
dwReserved1、dwReserved2
今後のために確保されている。0 を設定する。

注意

DDVPBCAPS_DESTINATION を指定すると、他のメンバで記述される伸縮係数は、GetBandwidthInfo メソッドの呼び出しで与えられるディメンジョンでオーバーレイを表示するのに必要となる最小伸縮係数を記述する。伸縮係数値が 1000 未満の場合、表示の際にビデオ ポートはオーバーレイを収縮する能力を持つ。伸縮係数値が 1000 を超える場合は、オーバーレイを表示するためにオーバーレイを伸縮して転送元より大きくする必要がある。

DDVPBCAPS_SOURCE を指定すると、ほかのメンバに記述されている伸縮係数は、オーバーレイを表示するためにオーバーレイ転送元をどれくらい収縮する必要があるかを示す。この場合、最適値は 1000 で、収縮が必要ないことを意味する。値が 1000 より小さい場合、GetBandwidthInfo の呼び出しの際に指定した転送元矩形が大きすぎることを意味する。たとえば、伸縮係数が 750 で dwWidth パラメータに 320 ピクセルを指定した場合、そのサイズではオーバーレイを表示できない。オーバーレイを表示するには、240 ピクセル幅の転送元矩形を使用しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。


DDVIDEOPORTCAPS

DDVIDEOPORTCAPS 構造体は、ビデオ ポートの能力とアライメント制限を記述する。この構造体は、IDDVideoPortContainer::EnumVideoPorts メソッドと共に使用される。

typedef struct _DDVIDEOPORTCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwMaxWidth;
    DWORD dwMaxVBIWidth;
    DWORD dwMaxHeight;
    DWORD dwVideoPortID;
    DWORD dwCaps;
    DWORD dwFX;
    DWORD dwNumAutoFlipSurfaces;
    DWORD dwAlignVideoPortBoundary;
    DWORD dwAlignVideoPortPrescaleWidth;
    DWORD dwAlignVideoPortCropBoundary;
    DWORD dwAlignVideoPortCropWidth;
    DWORD dwPreshrinkXStep;
    DWORD dwPreshrinkYStep;
    DWORD dwNumVBIAutoFlipSurfaces;
    DWORD dwNumPreferredAutoflip;
    WORD  wNumFilterTapsX;
    WORD  wNumFilterTapsY;
} DDVIDEOPORTCAPS, *LPDDVIDEOPORTCAPS;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなければならない。
dwFlags
有効なデータを含むフィールドを示すフラグ値。以下のフラグが定義されている。
DDVPD_AUTOFLIP
dwNumAutoFlipSurfaces メンバは有効である。
DDVPD_ALIGN
dwAlignVideoPortBoundary、dwAlignVideoPortPrescaleWidth、dwAlignVideoPortCropBoundary、および dwAlignVideoPortCropWidth メンバは有効である。
DDVPD_CAPS
dwCaps メンバは有効である。
DDVPD_FILTERQUALITY
wNumFilterTapsX および wNumFilterTapsY メンバは有効である。
DDVPD_FX
dwFX メンバは有効である。
DDVPD_HEIGHT
dwMaxHeight メンバは有効である。
DDVPD_ID
dwVideoPortID メンバは有効である。
DDVPD_PREFERREDAUTOFLIP
dwNumPreferredAutoflip メンバは有効である。
DDVPD_WIDTH
dwMaxWidth メンバは有効である。
dwMaxWidth
ビデオポート フィールドの最大幅。
dwMaxVBIWidth
VBI データの最大幅。
dwMaxHeight
ビデオ ポート フィールドの最大高さ。
dwVideoPortID
ビデオ ポートを識別するゼロベースのインデックス。
dwCaps
以下に、ビデオポート能力を示す。
DDVPCAPS_AUTOFLIP
VREF の際、テアリングを防止するためにフリップを自動的に実行する。データがメモリ内でインターリーブされている場合、VREF の 1 回おきにフリップする。
DDVPCAPS_COLORCONTROL
フレーム バッファに書き込む前に、到着データにカラー コントロール処理を行える。
DDVPCAPS_INTERLACED
インターレイス方式ビデオをサポートする。
DDVPCAPS_NONINTERLACED
非インターレイス方式ビデオをサポートする。
DDVPCAPS_OVERSAMPLEDVBI
一般のビデオ データとは異なるフォーマットまたは幅の VBI データを受け取る。
DDVPCAPS_READBACKFIELD
IDirectDrawVideoPort::GetFieldPolarity メソッドをサポートする。
DDVPCAPS_READBACKLINE
IDirectDrawVideoPort::GetVideoLine メソッドをサポートする。
DDVPCAPS_SHAREABLE
ビデオ ポートを共有する 2 つのゲンロッキング ビデオ ストリームをサポートする。一方のストリームは偶数フィールドを使用し、もう一方のストリームは奇数フィールドを使用する。各パラメータ (アドレス、スケーリング、クロッピングなど) はそれぞれのフィールドに対して維持される。
DDVPCAPS_SKIPEVENFIELDS
ビデオの偶数フィールドを自動的に破棄できる。
DDVPCAPS_SKIPODDFIELDS
ビデオの奇数フィールドを自動的に破棄できる。
DDVPCAPS_SYNCMASTER
ビデオ ポート同期に基づいてグラフィックス同期 (リフレッシュ レート) を実行できる。
DDVPCAPS_SYSTEMMEMORY
システム メモリに作成されたサーフェスに書き込みを実行できる。
DDVPCAPS_VBIANDVIDEOINDEPENDENT
ビデオ ストリームの VBI およびビデオ部分は、独立したプロセスで制御できる。
DDVPCAPS_VBISURFACE
VBI 内のデータを別のサーフェスに書き込むことができる。
dwFX
以下に、追加ビデオポート能力を示す。
DDVPFX_CROPTOPDATA
VBI データをくり抜くために、制限付きクロッピングが利用できる。
DDVPFX_CROPX
サーフェスに書き込まれる前に、到着データを x 方向にくり抜ける。
DDVPFX_CROPY
サーフェスに書き込まれる前に、到着データを y 方向にくり抜ける。
DDVPFX_IGNOREVBIXCROP
オーバーサンプルされる VBI データをくり抜く場合、ビデオ ポートは左右のクロッピング座標を無視できる。
DDVPFX_INTERLEAVE
メモリのインターレイス フィールドのインターリーブをサポートする。
DDVPFX_MIRRORLEFTRIGHT
ビデオ データをフレーム バッファに書き込む際に、左右のミラーリングをサポートする。
DDVPFX_MIRRORUPDOWN
ビデオ データをフレーム バッファに書き込む際に、上下のミラーリングをサポートする。
DDVPFX_PRESHRINKX
サーフェスに記述される前に、データは x 方向に任意に収縮できる。
DDVPFX_PRESHRINKY
サーフェスに記述される前に、データは y 方向に任意に収縮できる。
DDVPFX_PRESHRINKXB
サーフェスに記述される前に、データは x 方向にバイナリ収縮 (1/2、1/4、1/8 など) できる。
DDVPFX_PRESHRINKYB
サーフェスに記述される前に、データは y 方向にバイナリ収縮 (1/2、1/4、1/8 など) できる。
DDVPCAPS_PRESHRINKXS
データは x 方向に 1/x のインクリメントで収縮できる。ここで、x は dwShrinkXStep メンバで指定される。
DDVPCAPS_PRESHRINKYS
データは y 方向に 1/y のインクリメントで収縮できる。ここで、y は dwShrinkYStep メンバで指定される。
DDVPFX_PRESTRETCHX
サーフェスに記述される前に、データは x 方向に任意に伸縮できる。
DDVPFX_PRESTRETCHY
サーフェスに記述される前に、データは y 方向に任意に伸縮できる。
DDVPFX_PRESTRETCHXN
サーフェスに書き込む前に、データは x 方向に整数伸縮できる (1 ×、2 ×、3 ×など)。
DDVPFX_PRESTRETCHYN
サーフェスに書き込む前に、データは y 方向に整数伸縮できる (1 ×、2 ×、3 ×など)。
DDVPFX_VBICONVERT
VBI 内のデータを残りのビデオ データとは無関係に変換できる。
DDVPFX_VBINOINTERLEAVE
インターリーブは、VBI のデータに対して無効にされる。
DDVPFX_VBINOSCALE
スケーリングは、VBI 内のデータに対して無効にされる。
dwNumAutoFlipSurfaces
ビデオ ポートがサポートする自動フリップ可能なサーフェスの最大数。
dwAlignVideoPortBoundary
サーフェス内の配置のバイト制限。
dwAlignVideoPortPrescaleWidth
プリスケーリング後の幅のバイト制限。
dwAlignVideoPortCropBoundary
左クロッピングのバイト制限。
dwAlignVideoPortCropWidth
クロッピング幅のバイト制限。
dwPreshrinkXStep
1/dwPreshrinkXStep のステップで、幅を x 方向に収縮できる。
dwPreshrinkYStep
1/dwPreshrinkYSte のステップで、高さを y 方向に収縮できる。
dwNumVBIAutoFlipSurfaces
残りのビデオ ストリームに依存せずに、垂直帰線消去間隔 (VBI) の間に転送されたデータの受け取りが可能な自動フリッピング サーフェスの数。自動フリッピング チェーンを構築する場合、VBI サーフェスの数は、残りのビデオ データを受け取るサーフェスの数と等しくする必要がある。
dwNumPreferredAutoflip
ハードウェアがサポートする自動フリップ可能サーフェスの最適な数。
wNumFilterTapsX、wNumFilterTapsY
プレスケール フィルタが x および y 方向で使用するタップ数。たとえば、値が 0 だと、プレスケーリングはその方向で実行されない。値が 1 だと、プレスケールは対応する数で実行する。値が 2 だと、プレスケールは 2 つのタップを使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。


DDVIDEOPORTCONNECT

DDVIDEOPORTCONNECT 構造体は、ビデオ ポート コネクションを記述する。この構造体は、IDDVideoPortContainer::GetVideoPortConnectInfo メソッドと共に使用する。

typedef struct _DDVIDEOPORTCONNECT{
    DWORD dwSize;
    DWORD dwPortWidth;
    GUID  guidTypeID;
    DWORD dwFlags;
    ULONG_PTR dwReserved1;
} DDVIDEOPORTCONNECT,*LPDDVIDEOPORTCONNECT;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwPortWidth
ビデオポートの幅。この値は、メモリのサーフェスの幅ではなく、ビデオ ポートの物理ピンの数を表す。このメンバは、guidTypeID の値がある定まったサイズを取る場合でも、常に設定しなくてはならない。
guidTypeID
ビデオ ポートの同期特性を記述する GUID。次のポート タイプがあらかじめ定義されている。
DDVPTYPE_E_HREFH_VREFH
HREF がアクティブ ハイで、VREF がアクティブ ハイである場所の外部同期。
DDVPTYPE_E_HREFH_VREFL
HREF がアクティブ ハイで、VREF がアクティブ ローである場所の外部同期。
DDVPTYPE_E_HREFL_VREFH
HREF がアクティブ ローで、VREF がアクティブ ハイである場所の外部同期。
DDVPTYPE_E_HREFL_VREFL
HREF がアクティブ ローで、VREF がアクティブ ローである場所の外部同期。
DDVPTYPE_CCIR656
CCIR656 仕様に従って、データ ストリームに同期情報を組み込む。
DDVPTYPE_BROOKTREE
Brooktree 定義を使って、データ ストリームに同期情報を組み込む。
DDVPTYPE_PHILIPS
Philips 定義を使って、データ ストリームに同期情報を組み込む。
dwFlags
ビデオポート コネクションの能力を記述するフラグ。このメンバは、コネクション情報を取得するときに DirectDraw により、またはコネクション情報を設定するときにクライアントにより設定できる。このメンバは、次のフラグの組み合わせとなる。
DDVPCONNECT_DOUBLECLOCK
ビデオ ポートはダブルクロッキング データをサポートするか、データをダブルクロックする必要がある。このフラグは、外部同期だけに有効である。
DDVPCONNECT_VACT
ビデオ ポートは外部 VACT 信号の使用をサポートするか、外部 VACT 信号を使用する必要がある。このフラグは、外部同期だけに有効である。
DDVPCONNECT_INVERTPOLARITY
ビデオ ポートはフィールド極性を反転する能力を持つか、フィールド極性を反転する。

ビデオ ポートがフィールド極性を反転させる場合、偶数フィールドを奇数フィールドとして処理し、逆の場合も同様である。

DDVPCONNECT_DISCARDSVREFDATA
ビデオ ポートは VREF の間に書き込まれたデータを破棄し、データがフレーム バッファに書き込まれないようにする。このフラグは読み込み専用である。
DDVPCONNECT_HALFLINE
ビデオ ポートはフレーム バッファにハーフ ラインを書き込む。これにより、場合によってはデータが正しく表示されないことがある。このフラグは読み込み専用である。
DDVPCONNECT_INTERLACED
信号がインターレイスされる。このフラグは、ビデオ ポート オブジェクトを作成する場合にクライアントだけが使用する。
DDVPCONNECT_SHAREEVEN
物理ビデオ ポートは共有可能で、このビデオポート オブジェクトは偶数フィールドを使用する。このフラグは、ビデオポート オブジェクトを作成する際にクライアントでのみ使用する。
DDVPCONNECT_SHAREODD
物理ビデオ ポートは共有可能で、このビデオ ポート オブジェクトは奇数フィールドを使用する。このフラグは、ビデオポート オブジェクトを作成する際にクライアントでのみ使用する。
dwReserved1
今後のために確保されている。0 を設定する。

注意

この構造体は、独立して DDVIDEOPORTDESC 構造体のメンバとして使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。


DDVIDEOPORTDESC

DDVIDEOPORTDESC 構造体は、作成しようとするビデオポート オブジェクトを記述する。この構造体は、IDDVideoPortContainer::CreateVideoPort メソッドと共に使用される。

typedef struct _DDVIDEOPORTDESC {
    DWORD dwSize;
    DWORD dwFieldWidth;
    DWORD dwVBIWidth;
    DWORD dwFieldHeight;
    DWORD dwMicrosecondsPerField;
    DWORD dwMaxPixelsPerSecond;
    DWORD dwVideoPortID;
    DWORD dwReserved1;
    DDVIDEOPORTCONNECT VideoPortType;
    ULONG_PTR dwReserved2;
    ULONG_PTR dwReserved3;
 } DDVIDEOPORTDESC, *LPDDVIDEOPORTDESC;

メンバ

dwSize
バイト単位の構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwFieldWidth
ピクセル単位の到着ビデオ ストリームの幅。
dwVBIWidth
ピクセル単位の到着ビデオ ストリームにおける VBI データの幅。
dwFieldHeight
走査線で表す、到着ビデオ ストリームのフィールドのフィールド高さ。
dwMicrosecondsPerField
ミリ秒単位のライブ ビデオ VREF 周期の時間間隔。この数は、もっとも近いミリ秒に切り上げる。
dwMaxPixelsPerSecond
秒ごとの最大ピクセル率。
dwVideoPortID
使用する物理ビデオ ポートのゼロベースの ID。
dwReserved1
今後のために確保されている。0 を設定する。
VideoPortType
ビデオ ポートのコネクション特性を記述する DDVIDEOPORTCONNECT 構造体。
dwReserved2、dwReserved3
今後のために確保されている。0 を設定する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。


DDVIDEOPORTINFO

DDVIDEOPORTINFO 構造体は、サーフェスへのビデオ データの転送を記述する。この構造体は、IDirectDrawVideoPort::StartVideo メソッドと共に使用される。

typedef struct _DDVIDEOPORTINFO{
    DWORD dwSize;
    DWORD dwOriginX;
    DWORD dwOriginY;
    DWORD dwVPFlags;
    RECT rCrop;
    DWORD dwPrescaleWidth;
    DWORD dwPrescaleHeight;
    LPDDPIXELFORMAT lpddpfInputFormat;
    LPDDPIXELFORMAT lpddpfVBIInputFormat;
    LPDDPIXELFORMAT lpddpfVBIOutputFormat;
    DWORD dwVBIHeight;
    ULONG_PTR dwReserved1;
    ULONG_PTR dwReserved2;
} DDVIDEOPORTINFO,*LPDDVIDEOPORTINFO;

メンバ

dwSize
バイト単位のこの構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
dwOriginX、dwOriginY
サーフェスのビデオ データにおける起点の x 座標および y 座標。
dwVPFlags
以下に、ビデオポート オプションを示す。
DDVP_AUTOFLIP
自動フリッピングを実行する。詳細については、「自動フリッピング」を参照すること。
DDVP_CONVERT
lpddpfVBIOutputFormat メンバの情報を使って変換を実行する。
DDVP_CROP
rCrop メンバが指定する矩形を使ってクロッピングを実行する。
DDVP_IGNOREVBIXCROP
VBI データをクロッピングする場合、ビデオ ポートは左右のクロッピング座標を無視する。
DDVP_INTERLEAVE
インターレイスされたフィールドをメモリでインターリーブする。
DDVP_MIRRORLEFTRIGHT
フレーム バッファに書き込まれる際、イメージ データを左から右へミラー化する。
DDVP_MIRRORUPDOWN
フレーム バッファに書き込まれる際、イメージ データを上から下へミラー化する。
DDVP_OVERRIDEBOBWEAVE
オーバーレイ サーフェスを作成するときに、呼び出し側で設定するディスプレイ メソッドだけを使用して、ドライバにより選択される自動ディスプレイ メソッドをオーバーライドする。
DDVP_PRESCALE
dwPrescaleHeight および dwPrescaleWidth メンバの値に基づいて、プレスケーリングまたはプレズーミングを実行する。
DDVP_SKIPEVENFIELDS
偶数フィールドの入力を無視する。
DDVP_SKIPODDFIELDS
奇数フィールドの入力を無視する。
DDVP_SYNCMASTER
ビデオ ポート VREF は、ビデオ ポートへのリフレッシュ レートをロックして、グラフィックス VREF を実行する必要がある。
DDVP_VBICONVERT
lpddpfVBIOutputFormat メンバは、VBI データの変換に使用するデータを含む。
DDVP_VBINOSCALE
VBI データはスケーリングを行わない。
DDVP_VBINOINTERLEAVE
インターリーブは、VBI のデータに対して無効にされる。
rCrop
クロッピング矩形。このメンバはオプションである。
dwPrescaleWidth
x 方向でのプレスケーリングまたはズーミング。このメンバはオプションである。
dwPrescaleHeight
y 方向でのプレスケーリングまたはズーミング。このメンバはオプションである。
lpddpfInputFormat
ビデオ ポートに書き込むピクセル フォーマットを記述する DDPIXELFORMAT 構造体。多くの場合、サーフェスのピクセル フォーマットと同じであるが、ビデオ ポートが変換を実行する場合には異なるときもある。
lpddpfVBIInputFormat、lpddpfVBIOutputFormat
垂直帰線消去間隔内のデータの出力ピクセル フォーマットを記述する DDPIXELFORMAT 構造体。
dwVBIHeight
走査線で表す、垂直帰線消去間隔内のデータ量。
dwReserved1、dwReserved2
今後のために確保されている。0 を設定する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。


DDVIDEOPORTSTATUS

DDVIDEOPORTSTATUS 構造体は、ビデオポート オブジェクトのステータスを記述する。この構造体は、IDDVideoPortContainer::QueryVideoPortStatus メソッドととも使用される。

typedef struct _DDVIDEOPORTSTATUS {
    DWORD dwSize;
    BOOL  bInUse;
    DWORD dwFlags;
    DWORD dwReserved1;
    DDVIDEOPORTCONNECT VideoPortType;
    ULONG_PTR dwReserved2;
    ULONG_PTR dwReserved3;
} DDVIDEOPORTSTATUS, *LPDDVIDEOPORTSTATUS;

メンバ

dwSize
バイト単位のこの構造体のサイズ。このメンバは、構造体を使用する前に初期化しなくてはならない。
bInUse
ビデオ ポートの現在のステータスを示す値。このメンバは、ビデオ ポートが現在使用中であれば TRUE となり、それ以外は FALSE となる。
dwFlags
以下のフラグのうち、1 つ以上の値を取る。
DDVPSTATUS_VBIONLY
ビデオポート インターフェイスは、ビデオ ストリームの VBI 部分のみ制御する。
DDVPSTATUS_VIDEOONLY
ビデオポート インターフェイスは、ビデオ ストリームのビデオ部分のみ制御する。
dwReserved1
今後のために確保されている。0 を設定する。
VideoPortType
ビデオポート コネクション情報を受け取る DDVIDEOPORTCONNECT 構造体。
dwReserved2、dwReserved3
今後のために確保されている。0 を設定する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dvp.h で宣言。


戻り値

エラーは負の値で表され、組み合わされることはない。このテーブルは、IDirectDraw7、IDirectDrawSurface7、IDirectDrawPalette、IDirectDrawClipper、IDDVideoPortContainer、および IDirectDrawVideoPort インターフェイスのすべてのメソッドにより返される可能性のある値を一覧表示している。個々のメソッドが返す可能性のあるエラー コードのリストは、そのメソッドの記述を参照すること。

DD_OK
要求は成功し完了した。
DDERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DDERR_BLTFASTCANTCLIP
DirectDrawClipper オブジェクトは、IDirectDrawSurface7::BltFast メソッドの呼び出しに渡された転送元サーフェスにアタッチされている。
DDERR_CANNOTATTACHSURFACE
要求されたサーフェスにはサーフェスをアタッチできない。
DDERR_CANNOTDETACHSURFACE
要求されたサーフェスからサーフェスのアタッチを解除できない。
DDERR_CANTCREATEDC
Windows はこれ以上デバイス コンテキスト (DC) を作成できない。また、サーフェスにパレットがなく、ディスプレイ モードがインデック付きのパレットでない場合に、DC がインデックス付きパレット サーフェスを要求した (この場合、DirectDraw は DC に適切なパレットを選択できない)。
DDERR_CANTDUPLICATE
プライマリ サーフェス、3D サーフェス、暗に作られるサーフェスは複製できない。
DDERR_CANTLOCKSURFACE
DCI サポートなしでプライマリ サーフェスをロックしようとしたため、このサーフェスへのアクセスが拒否された。
DDERR_CANTPAGELOCK
サーフェスのページロックが失敗した。ページ ロックは、ディスプレイメモリ サーフェスまたはエミュレートされたプライマリ サーフェスでは作用しない。
DDERR_CANTPAGEUNLOCK
サーフェスのページロックの解除が失敗した。ページ ロックの解除は、ディスプレイメモリ サーフェスまたはエミュレートされたプライマリ サーフェスでは作用しない。
DDERR_CLIPPERISUSINGHWND
ウィンドウ ハンドルを既に監視している DirectDrawClipper オブジェクトに対して、クリップ リストを設定しようとした。
DDERR_COLORKEYNOTSET
この処理に対して、転送元カラー キーが指定されていない。
DDERR_CURRENTLYNOTAVAIL
現時点ではサポートされていない。
DDERR_DDSCAPSCOMPLEXREQUIRED
DirectX 7.0 で追加。サーフェスが DDSCAPS_COMPLEX フラグを要求している。
DDERR_DCALREADYCREATED
デバイス コンテキスト (DC) は既にこのサーフェスに対して返されている。1 サーフェスにつき 1 つの DC しか取得することはできない。
DDERR_DEVICEDOESNTOWNSURFACE
1 つの DirectDraw デバイスで作成されたサーフェスは、別の DirectDraw デバイスで直接使用することはできない。
DDERR_DIRECTDRAWALREADYCREATED
このドライバを表す DirectDraw オブジェクトが、このプロセスで既に作成されていることを表す。
DDERR_EXCEPTION
要求された処理を実行する間に例外が発生した。
DDERR_EXCLUSIVEMODEALREADYSET
既に排他モードが設定されているにもかかわらず、協調レベルを設定しようとした。
DDERR_EXPIRED
データが終了したので、有効でなくなった。
DDERR_GENERIC
未定義のエラー状態である。
DDERR_HEIGHTALIGN
提供された矩形の高さは、必要とされるアライメントの倍数ではない。
DDERR_HWNDALREADYSET
DirectDraw 協調レベル ウィンドウ ハンドルが既に設定されている。ウィンドウ ハンドルは、プロセスがサーフェスあるいは作成されたパレットを保持している間はリセットできない。
DDERR_HWNDSUBCLASSED
DirectDraw 協調レベル ウィンドウ ハンドルがサブクラス化されているため、DirectDraw の状態のリストアが阻止された。
DDERR_IMPLICITLYCREATED
サーフェスが暗に作成されたために、サーフェスをリストアできない。
DDERR_INCOMPATIBLEPRIMARY
プライマリ サーフェスの作成要求が既存のプライマリ サーフェスと一致していない。
DDERR_INVALIDCAPS
コールバック関数に渡された 1 つ以上の能力ビットが不正である。
DDERR_INVALIDCLIPLIST
DirectDraw は、提供されたクリップ リストをサポートしない。
DDERR_INVALIDDIRECTDRAWGUID
DirectDrawCreate 関数に渡されるグローバル ユニーク識別子 (GUID) が有効な DirectDraw ドライバ識別子でない。
DDERR_INVALIDMODE
DirectDraw は要求されたモードをサポートしない。
DDERR_INVALIDOBJECT
DirectDraw が、無効な DirectDraw オブジェクトのポインタを受け取った。
DDERR_INVALIDPARAMS
メソッドに渡された 1 つ以上のパラメータが不正である。
DDERR_INVALIDPIXELFORMAT
指定されたピクセル フォーマットが無効である。
DDERR_INVALIDPOSITION
転送先のオーバーレイの位置が不正である。
DDERR_INVALIDRECT
提供された矩形が無効である。
DDERR_INVALIDSTREAM
指定されたストリームに無効なデータを含む。
DDERR_INVALIDSURFACETYPE
サーフェスの種類が間違っている。
DDERR_LOCKEDSURFACES
1 つ以上のサーフェスがロックされており、要求された処理に失敗した。
DDERR_MOREDATA
指定されたバッファ サイズに保持できる以上のデータが存在する。
DDERR_NEWMODE
DirectX 7.0 で追加。DDSMT_ISTESTREQUIRED フラグで IDirectDraw7::StartModeTest を呼び出すと、解像度の一部またはすべてをテストできる、あるいはテストする必要があることを示すこの値が返される。IDirectDraw7::EvaluateMode は、テストが新しいディスプレイ モードに切り替わったことを示すこの値を返す。
DDERR_NO3D
3-D ハードウェアまたはエミュレーションが存在しない。
DDERR_NOALPHAHW
アルファアクセラレート ハードウェアが存在しないか利用できなかったため、要求された処理に失敗した。
DDERR_NOBLTHW
ブリット ハードウェアが存在しない。
DDERR_NOCLIPLIST
利用可能なクリップ リストがない。
DDERR_NOCLIPPERATTACHED
DirectDrawClipper オブジェクトがサーフェス オブジェクトにアタッチできない。
DDERR_NOCOLORCONVHW
色変換ハードウェアが存在しない、または利用できない。
DDERR_NOCOLORKEY
サーフェスに現在のカラー キーがない。
DDERR_NOCOLORKEYHW
転送先カラー キーに対するハードウェア サポートがない。
DDERR_NOCOOPERATIVELEVELSET
IDirectDraw7::SetCooperativeLevel メソッドを使用せずに作成関数が呼び出された。
DDERR_NODC
このサーフェスに対して、デバイス コンテキスト (DC) が作成されていない。
DDERR_NODDROPSHW
DirectDraw ラスタ処理 (ROP) ハードウェアが利用できない。
DDERR_NODIRECTDRAWHW
ハードウェア専用 DirectDraw オブジェクトを作成できない。ドライバはハードウェアをサポートしない。
DDERR_NODIRECTDRAWSUPPORT
現在のディスプレイ ドライバは DirectDraw をサポートしない。
DDERR_NODRIVERSUPPORT
DirectX 7.0 で追加。ディスプレイ アダプタ ドライバがリフレッシュ レートを列挙しないため、テストを実行できない。
DDERR_NOEMULATION
ソフトウェア エミュレーションが利用できない。
DDERR_NOEXCLUSIVEMODE
アプリケーションに対して排他モードが要求されたが、アプリケーションには排他モードがない。
DDERR_NOFLIPHW
表示されるサーフェスをフリッピングできない。
DDERR_NOFOCUSWINDOW
最初にフォーカス ウィンドウを設定せずにデバイス ウィンドウを設定または作成しようとした。
DDERR_NOGDI
GDI が存在しない。
DDERR_NOHWND
クリッパー通知がウィンドウ ハンドルを必要とする、あるいはウィンドウ ハンドルが協調レベル ウィンドウ ハンドルとしてあらかじめ設定されていない。
DDERR_NOMIPMAPHW
ミップマップ能力を持つテクスチャ マッピング ハードウェアが存在しない、または利用できない。
DDERR_NOMIRRORHW
ミラーリング ハードウェアが存在しない、または利用できない。
DDERR_NOMONITORINFORMATION
DirectX 7.0 で追加。関連付けられた EDID データがモニタに存在しないため、テストを実行できない。
DDERR_NONONLOCALVIDMEM
非ローカル ビデオ メモリをサポートしないデバイスから、非ローカル ビデオ メモリを割り当てようとした。
DDERR_NOOPTIMIZEHW
デバイスは、最適化されたサーフェスをサポートしない。
DDERR_NOOVERLAYDEST
転送先として確立するために IDirectDrawSurface7::UpdateOverlay メソッドが呼び出されなかったオーバーレイにおいて、IDirectDrawSurface7::GetOverlayPosition メソッドが呼び出されている。
DDERR_NOOVERLAYHW
オーバーレイ ハードウェアが存在しない、または利用できない。
DDERR_NOPALETTEATTACHED
パレット オブジェクトをこのサーフェスにアタッチできない。
DDERR_NOPALETTEHW
16 色あるいは 256 色のパレットに対するハードウェア サポートがない。
DDERR_NORASTEROPHW
適切なラスタ処理ハードウェアが存在しない、または利用できない。
DDERR_NOROTATIONHW
回転ハードウェアが存在しない、または利用できない。
DDERR_NOSTEREOHARDWARE
ステレオ ハードウェアが存在しない、または利用できない。
DDERR_NOSTRETCHHW
伸縮に対するハードウェア サポートがない。
DDERR_NOSURFACELEFT
ステレオ サーフェスをサポートするハードウェアが存在しない。
DDERR_NOT4BITCOLOR
DirectDrawSurface オブジェクトは、4 ビット色パレットを使用していない。また、要求された処理は 4 ビット色パレットを要求する。
DDERR_NOT4BITCOLORINDEX
DirectDrawSurface オブジェクトは、4 ビット カラー インデックス パレットを使用していない。また、要求された処理は 4 ビット カラー インデックス パレットを要求する。
DDERR_NOT8BITCOLOR
DirectDrawSurface オブジェクトは、8 ビット色パレットを使用していない。また、要求された処理は 8 ビット色パレットを要求する。
DDERR_NOTAOVERLAYSURFACE
非オーバーレイ サーフェスに対して、オーバーレイ成分が呼び出されている。
DDERR_NOTEXTUREHW
テクスチャマッピング ハードウェアが存在しないか利用できないため、処理を実行できない。
DDERR_NOTFLIPPABLE
フリップできないサーフェスをフリップしようとした。
DDERR_NOTFOUND
要求された項目が見つからなかった。
DDERR_NOTINITIALIZED
オブジェクトが初期化される前に、CoCreateInstance で作成した DirectDraw オブジェクトのインターフェイス メソッドを呼び出そうとした。
DDERR_NOTLOADED
サーフェスは最適化されているが、まだメモリが割り当てられていない。
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_OVERLAPPINGRECTS
転送元および転送先矩形が同じサーフェス上にあり、互いにオーバーラップしている。
DDERR_OVERLAYCANTCLIP
ハードウェアはクリッピング オーバーレイをサポートしない。
DDERR_OVERLAYCOLORKEYONLYONEACTIVE
オーバーレイ上に複数のアクティブなカラー キーを持とうとした。
DDERR_OVERLAYNOTVISIBLE
IDirectDrawSurface7::GetOverlayPosition メソッドが非表示のオーバーレイで呼び出された。
DDERR_PALETTEBUSY
パレットがもう 1 つのスレッドによりロックされているため、アクセスが拒否された。
DDERR_PRIMARYSURFACEALREADYEXISTS
この処理は既にプライマリ サーフェスを作成している。
DDERR_REGIONTOOSMALL
IDirectDrawClipper::GetClipList メソッドに渡された領域が小さすぎる。
DDERR_SURFACEALREADYATTACHED
既にアタッチしているもう 1 つのサーフェスにサーフェスをアタッチしようとした。
DDERR_SURFACEALREADYDEPENDENT
既にほかのサーフェスに依存しているサーフェスを依存させようとした。
DDERR_SURFACEBUSY
サーフェスがもう 1 つのスレッドでロックされているため、サーフェスへのアクセスが拒否された。
DDERR_SURFACEISOBSCURED
サーフェスへのアクセスが、サーフェスが隠蔽されているため拒否された。
DDERR_SURFACELOST
サーフェス メモリの不足のため、サーフェスへのアクセスが拒否された。このサーフェスで IDirectDrawSurface7::Restore メソッドを呼び出すと、関連付けられたメモリをリストアできる。
DDERR_SURFACENOTATTACHED
要求されたサーフェスはアタッチできない。
DDERR_TESTFINISHED
DirectX 7.0 で追加。IDirectDraw7::StartModeTest メソッドがこの値を返した場合、テスト用に選択したすべての解像度は既にリフレッシュ レート情報をレジストリに持っているため、テストを開始できないことを意味する。IDirectDraw7::EvaluateMode メソッドがこの値を返した場合は、DirectDraw がリフレッシュ レート テストを完了したことを意味する。
DDERR_TOOBIGHEIGHT
DirectDraw で要求された幅が大きすぎる。
DDERR_TOOBIGSIZE
DirectDraw で要求されたサイズが大きすぎる。ただし、個々の高さおよび幅は有効なサイズである。
DDERR_TOOBIGWIDTH
DirectDraw によって要求された幅が大きすぎる。
DDERR_UNSUPPORTED
サポートされない処理であった。
DDERR_UNSUPPORTEDFORMAT
要求されたピクセル フォーマットは DirectDraw ではサポートされていない。
DDERR_UNSUPPORTEDMASK
要求されたピクセル フォーマットのビットマスクが DirectDraw でサポートされていない。
DDERR_UNSUPPORTEDMODE
ディスプレイは現在サポートされていないモードである。
DDERR_VERTICALBLANKINPROGRESS
垂直帰線消去期間である。
DDERR_VIDEONOTACTIVE
ビデオ ポートがアクティブではない。
DDERR_WASSTILLDRAWING
このサーフェスから、またはサーフェスへの前回のブリット処理が完了していない。
DDERR_WRONGMODE
異なったモードで作成されたため、このサーフェスはリストアすることができない。
DDERR_XALIGN
提供された矩形を必要とされる範囲に水平一列に並べることができなかった。


ピクセル フォーマット マスク

ここでは、ハードウェア エミュレーション レイヤ (HEL) がサポートするピクセル フォーマットについて説明する。以下の項目について記述する。

  • テクスチャマップ フォーマット
  • オフスクリーン サーフェス フォーマット


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

ハードウェア エミュレーション レイヤ (HEL) によって広範囲にわたってテクスチャ ピクセル フォーマットがサポートされている。以下のテーブルにこれらのフォーマットを示す。マスク欄には、ピクセル フォーマット フラグとビット深度の各集合に対する赤、緑、青、およびアルファのマスクを示している。

ピクセル フォーマット フラグ | ビット深度 | マスク
DDPF_RGB | DDPF_PALETTEINDEXED1 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED1 | DDPF_PALETTEINDEXEDTO8 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | DDPF_PALETTEINDEXEDTO8 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | DDPF_PALETTEINDEXEDTO8 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED8 | 8 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | 8 | R:0x000000E0 G:0x0000001C B:0x00000003 A:0x00000000
DDPF_RGB | DDPF_ALPHAPIXELS | 16 | R:0x00000F00 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 | DDPF_ALPHAPIXELS | 16 | R:0x00007C00 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 | DDPF_ALPHAPIXELS | 32 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0xFF000000
DDPF_RGB | DDPF_ALPHAPIXELS | 32 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0xFF000000

HEL では、これらのフォーマットをシステム メモリに作成することができる。3D アクセラレート ディスプレイ カード用の DirectDraw デバイス ドライバは、ディスプレイ メモリに別のフォーマットのテクスチャを作成することができる。そのようなドライバは、テクスチャが作成できることを示すために DDSCAPS_TEXTURE フラグをエクスポートする。


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

以下の表は、DirectX ハードウェア エミュレーション レイヤ (HEL) がサポートするオフスクリーン プレーン サーフェスのピクセル フォーマットを示している。マスク欄には、ピクセル フォーマット フラグとビット深度の各集合に対する赤、緑、青、およびアルファのマスクを示している。

ピクセル フォーマット フラグ | ビット深度 | マスク
DDPF_RGB | DDPF_PALETTEINDEXED1 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED8 | 8 | R:0x00000000 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
DDPF_RGB | DDPF_ZPIXELS | 32 | R:0x0000F800 G:0x000007E0 B:0x0000001F Z:0xFFFF0000
DDPF_RGB | DDPF_ZPIXELS | 32 | R:0x00007C00 G:0x000003E0 B:0x0000001F Z:0xFFFF0000

広範囲なオフスクリーン サーフェス フォーマットをサポートするほかにも、HEL は Direct3D またはその他の 3D レンダラ用のサーフェスをサポートする。


4 文字コード (FOURCC)

DirectDraw は、4 文字からなる特別なコードの集合を使用する。これらのコードは、4 文字コードまたは FOURCC と呼ばれ、ビットマップ イメージ、サウンド、ビデオなどのマルチメディア データを含むファイルのヘッダー ファイルに格納されている。FOURCC は、マルチメディア データを作成するために使用されたソフトウェア技術を示している。また暗に、FOURCC はデータ自体のフォーマットも記述している。

DirectDraw アプリケーションは、イメージ カラーやフォーマット変換に FOURCC を使用する。アプリケーションで、IDirectDrawSurface7::GetPixelFormat メソッドを呼び出して、フォーマットが RGB ではないサーフェスのピクセル フォーマットを要求すると、メソッドが返るときに DDPIXELFORMAT 構造体の dwFourCC メンバが FOURCC を識別する。

さらに、BITMAPINFOHEADER 構造体の biCompression メンバは、イメージを収縮または伸縮するために使用するコーデックを示すため、FOURCC に設定することができる。

FOURCC は、マルチメディア ソフトウェア技術の各ベンダーによりマイクロソフトに登録されている。以下のテーブルに、共通の FOURCC の例を示す。

FOURCC | 会社名 | 技術名
AUR2 | AuraVision Corporation | AuraVision Aura 2:YUV 422
AURA | AuraVision Corporation | AuraVision Aura 1:YUV 411
CHAM | Winnov, Inc. | MM_WINNOV_CAVIARA_CHAMPAGNE
CVID | Supermac | Cinepak by Supermac
CYUV | Creative Labs, Inc | クリエイティブ ラボ YUV
DXT1 | Microsoft Corporation | DirectX Texture Compression フォーマット 1
DXT2 | Microsoft Corporation | DirectX Texture Compression フォーマット 2
DXT3 | Microsoft Corporation | DirectX Texture Compression フォーマット 3
DXT4 | Microsoft Corporation | DirectX Texture Compression フォーマット 4
DXT5 | Microsoft Corporation | DirectX Texture Compression フォーマット 5
FVF1 | Iterated Systems, Inc. | フラクタル ビデオ フレーム
IF09 | Intel® Corporation | インテル インターミディアット YUV9
IV31 | Intel Corporation | インディオ 3.1
JPEG | Microsoft Corporation | スティル イメージ JPEG DIB
MJPG | Microsoft Corporation | モーション JPEG Dib フォーマット
MRLE | Microsoft Corporation | レン レングス エンコーディング
MSVC | Microsoft Corporation | ビデオ 1
PHMO | IBM Corporation | フォトモーション
RT21 | Intel Corporation | インディオ 2.1
ULTI | IBM Corporation | アルティモーション
V422 | Vitec Multimedia | 24 ビット YUV 4:2:2
V655 | Vitec Multimedia | 16 ビット YUV 4:2:2
VDCT | Vitec Multimedia | Video Maker Pro DIB
VIDS | Vitec Multimedia | YUV 4:2:2 CCIR 601 for V422
YU92 | Intel Corporation | YUV
YUV8 | Winnov, Inc. | MM_WINNOV_CAVIAR_YUV8
YUV9 | Intel Corporation | YUV9
YUYV | Canopus, Co., Ltd. | BI_YUYV, Canopus
ZPEG | Metheus | Video Zipper


DirectDraw Visual Basic リファレンス

ここでは、DirectDraw が提供する API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • クラス
  • 型
  • 列挙
  • エラー コード
  • ピクセル フォーマット マスク
  • 4 文字コード (FOURCC)


クラス

ここでは、DirectDraw コンポーネントで使用されるクラスのリファレンス情報を記述する。以下のクラスについて説明する。

  • DirectDraw7
  • DirectDrawClipper
  • DirectDrawColorControl
  • DirectDrawEnum
  • DirectDrawEnumModes
  • DirectDrawEnumSurfaces
  • DirectDrawGammaControl
  • DirectDrawIdentifier
  • DirectDrawPalette
  • DirectDrawSurface7
  • DirectDraw グローバル メソッド
  • IFont


DirectDraw7

アプリケーションは DirectDraw7 クラスのメソッドを使って、DirectDraw オブジェクトを作成し、システムレベル変数と共に作用する。この項は、このクラスのメソッドのリファレンスである。概要については、「DirectDraw オブジェクト」を参照すること。

DirectDraw7 クラスのメソッドは、以下のグループにまとめることができる。

協調レベル | SetCooperativeLevel
 | TestCooperativeLevel
オブジェクトの作成 | CreateClipper
 | CreatePalette
 | CreateSurface
 | CreateSurfaceFromFile
 | CreateSurfaceFromResource
 | GetDirect3D
 | LoadPaletteFromBitmap
デバイス能力 | GetCaps
ディスプレイ モード | GetDisplayMode
 | GetDisplayModesEnum
 | GetMonitorFrequency
 | RestoreDisplayMode
 | SetDisplayMode
 | WaitForVerticalBlank
ディスプレイ ステータス | GetScanLine
 | GetVerticalBlankStatus
その他 | GetAvailableTotalMem
 | GetDeviceIdentifier
 | GetFourCCCodes
 | GetFreeMem
 | GetNumFourCCCodes
サーフェス管理 | DuplicateSurface
 | FlipToGDISurface
 | GetGDISurface
 | GetSurfaceFromDC
 | GetSurfacesEnum
 | RestoreAllSurfaces

DirectDraw7 クラスは、以前のバージョンよりも柔軟にサーフェスを管理できるメソッドを提供することにより、クラスの前のバージョンにおける機能を拡張している。


DirectDraw7.CreateClipper

DirectDraw7.CreateClipper メソッドは、DirectDrawClipper オブジェクトを作成する。

object.CreateClipper(flags As Long) As DirectDrawClipper

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
flags
現在使用されていないので、0 に設定する。

戻り値

成功すれば、DirectDrawClipper オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY

注意

DirectDrawClipper オブジェクトを DirectDrawSurface にアタッチし、DirectDrawSurface7.Blt の実行時に使用することができる。

参照

DirectDrawSurface7.GetClipper、DirectDrawSurface7.SetClipper


DirectDraw7.CreatePalette

DirectDraw7.CreatePalette メソッドは、この DirectDraw オブジェクトに対する DirectDrawPalette オブジェクトを作成する。

object.CreatePalette( _
    flags As CONST_DDPCAPSFLAGS, _
    pe() As PALETTEENTRY) As DirectDrawPalette

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
flags
CONST_DDPCAPSFLAGS 列挙の 1 つまたは複数の定数。
pe()
この DirectDrawPalette オブジェクトを初期化する、2、4、16、または 256 の PALETTEENTRY 型の配列。

戻り値

成功すれば、DirectDrawPalette オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED


DirectDraw7.CreateSurface

DirectDraw7.CreateSurface メソッドは、この DirectDraw オブジェクトに対するDirectDrawSurface7 オブジェクトを作成する。

object.CreateSurface( _
    dd As DDSURFACEDESC2) As DirectDrawSurface7

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
dd
要求されるサーフェスを記述する DDSURFACEDESC2 型。DDSCAPS2 型は、DDSURFACEDESC2 のメンバである。

戻り値

成功すれば、DirectDrawSurface7 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

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_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE


DirectDraw7.CreateSurfaceFromFile

DirectDraw7.CreateSurfaceFromFile メソッドは、この DirectDraw オブジェクトに対する DirectDrawSurface7 オブジェクトを作成し、指定されたビットマップ イメージを DirectDrawSurface オブジェクトにアタッチする。

object.CreateSurfaceFromFile( _
    file As String, _
    dd As DDSURFACEDESC2) As DirectDrawSurface7

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
file
作成するサーフェスにロードするビットマップ イメージの名前。
dd
要求されるサーフェスを記述する DDSURFACEDESC2 型。DDSCAPS2 型は、DDSURFACEDESC2 のメンバである。

戻り値

成功すれば、DirectDrawSurface7 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

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_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

注意

256 色を使用する場合、このメソッドを呼び出してパレット情報を表示する前に、ディスプレイ モードとパレットを設定する。


DirectDraw7.CreateSurfaceFromResource

DirectDraw7.CreateSurfaceFromResource メソッドは、この DirectDraw オブジェクトに対する DirectDrawSurface7 オブジェクトを作成し、指定されたリソースを DirectDrawSurface オブジェクトにアタッチする。

object.CreateSurfaceFromResource( _
    file As String, _
    resName As String, _
    ddsd As DDSURFACEDESC2) As DirectDrawSurface7

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
file
作成するサーフェスにロードするリソースのファイル名。リソースが実行可能ファイルに含まれる場合、リソースの場所を示すには、このパラメータに空の文字列を指定する。このパラメータは、リソースが存在する OCX の名前にすることもできる。
resName
作成するサーフェスにロードするリソースの名前。
ddsd
要求されたサーフェスを記述する DDSURFACEDESC2 型。DDSCAPS2 型は、DDSURFACEDESC2 のメンバである。

戻り値

成功すれば、DirectDrawSurface7 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

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_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

注意

モジュール名に空の文字列を使用して Microsoft® Visual Basic® 環境でアプリケーションを実行すると、リソースの場所を検索できない。スタンドアロンの実行可能ファイルを使用している場合のみ、空の文字列を渡しても成功する。

リソース名は、数字ではなく文字で指定しなければならない。リソース名をクオーテーション マークで囲んで文字列にしないと、メソッドは失敗する。


DirectDraw7.DuplicateSurface

DirectDraw7.DuplicateSurface メソッドは、DirectDrawSurface7 オブジェクトを複製する。

object.DuplicateSurface( _
    ddIn As DirectDrawSurface7) As DirectDrawSurface7

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
ddIn
複製されるサーフェスになる DirectDrawSurface7 オブジェクト。

戻り値

成功すれば、新しく複製された DirectDrawSurface7 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_CANTDUPLICATE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACELOST

注意

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


DirectDraw7.FlipToGDISurface

DirectDraw7.FlipToGDISurface メソッドは、GDI が書き込むサーフェスをプライマリ サーフェスにする。

object.FlipToGDISurface()

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

注意

このメソッドはページ フリッピング アプリケーションの最後に呼び出され、GDI が記述しているディスプレイ メモリをユーザーに表示させるようにする。

このメソッドでは、ステレオ自動フリッピングは使用できない。

参照

DirectDraw7.GetGDISurface


DirectDraw7.GetAvailableTotalMem

DirectDraw7.GetAvailableTotalMem メソッドは、指定されたタイプのサーフェスで使用可能なディスプレイ メモリの総容量を取得する。

object.GetAvailableTotalMem( _
    ddsCaps As DDSCAPS2) As Long

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
ddsCaps
指定されたサーフェスのハードウェア能力を示す DDSCAPS2 型。

戻り値

成功すれば、総メモリ容量を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

注意

このメソッドは、現在のディスプレイ メモリの瞬間的な状態だけを提供する。ディスプレイ メモリの空き容量は、サーフェスの作成と解放により変化する。したがって、空きメモリ容量の値は単に近似値として使用すべきである。さらに、特定のディスプレイ アダプタ カードでは、2 つの異なるメモリ タイプを区別しない。たとえば、アダプタはディスプレイ メモリの同じ部分を使って、Z バッファとテクスチャを格納する場合がある。このため、サーフェスのあるタイプ (たとえば Z バッファ) を割り当てることは、サーフェスのほかのタイプ (たとえばテクスチャ) が利用できるディスプレイ メモリの容量に影響を与える。したがって、動的使用 (テクスチャ マッピングなど) で利用できるメモリ容量を決める前に、アプリケーションの固定リソース (フロントとバック バッファ、および Z バッファなど) を最初に割り当てることが最良の方法となる。


DirectDraw7.GetCaps

DirectDraw7.GetCaps メソッドは、ハードウェアとハードウェア エミュレーション レイヤ (HEL) に対するデバイス ドライバの能力を格納する。

object.GetCaps(hwCaps As DDCAPS, helCaps As DDCAPS)

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
hwCaps
デバイス ドライバが報告するハードウェアの能力を格納する DDCAPS 型。
helCaps
HEL の能力を格納する DDCAPS 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDraw7.GetDeviceIdentifier

DirectDraw7.GetDeviceIdentifier メソッドは、DirectDraw デバイス ドライバに関する情報が格納された DirectDrawIdentifier オブジェクトを返す。

object.GetDeviceIdentifier( _
    flags As CONST_DDDEVICEIDFLAGS _ )
    As DirectDrawIdentifier

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
flags
情報オプションを指定する CONST_DDDEVICEIDFLAGS 列挙の定数の 1 つ。

戻り値

成功すれば、DirectDrawIdentifier オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDraw7.GetDirect3D

DirectDraw7.GetDirect3D メソッドは、Direct3D7 オブジェクトを作成する。

object.GetDirect3D() As Direct3D7

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、Direct3D7 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

E_INVALIDINTERFACE
E_OUTOFMEMORY

トラッピング エラーの詳細については、「Visual Basic エラー トラッピング」を参照すること。

注意

このメソッドが成功して取得されたオブジェクトは、Direct3D7 オブジェクト変数に割り当てなければならない。以下に例を示す。

Dim Direct3D as Direct3D7
Set Direct3D = object.GetDirect3D()


DirectDraw7.GetDisplayMode

DirectDraw7.GetDisplayMode メソッドは、現在のディスプレイ モードを取得する。

object.GetDisplayMode(surface As DDSURFACEDESC2)

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
surface
サーフェスのディスプレイ モード情報が格納される DDSURFACEDESC2 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTEDMODE

注意

アプリケーションがこのメソッドで返された情報をあらかじめ保存して、クリーンアップの際のディスプレイ モードのリストアとして利用することは望ましくない。アプリケーションでは DirectDraw7.RestoreDisplayMode メソッドを使って、クリーンアップの際にモードをリストアすべきである。これにより、マルチプロセス環境で起こる競合を回避できる。

参照

DirectDraw7.SetDisplayMode、DirectDraw7.RestoreDisplayMode、DirectDraw7.GetDisplayModesEnum


DirectDraw7.GetDisplayModesEnum

DirectDraw7.GetDisplayModesEnum メソッドは、ディスプレイ モード情報が格納された DirectDrawEnumModes オブジェクトを返す。

object.GetDisplayModesEnum( _
    flags As CONST_DDEDMFLAGS, _
    ddsd As DDSURFACEDESC2) As DirectDrawEnumModes

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
flags
CONST_DDEDMFLAGS 列挙の定数の 1 つ。
ddsd
サーフェスのディスプレイ モード情報が格納される DDSURFACEDESC2 型。

戻り値

成功すれば、DirectDrawEnumModes オブジェクトを返す。このオブジェクトによってディスプレイ モードの記述を照会できる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
E_OUTOFMEMORY

注意

アプリケーションがこのメソッドで返された情報をあらかじめ保存して、クリーンアップの際のディスプレイ モードのリストアとして利用することは望ましくない。アプリケーションでは DirectDraw7.RestoreDisplayMode メソッドを使って、クリーンアップの際にモードをリストアすべきである。これにより、マルチプロセス環境で起こる競合を回避できる。

参照

DirectDraw7.SetDisplayMode、DirectDraw7.RestoreDisplayMode、DirectDraw7.GetDisplayModesEnum


DirectDraw7.GetFourCCCodes

DirectDraw7.GetFourCCCodes メソッドは、DirectDraw オブジェクトによってサポートされる FOURCC コードを取得する。

object.GetFourCCCodes(ccCodes() As Long)

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
ccCodes
このDirectDraw オブジェクトによってサポートされる 4 文字コード (FOURCC) を格納する変数の配列。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

DirectDraw7 オブジェクトによってサポートされるコードの数を取得するには、DirectDraw7.GetNumFourCCCodes を使用する。


DirectDraw7.GetFreeMem

DirectDraw7.GetFreeMem メソッドは、ディスプレイ メモリの現在の空き容量を取得する。

object.GetFreeMem(ddsCaps As DDSCAPS2) As Long

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
ddsCaps
指定されたサーフェスのハードウェア能力を示す DDSCAPS2 型。

戻り値

成功すれば、メモリの空き容量を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

注意

このメソッドは、現在のディスプレイ メモリの瞬間的な状態だけを提供する。ディスプレイ メモリの空き容量は、サーフェスの作成と解放により変化する。したがって、空きメモリ容量の値は単に近似値として使用すべきである。さらに、特定のディスプレイ アダプタ カードでは、2 つの異なるメモリ タイプを区別しない。たとえば、アダプタはディスプレイ メモリの同じ部分を使って、Z バッファとテクスチャを格納する場合がある。このため、サーフェスのあるタイプ (たとえば、Z バッファ) を割り当てることは、サーフェスのほかのタイプ (テクスチャ) が利用できるディスプレイ メモリの容量に影響を与える。したがって、動的使用 (テクスチャ マッピングなど) で利用できるメモリ容量を決める前に、アプリケーションの固定リソース (フロントとバック バッファ、および Z バッファなど) を最初に割り当てることが最良の方法となる。


DirectDraw7.GetGDISurface

DirectDraw7.GetGDISurface メソッドは、GDI がプライマリ サーフェスとして処理するサーフェス メモリを現在示す DirectDrawSurface オブジェクトを取得する。

object.GetGDISurface() As DirectDrawSurface7

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawSurface7 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

参照

DirectDraw7.FlipToGDISurface


DirectDraw7.GetMonitorFrequency

DirectDraw7.GetMonitorFrequency メソッドは、DirectDraw オブジェクトが動作するモニタの周波数を取得する。

object.GetMonitorFrequency() As Long

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、モニタの周波数をヘルツ単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED


DirectDraw7.GetNumFourCCCodes

DirectDraw7.GetNumFourCCCodes メソッドは、DirectDraw オブジェクトによってサポートされる FOURCC コードの数を取得する。

object.GetFourCCCodes() As Long

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、サポートされる 4 文字コード (FOURCC) の数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、通常 DirectDraw7.GetFourCCCodes を呼び出す前に呼び出される。


DirectDraw7.GetScanLine

DirectDraw7.GetScanLine メソッドは、モニタ上で現在描画されている走査線を取得する。

object.GetScanLine(lines As Long) As Long

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
lines
現在の走査線。

戻り値

成功すれば、DD_OK を返す。これは、呼び出し側のアプリケーションが、実行を続けられることを示す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS

注意

走査線はゼロベースの整数として報告される。返される走査線の値は 0 から n までの値であり、走査線 0 はスクリーン上の最初の可視走査線、走査線 n は最後の可視走査線である。さらに、垂直帰線消去間隔に生じる任意の走査線を足すことができる。したがって、アプリケーションが 640×480 で実行され、垂直帰線消去間隔に 12 の走査線がある場合、このメソッドが返す値は 0 から 491 の範囲となる。

参照

DirectDraw7.GetVerticalBlankStatus、DirectDraw7.WaitForVerticalBlank


DirectDraw7.GetSurfaceFromDC

DirectDraw7.GetSurfaceFromDC メソッドは、その GDI デバイス コンテキスト ハンドルに基づくサーフェスに対する DirectDrawSurface7 オブジェクトを取得する。

object.GetSurfaceFromDC(hdc As Long) As DirectDrawSurface7

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
hdc
ディスプレイ デバイス コンテキストへのハンドル。

戻り値

成功すれば、DirectDrawSurface7 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_NOTFOUND

注意

このメソッドは、DirectDraw オブジェクトに既に関連付けられたサーフェスを識別する、デバイス コンテキスト ハンドルに対してだけ成功する。

参照

サーフェス コンテキストとデバイス コンテキスト


DirectDraw7.GetSurfacesEnum

DirectDraw7.GetSurfacesEnum メソッドは、DirectDraw7 オブジェクトにアタッチされたサーフェスの列挙に使用される DirectDrawEnumSurfaces オブジェクトを返す。

object.GetSurfacesEnum( _
    flags As CONST_DDENUMSURFACESFLAGS, _
    desc As DDSURFACEDESC2) As DirectDrawEnumSurfaces

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
flags
1 つの検索型フラグと 1 つの適業フラグの組み合わせを含む CONST_DDENUMSURFACESFLAGS 列挙。検索型フラグは、メソッドが適合フラグを検索する方法を決定する。つまり、desc パラメータの記述を使用して作成されるサーフェスを検索したり、既にその記述に適合する既存のサーフェスを検索できる。適合フラグは、メソッドがすべてのサーフェス、適合するサーフェスだけ、または desc パラメータの記述に適合しないサーフェスだけを列挙するかどうかを決定する。
desc
対象となるサーフェスを定義する DDSURFACEDESC2 型。

戻り値

成功すれば、DirectDrawEnumSurfaces オブジェクトを返す。このオブジェクトを使って、アタッチされたサーフェスの記述を照会できる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
E_OUTOFMEMORY

注意

DDENUMSURFACES_CANBECREATED フラグを設定する場合、このメソッドは検索基準に合うサーフェスを一時的に作成しようとする。


DirectDraw7.GetVerticalBlankStatus

DirectDraw7.GetVerticalBlankStatus メソッドは、垂直帰線消去のステータスを取得する。

object.GetVerticalBlankStatus() As Long

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、垂直帰線消去のステータスを返す。垂直帰線消去が発生する場合にこのパラメータはゼロとなり、そうでない場合はゼロ以外の値となる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

垂直帰線消去と同期するには、DirectDraw7.WaitForVerticalBlank メソッドを使用する。

参照

DirectDraw7.GetScanLine、DirectDraw7.WaitForVerticalBlank


DirectDraw7.LoadPaletteFromBitmap

DirectDraw7.LoadPaletteFromBitmap メソッドは、この DirectDraw オブジェクトで指定されたビットマップのパレットに基づいて、DirectDrawPalette オブジェクトを作成する。

object.LoadPaletteFromBitmap( _
    bName As String) As DirectDrawPalette

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
bName
パレットをロードするビットマップの名前。

戻り値

成功すれば、DirectDrawPalette オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED


DirectDraw7.RestoreAllSurfaces

DirectDraw7.RestoreAllSurfaces メソッドは、DirectDraw オブジェクトに対して作成されたサーフェスすべてを、サーフェスを作成した順番でリストアする。

object.RestoreAllSurfaces()

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは便利である。このメソッドは、この DirectDraw オブジェクトが作成するサーフェスごとに、効率的に DirectDrawSurface7.Restore を呼び出す。

参照

DirectDrawSurface7.Restore、サーフェスの消失とリストア


DirectDraw7.RestoreDisplayMode

DirectDraw7.RestoreDisplayMode メソッドは、プライマリ サーフェスのディスプレイ デバイス ハードウェアのモードを、DirectDraw7.SetDisplayMode メソッドが呼び出される前の状態にリセットする。このメソッドを使用するには、排他レベルのアクセスが必要とされる。

object.RestoreDisplayMode()

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE

参照

DirectDraw7.SetDisplayMode、DirectDrawEnumModes、DirectDraw7.SetCooperativeLevel


DirectDraw7.SetCooperativeLevel

DirectDraw7.SetCooperativeLevel メソッドは、アプリケーションの最上位動作を決定する。

object.SetCooperativeLevel( _
    hdl As Long, _
    flags As CONST_DDSCLFLAGS)

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
hdl
アプリケーションが使用するウィンドウ ハンドル。呼び出すアプリケーションの最上位ウィンドウ ハンドルに設定する (最上位ウィンドウが作成した子ウィンドウに対するハンドルではない)。flags パラメータに DDSCL_NORMAL フラグを指定する場合、このパラメータは 0 となる。
flags
CONST_DDSCLFLAGS 列挙の 1 つまたは複数の定数。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_EXCLUSIVEMODEALREADYSET
DDERR_HWNDALREADYSET
DDERR_HWNDSUBCLASSED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

このメソッドは、アプリケーション ウィンドウを作成した同じスレッドで呼び出されなくてはならない。

アプリケーションは、DDSCL_EXCLUSIVE または DDSCL_NORMAL フラグのどちらかを設定しなくてはならない。

ほかのアプリケーションに対して、大幅なパフォーマンス変化を引き起こす可能性のある関数を呼び出すには、DDSCL_EXCLUSIVE フラグを設定しなくてはならない。詳細については、「協調レベル」を参照すること。

参照

DirectDraw7.SetDisplayMode、DirectDraw7.GetDisplayModesEnum、モード X モードとモード 13 ディスプレイ モード、フォーカス ウィンドウとデバイス ウィンドウ


DirectDraw7.SetDisplayMode

DirectDraw7.SetDisplayMode メソッドは、ディスプレイ デバイス ハードウェアのモードを設定する。

object.SetDisplayMode( _
    w As Long, _
    h As Long, _
    bpp As Long, _
    ref As Long, _
    mode As CONST_DDSDMFLAGS)

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
w、h
新しいモードの幅と高さ。
bpp
解像度、新しいモードのビット/ピクセル (bpp)。
ref
新しいモードのリフレッシュ レート。この値を 0 に設定すると、ドライバに対するデフォルトのリフレッシュ レートを要求する。
mode
追加オプションを記述する CONST_DDSDMFLAGS 列挙の定数の 1 つ。現時点で唯一の有効なフラグは DDSDM_STANDARDVGAMODE であり、メソッドでモード X の 320×200×8 モードではなく、モード 13 を設定できる。別の解像度、ビット深度、またはモード X モードに設定する場合は、このフラグを使用せずにパラメータを 0 に設定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

注意

このメソッドは、アプリケーション ウィンドウを作成した同じスレッドで呼び出されなくてはならない。

別のアプリケーションがディスプレイ モードを変更する場合、プライマリ サーフェスは消失され、新しいディスプレイ モードに適合するようにプライマリ サーフェスが再作成されるまで、DDERR_SURFACELOST を返す。

参照

DirectDraw7.RestoreDisplayMode、DirectDraw7.GetDisplayModesEnum、DirectDraw7.SetCooperativeLevel、ディスプレイ モードの設定、ディスプレイ モードのリストア


DirectDraw7.TestCooperativeLevel

DirectDraw7.TestCooperativeLevel メソッドは、ウィンドウまたはフルスクリーン アプリケーションに対する DirectDraw デバイスの現在の協調レベル ステータスを報告する。

object.TestCooperativeLevel() As Long

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DD_OK を返す。これは、呼び出し側のアプリケーションが、実行を続けられることを示す。

エラー コード

失敗するか、DD_OK が返されないとエラーが発生し、Err.Number に次のいずれかの値が設定される (「注意」参照)。

DDERR_INVALIDOBJECT
DDERR_EXCLUSIVEMODEALREADYSET
DDERR_NOEXCLUSIVEMODE
DD_OK
DDERR_WRONGMODE

注意

このメソッドは、サーフェスのリストアや DirectDraw オブジェクトの再作成の通知として、WM_ACTIVATEAPP および WM_DISPLAYCHANGE システム メッセージを使用するアプリケーションで特に役立つ。戻り値 0 は、サーフェスをリストアまたは再作成することなく、アプリケーションが実行を続けられることを常に示す。しかし、エラー コードの解釈は、アプリケーションが使用する協調レベルによって異なる。詳細については、「協調レベルのテスト」を参照すること。


DirectDraw7.WaitForVerticalBlank

DirectDraw7.WaitForVerticalBlank メソッドは、アプリケーションが垂直帰線消去間隔と共に同期する方法を提供する。

object.WaitForVerticalBlank( _
    flags As CONST_DDWAITVBFLAGS, _
    handle As Long) As Long

パラメータ

object
DirectDraw7 オブジェクトを表すオブジェクト式。
flags
垂直帰線消去に対しての待機時間を指定する CONST_DDWAITVBFLAGS 列挙の定数の 1 つ。
handle
垂直帰線消去が発生したときにトリガとなるイベントのハンドル。このパラメータは、現時点では使用できない。

戻り値

成功すれば、DD_OK を返す。これは、呼び出し側のアプリケーションが、実行を続けられることを示す。

エラー コード

失敗するか、DD_OK が返されないとエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DD_OK
DDERR_WASSTILLDRAWING

参照

DirectDraw7.GetVerticalBlankStatus、DirectDraw7.GetScanLine


DirectDrawClipper

アプリケーションは、DirectDrawClipper クラスのメソッドを使ってクリップ リストを管理する。この項は、このクラスのメソッドのリファレンスである。概要については、「クリッパー」を参照すること。

DirectDrawClipper クラスのメソッドは、以下のグループにまとめることができる。

クリップ リスト | GetClipList
 | GetClipListSize
 | IsClipListChanged
 | SetClipList
ハンドル | GetHWnd
 | SetHWnd


DirectDrawClipper.GetClipList

DirectDrawClipper.GetClipList メソッドは、DirectDrawClipper オブジェクトに関連付けられたクリップ リストのコピーを取得する。

object.GetClipList(rects() As RECT)

パラメータ

object
DirectDrawClipper オブジェクトを表すオブジェクト式。
rects()
クリップ リストが格納される RECT 型の配列。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST
DDERR_REGIONTOOSMALL

参照

DirectDrawClipper.SetClipList


DirectDrawClipper.GetClipListSize

DirectDrawClipper.GetClipListSize メソッドは、DirectDrawClipper オブジェクトに関連付けられたクリップ リストのサイズを取得する。

object.GetClipListSize() As Long

パラメータ

object
DirectDrawClipper オブジェクトを表すオブジェクト式。

戻り値

成功すれば、クリップ リストのサイズをバイト単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST


DirectDrawClipper.GetHWnd

DirectDrawClipper.GetHWnd メソッドは、DirectDrawClipper.SetHWnd メソッドによってこの DirectDrawClipper オブジェクトに関連付けられたウィンドウ ハンドルを取得する。

object.GetHWnd() As Long

パラメータ

object
DirectDrawClipper オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ウィンドウ ハンドルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

参照

DirectDrawClipper.SetHWnd


DirectDrawClipper.IsClipListChanged

DirectDrawClipper.IsClipListChanged メソッドは、DirectDrawClipper オブジェクトにウィンドウ ハンドルが関連付けられている場合に、クリップ リストの状態をモニタする。

object.IsClipListChanged() As Long

パラメータ

object
DirectDrawClipper オブジェクトを表すオブジェクト式。

戻り値

成功すれば、クリップ リストの状態を返す。クリップ リストが変更されている場合はゼロ以外の値、変更されていない場合はゼロになる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawClipper.SetClipList

DirectDrawClipper.SetClipList メソッドは、親 DirectDrawClipper オブジェクトがアタッチされたサーフェス上で、DirectDrawSurface7.Blt メソッドが使用するクリップ リストを設定または削除する。

object.SetClipList( _
    count As Long, _
    rects() as RECT)

パラメータ

object
DirectDrawClipper オブジェクトを表すオブジェクト式。
count
rects( ) 配列の RECT 型の数。
rects()
クリップ リストを記述する RECT 型の配列。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_CLIPPERISUSINGHWND
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

ウィンドウ ハンドルが既に DirectDrawClipper オブジェクトに関連付けられている場合、クリップ リストは設定されない。DirectDrawSurface7.BltFast メソッドではクリップできない。

参照

DirectDrawClipper.GetClipList、DirectDrawSurface7.Blt、DirectDrawSurface7.BltFast


DirectDrawClipper.SetHWnd

DirectDrawClipper.SetHWnd メソッドは、クリッピング情報を取得するウィンドウ ハンドルを設定する。

object.SetHWnd(hdl As Long)

パラメータ

object
DirectDrawClipper オブジェクトを表すオブジェクト式。
hdl
クリッピング情報を取得するウィンドウ ハンドル。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

参照

DirectDrawClipper.GetHWnd


DirectDrawColorControl

DirectDrawColorControl クラスのメソッドを使って、カラー コントロールを取得したり設定することができる。このオブジェクトは、DirectDrawSurface7.GetDirectDrawColorControl によって作成される。このクラスには、次の 2 つのメソッドがある。

カラー コントロール | GetColorControls
 | SetColorControls


DirectDrawColorControl.GetColorControls

DirectDrawColorControl.GetColorControls メソッドは、指定したオーバーレイやプライマリ サーフェスに関連付けられた現在のカラー コントロールの設定を返す。DDCOLORCONTROL 型の lFlags メンバは、サポートされるカラー コントロール オプションを示す。

object.GetColorControls(colorControl As DDCOLORCONTROL)

パラメータ

object
DirectDrawColorControl オブジェクトを表すオブジェクト式。
colorControl
指定したサーフェスの現在のカラー コントロール設定を受け取る DDCOLORCONTROL 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

注意

DirectDraw デバイスがカラー コントロールをサポートしていない場合、このメソッドは失敗する。

参照

DirectDrawColorControl.SetColorControls、カラー コントロールの使用、ガンマ コントロールとカラー コントロール


DirectDrawColorControl.SetColorControls

DirectDrawColorControl.SetColorControls メソッドは、指定したオーバーレイやプライマリ サーフェスに関連付けられたカラー コントロールを設定する。

object.SetColorControls(colorControl As DDCOLORCONTROL)

パラメータ

object
DirectDrawColorControl オブジェクトを表すオブジェクト式。
colorControl
指定したサーフェスに適用される新しい値を含む DDCOLORCONTROL 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

参照

DirectDrawColorControl.GetColorControls、カラー コントロールの使用、ガンマ コントロールとカラー コントロール


DirectDrawEnum

アプリケーションは、DirectDrawEnum クラスのメソッドを使って、コンピュータにインストールされたビデオ ディスプレイ アダプタに関する情報を取得する。このオブジェクトは、DirectX7.GetDDEnum メソッドによって作成され、データが格納される。

DirectDraw 列挙 | GetCount
 | GetDescription
 | GetGuid
 | GetMonitorHandle
 | GetName


DirectDrawEnum.GetCount

DirectDrawEnum.GetCount メソッドは、システムにインストールされた DirectDraw ドライバの数を返す。

object.GetCount() As Long

パラメータ

object
DirectDrawEnum オブジェクトを表すオブジェクト式。

戻り値

成功すれば、列挙オブジェクトのエントリの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

各エントリに 1 つの DirectDraw ドライバが記述される。個々のドライバの記述を取得するには、DirectDrawEnum.GetDescription、DirectDrawEnum.GetGuid、および DirectDrawEnum.GetName を使用する。


DirectDrawEnum.GetDescription

DirectDrawEnum.GetDescription メソッドは、指定した DirectDraw デバイスのドライバの記述を返す。

object.GetDescription(index As Long) As String

パラメータ

object
DirectDrawEnum オブジェクトを表すオブジェクト式。
index
DirectDrawEnum オブジェクト内の特定の DirectDraw デバイス。

戻り値

成功すれば、そのデバイスのドライバの記述を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawEnum.GetGuid

DirectDrawEnum.GetGuid は、指定した DirectDraw デバイスの固有の識別子を返す。

object.GetGuid(index As Long) As String

パラメータ

object
DirectDrawEnum オブジェクトを表すオブジェクト式。
index
DirectDrawEnum オブジェクト内の特定の DirectDraw デバイス。

戻り値

成功すれば、デバイスの固有の識別子を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawEnum.GetMonitorHandle

DirectDrawEnum.GetMonitorHandle は、指定した DirectDraw デバイスのモニタ ハンドルを返す。

object.GetName(index As Long) As Long

パラメータ

object
DirectDrawEnum オブジェクトを表すオブジェクト式。
index
DirectDrawEnum オブジェクト内の特定の DirectDraw デバイス。

戻り値

成功すれば、そのデバイスのモニタ ハンドルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawEnum.GetName

DirectDrawEnum.GetName は、指定した DirectDraw デバイスのドライバ名を返す。

object.GetName(index As Long) As String

パラメータ

object
DirectDrawEnum オブジェクトを表すオブジェクト式。
index
DirectDrawEnum オブジェクト内の特定の DirectDraw デバイス。

戻り値

成功すれば、そのデバイスのドライバ名を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawEnumModes

アプリケーションは、DirectDrawEnumModes クラスのメソッドを使って、そのコンピュータで使用可能なビデオ モードを列挙する。このオブジェクトは、DirectDraw7.GetDisplayModesEnum メソッドによって作成され、データが格納される。

DirectDraw モード列挙 | GetCount
 | GetItem


DirectDrawEnumModes.GetCount

DirectDrawEnumModes.GetCount メソッドは、使用可能なビデオ モードの数を返す。

object.GetCount() As Long

パラメータ

object
DirectDrawEnumModes オブジェクトを表すオブジェクト式。

戻り値

成功すれば、使用可能なビデオ モードの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

各エントリに 1 つのビデオ モードが記述される。個々のビデオ モードの記述を取得するには、DirectDrawEnumModes.GetItem を使用する。


DirectDrawEnumModes.GetItem

DirectDrawEnumModes.GetItem メソッドは、列挙オブジェクトで指定した要素のビデオ モードの記述を返す。

object.GetItem(index As Long, info As DDSURFACEDESC2)

パラメータ

object
DirectDrawEnumModes オブジェクトを表すオブジェクト式。
index
配列のどの要素にアクセスするかを示す番号。各要素が使用可能なビデオ モードになる。
info
ビデオ モード情報が格納される DDSURFACEDESC2 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DirectDrawEnumModes オブジェクトに含まれるビデオ モードの数は、DirectDrawEnumModes.GetCount によって取得できる。


DirectDrawEnumSurfaces

アプリケーションは、DirectDrawEnumSurfaces クラスのメソッドを使って、作成されたすべてのサーフェスを列挙する。このオブジェクトは、DirectDrawSurface7.GetAttachedSurfaceEnum メソッドによって作成され、データが格納される。

DirectDraw サーフェス列挙 | GetCount
 | GetItem


DirectDrawEnumSurfaces.GetCount

DirectDrawEnumSurfaces.GetCount メソッドは、作成されたサーフェスの数を返す。

object.GetCount() As Long

パラメータ

object
DirectDrawEnumSurfaces オブジェクトを表すオブジェクト式。

戻り値

成功すれば、作成されたサーフェスの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

各エントリに作成された DirectDraw サーフェスが記述される。各サーフェスの記述を取得するには、DirectDrawEnumSurfaces.GetItem を使用する。


DirectDrawEnumSurfaces.GetItem

DirectDrawEnumSurfaces.GetItem メソッドは、DirectDrawEnumSurfaces オブジェクトに含まれる作成されたサーフェスのリストから、特定のサーフェスを返す。

object.GetItem(index As Long) As DirectDrawSurface7

パラメータ

object
DirectDrawEnumSurfaces オブジェクトを表すオブジェクト式。
index
配列のどの要素にアクセスするかを示す番号。各要素が作成されたサーフェスを表す。

戻り値

そのサーフェスを記述する DirectDrawSurface7 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

作成されたサーフェスの数を取得するには、DirectDrawEnumSurfaces.GetCount メソッドを呼び出す。


DirectDrawGammaControl

アプリケーションは DirectDrawGammaControl クラスのメソッドを使用して、プライマリ サーフェスの赤、緑、および青ガンマ ランプ レベルを調整する。この項は、このクラスのメソッドのリファレンスである。このオブジェクトは、DirectDrawSurface7.GetDirectDrawGammaControl メソッドによって作成される。

概要については、「ガンマ コントロールとカラー コントロール」を参照すること。

ガンマ ランプ | GetGammaRamp
 | SetGammaRamp


DirectDrawGammaControl.GetGammaRamp

DirectDrawGammaControl.GetGammaRamp メソッドは、プライマリ サーフェスに対する赤、緑、および青のガンマ ランプを取得する。

object.GetGammaRamp( _
    flags As CONST_DDSGRFLAGS, _
    gammaRamp As DDGAMMARAMP)

パラメータ

object
DirectDrawGammaControl オブジェクトを表す オブジェクト式。
flags
ガンマ キャリブレーションを要求するかどうかを示す CONST_DDSGRFLAGS 列挙の定数の 1 つ。このパラメータを DDSGR_CALIBRATE に設定すると、口径測定器がすべてのシステム上で同一になるように、ディスプレイの物理的性質に従って、ガンマ ランプの調節を要求できる。キャリブレーションを必要としない場合は、このパラメータを 0 に設定する。
gammaRamp
現在の赤、緑、および青のガンマ ランプを含む DDGAMMARAMP 型。この型は、フレーム バッファの色の値をデジタル-アナログ コンバータ (DAC) に渡す色の値にマップする。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

参照

DirectDrawGammaControl.SetGammaRamp、ガンマ コントロールとカラー コントロール


DirectDrawGammaControl.SetGammaRamp

DirectDrawGammaControl.SetGammaRamp メソッドは、プライマリ サーフェスに対する赤、緑、および青のガンマ ランプを設定する。

object.SetGammaRamp( _
    flags As CONST_DDSGRFLAGS, _
    gammaRamp As DDGAMMARAMP)

パラメータ

object
DirectDrawGammaControl オブジェクトを表す オブジェクト 式。
flags
ガンマ キャリブレーションを要求するかどうかを示す CONST_DDSGRFLAGS 列挙の定数の 1 つ。このパラメータを DDSGR_CALIBRATE に設定すると、口径測定器がすべてのシステム上で同一になるように、ディスプレイの物理的性質に従って、ガンマ ランプの調整を要求できる。キャリブレーションを必要としない場合は、このパラメータを 0 に設定する。
gammaRamp
新しい赤、緑、および青のガンマ ランプ エントリを含む DDGAMMARAMP 型。個々の配列は、フレーム バッファの色の値をデジタル-アナログ コンバータ (DAC) に渡す色の値にマップする。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

注意

すべてのシステムでガンマ キャリブレーションをサポートするわけではない。ガンマ キャリブレーションをサポートするかどうかを決めるには、DirectDraw7.GetCaps を呼び出し、メソッドが返した後に関連する DDCAPS 型の lCaps2 メンバを調べる。DDCAPS_CANCALIBRATEGAMMA 能力フラグが存在すると、ガンマ キャリブレーションはサポートされる。

ガンマ ランプのキャリブレーションでは、いくつかの処理にオーバーヘッドが起こるので、頻繁に使用できない。

ガンマ キャリブレーションをサポートしないシステム上で実行する場合、flags パラメータに DDSGR_CALIBRATE フラグを設定すると、このメソッドは成功する。キャリブレーションせずに新しいガンマ ランプ値を設定すると、メソッドは成功する。

参照

DirectDrawGammaControl.GetGammaRamp、ガンマ コントロールとカラー コントロール


DirectDrawIdentifier

アプリケーションは、DirectDrawIdentifier クラスのメソッドを使用して、DirectDraw ドライバに関する情報を取得する。ひどいドライバやチップセット反応の回避方法を実装する特定のハードウェア インストールを認識するには、このオブジェクトを注意して使用すること。このオブジェクトは、DirectDraw7.GetDeviceIdentifier メソッドによって作成される。

DirectDrawdentifier のメソッドは、以下のグループにまとめることができる。

ドライバ情報 | GetDescription
 | GetDeviceId
 | GetDeviceIdentifier
 | GetDriver
 | GetDriverSubVersion
 | GetDriverVersion
 | GetRevision
 | GetSubSysId
 | GetVendorId
 | GetWHQLLevel


DirectDrawIdentifier.GetDescription

DirectDrawIdentifier.GetDescription メソッドは、ドライバの記述を返す。

object.GetDescription() As String

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ドライバの記述を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawIdentifier.GetDeviceId

DirectDrawIdentifier.GetDeviceId メソッドは、チップセットのタイプを示す識別子を返す。

object.GetDeviceId() As Long

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、チップセットのタイプを示す識別子を返す。不明の場合は 0。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawIdentifier.GetDeviceIdentifier

DirectDrawIdentifier.GetDeviceIndentifier メソッドは、ドライバ/チップセット ペア固有の識別子を返す。

object.GetDeviceIndentifier() As String

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ドライバ/チップセットの GUID を返す。不明の場合は 0。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

ドライバ/チップセットへの変更を調査して、グラフィックス サブシステムのプロフィールを再作成したい場合は、ここで返された GUID を使用する。また、特定の疑わしいドライバを識別する場合にも使用できる。


DirectDrawIdentifier.GetDriver

DirectDrawIdentifier.GetDriver メソッドは、DirectDraw デバイス ドライバの名前を返す。

object.GetDriver() As String

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ドライバ名を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawIdentifier.GetDriverSubVersion

DirectDrawIdentifier.GetDriverSubVersion メソッドは、ドライバのサブ バージョンを返す。

object.GetDriverSubVersion() As Long

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ドライバのサブ バージョンを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

この要素を使用して疑わしいドライバを識別する場合は、注意して行うこと。この目的のためには、デバイス識別子を使用することを勧める。


DirectDrawIdentifier.GetDriverVersion

DirectDrawIdentifier.GetDriverVersion メソッドは、ドライバのメイン バージョンを返す。

object.GetDriverVersion() As Long

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ドライバのメイン バージョンを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

この要素を使用して疑わしいドライバを識別する場合は、注意して行うこと。この目的のためには、デバイス識別子を使用することを勧める。


DirectDrawIdentifier.GetRevision

DirectDrawIdentifier.GetRevision メソッドは、チップセットの改訂版レベルを返す。

object.GetRevision() As Long

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、チップセットの改訂版レベルの識別子を返す。不明の場合は 0。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawIdentifier.GetSubSysId

DirectDrawIdentifier.GetSubSysId メソッドは、サブシステムの識別子を返す。

object.GetSubSysId() As Long

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、サブシステムの識別子を返す。通常、特定の基盤を意味する。不明の場合は 0。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawIdentifier.GetVendorId

DirectDrawIdentifier.GetVendorId メソッドは、メーカーの識別子を返す。

object.GetVendorId() As Long

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、メーカーの識別子を返す。不明の場合は 0。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawIdentifier.GetWHQLLevel

DirectDrawIdentifier.GetWHQLLevel メソッドは、デバイス/ドライバ ペアの WHQL (Windows Hardware Quality Lab) 認証レベルを取得する。

object.GetWHQLLevel() As Long

パラメータ

object
DirectDrawIdentifier オブジェクトを表すオブジェクト式。

戻り値

成功すれば、デバイス/ドライバ ペアの WHQL (Windows Hardware Quality Lab) 認証レベルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawPalette

アプリケーションは、DirectDrawPalette クラスのメソッドを使って、DirectDrawPalette オブジェクトを作成し、システムレベル変数と共に作用する。DirectDrawPalette オブジェクトは、DirectDrawSurface7.GetPalette メソッドによって作成される。

この項は、このクラスのメソッドのリファレンスである。概要については、「パレット」を参照すること。

DirectDrawPalette クラスのメソッドは、以下のグループにまとめることができる。

パレット能力 | GetCaps
パレット エントリ | GetEntries
 | SetEntries


DirectDrawPalette.GetCaps

DirectDrawPalette.GetCaps メソッドは、このパレット オブジェクトの能力を取得する。

object.GetCaps() As CONST_DDPCAPSFLAGS

パラメータ

object
DirectDrawPalette オブジェクトを表すオブジェクト式。

戻り値

成功すれば、パレット オブジェクトの能力を示す CONST_DDPCAPSFLAGS 列挙の定数の 1 つを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawPalette.GetEntries

DirectDrawPalette.GetEntries メソッドは、DirectDrawPalette オブジェクトからのパレット値を照会する。

object.GetEntries( _
    start As Long, _
    count As Long, _
    val() As PALETTEENTRY)

パラメータ

object
DirectDrawPalette オブジェクトを表すオブジェクト式。
start
順番に取得するエントリの開始。
count
val() に指定するアドレスに適合するパレット エントリの数。個々のパレット エントリの色は、start パラメータの値から count パラメータから 1 を引いた値まで、順番に返される (これらの値は、DirectDrawPalette.SetEntries で設定される)。
val()
PALETTEENTRY 型の変数の配列。DirectDraw7.CreatePalette の flags パラメータに DDPCAPS_8BITENTRIES フラグが設定されている場合、パレット エントリは 1 バイトごととなる。それ以外は 4 バイトごととなる。個々のフィールドは、色記述となる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPALETTIZED

参照

DirectDrawPalette.SetEntries


DirectDrawPalette.SetEntries

DirectDrawPalette.SetEntries メソッドは、DirectDrawPalette オブジェクトのエントリを即座に変更する。

object.SetEntries( _
    start As Long, _
    count As Long, _
    val() As PALETTEENTRY)

パラメータ

object
DirectDrawPalette オブジェクトを表すオブジェクト式。
start
設定される最初のエントリ。
count
変更されるパレット エントリの数。
val()
PALETTEENTRY 型の変数の配列。DirectDraw7.CreatePalette の flags パラメータに DDPCAPS_8BITENTRIES フラグが設定されている場合、パレット エントリは 1 バイトごととなる。それ以外は 4 バイトごととなる。個々のフィールドは、色記述となる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOPALETTEATTACHED
DDERR_NOTPALETTIZED
DDERR_UNSUPPORTED

参照

DirectDrawPalette.GetEntries、DirectDrawSurface7.SetPalette


DirectDrawSurface7

アプリケーションは DirectDrawSurface7 クラスのメソッドを使って、DirectDrawSurface オブジェクトを作成し、システムレベル変数と共に作用する。この項は、このクラスのメソッドのリファレンスである。概要については、「サーフェス」を参照すること。

DirectDrawSurface7 クラスのメソッドは、以下のグループにまとめることができる。

メモリの割り当て | IsLost
 | Restore
サーフェスのアタッチ | AddAttachedSurface
 | DeleteAttachedSurface
 | GetAttachedSurface
 | GetAttachedSurfaceEnum
ブリット | Blt
 | BltColorFill
 | BltFast
 | BltFx
 | BltToDC
 | GetBltStatus
カラー キーイング | GetColorKey
 | SetColorKey
デバイス コンテキスト | GetDC
 | ReleaseDC
描画とテキスト | DrawBox
 | DrawCircle
 | DrawEllipse
 | DrawLine
 | DrawRoundedBox
 | DrawText
 | GetDrawStyle
 | GetDrawWidth
 | GetFillColor
 | GetFillStyle
 | GetFontBackColor
 | GetFontTransparency
 | GetForeColor
 | SetDrawStyle
 | SetDrawWidth
 | SetFillColor
 | SetFillStyle
 | SetFont
 | SetFontBackColor
 | SetFontTransparency
 | SetForeColor
フリッピング | Flip
 | GetFlipStatus
ロック | GetLockedArray
 | GetLockedPixel
 | Lock
 | SetLockedPixel
 | Unlock
その他 | GetDirectDraw
 | GetDirectDrawColorControl
 | GetDirectDrawGammaControl
オーバーレイ | GetOverlayPosition
 | GetOverlayZOrdersEnum
 | SetOverlayPosition
 | UpdateOverlay
 | UpdateOverlayFx
 | UpdateOverlayZOrder
サーフェス能力 | GetCaps
サーフェス クリッパー | GetClipper
 | SetClipper
サーフェス特性 | ChangeUniquenessValue
 | GetPixelFormat
 | GetSurfaceDesc
 | GetUniquenessValue
サーフェス パレット | GetPalette
 | SetPalette
テクスチャ | GetLOD
 | GetPriority
 | SetLOD
 | SetPriority


DirectDrawSurface7.AddAttachedSurface

DirectDrawSurface7.AddAttachedSurface メソッドは、指定したサーフェスをこのサーフェスにアタッチする。

object.AddAttachedSurface(ddS As DirectDrawSurface7)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
ddS
アタッチされるサーフェスに対する DirectDrawSurface7 オブジェクト。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

注意

DirectDrawSurface7.DeleteAttachedSurface メソッドを使って、明示的にサーフェスのアタッチを解除できる。DirectDraw7.CreateSurface の呼び出しで作成する複合サーフェスとは異なり、このメソッドでアタッチされるサーフェスは自動的に解放されない。このようなサーフェスの解放は、アプリケーションの役目である。

Z バッファ、アルファ チャネル、およびバック バッファを含むアタッチが可能である。自動的にほかのアタッチを切断するアタッチもある。たとえば、3D Z バッファを一度に 1 つのバック バッファだけにアタッチすることができる。アタッチは双方向的ではないので、サーフェスをそれ自体にアタッチすることはできない。エミュレートされていないサーフェスに、エミュレートされたサーフェス (システム メモリ内) をアタッチすることはできない。1 つのサーフェスがテクスチャ マップでない限り、2 つのアタッチされたサーフェスは同じサイズでなくてはらない。フリッピング サーフェスを同じ型の別のフリッピング サーフェスにアタッチできないが、異なるタイプの 2 つのサーフェスをアタッチすることができる。たとえば、フリッピング Z バッファを、通常のフリッピング サーフェスにアタッチできる。フリッピングしないサーフェスを同じタイプの別のフリッピングしないサーフェスにアタッチすると、2 つのサーフェスはフリッピング チェーンとなる。フリッピングしないサーフェスをフリッピング サーフェスにアタッチすると、既存のフリッピング チェーンの一部となる。追加サーフェスはこのチェーンに追加され、DirectDrawSurface7.Flip メソッドを呼び出すごとにサーフェスを 1 ステップ進ませる。

参照

DirectDrawSurface7.DeleteAttachedSurface、DirectDrawSurface7.GetAttachedSurfaceEnum


DirectDrawSurface7.Blt

DirectDrawSurface7.Blt メソッドは、ビット ブリットを実行する。このメソッドは、ブリット処理中に Z バッファまたはアルファ ブレンディング (アルファ チャネルを参照) をサポートしない。

object.Blt( _
    destRect As RECT, _
    ddS As DirectDrawSurface7, _
    srcRect As RECT, _
    flags As CONST_DDBLTFLAGS) As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
destRect
転送先サーフェス上にブリットする矩形の左上と右下の位置を定義する RECT 型。このパラメータが空の RECT 型の場合、転送先サーフェス全体を使用する。
ddS
ブリットの転送元である DirectDrawSurface オブジェクトに対する DirectDrawSurface7 オブジェクト。
srcRect
転送元サーフェス上からブリットする矩形の左上と右下の位置を定義する RECT 型。このパラメータが空の RECT の場合、転送元サーフェス全体を使用する。
flags
カラー キー情報を指定する、またはメソッドから特別な動作を要求する、関連付けられた DDBLTFX 型の有効メンバを決定する CONST_DDBLTFLAGS 列挙の定数の組み合わせ。

エラー コード

失敗すれば、次のいずれかのエラー コードを返す。

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
DDERR_WASSTILLDRAWING

注意

このメソッドは、同期または非同期のブリット (後者は、デフォルト動作) を、ディスプレイ メモリからディスプレイ メモリへ、ディスプレイ メモリからシステム メモリへ、システム メモリからディスプレイ メモリへ、システム メモリからシステム メモリへのいずれかで実行する能力がある。ブリットは、転送元カラー キーおよび転送先カラー キーを使って実行される。転送元および転送先矩形が同じサイズではない場合、任意の伸縮や収縮が行われる。

通常、ブリットがビジーの場合、またはブリットをセット アップできなかった場合、DirectDrawSurface7.Blt はエラーと共に即座に返る。同期ブリットを要求するには、DDBLT_WAIT フラグを指定する。DDBLT_WAIT フラグを指定すると、ブリットがセット アップされるか、メソッドが返る前に別のエラーが発生するまで、このメソッドは待機する。

right および bottom メンバは排他なので、dstRect と srcRect パラメータを定義することに注意する。したがって、right から left を引くと矩形の幅と等しくなる。これは、矩形の幅から 1 を引いた値ではない。

このメソッドはしばしばエラーを引き起こすので、エラー オブジェクトにエラーを設定する代わりに、エラー コードを返す。


DirectDrawSurface7.BltColorFill

DirectDrawSurface7.BltColorFill メソッドは、指定した転送先矩形に、単色のビット ブリットを実行する。

object.BltColorFill( _
    destRect As RECT, _
    fillvalue As Long) As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
destRect
転送先サーフェス上にブリットする矩形の左上と右下の位置を定義する RECT 型。このパラメータが RECT 型の場合、転送先サーフェス全体を使用する。
fillvalue
ブリットするカラー。

エラー コード

失敗すれば、次のいずれかのエラー コード返す。

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

注意

このメソッドはしばしばエラーを引き起こすので、エラー オブジェクトにエラーを設定する代わりに、エラー コードを返す。


DirectDrawSurface7.BltFast

DirectDrawSurface7.BltFast メソッドは、転送元カラー キーまたは転送先カラー キーを使って、転送元コピー ブリットまたは透過型ブリットを実行する。

object.BltFast( _
    dx As Long, _
    dy As Long, _
    ddS As DirectDrawSurface7, _
    srcRect As RECT, _
    trans As CONST_DDBLTFASTFLAGS) As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
dx、dy
転送先サーフェス上にブリットする x 座標と y 座標。
ddS
ブリットの転送元である DirectDrawSurface オブジェクトに対する DirectDrawSurface7 オブジェクト。
srcRect
転送元サーフェス上からブリットする矩形の左上と右下の位置を定義する RECT 型。
trans
転送のタイプを識別する CONST_DDBLTFASTFLAGS 列挙の定数の 1 つ。

エラー コード

失敗すれば、次のいずれかのエラー コードを返す。

DDERR_EXCEPTION
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

ハードウェアが非同期ブリットをサポートする場合、このメソッドは常にそれを試みる。

このメソッドはディスプレイ メモリ サーフェス上だけで作用し、ブリット中はクリップできない。アタッチしたクリッパーのあるサーフェス上でこのメソッドを使用する場合、呼び出しは失敗して、メソッドは DDERR_UNSUPPORTED を返す。

DirectDrawSurface7.BltFast のソフトウェア実装は、DirectDrawSurface7.Blt メソッドよりも 10 パーセント高速となる。ただし、ディスプレイ ハードウェアを使用している場合は、速さの違いはない。

通常、ブリットがビジーの場合、およびブリットがセット アップされていない場合、DirectDrawSurface7.BltFast は即座にエラーを返す。ただし、ブリットがセット アップされるか別のエラーが発生するまで、このメソッドを返さない場合は、DDBLTFAST_WAIT フラグを使用する。

このメソッドはしばしばエラーを引き起こすので、エラー オブジェクトにエラーを設定する代わりに、エラー コードを返す。


DirectDrawSurface7.BltFx

DirectDrawSurface7.BltFx メソッドは、BltFx パラメータで指定したブリット エフェクト動作を追加して、ビット ブリットを実行する。

object.BltFx( _
    destRect As RECT, _
    ddS As DirectDrawSurface7, _
    srcRect As RECT, _
    flags As CONST_DDBLTFLAGS, _
    BltFx As DDBLTFX) As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
destRect
転送先サーフェス上にブリットする矩形の左上と右下の位置を定義する RECT 型。このパラメータが空の RECT 型の場合、転送先サーフェス全体を使用する。
ddS
ブリットの転送元になる DirectDrawSurface7 オブジェクト。
srcRect
転送元サーフェス上からブリットする矩形の左上と右下の位置を定義する RECT 型。このパラメータが空の RECT の場合、転送元サーフェス全体を使用する。
flags
カラー キー情報を指定する、またはメソッドから特別な動作を要求する、関連付けられた DDBLTFX 型の有効メンバを決定する CONST_DDBLTFLAGS 列挙の定数の組み合わせ。
BltFx
実行する追加のブリット エフェクト動作を指定する DDBLTFX 型。

エラー コード

失敗すれば、次のいずれかのエラー コードを返す。

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

注意

このメソッドはしばしばエラーを引き起こすので、エラー オブジェクトにエラーを設定する代わりに、エラー コードを返す。


DirectDrawSurface7.BltToDC

DirectDrawSurface7.BltToDC メソッドは、指定したデバイス コンテキストにビット ブリットを実行する。

object.BltToDC( _
    hdc As LONG, _
    srcRect As RECT, _
    destRect As RECT)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
hdc
デバイス コンテキストのハンドル。
srcRect
転送元サーフェス上からブリットする矩形の左上と右下の位置を定義する RECT 型。このパラメータが空の RECT 型の場合、転送元サーフェス全体を使用する。
destRect
転送先サーフェス上にブリットする矩形の左上と右下の位置を定義する RECT 型。このパラメータが空の RECT の場合、転送元サーフェス全体を使用する。

エラー コード

失敗すれば、次のいずれかのエラー コードを返す。

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

注意

このメソッドはしばしばエラーを引き起こすので、エラー オブジェクトにエラーを設定する代わりに、エラー コードを返す。


DirectDrawSurface7.ChangeUniquenessValue

DirectDrawSurface7.ChangeUniquenessValue メソッドは、このサーフェスに対する固有値を手動で更新する。

object.ChangeUniquenessValue()

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

サーフェスのコンテンツを変更すると常に、DirectDraw は固有値を自動的に更新する。

参照

DirectDrawSurface7.GetUniquenessValue


DirectDrawSurface7.DeleteAttachedSurface

DirectDrawSurface7.DeleteAttachedSurface メソッドは、アタッチした 2 つのサーフェスのアタッチを解除する。

object.DeleteAttachedSurface(ddS As DirectDrawSurface7)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
ddS
アタッチを解除する DirectDrawSurface オブジェクトに対する DirectDrawSurface7 オブジェクト。このパラメータが Nothing の場合、アタッチされたすべてのサーフェスのアタッチが解除される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_CANNOTDETACHSURFACE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_SURFACENOTATTACHED

注意

DirectDrawSurface7.AddAttachedSurface メソッドではなく、DirectDraw により形成される暗黙的なアタッチは解除できない。フリッピング チェーンからサーフェスのアタッチを解除すると、チェーン中のほかのサーフェスを変更する可能性がある。フリッピング チェーンからフロント バッファのアタッチを解除する場合、チェーン中の次のサーフェスがフロント バッファとなり、その次のサーフェスがバック バッファとなる。チェーンからバック バッファのアタッチを解除する場合、次のサーフェスがバック バッファとなる。チェーンから平面サーフェスのアタッチを解除する場合、そのチェーンが単に短くなる。フリッピング チェーンに 2 つサーフェスがあるだけで、それらのアタッチを解除する場合、そのチェーンは破棄されて、両サーフェスは元の転送先に戻る。

参照

DirectDrawSurface7.Flip


DirectDrawSurface7.DrawBox

DirectDrawSurface7.DrawBox メソッドは、サーフェス上に長方形を描画する。

object.DrawBox( _
    x1 As Long, _
    y1 As Long, _
    x2 As Long, _
    y2 As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x1, y1, x2, y2
描画する長方形の左上と右下の位置。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの線スタイルは実線、塗りつぶしスタイルは透明に設定されている。これらのスタイルは、それぞれ DirectDrawSurface7.SetDrawStyle と DirectDrawSurface7.SetFillStyle を使って変更できる。


DirectDrawSurface7.DrawCircle

DirectDrawSurface7.DrawCircle メソッドは、サーフェス上に円を描画する。

object.DrawCircle( _
    x1 As Long, _
    y1 As Long, _
    r As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x1, y1, r
描画する円の中心点と半径。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの線スタイルは実線、塗りつぶしスタイルは透明に設定されている。これらのスタイルは、それぞれ DirectDrawSurface7.SetDrawStyle と DirectDrawSurface7.SetFillStyle を使って変更できる。


DirectDrawSurface7.DrawEllipse

DirectDrawSurface7.DrawEllipse メソッドは、サーフェス上に楕円を描画する。

object.DrawEllipse(x1 As Long, _
    y1 As Long, _
    x2 As Long, _
    y2 As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x1, y1, x2, y2
描画する楕円の境界矩形の左上と右上の角。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの線スタイルは実線、塗りつぶしスタイルは透明に設定されている。これらのスタイルは、それぞれ DirectDrawSurface7.SetDrawStyle と DirectDrawSurface7.SetFillStyle を使って変更できる。


DirectDrawSurface7.DrawLine

DirectDrawSurface7.DrawLine メソッドは、サーフェス上に線を描く。

object.DrawLine( _
    x1 As Long, _
    y1 As Long, _
    x2 As Long, _
    y2 As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x1, y1, x2, y2
線の終点。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの線スタイルは実線に設定されているが、DirectDrawSurface7.SetDrawStyle を使って変更できる。


DirectDrawSurface7.DrawRoundedBox

DirectDrawSurface7.DrawRoundedBox メソッドは、サーフェス上に角丸長方形を描画する。

object.DrawRoundedBox( _
    x1 As Long, _
    y1 As Long, _
    x2 As Long, _
    y2 As Long, _
    rw As Long, _
    rh As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x1, y1, x2, y2
長方形の左上と右下の位置。
rw
角丸長方形の描画に使用される楕円の幅。
rh
角丸長方形の描画に使用される楕円の高さ。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの線スタイルは実線、塗りつぶしスタイルは透明に設定されている。これらのスタイルは、それぞれ DirectDrawSurface7.SetDrawStyle と DirectDrawSurface7.SetFillStyle を使って変更できる。


DirectDrawSurface7.DrawText

DirectDrawSurface7.DrawText メソッドは、サーフェス上にテキストを表示する。

object.DrawText( _
    x As Long, _
    y As Long, _
    text As String, _
    b As Boolean)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x, y
テキストを表示するサーフェス上の場所。
text
表示するテキスト。
b
現在のカーソル位置にテキストを表示するかどうかを指定するブール値。「注意」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DirectDrawSurface7.DrawText への最後の呼び出しの終わりにテキストを追加するには、x および y 座標として 0,0 を渡し、b を TRUE に設定する。b を FALSE に設定してこのメソッドを呼び出すと、指定した x および y 座標にテキストが表示される。


DirectDrawSurface7.Flip

DirectDrawSurface7.Flip メソッドは、DDSCAPS_BACKBUFFER サーフェスと関連付けられたサーフェス メモリを、フロント バッファ サーフェスと関連付ける。

object.Flip( _
    ddS As DirectDrawSurface7, _
    flags As CONST_DDFLIPFLAGS)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
ddS
フリッピング チェーン内の任意のサーフェスに対する DirectDrawSurface7 オブジェクト。このパラメータのデフォルトは Nothing であり、この場合、DirectDraw は互いにアタッチされている順にバッファから循環する。このパラメータが Nothing でない場合、DirectDraw はフリッピング チェーンの次のサーフェスの代わりに指定したサーフェスへフリップする。指定したサーフェスがフリッピング チェーンのメンバではない場合、メソッドは失敗する。
flags
フリップ オプションを指定する CONST_DDFLIPFLAGS 列挙の 1 つまたは複数の定数。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

このメソッドを呼び出すことができるのは、DDSCAPS_FLIP および DDSCAPS_FRONTBUFFER 能力のあるサーフェスだけである。このメソッドを呼び出す以前にフロント バッファと関連付けられたディスプレイ メモリは、バック バッファと関連付けられる。

ddS パラメータは、バック バッファがフロント バッファになるべきバッファではないというまれな場合に使用される。通常、このパラメータは Nothing である。

DirectDrawSurface7.Flip メソッドは、常に垂直線消去と同期する。サーフェスがビデオ ポートに割り当てられていると、このメソッドは表示されるオーバーレイ サーフェスとビデオ ポートのターゲット サーフェスを更新する。

詳細については、「フリッピング サーフェス」を参照すること。

参照

DirectDrawSurface7.GetFlipStatus


DirectDrawSurface7.GetAttachedSurface

DirectDrawSurface7.GetAttachedSurface メソッドは、指定した能力を持つアタッチされたサーフェスを取得する。

object.GetAttachedSurface( _
    caps As DDSCAPS2) As DirectDrawSurface7

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
caps
サーフェスのハードウェア能力を含む DDSCAPS2 型。

戻り値

成功すれば、DirectDrawSurface7 オブジェクトを返す。取得するサーフェスは、caps パラメータの記述に適合するものである。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST

注意

アタッチは、複数の DirectDrawSurface オブジェクトを複合型に接続するために使用される。複合型は、Z バッファと共に 3D ページ フリッピングをサポートするために必要な型である。要求する能力に適合するアタッチされたサーフェスが 1 つ以上ある場合、このメソッドは失敗する。この場合、アプリケーションはアタッチされたサーフェスを取得するために、DirectDrawSurface7.GetAttachedSurfaceEnum メソッドを使用しなければならない。

このメソッドの成功により取得したオブジェクトは、DirectDrawSurface7 オブジェクト変数に割り当てなければならない。以下に例を示す。

Dim DDrawSurface as DirectDrawSurface7
Set DDrawSurface = object.GetAttachedSurface()


DirectDrawSurface7.GetAttachedSurfaceEnum

DirectDrawSurface7.GetAttachedSurfaceEnum メソッドは、アタッチされたサーフェスの情報を格納する DirectDrawEnumSurfaces オブジェクトを返す。

object.GetAttachedSurfaceEnum() As DirectDrawEnumSurfaces

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawEnumSurfaces 列挙インターフェイスを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

注意

アタッチされたサーフェスの数を取得するには DirectDrawEnumSurfaces.GetCount、アタッチされたサーフェスの記述を取得するには DirectDrawEnumSurfaces.GetItem を呼び出す。

このメソッドの成功により取得したオブジェクトは、DirectDrawEnumSurfaces オブジェクト変数に割り当てなければならない。以下に例を示す。

Dim SurfaceEnum as DirectDrawEnumSurfaces
Set SurfaceEnum = object.GetAttachedSurfacesEnum()


DirectDrawSurface7.GetBltStatus

DirectDrawSurface7.GetBltStatus メソッドは、ブリット ステータスを取得する。

object.GetBltStatus(flags As CONST_DDGBSFLAGS) As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
flags
CONST_DDGBSFLAGS 列挙の定数の 1 つ。

戻り値

成功すれば、flags パラメータで指定された定数に応じて、FALSE の場合はゼロ、TRUE の場合はゼロ以外の値を返す。

エラー コード

失敗すればエラーが発生し、サーフェスがフリッピング プロセスを終えていない場合は Err.Number に DDERR_WASSTILLDRAWING が設定され、それ以外の場合は次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DD_OK
DDERR_UNSUPPORTED


DirectDrawSurface7.GetCaps

DirectDrawSurface7.GetCaps メソッドは、サーフェスの能力を取得する。これらの能力は、ディスプレイ デバイスの能力に関連している必要はない。

object.GetCaps(caps As DDSCAPS2)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
caps
サーフェスのハードウェア能力を格納する DDSCAPS2 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawSurface7.GetClipper

DirectDrawSurface7.GetClipper メソッドは、サーフェスに関連付けられた DirectDrawClipper オブジェクトを取得する。

object.GetClipper() As DirectDrawClipper

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、サーフェスに関連付けられた DirectDrawClipper オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPPERATTACHED

参照

DirectDrawSurface7.SetClipper

注意

メソッドの成功により取得したオブジェクトは、DirectDrawClipper オブジェクト変数に割り当てられなければならない。以下に例を示す。

Dim Clipper as DirectDrawClipper
Set Clipper = object.GetClipper()


DirectDrawSurface7.GetColorKey

DirectDrawSurface7.GetColorKey メソッドは、DirectDrawSurface オブジェクトに対するカラー キー値を取得する。

object.GetColorKey(flags As Long, val As DDCOLORKEY)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
flags
要求されるカラー キー。以下のいずれかになる。
DDCKEY_DESTBLT
ブリット処理に対する転送先カラー キーとして使用されるカラー キーや色空間。
DDCKEY_DESTOVERLAY
オーバーレイ処理に対する転送先カラー キーとして使用されるカラー キーや色空間。
DDCKEY_SRCBLT
ブリット処理に対する転送元カラー キーとして使用されるカラー キーや色空間。
DDCKEY_SRCOVERLAY
オーバーレイ処理に対する転送元カラー キーとして使用されるカラー キーや色空間。
val
DirectDrawSurface オブジェクトの指定されたカラー キーに対する現在の値を格納する DDCOLORKEY 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOLORKEY
DDERR_NOCOLORKEYHW
DDERR_SURFACELOST
DDERR_UNSUPPORTED

参照

DirectDrawSurface7.SetColorKey


DirectDrawSurface7.GetDC

DirectDrawSurface7.GetDC メソッドは、サーフェスに対するデバイス コンテキストの GDI 互換ハンドルを作成する。

object.GetDC() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、デバイス コンテキストのハンドルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

このメソッドは、サーフェスをロックする DirectDrawSurface7.Lock メソッドの内部バージョンを使用する。DirectDrawSurface7.ReleaseDC メソッドが呼び出されるまで、サーフェスはロックされたままである。

ReleaseDC は、GetDC を呼び出した同じスレッドから呼び出さなければならない。

参照

DirectDrawSurface7.Lock


DirectDrawSurface7.GetDirectDraw

DirectDrawSurface7.GetDirectDraw メソッドは、サーフェスを作成するために使用された DirectDraw オブジェクトを取得する。

object.GetDirectDraw() As DirectDraw7

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDraw7 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

メソッドの成功により取得したオブジェクトは、DirectDraw7 オブジェクト変数に割り当てなければならない。以下に例を示す。

Dim DDrawObject as DirectDraw7
Set DDrawObject = object.GetDDInterface()


DirectDrawSurface7.GetDirectDrawColorControl

DirectDrawSurface7.GetDirectDrawColorControl メソッドは、サーフェスで使用される DirectDrawColorControl オブジェクトを返す。

object.GetDirectDrawColorControl() As DirectDrawColorControl

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawColorControl オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawSurface7.GetDirectDrawGammaControl

DirectDrawSurface7.GetDirectDrawGammaControl メソッドは、サーフェスで使用される DirectDrawGammaControl オブジェクトを返す。

object.GetDirectDrawGammaControl() As DirectDrawGammaControl

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawGammaControl オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawSurface7.GetDrawStyle

DirectDrawSurface7.GetDrawStyle メソッドは、DirectDrawSurface7.SetDrawStyle によって設定されたスタイルを返す。

object.GetDrawStyle() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

DirectDrawSurface7.SetDrawStyle によって設定されたスタイルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの線スタイルは実線である。


DirectDrawSurface7.GetDrawWidth

DirectDrawSurface7.GetDrawWidth メソッドは、DirectDrawSurface7.SetDrawWidth によって設定された幅を返す。

object.GetDrawWidth() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

DirectDrawSurface7.SetDrawWidth によって設定された幅を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの線幅は 1 である。


DirectDrawSurface7.GetFillColor

DirectDrawSurface7.GetFillColor メソッドは、DirectDrawSurface7.SetFillColor によって設定された塗りつぶしカラーを返す。

object.GetFillColor() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawSurface7.SetFillColor によって設定された塗りつぶしカラーの値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの塗りつぶしカラーは黒である。


DirectDrawSurface7.GetFillStyle

DirectDrawSurface7.GetFillStyle メソッドは、DirectDrawSurface7.SetFillStyle によって設定された塗りつぶしスタイルを返す。

object.GetFillStyle() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawSurface7.SetFillStyle によって設定された塗りつぶしスタイルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの塗りつぶしスタイルは透明である。


DirectDrawSurface7.GetFlipStatus

DirectDrawSurface7.GetFlipStatus メソッドは、サーフェスがフリッピング プロセスを終えたかどうかを示す。

object.GetFlipStatus(flags As CONST_DDGFSFLAGS) As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
flags
CONST_DDGFSFLAGS 列挙の定数の 1 つ。

戻り値

成功すれば、flags パラメータで指定された定数に応じて、FALSE の場合はゼロを、TRUE の場合はゼロ以外の値を返す。

エラー コード

失敗すればエラーが発生し、サーフェスがフリッピング プロセスを終えていない場合は Err.Number に DDERR_WASSTILLDRAWING が設定され、それ以外の場合は次のいずれかの値に設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DD_OK
DDERR_UNSUPPORTED

参照

DirectDrawSurface7.Flip


DirectDrawSurface7.GetFontBackColor

DirectDrawSurface7.GetFontBackColor メソッドは、フォントの背景色を返す。

object.GetFontBackColor() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、フォントの背景色を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectDrawSurface7.SetFontBackColor


DirectDrawSurface7.GetFontTransparency

DirectDrawSurface7.GetFontTransparency メソッドは、DirectDrawSurface7.SetFontTransparency によって設定されたフォントの透過性を返す。

object.GetFontTransparency() As Boolean

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

フォントが透過型に設定されている場合はゼロ以外の値を、透過型に設定されていない場合はゼロを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawSurface7.GetForeColor

DirectDrawSurface7.GetForeColor メソッドは、DirectDrawSurface7.SetForeColor によって設定された前景色を返す。

object.GetForeColor() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawSurface7.SetForeColor によって設定された前景色を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawSurface7.GetLockedArray

DirectDrawSurface7.GetLockedArray メソッドは、DirectDrawSurface7.Lock メソッドの呼び出しによってロックされたピクセルの配列を返す。

object.GetLockedArray( _
    array() As Byte)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
array()
ロックされたピクセルの配列 (バイト)。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドは、経験を積んだユーザーのためのメソッドである。このメソッドは、DirectDrawSurface7.Lock を呼び出してから DirectDrawSurface7.Unlock を呼び出すまでの間のみ使用できる。ディスプレイ カードによっては、ピッチがサーフェスの幅と一致しない場合があるので、メモリへの書き込みが配列を越えないように注意する。


DirectDrawSurface7.GetLockedPixel

DirectDrawSurface7.GetLockedPixel メソッドは、DirectDrawSurface7.SetLockedPixel によって設定されたピクセルを返す。

object.GetLockedPixel( _
    x As Long, _
    y As Long) As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x、y
ロックされたピクセルの座標。

戻り値

成功すれば、ロックされたピクセルのカラーを返す。この値は、ピクセル フォーマットと同じフォーマットになる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawSurface7.GetLOD

DirectDrawSurface7.GetLOD メソッドは、管理されるミップマップ サーフェスに現在設定されている最大詳細レベルを取得する。このメソッドは、管理下のテクスチャに対してのみ成功する (「注意」参照)。

object.GetLOD() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ミップマップ チェーンの最大詳細レベルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDPARAMS
DDERR_INVALIDOBJECT

注意

アプリケーションは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE フラグで作成されたテクスチャ) に対してのみこのメソッドを呼び出すことができる。非管理下のテクスチャに対してこのメソッドを呼び出すと、メソッドが失敗し、DDERR_INVALIDOBJECT エラーが発生する。

このメソッドは、このチェーン内でローカル ビデオ メモリにロードできる最大詳細ミップマップを Direct3D テクスチャ マネージャに通知する。たとえば、5 レベルのミップマップ チェーンで、戻り値が 2 の場合、テクスチャ マネージャは所定の時間でミップマップ レベル 2 から 4 だけをローカル ビデオ メモリにロードする。同様に、チェーン内の最大詳細ミップマップのサイズが 256×256 で、戻り値が 2 の場合、ビデオ メモリに存在する最大ミップマップのサイズは 64×64 になる。

参照

DirectDrawSurface7.SetLOD、ミップマップによるテクスチャ フィルタリング、自動テクスチャ管理、テクスチャ


DirectDrawSurface7.GetOverlayPosition

表示状態のアクティブ オーバーレイ サーフェス (DDSCAPS_OVERLAY フラグが設定されている) が与えられると、DirectDrawSurface7.GetOverlayPosition メソッドはサーフェスのディスプレイ座標を返す。

object.GetOverlayPosition(x As Long, y As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x、y
x 座標と y 座標のアドレス。

戻り値

成功すれば、アクティブ オーバーレイ サーフェスのディスプレイ座標を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST

参照

DirectDrawSurface7.SetOverlayPosition、DirectDrawSurface7.UpdateOverlay


DirectDrawSurface7.GetOverlayZOrdersEnum

DirectDrawSurface7::GetOverlayZOrdersEnum メソッドは、指定した転送先のオーバーレイ サーフェスの列挙に使用される DirectDrawEnumSurfaces オブジェクトを返す。オーバーレイは、フロントからバック、またはバックからフロントの順で列挙される。

object.GetOverlayZOrdersEnum( _
    flags As CONST_DDENUMOVERLAYZFLAGS) _
    As DirectDrawEnumSurfaces

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
flags
列挙オプションを指定する CONST_DDENUMOVERLAYZFLAGS 列挙の定数の 1 つ。

戻り値

成功すれば、オーバーレイ サーフェスの z オーダー情報を照会できる DirectDrawEnumSurfaces オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

参照

DirectDrawSurface7.UpdateOverlayZOrder


DirectDrawSurface7.GetPalette

DirectDrawSurface7.GetPalette メソッドは、このメソッドに関連付けられた DirectDrawPalette オブジェクトを取得する。

object.GetPalette() As DirectDrawPalette

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectDrawPalette オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED

注意

このメソッドの成功により取得したオブジェクトは、DirectDrawPalette オブジェクト変数に割り当てなければならない。以下に例を示す。

Dim DDPalette as DirectDrawPalette
Set DDPalette = object.GetPalette()

参照

DirectDrawSurface7.SetPalette


DirectDrawSurface7.GetPixelFormat

DirectDrawSurface7.GetPixelFormat メソッドは、サーフェスのカラー フォーマットとピクセル フォーマットを取得する。

object.GetPixelFormat(pf As DDPIXELFORMAT)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
pf
サーフェスの現在のピクセル フォーマットと色空間フォーマットの詳細情報を格納する DDPIXELFORMAT 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE


DirectDrawSurface7.GetPriority

DirectDrawSurface7.GetPriority メソッドは、このテクスチャのテクスチャ管理優先順位を取得する。このメソッドは、管理下のテクスチャに対してのみ成功する (「注意」参照)。

object.GetPriority() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、テクスチャ管理優先順位を返す。

エラー コード

失敗すればエラーが発生し、パラメータが無効の場合、または Direct3D によってテクスチャが管理されていない場合は、Err.Number に DDERR_INVALIDOBJECT が設定される。

注意

管理下のテクスチャをメモリから削除するときに、この優先順位が使用される。優先順位の低いテクスチャは、優先順位の高いテクスチャより先に削除される。2 つのテクスチャの優先順位が等しい場合、最近使用したテクスチャをメモリに残し、古い方を削除する。

アプリケーションは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE フラグで作成されたテクスチャ) に対してのみ優先順位を設定および取得できる。非管理化のテクスチャに対してこのメソッドを呼び出すと失敗し、DDERR_INVALIDOBJECT を返す。

参照

DirectDrawSurface7.SetPriority、自動テクスチャ管理


DirectDrawSurface7.GetSurfaceDesc

DirectDrawSurface7.GetSurfaceDesc メソッドは、現在の状態におけるサーフェス記述を取得する。

object.GetSurfaceDesc(surface As DDSURFACEDESC2)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
surface
このサーフェスの現在の記述を格納する DDSURFACEDESC2 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawSurface7.GetUniquenessValue

DirectDrawSurface7.GetUniquenessValue メソッドは、このサーフェスの現在の固有値を取得する。

object.GetUniquenessValue() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、サーフェスの現在の固有値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

定義される固有値だけが、サーフェスが DirectDraw のコントロール以上に変更されやすいことを示す 0 となる。ほかの固有値は、キャッシュされる前の固有値と異なる場合にだけ重要となる。現在の値がキャッシュされる値と異なる場合、次にサーフェスのコンテンツが変更される。

参照

DirectDrawSurface7.ChangeUniquenessValue


DirectDrawSurface7.IsLost

DirectDrawSurface7.IsLost メソッドは、DirectDrawSurface オブジェクトに関連付けられたサーフェス メモリが解放されたかどうかを決定する。

object.IsLost() As Long

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、サーフェスが解放されていない場合はゼロ (FALSE)、解放されている場合はゼロ以外の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

注意

このメソッドを使って、サーフェス メモリを再割り当てする必要があるかどうかを確認できる。再割り当ては、DirectDrawSurface7.Restore メソッドによって行う。DirectDrawSurface オブジェクトがサーフェス メモリを消失すると、大部分のメソッドは DDERR_SURFACELOST を返してほかのアクションを実行しない。

ディスプレイ カードのモードが変更されるとき、またはアプリケーションがディスプレイ カードへの排他アクセスを受け取り、ディスプレイ カードに現在割り当てられているサーフェス メモリをすべて解放するときに、サーフェスはそれらのメモリを消失できる。

参照

DirectDrawSurface7.Restore、サーフェスの消失とリストア


DirectDrawSurface7.Lock

DirectDrawSurface7.Lock メソッドは、サーフェス メモリを取得する。

object.Lock( _
    r As RECT, _
    desc As DDSURFACEDESC2, _
    flags As CONST_DDLOCKFLAGS, _
    hnd As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
r
ロックされるサーフェスの領域を示す矩形の左上と右下の位置を定義する RECT 型。このパラメータが空の RECT の場合、サーフェス全体がロックされる。
desc
サーフェスに関する詳細情報を格納する DDSURFACEDESC2 型。
flags
ロックのタイプを記述する CONST_DDLOCKFLAGS 列挙の定数の 1 つ。
hnd
使用されないので、0 に設定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

注意

このメソッドの使用については、「サーフェス メモリへの直接アクセス」を参照すること。

サーフェス メモリを取得した後、対応する DirectDrawSurface7.Unlock メソッドが呼び出されるまでサーフェスにアクセスできる。サーフェスのロックが解除されると、サーフェス メモリは無効となる。

サーフェスのロックされた領域からブリットするために、DirectDraw ブリット関数を呼び出してはならない。この関数を呼び出した場合、ブリットは DDERR_SURFACEBUSY または DDERR_LOCKEDSURFACES のどちらかを返す。さらに、GDI ブリット関数は、ロックされたビデオ メモリ サーフェスで使用されると、何も返さずに失敗する。

このメソッドは、DirectDrawSurface7.Unlock メソッドを呼び出すまで、DirectDraw で Win16Mutex (Win16Lock とも呼ばれる) を保持する場合がある。GUI デバッガは、Win16Mutex が保持されている間は処理できない。

参照

DirectDrawSurface7.Unlock、DirectDrawSurface7.GetDC、DirectDrawSurface7.ReleaseDC


DirectDrawSurface7.ReleaseDC

DirectDrawSurface7.ReleaseDC メソッドは、DirectDrawSurface7.GetDC メソッドによって取得されたデバイス コンテキストのハンドルを解放する。

object.ReleaseDC(hdc As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
hdc
DirectDrawSurface7.GetDC によって取得されたデバイス コンテキストのハンドル。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_UNSUPPORTED

注意

このメソッドは、DirectDrawSurface7.GetDC メソッドが呼び出されたときに、前もってロックされたサーフェスのロックも解除する。

ReleaseDC は、GetDC を呼び出した同じスレッドから呼び出さなければならない。

参照

DirectDrawSurface7.GetDC


DirectDrawSurface7.Restore

DirectDrawSurface7.Restore メソッドは、消失されたサーフェスをリストアする。これは、DirectDrawSurface オブジェクトに関連付けられたサーフェス メモリを解放するときに生じる。

object.Restore()

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

注意

このメソッドは、サーフェスに対して割り当てられたメモリをリストアするが、サーフェスが消失される前に存在した可能性のあるビットマップは再ロードしない。DDSCAPS2_PERSISTENTCONTENT フラグで作成されたサーフェスのコンテンツだけが自動的にリストアされる。このフラグがないサーフェスが消失されると、メモリをリストアしてから保持したグラフィックスを完全に再構成しなければならない。

ディスプレイ カードのモードを変更するため、またはアプリケーションがディスプレイ カードへの排他アクセスを受け取って、カードに割り当てられた現在のサーフェス メモリのすべてを解放するために、サーフェスを消失できる。DirectDrawSurface オブジェクトがそのサーフェス メモリを消失すると、大部分のメソッドは DDERR_SURFACELOST を返して、ほかのあらゆる機能が実行できなくなる。DirectDrawSurface7.Restore メソッドは、サーフェス メモリを再割り当てして、DirectDrawSurface オブジェクトに再びアタッチする。

このメソッドへの単一の呼び出しは、DirectDrawSurface オブジェクトの暗に関連付けられたサーフェス (バック バッファなど) をリストアする。暗に作成されたサーフェスをリストアしようとすると、エラーが生じる。DirectDrawSurface7.Restore は、DirectDrawSurface7.AddAttachedSurface メソッドを使って作成した明示的なアタッチには作用しない。つまり、これらの個々のサーフェスは、個別にリストアしなくてはならない。

参照

DirectDrawSurface7.IsLost


DirectDrawSurface7.SetClipper

DirectDrawSurface7.SetClipper メソッドは、サーフェスにクリッパー オブジェクトをアタッチしたり、サーフェスからクリッパー オブジェクトを削除する。

object.SetClipper(val As DirectDrawClipper)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
val
DirectDrawSurface オブジェクトにアタッチされる DirectDrawClipper オブジェクトに対する DirectDrawClipper オブジェクト。このパラメータが Nothing の場合、現在の DirectDrawClipper オブジェクトはアタッチを解除される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOCLIPPERATTACHED

注意

val パラメータとして Nothing を渡す場合、サーフェスからクリッパーが削除される。このメソッドは、プライマリ サーフェスにオーバーレイされるか、ブリットされるサーフェスにより主に使用される。ただし、このメソッドは、どのサーフェス上でも使用できる。DirectDrawClipper オブジェクトがアタッチされて、クリップ リストがそれに関連付けられると、DirectDrawClipper オブジェクトは親の DirectDrawSurface オブジェクトを含む DirectDrawSurface7.Blt 処理で使用される。このメソッドは、DirectDrawSurface オブジェクトの現在の DirectDrawClipper オブジェクトにおけるアタッチも解除できる。

参照

DirectDrawSurface7.GetClipper


DirectDrawSurface7.SetColorKey

DirectDrawSurface7.SetColorKey メソッドは、ハードウェアがサーフェス基準ごとにカラー キーをサポートする場合、DirectDrawSurface オブジェクトに対するカラー キー値を設定する。

object.SetColorKey( _
    flags As CONST_DDCKEYFLAGS, _
    val As DDCOLORKEY)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
flags
要求されるカラー キーのタイプを指定する CONST_DDCKEYFLAGS 列挙の定数の 1 つ。
val
DirectDrawSurface オブジェクトに対して新しいカラー キー値を含む DDCOLORKEY 型。前もって設定したカラー キーを削除するには、この値を Nothing にする。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOOVERLAYHW
DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

注意

透過型ブリットとオーバーレイに対して、転送先サーフェスの転送先の色と転送元サーフェスの転送元の色を設定しなくてはならない。

参照

DirectDrawSurface7.GetColorKey


DirectDrawSurface7.SetDrawStyle

DirectDrawSurface7.SetDrawStyle は、線スタイルを設定する。

object.SetDrawStyle(drawStyle As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
drawStyle
次の線スタイルのいずれかに設定する。
設定 | 説明
0 | (デフォルト) 実線
1 | 破線
2 | 点線
3 | 一点破線
4 | 二点破線
5 | 透明
6 | 実線

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectDrawSurface7.GetDrawStyle


DirectDrawSurface7.SetDrawWidth

DirectDrawSurface7.SetDrawWidth メソッドは、描画メソッドで使用される線の幅を設定する。

object.setDrawWidth(drawWidth As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
drawWidth
描画メソッドで使用される線の幅。デフォルト値は 1 である。1 から 32,767 の任意の値を指定できる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectDrawSurface7.GetDrawWidth


DirectDrawSurface7.SetFillColor

DirectDrawSurface7.SetFillColor メソッドは、描画メソッドで使用される塗りつぶしカラーを指定する。

object.SetFillColor(color As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
color
描画メソッドで塗りつぶしカラーとして使用される RGB 値。デフォルト値は黒 (&H00000000) である。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectDrawSurface7.GetFillColor


DirectDrawSurface7.SetFillStyle

DirectDrawSurface7.SetFillStyle メソッドは、描画メソッドで使用される塗りつぶしスタイルを指定する。

object.SetFillStyle(fillStyle As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
fillStyle
次の塗りつぶしスタイルのいずれかに設定する。
設定 | 説明
0 | (デフォルト) 均一
1 | 透明
2 | 横縞
3 | 縦縞
4 | 右上がり斜め縞
5 | 右下がり斜め縞
6 | 格子縞
7 | 斜め格子縞

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectDrawSurface7.GetFillStyle


DirectDrawSurface7.SetFont

DirectDrawSurface7.SetFont メソッドは、DirectDrawSurface7.DrawText で使用されるフォントを指定する。

object.SetFont(font As IFont)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
font
IFont クラスで指定されたフォント。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawSurface7.SetFontBackColor

DirectDrawSurface7.SetFontBackColor メソッドは、フォントの背景色を設定する。

object.SetFontBackColor(color As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
color
フォントの背景色。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawSurface7.SetFontTransparency

DirectDrawSurface7.SetFontTransparency メソッドは、DirectDrawSurface7.DrawText が透過型の場合、そのフォントを使用するかどうかを指定する。

object.SetFontTransparency(b As Boolean)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
b
フォントが透過型の場合は D_TRUE、フォントが透過型でない場合は D_FALSE に設定する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectDrawSurface7.SetForeColor

DirectDrawSurface7.SetForeColor メソッドは、描画メソッドで使用される前景色を設定する。

object.SetForeColor(color As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
color
前景色として設定する RGB 値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectDrawSurface7.GetForeColor


DirectDrawSurface7.SetLockedPixel

DirectDrawSurface7.SetLockedPixel メソッドは、指定したカラーに単一ピクセルを設定し、ロックされたサーフェスを更新する。

object.SetLockedPixel( _
    x As Long, _
    y As Long, _
    col As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x、y
設定するピクセルの座標。
col
設定するピクセルの RGB 値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

事前に DirectDrawSurface7.Lock を呼び出してサーフェスをロックしておかなければならない。

参照

DirectDrawSurface7.GetLockedPixel


DirectDrawSurface7.SetLOD

DirectDrawSurface7.SetLOD メソッドは、管理されるミップマップ サーフェスの最大詳細レベルを設定する。このメソッドは、管理下のサーフェスに対してのみ成功する (「注意」参照)。

object.SetLOD(lod As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
lod
メソッドが成功した場合にミップマップ チェーンに設定される詳細レベルの最大値。

戻り値

成功すれば、DD_OK を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

アプリケーションは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE フラグで作成されたテクスチャ) に対してのみこのメソッドを呼び出すことができる。非管理化のメソッドに対してこのメソッドを呼び出すと失敗し、DDERR_INVALIDOBJECT を返す。

このメソッドは、このチェーン内でローカル ビデオ メモリにロードできる最大詳細ミップマップを Direct3D テクスチャ マネージャに通知する。たとえば、5 レベルのミップマップ チェーンで、lod が 2 に設定されている場合、テクスチャ マネージャは所定の時間でミップマップ レベル 2 から 4 だけをローカル ビデオ メモリにロードする。同様に、チェーン内の最大詳細ミップマップのサイズが 256×256 で、最大レベルが 2 に設定されている場合、ビデオ メモリに存在する最大ミップマップのサイズは 64×64 になる。

参照

DirectDrawSurface7.GetLOD、ミップマップによるテクスチャ フィルタリング、自動テクスチャ管理、テクスチャ


DirectDrawSurface7.SetOverlayPosition

DirectDrawSurface7.SetOverlayPosition メソッドは、オーバーレイ サーフェスのディスプレイ座標を変更する。

object.SetOverlayPosition(x As Long, y As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
x、y
新しい x ディスプレイ座標と y ディスプレイ座標。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST
DDERR_UNSUPPORTED

参照

DirectDrawSurface7.GetOverlayPosition


DirectDrawSurface7.SetPalette

DirectDrawSurface7.SetPalette メソッドは、サーフェスにパレット オブジェクトをアタッチする (または、サーフェスからそのアタッチを解除する)。サーフェスは、すべての連続する処理にこのパレットを使用する。パレットの変更は、リフレッシュ タイミングに関係なく即座に行われる。

object.SetPalette(ddp As DirectDrawPalette)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
ddp
このサーフェスと共に使用されるパレット オブジェクトに対する DirectDrawPalette オブジェクト。このパラメータが Nｏｔｈｉｎｇ の場合、現在のパレットはアタッチを解除される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_SURFACELOST
DDERR_UNSUPPORTED

注意

ddp パラメータとして Ｎｏｔｈｉｎｇ を渡す場合、パレットはサーフェスから削除される。

参照

DirectDrawSurface7.GetPalette、DirectDraw7.CreatePalette


DirectDrawSurface7.SetPriority

DirectDrawSurface7.SetPriority メソッドは、このテクスチャにテクスチャ管理優先順位を割り当てる。このメソッドは、管理下のテクスチャに対してのみ成功する (「注意」参照)。

object.SetPriority(Priority As Long)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
Priority
テクスチャの新しいテクスチャ管理優先順位を示す値。

エラー コード

失敗すればエラーが発生し、パラメータが無効の場合、またはテクスチャが Direct3D によって管理されていない場合は、Err.Number にDDERR_INVALIDOBJECT が設定される。

注意

管理下のテクスチャをメモリから削除するときに、この優先順位が使用される。優先順位の低いテクスチャは、優先順位の高いテクスチャより先に削除される。2 つのテクスチャの優先順位が等しい場合、最近使用したテクスチャをメモリに残し、古い方を削除する。

アプリケーションは、管理下のテクスチャ (DDSCAPS2_TEXTUREMANAGE フラグで作成されたテクスチャ) に対してのみ優先順位を設定および取得できる。非管理化のテクスチャに対してこのメソッドを呼び出すと失敗し、DDERR_INVALIDOBJECT を返す。

参照

DirectDrawSurface7.GetPriority、自動テクスチャ管理


DirectDrawSurface7.Unlock

DirectDrawSurface7.Unlock メソッドは、DirectDraw に直接サーフェス処理が完了したことを通知する。

object.Unlock(r As RECT)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
r
DirectDrawSurface7.Lock メソッドへの呼び出しに対応する呼び出しで、サーフェスをロックするために使用した RECT 型。DirectDrawSurface7.Lock メソッドへの呼び出しに対応する呼び出しの r パラメータに Nothing を渡すことにより、サーフェス全体をロックした場合に限り、このパラメータは Nothing になる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOTLOCKED
DDERR_SURFACELOST

注意

異なる転送先矩形のある同じサーフェスに対する DirectDrawSurface7.Lock の呼び出しは複数回可能なため、r パラメータは DirectDrawSurface7.Lock および DirectDrawSurface7.Unlock メソッドの呼び出しにリンクする。

参照

DirectDrawSurface7.Lock


DirectDrawSurface7.UpdateOverlay

DirectDrawSurface7.UpdateOverlay メソッドは、オーバーレイ サーフェスのビジュアル属性を再配置したり変更する。これらのサーフェスには、DDSCAPS_OVERLAY フラグを設定する必要がある。

object.UpdateOverlay(RECT As RECT, _
    ddS As DirectDrawSurface7, _
    rectD As RECT, _
    flags As CONST_DDOVERFLAGS)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
RECT
オーバーレイとして使用される転送元サーフェスの領域の x、y、幅、および高さを定義する RECT 型。このパラメータは、オーバーレイを隠蔽する場合や、オーバーレイ サーフェス全体を使用し、かつオーバーレイ サーフェスがデバイス ドライバからの境界およびサイズ アライメント制限にも従うことを示す場合に、空の RECT とする。
ddS
オーバーレイが行われるサーフェスに対する DirectDrawSurface7 オブジェクト。
rectD
オーバーレイを移動する転送先サーフェスの領域の x、y、幅、および高さを定義する RECT 型。このパラメータは、オーバーレイを隠蔽する場合に空の RECT となる。
flags
CONST_DDOVERFLAGS 列挙の 1 つまたは複数の定数。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_DEVICEDOESNTOWNSURFACE
DDERR_GENERIC
DDERR_HEIGHTALIGN
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOSTRETCHHW
DDERR_NOTAOVERLAYSURFACE
DDERR_OUTOFCAPS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_XALIGN


DirectDrawSurface7.UpdateOverlayFx

DirectDrawSurface7.UpdateOverlayFx メソッドは、特殊なオーバーレイ エフェクトを使って、オーバーレイ サーフェスに対するビジュアル属性を再配置したり変更する。これらのサーフェスには、DDSCAPS_OVERLAY フラグを設定する必要がある。

object.UpdateOverlayFx(RECT As RECT, _
    ddS As DirectDrawSurface7, _
    rectD As RECT, _
    flags As CONST_DDOVERFLAGS, _
    ddoverfx As DDOVERLAYFX)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
RECT
オーバーレイとして使用される転送元サーフェスの領域の x、y、幅、および高さを定義する RECT 型。このパラメータは、オーバーレイを隠蔽する場合や、オーバーレイ サーフェス全体を使用し、かつオーバーレイ サーフェスがデバイス ドライバからの境界およびサイズ アライメント制限にも従うことを示す場合に、空の RECT とする。
ddS
オーバーレイが行われるサーフェスに対する DirectDrawSurface7 オブジェクト。
rectD
オーバーレイを移動する転送先サーフェスの領域の x、y、幅、および高さを定義する RECT 型。このパラメータは、オーバーレイを隠蔽する場合に空の RECT となる。
flags
CONST_DDOVERFLAGS 列挙の 1 つまたは複数の定数。ddoverfx パラメータによって設定されたエフェクトを適用するには、DDOVER_DDFX フラグを指定しなければならない。
ddoverfx
オーバーレイ サーフェスに適用される追加のエフェクトを記述する DDOVERLAYFX 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_DEVICEDOESNTOWNSURFACE
DDERR_GENERIC
DDERR_HEIGHTALIGN
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOSTRETCHHW
DDERR_NOTAOVERLAYSURFACE
DDERR_OUTOFCAPS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_XALIGN


DirectDrawSurface7.UpdateOverlayZOrder

DirectDrawSurface7.UpdateOverlayZOrder メソッドは、オーバーレイの ｚ オーダーを設定する。

object.UpdateOverlayZOrder( _
    flags As CONST_DDOVERZFLAGS, _
    ddS As DirectDrawSurface7)

パラメータ

object
DirectDrawSurface7 オブジェクトを表すオブジェクト式。
flags
オーバーレイの位置を記述する CONST_DDOVERZFLAGS 列挙の定数の 1 つ。
ddS
オーバーレイ チェーンの相対位置として使用される DirectDraw サーフェスに対する DirectDrawSurface7 オブジェクト。このパラメータは、DDOVERZ_INSERTINBACKOF および DDOVERZ_INSERTINFRONTOF だけのために必要とされる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTAOVERLAYSURFACE


IFont

IFont クラスは、DirectDrawSurface7.SetFont メソッドが、DirectDrawSurface7.DrawText メソッドで使用されるフォントを指定するために使用する。

このクラスと、関連するメソッドについては、Visual Basic の Font クラスの項を参照すること。


DirectDraw グローバル メソッド

DirectX7 クラスは、DirectX for Visual Basic アプリケーションの基本クラスである。このクラスには、すべての DirectX コンポーネントで使用されるメソッドがある。DirectDraw に関連するメソッドは以下のとおりである。

  • DirectX7.DirectDrawCreate
  • DirectX7.GetDDEnum


型

この項では、DirectDraw と共に使用される以下の型について説明する。

  • DDBLTFX
  • DDCAPS
  • DDCOLORCONTROL
  • DDCOLORKEY
  • DDGAMMARAMP
  • DDOVERLAYFX
  • DDPIXELFORMAT
  • DDSCAPS2
  • DDSURFACEDESC2
  • PALETTEENTRY
  • RECT


DDBLTFX

DDBLTFX 型は、ラスタ処理、エフェクト、およびオーバーライド情報を DirectDrawSurface7.Blt メソッドに渡す。

Type DDBLTFX
    ddckDestColorKey_high As Long
    ddckDestColorKey_low As Long
    ddckSrcColorKey_high As Long
    ddckSrcColorKey_low As Long
    lAlphaDestConst As Long
    lAlphaDestConstBitDepth As Long
    lAlphaEdgeBlend As Long
    lAlphaEdgeBlendBitDepth As Long
    lAlphaSrcConst As Long
    lAlphaSrcConstBitDepth As Long
    lDDFX As CONST_DDBLTFXFLAGS
    lDDROP As Long
    lFill As Long
    lReserved As Long
    lROP As Long
    lRotationAngle As Long
    lZBufferBaseDest As Long
    lZBufferHigh As Long
    lZBufferLow As Long
    lZBufferOpCode As Long
    lZDestConst As Long
    lZDestConstBitDepth As Long
    lZSrcConst As Long
    lZSrcConstBitDepth As Long
End Type

メンバ

ddckDestColorKey_high
転送先カラー キーとして使用される色範囲の上限値。
ddckDestColorKey_low
転送先カラー キーとして使用される色範囲の下限値。
ddckSrcColorKey_high
転送元カラー キーとして使用される色範囲の上限値。
ddckSrcColorKey_low
転送元カラー キーとして使用される色範囲の下限値。
lAlphaDestConst
転送先アルファ チャネルとして使用する定数。
lAlphaDestConstBitDepth
転送先アルファ定数のビット深度。
lAlphaEdgeBlend
エッジ ブレンドで使用するアルファ定数。
lAlphaEdgeBlendBitDepth
アルファ エッジ ブレンドにおけるビット深度定数。
lAlphaSrcConst
転送元アルファ チャネルとして使用する定数。
lAlphaSrcConstBitDepth
転送元アルファ定数のビット深度。
lDDFX
FX 処理のタイプ。CONST_DDBLTFXFLAGS 列挙の定数の 1 つ。
lDDROP
DirectDraw ラスタ処理。
lFill
DDBLT_COLORFILL を指定するときに、サーフェスを塗りつぶすために使用する色。この値は、転送先サーフェスのピクセル フォーマットに該当するピクセルでなくてはならない。パレット化サーフェスであればパレット インデックス、16 ビット RGB サーフェスであれば 16 ビット ピクセル値となる。
lReserved
将来的な使用のために確保されている。
lROP
Win32 ラスタ処理。サポートされるラスタ処理のリストを取得するには、DirectDraw7.GetCaps メソッドを呼び出す。
lRotationAngle
ブリットにおける回転角度。
lZBufferBaseDest
Z バッファの転送先基底値。
lZBufferHigh
Z バッファの最高限界。
lZBufferLow
Z バッファの最低限界。
lZBufferOpCode
Z バッファ比較。
lZDestConst
転送先 Z バッファとして使用する定数。
lZDestConstBitDepth
転送先 z 定数のビット深度。
lZSrcConst
転送元 Z バッファとして使用する定数。
lZSrcConstBitDepth
転送元 z 定数のビット深度。


DDCAPS

DDCAPS 型は、DirectDraw オブジェクトが明らかにするハードウェアの能力を表す。この型には、作成できる DirectDrawSurface オブジェクトの種類を記述するこのコンテキストの DDSCAPS2 型を含む。しかし、これらの能力が記述するサーフェスのすべてを同時に作成することは不可能な場合がある。この型は、DirectDraw7.GetCaps メソッドで使用される。

Type DDCAPS
    ddsCaps As DDSCAPS2
    lAlignBoundaryDest As Long
    lAlignBoundarySrc As Long
    lAlignSizeDest As Long
    lAlignSizeSrc As Long
    lAlignStrideAlign As Long
    lAlphaBltConstBitDepths As Long
    lAlphaBltPixelBitDepths As Long
    lAlphaBltSurfaceBitDepths As Long
    lAlphaOverlayConstBitDepths As Long
    lAlphaOverlayPixelBitDepths As Long
    lAlphaOverlaySurfaceBitDepths As Long
    lCaps As CONST_DDCAPS1FLAGS
    lCaps2 As CONST_DDCAPS2FLAGS
    lCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lCurrVideoPorts As Long
    lCurrVisibleOverlays As Long
    lFXCaps As CONST_DDFXCAPSFLAGS
    lMaxHwCodecStretch As Long
    lMaxLiveVideoStretch As Long
    lMaxOverlayStretch As Long
    lMaxVideoPorts As Long
    lMaxVisibleOverlays As Long
    lMinHwCodecStretch As Long
    lMinLiveVideoStretch As Long
    lMinOverlayStretch As Long
    lNLVBCaps As CONST_DDCAPS1FLAGS
    lNLVBCaps2 As CONST_DDCAPS2FLAGS
    lNLVBCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lNLVBFXCaps As CONST_DDFXCAPSFLAGS
    lNLVBRops (0 To 7) As Long
    lNumFourCCCodes As Long
    lPalCaps As CONST_DDPCAPSFLAGS
    lReserved1 As Long
    lReserved2 As Long
    lReserved3 As Long
    lReservedCaps As Long
    lRops (0 To 7) As Long
    lSSBCaps As CONST_DDCAPS1FLAGS
    lSSBCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lSSBFXCaps As CONST_DDFXCAPSFLAGS
    lSSBRops (0 To 7) As Long
    lSVBCaps As CONST_DDCAPS1FLAGS
    lSVBCaps2 As CONST_DDCAPS2FLAGS
    lSVBCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lSVBFXCaps As CONST_DDFXCAPSFLAGS
    lSVBRops (0 To 7) As Long
    lSVCaps As CONST_DDSTEREOCAPSFLAGS
    lVidMemFree As Long
    lVidMemTotal As Long
    lVSBCaps As CONST_DDCAPS1FLAGS
    lVSBCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lVSBFXCaps As CONST_DDFXCAPSFLAGS
    lVSRops (0 To 7) As Long
    lZBufferBitDepths As Long
End Type

メンバ

ddsCaps
追加の能力を記述する DDSCAPS2 型。
lAlignBoundaryDest
ピクセル単位のオーバーレイ サーフェスに対する転送先矩形のアライメント。
lAlignBoundarySrc
ピクセル単位のオーバーレイ サーフェスに対する転送元矩形のアライメント。
lAlignSizeDest
ピクセル単位のオーバーレイ サーフェスに対する転送先矩形のサイズ アライメント。オーバーレイ転送先矩形は、この値の倍数のピクセル幅でなくてはならない。
lAlignSizeSrc
ピクセル単位のオーバーレイ サーフェスに対する転送元矩形のサイズ アライメント。オーバーレイ転送元矩形は、この値の倍数のピクセル幅でなくてはならない。
lAlignStrideAlign
ストライド アライメント。
lAlphaBltConstBitDepths
DDBD_2、DDBD_4、または DDBD_8 (2 ビット、4 ビット、または 8 ビット/ピクセルを示す)。
lAlphaBltPixelBitDepths
DDBD_1、DDBD_2、DDBD_4、または DDBD_8 (1 ビット、2 ビット、4 ビット、または 8 ビット/ピクセルを示す)。
lAlphaBltSurfaceBitDepths
DDBD_1、DDBD_2、DDBD_4、または DDBD_8 (1 ビット、2 ビット、4 ビット、または 8 ビット/ピクセルを示す)。
lAlphaOverlayConstBitDepths
DDBD_2、DDBD_4、または DDBD_8 (2 ビット、4 ビット、または 8 ビット/ピクセルを示す)。
lAlphaOverlayPixelBitDepths
DDBD_1、DDBD_2、DDBD_4、または DDBD_8 (1 ビット、2 ビット、4 ビット、または 8 ビット/ピクセルを示す)。
lAlphaOverlaySurfaceBitDepths
DDBD_1、DDBD_2、DDBD_4、または DDBD_8 (1 ビット、2 ビット、4 ビット、または 8 ビット/ピクセルを示す)。
lCaps
ドライバ固有の能力を記述する CONST_DDCAPS1FLAGS 列挙の定数。
lCaps2
追加のドライバ固有能力を記述する CONST_DDCAPS2FLAGS 列挙の定数。
lCKeyCaps
カラー キー能力を記述する CONST_DDCKEYCAPSFLAGS 列挙の定数。
lCurrVideoPorts
ライブ ビデオ ポートの現在の数。
lCurrVisibleOverlays
表示されるオーバーレイまたはオーバーレイ スプライトの現在の数。
lFXCaps
ドライバ固有の伸縮とエフェクトの能力を記述する CONST_DDFXCAPSFLAGS 列挙の定数。
lMinHwCodecStretch および lMaxHwCodecStretch
廃止された。使用しない。
lMinLiveVideoStretch および lMaxLiveVideoStretch
廃止された。使用しない。
lMinOverlayStretch および lMaxOverlayStretch
1000 倍される最小および最大オーバーレイ伸縮係数。たとえば、1.3 = 1300。
lMaxVideoPorts
ライブ ビデオ ポートの最大数。
lMaxVisibleOverlays
表示されるオーバーレイまたはオーバーレイ スプライトの最大数。
lNLVBCaps
非ローカル ビデオ メモリからローカル ビデオ メモリへのブリットに対するドライバ固有の能力を記述する CONST_DDCAPS1FLAGS 列挙の定数。有効フラグは、lCaps メンバで使用されるブリット関連フラグと等しい。
lNLVBCaps2
非ローカル ビデオ メモリからローカル ビデオ メモリへのブリットに対する追加のドライバ固有能力を記述する CONST_DDCAPS2FLAGS 列挙の定数。有効フラグは、lCap2 メンバで使用されるブリット関連フラグと等しい。
lNLVBCKeyCaps
非ローカル ビデオ メモリからローカル ビデオ メモリへのブリットに対するドライバのカラー キー能力を記述する CONST_DDCKEYCAPSFLAGS 列挙の定数。有効フラグは、lCKeyCaps メンバで使用されるブリット関連フラグと等しい。
lNLVBFXCaps
非ローカル ビデオ メモリからローカル ビデオ メモリへのブリットに対するドライバの FX 能力を記述する CONST_DDFXCAPSFLAGS 列挙の定数。有効フラグは、lFXCap メンバで使用されるブリット関連フラグと等しい。
lNLVBRops[0 から 7]
非ローカル ビデオ メモリからローカル ビデオ メモリへのブリットに対してサポートされるラスタ処理。
lNumFourCCCodes
FOURCC コードの数。
lPalCaps
パレット能力を記述する CONST_DDPCAPSFLAGS 列挙の定数。
lReserved1、lReserved2、lReserved3、および lReservedCaps
将来的な使用のために確保されている。
lRops[0 から 7]
サポートされるラスタ処理。
lSSBCaps
システム メモリからシステム メモリへのブリットに対するドライバ固有の能力を記述する CONST_DDCAPS1FLAGS 列挙の定数。有効フラグは、lCaps メンバで使用されるブリット関連フラグと等しい。
lSSBCKeyCaps
システム メモリからシステム メモリへのブリットに対するドライバのカラー キー能力を記述する CONST_DDCKEYCAPSFLAGS 列挙の定数。有効フラグは、lCKeyCaps メンバで使用されるブリット関連フラグと等しい。
lSSBFXCaps
システム メモリからシステム メモリへのブリットに対するドライバの FX 能力を記述する CONST_DDFXCAPSFLAGS 列挙の定数。有効フラグは、lFXCaps メンバで使用されるブリット関連フラグと等しい。
lSSBRops[0 から 7]
システム メモリからシステム メモリへのブリットに対してサポートされるラスタ処理。
lSVBCaps
システム メモリからディスプレイ メモリへのブリットに対するドライバ固有の能力を記述する CONST_DDCAPS1FLAGS 列挙の定数。有効フラグは、ｌCaps メンバで使用されるブリット関連フラグと等しい。
lSVBCaps2
システム メモリからビデオ メモリへのブリットに対するドライバ固有の能力を記述する CONST_DDCAPS2FLAGS 列挙の定数。有効フラグは、lCaps2 メンバで使用されるブリット関連フラグと等しい。
lSVBCKeyCaps
システム メモリからディスプレイ メモリへのブリットに対するドライバのカラー キー能力を記述する CONST_DDCKEYCAPSFLAGS 列挙の定数。有効フラグは、lCKeyCaps メンバで使用されるブリット関連フラグと等しい。
lSVBFXCaps
システム メモリからディスプレイ メモリへのブリットに対するドライバの FX 能力を記述する CONST_DDFXCAPSFLAGS 列挙の定数。有効フラグは、lFXCaps メンバで使用されるブリット関連フラグと等しい。
lSVBRops[0 から 7]
システム メモリからディスプレイ メモリへのブリットに対してサポートされるラスタ処理。
lSVCaps
ステレオ ビジョン能力を記述する CONST_DDSTEREOCAPSFLAGS 列挙の定数。
lVidMemFree
ディスプレイ メモリの空き容量。
lVidMemTotal
ディスプレイ メモリの総容量。
lVSBCaps
ディスプレイ メモリからシステム メモリへのブリットに対するドライバ固有の能力を記述する CONST_DDCAPS1FLAGS 列挙の定数。有効フラグは、lCaps メンバで使用されるブリット関連フラグと等しい。
lVSBCKeyCaps
ディスプレイ メモリからシステム メモリへのブリットに対するドライバのカラー キー能力を記述する CONST_DDCKEYCAPSFLAGS 列挙の定数。有効フラグは、lCKeyCaps メンバで使用されるブリット関連フラグと等しい。
lVSBFXCaps
ディスプレイ メモリからシステム メモリへのブリットに対するドライバの FX 能力を記述する CONST_DDFXCAPSFLAGS 列挙の定数。有効フラグは、lFXCaps メンバで使用されるブリット関連フラグと等しい。
lVSRops[0 から 7]
ディスプレイ メモリからシステム メモリへのブリットに対してサポートされるラスタ処理。
lZBufferBitDepths
DDBD_8、DDBD_16、または DDBD_24 (8 ビット、16 ビット、24 ビット/ピクセルを示す)。32 ビット バッファはサポートされていない。


DDCOLORCONTROL

DDCOLORCONTROL 型は、DirectDrawVideoPortObject または プライマリ サーフェスに関連付けられたカラー コントロールを定義する。

Type DDCOLORCONTROL
    lBrightness As Long
    lColorEnable As Long
    lContrast As Long
    lFlags As CONST_DDCOLORFLAGS
    lGamma As Long
    lHue As Long
    lReserved1 As Long
    lSaturation As Long
    lSharpness As Long
End Type

メンバ

lBrightness
IRE 単位 100 で表した輝度。有効範囲は、0 から 10,000 まで。デフォルト値は 750 (7.5 IRE)。
lColorEnable
色を使用するかどうかを示すフラグ。このメンバがゼロの場合、色は使用しない。このメンバが 1 の場合、色を使用する。デフォルト値は 1。
lContrast
IRE 単位で表した輝度における上下の値の相対的差違。有効範囲は、0 から 20,000 まで。デフォルト値は 10,000 (100 IRE)。コントラストの上の値により、より暗い輝度は黒に向かう傾向があり、より明るい輝度は白に向かう傾向がある。コントラストの下の値は、すべての輝度を中間の輝度に向かわせる。
lFlags
どのメンバが有効なデータを含むかを示す CONST_DDCOLORFLAGS 列挙の定数。DirectDrawColorControl.GetColorControls メソッドによって返されたタイプの場合、デバイスによってサポートされるオプションも示す。
lGamma
輝度に適用されるガンマ修正量を制御する。有効範囲は、1 から 500 ガンマ単位で、デフォルト値は 1。
lHue
クロミナンス成分の位相関係。色相は度で指定され、有効範囲は -180 から 180 までである。デフォルト値は 0。
lReserved1
将来的な使用のために確保されている。
lSaturation
IRE 単位 100 で表したカラー強度。有効範囲は、0 から 20,000 まで。デフォルト値は 10,000 (100 IRE)。
lSharpness
任意の単位の鮮明度。有効範囲は、0 から 10 まで。デフォルト値は 5。


DDCOLORKEY

DDCOLORKEY 型は、転送元カラー キー、転送先カラー キー、または色空間を記述する。カラー キーは、上限と下限の範囲値が同じ場合に指定される。この型は、DirectDrawSurface7.GetColorKey および DirectDrawSurface7.SetColorKey メソッドで使用される。

Type COLORKEY
    high As Long
    low As Long
End Type

メンバ

high
カラー キーとして使用される色範囲の上限値。
low
カラー キーとして使用される色範囲の下限値。


DDGAMMARAMP

DDGAMMARAMP 型は、DirectDrawGammaControl.GetGammaRamp および DirectDrawGammaControl.SetGammaRamp メソッドのための赤、緑、および青のランプ データを含む。

Type DDGAMMARAMP
    blue(0 To 255) As Integer
    green(0 To 255) As Integer
    red(0 To 255) As Integer
End Type

メンバ

red、green、blue
赤、緑、および青のガンマ ランプ。

参照

ガンマ コントロールとカラー コントロール


DDOVERLAYFX

DDOVERLAYFX 型は、DirectDrawSurface7.UpdateOverlay メソッドにオーバーライド情報を渡す。

type DDOVERLAYFX
    dckDestColorkey As DDCOLORKEY
    dckSrcColorkey As DDCOLORKEY
    lAlphaDestConst As Long
    lAlphaDestConstBitDepth As Long
    lAlphaEdgeBlend As Long
    lAlphaEdgeBlendBitDepth As Long
    lAlphaSrcConst As Long
    lAlphaSrcConstBitDepth As Long
    lDDFX As CONST_DDOVERFXFLAGS
    lFlags As Long
End Type

メンバ

dckDestColorkey
転送先カラー キー オーバーライド。
dckSrcColorkey
転送元カラー キー オーバーライド。
lAlphaDestConst
転送先のアルファ チャネルとして使用される定数。
lAlphaDestConstBitDepth
転送先のアルファ定数を指定するために使用されるビット深度。
lAlphaEdgeBlend
エッジ ブレンドに対するアルファとして使用される定数。
lAlphaEdgeBlendBitDepth
アルファ エッジ ブレンドに対する定数を指定するために使用されるビット深度。
lAlphaSrcConst
転送元のアルファ チャネルとして使用する定数。
lAlphaSrcConstBitDepth
転送元のアルファ定数を指定するために使用されるビット深度。
lDDFX
CONST_DDOVERFXFLAGS 列挙の定数の 1 つ。
lFlags
現在使用されていないので、0 に設定する。


DDPIXELFORMAT

DDPIXELFORMAT 型は、DirectDrawSurface7.GetPixelFormat メソッドに対する DirectDrawSurface オブジェクトのピクセル フォーマットを記述する。

Type DDPIXELFORMAT
    lAlphaBitDepth As Long
    lBBitMask As Long
    lBumpBitCount As Long
    lBumpDuBitMask As Long
    lBumpDvBitMask As Long
    lBumpLuminanceBitMask As Long
    lFlags As CONST_DDPIXELFORMATFLAGS
    lFourCC As Long
    lGBitMask As Long
    lLuminanceAlphaBitMask As Long
    lLuminanceBitCount As Long
    lLuminanceBitMask As Long
    lRBitMask As Long
    lRGBAlphaBitMask As Long
    lRGBBitCount As Long
    lRGBZBitMask As Long
    lStencilBitDepth As Long
    lStencilBitMask As Long
    lUBitMask As Long
    lVBitMask As Long
    lYBitMask As Long
    lYUVAlphaBitMask As Long
    lYUVBitCount As Long
    lYUVZBitMask As Long
    lZBitMask As Long
    lZBufferBitDepth As Long
End Type

メンバ

lAlphaBitDepth
アルファ専用サーフェス (DDPF_ALPHA) のためのアルファ チャネル ビット深度 (1、2、4、または 8)。アルファ情報を含むピクセル フォーマットは色データ (DDPF_ALPHAPIXELS) でインターリーブされるため、lRGBAlphaBitMask メンバのビットを数え、アルファ成分のビット深度を取得しなくてはならない。
lBBitMask
青ビットのマスク。
lBumpBitCount
バンプマップ サーフェスの総バンプマップ ビット/ピクセル。
lBumpDuBitMask
バンプマップ U デルタ ビットのマスク、
lBumpDvBitMask
バンプマップ V デルタ ビットのマスク。
lBumpLuminanceBitMask
バンプマップ ピクセルの輝度のマスク。
lFlags
オプション制御フラグを記述する CONST_DDPIXELFORMATFLAGS 列挙の定数。
lFourCC
FOURCC コード。詳細については、「4 文字コード (FOURCC)」を参照すること。
lGBitMask
緑ビットのマスク。
lRGBAlphaBitMask、lYUVAlphaBitMask、lLuminanceAlphaBitMask
アルファ チャネルのマスク。
lLuminanceBitCount
総輝度ビット/ピクセル。このメンバは、輝度専用および輝度アルファ サーフェスだけに適用する。
lLuminanceBitMask
輝度ビットのマスク。
lRBitMask
赤ビットのマスク。
lRGBAlphaBitMask、lYUVAlphaBitMask
アルファ チャネルのマスク。
lRGBBitCount
RGB ビット/ピクセル (4、8、16、24、または 32)。
lRGBZBitMask、lYUVZBitMask
z チャネルのマスク。
lStencilBitDepth
ステンシル バッファのビット深度。このメンバは、ステンシル情報の Z バッファの各ピクセル内で確保されるビットの数を指定する。(z ビットの総数は lZBufferBitDepth から lStencilBitDepth を引いた数と等しい)。
lStencilBitMask
各 Z バッファ ピクセル内のステンシルビットのマスク。
lUBitMask
U ビットのマスク。
lVBitMask
V ビットのマスク。
lYBitMask
Y ビットのマスク。
lYUVBitCount
YUV ビット/ピクセル (4、8、16、24、または 32)。
lZBitMask
z ビットのマスク。
lZBufferBitDepth
Z バッファのビット深度 (8、16、または 24)。32 ビット バッファはサポートされていない。


DDSCAPS2

DDSCAPS2 型は、DirectDrawSurface オブジェクトの能力を定義する。この型は、DDSURFACEDESC2 型の一部である。

Type DDSCAPS2
   lCaps As CONST_DDSURFACECAPSFLAGS
   lCaps2 As CONST_DDSURFACECAPS2FLAGS
   lCaps3 As Long
   lCaps4 As Long
End Type

メンバ

lCaps
サーフェスの能力を表す CONST_DDSURFACECAPSFLAGS 列挙の 1 つまたは複数の定数。
lCaps2
追加サーフェス能力。このメンバは、CONST_DDSURFACECAPS2FLAGS 列挙の能力定数を 1 つ以上含むことができる。また、追加フラグによってサーフェス メモリの割り当て方法を示すことができる。
lCaps3 および lCaps4
現時点では、未使用である。


DDSURFACEDESC2

DDSURFACEDESC2 型は、サーフェスの記述を含む。この型は、DirectDraw7.CreateSurface メソッドに渡される。関係するメンバは、サーフェスの個々のタイプにより異なる。

Type DDSURFACEDESC2
    ddckCKDestBlt As DDCOLORKEY
    ddckCKDestOverlay As DDCOLORKEY
    ddckCKSrcBlt As DDCOLORKEY
    ddckCKSrcOverlay As DDCOLORKEY
    ddpfPixelFormat As DDPIXELFORMAT
    ddsCaps As DDSCAPS2
    lAlphaBitDepth As Long
    lBackBufferCount As Long
    lFlags As CONST_DDSURFACEDESCFLAGS
    lHeight As Long
    lLinearSize As Long
    lMipMapCount As Long
    lPitch As Long
    lRefreshRate As Long
    lTextureStage As Long
    lWidth As Long
    lZBufferBitDepth As Long
End Type

メンバ

ddckCKDestBlt
ブリット処理の転送先カラー キーを記述する DDCOLORKEY 型。
ddckCKDestOverlay
オーバーレイ サーフェスに使用する転送先カラー キーを記述する DDCOLORKEY 型。
ddckCKSrcBlt
ブリット処理の転送元カラー キーを記述する DDCOLORKEY 型。
ddckCKSrcOverlay
オーバーレイ サーフェスに使用する転送元カラー キーを記述する DDCOLORKEY 型。
ddpfPixelFormat
サーフェスのピクセル フォーマットを記述する DDPIXELFORMAT 型。
ddsCaps
サーフェスの能力を含む DDSCAPS2 型。
lAlphaBitDepth
アルファ バッファの深度。
lBackBufferCount
バック バッファの数。
lFlags
オプション制御フラグ。CONST_DDSURFACEDESCFLAGS 列挙の 1 つまたは複数の定数。
lHeight および lWidth
ピクセル単位で作成しようとするサーフェスのディメンジョン。
lLinearSize
現時点では、未使用である。
lMipMapCount
ミップマップレベルの数。
lPitch
次のラインの開始までのバイト単位の距離。DirectDrawSurface7.GetSurfaceDesc メソッドで使用すると戻り値になる。既存のメモリからサーフェスを作成する場合、このメンバは入力値になり、複数でなければならない。
lRefreshRate
リフレッシュ レート (ディスプレイ モードを記述する場合に使用)。この値が 0 の場合、アダプタ障害を示す。
lTextureStage
3D デバイスのマルチテクスチャ カスケードにおける特定のステージに、テクスチャをバインドするために使用するステージ識別子。すべてのハードウェアに必要ではないが、このメンバの設定は 3D アクセラレータの多様性に対して、最適なパフォーマンスを与える。明示的に割り当てられたテクスチャを要求するハードウェアが、Direct3DDevice7.GetCaps メソッドで満たされる D3DDEVICEDESC 型の D3DDEVCAPS_SEPARATETEXTUREMEMORIES 3-D デバイス能力を示す。
lZBufferBitDepth
Z バッファの深度。32 ビット Z バッファはサポートされていない。

注意

DirectDrawSurface7.GetSurfaceDesc メソッドを呼び出すと、lPitch メンバが出力値になる。既存のメモリからサーフェスを作成したり、サーフェス特性を更新している場合、これらのメンバは入力値となる。この入力値は、DirectDraw で使用される呼び出し側のアプリケーションにより割り当てられたメモリのピッチと位置を記述する。DirectDraw は、アプリケーションが割り当てたメモリを管理したり解放しようとしない。詳細については、「クライアント メモリ サーフェスの作成」、および「サーフェス特性の更新」を参照すること。


PALETTEENTRY

PALETTEENTRY 型は、論理色パレット エントリの色と使用方法を指定する。

Type PALETTEENTRY
    blue As Byte
    flags As Byte
    green As Byte
    red As Byte
End Type

メンバ

blue
パレット エントリの青の強度。
flags
パレット エントリの使用方法を指定する。flags メンバは、Nothing または以下のいずれかの値に設定できる。
値 | 意味
PC_EXPLICIT | ハードウェア パレット インデックスを示す論理パレット エントリの下位ワード。このフラグによって、アプリケーションはディスプレイ デバイス パレットのコンテンツを表示できる。
PC_NOCOLLAPSE | システム パレットの既存の色に適合せずに、未使用のエントリに割り当てる色。システム パレットに未使用のエントリがない場合、通常どおりに適合される。システム パレットに割り当てられた色は、ほかの論理パレットの色と適合できる。
PC_RESERVED | パレット アニメーションに使用される論理パレット エントリ。色が頻繁に変化するので、このフラグによって、ほかのウィンドウがそのパレット エントリに色を適合しないようにする。未使用のシステム パレット エントリが使用可能な場合、そのエントリに色が割り当てられる。そうでない場合、その色はアニメーションで使用できない。

green
パレット エントリの緑の強度。
red
パレット エントリの赤の強度。


RECT

RECT 型は、矩形の左上と右下の角の座標を定義する。

Type RECT
    Bottom As Long
    Left As Long
    Right As Long
    Top As Long
End Type

メンバ

Bottom
矩形の右下角の ｙ 座標。
Left
矩形の左上角の ｘ 座標。
Right
矩形の右下角の ｘ 座標。
Top
矩形の左上角の ｙ 座標。


列挙

DirectDraw では、列挙を使用して定数をグループ化し、Visual Basic のステートメント完了機能を利用する。DirectDraw では次の列挙を使用する。

  • CONST_DDBITDEPTHFLAGS
  • CONST_DDBLTFASTFLAGS
  • CONST_DDBLTFLAGS
  • CONST_DDBLTFXFLAGS
  • CONST_DDCAPS1FLAGS
  • CONST_DDCAPS2FLAGS
  • CONST_DDCKEYCAPSFLAGS
  • CONST_DDCKEYFLAGS
  • CONST_DDCOLORFLAGS
  • CONST_DDDEVICEIDFLAGS
  • CONST_DDEDMFLAGS
  • CONST_DDENUMOVERLAYZFLAGS
  • CONST_DDENUMSURFACESFLAGS
  • CONST_DDFLIPFLAGS
  • CONST_DDFXCAPSFLAGS
  • CONST_DDGBSFLAGS
  • CONST_DDGFSFLAGS
  • CONST_DDLOCKFLAGS
  • CONST_DDOVERFLAGS
  • CONST_DDOVERFXFLAGS
  • CONST_DDOVERZFLAGS
  • CONST_DDPALFLAGS
  • CONST_DDPCAPSFLAGS
  • CONST_DDPIXELFORMATFLAGS
  • CONST_DDRAW
  • CONST_DDRAWERR
  • CONST_DDSCLFLAGS
  • CONST_DDSDMFLAGS
  • CONST_DDSGRFLAGS
  • CONST_DDSTEREOCAPSFLAGS
  • CONST_DDSURFACECAPS2FLAGS
  • CONST_DDSURFACECAPSFLAGS
  • CONST_DDSURFACEDESCFLAGS
  • CONST_DDWAITVBFLAGS


CONST_DDBITDEPTHFLAGS

CONST_DDBITDEPTHFLAGS 列挙を使って、ビット深度を指定する。

Enum CONST_DDBITDEPTHFLAGS
    DDBD_1 = 16384
    DDBD_16 = 1024
    DDBD_2  = 8192
    DDBD_24 =  512
    DDBD_32 =  256
    DDBD_4  = 4096
    DDBD_8  = 2048
End Enum
DDBD_1 to 32
ビット/ピクセル


CONST_DDBLTFASTFLAGS

CONST_DDBLTFASTFLAGS 列挙は、DirectDrawSurface7.BltFast メソッドの trans パラメータで使用され、転送のタイプを定義する。

Enum CONST_DDBLTFASTFLAGS
    DDBLTFAST_DESTCOLORKEY =  2
    DDBLTFAST_DONOTWAIT    = 32
    DDBLTFAST_NOCOLORKEY   =  0
    DDBLTFAST_SRCCOLORKEY  =  1
    DDBLTFAST_WAIT         = 16
End Enum
DDBLTFAST_DESTCOLORKEY
転送先のカラー キーを使用する透過型ブリットを指定する。
DDBLTFAST_DONOTWAIT
ブリットがビジーの場合待機せず、ブリットを行わずに返す。
DDBLTFAST_NOCOLORKEY
透過型ではない通常のコピー ブリットを指定する。
DDBLTFAST_SRCCOLORKEY
転送元のカラー キーを使用する透過型ブリットを指定する。
DDBLTFAST_WAIT
ブリットがビジーの場合、DDERR_WASSTILLDRAWING メッセージを返さずに待機する。ブリットがセット アップされるか、あるいは別のエラーが発生すると即座に返す。


CONST_DDBLTFLAGS

CONST_DDBLTFLAGS 列挙は、DirectDrawSurface7.Blt および DirectDrawSurface7.BltFx メソッドの flag パラメータで使用され、関連付けられた DDBLTFX 型の有効なメンバを定義する。DDBLTFX 型は、カラー キー情報を指定するか、メソッドに特殊な動作を要求する。

Enum CONST_DDBLTFLAGS
    DDBLT_ASYNC = 512
    DDBLT_COLORFILL = 1024
    DDBLT_DDFX = 2048
    DDBLT_DDROPS = 4096
    DDBLT_DEPTHFILL = 33554432
    DDBLT_DONOTWAIT = 134217728
    DDBLT_KEYDEST = 8192
    DDBLT_KEYDESTOVERRIDE = 16384
    DDBLT_KEYSRC = 32768
    DDBLT_KEYSRCOVERRIDE = 65536
    DDBLT_ROP = 131072
    DDBLT_ROTATIONANGLE = 262144
    DDBLT_WAIT = 16777216
End Enum
評価フラグ
DDBLT_COLORFILL
転送先サーフェス上の転送先矩形を格納する RGB 色として DDBLTFX 型の lFill メンバを使用する。
DDBLT_DDFX
このブリットに対して使用するエフェクトを指定する、DDBLTFX 型の lDDFX メンバを使用する。
DDBLT_DDROPS
Win32 API の部分ではないラスタ処理 (ROPS) を指定する、DDBLTFX 型の lROP メンバを使用する。
DDBLT_DEPTHFILL
転送先 Z バッファ サーフェス上の転送先矩形を格納する深度値として、DDBLTFX 型の lFilll メンバを使用する。
DDBLT_DONOTWAIT
ブリットがビジーの場合、ブリットが可能になるまで待機せず、ブリットを行わずに返す。
DDBLT_KEYDESTOVERRIDE
転送先サーフェスのカラー キーとして DDBLTFX 型の ddckDestColorkey_high および ddckDestColorkey_low メンバを使用する。
DDBLT_KEYSRCOVERRIDE
転送元サーフェスのカラー キーとして DDBLTFX 型の ddckSrcColorkey_high および ddckSrcColorkey_low メンバを使用する。
DDBLT_ROP
このブリットにおける ROP に対して DDBLTFX 型の lROP メンバを使用する。これらの ROP は、Win32 API で定義されているものと同じである。
DDBLT_ROTATIONANGLE
サーフェスの回転角 (1/100 度単位で指定される) として DDBLTFX 型の lRotationAngle メンバを使用する。
カラー キー フラグ
DDBLT_KEYDEST
転送先サーフェスに関連付けられたカラー キーを使用する。
DDBLT_KEYSRC
転送元サーフェスに関連付けられたカラー キーを使用する。
動作フラグ
DDBLT_ASYNC
受け取る順で FIFO (ファースト イン、ファースト アウト) ハードウェアから非同期にこのブリットを実行する。FIFO ハードウェアの空き領域を利用できない場合、呼び出しは失敗する。
DDBLT_WAIT
ブリットがビジーの場合、DDERR_WASSTILLDRAWING 戻り値をすぐに返さずに待機する。そして、ブリットがセット アップされるか、別のエラーが発生したら即座に返す。


CONST_DDBLTFXFLAGS

CONST_DDBLTFXFLAGS 列挙は、DDBLTFX 型の lDDFX メンバで使用され、ＦＸ 処理のタイプを指定する。

Enum CONST_DDBLTFXFLAGS
    DDBLTFX_ARITHSTRETCHY   =   1
    DDBLTFX_MIRRORLEFTRIGHT =   2
    DDBLTFX_MIRRORUPDOWN    =   4
    DDBLTFX_NOTEARING       =   8
    DDBLTFX_ROTATE180       =  16
    DDBLTFX_ROTATE270       =  32
    DDBLTFX_ROTATE90        =  64
    DDBLTFX_ZBUFFERBASEDEST = 256
    DDBLTFX_ZBUFFERRANGE    = 128
End Enum
DDBLTFX_ARITHSTRETCHY
このブリットに対して、y 軸に沿って算術伸縮を使用する。
DDBLTFX_MIRRORLEFTRIGHT
y 軸上でサーフェスを回転する。このブリットは、サーフェスを左から右にミラー化する。
DDBLTFX_MIRRORUPDOWN
x 軸上でサーフェスを回転する。このブリットは、サーフェスを上から下にミラー化する。
DDBLTFX_NOTEARING
このブリットがテアリングしないように考慮する。
DDBLTFX_ROTATE180
このブリット中に、サーフェスを時計回りに 180 度回転する。
DDBLTFX_ROTATE270
このブリット中に、サーフェスを時計回りに 270 度回転する。
DDBLTFX_ROTATE90
このブリット中に、サーフェスを時計回りに 90 度回転する。
DDBLTFX_ZBUFFERBASEDEST
この z ブリット中に、転送先 z 値と比較する前の転送元 z 値のおのおのに DDBLTFX 型の lZBufferBaseDest メンバを追加する。
DDBLTFX_ZBUFFERRANGE
この z ブリット中に、転送元サーフェスからコピーしたビットへの限界を指定する範囲値として DDBLTFX 型の ｌZBufferLow および ｌZBufferHigh メンバを使用する。


CONST_DDCAPS1FLAGS

CONST_DDCAPS1FLAGS 列挙は、DDCAPS 型の lCaps、lNLVBCaps、lSSBCaps、lSVBCaps、および lVSBCaps メンバで使用され、ハードウェア能力を記述する。

Enum CONST_DDCAPS1FLAGS
    DDCAPS_3D               =           1
    DDCAPS_ALIGNBOUNDARYDEST =          2
    DDCAPS_ALIGNBOUNDARYSRC =           8
    DDCAPS_ALIGNSIZEDEST    =           4
    DDCAPS_ALIGNSIZESRC     =          16
    DDCAPS_ALIGNSTRIDE      =          32
    DDCAPS_ALPHA            =     8388608
    DDCAPS_BANKSWITCHED     =   134217728
    DDCAPS_BLT              =          64
    DDCAPS_BLTCOLORFILL     =    67108864
    DDCAPS_BLTDEPTHFILL     =   268435456
    DDCAPS_BLTFOURCC        =         256
    DDCAPS_BLTQUEUE         =         128
    DDCAPS_BLTSTRETCH       =         512
    DDCAPS_CANBLTSYSMEM     = -2147483648
    DDCAPS_CANCLIP          =   536870912
    DDCAPS_CANCLIPSTRETCHED =  1073741824
    DDCAPS_COLORKEY         =     4194304
    DDCAPS_COLORKEYHWASSIST =    16777216
    DDCAPS_GDI              =        1024
    DDCAPS_NOHARDWARE       =    33554432
    DDCAPS_OVERLAY          =        2048
    DDCAPS_OVERLAYCANTCLIP  =        4096
    DDCAPS_OVERLAYFOURCC    =        8192
    DDCAPS_OVERLAYSTRETCH   =       16384
    DDCAPS_PALETTE          =       32768
    DDCAPS_PALETTEVSYNC     =       65536
    DDCAPS_READSCANLINE     =      131072
    DDCAPS_VBI              =      524288
    DDCAPS_ZBLTS            =     1048576
    DDCAPS_ZOVERLAYS        =     2097152
End Enum
DDCAPS_3D
ディスプレイ ハードウェアに 3D アクセラレータがあることを示す。
DDCAPS_ALIGNBOUNDARYDEST
DirectDraw が、サーフェスの lAlignBoundaryDest 境界に連続する x 軸のあるオーバーレイ転送先矩形だけをサポートすることを示す。
DDCAPS_ALIGNBOUNDARYSRC
DirectDraw が、サーフェスの lAlignBoundarySrc 境界に連続する x 軸のあるオーバーレイ転送元矩形だけをサポートすることを示す。
DDCAPS_ALIGNSIZEDEST
DirectDraw が、ピクセル単位の x 軸のサイズが lAlignSizeDest の倍数であるオーバーレイ転送先矩形だけをサポートすることを示す。
DDCAPS_ALIGNSIZESRC
DirectDraw が、ピクセル単位の x 軸のサイズが lAlignSizeSrc の倍数であるオーバーレイ転送元矩形だけをサポートすることを示す。
DDCAPS_ALIGNSTRIDE
DirectDraw が、lAlignStrideAlign 値に等しいストライド境界のあるディスプレイ メモリ サーフェスを作成することを示す。
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
オーバーレイまたはブリット処理のどちらかで、カラー キーのいくつかの形式をサポートする。より特定なカラー キー能力情報は、lCKeyCaps メンバにある。
DDCAPS_COLORKEYHWASSIST
カラー キーが、部分的にハードウェアでサポートされていることを示す。このため、ほかのリソース (CPU またはビデオ メモリ) を使用する可能性がある。このビットが設定されていない場合、ハードウェアのフル サポートが実施される。
DDCAPS_GDI
ディスプレイ ハードウェアが、ＧＤＩ で共有されることを示す。
DDCAPS_NOHARDWARE
ハードウェア サポートのないことを示す。
DDCAPS_OVERLAY
ディスプレイ ハードウェアが、オーバーレイをサポートすることを示す。
DDCAPS_OVERLAYCANTCLIP
ディスプレイ ハードウェアがオーバーレイをサポートするが、クリップできないことを示す。
DDCAPS_OVERLAYFOURCC
オーバーレイ ハードウェアが、オーバーレイ処理中に色空間の変更できることを示す。
DDCAPS_OVERLAYSTRETCH
オーバーレイ ハードウェアが、伸縮できることを示す。lMinOverlayStretch および lMaxOverlayStretch メンバに有効なデータがある。
DDCAPS_PALETTE
DirectDraw が、プライマリ サーフェスだけでなくほかのサーフェスにも、DirectDrawPalette オブジェクトを作成し、サポートできることを示す。
DDCAPS_PALETTEVSYNC
DirectDraw が、垂直リフレッシュと同期するパレットを更新できることを示す。
DDCAPS_READSCANLINE
ディスプレイ ハードウェアが、現在の走査線を返せることを示す。
DDCAPS_VBI
ディスプレイ ハードウェアが、垂直帰線消去割り込みを生成できることを示す。
DDCAPS_ZBLTS
ブリット処理と共に Z バッファの使用をサポートする。
DDCAPS_ZOVERLAYS
重なりを制御するオーバーレイの ｚ 値として、DirectDrawSurface7.UpdateOverlayZOrder メソッドの使用をサポートする。


CONST_DDCAPS2FLAGS

CONST_DDCAPS2FLAGS 列挙は、DDCAPS 型の lCaps2、lNLVBCaps2、lSVBCaps2 メンバで使用され、追加のドライバ固有能力を記述する。

Enum CONST_DDCAPS2FLAGS
    DDCAPS2_AUTOFLIPOVERLAY    =     8
    DDCAPS2_CANBOBHARDWARE     = 16384
    DDCAPS2_CANBOBINTERLEAVED  =    16
    DDCAPS2_CANBOBNONINTERLEAVED =  32
    DDCAPS2_CANCALIBRATEGAMMA  = 1048576
    DDCAPS2_CANDROPZ16BIT      =   256
    DDCAPS2_CANFLIPODDEVEN     =  8192
    DDCAPS2_CANMANAGETEXTURE   = 8388608
    DDCAPS2_CANRENDERWINDOWED  = 524288
    DDCAPS2_CERTIFIED          =     1
    DDCAPS2_COLORCONTROLOVERLAY =   64
    DDCAPS2_COLORCONTROLPRIMARY =  128
    DDCAPS2_COPYFOURCC         = 32768
    DDCAPS2_FLIPINTERVAL       = 2097152
    DDCAPS2_FLIPNOVSYNC        = 4194304
    DDCAPS2_NO2DDURING3DSCENE  =     2
    DDCAPS2_NONLOCALVIDMEM     =   512
    DDCAPS2_NONLOCALVIDMEMCAPS =  1024
    DDCAPS2_NOPAGELOCKREQUIRED =  2048
    DDCAPS2_PRIMARYGAMMA       = 131072
    DDCAPS2_STEREO             = 33554432
    DDCAPS2_VIDEOPORT          =     4
    DDCAPS2_WIDESURFACES       =  4096
End Enum
DDCAPS2_AUTOFLIPOVERLAY
オーバーレイは、ビデオ ポート VSYNC が発生するたびに、フリップ チェーンの次のサーフェスに自動的にフリップされる。また、CPU のオーバーヘッドなしに、ビデオ ポートおよびオーバーレイからビデオをダブルバッファできる。このオプションは、サーフェスがビデオ ポートからデータを受け取るときだけに有効である。ビデオ ポート データがインターレイスまたはインターリーブされていない場合は、VSYNC のたびにフリップする。データがメモリでインターリーブされている場合、1 つおきの VSYNC のたびにフリップする。
DDCAPS2_CANBOBHARDWARE
オーバーレイ ハードウェアは、インターレイス ビデオ ストリームの個々のフィールドを個別に表示できる。
DDCAPS2_CANBOBINTERLEAVED
オーバーレイ ハードウェアは、特別なハードウェア サポートがなければ、通常発生する可能性のある異常を引き起こすことなく、メモリでインターリーブしている間は、インターレイス ビデオ ストリームの個々のフィールドを個別に表示できる。このオプションは、サーフェスがビデオ ポートからデータを受け取るとき、またはビデオが垂直方向に少なくても 2倍ズームされるときだけに有効である。
DDCAPS2_CANBOBNONINTERLEAVED
オーバーレイ ハードウェアは、特別なハードウェア サポートがなければ、通常発生する可能性のある異常を引き起こすことなく、メモリでインターリーブしていない間は、インターレイス ビデオ ストリームの個々のフィールドを個別に表示できる。このオプションは、サーフェスがビデオ ポートからデータを受け取るとき、または、ビデオが垂直方向に少なくても 2倍ズームされるときだけに有効である。
DDCAPS2_CANCALIBRATEGAMMA
システムには、自動的にガンマ ランプを調節できるインストールされた口径測定器があるので、その結果は口径測定器のある全システム上で示される。新しいガンマ レベルを設定するときに口径測定器を含めるには、DirectDrawGammaControl.SetGammaRamp メソッドを呼び出すときに、DDSGR_CALIBRATE フラグを使用する。ガンマ ランプのキャリブレーションでは、いくつかの処理にオーバーヘッドが起こるので、頻繁に使用できない。
DDCAPS2_CANDROPZ16BIT
16 ビット RGBZ 値を 16 ビット RGB 値に変換できる (システムは、8 ビット変換をサポートしない)。
DDCAPS2_CANFLIPODDEVEN
ドライバは、DirectDrawSurface7.Flip メソッドと共に使用する DDFLIP_ODD および DDFLIP_EVEN フラグを指定して、奇数および偶数フリップ処理を実行できる。
DDCAPS2_CANMANAGETEXTURE
Microsoft® Direct3D® テクスチャ マネージャは、このフラグを使って、管理されるサーフェスを非ローカル ビデオ メモリに入れるかどうかを決める。このフラグが設定されている場合、テクスチャ マネージャは管理されるサーフェスを非ローカル ビデオ メモリに入れる。非ローカル ビデオ メモリからのテクスチャリングが不可能なドライバでは、このフラグを設定しない。
DDCAPS2_CANRENDERWINDOWED
ドライバは、ウィンドウ モードのレンダリングができる。
DDCAPS2_CERTIFIED
ディスプレイ ハードウェアが保証されていることを示す。
DDCAPS2_COLORCONTROLOVERLAY
オーバーレイ サーフェスに、カラー コントロール (輝度、鮮明度など) を含む。
DDCAPS2_COLORCONTROLPRIMARY
プライマリ サーフェスに、カラー コントロール (たとえば、ガンマ) を含む。
DDCAPS2_COPYFOURCC
ドライバが、同じ FOURCC の別のサーフェスに対して、FOURCC サーフェスのブリットをサポートすることを示す。
DDCAPS2_FLIPINTERVAL
ドライバが DDFLIP_INTERVAL* フラグに応答することを示す (「DirectDrawSurface7.Flip」参照)。
DDCAPS2_FLIPNOVSYNC
ドライバが DDFLIP_NOVSYNC フラグに応答することを示す (「DirectDrawSurface7.Flip」参照)。
DDCAPS2_NO2DDURING3DSCENE
Direct3DDevice7.BeginScene メソッドを呼び出してから Direct3DDevice7.EndScene メソッドを呼び出すまでの間に Direct3D が使用するすべてのサーフェス上で、DirectDrawSurface7.Blt および DirectDrawSurface7.Lock のような 2D 処理を実行できないことを示す。
DDCAPS2_NONLOCALVIDMEM
ディスプレイ ドライバが、非ローカル ビデオ メモリのサーフェスをサポートすることを示す。
DDCAPS2_NONLOCALVIDMEMCAPS
非ローカル ビデオ メモリ サーフェスのブリット能力が、ローカル ビデオ メモリ サーフェスの場合と異なることを示す。このフラグが存在する場合、DDCAPS2_NONLOCALVIDMEM フラグも存在する。
DDCAPS2_NOPAGELOCKREQUIRED
ページロックされていないシステム メモリ サーフェスが、DMA ブリット処理をサポートする。
DDCAPS2_PRIMARYGAMMA
プライマリ サーフェスに対するダイナミック ガンマ ランプをサポートする。詳細については、「ガンマ コントロールとカラー コントロール」を参照すること。
DDCAPS2_STEREO
DirectX 7.0 の新機能。ステレオ モードをサポートするには、ddcaps.dwSVCaps ビットをオンにする。ドライバは、現在のモード以外の少なくとも 1 つのモードでステレオ ビューを実現できる。アプリケーションは、DirectDraw7.GetDisplayMode または DirectDraw7.GetDisplayModesEnum を使って、モードごとのステレオ情報を取得できる。
DDCAPS2_VIDEOPORT
ディスプレイ ハードウェアが、ライブ ビデオをサポートすることを示す。
DDCAPS2_WIDESURFACES
ディスプレイ サーフェスが、プライマリ サーフェスよりも広いサーフェスをサポートすることを示す。


CONST_DDCKEYCAPSFLAGS

CONST_DDCKEYCAPSFLAGS 列挙は、DDCAPS 型の lCKeyCaps、lNLVBCKeyCaps、lSSBCKeyCaps、lSVBCKeyCaps、および lVSBCKeyCaps メンバで使用され、ハードウェアのカラー キー能力を記述する。

Enum CONST_DDCKEYCAPSFLAGS
    DDCKEYCAPS_DESTBLT               =      1
    DDCKEYCAPS_DESTBLTCLRSPACE       =      2
    DDCKEYCAPS_DESTBLTCLRSPACEYUV    =      4
    DDCKEYCAPS_DESTBLTYUV            =      8
    DDCKEYCAPS_DESTOVERLAY           =     16
    DDCKEYCAPS_DESTOVERLAYCLRSPACE   =     32
    DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV =    64
    DDCKEYCAPS_DESTOVERLAYONEACTIVE  =    128
    DDCKEYCAPS_DESTOVERLAYYUV        =    256
    DDCKEYCAPS_NOCOSTOVERLAY         = 262144
    DDCKEYCAPS_SRCBLT                =    512
    DDCKEYCAPS_SRCBLTCLRSPACE        =   1024
    DDCKEYCAPS_SRCBLTCLRSPACEYUV     =   2048
    DDCKEYCAPS_SRCBLTYUV             =   4096
    DDCKEYCAPS_SRCOVERLAY            =   8192
    DDCKEYCAPS_SRCOVERLAYCLRSPACE    =  16384
    DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV =  32768
    DDCKEYCAPS_SRCOVERLAYONEACTIVE   =  65536
    DDCKEYCAPS_SRCOVERLAYYUV         = 131072
End Enum
DDCKEYCAPS_DESTBLT
カラー キーによる透過型ブリットをサポートする。カラー キーは、RGB 色の転送先サーフェスの置換可能なビットを識別する。
DDCKEYCAPS_DESTBLTCLRSPACE
色空間による透過型ブリットをサポートする。色空間は、RGB 色の転送先サーフェスの置換可能なビットを識別する。
DDCKEYCAPS_DESTBLTCLRSPACEYUV
色空間による透過型ブリットをサポートする。色空間は、YUV 色の転送先サーフェスの置換可能なビットを識別する。
DDCKEYCAPS_DESTBLTYUV
カラー キーによる透過型ブリットをサポートする。カラー キーは、YUV 色の転送先サーフェスの置換可能なビットを識別する。
DDCKEYCAPS_DESTOVERLAY
カラー キーイングによるオーバーレイをサポートする。カラー キーイングは、RGB 色でオーバーレイされる転送先サーフェスの置換可能なビットである。
DDCKEYCAPS_DESTOVERLAYCLRSPACE
RGB 色の転送先におけるカラー キーとして、色空間をサポートする。
DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV
YUV 色の転送先におけるカラー キーとして、色空間をサポートする。
DDCKEYCAPS_DESTOVERLAYONEACTIVE
表示されるオーバーレイ サーフェスに対して、1 つのアクティブ転送先カラー キー値だけをサポートする。
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
表示されるオーバーレイ サーフェスに対して、1 つのアクティブ転送元カラー キー値だけをサポートする。
DDCKEYCAPS_SRCOVERLAYYUV
YUV 色のオーバーレイ サーフェスで転送元のカラー キーを使用して、オーバーレイをサポートする。


CONST_DDCKEYFLAGS

CONST_DDCKEYFLAGS 列挙は、DirectDrawSurface7.SetColorKey メソッドの flags フラグで使用され、要求されたカラー キーのタイプを指定する。

Enum CONST_DDCKEYFLAGS
    DDCKEY_COLORSPACE =  1
    DDCKEY_DESTBLT    =  2
    DDCKEY_DESTOVERLAY = 4
    DDCKEY_SRCBLT     =  8
    DDCKEY_SRCOVERLAY = 16
End Enum
DDCKEY_COLORSPACE
色空間。型に単一のカラー キーがある場合は設定しない。
DDCKEY_DESTBLT
ブリット処理の転送先カラー キーとして使用されるカラー キーや色空間。
DDCKEY_DESTOVERLAY
オーバーレイ処理の転送先カラー キーとして使用されるカラー キーや色空間。
DDCKEY_SRCBLT
ブリット処理の転送元カラー キーとして使用されるカラー キーや色空間。
DDCKEY_SRCOVERLAY
オーバーレイ処理の転送元カラー キーとして使用されるカラー キーや色空間。


CONST_DDCOLORFLAGS

CONST_DDCOLORFLAGS 列挙は、DDCOLORCONTROL 型の lFlags メンバで使用され、DDCOLORCONTROL 型のどのメンバが有効なデータを含むかを示す。

Enum CONST_DDCOLORFLAGS
    DDCOLOR_BRIGHTNESS  =  1
    DDCOLOR_COLORENABLE = 64
    DDCOLOR_CONTRAST    =  2
    DDCOLOR_GAMMA       = 32
    DDCOLOR_HUE         =  4
    DDCOLOR_SATURATION  =  8
    DDCOLOR_SHARPNESS   = 16
End Enum
DDCOLOR_BRIGHTNESS
IBrightness メンバが有効なデータを含む。
DDCOLOR_COLORENABLE
lColorEnable メンバが有効なデータを含む。
DDCOLOR_CONTRAST
IContrast メンバが有効なデータを含む。
DDCOLOR_GAMMA
IGamma メンバが有効なデータを含む。
DDCOLOR_HUE
IHue メンバが有効なデータを含む。
DDCOLOR_SATURATION
ISaturation メンバが有効なデータを含む。
DDCOLOR_SHARPNESS
ISharpness メンバが有効なデータを含む。


CONST_DDDEVICEIDFLAGS

CONST_DDDEVICEIDFLAGS 列挙は、DirectDraw7.GetDeviceIdentifier メソッドの flags パラメータで使用され、スタックされた第 2 の 3D アダプタと共に装備される、システムのホスト (通常は 2D) アダプタに関する情報を返す。

Enum CONST_DDDEVICEIDFLAGS
    DDGDI_DEFAULT           = 0
    DDGDI_GETHOSTIDENTIFIER = 1
End Enum
DDGDI_DEFAULT
ホスト アダプタの通常の列挙を実行する。
DDGDI_GETHOSTIDENTIFIER
スタックされた第 2 の 3D アダプタと共に装備される、システムのホスト (通常は 2D) アダプタについての情報を返すためにメソッドを引き起こす。このようなアダプタは、ホスト アダプタの一部であるが、別のカードに通常配置されているようにアプリケーションに現れる。dwFlags パラメータがゼロの場合、DirectDraw オブジェクトの質を最も正確に反映するために、ストックされた第 2 の情報が返される。


CONST_DDEDMFLAGS

CONST_DDEDMFLAGS 列挙は、DirectDraw7.GetDisplayModesEnum メソッドの flags パラメータで使用され、列挙のタイプを指定する。

Enum CONST_DDEDMFLAGS
    DDEDM_DEFAULT          = 0
    DDEDM_REFRESHRATES     = 1
    DDEDM_STANDARDVGAMODES = 2
End Enum
DDEDM_DEFAULT
ディスプレイ モードの通常の列挙を実行する。
DDEDM_REFRESHRATES
異なるリフレッシュ レートでモードを列挙する。特定のモードが 1 回だけ列挙されることを保証する。このフラグは、モードがユニークかどうかを決定するときに、リフレッシュ レートを考慮するかどうかを指定する。
DDEDM_STANDARDVGAMODES
320×200×8 モード X モード以外に、モード 13 を列挙する。


CONST_DDENUMOVERLAYZFLAGS

CONST_DDENUMOVERLAYZFLAGS 列挙は、DirectDrawSurface7.GetOverlayZOrdersEnum メソッドの flags パラメータで使用され、メソッドがオーバーレイの z オーダーを列挙する方法を制御する。

Enum CONST_DDENUMSURFACESFLAGS
    DDENUMOVERLAYZ_BACKTOFRONT = 0
    DDENUMOVERLAYZ_FRONTTOBACK = 1
End Enum
DDENUMOVERLAYZ_BACKTOFRONT
バックからフロントの順でオーバーレイを列挙する。
DDENUMOVERLAYZ_FRONTTOBACK
フロントからバックの順でオーバーレイを列挙する。


CONST_DDENUMSURFACESFLAGS

CONST_DDENUMSURFACESFLAGS 列挙は、DirectDraw7.GetSurfacesEnum メソッドが、アタッチされたサーフェスを列挙する方法を制御する。

Enum CONST_DDENUMSURFACESFLAGS
    DDENUMSURFACES_ALL          =  1
    DDENUMSURFACES_CANBECREATED =  8
    DDENUMSURFACES_DOESEXIST    = 16
    DDENUMSURFACES_MATCH        =  2
    DDENUMSURFACES_NOMATCH      =  4
End Enum
検索型フラグ
DDENUMSURFACES_CANBECREATED
作成可能で検索基準に合う最初のサーフェスを列挙する。このフラグは、DDENUMSURFACES_MATCH フラグと共に使用されるだけである。
DDENUMSURFACES_DOESEXIST
検索基準に合う既存のサーフェスを列挙する。
適合フラグ
DDENUMSURFACES_ALL
検索基準に合うサーフェスすべてを列挙する。このフラグは、DDENUMSURFACES_DOESEXIST 検索型フラグと共に使用されるだけである。
DDENUMSURFACES_MATCH
サーフェス記述に適合するサーフェスを検索する。
DDENUMSURFACES_NOMATCH
サーフェス記述に適合しないサーフェスを検索する。


CONST_DDFLIPFLAGS

CONST_DDFLIPFLAGS 列挙は、DirectDrawSurface7.Flip メソッドの flags パラメータで使用され、フリップ オプションを指定する。

Enum CONST_DDFLIPFLAGS
    DDFLIP_DONOTWAIT  =         32
    DDFLIP_EVEN       =          2
    DDFLIP_INTERFVAL2 =  536870912
    DDFLIP_INTERFVAL3 =  805306368
    DDFLIP_INTERFVAL4 = 1073741824
    DDFLIP_NOVSYNC    =          8
    DDFLIP_ODD        =          4
    DDFLIP_WAIT       =          1
    DDFLIP_STEREO     =         16
End Enum
DDFLIP_DONOTWAIT
デフォルトは DDFLIP_WAIT。デフォルト値をオーバーライドし、アクセラレータがビジーの間 (DDERR_WASSTILLDRAWING エラー値で示される) の時間を使いたい場合は、DDFLIP_DONOTWAIT を使用する。
DDFLIP_EVEN
オーバーレイ サーフェスでビデオを表示する場合に使用する。新しいサーフェスには、ビデオ信号の偶数フィールドからのデータが含まれる。このフラグは、DDFLIP_ODD フラグと共に使用することはできない。
DDFLIP_INTERFVAL2, DDFLIP_INTERFVAL3,
DDFLIP_INTERFVAL4
これらのフラグは、各フリップ間を待機する垂直リトレイス数を示す。デフォルト値は 1。DirectDraw では、指定した垂直リトレイス数になるまで、フリップ内の各サーフェスに DERR_WASSTILLDRAWING を返す。DDFLIP_INTERVAL2 が設定されると、DirectDraw は 2 番目の垂直同期ごとにフリップする。DDFLIP_INTERVAL3 では 3 番目の同期ごと、DDFLIP_INTERVAL4 では 4 番目の同期ごとにフリップする。

DDCAPS2_FLIPINTERVAL がデバイスに戻される DDCAPS 型に設定される場合にだけ、これらのフラグは効率的である。

DDFLIP_NOVSYNC
次の走査線にできる限り近い物理的なフリップを実行する DirectDraw を引き起こす。2 つのフリップされたサーフェスを含む次の処理では、物理的なフリップが終了したかどうかをチェックしない。つまり、この結果のために DDERR_WASSTILLDRAWING を返さない (ほかの結果では返す場合もある)。このため、アプリケーションではモニタのリフレッシュ レート以上の高周波数でフリップを実行できるが、目に見える異常が発生する場合もある。

DDCAPS2_FLIPNOVSYNC がデバイスに戻される DDCAPS 型に設定されていない場合、DDFLIP_NOVSYNC は非効率的である。

DDFLIP_ODD
オーバーレイ サーフェスでビデオを表示する場合に使用する。新しいフラグには、ビデオ信号の奇数フィールドからのデータが含まれる。このフラグは、DDFLIP_EVEN フラグと共に使用することはできない。
DDFLIP_STEREO
DirectDraw がメイン ステレオ サーフェスをフリップして表示する。このフラグを設定すると、ステレオ自動フリッピングが可能になる。ハードウェアは、スクリーンをリフレッシュするごとに、左と右のバッファの間で自動的にフリップする。
DDFLIP_WAIT
通常、ディスプレイ ハードウェアの状態が不適切なためにフリップをセット アップできない場合、DDERR_WASSTILLDRAWING エラーが即座に返り、フリップは起こらない。しかし、このフラグを設定すると、ハードウェア アブストラクション レイヤ (HAL) から DDERR_WASSTILLDRAWING エラーを受け取っても、メソッドはフリップしようとし続ける。この場合、メソッドはフリッピング処理が成功するか、DDERR_SURFACEBUSY のような別のエラーが返されるまで返さない。


CONST_DDFXCAPSFLAGS

CONST_DDFXCAPSFLAGS 列挙は、DDCAPS 型の lFXCaps、lNLVBFXCaps、lSSBFXCaps、lSVBFXCaps、および lVSBFXCaps メンバで使用され、伸縮およびエフェクト、非ローカル ビデオ メモリからローカル ビデオ メモリへのブリット、システム メモリからシステム メモリへのブリット、システム メモリからディスプレイ メモリへのブリット、およびディスプレイ メモリからシステム メモリへのブリットに対するドライバ固有の能力を記述する。

Enum CONST_DDFXCAPSFLAGS
    DDFXCAPS_BLTALPHA               =         1
    DDFXCAPS_BLTARITHSTRETCHY       =        32
    DDFXCAPS_BLTARITHSTRETCHYN      =        16
    DDFXCAPS_BLTFILTER              =        32
    DDFXCAPS_BLTMIRRORLEFTRIGHT     =        64
    DDFXCAPS_BLTMIRRORUPDOWN        =       128
    DDFXCAPS_BLTROTATION            =       256
    DDFXCAPS_BLTROTATION90          =       512
    DDFXCAPS_BLTSHRINKX             =      1024
    DDFXCAPS_BLTSHRINKXN            =      2048
    DDFXCAPS_BLTSHRINKY             =      4096
    DDFXCAPS_BLTSHRINKYN            =      8192
    DDFXCAPS_BLTSTRETCHX            =     16384
    DDFXCAPS_BLTSTRETCHXN           =     32768
    DDFXCAPS_BLTSTRETCHY            =     65536
    DDFXCAPS_BLTSTRETCHYN           =    131072
    DDFXCAPS_BLTTRANSFORM           =         2
    DDFXCAPS_OVERLAYALPHA           =         4
    DDFXCAPS_OVERLAYARITHSTRETCHY   =    262144
    DDFXCAPS_OVERLAYARITHSTRETCHYN  =         8
    DDFXCAPS_OVERLAYFILTER          =    262144
    DDFXCAPS_OVERLAYMIRRORLEFTRIGHT = 134217728
    DDFXCAPS_OVERLAYMIRRORUPDOWN    = 268435456
    DDFXCAPS_OVERLAYSHRINKX         =    524288
    DDFXCAPS_OVERLAYSHRINKXN        =   1048576
    DDFXCAPS_OVERLAYSHRINKY         =   2097152
    DDFXCAPS_OVERLAYSHRINKYN        =   4194304
    DDFXCAPS_OVERLAYSTRETCHX        =   8388608
    DDFXCAPS_OVERLAYSTRETCHXN       =  16777216
    DDFXCAPS_OVERLAYSTRETCHY        =  33554432
    DDFXCAPS_OVERLAYSTRETCHYN       =  67108864
    DDFXCAPS_OVERLAYTRANSFORM       = 536870912
End Enum
DDFXCAPS_BLTALPHA
アルファ ブレンディング ブリット処理をサポートする。
DDFXCAPS_BLTARITHSTRETCHY
ピクセルを 2 乗にして拡大する技術ではなく、ブリット処理中にサーフェスを拡大したり収縮する算術処理を使用する。これは、y 軸 (垂直) に沿って行われる。
DDFXCAPS_BLTARITHSTRETCHYN
ピクセルを 2 乗にして拡大する技術ではなく、ブリット処理中にサーフェスを拡大したり収縮する算術処理を使用する。これは、y 軸 (垂直) に沿って行われ、整数倍 (×1、×2 など) で伸縮するためだけに動作する。
DDFXCAPS_BLTFILTER
ドライバは、ラップされたブリットに対してフィルタリングするサーフェスの再構成を行える。
DDFXCAPS_BLTMIRRORLEFTRIGHT
ブリット処理で左右のミラーリングをサポートする。
DDFXCAPS_BLTMIRRORUPDOWN
ブリット処理で上下のミラーリングをサポートする。
DDFXCAPS_BLTROTATION
ブリット処理で任意の回転をサポートする。
DDFXCAPS_BLTROTATION90
ブリット処理で 90 度の回転をサポートする。
DDFXCAPS_BLTSHRINKX
x 軸 (水平) に沿ってサーフェスを任意に収縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSHRINKXN
x 軸 (水平) に沿ってサーフェスを整数倍 (×1、×2 など) に収縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSHRINKY
y 軸 (垂直) に沿ってサーフェスを任意に収縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSHRINKYN
y 軸 (垂直) に沿ってサーフェスを整数倍 (×1、×2 など) に収縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSTRETCHX
x 軸 (水平) に沿ってサーフェスを任意に伸縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSTRETCHXN
x 軸 (水平) に沿ってサーフェスを整数倍 (×1、×2 など) に伸縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSTRETCHY
y 軸 (垂直) に沿ってサーフェスを任意に伸縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTSTRETCHYN
y 軸 (垂直) に沿ってサーフェスを整数倍 (×1、×2 など) に伸縮することをサポートする。このフラグは、ブリット処理だけに有効である。
DDFXCAPS_BLTTRANSFORM
ブリットされるスプライトに対してジオメトリ トランスフォーム (または、ラップ) をサポートする。現時点では、トランスフォームはブリット処理でサポートされていない。
DDFXCAPS_OVERLAYALPHA
オーバーレイ サーフェスに対するアルファ ブレンディングをサポートする。
DDFXCAPS_OVERLAYARITHSTRETCHY
y 軸 (垂直) に沿ってサーフェスを任意に収縮することをサポートする。
DDFXCAPS_OVERLAYARITHSTRETCHYN
y 軸 (垂直) に沿ってサーフェスを整数倍 (×1、×2 など) に収縮することをサポートする。
DDFXCAPS_OVERLAYFILTER
ラップされたオーバーレイ スプライトに対してフィルタリングするサーフェスの再構成をサポートする。現時点では、フィルタリングは明示的に表示されるオーバーレイ サーフェス (DirectDrawSurface7.UpdateOverlay の呼び出しで表示される) でサポートされていない。
DDFXCAPS_OVERLAYMIRRORLEFTRIGHT
水平軸に沿ってオーバーレイのミラーリングをサポートする。
DDFXCAPS_OVERLAYMIRRORUPDOWN
水平軸に沿ってオーバーレイのミラーリングをサポートする。
DDFXCAPS_OVERLAYSHRINKX
x 軸 (水平) に沿ってサーフェスを任意に収縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、収縮が可能であることではない。
DDFXCAPS_OVERLAYSHRINKXN
x 軸 (水平) に沿ってサーフェスを整数倍 (×1、×2 など) に収縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、収縮が可能であることではない。
DDFXCAPS_OVERLAYSHRINKY
y 軸 (垂直) に沿ってサーフェスを任意に収縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、収縮が可能であることではない。
DDFXCAPS_OVERLAYSHRINKYN
y 軸 (垂直) に沿ってサーフェスを整数倍 (×1、×2 など) に収縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、収縮が可能であることではない。
DDFXCAPS_OVERLAYSTRETCHX
x 軸 (水平) に沿ってサーフェスを任意に伸縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、伸縮が可能であることではない。
DDFXCAPS_OVERLAYSTRETCHXN
x 軸 (水平) に沿ってサーフェスを整数倍 (×1、×2 など) に伸縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、伸縮が可能であることではない。
DDFXCAPS_OVERLAYSTRETCHY
y 軸 (垂直) に沿ってサーフェスを任意に伸縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、伸縮が可能であることではない。
DDFXCAPS_OVERLAYSTRETCHYN
y 軸 (垂直) に沿ってサーフェスを整数倍 (×1、×2 など) に伸縮することをサポートする。このフラグは、DDSCAPS_OVERLAY サーフェスだけに有効である。このフラグは、サーフェスの能力だけを示し、伸縮が可能であることではない。
DDFXCAPS_OVERLAYTRANSFORM
オーバーレイ スプライトに対してジオメトリ トランスフォーム (または、ラップ) をサポートする。現時点では、トランスフォームは明示的に表示されるオーバーレイ サーフェス (DirectDrawSurface7.UpdateOverlay の呼び出しで表示される) でサポートされていない。


CONST_DDGBSFLAGS

CONST_DDGBSFLAGS 列挙は、DirectDrawSurface7.GetBltStatus メソッドの flags パラメータで使用され、取得するステータスのタイプを指定する。

Enum CONST_DDGBSFLAGS
    DDGBS_CANBLT    = 1
    DDGBS_ISBLTDONE = 2
End Enum
DDGBS_CANBLT
このサーフェスを必要とするブリットがすぐに実行できるかどうかを問い合わせ、ブリットが完了すると DD_OK を返す。
DDGBS_ISBLTDONE
ブリットが実行されたかどうかを問い合わせ、このサーフェス上の最後のブリットが完了すると DD_OK を返す。


CONST_DDGFSFLAGS

CONST_DDGFSFLAGS 列挙は、DirectDrawSurface7.GetFlipStatus メソッドの flags パラメータで使用され、取得するフリップ ステータスのタイプを指定する。

Enum CONST_DDGFSFLAGS
    DDGFS_CANFLIP    = 1
    DDGFS_ISFLIPDONE = 2
End Enum
DDGFS_CANFLIP
このサーフェスを即座にフリップできるかどうかを問い合わせ、フリップが完了したら DD_OK を返す。
DDGFS_ISFLIPDONE
フリップが完了したかどうかを問い合わせ、このサーフェスの最後のフリップが完了したら DD_OK を返す。


CONST_DDLOCKFLAGS

CONST_DDLOCKFLAGS 列挙は、DirectDrawSurface7.Lock および Direct3DVertexBuffer7.Lock メソッドの flags パラメータで使用され、ロックの実行方法を示す。

Enum CONST_DDLOCKFLAGS
    DDLOCK_DONOTWAIT     = 16384
    DDLOCK_EVENT         =    2
    DDLOCK_NOSYSLOCK     = 2048
    DDLOCK_READONLY      =   16
    DDLOCK_SURFACEMEMORYPTR = 0
    DDLOCK_WAIT          =    1
    DDLOCK_WRITEONLY     =   32
End Enum
DDLOCK_DONOTWAIT
デフォルトは DDLOCK_WAIT。デフォルト値をオーバーライドし、アクセラレータがビジーの間 (DDERR_WASSTILLDRAWING エラー値で示される) の時間を使いたい場合は、DDFLIP_DONOTWAIT を使用する。
DDLOCK_EVENT
現時点では、実装されていない。
DDLOCK_NOSYSLOCK
Win16Mutex (Win16Lock と呼ばれる) を使用しない。プライマリ サーフェスをロックしているときは、このフラグは無視される。
DDLOCK_READONLY
ロックしているサーフェスが読み込み専用であることを示す。
DDLOCK_SURFACEMEMORYPTR
有効な矩形を返さなくてはならないことを示す。矩形が指定されていない場合、サーフェスを返す。このフラグはデフォルトである。
DDLOCK_WAIT
ブリット処理が処理中のためにロックを取得できない場合、ロックが取得されるまで、または DDERR_SURFACEBUSY のような別のエラーが発生するまで、メソッドは再試行する。
DDLOCK_WRITEONLY
ロックしているサーフェスが書き込み可能であることを示す。


CONST_DDOVERFLAGS

CONST_DDOVERFLAGS 列挙のフラグは、DirectDrawSurface7.UpdateOverlay メソッドの flags パラメータで使用され、オーバーレイのビジュアル属性を変更する。

Enum CONST_DDOVERFLAGS
    DDOVER_ADDDIRTYRECT             = 32768
    DDOVER_ALPHADEST                = 1
    DDOVER_ALPHADESTCONSTOVERRIDE   = 2
    DDOVER_ALPHADESTNEG             = 4
    DDOVER_ALPHADESTSURFACEOVERRIDE = 8
    DDOVER_ALPHAEDGEBLEND           = 16
    DDOVER_ALPHASRC                 = 32
    DDOVER_ALPHASRCCONSTOVERRIDE    = 64
    DDOVER_ALPHASRCNEG              = 128
    DDOVER_ALPHASRCSURFACEOVERRIDE  = 256
    DDOVER_ARGBSCALEFACTORS         = 33554432
    DDOVER_AUTOFLIP                 = 1048576
    DDOVER_BOB                      = 2097152
    DDOVER_DDFX                     = 524288
    DDOVER_DEGRADEARGBSCALING       = 67108864
    DDOVER_HIDE                     = 512
    DDOVER_INTERLEAVED              = 8388608
    DDOVER_KEYDEST                  = 1024
    DDOVER_KEYDESTOVERRIDE          = 2048
    DDOVER_KEYSRC                   = 4096
    DDOVER_KEYSRCOVERRIDE           = 8192
    DDOVER_OVERRIDEBOBWEAVE         = 4194304
    DDOVER_REFRESHALL               = 131072
    DDOVER_REFRESHDIRTYRECTS        = 65536
    DDOVER_SHOW                     = 16384
End Enum
DDOVER_ADDDIRTYRECT
エミュレートされたオーバーレイ サーフェスにダーティー矩形を追加する。
DDOVER_ALPHADEST
廃止された。
DDOVER_ALPHADESTCONSTOVERRIDE
このオーバーレイに対して転送先アルファ チャネルとして DDOVERLAYFX 型の lAlphaDestConst メンバを使用する。
DDOVER_ALPHADESTNEG
アルファ値の増加につれ、転送先サーフェスがより透過型となることを示す (0 は不透明)。
DDOVER_ALPHADESTSURFACEOVERRIDE
このオーバーレイに対して転送先アルファ チャネルとして DDOVERLAYFX 型の lpDDSAlphaDest メンバを使用する。
DDOVER_ALPHAEDGEBLEND
カラー キー色を境界とするイメージの縁に対するアルファ チャネルとして DDOVERLAYFX 型の lAlphaEdgeBlend メンバを使用する。
DDOVER_ALPHASRC
ピクセル フォーマットのアルファ情報か、このオーバーレイに対して転送元アルファ チャネルとして転送元サーフェスにアタッチされるアルファ チャネル サーフェスのどちらかを使用する。
DDOVER_ALPHASRCCONSTOVERRIDE
このオーバーレイに対して転送元アルファ チャネルとして DDOVERLAYFX 型の lAlphaSrcConst メンバを使用する。
DDOVER_ALPHASRCNEG
アルファ値の増加につれ、転送元サーフェスがより透過型になることを示す (0 は不透明)。
DDOVER_ALPHASRCSURFACEOVERRIDE
このオーバーレイに対して転送元アルファ チャネルとして DDOVERLAYFX 型の lpDDSAlphaSrc メンバを使用する。
DDOVER_ARGBSCALEFACTORS
DirectX 7.0 の新機能。オーバーレイ FX 型に有効なスケーリング係数が含まれる。
DDOVER_AUTOFLIP
ビデオ ポート VSYNC が発生するたびに、フリップ チェーンの次のサーフェスを自動的にフリップする。
DDOVER_BOB
インターレイス ビデオ ストリームの個々のフィールドを異常なく個別に表示する。
DDOVER_DDFX
DirectDrawSurface7.UpdateOverlayFx を呼び出すときに、ddoverfx パラメータのフラグ セットを使って特殊なオーバーレイ エフェクトを定義する。このフラグを設定しないと、ddoverfx パラメータが無視されるので、必ず設定する。
DDOVER_DEGRADEARGBSCALING
DirectX 7.0 の新機能。ドライバの能力に合わせて ARGB スケーリング係数を下げることができる。
DDOVER_HIDE
このオーバーレイをオフにする。
DDOVER_INTERLEAVED
サーフェス メモリが、インターリーブされたフィールドから成ることを示す。
DDOVER_KEYDEST
転送先サーフェスに関連付けられたカラー キーを使用する。
DDOVER_KEYDESTOVERRIDE
転送先サーフェスのカラー キーとして DDOVERLAYFX 型の dckColorkey メンバを使用する。
DDOVER_KEYSRC
転送元サーフェスに関連付けられたカラー キーを使用する。
DDOVER_KEYSRCOVERRIDE
転送元サーフェスのカラー キーとして DDOVERLAYFX 型の dckSrcColorkey メンバを使用する。
DDOVER_OVERRIDEBOBWEAVE
BOB/WEAVE 決定を、ほかのインターフェイスでオーバーライドしてはならないことを示す。
DDOVER_REFRESHALL
エミュレートされたオーバーレイ サーフェス上でサーフェス全体を再描画する。
DDOVER_REFRESHDIRTYRECTS
エミュレートされたオーバーレイ サーフェス上でダーティ矩形を再描画する。
DDOVER_SHOW
このオーバーレイをオンにする。


CONST_DDOVERFXFLAGS

CONST_DDOVERFXFLAGS 列挙のフラグは、DDOVERLAYFX 型の lDDFX メンバで使用され、オーバーレイの使用方法を指定する。

Enum CONST_DDPALFLAGS
    DDOVERFX_ARITHSTRETCHY   = 1
    DDOVERFX_MIRRORLEFTRIGHT = 2
    DDOVERFX_MIRRORUPDOWN    = 4
End Enum
DDOVERFX_ARITHSTRETCHY
伸縮する場合、このオーバーレイの y 軸に沿って算術伸縮を使用する。
DDOVERFX_MIRRORLEFTRIGHT
垂直軸の周りでオーバーレイをミラー化する。
DDOVERFX_MIRRORUPDOWN
水平軸の周りでオーバーレイをミラー化する。


CONST_DDOVERZFLAGS

CONST_DDOVERZFLAGS 列挙のフラグは、DirectDrawSurface7.UpdateOverlayZOrder 型の flags メンバで使用され、オーバーレイの z オーダーを設定する。

Enum CONST_DDPALFLAGS
    DDOVERZ_INSERTINBACKOF  = 5
    DDOVERZ_INSERTINFRONTOF = 4
    DDOVERZ_MOVEBACKWARD    = 3
    DDOVERZ_MOVEFORWARD     = 2
    DDOVERZ_SENDTOBACK      = 1
    DDOVERZ_SENDTOFRONT     = 0
End Enum
DDOVERZ_INSERTINBACKOF
このオーバーレイをオーバーレイ チェーンの参照オーバーレイの後ろに挿入する。
DDOVERZ_INSERTINFRONTOF
このオーバーレイをオーバーレイ チェーンの参照オーバーレイの前に挿入する。
DDOVERZ_MOVEBACKWARD
このオーバーレイをオーバーレイ チェーンの 1 つ後ろに移動する。
DDOVERZ_MOVEFORWARD
このオーバーレイをオーバーレイ チェーンの 1 つ前に移動する。
DDOVERZ_SENDTOBACK
このオーバーレイをオーバーレイ チェーンの後ろに移動する。
DDOVERZ_SENDTOFRONT
このオーバーレイをオーバーレイ チェーンの前に移動する。


CONST_DDPALFLAGS

CONST_DDPALFLAGS 列挙のフラグは、PALETTEENTRY 型の flags メンバで使用され、パレット エントリの使用方法を指定する。

Enum CONST_DDPALFLAGS
    PC_DEFAULT     = 0
    PC_EXPLICIT    = 2
    PC_NOCOLLAPSE  = 4
    PC_RESERVED    = 1
End Enum
PC_DEFAULT
パレット エントリを、以下のフラグによって変更せずに使用する。
PC_EXPLICIT
論理パレット エントリの下位ワードによってハードウェア パレット インデックスを示す。アプリケーションは、このフラグを使ってディスプレイ デバイス パレットのコンテンツを表示できる。
PC_NOCOLLAPSE
色をシステム パレットの既存のカラーに適合せずに、システム パレットの未使用のエントリに割り当てる。システム パレットに未使用のエントリがない場合、通常どおりに適合される。システム パレットに割り当てられた色は、ほかの論理パレットの色と適合できる。
PC_RESERVED
パレット アニメーションに使用される論理パレット エントリ。色が頻繁に変化するので、このフラグによって、ほかのウィンドウがパレット エントリに色を適合しないようにする。未使用のシステム パレット エントリが使用可能な場合、そのエントリに色が割り当てられる。そうでない場合、その色はアニメーションで使用できない。

注意

タイプ ライブラリでは、この列挙ではなく PALETTEENTRY のフラグ メンバをバイトに定義するので、自動完了は使用できない。この列挙のフラグは flags メンバに対して有効であり、動作を変更するために指定できる。


CONST_DDPCAPSFLAGS

CONST_DDPCAPSFLAGS 列挙は、DirectDraw7.CreatePalette の flags パラメータで、DirectDrawPalette.GetCaps の戻り値として使用される。また、DDCAPS の lPalCaps メンバによってパレットの能力を記述するために使用される。

Enum CONST_DDPCAPSFLAGS
    DDPCAPS_1BIT             =  256
    DDPCAPS_2BIT             =  512
    DDPCAPS_4BIT             =    1
    DDPCAPS_8BIT             =    4
    DDPCAPS_8BITENTRIES      =    2
    DDPCAPS_ALLOW256         =   64
    DDPCAPS_ALPHA            = 1024
    DDPCAPS_INITIALIZE       =    8
    DDPCAPS_PRIMARYSURFACE   =   16
    DDPCAPS_PRIMARYSURFACELEFT = 32
    DDPCAPS_VSYNC            =  128
End Enum
DDPCAPS_1BIT
インデックスが 1 ビットであることを示す。カラー テーブルには、2 つのエントリがある。
DDPCAPS_2BIT
インデックスが 2 ビットであることを示す。カラー テーブルには、4 つのエントリがある。
DDPCAPS_4BIT
インデックスが 4 ビットであることを示す。カラー テーブルには、16 のエントリがある。
DDPCAPS_8BIT
インデックスが 8 ビットであることを示す。カラー テーブルには、256 のエントリがある。
DDPCAPS_8BITENTRIES
インデックスを 8 ビット カラー インデックスに指定する。DDPCAPS_1BIT、DDPCAPS_2BIT、または DDPCAPS_4BIT フラグを使う場合と、ターゲット サーフェスが 8 bpp の場合だけ、このフラグは有効となる。個々のカラー エントリは 1 バイト長であり、転送先サーフェスの 8 bpp パレットへのインデックスである。
DDPCAPS_ALLOW256
このパレットは、定義されるすべての 256 エントリを所有できる。
DDPCAPS_ALPHA
関連付けられた PALETTEENTRY 型の flags メンバが、単一の 8 ビット アルファ値として判断されることを示す。このフラグで作成されるパレットは、DDSCAPS_TEXTURE 能力フラグで作成されたサーフェスであるテクスチャにアタッチできるだけである。
DDPCAPS_INITIALIZE
廃止されたので、無視される。
DDPCAPS_PRIMARYSURFACE
プライマリ サーフェスにこのパレットをアタッチする。このパレットのカラー テーブルを変更すると、DDPSETPAL_VSYNC が指定されてサポートされない限り、即座にディスプレイに影響を与える。
DDPCAPS_PRIMARYSURFACELEFT
このパレットは、左眼プライマリ サーフェスにアタッチされる。このパレットのカラー テーブルを変更すると、DDPSETPAL_VSYNC が指定されてサポートされない限り、即座に左眼ディスプレイに影響を与える。
DDPCAPS_VSYNC
このパレットは、モニタのリフレッシュ レートと同期するように修正できる。


CONST_DDPIXELFORMATFLAGS

CONST_DDPIXELFORMATFLAGS 列挙は、DDPIXELFORMAT 型の lFlags メンバで使用され、オプション制御フラグを指定する。

Enum CONST_DDPIXELFORMATFLAGS
    DDPF_ALPHA          =      2
    DDPF_ALPHAPIXELS    =      1
    DDPF_ALPHAPREMULT   =  32768
    DDPF_BUMPDUDV       = 524288
    DDPF_BUMPLUMINANCE  = 262144
    DDPF_COMPRESSED     =    128
    DDPF_FOURCC         =      4
    DDPF_LUMINANCE      = 131072
    DDPF_PALETTEINDEXED1 =  2048
    DDPF_PALETTEINDEXED2 =  4096
    DDPF_PALETTEINDEXED4 =     8
    DDPF_PALETTEINDEXED8 =    32
    DDPF_PALETTEINDEXEDTO8 =  16
    DDPF_RGB             =    64
    DDPF_RGBTOYUV        =   256
    DDPF_STENCILBUFFER   = 16384
    DDPF_YUV             =   512
    DDPF_ZBUFFER         =  1024
    DDPF_ZPIXELS         =  8192
End Enum
DDPF_ALPHA
ピクセル フォーマットは、アルファ専用サーフェスを記述する。
DDPF_ALPHAPIXELS
サーフェスには、ピクセル フォーマットのアルファ チャネル情報がある。
DDPF_ALPHAPREMULT
サーフェスは、あらかじめ増やしたアルファ フォーマットを使用する。つまり、個々のピクセルの色成分は、アルファ成分をあらかじめ掛けられている。
DDPF_BUMPDUDV
ピクセル フォーマットのバンプマップ データは有効である。バンプマップ情報は、lBumpBitCount、lBumpDuBitMask、lBumpDvBitMask、および lBumpLuminanceBitMask メンバにある。
DDPF_BUMPLUMINANCE
ピクセル フォーマットの輝度データは有効である。また、lLuminanceBitMask メンバは、輝度専用または輝度アルファ サーフェスに対する有効な輝度ビットを記述する。
DDPF_COMPRESSED
サーフェスは指定された特定のフォーマットでピクセル データを受け取り、書き込み処理中にそのデータを圧縮する。
DDPF_FOURCC
lFourCC メンバは有効で、非 RGB ピクセル フォーマットを記述する FOURCC コードを含む。
DDPF_LUMINANCE
ピクセル フォーマットは、輝度専用または輝度アルファ サーフェスを記述する。
DDPF_PALETTEINDEXED1
DDPF_PALETTEINDEXED2
DDPF_PALETTEINDEXED4
DDPF_PALETTEINDEXED8
サーフェスは、1 ビット、2 ビット、4 ビット、または 8 ビットの色でインデックスされている。
DDPF_PALETTEINDEXEDTO8
サーフェスは、1 ビット、2 ビット、4 ビットの色を 8 ビット パレットにインデックスしている。
DDPF_RGB
ピクセル フォーマット型の RGB データは有効である。
DDPF_RGBTOYUV
サーフェスは RGB データを受け取り、書き込み処理中に YUV データにそのデータを変換する。書き込みのデータのフォーマットは、ピクセル フォーマット型に含まれる。DDPF_RGB フラグが設定されている。
DDPF_STENCILBUFFER
サーフェスは、Z バッファの個々のピクセルにおけるステンシルと深度情報を符号化する。
DDPF_YUV
ピクセル フォーマット型の YUV データは有効である。
DDPF_ZBUFFER
ピクセル フォーマットは、Z バッファ専用サーフェスを記述する。
DDPF_ZPIXELS
サーフェスは、ピクセルの z 情報を含む。


CONST_DDRAW

CONST_DDRAW 列挙には、DirectDraw 全体で使用される定数が含まれる。

Enum CONST_DDRAW
    DD_ROP_SPACE = 8
End Enum
DD_ROP_SPACE
デフォルトの Win32 ラスタ処理。


CONST_DDRAWERR

DirectDraw のエラー値については、「エラー コード」を参照すること。


CONST_DDSCLFLAGS

CONST_DDSCLFLAGS 列挙は、DirectDraw7.SetCooperativeLevel 列挙の flags パラメータで使用され、アプリケーションの最上位動作を定義する。

Enum CONST_DDSCLFLAGS
    DDSCL_ALLOWMODEX       =    64
    DDSCL_ALLOWREBOOT      =     2
    DDSCL_CREATEDEVICEWINDOW = 512
    DDSCL_EXCLUSIVE        =    16
    DDSCL_FULLSCREEN       =     1
    DDSCL_MULTITHREADED    =  1024
    DDSCL_NORMAL           =     8
    DDSCL_NOWINDOWCHANGES  =     4
    DDSCL_SETDEVICEWINDOW  =   256
    DDSCL_SETFOCUSWINDOW   =   128
End Enum
DDSCL_ALLOWMODEX
モード X ディスプレイ モードの利用を許可する。DDSCL_EXCLUSIVE と DDSCL_FULLSCREEN プラグが存在する場合だけ、このフラグを使用できる。
DDSCL_ALLOWREBOOT
排他 (フルスクリーン) モード時に、Ctrl ＋ Alt ＋ Del の機能を許可する。
DDSCL_CREATEDEVICEWINDOW
このフラグは、Windows 98 と Windows NT 2000 だけでサポートされる。DirectDraw が、この DirectDraw オブジェクトに対するデフォルト デバイス ウィンドウを作成し、管理することを示す。詳細については、「フォーカス ウィンドウとデバイス ウィンドウ」を参照すること。
DDSCL_EXCLUSIVE
排他レベルを要求する。このフラグは、DDSCL_FULLSCREEN フラグと共に使用しなければならない。
DDSCL_FULLSCREEN
排他モードの所有者がプライマリ サーフェス全体に対して責任を負うことを示す。GDI を無視できる。このフラグは、DDSCL_EXCLUSIVE フラグと共に使用しなければならない。
DDSCL_MULTITHREADED
マルチスレッドの確実な DirectDraw 動作を要求する。これにより、Direct3D が頻繁にグローバル危険域を取得するようになる。
DDSCL_NORMAL
アプリケーションが、通常の Windows アプリケーションとして機能することを示す。このフラグは、DDSCL_ALLOWMODEX、DDSCL_EXCLUSIVE、または DDSCL_FULLSCREEN フラグと共に使用することはできない。
DDSCL_NOWINDOWCHANGES
DirectDraw が、アクティブなアプリケーション ウィンドウを最小化したり、リストアできないことを示す。
DDSCL_SETDEVICEWINDOW
このフラグは、Windows 98 と Windows NT 2000 だけでサポートされる。hdl パラメータが、この DirectDraw オブジェクトに対するデバイス ウィンドウのウィンドウ ハンドルであることを示す。このフラグは、DDSCL_SETFOCUSWINDOW フラグと共に使用することはできない。
DDSCL_SETFOCUSWINDOW
このフラグは、Windows 98 と Windows NT 2000 だけでサポートされる。hdl パラメータが、この DirectDraw オブジェクトに対するフォーカス ウィンドウのウィンドウ ハンドルであることを示す。このフラグは、DDSCL_SETDEVICEWINDOW フラグと共に使用することはできない。


CONST_DDSDMFLAGS

CONST_DDSDMFLAGS 列挙は、DirectDraw7.SetDisplayMode メソッドの flags パラメータで使用され、ディスプレイ デバイス ハードウェアのモードを設定する。

Enum CONST_DDSDMFLAGS
    DDSDM_DEFAULT = 0
    DDSDM_STANDARDVGAMODE = 1
End Enum
DDSDM_DEFAULT
モード X の代わりにモード 13 を使用せずに、モードを設定する。
DDSDM_STANDARDVGAMODE
モード X の 320×200×8 モードではなく、モード 13 を設定できる。別の解像度、ビット深度、またはモード X モードに設定する場合は、このフラグを使用せずにパラメータを 0 に設定する。


CONST_DDSGRFLAGS

CONST_DDSGRFLAGS 列挙は、DirectDrawGammaControl.SetGammaRamp メソッドの flags パラメータで使用され、要求されるガンマ キャリブレーションを示す。

Enum CONST_DDSGRFLAGS
    DDSGR_CALIBRATE = 1
    DDSGR_DEFAULT = 0
End Enum
DDSGR_DEFAULT
ガンマ ランプをディスプレイの物理的性質に従ってキャリブレーションせずに設定する。
DDSGR_CALIBRATE
調節結果がすべてのシステム上で同一になるように、口径測定器がディスプレイの物理的性質に従ってガンマ ランプを調節するよう要求する。キャリブレーションを必要としない場合は、このパラメータを 0 に設定する。


CONST_DDSTEREOCAPSFLAGS

CONST_DDSTEREOCAPSFLAGS 列挙は、DDCAPS 型の lSVCaps メンバで使用され、ステレオ ビジョン能力を記述する。

Enum CONST_DDSTEREOCAPSFLAGS
    DDSVCAPS_ENIGMA  = 1
    DDSVCAPS_FLICKER = 2
    DDSVCAPS_REDBLUE = 4
    DDSVCAPS_SPLIT   = 8
    DDSVCAPS_STEREOSEQUENTIAL = 16
End Enum
DDSVCAPS_ENIGMA
エニグマ コーディングにより、ステレオ ビューを実現していることを示す。
DDSVCAPS_FLICKER
高周波フリッカーにより、ステレオ ビューを実現していることを示す。
DDSVCAPS_REDBLUE
ビューワーで左と右の眼に配置した赤と青のフィルタからイメージを見ることにより、ステレオ ビューを実現していることを示す。すべてのイメージは、このプロセスの色空間と適合しなくてはならない。
DDSVCAPS_SPLIT
スプリットスクリーン技術により、ステレオ ビューを実現していることを示す。
DDSVCAPS_STEREOSEQUENTIAL
ドライバは、現在のモード以外の少なくとも 1 つのモードでステレオ ビューを実現できる。アプリケーションは、DirectDraw7.GetDisplayMode または DirectDraw7.GetDisplayModesEnum を使って、モードごとのステレオ情報を取得できる。


CONST_DDSURFACECAPS2FLAGS

CONST_DDSURFACECAPS2FLAGS 列挙は、DDSCAPS2 型の lCaps2 メンバで使用され、追加のサーフェス能力を記述する。

Enum CONST_DDSURFACECAPS2FLAGS
    DDSCAPS2_CUBEMAP             = 512
    DDSCAPS2_CUBEMAP_ALLFACES    = 65024
    DDSCAPS2_CUBEMAP_NEGATIVEX   = 2048
    DDSCAPS2_CUBEMAP_NEGATIVEY   = 8192
    DDSCAPS2_CUBEMAP_NEGATIVEZ   = 32768
    DDSCAPS2_CUBEMAP_POSITIVEX   = 1024
    DDSCAPS2_CUBEMAP_POSITIVEY   = 4096
    DDSCAPS2_CUBEMAP_POSITIVEZ   = 16384
    DDSCAPS2_D3DTEXTUREMANAGE    = 131072
    DDSCAPS2_HARDWAREDEINTERLACE = 2
    DDSCAPS2_HINTANTIALIASING    = 256
    DDSCAPS2_HINTDYNAMIC         = 4
    DDSCAPS2_HINTSTATIC          = 8
    DDSCAPS2_MIPMAPSUBLEVEL      = 65536
    DDSCAPS2_OPAQUE              = 128
    DDSCAPS2_STEREOSURFACELEFT   = 524288
    DDSCAPS2_TEXTUREMANAGE       = 16
End Enum
能力フラグ
DDSCAPS2_CUBEMAP
DirectX 7.0 の新機能。このサーフェスがキューブ環境マップであることを示す。
DDSCAPS2_CUBEMAP_ALLFACES
DirectX 7.0 の新機能。このフラグを DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの 6 つの面をすべて作成する。
DDSCAPS2_CUBEMAP_NEGATIVEX
DirectX 7.0 の新機能。このフラグを DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの負の x 面を作成する。
DDSCAPS2_CUBEMAP_NEGATIVEY
DirectX 7.0 の新機能。このフラグを DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの負の y 面を作成する。
DDSCAPS2_CUBEMAP_NEGATIVEZ
DirectX 7.0 の新機能。このフラグを DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの負の z 面を作成する。
DDSCAPS2_CUBEMAP_POSITIVEX
DirectX 7.0 の新機能。このフラグを DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの正の x 面を作成する。
DDSCAPS2_CUBEMAP_POSITIVEY
DirectX 7.0 の新機能。このフラグを DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの正の y 面を作成する。
DDSCAPS2_CUBEMAP_POSITIVEZ
DirectX 7.0 の新機能。このフラグを DDSCAPS2_CUBEMAP フラグと共に使用して、キューブ環境マップの正の z 面を作成する。
DDSCAPS2_D3DTEXTUREMANAGE
DirectX 7.0 の新機能。テクスチャが常に Direct3D によって管理されることを示す。
DDSCAPS2_HARDWAREDEINTERLACE
このサーフェスが、インターレイス方式ではないハードウェアを使用するビデオ ポートからデータを受け取ることを示す。これにより、ドライバは要求される可能性のある外部バッファにメモリを割り当てることができる。DDSCAPS_VIDEOPORT および DDSCAPS_OVERLAY フラグも設定しなくてはならない。
DDSCAPS2_HINTANTIALIASING
アプリケーションがアンチエイリアスを使用することを示す。DDSCAPS_3DDEVICE が同様に設定されている場合にだけ有効である。
DDSCAPS2_HINTDYNAMIC
このサーフェスが非常によくロックされること (手続きテクスチャやダイナミック ライト マップなど) をドライバに示す。このフラグは、テクスチャ サーフェスに対してだけ使用できる (DDSCAPS_TEXTURE フラグは、ｌCaps2 メンバに設定する)。このフラグは、DDSCAPS2_HINTSTATIC または DDSCAPS2_OPAQUE フラグと共に使用できない。
DDSCAPS2_HINTSTATIC
このサーフェスが、ロードにより再び整理されたり再びタイル表示できることをドライバに示す。この処理では、テクスチャのサイズを変更できない。アプリケーションはこれらのビットをロックする場合があるので、相対的に早く、左右対称である (この処理のときにパフォーマンスが低下する場合がある)。このフラグは、テクスチャ サーフェスに対してだけ使用できる (DDSCAPS_TEXTURE フラグは、lCaps2 メンバに設定する)。このフラグは、DDSCAPS2_HINTDYNAMIC または DDSCAPS2_OPAQUE フラグと共に使用できない。
DDSCAPS2_MIPMAPSUBLEVEL
DirectX 7.0 の新機能。ルート サーフェスに複数のミップマップ サーフェスがアタッチされているキューブ マップなどのサーフェス構成要素に対して、EnumAttachedSurfaces ではなく GetAttachedSurface を使用できる。GetAttachedSurface の呼び出しで、最上位サーフェスとアタッチされたミップマップ レベルを区別できるように、ミップマップ キューブマップの最上位レベル以外のサーフェスにはすべてこのフラグを設定する必要がある。CreateSurface ではこのフラグを無視する。
DDSCAPS2_OPAQUE
このサーフェスが、決して再ロックされないことをドライバに示す。ドライバは、再タイル表示や実際の圧縮によりこのサーフェスを自由に最適化できる。このようなサーフェスはロックされたり、ブリット処理で使用されたりできない。この能力でサーフェスをロックしたりブリットしようとすると、失敗する。このフラグは、テクスチャ サーフェスに対してだけ使用できる (DDSCAPS_TEXTURE フラグは、lCaps2 メンバに設定する)。このフラグは、DDSCAPS2_HINTDYNAMIC または DDSCAPS2_HINTSTATIC フラグと共に使用できない。
DDSCAPS2_STEREOSURFACELEFT
DirectX 7.0 の新機能。このサーフェスが、ステレオ フリッピング チェーンの一部であることを示す。DirectDraw7.CreateSurface の呼び出し時にこのフラグを設定すると、プライマリ フリッピング チェーンの各バッファに対して、ステレオ サーフェスのペアが作成される。このフラグでは、複合フリッピング チェーン (バック バッファを含む) を作成しなければならない。単一セットのステレオ サーフェスは作成できない。DirectDrawSurface7.Flip メソッドを実行するには、バック バッファが必要である (少なくとも 4 つのサーフェスが作成されていなければならない)。

また、DirectDraw7.GetDisplayModesEnum または DirectDraw7.GetDisplayMode の呼び出しで取得された DDSURFACEDESC2 型にこのフラグが設定されている場合、そのモードでステレオがサポートされていることを示す。

DDSCAPS2_TEXTUREMANAGE
クライアントがこのテクスチャ サーフェスを、ドライバが使用可能な場合はドライバによって、使用不能な場合は Direct3D 直接モード (DirectX 7.0 の新機能) によって管理することを示す。このフラグは、テクスチャ サーフェスに対してだけ使用できる (DDSCAPS_TEXTURE フラグは、lCaps2 メンバに設定する)。詳細については、Direct3D 直接モードの「自動テクスチャ管理」を参照すること。アプリケーションが Direct3D 保持モードを使用する場合には、このフラグを使用せずに、システム メモリにテクスチャを作成し、保持モードで管理できるようにする。


CONST_DDSURFACECAPSFLAGS

CONST_DDSURFACECAPSFLAGS 列挙は、DDSCAPS2 型の lCaps メンバで使用され、サーフェスの能力を記述する。

Enum CONST_DDSURFACECAPSFLAGS
    DDSCAPS_3DDEVICE        =        8192
    DDSCAPS_ALLOCONLOAD     =    67108864
    DDSCAPS_ALPHA           =           2
    DDSCAPS_BACKBUFFER      =           4
    DDSCAPS_COMPLEX         =           8
    DDSCAPS_FLIP            =          16
    DDSCAPS_FRONTBUFFER     =          32
    DDSCAPS_HWCODEC         =     1048576
    DDSCAPS_LIVEVIDEO       =      524288
    DDSCAPS_LOCALVIDMEM     =   268435456
    DDSCAPS_MIPMAP          =     4194304
    DDSCAPS_MODEX           =     2097152
    DDSCAPS_NONLOCALVIDMEM  =   536870912
    DDSCAPS_OFFSCREENPLAIN  =          64
    DDSCAPS_OPTIMIZED       = -2147483648
    DDSCAPS_OVERLAY         =         128
    DDSCAPS_OWNDC           =      262144
    DDSCAPS_PALETTE         =         256
    DDSCAPS_PRIMARYSURFACE  =         512
    DDSCAPS_RESERVED2       =     8388608
    DDSCAPS_STANDARDVGAMODE =  1073741824
    DDSCAPS_SYSTEMMEMORY    =        2048
    DDSCAPS_TEXTURE         =        4096
    DDSCAPS_VIDEOMEMORY     =       16384
    DDSCAPS_VIDEOPORT       =   134217728
    DDSCAPS_VISIBLE         =       32768
    DDSCAPS_WRITEONLY       =       65536
    DDSCAPS_ZBUFFER         =      131072
End Enum
DDSCAPS_3DDEVICE
このサーフェスが、3D レンダリングに使用できることを示す。アプリケーションはこのフラグを使い、デバイスが適切なヒープから割り当てられたオフスクリーン サーフェスのある特定のヒープだけをレンダリングできることを保証する。このフラグがヒープに対して設定されている場合、サーフェスはそのヒープから割り当てられない。
DDSCAPS_ALLOCONLOAD
使用しない。DirectDraw と Direct3D では無視される。
DDSCAPS_ALPHA
このサーフェスが、アルファ専用情報を含むことを示す。
DDSCAPS_BACKBUFFER
このサーフェスが、サーフェス フリッピング型のバック バッファであることを示す。通常、この能力は、DDSCAPS_FLIP フラグが使用されるときに CreateSurface メソッドで設定される。DDSCAPS_FRONTBUFFER サーフェスの直前のサーフェスだけ、この能力が設定される。ほかのサーフェスは、DDSCAPS_FLIP フラグの存在、アタッチの順序、および DDSCAPS_FRONTBUFFER と DDSCAPS_BACKBUFFER 能力の欠如により、バック バッファと識別される。この能力が CreateSurface メソッドに送られると、スタンドアロン バック バッファを作成する。このメソッドの呼び出し後、このサーフェスはフロント バッファ、別のバック バッファ、またはその両方にアタッチすることができ、フリッピング サーフェス型が形成される。詳細については、「DirectDrawSurface7.AddAttachedSurface」を参照すること。DirectDraw は、フリッピング型のサーフェスにおける任意の数をサポートする。
DDSCAPS_COMPLEX
複合サーフェスが記述されていることを示す。複合サーフェスは、1 つ以上のサーフェスの作成をもたらす。追加サーフェスは、ルート サーフェスにアタッチされる。複合型は、単にルートを破棄することで破棄できる。
DDSCAPS_FLIP
このサーフェスが、サーフェス フリッピング型の一部であることを示す。この能力が CreateSurface メソッドに渡される場合、フロント バッファと 1 つ以上のバック バッファを作成する。DirectDraw は、フロント バッファ サーフェスに DDSCAPS_FRONTBUFFER ビット、およびフロント バッファ サーフェスに隣接するサーフェスに DDSCAPS_BACKBUFFER ビットを設定する。DDSURFACEDESC2 型の lBackBufferCount メンバは、メソッドの呼び出しが成功するために、少なくとも 1 に設定する必要がある。CreateSurface メソッドで複数のサーフェスを作成する場合、DDSCAPS_COMPLEX 能力を常に設定しなくてはならない。
DDSCAPS_FRONTBUFFER
このサーフェスが、サーフェス フリッピング型のフロント バッファであることを示す。一般的にこのフラグは、DDSCAPS_FLIP 能力を設定する場合に、CreateSurface メソッドで設定される。この能力が CreateSurface メソッドに送られると、スタンドアロン フロント バッファを作成する。このサーフェスには、DDSCAPS_FLIP 能力がない。DirectDrawSurface7.AddAttachedSurface を使って、ほかのバック バッファにアタッチすることができ、フリッピング型を形成する。
DDSCAPS_HWCODEC
このサーフェスが、ハードウェアにより圧縮を解除されたストリームを持つことができることを示す。
DDSCAPS_LIVEVIDEO
このサーフェスが、ライブ ビデオを受け取れることを示す。
DDSCAPS_LOCALVIDMEM
このサーフェスが、非ローカル ビデオ メモリではなく、真のローカル ビデオ メモリに存在することを示す。このフラグを指定すると、DDSCAPS_VIDEOMEMORY も同様に指定しなくてはならない。このフラグは、DDSCAPS_NONLOCALVIDMEM フラグと共に使用できない。
DDSCAPS_MIPMAP
このサーフェスが、1 レベルのミップマップであることを示す。このサーフェスをほかの DDSCAPS_MIPMAP サーフェスにアタッチすると、ミップマップを形成できる。これは、多数のサーフェスの作成、および DirectDrawSurface7.AddAttachedSurface メソッドの使用によるアタッチにより明示的に行われるか、または CreateSurface メソッドの使用により暗に行われる。この能力を設定する場合、DDSCAPS_TEXTURE も設定しなくてはならない。
DDSCAPS_MODEX
このサーフェスが、320×200 または 320×240 のモード X サーフェスであることを示す。
DDSCAPS_NONLOCALVIDMEM
このサーフェスが、真のローカル ビデオ メモリではなく、非ローカル ビデオ メモリに存在することを示す。このフラグを指定すると、DDSCAPS_VIDEOMEMORY フラグも同様に指定しなくてはならない。これは、DDSCAPS_LOCALVIDMEM フラグと共に使用することはできない。
DDSCAPS_OFFSCREENPLAIN
このサーフェスが、オーバーレイ、テクスチャ、Z バッファ、フロント バッファ、バック バッファ、またはアルファ サーフェスのどれでもないオフスクリーン サーフェスであることを示す。平面サーフェスを識別するために使用される。
DDSCAPS_OPTIMIZED
現時点では、実装されていない。
DDSCAPS_OVERLAY
このサーフェスが、オーバーレイ サーフェスであることを示す。現在、プライマリ サーフェスにオーバーレイされているかどうかにより、直接的に表示されるかどうかが決まる。DDSCAPS_VISIBLE は、サーフェスが現時点でオーバーレイされているかどうかを決定するために使用できる。
DDSCAPS_OWNDC
このサーフェスが、長時間にわたりデバイス コンテキスト (DC) 関連であることを示す。
DDSCAPS_PALETTE
このデバイス ドライバにより、固有の DirectDrawPalette オブジェクトを作成してこのサーフェスにアタッチできることを示す。
DDSCAPS_PRIMARYSURFACE
サーフェスが、プライマリ サーフェスであることを示す。このサーフェスが現在表示されていることを表す。
DDSCAPS_RESERVED2
将来的な使用のために確保されている。
DDSCAPS_STANDARDVGAMODE
このサーフェスが標準 VGA モード サーフェスであり、モード X サーフェスではないことを示す。このフラグは、DDSCAPS_MODEX フラグの組み合わせで使用することはできない。
DDSCAPS_SYSTEMMEMORY
このサーフェス メモリが、システム メモリに割り当てられたことを示す。
DDSCAPS_TEXTURE
このサーフェスが、3D テクスチャとして使用できることを示す。ただし、必ずしも 3D テクスチャとして使用しなくてはならないということではない。
DDSCAPS_VIDEOMEMORY
このサーフェスが、ディスプレイ メモリに存在することを示す。
DDSCAPS_VIDEOPORT
このサーフェスが、ビデオ ポートからデータを受け取れることを示す。
DDSCAPS_VISIBLE
このサーフェスに対して行われる変更が、即座に表示されることを示す。オーバーレイされる間のオーバーレイや、テクスチャされる間のテクスチャ マップに対するのと同様、プライマリ サーフェスに対して常に設定される。
DDSCAPS_WRITEONLY
サーフェスが、書き込み専用となることを示す。サーフェスからの読み込みアクセスが、一般保護 (GP) エラーを発生する可能性もある。このサーフェスからの読み込み結果は意味がない。
DDSCAPS_ZBUFFER
このサーフェスが、Z バッファであることを示す。Z バッファには、表示されない情報を含む。代わりに、Z バッファには、どのピクセルが表示され、どのピクセルが表示されないかを決定するのに使用するビット深度情報を含む。


CONST_DDSURFACEDESCFLAGS

CONST_DDSURFACEDESCFLAGS 列挙は、DDSURFACEDESC2 型の lFlags メンバで使用され、DDSURFACEDESC2 のどのメンバが有効なデータを含むかを指定する。

Enum CONST_DDSURFACEDESCFLAGS
    DDSD_ALL          = 1047022
    DDSD_ALPHABITDEPTH =    128
    DDSD_BACKBUFFERCOUNT =   32
    DDSD_CAPS         =       1
    DDSD_CKDESTBLT    =   16384
    DDSD_CKDESTOVERLAY =   8192
    DDSD_CKSRCBLT     =   65536
    DDSD_CKSRCOVERLAY =   32768
    DDSD_HEIGHT       =       2
    DDSD_LINEARSIZE   =  524288
    DDSD_LPSURFACE    =    2048
    DDSD_MIPMAPCOUNT  =  131072
    DDSD_PITCH        =       8
    DDSD_PIXELFORMAT  =    4096
    DDSD_REFRESHRATE  =  262144
    DDSD_TEXTURESTAGE = 1048576
    DDSD_WIDTH        =       4
    DDSD_ZBUFFERBITDEPTH =   64
End Enum
DDSD_ALL
すべての入力メンバが有効である。
DDSD_ALPHABITDEPTH
lAlphaBitDepth メンバは有効である。
DDSD_BACKBUFFERCOUNT
lBackBufferCount メンバは有効である。
DDSD_CAPS
ddsCaps メンバは有効である。
DDSD_CKDESTBLT
ddckCKDestBlt メンバは有効である。
DDSD_CKDESTOVERLAY
ddckCKDestOverlay メンバは有効である。
DDSD_CKSRCBLT
ddckCKSrcBlt メンバは有効である。
DDSD_CKSRCOVERLAY
ddckCKSrcOverlay メンバは有効である。
DDSD_HEIGHT
lHeight メンバは有効である。
DDSD_LINEARSIZE
使用されない (DX6 以降で実装される場合がある。lLinearSize メンバが有効であることを示す)。
DDSD_LPSURFACE
lpSurface メンバは有効である。
DDSD_MIPMAPCOUNT
lMipMapCount メンバは有効である。
DDSD_PITCH
lPitch メンバは有効である。
DDSD_PIXELFORMAT
ddpfPixelFormat メンバは有効である。
DDSD_REFRESHRATE
lRefreshRate メンバは有効である。
DDSD_TEXTURESTAGE
lTextureStage メンバは有効である。
DDSD_WIDTH
lWidth メンバは有効である。
DDSD_ZBUFFERBITDEPTH
lZBufferBitDepth メンバは有効である。


CONST_DDWAITVBFLAGS

CONST_DDWAITVBFLAGS 列挙は、DirectDraw7.WaitForVerticalBlank メソッドの flags パラメータで使用され、垂直帰線消去の待機時間を指定する。

Enum CONST_DDWAITVBFLAGS
    DDWAITVB_BLOCKBEGIN      = 1
    DDWAITVB_BLOCKBEGINEVENT = 2
    DDWAITVB_BLOCKEND        = 4
End Enum
DDWAITVB_BLOCKBEGIN
垂直帰線消去間隔が発生したときに返す。
DDWAITVB_BLOCKBEGINEVENT
垂直帰線消去が発生するときのイベント トリガ。この値は、現時点ではサポートされていない。
DDWAITVB_BLOCKEND
垂直帰線消去間隔が終了して表示するときに返す。


エラー コード

エラーは負の値で表され、組み合わされることはない。この項では、DirectDraw7、DirectDrawSurface7、DirectDrawPalette、および DirectDrawClipper オブジェクトのすべてのメソッドが返す可能性のある値のリストを示す。個々のメソッドが返す可能性のあるエラー コードのリストは、そのメソッドの記述を参照すること。

DD_OK
要求は成功し完了した。
DDERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DDERR_BLTFASTCANTCLIP
DirectDrawClipper オブジェクトが DirectDrawSurface7.BltFast メソッドの呼び出しに渡される転送元サーフェスにアタッチされている。
DDERR_CANNOTATTACHSURFACE
要求されたサーフェスにはサーフェスをアタッチできない。
DDERR_CANNOTDETACHSURFACE
要求されたサーフェスからサーフェスのアタッチを解除できない。
DDERR_CANTCREATEDC
Windows はそれ以上のいかなるデバイス コンテキスト (DC) も作ることができない。または、サーフェスにパレットがなく、ディスプレイ モードがインデックス付きのパレットでない場合、DC がインデックス付きパレット サーフェスのために要求された (この場合、DirectDraw は DC の固有のパレットを選択できない)。
DDERR_CANTDUPLICATE
プライマリ サーフェス、3D サーフェス、暗に作られるサーフェスは複製できない。
DDERR_CANTLOCKSURFACE
DCI サポートなしでプライマリ サーフェスのロックをしようとしたため、このサーフェスへのアクセスが拒否された。
DDERR_CANTPAGELOCK
サーフェスのページロックが失敗した。ページ ロックはディスプレイ メモリ サーフェスあるいはエミュレートされたプライマリ サーフェスの上では作用しない。
DDERR_CANTPAGEUNLOCK
サーフェスのページロックの解除が失敗した。ページ ロックの解除はディスプレイ メモリ サーフェスまたはエミュレートされたプライマリ サーフェス上では作用しない。
DDERR_CLIPPERISUSINGHWND
ウィンドウ ハンドルを既にモニタしている DirectDrawClipper オブジェクトにクリップ リストを設定しようとした。
DDERR_COLORKEYNOTSET
この処理に対する転送元カラー キーが指定されていない。
DDERR_CURRENTLYNOTAVAIL
現時点ではサポートされていない。
DDERR_DCALREADYCREATED
デバイス コンテキスト (DC) は既にこのサーフェスに対して返されている。1 サーフェスにつき 1 つの DC しか取得することはできない。
DDERR_DEVICEDOESNTOWNSURFACE
1 つの DirectDraw オブジェクトで作成されたサーフェスは、別の DirectDraw デバイスで直接使用することはできない。
DDERR_DIRECTDRAWALREADYCREATED
このドライバを表す DirectDraw オブジェクトが、このプロセスで既に作成されていることを表す。
DDERR_EXCEPTION
要求された処理を実行する間に例外が発生した。
DDERR_EXCLUSIVEMODEALREADYSET
既に排他モードが設定されているにもかかわらず、協調レベルを設定しようとした。
DDERR_EXPIRED
データが終了したので、有効でなくなった。
DDERR_GENERIC
未定義のエラー状態である。
DDERR_HEIGHTALIGN
提供された矩形の高さは、必要とされるアライメントの倍数ではない。
DDERR_HWNDALREADYSET
DirectDraw 協調レベル ウィンドウ ハンドルが既に設定されている。ウィンドウ ハンドルは、プロセスがサーフェスまたは作成されたパレットを保持している間はリセットできない。
DDERR_HWNDSUBCLASSED
DirectDraw 協調レベル ウィンドウ ハンドルがサブクラス化されているため、DirectDraw の状態のリストアが阻止された。
DDERR_IMPLICITLYCREATED
サーフェスが暗に作成されたために、サーフェスをリストアできない。
DDERR_INCOMPATIBLEPRIMARY
プライマリ サーフェス作成要求が既存のプライマリ サーフェスと適合していない。
DDERR_INVALIDCAPS
コールバック関数に渡された 1 つ以上の能力ビットが不正である。
DDERR_INVALIDCLIPLIST
DirectDraw は提供されたクリップ リストをサポートしない。
DDERR_INVALIDDIRECTDRAWGUID
Directx7.DirectDrawCreate 関数に渡されるグローバル ユニーク識別子 (GUID) は、有効な DirectDraw ドライバ識別子ではない。
DDERR_INVALIDMODE
DirectDraw は要求されたモードをサポートしない。
DDERR_INVALIDOBJECT
DirectDraw が無効な DirectDraw オブジェクトを受け取った。
DDERR_INVALIDPARAMS
メソッドに渡された 1 つ以上のパラメータが不正である。
DDERR_INVALIDPIXELFORMAT
指定されたピクセル フォーマットが無効である。
DDERR_INVALIDPOSITION
転送先のオーバーレイの位置が不正である。
DDERR_INVALIDRECT
提供された矩形が無効である。
DDERR_INVALIDSTREAM
指定されたストリームに無効なデータを含む。
DDERR_INVALIDSURFACETYPE
サーフェスが間違ったタイプのため、要求された処理を実行できなかった。
DDERR_LOCKEDSURFACES
1 つ以上のサーフェスがロックされている。
DDERR_MOREDATA
指定されたバッファ サイズに保持できる以上のデータが存在する。
DDERR_NO3D
3D ハードウェアまたはエミュレーションが存在しない。
DDERR_NOALPHAHW
アルファ アクセラレーション ハードウェアが存在しないか、利用できない。
DDERR_NOBLTHW
ブリット ハードウェアが存在しない。
DDERR_NOCLIPLIST
クリップ リストが利用できない。
DDERR_NOCLIPPERATTACHED
DirectDrawClipper オブジェクトがサーフェス オブジェクトにアタッチできない。
DDERR_NOCOLORCONVHW
カラー変換ハードウェアが存在しないか、利用できない。
DDERR_NOCOLORKEY
サーフェスが現在のカラー キーを持っていない。
DDERR_NOCOLORKEYHW
ハードウェアが転送先カラー キーをサポートしていない。
DDERR_NOCOOPERATIVELEVELSET
DirectDraw7.SetCooperativeLevel メソッドが呼び出されていないのに作成関数が呼び出された。
DDERR_NODC
DC がこのサーフェスに対して作成されていなかった。
DDERR_NODDROPSHW
DirectDraw ラスタ処理 (ROP) ハードウェアが利用できない。
DDERR_NODIRECTDRAWHW
ハードウェア専用 DirectDraw object オブジェクトを作成できない。ドライバはハードウェアをサポートしない。
DDERR_NODIRECTDRAWSUPPORT
現在のディスプレイ ドライバは DirectDraw をサポートしない。
DDERR_NOEMULATION
ソフトウェア エミュレーションが利用できない。
DDERR_NOEXCLUSIVEMODE
アプリケーションに対して排他モードが要求されたが、アプリケーションには排他モードがない。
DDERR_NOFLIPHW
表示されるサーフェスをフリッピングできない。
DDERR_NOFOCUSWINDOW
フォーカス ウィンドウが最初に設定されずに、デバイス ウィンドウを設定したり作成しようとした。
DDERR_NOGDI
GDI が存在しない。
DDERR_NOHWND
クリッパー通知がウィンドウ ハンドルを必要とする、またはウィンドウ ハンドルが協調レベル ウィンドウ ハンドルとしてあらかじめ設定されていない。
DDERR_NOMIPMAPHW
ミップマップ対応のテクスチャ マッピング ハードウェアが存在しないか、利用できない。
DDERR_NOMIRRORHW
ミラーリング ハードウェアが存在しないか、利用できない。
DDERR_NONONLOCALVIDMEM
非ローカル ビデオ メモリをサポートしないデバイスから、非ローカル ビデオ メモリを割り当てようとした。
DDERR_NOOPTIMIZEHW
デバイスは、最適化されたサーフェスをサポートしない。
DDERR_NOOVERLAYHW
オーバーレイ ハードウェアが存在しないか、利用できない。
DDERR_NOPALETTEATTACHED
パレット オブジェクトをこのサーフェスにアタッチできない。
DDERR_NOPALETTEHW
16 色あるいは 256 色のパレットに対するハードウェア サポートがない。
DDERR_NORASTEROPHW
適切なラスタ処理ハードウェアが存在しないか、利用できない。
DDERR_NOROTATIONHW
回転ハードウェアが存在しないか、利用できない。
DDERR_NOSTEREOHARDWARE
ステレオ ハードウェアが存在しないか、利用できない。
DDERR_NOSTRETCHHW
ハードウェアが伸縮をサポートしていない。
DDERR_NOSURFACELEFT
ステレオ サーフェスをサポートするハードウェアが存在しない。
DDERR_NOT4BITCOLOR
DirectDrawSurface オブジェクトは、4 ビット色パレットを使用していない。また、要求された処理は 4 ビット色パレットを要求する。
DDERR_NOT4BITCOLORINDEX
DirectDrawSurface オブジェクトは、4 ビット カラー インデックス パレットを使用していない。また、要求された処理は 4 ビット カラー インデックス パレットを要求する。
DDERR_NOT8BITCOLOR
DirectDrawSurface オブジェクトは、8 ビット色パレットを使用していない。また、要求された処理は 8 ビット色パレットを要求する。
DDERR_NOTAOVERLAYSURFACE
非オーバーレイ サーフェスに対して、オーバーレイ成分が呼び出された。
DDERR_NOTEXTUREHW
テクスチャ マッピング ハードウェアが存在しないか、利用できない。
DDERR_NOTFLIPPABLE
フリップできないサーフェスをフリップしようとした。
DDERR_NOTFOUND
要求された項目が見つからなかった。
DDERR_NOTINITIALIZED
オブジェクトが初期化される前に、CoCreateInstance で作成した DirectDraw オブジェクトのインターフェイス メソッドを呼び出そうとした。
DDERR_NOTLOADED
サーフェスは最適化されているが、まだメモリが割り当てられていない。
DDERR_NOTLOCKED
ロックされていないサーフェスのロック解除が行われた。
DDERR_NOTPAGELOCKED
未処置のページ ロックのないサーフェスのページ ロックの解除が行われた。
DDERR_NOTPALETTIZED
使用しているサーフェスはパレットベースのサーフェスではない。
DDERR_NOVSYNCHW
ハードウェアが垂直帰線消去同期処理をサポートしていない。
DDERR_NOZBUFFERHW
ハードウェアが Z バッファをサポートしていない。
DDERR_NOZOVERLAYHW
ハードウェアがオーバーレイの z オーダリングをサポートしていない。
DDERR_OUTOFCAPS
要求された処理に必要なハードウェアが既に割り当てられている。
DDERR_OUTOFMEMORY
DirectDraw が処理を行うのに十分なメモリがない。
DDERR_OUTOFVIDEOMEMORY
DirectDraw が処理を行うのに十分なディスプレイ メモリがない。
DDERR_OVERLAPPINGRECTS
転送元矩形と転送先矩形が同じサーフェス上にある。
DDERR_OVERLAYCANTCLIP
ハードウェアはクリッピング オーバーレイをサポートしない。
DDERR_OVERLAYCOLORKEYONLYONEACTIVE
オーバーレイ上に 1 つ以上の有効なカラー キーを持とうとした。
DDERR_OVERLAYNOTVISIBLE
メソッドが表示されないオーバーレイで呼び出された。
DDERR_PALETTEBUSY
パレットがもう 1 つのスレッドによりロックされているため、アクセスが拒否された。
DDERR_PRIMARYSURFACEALREADYEXISTS
この処理は既にプライマリ サーフェスを作成している。
DDERR_REGIONTOOSMALL
DirectDrawClipper.GetClipList メソッドに渡された領域が小さすぎる。
DDERR_SURFACEALREADYATTACHED
既にアタッチしているもう 1 つのサーフェスにサーフェスをアタッチしようとした。
DDERR_SURFACEALREADYDEPENDENT
既にほかのサーフェスに依存しているサーフェスを依存させようとした。
DDERR_SURFACEBUSY
サーフェスがもう 1 つのスレッドでロックされているため、サーフェスへのアクセスが拒否された。
DDERR_SURFACEISOBSCURED
サーフェスへのアクセスが、サーフェスが隠蔽されているため拒否された。
DDERR_SURFACELOST
サーフェス メモリの不足のため、サーフェスへのアクセスが拒否された。このサーフェスで DirectDrawSurface7.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_VIDEONOTACTIVE
ビデオ ポートがアクティブではない。
DDERR_WASSTILLDRAWING
このサーフェスから、またはサーフェスへの前回のブリット処理が完了していない。
DDERR_WRONGMODE
異なったモードで作成されたため、このサーフェスはリストアすることができない。
DDERR_XALIGN
提供された矩形を必要とされる範囲に水平一列に並べることができなかった。
E_INVALIDINTERFACE
指定されたインターフェイスが無効であるか、存在しない。
E_OUTOFMEMORY
メソッドを完了するために十分な空き容量がない。


ピクセル フォーマット マスク

この項では、ハードウェア エミュレーション レイヤ (HEL) がサポートするピクセル フォーマットについて説明する。以下の項目について記述する。

  • テクスチャ マップ フォーマット
  • オフスクリーン サーフェス フォーマット


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

HEL は、広範囲のテクスチャ マップ フォーマットをサポートしている。以下のテーブルにこれらのフォーマットを示す。マスク欄には、ピクセル フォーマット フラグとビット深度の各集合に対する赤、緑、青、およびアルファのマスクを示している。

ピクセル フォーマット フラグ | ビット深度 | マスク
DDPF_RGB | DDPF_PALETTEINDEXED1 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED1 | DDPF_PALETTEINDEXEDTO8 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | DDPF_PALETTEINDEXEDTO8 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | DDPF_PALETTEINDEXEDTO8 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED8 | 8 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | 8 | R:0x000000E0 G:0x0000001C B:0x00000003 A:0x00000000
DDPF_RGB | DDPF_ALPHAPIXELS | 16 | R:0x00000F00 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 | DDPF_ALPHAPIXELS | 16 | R:0x00007C00 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 | DDPF_ALPHAPIXELS | 32 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0xFF000000
DDPF_RGB | DDPF_ALPHAPIXELS | 32 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0xFF000000

HEL では、これらのフォーマットをシステム メモリに作成することができる。3D アクセラレート ディスプレイ カード用の DirectDraw デバイス ドライバは、ディスプレイ メモリに別のフォーマットのテクスチャを作成することもある。そのようなドライバは、テクスチャが作成できることを示すために DDSCAPS_TEXTURE フラグをエクスポートする。


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

以下のテーブルは、DirectX® 5,0 HEL がサポートするオフスクリーン サーフェスのピクセル フォーマットを示している。マスク欄には、ピクセル フォーマット フラグとビット深度の各集合に対する赤、緑、青、およびアルファのマスクを示している。

ピクセル フォーマット フラグ | ビット深度 | マスク
DDPF_RGB | DDPF_PALETTEINDEXED1 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED8 | 8 | R:0x00000000 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
DDPF_RGB | DDPF_ZPIXELS | 32 | R:0x0000F800 G:0x000007E0 B:0x0000001F Z:0xFFFF0000
DDPF_RGB | DDPF_ZPIXELS | 32 | R:0x00007C00 G:0x000003E0 B:0x0000001F Z:0xFFFF0000

広範囲なオフスクリーン サーフェス フォーマットのサポートのほかに、HEL は Direct3D またはほかの 3D レンダラーでの使用を意図したサーフェスもサポートする。


4 文字コード (FOURCC)

DirectDraw は、4 文字から成る特別なコードの集合を使用する。4 文字コードまたは FOURCC とも呼ばれるこれらのコードは、ビットマップ イメージ、サウンド、ビデオなどのマルチメディア データを含むファイルへのヘッダー ファイルに格納されている。FOURCC は、マルチメディア データを作成するために使用されたソフトウェア技術を示している。また暗に、FOURCC はデータ自体のフォーマットも記述している。

DirectDraw アプリケーションは、イメージ カラーやフォーマット変換に FOURCC を使用する。フォーマットが RGB ではないサーフェスのピクセル フォーマットを要求するためにアプリケーションが DirectDrawSurface7.GetPixelFormat メソッドを呼び出すと、メソッドが返るときに DDPIXELFORMAT 型の lFourCC メンバは FOURCC を識別する。

さらに、BITMAPINFOHEADER 型の biCompression メンバは、イメージを圧縮または復元するために使用するコーデックを示すため、FOURCC に設定することができる。

FOURCC は、マルチメディア ソフトウェア技術の各ベンダーによりマイクロソフトに登録されている。以下のテーブルに、共通の FOURCC の例を示す。

FOURCC | 会社名 | 技術名
AUR2 | AuraVision Corporation | AuraVision Aura 2:YUV 422
AURA | AuraVision Corporation | AuraVision Aura 1:YUV 411
CHAM | Winnov, Inc. | MM_WINNOV_CAVIARA_CHAMPAGNE
CVID | Supermac | Cinepak by Supermac
CYUV | Creative Labs, Inc | クリエイティブ ラボ YUV
FVF1 | Iterated Systems, Inc. | フラクタル ビデオ フレーム
IF09 | Intel Corporation | インテル インターミディアット YUV9
IV31 | Intel Corporation | インディオ 3,1
JPEG | Microsoft Corporation | スティル イメージ JPEG DIB
MJPG | Microsoft Corporation | モーション JPEG Dib フォーマット
MRLE | Microsoft Corporation | レン レングス エンコーディング
MSVC | Microsoft Corporation | ビデオ 1
PHMO | IBM Corporation | フォトモーション
RT21 | Intel Corporation | インディオ 2.1
ULTI | IBM Corporation | アルティモーション
V422 | Vitec Multimedia | 24 ビット YUV 4:2:2
V655 | Vitec Multimedia | 16 ビット YUV 4:2:2
VDCT | Vitec Multimedia | Video Maker Pro DIB
VIDS | Vitec Multimedia | YUV 4:2:2 CCIR 601 for V422
YU92 | Intel Corporation | YUV
YUV8 | Winnov, Inc. | MM_WINNOV_CAVIAR_YUV8
YUV9 | Intel Corporation | YUV9
YUYV | Canopus, Co., Ltd. | BI_YUYV, Canopus
ZPEG | Metheus | Video Zipper


DirectDraw のツールとサンプル

ここでは、DirectX SDK に含まれている、DirectDraw の使用法および DirectDraw アプリケーションの開発支援機能を示すサンプル アプリケーションについて説明する。説明する内容は以下のとおりである。

  • DirectDraw ツール
  • DirectDraw C/C++ サンプル
  • DirectDraw Visual Basic サンプル


DirectDraw ツール

ここでは、DirectX SDK に含まれるアプリケーションで、DirectDraw を使用するアプリケーションを開発するためのアプリケーションについて説明する。説明するツールは以下のとおりである。

  • DirectDraw Caps
  • DirectDraw Test
  • DirectX Texture ツール
  • KillHelp


DirectDraw Caps

説明

このユーティリティでは、デバイスの DirectDraw 能力を調べ、いろいろなスクリーン解像度をテストできる。

パス

実行可能ファイル :(SDK ルート)\bin\DXUtils\DDCaps.exe

ユーザーズ ガイド

[Driver] メニューおよび [HEL] メニューから能力のリストを選択し表示する。チェック ボックスの選択を解除して、ハードウェアまたはエミュレーション レイヤの能力をオフにする。

異なる解像度での能力をチェックするには、希望する解像度をダブルクリックする。能力のダイアログ ボックスが開いている場合は、[Refresh] をクリックする。

プログラムを終了すると、デフォルトのスクリーン解像度に戻る。


DirectDraw Test

説明

DirectDraw Test アプリケーションでは、サーフェスの作成と操作、サーフェス間のブリット、処理時間のチェック、その他のテストを実行できる。

パス

実行可能ファイル :(SDK ルート)\Bin\DXUtils\DDTest.exe

ユーザーズ ガイド

最初に [Options] をクリックしてデバイスを選択し、次に [Connect] をクリックして DirectDraw システムに接続する。[Create] ボタンをクリックし、希望する能力を選択して、1 つまたは複数のサーフェスを作成する。サーフェスの作成に失敗した場合、メッセージ リストにエラーが表示されるので注意すること。

ドロップダウン リストからサーフェスを選択し、さまざまなボタンを使用して操作する。各種フラグを使用してサーフェスから別のサーフェスにブリットするには、[Blt] を選択する。

[Timing] をクリックしてタイミング テストを実行する。テストを実行する前に [Set Mode]をクリックして異なる解像度を選択すれば、そのスクリーン解像度での処理速度をチェックできる。


DirectX Texture ツール

説明

このツールは、新しい DXTn 圧縮フォーマットのテクスチャ マップを作成するためのツールである。圧縮されたテクスチャの作成は、実際にはそれほど難しくはなく、IDirectDrawSurface7::Blt メソッドによって変換することができる。上級の開発者は、おそらく各自の必要性に応じた専用ツールを作成するものと考えられるが、このツールは、以下のような便利な基本的機能を提供する。

  • BMP ファイルおよび DDS ファイル を開く (DDS ファイル フォーマットの説明については、ユーザーズ ガイドの対応するトピックを参照すること)。
  • BMP ファイルをアルファ チャネルとして開く。
  • テクスチャを DDS フォーマットで保存する。
  • 5 種類すべての DXTn 圧縮フォーマットへの変換をサポートする。
  • ミップマップの生成をサポートする (ボックス フィルタ使用)。
  • グレースケール イメージとして、またはユーザー選択可能なバックグラウンド カラーを使用して、アルファ チャネルをビジュアル化できる。
  • フォーマットによるイメージ品質の相違を簡単にビジュアル比較できる。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\DXTex

実行可能ファイル :(SDK ルート)\Bin\DxUtils\Dxtex.exe

ユーザーズ ガイド

DirectX Texture ツールは、マルチドキュメント インターフェイスを使用する。テクスチャ マップはそれぞれドキュメントであり、複数のドキュメントを同時に開くことができる。

開いているドキュメントごとに、テクスチャを 1 つまたは 2 つのフォーマットで保持することができる。たとえば、32 ビット ARGB テクスチャを自動的に作成する BMP ファイルをインポートし、そのテクスチャを DXT1 フォーマットに変換することが可能である。ドキュメントには、両方のフォーマットでイメージが記憶され、ユーザーはウィンドウ内でクリックするか、または [View] メニューから [Original] または [New] を選択することによって、フォーマットの異なるイメージをフリップすることができる。これにより、イメージの圧縮によるアーティファクトが見つかりやすくなり、イメージの質を低下させずに、異なる圧縮フォーマットを試すことができる。

このテクニックを使用せずに ARGB を DXT1 に変換した場合、1 ビットを除くすべてのアルファが失われる。そして DXT2 に変換したとしても、アルファ レベルは 2 つしか存在しないことになる。Direct Texture ツールのシステムでは、この 2 回目の変換は元の ARGB フォーマットから行われ、変換された DXT2 イメージには、DXT2 がサポートする 16 レベルのアルファがすべて含まれる。このイメージを保存すると、元のフォーマットは破棄されて新しいフォーマットのみが保存される。

このシステムには、いくつか注意すべき点がある。

  • ドキュメントが開かれてからフォーマットの変換がまったく要求されなかった場合、片方のフォーマットが「元の」フォーマットとなり、ドキュメントを保存するときにはそのフォーマットにイメージが書き込まれる。
  • ドキュメントが開かれてからフォーマットの変換が要求された場合、変換されたフォーマットが「新たな」フォーマットとなり、ドキュメントを保存するとそのフォーマットにイメージが書き込まれる。
  • 2 回目の変換が要求された場合、最初の変換で作成された「新しい」フォーマットが第 2 のフォーマットに置き換えられる。「元の」フォーマットは変更されない。
  • ミップマップの生成は、両方のフォーマットに同時に適用される。
  • 元のフォーマットに複数のミップマップがあり新しいフォーマットへの変換が要求された場合、新しいフォーマットにも自動的に複数のミップマップが存在することになる。

ミップマップを作成するには、[Format] メニューから [Generate MipMaps] を選択する。ソース イメージの高さおよび幅は、2 の累乗でなくてはならない。フィルタリングは、単純なボックス フィルタで実行される。つまり、最も近い 4 つのピクセルが平均化されて目的のピクセルが作成される。

DirectX Texture ツールは、テクスチャにおけるアルファを完全サポートする。BMP ファイルをインポートするとき、2 つのファイルが存在し、その片方のファイル名が「_a」で終わる場合 (例 tex.bmp および tex_a.bmp)、「_a」で終わるファイルがアルファ チャネルとしてロードされる。この 2 つ目の bmp の青のチャネルがアルファ チャネルに格納される。

ドキュメントを開いたのちは、[File] メニューの [Open As Alpha Channel] を使用して明示的に bmp ファイルをアルファ チャネルとしてロードできる。

アルファ チャネルを RGB チャネルなしで直接表示するには、[View] メニューから [Alpha Channel Only] を選択する。アルファ チャネルがグレースケール イメージとして表示される。アルファ チャネルがロードされていない場合、アルファ チャネルは全域にわたって 100 パーセントとなり [Alpha Channel Only] を選択するとイメージが白く塗りつぶされるので注意すること。

通常のビューではアルファ チャネルのエフェクトが目に見えるが、これは、ウィンドウがバックグラウンド カラーで塗りつぶされており、アルファ チャネルが 100 パーセント未満のテクスチャでは、そのカラーが透けて見えるからである。バックグラウンド カラーを変更するには、[View] メニューから [Change Background Color] を選択する。この選択を実行しても、テクスチャそのもの、またはファイルを保存するときに書き込まれるデータには影響しない。

DXT2 フォーマットおよび DXT4 フォーマットでは、あらかじめ計算されたアルファが使用される。つまり、サーフェスに格納される赤、緑、および青の値には、対応するアルファ値が既に乗算されている。DirectDraw では、あらかじめ計算されたアルファが含まれるサーフェスからあらかじめ計算されていないアルファが含まれるサーフェスにブリットすることはできない。したがって、処理によって (Alpha Channel として開く、DXT3 への変換 DXT5 への変換) は、DXT2 および DXT4 フォーマットでは実行できない。DXTn テクスチャをサポートしない Direct3D デバイス では、これらのフォーマットを使用したテクスチャをサポートすることは難しい。これは、DirectDraw ではこれらのフォーマットを従来のARGB サーフェスへもブリットを処理できないためである (ARGB サーフェスでもあらかじめ計算されたアルファが使用されている場合はブリットできるが、このような場合はまれである)。したがって、可能であれば DXT2 よりも DXT3 を、DXT4 よりも DXT5 を使用する方が簡単である。

コマンドライン オプションを使用して、入力ファイル、出力ファイル名、および処理オプションを DirectX Texture ツールに渡すことができる。出力ファイル名を指定すれば、その出力ファイルを書き込んだ後にプログラムが自動終了し、ユーザー インターフェイスは表示されない。

dxtex [infilename] [-a alphaname] [-m] [DXT1|DXT2|DXT3|DXT4|DXT5] [outfilename]
infilename
ロードするファイル名。.bmp または .dds ファイル。
-a alphaname
「-a」を指定した場合、次のパラメータがアルファ チャネルとしてロードする bmp ファイル名となる。アルファ ファイル名を指定しなかった場合、アプリケーションは infilename_a.bmp という名前のファイルを探し、そのファイルが存在すればそのファイルをアルファ チャネルとして使用する。
-m
このオプションを指定した場合、ミップマップが生成される。
DXT1 | DXT2 | DXT3 | DXT4 | DXT5
圧縮フォーマットを指定する。フォーマットを指定しなかった場合、イメージは ARGB-8888 になる。
outfilename
転送先ファイル名を指定する。転送先を指定しなかった場合、ユーザー インターフェイスによって現在のファイルと要求されている処理が表示される。outfilename を指定した場合、処理されたファイルを保存した後でユーザー インターフェイスを提示せずにアプリケーションが終了する。

参照

DDS ファイル フォーマットの詳細情報については、「Compress サンプル」を参照すること。


KillHelp

説明

KillHelp は Ddhelp.exe をシャットダウンし、シャットダウンされた Ddhelp.exe は Ddraw.dll をメモリからアンロードする。

パス

実行可能ファイル :(SDK ルート)\Bin\DXUtils\Killhelp.exe

ユーザーズ ガイド

このプログラムは、デバイス ドライバ開発者専用である。

DirectDraw アプリケーションによって Ddraw.dll が初めてロードされると、その Ddraw.dll が Ddhelp.exe をロードする。Ddhelp.exe によって、DirectDraw は適切なスクリーン解像度をリストアし、アプリケーションが失敗した場合でもその他のクリーンアップ タスクを実行することができる。KillHelp は、システムを再スタートせずに Ddraw.dll、および Ddhelp.exe をメモリから削除する唯一の方法である。


DirectDraw C/C++ サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

ここでは、主に DirectDraw コンポーネントを示すことを意図している、DirectX SDK 内のサンプル アプリケーションの要約を提供する。以下のサンプル プログラムが含まれている。

  • DDEnum サンプル
  • DDEx1 サンプル
  • DDEx2 サンプル
  • DDEx3 サンプル
  • DDEx4 サンプル
  • DDEx5 サンプル
  • DDOverlay サンプル
  • Font サンプル
  • FSWindow サンプル
  • ModeTest サンプル
  • Mosquito サンプル
  • Multimon サンプル
  • Space Donuts サンプル
  • Stretch サンプル
  • Switcher サンプル
  • Wormhole サンプル

DirectX サンプルには、Microsoft® Visual C++® プロジェクト ワークスペース ファイルが含まれるが、正しくコンパイルするには、開発環境に他の設定が必要となる。詳細情報については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。


DDEnum サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、現在の DirectDraw デバイスの列挙方法と、IDirectDraw7::GetDeviceIdentifier メソッドを使用して情報を取得する方法について示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\DDEnum

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\DDEnum.exe

ユーザーズ ガイド

このユーザー インターフェイスは単純なダイアログ ボックスである。2 つのボタン [Prev] および [Next] ボタンにより、列挙された前のデバイスや次のデバイスの情報を表示する。アプリケーションを終了するには、[Close] ボタンをクリックする。


DDEx1 サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

DDEx1 では、DirectDraw アプリケーションを初期化し実行するのに必要なタスクを示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Ddex1

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Ddex1.exe

ユーザーズ ガイド

DDEx1 では、ユーザー入力の必要はない。プログラムを終了するには、F12 キーまたは ESC キーを押す。

プログラミング上の注意

このプログラムでは、DirectDraw の初期化方法および DirectDraw サーフェスの作成方法を示す。バック バッファを作成し、フロントおよびバック バッファの内容を交互に表示するページ フリッピングを使用する。また、他のテクニックとしてカラー フィルと、DirectDraw サーフェスの GDI 関数の使用について示す。


DDEx2 サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

DDEx2 は、ビットマップを追加した DDEx1 プログラムの拡張である。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Ddex2

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Ddex2.exe

ユーザーズ ガイド

DDEx2 では、ユーザー入力の必要はない。プログラムを終了するには、F12 キーまたは ESC キーを押す。

プログラミング上の注意

DDEx2 では、パレット化ビデオ モードの設定方法について示す。DDutil.cpp のルーチンはビットマップ ファイルをロードし、DirectDraw サーフェスにそのビットマップをコピーする。


DDEx3 サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

DDEx3 プログラムは、DDEx2 の拡張である。この例では、オフスクリーン サーフェスの使用について示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Ddex3

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Ddex3.exe

ユーザーズ ガイド

DDEx3 では、ユーザー入力の必要はない。プログラムを終了するには、F12 キーまたは ESC キーを押す。

このプログラムでは、少なくとも 1.2 MB のビデオ RAM が必要である。

プログラミング上の注意

フロントおよびバック バッファ以外に、このプログラムでは 2 つのオフスクリーン サーフェスを作成し、作成したオフスクリーン サーフェスにビットマップをロードする。オフスクリーン サーフェスの内容をバック バッファにコピーするには、IDirectDrawSurface7::BltFast メソッドを呼び出す。このバック バッファは、フレームごとにソース サーフェスを切り替える。バック バッファにビットマップをブリットした後、DDEx3 ではフロントおよびバック バッファにフリップする。


DDEx4 サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

DDEx4 プログラムは、DDEx3の拡張である。DDEx4 では、簡単なアニメーション テクニックを示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Ddex4

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Ddex4.exe

ユーザーズ ガイド

DDEx4 では、ユーザー入力の必要はない。プログラムを終了するには、F12 キーまたは ESC キーを押す。

このプログラムでは、少なくとも 1.2 MB のビデオ RAM が必要である。

プログラミング上の注意

DDEx3 とは異なり、DDEx4 プログラムでは単に 1 つのオフスクリーン サーフェスを作成する。そして、一連のアニメーション イメージを含むビットマップをこのサーフェスにロードする。アニメーションを作成するには、オフスクリーン サーフェスの部分をバック バッファにブリットし、フロントおよびバック バッファにフリップする。

ブリット ルーチンでは、透過型バックグラウンドでスプライトを作成する転送元カラー キーの使用を示す。


DDEx5 サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

DDEx5 プログラムは、DDEx4の拡張である。このプログラムでは、簡単なパレット操作を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Ddex5

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Ddex5.exe

ユーザーズ ガイド

DDEx4 では、ユーザー入力の必要はない。プログラムを終了するには、F12 キーまたは ESC キーを押す。

このプログラムでは、少なくとも 1.2 MB のビデオ RAM が必要である。

プログラミング上の注意

このプログラムでは IDirectDrawPalette::GetEntries を使用してパレットを読み込み、エントリの変更を行った後で、IDirectDrawPalette::SetEntries を使用してパレットを更新する。


DDOverlay サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプル アプリケーションでは、DirectDraw ウィンドウ アプリケーションにおけるオーバーレイの使用を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\DDovrly

可能実行ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Ddovrly.exe

ユーザーズ ガイド

プログラムを実行するには、オーバーレイをサポートするハードウェアが必要となる。

移動、サイズ変更、ウィンドウの縮小とリストアを試してみること。プログラムを終了するには、ALT+F4 キーを押すか、[Close] ボタンをクリックする。

プログラミング上の注意

このプログラムではオーバーレイ サポートをチェックし、オーバーレイ サーフェスへビットマップをロードし、Windows メッセージに応じてオーバーレイ サーフェスからウィンドウを更新する。


Font サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプル プログラムでは、GDI フォントから生成されたテキストを使用して、ビデオ メモリを直接ロックしアクセスする方法を示す。テキストを DirectDrawSurface に描画するには、ほかにもっと優れた方法がいくつかある。このサンプルのポイントは、直接ビデオ メモリをロックしてアクセスする方法を正しく示すことにある。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Font

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Font.exe

ユーザーズ ガイド

このプログラムは Arial フォントのテキスト文字列を繰り返し更新し、その文字列をスクリーンの周りでランダムに動かす。ユーザー入力の必要はない。終了するにはウィンドウを閉じる。

プログラミング上の注意

このプログラムではメモリ デバイス コンテキストと DIB セクションにフォントを作成し、それらを使用して GDI が描画したピクセルへのアクセスを取得する。その後、テキスト ビットマップが、直接メモリ コピーでプライマリ サーフェスに配置される。そして、透過的または非透過的にブリットされるオフスクリーン サーフェスの代わりに、簡単に動かすことができる。


FSWindow サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、アプリケーションで DirectDraw がフルスクリーン排他モードで実行されている間に、ダイアログ ボックスまたはウィンドウを呼び出す方法を示す。ウィンドウの内容からビットマップを作成し、そのビットマップをデバイスにブリットすれば、GDI 非対応のデバイスでも検出しサポートする。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\FSWindow

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\FSWindow.exe

ユーザーズ ガイド

複数のデバイスがある場合、サンプルの開始と共にダイアログ ボックスが表示され、そこからサンプルを実行するデバイスを選択することができる。その後はフルスクリーン排他モードに切り替わり、ダイアログ ボックスとマウス カーソルが表示される。

ダイアログ ボックスを閉じてマウス カーソルを隠蔽するには、[Cancel] または [OK] ボタンをクリックする。ダイアログ ボックスとマウス カーソルをもう一度表示するには、F1 キーを押す。ダイアログ ボックスが表示されなくなったら、Esc キーを押してプログラムを終了する。

プログラミング上の注意

重要なコードの多くは、Fswindow.cpp ファイル内にある。

サンプルはダイナミック コンテンツ モードを使用し、ダイアログ ボックスが頻繁にリフレッシュされて、フォーカスがあるコントロールやエディット フィールドのテキストが表示されるスタティック コンテンツ モードは CPU の処理時間がより短く、たとえばヘルプ メッセージを表示するポップアップ ウィンドウに適している。

コンテンツ ウィンドウはどのような種類のウィンドウにもなれることを理解することが重要である。コンテンツ ウィンドウは、HTML Help ウィンドウや、初期化されたテキストを表示するリッチ エディット コントロールを備えたウィンドウにもなる。表示するウィンドウの形状に合わせて変化する複雑なクリップ領域があるため、ウィンドウには正方形のクリップ領域は必要ない。


ModeTest サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

この例は、IDirectDraw7::StartModeTest メソッドと IDirectDraw7::EvaluateMode メソッドの基本的な使用方法を示す。これらのメソッドを一緒に使用すれば、モニタをどんなディスプレイ モードとリフレッシュ レートでディスプレイ デバイスと接続すれば表示できるかをアプリケーションで調べることができる。アプリケーションは、高いリフレッシュ レートを使用したいときに、これらのメソッドを使用できる。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\ModeTest

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\ModeTest.exe

ユーザーズ ガイド

このユーザー インターフェイスは単純なダイアログ ボックスである。最初に DirectDraw ディスプレイ デバイスを選択する。次に左側のリスト ボックスから 1 つ以上のモードを選択し、[Test] をクリックする。ディスプレイ モードごとにテストが実行され、モードが正しく表示されているかどうかを指定できる。間違った場合は、[Reset] をクリックして再度テストする。アプリケーションを終了するには、[Close] をクリックする。

プログラミング上の注意

DirectDraw では、アプリケーションが渡したリストを元に、テストするモードのリストがセットアップされ、アプリケーションの制御によって、モードが順番にテストされる。

アプリケーションは IDirectDraw7::EvaluateMode を継続的に呼び出す。DirectDraw によってモードが設定される。アプリケーションで実行しなければならないのは、事前に協調レベルを設定すること、サーフェスのロスと現在のモードが正しく表示されているかどうかを尋ねるインターフェイスの描画を処理することだけである。DirectDraw が EvalulateMode から返す情報によって、アプリケーションは上記の設定を行う時期とテストの停止時期を知ることができる。

ユーザーがモードを承認すると、アプリケーションはフラグを EvaluateMode に渡し、DirectDraw はそのモードに適切のマークを付けて次の処理に進む。DirectDraw ではまた、時間が不足したと判断されて特定のモードのテストが中断されることがある。

DirectDraw では、自動化された手段によって得られる情報を活用してテストの処理ができるだけ短縮されるため、アプリケーションは関係のあるモードだけをテストすればよい。


Mosquito サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

このプログラムでは、オーバーレイを使用する DirectDraw アニメーションを示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Mosquito

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Mosquito.exe

ユーザーズ ガイド

Mosquito アプリケーションを実行するには、オーバーレイをサポートするディスプレイ アダプタが必要である。オーバーレイをサポートするコンピュータでは、このプログラムはスクリーン上を飛ぶ大きな蚊を作成する。ディスプレイ アダプタ カードがオーバーレイの転送先カラー キーイングをサポートしない場合、蚊の周りに荒れ模様の黒い矩形の背景が表示される。

カードには、その他の特定の解像度で十分なオーバーレイをサポートするものもある。カードが DirectDraw からオーバーレイをサポートするのに、Mosquito プログラムでオーバーレイの作成や表示に問題が生じる場合は、スクリーンを低解像度に切り替えたり、色深度を切り替えたり、アプリケーションを再スタートしてみること。

プログラミング上の注意

このプログラムでは複雑なオーバーレイ サーフェスを作成し、それをフリップしてアニメーションする。


Multimon サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

このプログラムでは、複数のモニタを利用するアプリケーションのプログラミングに使用できるテクニックをいくつか示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Multimon

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Multimon.exe

ユーザーズ ガイド

アプリケーションには、入力の必要はない。終了するには、任意の場所または Esc キーを押す。

プログラミング上の注意

GetMonitorInfo や MonitorFromRect といったマルチモニタ関数を Windows 95 で使用するため、Multimon.h. ファイルをインクルードすることができる。また、C ファイルまたは C++ ファイルの 1 つで COMPILE_MULTIMON_STUBS を定義してから Multimon.h をインクルードする必要がある。これにより、Windows 95 上で実行したときに、multimon 関数によって適切な値が返される。

DirectDraw デバイスを列挙するときは、DirectDrawEnumerate または DirectDrawEnumerateEx. のいずれかを使用することができる。DirectDrawEnumerateEx は、DirectX 5.0 およびそれ以降がインストールされている Windows 98 システム、DirectX 6.0 またはそれ以降がインストールされているその他のシステムで使用できる。

すべてのシステムに DirectDrawEnumerateEx が存在するとは限らないため、以前の DirectDraw では開発者が LoadLibrary と GetProcAddress を使用して DirectDrawEnumerateEx の有無をチェックしなければならないように設定されていた。DirectX 7.0 ではこのような制限がなくなり DirectDrawEnumerateEx を直接呼び出すことができるが、そうすると、DirectX 7.0 またはそれ以降がインストールされていない場合にプログラムを実行できなくなることに注意すること。このサンプルでは、DirectDrawEnumerateEx が利用できない場合の LoadLibrary/GetProcAddress テクニックの実行方法、および DirectDrawEnumerate の使用方法を示す。

フルスクリーンのマルチモニタ アプリケーションでは、フォーカス ウィンドウおよびデバイス ウィンドウの処理が必要となる。フォーカス ウィンドウは、ユーザー入力メッセージを受け取り、デバイス ウィンドウは各スクリーンをカバーする。このプログラムは、これらのウィンドウを適切に作成し割り当てるため IDirectDraw7::SetCooperativeLevel を呼び出す方法を示す。

スクリーンごとに専用の DirectDraw インターフェイスを取得するため、ある DirectDraw インターフェイスで作成された DirectDrawSurfaces を他の DirectDraw インターフェイスで使用することはできない。このため、複数モニタ上で使用されるグラフィックスを作成するには、追加のタスクが必要となる。

このサンプルでは 2 つのテクニックを紹介する。最適なパフォーマンスを得るには、ビデオ メモリ サーフェスを使用する必要がある。スクリーンごとに個別のビデオ メモリ DirectDrawSurface を作成しなければならない。システム メモリ サーフェスが必要とされる場合、または望ましい場合、スクリーンごとに個別の DirectDrawSurfaces を作成する必要があるが、同一のサーフェス データ メモリをポイントするように構成することができる。The IDirectDrawSurface7::SetSurfaceDesc メソッドは、この操作に使用できる。これを実行してもパフォーマンスに影響はないが、不必要なシステム メモリの消費を防止することができる。

IDirectDrawSurface7::Blt の呼び出しは、転送先サーフェスの境界の外側でデータを書き込みを行うと失敗するのが普通である。これを防止するには、転送先にクリッパー オブジェクトを付加する。このサンプルでは、各スクリーンのクリッパーを作成してフロント バッファとバック バッファに付加し、スプライト サーフェスをアプリケーションによって手動でクリップしなくてもブリットできるようにする方法を示す。


Space Donuts サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

この簡単なゲームでは、DirectDraw、DirectInput、およびDirectSound の組み合わせ方法について示す。他の DirectX コンポーネントについても示すが、主に複数のスプライトをアニメーションする方法について示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Donuts

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Donuts.exe

ユーザーズ ガイド

デフォルトの入力はキーボードであるが、[Game] メニューからジョイスティックも選択できる。

このゲームで使用できるコマンドは、オープニング スクリーンでリストされる。すべての数字はテンキーパッドから入力する。"Joy" は、ジョイスティック ボタンに対応する。

キー | コマンド
Esc、F12 | 終了
4 | 左回転
6 | 右回転
5 (Joy 3) | 停止
8 | 前進
2 | 後退
7 (Joy 2) | 盾
Space キー (Joy 1) | 発射
Enter | ゲームの開始
F1 | 後続残像影響のオン/オフの切り替え
F3 | オーディオのオン/オフの切り替え
F5 | フレーム レート表示のオン/オフの切り替え
F10 | メイン メニュー

Space Donuts のデフォルト設定は、256 色で 640 × 480 である。デフォルト以外の解像度とピクセル深度は、コマンド ラインで指定できる。

このゲームでは、大文字と小文字の区別のある以下のコマンド ライン スイッチを使用する。

e | ハードウェア アクセラレータではなく、ソフトウェア エミュレーションを使用する。
t | 入力の必要のないテスト モード。
x | ストレス モード。設定する場合、停止することはできない。
S | サウンドのオン/オフを切り替える。

これらのスイッチの後に、x 解像度、y 解像度、およびピクセルごとのビットを表す 3 つのオプション数字が続くこともある。以下に例を示す。

donuts -S 800 600 16

プログラミング上の注意

このゲームでは、DirectDraw の多くの機能を示す。ドライバをサポートする場合、ハードウェア アクセラレータを利用する。

このプログラムでは、1 MB 未満のビデオ RAM が必要である。

このアプリケーションのサウンド コードは、DirectSound API を強調するように故意に設計されている。DirectSound API の効果的な使用方法を示しているわけではない。たとえば、スクリーン上の個々の項目記号は異なるサウンド バッファを使用する。Space Donuts では 70 以上のサウンドバッファ (複製も含む) を作成し、20 から 25 のサウンドバッファ間ではいつでも遊びが存在する可能性がある。

Dsutil.h および Dsutil.c (Sdk\Samples\Misc ディレクトリにある) のヘルプ関数を使用すると、サウンドを実装できる。これらの関数を使用すると、アプリケーションに素早くかつ簡単にサウンドを追加できる。


Stretch サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

Stretch サンプル アプリケーション プログラムでは、ビットマップ イメージをブリットする間の伸縮とクリッピングを示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Stretch

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Stretch.exe

ユーザーズ ガイド

Stretch は、8 bpp を使用するビデオ モードで実行しなくてはならない。他のビデオ モードでは正確に動作できない。

このプログラムは、クライアント ウィンドウで循環する赤のトーラスを表示する。[Rotation] メニューの [Stop]、[Slow]、および [Fast] オプションで循環速度を制御する。ウィンドウのサイズを変更するには、[Size] メニューから項目を選択するか、マウスでウィンドウのサイズを変更する。

プログラミング上の注意

Stretch プログラム ウィンドウのサイズを 1×1 以外に変更するときは常に、DirectDraw ブリット メソッドのイメージ伸縮能力を使用している。

プライマリ サーフェス用のクリッパーは、クライアント ウィンドウで設定される。クリッピングを示すには、Stretch プログラムのウィンドウ上に他のウィンドウを部分的に重ねる。Stretch がビットマップをブリットすると、他のウィンドウに位置するビットマップの部分がクリップされる。


Switcher サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、DirectDraw の標準協調レベルと排他協調レベル間の切り替え方法について示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Switcher

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Switcher.exe

ユーザーズ ガイド

ALT+ENTER キーを押すと、フルスクリーンとウィンドウ モード間を切り替えられる。プログラムを終了するには、ESC キーを押す。

プログラミング上の注意

一般的 (ウィンドウ) モードでは、このサンプルはクリッパーを割り当て、マウス カーソルを示し、他のアプリケーションのフォーカス消失によるウィンドウ移動、WM_PAINT メッセージ、および一時中断を処理する。排他 (フルスクリーン) モードでは、ブリットではなくページ フリッピングを使用して、場面を更新する。


Wormhole サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプル プログラムでは、パレット変更でアニメ エフェクトを作成する方法について示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Src\Wormhole

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DDraw\Bin\Wormhole.exe

ユーザーズ ガイド

プログラムを終了するには、F12 キーまたは Esc キーを押す。

プログラミング上の注意

4 色の 4×4 のディスプレイを考える。色を設定すると次のようになる。

ここで、各行のすべての色を右に循環できる。右側の 1 つは左へ覆う。

この循環を続けると、右に移動するアニメーションされた行を取得できる。同様にして、下に向かう行をアニメーションすることができる。

ここで、パレットを 16 色に拡張すると、同時に下と右への移動を結合できる。

右に移動

下に移動

右下に移動

ここで、これらの 4×4 ブロックの端と端にタイルを張り、上記のように循環させると、動く千鳥格子を取得できる。虫の掘った穴も同様に作成できるが、15×15 ブロック (225色) を使用して、平面でブロックの端と端にタイルを張る代わりに、虫の掘った穴の中央で 3-D 収束の内側にタイルを張る。

以下に示すコードで、前述の 15×15 グリッドを使用する 3-D の虫の掘った穴を生成できる。

// 全タスク
// r、θ、z を x、y、x に変換して、x、y を隠す
// ポイントをプロットする
// =-1.0+(log(2.0*j/DIVS) は、プロット用の math eqn を設定する行
// 自由に、他の関数も試すこと
// 柱座標。たとえば、z=f(r,theta)

#define STRETCH 25
#define PI      3.14159265358979323846
#define XCENTER 160
#define YCENTER 50
#define DIVS    1200
#define SPOKES  2400

void transarray(void)
    {
    float x,y,z;
    int i,j,color;
    for(j=1;j<DIVS+1;j++)
        for(i=0;i<SPOKES;i++)
            {
            z=-1.0+(log(2.0*j/DIVS));
            x=(320.0*j/DIVS*cos(2*PI*i/SPOKES));
            y=(240.0*j/DIVS*sin(2*PI*i/SPOKES));
            y=y-STRETCH*z;
            x+=XCENTER;
            y+=YCENTER;
            color=((i/8)%15)+15*((j/6)%15)+1;
            if ((x>=0)&&(x<=320)&&(y>=0)&&(y<=200))
                plot((int) x,(int) y,color);
            }
    }

ビットマップを DirectDraw サーフェスにロードした後にすべきことは、色を回転させ、虫の掘った穴を取得するだけである。


DirectDraw Visual Basic サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ サンプル」を参照すること。

[Visual Basic]

ここでは、DirectX for Visual Basic の DirectDraw コンポーネントを示すサンプル アプリケーションについて説明する。以下のサンプル プログラムが含まれている。

  • DDBlend サンプル
  • Fire サンプル

また、SDK には、5 つの簡単なチュートリアル アプリケーションも用意されている。これらのチュートリアルについては、「DirectDraw Visual Basic チュートリアル」を参照すること。


DDBlend サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ サンプル」を参照すること。

[Visual Basic]

説明

DDBlend サンプルでは、DirectDraw のフルスクリーン サポート、サーフェスの直接処理、および 8 ビット パレットのスクロールについて説明する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DDraw\Src\DDBlend

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DDraw\Bin\DDBlend.exe

ユーザーズ ガイド

渦巻きカラーの原点は、マウスを使って変更する。Insert キーを押すと、スクリーン解像度で前方に循環し、Delete キーを押すと後方に循環する。粒子の数を増やすには Home キーを押し、粒子を削除するには End キーを押す。不鮮明さを増加させるには PageUp キーを押し、低下させるには PageDown キーを押す。パレットを切り替えるには、スペース キーを押す。

プログラミング上の注意

DDBlend は、DirectX がサーフェス メモリに直接アクセスする方法を示すフルスクリーン サンプルである。また、8 ビット パレットのスクロールと高速ビデオ モードの切り替え方法も示す。


Fire サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectDraw C/C++ サンプル」を参照すること。

[Visual Basic]

説明

Fire サンプルでは、DirectDraw を使用してビデオ メモリを直接操作する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DDraw\Src\Fire

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DDraw\Bin\Fire.exe

ユーザーズ ガイド

ユーザー入力の必要はない。Esc キーを押すとプログラムが終了する。

プログラミング上の注意

このサンプルでは、DirectDrawSurface7.GetLockedArray を使用して、ディスプレイ メモリをバイトの配列 Pict に配置する (ここで個別に処理することができる)。


DirectInput

ここでは、Microsoft® DirectX® API (Application Programming Interface) の DirectInput® コンポーネントについて説明する。この情報は次のトピックに分かれている。

  • DirectInput について
  • DirectInput を使用する理由
  • DirectInput アーキテクチャ
  • DirectInput の要点
  • DirectInput チュートリアル
  • DirectInput リファレンス
  • DirectInput のツールとサンプル


DirectInput について

DirectInput は、マウス、キーボード、ジョイスティック、その他ゲーム コントローラの入力デバイスに加え、フォース フィードバック (入出力) デバイスもサポートする API である。


DirectInput を使用する理由

DirectInput は、Microsoft® Win32® API がサポートしていないデバイスに新しいサービスを提供することに加え、Microsoft® Windows® メッセージに依存せずに、ハードウェア ドライバと直接通信することにより、入力データへのアクセスを高速化している。

DirectInput を使うと、アプリケーションがバックグラウンドにある場合でも、入力デバイスに対するアクセス権を取得できる。また、フォース フィードバックのほか、あらゆるタイプの入力デバイスを完全にサポートしている。

DirectInput の拡張サービスと性能の改善により、DirectInput は、Windows で動作するゲーム、シミュレーション、およびその他のリアルタイム対話型アプリケーションに対する有用なツールとなっている。


DirectInput アーキテクチャ

ここでは、DirectInput の基本構造、および Windows オペレーティング システムと入力ハードウェアに連係した動作方法について説明する。ここで紹介する DirectInput の要素を実装する方法については、「DirectInput の要点」を参照すること。

  • DirectInput アーキテクチャの概要
  • Windows との統合
  • ヒューマン インターフェイス デバイス


DirectInput アーキテクチャの概要

[C++]

DirectInput の基本的アーキテクチャは、IDirectInput7 COM インターフェイスをサポートする DirectInput オブジェクト、およびデータを提供する入力デバイスごとのオブジェクトで構成される。各デバイスは、デバイス オブジェクト インスタンスまたは単なるデバイス オブジェクトを持つ。これらは、キー、ボタン、軸などの個別の制御手段またはスイッチである。

注 : オブジェクトという言葉は、コード オブジェクトを説明するのに使われることもあれば、入力デバイスでの個別の制御手段の 1 つを説明するのに使われることもある。ここでいうデバイス オブジェクトは、IDirectInputDevice7 インターフェイスをインスタンス化するコード オブジェクトではなく、入力デバイスの制御手段を表す。デバイス総体を表すコード オブジェクトは、DirectInputDevice オブジェクトと呼ぶ。

それぞれの DirectInputDevice オブジェクトは、マウス、キーボード、またはジョイスティックなどの入力デバイスを表す。タッチパッド付きキーボードなど、実際には異なる種類の入力デバイスを組み合わせた物理デバイスは、2 つまたはそれ以上の DirectInputDevice オブジェクトとして表される。フォース フィードバック デバイスは、入力と出力の両方を操作する 1 つのジョイスティック オブジェクトとして表される。

DirectInputDevice オブジェクトは、IDirectInputDevice7 インターフェイスをインスタンス化する。

アプリケーションは、デバイス上で使用可能なオブジェクトの数とタイプを IDirectInputDevice7::EnumObjects メソッドを使って確認する。個別のデバイス オブジェクトは、コード オブジェクトとしてカプセル化されずに、DIDEVICEOBJECTINSTANCE 構造体として記述される。

フォース フィードバック エフェクトは、IDirectInputEffect インターフェイスにより表される。このインターフェイスの各メソッドを使って、エフェクトの生成、変更、開始、および停止を行う。

すべての DirectInput インターフェイスは、ANSI 版と Unicode 版で使用できる。コンパイル時に「UNICODE」が定義されている場合は、UNICODE 版が使用される。

[Visual Basic]

DirectInput の基本的アーキテクチャは、アプリケーションが使用している入力デバイスごとに 1 つの DirectInput オブジェクトと DirectInputDevice オブジェクトで構成される。DirectInputDevice オブジェクトは、入力データを取得するのに使用される。

また、すべての使用可能なデバイスは、DirectInput により使用されているかどうかにかかわらず、DirectInputDeviceInstance オブジェクトで表現できる。このオブジェクトを使うことで、そのデバイスに関するさまざまな情報を取得できる。

各 DirectInputDevice オブジェクトは、マウス、キーボード、またはジョイスティックなどの入力デバイスを表す (このドキュメントでは、ジョイスティックという用語には、マウスやキーボード以外のあらゆるゲーム コントローラが含まれる)。タッチパッド付きキーボードなど、実際には異なる種類の入力デバイスを組み合わせた物理デバイスは、2 つまたはそれ以上の DirectInputDevice オブジェクトとして表される。フォースフィードバック デバイスは、入力と出力の両方を操作する 1 つのジョイスティック オブジェクトとして表される。

各デバイスは、キー、ボタン、軸などの個別の制御手段またはスイッチであるデバイス オブジェクトを持つ。各デバイス オブジェクトは、DirectInputDeviceObjectInstance クラスのインスタンスにより表現される。このメソッドを使うことで、そのデバイス オブジェクトに関する情報を取得できる (ただし、入力データは常に DirectInputDevice で取得する)。

注 : オブジェクトという言葉は、コード オブジェクトを説明するのに使われることもあれば、入力デバイスでの個別の制御手段の 1 つを説明するのに使われることもある。ここでいうデバイス オブジェクトは、DirectInputDevice オブジェクトではなく、入力デバイスの制御手段を表す。

デバイスとデバイス オブジェクトは列挙できる。列挙結果のコレクションは、DirectInputEnumDevices オブジェクトと DirectInputEnumDeviceObjects オブジェクトで表される。


Windows との統合

DirectInput はデバイス ドライバに直接働きかけて動作するので、マウス メッセージとキーボード メッセージは抑制または無視される。排他モードでマウスを使用すると、DirectInput はマウス メッセージを抑制する。その結果、Windows は標準カーソルを表示できなくなる。

DirectInput は、コントロール パネルでユーザーが行ったマウスとキーボードの設定も無視する。

キーボードの場合、文字反復の設定は、DirectInput では使用されない。バッファリング データを利用しているときは、DirectInput は、個々のキーの「押し」と「離し」を反復なしの 1 つのイベントとして解釈する。直接データを利用しているときは、DirectInput が関与するのはキーの現在の物理的状態のみであり、Windows で解釈されるキーボード イベントには関与しない。

マウスの場合、DirectInput は加速値やボタン機能の入れ替えなどのコントロール パネルの設定を無視する。また、DirectInput は直接マウス ドライバに作用し、ウィンドウ表示アプリケーションに対してマウス データを解釈する Windows サブシステムをバイパスする。

注 : ドライバ自体の設定は、DirectInput により認識される。たとえば、ユーザーが 3 つボタンのマウスを持っていて、ドライバ ユーティリティ ソフトウェアを使って中央のボタンにダブルクリックのショートカットを割り当てると、DirectInput は、中央のボタンの 1 回のクリックを主ボタンの 2 回のクリックとして報告する。

ジョイスティックやその他のゲーム デバイスの場合、DirectInput は、コントロール パネルでユーザーが設定したキャリブレーションを使用する。


ヒューマン インターフェイス デバイス

ヒューマン インターフェイス デバイス (HID) は、標準の USB (Universal Serial Bus) 規格に属するクラスである。DirectInput は、HID に準拠したデバイスを完全にサポートする。

HID デバイスから入手できるデータは、実質上、従来のデバイスから入手できるデータと同じである。さらに、HID デバイスは、出力を受け入れることができる。たとえば、キーボードの LED のオン/オフを切り替えることができる。

HID デバイスを問い合わせることにより、DirectInput はその "利用ページ" と "処理方法" を確認できる。デバイスのタイプとサブタイプについての情報を提供する事前定義されたコードがある。

HID コントロールは、"コレクション" に分類される。コレクションは入れ子構造にすることができる。

HID の詳細については、http://www.usb.org を参照すること。


DirectInput の要点

ここでは、DirectInput の概念とコンポーネントについて具体的な例を交えて紹介し、DirectInput システムをアプリケーションに実装するのに必要な情報を提供する。より幅広い概要については、「DirectInput アーキテクチャ」を参照すること。

以下のテーマについて解説する。

  • DirectInput の作成
  • DirectInput デバイスの列挙
  • DirectInput デバイス
  • DirectInput デバイス データ
  • フォース フィードバック
  • 前のバージョンの DirectInput の設計


DirectInput の作成

[C++]

DirectInput アプリケーションでは、必ず最初に IDirectInput7 インターフェイスを取得する。これを最も簡単に行う方法は、DirectInputCreateEx 関数を呼び出すことである。

単一の DirectInput オブジェクトを作成し、アプリケーションが終了するまで解放するべきではない。

[Visual Basic]

DirectInput アプリケーションでは、必ず最初に IDirectInput7 オブジェクトを作成する。これを行うには、DirectX7.DirectInputCreate メソッドを使用する。

単一の DirectInput オブジェクトを作成し、アプリケーションが終了するまで解放するべきではない。


DirectInput デバイスの列挙

DirectInput は、すべての使用可能な入力デバイスをシステムに問い合わせ、それらが接続されているかどうかを判定し、それらのデバイスに関する情報を返すことができる。このプロセスを列挙と呼ぶ。

[C++]

標準のキーボードやマウス、またはその両方だけをアプリケーションで使っているなら、使用可能な入力デバイスを列挙する必要はない。「DirectInput デバイスの作成」で説明するように、IDirectInput7::CreateDeviceEx メソッドを使用するときは、事前定義されたグローバル変数を使用できる。

ほかのすべての入力デバイス、および複数のキーボードまたはマウスを使用するシステムに関しては、DirectInputDevice オブジェクトを作成できるように、IDirectInput7::EnumDevices を呼び出して、少なくともインスタンス GUID (Globally Unique IDentifier) を取得する必要がある。列挙して、使用可能なデバイスをユーザーが選択できるようにすることもできる。

以下は、IDirectInput7::EnumDevices メソッド実装の例である。

/* lpdi は、有効な IDirectInput7 インターフェイス ポインタである。*/

GUID       KeyboardGUID = GUID_SysKeyboard;

lpdi->EnumDevices(DIDEVTYPE_KEYBOARD,
DIEnumDevicesCallback,
&KeyboardGUID,
DIEDFL_ATTACHEDONLY);

1 番目のパラメータは、列挙すべきデバイスのタイプを指定する。タイプに関係なくすべてのデバイスを列挙したければ、NULL とする。それ以外は、DIDEVICEINSTANCE のリファレンスに説明のある DIDEVTYPE_* 値の 1 つを指定する。

2 番目のパラメータは、列挙された各デバイスに対して一度ずつ呼び出されるコールバック関数へのポインタである。この関数は、どのような名前でもよいが、ここではプレースホルダ名の DIEnumDevicesCallback を使用する。

EnumDevices メソッドの 3 番目のパラメータは、コールバック関数に渡す任意の 32 ビットの値である。この例では、GUID 型の変数へのポインタであり、コールバック関数がキーボード インスタンス GUID を割り当てることができるように渡される。

4 番目のパラメータは、列挙対象が全デバイスか、またはアタッチされているデバイスのみ (DIEDFL_ALLDEVICES または DIEDFL_ATTACHEDONLY) かを指定するフラグである。

アプリケーションが複数の入力デバイスを使用している場合、列挙されたとおりにデバイスを初期化するには、コールバック関数を使用するのが適している (例については、「チュートリアル 3 : ジョイスティックの使用」を参照すること)。デバイスのインスタンス GUID をコールバック関数から取得する。ここでは、デバイスの特定のサブタイプを検索したり、デバイス名をリストボックスに追加したりするなど、別の処理を実行することもできる。

以下のコードは、拡張キーボードの存在をチェックし、見つかったら列挙を停止するコードの例である。見つかったキーボードのインスタンス GUID を KeyboardGUID 変数 (前の例の EnumDevices の呼び出しで pvRef として渡される) に割り当てる。この変数は、次に IDirectInput7::CreateDeviceEx を呼び出す際に使用できる。

BOOL          hasEnhanced;

BOOL CALLBACK DIEnumKbdCallback(LPCDIDEVICEINSTANCE lpddi,
                            LPVOID pvRef)
{
  *(GUID*) pvRef = lpddi->guidInstance;
  if (GET_DIDEVICE_SUBTYPE(lpddi->dwDevType) ==
                       DIDEVTYPEKEYBOARD_PCENH)
  {
    hasEnhanced = TRUE;
    return DIENUM_STOP;
  }
  return DIENUM_CONTINUE;
} // コールバックの終了。

1 番目のパラメータは、デバイスの情報を格納する構造体を指す。この構造体は、DirectInput が自動的に作成する。

2 番目のパラメータは、EnumDevices から渡されたデータを指す。この場合は、変数 KeyboardGUID へのポインタである。この変数には当初、デフォルト値が割り当てられているが、デバイスが列挙されるたびに、新しい値が割り当てられる。単一のキーボードに対してどのインスタンス GUID を使用するかは実際には重要でないが、上記のコードは、コールバック関数からインスタンス GUID を取得する技法を具体的に示している。

この場合の戻り値は、検索対象のデバイスが見つかれば列挙を停止し、そうでなければ続行することを示す。列挙は、全デバイスの列挙が終了すると直ちに自動的に停止する。

[Visual Basic]

標準のキーボードやマウス、またはその両方だけをアプリケーションで使っているなら、使用可能な入力デバイスを列挙する必要はない。「DirectInput デバイスの作成」で説明するように、DirectInput.CreateDevice メソッドを呼び出すときは、事前定義された GUID エイリアスを使用できる。

ほかのすべての入力デバイス、および複数のキーボードまたはマウスを使用するシステムに関しては、DirectInput.GetDIEnumDevices を呼び出して、使用可能なデバイスのコレクションを作成する。このメソッドは、デバイスのコレクションを表す DirectInputEnumDevices オブジェクトを返す。コレクション内の各デバイスは、DirectInputEnumDevices.GetItem メソッドを使用することにより、DirectInputDeviceInstance オブジェクトとして取得できる。

非標準デバイスに対して DirectInputDevice オブジェクトを作成するには、前もって DirectInputDeviceInstance.GetGuidInstance を呼び出すことにより、少なくともそのデバイスの GUID を取得する必要がある。デバイスを列挙して、特定のタイプやサブタイプを検索したり (DirectInputDeviceInstance.GetDevType を使用)、ユーザーがゲーム コントローラを選択できるようにリストボックスに代入したりすることもできる。

特定の能力を持つデバイスを検索することもできる。これを行うには、候補となるデバイスのそれぞれについて DirectInputDevice オブジェクトを作成し、DirectInputDevice.GetCapabilities メソッドを使って詳細機能を調査する必要がある。


DirectInput デバイス

ここでは、マウス、キーボード、ジョイスティックなどのデバイスを表すコード オブジェクトについて記述する。以下のトピックについて説明する。

  • デバイスのセットアップ
  • DirectInput デバイスの作成
  • デバイス能力
  • 協調レベル
  • デバイス オブジェクトの列挙
  • デバイス データ形式
  • デバイス プロパティ
  • デバイスの取得
  • デバイス変更の認識

デバイスからのデータの取得および解釈の方法についての情報は、「DirectInput デバイス データ」を参照すること。


デバイスのセットアップ

アプリケーションは、入力が行われるデバイスごとにオブジェクトを作成しなければならない。そのデバイスが使用できるように、最低限でもデータ形式の設定やデバイスの取得などの準備もしなければならない。ほかにも、デバイスに関する情報の収集やデバイスのプロパティの変更など、独自のタスクを実行することもある。

以下のタスクは、セットアップ手順の一部である。手順の中には必須のものもあれば、デバイスの詳細情報を必要とする場合、あるいはデフォルト値を変更しなければならない場合に限り必要となるものもある。

  1. DirectInput デバイスを作成する (必須)。「DirectInput デバイスの作成」を参照。
  2. デバイス能力を取得する (オプション)。
  3. デバイスのキー、ボタンおよび軸を列挙する (オプション)。「デバイス オブジェクトの列挙」を参照。
  4. 協調レベルを設定する (推奨)。
  5. デバイスデータ形式を設定する (必須)。
  6. デバイス プロパティを設定する (バッファリング データを取得する予定ならば、少なくともバッファ サイズを設定しなければならない)。
  7. データを読み取る用意ができたら、デバイスを取得する (必須)。「デバイスの取得」を参照。


DirectInput デバイスの作成

デバイスから入力データを取得するには、まずそのデバイスを表すオブジェクトを作成しなければならない。

[C++]

IDirectInput7::CreateDeviceEx メソッドを使って、IDirectInputDevice7 インターフェイスへのポインタを取得する。その後、このインターフェイスのメソッドを使って、デバイスの操作とデータの取得を行う。

次のコードは、キーボード デバイスを作成する例である。lpdi は IDirectInput7 インターフェイスへのポインタである。

LPDIRECTINPUTDEVICE7  lpdiKeyboard;
lpdi->CreateDeviceEx(GUID_SysKeyboard, IID_IDirectInputDevice7,
(void**)&lpdiKeyboard, NULL);

IDirectInput7::CreateDeviceEx の最初のパラメータはインスタンス GUID であり、インターフェイスの作成対象デバイスのインスタンスを識別する。DirectInput には、事前定義された 2 つの GUID (GUID_SysMouse および GUID_SysKeyboard) があり、それぞれシステム マウスとシステム キーボードを表す。これらの識別子を CreateDeviceEx メソッドに渡すことができる。CreateDeviceEx メソッドのパラメータとして、グローバル変数の GUID_Joystick を使用してはならない。GUID_Joystick は製品 GUID であり、インスタンス GUID ではないからである。

注 : ワークステーションに 2 つ以上のマウスがある場合は、すべてのマウスが結合されてシステム デバイスを形成する。キーボードについても同様である。

DirectInput は、このほかにも主にテストに使用する事前定義された 4 つの GUID を用意している。これらは GUID_SysKeyboardEm、GUID_SysKeyboardEm2、GUID_SysMouseEm、および GUID_SysMouseEm2 である。この GUID の 1 つを CreateDeviceEx に渡すことで、列挙レイヤーを介して、システム キーボードやシステム マウスに対するレベル 1 またはレベル 2 のアクセス権が付与される。これらの GUID は、常にシステム マウスやシステム キーボードを表す。これらはGUID_SysKeyboard および GUID_SysMouse のエイリアスであり、DIEDFL_INCLUDEALIASES フラグが渡されなければ、IDirectInput7::EnumDevices では列挙されない。

システム マウスまたはシステム キーボード以外のデバイスの場合は、IDirectInput7::EnumDevices で返されるデバイスのインスタンス GUID を使用する。1 つのデバイスに対するインスタンス GUID は常に同一である。列挙したリストからユーザーに 1 つのデバイスを選択させ、その GUID を構成ファイルに保存しておくと、後のセッションでその GUID を再び使用することができる。

[Visual Basic]

DirectInput.CreateDevice メソッドを使って、DirectInputDevice オブジェクトを取得する。その後、このインターフェイスのメソッドを使って、デバイスの操作とデータの取得を行う。

次のコードは、キーボード デバイスを作成する例である。di は DirectInput オブジェクトである。

Dim diDev As DirectInputDevice
Set diDev = di.CreateDevice("GUID_SysKeyboard")

パラメータは GUID のエイリアスであり、インターフェイスの作成対象デバイスのインスタンスを識別する。DirectInput には、事前定義された 2 つの GUID (GUID_SysMouse および GUID_SysKeyboard) があり、それぞれシステム マウスとシステム キーボードを表す。これらの識別子を CreateDevice メソッドに渡すことができる。

注 : ワークステーションに 2 つ以上のマウスがある場合は、すべてのマウスが結合されてシステムデバイスを形成する。キーボードについても同様である。

システム マウスやシステム キーボード以外のデバイスの場合は、DirectInputDeviceInstance.GetGuidInstance から取得したデバイスのインスタンス GUID を使用する。1 つのデバイスに対するインスタンス GUID は常に同一である。列挙したリストからユーザーに 1 つのデバイスを選択させ、その GUID を構成ファイルに保存しておくと、後のセッションでその GUID を再び使用することができる。

次のサンプル コードは、アプリケーションがデバイスを列挙し、適切なデバイス diDevInstance を見つけたことを前提としている。このデバイスを DirectInputDevice として作成する。

Dim guid As String
guid = diDevInstance.GetGuidInstance
Set diDev = di.CreateDevice(guid)

DirectInputDeviceInstance オブジェクトの取得方法については、「DirectInput デバイスの列挙」を参照すること。


デバイス能力

デバイスからの入力を要求する前に、ユーザーがその能力をある程度知っておく必要がある。ジョイスティックに視点ハットが付いているか。マウスはユーザーのマシンに現在アタッチされているか。

[C++]

そうした疑問点は、IDirectInputDevice7::GetCapabilities メソッドを呼び出すことにより解決することができる。このメソッドは、能力に関するデータを DIDEVCAPS 構造体に返す。DirectX のほかの類似の構造体の場合と同様に、メソッドにこの構造体を渡す前に、dwSize メンバを初期化しておかなければならない。

注 : 処理速度やメモリ使用を最適化するために、より小さい DIDEVCAPS_DX3 構造体を利用することができる。

以下のコードは、マウスがアタッチされているかどうか、およびマウスが第 3 軸 (通常は、ホイール) を持っているかどうかをチェックする例である。

//  LPDIRECTINPUTDEVICE7  lpdiMouse;  // 以前に初期化済み

DIDEVCAPS DIMouseCaps;
HRESULT hr;
BOOLEAN    WheelAvailable;

DIMouseCaps.dwSize = sizeof(DIDEVCAPS);
hr = lpdiMouse->GetCapabilities(&DIMouseCaps);
WheelAvailable = ((DIMouseCaps.dwFlags & DIDC_ATTACHED)
&& (DIMouseCaps.dwAxes > 2));

あるボタンまたは軸が存在するかどうかをチェックするもう 1 つの方法は、そのオブジェクトに対して IDirectInputDevice7::GetObjectInfo を呼び出すことである。その呼び出しに対し DIERR_OBJECTNOTFOUND が返ってきた場合、オブジェクトは存在しない。以下のコードでは、第 3 軸ではないにしても z 軸が存在するかどうかを判断する。

DIDEVICEOBJECTINSTANCE didoi;

didoi.dwSize = sizeof(DIDEVICEOBJECTINSTANCE);
hr = lpdiMouse->GetObjectInfo(&didoi,DIMOFS_Z, DIPH_BYOFFSET);
WheelAvailable = SUCCEEDED(hr);
[Visual Basic]

そうした疑問点は、DirectInputDevice.GetCapabilities メソッドを呼び出すことにより解決することができる。このメソッドは、能力に関するデータを DIDEVCAPS 型に返す 。

以下のコードは、マウスがアタッチされているかどうか、およびマウスが第 3 軸 (通常は、ホイール) を持っているかどうかをチェックする例である。

' diMouse は、有効な DirectInputDevice オブジェクトである。*/

Dim WheelAvailable As Boolean
Dim dicaps as DIDEVCAPS

Call diDev.GetCapabilities(dicaps)
WheelAvailable = ((dicaps.lFlags And DIDC_ATTACHED) _
And (dicaps.lAxes > 2))

あるボタンまたは軸が存在するかどうかをチェックするもう 1 つの方法は、そのオブジェクトに対して DirectInputDevice.GetObjectInfo を呼び出すことである。その呼び出しに対し DIERR_NOTFOUND が返ってきた場合、オブジェクトは存在しない。以下のコードでは、第 3 軸ではないにしても z 軸が存在するかどうかを判断する。

Dim didoi As DirectInputDeviceObjectInstance
On Error GoTo NOTFOUND
Set didoi = diDev.GetObjectInfo(DIMOFS_Z, DIPH_BYOFFSET)
On Error GoTo 0
.
.
.
NOTFOUND:
If Err.Number = DIERR_NOTFOUND Then
MsgBox "No z-axis found."
End If


協調レベル

[C++]

デバイスの協調レベルは、アプリケーション間および Windows システムでデバイスを共有する方法を定義する。以下の例のように、協調レベルを設定するには IDirectInputDevice7::SetCooperativeLevel メソッドを使用する。

/* hwnd は、最上位ウィンドウのハンドルである。*/
lpdiDevice->SetCooperativeLevel(hwnd,
        DISCL_NONEXCLUSIVE | DISCL_FOREGROUND)

パラメータは、そのデバイスに関連付けられた最上位ウィンドウ (一般的には、アプリケーション ウィンドウ) のハンドルと、1 つまたは複数のフラグである。

[Visual Basic]

デバイスの協調レベルは、アプリケーション間および Windows システムでデバイスを共有する方法を定義する。以下の例のように、協調レベルを設定するには DirectInputDevice.SetCooperativeLevel メソッドを使用する。

diDevice.SetCooperativeLevel(hWnd,
        DISCL_NONEXCLUSIVE Or DISCL_FOREGROUND)

パラメータは、デバイスに関連する最上位ウィンドウ (一般的には、アプリケーション ウィンドウ) のハンドルと、1 つまたは複数のフラグである。フォームの hWnd プロパティは、そのフォームが表示されるまで有効にならない。アプリケーションのメイン フォームの Load メソッドで DirectInput デバイスを初期化している場合、協調レベルを設定する前に、Show メソッドを呼び出す必要がある。

注 : DirectInput にはデフォルト設定が用意されているが、協調レベルは、明示的に設定しなければならない。これは、DirectInput にウィンドウのハンドルを与えるための唯一の方法だからである。このハンドルがないと、DirectInput は、ジョイスティックの再キャリブレーションなど、ウィンドウ メッセージが必要な状況で反応することができなくなる。

有効なフラグの組み合わせを以下の表に示す。

フラグ | メモ
DISCL_NONEXCLUSIVE DISCL_BACKGROUND | デフォルト設定
DISCL_NONEXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_BACKGROUND | キーボードまたはマウスには無効

[C++]

キーボードの場合は、DISCL_NOWINKEY と DISCL_NONEXCLUSIVE を同時に使用することもできる。このフラグで Windows キーを無効にすることにより、ユーザーは不注意でアプリケーションを終了することがなくなる。排他モードでは、Windows キーは常に無効である。

協調レベルには 2 つの構成要素がある。デバイスをフォアグラウンドまたはバックグラウンドで使用するか、および排他または非排他に使用するかである。

フォアグラウンドとバックグラウンド

フォアグラウンド協調レベルは、アプリケーションがフォアグラウンドにある場合、すなわち、入力フォーカスを持つ場合に限り、入力デバイスが使用可能になることを意味する。アプリケーションがバックグラウンドに移ると、入力デバイスは自動的に解放されるか使用不可になる。

バックグラウンド協調レベルとは、実際には「フォアグラウンドとバックグラウンド」のことである。バックグラウンド協調レベルのデバイスは、アプリケーションからいつでも取得して使用できる。

通常は、フォアグラウンド アクセス権だけで十分なはずである。というのも、大半のアプリケーションにとって、ほかのプログラムがフォアグラウンドにある場合に発生する入力は重要でないからである。

アプリケーションの開発中に、条件付きコンパイルを使って、デバッグ用にバックグラウンド協調レベルを設定することは有用である。これにより、アプリケーションは、デバッグ環境への切り替えでバックグラウンドに移動するたびに、デバイスへのアクセスを失うことがなくなる。

排他と非排他

あるアプリケーションがデバイスを排他レベルで使用しているからといって、ほかのアプリケーションが同じデバイスからデータを取得できないということにはならない。「排他レベルで使用」とは、ほかのアプリケーションが同じデバイスを排他には取得できないということを意味する。

たとえばあるミュージック プレーヤー アプリケーションの場合、アプリケーションはバックグラウンドにあっても、ハンドヘルドのリモート コントロール デバイスから入力を受け付ける。ここで、同じリモート コントロール デバイスからの信号に応答して、映画を再生するアプリケーションを実行するとしよう。ユーザーが [Play] を押したら何が起こるだろうか。両方のプログラムが再生を開始することになる。このような結果をユーザーが望んでいるとは思えない。そうならないようにするには、各アプリケーションに DISCL_EXCLUSIVE フラグを設定し、一度にどちらかのプログラムしか実行できないようにする必要がある。

フォース フィードバック エフェクトを利用するには、アプリケーションはデバイスへの排他アクセスができなければならない。

Windows 自体には、マウスへの排他アクセスが必要である。なぜなら、アクティブでないウィンドウ上でのクリックなどのマウス イベントを使って、アプリケーションにデバイスを強制解放させることが可能であり、そのことが、入力バッファからのデータの喪失など、潜在的に有害な結果を生む可能性があるからである。このため、あるアプリケーションがマウスに対する排他アクセス権を持っていると、Windows には一切のアクセスが許されない。マウス メッセージは生成されない。さらなる副作用として、カーソルが消えることもある。

あるアプリケーションがキーボードに対する排他アクセス権を持っている場合、DirectInput は一切のキーボード メッセージを抑制する。ただし、Ctrl+Alt+Del キーおよび Windows 95 や Windows 98 での Alt+Tab キーは使用できる。


デバイス オブジェクトの列挙

デバイス上でどのボタンまたは軸が使用可能であるかを、アプリケーションが確認しなければならない場合がある。この確認を行うには、デバイスを列挙する場合とほぼ同じ方法でデバイス オブジェクトを列挙する。

[C++]

IDirectInputDevice7::EnumObjects の機能は、IDirectInputDevice7::GetCapabilities と重複するところがある。どちらのメソッドも、使用可能なボタンまたは軸がいくつあるかを確認するのに使用できる。しかし、EnumObjects は、特定のオブジェクトの存在をチェックするよりも、むしろ、使用可能なオブジェクトをすべてカタログ化することを目的としたメソッドである。たとえば、DirectX SDK のサンプル コード中の DirectInput QuickTest アプリケーションは、EnumObjects を使用して、選択したデバイスの [Object] ページ上にリストを登録する。

EnumObjects メソッドには、IDirectInput7::EnumDevices などのようにコールバック関数があって、各オブジェクトに対してほかの処理をさせることができる。たとえば、オブジェクトをリストに追加したり、ユーザー インターフェイス上に対応する項目を作成したりすることである。

以下のコードは、各オブジェクトの名前を抽出して、文字列リストまたは配列に追加できるようにする例である。この標準コールバックは、ドキュメントではプレースホルダ名 DIEnumDeviceObjectsCallback で表されているが、自由に名前を付けることができる。この関数は、列挙されるそれぞれオブジェクトに対して、一度ずつ呼び出されることに注意すること。

char szName[MAX_PATH];

BOOL CALLBACK DIEnumDeviceObjectsCallback(
                      LPCDIDEVICEOBJECTINSTANCE lpddoi,
                      LPVOID pvRef)
{
  lstrcpy(szName, lpddoi->tszName);
// szName をリストあるいは配列に追加する。
  .
  .
  .
return DIENUM_CONTINUE;
}

1 番目のパラメータは、オブジェクトの情報を格納する構造体へのポインタである。この構造体は、DirectInput により自動作成される。

2 番目のパラメータは、EnumObjects の 2 番目のパラメータと同等なデータに対するアプリケーション定義ポインタである。この例では、当パラメータは使用されていない。

この場合の戻り値は、列挙するオブジェクトが存在する限り列挙が続くことを示す。

以下のコードは、EnumObjects メソッドを呼び出し、コールバック関数を動作させる例である。

lpdiMouse->EnumObjects(DIEnumDeviceObjectsCallback,
                       NULL, DIDFT_ALL);

1 番目のパラメータは、コールバック関数のアドレスである。

2 番目のパラメータは、コールバック関数の中で、使用または変更したいデータへのポインタとして使用できる。この例では、このパラメータを使用していなので、NULL を渡している。

3 番目のパラメータは、列挙の中に含めるオブジェクトのタイプ (複数可) を示すフラグである。この例では、すべてのオブジェクトを列挙することになる。列挙の範囲を限定するには、IDirectInput7::EnumDevices にリストされるほかの DIDFT_* フラグを 1 つ以上使用すればよい

注 : DIDFT_* フラグの一部は、ほかのフラグを組み合わせたものである。たとえば、DIDFT_AXIS は、DIDFT_ABSAXIS | DIDFT_RELAXIS と同等である。

[Visual Basic]

DirectInputDevice.GetDeviceObjectsEnum を呼び出すことで、デバイス オブジェクトを列挙する。これにより、要求したパラメータに一致する使用可能なデバイス オブジェクトのコレクションを表す DirectInputEnumDeviceObjects クラスのインスタンスが返される。

以下のコードは、デバイス上の軸を列挙する例である。

' diDev は DirectInputDevice オブジェクトである。

Dim diEnumObjects As DirectInputEnumDeviceObjects
Set diEnumObjects = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

パラメータは、列挙の中に含めるオブジェクトのタイプ (複数可) を示すフラグである。

注 : CONST_DIDFTFLAGS フラグの一部は、ほかのフラグを組み合わせたものである。たとえば、DIDFT_AXIS は、DIDFT_ABSAXIS OR DIDFT_RELAXIS と同等である。

特定のデバイス オブジェクトに関する情報を取得するには、DirectInputDeviceObjectInstance オブジェクトの各メソッドを呼び出す。このオブジェクトは、DirectInputEnumDeviceObjects.GetItem を呼び出すことで取得される。利用可能なデバイスの情報には、デバイスの名前、タイプ、およびデータ構造体内でのオフセットなどがある。

以下のコードは、前例で列挙された軸の名前をリストする例である。

Dim diDevEnumObjects As DirectInputEnumDeviceObjects
Set diDevEnumObjects = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

Dim diDevObjInstance As DirectInputDeviceObjectInstance
Dim i As Integer
For i = 1 To diEnumObjects.GetCount
Set diDevObjInstance = diEnumObjects.GetItem(i)
Call List1.AddItem(diDevObjInstance.GetName)
Next i


デバイス データ形式

デバイスのデータ形式の設定は、デバイス取得およびデバイス使用を始める前に行う基本的な手順である。デバイスから直接データ (状態データ) を取得することを目的としていない場合でも、データ形式を設定しなければならない。DirectInput では多くのメソッドでデータ形式を使用し、特定のデバイス オブジェクトを識別する。

[C++]

デバイス オブジェクトが使用するデバイスとデータ配列の方法は、IDirectInputDevice7::SetDataFormat メソッドが DirectInput に対して指示する。

DIDATAFORMAT 構造体および DIOBJECTDATAFORMAT 構造体のリファレンス中の例には、非標準デバイスに対してカスタム データ形式を設定する方法が示されている。この設定手順は幸いにも、ジョイスティック、キーボード、およびマウスには不要である。DirectInput は、5 つのグローバル変数、すなわち c_dfDIJoystick、c_dfDIJoystick2、c_dfDIKeyboard、c_dfDIMouse、および c_dfDIMouse2 を提供している。これらの変数を SetDataFormat に渡してジョイスティック、キーボード、およびマウスに対する標準データ形式を作成することができる。

以下のサンプル コードで、lpdiMouse は、DirectInputDevice オブジェクトに対する初期化されたポインタである。

lpdiMouse->SetDataFormat(&c_dfDIMouse);

注 : 事前定義された DIDATAFORMAT グローバル変数は const 変数であるので、この中の dwFlags メンバを (たとえば、軸のプロパティを変更するために) 変更することはできない。プロパティを変更するには、データ形式を設定した後で、デバイスを取得する前に、IDirectInputDevice7::SetProperty を使用する。

[Visual Basic]

デバイス オブジェクトが使用するデバイスとデータ配列の方法は、DirectInputDevice.SetCommonDataFormat メソッドと DirectInputDevice.SetDataFormat メソッドが DirectInput に対して指示する。

マウス、キーボード、および DIJOYSTATE 型または DIJOYSTATE2 型で記述できる入力データを持つその他のゲーム コントローラなど、標準デバイスの場合、SetCommonDataFormat メソッドを呼び出して、CONST_DICOMMONDATAFORMATS 列挙から定数を渡すことにより、データ形式を設定できる。ほとんどのアプリケーションにとって、共通のデータ形式を使用することが好ましい。

特殊デバイスの場合は、データ形式の記述を SetDataFormat メソッドに渡す必要がある。以下のコードは、2 つの軸を持ちボタンを持たないデバイスに、データ形式を設定する例である。どちらの軸も、データとして Long を要求する。

Dim dx As New DirectX7
Dim di As DirectInput
Dim did As DirectInputDevice
Dim fD As DIDATAFORMAT
Dim fDA(1) As DIOBJECTDATAFORMAT

Private Sub Form_Load()
Set di = dx.DirectInputCreate()

Set did = di.CreateDevice("GUID_SysMouse")

fDA(0).lFlags = DIDOI_POLLED
fDA(0).lOfs = 0
fDA(0).lType = DIDFT_RELAXIS
fDA(0).strGuid = "GUID_XAxis"

fDA(1).lFlags = DIDOI_POLLED
fDA(1).lOfs = 4
fDA(1).lType = DIDFT_RELAXIS
fDA(1).strGuid = "GUID_YAxis"

fD.dataSize = 8
fD.lFlags = DIDF_RELAXIS
fD.lObjSize = 4
fD.numObjs = 2

did.SetDataFormat fD, fDA()

End Sub


デバイス プロパティ

DirectInput デバイスのプロパティには、データ バッファのサイズ、軸が返す値の範囲と細分性、軸データが相対か絶対か、およびジョイスティックの物理的位置と報告データ間の関係に影響するジョイスティック軸のデッド ゾーンと飽和がある。特殊デバイスは、これ以外のプロパティを持つこともある。

1 つの例外 (フォース フィードバック デバイスのゲイン プロパティ) を除いて、プロパティは、デバイスが解放された状態にある場合に限り変更することができる。

[C++]

IDirectInputDevice7::SetProperty メソッドまたは IDirectInputDevice7::GetProperty メソッドを呼び出す前に、DIPROPHEADER 構造体とデータの 1 つ以上の要素で構成されるプロパティ構造体を設定する必要がある。入力デバイスには多くのプロパティがあるので、SetProperty はこれらのプロパティを定義するあらゆる種類の構造体に対して機能できなくてはならない。DIPROPHEADER 構造体の目的は、プロパティ構造体のサイズとデータの解釈方法を定義することである。

DirectInput は、以下の事前定義されたプロパティ構造体を含む。

  • DIPROPDWORD は、バッファ サイズなど単一の値を要求するプロパティに対して、DIPROPHEADER 構造体と DWORD データ メンバを含む構造体を定義する。
  • DIPROPRANGE はプロパティ範囲に対するもので、2 つの値 (最大値と最小値) を要求する。DIPROPHEADER 構造体と 2 つの LONG データ メンバで構成される。
  • DIPROPGUIDANDPATH は、DirectInput でサポートされていない HID に対してアプリケーションが操作を実行できる、特殊なプロパティ構造体である。この構造体は、DIPROPHEADER 構造体と GUID、およびパスを表す Unicode 文字列で構成される。
  • DIPROPSTRING は、Unicode 文字列プロパティである。この構造体は、DIPROPHEADER 構造体と Unicode 文字列で構成される。

SetProperty の場合、プロパティ構造体のデータ メンバは、プログラマが設定する値である。GetProperty の場合は、現在の値がデータ メンバに返される。

GetProperty または SetProperty を呼び出す前に、DIPROPHEADER 構造体を以下の値で初期化しておかなければならない。

  • プロパティ構造体のサイズ
  • DIPROPHEADER 構造体自体のサイズ
  • オブジェクト識別子
  • オブジェクト識別子の解釈方法を指示する dwHow メンバ

デバイス全体からプロパティを取得したり設定したりする場合、オブジェクト識別子 dwObj は、ゼロであり、dwHow メンバは、DIPH_DEVICE である。1 つのデバイス オブジェクト (たとえば、特定の軸) に対してプロパティを設定または取得したい場合は、dwObj と dwHow の組み合わせ値により、そのオブジェクトが識別される。詳細については、「DIPROPHEADER 構造体」を参照すること。

プロパティ構造体の設定後、取得または変更したいプロパティの識別子と共に、構造体のヘッダーのアドレスを、GetProperty または SetProperty に渡す。

SetProperty および GetProperty に渡されるプロパティを識別するために、以下の値が使用される。詳細については、「IDirectInputDevice7::GetProperty」を参照すること。

  • DIPROP_BUFFERSIZE。「バッファリング データと直接データ」を参照すること。
  • DIPROP_AXISMODE。「相対座標と絶対座標」も参照すること。
  • DIPROP_CALIBRATIONMODE
  • DIPROP_GRANULARITY
  • DIPROP_FFGAIN
  • DIPROP_FFLOAD
  • DIPROP_AUTOCENTER
  • DIPROP_RANGE
  • DIPROP_DEADZONE
  • DIPROP_SATURATION

最後の 3 つのプロパティについての詳細は、「ジョイスティック軸データの解釈」も参照すること。

以下のサンプル コードでは、10 個のデータ項目を保持するようにデバイスのバッファ サイズを設定する。

DIPROPDWORD  dipdw;
HRESULT      hres;
dipdw.diph.dwSize = sizeof(DIPROPDWORD);
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipdw.diph.dwObj = 0;
dipdw.diph.dwHow = DIPH_DEVICE;
dipdw.dwData = 10;
hres = lpdiDevice->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph);
[Visual Basic]

DirectInputDevice.SetProperty メソッドまたは DirectInputDevice.GetProperty メソッドは、2 つのパラメータを取る。設定するプロパティを識別する文字列形式の GUID エイリアスと、Any 型のデータである。このデータは、次のいずれか 1 つの型で渡される。

  • DIPROPLONG は、バッファ サイズなど単一の値を要求するプロパティに対して使用される。このプロパティ データは、単一の Long 値で構成される。
  • DIPROPRANGE はプロパティ範囲に対するもので、2 つの値 (最大値と最小値) を要求する。このプロパティ データは、2 つの Long データ メンバで構成される。

SetProperty の場合、プロパティ型のデータ メンバは、プログラマが設定する値である。GetProperty の場合は、現在の値がデータ メンバに返される。

実際のプロパティ データに加えて、これら 2 つの型には、lHow、lObj、および lSize の 3 つのメンバが含まれる。

lHow と lObj の値は連係して機能する。lHow は、プロパティを設定または取得するデバイス オブジェクトを識別するのに使用されるシステムを表し、lObj はデバイス オブジェクトを識別する。

lHow が DIPH_BYID である場合、デバイス オブジェクトは、lObj の一意な数値識別子で表される。この ID は、デバイス オブジェクトを列挙した後に、DirectInputDeviceObjectInstance.GetType により返される値から抽出できる。

ほとんどのアプリケーションの場合、デバイス オブジェクトを識別する方法として比較的容易なのは、DirectInputDevice.SetCommonDataFormat または DirectInputDevice.SetDataFormat で確立されるデータ構造体内のオフセットを使用する方法である。この場合、lHow は DIPH_BYOFFSET であり、lObj はバイト単位のオフセットである。キーボード、マウス、および DIJOYSTATE 型のデータを受け取ることができる任意のゲーム コントローラの場合、デバイス オブジェクトは事前定義された定数で識別できる。「CONST_DIKEYFLAGS」、「CONST_DIMOUSEOFS」、および「CONST_DIJOYSTICKOFS」を参照すること。

lHow メンバも DIPH_DEVICE を含むことができる。つまり、プロパティの所属先は単一のデバイス オブジェクトではなく、そのデバイス全体である。バッファ サイズはそのようなプロパティの一例である。lHow が DIPH_DEVICE であれば、lObj はゼロである。

最後に、プロパティ タイプの lSize メンバは、そのタイプのサイズに初期化する必要がある。GetProperty や SetProperty は、渡されるプロパティのタイプを認識していないので、この手順は必ず実行しなければならない。

SetProperty および GetProperty に渡されるプロパティを識別するために、以下の文字列が使用される。詳細については、「DirectInputDevice.GetProperty」を参照すること。

  • DIPROP_AXISMODE。「相対座標と絶対座標」も参照すること。
  • DIPROP_BUFFERSIZE。「バッファリング データと直接データ」を参照すること。
  • DIPROP_DEADZONE
  • DIPROP_GRANULARITY
  • DIPROP_RANGE
  • DIPROP_SATURATION

無効ゾーン、範囲、および飽和値の詳細については、「ジョイスティック軸データの解釈」を参照すること。

以下のコードは、デバイスのバッファ サイズを設定する例である。

' diDev は、データ形式を設定済みの DirectInputDevice である。

Dim diProp As DIPROPLONG
diProp.lHow = DIPH_DEVICE
diProp.lObj = 0
diProp.lData = 10
diProp.lSize = Len(diProp)
Call diDev.SetProperty("DIPROP_BUFFERSIZE", diProp)


デバイスの取得

DirectInput デバイスの取得とは、アプリケーションにデバイスへのアクセスをさせることである。デバイスが取得されている限り、DirectInput は、アプリケーションがデバイスのデータを使用できるようにする。デバイスが取得されていない場合、デバイスの特性に対する操作はできるが、データは一切取得できない。

取得は永続するものではない。アプリケーションは、デバイスを何回でも取得し、解放することができる。

協調レベルによっては、アプリケーションがバックグラウンドに移行すると必ず自動的にデバイスが解放されることがある。マウスの場合、ユーザーがメニューをクリックすると自動的に解放される。クリックした時点で Windows がデバイスの制御を引き継ぐからである。

デバイス プロパティの変更に先立って、そのデバイスを解放する必要がある。唯一の例外として、フォース フィードバック デバイスは、取得状態にあってもゲインを変更できる。

取得の仕組みが必要な理由は、次の 2 つである。

第一に、DirectInput は、デバイスからのデータの流れがシステムにより中断されたときには、アプリケーションに通知できなければならない。たとえば、ユーザーが Alt+Tab を使用して別のアプリケーションに切り替え、切り替え後のアプリケーションで入力デバイスを使用した場合に、元のアプリケーションは、入力デバイスがもはや自身に属さず、バッファ状態が変化した可能性があることを知る必要がある。DISCL_FOREGROUND 協調レベルでのアプリケーションを観察してみよう。ユーザーが Shift キーを押す。Shift キーを押し続けている間に、別のアプリケーションに切り替える。その後、ユーザーは Shift キーを離し、元のアプリケーションに戻る。元のアプリケーションからみれば、Shift キーは依然として押されている状態である。取得の仕組みでは、元のアプリケーションに入力が終了したことを通知して、この状態から回復させることができる。

第二に、アプリケーションがデバイスのプロパティを変更できるので、保護がなければユーザーがデータを取得しようとするたびに、DirectInput がプロパティをチェックしなければならなくなる。これは、かなり非効率であろう。さらに悪いことには、バッファ サイズを変更している最中に、データ バッファにアクセスするハードウェア割り込みが発生する可能性がある。そうした理由で、DirectInput は、プロパティを変更する前に、アプリケーションに対してデバイスを解放するように要求する。デバイスを再取得すると、DirectInput はプロパティを確認して、デバイスからアプリケーションへの最適なデータ転送の方法を決定する。この処理は一度しか行われないので、データ取得の各メソッドを非常に高速にすることができる。

[C++]

デバイスを喪失する最も一般的な原因は、アプリケーションがバックグラウンドに移行することである。したがって、アプリケーションがアクティブになったときには常に、デバイスを再取得することが必要になる。しかし、起動時の WM_ACTIVATE ハンドラに依存するには注意が必要である。最初の WM_ACTIVATE メッセージが到着するのは、おそらくウィンドウの初期化中で、DirectInput のセットアップ前である。起動時にデバイスを確実に取得するには、デバイスが初期化されたらすぐに IDirectInputDevice7::Acquire を呼び出すようにする。

特に標準のキーボードやマウス以外のデバイスの場合、プログラム ウィンドウがアクティブになったときにデバイスを取得しても、デバイスが解放されるすべてのケースに対応できるとは限らない。アプリケーションがデバイスを不意に解放する場合もあるので、デバイスからデータを取得しようとする前に、取得状態を確認する仕組みが必要である。Scrawl サンプル アプリケーションでは、Scrawl_OnMouseInput 関数でこの確認を行っている。この関数では、DIERR_INPUTLOST エラーが、マウスを再取得するメッセージのトリガになる(「チュートリアル 2 : マウスの使用」も参照すること)。

[Visual Basic]

特に排他協調レベルを設定した場合は、アプリケーションがデバイスを不意に解放する場合もあるので、アプリケーションが確実に取得状態を追跡するようにする。データを取得しようとした後で、DIERR_INPUTLOST エラーが発生したかどうかをチェックするのも 1 つの方法である。このエラーが発生していると、デバイスが解放されていたことがわかる。アプリケーションがイベント通知に応じて入力を取得している場合、取得が喪失すると、イベントが信号を発する。

排他モードでデバイスを管理する方法の詳細については、「ScrawlB サンプル」を参照すること。

取得済みのデバイスを再取得しようとしても、害はまったくない。Acquire に対する冗長な呼び出しは無視され、デバイスは常時 Unacquire を 1 回呼び出すことで解放することができる。

[C++]

Windows は、アプリケーションがマウスを排他モードで使用しているときは、マウスにアクセスしない。Windows にマウスを使用させたい場合は、マウスを解放しなければならない。Scrawl サンプルの 1 つの例では、右ボタンのクリックに反応するために、マウスを解放し、Windows カーソルを同じ点に表示し、コンテキスト メニューをポップアップし、メニュー選択が行われるまで Windows が入力を処理するようにしている。

[Visual Basic]

Windows は、アプリケーションがマウスを排他モードで使用しているときは、マウスにアクセスしない。Windows にマウスを使用させたければ、マウスを解放しなければならない。ScrawlB サンプル の 1 つの例では、右ボタンのクリックに反応するために、マウスを解放し、Windows カーソルを同じ点に表示し、コンテキスト メニューをポップアップし、メニュー選択が行われるまで Windows が入力を処理するようにしている。


デバイス変更の認識

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

USB (Universal Serial Bus) デバイスは、システムを再起動しなくても装着や取り外しができるので、入力デバイスの構成の変化にアプリケーションが反応できるようにしなければならない。たとえば、コントローラをもう 1 台挿すことで、進行中のゲームに新たなプレーヤーが参加できるようにすることを考えてみる。

デバイスが変化するときにメッセージを受け取るには、まず、以下のサンプル コードのように、通知を受け取るように登録する必要がある。

PVOID hNotifyDevNode;

void RegisterForDevChange(HWND hDlg, PVOID *hNotifyDevNode)
{
DEV_BROADCAST_DEVICEINTERFACE *pFilterData =
(DEV_BROADCAST_DEVICEINTERFACE*)
_alloca(sizeof(DEV_BROADCAST_DEVICEINTERFACE));
ASSERT (pFilterData);

ZeroMemory(pFilterData, sizeof(DEV_BROADCAST_DEVICEINTERFACE));

pFilterData->dbcc_size = sizeof(DEV_BROADCAST_DEVICEINTERFACE);
pFilterData->dbcc_devicetype = DBT_DEVTYP_DEVICEINTERFACE;
pFilterData->dbcc_classguid  = GUID_CLASS_INPUT;

*hNotifyDevNode = RegisterDeviceNotification(hDlg, pFilterData,
            DEVICE_NOTIFY_WINDOW_HANDLE);
}

次に、以下の例のように、メイン ウィンドウ プロシージャで、デバイスがアタッチされたこと、デバイスがこれから取り外されること、デバイスが既に取り外されたことを通知するメッセージをチェックする。

MyWindowProc(HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
{
switch (nMsg)
    {
case WM_DEVICECHANGE:
        {
switch (wParam)
            {
case DBT_DEVICEARRIVAL:
// デバイスの到着を処理する
break;

case DBT_DEVICEQUERYREMOVE:
// デバイスの削除要求を処理する
break;

case DBT_DEVICEREMOVECOMPLETE:
// デバイスの削除を処理する
break;
            }
        }
.
.
.
    }
}

DBT_DEVICEARRIVAL イベントに応じて、IDirectInput7::FindDevice を使ってデバイスのインスタンス GUID を取得し、この値を IDirectInput7::CreateDeviceEx に渡す。

詳細については、Platform SDK に含まれるデバイス管理のトピックを参照すること。


DirectInput デバイス データ

ここでは、DirectInput デバイス データの取得に関する基本的な考え方をいくつか説明する。

  • バッファリング データと直接データ
  • タイム スタンプとシーケンス番号
  • ポーリングとイベント
  • 相対座標と絶対座標

マウス、キーボードおよびジョイスティック出力データの特定事項、および出力データについては、以下のトピックで詳述する。

  • マウス データ
  • キーボード データ
  • ジョイスティック データ
  • データ出力


バッファリング データと直接データ

DirectInput は、バッファリング データと直接データの 2 種類のデータを供給する。バッファリング データは、アプリケーションが取得するまで格納されているイベントのレコードである。直接データは、デバイスの現在の状態のスナップショットである。

直接データは、デバイスの現在の状態だけに関心のあるアプリケーションで使用することが考えられる。たとえば、ジョイスティックの現在位置と、1 つ以上のボタンの状態に反応するフライト コンバット シミュレーションなどである。バッファリング データは、状態よりもイベントを重要視する場合に選択するとよい。たとえば、マウスの動きやボタンのクリックに反応するアプリケーションなどである。両方のタイプのデータを使用することもできる。たとえば、ジョイスティック軸では直接データを取得して、ボタンではバッファリング データを取得する場合などである。

DirectX SDK で提供されている DirectInput QuickTest アプリケーションでは、デバイスの直接データとバッファリング データの両方を見ることができる。アプリケーション ウィンドウでデバイスを作成した後、[Mode] ページでそのプロパティを設定する。すると、[Data] ページの左側に直接データ、右側にバッファリング データが表示される。

[C++]

アプリケーションは、IDirectInputDevice7::GetDeviceState メソッドを呼び出すことで、直接データを取得する。名前が表すとおり、このメソッドはデバイスの現在の状態を返す。たとえば、各ボタンがアップ状態かダウン状態か、などである。このメソッドは、現在の状態と以前の状態を比較して得られる暗黙の情報を除いて、最後の呼び出し以降にデバイスに起きたイベントに関するデータは、まったく提供しない。GetDeviceState に対する最後の呼び出しから現在の呼び出しまでの間に、ユーザーがボタンを押したり離したりしていても、アプリケーションはそのことに関して何も認識しない。他方、ボタンを押したままにしていると、GetDeviceState は、ユーザーがボタンを離すまで「ボタン ダウン」を報告し続ける。

このデバイス状態の報告は、WM_LBUTTONDOWN のような一度限りのメッセージによる Windows のイベント報告とは異なり、Win32 の GetKeyboardState 関数の報告に類似している。GetDeviceState を使用してデバイスをポーリングする場合には、ボタン クリック、ダブルクリック、または単一のキー ストロークの区別をプログラムで判断しなければならず、また、アプリケーションがボタン ダウン状態またはキー ダウン状態に対し、不適切なタイミングで応答し続けることのないように適切に処理しなければならない。

バッファリング データの場合、イベントは、プログラムが処理を開始できる状態になるまで格納されている。ボタンやキーが押されたり、軸が移動されたりするたびに、そのイベントに対する情報がバッファ中の DIDEVICEOBJECTDATA 構造体に置かれる。バッファがオーバーフローすると、新しいデータは失われる。アプリケーションがバッファを読み出すには、IDirectInputDevice7::GetDeviceData を呼び出す。一度に任意の数の項目を読み出すことができる。

項目を読み出すと、通常は、バッファからその項目が消去されるが、消去無しピーキングも選択できる。

バッファリング データを取得するには、まず IDirectInputDevice7::SetProperty メソッドでバッファ サイズを設定する必要がある (「デバイス プロパティ」を参照すること)。バッファ サイズの設定は、デバイスを最初に取得する前に行う。効率上の理由から、デフォルトのバッファ サイズはゼロである。この値を変更しない限り、バッファリング データを取得することはできない。バッファ サイズはバイト単位やワード単位ではなく、デバイスのタイプに対応したデータの項目単位でカウントされる。

GetDeviceData メソッドを呼び出した後は、pdwInOut パラメータ値をチェックする必要がある。バッファから取り出される項目数は、この変数に返される。

注 : アナログ ジョイスティックなど、割り込みを生成しないデバイスの場合、IDirectInputDevice7::Poll メソッドが呼び出されるまで、DirectInput はいかなるデータも取得しない。詳細については、「ポーリングとイベント」を参照すること。

バッファリング データを取得する例については、IDirectInputDevice7::GetDeviceData を参照すること。

[Visual Basic]

アプリケーションは、以下のメソッドのいずれかを呼び出すことで、直接データを取得する。

  • DirectInputDevice.GetDeviceStateKeyboard。DIKEYBOARDSTATE 型のデータを取得するデバイスの場合 (これ以下の 3 つのメソッドについては、DirectInputDevice.SetCommonDataFormat を使ってデータ形式を設定する必要がある)。
  • DirectInputDevice.GetDeviceStateMouse。DIMOUSESTATE 型のデータを取得するデバイスの場合。
  • DirectInputDevice.GetDeviceStateJoystick。DIJOYSTATE 型のデータを取得するデバイスの場合。
  • DirectInputDevice.GetDeviceStateJoystick2。DIJOYSTATE2 型のデータを取得するデバイスの場合。
  • DirectInputDevice.GetDeviceState。DirectInputDevice.SetDataFormat を使ってカスタム データ形式を設定し、使用するデバイスの場合。

名前が表すとおり、これらの各メソッドはデバイスの現在の状態を返す。たとえば、各ボタンがアップ状態かダウン状態か、などである。このメソッドは、現在の状態と以前の状態を比較して得られる暗黙の情報を除いて、最後の呼び出し以降にデバイスに起きたイベントに関するデータは、まったく提供しない。各メソッドに対する最後の呼び出しから現在の呼び出しまでの間に、ユーザーがボタンを押したり離したりしていても、アプリケーションはそのことに関して何も認識しない。他方、ボタンを押したままにすると、メソッドは、ユーザーがボタンを離すまで「ボタン ダウン」を報告し続ける。

このデバイス状態の報告は、Click や Keydown のような一度限りのイベントによる Visual Basic のイベント報告とは異なっている。GetDeviceState メソッドのいずれかを使用してデバイスをポーリングする場合には、ボタン クリック、ダブルクリック、または単一のキー ストロークの区別をプログラムで判断しなければならず、また、アプリケーションがボタン ダウン状態またはキー ダウン状態に対し、不適切なタイミングで応答し続けることのないように適切に処理しなければならない。

バッファリング データの場合、イベントは、プログラムが処理を開始できる状態になるまで格納されている。ボタンやキーが押されたり、軸が移動されたりするたびに、そのイベントに対する情報がバッファ中の DIDEVICEOBJECTDATA 型に置かれる。アプリケーションがバッファを読み取るには、DirectInputDevice.GetDeviceData を呼び出す。一度に任意の数の項目を読み出すことができる。

項目を読み出すと、通常は、バッファからその項目が消去されるが、DIGDD_PEEK フラグを設定すると、削除せずに取得することも選択できる。

バッファリング データを取得するには、まず DirectInputDevice.SetProperty メソッドでバッファ サイズを設定する必要がある (「デバイス プロパティ」を参照すること)。バッファ サイズの設定は、デバイスを最初に取得する前に行う。効率上の理由から、デフォルトのバッファ サイズはゼロである。この値を変更しない限り、バッファリング データを取得することはできない。バッファ サイズはバイト単位やワード (WORD) 単位ではなく、デバイスのタイプに対応したデータの項目単位でカウントされる。

GetDeviceData の戻り値は、バッファから取得された項目数を示している。バッファがオーバーフローした場合、データは返されず、GetDeviceData はエラーを発生する。このエラーにより、アプリケーションが捕捉される。

注 : アナログ ジョイスティックなど、割り込みを生成しないデバイスの場合、DirectInputDevice.Poll メソッドを呼び出すまで、DirectInput はいかなるデータも取得しない。詳細については、「ポーリングとイベント」を参照すること。

参照

  • タイム スタンプとシーケンス番号
  • マウス データ
  • キーボード データ
  • ジョイスティック データ


タイム スタンプとシーケンス番号

[C++]

バッファリングされている DirectInput 入力データの場合 (「バッファリング データと直接データ」を参照)、各 DIDEVICEOBJECTDATA 構造体には、イベントのタイプとそれに関連付けられたデバイス オブジェクトだけでなく、タイム スタンプとシーケンス番号も格納される。

dwTimeStamp メンバは、イベントが発生したときのシステム時間をミリ秒単位で格納する。これは、Win32 GetTickCount 関数によって返される値と同じか、より精度が高い値である。

dwSequence メンバは、DirectInput が割り当てたシーケンス番号を格納する。DirectInput システムは、単一のシーケンス カウンタを保持している。このカウンタは、任意のデバイスで、バッファリングされるイベントが発生するたびに随時増加する。この番号を使って、異なるデバイスから発生するイベントを比較し、どちらが先かを確認することができる。DISEQUENCE_COMPARE マクロは、シーケンス カウンタの循環性を考慮している。

[Visual Basic]

バッファリングされている DirectInput 入力データの場合 (「バッファリング データと直接データ」を参照)、各 DIDEVICEOBJECTDATA 型には、イベントのタイプとそれに関連するデバイス オブジェクトだけでなく、タイム スタンプとシーケンス番号も格納される。

lTimeStamp メンバは、イベントが発生したときのシステム時間をミリ秒単位で格納する。これは、Win32 GetTickCount 関数によって返される値と同じか、より精度が高い値である。

lSequence メンバは、DirectInput が割り当てたシーケンス番号を格納する。DirectInput システムは、単一のシーケンス カウンタを保持している。このカウンタは、任意のデバイスで、バッファリングされるイベントが発生するたびに随時増加する。この番号を使って、異なるデバイスから発生するイベントを比較し、どちらが先かを確認することができる。

同時に発生するイベントには、同じシーケンス番号が割り当てられる。たとえば、マウスやジョイスティックを斜めに移動する場合の x 軸と y 軸の変化は、同じシーケンス番号を持つ。

注 : イベントは、常に、発生時間順にバッファに入れられるので、単一デバイスからのイベントを単に順序付けするだけなら、シーケンス番号をチェックする必要はない。


ポーリングとイベント

入力データが発生しているかどうかを確認するには、ポーリングとイベント通知という 2 つの方法がある。

デバイスのポーリングとは、デバイス オブジェクトの現在の状態を定期的に取得すること、またはイベント バッファの内容をチェックすることを意味する。ポーリングが使用されるのは通常、決してアイドルになることがなく、常にゲームの世界を更新、レンダリングするリアルタイム ゲームである。

[C++]

C++ アプリケーションでのポーリングは通常、メッセージ ループ内で行われる。

イベント通知は、Scrawl サンプルのように、何もしないで入力を待つようなアプリケーションに向いている。イベント通知を使用するには、Win32 CreateEvent 関数でスレッド同期オブジェクトをセットアップした後、イベントのハンドルを IDirectInputDevice7::SetEventNotification メソッドに渡すことによって、このイベントとデバイスを関係付ける。これで、デバイスの状態が変化するたびに、DirectInput によってイベントが通知される。アプリケーションは、WaitForSingleObject などの Win32 関数を使用して、イベントの通知を受け取った後、入力バッファをチェックして何のイベントかを確認し、応答することができる。サンプル コードについては、「Scrawl サンプル」および「IDirectInputDevice7::SetEventNotification」を参照すること。

ジョイスティックやほかのゲーム デバイス、またはこれらのデバイス上のオブジェクトのうちいくつかは、IDirectInputDevice7::Poll メソッドを呼び出すまで、ハードウェア割り込みを生成せず、いかなるデータも返さず、いかなるイベントも送信しない(このようなバックグラウンドでのポーリングを、ここで説明するアプリケーション ポーリングと混同しないこと。Poll メソッドは、データを一切取得しないが、データを使用可能にすることがある)。

データを取得しようとするたびに Poll メソッドを呼び出す必要があるかどうかを調べるには、まずデバイスのデータ形式を設定し、IDirectInputDevice7::GetCapabilities メソッドを呼び出して、DIDEVCAPS 構造体の DIDC_POLLEDDATAFORMAT フラグをチェックする。

DIDC_POLLEDDATAFORMAT フラグと DIDC_POLLEDDEVICE フラグを混同しないこと。後者は、デバイス上のオブジェクトのいずれかがポーリングを必要としているときに設定されるフラグである。次に、IDirectInputDevice7::GetObjectInfo メソッドを呼び出し、DIDEVICEOBJECTINSTANCE 構造体にある DIDOI_POLLED フラグをチェックすると、ポーリングを必要としているのが特定のオブジェクトであるかどうかを見分けることができる。

DIDC_POLLEDDEVICE フラグはデバイスの最悪の状態を表すのであって、デバイスの実際の状態を表すのではない。たとえば、ソフトウェア解像度調節付きの HID マウスの場合、解像度情報を読み取るためにポーリングを要求するので、DIDC_POLLEDDEVICE フラグが設定される。デバイスの標準ボタンと軸データ以外は必要ない場合、このような条件のもとでデバイスをポーリングすることは、無意味である。

ただし、IDirectInputDevice7::Poll メソッドを呼び出しても、入力デバイスに障害を与えることはない。この呼び出しが不要なときは、何のエフェクトも持たずにすぐに終了する。

[Visual Basic]

Visual Basic アプリケーションでは、ポーリングは通常、Sub Main プロシージャ内で行われる。

イベント通知は、ScrawlB サンプルのように、何もしないで入力を待つようなアプリケーションに向いている。イベント通知を使用するには、データを取得するフォームまたはモジュールに DirectXEvent を実装する。次に、DirectX7.CreateEvent を使ってイベント ハンドルを作成し、このハンドルを DirectInputDevice.SetEventNotification に渡す。これで、デバイスで入力イベントが発生すると必ず DirectXEvent.DXCallback メソッドが呼び出され、Sub Main 内と同様に、このメソッドの実装内で、デバイスの状態またはバッファリング データのどちらかを取得できる。

ジョイスティックやほかのゲームデバイス、またはこれらのデバイス上のオブジェクトのうちいくつかは、DirectInputDevice.Poll メソッドを呼び出すまで、ハードウェア割り込みを生成せず、いかなるデータも返さず、いかなるイベントも送信しない(このようなバックグラウンドでのポーリングを、ここで説明するアプリケーション ポーリングと混同しないこと。Poll メソッドは、データを一切取得しないが、データを使用可能にすることがある)。

データを取得しようとするたびに Poll メソッドを呼び出す必要があるかどうかを調べるには、まずデバイスのデータ形式を設定し、次に DirectInputDevice.GetCapabilities メソッドを呼び出して、DIDEVCAPS 型の DIDC_POLLEDDATAFORMAT フラグをチェックする。

DIDC_POLLEDDATAFORMAT フラグと DIDC_POLLEDDEVICE フラグを混同しないこと。後者は、デバイス上のオブジェクトのどれかがポーリングを必要としているときに設定されるフラグである。次に、IDirectInputDevice7::GetObjectInfo メソッドを呼び出して DirectInputDeviceObjectInstance オブジェクトを取得し、DirectInputDeviceObjectInstance.GetFlags により返される値中の DIDOI_POLLED フラグをチェックすると、ポーリングを必要としているのが特定のオブジェクトであるかどうかを見分けることができる。

DIDC_POLLEDDEVICE フラグはデバイスの最悪の状態を表すのであって、デバイスの実際の状態を表すのではない。たとえば、ソフトウェア解像度調節付きの HID マウスでは、解像度情報を読み取るためにポーリングを要求するので、DIDC_POLLEDDEVICE フラグが設定される。デバイスの標準ボタンと軸データ以外は必要ない場合は、このような条件のもとでデバイスをポーリングすることは、無意味である。

ただし、Poll メソッドを呼び出しても、入力デバイスに障害を与えることはない。この呼び出しが不要なときは、何のエフェクトも持たずにすぐに終了する。


相対座標と絶対座標

軸座標は、相対値として返される場合もある。すなわち、アプリケーションが前回デバイスの状態を取得してからの変化量、バッファリング入力の場合は、直前の項目がバッファに入れられてからの変化量である。

絶対軸座標とは、デバイスの取得以来、システムが返したすべての相対座標の連続合計のことである。すなわち、ある固定点に対する軸の位置を示す。

デフォルトでは、マウスの軸は相対座標であり、ジョイスティック軸は絶対座標で報告される。プロパティを設定することで、デバイスの座標システムを変更できる。詳細については、「デバイス プロパティ」を参照すること。


マウス データ

[C++]

データを取得するようにマウス デバイスを設定するには、パラメータとして c_dfDIMouse または c_dfDIMouse2 のグローバル変数を指定して、IDirectInputDevice7::SetDataFormat メソッドを呼び出す。5 つ以上のマウス ボタンをサポートする場合は、c_dfDIMouse2 を使用する。

フルスクリーン アプリケーションの性能を最大限発揮するには、協調レベルに DISCL_EXCLUSIVE | DISCL_FOREGROUND を設定する。排他を設定すると、Windows カーソルが消失する。DISCL_FOREGROUND を設定すると、デバッグ ウィンドウに切り替えたときに、アプリケーションがマウスへのアクセス権を失う。DISCL_BACKGROUND に変更すると、アプリケーションのパフォーマンスは犠牲になるが、アプリケーションのデバッグをより容易に行うことができるようになる。

[Visual Basic]

データを取得するようにマウス デバイスを設定するには、まずパラメータに DIFORMAT_MOUSE を指定して DirectInputDevice.SetCommonDataFormat メソッドを呼び出す。

フルスクリーン アプリケーションの性能を最大にするには、協調レベルに DISCL_EXCLUSIVE | DISCL_FOREGROUND を設定する。排他設定では、Windows カーソルが消失する。DISCL_FOREGROUND を設定すると、Visual Basic 開発環境に切り替えたときに、アプリケーションがマウスへのアクセス権を失う。DISCL_BACKGROUND に変更すると、アプリケーションのパフォーマンスは犠牲になるが、アプリケーションのデバッグをより容易に行うことができるようになる。

以下のトピックには、マウスの直接データとバッファリング データの取得、解釈の詳細の説明がある。

  • マウスの直接データ
  • マウスのバッファリング データ
  • マウス軸データの解釈
  • 消失したマウス入力の確認

参照

デバイス データ形式、協調レベル


マウスの直接データ

[C++]

マウスの現在の状態を取得するには、DIMOUSESTATE 構造体か DIMOUSESTATE2 構造体へのポインタを指定して、IDirectInputDevice7::GetDeviceState を呼び出す。どちらの構造体を使用するかは、データ形式に依存する。この構造体に返されるマウス状態には、軸データおよび各ボタンの状態が含まれる。

構造体の最初の 3 つのメンバが軸座標を保持する (「マウス軸データの解釈」を参照すること)。

rgbButtons メンバは、バイト配列である。4 つまたは 8 つの各ボタンに 1 要素が対応する。従来型のマウスの場合、一般的に、配列の 1 番目の要素が左ボタン、2 番目が右ボタン、3 番目が中央ボタンである。上位ビットは、ボタンがダウン状態の場合にセットされ、ボタンがアップ状態または存在しない場合に消去される。

[Visual Basic]

マウスの現在の状態を取得するには、DIMOUSESTATE 型を指定して DirectInputDevice.GetDeviceStateMouse を呼び出す。この型に返されるマウス状態には、軸データおよび各ボタンの状態が含まれる。

DIMOUSESTATE 型の x、y、z の各メンバは、軸座標を保持する (「マウス軸データの解釈」を参照すること)。buttons メンバは、バイト配列である。4 つの各ボタンに 1 要素が対応する。一般的に、配列の 1 番目の要素が左ボタン、2 番目が右ボタン、3 番目が中央ボタン、4 番目が残りのボタンである。上位ビットは、ボタンがダウン状態の場合にセットされ、ボタンがアップ状態または存在しない場合に消去される。

参照

バッファリング データと直接データ


マウスのバッファリング データ

マウスからバッファリング データを取得するには、バッファ サイズを設定しなければならない (「デバイス プロパティ」を参照すること)。バッファのデフォルト サイズはゼロなので、この手順は不可欠である。

[C++]

また、DIDEVICEOBJECTDATA 構造体の配列も宣言する必要がある。この配列は、最大でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はないが、配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

デバイスの取得後は、IDirectInputDevice7::GetDeviceData メソッドを使っていつでもバッファ内のイベントを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。返されたDIDEVICEOBJECTDATA 配列中の各要素は、マウスに対する単一オブジェクトの状態変化を表す。たとえば、ユーザーがボタン 0 を押してマウスを斜めに移動すると、GetDeviceData に渡された配列 (3 つ以上の要素を持っている場合、dwInOut は 3 以上) は、3 つの要素が埋められる。これらの要素はそれぞれ、ボタン 0 の押下、x 軸の変化、および y 軸の変化を表す。pdwInOut は 3 に設定される。

配列中の要素がどのオブジェクトを指すかは、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを、以下のマクロによって返される値と比較することで確認できる。

  • DIMOFS_BUTTON0 ～ DIMOFS_BUTTON3
  • DIMOFS_X
  • DIMOFS_Y
  • DIMOFS_Z

これらの各値は、DIMOUSESTATE 構造体または DIMOUSESTATE2 構造体中のオブジェクトに対するデータのオフセットから導かれる。たとえば、DIMOFS_BUTTON0 が返す値は、DIMOUSESTATE 構造体中の rgbButtons[0] オフセットと等しい。マクロを使用して単純な比較を行い、どのデバイス オブジェクトがバッファの項目に関連しているかを決定することができる。たとえば、以下のとおりである。

DIDEVICEOBJECTDATA *lpdidod;
int         n;
.
.
.
/* MouseBuffer は、DIDEVICEOBJECTDATA 構造体の配列であり、
GetDeviceData の呼び出しによって設定される。
n は、配列中の埋め込まれたすべての要素を
調べるループで増加する。*/
lpdidod = &MouseBuffer[n];
if (( (int) lpdidod->dwOfs == DIMOFS_BUTTON0)
&& (lpdidod->dwData & 0x80))
{
; // 左ボタン押下に応じて何らかの処理を行う。
}

デバイス オブジェクトの状態変化データは、DIDEVICEOBJECTDATA 構造体の dwData メンバに格納される。軸の場合は、座標値がこのメンバに返される。ボタン オブジェクトの場合は、dwData の下位バイトだけが有意であり、上位ビットはボタンが押されたときに設定され、ボタンが離されたときに消去される。言い換えれば、(dwData & 0x80) がゼロでないとき、ボタンが押されていることになる。

DIDEVICEOBJECTDATA 構造体のほかのメンバの詳細については、「タイム スタンプとシーケンス番号」を参照すること。

[Visual Basic]

また、DIDEVICEOBJECTDATA 型の配列も宣言する必要がある。この配列は、最大でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はないが、配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

デバイスの取得後は、DirectInputDevice.GetDeviceData メソッドを使っていつでもバッファ内のイベントを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。返されたDIDEVICEOBJECTDATA 配列中の各要素は、マウスに対する単一オブジェクトの状態の変化を表す。たとえば、ユーザーがボタン 0 を押してマウスを斜めに移動すると、GetDeviceData に渡された配列 (3 つ以上の要素を持っている場合) は、3 つの要素が埋められる。これらの要素はそれぞれ、ボタン 0 の押下、x 軸の変化、および y 軸の変化を表す。メソッドの戻り値は 3 である。

配列中の要素がどのオブジェクトを指すかは、DIDEVICEOBJECTDATA 型の lOfs メンバを、CONST_DIMOUSEOFS 列挙内の定数と比較することで確認できる。これらの各値は、DIMOUSESTATE 型中のオブジェクトに対するデータのオフセットから導かれる。たとえば、DIMOFS_BUTTON0 が返す値は、DIMOUSESTATE 型中の buttons(0) オフセットと等しい。

デバイス オブジェクトの状態変化データは、DIDEVICEOBJECTDATA 型の lData メンバに格納される。軸の場合には、座標値がこのメンバ中に返される。ボタンオブジェクトでは、lData の下位バイトだけが有意であり、上位ビットはボタンが押されたときに設定され、ボタンが離されたときに消去される。言い換えれば、(lData & 0x80) がゼロでないとき、ボタンが押されていることになる。

DIDEVICEOBJECTDATA 型のほかのメンバの詳細については、「タイム スタンプとシーケンス番号」を参照すること。

次のコードは、バッファ (BufferSize 数の要素を含む) の内容全体を取得し、さまざまなイベントに応答する例である。

' objDIDev は DirectInputDevice オブジェクトである。
Dim diDeviceData(1 To BufferSize) As DIDEVICEOBJECTDATA
Dim NumEvents As Integer
Dim i As Integer

NumEvents = objDIDev.GetDeviceData(diDeviceData, 0)
For i = 1 To NumEvents
Select Case diDeviceData(i).lOfs
Case DIMOFS_X
' x 軸の移動に反応する。

Case DIMOFS_Y
' y 軸の移動に反応する。

Case DIMOFS_BUTTON0
If diDeviceData(i).lData And &H80 Then
' 左ボタン押下に反応する。
Else
' 左ボタン解放に反応する。
End If

End Select
Next i


マウス軸データの解釈

マウスの x 軸および y 軸に対して返されるデータは、カーソルではなくマウス自身の動作を示す。測定単位は、マウスのハードウェアが返す値に基づくものであり、ピクセルやその他の画面測定形式とは無関係である。DirectInput はマウス ドライバと直接通信するので、ユーザーがコントロール パネルで設定するマウスのスピードと加速値は、このデータに影響しない。

マウスから返される軸データは、相対でも絶対でもよい (「相対座標と絶対座標」も参照すること)。マウスは相対的なデバイスなので (ジョイスティックとは異なり、ホームポジションを持たない)、デフォルトでは、相対データが返される。

[C++]

軸モードは、相対データまたは絶対データのどちらを返すかを指定するもので、デバイスを取得する前に変更できるプロパティである (「デバイス プロパティ」を参照すること)。軸モードを "絶対" に設定するには、rguidProp パラメータに DIPROP_AXISMODE 値を指定し、DIPROPDWORD 構造体の dwData メンバに DIPROPAXISMODE_ABS を指定して、IDirectInputDevice7::SetProperty を呼び出す。

[Visual Basic]

軸モードは、相対データまたは絶対データのどちらを返すかを指定するものであるが、デバイスを取得する前に変更できるプロパティである (「デバイス プロパティ」を参照すること)。軸モードを "絶対" に設定するには、guid パラメータに DIPROP_AXISMODE 値を指定し、DIPROPDWORD 型の lData メンバに DIPROPAXISMODE_ABS を指定して、DirectInputDevice.SetProperty を呼び出す。

マウスの軸モードが "相対" の場合、軸座標は、最後の値が返されて以降、軸にそってデバイスが移動した単位数を表す。負の値は、ｘ軸の場合、マウスが左方向に移動したこと、y 軸の場合、ユーザーから離れる方向にマウスが移動したこと、および z 軸 (ホイール) が手前に回転したことをそれぞれ示す。正の値はこれと反対方向の動きを示す。

軸モードが "絶対" の場合、軸座標は、単純に DirectInput が受信した相対動作のすべての累積合計となる。軸座標値は、デバイスの取得時には、特定の値に初期化されていないので、アプリケーションは、絶対値を未知の原点を基準にした相対値として扱う必要がある。デバイスを取得したときは、いつも現在の絶対位置を記録して、それを "仮想原点" として保存することができる。この仮想原点は、その後、デバイスから得られる絶対座標から減算することにより、マウスが取得時点から移動した相対距離を計算することができる。

軸座標に返されるデータは、デバイスの細分性プロパティによっても影響を受ける。マウスの x 軸と y 軸の場合、細分度は通常 1 であり、これは、値の最小変化が 1 であることを意味する。ホイールの場合、細分度が 1 より大きくなることもある。


消失したマウス入力の確認

[C++]

協調レベルに DISCL_FOREGROUND を設定した状態で、フォーカスがほかのアプリケーションに切り替わる場合、あるいは使用中のアプリケーションのほかのメニューに切り替わる場合でも、Windows がアプリケーションにマウスを強制的に解放させることがあるので、IDirectInputDevice7::GetDeviceData または IDirectInputDevice7::GetDeviceState メソッドからの戻り値 DIERR_INPUTLOST をチェックして、必要に応じてマウスを再取得する必要がある (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、マウスの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。

[Visual Basic]

協調レベルに DISCL_FOREGROUND を設定した状態で、フォーカスがほかのアプリケーションに切り替わる場合、あるいは使用中のアプリケーションのほかのメニューに切り替わる場合でも、Windows がアプリケーションにマウスを強制的に解放させることがあるので、DirectInputDevice.GetDeviceData または DirectInputDevice.GetDeviceStateMouse メソッドからの DIERR_INPUTLOST の戻り値をチェックして、必要に応じてマウスを再取得する必要がある (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、マウスの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。


キーボード データ

DirectInput に関する限り、キーボードは、テキスト入力デバイスではなく、多数のボタンを備えたゲーム パッドとなる。アプリケーションがテキスト入力を必要とするときは、DirectInput のメソッドを使ってはいけない。通常の Windows メッセージからデータを取得するのが最も簡単であり、文字反復および物理キーの仮想キーへの変換などの Windows サービスを利用することができるからである。これは、英語以外の言語を使用する場合には特に重要である。英語以外の言語ではキーの特別な解釈が必要となることがあるからである。

[C++]

データを取得するようにキーボード デバイスを設定するには、パラメータに c_dfDIKeyboard グローバル変数を指定して、IDirectInputDevice7::SetDataFormat メソッドを呼び出す (「デバイス データ形式.」を参照すること)。

[Visual Basic]

データを取得するようにキーボード デバイスを設定するには、パラメータに DIFORMAT_KEYBOARD を指定して、DirectInputDevice.SetCommonDataFormat メソッドを呼び出す。

以下のトピックでは、キーボード データの取得と解釈の詳細を説明する。

  • キーボードの直接データ
  • キーボードのバッファリング データ
  • キーボード データの解釈
  • 消失したキーボード入力の確認


キーボードの直接データ

[C++]

キーボードの現在の状態を取得するには、戻り値データを保持する 256 バイトの配列へのポインタを指定して、IDirectInputDevice7::GetDeviceState メソッドを呼び出す。

GetDeviceState メソッドは、Win32 GetKeyboardState 関数と同様に動作し、キーボードの現在の状態のスナップショットを返す。各キーは、256 バイトの配列内の 1 バイトによって表される。配列のアドレスは、lpvData パラメータとして渡されたものである。バイトの上位ビットが設定されている場合、キーは押した状態にある。配列は最も便利なように、DirectInput キーボード デバイス定数によりインデックスが付けられている (「キーボード データの解釈」も参照すること)。

以下のコードは、Esc キーの押下に応じて何らかの処理を行う例である。

// LPDIRECTINPUTDEVICE lpdiKeyboard; // 前もって初期化され、
// 取得されている。

BYTE diKeys[256];
if (lpdiKeyboard->GetDeviceState(256, diKeys) == DI_OK)
{
if (diKeys[DIK_ESCAPE] & 0x80) DoSomething();
}
[Visual Basic]

キーボードの現在の状態を取得するには、DIKEYBOARDSTATE 型を指定して DirectInputDevice.GetDeviceStateKeyboard を呼び出す。

GetDeviceState メソッドは、キーボードの現在の状態のスナップショットを返す。各キーは、DIKEYBOARDSTATE 型を構成する 256 バイトの配列内の 1 バイトによって表される。バイトの上位ビットが設定されていると、キーは、ダウン状態にある。配列は最も便利なように、CONST_DIKEYFLAGS 列挙のメンバによりインデックスが付けられている (「キーボード データの解釈」も参照すること)。

以下のコードは、現在 Esc キーが押下されているかどうかを判定する例である。

' objDIDev は DirectInputDevice オブジェクトである。
Dim dev As DirectInputDevice
Dim KeyState As DIKEYBOARDSTATE

Call objDIDev.GetDeviceStateKeyboard(KeyState)
If (KeyState.Key(DIK_ESCAPE) And &H80) Then
' キーは押下されている。
End If


キーボードのバッファリング データ

キーボードからバッファリング データを取得するには、バッファ サイズを設定しなければならない (「デバイス プロパティ」を参照すること)。この手順は、バッファのデフォルト サイズがゼロであるので不可欠である。

[C++]

また、DIDEVICEOBJECTDATA 構造体の配列も宣言する必要がある。この配列は、最大でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はないが、配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

キーボード デバイスの取得後は、IDirectInputDevice7::GetDeviceData メソッドを使っていつでもバッファを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。

DIDEVICEOBJECTDATA 配列の各要素は、単一キーの状態変化、すなわち、押下と解放を表す。DirectInput は、キーボードから直接データを取得するために、コントロール パネルの文字反復の設定はすべて無視する。すなわち、キーストロークは、キーが押下されている時間の長短に関係なく、1 度しかカウントされないということになる。

配列中の要素がどのキーを指すかは、DirectInput のキーボード デバイス定数と、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを比較することにより確認できる (「キーボード データの解釈」も参照すること)。

キーの状態変化データは、DIDEVICEOBJECTDATA 構造体の dwData メンバに格納されている。意味を持つのは、dwData の下位バイトのみである。上位ビットは、キーが押下されたときに設定され、キーが離されたときに消去される。言い換えれば、(dwData & 0x80) がゼロでないとき、キーが押されていることになる。

[Visual Basic]

また、DIDEVICEOBJECTDATA 型の配列も宣言する必要がある。この配列は、最大でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はないが、配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

キーボード デバイスの取得後は、DirectInputDevice.GetDeviceData メソッドを使っていつでもバッファ内のイベントを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。

DIDEVICEOBJECTDATA 配列の各要素は、単一キーの状態変化、すなわち、押下と解放を表す。DirectInput は、キーボードから直接データを取得するために、コントロール パネルの文字反復の設定はすべて無視する。すなわち、キーストロークは、キーが押下されている時間の長短に関係なく、1 度しかカウントされないということになる。

配列中の要素がどのキーを指すかは、DIDEVICEOBJECTDATA 型の lOfs メンバを、CONST_DIKEYFLAGS 列挙内の定数と比較することで確認できる (「キーボード データの解釈」も参照すること)。

キーの状態変化データは、DIDEVICEOBJECTDATA 型の lData メンバに格納されている。意味を持つのは、lData の下位バイトのみである。下位バイトの上位ビットは、キーが押下されたときに設定され、キーが離されたときに消去される。言い換えれば、(lData And &H80) がゼロでないとき、キーが押されていることになる。


キーボード データの解釈

[C++]

ここでは、IDirectInputDevice7::GetDeviceState メソッドおよび IDirectInputDevice7::GetDeviceData メソッドが報告するデータのキーの識別について説明する。GetDeviceData からのデータの解釈についての詳細は、「タイム スタンプとシーケンス番号」を参照すること。

[Visual Basic]

ここでは、DirectInputDevice.GetDeviceState メソッドおよび DirectInputDevice.GetDeviceData メソッドが報告するデータのキーの識別について説明する。GetDeviceData からのデータの解釈についての詳細は、「タイム スタンプとシーケンス番号」を参照すること。

DirectInput がキーボードを読み取る上で、Windows のほかの方法と異なるのは、次の重要な点である。キーボード データは、仮想キーを指すのではなく、実際の物理的なキー、すなわち、スキャン コードを指す。たとえば、DIK_ENTER はメイン キーボードの Enter キーを指すが、テンキーの Enter キーは指していない。

DirectInput は、拡張キーボード上の各キーに対する定数と共に、国際キーボード上にある追加キーも定義する。NEC キーボードは、PC 拡張キーボードとは異なるスキャン コードをサポートしているので、DirectInput は、可能な限り NEC スキャン コードを PC 拡張スキャン コードに変換する。

また、すべての PC 拡張キーボードに、新しい Windows キー (DIK_LWIN、DIK_RWIN、DIK_APPS) があるわけではない。キーが物理的にも使用可能であるかどうかを確認する方法はない。

ラップトップなどの小型コンピュータは、フルセットのキーを実装していない。代わりに、一部のキー (普通はテンキー) をほかのキーと多重化し、補助モードキーによって選択するようにして、個別のスキャン コードをつくらないようにしている。

キーボード サブタイプが PC XT または PC AT キーボードを示している場合、DIK_F11、DIK_F12、およびすべての拡張キー (0x7F より大きい DIK_* 値を持つキー) は利用できない。さらに、PC XT キーボードには DIK_SYSRQ がない。

日本語キーボード、特に NEC PC-98 キーボードは、US キーボードとは相当に異なるキー セットを含んでいる。詳細については、「DirectInput と日本語キーボード」を参照すること。


消失したキーボード入力の確認

[C++]

協調レベルを DISCL_FOREGROUND に設定した状態で、フォーカスがほかのアプリケーションに切り替わる場合、Windows がアプリケーションにキーボードを強制的に解放させることがあるので、IDirectInputDevice7::GetDeviceData メソッドまたは IDirectInputDevice7::GetDeviceState メソッドからの DIERR_INPUTLOST 戻り値をチェックして、必要に応じてキーボードを再取得する必要がある (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、キーボードの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。

[Visual Basic]

協調レベルを DISCL_FOREGROUND に設定した状態で、フォーカスがほかのアプリケーションに切り替わる場合、Windows がアプリケーションにキーボードを強制的に解放させることがあるので、DirectInputDevice.GetDeviceData メソッドまたは DirectInputDevice.GetDeviceStateKeyboard メソッドからの DIERR_INPUTLOST 戻り値をチェックして、必要に応じてキーボードを再取得する必要がある (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、キーボードの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。


ジョイスティック データ

[C++]

データを取得するようにジョイスティック デバイスを設定するには、パラメータに c_dfDIJoystick グローバル変数を指定して、IDirectInputDevice7::SetDataFormat メソッドを呼び出す (「デバイス データ形式」を参照すること)。

一部のデバイス ドライバは、明示的に要求されるまで DirectInput に状態の変化を通知しないことがあるので、ジョイスティックのデータを取得する前には必ず IDirectInputDevice7::Poll メソッドを呼び出さなくてはならない。詳細については、「ポーリングとイベント」を参照すること。

[Visual Basic]

データを取得するようにジョイスティック デバイスを設定するには、パラメータに DIFORMAT_JOYSTICK または DIFORMAT_JOYSTICK2 を指定して、DirectInputDevice.SetCommonDataFormat メソッドを呼び出す (「デバイス データ形式」を参照すること)。

一部のデバイス ドライバは、明示的に要求されるまで DirectInput に状態の変化を通知しないことがあるので、ジョイスティックのデータを取得する前には必ず DirectInputDevice.Poll メソッドを呼び出さなくてはならない。詳細については、「ポーリングとイベント」を参照すること。

以下のトピックでは、ジョイスティックおよびゲームパッドまたは操縦桿などの入力デバイスからのデータの取得と解釈を説明する。

  • ジョイスティックの直接データ
  • ジョイスティックのバッファリング データ
  • ジョイスティック軸データの解釈
  • 消失したジョイスティック入力の確認


ジョイスティックの直接データ

[C++]

ジョイスティックの現在の状態を取得するには、DIJOYSTATE 構造体または DIJOYSTATE2 構造体へのポインタを指定して IDirectInputDevice7::GetDeviceState メソッドを呼び出す。どちらの構造体を使用するかは、c_dfDIJoystick か c_dfDIJoystick2 のどちらでデータ形式が設定されたのかによる (「デバイス データ形式」を参照すること)。構造体に返されるジョイスティックの状態には、軸座標、ボタンの状態、および視点コントローラの状態などがある。

DIJOYSTATE 構造体の最初の 7 つのメンバが軸座標を保持する。このうち最後のメンバ rglSlider は 2 つの値の配列である (「ジョイスティック軸データの解釈」を参照すること)。

rgdwPOV メンバには、4 つまでの視点コントローラの位置が含まれている。これらは、北から時計回り (または前方) の実角度の 100 倍で表される。中心位置は -1 として報告される。5 つの位置しか持たないコントローラでは、dwPOV は以下のいずれか 1 つの値を取る。

  • -1
  • 0
  • 90 * DI_DEGREES
  • 180 * DI_DEGREES
  • 270 * DI_DEGREES.

中心位置として、-1 ではなく 65,535 を報告するドライバもある。POV 標識が中心位置にあるかどうかは、次のようにチェックしなければならない。

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

rgbButtons メンバは、バイト配列である。データ形式によって、32 個または 128 個の各ボタンに 1 要素が対応する。各ボタンの上位ビットは、ボタンがダウン状態で設定され、アップ状態または存在しない場合に消去される。

DIJOYSTATE2 構造体には、軸の速度、加速度、フォース、およびトルクについての情報を提供する追加メンバがある。

[Visual Basic]

ジョイスティックの現在の状態を取得するには、DirectInputDevice.GetDeviceStateJoystick メソッドまたは DirectInputDevice.GetDeviceStateJoystick2 メソッドを呼び出す。どちらのメソッドを使用するかは、DIFORMAT_JOYSTICK か DIFORMAT_JOYSTICK2 のどちらでデータ形式が設定されたのかによる (「デバイス データ形式.」を参照すること)。state パラメータに返されるジョイスティック状態には、軸座標、ボタンの状態、および視点コントローラの状態などがある。

DIJOYSTATE 型または DIJOYSTATE2 型の POV メンバには、4 つまでの視点コントローラの位置が含まれている。これらは、北から時計回り (または前方) の実角度の 100 倍で表される。中心位置は -1 として報告される。5 つの位置しか持たないコントローラの場合、POV は以下のどれか 1 つの値を取る。

  • -1
  • 0
  • 9000
  • 18000
  • 27000

中心位置として、-1 ではなく 65,535 を報告するドライバもある。POV 標識が中心位置にあるかどうかは、次のようにチェックしなければならない。

Dim POVCentered As Boolean
POVCentered = (dwPOV And &HFFFF) = &HFFFF;

buttons メンバは、バイト配列である。データ型によって、32 個または 128 個の各ボタンに 1 要素が対応する。各ボタンの上位ビットは、ボタンがダウン状態で設定され、アップ状態または存在しない場合に消去される。

DIJOYSTATE2 型には、軸の速度、加速度、フォース、およびトルクについての情報を提供する追加メンバがある。

詳細については、「ジョイスティック軸データの解釈」を参照すること。

参照

バッファリング データと直接データ


ジョイスティックのバッファリング データ

[C++]

ジョイスティックからバッファリング データを取得するには、まず、バッファサイズを設定し (「デバイス プロパティ」を参照すること)、DIDEVICEOBJECTDATA 構造体の配列を宣言しなければならない。この配列は、最高でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はないが、配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

デバイスの取得後は、IDirectInputDevice7::GetDeviceData メソッドを使っていつでもバッファを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。

DIDEVICEOBJECTDATA 配列中の各要素は、ジョイスティックに対する単一オブジェクトの状態の変化を表す。たとえば、ユーザーがボタン 0 を押してスティックを斜めに移動すると、GetDeviceData に渡された配列 (3 つ以上の要素を持っている場合、dwInOut は 3 以上) は、3 つの要素が埋められる。これらの要素はそれぞれ、ボタン 0 の押下、x 軸の変化、および y 軸の変化を表す。pdwInOut は 3 に設定される。

配列中の要素がどのオブジェクトを指すかは、以下の値と、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを比較することにより決定できる。

  • DIJOFS_X
  • DIJOFS_Y
  • DIJOFS_Z
  • DIJOFS_Rx
  • DIJOFS_Ry
  • DIJOFS_Rz
  • DIJOFS_BUTTON0 から DIJOFS_BUTTON31 または DIJOFS_BUTTON(n)
  • DIJOFS_POV(n)
  • DIJOFS_SLIDER(n)

これらのそれぞれの値は、DIJOYSTATE 構造体中のオブジェクトに対するデータのオフセットと等しい。たとえば、DIJOFS_BUTTON0 は、DIJOYSTATE 構造体中の rgbButtons[0] オフセットと等しい。単純な比較を行うことで、どのデバイス オブジェクトがバッファ上の項目に関連しているかを確認することができる。たとえば、以下のとおりである。

DIDEVICEOBJECTDATA *lpdidod;
int         n;
.
.
.
/* JoyBuffer は、DIDEVICEOBJECTDATA 構造体の配列であり、
GetDeviceData への呼び出しによって設定される。
n は、配列中で埋め込まれたすべての要素を
調べるループで増加する  */ */
lpdidod = &JoyBuffer[n];
if (( (int) lpdidod->dwOfs == DIJOFS_BUTTON0)
&& (lpdidod->dwData & 0x80))
{
; // 主ボタンの押下に応じて、何らかの処理を行う。
}

データ形式が c_dfDIJoystick2 で設定された場合は、DIJOYSTATE 内に存在するすべてのデバイス オブジェクトに事前定義されたオフセットを使用することができる。ただし、DIJOYSTATE2 の追加メンバに表現されるデバイス オブジェクトには、独自のオフセットを設定する必要がある。

デバイス オブジェクトの状態変化データは、DIDEVICEOBJECTDATA 構造体の dwData メンバに格納される。軸の場合には、座標値がこのメンバ中に返される。ボタン オブジェクトの場合には、dwData の下位バイトだけが有意である。このバイトの上位ビットは、ボタンが押された場合に設定され、ボタンが離された場合に消去される。

ほかのメンバについては、「タイム スタンプとシーケンス番号」を参照すること。

[Visual Basic]

ジョイスティックからバッファリング データを取得するには、まず、バッファサイズを設定し (「デバイス プロパティ」を参照すること)、DIDEVICEOBJECTDATA 型の配列を宣言しなければならない。この配列は、最高でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はないが、配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

デバイスの取得後は、DirectInputDevice.GetDeviceData メソッドを使っていつでもバッファ内のイベントを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。

DIDEVICEOBJECTDATA 配列中の各要素は、ジョイスティックに対する単一オブジェクトの状態の変化を表す。たとえば、ユーザーがボタン 0 を押してスティックを斜めに移動すると、GetDeviceData に渡された配列 (3 つ以上の要素を持っている場合) には、3 つの要素が埋められる。これらの要素はそれぞれ、ボタン 0 の押下、x 軸の変化、および y 軸の変化を表す。メソッドの戻り値は 3 である。

配列中の要素がどのオブジェクトを指すかは、DIDEVICEOBJECTDATA 型の lOfs メンバを、CONST_DIJOYSTICKOFS 列挙内の定数と比較することで確認できる。これらのそれぞれの値は、DIJOYSTATE 型中のオブジェクトに対するデータのオフセットと等しい。たとえば、DIJOFS_BUTTON0 が返す値は、DIJOYSTATE 型中の buttons(0) オフセットと等しい。

データ形式が DIFORMAT_JOYSTICK2 で設定された場合は、DIJOYSTATE 内に存在するすべてのデバイス オブジェクトのオフセット定数を使用することができる。ただし、DIJOYSTATE2 の追加メンバに表現されるデバイス オブジェクトには、独自のオフセットを設定する必要がある。この型の内部構造は、Dinput.h ヘッダー ファイルに含まれる同名の C++ 構造体と同じである。

デバイス オブジェクトの状態変化データは、DIDEVICEOBJECTDATA 型の lData メンバに格納される。軸の場合には、座標値がこのメンバ中に返される。ボタン オブジェクトの場合には、lData の下位バイトだけが有意である。このバイトの上位ビットは、ボタンが押された場合に設定され、ボタンが離された場合に消去される。

ほかのメンバについては、「タイム スタンプとシーケンス番号」を参照すること。


ジョイスティック軸データの解釈

ジョイスティックの軸値は、マウスの軸値と同様である。スティックを右に動かすと x 軸の戻り値が増し、スティックを手前に引き倒すと y 軸の値が増す。

ジョイスティック軸のデータは、軸の範囲プロパティにより任意の単位に決定される。たとえば、ジョイスティックの x 軸の範囲が 0 から 10,000 までの場合には、単位はジョイスティックの左右の移動の 10,000 分の 1 となり、中心位置は 5,000 となる。軸によっては、細分度プロパティが 1 より大きい場合もあり、その場合には値は丸められる。たとえば、細分度が 10 の場合には、値は 0、10、20 などのように報告される。

軸データは、無効ゾーンという、動作が無視される中心位置の周辺領域によっても影響を受ける。無効ゾーンは、ジョイスティックの少なくとも一方の軸に対する真の中心位置からの小さなずれに対する許容範囲となる。無効ゾーン内の軸の値は、真の中心として報告される。

軸の飽和プロパティとは、範囲の最大値および最小値の許容ゾーンのことである。このゾーン内の軸値は、最小値または最大値として報告される。飽和プロパティの目的は、たとえば、ジョイスティックの頂部の左位置と底部の左位置で報告される最小 x 軸間のわずかな差違を許容することにある。

次の図は、無効ゾーンと飽和ゾーンのエフェクトを示したものである。垂直軸は、軸の戻り値を表す。ここで、min と max は報告された範囲の下限と上限であり、ctr は報告された中心である。水平軸は、ジョイスティックの物理的な位置を示す。ここで、pmin と pmax は、物理的な範囲の限界、pctr は軸の中立点、dmin と dmax は無効ゾーンの限界値、そして smin と smax は上下の飽和ゾーンの境界である。下位飽和ゾーンは pmin と smin の間に存在し、上位飽和ゾーンは smax と pmax の間に存在し、無効ゾーンは dmin と dmax の間に存在する。

[C++]

ジョイスティック プロパティの詳細については、以下を参照すること。

  • IDirectInputDevice7::GetProperty
  • IDirectInputDevice7::SetProperty
  • DIPROPRANGE
[Visual Basic]

ジョイスティック プロパティの詳細については、以下を参照すること。

  • DirectInputDevice.GetProperty
  • DirectInputDevice.SetProperty
  • DIPROPRANGE

ジョイスティックから返される軸座標は、相対でも絶対でもよい (「相対座標と絶対座標」も参照すること)。ジョイスティックは絶対デバイスなので (マウスとは異なり、軸にそって無限には移動できない)、デフォルトでは絶対データが返される。ジョイスティックの軸モードが "相対" に設定されている場合には、軸座標は、最後の値が返されてから以降の軸にそった移動の単位数を表す。

[C++]

軸モードは、相対データまたは絶対データのどちらを返すかを指定するもので、デバイスを取得する前に変更できるプロパティである (「デバイス プロパティ」を参照すること)。軸モードを "相対" に設定するには、rguidProp パラメータに DIPROP_AXISMODE 値を指定し、DIPROPDWORD 構造体の dwData メンバに DIPROPAXISMODE_REL を指定して、IDirectInputDevice7::SetProperty メソッドを呼び出す。

[Visual Basic]

軸モードは、相対データまたは絶対データのどちらを返すかを指定するもので、デバイスを取得する前に変更できるプロパティである (「デバイス プロパティ」を参照すること)。軸モードを "絶対" に設定するには、guid パラメータに DIPROP_AXISMODE 値を指定し、DIPROPLONG 型の lData メンバに DIPROPAXISMODE_ABS を指定して、DirectInputDevice.SetProperty を呼び出す。


消失したジョイスティック入力の確認

ジョイスティックをフォアグラウンドモードで使用する (「協調レベル」を参照すること) 場合には、フォーカスが他のアプリケーションに切り替わるときに、デバイスを喪失することがある。

[C++]

IDirectInputDevice7::GetDeviceData メソッドまたは IDirectInputDevice7::GetDeviceState メソッドからの DIERR_INPUTLOST 戻り値をチェックし、必要に応じてジョイスティックを再取得することができる (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、ジョイスティックの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。

キーボードやマウスとは異なり、Windows システムはジョイスティックを使用しないので、アプリケーションがバックグラウンドに移行する場合を除き、ジョイスティックへのアクセス権が失われることはない。したがって、どちらのメソッドでも、WM_ACTIVATE メッセージに応えてデバイスを再取得できる。

[Visual Basic]

DirectInputDevice.GetDeviceData メソッドまたは DirectInputDevice.GetDeviceState メソッドからの DIERR_INPUTLOST 戻り値をチェックし、必要に応じてジョイスティックを再取得することができる (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、ジョイスティックの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。


データ出力

[C++]

ヒューマン インターフェイス デバイスは、入力の生成と同様に出力を扱うことができる。IDirectInputDevice7::SendDeviceData メソッドは、データのパケットをそれらのデバイスに送る。

SendDeviceData は、反対に IDirectInputDevice7::GetDeviceData として表示することができる。SendDeviceData メソッドと同様、GetDeviceData メソッドは、データの基本単位として DIDEVICEOBJECTDATA 構造体を使用する。この場合、dwOfs メンバに含まれるのは、デバイスのデータ形式のオフセットではなく、データに関連付けられたデバイス オブジェクトのインスタンス ID である(オフセット識別子は、選択されたデータ形式での入力を提供するデバイス オブジェクトのためだけに存在するので、出力しか認めないオブジェクトは、オフセットを持つことすらない)。dwData メンバには、そのオブジェクトに適したデータが含まれる。dwTimeStamp および dwSequence メンバは使用しない。これらのメンバは、ゼロに設定しなければならない。

デバイスにデータを送るには、最初に DIDEVICEOBJECTDATA 構造体の配列を設定し、要求された数の要素をデータで埋めてから、使用されるアドレスと要素数を SendDeviceData に渡す。複数のデバイス オブジェクトに対するデータは、デバイスに送られる単一パケットに結合される。

データ パケットの形式は、パケット内の使用されないフィールドの処理方法と同じで、デバイスによって異なる。デバイスによっては、データが提供されない場合には、オブジェクトの状態に変更がないとみなし、フィールドをオプションとして扱うことがある。一般的には、特にデータがフィールドに提供されない場合であっても、すべてのフィールドは重要である。たとえば、単一のキーボード LED にデータを送ると、ほかの 2 つの LED のデータはゼロで、2 つの LED はオフであると仮定される。しかし、この 2 つの LED のデータとして、最後に送信された値を使用する場合には、DISDD_CONTINUE フラグを使用してこの動作を無効にすることができる。

次の例では、コードが繰り返し実行される場合、キーボード上の LED (IDirectInputDevice7 インターフェース pdev により表される) は繰り返し点滅する。デバイス オブジェクト識別子、NumLockID、CapsLockID、および ScrollLockID は、デバイス オブジェクトの列挙中か、または IDirectInputDevice7::GetObjectInfo を呼び出すことで、DIDEVICEOBJECTINSTANCE 構造体の dwType メンバから事前に取得されている。LED の状態は、データ バイトの上位ビットにより決定されるものとする。

void FlashLEDs(void)
    {
static int     rgiBits[] = { 1, 2, 4, 2 };
static int     iLooper = 0;
DWORD       cdod = 3;         // 項目数。
DIDEVICEOBJECTDATA rgdod[3];
HRESULT      hres;

// dwTimeStamp および dwSequence を消去する必要がある。
ZeroMemory(rgdod, sizeof(rgdod));

rgdod[0].dwOfs = NumLockID;
rgdod[1].dwOfs = CapsLockID
rgdod[2].dwOfs = ScrollLockID;

rgdod[0].dwData = (rgiBits[iLooper] & 1) ?0x80 : 0;
                                           // 1,0,0,0,...
rgdod[1].dwData = (rgiBits[iLooper] & 2) ?0x80 : 0;
                                           // 0,1,0,1,...
rgdod[2].dwData = (rgiBits[iLooper] & 4) ?0x80 : 0;
                                           // 0,0,1,0,...

iLooper = (iLooper + 1) % ARRAYSIZE(rgiBits); // 0 から 3 までループする。

hres = IDirectInputDevice7_SendDeviceData(pdev,
sizeof(DIDEVICEOBJECTDATA),
rgdod, &cdod, 0);
    }
[Visual Basic]

ヒューマン インターフェイス デバイスは、入力の生成と同様に出力を認知することができる。そのようなデバイスにデータ パケットを送信するには、DirectInputDevice.SendDeviceData メソッドを使用する。

SendDeviceData は、反対に DirectInputDevice.GetDeviceData として表示することができる。SendDeviceData メソッドと同様、GetDeviceData メソッドは、データの基本単位として DIDEVICEOBJECTDATA 型を使用する。この場合、lOfs メンバに含まれるのは、デバイスのデータ形式のオフセットではなく、データに関連付けられたデバイス オブジェクトのインスタンス ID である。この ID は、デバイス オブジェクトを列挙した後に、DirectInputDeviceObjectInstance.GetType により返される値から抽出できる(オフセット識別子は、選択されたデータ形式での入力を提供するデバイス オブジェクトのためだけに存在するので、出力しか認めないオブジェクトは、オフセットを持つことすらない)。lData メンバには、そのオブジェクトに適したデータが含まれる。lTimeStamp および lSequence メンバは使用しない。これらのメンバは、ゼロに設定しなければならない。

デバイスにデータを送るには、最初に DIDEVICEOBJECTDATA 型の配列を設定し、要求された数の要素をデータで埋めてから、使用するアドレスと要素数を SendDeviceData に渡す。異なるデバイス オブジェクトのデータは、デバイスに送られる単一パケットに結合される。

データ パケットの形式は、パケット内の使用されないフィールドの処理方法と同じで、デバイスによって異なる。デバイスによっては、データが提供されない場合には、オブジェクトの状態に変更がないとみなし、フィールドをオプションとして扱うことがある。一般的には、特にデータがフィールドに提供されない場合であっても、すべてのフィールドは重要である。たとえば、単一のキーボード LED にデータを送ると、ほかの 2 つの LED のデータはゼロで、それらの LED はオフであると仮定される。しかし、この 2 つの LED のデータとして、最後に送信された値を使用する場合には、DISDD_CONTINUE フラグを使用してこの動作を無効にすることができる。


フォース フィードバック

フォース フィードバックとは、入出力デバイス (たとえば、ジョイスティックに組み込まれているモーター) にプッシュあるいは抵抗を生成することである。DirectInput では、互換性のあるドライバを持つデバイスにフォース フィードバック エフェクトを生成することができる。

以下のトピックでは、フォース フィードバックの概念を紹介する。

  • フォース フィードバックの基本概念
  • エフェクトの列挙
  • ファイルからのエフェクトの読み込み
  • サポートされるエフェクトについての情報
  • エフェクトの生成
  • エフェクトの方向
  • エンベロープとオフセット
  • エフェクトのプレイバック
  • エフェクトのダウンロードとアンロード
  • エフェクトの変更
  • ゲイン
  • フォース フィードバック状態
  • エフェクト オブジェクトの列挙
  • エフェクトのタイプ


フォース フィードバックの基本概念

フォース フィードバックのうち特殊なインスタンスを "エフェクト" と言い、プッシュや抵抗を "フォース" と言う。多くのエフェクトは、以下のカテゴリのいずれかに属する。

  • コンスタント フォース － 単一方向の一定のフォース
  • 傾斜フォース － 一定の率で大きさが増加または減少するフォース
  • 周期的エフェクト － 定義された波形パターンで変化するフォース。
  • 条件 － ユーザーによる入力にだけ反応して発生するフォース。たとえば、ジョイスティックの動作に対して抵抗を生み出す摩擦エフェクトや、ジョイスティックがある位置から動かされた後で、スティックをその位置に戻そうとするスプリング エフェクトである。

フォースの強さを "マグニチュード" という。マグニチュードは、0 (フォースなし) から 10,000 (デバイスの最大フォースで、C/C++ の場合、Dinput.h で DI_FFNOMINALMAX として定義されている) の範囲の単位で測定される。負の値は、反対の方向にあるフォースを示す。マグニチュードは比例的な単位である。たとえば、フォース 10,000 はフォース 5,000 の 2 倍の大きさである。

傾斜フォースには、初期マグニチュードと終期マグニチュードがある。周期的エフェクトでは、基本的マグニチュードは波の頂点でのフォースとなる。

フォースの "方向" はフォースが来る方向である。ある軸上の正のフォースは正から負のほうへ押す力である。

また、エフェクトには "継続時間" がある。これは、マイクロ秒単位で測定される。周期的エフェクトには、"周期" または 1 サイクルの継続時間があり、これらもマイクロ秒単位で測定される。周期的エフェクトの "フェーズ" とは、再生開始箇所の波にそって存在する点のことである。

次の図は、マグニチュード 5,000、つまりデバイスの最大フォースの半分での鋸歯周期的エフェクトを表す。水平軸はエフェクトの継続時間を、垂直軸はマグニチュードをそれぞれ表す。中央線よりも上の点は、エフェクトに定義された方向における正のフォースを、下の点は負のフォース、すなわち反対方向のフォースを表す。

さらにフォースは、"エンベロープ" によって形成される。エンベロープは、"アタック値" と "フェード値" を定義する。アタック値とフェード値により、始点と終点間のエフェクトのマグニチュードが変化する。アタックとフェードには継続時間がある。継続時間は、マグニチュードが "保持値" に到達するのに必要な時間、または保持値から外れるのに要する時間を決定する。保持値とは、エフェクトの中間部のマグニチュードのことである。

次の図は、エンベロープを示している。アタック レベルは 8,000、フェード レベルは 1,000 に設定されている。保持レベルは、このエンベロープを適用したフォースの基本的マグニチュードによって定義される。この例では保持レベルは 5,000 である。このケースでは、アタックの方が保持よりも大きいことに注意すること。これは、エフェクトの初期に強いキックを与えることになる。アタック レベルとフェード レベルの両方が保持レベルより大きいことも小さいこともある。

次の図は、最初の図の周期的エフェクトにエンベロープを適用した結果を示す。マグニチュードの負側では、エンベロープが鏡写しになっている。アタック値 8,000 が意味するのは、一方の方向のフォースの初期マグニチュードが、最大フォースの 80% になるということである。

周期的エフェクトと条件は、すべて、"オフセット" の追加によっても変更することができる。オフセットとは、波形を基本レベルよりも上または下にシフトする量を定義するものである。鋸歯の例に正のオフセットを適用した実際のエフェクトでは、正のフォースを強め、負のフォースを弱めることになる。すなわち、フォースの波形では、一方向への波の頂点が、他方向への波の頂点よりも高くなる。

また、エフェクトの全体的マグニチュードは、"ゲイン" によって増減可能である。ゲインとは、オーディオにおける音量コントロールに類似している。単一のゲイン値を 1 つのデバイスのすべてのエフェクトに適用できるので、これを使って、いろいろなハードウェアに対してフォースを強めたり、弱めたりする補正を加えることができる。また、ユーザーの好みに対応することもできる。


エフェクトの列挙

[C++]

IDirectInputDevice7::EnumEffects メソッドは、さまざまな種類のエフェクトに関して、デバイスで提供されるサポートについての情報を返す。

"サポートされるエフェクト" と "生成されるエフェクト" ("エフェクト オブジェクト") の両者を区別することが重要である。サポートされるエフェクトは、エンベロープによって形成できるコンスタント フォースである。しかし、このエフェクトには、マグニチュード、方向、継続時間、アタックまたはフェードなどのプロパティがまったくない。アプリケーションでエフェクト オブジェクトを生成するときは、これらのプロパティを設定する。サポートされるエフェクトは、それぞれ異なるパラメータを持つ多くのエフェクト オブジェクトによって表すことができる。たとえば、それぞれ異なる継続時間、マグニチュードおよび方向を持つ複数のコンスタント フォースによって表すことができる。

生成されたエフェクトの列挙については、「エフェクト オブジェクトの列挙」を参照すること。

ほかの DirectInput 列挙と同様に、IDirectInputDevice7::EnumEffects メソッドにはコールバック関数が必要である。ドキュメントではこの関数はプレースホルダ名の DIEnumEffectsCallback で表されているが、好きな名前を付けることができる。この関数は、列挙されるエフェクトごとに呼び出される。この関数内では、それぞれのエフェクトに対する GUID を取得でき、ハードウェア サポートの範囲についての情報を取得でき、さらに、1 つまたはそれ以上のエフェクト オブジェクトを生成し、そのオブジェクトのメソッドを使用してエフェクトを操作することができる。

以下の例は、列挙を開始する IDirectInputDevice7::EnumEffects メソッドを呼び出すコードである。このコールバック関数の pvRef パラメータは 32 ビットの任意の値を取ることができる。この場合、このパラメータはデバイス インターフェイスへのポインタであり、デバイスがサポートするエフェクトについての情報の取得と、エフェクト オブジェクトの生成に使用される。

HRESULT hr;
// LPDIRECTINPUTDEVICE lpdid2;  // 初期化済み。

BOOL CALLBACK DIEnumEffectsCallback(LPCDIEFFECTINFO pdei,
LPVOID pvRef)
{
LPDIRECTINPUTDEVICE2 lpdid = pvRef;  // 呼び出しデバイスへのポインタ。
LPDIRECTINPUTEFFECT lpdiEffect;   // 生成されたエフェクトへのポインタ。
DIEFFECT      diEffect;   // 生成されたエフェクト用のパラメータ。
DICONSTANTFORCE   diConstantForce; // タイプ固有パラメータ。
                                          // for diEffect

if (DIEF_GETTYPE(pdei->dwEffType) == DIEFFT_CONSTANTFORCE)
    {
/* エフェクト タイプ (pdei から) のサポート情報を
抽出し、それに応じてエフェクトを適応させること
ができる。たとえば、このデバイスは、このタイプ
のエフェクトではエンベロープをサポートしない。*/
       .
       .
       .
// 1 つまたはそれ以上のコンスタント フォース エフェクトを生成する。
// それぞれについて、DICONSTANTFORCE と
// DIEFFECT 構造体を初期化しなければならない。
// 「エフェクトの生成」で詳しい例を参照すること。
       .
       .
       .
hr = pdid->CreateEffect(pdei->guid,
&diEffect,
&lpdiEffect,
NULL);
       .
       .
       .
    }
// ほかのタイプのエフェクトについても同様。
   .
   .
   .

return DIENUM_CONTINUE;
} // コールバックの終了。
.
.
.
// コールバックの始動。
hr = lpdid2->EnumEffects(&EnumEffectsCallback,
lpdid2, DIEFT_ALL);

エフェクトを初期化する方法の詳細については、「エフェクトの生成」を参照すること。

[Visual Basic]

DirectInputDevice.GetEffectsEnum メソッドは、デバイスによりサポートされるエフェクトを列挙する。このメソッドは、サポートされるエフェクトのコレクションを表す DirectInputEnumEffects オブジェクトを返す。DirectInputEnumEffects の各メソッドを使うと、特定のエフェクトに関する情報を取得できる。

"サポートされるエフェクト" と "生成されるエフェクト" ("エフェクト オブジェクト") の両者を区別することが重要である。サポートされるエフェクトは、エンベロープ によって形成できるコンスタント フォースである。しかし、このエフェクトには、マグニチュード、方向、継続時間、アタックまたはフェードなどのプロパティがまったくない。アプリケーションでエフェクト オブジェクトを生成するときは、これらのプロパティを設定する。サポートされるエフェクトは、それぞれ異なるパラメータを持つ多くのエフェクト オブジェクトによって表すことができる。たとえば、それぞれ異なる継続時間、マグニチュードおよび方向を持つ複数のコンスタント フォースによって表すことができる。

次のコードは、アプリケーションがハードウェア固有のエフェクトを列挙して、Microsoft® SideWinder® ジョイスティックによりサポートされる固有のエフェクトを探す例である。目的のエフェクトが見つからない場合は、アプリケーションは標準エフェクトのいずれかを代用する。

Const BasketballDribble = _
"{E84CD1AC-81FA-11D0-94AB-0080C74C7E95}"
Dim diEnumEffects as DirectInputEnumEffects
Dim EffGuid As String
Dim i as Integer

' diDev は DirectInputDevice オブジェクトである。
Set diEnumEffects = didev.GetEffectsEnum(DIEFT_HARDWARE)
For i = 1 To diEnumEffects.GetCount
If diEnumEffects.GetEffectGuid(i) = BasketballDribble Then
EffGuid = BasketballDribble
Exit For
End If
Next i
If EffGuid <> BasketballDribble Then
EffGuid = "GUID_Sine"
' ここで、列挙されたドリブルのパラメータを設定する。
End If

' 最後に EffGuid を DirectInputDevice.CreateEffect に渡す。


ファイルからのエフェクトの読み込み

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic は、エフェクト ファイルをサポートしていない。

[C++]

DirectX SDK で提供される Force Editor、または同じファイル フォーマットを使用する別のアプリケーションを使って、エフェクトをデザインし、ファイルに保存することができる。実行時にこれらのエフェクトを読み込むことで、任意のアプリケーションで使用することができる。

エフェクトを読み込むには、IDirectInputDevice7::EnumEffectsInFile メソッドを呼び出す。デフォルトでは、列挙は標準の DirectInput エフェクトに限定されるが、DIFEF_INCLUDENONSTANDARD フラグを設定することで、これ以外のエフェクトを列挙できる。また、DIFEF_MODIFYIFNEEDED フラグを設定すると、必要に応じて、エフェクトがデバイスに対して作用するように、各エフェクトのパラメータの変更を DirectInput に指示することができる(たとえば、2 つの軸に対して作成されたエフェクトを、単一軸の車のハンドルに対して作用させることができる)。

次のサンプル コードでは、最初の 3 つの標準エフェクトがファイルから読み込まれ、DirectInputEffect オブジェクトとして作成される。

// g_lpdid7 は、フォース フィードバック デバイスへの有効な
// IDirectInputDevice7 ポインタである。

// エフェクト ポインタの配列は、グローバルに宣言される。
LPDIRECTINPUTEFFECT pEff[3];
.
.
.
g_lpdid7->EnumEffectsInFile("FEdit1.ffe", EnumEffectsInFileProc,
NULL, DIFEF_MODIFYIFNEEDED);
.
.
.

以下のコールバック プロシージャは、DIENUM_STOP が返されるまで、エフェクト ファイル内のエフェクトごとに呼び出される。

BOOL CALLBACK EnumEffectsInFileProc(LPCDIFILEEFFECT lpdife,
        LPVOID pvRef)

    {
HRESULT hr;
static int  i;

//  DIFEF_MODIFYIFNEEDED フラグが渡されたので、
// エフェクト パラメータは lpdife->lpDiEffect に変更される。

hr = g_lpdid7->CreateEffect(lpdife->GuidEffect,
lpdife->lpDiEffect,
&pEff[i], NULL);
if (FAILED(hr))
        {
// エラー処理
        }
if (++i > 2) return DIENUM_STOP;
else return DIENUM_CONTINUE;
    }


サポートされるエフェクトについての情報

[C++]

IDirectInputDevice7::GetEffectInfo メソッドを使うと、GUID が判明しているエフェクトについて、そのデバイスのサポート情報を取得できる。このメソッドは、DIEFFECTINFO 構造体で返される情報と同じ情報を列挙中に取得する。詳細については、「エフェクトの列挙」を参照すること。

次のサンプル コードは、EffectGuid 変数に GUID が格納されているエフェクトに関する情報を取得し、エフェクトを停止または再起動せずにエフェクトの方向を変更できるかどうかを調べる。

DIEFFECTINFO diEffectInfo;
diEffectInfo.dwSize = sizeof(DIEFFECTINFO);
lpdid2->GetEffectInfo(&diEffectInfo, EffectGuid);
if (diEffectInfo.dwDynamicParams & DIEP_DIRECTION)
{
// パラメータは動的にリセットできる。
}
[Visual Basic]

DirectX for Visual Basic では、サポートされるエフェクトに関する情報は、DirectInputEnumEffects 列挙オブジェクトから取得しなければならない。「エフェクトの列挙」を参照すること。

次のサンプル コードは、最初に列挙されたエフェクトに関する情報を取得して、そのエフェクトを停止または再起動せずにエフェクトの方向を変更できるかどうかを調べる。

' diEnumEffects は初期化された DirectInputEnumEffects オブジェクトである。
Dim params As Long
params = diEnumEffects.GetDynamicParams(1)
If params And DIEP_DIRECTION Then
Debug.Print "エフェクトの方向は動的である。"
End If


エフェクトの生成

[C++]

エフェクト オブジェクトを生成するには、IDirectInputDevice7::CreateEffect メソッドを使用する。次のサンプル コードで、pdev2 はインターフェイスのインスタンスを指している。この例では、半秒間に全力でジョイスティックをユーザーから離れる方向へ引くという、非常に単純なエフェクトが生成される。

HRESULT hr;
LPDIRECTINPUTEFFECT lpdiEffect; // 生成されるエフェクトへのポインタを受け取る。
DIEFFECT diEffect;        // 生成されるエフェクト用のパラメータ。

DWORD      dwAxes[2] = { DIJOFS_X, DIJOFS_Y };
LONG       lDirection[2] = { 18000, 0 };

DICONSTANTFORCE diConstantForce;

diConstantForce.lMagnitude = DI_FFNOMINALMAX;  // 最大フォース。

diEffect.dwSize = sizeof(DIEFFECT);
diEffect.dwFlags = DIEFF_POLAR | DIEFF_OBJECTOFFSETS;
diEffect.dwDuration = 0.5 * DI_SECONDS;
diEffect.dwSamplePeriod = 0;               // デフォルト値
diEffect.dwGain = DI_FFNOMINALMAX;         // スケーリングなし
diEffect.dwTriggerButton = DIEB_NOTRIGGER; // ボタン応答ではない。
diEffect.dwTriggerRepeatInterval = 0;   // 利用できない。
diEffect.cAxes = 2;
diEffect.rgdwAxes = &dwAxes;
diEffect.rglDirection = &lDirection;
diEffect.lpEnvelope = NULL;
diEffect.cbTypeSpecificParams = sizeof(DICONSTANTFORCE);
diEffect.lpvTypeSpecificParams = &diConstantForce;

hr = pdev2->CreateEffect(GUID_ConstantForce,
&diEffect,
&lpdiEffect,
NULL);

このメソッド呼び出しでは、最初のパラメータは、生成されるエフェクトに関連付けられたサポートされるエフェクトを表す。この例では、Dinput.h で定義済みの GUID のうちの 1 つを使用している。定義済みの GUID を使用する場合、デバイスがこのエフェクトをサポートしなければ呼び出しは失敗する。

第 2 のパラメータは、DIEFFECT 構造体に指定されているパラメータを設定する。

第 3 のパラメータは、呼び出しが成功した場合に、エフェクト オブジェクトへのポインタを受け取る。

DIEFF_POLAR フラグは、フォースの方向に使用する座標の種類を指定する (「エフェクトの方向」を参照すること)。このフラグは DIEFF_OBJECTOFFSETS と組み合わされる。これは、ほかのメンバで使用されるボタンや軸も、このデバイスの DIDATAFORMAT 構造体の中でオフセットによって識別される、ということを示す。この代わりに DIEFF_OBJECTIDS フラグを使用することができる。このフラグは、オブジェクトが IDirectInputDevice7::EnumObjects メソッドで列挙されたとき、そのオブジェクトに対して返される DIDEVICEOBJECTINSTANCE 構造体の dwType メンバによってボタンと軸が識別される、ということを意味している。

DIEFFECT 構造体のメンバの詳細については、「エフェクトの方向」を参照すること。

[Visual Basic]

エフェクト オブジェクトを生成するには、DirectInputDevice.CreateEffect メソッドを使用する。次のサンプル コードでは、didev はDirectInputDevice オブジェクトを指している。この例では、半秒間に全力でジョイスティックをユーザーから離れる方向へ引くという、非常に単純なエフェクトが生成される。

Dim effectInfo As DIEFFECT
Dim objDIEffect As DirectInputEffect

With effectInfo

.constantForce.lMagnitude = 10000
.lGain = 10000
.lDuration = 500000
.x = 18000
.lTriggerButton = -1  ' トリガ ボタンなし
End With

didev.Acquire
Set objDIEffect = didev.CreateEffect("GUID_ConstantForce", effectInfo)

最初のパラメータには、事前定義された GUID の 1 つ、または、ハードウェア ドキュメントや DirectInputEnumEffects.GetEffectGuid メソッドで列挙されたエフェクトとして取得された、文字列形式の実際の GUID を使用できる。

DIEFFECT 型のうち使用するメンバは、エフェクトの種類によって異なる。コンスタント フォースは、単一のタイプ固有のパラメータのみを要求する、最も単純なフォースである。lGain、lDuration、および lTriggerButton の各メンバは、すべてのエフェクトに設定しなければならない。これらのメンバのデフォルト値はゼロであるが、通常は適切ではないためである。

デフォルトでは、エフェクトの方向は極座標で表される。つまり、DIEFFECT.x がフォースの来る方向を 100 分の 1 度単位で保持し、DIEFFECT.y はゼロでなければならない。

エフェクトは作成時にデバイスに自動的にダウンロードされる。これにより、デバイスは満杯ではなく、排他協力レベルで取得される。


エフェクトの方向

[C++]

1 つまたはそれ以上の軸に対して方向を定義することができる。マウスとジョイスティックの場合と同様に、x 軸は左から右へと増加し、y 軸は遠くから近くへと増加する。3 次元デバイスでは、z 軸は上方から下方へと増加する。

エフェクトの方向は、エフェクトが来る方向である。y 軸の負側に沿った方向でのエフェクトは、スティックを y 軸の正側に沿って (ユーザーに向かって) 押そうとする。方向の軸値を視覚的にとらえるには、ユーザーがデバイスに反対に作用する力を加えているところを想像してみればよい。エフェクトを打ち消すためにユーザーがスティックを左方向に押さなければならない場合、このエフェクトは「左」方向である。つまり、このエフェクトは x 軸の負側にある。

方向は "極" 座標、"球面" 座標、または、"デカルト" 座標で表すことができる。

極座標は、エフェクトに対して設定されたゼロ地点 (真北) から時計回りに、実角度の 100 倍の単一角度で表される。通常これは負側の y 軸、すなわち、ユーザーから遠ざかる方向である。したがって、極座標 9,000 のエフェクトは通常、東の方向つまりユーザーの右側の方向を持つ。このエフェクトを打ち消すには、ユーザーは右側へ力を加えなければならない。

球面座標も実角度の 100 倍で表されるが、2 つまたはそれ以上の角度を含むことがある。それぞれの角度について、方向は次の軸の正方向に回転する。3 次元デバイスの場合は、第 1 の角度は、通常正側の x 軸から正側の y 軸に向かって (東から時計回りに) 回転し、第 2 の角度は正側の z 軸に向かって (下方へ) 回転する。したがって、方向が (0, 0) のフォースはユーザーの右側の方向であり、机面と平行になる。第 1 の角度が 27,000 で第 2 の角度が 4,500 の方向とは、ユーザーからまっすぐに離れながら (東から時計回りに 270 度)、床に向かう (机面から下方へ 45 度の角度) 方向である。この方向のフォースを打ち消すには、前方へ押し出しながら下方へ押し下げなくてはならない。

デカルト座標は 3 次元ベクトルに似ている。中心を始点 (0,0) とするグラフ用紙に直線を引くと、その直線の方向は、始点からの距離とは関係なく、直線が通る任意の座標により定義することができる。したがって、方向 (1, -2) と方向 (5, -10) はまったく同じものとなる。

注 : フォース フィードバック エフェクトの生成に使用する座標は方向のみを定義し、マグニチュードや距離は定義しない。

エフェクトを生成または変更するときは、DIEFFECT 構造体の cAxes、rgdwAxes、および rglDirection メンバを使用して、フォースの方向を指定する。

cAxes メンバは、次に続く 2 つのメンバが指す配列の要素の数を指示するだけである。

rgdwAxes が指す配列により、軸が識別される。DIEFF_OBJECTOFFSETS フラグが設定されていれば、軸はデータ形式構造体内のオフセットによって指定される。これらのオフセットは DIJOFS_* を使って非常に簡単に指定される (これらの値については、「ジョイスティック デバイス定数」を参照すること。

最後に、rglDirection メンバはフォースの方向を指定する。

注 : cAxes および rgdwAxes メンバは一度設定すると、変更することはできない。エフェクトは常に同一の軸リストを持つ。

デカルト座標、極座標、球面座標のどれを使用する場合でも、rgdwAxes が指す配列にある軸の数とまったく同じ数の要素を rglDirection に用意しなければならない。

極座標システムでは、「北 (ゼロ度)」はベクトル (0, -1) 上にあり、このベクトルの要素は rgdwAxes が指す軸リストの要素に対応する。通常はこれらの軸は x と y なので、北はそのまま y 軸の負側の方向になる。すなわち、ユーザーから離れる方向になる。rglDirection の最後の要素はゼロでなければならない。

「エフェクトの生成」での例では、2 次元フォースの方向は極座標で定義される。この例ではフォースは南方向、すなわちユーザーの方向から来ているので、ユーザーがフォースを打ち消すにはスティックを手前に引き寄せなくてはならない。南の方向は北から時計回りに 180 度であり、次のように割り当てることができる

LONG       lDirection[2] = { 18000, 0 };

より明確にするために、割り当ては次のように表すこともできる。

LONG lDirection[2] = { 180 * DI_DEGREES, 0 };

球面座標については、3 軸デバイスで作業していると仮定した場合、同じ方向は次のように割り当てられる。

LONG lDirection[3] = { 90 * DI_DEGREES, 0, 0 }

DIEFFECT 構造体では、第 1 の角度は、方向 (1, 0) から方向 (0,1) へ回転した実角度の 100 倍で計測される。第 2 の角度は (0, 0, 1) へ回転する実角度の 100 倍で計測される。この場合も、ベクトル表記法の要素は rgdwAxes メンバが指す配列の要素に対応する。この配列の要素が、順に x 軸、y 軸、および z 軸を表すと仮定しよう。原点は x = 1、y = 0 である、すなわち、ユーザーの右側にある。回転の方向は、y 軸の正側 ( 0, 1) に向かう、すなわち、ユーザー側へ、または時計回りに向かう。この例におけるフォースは、右から時計回りに 90 度である、すなわち、南方向である。lDirection の第 2 の要素が 0 なので、第 3 軸上での回転はない。

デカルト座標でこれと同じことを実現するにはどうしたらよいだろうか。dwFlags メンバの DIEFF_CARTESIAN フラグを使用すると仮定すれば、次のように方向を指定することになる。

LONG       lDirection[2] = { 1, 0 };

繰り返すが、この配列の要素は rgdwAxes が指す配列にリストされている軸に対応している。この例では x 軸にゼロを設定し、y 軸に 1 を設定している。すなわち、方向は直接 y 軸の正側上、または南にある。

エフェクトの方向についての理論は、理解するのは難しいかもしれないが、実践してみればかなり容易に理解できる。サンプル コードがあるので、「エフェクト方向設定の実例」を参照すること。

[Visual Basic]

DirectX for Visual Basic は、x 軸と y 軸での 2 軸エフェクトをサポートしている。

エフェクトの方向は、エフェクトが来る方向である。y 軸の負側に沿った方向でのエフェクトは、スティックを y 軸の正側に沿って (ユーザーに向かって) 押そうとする。方向の軸値を視覚的にとらえるには、ユーザーがデバイスに反対に作用する力を加えているところを想像してみればよい。エフェクトを打ち消すためにユーザーがスティックを左方向に押さなければならない場合、このエフェクトは「左」方向である。つまり、このエフェクトは x 軸の負側にある。

方向は "極" 座標、"球面" 座標、または、"デカルト" 座標で表すことができる。デフォルトでは、極座標が使用される。方向は DIEFFECT 型の x メンバに指定される。この場合、y メンバは常にゼロである。デカルト座標を使用するには、lFlags メンバの DIEFF_CARTESIAN を指定して、x と y の両方を指定する必要がある。

極座標は、エフェクトに対して設定されたゼロ地点 (真北) から時計回りに、実角度の 100 倍の単一角度で表される。通常これは負側の y 軸、すなわち、ユーザーから遠ざかる方向である。したがって、極座標 9,000 のエフェクトは通常、東の方向つまりユーザーの右側の方向を持つ。このエフェクトを打ち消すには、ユーザーは右側へ力を加えなければならない。

デカルト座標は 3 次元ベクトルに似ており、3 次元環境においてフォースをユーザーの方向設定に一致させる場合に非常に便利である。中心を始点 (0,0) とするグラフ用紙に直線を引くと、その直線の方向は、始点からの距離とは関係なく、直線が通る任意の座標により定義することができる。したがって、方向 (1, -2) と方向 (5, -10) はまったく同じものとなる。

注 : フォース フィードバック エフェクトの生成に使用する座標は方向のみを定義し、マグニチュードや距離は定義しない。

次のコードは、DirectInputEffect オブジェクトの dieff で表されるフォースの方向を反転する例である。dieff は、グローバル DIEFFECT 型の effectinfo を使って作成済みである。

effectinfo.lFlags = DIEFF_CARTESIAN
effectinfo.X = effectinfo.X * -1
effectinfo.Y = effectinfo.Y * -1
Call dieff.SetParameters(effectinfo, DIEP_DIRECTION)

DirectX for Visual Basic は、条件による方向設定をサポートしていない。


エフェクト方向設定の実例

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

単一軸エフェクト

単一軸エフェクトの方向の設定は、実際に指定するものが何もないので、極めて単純である。DIEFF_CARTESIAN フラグを DIEFFECT 構造体の dwFlags メンバに設定し、値がゼロの単一の LONG を指す rglDirection を設定する。

次のコードは、x 軸エフェクトの方向と軸パラメータを設定する例である。

DIEFFECT eff;
LONG   lZero = 0;            // 方向なし。
DWORD  dwAxis = DIJOFS_X;        // x 軸エフェクト。

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes = 1;               // 1 つの軸。
eff.dwFlags =
DIEFF_CARTESIAN | DIEFF_OBJECTOFFSETS;   // フラグ
eff.rglDirection = &lZero;         // 方向。
eff.rgdwAxes = &dwAxis;          // エフェクトの軸。

極座標での 2 軸エフェクト

極座標 2 軸エフェクトの方向の設定は少し複雑である。DIEFF_POLAR フラグを dwFlags に設定し、2 つの LONG からなる 1 つの配列を指すように rglDirection を設定する。こうすると、この配列の第 1 の要素が、エフェクトが来る方向になる。この配列の第 2 の要素はゼロでなくてはならない。

次のコードは、東から来る 2 軸エフェクトの方向と軸パラメータを設定する例である

DIEFFECT eff;
LONG   rglDirection = { 90 * DI_DEGREES, 0 }; // 北から 90 度、
// すなわち東。
DWORD  rgdwAxes[2] = { DIJOFS_X, DIJOFS_Y }; // x 軸と y 軸

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes = 2;                 // 2 つの軸
eff.dwFlags =
DIEFF_POLAR | DIEFF_OBJECTOFFSETS;     // フラグ。
eff.rglDirection = rglDirection;        // 方向
eff.rgdwAxes = rgdwAxes;            // エフェクトの軸

デカルト座標での 2 軸エフェクト

デカルト座標 2 軸エフェクトの方向の設定は少し複雑である。DIEFF_CARTESIAN フラグを dwFlags に設定し、ここでも、2 つの LONG からなる 1 つの配列を指すように rglDirection を設定する。このときの配列の第 1 要素は方向ベクトルの x 座標で、第 2 要素は y 座標である。

次のコードは、東から来る 2 軸エフェクトの方向と軸パラメータを設定する例である

DIEFFECT eff;
LONG   rglDirection = { 1, 0 };        // 正値 x = 東
DWORD  rgdwAxes[2] = { DIJOFS_X, DIJOFS_Y }; // x 軸と y 軸

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes = 2;                 // 2 つの軸
eff.dwFlags =
DIEFF_CARTESIAN | DIEFF_OBJECTOFFSETS;   // フラグ
eff.rglDirection = rglDirection;        // 方向
eff.rgdwAxes = rgdwAxes;            // エフェクトの軸


エンベロープとオフセット

エンベロープとオフセットを使って、いくつかの基本的マグニチュードを変更することができる。概要については、「フォース フィードバックの基本概念」を参照すること。

[C++]

エフェクトの生成または変更の際にエンベロープを適用するには、DIENVELOPE 構造体を初期化して、この構造体へのポインタを DIEFFECT 構造体の lpEnvelope メンバに設定する。

どのエフェクトがエンベロープをサポートするかを決定するのはデバイス ドライバである。通常は、コンスタント フォース、傾斜フォースおよび周期的フォースにエンベロープを適用できるが、条件には適用できない。特定のフォースがエンベロープをサポートするかどうかを判定するには、IDirectInputDevice7::GetEffectInfo メソッドを呼び出し、DIEFFECTINFO 構造体の dwStaticParams メンバにある DIEP_ENVELOPE フラグをチェックする。

オフセットを適用するには、DIEFFECT 構造体の lpvTypeSpecificParams メンバが指す DIPERIODIC 構造体または DICONDITION 構造体の lOffset メンバを設定する。周期的エフェクトの場合、オフセットの絶対値とエフェクトのマグニチュードを足した値が DI_FFNOMINALMAX を超えてはならない。

オフセットをコンスタント フォースや傾斜フォースに適用することはできない。これらのフォースの場合、マグニチュードを変更すれば同じエフェクトを得ることができる。

[Visual Basic]

エフェクトの生成または変更の際にエンベロープを適用するには、DIEFFECT 型の bUseEnvelope メンバを TRUE に設定し、DIENVELOPE 型の envelope メンバを初期化する。

どのエフェクトがエンベロープをサポートするかを決定するのはデバイス ドライバである。通常は、コンスタント フォース、傾斜フォースおよび周期的フォースにエンベロープを適用できるが、条件には適用できない。特定のフォースがエンベロープをサポートするかどうかを判定するには、DirectInputEnumEffects.GetStaticParams メソッドを呼び出し、返された値の DIEP_ENVELOPE フラグをチェックする。

オフセットを適用するには、DIEFFECT の periodic メンバや condition メンバで使用される、DIPERIODICFORCE 型または DICONDITION 型の lOffset メンバを設定する。周期的エフェクトの場合、オフセットの絶対値とエフェクトのマグニチュードを足した値が 10,000 を超えてはならない。

オフセットをコンスタント フォースや傾斜フォースに適用することはできない。これらのフォースの場合、マグニチュードを変更すれば同じエフェクトを得ることができる。


エフェクトのプレイバック

[C++]

エフェクトのプレイバックを開始する主な方法は 2 つある。IDirectInputEffect::Start メソッドを呼び出して手動で開始する方法と、ボタン押下への応答で自動的に開始する方法である。DIEP_START フラグを指定して IDirectInputEffect::SetParameters メソッドを呼び出すことでエフェクトを変更するときにも、プレイバックが開始する。

dwIterations パラメータに INFINITE を渡すと、エンベロープを適用しながらエフェクトのプレイバックを反復させることができる。エンベロープを反復することなくエフェクトを反復したいとき (たとえば、最初に強いキックをした後、動悸を静めるというような場合) は、dwIterations に 1 を設定し、次に DIEFFECT 構造体の dwDuration メンバに INFINITE をセットすればよい(これは IDirectInputDevice7::CreateEffect メソッドに渡される構造体である)。

注 : デバイスによっては、エフェクトの複数回の繰り返しが不可能で、Start メソッドへのパラメータ dwIterations に値 1 しか認めないものもある。Start からの戻り値を常にチェックして、エフェクトが正常に再生されたかどうかを確認しなければならない。

エフェクトをボタン押下に割り付けるには、DIEFFECT 構造体の dwTriggerButton メンバを設定する。ボタンが押下されているときのプレイバック間に遅延を加えたいならば、その遅延値を dwTriggerRepeatInterval メンバに設定する。この遅延は、1 つのプレイバックの終了から次のプレイバックの開始までの間隔のことで、マイクロ秒単位で表される。

注 : デバイスによっては、複数回のエフェクトを同じボタンで発生させることができないものもある。2 つ以上のエフェクトを 1 つのボタンに割り付けると、最後にダウンロードされたエフェクトが、発生するエフェクトとなる。また、トリガの反復間隔はサポートされていない。

エフェクトのトリガ ボタンへの割り付けを解除するには、IDirectInputEffect::Unload メソッドを呼び出すか、または DIEB_NOTRIGGER に設定されている dwTriggerButton に、このエフェクト用のパラメータを設定するか、どちらかの操作を行わなければならない。

割り付けたエフェクトは、ほかのすべてのエフェクトと同様に、アプリケーションがデバイスへのアクセス権を失うと失われる。再びこれらのエフェクトを有効にするには、アプリケーションがデバイスを再取得すると同時にこれらのエフェクトをダウンロードする。この処理はトリガに割り付けていないエフェクトでは不必要である。なぜなら、この種のエフェクトは、Start メソッドが呼び出されるときはいつも、必要に応じて自動的にダウンロードされるからである。

エフェクトの継続時間が有限で、エフェクトが Start メソッドへの呼び出しによって開始する場合、継続時間が過ぎるとエフェクトの再生は終了する。エフェクトの継続時間が INFINITE に設定されていた場合、プレイバックが終了するのは、IDirectInputEffect::Stop メソッドが呼び出されたときのみである。トリガボタンに割り付けたエフェクトはそのボタンを押すと開始し、そのボタンを離すか、継続時間が過ぎるか、どちらか早い方の時点で終了する。

[Visual Basic]

エフェクトのプレイバックを開始する主な方法は 2 つある。DirectInputEffect.Start メソッドを呼び出して手動で開始する方法と、ボタン押下への応答で自動的に開始する方法である。DIEP_START フラグを指定して DirectInputEffect.SetParameters メソッドを呼び出すことでエフェクトを変更するときにも、プレイバックは開始する。

Start メソッドの iterations パラメータに -1 を渡すと、エンベロープを適用しながらエフェクトのプレイバックを反復させることができる。エンベロープを反復することなくエフェクトを反復したいとき (たとえば、最初に強いキックをした後、動悸を静めるというような場合) は、iterations に 1 を設定し、次に 型の lDuration メンバに -1 を設定すればよい (これは DirectInputDevice.CreateEffect メソッドに渡されるタイプである)。

注 : デバイスによっては、エフェクトの複数回の繰り返しが不可能で、Start メソッドへのパラメータ iterations に値 1 しか認めないものもある。

エフェクトをボタンに割り付けるには、DIEFFECT 型の lTriggerButton メンバを設定する。ボタンが押下されているときのプレイバック間に遅延を加えたいならば、その遅延値を lTriggerRepeatInterval メンバに設定する。この遅延は、1 つのプレイバックの終了から次のプレイバックの開始までの間隔のことで、マイクロ秒単位で表される。

注 : デバイスによっては、複数回のエフェクトを同じボタンで発生させることができないものもある。2 つ以上のエフェクトを 1 つのボタンに割り付けると、最後にダウンロードされたエフェクトが、発生するエフェクトとなる。また、トリガの反復間隔はサポートされていない。

エフェクトのトリガ ボタンへの割り付けを解除するには、DirectInputEffect.Unload メソッドを呼び出すか、または、-1 に設定されている lTriggerButton にエフェクトのパラメータを設定するか、どちらかの操作を行わなければならない。

割り付けたエフェクトは、ほかのすべてのエフェクトと同様に、アプリケーションがデバイスへのアクセス権を失うと失われる。再びこれらのエフェクトを有効にするには、アプリケーションがデバイスを再取得すると同時にこれらのエフェクトをダウンロードする。この処理はトリガに割り付けていないエフェクトでは不必要である。なぜなら、この種のエフェクトは、Start メソッドが呼び出されるときはいつも、必要に応じて自動的にダウンロードされるからである。

エフェクトの継続時間が有限で、エフェクトが Start メソッドへの呼び出しによって開始する場合、継続時間が過ぎるとエフェクトの再生は終了する。エフェクトの継続時間が -1 に設定されていた場合、プレイバックが終了するのは、DirectInputEffect.Stop メソッドが呼び出されたときのみである。トリガボタンに割り付けたエフェクトはそのボタンを押すと開始し、そのボタンを離すか、継続時間が過ぎるか、どちらか早い方の時点で終了する。


エフェクトのダウンロードとアンロード

エフェクトは再生する前にデバイスにダウンロードしなければならない。エフェクトのダウンロードとは、ドライバにエフェクトのプレイバックの準備をするように通知することである。ダウンロードの方法を決定するのはまったくドライバに任せられる。一般に、ドライバはエフェクトのパラメータをハードウェア メモリに置き、デバイスとシステムの間のデータ順次転送を最小限に抑える。これにより、遅延時間が削減される。このことは、"発射" ボタンのように、トリガへの応答で機能する条件とエフェクトにとっては特に意味がある。デバイスが軸移動とボタン押下に応答するためにシステムとまったくやりとりを行う必要がない、というのが理想的だろう。

デバイスが満杯ではなくしかも排他協調レベルで取得されている場合には、エフェクトの生成時にダウンロードが自動的に行われる。エフェクトを開始、またはエフェクトのパラメータを変更するときも、ダウンロードはデフォルトで行われる。

[C++]

パラメータを変更するときに DIEP_NODOWNLOAD フラグを指定すれば、引き続き IDirectInputEffect::Download メソッドを使用してエフェクトのダウンロードやアップロードを行わなければならない。

デバイスが未取得状態のとき (たとえば、デバイスが排他フォアグラウンド協調レベルで取得されていて、アプリケーションがバックグラウンドに移行するとき)、エフェクトはアンロードされているので、アプリケーションがフォアグラウンドを再取得するときに再びエフェクトをダウンロードしなければならない。先に述べたように、エフェクトのダウンロードは、IDirectInputEffect::Start メソッドを呼び出すと自動的に行われる。しかし、デバイスを再取得すると同時にすべてのエフェクトをダウンロードするかどうかを選択することはできる。Start メソッドは通常トリガ ボタンに割り付けたエフェクトでは呼び出されないので、この種のエフェクトは必ずダウンロードする必要がある。

エフェクトのダウンロード中にアプリケーションが DIERR_DEVICEFULL エラーを受けたら、古いエフェクトをアンロードして新しいエフェクトのためのスペースを確保する必要がある。IDirectInputEffect::Unload メソッドを呼び出せば、デバイスから 1 つのエフェクトを削除することができる。また、IDirectInputDevice7::SendForceFeedbackCommand メソッドを呼び出してデバイスをリセットすれば、すべてのエフェクトを削除することもできる。

[Visual Basic]

パラメータを変更するときに DIEP_NODOWNLOAD フラグを指定すれば、引き続き DirectInputEffect.Download メソッドを使用してエフェクトのダウンロードやアップロードを行わなければならない。

デバイスが未取得状態のとき (たとえば、デバイスが排他フォアグラウンド協調レベルで取得されていて、アプリケーションがバックグラウンドに移行するとき)、エフェクトはアンロードされているので、アプリケーションがフォアグラウンドを再取得するときに再びエフェクトをダウンロードしなければならない。先に述べたように、エフェクトのダウンロードは、DirectInputEffect.Start メソッドを呼び出すと自動的に行われる。しかし、デバイスを再取得すると同時にすべてのエフェクトをダウンロードするかどうかを選択することはできる。Start メソッドは通常トリガ ボタンに割り付けたエフェクトでは呼び出されないので、この種のエフェクトは必ずダウンロードする必要がある。

エフェクトのダウンロード中にアプリケーションが DIERR_DEVICEFULL エラーを受けたら、古いエフェクトをアンロードして新しいエフェクトのためのスペースを確保する必要がある。DirectInputEffect.Unload メソッドを呼び出せば、デバイスから 1 つのエフェクトを削除することができる。また、DirectInputDevice.SendForceFeedbackCommand メソッドを呼び出してデバイスをリセットすれば、すべてのエフェクトを削除することもできる。

フォース フィードバック デバイスを生成すると、ハードウェアとドライバがリセットされるので、存在していたエフェクトすべてが消去される。


エフェクトの変更

[C++]

エフェクトの再生中でもエフェクトのパラメータを変更することができる場合がある。これは IDirectInputEffect::SetParameters メソッドを使用して行う。

DIEFFECTINFO 構造体の dwDynamicParams メンバは、エフェクトの再生中でも変更できるエフェクトのパラメータを通知する。エフェクトの再生中には変更できないエフェクトのパラメータを変更しようとして、エフェクトが実際にまだ再生しているときは、通常、DirectInput はエフェクトを停止させ、パラメータを更新し、エフェクトを再スタートさせる。この DirectInput のデフォルトの動作を無効にするには、DIEP_NORESTART フラグを渡せばよい。

次の C++ のプログラム例では、「エフェクトの生成」にあるサンプル プログラムでセットされたコンスタント フォースのマグニチュードを変更する。

DIEFFECT    diEffect;      // エフェクト用のパラメータ。
DICONSTANTFORCE diConstantForce;
// タイプ固有パラメータ。

diConstantForce.lMagnitude = 5000;
diEffect.dwSize = sizeof(DIEFFECT);
diEffect.cbTypeSpecificParams = sizeof(DICONSTANTFORCE);
diEffect.lpvTypeSpecificParams = &diConstantForce;
hr = lpdiEffect->SetParameters(&diEffect, DIEP_TYPESPECIFICPARAMS);

このフラグにより、DIEFFECT 構造体からのデータ転送は、関連するメンバに限られることが保証される。したがって、この構造体全体を初期化する必要がなくなり、デバイスに送信する必要のあるデータの量が最小限で済む。

[Visual Basic]

エフェクトの再生中でもエフェクトのパラメータを変更することができる場合がある。これを行うには、DirectInputEffect.SetParameters メソッドを使用する。

エフェクトの再生中でも変更できるエフェクトのパラメータを調べるには、DirectInputEnumEffects.GetDynamicParams メソッドを呼び出す。

エフェクト再生中には変更できないエフェクトのパラメータを変更しようとして、エフェクトが実際にまだ再生しているときは、通常、DirectInput はエフェクトを停止させ、パラメータを更新し、エフェクトを再スタートさせる。この DirectInput のデフォルトの働きを無効にするには、SetParameters に DIEP_NORESTART フラグを渡せばよい。

次のコードは、DirectInputEffect オブジェクトの dieff で表されるコンスタント フォースのマグニチュードを変更する例である。このオブジェクトは、グローバルな DIEFFECT 型の effectinfo を使って作成済みである。

effectinfo.constantForce.lMagnitude = 5000
Call dieff.SetParameters(effectinfo, DIEP_TYPESPECIFICPARAMS)

DIEFFECT の condition、constantforce、periodicforce、および rampforce の各メンバを変更する場合は、DIEP_TYPESPECIFICPARAMS フラグを設定する必要がある。


ゲイン

フォースを及ぼすデバイスの種類に応じて、エフェクトのフォースの大きさに差を付けたい場合があるだろう。たとえば、ある軸に対して最大 n ニュートンのフォースを生み出すデバイスでアプリケーションのエフェクトが正しく働くと思われるときは、より多くのフォースを生み出すデバイス用にゲインを調整したいことがあるだろう (軸のフォースの最大値を増やすためにゲインを使用することはできないので、生み出すフォースが小さいデバイスに対して、適切な値を基本的エフェクト マグニチュードに設定すべきである)。

また、ゲインを使って、ハードウェアで定義されたエフェクトのマグニチュードを減少させることもできる。

[C++]

軸やボタンなどのデバイス オブジェクトによって発生するフォースは、オブジェクトの列挙時に DIDEVICEOBJECTINSTANCE 構造体の dwFFMaxForce メンバに格納されて返される (「デバイス オブジェクトの列挙」を参照すること)。

IDirectInputDevice7::SetProperty メソッドを使用して、デバイス全体のゲインを設定することができる。

個別のエフェクトを作成するときは、DIEFFECT 構造体の dwGain メンバに値を設定することで、エフェクトにゲインを設定しなければならない(dwGain がゼロならば、そのエフェクトは感じられない)。この値は、dwFlags パラメータに DIEP_GAIN を指定して IDirectInputEffect::SetParameters を呼び出すことで、後から変更することができる。

[Visual Basic]

DirectInputDevice.SetProperty メソッドを使用して、デバイス全体のゲインを設定することができる。

個別のエフェクトを作成するときは、DIEFFECT 型の lGain メンバに値を設定することで、エフェクトにゲインを設定しなければならない(lGain がゼロならば、そのエフェクトは感じられない)。この値は、flags パラメータに DIEP_GAIN を指定して DirectInputEffect.SetParameters を呼び出すことで、後から変更することができる。

デバイス ゲインを設定する目的は、アプリケーションにすべてのエフェクトのフォースを一括して制御させることである。たとえば、音響ミキサーのメイン ボリューム コントローラのように、フォース フィードバック エフェクトに必要とされる強度をユーザーに指定させるスライド コントローラをアプリケーションに付けたいと思うことがあるだろう。デバイス ゲインを設定すれば、ユーザーの好みに合わせて個別のエフェクトのゲインを、アプリケーションが調整する必要がなくなる。

1 つのゲイン値は 0 から 10,000 の範囲の値を取る。10,000 という値は、マグニチュードをスケーリングすべきでないということを示す。7,500 という値は、フォースの名目マグニチュードの 75% にフォースをスケーリングすべきであるということを意味している。その他の数値もこれに準じる。


フォース フィードバック状態

[C++]

IDirectInputDevice7::SendForceFeedbackCommand メソッドを使用すれば、デバイスのアクチュエータをオフ (再生しているエフェクトすべてを無視するのに有効) にし、エフェクトのプレイバックを中断または中止し、デバイスをリセットしてダウンロードしたすべてのエフェクトを削除することができる。

現在のフォース フィードバック状態を取得するには、IDirectInputDevice7::GetForceFeedbackState メソッドを使用する。このメソッドにより、アクチュエータが有効かどうか、プレイバックが中断状態かどうか、およびデバイスがリセットされたかどうかという情報が返される。また、さまざまなスイッチに関する情報や、現在デバイスに電源が入っているかどうかの情報も取得される。

[Visual Basic]

DirectInputDevice.SendForceFeedbackCommand メソッドを使用すれば、デバイスのアクチュエータをオフ (再生しているエフェクトすべてを無視するのに有効) にし、エフェクトのプレイバックを中断または中止し、デバイスをリセットしてダウンロードしたすべてのエフェクトを削除することができる。

現在のフォース フィードバック状態を取得するには、DirectInputDevice.GetForceFeedbackState メソッドを使用する。このメソッドにより、アクチュエータが有効かどうか、プレイバックが中断状態かどうか、およびデバイスがリセットされたかどうかという情報が返される。また、さまざまなスイッチに関する情報や、現在デバイスに電源が入っているかどうかの情報も取得される。


エフェクト オブジェクトの列挙

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic は、生成されるエフェクトの列挙をサポートしていない。

[C++]

プログラムに生成したすべてのエフェクトの実験や操作が必要になったときは、IDirectInputDevice7::EnumCreatedEffectObjects メソッドを利用することができる。現在のところ、このメソッドにはフラグがまったく定義されていないので、特定の種類のエフェクトに列挙を絞り込むことはできない。すべてのエフェクトが列挙されてしまう。

注 : このメソッドは生成されるエフェクトは列挙するが、デバイスによってサポートされるエフェクトは列挙しない。この 2 つのエフェクトの区別について詳細は、「エフェクトの列挙」を参照すること。

DirectInput のほかの列挙と同様に、EnumCreatedEffectObjects メソッドにはコールバック関数が必要である。この標準コールバック関数は、ドキュメントではプレースホルダ名 DIEnumCreatedEffectObjectsCallback で表されているが、異なる名前を付けてもよい。この関数は列挙されたエフェクトそれぞれについて呼び出される。この関数内では、どんな処理でも実行することができる。しかし、列挙の実行中は新しいエフェクトを生成しない方が安全である。

次に挙げるのは、コールバック関数のコーディングの 1 例である。ここでは、EnumCreatedEffectObjects メソッドへの呼び出しが行われている。コールバック関数の pvRef パラメータは、32 ビットの任意の値を取ることができる。この場合、このパラメータはデバイス インターフェイスへのポインタである。

HRESULT hr;
// LPDIRECTINPUTDEVICE lpdid;  // 初期化済み。

BOOL CALLBACK DIEnumCreatedEffectObjectsCallback(
LPDIRECTINPUTEFFECT peff, LPVOID pvRef);
{
LPDIRECTINPUTDEVICE pdid = pvRef; // 呼び出しデバイスへのポインタ。
DIEFFECT      diEffect;   // 生成されたエフェクト用のパラメータ。

diEffect.dwSize = sizeof(DIEFFECTINFO);
peff->GetParameters(&diEffect, DIEP_ALLPARAMS);
// パラメータのチェックまたは設定、あるいはその他の処理。
    .
    .
    .
} // コールバックの終了。

// コールバックの始動。
hr = lpdid->EnumCreatedEffectObjects(&EnumCreatedEffectObjectsCallback,
&lpdid, 0);


エフェクトのタイプ

ここでは、以下のフォース フィードバック エフェクト タイプについて説明する。

  • コンスタント フォース
  • 傾斜フォース
  • 周期的エフェクト
  • 条件
  • カスタム フォース
  • デバイス エフェクト


コンスタント フォース

コンスタント フォースは、一定のマグニチュードと継続時間を持つフォースのことである。

エンベロープをコンスタント フォースに適用して、フォースに形を与えることができる。たとえば、2,000 の名目マグニチュードと 2 秒の継続時間を持つエフェクトがあると仮定しよう。この場合、次の値を持つエンベロープを適用する。

アタック時間 | 0.5 秒
初期アタック レベル | 5,000
フェード時間 | 1 秒
フェード レベル | 0

エフェクトを再生すると、次の値が得られる。

経過時間 | マグニチュード
0.0 | 5,000
0.1 | 4,400
0.2 | 3,800
0.3 | 3,200
0.4 | 2,600
0.5 | 2,000
(保持の継続時間) | 2,000
1.0: | 2,000
1.1 | 1,800
1.2 | 1,600
1.3 | 1,400
1.4 | 1,200
1.5 | 1,000
1.6 | 800
1.7 | 600
1.8 | 400
1.9 | 200
2.0 | 0

コンスタント フォースにオフセットを適用することはできない。

[C++]

コンスタント フォースを生成するには、GUID_ConstantForce を IDirectInputDevice7::CreateEffect メソッドに渡す。DIEFFECTINFO 構造体のメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトが DIEFT_CONSTANTFORCE と等しいときは、IDirectInputDevice7::EnumEffects メソッドで取得したほかの任意の GUID を渡すことができる。この方法を使えば、騒乱をシミュレーションする "コンスタント" フォース (名前は "コンスタント (定常)" だが実際にはマグニチュードがランダムに変化する) など、業者が設計したハードウェア特有のフォースを使用することができる。

コンスタント フォースは、DICONSTANTFORCE 構造体を使ってマグニチュードを定義する。負のマグニチュードには、フォースの方向を反転するエフェクトがある。

[Visual Basic]

コンスタント フォースを生成するには、GUID_ConstantForce を DirectInputDevice.CreateEffect メソッドに渡す。DirectInputEnumEffects.GetType により返された値の下位バイトが DIEFT_CONSTANTFORCE に等しい場合は、DirectInputEnumEffects.GetEffectGuid メソッドにより取得されたほかの任意の GUID を渡すこともできる。この方法を使えば、騒乱をシミュレーションする "コンスタント" フォース (名前は "コンスタント (定常)" だが実際にはマグニチュードがランダムに変化する) など、業者が設計したハードウェア特有のフォースを使用することができる。

コンスタント フォースのマグニチュードは、DIEFFECT の constantForce メンバ内の DICONSTANTFORCE 型に格納される。負のマグニチュードには、フォースの方向を反転するエフェクトがある。


傾斜フォース

傾斜フォースは、定義済みの初期マグニチュードと終期マグニチュードおよび有限の継続時間を持つフォースのことである。傾斜フォースは、1 方向だけに延びる場合も、あるいは 1 方向に向かって強い勢いで始まり、弱まって、停止し、反対方向に強く進むという場合もある。

次の図は、マグニチュード -5,000 で始まり、マグニチュード 5,000 で終わる傾斜フォースを表している。

エンベロープを傾斜フォースに適用して、傾斜フォースを引き伸ばすことができる。次の図は、前の図の傾斜フォースにエンベロープ (緑で表してある) を適用するエフェクトを表している。

エンベロープの維持期間部分では、エフェクトのマグニチュードはエンベロープの適用前と同じ直線を描く。アタックとフェードの継続時間については、傾斜フォースの傾斜はアタック レベルとフェード レベルで変更される。

傾斜フォースにはオフセットを適用できない。

[C++]

傾斜フォースを生成するには、GUID_RampForce を IDirectInputDevice7::CreateEffect メソッドに渡す。DIEFFECTINFO 構造体のメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトが DIEFT_RAMPFORCE と等しい場合は、IDirectInputDevice7::EnumEffects メソッドで取得したほかの任意の GUID を渡すこともできる。この方法を使えば、業者が設計したハードウェア特有の傾斜フォースを使用することができる。

傾斜フォースは DIRAMPFORCE 構造体を利用して、フォースの初期マグニチュードと終期マグニチュードを定義することができる。一方、その継続時間は DIEFFECT 構造体によって定義される。継続時間を決して INFINITE に設定してはいけない。

[Visual Basic]

傾斜フォースを生成するには、GUID_RampForce を DirectInputDevice.CreateEffect メソッドに渡す。DirectInputEnumEffects.GetType により返された値の下位バイトが DIEFT_RAMPFORCE と等しい場合は、DirectInputEnumEffects.GetEffectGuid メソッドで取得されたほかの任意の GUID を渡すこともできる。この方法を使えば、業者が設計したハードウェア特有の傾斜フォースを使用することができる。

フォースの初期マグニチュードと終期マグニチュードは、DIEFFECT の rampForce メンバに含まれる DIRAMPFORCE 型で定義される。継続時間を無限にすることはできないので、DIEFFECT.lDuration は正の値でなければならない。


周期的エフェクト

周期的エフェクトは波形エフェクトである。DirectInput では、以下の形を定義している。

  • 正方形
  • サイン カーブ
  • コサイン カーブ
  • 三角形
  • アップ鋸歯 (SawtoothUp) － この波形は最大の正フォースに達した後、垂直に下降する。「フォース フィードバックの基本概念」の例を参照すること。
  • ダウン鋸歯 (SawtoothDown) － この波形は最大の負フォースに達した後、垂直に上昇する。

周期的エフェクトにはエンベロープを適用することができる。「フォース フィードバックの基本概念」の例を参照すること。

周期的エフェクトのフェーズとは、エフェクトが始まる波形上の点である。フェーズは 0 から 35,999 までの範囲で、実角度の 100 倍で計測される。次の表は、選択したフェーズ値 (度単位) がさまざまな波形上のどこにあるかを示している。Max は波の最上部 (+) または最底部 (-) であり、Mid は波の中間点である。これらの位置では、どちらの方向にもフォースは適用されていない。

 | 0 | 90 | 180 | 270
正方形 | +Max | +Max | -Max | -Max
サイン カーブ | Mid | +Max | Mid | -Max
三角形 | +Max | Mid | -Max | Mid
アップ鋸歯 | -Max | -Max/2 | Mid | +Max/2 (サイクルの反復の直前に +Max に達する)
ダウン鋸歯 | +Max | +Max/2 | Mid | -Max/2 (サイクルの反復の直前に -Max に達する)

ドライバにより、フェーズ値が直近のサポート値に丸められることがある。たとえば、ドライバによっては、サインエフェクトで 0 と 9,000 (コサインを生成するために) しかサポートせず、その他のエフェクトで 0 と 18,000 しかサポートしていないこともある。

[C++]

周期的フォースを生成するには、IDirectInputDevice7::CreateEffect メソッドの rguid パラメータに次に挙げる値のどれか 1 つを渡す。

  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown

DIEFFECTINFO 構造体のメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトが DIEFT_PERIODICY に等しい場合は、IDirectInputDevice7::EnumEffects メソッドで取得したほかの任意の GUID を渡してもよい。この方法を使えば、業者が設計したハードウェア特有のフォースを使用することができる。たとえば、スティックを小さい円形に回転する周期的エフェクトをサポートしているハードウェア デバイスなどがある。

周期的エフェクトのタイプ固有構造体は DIPERIODIC である。

周期的エフェクトの "周期" (DIPERIODIC.dwPeriod) と "サンプリング間隔" (DIEFFECT.dwSamplePeriod) を混同しないように注意すること。周期は 1 つの波のサイクル全体を実行するのに要する時間である。サンプリング間隔は、すべてのエフェクトと同様に、マグニチュードを実際に調整する間隔の最小時間である。

[Visual Basic]

周期的フォースを生成するには、DirectInputDevice.CreateEffect メソッドの guid パラメータに、次に挙げる値のどれか 1 つを渡す。

  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown

DirectInputEnumEffects.GetType で返される値の下位バイトが DIEFT_PERIODICY に等しい場合は、DirectInputEnumEffects.GetEffectGuid メソッドで取得したほかの任意の GUID を渡すこともできる。この方法を使えば、業者が設計したハードウェア特有のフォースを使用することができる。

周期的エフェクトのタイプ固有パラメータは、DIEFFECT の periodicForce メンバに含まれる DIPERIODICFORCE 型に格納されている。

周期的エフェクトの周期 (DIEFFECT.periodic.lPeriod) とサンプリング間隔 (DIEFFECT.lSamplePeriod) を混同しないように注意すること。周期は 1 つの波のサイクル全体を実行するのに要する時間である。サンプリング間隔は、すべてのエフェクトと同様に、マグニチュードを実際に調整する間隔の最小時間である。


条件

条件とは、デバイス内の現在のセンサ値に反応して適用されるフォースのことである。すなわち、条件は、ジョイスティック ハンドルの位置または速度など、デバイスに関する情報を必要とする。

一般的に、条件はゲームやその他のアプリケーションにおける個別のイベントには関連付けられていない。条件は、フライト スティックの硬さや緩さ、または直進の位置に戻すハンドルの向きなどの状態を表現する。

条件は、定義されたマグニチュードを持たない。マグニチュードは、入力オブジェクトの動作と位置によって測定される。

DirectInput は、次のような条件のエフェクトを定義する。

  • 摩擦 ― 軸が移動するときに適用されるフォースで、定義済みの摩擦係数によって決まる。
  • ダンパ ― このフォースはユーザーがジョイスティックを動かす速度に比例して増加する。
  • 慣性 ― このフォースは軸の加速度に比例して増加する。
  • スプリング ― このフォースは定義されている中立点からの軸の距離に比例して増加する。

ほとんどのハードウェア デバイスでは、条件にエンベロープを適用できない。

条件には次のタイプのパラメータがある。

Offset
条件の適用が始まる適切なセンサ値を読み込む、ゼロからのオフセット。スプリング エフェクトでは、中立点 (スプリングが静止していると考えられる軸上の点) は条件用のこのオフセットによって定義される。ダンパ エフェクトでは、このオフセットにより、ダンパ フォースがゼロとなる最大速度値が定義される。通常、オフセットは慣性エフェクトや摩擦エフェクトには使用しない。
Coefficient
エフェクトのスケーリングを算出する乗数。デバイスによっては、条件に関係する軸上の正方向と負方向に別の係数を設定することができる。たとえば、攻撃を受けた飛行機をコントロールする操縦桿は、左よりも右へ動かす方が容易になるというような場合である。
Saturation
フォース フィードバックでは、飽和点はエフェクトを上げる最大のフォースを表している。たとえば、操縦桿が X 軸上でスプリング条件を持っていると仮定してみよう。オフセットはゼロ、係数は 10,000 であり、通常は操縦桿が中立点から最も離れているときに、最大フォースが発揮される。しかし、正負 5,000 の飽和点を定義していると、操縦桿が右や左に移動した後、フォースは増加しない。

飽和点をサポートしていないデバイスもある。

Deadband
デッドバンドとは、条件が作用しない軸のオフセット範囲のことである。スプリングが軸の中立点に静止している場合は、デッドバンドはこの静止の範囲を拡張する。

デッドバンドをサポートしていないデバイスもある。

条件に継続時間を設定することができる。しかし、継続時間を INFINITE (-1) に設定し、アプリケーションで特定のイベントに応答するときだけエフェクトを停止する方法が使用されることが多い。

[C++]

条件を生成するには、IDirectInputDevice7::CreateEffect メソッドの rguid パラメータに次の値のどれか 1 つを渡す。

  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction

DIEFFECTINFO 構造体のメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトが DIEFT_CONDITION に等しい場合は、IDirectInputDevice7::EnumEffects メソッドで取得したほかの任意の GUID を渡すことができる。この方法を使えば、業者が設計したハードウェア特有の条件を使用することができる。

条件のタイプ固有構造体は DICONDITION である。複数軸の条件では、1 つの軸に対して複数の構造体からなる配列を使用するか、または特定の方向での条件を定義する 1 つの構造体を使用することができる。どちらの場合でも、DIEFFECT 構造体の cbTypeSpecificParams メンバに、使用するバイト数を設定する必要がある。すなわち、sizeof(DICONDITION) * n を設定する必要がある。ここで n は使用する構造体の数を表す。1 つあるいは複数の構造体を使用する方法の情報は、DICONDITION 構造体についての「注意」を参照すること。

エフェクトの係数と飽和について正と負の両方がデバイスでサポートされているかどうかを確認するには、アプリケーションで IDirectInputDevice7::GetEffectInfo メソッドまたは IDirectInputDevice7::EnumEffects メソッドを呼び出し、DIEFFECTINFO 構造体の dwEffectType メンバを調べなければならない。エフェクトが DIEFT_POSNEGCOEFFICIENTS フラグを返さなければ、lNegativeCoefficient メンバの値は無視され、lPositiveCoefficient の値が軸全体に適用される。同様に、エフェクトが DIEFT_POSNEGSATURATION フラグを返さなければ、dwNegativeSaturation の値は無視され、dwPositiveSaturation の値が負の飽和レベルとして使用される。また、エフェクトが DIEFT_SATURATION フラグを返さなければ、dwPositiveSaturation と dwNegativeSaturation の両方の値が無視され、飽和点は適用されない。

係数には負数を設定することができる。こうすると、エフェクトは反対方向のフォースを生成する。たとえばスプリング エフェクトでは、係数に負数を設定すると、スプリング エフェクトはオフセット点に向かって引っ張らずに、オフセット点から離れる方向へ押すことになる。

また、DIEFFECTINFO.dwEffectType に DIEFT_DEADBAND フラグが設定されているかどうかをチェックすることで、デッドバンドが条件に対してサポートされているかどうかを知ることができる。サポートされていない場合、DICONDITION 構造体の lDeadBand メンバの値は無視される。

[Visual Basic]

条件を生成するには、IDirectInputDevice7::CreateEffect メソッドの rguid パラメータ に次の値のどれか 1 つを渡す。

  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction

DirectInputEnumEffects.GetType により返された値の下位バイトが DIEFT_CONDITION に等しい場合は、DirectInputEnumEffects.GetEffectGuid メソッドで取得したほかの任意の GUID を渡すこともできる。この方法を使えば、業者が設計したハードウェア特有の条件を使用することができる。

条件のタイプ固有パラメータは、DIEFFECT 型の condition メンバに含まれる DICONDITION 型に記述される。

エフェクトの係数と飽和について正と負の両方がデバイスでサポートされているかどうかを確認するには、アプリケーションで DirectInputEnumEffects.GetType メソッドを呼び出し、返された値のメンバを調べる必要がある。エフェクトが DIEFT_POSNEGCOEFFICIENTS フラグを返さなければ、DICONDITION.lNegativeCoefficient の値は無視され、lPositiveCoefficient の値が軸全体に適用される。同様に、エフェクトが DIEFT_POSNEGSATURATION フラグを返さなければ、lNegativeSaturation の値は無視され、lPositiveSaturation の値が負の飽和レベルとして使用される。また、エフェクトが DIEFT_SATURATION フラグを返さなければ、lPositiveSaturation と lNegativeSaturation の両方の値が無視され、飽和点は適用されない。

係数には負数を設定することができる。こうすると、エフェクトは反対方向のフォースを生成する。たとえばスプリング エフェクトでは、係数に負数を設定すると、スプリング エフェクトはオフセット点に向かって引っ張らずに、オフセット点から離れる方向へ押すことになる。

また、GetType メンバ に DIEFT_DEADBAND フラグが設定されているかどうかをチェックすることで、デッドバンドが条件に対してサポートされているかどうかを知ることができる。サポートされていない場合、DICONDITION 構造体の lDeadBand メンバの値は無視される。

単一軸エフェクトを生成するには、DIEFFECT 型の conditionX メンバまたは conditionY メンバに、未使用の軸に対する係数をゼロとして設定する。

DirectX for Visual Basic では、条件の回転をサポートしていない。


カスタム フォース

アプリケーションの作成者は、カスタム フォースを作成することによって、独自のエフェクトを作成することができる。カスタム フォースは、デバイスが再生するコンスタント フォース値の配列である。

[C++]

カスタム波形エフェクトのタイプ固有構造体は、DICUSTOMFORCE である。

DICUSTOMFORCE 構造体の dwSamplePeriod メンバと DIEFFECT 構造体の dwSamplePeriod メンバには同じ値を設定しなければならない。この値はミリ秒単位の時間であり、フォースの配列の各要素が再生される時間を表す。

DIEFFECT の dwDuration メンバに設定された時間が過ぎるまで、カスタム フォースは繰り返し働く。

[Visual Basic]

カスタム フォースを生成するには、まずマグニチュードの配列を定義する。すべてのマグニチュードは -10,000 から 10,000 の範囲に含まれる。次に、この配列を DirectInputDevice.CreateCustomEffect メソッドに渡す。

samplePeriod パラメータと、DIEFFECT 型の lSamplePeriod メンバに同じ値を設定する。この値はミリ秒単位の時間であり、フォースの配列の各要素が再生される時間を表す。

DIEFFECT.lDuration に設定された時間が過ぎるまで、カスタム フォースは繰り返し働く。


デバイス エフェクト

ハードウェア ドライバは、DirectInput が定義するカテゴリに当てはまらない特殊効果をサポートすることができる。このようなエフェクトに対応するタイプ固有のパラメータは、ハードコーディングされていることもあれば、アプリケーションで変更できることもある。

[C++]

タイプ固有のパラメータが変更可能な場合、アプリケーション開発者は、エフェクトにより要求されるデータ構造を宣言しているヘッダー ファイルを取得しなければならない。

ハードウェア ベンダーは、そのデバイス固有エフェクトを識別する GUID を提供しなければならない。またハードウェア ベンダーは、そのエフェクトに対するタイプ固有パラメータ用の特別な構造体を提供することもある。次に、アプリケーションは、DIEFFECT 構造体とそのエフェクトに対するタイプ固有構造体を、ほかのどのエフェクトでも同様だが、初期化しなければならない。次に、IDirectInputDevice7::CreateEffect メソッドを呼び出し、デバイス GUID と DIEFFECT 構造体へのポインタを渡す。

DIEFFECTINFO 構造体にデバイス エフェクトについての情報が入るが、そのメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトは、定義済みの DirectInput のエフェクトタイプ (コンスタント フォース、傾斜フォース、周期的エフェクト、条件) のどれにデバイス エフェクトが分類されるのかを示している。定義済みのカテゴリのどれにも分類できない場合、下位バイトの値は DIEFT_HARDWARE である。

デバイス固有のエフェクトが定義済みのいずれかの種類に分類できれば、DIEFFECT 構造体の lpvTypeSpecificParams メンバはその種類に応じて、DICONSTANTFORCE 構造体、DIRAMPFORCE 構造体、DIPERIODIC 構造体、または DICONDITION 構造体を指し、cbTypeSpecificParams メンバはその構造体のサイズと同じ値でなくてはならない。

DIEFT_GETTYPE(dwEfftype) の値が DIEFT_HARDWARE であれば、lpvTypeSpecificParams メンバおよび cbTypeSpecificParams メンバの値は、そのエフェクトが特別なタイプ固有パラメータを必要としているかどうかによって決まる。特別なパラメータを必要とするときは、この 2 つのメンバの値は、メーカーのヘッダー ファイルで定義され、各自のアプリケーションで宣言および初期化された、適切な構造体を指さなくてはならない。そのエフェクトが特別なパラメータを必要としない場合、すなわち、ハードウェア エフェクト用の DIEFFECTINFO 構造体の dwStaticParms メンバに DIEP_TYPESPECIFICPARAMS フラグがないときは、lpvTypeSpecificParams は NULL で、cbTypeSpecificParams はゼロでなければならない。

DirectInput は確認のため、GUID と DIEFFECT 構造体をデバイス ドライバに渡す。GUID が未知である場合は、デバイスは DIERR_DEVICENOTREG を返す。GUID は既知でも、タイプ固有データがそのエフェクトに対して不正確である場合は、デバイスは DIERR_INVALIDPARAM を返す。

[Visual Basic]

DirectX for Visual Basic は、カスタムのタイプ固有パラメータを要求するハードウェア エフェクトをサポートしていない。

ハードウェア ベンダーは、デバイス固有のエフェクトを識別する GUID を提供しなければならない。次に、アプリケーションは、ほかのエフェクトと同様に、DIEFFECT 型を初期化しなければならない。次に、この型を GUID と共に DirectInputDevice.CreateEffect メソッドに渡す。

DirectInputEnumEffects 列挙にデバイス固有のエフェクトについての情報が入るが、DirectInputEnumEffects.GetType の戻り値の下位バイトは、定義済みの DirectInput のエフェクト タイプ (コンスタント フォース、傾斜フォース、周期的エフェクト、条件) のどれにデバイス エフェクトが分類されるのかを示している。定義済みのカテゴリのどれにも分類できない場合、下位バイトの値は DIEFT_HARDWARE である。

デバイス固有のエフェクトが定義済みのいずれかの種類に分類できれば、そのカテゴリの標準フォースの場合と同様に、DIEFFECT 型を初期化しなければならない。たとえば、エフェクト タイプが DIEFT_CONSTANTFORCE である場合は、constantForce メンバを初期化する必要がある。

DirectInput は確認のため、GUID と DIEFFECT をデバイス ドライバに渡す。GUID が未知である場合、デバイスは DIERR_DEVICENOTREG を返す。GUID は既知でも、タイプ固有データがそのエフェクトに対して不正確である場合は、デバイスは DIERR_INVALIDPARAM を返す。


前のバージョンの DirectInput の設計

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectInput では、バージョン番号をメソッドに渡さなければならないことがある。このパラメータは、DirectInput サブシステムがどのバージョンの Direct X をエミュレートするかを指定する。

最新バージョンの DirectInput 用に設計されたアプリケーションは、Dinput.h で定義されている DIRECTINPUT_VERSION 値を渡す必要がある。

以前のバージョンで実行するように設計されたアプリケーションでは、設計対象の DirectInput のバージョンに対応した値、すなわち上位バイトにメイン バージョン番号をつけた値を渡す必要がある。たとえば、DirectInput 3 上で動作するように設計されたアプリケーションは、0x0300 を渡す必要がある。

Dinput.h ヘッダー ファイルをインクルードする前に、DIRECTINPUT_VERSION を 0x0300 と定義すると、このヘッダー ファイルは DirectInput 3.0 と互換性を持つ構造体定義を生成する。

Dinput.h ヘッダー ファイルをインクルードする前に DIRECTINPUT_VERSION を定義しないと、Dinput.h ヘッダー ファイルは DirectInput の現行バージョンと互換性のある構造体定義を生成する。しかし、DirectX 3 と互換性のある構造体も、その名前に "_DX3" を付ければ使用することができる。たとえば、DirectX 3 と互換性のある DIDEVCAPS 構造体は DIDEVCAPS_DX3 と名付けられることになる。

また、DirectInput インターフェイスと DirectInputDevice インターフェイスの適切なバージョンを使用する必要がある。DirectX 7.0 より前のバージョンの DirectX では、IDirectInput と、IDirectInputDevice または IDirectInputDevice2 のどちらかを使用する必要がある (後者は DirectX 5.0 以降のバージョンで利用可能)。


DirectInput チュートリアル

ここでは、Microsoft® DirectInput® の基本的な機能をステップ バイ ステップで説明している。

  • DirectInput C/C++ チュートリアル
  • DirectInput Visual Basic チュートリアル


DirectInput C/C++ チュートリアル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

ここでは、次のチュートリアルを使用して、DirectInput の基本的な機能を C または C++ アプリケーションに実装する方法を段階的に説明する。

  • チュートリアル 1 : キーボードの使用

    最初のチュートリアルは、既存のアプリケーションに DirectInput キーボード サポートを追加する手順を示す。

  • チュートリアル 2 : マウスの使用

    2 番目のチュートリアルは、アプリケーションで DirectInput マウス サポートを実現する手順を示す。このチュートリアルは、Scrawl サンプルを基にしており、バッファリング データに焦点を当てる。

  • チュートリアル 3 : ジョイスティックの使用

    このチュートリアルは、システムに接続されているジョイスティックをすべて列挙する方法、コールバック関数で各ジョイスティックに対する DirectInput デバイス オブジェクトを作成して初期化する方法、および直接データを取得する方法を示す。サンプル コードは、Space Donuts サンプルを基にしている。

  • チュートリアル 4 : フォース フィードバックの使用

    最後のチュートリアルは、フォース フィードバック ジョイスティックでの単純なエフェクトの生成と操作について説明する。


チュートリアル 1 : キーボードの使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

キーボード入力の準備を行うには、まず、DirectInput オブジェクトのインスタンスを作成する。次に、IDirectInput7::CreateDeviceEx メソッドを使用して、IDirectInputDevice7 インターフェイスのインスタンスを作成する。IDirectInputDevice7 インターフェイスの各メソッドは、デバイスの操作、デバイスの動作の設定、およびデータの取得を行うのに使用する。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : DirectInput オブジェクトの作成
  • ステップ 2 : DirectInput キーボード デバイスの作成
  • ステップ 3 : キーボード データ形式の設定
  • ステップ 4 : キーボードの動作の設定
  • ステップ 5 : キーボードへのアクセス権の取得
  • ステップ 6 : キーボードからのデータの取得
  • ステップ 7 : DirectInput システムの終了

DirectInput キーボード サポートをアプリケーションに追加するのは、比較的簡単なので、このチュートリアルは、完全なサンプル アプリケーションにはなっていない。チュートリアルのすべての手順は、本文内のコードで具体的に示している。システムの初期化の関連手順は、「サンプル関数 1 : DI_Init」にまとめてある。システムを終了させる必要のあるときには、もう 1 つの関数「サンプル関数 2 : DI_Term」が、必ず呼ばれる。


ステップ 1 : DirectInput オブジェクトの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

DirectInput システムのセットアップ手順の最初は、全体のマネージャとして単一の DirectInput オブジェクトを作成することである。これは、DirectInputCreateEx 関数を呼び出すことによって行う。

// HINSTANCE hinst; // 以前に初期化済み。
HRESULT         hr;
LPDIRECTINPUT7  g_lpdi;

hr = DirectInputCreateEx(hinst, DIRECTINPUT_VERSION,
IID_IDirectInput7, (void**)&g_lpdi, NULL);
if FAILED(hr)
{
// DirectInput は利用可能ではない。適切な処置をとる。
  }

DirectInputCreateEx の第 1 パラメータは、オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドルである。

第 2 パラメータは、どのバージョンの DirectInput システムを DirectInput オブジェクトに使用するかを指示する。以前のバージョンの DirectInput と互換性のあるアプリケーションを設計することもできる。詳細については、「前のバージョンの DirectInput の設計」を参照すること。

第 3 パラメータは、どのインターフェイスが返されるかを指定する。ほとんどのアプリケーションは IID_IDirectInput7 を渡すことで、最新のバージョンを取得する。

第 4 パラメータは、この呼び出しが成功した場合に、有効なインターフェイス ポインタで初期化される変数のアドレスである。

最後のパラメータには、COM 集合化で使用する制御オブジェクトの IUnknown インターフェイスのアドレスを指定する。アプリケーションは、普通、集合化を使用しないので NULL を渡す。

次項 : ステップ 2 : DirectInput キーボード デバイスの作成


ステップ 2 : DirectInput キーボード デバイスの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

DirectInput オブジェクトの作成後、アプリケーションはキーボード オブジェクト (デバイス) を作成し、IDirectInputDevice7 インターフェイスへのポインタを取得しなければならない。デバイスは、このインターフェイスのメソッドを使用して、キーボード関連タスクの大半を実行する。

このポインタを取得するには、「サンプル関数 1 : DI_Init」で示すように、IDirectInput7::CreateDeviceEx メソッドを呼び出さなければならない。CreateDeviceEx は、4 つのパラメータを取る。

第 1 パラメータは、作成するデバイスの GUID である。キーボード システムが使用されることになるので、事前に定義されたグローバル変数を GUID_SysKeyboard に渡す。

第 2 パラメータは、目的のインターフェイスの GUID である。ほとんどのアプリケーションは IID_IDirectInputDevice7 を渡すことで、最新のバージョンを取得する。

第 3 パラメータは、呼び出しが成功した場合に、取得したインターフェイス ポインタで初期化される変数のアドレスである。

第 4 パラメータは、COM 集合化で使用する制御オブジェクトの IUnknown インターフェイスのアドレスである。集合化を使用しない場合には、このパラメータを NULL にする。

以下のコードは、IDirectInputDevice7 インターフェイスへのポインタを取得しようとする例である。失敗した場合には、DI_Term アプリケーション定義サンプル関数を呼び出し、既存の DirectInput オブジェクトがあればその割り当てを解除する。

注 : すべての例の g_lpdi は、DirectInput オブジェクトに対する初期化されたポインタである。メソッド呼び出しは、C++ 形式である。

HRESULT hr;
LPDIRECTINPUTDEVICE7  g_lpDIDEVICE

hr = g_lpDI->CreateDeviceEx(GUID_SysKeyboard, IID_IDirectInputDevice7,
(void**)&g_lpDIDevice, NULL);
if FAILED(hr)
{
DI_Term();
return FALSE;
}

次項 : ステップ 3 : キーボード データ形式の設定


ステップ 3 : キーボード データ形式の設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

IDirectInputDevice7 ポインタを取得したら、「サンプル関数 1 : DI_Init」に示すように、デバイスのデータ形式を設定しなければならない。キーボードの場合、これは非常に簡単なタスクである。ユーザーの便宜を考慮してDirectInput に用意されているデータ形式を、c_dfDIKeyboard グローバル変数に指定して IDirectInputDevice7::SetDataFormat メソッドを呼び出す。

以下のコードは、データ形式を設定しようとする例である。失敗した場合には、DI_Term サンプル関数を呼び出し、既存の DirectInput オブジェクトがあればその割り当てを解除する。

hr = g_lpDIDevice->SetDataFormat(&c_dfDIKeyboard);

if FAILED(hr){
DI_Term();
return FALSE;
}

次項 : ステップ 4 : キーボードの動作の設定


ステップ 4 : キーボードの動作の設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションは、キーボードにアクセスする前に、「サンプル関数 1 : DI_Init」に示すように、IDirectInputDevice7::SetCooperativeLevel メソッドを使用してデバイスの動作を設定しなければならない。このメソッドは、デバイスに関連付けられたウィンドウへのハンドルと、協調レベルを決定するフラグの組み合わせを受け取る。この場合、アプリケーションはフォアグラウンドの非排他アクセスを要求している。

以下のコードは、デバイスの協調レベルを設定しようとする例である。失敗した場合には、DI_Term アプリケーション定義サンプル関数を呼び出し、既存の DirectInput オブジェクトがあればその割り当てを解除する。

// 協調レベルを設定する。
hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
DISCL_FOREGROUND | DISCL_NONEXCLUSIVE);

if FAILED(hr){
DI_Term();
return FALSE;
}

次項 : ステップ 5 : キーボードへのアクセス権の取得


ステップ 5 : キーボードへのアクセス権の取得

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

キーボードの動作を設定したら、アプリケーションは、IDirectInputDevice7::Acquire メソッドを呼び出して、デバイスに対するアクセス権を取得できる。アプリケーションは、デバイスからデータを取得する前に、デバイスを取得しなければならない。Acquire メソッドには、パラメータはない。

以下は、「ステップ 2 : DirectInput キーボード デバイスの作成」で作成されたキーボード デバイスを取得するコードである。

if (g_lpDIDevice) g_lpDIDevice->Acquire();

次項 : ステップ 6 : キーボードからのデータの取得


ステップ 6 : キーボードからのデータの取得

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

デバイスを取得すれば、アプリケーションは、デバイスからのデータの取得を開始できる。データを取得する最も簡単な方法は、IDirectInputDevice7::GetDeviceState メソッドを呼び出すことである。このメソッドは、デバイスを呼び出したときのその瞬間の状態を取得する。

GetDeviceState メソッドは 2 つのパラメータを取る。デバイス状態データが設定されるバッファのサイズと、そのバッファへのポインタである。キーボードの場合は、常に、符号無し 256 バイトのバッファを宣言する。

以下のコードは、キーボードの状態を取得しようとする例である。取得に失敗した場合、アプリケーション定義のサンプル関数を呼び出し、既存の DirectInput オブジェクトがあれば、その割り当てを解除する (「サンプル関数 2 : DI_Term」を参照)。

キーボードの現在の状態を取得した後、アプリケーションは、呼び出し時に押された特定のキーに応答することができる。バッファ中の各要素が 1 つのキーを表す。要素の上位ビットがオンの場合、そのキーは、呼び出し時に押されていたことを示す。それ以外の場合は、キーは押されていない。あるキーの状態をチェックするには、DirectInput のキーボード デバイス定数を使用して、そのキーに対するバッファのインデックスを作成する。

以下のコードは、ある仮想の宇宙船ゲームのメイン ループから呼び出されるスケルトン関数である。ここでは、IDirectInputDevice7::GetDeviceState メソッドを使用してキーボードをポーリングする。次に、デバイス状態を取得したときに、左向き矢印、右向き矢印、上向き矢印、または下向き矢印の各キーが押されたかどうかをチェックする。これを行うには、この関数の本体で定義されている KEYDOWN マクロを使用する。KEYDOWN マクロは、バッファの変数名とインデックス値を受け取った後、指定インデックスに位置するバイトをチェックして上位ビットが設定されているかどうかを調べ、設定されている場合には TRUE を返す。

void WINAPI ProcessKBInput()
{
#define KEYDOWN(name,key) (name[key] & 0x80)

char     buffer[256];
HRESULT hr;

hr = g_lpDIDevice->GetDeviceState(sizeof(buffer),(LPVOID)&buffer);
if FAILED(hr)
    {
// 失敗の場合、デバイスは失われている。
// (hr == DIERR_INPUTLOST) をチェックし、
// 再取得を試みる必要がある。
return;
    }

// 船を右もしくは左に向ける。
if (KEYDOWN(buffer, DIK_RIGHT));
// 右に向ける。
else if(KEYDOWN(buffer, DIK_LEFT));
// 左に向ける。

// 船を進める。もしくは止める。
if (KEYDOWN(buffer, DIK_UP)) ;
// 船を前進させる。
else if (KEYDOWN(buffer, DIK_DOWN));
// 船を止める。
}

次項 : ステップ 7 : DirectInput システムの終了


ステップ 7 : DirectInput システムの終了

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションを終了する直前に、すべての DirectInput オブジェクトを解放する必要がある。これは 3 段階の処理から成る。

  • すべての DirectInput デバイスのアクセス権を解放する (IDirectInputDevice7::Unacquire)
  • すべての DirectInput デバイスを解放する (IDirectInputDevice7::Release)
  • DirectInput オブジェクトを解放する (IDirectInput7::Release)

DirectInput システムを終了させる関数のサンプルは、「サンプル関数 2 : DI_Term」を参照すること。


サンプル関数 1 : DI_Init

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

このアプリケーション定義サンプル関数は、DirectInput オブジェクトを作成して初期化し、必要なインターフェイス ポインタを取得して、それらのポインタをグローバル変数に割り当てる。初期化が完了したら、デバイスを取得する。

初期化のどの部分で失敗しても、この関数は、DI_Term アプリケーション定義サンプル関数を呼び出し、プログラムを終了する準備として、DirectInput オブジェクトとインターフェイス ポインタの割り当てを解除する (「サンプル関数 2 : DI_Term」を参照)。

DI_Init 関数は、DirectInput オブジェクトを作成することに加えて、以下のチュートリアル手順で説明されているタスクを実行する。

  • ステップ 2 : DirectInput キーボード デバイスの作成
  • ステップ 3 : キーボード データ形式の設定
  • ステップ 4 : キーボードの動作の設定
  • ステップ 5 : キーボードのアクセス権の取得

以下は、DI_Init 関数である。

/ * 次の変数は初期化済みとする。
HINSTANCE             g_hinst;    // アプリケーションインスタンス
HWND                  g_hwndMain; // アプリケーション ウィンドウ
*/
LPDIRECTINPUT7        g_lpDI;
LPDIRECTINPUTDEVICE7  g_lpDIDevice;

BOOL WINAPI DI_Init()
{
HRESULT hr;

// DirectInput オブジェクトを作成する。
hr = DirectInputCreateEx(g_hinst, DIRECTINPUT_VERSION,
IID_IDirectInput7, (void**)&g_lpDI, NULL);
if FAILED(hr) return FALSE;

// IDirectInputDevice7 インターフェイスへのポインタを取得する。
hr = g_lpDI->CreateDeviceEx(GUID_SysKeyboard,
IID_IDirectInputDevice7, (void**)&g_lpDIDevice, NULL);
if FAILED(hr)
    {
DI_Term();
return FALSE;
    }

// IDirectInputDevice7 インターフェイスを保持して、
// 使用準備が整ったところである。

// キーボード用 DirectInput オブジェクトが作る、事前定義された
// キーボード データ形式を用いて、データ形式を設定する。
hr = g_lpDIDevice->SetDataFormat(&c_dfDIKeyboard);
if FAILED(hr)
    {
DI_Term();
return FALSE;
    }

// 協調レベルを設定する。
hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
DISCL_FOREGROUND | DISCL_NONEXCLUSIVE);
if FAILED(hr)
    {
DI_Term();
return FALSE;
    }

// 入力デバイスにアクセスする。
hr = g_lpDIDevice->Acquire();
if FAILED(hr)
    {
DI_Term();
return FALSE;
    }

return TRUE;
}


サンプル関数 2 : DI_Term

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

このアプリケーション定義サンプル関数は、プログラムを終了する準備として、またはデバイスの正常な初期化が失敗した場合の処理として、既存の DirectInput インターフェイス ポインタの割り当てを解除する。

/ * 次の変数は初期化済みとする。
LPDIRECTINPUT7        g_lpDI;
LPDIRECTINPUTDEVICE7  g_lpDIDevice;
*/

void WINAPI DI_Term()
{
if (g_lpDI)
    {
if (g_lpDIDevice)
        {
            /* Release() を呼び出す前は
             必ずデバイスのアクセス権を解放する。*/
g_lpDIDevice->Unacquire();
g_lpDIDevice->Release();
g_lpDIDevice = NULL;
        }
g_lpDI->Release();
g_lpDI = NULL;
    }
}


チュートリアル 2 : マウスの使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、マウス デバイスをセットアップし、入力のバッファリング データを取得する作業を順を追って説明する。この例は、Scrawl サンプルを基にしている。

マウス入力の準備を行うには、まず、DirectInput オブジェクトのインスタンスを作成する。次に、IDirectInput7::CreateDeviceEx メソッドを使用して、IDirectInputDevice7 インターフェイスのインスタンスを作成する。IDirectInputDevice7 インターフェイスの各メソッドは、デバイスの操作、デバイスの動作の設定、およびデータの取得を行うのに使用する。

DirectInput システムのセットアップの準備手順とシステムを終了する最後の手順は、どのアプリケーションでも同じであり、「チュートリアル 1 : キーボードの使用」で説明してある。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : DirectInput マウス デバイスの作成
  • ステップ 2 : マウス形式の設定
  • ステップ 3 : キーボードの動作の設定
  • ステップ 4 : マウスからのバッファリング データ入力の準備
  • ステップ 5 : マウスへのアクセス権の管理
  • ステップ 6 : マウスからのバッファリング データの取得

注 : アプリケーションが排他協調レベルでマウスを取得しているとき、Windows はマウス ポインタを画面に表示しない。このため、アプリケーションには、簡単なスプライト エンジンが必要となる。Scrawl サンプル アプリケーションでは、Win32 関数の DrawIcon を使用して十字カーソルを画面に表示する。


ステップ 1 : DirectInput マウス デバイスの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

DirectInput オブジェクトを作成すると、アプリケーションは、マウス関連タスクの大半を実行するのに使う IDirectInputDevice7 インターフェイスへのポインタを取得する必要がある。このポインタを取得するには、IDirectInput7::CreateDeviceEx メソッドを呼び出す。

CreateDeviceEx の第 1 パラメータは、アプリケーションが作成しようとしているデバイスの GUID (Globally Unique IDentifier) 値である。この場合はシステムマウスを使用するので、アプリケーションは、事前定義されたグローバル変数の GUID_SysMouse を渡す必要がある。

第 2 パラメータは、目的の DirectInputDevice インターフェイスの GUID である。ほとんどのアプリケーションは最新のインターフェイスを要求するので、IID_IDirectInputDevice7 を渡す。

第 3 パラメータは、この呼び出しが成功した場合に、有効な IDirectInputDevice7 インターフェイス ポインタで初期化される変数のアドレスである。

第 4 パラメータは、COM 集合化で使用する制御オブジェクトの IUnknown インターフェイスのアドレスである。集合化を使用しない場合には、このパラメータを NULL にする。

以下のコードは、IDirectInputDevice7 インターフェイスへのポインタを取得しようとする例である。呼び出しが失敗すれば、FALSE が返される。g_pdi は、IDirectInput7 への有効なポインタであると仮定する。

LPDIRECTINPUTDEVICE g_pMouse;
HRESULT             hr;

hr = g_pdi->CreateDeviceEx(GUID_SysMouse, IID_IDirectInputDevice7,
(void**)&g_pMouse, NULL);

if (FAILED(hr)) {
return FALSE;
}

次項 : ステップ 2 : マウス形式の設定


ステップ 2 : マウス形式の設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

IDirectInputDevice7 ポインタを取得したら、デバイスのデータ形式を設定しなければならない。マウスの場合、これは非常に簡単なタスクである。便宜上 DirectInput に用意されているデータ形式を、c_dfDIMouse グローバル変数に指定して IDirectInputDevice7::SetDataFormat メソッドを呼び出す。

以下は、デバイスのデータ形式を設定しようとするコードである。呼び出しが失敗すれば、FALSE が返される。

hr = g_pMouse->SetDataFormat(&c_dfDIMouse);

if (FAILED(hr)) {
return FALSE;
}

次項 : ステップ 3 : キーボードの動作の設定


ステップ 3 : キーボードの動作の設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションがマウスに対するアクセス権を取得できるようにするには、前もって、IDirectInputDevice7::SetCooperativeLevel メソッドを使用してマウス デバイスの動作を設定しなければならない。このメソッドは、デバイスに関連付けられたウィンドウのハンドルを受け取る。Scrawl では、DISCL_EXCLUSIVE フラグが指定されているので、マウス デバイスに対する排他アクセス権を持つのは、このアプリケーションのみであるということが保証される。このフラグと DISCL_FOREGROUND とを組み合わせている理由は、別のアプリケーションがフォアグラウンドにあるときのマウスの動作には、Scrawl は関知しないからである。

以下は、デバイスの協調レベルを設定しようとするコードである。設定に失敗すれば、FALSE が返される。

hr = g_pMouse->SetCooperativeLevel(hwnd,
DISCL_EXCLUSIVE | DISCL_FOREGROUND);

if (FAILED(hr)) {
return FALSE;
}

次項 : ステップ 4 : マウスからのバッファリング データ入力の準備


ステップ 4 : マウスからのバッファリング データ入力の準備

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

Scrawl アプリケーションは、イベント通知を使用してマウスの動作を検出する方法、およびマウスからのバッファリング入力を読み取る方法を示している。この方法はどちらも、ある程度のセットアップを必要とする。それらの手順は、マウス デバイスの作成後で、マウス デバイスの取得前であればいつでも実行できる。

まず、イベントを作成し、マウス デバイスと関連付ける。これにより、新たな有効データが発生したことを示すハードウェア割り込みがあれば、いつでもマウス デバイス オブジェクトに通知するように、DirectInput に指示していることになる。

以下は Scrawl での処理方法である。ここで、g_hevtMouse はグローバル HANDLE である。

g_hevtMouse = CreateEvent(0, 0, 0, 0);

if (g_hevtMouse == NULL) {
return FALSE;
}

hr = g_pMouse->SetEventNotification(g_hevtMouse);

if (FAILED(hr)) {
return FALSE;
}

まず、この段階でバッファ サイズを設定する必要がある。これは、プログラムが入力データを参照する用意ができるまで、DirectInput があらゆる入力データを格納できるようにするためである。デフォルトのバッファ サイズはゼロであるので、この手順は、バッファリング データを使う場合の基本的手順であることを、覚えておくこと。

イベント通知では、バッファリング データを使用する必要はない。ただし、必要に応じて、イベント通知の直後にデータを取得することもできる。

バッファ サイズを設定するには、DIPROPDWORD 構造体を、構造体自体についての情報と、設定したいプロパティについての情報で初期化する必要がある。ほとんどの値は、定型的なものだが、最後の dwData は重要な値である。これは、バッファが保持する項目数に初期化する。

#define DINPUT_BUFFERSIZE 16

DIPROPDWORD dipdw =
    {
// ヘッダー
        {
sizeof(DIPROPDWORD),        // diph.dwSize
sizeof(DIPROPHEADER),       // diph.dwHeaderSize
0,                          // diph.dwObj
DIPH_DEVICE,                // diph.dwHow
        },
// データ
DINPUT_BUFFERSIZE,              // dwData
    };

次に、ヘッダー (DIPROPDWORD 構造体内の DIPROPHEADER 構造体) のアドレスと、変更したいプロパティの識別子を、次のように IDirectInputDevice7::SetProperty メソッドに渡す。

hr = g_pMouse->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph);

if (FAILED(hr)) {
return FALSE;
 }

これでセットアップは完了し、いつでもマウスを取得してデータの収集を始められる。

次項 : ステップ 5 : マウスへのアクセス権の管理


ステップ 5 : マウスへのアクセス権の管理

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

DirectInput は、デバイスのアクセス権を管理するために、IDirectInputDevice7::Acquire および IDirectInputDevice7::Unacquire メソッドを提供する。アプリケーションは、まず Acquire メソッドを呼び出し、デバイスに対するアクセス権を取得しなければならない。次に、IDirectInputDevice7::GetDeviceState メソッドと IDirectInputDevice7::GetDeviceData メソッドを使用して、マウス情報を要求する。

ほとんどの場合、アプリケーションはデバイスを取得する。しかし、フォアグラウンド アクセスしか持たない場合は、アプリケーションがバックグラウンドに移行すると必ずマウスは解放される。フォーカスが戻った場合には、確実にデバイスを再取得する必要がある。これは、WM_ACTIVATE メッセージに反応することで行うことができる。

Scrawl では、アプリケーションがフォーカスを取得するのか、あるいは失うのかに合わせて、グローバル変数の g_fActive を設定することで、このメッセージを処理している。次に、ヘルパー関数の Scrawl_SyncAcquire を呼び出す。このヘルパー関数は、g_fActive が TRUE の場合にマウスを取得し、そうでない場合にはマウスを解放する。

case WM_ACTIVATE:
g_fActive = wParam == WA_ACTIVE || wParam == WA_CLICKACTIVE;
Scrawl_SyncAcquire(hwnd);
break;

排他アクセス権を持っている場合、メニューやダイアログ ボックスにアクセスするなど、ユーザーが対話形式で Windows を操作できるように、アプリケーションはマウスを解放しなければならないことがある。Scrawl では、Alt キーとスペース キーを同時に押すことで、ユーザーがシステム メニューを開くことができる。

Scrawl のウィンドウ プロシージャは、WM_ENTERMENULOOP に対するハンドラを持っている。このハンドラは、グローバル変数 g_fActive に FALSE を設定し、Scrawl_SyncAcquire 関数を呼び出すことで応答する。このハンドラを使うと、Windows はマウスを保持し、独自のカーソルを表示することができる。

ユーザーがメニューの使用を終了すると、Windows はアプリケーションに WM_EXITMENULOOP メッセージを送る。この場合、Scrawl のウィンドウ処理により、アプリケーション定義メッセージの WM_SYNCACQUIRE がアプリケーション自体のメッセージ キューに送信される。このことにより、Scrawl_SyncAcquire 関数でマウスが再取得される前に、ほかの待機中のメッセージが処理される。

また、Scrawl は、コンテキスト メニューを開く右ボタン クリックに応答して、マウスを解放する。マウスは遅れて解放されるが、WM_ENTERMENULOOP ハンドラでは、メニューが表示される前に Windows カーソルの位置を設定できるように、最初にマウスを解放している。

最後に、Scrawl は、データの取得を試みて DIERR_INPUTLOST エラーが返されたら、マウスの再取得を試みる。これは、ほかの箇所では処理されない方法によってデバイスが解放された場合への備えである。たとえば、ユーザーが Ctrl+Alt+Del キーを押した場合などである。

まとめると、アプリケーションは、マウスからデータを取得する前に、マウスを取得する必要がある。マウスの取得は、アプリケーションに強制的にマウスのアクセス権を放棄させる事態が発生しない限り、一度だけ行えば済む。排他モードでは、Windows がマウスを必要とするときに、マウスの制御を放棄しなければならない。また、マウスのアクセス権を Windows またはその他のアプリケーションに譲った後、マウスに対するアクセス権が必要になった場合は、マウスを再取得しなければならない。

次項 : ステップ 6 : マウスからのバッファリング データの取得


ステップ 6 : マウスからのバッファリング データの取得

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

マウスを取得すれば、アプリケーションは、マウスからのデータの取得を開始することができる。

Scrawl サンプルでは、データ取得は、通知されたイベントがトリガとなる。シグナルやメッセージがあることが MsgWaitForMultipleObjects から示されるまで、アプリケーションは、WinMain 関数の中でスリープ状態に入る。マウス関連のシグナルがあれば、Scrawl_OnMouseInput 関数が呼び出される。この関数は、バッファリング入力を取り扱う方法の好例であるので、以下詳細に説明する。

まず、この関数は、元のカーソル位置が完全に消去されていることを確認する。Scrawl は独自のカーソルを維持し、その描画や消去を全面的に行わなければならないことに注意する。

void Scrawl_OnMouseInput(HWND hwnd)
{
/* 元のカーソルは、クリアされるので無効になる。
InvalidateCursorRect(hwnd);

ここで、関数はループに入り、バッファの全内容に対する読み取りおよび応答を行う。データは一度に 1 項目しか取得できないので、データを保持するためには、DIDEVICEOBJECTDATA 構造体が 1 つだけあればよい。

入力処理にはこのほかにも、バッファ全体を一度に読み取った後、ループで取得項目を順に 1 つずつ応答していく方法がある。その場合は、dwElements をバッファ サイズとし、od はそのサイズに等しい数の要素を持つ配列とする。

    while (!fDone) {
        DIDEVICEOBJECTDATA od;
        DWORD dwElements = 1;   // 取得すべき項目数

アプリケーションは、データを取得するために IDirectInputDevice7::GetDeviceData メソッドを呼び出す。第 2 パラメータはデータを置く位置を、第 3 パラメータは必要な項目数を、DirectInput にそれぞれ通知する。データをバッファに残しておく場合は、最後のパラメータを DIGDD_PEEK とする。ただし、この場合は、データを再度必要とすることはないので削除する。

        HRESULT hr = g_pMouse->GetDeviceData(
                             sizeof(DIDEVICEOBJECTDATA),
                             &od,
                             &dwElements, 0);

ここで、アプリケーションは、デバイスに対するアクセス権が失われているかどうかの確認チェックを行い、失われていればすぐに適切なタイミングでマウスの再取得を行うように自身に指示する。この手順は、「ステップ 5 : マウスへのアクセス権の管理」で説明する。

        if (hr == DIERR_INPUTLOST) {
            PostMessage(hwnd, WM_SYNCACQUIRE, 0, 0L);
            break;
        }

次に、アプリケーションは、GetDeviceData メソッドの呼び出しが成功したこと、および取得するデータが実際に存在したことを確認する。GetDeviceData の呼び出し後、dwElements 変数は実際に取得した項目数を示していることに注意する。

        /* データが読めない、または利用可能データがない。*/
        if (FAILED(hr) || dwElements == 0) {
            break;
        }

ここまで実行が進めば、すべて順調である。すなわち、呼び出しは成功し、バッファにはデータ項目が存在する。ここで、アプリケーションは、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを調べ、デバイス上のどのオブジェクトが状態変化を報告したかを確認する。次に、ヘルパー関数を呼び出し、適切に対応する。dwData メンバの値は、状態に関する情報をもっており、これらのヘルパー関数に渡される。

        /* 要素を調べて何が発生したかを確認する。*/

        switch (od.dwOfs) {

        /* DIMOFS_X:マウスの水平動作。*/
        case DIMOFS_X: UpdateCursorPosition(od.dwData, 0); break;

        /* DIMOFS_Y:マウスの垂直動作。*/
        case DIMOFS_Y: UpdateCursorPosition(0, od.dwData); break;

        /* DIMOFS_BUTTON0:ボタン 0 を押すあるいは離す。*/
        case DIMOFS_BUTTON0:

            if (od.dwData & 0x80) { /* ボタンを押す。*/
                fDone = 1;
                Scrawl_OnButton0Down(hwnd); /* ボタン押下モードに
                                               変わる。*/
            }
            break;

        /* DIMOFS_BUTTON1:ボタン 1 を押すまたは離す。*/
        case DIMOFS_BUTTON1:

            if (!(od.dwData & 0x80)) {    /* ボタンを離す。*/
                fDone = 1;
                Scrawl_OnButton1Up(hwnd); /* コンテキスト メニュー タイム。*/
            }
        }

    }

最後に、カーソルがいずれかのヘルパー関数により移動された場合のために、Scrawl_OnMouseInput サンプル関数は、カーソルが占有している画面上の矩形を無効化する。

/* 新しいカーソルが描画されるので無効化する。
InvalidateCursorRect(hwnd);
}

また、Scrawl は、Scrawl_OnButton0Down 関数にあるマウス データを集める。これは、主ボタンが押下されている間、すなわち、ユーザーが描画している間のマウス移動を、アプリケーションが追跡する関数である。この関数は、イベント通知には依存しないが、ボタンが離されるまで、連続的に DirectInput バッファをポーリングする。

Scrawl_OnButton0Down 関数で注意すべき重要な点は、すべての待機中のデータが読み込まれるまでは実際の描画は行われない、ということである。これは、マウスの水平方向と垂直方向の移動が、独立したイベントとして報告されるためである (ただし、両イベントのバッファへの配置は同時に行われる)。独立したそれぞれの軸移動に反応して直線が直ちに描画される場合、マウスを斜めに動かすと、直角に交わる 2 直線が描画されることになる。

アプリケーションの応答前に、両軸における移動が計算に入れられていることを確認するには、x 軸項目と y 軸項目のシーケンス番号をチェックする方法もある。番号が同一であれば、2 つのイベントが同時に発生したことになる。詳細については、「タイム スタンプとシーケンス番号」を参照すること。


チュートリアル 3 : ジョイスティックの使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、システム上のジョイスティックを列挙し、入力用に 2 つ以上のジョイスティックをセットアップする方法を示す。サンプル コードは、Space Donuts サンプルを基にしている。メソッド呼び出しは、C 形式で行う。

DirectInput システムのセットアップの準備手順とシステムを終了する最後の手順は、どのアプリケーションでも同じであり、これについては「チュートリアル 1 : キーボードの使用」で説明してある。

チュートリアルの最初の手順は、デバイスを列挙すること、すなわち、使用可能なジョイスティックを確認することである。この処理の一部として、各ジョイスティック デバイスを初期化し、必要な特性を設定する。次に、IDirectInputDevice7 インターフェイス メソッドを使用して、各ジョイスティックからデータを取得する。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : ジョイスティックの列挙
  • ステップ 2 : DirectInput ジョイスティック デバイスの作成
  • ステップ 3 : ジョイスティック データ形式の設定
  • ステップ 4 : ジョイスティックの動作の設定
  • ステップ 5 : ジョイスティックへのアクセス権の取得
  • ステップ 6 : ジョイスティックからのデータを取得


ステップ 1 : ジョイスティックの列挙

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

DirectInput システムを作成したら、IDirectInput7::EnumDevices メソッドを呼び出し、ジョイスティックを列挙する。この処理を行うには、次のコードを使用する。

// pdi は、IDirectInput7 への初期化済みのポインタである。

pdi->lpVtbl->EnumDevices(pdi, DIDEVTYPE_JOYSTICK,
InitJoystickInput, pdi, DIEDFL_ATTACHEDONLY);

メソッド呼び出しは C 形式である。呼び出しを簡単にするために、IDirectInput7_EnumDevices マクロを使用することに注意すること。すべての DirectInput メソッドには、それに対応する、Dinput.h で定義されたマクロが含まれていて、適切な C または C++ の文法に従って展開する。

第 2 パラメータとして渡される DIDEVTYPE_JOYSTICK 定数は、列挙対象のデバイスのタイプを指定する。

InitJoystickInput は、ジョイスティックが見つかるたびに呼び出されるコールバック関数のアドレスである。チュートリアルのこれ以降のステップにおいて、個別のデバイスはこの関数の中で初期化される。

第 4 パラメータは、コールバック関数が使用できる任意の 32 ビット値である。この場合は、DirectInput インターフェイスへのポインタである。コールバック関数が IDirectInput7::CreateDeviceEx メソッドを呼び出すには、このポインタが必要である。

最後のパラメータの DIEDFL_ATTACHEDONLY は、列挙対象をコンピュータにアタッチされているデバイスに限定するフラグである。

次項 : ステップ 2 : DirectInput ジョイスティック デバイスの作成


ステップ 2 : DirectInput ジョイスティック デバイスの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

DirectInput オブジェクトを作成すると、アプリケーションは、ジョイスティック関連タスクの大半を実行するのに使う IDirectInputDevice7 インターフェイスへのポインタを取得する必要がある。Space Donuts サンプルでは、この処理は、ジョイスティックが列挙されるたびに呼び出されるコールバック関数 InitJoystickInput で行われている。

以下は、そのコールバック関数の最初の一部である。

BOOL FAR PASCAL InitJoystickInput(LPCDIDEVICEINSTANCE pdinst,
                                  LPVOID pvRef)
{
   LPDIRECTINPUT7 pdi = pvRef;
   LPDIRECTINPUTDEVICE7 pdev;

   // DirectInput ジョイスティック デバイスを作成する。
   if (pdi->lpVtbl->CreateDeviceEx(pdi, &pdinst->guidInstance,
          IID_IDirectInputDevice7, (void**)&pdev, NULL) != DI_OK)
   {
      OutputDebugString("IDirectInput7::CreateDeviceEx FAILED\n");
      return DIENUM_CONTINUE;
   }

InitJoystickInput のコールバック関数のパラメータは、以下のとおりである。

  • デバイス インスタンスへのポインタ。インスタンスは、デバイスが列挙されたときに DirectInput システムによって供給される。
  • DirectInput インターフェイスへのポインタ。これは、IDirectInput7::EnumDevices に対するパラメータとして指定したものである。このパラメータには、32 ビットの任意の値を取ることができるが、この場合、IDirectInput7::CreateDeviceEx メソッドを呼び出すことができるように、DirectInput インターフェイスを指定する。

サンプル関数 InitJoystickInput は、DirectInput オブジェクトへのローカル ポインタ pdi を宣言し、このポインタに、コールバック関数に渡す値を割り当てる。また、DirectInput デバイスへのローカル ポインタ pdev も宣言する。このポインタは、デバイスの作成時に初期化される。

コールバック関数の最初のタスクは、デバイスを作成することである。IDirectInput7::CreateDeviceEx メソッドは、4 つのパラメータを取る。

第 1 パラメータは、呼び出し側の DirectInput インターフェイスに対するポインタであり、C++ では不要である。

第 2 パラメータは、デバイスのインスタンスの GUID に対する参照値である。この場合、GUID は DirectInput がデバイスを列挙したときに与える DIDEVICEINSTANCE 構造体から取られる。

第 3 パラメータは、呼び出しが成功した場合に、有効なインターフェイス ポインタで初期化される変数のアドレスである。

第 4 パラメータは、COM 集合化で使用する制御オブジェクトの IUnknown インターフェイスのアドレスである。Space Donuts サンプルでは集合化を使用しないので、パラメータは NULL である。

何らかの理由で、デバイス インターフェイスを作成できない場合は、コールバック関数から DIENUM_CONTINUE が返されることに注意すること。このフラグは、列挙対象のデバイスが存在する限り、列挙を続行することを DirectInput に指示する。

次項 : ステップ 3 : ジョイスティック データ形式の設定


ステップ 3 : ジョイスティック データ形式の設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

これまでにアプリケーションは、DirectInput デバイスへのポインタを取得しているので、IDirectInputDevice7 メソッドを呼び出して、そのデバイスを操作することができる。ここではまず、ジョイスティックのデータ形式を設定する。この手順は不可欠である。この手順では、DirectInput に対して入力データの書式を設定する方法を指示する。

Space Donuts サンプルでは、前のステップで導入したコールバック関数でこの処理を実行する。

   if (pdev->lpVtbl->SetDataFormat(pdev, &c_dfDIJoystick) != DI_OK)
   {
      OutputDebugString("IDirectInputDevice7::SetDataFormat FAILED\n");
      pdev->lpVtbl->Release(pdev);
      return DIENUM_CONTINUE;
   }

pdev 変数は、IDirectInput7::CreateDeviceEx が作成したデバイス インターフェイスへのポインタである。

IDirectInputDevice7::SetDataFormat メソッドは、2 つのパラメータを取る。第 1 パラメータは、このインターフェイスの呼び出し側インスタンスに対するポインタであり、C++ では不要である。第 2 パラメータは、デバイスのデータの書式設定方法に関する情報を格納する DIDATAFORMAT 構造体へのポインタである。ジョイスティックの場合は、事前定義されたグローバル変数 c_dfDIJoystick をここで使用できる。

前のステップのように、コールバック関数は、デバイスの初期化に失敗した場合に DIENUM_CONTINUE を返す。このフラグは、列挙対象のデバイスが存在する限り、列挙を続行することを DirectInput に指示する。

次項 : ステップ 4 : ジョイスティックの動作の設定


ステップ 4 : ジョイスティックの動作の設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

これまでに、ジョイスティック デバイスの作成とデバイスのデータ形式の設定が完了している。次は、デバイスの協調レベルを設定することである。Space Donuts サンプルでは、この処理は、デバイスが列挙されたときにコールバック関数で行われる。前のステップと同様に、pdev はデバイス インターフェイスへのポインタである。

   if(pdev->lpVtbl->SetCooperativeLevel(pdev, hWndMain,
      DISCL_NONEXCLUSIVE | DISCL_FOREGROUND) != DI_OK)
   {
      OutputDebugString("IDirectInputDevice7::SetCooperativeLevel
                         FAILED\n");
      pdev->lpVtbl->Release(pdev);
      return DIENUM_CONTINUE;
   }

ここでも、IDirectInputDevice7::SetCooperativeLevel の第 1 パラメータは、呼び出し側オブジェクトに対するポインタである。

第 2 パラメータは、ウィンドウ ハンドルである。この場合、メイン プログラムのウィンドウ ハンドルが渡される。

最後のパラメータは、必要な協調レベルを指定するフラグの組み合わせである。Space Donuts サンプルがジョイスティックからの入力を要求するのは、フォアグラウンド アプリケーションの場合のみであり、別のプログラムが排他モードでジョイスティックを使用しているかどうかには注意を払わない。したがって、フラグには DISCL_NONEXCLUSIVE | DISCL_FOREGROUND が設定される (これらのフラグの詳細については、「協調レベル」を参照)。

最終手順は、デバイスのプロパティを設定することであり、コールバック関数で列挙されている各ジョイスティックに対して実行される。サンプルでは、変更されるプロパティに x 軸と y 軸の両方の範囲とデッド ゾーンが含まれている。

範囲を設定することにより、返させたい軸の最大値と最小値が何であるかを DirectInput に指示することになる。例のように、x 軸に対して範囲 -1,000 から +1,000 を設定すると、ジョイスティックが最左端にある場合に値 -1,000 を、最右端にある場合に +1,000 を、中央にある場合にゼロをそれぞれ返すことを要求することになる。

デッド ゾーンは、軸の中間にある許容領域であり、軸移動の物理的範囲の 10,000 分の 1 単位で測定される。x 軸に対して 1,000 のデッド ゾーンを設定すると、スティックを中心位置から軸移動範囲の 10 分の 1 だけ左右に移動しても、スティックは中心にあるとみなされることを示す。無効ゾーンの詳細については、「ジョイスティック軸データの解釈」を参照すること。

以下は、x 軸の範囲を設定するコードである。

   DIPROPRANGE diprg;

   diprg.diph.dwSize       = sizeof(diprg);
   diprg.diph.dwHeaderSize = sizeof(diprg.diph);
   diprg.diph.dwObj        = DIJOFS_X;
   diprg.diph.dwHow        = DIPH_BYOFFSET;
   diprg.lMin              = -1000;
   diprg.lMax              = +1000;

   if FAILED(pdev->lpVtbl->SetProperty(pdev,
                   DIPROP_RANGE, &diprg.diph))
   {
      OutputDebugString("IDirectInputDevice7::SetProperty(DIPH_RANGE)
                         FAILED\n");
      pdev->lpVtbl->Release(pdev);
      return FALSE;
   }

ここでは最初に、DIPROPRANGE 構造体 diprg を設定する。その構造体のアドレスは、IDirectInputDevice7::SetProperty メソッドに渡される。実際には、構造体自体のアドレスが渡されるのではなく、その最初のメンバのアドレスが渡される。最初のメンバとは、1 つの DIPROPHEADER 構造体である。詳細については、「デバイス プロパティ」を参照すること。

プロパティ ヘッダーは、以下の値で初期化される。

  • プロパティ構造体のサイズ
  • ヘッダー構造体のサイズ
  • DIJOFS_X ジョイスティック デバイス定数マクロが返す値。プロパティを変更する対象のオブジェクトへのポインタである。
  • 第 3 パラメータの解釈方法を示すフラグ。

DIPROPRANGE 構造体の lmin と lmax メンバに必要な範囲値を割り当てる。

アプリケーションは、ここで IDirectInputDevice7::SetProperty メソッドを呼び出す。これまでと同様に、第 1 パラメータは、呼び出し側オブジェクトに対するポインタである。第 2 パラメータは、どのプロパティを変更するのかを示すフラグである。第 3 パラメータは、プロパティ構造体の DIPROPHEADER メンバのアドレスである。

x 軸の無効ゾーンの設定も同様にして行える。Space Donuts サンプルは、ヘルパー関数 SetDIDwordProperty を使用して、DIPROPDWORD プロパティ構造体を初期化する。DIPROPRANGE とは異なり、この構造体には、例では 5,000 が設定されているデータ メンバが 1 つしか含まれていない。この値は、軸が中心からその範囲の半分を動かなければ軸が中心を離れたとは報告されないことを示す。

   // X 軸の無効ゾーンを 50% に設定する (不測の転回を避けるため)。
   if FAILED(SetDIDwordProperty(pdev, DIPROP_DEADZONE, DIJOFS_X,
                                DIPH_BYOFFSET, 5000))
   {
      OutputDebugString("IDirectInputDevice7::
                           SetProperty(DIPH_DEADZONE) FAILED\n");
      pdev->lpVtbl->Release(pdev);
      return FALSE;
   }

次項 : ステップ 5 : ジョイスティックへのアクセス権の取得


ステップ 5 : ジョイスティックへのアクセス権の取得

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

ジョイスティックの動作を設定したら、アプリケーションは、IDirectInputDevice7::Acquire メソッドを呼び出して、デバイスに対するアクセス権を取得できる。アプリケーションは、デバイスからデータを取得する前に、デバイスを取得しなければならない。Acquire メソッドには、パラメータはない。

Space Donuts アプリケーションは、ReacquireInput 関数の中でデバイスの取得を処理している。この関数は、二重の機能を実行する。すなわち、スタートアップ時にデバイスを取得する機能、そしてアプリケーションが入力データの取得を試みて、何らかの理由で DIERR_INPUTLOST エラーが返されたときにデバイスを再取得する機能である。

以下のコードでは、g_pdevCurrent は、現在使用されている DirectInput デバイスが何であれ、それに対するグローバル ポインタである。

BOOL ReacquireInput(void)
{
    HRESULT hRes;

    // 現デバイスがあれば、
    if (g_pdevCurrent)
    {
        // それを取得する。
        hRes = IDirectInputDevice_Acquire(g_pdevCurrent);
        // この呼び出しは、次のように展開されるマクロである。
        // g_pdevCurrent->lpVtbl->Acquire(g_pdevCurrent);

        if (SUCCEEDED(hRes))
        {
            // 取得成功。
            return TRUE;
        }
        else
        {
            // 取得失敗。
            return FALSE;
        }
    }
    else
    {
        // 現デバイスがない。
        return FALSE;
    }
}

この例では、デバイスの取得は、Dinput.h で定義されている IDirectInputDevice_Acquire マクロの呼び出しによって実現されている。このマクロは、IDirectInputDevice7::Acquire メソッドに対する C の呼び出しを簡単にするものである。

次項 : ステップ 6 : ジョイスティックからのデータを取得


ステップ 6 : ジョイスティックからのデータを取得

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションでは、ジョイスティック軸の移動よりも、ジョイスティック軸の位置の方が重要であることが多いので、デバイスからは、バッファリング データよりも直接データを取得することがよく行われる。直接データは、IDirectInputDevice7::GetDeviceState でポーリングすることによって取得できる。デバイス状態が変化したとき、すべてのデバイス ドライバが DirectInput に通知するとは限らないので、デバイス状態をチェックする前に IDirectInputDevice7::Poll メソッドを呼び出すことは常に適切な処置である。

Space Donuts アプリケーションは、ジョイスティックがアクティブな入力デバイスであるという前提で、レンダリング ループを使って、各パスについて下記の関数を呼び出す。

DWORD ReadJoystickInput(void)
{
    DWORD                   dwKeyState;
    HRESULT                 hRes;
    DIJOYSTATE              js;

    // 現在の状態を読み取るジョイスティックをポーリングする。
    hRes = IDirectInputDevice7_Poll(g_pdevCurrent);

    // ジョイスティックからデータを入力する。
    hRes = IDirectInputDevice7_GetDeviceState(g_pdevCurrent,
                                            sizeof(DIJOYSTATE), &js);

    if (hRes != DI_OK)
    {
        // 何らかの理由で入力を失ったために読み取りが失敗したのか？
        // そうなら再取得を試みる。これも失敗したなら、
        // GetDeviceData からのエラーは、DIERR_NOTACQUIRED である。
        // この結果、無限ループに陥らないで済む。
        if(hRes == DIERR_INPUTLOST)
            ReacquireInput();

        // データがまったく読み取れなかったという事実が返される。
        return 0;
    }

    // スティックとボタンの位置を調べる。

    dwKeyState = 0;
    if (js.lX < 0) {
        dwKeyState |= KEY_LEFT;
    } else if (js.lX > 0) {
        dwKeyState |= KEY_RIGHT;
    }

    if (js.lY < 0) {
        dwKeyState |= KEY_UP;
    } else if (js.lY > 0) {
          dwKeyState |= KEY_DOWN;
   }

    if (js.rgbButtons[0] & 0x80) {
        dwKeyState |= KEY_FIRE;
    }

    if (js.rgbButtons[1] & 0x80) {
        dwKeyState |= KEY_SHIELD;
    }

    if (js.rgbButtons[2] & 0x80) {
        dwKeyState |= KEY_STOP;
    }

    return dwKeyState;
}

IDirectInputDevice7_Poll および IDirectInputDevice7_GetDeviceState への呼び出しに注意すること。これらは、対応するメソッドへの C の呼び出しを展開するマクロであり、このチュートリアルの前のステップに出てきたマクロに類似している。このマクロへのパラメータは、メソッドへ渡すパラメータと同じである。この点は、GetDeviceState への呼び出しに類似している。

    hRes = IDirectInputDevice7_GetDeviceState(g_pdevCurrent,
                                             sizeof(DIJOYSTATE), &js);

1 番目のパラメータは、呼び出し側オブジェクトに対するポインタである。第 2 パラメータは、データが返される構造体のサイズである。最後のパラメータは、DIJOYSTATE 型であるこの構造体のアドレスである。この構造体は、最高 6 つの軸、32 のボタン、および 1 つの視点ハットを保持する。サンプル プログラムでは、2 つの軸と 3 つのボタンの状態を確認する。

軸の位置がゼロ以外と報告された場合、その軸は無効ゾーンの外側にあるので、関数は、dwKeyState 変数を適切に設定して応答する。この変数は、キーボードまたはジョイスティックのいずれかで入力された現在のユーザー コマンドのセットを保持する。たとえば、ジョイスティックの x 軸がゼロより大きければ、右向き矢印キーが押されているとみなされる。

ジョイスティック ボタンは、キーまたはマウス ボタンとまったく同じように機能する。戻り値バイトの上位ビットが設定されていれば、ボタンがダウン状態であることを示す。


チュートリアル 4 : フォース フィードバックの使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、フォース フィードバック ジョイスティックで単純なエフェクトを生成、再生、変更する手順を示す。このエフェクトは、始動させようとしてもなかなか始動しないチェーンソーに少し似ている。サンプル コードは C++ で記述してある。

DirectInput システムのセットアップの準備手順とシステムを終了する最後の手順は、どのアプリケーションでも基本的に同じであり、これについては「チュートリアル 1 : キーボードの使用」で説明してある。しかし、DirectInput フォース フィードバック システムを終了するときは、生成したエフェクトを解除する手順を追加しなければならない。

チュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : フォース フィードバック デバイスの列挙
  • ステップ 2 : DirectInput フォース フィードバック デバイスの作成
  • ステップ 3 : サポートされたエフェクトの列挙
  • ステップ 4 : エフェクトの生成
  • ステップ 5 : エフェクトの再生
  • ステップ 6 : エフェクトの変更


ステップ 1 : フォース フィードバック デバイスの列挙

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

最初の手順は、フォース フィードバック デバイスがシステムで利用できるようにすることである。これを行うには IDirectInput7::EnumDevices メソッドを呼び出す。次の例では、列挙が少なくとも 1 つの適合するデバイスを見つけることができた場合のみ、ゲーム デバイス インターフェイスへのグローバル ポインタが初期化される。

LPDIRECTINPUTDEVICE7  g_lpdid7 = NULL;

lpdi->EnumDevices(DIDEVTYPE_JOYSTICK,
                  DIEnumDevicesProc,
                  NULL,
                  DIEDFL_FORCEFEEDBACK | DIEDFL_ATTACHEDONLY);
if (g_lpdid7 == NULL)
  {
  // フォース フィードバック ジョイスティックが利用できない。適切な処理をとる。
  }

この例では、lpdi は IDirectInput7 インターフェイスへの初期化済みポインタである。EnumDevices の第 1 パラメータにより、列挙対象がジョイスティック類のデバイスに限定される。第 2 パラメータは、DirectInput が列挙できるデバイスを識別するたびに呼び出されるコールバック関数である。第 3 パラメータは、コールバック関数に渡される、またはコールバック関数から渡されるユーザー定義データを表す。この例では使用されていない。最後に、第 4 パラメータのフラグにより、列挙対象が、フォース フィードバックをサポートするシステムに実際にアタッチされているデバイスに限定される。

コールバック関数は、デバイスが発見されるとすぐにそのデバイスを初期化するのに便利である (最初に発見されたのが使用したいデバイスであることを前提としている)。この処理は、「ステップ 2 : DirectInput フォース フィードバック デバイスの作成」で行うことになる。


ステップ 2 : DirectInput フォース フィードバック デバイスの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

DirectInput にデバイスを列挙させるには、DIEnumDevicesCallback と同種のコールバック関数を作成しなければならない。ステップ 1 では、この関数のアドレスを IDirectInput7::EnumDevices メソッドに渡している。

DirectInput は、知る必要があるデバイスについての情報を通知する DIDEVICEINSTANCE 構造体へのポインタを、第 1 パラメータとしてコールバック関数へ渡す。次の例で最も重要な構造体メンバは guidInstance であり、これは、ユーザーのシステムで特定のハードウェアを識別する唯一の手段である。この GUID は、後で IDirectInput7::CreateDeviceEx メソッドに渡さなければならない。

次に示すのは、コールバック関数の最初の部分であり、GUID を取り出してデバイス オブジェクトを作成する。

BOOL CALLBACK DIEnumDevicesProc(LPCDIDEVICEINSTANCE lpddi,
                                LPVOID pvRef)
  {
  HRESULT hr;
  GUID DeviceGuid = lpddi->guidInstance;

  // ゲーム デバイスを生成する。

  hr = lpdi->CreateDeviceEx(DeviceGuid, IID_IDirectInputDevice7,
          (void**)&g_lpdid7, NULL);

  if (FAILED(hr))
    {
    OutputDebugString("デバイスの作成に失敗しました。\n");
    return DIENUM_STOP;
    }

次の手順は、まだコールバック関数の中であるが、入力デバイスのセットアップ処理に類似している。注意すべきは、どのフォース フィードバック デバイスにとっても排他協調レベルが必要であるということである。また、データ形式を設定する必要もある。

  // 協調レベルの設定
  if (FAILED(g_lpdid7->SetCooperativeLevel(hMainWindow,
         DISCL_EXCLUSIVE | DISCL_FOREGROUND)))
    {
    OutputDebugString(
      "協調レベルの設定に失敗しました。\n");
    g_lpdid7->Release();
    g_lpdid7 = NULL;
    return DIENUM_STOP;
    }

  // ゲームデータ形式の設定
  if (FAILED(g_lpdid7->SetDataFormat(&c_dfDIJoystick)))
    {
    OutputDebugString("ゲーム デバイス データ形式の設定に失敗しました。\n");
    g_lpdid7->Release();
    g_lpdid7 = NULL;
    return DIENUM_STOP;
    }

最後に、デバイスの自動センタリング機能をオフにしたい場合に触れる。基本的に自動センタリング機能は、モーターを使って標準ジョイスティックでスプリングをシミュレートする条件エフェクトである。この機能をオフにすると、ほかのエフェクトが妨害されなくなる。

  DIPROPDWORD DIPropAutoCenter;

  DIPropAutoCenter.diph.dwSize = sizeof(DIPropAutoCenter);
  DIPropAutoCenter.diph.dwHeaderSize = sizeof(DIPROPHEADER);
  DIPropAutoCenter.diph.dwObj = 0;
  DIPropAutoCenter.diph.dwHow = DIPH_DEVICE;
  DIPropAutoCenter.dwData = 0;

  if (FAILED(lpdid7->SetProperty(DIPROP_AUTOCENTER,
          &DIPropAutoCenter.diph)))
    {
    OutputDebugString("Failed to change device property.\n");
    }

  return DIENUM_STOP;   // 1 つで十分。
  } // DIEnumDevicesProc の終了。

使用前に、デバイスを取得しなければならない。取得方法の例については、チュートリアル 3 の「ステップ 5 : ジョイスティックへのアクセス権の取得」を参照すること。

次項 : ステップ 3 : サポートされたエフェクトの列挙


ステップ 3 : サポートされたエフェクトの列挙

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

これまでにフォース フィードバック デバイスの列挙と生成に成功したので、そのデバイスがサポートするエフェクトのタイプを列挙することができる。

どのデバイスでも利用可能な標準的エフェクトのみを生成したい場合は、エフェクトの列挙は必ずしも必要ではない。エフェクト オブジェクトを生成するとき、GUID_ConstantForce などの定義済み GUID のうちどれか 1 つを使って、目的のエフェクト タイプを簡単に識別することができる。これらの識別子の全リストについては、「IDirectInputDevice7::CreateEffect」を参照すること。

もっと柔軟性のある方法は、特定タイプのサポートされるエフェクトを列挙し、コールバック関数からエフェクトに対する GUID を取得することである。FFDonuts サンプルでは、この方法が使われている。ここでもそのサンプル アプリケーションを応用することにする。もちろん、コールバック関数を使用して、エフェクトに対するデバイスのサポートについての詳細情報 (たとえば、デバイスがエンベロープをサポートしているかどうかについて) を得ることもできるが、このチュートリアルではエフェクト GUID だけを取得することにする。

まず、列挙されたエフェクトそれぞれについて DirectInput によって呼び出されるコールバック関数を生成する。この標準コールバックの情報は、「DIEnumEffectsCallback」を参照すること。この関数には好きな名前を付けることができる。

BOOL EffectFound = FALSE; // グローバル フラグ

BOOL CALLBACK DIEnumEffectsProc(LPCDIEFFECTINFO pei, LPVOID pv)
  {
*((GUID *)pv) = pei->guid;
EffectFound = TRUE;
return DIENUM_STOP; // 1 つで十分
  }

アプリケーションで定義された値 pv が指す GUID 変数には、エフェクトのために DirectInput が生成する DIEFFECTINFO 構造体へ渡される値が代入される。

エフェクト GUID を取得するために、次のように IDirectInputDevice7::EnumEffects メソッドを呼び出し、コールバックをスタートさせる。

HRESULT  hr;
GUID     guidEffect;

hr = g_lpdid7->EnumEffects(
     (LPDIENUMEFFECTSCALLBACK) DIEnumEffectsProc,
     &guidEffect,
     DIEFT_PERIODIC);
if (FAILED(hr))
  {
  OutputDebugString("エフェクトの列挙に失敗しました。\n");
  // 注意 : 成功したといっても、どれかのエフェクトが発見されたということを意味するわけではなく、
  // 単に処理がスムーズに行われたことを意味する。
  }

GUID 変数のアドレス guidEffect を EnumEffects メソッドに渡すことに注意すること。このアドレスは、コールバック関数に pv パラメータとして渡される。さらに、DIEFT_PERIODIC フラグを設定して、列挙対象を周期的エフェクトに限定する。

次項 : ステップ 4 : エフェクトの生成


ステップ 4 : エフェクトの生成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

エフェクトの列挙後 EffectFound の値が FALSE でなければ、必要なエフェクト タイプの少なくとも 1 つに対するサポートを DirectInput が発見したとみなしてよい (もちろん、実際には、不特定な周期的エフェクトを発見しただけでは満足できないだろう。サインや鋸歯などの特定のエフェクトを使用したいだろうから)。エフェクト GUID が備わっているので、今度はエフェクト オブジェクトを生成することができる。

IDirectInputDevice7::CreateEffect メソッドを呼び出す前に、次の配列と構造体を設定する必要がある。

  • エフェクトにかかわる軸の配列。ジョイスティックの場合、この配列は通常 x 軸と y 軸に対する識別子からなる。
  • 方向を設定する値の配列。これらの値は、軸の数と使用する座標の種類 (極座標、球面座標、デカルト座標) に応じて異なる。この配列の複雑な働きについての詳しい説明は、「エフェクトの方向」を参照すること。
  • タイプ固有パラメータの構造体。次の例では、周期的エフェクトを生成しているので、構造体のタイプは DIPERIODIC となっている。
  • エフェクトに適用するエンベロープを定義する DIENVELOPE 構造体。
  • 最後に、エフェクト用の基本的パラメータを格納する DIEFFECT 構造体。

まず、配列と構造体を宣言する。配列は次のように一度に初期化できる。

DWORD      dwAxes[2] = { DIJOFS_X, DIJOFS_Y };
LONG       lDirection[2] = { 0, 0 };

DIPERIODIC diPeriodic;      // タイプ固有パラメータ
DIENVELOPE diEnvelope;      // エンベロープ
DIEFFECT   diEffect;        // 汎用パラメータ

次にタイプ固有パラメータを初期化する。次の例のような値を設定すると、1/20 秒周期の全力周期的エフェクトを生成することになる。

diPeriodic.dwMagnitude = DI_FFNOMINALMAX;
diPeriodic.lOffset = 0;
diPeriodic.dwPhase = 0;
diPeriodic.dwPeriod = (DWORD) (0,05 * DI_SECONDS);

チェーンソーのモーターが始動しようとして、短い間咳のような騒音を出し、次第にそれが止んでいくというエフェクトを得るために、エンベロープに半秒間のアタック時間と 1 秒間のフェード時間を設定する。こうして、短期間の維持期間値が得られる。

diEnvelope.dwSize = sizeof(DIENVELOPE);
diEnvelope.dwAttackLevel = 0;
diEnvelope.dwAttackTime = (DWORD) (0.5 * DI_SECONDS);
diEnvelope.dwFadeLevel = 0;
diEnvelope.dwFadeTime = (DWORD) (1.0 * DI_SECONDS);

次に、基本的エフェクトパラメータを設定する。これらのパラメータには、方向とデバイス オブジェクト (ボタンと軸) の識別方法を決定するフラグ、エフェクトのサンプル周期とゲイン、およびさきほど準備した他のデータへのポインタが含まれる。さらに、ジョイスティックの発射ボタンにエフェクトを割り付けて、ボタンを押せばエフェクトが自動的に再生するようにする。

diEffect.dwSize = sizeof(DIEFFECT);
diEffect.dwFlags = DIEFF_POLAR | DIEFF_OBJECTOFFSETS;
diEffect.dwDuration = (DWORD) (2 * DI_SECONDS);

diEffect.dwSamplePeriod = 0;               // デフォルト値
diEffect.dwGain = DI_FFNOMINALMAX;         // スケーリングなし
diEffect.dwTriggerButton = DIJOFS_BUTTON0;
diEffect.dwTriggerRepeatInterval = 0;
diEffect.cAxes = 2;
diEffect.rgdwAxes = dwAxes;
diEffect.rglDirection = &lDirection[0];
diEffect.lpEnvelope = &diEnvelope;
diEffect.cbTypeSpecificParams = sizeof(diPeriodic);
diEffect.lpvTypeSpecificParams = &diPeriodic;

セットアップはここまで。やっとエフェクトを生成できる。

LPDIEFFECT  g_lpdiEffect;  // グローバル エフェクト オブジェクト

HRESULT hr = g_lpdid7->CreateEffect(
                 guidEffect,     // 列挙からの GUID
                 &diEffect,      // データの場所
                 &g_lpdiEffect,  // インターフェイス ポインタを置く場所
                 NULL);          // 集合化なし
if (FAILED(hr))
  {
  OutputDebugString("周期的エフェクトの作成に失敗しました。");
  }

デバイスが排他協調レベルで取得された状態にあれば、デフォルトでは、このエフェクトは生成されると同時にデバイスにダウンロードされることを覚えておくこと。すべてが計画通りに進めば、コンパイルして、実行することができるはずである。発射ボタンを押せば、ガス欠のチェーンソーが立てる激しい音を聞くことができるはずである。

次項 : ステップ 5 : エフェクトの再生


ステップ 5 : エフェクトの再生

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

前のステップで生成したエフェクトはボタン押下に応答して始動する。明示的な呼び出しに応答して再生するエフェクトを生成するには、ステップ 4 に戻って、DIEFFECT 構造体のメンバ dwTriggerButton を次のように変更する必要がある。

diEffect.dwTriggerButton = DIEB_NOTRIGGER;

ここで、実際に始動し、動き続けるチェーンソーを作ることを考える。dwDuration メンバを次のように変更するだけでよい。

diEffect.dwDuration = INFINITE;

このエフェクトを始動するのは非常に簡単である。

g_lpdiEffect->Start(1, 0);

このエフェクトは次のようにして止めるまで働き続ける。

g_lpdiEffect->Stop();

注意してほしいのは、前のステップで生成したエンベロープを変更する必要がないことである。アタックはエフェクトが始動すると再生するが、フェード値は無視される。

次項 : ステップ 6 : エフェクトの変更


ステップ 6 : エフェクトの変更

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic チュートリアル」を参照すること。

[C++]

チェーンソーは陽気にガタガタと音を立てている。このチェーンソーが木材に切り込む時にエンジンが減速するシミュレーションをするために、このエフェクトを変更したいとする。幸い、DirectInput では再生中のエフェクトのパラメータを変更することができる。

このエフェクトを変更するには、DIEFFECT 構造体のセットアップ、またはこのエフェクトの生成に使用した構造体へのアクセスが必要である。有効な新しい構造体をローカルにセットアップする場合は、dwSize メンバと、変更するデータを含むまたはそのデータを指すメンバのみを初期化すればよい。

この例では、タイプ固有パラメータ (エフェクトの周期) を変更しようとしているので、エフェクトを生成するときに使用した DIPERIODIC 構造体へのアクセスが必要である。この構造体のローカル コピーを作り、すべてのメンバを初期化してもよい。DIPERIODIC 構造体のアドレスが DIEFFECT 構造体のメンバ lpvTypeSpecificParams に格納されていることを確認する。

エフェクトの新しい周期を設定する。

diPeriodic.dwPeriod = (DWORD) (0.08 * DI_SECONDS);

その後、実際に変更を行うメソッドを呼び出す。

HRESULT hr = g_lpdiEffect->SetParameters(&diEffect,
                           DIEP_TYPESPECIFICPARAMS)

この変更を DIEFFECT 構造体の 1 つのメンバに限定しているフラグに注意すること。

ほかのフラグを使って、変更の方法を制御することができる。たとえば、DIEP_NODOWNLOAD フラグを使えば、エフェクトの始動直後にパラメータを変更し、しかも、ユーザーが実際に木材を切り始めるまで、新しいエフェクトの実行を遅らせることができるだろう。その後、IDirectInputEffect::Download メソッドを呼び出すことになるだろう。さまざまな制御フラグの使用方法については、IDirectInputEffect::SetParameters を参照すること。


DirectInput Visual Basic チュートリアル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここでは、次のチュートリアルを使用して、Visual Basic アプリケーションに DirectInput を実装する方法をステップ バイ ステップで説明する。

  • チュートリアル 1 : キーボードの使用

    最初のチュートリアルは、イベント ポーリングを使って、既存のアプリケーションに DirectInput キーボード サポートを追加する手順を示す。

  • チュートリアル 2 : マウスの使用

    2 番目のチュートリアルは、排他協調レベルとイベント通知を使って、アプリケーションで DirectInput マウス サポートを実現する手順を示す。このチュートリアルは、ScrawlB サンプルを基本としており、バッファリング データに焦点を当てる。

  • チュートリアル 3 : ジョイスティックの使用

    このチュートリアルは、システムに接続されているジョイスティックをすべて列挙する方法、コールバック関数で各ジョイスティックに対する DirectInput デバイス オブジェクトを作成して初期化する方法、および直接データを取得する方法を示す。

  • チュートリアル 4 : フォース フィードバックの使用

    最後のチュートリアルでは、アプリケーションに単純なフォース フィードバック エフェクトを実装する方法を示す。


チュートリアル 1 : キーボードの使用

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

キーボード入力の準備を行うには、まず、DirectInput オブジェクトを作成する。次に、キーボードを表す DirectInputDevice オブジェクトを作成する。デバイスの動作を設定したり、データを取得したりするには、DirectInputDevice クラスのメソッドを使用する。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : DirectInput とキーボード デバイスの作成
  • ステップ 2 : キーボード パラメータの設定
  • ステップ 3 : キーボードのアクセス権の取得
  • ステップ 4 : キーボードからの直接データの取得


ステップ 1 : DirectInput とキーボード デバイスの作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectInput システムのセットアップ手順の最初は、全体のマネージャとして単一の DirectInput オブジェクトを作成することである。これは、DirectX7.DirectInputCreate メソッドを呼び出すことにより実現される。このメソッドは通常、メイン フォームの Load イベントか、Sub Main の中で次のように呼び出す。

Dim dx As New DirectX7
Dim di As DirectInput

Set di = dx.DirectInputCreate()

次に、DirectInput.CreateDevice にキーボード GUID を渡し、キーボードを標準デバイスとして作成する。

Dim didev As DirectInputDevice
Set didev = di.CreateDevice("GUID_SysKeyboard")

次項 : ステップ 2 : キーボード パラメータの設定


ステップ 2 : キーボード パラメータの設定

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectInputDevice を作成したら、デバイスのデータ形式を設定しなければならない。キーボードの場合は、その他の標準デバイスと同様に、非常に簡単なタスクである。DirectInputDevice.SetCommonDataFormat メソッドを呼び出す。パラメータとして DIFORMAT_KEYBOARD を渡すことで、便宜上 DirectInput で用意されたデータ形式を指定する。

Call didev.SetCommonDataFormat(DIFORMAT_KEYBOARD)

バッファリング データを取得する場合であっても、データ形式を設定しなければならない。DirectInput では、データ形式内のオフセットでデバイス オブジェクトを識別する。キーボードの場合、キーは DIKEYBOARDSTATE 型内のオフセットで識別される。

アプリケーションは、キーボードへのアクセス権を取得する前に、次のように DirectInputDevice.SetCooperativeLevel メソッドを使ってデバイスの動作を設定しなければならない。

didev.SetCooperativeLevel Me.hWnd, _
        DISCL_NONEXCLUSIVE Or DISCL_BACKGROUND

このメソッドは、デバイスに関連付けられたウィンドウのハンドルと、必要な協調レベルを示す 2 つのフラグ (DISCL_EXCLUSIVE と DISCL_NONEXCLUSIVE のいずれか、および DISCL_FOREGROUND と DISCL_BACKGROUND のいずれか) を受け取る。DirectInput は、キーボード デバイスに対する排他アクセス権をサポートしていないので、この場合は DISCL_NONEXCLUSIVE フラグを指定しなければならない。

また、この例ではバックグラウンド協調レベルを設定し、フォームがフォアグラウンドにあるかどうかにかかわらず入力を受け付けるようにしている。キー ストロークは引き続き、フォーカスを持つアプリケーションに渡されることに注意すること。大部分のアプリケーションはバックグラウンドにある間に入力を受け付ける必要はない。また、そのような場合には、DISCL_FOREGROUND フラグを設定するべきである。

次項 : ステップ 3 : キーボードのアクセス権の取得


ステップ 3 : キーボードのアクセス権の取得

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

キーボードの動作を設定し終えたら、DirectInputDevice.Acquire メソッドを呼び出すことでデバイスへのアクセス権を取得できる。アプリケーションは、デバイスからデータを取得する前に、デバイスを取得しなければならない。Acquire メソッドはパラメータを取らない。

Call didev.Acquire

サンプル コードでは、アプリケーションはバックグラウンドの非排他協調レベルを使用しているので、キーボードの取得に失敗したり、後でアクセスを喪失したりする可能性はない。ただし通常は、Acquire を呼び出す場合も、データを取得しようとする際と同様に、エラー処理を行うのが好ましい。

次項 : ステップ 4 : キーボードからの直接データの取得


ステップ 4 : キーボードからの直接データの取得

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

デバイスを取得すれば、アプリケーションは、デバイスからのデータの取得を開始できる。これを最も簡単に行う方法は、DirectInputDevice.GetDeviceStateKeyboard メソッドを呼び出すことである。このメソッドは、呼び出し時のその瞬間のデバイスの状態を取得する。

GetDeviceStateKeyboard メソッドは、単一のパラメータとして DIKEYBOARDSTATE 型を受け取る。このパラメータは単に、256 バイトの配列を含んでいる。

以下のコードは、キーボードの状態を取得する例である。

Dim state As DIKEYBOARDSTATE
Call didev.GetDeviceStateKeyboard(state)

キーボードの現在の状態を取得した後、アプリケーションは、呼び出し時に押された特定のキーに応答することができる。バッファ中の各要素が 1 つのキーを表す。要素の上位ビットがオンの場合、そのキーは、呼び出し時に押されていたことを示す。それ以外の場合は、キーは押されていない。あるキーの状態をチェックするには、CONST_DIKEYFLAGS 列挙の定数を使用して、そのキーに対するバッファのインデックスを作成する。

次のサンプル コードでは、アプリケーションが矢印キーに応答して車を移動する方法を示す。

If state.Key(DIK_UP) And &H80 Then
  ' 車を上方向に移動する。
End If
if state.Key(DIK_DOWN) And &H80 Then
  ' 車を下方向に移動する。
End If
' 以下同様。

次のコードも同じように動作する。

If state.Key(DIK_UP)
  ' Move the vehicle up
End If

DirectInput の現在のバージョンにおけるすべてのボタンと同様に、キーがアップであれば、キーの状態を表す値はゼロである。ただし、将来のバージョンでは、複数の状態を持ち、ゼロ以外の値を複数持つ "アナログ" キーがサポートされる可能性がある。このため、特にキーボード以外のデバイスを扱う場合、後者のコードは慎重に使用しなければならない。

また、DIK_UP は専用の方向キーであり、上向き矢印を表す単一のキーであることに注意。DirectInput では、テンキー上の 8 つのキーを特異キーとして扱い、NUM LOCK が有効かどうかにかかわらず、同一の識別子が付与される。矢印キーのいずれかから入力を受け取るようにするには、次のようなコードを記述する必要がある。

If state.Key(DIK_UP) Or state.Key(DIK_NUMPAD8) Then
  ' 車を上方向に移動する。
End If


チュートリアル 2 : マウスの使用

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、マウスを排他協調レベルで使用し、通知に応答してバッファリング データを取得する方法を示す。サンプル コードは、ScrawlB サンプルを基にしている。

このチュートリアルは、次のステップで構成されている。

  • ステップ 1 : マウスの設定
  • ステップ 2 : 通知の設定
  • ステップ 3 : マウスの排他アクセス権の管理
  • ステップ 4 : マウスからのバッファリング データの取得


ステップ 1 : マウスの設定

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectInput でマウスを使用するためのセットアップにおける最初の手順は、「チュートリアル 1 : キーボードの使用」で実行した手順とほぼ同じである。ScrawlB サンプルでは、Sub Main でいくつかのグローバル変数を宣言してから、次のように初期化を行う。

Public objDX As New DirectX7
Public objDI As DirectInput
.
.
.
Set objDIDev = objDI.CreateDevice("guid_SysMouse")
Call objDIDev.SetCommonDataFormat(DIFORMAT_MOUSE)
Call objDIDev.SetCooperativeLevel(frmCanvas.hwnd, _
        DISCL_FOREGROUND Or DISCL_EXCLUSIVE)

ここで、デバイスは排他コントロールを得る。その結果、アプリケーションがマウスを取得した状態にある限り、Windows はマウス メッセージを生成したり、システム カーソルを表示したりしない。DISCL_EXCLUSIVE は DISCL_FOREGROUND と組み合わせなければならない。なぜなら、アプリケーションがフォーカスを失った場合、マウスへの排他アクセスを持つことができず、データを取得することもできないからである。

ScrawlB サンプル アプリケーションはマウスに対する全責務を引き継ぐので、専用カーソルの位置を追跡したり、マウスの動きに合わせてカーソルの移動をスケーリングしたりしなければならない。次のグローバル変数は、カーソル座標 (メインフォームの左上隅からの相対ピクセル数) と移動スケーリングの格納に使用する。

Public g_cursorx As Long
Public g_cursory As Long
Public g_Sensitivity

Sub Main に戻り、バッファリング データを受け取ることができるように、DirectInputDevice.SetProperty メソッドを使ってバッファ サイズを設定する。

Dim diProp As DIPROPLONG
diProp.lHow = DIPH_DEVICE
diProp.lObj = 0
diProp.lData = BufferSize    ' BufferSize は定数
diProp.lSize = Len(diProp)
Call objDIDev.SetProperty("DIPROP_BUFFERSIZE", diProp)

次項 : ステップ 2 : 通知の設定


ステップ 2 : 通知の設定

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

ScrawlB サンプル アプリケーションは、Sub Main でマウス入力をポーリングするのではなく、マウス イベントが発生したときに必ずマウス入力を通知するよう、DirectInput に依存する。アプリケーションは初期化処理中にイベント ハンドルを取得し、そのハンドルを DirectInputDevice.SetEventNotification に渡す。

Dim EventHandle As Long
EventHandle = objDX.CreateEvent(frmCanvas)
Call objDIDev.SetEventNotification(EventHandle)

これにより、DirectInput は DirectXEvent クラスを実装するすべてのオブジェクトを通知する。ScrawlB の場合、実装するオブジェクトは frmCanvas フォームであり、その宣言セクションには次の行が含まれる。

Implements DirectXEvent

この行により、frmCanvas は DirectXEvent クラスのメソッドを継承する。この行が実行されると、そのクラスの可視メソッドは DirectXEvent.DXCallback のみであり、継承したクラスはこのメソッドを実装しなければならない。入力イベントが発生すると必ず DirectInput はこのメソッドを呼び出すようになる。

DXCallback の実装方法については「ステップ 4 : マウスからのバッファリング データの取得」で説明する。

次項 : ステップ 3 : マウスの排他アクセス権の管理


ステップ 3 : マウスの排他アクセス権の管理

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

ScrawlB サンプルでは、排他フォアグラウンド協調レベルでマウスを使用する方法を示す。このレベルでは、マウスがアプリケーションに取得されている間、Windows はマウスを追跡しない。その場合、アプリケーションには主に、次の 3 つの重要な役割がある。

  • カーソルが必要な場合はカーソルを表示し、DirectInput データに応答して適切な速度でカーソルを移動しなければならない。
  • ユーザーがキーボードを使って別のアプリケーションに切り替えると取得は失われる。ユーザーがこのアプリケーションに戻したときに、マウスを再取得しなければならない。
  • アプリケーション内のメニューを操作するなど、ユーザーがシステム カーソルを使用したいときに、Windows がマウスを取得できる手段を提供しなければならない。

ScrawlB は、ユーザー定義の感度値により調整されたマウス移動の専用レコードを保持し、描画用カーソルとして機能するアイコンを表示することで、第 1 の役割を処理する。

ScrawlB は、アプリケーション ウィンドウがバックグラウンドに移行すると、必ずマウスは解放される。アプリケーションがフォアグラウンドに戻ると、アプリケーションは MouseMove イベント ハンドラの中で DirectInputDevice.Acquire を呼び出すことで、マウスを自動的に再取得する。このハンドラは、Windows がマウス メッセージをアプリケーションに送信するときに呼び出される。この処理は、システム カーソルがクライアント ウィンドウ上に移動するか、クライアント ウィンドウがシステム カーソルの下のフォーカスを取得すると、発生する。ScrawlB がマウスを再取得した後は、当然ながら Windows マウス メッセージは送信されないので、これ以降のマウス イベントに応答して Form_MouseMove メソッドが呼び出されることはない。

ユーザーがコンテキスト メニューを操作したり、またはウィンドウのサイズを変更するなど、ほかの目的のためにシステム カーソルを表示したりできるように、ユーザーがメニューを表示すると、ScrawlB は DirectInputDevice.Unacquire メソッドを呼び出す。メニューが閉じられると、Form_MouseMove が呼び出され、マウスが再取得される。ただし、ユーザーがメニューから [Suspend] を選択する場合を除く。この場合はフラグが設定される。このフラグは、Form_MouseMove によるマウスの再取得を妨害するので、ユーザーはシステム カーソルを引き続き使用できる。

サンプル アプリケーションでは、マウスを解放する複数の方法を示している。ユーザーが Alt キーを押しながらスペース キーを押して、システム メニューを表示する場合、Windows は WM_ENTERMENULOOP メッセージを送信する。このメッセージは、サブクラス化されたウィンドウ プロシージャによりインターセプトされるので、マウスは取得されない。メニューを操作するためやユーザーがウィンドウのサイズを変更するために Windows がシステム カーソルを使用している限り、Windows は frmCanvas に対してマウス メッセージを送信しない。したがって、アプリケーションは Form_MouseMove でマウスを再取得しようとはしない。WM_ACTIVATE や WM_ACTIVATEAPP など、ほかの Windows メッセージを傍受する際にも同様の方法が使用される。これによりアプリケーションは、フォーカスの取得と喪失に応答して、マウスの取得と解放を完全に制御できる。

次項 : ステップ 4 : マウスからのバッファリング データの取得


ステップ 4 : マウスからのバッファリング データの取得

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

ScrawlB サンプルは、frmCanvas により実装される DirectXEvent.DXCallback メソッド内部で、マウスのバッファリング データを取得する。入力イベントが発生すると必ずこのメソッドが呼び出される。

このメソッドは、DirectInput がデータの格納に使用するバッファと同じサイズのバッファを宣言する。これは、以前の DirectInputDevice.SetProperty の呼び出しにより設定されたサイズである。

Dim diDeviceData(1 To BufferSize) As DIDEVICEOBJECTDATA

また、実際に取得された項目数を受け取る変数、ループ カウンタ、およびイベントの前回のシーケンス番号を追跡する変数も必要である。

Dim NumItems As Integer
Dim i As Integer
Static OldSequence As Long

この時点でアプリケーションは、DirectInputDevice.GetDeviceData を一度呼び出すことで、利用可能なデータをすべて取得する。

On Error GoTo INPUTLOST
NumItems = objDIDev.GetDeviceData(diDeviceData, 0)
On Error GoTo 0

エラー トラップに注意してほしい。DirectInput が送信するイベントの 1 つは、取得の喪失である。たとえば、ユーザーが別のアプリケーションに切り替えた場合、ScrawlB はマウスを取得した状態にはない。イベントが送信され、このメソッドが呼び出されても、GetDeviceData は失敗する。データは、取得状態にあるデバイスからしか取得できないためである。

ここでアプリケーションは、取得した項目を反復し、DIDEVICEOBJECTDATA 型内のデータを調べ、lOfs メンバと目的のさまざまなボタンと軸を表す定数を比較する。たとえば x 軸の場合、アプリケーションは lData メンバから軸位置の変化量を取得し、ユーザー定義の感度を計算しながら、これを使ってカーソル位置を調整する。

For i = 1 To NumItems
    Select Case diDeviceData(i).lOfs
        Case DIMOFS_X
           g_cursorx = g_cursorx + diDeviceData(i).lData * _
               g_Sensitivity

また、アプリケーションはシーケンス番号を調べて、前回の番号と比較する。2 つの軸イベントが同じシーケンス番号を持つ場合、マウスは斜めに移動しており、2 つの移動を計算し終えるまでは、カーソル位置を更新したり線を描画したりするべきではない。

           If OldSequence <> diDeviceData(i).lSequence Then
             UpdateCursor  ' カーソルを移動し、直線を描画する。
             OldSequence = diDeviceData(i).lSequence
           Else
             OldSequence = 0
           End If

ボタンの場合、メソッドは、lData 内の適切なビットをチェックして、イベントの種類を決定する。ビットが設定されている場合、マウス ボタンは押されている。それ以外の場合、マウス ボタンは押されていない。GetDeviceData はデバイスの現在の状態を返すものではないので、ボタンが押し下げられているかどうかの専用記録を保持するのは、アプリケーションが行わなければならない。左ボタンの場合、ScrawlB はこの情報を Drawing ブール型変数に保持する。

         Case DIMOFS_BUTTON0
           If diDeviceData(i).lData And &H80 Then
             Drawing = True

             ' Line 関数の記録を保持する。
             CurrentX = g_cursorx
             CurrentY = g_cursory

             ' 直後にボタンアップが発生した場合は、点を描画する。
             PSet (g_cursorx, g_cursory)
           Else
             Drawing = False
           End If
.
.
.
    End Select
Next i


チュートリアル 3 : ジョイスティックの使用

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、ジョイスティック デバイスの作成方法、ジョイスティックのプロパティの設定方法、および直接データの取得方法を示す。この例は、Joystick サンプルを基にしている。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : ジョイスティックの列挙と作成
  • ステップ 2 : ジョイスティック能力の取得
  • ステップ 3 : ジョイスティック プロパティの設定
  • ステップ 4 : ジョイスティックからの直接データの取得


ステップ 1 : ジョイスティックの列挙と作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

システム キーボードやシステム マウスがあるということと同じ意味での、システム ジョイスティックというものはないので、ジョイスティックの DirectInputDevice オブジェクトを作成するには、まずインスタンス GUID (グローバル ユニーク識別子) を取得する必要がある。通常、これは利用可能なジョイスティックを列挙し、ユーザーに選択肢を提示して、選択されたデバイスの情報を取得することにより実現される。

次の関数は、DirectInput を初期化し、アタッチされているジョイスティックを列挙する。

Dim dx As New DirectX7
Dim di As DirectInput
Dim diDev As DirectInputDevice
Dim diDevEnum As DirectInputEnumDevices

Sub InitDirectInput()
    On Error GoTo Error_Out

    Set di = dx.DirectInputCreate()
    Set diDevEnum = di.GetDIEnumDevices( _
            DIDEVTYPE_JOYSTICK, DIEDFL_ATTACHEDONLY)
    If diDevEnum.GetCount = 0 Then
        MsgBox "No joystick attached."
        Unload Me
    End If

    'アタッチされているジョイスティックをリストボックスに追加する。
    Dim i As Integer
    For i = 1 To diDevEnum.GetCount
        Call lstJoySticks.AddItem( _
                diDevEnum.GetItem(i).GetInstanceName)
    Next

    ' イベント ハンドルを取得して、デバイスに関連付ける。
    EventHandle = dx.CreateEvent(Me)
    Exit Sub

Error_Out:
    MsgBox "Error initializing DirectInput."
    Unload Me

End Sub

ユーザーがリストからジョイスティックを選択すると、そのデバイスが作成され、lstJoySticks_Click プロシージャ内で初期化される。

Set diDev = di.CreateDevice(diDevEnum.GetItem( _
        lstJoySticks.ListIndex + 1).GetGuidInstance)
diDev.SetCommonDataFormat DIFORMAT_JOYSTICK
diDev.SetCooperativeLevel Me.hWnd, _
        DISCL_FOREGROUND Or DISCL_NONEXCLUSIVE

DirectInput.CreateDevice の呼び出しでは、列挙から取得された DirectInputDeviceInstance オブジェクトの GUID をパラメータとして受け取る。DirectX for Visual Basic におけるすべての列挙コレクションと同様に、デバイスの列挙は 1 から開始される。したがって、インデックスは、リスト ボックスで選択された項目のインデックスよりも 1 つ大きくなる。また、リスト ボックスはソートしない。

デバイス上のオブジェクトを列挙しようとしたり、プロパティを操作しようとしたりする前に、データ形式を設定する必要がある。

次項 : ステップ 2 : ジョイスティック能力の取得


ステップ 2 : ジョイスティック能力の取得

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

デバイス上のボタン、軸、および視点コントローラについての情報を取得するには、DirectInputDevice.GetCapabilities を呼び出すだけでよい。

Dim joyCaps As DIDEVCAPS
Call diDev.GetCapabilities joyCaps

Joystick サンプルが知る必要があるのは、デバイス上のボタンと視点コントローラの数のみである。DIDEVCAPS 型は、デバイス上の軸の数も報告するが、軸の状態については一切情報を公開しない。この情報を知るために、サンプルは IdentifyAxes プロシージャを呼び出す。

Sub IdentifyAxes(diDev As DirectInputDevice)

   Dim didoEnum As DirectInputEnumDeviceObjects
   Dim dido As DirectInputDeviceObjectInstance
   Dim i As Integer

   For i = 1 To 8
     AxisPresent(i) = False
   Next

いくつかの変数を宣言し、AxisPresent 配列 (各軸に対するブール型変数を格納する) を消去してから、プロシージャはすべてのデバイス オブジェクトの列挙に進む。

   Set didoEnum = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

次に、DirectInputDevice.SetCommonDataFormat の呼び出しで以前に設定されたデータ形式の中で、そのオフセットごとに DirectInputDeviceObjectInstance を問い合わせる。このオフセットにより、軸の従来の役割やタイプが識別される。たとえば、DIJOFS_RZ 軸は、メイン スティックのひねり動作に対応することがわかる。ただし、デバイス ドライバは、軸に対して自由に指示を割り当てることができる。ユーザーがアプリケーション内で軸とアクションの対応を変更できるようにしておくのは良いアイデアである。

    For i = 1 To didoEnum.GetCount
        Set dido = didoEnum.GetItem(i)
        Select Case dido.GetOfs
            Case DIJOFS_X
                AxisPresent(1) = True
            Case DIJOFS_Y
                AxisPresent(2) = True
' 以下同様。
.
.
.
        End Select
    Next
End Sub

次に、アプリケーションは、以前に作成されたイベント ハンドルをデバイスに渡す。これにより、入力イベントが発生すると、通知はフォームに送信される。

Call diDev.SetEventNotification(EventHandle)

次項 : ステップ 3 : ジョイスティック プロパティの設定


ステップ 3 : ジョイスティック プロパティの設定

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

プロパティの変更は、DirectInputDevice.SetProperty メソッドを使って行う。これはデバイスの確立後、かつデバイスの取得前に行わなければならない。

デバイスが返す軸の範囲の値は軸ごとに異なっているので、すべてのデバイスに適用される範囲を設定するのが好ましい。Joystick サンプルでは、すべての軸の値を 0 ～ 10,000 の範囲に収めるよう要求している。

Dim DiProp_Range As DIPROPRANGE

With DiProp_Range
    .lHow = DIPH_DEVICE  ' すべての軸に対して設定する。
    .lSize = Len(DiProp_Range)
    .lMin = 0
    .lMax = 10000
End With
diDev.SetProperty "DIPROP_RANGE", DiProp_Range

lSize メンバ内の DIPROPRANGE 型の長さを指定しなければならない。なぜなら、このメソッドはさまざまな型のパラメータを処理できるので、割り当てるメモリの量を知る必要があるからである。C++ のプログラミングを熟知している場合は、Len(DIPROPRANGE) が有効でないことにも注意すること。これはゼロを返すからである。

Joystick サンプルでは、ジョイスティックの無効ゾーンと飽和ゾーンも設定する。この場合、スロットルや方向舵などの軸にこれらの値を設定するのは望ましくない。したがって、プロパティの変更はデータ形式内のオフセットで識別されるデバイス オブジェクトに適用されることを示すように、プロパティ タイプの lHow メンバが設定され、lObj メンバにはそのオフセット値が設定される。

Dim DiProp_Dead As DIPROPLONG

With DiProp_Dead
    .lData = 1000
    .lObj = DIJOFS_X
    .lSize = Len(DiProp_Dead)
    .lHow = DIPH_BYOFFSET
' x 軸の設定。
    .lObj = DIJOFS_X
    diDev.SetProperty "DIPROP_DEADZONE", DiProp_Dead
' y 軸の設定。
    .lObj = DIJOFS_Y
    diDev.SetProperty "DIPROP_DEADZONE", DiProp_Dead
End With

lData の値は、無効ゾーンとして設定する移動範囲の割合であり、10,000 までの値で表される。サンプルで使用される 1000 という値は、x 軸と y 軸の移動範囲のうち中心の 10% が 5000 として報告されることを指定している。5000 は、前のステップで設定した範囲の中心を表す値である。

注 : 無効ゾーンと飽和値は、デバイスにより報告される値の範囲にかかわらず、常に 10,000 までの値で表される。

デバイスの飽和ゾーンも同様に設定する。この場合、lData は飽和ゾーンの外側にある最大の移動範囲の割合を表すので、9500 である。つまり、ジョイスティックにより返される未加工の値の上位および下位 5% は、デバイスに設定された最小値または最大値として報告される (この場合、0 または 10,000)。

次項 : ステップ 4 : ジョイスティックからの直接データの取得


ステップ 4 : ジョイスティックからの直接データの取得

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

この時点で、必要なプロパティは設定されており、デバイスは取得可能で、データはジョイスティックから収集可能である。Joystick サンプルでは、プロパティを設定した後のループ内でデバイスをポーリングしている。実際のマルチメディア アプリケーションでは、ポーリングはメインのゲーム ループやレンダリング ループ内で行われる。

diDev.Acquire

While DoEvents
    diDev.Poll
Wend

サンプル アプリケーションは、実際にデバイスをポーリングするたびに直接データを取得しているわけではない。不要な画面更新をなくすために、ポーリングは通知に基づいて行われる。割り込みを生成しないデバイスにより通知が発行されていることを保証する唯一の方法は、Poll を呼び出すことである。ゲーム デバイス (HID など) によってはポーリングは必要ではないが、DirectInputDevice.Poll を余分に呼び出すことは、Poll を呼び出す前にデバイスのフラグをチェックするのと同様に効率的である。

通知は DirectXEvent.DXCallback メソッドの実装内で通常どおり処理される。このプロシージャが呼び出されるたびに、アプリケーションは何らかのジョイスティック イベントが発生したことを認識する。この時点で、DirectInputDevice.GetDeviceData を呼び出して、待機中の軸の変化やボタン イベントを取得することもできる。ただし、ゲーム コントローラでは、デバイス全体の状態を取得することが普通なので、サンプルでは DirectInputDevice.GetDeviceStateJoystick を使用している。

Dim js As DIJOYSTATE

diDev.GetDeviceStateJoystick js

ここで、DIJOYSTATE 型の値は、デバイス オブジェクトの状態に関してアプリケーションが知る必要のあるすべての情報を示している。アプリケーションは「ステップ 2 : ジョイスティック能力の取得」で、どのボタン、軸、視点コントローラが実際に存在するかがわかっているので、型のどのメンバを無視するかも認識している。


チュートリアル 4 : フォース フィードバックの使用

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、フォース フィードバック デバイスが存在するかどうかをテストする方法、エフェクトを生成して再生する方法、およびエフェクトの再生中にパラメータを変更する方法を示す。

このチュートリアルでは、タスクを以下の手順に分割している。

  • ステップ 1 : フォース フィードバック デバイスの初期化
  • ステップ 2 : デバイス プロパティの設定
  • ステップ 3 : エフェクトの生成
  • ステップ 4 : エフェクトの変更


ステップ 1 : フォース フィードバック デバイスの初期化

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

フォース フィードバックを実装するには、まず、適切なデバイスが使用可能かどうかを調べ、使用可能であれば、そのデバイスに DirectInputDevice オブジェクトを作成しなければならない。ここで、x 軸と y 軸でエフェクトを再生できるデバイスが必要なアプリケーションを考えてみる。

次のサンプルは、DirectInput オブジェクトを作成し、それを使って DirectInputEnumDevices オブジェクト内の利用可能なデバイスを列挙することから開始する。すべてのフォース フィードバック デバイスは DIDEVTYPE_JOYSTICK 型なので、列挙対象はこの型のアタッチ済みデバイスに制限されている。

' dx は初期化済みのグローバル DirectX オブジェクト。
' di は、グローバル DirectInput オブジェクト。

Dim diDevInst As DirectInputDeviceInstance
Dim diDevObjEnum As DirectInputEnumDeviceObjects
Dim devobj As DirectInputDeviceObjectInstance

Dim devcaps As DIDEVCAPS
Dim ForceX As Boolean, ForceY As Boolean
Dim FoundForce As Boolean
Dim efftype As Long
Dim strObjGuid As String

Dim i As Integer, iAxes As Integer

Set di = dx.DirectInputCreate
Set diEnumDev = di.GetDIEnumDevices(DIDEVTYPE_JOYSTICK, _
        DIEDFL_ATTACHEDONLY)

ここで、サンプルはフォース フィードバック能力を持つデバイスを見つけるまで、使用可能なデバイスの調査を反復する。

For i = 1 To diEnumDev.GetCount
  Set diDevInst = diEnumDev.GetItem(i)
  Set didev = di.CreateDevice(diDevInst.GetGuidInstance)
  Call didev.GetCapabilities(devcaps)
  If devcaps.lFlags And DIDC_FORCEFEEDBACK Then

ここで、サンプルは DirectInputEnumDeviceObjects コレクションに含まれるデバイス上の軸を列挙する。

    Set diDevObjEnum = didev.GetDeviceObjectsEnum(DIDFT_AXIS)
    ForceX = False
    ForceY = False

次に、軸の中から x 軸と y 軸を探し、それらの軸がフォース フィードバック エフェクトをサポートするかどうかを調べる。

    For iAxes = 1 To diDevObjEnum.GetCount
      Set devobj = diDevObjEnum.GetItem(iAxes)
      strObjGuid = devobj.GetGuidType
      If strObjGuid = "GUID_XAxis" Then
        If devobj.GetFlags And DIDOI_FFACTUATOR Then
          ForceX = True
        End If
      ElseIf strObjGuid = "GUID_YAxis" Then
        If devobj.GetFlags And DIDOI_FFACTUATOR Then
          ForceY = True
        End If
      End If
    Next iAxes
    FoundForce = ForceX And ForceY
    if FoundForce Then Exit For
  End If
Next i

If Not FoundForce Then
  MsgBox "Two force feedback axes required."
End

次項 : ステップ 2 : デバイス プロパティの設定


ステップ 2 : デバイス プロパティの設定

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

適切なフォース フィードバック デバイスが見つかった場合、能力をチェックするために前のステップで作成された DirectInputDevice オブジェクトが残っている。オブジェクトには、データ形式や協調レベルの設定、および入力用の範囲プロパティの設定などの初期化が必要である。この処理については、「チュートリアル 3 : ジョイスティックの使用」を参照すること。協調レベルには DISCL_EXCLUSIVE を含めなければならない。デバイスへのバックグラウンド アクセス権を持つ必要はないが、DISCL_BACKGROUND フラグを使うと、コード ウィンドウに切り替えるときに取得を失うことがなくなるので、デバッグ作業が容易になる。

Call didev.SetCommonDataFormat(DIFORMAT_JOYSTICK2)
Call didev.SetCooperativeLevel(Me.hWnd, _
        DISCL_BACKGROUND Or DISCL_EXCLUSIVE)
' 範囲プロパティの設定などを行う。
.
.
.

フォース フィードバックの場合、デフォルトのスプリング アクションが生成するエフェクトに干渉しないように、デバイスの自動センタリング プロパティを無効にしたい場合もある。

Dim prop As DIPROPLONG
prop.lData = 0
prop.lHow = DIPH_DEVICE
prop.lObj = 0
prop.lSize = Len(prop)
Call didev.SetProperty("DIPROP_AUTOCENTER", prop)

didev.Acquire

次項 : ステップ 3 : エフェクトの生成


ステップ 3 : エフェクトの生成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

アプリケーションで、ジョイスティックに制御される移動可能オブジェクト (たとえば、鉄球) に対して静止オブジェクト (たとえば、磁石) が引き付ける力をシミュレートすることを考えてみよう。このシミュレーションの最初に、鉄球は磁石の真南にあり、引く最大距離の半分の位置にある。

コンスタント フォースにより磁石の引き付ける力をシミュレートする。まず、このフォースを表す DIEFFECT 型を設定する。

Dim EffectInfo as DIEFFECT
With EffectInfo
  .constantForce.lMagnitude = 5000
  .lDuration = -1       ' 無限。
  .x = 18000
  .lGain = 10000        ' 全マグニチュードで再生する。
  .lTriggerButton = -1  ' トリガ ボタンなし。
End With

DIEFFECT のほかのすべてのメンバは、コンスタント フォースに無関係であるか、またはゼロとして有効である。

次にエフェクトを生成する。

Dim di_effect As DirectInputEffect
Set di_effect = didev.CreateEffect("GUID_ConstantForce", EffectInfo)

このときにデバイスが取得状態にあれば、エフェクトが自動的にダウンロードされる。取得状態になければ、エフェクトは開始時にダウンロードされる。

di_effect.Start(1, 0)

このエフェクトは無限の継続時間を持っているので、エフェクトを一度だけ繰り返す場合、フラグは不要である。

次項 : ステップ 4 : エフェクトの変更


ステップ 4 : エフェクトの変更

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ チュートリアル」を参照すること。

[Visual Basic]

ユーザーが鉄球を回転させるのに応じて、アプリケーションはエフェクトの方向とマグニチュードを調整する。ただし、最初に、そのデバイスでエフェクトを停止して再開せずにエフェクトの方向を変更できるかどうかを調べる必要がある。DirectInput は必要に応じてエフェクトを停止して再開するが、動作の連続性を保ちながら、アプリケーションの動作を変更したい場合もある。

エフェクトの能力を調べるために、サポートされるエフェクトを列挙し、必要な特定のエフェクトを探す必要がある。

Dim diEnumEffects As DirectInputEnumEffects
Dim params As Long
Dim i As Long

' コンスタント フォースを列挙する。

Set diEnumEffects = didev.GetEffectsEnum(DIEFT_CONSTANTFORCE)

For i = 1 To diEnumEffects.GetCount

  ' 標準のコンスタント フォースを探す。ほかの処理を行ってもよい。

  If diEnumEffects.GetEffectGuid(i) = "GUID_ConstantForce" Then
    params = diEnumEffects.GetDynamicParams(i)
    Exit For
  End If

Next i

If Not (params And DIEP_DIRECTION) Then
  ' 方向を動的に変えることはできない。変更対象のポイントを制限するなど、
  ' 補正のための措置をとる。
End If

同様に、エフェクトのマグニチュードを動的に変更できるかどうかを知るには、次のチェックを行う。

if Not (params And DIEP_TYPESPECIFICPARAMS)
   ' タイプ固有パラメータを動的には変更できない。
End If

次に、デバイスに入力の有無をポーリングして鉄球を移動するたびにエフェクトを変更してみよう。ここで、CurrentMag に新しいマグニチュード、および CurrentBearing に新しい方向 (度単位) を計算したとする。必要な変更を加えるために、DIEFFECT の関連するメンバだけを初期化する必要がある。

EffectInfo.constantForce.lMagnitude = CurrentMag
EffectInfo.x = CurrentBearing * 100

ここで、どのメンバに有効なデータが含まれているかを示すフラグと共に、DIEFFECT 型を DirectInputEffect.SetParameters に渡す。

di_effect.SetParameters(EffectInfo, _
        DIEP_DIRECTION Or DIEP_TYPESPECIFICPARAMS)

DIEP_TYPESPECIFICPARAMS フラグは、そのエフェクトのタイプに関連する情報を含むメンバが有効であることを示す。コンスタント フォースの場合、これは constantForce メンバを意味する。


DirectInput リファレンス

ここでは、C/C++ および Microsoft® Visual Basic® 開発システムで Microsoft® DirectInput® が提供する API (Application Programming Interface) 要素のリファレンス情報を記述する。リファレンス情報は以下の言語別に構成される。

  • DirectInput C/C++ リファレンス
  • DirectInput Visual Basic リファレンス


DirectInput C/C++ リファレンス

DirectInput C/C++ API のリファレンス情報は、次のように分類される。

  • インターフェイス
  • 関数
  • コールバック関数
  • マクロ
  • 構造体
  • デバイス定数
  • 戻り値


インターフェイス

ここでは、以下の DirectInput インターフェイスのメソッドに関するリファレンスを提供する。

  • IDirectInput7
  • IDirectInputDevice7
  • IDirectInputEffect

注 : すべての DirectInput メソッドには、定義されている言語に応じて、C または C++ 構文に展開するマクロが用意されている。これらのマクロは Dinput.h ヘッダー ファイルにあり、独立して記述されているわけではない。


IDirectInput7

アプリケーションは、IDirectInput7 インターフェイスのメソッドを使用して、DirectInput デバイスの列挙、作成、ステータスの受信、DirectInput オブジェクトの初期化、およびコントロール パネルのインスタンスの起動を行う。

IDirectInput7 インターフェイスは DirectInputCreateEx 関数を使用して取得する。

IDirectInput7 は、これまでの DirectX のバージョンで使用されていた IDirectInput に取って代わるインターフェイスである。

IDirectInput7 インターフェイスのメソッドは、以下のグループにまとめることができる。

デバイス管理 | CreateDevice
 | CreateDeviceEx
 | EnumDevices
 | FindDevice
 | GetDeviceStatus
その他 | Initialize
 | RunControlPanel

すべての COM インターフェイスと同様に、IDirectInput インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUT 型は IDirectInput7 インターフェイスへのポインタとして定義される。

typedef struct IDirectInput7    *LPDIRECTINPUT7;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInput7::CreateDevice

IDirectInput7::CreateDevice メソッドは、指定の GUID に基づきデバイスのインスタンスを作成して初期化し、IDirectInputDevice インターフェイスを取得する。これは、IDirectInput7::CreateDeviceEx に取って代わるメソッドである。

HRESULT CreateDevice(
  REFGUID rguid,
  LPDIRECTINPUTDEVICE *lplpDirectInputDevice,
  LPUNKNOWN pUnkOuter
);

パラメータ

rguid
C++ の場合、目的の入力デバイスのインスタンス GUID に対する参照値。C の場合、この GUID のアドレス (「注意」を参照)。この GUID は、IDirectInput7::EnumDevices メソッドを介して取得するか、または、次の事前定義された GUID の 1 つを使用する。
GUID_SysKeyboard
デフォルトのシステム キーボード。
GUID_SysMouse
デフォルトのシステム マウス。

この GUID 値を有効にするには、アプリケーションは、ソース ファイルの先頭で、ほかのすべてのプリプロセッサ ディレクティブに先立ち、INITGUID を定義するか、あるいは DXGUID.LIB にリンクしなければならない。

lplpDirectInputDevice
成功時に IDirectInputDevice インターフェイスのポインタを取得する変数のアドレス。
pUnkOuter
COM 集合化に対する制御オブジェクトの IUnknown インターフェイスのアドレス。インターフェイスが集合化されない場合には NULL。普通、呼び出し側は NULL を渡す。

戻り値

成功すれば DI_OK を返す。

失敗すれば次の戻り値のいずれかを返す。

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_NOTINITIALIZED
DIERR_OUTOFMEMORY

注意

C++ では、rguid パラメータは参照値として渡さなければならない。C では参照値として渡すことができないので、アドレスとして渡さなければならない。次は、C++ での呼び出し例である。

lpdi->CreateDevice(GUID_SysKeyboard, &pdev, NULL);

次は、C での同じ呼び出し例である。

lpdi->lpVtbl->CreateDevice(lpdi, &GUID_SysKeyboard, &pdev, NULL);

punkOuter = NULL を指定してこのメソッドを呼び出すことは、CoCreateInstance(&CLSID_DirectInputDevice, NULL, CLSCTX_INPROC_SERVER, riid, lplpDirectInputDevice) を使用してオブジェクトを作成した後、Initialize を使用して初期化することと同等である。

punkOuter != NULL を指定してこのメソッドを呼び出すことは、CoCreateInstance(&CLSID_DirectInputDevice, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInputDevice) を使用してオブジェクトを作成することと同等である。集合化したオブジェクトは手動で初期化しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInput7::CreateDeviceEx

IDirectInput7::CreateDeviceEx メソッドは、指定の GUID に基づきデバイスのインスタンスを作成して初期化し、IDirectInputDevice、IDirectInputDevice2、または IDirectInputDevice7 インターフェイスを取得する。

HRESULT CreateDeviceEx(
  REFGUID rguid,
  REFIID riid,
  LPVOID *pvOut,
  LPUNKNOWN pUnkOuter
);

パラメータ

rguid
C++ の場合、目的の入力デバイスのインスタンス GUID に対する参照値。C の場合、この GUID のアドレス (「注意」を参照)。この GUID は、IDirectInput7::EnumDevices メソッドを介して取得するか、または、次の事前定義された GUID の 1 つを使用する。
GUID_SysKeyboard
デフォルトのシステム キーボード。
GUID_SysMouse
デフォルトのシステム マウス。

この GUID 値を有効にするには、アプリケーションは、ソース ファイルの先頭で、ほかのすべてのプリプロセッサ ディレクティブに先立ち、INITGUID を定義するか、あるいは DXGUID.LIB にリンクしなければならない。

riid
目的のインターフェイスの一意な識別子。現在受け付ける値は、IID_IDirectInputDevice、IID_IDirectInputDevice2、および IID_IDirectInputDevice7 である。
pvOut
成功時にインターフェイス ポインタを取得する変数のアドレス。
pUnkOuter
COM 集合化に対する制御オブジェクトの IUnknown インターフェイスのアドレス。インターフェイスが集合化されていない場合には NULL。普通、呼び出し側は NULL を渡す。

戻り値

成功すれば DI_OK を返す。

失敗すれば次の戻り値のいずれかを返す。

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_NOTINITIALIZED
DIERR_OUTOFMEMORY

注意

C++ では、rguid パラメータは参照値として渡さなければならない。C では参照値として渡すことができないので、アドレスとして渡さなければならない。次は、C++ での呼び出し例である。

lpdi->CreateDevice(GUID_SysKeyboard, &pdev, NULL);

次は、C での同じ呼び出し例である。

lpdi->lpVtbl->CreateDevice(lpdi, &GUID_SysKeyboard, &pdev, NULL);

多くの場合、アプリケーションは、riid パラメータとして IID_IDirectInputDevice7 を渡し、IDirectInputDevice7 インターフェイスを取得することになる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInput7::EnumDevices

IDirectInput7::EnumDevice メソッドは、現在コンピュータにアタッチ されているか、アタッチ可能なデバイスを列挙する。

HRESULT EnumDevices(
  DWORD dwDevType,
  LPDIENUMCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

パラメータ

dwDevType
デバイス タイプのフィルタ。このパラメータがゼロなら、すべてのデバイス タイプが列挙される。ゼロでなければ、列挙すべきデバイス タイプを示す DIDEVTYPE_* 値になる (「DIDEVICEINSTANCE」を参照)。
lpCallback
各 DirectInput デバイスの記述を使って呼び出されるコールバック関数のアドレス。
pvRef
アプリケーション定義の 32 ビット値。列挙コールバック関数が呼ばれるたびに渡される。
dwFlags
列挙の範囲を指定するフラグ値。次のフラグを指定する。
DIEDFL_ALLDEVICES
すべてのインストール済みデバイスが列挙される。これがデフォルト モードである。
DIEDFL_ATTACHEDONLY
アタッチかつインストール済みデバイスだけ。
DIEDFL_FORCEFEEDBACK
フォース フィードバックをサポートするデバイスだけ。
DIEDFL_INCLUDEALIASES
ほかのデバイスのエイリアスであるデバイスを含む。
DIEDFL_INCLUDEPHANTOMS
仮想デバイス (プレースホルダ) を含む。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

すべてのインストール済みデバイスは、たとえそれが現存していなくても列挙可能である。たとえば、操縦桿は、システムにインストールするが、当面コンピュータに接続しないでおくこともできる。dwFlags パラメータを設定して、アタッチされているデバイスだけを列挙するか、またはインストール済みのすべてのデバイスを列挙するかを指示する。DIEDFL_ATTACHEDONLY フラグが存在しない場合は、インストール済みの全デバイスが列挙される。

選別したいデバイス タイプを dwDevType フィルタとして渡して、そのタイプのデバイスだけを列挙することができる。

LpCallback パラメータには、DIEnumDevicesCallback として表記されている種類のコールバック関数のアドレスを指定する。DirectInput は、列挙されているデバイスごとに、この関数を呼び出す。このコールバック関数の中では、デバイス タイプと登録名、および製品 GUID と登録名が、各デバイスに対して与えられる。単一の入力デバイスが、複数の DirectInput デバイス タイプとして機能することができる場合は、サポートする各デバイス タイプごとに返される。たとえば、組み込みマウス付きのキーボードは、1 つのキーボードとして、かつ、1 つのマウスとして列挙される。ただし、製品 GUID は各デバイスに対して同じである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInput7::FindDevice

IDirectInput7::FindDeviceStatus メソッドは、システムに新たにアタッチされたデバイスのインスタンス GUID を取得する。このメソッドは、Win32 デバイス管理通知に応答して呼び出される。

HRESULT FindDevice(
  REFGUID rguidClass,
  LPCTSTR ptszName,
  LPGUID pguidInstance
);

パラメータ

rguidClass
アプリケーションが検索するデバイス クラスの一意な識別子。アプリケーションは、デバイス到着通知からクラス GUID を取得する (Platform SDK の DBT_DEVICEARRIVAL イベントのトピックを参照)。
ptszName
デバイスの名前。アプリケーションは、デバイス到着通知から名前を取得する。
pguidInstance
デバイスが見つかった場合にデバイスのインスタンス GUID を受け取る変数のアドレス。この値は IDirectInput7::CreateDeviceEx に渡すことができる。

戻り値

成功すれば DI_OK を返す。

失敗すれば DIERR_DEVICENOTREG を返す。GUID と名前が、DirectInput に登録されているデバイス クラスに対応しない場合は、失敗となる。たとえば、入力デバイスではなく、記憶デバイスを参照する場合などである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

デバイス変更の認識


IDirectInput7::GetDeviceStatus

Platform SDK: DirectX

IDirectIIDirectInput::GetDeviceStatus

IDirectInput7::GetDeviceStatus メソッドは、指定デバイスのステータスを取得する。

HRESULT GetDeviceStatus(
  REFGUID rguidInstance
);

パラメータ

rguidInstance
ステータスをチェックするデバイスのインスタンス識別子。

戻り値

メソッドが成功し、デバイスがシステムにアタッチされている場合は DI_OK を返し、そうでなければ DI NOTATTACHED を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_GENERIC
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInput7::Initialize

IDirectInput7::Initialize メソッドは、DirectInput オブジェクトを初期化する。DirectInputCreate 関数と DirectInputCreateEx 関数は、作成した DirectInput オブジェクトを自動的に初期化する。アプリケーションは、通常、このメソッドを呼び出す必要はない。

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion
);

パラメータ

hinst
DirectInput オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドル。DirectInput は、この値を使用して、アプリケーションまたは DLL が、オブジェクト作成の資格を認められているかどうかを判断し、下位互換性のためにとるべき特別な動作を確定する。

DLL が親のアプリケーションのハンドルを渡すと、エラーとなる。たとえば、Web ページに埋め込まれていて DirectInput を使用する ActiveX コントロールは、Web ブラウザのハンドルではなく、それ自身のインスタンスのハンドルを渡さなければならない。これにより、DirectInput がそのコントロールを認識し、必要と思われる特別な動作をすべて有効にすることが確実になる。

dwVersion
アプリケーションの設計対象である DirectInput のバージョン番号。この値は通常、DIRECTINPUT_VERSION である。以前のバージョン番号を渡すと、DirectInput がそのバージョンをエミュレートすることになる。詳細は、「前のバージョンの DirectInput の設計」を参照すること。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_BETADIRECTINPUTVERSION
DIERR_OLDDIRECTINPUTVERSION

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInput7::RunControlPanel

Platform SDK: DirectX

IDirectInputDevice::RunControlPanel

IDirectInput7::RunControlPanel メソッドは、ユーザーが新しい入力デバイスをインストールしたり、構成を変更したりできるように、Windows コントロール パネルを実行する。

HRESULT RunControlPanel(
  HWND hwndOwner,
  DWORD dwFlags
);

パラメータ

hwndOwner
これ以降のユーザー インターフェイスの親ウィンドウとして使用するウィンドウのハンドル。このパラメータが NULL ならば、親ウィンドウは使用されない。
dwFlags
現在は未使用なので、ゼロに設定しなければならない。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::RunControlPanel


IDirectInputDevice7

アプリケーションは、IDirectInputDevice7 インターフェイスのメソッドを使用して、DirectInput デバイスのアクセス権の取得と解放、デバイス プロパティと情報の管理、動作の設定、初期化の実行、フォース フィードバック エフェクトの生成と再生、およびデバイスのコントロール パネルの起動を行う。

IDirectInput7 インターフェイスは IDirectInput7::CreateDeviceEx メソッドを使用して取得する。例については、「DirectInput デバイスの作成」を参照すること。

IDirectInputDevice7 は、これまでのバージョンの DirectX で使用されていた IDirectInputDevice および IDirectInputDevice2 に取って代わるインターフェイスである。

IDirectInputDevice7 インターフェイスのメソッドは、以下のグループにまとめることができる。

入力デバイスのアクセス | Acquire
 | Unacquire
デバイス情報 | GetCapabilities
 | GetDeviceData
 | GetDeviceInfo
 | GetDeviceState
 | Poll
 | SetDataFormat
 | SetEventNotification
デバイス オブジェクト | EnumObjects
 | GetObjectInfo
デバイス プロパティ | GetProperty
 | SetCooperativeLevel
 | SetProperty
フォース フィードバック | CreateEffect
 | EnumCreatedEffectObjects
 | EnumEffects
 | EnumEffectsInFile
 | Escape
 | GetEffectInfo
 | GetForceFeedbackState
 | SendForceFeedbackCommand
 | WriteEffectToFile
その他 | Initialize
 | RunControlPanel
 | SendDeviceData

すべての COM インターフェイスと同様に、IDirectInputDevice7 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUTDEVICE7 型は IDirectInputDevice インターフェイスへのポインタとして定義される。

typedef struct IDirectInputDevice7    *LPDIRECTINPUTDEVICE7;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7

Built on 2000年4月13日


IDirectInputDevice7::Acquire

IDirectInputDevice7::Acquire メソッドは、入力デバイスへのアクセス権を取得する。

HRESULT Acquire();

パラメータ

なし。

戻り値

成功すれば DI_OK または S_FALSE、

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OTHERAPPHASPRIO

S_FALSE が返された場合、デバイスは取得済みである。

注意

デバイス取得の前に IDirectInputDevice7::SetDataFormat メソッドを使用して、データ形式を設定しなければならない。

デバイスに対して IDirectInputDevice7::GetDeviceState または IDirectInputDevice7::GetDeviceData メソッドを呼び出す前に、そのデバイスを取得しておかなければならない。

デバイス取得では、参照カウントを使用しない。このため、アプリケーションが IDirectInputDevice7::Acquire メソッドを 2 回呼び出し、その後 IDirectInputDevice7::Unacquire メソッドを 1 回呼び出すと、デバイスは解放される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::CreateEffect

Platform SDK: DirectX

IDirectInputDevice7::CreateEffect

IDirectInputDevice7::CreateEffect メソッドは、エフェクトの GUID によって識別されるエフェクトのインスタンスを作成、初期化する。

HRESULT CreateEffect(
  REFGUID rguid,
  LPCDIEFFECT lpeff,
  LPDIRECTINPUTEFFECT * ppdeff,
  LPUNKNOWN punkOuter
);

パラメータ

rguid
作成するエフェクトの識別情報。これは事前定義されたエフェクト GUID でも、あるいは IDirectInputDevice7::EnumEffects から得られる GUID でもよい。

以下のエフェクト GUID が定義されている。

  • GUID_ConstantForce
  • GUID_RampForce
  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown
  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction
  • GUID_CustomForce
lpeff
作成されたエフェクトにパラメータを与える DIEFFECT 構造体。このパラメータは、オプションである。NULL の場合、エフェクト オブジェクトは、パラメータなしで作成される。次に、アプリケーションは、IDirectInputEffect::SetParameters メソッドを呼び出し、エフェクトをダウンロードする前にエフェクトのパラメータを設定しなければならない。
ppdeff
成功時に IDirectInputEffect インターフェイスへのポインタを受け取る変数のアドレス。
punkOuter
COM 集合化に対する制御オブジェクトの IUnknown インターフェイスのアドレス。インターフェイスが集合化されない場合、値は NULL である。普通、呼び出し側は NULL を渡す。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_DEVICENOTREG
DIERR_DEVICEFULL
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

戻り値が S_OK である場合、エフェクトは作成済みで、エフェクトのパラメータは更新済みであるが、エフェクトをダウンロードする必要がなかったことを示す。エフェクトをダウンロードするには、デバイスを排他モードで取得しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::EnumCreatedEffectObjec

Platform SDK: DirectX

IDirectInputDevice7::EnumCreatedEffectObjects

IDirectInputDevice7::EnumCreatedEffectObjects メソッドは、このデバイスに現在作成されているすべてのエフェクトを列挙する。IDirectInputDevice7::CreateEffect によって作成されたエフェクトが列挙される。

HRESULT EnumCreatedEffectObjects(
  LPDIENUMCREATEDEFFECTOBJECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD fl
);

パラメータ

lpCallback
アプリケーション定義のコールバック関数のアドレス。DirectInput は、プロトタイプ関数 DIEnumCreatedEffectObjectsCallback を提供している。
pvRef
コールバック用のリファレンス データ (コンテキスト)
fl
フラグは現在未定義である。このパラメータは、ゼロでなければならない。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

列挙の進行中に、エフェクトを作成または廃棄すると、その結果は予測できない。しかし、コールバック関数は、渡されるエフェクトを確実に解放する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::EnumEffects

Platform SDK: DirectX

IDirectInputDevice7::EnumEffects

IDirectInputDevice7::EnumEffects メソッドは、デバイス上のフォース フィードバック システムがサポートするエフェクトをすべて列挙する。列挙される GUID は、デバイス メーカー独自のエフェクトに加えて、事前定義されたエフェクトも表すことができる。

HRESULT EnumEffects(
  LPDIENUMEFFECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwEffType
);

パラメータ

lpCallback
アプリケーション定義のコールバック関数のアドレス。この関数の宣言は、DIEnumEffectsCallback プロトタイプの宣言と同様に行わなければならない。
pvRef
コールバック関数に渡すアプリケーション定義の 32 ビットの値。このパラメータには、任意の 32 ビットの値を使用できる。ただし、便宜上、LPVOID と宣言されている。
dwEffType
エフェクト タイプのフィルタ。DIEFT_* 値の 1 つを使用して列挙するエフェクト タイプを指示するか、あるいは DIEFT_ALL を使用してすべてのエフェクト タイプを列挙する。これらの値のリストについては、「DIEFFECTINFO」を参照すること。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

コールバック関数が列挙を途中で停止すると、その列挙は成功したと見なされる。

注意

アプリケーションは、DIEFFECTINFO 構造体の dwEffType メンバを使用して、エフェクトのタイプ、エフェクトがサポートしているエンベロープと条件パラメータが何であるか、などエフェクトの一般的情報を取得できる。

エフェクトを最大限に利用するには、デバイス メーカーに問い合わせて、エフェクトの意味内容とそのエフェクト固有のパラメータに関する情報を入手しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::EnumEffects

Platform SDK: DirectX

IDirectInputDevice7::EnumEffectsInFile

IDirectInputDevice7::EnumEffectsInFile メソッドは、Force Editor ユーティリティや、同じファイル形式を使用する別のアプリケーションで、作成されたファイルに含まれるすべてのエフェクトを列挙する。

HRESULT EnumEffectsInFile(
  LPCSTR lpszFileName,
  LPENUMEFFECTSINFILECALLBACK pec,
  LPVOID pvRef,
  DWORD dwFlags
);

パラメータ

lpszFileName
Name of the RIFF file.
pec
アプリケーション定義のコールバック関数のアドレス。この関数の宣言は、DIEnumEffectsInFileCallback プロトタイプの宣言と同様に行わなければならない。
pvRef
コールバック関数に渡すアプリケーション定義の 32 ビットの値。このパラメータは、32 ビットの任意の値を取ることができる。
dwFlags
DIFEF_DEFAULT (= 0) あるいは以下の値の一方または両方を使用できる。
DIFEF_INCLUDENONSTANDARD
DirectInput で定義されていないエフェクト タイプを含める。
DIFEF_MODIFYIFNEEDED
現在のデバイスで再生できるように、作成したエフェクトを必要に応じて変更するように DirectInput に対して指示する。たとえば、2 つの軸に対して作成されたエフェクトは、デフォルトでは単一軸デバイスでは再生されない。このフラグを設定すると、単一軸でそのようなエフェクトが再生される。パラメータは、DIEFFECT 構造体内で変更される。この構造体は、コールバックに渡される DIFILEEFFECT 構造体の lpDiEffect メンバにより参照される。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

コールバック関数が列挙を途中で停止すると、その列挙は成功したと見なされる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::WriteEffectToFile、「ファイルからのエフェクトの読み込み」


IDirectInputDevice7::EnumObjects

IDirectInputDevice7::EnumObjects メソッドは、デバイス上で使用可能な入力ソース (軸、ボタンなど) を列挙する。

HRESULT EnumObjects(
  LPDIENUMDEVICEOBJECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

パラメータ

lpCallback
DirectInputDevice オブジェクトのコールバック関数のアドレス。DirectInput は、この関数のプロトタイプを DIEnumDeviceObjectsCallback として提供している。
pvRef
コールバック用のリファレンス データ (コンテキスト)
dwFlags
列挙するオブジェクトのタイプを指定するフラグ。次のフラグは、列挙対象を指定されたタイプのオブジェクトに制限する。
DIDFT_ABSAXIS
絶対軸。
DIDFT_ALL
すべてのオブジェクト。
DIDFT_AXIS
絶対軸、相対軸のどちらか。
DIDFT_BUTTON
プッシュ ボタンまたはトグル ボタン。
DIDFT_COLLECTION
HID リンク コレクション。HID リンク コレクションは、独自のデータを生成しない。
DIDFT_ENUMCOLLECTION(n)
HID リンク コレクション番号 n に属するオブジェクト。
DIDFT_FFACTUATOR
フォース フィードバック アクチュエータを含むオブジェクト。すなわち、フォースをこのオブジェクトに適用することができる。
DIDFT_FFEFFECTTRIGGER
フォース フィードバック エフェクトをトリガするために使用できるオブジェクト。
DIDFT_NOCOLLECTION
HID リンク コレクションに属さないオブジェクト。すなわち、DIDEVICEOBJECTINSTANCE 構造体の wCollectionNumber メンバが 0 であるオブジェクト。
DIDFT_NODATA
データを生成しないオブジェクト。
DIDFT_OUTPUT
IDirectInputDevice7::SendDeviceData メソッドを利用することによって、データを送ることができるオブジェクト。
DIDFT_POV
視点コントローラ。
DIDFT_PSHBUTTON
プッシュ ボタン。プッシュ ボタンは、ユーザーが押したときにダウン、ユーザーが離したときにアップと報告される。
DIDFT_RELAXIS
相対軸。
DIDFT_TGLBUTTON
トグル ボタン。トグル ボタンは、ユーザーが押したときにダウンと報告され、ユーザーが再度そのボタンを押すまでその状態に留まる。
DIDFT_VENDORDEFINED
メーカーにより定義されるタイプのオブジェクト。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

dwFlags パラメータに DIDFT_FFACTUATOR および DIDFT_FFEFFECTTRIGGER フラグを指定すると、列挙対象は、この 2 つのフラグで定義されているすべての基準を満たすオブジェクトに限定される。ほかのすべてのフラグの場合は、このカテゴリに指定したフラグで定義されている基準を満たすオブジェクトが列挙される。たとえば、(DIDFT_FFACTUATOR | DIDFT_FFEFFECTTRIGGER) を指定すると、列挙対象をフォース フィードバック トリガ オブジェクトに限定する。これに対して、(DIDFT_FFEFFECTRIGGER | DIDFT_TGLBUTTON | DIDFT_PSHBUTTON) を指定すると、エフェクト トリガとして利用できる任意のボタンが列挙される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::Escape

Platform SDK: DirectX

IDirectInputDevice7::Escape

IDirectInputDevice7::Escape メソッドは、ハードウェア固有のコマンドをフォース フィードバック ドライバに送信する。

HRESULT Escape(
  LPDIEFFESCAPE pesc
);

パラメータ

pesc
送信するコマンドを表す DIEFFESCAPE 構造体。成功すると、実際に使用する出力バッファのバイト数が cbOutBuffer メンバに格納される。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_DEVICEFULL
DIERR_NOTINITIALIZED

ほかのデバイス固有エラー コードを返すこともできる。ハードウェア メーカーから詳細情報を入手すること。

注意

各ドライバは、異なるエスケープ シーケンスを実装しているので、正しいドライバと通信しているかどうかは、アプリケーション自体が確認しなければならない。これは、DIDEVICEINSTANCE 構造体の guidFFDriver メンバと、アプリケーションが期待している値を比較することにより確認できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice7::GetCapabilities

IDirectInputDevice7::GetCapabilities メソッドは、DirectInputDevice オブジェクトの能力を取得する。

HRESULT GetCapabilities(
  LPDIDEVCAPS lpDIDevCaps
);

パラメータ

lpDIDevCaps
デバイスの能力を格納する DIDEVCAPS 構造体のアドレス。この構造体の dwSize メンバは、このメソッドを呼び出す前に初期化しておかなければならない。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

DirectX 3 との互換性については、sizeof(DIDEVCAPS_DX3) に初期化した dwSize メンバを含む DIDEVCAPS_DX3 構造体を渡してもよい。詳細については、「前のバージョンの DirectInput の設計」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::SendDeviceData

Platform SDK: DirectX

IDirectInputDevice7::GetDeviceData

IDirectInputDevice7::GetDeviceData メソッドは、デバイスからバッファリング データを取得する。

HRESULT GetDeviceData(
  DWORD cbObjectData,
  LPDIDEVICEOBJECTDATA rgdod,
  LPDWORD pdwInOut,
  DWORD dwFlags
);

パラメータ

cbObjectData
DIDEVICEOBJECTDATA 構造体のバイト単位のサイズ。
rgdod
バッファリング データを受け取るための DIDEVICEOBJECTDATA 構造体の配列。この配列の要素数は、pdwInOut パラメータの値と等しくなければならない。このパラメータが NULL の場合、バッファリング データはどこにも格納されないが、その他の副次エフェクトはすべて発生する。
pdwInOut
入力パラメータは、rgdod パラメータが指す配列の要素数である。出力パラメータは、実際に取得された要素数である。
dwFlags
データを取得する方法を制御するフラグ。ゼロまたは次のフラグを指定する。
DIGDD_PEEK
バッファから項目を削除しない。これ以降の IDirectInputDevice7::GetDeviceData 呼び出しで、同じデータを読み取ることができる。通常、データは読み取り後、バッファから削除される。

戻り値

成功すれば DI_OK または DI_BUFFEROVERFLOW、

失敗すれば次のエラー値のいずれかを返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTBUFFERED
DIERR_NOTINITIALIZED

注意

デバイス データを取得する前に、IDirectInputDevice7::SetDataFormat メソッドでデータ形式を設定し、IDirectInputDevice7::SetProperty メソッドでバッファ サイズを設定し、続いて IDirectInputDevice7::Acquire メソッドでデバイスを取得しなければならない。

以下の例では、バッファリング データ要素を最高 10 個まで読み取る。デバイス バッファからは、データを読み取りながら削除している。

DIDEVICEOBJECTDATA rgdod[10];
DWORD dwItems = 10;
hres = IDirectInputDevice7_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
rgdod,
&dwItems,
    0);
if (SUCCEEDED(hres)) {
// dwItems = 読み取られた要素数 (0 になる)。
if (hres == DI_BUFFEROVERFLOW) {
// バッファがオーバーフローした。
    }
}

バッファをフラッシュして、フラッシュした項目の数を取得するには、rgdod パラメータに NULL、pdwInOut パラメータに INFINITE を含む変数へのポインタをそれぞれ指定する。以下の例で、その方法を示す。

dwItems = INFINITE;
hres = IDirectInputDevice7_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
NULL,
&dwItems,
            0);
if (SUCCEEDED(hres)) {
// バッファのフラッシュに成功。
// dwItems = フラッシュした要素数。
if (hres == DI_BUFFEROVERFLOW) {
// バッファがオーバーフローした。
    }
}

デバイス バッファ中の要素数を調べるには、rgdod パラメータに NULL、pdwInOut パラメータに INFINITE、dwFlags に DIGDD_PEEK をそれぞれ指定する。以下の例で、その方法を示す。

dwItems = INFINITE;
hres = IDirectInputDevice7_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
NULL,
&dwItems,
DIGDD_PEEK);
if (SUCCEEDED(hres)) {
// dwItems = バッファ内の要素数。
if (hres == DI_BUFFEROVERFLOW) {
// バッファ オーバーフローが発生。一部のデータ
// のキャプチャに失敗した。
    }
}

バッファ オーバーフローが発生したかどうかを調べるには、rgdod パラメータに NULL、pdwInOut パラメータにゼロを設定する。以下の例で、その方法を示す。

dwItems = 0;
hres = IDirectInputDevice7_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
NULL,
&dwItems,
            0);
if (hres == DI_BUFFEROVERFLOW) {
// バッファ オーバーフローが発生。
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::Poll、「ポーリングとイベント」


IDirectInputDevice7::GetDeviceInfo

IDirectInputDevice7::GetDeviceInfo メソッドは、デバイスの識別情報を取得する。

HRESULT GetDeviceInfo(
  LPDIDEVICEINSTANCE pdidi
);

パラメータ

pdidi
デバイスの識別情報を格納する DIDEVICEINSTANCE 構造体のアドレス。アプリケーションは、このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しておかなければならない。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

DirectX 3 との互換性については、sizeof(DIDEVICEINSTANCE_DX3 ) に初期化した dwSize メンバを含む DIDEVICEINSTANCE_DX3 構造体を渡してもよい。詳細については、「前のバージョンの DirectInput の設計」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice7::GetDeviceState

IDirectInputDevice7::GetDeviceState メソッドは、デバイスから直接データを取得する。

HRESULT GetDeviceState(
  DWORD cbData,
  LPVOID lpvData
);

パラメータ

cbData
lpvData パラメータ内のバイト単位のバッファ サイズ。
lpvData
デバイスの現在の状態を受け取る構造体のアドレス。IDirectInputDevice7::SetDataFormat メソッドを呼び出す前に、データ形式を設定する。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTINITIALIZED
E_PENDING

注意

デバイス データを取得する前に、IDirectInputDevice7::SetCooperativeLevel メソッドで協調レベルを設定した後、IDirectInputDevice7::SetDataFormat メソッドでデータ形式を設定し、IDirectInputDevice7::Acquire メソッドでデバイスを取得する。

次の表に示すように、5 つの定義済みデータ形式には、それぞれに対応するデバイス状態構造体が必要である。

データ形式 | 状態構造体
c_dfDIMouse | DIMOUSESTATE
c_dfDIMouse2 | DIMOUSESTATE2
c_dfDIKeyboard | 256 バイトの配列
c_dfDIJoystick | DIJOYSTATE
c_dfDIJoystick2 | DIJOYSTATE2

たとえば、c_dfDIMouse 形式を IDirectInputDevice::SetDataFormat メソッドに渡す場合は、DIMOUSESTATE 構造体を IDirectInputDevice::GetDeviceState メソッドに渡さなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::Poll、「ポーリングとイベント」、「バッファリング データと直接データ」


IDirectInputDevice2::GetEffectInfo

Platform SDK: DirectX

IDirectInputDevice7::GetEffectInfo

IDirectInputDevice7::GetEffectInfo メソッドは、エフェクトに関する情報を取得する。

HRESULT GetEffectInfo(
  LPDIEFFECTINFO pdei,
  REFGUID rguid
);

パラメータ

pdei
エフェクトの情報を受け取る DIEFFECTINFO 構造体。呼び出し側は、このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しておかなければならない。
rguid
情報を要求するエフェクトの識別子。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

C++ では、rguid パラメータは参照値として渡さなければならない。C では参照値として渡すことができないので、アドレスとして渡さなければならない。次は、C++ での呼び出し例である。

lpdev2->GetEffectInfo(&dei, GUID_Effect);

次は、C での同じ呼び出し例である。

lpdev2->lpVtbl->GetEffectInfo(lpdev2, &dei, &GUID_Effect);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::GetForceFeedbackState

Platform SDK: DirectX

IDirectInputDevice7::GetForceFeedbackState

IDirectInputDevice7::GetForceFeedbackState メソッドは、デバイスのフォース フィードバック システムの状態を取得する。

HRESULT GetForceFeedbackState(
  LPDWORD pdwOut
);

パラメータ

pdwOut
デバイスのフォース フィードバック システムの現在の状態を表すフラグのアドレス。

この値は、以下の定数の組み合わせである。

DIGFFS_ACTUATORSOFF
デバイスのフォース フィードバック アクチュエータが無効である。
DIGFFS_ACTUATORSON
デバイスのフォース フィードバック アクチュエータが有効である。
DIGFFS_DEVICELOST
デバイスが予期しない障害を被り、不確定な状態にある。一度デバイスを解放した後で再取得するか、または DISFFC_RESET コマンドを送信するかどちらかでデバイスをリセットしなければならない。
DIGFFS_EMPTY
デバイスはダウンロードされた要素を持たない。
DIGFFS_PAUSED
すべてのアクティブなエフェクトの再生が一時停止されている。
DIGFFS_POWEROFF
フォース フィードバック システムは、現在使用できない。デバイスが電源状態を報告できなければ、DIFFS_POWERON および DIFFS_POWEROFF のどちらも返されない。
DIGFFS_POWERON
フォース フィードバック システムの電源は現在入っている。デバイスが電源状態を報告できなければ、DIFFS_POWERON および DIFFS_POWEROFF のどちらも返されない。
DIGFFS_SAFETYSWITCHOFF
安全スイッチが現在オフである。つまり、デバイスが動作できない。デバイスが安全スイッチの状態を報告できなければ、DIFFS_SAFETYSWITCHON と DIFFS_SAFETYSWITCHOFF のどちらも返されない。
DIGFFS_SAFETYSWITCHON
安全スイッチが現在オンである。つまり、デバイスは動作できる。デバイスが安全スイッチの状態を報告できなければ、DIFFS_SAFETYSWITCHON と DIFFS_SAFETYSWITCHOFF のどちらも返されない。
DIGFFS_STOPPED
再生中のエフェクトはなく、デバイスは中断状態ではない。
DIGFFS_USERFFSWITCHOFF
ユーザー フォース フィードバック スイッチが現在オフである。つまり、デバイスは動作できない。デバイスがユーザー フォース フィードバック スイッチの状態を報告できなければ、DIFFS_USERFFSWITCHON と DIFFS_USERFFSWITCHOFF のどちらも返されない。
DIGFFS_USERFFSWITCHON
ユーザー フォース フィードバック スイッチが現在オンである。つまり、デバイスは動作できる。デバイスがユーザー フォース フィードバック スイッチの状態を報告できなければ、DIFFS_USERFFSWITCHON と DIFFS_USERFFSWITCHOFF のどちらも返されない。

DirectInput の将来のバージョンで、フラグが追加定義される可能性もある。アプリケーションは、現在未定義のフラグをすべて無視する必要がある。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::GetEffectInfo

Platform SDK: DirectX

IDirectInputDevice7::GetObjectInfo

IDirectInputDevice7::GetObjectInfo メソッドは、ボタンや軸などのデバイス オブジェクトの情報を取得する。

HRESULT GetObjectInfo(
  LPDIDEVICEOBJECTINSTANCE pdidoi,
  DWORD dwObj,
  DWORD dwHow
);

パラメータ

pdidoi
オブジェクトの情報を格納する DIDEVICEOBJECTINSTANCE 構造体のアドレス。この構造体の dwSize メンバは、このメソッドを呼び出す前に初期化しておかなければならない。
dwObj
取得する情報が所属するオブジェクトを識別する値。このパラメータに設定する値は、dwHow パラメータで指定されている値に依存する。
dwHow
dwObj パラメータの解釈方法を指定する値。この値は、次のいずれか 1 つである。
値 | 意味
DIPH_BYOFFSET | dwObj パラメータは、アクセスする情報が所属するオブジェクトの現在のデータ形式に対するオフセットである。
DIPH_BYID | dwObj パラメータは、オブジェクト タイプ、またはインスタンス識別子である。この識別子は、DIDEVICEOBJECTINSTANCE 構造体の dwType メンバの中に返される。この構造体は、IDirectInputDevice7::EnumObjects メソッドに対する以前の呼び出しで返されたものである。
DIPH_BYUSAGE | dwObj パラメータは、オブジェクトの "HID 使用ページ" と "使用状況" の値である。これらの値は DIMAKEUSAGEDWORD マクロにより組み合わせられる。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND

注意

DirectX 3 との互換性については、sizeof(DIDEVICEOBJECTINSTANCE_DX3) に初期化した dwSize メンバを含む DIDEVICEOBJECTINSTANCE_DX3 構造体を渡してもよい。詳細については、「前のバージョンの DirectInput の設計」を参照すること。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice7::GetProperty

IDirectInputDevice7::GetProperty メソッドは、入力デバイスについての情報を取得する。

HRESULT GetProperty(
  REFGUID rguidProp,
  LPDIPROPHEADER pdiph
);

パラメータ

rguidProp
取得するプロパティの識別子。この識別子として、事前定義された値の 1 つ、またはプロパティを識別する GUID へのポインタを使用できる。入力デバイスに対しては、次のプロパティが事前定義されている。
DIPROP_AUTOCENTER
デバイス オブジェクトが自動センタリングを行うかどうかを指定する。詳細については、「IDirectInputDevice7::SetProperty」を参照すること。
DIPROP_AXISMODE
軸モードを取得する。取得値 (DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL) は、割り当てられた DIPROPDWORD 構造体の dwData メンバに設定される。詳細は、pdiph パラメータの説明を参照すること。
DIPROP_BUFFERSIZE
入力バッファ サイズを取得する。取得値は、割り当てられた DIPROPDWORD 構造体の dwData メンバに設定される。詳細は、pdiph パラメータの説明を参照すること。

バッファ サイズは、IDirectInputDevice7::GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。DIPROPDWORD 構造体の dwData メンバ中のバッファ サイズが大きすぎてデバイスがサポートできなければ、サポート可能な最大バッファ サイズが設定される。要求したバッファ サイズが設定されたかどうかを確認するには、バッファ サイズ プロパティを取得して、設定しようとした値とその結果を比較する。

DIPROP_DEADZONE
0 ～ 10,000 の範囲でジョイスティックの無効ゾーンの値を取得する。ここで、0 は無効ゾーンが存在しないこと、5,000 は無効ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸が無効ゾーン内にあると、軸の範囲の中心にあるものと報告される。
DIPROP_FFGAIN
デバイスのゲインを取得する。詳細については、「IDirectInputDevice7::SetProperty」を参照すること。
DIPROP_FFLOAD
デバイスのメモリ ロードを取得する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは DIPH_DEVICE でなければならない。

dwData メンバは、0～100 の範囲にある値を格納する。この値は、使用中のデバイス メモリのパーセント数を示す。

DIPROP_GRANULARITY
入力の細分度を取得する。取得値は、割り当てられた DIPROPDWORD 構造体の dwData メンバに設定される。詳細は pdiph パラメータの説明を参照すること。

細分度は、オブジェクトが移動距離を報告する際の最小量を表す。多くの軸オブジェクトの細分度は 1 であり、あらゆる値を取ることができる。軸によっては、より大きな細分度を持つものもある。たとえば、マウスのホイール軸の細分度は 20 にすることもできる。報告される位置変化はすべて、20 の倍数となる。すなわち、ユーザーがホイールをゆっくり回転させると、デバイスは位置を 0、20、40 などと報告する。

これは読み取り専用プロパティである。IDirectInputDevice7::SetProperty メソッドを呼び出しても、値を設定することはできない。

DIPROP_GUIDANDPATH
アプリケーションは、デバイスのクラス GUID とデバイス インターフェイス (パス) にアクセスできる。詳細設定の可能なアプリケーションはこのプロパティを使うことで、DirectInput でサポートされていない HID に対して操作を実行できる。詳細については、DIPROPGUIDANDPATH 構造体のリファレンスを参照すること。
DIPROP_INSTANCENAME
デバイスのインスタンスの登録名を取得する。詳細については、「IDirectInputDevice7::SetProperty」を参照すること。
DIPROP_PRODUCTNAME
デバイスの製品の登録名を取得する。詳細については、「IDirectInputDevice7::SetProperty」を参照すること。
DIPROP_RANGE
オブジェクトが報告できる値の範囲を取得する。取得された最小値および最大値は、割り当てられた DIPROPRANGE 構造体の lMin および lMax メンバに設定される。詳細は pdiph パラメータの説明を参照すること。

一部のデバイスでは、これは読み取り専用プロパティである。IDirectInputDevice7::SetProperty メソッドを呼び出しても、値を設定することはできない。

DIPROP_SATURATION
0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を取得する。飽和レベルとは、軸が極限位置にあるとみなされる点のことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (無効ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。
pdiph
メンバとして DIPROPHEADER 構造体を持つ大型プロパティ依存構造体の、DIPROPHEADER 部分のアドレス。オブジェクトの範囲情報の取得時には、この値は、DIPROPRANGE 構造体に含まれる DIPROPHEADER 構造体のアドレスとなる。ほかのプロパティの場合、この値は、DIPROPDWORD 構造体に含まれる DIPROPHEADER 構造体のアドレスとなる。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

注意

以下の C コードの例は、DIPROP_BUFFERSIZE プロパティ値の取得方法を説明する。

DIPROPDWORD dipdw; // DIPROPDWORD は DIPROPHEADER 構造体を格納する。
HRESULT hr;
dipdw.diph.dwSize    = sizeof(DIPROPDWORD);
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipdw.diph.dwObj    = 0; // デバイス プロパティ
dipdw.diph.dwHow    = DIPH_DEVICE;

hr = IDirectInputDevice7_GetProperty(pdid, DIPROP_BUFFERSIZE, &dipdw.diph);
if (SUCCEEDED(hr)) {
// dipdw.dwData メンバはバッファ サイズを格納する。
}

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::SetProperty


IDirectInputDevice7::Initialize

IDirectInputDevice7::Initialize メソッドは、DirectInputDevice オブジェクトを初期化する。IDirectInput7::CreateDevice メソッドは、デバイスの作成後、自動的にデバイスを初期化するので、アプリケーションは通常、このメソッドを呼び出す必要はない。

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFGUID rguid
);

パラメータ

hinst
DirectInput オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドル。DirectInput は、この値を使用して、アプリケーションまたは DLL が、オブジェクト作成の資格を認められているかどうかを判断し、下位互換性のためにとるべき特別な動作を確定する。

DLL が親のアプリケーションのハンドルを渡すと、エラーとなる。たとえば、Web ページに埋め込まれている DirectInput を使用する ActiveX コントロールは、Web ブラウザのハンドルではなく、それ自身のインスタンスのハンドルを渡さなければならない。これにより、DirectInput がそのコントロールを認識し、必要と思われる特別な動作をすべて有効にすることが確実になる。

dwVersion
アプリケーションの設計対象である DirectInput のバージョン番号。この値は通常、DIRECTINPUT_VERSION である。以前のバージョン番号を渡すと、DirectInput がそのバージョンをエミュレートすることになる。詳細については、「前のバージョンの DirectInput の設計」を参照すること。
rguid
インターフェイスを関連付けるデバイスのインスタンスに対する識別子。IDirectInput7::EnumDevices メソッドを使うと、システムがどのインスタンス GUID をサポートしているかを確認することができる。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_ACQUIRED
DIERR_DEVICENOTREG

S_FALSE が返されれば、rGUID を介して渡されたインスタンス GUID を持つデバイスは初期化済みである。

注意

このメソッドが失敗する場合、基底のオブジェクトは不定の状態にあるものとみなし、使用前に再初期化しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::Poll

Platform SDK: DirectX

IDirectInputDevice7::Poll

IDirectInputDevice7::Poll メソッドは、DirectInput デバイス上のポーリング対象オブジェクトからデータを取得する。デバイスにポーリングが必要ないときにこのメソッドを呼び出しても、エフェクトは一切ない。ポーリングする必要があるデバイスが定期的にポーリングされない場合、このデバイスから新しいデータは取得されない。このメソッドを呼び出すと、DirectInput はデバイス状態を更新し、バッファリング データが使用可能であれば入力イベントを生成し、通知が有効であれば通知イベントを設定する。

HRESULT Poll()

パラメータ

なし。

戻り値

成功すれば DI_OK を返す。デバイスがポーリングを要求しない場合は DI_NOEFFECT を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_NOTINITIALIZED

注意

デバイス データをポーリングする前に、IDirectInputDevice7::SetDataFormat メソッドでデータ形式を設定して、IDirectInputDevice7::Acquire メソッドでデバイスを取得しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

「ポーリングとイベント」


IDirectInputDevice7::RunControlPanel

IDirectInputDevice7::RunControlPanel メソッドは、このデバイスに関連付けられた DirectInput コントロール パネルを実行する。デバイスにコントロール パネルが関連付けられていない場合は、デフォルトのコントロール パネルが起動される。

HRESULT RunControlPanel(
  HWND hwndOwner,
  DWORD dwFlags
);

パラメータ

hwndOwner
親ウィンドウのハンドル。このパラメータが NULL なら、親ウィンドウは使用されない。
dwFlags
現在未使用である。ゼロだけが有効な値である。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::SendDeviceData

Platform SDK: DirectX

IDirectInputDevice7::SendDeviceData

IDirectInputDevice7::SendDeviceData メソッドは、出力を受け付けるデバイスにデータを送信する。デバイスは、取得済みの状態でなければならない。

HRESULT SendDeviceData(
  DWORD cbObjectData,
  LPCDIDEVICEOBJECTDATA rgdod,
  LPDWORD pdwInOut,
  DWORD fl
);

パラメータ

cbObjectData
単一の DIDEVICEOBJECTDATA 構造のサイズ (バイト単位)。
rgdod
デバイスに送信するデータを格納した DIDEVICEOBJECTDATA 構造体の配列。これは、*pdwInOut 要素で構成されていなければならない。

DIDEVICEOBJECTDATA 構造体 の dwOfs フィールドには、データの送信先となるデバイス オブジェクトの識別子が含まれなければならない。この識別子は、DIDEVICEOBJECTINSTANCE 構造体 の dwType フィールドから取得される。dwTimeStamp および dwSequence メンバは、ゼロでなければならない。

pdwInOut
呼び出し時は、このパラメータが指す変数には、rgdod が指す配列の要素数が含まれる。終了時は、デバイスに送信された要素数が含まれる。
fl
データの送信方法を制御するフラグ。ゼロまたは次の値を取ることができる。
DISDD_CONTINUE
送信されるデバイス データは、以前に送信されたデバイス データに上書きされる。「注意」を参照すること。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED

注意

個別のデータ要素が特定の順序で送信されるという保証はない。しかし、IDirectInputDevice7::SendDeviceData の呼び出しが成功した場合、送信されたデータの間に別のデータが紛れ込むことはない。また、複数のデータが 1 回の呼び出しで同じオブジェクトに送信される場合、どのデータが送信されるかは特定されない。

たとえば、データをパケット単位で送信できるデバイスがあり、各パケットは、A および B という 2 つの情報を表すとする。ここで、アプリケーションが 3 つのデータ要素 (B = 2、A = 1、B =0) を送信しようとするとどうなるだろうか。

実際のデバイスに送信されるパケットは 1 つである。パケットの A フィールドの値は 1、そしてパケットの B フィールドの値は 2 か 0 になる。

データを指定どおりにデバイスに送信する必要がある場合は、IDirectInputDevice7::SendDeviceData を 3 回呼び出し、呼び出しごとにデータ要素を 1 つずつ送信しなければならない。

最初の呼び出しに応答して、A フィールドがブランク、B フィールドの値が 2 のパケットをデバイスに送信する。

2 回目の呼び出しでは、A フィールドの値が 1、B フィールドがブランクのパケットを送信する。

最後の 3 回目の呼び出しで、A フィールドがブランク、B フィールドの値が 0 のパケットを送信する。

DISDD_CONTINUE フラグが設定されている場合、送信されたデバイス データは以前に送信されたデバイス データに上書きされる。フラグの設定がなければ、送信されるデバイス データはまったく新しいデータとして処理される。

たとえば、Button0 および Button1 の 2 つのボタン出力をサポートするデバイスがあるとする。アプリケーションが最初に IDirectInputDevice7::SendDeviceData を呼び出して "Button0 押下" を渡すと、デバイスには、"Button0 押下、Button1 未押下" という形式のパケットが送信される。次に、アプリケーションがもう一度 SendDeviceData を呼び出して "Button1 押下" と DISDD_CONTINUE フラグを渡すと、デバイスには、"Button0 押下、Button1 押下" という形式のパケットが送信される。しかし、アプリケーションが DISDD_CONTINUE フラグを渡さなかった場合、デバイスに送信されるパケットは、"Button0 未押下 , Button1 押下" となる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice2::SendForceFeedbackCom

Platform SDK: DirectX

IDirectInputDevice7::SendForceFeedbackCommand

IDirectInputDevice7::SendForceFeedbackCommand メソッドは、デバイスのフォース フィードバック システムにコマンドを送信する。

HRESULT SendForceFeedbackCommand(
  DWORD dwFlags
);

パラメータ

dwFlags
目的の状態変化を示す単一の値。次のいずれか 1 つの値を取ることができる。
DISFFC_CONTINUE
中断されたすべてのアクティブなエフェクトの再生を継続する。デバイスが中断状態にないときにこのコマンドを送信すると、エラーになる。
DISFFC_PAUSE
すべてのアクティブ エフェクトの再生を中断する。このコマンドはエフェクトのクロックも停止するので、再開すると、エフェクトは継続時間を満了するまで再生が続行される。

デバイスが中断状態にある間は、新しいエフェクトを開始したり、既存のエフェクトを変更したりすることはできない。そのような操作を行うと、これ以降の DISFFC_CONTINUE コマンドが正常に機能しなくなることがある。

中断を破棄してすべてのエフェクトを停止するには、DISFFC_STOPALL または DISFCC_RESET コマンドを使用する。

DISFFC_RESET
デバイスのフォース フィードバック システムを始動状態にする。すべてのエフェクトはデバイスから削除され、有効でなくなる。これらのエフェクトを再び使用するには、再生成しなければならない。デバイスのアクチュエータは無効である。
DISFFC_SETACTUATORSOFF
デバイスのフォース フィードバック アクチュエータを無効にする。アクチュエータがオフの間も、エフェクトは引き続き再生されるが、デバイスはそれを無視する。音楽再生デバイスにたとえると、エフェクトは一時停止 (ポーズ) ではなく、消音 (ミュート) された状態である。
DISFFC_SETACTUATORSON
デバイスのフォース フィードバック アクチュエータを有効にする。
DISFFC_STOPALL
すべてのアクティブなエフェクトの再生を停止する。アクティブなエフェクトはすべてリセットされるが、デバイスには保存されており、引き続き有効である。デバイスが中断されている場合、その状態は失われる。

このコマンドは、再生中のエフェクトごとに IDirectInputEffect::Stop メソッドを呼び出すことに等しい。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice7::SetCooperativeLevel

IDirectInputDevice7::SetCooperativeLevel メソッドは、デバイスのインスタンスに対する協調レベルを確立する。協調レベルは、このインスタンスが、同じデバイスのほかのインスタンス、およびシステムのこれ以外の部分との間で、どのように対話するかを決定する。

HRESULT SetCooperativeLevel(
  HWND hwnd,
  DWORD dwFlags
);

パラメータ

hwnd
デバイスに関連付けられているウィンドウ ハンドル。このパラメータは、このプロセスに属する最上位の有効なウィンドウ ハンドルでなければならない。デバイスに関連付けられたウィンドウは、DirectInput デバイスの中でアクティブである間は、破壊してはならない。
dwFlags
デバイスに関連付ける協調レベルを表すフラグ。次のフラグが定義されている。
DISCL_BACKGROUND
アプリケーションは、バックグラウンド アクセス権を要求する。バックグラウンド アクセス権が許可されると、割り当てられたウィンドウがアクティブ ウィンドウでない場合でも、いつでもデバイスを取得できる。
DISCL_EXCLUSIVE
アプリケーションは、排他アクセス権を要求する。排他アクセス権が付与されると、デバイスが取得されている間、デバイスのほかのインスタンスは、そのデバイスの排他アクセス権を取得できない。ただし、別のアプリケーションが排他アクセス権を取得している場合でも、デバイスの非排他アクセス権は常に認められる。

アプリケーションがマウスまたはキーボード デバイスを排他モードで取得している場合は、WM_ENTERSIZEMOVE メッセージおよび WM_ENTERMENULOOP メッセージを受け取ると、常にデバイスを解放する必要がある。それ以外の場合、ユーザーはメニューを操作したり、ウィンドウを移動またはウィンドウのサイズを変更したりすることはできない。

DISCL_FOREGROUND
アプリケーションはフォアグラウンド アクセス権を要求する。フォアグラウンド アクセス権が付与されると、割り当てられたウィンドウがバックグラウンドに移動するときに、デバイスは自動的に解放される。
DISCL_NONEXCLUSIVE
アプリケーションは非排他アクセス権を要求する。デバイスに対するアクセス権は、同じデバイスにアクセスしているほかのアプリケーションの妨げにならない。
DISCL_NOWINKEY
Windows キーを無効にする。このフラグを設定すると、ユーザーは誤ってアプリケーションを終了することがなくなる。

アプリケーションは、DISCL_FOREGROUND または DISCL_BACKGROUND のどちらか一方を指定しなければならない。両方指定することも、まったく指定しないこともエラーとなる。同様に、アプリケーションは、DISCL_EXCLUSIVE または DISCL_NONEXCLUSIVE のどちらか一方を指定しなければならない。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_HANDLE

注意

システム マウスが排他モードで取得されると、マウス ポインタは、デバイスが解放されるまで画面から消去される。

アプリケーションは、IDirectInputDevice7::Acquire メソッドでデバイスを取得する前に、このメソッドを呼び出さなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

「協調レベル」


IDirectInputDevice7::SetDataFormat

IDirectInputDevice7::SetDataFormat メソッドは、DirectInput デバイスのデータ形式を設定する。

HRESULT SetDataFormat(
  LPCDIDATAFORMAT lpdf
);

パラメータ

lpdf
DirectInputDevice が返すべきデータ形式を記述する構造体のアドレス。アプリケーションは、独自の DIDATAFORMAT 構造体を定義することも、次の事前定義されたグローバル変数の 1 つを使用することもできる。
  • c_dfDIKeyboard
  • c_dfDIMouse
  • c_dfDIMouse2
  • c_dfDIJoystick
  • c_dfDIJoystick2

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_ACQUIRED
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

IDirectInputDevice7::Acquire でデバイスを取得する前に、データ形式を設定しておかなければならない。データ形式は、一度設定するだけでよい。データ形式は、デバイスが取得されている間は変更できない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::GetDeviceState


IDirectInputDevice7::SetEventNotification

IDirectInputDevice7::SetEventNotification メソッドは、イベント通知ステータスを設定する。このメソッドは、デバイス状態が変化したときに設定されるイベントを指定する。イベント通知をオフにするためにも使われる。

HRESULT SetEventNotification(
  HANDLE hEvent
);

パラメータ

hEvent
デバイス状態が変化したときに設定されるイベントのハンドル。DirectInput はデバイスの状態が変化したときに、このハンドルに対して Win32 SetEvent 関数を使用する。hEvent パラメータを NULL にすると、通知は無効になる。

アプリケーションは、Win32 CreateEvent 関数を使用して、手動リセット イベントまたは自動リセット イベントとしてハンドルを作成することができる。イベントを自動リセット イベントとして作成すると、オペレーティング システムは、待ち時間が経過したときに自動的にイベントをリセットする。イベントを手動リセット イベントとして作成すると、アプリケーションは、Win32 ResetEvent 関数を呼び出してイベントをリセットしなければならない。DirectInput は、イベント通知ハンドルに対して、Win32 ResetEvent 関数を呼び出さない。アプリケーションは、通常、イベントを自動リセット イベントとして作成する。

戻り値

成功すれば DI_POLLEDDEVICE、

失敗すれば次のエラー値のいずれかを返す。

DIERR_ACQUIRED
DIERR_HANDLEEXISTS
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

デバイス状態の変更は次のいずれかに定義される。

  • 軸の位置の変更
  • ボタンの状態 (押した状態または離した状態)
  • 視点コントロールの方向の変更
  • 取得の喪失

DirectInputDevice オブジェクト中に選択されているイベントに対しては、Win32 CloseHandle 関数を呼び出してはならない。イベント ハンドルを終了する前に、hEvent パラメータに NULL を設定して、このメソッドを呼び出さなければならない。

イベント通知ハンドルは、デバイスが取得されている間は変更できない。この関数が成功すれば、アプリケーションは、ほかの Win32 イベント ハンドルと同様に、このイベント ハンドルを使用できる。

以下の例は、ハンドルが現在ブロッキングなしに設定されているかどうかをチェックする。

dwResult = WaitForSingleObject(hEvent, 0);
if (dwResult == WAIT_OBJECT_0) {
// イベントを設定する。イベントが自動リセットで
// 作成されていた場合は、同時にリセットされる。
}

次の例は、イベントが設定されるまで、繰り返しブロッキングを行う処理を示している。待ち時間が経過するまで、スレッドはシステムに応答できないので、この動作は厳禁である。特に、スレッドは Windows メッセージに応答しなくなる。

dwResult = WaitForSingleObject(hEvent, INFINITE);
if (dwResult == WAIT_OBJECT_0) {
// イベントが設定された。イベントが自動リセットで
// 作成されていた場合は、同時にリセットされる。
}

以下の例は、2 つのイベントを使用するメッセージベースのアプリケーションの、典型的なメッセージ ループを示している。

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

次の例は、2 つのイベントを使用する非メッセージベースのアプリケーションの、典型的なメッセージ ループを示している。

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

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

「ポーリングとイベント」


IDirectInputDevice7::SetProperty

IDirectInputDevice7::SetProperty メソッドは、デバイスの動作を定義するプロパティを設定する。これらのプロパティには、入力バッファ サイズや軸モードなどがある。

HRESULT SetProperty(
  REFGUID rguidProp,
  LPCDIPROPHEADER pdiph
);

パラメータ

rguidProp
設定対象のプロパティの識別子。この識別子は、事前定義された値の 1 つでも、またはプロパティを識別する GUID へのポインタでもよい。以下のプロパティ値が入力デバイスに対して事前定義されている。
DIPROP_AUTOCENTER
デバイス オブジェクトが自動センタリングを行うかどうかを指定する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。

dwData メンバは、次のいずれか 1 つの値を取ることができる。

DIPROPAUTOCENTER_OFF:ユーザーがデバイスを離しても、自動的にセンタリングを行わない。フォース フィードバックを使用するアプリケーションは、エフェクトの再生前に自動センタリングのスプリングを無効にする必要がある。

DIPROPAUTOCENTER_ON:ユーザーがデバイスを離すと、自動的にセンタリングを行う。たとえば、このモードのジョイスティックは、自動センタリングのスプリングが有効になる。

フォース フィードバック エフェクトを使用すると、自動センタリングのスプリングに影響する場合がある。一部のデバイスでは、フォース フィードバック エフェクトを再生するときに、自動センタリング スプリングを無効にする。

自動センタリング機能をサポートしていないデバイスもある。

DIPROP_AXISMODE
軸モードを設定する。設定値 (DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL) は、割り当てられた DIPROPDWORD 構造体の dwData メンバに指定しなければならない。詳細は pdiph パラメータの説明を参照すること。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。

DIPROP_BUFFERSIZE
入力バッファ サイズを設定する。設定値は、割り当てられた DIPROPDWORD 構造体の dwData メンバに指定しなければならない。詳細は pdiph パラメータの説明を参照すること。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

DIPROP_CALIBRATIONMODE
DirectInput が取得するデータが、キャリブレーション済みかキャリブレーション前かを、アプリケーションが指定できるようにする。デフォルトでは、DirectInput はキャリブレーション済みデータを取得する。

デバイス全体に対してキャリブレーション モードを設定することは、それぞれの軸に対してキャリブレーション モードを設定することと同じ意味を持つ。

DIPROPDWORD 構造体の dwData メンバは次のいずれか 1 つの値を取ることができる。

DIPROPCALIBRATIONMODE_COOKED:DirectInput は、キャリブレーション情報の適用後のデータを返す。これがデフォルト モードである。

DIPROPCALIBRATIONMODE_RAW:DirectInput は、キャリブレーション前の未加工データを返す。このモードは通常、コントロール パネル型のアプリケーションでのみ使用される。

デバイスを未加工モードに設定すると、無効ゾーン、飽和値、および範囲の設定が無視される。

DIPROP_DEADZONE
0 ～ 10,000 の範囲でジョイスティックの無効ゾーンの値を設定する。ここで、0 は無効ゾーンが存在しないこと、5,000 は無効ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸が無効ゾーン内にあると、軸の範囲の中心にあるものと報告される。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

DIPROP_FFGAIN
デバイスのゲインを設定する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。

dwData メンバは、デバイス上に作成されたすべてのエフェクトに適用されるゲイン値を格納する。値は、0 ～ 10,000 の整数である。デバイスに対するエフェクトのマグニチュードは、この値で調整される。たとえば、10,000 は、すべてのエフェクト マグニチュードをそのまま適用することを示す。9,000 は、すべてのエフェクト マグニチュードをその名目マグニチュードの 90 パーセントに圧縮することを示す。

ゲイン値の設定は、ユーザーの好みに応じて、すべてのフォース フィードバック エフェクトを一率に減少したい場合に有効である。

ほかのプロパティとは異なり、ゲインはデバイスが取得状態にある場合に設定できる。

DIPROP_INSTANCENAME
これは、詳細設定の可能なアプリケーション用に設けられたプロパティであり、これを使ってデバイスのインスタンスの登録名を変更すると、接続されている同種のデバイスを区別することができる。インスタンスの登録名は、DIDEVICEINSTANCE 構造体の tszInstanceName メンバ内に返される。アプリケーションは通常、登録名を変更する必要はない。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

pdiph パラメータは、DIPROPSTRING 構造体の diph メンバへのポインタでなければならない。

DIPROP_PRODUCTNAME
これは、詳細設定の可能なアプリケーション用に設けられたプロパティであり、これを使ってデバイスの製品の登録名を変更すると、接続されている同種のデバイスを区別することができる。製品の登録名は、DIDEVICEINSTANCE 構造体の tszProductName メンバ内に返される。アプリケーションは通常、登録名を変更する必要はない。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

pdiph パラメータは、DIPROPSTRING 構造体の diph メンバへのポインタでなければならない。

DIPROP_RANGE
オブジェクトが報告可能な値の範囲を設定する。最小値および最大値は、割り当てられた DIPROPRANGE 構造体の lMin メンバと lMax メンバから取得される。

一部のデバイスでは、これは読み取り専用プロパティである。

範囲の大小を逆にはできない。lMax は、lMin より大きな値でなければならない。

DIPROP_SATURATION
0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を設定する。飽和レベルとは、軸が極限位置にあるとみなされる点のことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (無効ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

pdiph
タイプ固有のプロパティ構造体に含まれる DIPROPHEADER 構造体のアドレス。

戻り値

成功すれば DI_OK または DI_PROPNOEFFECT、

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

注意

バッファ サイズは、IDirectInputDevice7::GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。DIPROPDWORD 構造体の dwData メンバ中のバッファ サイズが大きすぎてデバイスがサポートできない場合は、サポート可能な最大バッファ サイズが設定される。要求したバッファ サイズが設定されたかどうかを確認するには、バッファ サイズ プロパティを取得して、設定しようとした値とその結果を比較する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::GetProperty


IDirectInputDevice7::Unacquire

IDirectInputDevice7::Unacquire メソッドは、デバイスへのアクセス権を解放する。

HRESULT Unacquire();

パラメータ

なし。

戻り値

デバイスが解放された場合は DI_OK を返し、デバイスが取得状態になかった場合は DI_NOEFFECT を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputDevice7::WriteEffectToFile

IDirectInputDevice7::WriteEffectToFile メソッドは、1 つ以上のフォース フィードバック エフェクトについての情報をファイルに保存する。このファイルは、IDirectInputDevice7::EnumEffectsInFile を使って読み取ることができる。これは主に、独自のフォースを生成するアプリケーションを作成したい開発者向けのメソッドである。

HRESULT WriteEffectToFile(
  LPCSTR lpszFileName,
  DWORD dwEntries,
  LPCDIFILEEFFECT rgDiFileEft,
  DWORD dwFlags
);

パラメータ

lpszFileName
RIFF ファイルの名前。
dwEntries
rgDiFileEft 配列中の構造体の数。
rgDiFileEft
DIFILEEFFECT 構造体の配列。
dwFlags
エフェクトの記述方法を制御するフラグ。DIFEF_DEFAULT (= 0) または次の値を取ることができる。
DIFEF_INCLUDENONSTANDARD
DirectInput で定義されていないエフェクトを含める。このフラグが指定されない場合は、GUID_ConstantForce など、Dinput.h に定義された GUID を持つエフェクトのみが記述される。

戻り値

メソッドが成功すれば DI_OK を返す。

失敗すれば DIERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::EnumEffectsInFile


IDirectInputEffect

アプリケーションは、IDirectInputEffect インターフェイスのメソッドを使用して、フォース フィードバック デバイスのエフェクトを管理する。

このインターフェイスは IDirectInputDevice7::CreateEffect メソッドを使用して取得される。

IDirectInputEffect インターフェイスのメソッドは、以下のグループにまとめることができる。

エフェクトの情報 | GetEffectGuid
 | GetEffectStatus
 | GetParameters
エフェクトの操作 | Download
 | Initialize
 | SetParameters
 | Start
 | Stop
 | Unload
その他 | Escape

すべての COM インターフェイスと同様に、IDirectInputEffect インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUTEFFECT 型は IDirectInputEffect インターフェイスへのポインタとして定義される。

typedef struct IDirectInputEffect  *LPDIRECTINPUTEFFECT;

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::Download

IDirectinputEffect::Download メソッドは、デバイスにエフェクトを設定する。同じエフェクトが既にデバイスにあれば、IDirectInputEffect::SetParameters メソッドで設定された値に適合するように、既存のエフェクトが更新される。

HRESULT Download(void);

パラメータ

なし。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

S_FALSE が返された場合、そのエフェクトは既にデバイスにダウンロードされている。

注意

エフェクトの再生中にエフェクトを更新することは有効である。この操作の意味は、IDirectInputEffect::SetParameters のリファレンスの中で説明されている。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::Escape

IDirectInputEffect::Escape メソッドは、ハードウェア固有のコマンドをドライバに送信する。

HRESULT Escape(
  LPDIEFFESCAPE pesc
);

パラメータ

pesc
送信するコマンドを記述する DIEFFESCAPE 構造体。成功すると、使用された出力バッファのバイト数が cbOutBuffer メンバに格納される。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL

ほかのデバイス固有エラー コードを返すこともできる。ハードウェア メーカーから詳細情報を入手すること。

注意

各ドライバは、異なるエスケープ シーケンスを実装しているので、正しいドライバと通信しているかどうかは、アプリケーション自体が確認しなければならない。これは、DIDEVICEINSTANCE 構造体の guidFFDriver メンバと、アプリケーションが期待している値を比較することにより確認できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::GetEffectGuid

IDirectInputEffect::GetEffectGuid メソッドは、IDirectInputEffect オブジェクトが表すエフェクトの GUID を取得する。

HRESULT GetEffectGuid(
  LPGUID pguid
);

パラメータ

pguid
このメソッドによって格納される GUID 構造体。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

取得した GUID を IDirectInputDevice7::GetEffectInfo に渡すことにより、そのエフェクトに関する拡張情報を取得できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::GetEffectStatus

IDirectInputEffect::GetEffectStatus メソッドは、エフェクトのステータスを取得する。

HRESULT GetEffectStatus(
  LPDWORD pdwFlags
);

パラメータ

pdwFlags
エフェクトのステータス フラグ。ゼロまたは次のフラグを取ることができる。
DIEGES_PLAYING
エフェクトは再生中である。
DIEGES_EMULATED
エフェクトはエミュレートされている。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::GetParameters

IDirectInputEffect::GetParameters メソッドは、エフェクトの情報を取得する。

HRESULT GetParameters(
  LPDIEFFECT peff,
  DWORD dwFlags
);

パラメータ

peff
エフェクト情報を受け取る DIEFFECT 構造体のアドレス。dwSize メンバは、このメソッドを呼び出す前にアプリケーションによって設定しておかなければならない。
dwFlags
エフェクト情報のどの部分を取得するかを指定するフラグ。ゼロまたは次のフラグを取ることができる。
DIEP_ALLPARAMS
ほかのすべての DIEP_* フラグの組み合わせたもので、DIEFFECT 構造体の全メンバを要求することを示す。
DIEP_ALLPARAMS_DX5
DIEP_STARTDELAY フラグを除くすべての DIEP_* フラグを組み合わせたもの。
DIEP_AXES
cAxes および rgdwAxes メンバがデータを受け取る。入力パラメータとして、cAxes は rgdwAxes が指すバッファのサイズ (DWORD 単位) を格納する。バッファが小さすぎると、このメソッドは DIERR_MOREDATA を返し、必要なバッファ サイズを cAxes に設定する。
DIEP_DIRECTION
cAxes および rglDirection メンバがデータを受け取る。入力パラメータとして、cAxes は rglDirection が指すバッファのサイズ (DWORD 単位) を格納する。バッファが小さすぎると、GetParameters メソッドは DIERR_MOREDATA を返し、必要なバッファ サイズを cAxes に設定する。

dwFlags メンバには、座標系フラグ (DIEFF_CARTESIAN、DIEFF_POLAR または DIEFF_SPHERICAL) のうち少なくとも 1 つが設定されていなければならない。DirectInput は、指定された 1 つの座標系で表したエフェクトの方向を返す。その際、必要があれば座標系間で変換を行う。終了時に、dwFlags メンバには 1 つの座標系フラグが設定され、DirectInput が使用する座標系を指示する。特別に、3 つの座標系フラグすべてを渡すと、それらの座標を設定したのとまったく同じ形式で座標が取得される。

DIEP_DURATION
dwDuration メンバがデータを受け取る。
DIEP_ENVELOPE
lpEnvelope メンバは、データを受け取る DIENVELOPE 構造体を指す。エフェクトに関係するエンベロープがないときは、lpEnvelope メンバは NULL に設定される。
DIEP_GAIN
dwGain メンバがデータを受け取る。
DIEP_SAMPLEPERIOD
dwSamplePeriod メンバがデータを受け取る。
DIEP_STARTDELAY
dwStartDelay メンバがデータを受け取る。
DIEP_TRIGGERBUTTON
dwTriggerButton メンバがデータを受け取る。
DIEP_TRIGGERREPEATINTERVAL
dwTriggerRepeatInterval メンバがデータを受け取る。
DIEP_TYPESPECIFICPARAMS
lpvTypeSpecificParams メンバは、cbTypeSpecificParams メンバによりサイズが指定されるバッファを指す。リターン時、このバッファには、エフェクトに関係するタイプ固有データが格納され、cbTypeSpecificParams メンバには、コピーされたバイト数が格納される。アプリケーションで用意されたバッファが小さすぎてタイプ固有データすべてを格納できない場合、このメソッドは DIERR_MOREDATA を返し、必要とされるバッファ サイズのバイト数が cbTypeSpecificParams メンバに設定される。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_MOREDATA
DIERR_NOTINITIALIZED

注意

DIERR_INVALIDPARAM エラーを発生する一般的なエラーには、DIEFFECT 構造体の dwSize メンバの未設定、無効なフラグの指定、エフェクト情報の受け取り準備上での DIEFFECT 構造体のメンバの不適正な設定、などがある。たとえば、情報が dwTriggerButton メンバに取得されるべきときは、DirectInput がボタンを記述する方法を識別できるように、dwFlags メンバには、DIEFF_OBJECTIDS または DIEFF_OBJECTOFFSETS のどちらか一方を設定しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::Initialize

IDirectInputEffect::Initialize メソッドは、DirectInputEffect オブジェクトを初期化する。

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFGUID rguid
);

パラメータ

hinst
DirectInputEffect オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドル。DirectInput は、この値を使用して、アプリケーションまたは DLL が、オブジェクト作成の資格を認められているかどうかを判断し、下位互換性のために取るべき特別な動作を確定する。DLL が親のアプリケーションのハンドルを渡すと、エラーとなる。
dwVersion
アプリケーションの設計対象である DirectInput のバージョン番号。この値は通常、DIRECTINPUT_VERSION である。以前のバージョン番号を渡すと、DirectInput がそのバージョンをエミュレートすることになる。詳細については、「前のバージョンの DirectInput の設計」を参照すること。
rguid
インターフェイスが関連付けられているエフェクトの識別子。IDirectInputDevice7::EnumEffects メソッドを使用して、デバイスがどのエフェクト GUID をサポートしているかを確認できる。

戻り値

成功すれば DI_OK を返す。

失敗すれば DIERR_DEVICENOTREG を返す。

注意

このメソッドが失敗する場合、基底のオブジェクトは不定の状態にあるものとみなされるので、初期化し直してからでないと以降の使用はできない。

IDirectInputDevice7::CreateEffect メソッドは、エフェクトを作成後、自動的に初期化する。アプリケーションは、通常、Initialize メソッドを呼び出す必要はない。

C++ では、rguid パラメータは参照値として渡さなければならない。C では参照値として渡すことができないので、アドレスとして渡さなければならない。次は、C++ での呼び出し例である。

lpeff->Initialize(g_hinstDll, DIRECTINPUT_VERSION, GUID_Effect);

次は、C での同じ呼び出し例である。

lpeff->lpVtbl->Initialize(lpeff, g_hinstDll,
                          DIRECTINPUT_VERSION, &GUID_Effect);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::SetParameters

IDirectInputEffect::SetParameters メソッドは、エフェクトの特性を設定する。

HRESULT SetParameters(
  LPCDIEFFECT peff,
  DWORD dwFlags
);

パラメータ

peff
エフェクトの情報を格納する DIEFFECT 構造体。dwFlags パラメータの対応ビットによって指定されている任意のメンバと同様、このメソッドを呼び出す前にアプリケーションによって dwSize メンバが設定されていなければならない。
dwFlags
エフェクトの情報のどの部分を設定するかを指定し、パラメータのダウンロード処理の方法を指定するフラグ。ゼロまたは次のフラグを取ることができる。
DIEP_AXES
cAxes および rgdwAxes メンバがデータを格納する。
DIEP_DIRECTION
cAxes および rglDirection メンバがデータを格納する。dwFlags メンバが (DIEFF_CARTESIAN または DIEFF_POLAR を使用して) 値を解釈すべき座標系を指定する。
DIEP_DURATION
dwDuration メンバがデータを格納する。
DIEP_ENVELOPE
lpEnvelope メンバは、データを格納する DIENVELOPE 構造体を指す。エフェクトから既存のエンベロープを切り離すには、このフラグを渡し、lpEnvelope メンバ を NULL に設定する。
DIEP_GAIN
dwGain メンバがデータを格納する。
DIEP_NODOWNLOAD
パラメータの更新後、通常は自動実行される IDirectInputEffect::Download を抑制する。「注意」を参照すること。
DIEP_NORESTART
エフェクトの停止や再開を抑制してパラメータを変更する。「注意」を参照すること。
DIEP_SAMPLEPERIOD
dwSamplePeriod メンバがデータを格納する。
DIEP_START
パラメータの更新後、エフェクトを開始 (エフェクトが再生中であれば、再開) させる。デフォルトでは、エフェクトの再生状態は変更されない。
DIEP_STARTDELAY
dwTriggerButton メンバがデータを格納する。
DIEP_TRIGGERBUTTON
dwTriggerButton メンバがデータを格納する。
DIEP_TRIGGERDELAY
dwTriggerDelay メンバがデータを格納する。
DIEP_TRIGGERREPEATINTERVAL
dwTriggerRepeatInterval メンバがデータを格納する。
DIEP_TYPESPECIFICPARAMS
DIEFFECT 構造体の lpTypeSpecificParams および cbTypeSpecificParams メンバがエフェクトのタイプ固有データのアドレスとサイズを格納する。

戻り値

成功すれば次の値のいずれかを返す。

DI_OK
DI_EFFECTRESTARTED
DI_DOWNLOADSKIPPED
DI_TRUNCATED
DI_TRUNCATEDANDRESTARTED

失敗すれば次のエラー値のいずれかを返す。

DIERR_NOTINITIALIZED
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

注意

エフェクト用の DIEFFECTINFO 構造体の dwDynamicParams メンバは、エフェクトの再生中に動的に更新できるパラメータを指定する。

IDirectInputEffect::SetParameters メソッドは、自動的にエフェクトをダウンロードするが、この動作は、DIEP_NODOWNLOAD フラグを設定することによって抑制できる。自動ダウンロードが抑制されていれば、IDirectInputEffect::Download メソッドを起動して、エフェクトを手動でダウンロードすることができる。

エフェクトの再生中にパラメータが更新されると、エフェクトの開始時のパラメータであったかのように、新しいパラメータが有効になる。

たとえば、3 秒の継続時間を持つ周期的エフェクトが開始されていて、2 秒後に、エフェクトの方向が変更されるとする。その後、残りの 1 秒のエフェクトは、新しい方向で継続される。エンベロープ、フェーズ、振幅などのエフェクトのパラメータは、方向が変更されなかったかのように続行される。

先の例と同じ状況で、今度は 2 秒後にエフェクトの継続時間が 1.5 秒に変更されたとすると、エフェクトは停止する。

通常、ドライバが再生中のエフェクトのパラメータを更新できない場合、ドライバはそのエフェクトを停止し、パラメータを更新してからそのエフェクトを再開することができる。DIEP_NORESTART フラグを渡すと、この処理が抑制される。エフェクトの再生中にドライバがエフェクトのパラメータを更新できないときは、エラー コードの DIERR_EFFECTPLAYING が返され、パラメータは更新されない。

フラグ DIEP_NODOWNLOAD、DIEP_START、DIEP_NORESTART のうち 2 つ以上を設定してはいけない (何も渡さなくてもよい)。

この 3 つのフラグは、次に示すように、ダウンロード処理とプレイバック処理を制御する。

DIEP_NODOWNLOAD を設定すると、エフェクト パラメータは更新されるが、デバイスにダウンロードはされない。

DIEP_START フラグを設定すると、エフェクト パラメータは更新され、デバイスにダウンロードされる。そして、IDirectInputEffect::Start メソッドが dwIterations パラメータに 1 を設定し、フラグなしで呼び出された場合とまったく同じように、エフェクトが始動する。DIEP_START で更新処理を付加した方法の方が Start メソッドを呼び出す方法よりも少し高速である。これは前者の方法では、デバイスに送信する情報が少なくて済むためである。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生していないときは、パラメータは更新され、デバイスにダウンロードされる。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生中のときは、デバイスが実行中 (オンザフライ) 更新をサポートしていれば、パラメータは更新される。上記以外の場合、処理は DIEP_NORESTART フラグの状態に左右される。このフラグが設定されていれば、エラー コード DIERR_EFFECTPLAYING が返される。このフラグが設定されていなければ、エフェクトは停止し、パラメータが更新され、エフェクトが再開する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::Start

IDirectInputEffect::Start メソッドは、エフェクトの再生を開始する。エフェクトが既に再生中ならば、最初から開始される。エフェクトがダウンロードされていないか、または前回のダウンロード以来、変更されている場合は、開始前にエフェクトがダウンロードされる。この処理はデフォルトで行われる。これを抑制するには、DIES_NODOWNLOAD フラグを渡せばよい。

HRESULT Start(
  DWORD dwIterations,
  DWORD dwFlags
);

パラメータ

dwIterations
連続してエフェクトを再生する回数。エンベロープは、反復ごとに再調整される。

エフェクトを一度だけ再生するには、1 を渡す。明示的に停止させられるまで反復再生するには、INFINITE を渡す。エンベロープを再調整しないで、明示的に停止させられるまでエフェクトを再生するには、IDirectInputEffect::SetParameters メソッドを使用してエフェクト パラメータを修正した後、その dwDuration メンバを INFINITE に変更する。

dwFlags
デバイスがエフェクトをどのように再生するかを表すフラグ。値はゼロまたは次のフラグのいずれかを指定する。
DIES_SOLO
指定されたエフェクトが再生される前に、デバイス上のほかのすべてのエフェクトを停止する。このフラグを省略すると、エフェクトは、デバイス上で既に再生が始まっている既存のエフェクトと混合されることになる。
DIES_NODOWNLOAD
エフェクトの自動ダウンロードを行わない。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_INCOMPLETEEFFECT
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

複数回の繰り返しをサポートしないデバイスもある。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::Stop

IDirectInputEffect::Stop メソッドは、エフェクトの再生を停止する。

HRESULT Stop(void);

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


IDirectInputEffect::Unload

IDirectInputEffect::Unload メソッドは、デバイスからエフェクトを削除する。エフェクトが再生されている場合、エフェクトは、アンロードされる前に自動的に停止する。

HRESULT Unload(void);

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


関数

ここでは、COM インターフェイス メソッド以外の DirectInput 関数およびコールバック関数のリファレンスを提供する。

このカテゴリには次の関数が分類される。

  • DirectInputCreate は、DirectInput システムを作成し、IDirectInput インターフェイスを取得するのに使用される。この関数は引き続きサポートされるが、DirectInputCreateEx に引き継がれている。
  • DirectInputCreateEx は、DirectInput システムを作成し、IDirectInput,、IDirectInput2、または IDirectInput7 インターフェイスを取得するのに使用される。


DirectInputCreate

DirectInputCreate 関数は、IDirectInput COM インターフェイスをサポートする DirectInput オブジェクトを作成する。

HRESULT WINAPI DirectInputCreate(
  HINSTANCE hinst,
  DWORD dwVersion,
  LPDIRECTINPUT * lplpDirectInput,
  LPUNKNOWN punkOuter
);

パラメータ

hinst
DirectInput オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドル。DirectInput は、この値を使用して、アプリケーションまたは DLL が、オブジェクト作成の資格を認められているかどうかを判断し、下位互換性のためにとるべき特別な動作を確定する。

DLL が親のアプリケーションのハンドルを渡すと、エラーとなる。たとえば、Web ページに埋め込まれている DirectInput を使用する ActiveX コントロールは、Web ブラウザのハンドルではなく、それ自身のインスタンスのハンドルを渡さなければならない。これにより、DirectInput がそのコントロールを認識し、必要と思われる特別な動作をすべて有効にすることが確実になる。

dwVersion
アプリケーションの設計対象である DirectInput のバージョン番号。この値は通常、DIRECTINPUT_VERSION である。以前のバージョン番号を渡すと、DirectInput がそのバージョンをエミュレートすることになる。詳細については、「前のバージョンの DirectInput の設計」を参照すること。
lplpDirectInput
呼び出しが成功した場合に IDirectInput インターフェイス ポインタを受け取る変数のアドレス。
punkOuter
COM 集合化に対する制御オブジェクトの IUnknown インターフェイスのアドレスへのポインタ。インターフェイスが集合化されていない場合には NULL。普通、呼び出し側は NULL を渡す。集合化が要求された場合、*lplpDirectInput に返されるオブジェクトは、COM 集合化が要求するように、IDirectInput インターフェイスではなく IUnknown へのポインタである。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_BETADIRECTINPUTVERSION
DIERR_INVALIDPARAM
DIERR_OLDDIRECTINPUTVERSION
DIERR_OUTOFMEMORY

注意

この関数は、DirectInputCreateEx に引き継がれている。新しい関数は、DirectInput オブジェクトの既存のインターフェイスを取得できる。新しい関数を使って、より機能の豊富な IDirectInput7 インターフェイスを取得することを推奨する。

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 を適切な文字セットにマップする。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


DirectInputCreateEx

DirectInputCreateEx 関数は、IDirectInput、IDirectInput2、または IDirectInput7 COM インターフェイスをサポートする DirectInput オブジェクトを作成する。

HRESULT WINAPI DirectInputCreateEx(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFIID riidltf,
  LPVOID * ppvOut,
  LPUNKNOWN punkOuter
);

パラメータ

詳細については、「前のバージョンの DirectInput の設計」を参照すること。
riidltf
目的の DirectInput インターフェイスの一意な識別子。サポートされる値は、IID_IDirectInput、IID_IDirectInput2、および IID_IDirectInput7 である。コンパイル時に UNICODE が定義されている場合、インターフェイスの Unicode 版が返される。それ以外の場合は、ANSI 版のインターフェイスが返される。
ppvOut
コールの成功時にインターフェイス ポインタを受け取る変数のアドレス。
punkOuter
COM 集合化に対する制御オブジェクトの IUnknown インターフェイスのアドレスへのポインタ。インターフェイスが集合化されていない場合には NULL。普通、呼び出し側は NULL を渡す。集合化が要求された場合、*ppvOut に返されるオブジェクトは、COM 集合化が要求するように、IDirectInput インターフェイスではなく IUnknown へのポインタである。

戻り値

成功すれば DI_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DIERR_BETADIRECTINPUTVERSION
DIERR_INVALIDPARAM
DIERR_OLDDIRECTINPUTVERSION
DIERR_OUTOFMEMORY

注意

punkOuter = NULL を指定してこの関数を呼び出すことは、CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput7W, lplpDirectInput) を使用してオブジェクトを作成した後、IDirectInput7::Initialize で初期化することと同等である。

punkOuter != NULL を指定してこの関数を呼び出すことは、CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInput) を使用してオブジェクトを作成することと同等である。集合化したオブジェクトは手動で初期化しなければならない。

このサービスは、ANSI と Unicode のバージョンに分かれている。ANSI バージョンは、IDirectInputA インターフェイスをサポートするオブジェクトを作成し、Unicode バージョンは IDirectInputW インターフェイスをサポートするオブジェクトを作成する。文字セットの問題に敏感な他のシステム サービスと同様に、ヘッダー ファイル内のマクロは、DirectInputCreateEx を適切な文字セットにマップする。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput.lib を使用。


コールバック関数

次の 4 つの関数は、プロトタイプのコールバック関数であり、さまざまな列挙メソッドと共に使用する。アプリケーションではこれらのコールバック関数の 1 つを宣言できる。その際、関数の名前、定義方法は任意でよいが、パラメータのタイプと戻り値のタイプは、プロトタイプ内で同じでなくてはならない。

  • DIEnumCreatedEffectObjectsCallback
  • DIEnumDeviceObjectsCallback
  • DIEnumDevicesCallback
  • DIEnumEffectsCallback
  • DIEnumEffectsInFileCallback


DIEnumCreatedEffectObjectsCallback

DIEnumCreatedEffectObjectsCallback 関数は、IDirectInputDevice7::EnumCreatedEffectObjects メソッドに対する呼び出し結果として DirectInputDevice エフェクトを受け取る、アプリケーション定義コールバック関数である。

BOOL CALLBACK DIEnumCreatedEffectObjectsCallback(
  LPDIRECTINPUTEFFECT peff,
  LPVOID pvRef
);

パラメータ

peff
作成されたエフェクト オブジェクトへのポインタ。
pvRef
IDirectInputDevice7::EnumCreatedEffectObjects メソッドで指定されるアプリケーション定義値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


DIEnumDeviceObjectsCallback

DIEnumDeviceObjectsCallback 関数は、IDirectInputDevice7::EnumObjects メソッドに対する呼び出し結果として DirectInputDevice オブジェクトを受け取る、アプリケーション定義コールバック関数である。

BOOL CALLBACK DIEnumDeviceObjectsCallback(
  LPCDIDEVICEOBJECTINSTANCE lpddoi,
  LPVOID pvRef
);

パラメータ

lpddoi
列挙対象のオブジェクトを記述する DIDEVICEOBJECTINSTANCE 構造体。
pvRef
EnumObjects メソッドで指定されるアプリケーション定義値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


DIEnumDevicesCallback

DIEnumDevicesCallback 関数は、IDirectInput7::EnumDevices メソッドに対する呼び出し結果として DirectInput デバイスを受け取る、アプリケーション定義コールバック関数である。

BOOL CALLBACK DIEnumDevicesCallback(
  LPCDIDEVICEINSTANCE lpddi,
  LPVOID pvRef
);

パラメータ

lpddi
デバイス インスタンスを記述する DIDEVICEINSTANCE 構造体のアドレス。
pvRef
EnumDevices メソッドで指定されるアプリケーション定義値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


DIEnumEffectsCallback

DIEnumEffectsCallback 関数は、IDirectInputDevice7::EnumEffects メソッドと共に使用するアプリケーション定義コールバック関数である。

BOOL CALLBACK DIEnumEffectsCallback(
  LPCDIEFFECTINFO pdei,
  LPVOID pvRef
);

パラメータ

pdei
列挙されたエフェクトを記述する DIEFFECTINFO 構造体。
pvRef
EnumEffects メソッドで指定されるアプリケーション定義データのアドレス。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


DIEnumEffectsInFileCallback

DIEnumEffectsInFileCallback 関数は、IDirectInputDevice7::EnumEffectsInFile メソッドと共に使用するアプリケーション定義コールバック関数である。

BOOL CALLBACK DIEnumEffectsInFileCallback(
  LPCDIFILEEFFECT lpDiFileEf,
  LPVOID pvRef
);

パラメータ

lpDiFileEf
列挙されたエフェクトを記述する DIFILEEFFECT 構造体。
pvRef
EnumEffectsInFile メソッドで指定されるアプリケーション定義データのアドレス。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


マクロ

ここでは、DirectInput で使用されている以下のマクロを説明する。

  • DIDFT_GETINSTANCE
  • DIDFT_GETTYPE
  • DIDFT_MAKEINSTANCE
  • DIEFT_GETTYPE
  • DIMAKEUSAGEDWORD
  • DISEQUENCE_COMPARE
  • GET_DIDEVICE_SUBTYPE
  • GET_DIDEVICE_TYPE

Dinput.h は、IDirectInput および IDirectInputDevice 両インターフェイスのすべてのメソッドに対する C の呼び出しのマクロも定義する。これらのマクロを使うことで、メソッド テーブルへのポインタが不要になる。たとえば、以下は、IDirectInputDevice7::Release メソッドに対する C による呼び出しの例である。

lpdid->lpVtbl->Release(lpdid));

同等のマクロ呼び出しは、以下のような形式になる。

IDirectInputDevice7_Release(lpdid);

これらのマクロはすべて、メソッド呼び出しの場合と同一のパラメータを取る。


DIDFT_GETINSTANCE

DIDFT_GETINSTANCE マクロは、データ形式タイプからオブジェクトのインスタンス番号コードを抽出する。

DIDFT_GETINSTANCE(n) LOWORD((n) >> 8)

パラメータ

n
DirectInput データ形式タイプ。このパラメータが取ることができる値は、DIOBJECTDATAFORMAT 構造体の dwType メンバの値と同じである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

DIDFT_MAKEINSTANCE、DIDFT_GETTYPE


DIDFT_GETTYPE

DIDFT_GETTYPE マクロは、データ形式タイプからオブジェクト タイプ コードを抽出する。

DIDFT_GETTYPE(n)  LOBYTE(n)

パラメータ

n
DirectInput データ形式タイプ。このパラメータが取ることができる値は、DIOBJECTDATAFORMAT 構造体の dwType メンバの値と同じである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

DIDFT_GETINSTANCE


DIDFT_MAKEINSTANCE

DIDFT_MAKEINSTANCE マクロは、デバイス オブジェクトのインスタンス識別子を作成して、DIOBJECTDATAFORMAT 構造体の dwType メンバの中に含める。

DIDFT_MAKEINSTANCE(n) ((WORD)(n) << 8)

パラメータ

n
オブジェクトのインスタンス。たとえば、マウスのボタン 1 の場合は 1。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

DIDFT_GETINSTANCE


DIEFT_GETTYPE

DIDFT_GETTYPE マクロは、データ形式タイプからオブジェクト タイプ コードを抽出する。

DIEFT_GETTYPE(n)  LOBYTE(n)

パラメータ

n
DirectInput エフェクト形式タイプ。このパラメータが取ることができる値は、DIEFFECTINFO 構造体の dwEffType メンバの値と同じである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIMAKEUSAGEDWORD

DIMAKEUSAGEDWORD マクロは、デバイス オブジェクトに対するHID コードの "使用ページ" と "使用状況" を組み合わせて、IDirectInputDevice7::GetObjectInfo メソッドに渡す。

DWORD DIMAKEUSAGEDWORD(
  WORD UsagePage,
  WORD Usage
);

パラメータ

UsagePage
デバイス オブジェクトの使用ページ。
Usage
デバイス オブジェクトの使用状況。

注意

このマクロは、Dinput.h 内で次のように宣言される。

#define DIMAKEUSAGEDWORD(UsagePage, Usage) \
((DWORD)MAKELONG(Usage, UsagePage))

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Requires Windows 98.
Header:dinput.h で宣言。


DISEQUENCE_COMPARE

DISEQUENCE_COMPARE マクロは、2 つの DirectInput シーケンス番号を比較して、シーケンス番号の循環を補正する。

DISEQUENCE_COMPARE(dwSequence1, cmp, dwSequence2) \
                ((int)((dwSequence1) - (dwSequence2)) cmp 0)

パラメータ

dwSequence1
比較する第 1 シーケンス番号。
cmp
比較演算子 (==、!=、<、>、<=、>=) のいずれか 1 つ。
dwSequence2
比較する第 2 シーケンス番号。

戻り値

cmp パラメータに指定され比較結果が真の場合はゼロ以外を返し、偽の場合はゼロを返す。

注意

以下の例は、dwSequence1 パラメータ値が、時間的に dwSequence2 パラメータ値に先行するかどうかをチェックする。

BOOL Sooner = (DISEQUENCE_COMPARE(dwSequence1, <, dwSequence2));

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


GET_DIDEVICE_SUBTYPE

GET_DIDEVICE_SUBTYPE マクロは、デバイス タイプ記述コードからデバイス サブタイプ コードを抽出する。

GET_DIDEVICE_SUBTYPE(dwDevType)  HIBYTE(dwDevType)

パラメータ

dwDevType
DirectInput デバイス タイプ記述コード。このパラメータが取ることができる値は、DIDEVICEINSTANCE 構造体の dwDevType メンバの値と同じである。

注意

サブタイプ コードの解釈は、プライマリ タイプによって変わる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

GET_DIDEVICE_TYPE、DIDEVICEINSTANCE


GET_DIDEVICE_TYPE

GET_DIDEVICE_TYPE マクロは、デバイス タイプ記述コードからデバイスのプライマリ タイプ コードを抽出する。

GET_DIDEVICE_TYPE(dwDevType)  LOBYTE(dwDevType)

パラメータ

dwDevType
DirectInput デバイス タイプ記述コード。このパラメータが取ることができる値は、DIDEVICEINSTANCE 構造体の dwDevType メンバの値と同じである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

GET_DIDEVICE_SUBTYPE、DIDEVICEINSTANCE


構造体

ここでは、以下の DirectInput 構造体を説明する。

  • DICONDITION
  • DICONSTANTFORCE
  • DICUSTOMFORCE
  • DIDATAFORMAT
  • DIDEVCAPS
  • DIDEVICEINSTANCE
  • DIDEVICEOBJECTDATA
  • DIDEVICEOBJECTINSTANCE
  • DIEFFECT
  • DIEFFECTINFO
  • DIEFFESCAPE
  • DIENVELOPE
  • DIFILEEFFECT
  • DIJOYSTATE
  • DIJOYSTATE2
  • DIMOUSESTATE
  • DIMOUSESTATE2
  • DIOBJECTDATAFORMAT
  • DIPERIODIC
  • DIPROPDWORD
  • DIPROPGUIDANDPATH
  • DIPROPHEADER
  • DIPROPRANGE
  • DIPROPSTRING
  • DIRAMPFORCE

注 : 使用前にすべての DirectX 構造体のメモリは、ゼロに初期化されなければならない。また、dwSize メンバを含むすべての構造体は、使用前に dwSize メンバをその構造体のサイズに設定する必要がある。次の例は、DIDEVCAPS 構造体の動作を説明している。

DIDEVCAPS didevcaps; // これはまだ使用できない。

ZeroMemory(&didevcaps, sizeof(didevcaps));
didevcaps.dwSize = sizeof(didevcaps);

// これで構造体を使うことができる。
.
.


DICONDITION

DICONDITION 構造体は、DIEFT_CONDITION としてマークされているエフェクトのタイプ固有の情報を格納する。

あるエフェクトに関する DICONDITION 構造体の配列へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。配列の要素数は、エフェクトに関係付けられた軸の数に等しくなければならない。

typedef struct DICONDITION {
    LONG lOffset;
    LONG lPositiveCoefficient;
    LONG lNegativeCoefficient;
    DWORD dwPositiveSaturation;
    DWORD dwNegativeSaturation;
    LONG lDeadBand;
} DICONDITION, *LPDICONDITION;

typedef const DICONDITION *LPCDICONDITION;

メンバ

lOffset
-10,000 ～ 10.000 の範囲にある、条件のオフセット。
lPositiveCoefficient
-10,000 ～ 10.000 の範囲にある、オフセットの正側の係数定数。
lNegativeCoefficient
-10,000 ～ 10.000 の範囲にある、オフセットの負側の係数定数。

デバイスが正と負に分かれた係数をサポートしていない場合、lNegativeCoefficient 値は無視され、lPositiveCoefficient 値が正負両方の係数として使用される。

dwPositiveSaturation
0 ～ 10,000 の範囲にある、オフセットの正側の最大フォース出力。

デバイスがフォースの飽和をサポートしない場合、このメンバ値は無視される。

dwNegativeSaturation
0 ～ 10,000 の範囲にある、オフセットの負側の最大フォース出力。

デバイスがフォースの飽和値をサポートしない場合、このメンバ値は無視される。

デバイスが正と負に分かれた飽和値をサポートしていない場合、dwNegativeSaturation 値は無視され、dwPositiveSaturation 値が正負両方の飽和値として使用される。

lDeadBand
0 ～ 10,000 の範囲にある、条件がアクティブでない lOffset 周辺の領域。すなわち、lOffset - lDeadBand と lOffset + lDeadBand の間では、条件はアクティブではない。

注意

条件のタイプが異なれば、パラメータの意味も異なるが、基本的な考え方は、条件に起因するフォースは、A(q - q0) に等しくなるということである。ここで、A は、スケーリング係数、q はある距離であり、q0 は、その距離に対する中立値である。

上記の単純な式は、デッドバンドのゼロ以外の値が指定された場合は調整しなければならない。距離が lOffset - lDeadBand より小さければ、生成されるフォースは、次の式で示される。

force = lNegativeCoefficient * (q - (lOffset - lDeadBand))

同様に、距離が lOffset + lDeadBand より大きければ、生成されるフォースは、次の式で示される。

force = lPositiveCoefficient * (q - (lOffset + lDeadBand))

スプリング条件は、軸の位置を距離として使用する。

ダンパ条件は、軸の速度を距離として使用する。

慣性条件は、軸の加速度を距離として使用する。

配列に含まれる DICONDITION 構造体の数が、エフェクトに対する軸の数と等しい場合、第 1 の構造体は第 1 の軸に適用され、第 2 の構造体は第 2 の軸に適用される。それ以降も同様の対応関係を保つ。たとえば、2 軸のスプリング条件で、両方の DICONDITION 構造体で lOffset がゼロに設定されていれば、ジョイスティックの自動センタリング スプリングと同じエフェクトが得られる。このように、1 つの条件がそれぞれの軸に対して定義されている場合、エフェクトは回転しない。

2 つ以上の軸を持つエフェクトに対して DICONDITION 構造体 が 1 つの場合、DICONDITION 構造体のパラメータが有効となる方向は、DIEFFECT 構造体の rglDirection フィールドに渡される方向パラメータによって決定される。たとえば、45 度 (極座標で) 回転する摩擦条件は、北東から南西への方向のジョイスティックの動きには抵抗するだろうが、北西から南東への方向のジョイスティックの動きにはなんら作用を及ぼさないだろう。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DICONSTANTFORCE

DICONSTANTFORCE 構造体は、DIEFT_CONSTANTFORCE としてマークされているエフェクトに関するタイプ固有の情報を格納する。

この構造体は、コンスタント フォース エフェクトを表す。

エフェクトに関する単一の DICONSTANTFORCE 構造体へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。

typedef struct DICONSTANTFORCE {
    LONG lMagnitude;
} DICONSTANTFORCE, *LPDICONSTANTFORCE;

typedef const DICONSTANTFORCE *LPCDICONSTANTFORCE;

メンバ

lMagnitude
-10.000 ～ 10,000 の範囲にある、エフェクトのマグニチュード。エンベロープがこのエフェクトに適用されていれば、この値は、維持期間のマグニチュードを表す。エンベロープの適用がなければ、この値は、エフェクト全体の振幅を表す。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DICUSTOMFORCE

DICUSTOMFORCE 構造体は、DIEFT_CUSTOMFORCE としてマークされているエフェクトに関するタイプ固有の情報を格納する。

この構造体は、カスタムまたはユーザー定義フォースを表す。

エフェクトの DICUSTOMFORCE 構造体へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。

typedef struct DICUSTOMFORCE {
    DWORD cChannels;
    DWORD dwSamplePeriod;
    DWORD cSamples;
    LPLONG rglForceData;
} DICUSTOMFORCE, *LPDICUSTOMFORCE;

typedef const DICUSTOMFORCE *LPCDICUSTOMFORCE;

メンバ

cChannels
このフォースによって影響されるチャネル (軸) の数。

1 番目のチャネルが、エフェクトに関連付けられた 1 番目の軸に適用され、2 番目のチャネルが 2 番目の軸に適用されるというように続く。軸よりもチャネルの数が少なければ、余分な軸に対する関連付けは行われない。

チャネルが 1 つしか存在しなければ、エフェクトは、DIEFFECT 構造体の rglDirection メンバが指定する方向に回転する。複数のチャネルがあると、回転できない。

カスタム エフェクトの回転をサポートしていないデバイスもある。

dwSamplePeriod
マイクロ秒単位のサンプリング間隔。
cSamples
rglForceData 内のサンプルの合計数。cChannels の整数倍でなければならない。
rglForceData
カスタム フォースを表すフォース値の配列へのポインタ。複数のチャネルが指定されていれば、値は、順番に割り当てられる。たとえば、cChannels が 3 の場合には、配列の 1 番目の要素は 1 番目のチャネルに、2 番目の要素は 2 番目のチャネルに、3 番目の要素は 3 番目のチャネルにそれぞれ属する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIDATAFORMAT

DIDATAFORMAT 構造体は、デバイスのデータ形式を記述する情報を格納する。この構造体は、IDirectInputDevice7::SetDataFormat メソッドで使用する。

typedef struct DIDATAFORMAT {
    DWORD dwSize;
    DWORD dwObjSize;
    DWORD dwFlags;
    DWORD dwDataSize;
    DWORD dwNumObjs;
    LPDIOBJECTDATAFORMAT rgodf;
} DIDATAFORMAT, *LPDIDATAFORMAT;

typedef const DIDATAFORMAT *LPCDIDATAFORMAT;

メンバ

dwSize
この構造体のバイト単位のサイズ。
dwObjSize
DIOBJECTDATAFORMAT 構造体のバイト単位のサイズ。
dwFlags
データ形式のほかの属性を表すフラグ。この値は、次のいずれか 1 つである。
DIDF_ABSAXIS
軸は絶対モードにある。データ形式にこのフラグを設定することは、IDirectInputDevice7::SetProperty メソッドを使用して軸モード プロパティを手動で設定することに等しい。この値は、DIDF_RELAXIS フラグと組み合わせることはできない。
DIDF_RELAXIS
軸は相対モードにある。データ形式にこのフラグを設定することは、IDirectInputDevice7::SetProperty メソッドを使用して軸モード プロパティを手動で設定することに等しい。この値は、DIDF_ABSAXIS フラグと組み合わせることはできない。
dwDataSize
デバイスが返すデータ パケットのバイト単位のサイズ。この値は、4 の倍数、かつデータ パケット内のオブジェクト データの最大オフセット値より大きくなければならない。
dwNumObjs
rgodf 配列中のオブジェクト数。
rgodf
DIOBJECTDATAFORMAT 構造体の配列のアドレス。各構造体は、1 つのオブジェクト データがデバイス データの中でどのように報告されるのかを記述する。典型的なエラーとしては、2 種類の情報を同じ位置に格納したり、1 種類の情報を複数の位置に格納したりするものがある。

注意

アプリケーションは、通常、DIDATAFORMAT 構造体を作成する必要はない。アプリケーションは、事前定義されたグローバル データ形式変数の c_dfDIMouse、c_dfDIMouse2、c_dfDIKeyboard、c_dfDIJoystick、c_dfDIJoystick2 のいずれかを使用できるからである。

以下の例では、2 つの軸 (絶対座標で報告される) と 2 つのボタンを必要とするアプリケーションが使用できるデータ形式を設定している。

// アプリケーションが次の構造体を使って、
// デバイス データを読み取ると仮定する。

typedef struct MYDATA {
LONG lX;          // x 軸がここにくる。
LONG lY;          // y 軸がここにくる。
BYTE bButtonA;       // 1 つのボタンがここにくる。
BYTE bButtonB;       // 別のボタンがここにくる。
BYTE bPadding[2];     // サイズは、DWORD の倍数でなければならない。
} MYDATA;

// 次のデータ形式を使用できる。

DIOBJECTDATAFORMAT rgodf[ ] = {
{ &GUID_XAxis, FIELD_OFFSET(MYDATA, lX),
DIDFT_AXIS | DIDFT_ANYINSTANCE, 0, },
{ &GUID_YAxis, FIELD_OFFSET(MYDATA, lY),
DIDFT_AXIS | DIDFT_ANYINSTANCE, 0, },
{ &GUID_Button, FIELD_OFFSET(MYDATA, bButtonA),
DIDFT_BUTTON | DIDFT_ANYINSTANCE, 0, },
{ &GUID_Button, FIELD_OFFSET(MYDATA, bButtonB),
DIDFT_BUTTON | DIDFT_ANYINSTANCE, 0, },
};
#define numObjects (sizeof(rgodf) / sizeof(rgodf[0]))

DIDATAFORMAT df = {
sizeof(DIDATAFORMAT),    // この構造体
sizeof(DIOBJECTDATAFORMAT), // オブジェクト データ形式のサイズ
DIDF_ABSAXIS,        // 絶対軸の座標
sizeof(MYDATA),       // デバイス データのサイズ
numObjects,         // オブジェクト数
rgodf,           // その位置
};

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIDEVCAPS

DIDEVCAPS 構造体は、DirectInput デバイスの能力に関する情報を格納する。この構造体は、IDirectInputDevice7::GetCapabilities メソッドで使用される。

typedef struct DIDEVCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwDevType;
    DWORD dwAxes;
    DWORD dwButtons;
    DWORD dwPOVs;
    DWORD dwFFSamplePeriod;
    DWORD dwFFMinTimeResolution;
    DWORD dwFirmwareRevision;
    DWORD dwHardwareRevision;
    DWORD dwFFDriverVersion;
} DIDEVCAPS, *LPDIDEVCAPS;

メンバ

dwSize
この構造体のバイト単位のサイズ。IDirectInputDevice7::GetCapabilities メソッドに呼び出す前に、アプリケーションは、このメンバを初期化しておかなければならない。
dwFlags
デバイスに関連付けられたフラグ。この値は、以下の定数の組み合わせとなる。
DIDC_ALIAS
デバイスは、別の DirectInput デバイスの複製である。別名のデバイスは、デフォルトでは IDirectInput7::EnumDevices によって列挙されない。
DIDC_PHANTOM
このデバイスは実在しない。このデバイスは、将来提供されるかもしれないデバイスのプレースホルダである。仮想デバイスは、デフォルトでは IDirectInput7::EnumDevices によって列挙されない。
DIDC_ATTACHED
デバイスは、物理的にアタッチされている。
DIDC_DEADBAND
デバイスは、少なくとも 1 つのフォース フィードバック条件でデッドバンドをサポートしている。
DIDC_EMULATED
このフラグが設定されると、データはユーザー モード デバイス インターフェイス (HID など) から、またはほかのリング 3 の手段により入力される。フラグが設定されない場合、データはカーネル モード ドライバから直接入力される。
DIDC_FORCEFEEDBACK
デバイスは、フォース フィードバックをサポートする。
DIDC_FFFADE
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対するフェード パラメータをサポートする。デバイスがフェードをサポートしない場合、デバイスは、DIENVELOPE 構造体のフェード レベルとフェード時間の両パラメータを無視する。

IDirectInputDevice7::GetEffectInfo メソッドの呼び出し後、個別のエフェクトがフェードをサポートしていれば、DIEFT_FFFADE フラグが設定される。

DIDC_FFATTACK
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対するアタック パラメータをサポートする。デバイスがアタックをサポートしない場合、デバイスは、DIENVELOPE 構造体のアタック レベルとアタック時間の両パラメータを無視する。

IDirectInputDevice7::GetEffectInfo メソッドの呼び出し後、個別のエフェクトがアタックをサポートしていれば、DIEFT_FFATTACK フラグが設定される。

DIDC_POLLEDDATAFORMAT
現状のデータ形式で少なくとも 1 つのオブジェクトが、割り込み駆動ではなく、ポーリングされる。これらオブジェクトのために、アプリケーションは明示的に IDirectInputDevice7::Poll メソッドを呼び出して、データを取得しなければならない。
DIDC_POLLEDDEVICE
デバイス上の少なくとも 1 つのオブジェクトが、割り込み駆動ではなく、ポーリングされる。これらオブジェクトのために、アプリケーションは明示的に IDirectInputDevice7::Poll メソッドを呼び出して、データを取得しなければならない。HID デバイスは、ポーリング オブジェクトと非ポーリング オブジェクトを混在して格納できる。
DIDC_POSNEGCOEFFICIENTS
フォース フィードバック システムは、少なくとも 1 つの条件に対して条件の 2 つの係数値をサポートする (一方は、軸の正移動、他方は、軸の負移動)。デバイスが一方の係数しかサポートしていない場合、DICONDITION 構造体の負の係数は無視される。

IDirectInputDevice7::GetEffectInfo メソッドの呼び出し後、個別の条件が正と負の係数を別々にサポートしていれば、その条件は DIEFT_POSNEGCOEFFICIENTS フラグを設定する。

DIDC_POSNEGSATURATION
フォース フィードバック システムは、少なくとも 1 つの条件に対して、正負の両方のフォース出力に対する最大飽和をサポートする。デバイスが一方の飽和値しかサポートしていない場合、DICONDITION 構造体の負の飽和値は無視される。

IDirectInputDevice7::GetEffectInfo メソッドの呼び出し後、個別の条件が正と負の飽和値を別々にサポートしていれば、その条件は DIEFT_POSNEGSATURATION フラグを設定する。

DIDC_SATURATION
フォース フィードバック システムは、少なくとも 1 つの条件に対して条件エフェクトの飽和をサポートする。デバイスが飽和をサポートしていなければ、ある条件のもとで生成されるフォースは、デバイスが生成できる最大フォースによってのみ制限される。

IDirectInputDevice7::GetEffectInfo メソッドの呼び出し後、個別の条件が飽和をサポートしていれば、その条件は DIEFT_SATURATION フラグを設定する。

DIDC_STARTDELAY
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対する遅延パラメータをサポートする。デバイスが開始遅延をサポートしない場合、DIEFFECT 構造体の dwStartDelay メンバは無視される。
dwDevType
デバイス タイプ記述子。このメンバは、DIDEVICEINSTANCE 構造体の dwDevType メンバと同等な値を格納できる。
dwAxes
デバイス上で使用可能な軸の数。
dwButtons
デバイス上で使用可能なボタンの数。
dwPOVs
デバイス上で使用可能な視点コントローラの数。
dwFFSamplePeriod
未加工のフォース コマンドを連続して再生する際の間隔の最小時間。
dwFFMinTimeResolution
マイクロ秒単位のデバイスの分解能の最小時間。デバイスは、すべての時間を最も近い増加値に丸める。たとえば、dwFFMinTimeResolution の値が 1000 の場合には、デバイスはすべての時間を最も近いミリ秒に丸める。
dwFirmwareRevision
デバイスのファームウェア リビジョン番号。
dwHardwareRevision
デバイスのハードウェア リビジョン番号。
dwFFDriverVersion
デバイス ドライバのバージョン番号。

注意

バージョン番号の付け方はデバイス メーカーによって異なる。確実なのは、新しいバージョンには以前のバージョンよりも大きい数字が付く、ということだけである。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

DIDEVICEINSTANCE


DIDEVICEINSTANCE

DIDEVICEINSTANCE 構造体は、デバイスのインスタンスに関する情報を格納する。この構造体は、IDirectInput7::EnumDevices および IDirectInputDevice7::GetDeviceInfo メソッドで使用される。

typedef struct DIDEVICEINSTANCE {
    DWORD dwSize;
    GUID  guidInstance;
    GUID  guidProduct;
    DWORD dwDevType;
    TCHAR tszInstanceName[MAX_PATH];
    TCHAR tszProductName[MAX_PATH];
    GUID guidFFDriver;
    WORD wUsagePage;
    WORD wUsage;
} DIDEVICEINSTANCE, *LPDIDEVICEINSTANCE;

typedef const DIDEVICEINSTANCE  *LPCDIDEVICEINSTANCE;

メンバ

dwSize
この構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
guidInstance
デバイスのインスタンスに対する一意な識別子。アプリケーションは、このインスタンス GUID を構成ファイルに保存し、後で使用することもできる。インスタンス GUID は、コンピュータごとに固有である。1 つのコンピュータから取得されるインスタンス GUID は、ほかのコンピュータ上のインスタンス GUID とは無関係である。
guidProduct
製品の一意な識別子。この識別子は、デバイス メーカーが定める。
dwDevType
デバイス タイプ記述子。デバイス タイプ記述コードの最下位バイトは、デバイス タイプを指定する。最下位バイトから 1 つ上位のバイトは、デバイス サブタイプを指定する。この値は、以下のタイプの 1 つと、それに対応するサブタイプ、およびオプションとして DIDEVTYPE_HID を組み合わせたものとなる。DIDEVTYPE_HID は、ヒューマン インターフェイス デバイスを指定する。
デバイス タイプ
DIDEVTYPE_MOUSE
マウスまたはマウス類似デバイス (トラックボールなど)。
DIDEVTYPE_KEYBOARD
キーボードまたはキーボード類似デバイス。
DIDEVTYPE_JOYSTICK
ジョイスティックまたは類似デバイス (ステアリング ホイールなど)。
DIDEVTYPE_DEVICE
上記のカテゴリに属さないデバイス。
マウス サブタイプ
DIDEVTYPEMOUSE_UNKNOWN
サブタイプは確定できない。
DIDEVTYPEMOUSE_TRADITIONAL
デバイスは、従来のマウスである。
DIDEVTYPEMOUSE_FINGERSTICK
デバイスは、フィンガースティックである。
DIDEVTYPEMOUSE_TOUCHPAD
デバイスは、タッチパッドである。
DIDEVTYPEMOUSE_TRACKBALL
デバイスは、トラックボールである。
キーボード サブタイプ
DIDEVTYPEKEYBOARD_UNKNOWN
サブタイプは確定できない。
DIDEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 キー キーボード
DIDEVTYPEKEYBOARD_OLIVETTI
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 キーボード
ジョイスティック サブタイプ
DIDEVTYPEJOYSTICK_UNKNOWN
サブタイプは確定できない。
DIDEVTYPEJOYSTICK_TRADITIONAL
従来のジョイスティック。
DIDEVTYPEJOYSTICK_FLIGHTSTICK
フライト シミュレーション用に最適化されているジョイスティック。
DIDEVTYPEJOYSTICK_GAMEPAD
主要目的がボタン入力を行うことにあるデバイス。
DIDEVTYPEJOYSTICK_RUDDER
偏揺制御用のデバイス。
DIDEVTYPEJOYSTICK_WHEEL
車のハンドル用のデバイス。
DIDEVTYPEJOYSTICK_HEADTRACKER
ユーザーの頭の動きを追跡するデバイス。

高位ワードのフラグ

DIDEVTYPE_HID
デバイスは、HID (Human Interface Device) プロトコルを使用する。
tszInstanceName[MAX_PATH]
インスタンスの登録名。たとえば、"Joystick 1"。
tszProductName[MAX_PATH]
製品の登録名。
guidFFDriver
フォース フィードバックに使用されるドライバの一意な識別子。この識別子は、ドライバのメーカーが定める。
wUsagePage
デバイスが HID デバイスであれば、このメンバには、HID 使用ページ コードが含まれる。
wUsage
デバイスが HID デバイスであれば、このメンバには、HID 使用コードが含まれる。

注意

以前のバージョンの DirectX と互換性を持たせるため、DIDEVICEINSTANCE 構造体の最初の 6 つのメンバだけを含む DIDEVICEINSTANCE_DX3 構造体も定義される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIDEVICEOBJECTDATA

DIDEVICEOBJECTDATA 構造体は、バッファリング デバイスの未加工の情報を格納する。この構造体は、IDirectInputDevice7::GetDeviceData および IDirectInputDevice7::SendDeviceData メソッドで使用される。

typedef struct DIDEVICEOBJECTDATA {
    DWORD dwOfs;
    DWORD dwData;
    DWORD dwTimeStamp;
    DWORD dwSequence;
} DIDEVICEOBJECTDATA, *LPDIDEVICEOBJECTDATA;

typedef const DIDEVICEOBJECTDATA *LPCDIDEVICEOBJECTDATA;

メンバ

dwOfs
GetDeviceData の場合、データの報告対象となっているオブジェクトの、現在のデータ形式に対するオフセット値。すなわち、IDirectInputDevice7::GetDeviceState メソッドの呼び出しによってデータが取得された場合、その dwData が格納されている位置となる。デバイスがマウス、キーボード、またはジョイスティックとしてアクセスされる場合に、この dwOfs メンバは、マウス デバイス定数、キーボード デバイス定数、またはジョイスティック デバイス定数のいずれかになる。カスタム データ形式が設定されている場合は、カスタム データ形式に関連するオフセットになる。

SendDeviceData の場合、データの送信先であるオブジェクトのインスタンス ID。これは DIDEVICEOBJECTINSTANCE 構造体の dwType メンバから取得される。

dwData
デバイスから取得またはデバイスに送信されるデータ。

軸からの入力の場合、デバイスが相対軸モードにあれば、相対軸の動きが報告される。デバイスが絶対軸モードにあれば、絶対座標が報告される。

ボタンからの入力の場合、dwData の下位バイトだけが有意である。下位バイトの上位ビットは、ボタンがダウン状態の場合に設定され、アップ状態の場合に消去される。

dwTimeStamp
入力イベントが生成されたミリ秒単位の時間カウント。現在のシステム時間カウント (低分解能) は、Win32 GetTickCount 関数を呼び出して取得できる。なお、この値は、約 50 日で循環する。

構造体が SendDeviceData メソッドと共に使用される場合、このメンバは必ずゼロになる。

dwSequence
このイベントに対する DirectInput シーケンス番号。すべての入力イベントには、昇順のシーケンス番号が割り当てられている。これにより、異なるデバイスからのイベントを時間順にソートすることが可能になる。この値は、循環して初期値に戻るので、2 つのシーケンス番号を比較する場合には注意しなければならない。この比較を安全に行うには、DISEQUENCE_COMPARE マクロを使用すればよい。

構造体が SendDeviceData メソッドと共に使用される場合、このメンバは必ずゼロになる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIDEVICEOBJECTINSTANCE

DIDEVICEOBJECTINSTANCE 構造体は、デバイス オブジェクトのインスタンスに関する情報を格納する。この構造体は、IDirectInputDevice7::EnumObjects メソッドで使用され、DIEnumDeviceObjectsCallback コールバック関数に対して、軸またはボタンなど、デバイスに関連付けられた特定のオブジェクトについての情報を提供する。また、デバイス オブジェクトの情報を取得するために、IDirectInputDevice7::GetObjectInfo メソッドでも使用される。

typedef struct DIDEVICEOBJECTINSTANCE {
    DWORD dwSize;
    GUID  guidType;
    DWORD dwOfs;
    DWORD dwType;
    DWORD dwFlags;
    TCHAR tszName[MAX_PATH];
    DWORD dwFFMaxForce;
    DWORD dwFFForceResolution;
    WORD  wCollectionNumber;
    WORD  wDesignatorIndex;
    WORD  wUsagePage;
    WORD  wUsage;
    DWORD dwDimension;
    WORD  wExponent;
    WORD  wReportId;
} DIDEVICEOBJECTINSTANCE, *LPDIDEVICEOBJECTINSTANCE;

typedef const DIDEVICEOBJECTINSTANCE *LPCDIDEVICEOBJECTINSTANCE;

メンバ

dwSize
この構造体のバイト単位のサイズ。列挙の間に、アプリケーションはこの値を調べ、構造体のメンバがいくつ有効であるかを確認できる。構造体が IDirectInputDevice7::GetObjectInfo メソッドに渡されるとき、このメンバを sizeof(DIDEVICEOBJECTINSTANCE) に初期化しなければならない。
guidType
オブジェクト タイプを示す一意な識別子。このメンバはオプションである。次のいずれか 1 つの値を取ることができる。
GUID_XAxis
水平軸。たとえば、マウスの左右の動きを表すことができる。
GUID_YAxis
垂直軸。たとえば、マウスの前後の動きを表すことができる。
GUID_ZAxis
z 軸。たとえば、マウス上のホイールの回転、またはジョイスティックのスロットル制御の移動を表すことができる。
GUID_RxAxis
x 軸を中心とする回転。
GUID_RyAxis
y 軸を中心とする回転。
GUID_RzAxis
z 軸を中心とする回転 (方向舵のコントロールでよく使われる)。
GUID_Slider
スライド軸。
GUID_Button
マウスのボタン。
GUID_Key
キーボード上のキー。
GUID_POV
視点インジケータ
GUID_Unknown
確定できない。

将来、これ以外のオブジェクト タイプも定義される可能性がある。

dwOfs
データ形式内のオフセットで、このオブジェクトに報告されるデータの位置。この値は、メソッド呼び出しにおけるオブジェクトと DIPH_BYOFFSET フラグを受け取る構造体の中のオブジェクトを識別するために使用される。
dwType
オブジェクトを表すデバイス タイプ。オブジェクト タイプ (軸、ボタンなど) を表す DIDFT_* フラグの組み合わせであり、中央の 16 ビットには、オブジェクト インスタンス番号が格納される。オブジェクト インスタンス番号を抽出するには、DIDFT_GETINSTANCE マクロを使用する。DIDFT_* フラグについては、IDirectInputDevice7::EnumObjects を参照すること。
dwFlags
データ形式のほかの属性を表すフラグ。この値は、次のいずれか 1 つである。
DIDOI_ASPECTACCEL
オブジェクトは加速度情報を報告する。
DIDOI_ASPECTFORCE
オブジェクトはフォース情報を報告する。
DIDOI_ASPECTMASK
アスペクト情報を報告するためのビット。1 つのオブジェクトは最大 1 つのアスペクトしか表すことができない。
DIDOI_ASPECTPOSITION
オブジェクトは位置情報を報告する。
DIDOI_ASPECTVELOCITY
オブジェクトは速度情報を報告する。
DIDOI_FFACTUATOR
オブジェクトは、フォース フィードバック エフェクトを自身に適用させることができる。
DIDOI_FFEFFECTTRIGGER
オブジェクトは、フォース フィードバック エフェクトの再生をトリガする。
DIDOI_GUIDISUSAGE
DIOBJECTDATAFORMAT 構造体の pguid メンバは、実際には目的の使用ページおよび使用状況を組み合わせ、適切にキャストされた DIMAKEUSAGEDWORD である。
DIDOI_POLLED
IDirectInputDevice7::Poll メソッドが呼び出されるまで、オブジェクトはデータを返さない。
tszName[MAX_PATH]
オブジェクトの名前。たとえば、"X-Axis" または "Right Shift" など。
dwFFMaxForce
このオブジェクトに関連付けられたアクチュエータが作り出せる最大フォースのマグニチュード。フォースは、ニュートン単位で表現され、デバイスを通常に操作している間の手の位置との関連で測定される。
dwFFForceResolution
このオブジェクトに関連付けられたアクチュエータのフォース分解能。戻り値は、フォース フィードバック システムが 0 (フォースなし) から最大フォースの範囲で表現できるフォースの段階数または下位区分の数を表す。
wCollectionNumber
オブジェクトが属する HID リンク コレクション。
wDesignatorIndex
HID 物理記述子の指定を参照するインデックス。この数値は、デバイス オブジェクトについての追加情報を含む HID 解釈ライブラリ (Hidpi.h) の関数に渡される。
wUsagePage
オブジェクトに関連する HID 使用ページ (判明した場合)。ヒューマン インターフェイス デバイスは常に使用ページを報告する。非 HID デバイスはオプションで使用ページを報告する。非 HID デバイスが報告しない場合、このパラメータの値はゼロになる。
wUsage
オブジェクトに関連する HID 使用状況 (判明した場合)。ヒューマン インターフェイス デバイスは常に使用を報告する。非 HID デバイスはオプションで使用状況を報告する。非 HID デバイスが報告しない場合、このパラメータの値はゼロになる。
dwDimension
オブジェクトの値を報告する単位の HID コード (判明している場合)。不明な場合はゼロとなる。
wExponent
単位に付ける指数 (判明している場合)。次元単位は常に整数であるので、整数以外のタイプに単位を変換するには指数が必要となる。
wReportId
予約済み。

注意

アプリケーションは wUsagePage および wUsage メンバを使用して、オブジェクトの設計目的についての追加情報を得ることができる。たとえば、wUsagePage の値が 0x02 (乗物のコントロール) で、wUsage の値が 0xB9 (昇降舵トリム) の場合、オブジェクトは、操縦桿の昇降舵トリム コントロールとして設計されている。フライト シミュレータ アプリケーションはこの情報を使用して、デバイス上のオブジェクトに対して、より適切なデフォルト動作を提供することができる。HID 使用コードは USB 標準委員会で定められている。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIEFFECT

DIEFFECT 構造体は、IDirectInputDevice7::CreateEffect メソッドが、新しい IDirectInputEffect オブジェクトを初期化するために使用する。IDirectInputEffect::SetParameters および IDirectInputEffect::GetParameters メソッドによっても使用される。

typedef struct DIEFFECT {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwDuration;
    DWORD dwSamplePeriod;
    DWORD dwGain;
    DWORD dwTriggerButton;
    DWORD dwTriggerRepeatInterval;
    DWORD cAxes;
    LPDWORD rgdwAxes;
    LPLONG rglDirection;
    LPDIENVELOPE lpEnvelope;
    DWORD cbTypeSpecificParams;
    LPVOID lpvTypeSpecificParams;
    DWORD  dwStartDelay;
} DIEFFECT, *LPDIEFFECT;

typedef const DIEFFECT *LPCDIEFFECT;

メンバ

dwSize
構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
dwFlags
エフェクトに関連付けられたフラグ。この値は、以下の値の 1 つ以上の組み合わせとなる。
DIEFF_CARTESIAN
rglDirection の値は、デカルト座標として解釈する。
DIEFF_OBJECTIDS
dwTriggerButton および rgdwAxes の値は、IDirectInputDevice7::EnumObjects によって取得されるオブジェクト識別子である。
DIEFF_OBJECTOFFSETS
dwTriggerButton および rgdwAxes の値は、データ形式オフセットで IDirectInputDevice7::SetDataFormat によって選択されているデータ形式を起点とする。
DIEFF_POLAR
rglDirection の値は、極座標と解釈する。
DIEFF_SPHERICAL
rglDirection の値は、球面座標と解釈する。
dwDuration
エフェクトのマイクロ秒単位の継続時間の合計。この値が INFINITE であれば、エフェクトの継続時間は無限となる。エンベロープがエフェクトに適用されていれば、アタックも適用され、無限の維持期間も適用されることになる。
dwSamplePeriod
デバイスがエフェクトを再生すべき間隔。マイクロ秒単位。この値がゼロであれば、デフォルトの再生サンプリング速度を使用することを意味する。

デバイスが指定の速度でエフェクトを再生できなければ、指定された値に最も近い速度を選択する。

カスタム dwSamplePeriod の設定は、特殊効果に使用できる。たとえば、サイン波を意図的に大きなサンプリングレートで再生すると、ざらざらした質感をもたらす。

dwGain
エフェクトに適用されるゲイン。0 ～ 10,000 の範囲にある。ゲインとは、エフェクトの全マグニチュードとそのエンベロープに適用されるスケーリング係数である。
dwTriggerButton
エフェクトの再生をトリガするのに使用されるボタンの識別子またはオフセット。DIEFF_OBJECTIDS および DIEFF_OBJECTOFFSETS の各フラグが、この値の意味内容を決定する。このメンバに DIEB_NOTRIGGER が設定されている場合、エフェクトに関連付けられているトリガ ボタンはない。
dwTriggerRepeatInterval
ボタンの押下および押し続けによってエフェクトがトリガされたときの、1 回の再生の終了と開始の間隔を表す、マイクロ秒単位の時間。繰り返しを抑制するには、この値を INFINITE に設定する。

DIEFFECTINFO 構造体の dwStaticParams メンバに DIEP_TRIGGERREPEATINTERVAL フラグが設定されている場合は、1 つのエフェクトのトリガによる繰り返しが可能である。

cAxes
エフェクトに関連している軸の数。軸リストまたは方向リストの変更または設定時には、呼び出し側がこのメンバを設定しておかなければならない。

エフェクトの軸数は、一度設定されると変更できない。

rgdwAxes
(cAxes 要素から成る) DWORD 配列へのポインタ。この DWORD 配列は、エフェクトを適用する対象の軸を識別する識別子またはオフセットを格納する。DIEFF_OBJECTIDS および DIEFF_OBJECTOFFSETS の各フラグが、配列の値の意味内容を決定する。

エフェクトに関連付けられた軸のリストは、一度設定されると変更できない。

単一のエフェクトに関連付けられる軸の数は、32 までである。

rglDirection
デカルト座標または極座標を格納する (cAxes 要素から成る) LONG 配列へのポインタ。DIEFF_CARTESIAN、DIEFF_POLAR および DIEFF_SPHERICAL の各フラグが配列の値の意味内容を決定する。

デカルト座標では、rglDirection の各値は、rgdwAxes の対応する軸に関連付けられる。

極座標では、角度は、(0, -1) 方向から (1, 0) の方向に回転する実角度の 100 倍で測定される。これが意味するのは、北はユーザーの正面の方向であり、東はユーザーの右側であるということである。最後の要素は使用されない。

球面座標では、第 1 の角度は、(1,0) の方向から (0,1) の方向へ回転した実角度の 100 倍で計測される。第 2 の角度は (軸の数が 3 以上であるとき)、(0,0,1) へ向かう実角度の 100 倍で計測される。第 3 の角度は (軸の数が 4 以上であるとき)、(0,0,0,1) へ向かう実角度の 100 倍で計測される。以下も同様に解釈する。最後の要素は使用されない。

注 : rglDirection 配列は、極座標または球面座標が指定されている場合でも cAxes エントリを含まなければならない。極座標または球面座標の場合、rglDirection 配列の最後の要素は、将来の用途のために予約されているので、ゼロでなければならない。

lpEnvelope
このエフェクトが使用するエンベロープを表す DIENVELOPE 構造体へのオプション ポインタ。すべてのエフェクト タイプが、エンベロープを使用するとは限らない。エンベロープの適用がなければ、このメンバには、NULL を設定する必要がある。
cbTypeSpecificParams
対応するエフェクト タイプに関する追加のタイプ固有パラメータのバイト数。
lpvTypeSpecificParams
タイプ固有パラメータへのポインタ。タイプ固有パラメータが存在しない場合には NULL。

エフェクトが DIEFT_CONDITION 型であれば、このメンバは、条件のパラメータを定義する DICONDITION 構造体からなる配列へのポインタを持つ。1 つの構造体を使用してもよい。この場合、条件は配列 rglDirection で指定された方向に適用される。そうでない場合は、配列 rgdwAxes の軸と同じ順序で、それぞれの軸に対して 1 つの構造体が必要となる。それぞれの軸に 1 つの構造体を用意すると、エフェクトは回転しない。配列 rglDirection では次の値を使用しなければならない。

  • DIEFF_SPHERICAL: 0, 0, ...
  • DIEFF_POLAR: 9000, 0, ...
  • DIEFF_CARTESIAN: 1, 0, ...

エフェクトが DIEFT_CUSTOMFORCE 型であれば、このメンバは、カスタム フォースのパラメータを定義する DICUSTOMFORCE 構造体へのポインタを持つ。

エフェクトが DIEFT_PERIODIC 型であれば、このメンバは、エフェクトのパラメータを定義する DIPERIODIC 構造体へのポインタを持つ。

エフェクトが DIEFT_CONSTANTFORCE 型であれば、このメンバは、コンスタント フォースのパラメータを定義する DICONSTANTFORCE 構造体へのポインタを持つ。

エフェクトが DIEFT_RAMPFORCE 型であれば、このメンバは、傾斜フォースのパラメータを定義する DIRAMPFORCE 構造体へのポインタを持つ。

dwStartDelay
IDirectInputEffect::Start を呼び出してからエフェクトを再生する前に、デバイスが待機する時間 (マイクロ秒単位)。この値がゼロであれば、エフェクトの再生は直ちに開始される。このメンバは、DirectX 7.0 より前のバージョンには存在しない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIEFFECTINFO

DIEFFECTINFO 構造体は、IDirectInputDevice7::EnumEffects および IDirectInputDevice7::GetEffectInfo メソッドが、デバイスによりサポートされるエフェクトに関する情報を返すために使用する。

typedef struct DIEFFECTINFO {
    DWORD dwSize;
    GUID guid;
    DWORD dwEffType;
    DWORD dwStaticParams;
    DWORD dwDynamicParams;
    TCHAR tszName[MAX_PATH];
} DIEFFECTINFO, *LPDIEFFECTINFO;

typedef const DIEFFECTINFO  *LPCDIEFFECTINFO;

メンバ

dwSize
構造体のバイト単位のサイズ。列挙の間に、アプリケーションはこの値を調べ、構造体のメンバがいくつ有効であるかを確認できる。この構造体が IDirectInputDevice7::GetEffectInfo メソッドに渡される前に、この構造体のメンバを初期化しなければならない。
guid
エフェクトの識別子。
dwEffType
ゼロまたは以下の値のいずれか。
DIEFT_ALL
IDirectInputDevice7::EnumEffects に対してのみ有効。タイプに関係なくすべてのエフェクトを列挙する。このフラグは、ほかのどのフラグとも組み合せることはできない。
DIEFT_CONDITION
エフェクトは、条件を表す。条件を作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DICONDITION 構造体 (各軸に 1 つ) から成る配列を指し、cbTypeSpecificParams メンバには cAxis * sizeof(DICONDITION) を設定しなければならない。

すべてのデバイスが、条件のすべてのパラメータをサポートするわけではない。エフェクトの能力フラグをチェックして、どの能力が使用可能であるかを調べる。

このフラグは、IDirectInputDevice7::EnumEffects に渡して、列挙対象を条件に制限することができる。

DIEFT_CONSTANTFORCE
エフェクトは、コンスタント フォース エフェクトを表す。コンスタント フォース エフェクトを作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DICONSTANTFORCE 構造体を指し、cbTypeSpecificParams メンバには sizeof(DICONSTANTFORCE) を設定しなければならない。

このフラグは、IDirectInputDevice7::EnumEffects に渡して、列挙対象をコンスタント フォース エフェクトに制限することができる。

DIEFT_CUSTOMFORCE
エフェクトは、カスタム フォース エフェクトを表す。カスタム フォース エフェクトを作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DICUSTOMFORCE 構造体を指し、cbTypeSpecificParams メンバには sizeof(DICUSTOMFORCE) を設定しなければならない。

このフラグは、IDirectInputDevice7::EnumEffects に渡して、列挙対象をカスタム フォース エフェクトに制限することができる。

DIEFT_DEADBAND
この条件エフェクトに対するエフェクト ジェネレータは、lDeadBand パラメータをサポートする。
DIEFT_FFATTACK
このエフェクトに対するエフェクト ジェネレータは、アタック エンベロープ パラメータをサポートする。エフェクト ジェネレータがアタックをサポートしていなければ、DIENVELOPE 構造体のアタック レベルとアタック時間のパラメータを、エフェクトが無視する。

DIEFT_FFATTACK と DIEFT_FFFADE が両方とも設定されていなければ、エフェクトは、エンベロープをサポートせず、指定のエンベロープは、すべて無視される。

DIEFT_FFFADE
このエフェクトに対するエフェクト ジェネレータは、フェード パラメータをサポートする。エフェクト ジェネレータがフェードをサポートしていなければ、DIENVELOPE 構造体のフェード レベルとフォード時間のパラメータを、エフェクトが無視する。

DIEFT_FFATTACK と DIEFT_FFFADE が両方とも設定されていなければ、エフェクトは、エンベロープをサポートせず、指定のエンベロープは、すべて無視される。

DIEFT_HARDWARE
エフェクトは、ハードウェア固有のエフェクトを表す。ハードウェア固有エフェクトの使用の詳細については、ハードウェアのドキュメントを参照すること。

このフラグを IDirectInputDevice7::EnumEffects メソッドに渡して、列挙対象をハードウェア固有エフェクトに制限することができる。

DIEFT_PERIODIC
エフェクトは、周期的フォース エフェクトを表す。周期的フォース エフェクトを作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DIPERIODIC 構造体を指し、cbTypeSpecificParams メンバには sizeof(DIPERIODIC) を設定しなければならない。

このフラグは、IDirectInputDevice7::EnumEffects に渡して、列挙対象を周期的フォース エフェクトに制限することができる。

DIEFT_POSNEGCOEFFICIENTS
このエフェクトに対するエフェクト ジェネレータは、条件に対する 2 つの係数値、一方は正の軸移動、他方は負の軸移動に対する係数をサポートする。デバイスが一方向の係数しかサポートしない場合、DICONDITION 構造体の負の係数が無視され、正の係数が両方の方向で使用される。
DIEFT_POSNEGSATURATION
このエフェクトに対するエフェクト ジェネレータは、正負の両方のフォース出力に対する最大飽和をサポートする。デバイスが一方向の飽和値しかサポートしないのであれば、DICONDITION 構造体の負の飽和値が無視され、正の飽和値が両方の方向で使用される。
DIEFT_RAMPFORCE
エフェクトは、傾斜フォース エフェクトを表す。傾斜フォース エフェクトを作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DIRAMPFORCE 構造体を指し、cbTypeSpecificParams メンバには sizeof(DIRAMPFORCE) を設定しなければならない。

このフラグは、IDirectInputDevice7::EnumEffects に渡して、列挙対象を傾斜フォース エフェクトに制限することができる。

DIEFT_SATURATION
このエフェクトに対するエフェクト ジェネレータは、条件エフェクトの飽和をサポートする。エフェクト ジェネレータが飽和をサポートしていなければ、条件が生成したフォースは、デバイスが生成できる最大フォースによってのみ制限される。
dwStaticParams
エフェクトがサポートするパラメータを表すゼロ以上の DIEP_* 値。たとえば、DIEP_ENVELOPE が設定されていれば、エフェクトはエンベロープをサポートする。このメンバが取りうる値のリストについては、「IDirectInputEffect::GetParameters」を参照すること。

デバイスがサポートしていないエフェクト パラメータをアプリケーションが使用しようとしても、エラーにはならない。サポートされていないパラメータは、無視されるだけである。

この情報は、アプリケーションが特定のデバイスの能力にフォース フィードバックを適合させて使えるようにするために提供されている。

dwDynamicParams
エフェクトの再生中に修正できるエフェクト パラメータを示すゼロ以上の DIEP_* 値。このメンバが取りうる値のリストについては、「IDirectInputEffect::GetParameters」を参照すること。

エフェクトの再生中にアプリケーションがパラメータを変更しようとしても、ドライバがそのエフェクトを動的に修正する機能をサポートしていない場合は、ドライバはそのエフェクトを停止して、パラメータを更新し、その後にエフェクトを再開することができる。詳細については、「IDirectInputEffect::SetParameters」を参照すること。

tszName[MAX_PATH]
エフェクトの名前。たとえば、"Sawtooth up" または "Constant フォース" など。

注意

dwEffType フラグからエフェクト タイプを抽出するには、DIEFT_GETTYPE マクロを使用する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIEFFESCAPE

DIEFFESCAPE 構造体は、ハードウェア データをデバイス ドライバに直接、渡すために IDirectInputDevice7::Escape および IDirectInputEffect::Escape メソッドで使用される。

typedef struct DIEFFESCAPE {
    DWORD dwSize;
    DWORD dwCommand;
    LPVOID lpvInBuffer;
    DWORD cbInBuffer;
    LPVOID lpvOutBuffer;
    DWORD cbOutBuffer;
} DIEFFESCAPE, *LPDIEFFESCAPE;

メンバ

dwSize
構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
dwCommand
ドライバのコマンド番号。有効なコマンドの一覧については、ドライバのドキュメントを参照すること。
lpvInBuffer
操作を実行するのに必要なデータを格納しているバッファ。
cbInBuffer
lpvInBuffer バッファのバイト単位のサイズ。
lpvOutBuffer
操作の出力データが返されるバッファ。
cbOutBuffer
入力パラメータとしては、lpvOutBuffer バッファのバイト単位のサイズ。出力パラメータとしては、コマンドが実際に作成したバイト数。

注意

各ドライバは、異なるエスケープ シーケンスを実装しているので、正しいドライバと通信しているかどうかは、アプリケーション自体が確認しなければならない。これは、DIDEVICEINSTANCE 構造体の guidFFDriver メンバと、アプリケーションが期待している値を比較することにより確認できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIENVELOPE

DIENVELOPE 構造体は、DIEFFECT 構造体がエフェクトに対するオプションのエンベロープ パラメータを指定するために使用する。そのエンベロープの維持期間レベルは、DIPERIODIC 構造体の dwMagnitude メンバと DICONSTANTFORCE 構造体の lMagnitude メンバとが示す値である。保持時間は、DIEFFECT 構造体の dwDuration メンバが示す値である。

typedef struct DIENVELOPE {
    DWORD dwSize;
    DWORD dwAttackLevel;
    DWORD dwAttackTime;
    DWORD dwFadeLevel;
    DWORD dwFadeTime;
} DIENVELOPE, *LPDIENVELOPE;

typedef const DIENVELOPE *LPCDIENVELOPE;

メンバ

dwSize
構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
dwAttackLevel
基線を基準とするエンベロープの始点における振幅。基線に対する相対値。0 ～ 10,000 の範囲である。エフェクトのタイプ固有データが基線を指定していなければ、振幅はゼロを基準とする。
dwAttackTime
維持期間レベルに到達するのに必要な、マイクロ秒単位の時間。
dwFadeLevel
エンベロープの終点での振幅。基線に対する相対値。0 ～ 10,000 の範囲である。エフェクトのタイプ固有データが基線を指定していなければ、振幅はゼロを基準とする。
dwFadeTime
フェード レベルに到達するのに必要なマイクロ秒単位の時間。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIFILEEFFECT

DIFILEEFFECT 構造体は、ファイルに保存されたフォース フィードバック エフェクトのデータを表す。この構造体は、IDirectInputDevice7::EnumEffectsInFile および IDirectInputDevice7::WriteEffectToFile メソッドで使用される。

typedef struct DIFILEEFFECT{
    DWORD       dwSize;
    GUID        GuidEffect;
    LPCDIEFFECT lpDiEffect;
    CHAR        szFriendlyName[MAX_PATH];
}DIFILEEFFECT, *LPDIFILEEFFECT;

メンバ

dwSize
構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
GuidEffect
エフェクト タイプの一意な識別子。GUID_ConstantForce など、Dinput.h に定義された標準 GUID や、デザイナによって作成された GUID をとることができる。
lpDiEffect
エフェクトに関する情報を含む DIEFFECT 構造体へのポインタ。
szFriendlyName
エフェクトの名前。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIJOYSTATE

DIJOYSTATE 構造体は、ジョイスティック デバイスの状態に関する情報を格納する。この構造体は、IDirectInputDevice7::GetDeviceState メソッドで使用する。

typedef struct DIJOYSTATE {
    LONG    lX;
    LONG    lY;
    LONG    lZ;
    LONG    lRx;
    LONG    lRy;
    LONG    lRz;
    LONG    rglSlider[2];
    DWORD   rgdwPOV[4];
    BYTE    rgbButtons[32];
} DIJOYSTATE, *LPDIJOYSTATE;

メンバ

lX
ジョイスティックの x 軸の情報 (通常は、スティックの左右の動き)。
lY
ジョイスティックの y 軸の情報 (通常は、スティックの前後の動き)。
lZ
ジョイスティックの z 軸の情報 (通常は、スロットル制御)。ジョイスティックにこの軸がなければ、値はゼロである。
lRx
ジョイスティックの x 軸回転の情報。ジョイスティックにこの軸がなければ、値はゼロである。
lRy
ジョイスティックの y 軸回転の情報。ジョイスティックにこの軸がなければ、値はゼロである。
lRz
ジョイスティックの z 軸回転の情報 (方向舵のコントロールでよく呼び出される)。ジョイスティックにこの軸がなければ、値はゼロである。
rglSlider[2]
2 つの追加軸の値 (以前には u 軸と v 軸と呼ばれていた)。この値の意味はジョイスティックで異なる。これらの値の意味についての情報を得るには、IDirectInputDevice7::GetObjectInfo メソッドを使用する。
rgdwPOV[4]
最高 4 つまでの方向コントローラ (視点インジケータなど) の現在位置。この位置は、北から (ユーザーの正面側) 時計回りの実角度の 100 倍で表される。中心位置は通常 -1 と報告されるが、これについては「注意」を参照すること。5 つの位置しか持たないインジケータの場合、コントローラの値は -1、0、9,000、18,000、27,000 のどれか 1 つの値を取る。
rgbButtons[32]
ボタン状態の配列。バイトの上位ビットは、対応するボタンがダウン状態にあるときに設定され、ボタンがアップ状態または存在しないときには消去される。

注意

ジョイスティック式のアクセスができるようにデバイスを準備するには、IDirectInputDevice7::SetDataFormat メソッドを呼び出し、c_dfDIJoystick グローバル データ形式変数を渡す。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

POV インジケータの中心位置を 65,535 と報告するドライバもある。POV インジケータが中心位置にあるかどうかは、次のようにして確認する。

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIJOYSTATE2

DIJOYSTATE2 構造体は、拡張機能付きジョイスティック デバイスの状態に関する情報を格納する。この構造体は、IDirectInputDevice7::GetDeviceState メソッドで使用する。

typedef struct DIJOYSTATE2 {
    LONG    lX;
    LONG    lY;
    LONG    lZ;
    LONG    lRx;
    LONG    lRy;
    LONG    lRz;
    LONG    rglSlider[2];
    DWORD   rgdwPOV[4];
    BYTE    rgbButtons[128];
    LONG    lVX;
    LONG    lVY;
    LONG    lVZ;
    LONG    lVRx;
    LONG    lVRy;
    LONG    lVRz;
    LONG    rglVSlider[2];
    LONG    lAX;
    LONG    lAY;
    LONG    lAZ;
    LONG    lARx;
    LONG    lARy;
    LONG    lARz;
    LONG    rglASlider[2];
    LONG    lFX;
    LONG    lFY;
    LONG    lFZ;
    LONG    lFRx;
    LONG    lFRy;
    LONG    lFRz;
    LONG    rglFSlider[2];
} DIJOYSTATE2, *LPDIJOYSTATE2;

メンバ

lX
ジョイスティックの x 軸の情報 (通常は、スティックの左右の動き)。
lY
ジョイスティックの y 軸の情報 (通常は、スティックの前後の動き)。
lZ
ジョイスティックの z 軸の情報 (通常は、スロットル制御)。ジョイスティックにこの軸がなければ、値はゼロである。
lRx
ジョイスティックの x 軸回転の情報。ジョイスティックにこの軸がなければ、値はゼロである。
lRy
ジョイスティックの y 軸回転の情報。ジョイスティックにこの軸がなければ、値はゼロである。
lRz
ジョイスティックの z 軸回転の情報 (方向舵のコントロールでよく呼び出される)。ジョイスティックにこの軸がなければ、値はゼロである。
rglSlider[2]
2 つの追加軸の値 (以前には u 軸と v 軸と呼ばれていた)。この値の意味はジョイスティックで異なる。これらの値の意味についての情報を得るには、IDirectInputDevice7::GetObjectInfo メソッドを使用する。
rgdwPOV[4]
最高 4 つまでの方向コントローラ (視点ハットなど) の現在位置。この位置は、北から (ユーザーの正面側) 時計回りの実角度の 100 倍で表される。中心位置は通常 -1 と報告されるが、これについては「注意」を参照すること。5 つの位置しか持たないインジケータの場合、コントローラの値は -1、0、9,000、18,000、27,000 のどれか 1 つの値を取る。
rgbButtons[128]
ボタン状態の配列。バイトの上位ビットは、対応するボタンがダウン状態にあるときに設定され、ボタンがアップ状態または存在しないときには消去される。
lVX
x 軸速度の情報。
lVY
y 軸速度の情報。
lVZ
z 軸速度の情報。
lVRx
x 軸角速度の情報。
lVRy
y 軸角速度の情報。
lVRz
z 軸角速度の情報。
rglVSlider[2]
追加軸の速度の情報。
lAX
x 軸加速度の情報。
lAY
y 軸加速度の情報。
lAZ
z 軸加速度の情報。
lARx
x 軸角加速度の情報。
lARy
y 軸角加速度の情報。
lARz
z 軸角加速度の情報。
rglASlider[2]
追加軸の加速度の情報。
lFX
x 軸フォースの情報。
lFY
y 軸フォースの情報。
lFZ
z 軸フォースの情報。
lFRx
x 軸トルクの情報。
lFRy
y 軸トルクの情報。
lFRz
z 軸トルクの情報。
rglFSlider[2]
追加軸のフォースの情報。

注意

拡張機能付きジョイスティックへのアクセス用にデバイスを準備するには、IDirectInputDevice7::SetDataFormat メソッドを呼び出し、c_dfDIJoystick2 グローバルデータ形式変数を渡す。

DIJOYSTATE2 構造体は IDirectInputDevice7 インターフェイスと特別な関連はない。DIJOYSTATE または DIJOYSTATE2 のどちらか一方を、IDirectInputDevice インターフェイスまたは IDirectInputDevice7 インターフェイスのどちらか一方と共に使用することができる。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

POV インジケータの中心位置を 65,535 と報告するドライバもある。POV インジケータが中心位置にあるかどうかは、次のようにして確認する。

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIMOUSESTATE

DIMOUSESTATE 構造体は、4 つまでのボタンを持つマウス デバイスの状態に関する情報、またはマウス デバイスと同じようにアクセスされるその他のデバイスの状態に関する情報を格納する。この構造体は、IDirectInputDevice7::GetDeviceState メソッドで使用する。

typedef struct DIMOUSESTATE {
    LONG lX;
    LONG lY;
    LONG lZ;
    BYTE rgbButtons[4];
} DIMOUSESTATE, *LPDIMOUSESTATE;

メンバ

lX
マウスの x 軸情報。
lY
マウスの y 軸情報。
lZ
マウスの z 軸情報 (通常、ホイール)。マウスに z 軸がなければ、この値はゼロである。
rgbButtons[4]
ボタン状態の配列。バイトの上位ビットは、対応するボタンがダウン状態にあるときに設定される。

注意

マウス型のアクセスができるようにデバイスを準備するには、IDirectInputDevice7::SetDataFormat メソッドを呼び出し、c_dfDIMouse グローバル データ形式変数を渡す。

マウスは相対軸デバイスであるので、マウス軸の絶対軸位置は、単純に相対的な動きの累積として求められる。したがって、絶対軸位置は、ほかの絶対軸位置と比較する場合を除いて無意味となる。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

DIMOUSESTATE2


DIMOUSESTATE2

DIMOUSESTATE2 構造体は、8 つまでのボタンを持つマウス デバイス、またはマウス デバイスと同様にアクセスされるその他のデバイスに関する情報を格納する。この構造体は、IDirectInputDevice7::GetDeviceState メソッドで使用する。

typedef struct DIMOUSESTATE {
    LONG lX;
    LONG lY;
    LONG lZ;
    BYTE rgbButtons[8];
} DIMOUSESTATE, *LPDIMOUSESTATE;

メンバ

lX
マウスの x 軸情報。
lY
マウスの y 軸情報。
lZ
マウスの z 軸情報 (通常、ホイール)。マウスに z 軸がなければ、この値はゼロである。
rgbButtons[8]
ボタン状態の配列。バイトの上位ビットは、対応するボタンがダウン状態にあるときに設定される。

注意

マウス型のアクセスができるようにデバイスを準備するには、IDirectInputDevice7::SetDataFormat メソッドを呼び出し、c_dfDIMouse2 グローバル データ形式変数を渡す。

マウスは相対軸デバイスであるので、マウス軸の絶対軸位置は、単純に相対的な動きの累積として求められる。したがって、絶対軸位置は、ほかの絶対軸位置と比較する場合を除いて無意味となる。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

DIMOUSESTATE


DIOBJECTDATAFORMAT

DIOBJECTDATAFORMAT 構造体は、IDirectInputDevice7::SetDataFormat メソッドで使用するためのデバイス オブジェクトのデータ形式の情報を格納する。

typedef struct DIOBJECTDATAFORMAT {
    const GUID * pguid;
    DWORD        dwOfs;
    DWORD        dwType;
    DWORD        dwFlags;
} DIOBJECTDATAFORMAT, *LPDIOBJECTDATAFORMAT;

typedef const DIOBJECTDATAFORMAT *LPCDIOBJECTDATAFORMAT;

メンバ

pguid
軸、ボタン、またはその他の入力ソースに対する一意な識別子。データ形式の要求時、このメンバを NULL にすると、あらゆるタイプのオブジェクトを許可することになる。
dwOfs
入力ソースのデータを格納するデータ パケット内のオフセット。この値は、軸など、DWORD サイズのデータに合うように、4 の倍数でなければならない。ボタンに対してはバイト整列でも構わない。
dwType
オブジェクトを表すデバイス タイプ。オブジェクト タイプ (軸、ボタンなど) を表す以下のフラグの組み合わせであり、中央の 16 ビットは、オブジェクト インスタンス番号を格納する。データ形式の要求時に、インスタンス部分に DIDFT_ANYINSTANCE を設定すると、あらゆるインスタンスを許可することができる。DIDFT_MAKEINSTANCE(n) に設定して、要求をインスタンス n に限定することもできる。「注意」を参照すること。
DIDFT_ABSAXIS
SetDataFormat メソッドによって選択されたオブジェクトは、絶対軸でなければならない。
DIDFT_AXIS
SetDataFormat メソッドによって選択されたオブジェクトは、絶対軸あるいは相対軸でなければならない。
DIDFT_BUTTON
SetDataFormat メソッドによって選択されたオブジェクトは、プッシュ ボタンあるいはトグル ボタンでなければならない。
DIDFT_FFACTUATOR
SetDataFormat メソッドによって選択されたオブジェクトは、フォース フィードバック アクチュエータを含まなければならない。すなわち、フォースをこのオブジェクトに適用することができなければならない。
DIDFT_FFEFFECTTRIGGER
SetDataFormat メソッドによって選択されたオブジェクトは、有効なフォース フィードバック エフェクト トリガでなければならない。
DIDFT_POV
SetDataFormat メソッドによって選択されたオブジェクトは、視点コントローラでなければならない。
DIDFT_PSHBUTTON
SetDataFormat メソッドによって選択されたオブジェクトは、プッシュ ボタンでなければならない。
DIDFT_RELAXIS
SetDataFormat によって選択されたオブジェクトは、相対軸でなければならない。
DIDFT_TGLBUTTON
SetDataFormat によって選択されたオブジェクトは、トグル ボタンでなければならない。
DIDFT_VENDORDEFINED
SetDataFormat によって選択されたオブジェクトは、メーカー定義のタイプでなければならない。
dwFlags
ゼロまたは以下の値のいずれか。
DIDOI_ASPECTACCEL
SetDataFormat によって選択されたオブジェクトは、加速度情報を報告しなければならない。
DIDOI_ASPECTFORCE
SetDataFormat によって選択されたオブジェクトは、フォース情報を報告しなければならない。
DIDOI_ASPECTPOSITION
SetDataFormat によって選択されたオブジェクトは、位置情報を報告しなければならない。
DIDOI_ASPECTVELOCITY
SetDataFormat によって選択されたオブジェクトは、速度情報を報告しなければならない。

注意

データ形式は、各オブジェクト (軸、ボタンなど) が 1 つずつ保有する複数の DIOBJECTDATAFORMAT 構造体で構成される。これらの構造体の配列は、IDirectInputDevice7::SetDataFormat に渡される DIDATAFORMAT 構造体に格納される。アプリケーションは、通常、DIOBJECTDATAFORMAT 構造体からなる配列を作成する必要はなく、DIOBJECTDATAFORMAT に事前定義されている設定値である c_dfDIMouse、c_dfDIMouse2、c_dfDIKeyboard、c_dfDIJoystick、または c_dfDIJoystick2 などの事前定義されたデータ形式データのいずれかを使用できる。

以下のオブジェクト データ形式は、DirectInput が最初の使用可能な軸を選択し、そのデバイス データのオフセット 4 の位置にある値を DWORD で報告しなければならないということを指定している。

DIOBJECTDATAFORMAT dfAnyAxis = {
0,                  // ワイルドカード
4,                  // オフセット
DIDFT_AXIS | DIDFT_ANYINSTANCE, // どんな軸でもよい。
0,                  // アスペクトに関与しない。
};

以下のオブジェクト データ形式は、デバイスの x 軸をデバイス データのオフセット 12 の位置に DWORD で格納するように指定している。デバイスが複数の x 軸を持っている場合には、最初に使用可能な軸が選択される。

DIOBJECTDATAFORMAT dfAnyXAxis = {
&GUID_XAxis,          // X 軸でなければならない。
12,                  // オフセット
DIDFT_AXIS | DIDFT_ANYINSTANCE, // どんな X 軸でもよい。
0,                  // アスペクトに関与しない。
};

以下のオブジェクト データ形式は、DirectInput が最初に使用可能なボタンを選択して、デバイス データのオフセット 16 の位置にあるバイトの上位ビットの値を報告するように指定している。

DIOBJECTDATAFORMAT dfAnyButton = {
0,                  // ワイルドカード
16,                  // オフセット
DIDFT_BUTTON | DIDFT_ANYINSTANCE, // どんなボタンでもよい。
0,                  // アスペクトに関与しない。
};

以下のオブジェクト データ形式は、デバイスのボタン 0 をデバイス データのオフセット 18 の位置に格納されているバイトの上位ビットとして報告するように指定している。

デバイスにボタン 0 がなければ、このデータ形式の設定は失敗に終わる。

DIOBJECTDATAFORMAT dfButton0 = {
0,                  // ワイルドカード
18,                  // オフセット
DIDFT_BUTTON | DIDFT_MAKEINSTANCE(0), // ボタン 0
0,                  // アスペクトに関与しない。
};

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIPERIODIC

DIPERIODIC 構造体は、DIEFT_PERIODIC とマークされているエフェクトに対するタイプ情報を格納する。

この構造体は、周期的エフェクトを表す。

エフェクトを表す単一の DIPERIODIC 構造体へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。

typedef struct DIPERIODIC {
    DWORD dwMagnitude;
    LONG  lOffset;
    DWORD dwPhase;
    DWORD dwPeriod;
} DIPERIODIC, *LPDIPERIODIC;

typedef const DIPERIODIC *LPCDIPERIODIC;

メンバ

dwMagnitude
0 ～ 10,000 の範囲にある、エフェクトのマグニチュード。エンベロープがこのエフェクトに適用されていれば、この値は、維持期間のマグニチュードを表す。エンベロープの適用がなければ、この値は、エフェクト全体の振幅を表す。
lOffset
エフェクトの識別子。エフェクトが生成するフォースの範囲は、lOffset - dwMagnitude から lOffset + dwMagnitude までの間になる。lOffset メンバの値は、エフェクトに適用されるすべてのエンベロープに対する基線にもなる。
dwPhase
0 ～ 35,999 の範囲内にある周期的エフェクトの再生開始位置。「注意」を参照すること。
dwPeriod
マイクロ秒単位のエフェクトの間隔。

注意

デバイス ドライバは dwPhase メンバのすべての値をサポートしているとはかぎらない。サポートされていない値は、直近のサポート値に丸められる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIPROPDWORD

DIPROPDWORD は、DWORD プロパティへのアクセスに使用する汎用的な構造体である。

typedef struct DIPROPDWORD {
    DIPROPHEADER     diph;
    DWORD            dwData;
} DIPROPDWORD, *LPDIPROPDWORD;

typedef const DIPROPDWORD *LPCDIPROPDWORD;

メンバ

diph
DIPROPHEADER 構造体。以下のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPDWORD)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow メンバが DIPH_DEVICE であれば、このメンバはゼロとする。

dwHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。

dwHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。たとえば、c_dfDIMouse データ形式を選ぶと、このメンバは DIIMOFS_* 値のうちどれか 1 つとしなければならない。
dwHow | dwObj メンバの解釈方法を指定する。dwOb が DIPROP_AXISMODE または DIPROP_BUFFERSIZE であれば、dwHow は DIPH_DEVICE とする。

dwData
設定または取得されるプロパティ値。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice7::GetProperty、IDirectInputDevice7::SetProperty


DIPROPGUIDANDPATH

DIPROPGUIDANDPATH 構造体は、GUID とパスを表す値を持つプロパティへのアクセスに使用される。

typedef struct DIPROPGUIDANDPATH {
    DIPROPHEADER diph;
    GUID         guidClass;
    WCHAR        wszPath[MAX_PATH];
} DIPROPGUIDANDPATH, *LPDIPROPGUIDANDPATH;

メンバ

diph
DIPROPHEADER 構造体。以下のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPGUIDANDPATH)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj | エフェクトの識別子。デバイスの場合はゼロである。
dwHow | dwObj メンバの解釈方法。

guidClass
オブジェクトのクラス GUID。
wszPath
返されるオブジェクトのパス。これは Unicode 文字列である。

注意

DIPROPGUIDANDPATH 構造体に関連付けられた DIPROP_GUIDANDPATH プロパティを使うと、詳細設定の可能なアプリケーションは、DirectInput でサポートされていない HID に対して操作を実行できる。

アプリケーションは、rguidProp パラメータに DIPROP_GUIDANDPATH を指定して IDirectInputDevice7::GetProperty メソッドを呼び出す。デバイスのクラス GUID は、DIPROPGUIDANDPATH 構造体の guidClass メンバに返される。デバイス インターフェイスのパスは、wszPath メンバに返される。その後、アプリケーションはこのパスに対して CreateFile 関数を呼び出して、デバイスに直接アクセスすることができる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : dinput.h で宣言。


DIPROPHEADER

DIPROPHEADER は、すべてのプロパティ構造体の先頭に位置する汎用的な構造体である。

typedef struct DIPROPHEADER {
    DWORD    dwSize;
    DWORD    dwHeaderSize;
    DWORD    dwObj;
    DWORD    dwHow;
} DIPROPHEADER, *LPDIPROPHEADER;

typedef const DIPROPHEADER *LPCDIPROPHEADER;

メンバ

dwSize
包含する構造体のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
dwHeaderSize
DIPROPHEADER 構造体のサイズ。
dwObj
アクセスするプロパティが属するオブジェクト。このメンバに設定する値は、dwHow メンバに指定されている値に依存する。
dwHow
dwObj メンバの解釈方法を指定する値。この値は、次のいずれか 1 つである。
値 | 意味
DIPH_DEVICE | dwObj メンバは、ゼロとする。
DIPH_BYOFFSET | dwObj メンバは、アクセスしているプロパティが属するオブジェクトの現在のデータ形式に対するオフセットである。
DIPH_BYID | dwObj メンバは、オブジェクト タイプまたはインスタンス識別子である。この識別子は、IDirectInputDevice7::EnumObjects メソッドを前回呼び出した際の戻り値である DIDEVICEOBJECTINSTANCE 構造体の dwType メンバに返される。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


DIPROPRANGE

DIPROPRANGE 構造体は、デバイス内のオブジェクトの範囲に関する情報を格納する。この構造体は、IDirectInputDevice7::GetProperty および IDirectInputDevice7::SetProperty メソッドで DIPROP_RANGE フラグを設定して使用する。

typedef struct DIPROPRANGE {
    DIPROPHEADER diph;
    LONG         lMin;
    LONG         lMax;
} DIPROPRANGE, *LPDIPROPRANGE;

typedef const DIPROPRANGE *LPCDIPROPRANGE;

メンバ

diph
DIPROPHEADER 構造体。以下のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPRANGE)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj | 取得または設定する範囲が属するオブジェクトの識別子。
dwHow | dwObj メンバの解釈方法。

lMin
範囲の下限。デバイスの範囲に制限がなければ、IDirectInputDevice7::GetProperty メソッドが戻るとき、この値は DIPROPRANGE_NOMIN となる。
lMax
範囲の上限。デバイスの範囲に制限がなければ、IDirectInputDevice7::GetProperty メソッドが戻るとき、この値は DIPROPRANGE_ NOMAX となる。

注意

範囲に制限のないデバイスに対する範囲値は、循環する。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice7::GetProperty、IDirectInputDevice7::SetProperty


DIPROPSTRING

DIPROPSTRING 構造体は、文字列プロパティにアクセスするために使用される。

typedef struct {
    DIPROPHEADER diph;
    WCHAR wsz;
} DIPROPSTRING;

メンバ

diph
DIPROPHEADER 構造体。以下のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPSTRING)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj | 取得または設定するプロパティが属するオブジェクトの識別子。
dwHow | dwObj メンバの解釈方法。

wsz
文字列。これは Unicode 文字列である。

注意

DIPROPSTRING 構造体に関連付けられた DIPROP_INSTANCENAME および DIPROP_PRODUCTNAME プロパティを使うと、詳細設定の可能なアプリケーションは、DirectInput でサポートされていない HID に対して操作を実行できる。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 98 が必要。
ヘッダー : dinput.h で宣言。


DIRAMPFORCE

DIRAMPFORCE 構造体は、DIEFT_RAMPFORCE としてマークされているエフェクトに関するタイプ情報を含む。この構造体は傾斜フォース エフェクトを表す。

エフェクトに関する単一の DIRAMPFORCE 構造体へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。

typedef struct DIPROPRANGE {
    LONG lStart;
    LONG lEnd;
} DIRAMPFORCE, *LPDIRAMPFORCE;

typedef const DIRAMPFORCE *LPCDIRAMPFORCE;

メンバ

lStart
-10,000 ～ 10.000 の範囲にある、エフェクトの始点のマグニチュード。
lEnd
-10,000 ～ 10.000 の範囲にある、エフェクトの終点のマグニチュード。

注意

傾斜フォース エフェクトの dwDuration は、INFINITE にはできない。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dinput.h で宣言。


デバイス定数

ここでは、キー、ボタンおよび軸に対するデータを解釈するのに使用する定数に関するリファレンスを提供する。

  • キーボード デバイス定数
  • DirectInput と日本語キーボード
  • マウス デバイス定数
  • ジョイスティック デバイス定数


キーボード デバイス定数

Dinput.h に定義されているキーボード デバイス定数は、キーボード デバイスのデータ パケット (256 バイト配列) 内でのオフセットを表す。指定のオフセット位置のデータは、キーボード キーに関連付けられている。通常、それらの値は、DIDEVICEOBJECTDATA、DIOBJECTDATAFORMAT、または DIDEVICEOBJECTINSTANCE 構造体の dwOfs メンバの中で使用されるか、あるいは配列の記法を使用して配列内のデータにアクセスするときのインデックスとして使用される。

標準キーボード デバイス定数は、以下のとおりである (昇順)。

定数 | メモ
DIK_ESCAPE |
DIK_1 | メイン キーボード上
DIK_2 | メイン キーボード上
DIK_3 | メイン キーボード上
DIK_4 | メイン キーボード上
DIK_5 | メイン キーボード上
DIK_6 | メイン キーボード上
DIK_7 | メイン キーボード上
DIK_8 | メイン キーボード上
DIK_9 | メイン キーボード上
DIK_0 | メイン キーボード上
DIK_MINUS | メイン キーボード上
DIK_EQUALS | メイン キーボード上
DIK_BACK | BackSpace キー
DIK_TAB |
DIK_Q |
DIK_W |
DIK_E |
DIK_R |
DIK_T |
DIK_Y |
DIK_U |
DIK_I |
DIK_O |
DIK_P |
DIK_LBRACKET | [ キー
DIK_RBRACKET | ] キー
DIK_RETURN | メイン キーボード上の Enter キー
DIK_LCONTROL | 左 Ctrl キー
DIK_A |
DIK_S |
DIK_D |
DIK_F |
DIK_G |
DIK_H |
DIK_J |
DIK_K |
DIK_L |
DIK_SEMICOLON |
DIK_APOSTROPHE |
DIK_GRAVE | アクサン グラーブ (`) キー
DIK_LSHIFT | 左 Shift キー
DIK_BACKSLASH |
DIK_Z |
DIK_X |
DIK_C |
DIK_V |
DIK_B |
DIK_N |
DIK_M |
DIK_COMMA |
DIK_PERIOD | メイン キーボード上
DIK_SLASH | メイン キーボード上の順スラッシュ
DIK_RSHIFT | 右 Shift キー
DIK_MULTIPLY | テンキー上の * キー
DIK_LMENU | 左 Alt キー
DIK_SPACE | スペース キー
DIK_CAPITAL | CapsLock キー
DIK_F1 |
DIK_F2 |
DIK_F3 |
DIK_F4 |
DIK_F5 |
DIK_F6 |
DIK_F7 |
DIK_F8 |
DIK_F9 |
DIK_F10 |
DIK_NUMLOCK |
DIK_SCROLL | ScrollLock
DIK_NUMPAD7 |
DIK_NUMPAD8 |
DIK_NUMPAD9 |
DIK_SUBTRACT | テンキー上のマイナス記号
DIK_NUMPAD4 |
DIK_NUMPAD5 |
DIK_NUMPAD6 |
DIK_ADD | テンキー上のプラス記号
DIK_NUMPAD1 |
DIK_NUMPAD2 |
DIK_NUMPAD3 |
DIK_NUMPAD0 |
DIK_DECIMAL | テンキー上のピリオド (小数点)
DIK_OEM_102 | 英語キーボードおよびドイツ語キーボード上
DIK_F11 |
DIK_F12 |
DIK_F13 |
DIK_F14 |
DIK_F15 |
DIK_KANA | 日本語キーボード上
DIK_ABNT_C1 | ブラジル語キーボードのテンキー上
DIK_CONVERT | 日本語キーボード上
DIK_NOCONVERT | 日本語キーボード上
DIK_YEN | 日本語キーボード上
DIK_ABNT_C2 | ブラジル語キーボードのテンキー上
DIK_NUMPADEQUALS | 数値キーボード上 (NEC PC98)
DIK_PREVTRACK | 前のトラック、日本語キーボードのサーカムフレックス
DIK_AT | 日本語キーボード上
DIK_COLON | 日本語キーボード上
DIK_UNDERLINE | 日本語キーボード上
DIK_KANJI | 日本語キーボード上
DIK_STOP | 日本語キーボード上
DIK_AX | 日本語キーボード上
DIK_UNLABELED | 日本語キーボード上
DIK_NEXTTRACK | 次のトラック
DIK_NUMPADENTER |
DIK_RCONTROL | 右 Ctrl キー
DIK_MUTE |
DIK_CALCULATOR |
DIK_PLAYPAUSE |
DIK_MEDIASTOP |
DIK_VOLUMEDOWN |
DIK_VOLUMEUP |
DIK_WEBHOME |
DIK_NUMPADCOMMA | NEC PC98 テンキー上のコンマ
DIK_DIVIDE | テンキー上の順スラッシュ
DIK_SYSRQ |
DIK_RMENU | 右 Alt キー
DIK_PAUSE |
DIK_HOME
DIK_UP | 上矢印キー
DIK_PRIOR | PageUp キー
DIK_LEFT | 左矢印キー
DIK_RIGHT | 右矢印キー
DIK_END |
DIK_DOWN | 下矢印キー
DIK_NEXT | PageDown キー
DIK_INSERT |
DIK_DELETE |
DIK_LWIN | 左 Windows キー
DIK_RWIN | 右 Windows キー
DIK_APPS | アプリケーション キー
DIK_POWER |
DIK_SLEEP |
DIK_WAKE |
DIK_WEBSEARCH |
DIK_WEBFAVORITES |
DIK_WEBREFRESH |
DIK_WEBSTOP |
DIK_WEBFORWARD |
DIK_WEBBACK |
DIK_MYCOMPUTER |
DIK_MAIL |
DIK_MEDIASELECT |

以下の代替名も使用可能である。

代替名 | 通常名 | メモ
DIK_BACKSPACE | DIK_BACK | BackSpace
DIK_NUMPADSTAR | DIK_MULTIPLY | テンキー上の * キー
DIK_LALT | DIK_LMENU | 左 Alt キー
DIK_CAPSLOCK | DIK_CAPITAL | CapsLock キー
DIK_CIRCUMFLEX | DIK_PREVTRACK | 日本語キーボード上
DIK_NUMPADMINUS | DIK__SUBTRACT | テンキー上のマイナス キー
DIK_NUMPADPLUS | DIK_ADD | テンキー上のプラス キー
DIK_NUMPADPERIOD | DIK_DECIMAL | テンキー上のピリオド キー
DIK_NUMPADSLASH | DIK__DIVIDE | テンキー上の順スラッシュ
DIK_RALT | DIK_RMENU | 右 Alt キー
DIK_UPARROW | DIK_UP | 矢印キーパッド上
DIK_PGUP | DIK_PRIOR | 矢印キーパッド上
DIK_LEFTARROW | DIK_LEFT | 矢印キーパッド上
DIK_RIGHTARROW | DIK_RIGHT | 矢印キーパッド上
DIK_DOWNARROW | DIK_DOWN | 矢印キーパッド上
DIK_PGDN | DIK_NEXT | 矢印キーパッド上

日本語キーボードについては、「DirectInput と日本語キーボード」を参照すること。


DirectInput と日本語キーボード

日本語キーボードと US キーボードの間には相当な違いがある。以下に、各種の日本語キーボードで使用可能な拡張キーを一覧で示す。また、US キーボードでは使用可能であるが、多くの日本語キーボードでは見当たらないキーの一覧も示す。

また、一部の NEC PC-98 キーボードでは、DIK_CAPSLOCK および DIK_KANA キーは、トグル ボタンでありプッシュ ボタンではないことに注意すること。これらのキーは、最初に押されたときにダウン イベントを生成し、2 回目に押されたときにアップ イベントを生成する。

キーボード | 拡張キー | 欠けるキー
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, DIK_F14, DIK_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


マウス デバイス定数

Dinput.h に定義されているマウス デバイス定数は、マウス デバイスのデータパケットである DIMOUSESTATE または DIMOUSESTATE2 構造体に対するオフセットを表す。指定のオフセット位置にあるデータは、デバイス オブジェクト (ボタンまたは軸) に関連付けられている。通常、それらの値は、DIDEVICEOBJECTDATA、DIOBJECTDATAFORMAT、または DIDEVICEOBJECTINSTANCE 構造体の dwOfs に使用される。

マウス デバイス定数は、以下のとおりである。

DIMOFS_BUTTON0 | マウスボタン 0 の状態を表すデータのオフセット。
DIMOFS_BUTTON1 | マウスボタン 1 の状態を表すデータのオフセット。
DIMOFS_BUTTON2 | マウスボタン 2 の状態を表すデータのオフセット。
DIMOFS_BUTTON3 | マウスボタン 3 の状態を表すデータのオフセット。
DIMOFS_BUTTON4 | マウスボタン 4 の状態を表すデータのオフセット (DIMOUSESTATE2 のみ)。
DIMOFS_BUTTON5 | マウスボタン 5 の状態を表すデータのオフセット (DIMOUSESTATE2 のみ)。
DIMOFS_BUTTON6 | マウスボタン 6 の状態を表すデータのオフセット (DIMOUSESTATE2 のみ)。
DIMOFS_BUTTON7 | マウスボタン 7 の状態を表すデータのオフセット (DIMOUSESTATE2 のみ)。
DIMOFS_X | x 軸上のマウスの位置を表すデータのオフセット。
DIMOFS_Y | y 軸上のマウスの位置を表すデータのオフセット。
DIMOFS_Z | z 軸上のマウスの位置を表すデータのオフセット。


ジョイスティック デバイス定数

ジョイスティック デバイス定数は、ジョイスティック デバイスのデータ パケットである DIJOYSTATE 構造体に対するオフセットを表す。指定のオフセットにあるデータは、デバイス オブジェクト、すなわちボタンまたは軸と関連付けられている。通常、それらの値は、DIDEVICEOBJECTDATA、DIOBJECTDATAFORMAT、または DIDEVICEOBJECTINSTANCE 構造体の dwOfs に使用される。

次のマクロは、常に状態を示すデータのオフセットを返すが、そのデータは DIJOYSTATE 構造体の先頭に関連付けられた特定のボタンまたは軸によって決まる。

DIJOFS_BUTTON0 から DIJOFS_BUTTON31 または DIJOFS_BUTTON(n) | ボタン
DIJOFS_POV(n) | 視点インジケータ
DIJOFS_RX | x 軸回転
DIJOFS_RY | y 軸回転
DIJOFS_RZ | z 軸回転 (方向舵)
DIJOFS_X | x 軸
DIJOFS_Y | y 軸
DIJOFS_Z | z 軸
DIJOFS_SLIDER(n) | スライド軸


戻り値

以下は、DirectInput メソッドと機能によって返される HRESULT 値の一覧である。エラーは負の値によって示され、結合することができない。

それぞれのメソッドまたは機能はエラー値を返すことができるが、詳細についてはそれぞれの説明を参照すること。本文中のエラー コードの一覧は、必然的に不完全になっている。たとえば、どんな DirectInput メソッドも DIERR_OUTOFMEMORY を返すことができるが、本文中では、このエラー コードはそのメソッドの戻り値としては明示されていない。

DI_BUFFEROVERFLOW
デバイスバッファがオーバーフローし、一部の入力が失われた。この値は、標準の COM 戻り値である S_FALSE に等しい。
DI_DOWNLOADSKIPPED
エフェクトのパラメータの更新は成功したが、このエフェクトに関連するデバイスが排他モードで取得されていないので、このエフェクトをダウンロードできない。
DI_EFFECTRESTARTED
エフェクトを停止し、そのパラメータの更新を行い、その後このエフェクトを再開した。
DI_NOEFFECT
この操作にエフェクトはない。この値は、標準の COM 戻り値である S_FALSE に等しい。
DI_NOTATTACHED
デバイスは存在するが現在アタッチされていない。この値は、標準の COM 戻り値である S_FALSE に等しい。
DI_OK
操作は、完全に終了した。この値は、標準の COM 戻り値である S_OK に等しい。
DI_POLLEDDEVICE
デバイスは、ポーリング対象デバイスである。その結果、デバイス バッファリングでは、データは一切収集されず、イベントは、IDirectInputDevice7::Poll メソッドが呼び出されるまで通知されない。
DI_PROPNOEFFECT
デバイス プロパティの変更はエフェクトがなかった。この値は、標準の COM 戻り値である S_FALSE に等しい。
DI_TRUNCATED
エフェクトのパラメータの更新は成功したが、パラメータのうちデバイスの能力を超えているものがあり、それらは直近のサポート値に丸められた。
DI_TRUNCATEDANDRESTARTED
DI_EFFECTRESTARTED | DI_TRUNCATED に等しい。
DIERR_ACQUIRED
操作は、デバイスが取得状態の間は実行できない。
DIERR_ALREADYINITIALIZED
このオブジェクトは初期化済みである。
DIERR_BADDRIVERVER
オブジェクトは、互換性のないドライバ バージョン、あるいは不適格または不完全なドライバ コンポーネントであるために作成できなかった。
DIERR_BETADIRECTINPUTVERSION
アプリケーションは、DirectInput のサポートされていないリリース前のバージョン用に作成されたものである。
DIERR_DEVICEFULL
デバイスはフルである。
DIERR_DEVICENOTREG
デバイスまたはデバイスインスタンスが DirectInput に登録されていない。この値は、標準の COM 戻り値である REGDB_E_CLASSNOTREG に等しい。
DIERR_EFFECTPLAYING
パラメータは、メモリ内では更新されたが、デバイスにはダウンロードされなかった。デバイスが再生中のエフェクトの更新をサポートしていないためである。
DIERR_HASEFFECTS
デバイスは、エフェクトがそのデバイスにアタッチされているために再初期化できない。
DIERR_GENERIC
DirectInput サブシステムで 原因不明のエラーが発生した。この値は、標準の COM 戻り値である E_FAIL に等しい。
DIERR_HANDLEEXISTS
デバイスは、既に、自身にイベント通知の関連付けをしている。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_INCOMPLETEEFFECT
必須情報がないので、エフェクトをダウンロードできなかった。たとえば、エフェクトに関連する軸がなかったり、タイプ固有情報が与えられていない場合。
DIERR_INPUTLOST
入力デバイスのアクセス権を失った。再取得しなければならない。
DIERR_INVALIDPARAM
無効なパラメータが戻ってくる関数に渡されたか、オブジェクトがその関数を呼び出せない状態になかった。この値は、標準の COM 戻り値である E_INVALIDARG に等しい。
DIERR_MOREDATA
要求情報の一部がバッファに納まらなかった。
DIERR_NOAGGREGATION
オブジェクトは、集合化をサポートしない。
DIERR_NOINTERFACE
オブジェクトは、指定のインターフェイスをサポートしていない。この値は、標準の COM 戻り値である E_NOINTERFACE に等しい。
DIERR_NOTACQUIRED
操作は、デバイスが取得されない限り実行できない。
DIERR_NOTBUFFERED
デバイスは、バッファリングされていない。バッファリングを有効にするには DIPROP_BUFFERSIZE プロパティを設定する。
DIERR_NOTDOWNLOADED
エフェクトがダウンロードされていない。
DIERR_NOTEXCLUSIVEACQUIRED
操作は、デバイスが DISCL_EXCLUSIVE モードで取得されていなければ実行できない。
DIERR_NOTFOUND
要求されたオブジェクトは存在しない。
DIERR_NOTINITIALIZED
このオブジェクトは、初期化されていなかった。
DIERR_OBJECTNOTFOUND
要求されたオブジェクトは存在しない。
DIERR_OLDDIRECTINPUTVERSION
アプリケーションは、より新しいバージョンの DirectInput を必要とする。
DIERR_OTHERAPPHASPRIO
ほかのアプリケーションの優先レベルの方が高いので、この呼び出しの実行がうまくいかない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。このエラーは、アプリケーションのデバイスに対するアクセス権が、フォアグラウンドアクセス権であるにもかかわらず、バックグラウンドにいるときに、デバイスを取得しようとした場合に返される。
DIERR_OUTOFMEMORY
DirectInput サブシステムが呼び出しを完了するのに十分なメモリを割り当てることができなかった。この値は、標準の COM 戻り値である E_OUTOFMEMORY に等しい。
DIERR_READONLY
指定のプロパティは変更できない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_REPORTFULL
送られる情報の方が、デバイスに送ることができる情報よりも多い。
DIERR_UNPLUGGED
この操作は、デバイスが接続されていない可能性を示す。
DIERR_UNSUPPORTED
この関数呼び出しは、この時点ではサポートされない。この値は、標準の COM 戻り値である E_NOTIMPL に等しい。
E_HANDLE
このパラメータは、このプロセスに関係する有効な最上位のウィンドウ ハンドルでなければならない。
E_PENDING
データは、まだ使用不可である。


DirectInput Visual Basic リファレンス

DirectInput の Visual Basic API のリファレンス情報は、以下のカテゴリに分類される。

  • クラス
  • 型
  • 列挙
  • キーボード キー
  • エラー コード


クラス

ここでは、以下の DirectInput クラスのメソッドに関するリファレンスを提供する。

  • DirectInput
  • DirectInputDevice
  • DirectInputDeviceInstance
  • DirectInputDeviceObjectInstance
  • DirectInputEffect
  • DirectInputEnumDeviceObjects
  • DirectInputEnumDevices
  • DirectInputEnumEffects


DirectInput

DirectInput クラスは、DirectInput システムを表す。アプリケーションは、このクラスの単一のオブジェクトを持ち、Windows コントロール パネルのインスタンスの起動のほか、利用可能なデバイスの列挙、デバイスの作成、およびデバイスの状態の取得を行うのに使用される。

DirectInput オブジェクトを取得するには、DirectX7.DirectInputCreate メソッドを使用する。

DirectInput クラスには、次のメソッドがある。

デバイス管理 | CreateDevice
 | GetDeviceStatus
 | GetDIEnumDevices
その他 | RunControlPanel


DirectInput.CreateDevice

DirectInput.CreateDevice メソッドは、指定された GUID に基づいてデバイスのインスタンスを作成し、初期化する。

object.CreateDevice(guid As String) As DirectInputDevice

パラメータ

object
DirectInput オブジェクトを表すオブジェクト式。
guid
目的の入力デバイスを表すインスタンス GUID。この GUID は、DirectInputEnumDevices.GetItem メソッドが返す DirectInputDeviceInstance オブジェクトから返される。次の文字列のいずれかを使用することもできる。
GUID_SysKeyboard
デフォルトのシステム キーボード。
GUID_SysMouse
デフォルトのシステム マウス。

戻り値

成功すれば、DirectInputDevice オブジェクトが返される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_OUTOFMEMORY

参照

GUID の使用


DirectInput.GetDeviceStatus

DirectInput.GetDeviceStatus メソッドは、デバイスがシステムにアタッチされているかどうかを判定する。

object.GetDeviceStatus(guid As String) As Boolean

パラメータ

object
DirectInput オブジェクトを表すオブジェクト式。
guid
目的の入力デバイスを表すインスタンス GUID。GUID は、DirectInputEnumDevices.GetItem メソッドが返すオブジェクトの DirectInputDeviceInstance.GetGuidInstance メソッドを使って取得される。次の文字列のいずれかを使用することもできる。
GUID_SysKeyboard
デフォルトのシステム キーボード。
GUID_SysMouse
デフォルトのシステム マウス。

戻り値

デバイスがアタッチされている場合に TRUE が返され、それ以外の場合は FALSE が返される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_GENERIC
DIERR_INVALIDPARAM

参照

GUID の使用


DirectInput.GetDIEnumDevices

DirectInput.GetDIEnumDevices メソッドは、DirectInputEnumDevices オブジェクトを返す。このオブジェクトを使って、現在アタッチされているデバイスや、コンピュータにアタッチされている可能性のあるデバイスを列挙する。

object.GetDIEnumDevices( _
  deviceType As CONST_DIDEVICETYPE, _
  flags As CONST_DIENUMDEVICESFLAGS) _
  As DirectInputEnumDevices

パラメータ

object
DirectInput オブジェクトを表すオブジェクト式。
deviceType
デバイス タイプのフィルタ。このパラメータがゼロなら、すべてのデバイス タイプが列挙される。ゼロ以外の場合は、次の列挙対象のデバイス タイプを示す CONST_DIDEVICETYPE 列挙の DIDEVTYPE_* 定数である。
DIDEVTYPE_MOUSE
マウスまたはマウス類似デバイス (トラックボールなど)。
DIDEVTYPE_KEYBOARD
キーボードまたはキーボード類似デバイス。
DIDEVTYPE_JOYSTICK
ジョイスティックまたは類似デバイス (ステアリング ホイールなど)。
DIDEVTYPE_DEVICE
上記のカテゴリに属さないデバイス。
flags
列挙の範囲を指定するフラグ値。このパラメータは、次の CONST_DIENUMDEVICESFLAGS 列挙の定数のいずれかである。このフラグがゼロ (DIEDFL_ALLDEVICES) であれば、インストール済みの全デバイスが列挙される。DIEDFL_ATTACHEDONLY であれば、システムに実際にアタッチされているデバイスのみが列挙される。

戻り値

成功すれば、DirectInputEnumDevices オブジェクトが返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

すべてのインストール済みデバイスは、たとえそれが現存していなくても列挙可能である。たとえば、ジョイスティックは、システムにインストールするが、当面コンピュータに接続しないでおくこともできる。

単一のハードウェアが、複数の DirectInput デバイス タイプとして機能することができる場合は、サポートする各デバイス タイプごとに返される。たとえば、組み込みマウス付きのキーボードは、1 つのキーボードとして、かつ、1 つのマウスとして列挙される。ただし、製品 GUID は各デバイスに対して同じである。


DirectInput.RunControlPanel

DirectInput.RunControlPanel メソッドは、ユーザーが新しい入力デバイスをインストールしたり、構成を変更したりできるように、Windows コントロール パネルを実行する。

object.RunControlPanel(hwndOwner As Long)

パラメータ

object
DirectInput オブジェクトを表すオブジェクト式。
hwndOwner
これ以降のユーザー インターフェイスの親ウィンドウとして使用するウィンドウのハンドル。このパラメータがゼロなら、親ウィンドウは使用されない。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDevice.RunControlPanel


DirectInputDevice

アプリケーションは、DirectInputDevice クラスのメソッドを使用して、DirectInput デバイスのアクセス権の取得と解放、デバイス プロパティと情報の管理、動作の設定、初期化の実行、およびデバイスのプロパティ シートの起動を行う。

DirectInputDevice オブジェクトを取得するには、DirectInput.CreateDevice メソッドを使用する。

DirectInputDevice クラスのメソッドは、以下のグループにまとめることができる。

アクセス | Acquire
 | SetCooperativeLevel
 | Unacquire
オブジェクト | GetDeviceObjectsEnum
 | GetObjectInfo
プロパティ | GetCapabilities
 | GetDeviceInfo
 | GetProperty
 | SetCommonDataFormat
 | SetDataFormat
 | SetProperty
データの取得 | GetDeviceData
 | GetDeviceState
 | GetDeviceStateJoystick
 | GetDeviceStateJoystick2
 | GetDeviceStateKeyboard
 | GetDeviceStateMouse
 | Poll
 | SetEventNotification
フォース フィードバック | CreateCustomEffect
 | CreateEffect
 | GetEffectsEnum
 | GetForceFeedbackState
 | SendForceFeedbackCommand
その他 | RunControlPanel
 | SendDeviceData


DirectInputDevice.Acquire

DirectInputDevice.Acquire メソッドは、入力デバイスのアクセス権を取得する。

object.Acquire()

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_OTHERAPPHASPRIO

注意

デバイスを取得する前に、DirectInputDevice.SetDataFormat メソッドまたは DirectInputDevice.SetCommonDataFormat メソッドを使ってデータ形式を設定しなければならない。

デバイスから入力データを取得する前に、デバイスを取得しなければならない。

参照

DirectInputDevice.Unacquire


DirectInputDevice.CreateCustomEffect

DirectInputDevice.CreateCustomEffect メソッドは、固定的な継続時間を持つ一連のコンスタント フォースで構成されるフォース フィードバック エフェクトを生成する。

object.CreateCustomEffect(effectinfo As DIEFFECT, _
    channels As Long, samplePeriod As Long, _
    nSamples As Long, sampledata() As Long) _
    As DirectInputEffect

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
effectinfo
エフェクトの一般的なパラメータを格納する DIEFFECT 型。
channels
このフォースによって影響されるチャネル (軸) の数。1 または 2 でなければならない。

チャネルが 1 つしか存在しない場合、エフェクトは、DIEFFECT 型の x メンバが指定する方向に回転する。カスタム エフェクトの回転をサポートしていないデバイスもある。

複数のチャネルが存在する場合、第 1 チャネルは x 軸に適用され、第 2 チャネルは y 軸に適用される。回転は許可されない。

samplePeriod
マイクロ秒単位のサンプリング間隔。「注意」を参照すること。
nSamples
sampledata 配列中の要素の数。
sampledata
マグニチュードの配列。channels が 2 以上であれば、各値は順番に割り当てられる。たとえば、channels が 2 の場合、配列の第 1 要素は x 軸、第 2 要素は y 軸、第 3 要素は x 軸に割り当てられる。チャネルがこれより多い場合も同様である。

注意

理論的には、samplePeriod は sampledata に含まれる有効な各マグニチュードの時間の長さである。他方、DIEFFECT.lSamplePeriod は、データのサンプリング間隔 (およびマグニチュードの変化間隔の最小時間) の長さである。配列内の各要素は、配列全体を反復処理する際に一度だけサンプリングする必要があるが、ドライバによってはどのような場合にも samplePeriod を無視することがあるので、lSamplePeriod と samplePeriod の値を同じにすることが望ましい。

参照

カスタム フォース


DirectInputDevice.CreateEffect

DirectInputDevice.CreateEffect メソッドは、フォース フィードバック エフェクトを生成する。デバイスが現在排他レベルで取得されている場合、エフェクトのダウンロードも行われる。

object.CreateEffect(effectGuid As String, _
  effectinfo As DIEFFECT) As DirectInputEffect

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
effectGuid
ハードウェア ドライバにより認識されるエフェクトの GUID の文字列表現。標準のエフェクトを表す次のエイリアスのいずれかを使用できる。

GUID_ConstantForce
GUID_RampForce
GUID_Square
GUID_Sine
GUID_Triangle
GUID_SawtoothUp
GUID_SawtoothDown
GUID_Spring
GUID_Damper
GUID_Inertia
GUID_Friction

effectinfo
作成されたエフェクトに対するパラメータを格納する DIEFFECT 構造体。

戻り値

成功すれば、DirectInputEffect オブジェクトが返される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_DEVICENOTREG
DIERR_DEVICEFULL
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

エラーが発生しない場合、エフェクトは作成済みで、エフェクトのパラメータは更新済みであるが、エフェクトをダウンロードする必要はなかった。エフェクトをダウンロードするには、デバイスを排他モードで取得しなければならない。

参照

DirectInputEffect.Download、DirectInputEffect.Start


DirectInputDevice.GetCapabilities

DirectInputDevice.GetCapabilities メソッドは、DirectInputDevice オブジェクトの能力を取得する。

object.GetCapabilities(caps As DIDEVCAPS)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
caps
デバイスの能力を格納する DIDEVCAPS 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputDevice.GetDeviceData

DirectInputDevice.GetDeviceData メソッドは、デバイスからバッファリング データを取得する。

object.GetDeviceData( _
  deviceObjectDataArray() As DIDEVICEOBJECTDATA, _
  flags As CONST_DIDGDDFLAGS) As Long

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
deviceObjectDataArray()
バッファリング データを受け取るための DIDEVICEOBJECTDATA 型の配列。
flags
データを取得方法を制御するフラグ。この値は、ゼロか、CONST_DIDGDDFLAGS 列挙の定数のいずれかを取ることができる。

戻り値

成功すれば、実際に取得されたバッファリング データの要素数が deviceObjectDataArray に返される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DI_BUFFEROVERFLOW
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTBUFFERED

注意

デバイス データを取得する前に、DirectInputDevice.SetDataFormat メソッドでデータ形式を設定し、DirectInputDevice.SetProperty メソッドでバッファ サイズを設定し、DirectInputDevice.Acquire メソッドでデバイスを取得しなければならない。

このメソッドを使って、SetProperty で作成したバッファから 1 つ以上の入力イベントを取得することができる。一度の呼び出しで、待機中のすべてのイベントを取得する必要はない。たとえば、単一の要素で構成される deviceObjectDataArray() に渡し、すべてのデータが返されるまで GetDeviceData をループ処理することができる。

バッファがオーバーフローすると、待機中のすべてのデータは失われ、DI_BUFFEROVERFLOW エラーが発生する。

参照

DirectInputDevice.Poll、ポーリングとイベント


DirectInputDevice.GetDeviceInfo

DirectInputDevice.GetDeviceInfo メソッドは、デバイスの識別情報を取得する。

object.GetDeviceInfo() As DirectInputDeviceInstance

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectInputDeviceInstance オブジェクトが返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputDevice.GetDeviceObjectsEnum

DirectInputDevice.GetDeviceObjectsEnum メソッドは、DirectInputEnumDeviceObjects オブジェクトを返す。このオブジェクトは、デバイスで利用可能なオブジェクトを列挙するのに使用する。デバイス オブジェクトは、通常、軸やボタンである。

object.GetDeviceObjectsEnum( _
  flags As CONST_DIDFTFLAGS) _
  As DirectInputEnumDeviceObjects

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
flags
列挙するオブジェクトのタイプを指定するフラグ。CONST_DIDFTFLAGS 列挙の 1 つ以上のメンバを使用できる。

戻り値

成功すれば、戻り値は DirectInputEnumDeviceObjects である。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DIDFT_FFACTUATOR および DIDFT_FFEFFECTTRIGGER のフラグを指定すると、列挙対象は、この 2 つのフラグで定義されているすべての基準を満たすオブジェクトに限定される。ほかのすべてのフラグの場合は、このカテゴリに指定したフラグで定義されている基準を満たすオブジェクトが列挙される。たとえば、(DIDFT_FFACTUATOR Or DIDFT_FFEFFECTTRIGGER) は、列挙対象をフォース フィードバック トリガ オブジェクトに限定する。これに対して、(DIDFT_FFEFFECTRIGGER Or DIDFT_TGLBUTTON Or DIDFT_PSHBUTTON) は、エフェクト トリガとして利用できる任意のボタンが列挙される。


DirectInputDevice.GetDeviceState

DirectInputDevice.GetDeviceState メソッドは、標準のキーボード、マウス、またはジョイスティック以外のデバイスの直接データを取得する。

object.GetDeviceState(cb As Long, state As Any)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
cb
先頭要素が state として渡される配列のサイズ。
state
デバイスの状態情報を受け取る配列の先頭要素。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice.SetCooperativeLevel メソッドで協調レベルを設定し、DirectInputDevice.SetDataFormat メソッドでデータ形式を設定し、DirectInputDevice.Acquire メソッドでデバイスを取得しなければならない。

参照

DirectInputDevice.GetDeviceStateJoystick、DirectInputDevice.GetDeviceStateJoystick2、DirectInputDevice.GetDeviceStateKeyboard、DirectInputDevice.GetDeviceStateMouse、DirectInputDevice.SetDataFormat、バッファリング データと直接データ


DirectInputDevice.GetDeviceStateJoystick

DirectInputDevice.GetDeviceStateJoystick メソッドは、ジョイスティック デバイスから直接データを取得する。

object.GetDeviceStateJoystick(state As DIJOYSTATE)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
state
デバイスの現在の状態を受け取る DIJOYSTATE 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice.SetCooperativeLevel メソッドで協調レベルを設定し、DirectInputDevice.SetCommonDataFormat メソッドでデータ形式を設定し、DirectInputDevice.Acquire メソッドでデバイスを取得しなければならない。

参照

DirectInputDevice.Poll


DirectInputDevice.GetDeviceStateJoystick2

DirectInputDevice.GetDeviceStateJoystick2 メソッドは、拡張機能付きのジョイスティック デバイスから直接データを取得する。

object.GetDeviceStateJoystick2(state As DIJOYSTATE2)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
state
デバイスの現在の状態を受け取る DIJOYSTATE2 型。データ形式は、先に DirectInputDevice.SetDataFormat メソッドを呼び出すことで設定される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice.SetCooperativeLevel メソッドで協調レベルを設定し、DirectInputDevice.SetCommonDataFormat メソッドでデータ形式を設定し、DirectInputDevice.Acquire メソッドでデバイスを取得しなければならない。

参照

DirectInputDevice.Poll、ポーリングとイベント


DirectInputDevice.GetDeviceStateKeyboard

DirectInputDevice.GetDeviceStateKeyboard メソッドは、キーボード デバイスから直接データを取得する。

object.GetDeviceStateKeyboard(state As DIKEYBOARDSTATE)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
state
デバイスの現在の状態を受け取る DIKEYBOARDSTATE 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice.SetCooperativeLevel メソッドで協調レベルを設定し、DirectInputDevice.SetCommonDataFormat メソッドでデータ形式を設定し、DirectInputDevice.Acquire メソッドでデバイスを取得しなければならない。

参照

DirectInputDevice.Poll


DirectInputDevice.GetDeviceStateMouse

DirectInputDevice.GetDeviceStateMouse メソッドは、マウス デバイスから直接データを取得する。

object.GetDeviceStateMouse(state As DIMOUSESTATE)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
state
デバイスの現在の状態を受け取る DIMOUSESTATE 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice.SetCooperativeLevel メソッドで協調レベルを設定し、DirectInputDevice.SetCommonDataFormat メソッドでデータ形式を設定し、DirectInputDevice.Acquire メソッドでデバイスを取得しなければならない。

参照

DirectInputDevice.Poll


DirectInputDevice.GetEffectsEnum

DirectInputDevice.GetEffectsEnum メソッドは、標準のエフェクトやデバイス メーカーにより設計されたエフェクトなど、デバイスがサポートするフォース フィードバック エフェクトを列挙する。

object.GetEffectsEnum( _
  effType As CONST_DIEFTFLAGS) As DirectInputEnumEffects

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
effType
列挙対象のエフェクト タイプを指定する CONST_DIEFTFLAGS 列挙のうち、次のいずれか 1 つのフラグ。

DIEFT_ALL
DIEFT_CONDITION
DIEFT_CONSTANTFORCE
DIEFT_CUSTOMFORCE
DIEFT_HARDWARE
DIEFT_PERIODIC
DIEFT_RAMPFORCE

戻り値

DirectInputEnumEffects オブジェクトを返す。このオブジェクトのメソッドは、エフェクトに関する情報の取得に使用する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputDevice.GetForceFeedbackState

DirectInputDevice.GetForceFeedbackState メソッドは、デバイスのフォース フィードバック システムの状態を取得する。

object.GetForceFeedbackState() As CONST_DIGFFSFLAGS

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。

戻り値

成功すれば、デバイスのフォース フィードバック システムの現在の状態を表す CONST_DIGFFSFLAGS 列挙からのフラグが返される。

DirectInput の将来のバージョンで、フラグが追加定義される可能性もある。アプリケーションは、現在未定義のフラグをすべて無視する必要がある。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。


DirectInputDevice.GetObjectInfo

DirectInputDevice.GetObjectInfo メソッドは、ボタンや軸などのデバイス オブジェクトに関する情報を取得する。

object.GetObjectInfo( _
  Obj As Long, _
  how As CONST_DIPHFLAGS) _
  As DirectInputDeviceObjectInstance

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
Obj
情報を取得するオブジェクトを識別する値。このパラメータの解釈は、how パラメータで指定されている値に依存する。
how
Obj パラメータの解釈方法を指定する値。この値は、CONST_DIPHFLAGS 列挙の定数のいずれかを取ることができる。

戻り値

DirectInputDeviceObjectInstance オブジェクトを返す。このオブジェクトのメソッドは、オブジェクトに関する情報の取得に使用する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_OBJECTNOTFOUND


DirectInputDevice.GetProperty

DirectInputDevice.GetProperty メソッドは、入力デバイスに関する情報を取得する。

object.GetProperty( _
  guid As String, _
  propertyInfo As Any)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
guid
取得するプロパティの識別子。入力デバイスには次のプロパティが定義されており、文字列として渡すことができる。
DIPROP_AUTOCENTER
デバイス オブジェクトが自動センタリングを行うかどうかを指定する。詳細については、「DirectInputDevice.SetProperty」を参照すること。
DIPROP_AXISMODE
軸モードを取得する。取得される値は DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL である (「CONST_DINPUT」列挙を参照)。
DIPROP_BUFFERSIZE
入力バッファ サイズを取得する。バッファ サイズは、DirectInputDevice.GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。
DIPROP_DEADZONE
0 ～ 10,000 の範囲でジョイスティックの無効ゾーンの値を取得する。ここで、0 は無効ゾーンが存在しないこと、5,000 は無効ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸が無効ゾーン内にあると、軸の範囲の中心にあるものと報告される。
DIPROP_FFGAIN
デバイスのゲインを取得する。詳細については、「DirectInputDevice.SetProperty」を参照すること。
DIPROP_FFLOAD
デバイスのメモリ ロードを取得する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPLONG 型の lHow メンバは DIPH_DEVICE でなければならない。

lData メンバは、0 ～ 100 の範囲にある値を格納する。この値は、使用中のデバイス メモリのパーセント数を示す。

DIPROP_GRANULARITY
入力の細分度を取得する。細分度は、オブジェクトが移動を報告する最小距離を表す。多くの軸オブジェクトの細分度は 1 であり、あらゆる値を取ることができる。軸によっては、より大きな細分度を持つものもある。たとえば、マウスのホイール軸の細分度は 20 にすることもできる。報告される位置変化はすべて、20 の倍数となる。つまり、ユーザーがホイールをゆっくり回転させると、デバイスは位置を 0、20、40 などと報告する。

これは読み取り専用プロパティなので、DirectInputDevice.SetProperty メソッドを呼び出しても、値を設定することはできない。

DIPROP_RANGE
オブジェクトが報告できる値の範囲を取得する。取得された最小値および最大値は、割り当てられた DIPROPRANGE 型の lMin および lMax メンバに設定される。

一部のデバイスでは、これは読み取り専用プロパティである。DirectInputDevice.SetProperty メソッドを呼び出しても、値を設定することはできない。

DIPROP_SATURATION
0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を取得する。飽和レベルとは、軸が極限位置にあると見なされる点のことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (無効ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。
propertyInfo
単一の値を受け取る DIPROPLONG 型。または、1 組の値を受け取る DIPROPRANGE 型。この型の lObj、lHow、および lSize メンバは、メソッドを呼び出す前に初期化しなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

参照

DirectInputDevice.SetProperty


DirectInputDevice.Poll

DirectInputDevice.Poll メソッドは、DirectInput デバイス上のポーリング対象オブジェクトから、利用可能なデータを作成する。デバイスにポーリングが必要ないときにこのメソッドを呼び出しても、エフェクトは一切ない。ポーリングする必要があるデバイスが定期的にポーリングされない場合、このデバイスから新しいデータは取得されない。このメソッドを呼び出すと、DirectInput はデバイス状態を更新し、バッファリング データが使用可能な場合は入力イベントを生成し、通知が有効であれば通知イベントを設定する。

object.Poll()

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_NOTACQUIRED

注意

デバイスをポーリングする前に、DirectInputDevice.SetDataFormat メソッドか、DirectInputDevice.SetCommonDataFormat メソッドでデータ形式を設定し、DirectInputDevice.Acquire メソッドでデバイスを取得しなければならない。


DirectInputDevice.RunControlPanel

DirectInputDevice.RunControlPanel メソッドは、デバイスに関連付けられたコントロール パネルのプロパティ シートを開く。デバイスにプロパティ シートが関連付けられていない場合、デフォルトのプロパティが表示される。

object.RunControlPanel(hwnd As Long)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
hwnd
親ウィンドウのハンドル。このパラメータがゼロなら、親ウィンドウは使用されない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のエラー コードが設定される。

DIERR_INVALIDPARAM


DirectInputDevice.SendDeviceData

DirectInputDevice.SendDeviceData メソッドは、出力を受け付けるデバイスにデータを送信する。デバイスは、取得済みの状態でなければならない。

object.SendDeviceData(count As Long, _
  data() As DIDEVICEOBJECTDATA, _
  flags As CONST_DESDDFLAGS) As Long

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
count
data 内の要素数。
data
デバイスに送信するデータを格納した DIDEVICEOBJECTDATA 型の配列。

DIDEVICEOBJECTDATA 型の lOfs フィールドには、データの送信先であるデバイス オブジェクトのインスタンス識別子 (データ オフセットではない) を格納しなければならない (「DirectInputDeviceObjectInstance.GetType」を参照)。lTimeStamp メンバと lSequence メンバはゼロでなければならない。

flags
データの送信方法を制御するフラグ。ゼロまたは次の値を取ることができる。
DISDD_CONTINUE
送信されるデバイス データは、以前に送信されたデバイス データに上書きされる。「注意」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED

注意

個別のデータ要素が特定の順序で送信されるという保証はない。しかし、SendDeviceData の呼び出しが成功した場合、送信されたデータの間に別のデータが紛れ込むことはない。さらに、複数のデータが 1 回の呼び出しで同じオブジェクトに送信される場合、どのデータが送信されるかは特定されない。

たとえば、データをパケット単位で送信できるデバイスがある。2 つの情報を記述するパケットをそれぞれ A と B とする。アプリケーションが 3 つのデータ要素 (B = 2、A = 1、B =0) を送信しようとするとどうなるだろうか。

実際のデバイスに送信されるパケットは、1 つである。パケットの A フィールドの値は 1、そしてパケットの B フィールドの値は 2 か 0 になる。

データを指定どおりにデバイスに送信しなければならない場合は、SendDeviceData を 3 回呼び出し、呼び出しごとにデータ要素を 1 つずつ送信しなければならない。

最初の呼び出しに応答して、A フィールドがブランク、B フィールドの値が 2 のパケットをデバイスに送信する。

2 回目の呼び出しでは、A フィールドの値が 1、B フィールドがブランクのパケットを送信する。

最後の 3 回目の呼び出しで、A フィールドがブランク、B フィールドの値が 0 のパケットを送信する。

DISDD_CONTINUE が設定されている場合、送信されたデバイス データは以前に送信されたデバイス データに上書きされる。フラグの設定がなければ、送信されるデバイス データはまったく新しいものとして処理される。

たとえば、Button0 および Button1 の 2 つのボタン出力をサポートするデバイスがあるとする。アプリケーションが最初に SendDeviceData を呼び出して "Button0 押下" を渡すと、デバイスには、"Button0 押下、Button1 未押下" という形式のパケットが送信される。次に、アプリケーションがもう一度 SendDeviceData を呼び出して "Button1 押下" と DISDD_CONTINUE フラグを渡すと、デバイスには、"Button0 押下、Button1 押下" という形式のパケットが送信される。しかし、アプリケーションが DISDD_CONTINUE フラグを渡さなかった場合、デバイスに送信されるパケットは、"Button0 未押下、Button1 押下" となる。


DirectInputDevice.SendForceFeedbackCommand

DirectInputDevice.SendForceFeedbackCommand メソッドは、デバイスのフォース フィードバック システムにコマンドを送信する。

object.SendForceFeedbackCommand(flags As Long)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
flags
目的の状態変化を示す単一の値。この値は、CONST_DISFFCFLAGS 列挙のメンバのいずれかを取ることができる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED


DirectInputDevice.SetCommonDataFormat

DirectInputDevice.SetCommonDataFormat メソッドは、標準デバイスの入力データ形式を設定する。

object.SetCommonDataFormat( _
  format As CONST_DICOMMONDATAFORMATS)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
format
デバイスで使用されるデータ形式を識別する CONST_DICOMMONDATAFORMATS 列挙のいずれか。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_ACQUIRED
DIERR_INVALIDPARAM

注意

DirectInputDevice.Acquire メソッドでデバイスを取得する前に、データ形式を設定しなければならない。データ形式は、一度設定するだけでよい。データ形式は、デバイスが取得されている間は変更できない。

参照

DirectInputDevice.SetDataFormat


DirectInputDevice.SetCooperativeLevel

DirectInputDevice.SetCooperativeLevel メソッドは、デバイスのインスタンスに協調レベルを設定する。協調レベルは、このインスタンスが、同じデバイスのほかのインスタンス、およびシステムのこれ以外の部分との間で、どのように対話するかを決める。

object.SetCooperativeLevel(hwnd As Long, _
  flags As CONST_DISCLFLAGS)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
hwnd
デバイスに関連付けられているウィンドウ ハンドル。このパラメータは、このプロセスに属する最上位の有効なウィンドウ ハンドルでなければならない。デバイスに関連付けられるウィンドウは、DirectInput デバイスの中でアクティブである間は、破壊してはならない。
flags
デバイスに関連付ける協調レベルを表すフラグ。CONST_DISCLFLAGS 列挙の定数である。

次のフラグの組み合わせが有効である。
フラグ | 意味 | 対象
DISCL_NONEXCLUSIVE Or DISCL_BACKGROUND | ほかのアプリケーションは、排他モードまたは非排他モードにあるデバイスを取得できる。このアプリケーションは、データにいつでもアクセスできる。 | すべて。
DISCL_NONEXCLUSIVE Or DISCL_FOREGROUND | ほかのアプリケーションは、排他モードまたは非排他モードにあるデバイスを取得できる。このアプリケーションは、フォアグラウンドにあるときのみデータにアクセスできる。 | すべて。
DISCL_EXCLUSIVE Or DISCL_BACKGROUND | ほかのアプリケーションは、非排他モードにあるデバイスを取得できる。このアプリケーションは、データにいつでもアクセスできる。 | ジョイスティック。
DISCL_EXCLUSIVE Or DISC_FOREGROUND | ほかのアプリケーションは、非排他モードにあるデバイスを取得できる。このアプリケーションは、フォアグラウンドにあるときのみデータにアクセスできる。 | すべて。マウスの場合、有効だが Windows はカーソルを表示できない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_INVALIDHANDLE

注意

2 つのアプリケーション (または同一アプリケーションの 2 つのインスタンス) が同時に 1 つのデバイスを排他モードで取得することはできない。これは主にセキュリティ面での機能である。これにより、1 つのアプリケーションからの入力が、同時に実行されている別のアプリケーションに流れることはない。

システム マウスが排他モードで取得されると、マウス ポインタは、デバイスが解放されるまで画面から消去される。

アプリケーションは、DirectInputDevice.Acquire メソッドでデバイスを取得する前に、このメソッドを呼び出す必要がある。

参照

協調レベル


DirectInputDevice.SetDataFormat

DirectInputDevice.SetDataFormat メソッドは、標準のキーボードやマウス以外の、DirectInput デバイスのデータ形式を設定する。

object.SetDataFormat(format As DIDATAFORMAT, _
  formatArray() As DIOBJECTDATAFORMAT))

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
format
デバイスが返すデータ形式を表す DIDATAFORMAT 型。
formatArray
デバイス上のオブジェクトのデータ形式を表す DIOBJECTDATAFORMAT 型の配列。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_ACQUIRED
DIERR_INVALIDPARAM

注意

DirectInputDevice.Acquire メソッドでデバイスを取得する前に、データ形式を設定しなければならない。データ形式は、一度設定するだけでよい。データ形式は、デバイスが取得されている間は変更できない。

参照

DirectInputDevice.SetCommonDataFormat


DirectInputDevice.SetEventNotification

DirectInputDevice.SetEventNotification メソッドは、イベント通知ステータスを設定する。このメソッドは、デバイス状態が変化したときに設定されるイベントを指定する。イベント通知をオフにするためにも使用される。

object.SetEventNotification(hEvent As Long)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
hEvent
デバイス状態が変化したときに設定されるイベントのハンドル。通知を無効にするにはゼロを設定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_ACQUIRED
DIERR_HANDLEEXISTS
DIERR_INVALIDPARAM

注意

デバイス状態の変更は次のいずれかに定義される。

  • 軸の位置の変更
  • ボタンの状態 (押した状態または離した状態)
  • 視点コントロールの方向の変更
  • 取得の喪失

イベント ハンドルを破壊する前に、hEvent パラメータにゼロを設定して、このメソッドを呼び出さなければならない。

イベント通知ハンドルは、デバイスが取得されている間は変更できない。

参照

ポーリングとイベント、DirectXEvent


DirectInputDevice.SetProperty

DirectInputDevice.SetProperty メソッドは、デバイスの動作を定義するプロパティを設定する。

object.SetProperty( _
  guid As String, _
  propertyInfo As Any)

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。
guid
設定対象のプロパティの識別子。入力デバイスには次のプロパティ値が定義されており、文字列として渡すことができる。
DIPROP_AXISMODE
軸モードを設定する。設定値 (CONST_DINPUT 列挙の DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL) は、割り当てられた DIPROPLONG 型の lData メンバに指定しなければならない。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPLONG 型の lHow メンバは DIPH_DEVICE でなければならない。

DIPROP_BUFFERSIZE
入力バッファ サイズを設定する。「注意」を参照すること。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPLONG 型の lHow メンバは DIPH_DEVICE でなければならない。

DIPROP_CALIBRATIONMODE
DirectInput が取得するデータが、キャリブレーション済みかキャリブレーション前かを、アプリケーションが指定できるようにする。デフォルトでは、DirectInput はキャリブレーション済みデータを取り出す。

デバイス全体に対してキャリブレーション モードを設定することは、それぞれの軸に対してキャリブレーション モードを設定することと同じ意味を持つ。

DIPROPLONG 型の lData メンバは次のいずれか 1 つの値を取ることができる。

DIPROPCALIBRATIONMODE_COOKED:DirectInput は、キャリブレーション情報の適用後のデータを返す。これがデフォルト モードである。

DIPROPCALIBRATIONMODE_RAW:DirectInput は、キャリブレーション前の未加工データを返す。このモードは通常、コントロール パネル型のアプリケーションでのみ使用される。

デバイスを未加工モードに設定すると、無効ゾーン、飽和値、および範囲の設定が無視される。

DIPROP_DEADZONE
0 ～ 10,000 の範囲でジョイスティックの無効ゾーンの値を設定する。ここで、0 は無効ゾーンが存在しないこと、5,000 は無効ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸が無効ゾーン内にあると、軸の範囲の中心にあるものと報告される。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

DIPROP_RANGE
オブジェクトが報告可能な値の範囲を設定する。最小値および最大値は、割り当てられた DIPROPRANGE 型の lMin メンバと lMax メンバから取得される。

一部のデバイスでは、これは読み取り専用プロパティである。

範囲の大小を逆にはできない。lMax は、lMin より大きくなければならない。

DIPROP_SATURATION
0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を設定する。飽和レベルとは、軸が極限位置にあると見なされる点のことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (無効ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

propertyInfo
単一の値を取るプロパティのデータを格納する DIPROPLONG 型。または、1 組の値を取るプロパティのデータを格納する DIPROPRANGE 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

注意

バッファ サイズは、DirectInputDevice.GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。DIPROPLONG 型の lData メンバ中のバッファ サイズが大きすぎてデバイスがサポートできない場合は、サポート可能な最大バッファ サイズが設定される。要求したバッファ サイズが設定されたかどうかを確認するには、バッファ サイズ プロパティを取得して、設定しようとした値とその結果を比較する。

参照

DirectInputDevice.GetProperty


DirectInputDevice.Unacquire

DirectInputDevice.Unacquire メソッドは、入力デバイスのアクセス権を解放する。

object.Unacquire()

パラメータ

object
DirectInputDevice オブジェクトを表すオブジェクト式。

エラー コード

なし。

参照

DirectInputDevice.Acquire


DirectInputDeviceInstance

DirectInputDeviceInstance クラスは、デバイスのインスタンスに関する情報の取得に使用される。

このクラスのオブジェクトは、DirectInputDevice.GetDeviceInfo メソッドと DirectInputEnumDevices.GetItem メソッドにより返される。

DirectInputDeviceInstance クラスには、次のメソッドがある。

情報 | GetDevType
 | GetGuidFFDriver
 | GetGuidInstance
 | GetGuidProduct
 | GetInstanceName
 | GetProductName
 | GetUsage
 | GetUsagePage


DirectInputDeviceInstance.GetDevType

DirectInputDeviceInstance.GetDevType メソッドは、デバイス タイプとサブタイプを取得する。

object.GetDevType() As Long

パラメータ

object
DirectInputDeviceInstance オブジェクトを表すオブジェクト式。

戻り値

デバイス タイプ識別子が返される。この値は、タイプ (最下位バイト) とサブタイプの組み合わせ (最下位から 1 つ上位のバイト) であり、オプションで Or を使って DIDEVTYPE_HID を組み合わせられる。このフラグは HID (Human Interface Device) を指定する。以下は、CONST_DIDEVICETYPE 列挙の定数である。

デバイス タイプ
DIDEVTYPE_MOUSE
マウスまたはマウス類似デバイス (トラックボールなど)。
DIDEVTYPE_KEYBOARD
キーボードまたはキーボード類似デバイス。
DIDEVTYPE_JOYSTICK
ジョイスティックまたは類似デバイス (ステアリング ホイールなど)。
DIDEVTYPE_DEVICE
上記のカテゴリに属さないデバイス。
マウス サブタイプ
DIDEVTYPEMOUSE_UNKNOWN
サブタイプは確定できない。
DIDEVTYPEMOUSE_TRADITIONAL
デバイスは、従来のマウスである。
DIDEVTYPEMOUSE_FINGERSTICK
デバイスは、フィンガースティックである。
DIDEVTYPEMOUSE_TOUCHPAD
デバイスは、タッチパッドである。
DIDEVTYPEMOUSE_TRACKBALL
デバイスは、トラックボールである。
キーボード サブタイプ
DIDEVTYPEKEYBOARD_UNKNOWN
サブタイプは確定できない。
DIDEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 キー キーボード
DIDEVTYPEKEYBOARD_OLIVETTI
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 キーボード
ジョイスティック サブタイプ
DIDEVTYPEJOYSTICK_UNKNOWN
サブタイプは確定できない。
DIDEVTYPEJOYSTICK_TRADITIONAL
従来のジョイスティック。
DIDEVTYPEJOYSTICK_FLIGHTSTICK
フライト シミュレーション用に最適化されているジョイスティック。
DIDEVTYPEJOYSTICK_GAMEPAD
主要目的がボタン入力を行うことにあるデバイス。
DIDEVTYPEJOYSTICK_RUDDER
偏揺制御用のデバイス。
DIDEVTYPEJOYSTICK_WHEEL
車のハンドル用のデバイス。
DIDEVTYPEJOYSTICK_HEADTRACKER
ユーザーの頭の動きを追跡するデバイス。
HID
DIDEVTYPE_HID
デバイスは、HID (Human Interface Device) プロトコルを使用する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

ホイールなど、デバイスの特定のサブタイプを探すには、タイプとサブタイプの両方をチェックする必要がある。


DirectInputDeviceInstance.GetGuidFFDriver

DirectInputDeviceInstance.GetGuidFFDriver メソッドは、フォース フィードバック ドライバの一意な識別子を返す。

object.GetGuidFFDriver() As String

パラメータ

object
DirectInputDeviceInstance オブジェクトを表すオブジェクト式。

戻り値

フォース フィードバック ドライバの GUID が文字列形式で返される。この識別子は、ドライバのメーカーが定める。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectInputDeviceInstance.GetGuidInstance

DirectInputDeviceInstance.GetGuidInstance メソッドは、デバイスのインスタンスの一意な識別子を返す。

object.GetGuidInstance() As String

パラメータ

object
DirectInputDeviceInstance オブジェクトを表すオブジェクト式。

戻り値

デバイス インスタンスの GUID が文字列形式で返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

アプリケーションは、このインスタンス GUID を構成ファイルに保存し、後で使用することもできる。インスタンス GUID は、コンピュータごとに固有である。1 つのコンピュータから取得されるインスタンス GUID は、ほかのコンピュータ上のインスタンス GUID とは無関係である。

参照

DirectInputDeviceInstance.GetGuidProduct、GUID の使用


DirectInputDeviceInstance.GetGuidProduct

DirectInputDeviceInstance.GetGuidProduct メソッドは、デバイスに対するメーカーの一意な識別子を取得する。

object.GetGuidProduct() As String

パラメータ

object
DirectInputDeviceInstance オブジェクトを表すオブジェクト式。

戻り値

製品の GUID が文字列形式で返される。この識別子は、デバイス メーカーが定める。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance.GetGuidInstance、GUID の使用


DirectInputDeviceInstance.GetInstanceName

DirectInputDeviceInstance.GetInstanceName メソッドは、デバイス インスタンスの名前を取得する。

object.GetInstanceName() As String

パラメータ

object
DirectInputDeviceInstance オブジェクトを表すオブジェクト式。

戻り値

インスタンスの登録名が返される。たとえば、"Joystick 1" など。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance.GetProductName


DirectInputDeviceInstance.GetProductName

DirectInputDeviceInstance.GetProductName メソッドは、デバイスの製品名を取得する。

object.GetProductName() As String

パラメータ

object
DirectInputDeviceInstance オブジェクトを表すオブジェクト式。

戻り値

製品の登録名が返される。たとえば、"Microsoft SideWinder" など。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance.GetInstanceName


DirectInputDeviceInstance.GetUsage

DirectInputDeviceInstance.GetUsage メソッドは、HID (Human Interface Devices) の使用コードを取得する。

object.GetUsage() As Integer

パラメータ

object
DirectInputDeviceInstance オブジェクトを表すオブジェクト式。

戻り値

デバイスが HID である場合、使用コードが返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance.GetUsagePage


DirectInputDeviceInstance.GetUsagePage

DirectInputDeviceInstance.GetUsagePage メソッドは、HID (Human Interface Devices) の使用ページを取得する。

object.GetUsagePage() As Integer

パラメータ

object
DirectInputDeviceInstance オブジェクトを表すオブジェクト式。

戻り値

デバイスが HID である場合、HID 使用ページが返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance.GetUsage


DirectInputDeviceObjectInstance

DirectInputDeviceObjectInstance クラスは、ボタンや軸など、DirectInput デバイス上のオブジェクトを表す。

DirectInputDeviceObjectInstance オブジェクトは、DirectInputDevice.GetObjectInfo メソッドと DirectInputEnumDeviceObjects.GetItem メソッドにより返される。

このクラスには、次のメソッドがある。

情報 | GetCollectionNumber
 | GetDesignatorIndex
 | GetDimension
 | GetExponent
 | GetFlags
 | GetGuidType
 | GetName
 | GetOfs
 | GetType
 | GetUsage
 | GetUsagePage


DirectInputDeviceObjectInstance.GetCollectionNumber

DirectInputDeviceObjectInstance.GetCollectionNumber メソッドは、デバイス オブジェクトの所属先である HID リンク コレクションの番号を取得する。

object.GetCollectionNumber() As Integer

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

デバイスが HID (Human Interface Device) であり、オブジェクトがコレクションに属しているのであれば、コレクションの番号が返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetDesignatorIndex

DirectInputDeviceObjectInstance.GetDesignatorIndex メソッドは、HID (Human Interface Device) 上のオブジェクトの指定インデックスを取得する。

object.GetDesignatorIndex() As Integer

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

HID 物理記述子の指定を参照するインデックスが返される。この数値は、デバイス オブジェクトについての追加情報を取得するために、HID 解釈ライブラリの関数に渡される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetDimension

DirectInputDeviceObjectInstance.GetDimension メソッドは、オブジェクトの値を報告する次元単位に対する HID コードを取得する。

object.GetDimension() As Long

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

オブジェクトの値を報告する次元単位のコードが返される (判明している場合)。不明な場合はゼロとなる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceObjectInstance.GetExponent


DirectInputDeviceObjectInstance.GetExponent

DirectInputDeviceObjectInstance.GetExponent メソッドは、デバイス オブジェクトの次元単位に関連付ける指数を取得する。

object.GetExponent() As Integer

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

単位に付ける指数が返される (判明している場合)。次元単位は常に整数であるので、整数以外のタイプに単位を変換するには指数が必要となる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceObjectInstance.GetDimension


DirectInputDeviceObjectInstance.GetFlags

DirectInputDeviceObjectInstance.GetFlags メソッドは、デバイス オブジェクトに関連付けられたフラグを取得する。

object.GetFlags() As CONST_DIDEVICEOBJINSTANCEFLAGS

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

オブジェクトのその他の属性を表すフラグが返される。戻り値は、CONST_DIDEVICEOBJINSTANCEFLAGS 列挙の 1 つ以上のメンバで構成される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetGuidType

DirectInputDeviceObjectInstance.GetGuidType メソッドは、オブジェクト タイプの一意な識別子を取得する。

object.GetGuidType() As String

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

オブジェクト タイプの一意な識別子を表す次の文字列識別子のいずれかが返される。オブジェクト タイプが次の一覧にない GUID を持つ場合、実際の GUID を表す文字列が返される。オブジェクト タイプが GUID を持たない場合、空の文字列が返される。

GUID_XAxis
水平軸。たとえば、マウスの左右の動きを表すことができる。
GUID_YAxis
垂直軸。たとえば、マウスの前後の動きを表すことができる。
GUID_ZAxis
z 軸。たとえば、マウス上のホイールの回転、またはジョイスティックのスロットル制御の移動を表すことができる。
GUID_RxAxis
x 軸を中心とする回転。
GUID_RyAxis
y 軸を中心とする回転。
GUID_RzAxis
z 軸を中心とする回転 (方向舵のコントロールでよく使われる)。
GUID_Slider
スライド軸。
GUID_Button
マウスのボタン。
GUID_Key
キーボード上のキー。
GUID_POV
視点インジケータまたは視点ハット。
GUID_Unknown
確定できない。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetName

DirectInputDeviceInstance.GetName メソッドは、デバイス オブジェクトの名前を取得する。

object.GetName() As String

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

オブジェクトの名前が返される。たとえば、"X-Axis" または "Right Shift" など。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetOfs

DirectInputDeviceObjectInstance.GetOfs メソッドは、デバイスのデータ形式内の、デバイス オブジェクトのデータのオフセットを取得する。

object.GetOfs() As Long

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

データ形式内のオフセットで、このオブジェクトに報告されるデータの位置が返される。この値は、メソッド呼び出しにおけるオブジェクトと DIPH_BYOFFSET フラグを受け取るタイプの中のオブジェクトを識別するために使用される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDevice.GetObjectInfo、DIPROPLONG、DIPROPRANGE


DirectInputDeviceObjectInstance.GetType

DirectInputDeviceObjectInstance.GetType メソッドは、オブジェクトのタイプと一意な識別子を取得する。

object.GetType() As Long

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

オブジェクトを表すデバイス タイプ。オブジェクト タイプ (軸、ボタンなど) を表す CONST_DIDFTFLAGS フラグの組み合わせであり、中央の 16 ビットには、オブジェクト インスタンス番号が格納される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

オブジェクト インスタンス ID を取得するには、次の処理を実行する。

Dim ObjID as Long
ObjID = (diObj.GetType And &HFFFF00) \ 256


DirectInputDeviceObjectInstance.GetUsage

DirectInputDeviceObjectInstance.GetUsage メソッドは、デバイス オブジェクトに対する HID (Human Interface Devices) の使用コードを取得する。

object.GetUsage() As Integer

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

オブジェクトに関連する HID 使用状況が返される (判明した場合)。HID は常に使用状況を報告する。非 HID デバイスはオプションで使用状況を報告する。非 HID デバイスが報告しない場合、このパラメータの値はゼロになる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceObjectInstance.GetUsagePage


DirectInputDeviceObjectInstance.GetUsagePage

DirectInputDeviceObjectInstance.GetUsagePage メソッドは、デバイス オブジェクトに対する HID (Human Interface Devices) の使用ページを取得する。

object.GetUsagePage() As Integer

パラメータ

object
DirectInputDeviceObjectInstance オブジェクトを表すオブジェクト式。

戻り値

オブジェクトに関連する HID 使用ページが返される (判明した場合)。HID は常に使用ページを報告する。非 HID デバイスはオプションで使用ページを報告する。非 HID デバイスが報告しない場合、このパラメータの値はゼロになる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceObjectInstance.GetUsage


DirectInputEffect

DirectInputEffect クラスのオブジェクトは、アプリケーションが生成するフォース フィードバック エフェクトを表す。オブジェクトを作成するには、DirectInputDevice.CreateEffect メソッドを使用する。

このクラスには、次のメソッドがある。

情報 | GetEffectGuid
 | GetEffectStatus
 | GetParameters
操作 | Download
 | SetParameters
 | Start
 | Stop
 | Unload


DirectInputEffect.Download

DirectInputEffect.Download メソッドは、デバイスにエフェクトを配置する。そのエフェクトがデバイス上に既に存在する場合、DirectInputEffect.SetParameters メソッドで設定された値に一致するように、既存のエフェクトが更新される。

object.Download()

パラメータ

object
DirectInputEffect オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

エフェクトの再生中にエフェクトを更新することは有効である。この操作の意味は、DirectInputEffect.SetParameters のリファレンスの中で説明されている。


DirectInputEffect.GetEffectGuid

DirectInputEffect.GetEffectGuid メソッドは、DirectInputEffect オブジェクトが表すエフェクトの GUID または GUID エイリアスを取得する。

object.GetEffectGuid() As String

パラメータ

object
DirectInputEffect オブジェクトを表すオブジェクト式。

戻り値

DirectInputDevice.CreateEffect に渡す GUID またはエイリアスが返される (たとえば、"GUID_ConstantForce" など)。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectInputEffect.GetEffectStatus

DirectInputEffect.GetEffectStatus メソッドは、エフェクトのステータスを取得する。

object.GetEffectStatus() As Long

パラメータ

object
DirectInputEffect オブジェクトを表すオブジェクト式。

戻り値

エフェクトのステータス フラグが返される。値はゼロか、次の CONST_DIEGESFLAGS 列挙の定数のいずれかを取ることができる。

DIEGES_PLAYING
エフェクトは再生中である。
DIEGES_EMULATED
エフェクトはエミュレートされる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputEffect.GetParameters

DirectInputEffect.GetParameters メソッドは、エフェクトに関する情報を取得する。

object.GetParameters(effectinfo As DIEFFECT)

パラメータ

object
DirectInputEffect オブジェクトを表すオブジェクト式。
effectinfo
エフェクト パラメータを受け取る DIEFFECT 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_MOREDATA
DIERR_NOTINITIALIZED


DirectInputEffect.SetParameters

DirectInputEffect.SetParameters メソッドは、エフェクトの特性を設定する。

object.SetParameters(effectinfo As DIEFFECT, flags As CONST_DIEPFLAGS)

パラメータ

object
DirectInputEffect オブジェクトを表すオブジェクト式。
effectinfo
エフェクト パラメータを格納する DIEFFECT 型。
flags
エフェクト情報のどの部分を設定するか、パラメータのダウンロードをどのように処理するかを指定する、CONST_DIEPFLAGS 列挙からのフラグ。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_NOTINITIALIZED
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

注意

どのパラメータがエフェクトの再生中に動的に更新できるかを判定するには、DirectInputEnumEffects.GetDynamicParams メソッドを使用する。

DirectInputEffect.SetParameters メソッドは、自動的にエフェクトをダウンロードするが、この動作は、DIEP_NODOWNLOAD フラグを設定することによって抑制できる。自動ダウンロードが抑制されていた場合、DirectInputEffect.Download を呼び出してエフェクトを手動でダウンロードできる。

エフェクトの再生中にパラメータが更新されると、エフェクトの開始時のパラメータであったかのように、新しいパラメータが有効になる。

たとえば、3 秒の継続時間を持つ周期的エフェクトが開始されているとする。2 秒後に、エフェクトの方向が変更される。その後、エフェクトは残りの 1 秒間は新しい方向で継続される。エンベロープ、フェーズ、振幅などのエフェクトのパラメータは、方向が変更されなかったかのように続行される。

先の例と同じ状況で、今度は 2 秒後にエフェクトの継続時間が 1.5 秒に変更されたとすると、エフェクトは停止する。

通常、ドライバが再生中のエフェクトのパラメータを更新できない場合、ドライバはそのエフェクトを停止し、パラメータを更新してからそのエフェクトを再開することができる。DIEP_NORESTART フラグを渡すと、この処理が抑制される。エフェクトの再生中にドライバがエフェクトのパラメータを更新できないときは、エラー コードの DIERR_EFFECTPLAYING が返され、パラメータは更新されない。

フラグ DIEP_NODOWNLOAD、DIEP_START、DIEP_NORESTART のうち 2 つ以上を設定してはいけない (何も渡さなくてもよい)。

この 3 つのフラグは、次に示すように、ダウンロード処理とプレイバック処理を制御する。

DIEP_NODOWNLOAD を設定すると、エフェクト パラメータは更新されるが、デバイスにダウンロードはされない。

DIEP_START フラグを設定すると、エフェクト パラメータは更新され、デバイスにダウンロードされる。そして、DirectInputEffect.Start メソッドが iterations パラメータに 1 を設定し、フラグなしで呼び出された場合とまったく同じように、エフェクトが始動する。DIEP_START で更新処理を付加した方法の方が Start メソッドを呼び出す方法よりも少し高速である。これは前者の方法では、デバイスに送信する情報が少なくて済むためである。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトを再生していないときは、パラメータは更新され、デバイスにダウンロードされる。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生中のときは、デバイスが実行中 (オンザフライ) 更新をサポートしていれば、パラメータは更新される。上記以外の場合、処理は DIEP_NORESTART フラグの状態に左右される。このフラグが設定されていれば、エラー コード DIERR_EFFECTPLAYING が返される。このフラグがなければ、エフェクトは停止し、パラメータが更新され、エフェクトが再開する。


DirectInputEffect.Start

DirectInputEffect.Start メソッドは、エフェクトの再生を開始する。エフェクトが既に再生中ならば、最初から開始される。エフェクトがダウンロードされていないか、または前回のダウンロード以来、変更されている場合は、開始前にエフェクトがダウンロードされる。この処理はデフォルトで行われる。これを抑制するには、DIES_NODOWNLOAD フラグを渡せばよい。

object.Start(iterations As Long, flags As Long)

パラメータ

object
DirectInputEffect オブジェクトを表すオブジェクト式。
iterations
連続してエフェクトを再生する回数。エンベロープは、反復ごとに再調整される。

エフェクトを一度だけ再生するには、1 を渡す。エフェクトを明示的に停止するまで繰り返し再生するには、-1 を渡す。エフェクトを明示的に停止するまでエンベロープを再調整せずに再生するには、DirectInputEffect.SetParameters メソッドでエフェクト パラメータを変更し、DIEFFECT の lDuration メンバを -1 に変更する。

flags
デバイスがエフェクトをどのように再生するかを表す、CONST_DIESFLAGS 列挙のフラグ。値はゼロまたは次のフラグのいずれかを指定する。
DIES_SOLO
指定されたエフェクトが再生される前に、デバイス上のほかのすべてのエフェクトを停止する。このフラグを省略すると、エフェクトは、デバイス上で既に再生が始まっている既存のエフェクトと混合されることになる。
DIES_NODOWNLOAD
エフェクトの自動ダウンロードを行わない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_INCOMPLETEEFFECT
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

複数回の繰り返しをサポートしないデバイスもある。


DirectInputEffect.Stop

DirectInputEffect.Stop メソッドは、再生中のエフェクトを停止する。

object.Stop()

パラメータ

object
DirectInputEffect オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。


DirectInputEffect.Unload

DirectInputEffect.Download メソッドは、デバイスからエフェクトを削除する。エフェクトが再生されている場合、エフェクトは、アンロードされる前に自動的に停止する。

object.Unload()

パラメータ

object
DirectInputEffect オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。


DirectInputEnumDeviceObjects

DirectInputEnumDeviceObjects クラスは、システムにインストールされている DirectInputDevice オブジェクトを列挙する。このオブジェクトは、DirectInputDevice.GetDeviceObjectsEnum メソッドを呼び出した結果として作成され、データが格納される。

このクラスには、次のメソッドがある。

情報 | GetCount
 | GetItem


DirectInputEnumDeviceObjects.GetCount

DirectInputEnumDeviceObjects.GetCount メソッドは、DirectInputEnumDeviceObjects コレクションに含まれる項目数を返す。

object.GetCount() As Long

パラメータ

object
DirectInputEnumDeviceObjects オブジェクトを表すオブジェクト式。

戻り値

デバイスに対して列挙されたデバイス オブジェクトの数が返される。

エラー コード

なし。


DirectInputEnumDeviceObjects.GetItem

DirectInputEnumDeviceObjects.GetItem メソッドは、指定したデバイス オブジェクトを表すオブジェクトを取得する。

object.GetItem(index As Long) _
  As DirectInputDeviceObjectInstance

パラメータ

object
DirectInputEnumDeviceObjects オブジェクトを表すオブジェクト式。
index
取得する列挙項目のインデックス。

戻り値

DirectInputDeviceObjectInstance オブジェクトを返す。このオブジェクトのメソッドは、デバイス オブジェクトに関する情報の取得に使用する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DirectInputEnumDeviceObjects に含まれる項目数を取得するには、まず DirectInputEnumDeviceObjects.GetCount メソッドを呼び出す。


DirectInputEnumDevices

DirectInputEnumDevices クラスは、システムにインストールされている DirectInput デバイスを列挙する。このオブジェクトは、DirectInput.GetDIEnumDevices メソッドを呼び出した結果として作成され、データが格納される。

このクラスには、次のメソッドがある。

情報 | GetCount
 | GetItem


DirectInputEnumDevices.GetCount

DirectInputEnumDevices.GetCount メソッドは、DirectInputEnumDevices コレクションに含まれる DirectInput デバイス数を返す。

object.GetCount() As Long

パラメータ

object
DirectInputEnumDevices オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectInputEnumDevices コレクションに含まれる DirectInput デバイスの数が返される。

エラー コード

なし。


DirectInputEnumDevices.GetItem

DirectInputEnumDevices.GetItem メソッドは、列挙されたデバイスについての情報を返す。

object.GetItem(index As Long) As DirectInputDeviceInstance

パラメータ

object
DirectInputEnumDevices オブジェクトを表すオブジェクト式。
index
DirectInputEnumDevices. に含まれる特定の DirectInput データ項目。

戻り値

DirectInputDeviceInstance オブジェクトを返す。このオブジェクトのメソッドは、デバイスに関する情報の取得に使用する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DirectInputEnumDevices に含まれる項目数を取得するには、まず DirectInputEnumDevices.GetCount メソッドを呼び出す。


DirectInputEnumEffects

DirectInputEnumEffects クラスのオブジェクトは、デバイスでサポートされるフォース フィードバック エフェクトのコレクションを表し、エフェクトに関する情報の取得に使用される。オブジェクトを作成するには、DirectInputDevice.GetEffectsEnum メソッドを使用する。

このクラスには、次のメソッドがある。

情報 | GetCount
 | GetDynamicParams
 | GetEffectGuid
 | GetName
 | GetStaticParams
 | GetType


DirectInputEnumEffects.GetCount

DirectInputEnumEffects.GetCount メソッドは、コレクション内の列挙されたエフェクト数を返す。

object.GetCount() As Long

パラメータ

object
DirectInputEnumEffects オブジェクトを表すオブジェクト式。

戻り値

コレクション内の項目数が返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputEnumEffects.GetDynamicParams

DirectInputEnumEffects.GetDynamicParams メソッドは、エフェクトを停止せずに DirectInputEffect.SetParameters メソッドで変更できるエフェクト パラメータについての情報を取得する。

object.GetDynamicParams(i As Long) As CONST_DIEPFLAGS

パラメータ

object
DirectInputEnumEffects オブジェクトを表すオブジェクト式。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

エフェクトの再生中に動的に更新可能なパラメータを表す CONST_DIEPFLAGS 列挙のフラグが返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectInputEffect.SetParameters


DirectInputEnumEffects.GetEffectGuid

DirectInputEnumEffects.GetEffectGuid メソッドは、サポートされるエフェクトの GUID を取得する。この GUID は、DirectInputDevice.CreateEffect メソッドに渡される。

object.GetEffectGuid(i As Long) As String

パラメータ

object
DirectInputEnumEffects オブジェクトを表すオブジェクト式。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

GUID が文字列形式で返される。標準のエフェクトの場合、戻り値は、"GUID_ConstantForce" などのエイリアスである。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectInputEnumEffects.GetName

DirectInputEnumEffects.GetName メソッドは、エフェクトの名前を取得する。

object.GetName(i As Long) As String

パラメータ

object
DirectInputEnumEffects オブジェクトを表すオブジェクト式。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

"Constant Force" など、エフェクトの名前が返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputEnumEffects.GetStaticParams

DirectInputEnumEffects.GetStaticParams メソッドは、デバイスでサポートされるエフェクト パラメータに関する情報を取得する。

object.GetStaticParams(i As Long) As CONST_DIEPFLAGS

パラメータ

object
DirectInputEnumEffects オブジェクトを表すオブジェクト式。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

エフェクトがサポートするパラメータを表す CONST_DIEPFLAGS 列挙のフラグが返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectInputEnumEffects.GetType

DirectInputEnumEffects.GetType メソッドは、エフェクトのタイプと能力に関する情報を取得する。

object.GetType(i As Long) As CONST_DIEFTFLAGS

パラメータ

object
DirectInputEnumEffects オブジェクトを表すオブジェクト式。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

エフェクトに関する情報を表す CONST_DIEFTFLAGS 列挙のフラグが返される。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

エフェクト タイプは下位バイトに格納され、&HHF と AND を取ることで、ビットごとに取得される。


型

ここでは、以下の DirectInput 型を説明する。

  • DICONDITION
  • DICONSTANTFORCE
  • DIDATAFORMAT
  • DIDEVCAPS
  • DIDEVICEOBJECTDATA
  • DIEFFECT
  • DIENVELOPE
  • DIJOYSTATE
  • DIJOYSTATE2
  • DIKEYBOARDSTATE
  • DIMOUSESTATE
  • DIOBJECTDATAFORMAT
  • DIPERIODICFORCE
  • DIPROPLONG
  • DIPROPRANGE
  • DIRAMPFORCE


DICONDITION

DICONDITION 型は、DIEFFECT 型に含まれるフォース フィードバック条件のパラメータを表す。

Type DICONDITION
  lDeadBand As Long
  lNegativeCoefficient As Long
  lNegativeSaturation As Long
  lOffset As Long
  lPositiveCoefficient As Long
  lPositiveSaturation As Long
End Type

メンバ

lDeadBand
0 ～ 10,000 の範囲にある、条件がアクティブでない lOffset 周辺の領域。つまり、lOffset - lDeadBand と lOffset + lDeadBand の間では、条件はアクティブではない。
lNegativeCoefficient
-10,000 ～ +10.000 の範囲にある、オフセットの負側の係数定数。

デバイスが正と負に分かれた係数をサポートしていない場合、lNegativeCoefficient 値は無視され、lPositiveCoefficient 値が正負両方の係数として使用される。

lNegativeSaturation
0 ～ 10,000 の範囲にある、オフセットの負側の最大フォース出力。

デバイスがフォースの飽和値をサポートしない場合、このメンバ値は無視される。

デバイスが正と負に分かれた飽和値をサポートしていない場合、lNegativeSaturation 値は無視され、lPositiveSaturation 値が正負両方の飽和値として使用される。

lOffset
-10,000 ～ +10.000 の範囲にある、条件のオフセット。
lPositiveCoefficient
-10,000 ～ +10.000 の範囲にある、オフセットの正側の係数定数。
lPositiveSaturation
0 ～ 10,000 の範囲にある、オフセットの正側の最大フォース出力。

デバイスがフォースの飽和をサポートしない場合、このメンバ値は無視される。

注意

条件のタイプが異なれば、パラメータの意味も異なるが、基本的な考え方は、条件に起因するフォースは、A(q - q0) に等しくなるということである。ここで、A は、スケーリング係数、q はある距離であり、q0 は、その距離に対する中立値である。

上記の単純な式は、デッドバンドにゼロ以外の値が指定された場合は調整しなければならない。距離が lOffset - lDeadBand より小さければ、生成されるフォースは、次の式で示される。

force = lNegativeCoefficient * (q - (lOffset - lDeadBand))

同様に、距離が lOffset + lDeadBand より大きければ、生成されるフォースは、次の式で示される。

force = lPositiveCoefficient * (q - (lOffset + lDeadBand))

スプリング条件は、軸の位置を距離として使用する。

ダンパ条件は、軸の速度を距離として使用する。

慣性条件は、軸の加速度を距離として使用する。


DICONSTANTFORCE

DICONSTANTFORCE 型は、DIEFFECT 型に含まれるコンスタント フォースのパラメータを表す。

Type DICONSTANTFORCE
  lMagnitude As Long
End Type

メンバ

lMagnitude
-10.000 ～ +10.000 の範囲にある、エフェクトのマグニチュード。エンベロープがこのエフェクトに適用されていれば、この値は、維持期間のマグニチュードを表す。エンベロープの適用がなければ、この値は、エフェクト全体の振幅を表す。


DIDATAFORMAT

DIDATAFORMAT 型は、デバイスのデータ形式を表す情報を格納する。この型は、DirectInputDevice.SetDataFormat メソッドで使用される。

Type DIDATAFORMAT
    dataSize As Long
    lFlags As Long
    lObjSize As Long
    numObjs As Long
End Type

メンバ

dataSize
デバイスが返すデータ パケットのバイト単位のサイズ。この値は、4 の倍数であり、かつデータ パケット内のオブジェクト データの最大オフセット値より大きくなければならない。
lFlags
データ形式のほかの属性を表すフラグ。この値は、CONST_DIDATAFORMATFLAGS 列挙のいずれかを取ることができる。
lObjSize
DIOBJECTDATAFORMAT 型のバイト単位のサイズ。
numObjs
返されるデータのオブジェクト数。

注意

アプリケーションが DIDATAFORMAT 型を作成する必要があるのは、標準以外のデバイスを使用する場合のみである。マウス、キーボード、およびジョイスティックの場合は、DirectInputDevice.SetCommonDataFormat でデータ形式を設定する。


DIDEVCAPS

DIDEVCAPS 型は、DirectInput デバイスの能力に関する情報を格納する。この型は、DirectInputDevice.GetCapabilities メソッドで使用される。

Type DIDEVCAPS
    lAxes As Long
    lButtons As Long
    lDevType As CONST_DIDEVICETYPE
    lDriverVersion As Long
    lFFMinTimeResolution As Long
    lFFSamplePeriod As Long
    lFirmwareRevision As Long
    lFlags As CONST_DIDEVCAPSFLAGS
    lHardwareRevision As Long
    lPOVs As Long
End Type

メンバ

lAxes
デバイス上で使用可能な軸の数。
lButtons
デバイス上で使用可能なボタンの数。
lDevType
デバイスのタイプとサブタイプに関する情報を格納したパック値。DirectInputDeviceInstance.GetDevType メソッドが返すのと等しい値である。
lDriverVersion
デバイス ドライバのバージョン番号。
lFFMinTimeResolution
フォース フィードバック エフェクトの再生時にデバイスが分解可能な最小時間 (マイクロ秒単位)。デバイスは、すべての時間を最も近い増加値に丸める。たとえば、lFFMinTimeResolution の値が 1000 の場合には、デバイスはすべての時間を最も近いミリ秒に丸める。
lFFSamplePeriod
未加工のフォース コマンドを連続して再生する際の、再生間隔の最小時間。
lFirmwareRevision
デバイスのファームウェア リビジョン番号。
lFlags
デバイスに関連付けられたフラグ。CONST_DIDEVCAPSFLAGS 列挙の定数を組み合わせた値となる。
lHardwareRevision
デバイスのハードウェア リビジョン番号。
lPOVs
デバイス上で使用可能な視点コントローラの数。

注意

バージョン番号の付け方はデバイス メーカーによって異なる。確実なのは、新しいバージョンには以前のバージョンよりも大きい数字が付く、ということだけである。


DIDEVICEOBJECTDATA

DIDEVICEOBJECTDATA 型は、バッファリング デバイスの未加工の情報を格納する。この型は、DirectInputDevice.GetDeviceData メソッドで使用される。

Type DIDEVICEOBJECTDATA
    lData As Long
    lOfs As Long
    lSequence As Long
    lTimeStamp As Long
End Type

メンバ

lData
デバイスから取得されるデータ。

軸からの入力の場合、デバイスが相対軸モードにあれば、相対軸の動きが報告される。デバイスが絶対軸モードにあれば、絶対座標が報告される。

ボタンからの入力の場合、lData の下位バイトだけが有意である。下位バイトの上位ビットは、ボタンがダウン状態の場合に設定され、アップ状態の場合に消去される。

lOfs
報告されているデータが属するオブジェクトの現在のデータ形式に対するオフセット。つまり、DirectInputDevice.GetDeviceStateX メソッド (GetDeviceStateMouse など、X は特定のデバイスを指す) を呼び出してデータを取得した場合に、データが格納されている場所。デバイスがキーボードとしてアクセスされる場合、この値を CONST_DIKEYFLAGS 列挙のメンバと比較することで、どのキーがイベントを生成したかを判定できる。マウスやジョイスティックの場合、lOfs の値は、DIMOUSESTATE、DIJOYSTATE、または DIJOYSTATE2 型 (DirectInputDevice.SetCommonDataFormat で設定されたデータ形式により異なる) に含まれる軸またはボタンのバイト オフセットと等しい。これらのオフセットの定数は、CONST_DIMOUSEOFS 列挙および CONST_DIJOYSTICKOFS 列挙に含まれる。DirectInputDevice.SetDataFormat でカスタム データ形式が設定されていた場合、lOfs は、カスタム データ形式内のデバイス オブジェクトの場所のオフセットである。
lSequence
このイベントに対する DirectInput シーケンス番号。すべての入力イベントには、昇順のシーケンス番号が割り当てられている。これにより、異なるデバイスからのイベントを時間順にソートすることが可能になる。この値は、循環して初期値に戻るので、2 つのシーケンス番号を比較する場合には注意しなければならない。
lTimeStamp
入力イベントが生成されたミリ秒単位のシステム時間。この値は、約 50 日で循環する。


DIEFFECT

DIEFFECT 型は、フォース フィードバック エフェクトを表す。この型は、エフェクトのパラメータを設定するために DirectInputDevice.CreateEffect メソッドや DirectInputEffect.SetParameters メソッドに渡される。この型に含まれる既存のパラメータは、DirectInputEffect.GetParameters メソッドで取得される。

Type DIEFFECT
  bUseEnvelope As Long
  conditionFlags As CONST_DICONDITIONFLAGS
  conditionX As DICONDITION
  conditionY As DICONDITION
  constantForce As DICONSTANTFORCE
  envelope As DIENVELOPE
  lDuration As Long
  lFlags As Long
  lGain As Long
  lSamplePeriod As Long
  lStartDelay As Long
  lTriggerButton As Long
  lTriggerRepeatInterval As Long
  periodicForce As DIPERIODICFORCE
  rampForce As DIRAMPFORCE
  x As Long
  y As Long
End Type

メンバ

bUseEnvelope
envelope メンバに記述されるエンベロープがエフェクトに適用される場合は TRUE。
conditionFlags
CONST_DICONDITIONFLAGS 列挙のフラグ。DirectX for Visual Basic の現在のバージョンでは、この値はゼロである。
conditionX
x 軸の条件のパラメータを表す DICONDITION 型。別の型のエフェクトでは無視される。
conditionY
y 軸の条件のパラメータを表す DICONDITION 型。別の型のエフェクトでは無視される。
constantForce
コンスタント フォースのパラメータを表す DICONSTANTFORCE 型。別の型のエフェクトでは無視される。
envelope
エフェクトに適用されるエンベロープのパラメータを表す DIENVELOPE 型。bUseEnvelope メンバが TRUE の場合にのみ有効。
lDuration
マイクロ秒単位のエフェクトの継続時間。-1 という値は、無限の継続時間を表す。無限の継続時間を持つエフェクトにエンベロープが適用されていれば、アタックも適用され、無限の維持期間も適用されることになる。
lFlags
ゼロ、またはほかのメンバの解釈方法を指定する CONST_DIEFFFLAGS 列挙のメンバ。
lGain
エフェクトに適用されるゲイン。0 ～ 10,000 の範囲にある。ゲインとは、エフェクトの全マグニチュードとそのエンベロープに適用されるスケーリング係数である。
lSamplePeriod
デバイスがエフェクトをサンプリングする期間 (マイクロ秒単位)。つまり、フォースにおける変化の細分度。この値がゼロであれば、デフォルトの再生サンプリング速度を使用することを意味する。

デバイスが指定の速度でエフェクトをサンプリングできなければ、指定された値に最も近い速度を選択する。

カスタム サンプリング期間の設定は、特殊効果に使用できる。たとえば、サイン波を意図的に大きなサンプリングレートで再生すると、ざらざらした質感をもたらす。

lStartDelay
DirectInputEffect.Start を呼び出してからエフェクトを再生する前に、デバイスが待機する時間 (マイクロ秒単位)。この値がゼロであれば、エフェクトの再生は直ちに開始される。
lTriggerButton
エフェクトをトリガするボタンのオフセット値。CONST_DIJOYSTICKOFS 列挙のメンバのいずれか 1 つの値を取る。エフェクトがトリガ ボタンを持たないことを示すには、-1 にする。
lTriggerRepeatInterval
ボタンの押下および押し続けによってエフェクトがトリガされたときの、1 回の再生の終了と開始の間隔を表す、マイクロ秒単位の時間。繰り返しを抑制するには、この値を -1 に設定する。

トリガの繰り返しをサポートしないデバイスもある。

periodicForce
周期的エフェクトのパラメータを表す DIPERIODICFORCE 型。別の型のエフェクトでは無視される。
rampForce
傾斜フォースのパラメータを表す DIRAMPFORCE 型。別の型のエフェクトでは無視される。
x
エフェクトの方向。多くの場合、方向は北 (通常、y 軸の負側) からの回転量として 1/100 度単位で表される。したがって、ゼロという値は、ユーザーの正面からくるフォースを示し、9000 という値は、ユーザーの右側からくるフォースを示す。以下同様に解釈する。この場合、y はゼロである。

lFlags に DIEFF_CARTESIAN が含まれている場合、これは x 軸上の相対フォース量を表すデカルト座標の値である。たとえば、x = -1 かつ y = 1 である場合、フォースは、南東方向からくる。詳細については、「エフェクトの方向」を参照すること。

y
lFlags に DIEFF_CARTESIAN が含まれている場合、これは ｙ 軸上の相対フォース量を表すデカルト座標の値である。それ以外の場合、ゼロでなければならない。


DIENVELOPE

DIENVELOPE 型は、DIEFFECT 型に含まれるエンベロープのパラメータを表す。

Type DIENVELOPE
  lAttackLevel As Long
  lAttackTime As Long
  lFadeLevel As Long
  lFadeTime As Long
End Type

メンバ

lAttackLevel
基線を基準とするエンベロープの始点における振幅。基線に対する相対値。0 ～ 10,000 の範囲である。エフェクトのタイプ固有データが、基線を指定していなければ、振幅はゼロを基準とする。
lAttackTime
維持期間レベルに到達するのに必要な、マイクロ秒単位の時間。
lFadeLevel
エンベロープの終点での振幅。基線に対する相対値。0 ～ 10,000 の範囲である。エフェクトのタイプ固有データが、基線を指定していなければ、振幅はゼロを基準とする。
lFadeTime
フェード レベルに到達するのに必要なマイクロ秒単位の時間。


DIJOYSTATE

DIJOYSTATE 型は、ジョイスティック デバイスの状態に関する情報を格納する ("ジョイスティック" には、ゲーム パッドやステアリング ホイールなど、ほかのコントローラも含まれる)。この型は、DirectInputDevice.GetDeviceStateJoystick メソッドで使用される。

Type DIJOYSTATE
    buttons(0 To 31) As Byte
    POV(0 To 3) As Long
    rx As Long
    ry As Long
    rz As Long
    slider(0 To 1) As Long
    x As Long
    y As Long
    z As Long
End Type

メンバ

buttons
ボタンの状態の配列。バイトの上位ビットは、対応するボタンがダウン状態にあるときに設定され、ボタンがアップ状態または存在しないときには消去される。
POV
最高 4 つまでの方向コントローラ (視点ハットなど) の現在位置。この位置は、北から (ユーザーの正面側) 時計回りの実角度の 100 倍で表される。中心位置は通常 -1 と報告されるが、これについては「注意」を参照すること。5 つの位置しか持たないインジケータの場合、コントローラの値は -1、0、9,000、18,000、27,000 のいずれか 1 つの値を取る。
rx
ジョイスティックの x 軸回転の情報。ジョイスティックにこの軸がなければ、値はゼロである。
ry
ジョイスティックの y 軸回転の情報。ジョイスティックにこの軸がなければ、値はゼロである。
rz
ジョイスティックの z 軸回転の情報 (方向舵のコントロールでよく呼び出される)。ジョイスティックにこの軸がなければ、値はゼロである。
slider
2 つの追加軸の値。その意味はジョイスティックにより異なる。これらの値に関する意味情報を取得するには、DirectInputDevice.GetObjectInfo メソッドを使用する。
x
ジョイスティックの x 軸の情報 (通常は、スティックの左右の動き)。
y
ジョイスティックの y 軸の情報 (通常は、スティックの前後の動き)。
z
ジョイスティックの z 軸の情報 (通常は、スロットル制御)。ジョイスティックにこの軸がなければ、値はゼロである。

注意

ジョイスティック型のアクセスをするには、DirectInputDevice.SetCommonDataFormat メソッドを呼び出し、DIFORMAT_JOYSTICK 形式定数を渡すことで、デバイスの準備をしなければならない。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

POV インジケータの中心位置を 65,535 と報告するドライバもある。POV インジケータが中心位置にあるかどうかは、次のようにして確認する。

Dim POVCentered as Boolean
POVCentered = MyDijoystate.POV(0) And &HFFFF;

参照

DIJOYSTATE2


DIJOYSTATE2

DIJOYSTATE2 型は、拡張機能付きジョイスティック デバイスの状態に関する情報を格納する。この型は、DirectInputDevice.GetDeviceStateJoystick2 メソッドで使用される。

この型は、フォース フィードバック デバイスなど、非常に特殊なコントローラ向けの型なので、通常、アプリケーションはこの型を使用する必要はない。標準のゲーム コントローラの場合、DirectInputDevice.GetDeviceStateJoystick を呼び出すことで、DIJOYSTATE 型を使用してデータを取得する。

Type DIJOYSTATE2
    buttons(0 To 31) As Byte
    frx As Long
    fry As Long
    frz As Long
    fslider(0 To 1) As Long
    fx As Long
    fy As Long
    fz As Long
    POV(0 To 3) As Long
    rx As Long
    ry As Long
    rz As Long
    slider(0 To 1) As Long
    vrx As Long
    vry As Long
    vrz As Long
    vslider(0 To 1) As Long
    vx As Long
    vy As Long
    vz As Long
    x As Long
    y As Long
    z As Long
End Type

メンバ

buttons
ボタンの状態の配列。バイトの上位ビットは、対応するボタンがダウン状態にあるときに設定され、ボタンがアップ状態または存在しないときには消去される。
frx
x 軸トルクの情報。
fry
y 軸トルクの情報。
frz
z 軸トルクの情報。
fslider
追加軸のフォースの情報。
fx
x 軸フォースの情報。
fy
y 軸フォースの情報。
fz
z 軸フォースの情報。
POV
最高 4 つまでの方向コントローラ (視点ハットなど) の現在位置。この位置は、北から (ユーザーの正面側) 時計回りの実角度の 100 倍で表される。中心位置は通常 -1 と報告されるが、これについては「注意」を参照すること。5 つの位置しか持たないインジケータの場合、コントローラの値は -1、0、9,000、18,000、27,000 のいずれか 1 つの値を取る。
rx
ジョイスティックの x 軸回転の情報。ジョイスティックにこの軸がなければ、値はゼロである。
ry
ジョイスティックの y 軸回転の情報。ジョイスティックにこの軸がなければ、値はゼロである。
rz
ジョイスティックの z 軸回転の情報 (方向舵のコントロールでよく呼び出される)。ジョイスティックにこの軸がなければ、値はゼロである。
slider
2 つの追加軸の値。その意味はジョイスティックにより異なる。これらの値に関する意味情報を取得するには、DirectInputDevice.GetObjectInfo メソッドを使用する。
vrx
x 軸角速度の情報。
vry
y 軸角速度の情報。
vrz
z 軸角速度の情報。
vslider[0 To 1]
追加軸の速度の情報。
vx
x 軸速度の情報。
vy
y 軸速度の情報。
vz
z 軸速度の情報。
x
ジョイスティックの x 軸の情報 (通常は、スティックの左右の動き)。
y
ジョイスティックの y 軸の情報 (通常は、スティックの前後の動き)。
z
ジョイスティックの z 軸の情報 (通常は、スロットル制御)。ジョイスティックにこの軸がなければ、値はゼロである。

注意

拡張機能付きのジョイスティックにアクセスするには、DirectInputDevice.SetCommonDataFormat メソッドを呼び出し、DIFORMAT_JOYSTICK2 データ形式変数を渡すことで、デバイスの準備をしなければならない。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

POV インジケータの中心位置を 65,535 と報告するドライバもある。POV インジケータが中心位置にあるかどうかは、次のようにして確認する。

Dim POVCentered as Boolean
POVCentered = MyDijoystate2.POV(0) And &HFFFF;


DIKEYBOARDSTATE

DIKEYBOARDSTATE 型は、キーボードのキーの状態に関する情報を格納する。この型は、DirectInputDevice.GetDeviceStateKeyboard メソッドで使用される。

Type DIKEYBOARDSTATE
    key(0 To 255) As Byte
End Type

メンバ

key
ボタンの状態の配列。この配列には、CONST_DIKEYFLAGS 列挙のメンバでインデックスを作成できる。各キーの上位ビットは、キーがダウン状態で設定され、アップ状態または存在しない場合に消去される。

注意

次のコードは、Esc キーが押されているかどうかを確認する例である。

Dim keyState as DIKEYBOARDSTATE
' diDevice は有効な DirectInputDevice オブジェクトである。

Call diDevice.GetDeviceStateKeyboard(keyState)
If (keyState.key(DIK_ESCAPE) And &H80) Then
    ' キーは押下されている。
End If


DIMOUSESTATE

DIMOUSESTATE 型は、マウス デバイスの状態に関する情報、またはマウス デバイスと同じようにアクセスされるその他のデバイスの状態に関する情報を格納する。この型は、DirectInputDevice.GetDeviceStateMouse メソッドで使用される。

Type DIMOUSESTATE
    buttons(0 To 3) As Byte
    x As Long
    y As Long
    z As Long
End Type

メンバ

buttons
ボタンの状態の配列。バイトの上位ビットは、対応するボタンがダウン状態にあるときに設定される。
x
マウスの x 軸情報。
y
マウスの y 軸情報。
z
マウスの z 軸情報 (通常、ホイール)。マウスに z 軸がなければ、この値はゼロである。

注意

DirectInputDevice.SetCommonDataFormat メソッドに DIFORMAT_MOUSE 定数を渡すことで準備していたデバイスからは、この型に直接データが返される。

軸が相対モードである場合は、適切なメンバが、このメソッドを前回に呼び出して以降の位置の変化量を格納する。軸が絶対モードである場合は、同じメンバが、任意の始点に対する相対的な動きの累積を格納する。したがって、絶対軸位置は、ほかの絶対軸位置と比較する場合を除いて無意味となる。


DIOBJECTDATAFORMAT

DIOBJECTDATAFORMAT 型には、DirectInputDevice.SetDataFormat メソッドで使用されるデバイス オブジェクトのデータ形式に関する方法が格納される。

Type DIOBJECTDATAFORMAT {
    lFlags As CONST_DIDEVICEOBJINSTANCEFLAGS
    lOfs As Long
    lType As CONST_DIDFTFLAGS
    strGuid As String
End Type

メンバ

lFlags
ゼロ、または次の CONST_DIDEVICEOBJINSTANCEFLAGS 列挙の値。
DIDOI_ASPECTACCEL
DirectInput.SetDataFormat で選択されたオブジェクトは、加速度情報を報告する。
DIDOI_ASPECTFORCE
DirectInput.SetDataFormat で選択されたオブジェクトは、フォース情報を報告する。
DIDOI_ASPECTPOSITION
DirectInput.SetDataFormat で選択されたオブジェクトは、位置情報を報告する。
DIDOI_ASPECTVELOCITY
DirectInput.SetDataFormat で選択されたオブジェクトは、速度情報を報告する。
lOfs
入力ソースのデータを格納するデータ パケット内のバイト オフセット。この値は、軸など、Long サイズのデータに合うように、4 の倍数でなければならない。ボタンの場合はバイト整列でも構わない。
lType
オブジェクトを表すデバイス タイプ。オブジェクト タイプ (軸、ボタンなど) を表す CONST_DIDFTFLAGS 列挙の値の組み合わせであり、中央の 16 ビットには、オブジェクト インスタンス番号が格納される。
strGuid
入力ソースのタイプに対する一意な識別子。空の文字列は、あらゆるタイプのオブジェクトが許容されることを示す。

次の文字列は、デバイス オブジェクトのタイプを識別するために、実際の GUID 文字列の代わりに使用できる。

GUID_XAxis
GUID_YAxis
GUID_ZAxis
GUID_RxAxis
GUID_RyAxis
GUID_RzAxis
GUID_Slider
GUID_Button
GUID_Key
GUID_POV


DIPERIODICFORCE

DIPERIODICFORCE 型は、DIEFFECT 型に含まれる周期的フォースのパラメータを表す。

Type DIPERIODICFORCE
  lMagnitude As Long
  lOffset As Long
  lPhase As Long
  lPeriod As Long
End Type

メンバ

lMagnitude
0 ～ 10.000 の範囲にある、エフェクトのマグニチュード。エンベロープがこのエフェクトに適用されていれば、この値は、維持期間のマグニチュードを表す。エンベロープの適用がなければ、この値は、エフェクト全体の振幅を表す。
lOffset
エフェクトのオフセット。エフェクトが生成するフォースは、lOffset - lMagnitude から lOffset + lMagnitude の範囲になる。lOffset メンバの値は、エフェクトに適用されるすべてのエンベロープに対する基線にもなる。
lPhase
0 ～ 35,999 の範囲内にある周期的エフェクトの再生開始位置。「注意」を参照すること。
lPeriod
マイクロ秒単位のエフェクトの周期。

注意

デバイス ドライバは lPhase メンバのすべての値をサポートしているとは限らない。サポートされていない値は、直近のサポート値に丸められる。


DIPROPLONG

DIPROPLONG 型は、プロパティが単一の値を取る場合に、DirectInputDevice.SetProperty メソッドや DirectInputDevice.GetProperty メソッドで、入力デバイスに設定または取得されるプロパティ情報を格納するのに使用する。

Type DIPROPLONG
    lData As Long
    lHow As Long
    lObj As Long
    lSize As Long
End Type

メンバ

lData
設定または取得されるプロパティ固有の値。
lHow
lObj パラメータの解釈方法を指定する値。この値は、CONST_DIPHFLAGS 列挙のメンバのいずれかを取ることができる。

lObj が DIPROP_AXISMODE または DIPROP_BUFFERSIZE である場合、これらのプロパティは個別のオブジェクトには設定できないので、lHow は DIPH_DEVICE でなければならない。

lObj
アクセスするプロパティが属するオブジェクト。

lHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。この値は、DirectInputDeviceObjectInstance.GetType メソッドを使ってオブジェクトごとに取得できる。

lHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。この値は、DirectInputDeviceObjectInstance.GetOfs メソッドで取得できる。

lHow が DIPH_DEVICE である場合、この値はゼロである。

lSize
この型のサイズ。

注意

SetProperty メソッドに型が渡される前に、すべてのメンバを適切な値で初期化する必要がある。GetProperty メソッドに型が渡される前に、lData を除くすべてのメンバを適切な値で初期化する必要がある。

参照

DIPROPRANGE


DIPROPRANGE

DIPROPRANGE 型は、プロパティが値の範囲を取る場合に DirectInputDevice.SetProperty メソッドや DirectInputDevice.GetProperty メソッドで、入力デバイスに設定または取得されるプロパティ情報を格納するために使用する。

Type DIPROPRANGE
    lHow As Long
    lMax As Long
    lMin As Long
    lObj As Long
    lSize As Long
End Type

メンバ

lHow
lObj メンバの解釈方法を指定する値。この値は、CONST_DIPHFLAGS 列挙のメンバのいずれかを取ることができる。
lMax
範囲の上限。デバイスの範囲に制限がなければ、DirectInputDevice.GetProperty メソッドが戻るとき、この値は DIPROPRANGE_NOMAX (CONST_DINPUT 列挙の値) となる。
lMin
範囲の下限。デバイスの範囲に制限がなければ、DirectInputDevice.GetProperty メソッドが戻るとき、この値は DIPROPRANGE_NOMIN (CONST_DINPUT 列挙の値) となる。
lObj
アクセスするプロパティが属するオブジェクト。

lHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。この値は、DirectInputDeviceObjectInstance.GetType メソッドを使ってオブジェクトごとに取得できる。

lHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。この値は、DirectInputDeviceObjectInstance.GetOfs メソッドで取得できる。

lHow が DIPH_DEVICE である場合、この値はゼロである。

lSize
この型のサイズ。

参照

DIPROPLONG


DIRAMPFORCE

DIRAMPFORCE 型は、DIEFFECT 型に含まれる傾斜フォースのパラメータを表す。

Type DIRAMPFORCE
  lRangeEnd As Long
  lRangeStart As Long
End Type

メンバ

lRangeEnd
-10,000 ～ +10.000 の範囲にある、エフェクトの終点のマグニチュード。
lRangeStart
-10,000 ～ +10.000 の範囲にある、エフェクトの始点のマグニチュード。

注意

傾斜フォースエフェクトの継続時間は有限でなければならない。


列挙

DirectInput は、Visual Basic のステートメント補完機能を利用するために、列挙を使って定数をグループ化する。DirectInput で使用される列挙は次のとおりである。

  • CONST_DICOMMONDATAFORMATS
  • CONST_DICONDITIONFLAGS
  • CONST_DIDATAFORMATFLAGS
  • CONST_DIDEVCAPSFLAGS
  • CONST_DIDEVICEOBJINSTANCEFLAGS
  • CONST_DIDEVICETYPE
  • CONST_DIDFTFLAGS
  • CONST_DIDGDDFLAGS
  • CONST_DIEFFFLAGS
  • CONST_DIEFTFLAGS
  • CONST_DIEGESFLAGS
  • CONST_DIENUMDEVICESFLAGS
  • CONST_DIEPFLAGS
  • CONST_DIESFLAGS
  • CONST_DIGFFSFLAGS
  • CONST_DIJOYSTICKOFS
  • CONST_DIKEYFLAGS
  • CONST_DIMOUSEOFS
  • CONST_DINPUT
  • CONST_DINPUTERR
  • CONST_DIPHFLAGS
  • CONST_DISCLFLAGS
  • CONST_DISDDFLAGS
  • CONST_DISFFCFLAGS


CONST_DICOMMONDATAFORMATS

CONST_DICOMMONDATAFORMATS 列挙のメンバは、DirectInputDevice.SetCommonDataFormat メソッドの format パラメータにデータ形式を指定するのに使用する。

Enum CONST_DICOMMONDATAFORMATS
    DIFORMAT_JOYSTICK =  3
    DIFORMAT_JOYSTICK2 = 4
    DIFORMAT_KEYBOARD =  1
    DIFORMAT_MOUSE =     2
End Enum
DIFORMAT_JOYSTICK
状態データを DIJOYSTATE 型に受け取るジョイスティック。
DIFORMAT_JOYSTICK2
状態データを DIJOYSTATE2 型に受け取る拡張機能付きジョイスティック。
DIFORMAT_KEYBOARD
状態データを DIKEYBOARDSTATE 型に受け取るキーボード。
DIFORMAT_MOUSE
状態データを DIMOUSESTATE 型に受け取るマウス。


CONST_DICONDITIONFLAGS

CONST_DICONDITIONFLAGS 列挙は、フォース フィードバック エフェクトの軸と方向を設定するために DIEFFECT 型の conditionFlags メンバに使用される。

Enum CONST_DICONDITIONFLAGS
    DICONDITION_USE_BOTH_AXES = 1
    DICONDITION_USE_DIRECTION = 2
End Enum
DICONDITION_USE_BOTH_AXES
現在未サポートである。
DICONDITION_USE_DIRECTION
現在未サポートである。


CONST_DIDATAFORMATFLAGS

CONST_DIDATAFORMATFLAGS 列挙は、データ形式の追加属性を表すために DIDATAFORMAT 型の lFlags メンバに使用される。

Enum CONST_DIDATAFORMATFLAGS
    DIDF_ABSAXIS = 1
    DIDF_RELAXIS = 2
End Enum
DIDF_ABSAXIS
軸は絶対モードにある。このフラグをデータ形式に設定することは、DirectInputDevice.SetProperty メソッドを使って軸モード プロパティを手動で設定するのと等しい。この値を DIDF_RELAXIS フラグと組み合わせることはできない。
DIDF_RELAXIS
軸は相対モードにある。このフラグをデータ形式に設定することは、DirectInputDevice.SetProperty メソッドを使って軸モード プロパティを手動で設定するのと等しい。この値を DIDF_ABSAXIS フラグと組み合わせることはできない。


CONST_DIDEVCAPSFLAGS

CONST_DIDEVCAPSFLAGS 列挙は、DirectInput デバイスを表すために DIDEVCAPS 型の lFlags メンバに使用される。

Enum CONST_DIDEVCAPSFLAGS
    DIDC_ATTACHED =              1
    DIDC_DEADBAND =          16384 (&H4000)
    DIDC_EMULATED =              4
    DIDC_FFATTACK =            512 (&H200)
    DIDC_FFFADE =             1024 (&H400)
    DIDC_FORCEFEEDBACK =       256 (&H100)
    DIDC_POLLEDDATAFORMAT =      8
    DIDC_POLLEDDEVICE =          2
    DIDC_POSNEGCOEFFICIENTS = 4096 (&H1000)
    DIDC_POSNEGSATURATION =   8192 (&H2000)
    DIDC_SATURATION =         2048 (&H800)
End Enum
DIDC_ATTACHED
デバイスは、物理的にアタッチされている。
DIDC_DEADBAND
デバイスは、少なくとも 1 つのフォース フィードバック条件でデッドバンドをサポートしている。
DIDC_EMULATED
このフラグが設定されると、データはユーザー モード デバイス インターフェイス (HID など)、またはほかのリング 3 の手段により入力される。フラグが設定されない場合、データはカーネル モード ドライバから直接入力される。
DIDC_FFATTACK
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対するアタック パラメータをサポートする。デバイスがアタックをサポートしない場合、DIENVELOPE 型の lAttackLevel メンバと lAttackTime メンバは、デバイスにより無視される。
DIDC_FFFADE
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対するフェード パラメータをサポートする。デバイスがフェードをサポートしない場合、DIENVELOPE 型の lFadeLevel メンバと lFadeTime メンバは、デバイスにより無視される。
DIDC_FORCEFEEDBACK
デバイスは、フォース フィードバックをサポートする。
DIDC_POLLEDDATAFORMAT
現状のデータ形式で少なくとも 1 つのオブジェクトが、割り込み駆動ではなく、ポーリングされる。このようなオブジェクトの場合、アプリケーションはデータを取得するために DirectInputDevice.Poll メソッドを明示的に呼び出さなければならない。
DIDC_POLLEDDEVICE
デバイス上の少なくとも 1 つのオブジェクトが、割り込み駆動ではなく、ポーリングされる。このようなオブジェクトの場合、アプリケーションはデータを取得するために DirectInputDevice.Poll メソッドを明示的に呼び出さなければならない。HID デバイスは、ポーリング オブジェクトと非ポーリング オブジェクトを混在して格納できる。
DIDC_POSNEGCOEFFICIENTS
フォース フィードバック システムは、少なくとも 1 つの条件に対して条件の 2 つの係数値をサポートする (一方は、軸の正移動、他方は、軸の負移動)。デバイスが両方の係数をサポートしていなければ、DICONDITION 型の負の係数は無視される。
DIDC_POSNEGSATURATION
フォース フィードバック システムは、少なくとも 1 つの条件に対して、正負の両方のフォース出力に対する最大飽和をサポートする。デバイスが両方の飽和値をサポートしていなければ、DICONDITION 型の負の飽和値は無視される。
DIDC_SATURATION
フォース フィードバック システムは、少なくとも 1 つの条件に対して条件エフェクトの飽和をサポートする。デバイスが飽和をサポートしていなければ、ある条件の下で生成されるフォースは、デバイスが生成できる最大フォースによってのみ制限される。

参照

CONST_DIEFTFLAGS


CONST_DIDEVICEOBJINSTANCEFLAGS

CONST_DIDEVICEOBJINSTANCEFLAGS 列挙のメンバは、デバイス オブジェクトの能力を表し、DirectInputDeviceObjectInstance.GetFlags メソッドにより返される。また、DirectInputDevice.SetDataFormat メソッドに渡される DIOBJECTDATAFORMAT 型内にも存在する。

Enum CONST_DIDEVICEINSTANCEFLAGS
    DIDOI_ASPECTACCEL =     768 (&H300)
    DIDOI_ASPECTFORCE =    1024 (&H400)
    DIDOI_ASPECTMASK =     3840 (&HF00)
    DIDOI_ASPECTPOSITION =  256 (&H100)
    DIDOI_ASPECTVELOCITY =  512 (&H200)
    DIDOI_FFACTUATOR =        1
    DIDOI_FFEFFECTTRIGGER =   2
    DIDOI_POLLED =        32768 (&H8000)
End Enum
DIDOI_ASPECTACCEL
オブジェクトは加速度情報を報告する。
DIDOI_ASPECTFORCE
オブジェクトはフォース情報を報告する。
DIDOI_ASPECTMASK
アスペクト情報を報告するためのビット。1 つのオブジェクトは最大 1 つのアスペクトしか表すことができない。
DIDOI_ASPECTPOSITION
オブジェクトは位置情報を報告する。
DIDOI_ASPECTVELOCITY
オブジェクトは速度情報を報告する。
DIDOI_FFACTUATOR
オブジェクトは、フォース フィードバック エフェクトを自身に適用させることができる。
DIDOI_FFEFFECTTRIGGER
オブジェクトは、フォース フィードバック エフェクトの再生をトリガする。
DIDOI_POLLED
オブジェクトは、DirectInputDevice.Poll メソッドが呼び出されるまでデータを返さない。

注意

これらのフラグのうち、DirectX for Visual Basic で開発されるアプリケーションに必要なのは、DIDIO_POLLED のみである。


CONST_DIDEVICETYPE

CONST_DIDEVICETYPE 列挙のメンバは、入力デバイスのタイプとサブタイプを識別するために使用される。タイプとサブタイプを表すパック値は、DirectInputDeviceInstance.GetDevType メソッドにより返される。また、DirectInputDevice.GetCapabilities が返す DIDEVCAPS 型の lDevType メンバに含まれる。プライマリ タイプを表す値は、deviceType パラメータとして DirectInput.GetDIEnumDevices メソッドに渡される。

タイプとサブタイプによりリストされるメンバの一覧については、「DirectInputDeviceInstance.GetDevType」を参照すること。

Enum CONST_DIDEVICETYPE
    DIDEVTYPE_DEVICE              = 1
    DIDEVTYPE_HID             = 65536 (&H10000)
    DIDEVTYPE_JOYSTICK            = 4
    DIDEVTYPE_KEYBOARD            = 3
    DIDEVTYPE_MOUSE               = 2
    DIDEVTYPEJOYSTICK_FLIGHTSTICK = 3
    DIDEVTYPEJOYSTICK_GAMEPAD     = 4
    DIDEVTYPEJOYSTICK_HEADTRACKER = 7
    DIDEVTYPEJOYSTICK_RUDDER      = 5
    DIDEVTYPEJOYSTICK_TRADITIONAL = 2
    DIDEVTYPEJOYSTICK_UNKNOWN     = 1
    DIDEVTYPEJOYSTICK_WHEEL       = 6
    DIDEVTYPEKEYBOARD_J3100      = 12
    DIDEVTYPEKEYBOARD_JAPAN106   = 10
    DIDEVTYPEKEYBOARD_JAPANAX    = 11
    DIDEVTYPEKEYBOARD_NEC98       = 7
    DIDEVTYPEKEYBOARD_NEC98106    = 9
    DIDEVTYPEKEYBOARD_NEC98LAPTOP = 8
    DIDEVTYPEKEYBOARD_NOKIA1050   = 5
    DIDEVTYPEKEYBOARD_NOKIA9140   = 6
    DIDEVTYPEKEYBOARD_OLIVETTI    = 2
    DIDEVTYPEKEYBOARD_PCAT        = 3
    DIDEVTYPEKEYBOARD_PCENH       = 4
    DIDEVTYPEKEYBOARD_PCXT        = 1
    DIDEVTYPEKEYBOARD_UNKNOWN     = 0
    DIDEVTYPEMOUSE_FINGERSTICK    = 3
    DIDEVTYPEMOUSE_TOUCHPAD       = 4
    DIDEVTYPEMOUSE_TRACKBALL      = 5
    DIDEVTYPEMOUSE_TRADITIONAL    = 2
    DIDEVTYPEMOUSE_UNKNOWN        = 1
End Enum
DIDEVTYPE_DEVICE
その他のカテゴリに属さないデバイス。
DIDEVTYPE_HID
デバイスは、HID (Human Interface Device) プロトコルを使用する。
DIDEVTYPE_JOYSTICK
ジョイスティックまたは類似デバイス (ステアリング ホイールなど)。
DIDEVTYPE_KEYBOARD
キーボードまたはキーボード類似デバイス。
DIDEVTYPE_MOUSE
マウスまたはマウス類似デバイス (トラックボールなど)。
DIDEVTYPEJOYSTICK_FLIGHTSTICK
フライト シミュレーション用に最適化されているジョイスティック。
DIDEVTYPEJOYSTICK_GAMEPAD
主要目的がボタン入力を行うことにあるデバイス。
DIDEVTYPEJOYSTICK_HEADTRACKER
ユーザーの頭の動きを追跡するデバイス。
DIDEVTYPEJOYSTICK_RUDDER
偏揺制御用のデバイス。
DIDEVTYPEJOYSTICK_TRADITIONAL
従来のジョイスティック。
DIDEVTYPEJOYSTICK_UNKNOWN
サブタイプは確定できない。
DIDEVTYPEJOYSTICK_WHEEL
車のハンドル用のデバイス。
DIDEVTYPEKEYBOARD_J3100
日本語 J3100 キーボード。
DIDEVTYPEKEYBOARD_JAPAN106
日本語 106 キー キーボード。
DIDEVTYPEKEYBOARD_JAPANAX
日本語 AX キーボード。
DIDEVTYPEKEYBOARD_NEC98
日本語 NEC PC98 キーボード。
DIDEVTYPEKEYBOARD_NEC98106
日本語 NEC PC98 106 キー キーボード。
DIDEVTYPEKEYBOARD_NEC98LAPTOP
日本語 NEC PC98 ラップトップ キーボード。
DIDEVTYPEKEYBOARD_NOKIA1050
Nokia 1050 キーボード。
DIDEVTYPEKEYBOARD_NOKIA9140
Nokia 9140 キーボード。
DIDEVTYPEKEYBOARD_OLIVETTI
Olivetti 102 キー キーボード。
DIDEVTYPEKEYBOARD_PCAT
IBM PC/AT 84 キー キーボード。
DIDEVTYPEKEYBOARD_PCENH
IBM PC 拡張 101/102 キー式キーボードまたは Microsoft ナチュラル キーボード。
DIDEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 キー キーボード。
DIDEVTYPEKEYBOARD_UNKNOWN
サブタイプは確定できない。
DIDEVTYPEMOUSE_FINGERSTICK
デバイスは、フィンガースティックである。
DIDEVTYPEMOUSE_TOUCHPAD
デバイスは、タッチパッドである。
DIDEVTYPEMOUSE_TRACKBALL
デバイスは、トラックボールである。
DIDEVTYPEMOUSE_TRADITIONAL
デバイスは、従来のマウスである。
DIDEVTYPEMOUSE_UNKNOWN
サブタイプは確定できない。


CONST_DIDFTFLAGS

CONST_DIDFTFLAGS 列挙のメンバは、列挙するデバイス オブジェクトのタイプを指定するために DirectInputDevice.GetDeviceObjectsEnum メソッドの flags パラメータに使用される。これらの値は、デバイス オブジェクトの能力を表すために DirectInputDeviceObjectInstance.GetFlags メソッドによっても返される。

Enum CONST_DIDFTFLAGS
    DIDFT_ABSAXIS         =        2
    DIDFT_ALL             =        0
    DIDFT_ANYINSTANCE     = 16776960 (&HFFFF00)
    DIDFT_AXIS            =        3
    DIDFT_BUTTON          =       12
    DIDFT_COLLECTION      =       64 (&H40)
    DIDFT_FFACTUATOR      = 16777216 (&H1000000)
    DIDFT_FFEFFECTTRIGGER = 33554432 (&H2000000)
    DIDFT_INSTANCEMASK    = 16776960(&HFFFF00)
    DIDFT_NOCOLLECTION    = 16776960 (&HFFFF00)
    DIDFT_NODATA          =      128 (&H80)
    DIDFT_POV             =       16 (&H10)
    DIDFT_PSHBUTTON       =        4
    DIDFT_RELAXIS         =        1
    DIDFT_TGLBUTTON       =        8
End Enum
DIDFT_ABSAXIS
絶対軸。
DIDFT_ALL
すべてのオブジェクト。
DIDFT_ANYINSTANCE
オブジェクトの任意のインスタンス。
DIDFT_AXIS
絶対軸、相対軸のどちらか。
DIDFT_BUTTON
プッシュ ボタンまたはトグル ボタン。
DIDFT_COLLECTION
HID リンク コレクション。HID リンク コレクションは、独自のデータを生成しない。
DIDFT_FFACTUATOR
フォース フィードバック アクチュエータを含むオブジェクト。つまり、フォースをこのオブジェクトに適用することができる。
DIDFT_FFEFFECTTRIGGER
フォース フィードバック エフェクトをトリガするために使用できるオブジェクト。
DIDFT_INSTANCEMASK
DIDFT_ANYINSTANCE と同じ。
DIDFT_NOCOLLECTION
あらゆる HID リンク コレクションに属しない、つまり、DirectInputDeviceObjectInstance.GetCollectionNumber がゼロを返すオブジェクト。
DIDFT_NODATA
データを生成しないオブジェクト。
DIDFT_POV
視点コントローラ。
DIDFT_PSHBUTTON
プッシュ ボタン。プッシュ ボタンは、ユーザーが押したときにダウン、ユーザーが離したときにアップと報告される。
DIDFT_RELAXIS
相対軸。
DIDFT_TGLBUTTON
トグル ボタン。トグル ボタンは、ユーザーが押したときにダウンと報告され、ユーザーが再度そのボタンを押すまでその状態に留まる。


CONST_DIDGDDFLAGS

CONST_DIDGDDFLAGS 列挙のメンバは、データの取得方法を制御するために DirectInputDevice.GetDeviceData メソッドの flags パラメータに使用される。

Enum CONST_DIDGDDFLAGS
    DIGDD_DEFAULT = 0
    DIGDD_PEEK    = 1
End Enum
DIGDD_DEFAULT
取得した項目をバッファから削除する。
DIGDD_PEEK
取得した項目をバッファから削除しない。これ以降の GetDeviceData 呼び出しで、同じデータを読み取ることができる。


CONST_DIEFFFLAGS

CONST_DIEFFFLAGS 列挙のメンバは、DIEFFECT 型の lFlags メンバに使用される。

Enum CONST_DIEFFFLAGS
    DIEFF_CARTESIAN =    16 (&H10)
    DIEFF_OBJECTOFFSETS = 2
    DIEFF_POLAR =        32 (&H20)
End Enum
DIEFF_CARTESIAN
エフェクトの方向は、デカルト座標で指定される。DIEFFECT.x と DIEFFECT.y に有効な値が格納される。
DIEFF_OBJECTOFFSETS
DIEFFECT の lTriggerButton メンバの値は、デバイスのデータ構造に含まれるボタンのオフセットである。
DIEFF_POLAR
エフェクトの方向は、極座標で指定される。DIEFFECT.x に有効な値が格納される。

注意

DirectInputDevice.CreateEffect および DirectInputDevice.CreateCustomEffect のデフォルトの動作は、DIEFFECT.lFlags に (DIEFF_OBJECTOFFSETS Or DIEFF_POLAR) が含まれる場合と同様に、エフェクトを生成する。つまり、これらのフラグを指定する必要はない。


CONST_DIEFTFLAGS

CONST_DIEFTFLAGS 列挙のメンバは、フォース フィードバック エフェクトのタイプと能力を表す。これらのメンバは、DirectInputDevice.GetEffectsEnum メソッドでエフェクトの列挙対象を 1 つ以上のプライマリ タイプに制限するために使用される。また、DirectInputEnumEffects.GetType メソッドでもこれらのメンバが返される。

Enum CONST_DIEFTFLAGS
    DIEFT_ALL =                   0
    DIEFT_CONDITION =             4
    DIEFT_CONSTANTFORCE =         1
    DIEFT_CUSTOMFORCE =           5
    DIEFT_DEADBAND =          16384 (&H4000)
    DIEFT_FFATTACK =            512 (&H200)
    DIEFT_FFFADE =             1024 (&H400)
    DIEFT_HARDWARE =            255 (&HFF)
    DIEFT_PERIODIC =              3
    DIEFT_POSNEGCOEFFICIENTS = 4096 (&H1000)
    DIEFT_POSNEGSATURATION =   8192 (&H2000)
    DIEFT_RAMPFORCE =             2
    DIEFT_SATURATION =         2048 (&H800)
End Enum
DIEFT_ALL
すべてのエフェクトを列挙する。
DIEFT_CONDITION
エフェクトは条件である。または、条件を列挙する。
DIEFT_CONSTANTFORCE
エフェクトはコンスタント フォースである。または、コンスタント フォースを列挙する。
DIEFT_CUSTOMFORCE
エフェクトはカスタム フォースである。または、カスタム フォースを列挙する。
DIEFT_DEADBAND
エフェクトはデッドバンドをサポートする。
DIEFT_FFATTACK
エフェクトはアタックをサポートする。
DIEFT_FFFADE
エフェクトはフェードをサポートする。
DIEFT_HARDWARE
エフェクトはハードウェアに固有である。または、ハードウェア エフェクトを列挙する。
DIEFT_PERIODIC
エフェクトは周期的である。または、周期的エフェクトを列挙する。
DIEFT_POSNEGCOEFFICIENTS
条件は正と負の係数を個別にサポートする。
DIEFT_POSNEGSATURATION
エフェクトは正と負の飽和を個別にサポートする。
DIEFT_RAMPFORCE
エフェクトは傾斜フォースである。または、傾斜フォースを列挙する。
DIEFT_SATURATION
エフェクトは飽和値をサポートする。

参照

CONST_DIDEVCAPSFLAGS


CONST_DIEGESFLAGS

CONST_DIEGESFLAGS 列挙のメンバは、DirectInputEffect.GetEffectStatus メソッドにより返される。

Enum CONST_DIEGESFLAGS
    DIEGES_EMULATED = 2
    DIEGES_PLAYING = 1
End Enum
DIEGES_EMULATED
エフェクトはエミュレートされる。
DIEGES_PLAYING
エフェクトは再生中である。


CONST_DIENUMDEVICESFLAGS

CONST_DIENUMDEVICESFLAGS 列挙のメンバは、すべてのデバイスを列挙するか、またはアタッチされたデバイスのみを列挙するかを指示するために、DirectInput.GetDIEnumDevices メソッドの flags パラメータに使用される。

Enum CONST_DIENUMDEVICESFLAGS
    DIEDFL_ALLDEVICES  = 0
    DIEDFL_ATTACHEDONLY = 1
End Enum
DIEDFL_ALLDEVICES
すべてのインストール済みデバイスが列挙される。これがデフォルト モードである。
DIEDFL_ATTACHEDONLY
アタッチかつインストール済みデバイスだけ列挙される。


CONST_DIEPFLAGS

CONST_DIEPFLAGS 列挙のメンバは、設定対象のパラメータ、およびエフェクトのそれ以降の動作を指定するために、DirectInputEffect.SetParameters メソッドに渡される。また、一部のメンバは、パラメータのサポートに関する情報を取得する DirectInputEnumEffects.GetStaticParams メソッドおよび DirectInputEnumEffects.GetDynamicParams メソッドにより返される。

Enum CONST_DIEPFLAGS
    DIEP_ALLPARAMS =            511 (&H1FF)
    DIEP_AXES =                  32 (&H20)
    DIEP_DIRECTION =             64 (&H40)
    DIEP_DURATION =               1
    DIEP_ENVELOPE =             128 (&H80)
    DIEP_GAIN =                   4
    DIEP_NODOWNLOAD =   -2147483648 (&H80000000)
    DIEP_NORESTART =     1073741824 (&H40000000)
    DIEP_SAMPLEPERIOD =           2
    DIEP_START =          536870912 (&H20000000)
    DIEP_TRIGGERBUTTON =          8
    DIEP_TRIGGERREPEATINTERVAL = 16 (&H10)
    DIEP_TYPESPECIFICPARAMS =   256 (&H100)
End Enum
DIEP_ALLPARAMS
未使用。
DIEP_AXES
未使用。
DIEP_DIRECTION
DIEFFECT の x および y メンバが有効である。または、方向パラメータがサポートされる。エフェクト パラメータを設定または要求している場合、DIEFFECT.lFlags の DIEFF_CARTESIAN か DIEFF_POLAR を指定することで、デカルト座標または極座標のどちらで方向を設定、または取得するかを指定できる。
DIEP_DURATION
DIEFFECT の lDuration メンバが有効である。または、エフェクトは方向の変更をサポートする。
DIEP_ENVELOPE
DIEFFECT の envelope メンバが有効である。または、エフェクトはエンベロープの適用をサポートする。
DIEP_GAIN
lGain メンバが有効である。または、エフェクトはゲインの適用をサポートする。
DIEP_NODOWNLOAD
パラメータの設定後、エフェクトをダウンロードしない。
DIEP_NORESTART
エフェクトの停止や再開を抑制してパラメータを変更する。
DIEP_SAMPLEPERIOD
lSamplePeriod メンバが有効である。
DIEP_START
パラメータの設定後、エフェクトを直ちに開始する。
DIEP_TRIGGERBUTTON
lTriggerButton メンバが有効である。または、エフェクトはトリガ ボタンをサポートする。
DIEP_TRIGGERREPEATINTERVAL
lTriggerRepeatInterval メンバが有効である。または、エフェクトはトリガの繰り返しをサポートする。
DIEP_TYPESPECIFICPARAMS
エフェクトは、アプリケーションが変更可能なタイプ固有のパラメータを持つ。この値は、すべての標準エフェクトと、アプリケーションによる変更が可能なパラメータを持つハードウェア固有のエフェクトに対して、GetStaticParams により返される。DirectX for Visual Basic は、このフラグが設定されていない場合にのみハードウェア エフェクトをサポートする。


CONST_DIESFLAGS

CONST_DIESFLAGS は、フォース フィードバック エフェクトの再生動作を制御するために使用される。

Enum CONST_DIESFLAGS
    DIES_NODOWNLOAD  = -2147483648 (&H80000000)
    DIES_SOLO =                  1
End Enum
メンバの説明については、「DirectInputEffect.Start」を参照すること。


CONST_DIGFFSFLAGS

CONST_DIGFFSFLAGS 列挙のメンバは、フォース フィードバック デバイスの状態を表す。これらのメンバは、DirectInputDevice.GetForceFeedbackState メソッドにより返される。

Enum CONST_DIGFFSFLAGS
    DIGFFS_ACTUATORSOFF =        32 (&H20)
    DIGFFS_ACTUATORSON =         16 (&H10)
    DIGFFS_DEVICELOST = -2147483648 (&H80000000)
    DIGFFS_EMPTY =                1
    DIGFFS_PAUSED =               4
    DIGFFS_POWEROFF =           128 (&H80)
    DIGFFS_POWERON =             64 (&H40)
    DIGFFS_SAFETYSWITCHOFF =    512 (&H200)
    DIGFFS_SAFETYSWITCHON =     256 (&H100)
    DIGFFS_STOPPED =              2
    DIGFFS_USERFFSWITCHOFF =   2048 (&H800)
    DIGFFS_USERFFSWITCHON =    1024 (&H400)
End Enum
DIGFFS_ACTUATORSOFF
デバイスのフォース フィードバック アクチュエータが無効である。
DIGFFS_ACTUATORSON
デバイスのフォース フィードバック アクチュエータが有効である。
DIGFFS_DEVICELOST
デバイスが予期しない障害を被り、不確定な状態にある。一度デバイスを解放した後で再取得するか、または DISFFC_RESET コマンドを送信するかどちらかでデバイスをリセットしなければならない。
DIGFFS_EMPTY
デバイスはダウンロードされた要素を持たない。
DIGFFS_PAUSED
すべてのアクティブなエフェクトの再生が一時停止されている。
DIGFFS_POWEROFF
フォース フィードバック システムは、現在使用できない。デバイスが電源状態を報告できなければ、DIFFS_POWERON および DIFFS_POWEROFF のどちらも返されない。
DIGFFS_POWERON
フォース フィードバック システムの電源は現在入っている。デバイスが電源状態を報告できなければ、DIFFS_POWERON および DIFFS_POWEROFF のどちらも返されない。
DIGFFS_SAFETYSWITCHOFF
安全スイッチが現在オフである。つまり、デバイスは動作できない。デバイスが安全スイッチの状態を報告できなければ、DIFFS_SAFETYSWITCHON および DIFFS_SAFETYSWITCHOFF のどちらも返されない。
DIGFFS_SAFETYSWITCHON
安全スイッチが現在オンである。つまり、デバイスは動作できる。デバイスが安全スイッチの状態を報告できなければ、DIFFS_SAFETYSWITCHON および DIFFS_SAFETYSWITCHOFF のどちらも返されない。
DIGFFS_STOPPED
再生中のエフェクトはなく、デバイスは中断状態ではない。
DIGFFS_USERFFSWITCHOFF
ユーザー フォース フィードバック スイッチが現在オフである。つまり、デバイスは動作できない。デバイスがユーザー フォース フィードバック スイッチの状態を報告できなければ、DIFFS_USERFFSWITCHON および DIFFS_USERFFSWITCHOFF のどちらも返されない。
DIGFFS_USERFFSWITCHON
ユーザー フォース フィードバック スイッチが現在オンである。つまり、デバイスは動作できる。デバイスがユーザー フォース フィードバック スイッチの状態を報告できなければ、DIFFS_USERFFSWITCHON および DIFFS_USERFFSWITCHOFF のどちらも返されない。


CONST_DIJOYSTICKOFS

CONST_DIJOYSTICKOFS 列挙のメンバは、データ形式内のさまざまなジョイスティック デバイス オブジェクトに対するデータのオフセットを表す。

Enum CONST_DIJOYSTICKOFS
    DIJOFS_BUTTON0 =  48 (&H30)
    DIJOFS_BUTTON1 =  49 (&H31)
    DIJOFS_BUTTON10 = 58 (&H3A)
    DIJOFS_BUTTON11 = 59 (&H3B)
    DIJOFS_BUTTON12 = 60 (&H3C)
    DIJOFS_BUTTON13 = 61 (&H3D)
    DIJOFS_BUTTON14 = 62 (&H3E)
    DIJOFS_BUTTON15 = 63 (&H3F)
    DIJOFS_BUTTON16 = 64 (&H40)
    DIJOFS_BUTTON17 = 65 (&H41)
    DIJOFS_BUTTON18 = 66 (&H42)
    DIJOFS_BUTTON19 = 67 (&H43)
    DIJOFS_BUTTON2 =  50 (&H32)
    DIJOFS_BUTTON20 = 68 (&H44)
    DIJOFS_BUTTON21 = 69 (&H45)
    DIJOFS_BUTTON22 = 70 (&H46)
    DIJOFS_BUTTON23 = 71 (&H47)
    DIJOFS_BUTTON24 = 72 (&H48)
    DIJOFS_BUTTON25 = 73 (&H49)
    DIJOFS_BUTTON26 = 74 (&H4A)
    DIJOFS_BUTTON27 = 75 (&H4B)
    DIJOFS_BUTTON28 = 76 (&H4C)
    DIJOFS_BUTTON29 = 77 (&H4D)
    DIJOFS_BUTTON3 =  51 (&H33)
    DIJOFS_BUTTON30 = 78 (&H4E)
    DIJOFS_BUTTON31 = 79 (&H4F)
    DIJOFS_BUTTON4 =  52 (&H34)
    DIJOFS_BUTTON5 =  53 (&H35)
    DIJOFS_BUTTON6 =  54 (&H36)
    DIJOFS_BUTTON7 =  55 (&H37)
    DIJOFS_BUTTON8 =  56 (&H38)
    DIJOFS_BUTTON9 =  57 (&H39)
    DIJOFS_POV0 =     32 (&H20)
    DIJOFS_POV1 =     36 (&H24)
    DIJOFS_POV2 =     40 (&H28)
    DIJOFS_POV3 =     44 (&H2C)
    DIJOFS_RX =       12
    DIJOFS_RY =       16 (&H10)
    DIJOFS_RZ =       20 (&H14)
    DIJOFS_SLIDER0 =  24 (&H18)
    DIJOFS_SLIDER1 =  28 (&H1C)
    DIJOFS_X =         0
    DIJOFS_Y =         4
    DIJOFS_Z =         8
End Enum
DIJOFS_BUTTON(n)
ボタン n のデータのオフセット。
DIJOFS_POV(n)
視点コントローラ n のデータのオフセット。
DIJOFS_RX, DIJOFS_RY, DIJOFS_RZ
軸回転のデータのオフセット。
DIJOFS_SLIDER0, DIJOFS_SLIDER1
スライダのデータのオフセット。
DIJOFS_X, DIJOFS_Y, DIJOFS_Z
軸のデータのオフセット。


CONST_DIKEYFLAGS

CONST_DIKEYFLAGS 列挙は、キーボード デバイス定数をグループ化する。


CONST_DIMOUSEOFS

CONST_DIMOUSEOFS 列挙のメンバは、データ形式内のさまざまなマウス デバイス オブジェクトに対するデータのオフセットを表す。

Enum CONST_DIMOUSEOFS
    DIMOFS_BUTTON0 = 12
    DIMOFS_BUTTON1 = 13
    DIMOFS_BUTTON2 = 14
    DIMOFS_BUTTON3 = 15
    DIMOFS_X =        0
    DIMOFS_Y =        4
    DIMOFS_Z =        8
End Enum
DIMOFS_BUTTON(n)
ボタン n のデータのオフセット。
DIMOFS_X, DIMOFS_Y, DIMOFS_Z
軸のデータのオフセット。


CONST_DINPUT

CONST_DINPUT 列挙は、DirectInput 全体で使用されるさまざまな定数を格納する。

Enum CONST_DINPUT
    DIPROPAXISMODE_ABS =           0
    DIPROPAXISMODE_REL =           1
    DIPROPCALIBRATIONMODE_COOKED = 0
    DIPROPCALIBRATIONMODE_RAW =    1
    DIPROPRANGE_NOMAX =   2147483647 (&H7FFFFFFF)
    DIPROPRANGE_NOMIN =  -2147483648 (&H80000000)
End Enum
DIPROPAXISMODE_ABS
DirectInputDevice.GetProperty および DirectInputDevice.SetProperty で使用され、絶対軸モードを表す。
DIPROPAXISMODE_REL
DirectInputDevice.GetProperty および DirectInputDevice.SetProperty で使用され、相対軸モードを表す。
DIPROPCALIBRATIONMODE_COOKED
DIPROP_CALIBRATIONMODE プロパティの設定で使用され、キャリブレーション情報の適用後に DirectInput が軸データを返すことを示す。
DIPROPCALIBRATIONMODE_RAW
DIPROP_CALIBRATIONMODE プロパティの設定で使用され、DirectInput が未加工のキャリブレーション前の軸データを返すことを示す。このモードは通常、コントロール パネル型のアプリケーションでのみ使用される。
DIPROPRANGE_NOMAX
軸の範囲に上限がない場合に DirectInputDevice.GetProperty から返される。
DIPROPRANGE_NOMIN
軸の範囲に下限がない場合に DirectInputDevice.GetProperty から返される。


CONST_DINPUTERR

CONST_DINPUTERR 列挙は、DirectInput のエラー コードを格納する。すべてのエラー コードとその定義については、「エラー コード」に記載されている。


CONST_DIPHFLAGS

CONST_DIPHFLAGS 列挙のメンバは、デバイス オブジェクトの識別方法を指定するために使用される。これらのメンバは、DirectInputDevice.GetObjectInfo メソッドのほか、DIPROPLONG 型と DIPROPRANGE 型で使用される。

Enum CONST_DIPHFLAGS
    DIPH_DEVICE  =  0
    DIPH_BYID  =    2
    DIPH_BYOFFSET = 1
End Enum
DIPH_DEVICE
プロパティは、特定のオブジェクトではなくデバイス全体に適用される。
DIPH_BYOFFSET
デバイス オブジェクトは、アクセスする情報が所属するオブジェクトの現在のデータ形式に対するオフセットで識別される。
DIPH_BYID
デバイス オブジェクトは、DirectInputDeviceObjectInstance.GetType メソッドの戻り値から取得されるインスタンス識別子で識別される。


CONST_DISCLFLAGS

CONST_DISCLFLAGS 列挙は、DirectInputDevice.SetCooperativeLevel メソッドの flags パラメータに使用され、デバイスが、そのデバイスのほかのインスタンスおよびシステムの残りの部分と通信する方法を決定する。

Enum CONST_DISCLFLAGS
    DISCL_BACKGROUND   = 8
    DISCL_EXCLUSIVE    = 1
    DISCL_FOREGROUND   = 4
    DISCL_NONEXCLUSIVE = 2
End Enum
DISCL_BACKGROUND
アプリケーションは、バックグラウンド アクセス権を要求する。バックグラウンド アクセス権が許可されると、割り当てられたウィンドウがアクティブ ウィンドウでない場合でも、いつでもデバイスを取得できる。
DISCL_EXCLUSIVE
アプリケーションは、排他アクセス権を要求する。排他アクセス権が付与されると、デバイスが取得されている間、デバイスのほかのインスタンスは、そのデバイスの排他アクセス権を取得できない。ただし、別のアプリケーションが排他アクセス権を取得している場合でも、デバイスの非排他アクセス権は常に認められる。

アプリケーションがマウス デバイスやキーボード デバイスを取得すると、ユーザーはウィンドウ メニューを使用したり、ウィンドウを移動したり、ウィンドウのサイズを変更したりすることはできなくなる。

DISCL_FOREGROUND
アプリケーションはフォアグラウンド アクセス権を要求する。フォアグラウンド アクセス権が付与されると、割り当てられたウィンドウがバックグラウンドに移動するときに、デバイスは自動的に解放される。
DISCL_NONEXCLUSIVE
アプリケーションは、排他アクセス権を要求する。デバイスに対するアクセス権は、同じデバイスにアクセスしているほかのアプリケーションの妨げにならない。

アプリケーションは、DISCL_FOREGROUND または DISCL_BACKGROUND のどちらか一方を指定しなければならない。両方指定することも、まったく指定しないこともエラーとなる。同様に、アプリケーションは、DISCL_EXCLUSIVE または DISCL_NONEXCLUSIVE のどちらか一方を指定しなければならない。


CONST_DISDDFLAGS

CONST_DISDDFLAGS 列挙のメンバは、DirectInputDevice.SendDeviceData メソッドに渡される。

Enum CONST_DISDDCFLAGS
    DISDD_CONTINUE = 1
    DISDD_DEFAULT =  0
End Enum
DISDD_CONTINUE
データは既存のデータを上書きする。詳細については、DirectInputDevice.SendDeviceData の「注意」を参照すること。
DISDD_DEFAULT
データは既存のデータを上書きしない。


CONST_DISFFCFLAGS

CONST_DISFFCFLAGS 列挙のメンバは、DirectInputDevice.SendForceFeedbackCommand メソッドで送信するコマンドを指定するために使用される。

Enum CONST_DISFFCFLAGS
    DISFFC_CONTINUE =         8
    DISFFC_PAUSE =            4
    DISFFC_RESET =            1
    DISFFC_SETACTUATORSOFF = 32 (&H20)
    DISFFC_SETACTUATORSON =  16 (&H10)
    DISFFC_STOPALL =          2
End Enum
DISFFC_CONTINUE
中断されたすべてのアクティブなエフェクトの再生を継続する。デバイスが中断状態にないときにこのコマンドを送信すると、エラーになる。
DISFFC_PAUSE
すべてのアクティブ エフェクトの再生を中断する。このコマンドはエフェクトのクロックも停止するので、再開すると、エフェクトは継続時間を満了するまで再生が続行される。

デバイスが中断状態にある間は、新しいエフェクトを開始したり、既存のエフェクトを変更したりすることはできない。そのような操作を行うと、これ以降の DISFFC_CONTINUE コマンドが正常に機能しなくなることがある。

中断を破棄してすべてのエフェクトを停止するには、DISFFC_STOPALL または DISFCC_RESET コマンドを使用する。

DISFFC_RESET
デバイスのフォース フィードバック システムを始動状態にする。すべてのエフェクトはデバイスから削除され、有効でなくなる。これらのエフェクトを再び使用するには、再生成しなければならない。デバイスのアクチュエータは無効である。
DISFFC_SETACTUATORSOFF
デバイスのフォース フィードバック アクチュエータを無効にする。アクチュエータがオフの間も、エフェクトは引き続き再生されるが、デバイスはそれを無視する。音楽再生デバイスにたとえると、エフェクトは一時停止 (ポーズ) ではなく、消音 (ミュート) された状態である。
DISFFC_SETACTUATORSON
デバイスのフォース フィードバック アクチュエータを有効にする。
DISFFC_STOPALL
すべてのアクティブなエフェクトの再生を停止する。アクティブなエフェクトはすべてリセットされるが、デバイスには保存されており、引き続き有効である。デバイスが中断されている場合、その状態は失われる。

このコマンドは、再生中のエフェクトごとに DirectInputEffect.Stop メソッドを呼び出すことに等しい。


キーボード キー

ここでは、次の内容について説明する。

  • キーボード デバイス定数
  • DirectInput と日本語キーボード


キーボード デバイス定数

CONST_DIKEYFLAGS 列挙のメンバであるキーボード デバイス定数は、キーボード デバイスのデータ パケット (256 バイト配列) 内でのオフセットを表す。指定のオフセット位置のデータは、キーボード キーに関連付けられている。

標準キーボード デバイス定数は、以下のとおりである (昇順)。

定数 | メモ
DIK_ESCAPE |
DIK_1 | メイン キーボード上
DIK_2 | メイン キーボード上
DIK_3 | メイン キーボード上
DIK_4 | メイン キーボード上
DIK_5 | メイン キーボード上
DIK_6 | メイン キーボード上
DIK_7 | メイン キーボード上
DIK_8 | メイン キーボード上
DIK_9 | メイン キーボード上
DIK_0 | メイン キーボード上
DIK_MINUS | メイン キーボード上
DIK_EQUALS | メイン キーボード上
DIK_BACK | BaackSpace キー
DIK_TAB |
DIK_Q |
DIK_W |
DIK_E |
DIK_R |
DIK_T |
DIK_Y |
DIK_U |
DIK_I |
DIK_O |
DIK_P |
DIK_LBRACKET | [
DIK_RBRACKET | ]
DIK_RETURN | メイン キーボード上の Enter キー
DIK_LCONTROL | 左 Ctrl キー
DIK_A |
DIK_S |
DIK_D |
DIK_F |
DIK_G |
DIK_H |
DIK_J |
DIK_K |
DIK_L |
DIK_SEMICOLON |
DIK_APOSTROPHE |
DIK_GRAVE | アクサン グラーブ (`) キー
DIK_LSHIFT | 左 Shift キー
DIK_BACKSLASH |
DIK_Z |
DIK_X |
DIK_C |
DIK_V |
DIK_B |
DIK_N |
DIK_M |
DIK_COMMA |
DIK_PERIOD | メイン キーボード上
DIK_SLASH | メイン キーボード上の順スラッシュ (/)
DIK_RSHIFT | 右 Shift キー
DIK_MULTIPLY | テンキー上のアスタリスク キー
DIK_LMENU | 左 Alt キー
DIK_SPACE | Space キー
DIK_CAPITAL | CapsLock
DIK_F1 |
DIK_F2 |
DIK_F3 |
DIK_F4 |
DIK_F5 |
DIK_F6 |
DIK_F7 |
DIK_F8 |
DIK_F9 |
DIK_F10 |
DIK_NUMLOCK |
DIK_SCROLL | ScrollLock
DIK_NUMPAD7 |
DIK_NUMPAD8 |
DIK_NUMPAD9 |
DIK_SUBTRACT | テンキー上のハイフン (マイナス記号) キー
DIK_NUMPAD4 |
DIK_NUMPAD5 |
DIK_NUMPAD6 |
DIK_ADD | テンキー上のプラス記号キー
DIK_NUMPAD1 |
DIK_NUMPAD2 |
DIK_NUMPAD3 |
DIK_NUMPAD0 |
DIK_DECIMAL | テンキー上のピリオド (小数点)
DIK_F11 |
DIK_F12 |
DIK_F13 |
DIK_F14 |
DIK_F15 |
DIK_KANA | 日本語キーボード上
DIK_CONVERT | 日本語キーボード上
DIK_NOCONVERT | 日本語キーボード上
DIK_YEN | 日本語キーボード上
DIK_NUMPADEQUALS | テンキー上 (NEC PC98)
DIK_CIRCUMFLEX | 日本語キーボード上
DIK_AT | 日本語キーボード上
DIK_COLON | 日本語キーボード上
DIK_UNDERLINE | 日本語キーボード上
DIK_KANJI | 日本語キーボード上
DIK_STOP | 日本語キーボード上
DIK_AX | 日本語キーボード上
DIK_UNLABELED | 日本語キーボード上
DIK_NUMPADENTER |
DIK_RCONTROL | 右 Ctrl キー
DIK_NUMPADCOMMA | NEC PC98 テンキー上のコンマ
DIK_DIVIDE | テンキー上の順スラッシュ (/)
DIK_SYSRQ |
DIK_RMENU | 右 Alt キー
DIK_HOME |
DIK_UP | 上向き矢印キー
DIK_PRIOR | PageUp キー
DIK_LEFT | 左向き矢印キー
DIK_RIGHT | 右向き矢印キー
DIK_END |
DIK_DOWN | 下向き矢印キー
DIK_NEXT | PageDown キー
DIK_INSERT |
DIK_DELETE |
DIK_LWIN | 左 Windows キー
DIK_RWIN | 右 Windows キー
DIK_APPS | アプリケーション キー
DIK_PAUSE |

日本語キーボードについては、「DirectInput と日本語キーボード」を参照すること。


エラー コード

以下は、DirectInput メソッドと関数によって返されるエラー コードの一覧である。エラーは負の値によって示され、結合することができない。

それぞれのメソッドまたは関数はエラー値を返すことができるが、詳しくはそれぞれの説明を参照すること。本文中のエラー コードの一覧は、必然的に不完全になっている。たとえば、どんな DirectInput メソッドも DIERR_OUTOFMEMORY を返すことができるが、本文中では、このエラー コードはそのメソッドの戻り値としては明示されていない。

DI_BUFFEROVERFLOW
入力バッファがオーバーフローし、データが失われた。
DIERR_ACQUIRED
操作は、デバイスが取得状態の間は実行できない。
DIERR_ALREADYINITIALIZED
このオブジェクトは初期化済みである。
DIERR_BADDRIVERVER
オブジェクトは、互換性のないドライバ バージョン、あるいは不適格または不完全なドライバ コンポーネントであるために作成できなかった。
DIERR_BETADIRECTINPUTVERSION
アプリケーションは、DirectInput のサポートされていないリリース前のバージョン用に作成されたものである。
DIERR_DEVICEFULL
デバイスはフルである。
DIERR_DEVICENOTREG
デバイスまたはデバイス インスタンスが DirectInput に登録されていない。この値は、標準の COM 戻り値である REGDB_E_CLASSNOTREG に等しい。
DIERR_EFFECTPLAYING
パラメータは、メモリ内では更新されたが、デバイスにはダウンロードされなかった。デバイスが再生中のエフェクトの更新をサポートしていないためである。
DIERR_HASEFFECTS
エフェクトがデバイスにアタッチされているため、デバイスを再初期化できない。
DIERR_GENERIC
DirectInput サブシステムで 原因不明のエラーが発生した。この値は、標準の COM 戻り値である E_FAIL に等しい。
DIERR_HANDLEEXISTS
デバイスは、既に、自身にイベント通知の関連付けをしている。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_INCOMPLETEEFFECT
必須情報がないので、エフェクトをダウンロードできなかった。たとえば、エフェクトに関連する軸がなかったり、タイプ固有情報が与えられていない場合。
DIERR_INPUTLOST
入力デバイスのアクセス権を失った。再取得しなければならない。
DIERR_INVALIDHANDLE
無効なウィンドウ ハンドルがメソッドに渡された。
DIERR_INVALIDPARAM
無効なパラメータが戻ってくる関数に渡されたか、オブジェクトがその関数を呼び出せる状態になかった。この値は、標準の COM 戻り値である E_INVALIDARG に等しい。
DIERR_MOREDATA
要求情報の一部がバッファに収まらなかった。
DIERR_NOAGGREGATION
オブジェクトは、集合化をサポートしない。
DIERR_NOINTERFACE
オブジェクトは、指定のインターフェイスをサポートしていない。この値は、標準の COM 戻り値である E_NOINTERFACE に等しい。
DIERR_NOTACQUIRED
操作は、デバイスが取得されない限り実行できない。
DIERR_NOTBUFFERED
デバイスは、バッファリングされていない。バッファリングを有効にするには DIPROP_BUFFERSIZE プロパティを設定する。
DIERR_NOTDOWNLOADED
エフェクトがダウンロードされていない。
DIERR_NOTEXCLUSIVEACQUIRED
操作は、デバイスが DISCL_EXCLUSIVE モードで取得されていなければ実行できない。
DIERR_NOTINITIALIZED
このオブジェクトは、初期化されていなかった。
DIERR_NOTFOUND
要求されたオブジェクトは存在しない。
DIERR_OBJECTNOTFOUND
要求されたオブジェクトは存在しない。
DIERR_OLDDIRECTINPUTVERSION
アプリケーションは、より新しいバージョンの DirectInput を必要とする。
DIERR_OTHERAPPHASPRIO
ほかのアプリケーションの優先レベルの方が高いので、この呼び出しの実行がうまくいかない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。このエラーは、アプリケーションのデバイスに対するアクセス権が、フォアグラウンド アクセス権であるにもかかわらず、バックグラウンドにいるときに、デバイスを取得しようとした場合に返される。
DIERR_OUTOFMEMORY
DirectInput サブシステムが呼び出しを完了するのに十分なメモリを割り当てることができなかった。この値は、標準の COM 戻り値である E_OUTOFMEMORY に等しい。
DIERR_READONLY
指定のプロパティは変更できない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_REPORTFULL
送られる情報の方が、デバイスに送ることができる情報よりも多い。
DIERR_UNPLUGGED
この操作は、デバイスが接続されていない可能性を示す。
DIERR_UNSUPPORTED
この関数呼び出しは、この時点ではサポートされない。この値は、標準の COM 戻り値である E_NOTIMPL に等しい。
E_PENDING
データは、まだ使用不可である。


DirectInput のツールとサンプル

ここでは、DirectX SDK に付属するツールおよびサンプル アプリケーションのうち、DirectInput に関連するものについて説明する。説明する内容は以下のとおりである。

  • DirectInput ツール
  • DirectInput C/C++ サンプル
  • DirectInput Visual Basic サンプル


DirectInput ツール

DirectInput で使用するために以下のツールが用意されている。

  • DirectInput QuickTest
  • Force Editor


DirectInput QuickTest

説明

DirectInput QuickTest アプリケーションを使うと、デバイスおよびデバイス オブジェクトのプロパティを表示したり、デバイスからの入力データを表示したりすることができる。

パス

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin\Diquick.exe

ユーザーズ ガイド

初期画面で、デバイスを選択して [Create] ボタンをクリックする。デバイスが正常に作成されたら、複数のタブを持つプロパティ シートが表示される。

[Mode] ページでは、協調レベル、データ モード、および軸モードを選択する。ジョイスティックの場合、ポーリング データ モードを選択しなければならない。また、[Form of] ボックスからデバイス タイプを確認する必要もある。バッファリング データを表示したい場合は、このページでバッファ サイズにゼロより大きい値を指定しなければならない。

[Caps] ページでは、デバイスに関するその他の情報を指定する。

[Objects] ページでは、デバイス上で選択されたボタンや軸を列挙できる。[Properties] ボタンをクリックすると、選択したオブジェクトに対して、DIDEVICEOBJECTINSTANCE 構造体 (C++) または DirectInputDeviceObjectInstance オブジェクト (Visual Basic) で表されるデータのサマリが表示される。このプロパティ シートでは、軸の範囲、無効ゾーン、および飽和点を設定することもできる。

また、[Data] ページには、デバイスからの入力データが表示される。ページの左側には直接データ、ページの右側にはバッファリング データ (バッファ サイズを設定済みの場合) が表示される。


Force Editor

説明

Force Editor アプリケーションを使うと、フォース フィードバック エフェクトをデザインしたり、そのエフェクトを単独でテストしたり、いくつかのエフェクトを組み合わせてテストしたりすることができる。エフェクトは、ファイルに保存して、DirectInput アプリケーションに読み込ませることができる。

パス

実行可能ファイル :(SDK ルート)\Bin\Dxutils\Fedit.exe

ユーザーズ ガイド

F1 キーを押すと、オンライン ヘルプが表示される。


DirectInput C/C++ サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

以下のサンプル プログラムには、DirectInput の使い方と機能が示されている。

  • DIGame サンプル
  • FFDonuts サンプル
  • FFFileRead サンプル
  • JoyFFeed サンプル
  • JoystImm サンプル
  • KeybdBuf サンプル
  • KeybdExc サンプル
  • KeybdImm サンプル
  • MouseExc サンプル
  • MouseNon サンプル
  • Scrawl サンプル

さらに、DirectInput の基本機能について具体的に説明する詳細なコメント入りのソース コードが、次の場所に収録されている。

(SDK ルート)\Samples\Multimedia\DInput\Src\Tutorials

DirectX のサンプルには Microsoft® Visual C++® プロジェクト ワークスペース ファイルが含まれているが、読者の開発環境で正しくコンパイルできるかどうかを確認する必要がある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。


DIGame サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

DIGame サンプル アプリケーションは、キーボード、マウス、またはジョイスティックでプレイできる、単純なシューティング ゲームである。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\DIGame

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin

ユーザーズ ガイド

デフォルトの入力デバイスはキーボードである。デバイスを変更するには、[File] メニューの [Select Input Device] をクリックする。

矢印キー、マウス、またはジョイスティックを使って、船体を上方向や下方向に移動する。左や右に動かすと、方向が変化する。Space キー、左マウス ボタン、またはジョイスティックのメイン ボタンを押すと、発射する。

もう一度開始するには、[File] の [New Game] をクリックする。

プログラミング上の注意

入力コードはすべて Digame.cpp に含まれている。


FFDonuts サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

このプログラムは「Space Donuts サンプル プログラム」を改変したもので、フォース フィードバック ジョイスティックが接続されている場合にフォース フィードバック出力を追加する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\FFdonuts

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin

ユーザーズ ガイド

プログラムを起動すると、ダイアログ ボックスが表示される。ここで、フォース フィードバック エフェクトのマグニチュードを設定する。

宇宙船が表示されたら、加速するにはジョイスティックを前に倒し、減速したり後退したりするにはジョイスティックを引き戻す。ジョイスティックを右や左に動かすと、宇宙船が回転する。トリガ ボタンを押すと、弾丸が発射する。セカンド ボタンを押すと、シールドが張られる。弾丸が発射されたり、物体に衝突したり、画面の端ではねかえったりしたときに、フォース フィードバックが効くことを確認してもらいたい。

プログラミング上の注意

フォース フィードバックのルーチンは、Input.c ファイルに記述されている。このプログラムは、コンスタント フォース、周期的エフェクト、エンベロープ、およびゲインの使用法を具体的に説明している。発射ボタンのエフェクトは、DIEFFECT 構造体でトリガ ボタンに連動するのではなく、通常の入力イベントに反応して動作することに注意すること。

参照

Space Donuts サンプル


FFFileRead サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルでは、Force Editor で作成されたファイルからエフェクトを読み取る方法やエフェクトを生成する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\FFFileRead

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin\FFeedFileRead.exe

メディア ファイル :(SDK ルート)\Samples\Multimedia\DInput\Media

ユーザーズ ガイド

[Read File] をクリックして、Media フォルダに用意されている .ffe ファイルか、または独自に作成したファイルを読み込む。次に、[Play Effects] をクリックする。

プログラミング上の注意

ファイルから列挙されたエフェクトのそれぞれについて、EnumAndCreateEffectsCallback 関数が IDirectInputEffect ポインタを初期化し、そのポインタをリンクされたリストに追加する。OnPlayEffects 関数がこのリストを処理し、すべてのエフェクトを再生する。


JoyFFeed サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

このアプリケーションは、実際の動作をフォース フィードバック ジョイスティックに適用し、シミュレータのようなアプリケーションで、フォース フィードバックを使って、物理エンジンで計算されたフォースを生成する方法を具体的に示す。

このアプリケーションを動作させるには、フォース フィードバック デバイスを接続しなければならない。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\JoyFFeed

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin

ユーザーズ ガイド

このアプリケーションを起動すると、十字カーソルと黒いポイントがウィンドウに表示される。ウィンドウのクライアント エリア内の任意の場所でマウスをクリックすると、黒いポイントが移動する(ジョイスティックのハンドルを動かしても何も起こらないことに注意)。JoyFFeed は、十字カーソルからの距離に比例して、ポイントの方向からジョイスティックのハンドルにコンスタント フォースを与える。マウスのボタンを押し続けると、ポイントを継続的に動かすこともできる。

プログラミング上の注意

このサンプル プログラムは、入力デバイスがいくつ接続されているかを列挙し、最初に検出されたフォース フィードバック ジョイスティックを取得する。検出されなければ、メッセージを表示してプログラムを終了する。

黒いポイントを移動すると、joySetForcesXY 関数は、カーソルの座標をフォースの方向とマグニチュードに変換する。このデータは、コンスタント フォース エフェクトのパラメータを変更するのに使われる。


JoystImm サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

JoystImm サンプルは、ジョイスティックのデータを取得し表示する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\JoystImm

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin

ユーザーズ ガイド

ジョイスティックを動かしたりひねったり、スロットル ホイールを回したり、さまざまな組み合わせでボタンを押したりしたときに、表示されたデータがどのように変化するかを観察する。

プログラミング上の注意

このアプリケーションは、ダイアログ プロシージャ内部に設定されたタイマに応答して、ジョイスティックの直接データをポーリングする。


KeybdBuf サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

KeybdBuf プログラムは、キーボードのデータを取得し表示する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\src\KeybdBuf

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\bin

ユーザーズ ガイド

キーを押したり、離したりするたびに、イベントが画面に記録される。キーは、インデックス値によって特定される (「キーボード デバイス定数」を参照)。

プログラミング上の注意

このサンプルは、アプリケーションがキーボードのバッファリング データを取得するにはどのように DirectInput を使用するかを説明している。


KeybdExc サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

KeybdExc サンプルは、キーボードを排他協調レベルで使用する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\KeybdExc

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin\KeybdExc.exe

ユーザーズ ガイド

1 つまたは複数のボタンを押し続けると、それぞれのキーのインデックス値 (「キーボード デバイス定数」を参照) が表示される。Windows キーを押すと、「KeybdImm サンプル」では [スタート] メニューが表示されるが、このプログラムでは表示されないことに注意すること。

プログラミング上の注意

このサンプルは、排他フォアグラウンド協調レベルでキーボードの直接データを取得するにはどのように DirectInput を使用するかを説明している。このアプリケーションは繰り返し IDirectInputDevice7::GetDeviceState を呼び出し、押されているすべてのキーの値を含む文字列を表示する。


KeybdImm サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

Kyebdlmm プログラムは、キーボードのデータを取得し表示する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\KeybdImm

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin

ユーザーズ ガイド

1 つまたは複数のボタンを押し続けると、それぞれのキーのインデックス値 (「キーボード デバイス定数」を参照) が表示される。

プログラミング上の注意

このサンプルは、非排他フォアグラウンド協調レベルでキーボードの直接データを取得するにはどのように DirectInput を使用するかを説明している。このアプリケーションは繰り返し IDirectInputDevice7::GetDeviceState を呼び出し、押されているすべてのキーの値を含む文字列を表示する。


MouseExc サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

MouseExc プログラムは、DirectInput デバイスの初期化と直接データを取得する方法を説明している。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\MouseExc

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin

ユーザーズ ガイド

マウスを動かすと、それに応じて座標が変化して表示される。マウス ボタンを押し続けると、そのボタンの番号が表示される。システム カーソルが表示されなくなることに注意すること。

プログラミング上の注意

このサンプルは、排他フォアグラウンド モードでマウスの相対データを取得するにはどのように DirectInput を使用するかを説明している。このプログラムは、直前に IDirectInputDevice7::GetDeviceState を呼び出してからのマウス座標の変化を 1 秒間に約 30 回表示する。


MouseNon サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

MouseNon プログラムは、DirectInput デバイスの初期化とデータの直接の取得をどのように行うかを説明している。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\MouseNon

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin

ユーザーズ ガイド

マウスを動かすと、それに応じて座標が変化して表示される。マウス ボタンを押し続けると、そのボタンの番号が表示される。カーソルはアプリケーション ウィンドウに表示されないが、アプリケーションはフォアグラウンドになっていなければならないことに注意すること。

プログラミング上の注意

このサンプルは、非排他フォアグラウンド モードでマウスの相対データを取得するにはどのように DirectInput を使用するかを説明している。このプログラムは、直前に IDirectInputDevice7::GetDeviceState を呼び出してからのマウス座標の変化を 1 秒間に約 30 回表示する。


Scrawl サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectInput Visual Basic サンプル」を参照すること。

[C++]

説明

Scrawl アプリケーションは、ウィンドウ表示アプリケーションの排他モードでのマウスの使い方を説明している。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DInput\Src\Scrawl

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DInput\Bin

ユーザーズ ガイド

ユーザーがコントロール パネルで設定している内容にかかわらず、メインのマウス ボタンは常に左ボタンで、セカンダリ ボタンは右ボタンである。

左ボタンを押しながらマウスを動かすと、線が描かれる。右ボタンをクリックすると、ポップアップ メニューが表示される。ポップアップ メニューからは、クライアント ウィンドウの消去、マウス感度の設定、アプリケーションの終了を選択することができる。

プログラミング上の注意

Scrawl アプリケーションは、次のような DirectInput プログラミングのさまざまな面を示している。

  • ウィンドウ表示アプリケーションの排他モードでマウスを使用する。
  • メニューを使うために Windows が必要としたときにマウスを解放する。
  • Windows がマウスを必要としなくなったときに、マウスを再取得する。
  • デバイスのバッファリング データを読み取る。
  • 座標の移動が完了するまで画面表示の更新を延期する。
  • デバイスの活動状況を通知する。
  • 任意の範囲にカーソルの動きを制限する。
  • 使用前に、未処理のマウス座標を計測する。
  • 相対座標モードを使用する。


DirectInput Visual Basic サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ サンプル」を参照すること。

[Visual Basic]

以下のサンプル プログラムには、DirectInput の使い方と機能が示されている。

  • ForceFeedback サンプル
  • Joystick サンプル
  • Keyboard サンプル
  • ScrawlB サンプル


ForceFeedback サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ サンプル」を参照すること。

[Visual Basic]

説明

このサンプルは、エフェクトの生成、パラメータの設定、およびエフェクトの再生を行うことができる簡単なフォース フィードバック エディタである。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Src\FFeedback

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Bin\ForceFeedback.exe

ユーザーズ ガイド

一覧からエフェクト タイプを選択し、パラメータを変更する。ジョイスティックの主ボタンを押すと、エフェクトが再生される。

プログラミング上の注意

このサンプルでは、自動センタリング プロパティをオフにする方法、およびエフェクトを生成して変更する方法を示す。エフェクト パラメータの変更は、直ちに適用される。


Joystick サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ サンプル」を参照すること。

[Visual Basic]

説明

Joystick サンプルでは、ジョイスティックを列挙し、ジョイスティックのプロパティを設定し、直接データを取得する方法を示す。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Src\Joystick

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Bin\Joystick.exe

ユーザーズ ガイド

一覧からジョイスティックを選択する。軸およびボタンから取得されたデータが表示される。

プログラミング上の注意

選択肢が DirectInputEnumDevices コレクションから容易に取得できるように、リスト ボックスはソートされない。


Keyboard サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ サンプル」を参照すること。

[Visual Basic]

説明

Keyboard サンプルでは、キーボード デバイスを作成して直接データを取得する方法を示す。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Src\Keyboard

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Bin\Keyboard.exe

ユーザーズ ガイド

1 つ以上のキーを押し下げると、そのキーの名前 (CONST_DIKEYFLAGS) がリスト ボックスに表示される。

プログラミング上の注意

バックグラウンド協調レベルを使用するので、アプリケーションに入力フォーカスがなくても、キーは読み取られる。


ScrawlB サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectInput C/C++ サンプル」を参照すること。

[Visual Basic]

説明

ScrawlB サンプルでは、マウスを排他モードで使用する方法、マウス イベントのイベント通知を使用する方法、およびバッファリング データを取得して解釈する方法を示す。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Src\Scrawlb

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Bin\Scrawlb.exe

ユーザーズ ガイド

左ボタンを押し下げると描画する。右ボタンをクリックすると、コンテキスト メニューが表示される。[Suspend] を選択する (または Alt キーを押して離す) と、システム カーソルが解放されるので、ウィンドウを移動したり、ウィンドウのサイズを変更したり、別のアプリケーションをクリックしたりできる。描画を再開するには、クライアント ウィンドウをもう一度クリックする。

Alt + Tab キーを押して別のアプリケーションに切り替えると、ScrawlB はクライアント ウィンドウにマウスを渡すと同時に、マウスを回復する。

プログラミング上の注意

アプリケーションは、WM_ENTERMENULOOP メッセージをインターセプトするために、メイン ウィンドウをサブクラス化する。ユーザーが Alt キーを押しながらスペース キーを押してシステム メニューを開いたかどうかを調べるには、これが最適な方法である。これがわかれば、ScrawlB はマウスを解放できる。ただし、サブクラス化すると、デバッグ時に問題が生じることがある。modMain.bas のコメントを参照すること。

frmCanvas モジュールは、入力イベントを処理するために DirectXEvent を実装する。また、このフォームでは、DirectInput がマウスに対するアクセス権を持たないときに Windows マウス イベントを取得するために、Visual Basic の MouseMove イベントを使用する。このイベントがトリガされると、アプリケーションはカーソルがクライアント ウィンドウに戻ったことを認識するので、マウスを再取得することができる。


DirectMusic

ここでは、DirectX® の DirectMusic コンポーネントに関する情報を、次のトピックに分けて記述する。

  • DirectMusic について
  • DirectMusic を使用する理由
  • DirectMusic アーキテクチャ
  • DirectMusic の要点
  • DirectMusic チュートリアル
  • DirectMusic リファレンス
  • DirectMusic サンプル


DirectMusic について

DirectMusic は、Microsoft® DirectX® API のミュージック コンポーネントである。デジタル サウンド サンプルのキャプチャと再生を行う Microsoft® DirectSound® API とは異なり、DirectMusic はメッセージ ベースのミュージック データを処理する。ミュージック データは、ハードウェアまたはソフトウェア シンセサイザにより、ウェーブ サンプルに変換される。デフォルトのソフトウェアの実装では、Microsoft® Software Synthesizer を使ってウェーブ サンプルが作成される。作成したサンプルは、DirectSound へのストリームに送られる。音色の発音は、ダウンローダブル サウンド (DLS) 規格に従って、サンプルから合成される。

MIDI (Musical Instrument Digital Interface) フォーマットでの入力のサポートはもちろんのこと、DirectMusic では実行時に音楽をアレンジすることができる。この音楽は、アルゴリズムで生成されるのではなく、作曲者がオーサリングした要素に基づいて生成される (オーサリン グツールの Microsoft® DirectMusic Producer は、別途ドキュメント化されている)。音楽はさまざまなバリエーションで演奏され、プログラムのイベントに動的に応答することができる。

DirectX のほかのコンポーネントと同様、DirectMusic は COM (Component Object Model、コンポーネント オブジェクト モデル) に基づいている。

DirectMusic は、Microsoft® Windows® 95、Microsoft® Windows® 98、および Microsoft® Windows® 2000 において、すべての機能を発揮できる。ただし、ハードウェア アクセラレーションを利用できるのは、Windows 2000 および Windows 98 Second Edition のみである。


DirectMusic を使用する理由

DirectMusic API は、Windows プラットフォームで音楽を演奏するために、次の基礎的な要件を処理する。

  • 再生を一貫性のある方法で再現。ダウンローダブル サウンドを使うことにより、アプリケーションはあらゆるコンピュータで同じ音色の音を再生することができる。また、アプリケーション独自の設計による音色を使った演奏ができる。
  • ジッタフリーのタイミング。MIDI で生成された音楽の再生は、タイミング精度が 2 ミリ秒以内である。
  • 拡張性。DirectMusic により、ベンダーが基本レベルの機能セットに制限されることはない。
  • ハードウェア アクセラレーション。Windows 98 Second Edition および Windows 2000 では、DirectMusic は DLS 対応のハードウェア シンセサイザのストリームに出力することができる。
  • ソフトウェア エミュレーション。ハードウェア アクセラレーション機能を備えていないコンピュータも、パフォーマンスに及ぼす影響を最小限に抑えて DirectMusic に完全に対応できる。

加えて、DirectMusic はアプリケーション開発の簡素化とユーザーの経験向上を図って、次の重要な機能を提供する。

  • パフォーマンス テクノロジにかかわりなく、ミュージック セグメントのロードと演奏を行うための一般的なメカニズム。DirectMusic は、スタンダード MIDI ファイル、オーサリングされたミュージック セグメント、およびサードパーティのテクノロジを等しくサポートする。
  • 多重演奏。音楽の複数のピースを同時に演奏でき、タイミングや音色セットなどを完全に分離できる。
  • 16 を超える MIDI チャンネル。パフォーマンス チャンネルをチャンネル グループにマッピングすることにより、DirectMusic はチャンネル数 16 の制約を打破し、任意の数の発音をシンセサイザの制限まで、同時に演奏することを可能にした。
  • DLS 音色の自動管理。
  • ダイナミックでインタラクティブな再生。DirectMusic Producer と組み合わせることにより、DirectMusic パフォーマンス エンジンを使って、保存された楽曲材料をベースとするダイナミックな音楽サウンド トラックを作成できる。音楽は、演奏される直前まで最終的な形式とは見なされず、プログラム イベントに応答することができる。
  • マスタ クロックの使用による、すべての音楽再生の同期化。


DirectMusic アーキテクチャ

ここでは、DirectMusic のコンポーネントを紹介する。次の項目について説明する。

  • コア レイヤとパフォーマンス レイヤ
  • DirectMusic オブジェクトとインターフェイスの概要 (C/C++)
  • DirectMusic クラスの概要 (Visual Basic)
  • DirectMusic のデータの流れの概要
  • DirectMusic メッセージ
  • ダウンローダブル サウンド
  • Microsoft Software Synthesizer

これらのコンポーネントをアプリケーションに実装する方法については、「DirectMusic の要点」を参照すること。


コア レイヤとパフォーマンス レイヤ

DirectMusic のコア レイヤはタイミングとポートを管理し、DLS コレクションを管理するためのサービスを提供する。バッファとタイム スタンプを備えた MIDI 入出力をサポートする。デフォルトでは、MIDI データは DirectMusic によってシーケンス化される。

コア レイヤには Microsoft Software Synthesizer も含まれるが、これは DLS サポートのハードウェア エミュレーションとして機能する。ユーザーのコンピュータに DLS ハードウェア アクセラレーションがない場合、ソフトウェア シンセサイザは DLS を使って、シーケンス化された MIDI データからウェーブ出力を合成する。ベンダーは独自のソフトウェア シンセサイザを作成してもよい。

DirectMusic のパフォーマンス レイヤは、MIDI ファイルのロードと再生、音楽のアレンジなど、音楽再生の上位レベルの処理を、DirectMusic Producer などのアプリケーションでオーサリングされた要素に基づいて処理する。

[C++]

コア レイヤのインターフェイスおよび関連する API 要素は、Dmusicｃ.h ヘッダー ファイルで宣言されている。また、パフォーマンス レイヤのインターフェイスと API 要素は、Dmusici.h ヘッダー ファイルで宣言されている。

[Visual Basic]

DirectX for Visual Basic では、主にパフォーマンス レイヤが公開される。複数のポートを操作したり、DLS データを下位レベルで操作したり、独自のデータ トラックを作成する必要のある特殊なアプリケーションには、C++ を使用する。


DirectMusic オブジェクトとインターフェイスの概要

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic クラスの概要」を参照すること。

[C++]

DirectMusic では、多くのオブジェクトが複数のインターフェイスを備えているので、オブジェクトとその COM インターフェイスを区別することが重要である。たとえば、IDirectMusicCollection インタフェースをサポートするオブジェクトは、IDirectMusicObject と同様に、COM の標準的な IPersistStream インターフェイスをもサポートする。

ここでは、DirectMusic オブジェクトをその主要または固有のインターフェイス名で呼ぶが、最初の "I" は省略する。そのため、IDirectMusicCollection によって表されるオブジェクトを DirectMusicCollection オブジェクトと呼ぶ。オブジェクトは、コレクション、パフォーマンス、セグメント、トラックなどの、短い名前で呼ばれる場合もある。

インターフェイス ポインタはしばしばそのオブジェクトへのポインタとして使われるので、ほかのインターフェイスのメソッドを通してそれらのオブジェクトにアクセスもできる。実際、インターフェイスの 1 つである IDirectMusicDownloadedInstrument は、自分自身の固有なメソッドを備えておらず、ほかのインターフェイスのメソッドのパラメータとしてのみ使われる。

DirectMusic は多くの COM オブジェクトとインターフェイスによって構成されており、それらは複雑な方法で互いに関連している。ただし、次の広範な機能に従っていくつかのカテゴリに分類できる。

  • コア オブジェクトとインターフェイス
  • ローダー オブジェクトとインターフェイス
  • 音色オブジェクトとインターフェイス
  • ツール オブジェクトとインターフェイス
  • パフォーマンス オブジェクトとインターフェイス
  • コンポーザ オブジェクトとインターフェイス
  • シンセサイザ オブジェクトとインターフェイス


コア オブジェクトとインターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic クラスの概要」を参照すること。

[C++]

コア オブジェクトは、DirectMusic の基本的な要求 (入力、出力、およびタイミング) を処理する。これらのオブジェクトは、通常は DirectMusicPerformance などのほかのオブジェクトで管理され、開発者が直接インターフェイスを使用する必要はない。

DirectMusic オブジェクト

IDirectMusic インターフェイスによって表される DirectMusic オブジェクトは、ポートとバッファの作成、DirectSound との接続、およびマスタ クロックの設定に使われる。各アプリケーションは、このオブジェクトのインスタンスを複数作成すべきではない。

多くのアプリケーションでは、直接 IDirectMusic インターフェイスを使用する必要はない。この点は、DirectX ベースのほかのインターフェイスとは異なる。たとえば、IDirectSound はあらゆる DirectSound アプリケーションの出発点である。協調レベルの設定やサウンド バッファの作成などの基本的なタスクを実行する。一方、DirectMusic では、初期化のほとんどは DirectMusicPerformance などのほかのオブジェクトによって処理され、これらのオブジェクトは CoCreateInstance を直接呼び出して独立的に作成される。

ポート

ミュージック データの送受信を行う各デバイスは、DirectMusicPort オブジェクト内にカプセル化されている。IDirectMusicPort インターフェイスのメソッドを使うとポートを直接操作できるが、ポートはパフォーマンスによって管理されているため、ほとんどのアプリケーションではこれらのメソッドを必要としない。たとえば、チャンネル内のデータが正しくルーティングされるようにするには、DirectMusicPerformance オブジェクトを通してチャンネルをポートに割り当てる。

バッファ

IDirectMusicBuffer インターフェイスは、ポートで演奏する準備 (またはポートから読み込む準備) ができているデータを表す。ほとんどのアプリケーションではバッファ オブジェクトを直接扱うことはないが、必要な場合は、その内容を直接操作するためのメソッドが提供されている。

スルー

IDirectMusicThru インターフェイスは、キャプチャ ポートから別のポートへのデータの直接転送を設定するために使用される。

基準クロック

IReferenceClock インターフェイスを実装するオブジェクトはマスタ クロックを表し、すべての DirectMusic アクティビティとポートの遅延時間クロックを同期させる。


ローダー オブジェクトとインターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic クラスの概要」を参照すること。

[C++]

DirectMusicCollection や DirectMusicStyle のような特定のタイプのオブジェクトは、音楽のパフォーマンスに組み込む前に (通常はファイルから) ロードしなければならない。DirectMusicSegment などのその他のオブジェクトは、実行時にロードまたは構築することができる。ここで紹介しているインターフェイスは、ロードに必要である。

ローダー

DirectMusicLoader オブジェクトは、IDirectMusicLoader インターフェイスを通じて、オブジェクトの列挙、キャッシング、およびロードを管理する。

ストリーム

ファイルまたはリソースから読み込まれるデータは、ストリーム オブジェクトによって表される。ストリームはローダーによって作成および管理され、ほとんどのアプリケーションでは直接ストリームを処理する必要はない。ストリーム オブジェクトは、次の 2 つのインターフェイスを実装する。

  • IStream は、ファイルまたはリソースからデータをストリームに入れ、ロードされているオブジェクトに渡す。オブジェクトは IPersistStream の実装を使って、これを解析する。
  • IDirectMusicGetLoader は、ストリームを作成した DirectMusicLoader オブジェクトへのポインタを返す、1 つのメソッドを有する。このインターフェイスは、ストリームにほかのオブジェクトへの参照が見つかった場合、およびロードされているオブジェクトがローダーを呼び出して、参照されたオブジェクトをロードする場合に使用される。

これらのインターフェイスをロード処理で使用する方法の詳細については、「DirectMusic ローダー」を参照すること。

オブジェクト

ファイルやリソースを表す DirectMusic のすべてのオブジェクトは、IDirectMusicObject インターフェイスをサポートする。これは、ローダーによって汎用のポインタとして使用される。アプリケーションがこのインターフェイスへのポインタを取得している場合は、IDirectMusicObject::QueryInterface メソッドを使って、IDirectMusicCollection や IDirectMusicStyle などの、オブジェクト固有のインターフェイスへのポインタを取得できる。ただし、通常は IDirectMusicLoader::GetObject の呼び出しで、必要なインターフェイスを取得することができる。

IDirectMusicObject のメソッドは、ローダーがオブジェクトを識別するために内部で使用される。


音色オブジェクトとインターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic クラスの概要」を参照すること。

[C++]

音色は、基本的なミュージック ティンバーまたはその他のサウンドを表すオブジェクトである。旧来のハードウェア MIDI ポートを除くすべてのポートで、各音色はダウンローダブル サウンド (DLS) の独自のセットに関連付けられる。DLS は、音色を使用する前にポートにダウンロードしなければならない。

ダウンローダブル サウンドは、3 つの抽象化レベルで処理できる。最も高いレベルでは、ファイルからバンドをロードし、バンド オブジェクトを使って音色の DLS をダウンロードする。次のレベルでは、コレクションの各音色に直接アクセスして、ポートにダウンロードする。最も低いレベルでは、DLS データそのものを操作する。

音色の管理には、次のオブジェクトとインターフェイスを使用する。

コレクション

音色は DirectMusicCollection オブジェクトに格納される。このオブジェクトは、DLS ファイルのインスタンスを表す。DirectMusicCollection オブジェクトがロードされると、IDirectMusicCollection インターフェイスを使って、コレクションの音色を列挙し、指定した MIDI パッチ番号を持つ音色へのポインタを取得できる。

音色

コレクションの音色は、IDirectMusicInstrument インターフェイスへのポインタによって表される。このポインタを IDirectMusicPerformance::DownloadInstrument または IDirectMusicPort::DownloadInstrument メソッドに渡して、ポートに DLS データをダウンロードすることができる。

ダウンロードされた音色は、IDirectMusicDownloadedInstrument インターフェイス ポインタによって表される。このポインタは、IDirectMusicPort::UnloadInstrument を呼び出して音色をアンロードする場合にのみ使われる。

音色用の独自の DLS データをダウンロードする必要があるアプリケーション (コレクション編集ツールなど)は、ポート オブジェクトによって実装された IDirectMusicPortDownload インターフェイスのメソッドを使って、シンセサイザ用のデータを取得できる。このインターフェイスを使って音色データのバッファを割り当てると、IDirectMusicDownload インターフェイス ポインタが返される。このインターフェイスの唯一のメソッドを使って、バッファそのものへのポインタを取得することができる。

バンド

DirectMusicBand オブジェクトは、一連の音色を表しており、これによって MIDI プログラムはミュージック セグメントに変更を加える。バンドは、オーサリング ツールで作成され、ファイルから別個にロードすることができる。また、オーサリングされたセグメントまたはスタイルの一部とすることもできる。

IDirectMusicBand インターフェイスを使って、バンドをダウンロードおよびアンロードすることができる。このインターフェイスには、バンドからセカンダリ セグメントを作成するメソッドも含まれる。このセグメントはパフォーマンスによって演奏され、プログラム チェンジを実行する。

コレクションとバンドの重要な違いは次のとおりである。

  • コレクションは、任意のセグメントの再生に利用できる音色のグループである。バンドは、特定のセグメントを実際に演奏する音色のグループである。
  • コレクション中の音色には、ティンバーを定義している DLS データが含まれている。バンドの音色にはこれらのデータは含まれていないが、1 つまたは複数のコレクションの音色へリンクされる。
  • コレクションの音色は、セグメントの特定のパフォーマンス チャンネル (P チャンネル) には関連付けられていない。バンドは、音色のパッチ番号をセグメント内の各 P チャンネルに割り当て、発音の優先順位をチャンネルに割り当てる。
  • コレクションは、音色を演奏する方法に関して何も情報を保持していない。バンドは、各音色のボリューム、パン、転調の設定を保持している。


ツール オブジェクトとインターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic クラスの概要」を参照すること。

[C++]

ツールはミュージック メッセージに割り込んで、ポートに渡す前にメッセージを処理するオブジェクトである。すべてのツールは (DirectMusic によって実装される出力ツールを除いて)、アプリケーションで定義される。

ツール

IDirectMusicTool インターフェイスは、1 つのツールを表す。このインターフェイスのメソッドは、ツールの機能を定義するためにアプリケーションまたは DLL によって実装される。

グラフ

複数のツールはグラフ内に収集され、IDirectMusicGraph インターフェイスによって表される。このインターフェイスは、セグメントおよびパフォーマンス オブジェクトの両方によって実装される。このインターフェイスは、あるツールからほかのツールへメッセージを転送し、ツールをグラフに追加し、個別のツールへのポインタを取り出し、グラフをシャットダウンするために使用される。


パフォーマンス オブジェクトとインターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic クラスの概要」を参照すること。

[C++]

ミュージック データを再生するには、次のオブジェクトとインターフェイスを使用する。このグループのインターフェイスには、全部で 75 以上のメソッドがあり、DirectMusic アプリケーションにおいて主要な役割を演じる。

パフォーマンス

DirectMusicPerformance オブジェクトは、音楽再生の総合的なマネージャである。IDirectMusicPerformance インターフェイスを通して、ポートの追加と削除、音色のダウンロード、グラフ (ツールの集合) の付加、複数のセグメントのイベント通知の管理、およびセグメントの演奏を行う。

セグメント

DirectMusicSegment オブジェクトはデータのチャンクを表す。ほとんど場合は音楽の部品で、1 つまたは複数のトラックに含まれる。通常、セグメントはファイルからロードするか、実行時に DirectMusicComposer オブジェクトを使って作成する。セグメントを演奏するには、アプリケーションは IDirectMusicSegment インターフェイス ポインタを IDirectMusicPerformance::PlaySegment メソッドに渡す。

IDirectMusicSegment インターフェイスのメソッドは、タイミング、ループ、イベント通知、トラック、ツール グラフ、およびセグメントのその他のさまざまなパラメータの管理に使われる。

演奏中のセグメントのインスタンスは、もう 1 つのインターフェイス IDirectMusicSegmentState によって表される。このインターフェイスのメソッドは、再生の状態に関する情報を返す。パフォーマンスはこのインターフェイスへのポインタを使って、セグメント インスタンスの停止または削除を行う。

トラック

特定の種類の時間ベース データのチャンクは DirectMusicTrack オブジェクトによって表されるが、より単純にはトラックと呼ばれる。IDirectMusicTrack インターフェイスのメソッドを使って、データの設定と取り出し、データの演奏、および通知の設定が行える。通常、トラックの処理はそれらのトラックを保持する DirectMusicSegment オブジェクトのメソッドによって行われるので、ほとんどのアプリケーションではこのインターフェイスを直接使うことはない。

注 : DirectMusicTrack は、音色トラックと同じものではない。DirectMusicTrack は、MIDI メッセージ、コード進行、バンド変更など、あらゆる種類の時間ベースのデータを表す。


コンポーザ オブジェクトとインターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic クラスの概要」を参照すること。

[C++]

このカテゴリのオブジェクトとインターフェイスは、音楽のリアルタイム アレンジに使用される。コンポーザ自身を除いて、DirectMusic Producer などのアプリケーションで作成されたファイルからロードされたデータを表す。各オブジェクトの役割については、「音楽のアレンジ」を参照すること。

コンポーザ

IDirectMusicComposer インターフェイスのメソッドにより、人間の作曲者が作成したコード マップ、スタイル、およびテンプレートを使って、アプリケーションでミュージック セグメントおよび移行部をアレンジすることができる。

スタイル

スタイルには、音符のパターンを含む、音楽の一部分に関する基本的な情報が含まれる。スタイルは、オーサリングされたセグメントを構成している場合がある。この場合、ほとんどの処理は背景で実行される。また、まったく新しいセグメントを実行時にアレンジすることもできる。スタイルは、IDirectMusicStyle インターフェイスによって表される。

コード マップ

DirectMusicChordMap オブジェクトは、音楽の一部分のコード進行を決定するために DirectMusicComposer で使用される、コードとパスの集合を表す。

IDirectMusicChordMap インターフェイスは、ファイルからロードされた DirectMusicChordMap オブジェクト用に取得する。このインターフェイスへのポインタを IDirectMusicComposer のメソッドに渡すことにより、オーサリングされたコード マップを使って、セグメントまたは移行部を実行時に作成することができる。新しいコード マップを適用することにより、既存のセグメントのコード パターンを変更することもできる。

テンプレート

テンプレートは、特別なタイプの DirectMusicSegment オブジェクトである。直接演奏されることはないが、DirectMusicComposer がスタイルとコード マップに基づいて、セグメントをリアルタイムに構築するために使用される。


シンセサイザ オブジェクトとインターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic クラスの概要」を参照すること。

[C++]

シンセサイザは、MIDI メッセージをウェーブフォーム データに変換し、これをウェーブ出力デバイスのストリームに入れる。DirectMusic には独自のソフトウェア シンセサイザが付属するが、カスタム シンセサイザを実装することも可能である。出力を別のデバイスに転送することも可能である。これらの情報は、DirectX DDK (Driver Development Kit) に含まれている。

シンセサイザ

アプリケーションによって実装されたシンセサイザは、IDirectMusicSynth インターフェイスによって表される。ほとんどのアプリケーションは、このインターフェイスを使用しない。また、このインターフェイスについては DirectX SDK ではドキュメント化されていない。

シンセ シンク

DirectSound や Microsoft® Win32® のウェーブフォーム オーディオなど、シンセサイザがデータの送信に使うウェーブ ストリームのことで、IDirectMusicSynthSink インターフェイスによって表される。ほとんどのアプリケーションは、このインターフェイスを使用しない。また、このインターフェイスについては DirectX SDK ではドキュメント化されていない。


DirectMusic クラスの概要

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic オブジェクトとインターフェイスの概要」を参照すること。

[Visual Basic]

DirectMusic クラスは、広範な機能に従って次のカテゴリにグループ化できる。

  • ローダー クラス
  • パフォーマンス クラス
  • コンポーザ クラス
  • 音色クラス


ローダー クラス

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic オブジェクトとインターフェイスの概要」を参照すること。

[Visual Basic]

音楽を演奏するための最初の手順は、ファイルまたはリソースからデータをロードすることである。DirectMusicLoader クラスのオブジェクトは、バンド、コレクション、セグメント、およびスタイルのロードに使用される。すべてのファイル入出力とデータの解析は、DirectMusic によって処理される。

DirectMusicLoader メソッド (SetSearchDirectory 以外) はそれぞれ、データを表すオブジェクトを返す。ロードされているプライマリ オブジェクトによって参照されているほかのオブジェクトも、利用可能となる。たとえば、DirectMusicLoader.LoadStyle を使ってロードしたスタイルにバンドへの参照が含まれている場合、スタイル オブジェクトのメソッドを呼び出すことで、バンド オブジェクトをいつでも取り出すことができる。


パフォーマンス クラス

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic オブジェクトとインターフェイスの概要」を参照すること。

[Visual Basic]

DirectMusicPerformance クラスは、DirectMusic アプリケーションの中心である。ほとんどのアプリケーションは、このクラスのオブジェクトを 1 つ持ち、タイミングとポートの管理、マスタ テンポなどのグローバル ミュージック パラメータの変更、およびミュージック セグメントの演奏を行う。

MIDI ファイルや、DirectMusic Producer などのアプリケーションでオーサリングされたセグメントなど、音楽の部品はそれぞれ DirectMusicSegment クラスのオブジェクトによって表される。このクラスのメソッドを使うと、セグメントのミュージック パラメータを設定または取り出したり、関連付けられている DLS 音色を管理することができる。DirectMusicSegment の特殊な形態であるテンプレートは、演奏可能なセグメントのリアルタイム アレンジに使用される。

DirectMusicSegment オブジェクトを DirectMusicPerformance.PlaySegment に渡すときに、メソッドは、セグメントの演奏中のインスタンスを表す DirectMusicSegmentState クラスのオブジェクトを返す。このオブジェクトのメソッドを使うと、演奏が開始されたタイムなどの情報を取得できる。DirectMusicSegmentState は、セグメントが現在演奏中であるかどうかを判定したり、再生を停止するために、DirectMusicPerformance にも渡される。


コンポーザ クラス

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic オブジェクトとインターフェイスの概要」を参照すること。

[Visual Basic]

DirectMusic アプリケーションで演奏される音楽の多くは、MIDI ファイルとして、またはセグメントとして完全にオーサリングされている。ただし、DirectMusic では、スタイルおよびテンプレートなどの要素に基づいて、実行時にアプリケーションで音楽をアレンジすることもできる。

DirectMusicComposer クラスには、テンプレート、コード マップやテンプレートに基づいた演奏可能なセグメント、またはほかのセグメントに基づいた移行部を表す、DirectMusicSegment オブジェクトを作成するメソッドが含まれる。コンポーザ オブジェクトを使うと、既存のセグメントのコード マップを変更することもできる。

DirectMusicChordMap クラスは、ファイルまたはリソースからロードされたコード マップを表す。これにより、コード進行を作成するために必要な情報が DirectMusicComposer に供給される。

DirectMusicStyle クラスのオブジェクトは、別のエンティティとして、またはオーサリングされたセグメントの一部として、ファイルまたはリソースからのデータにも基づいている。このオブジェクトは、アレンジに使用されるミュージック パターンのセットを表し、DirectMusicComposer のメソッドに渡される。固有のメソッドは、モチーフやバンドなど、スタイルで決定されているほかの要素を取り出すために使用される。


音色クラス

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic オブジェクトとインターフェイスの概要」を参照すること。

[Visual Basic]

DirectMusicBand クラスは、音楽の部品に割り当てられた音色のセット (ボリューム、パン、および転調を含む) を表す。スタイルで決定されているバンド チェンジは、スタイルに基づくセグメントが演奏されているときに自動的に行われる。ただし、スタイルから、または別のファイルやリソースから DirectMusicBand オブジェクトを取得して、DirectMusicSegment を作成することもできる。このセグメントを演奏して、プログラム チェンジすることができる。

DirectMusicCollection クラスは、DLS コレクションを表す。セグメントが演奏されるとき、またはバンドがダウンロードされるときに、音色データがポートにダウンロードされるので、ほとんどのアプリケーションでは直接コレクションを操作する必要はない。

コレクションとバンドの主な違いは次のとおりである。

  • コレクションは、任意のセグメントの再生に利用できる音色のグループである。バンドは、特定のセグメントを実際に演奏する音色のグループである。
  • コレクション中の音色には、ティンバーを定義している DLS データが含まれている。バンドの音色には、これらのデータが含まれていないが、1 つまたは複数のコレクションの音色へリンクされる。
  • コレクションの音色は、セグメントの特定のパフォーマンス チャンネル (P チャンネル) には関連付けられていない。バンドは、音色のパッチ番号をセグメント内の各 P チャンネルに割り当て、発音の優先順位をチャンネルに割り当てる。
  • コレクションは、音色を演奏する方法に関して何も情報を保持していない。バンドは、各音色のボリューム、パン、転調の設定を保持する。


DirectMusic のデータの流れの概要

一般的に、DirectMusic アプリケーションは、次に示すような 1 つまたは複数のソースからミュージック データを取得する。

  • MIDI ファイル
  • DirectMusic Producer などのアプリケーションでオーサリングされたセグメント ファイル
  • DirectMusic Producer などのアプリケーションでオーサリングされ、DirectMusicComposer オブジェクトによって完全にアレンジされたコンポーネント ファイル

注 : これらのデータ ソースは、リソースとしてアプリケーションに格納することができる。

これらのソースからのデータは、DirectMusicSegment オブジェクトにカプセル化される。各セグメント オブジェクトは、1 つのソースからのデータを表す。パフォーマンスではいつでも、1 つ以上のセグメント、つまり 1 つの "プライマリ セグメント" と 1 つまたは複数の "セカンダリ セグメント" を演奏することができる。ソース ファイルは混在させることができる。たとえば、MIDI ファイルに基づくセカンダリ セグメントを、オーサリングされたセグメント ファイルと一緒に演奏することができる。

1 つのセグメントには複数のトラックが含まれ、それぞれが音符やテンポの変更など、特定の種類のタイム データを含んでいる。

ほとんどのトラックは、パフォーマンスでセグメントが演奏されるときにメッセージを生成する。パフォーマンスは、アプリケーション定義ツールにメッセージを送り、ツールはメッセージを変更して渡したり、メッセージの削除や、新規メッセージの送信を行うことができる。ツールは、セグメント グラフとパフォーマンス グラフにグループ化される。セグメント グラフでは、自身のセグメントからのメッセージのみが処理される。パフォーマンス グラフでは、すべてのセグメントからのメッセージが受け付けられる。

[Visual Basic]

アプリケーション定義ツールは、DirectX for Visual Basic ではサポートされていない。

最終的に、メッセージは出力ツールに到達する。出力ツールで、データはポートに渡される前に MIDI フォーマットに変換される。チャンネル固有の MIDI メッセージは、ポートの適切なチャンネル グループに転送される。ポートはサウンド ウェーブを合成し、ウェーブ出力デバイス (通常は DirectSound バッファ) のストリームに入れる。

次の図は、ファイルから取り出されたミュージック データが、ウェーブ出力デバイスに送られるようすを示している。単純にするために、1 つのセグメントだけを示している。このセグメントは、3 つのソースのいずれかのみからデータを取り出している。使用できるソースは、MIDI ファイル、オーサリングされたセグメント ファイル、または DirectMusicComposer オブジェクトによって結合されたコンポーネント ファイルのいずれかである。

パフォーマンスにおけるメッセージの流れを詳細に確認するには、「DirectMusic メッセージ」を参照すること。

図に示されている処理を実装する方法については、「DirectMusic の要点」の「DirectMusic ローダー」および「音楽の演奏」を参照すること。

セグメントおよびコンポーネント ファイルの詳細については、「音楽のアレンジ」を参照すること。

[C++,Visual Basic]


DirectMusic メッセージ

ミュージック データは、メッセージの形で DirectMusic パフォーマンス エンジンに渡される。ほとんどの DirectMusic アプリケーションでは、このメッセージを直接処理する必要はないが、その構造についての基本的な知識があると、DirectMusic の動作を理解するのに役立つ。

DirectMusic では、2 種類のメッセージが処理される。

  • パフォーマンス メッセージ。シーケンス化されたデータはすべて、この形式でパフォーマンス エンジンに渡される。これらのメッセージには、データのタイミングおよびルーティングに関する詳細な情報が含まれている。
  • スタンダード MIDI メッセージ。これらのメッセージは、MIDI ファイルまたはデバイスから読み込まれ、ほかのデバイスに直接渡される (スルーされる) か、パフォーマンスに渡される前にパフォーマンス メッセージ形式に変換される。シンセサイザへの最終出力も、MIDI メッセージの形式である。

次のトピックでは、メッセージとそのルーティング方法について詳しく説明する。

  • チャンネル
  • メッセージの作成と配信
  • パフォーマンス メッセージのタイプ
  • MIDI メッセージ


チャンネル

チャンネルは、パフォーマンス内の 1 つのパートに固有のメッセージの送信先である。たとえばチャンネルは、音色にサウンドを発生させるノートオン メッセージを受け取ったり、パートに別の音色を割り当てるプログラム チェンジ メッセージを受け取る (「MIDI チャンネル メッセージ」を参照すること)。

MIDI 1.0 規格では、16 個の MIDI チャンネルがあり、一度に 16 を超える音色は演奏できないことを意味している。DirectMusic では、この規格に対応すると同時に、アプリケーションがより多くのチャンネルを同時に利用できるように、チャンネル グループが作成される。最大 65,536 個のチャンネル グループが同時に存在し、それぞれに 16 個のチャンネルが含まれるので、チャンネル総数は 100 万以上に上る。特定のポートに、そのポートがサポートする範囲で任意の数のチャンネル グループを割り当てることができる。従来の MIDI ハードウェア ポートには、1 つのチャンネル グループしか割り当てることができない。

システム エクスクルーシブ メッセージは、1 つのチャンネル グループ内の 16 チャンネルのすべてに対して送信できるが、ほかのチャンネル グループ宛てには送信できない。

DirectMusic パフォーマンス内のすべての音色は、固有のパフォーマンス チャンネル、つまり P チャンネルを持つ。P チャンネルは、特定のポートに対する特定のグループ内の特定の MIDI チャンネルを表す。パフォーマンスがあるバンドを選択すると、そのバンド内の各音色は 1 つの P チャンネルにマップされる。

[C++]

同時に演奏できる音符の数は、ポートで利用できる発音数によって制限される (この数は、DMUS_PORTCAPS 構造体の dwMaxVoices メンバで指定できる)。

[Visual Basic]

同時に演奏できる音符の数は、ポートで利用できる発音数によって制限される (この数は、DMUS_PORTCAPS 型の lMaxVoices メンバで指定できる)。

発音は、チャンネルで演奏される 1 つの音符を合成する、リソースのセットである。利用できる発音の数より多くの音符が演奏される場合は、シンセサイザによって、1 つまたは複数の音符が抑制されなければならない。どの音符を演奏するかは、現在音符を演奏している発音の優先順位によって決定され、これはチャンネルの優先順位に基づく。デフォルトでは、チャンネルはインデックス値に基づいて順位付けされる。ただし、チャンネル 10 は MIDI パーカッション チャンネルで、優先順位は最も高くなる。

[C++]

アプリケーションおよびシンセサイザでは、独自にチャンネルの優先順位を設定できる。詳細については、IDirectMusicPort::GetChannelPriority の「注意」を参照すること。DMUS_CHANNEL_PRIORITY_PMSG も参照すること。


メッセージの作成と配信

セグメントが演奏されているときに、ほとんどのトラックは、再生中に発生するイベントに関する情報を含むメッセージを生成する (詳細については、「トラック」を参照すること)。

数種類のメッセージを送信するトラックもある。たとえば、スタイル トラックは音符メッセージと拍子記号メッセージを送信する。これらの場合、アプリケーションはトラックの特定の種類のメッセージを無効にすることができる。詳細については、「トラック パラメータの設定と取り出し」を参照すること。

アプリケーションは、メッセージを直接キューに入れることもできる。たとえば、テンポを変更する場合に、この操作を行うことができる。

[C++]

サンプル コードについては、IDirectMusicPerformance::SendPMsg を参照すること。

[Visual Basic]

サンプル コードについては、「DLSEffects サンプル」を参照すること。

パフォーマンス エンジンは、各メッセージを実時間 (基準タイム) でいつ処理するかを決定する。チャンネル メッセージの場合、パフォーマンスはメッセージを転送する P チャンネルも決定する。この情報は、メッセージ タイプ、ソース トラック、メッセージを受信する最初のグラフとツールへのポインタなどを保持するほかのデータと共に、メッセージに保存される。

テンポや拍子記号の変更などの特定のメッセージは、パフォーマンスによって直ちに処理され、解放される。音符やパッチの変更など、その他のメッセージはキューに入れられ、タイム スタンプの順に処理される。

注 : 同じタイム スタンプのメッセージが特定の順序で処理されるという保証はない。

テンポ メッセージは、ミュージック タイムを基準タイムに変換する方法をパフォーマンスに伝える。拍子記号はセグメントに内蔵されていて変更できないため、拍子記号メッセージは情報を伝えるに過ぎない。

[C++]

メッセージは最初に、セグメントのグラフ内のツールに送信され、次いでパフォーマンスのグラフ内のツールに送信される (アプリケーションは、これらのグラフのいずれかまたは両方を作成し、ツールを定義する。デフォルトのグラフはない)。

グラフ内の最初のツールはメッセージを処理し、そのメッセージをほかのツールに渡したい場合は、次のツールへのポインタと共にそのメッセージをグラフにスタンプ処理させる。詳細については、「チュートリアル 2 : ツールの使い方 を参照すること。

この時点で、グラフはメッセージに配信タイプのフラグを割り当てる。このフラグに基づいて、メッセージを次のツールに配信する時期が決まる。このフラグは、ツールで予期されている、次のような配信タイプに基づいている。

  • メッセージに DMUS_PMSGF_TOOL_IMMEDIATE フラグが割り当てられている場合、即座に次のツールに配信される。
  • DMUS_PMSGF_TOOL_QUEUE フラグが割り当てられているメッセージは、遅延時間を考慮に入れた上で、演奏されると想定される時期の直前に配信される (「遅延時間とバンパー時間」を参照すること)。
  • メッセージに DMUS_PMSGF_TOOL_ATTIME フラグが割り当てられている場合、処理されるのとまったく同じ時期に配信される。通知の処理には、ほとんどまたはまったく遅延時間が発生しないので、通知メッセージにはこのフラグが割り当てられる。

グラフがメッセージのスタンプ処理とフラグ割り当てを行った後で、現在のツールは配信タイプを変更することができる。

最終的に、メッセージは破棄されない限り、DirectMusic の出力ツールに到達する。このツールは受け取ったすべてのメッセージをスタンダード MIDI メッセージに変換し、それらをポート バッファ経由でシンセサイザに配信する。


パフォーマンス メッセージのタイプ

[C++]

メッセージは、DMUS_PMSG から派生したさまざまなタイプに保存される。C は継承をサポートしていないので、DMUS_PMSG のメンバは DMUS_PMSG_PART マクロ内の各メッセージタイプの宣言に含まれている。これらのメンバは、メッセージ タイプ、タイム スタンプ、メッセージ送信先のパフォーマンス チャンネル、メッセージ処理に使われる次のグラフとツールを含む、すべてのメッセージにとって共通のデータを保持している。ほかのメンバは、メッセージ タイプ固有のデータを保持している。

メッセージ構造体は次のように定義されている。

DMUS_PMSG | 追加パラメータのない単純なメッセージ。
DMUS_CHANNEL_PRIORITY_PMSG | チャンネル優先順位の変更。「チャンネル」を参照すること。
DMUS_CURVE_PMSG | 曲線。
DMUS_MIDI_PMSG | 固有のメッセージ タイプを持たない MIDI メッセージ。たとえば、コントロール チェンジ。
DMUS_NOTE_PMSG | 音楽の音符 (継続時間を含む。したがって、MIDI ノートオンおよびノートオフ メッセージは、このスタイルに組み合わされる)。
DMUS_NOTIFICATION_PMSG | 通知。「通知とイベントの処理」を参照すること。
DMUS_PATCH_PMSG | MIDI パッチの変更。
DMUS_SYSEX_PMSG | MIDI システム エクスクルーシブ メッセージ。
DMUS_TEMPO_PMSG | テンポの変更。
DMUS_TIMESIG_PMSG | 拍子記号の変更。
DMUS_TRANSPOSE_PMSG | 転調。

[Visual Basic]

DirectX for Visual Basic では、アプリケーションがメッセージ構造体に直接アクセスすることはできない。その代わりに、特定の種類のメッセージを送信するために、次のメソッドが用意されている。

DirectMusicPerformance.SendCurvePMSG | MIDI 曲線
DirectMusicPerformance.SendNotePMSG | 音楽の音符
DirectMusicPerformance.SendPatchPMSG | パッチの変更
DirectMusicPerformance.SendMIDIPMSG | その他の MIDI イベント
DirectMusicPerformance.SendTempoPMSG | テンポの変更
DirectMusicPerformance.SendTimeSigPMSG | 拍子記号の変更
DirectMusicPerformance.SendTransposePMSG | 転調の変更


MIDI メッセージ

ここでは、スタンダード MIDI メッセージの概要と、一般的には MIDI ファイルからストリームに渡されるこれらのメッセージを、DirectMusic で処理する方法について説明する。ほとんどのアプリケーションは、MIDI メッセージを直接処理しない。再生の詳細はすべて、ローダーとパフォーマンスで管理される。

MIDI 入力は、パフォーマンスによってツールにルーティングされる前に、パフォーマンス メッセージ形式に変換される。出力ツールは、データをシンセサイザに渡す前に、スタンダード MIDI メッセージ形式に戻す。

注 : MIDI メッセージが、ファイルに記述されている順序で処理されるという保証はない。DirectMusic メッセージはタイム スタンプの順に配信される。タイム スタンプが同一の MIDI メッセージが 2 つある場合は、予想と異なる順序で配信される場合がある。MIDI コンテンツをオーサリングするときに、イベントを発生させる順序が決まっている場合は、これらのイベントに同じタイム スタンプを与えないように注意する。たとえば、プログラム チェンジに依存する音符がある場合は、これらの音符とプログラム チェンジを同時に配置しない。

MIDI メッセージは、1 バイトのステータス バイトと、その後に続く 1 バイトか 2 バイトのデータ バイトによって構成される。システム エクスクルーシブ MIDI メッセージは可変長である。ステータス バイトはメッセージのタイプを示し、一部の状況では、そのメッセージを受け取るチャンネルを示す。ファイル中に同じ種類のイベントが続けて現れる場合は、ステータス バイトを省略できる。これは、動作ステータスと呼ばれる。上位ビットが常に消去されているので、データ バイトを認識できる。ステータス バイトの上位ビットは、常に設定されている。

MIDI イベントがファイルからストリームに入れられるタイミングは、各メッセージの前にある数字で制御される。この値は、このイベントと最後のイベントの間隔を、ティック数で表している。ティックの実際の継続時間は、ファイル ヘッダーの時間の形式によって決定される。

MIDI メッセージは、次の 2 つの主要なカテゴリに分類できる。

  • MIDI チャンネル メッセージ
  • MIDI システム メッセージ


MIDI チャンネル メッセージ

チャンネル メッセージは、音楽の 1 つのパートに対応する特定のチャンネルをアドレス指定される。

チャンネル メッセージは、モード メッセージか発音メッセージのどちらかである。

モード メッセージは、チャンネルがそれ以降の発音メッセージを取り扱う方法を決定する。たとえば、モード メッセージは、何か通知があるまではすべてのノートオン メッセージを無視して、無音状態を保つようチャンネルに指示することがある。

ほとんどのチャンネル メッセージは発音メッセージである。これらはチャンネルに音符の演奏の開始または停止、何らかの方法での音符の変更を指示し、チャンネルにほかの MIDI パッチ番号を割り当てることにより音色を変更する。

発音メッセージは、次のいずれかのタイプを取る。

発音メッセージ | 目的
ノートオン | 音符を演奏する。
ノートオフ | 音符の演奏を停止する。
コントロール チェンジ | ペダル、レバー、その他のデバイスからのデータを使って楽音を変更する。ボリュームやバンク セレクトなど、さまざまなコントロールにも使われる。
プログラム (パッチ) チェンジ | パッチ番号を割り当てることにより、チャンネルの音色を選択する。
アフタータッチ | キーのアフタータッチに従って、個別の音符またはチャンネルのすべての音符を変更する。
ピッチ ベンド チェンジ | チャンネルで演奏されるすべての音符のピッチを変更する。

これらの説明は、スタンダード MIDI メッセージに適用され、パフォーマンス メッセージ形式に変換された MIDI データには適用されない。たとえば、音符の演奏を開始および停止するための MIDI メッセージのペアは、DirectMusic によって、音符の継続時間を指定する 1 つのメッセージに結合される。DirectMusic メッセージには、メッセージのタイミングやルーティングに関する多くの追加情報も含まていれる。

MIDI 音符

ノートオン メッセージのデータ バイトは、ピッチとベロシティを表す。ほとんどの場合、ピッチの値 (キーナンバー) 0 は 2 オクターブ下の C 音 (MIDI では C0 と表記) であり、12 は 1 オクターブ下の C (MIDI の C1)、60 はピアノでいう中央の C (MIDI の C5) を意味する。ドラム キットの場合、データ バイトは特定のドラム サウンドを意味する。たとえば、GM (General MIDI) のパーカッション キー マップでは、値 60 はハイ ボンゴのサウンドを意味する。チャンネル 10 はドラム キットに予約されているので、シンセサイザはこのチャンネルでのノートオン メッセージをほかのチャンネルとは異なった方法で扱うことを知っている。

DirectMusic が MIDI 音符を変換する方法については、「ミュージック値と MIDI 音符」を参照すること。

プログラム チェンジ

プログラム チェンジとパッチ番号は、MIDI 再生と DirectMusic において非常に重要である。プログラム チェンジは特定の音色 (プログラムまたはティンバーとも呼ぶ) をチャンネルに割り当てるので、チャンネルに送信された音符は適切なサウンドで演奏される。音色はパッチ番号によって識別される。GM 音色セットをロードする場合、パッチ番号 1 を指定するプログラム チェンジでは、チャンネルは必ずアコースティック グランド ピアノの音符で演奏される (もちろん、スピーカで生成される実際のサウンドは、音色の合成方法に依存する)。

バンク セレクト

プログラム チェンジの際に 1 バイトのデータ バイトを使ってパッチ番号を選択しているが、MIDI メッセージの各データ バイトで有効なのは 7 ビットだけなので、プログラム チェンジでは最大 128 の音色を選択することができる。より多くの選択肢を提供するために、MIDI 規格では最大 16,384 の音色バンクの使用が認められ、各バンクに最大 128 の音色を含めることができる。

ほかのバンクから音色を選択するには、MIDI シーケンサは最初にバンク セレクトと呼ばれるコントロール チェンジ メッセージを送信しなければならない。このメッセージのデータ バイトのうち 2 バイトを、最上位バイト (MSB) および最下位バイト (LSB) と呼び、これらを組み合わせてバンクを識別する。バンクを選択した後、それ以降のプログラム チェンジではそのバンクから音色が選択される。

DirectMusic パッチ番号

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。DirectX for Visual Basic では、DirectMusicPerformance.SendPatchPMSG メソッドを使う方法を除いて、アプリケーションでパッチ番号を変更することは認められていない。

[C++]

MIDI の定める 7 ビット パッチ番号とは異なり、DirectMusic の音色パッチ番号は 32 ビット値であり、その中に MIDI パッチ番号、バンク セレクトの MSB と LSB、およびドラム キット用の 1 ビット フラグが含まれている。IDirectMusicCollection::EnumInstrument、IDirectMusicCollection::GetInstrument、およびIDirectMusicInstrument::GetPatch の各メソッドはこの拡張パッチ番号を返す。IDirectMusicInstrument::SetPatch メソッドを使うと、音色を変更できる。

DirectMusic パッチの値は、次のように構成されている。

ビット | 目的
0-7 | MIDI パッチ番号 (ビット 7 は常に 0)
8-15 | LSB バンク セレクト (ビット 15 は常に 0)
16-23 | MSB バンク セレクト (ビット 23 は常に 0)
24-30 | 未使用
31 | ドラム キット用のフラグ


MIDI システム メッセージ

システム メッセージは、どのチャンネルにとっても排他的ではない。これらは次の表のように 3 種類に分類される。

メッセージ タイプ | 目的
システム共通 | さまざまなコマンドとデータ
システム エクスクルーシブ | 機器固有のコマンドとデータ
システム リアルタイム | クロックベースの MIDI 機器の同期化

ほかの MIDI メッセージとは異なり、システム エクスクルーシブ メッセージは任意の長さのデータ バイトを保持できる。データを送信した後で、シーケンサは EOX と呼ばれるシステム共通メッセージを送信し、システム エクスクルーシブ メッセージの終わりを知らせる。

[C++]

DirectMusic では、DMUS_SYSEX_PMSG 構造体が、データ長とデータ バイトの配列へのポインタを保持する。

[Visual Basic]

DirectX for Visual Basic では、アプリケーションがシステム エクスクルーシブ メッセージに直接アクセスすることはできない。


ダウンローダブル サウンド

これまで、ほとんどのコンピュータ音楽は、次の 2 つの方法のいずれかで生成されていた。それぞれに利点はあるが、欠点もある。

  • 通常は .WAV ファイル、またはレッドブック オーディオ規格に従った標準的な CD トラックに記録されているデジタル サンプルからウェーブフォーム (波形) を再現する方法。デジタル サンプルではどのようなサウンドも再現可能で、どのサウンド カードを使った場合でも得られる出力は非常によく似ている。ただし、ストリーミング用に多くの記憶領域とリソースが必要となる。
  • 一般的には MIDI ファイルからのメッセージに応答して、音色のサウンドを通常はハードウェアで合成する方法。MIDI ファイルはコンパクトで、ストリーミング リソースもわずかしか必要としないが、出力は General MIDI セットのシンセサイザで利用できる音色の数に限定され、システムによっては非常に異なった音になる場合がある。

デジタル サンプリングの利点と、MIDI のコンパクトさおよび柔軟性を組み合わせる 1 つの方法が、ウェーブテーブル合成である。これは、デジタル サンプルから音色のサウンドを合成する方法である。実際の音色をレコーディングすることによってサンプルを取得し、ハードウェアに保存する。さまざまなピッチとボリュームで任意の長さのサウンドを作成するために、サンプルのループと調整が行われる。

ウェーブテーブル合成はアルゴリズムに基づく FM 合成より現実的なティンバーを作成するが、依然として固定セットの音色に限定される。さらに特定の音色のサウンドはメーカーの実装によって異なり、ハードウェアの組み合わせが異なると非常に異なったサウンドになる場合がある。

これらの制限を克服するために、MIDI Manufactures Association によってダウンローダブル サウンド (downloadable sounds、DLS) 規格が発表された。DLS は、システムにハードワイアードで実装されたサンプルの代わりに、実行時に提供されるサンプルに基づいてウェーブテーブル合成を行うことができる方法である。音色を記述するデータはシンセサイザにダウンロードされ、その後はほかの MIDI 音色と同様にその音色を演奏できる。DLS はアプリケーションの一部として配信できるため、開発者はサウンドトラックをすべてのシステムで同じように演奏させることができる。また、音色の選択が制限されることもない。

DLS 音色は 1 つまたは複数のサンプルから作成され、通常はシングル ピッチを表すが、シンセサイザで変更を加えることによりその他のピッチを作成できる。広範囲のピッチで音色のサウンドを現実的にするには、複数のサンプルを使う。DLS 音色をダウンロードする際に、リージョンと呼ばれる特定のピッチ範囲が各サンプルに割り当てられる。通常、16 個より多くのリージョンを使うことはない。

加えて、サンプルにアーティキュレーションを与えることもできる。これはアタック (音符がフル ボリュームに達する速度)、ディケイ (フルボリュームから減衰する速度)、およびサウンドを実際の音色により近づけるためのその他の特徴を定義する。

ダウンローダブル サウンドは音色コレクションに格納され、ここからシンセサイザにダウンロードされる。

ほかの MIDI 音色の場合と同様に、DLS 音色にはパッチ番号が割り当てられ、MIDI メッセージに応答する。ただし、DLS 音色 (機器) は General MIDI セットに従う必要はない。実際、音色を表す必要はまったくない。演説の一部や作成済みの完全な小節など、どんなサウンドでも DLS 音色に変換することができる。

DLS コレクションと DLS 音色の作成方法の詳細については、DirectMusic Producer のドキュメントを参照すること。アプリケーションに DLS を組み込む方法の詳細については、「DLS の使い方」を参照すること。


Microsoft Software Synthesizer

Microsoft Software Synthesizer は DirectMusic と共に提供され、ハードウェア DLS を利用できない、または DLS がオペレーティング システムでサポートされていない場合に、デフォルト ポートになる。このシンセサイザは DLS サンプルに基づく音色のティンバーを使って、MIDI メッセージのストリームに基づくウェーブフォームを作成する。デフォルトでは、サンプルは Roland GS コレクションから取られるが、このコレクションも DirectMusic の一部としてインストールされる。シンセサイザは、出力を DirectSound ミキサに送信する。

注 : Roland GM/GS Sound Set を修正することはできない。「法的情報」の「著作権に関する注意」を参照すること。

Microsoft Software Synthesizer には、リバーブ機能が含まれており、デフォルトで有効になっている。Waves TrueVerb リバーブ テクノロジが Microsoft にライセンスされており、SimpleVerb として実装されている。


DirectMusic の要点

ここでは、DirectMusic をアプリケーションに実装する方法についての、実際的な情報を説明する。一般的な概要については、「DirectMusic アーキテクチャ」を参照すること。

次の項目について説明する。

  • DirectMusic プロジェクトの作成
  • DirectMusic プロジェクトのデバッグ
  • DirectMusic と DirectSound の統合
  • ポートの使い方
  • DirectMusic ローダー
  • DirectMusic のファイル形式
  • DLS の使い方
  • 音楽の演奏
  • ミュージック パラメータ
  • 音楽のキャプチャ
  • DirectMusic ツール
  • 音楽のアレンジ


DirectMusic プロジェクトの作成

[Visual Basic]

ここでは、C++ によるアプリケーション開発に関連する内容だけを説明する。

[C++]

ほかの DirectX コンポーネントと異なり、DirectMusic API は完全な COM ベースであり、COM オブジェクトを作成するヘルパー関数などのライブラリ関数を含まない。したがって、ビルド中にリンクする Dmusic.lib ファイルは存在しない。

ほとんどのプロジェクトでは、Dmusicc.h および Dmusici.h ヘッダー ファイルをインクルードしなければならない。これらのファイルには、それぞれコア レイヤおよびパフォーマンス レイヤの宣言が含まれている。また、戻り値を含む Dmerror.h ファイルもインクルードしなければならない。Dmusicf.h にはファイル形式が含まれ、ファイルを直接操作したり、DirectMusic に組み込まれたローダーにまったく依存しない、ミュージック オーサリング ツールなどのアプリケーションでのみ必要となる。

Dmksctrl.h には、プロパティの設定で使用される IKsControl インターフェイスの宣言が含まれている。Ksproxy.h および Ks.h ファイルがある場合、このファイルは必要ない。

DirectMusic は、Windows 32 ビット オペレーティング システムのマルチスレッド機能を使用する。マルチスレッドを利用することによって、アプリケーションが別のタスクを実行している間に、DirectMusic はバックグラウンドで音楽の生成、処理、および合成を行うことができる。プロジェクトをマルチスレッドを使って開発するように注意すること。少なくとも、マルチスレッド ライブラリとリンクすること。

また、アプリケーションが DirectMusic で使用される GUID にアクセスできるように注意する。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。


DirectMusic プロジェクトのデバッグ

[Visual Basic]

ここでは、C++ によるアプリケーション開発に関連する内容だけを説明する。

[C++]

DirectX ソフトウェア開発キットのデバッグ バージョンでインストールされる DirectMusic DLL (ダイナミック リンク ライブラリ) は、アプリケーションの実行時に、情報をデバッグ出力ウィンドウに生成する。デフォルトでは、利用できるすべての情報が表示される。

Win.ini の値を変更すると、デバッグ出力ウィンドウに表示される情報を制御することができる。DirectMusic DLL それぞれの出力は、次の例に示すように、個別に設定することができる。

[Debug]
DMBAND=1
DMCOMPOS=1
DMIME=1
DMLOADER=0
DMUSIC=1
DMSTYLE=3
DMSYNTH=5

それぞれの値は 0 ～ 5 の範囲で設定できる。表示されるデバッグ情報の量は、0 で最も少なく、5 で最も多くなる。Win.ini にエントリがない場合、デバッグ出力のレベルは 0 になる。特定のコンポーネントにほかのコンポーネントよりも高い値を設定し、そのコンポーネントの問題に注目することができる。コントロール パネルの DirectX プロパティ シートを使って、デバッグ レベルを変更することもできる。ただし、この方法ではすべての DirectMusic コンポーネントに同じ値が設定される。

「DirectX アプリケーションのデバッグ」を参照すること。


DirectMusic と DirectSound の統合

通常、Microsoft Software Synthesizer やその他のシンセサイザは、出力ウェーブ データを DirectSound バッファのストリームに入れる。DirectMusic では、特別な操作を必要とせずに、DirectSound へのリンクの詳細をすべて処理することができる。DirectSound オブジェクトを作成したりリンクするときに、DirectMusic はプライマリ バッファ フォーマットを、すべての DirectMusic ポート間で最高のフォーマットに一致させる。

[C++]

サウンドトラックでミュージック ファイルのみを使い、ウェーブ ファイルやリソースの演奏に DirectSound を必要としないアプリケーションの場合、通常は DirectMusic のパフォーマンスが初期化されるときに DirectSound オブジェクトが作成される。次に例に示す。pPerf は IDirectMusicPerformance インターフェイスへのポインタである。

pPerf->Init(NULL, NULL, hwnd);

この例では、最初の NULL は内部で作成および管理される DirectMusic オブジェクトを指定し、2 番目の NULL は同様の DirectSound オブジェクトを指定する。hwnd は、DirectSound の制御ウィンドウのハンドルを表す。

注 : DirectMusic に DirectSound オブジェクトを作成するように要求するときに、最上位レベル アプリケーション ウィンドウのハンドルを提供するのは良い考えである。IDirectMusicPerformance::Init および IDirectSound::SetCooperativeLevel の「注意」を参照すること。

[Visual Basic]

サウンドトラックでミュージック ファイルのみを使い、ウェーブ ファイルやリソースの演奏に DirectSound を必要としないアプリケーションの場合、一般的には DirectMusic のパフォーマンスが初期化されるときに DirectSound オブジェクトが作成される。次に例を示す。Perf は、DirectMusicPerformance オブジェクトである。

Perf.Init(Nothing, hwnd);

この例では、Nothing は DirectSound オブジェクトが内部的に作成され管理されることを表す。hwnd は DirectSound の制御ウィンドウのハンドルである。

注 : DirectMusic に DirectSound オブジェクトを作成するように要求するときに、最上位レベル アプリケーション ウィンドウのハンドルを提供するのは良い考えである。DirectMusicPerformance.Init およびDirectSound.SetCooperativeLevel の「注意」を参照すること。

詳細については、次のトピックを参照すること。

  • DirectSound オブジェクトの設定
  • DirectSound バッファ オブジェクトの設定


DirectSound オブジェクトの設定

[C++]

DirectMusic に DirectSound オブジェクトを作成および管理させても、DirectSound を使用しないアプリケーションには関係ない。ただし、アプリケーションが DirectSound を使って、DirectMusic シンセサイザ以外のソースからウェーブ データを演奏している場合は、DirectMusic でも同じ IDirectSound インターフェイスを使用しなければならない。まず DirectSound オブジェクトを作成し、続いて DirectMusic にインターフェイス ポインタを渡す。この処理は、次の例に示すように IDirectMusicPerformance::Init の呼び出しで実行される。pPerf は IDirectMusicPerformance で、pDS は IDirectSound へのポインタである。

pPerf->Init(NULL, pDS, NULL);

注 : IDirectSound ポインタを IDirectMusicPerformance::Init に渡すときに、3 番目のパラメータのウィンドウ ハンドルは無視される。アプリケーションは IDirectSound::SetCooperativeLevel を呼び出して、制御ウィンドウの設定を行う必要がある。

DirectMusic で使用される DirectSound オブジェクトに、DSSCL_PRIORITY 協調レベルを設定する。DSSCL_NORMAL 協調レベルを設定した場合、DirectMusic はプライマリ バッファ フォーマットをアップグレードできない。

パフォーマンスに頼らずに、CoCreateInstance を使って自分で DirectMusic オブジェクトを作成する場合は、明示的に既存の IDirectSound インターフェイスにリンクしなければならない。この処理は、IDirectMusic::SetDirectSound メソッドを使って実行される。

IDirectMusicPort::SetDirectSound メソッドを使って、ポートに別の DirectSound オブジェクトを割り当てることもできる。異なるポートが異なるオーディオ デバイス上にあり、それぞれが固有の IDirectSound インターフェイスで表されている場合に、この操作を行う。ポートの DirectSound オブジェクトは、ポートがアクティブになると変更することができない。

DirectSound を必要とするポートをアクティブにする場合は、次のリストから、まず利用可能な IDirectSound インターフェイスを取得する。

  1. IDirectMusicPort::SetDirectSound に渡される IDirectSound インターフェイス
  2. IDirectMusic::SetDirectSound に渡される IDirectSound インターフェイス
  3. IDirectMusic::SetDirectSound に NULL が渡された場合は、DirectMusic によって作成された IDirectSound インターフェイス

DirectSound がエミュレーション モードである場合、オーディオ デバイスが排他的に使用される。アプリケーションは、フォーカスを失ったときに DirectSound を解放して、ほかのアプリケーションがデバイスを使用できるようにするべきである。一般的には、WM_ACTIVATE メッセージへの応答でこの処理を行う。

DirectMusic が DirectSound オブジェクトを作成している場合は、すべてのポートが非アクティブになったときに、オブジェクトが自動的に解放される (さらに、DirectMusic を使用する最初のポートが再びアクティブになったときに、オブジェクトが作成される)。ただし、自分で DirectSound オブジェクトを作成した場合は、自分で解放しなければならない。この処理を実行するには、IDirectMusic::SetDirectSound または IDirectMusicPort::SetDirectSound メソッドに、pDirectSound パラメータとして NULL を渡す。

[Visual Basic]

DirectMusic に DirectSound オブジェクトを作成および管理させても、DirectSound を使用しないアプリケーションには関係ない。ただし、アプリケーションが DirectSound を使って、DirectMusic シンセサイザ以外のソースからウェーブ データを演奏している場合は、DirectMusic でも同じ DirectSound オブジェクトを使用しなければならない。まず DirectSound オブジェクトを作成し、次にこれを DirectMusic に渡す。この処理は、次の例に示すように DirectMusicPerformance.Init の呼び出しで実行される。Perf は DirectMusicPerformance オブジェクトで、DS は DirectSound オブジェクトである。

Perf.Init(DS, 0);

注 : DirectSound オブジェクトを DirectMusicPerformance.Init に渡すときに、2 番目のパラメータのウィンドウ ハンドルは無視される。アプリケーションは、DirectSound.SetCooperativeLevel を呼び出して、制御ウィンドウの設定を行う必要がある。

DirctMusic で使用される DirectSound オブジェクトに、DSSCL_PRIORITY 協調レベルを設定する。DSSCL_NORMAL 協調レベルを設定した場合、DirectMusic はプライマリ バッファ フォーマットをアップグレードできない。


DirectSound バッファ オブジェクトの設定

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。DirectX for Visual Basic では、DirectMusic 出力に対してカスタム DirectSound バッファはサポートされない。

[C++]

DirectMusic が DirectSound にリンクされる場合、各ポートからのウェーブ出力用のセカンダリ DirectSound バッファが、ポートと同じ形式で作成および管理される。IDirectMusicPort::SetDirectSound メソッドを使ってデフォルトの動作を上書きし、データを別のバッファのストリームに入れることができる。この操作は、たとえばサウンド バッファに 3-D エフェクトを与えるために実行できる (「3DMusic サンプル」を参照すること)。シンセサイザ ポートのインスタンスを複数作成して、それぞれに固有の DirectSound 3-D バッファを設定し、空間内の別の場所に違う音色を配置することもできる。

IDirectMusicPort::SetDirectSound に渡すバッファは、フォーマットの一致したセカンダリ ストリーミング バッファでなければならない。ウェーブ フォーマットの情報および推奨バッファ サイズを取得するには、IDirectMusicPort::GetFormat メソッドを呼び出す。

IDirectMusicPort::SetDirectSound に独自の IDirectSoundBuffer を渡すと、DirectMusic はプライマリ バッファのアップグレードを試みない。


ポートの使い方

ポートは、ミュージック データの送信または受信を行うデバイスである。ハードウェア デバイス、ソフトウェア シンセサイザ、ソフトウェア フィルタのいずれかを表す。

[C++]

DirectMusic アプリケーション内の各ポートは、IDirectMusicPort インターフェイスによって表される。このインターフェイスのメソッドを使って、デバイスに関する情報の取り出し、デバイス内のメモリの管理、DLS 音色のダウンロードとアンロード、流入データの読み込み、再生バッファの挿入を行う。

どのパフォーマンスも少なくとも 1 つのポートを備えていなければならない。デフォルト ポート以外のポートを使って、デフォルト ポートの特別なパラメータを設定する場合は、まず DMUS_PORTPARAMS 構造体を設定する。すべてのメンバに値を入力する必要はないが、dwValidParams メンバに適切なフラグを書き込むことにより、どのメンバが有効な情報を持っているのか DirectMusic に知らせなければならない。次に、この構造体を IDirectMusic::CreatePort メソッドに渡す。

次の C++コード例では、デフォルトの出力ポート用のオブジェクトを作成し、ポートに 5 つのチャンネル グループを設定する方法を示している。pDirectMusic は、有効な IDirectMusic ポインタとする。

IDirectMusicPort*  pPort;
DMUS_PORTPARAMS    dmos;

ZeroMemory( &dmos, sizeof(DMUS_PORTPARAMS) );
dmos.dwSize = sizeof(DMUS_PORTPARAMS);
dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;
dmos.dwChannelGroups = 5;
HRESULT hr = pDirectMusic->CreatePort( GUID_NULL, &dmos,
        &pPort, NULL )

設定したポートは IDirectMusic::Activate または IDirectMusicPort::Activate を呼び出してアクティブ化し、IDirectMusicPerformance::AddPort メソッドを使ってパフォーマンスに付加する。

ポートをパフォーマンスに付加するときに、IDirectMusicPerformance::AssignPChannelBlock メソッドを呼び出して、P チャンネルのブロックを割り当てる。IDirectMusicPerformance::AddPort に NULL を渡してデフォルト ポートを追加するときだけ、この処理が必要ない。この場合、P チャンネル 0-15 は、ポートの最初のグループの MIDI チャンネルに割り当てられる。

IDirectMusicPerformance::AssignPChannelBlock および IDirectMusicPerformance::AssignPChannel の各メソッドを使うと、これらのP チャンネルを異なった方法で割り当て、ほかの P チャンネルを追加し、P チャンネルをほかのポートに割り当てることができる。

[Visual Basic]

DirectX for Visual Basic では、各パフォーマンスに対して 1 つのポートだけがサポートされ、すべての P チャンネル はこのポートに割り当てられる。パフォーマンスを初期化した後に、DirectMusicPerformance.SetPort を使ってポートを選択する。デフォルト ポート を使用するには、index パラメータに -1 を渡す。

パフォーマンスを初期化するときに、利用可能なポートが自動的に列挙される。DirectMusicPerformance.GetPortCount、DirectMusicPerformance.GetPortCaps、および DirectMusicPerformance.GetPortName メソッドを使って、特定のポートや機能を検索することができる。次のコードでは、最初のソフトウェア シンセサイザを検索し、パフォーマンスのポートとして設定している。最大で 16 のチャンネル グループがサポートされている。

' perf は DirectMusicPerformance オブジェクトである。
Dim X As Integer
Dim portcaps As DMUS_PORTCAPS

perf.Init(Nothing, Me.hWnd)
For X = 1 to perf.GetPortCount
    Call perf.GetPortCaps(X, portcaps)
    If portcaps.lFlags And DMUS_PC_SOFTWARESYNTH Then
        perf.SetPort(X, 16)
        Exit For
    End If
Next X
' ポートが設定されてなかった場合は、デフォルト ポートを設定するか、ほかの操作を行う。

ポートの詳細については、次のトピックを参照すること。

  • デフォルト ポート
  • 従来のポート
  • ポートのプロパティ セット


デフォルト ポート

Windows 95、および Windows 98 Second Edition 以前の Windows 98 において、または DLS をサポートするハードウェアを利用できない場合は、Microsoft Software Synthesizer がデフォルト ポートになる。Windows 98 Second Edition 以降、および Windows 2000 では、ハードウェア シンセサイザがデフォルト ポートになる場合もある。

[C++]

アプリケーションでデフォルト ポートを使用する場合、パフォーマンスにポートを追加する前に IDirectMusic::CreatePort メソッドを呼び出す必要はない。代わりに、IDirectMusicPerformance::AddPort に NULL を渡すことができる。

IDirectMusic::GetDefaultPort を呼び出してデフォルト ポートを取得し、続いて IDirectMusicPort::GetCaps メソッドを使って機能を確認する。ポートがアプリケーションの要求に適合しない場合は、IDirectMusic::EnumPort メソッドを使って、Microsoft Software Synthesizer かその他のポートを検索する。

[Visual Basic]

DirectMusicPerformance.SetPort の index パラメータとして -1 を渡すと、パフォーマンスはデフォルト ポートを使用する。ただし、この場合、ポートの機能を確認することはできない。アプリケーションで特定の機能を持つポートが必要な場合は、パフォーマンスを初期化するときに DirectMusic によって作成されたコレクションでポートを確認する。詳細については、「ポートの使い方」を参照すること。


従来のポート

Windows 95 および Windows 98 では、DirectMusic は従来のポートをサポートする。従来のポートとは、出力データが FM またはハードウェア ウェーブテーブル合成を使って MIDI デバイスにシーケンス化されるポートである。

DirectMusic では、従来のポートには次のような制限がある。

  • Windows 2000 ではサポートされない。
  • ダウンローダブル サウンド がサポートされない。
  • マスタ ボリュームを変更できない (グローバル パラメータを設定することによって、ほかのポートで実行できる。「グローバル パラメータの設定と取り出し」を参照すること)。
  • 1 つのチャンネル グループしか利用できない (「チャンネル」を参照すること)。

Microsoft Software Synthesizer により、ウェーブフォーム オーディオを演奏できるすべての出力デバイスで一貫した結果が得られるので、ほとんどのアプリケーションでは、従来のポートについて考慮する必要はない。

[C++]

IDirectMusic::EnumPort または IDirectMusicPort::GetCaps メソッドによって返される DMUS_PORTCAPS 構造体の、dwType メンバの DMUS_PORT_WINMM_DRIVER フラグによって、従来のポートを認識することができる。

従来のポートでは、アプリケーションは DMUS_PORTPARAMS 構造体の fShare メンバを設定して、従来のポートのチャンネルを論理ポート間で共有するかどうかを決定しなければならない点でも、その他のポートと異なっている。このメンバは、DMUS_PORTCAPS 構造体の dwFlags メンバの DMUS_PC_SHAREABLE フラグを持つポートにだけ関係がある。これは常に従来のポートの場合である。

[Visual Basic]

DirectMusicPerformance.GetPortCaps によって返される DMUS_PORTCAPS 型の、lType メンバの DMUS_PORT_WINMM_DRIVER フラグによって、従来のポートを認識することができる。


ポートのプロパティ セット

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。DirectX for Visual Basic では、ポートのプロパティ セットはサポートされない。

[C++]

DirectMusic は、プロパティ セットを通して、ハードウェアとドライバの新しい機能に対するサポートを提供する。プロパティ セットは GUID によって表され、セット内の各項目は 0 から始まるインデックス番号を割り当てられている。

ハードウェア ベンダーは新しい機能をプロパティとして定義し、GUID を含め、それらのプロパティに関する仕様を公示する。IKsControl::KsProperty メソッドを使って、プロパティが利用可能であるかどうかを確認し、プロパティの値を設定および取り出すことができる。IDirectMusicPort::QueryInterface メソッドを呼び出し、インターフェイス識別子として IID_IKsControl を渡すことにより、ポートに対応する.IKsControl インターフェイスを取得する。

プロパティ セットは GUID によって表され、セットの各項目は 0 から始まるインデックスによって表される。GUID に対してインデックス化された項目の意味が変更されることはない。DirectMusic でサポートされるプロパティ セットのリストについては、KSPROPERTY を参照すること。

DirectMusic であらかじめ定義されているプロパティ セットはすべて、ただ 1 つの項目を持っており、通常、インデックス番号は 0 に設定されている。カーネルストリーミング (KS) プロパティの完全定義もサポートされており、ベンダーは任意の数の項目とインスタンス、および任意のサイズのデータを持つプロパティ セットを自由に作成できる。

プロパティ項目の要求をポートに対して送信する作業は、ポートの実装に依存する。Win32 ハンドル ベースのマルチメディア呼び出し (midiOut と midiIn の各関数) を利用して DirectMusic のエミュレーションを行っているポートでは、どのプロパティもサポートされない。

次のコード例では、IKsControl::KsProperty メソッドを使って、ポートが General MIDI サウンド セットをハードウェアでサポートしているかどうかを調べている。

BOOL IsGMSupported(IDirectMusicPort *pPort)
{
    HRESULT     hr;
    IKsControl  *pControl;
    KSPROPERTY  ksp;
    DWORD       dwFlags;
    ULONG       cb;
    BOOL        fIsSupported;

    // IKsControl インターフェイスのクエリ。
    hr = pPort->QueryInterface(IID_IKsControl, (void**)&pControl);
    if (FAILED(hr))
    {
        // ポートはプロパティをサポートしない。GM がサポートされないとする。
        return FALSE;
    }
    // GM について確認する。
    ksp.Set   = GUID_DMUS_PROP_GM_Hardware;
    ksp.Id    = 0;
    ksp.Flags = KSPROPERTY_TYPE_BASICSUPPORT;
    hr = pControl->KsProperty(&ksp, sizeof(ksp),
            &dwFlags, sizeof(dwFlags), &cb);
    fIsSupported = FALSE;
    if (SUCCEEDED(hr) || (cb >= sizeof(dwFlags))
    {
        // セットはサポートされる。
        fIsSupported = (BOOL)(dwFlags & KSPROPERTY_TYPE_GET);
    }
    pControl->Release();
    return fIsSupported;
}

次のコード例は、プロパティを変更する方法を示している。この場合、ソフトウェア シンセサイザのリバーブ プロパティは、DMUS_WAVES_REVERB_PARAMS 構造体に含まれるプロパティに設定される。

/* m_* 変数は、有効な値で初期化されていると仮定する。
   m_pPort は IDirectMusicPort へのポインタである。*/

DMUS_WAVES_REVERB_PARAMS Params;

Params.fInGain = m_fReverbIn;
Params.fHighFreqRTRatio = m_fReverbHigh;
Params.fReverbMix = m_fReverbMix;
Params.fReverbTime = m_fReverbTime;

IKsControl *pControl;
if (m_pPort)
{
    // IKsControl インターフェイスのクエリ。
    HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
            (void**)&pControl);
    if (SUCCEEDED(hr))
    {
        KSPROPERTY ksp;
        ULONG cb;

        ZeroMemory(&ksp, sizeof(ksp));
        ksp.Set   = GUID_DMUS_PROP_WavesReverb;
        ksp.Id    = 0;
        ksp.Flags = KSPROPERTY_TYPE_SET;

        pControl->KsProperty(&ksp,
                             sizeof(ksp),
                             (LPVOID)&Params,
                             sizeof(Params),
                             &cb);
        pControl->Release();
    }
}

次のコード例では、m_pPort で表されるポートでリバーブ エフェクトを有効にしている。

DWORD dwEffects = 0;
IKsControl *pControl;
HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
        (void**)&pControl);
if (SUCCEEDED(hr))
{
  KSPROPERTY ksp;
  ULONG cb;

  ZeroMemory(&ksp, sizeof(ksp));
  dwEffects = DMUS_EFFECT_REVERB;
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_SET;

  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID)&dwEffects,
             sizeof(dwEffects),
             &cb);
  pControl->Release();
}

最後の例は、その他のエフェクトを現状のまま、リバーブだけをオフにする方法を示している。

DWORD dwEffects = 0;
IKsControl *pControl;
HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
        (void**)&pControl);
if (SUCCEEDED(hr))
{
  KSPROPERTY ksp;
  ULONG cb;

  ZeroMemory(&ksp, sizeof(ksp));
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_GET;

  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID)&dwEffects,
             sizeof(dwEffects),
             &cb);

  ZeroMemory(&ksp, sizeof(ksp));
  dwEffects = dwEffects & ~DMUS_EFFECT_REVERB;
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_SET;

  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID)&dwEffects,
             sizeof(dwEffects),
             &cb);

  pControl->Release();
}


DirectMusic ローダー

[C++]

DirectMusic オブジェクトをミュージック パフォーマンスに組み込む前に、それらをファイルまたはリソースからロードしなければならない。IDirectMusicLoader インターフェイスは、これらのオブジェクトのロードを管理するために使用される。また、オブジェクトを検索および列挙し、何度もロードされないようにキャッシングするためにも使用される。

アプリケーションでは、既存のローダーのインスタンスを、一度に 1 つだけ使用するべきである。1 つのグローバル ローダー オブジェクトを作成し、ロードがすべて終了するまでオブジェクトを解放しないようにする。この方法により、オブジェクトが効果的に検索およびキャッシングされる。

DirectMusic における IStream の実装により、データがソースからストリームに入れられる。データの解析は、IPersistStream の実装を通して、さまざまなオブジェクト自身によって処理される。標準的な DirectMusic データだけを処理する場合は、これらのインターフェイスを直接使用する必要はない。

ほかのオブジェクトによって参照されるオブジェクトは、透過的にロードされる。たとえば、DirectMusic Producer からロードされるスタイルに、ほかのファイルにデータがあるバンドへの参照が含まれているとする。スタイルの IPersistStream は参照を見つけると、データ ストリームを渡した IStream から IDirectMusicGetLoader インターフェイスを取得する。このインターフェイスを使用して、DirectMusicLoader へのポインタを取得する。続いて、IDirectMusicLoader::GetObject を呼び出して、バンドをロードする。

[Visual Basic]

DirectMusic オブジェクトをミュージック パフォーマンスに組み込む前に、それらをファイルまたはリソースからロードしなければならない。DirectMusicLoader クラスは、これらのオブジェクトのロードを管理するために使用される。

アプリケーションでは、既存の DirectMusicLoader オブジェクトを、一度に 1 つだけ使用するべきである。1 つのグローバル ローダー オブジェクトを作成し、ロードがすべて終了するまでオブジェクトを解放しないようにする。この方法により、オブジェクトが効果的に検索およびロードされる。

ただし、アプリケーションがセグメントを何度もロードする場合は、DirectMusic が内部で使用しているキャッシュ システムのために、同じセグメント オブジェクトは、ループの開始ポイントや DLS コレクションへの接続などの設定を、同じ内容で取得するように注意する。これを避けるには、セグメントを再ロードする前に、DirectMusicLoader オブジェクトを Nothing に設定して解放し、新しいオブジェクトを作成する。

ほかのオブジェクトによって参照されるオブジェクトは、透過的にロードされる。たとえば、DirectMusic Producer からロードされるスタイルに、ほかのファイルにデータがあるバンドへの参照が含まれているとする。DirectMusic は自動的にバンドをロードし、アプリケーションは DirectMusicStyle.GetBand メソッドを使ってこれを取り出す。

ローダーの使用方法の詳細については、次のトピックを参照すること。

  • ローダーの検索ディレクトリの設定
  • ディレクトリでのオブジェクト検索
  • オブジェクトの列挙
  • ファイルからのオブジェクトのロード
  • リソースからのオブジェクトのロード
  • オブジェクト デスクリプタの取得
  • オブジェクトのキャッシング
  • オブジェクトの設定
  • カスタム ロード


ローダーの検索ディレクトリの設定

[C++]

検索対象のオブジェクトを記述する DMUS_OBJECTDESC 構造体の wszFileName メンバがフル パスを指定していない限り、ローダーはデフォルトでカレント ディレクトリを検索する。IDirectMusicLoader::SetSearchDirectory メソッドを使うと、IDirectMusicLoader::GetObject と IDirectMusicLoader::EnumObject の各メソッドで異なったデフォルト パスを設定できる。このデフォルト パスをすべてのオブジェクトに適用することも、特定のクラスのオブジェクトだけに適用することもできる。

次のコード例では、スタイル ファイルの検索パスを設定している。

HRESULT mySetLoaderPath (
    IDirectMusicLoader *pILoader)    // 以前に作成済み。
{
    return pILoader->SetSearchDirectory(
            CLSID_DirectMusicStyle,
            L"c:\\mymusic\\funky",
            FALSE);
}

この関数を呼び出しておくと、アプリケーションは次のコード例のように、フル パスを指定せずにファイル名だけを使ってスタイルをロードできる。

HRESULT myLoadStyleFromPath (
    IDirectMusicStyle **ppIStyle,    // スタイルへのポインタを取り出す。
    IDirectMusicLoader *pILoader)    // ローダーは既に作成済。
{
    HRESULT hr;
    DMUS_OBJECTDESC Desc;

    ZeroMemory(&Desc, sizeof(DMUS_OBJECTDESC);
    Desc.dwSize = sizeof(DMUS_OBJECTDESC);
    wcscpy(Desc.wszFileName, L"polka.sty");   // 短いファイル名。
    Desc.guidClass = CLSID_DirectMusicStyle;  // オブジェクト クラス
    Desc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME;

    hr = pILoader->GetObject(&Desc,
            IID_IDirectMusicStyle, (void **) ppIStyle);
    return hr;
}
[Visual Basic]

デフォルトでは、ロード メソッドにフル パスを渡さない限り、ローダーはカレント ディレクトリのファイル オブジェクトを検索する。DirectMusicLoader.SetSearchDirectory メソッドを使うと、DirectMusicLoader.LoadBand、DirectMusicLoader.LoadCollection、DirectMusicLoader.LoadSegment、および DirectMusicLoader.LoadStyle メソッドに異なるデフォルト パスを設定することができる。


ディレクトリでのオブジェクト検索

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。

[C++]

IDirectMusicLoader::ScanDirectory メソッドは、特定のクラスのオブジェクトを現在の検索ディレクトリで探す。サブクラスと、"*" 以外のファイル拡張子を指定することにより、検索範囲を狭められる。

このメソッドは一致するすべてのファイルから成るリストを作成し、IDirectMusicObject::ParseDescriptor メソッドを使ってオブジェクトの GUID と名前を抽出する。これらの識別子は内部データベースに保持されるので、アプリケーションはそれ以降、ファイル名ではなく GUID や名前を使ってオブジェクトをロードできる (「ファイルからのオブジェクトのロード」を参照すること)。

注 : オブジェクトをロードする前に、常に IDirectMusicLoader::ScanDirectory を呼び出すのは良い考えである。ファイル名を明示的に指定してオブジェクトをロードする場合でも、これらのオブジェクトにはファイル名で指定されていないほかのオブジェクトへの参照が含まれている場合がある。オブジェクトが格納されている各ディレクトリに対して ScanDirectory が呼び出されていない場合、ローダーはこれらの参照されているオブジェクトを見つけることができない。

ScanDirectory メソッドの pwszScanFileName パラメータに、文字列へのポインタを含めると、その名前を持つファイルに検索結果がキャッシングされ、それ以降の検索が高速化される。キャッシュ ファイルを利用できる場合、このメソッドはタイム スタンプやサイズが変更されているファイルに限ってオブジェクト情報を更新する。

注 : 現在のバージョンの DirectMusic では、ScanDirectory はキャッシュ ファイルを使用しない。キャッシュ ファイルの実装は、現在でも可能である。これにより、今後のバージョンでパフォーマンスが向上する。

例については、「オブジェクトの列挙」を参照すること。


オブジェクトの列挙

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。

[C++]

IDirectMusicLoader::EnumObject メソッドを使って、IDirectMusicLoader::ScanDirectory または IDirectMusicLoader::GetObject のどちらかを呼び出して内部データベースに記録した、特定のクラスまたは全クラスの全オブジェクトを反復する。見つかった各オブジェクトの説明は、DMUS_OBJECTDESC 構造体に返される。

注 : 全オブジェクトを確実に見つけるには、最初に ScanDirectory を呼び出しておく。EnumObject はディスク ファイルを解析するのではなく、内部データベースでオブジェクトをチェックする。

次の例では、現在の検索ディレクトリに記録されているすべてのスタイル オブジェクトを列挙し、デバッギング マクロ TRACE を使ってそれらの情報を 1 つずつ表示している。そのクラスで列挙すべきオブジェクトがなくなるまでループは続行される。

void myListStyles(
        IDirectMusicLoader *pILoader)

{
    HRESULT hr = pILoader->SetSearchDirectory(
            CLSID_DirectMusicStyle,
            L"c:\\mymusic\\wassup",
            TRUE);
    if (SUCCEEDED(hr))
    {
        hr = pILoader->ScanDirectory(
                CLSID_DirectMusicStyle,
                L"sty",
                L"stylecache");
        if (hr == S_OK)    // ファイルが見つかった場合のみ...
        {
            DWORD dwIndex;
            DMUS_OBJECTDESC Desc;
            Desc.dwSize = sizeof(DMUS_OBJECTDESC);
            for (dwIndex = 0; ;dwIndex++)
            {
                if (S_OK ==(pILoader->EnumObject(
                        CLSID_DirectMusicStyle,
                        dwIndex, &Desc)))
                {
                    TRACE("Name: %S, Category: %S, Path: %S\n",
                            Desc.wszName,
                            Desc.wszCategory,
                            Desc.wszFileName);
                }
                else break;
            }
        }
    }
}

このコード例では、メソッド呼び出しの結果をテストする目的で、SUCCEEDED マクロを使っていない点に注意すること。不適切なインデックス番号を指定した場合、EnumObject が成功コードの S_FALSE を返すためである。


ファイルからのオブジェクトのロード

[C++]

オブジェクトをロードするには、次のコード例に示すように、最初に IDirectMusicLoader インターフェイスを取得する。

IDirectMusicLoader* m_pLoader;

CoInitialize(NULL);
HRESULT hr = CoCreateInstance(
    CLSID_DMLoader,
    NULL,
    CLSCTX_INPROC,
    IID_IDirectMusicLoader,
    (void**)&m_pLoader);

次にオブジェクトを記述し、IDirectMusicLoader::GetObject メソッドを呼び出してそのオブジェクトをロードし、希望のインターフェイスを取得する。

次のコード例では、ディスクからスタイルをロードし、そのスタイルへのポインタを、パラメータによって指定された変数へ返している。

void myLoadStyle(
    IDirectMusicStyle **ppIStyle)
{
    IDirectMusicLoader *pILoader;        // ローダー インターフェイス。

/* 通常はローダーを 1 回作成し、アプリケーションを実行している間、
そのローダーを使用する。これにより、オーバーヘッドが減少し、
オブジェクトをキャッシングするローダーの機能を利用できる。ただし、
この例では、ローダーを動的に作成し、スタイルをロードした後で
破棄している。*/

    CoCreateInstance(
            CLSID_DirectMusicLoader,NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicLoader,
            (void **) &pILoader);

    if (pILoader)
    {
        DMUS_OBJECTDESC Desc;

        // 最初にファイル名とスタイル オブジェクトの GUID を指定して、
        // Desc を初期化する。

        wcscpy(Desc.wszFileName,L"c:\\mymusic\\funky\\polka.sty");
        Desc.guidClass = CLSID_DirectMusicStyle;
        Desc.dwSize = sizeof (DMUS_OBJECTDESC);
        Desc.dwValidData = DMUS_OBJ_CLASS |
                           DMUS_OBJ_FILENAME |
                           DMUS_OBJ_FULLPATH;

        pILoader->GetObject(&Desc, IID_IDirectMusicStyle,
                (void **) ppIStyle);
        pILoader->Release();
    }
}

このコード例では、ファイルをフル パス名で指定し、これを DMUS_OBJ_FULLPATH フラグを設定して指示している。既に検索ディレクトリを設定してある場合は、フル パス情報なしでファイルの短い名前を使える。例については、「ローダーの検索ディレクトリの設定」を参照すること。

検索対象の特定のファイル オブジェクトを識別するには、DMUS_OBJECTDESC 構造体の wszName、guidObject、wszFileName の各メンバのいずれかに値を入力し、dwValidData メンバに適切な 1 つまたは複数のフラグをセットする。wszFileName ではなく wszName か guidObject を使ってファイルを識別する場合は、IDirectMusicLoader::ScanDirectory メソッドを呼び出して、カレント ディレクトリ内の GUID と名前を利用可能にしなければならない。詳細については、「ディレクトリでのオブジェクト検索」を参照すること。

[Visual Basic]

オブジェクトをロードするには、まず DirectMusicLoader オブジェクトを作成する。続いて、次のいずれかのメソッドを呼び出す。

  • DirectMusicLoader.LoadBand
  • DirectMusicLoader.LoadCollection
  • DirectMusicLoader.LoadSegment
  • DirectMusicLoader.LoadStyle

目的のオブジェクトが含まれているファイルの、ファイル名またはフル パスのいずれかを渡す。これらのメソッドは、適切なクラスのインスタンスを返す。

次のコード例では、現在の検索ディレクトリにあるファイルからセグメントをロードしている。objDX は DirectX7 オブジェクトを表す。

Dim objDMLoader As DirectMusicLoader
Dim objSeg As DirectMusicSegment

Set objDMLoader = objDX.DirectMusicLoaderCreate
Set objSeg = objDMLoader.LoadSegment("Myseg.sgt")

「リソースからのオブジェクトのロード」も参照すること。


リソースからのオブジェクトのロード

[C++]

リソースから、またはメモリの別の場所からオブジェクトをロードする操作は、ファイルからオブジェクトをロードする場合とほぼ同じである (「ファイルからのオブジェクトのロード」を参照すること)。ただし、この場合、DMUS_OBJECTDESC 構造体の wszName、guidObject、および wszFileName メンバは使用しない。これらのメンバの代わりに、オブジェクトが占有しているメモリ ブロックへのポインタと、そのサイズを取得し、これらの情報をそれぞれ、DMUS_OBJECTDESC 構造体の pbMemData および llMemLength メンバに格納する。dwFlags メンバの DMUS_OBJ_MEMORY フラグも設定しなければならない。

データを簡単にキャッシングできるように、ローダーはメモリへのポインタを内部で保持するため、一度 IDirectMusicLoader::GetObject が呼び出されると、メモリを解放することはできない。これを消去するには、IDirectMusicLoader::SetObject を同じ DMUS_OBJECTDESC デスクリプタを使って呼び出す。ただし、pbMemData には NULL を設定する。リソース メモリは解放されないため、リソースからロードする場合は関係ない。

次の例では、MIDI ファイルをリソースからセグメントにロードしている。

HRESULT LoadMidi(HMODULE hMod, WORD ResourceID)
{
    HRESULT              hr;
    DMUS_OBJECTDESC      ObjDesc;
    IDirectMusicSegment* pSegment = NULL;

    HRSRC hFound = FindResource(hMod,
            MAKEINTRESOURCE(ResourceID), RT_RCDATA);
    HGLOBAL hRes = LoadResource(hMod, hFound);

    ObjDesc.dwSize = sizeof(DMUS_OBJECTDESC);
    ObjDesc.guidClass = CLSID_DirectMusicSegment;
    ObjDesc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_MEMORY;
    ObjDesc.pbMemData = (BYTE *) LockResource(hRes);
    ObjDesc.llMemLength = SizeofResource(hMod, hFound);

    hr = m_pDXPerformance->m_pLoader->GetObject(
            &ObjDesc, IID_IDirectMusicSegment2,
            (void**) &m_pSegment );

    return hr;
}

ほかのオブジェクトによって参照されているオブジェクトは、最初にロードしなければならない。たとえば、スタイルへの参照を含むセグメントをロードする場合、セグメントを正しく演奏するには、スタイルが先にロードされていなければならない。セグメントがスタイルを見つけられるように、スタイルで DirectMusicLoader::SetObject を呼び出すこともできる。

[Visual Basic]

リソースから、またはメモリの別の場所からオブジェクトをロードする操作は、ファイルからオブジェクトをロードする場合とほぼ同じである (「ファイルからのオブジェクトのロード」を参照すること)。DirectMusicLoader.LoadBandFromResource、DirectMusicLoader.LoadChordMapFromResource、DirectMusicLoader.LoadCollectionFromResource、DirectMusicLoader.LoadSegmentFromResource、および DirectMusicLoader.LoadStyleFromResource メソッドはそれぞれ、モジュール名とリソース識別子をパラメータとして受け取り、適切なクラスのインスタンスを返す。

ローダーでは、次の種類のリソースが認識される。

"DMBAND" | LoadBandFromResource
"DMCHORD" | LoadChordmapFromResource
"DMCOLL" | LoadCollectionFromResource
"DMSEG" | LoadSegmentFromResource
"DMSTYLE" | LoadStyleFromResource

ほかのオブジェクトによって参照されているオブジェクトは、最初にロードしなければならない。たとえば、スタイルへの参照を含むセグメントをロードする場合、セグメントを正しく演奏するには、スタイルが先にロードされていなければならない。

次のコード例では、実行可能ファイルに "DMSEG" リソースとして格納されている MIDI ファイルを、ロードおよび演奏する。loader は DirectMusicLoader オブジェクトを表し、perf は DirectMusicPerformance を表す。

Dim seg As DirectMusicSegment
Set seg = loader.LoadSegmentFromResource("listen.exe", "CANYON.MID")
Call seg.Download(perf)
Call perf.PlaySegment(SEG, 0, 0)


オブジェクト デスクリプタの取得

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。

[C++]

オブジェクトをロードした後で、そのオブジェクトの IDirectMusicObject インターフェイスを使って、DMUS_OBJECTDESC 構造体内の情報を取り出さなければならない。最初にそのオブジェクトの IDirectMusicObject インターフェイスを取得しなければならない。

次のコード例では、IDirectMusicObject::GetDescriptor メソッドを使ってスタイル名を取得している。

/* pStyle は、DirectMusicPerformance インターフェイスへの
   有効なポインタを表す。*/

if (pStyle)
{
    IDirectMusicObject *pIObject;
    DMUS_OBJECTDESC Desc;

    if (SUCCEEDED(pStyle->QueryInterface(IID_IDirectMusicObject,
            (void **) &pIObject)
    {
        if (SUCCEEDED(pIObject->GetDescriptor(&Desc))
        {
            if (Desc.dwValidData & DMUS_OBJ_NAME)
            {
                TRACE("スタイル名は、%S です。\n",Desc.wszName);
            }
        }
        pIObject->Release();
    }
}


オブジェクトのキャッシング

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。

[C++]

オブジェクトをキャッシングすると、IDirectMusicLoader::GetObject メソッドは常に同じインターフェイスポインタを返すようになる。

ファイル ロード プロセスでは、オブジェクトへのリンクを解決するためにキャッシングが広範囲に使われる。キャッシュ内にオブジェクトが見つからない場合、そのオブジェクトが既に存在している場合でも、オブジェクトを再ロードしなければならない。たとえば、2 つのセグメントが同じスタイルを参照している場合を考える。最初のセグメントをロードするときに、セグメントはローダーを呼び出してスタイルを取得する。続いてスタイルは、スタイル オブジェクトを作成してディスクからロードし、スタイルへのポインタをキャッシュに格納して、これをセグメントに返す。キャッシングが有効な場合、2 番目のセグメントがロードされるときにスタイルの問い合わせが行われ、ローダーが直ちにこれを返す。2 つのセグメントは、どちらも同じスタイルを指している。キャッシングが無効な場合は、2 番目のセグメントが同じスタイルを要求したときに、同じスタイルがファイルからロードされて重複することになる。これは非常に効率が悪い。

もう一つの例として、IDirectMusicBand が General MIDI の DLS コレクションをキャッシュに置くよう要求する場合を考える。IDirectMusicBand が GM 音色を操作するたびに、ローダーに GUID_DefaultGMCollection を要求し、ローダーからコレクションを取得する。CLSID_DirectMusicCollection のキャッシングが無効になっている場合、MIDI ファイル内でパッチ チェンジが発生するたびに、GM コレクション全体のコピーが作成される。

デフォルトでは、すべてのオブジェクト クラスでキャッシングが有効になっている。IDirectMusicLoader::EnableCache メソッドを使うと、1 つまたはすべてのオブジェクト クラスのキャッシングを無効にできる。このメソッドを使って、任意またはすべてのオブジェクト クラスのキャッシングを有効にすることもできる。

今後のキャッシングを無効にせずにキャッシュを消去するには、IDirectMusicLoader::ClearCache メソッドを使う。

1 つのオブジェクトをキャッシングするには、そのオブジェクトを IDirectMusicLoader::CacheObject メソッドに渡す。IDirectMusicLoader::ReleaseObject メソッドを使ってキャッシュからオブジェクトを削除し、次にそのオブジェクトに対して GetObject を呼び出したときに、そのオブジェクトが再びロードされることを保証できる。

Release メソッドを呼び出してオブジェクトを破棄する前に、キャッシングされたオブジェクト、特にセグメントに対して ReleaseObject を呼び出す。呼び出しを行わなかった場合、オブジェクトのコピーがキャッシュ内に残り、特定の状態を表す情報が保持される。セグメントの場合は、今後作成するインスタンスがキャッシュからロードされ、開始ポイントとループ ポイントが、前のインスタンスが破棄されたときの状態と同じになる。

CacheObject、ReleaseObject、および EnableCache を適切に使うことにより、不必要なオブジェクトをキャッシュから削除し、その他のオブジェクトをキャッシュに残すことができる。


オブジェクトの設定

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。

[C++]

後でほかのオブジェクトから参照されるオブジェクトを、参照元のオブジェクトをロードするときにローダーが取り出せるように、実際にはロードせずに、その場所だけをローダーに指示することが望ましい。オブジェクトに新しい属性を与えて、ローダーが属性を使ってオブジェクトを検索できるようにすることもできる。

SetObject メソッドは、パラメータとして DMUS_OBJECTDESC 構造体を受け取る。この構造体には、2 つの主要な情報が含まれる。

  • データへのポインタ。ファイル パスまたはメモリのブロックへのポインタとなる (「ファイルからのオブジェクトのロード」および「リソースからのオブジェクトのロード」を参照すること)。
  • 後で参照されたときに使用する、オブジェクトの識別子。GUID または名前となる。GetObject の呼び出しで、同じ名前または GUID を使って、格納されたオブジェクトが検索される。オブジェクトに既に存在している GUID または名前を変更することはできない。
  • 次のコード例では、リソース内の名前の付いていないオブジェクト (MIDI ファイルなど) に名前を割り当てている。
HRESULT SetObjectFromResource(const GUID* guid, int ID,
        char* type, WCHAR* name)
{
  HRSRC hResource = NULL;
  HGLOBAL hData = NULL;
  hResource = FindResource(g_hInstance, MAKEINTRESOURCE(ID), type);
  if (hResource != NULL)
  {
    hData = LoadResource(g_hInstance, hResource);
    if (hData != NULL)
    {
      DMUS_OBJECTDESC desc;
      if(m_pLoader && (hResource != NULL) && (hData != NULL))
      {
        ZeroMemory(&desc,sizeof(desc));
        desc.pbMemData = (BYTE*) LockResource(*hData);
        desc.llMemLength = SizeofResource(g_hInstance, (*hResource));
        desc.guidClass = (*guid);
        desc.dwSize = sizeof(desc);
        desc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_MEMORY;
        if (name)
        {
            wcscpy(desc.wszName, name);
            desc.dwValidData |= DMUS_OBJ_NAME;
        }
        return m_pLoader->SetObject(&desc);
      }
    }
  }
  return E_FAIL;
}

次のコードは、MIDI タイプのリソースとして格納された MIDI ファイルに名前を割り当てるときに使用できる。

SetObjectFromResource(CLSID_DirectMusicSegment, 101,
"MIDI", "canyon");

これ以降、オブジェクトはいつでも名前を使ってロードできる。


カスタム ロード

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。DirectX for Visual Basic では、標準的な DirectMusic オブジェクトのロードだけがサポートされる。

[C++]

特殊なアプリケーションでは、ファイルやリソースからのデータをカプセル化する、独自のオブジェクト タイプを作成できる。DirectMusic ローダに、これらのオブジェクトのロードを処理させると便利である。カスタム オブジェクトがほかのオブジェクトから参照されている場合や、カスタム オブジェクトにほかのオブジェクトへの参照が含まれている場合に、特に便利となる。

DirectMusic ローダーを利用するロード メカニズムを実装するには、次の手順を実行する。

  • IDirectMusicLoader::GetObject で検索されるように、オブジェクト クラスを登録する。
  • オブジェクトを検索およびキャッシングするために必要な情報をローダーが取得できるように、オブジェクトに IDirectMusicObject インターフェイスを実装する。
  • オブジェクトに IPersistStream インターフェイスを実装し、IPersistStream::Load メソッドの機能をすべて使えるようにする。これにより、DirectMusicLoader によって渡された、IStream インターフェイス上の呼び出しを通して取得したデータを解析することができる。
  • Load の実装において、IDirectMusicGetLoader インターフェイスの IStream のクエリを行い、次に IDirectMusicGetLoader::GetLoader を呼び出して、ストリームを作成した DirectMusicLoader へのポインタを取得することで、ほかのオブジェクトへの参照が処理されていることを確認する。このポインタを取得したら、IDirectMusicLoader::GetObject を呼び出して、新しいオブジェクトをロードする。

アプリケーションが、ファイル入力そのものを管理しなければならない場合もある。たとえば、すべてのオブジェクトが、特殊な圧縮リソース ファイルに格納されている場合などである。アプリケーションは、IDirectMusicLoader インターフェイスをサポートするオブジェクトを作成し、IDirectMusicLoader::GetObject メソッドを実装して、独自のローダーを作成することができる。ほかのメソッドはすべてオプションである。また、ローダーのこの実装は、IStream および IDirectMusicGetLoader インターフェイスの両方を持つ独自のストリーム オブジェクトを作成しなければならない。


DirectMusic のファイル形式

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic は、ファイル解析をサポートしない。ファイル解析、常に DirectMusicLoader オブジェクトによって透過的に処理される。

[C++]

ここでは、DirectMusic Producer などのアプリケーションで作成され、IDirectMusicLoader::GetObject が呼び出されたときに DirectMusic によって読み込まれる、ミュージック ファイルの形式について説明する。ほとんどのアプリケーションでは、これらのファイルを直接解析することはない。このファイル形式の情報は、ミュージック オーサリング アプリケーションや DirectMusic プラグインの開発者が、データを互換性のある形式で保存したり、独自のオブジェクトにデータをロードできるようにするために提供されている。

DirectMusic データは、RIFF (Resource Interchange File Format) で保存される。次のトピックでは、RIFF ファイルに関する情報と、DirectMusic がデータを格納する方法について説明している。

  • RIFF について
  • RIFF の表記法
  • DirectMusic ファイルのチャンク

DirectMusic ファイルで使用されるデータ構造については、「ファイルの構造体」を参照すること。


RIFF について

RIFF ファイルの基本的な構成単位はチャンクである。チャンクは、データの論理的な単位である。各チャンクには、次のフィールドが含まれている。

  • チャンク識別子を表す、4 文字のコード (FOURCC)。慣習的に、チャンク タイプの登録には大文字を使い、それ以外では小文字を使う。
  • チャンクのデータ メンバのサイズを指定する DWORD 値。
  • データ。

ほかのチャンクに含まれているチャンクは、サブチャンクである。サブチャンクを含むことができるチャンクは、チャンク識別子が RIFF または LIST のチャンクだけである。

ファイルの最初のチャンクは、RIFF として識別されなければならない。ファイル内のその他のチャンクはすべて、RIFF チャンクのサブチャンクとなる。

RIFF チャンクでは、データ フィールドの最初の 4 バイトに追加フィールドが含まれる。追加フィールドでは、チャンクの形式タイプが提供される。形式タイプは、ファイルに格納されるデータの形式を識別する、4 文字のコードである。たとえば、DirectMusic のスタイルの形式タイプは DMST である。

LIST チャンクも、データ フィールドの最初の 4 バイトに追加フィールドを含んでいる。この追加フィールドには、フィールドのリスト タイプが含まれる。リスト タイプは、リストの内容を識別する 4 文字のコードである。たとえば、DirectMusic のスタイルは、パフォーマンスの特定のパート (音色トラック) に関するデータを含む、リスト タイプが "part" の LIST チャンクを持っている。

LIST チャンクは、サブチャンクをグループ化したものである。これらのサブチャンクのいくつかは繰り返し現れる場合があるが、LIST は配列ではない。使用されている用語のために、混乱が生じる可能性がある。たとえば、<part-list> というラベルの付いたチャンクは、パートのリストであると予想するかもしれないが、実際には、"パート" チャンクの要素のリストであり、1 つのパートを示している。

注 : DirectMusic ファイルで使用されているすべての 4 文字コードには、対応するマクロが Dmusicf.h に用意されている。たとえば、DMST の FOURCC は、DMUS_FOURCC_STYLE_FORM マクロによって返される。

一般的な RIFF ファイルの詳細については、Platform SDK ドキュメントの「Resource Interchange File Format Services」を参照すること。


RIFF の表記法

次の DirectMusic ファイルの説明は、従来の RIFF ファイルの表記法のサブセットを使用している。この表記法の主な部分を、次の表に示す。

表記法 | 説明
<element> | "element" というラベルの付いたファイル要素、または element タイプ
[ <element> ] | オプションのファイル要素
<element>... | 指定した要素の 1 つまたは複数のコピー
[<element>]... | 指定した要素の 0 以上のコピー
name、'name'、NAME、または 'NAME' | 形式タイプ、リスト タイプ、またはチャンクの FOURCC 識別子
// コメント | コメント.

ラベルは表記法でのみ使用され、ファイル自体では使用されない。<cheh-ck> というラベルは、固有の FOURCC 識別子および形式を持つチャンクを参照する。この種類のチャンクが表記法に現れる場合は、同じラベルが使用される。

ラベルに関連付けられたデータまたはサブ要素は、次のように表される。

<cheh-ck> -> cheh( <DMUS_IO_CHORDENTRY> )

この表記法は、<cheh-ck> というラベルの付いたチャンクは、FOURCC 識別子の "cheh" と、それに続く DMUS_IO_CHORDENTRY 構造体で構成されていることを表す。もちろん、RIFF チャンクと同様に、データのサイズを表す DWORD を、データの前に置かなければならない。このデータ サイズ要素は当然あるべきものと考えられるため、表記法には示していない。

次の例は、リスト要素を示している。FOURCC LIST とリスト識別子の "camp"、および <choe-list> というラベルの付いた 1 つまたは複数の要素で構成されている。<choe-list> 要素は、ほかの場所に展開される。

<cmap-list> -> LIST( 'cmap'
<choe-list>... )


DirectMusic ファイルのチャンク

ここでは、DirectMusic RIFF ファイルで使用されている、チャンクの形式について説明する。

  • 共通のチャンク
  • バンド形式
  • コード マップ形式
  • セグメント形式
  • スタイル形式
  • ツール形式
  • ツール グラフ形式
  • トラック形式


共通のチャンク

次のチャンクは、さまざまなリスト チャンクおよび形式で使用される。

GUID チャンク

<guid-ck> -> guid( <GUID> )

これは、要素の GUID 識別子である。

バージョン チャンク

<vers-ck> -> vers( <DMUS_IO_VERSION> )

このチャンクには、要素のバージョン情報が含まれる。

UNFO チャンク

<UNFO-list> -> LIST( 'UNFO'
<unfo-text-ck>...
    )

UNFO チャンクは、RIFF INFO リストに似ている。ただし、Unicode 文字を使う点が異なっている。INFO および UNFO リストは、NULL で終了する文字列を含む、さまざまなチャンクで構成される。

参照リスト チャンク

参照リスト チャンクには、ほかのファイルのオブジェクトへの参照に関する情報が含まれる。たとえば、バンド オブジェクトには、別のファイルにある DLS コレクションへの参照が含まれている場合がある。

参照リストの表記法は、次のようになる。

<DMRF-list> ->LIST( 'DMRF'
<refh-ck>       // 参照ヘッダー
[<guid-ck>]     // オブジェクトの GUID
[<date-ck>]     // ファイルの日付
[<name-ck>]     // 名前
[<file-ck>]     // ファイル名
[<catg-ck>]     // カテゴリ名
[<vers-ck>]     // バージョン情報
)

データは、参照されているオブジェクトに関する情報を含むヘッダーから始まる。

<refh-ck> -> refh( <DMUS_IO_REFERENCE> )

ほかのチャンクはすべてオプションである。GUID およびバージョン チャンクは、上で説明したとおりである。その他の表記法は、次のとおりである。

<date-ck> -> date( <FILETIME> )
<name-ck> -> name( <WCHAR>...)  // NULL で終了する文字列
<file-ck> -> file( <WCHAR>...)  // NULL で終了する文字列
<catg-ck> -> catg( <WCHAR>...)  // NULL で終了する文字列


バンド形式

次の表記法は、バンド ファイルの最上位レベルのチャンクまたは形式を示している。バンド形式は、ほかのチャンクに含めることもできる。

RIFF( 'DMBD'
[<guid-ck>]     // バンドの GUID
[<vers-ck>]     // オプションのバージョン情報
[<UNFO-list>]   // 名前、作者、著作権情報、コメント
<lbil-list>     // 音色のリスト
)

最初の 3 つのチャンクはオプションである。詳細については、「共通のチャンク」を参照すること。

データは、リストのいずれかに含まれる。

<lbil-list> -> LIST( 'lbil'
<lbin-list>...
    )

各音色は、リスト中に次の形式で記述される。

<lbin-list> -> LIST( 'lbin'
<bins-ck>
[<DMRF-list>]
    )

音色リスト内で、次のチャンクには音色を表すヘッダーが含まれる。

<bins-ck> -> bins( <DMUS_IO_INSTRUMENT> )

音色リストには、DLS 音色への参照である <DMRF-list> を含めることもできる。「共通のチャンク」を参照すること。


コード マップ形式

次の表記法は、コード マップ ファイルの最上位レベルのチャンク、または形式の構成を示している。

RIFF( 'DMPR'
<perh-ck>       // コード マップ ヘッダー チャンク
[ <guid-ck> ]   // GUID チャンク
[ <vers-ck> ]   // バージョン チャンク
[ <UNFO-list> ] // UNFO リスト
<chdt-ck>       // コード データ チャンク
<chpl-list>     // コード パレット
<cmap-list>     // コード グラフ
<spsq-list>     // サインポスト リスト
)

GUID チャンク、バージョン チャンク、および UNFO リストを除く、各項目が必要である。「共通のチャンク」を参照すること。

必要なチャンクと、そのサブチャンクは次のとおりである。

<perh-ck> -> perh( <DMUS_IO_CHORDMAP> )

これは、コード マップの基本的なヘッダー情報である。

<chdt-ck> -> chdt(
<WORD>    // DMUS_IO_CHORDMAP_SUBCHORD のサイズ
<DMUS_IO_CHORDMAP_SUBCHORD>...
    )

<chdt-ck> チャンクには、サブコード当たりのバイト数を表す WORD 値と、固有のサブコードの配列が含まれる。このファイルのほかのパートで参照されているサブコード識別子はすべて、この配列のインデックスに直接対応する。

<chpl-list> -> LIST( 'chpl'
<chrd-list>...
    )

このリストにはコード パレットが含まれる。現在、このリストには 24 の項目が必要である。

<chrd-list> -> LIST( 'chrd'
<UNAM-ck>    // コード名
<sbcn-ck>    // サブコードのインデックス
    )

このリストには、基本的なコード情報が含まれる。この情報は、コードの名前と、サブコードの識別子のリストを表す。

<UNAM-ck> -> UNAM ( <WCHAR>... )

UNAM チャンクは、コードの名前を格納する。

<sbcn-ck> -> sbcn( <WORD>... )

"sbcn" チャンクには、1 つまたは複数のサブコード識別子が含まれる。これらは、<chdt-ck> にある配列のインデックスに直接対応する。現在、最大で 4 つのコードがサポートされている。

<cmap-list>  ->  LIST( 'cmap'
<choe-list>...
    )

"cmap" リストには、コード マップのコード接続グラフ全体が含まれる。コード マップの大部分のデータは、このチャンクに存在する。

<choe-list> -> LIST( 'choe'
<cheh-ck>      // コード エントリ データ。
<chrd-list>    // コード データ。上の説明を参照。
<ncsq-ck>      // 次のコード リスト。
    )

"choe" リストには、コード グラフの 1 つのエントリのデータと、次にコード グラフに現れるすべてのコードへのポインタが含まれる。

<cheh-ck> -> cheh( <DMUS_IO_CHORDENTRY> )

これは、コード エントリ ヘッダーである。構造体の識別子は、コード接続グラフの識別子であり、サブコード識別子ではない。

<ncsq-ck> -> ncsq (
<WORD>         // DMUS_IO_NEXTCHORD のサイズ
<DMUS_IO_NEXTCHORD>...
    )

"ncsq" チャンクには、接続グラフのコードを別のコードに接続するデータが含まれる。接続グラフの各コードは、16 ビットの識別子で表される。

<spsq-list> -> LIST( 'spsq'
<spst-list>...
    )

"spsq" リストには、サインポストそれぞれのデータが含まれる。

<spst-list>  ->  LIST( 'spst'
<spsh-ck>
<chrd-list>  // コード データ。上の説明を参照。
[ <cade-list> ]
    )

"spst" リストには、1 つのサインポストのデータが含まれる。データは、ヘッダー、コード情報、およびオプションのカデンツァ コードで構成される。

<cade-list> -> LIST( 'cade'
<chrd-list>...
    )

"cade" リストには、カデンツァ コードの情報が含まれる。現在、このリストでは 2 つまでのカデンツァ コードがサポートされている。その他の追加コードや情報は無視される。

<spsh-ck> -> spsh(
<DMUS_IO_CHORDMAP_SIGNPOST>
)

最後に、"spsh" チャンクにはサインポスト データが含まれる。


セグメント形式

次の表記法は、セグメント ファイルの最上位レベルのチャンクの構成を示している。

RIFF( 'DMSG'
<segh-ck>       // セグメント ヘッダー チャンク
[<guid-ck>]     // セグメントの GUID
[<vers-ck>]     // オプションのバージョン情報
[<UNFO-list>]   // 名前、作者、著作権情報、コメント
<trkl-list>     // トラックのリスト
[<DMTG-form>]   // オプションのツール グラフ
    )

個々のチャンクおよびそのサブチャンクの詳細は、次のとおりである。

<segh-ck> -> segh( <DMUS_IO_SEGMENT_HEADER> )

このチャンクには、セグメントの基本的なヘッダー情報が含まれる。次の 3 つのチャンクについては、「共通のチャンク」を参照すること。

次のチャンクはトラック リストである。各トラックは、トラック形式にカプセル化される。

<trkl-list> -> LIST( 'trkl'
<DMTK-form>...
    )

最後に、セグメント形式にはツール グラフ形式を含めることができる。


スタイル形式

次の表記法は、スタイル ファイルの最上位レベルのチャンクの構成を示している。

RIFF( 'DMST'
<styh-ck>       // スタイル ヘッダー チャンク
<guid-ck>       // 一意の識別子
[<UNFO-list>]   // 名前、作者、著作権情報、コメント
[<vers-ck>]     // バージョン チャンク
<part-list>...// パターンで使用される、スタイル中のパートのリスト
<pttn-list>...// スタイル中のパターンのリスト
<DMBD-form>...// スタイル中のバンドのリスト
[<motf-list>]   // スタイル中のモチーフのリスト
[<prrf-list>]   // スタイル中のコード マップ参照のリスト
)

個々のチャンクおよびそのサブチャンクの詳細は、次のとおりである。

<styh-ck> -> styh( <DMUS_IO_STYLE> )

このチャンクには、スタイルの基本的なヘッダー情報が含まれる。次の 3 つのチャンクについては、「共通のチャンク」を参照すること。

次のチャンクは、スタイルの各ミュージック パートのチャンクである。

<part-list> -> LIST('part'
<prth-ck>       // パート ヘッダー チャンク
[<UNFO-list>]
[<note-ck>]     // パートの音符のリスト
[<crve-ck>]     // パートの曲線のリスト
    )

上の例に示すように、パート リストにはヘッダー、オプションの UNFO チャンク、および音符と曲線のリストが含まれる (UNFO リストについては、「共通のチャンク」を参照すること)。

<prth-ck> -> prth( <DMUS_IO_STYLEPART> )

<note-ck> -> note(
< DWORD >  // DMUS_IO_STYLENOTE のサイズ
< DMUS_IO_STYLENOTE >...
    )

<crve-ck> -> crve(
< DWORD >  // DMUS_IO_STYLECURVE のサイズ
< DMUS_IO_STYLECURVE >...
    )

パート リスト チャンクの次は、パターン リスト チャンクである。

<pttn-list> -> LIST( 'pttn'
<ptnh-ck>       // パターン ヘッダー チャンク
<rhtm-ck>       // コード マッチング用のリズムのリスト
[<UNFO-list>]
[<mtfs-ck>]     // モチーフ設定チャンク
<pref-list>...// パート参照 ID のリスト
    )

パターン リストは、次のサブチャンクで構成される (オプションの UNFO リストについては、「共通のチャンク」を参照すること)。

<ptnh-ck> -> ptnh(
< DMUS_IO_PATTERN >
    )

<rhtm-ck> -> rhtm(
< DWORD >...
    )

このチャンクは、各小節ごとに 1 つの DWORD 配列で構成され、リズム パターンを表す。ビットの配置については、DMUS_RHYTHM_PARAM の dwRhythmPattern メンバを参照すること。

<mtfs-ck> -> mtfs(
< DMUS_IO_MOTIFSETTINGS >
    )

<pref-list> -> LIST( 'pref'
<prfc-ck>   // パート参照チャンク
    )

続いて、"pref" チャンクはパート参照の配列で構成される。

<prfc-ck> -> prfc(
< DMUS_IO_PARTREF >
    )

スタイル形式の最後のチャンクは、コード マップ参照のリストである。

<prrf-list> -> LIST( 'prrf'
<DMRF-list>...
    )

<DMRF-list> の詳細については、「共通のチャンク」を参照すること。


ツール形式

ツール形式には、ツールに関する情報が含まれる。ツールは、ツール グラフ形式に埋め込むか、別のファイルに格納することができる。

<DMTL-form> -> RIFF( 'DMTL'
<tolh-ck>
[<guid-ck>]     // ツール オブジェクト インスタンスの GUID
[<vers-ck>]     // バージョン情報
[<UNFO-list>]   // 名前、作者、著作権情報、コメント
[<data>]        // ツール データ
)

ツール ヘッダー チャンクは次のとおりである。

<tolh-ck> -> tolh( <DMUS_IO_TOOL_HEADER> )

次の 3 つの要素はオプションである。「共通のチャンク」を参照すること。

<data> 要素は、DMUS_IO_TOOL_HEADER で識別されるタイプのチャンクで構成される。このチャンクの形式は、ツールの定義によって異なり、リストまたはチャンクとなる。


ツール グラフ形式

ツール グラフ チャンクは、最上位レベルの形式、またはセグメント形式のサブチャンクとして記述される。

RIFF( 'DMTG'
[<guid-ck>]     // ツール グラフの GUID
[<vers-ck>]     // オプションのバージョン情報
[<UNFO-list>]   // 名前、作者、著作権情報、コメント
<toll-list>     // ツールのリスト
)

最初の 3 つの要素はオプションである。「共通のチャンク」を参照すること。

ツール グラフ チャンクの主要な部分であり、唯一必要となるのは、ツール リストである。

<toll-list> -> LIST( 'toll'
<DMTL-form>...
    )

<DMTL-form> チャンクの詳細については、「ツール形式」を参照すること。


トラック形式

トラック形式には、1 つのトラックに関する情報が含まれる。この形式は、セグメント形式に埋め込むか、独自のファイルに格納することができる。

<DMTK-form> -> RIFF( 'DMTK'
<trkh-ck>
[<guid-ck>]     // トラック オブジェクト インスタンスの GUID
[<vers-ck>]     // バージョン情報
[<UNFO-list>]   // 名前、作者、著作権情報、コメント
[<data>]        // トラック データ
)

サブチャンクの詳細は次のとおりである。

<trkh-ck> -> trkh(
<DMUS_IO_TRACK_HEADER>
    )

このチャンクには、トラックの基本的なヘッダー情報が含まれる。

次の 3 つの要素はオプションである。「共通のチャンク」を参照すること。

トラック形式の最後の要素は、トラックのデータである。データで使用されるチャンクの種類は、DMUS_IO_TRACK_HEADER 構造体で識別される。標準的なトラック チャンクは、次のように定義されている。

  • バンド トラック形式
  • コード トラック リスト
  • コード マップ トラック リスト
  • コマンド トラック チャンク
  • ミュート トラック チャンク
  • シーケンス トラック リスト
  • サインポスト トラック チャンク
  • スタイル トラック リスト
  • システム エクスクルーシブ トラック チャンク
  • テンポ トラック チャンク
  • 拍子記号トラック チャンク


DLS の使い方

ここでは、DirectMusic でのダウンロードダブル サウンド (DLS) の使い方について説明する。DLS の概要は、「ダウンローダブル サウンド」を参照すること。

ほとんどのアプリケーションは音色やダウンロードダブル サウンドを直接扱う必要がない。コレクションを開いたり、音色データをダウンロードする処理は、バンド オブジェクトによって実行される。バンドをダウンロードすると、そのバンドに関連付けられているすべての音色データもダウンロードされる。詳細については、「バンドの使い方」を参照すること。

[C++]

独自の DLS 管理を行う特別な DirectMusic アプリケーションでは、2 つのステップを実施しなければならない。最初に音色コレクションをロードし、次に音色データをポートにダウンロードする。

次のトピックで、これらのステップについて取り上げる。

  • コレクションのロード
  • 音色の操作
  • カスタム音色による MIDI ファイルの演奏

音色とコレクションを編集するアプリケーションでは、より低いレベルでも DLS データを操作できなければならない。詳細については、次のトピックを参照すること。

  • 下位レベル DLS
[Visual Basic]

コレクションの操作の詳細については、次のトピックを参照すること。

  • コレクションのロード
  • カスタム音色による MIDI ファイルの演奏


コレクションのロード

[C++]

ファイルからコレクションをロードする最も簡単な方法は、IDirectMusicLoader インターフェイスを使うことである (詳細については、「ファイルからのオブジェクトのロード」を参照すること)。IDirectMusicCollection インターフェイスへのポインタを取得すると、コレクション内のすべての音色にアクセスできる。ただし、この時点では、実際には音色はポートにダウンロードされていない。音色データは、必要になるまでメモリにロードされない。

コレクションは、IDirectMusicCollection、IDirectMusicObject、IPersistStream の各インターフェイスをサポートする COM オブジェクトである。IPersistStream は、標準的な COM インターフェイスであり、記憶の目的で単純なシリアル ストリームを使って、オブジェクトの保存とロードを行うメソッドを提供する。

IPersistStream::Load を呼び出した時点では、IDirectMusicCollection はコレクション全体をロードすることはない。通常、IPersistStream をサポートするオブジェクトは永続的なデータすべてをストリームにロードし、Load メソッドの外部で IStream ポインタを使わない。しかし、IDirectMusicCollection 内でこの方法により IPersistStream::Load をサポートすると、コレクション内のただ 1 つの音色を使う場合でも、DLS コレクション全体をメモリにロードしなければならない。代わりに、IDirectMusicCollection は IStream ポインタを保存し、後でそのポインタを使って、DirectMusic のポートにダウンロードすべき音色のデータをロードする。IDirectMusicCollection は、IPersistStream インターフェイス経由で提供されるデータ ストリームが DLS ファイル形式であると想定している。

次のコード例では、IDirectMusicLoader::GetObject メソッドが自動的に実行する処理を、手作業で行っている。コレクション オブジェクトを作成し、ストリームをそのオブジェクトにロードする。

HRESULT myLoadCollectionFromStream(
        IStream *pIStream,    // ファイルから作成したストリーム
        IDirectMusicCollection **ppICollection )

{
    HRESULT hr;

    hr = CoCreateInstance(CLSID_DirectMusicCollection,
                          NULL,
                          CLSCTX_INPROC,
                          IID_IDirectMusicCollection,
                          (void **)ppICollection);
    if (SUCCEEDED(hr))
    {
        IPersistStream* pIPersistStream;
        hr = *ppICollection->QueryInterface(
                IID_IPersistStream, (void**)&pIPersistStream);
        if (SUCCEEDED(hr))
        {
            hr = pIPersistStream->Load(pIStream);
            pIPersistStream->Release();
        }
    }
    return hr;
}

次のコード例では、DirectMusicLoader を使って、ファイル名を指定してコレクションをロードしている。

HRESULT myLoadCollectionByName(
        IDirectMusicLoader *pILoader,
        char *pszFileName,
        IDirectMusicCollection **ppICollection)
{
    HRESULT hr;
    DMUS_OBJECTDESC Desc;             // ディスクリプタ

    // 最初にファイル名とコレクション オブジェクトの GUID を
    // 指定して、Desc を初期化する。
    // ファイル名は最初、char 文字列になっているので、
    // Unicode に変換する。

    mbstowcs(Desc.wszFileName,pszFileName,DMUS_MAX_FILENAME);
    Desc.dwSize = sizeof(DMUS_OBJECTDESC);
    Desc.guidClass = CLSID_DirectMusicCollection;
    Desc.dwValidData = DMUS_OBJ_CLASS
            | DMUS_OBJ_FILENAME
            | DMUS_OBJ_FULLPATH;

    hr = pILoader->GetObject(&Desc,
            IID_IDirectMusicCollection,
            (void **) ppICollection);
    return hr;
}

標準的な GM/GS セットをロードするために、DMUS_OBJECTDESC 構造体の guidObject メンバに、ローダーへのパス GUID_DefaultGMCollection を設定する。ローダーを使ってこのオブジェクトに何度もアクセスする場合は、キャッシングが有効になっていることを確認し (デフォルトの設定)、GM コレクションを要求するたびにコピーが 1 つ作成されることを防止する。

注 : GM/GS Sound Set を変更することはできない。詳細については、「法的情報」の「著作権に関する注意」を参照すること。

次のコード例は、GUID によって識別されるコレクションをロードする方法を示している。

HRESULT myGetGMCollection(
        IDirectMusicLoader *pILoader,
        IDirectMusicCollection **ppICollection)
{
    HRESULT hr;
    DMUS_OBJECTDESC desc;

    desc.dwSize = sizeof(DMUS_OBJECTDESC);
    desc.guidClass = CLSID_DirectMusicCollection;
    desc.guidObject = GUID_DefaultGMCollection;
    desc.dwValidData = (DMUS_OBJ_CLASS | DMUS_OBJ_OBJECT);
    hr = pILoader->GetObject(&desc, IID_IDirectMusicCollection,
            (void **) ppICollection);
    return hr;
}
[Visual Basic]

音色コレクションをロードするには、DirectMusicLoader.LoadCollection または DirectMusicLoader.LoadCollectionFromResource メソッドを呼び出す。これらのメソッドは、DirectMusicCollection オブジェクトを返す。このオブジェクトにはメソッドがなく、DirectMusicSegment.ConnectToCollection へのパラメータとしてのみ機能する。このメソッドを呼び出してコレクションをセグメントに関連付けた後、DirectMusicSegment.Download を呼び出して音色をダウンロードする。

これらの手順は、デフォルト以外のコレクションを使用する場合にのみ必要となる。セグメントにカスタム コレクションが含まれていない場合、またはセグメントが MIDI ファイルの場合、通常は DirectMusicSegment.Download を呼び出すときに、セグメント中にオーサリングされたデフォルト コレクションの音色、またはGeneral MIDI セットの音色がポートにダウンロードされる。バンドをダウンロードするときに、そのバンドの音色で必要なすべての DLS データがダウンロードされる。「バンドの使い方」を参照すること。


音色の操作

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、アプリケーションがコレクションの個々の音色を操作することはできない。

[C++]

DirectMusicCollection を作成してコレクション ファイルからロードした後、IDirectMusicCollection::EnumInstrument メソッドを使って、利用可能なすべての音色のパッチ番号と名前を取り出せる。

次のコード例では、コレクション内のすべての音色を列挙し、その名前とパッチ番号を表示している。

void myListInstruments(
        IDirectMusicCollection *pCollection)

{
    HRESULT hr = S_OK;
    DWORD dwPatch;
    WCHAR wszName[MAX_PATH];
    DWORD dwIndex;
    for (dwIndex = 0; hr == S_OK; dwIndex++)
    {
        hr = pCollection->EnumInstrument(
                dwIndex, &dwPatch, wszName, MAX_PATH);
        if (hr == S_OK)
        {
           printf("パッチ %lx は、%S。\n",dwPatch,wszName);
        }
    }
}

IDirectMusicCollection::GetInstrument メソッドに特定の音色のパッチ番号を渡すことにより、その音色へのポインタを取得できる。

音色を取得した後、IDirectMusicInstrument::SetPatch メソッドを使ってパッチ番号を変更できる。

コレクションをロードし、音色を取り出す作業は、音色を利用可能にするための最初のステップに過ぎない。次に、これらの音色をポートにダウンロードしなければならない。

音色をポートにダウンロードするには、IDirectMusicInstrument インターフェイス ポインタを IDirectMusicPort::DownloadInstrument メソッドに渡す。このメソッドは、ポートで DLS データを利用可能にする。音色を特定のパフォーマンスに関連付けることはない。

IDirectMusicPerformance::DownloadInstrument メソッドを使って、音色をダウンロードすることもできる。DLS データのダウンロードに加えて、このメソッドは音色を特定のパフォーマンス チャンネルに割り当てる。

メモリを節約するために、指定された音符の範囲で必要なウェーブとアーティキュレーションだけがダウンロードされる。たとえば、バスーンを使う場合、低音の C から中間の B までの音符範囲に相当するデータだけをダウンロードするよう指定することがある。その範囲内のリージョン のデータだけをダウンロードすべきである。

次のコード例では、指定されたコレクション、パッチ番号、ポート、および音符範囲に対して、コレクションから音色を取り出し、その音色をダウンロードしている。この関数は、1 つの DMUS_NOTERANGE 構造体からなる配列を作成し、この配列を IDirectMusicPort::DownloadInstrument メソッドに渡す。一般的には、音符の 1 つの範囲だけを指定するが、複数の範囲を指定することもできる。配列へのポインタの代わりに NULL を渡すと、すべての範囲のデータがダウンロードされる。

HRESULT myDownload(
    IDirectMusicCollection *pCollection,    // DLS コレクション
    IDirectMusicPort *pPort,                // ダウンロード先ポート
    IDirectMusicDownloadedInstrument **ppDLInstrument,
    DWORD dwPatch,                          // 要求された音色
    DWORD dwLowNote,                        // 音符範囲の下限の音符
    DWORD dwHighNote)                       // 音符範囲の上限の音符

{
    HRESULT hr;
    IDirectMusicInstrument* pInstrument;
    hr = pCollection->GetInstrument(dwPatch, &pInstrument);
    if (SUCCEEDED(hr))
    {
        DMUS_NOTERANGE NoteRange[1];         // オプションの音符範囲
        NoteRange[0].dwLowNote = dwLowNote;
        NoteRange[0].dwHighNote = dwHighNote;
        hr = pPort->DownloadInstrument(pInstrument,
                ppDLInstrument,
                NoteRange,   // 範囲の配列
                1);          // 配列内の要素数
        pInstrument->Release();
    }
    return hr;
}

Download メソッドは、IDirectMusicDownloadedInstrument インターフェイスへのポインタを返す。このポインタの目的は、それ以降に IDirectMusicPort::UnloadInstrument メソッドを呼び出すときに音色を識別することだけであり、このメソッドは特定のポートから音色インスタンスをアンロードする (DirectMusicCollection は、特定のポートにバインドされない。異なる音色を異なるポートにダウンロードすることも、1 つの音色を複数のポートにダウンロードすることもできる)。

次のコード例では、音色をダウンロードした後、アンロードしている。この例は、IDirectMusicDownloadedInstrument ポインタの使用方法を示している。

HRESULT myFickleDownload(
        IDirectMusicInstrument* pInstrument,
        IDirectMusicPort *pPort,
        DWORD dwPatch)

{
    HRESULT hr;
    IDirectMusicDownloadedInstrument * pDLInstrument;
    hr = pPort->DownloadInstrument(
            pInstrument, &pDLInstrument,
            NULL, 0);
    if (SUCCEEDED(hr))
    {
        pPort->UnloadInstrument(pDLInstrument);
        pDLInstrument->Release();
    }
    return hr;
}

IDirectMusicBand::Download メソッドは、バンド内のすべての音色を自動的にダウンロードする。開発者がパフォーマンスへのポインタを渡すだけで、このメソッドはそのパフォーマンスに付加された適切なポートに各音色をダウンロードする。


カスタム音色による MIDI ファイルの演奏

MIDI ファイルを演奏する場合、デフォルトでは、Gm.dls ファイルに含まれる Roland GM/GS Sound Set の音色が使用される。ただし、ほかのコレクションの音色を使って MIDI ファイルを演奏することもできる。

[C++]

ほかのコレクションの音色を使って MIDI ファイルを演奏するには、最初に、「コレクションのロード」で説明した方法でコレクションをロードし、IDirectMusicCollection インターフェイスへのポインタを取得する。続いて、MIDI セグメントに対して IDirectMusicSegment::SetParam を呼び出し、セグメントとコレクションの接続を確立する。

次のコード例は、接続の作成方法を示している。

/* pSegment は MIDI ファイルから作成され、
pLoadedCollection は有効な IDirectMusicCollection
ポインタであるとする。*/

HRESULT hr = pSegment->SetParam(GUID_ConnectToDLSCollection,
0xFFFFFFFF, 0, 0,
(void*)pLoadedCollection);

ほかのコレクションの場合と同様に、自動ダウンロードが有効でない場合は、MIDI ファイルの演奏に使用する音色を、セグメントを演奏する前にダウンロードしなければならない (自動ダウンロードの詳細については、「グローバル パラメータの設定と取り出し」および「バンドのダウンロードとアンロード」を参照すること)。音色が自動的にダウンロードされない場合は、次のコード例に示すように、IDirectMusicSegment::SetParam を呼び出して音色をダウンロードしなければならない。

/* pSegment は IDirectMusicSegment ポインタであり、pPerformance は
IDirectMusicPerformance への有効なポインタである。*/

pSegment->SetParam(GUID_Download, 0xFFFFFFFF, 0, 0, (void *) pPerformance);

SetParam を使ったダウンロードの詳細については、「トラック パラメータの設定と取り出し」を参照すること。

[Visual Basic]

ほかのコレクションの音色を使って MIDI ファイルを演奏するには、MIDI ファイルに基づいて、コレクションをロードし、セグメントに関連付ける。次に、ほかのセグメントの場合と同様に、コレクションをダウンロードする。詳細については、「コレクションのロード」を参照すること。

注 : MIDI セグメントにカスタム コレクションを付加するときに、GM コレクションへの接続は破壊されない。たとえば、パッチ番号が 12 の 1 つの音色を含むコレクションをロードし、これをセグメントに接続する場合、12 以外のパッチ番号を持つ MIDI チャンネルでは、GM コレクションの適切な音色を使って演奏が続けられる。


下位レベル DLS

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、下位レベルでの DLS データの操作はサポートされていない。

[C++]

DLS コレクションを編集する DirectMusic アプリケーションを作成している場合は、DirectMusicInstrument オブジェクトにカプセル化することなく、音色データをシンセサイザにダウンロードできなければならない。

DLS データを操作するには、DLS の仕様およびファイル構造についての知識が必要となる。これらの情報の詳細については、MIDI Manufactures Association に問い合わせること。

未加工の音色データをダウンロードするには、最初に、次のコード例のように IDirectMusicPortDownload インターフェイスへのポインタを取得する必要がある。ここでは、pIPort が IDirectMusicPort インターフェイスへの有効なポインタであることを想定している。

IDirectMusicPortDownload **ppIDownloadPort;

HRESULT hr = pIPort->QueryInterface(IID_IDirectMusicPortDownload,
        (void **) ppIDownloadPort);

HRESULT が S_OK ではない場合、そのポートは DLS ダウンロードをサポートしていない。

次に、準備およびダウンロードしなければならないバッファを識別する。音色をシンセサイザに送信するには、音色全体の定義を表し、すべてのリージョンとアーティキュレーションを備えた 1 つの音色バッファと、一連のウェーブ バッファを作成する。音色がリージョン用に参照する 1 つのウェーブにつき、1 つのウェーブ バッファを作成する。

各バッファには、固有の識別子を付けなければならない。これらの識別子を使ってバッファ間のリンク、特にリージョンとウェーブのリンクを解決する。ダウンロードする必要のあるバッファ数を集計し、IDirectMusicPortDownload::GetDLId を呼び出して、識別子の範囲を割り当てる。たとえば、1 つの音色を 3 つのウェーブと一緒にダウンロードする場合、全部で 4 つのバッファをダウンロードしなければならない。したがって、4 つの識別子のセットを要求する。

バッファごとに必要なサイズを計算し、次に IDirectMusicPortDownload::AllocateBuffer を呼び出してそのサイズを割り当てる。このメソッドは、そのバッファを表す IDirectMusicDownload インターフェイスを返す。メモリにアクセスするには、IDirectMusicDownload::GetBuffer を呼び出す。

注 : GetBuffer メソッドは 2 つある。

IDirectMusicPortDownload::GetBuffer は、ダウンロード識別子が既知のバッファ オブジェクトに対する IDirectMusicDownload インターフェイス ポインタを返す。

IDirectMusicDownload::GetBuffer は、バッファのメモリへのポインタを返す。

今度はデータを各バッファに書き込む。各バッファは DMUS_DOWNLOADINFO 構造体によって指定された場所で始まる。この構造体は、サイズとダウンロードの機能を定義する。この構造体は、次の方法で準備しなければならない。

  • dwDLType メンバを、音色の場合は DMUS_DOWNLOADINFO_INSTRUMENT に、ウェーブの場合は DMUS_DOWNLOADINFO_WAVE に設定する。
  • dwDLId メンバを、IDirectMusicPortDownload::GetDLId を実行して取得した、固有の識別子のいずれかに設定する。
  • dwNumOffsetTableEntries メンバを、DMUS_OFFSETTABLE 構造体内のエントリ数に設定する。
  • cbSize メンバを、DMUS_DOWNLOADINFO および DMUS_OFFSETTABLE を含む、ダウンロード チャンクのサイズに設定する。

DMUS_DOWNLOADINFO 構造体は、常に DMUS_OFFSETTABLE 構造体に従う。このオフセット テーブルを使って、データ内のすべてのリンクを管理する。データ内の構造体が他の構造体を参照する場合はいつでも、ポインタではなく整数のインデックス番号を使う。データ内にある参照可能なすべての構造体には、一意のインデックス番号が割り当てられている。DMUS_OFFSETTABLE は、この整数インデックス番号をデータ内のバイト オフセットに変換する。

音色データまたはウェーブデータは、DMUS_OFFSETTABLE に従う。音色をダウンロードする場合は、DMUS_INSTRUMENT 構造体で指定された場所からデータが始まる。それ以外のものをダウンロードする場合は、DMUS_WAVE 構造体で指定された場所からデータが始まる。

DMUS_INSTRUMENT 構造体に従う音色データは、次の構造体で構成される。

  • DMUS_ARTICPARAMS
  • DMUS_ARTICULATION
  • DMUS_COPYRIGHT
  • DMUS_EXTENSIONCHUNK
  • DMUS_INSTRUMENT
  • DMUS_NOTERANGE
  • DMUS_REGION

DMUS_WAVE 構造体で示されるウェーブ データは、DMUS_WAVEDATA 構造体で構成される。

バッファすべてが準備できている場合、IDirectMusicPortDownload::Download を使ってそれらをダウンロードする。最初にウェーブ バッファをダウンロードすること。その結果ウェーブ バッファが適切な場所に配置され、音色をダウンロードするときに参照できる。

バッファをダウンロードすると、シンセサイザは音色を演奏できる状態になる。バッファをダウンロードした後、そのバッファで使われているメモリにはアクセスできなくなる。

その後、音色の演奏が終了したら、バッファのアンロードと解放を行う。最初に音色バッファをアンロードし、次にすべてのウェーブ バッファをアンロードする。アンロードを行うには、IDirectMusicPortDownload::Unload を呼び出し、IDirectMusicDownload オブジェクトを渡す。次に、IDirectMusicDownload::Release を呼び出して、各バッファを解放する。

既にダウンロードされている音色を更新する場合、ダウンロード済みのバッファの上書きはできない。代わりに、ウェーブではなく音色を置き換える。音色を置き換えるには、IDirectMusicPortDownload::AllocateBuffer を呼び出し、適切なバッファ サイズを指定して新しい IDirectMusicDownload インターフェイスを割り当てる。IDirectMusicPortDownload::GetDLId を呼び出して、バッファの新しい識別子を生成すること。新しいアーティキュレーション情報をバッファに書き込み、次にバッファをダウンロードする。続いて、IDirectMusicPortDownload::Unload を呼び出して、以前にダウンロードされていたバッファをアンロードする。

ウェーブ バッファを更新する場合は、もう 1 つステップが増える。新しいウェーブ バッファと、そのバッファを参照する更新された音色バッファの 2 つを作成する。新しいウェーブ バッファ、次いで新しい音色バッファをダウンロードする。さらに古い音色バッファ、次いで古いウェーブ バッファをアンロードする。


音楽の演奏

ここでは、DirectMusic のパフォーマンスの基本的な要素と、ソースからミュージック データを取得して出力するために必要となる重要なメソッドを紹介する。

次の項目について説明する。

  • パフォーマンスの作成
  • セグメント
  • トラック
  • バンドの使い方
  • タイミング
  • 通知とイベントの処理


パフォーマンスの作成

[C++]

音楽の再生は、パフォーマンス オブジェクトによって管理される。パフォーマンス オブジェクトは、ソースから音楽を取り出して出力バッファに送るまでの、ほとんどの作業を処理する。パフォーマンス オブジェクトは、次のタスクを実行する。

  • ポートの追加
  • チャンネルへの音色の割り当て
  • シンセサイザへの音色のダウンロード
  • セグメントの演奏と停止
  • メッセージのディスパッチ
  • ツールとタイミングの管理

ほとんどのアプリケーションは、DirectMusicPerformance オブジェクトを 1 つだけ使用するが、マスタ テンポやボリュームなどのパラメータの異なる複数のパフォーマンスを使用することもできる。

次のコード例では、パフォーマンスを 1 つ作成して、IDirectMusicPerformance インターフェイスへのポインタを取得している。

IDirectMusicPerformance* pPerf;

if (FAILED(CoCreateInstance(
        CLSID_DirectMusicPerformance,
        NULL,
        CLSCTX_INPROC,
        IID_IDirectMusicPerformance,
        (void**)&pPerf
    )))
{
    pPerf = NULL;
}

作成したパフォーマンスは初期化しなければならない。初期化における重要な処理は、DirectMusic オブジェクトの作成である。CoCreateInstance に CLSID_DirectMusic を渡し、次に IDirectMusicPerformance::Init に IDirectMusic インターフェイス ポインタを渡すと、DirectMusic オブジェクトを作成することができる。ただし、多くの場合は、Init を使って DirectMusic オブジェクトを作成した方がより簡単である。ポートおよびマスタ クロックに対して必要な制御の程度に応じて、IDirectMusic インターフェイスへのポインタを取得するかどうかを選択することもできる。デフォルトのシンセサイザおよびデフォルトのマスタ クロックのみを使う場合は、通常、IDirectMusic のメソッドにアクセスする必要はない。この場合は、Init に NULL を渡す。

次のコード例では、パフォーマンスを初期化して、IDirectMusic へのポインタを取得し、アプリケーション ウィンドウ ハンドルで初期化された IDirectSound インターフェイスを作成している。

IDirectMusic* pDirectMusic;

if (SUCCEEDED(pPerf->Init(&pDirectMusic,
NULL,     // DirectSound オブジェクトの作成
hWnd      // アプリケーション ウィンドウ ハンドル
        )))
{
// パフォーマンスの初期化
}
[Visual Basic]

音楽の再生は、パフォーマンス オブジェクトによって管理される。パフォーマンス オブジェクトは、ソースから音楽を取り出して出力バッファに送るまでの、ほとんどの作業を処理する。パフォーマンス オブジェクトは、次のタスクを実行する。

  • ポートの列挙とアクティブ ポートの設定
  • セグメントの演奏と停止
  • メッセージのディスパッチ
  • タイミングの管理

ほとんどのアプリケーションは、DirectMusicPerformance オブジェクトを 1 つだけ使用するが、マスタ テンポやボリュームなどのパラメータが異なっていたり、異なるポートで演奏を行う複数のパフォーマンスを使用することもできる。

次のコード例では、独自の DirectSound オブジェクトと共にパフォーマンスを作成し、これを初期化して、1 つのチャンネル グループでデフォルト ポートを使うように設定している。objDX は DirectX7 オブジェクトを表す。

Dim objDMPerformance as DirectMusicPerformance

Set objDMPerformance = objDX.DirectMusicPerformanceCreate
Call objDMPerformance.Init(Nothing, 0)
Call objDMPerformance.SetPort(-1, 1)

パフォーマンスの設定の詳細については、「DirectMusic と DirectSound の統合」および「ポートの使い方」を参照すること。


セグメント

[C++]

DirectMusic 内のデータの基本チャンクをセグメントと呼ぶ。セグメントは IDirectMusicSegment インターフェイスによって表される。セグメントは、次のいずれかの方法で作成することができる。

  • IDirectMusicSegment インターフェイスをサポートするファイルまたはリソース オブジェクトをロードする。詳細については、「DirectMusic ローダー」を参照すること。
  • IDirectMusicStyle::GetMotif メソッドを使って、スタイルからモチーフを取得する。
  • IDirectMusicComposer インターフェイスのメソッドを使って、実行時にアレンジまたは移行部を作成する。「アレンジ用のプログラミングの概要」および「移行部の使い方」を参照すること。
  • IDirectMusicSegment::Clone メソッドを使って、既存のセグメントのコピーを作成する。
  • 既存のトラックからセグメントを構築する。CoCreateInstance を呼び出してセグメント オブジェクトを作成し、次に IDirectMusicSegment::InsertTrack を呼び出してトラックを追加する。
  • IDirectMusicBand::CreateSegment メソッドを使用する。このメソッドにより、バンド チェンジの作成にだけ使用される、特殊なセカンダリ セグメントが作成される。「プログラム的なバンド チェンジの実行」を参照すること。

各セグメントは 1 つまたは複数のトラックによって構成され、各トラックは IDirectMusicTrack インターフェイスによって表される。トラックは、セグメントのデータのほとんどを保持し、データは、音符イベント、バンド チェンジ、テンポ チェンジ、またはその他のタイム イベントで構成される。トラックはセグメント オブジェクトを通して管理されるため、アプリケーションは一般的にこれらのインターフェイスを必要としない。詳細については、「トラック」を参照すること。

[Visual Basic]

DirectMusic 内のデータの基本チャンクをセグメントと呼ぶ。各セグメントは DirectMusicSegment オブジェクトによって表される。セグメントは、次のいずれかの方法で作成することができる。

  • DirectMusicLoader.LoadSegment または DirectMusicLoader.LoadSegmentFromResource メソッドを使って、DirectMusicSegment クラスをサポートするファイルまたはリソース オブジェクトをロードする。詳細については、「DirectMusic ローダー」を参照すること。
  • DirectMusicStyle.GetMotif メソッドを使って、スタイルからモチーフを取得する。
  • DirectMusicComposer クラスのメソッドを使って、実行時にアレンジまたは移行部を作成する。「アレンジ用のプログラミングの概要」および「移行部の使い方」を参照すること。
  • DirectMusicSegment.Clone メソッドを使って、既存のセグメントのコピーを作成する。
  • DirectMusicBand.CreateSegment メソッドを使用する。このメソッドにより、バンド チェンジにのみ使用される、特殊なセカンダリ セグメントが作成される。「プログラム的なバンド チェンジの実行」を参照すること。

セグメントはさまざまな目的を果たす。次に、使用する頻度の高いセグメントを示す。

  • プライマリ セグメント。MIDI ファイル、DirectMusic Producer でオーサリングされたセグメント、コンポーザ オブジェクトによって実行時に作成されるセグメントなどの、ミュージック ピース。
  • モチーフ セグメント。非同期的に演奏される短いミュージック ピース。モチーフはスタイル オブジェクトの一部であるが、ほかのソースから短いセカンダリ セグメントを作成し、モチーフのようにプライマリ セグメントに重ねて演奏することもできる。
  • バンド セグメント。パフォーマンス内のさまざまなチャンネル用の一連の音色および音色セグメント。アプリケーションはバンド セグメントを演奏し、音楽を演奏するバンドに変更を加えることができる。
  • テンプレート セグメント。コード進行、グルーブ レベル、および装飾などのガイドとして、実行時にスタイルやコード マップと共に組み合わされ、音楽を形成する。ほかのセグメントとは異なり、アプリケーションがテンプレート セグメントを直接演奏することは決してない。代わりに、テンプレート セグメントはコンポーザ オブジェクトに渡され、ミュージック セグメントの作成に使用される。
[C++]

セグメントの再生は、IDirectMusicPerformance インターフェイスで制御され、IDirectMusicPerformance::PlaySegment の呼び出しで開始される。セグメントの演奏インスタンスは IDirectMusicSegmentState インターフェイスによって表され、このインターフェイスを使ってセグメントの現在の状態に関する情報を取り出せる。

[Visual Basic]

セグメントの再生は、DirectMusicPerformance オブジェクトで制御され、DirectMusicPerformance.PlaySegment の呼び出しで開始される。再生するセグメントのインスタンスは DirectMusicSegmentState オブジェクトで表され、このオブジェクトを使ってセグメントの現在の状態に関する情報を取り出せる。

パフォーマンス内では、ただ 1 つのプライマリ セグメントを演奏できる。再生の目的でプライマリ セグメントを挿入する場合は、現在演奏されているセグメントが終わった後にそのセグメントを演奏するように指定したり、現在のプライマリ セグメントを置き換えることができる。

一方、セカンダリ セグメントはプライマリ セグメント上で演奏され、任意の数のセカンダリ セグメントを同時に演奏できる。

通常、セカンダリ セグメントはプライマリ セグメントのパフォーマンスを変更しない。たとえば、セカンダリ セグメントは、プライマリ セグメントのスタイルに影響を与えずに、別のスタイルに基づくことができる。

[C++]

ただし、セカンダリ セグメントは制御セグメントとして指定することができる。この場合、通常はプライマリ セグメントで処理される IDirectMusicPerformance::SetParam および IDirectMusicPerformance::GetParam 呼び出しに応答するタスクが、セカンダリ セグメントによって奪われる。このように、制御セグメントによって、現在のコードまたはグルーブ レベルが管理される場合がある。詳細については、「トラック」を参照すること。

セカンダリ セグメントを制御セグメントとして演奏する方法の詳細については、DMUS_SEGF_FLAGS を参照すること。

[Visual Basic]

ただし、セカンダリ セグメントは制御セグメントとして指定することができる。この場合、セカンダリ セグメントは DirectMusicPerformance.GetCommand などの特定の呼び出しに応答するタスクを実行し、現在のコードやグルーブ レベルなど、音楽のいくつかの面を制御する。

セカンダリ セグメントを制御セグメントとして演奏する方法の詳細については、CONST_DMUS_SEGF_FLAGS を参照すること。

セグメントの再生の詳細については、「セグメントのタイミング」を参照すること。


トラック

トラックはセグメントのコンポーネントで、シーケンス化されたデータが含まれる。データには、音符、基調コード、テンポ、パッチ チェンジ、バンド チェンジ、およびパフォーマンスが音楽のピースを演奏するときに知っておく必要がある、その他すべてに関する情報が含まれる。

[Visual Basic]

DirectX for Visual Basic では、個々のトラックにアクセスできるアプリケーションは提供されない。再生はすべて、セグメント レベルで処理される。

[C++]

各トラックは、IDirectMusicTrack インターフェイスによって表される。このインターフェイスのメソッドはパフォーマンスによって呼び出され、ほとんどのアプリケーションでは、直接使用する必要はない。

アプリケーションが IDirectMusicPerformance::PlaySegment を呼び出すときに、DirectMusic はセグメントのトラックに対して IDirectMusicTrack::Play メソッドを呼び出す。ほとんどのトラックは、演奏されているセグメントのパートに対して有効なデータを含む、タイムスタンプ メッセージを直ちに生成する。これらのメッセージはキューに格納される (その後の動作については、「メッセージの作成と配信」を参照すること)。

いくつかのトラックでは、IDirectMusicTrack::Play に対してメッセージが生成されないが、代わりに、GetParam 呼び出しの形式でパフォーマンスやほかのトラックから送られてくる情報の要求に応答する (「トラック パラメータの設定と取り出し」を参照すること)。

次のリストに、DirectMusic で実装される標準的なトラックの種類と、それぞれの簡単な説明を示す。標準的なトラックでサポートされるメソッドのリストについては、IDirectMusicTrack を参照すること。

  • バンド。DLS データをパフォーマンスにダウンロードする。DMUS_PATCH_PMSG、DMUS_TRANSPOSE_PMSG、DMUS_CHANNEL_PRIORITY_PMSG、および DMUS_MIDI_PMSG 型のメッセージを送信する (ボリュームおよびパン用)。MIDI ファイルおよびスタイルに基づくセグメントで使用される。
  • コード。パターンに格納されたミュージック値を、MIDI 値に変換するために使用される。DMUS_NOTIFICATION_PMSG 型のメッセージを送信する (GUID_NOTIFICATION_CHORD 通知用)。
  • コード マップ。コード トラックを作成するために、テンプレート セグメントで使用される。
  • コマンド。テンプレート セグメントでコード トラックを作成するため、およびスタイル セグメントで演奏するパターンを決定するために使用される。DMUS_NOTIFICATION_PMSG 型のメッセージを送信する (GUID_NOTIFICATION_COMMAND の通知用)。
  • モチーフ。ほかのセグメントと一緒にモチーフを演奏するために使用する。DMUS_CURVE_PMSG、DMUS_NOTE_PMSG、および DMUS_NOTIFICATION_PMSG 型のメッセージを送信する (GUID_NOTIFICATION_MEASUREANDBEAT の通知用)。
  • ミュート。スタイル ベースのセグメント、または MIDI ベースのセグメントと一緒に使用する。P チャンネルをほかの P チャンネルに再割り当てしたり、ミュートすることができる。
  • シーケンス。DMUS_NOTE_PMSG および DMUS_MIDI_PMSG 型のシーケンス メッセージを送信する。MIDI ファイルに基づくセグメントで使用される。.sgt 形式で保存されたセグメントに対し、DMUS_CURVE_PMSG 型のメッセージを送信する。
  • サインポスト。コード トラックを作成するために、テンプレート セグメントで使用される。
  • スタイル。スタイルに基づくセグメントの基本的なトラック。DMUS_TIMESIG_PMSG、DMUS_CURVE_PMSG, DMUS_NOTE_PMSG、および DMUS_NOTIFICATION_PMSG 型のメッセージを送信する (GUID_NOTIFICATION_MEASUREANDBEAT の通知用)。
  • システム エクスクルーシブ。DMUS_SYSEX_PMSG 型のシステム エクスクルーシブ メッセージを送信する。MIDI ファイルに基づくセグメントで使用される。
  • テンポ。DMUS_TEMPO_PMSG 型のメッセージを送信して、パフォーマンスのテンポを設定する。
  • 拍子記号。GUID_NOTIFICATION_MEASUREANDBEAT 通知と同様に、DMUS_TIMESIG_PMSG 型のメッセージを送信する。MIDI ファイルに基づくセグメントで使用される。


バンドの使い方

バンドとは、スタイル内の特定のパートに割り当てられた一連の音色である。演奏時に各音色トラックは、次の情報を保存している P チャンネルにマップされる。

  • MIDI ボリューム。
  • MIDI パン。
  • 転調。この値が 0 でない場合、チャンネル上の音楽の音符は、音色に合わせて自動的に転調される。
  • 音色の MIDI パッチ番号。バンク セレクト の MSB と LSB も含まれる。
  • 音色のロード元となる DLS コレクションへの参照。デフォルトの DLS コレクションは、スタンダード General MIDI コレクションである。

セグメントとスタイルは常に、少なくともデフォルト バンドと呼ばれる 1 つのバンドによって構成される。スタイルには、追加のバンドを含めることができる。セグメントまたはスタイルをロードするときに、デフォルト バンドおよびその他のバンドは、どちらも自動的にロードされる。ただし、どんなバンドを使用する場合でも、バンドの音色用に DLS データをダウンロードしなければならない。

[C++]

IDirectMusicStyle::GetDefaultBand メソッドを使って、デフォルト バンドへのポインタを取得することができる。

スタイルにオーサリングされたその他のバンドは、IDirectMusicStyle::EnumBand および IDirectMusicStyle::GetBand メソッドを使って、検索および取得することができる。バンドは、ほかのスタイル ファイルやバンド ファイルからも取得できる。IDirectMusicBand インターフェイスを取得した後、このバンドにアクセスし、デフォルトのバンドを置き換えることもできる。

[Visual Basic]

DirectMusicStyle.GetDefaultBand メソッドを使って、デフォルト バンドを表すオブジェクトを取得することができる。スタイルにオーサリングされたほかのバンドは、DirectMusicStyle.GetBand メソッドを使って取得することができる。バンドは、ほかのスタイル ファイルやバンド ファイルからも取得できる。DirectMusicBand オブジェクトを取得した後、このバンドにアクセスし、デフォルトのバンドを置き換えることもできる。

独自のファイルからバンドをロードすることは、DirectMusic 内のほかのオブジェクトをロードすることに似ている。詳細については、「DirectMusic ローダー」を参照すること。

バンドの詳細については、次のトピックを参照すること。

  • バンドのダウンロードとアンロード
  • プログラム的なバンド チェンジの実行
  • 確実なタイミングでのバンド チェンジ


バンドのダウンロードとアンロード

バンドを使用するには、まず参照する音色をパフォーマンスにダウンロードしなければならない。この手順により、音色が P チャンネルに割り当てられ、ポートに DLS データがダウンロードされる。

デフォルトでは、使用するバンドのダウンロードはアプリケーションが行う。ただし、バンドの自動ダウンロードを有効にすることもできる。自動ダウンロードが有効な場合、バンドに含まれるセグメントがキューに格納されるときに、バンドの音色がダウンロードされる。セグメントが停止されると、同じ音色を使用しているほかのセグメントを直ちにキューに入れて演奏するか、現在演奏中でない限り、音色は自動的にアンロードされる。

注 : 自動ダウンロードは、セグメントのタイミングが重要でないときにだけ使用するべきである。音色のロードとアンロードを繰り返すと時間がかかり、複雑な音楽環境では、重大なパフォーマンスの低下が発生する場合がある。

自動ダウンロード メカニズムの一部である自動アンロードについても、望んでいない結果となる場合があるので、注意しなければならない。たとえば、チャンネルの音色を変更する短いセカンダリ セグメントを演奏する場合を考える。セカンダリ セグメントが開始されるときに、音色が自動的にダウンロードされ、既存の音色に置き換えられる。セカンダリ セグメントが終了すると、音色は自動的にアンロードされる。したがって、チャンネルの音色がなくなり、チャンネルからは音が出なくなる。

バンドのダウンロードにより、パフォーマンスがバンドを利用できるようになるが、プログラム チェンジは行われない。プログラム チェンジは、セグメントのバンド トラックで生成されるメッセージに応じて実行される。このメッセージは、一般的にはセグメント ファイルにオーサリングされる。実行時にプログラム チェンジを行う方法については、「プログラム的なバンド チェンジの実行」を参照すること。

バンドのダウンロードとアンロードを実装する方法については、次のトピックを参照すること。

  • バンドの自動ダウンロード
  • 手動によるバンドのダウンロード
  • バンドのアンロード


プログラム的なバンド チェンジの実行

通常は、ロードされたセグメントのバンド トラックによって、プログラム チェンジが実行される。ただし、手動で行うこともできる。

[C++]

まず、IDirectMusicBand::CreateSegment メソッドを呼び出して、セカンダリ セグメントを作成する。次に、IDirectMusicPerformance::PlaySegment を呼び出して、作成したセグメントを演奏する。通常は dwFlags パラメータ内の DMUS_SEGF_MEASURE または DMUS_SEGF_GRID (DMUS_SEGF_FLAGS を参照) を使って、適切な境界でバンド チェンジが有効になるよう保証する。

次のコード例では、バンドからセグメントを作成し、そのセグメントを演奏している。

/ * 自動ダウンロードが有効になっているか、アプリケーションが pBand->Download を呼び出していると仮定する。*/

HRESULT myPlayBand(
    IDirectMusicBand *pBand,         // バンド オブジェクトへのポインタ。
    IDirectMusicPerformance *pPerf,  // バンドを使うパフォーマンス。
    REFERENCE_TIME rfTime,           // 演奏開始タイム。
    DWORD dwFlags)                   // パフォーマンス フラグ。

{
    IDirectMusicSegment *pSegment;
    HRESULT hr = pBand->CreateSegment(&pSegment);
    if (SUCCEEDED(hr))
    {
        hr = pPerf->PlaySegment(pSegment,
                dwFlags | DMUS_SEGF_SECONDARY,
                rfTime,
                NULL);
        pSegment->Release();
    }
    return hr;
}
[Visual Basic]

まず、DirectMusicBand.CreateSegment を使ってセグメントを作成する。次に、DirectMusicPerformance.PlaySegment を呼び出して、作成したセグメントを演奏する。通常は、IFlags パラメータ内の DMUS_SEGF_MEASURE または DMUS_SEGF_GRID (CONST_DMUS_SEGF_FLAGS を参照) を使って、適切な境界でバンド チェンジが有効になるよう保証する。

パフォーマンスは、一度に複数のバンドの音色を演奏することができる。たとえば、アプリケーションが 1 つのバンドを使ってプライマリ セグメントを演奏しているときに、別のバンドを持つスタイルのモチーフを演奏する場合を考える。最初のバンドの音色が、2 つ目のバンドの音色以外の P チャンネル に割り当てられる限り、衝突は起こらない。ただし、通常、モチーフ セグメントは独自のバンド トラックを持たない。したがって、最初にバンド セグメントを作成してから演奏しなければ、モチーフの P チャンネルからは音が出ない (モチーフ セグメントにバンド トラックを追加することもできるが、別のバンド セグメントを作成する方が簡単である)。


確実なタイミングでのバンド チェンジ

バンド セグメントを演奏するときに重要な問題となるのは、スタイル トラックで演奏される音符のタイミングのばらつきである。たとえば、小節 1 の 1 拍目の音符が、実際の拍の境界よりわずかに進んだり遅れたりする場合がある。バンド セグメントではこの状況を承知していないので、いくつかの音符が間違った音色で演奏される場合がある。

[C++]

この問題を避けるために、アプリケーションはバンド セグメントを早めにキューに格納するべきである。たとえば、スタイル セグメントの pStyleSeg とバンド セグメントの pBandSeg があるときに、パフォーマンス (pPerf) の次の小節境界で、スタイル セグメントとバンド セグメントの両方を演奏する場合を考える。スタイルには、セグメントの開始タイムよりも、最大 30 ティック (ミュージック タイムで) 早く開始される可能性のある音符が含まれていることがわかっている。次のコード例では、バンド セグメントがスタイル セグメントよりも 31 ティック前に演奏されることが保証されている。したがって、すべての音色は、音符が演奏される前に適切に設定される。

/* 最初に、次の小節のタイムを取得して、
   ミュージック タイムに変換する。*/

REFERENCE_TIME rtResolved;
MUSIC_TIME mtResolved;

pPerf->GetResolvedTime( 0, &rtResolved, DMUS_TIME_RESOLVE_MEASURE );
pPerf->ReferenceToMusicTime( rtResolved, &mtResolved );

/* バンド セグメントを、小節境界の 31 ティック前に演奏する。*/

mtResolved -= 31;
pPerf->PlaySegment(pBandSeg, 0, mtResolved, NULL);

/* スタイル セグメントを小節境界で演奏する。*/

pPerf->PlaySegment(pStyleSeg, DMUS_TIME_RESOLVE_MEASURE, 0, NULL);
[Visual Basic]

この問題を避けるために、アプリケーションはバンド セグメントを早めにキューに格納するべきである。たとえば、スタイル セグメントの styleSeg とバンド セグメントの bandSeg があり、パフォーマンス (perf) の次の小節境界で、スタイル セグメントとバンド セグメントの両方を演奏する場合を考える。スタイルには、セグメントの開始タイムよりも、最大 30 ティック (ミュージック タイムで) 早く開始される可能性のある音符が含まれていることがわかっている。次のコード例では、バンド セグメントがスタイル セグメントよりも 31 ティック前に演奏されることが保証されている。したがって、すべての音色は、音符が演奏される前に適切に設定される。

'まず、次の小節のタイムを取得して、
' ミュージック タイムに変換する。

Dim ctResolved As Long
Dim mtResolved As Long

ctResolved = perf.GetResolvedTime(ctResolved, DMUS_SEGF_MEASURE)
mtResolved = perf.ClockToMusicTime(ctResolved)

' バンド セグメントを、小節境界の 31 ティック前に演奏する。

mtResolved = mtResolved - 31
Call perf.PlaySegment(bandSeg, 0, mtResolved)

' スタイル セグメントを小節境界で演奏する。

Call perf.PlaySegment(styleSeg, DMUS_SEGF_MEASURE, 0 )

注 : セグメントで演奏される音符にばらつきがない場合 (たとえば、MIDI ファイルに基づくセグメントの場合) は、同時に演奏されるバンド セグメントのタイミングについて注意する必要はない。デフォルトでは、すべてのバンド セグメントは 1 ティック早く開始される。


タイミング

ここでは、DirectMusic のさまざまなタイミングの概要について説明する。次の項目について説明する。

  • マスタ クロック
  • クロック タイムとミュージック タイム
  • テンポの変更
  • 準備時間
  • 遅延時間とバンパー時間
  • セグメントのタイミング


マスタ クロック

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、アプリケーションは別のマスタ クロックを選択することはできない。

[C++]

正確なタイミングと受け入れられる短い遅延時間を保証するために、DirectMusic はマスタ クロックをカーネル モードに実装している。このクロックは、ハードウェア タイマに基づいている。DirectMusic では、システム クロックが自動的にマスタ クロックとして選択されるが、アプリケーションではサウンド カードのウェーブ出力クリスタルなどの別のクロックを選択することができる。

マスタ クロックは高分解能のタイマであり、DirectMusic を使うプロセス、デバイス、およびアプリケーションはこのクロックを共有する。このクロックは、システム内のすべての音楽再生を同期化するために使われる。これは、標準的なIReferenceClock インターフェイスである。IReferenceClock::GetTime メソッドは、現在のタイムを 100 ナノ秒単位の 64 ビット整数として返す (REFERENCE_TIME 型として定義されている)。

マスタ クロックへのインターフェイスを取得するには、IDirectMusic::GetMasterClock メソッドを使う。

アプリケーションでほかのマスタ クロックも選択できる。ただし、マスタ クロックを選択できるのは、ほかに動作中の DirectMusic アプリケーションがないときだけである。最初に IDirectMusic::EnumMasterClock メソッドを使って、マスタ クロックの機能を果たせるすべてのデバイスの記述を取得する。マスタ クロックとして使いたいデバイスの GUID を取得した後で、その GUID を IDirectMusic::SetMasterClock メソッドに渡す。


クロック タイムとミュージック タイム

[C++]

DirectX for C++ では、マスタ クロックによって返されるタイムは、REFERENCE_TIME 型で定義される 64 ビット値である。基準タイムはおよそ 100 ナノ秒 (ns) 単位で測定されるので、クロックのティック (目盛り) は 1 秒間におよそ 10,000,000 個存在する。IReferenceClock::GetTime メソッドは、任意の開始タイム以降に経過した時間を返す。

ミュージック タイムは、MUSIC_TIME 型として定義される 32 ビット値である。これは時間の絶対的な測定値ではなく、テンポに基づく相対値である。クロックは、パフォーマンスが初期化されるときに開始され、4 分音符当たり DMUS_PPQ の時間が経過する (DMUS_PPQ は、現在 768 に定義されている)。

パフォーマンスが初期化されるときに、内部クロックの維持が開始される。IDirectMusicPerformance::GetTime メソッドを使って、現在のパフォーマンスタイムを基準タイムとミュージック タイムの両方で取得することができる。

IDirectMusicPerformance::AdjustTime メソッドを使うと、パフォーマンス タイムをわずかに変更することができる。ほとんどのアプリケーションでは、この操作を実行する必要はない。ただし、ほかのソースに同期させる場合には、この処理が役に立つ。

パフォーマンス内でこれら 2 種類のタイムを変換するには、IDirectMusicPerformance::MusicToReferenceTime と IDirectMusicPerformance::ReferenceToMusicTime の各メソッドを使う。

IDirectMusicPerformance::PlaySegment を呼び出して、演奏したいセグメントを挿入する際に、基準タイムを使って開始タイムを指定する。その時点でプライマリ セグメントが演奏されていない場合、このタイムは現在のテンポに従って直ちにミュージック タイムに変換される。ほかのプライマリ セグメントが演奏されている場合は、挿入されたセグメントの開始タイムに達した時点で、その開始タイムがミュージック タイムに変換される。

セグメントの演奏が開始される前にテンポが変更された場合は、開始タイムが影響を受けたり、セグメントが希望した境界で開始されない場合がある。前者の状況では、直ちにミュージック タイムへの変換が行われる。テンポの速度が上昇した場合は (基準タイムでの) 開始タイムは早まり、テンポの速度が低下した場合は遅れる。後者の状況では、開始タイムに変換が行われるので、テンポの変更が発生すると、正確な分解能の境界でセグメントが始まらないことを意味する。たとえば、セグメントがある小節境界 (PlaySegment の dwFlags パラメータで指示) で開始される場合、基準タイムでの開始タイムは、セグメントがキューに格納されるときに計算される。その後でテンポが変更されると、小節境界が計算したタイムどおりにならない可能性がある。

プライマリ セグメントが DMUS_SEGF_QUEUE フラグと共に PlaySegment に渡されるときに (DMUS_SEGF_FLAGS を参照)、i64StartTime パラメータは無視され、セグメントは、既に開始タイムが変換されているプライマリ セグメントの後で演奏されるように、キューに格納される。これは、基準タイムを指定して現在キューに置かれているセグメントが、DMUS_SEGF_QUEUE セグメントに割り込む可能性があることを意味する。

次の例で、この動作を説明する。3 つのセグメントがあり、それぞれの長さが 10 秒であるとする。セグメント A を、今から 5 秒後に演奏するようにキューに格納する。現在演奏されているプライマリ セグメントはないため、開始タイムは直ちにミュージック タイムに変換される。6 秒経過した時点で、セグメント B を 20 秒から演奏するようにキューに格納する。この場合、既に音楽が演奏中で、テンポが変更されている可能性があるため、ミュージック タイムへの変換はすぐには行われない。次に、DMUS_SEGF_QUEUE フラグを設定したセグメント C を、セグメント A が終了しだい、つまり 15 秒から演奏するようにキューに格納する。20 秒の時点で、セグメント B の演奏が開始され、セグメント C が中断される。

[Visual Basic]

DirectX for Visual Basic では、マスタ クロックによって返されるタイムは Long であり、およそ 1 ミリ秒の単位で表される。DirectMusicPerformance.GetClockTime によって返される値は、任意の開始タイム以降に経過した時間である。

ミュージック タイムも Long であり、時間の絶対的な測定値ではなく、テンポに基づく相対値である。クロックは、パフォーマンスが初期化されるときに開始され、4 分音符当たり 768 の時間が経過する。現在のタイムは、DirectMusicPerformance.GetMusicTime を使って取得することができる。

パフォーマンスで 2 種類のタイムを変換するには、DirectMusicPerformance.MusicToClockTime および DirectMusicPerformance.ClockToMusicTime メソッドを使用する。

DirectMusicPerformance.PlaySegment の呼び出しによってセグメントがキューに格納され、開始タイムがクロック タイムで与えられる場合、DirectMusic は開始タイムをミュージック タイムに変換しなければならない。その時点でプライマリ セグメントが演奏されていない場合、このタイムは現在のテンポに従って直ちにミュージック タイムに変換される。ほかのプライマリ セグメントが演奏されている場合は、挿入されたセグメントの開始タイムに達した時点で、その開始タイムはミュージック タイムに変換される。

セグメントの演奏が開始される前にテンポが変更された場合は、開始タイムが影響を受ける可能性があり、セグメントが希望した境界で開始されない場合がある。前者の状況では、直ちにミュージック タイムへの変換が行われる。テンポの速度が上昇した場合は (基準タイムでの) 開始タイムは早まり、テンポの速度が低下した場合は遅れる。後者の状況では、開始タイムに変換が行われるので、テンポの変更が発生すると、正確な分解能の境界でセグメントが始まらないことを意味する。たとえば、セグメントがある小節境界 (PlaySegment の lFlags パラメータで指示) で始まる場合、セグメントが挿入された時点で実際の開始タイム (クロック タイムで表現) が計算されるが、その後テンポが変更されると、小節境界は当初予定されていた時点と一致しない可能性がある。

プライマリ セグメントが DMUS_SEGF_QUEUE フラグと共に PlaySegment に渡されるときに (CONST_DMUS_SEGF_FLAGS を参照)、startTime パラメータは無視され、セグメントは、既に開始タイムが変換されているプライマリ セグメントの後で演奏されるように、キューに格納される。これは、基準タイムを指定して現在キューに置かれているセグメントが、DMUS_SEGF_QUEUE セグメントに割り込む可能性があることを意味する。

次の例で、この動作を説明する。3 つのセグメントがあり、それぞれの長さが 10 秒であるとする。セグメント A を、今から 5 秒後に演奏するようにキューに格納する。現在演奏されているプライマリ セグメントはないため、開始タイムは直ちにミュージック タイムに変換される。6 秒経過した時点で、セグメント B を 20 秒から演奏するようにキューに格納する。この場合、既に音楽が演奏中で、テンポが変更されている可能性があるため、ミュージック タイムへの変換はすぐには行われない。次に、DMUS_SEGF_QUEUE フラグを設定したセグメント C を、セグメント A が終了しだい、つまり 15 秒から演奏するようにキューに格納する。20 秒の時点で、セグメント B の演奏が開始され、セグメント C が中断される。


テンポの変更

パフォーマンスのテンポは、DirectMusic で使用される 2 種類のタイムの変換を指示し、音楽境界のイベントの分解能を制御する (「クロック タイムとミュージック タイム」を参照すること)。通常は、プライマリ セグメントのテンポ トラックがテンポを制御するが、アプリケーションで動的にテンポを設定することもできる。

[C++]

テンポを設定する方法には、メッセージを送信する方法と、トラック パラメータを設定する方法の 2 つがある。

次のコード例では、メッセージを送信してテンポを変更している。

/* pIDMSegment は有効な IDirectMusicSegment であり、
IDMPerformance は有効な IDirectMusicPerformance であるとする。*/

// セグメントのテンポ トラックを無効にして、テンポをリセットしないようにする。
pIDMSegment->SetParam( GUID_DisableTempo, 0xFFFF,0,0, NULL );

DMUS_TEMPO_PMSG* pTempo;

if( SUCCEEDED(pIDMPerformance->AllocPMsg(
sizeof(DMUS_TEMPO_PMSG), (DMUS_PMSG**)&pTempo)))
{
// テンポ イベントをキューに格納する。
ZeroMemory(pTempo, sizeof(DMUS_TEMPO_PMSG));
pTempo->dwSize = sizeof(DMUS_TEMPO_PMSG);
pTempo->dblTempo = 100;
pTempo->dwFlags = DMUS_PMSGF_REFTIME;
pTempo->dwType = DMUS_PMSGT_TEMPO;
pIDMPerformance->SendPMsg((DMUS_PMSG*)pTempo);
}

次のコード例は、テンポ パラメータを変更する方法を示している。詳細については、「トラック パラメータの設定と取り出し」を参照すること。

DMUS_TEMPO_PARAM Tempo;
Tempo.dblTempo = 100;
pIDMSegment->SetParam(GUID_TempoParam, 0xFFFF, 0, 0, &Tempo);
[Visual Basic]

テンポを設定する方法には、マスタ テンポを設定する方法と、テンポ メッセージを送信する方法の 2 つがある。

マスタ テンポは、パフォーマンスのすべてのテンポに乗算する係数である。たとえば、0.75 のパラメータで DirectMusicPerformance.SetMasterTempo を呼び出してマスタ テンポを設定し、1 分間に 120 拍のテンポを持つセグメントを演奏する場合、セグメントは 90 のテンポで演奏される。

DirectMusicPerformance.SendTempoPMSG メソッドを使ってテンポを送信すると、メッセージのスタンプに指定されたタイムにテンポが変更される。新しいテンポは、アプリケーションから直接、または演奏されているセグメントによって、ほかのテンポ メッセージが送信されるまで有効である。テンポの値は、マスタ テンポによって変更することができる。

次の呼び出しでは、直ちに 1 分間に 100 拍のテンポに設定される。perf は DirectMusicPerformance オブジェクトを表す。lTime パラメータに 0 を渡して、メッセージを直ちに送信するように指定する場合は、DMUS_PMSGF_REFTIME フラグも設定しなければならない。

Call perf.SendTempoPMSG(0, DMUS_PMSGF_REFTIME, 100)


準備時間

セグメントを演奏するときに、パフォーマンスはセグメントのトラックを繰り返し呼び出す。この呼び出しにより、1 秒の何分のいくつかの指定された時間範囲分のメッセージが生成される。これらのメッセージは、これまでの呼び出しで生成されたメッセージの後ろに挿入される。デフォルトでは、およそ 1 秒分のメッセージが、いつでもキューにある。

「遅延時間とバンパー時間」の図を参照すること。

[C++]

キューは、IDirectMusicTrack::Play の呼び出しによって、絶えず満タンにされているガス タンクのようなものである。パフォーマンスが Play を呼び出すごとに、現在のタイムに準備時間を加算して、呼び出しのタイムが計算される。現在のタイムが 10,000 ミリ秒 (または、等価な REFERENCE_TIME 単位) で、準備時間がデフォルトで 1000 ミリ秒である場合、終了タイムは 11,000 となる。つまり、11,000 までの演奏分の新しいメッセージをすべて準備して、キューに格納しなければならない。

キューのサイズは、IDirectMusicPerformance::SetPrepareTime メソッドを呼び出して変更することができる。また、現在のサイズは、IDirectMusicPerformance::GetPrepareTime を使って取得することができる。

ほとんどのアプリケーションでは、デフォルトの準備時間を変更する必要はない。ここで説明した処理は、アプリケーションからは認識されていない。ただし、アプリケーションは IDirectMusicPerformance::PlaySegment にDMUS_SEGF_AFTERPREPARETIME フラグを渡すことができるので、準備時間の概念を理解しておくと有効である。

[Visual Basic]

キューは、絶えず満タンにされているガス タンクのようなものである。パフォーマンスがメッセージを送信するようにセグメントに要求するごとに、現在のタイムに準備時間を加算して、呼び出しの終了タイムが計算される。現在のタイムが 10,000 ミリ秒で、準備時間がデフォルトで 1000 ミリ秒である場合、終了タイムは 11,000 となる。つまり、11,000 までの演奏分の新しいメッセージをすべて準備して、キューに格納しなければならない。

キューのサイズは、DirectMusicPerformance.SetPrepareTime を呼び出して変更することができる。現在のサイズは、DirectMusicPerformance.GetPrepareTime を使って取得することができる。

ほとんどのアプリケーションでは、デフォルトの準備時間を変更する必要はない。ここで説明した処理は、アプリケーションからは認識されていない。ただし、アプリケーションは DirectMusicPerformance.PlaySegment に DMUS_SEGF_AFTERPREPARETIME フラグを渡すことができるので、準備時間の概念を理解しておくと有効である。

通常、セグメントの開始タイムを "現在" に設定すると、パフォーマンスは現在キューに格納されているメッセージをすべて無効にする。この時点で有効なままのトラック (たとえば、新しいプライマリ セグメントの導入にかかわらず、演奏が続けられるセカンダリ セグメントのトラック) は、新しいセグメントによる音楽環境の変化を考慮して、メッセージを再送信しなければならない。不必要な処理を避け、連続性を確実にするために (たとえば、長い音符や、音楽以外の DLS サウンドが途切れないようにするために)、DMUS_SEGF_AFTERPREPARETIME フラグを使って、現在キューにあるメッセージがすべて処理されてポート バッファに渡されるまで、セグメントの演奏を開始しないように指定することができる。したがって、たとえば、タイム 10,000 までのメッセージがキューにあり、現在のタイムが 9,000 の場合、演奏用にキューに格納されるセグメントは、ちょうど 10,000 ミリ秒後に演奏を開始する。

詳細については、「セグメントのタイミング」を参照すること。


遅延時間とバンパー時間

[C++]

遅延時間とは、ポートがミュージック メッセージを受け取ってから、演奏すべき十分なウェーブが合成されるまでの遅延時間を意味する。IDirectMusicPerformance::GetLatencyTime メソッドは、現在のタイムにパフォーマンスの遅延時間を加算した全体の時間を取り出す。この値は、ポートの遅延時間クロックによって返される最大の値である。

バンパーとは、音楽イベントがポート バッファに置かれてから、ポートがそのイベントの処理を開始するタイムまでの、コードを実行するために割り当てられた時間である。デフォルトでは、バンパーの長さは 50 ミリ秒 (ms) である。アプリケーションは、IDirectMusicPerformance::SetBumperLength メソッドを使ってこの値を変更し、IDirectMusicPerformance::GetBumperLength を呼び出して現在の値を取得できる。

遅延時間とバンパー時間は結合される場合がある。あるイベントが 10,000 ミリ秒の時点で演奏されると仮定する。このポートの遅延時間は 100 ミリ秒であること、およびバンパー時間の長さはデフォルトの 50 ミリ秒であることがわかっている。そのため、パフォーマンスは 9,850 ミリ秒の時点でこのメッセージをポート バッファに置く。

ポート バッファに置かれたメッセージは、もはやパフォーマンスに所属していないため、IDirectMusicPerformance::Invalidate または IDirectMusicPerformance::Stop メソッドを使っても、演奏を止められない点に注意すること。無効にできる最初のメッセージは、現在のタイムに遅延時間とバンパー時間を加えたタイムと同じか、それ以降のタイム スタンプを持つ。IDirectMusicPerformance::GetQueueTime メソッドを使うと、この値を取得することができる。

[Visual Basic]

遅延時間とは、ポートがミュージック メッセージを受け取ってから、演奏すべき十分なウェーブが合成されるまでの遅延時間を意味する。DirectMusicPerformance.GetLatencyTime メソッドは、現在のタイムにパフォーマンスの遅延時間を加算した全体の時間を取り出す。この値は、ポートの遅延時間クロックによって返される最大の値である。

バンパーとは、音楽イベントがポート バッファに置かれてから、ポートがそのイベントの処理を開始するタイムまでの、コードを実行するために割り当てられた時間である。デフォルトでは、バンパーの長さは 50 ミリ秒 (ms) である。アプリケーションは、DirectMusicPerformance.SetBumperLength メソッドを使ってこの値を変更したり、DirectMusicPerformance.GetBumperLength を呼び出して現在の値を取得することができる。

遅延時間とバンパー時間は結合される場合がある。あるイベントが 10,000 ミリ秒の時点で演奏されると仮定する。このポートの遅延時間は 100 ミリ秒であること、およびバンパー時間の長さはデフォルトの 50 ミリ秒であることがわかっている。そのため、パフォーマンスは 9,850 ミリ秒の時点でこのメッセージをポート バッファに置く。

ポート バッファに置かれたメッセージは、もはやパフォーマンスに所属していないため、DirectMusicPerformance.Invalidate または DirectMusicPerformance.Stop メソッドを使っても、演奏を止められない点に注意すること。無効にできる最初のメッセージは、現在のタイムに遅延時間とバンパー時間を加えたタイムと同じか、それ以降のタイム スタンプを持つ。DirectMusicPerformance.GetQueueTime メソッドを使うと、この値を取得することができる。

次の図は、さまざまなメソッドで取得される、タイムと継続時間の関係を示している。現在のタイムは左側に示されている。右側が、メッセージの準備が完了する最終タイムである。準備時間はいつでも、キューにあるメッセージの合計の長さの近似である。

[Visual Basic]

図に示すメソッドは C++ API のものであるが、DirectX for Visual Basic でもほとんど同じ名前が使用されている。たとえば、IDirectMusicPerformance::GetPrepareTime は DirectMusicPerformance.GetPrepareTime と等価であり、図の GetTime メソッドは DirectMusicPerformance.GetClockTime と等価である。


セグメントのタイミング

[C++]

IDirectMusicSegment::SetStartPoint メソッドを呼び出して開始ポイントを設定しない限り、セグメントは最初から演奏される。IDirectMusicSegment::SetRepeats を使ってリピート回数を設定した場合、IDirectMusicSegment::SetLoopPoints を呼び出してループを定義しなければ、セグメント全体がその回数だけ反復される。ループを設定すると、セグメントのループ ポイント間の部分だけが繰り返される。

セグメントの演奏が開始される演奏タイムは、IDirectMusicPerformance::PlaySegment の 2 つのパラメータによって決定される。

  • i64StartTime パラメータは、セグメントの演奏を開始できる、最も早いタイムを設定する。i64StartTime が 0 の場合は、可能な限り早いタイムとなる。セグメントが開始されるタイムは、セグメントの種類によって異なる。プライマリ セグメントまたは制御セグメント の場合、最も早い開始タイムはキュー (またはフラッシュ) 時間である。制御以外のセカンダリ セグメントの場合、最も早い開始タイムは遅延時間後である。キュー時間と待ち時間の詳細については、「遅延時間とバンパー時間」を参照すること。
  • dwFlags パラメータは、現在演奏中のセグメントのリズムに基づいて、スケジュールされたタイム以降どれだけ速やかにセグメントの演奏を開始できるかを決定する。通常は、新しいセグメントを開始する前に適切な時間、つまり移行部やモチーフの長さだけ待つはずである。次の DMUS_SEG_FLAGS のいずれかを設定することにより、遅延を制御する。
[Visual Basic]

DirectMusicSegment.SetStartPoint メソッドを呼び出して開始ポイントを設定しない限り、セグメントは最初から演奏される。IDirectMusicSegment.SetRepeats を使ってリピート回数を設定した場合、DirectMusicSegment.SetLoopPoints を呼び出してループを定義しなければ、セグメント全体がその回数だけ反復される。ループを設定すると、セグメントのループ ポイント間の部分だけが繰り返される。

セグメントの演奏が開始される演奏タイムは、DirectMusicPerformance.PlaySegment の 2 つのパラメータによって決定される。

  • startTime パラメータは、セグメントの演奏を開始できる、最も早いタイムを設定する。startTime が 0 の場合は、可能な限り早いタイムとなる。セグメントが開始されるタイムは、セグメントの種類によって異なる。プライマリ セグメントまたは制御セグメント の場合、最も早い開始タイムはキュー (またはフラッシュ) 時間である。制御以外のセカンダリ セグメントの場合、最も早い開始タイムは遅延時間後である。キュー時間と遅延時間の詳細については、「遅延時間とバンパー時間」を参照すること
  • IFlags パラメータは、現在演奏中のセグメントのリズムに基づいて、スケジュールされたタイム以降どれだけ速やかにセグメントの演奏を開始できるかを決定する。通常は、新しいセグメントを開始する前に適切な時間、つまり移行部やモチーフの長さだけ待つはずである。次の CONST_DMUS_SEGF_FLAGS のいずれかを設定して、遅延を制御する。
DMUS_SEGF_AFTERPREPARETIME
最も早い開始タイムに準備時間を加えたタイムに演奏する。既にキューにある現在演奏中のセグメントからポートへのメッセージは、いずれも無効にならない。これにより処理時間が省略され、プライマリ セグメント間の移行部でモチーフがなめらかに演奏されることが保証される。
DMUS_SEGF_GRID
グリッド境界で演奏する。グリッドとは拍 (ビート) の小分割である。スタイルの形式でオーサリングされた拍子記号は、各拍を何個のグリッドに分割するかを決定する。
DMUS_SEGF_BEAT
拍で演奏する。
DMUS_SEGF_MEASURE
小節の先頭で演奏する。
DMUS_SEGF_DEFAULT
挿入されたセグメントのデフォルトの境界を使う。

これらのフラグがいずれもセットされていない場合、セグメントは最も早い開始タイムに演奏を開始する。

テンポの変更によって開始タイムが受ける影響については、「クロック タイムとミュージック タイム」を参照すること。


通知とイベントの処理

アプリケーションは、音楽イベントに応答しなければならない場合がある。たとえば、セグメントが終わったことを確認する必要がある場合や、グラフィックスと音楽の拍を同期させたい場合などである。特定のタイプのイベントが発生したときに、そのことを通知するよう DirectMusic に指示して、必要な情報を取得することができる。

[C++]

通知を受けたい音楽イベントの種類を指定するには、イベントの種類ごとに一度だけ IDirectMusicPerformance::AddNotificationType メソッドを呼び出す。次のコード例では、DirectMusic にセグメントに関連するイベントを設定するように指示している。実際のイベントの種類 (セグメントの開始やセグメントの終了など) は、通知メッセージから得られる。

/* pPerformance は、有効な
   IDirectMusicPerformance ポインタであるとする。*/

GUID guid = GUID_NOTIFICATION_SEGMENT;
// C の構文
pPerformance->AddNotificationType(&guid);
// C++ の構文
pPerformance->AddNotificationType(guid);

IDirectMusicSegment::AddNotificationType メソッドを使って、特定のセグメントに対して通知タイプを追加することもできる。たとえば、特定のセグメントが演奏を停止したときに通知を受け取るような場合に、この設定を行うことができる。このメソッドを使って GUID_NOTIFICATION_PERFORMANCE 型を要求することはできない。これらの型は、パフォーマンス オブジェクトから取得しなければならない。

通知は、DMUS_NOTIFICATION_PMSG メッセージ構造体の形式で送られる。IDirectMusicPerformance::GetNotificationPMsg メソッドを呼び出して、Windows メッセージ ループ内で保留中の通知メッセージをポーリングすることができる。また、メッセージが保留中のときに、DirectMusic に別のスレッドでイベント オブジェクトを通知させることもできる。

Windows イベント オブジェクトを使って、保留中の DirectMusic 通知メッセージを知らせたい場合は、まず Win32 CreateEvent 関数を呼び出して、イベント ハンドルを取得しなければならない。通常は、次のような呼び出しを行って、自動リセット イベントを作成する。

HANDLE g_hNotify = CreateEvent(NULL, FALSE, FALSE, NULL);

イベントの作成後、このハンドルを IDirectMusicPerformance::SetNotificationHandle メソッドに渡してパフォーマンスに割り当てる。イベントを取り出せなかった場合でも DirectMusic はイベントを待機するが、このメソッドの 2 番目のパラメータを使うとデフォルトの時間を変更できる。このパラメータに 0 を指定すると、デフォルトの時間の 2 秒が使用される。

次の例では、g_pPerf は IDirectMusicPerformance インターフェイスへの有効なポインタを表している。

g_pPerf->SetNotificationHandle(g_hNotify, 0);

次のコード例は、独自のスレッドで繰り返し実行され、通知されたイベントを確認して、通知メッセージを取り出している。

void WaitForEvent( LPVOID lpv)
{
    DWORD dwResult;
    DMUS_NOTIFICATION_PMSG* pPmsg;
    char szCount[4];

    while (TRUE)
    {
        dwResult = WaitForSingleObject(g_hNotify, 100);
        while (S_OK == g_pPerf->GetNotificationPMsg(&pPmsg))
        {
            // 通知タイプを確認し、それに対応する処理を行う。
            .
            .
            .
            g_pPerf->FreePMsg((DMUS_PMSG*)pPmsg);
        }
    }
}

このスレッドは次のように実行される。

_beginthread(WaitForEvent, 0, NULL);

通知が必要なくなった場合は、次のコード例に示すように、スレッドをシャット ダウンし、パフォーマンスから通知ハンドルを削除し、イベント オブジェクトを破棄する。

_endthread();
g_pPerf->SetNotificationHandle(0, 0);
CloseHandle(g_hNotify);

アプリケーションのメッセージ ループで、イベントを作成して通知メッセージを取り出す必要はない。IDirectMusicPerformance::AddNotificationType メソッドを呼び出して通知を要求している場合、メッセージはパフォーマンスによって送信され、IDirectMusicPerformance::GetNotificationPMsg の呼び出しで取り出すことができる。

イベントが通知される場合、またはメッセージ ループで GetNotificationPMsg を呼び出す場合は、複数のメッセージを待機することができる。すべての通知を確実に受け取るには、S_FALSE が返されるまで GetNotificationPMsg の呼び出しを繰り返す。

同じタイム スタンプを持つメッセージが複数ある場合、これらのメッセージはキューに格納されるときに特定の順序にはならない。

IDirectMusicPerformance::FreePMsg メソッドを呼び出して、取り出したイベントを解放するのは開発者の責任である。

[Visual Basic]

通知を受けたい音楽イベントの種類を指定するには、イベントの種類ごとに一度だけ DirectMusicPerformance.AddNotificationType メソッドを呼び出す。次のコード例では、DirectMusic にセグメント イベントを要求している。perf は DirectMusicPerformance オブジェクトである。イベントの種類 (セグメントの開始やセグメントの終了など) は、通知メッセージから得られる。

Call perf.AddNotificationType(DMUS_NOTIFY_ON_SEGMENT)

通知は、DMUS_NOTIFICATION_PMSG メッセージ タイプの形式で送られる。Sub Main またはその他のループで DirectMusicPerformance.GetNotificationPMsg メソッドを呼び出して、保留中の通知メッセージをポーリングすることができる。また、メッセージが保留中のときに、DirectMusic に別のスレッドでイベント オブジェクトを通知させることもできる。

DirectMusic にイベントを通知させるには、DirectX7.CreateEvent を使ってイベント ハンドルを取得し、このハンドルをDirectMusicPerformance.SetNotificationHandle に渡す。CreateEvent に渡すモジュールは、DirectXEvent クラスを実装し、DirectXEvent.DXCallback メソッドの実装を提供しなければならない。これは、イベントが通知されるたびに DirectMusic によって呼び出される。

次のコード例は、frmMain というフォーム モジュールの通知を設定している。

' DX は DirectX7 オブジェクトを表し、perf は DirectMusicPerformance オブジェクトを表す。
Dim hEvent As Long
hEvent = DX.CreateEvent(frmMain)
Call perf.SetNotificationHandle(hEvent)

フォーム モジュールには、次に示すものと同様なコードが含まれる。このコードは、セグメントが演奏を終了したことを示すメッセージを検索する。

Implements DirectXEvent

Private Sub DirectXEvent_DXCallback(ByVal eventid As Long)

Dim GotMSG As Boolean
Dim PMsg As DMUS_NOTIFICATION_PMSG

Do
GotMSG = gobjDMPerformance.GetNotificationPMSG(PMsg)
If GotMSG Then
If PMsg.lNotificationOption = DMUS_NOTIFICATION_SEGEND Then
' セグメントが演奏を終了している。
End If
End If
Loop Until Not GotMSG

End Sub

アプリケーションのメイン ループで、イベントを作成して通知メッセージを取り出す必要はない。DirectMusicPerformance.AddNotificationType メソッドを呼び出して通知を要求している場合、メッセージはパフォーマンスによって送信され、DirectMusicPerformance.GetNotificationPMsg の呼び出しで取り出すことができる。

イベントが通知される場合、またはループで GetNotificationPMsg を呼び出す場合は、複数のメッセージを待機することができる。すべての通知を確実に受け取るには、False が返されるまで GetNotificationPMsg の呼び出しを繰り返す。

同じタイム スタンプを持つメッセージが複数ある場合、これらのメッセージはキューに格納されるときに特定の順序にはならない。


ミュージック パラメータ

[Visual Basic]

DirectX for Visual Basic では、DirectMusicPerformance および DirectMusicSegment のさまざまなメソッドを使って、ミュージック パラメータを設定および取り出すことができる。

変更されたパラメータに音楽を直ちに応答させるには、アプリケーションで DirectMusicPerformance.Invalidate メソッドを使って、キューからメッセージをフラッシュする。このメソッドにより、すべてのトラックは指定したポイント以降のメッセージを再送信する。

[C++]

DirectMusic では、次の SetParam メソッドのいずれかを使って実行中にパラメータを変更し、トラックのさまざまな動作を制御することができる。、

  • IDirectMusicPerformance::SetParam は、このパフォーマンスの現在の制御セグメント内で、特定のトラックにデータを設定する。制御セグメントは、通常はプライマリ セグメントであるが、セカンダリ セグメントを演奏中に制御セグメントとして指定することができる。DMUS_SEGF_FLAGS を参照すること。
  • IDirectMusicSegment::SetParam は、セグメント内の特定のトラックにデータを設定する。
  • IDirectMusicTrack::SetParam は、トラックにデータを設定する。

また、IDirectMusicPerformance::SetGlobalParam メソッドを使って、パフォーマンス全体に適用される値を設定することができる。

GetParam および GetGlobalParam メソッドは、トラックまたはパフォーマンスの現在の値を取得する。

変更されたパラメータに音楽を直ちに応答させるには、アプリケーションで IDirectMusicPerformance::Invalidate メソッドを使って、キューからメッセージをフラッシュする。このメソッドにより、すべてのトラックは指定したポイント以降のメッセージを再送信する。

パラメータの詳細については、次のトピックを参照すること。

  • トラック パラメータの設定と取り出し
  • グローバル パラメータの設定と取り出し


トラック パラメータの設定と取り出し

[Visual Basic]

DirectMusicPerformance および DirectMusicSegment のメソッドのいくつかでは、通常は制御セグメントの特定のトラックでパラメータを設定または取得することができる。ただし、DirectX for Visual Basic を使用するアプリケーションは、これらのトラックについて関与する必要はない。これらのメソッドは、低レベルでの動作について知らなくても使用することができる。

[C++]

パフォーマンス、セグメント、またはトラックの SetParam および GetParam メソッドを使って、トラック パラメータを設定および取得することができる。パフォーマンスまたはセグメントでこれらのメソッドのいずれかを呼び出すときに、dwGroupBits および dwIndex パラメータを設定して、トラックを識別することができる。ただし、ほとんどの場合は、DirectMusic に適切なトラックを検索させることができる。詳細については、「トラックの識別」を参照すること。

場合によっては、変更を行うタイム、またはパラメータを取得するタイムを、トラック内で指定しなければならない。特定のトラック パラメータでこの値が使用されているかどうかを確認するには、「トラック パラメータのタイプ」を参照すること。

いくつかのパラメータでは、SetParam で機能がオンまたはオフになり、データは必要ない。ただし、ほかのパラメータを設定するときに、データを含む構造体または変数も渡さなければならない。データに関連付けられたパラメータだけを取り出すことができる。したがって、GetParam を使う場合、データを受け取るには、常に適切な変数または構造体へのポインタを渡さなければならない。

特定のパラメータがトラックによってサポートされているかどうかを確認するには、IDirectMusicTrack::IsParamSupported メソッドを使用して、S_OK の結果を確認する。

詳細については、次のトピックを参照すること。

  • トラックの識別
  • トラック パラメータのタイプ
  • メッセージの無効化と有効化


トラックの識別

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

IDirectMusicTrack::SetParam または IDirectMusicTrack::GetParam を使ってパラメータを設定または取得するときに、パラメータはメソッドを呼び出したトラックに関連付けられる。ただし、IDirectMusicPerformance::SetParam、IDirectMusicPerformance::GetParam、IDirectMusicSegment::SetParam、または IDirectMusicSegment::GetParam を呼び出すときに、DirectMusic は適切なトラックを検索する必要がある。

通常は、目的のパラメータがどのトラックに含まれるかを、DirectMusic に決定させることができる。この場合、dwGroupBits を 0xFFFFFFFF に、dwIndex を 0 に設定する。たとえば、次の IDirectMusicSegment::SetParam の呼び出しでは、セグメントのループでテンポがリセットされないように、テンポ トラックをオフにしている。

pIDMSegment->SetParam(GUID_DisableTempo, 0xFFFFFFFF, 0, 0, NULL);

ただし、トラックを識別しなければならない場合もある。一般的には、セグメントに同じタイプのトラックが 2 つ以上含まれている場合である。目的のトラックでパラメータを設定または取得するには、グループまたはインデックス値を使って、トラックを識別しなければならない。

すべてのトラックは 1 つまたは複数のグループに属し、それぞれのグループは dwGroupBits パラメータのビットで表される。dwGroupBits は、後で説明するメソッドの 1 つのパラメータである (トラックは、パフォーマンスに挿入されるときに、1 つまたは複数のグループに割り当てられる。IDirectMusicSegment::InsertTrack を参照すること。ファイルからロードされるセグメントの場合、トラック グループはセグメントのオーサーによって割り当てられる)。

トラックは、属しているグループそれぞれにおいて、ゼロから始まるインデックス値で識別される。インデックス値は、トラックが挿入された順序で決定される。

1 つのセグメントが、次のトラックによって構成されていると仮定する。

トラック | グループ ビット
A | 0x1
B | 0x2
C | 0x1
D | 0x3

グループ 1 はトラック A、トラック C、およびトラック D を含み、グループ 2 はトラック B とトラック D を含む。dwGroupBits を 1、dwIndex を 0 にして GetParam または SetParam を呼び出すと、パラメータは、グループ 1 の最初のトラックであるトラック A から取り出される。dwIndex が 1 の場合は、グループで 2 番目のトラック C からパラメータが取り出される。トラック D は、グループ 1 とグループ 2 の、2 つのグループに属している。したがって、このトラックは、dwGroupBits = 1 および dwIndex =2、または dwGroupBits = 2 および dwIndex = 1 の組み合わせのどちらかで識別される。

dwGroupBits に複数のビットを設定すると、それらのすべてのビットを含む n 番目のトラックからパラメータが取り出される。ここで n は dwIndex 内の値である。


トラック パラメータのタイプ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

SetParam または GetParam メソッドのいずれかで設定または取り出されるトラック パラメータは、メソッドの rguidType パラメータの GUID で識別される。データを必要とする各パラメータは、特定のデータ タイプに関連付けられている。pParam は、このタイプの変数または構造体を指していなければならない。場合によっては、GetParam を呼び出すときにも、データ構造体の一部を初期化する必要がある。

定義済みのパラメータを、次の表に示す。各パラメータの詳細については、リンク先の表を参照すること。詳細な表で、pParam および mtTime は、さまざまな GetParam および SetParam メソッドのパラメータを表している。パラメータは常に特定のトラック タイプに関連付けられるが、通常は、セグメントまたはパフォーマンスでメソッドを呼び出すと、DirectMusic が適切なトラックを検索する (「トラックの識別」を参照すること)。

GUID_ChordParam | GUID_EnableTimeSig
GUID_Clear_All_Bands | GUID_IDirectMusicBand
GUID_CommandParam | GUID_IDirectMusicChordMap
GUID_CommandParam2 | GUID_IDirectMusicStyle
GUID_ConnectToDLSCollection | GUID_MuteParam
GUID_Disable_Auto_Download | GUID_RhythmParam
GUID_DisableTempo | GUID_SeedVariations
GUID_DisableTimeSig | GUID_StandardMIDIFile
GUID_Download | GUID_TempoParam
GUID_Enable_Auto_Download | GUID_TimeSignature
GUID_EnableTempo | GUID_Unload


グローバル パラメータの設定と取り出し

[C++]

IDirectMusicPerformance::SetGlobalParam および IDirectMusicPerformance::GetGlobalParam メソッドを使うと、1 つのトラックだけでなく、パフォーマンス全体に影響するパラメータを設定および取得することができる。

設定または取得するパラメータは、メソッドの rguidType パラメータにある GUID で識別される。各パラメータは特定のデータ タイプに関連付けられる。データ タイプのサイズは、dwSize パラメータで与えられる。次の表に、定義済みの GUID とそのデータ タイプを示す。

パラメータ タイプの GUID (rguidType) とデータ (*pParam) | 説明
GUID_PerfAutoDownload BOOL | このパラメータは、セグメントを演奏するときに、音色を自動的にダウンロードするかどうかを制御する。デフォルトではオフである。「バンドのダウンロードとアンロード」を参照すること。
GUID_PerfMasterGrooveLevel char | マスタ グルーブ レベルは、コマンド トラックで設定されるグルーブ レベルに常に加算される値である。必要な場合は、1 ～ 100 の範囲になるように、結果の値が調整される。
GUID_PerfMasterTempo float | マスタ テンポは、最終出力ツールによってテンポに適用されるスケール ファクタである。デフォルトの値は 1 である。0.5 でテンポは 2 分の 1 になり、2.0 で 2 倍のテンポになる。この値は、DMUS_MASTERTEMPO_MIN から DMUS_MASTERTEMPO_MAX の範囲で設定できる。
GUID_PerfMasterVolume long | マスタ ボリュームは、増幅または減衰の係数で、1 デシベルの 100 分の 1 の単位で表される。デフォルトのボリュームまたはパフォーマンス全体に適用される。設定できる値の範囲は、ポートによって決まる。従来のハードウェア MIDI ポートでは、マスタ ボリュームの変更はサポートされていない。

アプリケーションは、独自のタイプのグローバル パラメータを使うこともできる。新しいタイプを作成するには、GUID とそのデータ タイプを確定する。

パラメータを設定するときに、パフォーマンスは、GUID で識別されるリンクされた項目のリストのデータにメモリを割り当てる。データは、IDirectMusicPerformance::GetGlobalParam を呼び出して取り出すことができる。定義済みのパラメータも、取り出す前には設定しなければならない。パラメータに対して SetGlobalParam が呼び出されていない場合、GetGlobalParam は失敗する。

[Visual Basic]

DirectMusicPerformance クラスには、パフォーマンス全体に影響するグローバル パラメータを設定および取得するための、次のメソッドが用意されている。

GetMasterAutoDownload SetMasterAutoDownload | このパラメータは、セグメントを演奏するときに音色を自動的にダウンロードするかどうかを制御する。デフォルトではオフである。「バンドのダウンロードとアンロード」を参照すること。
GetMasterGrooveLevel SetMasterGrooveLevel | マスタ グルーブ レベルは、コマンド トラックで設定されるグルーブ レベルに常に加算される値である。必要な場合は、1 ～ 100 の範囲になるように、結果の値が調整される。
GetMasterTempo SetMasterTempo | マスタ テンポは、最終出力ツールによってテンポに適用されるスケール ファクタである。デフォルトの値は 1 である。0.5 でテンポは 2 分の 1 になり、2.0 で 2 倍のテンポになる。この値は、0.25 ～ 2.0 の範囲で設定できる。
GetMasterVolume SetMasterVolume | マスタ ボリュームは、増幅または減衰の係数で、1 デシベルの 100 分の 1 の単位で表される。デフォルトのボリュームまたはパフォーマンス全体に適用される。設定できる値の範囲は、ポートによって決まる。従来のハードウェア MIDI ポートでは、マスタ ボリュームの変更はサポートされていない。


メッセージの無効化と有効化

[C++]

トラックで GUID_DisableTempo および GUID_DisableTimeSig パラメータを設定すると、それぞれ DMUS_TEMPO_PMSG および DMUS_TIMESIG_PMSG メッセージの生成を無効にすることができる。たとえば、動的にテンポを設定して、プライマリ セグメントにテンポ メッセージを送信させたくない場合などに使用できる。

メッセージを再び有効にするには、rguidType パラメータに GUID_EnableTempo および GUID_EnableTimeSig を指定して、いずれかの SetParam を呼び出す。これらのパラメータを設定して、制御セグメントでないセグメントにテンポ メッセージを送信させたり、セカンダリ セグメントに拍子記号メッセージを送信させることもできる (制御セグメントの詳細については、「セグメント」と DMUS_SEGF_FLAGS を参照すること)。

パラメータを設定する方法については、「トラック パラメータの設定と取り出し」を参照すること。

IDirectMusicTrack::IsParamSupported の「注意」も参照すること。

[Visual Basic]

DirectMusicSegment.SetTempoEnable および DirectMusicSegment.SetTimeSigEnable メソッドを使うと、テンポと拍子記号メッセージの生成をそれぞれ無効にすることができる。たとえば、動的にテンポを設定して、プライマリ セグメントにテンポ メッセージを送信させたくない場合などに使用できる。

SetTempoEnable を使うと、制御セグメントでないセグメントにもテンポ メッセージを送信させることもできる。また、SetTimeSigEnable を使って、セカンダリ セグメントに拍子記号メッセージを送信させることもできる (制御セグメントの詳細については、「セグメント」と DMUS_SEGF_FLAGS を参照すること)。


音楽のキャプチャ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、音楽のキャプチャはサポートされない。

[C++]

キーボードなどのデバイスから MIDI メッセージをキャプチャすることは、DirectMusic では非常に簡単である。

通常は、キャプチャ デバイスのポートを作成し、IDirectMusicPort::SetReadNotificationHandle メソッドを使って、メッセージを読み込めるときに常にイベントに通知させる。イベントに応答して、IDirectMusicPort::Read メソッドの呼び出しを S_FALSE が返されるまで繰り返し、未処理のイベントをバッファに置く。Read が呼び出されるたびに、利用可能なだけのイベント、またはバッファに収まるだけのイベントがバッファに置かれる。少なくとも 1 つのイベントがバッファに置かれると、S_OK が返される。

バッファからイベントを取り出すには、IDirectMusicBuffer::GetNextEvent メソッドを呼び出す。S_FALSE が返されて利用可能なイベントがなくなるまで、呼び出しごとに 1 つのイベントを受け取る。

次のコード例は、この処理を示している。

/* hEvent は CreateEvent で作成され、SetReadNotificationHandle の
呼び出しにより、キャプチャ ポートの pPort に
与えられる。また、pBuffer は IDirectMusic::CreateMusicBuffer に
よって初期化されているとする。*/

REFERENCE_TIME rt;
DWORD          dwGroup;
DWORD          cb;
BYTE          *pb;

DWORD dw = WaitForMultipleObjects(1, hEvent, FALSE, INFINITE);
for (;;)
{
hr = pPort->Read(pBuffer);
if (hr == S_FALSE)
      {
break;  // これ以上バッファに読み込むメッセージがない。
      }
pBuffer->ResetReadPtr();
for (;;)
    {
hr = pBuffer->GetNextEvent(&rt, &dwGroup, &cb, &pb);
if (hr == S_OK)
        {
// pb はメッセージのデータ構造体を指す。
// ポインタを使って、必要な操作を実行できる。
        }
else if (hr == S_FALSE)
        {
break;  // バッファにはメッセージが残っていない。
        }
}  // バッファの操作が終了。
}  // 未処理のイベントの読み込みが終了。

途中でメッセージを処理せずに、単にメッセージをポートからポートに送信する場合は、IDirectMusicThru インターフェイスを使用する。


DirectMusic ツール

DirectMusic におけるツールとは、メッセージを途中で取得して、何らかの方法で処理するオブジェクトを意味する。ツールはメッセージに変更を加えて次のツールに渡すか、メッセージを解放するか、元のメッセージ内の情報に基づいて新しいメッセージを送信するか、いずれかの方法で処理を行える。

DirectMusic には出力ツールがあり、通常はこのツールが最後にメッセージを受け取る。このツールは、パフォーマンス メッセージをスタンダード MIDI メッセージに変換し、シンセサイザへのストリームに入れる。ほかのツールは、アプリケーションによって実装するか、ライブラリから取得する。

[Visual Basic]

DirectX for Visual Basic では、アプリケーション定義のツール、またはサードパーティ製のツールはサポートされない。

[C++]

ツールを実装するには、IDirectMusicTool インターフェイスをサポートするオブジェクトを作成しなければならない。IDirectMusicTool メソッドのオブジェクト実装により、このツールがどのメッセージを取得するか、およびそのメッセージにどのような作業を行うかを決定する。

通常、出力ツール以外のすべてのツールはグラフに収集される。アプリケーションが、出力ツール以外に 1 つしかツールを使用していない場合でも、これを含めるための DirectMusicGraph を作成する。次に、そのグラフをセグメントかパフォーマンスに追加する。グラフは、ツール間でメッセージを転送する際に有効なメカニズムである。

パフォーマンス エンジンがセグメントを演奏するときに、セグメント グラフ内の各ツール、次いでパフォーマンス グラフ内の各ツールが、各メッセージを処理できる。あるツールがメッセージを処理した後、そのツールは IDirectMusicGraph::StampPMsg メソッドを呼び出し (DMUS_PMSG 構造体の pGraph メンバから IDirectMusicGraph ポインタを取得する)、次にそのメッセージを受け取るツールがある場合は、そのツールへのポインタをメッセージにスタンプする。次いで、このツールはメッセージをパイプラインへ返す。

ツールは、優先順位の高いスレッドでメッセージを処理する。ツールの IDirectMusicTool::ProcessPMsg メソッド内では、グラフィックスやファイル入出力などを行う時間のかかる関数を呼び出さないようにする。ツールがアクションをトリガする必要がある場合は、アプリケーションのメイン スレッドなどの別のスレッドに通知して実行する。

IDirectMusicTool のメソッドを実装するときに、親オブジェクトへの循環参照を作成しないように注意する。循環参照は、あるオブジェクトがほかのオブジェクトを作成したときに、子オブジェクトが親オブジェクトへの参照を維持している場合に発生する。たとえばツールが、IDirectMusicTool::Init メソッドに渡される、グラフへの新しい参照を作成する場合を考える。ツールがこの参照を解放できない場合、セグメントがグラフを解放しようとしたときに問題が発生する。ツールにはグラフへの参照が残っているため、グラフが完全に解放されない。また、グラフにはツールへの参照があるため、ツールも解放されない。

ツールの設定方法の詳細については、「チュートリアル 2 : ツールの使い方」を参照すること。


音楽のアレンジ

ここでは、DirectMusic のコンポーザ エンジンについて紹介する。エンジンを使用すると、既にオーサリングされているスタイル、テンプレート、バンドなどの要素を使って、動的にミュージック プログラムを実装することができる。

ここでは、次の項目について説明する。

  • ミュージック オーサリングの概要
  • アレンジ用のミュージック ファイル
  • アレンジ用のプログラミングの概要
  • 再生中の音楽の変化
  • ミュージック値と MIDI 音符
  • アレンジ要素の使い方


ミュージック オーサリングの概要

アレンジ用の音楽要素のオーサーは、DirectMusic Producer などのツールを使って、アプリケーションで必要な各音楽テーマの基本的な要素を作成する。次の各項目の詳細な情報については、DirectMusic Producer のドキュメントを参照すること。

  • スタイルのオーサリング
  • コード マップのオーサリング
  • スタイル ベースのセグメントのオーサリング
  • MIDI ベースのセグメントのオーサリング
  • テンプレートのオーサリング
  • バンドのオーサリング

注 : ここでは、DirectMusic のコンポーザ オブジェクトとの混同を避けるために、人間のコンポーザ (作曲者) をオーサーと表現する。


スタイルのオーサリング

スタイルとは音楽の基本的な定義である。スタイルはパターンの集まりであり、拍子記号とテンポ (1 分間の拍数) が含まれる。スタイルには、1 つまたは複数のバンドを含めることもできる。

パターンは、1 小節以上の長さの音型で、各音色の基本的な一連の音符、つまりパートで構成される。これらの音符は固定されていないが、最終的には、現在のキー、コード、および演奏モードに応じて、特定のピッチに割り当てられる。パターンには、バリエーションも含まれる。

モチーフは、基本スコア上でソロで演奏されるように計画された、特殊なパターンである。通常、モチーフは、インタラクティブ アプリケーションでイベントが発生したことを示すために使われる。たとえば、DMDonuts サンプル を例に取ると、宇宙船が画面の端に接したときにドラム ビートが演奏される。

DirectMusic Producer では、オーサーはピアノ ロールに似たグリッドを使ってパターンを作成する。各パートは (P チャンネルに対応する) 独自の行を持ち、音符はバーの長さ (持続時間)、太さ (ベロシティ)、縦軸方向の位置 (ピッチ)、および横軸方向の位置 (時間) で表される。

オーサーは、各パターンに対して多くのバリエーションを作成することができる。通常は、パターンをコピーして 1 部をわずかに変更することにより、バリエーションを作成できる。スタイルの再生メカニズムによって、実行時にバリエーションが選択される。ただし、オーサーは任意のコードに対してバリエーションを無効にすることもできる。つまり、特定のコードが演奏されているときは、あるバリエーションを決して選択しないよう指定できる。

オーサーは、パターンにグルーブ範囲を割り当てて、パターンを演奏できるグルーブ レベルを指定することもできる。

パターンは、装飾として指定することもできる。装飾には、イントロ、フィル、ブレーク、およびエンドの 4 種類があり、これらの 1 つまたは複数のカテゴリに、パターンを割り当てることができる。音楽の演奏中に特定の装飾が呼び出されると、その種類のパターンのみが再生の候補となる。


コード マップのオーサリング

現代の音楽の多く、特にポピュラー、ロック、フォーク、ジャズの特色はコード進行の概念に基づいており、特定の時間枠に演奏されるすべての音符が特定のコードに関連付けられていること、および音楽はあるコードから別のコードへと調和的に移行することを意味する。

DirectMusic 用にオーサリングされたパターンにある音符は、1 つのコードから派生しているか、コードと調和するよう意図されたものである。しかし実行時に、パターンはコード進行に合わせて転調する。つまり根底にあるコードの変化に応じて、DirectMusic は音符のピッチを変更する。

コード マップは、コード進行のロード マップである。コード マップ デザイナを使って、オーサーは希望の音楽感やパーソナリティを表現できるコードを選択する。オーサーはタイム ラインに沿って、フローチャート内でこれらのコードをアレンジする (タイム ラインには循環という概念があるので、ミュージック セクションの演奏が続く間、最初に戻ってループを形成する)。

特定の重要なコードをサインポストとして指定する。これらは、特定のポイントで演奏されなければならないコードである。音楽は、常にサインポストからサインポストへと移行する。しかし、サインポスト間のコード進行は、オーサーの指定したマップに従ってさまざまなルートをたどることもできる。

コード チャート内のルートは、コンポーザ エンジンによって実行時に選択することができる。この場合、パターン自体のバリエーションに追加してバリエーションが提供される。オーサーがセグメントを作成する際に、オーサリング ツールを使ってルートを選択することもできる。

コード マップのコードは、サブコードと呼ばれる、複数の異なるコードで構成することができる。同じコードを異なる転回で演奏して多調性を得るために、オーサーは異なるサブコードに別のパートを割り当てることができる。各サブコードは、1 つまたは複数のレベルで有効であり、スタイルのポートに割り当てられたレベルで調和する。

注 : DirectMusic では、コードに最大 DMUS_MAXSUBCHORD までのサブコードを含めることができる。この値は 8 に定義されているが、DirectMusic Producer では、現在のところ、1 コードに最大 4 つのサブコードしか作成できない。


スタイル ベースのセグメントのオーサリング

スタイル ベースのセグメントは、あらかじめ作成された、音楽の大きなピースであり、オーサーは次の要素を使ってセクションを構築する。

  • スタイル。スタイルは、パターンと同様、音楽に関する一般的な情報 (拍子記号やテンポなど) で構成される。
  • コード進行。オーサリング ツールがコード マップから自動的に派生したもの (コード チャートからパスを選択する)、またはオーサーが手作業で入力したもの。
  • 設定したタイムに適切なパターンを選択するための一連のコマンド。スタイル中のパターンの特徴は、装飾 (イントロ、フィル、ブレーク、およびエンド) として指定できること、およびオーサーが特定のグルーブ範囲を割り当てることができることである。セグメントのコマンド トラックは、スタイル再生エンジンに対して、イントロ パターンを選択して最初の小節で演奏し、次の 4 小節でグルーブ レベル が 25 のパターンのみを再生した後、ブレークを演奏する、などの動作を指示することができる。
  • バンド。オーサーは、音色と P チャンネルを、さまざまなパターンのすべてのパートに割り当てることができる。


MIDI ベースのセグメントのオーサリング

MIDI ベースのセグメントは、DirectMusic Producer で MIDI ファイルをインポートして作成される。オーサーは、ループ ポイントや、テンポ、キー、およびバンド チェンジを追加することができる。スタイル ベースのセグメントと異なり、MIDI セグメントにはパターンおよびコマンド トラックがない。これらの代わりにシーケンス トラックがあり、MIDI 音符とその他のコマンドはここに含まれる。


テンプレートのオーサリング

テンプレートはセグメントであるが、スタイル ベースのセグメントとは異なり、特定のスタイルに束縛されることはなく、固定コード進行も備えていない。

テンプレートはコード進行の代わりに、タイムラインに沿って一連のサインポスト グループ マーカーを備えている。サインポストは、コード進行のバリエーションが認められるリージョンの先頭と最後をマークするコードである。サインポストを作成するときに、オーサーはこれを 1 つのグループに割り当てる。

DirectMusicComposer が、テンプレートと特定のスタイルおよびコード マップを組み合わせてセグメントを生成するときに、オーサリング ツール内か実行時に、次のような処理が行われる。テンプレート内のタイム ラインに沿ってエンジンがサインポスト グループのマーカー ペアを見つけるたびに、エンジンはそのグループに所属するサインポスト コードのペアに対応するコード マップを参照する。ペアが見つかり、そのペア間の間隔が利用可能な時間に適合する場合は、エンジンはコード マップで定義されている 2 つのサインポスト コード間の固定コード進行に従う。ペア間の適切なパスが見つからない場合や、エンド サインポスト マーカーが存在しない場合は、エンジンは開始サインポスト グループ マーカーから派生した任意のコードを演奏する。

オーサーはセグメントを作成する際に、テンプレートを使って、複数のスタイルに類似のコード進行、グルーブ レベル、および装飾を適用することができる。ただし、DirectMusicComposer オブジェクトが実行時に、テンプレートをスタイルやコード マップと組み合わせる場合もある。


バンドのオーサリング

バンドとは一連の音色にそれぞれのパフォーマンス パラメータを組み合わせ、音楽のピース内の特定のパートを組み合わせたものである。バンドは DLS コレクションと同じではない。DLS コレクションはシンセサイザにダウンロードできる音色のセットを表し、任意のアプリケーションから利用することができる。

オーサーは DirectMusic Producerのようなツールを使って、楽器を P チャンネルに割り当てることによりバンドを作成するこれらの音色は任意の DLS コレクションから取得することができ、別のソースの音色を 1 つのバンドに混在させることもできる。たとえば、General MIDI セットのジャズ ギターをパート 1、Roland GS セットの 60 鍵オルガンをパート 2、カスタム DLS コレクションのエスニック パーカッションをパート 3 に配置できる。これらの各音色には、特定のボリューム、パン、転調の設定も割り当てられる。

P チャンネルは、音色をパートに割り当てる。パターンが P チャンネル 1 の特定の音符を呼び出す場合、この音符は P チャンネル 1 に割り当てられている現在のバンドの音色で演奏される。サウンドは、バンドで設定されている音色のボリューム、パン、および転調の値で修正される。

バンドは個別のファイルに保存するか、スタイルやセグメントに含められる。


アレンジ用のミュージック ファイル

DirectMusic のアレンジをプログラミングする場合、DirectMusic Producer のようなツールで作成したさまざまなファイルを使う。これらの要素を COM オブジェクトとしてアプリケーションにロードし、それらのオブジェクトへのインターフェイスを取得する (「DirectMusic ローダー」を参照すること)。

次の表に、開発者が扱うファイルのタイプを示す。

[C++]

クラス GUID は、オブジェクトをロードする際に DMUS_OBJECTDESC 構造体の guidClass メンバに書き込む値である。

要素 | クラス GUID | インターフェイス | ファイル タイプ
バンド | CLSID_DirectMusicBand | IDirectMusicBand | .bnd
DLS コレクション | CLSID_DirectMusicCollection | IDirectMusicCollection | .dls
コード マップ | CLSID_DirectMusicChordMap | IDirectMusicChordMap | .cdm
セグメント | CLSID_DirectMusicSegment | IDirectMusicSegment | .sgt
スタイル | CLSID_DirectMusicStyle | IDirectMusicStyle | .sty
テンプレート | CLSID_DirectMusicSegment | IDirectMusicSegment | .tpl

[Visual Basic]
要素 | DirectMusicLoader メソッド | クラス | ファイル タイプ
バンド | LoadBand | DirectMusicBand | .bnd
DLS コレクション | LoadCollection | DirectMusicCollection | .dls
コード マップ | LoadChordMap | DirectMusicChordMap | .cdm
セグメント | LoadSegment | DirectMusicSegment | .sgt
スタイル | LoadStyle | DirectMusicStyle | .sty
テンプレート | LoadSegment | DirectMusicSegment | .tpl

注 : バンドはスタイルの一部としてオーサリングできるが、その場合、スタイルをロードするときにそれらも自動的にロードされる。同様に、スタイルとバンドはセグメントにオーサリングできる。この場合、これらの要素を別のファイルに分ける必要ない。

ファイルには、ほかのファイルへの参照を含めることができる。スタイルにバンドへの参照が含まれている場合、ローダーがバンド ファイルを見つけることができれば、スタイルがロードされるときに自動的にバンドもロードされる。


アレンジ用のプログラミングの概要

実行時にアレンジされる音楽を実装するときに、既にオーサリングされているオブジェクトをビルディング ブロックとして使用する。オーサーやほかのコンテント プロバイダと相談しながら、小さなビルディング ブロックとして取得するミュージック データを選択することにより、実行時に最も高い柔軟性やバリエーションを実現したり、音楽をより完成された形で定義するために、あらかじめ作成された要素をより多く利用できる。

[C++]

最大のビルディング ブロックを使って、演奏する音楽についてパフォーマンスに指示しなければならない情報のすべてが含まれている、高度に構造化されたセグメント (スタイル ベースまたは MIDI ベース) をロードする。必要なのは、セクションをロードして、IDirectMusicSegment インターフェイスのクエリを行うことだけである。このインターフェイス ポインタを IDirectMusicPerformance::PlaySegment メソッドに渡す。スタイル再生エンジンは、スタイルからパターン バリエーションを選択し、固定コード進行に従ってこれらを演奏する。また、MIDI ベースのセグメントの場合は、MIDI シーケンスを演奏する。同様にバンド チェンジは、通常、セグメントに含まれる。

[Visual Basic]

最大のビルディング ブロックを使って、演奏する音楽についてパフォーマンスに指示しなければならない情報のすべてが含まれている、高度に構造化されたセグメント (スタイル ベースまたは MIDI ベース) をロードする。必要な作業は、DirectMusicLoader.LoadSegment または DirectMusicLoader.LoadSegmentFromResource メソッドを使ってセグメントをロードすることだけである。続いて、返された DirectMusicSegment オブジェクトを DirectMusicPerformance.PlaySegment メソッドに渡す。スタイル再生エンジンは、スタイルからパターン バリエーションを選択し、固定コード進行に従ってこれらを演奏する。また、MIDI ベースのセグメントの場合は、MIDI シーケンスを演奏する。同様にバンド チェンジは、通常、セグメントに含まれる。

より小さなビルディング ブロックを使う場合は、次の要素を取得する。

  • コード マップ。コード進行のロード マップを表す。
  • スタイル。基本的なメロディやリズムと共に、バリエーション、モチーフ、および装飾を定義する。
  • テンプレート セグメント。構造的な計画であり、セグメントの長さ、ループの有無、グルーブ レベルの変更や装飾を配置する場所、コード マップでサインポストの役割を果たすコードのタイプを含め、再生のさまざまな側面を制御する。
[C++]

IDirectMusicComposer::ComposeSegmentFromTemplate メソッドを使って、コード マップ、スタイル、およびテンプレートを組み合わせ、セグメントを構築する。

実行時の音楽アレンジをより柔軟に行うには、IDirectMusicComposer::ComposeSegmentFromShape メソッドを使って、テンプレートではなく定義済みのシェイプに基づくセグメントを作成する。シェイプは、コマンドおよびサインポスト トラックの作成に使用され、装飾パターン、コード進行、およびコード変更の頻度の選択を制御する。

セグメントを演奏するときに、パートの演奏に使用するバンドを制御することもできる。通常、バンドはスタイルおよびテンプレートの一部としてオーサリングされるが、アプリケーションが動的にバンド チェンジを行えるよう、バンドを個別のファイルとして供給することもできる。その場合、IDirectMusicBand::CreateSegment メソッドを使って、バンドだけからなるセカンダリ セグメントを作成し、音色や音色の設定をプライマリ セグメントに割り当てるときに、このセカンダリ セグメントを演奏しなければならない。詳細については、「バンドの使い方」を参照すること。

[Visual Basic]

DirectMusicComposer.ComposeSegmentFromTemplate メソッドを使って、コード マップ、スタイル、およびテンプレートを組み合わせ、セグメントを構築する。

実行時の音楽アレンジをより柔軟に行うには、DirectMusicComposer.ComposeSegmentFromShape メソッドを使って、テンプレートではなく定義済みのシェイプに基づくセグメントを作成する。シェイプは、コマンドおよびサインポスト トラックの作成に使用され、装飾パターン、コード進行、およびコード変更の頻度の選択を制御する。

セグメントを演奏するときに、パートの演奏に使用するバンドを制御することもできる。通常、バンドはスタイルおよびテンプレートの一部としてオーサリングされるが、アプリケーションが動的にバンド チェンジを行えるよう、バンドを個別のファイルとして供給することもできる。その場合、DirectMusicBand.CreateSegment メソッドを使って、バンドだけからなるセカンダリ セグメントを作成し、音色や音色の設定をプライマリ セグメントに割り当てるときに、このセカンダリ セグメントを演奏しなければならない。詳細については、「バンドの使い方」を参照すること。


再生中の音楽の変化

DirectMusic が (単純な MIDI ファイルや、MIDI ファイルに基づいてオーサリングされたセグメント以外の) セグメントを演奏するときに、演奏が同じに聞こえないように、基本的な和音とリズムに変更が加えられる。変更の一部はスクリプト化され、一部はランダムに行われる。

  • パターンの選択。一般的に、1 つのスタイルには複数のパターンが含まれる。これらのパターンは、コマンド トラックからのコマンドに応じて選択される。たとえば、コマンド トラックがブレーク装飾の演奏を要求すると、スタイル再生エンジンは現在のグルーブ レベルに矛盾しないブレーク パターンを選択する (オーサーは、各パターンにふさわしいグルーブ レベルを指定する)。適切なパターンがいくつかある場合は、いずれかがランダムに選択される。
  • パターン内のバリエーション。パターン内のパートには、複数のバリエーションを設定することができる。バリエーションは、オーサーが指定した順序で演奏することができる。それ以外の場合は、パターンの各繰り返しにおいて、スタイル再生エンジンがバリエーションをランダムに選択する。
  • グルーブ レベル。セグメントの現在のグルーブ レベルにより、スタイル内のどのパターンを再生用に選択できるかが決まる。現在のレベルを設定するのはコマンド トラックであるが、コマンド トラックは通常、セグメントかテンプレートの一部としてオーサリングされる。セグメントの現在のグルーブ レベルは、プログラム的に変更することができる。パフォーマンスのマスタ グルーブ レベルを設定することで、変更をすべてのセグメントに適用することができる。
  • 転調。セグメントを演奏するときに、根底にあるコードはコード トラックの進行に従って変化する。現在のパターンの音符は、新しいコードと調和するよう、自動的に転調される。
  • タイミングのバリエーション。再生エンジンは、個々の音符のパラメータ、つまり音符の開始時期と終了時期に、ランダムな変更を加えることができる。
  • バンド。セグメントの演奏中に、音色と音色の設定 (ボリューム、パン、および転調) の選択を、オーサリングされたセグメント内のバンド トラックで変更したり、アプリケーションで動的に変更することができる。アプリケーションは、バンド オブジェクトに基づいてセカンダリ セグメントを作成し、作成したセグメントを演奏することで、バンドを変更することができる。

アプリケーションはほとんどの場合、既存のセグメントを操作するのではなく、別のセグメントを演奏して音楽全体を制御する。たとえば、ゲームのインテンシティの変化を音楽に反映させるには、インテンシティ レベルに応じてオーサリングされた新しいセグメントに移行するだけでよい。オーサーにグルーブ範囲の異なるパターンを作成させ、ゲーム イベントに応じてグルーブ レベルを変更すると、1 つのスタイル ベースのセグメントでも同様のエフェクトを得ることができる。

実行時に音楽を変更する方法については、「ミュージック パラメータ」を参照すること。


ミュージック値と MIDI 音符

DirectMusic スタイル内のパターンの音符は、固定された音符ではない。これらの音符は、現在の演奏モードとサブコード レベルに応じて現在のコードに転調されたときにだけ実際の音符となる、ミュージック値である。

ミュージック値は、音符の意図的な役割を表すものである。たとえば、ミュージック値で、音符をコードの 2 番目の位置、1 つ上のスケールで演奏するように指定することができる。このミュージック値が特定のコードに適用されると、そのコードの 2 番目で、1 つ上のスケールの適切な MIDI 音符に変換される。

[C++]

ミュージック値のデータ形式の説明については、DMUS_NOTE_PMSG を参照すること。

[Visual Basic]

ミュージック値のデータ形式の説明については、DMUS_NOTE_PMSG を参照すること。

コードに対して音符がどのように解釈されるかは、演奏モードによって異なる。たとえば、モードが DMUS_PLAYMODE_NORMALCHORD の場合、音符はコードのルート音に基づいて、コードとスケールの音程として解釈される。モードが DMUS_PLAYMODE_FIXEDTOKEY の場合、音符は線形な値として解釈される。

[Visual Basic]

各演奏モードの詳細については、CONST_DMUS_PLAYMODE_FLAGS を参照すること。

サブコード レベルは 0 ～ 31 の値で、ミュージック値の確立に使用できるサブコードを決定する。DirectMusic コードは 1 つまたは複数のサブコードで構成され、複数の平行するコード進行を使って複雑な和音が可能となる。各サブコードは、1 つまたは複数のレベルをサポートする。オーサーは、各サブコードでサポートされるレベルを定義する。

セグメントが演奏されるときに、各音符は DMUS_NOTE_PMSG 型にカプセル化される。この型の midiValue メンバは、通常、シンセサイザに送信される MIDI 音符値を保持する。メッセージには、転調で使用される演奏モードとサブコード レベルや、オリジナルのミュージック値も保持される。

ミュージック値と演奏モードは、主にツールに関連があるが、これらは DirectX for Visual Basic ではサポートされていない。DirectMusicPerformance.SendNotePMSG を使って音符をパフォーマンスに挿入する場合、DMUS_NOTE_PMSG 型で目的の midiValue を指定し、musicValue、playModeFlags、および subChordLevel メンバは無視する。

次のコード例では、メッセージを送信して、直ちに中間の C を演奏している。

' perf は、DirectMusicPerformance を表す。
Dim note As DMUS_NOTE_PMSG

note.midiValue = 60
note.mtDuration = 500
note.flags = DMUS_NOTEF_NOTEON
note.velocity = 127
Call perf.SendNotePMSG(0, DMUS_PMSGF_REFTIME, 1, note)
[C++]

各演奏モードの詳細については、DMUS_PLAYMODE_FLAGS を参照すること。

サブコード レベルは 0 ～ 31 の値で、ミュージック値の確立に使用できるサブコードを決定する。DirectMusic コード (DMUS_CHORD_PARAM または DMUS_CHORD_KEY 構造体で表される) は、1 つまたは複数のサブコードで構成され、複数の平行するコード進行を使って複雑な和音が可能となる。各サブコードは、1 つまたは複数のレベルをサポートし、DMUS_SUBCHORD 構造体の dwLevels メンバで指定する。オーサーは、各サブコードでサポートされるレベルを定義する。

セグメントが演奏されるときに、各音符は DMUS_NOTE_PMSG 構造体にカプセル化される。この構造体の bMidiValue メンバは、通常、シンセサイザに送信される MIDI 音符値を保持する。メッセージには、転調で使用される演奏モードとサブコード レベルや、オリジナルミュージック値も保持される。ツールはこの情報を使って、音符を自由に変更することができる。たとえば、ツールは特定の演奏モードで転調される音符を割り込んで取得したり、演奏モードを変更することができる。また、IDirectMusicPerformance::MusicToMIDI メソッドを使って新しい MIDI 音符を取得したり、メッセージの bMidiValue メンバが渡される前に新しい値を設定することもできる。

MusicToMIDI メソッドは、DirectMusic のスタイル再生メカニズムの中心である。このメソッドはスタイル トラックによって呼び出され、コード トラックの現在のコードを使って、内部のミュージック値を音符に変換する。

ツールで処理を反転させ、別のコード、演奏モード、またはサブコード レベルを使って MIDI 音符から新しいミュージック値を取得する場合は、IDirectMusicPerformance::MIDIToMusic メソッドを呼び出す。新しいミュージック値は、音符メッセージの wMusicValue メンバに格納され、ほかのアプリケーション定義ツールで利用できる。ただし、DirectMusic 出力ツールはこれを無視し、通常どおり bMidiValue の音符を演奏する。


アレンジ要素の使い方

ここで説明する内容は、ミュージック コンポーネントを DirectMusic アプリケーションに組み込むためのガイドである。各コンポーネントの目的と、オブジェクトがコンポーネントを表す方法について基本的に理解していることを想定している。これらの内容を理解するには、「コンポーザ オブジェクトとインターフェイス」および「ミュージック オーサリングの概要」を参照すること。

スタイル、コード マップ、テンプレートなどの個々のコンポーネントを操作することなく、アプリケーションに DirectMusic を組み込むことができる。完全にオーサリングされたセグメントや、MIDI ファイルを処理することもできる。個々のコンポーネントを使うと、実行時にパフォーマンス全体をより詳細に制御することができる。

ここでは、次の項目を取り上げる。

  • オーサリングされたセグメントの使い方
  • スタイルの使い方
  • モチーフの使い方
  • コード マップの使い方
  • テンプレートの使い方
  • 移行部の使い方


オーサリングされたセグメントの使い方

オーサリングされたセグメントは、音楽のピースのデータをすべて含むファイルまたはリソースである。このセグメントは、MIDI ファイルか、スタイルおよびコード マップに基づいて作成することができる。単純な MIDI ファイルやリソースと異なり、バンド チェンジやバリエーションを含めることができる。

注 : 同様に、テンプレートもオーサリングされたセグメントであるが、これは音楽の組み込みピースを表すものではない。詳細については、「テンプレートの使い方」を参照すること。

[C++]

次のコード例に示すように、セグメントをオブジェクトとしてロードし、IDirectMusicSegment インターフェイスを取得して、アプリケーションでセグメントを作成する。この例では、セグメントは DirectMusic Producer ファイルからロードされている。

/* pLoader は IDirectMusicLoader インターフェイスへの
有効なポインタであり、検索ディレクトリは
適切に設定されているものとする。*/

DMUS_OBJECTDESC ObjectDescript;
IDirectMusicSegment* pSegment;

ObjectDescript.dwSize = sizeof(DMUS_OBJECTDESC);
ObjectDescript.idClass = CLSID_DirectMusicSegment;
strcpy(ObjectDescript.wszFileName, L"Dance.sgt");
ObjectDescript.dwValidData = DMOBJ_CLASS | DMOBJ_PATH ;
pLoader->GetObject(&ObjectDescript, IID_IDirectMusicSegment2,
    (void**) pSegment)))

この結果、IDirectMusicPerformance::PlaySegment メソッドに pSegment を渡せる。

[Visual Basic]

次のコード例に示すように、DirectMusicLoader.LoadSegment またはDirectMusicLoader.LoadSegmentFromResource メソッドを使って、アプリケーションでセグメントを作成する。この例では、セグメントは DirectMusic Producer ファイルからロードされている。

' loader は DirectMusicLoader オブジェクトである。
Dim seg As DirectMusicSegment
Set seg = loader.LoadSegment("Sample.sgt")

この結果、DirectMusicPerformance.PlaySegment メソッドに seg を渡せる。


スタイルの使い方

DirectMusicStyle オブジェクトは、音楽パターンの集まりを表す。通常は、装飾とモチーフ、拍子記号、テンポ、およびバンドが含まれる。基本的なリズムと、各音色パートで演奏される音符が定義される。

DirectMusicStyle オブジェクトは、スタイル ファイルかセクション ファイル、またはリソースから取得できる。詳細については、「DirectMusic ローダー」および「アレンジ用のミュージック ファイル」を参照すること。

スタイル単独では、実行時にミュージック セグメントを作成するのに十分な情報を備えていない。スタイルのほかに、コード マップ (コード進行のマップ) と、演奏時にグルーブ レベルと装飾を設定するコマンド トラックの、2 つのコンポーネントが必要となる。コマンド トラックはテンプレートから取り出すか、実行時にシェイプから生成する。コード マップは、通常はコード マップ ファイルかリソースから取得する。

[C++]

テンプレートに基づき、コマンド トラックを使ってセグメントを作成するには、IDirectMusicComposer::ComposeSegmentFromTemplate メソッドを呼び出す (「テンプレートの使い方」を参照すること)。

シェイプに基づいてセグメントを作成するには、IDirectMusicComposer::ComposeSegmentFromShape メソッドを呼び出す。スタイルへのポインタとコード マップへのポインタ、および作成されたセグメントへのポインタを受け取る変数を指定する。また、コード変更の頻度を制御する和音進行のレート、およびグルーブ レベルと装飾の進行を決定するシェイプ定数も指定する。

[Visual Basic]

テンプレートに基づき、コマンド トラックを使ってセグメントを作成するには、DirectMusicComposer.ComposeSegmentFromTemplate メソッドを呼び出す (「テンプレートの使い方」を参照すること)。

シェイプに基づいてセグメントを作成するには、DirectMusicComposer.ComposeSegmentFromShape メソッドを呼び出す。スタイルとコード マップへのポインタ、および作成されたセグメントへのポインタを受け取る変数を指定する。また、コード変更の頻度を制御する和音進行のレート、およびグルーブ レベルと装飾の進行を決定するシェイプ定数も指定する。


モチーフの使い方

モチーフとは、通常はインタラクティブ イベントに応じて演奏されるもので、基本的なスタイル パターン上で演奏されることを意図した、スタイル内の特種なパターンである。モチーフには、ほかのパターンと同様の複雑さを与えることができる。また、バリエーションや複数の音色パートを備えることも可能であるが、通常はさまざまなバックグラウンド パターンと組み合わせても適切に聞こえる、短い単純な音型である。カスタム DLS 音色で演奏するサウンド エフェクトにもなる。

[C++]

どのモチーフもスタイルの一部としてオーサリングされるので、スタイルをロードするとすぐにモチーフを利用できる。特定のモチーフを再生できるようにするには、IDirectMusicStyle::GetMotif メソッドを呼び出し、次のパラメータを渡す。

  • モチーフ名。スタイルに関するドキュメントからこの情報を得るか、IDirectMusicStyle::EnumMotif メソッドを使ってインデックス番号から取得できる。
  • メソッドが作成するセグメント オブジェクトへの IDirectMusicSegment インターフェイスを受け取るポインタ。

次のコード例では、pwszMotifName で名前を指定されたモチーフを取得し、演奏する。

void PlayMotif(IDirectMusicPerformance* pPerf,
         IDirectMusicStyle* pStyle,
         WCHAR* pwszMotifName)
{
  IDirectMusicSegment* pSeg;

// スタイルからモチーフ セグメントを取得する。GetMotif() は、
// モチーフを見つけられなかった場合は S_FALSE を返すので、
// S_OK が返されることを確認する。

  if (S_OK == pStyle->GetMotif(pwszMotifName, &pSeg))
  {
/* セグメントを演奏する。DMUS_SEGF_BEAT は、現在演奏中のセグメントが
ある場合に、次の拍を演奏することを意味する。DMUS_SEGF_SECONDARY は、
セグメントをセカンダリ セグメントとして演奏することを意味する。
セカンダリ セグメントは、現在演奏中のプライマリ セグメント上で演奏される。0 は、
すぐに演奏を開始することを意味する。最後の NULL は、
再生の状態を追跡する必要がないため、
最後のパラメータに IDirectMusicSegmentState* を返さないことを意味する。*/

    pPerf->PlaySegment(pSeg,
                       DMUS_SEGF_BEAT | DMUS_SEGF_SECONDARY,
                       0,
                       NULL);
    pSeg->Release();
  }
}

通常、モチーフはプライマリ セグメントに重ねて演奏されるため、pSeg はセカンダリ セグメントとして演奏される点に注意すること。モチーフにはコード トラックやバンド トラックがないため、これをプライマリ セグメントとして演奏することはできない。無音の状態のときにモチーフを演奏する場合は、スタイルから空白のパターンだけを含むプライマリ セグメントを作成し、モチーフを演奏する間、このセグメントを演奏しておく。

[Visual Basic]

どのモチーフもスタイルの一部としてオーサリングされるので、スタイルをロードするとすぐにモチーフを利用できる。特定のモチーフを再生できるようにするには、IDirectMusicStyle::GetMotif メソッドを呼び出し、モチーフの名前を渡す。この情報はスタイルのドキュメントで確認するか、DirectMusicStyle.GetMotifName メソッドを使ってインデックス値から取得する。

次のコード例では、スタイルの最初のモチーフを取得して演奏している。

' style は DirectMusicStyle である。
' perf は DirectMusicPerformance である。
Dim MotifName As String
Dim segMotif As DirectMusicSegment

MotifName = style.GetMotifName(0)
Set segMotif = style.GetMotif(MotifName)
Call perf.PlaySegment(segMotif, DMUS_SEGF_SECONDARY, 0)

通常、モチーフはプライマリ セグメントに重ねて演奏されるため、segMotif はセカンダリ セグメントとして演奏される点に注意すること。モチーフにはコード トラックやバンド トラックがないため、これをプライマリ セグメントとして演奏することはできない。無音の状態のときにモチーフを演奏する場合は、スタイルから空白のパターンだけを含むプライマリ セグメントを作成し、モチーフを演奏する間、このセグメントを演奏しておく。


コード マップの使い方

コード マップ オブジェクトは、基礎となる和音構造と音楽の雰囲気を提供するコードのコレクションを表す。コード マップには、多くの関連するコードによるいくつかのパスが含まれ、コンポーザ エンジンが音楽のピースのコード進行を決定する際に、さまざまな選択が可能となる。

オーサリングされたセグメントの場合、通常、アプリケーションはコード マップに関与する必要はない。コード マップは、固定コード進行を作成するために、オーサリングの段階で使用される。ただし、コード マップを使って、実行時にセグメントを作成したり、既存のセグメントのコード進行を変更することもできる。

DirectMusicChordMap オブジェクトは、コード マップ ファイルかリソースから取得する。詳細については、「DirectMusic ローダー」および「アレンジ用のミュージック ファイル」を参照すること。

[C++]

スタイルの一部としてコード マップをオーサリングした場合は、IDirectMusicStyle::GetChordMap メソッドに (オーサーが割り当てた) コード マップの名前を渡して、IDirectMusicChordMap インターフェイスへのポインタを取得することができる。IDirectMusicStyle::EnumChordMap メソッドを使って、特定のコード マップを検索することもできる。また、IDirectMusicStyle::GetDefaultChordMap メソッドを使って、スタイルのデフォルト コード マップへのポインタを取得することもできる。

注 : DirectMusic Producer では、スタイル ファイルへのコード マップのオーサリングはサポートされていない。

IDirectMusicComposer::ComposeSegmentFromTemplate または IDirectMusicComposer::ComposeSegmentFromShape メソッドを使ってセグメントを作成するときに、アレンジ用のコード マップを設定する。詳細については、「スタイルの使い方」を参照すること。

セグメントを作成した後で、IDirectMusicComposer::ChangeChordMap メソッドを呼び出して、いつでもコード マップを変更できる。これにより、基本的なリズムやメロディを変えることなく、音楽の雰囲気が変更される。

各コード マップは、24 の音程から成る基調のスケールを持つ。IDirectMusicChordMap::GetScale メソッドを使って、スケールの音程を決定することができる。このメソッドの pdwScale パラメータで示される変数の下位 24 ビットは、対応する音程がスケールの一部になっているかどうかに応じてセットまたは消去される。上位 8 ビットは、スケールのルート音を、0 ～ 23 の範囲 (低い C から中間の B) の整数で設定する。

[Visual Basic]

DirectMusicComposer.ComposeSegmentFromTemplate または DirectMusicComposer.ComposeSegmentFromShape を使ってセグメントを作成するときに、アレンジ用のコード マップを設定する。詳細については、「スタイルの使い方」を参照すること。

セグメントを作成した後で、DirectMusicComposer.ChangeChordMap メソッドを呼び出して、いつでもコード マップを変更できる。これにより、基本的なリズムやメロディを変えることなく、音楽の雰囲気が変更される。


テンプレートの使い方

テンプレートは、演奏可能な音楽のセグメントを実行時にアレンジするときに使用できる、特殊なセグメントである。テンプレートは、セグメントの長さとループ ポイントを設定する。コマンド トラックが提供され、グルーブ レベルの変更や、装飾パターンの選択が制御される。また、新しいコードをそれぞれどのサインポスト グループから取得するかを指定して、セグメントをアレンジするときにコード マップをどのように使用するかも指示する。

[C++]

各テンプレートは DirectMusicSegment オブジェクトによって表される。

テンプレートを取得する方法は 2 つある。

  • テンプレート ファイルまたはリソースからテンプレートを取得する。このファイルを DirectMusicObject としてロードし、IDirectMusicSegment インターフェイスのクエリを行う。詳細については、「DirectMusic ローダー」を参照すること。
  • IDirectMusicComposer::ComposeTemplateFromShape メソッドを使って、シェイプからテンプレートを作成する。テンプレートの長さ、全体のシェイプ、イントロとエンドの装飾パターンを演奏するかどうか、およびエンディングの長さを選択する。IDirectMusicSegment インターフェイスへのポインタが返される。

テンプレート セグメント オブジェクトを取得した後、スタイルやコード マップへのポインタと共に、そのオブジェクトを IDirectMusicComposer::ComposeSegmentFromTemplate メソッドに渡せる。また、コード変更の頻度を設定する和音進行も指定する。ComposeSegmentFromTemplate メソッドはセグメントを作成し、その IDirectMusicSegment インターフェイスへのポインタを、ppSectionSeg パラメータで指定されたアドレスに返す。次に、このポインタを IDirectMusicPerformance::PlaySegment メソッドに渡す。

[Visual Basic]

各テンプレートはDirectMusicSegment オブジェクトによって表される。

テンプレートを取得する方法は 2 つある。

  • DirectMusicLoader.LoadSegment または DirectMusicLoader.LoadSegmentFromResource を使って、テンプレート ファイルまたはリソースから取得する。
  • DirectMusicComposer.ComposeTemplateFromShape メソッドを使って、シェイプからテンプレートを作成する。テンプレートの長さ、全体のシェイプ、イントロとエンドの装飾パターンを演奏するかどうか、およびエンディングの長さを選択する。

テンプレート セグメント オブジェクトを取得した後、スタイルやコード マップへのポインタと共に、そのオブジェクトを DirectMusicComposer.ComposeSegmentFromTemplate メソッドに渡せる。また、コード変更の頻度を設定する和音進行も指定する。ComposeSegmentFromTemplate メソッドは、DirectMusicPerformance.PlaySegment メソッドに渡せるセグメントを作成する。


移行部の使い方

あるセグメントを停止して次のセグメントを始める際に、耳障りな中断が突然発生することを防止するため、または音楽を終止形 (カデンツァ) へ移行するために、適切な移行部を提供する中間または終始のセグメントを作成するようコンポーザに指示できる。

[C++]

移行部セグメントの作成には、次の 2 つのメソッドを使用する。

  • IDirectMusicComposer::AutoTransition メソッドは、パフォーマンスへのポインタを受け取り、現在演奏中のセグメントから開発者が指定した 2 番目のセグメントへの移行部を作成する。続いて、再生の目的で移行部セグメントと 2 番目のセグメントを自動的に挿入し、これら両方のセグメントへの IDirectMusicSegmentState インターフェイスを返す。移行部の演奏は、直ちに、または dwFlags パラメータで指定された次の境界から開始される。オプションで、2 番目のセグメントを NULL にもできるが、その場合は移行部を経て無音に至る。
  • IDirectMusicComposer::ComposeTransition メソッドは、1 番目のセグメントの任意の場所から 2 番目のセグメントの先頭または無音に至る移行部を作成し、アプリケーションが移行部を演奏できるように IDirectMusicSegment インターフェイスへのポインタを返す。

どちらのメソッドもパラメータとして、コード マップ、コマンド、および一連のフラグを受け取る。

  • コード マップは、通常どおり、セグメントのコード進行を定義するコード トラックを作成するために使用される。
  • コマンドとして、DMUS_COMMANDT_TYPES 列挙型のいずれかを指定する。コマンドは、移行部セグメントのコマンド トラックで要求するパターンのタイプとして、通常のグルーブ パターンと装飾のどちらを使うかを決定する。セグメントを演奏する際に、スタイルから適切なパターンが選択される。
  • DMUS_COMPOSEF_FLAGS からフラグを選択し、移行部の詳細、特にそのタイミングを定義する。DMUS_COMPOSEF_MODULATE フラグを使って、移行部をある調性から他の調性へ円滑に移行させる。2 番目のセグメントがない場合、無音への変調は不可能なので、このフラグは利用できない。
[Visual Basic]

移行部セグメントの作成には、次の 2 つのメソッドを使用する。

  • DirectMusicComposer.AutoTransition メソッドは、DirectMusicPerformance を受け取り、現在演奏中のセグメントから開発者が指定した 2 番目のセグメントへの移行部を作成する。続いて、再生の目的で移行部セグメントと 2 番目のセグメントを自動的に挿入する。移行部の演奏は、直ちに、または IFlags パラメータで指定された次の境界から開始される。オプションで、2 番目のセグメントを Nothing にもできるが、その場合は移行部を経て無音に至る。
  • DirectMusicComposer.ComposeTransition メソッドは、1 番目のセグメントの任意の場所から 2 番目のセグメントの先頭または無音に至る移行部を作成し、アプリケーションが移行を演奏できるように DirectMusicSegment オブジェクトを返す。

どちらのメソッドもパラメータとして、コード マップ、コマンド、および一連のフラグを受け取る。

  • コード マップは、通常どおり、セグメントのコード進行を定義するコード トラックを作成するために使用される。
  • コマンドとして、CONST_DMUS_COMMANDT_TYPES 列挙型のいずれかを指定する。コマンドは、移行部セグメントのコマンド トラックで要求するパターンのタイプとして、通常のグルーブ パターンと装飾のどちらを使うかを決定する。セグメントを演奏する際に、スタイルから適切なパターンが選択される。
  • CONST_DMUS_COMPOSEF_FLAGS からフラグを選択し、移行部の詳細、特にそのタイミングを定義する。DMUS_COMPOSEF_MODULATE フラグを使って、移行部をある調性から他の調性へ円滑に移行させる。2 番目のセグメントがない場合、無音への変調は不可能なので、このフラグは利用できない。

移行部の長さは、通常 1 小節である。ただし、DMUS_COMPOSEF_LONG フラグが含まれる場合、およびコマンドが DMUS_COMMANDT_END で、スタイル内のエンド装飾が 1 小節より長い場合は例外である。


DirectMusic チュートリアル

ここでは、Microsoft® DirectMusic® の基本的な機能を実装する方法についてステップ バイ ステップで説明するチュートリアルを提供する。

  • DirectMusic C/C++ チュートリアル
  • DirectMusic Visual Basic チュートリアル


DirectMusic C/C++ チュートリアル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

ここでは、次のチュートリアルを使用して、C または C++ アプリケーションに DirectMusic を実装する方法を説明する。

  • チュートリアル 1 : MIDI ファイルの演奏
  • チュートリアル 2 : ツールの使い方
  • チュートリアル 3 : アレンジの方法


チュートリアル 1 : MIDI ファイルの演奏

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルは、プライマリ セグメントを演奏するだけの、最も簡単な DirectMusic アプリケーションを設定するためのガイドである。この例では、セグメントは 1 つの MIDI ファイルを表しているが、ソースが DirectMusic Producer などのツールでオーサリングされた 1 つのセグメントである場合も、データのロードと演奏のプロセスはまったく同じである。

このチュートリアルは、次のステップで構成されている。

  • ステップ 1 : COM の初期化
  • ステップ 2 : パフォーマンスの作成
  • ステップ 3 : ローダーの作成
  • ステップ 4 : MIDI ファイルのロード
  • ステップ 5 : MIDI ファイルの演奏
  • ステップ 6 : DirectMusic のシャットダウン


ステップ 1 : COM の初期化

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

DirectMusic の何らかの呼び出しを行う前に、次の方法で COM を初期化しなければならない。

if (FAILED(CoInitialize(NULL)))
{
// アプリケーションを終了する。
}   // 成功したら次へ進む。

次項 : ステップ 2 : パフォーマンスの作成


ステップ 2 : パフォーマンスの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

どの DirectMusic アプリケーションでも中心となるオブジェクトはパフォーマンスであり、セグメントの再生を管理する。次のサンプル関数のように、COM の CoCreateInstance 関数を使ってパフォーマンスを作成する。

IDirectMusicPerformance* CreatePerformance(void)
{
    IDirectMusicPerformance* pPerf;

    if (FAILED(CoCreateInstance(
            CLSID_DirectMusicPerformance,
            NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicPerformance2,
            (void**)&pPerf
        )))
    {
        pPerf = NULL;
    }
    return pPerf;
}

この関数を使ってグローバル パフォーマンス ポインタを初期化し、後のステップで利用できる。

IDirectMusicPerformance* g_pPerf = CreatePerformance();
if (g_pPerf == NULL)
{
    // 失敗。パフォーマンスは作成されていない。
}

作成したパフォーマンスは、IDirectMusicPerformance::Init メソッドを呼び出して初期化する必要がある。メソッドは DirectMusic オブジェクトを作成して、デフォルト ポートを管理する。IDirectMusic のメソッドに直接アクセスする必要はないため、ポインタを取得する必要ない。したがって、Init の最初のパラメータには NULL を渡す。また、IDirectSound のポインタおよびウィンドウ ハンドルとして NULL を渡すと、DirectMusic は DirectSound オブジェクトを作成し、協調レベルを設定するときに現在のフォーカス ウィンドウを渡す。

if (FAILED(g_pPerf->Init(NULL, NULL, NULL)))
{
    // 失敗。パフォーマンスは初期化されていない。
};

パフォーマンスを作成した後で、初期化を行い、ポートを追加する必要がある。NULL パラメータを渡して IDirectMusicPerformance::AddPort メソッドを呼び出すと、自動的に 1 つのチャンネル グループと共にデフォルト ポート (通常は Microsoft Software Synthesizer) が追加され、そのグループの MIDI チャンネルに P チャンネル 0-15 が割り当てられる。

if (FAILED(pPerf->AddPort(NULL)))
{
// 失敗。ポートは初期化されていない。
}

次項 : ステップ 3 : ローダーの作成


ステップ 3 : ローダーの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

ディスクから何かオブジェクトをロードするには、最初に DirectMusicLoader オブジェクトを作成する必要がある。次のサンプル関数で示すとおり、他の COM オブジェクトを作成する場合と同様である。

IDirectMusicLoader* CreateLoader(void)
{
    IDirectMusicLoader* pLoader;

    if (FAILED(CoCreateInstance(
            CLSID_DirectMusicLoader,
            NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicLoader,
            (void**)&pLoader
        )))
    {
        pLoader = NULL;
    }
    return pLoader;
}

グローバル変数の初期化に、この関数を使う。

IDirectMusicLoader* g_pLoader = CreateLoader();
if (g_pLoader == NULL)
{
    // 失敗。ローダーは作成されていない。
}

次項 : ステップ 4 : MIDI ファイルのロード


ステップ 4 : MIDI ファイルのロード

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

このステップでは、関数 LoadMIDISegment を実装する。この関数は前のステップで作成した IDirectMusicLoader へのポインタを取得し、そのポインタを使って、MIDI ファイルからデータをカプセル化したセグメント オブジェクトを作成する。

IDirectMusicSegment* LoadMIDISegment(IDirectMusicLoader* pLoader,
        WCHAR wszMidiFileName )
{
    DMUS_OBJECTDESC ObjDesc;
    IDirectMusicSegment* pSegment = NULL;

演奏する MIDI ファイルはすべて、現在の作業ディレクトリに保存されているとする。検索ディレクトリを設定して、ローダーにディレクトリを指示する必要がある (検索ディレクトリをほかの場所に変更しない場合、この操作が必要なのは 1 度だけである。ファイルをロードするごとに指定する必要はない)。

    char szDir[_MAX_PATH];
    WCHAR wszDir[_MAX_PATH];

    if(_getcwd( szDir, _MAX_PATH ) == NULL)
    {
        return NULL;
    }

/*
次のマクロを使って、マルチバイト フォーマットから Unicode に変換する。
#define MULTI_TO_WIDE( x,y )  MultiByteToWideChar( CP_ACP, \
MB_PRECOMPOSED, y, -1, x, _MAX_PATH );
*/

    MULTI_TO_WIDE(wszDir, szDir);
    HRESULT hr = pLoader->SetSearchDirectory(GUID_DirectMusicAllTypes,
        wszDir, FALSE);
    if (FAILED(hr))
    {
        return NULL;
    }

次に DMUS_OBJECTDESC 構造体で、ロードするオブジェクトを記述する。

    ObjDesc.guidClass = CLSID_DirectMusicSegment;
    ObjDesc.dwSize = sizeof(DMUS_OBJECTDESC);
    wcscpy( ObjDesc.wszFileName, wszMidiFileName );
    ObjDesc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME;

ここで、オブジェクトをロードし、IDirectMusicSegment インターフェイスのクエリを行う。この操作は、IDirectMusicLoader::GetObject を一度呼び出すことで実行される。オブジェクトをロードすると、トラックが初期化され、MIDI データの再生を準備するために必要なすべての作業が行われる点に注意すること。

pLoader->GetObject(&ObjDesc,
IID_IDirectMusicSegment2, (void**) &pSegment);

セグメントをスタンダード MIDI ファイルとして演奏するには、ここでバンド トラックにパラメータを設定する必要がある。dwGroupBits メソッド パラメータに -1 (または、0xFFFFFFFF) を渡し、IDirectMusicSegment::SetParam メソッドを使ってトラックを検索する。

g_pMIDISeg->SetParam(GUID_StandardMIDIFile,
-1, 0, 0, (void*)g_pPerf);

DirectMusic がプログラム変更およびバンク選択を処理する方法は、スタンダード MIDI ファイルの場合と、DirectMusic 用にオーサリングされた MIDI コンテンツの場合では異なるため、このステップが必要となる。GUID_StandardMIDIFile パラメータは、音色をダウンロードする前に設定しなければならない。

次のステップは、音色のダウンロードである。デフォルトのソフトウェア シンセサイザは、General MIDI 音色セットの DLS データを必要とするため、単純な MIDI ファイルを演奏する場合でも、このステップが必要となる。このステップを省略すると、MIDI ファイルを演奏しても無音となる。GUID_Download パラメータを指定するために、もう一度セグメントで SetParam を呼び出す。

g_pMIDISeg->SetParam(GUID_Download, -1, 0, 0, (void*)g_pPerf);

LoadMIDISegment 関数で既にこの操作が完了している場合でも、ダウンロードの要求による実害はない点に注意すること。余分な要求は単に無視される。最終的には音色をアンロードしなければならないが、DirectMusic をシャットダウンする準備ができるまで待機することができる。

ここで、関数は演奏準備のできたセグメントへのポインタを返す。

    return pSegment;

} // LoadSegment()の終わり

新しいセグメントをロードする前に、既存のセグメントをクリーンアップする。続いて、LoadMIDISegment 関数にファイル名を渡す。

if (g_pMIDIseg)
{
    g_pMIDIseg->Release();
    g_pMIDIseg = NULL;
}

if (g_pLoader)
{
    IDirectMusicSegment* g_pMIDIseg = LoadMIDISegment(g_pLoader,
            L"tune.mid");
}

次項 : ステップ 5 : MIDI ファイルの演奏


ステップ 5 : MIDI ファイルの演奏

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

これまでのステップで、準備作業はすべて完了している。音楽の演奏自体は簡単である。

IDirectMusicSegmentState* g_pSegState;
if (g_pMIdiSEG)
{
    g_pPerf->PlaySegment(g_pMIDISeg, 0, 0, &g_pSegState);
}

IDirectMusicPerformance::PlaySegment を呼び出す際に、以下のパラメータを使う。

  • 前のステップで作成したセグメント。
  • 一連のタイミング フラグと開始タイム (ただし、ここでは即座にセグメントを演奏するだけなので必要ない)。
  • セグメント状態オブジェクトへのポインタのアドレス。返されたポインタを使って、セグメントに関する情報を取り出せる。セグメント状態が必要ない場合、このパラメータを NULL にできる。

ファイルを複数回再生したい場合、PlaySegment を呼び出す前に IDirectMusicSegment::SetRepeats メソッドを呼び出さなければならない。

音楽が最後に到達する前、またはリピートが終わる前に再生を停止するには、IDirectMusicPerformance::Stop メソッドを使う。このメソッドを使う最も単純な方法は、次のように、現在演奏中および演奏の目的でキューに置かれているすべての音楽を即座に停止することである。

g_pPerf->Stop(NULL, NULL, 0, 0)

代わりに、現在のセグメントへのポインタまたはセグメント状態へのポインタを指定し、ただ 1 つのセグメント、またはセグメントの 1 つのインスタンスを停止することもできる。

次項 : ステップ 6 : DirectMusic のシャットダウン


ステップ 6 : DirectMusic のシャットダウン

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

終了する前に、プログラムは音色のアンロード、作成したすべてのオブジェクトの解放、および COM の参照の解除を実行しなければならない (CoInitialize の呼び出し 1 つにつき、CoUninitialize の呼び出し 1 つを対応させなければならない点に注意すること)。

必要なクリーンアップを実行するには、次の関数を使用する。

HRESULT FreeDirectMusic()
{
// 演奏中の音楽がある場合は、演奏を中止する。実際には、
// 音色をアンロードするとき、または
// パフォーマンスをクローズするときに音楽は停止するので、
// この処理は必ずしも必要ではない。
g_pPerf->Stop( NULL, NULL, 0, 0 );

// 音色をアンロードする。これにより、無音になる。
// CloseDown はすべての音色をアンロードする。
// したがって、この呼び出しは必要である。
g_pMIDISeg->SetParam(GUID_Unload, -1, 0, 0, (void*)g_pPerf);

// セグメントを解放する。
g_pMIDISeg->Release();

// パフォーマンス オブジェクトをクローズし、解放する。
g_pPerf->CloseDown();
g_pPerf->Release();

// ローダー オブジェクトを解放する。
g_pLoader->Release();

// COM を解放する。
CoUninitialize();

return S_OK;
}


チュートリアル 2 : ツールの使い方

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、ツールを C++のクラスとして実装し、DirectMusic アプリケーションで利用する方法を示す。CEchoTool クラスを使うと、アプリケーションはパフォーマンス内のすべての音符に 1 つまたは複数のエコーを追加できる。

以下のサンプルコードは、DirectX に付属のサンプル アプリケーション Echotool に基づいている。

このチュートリアルは、以下のステップで構成されている。

  • ステップ 1 : ツール クラスの宣言
  • ステップ 2 : IUnknown メソッドの定義
  • ステップ 3 : メッセージ タイプの指定
  • ステップ 4 : ProcessPMsg メソッドの定義
  • ステップ 5 : クラス メソッドの定義
  • ステップ 6 : パフォーマンスへのツールの追加


ステップ 1 : ツール クラスの宣言

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

DirectMusic のツールを C++で作成する最初のステップは、IDirectMusicTool の派生クラスを宣言することである。

ここにサンプルの CEchoTool クラスの宣言を示す。

class CEchoTool : public IDirectMusicTool
{
public:
  CEchoTool();
  ~CEchoTool();

public:
// IUnknown
  virtual STDMETHODIMP QueryInterface(const IID &iid, void **ppv);
  virtual STDMETHODIMP_(ULONG) AddRef();
  virtual STDMETHODIMP_(ULONG) Release();

// IDirectMusicTool
  HRESULT STDMETHODCALLTYPE Init(
          IDirectMusicGraph* pGraph);
  HRESULT STDMETHODCALLTYPE GetMsgDeliveryType(
          DWORD* pdwDeliveryType);
  HRESULT STDMETHODCALLTYPE GetMediaTypeArraySize(
          DWORD* pdwNumElements);
  HRESULT STDMETHODCALLTYPE GetMediaTypes(
          DWORD** padwMediaTypes,
          DWORD dwNumElements);
  HRESULT STDMETHODCALLTYPE ProcessPMsg(
          IDirectMusicPerformance* pPerf,
          DMUS_PMSG* pDMUS_PMSG);
  HRESULT STDMETHODCALLTYPE Flush(
         IDirectMusicPerformance* pPerf,
         DMUS_PMSG* pDMUS_PMSG,
         REFERENCE_TIME rtTime);
private:
  long m_cRef;                // 参照カウンタ。
  DWORD m_dwEchoNum;          // 生成するエコーの数。
  MUSIC_TIME m_mtDelay;       // エコー間の遅延時間
  CRITICAL_SECTION m_CrSec;   // SetEchoNum()と SetDelay()
                              //   をスレッドセーフにする。
public:
// パブリック クラス メソッド
  void SetEchoNum(DWORD);
  void SetDelay(MUSIC_TIME);
};

次項 : ステップ 2 : IUnknown メソッドの定義


ステップ 2 : IUnknown メソッドの定義

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

サンプルの CEchoTool クラスの継承メソッド IUnknown は次のように実装されている。

STDMETHODIMP CEchoTool::QueryInterface(const IID &iid, void **ppv)
{
  if (iid == IID_IUnknown || iid == IID_IDirectMusicTool)
  {
    *ppv = static_cast<IDirectMusicTool*>(this);
  } else
  {
    *ppv = NULL;
    return E_NOINTERFACE;
  }

  reinterpret_cast<IUnknown*>(this)->AddRef();
  return S_OK;
}

STDMETHODIMP_(ULONG) CEchoTool::AddRef()
{
    return InterlockedIncrement(&m_cRef);
}

STDMETHODIMP_(ULONG) CEchoTool::Release()
{
    if( 0 == InterlockedDecrement(&m_cRef) )
    {
        delete this;
        return 0;
    }
    return m_cRef;
}

次項 : ステップ 3 : メッセージ タイプの指定


ステップ 3 : メッセージ タイプの指定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

CEchoTool クラスでは、すべての IDirectMusicTool メソッドを定義する必要がある。しかし Init や Flush 内で作業を行う必要はなく、これらのメソッドは単純に E_NOTIMPL を返す。

以下のメソッドを使って、処理の目的でこのツールに渡すメッセージを指定する。

  • GetMsgDeliveryType は、メッセージをツールに渡す時期を指定する。利用可能になった直後、メッセージにスタンプされたタイムちょうど、処理とポート バッファへの配置の準備ができたとき、が選択できる。これら 3 種類の「配信タイプ」は、それぞれ DMUS_PMSG 構造体の dwFlags メンバ内の DMUS_PMSGF_TOOL_IMMEDIATE、DMUS_PMSGF_TOOL_ATTIME、DMUS_PMSGF_TOOL_QUEUE の各フラグで表される。
  • GetMediaTypes は、メッセージの内容に基づいて、どのタイプのメッセージをツールに渡すべきかを決定する。CEchoTool は音符とパッチ チェンジだけを処理するので、MIDI ショート メッセージ、音符メッセージ、および DirectMusic パッチ メッセージだけを受け入れる。これらのメッセージは、DMUS_PMSG メッセージ構造体の DMUS_PMSGT_TYPES 列挙型のフラグによって識別される。
  • GetMediaTypeArraySize は、メディア タイプ配列内の要素の数を返す。

CEchoTool は、次のサンプルコード内でこれらのメソッドを実装する。

HRESULT STDMETHODCALLTYPE CEchoTool::GetMsgDeliveryType(
        DWORD* pdwDeliveryType )
{
// このツールはメッセージを即座に必要とする。
// これはデフォルトであり、E_NOTIMPL を返すと
// 正常に動作する。もう 1 つの方法は、
// *pdwDeliveryType を DMUS_PMSGF_TOOL_IMMEDIATE、
// DMUS_PMSGF_TOOL_QUEUE、および DMUS_PMSGF_TOOL_ATTIME の
// いずれかの配信タイプに明確に設定することである。

    *pdwDeliveryType = DMUS_PMSGF_TOOL_IMMEDIATE;
  return S_OK;
}

HRESULT STDMETHODCALLTYPE CEchoTool::GetMediaTypeArraySize(
        DWORD* pdwNumElements)
{
  *pdwNumElements = 3;
  return S_OK;
}

HRESULT STDMETHODCALLTYPE CEchoTool::GetMediaTypes(
        DWORD** padwMediaTypes,
        DWORD dwNumElements)
{
  if (dwNumElements == 3)
  {
    (*padwMediaTypes)[0] = DMUS_PMSGT_NOTE;
    (*padwMediaTypes)[1] = DMUS_PMSGT_MIDI;
    (*padwMediaTypes)[2] = DMUS_PMSGT_PATCH;
    return S_OK;
  }
  else
  {
    // これは決して発生しないはずである。
    return E_FAIL;
  }
}

次項 : ステップ 4 : ProcessPMsg メソッドの定義


ステップ 4 : ProcessPMsg メソッドの定義

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

このツールの実際の動作は、IDirectMusicTool::ProcessPMsg から派生したメソッド内で実行される。IDirectMusicTool::GetMediaTypes が返す配列内に列挙されたタイプのあらゆるメッセージは、このメソッドを要求する。

CEchoTool::ProcessPMsg メソッドは、最初にローカル変数の何らかの初期化を行う。

HRESULT STDMETHODCALLTYPE CEchoTool::ProcessPMsg(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pMsg)
{
  DMUS_NOTE_PMSG* pNote;
  DWORD dwCount;
  DWORD dwEchoNum;
  MUSIC_TIME mtDelay;

// SetEchoNum()と SetDelay()はこれらのメンバ変数を使うので、
// クリティカルセクションを利用してこれらをスレッドセーフにする。
  EnterCriticalSection(&m_CrSec);
  dwEchoNum = m_dwEchoNum;
  mtDelay = m_mtDelay;
  LeaveCriticalSection(&m_CrSec);

次にこのメソッドは、メッセージに対して IDirectMusicGraph::StampPMsg メソッドを呼び出す。処理が終わった後でこのメッセージを他のツールに転送しなければならない場合、StampPMsg は成功する (DirectMusic が最終出力ツールを用意しているため、メッセージの転送先となるアプリケーション固有のツールが存在しない場合でも、StampPMsg は成功するはずである)。失敗した場合、メソッドは S_FREE を返し、メッセージは自動的に無視される。

  if ((NULL == pMsg->pGraph) ||
    FAILED(pMsg->pGraph->StampPMsg(pMsg)))
  {
    return DMUS_S_FREE;
  }

ここでは CEchoTool がメッセージを処理する。DMUS_PMSGT_NOTE、DMUS_PMSGT_MIDI、または DMUS_PMSGT_PATCH のタイプのメッセージのみを受け取るよう設定されている点に注意すること (これらのタイプは DMUS_PMSGT_TYPES 列挙型の一部である)。

連続するエコーを作成するたびに、ツールは以下のことを行う。

  • IDirectMusicPerformance::AllocPMsg メソッドを呼び出して、新しいメッセージを作成する。
  • オリジナルのメッセージの DMUS_PMSG 構造体を新しいメッセージにコピーして、COM の管理用に一部のメンバを更新する。
  • 新しいメッセージを他のパフォーマンス チャンネルに割り当てる。
  • 音符の場合は、各エコーのボリュームを徐々に下げる。
  • メッセージの演奏タイムに遅延時間を追加する。
  • IDirectMusicPerformance::SendPMsg メソッドを呼び出して、パイプラインに新しいメッセージを置く。このメッセージに対して IDirectMusicGraph::StampPMsg が呼び出されていないので、デフォルトの最終出力ツール以外のツールへ転送されることはない。

MIDI の音符を扱うサンプルコードを示す。

  if( pPMsg->dwType == DMUS_PMSGT_MIDI )
  {
    // MIDI メッセージをエコー チャンネルにコピーする。
    for( dwCount = 1; dwCount <= dwEchoNum; dwCount++ )
    {
      DMUS_MIDI_PMSG* pMidi;
      if( SUCCEEDED( pPerf->AllocPMsg( sizeof(DMUS_MIDI_PMSG),
        (DMUS_PMSG**)&pMidi )))
      {
        // オリジナル メッセージをこのメッセージにコピーする。
        memcpy( pMidi, pPMsg, sizeof(DMUS_MIDI_PMSG) );

        // オブジェクトへのポインタを保持または保持している
        // 可能性のあるフィールドの Addref か消去を実行する。
        if( pMidi->pTool ) pMidi->pTool->AddRef();
        if( pMidi->pGraph ) pMidi->pGraph->AddRef();
        pMidi->punkUser = NULL;

        // メッセージが次の上位グループへ移動するよう、
        // P チャンネルを設定する。
        pMidi->dwPChannel = pMidi->dwPChannel +
                (16*dwCount);

        // エコーされるメッセージの時間への追加を行う。
        pMidi->mtTime += (dwCount * mtDelay);

        // メッセージを追加するので、MUSIC_TIME だけが有効になる。
        // REFERENCE_TIME は、SendPMsg()の内部で
        // 再計算される。
        pMidi->dwFlags = DMUS_PMSGF_MUSICTIME;

        // メッセージを送信する。
        pPerf->SendPMsg( (DMUS_PMSG*)pMidi );
      }
    }
  }

パッチ チェンジもコピーされ、現在使われていないものも含め他のすべてのエコー チャンネルに送信される。そのため、後でエコーを追加した場合でも、正しい音色による演奏が行われる。サンプルの EchoTool アプリケーションでは、Echotool.h で MAX_ECHOES が定義されている点に注意すること。

  else if( pPMsg->dwType == DMUS_PMSGT_PATCH )
  {
    for( dwCount = 1; dwCount <= MAX_ECHOES; dwCount++ )
    {
      DMUS_PATCH_PMSG* pPatch;
      if( SUCCEEDED( pPerf->AllocPMsg( sizeof(DMUS_PATCH_PMSG),
        (DMUS_PMSG**)&pPatch )))
      {
        // オリジナルメッセージをこのメッセージにコピーする。
        memcpy( pPatch, pPMsg, sizeof(DMUS_PATCH_PMSG) );

        // オブジェクトへのポインタを保持または保持している
        // 可能性のあるフィールドの Addref か消去を実行する。
        if( pPatch->pTool ) pPatch->pTool->AddRef();
        if( pPatch->pGraph ) pPatch->pGraph->AddRef();
        pPatch->punkUser = NULL;

        // メッセージが次の上位グループへ移動するよう、
        // P チャンネルを設定する。
        pPatch->dwPChannel = pPatch->dwPChannel +
          (16*dwCount);

        // エコーされるメッセージの時間への追加を行う。
        pPatch->mtTime += (dwCount * mtDelay);

        // メッセージを追加するので、MUSIC_TIME だけが有効になる。
        // REFERENCE_TIME は、SendPMsg()の内部で
        // 再計算される。
        pPatch->dwFlags = DMUS_PMSGF_MUSICTIME;

        // メッセージを送信する。
        pPerf->SendPMsg( (DMUS_PMSG*)pPatch );
      }
    }
  }

このメソッドは、MIDI の音符と同様の方法で音符を扱うが、ボリュームを下げるためのステップを追加する。

  else if( pPMsg->dwType == DMUS_PMSGT_NOTE )
  {
    // 次の音符のベロシティを追跡するための変数を作成する。
    BYTE bVelocity;
    pNote = (DMUS_NOTE_PMSG*)pPMsg;
    bVelocity = pNote->bVelocity;

    for( dwCount = 1; dwCount <= dwEchoNum; dwCount++ )
    {
      if( SUCCEEDED( pPerf->AllocPMsg( sizeof(DMUS_NOTE_PMSG),
              (DMUS_PMSG**)&pNote )))
      {
        // オリジナルの音符をこのメッセージにコピーする。
        memcpy( pNote, pPMsg, sizeof(DMUS_NOTE_PMSG) );

        // オブジェクトへのポインタを保持または保持している
        // 可能性のあるフィールドの Addref か消去を実行する。
        if( pNote->pTool ) pNote->pTool->AddRef();
        if( pNote->pGraph ) pNote->pGraph->AddRef();
        pNote->punkUser = NULL;

        // エコーされるメッセージの時間への追加を行う。
        pNote->mtTime += (dwCount * mtDelay);

        // エコーされた音符のボリュームを下げる。
        bVelocity = (BYTE) (bVelocity -
                ((bVelocity * (dwCount * 15))/100));
        pNote->bVelocity = bVelocity;

        // メッセージを追加するので、MUSIC_TIME だけが有効になる。
        // REFERENCE_TIME は、SendPMsg()の内部で
        // 再計算される。
        pNote->dwFlags = DMUS_PMSGF_MUSICTIME;
        pNote->dwPChannel = pNote->dwPChannel +
          (16*dwCount);

        // メッセージを送信する。
        pPerf->SendPMsg( (DMUS_PMSG*)pNote );
      }
    }
  }

最後に、ProcessPMsg メソッドは DMUS_S_REQUEUE を返し、オリジナル メッセージはパイプラインへ戻される。

return DMUS_S_REQUEUE;
} // CEchoTool::ProcessPMsg()の終わり

次項 : ステップ 5 : クラス メソッドの定義


ステップ 5 : クラス メソッドの定義

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

サンプルの CEchoTool クラスには、継承された IUnknown と IDirectMusicTool メソッドのほかに、コンストラクタとデストラクタ、およびエコーのパラメータを設定するための 2 つのパブリックメソッドがある。これらのメソッドの定義は、このチュートリアルとはやや関連が薄いが、完全を期すためにここで説明する。

CEchoTool::CEchoTool()
{
  m_cRef = 1;               // Release()はこれを解放する。
  m_dwEchoNum = 3;          // 1 つの音符につき 3 つのエコーをデフォルトに。
  m_mtDelay = DMUSPPQ / 2;  // 8 度の音符のエコー。
  InitializeCriticalSection(&m_CrSec);
}

CEchoTool::~CEchoTool()
{
  DeleteCriticalSection(&m_CrSec);
}

void CEchoTool::SetEchoNum(DWORD dwEchoNum)
{
  // ProcessPMsg()は m_dwEchoNum を使うので,クリティカル
  // セクションを利用してこのメソッドをスレッドセーフにする。
  if( dwEchoNum <= MAX_ECHOES )
  {
    EnterCriticalSection(&m_CrSec);
    m_dwEchoNum = dwEchoNum;
    LeaveCriticalSection(&m_CrSec);
  }
}

void CEchoTool::SetDelay(MUSIC_TIME mtDelay)
{
  // ProcessPMsg()は m_mtDelay を使うので,クリティカル
  // セクションを利用してこのメソッドをスレッドセーフにする。
  EnterCriticalSection(&m_CrSec);
  m_mtDelay = mtDelay;
  LeaveCriticalSection(&m_CrSec);
}

次項 : ステップ 6 : パフォーマンスへのツールの追加


ステップ 6 : パフォーマンスへのツールの追加

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

CEchoTool クラスを定義した後、アプリケーションはツールオブジェクトを作成し、グラフに挿入し、パフォーマンスに追加するので、パイプライン内の適切なメッセージを横取りできるようになる。

次のコードは CEchoTool クラスのインスタンスを作成し、ツールが作成すべきエコーの数を初期化し、ツールを保持するグラフを作成し、そのグラフをパフォーマンスに追加する (サンプル アプリケーション EchoTool では、この作業の一部をヘルパー関数 AddTool で実行している。ここでは追跡を容易にするため、コードに変更を加えている)。

/* pPerf が、パフォーマンス オブジェクトの IDirectMusicPerformance
   インターフェイスへの有効なポインタであることを想定している。*/

CEchoTool         *pEchoTool;
IDirectMusicGraph* pGraph;

pEchoTool = new CEchoTool;
if (pEchoTool)
{
    pEchoTool->SetEchoNum(0);

    // ツールを保持するために IDirectMusicGraph オブジェクトを作成する。
    if (SUCCEEDED(CoCreateInstance(
            CLSID_DirectMusicGraph,
            NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicGraph,
            (void**)&pGraph)))
    {
        // ツールをグラフに追加する。
        if (SUCCEEDED(pGraph->InsertTool(
                (IDirectMusicTool*)pCEchoTool,
                NULL,   // すべての P チャンネルに適用する。
                0,      // ほかの P チャンネルは何個あるか。
                0)))    // グラフ内のツールのインデックス番号。
        {
        // グラフをパフォーマンスに追加する。この結果、参照
        // カウントが増えるので、オリジナルのグラフは解放
        // できるようになる。
        pPerf->SetGraph(pGraph);
        }
        pGraph->Release();
    }
}

パフォーマンス内のグラフの設定により、すべてのセグメント内のメッセージは、このツールによって処理される機会を得る。代わりに、IDirectMusicSegment::SetGraph メソッドを使って、特定のセグメントにのみツールを適用することもできる。


チュートリアル 3 : アレンジの方法

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、DirectMusic Producer でオーサリングされた要素に基づいてミュージック パフォーマンスを設定する方法と、音楽をインタラクティブに、すなわちプログラム イベントに応じて演奏する方法を示す。

サンプル コードは、DirectX SDK の DMDonuts サンプル に基づいている。DMDonuts は大規模で複雑なアプリケーションなので、ここでは主要な要点だけを取り扱う。DirectMusic の詳細な実装については、ソースファイル Donuts.cpp とその付属ヘッダーのうち、DMUSIC BEGIN と DMUSIC END のコメントで囲まれている箇所を参照すること。

このチュートリアルは、以下のステップで構成されている。

  • ステップ 1 : define とグローバル
  • ステップ 2 : パフォーマンスの初期化
  • ステップ 3 : ミュージック要素のロード
  • ステップ 4 : 通知の設定
  • ステップ 5 : プライマリ セグメントの作成
  • ステップ 6 : プライマリ セグメントの演奏
  • ステップ 7 : 別のプライマリ セグメントへの移行
  • ステップ 8 : モチーフの演奏
  • ステップ 9 : 通知の処理
  • ステップ 10 : DirectMusic のシャットダウン


ステップ 1 : define とグローバル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

次の define とグローバル変数は、Donuts.cpp の先頭で宣言されている。このチュートリアルを利用する際の参照用に、ここに示しておく。

BOOL          bMusicEnabled = TRUE;

// さまざまな定数
const  GUID guidZero =    {0};
#define MOTIF_BOUNCE       0
#define MOTIF_DEATH        1
#define MOTIF_SHIELD       2
#define MOTIF_BLOWUP       4
#define MOTIF_BLOWUPLITE   3
#define NUM_MOTIFS         5
#define NUM_STYLES         2
#define SEGMENT_1          0
#define SEGMENT_2          1
#define SEGMENT_TRANS_1    2
#define SEGMENT_TRANS_2    3
#define NUM_SEGMENTS       4
#define NUM_CHORDMAP       4
#define BLOWUPS_PER_BEAT   2
#define MEASURE_LENGTH     DMUS_PPQ * 4
// パート数/四分音符 * 四分音符の数/小節 (4/4 拍子を想定)

// グローバル インターフェイス
IDirectMusicStyle*        gapStyle[NUM_STYLES];
IDirectMusicChordMap*     gapChordMap[NUM_STYLES] [NUM_CHORDMAP];
IDirectMusicSegment*      gapMotif[NUM_STYLES] [NUM_MOTIFS];
IDirectMusicSegment*      gapSegment[NUM_SEGMENTS] =
                          {NULL, NULL, NULL, NULL};
IDirectMusicComposer *    gpComposer = NULL;
IDirectMusicPerformance*  gpPerformance = NULL;
IDirectMusic*             gpDirectMusic = NULL;
IDirectMusicLoader*       gpLoader = NULL;
IDirectMusicSegment*      gpIntroTemplate = NULL;
IDirectMusicSegment*      gpGameTemplate = NULL;
IDirectMusicSegment*      gapShieldSegment[NUM_STYLES] = {NULL, NULL};
IDirectMusicSegment*      gapDefaultSegment[NUM_STYLES] =
                                  {NULL, NULL};
IDirectMusicBand*         gapShieldBand[NUM_STYLES] = {NULL, NULL};
IDirectMusicBand*         gapDefaultBand[NUM_STYLES] = {NULL, NULL};

// グローバル変数
BOOL        bAnyHits = FALSE;
int         gnCurrentStyle = 0;
int         gnCurrentChordMap = 0;
int         gnLastStyle = 0;
int         gnLastChordMap = 0;

BOOL        gbShieldsOn = FALSE;
static int  snLastTempo;
static int  snSubLevel;
static int  snMaxBlowUps = BLOWUPS_PER_BEAT;

次項 : ステップ 2 : パフォーマンスの初期化


ステップ 2 : パフォーマンスの初期化

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

Donuts.cpp ファイル内の InitializeGame 関数で DirectMusic パフォーマンスを設定する。

アプリケーションは最初に GetSearchPath 関数を呼び出すことにより、レジストリへのクエリを行って、DirectX のサンプル ミュージック ファイルの検索パスを取得する。その後、次のようにコンポーザ用とパフォーマンス用の COM オブジェクトを作成する。

CoInitialize(NULL);

if ( !SUCCEEDED(::CoCreateInstance(
        CLSID_DirectMusicComposer,
        NULL,
        CLSCTX_INPROC,
        IID_IDirectMusicComposer,
        (void**)&gpComposer
)))
{
    return CleanupAndExit("Couldn't create a composer object");
}

if ( !SUCCEEDED( CoCreateInstance( CLSID_DirectMusicPerformance,
        NULL,
        CLSCTX_INPROC,
        IID_IDirectMusicPerformance,
        (void**)&gpPerformance )))
{
    return CleanupAndExit("Couldn't create a performance object");
}

続いて、このアプリケーションは IDirectMusicPerformance::Init を呼び出してパフォーマンスを初期化する。このメソッドは、ポートの作成とアクティブ化を行う DirectMusic オブジェクトを作成する。DirectSound がほかのサウンド エフェクトに使用されているかどうかに応じて、lpDS に渡してパフォーマンスに既存の DirectSound オブジェクトをアタッチするか、NULL を渡してオブジェクトを作成する。

#ifdef USE_DSOUND
    if( !SUCCEEDED(gpPerformance->Init(&gpDirectMusic,
           lpDS, hWndMain)))
    {
        return CleanupAndExit("Couldn't initialize the performance");
    }
#else
    if( !SUCCEEDED(gpPerformance->Init(&gpDirectMusic,
            NULL, hWndMain)))
    {
        return CleanupAndExit("Couldn't initialize the performance");
    }
#endif

アプリケーションはここでデフォルト ポートを取得し、1 つのチャンネル グループでポートのインスタンスを作成し、その能力を取得する。

IDirectMusicPort* pPort = NULL;
DMUS_PORTPARAMS dmos;
DMUS_PORTCAPS dmpc;
GUID guidSynthGUID;
HRESULT hr = S_OK;

if ( !SUCCEEDED(gpDirectMusic->GetDefaultPort(&guidSynthGUID)))
{
    return CleanupAndExit("Could't GetDefaultPort on IDirectMusic");
}

ZeroMemory(&dmos, sizeof(dmos));
dmos.dwSize = sizeof(DMUS_PORTPARAMS);
dmos.dwChannelGroups = 1;
dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;

if( !SUCCEEDED(gpDirectMusic->CreatePort(guidSynthGUID,
            &dmos,
            &pPort,
            NULL)))
{
    return CleanupAndExit("Couldn't CreatePort on IDirectMusic");
}

ZeroMemory(&dmpc, sizeof(dmpc));
dmpc.dwSize = sizeof(DMUS_PORTCAPS);

if( !SUCCEEDED(pPort->GetCaps(&dmpc)))
{
    if (pPort) pPort->Release();
    return CleanupAndExit("Couldn't GetCaps on IDirectMusicPort");
}

ここで、_SOFTWARE_SYNTH_ が定義されているかどうかに応じて、アプリケーションの動作が変わる。_SOFTWARE_SYNTH_ が定義されている場合、DLS 機能を持つシンセサイザが要求され、アプリケーションはデフォルト ポートで DMUS_PC_DLS 能力フラグを確認する。フラグが見つからない場合は、デフォルト ポートを解放し、DMUS_PC_DLS 機能を持つ出力ポートが見つかるまで、利用可能なポートを列挙し続ける。最終的に、見つかったポートのインスタンスが作成される。

if ((dmpc.dwClass != DMUS_PC_OUTPUTCLASS)
        || !(dmpc.dwFlags & DMUS_PC_DLS))
{
    pPort->Release();
    pPort = NULL;
}

if (!pPort)
{
    for (DWORD index = 0; hr == S_OK; index++)
    {
        ZeroMemory(&dmpc, sizeof(dmpc));
        dmpc.dwSize = sizeof(DMUS_PORTCAPS);

        hr = gpDirectMusic->EnumPort(index, &dmpc);
        if(hr == S_OK)
        {
            if ( (dmpc.dwClass == DMUS_PC_OUTPUTCLASS) &&
                 (dmpc.dwFlags & DMUS_PC_DLS) )
            {
                CopyMemory(&guidSynthGUID, &dmpc.guidPort,
                        sizeof(GUID));

                ZeroMemory(&dmos, sizeof(dmos));
                dmos.dwSize = sizeof(DMUS_PORTPARAMS);
                dmos.dwChannelGroups = 1;
                dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;

                hr = gpDirectMusic->CreatePort(guidSynthGUID,
                        &dmos, &pPort, NULL);
                break;
            }
        }
    }
    if (hr != S_OK)
    {
        if (pPort) pPort->Release();
        return CleanupAndExit("Couldn't initialize the Synth port");
    }
}

一方、_SOFTWARE_SYNTH_ が定義されていない場合は、従来のハードウェア ポートが要求され、アプリケーションは MIDI マッパーが見つかるまで、ポートを列挙し続ける(ここでは、コードを示していない)。

次に、このポートをアクティブ化して、パフォーマンスに付加する。

pPort->Activate(TRUE);
gpPerformance->AddPort(pPort);

次の呼び出しで、P チャンネル 0-15 がこのポート上の最初の MIDI チャンネル グループへマップされる。このステップは、アプリケーションが AddPort に NULL を渡していないために必要である点に注意すること。

gpPerformance->AssignPChannelBlock(0, pPort, 1);

この時点で、ポートへのオリジナル参照を解放できる。この呼び出しは、パフォーマンスからポートを削除することはない。

if (pPort) pPort->Release();

次項 : ステップ 3 : ミュージック要素のロード


ステップ 3 : ミュージック要素のロード

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること

[C++]

サンプル アプリケーション DMDonuts で DirectMusic の機能を設定する次のステップは、音楽の要素であるスタイル、テンプレート、モチーフ、コード マップ、バンドをファイルからロードすることである。前のステップと同様、このコードも InitializeGame 関数から抜粋したものである。

最初に、このアプリケーションはローダー オブジェクトを作成する。

if (!SUCCEEDED(::CoCreateInstance(
            CLSID_DirectMusicLoader,
            NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicLoader,
            (void**)&gpLoader
        )))
{
    return CleanupAndExit("ローダー オブジェクトを作成できませんでした。");
}

次にすべてのオブジェクトの検索ディレクトリを設定し、オブジェクトキャッシュを有効にする。2 番目の呼び出しは、単純にデフォルトのキャッシュ ステータスを確認する。

hr = E_FAIL;

/ * GetSearchPath 関数は、レジストリからメディア ディレクトリを
    取得し、これを wszSearchPath に返す。*/

if (GetSearchPath(wszSearchPath))
{
    hr = gpLoader->SetSearchDirectory(
           GUID_DirectMusicAllTypes, wszSearchPath, FALSE);
}

/* ディレクトリが存在しない場合は、現在のディレクトリで試してみる。*/

if (FAILED(hr))
{
    hr = gpLoader->SetSearchDirectory(GUID_DirectMusicAllTypes,
            L".", FALSE);
}
if (FAILED(hr))
{
    return CleanupAndExit("DirectMusic ローダーの検索ディレクトリを \
            設定できませんでした。");
}
gpLoader->EnableCache(GUID_DirectMusicAllTypes, TRUE);

次のコードの一部は、Donuts.sty ファイル内の「Donuts」というスタイルをロードする。IDirectMusicLoader::ScanDirectory を呼び出してデータベースオブジェクトを構築すると、内部名を指定してオブジェクトをロードできるが、このアプリケーションはこのメソッドを呼び出していないため、最初に IDirectMusicLoader::GetObject を呼び出すと失敗に終わる。fallback 手続きは、ファイル名を使ってオブジェクトを識別し、もう一度 GetObject を呼び出す。

IDirectMusicObject* pObject = NULL;
DMUS_OBJECTDESC ObjectDescript;

ObjectDescript.dwSize = sizeof(DMUS_OBJECTDESC);
ObjectDescript.guidClass = CLSID_DirectMusicStyle;
wcscpy(ObjectDescript.wszName, L"Donuts");
ObjectDescript.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_NAME;

if (!SUCCEEDED(gpLoader->GetObject(&ObjectDescript,
        IID_IDirectMusicStyle, (void**)&gapStyle[1])))
{
    wcscpy(ObjectDescript.wszFileName, L"Donuts.sty");
    ObjectDescript.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME;
    if (!SUCCEEDED(gpLoader->GetObject(&ObjectDescript,
            IID_IDirectMusicStyle, (void**)&gapStyle[1])))
    {
        return CleanupAndExit("Couldn't load style object 1");
    }
}

次に InitializeGame 関数は同様の方法で、もう 1 つのスタイルと 2 つのテンプレートをロードする。

その次のステップは、ゲーム内の特定のイベントをマーク (明示) するために使われるモチーフの配列を初期化することである。各モチーフはスタイル内に含まれており、IDirectMusicStyle::GetMotif メソッドを呼び出すことによって取得される。このメソッドは、このモチーフ用のセグメントを作成する。Donuts.cpp ファイル内の次の例のように、メソッドにはモチーフの内部名を渡さなければならない。

WCHAR awszMotifs[NUM_MOTIFS][64];

wcscpy(awszMotifs[MOTIF_BOUNCE], L"Bounce");
.
.
.
hr = gapStyle[0]->GetMotif(awszMotifs[MOTIF_BOUNCE],
        &(gapMotif[0][MOTIF_BOUNCE]));

省略のない完全なコードを参照すると、このアプリケーションが同じ名前を持つモチーフを 2 セット ロードしていることがわかる。1 つは「Donuts」スタイルから、もう 1 セットは「Donutz」からである。プレーヤーのレベルが変化するのに応じて、DMDonuts はこれら 2 つのスタイルを切り替える。gapMotif を演奏するときに、グローバルな gnCurrentStyle の値に基づいて最初のインデックスが決定され、モチーフが現在のレベルに適したものであることを保証する。

続いて、アプリケーションはスタイルごとに 4 つのコード マップを初期化する。これらは、別々のファイルから取得される。

WCHAR awszChordMap[NUM_STYLES][NUM_CHORDMAP][64];
wcscpy(awszChordMap[0][0], L"minaeo.per");
wcscpy(awszChordMap[0][1], L"minfunc.per");
wcscpy(awszChordMap[0][2], L"mipedpt.per");
wcscpy(awszChordMap[0][3], L"tension.per");
wcscpy(awszChordMap[1][0], L"dianoble.per");
wcscpy(awszChordMap[1][1], L"minpedpt.per");
wcscpy(awszChordMap[1][2], L"mippjazz.per");
wcscpy(awszChordMap[1][3], L"minjazz.per");

ObjectDescript.guidClass = CLSID_DirectMusicChordMap;
ObjectDescript.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME;

for (short n = 0; n < NUM_STYLES; n++)
{
    for (short m = 0; m < NUM_CHORDMAP; m++)
    {
        if (hr == S_OK)
        {
            wcscpy(ObjectDescript.wszFileName,
                    awszChordMap[n][m]);
            hr = gpLoader->GetObject(&ObjectDescript,
                    IID_IDirectMusicChordMap,
                   (void**)&gapChordMap[n][m]);
        }
    }
}

if (hr != S_OK)
{
    return CleanupAndExit("コード マップをロードできませんでした。");
}

このスタイルから取り出すべき最後の要素はバンドである。各スタイルは 2 つの異なったバンドを備えている。1 つはプレーヤーの宇宙船にシールドがないとき、もう 1 つはシールドが張られているときである。バンドに割り当てられている名前が、モチーフやコード マップに割り当てられている名前とは異なる点に注意すること。どちらのバンドにも、WCHAR のローカル配列ではなく BSTR が割り当てられている。ただし、Win32® API では BSTR は WCHAR 配列へのポインタなので、これらは同じエフェクトをもたらす。

各バンドをロードするときに、これらはパフォーマンスにダウンロードされ、DLS データが音色で利用可能となる。

BSTR bstrDefault = SysAllocString(L"Default 2");
BSTR bstrShields = SysAllocString(L"Shields");

for (n = 0; n < NUM_STYLES; n++)
{
    if (hr == S_OK)
    {
        hr = gapStyle[n]->GetBand(bstrShields, &gapShieldBand[n]);
    }
    if (hr == S_OK)
    {
        hr = gapShieldBand[n]->Download(gpPerformance);
    }
    if (hr == S_OK)
    {
        hr = gapStyle[n]->GetBand(bstrDefault, &gapDefaultBand[n]);
    }
    if (hr == S_OK)
    {
        hr = gapDefaultBand[n]->Download(gpPerformance);
    }
}

SysFreeString(bstrDefault);
SysFreeString(bstrShields);

いくつかのエラーチェック コードの後で、InitializeGame 関数は自ら取得した 4 つのバンドからセグメントを作成する。これらのバンドを使って、適切なときにバンド チェンジを「演奏」する。セグメントを作成した後、バンド インターフェイスを解放する。

for (n = 0; n < NUM_STYLES; n++)
{
    if (hr == S_OK)
    {
        hr = gapShieldBand[n]->CreateSegment(&gapShieldSegment[n]);
    }
    if (hr == S_OK)
    {
        hr = gapDefaultBand[n]->CreateSegment(&gapDefaultSegment[n]);
    }
    apShieldBand[n]->Release();
    apDefaultBand[n]->Release();
}

次項 : ステップ 4 : 通知の設定


ステップ 4 : 通知の設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

InitializeGame 関数内の DirectMusic コードの最後の部分は、プライマリ セグメントの再生がバンド境界またはセグメントの最後に達したときに通知を行うよう要求する。このチュートリアルで後ほど観察するように、この通知メカニズムは同時に演奏できる「爆発」モチーフの数を制限するために使われている。

次のコードでは、通知のタイプが追加されている。通知 GUID は参照の形で渡さなければならないので、通知 GUID を変数に置く必要がある点に注意すること。

GUID guid;
guid = GUID_NOTIFICATION_SEGMENT;
gpPerformance->AddNotificationType( guid );
guid = GUID_NOTIFICATION_MEASUREANDBEAT;
gpPerformance->AddNotificationType( guid );

次項 : ステップ 5 : プライマリ セグメントの作成


ステップ 5 : プライマリ セグメントの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

サンプル アプリケーション DMDonuts 内の DirectMusic の 1 回限りの初期化はここまでで完了した。setup_game 関数内で行われるこれ以降の初期化は、ゲームのスタート時、またはプレーヤーが次のレベルへ進むたびに実施される。

setup_game 関数は、最初に ComposeNewSegments 関数を呼び出す。この関数は現在のゲーム レベルに基づいてスタイルとコード マップを選択し、それまでに作成したセグメントを解放する。続いて、これまでにファイルからロードしたテンプレートに基づいて 2 つの新しいセグメントを作成する。これらのセグメントのうち、1 つはアステロイド (小惑星) が衝突するまで演奏される導入のテーマであり、もう 1 つはその時点からプレーヤーのレベルが上がるまで演奏される。変数 snSubLevel は、現在のレベルでどのパートを使っているか追跡し、ほかの場所では、F7 キーを押して音楽を切り替えるよう指示されたときにどのセグメントを演奏すべきか決定するために使われる。

snSubLevel = 1;
snLastTempo = 0;
gnLastStyle = gnCurrentStyle;
gnLastChordMap = gnCurrentChordMap;
gnCurrentStyle = level % NUM_STYLES;
gnCurrentChordMap = ((level - 1) / 2) % NUM_CHORDMAP;
HRESULT hr = S_OK;
MUSIC_TIME mtSegmentLength;
if (gapSegment[SEGMENT_1])
{
    gapSegment[SEGMENT_1]->Release();
}
hr = gpComposer->ComposeSegmentFromTemplate(
        gapStyle[gnCurrentStyle],
        gpIntroTemplate, 0,
        gapChordMap[gnCurrentStyle][gnCurrentChordMap],
        &gapSegment[SEGMENT_1]
);
if (!SUCCEEDED(hr))
{
    CleanupAndExit("Segment 1 composition failed");
}

ここで、このテンプレートの最後の小節にサイン ポストがあり、それが最初の小節のサイン ポストと一致していることに気づく。これは自然なループを実現するためである。セグメントを作成した後で、最後の小節はループから外される。MEASURE_LENGTH の値が、「ステップ 1 : define とグローバル」で (DMUS_PPQ * 4)、つまりミュージック タイムの 4 分音符として計算される点に注意すること。拍子記号が 4/4 であるので、これは有効である。

gapSegment[SEGMENT_1]->GetLength(&mtSegmentLength);
gapSegment[SEGMENT_1]->SetLength(
        mtSegmentLength - MEASURE_LENGTH);

最後に、このセグメントがループを繰り返すように設定される。

gapSegment[SEGMENT_1]->SetRepeats(999);

gpGameTemplate に基づく 2 番目のセグメントの作成と設定も同じ方法で行われる。

次項 : ステップ 6 : プライマリ セグメントの演奏


ステップ 6 : プライマリ セグメントの演奏

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

前のステップで、Donuts.cpp ファイル内の setup_game 関数は、ComposeNewSegments 関数を呼び出し、現在のゲーム レベルで演奏される 2 つのプライマリ セグメントを作成した。ここでは setup_game 関数はこれらのセグメントのうち最初のものを演奏する。

gpPerformance->PlaySegment(
    gapSegment[SEGMENT_1], 0, 0, NULL);

このフラグが、このセグメントを即座に演奏するよう指示している点に注意すること。

この関数は、現在のスタイル用に作成されたデフォルトのバンド セグメントを演奏する。(ゲーム レベルが変化した時点で、2 つの異なったスタイルが存在する点に注意すること。各スタイルには 2 つのバンドがあり、デフォルトのバンドは「シールドあり」のバンドである。) バンド セグメントを演奏することにより、正しい音色セットがこの音楽を演奏することが保証される。バンドセグメントをセカンダリとして指定するフラグを割り当てなければならない点に注意すること。変更が即座に行われるので、3 番目のパラメータで開始タイムが指定されておらず、セグメント状態へのポインタが必要ないので、最後のパラメータは NULL になっている。

gpPerformance->PlaySegment(
    gapDefaultSegment[gnCurrentStyle],
    DMUS_SEGF_SECONDARY,
    0, NULL);

プレーヤーの宇宙船がシールドなしの状態になると、このスタイルのデフォルトのバンドが使われる。レベルの開始時に必ずこの状態が発生する。シールドが有効になると、アプリケーションはそれに応じて UpdateDisplayList 関数内の 2 番目のバンドを演奏し、シールドが無効になると再びデフォルトのバンドを演奏する。

次項 : ステップ 7 : 別のプライマリ セグメントへの移行


ステップ 7 : 別のプライマリ セグメントへの移行

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

Dmdonuts は、2 つの状況で異なったプライマリ セグメントを挿入する。ゲーム レベルが変化したときと、任意のレベルでアステロイドに最初に衝突したときである。次のコードは、CheckForHits 関数から抜粋したものである。この関数は、現在のレベルで衝突が最初に発生したことを検出すると、DirectMusic コンポーザに、現在の (導入) テーマからアクション テーマへの移行部を作成するよう指示する。IDirectMusicComposer::AutoTransition を呼び出した場合も、移行部と次のアクションセグメントが挿入され、それらが自動的に演奏される。この場合、移行部は次の小節境界から開始される。

if (gapSegment[SEGMENT_TRANS_1])
{
    gapSegment[SEGMENT_TRANS_1]->Release();
}
gpComposer->AutoTransition(
        gpPerformance,                 // パフォーマンス。
        gapSegment[SEGMENT_2],         // 次のプライマリ セグメント
        DMUS_COMMANDT_FILL,            // 装飾タイプ。
        DMUS_COMPOSEF_MODULATE |       // 新しいキーへ転調し、
        DMUS_COMPOSEF_MEASURE,         // 小節を開始する。
        gapChordMap[gnCurrentStyle] [gnCurrentChordMap],
                                       // 現在のコード マップを使う。
        &gapSegment[SEGMENT_TRANS_1],  // 作成された移行部セグメント。
        NULL, NULL                     // セグメント状態は必要ない
);

最初のセグメントを停止する必要がない点に注意すること。移行部または新しいプライマリ セグメントが演奏されると、最初のセグメントは自動的に停止する。

次項 : ステップ 8 : モチーフの演奏


ステップ 8 : モチーフの演奏

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

Dmdonuts はいくつかのモチーフを使って、ゲームのアクションにアクセントを付ける。たとえば、プレーヤーの宇宙船が画面の端に接したときや、プレーヤーの砲火がアステロイドに当たったときが挙げられる。

モチーフを演奏するのは、CheckForHits 関数から抜粋した次のコードが示すとおり単純な作業である。ドーナツに命中するたびに MOTIF_BLOWUP が演奏される。

gpPerformance->PlaySegment(
        gapMotif[gnCurrentStyle][MOTIF_BLOWUP],
        DMUS_SEGF_SECONDARY | DMUS_SEGF_GRID, 0, NULL);

このモチーフはセカンダリセグメントとして演奏しなければならないので、プライマリ セグメントが演奏されている最中でもメインテーマを妨げることはない。グリッド境界で演奏するように挿入され、プライマリ セグメントのステップを乱さずに演奏できるように最小限の分解能が設定される。rtStartTime パラメータは 0 であり、最初の境界に達したときにセグメントを演奏することを意味しており、演奏中のセグメントにアクセスする必要はないので ppSegmentState パラメータは NULL になっている。

次項 : ステップ 9 : 通知の処理


ステップ 9 : 通知の処理

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

「ステップ 4 : 通知の設定」では、セグメントが最後に達したとき、または拍か小節の境界に達したときに、DMDonuts が通知を要求する方法を観察した。この通知の目的は、一度に演奏される「爆発」モチーフの数を制限するのを支援することにある。

通知は WinMain 関数によって取り出される。キュー内のほかのメッセージを処理した後で、アプリケーションは保留中の通知が存在するかどうかをチェックする。この処理は、IDirectMusicPerformance::GetNotificationPMsg メソッドの呼び出しによって行う。保留中の通知メッセージがない場合、このメソッドは S_FALSE を返し、それ以上の処理は必要ない。S_OK が返された場合は、通知メッセージが *pEvent に格納されていることを表している。拍に関連する通知を要求しただけであるので、実際にアプリケーションでメッセージを確認する必要はない。メッセージは直ちに破棄される。さらに、次の拍までに演奏できる爆発モチーフの数を追跡する snMaxBlowUps をリセットする。

if (gpPerformance)
{
    DMUS_NOTIFICATION_PMSG* pEvent;
    while ( S_OK == gpPerformance->GetNotificationPMsg(&pEvent))
    {
        gpPerformance->FreePMsg((DMUS_PMSG*)pEvent);
        snMaxBlowUps = BLOWUPS_PER_BEAT;
    }
}

次項 : ステップ 10 : DirectMusic のシャットダウン


ステップ 10 : DirectMusic のシャットダウン

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic チュートリアル」を参照すること。

[C++]

DirectMusic を閉じるには、COM の参照を解除し (CoInitialize の呼び出し 1 つにつき、CoUninitialize の呼び出し 1 つを対応させなければならない点に注意すること)、ローダー キャッシュを消去し、パフォーマンスを停止し、作成したすべてのオブジェクトを解放する。

Donuts.cpp ファイルでは、次の関数が必要なクリーンアップ作業を実行する。

void CleanUpDMusic()
{
    if (gpLoader)
    {
        gpLoader->ClearCache(GUID_DirectMusicAllTypes);
        gpLoader->Release();
    }

    if (gpComposer)
    {
        gpComposer->Release();
    }

    if (gpIntroTemplate)
    {
        gpIntroTemplate->Release();
    }

    if (gpGameTemplate)
    {
        gpGameTemplate->Release();
    }

    for (short n = 0; n < NUM_STYLES; n++)
    {
        if (gapShieldBand[n])
        {
            gapShieldBand[n]->Unload(gpPerformance);
            gapShieldBand[n]->Release();
        }
        if (gapDefaultBand[n])
        {
            gapDefaultBand[n]->Unload(gpPerformance);
            gapDefaultBand[n]->Release();
        }
        if (gapShieldSegment[n])
        {
            gapShieldSegment[n]->Release();
        }

        if (gapDefaultSegment[n])
        {
            gapDefaultSegment[n]->Release();
        }

        if (gapStyle[n])
        {
            gapStyle[n]->Release();
        }

        for (short m = 0; m < NUM_CHORDMAP; m++)
        {
            if (gapChordMap[n][m])
            {
                gapChordMap[n][m]->Release();
            }
        }

        for (m = 0; m < NUM_MOTIFS; m++)
        {
            if (gapMotif[n][m])
            {
                gapMotif[n][m]->Release();
            }
        }
    }

    if (gpPerformance)
    {
        gpPerformance->Stop( NULL, NULL, 0, 0 );
        gpPerformance->CloseDown();
        gpPerformance->Release();
    }

    for (n = 0; n < NUM_SEGMENTS; n++)
    {
        if (gapSegment[n])
        {
            gapSegment[n]->Release();
        }
    }

    if (gpDirectMusic)
    {
        gpDirectMusic->Release();
    }

    CoUninitialize();
}


DirectMusic Visual Basic チュートリアル

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここでは、次のチュートリアルを使用して、Visual Basic アプリケーションに DirectMusic を実装する方法を説明する。

  • チュートリアル 1 : MIDI ファイルの演奏
  • チュートリアル 2 : DLS サウンド エフェクトの使い方


チュートリアル 1 : MIDI ファイルの演奏

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。C++ については、「チュートリアル 1 : MIDI ファイルの演奏」を参照すること。

[Visual Basic]

このチュートリアルは、プライマリ セグメントを演奏するだけの、最も簡単な DirectMusic アプリケーションを設定するためのガイドである。この例では、セグメントは 1 つの MIDI ファイルを表しているが、ソースが DirectMusic Producer などのツールでオーサリングされた 1 つのセグメントである場合も、データのロードと演奏のプロセスはまったく同じである。

このチュートリアルは、次のステップで構成されている。

  • ステップ 1 : パフォーマンスとローダーの作成
  • ステップ 2 : MIDI ファイルのロード
  • ステップ 3 : MIDI ファイルの演奏


ステップ 1 : パフォーマンスとローダーの作成

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectMusic アプリケーションの中心となるオブジェクトは、DirectMusicPerformance クラスのインスタンスである。異なるテンポなどを使って別のポートで演奏する複数のパフォーマンスを使用することもできるが、ほとんどのアプリケーションは、パフォーマンス オブジェクトを 1 つだけ必要とする。ミュージック データをロードするには、アプリケーションに DirectMusicLoader オブジェクトも必要である。

これらのオブジェクトを作成するには、まずグローバル DirectX7 オブジェクトを宣言しなければならない。

次のグローバル宣言では、DirectX7 オブジェクトと、ほかの必要なオブジェクト用の変数が作成される。

Public gObjDX As New DirectX7
Public gObjDMLoader As DirectMusicLoader
Public gObjDMPerformance As DirectMusicPerformance

起動時のコードで、パフォーマンスおよびローダー オブジェクトを次のように作成する。

Set gObjDMLoader = gObjDX.DirectMusicLoaderCreate
Set gObjDMPerformance = gObjDX.DirectMusicPerformanceCreate

また、パフォーマンスを初期化して、これにポートを割り当てなければならない。次のコードでは、パフォーマンスに独自の DirectSound オブジェクトを作成させ、デフォルト ポートを割り当てている。デフォルト ポートは、常に、Microsoft Software Synthesizer または DLS 対応のハードウェア シンセサイザのどちらかである。MIDI ファイルでは最大で 16 のチャンネルが必要となるため、1 つのチャンネル グループがポートに割り当てられる。その他の種類のセグメントも演奏するアプリケーションでは、この数を増やさなければならない場合がある。

' hWnd は、メイン フォームのウィンドウ ハンドルである。
Call gObjDMPerformance.Init(Nothing, hWnd)
Call gObjDMPerformance.SetPort(-1, 1)

次項 : ステップ 2 : MIDI ファイルのロード


ステップ 2 : MIDI ファイルのロード

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ チュートリアル」を参照すること。

[Visual Basic]

MIDI ファイルをロードするには、次の 3 つが必要である。

  • 前のステップで作成した DirectMusicLoader オブジェクト
  • DirectMusicSegment 変数
  • MIDI ファイルの名前

ミュージック ファイルがアプリケーションの作業ディレクトリ以外の場所にある場合は、DirectMusicLoader.SetSearchDirectory を呼び出してローダーに検索する場所を指示するか、各ファイルをフル パスで記述する。

次のコードでは、ローダーの検索ディレクトリを設定して、そのディレクトリからファイルをロードしている。

Call gObjDMLoader.SetSearchDirectory("c:\midiplay\media")
' この処理は一度だけ必要である。

Dim objSeg As DirectMusicSegment

' FileName は、ファイルの短い名前を含む文字列である。
Set objSeg = gObjDMLoader.LoadSegment(FileName)

次項 : ステップ 3 : MIDI ファイルの演奏


ステップ 3 : MIDI ファイルの演奏

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここまでのステップで、MIDI ファイルを表す DirectMusicSegment オブジェクトが作成されている。これを演奏するには、もう少し準備が必要である。

まず、セグメントに、スタンダード MIDI ファイルであることを通知する。このステップがなくてもセグメントを演奏することはできるが、再生に関する特定の項目が正しく処理されない可能性がある。次のコードでは、従来の MIDI ファイル拡張子を持つファイルに対して、この処理を実行している。

If StrConv(Right(FileName, 4), vbLowerCase) = ".mid" Then
    Call objSeg.SetStandardMidiFile
End If

次に、音色の DLS データが、ポートに確実にダウンロードされるようにする。最も簡単な方法は、パフォーマンス全体で自動ダウンロードを有効にすることである。この処理は、セットアップ コードで次のように指定できる。

Call gObjDMPerformance.SetMasterAutoDownload(True)

この方法の欠点は、セグメントの停止と同時にポートから音色がアンロードされるため、もう一度音色をダウンロードしなければならない点である。アプリケーションが異なるセグメントを続けて演奏する場合、この処理により、容認できないほどの遅延が発生する可能性がある。処理をより完全に制御するために、セグメントが演奏される直前に、毎回音色をダウンロードするように指定することができる。音色をアンロードするように選択するまで、またはパフォーマンスが終了するまで、音色はポートに残ったままとなる。重複するダウンロードは無視される。

Call objSeg.Download(gObjDMPerformance)

ここまでの作業で、セグメントは演奏可能となった。

Call gObjDMPerformance.PlaySegment(objSeg, 0, 0)

再生の状態を (たとえば、一時停止や再開を行えるように) 追跡する場合は、DirectMusicSegmentState オブジェクトの DirectMusicPerformance.PlaySegment の戻り値を保存しておく。

Dim objSegState as DirectMusicSegmentState
Set objSegState = gObjDMPerformance.PlaySegment(gObjPrimarySeg, 0, 0)


チュートリアル 2 : DLS サウンド エフェクトの使い方

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

このチュートリアルでは、DLS を使って、DirectMusic で音楽以外のサウンド エフェクトを作成する方法を説明する。コード例は、DLSEffects サンプルを基にしたもので、DLS コレクション ファイルの Boids.dls を使用する。また、DirectMusic Producer を使ってこのコレクションを検証し、チュートリアルで説明されている概念のいくつかをより深く理解することもできる。DLS コレクションの表示および編集方法の詳細については、DirectMusic Producer のドキュメントを参照すること。

このチュートリアルは、次のステップで構成されている。

  • ステップ 1 : サウンドのロード
  • ステップ 2 : エフェクトの演奏
  • ステップ 3 : エフェクトの修正と停止


ステップ 1 : サウンドのロード

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

パフォーマンスを作成および初期化した後、DLSEffects サンプルは DLS ファイルとセグメント ファイルをロードする。これらのファイルはどちらも、mediapath で指定されたディレクトリからロードされる。

' dx は DirectX7 オブジェクトを表す。
' perf は初期化された DirectMusicPerformance オブジェクトを表す。
' seg は DirectMusicSegment として宣言される。

mediapath = FindMediaDir("sample.sgt", "dmusic")
If mediapath <> vbNullString Then ChDir mediapath

Dim loader As DirectMusicLoader
Set loader = dx.DirectMusicLoaderCreate
Set coll = loader.LoadCollection(mediapath & "boids.dls")
Set seg = loader.LoadSegment(mediapath & "sample.sgt")

ロードされるセグメントの種類が何であるかは問題ではない。アプリケーションはセグメントを演奏しないが、DLS データをダウンロードするには DirectMusicSegment オブジェクトが必要である。

ここで、アプリケーションは DirectMusicCollection オブジェクトをセグメントに関連付け、ポートにダウンロードする。セグメントによって参照されるほかの音色も、同様にダウンロードされる。

Call seg.ConnectToCollection(coll)
Call seg.Download(perf)

Boids.dls コレクションには、Vocals という音色が 1 つだけ含まれている。この音色のパッチ番号は 127 に設定されている。MIDI パッチ メッセージを送信して、この音色を任意のチャンネルに割り当てることができる。ほかのサンプルに影響を与えることなく、演奏するサンプルの 1 つ (鼓動音のサウンド) にピッチ ベンドを設定できるように、アプリケーションは音色を 2 つのチャンネルに割り当てている。

Const channel = 1
Const hbchannel = 2
Const patch = 127
Call perf.SendPatchPMSG(0, DMUS_PMSGF_REFTIME, channel, patch, 0, 0)
Call perf.SendPatchPMSG(0, DMUS_PMSGF_REFTIME, hbchannel, patch, 0, 0)

チャンネル 1 または 2 で演奏される音符はいずれも、Vocals 音色を使用する。この音色を使って、異なるサウンド効果を得る方法については、「ステップ 2 : エフェクトの演奏」を参照すること。


ステップ 2 : エフェクトの演奏

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

DLSEffects サンプルでは、笑い声、何か国語かのスピーチの断片、鼓動音など、ユーザーはさまざまなサウンド エフェクトを聞くことができる。これらのサウンドはすべて、1 つの DLS 音色に含まれている。

異なる音符の範囲、つまりリージョンに対して、異なるウェーブ サンプルを関連付けることができるので、1 つの音色でまったく異なるサウンドを演奏することができる。たとえば Boids.dls では、1 番目のスピーチは C0 ～ B3 のピッチ範囲に割り当てられている。この範囲の音符は、いずれも同じウェーブ サンプルに基づく。ルート音符は C3 である。これは、C3 の音符が演奏されたときに、ウェーブは本来の周波数で聞こえることを意味する。その他の音符では、ウェーブのピッチが修正される。

次のプロシージャは、グローバル変数 gVelocity で指定されるボリュームで音符を送信する。

Private Sub SendNote(chan As Integer, pitch As Byte, dur As Long)

  Dim noteMsg As DMUS_NOTE_PMSG
  noteMsg.velocity = gVelocity
  noteMsg.flags = DMUS_NOTEF_NOTEON
  noteMsg.midiValue = pitch
  noteMsg.mtDuration = dur
  Call perf.SendNotePMSG(0, DMUS_PMSGF_REFTIME, chan, noteMsg)

 End Sub

Boids.dls のウェーブは、1 つを除くすべてが単発のサンプルである。つまり、音符が演奏されるときに、ウェーブ サンプルは音符の長さにかかわらず一度しか演奏されない。例外は鼓動音のサンプルで、音符が演奏されている間、サンプルはループして演奏される。このループの動作は、音色コレクションのオーサーによって指定されている。

次のプロシージャは C3 の音符を送信する。C3 は、1 番目のスピーチ サンプルのルート音符である。したがって、このサンプルは正確なピッチで演奏される。定数 NoteDur は 6000 ミリ秒で、DirectMusic がノートオフの MIDI メッセージを生成する前に、このサンプルまたはその他のウェーブを完全に再生できるだけの十分な時間を設定している(この時間が経過する前に、ボタンをクリックして同一の音符を送信した場合、ノートオフ メッセージによって新しい音符もキャンセルされ、演奏が完全に行われない場合がある)。

Private Sub cmdC3_Click()
  SendNote channel, 36, NoteDur
End Sub

DLSEffects アプリケーションでは、ほとんどのサンプルはそれぞれのルート音符で演奏される。ただし、鼓動音のサンプルの扱いは少し異なり、サウンド エフェクトのピッチをプログラム的に変更することができる。この項目については、「ステップ 3 : エフェクトの修正と停止」を参照すること。


ステップ 3 : エフェクトの修正と停止

[C++]

ここでは、DirectX for Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

Boids.dls の Vocals 音色の定義では、鼓動音サンプルのリージョンは B7 ～ B8 である。サンプル アプリケーションで演奏されているように、ユーザーは [Note] スライダを使って、このリージョン内で音符を選択することができる。スライダを移動するごとに、既に演奏中の音符は停止され、新しい音符が送信される。

音符の継続時間は無期限であるため、音符は DirectMusicPerformance.SendMIDIPMSG を使って、スタンダード MIDI ノートオン メッセージの形式で送信される (または、DirectMusicPerformance.SendNotePMSG を使って、継続時間に非常に大きな値を指定する)。現在の周波数とベロシティは、最後の 2 つのパラメータで与えられる。このメソッドはチャンネルを別のパラメータとして受け付けるため、スタンダード MIDI メッセージと異なり、MIDI ステータス バイト (&H90) の下位 4 ビットにはチャンネル番号が含まれれない。

Call perf.SendMIDIPMSG(0, DMUS_PMSGF_REFTIME, hbchannel, _
        &H90, B7Freq, gVelocity)

鼓動音の音符の変更に加えて、ユーザーは音符を演奏するチャンネルにピッチ ベンドを割り当てることもできる。ピッチ ベンドも、スタンダード MIDI メッセージとして送信される。

Call perf.SendMIDIPMSG(0, DMUS_PMSGF_REFTIME, hbchannel, _
        &HE0, lo, hi)

lo および hi パラメータは 7 ビット値で、ピッチ ベンドには 16,384 とおりの設定が可能である。詳細については、MIDI の仕様を参照すること。

鼓動音の音符を停止するために、サンプル アプリケーションは SendNotePMSG メソッドを使って、現在演奏されている音符と同じピッチの音符を送信する。DMUS_NOTE_PMSG 型の flags メンバには、通常の DMUS_NOTEF_NOTEON の代わりに 0 を設定する。

Private Sub B7NoteOff()

  Dim noteMsg As DMUS_NOTE_PMSG
  noteMsg.flags = 0
  noteMsg.midiValue = B7Freq  ' B7Freq is pitch of last note-on
  Call perf.SendNotePMSG(0, DMUS_PMSGF_REFTIME, hbchannel, noteMsg)
End Sub

チャンネルのピッチ ベンドは、この操作に影響を与えない。


DirectMusic リファレンス

ここでは、Microsoft® DirectMusic® が C/C++ および Microsoft® Visual Basic® で提供する API (Application Programming Interface) 要素のリファレンス情報を記述する。リファレンス情報は以下の言語別に構成される。

  • DirectMusic C/C++ リファレンス
  • DirectMusic Visual Basic リファレンス


DirectMusic C/C++ リファレンス

ここでは、DirectMusic が提供する API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • インターフェイス
  • メッセージ
  • 構造体
  • ファイル構造体
  • DLS 構造体
  • 列挙型
  • 戻り値


インターフェイス

ここでは、以下の DirectMusic インターフェイス メソッドに関するリファレンスを提供する。

  • IDirectMusic
  • IDirectMusicBand
  • IDirectMusicBuffer
  • IDirectMusicChordMap
  • IDirectMusicCollection
  • IDirectMusicComposer
  • IDirectMusicDownload
  • IDirectMusicDownloadedInstrument
  • IDirectMusicGetLoader
  • IDirectMusicGraph
  • IDirectMusicInstrument
  • IDirectMusicLoader
  • IDirectMusicObject
  • IDirectMusicPerformance
  • IDirectMusicPort
  • IDirectMusicPortDownload
  • IDirectMusicSegment
  • IDirectMusicSegmentState
  • IDirectMusicStyle
  • IDirectMusicThru
  • IDirectMusicTool
  • IDirectMusicTrack
  • IKsControl
  • IReferenceClock


IDirectMusic インターフェイス

IDirectMusic インターフェイスは、バッファ、ポート、マスタ クロックを管理するためのメソッドを提供する。各アプリケーションは、このインターフェイスのインスタンスを複数作成すべきではない。

注 : このインターフェイスを作成するヘルパー関数は存在しない。アプリケーションは COM の CoCreateInstance 関数か IDirectMusicPerformance::Init メソッドを使って DirectMusic オブジェクトを作成する。

IDirectMusic インターフェイスのメソッドは、以下のグループにまとめることができる。

アクティブ化 | Activate
バッファ | CreateMusicBuffer
リンク | SetDirectSound
ポート | CreatePort
 | EnumPort
 | GetDefaultPort
タイミング | EnumMasterClock
 | GetMasterClock
 | SetMasterClock

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusic::Activate

IDirectMusic::Activate メソッドは、このインターフェイスによって作成されたすべての出力ポートのアクティブ化または非アクティブ化を行う。

HRESULT Activate(
  BOOL fEnable
);

パラメータ

fEnable
DirectMusic のこのインスタンスで作成されたすべてのポートをアクティブ化 (TRUE) または非アクティブ化 (FALSE) する。

戻り値

成功すれば S_OK を返す。

失敗すれば DSERR_NODRIVER を返し、サウンド ドライバがないことを示す。

注意

アプリケーションがバックグラウンドで音楽を再生する必要がない場合、入力フォーカスを失った段階で IDirectMusic::Activate(FALSE) を呼び出すべきである。この結果、入力フォーカスが置かれている他のアプリケーションはこれらのポートにアクセスできる。入力フォーカスが再びこのアプリケーションに置かれた段階で、Activate(TRUE) を呼び出し、割り当てられているすべてのポートを使用可能にすべきである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::Activate


IDirectMusic::CreateMusicBuffer

IDirectMusic::CreateMusicBuffer メソッドは、ポートにシーケンス化されているミュージック メッセージを保持する DirectMusicBuffer オブジェクトを作成する。ポートの追加時にバッファ管理はパフォーマンスによって処理されるため、ほとんどのアプリケーションはこのメソッドを呼び出す必要がない。

HRESULT CreateMusicBuffer(
  LPDMUS_BUFFERDESC pBufferDesc,
  LPDIRECTMUSICBUFFER *ppBuffer,
  LPUNKNOWN pUnkOuter
);

パラメータ

pBufferDesc
作成されるミュージック バッファの記述を保持する DMUS_BUFFERDESC 構造体のアドレス。ポインタを渡す前に、アプリケーションはこの構造体の dwSize メンバを初期化しなければならない。「注意」を参照すること。
ppBuffer
IDirectMusicBuffer インターフェイスポインタを受け取る変数のアドレス。
pUnkOuter
COM 集合体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。集合体は現在サポートされていないため、この値は NULL に設定しなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusic::CreatePort

IDirectMusic::CreatePort メソッドは、特定の DirectMusic ポート用のオブジェクトを作成するために使われる。

HRESULT CreatePort(
  REFCLSID rclsidPort,
  LPDMUS_PORTPARAMS pPortParams,
  LPDIRECTMUSICPORT *ppPort,
  LPUNKNOWN pUnkOuter
);

パラメータ

rclsidPort
IDirectMusicPort インターフェイスの作成先となるポートを識別する GUID への参照 (C++) またはアドレス (C)。IDirectMusic::EnumPort メソッドを使って GUID を取り出す。このパラメータが GUID_NULL の場合は、返されるポートがデフォルト ポートになる。詳細については、「デフォルト ポート」を参照すること。
pPortParams
ポートのパラメータを保持する DMUS_PORTPARAMS 構造体のアドレス。このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しなければならない。
ppPort
IDirectMusicPort インターフェイスポインタを受け取る変数のアドレス。
pUnkOuter
COM 集合体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。集合体は現在サポートされていないため、この値は NULL に設定しなければならない。

戻り値

成功すれば S_OK を返す。指定したパラメータが利用できない場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_DSOUND_NOT_SET
E_INVALIDARG
E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

注意

ポートはデフォルトで、作成時には非アクティブになっている。これをアクティブにして、IDirectMusic::Activate または IDirectMusicPort::Activate を呼び出さなければならない。

すべてのパラメータが取得できない場合は、DMUS_PORTPARAMS 構造体を以下のように変更して、ポートの利用できるパラメータと一致させる。

エントリ内では、構造体の dwValidParams メンバによって、構造体内の有効なメンバが示される。構造体のメンバについてフラグをセットしていない場合は、ポートの作成時に、そのパラメータにデフォルト値が設定される。

値が返されると、dwValidParams 内のフラグによって、どのポート パラメータが設定されたかが示される。特定のパラメータを指定せず、デフォルト値に設定した場合、そのフラグは渡されたパラメータに追加される。

指定したパラメータをポートがサポートしていても、パラメータの値が範囲外の場合は、*pPortParams 内のパラメータ値が変更される。この場合、dwValidParams 内のフラグはセットされたままであるが、S_FALSE が返され、値が変更されたことが示される。

次のサンプル コードでは、アプリケーションがどのようにリバーブ機能を要求し、それを取得できたかどうかを判別する方法を示す(ポート プロパティのチェックおよび設定の別の方法については、「ポートのプロパティ セット」を参照すること)。

DMUS_PORTPARAMS params;

ZeroMemory(&params, sizeof(params));
params.dwSize = sizeof(params);
params.dwValidParams = DMUS_PORTPARAMS_EFFECTS;
params.dwEffectFlags = DMUS_EFFECT_REVERB;
HRESULT hr = pDirectMusic->CreatePort(guidPort, &params,
&port, NULL);
if (SUCCEEDED(hr))
{
fGotReverb = TRUE;
if (hr == S_FALSE)
    {
if (!(params.dwValidParams & DMUS_PORTPARAMS_EFFECTS))
        {
// デバイスはどのエフェクトもサポートしない。
fGotReverb = FALSE;
        }
else if (!(params.dwEffectFlags & DMUS_EFFECT_REVERB))
        {
// デバイスはエフェクトを認識するが、
// リバーブを割り当てることはできない。
fGotReverb = FALSE;
        }
    }
}

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusic::EnumMasterClock

IDirectMusic::EnumMasterClock メソッドは、DirectMusic がマスタ クロックとして利用できるクロックの記述の列挙と取得に使われる。このメソッドを呼び出すたびに、1 つのクロックに関する情報を取り出す。

HRESULT EnumMasterClock(
  DWORD dwIndex,
  LPDMUS_CLOCKINFO lpClockInfo
);

パラメータ

dwIndex
記述を取り出したいクロックのインデックス番号。最初に呼び出すときはこのパラメータを 0 に設定し、それ以降は呼び出しのたびに 1 ずつ大きくすべきである。S_FALSE が返されるまで呼び出しを続ける。
lpClockInfo
クロックの記述を受け取る DMUS_CLOCKINFO 構造体のアドレス。ポインタを渡す前に、アプリケーションはこの構造体の dwSize メンバを初期化しなければならない。

戻り値

成功すれば S_OK を返す。指定したインデックス番号を持つクロックが存在しない場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_NOINTERFACE
E_POINTER

注意

アプリケーションはクロックのインデックス番号を信頼したり保存すべきではない。再起動またはハードウェアの追加や削除が行われると、クロックのインデックス番号が変化する可能性がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic::SetMasterClock、IDirectMusic::GetMasterClock


IDirectMusic::EnumPort

IDirectMusic::EnumPort メソッドは、システムに接続されている DirectMusic ポートの能力の列挙と取得に使われる。このメソッドを呼び出すたびに、1 つのポートに関する情報を取り出す。

HRESULT EnumPort(
  DWORD dwIndex,
  LPDMUS_PORTCAPS pPortCaps
);

パラメータ

dwIndex
能力を取り出したいポートのインデックス番号。最初に呼び出すときはこのパラメータを 0 に設定し、それ以降は呼び出しのたびに 1 ずつ大きくすべきである。S_FALSE が返されるまで呼び出しを続ける。
pPortCaps
ポートの能力を受け取る DMUS_PORTCAPS 構造体のアドレス。ポインタを渡す前に、この構造体の dwSize メンバを初期化しなければならない。

戻り値

成功すれば S_OK を返す。指定したインデックス値を持つポートが存在しない場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_NOINTERFACE
E_POINTER

注意

アプリケーションはポートのインデックス番号を信頼したり保存すべきではない。再起動またはハードウェアの追加や削除が行われると、ポートのインデックス番号が変化する可能性がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusic::GetDefaultPort

IDirectMusic::GetDefaultPort メソッドは、デフォルトの出力ポートの GUID を取り出す。これは、IDirectMusic::CreatePort に GUID_NULL を渡したときに作成されるポートである。

HRESULT GetDefaultPort(
  LPGUID pguidPort
);

パラメータ

pguidPort
デフォルトポートの GUID を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

デフォルト ポート


IDirectMusic::GetMasterClock

IDirectMusic::GetMasterClock メソッドは、現在 DirectMusic マスタ クロックとして設定されているクロックの GUID と、IReferenceClock インターフェイスへのポインタを返す。

HRESULT GetMasterClock(
  LPGUID pguidClock,
  IReferenceClock **ppReferenceClock
);

パラメータ

pguidClock
マスタ クロックの GUID を受け取る変数のアドレス。この値が必要ない場合は、アプリケーションは NULL を渡してもよい。
ppReferenceClock
このクロックの IReferenceClock を受け取る変数のアドレス。この値が必要ない場合は、アプリケーションは NULL を渡してもよい。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_NOINTERFACE
E_POINTER

注意

アプリケーションは IReferenceClock インターフェイスを使い終わった後で、このインターフェイスを解放しなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic::SetMasterClock


IDirectMusic::SetDirectSound

IDirectMusic::SetDirectSound メソッドは、ウェーブ出力用に、DirectMusic を DirectSound オブジェクトに接続する。

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

パラメータ

pDirectSound
出力用に使う IDirectSound インターフェイスのアドレス。このパラメータが NULL の場合、DirectSound オブジェクトが作成され、協調レベルが設定される (「注意」を参照すること)。このパラメータに IDirectSound ポインタが含まれる場合は、アプリケーションが協調レベルを設定しなければならない。
hWnd
この呼び出しによって作成される、DirectSound オブジェクトのウィンドウ ハンドル。この値が NULL の場合、現在の前面ウィンドウがフォーカス ウィンドウとして設定される。「注意」を参照すること。

pDirectSound が有効なインターフェイスの場合、このパラメータは無視される。IDirectSound::SetCooperativeLevel の呼び出しでは、アプリケーションが有効なウィンドウ ハンドルを提供する必要があるためである。

戻り値

成功すれば S_OK を返す。

失敗すれば DMUS_E_DSOUND_ALREADY_SET を返す。

注意

指定した DirectSound オブジェクトは、すべてのポート上でオーディオをレンダリングする際に使われるオブジェクトである。このデフォルト値は、IDirectMusicPort::SetDirectSound メソッドを使って上書きできる。

IDirectMusic::SetDirectSound メソッドを呼び出すたびに、既存の DirectSound オブジェクトは解放される。

pDirectSound が NULL の場合、DirectSound を使うポートがアクティブ化されるまで新しい DirectSound オブジェクトは作成されない。DirectSound オブジェクトは、それを使用している最後のポートが非アクティブ化されると自動的に解放される。

DirectSound オブジェクトを自分で作成した場合は、すべてのポートを非アクティブ化した後で、このメソッドの pDirectSound パラメータに NULL を設定して呼び出すことによって解放できる (アクティブなポート対して SetDirectSound を呼び出すことは誤りである)。

hWnd パラメータに NULL を渡して、現在の前面ウィンドウ ハンドルを DirectSound に渡すことができる。ただし、初期化中にアプリケーション ウィンドウが前面にあると想定しないこと。通常、最上レベルのアプリケーション ウィンドウ ハンドルは、DirectMusic、DirectSound、および DirectDraw に渡さなければならない。「IDirectSound::SetCooperativeLevel」の「注意」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

DirectMusic と DirectSound の統合


IDirectMusic::SetMasterClock

IDirectMusic::SetMasterClock メソッドは、IDirectMusic::EnumMasterClock を呼び出した際に取得された GUID によって識別されるクロックを、DirectMusic のマスタ クロックに設定する。すべての DirectMusic アプリケーションは、ただ 1 つのマスタ クロックを使う。

HRESULT SetMasterClock(
  REFGUID rguidClock
);

パラメータ

rguidClock
DirectMusic のマスタ クロックとして設定されるクロックを識別する GUID への参照 (C++) またはアドレス (C)。このパラメータは、IDirectMusic::EnumMasterClock メソッドが返した GUID でなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば DMUS_E_PORTS_OPEN を返す。

注意

実行中の他のアプリケーションも DirectMusic を使っている場合、そのアプリケーションがシャットダウンするまではマスタ クロックを変更できない。

ほどんどのアプリケーションは SetMasterClock を呼び出す必要がない。システムクロック以外のハードウェアタイマとの厳密な同期を必要としない限り、このメソッドを呼び出すべきではない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic::GetMasterClock、IDirectMusic::EnumMasterClock


IDirectMusicBand

IDirectMusicBand インターフェイスは、DirectMusicBand オブジェクトを表す。バンドを使って、一連の P チャンネルの音色の選択肢とミキサ設定を指定する。概要については、「バンドの使い方」を参照すること。

バンドは複数の場所から取り出してもよい。これらを専用のファイルに保存しても、スタイルのバンド リストやセグメントのバンド トラックに埋め込んでもよい。

DirectMusicBand オブジェクトは、自らのデータをロードするために IPersistStream と IDirectMusicObject の各インターフェイスもサポートしている。

IDirectMusicBand インターフェイスのメソッドは、以下のグループにまとめることができる。

セグメント作成 | CreateSegment
音色データ | Download
 | Unload

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_BAND 型は、IDirectMusicBand インターフェイスへのポインタとして定義されている。

typedef IDirectMusicBand __RPC_FAR *LPDMUS_BAND;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicBand::CreateSegment

IDirectMusicBand::CreateSegment メソッドは、IDirectMusicPerformance::PlaySegment メソッドを使って、バンド内でのボリューム、パン、転調、およびパッチ チェンジ コマンドを動的に演奏する。

HRESULT CreateSegment(
  IDirectMusicSegment** ppSegment
);

パラメータ

ppSegment
作成されたセクション セグメントへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_OUTOFMEMORY
E_POINTER

注意

バンドからセグメントを作成する方法の例については、「プログラム的なバンド チェンジの実行」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicBand::Download

IDirectMusicBand::Download メソッドは、バンド内の音色の DLS データをパフォーマンス オブジェクトにダウンロードする。このメソッドは、IDirectMusicPerformance::DownloadInstrument メソッドを呼び出すことによって、バンド内の各音色をダウンロードする。DownloadInstrument は音色の P チャンネルを使って適切なポートを見つけ、そのポートに対して IDirectMusicPort::DownloadInstrument メソッドを呼び出す。

バンドのダウンロードが終わると、そのバンド内の音色は、プログラム チェンジ MIDI メッセージにより個別に選択するか、IDirectMusicBand::CreateSegment メソッドを呼び出して作成したバンド セグメントを再生することにより一度にすべてを選択できる。

HRESULT Download(
  IDirectMusicPerformance* pPerformance
);

パラメータ

pPerformance
楽器のダウンロード先のパフォーマンス。パフォーマンスは P チャンネルから DirectMusic ポートへのマッピングを管理する。

戻り値

成功すれば S_OK または DMUS_S_PARTIALDOWNLOAD を返す (「注意」を参照すること)。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

注意

ダウンロードしたバンドはシンセサイザ リソースを使うため、必要のないときは IDirectMusicBand::Unload メソッドを使ってアンロードしなければならない。

現在のバージョンの DirectMusic の場合、ポートが DLS をサポートしていなくても S_OK が返されることがある。

ダウンロードが完全に失敗した場合は、DMUS_E_NOT_INIT が返される。これは通常、初期化されたポートにパフォーマンスが正常に接続されなかったことを意味する。これは完全な失敗であるため、後で IDirectMusicBand::Unload を呼び出す必要はない。

ダウンロードが一部成功した場合は、DMUS_S_PARTIALDOWNLOAD が返される。これは、正常にダウンロードできた音色とダウンロードできなかった音色があることを意味する。その原因は通常、パフォーマンスとポートの設定においてプログラミング エラーが発生したためである。問題を特定する最良の方法は、Dmime.dll、Dmband.dll、および Dmsynth.dll のデバッグ トレースを 1 に設定することである (「DirectMusic プロジェクトのデバッグ」を参照)。

部分的なダウンロードが発生する一般的な原因を以下に示す。

  • バンドは、パフォーマンスに対して設定されていない P チャンネル上に音色を持っている (IDirectMusicPerformance::AssignPChannelBlock の使用による)。
  • バンドは、ポートに割り当てられていないチャンネル グループの P チャンネル上に音色を持っている。
  • バンドは、音色のダウンロード先となるシンセサイザと互換性のない DLS フォーマットの音色を持っている。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.hで宣言。

参照

IDirectMusicBand::Unload


IDirectMusicBand::Unload

IDirectMusicBand::Unload メソッドは、IDirectMusicBand::Download を使って以前にダウンロードしたバンド内の音色の DLS データをアンロードする。

HRESULT Unload(
  IDirectMusicPerformance* pPerformance
);

パラメータ

pPerformance
楽器のアンロード元のパフォーマンス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicBand::Download、IDirectMusicPort::UnloadInstrument


IDirectMusicBuffer::Flush

IDirectMusicBuffer::Flush メソッドは、バッファ内の全データを破棄する。

HRESULT Flush();

パラメータ

なし。

戻り値

常に S_OK を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicBuffer::GetBufferFormat

IDirectMusicBuffer::GetBufferFormat メソッドは、バッファフォーマットを表す GUID を返す。

HRESULT GetBufferFormat(
  LPGUID pGuidFormat
);

パラメータ

pGuidFormat
バッファフォーマットの GUID を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

バッファを作成したときにフォーマットを指定しなかった場合、*pGuidFormat に KSDATAFORMAT_SUBTYPE_DIRECTMUSIC が返される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic::CreateMusicBuffer、DMUS_EVENTHEADER


IDirectMusicBuffer::GetMaxBytes

IDirectMusicBuffer::GetMaxBytes メソッドは、バッファ内に保存できるバイト数を取り出す。

HRESULT GetMaxBytes(
  LPDWORD pcb
);

パラメータ

pcb
バッファが保持できる最大のバイト数を含む変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicBuffer::GetNextEvent

IDirectMusicBuffer::GetNextEvent メソッドは、バッファ内の以下のメッセージに関する情報を返し、読み込みポインタを先に進める。

HRESULT GetNextEvent(
  LPREFERENCE_TIME prt,
  LPDWORD pdwChannelGroup,
  LPDWORD pdwLength,
  LPBYTE* ppData
);

パラメータ

prt
メッセージのタイムを受け取る変数のアドレス。
pdwChannelGroup
メッセージのチャンネル グループを受け取る変数のアドレス。
pdwLength
メッセージの長さ (バイト単位) を受け取る変数のアドレス。
ppData
メッセージデータへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。ただし、バッファ内にメッセージが存在しなかった場合は S_FALSE を返す。

失敗すれば E_POINTER を返す。

注意

項目が必要ない場合、該当するポインタとして NULL を指定してもよい。

ppData に返されたポインタは、バッファオブジェクトの寿命の間に限って有効である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::ResetReadPtr


IDirectMusicBuffer::GetRawBufferPtr

IDirectMusicBuffer::GetRawBufferPtr メソッドは、根底にあるバッファデータ構造体へのポインタを返す。

HRESULT GetRawBufferPtr(
  LPBYTE* ppData
);

パラメータ

ppData
バッファのデータへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

このメソッドは、バッファの raw データへのポインタを返す。このデータのフォーマットは、実装に依存する。データの寿命は、バッファオブジェクトの寿命と同じである。そのため、次に IDirectMusicBuffer::Release メソッドを呼び出した後は、返されたポインタを保持すべきではない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicBuffer::GetStartTime

IDirectMusicBuffer::GetStartTime メソッドは、バッファ内のデータの開始タイムを取り出す。このタイムはマスタ クロックを基準とする。

HRESULT GetStartTime(
  LPREFERENCE_TIME prt
);

パラメータ

prt
開始タイムを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_BUFFER_EMPTY
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::SetStartTime、IDirectMusicBuffer::TotalTime


IDirectMusicBuffer::GetUsedBytes

IDirectMusicBuffer::GetUsedBytes メソッドは、バッファ内のデータのバイト数を取り出す。

HRESULT GetUsedBytes(
  LPDWORD pcb
);

パラメータ

pcb
使用中のバイト数を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::SetUsedBytes


IDirectMusicBuffer::PackStructured

IDirectMusicBuffer::PackStructured メソッドは、固定長データ (通常は MIDI チャンネル メッセージ) を、タイミング情報およびルーティング情報と共にバッファ内に挿入する。

HRESULT PackStructured(
  REFERENCE_TIME rt,
  DWORD dwChannelGroup,
  DWORD dwChannelMessage
);

パラメータ

rt
メッセージの絶対タイム。「注意」を参照すること。
dwChannelGroup
データが所属するチャンネル グループ。
dwChannelMessage
パックすべきデータ (MIDI メッセージ)。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_INVALID_EVENT
E_OUTOFMEMORY

注意

バッファ内に少なくとも 32 バイト (DMUS_EVENTHEADER と dwChannelMessage の合計サイズ) の空きが存在しなければならない。

rt パラメータには、データがポートに送信される絶対タイムを設定する必要がある。メッセージを即座に演奏するには、遅延時間クロックからこのタイムを取り出し、rt として使用する。「IDirectMusicPort::GetLatencyClock」を参照すること。

同じタイムのスタンプが付いたメッセージは、バッファ内に置かれた順序と同じ順序で演奏されるとは限らない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::PackUnstructured


IDirectMusicBuffer::PackUnstructured

IDirectMusicBuffer::PackUnstructured メソッドは、非構造化データ (通常は MIDI システムエクスクルーシブ メッセージ) を、タイミング情報およびルーティング情報と共にバッファ内に挿入する。

HRESULT PackUnstructured(
  REFERENCE_TIME rt,
  DWORD dwChannelGroup,
  DWORD cb,
  LPBYTE lpb
);

パラメータ

rt
メッセージの絶対タイム。
dwChannelGroup
メッセージが所属するチャンネル グループ。
cb
データのサイズ。バイト単位で指定する。
lpb
データへのポインタ。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_OUTOFMEMORY
E_POINTER

注意

このメソッドを使って、任意のデータをポートに送信できる。

少なくとも 28 バイト (DMUS_EVENTHEADER のサイズ)とデータのサイズを 4 バイトの倍数まで追加したサイズの空きがバッファ内に存在しなければならない。必要なバッファは DMUS_EVENT_SIZE(cb) マクロを使って取得できる。ここで cb はデータのサイズである。

rt パラメータには、データがポートに送信される絶対タイムを設定する必要がある。メッセージを即座に演奏するには、遅延時間クロックからこのタイムを取り出し、rt として使用する。「IDirectMusicPort::GetLatencyClock」を参照すること。

同じタイムのスタンプが付いたメッセージは、バッファ内に置かれた順序と同じ順序で演奏されるとは限らない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::PackStructured


IDirectMusicBuffer::ResetReadPtr

IDirectMusicBuffer::ResetReadPtr メソッドは、読み込みポインタをバッファ内のデータの先頭に設定する。

HRESULT ResetReadPtr()

パラメータ

なし。

戻り値

常に S_OK を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::GetNextEvent


IDirectMusicBuffer::SetStartTime

IDirectMusicBuffer::SetStartTime メソッドは、バッファ内のデータの開始タイムを設定する。このタイムはマスタ クロックを基準とする。

HRESULT SetStartTime(
  REFERENCE_TIME rt
);

パラメータ

rt
バッファの新しい開始タイム。

戻り値

常に S_OK を返す。

注意

バッファ内に既にあるイベントは、開始タイムを基準とするタイム スタンプが付けられ、新しい開始タイムからの同じオフセットから演奏する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::GetStartTime


IDirectMusicBuffer::SetUsedBytes

IDirectMusicBuffer::SetUsedBytes メソッドは、バッファ内のデータのバイト数を設定する。

HRESULT SetUsedBytes(
  DWORD cb
);

パラメータ

cb
バッファ内の有効なデータ バイト数。

戻り値

成功すれば S_OK を返す。

失敗すれば DMUS_E_BUFFER_FULL を返す。

注意

このメソッドを使うと、アプリケーションはバッファを手作業で再パックできる。通常、バッファ内のデータ フォーマットが、DirectMusic の提供するデフォルトのフォーマットと異なるときにのみ、このメソッドを使うべきである。

指定したバイト数が、IDirectMusicBuffer::GetMaxBytes メソッドの返す最大バッファ サイズを超えている場合、このメソッドは失敗する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::GetUsedBytes


IDirectMusicBuffer::TotalTime

IDirectMusicBuffer::TotalTime メソッドは、バッファ内のデータが包含する合計時間を返す。

HRESULT TotalTime(
  LPREFERENCE_TIME prtTime
);

パラメータ

prtTime
バッファ内に包含される合計時間 (100ns 単位) を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer::GetStartTime


IDirectMusicChordMap

IDirectMusicChordMap インターフェイスは、コード マップを表す。コード マップは、コンポーザ (IDirectMusicComposer によって表される) に対し、アレンジするセグメントのコード進行を作成するのに必要な情報を提供する。コード マップは、既存セグメント内のコードを変更する場合にも使用できる。

DirectMusicChordMap オブジェクトは、自らのデータをロードするために IDirectMusicObject と IPersistStream の各インターフェイスもサポートしている。

このインターフェイスは、以下のメソッドをサポートする。

IDirectMusicChordMap GetScale

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicPersonality::GetScale

Platform SDK: DirectX

IDirectMusicChordMap::GetScale

IDirectMusicChordMap::GetScale メソッドは、コード マップに関連付けられているスケールを取り出す。

HRESULT GetScale(
  DWORD* pdwScale
);

パラメータ

pdwScale
スケールの値を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

スケールは、DWORD 内のビットをスケールのパターン (下位 24 ビット) と ルート音 (上位 8 ビット) に分割して定義される。スケールのパターンは、最下位ビット (0x0001) は低音の C、次の上位ビット (0x0002) は C# であり、同様に 2 オクターブのスケールが定義される。上位 8 ビットは、スケールのルート音を 0 ～ 23 (低音の C から中間の B まで) の整数で表す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicCollection

IDirectMusicCollection インターフェイスは、DLS ファイルのインスタンスを管理する。コレクションは、楽器にアクセスするためのメソッドを提供し、IDirectMusicPort インターフェイスを使って楽器をシンセサイザにダウンロードする。

DirectMusicCollection オブジェクトは、自らのデータをロードするために IDirectMusicObject と IPersistStream の各インターフェイスもサポートしている。

コレクションを使った作業の詳細については、「 DLS の使い方」を参照すること。

IDirectMusicCollection インターフェイスのメソッドは、以下のグループにまとめることができる。

楽器 | EnumInstrument
 | GetInstrument

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicCollection::EnumInstrument

IDirectMusicCollection::EnumInstrument メソッドは、コレクション内のインデックスを使って、楽器のパッチ番号と名前を取り出す。

HRESULT EnumInstrument(
  DWORD dwIndex,
  DWORD* pdwPatch,
  LPWSTR pwszName,
  DWORD dwNameLen
);

パラメータ

dwIndex
コレクション内の楽器のインデックス。
pdwPatch
パッチ番号を受け取る変数のアドレス。
pwszName
楽器名を受け取るバッファのアドレス。名前が不要な場合は、NULL でもよい。
dwNameLen
楽器名バッファのサイズ。WCHAR 単位で指定する。

戻り値

成功すれば S_OK を返す。指定されたインデックス番号を持つ楽器が存在しない場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_OUTOFMEMORY
E_POINTER

注意

コレクション内のすべての楽器を列挙するには、dwIndex の値を 0 から始め、EnumInstrument が S_FALSE を返すまで値を大きくする。

pdwPatch に返されるパッチ番号は、バンク セレクトの MSB と LSB の MIDI パラメータも含む、完全なパッチアドレスを記述する。詳細は、「MIDI チャンネル メッセージ」を参照すること。

列挙型の順序は DLS コレクションの 1 つのインスタンス内では整合しているが、この順序はファイル内の楽器の順序、パッチ番号、楽器名のいずれとも関係はない。

楽器の列挙の例については、「音色の操作」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicCollection::GetInstrument

IDirectMusicCollection::GetInstrument メソッドは、パッチ番号を指定して、コレクションから楽器を取り出す。

HRESULT GetInstrument(
  DWORD dwPatch,
  IDirectMusicInstrument** ppInstrument
);

パラメータ

dwPatch
楽器のパッチ番号。
ppInstrument
IDirectMusicInstrument インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_CORE_INVALIDPATCH
E_FAIL
E_OUTOFMEMORY
E_POINTER

注意

dwPatch で渡されたパッチ番号は、バンク セレクトの MSB と LSB の MIDI パラメータも含む、完全なパッチアドレスを記述する。MSB は左シフトされた 16 ビットであり、LSB は左シフトされた 8 ビットである。詳細は、「 MIDI チャンネル メッセージ」を参照すること。

加えて、特に音色がドラム キットであり、MIDI チャンネル 10 で演奏されることを意図している場合は、上位ビット (0x80000000) をセットしなければならない。DLS レベル 1 用のこの特別なタグは、ドラムを必ず MIDI チャンネル 10 に置く。

このメソッドを使う方法の詳細については、「音色の操作」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicComposer

IDirectMusicComposer インターフェイスを使うと、コンポーザ エンジンにアクセスできる。テンプレートやコード マップから新しいセクション セグメントを構築することに加えて、このコンポーザは複数のセクション セグメント間の移行部を作成できる。コード マップを既存のセクション セグメントにも適用できるので、セクションのコード進行と雰囲気も変更できる。

詳細については、「音楽のアレンジ」を参照すること。

IDirectMusicComposer インターフェイスのメソッドは、以下のグループにまとめることができる。

コード マップの変更 | ChangeChordMap
通常のセグメントのアレンジ | ComposeSegmentFromShape
 | ComposeSegmentFromTemplate
テンプレート セグメントのアレンジ | ComposeTemplateFromShape
移行部セグメントのアレンジ | AutoTransition
 | ComposeTransition

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicComposer::AutoTransition

IDirectMusicComposer::AutoTransition メソッドは、パフォーマンスのプライマリ セグメント (または無音) からほかのセグメントへの移行部をアレンジし、演奏の目的でその移行部とセカンダリ セグメントを挿入する。

HRESULT AutoTransition(
  IDirectMusicPerformance* pPerformance,
  IDirectMusicSegment* pToSeg,
  WORD wCommand,
  DWORD dwFlags,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppTransSeg,
  IDirectMusicSegmentState** ppToSegState,
  IDirectMusicSegmentState** ppTransSegState
);

パラメータ

pPerformance
移行部を作成するパフォーマンス。
pToSeg
移行先セクション。移行部はこのセクションへ円滑に移行する。「注意」を参照すること。
wCommand
移行部を作成するときに使われる装飾。DMUS_COMMANDT_TYPES を参照すること。この値が DMUS_COMMANDT_ENDANDINTRO の場合、メソッドは、プライマリ セグメントの終了部と pToSeg の導入部を含むセグメントをアレンジする。
dwFlags
コンポーザ オプション。DMUS_COMPOSEF_FLAGS を参照すること。
pChordMap
移行部をアレンジするときに使うコード マップ。
ppTransSeg
作成されたセクション セグメントへのポインタを受け取る変数のアドレス。この値は NULL でもよい。その場合、ポインタは返されない。
ppToSegState
移行部 (pToSeg) の後のセグメントのパフォーマンス (pPerformance) によって作成されるセグメント状態へのポインタを受け取る変数のアドレス。「注意」を参照すること。
ppTransSegState
作成されたセグメント (ppTransSeg) のパフォーマンス (pPerformance) によって作成されるセグメント状態へのポインタを受け取る変数のアドレス。「注意」を参照すること。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

dwFlags が DMUS_COMPOSEF_MODULATE を含んでいない場合、pToSeg の値は NULL でもよい。pToSeg が NULL またはスタイル トラックを含んでいない場合 (MIDI ファイルに基づいている場合)、イントロの装飾は無効になる。演奏中のセグメントが NULL またはスタイル トラックを含んでいない場合は、フィル、ブレーク、エンド、およびグルーブの装飾が無効になる。演奏中のセグメントまたは pToSeg によって表されるセグメントでスタイル トラックが利用できない場合は、すべての装飾が無効になり、移行は行われない。その場合、ppTransSeg と ppTransSegState の両方が NULL を返すが、ポインタが NULL 以外のときメソッドは成功し、pToSeg によって表されるセグメントが挿入される。

pChordMap の値は NULL でもよい。値が NULL の場合、コード マップ トラックからコード マップを取得する試みが行われる。最初に pToSeg、次にパフォーマンスのプライマリ セグメントが試される。どのセグメントにもコード マップ トラックが含まれない場合は、現在のタイムにプライマリ セグメント内で発生するコードが移行部のコードとして使われる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer::ComposeTransition、移行部の使い方


IDirectMusicComposer::ChangeChordMap

IDirectMusicComposer::ChangeChordMap メソッドは、新しいコード マップを反映して、既存のセクション セグメントのコードとスケールのパターンを変更する。

HRESULT ChangeChordMap(
  IDirectMusicSegment* pSegment,
  BOOL fTrackScale,
  IDirectMusicChordMap* pChordMap
);

パラメータ

pSegment
変更に使うコード マップを含むセクション。
fTrackScale
TRUE の場合、メソッドは、すべてのコードを新しいコード マップ スケールのルート音に相対的に転調する。ルート音をそのままの状態にしない。
pChordMap
セグメントの新しいコード マップ。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

メソッドはセグメントの演奏中に呼び出すことができる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicComposer::ComposeSegmentFromShape

IDirectMusicComposer::ComposeSegmentFromShape メソッドは、あらかじめ定義されたシェイプに基づいて、スタイルとコード マップからオリジナルのセクション セグメントを作成する。このシェイプは、セクション全体で時間の経過に伴ってコードと装飾を発生させる方法を表す。

HRESULT ComposeSegmentFromShape(
  IDirectMusicStyle* pStyle,
  WORD wNumMeasures,
  WORD wShape,
  WORD wActivity,
  BOOL fIntro,
  BOOL fEnd,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppSegment
);

パラメータ

pStyle
セクション セグメントのアレンジに使うスタイル。
wNumMeasures
アレンジするセクション セグメントの長さ。小節単位で指定する。
wShape
アレンジするセクション セグメントのシェイプ。DMUS_SHAPET_TYPES 列挙型のいずれかの値を指定する。
wActivity
和音進行のレート。有効な値は 0 ～ 3。値が低いと、コード チェンジが増える。
fIntro
セクション セグメントの導入部をアレンジしたい場合は TRUE。
fEnd
セクション セグメントの終了部をアレンジしたい場合は TRUE。
pChordMap
セクション セグメントの作成に使うコード マップ。
ppSegment
作成されたセクション セグメントへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer::ComposeSegmentFromTemplate、IDirectMusicComposer::ComposeTemplateFromShape


IDirectMusicComposer::ComposeSegmentFromTemplate

IDirectMusicComposer::ComposeSegmentFromTemplate メソッドは、スタイル、コード マップ、およびテンプレートからオリジナルのセクション セグメントを作成する。

HRESULT ComposeSegmentFromTemplate(
  IDirectMusicStyle* pStyle,
  IDirectMusicSegment* pTemplate,
  WORD wActivity,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppSegment
);

パラメータ

pStyle
セクション セグメントの作成に使うスタイル。
pTemplate
セクション セグメントの作成に使うテンプレート。
wActivity
和音進行のレート。有効な値は 0 ～ 3。値が低いと、コード チェンジが増える。
pChordMap
セクション セグメントの作成に使うコード マップ。
ppSegment
作成されたセクション セグメントへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_POINTER

注意

pStyle が NULL ではない場合、このスタイルはセグメントのアレンジに使われる。NULL の場合、pTempSeg で指定されたテンプレートから取り出したスタイルをセグメントの作曲に使う。同様に、pChordMap が NULL ではない場合、このコード マップはセグメントのアレンジに使われる。NULL の場合、上記のテンプレートから取り出したコード マップをセグメントのアレンジに使う。

pStyle が NULL でテンプレート内にスタイル トラックが存在しない場合や、pChordMap が NULL でコード マップ トラックが存在しない場合、このメソッドは E_INVALIDARG を返す。

セクション セグメントの長さは、渡されたテンプレート セクションの長さと等しくなる。

作成されたセグメントのデフォルトの開始ポイントとループ ポイントは、テンプレート セグメント内の値に関係なく 0 である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer::ComposeSegmentFromShape、IDirectMusicComposer::ComposeTemplateFromShape、テンプレートの使い方


IDirectMusicComposer::ComposeTemplateFromShape

IDirectMusicComposer::ComposeTemplateFromShape メソッドは、あらかじめ定義されたシェイプに基づいて新しいテンプレートを作成する。

HRESULT ComposeTemplateFromShape(
  WORD wNumMeasures,
  WORD wShape,
  BOOL fIntro,
  BOOL fEnd,
  WORD wEndLength,
  IDirectMusicSegment** ppTemplate
);

パラメータ

wNumMeasures
アレンジするセクション セグメントの長さ。小節単位で指定する。0 より大きい値でなければならない。
wShape
アレンジするセクション セグメントのシェイプ。DMUS_SHAPET_TYPES 列挙型のいずれかの値を指定する。
fIntro
セクション セグメントの導入部をアレンジしたい場合は TRUE。
fEnd
セクション セグメントの終了部をアレンジしたい場合は TRUE。
wEndLength
終了部を作成したい場合は、終了部の長さ。小節単位で指定する。fEnd が TRUE の場合、この値は 0 より大きく、利用できる小節の数以下でなければならない (つまり、導入部では使われない)。「注意」も参照すること。
ppTemp;ate
作成されたセクション セグメントへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

wEndLength の値は、IDirectMusicComposer::ComposeSegmentFromTemplate メソッドを使ってこのテンプレートに関連付けられる可能性のある任意のスタイル内で利用できる最長の終了部の長さを超えてはならない。終了部は、セグメントが終わる前の wEndLength の小節で演奏を開始する。終了部が wEndLength の小節の長さより短い場合、音楽は基本グルーブ レベルに戻る。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer::ComposeSegmentFromShape、IDirectMusicComposer::ComposeSegmentFromTemplate、テンプレートの使い方


IDirectMusicComposer::ComposeTransition

IDirectMusicComposer::ComposeTransition メソッドは、あるセクション セグメントからほかのセクション セグメントへの移行部をアレンジする。

HRESULT ComposeTransition(
  IDirectMusicSegment* pFromSeg,
  IDirectMusicSegment* pToSeg,
  MUSIC_TIME mtTime,
  WORD wCommand,
  DWORD dwFlags,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppTransSeg
);

パラメータ

pFromSeg
移行部のアレンジに使われる移行元のセクション。
pToSeg
移行先セクション。移行部はこのセクションへ円滑に移行する。dwFlags が DMUS_COMPOSEF_MODULATE を含んでいない場合、NULL でもよい。
mtTime
pFromSeg のセクション内で移行部のアレンジを開始するタイム。
wCommand
移行部を作成するときに使われる装飾。DMUS_COMMANDT_TYPES を参照すること。この値が DMUS_COMMANDT_ENDANDINTRO の場合、メソッドは、pFromSeg の終了部と pToSeg の導入部を含むセグメントをアレンジする。
dwFlags
コンポーザ オプション。このパラメータは、DMUS_COMPOSEF_FLAGS 列挙型の値の 1 つまたは複数を保持していてもよい。
pChordMap
移行部をアレンジするときに使うコード マップ。「注意」を参照すること。
ppTransSeg
作成されたセクション セグメントへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

pChordMap の値は NULL でもよい。値が NULL の場合、コード マップ トラックからコード マップを取得する試みが行われる。最初に pToSeg、次に pFromSeg が試される。どのセグメントにもコード マップ トラックが含まれない場合は、mtTime に pFromSeg 内で発生するコードが移行部のコードとして使われる。

コンポーザは、最初に pFromSeg 内、次に pToSeg 内でテンポを探す。どのセグメントにもテンポ トラックがない場合、移行部セグメントのテンポはスタイルから取得される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer::AutoTransition、移行部の使い方


IDirectMusicDownload

IDirectMusicDownload インターフェイスは、連続したメモリ チャンクを表し、DLS シンセサイザ ポートへのダウンロードを行うために使われる。

IDirectMusicDownload インターフェイスとその中に含まれているメモリチャンクは、IDirectMusicPortDownload::AllocateBuffer メソッドによって作成される。その後、このインターフェイスの 1 つのメソッドを使って、このメモリにアクセスできる。

このインターフェイスは、以下のメソッドをサポートする。

IDirectMusicDownload GetBuffer

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicDownload::GetBuffer

IDirectMusicDownload::GetBuffer メソッドは、ダウンロードすべきデータを保持するバッファへのポインタを取り出す。

HRESULT GetBuffer(
  void** ppvBuffer,
  DWORD* pdwSize
);

パラメータ

ppvBuffer
データバッファへのポインタを受け取る変数のアドレス。
pdwSize
返されたバッファのサイズ (バイト単位 ) を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_BUFFERNOTAVAILABLE
E_POINTER

注意

バッファが既にダウンロードされている場合、このメソッドは DMUS_E_BUFFERNOTAVAILABLE を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicDownloadedInstrument

IDirectMusicDownloadedInstrument インターフェイスを使って、IDirectMusicPort::DownloadInstrument メソッドまたは IDirectMusicPerformance::DownloadInstrument メソッドによりシンセサイザへダウンロードされた音色を識別する。次にこのインターフェイスを使い、IDirectMusicPort::UnloadInstrument を呼び出して、その楽器をアンロードする。音色をアンロードしたら、インターフェイス ポインタはアプリケーションによって解放されなければならない。

具体的な例は、「音色の操作」を参照すること。

IDirectMusicDownloadedInstrument インターフェイスには、独自のメソッドはない。すべての COM インターフェイスと同様、IDirectMusicDownloadedInstrument インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicGetLoader

あるオブジェクトが、ストリームの形で参照されている他のオブジェクトをロードする必要があるときに、最初のオブジェクトは IDirectMusicGetLoader インターフェイスを使ってストリームを解析する。ストリームがローダーをサポートしている場合、ストリームは必ず IDirectMusicGetLoader インターフェイスを提供している。

ストリームから IDirectMusicGetLoader インターフェイスを取得する方法の例は、IDirectMusicGetLoader::GetLoader を参照すること。

IDirectMusicGetLoader インターフェイスは、以下のメソッドをサポートする。

IDirectMusicGetLoader GetLoader

すべての COM インターフェイスと同様、IDirectMusicTrack インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader、DirectMusic ローダー、カスタム ロード


IDirectMusicGetLoader::GetLoader

IDirectMusicGetLoader::GetLoader メソッドは、ストリームを作成したローダー オブジェクトへのポインタを取り出す。

HRESULT GetLoader(
  IDirectMusicLoader ** ppLoader
);

パラメータ

ppLoader
IDirectMusicLoader インターフェイスポインタを受け取る変数のアドレス。このインターフェイスの参照カウントはインクリメントされる。

戻り値

成功すれば S_OK を返す。

失敗すれば E_NOINTERFACE を返す。

注意

次のサンプル コードは、ローダーがアクセスする必要のあるオブジェクトへの参照を見つけるファイル パーサーから抜粋したものである。

HRESULT myGetReferencedObject(
    DMUS_OBJECTDESC *pDesc,          // 記述子は既に準備できている。
    IStream *pIStream,               // 解析対象のストリーム。
    IDirectMusicObject **ppIObject)  // アクセスしたいオブジェクト。
{
    IDirectMusicGetLoader *pIGetLoader;
    IDirectMusicLoader *pILoader;
    ppIObject = NULL;
    HRESULT hr = pIStream->QueryInterface(
           IID_IDirectMusicGetLoader,
           (void **) &pIGetLoader );
    if (SUCCEEDED(hr))
    {
        hr = pIGetLoader->GetLoader(&pILoader);
        if (SUCCEEDED(hr))
        {
            hr = pILoader->GetObject(pDesc, IID_DirectMusicLoader,
                  (void**) ppIObject);
            pILoader->Release();
        }
        pIGetLoader->Release();
    }
    return hr;
}

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

カスタム ロード


IDirectMusicGraph

IDirectMusicGraph インターフェイスは、ツールのロードとメッセージ フローを管理する。

グラフは、セグメントとパフォーマンスの 2 つの場所に置くことができる。パフォーマンス内のツールに対応するグラフは、性質上グローバルであり、そのためにあらゆるセグメントのメッセージを処理する。あるセグメント内のグラフは、そのセグメントの再生だけを目的として存在する。

IDirectMusicGraph インターフェイスのメソッドは、以下のグループにまとめることができる。

ルーティング | StampPMsg
ツール | GetTool
 | InsertTool
 | RemoveTool

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicGraph::GetTool

IDirectMusicGraph::GetTool メソッドは、指定されたインデックスのツールを取り出す。

HRESULT GetTool(
  DWORD dwIndex,
  IDirectMusicTool** ppTool
);

パラメータ

dwIndex
グラフ内の希望のツールを指定する、0 から始まるインデックス。
ppTool
ツールへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

アプリケーションには、取り出したツールを解放する責任がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicGraph::InsertTool

IDirectMusicGraph::InsertTool メソッドは、グラフにツールを挿入する。

HRESULT InsertTool(
  IDirectMusicTool * pTool,
  DWORD * pdwPChannels,
  DWORD cPChannels,
  LONG lIndex
);

パラメータ

pTool
挿入するツール。
pdwPChannels
ツールがメッセージを受け取る P チャンネルの配列のアドレス。このツールがあらゆる P チャンネルでメッセージを受け取る場合、NULL を渡す。
cPChannels
pdwPChannels が指す P チャンネルの数。pdwPChannels が NULL の場合は無視される。
lIndex
ツールを置く位置。これは 0 から始まるインデックスであり、現在のツールリストの先頭または最後 (値が負の場合 ) から数えた位置を意味する。lIndex が範囲外の場合、ツールはリストの先頭または最後に置かれる。ツールをリストの最後に置くには、現在のツールリスト内のツール数より大きい値を lIndex で指定する。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_ALREADY_EXISTS
E_OUTOFMEMORY
E_POINTER

注意

ツールの参照カウントはインクリメントされる。

このメソッドは IDirectMusicTool::Init を呼び出す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicGraph::RemoveTool

IDirectMusicGraph::RemoveTool メソッドは、グラフからツールを削除する。

HRESULT RemoveTool(
  IDirectMusicTool * pTool
);

パラメータ

pTool
削除するツールを含む変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

このツールへのグラフの参照は解放される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicGraph::StampPMsg

IDirectMusicGraph::StampPMsg メソッドは、メッセージを受け取る次のツールへのポインタをメッセージにスタンプする。ツールは、メッセージを処理した後、このメソッドを呼び出さなければならない。

HRESULT StampPMsg(
  DMUS_PMSG* pPMSG
);

パラメータ

pPMSG
スタンプの対象となるメッセージを保持する構造体のアドレス。この構造体は、DMUS_PMSG の派生タイプである。メッセージ タイプの概要については、「メッセージ」を参照すること。

戻り値

成功すれば S_OK を返す。失敗すれば DMUS_S_LAST_TOOL を返す。「注意」を参照すること。

失敗すれば E_POINTER を返す。

注意

エントリ内の pPMSG->pTool (「DMUS_PMSG」を参照) は、現在のツールを指す。StampPMsg はこのメンバを使って、現在のツールを決定し、グラフ内の次のツールを見つける。NULL の値はグラフ内の最初のツールを表す。

pPMSG->pGraph が指すオブジェクトは、ツールを保持するグラフを表す。StampPMsg 内部でこの値がツール自体の値と共にスタンプされる。複数のツール グラフが存在する場合、メッセージがセグメント状態からパフォーマンスへ移動する過程で、この値が変更されることがある。

pPMSG->dwType の値は、メッセージのメディア タイプに等しく、次のツールを見つけるのに使われる。メディア タイプとしてサポートされているのは、IDirectMusicTool::GetMediaTypes メソッドが返す値である。

pPMSG->dwPChannel の値を使ってトラックを指定するが、ツールはこのトラックを処理する能力を備えていなければならない。セクションをオーサリングする際に割り当てられた固有の番号を使ってトラックを識別する。

このメソッドは pPMSG->pTool が指す現在の IDirectMusicTool に対して Release を呼び出し、グラフ内の次のツールに置き換え、新しいツールに対して AddRef を呼び出す。

このメソッドは、次のツールが IDirectMusicTool::GetMsgDeliveryType メソッドで返すタイプに基づいて、メッセージに正しい引き渡しタイプ フラグも割り当てる。このフラグは、メッセージを次のツールに配信する時期を決定する。

DirectMusicSegmentState と DirectMusicPerformance の各オブジェクトでのこのメソッドを実装すると、成功した場合、常に S_OK を返す。DirectMusicGraph で実装すると、メッセージの受け取りを待っている出力ツールのほかにツールがない場合、DMUS_S_LAST_TOOL を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

DirectMusic ツール


IDirectMusicInstrument

IDirectMusicInstrument インターフェイスは、DLS コレクションの個別の音色を表す。

DirectMusicInstrument オブジェクトを作成して、音色をダウンロードするための唯一の方法は、最初に DirectMusicCollection オブジェクトを作成し、次に IDirectMusicCollection::GetInstrument メソッドを呼び出す。GetInstrument は DirectMusicInstrument オブジェクトを作成し、IDirectMusicInstrument インターフェイス ポインタを返す。

音色をダウンロードするには、その音色のインターフェイス ポインタを IDirectMusicPort::DownloadInstrument メソッドまたは IDirectMusicPerformance::DownloadInstrument メソッドに渡す。このメソッドが成功すると、IDirectMusicDownloadedInstrument インターフェイスへのポインタが返される。このインターフェイスは、楽器をアンロードする場合にのみ使われる。

IDirectMusicInstrument のメソッドは、既にダウンロードされている音色のみに対して動作する。既にポートにダウンロードされた楽器のインスタンスは、IDirectMusicInstrument::GetPatch や IDirectMusicInstrument::SetPatch の各メソッドの影響を受けない。

このインターフェイスは、以下のメソッドをサポートする。

IDirectMusicInstrument | GetPatch
 | SetPatch

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicInstrument::GetPatch

IDirectMusicInstrument::GetPatch メソッドは、楽器のパッチ番号を取り出す。このパッチ番号は、バンク セレクトの MSB と LSB、および MIDI パッチ (プログラムチェンジ) 番号によって構成されたアドレスである。オプションのフラグ ビットは、音色が旋律系の音色ではなく、ドラムであることを表す。

HRESULT GetPatch(
  DWORD* pdwPatch
);

パラメータ

pdwPatch
パッチ番号を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

pdwPatch に返されるパッチ番号は、バンク セレクトの MSB と LSB の MIDI パラメータも含む、完全なパッチ番号を記述する。加えて、特に音色がドラム キットであり、MIDI チャンネル 10 で演奏されることを意図している場合は、上位ビットがセットされる。DLS レベル 1 はドラムを必ず MIDI チャンネル 10 で演奏するため、これが DLS レベル 1 用の特別なタグである。詳細については、「MIDI チャンネル メッセージ」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicInstrument::SetPatch

IDirectMusicInstrument::SetPatch メソッドは、楽器用のパッチ番号を設定する。DLS コレクション内の各楽器はあらかじめ定義されたパッチ番号を持っているが、IDirectMusicCollection::GetInstrument メソッドを使ってコレクションから楽器を取り出した後、パッチ番号を再割り当てすることもできる。DirectMusic パッチ番号の詳細については、IDirectMusicInstrument::GetPatch を参照すること。

HRESULT SetPatch(
  DWORD dwPatch
);

パラメータ

dwPatch
楽器に割り当てる新しいパッチ番号。

戻り値

成功すれば S_OK を返す。

失敗すれば DMUS_E_INVALIDPATCH を返す。

注意

次のサンプル コードは、コレクションから音色を取得し、音色の MSB バンクの再マップを行って他のバンクを選択し、その音色をダウンロードする。

HRESULT myRemappedDownload(
    IDirectMusicCollection *pCollection,
    IDirectMusicPort *pPort,
    IDirectMusicDownloadedInstrument **ppDLInstrument,
    BYTE bMSB,       // パッチ番号のバンク セレクト内で指定された MIDI の MSB。
    DWORD dwPatch)   // 指定されたパッチ番号。

{
    HRESULT hr;
    IDirectMusicInstrument* pInstrument;
    hr = pCollection->GetInstrument(dwPatch, &pInstrument);
    if (SUCCEEDED(hr))
    {
        dwPatch &= 0xFF00FFFF;  // MSB を消去する。
        dwPatch |= bMSB << 16;  // 新しい MSB の値を設定する。
        pInstrument->SetPatch(dwPatch);
        hr = pPort->DownloadInstrument(pInstrument,
                ppDLInstrument,
                NULL, 0);       // すべてのリージョンをダウンロードする。
        pInstrument->Release();
    }
    return hr;
}

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicLoader

IDirectMusicLoader インターフェイスは、オブジェクトの検索、列挙、キャッシング、およびロードに使われる。詳細については、「DirectMusic ローダー」を参照すること。

IDirectMusicLoader インターフェイスのメソッドは、以下のグループにまとめることができる。

検索 | EnumObject
 | ScanDirectory
 | SetSearchDirectory
キャッシング | CacheObject
 | ClearCache
 | EnableCache
オブジェクト管理 | GetObject
 | ReleaseObject
 | SetObject

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_LOADER 型は、IDirectMusicLoader インターフェイスへのポインタとして定義されている。

typedef IDirectMusicLoader __RPC_FAR *LPDMUS_LOADER;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicLoader::CacheObject

IDirectMusicLoader::CacheObject メソッドは、オブジェクトへの参照を維持するようローダーに指示する。この結果、オブジェクトを 2 回ロードしないことが保証される。

HRESULT CacheObject(
  IDirectMusicObject * pObject
);

パラメータ

pObject
キャッシュに入れるオブジェクトの IDirectMusicObject インターフェイスのアドレス。

戻り値

成功すれば S_OK を返す。オブジェクトが既にキャッシュに入っている場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
DMUS_E_LOADER_OBJECTNOTFOUND

注意

アプリケーションの実行期間中、複数の場所からアクセスされるオブジェクトが存在する場合、ローダーにそのオブジェクトをキャッシングさせるとパフォーマンスが大幅に高速化される。概要については、「オブジェクトのキャッシング」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader::EnableCache、IDirectMusicLoader::ClearCache、IDirectMusicLoader::ReleaseObject


IDirectMusicLoader::ClearCache

IDirectMusicLoader::ClearCache メソッドは、特定のタイプのオブジェクトへのすべての参照を解放するようローダーに指示する。

HRESULT ClearCache(
  REFGUID rguidClass
);

パラメータ

rguidClass
消去されるオブジェクトのクラス識別子への参照 (C++) またはアドレス (C)。GUID_DirectMusicAllTypes を使って、すべてのタイプを指定できる。

戻り値

S_OK を返す。

注意

このメソッドは現在保持されているすべてのオブジェクトを消去するが、キャッシングを無効にすることはない。自動的なキャッシングを無効にするには、IDirectMusicLoader::EnableCache メソッドを使う。

キャッシュから 1 つのオブジェクトを消去するには、IDirectMusicLoader::ReleaseObject メソッドを呼び出す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader::CacheObject、オブジェクトのキャッシング


IDirectMusicLoader::EnableCache

IDirectMusicLoader::EnableCache メソッドは、ロードされるすべてのオブジェクトの自動的なキャッシングを有効または無効にするようローダーに指示する。デフォルトでは、すべてのクラスでキャッシングが有効になっている。

HRESULT EnableCache(
  REFGUID rguidClass,
  BOOL fEnable
);

パラメータ

rguidClass
キャッシングされるオブジェクトのクラス識別子への参照 (C++) またはアドレス (C)。GUID_DirectMusicAllTypes を使って、すべてのタイプを指定できる。
fEnable
キャッシングを有効にする場合は TRUE、キャッシングを無効にして消去する場合は FALSE。

戻り値

キャッシュの状態が変更される場合は S_OK、キャッシュが既に希望の状態になっている場合は S_FALSE を返す。

注意

キャッシングを無効にせずにキャッシュを消去するには、IDirectMusicLoader::ClearCache メソッドを呼び出す。

次のサンプル コードは、セグメント オブジェクトに限ってキャッシングを無効にするので、アプリケーションがそれらを解放した後はそれらのオブジェクトはメモリ内にとどまることはない。スタイル、コード マップ、DLS コレクションなど、共有すべきその他のオブジェクトは引き続きキャッシングされている。デフォルトですべてのオブジェクトのキャッシングは有効になっているので、EnableCache の最初の呼び出しは、通常は不要である。

void myPrepareLoader(IDirectMusicLoader *pILoader)

{
    pILoader->EnableCache(GUID_DirectMusicAllTypes, TRUE);
    pILoader->EnableCache(CLSID_DirectMusicSegment, FALSE);
}

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader::CacheObject、IDirectMusicLoader::ClearCache、オブジェクトのキャッシング


IDirectMusicLoader::EnumObject

IDirectMusicLoader::EnumObject メソッドは、要求したタイプの利用可能なすべてのオブジェクトを列挙する。利用可能なオブジェクトとは、既にロードされているもの、または IDirectMusicLoader::ScanDirectory を呼び出したときに検索ディレクトリ内に存在していたものである。

HRESULT EnumObject(
  REFGUID rguidClass,
  DWORD dwIndex,
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

rguidClass
表示されるオブジェクトのクラス識別子への参照 (C++) またはアドレス (C)。
dwIndex
リストのインデックス。通常は 0 から始まって、値が順に大きくなる。
pDesc
オブジェクトに関するデータを入力するための DMUS_OBJECTDESC 構造体のアドレス。

戻り値

成功すれば S_OK を返す。dwIndex がリストの最後を超えている場合は S_FALSE を返す。

注意

このメソッドの使い方の例は、「オブジェクトの列挙」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader::ScanDirectory


IDirectMusicLoader::GetObject

IDirectMusicLoader::GetObject メソッドは、指定されたオブジェクトをファイルまたはリソースから取り出し、希望のインターフェイスを返す。

HRESULT GetObject(
  LPDMUS_OBJECTDESC pDESC,
  REFIID riid,
  LPVOID FAR * ppv
);

パラメータ

pDESC
オブジェクトについて記述する DMUS_OBJECTDESC 構造体のアドレス。
riid
インターフェイスの一意の識別子。Dmusici.h で定義されている IID を参照すること。標準的なインターフェイスはすべて、"IID_" とインターフェイスの名前で構成される定義済みの識別子を持つ。たとえば、IDirectMusicTrack の識別子は IID_IDirectMusicTrack である。
ppv
オブジェクトの希望のインターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK または DMUS_S_PARTIALLOAD を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

注意

DMUS_S_PARTIALLOAD の戻り値によっては、デフォルトの音色コレクション ファイル、Gm.dls が利用できないことを意味する場合がある。

現在のバージョンの DirectMusic は、URL からのロードをサポートしていない。DMUS_OBJECTDESC 構造体の dwValidData メンバが DMUS_OBJ_URL を含んでいる場合、このメソッドは DMUS_E_LOADER_FORMATNOTSUPPORTED を返す。

このメソッドは、オブジェクトを取り出す前に DMUS_OBJECTDESC の相当するメンバを必要とすることはない。このメソッドは次の順序で検索を行う。

  1. DMUS_OBJ_OBJECT
  2. DMUS_OBJ_MEMORY
  3. DMUS_OBJ_FILENAME と DMUS_OBJ_FULLPATH
  4. DMUS_OBJ_NAME と DMUS_OBJ_CATEGORY
  5. DMUS_OBJ_NAME
  6. DMUS_OBJ_FILENAME

言い換えると、最も優先順位が高いのは一意の GUID、以下、リソース、フル パス名、内部名とカテゴリ、内部名、ローカル ファイル名の順である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader::ReleaseObject, IDirectMusicLoader::ScanDirectory


IDirectMusicLoader::ReleaseObject

IDirectMusicLoader::ReleaseObject メソッドは、オブジェクトへのローダーの参照を解放する。

HRESULT ReleaseObject(
  IDirectMusicObject * pObject
);

パラメータ

pObject
解放するオブジェクトを含む変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
DMUS_E_LOADER_OBJECTNOTFOUND

注意

ReleaseObject は、IDirectMusicLoader::CacheObject と対をなすメソッドである。

CacheObject メソッドを使って明示的に、または IDirectMusicLoader::EnableCache メソッドを使って自動的にオブジェクトをキャッシングできる。

特定のタイプのすべてのオブジェクトをフラッシュ (解放 ) するようローダーに指示するには、IDirectMusicLoader::ClearCache メソッドを呼び出す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader::GetObject、オブジェクトのキャッシング


IDirectMusicLoader::ScanDirectory

IDirectMusicLoader::ScanDirectory メソッドは、ディスク内のあるディレクトリで、指定されたクラス タイプとファイル拡張子を持つすべてのファイルを検索する。ファイルが見つかるたびに、IDirectMusicObject::ParseDescriptor メソッドを呼び出して、オブジェクトの GUID と名前を抽出する。この情報は内部データベースに保存される。あるディレクトリを検索した後、指定されたすべてのファイルは IDirectMusicLoader::EnumObject メソッドの列挙型として利用可能になる。加えて、IDirectMusicLoader::GetObject を使ったときに、ファイル名なしでもオブジェクトが取り出し可能になる。

HRESULT ScanDirectory(
  REFGUID rguidClass,
  WCHAR* pwzFileExtension,
  WCHAR* pwzScanFileName
);

パラメータ

rguidClass
オブジェクトのクラス識別子への参照 (C++) またはアドレス (C)。
pwzFileExtension
検索対象のファイル タイプのファイル拡張子。たとえば、L"sty" はスタイル ファイルを意味する。"*" を使って、任意の拡張子の付いたファイルまたは拡張子のないファイルを検索する。
pwzScanFileName
キャッシングされたファイル情報の保存と取り出しを行うためのオプションの保存ファイルの名前。最初に ScanDirectory を呼び出したときにこのファイルが作成され、それ以降の呼び出しで使われる。キャッシュファイルが不要な場合は NULL を指定する。

戻り値

成功すれば S_OK を返す。ファイルが見つからなかった場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_FOUND
E_FAIL
E_OUTOFMEMORY
E_POINTER
REGDB_E_CLASSNOTREG

注意

検索の場所を設定するために、最初に IDirectMusicLoader::SetSearchDirectory メソッドを呼び出さなければならない。

pwzScanFileName で定義されたファイルに、検索された情報を保存できる。保存を行うと、変更を加えられたファイルだけが検索されるため、それ以降の ScanDirectory の呼び出しが大幅に高速化される (キャッシュ ファイルは各オブジェクトのファイル サイズと日付を保存するので、ファイルが変更された場合はそのことを検出できる)。

ファイル タイプが複数の拡張子を持っている場合、拡張子ごとに ScanDirectory を 1 回呼び出す。

GUID_DirectMusicAllTypes は rguidClass の有効な値ではない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

ディレクトリでのオブジェクト検索


IDirectMusicLoader::SetObject

IDirectMusicLoader::SetObject メソッドは、オブジェクトが、ロード中の別のオブジェクトによって後で参照されるときに、オブジェクトの検索場所をローダーに指示する。次に、オブジェクトに属性を追加することによって、属性を使ってそのオブジェクトを参照できるようにする。概要については、「オブジェクトの設定」を参照すること。

HRESULT SetObject(
  LPDMUS_OBJECTDESC pDESC
);

パラメータ

pDESC
オブジェクトについて記述する DMUS_OBJECTDESC 構造体のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

注意

このメソッドを使って、オブジェクトについて現在有効でない属性を設定できる。たとえば、DMUS_OBJECTDESC 構造体の wszName メンバに値を入力し、MIDI ファイルに基づくセグメントなど、名前のないオブジェクトに内部名を割り当てることができる。ただし、既存属性を変更する目的でこのメソッドを使用することはできない。たとえば、ほとんどのオーサリングされたセグメントは既に名前を持っており、これらの名前をアプリケーションによって変更することはできない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader::GetObject


IDirectMusicLoader::SetSearchDirectory

IDirectMusicLoader::SetSearchDirectory メソッドは、オブジェクトファイルを検索するための検索パスを設定する。1 つのオブジェクト タイプ、またはすべてのファイルに対する検索パスを設定できる。

HRESULT SetSearchDirectory(
  REFGUID rguidClass,
  WCHAR* pwszPath,
  BOOL fClear
);

パラメータ

rguidClass
呼び出しに関係のあるオブジェクトのクラス識別子への参照 (C++) またはアドレス (C)。GUID_DirectMusicAllTypes は、すべてのタイプを指定する。
pwszPath
ディレクトリのファイルパス。長さが MAX_PATH 以下の有効なディレクトリ名でなければならない。
fClear
TRUE の場合、ディレクトリを設定する前に、オブジェクトに関するすべての情報を消去する。この結果、同じ名前を持つ他のディレクトリにあるオブジェクトへのアクセスを回避できる。ただし、それらのオブジェクトはキャッシュから削除されるわけではない。

戻り値

成功すれば S_OK を返す。検索ディレクトリが既に pwszPath に設定されている場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_BADPATH

注意

検索パスを設定した後、ローダーはファイル名を使ってオブジェクトをロードするときに、フルパス名を必要としない。この結果、オブジェクトはフル パスを把握していなくても他のオブジェクトを参照できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader::ScanDirectory、ローダーの検索ディレクトリの設定


IDirectMusicObject

ファイルからロードできるすべての DirectMusic オブジェクトは、DirectMusic ローダーと組み合わせて動作するように、IDirectMusicObject インターフェイスをサポートしている。新しいタイプのオブジェクトは、このインターフェイスを実装しなければならない。詳細については、「カスタム ロード」を参照すること。

ほとんどのアプリケーションは、このインターフェイスのメソッドを直接使用しない。ただし、IDirectMusicObject::GetDescriptor を使って、オブジェクトの名前、GUID、ファイル パス、バージョンなど、オブジェクトに関する情報を問い合わせることができる。

IDirectMusicObject インターフェイスは、別のインターフェイスの QueryInterface メソッドを呼び出すことによって取得しなければならない。CoCreateInstance を使って呼び出すことはできない。

IDirectMusicObject インターフェイスは、以下のメソッドをサポートする。

ディスクリプタ | GetDescriptor
 | ParseDescriptor
 | SetDescriptor

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_OBJECT 型は、IDirectMusicObject インターフェイスへのポインタとして定義されている。

typedef IDirectMusicObject __RPC_FAR *LPDMUS_OBJECT;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

DirectMusic ローダー、カスタム ロード


IDirectMusicObject::GetDescriptor

IDirectMusicObject::GetDescriptor メソッドは、オブジェクトの内部的な記述を取り出す。

このメソッドは DMUS_OBJECTDESC 構造体をとり、オブジェクトが自らについて知っているすべてのことをその構造体に入力する。

HRESULT GetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

pDesc
オブジェクトに関するデータを入力するための DMUS_OBJECTDESC 構造体のアドレス。オブジェクトの実装と、オブジェクトをファイルからロードした方法に基づいて、GetDescriptor が標準的なパラメータの一部またはすべてを入力する。dwValidData メンバ内のフラグをチェックして、他のどのメンバが有効なのか把握する。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

具体的な例については、「オブジェクト デスクリプタの取得」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicObject::SetDescriptor


IDirectMusicObject::ParseDescriptor

IDirectMusicObject::ParseDescriptor メソッドはファイル ストリームを受け取り、DMUS_OBJECTDESC 構造体に保存できるデータをファイルから検索する。dwValidData 内で、供給されたメンバに対して適切なフラグを割り当てる。

このメソッドは、主にローダーがディレクトリでオブジェクトを検索する際に使われるものであり、通常はアプリケーションが直接利用することはない。ただし、アプリケーションが DirectMusic 内にオブジェクト タイプを実装する場合、そのアプリケーションはこのメソッドをサポートすべきである。

HRESULT ParseDescriptor(
  LPSTREAM pStream,
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

pStream
ファイルのストリーム ソース。
pDesc
ファイルに関するデータを受け取る DMUS_OBJECTDESC 構造体のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_CHUNKNOTFOUND
DMUS_E_INVALID_BAND
DMUS_E_INVALIDFILE
DMUS_E_NOTADLSCOL
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicObject::SetDescriptor


IDirectMusicObject::SetDescriptor

IDirectMusicObject::SetDescriptor メソッドは、オブジェクトの内部的な記述を一部またはすべてのメンバに設定する。

このメソッドは、主にローダーがオブジェクトを作成する際に使われるものであり、通常はアプリケーションが直接利用することはない。ただし、アプリケーションが DirectMusic 内にオブジェクト タイプを実装する場合、そのアプリケーションはこのメソッドをサポートすべきである。

HRESULT SetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

pDesc
オブジェクトに関するデータを受け取る DMUS_OBJECTDESC 構造体のアドレス。dwValidData メンバで有効と定義されているすべてのメンバにデータがコピーされる。

戻り値

成功すれば S_OK または S_FALSE (「注意」を参照すること) を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_POINTER

注意

アプリケーションは通常、標準的なオブジェクトに対してこのメソッドを呼び出すことはない。IDirectMusicObject::GetDescriptor によって返されるオブジェクト ディスクリプタを変更することは可能であるが、新しい記述を IDirectMusicLoader::GetObject メソッドに正常に渡すことはできない。たとえば、オブジェクトの名前は変更できるが、GetObject はオブジェクトの元の名前を使ってそのオブジェクトを検索する。これは、GetObject がオブジェクト自身の SetDescriptor の実装に依存しているためである。

コピーされなかったメンバは、それまでの値を維持する。たとえば、あるオブジェクトが名前と GUID を既に内部で保存していたとする。新しい名前とファイル パスを指定して (さらに dwValidData に DMUS_OBJ_NAME | DMUS_OBJ_FILENAME を含めて) SetDescriptor メソッドを呼び出すと、名前は置き換えられ、ファイル名が供給されるが、GUID だけは元の値のままになる。

オブジェクトが 1 つまたは複数のメンバを設定できない場合、自らがサポートしているメンバだけを設定し、サポートしていないメンバに対応する dwValidData 内のフラグを消去し、S_FALSE を返す。アプリケーションによって定義されるオブジェクトは、少なくとも DMUS_OBJ_NAME と DMUS_OBJ_OBJECT をサポートすべきである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicObject::ParseDescriptor、IDirectMusicObject::GetDescriptor


IDirectMusicPerformance

IDirectMusicPerformance インターフェイスは、音楽再生の総合的なマネージャである。このインターフェイスは、ポートの追加と削除、パフォーマンス チャンネルのポートへのマッピング、セグメントの演奏、ツールによるメッセージの発信とルーティング、イベント通知の要求と受け取り、およびミュージック パラメータの設定と取り出しに使用される。また、タイミングに関する情報の取得、およびシステム間でタイムとミュージック値を変換するためのメソッドも備えている。

アプリケーションが 2 つの完全なミュージック セットを同時に演奏したい場合、複数のパフォーマンスを作成することにより、そのような演奏が行える。個別のパフォーマンスは独立したテンポマップに従い、完全に非同期に演奏されるが、一方で 1 つのパフォーマンス内のすべてのセグメントは固定的なステップで演奏される。

IDirectMusicPerformance インターフェイスのメソッドは、以下のグループにまとめることができる。

チャンネル | AssignPChannel
 | AssignPChannelBlock
 | PChannelInfo
楽器 | DownloadInstrument
メッセージ | AllocPMsg
 | FreePMsg
 | SendPMsg
MIDI 変換 | MIDIToMusic
 | MusicToMIDI
通知 | AddNotificationType
 | GetNotificationPMsg
 | RemoveNotificationType
 | SetNotificationHandle
パラメータ | GetGlobalParam
 | GetParam
 | SetGlobalParam
 | SetParam
ポート | AddPort
 | RemovePort
セグメント | GetSegmentState
 | IsPlaying
 | PlaySegment
 | Stop
タイミング | AdjustTime
 | GetBumperLength
 | GetLatencyTime
 | GetPrepareTime
 | GetQueueTime
 | GetResolvedTime
 | GetTime
 | MusicToReferenceTime
 | ReferenceToMusicTime
 | RhythmToTime
 | SetBumperLength
 | SetPrepareTime
 | TimeToRhythm
ツール | GetGraph
 | SetGraph
その他 | CloseDown
 | Init
 | Invalidate

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance::AddNotificationType

IDirectMusicPerformance::AddNotificationType メソッドは、パフォーマンスに通知タイプを追加する。AddNotificationType メソッドを呼び出すと、すべてのセグメントとトラックは新しい通知によって自動的に更新される。

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
追加される通知タイプの識別子への参照 (C++) またはアドレス (C)。定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること。アプリケーションは、カスタム トラックについて独自のタイプを定義できる。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_OUTOFMEMORY
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::RemoveNotificationType、IDirectMusicSegment::AddNotificationType、IDirectMusicTrack::AddNotificationType、通知とイベントの処理


IDirectMusicPerformance::AddPort

IDirectMusicPerformance::AddPort メソッドは、パフォーマンスにポートを割り当てる。

HRESULT AddPort(
  IDirectMusicPort* pPort
);

パラメータ

pPort
追加するポートを含む変数のアドレス。NULL の場合はデフォルト ポートが追加される。「注意」を参照すること。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_INIT
DMUS_E_CANNOT_OPEN_PORT
E_OUTOFMEMORY
E_POINTER

注意

このメソッドに NULL を渡したい場合は、最初にIDirectMusicPerformance::Init に NULL を渡す必要がある。

pPort に NULL を渡してデフォルト ポートが指定された場合、このデフォルト ポートには 1 つのチャンネル グループが割り当てられる。その他のポートについて P チャンネル が設定されていない場合、0 ～ 15 の P チャンネルが、0 ～ 15 の MIDI チャンネルに割り当てられる。

pPort が NULL でない場合、IDirectMusicPort::Activate の呼び出しによってポートをアクティブ化し、IDirectMusicPerformance::AssignPChannelBlock の呼び出しによってチャンネル ブロックを割り当てなければならない。

このメソッドは、IDirectMusicPerformance::RemovePort または IDirectMusicPerformance::CloseDown によって解放される IDirectMusicPort への参照を作成する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::RemovePort、デフォルト ポート


IDirectMusicPerformance::AdjustTime

IDirectMusicPerformance::AdjustTime メソッドは、パフォーマンスの内部時間を前方または後方に調整する。このメソッドはほとんどの場合、他のソースとの同期化を行う際にずれを補正するために使われる。

HRESULT AdjustTime(
  REFERENCE_TIME rtAmount
);

パラメータ

rtAmount
加算または減算される時間。－10,000,000 から 10,000,000 (－1 秒から +1 秒) の数値を指定する。

戻り値

成功すれば S_OK を返す。

失敗すれば E_INVALIDARG を返す。

注意

調整された時間は、DirectMusic によって内部的に使用される。IDirectMusicPerformance::GetTime メソッドによって取り出される時間には反映されない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::GetTime、タイミング


IDirectMusicPerformance::AllocPMsg

IDirectMusicPerformance::AllocPMsg メソッドは、パフォーマンス メッセージを割り当てる。

HRESULT AllocPMsg(
  ULONG cb,
  DMUS_PMSG** ppPMSG
);

パラメータ

cb
メッセージ構造体のサイズ。ほかのさまざまなタイプについては、「メッセージ」を参照すること。
ppPMSG
割り当てられたメッセージ構造体へのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

返されたメモリは特定の状態に初期化されていない。ただし、DMUS_PMSG 構造体の pTool メンバと dwSize メンバは例外で、前者は 0 に初期化され、後者は cb の値に設定される。

メッセージが IDirectMusicPerformance::SendPMsg によっていったん送信されると、アプリケーションはメモリを確保せず、メッセージの解放も行わない。ただし、ツールは、その IDirectMusicTool::Flush メソッドまたは IDirectMusicTool::ProcessPMsg メソッド内でメッセージを解放できる。アプリケーションは、通知メッセージの解放も行う。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::FreePMsg、IDirectMusicPerformance::SendPMsg、DirectMusic メッセージ


IDirectMusicPerformance::AssignPChannel

IDirectMusicPerformance::AssignPChannel メソッドは、1 つのパフォーマンス チャンネル (P チャンネル) をパフォーマンスに割り当て、このチャンネルをポート、グループ、MIDI チャンネルにマップする。

HRESULT AssignPChannel(
  DWORD dwPChannel,
  IDirectMusicPort* pPort,
  DWORD dwGroup,
  DWORD dwMChannel
);

パラメータ

dwPChannel
割り当てられる P チャンネル。
pPort
P チャンネルの割り当て先のポートを含む変数のアドレス。
dwGroup
ポート上のチャンネル グループ。
dwMChannel
グループ内のチャンネル。0 ～ 15 の範囲でなければならない。

戻り値

成功すれば S_OK または S_FALSE (「注意」を参照すること) を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_POINTER

注意

dwGroup がポートの範囲外の場合、このメソッドは S_FALSE を返す。チャンネルは割り当てられるが、ポートはそのグループを演奏できない。

dwMChannel が範囲外、または IDirectMusicPerformance::AddPort メソッドを呼び出してポートをパフォーマンスに追加する作業を行っていない場合、このメソッドは E_INVALIDARG を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::AssignPChannelBlock、IDirectMusicPerformance::PChannelInfo、チャンネル


IDirectMusicPerformance::AssignPChannelBlock

IDirectMusicPerformance::AssignPChannelBlock メソッドは、16 のパフォーマンス チャンネル (P チャンネル) から成るグループをパフォーマンスに割り当て、それらをポートとチャンネル グループにマップする。ポートをパフォーマンスに追加したときは、このメソッドを呼び出さなければならない。ただし、IDirectMusicPerformance::AddPort に NULL を渡すことによってデフォルト ポートを追加した場合を除く。

HRESULT AssignPChannelBlock(
  DWORD dwBlockNum,
  IDirectMusicPort* pPort,
  DWORD dwGroup
);

パラメータ

dwBlockNum
ブロック番号。0 はチャンネル 0 ～ 15、1 はチャンネル 16 ～ 31 を表す。以下同様である。
pPort
チャンネルの割り当て先のポートを含む変数のアドレス。
dwGroup
ポート上のチャンネル グループ。1 以上の値でなければならない。

戻り値

成功すれば S_OK または S_FALSE (「注意」を参照すること) を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_POINTER

注意

dwGroup がポートの範囲外の場合、このメソッドは S_FALSE を返す。チャンネルは割り当てられるが、ポートはそのグループを演奏できない。

dwMChannel が範囲外、または IDirectMusicPerformance::AddPort メソッドを呼び出してポートをパフォーマンスに追加する作業を行っていない場合、このメソッドは E_INVALIDARG を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::AssignPChannel、IDirectMusicPerformance::PChannelInfo、チャンネル


IDirectMusicPerformance::CloseDown

IDirectMusicPerformance::CloseDown メソッドは、パフォーマンス オブジェクトを閉じる。パフォーマンス オブジェクトを作成し、そのオブジェクトに対して IDirectMusicPerformance::Init を呼び出したアプリケーションは、パフォーマンスを解放する前に CloseDown を呼び出さなければならない。

HRESULT CloseDown();

パラメータ

なし。

戻り値

S_OK を返す。

注意

CloseDown の呼び出しを忘れると、メモリ リークやプログラム障害が発生することがある。

アプリケーションが NULL または NULL へのポインタを IDirectMusicPerformance::Init に渡して DirectMusic オブジェクトが作成された場合、CloseDown は IDirectMusic インターフェイスを処理する。アプリケーションが DirectMusic オブジェクトを明示的に作成し、Init へのポインタを渡した場合には、そのアプリケーションが IDirectMusic インターフェイスを解放しなければならない。

CloseDown は、まだアンロードされていない任意のダウンロード済みの音色も解放する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::Init


IDirectMusicPerformance::DownloadInstrument

IDirectMusicPerformance::DownloadInstrument メソッドは、音色の DLS データをポートにダウンロードする。

HRESULT DownloadInstrument(
  IDirectMusicInstrument* pInst,
  DWORD dwPChannel,
  IDirectMusicDownloadedInstrument** ppDownInst,
  DMUS_NOTERANGE* pNoteRanges,
  DWORD dwNumNoteRanges,
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

パラメータ

pInst
ダウンロードする音色を含む変数のアドレス。
dwPChannel
楽器の割り当て先のパフォーマンス チャンネル (P チャンネル)。
ppDownInst
ダウンロードされた楽器へのポインタを受け取る変数のアドレス。
pNoteRanges
DMUS_NOTERANGE 構造体の配列のアドレス。配列内の各エントリは、楽器が応答しなければならない MIDI 音符メッセージの連続範囲を指定する。音色のリージョンがダウンロードされるのは、そのリージョン内の少なくとも 1 つの音符が DMUS_NOTERANGE 構造体で指定されている場合に限られる。
dwNumNoteRanges
pNoteRanges が指す配列内の DMUS_NOTERANGE 構造体の数。この値が 0 に設定されている場合、pNoteRanges パラメータは無視され、この音色用のすべてのリージョンとウェーブ データがダウンロードされる。
ppPort
音色のダウンロード先のポートへのポインタを受け取る変数のアドレス。
pdwGroup
音色の割り当て先のグループを受け取る変数のアドレス。
pdwMChannel
音色の割り当て先の MIDI チャンネルを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_POINTER

注意

音色のダウンロードは通常、バンドによって処理されるため、ほとんどのアプリケーションではこのメソッドを使う必要がない。「バンドのダウンロードとアンロード」を参照すること。

P チャンネルがポートに割り当てられていない場合、このメソッドは E_INVALIDARG を返す。

リソースの浪費を防ぐには、音色が不要になったときに、IDirectMusicPort::UnloadInstrument メソッドを使ってアンロードする。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPort::DownloadInstrument,、IDirectMusicPort::UnloadInstrument、音色の操作


IDirectMusicPerformance::FreePMsg

IDirectMusicPerformance::FreePMsg メソッドは、メッセージを解放する。

HRESULT FreePMsg(
  DMUS_PMSG* pPMSG
);

パラメータ

pPMSG
解放するメッセージを含む変数のアドレス。このメッセージは、IDirectMusicPerformance::AllocPMsg メソッドで割り当てられたものでなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_CANNOT_FREE
E_POINTER

注意

ほとんどのメッセージは、処理されると、パフォーマンスによって自動的に解放される。また、IDirectMusicPerformance::SendPMsg を使って送信されたメッセージに対して、IDirectMusicPerformance::FreePMsg を呼び出してはならない。ただし、IDirectMusicPerformance::FreePMsg を IDirectMusicTool::ProcessPMsg または IDirectMusicTool::Flush 内で使って、不要なメッセージを解放できる。通知メッセージを解放する際にも、IDirectMusicPerformance::FreePMsg を使用しなければならない。

このメソッドは、以下の場合に DMUS_E_CANNOT_FREE を返す。

  • pPMSG が、AllocPMsg を使って割り当てたメッセージを表していない場合。
  • IDirectMusicPerformance::SendPMsg を呼び出したために pPMSG が現在パフォーマンス キューに置かれている場合。
  • pPMSG が既に解放されている場合。

pTool、pGraph、punkUser いずれかのメンバ (DMUS_PMSG を参照) 内に値が存在する場合、参照されている各オブジェクトは解放される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::AllocPMsg、DirectMusic メッセージ


IDirectMusicPerformance::GetBumperLength

IDirectMusicPerformance::GetBumperLength メソッドは、メッセージがポート バッファに置かれたタイムと、ポートがメッセージの処理を開始するタイムの間の時間を取り出す。この項目の概要については、「タイミング」を参照すること。

HRESULT GetBumperLength(
  DWORD* pdwMilliSeconds
);

パラメータ

pdwMilliSeconds
演奏前の時間の長さを含む変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

デフォルトの値は 50ミリ秒 (ms) である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SetBumperLength


IDirectMusicPerformance::GetGlobalParam

IDirectMusicPerformance::GetGlobalParam メソッドは、パフォーマンスからグローバル値を取り出す。

HRESULT GetGlobalParam(
  REFGUID rguidType,
  void* pParam,
  DWORD dwSize
);

パラメータ

rguidType
データ タイプの識別子への参照 (C++) またはアドレス (C)。
pParam
データのコピーを受け取るために割り当てられたメモリへのポインタ。pParam には正しいサイズを指定しなければならない。サイズは各データ タイプについて一定である。このパラメータは、IDirectMusicPerformance::SetGlobalParam メソッドに渡された情報を含む。
dwSize
データのサイズ。rguidType ごとに一定の値である。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_POINTER

注意

SetGlobalParam が rguidType について一度も呼び出されたことがない場合、このパフォーマンスが現在処理しているグローバル データ リストの中に、rguidType がない可能性がある。その場合、このメソッドは E_INVALIDARG を返す。つまり、どのパラメータにも、GetGlobalParam を使って取り出すことのできるデフォルト値があると想定しないこと。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SetGlobalParam、IDirectMusicPerformance::GetParam、ミュージック パラメータ


IDirectMusicPerformance::GetGraph

IDirectMusicPerformance::GetGraph メソッドは、パフォーマンスのツール グラフを取り出す。

HRESULT GetGraph(
  IDirectMusicGraph** ppGraph
);

パラメータ

ppGraph
ツール グラフへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

グラフの参照カウントはインクリメントされる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SetGraph、IDirectMusicSegment::GetGraph、IDirectMusicPerformance::SendPMsg


IDirectMusicPerformance::GetLatencyTime

IDirectMusicPerformance::GetLatencyTime メソッドは、現在の遅延時間を取り出す。遅延時間は、スピーカから音楽が聞こえている時間に、メッセージをキューに入れて IDirectMusicPort にレンダリングするための所要時間を加えた長さになる。この項目の概要については、「タイミング」を参照すること。

HRESULT GetLatencyTime(
  REFERENCE_TIME * prtTime
);

パラメータ

prtTime
現在の遅延時間を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance::GetNotificationPMsg

IDirectMusicPerformance::GetNotificationPMsg メソッドは、保留中の通知メッセージを取り出す。

HRESULT GetNotificationPMsg(
  DMUS_NOTIFICATION_PMSG** ppNotificationPMsg
);

パラメータ

ppNotificationPMsg
DMUS_NOTIFICATION_PMSG 構造体へのポインタを受け取る変数のアドレス。このメッセージを受け取ったアプリケーションは、そのメッセージに対して IDirectMusicPerformance::FreePMsg を呼び出す責任がある。

戻り値

成功すれば S_OK を返す。返される通知イベントが存在しない場合は S_FALSE を返す。

失敗すれば E_POINTER を返す。

注意

具体的な例については、アレンジの使い方を記載したチュートリアルの「ステップ 9 : 通知の処理」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理


IDirectMusicPerformance::GetParam

IDirectMusicPerformance::GetParam メソッドは、制御セグメント内のトラックからデータを取り出す。

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

パラメータ

rguidType
取得されるデータ タイプの識別子への参照 (C++) またはアドレス (C)。「トラック パラメータのタイプ」を参照すること。
dwGroupBits
希望のトラックが置かれるグループ (「注意」を参照すること)。すべてのグループを指定するには、この値を 0xFFFFFFFF に設定する。
dwIndex
データの取得に使われるグループ内で、トラックに割り当てられているインデックス。
mtTime
データを取得するタイム。パフォーマンス時間で指定する。
pmtNext
データが有効になるタイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、pmtNext を NULL に設定してもよい。「注意」を参照すること。
pParam
返されるデータの保存用に割り当てられた構造体のアドレス。返されるデータの保存用に割り当てられた構造体のアドレス。この構造体は、rguidType で識別されたデータ タイプにとって適切な種類とサイズを備えていなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_GET_UNSUPPORTED
DMUS_E_NO_MASTER_CLOCK
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。制御セグメントの詳細については、「セグメント」および「DMUS_SEGF_FLAGS」を参照すること。

別の制御セグメントが挿入される場合、*pParam で返されるデータは、*pmtNext で返されるタイムの前に無効になることがある。

各トラックは 1 つまたは複数のグループに所属するが、各グループは dwGroupBits 内のビットによって表されている。詳細については、「IDirectMusicSegment::InsertTrack」および「トラックの識別」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicTrack::GetParam、IDirectMusicPerformance::SetGlobalParam、IDirectMusicPerformance::GetTime、ミュージック パラメータ


IDirectMusicPerformance::GetPrepareTime

IDirectMusicPerformance::GetPrepareTime メソッドは、IDirectMusicTrack::Play を呼び出してから、スピーカを通してメッセージが実際に聞かれるまでの時間を取り出す。この間隔は、ツールがメッセージを処理するのに十分な時間である。

HRESULT GetPrepareTime(
  DWORD* pdwMilliSeconds
);

パラメータ

pdwMilliSeconds
準備時間を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

デフォルトの値は 1,000ミリ秒 (ms) である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SetPrepareTime、タイミング


IDirectMusicPerformance::GetQueueTime

IDirectMusicPerformance::GetQueueTime メソッドは、現在のフラッシュ時間を取り出す。フラッシュ時間とは、キュー内のメッセージをフラッシュ (解放) できる最も早いタイムである。このタイムより早いタイムのタイム スタンプを持つメッセージは、既にポートに送信されており、無効化することができない。

HRESULT GetQueueTime(
  REFERENCE_TIME * prtTime
);

パラメータ

prtTime
現在のフラッシュ時間を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

遅延時間とバンパー時間


IDirectMusicPerformance::GetResolvedTime

IDirectMusicPerformance::GetResolvedTime メソッドは、指定されたタイムを、指定された境界に解決する。

HRESULT GetResolvedTime(
  REFERENCE_TIME rtTime,
  REFERENCE_TIME* prtResolved,
  DWORD dwTimeResolveFlags
);

パラメータ

rtTime
解決するタイム。このタイムが現在タイムより早い場合は、現在タイムが使用される。
prtResolved
解決済みのタイムを受け取る変数のアドレス。
dwTimeResolveFlags
希望の分解能を記述する 1 つまたは複数の DMUS_TIME_RESOLVE_FLAGS。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

タイミング


IDirectMusicPerformance::GetSegmentState

IDirectMusicPerformance::GetSegmentState メソッドは、現在演奏中のプライマリ セグメント状態、または特定の時点で演奏されているプライマリ セグメント状態を取り出す。

HRESULT GetSegmentState(
  IDirectMusicSegmentState ** ppSegmentState,
  MUSIC_TIME mtTime
);

パラメータ

ppSegmentState
セグメント状態へのポインタを受け取る変数のアドレス。呼び出し元は、このポインタに対して Release を呼び出す責任がある。
mtTime
セグメント状態が取り出されるタイム。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

現在演奏されているセグメント状態を取得するには、IDirectMusicPerformance::GetTime メソッドを使って返されるタイムを渡す。現在演奏されているセグメント状態は、現在メッセージを生成しているセグメントを表す。遅延時間が存在するため、必ずしも現在演奏されているセグメント状態が現在スピーカから実際に聞こえているとは限らない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance::GetTime

IDirectMusicPerformance::GetTime メソッドは、パフォーマンスの現在のタイムを取り出す。

HRESULT GetTime(
  REFERENCE_TIME* prtNow,
  MUSIC_TIME* pmtNow
);

パラメータ

prtNow
現在のタイムを REFERENCE_TIME フォーマットで受け取る変数のアドレス。NULL でもよい。
pmtNow
現在のタイムを MUSIC_TIME フォーマットで受け取る変数のアドレス。NULL でもよい。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NO_MASTER_CLOCK
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

タイミング


IDirectMusicPerformance::Init

IDirectMusicPerformance::Init メソッドは、パフォーマンスを DirectMusic オブジェクトと DirectSound オブジェクトに関連付ける。

HRESULT Init(
  IDirectMusic** ppDirectMusic,
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

パラメータ

ppDirectMusic
パフォーマンスに割り当てる IDirectMusic インターフェイス ポインタがある場合、それを含む変数のアドレス。このインターフェイスの参照カウントはインクリメントされる。IDirectMusicPerformance::AddPort メソッドに渡すポートは、この DirectMusic オブジェクトから作成されたものでなければならない。

変数に NULL が含まれる場合、DirectMusic オブジェクトが作成され、インターフェイス ポインタが返される。

ppDirectMusic が NULL の場合、DirectMusic オブジェクトが作成され、パフォーマンスによって内部的に使用される。

「注意」を参照すること。

pDirectSound
ウェーブ出力用にデフォルトで使う IDirectSound インターフェイスのアドレス。この値が NULL の場合、DirectMusic によって DirectSound オブジェクトが作成される。ただし、DirectSound オブジェクトが存在できるのは 1 つのプロセスにつき 1 つだけである。アプリケーションで DirectSound を個別に使っている場合、そのインターフェイスを pDirectSound に渡さなければならない。アプリケーションが DirectMusic オブジェクトを明示的に作成する場合は、そのインターフェイスを IDirectMusic::SetDirectSound に渡さなければならない。
hWnd
DirectSound の作成に使うウィンドウ ハンドル。このパラメータは NULL でもよい。その場合、前面ウィンドウが使用される。「注意」を参照すること。

pDirectSound が NULL の場合、このパラメータは無視される。その場合、IDirectSound::SetCooperativeLevel の呼び出しにおいて、アプリケーションがウィンドウ ハンドルの設定を行わなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_ALREADY_INITED
E_OUTOFMEMORY
E_POINTER

注意

このメソッドは 1 回だけ呼び出すべきであり、パフォーマンスが演奏を開始する前に呼び出さなければならない。

DirectMusic オブジェクトは、以下の方法のいずれかを使って、パフォーマンスに関連付けることができる。

  • アプリケーションが独自の DirectMusic オブジェクトを作成し、IDirectMusic ポインタのアドレスを ppDirectMusic に渡すことによって、そのオブジェクトをパフォーマンスに提供する。この場合、アプリケーションが IDirectMusic::SetDirectSound を呼び出す必要があるため、pDirectSound と hWnd の各パラメータは無視される。
  • アプリケーションがパフォーマンスによる DirectMusic オブジェクトの作成を許可し、そのオブジェクトへのポインタを必要とする。この場合、エントリ時の *ppDirectMusic は NULL で、終了時には IDirectMusic ポインタを保持する。
  • アプリケーションがパフォーマンスによるそれ自身の初期化を許可し、DirectMusic オブジェクト ポインタを必要としない。この場合、ppDirectMusic は NULL である。

パフォーマンスを解放する前に、IDirectMusicPerformance::CloseDown メソッドを使ってパフォーマンスを終了しなければならない。

hWnd パラメータに NULL を渡して、現在の前面ウィンドウ ハンドルを DirectSound に渡すことができる。ただし、アプリケーション ウィンドウが初期化中に前面にあると想定しないこと。通常、最上レベルのアプリケーション ウィンドウ ハンドルは、DirectMusic、DirectSound、および DirectDraw に渡される。「IDirectSound::SetCooperativeLevel」の「注意」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

パフォーマンスの作成、DirectMusic と DirectSound の統合


IDirectMusicPerformance::Invalidate

IDirectMusicPerformance::Invalidate メソッドは、指定されたタイムから前方に向かってキュー内のすべてのメッセージをフラッシュ (解放) し、指定されたタイムから前方に向かってすべてのセグメントがデータを再送するようすべてのトラックに通知する。

HRESULT Invalidate(
  MUSIC_TIME mtTime,
  DWORD dwFlags
);

パラメータ

mtTime
無効にするタイム。dwFlags によって調整を加えられる。この値を 0 に設定すると、即座に無効にする。
dwFlags
mtTime を調整して小節、拍、またはグリッドに揃えるフラグ。この値は、0 または次に示す DMUS_SEGF_FLAGS 列挙型メンバのいずれかである。

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

戻り値

成功すれば S_OK を返す。

失敗すれば DMUS_E_NO_MASTER_CLOCK を返す。

注意

mtTime がかなり前のタイムで、そのタイムで無効化が行えない場合は、利用可能な範囲で最も早いタイムを使う。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

準備時間、セグメントのタイミング


IDirectMusicPerformance::IsPlaying

IDirectMusicPerformance::IsPlaying メソッドは、特定のセグメントまたはセグメント状態がスピーカから聞こえているかどうかを判別する。

HRESULT IsPlaying(
  IDirectMusicSegment* pSegment,
  IDirectMusicSegmentState* pSegState
);

パラメータ

pSegment
チェックされるセグメント。NULL の場合、pSegState だけをチェックする。
pSegState
チェックされるセグメント状態。NULL の場合、pSegment だけをチェックする。

戻り値

このメソッドが成功し、要求したセグメントとセグメント状態のどちらかが演奏されている場合は S_OK を返す。どちらも演奏されていない場合、またはどちらか 1 つだけを要求し、それが演奏されていない場合は、S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance::MIDIToMusic

IDirectMusicPerformance::MIDIToMusic メソッドは、提供されるコード、サブコード レベル、および演奏モードを使って、MIDI 音符の値を DirectMusic ミュージック値に変換する。

HRESULT MIDIToMusic(
  BYTE bMIDIValue,
  DMUS_CHORD_KEY* pChord,
  BYTE bPlayMode,
  BYTE bChordLevel,
  WORD *pwMusicValue
);

パラメータ

bMIDIValue
変換する MIDI 音符の値。0 ～ 127 の範囲で指定する。
pChord
音符の変換で使われるコードとキーの構造に関する情報を含む DMUS_CHORD_KEY 構造体のアドレス。これには、基調のスケールも含まれる。たとえば、コードが CM7 の場合、音符はルート音 C、メジャー 7 度のコード音程に照らして解釈される。この構造体は、8 個の平行したサブコードを、それぞれのコード音程、ルート音、スケール、および転回フラグと共に保持する。また、全体的なキーのルート音も保持する。
bPlayMode
ミュージック値がコードからどのように派生するかを決定する演奏モード。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bChordLevel
使用できるサブコードを定義するサブコード レベル。「DMUS_SUBCHORD」を参照すること。
pwMusicValue
ミュージック値を受け取る変数のアドレス。この値の詳細については、「DMUS_NOTE_PMSG」を参照すること。

戻り値

成功すれば次のいずれかを返す。「注意」を参照すること。

S_OK
DMUS_S_DOWN_OCTAVE
DMUS_S_UP_OCTAVE

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_CANNOT_CONVERT
E_INVALIDARG

注意

メソッドが失敗した場合、*pwMusicValue は変更されない。

戻り値が DMUS_S_UP_OCTAVE または DMUS_DOWN_OCTAVE の場合、音符変換では 0 未満または 128 以上の音符の値が生成されるため、0 ～ 127 の適切な MIDI 範囲に収まるように、1 または複数オクターブ分だけ上または下に移動される。これは、演奏モード DMUS_PLAYMODE_FIXEDTOCHORD および DMUS_PLAYMODE_FIXEDTOKEY を使うときに発生することがある。どちらも、MIDI 値を *pwMusicValue に返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::MusicToMIDI、ミュージック値と MIDI 音符


IDirectMusicPerformance::MusicToMIDI

IDirectMusicPerformance::MusicToMIDI メソッドは、DirectMusic ミュージック値を MIDI 音符の値に変換する。

HRESULT MusicToMIDI(
  WORD wMusicValue,
  DMUS_CHORD_KEY* pChord,
  BYTE bPlayMode,
  BYTE bChordLevel,
  BYTE *pbMIDIValue
);

パラメータ

wMusicValue
変換するミュージック値。ミュージック値については、「DMUS_NOTE_PMSG」を参照すること。
pChord
音符の変換で使われるコードとキー構造に関する情報を含む DMUS_CHORD_KEY 構造体のアドレス。これには、基調のスケールも含まれる。たとえば、コードが CM7 の場合、音符はルート音 C、メジャー 7 度のコード音程に照らして解釈される。この構造体は、8 個の平行したサブコードを、それぞれのコード音程、ルート音、スケール、および転回フラグと共に保持する。また、全体的なキーのルート音も保持する。
bPlayMode
ミュージック値がコードにどのように関連するかを決定する演奏モード。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bChordLevel
使用できるサブコードを定義するサブコード レベル。「DMUS_SUBCHORD」を参照すること。
pbMIDIValue
MIDI 値を受け取る変数のアドレス。0 ～ 127 の範囲で指定する。

戻り値

成功すれば次のいずれかを返す。「注意」を参照すること。

S_OK
DMUS_S_OVER_CHORD
DMUS_S_DOWN_OCTAVE
DMUS_S_UP_OCTAVE

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_CANNOT_CONVERT
E_INVALIDARG

注意

メソッドが失敗した場合または DMUS_S_OVER_CHORD を返す場合、*pwMIDIValue は変更されない。

ミュージック値がコードの最高音より高い位置にある音符を持っているため、音符が計算されない場合は、DMUS_S_OVER_CHORD を返す。これは、DMUS_PLAYMODE_NORMALCHORD 演奏モードだけに適用される。アプリケーションは音符に対して何の処理もしてはならない。音符はこのコードに対して演奏されるものではない。

戻り値が DMUS_S_UP_OCTAVE または DMUS_DOWN_OCTAVE の場合、音符変換では 0 未満または 128 以上の音符の値が生成されるため、0 ～ 127 の適切な MIDI 範囲に収まるように、1 または複数オクターブ分だけ上または下に移動される。これは、DMUS_PLAYMODE_FIXED 以外の演奏モードを使うときに発生することがある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::MIDIToMusic、ミュージック値と MIDI 音符


IDirectMusicPerformance::MusicToReferenceTime

IDirectMusicPerformance::MusicToReferenceTime メソッドは、MUSIC_TIME フォーマットの時間を REFERENCE_TIME フォーマットに変換する。

HRESULT MusicToReferenceTime(
  MUSIC_TIME mtTime,
  REFERENCE_TIME* prtTime
);

パラメータ

mtTime
変換される、MUSIC_TIME フォーマットの時間。
prtTime
REFERENCE_TIME フォーマットに変換された時間を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

注意

基準タイムはミュージック タイムよりも正確であるため、基準タイムからミュージック タイムに変換し、また基準タイムに変換したタイムは、おそらく元の値とは異なる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::ReferenceToMusicTime、クロック タイムとミュージック タイム


IDirectMusicPerformance::PChannelInfo

IDirectMusicPerformance::PChannelInfo メソッドは、指定されたパフォーマンス チャンネルのポート、グループ、および MIDI チャンネルを取り出す。

HRESULT PChannelInfo(
  DWORD dwPChannel,
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

パラメータ

dwPChannel
情報が必要とされる P チャンネル。
ppPort
IDirectMusicPort ポインタを受け取る変数のアドレス。ポインタが不要な場合は、NULL でもよい。NULL 以外のポインタが返される場合、参照カウントはインクリメントされる。ポインタに対して Release を呼び出すのはアプリケーションである。「注意」も参照すること。
pdwGroup
ポート上のグループへのポインタを受け取る変数のアドレス。この値が不要な場合は、NULL でもよい。
pdwMChannel
グループ内の MIDI チャンネルへのポインタを受け取る変数のアドレス。この値が不要な場合は、NULL でもよい。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_POINTER

注意

IDirectMusicPerformance::RemovePort の呼び出しによってポートが削除された場合、*ppPort に NULL ポインタが返されるが、メソッドは成功する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::AssignPChannel、IDirectMusicPerformance::AssignPChannelBlock


IDirectMusicPerformance::PlaySegment

IDirectMusicPerformance::PlaySegment メソッドは、セグメントの再生を開始する。

HRESULT PlaySegment(
  IDirectMusicSegment* pSegment,
  DWORD dwFlags,
  __int64 i64StartTime,
  IDirectMusicSegmentState** ppSegmentState
);

パラメータ

pSegment
演奏されるセグメント。
dwFlags
メソッドの動作を変更するフラグ。DMUS_SEGF_FLAGS を参照すること。
i64StartTime
セグメントの演奏を開始するタイム。dwFlags で指定される任意の境界分解能に調整される。DMUS_SEGF_REFTIME フラグがセットされていない限り、タイムはミュージック タイムで表される。値が 0 の場合、セグメントの演奏はできる限り早く開始される。
ppSegmentState
演奏中のセグメントのインスタンスに関するセグメント状態へのポインタを受け取る変数のアドレス。このフィールドは NULL でもよい。NULL ではない場合、セグメント状態ポインタが返され、アプリケーションはこのポインタに対して Release を呼び出さなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_OUTOFMEMORY
E_POINTER
DMUS_E_NO_MASTER_CLOCK
DMUS_E_SEGMENT_INIT_FAILED
DMUS_E_TIME_PAST

注意

セグメントの長さは 250 ミリ秒 (ms) を超えているべきである。

dwFlags の境界分解能は、現在演奏されているプライマリ セグメントに関連するものである。

プライマリ セグメントの演奏が、別のプライマリ セグメントの演奏中にスケジュール設定されている場合、後に演奏されるセグメントに DMUS_SEGF_QUEUE フラグをセットしない限り、最初のセグメントは停止する。後に演奏されるセグメントに DMUS_SEGF_QUEUE フラグをセットした場合、そのセグメントは、最初のセグメントの演奏が終わると同時に演奏が開始される。

セグメントの正確な開始タイムの詳細については、「セグメントのタイミング」を参照すること。テンポの変更がセグメントの開始タイムに及ぼす影響については、「クロック タイムとミュージック タイム」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

セグメント


IDirectMusicPerformance::ReferenceToMusicTime

IDirectMusicPerformance::ReferenceToMusicTime メソッドは、REFERENCE_TIME フォーマットの時間を MUSIC_TIME フォーマットに変換する。

HRESULT ReferenceToMusicTime(
  REFERENCE_TIME rtTime,
  MUSIC_TIME* pmtTime
);

パラメータ

rtTime
REFERENCE_TIME フォーマットの時間。
pmtTime
MUSIC_TIME フォーマットに変換された時間を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

注意

パフォーマンスについてマスター テンポが設定されている場合は、ミュージック タイムに変換するときに考慮される。「グローバル パラメータの設定と取り出し」を参照すること。

ミュージック タイムは基準タイムほど正確ではないため、切り捨てが行われる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::MusicToReferenceTime、クロック タイムとミュージック タイム


IDirectMusicPerformance::RemoveNotificationType

IDirectMusicPerformance::RemoveNotificationType メソッドは、以前に通知された通知タイプをパフォーマンスから削除する。RemoveNotificationType メソッドを呼び出すと、すべてのセグメントとトラックは更新される。

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
削除される通知タイプの識別子への参照 (C++) またはアドレス (C) (定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること)。この値が GUID_NULL の場合、すべての通知が削除される。

戻り値

成功すれば S_OK または S_FALSE (「注意」を参照すること) を返す。

失敗すれば E_POINTER を返す。

注意

rguidNotificationType がアクティブな通知ではない場合、S_FALSE が返される。

演奏を停止したセグメントに通知を追加した場合、セグメントへの参照が失われることにより、パフォーマンスはそのセグメントから通知タイプを削除できなくなる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::AddNotificationType、IDirectMusicSegment::RemoveNotificationType、IDirectMusicTrack::RemoveNotificationType、通知とイベントの処理


IDirectMusicPerformance::RemovePort

IDirectMusicPerformance::RemovePort メソッドは、パフォーマンスからポートを削除する。このポートにマップされていたすべての P チャンネルは無効になり、そのスタンプの付いたメッセージが演奏されることもない。

HRESULT RemovePort(
  IDirectMusicPort* pPort
);

パラメータ

pPort
削除されるポート。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::AddPort


IDirectMusicPerformance::RhythmToTime

IDirectMusicPerformance::RhythmToTime メソッドは、リズム タイムをミュージック タイムに変換する。

HRESULT RhythmToTime(
  WORD wMeasure,
  BYTE bBeat,
  BYTE bGrid,
  short nOffset,
  DMUS_TIMESIGNATURE *pTimeSig,
  MUSIC_TIME *pmtTime)
);

パラメータ

wMeasure
変換されるタイムの小節。
bBeat
変換されるタイムの拍。
bGrid
変換されるタイムのグリッド。
nOffset
変換されるタイムのグリッドからのオフセット。ミュージック タイムのティックで表す。
pTimeSig
拍子記号に関する情報を含む DMUS_TIMESIGNATURE 構造体のアドレス。
pmtTime
ミュージック タイムを受け取る変数のアドレス。

戻り値

成功すれば S_OK。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::TimeToRhythm


IDirectMusicPerformance::SendPMsg

IDirectMusicPerformance::SendPMsg メソッドは、パフォーマンス メッセージを送信する。このメソッドは、トラックの演奏時に呼び出される。ツールによって呼び出され、新しいデータをパフォーマンスに挿入する場合もある。

HRESULT SendPMsg(
  DMUS_PMSG* pPMSG
);

パラメータ

pPMSG
IDirectMusicPerformance::AllocPMsg によって割り当てられるメッセージ。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
E_INVALIDARG
E_POINTER

注意

タイム スタンプが rtTime と mtTime のどちらになっているかに応じて、dwFlags メンバ (「DMUS_PMSG」を参照) は DMUS_PMSGF_MUSICTIME と DMUS_PMSGF_REFTIME のどちらかを含んでいなければならない。また、メッセージのタイプに応じて、dwFlags は DMUS_PMSGF_TOOL_QUEUE、DMUS_PMSGF_TOOL_ATTIME、または DMUS_PMSGF_TOOL_IMMEDIATE いずれかの適切な配信タイプを含んでいなければならない。どれも指定しない場合、デフォルトとして DMUS_PMSGF_TOOL_IMMEDIATE が使われる。

メッセージのタイムが 0 に設定され、dwFlags メンバが DMUS_PMSGF_REFTIME を含んでいる場合、このメッセージは即座に送り出すものとしてキューに挿入される。

ほとんどの場合は、SendPMsg を呼び出す前に IDirectMusicGraph::StampPMsg メソッドをメッセージに対して呼び出すべきである。ただし、メッセージをメインの出力ツールへ直接送信する場合は、このステップを省略してもよい。メッセージをパフォーマンス グラフだけに渡したい場合は、IDirectMusicPerformance::QueryInterface を呼び出すことによって、IDirectMusicGraph インターフェイスを取得する。それ以外の場合は、IDirectMusicSegment::QueryInterface を呼び出すことによって、このインターフェイスを取得する。IDirectMusicPerformance::GetGraph または IDirectMusicSegment::GetGraph を呼び出してこのインターフェイスを取得しようとしないこと。これらのメソッドは、グラフ オブジェクトへのポインタを返すものであり、パフォーマンスまたはセグメントに対する IDirectMusicGraph インターフェイスの実装へのポインタは返さない。

パフォーマンスは通常、処理の終わったメッセージを解放する。詳細については、「IDirectMusicPerformance::FreePMsg」の「注意」を参照すること。

次のサンプル コードは、システム エクスクルーシブ メッセージとテンポ メッセージの割り当て方法と送信方法を示す。

/* pPerformance は有効な IDirectMusicPerformance ポインタであり、
mtTime は初期化済みの MUSIC_TIME 変数であると仮定する。*/

IDirectMusicGraph* pGraph;

/* グラフ ポインタをパフォーマンスから取得する。
メッセージをセグメント
   グラフに渡したい場合は、代わりにセグメント オブジェクトに対して
   QueryInterface を呼び出す。*/

if ( SUCCEEDED( pPerformance->QueryInterface(
        IID_IDirectMusicGraph, (void**)&pGraph )))
{
// 適切なサイズの DMUS_SYSEX_PMSG を割り当て、
// システムエクスクルーシブ データをそれに読み込ませる。

    DMUS_SYSEX_PMSG* pSysEx;

    if ( SUCCEEDED( pPerformance->AllocPMsg(
            sizeof(DMUS_SYSEX_PMSG) + m_dwSysExLength,
            (DMUS_PMSG**)&pSysEx )))
    {
// すべてのフィールドは、AllocPMsgAll メソッドから
// 0 に初期化される。
// m_pbSysExData は、長さが m_dwSysExLength のデータを含む
// 配列へのポインタであると仮定する。

        memcpy( pSysEx->abData, m_pbSysExData, m_dwSysExLength );
        pSysEx->dwSize = sizeof(DMUS_SYSEX_PMSG);
        pSysEx->dwLen = dwSysExLength;
        pSysEx->mtTime = mtTime;
        pSysEx->dwFlags = DMUS_PMSGF_MUSICTIME;
        pSysEx->dwType = DMUS_PMSGT_SYSEX;

        pGraph->StampPMsg( (DMUS_PMSG*)pSysEx );
        if (FAILED(pPerformance->SendPMsg( (DMUS_PMSG*)pSysEx )))
        {
            pPerformance->FreePMsg( (DMUS_PMSG*)pSysEx );
        }
    }

// タイム mtTime のテンポを 120 bpm に変更する。

    DMUS_TEMPO_PMSG* pTempo;

    if( SUCCEEDED( pPerformance->AllocPMsg(
            sizeof(DMUS_TEMPO_PMSG),
            (DMUS_PMSG**)&pTempo )))
    {
        pTempo->dwSize = sizeof(DMUS_TEMPO_PMSG);
        pTempo->dblTempo = 120;
        pTempo->mtTime = mtTime;
        pTempo->dwFlags = DMUS_PMSGF_MUSICTIME;
        pTempo->dwType = DMUS_PMSGT_TEMPO;
        pGraph->StampPMsg( (DMUS_PMSG*)pTempo );
        if (FAILED(pPerformance->SendPMsg( (DMUS_PMSG*)pTempo )))
        {
            pPerformance->FreePMsg( (DMUS_PMSG*)pTempo );
        }
    }

    pGraph->Release();
}

次のサンプル コードは、dwTrackID によって識別されるトラックに関連付けられた音符メッセージを送信する関数を示す。メッセージが DirectMusicTrack オブジェクトから生成されていない場合、仮想トラック ID は 0 でなければならない。

HRESULT CreateNotePMsg(IDirectMusicPerformance* pPerformance,
MUSIC_TIME mtTime, DWORD dwTrackID)
{

// Note PMessage を割り当てる。
DMUS_NOTE_PMSG* pNote = NULL;
HRESULT hr = pPerformance->AllocPMsg( sizeof(DMUS_NOTE_PMSG),
(DMUS_PMSG**) &pNote);
if (FAILED(hr)) return hr;

pNote->dwSize = sizeof(DMUS_NOTE_PMSG); // Note PMessage のサイズ
pNote->rtTime = 0;                      // 無視される。
pNote->mtTime = mtTime;                 // 音符の演奏タイム。
pNote->dwFlags = DMUS_PMSGF_MUSICTIME;  // mtTime フィールドを使う。
pNote->dwPChannel = 5;                  // PChannel 5 で演奏する。
pNote->dwVirtualTrackID = dwTrackID;    // パラメータからのトラック ID。

// 次の 2 つのフィールドは、メッセージを初めて送信するときに、
// NULL に設定しなければならない。これらのフィールドは、
// IDirectMusicGraph::StampPMsg で更新される。
pNote->pTool = NULL;
pNote->pGraph = NULL;
pNote->dwType = DMUS_PMSGT_NOTE;
pNote->dwVoiceID = 0;           // DirectX 6.1 の場合は常に 0。
pNote->dwGroupID = 0xFFFFFFFF;  // すべてのトラック グループ。
pNote->punkUser = NULL;         // 常に NULL。

// 現在の拍子記号をパフォーマンスから取得し、
// 小節と拍の情報を計算する。
DMUS_TIMESIGNATURE TimeSig;
MUSIC_TIME mtNext;
hr = pPerformance->GetParam(GUID_TimeSignature, 0xFFFFFFFF,
0, mtTime, &mtNext, &TimeSig);
if (FAILED(hr)) return hr;

// TimeSig.mtTime を再計算し、
// pPerformance->TimeToRhythm が予期する値を取得する。
TimeSig.mtTime += mtTime;

// 現在のコードをパフォーマンスから取得し、
// 音符の値を作成する。
DMUS_CHORD_KEY Chord;
hr = pPerformance->GetParam(GUID_ChordParam, 0xFFFFFFFF, 0,
mtTime, &mtNext, &Chord);
if (FAILED(hr)) return hr;

// オクターブ 5、コード音 2 (5 度)、スケールを持つ音符を作成する。
// オフセット 1 (=> 6 度)、変化音なし。
WORD wMusicValue = 0x5210;

// DMUS_PLAYMODE_PEDALPOINT を
// pPerformance->MusicToMIDI での演奏モードとして使う。
BYTE bPlayModeFlags = DMUS_PLAYMODE_PEDALPOINT;

// DMUS_NOTE_PMSG に固有なフィールドを入力する。
pNote->wMusicValue = wMusicValue;
hr = pPerformance->MusicToMIDI(
wMusicValue,
&Chord,
bPlayModeFlags,
        0,
&(pNote->bMidiValue));
if (FAILED(hr)) return hr;

hr = pPerformance->TimeToRhythm(
TimeSig.mtTime,
&TimeSig,
&(pNote->wMeasure),
&(pNote->bBeat),
&(pNote->bGrid),
&(pNote->nOffset));
if (FAILED(hr)) return hr;

pNote->mtDuration = DMUS_PPQ;       // 4 分音符の持続時間。
pNote->bVelocity = 120;             // MIDI のベロシティ (0 ～ 127)。
pNote->bFlags = DMUS_NOTEF_NOTEON;  // 常にこの値に設定する。
pNote->bTimeRange = 250;            // 開始タイムを大幅にランダム化する。
pNote->bDurRange = 5;               // 持続時間をわずかにランダム化する。
pNote->bVelRange = 0;               // ベロシティはランダム化しない。
pNote->bPlayModeFlags = bPlayModeFlags;
pNote->bSubChordLevel = 0;          // 音符はサブコード レベル 0 を使う。
pNote->cTranspose = 0;              // 転調はない。

// メッセージにパフォーマンス グラフのスタンプを付ける。
IDirectMusicGraph*  pGraph;
hr = pPerformance->QueryInterface( IID_IDirectMusicGraph,
(void**)&pGraph );
if (FAILED(hr)) return hr;

pGraph->StampPMsg( (DMUS_PMSG*)pNote );
pGraph->Release();

// 最後にメッセージを送信する。
hr = pPerformance->SendPMsg( (DMUS_PMSG*)pNote);
if (FAILED(hr))
    {
pPerformance->FreePMsg( (DMUS_PMSG*)pNote);
return hr;
    }

return S_OK;

}

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicTool::ProcessPMsg、メッセージ、DirectMusic メッセージ、DirectMusic ツール


IDirectMusicPerformance::SetBumperLength

IDirectMusicPerformance::SetBumperLength メソッドは、レンダリングの目的でメッセージをポートに送信する場合に、ポートの遅延時間より前に置かれる緩衝時間 (バンパー時間) を設定する。この項目の詳細については、「タイミング」を参照すること。

HRESULT SetBumperLength(
  DWORD dwMilliSeconds
);

パラメータ

dwMilliSeconds
演奏前の時間の長さ。単位はミリ秒 (ms)、デフォルト値は 50 である。

戻り値

S_OK を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::GetBumperLength、IDirectMusicPerformance::SetPrepareTime


IDirectMusicPerformance::SetGlobalParam

IDirectMusicPerformance::SetGlobalParam メソッドは、パフォーマンスのグローバル値を設定する。

HRESULT SetGlobalParam(
  REFGUID rguidType,
  void* pParam,
  DWORD dwSize
);

パラメータ

rguidType
データ タイプの識別子への参照 (C++) またはアドレス (C)。
pParam
パフォーマンスへのコピーと保存が行われるデータへのポインタ。
dwSize
データのサイズ。rguidTypeごとに一定の値である。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_POINTER
E_OUTOFMEMORY

注意

パフォーマンスはすべてのデータ タイプを把握しているわけではないので、dwSize パラメータは必要である。必要に応じて、新しいタイプも作成できる。

DirectMusic によって定義されるパラメータおよびそれらに関連のあるデータ タイプについては、「グローバル パラメータの設定と取り出し」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::GetGlobalParam、IDirectMusicPerformance::SetParam、ミュージック パラメータ


IDirectMusicPerformance::SetGraph

IDirectMusicPerformance::SetGraph メソッドは、パフォーマンスのツール グラフを置き換える。

HRESULT SetGraph(
  IDirectMusicGraph* pGraph
);

パラメータ

pGraph
設定されるツール グラフ。パフォーマンスからグラフを消去するために、NULL にも設定できる。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

現在のツール グラフ内で処理中のすべてのメッセージは削除される。

このメソッドはグラフの参照カウントをインクリメントするので、オリジナルの参照を解放しておくと安全である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetGraph、IDirectMusicPerformance::GetGraph、IDirectMusicPerformance::SendPMsg


IDirectMusicPerformance::SetNotificationHandle

IDirectMusicPerformance::SetNotificationHandle メソッドは、通知用のイベント ハンドル (Microsoft® Win32® の CreateEvent 関数によって作成される) を設定する。アプリケーションは、このハンドルに対して Win32 WaitForSingleObject 関数を適用すべきである。シグナルが送信されたときに、アプリケーションは IDirectMusicPerformance::GetNotificationPMsg メソッドを呼び出して、通知イベントを取り出すべきである。

HRESULT SetNotificationHandle(
  HANDLE hNotification,
  REFERENCE_TIME rtMinimum
);

パラメータ

hNotification
CreateEvent によって作成されたイベント ハンドル。既存のハンドルを消去する場合は、0 を指定する。
rtMinimum
パフォーマンスが古い通知イベントを破棄するまでに保持しておく最小の時間。値として 0 を指定すると、デフォルトの最小値である 20,000,000 基準タイム単位 (2 秒)、または以前にこのメソッドを呼び出したときの値を意味する。アプリケーションがまだ GetNotificationPMsg を呼び出していない場合は、このイベントは破棄されて、メモリが解放される。

戻り値

S_OK を返す。

注意

通知ハンドルが不要になったときには、アプリケーションが通知ハンドルに対して Win32 CloseHandle 関数を呼び出さなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理


IDirectMusicPerformance::SetParam

IDirectMusicPerformance::SetParam メソッドは、制御セグメント内のトラック上にデータを設定する。

HRESULT SetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  void* pParam
);

パラメータ

rguidType
設定されるデータ タイプの識別子への参照 (C++) またはアドレス (C)。「トラック パラメータのタイプ」を参照すること。
dwGroupBits
希望のトラックが置かれるグループ。
dwIndex
データの設定に使われる、dwGroupBits で識別されたグループ内で、トラックに割り当てられているインデックス。
mtTime
データの設定を行うタイム。IDirectMusicSegment::SetParam とは異なり、このメソッドではパフォーマンス タイムを使ってこのタイムを表す。このタイムからセグメントの開始タイムを引き、その結果を IDirectMusicSegment::GetParam に渡す。
pParam
データを保持する構造体のアドレス。この構造体は、rguidType で識別されたデータ タイプにとって適切な種類とサイズを備えていなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。DMUS_SEGF_FLAGS を参照すること。

dwGroupBits と dwIndex の説明については、「トラックの識別」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetGlobalParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::SetParam、IDirectMusicPerformance::GetTime、ミュージック パラメータ


IDirectMusicPerformance::SetPrepareTime

IDirectMusicPerformance::SetPrepareTime メソッドは、IDirectMusicTrack::Play メソッドを呼び出してから、スピーカを通してメッセージが実際に聞かれるまでの時間を設定する。

HRESULT SetPrepareTime(
  DWORD dwMilliSeconds
);

パラメータ

dwMilliSeconds
準備時間の長さ。単位はミリ秒 (ms)、デフォルト値は 1,000 である。

戻り値

S_OK を返す。

注意

詳細については、「タイミング」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::GetPrepareTime、IDirectMusicPerformance::SetBumperLength


IDirectMusicPerformance::Stop

IDirectMusicPerformance::Stop メソッドは、1 つまたは複数のセグメントの再生を停止する。

HRESULT Stop(
  IDirectMusicSegment* pSegment,
  IDirectMusicSegmentState* pSegmentState,
  MUSIC_TIME mtTime,
  DWORD dwFlags
);

パラメータ

pSegment
演奏を停止するセグメント。このセグメントに基づくすべてのセグメント状態は、mtTime の時点で停止される。「注意」を参照すること。
pSegmentState
演奏を停止するセグメント状態。「注意」を参照すること。
mtTime
セグメント、セグメント状態、またはその両方を停止するタイム。このタイムが過去のタイムである場合や、値として 0 を指定した場合は、要求したセグメントとセグメント状態の演奏が即座に停止される。
dwFlags
演奏の停止タイムを指定するフラグ。境界は現在のプライマリ セグメントに関連する。次の値のいずれかを使わなければならない。
0
即座に停止する。
DMUS_SEGF_GRID
次のグリッド境界または mtTime の後に停止する。
DMUS_SEGF_MEASURE
次の小節境界または mtTime の後に停止する。
DMUS_SEGF_BEAT
次の拍境界または mtTime の後に停止する。
DMUS_SEGF_DEFAULT
IDirectMusicSegment::SetDefaultResolution メソッドで設定されたデフォルト境界で停止する。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

pSegment と pSegmentState の両方が NULL である場合、すべての音楽は停止し、現在キューに置かれているすべてのセグメントが解放される。pSegment と pSegmentState のどちらかが NULL ではない場合、指定されたセグメント状態がパフォーマンスから削除される。両方共 NULL ではなく、なおかつ DMUS_SEGF_DEFAULT が使われている場合、pSegment から得られたデフォルトの分解能を使う。

すべてのパラメータに NULL または 0 を設定すると、すべての演奏が即座に停止し、コントローラ リセット メッセージおよびノートオフ メッセージが、マップされたすべての P チャンネルに送信される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::PlaySegment、DMUS_SEGF_FLAGS


IDirectMusicPerformance::TimeToRhythm

IDirectMusicPerformance::TimeToRhythm メソッドは、ミュージック タイムをリズム タイムに変換する。

HRESULT TimeToRhythm(
  MUSIC_TIME mtTime,
  DMUS_TIMESIGNATURE *pTimeSig,
  WORD *pwMeasure,
  BYTE *pbBeat,
  BYTE *pbGrid,
  short *pnOffset
);

パラメータ

mtTime
変換されるタイム。
pTimeSig
拍子記号に関する情報を含む DMUS_TIMESIGNATURE 構造体のアドレス。
pwMeasure
タイムが属する小節を受け取る変数のアドレス。
pbBeat
タイムが属する拍を受け取る変数のアドレス。
pbGrid
タイムが属するグリッドを受け取る変数のアドレス。
pnOffset
タイムが属するグリッド (ミュージック タイムのティックで表す) からのオフセットを受け取る変数のアドレス。

戻り値

成功すれば S_OK。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::RhythmToTime


IDirectMusicPort

IDirectMusicPort インターフェイスは、DirectMusicPort オブジェクトへのアクセスを提供する。DirectMusicPort オブジェクトは、ミュージック データを送信または受信するデバイスを表す。MPU-401 の入力ポート、MPU-401 の出力ポート、Microsoft Software Synthesizer、IHV が提供するフィルタは、いずれもポートである。MPU-401 などの物理的なデバイスは、複数のポートを提供できる。ただし、単一のポートでは、データのキャプチャとレンダリングはできない。

概要については、「ポートの使い方」を参照すること。

IDirectMusicPort インターフェイスのメソッドは、以下のグループにまとめることができる。

バッファ | PlayBuffer
 | Read
 | SetReadNotificationHandle
チャンネル | GetChannelPriority
 | GetNumChannelGroups
 | SetChannelPriority
 | SetNumChannelGroups
デバイス管理 | Activate
 | DeviceIoControl
 | SetDirectSound
情報 | GetCaps
 | GetFormat
 | GetLatencyClock
 | GetRunningStats
ダウンローダブル サウンド | Compact
 | DownloadInstrument
 | UnloadInstrument

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICPORT 型は、IDirectMusicPort インターフェイスへのポインタとして定義されている。

typedef IDirectMusicPort *LPDIRECTMUSICPORT;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicSynth::Activate

Platform SDK: DirectX

IDirectMusicPort::Activate

IDirectMusicPort::Activate メソッドは、ポートをアクティブ化または非アクティブ化する。

HRESULT Activate(
  BOOL fActive
);

パラメータ

fActive
ポートをアクティブ化 (TRUE) または非アクティブ化 (FALSE) に切り替える。

戻り値

成功すれば S_OK を返す。

失敗すれば DSERR_NODRIVER を返し、サウンド ドライバがないことを示す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic::Activate、ポートの使い方


IDirectMusicPort::Compact

IDirectMusicPort::Compact メソッドを使って、DLS またはウェーブテーブルのメモリをコンパクト化するようポートに指示する。この結果、ダウンロードされる新しい音色が、最大限の連続したメモリ チャンクを利用できる。

HRESULT Compact();

パラメータ

なし。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

注意

このメソッドは、独自のウェーブテーブル メモリを管理する必要のある DLS デバイスにだけ影響する。独自のメモリを管理しないポート (ホスト システムのメモリを利用するソフトウェア シンセサイザやハードウェア シンセサイザ) に対し、このメソッドは E_NOTIMPL を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicPort::DeviceIoControl

IDirectMusicPort::DeviceIoControl メソッドは、ポートを実装する根底のファイルに対して Win32 の DeviceIoControl 関数を呼び出す。

HRESULT DeviceIoControl(
  DWORD dwIoControlCode,
  LPVOID lpInBuffer,
  DWORD nInBufferSize,
  LPVOID lpOutBuffer,
  DWORD nOutBufferSize,
  LPDWORD lpBytesReturned,
  LPOVERLAPPED lpOverlapped
);

パラメータ

dwIoControlCode
実行される制御コード。
lpInBuffer
入力データを含むバッファへのポインタ。
nInBufferSize
入力バッファのサイズ。
lpOutBuffer
出力データを受け取るバッファへのポインタ。
nOutBufferSize
出力バッファのサイズ。
lpBytesReturned
出力バイト数を受け取る変数のアドレス。
lpOverlapped
非同期動作用の重なった (オーバーラップ) 構造体のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_NOTIMPL

注意

Windows ドライバモデル (WDM) フィルタグラフを実装しているポートでのみ、このメソッドはサポートされている。WDM フィルタ グラフを使っている場合、ファイル ハンドルはグラフ内の最上位のピンとして利用される。

DirectMusic がフィルタ グラフに対して実行している操作と、ピンに対して定義されたカーネル ストリーミングが衝突する可能性がある場合、DirectMusic はカーネル ストリーミングの実行を拒否できる。ただし、ユーザー定義の操作は決して妨害されない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicPort::DownloadInstrument

IDirectMusicPort::DownloadInstrument メソッドは、DLS デバイスに楽器をダウンロードするために使われる。音色をダウンロードすることは、音色を構成するデータを DLS デバイスに渡すことを意味する。この中には、楽器が必要とするアーティキュレーションデータとすべてのウェーブが含まれる。ウェーブのスペースを節約するために、その範囲で必要とされるウェーブとアーティキュレーションだけがダウンロードされる。このメソッドは IDirectMusicDownloadedInstrument インターフェイスポインタを返すが、これは後で楽器をアンロードするために使われる。

HRESULT DownloadInstrument(
  IDirectMusicInstrument *pInstrument,
  IDirectMusicDownloadedInstrument **ppDownloadedInstrument,
  DMUS_NOTERANGE *pNoteRanges,
  DWORD dwNumNoteRanges;
  );

パラメータ

pInstrument
メソッドによるデータのダウンロード元となる音色。
ppDownloadedInstrument
IDirectMusicDownloadedInstrument インターフェイスへのポインタを受け取る変数のアドレス。
pNoteRanges
DMUS_NOTERANGE 構造体の配列のアドレス。配列内の各エントリは、楽器が応答しなければならない MIDI 音符メッセージの連続範囲を指定する。音色のリージョンがダウンロードされるのは、そのリージョン内の少なくとも 1 つの音符が DMUS_NOTERANGE 構造体で指定されている場合に限られる。
dwNumNoteRanges
pNoteRanges が指す配列内の DMUS_NOTERANGE 構造体の数。この値が 0 に設定されている場合、pNoteRanges パラメータは無視され、この音色のすべてのリージョンとウェーブ データがダウンロードされる。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_OUTOFMEMORY
E_NOTIMPL

注意

メモリの浪費を防ぐには、音色が不要になったときに、IDirectMusicPort::UnloadInstrument と IDirectMusicDownloadedInstrument::Release の両方を呼び出して、アンロードしなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::Compact、音色の操作


IDirectMusicPort::GetCaps

IDirectMusicPort::GetCaps メソッドは、ポートの能力を取り出す。

HRESULT GetCaps(
  LPDMUS_PORTCAPS pPortCaps
);

パラメータ

pPortCaps
ポートの能力を受け取る DMUS_PORTCAPS 構造体のアドレス。このメソッドを呼び出す前に、この構造体の dwSize メンバを正しく初期化しなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_INVALIDARG

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicPort::GetChannelPriority

IDirectMusicPort::GetChannelPriority メソッドは、MIDI チャンネルの優先順位を取り出すために使われる。概要については、「チャンネル」を参照すること。

HRESULT GetChannelPriority(
  DWORD   dwChannelGroup,
  DWORD   dwChannel,
  LPDWORD pdwPriority
);

パラメータ

dwChannelGroup
チャンネルが置かれているグループ。
dwChannel
グループ内のチャンネルのインデックス。
pdwPriority
優先順位を受け取る変数のアドレス。「注意」を参照すること。

戻り値

成功すれば S_OK。

注意

Dmusicc.h 内で定義されている以下の値は、それぞれ優先順位の範囲を表す。優先順位の高いものから順にリストする。

DAUD_CRITICAL_VOICE_PRIORITY
DAUD_HIGH_VOICE_PRIORITY
DAUD_STANDARD_VOICE_PRIORITY
DAUD_LOW_VOICE_PRIORITY

以下の値は、DLS レベル 1 標準による、範囲内におけるチャンネルのデフォルト順位を表す。優先順位の高いものから順にリストする。パーカッション チャンネルのチャンネル 10 が、最も優先順位が高い。

DAUD_CHAN10_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN1_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN2_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN3_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN4_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN5_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN6_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN7_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN8_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN9_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN11_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN12_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN13_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN14_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN15_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN16_DEF_VOICE_PRIORITY_OFFSET

チャンネルの優先順位は、範囲とオフセットを使って表す。たとえば、DAUD_STANDARD_VOICE_PRIORITY と DAUD_CHAN10_DEF_VOICE_PRIORITY で、標準範囲内で最も高い優先順位を表す。

同じ優先順位値を持つチャンネルは、所属するチャンネル グループの種類に関係なく、同じ優先順位を持つ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::SetChannelPriority


IDirectMusicPort::GetFormat

IDirectMusicPort::GetFormat メソッドは、IDirectMusic::CreatePort に渡す DMUS_PORTPARAMS 構造体で指定されるウェーブ フォーマットに関する情報、およびウェーブ出力で使うバッファの推奨サイズに関する情報を取り出す。これらの情報を使って、ポート用に互換性のある IDirectSoundBuffer を作成できる。

HRESULT GetFormat(
  LPWAVEFORMATEX pWaveFormatEx,
  LPDWORD pdwWaveFormatExSize
  LPDWORD pdwBufferSize
);

パラメータ

pWaveFormatEx
フォーマットに関する情報を受け取る WAVEFORMATEX 構造体のアドレス。この値は NULL でもよい。「注意」を参照すること。
pdwWaveFormatExSize
構造体のサイズを含む、またはそれを受け取る変数のアドレス。「注意」を参照すること。
pdwBufferSize
DirectSound バッファの推奨サイズを受け取る変数のアドレス。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

WAVEFORMATEX 構造体は、フォーマットの詳細に応じて可変長にもなる。フォーマットの記述を取り出す前に、アプリケーションは、このメソッドを呼び出し、pWaveFormatEx パラメータに NULL を指定することによって、シンセサイザ オブジェクトに対してフォーマットのサイズに関する問い合わせを行わなければならない。構造体のサイズは、pdwWaveFormatExSize が指す変数に返される。次にアプリケーションは、十分なメモリを割り当て、GetFormat を再度呼び出して、フォーマットの記述を取り出すことができる。

pWaveFormatEx が NULL でない場合、DirectMusic は、できるだけ多くの pdwWaveFormatExSize バイトを構造体に書き込む。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::SetDirectSound


IDirectMusicPort::GetLatencyClock

IDirectMusicPort::GetLatencyClock メソッドは、ポートの遅延時間クロックへの IReferenceClock インターフェイス ポインタを取得するために使われる。この遅延時間クロックは、メッセージを演奏できる、現在に最も近い将来のタイムを指定する。遅延時間クロックは、IDirectMusic::SetMasterClock メソッドによって設定される DirectMusic マスタ クロックに基づいている。

HRESULT GetLatencyClock(
  IReferenceClock** ppClock
);

パラメータ

ppClock
遅延時間クロックの IReferenceClock インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

COM の規則に従って、GetLatencyClock は返されたインターフェイスの参照カウントを増やす。そのため、アプリケーションは何らかの時点で IReferenceClock インターフェイスに対して Release を呼び出さなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

遅延時間とバンパー時間


IDirectMusicPort::GetNumChannelGroups

IDirectMusicPort::GetNumChannelGroups メソッドは、ポート上のチャンネル グループの数を取り出す。

HRESULT GetNumChannelGroups
  LPDWORD pdwChannelGroups
);

パラメータ

pdwChannelGroups
チャンネル グループの数を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::SetNumChannelGroups、チャンネル


IDirectMusicPort::GetRunningStats

IDirectMusicPort::GetRunningStats メソッドは、ポートのシンセサイザの状態に関する状態を取り出す。

HRESULT GetRunningStats(
  LPDMUS_SYNTHSTATS pStats
);

パラメータ

pStats
シンセサイザの動作統計を受け取る DMUS_SYNTHSTATS 構造体のアドレス。このメソッドを呼び出す前に、この構造体の dwSize メンバを正しく初期化しなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_INVALIDARG
E_NOTIMPL

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicPort::PlayBuffer

IDirectMusicPort::PlayBuffer メソッドは、各ポートの再生バッファへの挿入を行う。

HRESULT PlayBuffer(
  IDIRECTMUSICBUFFER* pBuffer
);

パラメータ

pBuffer
ポートの再生キューに追加される DirectMusicBuffer オブジェクトのアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

注意

このバッファがシステムによって使われるのはこのメソッドの持続中だけであり、このメソッドから制御が戻った後は再利用できる。

IDirectMusicBuffer::SetStartTime メソッドによって開始タイムが設定されていない場合、IDirectMusicBuffer::PackStructured または IDirectMusicBuffer::PackUnstructured の各メソッドによって設定される、バッファ内の最も早いイベントのタイムが開始タイムになる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer、IDirectMusic::CreateMusicBuffer


IDirectMusicPort::Read

IDirectMusicPort::Read メソッドは、受信した MIDI データをバッファに入力する。読み込みに利用できるデータがなくなるまで、新しいバッファ オブジェクトに対してこのメソッドを呼び出すべきである。

HRESULT Read(
  IDirectMusicBuffer *pBuffer
);

パラメータ

pBuffer
受信 MIDI データの入力先の DirectMusicBuffer オブジェクトのアドレス。

戻り値

成功すれば S_OK または S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_NOTIMPL

注意

読み込むデータが存在しない場合、このメソッドは S_FALSE を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

音楽のキャプチャ


IDirectMusicPort::SetChannelPriority

IDirectMusicPort::SetChannelPriority メソッドは、MIDI チャンネルの優先順位を設定するために使われる。詳細については、「チャンネル」を参照すること。

HRESULT SetChannelPriority(
  DWORD  dwChannelGroup,
  DWORD  dwChannel,
  DWORD  dwPriority
);

パラメータ

dwChannelGroup
チャンネルが置かれているグループ。この値は 1 以上でなければならない。
dwChannel
グループ内のチャンネルのインデックス。
dwPriority
優先順位。「IDirectMusicPort::GetChannelPriority」の「注意」を参照すること。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_NOTIMPL

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::GetChannelPriority、DMUS_CHANNEL_PRIORITY_PMSG


IDirectMusicPort::SetDirectSound

IDirectMusicPort::SetDirectSound メソッドは、ポートのウェーブ データがストリーム化されるデフォルトの DirectSound オブジェクトまたはバッファ、あるいはその両方を上書きするために使われる。また、DirectSound からポートを接続解除する際にも使われる。

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  LPDIRECTSOUNDBUFFER pDirectSoundBuffer
);

パラメータ

pDirectSound
ポートの接続先となる DirectSound オブジェクトの IDirectSound インターフェイスのアドレス。既存の DirectSound オブジェクトを接続解除し、解放する場合は NULL を指定する。
pDirectSoundBuffer
ポートの接続先となる IDirectSoundBuffer インターフェイスのアドレス。この値は NULL でもよい。

戻り値

成功すれば S_OK または DMUS_S_NOBUFFERCONTROL を返す。「注意」を参照すること。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_ALREADY_ACTIVATED
E_INVALIDARG

注意

有効なポインタが pDirectSoundBuffer に渡されると、パンやボリュームなどのバッファ内でのコントロール チェンジが DirectMusic の再生に影響しない場合、このメソッドは DMUS_S_NOBUFFERCONTROL を返す。これは、WDM だけに影響する。

ポートをアクティブ化すると、必要に応じて DirectSound プライマリ バッファがアップグレードされ、このポート (IDirectMusic::CreatePort に渡される DMUS_PORTPARAMS 構造体で指定する) のサンプリング レートとチャンネル情報をサポートする。

pDirectSoundBuffer が指すバッファは、このポートのサンプリング レートとチャンネル情報に一致するフォーマットを持つ、セカンダリ ストリーミング バッファでなければならない。このパラメータが NULL の場合、適切な IDirectSoundBuffer インスタンスが内部的に作成される。

ポートをいったんアクティブ化したら、IDirectSound も IDirectSoundBuffer も変更できない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::Activate、IDirectMusicPort::GetFormat、DirectMusic と DirectSound の統合


IDirectMusicPort::SetNumChannelGroups

IDirectMusicPort::SetNumChannelGroups メソッドは、アプリケーションがポート上で必要とするチャンネル グループの数を変更する。

HRESULT SetNumChannelGroups(
  DWORD dwChannelGroups
);

パラメータ

dwChannelGroups
アプリケーションがこのポートに割り当てたいチャンネル グループの数。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::GetNumChannelGroups、チャンネル


IDirectMusicPort::SetReadNotificationHandle

IDirectMusicPort::SetReadNotificationHandle メソッドは、IDirectMusicPort::Read メソッドを使って MIDI メッセージが読み込めるようになったときに設定されるイベントを指定する。新しいデータが利用可能になると、必ずイベントのシグナルが送信される。イベント通知を無効にするには、hEvent パラメータの値として NULL を指定し、SetReadNotificationHandle を呼び出す。

HRESULT SetReadNotificationHandle(
  HANDLE hEvent
);

パラメータ

hEvent
Win32 CreateEvent 関数を呼び出したときに取得したイベント ハンドル。ポートが解放されたら、アプリケーションがこのハンドルを閉じなければならない。

戻り値

S_OK を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

音楽のキャプチャ


IDirectMusicPort::UnloadInstrument

IDirectMusicPort::UnloadInstrument メソッドは、以前にダウンロードした DLS 音色をアンロードするために使われる。

HRESULT UnloadInstrument(
  IDirectMusicDownloadedInstrument *pDownloadedInstrument
);

パラメータ

pDownloadedInstrument
IDirectMusicPort::DownloadInstrument メソッドを呼び出して音色をダウンロードしたときに取得した、IDirectMusicDownloadedInstrument インターフェイスのアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_DOWNLOADED_TO_PORT
E_POINTER
E_NOTIMPL

注意

IDirectMusicPort::DownloadInstrument によって割り当てられたメモリを解放するには、このメソッドを呼び出さなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

音色の操作


IDirectMusicPortDownload

IDirectMusicPortDownload インターフェイスを使うと、アプリケーションは DLS ダウンロードをサポートしているポートと直接通信し、メモリ チャンクをポートに直接ダウンロードできる。このインターフェイスが主に使われるのは、DLS 音色を直接編集するアプリケーションをオーサリングするときである。概要については「下位レベル DLS」を参照すること。

IDirectMusicPortDownload を取得するには、IDirectMusicPort::QueryInterface メソッドを呼び出し、IID_IDirectMusicPortDownload をインターフェイス GUID として渡す。ポートが DLS ダウンロードをサポートしていない場合、このメソッドは失敗する。

IDirectMusicPortDownload インターフェイスのメソッドは、以下のグループにまとめることができる。

バッファ管理 | AllocateBuffer
 | GetAppend
 | GetBuffer
 | GetDLId
ロード | Download
 | Unload

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicPortDownload::AllocateBuffer

IDirectMusicPortDownload::AllocateBuffer メソッドは、DLS データをポートへダウンロードするためのメモリ チャンクを割り当て、このバッファへのアクセスを可能にする IDirectMusicDownload インターフェイス ポインタを返す。

HRESULT AllocateBuffer(
  DWORD dwSize,
  IDirectMusicDownload** ppIDMDownload
);

パラメータ

dwSize
要求するバッファのサイズ。
ppIDMDownload
IDirectMusicDownload インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_INVALIDARG
E_OUTOFMEMORY

注意

いったんバッファを割り当てたら、そのサイズは変更できない。

IDirectMusicDownload インターフェイスを解放すると、バッファも解放される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPortDownload::GetBuffer、下位レベル DLS


IDirectMusicPortDownload::Download

IDirectMusicPortDownload::Download メソッドは、ウェーブまたは楽器の定義をポートにダウンロードする。最初に IDirectMusicPortDownload::AllocateBuffer メソッドを使って、メモリを割り当てなければならない。

HRESULT Download(
  IDirectMusicDownload* pIDMDownload
);

パラメータ

pIDMDownload
バッファ用の IDirectMusicDownload インターフェイスのアドレス。

戻り値

戻り値はポートの実装によって決まる。

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_FAIL
DMUS_E_ALREADY_DOWNLOADED
DMUS_E_BADARTICULATION
DMUS_E_BADINSTRUMENT
DMUS_E_BADOFFSETTABLE
DMUS_E_BADWAVE
DMUS_E_BADWAVELINK
DMUS_E_BUFFERNOTSET
DMUS_E_NOARTICULATION
DMUS_E_NOTMONO
DMUS_E_NOTPCM
DMUS_E_UNKNOWNDOWNLOAD

注意

ダウンロードするデータの準備方法については、「下位レベル DLS」を参照すること。

メモリをダウンロードした後、それ以上何かを行うことはできない。ダウンロードを更新するには、新しいバッファを作成し、IDirectMusicPortDownload::GetDLId メソッドを使って取得した新しいダウンロード ID を割り当て、その ID を送信しなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPortDownload::Unload、DMUS_DOWNLOADINFO、DMUS_OFFSETTABLE


IDirectMusicPortDownload::Download

Platform SDK: DirectX

IDirectMusicPortDownload::GetAppend

IDirectMusicPortDownload::GetAppend メソッドは、ポートがダウンロード バッファの最後に追加する必要のあるメモリの量を取り出す。ポートはこの追加メモリを使って、ループ境界にまたがってデータを補間できる。

HRESULT GetAppend(
  DWORD* pdwAppend
);

パラメータ

pdwAppend
メモリが必要となる追加サンプルの数を受け取る変数のアドレス。メモリの量はウェーブ フォーマットから計算できる。

戻り値

戻り値はポートの実装によって決まる。

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_NOTIMPL

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicPortDownload::GetBuffer

IDirectMusicPortDownload::GetBuffer メソッドは、一意の識別子が既にわかっているバッファの IDirectMusicDownload インターフェイス ポインタを取り出す。

HRESULT GetBuffer(
  DWORD dwDLId,
  IDirectMusicDownload** ppIDMDownload
);

パラメータ

dwDLId
バッファのダウンロード識別子。「DMUS_DOWNLOADINFO」を参照すること。
ppIDMDownload
バッファの IDirectMusicDownload インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
DMUS_E_INVALID_DOWNLOADID
DMUS_E_NOT_DOWNLOADED_TO_PORT

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPortDownload::GetDLId、IDirectMusicDownload::GetBuffer、下位レベル DLS


IDirectMusicPortDownload::GetDLId

IDirectMusicPortDownload::GetDLId メソッドは、1 つまたは複数のダウンロード バッファのシーケンシャル識別子を取得する。

シンセサイザにダウンロードされたすべてのメモリ チャンクは、自らの DMUS_DOWNLOADINFO 構造体内で一意の識別子を保持していなければならない。GetDLId メソッドは、2 つのダウンロードが同じ識別子を持っていないことを保証する。

HRESULT GetDLId(
  DWORD* pdwStartDLId,
  DWORD dwCount
);

パラメータ

pdwStartDLId
最初の識別子を受け取る変数のアドレス。
dwCount
予約される識別子の数。一連のチャンク全体を一度にダウンロードするよう計画もできる。チャンクごとに GetDLId を呼び出す代わりに、dwCount をチャンク数に設定する。GetDLId はセットの最初の ID を返し、*pdwStartDLId と dwCount までの範囲で他の識別子が自動的に予約される。それ以降 GetDLId を呼び出すと、それまでの予約値は飛ばされる。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_INVALIDARG

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPortDownload::GetBuffer、下位レベル DLS


IDirectMusicPortDownload::Unload

IDirectMusicPortDownload::Unload メソッドは、以前に IDirectMusicPortDownload::Download を使ってダウンロードされたバッファをアンロードする。

HRESULT Unload(
  IDirectMusicDownload* pIDMDownload
);

パラメータ

pIDMDownload
バッファ用の IDirectMusicDownload インターフェイスのアドレス。

戻り値

戻り値はポートの実装によって決まる。

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_NOINTERFACE
DMUS_E_SYNTHNOTCONFIGURED

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicSegment

IDirectMusicSegment インターフェイスは、セグメント、つまり複数のトラックで構成されているミュージック チャンクを表す。セグメントを定義するほとんどすべての情報がトラック内に保存されていて、トラックはどのようなものであってもかまわないので、セグメント自体は比較的簡潔なオブジェクトである。セグメント オブジェクトはデータの性質を把握していないとはいえ、トラック内のデータにアクセスするメソッドはいくつもある。

DirectMusicSegment オブジェクトは、自らのデータをロードするために IDirectMusicObject と IPersistStream の各インターフェイスもサポートしている。

IDirectMusicSegment インターフェイスのメソッドは、以下のグループにまとめることができる。

タイミングとループ | GetDefaultResolution
 | GetLength
 | GetLoopPoints
 | GetRepeats
 | GetStartPoint
 | SetDefaultResolution
 | SetLength
 | SetLoopPoints
 | SetRepeats
 | SetStartPoint
トラック | GetTrack
 | GetTrackGroup
 | InsertTrack
 | RemoveTrack
通知 | AddNotificationType
 | RemoveNotificationType
パラメータ | GetParam
 | SetParam
ツール | GetGraph
 | SetGraph
その他 | Clone Clone
 | InitPlay
 | SetPChannelsUsed

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

セグメント


IDirectMusicSegment::AddNotificationType

IDirectMusicSegment::AddNotificationType メソッドは、IDirectMusicPerformance::AddNotificationType メソッドに似ていて、このメソッドから呼び出される。前者は、セグメントが通知に応答できるようにする。セグメントは、各トラックの IDirectMusicTrack::AddNotificationType メソッドを呼び出す。

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
追加される通知タイプの識別子への参照 (C++) またはアドレス (C)。定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること。アプリケーションは、カスタム トラックについて独自のタイプを定義できる。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_OUTOFMEMORY

注意

セグメントは、タイプ GUID_NOTIFICATION_PERFORMANCE の通知を生成できない。このタイプの通知を取得するには、IDirectMusicPerformance::AddNotificationType を呼び出さなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理


IDirectMusicSegment::Clone

IDirectMusicSegment::Clone メソッドは、セグメントとその中のトラックのすべてまたはパートをコピーする。

HRESULT Clone(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  IDirectMusicSegment** ppSegment
);

パラメータ

mtStart
コピー開始パート。0 未満の場合や、セグメントの長さを超える場合は、0 が使われる。
mtEnd
コピー終了パート。この値がセグメントの最後を超える場合は、セグメントの最後までコピーされる。0、または mtStart 未満の場合も、最後までコピーされる。
ppSegment
メソッドが成功した場合は、作成されたセグメントへのポインタを受け取る変数のアドレス。アプリケーションには、セグメントの終了時に Release を呼び出す責任がある。

戻り値

成功すれば S_OK を返す。一部のトラックのコピーに失敗した場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

E_OUTOFMEMORY
E_POINTER

注意

セグメント内に IDirectMusicGraph インターフェイスが存在する場合、そのポインタもクローンの一部としてコピーされ、参照カウントがインクリメントされる。IDirectMusicSegment::SetStartPoint と IDirectMusicSegment::SetLoopPoints の各メソッドによって設定された開始ポイントとループ ポイントは、クローンの内部でデフォルト値 (開始ポイントは 0、ループ ポイントはセグメントの終わりを意味する 0) に設定される。反復回数は 0 にリセットされる。IDirectMusicSegment::SetDefaultResolution メソッドにより設定された分解能も、クローンの一部としてコピーされる。

スタイルベースのセグメントは、mtStart が 0 より大きい場合、小節境界上になければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicSegment::GetDefaultResolution

IDirectMusicSegment::GetDefaultResolution メソッドは、同期化用のデフォルトの分解能を取り出す。

HRESULT GetDefaultResolution(
  DWORD* pdwResolution
);

パラメータ

pdwResolution
デフォルトの分解能を受け取る変数のアドレス。DMUS_SEGF_FLAGS を参照すること。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetDefaultResolution、セグメントのタイミング


IDirectMusicSegment::GetGraph

IDirectMusicSegment::GetGraph メソッドは、セグメントのツール グラフを取り出す。

HRESULT GetGraph(
  IDirectMusicGraph** ppGraph
);

パラメータ

ppGraph
ツール グラフへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_POINTER

注意

セグメント内にグラフが存在しない場合、このメソッドは E_FAIL を返す。

ツール グラフの参照カウントはインクリメントされる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetGraph


IDirectMusicSegment::GetLength

IDirectMusicSegment::GetLength メソッドは、セグメントの長さを取り出す。

HRESULT GetLength(
  MUSIC_TIME* pmtLength
);

パラメータ

pmtLength
ミュージック タイムで表されたセグメントの長さを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

何らかの理由でセグメントの長さが設定されていなかった場合、*pmtLength は 0 に設定される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetLength


IDirectMusicSegment::GetLoopPoints

IDirectMusicSegment::GetLoopPoints メソッドは、セグメント内の開始ポイントとループ ポイントを取り出す。これらの 2 ポイント間は、IDirectMusicSegment::SetRepeats メソッドで設定された回数だけ反復される。

HRESULT GetLoopPoints(
  MUSIC_TIME* pmtStart,
  MUSIC_TIME* pmtEnd
);

パラメータ

pmtStart
ループの開始ポイントを受け取る変数のアドレス。
pmtEnd
ループの終了ポイントを受け取る変数のアドレス。値 0 は、セグメント全体をループさせることを意味する。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetLoopPoints、セグメントのタイミング


IDirectMusicSegment::GetParam

IDirectMusicSegment::GetParam メソッドは、セグメント内の 1 つのトラックからデータを取り出す。

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

パラメータ

rguidType
取得されるデータ タイプの識別子への参照 (C++) またはアドレス (C)。「トラック パラメータのタイプ」を参照すること。
dwGroupBits
希望のトラックが置かれているグループ。すべてのグループを指定するには、この値を 0xFFFFFFFF に設定する。詳細については、「トラックの識別」を参照すること。
dwIndex
dwGroupBits で識別されるグループ内で、データの取得先のトラックに割り当てられているインデックス。
mtTime
データの取得を行うタイム。
pmtNext
データが有効になるセグメント タイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、pmtNext を NULL に設定してもよい。「注意」を参照すること。
pParam
返されるデータの保存用に割り当てられた構造体のアドレス。返されるデータの保存用に割り当てられた構造体のアドレス。この構造体は、rguidType で識別されたデータ タイプにとって適切な種類とサイズを備えていなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_GET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

別の制御セグメントが挿入される場合、*pmtNext で返されるタイムの前に無効になることがある。制御セグメントの詳細については、「セグメント」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、ミュージック パラメータ


IDirectMusicSegment::GetRepeats

IDirectMusicSegment::GetRepeats メソッドは、セグメントのループ部分に設定された反復回数を取り出す。

HRESULT GetRepeats(
  DWORD* pdwRepeats
);

パラメータ

pdwRepeats
セグメントのループ部分に設定されている反復回数を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetRepeats


IDirectMusicSegment::GetStartPoint

IDirectMusicSegment::GetStartPoint メソッドは、IDirectMusicPerformance::PlaySegment メソッドに応答してセグメントの演奏を開始するポイントを取り出す。

HRESULT GetStartPoint(
  MUSIC_TIME* pmtStart
);

パラメータ

pmtStart
セグメントの演奏開始タイムを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetStartPoint


IDirectMusicSegment::GetTrack

IDirectMusicSegment::GetTrack メソッドは、指定されたタイプ、グループ、およびインデックスに一致するトラックをトラック リストから検索し、DirectMusicTrack オブジェクトへのポインタを取り出す。

HRESULT GetTrack(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  IDirectMusicTrack** ppTrack
);

パラメータ

rguidType
検索されるトラックの識別子 (CLSID_DirectMusicChordTrack など) への参照 (C++) またはアドレス (C)。値として GUID_NULL を指定すると、任意のトラックを取り出す。トラック識別子については、「IDirectMusicTrack」を参照すること。
dwGroupBits
検索されるトラックを含むトラック グループ。値 0 は無効である。dwGroupBits 内の各ビットは、1 つのトラック グループに対応する。グループにかかわりなくすべてのトラックを検索するには、このパラメータを 0xFFFFFFFF に設定する。
dwIndex
rguidType タイプ、なおかつ dwGroupBits に一致するために返されたグループから 1 つのトラックを識別するために使われる、0 から始まるインデックス。dwGroupBits で複数のグループが選択されている場合、選択されたグループの集合の中で見つかった pCommandGuid タイプから、このインデックスは n 番目のトラックを指定する。
ppTrack
トラックへのポインタを受け取る変数のアドレス。トラックが見つからなかった場合、この変数は NULL に設定される。

戻り値

成功すれば S_OK を返す。

失敗すれば E_FAIL を返す。

注意

すべてのトラックを列挙するには、rguidType に GUID_NULL、dwGroupBits に 0xFFFFFFFF を指定する。最初は dwIndex を 0 に設定して GetTrack を呼び出し、メソッドが成功コードを返さなくなるまで dwIndex をインクリメントして呼び出しを続ける。

トラック グループの詳細については、「トラックの識別」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::InsertTrack


IDirectMusicSegment::GetTrackGroup

IDirectMusicSegment::GetTrackGroup メソッドは、セグメント内のトラックに対して設定されたグループ ビットを取り出す。

HRESULT GetTrackGroup(
  IDirectMusicTrack* pTrack,
  DWORD* pdwGroupBits
);

パラメータ

pTrack
グループ ビットの検索対象となるトラック。
pdwGroupBits
グループを受け取る変数のアドレス。*pdwGroupBits 内の各ビットは、1 つのトラック グループに対応する。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::InsertTrack、トラックの識別


IDirectMusicSegment::InitPlay

IDirectMusicSegment::InitPlay は、セグメントが演奏される直前に、パフォーマンスによって呼び出される。

HRESULT InitPlay(
  IDirectMusicSegmentState** ppSegState,
  IDirectMusicPerformance* pPerformance,
  DWORD dwFlags
);

パラメータ

ppSegState
IDirectMusicSegmentState インターフェイスへのポインタを受け取る変数のアドレス。このインターフェイスはこのメソッドを呼び出したときに作成され、状態データを保持するために使われる。参照カウントが 1 になって返されるので、Release メソッドを呼び出すと、このインターフェイスは完全に解放される。
pPerformance
IDirectMusicPerformance インターフェイスのアドレス。パフォーマンス オブジェクトに対してこのメソッドを呼び出すために、セグメントとセグメント状態はこのインターフェイスを必要とする。
dwFlags
トラックの動作を変更する DMUS_SEGF_FLAGS。「注意」を参照すること。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_OUTOFMEMORY

注意

このメソッドは、DirectMusic によって内部的に使われるものであり、アプリケーションから呼び出してはならない。このメソッドは将来のバージョンではサポートされない。

セグメントを演奏する直前に、パフォーマンス エンジンは InitPlay メソッドを呼び出す。次にこのセグメントは IDirectMusicTrack::InitPlay メソッドを呼び出して各トラックの状態オブジェクトを収集し、その結果をセグメント状態のオブジェクトに保存する。IDirectMusicSegmentState インターフェイスを使うと、このオブジェクトにアクセスできる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicSegment::InsertTrack

IDirectMusicSegment::InsertTrack メソッドは、指定されたトラックを、セグメントのリストトラックに挿入する。

HRESULT InsertTrack(
  IDirectMusicTrack* pTrack,
  DWORD dwGroupBits
);

パラメータ

pTrack
セグメントに追加されるトラック。
dwGroupBits
トラックの挿入先となる、1 つまたは複数のグループ。この値は 0 にできない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

トラックは互いが正しくリンクするようにグループで配置される。たとえば、セグメントには、スタイル トラックとミュート トラックがそれぞれ 2 つ含まれる場合がある。各スタイル トラックは、それらに関連付けられているミュート トラックと共に異なるグループに配置される。トラック グループの詳細については、「トラックの識別」を参照すること。

セグメントが現在演奏中の場合、新しいトラックは再生に含まれない。これは、セグメント状態の初期化の際に新しいトラックは含まれていなかったためである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::RemoveTrack、IDirectMusicSegment::GetTrackGroup


IDirectMusicSegment::RemoveNotificationType

IDirectMusicSegment::RemoveNotificationType メソッドは、IDirectMusicPerformance::RemoveNotificationType メソッドに似ていて、このメソッドから呼び出される。前者により、セグメントは通知を削除できる。セグメントは、各トラックの IDirectMusicTrack::RemoveNotificationType メソッドを呼び出す。

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
削除される通知タイプの識別子への参照 (C++) またはアドレス (C)(定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること)。この値を GUID_NULL に設定すると、すべての通知が削除される。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理


IDirectMusicSegment::RemoveTrack

IDirectMusicSegment::RemoveTrack メソッドは、セグメントのトラック リストからトラックを削除する。

HRESULT RemoveTrack(
  IDirectMusicTrack* pTrack
);

パラメータ

pTrack
セグメントのトラック リストから削除されるトラック。

戻り値

成功すれば S_OK を返す。指定されたトラックがトラック リストの中に存在しない場合は S_FALSE を返す。

失敗すれば E_POINTER を返す。

注意

削除されたトラックは解放される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::InsertTrack


IDirectMusicSegment::SetDefaultResolution

IDirectMusicSegment::SetDefaultResolution メソッドは、同期化用のデフォルトの分解能を設定する。

HRESULT SetDefaultResolution(
  DWORD dwResolution
);

パラメータ

dwResolution
希望のデフォルトの分解能。この値は、0 または次に示す DMUS_SEGF_FLAGS 列挙型のメンバのいずれかである。

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

戻り値

S_OK を返す。

注意

このメソッドは、主にセカンダリ セグメント (モチーフ) が自らを小節、拍、またはグリッド のどの分解能で同期化するかを定義するために使われる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::GetDefaultResolution、セグメントのタイミング


IDirectMusicSegment::SetGraph

IDirectMusicSegment::SetGraph メソッドは、ツール グラフをセグメントに割り当てる。

HRESULT SetGraph(
  IDirectMusicGraph* pGraph
);

パラメータ

pGraph
Tool graph to be set.セグメント グラフを消去するために NULL に設定してもよい。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

現在のツールグラフ内で処理中のすべてのメッセージは削除される。

このメソッドはグラフの参照カウントをインクリメントするので、オリジナルの参照を解放しておくと安全である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SetGraph、DirectMusic ツール


IDirectMusicSegment::SetLength

IDirectMusicSegment::SetLength メソッドは、セグメントの長さをミュージック タイム単位で設定する。通常、ローダーがファイルからセグメントの長さを取り出して、その長さをセグメント オブジェクトに渡すときに、ローダーがこのメソッドを呼び出す。

HRESULT SetLength(
  MUSIC_TIME mtLength
);

パラメータ

mtLength
希望の長さ。0 より大きい値でなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
DMUS_E_OUT_OF_RANGE

注意

プライマリ セグメントの長さを設定しなかった場合、DMUS_SEGF_QUEUE フラグを指定した他のプライマリ セグメントをキューに挿入する際に問題が発生することがある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::GetLength


IDirectMusicSegment::SetLoopPoints

IDirectMusicSegment::SetLoopPoints メソッドは、反復するセグメントのパートの開始ポイントと終了ポイントを設定する。セグメントのパートは、IDirectMusicSegment::SetRepeats メソッドによって設定される回数だけ反復する。

HRESULT SetLoopPoints(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd
);

パラメータ

mtStart
ループの開始ポイント。
mtEnd
ループの終了ポイント。値 0 は、セグメント全体をループさせることを意味する。

戻り値

成功すれば S_OK を返す。

失敗すれば DMUS_E_OUT_OF_RANGE を返す。

注意

セグメントの演奏時には、開始タイムから mtEnd まで演奏し、mtStart にループする。次に、ループ部分を IDirectMusicSegment::SetRepeats によって設定される回数だけ反復し、最後まで演奏する。

デフォルト値は、最初から最後までセグメント全体をループさせるように設定されている。

mtStart の値がセグメントの長さ以上の場合、または mtEnd の値がセグメントの長さを超える場合、メソッドは失敗する。mtEnd が 0 の場合、mtStart も 0 でなければならない。

このメソッドは、このセグメントから作成された、現在演奏中のセグメント状態に影響を及ぼすことはない。

キャッシングされたセグメントのループ ポイントは、セグメントが解放され、再ロードされた場合でも継続される。セグメントが後でキャッシュから再ロードされないようにするために、セグメントを解放する前に、IDirectMusicLoader::ReleaseObject を呼び出す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::GetLoopPoints、セグメントのタイミング


IDirectMusicSegment::SetParam

IDirectMusicSegment::SetParam メソッドは、セグメント内の 1 つのトラックにデータを設定する。

HRESULT SetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  void* pParam
);

パラメータ

rguidType
設定されるデータ タイプへの参照 (C++) またはアドレス (C)。「トラック パラメータのタイプ」を参照すること。
dwGroupBits
希望のトラックが置かれているグループ。すべてのグループを指定するには、この値を 0xFFFFFFFF に設定する。詳細については、IDirectMusicPerformance::SetParam の「注意」を参照すること。
dwIndex
dwGroupBits で識別されるグループ内で、データの設定先のトラックに割り当てられているインデックス。
mtTime
データの設定を行うタイム。
pParam
データを保持する構造体のアドレス。データが必要ない場合は NULL を指定する。この構造体は、rguidType で識別されたデータ タイプにとって適切な種類とサイズを備えていなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicTrack::SetParam、ミュージック パラメータ


IDirectMusicSegment::SetPChannelsUsed

IDirectMusicSegment::SetPChannelsUsed メソッドは、このセグメントが使うパフォーマンス チャンネル (P チャンネル) を設定する。このメソッドは通常、トラックがどの P チャンネルを使っているかをセグメントに通知するために IDirectMusicTrack::Init メソッド内でトラックによって呼び出される。

HRESULT SetPChannelsUsed(
  DWORD dwNumPChannels,
  DWORD* paPChannels
);

パラメータ

dwNumPChannels
設定される P チャンネルの数。この値は、paPChannels が指す配列内のメンバの数と等しくなければならない。
paPChannels
P チャンネルの配列へのポインタ。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

このメソッドを使うと、セグメントがどのポートを使っているかをパフォーマンスに知らせ、その結果、パフォーマンスがワースト ケースに備える代わりに実際の遅延時間を決定できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

遅延時間とバンパー時間、チャンネル


IDirectMusicSegment::SetRepeats

IDirectMusicSegment::SetRepeats メソッドは、セグメントのループ部分の反復回数を設定する。デフォルトでは、セグメント全体がループされる。

HRESULT SetRepeats(
  DWORD dwRepeats
);

パラメータ

dwRepeats
セグメントのループ部分が反復される回数。値 0 は、一度の演奏だけで反復がないことを意味する。

戻り値

S_OK を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::GetRepeats、IDirectMusicSegment::SetLoopPoints、セグメントのタイミング


IDirectMusicSegment::SetStartPoint

IDirectMusicSegment::SetStartPoint メソッドは、IDirectMusicPerformance::PlaySegment メソッドの呼び出しに応答してセグメントの演奏を開始するポイントを設定する。

HRESULT SetStartPoint(
  MUSIC_TIME mtStart
);

パラメータ

mtStart
セグメントの演奏開始ポイント。この値が 0 未満またはセグメントの長さより大きい場合、開始ポイントは 0 に設定される。

戻り値

成功すれば S_OK を返す。

失敗すれば DMUS_E_OUT_OF_RANGE を返す。

注意

デフォルトの開始ポイントは 0 であり、セグメントの先頭から開始することを意味する。

mtStart がセグメントの長さ以上の場合は、このメソッドは失敗する。セグメントがまだ長さを持っていない場合、このメソッドの前に IDirectMusicSegment::SetLength を呼び出さなければならない。

このメソッドは、このセグメントから作成された、現在演奏中のセグメント状態に影響を及ぼすことはない。

キャッシングされたセグメントの開始ポイントは、セグメントが解放され、再ロードされた場合でも継続される。セグメントが後でキャッシュから再ロードされないようにするために、セグメントを解放する前に、IDirectMusicLoader::ReleaseObject を呼び出す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::GetStartPoint、IDirectMusicSegmentState::GetStartPoint、IDirectMusicSegment::SetLength、IDirectMusicSegment::SetLoopPoints、セグメントのタイミング


IDirectMusicSegmentState

IDirectMusicPerformance::PlaySegment メソッドを呼び出すと、パフォーマンス エンジンは演奏中のセグメント状態を追跡するセグメント状態オブジェクトを生成する。また、IDirectMusicSegmentState インターフェイスの形でセグメントへのハンドルをアプリケーションに提供する。このハンドルを使って、セグメントの再生ステータスを追跡できる。また、IDirectMusicPerformance のメソッドと組み合わせることにより、セグメント再生の直接的な停止やセグメントのパフォーマンスからの削除にも利用できる。

このインターフェイスは、以下のメソッドをサポートする。

情報 | GetRepeats
 | GetSeek
 | GetSegment
 | GetStartPoint
 | GetStartTime

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicSegmentState::GetRepeats

IDirectMusicSegmentState::GetRepeats メソッドは、セグメントのループ部分に設定された反復回数を返す。

HRESULT GetRepeats(
  DWORD* pdwRepeats
);

パラメータ

pdwRepeats
反復回数を受け取る変数のアドレス。値 0 は、そのセグメント全体を 1 回だけ演奏し、反復する部分がないことを意味する。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetRepeats


IDirectMusicSegmentState::GetSeek

IDirectMusicSegmentState::GetSeek メソッドは、セグメント状態内の現在のシークポインタを取り出す。これは、次に IDirectMusicTrack::Play メソッドを呼び出したときに渡される、mtStart パラメータの値である。この値はループと反復を考慮に入れていないため、セグメント状態全体が最初から反復される場合は、シーク ポインタは 0 にリセットされる。

HRESULT GetSeek(
  MUSIC_TIME* pmtSeek
);

パラメータ

pmtSeek
現在のシーク ポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicSegmentState::GetSegment

IDirectMusicSegmentState::GetSegment メソッドは、このセグメント状態を保持するセグメントへのポインタを返す。

HRESULT GetSegment(
  IDirectMusicSegment** ppSegment
);

パラメータ

ppSegment
IDirectMusicSegment インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

ppSegment に返されるポインタは、アプリケーションが解放しなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicSegmentState::GetStartPoint

IDirectMusicSegmentState::GetStartPoint メソッドは、演奏の開始に使われる (または既に使われた) セグメントのオフセットを返す。

HRESULT GetStartPoint(
  MUSIC_TIME * pmtStart
);

パラメータ

pmtStart
セグメントの先頭から、最初に演奏されるセグメント状態までのオフセット (ミュージック タイム単位) を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetStartPoint、IDirectMusicSegmentState::GetStartTime


IDirectMusicSegmentState::GetStartTime

IDirectMusicSegmentState::GetStartTime メソッドは、セグメントの演奏が開始された、またはこれから開始される演奏タイムを取得する。

HRESULT GetStartTime(
  MUSIC_TIME* pmtStart
);

パラメータ

pmtStart
このセグメント状態に保存されているミュージック タイム単位のオフセットを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

注意

セグメントの演奏が開始ポイント以外のほかのポイントから開始された場合、このメソッドが返す値から、IDirectMusicSegmentState::GetStartPoint が返すタイムを引くことによって、このセグメントの開始タイムを取り出すことができる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment::SetStartPoint、IDirectMusicSegment::GetStartPoint、IDirectMusicSegmentState::GetStartPoint


IDirectMusicStyle

IDirectMusicStyle インターフェイスは、スタイル オブジェクトへのアクセスを提供する。スタイル オブジェクトは、ミュージック パターンを演奏するときに必要になる情報をパフォーマンスに提供する。概要については、「スタイルの使い方」を参照すること。

スタイルには通常、バンドとモチーフが含まれるので、IDirectMusicStyle はこれらのオブジェクトにアクセスするためのメソッドを提供する。

DirectMusicStyle オブジェクトは、自らのデータをロードするために IDirectMusicObject と IPersistStream の各インターフェイスもサポートしている。

IDirectMusicStyle インターフェイスのメソッドは、以下のグループにまとめることができる。

列挙 | EnumBand
 | EnumChordMap
 | EnumMotif
情報 | GetBand
 | GetChordMap
 | GetDefaultBand
 | GetDefaultChordMap
 | GetEmbellishmentLength
 | GetMotif
 | GetTempo
 | GetTimeSignature

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicStyle::EnumBand

IDirectMusicStyle::EnumBand メソッドは、与えられたインデックスに対応するバンド名を取り出す。

HRESULT EnumBand(
  DWORD dwIndex,
  WCHAR * pwszName
);

パラメータ

dwIndex
スタイルのバンドリスト内の、0 から始まるインデックス。
pwszName
バンド名を受け取るバッファのアドレス。MAX_PATH のサイズを持つべきである。

戻り値

成功すれば S_OK を返す。指定されたインデックス値を持つバンドがなければ S_FALSE、名前の長さの値が MAX_PATH より大きい場合は DMUS_S_STRING_TRUNCATED を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_TYPE_UNSUPPORTED
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicStyle::EnumChordMap

IDirectMusicStyle::EnumChordMap メソッドは、指定されたインデックス値を持つコード マップの名前を取り出す。

HRESULT EnumChordMap(
  DWORD dwIndex,
  WCHAR * pwszName
);

パラメータ

dwIndex
スタイルのコード マップ リスト内にある、コード マップの 0 から始まるインデックス。
pwszName
コード マップ名を受け取るバッファのアドレス。MAX_PATH のサイズを持つべきである。

戻り値

成功すれば S_OK を返す。指定されたインデックス値を持つコード マップがなければ S_FALSE、名前の長さの値が MAX_PATH より大きい場合は DMUS_S_STRING_TRUNCATED を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_TYPE_UNSUPPORTED
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicStyle::EnumMotif

IDirectMusicStyle::EnumMotif メソッドは、与えられたインデックスに対応するモチーフ名を取り出す。

HRESULT EnumMotif(
  DWORD dwIndex,
  WCHAR * pwszName
);

パラメータ

dwIndex
スタイルのモチーフリスト内の、0 から始まるインデックス。
pwszName
モチーフ名を受け取るバッファのアドレス。MAX_PATH のサイズを持つべきである。

戻り値

成功すれば S_OK を返す。指定されたインデックス値を持つモチーフがなければ S_FALSE、モチーフ名の長さの値が MAX_PATH より大きい場合は DMUS_S_STRING_TRUNCATED を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle::GetMotif、モチーフの使い方


IDirectMusicStyle::GetBand

IDirectMusicStyle::GetBand メソッドは、指定されたバンドを取り出す。

HRESULT GetBand(
  WCHAR* pwszName,
  IDirectMusicBand** ppBand
);

パラメータ

pwszName
取り出されるバンドの名前。この名前は、スタイルの作成者によって割り当てられる。
ppBand
バンドへのポインタを受け取る変数のアドレス。

戻り値

メソッドが成功し、バンドが返された場合は S_OK を返す。指定された名前に対応するバンドが存在しない場合は S_FALSE を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle::GetDefaultBand、バンドの使い方


IDirectMusicStyle::GetChordMap

IDirectMusicStyle::GetChordMap メソッドは、指定されたコード マップを取り出す。

HRESULT GetChordMap(
  WCHAR* pwszName,
  IDirectMusicChordMap** ppChordMap
);

パラメータ

pwszName
取り出されるコード マップの名前。
ppChordMap
IDirectMusicChordMap インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

メソッドが成功し、コード マップが返された場合は S_OK を返す。指定された名前を持つコード マップが存在しない場合は S_FALSE を返す。

ppChordMap が有効なポインタではない場合は E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle::GetDefaultChordMap、コード マップの使い方


IDirectMusicStyle::GetDefaultBand

IDirectMusicStyle::GetDefaultBand メソッドは、スタイルのデフォルトのバンドを取り出す。

HRESULT GetDefaultBand(
  IDirectMusicBand ** ppBand
);

パラメータ

ppBand
デフォルトのバンドへのポインタを受け取る変数のアドレス。

戻り値

メソッドが成功し、バンドが返された場合は S_OK を返す。スタイルにデフォルトのバンドがない場合は S_FALSE を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle::GetBand、バンドの使い方


IDirectMusicStyle::GetDefaultChordMap

IDirectMusicStyle::GetDefaultChordMap メソッドは、スタイルのデフォルトのコード マップを取り出す。

HRESULT GetDefaultChordMap(
  IDirectMusicChordMap** ppChordMap
);

パラメータ

ppChordMap
IDirectMusicChordMap インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

メソッドが成功し、コード マップが返された場合は S_OK を返す。スタイルにデフォルトのコード マップがない場合は S_FALSE を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle::GetChordMap、コード マップの使い方


IDirectMusicStyle::GetEmbellishmentLength

IDirectMusicStyle::GetEmbellishmentLength メソッドは、指定された装飾タイプとグルーブ レベルから、最短パターンの長さと最長パターンの長さを見つける。

HRESULT GetEmbellishmentLength(
  DWORD dwType,
  DWORD dwLevel,
  DWORD* pdwMin,
  DWORD* pdwMax
);

パラメータ

dwType
装飾タイプ。DMUS_COMMANDT_TYPES を参照すること。
dwLevel
1 ～ 100 の範囲のグルーブ レベル。グルーブではない装飾は無視される。
pdwMin
指定されたタイプとグルーブ レベルの最短パターンの長さを受け取る変数のアドレス。
pdwMax
指定されたタイプとグルーブ レベルの最長パターンの長さを受け取る変数のアドレス。

戻り値

成功すれば S_OK または S_FALSE を返す。

失敗すれば E_POINTER を返す。

注意

指定されたタイプとグルーブ レベルに対応するパターンが存在しない場合は、戻り値は S_FALSE である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicStyle::GetMotif

IDirectMusicStyle::GetMotif メソッドは、指定されたモチーフを含むセグメントを作成する。

HRESULT GetMotif(
  WCHAR* pwszName,
  IDirectMusicSegment** ppSegment
);

パラメータ

pwszName
取り出されるモチーフの名前。
ppSegment
指定されたモチーフを含むセグメントへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK または S_FALSE を返す。

失敗すれば E_POINTER を返す。

注意

このメソッドは、pwszName に一致する名前を持つモチーフをスタイル リストから検索する。モチーフが見つかった場合、モチーフ トラックを含むセグメントが作成される。トラックは、スタイルをトラックの関連スタイル、モチーフをトラックのパターンとして参照する。

指定された名前を持つモチーフが存在しない場合、このメソッドは S_FALSE を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

モチーフの使い方


IDirectMusicStyle::GetTempo

IDirectMusicStyle::GetTempo メソッドは、スタイルの推奨テンポを取り出す。

HRESULT GetTempo(
  double* pTempo
);

パラメータ

pTempo
スタイルの推奨テンポを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

pTempo が有効なポインタではない場合は E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicStyle::GetTimeSignature

IDirectMusicStyle::GetTimeSignature メソッドは、スタイルの拍子記号を取り出す。

HRESULT GetTimeSignature(
  DMUS_TIMESIGNATURE* pTimeSig
);

パラメータ

pTimeSig
データを受け取る DMUS_TIMESIGNATURE 構造体のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicThru

IDirectMusicThru インターフェイスは、ミュージック メッセージのキャプチャ ポートから別のポートへの転送をサポートする。このインターフェイスは、キャプチャ ポートの IDirectMusicPort インターフェイスに対して QueryInterface を呼び出すことによって取得される。具体的な例については、「IDirectMusicThru::ThruChannel」の「注意」を参照すること。

このインターフェイスは、以下のメソッドをサポートする。

IDirectMusicThru ThruChannel

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

音楽のキャプチャ


IDirectMusicThru::ThruChannel

IDirectMusicThru::ThruChannel メソッドは、キャプチャ ポート上のチャンネルと別のポート上のチャンネル間での転送接続を確立または解除する。

HRESULT ThruChannel(
  DWORD dwSourceChannelGroup,
  DWORD dwSourceChannel,
  DWORD dwDestinationChannelGroup,
  DWORD dwDestinationChannel,
  LPDIRECTMUSICPORT pDestinationPort
);

パラメータ

dwSourceChannelGroup
キャプチャ ポート上のチャンネル グループ。現在のバージョンの DirectMusic では、この値は常に 1 に設定される。
dwSourceChannel
ソース チャンネル。
dwDestinationChannelGroup
転送先ポート上のチャンネル グループ。
dwDestinationChannel
転送先チャンネル。
pDestinationPort
転送先チャンネルの IDirectMusicPort インターフェイスのアドレス。この値を NULL に設定すると、既存の転送接続が解除される。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_NOTIMPL
E_INVALIDARG
DMUS_E_PORT_NOT_RENDER

注意

システム エクスクルーシブ メッセージは、転送先ポートに送信されない。

Microsoft Software Synthesizer または一定の遅延時間を持たないその他のシンセサイザへの転送は推奨されない。転送は、受信 MIDI イベントを受け取ると即座に行われる。ソフトウェア シンセサイザの遅延時間が比較的長いこと (ハードウェア ポートと比べた場合)、およびソフトウェア シンセサイザは複数のオーディオ ブロックを同時にレンダリングすることから、各イベントには演奏の前にわずかな遅延が発生する。この遅延の長さは、一定していない。このランダムなオフセットは、データの再生時にジッタとして発生する。その他のデバイス (MPU-401 ポートなど) の遅延時間はわずかであるため、ジッタは発生しない。

アプリケーションがソフトウェア シンセサイザに対してデータを転送する必要がある場合、受信ノート イベントのタイム スタンプにわずかなオフセットを追加して、シンセサイザのレンダリング遅延時間を補正しなければならない。

次のサンプル コードでは、IDirectMusicThru インターフェイスを取得し、キャプチャ ポートのグループ 1 上のすべてのチャンネルと、転送先ポート上の同等のチャンネルとの間で転送接続を確立する。

HRESULT SetupOneToOneThru(
    IDirectMusicPort *pCapturePort,
    IDirectMusicPort *pRenderPort)
{
    HRESULT hr;
    IDirectMusicThru *pThru;

    hr = pCapturePort->QueryInterface(IID_IDirectMusicThru,
            (void**)&pThru);
    if (FAILED(hr))
        return hr;

    for (DWORD dwChannel = 0; dwChannel < 16; dwChannel++)
    {
        hr = pThru->ThruChannel(1, dwChannel,
            1, dwChannel, pRenderPort);
        if (FAILED(hr))
            break;
    }

    pThru->Release();
    return hr;
}

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IDirectMusicTool

ツールとは、IDirectMusicTool インターフェイスを実装するオブジェクトである。これらはグラフの内部で使われる (IDirectMusicGraph を参照)。IDirectMusicPerformance::SendPMsg を使ってメッセージを送信すると、メッセージはグラフ内のツールを通過する。ツールはメッセージの変更、追加のメッセージの作成、メッセージの削除などを行える。

このインターフェイスは主に、独自のツールを作成することを考えている開発者によって利用される。

IDirectMusicTool インターフェイスのメソッドは、以下のグループにまとめることができる。

初期化 | Init
メッセージ管理 | Flush
 | GetMediaTypeArraySize
 | GetMediaTypes
 | GetMsgDeliveryType
 | ProcessPMsg

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

DirectMusic のデータの流れの概要、メッセージの作成と配信、DirectMusic ツール


IDirectMusicTool::Flush

パフォーマンスが停止したときに、キュー内にある各メッセージに対して IDirectMusicTool::Flush メソッドが呼び出される。ツールはこのメソッドを使って、メッセージのフラッシュ (解放) に必要なあらゆることを行える。たとえば、出力ツールはこのメソッドを使って、保留されているあらゆるノートオフ メッセージが即座に処理されるようにする。

HRESULT Flush(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pPMSG,
  REFERENCE_TIME rtTime
);

パラメータ

pPerf
IDirectMusicPerformance インターフェイスのアドレス。
pPMSG
フラッシュされるメッセージ。
rtTime
フラッシュを行うタイム。

戻り値

戻り値は実装によって決まる。成功すれば次のいずれかを返す。

DMUS_S_REQUEUE
DMUS_S_FREE
S_OK

失敗すれば E_POINTER を返す。

注意

メッセージは自らの dwFlags メンバに DMUS_PMSGF_TOOL_FLUSH を設定する。DMUS_PMSG を参照すること。

メソッドが DMUS_S_REQUEUE を返した場合、指定されたメッセージをツールが取得したいと考えていることを意味する。この結果、ツールはメッセージに新しいタイム スタンプとパラメータを書き込んでもう一度キューに入れるか、メッセージに他の配信タイプを割り当ててもう一度キューに入れる。

戻り値が DMUS_S_FREE の場合、ツールはメッセージを自動的に解放したいと考えており、メッセージをもう一度キューに入れたいとは考えていないことを意味する。

戻り値が S_OK の場合、ツールはメッセージを自動的に解放したいとは考えていない。おそらく何らかの理由でツールはメッセージを保持しているか、既に自ら解放した。

pPerf によって表されるパフォーマンスへの循環参照は作成しないこと。詳細については、「DirectMusic ツール」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTool::GetMediaTypeArraySize

IDirectMusicTool::GetMediaTypeArraySize メソッドは、IDirectMusicTool::GetMediaTypes メソッドに渡さなければならない配列のサイズを取り出す。値として 0 が返された場合、そのツールはすべてのタイプを処理するので、GetMediaTypes を呼び出す必要がないことを意味する。

HRESULT GetMediaTypeArraySize(
  DWORD* pdwNumElements
);

パラメータ

pdwNumElements
メディア タイプの数を受け取る変数のアドレス。このフィールドに 0 が返された場合、すべてのタイプがサポートされている。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTool::GetMediaTypes

IDirectMusicTool::GetMediaTypes メソッドは、このツールがサポートするメッセージ タイプのリストを取り出す。

HRESULT GetMediaTypes(
  DWORD** padwMediaTypes,
  DWORD dwNumElements
);

パラメータ

padwMediaTypes
DWORD の配列のアドレス。このメソッドは、ツールがサポートしているメディア タイプをこの配列に書き込む。メディア タイプについては、DMUS_PMSGT_TYPES を参照すること。
dwNumElements
padwMediaTypes 配列内の要素の数。この値は、IDirectMusicTool::GetMediaTypeArraySize メソッドが返した数と一致しているべきである。dwNumElements の値がこの数より小さい場合、メソッドはサポートされているすべてのメッセージ タイプを返せない。値がこの数より大きい場合、配列内の余分の要素は 0 に設定される。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。dwNumElements が小さすぎてすべての値を書き込めなかった場合は S_FALSE を返す。失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_INVALIDARG
E_NOTIMPL

注意

メソッドが E_NOTIMPL を返す場合、ツールはすべてのメディア タイプを処理する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTool::GetMsgDeliveryType

IDirectMusicTool::GetMsgDeliveryType メソッドは、メッセージをツールに配信する時期を決定するツールの配信タイプを取り出す。

HRESULT GetMsgDeliveryType(
  DWORD* pdwDeliveryType
);

パラメータ

pdwDeliveryType
配信タイプを受け取る変数のアドレス。返される値は、DMUS_PMSGF_TOOL_IMMEDIATE、DMUS_PMSGF_TOOL_QUEUE、DMUS_PMSGF_TOOL_ATTIME のいずれかでなければならない。*pdwDeliveryType の値が認識されない場合、グラフによって DMUS_PMSGF_TOOL_IMMEDIATE として扱われる。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。失敗すれば E_POINTER を返す。

注意

配信メカニズムの概要については、「メッセージの作成と配信」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTool::Init

IDirectMusicTool::Init メソッドは、ツールをグラフに挿入したときに呼び出され、ツールが必要な初期化を行うための機会を提供する。

HRESULT Init(
  IDirectMusicGraph* pGraph
);

パラメータ

pGraph
呼び出し中のグラフ。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_NOTIMPL

注意

ツールは複数のグラフに挿入できるため、このメソッドは複数の呼び出しに対して問題なく対処できなければならない。

pGraph によって表されるパフォーマンスへの循環参照は作成しないこと。詳細については、「DirectMusic ツール」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicGraph::InsertTool


IDirectMusicTool::ProcessPMsg

IDirectMusicTool::ProcessPMsg メソッドは、ツールの主要なタスクを実行する。このメソッドは、IDirectMusicTool::GetMediaTypes によって指定されるタイプと一致するすべてのメッセージに対して、パフォーマンスのリアルタイム スレッドの内部から呼び出される。

HRESULT ProcessPMsg(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pPMSG
);

パラメータ

pPerf
メッセージを生成しているパフォーマンス。
pPMSG
処理されるメッセージ。

戻り値

戻り値は実装によって決まる。成功すれば次のいずれかを返す。

DMUS_S_REQUEUE
DMUS_S_FREE
S_OK

失敗すれば E_POINTER を返す。

注意

メソッドが DMUS_S_REQUEUE を返した場合、指定されたメッセージをツールが取得したいと考えていることを意味する。この結果、ツールはメッセージに新しいタイム スタンプとパラメータを書き込んでもう一度キューに入れるか、メッセージに他の配信タイプを割り当ててもう一度キューに入れられる。

戻り値が DMUS_S_FREE の場合、ツールはメッセージを自動的に解放したいと考えており、メッセージをもう一度キューに入れたいとは考えていないことを意味する。

戻り値が S_OK の場合、ツールはメッセージを自動的に解放したいとは考えていない。おそらく何らかの理由でツールはメッセージを保持しているか、既に自ら解放した。

ツールは時間のかかる操作を実行してはならない。もしそうした場合、パフォーマンス全体に大きな影響を及ぼすためである。また、pPerf によって表されるパフォーマンスへの循環参照は作成しないこと。詳細については、「DirectMusic ツール」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SendPMsg、メッセージ、メッセージの作成と配信


IDirectMusicTrack

IDirectMusicTrack インターフェイスは、トラック オブジェクトを表す。セグメントの定義に関係のあるほとんどすべての内容がトラックに保存されている。このトラック メカニズムによって、セグメントは無限に拡張可能であり、セグメントは自ら使用する音楽やオーディオのテクノロジに関して何も把握していなくてもかまわない。

独自の音楽再生メカニズムを DirectMusic に実装することを計画している場合、そのメカニズムを表す DirectMusicTrack オブジェクトを作成する必要がある。DirectMusicTrack オブジェクトを作成しなかった場合、このインターフェイスのメソッドは通常、アプリケーションから直接呼び出されない。

注 : IDirectMusicTrack インターフェイスのメソッドを実装するときは、渡されるオブジェクトへの参照を保持しないこと。たとえば、IDirectMusicTrack::Init がパラメータとして受け取る IDirectMusicSegment インターフェイスへの参照を追加する場合は、この参照が解放されるようにする。

IDirectMusicTrack インターフェイスのメソッドは、以下のグループにまとめることができる。

初期化 | Init
再生 | EndPlay
 | InitPlay
 | Play
通知 | AddNotificationType
 | RemoveNotificationType
パラメータ | GetParam
 | IsParamSupported
 | SetParam
その他 | Clone

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

DirectMusicTrack オブジェクトは、自らのデータをロードするために IDirectMusicObject と IPersistStream の各インターフェイスもサポートしている。

次の表に、標準のトラック タイプによってサポートされるメソッドを示す。標準タイプの一般的な説明については、「トラック」を参照すること。

トラック | IDirectMusicTrack メソッド |  | IPersistStream メソッド
バンド (CLSID_DirectMusicBandTrack)
 | AddNotificationType | いいえ | IsDirty | はい
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | はい
 | GetParam | いいえ | Save | はい
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | はい
 | Play | はい
 | SetParam | はい
 | RemoveNotificationType | いいえ
コード (CLSID_DirectMusicChordTrack)
 | AddNotificationType | はい | IsDirty | はい
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | はい
 | GetParam | はい | Save | はい
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | はい
 | Play | はい
 | SetParam | はい
 | RemoveNotificationType | はい
コード マップ (CLSID_DirectMusicChordMapTrack)
 | AddNotificationType | いいえ | IsDirty | いいえ
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい* | Load | はい
 | GetParam | はい | Save | いいえ
 | Init | はい* |  |
 | InitPlay | はい*
 | IsParamSupported | はい
 | Play | はい*
 | SetParam | はい
 | RemoveNotificationType | いいえ
コマンド (CLSID_DirectMusicCommandTrack)
 | AddNotificationType | はい | IsDirty | はい
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | はい
 | GetParam | はい | Save | はい
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | はい
 | Play | はい
 | SetParam | はい
 | RemoveNotificationType | はい
モチーフ (CLSID_DirectMusicMotifTrack)
 | AddNotificationType | はい | IsDirty | いいえ
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | いいえ
 | GetParam | いいえ | Save | いいえ
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | はい
 | Play | はい
 | SetParam | はい
 | RemoveNotificationType | はい
ミュート (CLSID_DirectMusicMuteTrack)
 | AddNotificationType | いいえ | IsDirty | はい
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい* | Load | はい
 | GetParam | はい | Save | はい
 | Init | はい* |  |
 | InitPlay | はい*
 | IsParamSupported | はい
 | Play | はい*
 | SetParam | はい
 | RemoveNotificationType | いいえ
シーケンス (CLSID_DirectMusicSeqTrack)
 | AddNotificationType | いいえ | IsDirty | いいえ
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | はい
 | GetParam | いいえ | Save | いいえ
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | いいえ
 | Play | はい
 | SetParam | いいえ
 | RemoveNotificationType | いいえ
サイン ポスト (CLSID_DirectMusicSignPostTrack)
 | AddNotificationType | いいえ | IsDirty | はい
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい* | Load | はい
 | GetParam | いいえ | Save | はい
 | Init | はい* |  |
 | InitPlay | はい*
 | IsParamSupported | いいえ
 | Play | はい*
 | SetParam | いいえ
 | RemoveNotificationType | いいえ
スタイル (CLSID_DirectMusicStyleTrack)
 | AddNotificationType | はい | IsDirty | いいえ
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | はい
 | GetParam | はい | Save | いいえ
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | はい
 | Play | はい
 | SetParam | はい
 | RemoveNotificationType | はい
SysEx (CLSID_DirectMusicSysExTrack)
 | AddNotificationType | いいえ | IsDirty | いいえ
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | はい
 | GetParam | いいえ | Save | いいえ
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | いいえ
 | Play | はい
 | SetParam | いいえ
 | RemoveNotificationType | いいえ
テンポ (CLSID_DirectMusicTempoTrack)
 | AddNotificationType | いいえ | IsDirty | いいえ
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | はい
 | GetParam | はい | Save | いいえ
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | はい
 | Play | はい
 | SetParam | はい
 | RemoveNotificationType | いいえ
拍子記号** (CLSID_DirectMusicTimeSigTrack)
 | AddNotificationType | はい | IsDirty | いいえ
 | Clone | はい | GetSizeMax | いいえ
 | EndPlay | はい | Load | はい
 | GetParam | はい | Save | いいえ
 | Init | はい |  |
 | InitPlay | はい
 | IsParamSupported | はい
 | Play | はい
 | SetParam | はい
 | RemoveNotificationType | はい

注 :

* このメソッドは E_NOTIMPL 以外の値を返すが、その他の処理は行わない。

** 拍子記号トラックは、インポートされた MIDI ファイルおよびそれを使って作成される DirectMusic Producer セグメント内に存在する。ほとんどの場合、スタイル トラックは拍子記号トラックの機能を実装する。そのため、スタイル トラックを含んでいるセグメントが拍子記号トラックも含んでいる必要はない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

トラック、トラック パラメータの設定と取り出し


IDirectMusicTrack::AddNotificationType

IDirectMusicTrack::AddNotificationType メソッドは、トラックへのイベント通知を可能にする。IDirectMusicSegment::AddNotificationType メソッドに似ていて、このメソッドから呼び出される。

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
追加される通知タイプの識別子への参照 (C++) またはアドレス (C)。定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること。アプリケーションは、カスタム トラックについて独自のタイプを定義できる。

戻り値

成功すれば S_OK を返す。トラックが通知タイプをサポートしない場合は S_FALSE を返す。

トラックが通知をサポートしない場合は、E_NOTIMPL を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicTrack::RemoveNotificationType、通知とイベントの処理


IDirectMusicTrack::Clone

IDirectMusicTrack::Clone メソッドは、トラックのコピーを作成する。

HRESULT Clone(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  IDirectMusicTrack** ppTrack
 );

パラメータ

mtStart
複製開始パート。0 以上、かつトラックの長さ未満の値とすべきである。
mtEnd
複製終了パート。mtStart より大きく、トラックの長さ未満の値とすべきである。
ppTrack
メソッドが成功した場合は、作成されたトラックへのポインタを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

アプリケーションは、トラックの終了時に Release を呼び出さなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTrack::EndPlay

最初に IDirectMusicTrack::InitPlay を呼び出したオブジェクトを削除するときに、IDirectMusicTrack::EndPlay メソッドが呼び出される。

HRESULT EndPlay(
  void * pStateData
);

パラメータ

pStateData
IDirectMusicTrack::InitPlay が返した状態データ。このデータは EndPlay メソッドで解放しなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば E_POINTER を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTrack::GetParam

IDirectMusicTrack::GetParam メソッドは、トラックからデータを取り出す。

HRESULT GetParam(
  REFGUID rguidType,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

パラメータ

rguidType
取得されるデータ タイプの識別子への参照 (C++) またはアドレス (C)。「トラック パラメータのタイプ」を参照すること。
mtTime
データを取得するタイム。トラック時間で指定する。
pmtNext
データが有効になるタイムを受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、pmtNext を NULL に設定してもよい。
pParam
返されるデータの保存用に割り当てられた構造体のアドレス。返されるデータの保存用に割り当てられた構造体のアドレス。この構造体は、rguidType で識別されたデータ タイプにとって適切な種類とサイズを備えていなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_FOUND
DMUS_E_NOT_INIT
DMUS_E_TYPE_DISABLED
DMUS_E_GET_UNSUPPORTED
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicTrack::SetParam、IDirectMusicTrack::IsParamSupported、IDirectMusicPerformance::GetParam、IDirectMusicSegment::GetParam、ミュージック パラメータ


IDirectMusicTrack::Init

IDirectMusicTrack::Init メソッドは、トラックを追加し、必要な初期化を行うときにセグメントによって呼び出される。

HRESULT Init(
  IDirectMusicSegment* pSegment
);

パラメータ

pSegment
このトラックが所属するセグメント。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

注意

トラックがメッセージを演奏する場合、Init メソッド内で IDirectMusicSegment::SetPChannelsUsed を呼び出すべきである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTrack::InitPlay

IDirectMusicTrack::InitPlay メソッドは、トラックが演奏を開始する準備ができたときに呼び出される。状態データへのポインタを返すが、このポインタは IDirectMusicTrack::Play と IDirectMusicTrack::EndPlay に渡される。

HRESULT InitPlay(
  IDirectMusicSegmentState* pSegmentState,
  IDirectMusicPerformance* pPerformance,
  void** ppStateData,
  DWORD dwVirtualTrackID,
  DWORD dwFlags
);

パラメータ

pSegmentState
呼び出し中の IDirectMusicSegmentState インターフェイスのアドレス。
pPerformance
呼び出し中の IDirectMusicPerformance インターフェイスのアドレス。
ppStateData
状態情報へのポインタを受け取るための変数のアドレス。データのフォーマットと使用方法は、トラックに固有である。データは InitPlay メソッドで作成し、IDirectMusicTrack::EndPlay メソッドで解放しなければならない。ポインタは IDirectMusicTrack::Play メソッドに渡される。
dwVirtualTrackID
このトラックインスタンスに割り当てられた仮想トラック ID。
dwFlags
トラックの動作を制御する DMUS_SEGF_FLAGS。「注意」を参照すること。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

注意

トラックは pSegmentState、pPerformance、および dwTrackID の各パラメータを保存する必要がある。これらは IDirectMusicTrack::Play にも渡されるためである。

dwFlags パラメータは、IDirectMusicPerformance::PlaySegment の呼び出しでパフォーマンスに渡されたフラグを渡す。トラックは、DMUS_SEGF_CONTROL と DMUS_SEGF_SECONDARY の各フラグに基づいて、その実行方法を決定する。たとえば、テンポ トラックは、それ自体がプライマリ セグメントまたはセカンダリ制御セグメント のパートである場合に限り、テンポの変更を自動的に演奏する (DMUS_SEGF_SECONDARY が設定されていない、または DMUS_SEGF_CONTROL がセットされている)。

トラックは ppStateData で NULL を返す場合がある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTrack::IsParamSupported

IDirectMusicTrack::IsParamSupported メソッドは、IDirectMusicTrack::GetParam と IDirectMusicTrack::SetParam の各メソッドで指定されたデータ タイプをサポートしているかどうかを判断する。

HRESULT IsParamSupported(
  REFGUID rguidType
);

パラメータ

rguidType
データ タイプの識別子への参照 (C++) またはアドレス (C)。「トラック パラメータのタイプ」を参照すること。

戻り値

メソッドが成功し、タイプがサポートされていれば S_OK、

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_TYPE_DISABLED
DMUS_E_TYPE_UNSUPPORTED
E_POINTER
E_NOTIMPL

注意

SetParam メソッドのいずれかを使うことによってメッセージ タイプが無効になっている場合 (「メッセージの無効化と有効化」を参照)、IDirectMusicTrack::IsParamSupported メソッドは、対応するパラメータ タイプ (GUID_TempoParam または GUID_TimeSignature) を渡されたときに DMUS_E_TYPE_DISABLED を返す。

このメソッドは、GUID_DisableTempo を渡され、そのメッセージ タイプが既に無効になっている場合、または GUID_EnableTempo を渡され、そのメッセージ タイプが現在有効になっている場合にも、DMUS_E_TYPE_DISABLED を返す。このことは、GUID_DisableTimeSig と GUID_EnableTimeSig にも当てはまる。

GUID_EnableTempo、GUID_EnableTimeSig、GUID_DisableTempo、または GUID_DisableTimeSig の各パラメータ タイプによって参照されるメッセージ タイプをトラックがサポートしない場合、このメソッドは DMUS_E_TYPE_UNSUPPORTED を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam、ミュージック パラメータ


IDirectMusicTrack::Play

IDirectMusicTrack::Play メソッドは、トラックを演奏する。このメソッドは、メッセージの作成と送信など、セグメントの演奏時にトラックが行う必要のある任意の操作を実行する。

HRESULT Play(
  void* pStateData,
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  MUSIC_TIME mtOffset
  DWORD dwFlags,
  IDirectMusicPerformance* pPerf,
  IDirectMusicSegmentState* pSegSt,
  DWORD dwVirtualID
);

パラメータ

pStateData
IDirectMusicTrack::InitPlay メソッドが返した状態データ。データのフォーマットと使用方法は、トラックに固有である。
mtStart
開始タイム。
mtEnd
終了タイム。
mtOffset
IDirectMusicPerformance::SendPMsg に渡されるすべてのメッセージに追加されるオフセット。
dwFlags
この呼び出しの状態を示すフラグ。DMUS_TRACKF_FLAGS を参照すること。値 0 は、Play の呼び出しによって、再生が前の呼び出しから継続されることを意味する。
pPerf
メッセージの割り当てと送信に使われるパフォーマンス。
pSegSt
このトラックが所属するセグメント状態。IDirectMusicSegmentState::QueryInterface メソッドを呼び出して、IDirectMusicGraph インターフェイスを取得することもできる。たとえば IDirectMusicGraph::StampPMsg を呼び出す場合である。
dwVirtualID
トラックの仮想識別子。IDirectMusicPerformance::SendPMsg から渡されるすべてのメッセージの dwVirtualTrackID メンバ (DMUS_PMSG を参照) にこの値を書き込まなければならない。

戻り値

成功すれば S_OK または DMUS_S_END を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_NOT_INIT
E_POINTER

注意

トラックが空の場合、このメソッドは DMUS_S_END を返す。

トラックは、優先順位が中低度のスレッド内にメッセージを生成する。ファイルのデータをストリーム化するコードなど、時間のかかる関数を、トラックの Play メソッド内から呼び出すことができる。ただし、安全なマルチスレッド化のためのガイドラインに従うこと。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


IDirectMusicTrack::RemoveNotificationType

IDirectMusicTrack::RemoveNotificationType メソッドは、トラックからイベント通知を削除する。IDirectMusicSegment::RemoveNotificationType に似ていて、このメソッドから呼び出される。

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
削除される通知タイプの識別子への参照 (C++) またはアドレス (C)。定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること。

戻り値

成功すれば S_OK を返す。トラックが通知タイプをサポートしない場合は S_FALSE を返す。

トラックが通知をサポートしない場合は、E_NOTIMPL を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicTrack::AddNotificationType、通知とイベントの処理


IDirectMusicTrack::SetParam

IDirectMusicTrack::SetParam メソッドは、トラックにデータを設定する。

HRESULT SetParam(
  REFGUID rguidType,
  MUSIC_TIME mtTime,
  void* pParam
);

パラメータ

rguidType
設定されるデータ タイプの識別子への参照 (C++) またはアドレス (C)。「トラック パラメータのタイプ」を参照すること。
mtTime
データを設定するタイム。トラック時間で指定する。
pParam
データを保持する構造体のアドレス。データが必要ない場合は NULL を指定する。この構造体は、rguidType で識別されたデータ タイプにとって適切な種類とサイズを備えていなければならない。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TYPE_DISABLED
E_OUTOFMEMORY
E_POINTER

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicTrack::GetParam、IDirectMusicTrack::IsParamSupported、IDirectMusicPerformance::SetParam、IDirectMusicSegment::SetParam、トラック パラメータの設定と取り出し


IKsControl

IKsControl インターフェイスは、プロパティ、イベント、およびメソッドのサポートを取得、設定、または問い合わせるために使われる。このインターフェイスは、Windows ドライバ モデル カーネル ストリーミング アーキテクチャの一部であるが、DirectMusic によっても使用され、DirectMusic ポートのプロパティを公開する。このインターフェイスを取り出すには、riid パラメータに IID_IKsControl を指定して IDirectMusicPort::QueryInterface メソッドを呼び出す。

プロパティ項目の要求をポートに対して送信する作業は、ポートの実装に依存する。Win32 ハンドルベースのマルチメディア呼び出し (midiOut と midiIn の各関数) を利用して DirectMusic のエミュレーションを行っているポートは、どのプロパティをもサポートしない。

プラグ可能なソフトウェア シンセサイザを表すポートに対してプロパティ項目を要求すると、完全にユーザー モードで応答がなされる。このタイプのポートのトポロジは、シンク ノード (IDirectMusicSynthSink インターフェイス) に接続されたシンセサイザ (IDirectMusicSynth インターフェイスによって表される) である。このプロパティ要求は最初にシンセサイザ ノードに割り当てられ、シンセサイザがこの要求を認識しない場合はシンク ノードに割り当てられる。

このインターフェイスは、以下のメソッドをサポートする。現在のところ、KsProperty だけが DirectMusic によってサポートされている。

IKsControl | KsProperty
 | KsEvent
 | KsMethod

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmksctrl.h で宣言。

参照

ポートのプロパティ セット


IKsControl::KsProperty

IKsControl::KsProperty メソッドは、プロパティの値を取得または設定する。概要については、「ポートのプロパティ セット」を参照すること。

HRESULT KsProperty(
  PKSPROPERTY pProperty,
  ULONG ulPropertyLength,
  LPVOID pvPropertyData,
  ULONG ulDataLength,
  PULONG pulBytesReturned
);

パラメータ

pProperty
プロパティ セット、項目、実行する操作を提供する KSPROPERTY 構造体のアドレス。このプロパティにインスタンス データが含まれる場合、そのデータはメモリ内で構造体のすぐ後に置かれていなければならない。
ulPropertyLength
pProperty が指すメモリの長さ。任意のインスタンス データも含む。
pvPropertyData
設定操作の場合、プロパティの新しい値を表すデータを含むメモリ バッファのアドレス。取得操作の場合、プロパティの値を十分に保持できるメモリのアドレス。基本的なサポート問い合わせの場合、サイズが最低でも DWORD のバッファのアドレス。
ulDataLength
pvPropertyData が指すバッファの長さ。
pulBytesReturned
KSPROPERTY_TYPE_GET または KSPROPERTY_TYPE_BASICSUPPORT の呼び出しで、ポートによって pvPropertyData に返されるバイト数を受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY
E_POINTER
DMUS_E_UNKNOWN_PROPERTY

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmksctrl.h で宣言。

参照

ポートのプロパティ セット


IReferenceClock

IReferenceClock インターフェイスは、システム基準タイムを表す。DirectMusic マスタ クロックとポートの遅延時間クロックは、このインターフェイスを実装する。

このインターフェイスは、以下のメソッドをサポートする。

IReferenceClock | GetTime
 | AdviseTime
 | AdvisePeriodic
 | Unadvise

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic::GetMasterClock、IDirectMusicPort::GetLatencyClock、タイミング


IReferenceClock::AdvisePeriodic

IReferenceClock::AdvisePeriodic メソッドは、持続時間が経過した、非同期の期間通知を要求する。

HRESULT AdvisePeriodic(
  REFERENCE_TIME rtStartTime,
  REFERENCE_TIME rtPeriodTime,
  HSEMAPHORE hSemaphore,
  DWORD * pdwAdviseCookie
);

パラメータ

rtStartTime
通知が開始されるタイム。
rtPeriodTime
通知が行われる間隔。
hSemaphore
アドバイスを行うための手段となるセマフォのハンドル。
pdwAdviseCookie
要求の識別子を受け取る変数のアドレス。これを使って、将来、要求をキャンセルする場合などに、AdvisePeriodic の呼び出しを識別する。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

注意

rtStartTime によって示されるタイムに達した場合、ハンドルが hSemaphore として設定されているセマフォが解放される。それ以降、セマフォは rtPeriodTime の期間を使って反復的に解放される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IReferenceClock::Unadvise


IReferenceClock::AdviseTime

IReferenceClock::AdviseTime メソッドは、タイムが経過した非同期通知を要求する。

HRESULT AdviseTime(
  REFERENCE_TIME rtBaseTime,
  REFERENCE_TIME rtStreamTime,
  HEVENT hEvent,
  DWORD * pdwAdviseCookie
);

パラメータ

rtBaseTime
基本となる基準タイム。
rtStreamTime
ストリーム オフセット タイム。
hEvent
アドバイスを行うための手段となるイベントのハンドル。
pdwAdviseCookie
要求の識別子を受け取る変数のアドレス。これを使って、将来、要求をキャンセルする場合などに、AdviseTime の呼び出しを識別する。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

注意

rtBaseTime と rtStreamTime を足したタイムに達すると、ハンドルが hEvent のイベントが設定される。タイムが既に経過している場合、イベントは即座に設定される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

IReferenceClock::Unadvise


IDirectMusicPerformance::GetTime

Platform SDK: DirectX

IReferenceClock::GetTime

IReferenceClock::GetTime メソッドは、現在タイムを取り出す。

HRESULT GetTime(
  REFERENCE_TIME * pTime
);

パラメータ

pTime
現在タイムを受け取る変数のアドレス。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


IReferenceClock::Unadvise

IReferenceClock::Unadvise メソッドは、通知の要求をキャンセルする。

HRESULT Unadvise(
  DWORD dwAdviseCookie
);

パラメータ

dwAdviseCookie
IReferenceClock::AdviseTime または IReferenceClock::AdvisePeriodic の各メソッドで設定されている、キャンセルする要求の識別子。

戻り値

戻り値は実装によって決まる。成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


DMUS_PMSG

DMUS_PMSG 構造体は、すべての DirectMusic メッセージに共通する情報によって構成されている。しかし、C は継承をサポートしていないので、次のシンタックスに展開される DMUS_PMSG_PART マクロを含めることにより、この構造体のメンバは (DMUS_PMSG 自体を含め) すべてのメッセージ タイプに含まれる。

typedef struct DMUS_PMSG {
    DWORD              dwSize;
    REFERENCE_TIME     rtTime;
    MUSIC_TIME         mtTime;
    DWORD              dwFlags;
    DWORD              dwPChannel;
    DWORD              dwVirtualTrackID;
    IDirectMusicTool*  pTool;
    IDirectMusicGraph* pGraph;
    DWORD              dwType;
    DWORD              dwVoiceID;
    DWORD              dwGroupID;
    IUnknown*          punkUser;
} DMUS_PMSG;
dwSize
構造体のサイズ。バイト単位で指定する。このメンバは、IDirectMusicPerformance::AllocPMsg によって初期化される。
rtTime
メッセージの演奏を開始する基準タイム。dwFlags により変更される。DMUS_PMSGF_REFTIME が dwFlags 内にある場合だけ使われる。
mtTime
メッセージの演奏を開始するミュージック タイム。dwFlags によって変更される。DMUS_PMSGF_MUSICTIME が dwFlags 内にある場合だけ使われる。
dwFlags
さまざまなビット (「DMUS_PMSGF_FLAGS」と「DMUS_TIME_RESOLVE_FLAGS」を参照)。DMUS_PMSGF_REFTIME または DMUS_PMSGF_MUSICTIME を保持していなければならない。
dwPChannel
パフォーマンス チャンネル (P チャンネル)。ポート、チャンネル グループ、および MIDI チャンネルは、IDirectMusicPerformance::PChannelInfo メソッドを使うことによって、この値から取り出せる。テンポ メッセージなど、チャンネル固有ではないメッセージについては、この値を 0 に設定する。
dwVirtualTrackID
トラックの識別子。メッセージがトラックによって送信されていない場合、0 に設定する。
pTool
ツール インターフェイスのアドレス。IDirectMusicGraph::StampPMsg を使って設定できる。メッセージが出力ツール以外のツールに送られない場合は NULL に設定できる。
pGraph
ツール グラフ インターフェイスのアドレス。IDirectMusicGraph::StampPMsg を使って設定できる。メッセージが出力ツール以外のツールに送られない場合は NULL に設定できる。
dwType
メッセージ タイプ (DMUS_PMSGT_TYPES を参照 )。
dwVoiceID
将来の使用に備えて予約されている。0 を設定しなければならない。
dwGroupID
メッセージがトラックによって生成されている場合、そのメッセージが所属するトラック グループまたはグループの識別子(トラックは、IDirectMusicSegment::InsertTrack メソッドでグループに割り当てられる)。ほとんどの目的について、この値は 0xFFFFFFF でもよい。
punkUser
アプリケーションによって提供される IUnknown インターフェイスのアドレス。このポインタは、メッセージを解放したときに常に解放される。アプリケーションがオブジェクトを保持したい場合は、メッセージを解放する前に、AddRef を呼び出さなければならない。メッセージが COM ポインタを必要としない場合、この値は NULL でもよい。

注意

DMUS_PMSG 構造体は、dwType メンバに以下の値を持つメッセージについて、それ自体によって使われる。

DMUS_PMSGT_STOP
このタイプのメッセージを送信すると、指定されたタイムにパフォーマンスが停止する。
DMUS_PMSGT_DIRTY
制御セグメントが開始または終了するとき、セグメントおよびパフォーマンス グラフ内のすべてのツールは、このタイプのメッセージを受け取る。これは、セグメント内のすべてのツールとパフォーマンス グラフが GetParam の呼び出しでデータをキャッシングする場合、GetParam を再度呼び出して、それぞれのデータをリフレッシュしなければならないことを意味する。このメッセージ タイプが必要なツールは、IDirectMusicTool::GetMediaTypes の呼び出しでこれを指定しなければならない。パフォーマンス グラフ内のツールは、パフォーマンス内の各セグメントについて、メッセージのコピーを 1 部だけ受け取る。このようなツールは、同じタイム スタンプの付いた余分なメッセージを無視しても安全である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SendPMsg


DMUS_CHANNEL_PRIORITY_PMSG

DMUS_CHANNEL_PRIORITY_PMSG メッセージ構造体は、チャンネル優先順位チェンジに関するデータによって構成されている。

typedef struct _DMUS_CHANNEL_PRIORITY_PMSG {
    DMUS_PMSG_PART
    DWORD dwChannelPriority;
} DMUS_CHANNEL_PRIORITY_PMSG;
DMUS_PMSG_PART
共通のメッセージメンバに展開されるマクロ。DMUS_PMSG を参照すること。
dwChannelPriority
チャンネルの優先順位。定義済みの値のリストについては、「IDirectMusicPort::GetChannelPriority」の「注意」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPort::SetChannelPriority、IDirectMusicPerformance::SendPMsg


DMUS_CURVE_PMSG

DMUS_CURVE_PMSG 構造体は、曲線 (たとえばコンティニュアス コントローラ イベントのシーケンス) を表すメッセージ構造体である。

typedef struct DMUS_CURVE_PMSG {
    DMUS_PMSG_PART
    MUSIC_TIME mtDuration;
    MUSIC_TIME mtOriginalStart;
    MUSIC_TIME mtResetDuration;
    short      nStartValue;
    short      nEndValue;
    short      nResetValue;
    WORD       wMeasure;
    short      nOffset;
    BYTE       bBeat;
    BYTE       bGrid;
    BYTE       bType;
    BYTE       bCurveShape;
    BYTE       bCCData;
    BYTE       bFlags;
} DMUS_CURVE_PMSG;
DMUS_PMSG_PART
共通のメッセージメンバに展開されるマクロ。DMUS_PMSG を参照すること。
mtDuration
曲線の持続時間。
mtOriginalStart
オリジナルの開始タイム。メッセージを作成するときは 0 または曲線のオリジナルの開始タイムに設定しなければならない。
mtResetDuration
曲線が終了した後、リセット値を設定するまでの時間。bFlags 内に DMUS_CURVE_RESET がない場合は無視される。
nStartValue
曲線の開始値。
nEndValue
曲線の終了値。
nResetValue
曲線のリセット値。mtResetDuration の経過後、またはフラッシュ (解放) や無効化の際に設定される。bFlags 内に DMUS_CURVE_RESET がない場合は無視される。
wMeasure
曲線が発生する小節。
nOffset
曲線が発生するグリッドからのオフセット。ミュージック タイムで表される。
bBeat
この曲線が発生する (小節内の) 拍数。
bGrid
この曲線が発生する拍からのグリッド オフセット。
bType
曲線のタイプ。次の値のいずれかを使う。
DMUS_CURVET_CCCURVE
コンティニュアス コントローラ曲線 (MIDI コントロール チェンジのチャンネル発音メッセージ。ステータス バイトは &HBn。n はチャンネル番号を表す)。
DMUS_CURVET_MATCURVE
モノフォニック アフタータッチ曲線 (MIDI Channel Pressure チャンネル発音メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PATCURVE
ポリフォニック アフタータッチ曲線 (MIDI Poly Key Pressure チャンネル発音メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PBCURVE
ピッチ ベンド曲線 (MIDI Pitch Bend チャンネル発音メッセージ。ステータス バイトは &HEn)。
bCurveShape
曲線のシェイプ。次の値のいずれかを使う。
DMUS_CURVES_EXP
指数曲線シェイプ。
DMUS_CURVES_INSTANT
即時曲線シェイプ (曲線の開始と終了がほとんど同時に発生する)。
DMUS_CURVES_LINEAR
線形曲線シェイプ。
DMUS_CURVES_LOG
対数曲線シェイプ。
DMUS_CURVES_SINE
正弦曲線シェイプ。
bCCData
コントロール チェンジ タイプの場合は、CC 番号を指定する。
bFlags
デフォルトのタイムに達したとき、または移行部が原因で無効化が発生したときに nResetValue を設定しなければならない場合は、この値を DMUS_CURVE_RESET に設定する。この値を 0 に設定した場合は、曲線は新しい値に永続的にとどまる。他のすべてのビットは予約されている。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SendPMsg


DMUS_MIDI_PMSG

DMUS_MIDI_PMSG 構造体は、コントロール チェンジやピッチ ベンドなど、別のメッセージ タイプによって表されないスタンダード MIDI メッセージのデータによって構成されている。

typedef struct DMUS_MIDI_PMSGG {
    DMUS_PMSG_PART
    BYTE  bStatus;
    BYTE  bByte1;
    BYTE  bByte2;
    BYTE  bPad[1];
} DMUS_MIDI_PMSG;
DMUS_PMSG_PART
共通のメッセージメンバに展開されるマクロ。DMUS_PMSG を参照すること。
bStatus
スタンダード MIDI のステータスバイト。
bByte1
MIDI メッセージの最初の 1 バイト。これを必要としない MIDI メッセージでは無視される。
bByte2
MIDI メッセージの 2 バイト目。これを必要としない MIDI メッセージでは無視される。
bPad
WORD 境界までの追加。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

MIDI メッセージ、IDirectMusicPerformance::SendPMsg


DMUS_NOTE_PMSG

DMUS_NOTE_PMSG 構造体は、音楽の音符イベント用のデータによって構成されている。

typedef struct DMUS_NOTE_PMSG {
    DMUS_PMSG_PART
    MUSIC_TIME mtDuration;
    WORD       wMusicValue;
    WORD       wMeasure;
    short      nOffset;
    BYTE       bBeat;
    BYTE       bGrid;
    BYTE       bVelocity;
    BYTE       bFlags;
    BYTE       bTimeRange;
    BYTE       bDurRange;
    BYTE       bVelRange;
    BYTE       bPlayModeFlags;
    BYTE       bSubChordLevel;
    BYTE       bMidiValue;
} DMUS_NOTE_PMSG;
DMUS_PMSG_PART
共通のメッセージメンバに展開されるマクロ。DMUS_PMSG を参照すること。
mtDuration
音符の持続時間。
wMusicValue
音符の記述。ほとんどの演奏モードでは、以下に示すように、パックされた 4 ビット値の配列である。
オクターブ
-2 ～ 14 の範囲。この音符は、1 オクターブの 12 倍で上下に転調される。
コード位置
0 ～ 15 の範囲だが、3 を超えてはならない。コード内の最初の位置は 0 である。
スケール位置
0 ～ 15 の範囲。通常は 0 ～ 2 の範囲だが、1 音符のコードにし、コードの上のすべてをスケール位置として解釈することも可能。
変化音
-8 ～ 7 の範囲だが、通常は -2 ～ 2 の範囲。これは、スケールから音符を取り出すオフセットを表す。

固定演奏モードでは、ミュージック値は 0 ～ 127 の範囲にある MIDI 音符の値である。

wMeasure
音符が発生する小節。
nOffset
音符が発生するグリッドからのオフセット。ミュージック タイムで表される。
bBeat
この音符が発生する (小節内での ) 拍。
bGrid
この音符が発生する拍からのグリッド オフセット。
bVelocity
音符のベロシティ 。
bFlags
DMUS_NOTEF_FLAGS を参照すること。
bTimeRange
ランダム時間の範囲。
bDurRange
持続時間をランダム化する範囲。
bVelRange
ベロシティをランダム化する範囲。
bPlayModeFlags
ミュージック値がコードとサブコードにどのように関連するかを決定する演奏モード。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bSubChordLevel
音符が使うサブコード レベル。「DMUS_SUBCHORD」を参照すること。
bMidiValue
wMusicValue から変換された、MIDI 音符の値。

注意

音符を演奏するとき、DMUS_NOTE_PMSG はグラフ、グラフ内のあらゆるツールを経由して、最終的な MIDI 出力ツールに到達する。bFlags メンバが DMUS_NOTEF_NOTEON に設定されていることをツールが認識すると、ツールは MIDI ノートオン メッセージを (DMUS_PMSG パートの dwPChannel メンバに従って) 適切なポートに送信する。次にこのフラグを消去し、タイム スタンプに mtDuration を加え、メッセージを要求する。その結果、適切なタイムに音符は終了する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SendPMsg、ミュージック値と MIDI 音符


DMUS_NOTIFICATION_PMSG

DMUS_NOTIFICATION_PMSG 構造体は、DMUS_PMSG から派生したもので、通知を表す。

typedef struct DMUS_NOTIFICATION_PMSG {
    DMUS_PMSG_PART
    GUID   guidNotificationType;
    DWORD  dwNotificationOption;
    DWORD  dwField1;
    DWORD  dwField2;
} DMUS_NOTIFICATION_PMSG;
DMUS_PMSG_PART
共通のメッセージメンバに展開されるマクロ。DMUS_PMSG を参照すること。
guidNotificationType
通知タイプの識別子。次のタイプが定義されている。
GUID_NOTIFICATION_CHORD
コード チェンジ。
GUID_NOTIFICATION_COMMAND
コマンド イベント。
GUID_NOTIFICATION_MEASUREANDBEAT
小節および拍イベント。
GUID_NOTIFICATION_PERFORMANCE
パフォーマンス イベント。dwNotificationOption でさらに定義される。
GUID_NOTIFICATION_SEGMENT
セグメント イベント。dwNotificationOption でさらに定義される。
dwNotificationOption
通知サブタイプの識別子。

通知タイプが GUID_NOTIFICATION_SEGMENT の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_SEGABORT
セグメントが IDirectMusicPerformance::Stop によって停止された。
DMUS_NOTIFICATION_SEGALMOSTEND
セグメントが終了タイムから準備時間を引いたタイムに達した。
DMUS_NOTIFICATION_SEGEND
セグメントが終了した。
DMUS_NOTIFICATION_SEGLOOP
セグメントがループした。
DMUS_NOTIFICATION_SEGSTART
セグメントが開始した。

通知タイプが GUID_NOTIFICATION_COMMAND の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_GROOVE
グルーブ チェンジ。
DMUS_NOTIFICATION_EMBELLISHMENT
装飾コマンド (イントロ、フィル、ブレーク、またはエンド)。

通知タイプが GUID_NOTIFICATION_PERFORMANCE の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_MUSICSTARTED
再生が開始した。
DMUS_NOTIFICATION_MUSICSTOPPED
再生が停止した。

通知タイプが GUID_NOTIFICATION_MEASUREANDBEAT の場合、このメンバは DMUS_NOTIFICATION_MEASUREBEAT を保持する。その他のサブタイプは定義されない。

通知タイプが GUID_NOTIFICATION_CHORD の場合、このメンバは DMUS_NOTIFICATION_CHORD を保持する。その他のサブタイプは定義されない。

dwField1
通知タイプに固有の追加データ。GUID_NOTIFICATION_MEASUREANDBEAT 通知の場合、このメンバは小節内の拍番号を返す。
dwField2
通知タイプに固有の追加データ。将来の使用またはアプリケーションによって定義される使用に備えて予約されている。

注意

ほとんどの通知について、punkUser メンバ (「DMUS_PMSG」を参照) は、セグメント状態の IUnknown ポインタを保持する。これは、コードおよびコマンドの取得に使用すると非常に便利である。その場合、IDirectMusicSegmentState インターフェイスのクエリを行い、IDirectMusicSegmentState::GetSegment を呼び出して IDirectMusicSegment ポインタを取得する。次に、IDirectMusicSegment::GetParam メソッドを呼び出して、通知メッセージの mtTime メンバで指定されたタイムにコードまたはコマンドを取得する。

GUID_NOTIFICATION_PERFORMANCE タイプの通知の場合、punkUser メンバは常に NULL である。

アプリケーションは独自の通知メッセージ タイプおよびサブタイプを定義でき、余分なデータについては dwField1 と dwField2 を使用できる。そのようなカスタム通知メッセージは、その他のメッセージと同様に、割り当ておよび送信できる。アプリケーションによって定義されたトラックは、GUID (guidNotificationType) が IDirectMusicTrack::AddNotificationType に渡された後に、特定タイプのメッセージを送信できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理、IDirectMusicPerformance::SendPMsg


DMUS_PATCH_PMSG

DMUS_PATCH_PMSG 構造体は、プログラム チェンジ メッセージ用のデータによって構成されている。

typedef struct DMUS_PATCH_PMSG {
    DMUS_PMSG_PART
    BYTE  byInstrument;
    BYTE  byMSB;
    BYTE  byLSB;
    BYTE  byPad[1];
} DMUS_PATCH_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。DMUS_PMSG を参照すること。
byInstrument
音色のパッチ番号。
byMSB
バンク セレクトの上位バイト。
byLSB
バンク セレクトの下位バイト。
byPad
WORD 境界までの追加。この値は無視される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

DMUS_MIDI_PMSG、IDirectMusicPerformance::SendPMsg、MIDI メッセージ


DMUS_SYSEX_PMSG

DMUS_SYSEX_PMSG 構造体は DMUS_PMSG から派生したもので、MIDI システム エクスクルーシブ メッセージを表す。

typedef struct DMUS_SYSEX_PMSG {
    DMUS_PMSG_PART
    DWORD dwLen;
    BYTE  abData[1];
} DMUS_SYSEX_PMSG;
DMUS_PMSG_PART
共通のメッセージメンバに展開されるマクロ。DMUS_PMSG を参照すること。
dwLen
データの長さ。バイト単位で指定する。
abData
データ配列。メモリの割り当て方法およびデータをこのメンバにコピーする方法の例については、「IDirectMusicPerformance::SendPMsg」の「注意」を参照すること。

注意

システム エクスクルーシブ メッセージのデータ部分は、システム エクスクルーシブ識別子 (0xF0) で始まり、EOX (0xF7) で終わらなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

DMUS_MIDI_PMSG、DMUS_PATCH_PMSG、MIDI メッセージ、IDirectMusicPerformance::SendPMsg


DMUS_TEMPO_PMSG

DMUS_TEMPO_PMSG 構造体は、パフォーマンスのテンポを制御するメッセージ用のデータによって構成されている。

typedef struct DMUS_TEMPO_PMSG {
    DMUS_PMSG_PART
    double dblTempo;
} DMUS_TEMPO_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。DMUS_PMSG を参照すること。
dblTempo
DMUS_TEMPO_MIN ～ DMUS_TEMPO_MAX の範囲にあるテンポ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SendPMsg


DMUS_TIMESIG_PMSG

DMUS_TIMESIG_PMSG 構造体は、パフォーマンスの拍子記号を制御するメッセージ用のデータによって構成されている。

typedef struct _DMUS_TIMESIG_PMSG {
    DMUS_PMSG_PART
    BYTE bBeatsPerMeasure;
    BYTE bBeat;
    WORD wGridsPerBeat;
} DMUS_TIMESIG_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。DMUS_PMSG を参照すること。
bBeatsPerMeasure
小節あたりの拍数 (拍子記号の分子 )。
bBeat
拍を受け取る音符 (拍子記号の分母)。この値が 1 のときは全音符、2 のときは 2 分音符、4 のときは 4 分音符を意味する。以下同様である。0 は 256 分音符を意味する。
wGridsPerBeat
拍あたりのグリッド (小分割 )。この値は、特定の音楽イベントのタイミング分解能を決定する。たとえば、DMUS_SEGF_GRID フラグを使ったセグメントの挿入が挙げられる (DMUS_SEGF_FLAGS を参照)。

注意

拍子記号メッセージは、拍子記号トラックとスタイル トラックによって生成される。通常、セグメントには、拍子記号トラックまたはスタイル トラックのどちらかが含まれるが、両方含まれることはない。MIDI ファイルを表すセグメントには拍子記号トラックが含まれるが、DirectMusic Producer などのツールを使ってオーサリングされたセグメントのほとんどには、スタイル トラックに拍子記号情報が含まれる。

デフォルトでは、プライマリ セグメントだけが拍子記号メッセージを送信する。この動作を変更する方法については、「メッセージの無効化と有効化」を参照すること。

拍子記号はパフォーマンスによって使われ、DMUS_SEGF_FLAGS または DMUS_TIME_RESOLVE_FLAGS でタイムを調整できるすべてのメソッドで、タイムを小節、拍、およびグリッドの境界に解決する。また、拍子記号トラックとスタイル トラックは、拍子記号を使って、小節境界および拍境界に対する通知を生成する。「DMUS_NOTIFICATION_PMSG」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SendPMsg、DMUS_TIMESIGNATURE


DMUS_TRANSPOSE_PMSG

DMUS_TRANSPOSE_PMSG 構造体は、転調を制御するメッセージ用のデータによって構成されている。

typedef struct _DMUS_TRANSPOSE_PMSG {
    DMUS_PMSG_PART
    short nTranspose;
} DMUS_TRANSPOSE_PMSG;
DMUS_PMSG_PART
共通のメッセージメンバに展開されるマクロ。DMUS_PMSG を参照すること。
nTranspose
転調される半音の数。負の値であってもよい。

注意

音符の転調によって、スタンダード MIDI の範囲 0 ～ 127 より外側に達した場合は、その音符は演奏されない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SendPMsg


DMUS_BUFFERDESC

DMUS_BUFFERDESC 構造体は、IDirectMusic::CreateMusicBuffer メソッドのバッファを記述するために使われる。

typedef struct _DMUS_BUFFERDESC {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidBufferFormat;
    DWORD cbBuffer;
} DMUS_BUFFERDESC, *LPDMUS_BUFFERDESC;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
フラグは定義されていない。
guidBufferFormat
バッファの KS フォーマットの識別子。値 GUID_NULL は、KSDATAFORMAT_SUBTYPE_DIRECTMUSIC を表す。

guidBufferFormat が KSDATAFORMAT_SUBTYPE_DIRECTMUSIC 以外の KS フォーマットを表す場合、アプリケーションは、データを再生しているポートが指定のフォーマットを理解しているかどうか検証しなければならない。そうしなかった場合、バッファは無視される。ポートが特定の KS フォーマットをサポートしているかどうか調べるには、IKsControl::KsProperty メソッドを使う。

cbBuffer
メッセージの最小サイズ (バイト単位)。システムがバッファを 4 バイトの倍数に追加するため、割り当てることのできるメモリ量はわずかに増える。1 つの MIDI チャンネル メッセージを格納するには、バッファは少なくとも 32 バイトなければならない。システム エクスクルーシブ メッセージまたはその他の非構造化データを格納するために、バッファは最低 28 バイトとデータ サイズを合わせたサイズでなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

DMUS_EVENTHEADER、IDirectMusicBuffer::PackStructured、IDirectMusicBuffer::PackUnstructured


DMUS_CHORD_KEY

DMUS_CHORD_KEY 構造体は、IDirectMusicPerformance::MIDIToMusic と IDirectMusicPerformance::MusicToMIDI の各メソッド内でコードを記述する場合に使われる。

typedef struct _DMUS_CHORD_KEY {
    WCHAR         wszName[16];
    WORD          wMeasure;
    BYTE          bBeat;
    BYTE          bSubChordCount;
    DMUS_SUBCHORD SubChordList[DMUS_MAXSUBCHORD];
    DWORD         dwScale;
    BYTE          bKey;
} DMUS_CHORD_KEY;

メンバ

wszName
コード名。
wMeasure
コードが所属する小節。
bBeat
コードが所属する拍。
bSubChordCount
コードのサブコードリスト内にあるコードの数。
SubChordList
コードを構成するコンポーネントを記述する、DMUS_SUBCHORD 構造体の配列。
dwScale
コード全体の基調となるスケール。
bKey
コード全体の基調となるキー。

注意

この構造体は、GUID_ChordParam トラック パラメータの設定と取り出しで使われる、DMUS_CHORD_PARAM 構造体としても定義される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam、ミュージック パラメータ


DMUS_CHORD_PARAM

DMUS_CHORD_PARAM 構造体は、トラックがコード トラックであり、rguidType が GUID_ChordParam である場合、GetParam と SetParam のさまざまなメソッドの呼び出しの際に pParam パラメータとして使われる。

typedef DMUS_CHORD_KEY DMUS_CHORD_PARAM;

「DMUS_CHORD_KEY」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam、ミュージック パラメータ


DMUS_CLOCKINFO

DMUS_CLOCKINFO 構造体は、IDirectMusic::EnumMasterClock メソッドを使って列挙されたクロックに関する情報を報告する。

typedef struct _DMUS_CLOCKINFO{
    DWORD           dwSize;
    DMUS_CLOCKTYPE  ctType;
    GUID            guidClock;
    WCHAR           wszDescription[DMUS_MAX_DESCRIPTION];
} DMUS_CLOCKINFO, *LPDMUS_CLOCKINFO;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体をメソッドに渡す前に、このメンバを sizeof(DMUS_CLOCKINFO) に初期化しなければならない。
ctType
クロックのタイプを指定する、DMUS_CLOCKTYPE 列挙型のメンバ。
guidClock
クロックの識別子。DirectMusic のマスタ クロックを設定するために、この値を IDirectMusic::SetMasterClock メソッドに渡してもよい。
wszDescription
クロックの記述。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_COMMAND_PARAM

DMUS_COMMAND_PARAM 構造体は、トラックがコマンド トラックであり、rguidType パラメータが GUID_CommandParam である場合、GetParam と SetParam のさまざまなメソッドの呼び出しの際に pParam パラメータとして使われる。

typedef struct {
    BYTE bCommand;
    BYTE bGrooveLevel;
    BYTE bGrooveRange;
} DMUS_COMMAND_PARAM;

メンバ

bCommand
コマンド タイプ。DMUS_COMMANDT_TYPESを参照すること。
bGrooveLevel
コマンドのグルーブ レベル。グルーブ レベルは、1 ～ 100 の範囲で指定する値である。
bGrooveRange
グルーブ レベルをランダム化できる量。たとえば、グルーブ レベルが 35 で範囲が 4 の場合、実際のグルーブ レベルは 33 から 37 のいずれかの値になる。現在は実装されていない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam


DMUS_COMMAND_PARAM2

DMUS_COMMAND_PARAM2 構造体は、トラックがコマンド トラックであり、rguidType パラメータが GUID_CommandParam2 である場合、GetParam と SetParam のさまざまなメソッドの呼び出しの際に pParam パラメータとして使われる。

typedef struct {
    MUSIC_TIME mtTime;
    BYTE bCommand;
    BYTE bGrooveLevel;
    BYTE bGrooveRange;
} DMUS_COMMAND_PARAM2;

メンバ

mtTime
コマンドのタイム。
bCommand
コマンド タイプ。DMUS_COMMANDT_TYPES を参照すること。
bGrooveLevel
コマンドのグルーブ レベル。グルーブ レベルは、1 ～ 100 の範囲で指定する値である。
bGrooveRange
グルーブ レベルをランダム化できる量。たとえば、グルーブ レベルが 35 で範囲が 4 の場合、実際のグルーブ レベルは 33 から 37 のいずれかの値になる。現在は実装されていない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam


DMUS_EVENTHEADER

DMUS_EVENTHEADER 構造体は、ポート バッファ内のイベントの前に置かれ、これを記述する。

typedef struct _DMUS_EVENTHEADER {
    DWORD           cbEvent;
    DWORD           dwChannelGroup;
    REFERENCE_TIME  rtDelta;
    DWORD           dwFlags;
} DMUS_EVENTHEADER, *LPDMUS_EVENTHEADER;

メンバ

cbEvent
イベント内のバイト数。
dwChannelGroup
イベントが所属するグループ。
rtDelta
バッファの開始タイムからのオフセット。
dwFlags
イベントが解析可能な MIDI データの場合、DMUS_EVENT_STRUCTURED に設定される。

注意

この構造体の宣言の前には Pshpack4.h ヘッダー ファイルがインクルードされている。これによって構造体の自動整列が無効になり、データはヘッダーのすぐ後に続く(詳細については、Pshpack4.h 内のコメントを参照)。次に Poppack.h がインクルードされ、整列が有効になる。構造体全体 (ヘッダーとイベント) が 8 バイト境界まで追加される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusbuff.h で宣言。

参照

IDirectMusicBuffer::GetNextEvent、IDirectMusicBuffer::PackStructured、IDirectMusicBuffer::PackUnstructured


DMUS_NOTERANGE

DMUS_NOTERANGE 構造体は、楽器が応答しなければならない音符範囲を指定する。この構造体の配列を IDirectMusicPerformance::DownloadInstrument と IDirectMusicPort::DownloadInstrument の各メソッドに渡して、音色がどの音符に応答すべきか、そのためにどの音色リージョンをダウンロードする必要があるかを指定する。

typedef struct _DMUS_NOTERANGE {
    DWORD dwLowNote;
    DWORD dwHighNote;
} DMUS_NOTERANGE, *LPDMUS_NOTERANGE;

メンバ

dwLowNote
音色が応答しなければならない MIDI 音符範囲の低い音。
dwHighNote
音色が応答しなければならない MIDI 音符範囲の高い音。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。


DMUS_MUTE_PARAM

DMUS_MUTE_PARAM 構造体は、トラックがミュート トラックであり、rguidType が GUID_MuteParam である場合、GetParam と SetParam のさまざまなメソッドの呼び出しの際に pParam パラメータとして使われる。

typedef struct _DMUS_MUTE_PARAM {
    DWORD  dwPChannel;
    DWORD  dwPChannelMap;
    BOOL   fMute;
} DMUS_MUTE_PARAM;

メンバ

dwPChannel
ミュートまたは再マップするパフォーマンス チャンネル。構造体が GetParam に渡されている場合、このメンバを初期化しなければならない。
dwPChannelMap
dwPChannel がマップされているチャンネル。fMute が TRUE の場合、このメンバは無視される。
fMute
dwPChannel がミュートされている場合は TRUE。

注意

P チャンネル 3 上のすべての音符を P チャンネル 9 上で演奏したい場合、この構造体を SetParam メソッドのいずれかに渡す前に、dwPChannel を 3 に設定し、dwPChannelMap を 9 に設定する。P チャンネル 8 上の音符をミュートしたい場合、dwPChannel を 8 に設定し、dwPChannelMap を 0xFFFFFFFF に設定する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam


DMUS_OBJECTDESC

DMUS_OBJECTDESC 構造体を使って、DirectMusic オブジェクトを記述する。この構造体を IDirectMusicLoader::GetObject メソッドに渡して、ローダーが記憶装置から取り出すべきオブジェクトを識別する。この構造体からオブジェクトに関する情報を取り出すには、IDirectMusicLoader::EnumObject と IDirectMusicObject::GetDescriptor の各メソッドを使う。

typedef struct _DMUS_OBJECTDESC {
    DWORD         dwSize;
    DWORD         dwValidData;
    GUID          guidObject;
    GUID          guidClass;
    FILETIME      ftDate;
    DMUS_VERSION  vVersion;
    WCHAR         wszName[DMUS_MAX_NAME];
    WCHAR         wszCategory[DMUS_MAX_CATEGORY];
    WCHAR         wszFileName[DMUS_MAX_FILENAME];
    LONGLONG      llMemLength;
    PBYTE         pbMemData;
} DMUS_OBJECTDESC, *LPDMUS_OBJECTDESC;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を任意のメソッドに渡す前に、このメンバを sizeof(DMUS_OBJECTDESC) に初期化しなければならない。
dwValidData
どのメンバが有効なのか記述し、いくつかのメンバに関する詳細な情報を提供するフラグ。次の値が定義されている。
DMUS_OBJ_OBJECT
guidObject メンバは有効である。
DMUS_OBJ_CLASS
guidClass メンバは有効である。
DMUS_OBJ_NAME
wszName メンバは有効である。
DMUS_OBJ_CATEGORY
wszCategory メンバは有効である。
DMUS_OBJ_FILENAME
wszFileName メンバは有効である。
DMUS_OBJ_FULLPATH
wszFileName メンバはフルパスを保持している。このフラグをセットした場合、ローダーは、DMUS_OBJ_FILENAME がセットされていなくても wszFileName が有効であると想定する。
DMUS_OBJ_MEMORY
オブジェクトはメモリ内にあり、llMemLength と pbMemData は有効である。
DMUS_OBJ_URL
wszFileName メンバは URL を保持している (DirectMusic ローダーは現在 URL をサポートしていない)。
DMUS_OBJ_VERSION
vVersion メンバは有効である。
DMUS_OBJ_DATE
ftDate メンバは有効である。
DMUS_OBJ_LOADED
オブジェクトは現在メモリ内にロードされている。
guidObject
このオブジェクトの一意の識別子。
guidClass
オブジェクト クラスの一意の識別子。すべての標準的なオブジェクトは、"CLSID_" とオブジェクト名で構成される定義済みの識別子を持っている。たとえば、セグメント オブジェクトは CLSID_DirectMusicSegment として識別される。Dmusici.h ヘッダー ファイル内の定義を参照すること。
ftDate
オブジェクトが最後に編集された日付。
vVersion
バージョン情報を保持する DMUS_VERSION 構造体。
wszName
オブジェクトの名前。
wszCategory
オブジェクトのカテゴリ。
wszFileName
ファイルのパス。DMUS_OBJ_FULLPATH が設定されている場合、この値はフル パスである。それ以外の場合、ファイル名だけである。
llMemLength
メモリ内のデータのサイズ。
pbMemData
メモリ内のデータ。

注意

IDirectMusicLoader::GetObject メソッドを使ってオブジェクトを取り出せるように、wszName、idGuid、および wszFileName の少なくとも 1 つに有効なデータを書き込まなければならない。

名前とカテゴリの文字列は、8 ビットの ANSI 文字ではなく、WCHAR フォーマットの 16 ビット文字を使う。必要に応じて変換を行うよう注意すること。C ライブラリの mbstowcs 関数を使って、マルチバイトから Unicode、wcstombs 関数を使って Unicode からマルチバイトへの変換も行える。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

DirectMusic ローダー


DMUS_PORTCAPS

DMUS_PORTCAPS 構造体は、IDirectMusic::EnumPort メソッドを呼び出したときに列挙されたポートに関する情報を受け取る。IDirectMusicPort::GetCaps メソッドを通して情報を返すときも、この構造体が使われる。

typedef struct _DMUS_PORTCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidPort;
    DWORD dwClass;
    DWORD dwType;
    DWORD dwMemorySize;
    DWORD dwMaxChannelGroups;
    DWORD dwMaxVoices;
    DWORD dwMaxAudioChannels;
    DWORD dwEffectFlags;
    WCHAR wszDescription[DMUS_MAX_DESCRIPTION];
} DMUS_PORTCAPS, *LPDMUS_PORTCAPS;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を任意のメソッドに渡す前に、このメンバを sizeof(DMUS_PORTCAPS) に初期化しなければならない。
dwFlags
ポートのさまざまな能力を記述するフラグ。このフィールドは、次の値のうち 1 つまたは複数で構成されていてもよい。
DMUS_PC_DIRECTSOUND
ポートは DirectSound に送るストリーミング ウェーブ データをサポートする。
DMUS_PC_DLS
ポートは DLS レベル 1 のサンプル コレクションをサポートする。
DMUS_PC_DLS2
ポートは DLS レベル 2 のサンプル コレクションをサポートする。
DMUS_PC_EXTERNAL
ポートはホストの外部にあるデバイスに接続されている。たとえば、MPU-401 のような外部 MIDI ポートを通してデバイスに接続されている。
DMUS_PC_GMINHARDWARE
シンセサイザは独自の GM 音色セットを持っている。そのため、GM 音色はダウンロードする必要がない。
DMUS_PC_GSINHARDWARE
このポートは、ハードウェア内に Roland GS サウンド セットを保持している。
DMUS_PC_MEMORYSIZEFIXED
DLS 楽器で利用できるメモリは調整できない。
DMUS_PC_SHAREABLE
デバイス上にあるチャンネル グループの同じ範囲を使うポートは複数作成できる。このビットをセットしない限り、ポートは排他モードでのみ開くことができる。排他モードでは、作成された要求への割り当てに利用できるチャンネル グループがない限り、ポートを作成する試みは失敗する。
DMUS_PC_SOFTWARESYNTH
ポートはソフトウェア シンセサイザである。
DMUS_PC_XGINHARDWARE
このポートは、ハードウェア内に Yamaha XG 拡張を保持している。
guidPort
ポートの識別子。ポートの IDirectMusicPort インターフェイスを取得するために、この値を IDirectMusic::CreatePort メソッドに渡してもよい。
dwClass
このポートのクラス。次のクラスが定義されている。
DMUS_PC_INPUTCLASS
入力ポート。
DMUS_PC_OUTPUTCLASS
出力ポート。
dwType
このポートのタイプ。次のタイプが定義されている。
DMUS_PORT_WINMM_DRIVER
Windows マルチメディア ドライバ。
DMUS_PORT_USER_MODE_SYNTH
ユーザーモード シンセサイザ。
DMUS_PORT_KERNEL_MODE
WDM ドライバ。
dwMemorySize
DLS 楽器の保存に利用できるメモリの量。ポートがシステム メモリを使っていて、利用可能なシステム メモリによりその量が制限を受ける場合、このフィールドは DMUS_PC_SYSTEMMEMORY を保持する。
dwMaxChannelGroups
このポートがサポートするチャンネル グループの最大数。1 つのチャンネル グループは、16 個の MIDI チャンネルからなるセットである。
dwMaxVoices
このポートを開いたときに割り当てのできる発音の最大数。このパラメータが返されることをドライバがサポートしていない場合、値は -1 でもよい。
dwMaxAudioChannels
ポートによってレンダリングできるオーディオ チャンネルの最大数。このパラメータが返されることをドライバがサポートしていない場合、値は -1 でもよい。
dwEffectFlags
ポート上でどのようなオーディオ エフェクトを利用できるのかを示すフラグ。

次のフラグが定義されている。

DMUS_EFFECT_NONE
エフェクトはサポートしていない。
DMUS_EFFECT_REVERB
ポートはリバーブをサポートする。
DMUS_EFFECT_CHORUS
ポートはコーラスをサポートする。
wszDescription
ポートの記述。L"MPU-401 Output Port [330]" のようなシステム生成の名前でも、L"Port w/ External SC-55" のようなユーザー指定のわかりやすい名前でもよい。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


DMUS_PORTPARAMS

DMUS_PORTPARAMS 構造体は、DirectMusic ポートを開くためのパラメータによって構成されている。IDirectMusic::CreatePort メソッドを呼び出したときに、これらのパラメータが渡される。

typedef struct _DMUS_PORTPARAMS {
    DWORD dwSize;
    DWORD dwValidParams;
    DWORD dwVoices;
    DWORD dwChannelGroups;
    DWORD dwAudioChannels;
    DWORD dwSampleRate;
    DWORD dwEffectFlags;
    DWORD fShare;
} DMUS_PORTPARAMS, *LPDMUS_PORTPARAMS;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を任意のメソッドに渡す前に、このメンバを sizeof(DMUS_PORTPARAMS) に初期化しなければならない。
dwValidParams
この構造体内のどのポート パラメータへの書き込みが行われているかを指定する。特定のパラメータにフラグをセットすることは、ポートの作成時に、メソッドの呼び出しでそのパラメータを設定したい、またはデフォルト値を上書きしたいことを意味する。次のフラグが定義されている。

DMUS_PORTPARAMS_VOICES
DMUS_PORTPARAMS_CHANNELGROUPS
DMUS_PORTPARAMS_AUDIOCHANNELS
DMUS_PORTPARAMS_SAMPLERATE
DMUS_PORTPARAMS_EFFECTS
DMUS_PORTPARAMS_SHARE

dwVoices
このポートで必要な発音の数。これは絶対的な最大値ではない。ポートは、優先順位の低い発音を削除する必要があるときに、追加の発音を一時的に作成し、スムーズに変化させることができる。
dwChannelGroups
このポートに割り当てられるチャンネル グループの数。IDirectMusic::EnumPort と IDirectMusicPort::GetCaps の各メソッドが返した DMUS_PORTCAPS 構造体で指定されるチャンネル グループ数以下でなければならない。
dwAudioChannels
希望の出力チャンネル数。
dwSampleRate
希望のサンプリング レート。ヘルツ (Hz) 単位で指定する。
dwEffectFlags
希望の特殊効果を示すフラグ。次のフラグが定義されている。

DMUS_EFFECT_NONE
DMUS_EFFECT_REVERB
DMUS_EFFECT_CHORUS

fShare
TRUE の場合、すべてのポートが、このポートに割り当てられたチャンネル グループを使う。FALSE の場合、ポートは排他モードで開かれ、その他のポートによる同じチャンネル グループの使用が禁止される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。

参照

DMUS_PORTCAPS


DMUS_RHYTHM_PARAM

トラックがコード トラックであり、rguidType が GUID_RhythmParam である場合、さまざまな GetParam メソッドを呼び出す際に DMUS_RHYTHM_PARAM 構造体は pParam パラメータとして使われる。

typedef struct {
    DMUS_TIMESIGNATURE  TimeSig;
    DWORD               dwRhythmPattern;
} DMUS_RHYTHM_PARAM;

メンバ

TimeSig
リズム パラメータの拍子記号を保持する DMUS_TIMESIGNATURE 構造体。DMUS_RHYTHM_PARAM 構造体を GetParam に渡す前に、この構造体を初期化しなければならない。
dwRhythmPattern
コード シーケンスのリズム パターン。各ビットは 1 つまたは複数の小節内の 1 つの拍を表し、1 はその拍でコードがオンになっていること、0 はコードが存在しないことを表す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam


DMUS_SUBCHORD

DMUS_SUBCHORD 構造体は、DMUS_CHORD_PARAM 構造体の SubChordList メンバ内で使われる。

typedef struct {
    DWORD dwChordPattern;
    DWORD dwScalePattern;
    DWORD dwInversionPoints;
    DWORD dwLevels;
    BYTE  bChordRoot;
    BYTE  bScaleRoot;
} DMUS_SUBCHORD;

メンバ

dwChordPattern
サブコード内の音符。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応する音符はコード内に存在する。
dwScalePattern
スケール内の音符。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応する音符はスケール内に存在する。
dwInversionPoints
スケール内で転回が発生できるポイント。ビットがオフになっている場合、それに対応する音程では音符を転回できない。たとえば、パターン 100001111111 は、陽音階 (メジャー スケール) の 5 度と 7 度を除き、どこでも転回が認められることを意味する。
dwLevels
このサブコードがサポートするレベルを示すビット フィールド。スタイル内の各パートにはレベルが割り当てられ、レベルがこのメンバに含まれるパートだけについてこのコードが使われる。
bChordRoot
サブコードのルート音。0 は範囲内の最低音の C、23 は最高音の B である。
bScaleRoot
スケールのルート音。0 は範囲内の最低音の C、23 は最高音の B である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_SYNTHSTATS

IDirectMusicPort::GetRunningStats メソッドは、DMUS_SYNTHSTATS 構造体を使って、シンセサイザの現在の動作ステータスを返す。

typedef struct DMUS_SYNTHSTATS {
    DWORD dwSize;
    DWORD dwValidStats;
    DWORD dwVoices;
    DWORD dwTotalCPU;
    DWORD dwCPUPerVoice;
    DWORD dwLostNotes;
    DWORD dwFreeMemory;
    long  lPeakVolume;
} DMUS_SYNTHSTATS, *LPDMUS_SYNTHSTATS;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を任意のメソッドに渡す前に、このメンバを sizeof(DMUS_SYNTHSTATS) に初期化しなければならない。
dwValidStats
シンセサイザが、この構造体内のどのフィールドに書き込みを行うかを指定するフラグ。次のフラグが定義されている。

DMUS_SYNTHSTATS_VOICES
DMUS_SYNTHSTATS_TOTAL_CPU
DMUS_SYNTHSTATS_CPU_PER_VOICE
DMUS_SYNTHSTATS_FREE_MEMORY
DMUS_SYNTHSTATS_LOST_NOTES
DMUS_SYNTHSTATS_PEAK_VOLUME

dwVoices
演奏中の発音数の平均値。
dwTotalCPU
CPU 利用率に 100 をかけた合計パーセンテージ。
dwCPUPerVoice
発音あたりの CPU 利用率に 100 をかけたパーセンテージ。
dwLostNotes
失われた音符の数。発音スティーリングや過度に高い CPU 利用率が原因で、音符が欠落することがある。
dwFreeMemory
DLS 楽器を保存するために現在利用できるメモリの量。シンセサイザがシステム メモリを使っていて、利用可能なシステム メモリによりその量が制限を受ける場合、このフィールドは DMUS_SYNTHSTATS_SYSTEMMEMORY を保持する。
lPeakVolume
ピークボリューム。1/100dB (つまり mB) 単位で測定される。

注意

dwFreeMemory を除き、動作中のすべてのステータス パラメータは 1 秒ごとに更新される。たとえば、dwLostNotes は、1 秒間に失われた音符の合計数を提供する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_TEMPO_PARAM

DMUS_TEMPO_PARAM 構造体は、トラックがテンポ トラックであり、rguidType が GUID_TempoParam である場合、GetParam と SetParam のさまざまなメソッドの呼び出しの際に pParam パラメータとして使われる。

typedef struct _DMUS_TEMPO_PARAM {
    MUSIC_TIME  mtTime;
    double      dblTempo;
} DMUS_TEMPO_PARAM;

メンバ

mtTime
テンポが取り出された時間(このメンバは SetParam のメソッドでは使われない。SetParam のメソッドは代わりにそれらの mtTime パラメータを使う)。
dblTempo
DMUS_TEMPO_MIN ～ DMUS_TEMPO_MAX の範囲にあるテンポ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam


DMUS_TIMESIGNATURE

IDirectMusicStyle::GetTimeSignature メソッドに DMUS_TIMESIGNATURE 構造体を渡して、スタイルの拍子記号に関する情報を取り出す。この構造体は、rguidType パラメータが GUID_TimeSignature であり、トラックが拍子記号トラックまたはスタイル トラックである場合、DMUS_RHYTHM_PARAM 構造体またはさまざまな GetParam メソッドでも使われる。

typedef struct _DMUS_TIMESIGNATURE {
    MUSIC_TIME mtTime;
    BYTE  bBeatsPerMeasure;
    BYTE  bBeat;
    WORD  wGridsPerBeat;
} DMUS_TIMESIGNATURE;

メンバ

mtTime
この拍子記号が発生するミュージック タイム。
bBeatsPerMeasure
拍子記号の分子。
bBeat
拍子記号の分母。
wGridsPerBeat
拍あたりのグリッド (小分割)。この値は、特定の音楽イベントのタイミング分解能を決定する。たとえば、DMUS_SEGF_GRID フラグを使ったセグメントの挿入が挙げられる (DMUS_SEGF_FLAGS を参照 )。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::GetParam、IDirectMusicPerformance::SetParam、IDirectMusicSegment::GetParam、IDirectMusicSegment::SetParam、IDirectMusicTrack::GetParam、IDirectMusicTrack::SetParam、DMUS_TIMESIG_PMSG


DMUS_VERSION

DMUS_VERSION 構造体は、DMUS_OBJECTDESC 構造体に記述されたオブジェクトのバージョン情報を保持する。

typedef struct _DMUS_VERSION {
    DWORD  dwVersionMS;
    DWORD  dwVersionLS;
} DMUS_VERSION, FAR *LPDMUS_VERSION;

メンバ

dwVersionMS
バージョン番号の最上位 DWORD。
dwVersionLS
バージョン番号の最下位 DWORD。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_WAVES_REVERB_PARAMS

DMUS_WAVES_REVERB_PARAMS 構造体は、リバーブ エフェクトに関する情報を保持する。

typedef struct _DMUS_WAVES_REVERB_PARAMS {
    float  fInGain;
    float  fReverbMix;
    float  fReverbTime;
    float  fHighFreqRTRatio;
} DMUS_WAVES_REVERB_PARAMS;

メンバ

fInGain
入力ゲイン。dB 単位で指定する (出力オーバーフローを防ぐため)。デフォルト値は 0である。
fReverbMix
リバーブ ミックス。dB 単位で指定する。値が 0 の場合、100% ウェットなリバーブであることを意味する (ダイレクト シグナルはない)。負の値を指定すると、シグナルのウェット感は弱まる。係数が計算され、リバーブ ミックスの量に関係なく、全体的な出力レベルがほぼ一定に保たれる。デフォルト値は -10.0 である。
fReverbTime
リバーブ ディケイ時間。ミリ秒 (ms) 単位で指定する。デフォルト値は 1,000である。
fHighFreqRTRatio
高周波数とグローバル リバーブ時間の比率。特に明瞭なリバーブが必要でない限り、1 未満の値に設定すべきである。たとえば、fReverbTime が 1000 ms で、dHighFreqRTRatio が 0.1 の場合、高周波数のディケイ時間は 100 ms である。デフォルト値は 0.001。

注意

Waves 社の TrueVerb リバーブ テクノロジは、Microsoft にライセンス提供されており、Microsoft Software Synthesizer で使われる SimpleVerb として実装されている。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


KSPROPERTY

KSPROPERTY 構造体は IKsControl::KsProperty メソッドに渡され、プロパティと操作を識別する。

KSPROPERTY は KSIDENTIFIER 構造体として定義され、次のように宣言される。

typedef struct {
    union {
        struct {
            GUID   Set;
            ULONG  Id;
            ULONG  Flags;
        };
        LONGLONG    Alignment;
    };
} KSIDENTIFIER, *PKSIDENTIFIER;

メンバ

Set
プロパティ セットの識別子。以下のプロパティセット GUID は、DirectMusic によって事前に定義されている。
GUID_DMUS_PROP_DLS1
項目 0 は、このポートが DLS サンプルのダウンロードをサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_Effects
項目 0 は、DMUS_EFFECT_NONE または 1 つ以上のエフェクト フラグを含む (「DMUS_PORTCAPS」の「dwEffectFlags メンバ」を参照)。このプロパティを使って、エフェクトの現在の状態を設定または取得する。
GUID_DMUS_PROP_GM_Hardware
項目 0 は、このポートがハードウェア内で GM をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_GS_Capable
項目 0 は、このポートが Roland GS 拡張の最低要件をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_GS_Hardware
項目 0 は、このポートがハードウェア内で Roland GS 拡張をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_LegacyCaps
項目 0 は、このポートを実装している基盤の Windows マルチメディア デバイスを記述する MIDIINCAPS 構造体または MIDIOUTCAPS 構造体である。このポートの能力の構造体で dwClass が DMUS_PC_INPUTCLASS の場合、MIDIINCAPS 構造体が返される。それ以外の場合は MIDIOUTCAPS 構造体が返される。
GUID_DMUS_PROP_MemorySize
項目 0 は、このデバイス上でサンプル RAM が何バイト利用できるかを示すブール値である。
GUID_DMUS_PROP_SynthSink_DSOUND
項目 0 は、このポートが DirectSound をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_SynthSink_WAVE
項目 0 は、このポートが waveOut 関数を使ってウェーブ出力をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_Volume
項目 1 (DMUS_ITEM_Volume) は、DMUS_VOLUME_MAX ～ DMUS_VOLUME_MIN の範囲の LONG である。符号付きの値で、1/100dB 単位で表す。この値は、すべての DLS アーティキュレーションが実行された後に、すべての発音のゲインに追加される。デフォルトでは、ポートをパフォーマンスに追加するとき、このプロパティはマスタ ボリュームに設定される。マスタ ボリュームについては、「グローバル パラメータの設定と取り出し」を参照すること。
GUID_DMUS_PROP_WavesReverb
項目 0 は、リバーブ パラメータを保持する DMUS_WAVES_REVERB_PARAMS 構造体である。
GUID_DMUS_PROP_WriteLatency
項目 0 はユーザーモード シンセサイザ (DMUS_PORTCAPS 構造体の dwType メンバは DMUS_PORT_USER_MODE_SYNTH) の書き込み遅延時間である。ユーザーモード シンセサイザは、その出力を DirectSound にストリーム化する。書き込み遅延時間とは、シンセサイザがサウンド バッファを作成してから、それが聞こえるまでの遅延時間を意味する。この値を調整することにより、アプリケーションはシンセサイザをより詳細にチューニングし、サウンドの分断のない最小遅延時間を設定できる。一部のコンピュータ、特に、DirectSound のハードウェア サポートのないコンピュータの場合、初期遅延時間は他のコンピュータより非常に長くなる。そのため、値は常に最初に読み込まれるようにし、相対値を使って調整しなければならない。書き込み遅延時間は、各ポート インスタンスについて異なる値を持つことができる。このプロパティは、ポートをアクティブ化するたびに設定しなければならない。
GUID_DMUS_PROP_WritePeriod
項目 0 はユーザーモード シンセサイザ (DMUS_PORTCAPS 構造体の dwType メンバは DMUS_PORT_USER_MODE_SYNTH) の書き込み期間である。ユーザーモード シンセサイザは、その出力を DirectSound にストリーム化する。書き込み期間は、シンセサイザ シンクがシンセサイザのミキシングを許可する頻度を制御する。この値を減らすことによって、アプリケーションはシンセサイザの全体的な遅延時間を短縮できる。ただし、10 ミリ秒 (ms) より小さい値を指定すると、CPU の負荷が増加する。書き込み期間は、標準的な DirectSound シンクを使うすべてのポート インスタンスについて同じ値を持つ。このプロパティは、ポートをアクティブ化するたびに設定しなければならない。
GUID_DMUS_PROP_XG_Capable
項目 0 は、このポートが Yamaha XG 拡張の最低要件をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_XG_Hardware
項目 0 は、このポートがハードウェア内で Yamaha XG 拡張をサポートするかどうかを示すブール値である。
Id
プロパティ セット内の項目。
Flags
次のいずれかのフラグを使って、操作を指定する。
KSPROPERTY_TYPE_GET
指定されたプロパティ項目の値を取り出す。
KSPROPERTY_TYPE_SET
指定されたプロパティ項目の値を設定する。
KSPROPERTY_TYPE_BASICSUPPORT
プロパティ セット用に利用できるサポートのタイプを決定する。IKsControl::KsProperty が *pvPropertyData に返すデータは、KSPROPERTY_TYPE_GET と KSPROPERTY_TYPE_SET のどちらか、または両方を含む DWORD である。これは、その操作が可能であるかを示す。
Alignment
DirectMusic では使われない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmksctrl.h で宣言。

参照

ポートのプロパティ セット


ファイル構造体

ここでは、DirectMusic ファイルで使われるデータ構造体のリファレンス情報を記述する。標準的な DirectMusic の各オブジェクトは、IPersistStream インターフェイスを使って、それ自体のデータをロードするため、ほとんどのアプリケーションでは、これらの構造体に関する知識は必要ない。これらの構造体は、DirectMusic と互換性のあるフォーマットでデータを保存する必要のあるミュージック オーサリング アプリケーション用に主に用意されている。

DirectMusic ファイルでは、以下の構造体が使われる。

  • DMUS_IO_BAND_ITEM_HEADER
  • DMUS_IO_BAND_TRACK_HEADER
  • DMUS_IO_CHORD
  • DMUS_IO_CHORDENTRY
  • DMUS_IO_CHORDMAP
  • DMUS_IO_CHORDMAP_SIGNPOST
  • DMUS_IO_CHORDMAP_SUBCHORD
  • DMUS_IO_COMMAND
  • DMUS_IO_CURVE_ITEM
  • DMUS_IO_INSTRUMENT
  • DMUS_IO_MOTIFSETTINGS
  • DMUS_IO_MUTE
  • DMUS_IO_NEXTCHORD
  • DMUS_IO_PARTREF
  • DMUS_IO_PATTERN
  • DMUS_IO_REFERENCE
  • DMUS_IO_SEGMENT_HEADER
  • DMUS_IO_SEQ_ITEM
  • DMUS_IO_SIGNPOST
  • DMUS_IO_STYLE
  • DMUS_IO_STYLECURVE
  • DMUS_IO_STYLENOTE
  • DMUS_IO_STYLEPART
  • DMUS_IO_SUBCHORD
  • DMUS_IO_SYSEX_ITEM
  • DMUS_IO_TEMPO_ITEM
  • DMUS_IO_TIMESIG
  • DMUS_IO_TIMESIGNATURE_ITEM
  • DMUS_IO_TOOL_HEADER
  • DMUS_IO_TRACK_HEADER
  • DMUS_IO_VERSION

参照

DirectMusic のファイル形式


DMUS_IO_BAND_ITEM_HEADER

DMUS_IO_BAND_ITEM_HEADER 構造体は、バンド チェンジに関する情報を保持する。この構造体は、バンド トラック形式内で使われる。

typedef struct _DMUS_IO_BAND_ITEM_HEADER {
    MUSIC_TIME lBandTime;
} DMUS_IO_BAND_ITEM_HEADER;
lBandTime
バンド チェンジのタイム。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_BAND_TRACK_HEADER

DMUS_IO_BAND_TRACK_HEADER 構造体は、バンド トラックのデフォルト動作に関する情報を保持する。この構造体は、バンド トラック形式内で使われる。

typedef struct _DMUS_IO_BAND_TRACK_HEADER {
    BOOL bAutoDownload;
} DMUS_IO_BAND_TRACK_HEADER;
bAutoDownload
セグメントを演奏しているときの、音色を自動ダウンロードするためのフラグ。

注意

自動ダウンロードの詳細については、「バンドの使い方」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_CHORD

DMUS_IO_CHORD 構造体は、コード チェンジに関する情報を保持する。この構造体は、コード トラック リスト内で使われる。

typedef struct _DMUS_IO_CHORD {
    WCHAR       wszName[16];
    MUSIC_TIME  mtTime;
    WORD        wMeasure;
    BYTE        bBeat;
} DMUS_IO_CHORD;
wszName
コードの名前。
mtTime
コードのタイム。
wMeasure
コードが所属する小節。
bBeat
コードが所属する拍。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_CHORDENTRY

DMUS_IO_CHORDENTRY 構造体は、コード エントリに関する情報を保持する。この構造体は、コード マップ形式内で使われる。

typedef struct _DMUS_IO_CHORDENTRY {
    DWORD   dwFlags;
    WORD    wConnectionID;
} DMUS_IO_CHORDENTRY;
dwFlags
コードがコード グラフ内の開始コード (ビット 2 がセット) であるか 終了コード (ビット 3 がセット) であるかを示すフラグ。
wConnectionID
実行時ポインタを this に置き換える。各コード エントリには、一意の接続識別子がタグ付けされる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_CHORDMAP

DMUS_IO_CHORDMAP 構造体は、コード マップに関する情報を保持する。この構造体は、コード マップ形式内で使われる。

typedef struct _DMUS_IO_CHORDMAP {
    WCHAR   wszLoadName[20];
    DWORD   dwScalePattern;
    DWORD   dwFlags;
} DMUS_IO_CHORDMAP;
wszLoadName
コード マップの名前。コード マップをロードするときに、オブジェクト記述の中で使われる。
dwScalePattern
コード マップに関連付けられたスケール。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応する音符はスケール内に存在する。
dwFlags
将来の使用に備えて予約されている。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_CHORDMAP_SIGNPOST

DMUS_IO_CHORDMAP_SIGNPOST 構造体は、コード マップ内のサインポスト コードに関する情報を保持する。この構造体は、コード マップ形式内で使われる。

typedef struct _DMUS_IO_CHORDMAP_SIGNPOST {
    DWORD   dwChords;
    DWORD   dwFlags;
} DMUS_IO_CHORDMAP_SIGNPOST;
dwChords
このコードがサポートするサインポストのタイプ。テンプレート内の値と同じ値であるかを照合するために、これらの値が使われる。テンプレートを使うアレンジは、特に、テンプレート内でこれらの値を探し、これらの値と一致するコード マップ内の実際のコードを見つける作業から成る。次のフラグが定義されている。
DMUS_SIGNPOSTF_A
DMUS_SIGNPOSTF_B
DMUS_SIGNPOSTF_C
DMUS_SIGNPOSTF_D
DMUS_SIGNPOSTF_E
DMUS_SIGNPOSTF_F
DMUS_SIGNPOSTF_LETTER
DMUS_SIGNPOSTF_1
DMUS_SIGNPOSTF_2
DMUS_SIGNPOSTF_3
DMUS_SIGNPOSTF_4
DMUS_SIGNPOSTF_5
DMUS_SIGNPOSTF_6
DMUS_SIGNPOSTF_7
DMUS_SIGNPOSTF_ROOT
DMUS_SIGNPOSTF_CADENCE
dwFlags
このコードをカデンツァ コードの前に置くかどうかを定義するフラグ。サインポスト コードは最高 2 つのカデンツァ コードを持つことができる。その場合の値は、SPOST_CADENCE1 (最初のカデンツァ)、SPOST_CADENCE2 (2 番目のカデンツァ)、またはこれら 2 つのフラグを組み合わせたものを設定できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_SIGNPOST


DMUS_IO_CHORDMAP_SUBCHORD

DMUS_IO_CHORDMAP_SUBCHORD 構造体は、サブコードに関する情報を保持する。この構造体は、コード マップ形式内で使われる。

typedef struct _DMUS_IO_CHORDMAP_SUBCHORD {
    DWORD   dwChordPattern;
    DWORD   dwScalePattern;
    DWORD   dwInvertPattern;
    BYTE    bChordRoot;
    BYTE    bScaleRoot;
    WORD    wCFlags;
    DWORD   dwLevels;
} DMUS_IO_CHORDMAP_SUBCHORD;
dwChordPattern
サブコード内の音符。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応する音符はコード内に存在する。
dwScalePattern
スケール内の音符。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応する音符はスケール内に存在する。
dwInvertPattern
スケール内で転回が発生できるポイント。ビットがオフになっている場合、それに対応する音程では音符を転回できない。たとえば、パターン 100001111111 は、陽音階 (メジャー スケール) の 5 度と 7 度を除き、どこでも転回が認められることを意味する。
bChordRoot
サブコードのルート音。0 は範囲内の最低音の C、23 は最高音の B である。
bScaleRoot
スケールのルート音。0 は範囲内の最低音の C、23 は最高音の B である。
wCFlags
将来の使用に備えて予約されている。
dwLevels
このサブコードがサポートするレベルを示すビット フィールド。スタイル内の各パートにはレベルが割り当てられ、レベルがこのメンバに含まれるパートだけについてこのコードが使われる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_SUBCHORD


DMUS_IO_COMMAND

DMUS_IO_COMMAND 構造体は、コマンド イベントに関する情報を保持する。この構造体は、コマンド トラック チャンク内で使われる。

typedef struct _DMUS_IO_COMMAND {
    MUSIC_TIME  mtTime;
    WORD        wMeasure;
    BYTE        bBeat;
    BYTE        bCommand;
    BYTE        bGrooveLevel;
    BYTE        bGrooveRange;
} DMUS_IO_COMMAND;
mtTime
コマンドのタイム。
wMeasure
コマンドが所属する小節。
bBeat
コマンドが所属する拍。
bCommand
コマンド タイプ。DMUS_COMMANDT_TYPES を参照すること。
bGrooveLevel
グルーブ レベル。コマンドがグルーブ コマンドでない場合は 0 を指定する。
bGrooveRange
グルーブレベルをランダム化できる量。たとえば、グルーブ レベルが 35 で範囲が 4 の場合、実際のグルーブ レベルは 33 ～ 37 のいずれかの値になる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_CURVE_ITEM

DMUS_IO_CURVE_ITEM 構造体は、トラック内の曲線イベントに関する情報を保持する。この構造体は、シーケンス トラック リスト内で使われる。

typedef struct _DMUS_IO_CURVE_ITEM {
    MUSIC_TIME  mtStart;
    MUSIC_TIME  mtDuration;
    MUSIC_TIME  mtResetDuration;
    DWORD       dwPChannel;
    short       nOffset;
    short       nStartValue;
    short       nEndValue;
    short       nResetValue;
    BYTE        bType;
    BYTE        bCurveShape;
    BYTE        bCCData;
    BYTE        bFlags;
} DMUS_IO_CURVE_ITEM;
mtStart
曲線の開始タイム。
mtDuration
曲線の持続時間。
mtResetDuration
曲線が終了した後、リセット値を設定するまでの時間。
dwPChannel
イベントのパフォーマンス チャンネル。
nOffset
曲線が発生するグリッド境界からのオフセット。ミュージック タイムで表される。MIDI 曲線はロード時に最も近いグリッドに関連付けられるため、この値は正または負でもよい。
nStartValue
開始値。
nEndValue
終了値。
nResetValue
曲線のリセット値。mtResetDuration の経過後、またはフラッシュ (解放) や無効化の際に設定される。
bType
曲線のタイプ。次のタイプが定義されている。
DMUS_CURVET_CCCURVE
コンティニュアス コントローラ曲線 (MIDI Control Change チャンネル発音メッセージ。ステータス バイトは &HBn。n はチャンネル番号を表す)。
DMUS_CURVET_MATCURVE
モノフォニック アフタータッチ曲線 (MIDI Channel Pressure チャンネル発音メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PATCURVE
ポリフォニック アフタータッチ曲線 (MIDI Poly Key Pressure チャンネル発音メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PBCURVE
ピッチベンド曲線 (MIDI Pitch Bend チャンネル発音メッセージ。ステータス バイトは &HEn)。
bCurveShape
曲線のシェイプ。次のシェイプが定義されている。
DMUS_CURVES_EXP
指数曲線シェイプ。
DMUS_CURVES_INSTANT
即時曲線シェイプ (曲線の開始と終了がほとんど同時に発生する)。
DMUS_CURVES_LINEAR
線状曲線シェイプ。
DMUS_CURVES_LOG
対数曲線シェイプ。
DMUS_CURVES_SINE
正弦曲線シェイプ。
bCCData
コントロール チェンジ タイプの場合は、CC 番号を指定する。
bFlags
デフォルトのタイムに達したとき、または移行部が原因で無効化が発生したときに nResetValue を設定しなければならない場合は、この値を 1 に設定する。この値を 0 に設定した場合は、曲線は新しい値に永続的にとどまる。他のすべてのビットは予約されている。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_SEQ_ITEM


DMUS_IO_INSTRUMENT

DMUS_IO_INSTRUMENT 構造体は、音色に関する情報を保持する。この構造体は、バンド形式内で使われる。

typedef struct _DMUS_IO_INSTRUMENT {
    DWORD  dwPatch;
    DWORD  dwAssignPatch;
    DWORD  dwNoteRanges[4];
    DWORD  dwPChannel;
    DWORD  dwFlags;
    BYTE   bPan;
    BYTE   bVolume;
    short  nTranspose;
    DWORD  dwChannelPriority;
} DMUS_IO_INSTRUMENT;
dwPatch
音色を定義するための MSB、LSB、およびプログラム チェンジ。
dwAssignPatch
音色のダウンロード時に割り当てる MSB、LSB、およびプログラム チェンジ。
dwNoteRanges
128 ビット。音色が演奏できなければならない各 MIDI 音符につき 1 つ指定する。
dwPChannel
音色が演奏するパフォーマンス チャンネル。
dwFlags
コントロール フラグ。次の値が定義されている。
DMUS_IO_INST_ASSIGN_PATCH
dwAssignPatch メンバは有効である。
DMUS_IO_INST_BANKSELECT
dwPatch メンバには、MSB と LSB の有効なバンク セレクトが含まれる。
DMUS_IO_INST_CHANNEL_PRIORITY
dwChannelPriority メンバは有効である。
DMUS_IO_INST_GM
音色は General MIDI コレクションのものである。
DMUS_IO_INST_GS
音色は Roland GS コレクションのものである。
DMUS_IO_INST_NOTERANGES
dwNoteRanges メンバは有効である。
DMUS_IO_INST_PAN
bPan メンバは有効である。
DMUS_IO_INST_PATCH
dwPatch メンバは有効である。
DMUS_IO_INST_TRANSPOSE
nTranspose メンバは有効である。
DMUS_IO_INST_USE_DEFAULT_GM_SET
デフォルトの General MIDI 音色セットは、ポートがハードウェア内に GM を持っている場合でも、ポートにダウンロードしなければならない。XG または GS がリセットされたシステム エクスクルーシブ メッセージを持つ MIDI ファイルを解析する場合、GUID_StandardMIDIFile がバンドに対して要求されたかどうかにかかわらず、バンクセレクト メッセージが送信される。つまり、GUID_StandardMIDIFile は純粋に GM ファイルだけのものである。
DMUS_IO_INST_VOLUME
bVolume メンバは有効である。
DMUS_IO_INST_XG
音色は Yamaha XG コレクションのものである。
bPan
音色のパン。
bVolume
音色のボリューム。
nTranspose
音符を転調する半音の数。
dwChannelPriority
チャンネルの優先順位。定義済みの値のリストについては、「IDirectMusicPort::GetChannelPriority」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_MOTIFSETTINGS

DMUS_IO_MOTIFSETTINGS 構造体は、モチーフに関する情報を保持する。この構造体は、スタイル形式内で使われる。

typedef struct _DMUS_IO_MOTIFSETTINGS {
    DWORD       dwRepeats;
    MUSIC_TIME  mtPlayStart;
    MUSIC_TIME  mtLoopStart;
    MUSIC_TIME  mtLoopEnd;
    DWORD       dwResolution;
} DMUS_IO_MOTIFSETTINGS;
dwRepeats
反復回数。
mtPlayStart
再生の開始ポイント。通常は 0 に設定する。
mtLoopStart
ルーブ部分の開始ポイント。通常は 0 に設定する。
mtLoopEnd
ループ部分の終了ポイント。
dwResolution
デフォルトの分解能。「DMUS_TIME_RESOLVE_FLAGS」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicSegment::SetLoopPoints


DMUS_IO_MUTE

DMUS_IO_MUTE 構造体は、チャンネル上のミュート イベントに関する情報を保持する。この構造体は、ミュート トラック チャンク内で使われる。

typedef struct _DMUS_IO_MUTE {
    MUSIC_TIME  mtTime;
    DWORD       dwPChannel;
    DWORD       dwPChannelMap;
} DMUS_IO_MUTE;
mtTime
イベントのタイム。
dwPChannel
ミュートまたは再マップするパフォーマンス チャンネル。
dwPChannelMap
dwPChannel がマップされているチャンネル。dwPChannel をミュートする場合は 0xFFFFFFFF に設定する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_MUTE_PARAM


DMUS_IO_NEXTCHORD

DMUS_IO_NEXTCHORD 構造体は、コード グラフ内の次のコードに関する情報を保持する。この構造体は、コード マップ形式内で使われる。

typedef struct _DMUS_IO_NEXTCHORD {
    DWORD   dwFlags;
    WORD    nWeight;
    WORD    wMinBeats;
    WORD    wMaxBeats;
    WORD    wConnectionID;
} DMUS_IO_NEXTCHORD;
dwFlags
将来の使用に備えて予約されている。
nWeight
コード グラフをトラバースするときにこのリンクが使われる可能性 (1 ～ 100 の範囲)。
wMinBeats
アレンジされたセグメント内でこのコードを演奏できる拍の最小数。
wMaxBeats
アレンジされたセグメント内でこのコードを演奏できる拍の最大数。
wConnectionID
DMUS_IO_CHORDENTRY 構造体の wConnectionID メンバを参照する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_PARTREF

DMUS_IO_PARTREF 構造体は、パート参照に関する情報を保持する。この構造体は、スタイル形式内で使われる。

typedef struct _DMUS_IO_PARTREF {
    GUID  guidPartID;
    WORD  wLogicalPartID;
    BYTE  bVariationLockID;
    BYTE  bSubChordLevel;
    BYTE  bPriority;
    BYTE  bRandomVariation;
} DMUS_IO_PARTREF;
guidPartID
パートの識別子。
wLogicalPartID
ポート上の特定の MIDI チャンネルに対応している識別子。
bVariationLockID
このメンバ内の値と同じ値を持つパートは、常に同じバリエーションを演奏する。
bSubChordLevel
このパートが必要とするサブコード レベル。「注意」を参照すること。
bPriority
パートの優先順位。優先順位の詳細については、「チャンネル」を参照すること。
bRandomVariation
この値を設定すると、一致するバリエーションがランダムな順序で演奏される。この値を解除すると、一致するバリエーションがシーケンシャルな順序で演奏される。

注意

bSubChordLevel メンバは、0 から始まるインデックス値を持つ。実行時には、この値によって 1 が左シフトされ、DMUS_SUBCHORD 構造体の dwLevels メンバと比較するための 1 ビット値が生成される。したがって、bSubChordLevel が 0 のパートは、dwLevels に 1 を含んでいた任意のサブコードにマップされる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_PATTERN

DMUS_IO_PATTERN 構造体は、パターンに関する情報を保持する。この構造体は、スタイル形式内で使われる。

typedef struct _DMUS_IO_PATTERN {
    DMUS_IO_TIMESIG  timeSig;
    BYTE             bGrooveBottom;
    BYTE             bGrooveTop;
    WORD             wEmbellishment;
    WORD             wNbrMeasures;
} DMUS_IO_PATTERN;
timeSig
スタイルのデフォルトの拍子記号を上書きするための拍子記号を保持する DMUS_IO_TIMESIG 構造体。
bGrooveBottom
グルーブ範囲の最低音。
bGrooveTop
グルーブ範囲の最高音。
wEmbellishment
装飾のタイプ。DMUS_COMMANDT_TYPES を参照すること。
wNbrMeasures
小節内のパターンの長さ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_REFERENCE

DMUS_IO_REFERENCE 構造体は、別のファイルに保存されている別のオブジェクトへの参照に関する情報を保持する。この構造体は、参照リスト チャンク内で使われる。「共通のチャンク」を参照すること。

typedef struct _DMUS_IO_REFERENCE {
    GUID    guidClassID;
    DWORD   dwValidData;
} DMUS_IO_REFERENCE;
guidClassID
クラス識別子。
dwValidData
参照のどのデータ チャンクが存在するかを示すフラグ。値のリストについては、対応する DMUS_OBJECTDESC のメンバを参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_SEGMENT_HEADER

DMUS_IO_SEGMENT_HEADER 構造体は、セグメントに関する情報を保持する。この構造体は、セグメント形式内で使われる。

typedef struct _DMUS_IO_SEGMENT_HEADER {
    DWORD       dwRepeats;
    MUSIC_TIME  mtLength;
    MUSIC_TIME  mtPlayStart;
    MUSIC_TIME  mtLoopStart;
    MUSIC_TIME  mtLoopEnd;
    DWORD       dwResolution;
} DMUS_IO_SEGMENT_HEADER;
dwRepeats
反復回数。
mtLength
セグメントの長さ。
mtPlayStart
再生の開始ポイント。通常は 0 に設定する。
mtLoopStart
ルーブ部分の開始ポイント。通常は 0 に設定する。
mtLoopEnd
ループ部分の終了ポイント。
dwResolution
デフォルトの分解能。「DMUS_TIME_RESOLVE_FLAGS」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_MOTIFSETTINGS、IDirectMusicSegment::SetLoopPoints


DMUS_IO_SEQ_ITEM

DMUS_IO_SEQ_ITEM 構造体は、シーケンス トラック内のデータ項目に関する情報を保持する。この構造体は、シーケンス トラック リスト内で使われる。

typedef struct _DMUS_IO_SEQ_ITEM {
    MUSIC_TIME  mtTime;
    MUSIC_TIME  mtDuration;
    DWORD       dwPChannel;
    short       nOffset
    BYTE        bStatus;
    BYTE        bByte1;
    BYTE        bByte2;
} DMUS_IO_SEQ_ITEM;
mtTime
イベントのタイム。
mtDuration
イベントが有効な持続時間。
dwPChannel
イベントのパフォーマンス チャンネル。
nOffset
音符が演奏されるグリッド境界からのオフセット。ミュージック タイムで表される。MIDI 音符はロード時に最も近いグリッドに関連付けられるため、この値は正または負でもよい。
bStatus
MIDI イベント タイプ。MIDI ステータス バイトと同じだが、チャンネル情報がない。
bByte1
MIDI データの最初の 1 バイト。
bByte2
MIDI データの 2 バイト目。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_CURVE_ITEM、MIDI メッセージ


DMUS_IO_SIGNPOST

DMUS_IO_SIGNPOST 構造体は、コード マップ内のサインポスト コードに関連付けるための、サインポスト トラック内のサインポストに関する情報を保持する。この構造体は、サインポスト トラック チャンク内で使われる。

typedef struct _DMUS_IO_SIGNPOST {
    MUSIC_TIME  mtTime;
    DWORD       dwChords;
    WORD        wMeasure;
} DMUS_IO_SIGNPOST;
mtTime
サインポストのタイム。
dwChords
このサインポストに関連付けることのできるサインポスト コードのタイプ。テンプレート内の値と同じ値であるかを照合するために、これらの値が使われる。テンプレートを使うアレンジは、特に、テンプレート内でこれらの値を探し、これらの値と一致するコード マップ内の実際のコードを見つける作業から成る。次のフラグが定義されている。
DMUS_SIGNPOSTF_A
DMUS_SIGNPOSTF_B
DMUS_SIGNPOSTF_C
DMUS_SIGNPOSTF_D
DMUS_SIGNPOSTF_E
DMUS_SIGNPOSTF_F
DMUS_SIGNPOSTF_LETTER
DMUS_SIGNPOSTF_1
DMUS_SIGNPOSTF_2
DMUS_SIGNPOSTF_3
DMUS_SIGNPOSTF_4
DMUS_SIGNPOSTF_5
DMUS_SIGNPOSTF_6
DMUS_SIGNPOSTF_7
DMUS_SIGNPOSTF_ROOT
DMUS_SIGNPOSTF_CADENCE
wMeasure
サインポストが所属する小節。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_CHORDMAP_SIGNPOST


DMUS_IO_STYLE

DMUS_IO_STYLE 構造体は、スタイルの拍子記号とテンポに関する情報を保持する。この構造体は、スタイル形式内で使われる。

typedef struct _DMUS_IO_STYLE {
    DMUS_IO_TIMESIG  timeSig;
    double           dblTempo;
} DMUS_IO_STYLE;
timeSig
スタイルのデフォルトの拍子記号を保持する DMUS_IO_TIMESIG 構造体。
dblTempo
スタイルのテンポ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_STYLECURVE

DMUS_IO_STYLECURVE 構造体は、スタイル内の曲線に関する情報を保持する。この構造体は、スタイル形式内で使われる。

typedef struct _DMUS_IO_STYLECURVE {
    MUSIC_TIME  mtGridStart;
    DWORD       dwVariation;
    MUSIC_TIME  mtDuration;
    MUSIC_TIME  mtResetDuration;
    short       nTimeOffset;
    short       nStartValue;
    short       nEndValue;
    short       nResetValue;
    BYTE        bEventType;
    BYTE        bCurveShape;
    BYTE        bCCData;
    BYTE        bFlags;
} DMUS_IO_STYLECURVE;
mtGridStart
曲線が発生するグリッドの開始タイム。
dwVariation
この曲線が所属するバリエーション。各ビットは 32 あるバリエーションのいずれかに対応する。
mtDuration
曲線の持続時間。
mtResetDuration
曲線が終了した後、リセット値を設定するまでの時間。
nTimeOffset
曲線が発生する mtGridStart からのオフセット。
nStartValue
開始値。
nEndValue
終了値。
nResetValue
曲線のリセット値。mtResetDuration の経過後、またはフラッシュ (解放) や無効化の際に設定される。
bEventType
曲線のタイプ。詳細については、「DMUS_IO_CURVE_ITEM」を参照すること。
bCurveShape
曲線のシェイプ。詳細については、「DMUS_IO_CURVE_ITEM」を参照すること。
bCCData
コントロール チェンジ タイプの場合は、CC 番号を指定する。
bFlags
デフォルトのタイムに達したとき、または移行部が原因で無効化が発生したときに nResetValue を設定しなければならない場合は、この値を 1 に設定する。この値を 0 に設定した場合は、曲線は新しい値に永続的にとどまる。他のすべてのビットは予約されている。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_CURVE_PMSG、DMUS_IO_CURVE_ITEM


DMUS_IO_STYLENOTE

DMUS_IO_STYLENOTE 構造体は、スタイル内の音符に関する情報を保持する。この構造体は、スタイル形式内で使われる。

typedef struct _DMUS_IO_STYLENOTE {
    MUSIC_TIME  mtGridStart;
    DWORD       dwVariation;
    MUSIC_TIME  mtDuration;
    short       nTimeOffset;
    WORD        wMusicValue;
    BYTE        bVelocity;
    BYTE        bTimeRange;
    BYTE        bDurRange;
    BYTE        bVelRange;
    BYTE        bInversionID;
    BYTE        bPlayModeFlags;
} DMUS_IO_STYLENOTE;
mtGridStart
音符が発生するタイム。
dwVariation
この音符が所属するバリエーション。各ビットは 32 あるバリエーションのいずれかに対応する。
mtDuration
音符の持続時間。
nTimeOffset
mtGridStart からのオフセット。
wMusicValue
スケール内の位置。
bVelocity
音符のベロシティ。
bTimeRange
開始タイムをランダム化する範囲。
bDurRange
持続時間をランダム化する範囲。
bVelRange;
ベロシティをランダム化する範囲。
bInversionID
この音符が所属する転回グループの識別子。
bPlayModeFlags
パートの演奏モードを上書きするフラグ。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_STYLEPART

DMUS_IO_STYLEPART 構造体は、ミュージカル パートに関する情報を保持する。この構造体は、スタイル形式内で使われる。

typedef struct _DMUS_IO_STYLEPART {
    DMUS_IO_TIMESIG  timeSig;
    DWORD            dwVariationChoices[32];
    GUID             guidPartID;
    WORD             wNbrMeasures;
    BYTE             bPlayModeFlags;
    BYTE             bInvertUpper;
    BYTE             bInvertLower;
} DMUS_IO_STYLEPART;
timeSig
スタイルのデフォルトの拍子記号を上書きするための拍子記号を保持する DMUS_IO_TIMESIG 構造体。
dwVariationChoices
各 WORD は、32 あるバリエーションのいずれかに対応する。各 WORD にセットされるフラグは、そのバリエーションでサポートされるコードのタイプを示す (「注意」を参照)。次のフラグが定義されている。
DMUS_VARIATIONF_MAJOR
メジャー コードのスケール内の 7 つの位置。
DMUS_VARIATIONF_MINOR
マイナー コードのスケール内の 7 つの位置。
DMUS_VARIATIONF_OTHER
その他のコードのスケール内の 7 つの位置。
DMUS_VARIATIONF_ROOT_SCALE
スケール内のコード ルート音を処理する。
DMUS_VARIATIONF_ROOT_FLAT
フラットのコード ルート音を処理する (スケール内の音符に基づく)。
DMUS_VARIATIONF_ROOT_SHARP
シャープのコード ルート音を処理する (スケール内の音符に基づく)。
DMUS_VARIATIONF_TYPE_TRIAD
3 和音の単体コードを処理する。
DMUS_VARIATIONF_TYPE_6AND7
6 と 7 の単体コードを処理する。
DMUS_VARIATIONF_TYPE_COMPLEX
複合コードを処理する。
DMUS_VARIATIONF_DEST_TO1
1 のコードへの移行を処理する。
DMUS_VARIATIONF_DEST_TO5
5 のコードへの移行を処理する。
DMUS_VARIATIONF_MODES
DMUS_VARIATIONF_IMA25_MODE
DMUS_VARIATIONF_DMUS_MODE
いずれかのフラグをセットして、モードを示す。DirectMusic の場合、この値は常に DMUS_VARIATIONF_DMUS_MODE でなければならない。
guidPartID
パートの一意の識別子。
wNbrMeasures
パートの長さ。小節単位で表す。
bPlayModeFlags
演奏モードを定義するフラグ。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bInvertUpper
転回の上限。
bInvertLower
転回の下限。

注意

dwVariationChoices 内のフラグは、DirectMusic モードで指定したバリエーションによってサポートされるコードのタイプを決定する。最初の 7 つのフラグ (ビット 1 ～ 7) は、バリエーションがスケール位置に基づくメジャー コードをサポートする場合に設定する。たとえば、1、2、4 の各ビットが設定された場合、バリエーションは主音、2 度、4 度のスケール位置に基づくメジャー コードをサポートする。次の 7 つのフラグはマイナー コードに対して同様に機能し、その次の 7 つのフラグはメジャーおよびマイナー以外のコードに対して同様に機能する (SUS 4 コードなど)。22、23、24 の各ビットは、バリエーションがそれぞれスケールに基づくコード、スケールの音程のシャープに基づくコード、スケールの音程のフラットに基づくコードをサポートする場合に設定する。たとえば、C メジャーのスケールで C# マイナー コードをサポートするには、ビット 8 (同主マイナー) とビット 24 (シャープ) を設定する必要がある。25、26、27 の各ビットは、それぞれ 3 和音のコード、6 度または 7 度のコード、拡張されたコードを処理する。28 と 29 の各ビットは、それぞれ主音のコードと属音のコードが続くコードを処理する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_SUBCHORD

DMUS_IO_SUBCHORD 構造体は、サブコードに関する情報を保持する。この構造体は、コード トラック リスト内で使われる。

typedef struct _DMUS_IO_SUBCHORD {
    DWORD   dwChordPattern;
    DWORD   dwScalePattern;
    DWORD   dwInversionPoints;
    DWORD   dwLevels;
    BYTE    bChordRoot;
    BYTE    bScaleRoot;
} DMUS_IO_SUBCHORD;
dwChordPattern
サブコード内の音符。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応する音符はコード内に存在する。
dwScalePattern
スケール内の音符。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応する音符はスケール内に存在する。
dwInversionPoints
スケール内で転回が発生できるポイント。ビットがオフになっている場合、それに対応する音程では音符を転回できない。たとえば、パターン 100001111111 は、陽音階 (メジャー スケール) の 5 度と 7 度を除き、どこでも転回が認められることを意味する。
dwLevels
このサブコードがサポートするレベル。特定の音色を異なったレベルに割り当て (たとえばコードのサブコードだけを演奏する)、サブコードをそれらのレベルにマップする手法としてこの値を利用することもできる。
bChordRoot
サブコードのルート音。0 は範囲内の最低音の C、23 は最高音の B である。
bScaleRoot
スケールのルート音。0 は範囲内の最低音の C、23 は最高音の B である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_SUBCHORD


DMUS_IO_SYSEX_ITEM

DMUS_IO_SYSEX_ITEM 構造体は、システム エクスクルーシブ MIDI メッセージに関する情報を保持する。この構造体は、システム エクスクルーシブ トラック チャンク内で使われる。

typedef struct _DMUS_IO_SYSEX_ITEM {
    MUSIC_TIME  mtTime;
    DWORD       dwPChannel;
    DWORD       dwSysExLength;
} DMUS_IO_SYSEX_ITEM;
mtTime
メッセージのタイム。
dwPChannel
イベントのパフォーマンス チャンネル。
dwSysExLength
データの長さ。バイト単位で指定する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

MIDI システム メッセージ


DMUS_IO_TEMPO_ITEM

DMUS_IO_TEMPO_ITEM 構造体は、トラック内のテンポ チェンジに関する情報を保持する。この構造体は、テンポ トラック チャンク内で使われる。

typedef struct _DMUS_IO_TEMPO_ITEM {
    MUSIC_TIME  mtTime;
    double      dblTempo;
} DMUS_IO_TEMPO_ITEM;
mtTime
テンポ チェンジのタイム。
dblTempo
テンポ。1 分あたりの拍数で表す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DMUS_IO_TIMESIG

DMUS_IO_TIMESIG 構造体は、セグメントの拍子記号に関する情報を保持する。この構造体は、DMUS_IO_STYLE、DMUS_IO_VERSION、および DMUS_IO_PATTERN の各構造体で使われる。

typedef struct _DMUS_IO_TIMESIG {
    BYTE  bBeatsPerMeasure;
    BYTE  bBeat;
    WORD  wGridsPerBeat;
} DMUS_IO_TIMESIG;
bBeatsPerMeasure
小節あたりの拍数 (拍子記号の分子)。
bBeat
音符が受け取る拍 (拍子記号の分母)。この値が 1 のときは全音符、2 のときは 2 分音符、4 のときは 4 分音符を意味する。以下同様である。0 は 256 分音符を意味する。
wGridsPerBeat
拍あたりのグリッド (小分割 )。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_TIMESIGNATURE_ITEM


DMUS_IO_TIMESIGNATURE_ITEM

DMUS_IO_TIMESIGNATURE_ITEM 構造体は、拍子記号チェンジに関する情報を保持する。この構造体は、拍子記号トラック チャンク内で使われる。

typedef struct _DMUS_IO_TIMESIGNATURE_ITEM {
    MUSIC_TIME  mtTime;
    BYTE        bBeatsPerMeasure;
    BYTE        bBeat;
    WORD        wGridsPerBeat;
} DMUS_IO_TIMESIGNATURE_ITEM;
mtTime
イベントのタイム。
bBeatsPerMeasure
小節あたりの拍数 (拍子記号の分子)。
bBeat
音符が受け取る拍 (拍子記号の分母)。この値が 1 のときは全音符、2 のときは 2 分音符、4 のときは 4 分音符を意味する。以下同様である。0 は 256 分音符を意味する。
wGridsPerBeat
拍あたりのグリッド (小分割 )。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_TIMESIG, DMUS_TIMESIG_PMSG


DMUS_IO_TOOL_HEADER

DMUS_IO_TOOL_HEADER 構造体は、ツールに関する情報を保持する。この構造体は、ツール形式内で使われる。

typedef struct _DMUS_IO_TOOL_HEADER {
    GUID    guidClassID;
    long    lIndex;
    DWORD   cPChannels;
    FOURCC  ckid;
    FOURCC  fccType;
    DWORD   dwPChannels[1];
} DMUS_IO_TOOL_HEADER;
guidClassID
ツールのクラス識別子。
lIndex
グラフ内の位置。
cPChannels
dwPChannels 配列内の項目の数。
ckid
ツールのデータ チャンクの識別子。この値が 0 の場合、チャンクのタイプは LIST と見なされる。そのため、fccType は有効で、0 以外の値でなければならない。
fccType
リスト タイプ。この値が 0 の場合、ckid は有効で、0 以外の値でなければならない。
dwPChannels
ツールが有効なパフォーマンス チャンネルの配列。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicGraph::InsertTool


DMUS_IO_TRACK_HEADER

DMUS_IO_TRACK_HEADER 構造体は、トラックに関する情報を保持する。この構造体は、トラック形式内で使われる。

typedef struct _DMUS_IO_TRACK_HEADER {
    GUID     guidClassID;
    DWORD    dwPosition;
    DWORD    dwGroup;
    FOURCC   ckid;
    FOURCC   fccType;
} DMUS_IO_TRACK_HEADER;
guidClassID
トラックのクラス識別子。
dwPosition
トラック リスト内の位置。
dwGroup
トラックのグループ ビット。
ckid
トラックのデータ チャンクの識別子。この値が 0 の場合、チャンクのタイプは LIST と見なされる。そのため、fccType は有効で、0 以外の値でなければならない。
fccType
リスト タイプ。この値が 0 の場合、ckid は有効で、0 以外の値でなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicSegment::GetTrackGroup、IDirectMusicSegment::InsertTrack、トラック形式


DMUS_IO_VERSION

DMUS_IO_VERSION 構造体は、データのバージョン番号を保持する。この構造体は、さまざまなチャンクのバージョン サブチャンク内で使われる。「共通のチャンク」を参照すること。

typedef struct _DMUS_IO_VERSION {
    DWORD  dwVersionMS;
    DWORD  dwVersionLS;
} DMUS_IO_VERSION;
dwVersionMS
バージョン番号の上位 32 ビット。
dwVersionLS
バージョン番号の下位 32 ビット。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicf.h で宣言。


DLS 構造体

ここでは、ダウンローダブル サウンドと共に使われる構造体のリファレンス情報を記述する。DirectMusic は、DLS コレクションのロードおよびシンセサイザへの音色のダウンロードで発生する細かい作業を処理するため、ほとんどのアプリケーションではこれらの構造体を使う必要がない。これらの構造体は、主に DLS を編集するアプリケーション用に用意されている。

DLS データの使い方の概要については「下位レベル DLS」を参照すること。

DLS データ フォーマットの詳細については、MMA (MIDI Manufacturers Association) の規格を参照すること。

ここでは、以下の構造体について説明する。

  • DMUS_ARTICPARAMS
  • DMUS_ARTICULATION
  • DMUS_ARTICULATION2
  • DMUS_COPYRIGHT
  • DMUS_DOWNLOADINFO
  • DMUS_EXTENSIONCHUNK
  • DMUS_INSTRUMENT
  • DMUS_LFOPARAMS
  • DMUS_MSCPARAMS
  • DMUS_OFFSETTABLE
  • DMUS_PEGPARAMS
  • DMUS_REGION
  • DMUS_VEGPARAMS
  • DMUS_WAVE
  • DMUS_WAVEDATA


DMUS_ARTICPARAMS

DMUS_ARTICPARAMS 構造体は、DLS アーティキュレーション チャンクのパラメータを記述する。アーティキュレーションに関するすべてのパラメータは 1 つのチャンクに保存されるが、このチャンクは一連の構造体によって構成されており、各構造体はアーティキュレーションの各機能分野について定義している。楽器やリージョンがアーティキュレーションを利用する場合、DMUS_ARTICULATION チャンクからのインデックスを使って、このチャンクを参照する。

typedef struct {
    DMUS_LFOPARAMS LFO;
    DMUS_VEGPARAMS VolEG;
    DMUS_PEGPARAMS PitchEG;
    DMUS_MSCPARAMS Misc;
} DMUS_ARTICPARAMS;
LFO
低周波数発振器用のパラメータを保持する DMUS_LFOPARAMS 構造体。
VolEG
ボリュームエンベロープ ジェネレータ用のパラメータを保持する DMUS_VEGPARAMS 構造体。
PitchEG
ピッチエンベロープ ジェネレータ用のパラメータを保持する DMUS_PEGPARAMS 構造体。
Misc
初期のパン位置を保持する DMUS_MSCPARAMS 構造体。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。


DMUS_ARTICULATION

DMUS_ARTICULATION 構造体は、DLS 音色のアーティキュレーション チャンクについて記述する。このチャンクは、利用可能なすべてのアーティキュレーション データを 1 つのリスト内に保持できる。たとえば、DLS レベル 1 チャンクとあるメーカー固有のアーティキュレーション チャンクを保持できる。DLS チャンクは ulArt1Idx により参照され、追加のアーティキュレーション チャンクはすべて ulFirstExtCkIdx で始まるリストによって参照される。

typedef struct {
    ULONG ulArt1Idx;
    ULONG ulFirstExtCkIdx;
} DMUS_ARTICULATION;
ulArt1Idx
DMUS_OFFSETTABLE 構造体内にある、DLS アーティキュレーション チャンクのインデックス。この値が 0 の場合、DLS アーティキュレーションは存在しない。
ulFirstExtCkIdx
最初のサードパーティ拡張チャンクのインデックス。この値が 0 の場合、このアーティキュレーションに関連するサードパーティ拡張チャンクは存在しない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICULATION2


DMUS_ARTICULATION2

DMUS_ARTICULATION 構造体は、DLS 音色のアーティキュレーション チャンクについて記述する。この構造体は、フォーマットが DMUS_DOWNLOADINFO_INSTRUMENT2 として定義されている場合 (Dmdls.h ヘッダー ファイルで宣言) に使われる。DLS レベル 1 チャンクは ulArt1Idx により参照され、追加のアーティキュレーション チャンクはすべて ulFirstExtCkIdx で始まるリストによって参照される。DLS レベル 2 アーティキュレーション チャンクは、ulNextArtIdx も使う。

typedef struct {
    ULONG ulArt1Idx;
    ULONG ulFirstExtCkIdx;
    ULONG ulNextArtIdx;

} DMUS_ARTICULATION;
ulArt1Idx
DMUS_OFFSETTABLE 構造体内にある、DLS アーティキュレーション チャンクのインデックス。この値が 0 の場合、DLS レベル 1 またはレベル 2 アーティキュレーションは存在しない。
ulFirstExtCkIdx
最初のサードパーティ拡張チャンクのインデックス。この値が 0 の場合、このアーティキュレーションに関連するサードパーティ拡張チャンクは存在しない。DLS レベル 2 チャンクは、ここに置くこともできる。
ulNextArtIdx
DLS レベル 2 アーティキュレーションをよりサポートするための追加のアーティキュレーション チャンク。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICULATION


DMUS_COPYRIGHT

DMUS_COPYRIGHT 構造体は、DLS データ内にオプションの著作権チャンクを記述する。

typedef struct {
    ULONG cbSize;
    BYTE  byCopyright[ ];
} DMUS_COPYRIGHT;
cbSize
データのサイズ。
byCopyright[ ]
著作権データ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。


DMUS_DOWNLOADINFO

DMUS_DOWNLOADINFO 構造体は、ポートにダウンロードされる DLS データのヘッダーとして使われる。この構造体はダウンロードのサイズと機能を定義し、その後には常に DMUS_OFFSETTABLE チャンクが続く。

typedef struct _DMUS_DOWNLOADINFO {
    DWORD dwDLType;
    DWORD dwDLId;
    DWORD dwNumOffsetTableEntries;
    DWORD cbSize;
} DMUS_DOWNLOADINFO;
dwDLType
ダウンロードされるデータ タイプ。次のタイプが定義されている。
DMUS_DOWNLOADINFO_INSTRUMENT
DMUS_INSTRUMENT 構造体から始まる楽器の定義。
DMUS_DOWNLOADINFO_WAVE
DMUS_WAVE 構造体から始まる PCM ウェーブのデータ。
dwDLId
オブジェクトの一意の 32 ビット識別子。「注意」を参照すること。
dwNumOffsetTableEntries
後に続く DMUS_OFFSETTABLE 構造体内のエントリの数。
cbSize
DMUS_DOWNLOADINFO、DMUS_OFFSETTABLE、および実際のデータ チャンクの合計サイズ。

注意

dwDLId 内の識別子は、オブジェクトを接続するために使われ、IDirectMusicPortDownload::GetDLId メソッドを使って取得される。主に、楽器内のリージョンをウェーブ チャンクに結合する。たとえば、ウェーブ ダウンロードに 3 の dwDLId を指定した場合、音色チャンクは、いずれかの DMUS_REGION 構造体の WaveLink.ulTableIndex メンバに値 3 を配置された形でダウンロードされる。これは、リージョンがウェーブ チャンクに接続されていることを示す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。

参照

下位レベル DLS


DMUS_EXTENSIONCHUNK

DMUS_EXTENSIONCHUNK 構造体は、DLS 拡張チャンクを記述する。DirectMusic にとって未知の拡張を DLS ファイル フォーマットに加えた場合、これらの拡張すべてをこの可変サイズのチャンクでダウンロードする。

typedef struct {
    ULONG  cbSize;
    ULONG  ulNextExtCkIdx;
    FOURCC ExtCkID;
    BYTE   byExtCk[ ];
} DMUS_EXTENSIONCHUNK;
cbSize
チャンクのサイズ。
ulNextExtCkIdx
DMUS_OFFSETTABLE 構造体内にある、次の拡張チャンクのインデックス。この値が 0 の場合、サードパーティの拡張チャンクはそれ以上存在しない。
ExtCkID
チャンク識別子。
byExtCk[ ]
データ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。


DMUS_INSTRUMENT

DMUS_INSTRUMENT 構造体は、DLS ダウンロード チャンク内の楽器定義によって構成されている。

typedef struct {
    ULONG ulPatch;
    ULONG ulFirstRegionIdx;
    ULONG ulGlobalArtIdx;
    ULONG ulFirstExtCkIdx;
    ULONG ulCopyrightIdx;
    ULONG ulFlags;
} DMUS_INSTRUMENT;
ulPatch
楽器のパッチ番号。
ulFirstRegionIdx
楽器内の最初のリージョンチャンク (DMUS_REGION を参照) のインデックス。これは常に 1 つのリージョンとすべきであるが、将来のシンセサイザ アーキテクチャとの互換性を考慮して、このメンバの値を 0 にすることも認められる。
ulGlobalArtIdx
DMUS_OFFSETTABLE 構造体内にある、音色のグローバル アーティキュレーション チャンク (DMUS_ARTICULATION を参照) のインデックス。この値が 0 の場合、この楽器にはグローバル アーティキュレーションがない。
ulFirstExtCkIdx
DMUS_OFFSETTABLE 構造体内にある、最初の拡張チャンク (DMUS_ARTICULATION を参照) のインデックス。DirectMusic が認識していない新しいチャンクを追加するために使われる。この値が 0 の場合、この楽器にはサードパーティの拡張が関連付けられていない。
ulCopyrightIdx
DMUS_OFFSETTABLE 構造体内にある、オプションの著作権チャンク (「DMUS_COPYRIGHT」を参照) のインデックス。この値が 0 の場合、この楽器には著作権情報が関連付けられていない。
ulFlags
楽器の追加のフラグ。次のフラグが定義されている。
DMUS_INSTRUMENT_GM_INSTRUMENT
この楽器は General MIDI 標準の楽器である。パッチが重複している場合、GM 楽器の優先順位は必ず他の DLS 楽器より低くなる。たとえば、パッチ 0 を指定して GM 楽器をダウンロードし、同じくパッチ 0 を指定して GM 以外の楽器をダウンロードした場合、再生の際に必ず GM 以外の楽器が選択される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。


DMUS_LFOPARAMS

DMUS_LFOPARAMS 構造体は、DLS アーティキュレーション チャンク用の低周波数発振器 (LFO) を定義する。この構造体は、DMUS_ARTICPARAMS 構造体で使われる。

typedef struct {
    PCENT pcFrequency;
    TCENT tcDelay;
    GCENT gcVolumeScale;
    PCENT pcPitchScale;
    GCENT gcMWToVolume;
    PCENT pcMWToPitch;
} DMUS_LFOPARAMS;
pcFrequency
周波数。ピッチ単位で指定する。「注意」を参照すること。
tcDelay
初期のディレイ。タイムセント (time cent) 単位で指定する。「注意」を参照すること。
gcVolumeScale
トレモロを制御する出力スケール。減衰単位で指定する。「注意」を参照すること。
pcPitchScale
ビブラートを制御する LFO 出力スケール。ピッチ単位で指定する。「注意」を参照すること。
gcMWToVolume
トレモロを制御するモジュレーション ホイール範囲。減衰単位で指定する。「注意」を参照すること。
pcMWToPitch
トレモロを制御するモジュレーション ホイール範囲。減衰単位で指定する。「注意」を参照すること。

注意

DLS レベル 1 規格は、タイム セント、ピッチ セント、および減衰を 32 ビット対数値として定義する。詳細については、MMA (MIDI Manufacturers Association) の規格を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICPARAMS


DMUS_MSCPARAMS

DMUS_MSCPARAMS 構造体は、DLS アーティキュレーション チャンクのパンを定義する。この構造体は、DMUS_ARTICPARAMS 構造体で使われる。

typedef struct {
    PERCENT ptDefaultPan;
} DMUS_MSCPARAMS;
ptDefaultPan
デフォルトのパン。-50% ～ 50% の範囲を 0.1% 単位で指定し、16 ビット左シフトしたもの。

注意

PERCENT は long として定義される。パンの値については、MMA (MIDI Manufacturers Association) の規格を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICPARAMS


DMUS_OFFSETTABLE

DMUS_OFFSETTABLE 構造体は、ポートにダウンロード中の DLS 音色データのヘッダーで使われる。

typedef struct _DMUS_OFFSETTABLE {
    ULONG ulOffsetTable[DMUS_DEFAULT_SIZE_OFFSETTABLE];
} DMUS_OFFSETTABLE;
ulOffsetTable
データのバイト オフセットの配列。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。

参照

下位レベル DLS


DMUS_PEGPARAMS

DMUS_PEGPARAMS 構造体は、DLS アーティキュレーション チャンクのピッチ エンベロープを定義する。この構造体は、DMUS_ARTICPARAMS 構造体で使われる。

typedef struct {
    TCENT   tcAttack;
    TCENT   tcDecay;
    PERCENT ptSustain;
    TCENT   tcRelease;
    TCENT   tcVel2Attack;
    TCENT   tcKey2Decay;
    PCENT   pcRange;
} DMUS_PEGPARAMS;
tcAttack
アタック時間。タイムセント (time cent) 単位で指定する。「注意」を参照すること。
tcDecay
ディケイ時間。タイムセント単位で指定する。「注意」を参照すること。
ptSustain
サステイン。16 ビット左シフトしたパーセント表示の 1/100 を単位として使う。
tcRelease
リリース時間。タイムセント単位で指定する。「注意」を参照すること。
tcVel2Attack
アタック期間のベロシティ。タイムセント単位で指定する。「注意」を参照すること。
tcKey2Decay
ディケイ期間のキー。タイムセント単位で指定する。「注意」を参照すること。
pcRange
エンベロープ範囲。ピッチ単位で指定する。「注意」を参照すること。

注意

DLS レベル 1 規格は、タイム セントとピッチ セントを 32 ビット対数値として定義する。この構造体内の値については、MMA (MIDI Manufacturers Association) の規格を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICPARAMS


DMUS_REGION

DMUS_REGION 構造体は、DLS ダウンロードのリージョンを定義する。1 つまたは複数のリージョンを 1 つの音色バッファに埋め込み、音色ヘッダー チャンク DMUS_INSTRUMENT によって参照できる。

typedef struct {
    RGNRANGE RangeKey;
    RGNRANGE RangeVelocity;
    USHORT   fusOptions;
    USHORT   usKeyGroup;
    ULONG    ulRegionArtIdx;
    ULONG    ulNextRegionIdx;
    ULONG    ulFirstExtCkIdx;
    WAVELINK WaveLink;
    WSMPL    WSMP;
    WLOOP    WLOOP[1];
} DMUS_REGION;
RangeKey
このリージョンのキー範囲。
RangeVelocity
このリージョンのベロシティ範囲。
fusOptions
このリージョンの合成オプション。次のフラグが定義されている。
F_RGN_OPTION_SELFNONEXCLUSIVE
合成エンジンが同じ音符の 2 回目のノートオンを受け取ると、2 番目の音符は最初の音符と同様に演奏される。デフォルトではこのオプションはオフになっているので、合成エンジンは最初の音符にノートオフを強制的に適用する。
usKeyGroup
ドラム楽器のキーグループ。キーグループの値により、同じグループに所属する 1 つのドラム楽器内で複数のリージョンを利用できる。あるキー グループを指定してある音符を演奏しているときに、同じキー グループを指定して他の音符を演奏するよう合成エンジンが指示を受けた場合、合成エンジンは同じキー グループの値を持つ他のすべての音符をできるだけ早くオフにすべきである。現在、キー グループ 1 ～ 15 が有効であり、0 はキー グループが存在しないことを意味する。
ulRegionArtIdx
DMUS_OFFSETTABLE 構造体内にある、リージョンのグローバル アーティキュレーション チャンクのインデックス。この値が 0 の場合、リージョンはアーティキュレーションを保持せず、楽器のグローバル アーティキュレーションに依存する。
ulNextRegionIdx
DMUS_OFFSETTABLE 構造体内にある、リージョン リスト内の次のリージョンのインデックス。この値が 0 の場合、それ以上リージョンはない。
ulFirstExtCkIdx
DMUS_OFFSETTABLE 構造体内にある、サードパーティ拡張チャンクのインデックス。この値が 0 の場合、リージョンには拡張チャンクが関連付けられていない。
WaveLink
リージョンからウェーブへのリンクを管理する、標準的な DLS 構造体 (Dls1.h ヘッダー ファイル内で宣言されている)。WAVELINK 構造体の ulTableIndex メンバは、関連付けられたウェーブ バッファのダウンロード識別子を提供する (詳細については、「DMUS_DOWNLOADINFO」と「下位レベル DLS」を参照すること)。
WSMP
ウェーブの再生を管理する、標準的な DLS 構造体 (Dls1.h 内で宣言されている )。cSampleLoops メンバが 1 の場合、続く WLOOP 構造体はループの開始ポイントと終了ポイントを保持する。
WLOOP[ ]
ループを記述する、標準的な DLS 構造体 (Dls1.h 内で宣言されている )。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。


DMUS_VEGPARAMS

DMUS_VEGPARAMS 構造体は、DLS アーティキュレーション チャンクのボリューム エンベロープを定義する。

typedef struct {
    TCENT   tcAttack;
    TCENT   tcDecay;
    PERCENT ptSustain;
    TCENT   tcRelease;
    TCENT   tcVel2Attack;
    TCENT   tcKey2Decay;
} DMUS_VEGPARAMS;
tcAttack
アタック時間。タイムセント (time cent) 単位で指定する。「注意」を参照すること。
tcDecay
ディケイ時間。タイムセント単位で指定する。「注意」を参照すること。
ptSustain
サステイン。16 ビット左シフトしたパーセント表示の 1/100 を単位として使う。
tcRelease
リリース時間。タイムセント単位で指定する。「注意」を参照すること。
tcVel2Attack
アタック期間のベロシティ。タイムセント単位で指定する。「注意」を参照すること。
tcKey2Decay
ディケイ期間のキー。タイムセント単位で指定する。「注意」を参照すること。

注意

DLS レベル 1 規格は、タイム セントを 32 ビット対数値として定義する。この構造体内の値については、MMA (MIDI Manufacturers Association) の規格を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICPARAMS


DMUS_WAVE

DMUS_WAVE 構造体は、DLS ダウンロードのウェーブ チャンクを定義する。

typedef struct {
    ULONG  ulFirstExtCkIdx;
    ULONG  ulCopyrightIdx;
    ULONG  ulWaveDataIdx;
    WAVEFORMATEX   WaveformatEx;
} DMUS_WAVE;
ulFirstExtCkIdx
DMUS_OFFSETTABLE 構造体内にある、サードパーティ拡張チャンクのインデックス。この値が 0 の場合、ウェーブには拡張チャンクが関連付けられていない。
ulCopyrightIdx
DMUS_OFFSETTABLE 構造体内にある、著作権チャンクのインデックス。この値が 0 の場合、ウェーブには著作権情報が関連付けられていない。
ulWaveDataIdx
DMUS_OFFSETTABLE 構造体内にある、ウェーブ データのインデックス。「DMUS_WAVEDATA」を参照すること。
WaveformatEx
チャンクのウェーブ フォーマット。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。


DMUS_WAVEDATA

DMUS_WAVEDATA 構造体は、DLS ウェーブ ダウンロードのデータ チャンクを構成する。ウェーブ データが WAVEFORMATEX チャンクによって定義される性質上、この構造体は DMUS_WAVE 構造体にも埋め込まれている。

typedef struct {
    ULONG cbSize;
    BYTE byData[ ];
} DMUS_WAVEDATA;
cbSize
データのサイズ。
byData[ ]
PCM ウェーブ データ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmdls.h で宣言。


列挙型

ここでは、次の列挙型に関するリファレンスを提供する。

  • DMUS_CLOCKTYPE
  • DMUS_COMMANDT_TYPES
  • DMUS_COMPOSEF_FLAGS
  • DMUS_NOTEF_FLAGS
  • DMUS_PLAYMODE_FLAGS
  • DMUS_PMSGF_FLAGS
  • DMUS_PMSGT_TYPES
  • DMUS_SEGF_FLAGS
  • DMUS_SHAPET_TYPES
  • DMUS_TIME_RESOLVE_FLAGS
  • DMUS_TRACKF_FLAGS


DMUS_CLOCKTYPE

DMUS_CLOCKTYPE 列挙型のメンバは、DMUS_CLOCKINFO 構造体の ctType メンバ内で使われる。

typedef enum {
    DMUS_CLOCK_SYSTEM = 0,
    DMUS_CLOCK_WAVE   = 1
} DMUS_CLOCKTYPE;
DMUS_CLOCK_SYSTEM
クロックはシステム クロックである。
DMUS_CLOCK_WAVE
クロックはウェーブ再生デバイス上にある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.hで宣言。


DMUS_COMMANDT_TYPES

DMUS_COMMANDT_TYPES 列挙型のメンバは、IDirectMusicComposer::AutoTransition と IDirectMusicComposer::ComposeTransition の各メソッドの wCommand パラメータ、および DMUS_COMMAND_PARAM 構造体の bCommand メンバとして使われる。

enum enumDMUS_COMMANDT_TYPES {
    DMUS_COMMANDT_GROOVE      = 0,
    DMUS_COMMANDT_FILL        = 1,
    DMUS_COMMANDT_INTRO       = 2,
    DMUS_COMMANDT_BREAK       = 3,
    DMUS_COMMANDT_END         = 4,
    DMUS_COMMANDT_ENDANDINTRO = 5
} DMUS_COMMANDT_TYPES;
DMUS_COMMANDT_GROOVE
コマンドはグルーブ コマンドである。
DMUS_COMMANDT_FILL
コマンドはフィルである。
DMUS_COMMANDT_INTRO
コマンドは導入部である。
DMUS_COMMANDT_BREAK
コマンドは変換点である。
DMUS_COMMANDT_END
コマンドは終了部である。
DMUS_COMMANDT_ENDANDINTRO
コマンドは終了部と導入部である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_COMPOSEF_FLAGS

DMUS_COMPOSEF_FLAGS は、IDirectMusicComposer::ComposeTransition と IDirectMusicComposer::AutoTransition の各メソッドの dwFlags パラメータで使われる。

typedef enum enumDMUS_COMPOSEF_FLAGS {
    DMUS_COMPOSEF_NONE                = 0,
    DMUS_COMPOSEF_ALIGN             = 0x1,
    DMUS_COMPOSEF_OVERLAP           = 0x2,
    DMUS_COMPOSEF_IMMEDIATE         = 0x4,
    DMUS_COMPOSEF_GRID              = 0x8,
    DMUS_COMPOSEF_BEAT             = 0x10,
    DMUS_COMPOSEF_MEASURE          = 0x20,
    DMUS_COMPOSEF_AFTERPREPARETIME = 0x40,
    DMUS_COMPOSEF_MODULATE       = 0x1000,
    DMUS_COMPOSEF_LONG           = 0x2000
}  DMUS_COMPOSEF_FLAGS;
DMUS_COMPOSEF_NONE
フラグなし。デフォルトでは、移行部は小節境界から開始する。
DMUS_COMPOSEF_ALIGN
移行部を、現在演奏されているセグメントの拍子記号に揃える。このフラグは現在実装されていない。
DMUS_COMPOSEF_OVERLAP
移行部を pToSeg に重ねる (オーバーラップ)。このフラグは現在実装されていない。
DMUS_COMPOSEF_IMMEDIATE
AutoTransition only.ミュージック タイムまたは基準タイムの境界から移行部を開始する。
DMUS_COMPOSEF_GRID
AutoTransition のみ。グリッド境界から移行部を開始する。
DMUS_COMPOSEF_BEAT
AutoTransition のみ。拍の境界から移行部を開始する。
DMUS_COMPOSEF_MEASURE
AutoTransition only.小節境界から移行部を開始する。
DMUS_COMPOSEF_AFTERPREPARETIME
AutoTransition のみ。移行部を挿入するときは、DMUS_SEGF_AFTERPREPARETIME フラグを使う。
DMUS_COMPOSEF_MODULATE
pToSeg のコードを使って、pFromSeg から pToSeg へスムーズに変化する移行部をアレンジする。
DMUS_COMPOSEF_LONG
長い移行部をアレンジする。このフラグがセットされていない場合、ComposeTransition または AutoTransition の wCommand パラメータで終了部を指定し、スタイルに 1 小節より長い終了部が含まれていない限り、移行部の長さは最大でも 1 小節である。このフラグがセットされている場合、移行部の長さは 1 小節増える。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

DMUS_SEGF_FLAGS


DMUS_NOTEF_FLAGS

DMUS_NOTEF_FLAGS は、DMUS_NOTE_PMSG 構造体の bFlags メンバ内で使われる。

typedef enum enumDMUS_NOTEF_FLAGS {
    DMUS_NOTEF_NOTEON = 1,
} DMUS_NOTEF_FLAGS;
DMUS_NOTEF_NOTEON
MIDI ノートオンの場合はセットし、MIDI ノートオフの場合は消去する。IDirectMusicPerformance::SendPMsg メソッドで最初に DMUS_NOTE_PMSG を指定する場合は、このフラグをセットすべきである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_PLAYMODE_FLAGS

DMUS_PLAYMODE_FLAGS は、基本的な演奏モードのさまざまな構造体で使われる。演奏モードは、ミュージック値を MIDI 音符にどのように転調するかを決定する。

typedef enum enumDMUS_PLAYMODE_FLAGS {
    DMUS_PLAYMODE_KEY_ROOT          = 1,
    DMUS_PLAYMODE_CHORD_ROOT        = 2,
    DMUS_PLAYMODE_SCALE_INTERVALS   = 4,
    DMUS_PLAYMODE_CHORD_INTERVALS   = 8,
    DMUS_PLAYMODE_NONE              = 16,
} DMUS_PLAYMODE_FLAGS;
DMUS_PLAYMODE_KEY_ROOT
キーのルート音上に転調する。
DMUS_PLAYMODE_CHORD_ROOT
コードのルート音上に転調する。
DMUS_PLAYMODE_SCALE_INTERVALS
スケール パターンのスケールの音程を使う。
DMUS_PLAYMODE_CHORD_INTERVALS
コード パターンのコードの音程を使う。
DMUS_PLAYMODE_NONE
モードなし。親パートのモードを使う必要があることを示す。

注意

以下に示す定義済みの値は、演奏モード フラグの組み合わせを表す。

DMUS_PLAYMODE_ALWAYSPLAY
DMUS_PLAYMODE_SCALE_INTERVALS、DMUS_PLAYMODE_CHORD_INTERVALS、および DMUS_PLAYMODE_CHORD_ROOT の組み合わせ。コードの最高音より高い音符を演奏することが望ましい場合、このモードは、スケールの音程を使うことによって音符の位置を検索する。つまり、このモードは通常の演奏モードと旋律系の演奏モードの組み合わせであり、通常モードで失敗すると 2 度目の試行が旋律系モードで強制的に行われる。
DMUS_PLAYMODE_FIXED
ミュージック値を MIDI 値として解釈する。これは 0 として定義され、その他のフラグがないことを意味する。このフラグは、ドラム、サウンド エフェクト、およびコードまたはスケールによって転調してはならない、シーケンス化された音符について使われる。
DMUS_PLAYMODE_FIXEDTOCHORD
DMUS_PLAYMODE_CHORD_ROOT と同じ。ミュージック値は固定の MIDI 値であるが、コードのルート音上に転調される。
DMUS_PLAYMODE_FIXEDTOKEY
DMUS_PLAYMODE_KEY_ROOT と同じ。ミュージック値は固定の MIDI 値であるが、キーのルート音上に転調される。
DMUS_PLAYMODE_MELODIC
DMUS_PLAYMODE_CHORD_ROOT と DMUS_PLAYMODE_SCALE_INTERVALS の組み合わせ。コードのルート音は使われるが、音符はスケール内の音程だけを追う。キーのルート音とコードの音程は無視される。これは、コードのルート音を基準にして演奏される旋律系のラインにとって便利である。
DMUS_PLAYMODE_NORMALCHORD
DMUS_PLAYMODE_CHORD_ROOT と DMUS_PLAYMODE_CHORD_INTERVALS の組み合わせ。これは一般的な再生モードである。音符はコード内の音程を追う。コードはコードのルート音に基づいている。ミュージック値にスケール要素がある場合、ほかの音程はスケールから取り出され、追加される。コードがミュージック値のコード要素と一致する音程を持っていない場合、音符は無音である。
DMUS_PLAYMODE_PEDALPOINT
DMUS_PLAYMODE_KEY_ROOT と DMUS_PLAYMODE_SCALE_INTERVALS の組み合わせ。キーのルート音は使われるが、音符はスケール内の音程だけを追う。コードのルート音と音程は無視される。これは、キーのルート音を基準にして演奏される旋律系のラインにとって便利である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::MIDIToMusic、IDirectMusicPerformance::MusicToMIDI、DMUS_NOTE_PMSG、DMUS_IO_STYLENOTE、DMUS_IO_STYLEPART、ミュージック値と MIDI 音符


DMUS_PMSGF_FLAGS

DMUS_PMSGF_FLAGS 列挙型のメンバは、DMUS_PMSG 構造体の dwFlags メンバ内で使われる。

enum enumDMUS_PMSGF_FLAGS {
    DMUS_PMSGF_REFTIME        = 1,
    DMUS_PMSGF_MUSICTIME      = 2,
    DMUS_PMSGF_TOOL_IMMEDIATE = 4,
    DMUS_PMSGF_TOOL_QUEUE     = 8,
    DMUS_PMSGF_TOOL_ATTIME    = 16,
    DMUS_PMSGF_TOOL_FLUSH     = 32
} DMUS_PMSGF_FLAGS;
DMUS_PMSGF_REFTIME
rtTime メンバは有効である。
DMUS_PMSGF_MUSICTIME
mtTime メンバは有効である。
DMUS_PMSGF_TOOL_IMMEDIATE
タイム スタンプにかかわりなく、メッセージを即座に処理すべきである。
DMUS_PMSGF_TOOL_QUEUE
ポートの遅延時間を考慮して、タイム スタンプの直前にメッセージを処理すべきである。
DMUS_PMSGF_TOOL_ATTIME
タイムスタンプの時点でメッセージを処理すべきである。
DMUS_PMSGF_TOOL_FLUSH
メッセージをフラッシュ (解放) すべきである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::SendPMsg、IDirectMusicTool::GetMsgDeliveryType


DMUS_PMSGT_TYPES

DMUS_PMSGT_TYPES 列挙型のメンバは、DMUS_PMSG 構造体内の dwType メンバで、メッセージのタイプを識別するために使われる。

typedef enum enumDMUS_PMSGT_TYPES {
    DMUS_PMSGT_MIDI             = 0,
    DMUS_PMSGT_NOTE             = 1,
    DMUS_PMSGT_SYSEX            = 2,
    DMUS_PMSGT_NOTIFICATION     = 3,
    DMUS_PMSGT_TEMPO            = 4,
    DMUS_PMSGT_CURVE            = 5,
    DMUS_PMSGT_TIMESIG          = 6,
    DMUS_PMSGT_PATCH            = 7,
    DMUS_PMSGT_TRANSPOSE        = 8,
    DMUS_PMSGT_CHANNEL_PRIORITY = 9,
    DMUS_PMSGT_STOP             = 10,
    DMUS_PMSGT_DIRTY            = 11,
    DMUS_PMSGT_USER             = 255
} DMUS_PMSGT_TYPES;
DMUS_PMSGT_MIDI
MIDI チャンネル メッセージ。「DMUS_MIDI_PMSG」を参照すること。
DMUS_PMSGT_NOTE
音楽の音符。「DMUS_NOTE_PMSG」を参照すること。
DMUS_PMSGT_SYSEX
MIDI システムエクスクルーシブ メッセージ。「DMUS_SYSEX_PMSG」を参照すること。
DMUS_PMSGT_NOTIFICATION
通知メッセージ。「DMUS_NOTIFICATION_PMSG」を参照すること。
DMUS_PMSGT_TEMPO
テンポメッセージ。「DMUS_TEMPO_PMSG」を参照すること。
DMUS_PMSGT_CURVE
コントロール チェンジとピッチベンド曲線。「DMUS_CURVE_PMSG」を参照すること。
DMUS_PMSGT_TIMESIG
拍子記号。「DMUS_TIMESIG_PMSG」を参照すること。
DMUS_PMSGT_PATCH
パッチの変更。「DMUS_PATCH_PMSG」を参照すること。
DMUS_PMSGT_TRANSPOSE
転調。「DMUS_TRANSPOSE_PMSG」を参照すること。
DMUS_PMSGT_CHANNEL_PRIORITY
チャンネル優先順位チェンジ。「DMUS_CHANNEL_PRIORITY_PMSG」を参照すること。
DMUS_PMSGT_STOP
停止メッセージ。DMUS_PMSG を参照すること。
DMUS_PMSGT_DIRTY
制御セグメントが開始または終了した。DMUS_PMSG を参照すること。
DMUS_PMSGT_USER
ユーザー定義メッセージ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_SEGF_FLAGS

DMUS_SEGF_FLAGS 列挙型のメンバは、セグメントに対するアクションのタイミングおよびその他の要素を制御するために、IDirectMusicPerformance のさまざまなメソッドに渡される。

typedef enum enumDMUS_SEGF_FLAGS {
    DMUS_SEGF_REFTIME          = 64,
    DMUS_SEGF_SECONDARY        = 128,
    DMUS_SEGF_QUEUE            = 256,
    DMUS_SEGF_CONTROL          = 512
    DMUS_SEGF_AFTERPREPARETIME = 1<<10,
    DMUS_SEGF_GRID             = 1<<11,
    DMUS_SEGF_BEAT             = 1<<12,
    DMUS_SEGF_MEASURE          = 1<<13,
    DMUS_SEGF_DEFAULT          = 1<<14,
    DMUS_SEGF_NOINVALIDATE     = 1<<15,
} DMUS_SEGF_FLAGS;
DMUS_SEGF_REFTIME
タイム パラメータは基準タイムで表される。
DMUS_SEGF_SECONDARY
セカンダリ セグメント。
DMUS_SEGF_QUEUE
プライマリセグメントキューの最後に置く (プライマリセグメントのみ)。
DMUS_SEGF_CONTROL
制御セグメント として演奏する (セカンダリ セグメントのみ)。「注意」を参照すること。
DMUS_SEGF_AFTERPREPARETIME
準備時間の後に演奏する。「IDirectMusicPerformance::GetPrepareTime」を参照すること。
DMUS_SEGF_GRID
グリッド境界で演奏する。
DMUS_SEGF_BEAT
拍の境界で演奏する。
DMUS_SEGF_MEASURE
小節境界で演奏する。
DMUS_SEGF_DEFAULT
セグメントのデフォルトの境界を使う。
DMUS_SEGF_NOINVALIDATE
プライマリ セグメントまたは制御セグメントについて、このフラグを IDirectMusicPerformance::PlaySegment にセットすると、新しいセグメントで無効化が発生しない。このフラグがないと無効化が発生し、演奏中の曲線や音符が途切れ、リセットされる。このフラグは DMUS_SEGF_AFTERPREPARETIME と組み合わせなければならない。そうすることによって、新しいセグメント内の音符は、古いセグメントが演奏する音符に重ねて演奏しない。

注意

通常、プライマリ セグメントは制御セグメントである。DMUS_SEGF_CONTROL フラグを使って、セカンダリ セグメントを制御セグメントにすることができる。ただし、制御セグメントが存在できるのは一度に 1 つだけである (複数の制御セグメントを作成することはできるが、実際にどの制御セグメントが DirectMusic によって使われるかは保証されない)。トラックが別のトラックに対して GetParam を呼び出すときは、制御セグメントに対しても同様に呼び出す。デフォルトでは、制御セグメントだけがテンポ メッセージを送信する。

DMUS_SEGF_CONTROL フラグをセットすると、DMUS_SEGF_SECONDARY が想定される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance::Invalidate、IDirectMusicPerformance::PlaySegment、IDirectMusicPerformance::Stop、IDirectMusicSegment::GetDefaultResolution、IDirectMusicSegment::SetDefaultResolution、DMUS_TIME_RESOLVE_FLAGS


DMUS_SHAPET_TYPES

DMUS_SHAPET_TYPES 列挙型のメンバは、IDirectMusicComposer::ComposeSegmentFromShape と IDirectMusicComposer::ComposeTemplateFromShape の各構造体の wShape パラメータ内で使われ、グルーブ レベルの希望のパターンを指定する。

typedef enum enumDMUS_SHAPET_TYPES {
    DMUS_SHAPET_FALLING  = 0,
    DMUS_SHAPET_LEVEL    = 1,
    DMUS_SHAPET_LOOPABLE = 2,
    DMUS_SHAPET_LOUD     = 3,
    DMUS_SHAPET_QUIET    = 4,
    DMUS_SHAPET_PEAKING  = 5,
    DMUS_SHAPET_RANDOM   = 6,
    DMUS_SHAPET_RISING   = 7,
    DMUS_SHAPET_SONG     = 8
} DMUS_SHAPET_TYPES;
DMUS_SHAPET_FALLING
グルーブ レベルは下降する。
DMUS_SHAPET_LEVEL
グルーブ レベルは均等に保たれる。
DMUS_SHAPET_LOOPABLE
セグメントは先頭にループするよう調整されている。
DMUS_SHAPET_LOUD
グルーブ レベルは高い。
DMUS_SHAPET_QUIET
グルーブ レベルは低い。
DMUS_SHAPET_PEAKING
グルーブ レベルはピークまで上昇し、その後下降する。
DMUS_SHAPET_RANDOM
グルーブ レベルはランダムである。
DMUS_SHAPET_RISING
グルーブ レベルは上昇する。
DMUS_SHAPET_SONG
セグメントは歌の形式である。6 ～ 8 小節から成る複数の楽句をアレンジし、まとめることによって、グルーブ レベルにバリエーションのあるヴァースコーラス エフェクトが生み出される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_TIME_RESOLVE_FLAGS

DMUS_TIME_RESOLVE_FLAGS 列挙型のメンバは、DMUS_PMSG 構造体の dwFlags メンバ、および IDirectMusicPerformance::GetResolvedTime メソッドの dwTimeResolveFlags パラメータで使われる。

typedef enum enumDMUS_TIME_RESOLVE_FLAGS {
    DMUS_TIME_RESOLVE_AFTERPREPARETIME = 1<<10,
    DMUS_TIME_RESOLVE_GRID             = 1<<11,
    DMUS_TIME_RESOLVE_BEAT             = 1<<12,
    DMUS_TIME_RESOLVE_MEASURE          = 1<<13
} DMUS_TIME_RESOLVE_FLAGS;
DMUS_TIME_RESOLVE_AFTERPREPARETIME
準備時間の後のタイムに解決する。
DMUS_TIME_RESOLVE_GRID
グリッド境界上のタイムに解決する。
DMUS_TIME_RESOLVE_BEAT
拍境界上のタイムに解決する。
DMUS_TIME_RESOLVE_MEASURE
小節境界上のタイムに解決する。

注意

これらのフラグは、対応する DMUS_SEGF_FLAGS と交換して使うことができる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


DMUS_TRACKF_FLAGS

DMUS_TRACKF_FLAGS の値は、IDirectMusicTrack::Play メソッドの dwFlags パラメータ内で使われる。

typedef enum enumDMUS_TRACKF_FLAGS {
    DMUS_TRACKF_SEEK   = 1,
    DMUS_TRACKF_LOOP   = 2,
    DMUS_TRACKF_START  = 4,
    DMUS_TRACKF_FLUSH  = 8,
    DMUS_TRACKF_DIRTY  = 16
} DMUS_TRACKF_FLAGS;
DMUS_TRACKF_SEEK
IDirectMusicTrack::Play は、シークに対応して呼び出された。mtStart パラメータが直前の呼び出しの mtEnd と同じでなくてもかまわないことを意味する。
DMUS_TRACKF_LOOP
ループに応答して Play が呼び出された。
DMUS_TRACKF_START
これは IDirectMusicTrack::Play の最初の呼び出しである。トラックが先頭から演奏されていない場合は、DMUS_TRACKF_SEEK をセットしてもかまわない。
DMUS_TRACKF_FLUSH
フラッシュ (解放) か無効化に応答して Play が呼び出された。これは、既に演奏された何らかのものを再演奏するようトラックに要求する。この場合、DMUS_TRACKF_SEEK もセットされる。
DMUS_TRACKF_DIRTY
制御セグメント が開始または終了した。mtNext が IDirectMusicTrack::GetParam を呼び出すまで通常呼び出しを待っているトラックは、データが無効になる可能性があるため、待機せずに、即座に呼び出しを行うべきである。制御セグメントの設定方法については、「DMUS_SEGF_FLAGS」を参照すること。

注意

反復 (リピート ) に応答して Play を呼び出した場合、DMUS_TRACKF_LOOP と DMUS_TRACKF_SEEK がセットされる。

無効化をサポートするには、トラックはシークをサポートしなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.h で宣言。


戻り値

以下では、DirectMusic インターフェイスのメソッドが通常返す値を示す。各メソッドが返す可能性のあるエラー コードのリストについては、個別のメソッドの説明を参照すること。これらのリストは必ずしも包括的なものとは限らない。

DMUS_E_ALL_TOOLS_FAILED
グラフ オブジェクトは、IStream オブジェクト データからすべてのツールをロードできなかった。これは、ストリーム内でエラーが発生したか、ツールがクライアント上で不正に登録されていることが原因と考えられる。
DMUS_E_ALL_TRACKS_FAILED
セグメント オブジェクトは、IStream オブジェクト データからすべてのトラックをロードできなかった。これは、ストリーム内でエラーが発生したか、トラックがクライアント上で不正に登録されていることが原因と考えられる。
DMUS_E_ALREADY_ACTIVATED
ポートは既にアクティブ化されており、パラメータは変更できない。
DMUS_E_ALREADY_DOWNLOADED
バッファは既にダウンロードされている。
DMUS_E_ALREADY_EXISTS
ツールはグラフ内に既に含まれている。新しいインスタンスを作成しなければならない。
DMUS_E_ALREADY_INITED
オブジェクトは既に初期化されている。
DMUS_E_ALREADY_LOADED
DLS コレクションは既に開いている。
DMUS_E_ALREADY_SENT
メッセージは既に送信されている。
DMUS_E_ALREADYCLOSED
ポートは開いていない。
DMUS_E_ALREADYOPEN
ポートは既に開いていた。
DMUS_E_BADARTICULATION
DLS コレクション内に無効なアーティキュレーション チャンクがある。
DMUS_E_BADINSTRUMENT
DLS コレクション内に無効な音色チャンクがある。
DMUS_E_BADOFFSETTABLE
オフセット テーブルにエラーがある。
DMUS_E_BADWAVE
ウェーブ ヘッダーが壊れている。
DMUS_E_BADWAVELINK
DLS コレクション内のウェーブリンク チャンクが無効なウェーブを指している。
DMUS_E_BUFFER_EMPTY
バッファ内にデータがない。
DMUS_E_BUFFER_FULL
指定したバイト数が最大バッファ サイズを超えている。
DMUS_E_BUFFERNOTAVAILABLE
このバッファはダウンロードに利用できない。
DMUS_E_BUFFERNOTSET
データ用に準備されたバッファが存在しない。
DMUS_E_CANNOT_CONVERT
ミュージック値と MIDI 値との間で要求した変換は行われなかった。これは通常、提供された DMUS_CHORD_KEY 構造体に無効なコードまたはスケール パターンが含まれる場合に発生する。
DMUS_E_CANNOT_FREE
メッセージが割り当てられていないか、既に解放されているため、メッセージを解放できなかった。
DMUS_E_CANNOT_OPEN_PORT
デフォルトのシステム ポートを開くことができなかった。
DMUS_E_CANNOTREAD
IStream オブジェクトから読み込みを行おうとしていたときにエラーが発生した。
DMUS_E_CANNOTSEEK
IStream オブジェクトは Seek をサポートしない。
DMUS_E_CANNOTWRITE
IStream オブジェクトは Write をサポートしない。
DMUS_E_CHUNKNOTFOUND
指定されたヘッダーを持つチャンクが見つからなかった。
DMUS_E_DESCEND_CHUNK_FAIL
チャンク内に下がろうとしたが失敗した。
DMUS_E_DEVICE_IN_USE
デバイスは既に使われており (おそらく DirectMusic 以外のクライアントによって)、再度開くことができない。
DMUS_E_DMUSIC_RELEASED
DirectMusic オブジェクトの最後のインスタンスが解放されたため、操作を実行できない。DirectMusic オブジェクトの最後の解放が終わるまで、ポートは使用できない。
DMUS_E_DRIVER_FAILED
ドライバまたはハードウェアでの障害の可能性を示す予想外のエラーがデバイス ドライバから返された。
DMUS_E_DSOUND_ALREADY_SET
DirectSound オブジェクトは既に設定されている。
DMUS_E_DSOUND_NOT_SET
DirectSound オブジェクトが指定されていないため、ポートを作成できなかった。
DMUS_E_GET_UNSUPPORTED
パラメータの取得はサポートしていない。
DMUS_E_INSUFFICIENTBUFFER
要求された操作を実行するためのバッファが十分な大きさではない。
DMUS_E_INVALID_BAND
ファイルに有効なバンドが含まれていない。
DMUS_E_INVALID_DOWNLOADID
ダウンロード バッファの作成プロセスで、無効なダウンロード識別子が使われた。
DMUS_E_INVALID_EVENT
イベントは、有効な MIDI メッセージではない、または動作ステータスを利用しておりバッファ内にパックできない。
DMUS_E_INVALID_TOOL_HDR
IStream オブジェクトのデータには、無効なツール ヘッダーが含まれているため、グラフ オブジェクトによる読み込みができない。
DMUS_E_INVALID_TRACK_HDR
IStream オブジェクトのデータには、無効なトラック ヘッダーが含まれているため、セグメント オブジェクトによる読み込みができない。
DMUS_E_INVALIDBUFFER
無効な DirectSound バッファがポートに渡された。
DMUS_E_INVALIDFILE
ファイルが無効である。
DMUS_E_INVALIDOFFSET
DLS コレクション ファイル内のウェーブ チャンクが正しいオフセット上にない。
DMUS_E_INVALIDPATCH
コレクション内の音色がパッチ番号と一致しない。
DMUS_E_INVALIDPOS
DLS コレクションからウェーブ データを読み込み中にエラーが発生した。これは、不正なファイルであることを意味する。
DMUS_E_LOADER_BADPATH
ファイルパスが無効である。
DMUS_E_LOADER_FAILEDCREATE
オブジェクトが見つからなかったまたは作成できなかった。
DMUS_E_LOADER_FAILEDOPEN
ファイルが存在していないかロックされているのが原因で、ファイルを開くことに失敗した。
DMUS_E_LOADER_FORMATNOTSUPPORTED
データフォーマットがサポートされていないため、オブジェクトをロードできない。
DMUS_E_LOADER_NOCLASSID
DMUS_OBJECTDESC でクラス ID が供給されなかった
DMUS_E_LOADER_NOFILENAME
DMUS_OBJECTDESC でファイル名が供給されなかった
DMUS_E_LOADER_OBJECTNOTFOUND
オブジェクトが見つからなかった。
DMUS_E_NO_MASTER_CLOCK
パフォーマンス内にマスタ クロックが存在しない。IDirectMusicPerformance::Init メソッドを必ず呼び出すこと。
DMUS_E_NOARTICULATION
DLS コレクション内の音色からアーティキュレーションが見つからない。
DMUS_E_NOSYNTHSINK
シンクがシンセサイザに接続されていない。
DMUS_E_NOT_DOWNLOADED_TO_PORT
オブジェクトがポート上にないため、アンロードできない。
DMUS_E_NOT_FOUND
要求された項目はオブジェクトに含まれていない。
DMUS_E_NOT_INIT
必要なオブジェクトは初期化されていないか、初期化に失敗した。
DMUS_E_NOTADLSCOL
ロード中のオブジェクトは有効な DLS コレクションではない。
DMUS_E_NOTMONO
ウェーブ チャンクには複数のインターリーブ チャンネルがある。DLS フォーマットではモノラルが要求される。
DMUS_E_NOTPCM
ウェーブデータが PCM フォーマットになっていない。
DMUS_E_OUT_OF_RANGE
要求されたタイムはセグメントの範囲外である。
DMUS_E_PORT_NOT_CAPTURE
キャプチャ ポートではない。
DMUS_E_PORT_NOT_RENDER
出力ポートではない。
DMUS_E_PORTS_OPEN
システム内の任意のプロセスにインスタンス化されたポートがあるときは、要求された操作を実行できない。
DMUS_E_SEGMENT_INIT_FAILED
セグメントの初期化に失敗した。メモリで重大な問題が発生したと考えられる。
DMUS_E_SET_UNSUPPORTED
パラメータの設定はサポートしていない。
DMUS_E_SYNTHACTIVE
シンセサイザは既にアクティブ化されており、パラメータは変更できない。
DMUS_E_SYNTHINACTIVE
シンセサイザはアクティブ化されておらず、データを処理できない。
DMUS_E_SYNTHNOTCONFIGURED
シンセサイザは正しく構成されていないか、開いていない。
DMUS_E_TIME_PAST
要求されたタイムは過去のタイムである。
DMUS_E_TOOL_HDR_NOT_FIRST_CK
IStream オブジェクトのデータには最初のチャンクとしてのツール ヘッダーがないため、グラフ オブジェクトによる読み込みができない。
DMUS_E_TRACK_HDR_NOT_FIRST_CK
IStream オブジェクトのデータには最初のチャンクとしてのトラック ヘッダーがないため、セグメント オブジェクトによる読み込みができない。
DMUS_E_TRACK_NOT_FOUND
要求されたタイプのトラックがない。
DMUS_E_TYPE_DISABLED
トラック パラメータは無効化されているため利用できない。
DMUS_E_TYPE_UNSUPPORTED
パラメータはこのトラック上でサポートされていない。
DMUS_E_UNKNOWNDOWNLOAD
シンセサイザはこのタイプのダウンロードをサポートしていない。
DMUS_E_UNKNOWN_PROPERTY
このポートにはプロパティセットや項目が実装されていない。
DMUS_E_UNSUPPORTED_STREAM
IStream オブジェクトは、ロード中のオブジェクトがサポートしているデータを含んでいない。
DMUS_E_WAVEFORMATNOTSUPPORTED
無効なバッファ フォーマットがシンセサイザ シンクに渡された。
DMUS_S_DOWN_OCTAVE
音符が 1 オクターブまたは複数オクターブ分下げられ、MIDI 値の範囲内に収まっている。
DMUS_S_END
操作に成功し、データの最後に達した。
DMUS_S_FREE
割り当てられたメモリを解放すべきである。
DMUS_S_LAST_TOOL
グラフ内にはこれ以上のツールがない。
DMUS_S_NOBUFFERCONTROL
ポートからのオーディオ出力は、指定された DirectSound バッファと同じデバイスに転送されるが、パンやボリュームなどのバッファ コントロールは出力に影響しない。
DMUS_S_OVER_CHORD
ミュージック値がコードの最高音より高い位置にある音符を持っているため、MIDI 値は計算されていない。
DMUS_S_PARTIALDOWNLOAD
一部の音色をポートにダウンロードできなかった。
DMUS_S_PARTIALLOAD
オブジェクトは部分的なロードしかできなかった。これは、埋め込まれたトラックやツールなどの一部のコンポーネントが正しく登録されていない場合に発生することがある。
DMUS_S_REQUEUE
メッセージを次のツールに渡すべきである。
DMUS_S_STRING_TRUNCATED
メソッドは成功したが、返された文字列を切り捨てなければならなかった。
DMUS_S_UP_OCTAVE
音符が 1 オクターブまたは複数オクターブ分上げられ、MIDI 値の範囲内に収まっている。
E_FAIL
このメソッドは成功しなかった。
E_INVALIDARG
無効な引数。構造体の dwSize メンバを初期化するのを忘れ、このメンバをメソッドに渡した場合にこのエラーが起こることが多い。
E_NOAGGREGATION
集合体はサポートしていない。LPUNKNOWN パラメータを NULL に設定しなければならない。
E_NOINTERFACE
利用可能なオブジェクトインターフェイスがない。
E_NOTIMPL
このメソッドは実装されていない。動作に必要な機能をドライバがサポートしていないために、このメソッドが返されることがある。
E_OUTOFMEMORY
メモリ不足のため、タスクを完了できない。
E_POINTER
無効なポインタ (通常は NULL) がパラメータとして渡された。
REGDB_E_CLASSNOTREG
オブジェクト クラスが登録されていない。
S_FALSE
メソッドは成功したが、すべきことが何もなかった。
S_OK
動作は完了し、成功した。


DirectMusic Visual Basic リファレンス

ここでは、Microsoft® DirectMusic® for Microsoft® Visual Basic® の API 要素に関するリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • クラス
  • 型
  • 列挙型
  • エラー コード


クラス

ここでは、以下の DirectMusic クラスのメソッドに関するリファレンスを提供する。

  • DirectMusicBand
  • DirectMusicChordMap
  • DirectMusicCollection
  • DirectMusicComposer
  • DirectMusicLoader
  • DirectMusicPerformance
  • DirectMusicSegment
  • DirectMusicSegmentState
  • DirectMusicStyle


DirectMusicBand

DirectMusicBand クラスのオブジェクトは、バンドを表す。バンドを使って、一連のパフォーマンス チャンネルの音色の選択肢とミキサ設定を指定する。

バンドは専用のファイルに直接保存しても、スタイルに埋め込んでもよい。DirectMusicBand オブジェクトは、次のいずれかのメソッドを使って取得する。

  • DirectMusicLoader.LoadBand
  • DirectMusicLoader.LoadBandFromResource
  • DirectMusicStyle.GetDefaultBand
  • DirectMusicStyle.GetBand

DirectMusicBand クラスのメソッドは、以下のグループにまとめることができる。

セグメント作成 | CreateSegment
音色データ | Download
 | Unload


DirectMusicBand.CreateSegment

DirectMusicBand.CreateSegment メソッドは、DirectMusicPerformance.PlaySegment メソッドを使って、DirectMusicSegment オブジェクトを作成する。このオブジェクトを使って、バンド内でのボリューム、パン、転調、およびパッチ チェンジ コマンドを動的に実行できる。

object.CreateSegment() As DirectMusicSegment

パラメータ

object
DirectMusicBand オブジェクトを表すオブジェクト式。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_OUTOFMEMORY


DirectMusicBand.Download

DirectMusicBandDirectDownload メソッドは、バンド内の音色の DLS データをパフォーマンス オブジェクトにダウンロードする。バンドのダウンロードが終わると、そのバンド内の音色は、プログラム チェンジ MIDI メッセージにより個別に選択するか、DirectMusicBand.CreateSegment メソッドを呼び出して作成したバンド セグメントを演奏することにより一度にすべてを選択できる。

object.Download(performance As DirectMusicPerformance)

パラメータ

object
DirectMusicBand オブジェクトを表すオブジェクト式。
performance
バンドが演奏するパフォーマンス。パフォーマンスは、チャンネルから DirectMusic ポートへのマッピングを管理する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NOT_INIT
DMUS_E_OUTOFMEMORY

注意

ダウンロードされたバンドはシンセサイザ リソースを使用するため、不要になったときは、DirectMusicBand.Unload メソッドを使ってアンロードしなければならない。

現在のバージョンの DirectMusic の場合、ポートが DLS をサポートしていなくても成功することがある。

DMUS_E_NOT_INIT が返された場合は、通常、初期化されたポートにパフォーマンスが正常に接続されなかったことを意味する。これは完全な失敗であるため、後で DirectMusicBand.Unload を呼び出す必要はない。

ダウンロードが部分的に成功する場合、エラーは返されないが、一部の音色が演奏されない場合がある。部分的なダウンロードが発生する一般的な原因を以下に示す。

  • バンドは、ポートに割り当てられていないチャンネル グループの P チャンネル上に音色を持っている。
  • バンドは、音色のダウンロード先となるシンセサイザと互換性のない DLS フォーマットの音色を持っている。


DirectMusicBand.Unload

DirectMusicBand.Unload メソッドは、DirectMusicBand.Download によって前にダウンロードされたバンド内の音色の DLS データをアンロードする。

object.Unload(performance As DirectMusicPerformance)

パラメータ

object
DirectMusicBand オブジェクトを表すオブジェクト式。
performance
音色のアンロード元のパフォーマンス。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicChordMap

DirectMusicChordMap クラスのオブジェクトは、コード マップを表す。コード マップは、コンポーザ (DirectMusicComposer によって表される) に対し、アレンジするセグメントのコード進行を作成するのに必要な情報を提供する。コード マップを既存のセグメントに適用して、コードを変更することもできる。

このクラスには、パブリック メソッドがない。このクラスのインスタンスは、DirectMusicPerformance.GetChordmap メソッドを使って取得する。

参照

DirectMusicComposer.AutoTransition、DirectMusicComposer.ChangeChordMap、DirectMusicComposer.ComposeSegmentFromShape、DirectMusicComposer.ComposeSegmentFromTemplate、DirectMusicComposer.ComposeTransition、DirectMusicPerformance.GetChordmap


DirectMusicCollection

DirectMusicCollection クラスのオブジェクトは、DLS ファイルのインスタンスを管理する。

このクラスには、パブリック メソッドがない。このクラスのインスタンスは、DirectMusicLoader.LoadCollection または DirectMusicLoader.LoadCollectionFromResource の各メソッドを使って取得し、DirectMusicSegment.ConnectToCollection を呼び出すことによってセグメントに関連付ける。


DirectMusicComposer

アプリケーションは、DirectMusicComposer クラスのメソッドを使って、楽曲要素からセグメントと移行部をアレンジし、既存セグメントのコード マップを変更する。

DirectMusicComposer オブジェクトは、DirectX7.DirectMusicComposerCreate メソッドを使って取得する。

DirectMusicComposer クラスのメソッドは、以下のグループにまとめることができる。

コード マップの変更 | ChangeChordMap
通常のセグメントのアレンジ | ComposeSegmentFromShape
 | ComposeSegmentFromTemplate
テンプレート セグメントのアレンジ | ComposeTemplateFromShape
移行部セグメントのアレンジ | AutoTransition
 | ComposeTransition


DirectMusicComposer.AutoTransition

DirectMusicComposer.AutoTransition メソッドは、パフォーマンスのプライマリ セグメント (または無音) 内部からほかのセグメントへの移行部をアレンジし、演奏の目的でその移行部とセカンダリ セグメントを挿入する。

object.AutoTransition( _
    performance As DirectMusicPerformance, _
    toSeg As DirectMusicSegment, _
    lCommand As Long, _
    lFlags As Long, _
    chordmap As DirectMusicChordMap) _
    As DirectMusicSegment

パラメータ

object
DirectMusicComposer オブジェクトを表すオブジェクト式。
performance
移行に関係するパフォーマンス。
toSeg
移行先セクション。移行部はこのセクションへ円滑に移行する。「注意」を参照すること。
lCommand
移行部を作成するときに使用される装飾。「CONST_DMUS_COMMANDT_TYPES」を参照すること。この値が DMUS_COMMANDT_ENDANDINTRO の場合、メソッドは、プライマリ セグメントの終了部と toSeg の導入部を含むセグメントをアレンジする。
lFlags
コンポーザ オプション。「CONST_DMUS_COMPOSEF_FLAGS」を参照すること。
chordmap
移行部をアレンジするときに使用する DirectMusicChordmap オブジェクト。

戻り値

成功すれば、移行部セグメントのアレンジに利用できるスタイルがほかにない場合に限り、DirectMusicSegment オブジェクトを返す。「注意」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

lFlags が DMUS_COMPOSEF_MODULATE を含んでいない場合、toSeg の値は NULL でもよい。toSeg が NULL またはスタイル トラックを含まないセグメントの場合、導入部の装飾は無効になる。演奏中のセグメントがない場合またはセグメントがスタイル トラックを含んでいない場合は、フィル、ブレーク、エンド、およびグルーブの装飾が無効になる。

演奏中のセグメントまたは toSeg のどちらも、NULL またはスタイル トラックを含まないセグメント (MIDI ファイルに基づくセグメントなど) を指定できる。その場合、すべての装飾は無効になり、演奏中のセグメントと toSeg の間で移行は行われない。メソッドは NULL を返すが、成功して、toSeg によって表されるセグメントを挿入する。

chordmap の値は NULL でもよい。値が NULL の場合、コード マップ トラックからコード マップを取得する試みが行われる。最初に toSeg、次にパフォーマンスのプライマリ セグメントが試される。どのセグメントにもコード マップ トラックが含まれない場合は、現在のタイムにプライマリ セグメント内で発生するコードが移行部のコードとして使われる。


DirectMusicComposer.ChangeChordMap

DirectMusicComposer.ChangeChordMap メソッドは、新しいコード マップを反映して、既存セグメントのコードとスケール パターンを変更する。

object.ChangeChordMap(segment As DirectMusicSegment, _
    trackScale As Boolean, _
    chordmap As DirectMusicChordMap)

パラメータ

object
DirectMusicComposer オブジェクトを表すオブジェクト式。
segment
変更に使うコード マップを含むセクション。
trackScale
TRUE の場合、メソッドは、すべてのコードを新しいコード マップ スケールのルート音に相対的に転調する。ルート音をそのままの状態にしない。
chordmap
セグメントの新しいコード マップ。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

メソッドはセグメントの演奏中に呼び出すことができる。


DirectMusicComposer.ComposeSegmentFromShape

DirectMusicComposer.ComposeSegmentFromShape メソッドは、あらかじめ定義されたシェイプに基づいて、スタイルとコード マップからオリジナルのセクション セグメントを作成する。このシェイプは、セクション全体で時間の経過に伴ってコードと装飾を発生させる方法を表す。

object.ComposeSegmentFromShape(style As DirectMusicStyle, _
    numberOfMeasures As Integer, _
    shape As Integer, _
    activity As Integer, _
    bIntro As Boolean, _
    bEnd As Boolean, _
    chordmap As DirectMusicChordMap) As DirectMusicSegment

パラメータ

object
DirectMusicComposer オブジェクトを表すオブジェクト式。
style
セクション セグメントのアレンジに使用するスタイル。
numberOfMeasures
アレンジするセクション セグメントの長さ。小節単位で指定する。
shape
アレンジするセクション セグメントのシェイプ。グルーブ レベルの変更に基づく。CONST_DMUS_SHAPET_TYPES 列挙型のいずれかの値を指定する。
activity
和音進行のレート。有効な値は 0 ～ 3。値が低いと、コード チェンジが増える。
bIntro
セクション セグメントの導入部をアレンジしたい場合は TRUE。それ以外の場合は False。
bEnd
セクション セグメントの終了部をアレンジしたい場合は TRUE。それ以外の場合は False。
chordmap
セクション セグメントの作成に使用する DirectMusicChordmap オブジェクト。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicComposer.ComposeSegmentFromTemplate、DirectMusicComposer.ComposeTemplateFromShape


DirectMusicComposer.ComposeSegmentFromTemplate

DirectMusicComposer.ComposeSegmentFromTemplate メソッドは、スタイル、コード マップ、およびテンプレートからオリジナルのセクション セグメントを作成する。

object.ComposeSegmentFromTemplate( _
    style As DirectMusicStyle, _
    templateSeg As DirectMusicSegment, _
    activity As Integer, _
    chordmap As DirectMusicChordMap)
    As DirectMusicSegment

パラメータ

object
DirectMusicComposer オブジェクトを表すオブジェクト式。
style
セクション セグメントの作成に使用する DirectMusicStyle オブジェクト。
templateSeg
セクション セグメントの作成に使用するテンプレートを表す DirectMusicSegment オブジェクト。
activity
和音進行のレート。有効な値は 0 ～ 3。値が低いと、コード チェンジが増える。
chordmap
セクション セグメントの作成に使用するコード マップを表す DirectMusicChordmap オブジェクト。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値が設定される。

DMUS_E_INVALIDARG

注意

style が NULL ではない場合、このスタイルはセグメントのアレンジに使用される。NULL の場合、templateSeg で指定されたテンプレートから取り出したスタイルをセグメントのアレンジに使用する。同様に、chordmap が NULL ではない場合、このコード マップはセグメントのアレンジに使用される。NULL の場合、テンプレートから取り出したコード マップをセグメントのアレンジに使用する。

style が NULL でテンプレート内にスタイル トラックが存在しない場合や、chordmap が NULL でコード マップ トラックが存在しない場合、このメソッドは DMUS_E_INVALIDARG を返す。

セクション セグメントの長さは、渡されたテンプレート セクションの長さと等しくなる。

参照

DirectMusicComposer.ComposeSegmentFromShape、DirectMusicComposer.ComposeTemplateFromShape


DirectMusicComposer.ComposeTemplateFromShape

DirectMusicComposer.ComposeTemplateFromShape メソッドは、あらかじめ定義されたシェイプに基づいて新しいテンプレート セグメントを作成する。

object.ComposeTemplateFromShape(numMeasures As Integer, _
    shape As Integer, _
    bIntro As Boolean, _
    bEnd As Boolean, _
    endLength As Integer) As DirectMusicSegment

パラメータ

object
DirectMusicComposer オブジェクトを表すオブジェクト式。
numMeasures
アレンジするセクション セグメントの長さ。小節単位で指定する。0 より大きい値でなければならない。
shape
アレンジするテンプレート セグメントのシェイプ。グルーブ レベルに基づく。CONST_DMUS_SHAPET_TYPES 列挙型のいずれかを指定する。
bIntro
テンプレート セグメントの導入部をアレンジしたい場合は True。それ以外の場合は False。
bEnd
テンプレート セグメントの終了部をアレンジしたい場合は True。それ以外の場合は False。
endLength
終了部を作成したい場合は、終了部の長さ。小節単位で指定する。bEnd が True の場合、この値は 0 より大きく、利用できる小節数以下でなければならない (つまり、導入部で使われない)。「注意」も参照すること。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

注意

endLength の値は、任意のスタイル内で利用できる最長の終了部の長さを超えてはならない。この場合のスタイルとは、DirectMusicComposer.ComposeSegmentFromTemplate メソッドを使ってこのテンプレートに関連付けられる可能性のあるものを指す。終了部の演奏は、セグメントが終わる前の endLength の小節から開始される。終了部が endLength の小節の長さより短い場合、音楽は基本グルーブ レベルに戻る。

参照

DirectMusicComposer.ComposeSegmentFromShape、DirectMusicComposer.ComposeSegmentFromTemplate


DirectMusicComposer.ComposeTransition

DirectMusicComposer.ComposeTransition メソッドは、あるセクション セグメントからほかのセクション セグメントへの移行部をアレンジする。

object.ComposeTransition(fromSeg As DirectMusicSegment, _
    toSeg As DirectMusicSegment, _
    mtTime As Long, _
    lCommand As Long, _
    lFlags As Long, _
    chordmap As DirectMusicChordMap) _
    As DirectMusicSegment

パラメータ

object
DirectMusicComposer オブジェクトを表すオブジェクト式。
fromSeg
移行部の作成に使用するセクション セグメントを表す DirectMusicSegment オブジェクト。
toSeg
移行先セクション。移行部はこのセクションへ円滑に移行する。lFlags が DMUS_COMPOSEF_MODULATE を含んでいない場合、NULL でもよい。
mtTime
fromSeg のセクション内で移行部のアレンジを開始するタイム。
lCommand
移行部を作成するときに使われる装飾。「CONST_DMUS_COMMANDT_TYPES」を参照すること。この値が DMUS_COMMANDT_ENDANDINTRO の場合、メソッドは、fromSeg の終了部と toSeg の導入部を含むセグメントをアレンジする。
lFlags
コンポーザ オプション。このパラメータは、CONST_DMUS_COMPOSEF_FLAGS 列挙型の 1 つまたは複数の値を保持していてもよい。
chordmap
移行部のアレンジに使用するコード マップを表す DirectMusicChordmap オブジェクト。「注意」を参照すること。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

注意

chordmap の値は NULL でもよい。値が NULL の場合、コード マップ トラックからコード マップを取得する試みが行われる。最初に toSeg、次に fromSeg が試される。どのセグメントにもコード マップ トラックが含まれない場合は、mtTime に fromSeg 内で発生するコードが移行部のコードとして使用される。

コンポーザは、最初に fromSeg 内、次に toSeg 内でテンポを探す。どのセグメントにもテンポ トラックがない場合、移行部セグメントのテンポはスタイルから取得される。

参照

DirectMusicComposer.AutoTransition


DirectMusicLoader

DirectMusicLoader オブジェクトは、ミュージック データと音色データを表すオブジェクトの検索とロードに使用される。

このオブジェクトは、DirectX7.DirectMusicLoaderCreate メソッドを使って取得する。

ほかのオブジェクトによって参照されるオブジェクトは、自動的にロードされる。たとえば、スタイルには、その他のファイル内のバンドとコレクションへの参照が含まれる場合があり、これらの参照がロードされるのは、DirectMusicLoader.LoadStyle メソッドを呼び出したときである。

DirectMusicLoader のメソッドは、以下のグループにまとめることができる。

ロード | LoadBand
 | LoadBandFromResource
 | LoadChordMap
 | LoadChordMapFromResource
 | LoadCollection
 | LoadCollectionFromResource
 | LoadSegment
 | LoadSegmentFromResource
 | LoadStyle
 | LoadStyleFromResource
検索 | SetSearchDirectory


DirectMusicLoader.LoadBand

DirectMusicLoader.LoadBand メソッドは、ファイルからバンドをロードする。

object.LoadBand(filename As String) As DirectMusicBand

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
filename
バンドを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合、フル パスを指定しなければならない。

戻り値

成功すれば DirectMusicBand オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_INVALID_BAND
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader.LoadBandFromResource


DirectMusicLoader.LoadBandFromResource

DirectMusicLoader.LoadBandFromResource メソッドは、リソースからバンドをロードする。

object.LoadBandFromResource(moduleName As String, _
    resourceName As String) As DirectMusicBand

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
moduleName
リソースを含むモジュールの名前。
resourceName
バンドを含むリソースの識別子。リソースのタイプは "DMBAND" でなければならない。

戻り値

成功すれば DirectMusicBand オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_INVALID_BAND
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader.LoadBand


DirectMusicLoader.LoadChordMap

DirectMusicLoader.LoadChordMap メソッドは、ファイルからコード マップをロードする。

object.LoadChordMap(filename As String) _
    As DirectMusicChordMap

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
filename
コード マップを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合、フル パスを指定しなければならない。

戻り値

成功すれば DirectMusicChordMap オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader.LoadChordMapFromResource


DirectMusicLoader.LoadChordMapFromResource

DirectMusicLoader.LoadChordMapFromResource メソッドは、リソースからコード マップをロードする。

object.LoadChordMapFromResource( _
    moduleName As String, _
    resourceName As String) As DirectMusicChordMap

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
moduleName
リソースを含むモジュールの名前。
resourceName
コード マップを含むリソースの識別子。リソースのタイプは "DMCHORD" でなければならない。

戻り値

成功すれば DirectMusicChordMap オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader.LoadChordMap


DirectMusicLoader.LoadCollection

DirectMusicLoader.LoadCollection メソッドは、ファイルから DLS コレクションをロードする。

object.LoadCollection(filename As String) _
    As DirectMusicCollection

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
filename
DLS コレクションを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合、フル パスを指定しなければならない。

戻り値

成功すれば DirectMusicCollection オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_NOTADLSCOL

参照

DirectMusicLoader.LoadCollectionFromResource


DirectMusicLoader.LoadCollectionFromResource

DirectMusicLoader.LoadCollectionFromResource メソッドは、リソースから DLS コレクションをロードする。

object.LoadCollectionFromResource( _
    moduleName As String, _
    resourceName As String) As DirectMusicCollection

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
moduleName
リソースを含むモジュールの名前。
resourceName
コレクションを含むリソースの識別子。リソースのタイプは "DMCOLL" でなければならない。

戻り値

成功すれば DirectMusicCollection オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_NOTADLSCOL

参照

DirectMusicLoader.LoadCollection


DirectMusicLoader.LoadSegment

DirectMusicLoader.LoadSegment メソッドは、ファイルからセグメントをロードする。

object.LoadSegment(filename As String) As DirectMusicSegment

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
filename
セグメントを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合、フル パスを指定しなければならない。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader.LoadSegmentFromResource


DirectMusicLoader.LoadSegmentFromResource

DirectMusicLoader.LoadSegmentFromResource メソッドは、リソースからセグメントをロードする。

object.LoadSegmentFromResource( _
    moduleName As String, _
    resourceName As String) As DirectMusicSegment

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
moduleName
リソースを含むモジュールの名前。リソースのタイプは "DMSEG" でなければならない。
resourceName
セグメントを含むリソースの識別子。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_UNSUPPORTED_STREAM

参照

DirectMusicLoader.LoadSegment


DirectMusicLoader.LoadStyle

DirectMusicLoader.LoadStyle メソッドは、ファイルからスタイル オブジェクトをロードする。

object.LoadStyle(filename As String) As DirectMusicStyle

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
filename
スタイル オブジェクトを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合、フル パスを指定しなければならない。

戻り値

成功すれば DirectMusicStyle オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader.LoadStyleFromResource


DirectMusicLoader.LoadStyleFromResource

DirectMusicLoader.LoadStyleFromResource メソッドは、リソースからスタイル オブジェクトをロードする。

object.LoadStyleFromResource( _
    moduleName As String, _
    resourceName As String) As DirectMusicStyle

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
moduleName
リソースを含むモジュールの名前。
resourceName
スタイル オブジェクトを含むリソースの識別子。リソースのタイプは "DMSTYLE" でなければならない。

戻り値

成功すれば DirectMusicStyle オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader.LoadStyle


DirectMusicLoader.SetSearchDirectory

DirectMusicLoader.SetSearchDirectory メソッドは、フル パスが指定されなかった場合に DirectMusicLoader.LoadBand、DirectMusicLoader.LoadChordmap、DirectMusicLoader.LoadCollection、DirectMusicLoader.LoadSegment、および DirectMusicLoader.LoadStyle の各メソッドによって検索されるディレクトリを設定する。

object.SetSearchDirectory(dir As String)

パラメータ

object
DirectMusicLoader オブジェクトを表すオブジェクト式。
dir
検索されるディレクトリ。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_BADPATH

注意

検索パスを設定した後、ローダーはファイル名を使ってオブジェクトをロードするときに、フルパス名を必要としない。この結果、ほかのオブジェクトを参照するオブジェクトは、フル パスを把握していなくてもファイル名だけでそれらを検索できる。


DirectMusicPerformance

DirectMusicPerformance クラスのオブジェクトは、音楽再生の総合的なマネージャである。このオブジェクトは、パフォーマンス チャンネルのポートへのマッピング、セグメントの演奏、メッセージの送信、イベント通知の送受信、およびミュージック パラメータの設定と取り出しを行う。また、タイミングに関する情報の取得、およびシステム間でタイムとミュージック値を変換するためのメソッドも備えている。

アプリケーションが 2 つ以上の完全な音楽セットを同時に演奏したい場合、複数のパフォーマンス オブジェクトを作成することにより、そのような演奏が行える。個別のパフォーマンスは独立したテンポ マップに従うため、完全に非同期に演奏されるが、一方で 1 つのパフォーマンス内のすべてのセグメントは固定的なステップで演奏される。

DirectMusicPerformance オブジェクトは、DirectX7.DirectMusicPerformanceCreate メソッドを使って取得する。

DirectMusicPerformance クラスのメソッドは、以下のグループにまとめることができる。

メッセージ | SendCurvePMSG
 | SendMIDIPMSG
 | SendNotePMSG
 | SendPatchPMSG
 | SendTempoPMSG
 | SendTimeSigPMSG
 | SendTransposePMSG
通知 | AddNotificationType
 | GetNotificationPMSG
 | RemoveNotificationType
 | SetNotificationHandle
パラメータ | GetChordmap
 | GetCommand
 | GetGrooveLevel
 | GetMasterAutoDownload
 | GetMasterGrooveLevel
 | GetMasterTempo
 | GetMasterVolume
 | GetStyle
 | GetTempo
 | GetTimeSig
 | Reset
 | SetMasterAutoDownload
 | SetMasterGrooveLevel
 | SetMasterTempo
 | SetMasterVolume
ポート | GetPortCaps
 | GetPortCount
 | GetPortName
 | SetPort
セグメント | GetSegmentState
 | IsPlaying
 | PlaySegment
 | Stop
タイミング | AdjustTime
 | ClockToMusicTime
 | GetBumperLength
 | GetClockTime
 | GetLatencyTime
 | GetMusicTime
 | GetPrepareTime
 | GetQueueTime
 | GetResolvedTime
 | MusicToClockTime
 | SetBumperLength
 | SetPrepareTime
その他 | CloseDown
 | Init
 | Invalidate


DirectMusicPerformance.AddNotificationType

DirectMusicPerformance.AddNotificationType メソッドは、要求されたタイプのイベントが発生するたびに、パフォーマンスに通知メッセージを生成させる。

object.AddNotificationType( _
    type As CONST_DMUS_NOTIFICATION_TYPE)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
type
通知メッセージが送信されるイベントのタイプ。指定できる値については、「CONST_DMUS_NOTIFICATION_TYPE」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

参照

DirectMusicPerformance.RemoveNotificationType


DirectMusicPerformance.AdjustTime

DirectMusicPerformance.AdjustTime メソッドは、パフォーマンスの内部時間を前方または後方に調整する。このメソッドはほとんどの場合、ほかのソースとの同期化を行う際にずれを補正するために使用される。

object.AdjustTime(rtAmount As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
rtAmount
加算または減算される時間。クロック タイム単位で表す。－1,000 ～から 1,000 (－1 秒～ +1 秒) の数値を指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_INVALIDARG が設定される。

注意

調整された時間は、DirectMusic によって内部的に使用される。DirectMusicPerformance.GetClockTime メソッドが取り出すタイムには反映されない。


DirectMusicPerformance.ClockToMusicTime

DirectMusicPerformance.ClockToMusicTime メソッドは、クロック タイムをミュージック タイムに変換する。クロック タイムは絶対タイムである。ミュージック タイムは、パフォーマンスのテンポに基づく相対タイムである。

object.ClockToMusicTime(ctTime As Long) As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
ctTime
変換されるタイム。クロック タイム単位で表す。

戻り値

成功すれば、変換されたミュージック タイムを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

注意

パフォーマンスについてマスター テンポが設定されている場合は、ミュージック タイムに変換するときに考慮される。

ミュージック タイムはクロック タイムほど正確ではないため、切り捨てが行われる。

参照

DirectMusicPerformance.MusicToClockTime、クロック タイムとミュージック タイム


DirectMusicPerformance.CloseDown

DirectMusicPerformance.CloseDown メソッドは、パフォーマンスを終了する。パフォーマンス オブジェクトを作成し、それに対して DirectMusicPerformance.Init を呼び出したアプリケーションは、パフォーマンス オブジェクトを解放する前に、CloseDown を呼び出さなければならない。

object.CloseDown()

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

CloseDown の呼び出しを忘れると、メモリ リークやアプリケーション障害が発生することがある。

CloseDown は、まだアンロードされていない任意のダウンロード済みの音色も解放する。


DirectMusicPerformance.GetBumperLength

DirectMusicPerformance.GetBumperLength メソッドは、メッセージがポート バッファに置かれてから、ポートによる処理が開始されるまでの時間を取り出す。

object.GetBumperLength() As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、バンパーの長さをミリ秒単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの値は 50 ミリ秒 (ms) である。

参照

DirectMusicPerformance.SetBumperLength


DirectMusicPerformance.GetChordmap

DirectMusicPerformance.GetChordmap メソッドは、パフォーマンスの制御セグメントからコード マップを取り出す。

object.GetChordMap(mtTime As Long, _
    mtUntil As Long) As DirectMusicChordMap

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
コード マップが取り出されるタイム。ミュージック タイムで指定する。
mtUntil
コード マップが有効になるミュージック タイム (mtTime からの相対タイム) を受け取る変数。この変数が値 0 を返した場合、コード マップが常に有効になっているか、コード マップが無効になるタイムが不明であることを意味する。「注意」を参照すること。

戻り値

成功すれば DirectMusicChordmap オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。別の制御セグメントが挿入される場合、このメソッドによって返されるオブジェクトは、mtUntil に返されるタイムの前に無効になることがある。

参照

CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance.GetClockTime

DirectMusicPerformance.GetClockTime メソッドは、現在タイムを取り出す。

object.GetClockTime() As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、任意の開始タイムからの相対タイムを返す。約 1 ミリ秒の単位で表される。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

参照

DirectMusicPerformance.GetMusicTime、クロック タイムとミュージック タイム


DirectMusicPerformance.GetCommand

DirectMusicPerformance.GetCommand メソッドは、パフォーマンスの制御セグメントからコマンドを取り出す。コマンドは、指定のタイムに演奏されているパターンのタイプを示す。

object.GetCommand(mtTime As Long, mtUntil As Long) As Byte

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
コマンドが取り出されるタイム。ミュージック タイムで指定する。
mtUntil
コード マップが有効になるミュージック タイム (mtTime からの相対タイム) を受け取る変数。この変数が値 0 を返した場合、コマンドが常に有効になっているか、コマンドが無効になるタイムが不明であることを意味する。「注意」を参照すること。

戻り値

成功すれば、コマンドのタイプを返す。「CONST_DMUS_COMMANDT_TYPES」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。別の制御セグメントが挿入される場合、このメソッドによって返されるオブジェクトは、mtUntil に返されるタイムの前に無効になることがある。

参照

CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance.GetGrooveLevel

DirectMusicPerformance.GetGrooveLevel メソッドは、パフォーマンスの制御セグメントからグルーブ レベルを取り出す。グルーブ レベルによって、指定のタイムに演奏できるパターンが決まる。

object.GetGrooveLevel(mtTime As Long, _
    mtUntil As Long) As Byte

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
グルーブ レベルが取り出されるタイム。ミュージック タイムで指定する。
mtUntil
グルーブ レベルが有効になるミュージック タイム (mtTime からの相対タイム) を受け取る変数。この変数が値 0 を返した場合、グルーブ レベルが常に有効になっているか、グルーブ レベルが無効になるタイムが不明であることを意味する。「注意」を参照すること。

戻り値

成功すれば 1 ～ 100 の範囲で値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。別の制御セグメントが挿入される場合、このメソッドによって返されるオブジェクトは、mtUntil に返されるタイムの前に無効になることがある。

参照

CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance.GetLatencyTime

DirectMusicPerformance.GetLatencyTime メソッドは、現在の遅延時間を取り出す。遅延時間とは、メッセージがレンダリングのためにポートに送信されるタイムである。

object.GetLatencyTime() As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、遅延時間をクロック タイム単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。


DirectMusicPerformance.GetMasterAutoDownload

DirectMusicPerformance.GetMasterAutoDownload メソッドは、音色の自動ダウンロードの現在の設定を取り出す。

object.GetMasterAutoDownload() As Boolean

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、自動ダウンロードがオンの場合に True を返す。それ以外の場合は False を返す。デフォルト値は False である。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance.SetMasterAutoDownload、DirectMusicSegment.SetAutoDownloadEnable


DirectMusicPerformance.GetMasterGrooveLevel

DirectMusicPerformance.GetMasterGrooveLevel メソッドは、現在のマスタ グルーブ レベルを取り出す。これは、パフォーマンス内のすべてのグルーブ レベルに追加される値である。返される値は 1 ～ 100 の範囲に収まるように必要に応じて調整される。

object.GetMasterGrooveLevel() As Integer

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、マスタ グルーブ レベルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance.SetMasterGrooveLevel


DirectMusicPerformance.GetMasterTempo

DirectMusicPerformance.GetMasterTempo メソッドは、現在のマスタ テンポを取り出す。

object.GetMasterTempo() As Single

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば 0.25 ～ 2.0 の範囲で値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

マスタ テンポは、最終的な出力ツールによってテンポに適用されるスケーリング係数である。デフォルトでは 1 が設定される。値が 0.5 の場合、テンポは半分になり、2.0 の場合は 2 倍になる。

参照

DirectMusicPerformance.SetMasterTempo


DirectMusicPerformance.GetMasterVolume

DirectMusicPerformance.GetMasterVolume メソッドは、現在のマスタ ボリュームを取り出す。

object.GetMasterVolume() As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、現在のマスタ ボリュームを 1/100 dB (デシベル) 単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

マスタ ボリュームは、パフォーマンス全体のデフォルト ボリュームに適用される増幅係数または減衰係数である。設定できる値の範囲はポートによって決まる。

参照

DirectMusicPerformance.SetMasterVolume


DirectMusicPerformance.GetMusicTime

DirectMusicPerformance.GetMusicTime メソッドは、パフォーマンスの現在タイムをミュージック タイムで返す。

object.GetMusicTime() As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、現在タイムをミュージック タイム単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

参照

DirectMusicPerformance.GetClockTime、クロック タイムとミュージック タイム


DirectMusicPerformance.GetNotificationPMsg

DirectMusicPerformance.GetNotificationPMsg メソッドは、保留されている通知メッセージを取り出す。

object.GetNotificationPMSG( _
    message As DMUS_NOTIFICATION_PMSG) As Boolean

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
message
メッセージを受け取る DMUS_NOTIFICATION_PMSG 型。

戻り値

成功すれば、メッセージが受け取られた場合に True を返す。保留されているメッセージがなかった場合は False を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicPerformance.GetPortCaps

DirectMusicPerformance.GetPortCaps メソッドは、ポートの能力に関する情報を取り出す。

object.GetPortCaps(index As Long, caps As DMUS_PORTCAPS)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
index
ポートのインデックス。1 ～ DirectMusicPerformance.GetPortCount が返す値の範囲で指定する。
caps
ポートに関する情報を受け取る DMUS_PORTCAPS 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_INVALIDARG が設定される。


DirectMusicPerformance.GetPortCount

DirectMusicPerformance.GetPortCount メソッドは、システム上で利用できる DirectMusic ポートの数を返す。

object.GetPortCount() As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、利用できるポートの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicPerformance.GetPortName

DirectMusicPerformance.GetPortName メソッドは、ポートの名前を返す。

object.GetPortName(index As Long) As String

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
index
ポートのインデックス。1 ～ DirectMusicPerformance.GetPortCount が返す値の範囲で指定する。

戻り値

成功すれば、Microsoft Synthesizer など、ポートの名前を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicPerformance.GetPrepareTime

DirectMusicPerformance.GetPrepareTime メソッドは、メッセージが準備されてから、処理され、スピーカから聞こえるまでのだいたいの時間を取り出す。

object.GetPrepareTime() As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、準備時間をミリ秒単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

デフォルトの値は 1,000 ミリ秒 (ms) である。

参照

DirectMusicPerformance.SetPrepareTime


DirectMusicPerformance.GetQueueTime

DirectMusicPerformance.GetQueueTime メソッドは、現在のキュー (またはフラッシュ) タイムを取り出す。このタイムより早いタイムのタイム スタンプを持つメッセージは、既にポートのキューに入れられており、無効化することができない。

object.GetQueueTime() As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。

戻り値

成功すれば、キュー タイムをクロック タイム単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

注意

キュー タイムは、DirectMusicPerformance.GetLatencyTime と DirectMusicPerformance.GetBumperLength の各メソッドが返す値を加算した値に等しい。

セグメントを即座に停止すると、既に送信されたものの、ポート バッファのキューに入れられていないメッセージはすべてフラッシュ (解放) される。セグメントの演奏を最後に停止した時点から再開したい場合は、新しい開始ポイントを、セグメントを停止したときのセグメント内におけるキュー タイムのオフセットに設定する。

参照

DirectMusicPerformance.Invalidate


DirectMusicPerformance.GetResolvedTime

DirectMusicPerformance.GetResolvedTime メソッドは、指定されたタイムを、指定された境界に合わせて調整する。

object.GetResolvedTime(ctTime As Long, _
    flags As Long) As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
ctTime
解決されるタイム。クロック タイム単位で指定する。このタイムが現在タイムより早い場合は、現在タイムが使用される。
flags
希望の分解能を記述する、以下の 1 つ以上の CONST_DMUS_SEGF_FLAGS。
DMUS_SEGF_AFTERPREPARETIME
準備時間の後のタイムに解決する。
DMUS_SEGF_GRID
グリッド境界上のタイムに解決する。
DMUS_SEGF_BEAT
拍境界上のタイムに解決する。
DMUS_SEGF_MEASURE
小節境界上のタイムに解決する。

戻り値

成功すれば、解決されたタイムを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicPerformance.GetSegmentState

DirectMusicPerformance.GetSegmentState メソッドは、指定のタイムに演奏されているプライマリ セグメントを表す DirectMusicSegmentState オブジェクトを取り出す。

object.GetSegmentState(mtTime As Long) _
    As DirectMusicSegmentState

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
セグメント状態が取り出されるタイム。ミュージック タイムで指定する。

戻り値

成功すれば DirectMusicSegmentState オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_NOT_FOUND が設定される。

注意

現在演奏されているセグメント状態を取得するには、DirectMusicPerformance.GetMusicTime メソッドによって取り出されたタイムを渡す。この文脈の現在演奏されているというのは、メッセージを演奏するために現在呼び出されていることを意味する。遅延時間が存在するため、必ずしも現在演奏されているセグメント状態が現在スピーカから聞こえているとは限らない。

DirectMusicPerformance.PlaySegment を呼び出した直後にセグメント状態を取り出す場合は、遅延時間を考慮して mtTime の値に 150 を加算するとよい。


DirectMusicPerformance.GetStyle

DirectMusicPerformance.GetStyle メソッドは、指定のタイムにおける、制御セグメントの基調となるスタイルを取り出す。

object.GetStyle(mtTime As Long, mtUntil As Long) _
    As DirectMusicStyle

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
スタイルが取り出されるタイム。ミュージック タイムで指定する。
mtUntil
スタイルが有効になるミュージック タイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、スタイルが常に有効になっているか、スタイルが無効になるタイムが不明であることを意味する。「注意」を参照すること。

戻り値

成功すれば DirectMusicStyle オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。別の制御セグメントが挿入される場合、このメソッドによって返されるタイムは、mtUntil に返されるタイムの前に無効になることがある。


DirectMusicPerformance.GetTempo

DirectMusicPerformance.GetTempo メソッドは、指定されたタイムのテンポを取り出す。

object.GetTempo(mtTime As Long, mtUntil As Long) As Double

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
テンポが取り出されるタイム。ミュージック タイムで指定する。このタイムまたはこれより前に行われたテンポの最後の変更を使って、テンポが決まる。
mtUntil
テンポが有効になるミュージック タイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、テンポが常に有効になっているか、テンポが無効になるタイムが不明であることを意味する。

戻り値

成功すれば、テンポを 1 分あたりの拍数で返す。この値は DMUS_TEMPO_MIN ～ DMUS_TEMPO_MAX の範囲にある (「CONST_DMUS」を参照)。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND


DirectMusicPerformance.GetTimeSig

DirectMusicPerformance.GetTimeSig メソッドは、指定されたタイムの拍子記号を取り出す。

object.GetTimeSig(mtTime As Long, _
    mtUntil As Long, _
    timeSig As DMUS_TIMESIGNATURE)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
拍子記号が取り出されるタイム。ミュージック タイムで指定する。このタイムまたはこれより前に行われた拍子記号の最後の変更を使って、拍子記号が決まる。
mtUntil
拍子記号が有効になるミュージック タイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、拍子記号が常に有効になっているか、拍子記号が無効になるタイムが不明であることを意味する。「注意」を参照すること。
timeSig
拍子記号に関する情報を受け取る DMUS_TIMESIGNATURE 型。mtTime メンバは、要求されたタイムから、拍子記号の最後の変更が行われた時点までのオフセットを受け取る。常に 0 未満の値になる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND


DirectMusicPerformance.Init

DirectMusicPerformance.Init メソッドは、パフォーマンスを初期化し、それを DirectSound オブジェクトに関連付ける。パフォーマンスに対してその他のメソッドを呼び出す前に、このメソッドは一度しか呼び出すことができない。

object.Init(DirectSound As DirectSound, hwnd As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
DirectSound
既存の DirectSound オブジェクト。DirectMusic によってオブジェクトが作成されるようにしたい場合は NULL を指定する。
hwnd
DirectSound の作成に使用するウィンドウ ハンドル。このパラメータは 0 でもよい。その場合、前面ウィンドウが使用される。「注意」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_ALREADY_INITED
DMUS_E_OUTOFMEMORY

注意

DirectSound オブジェクトが存在できるのは 1 つのプロセスにつき 1 つだけである。アプリケーションがウェーブの演奏に DirectSound オブジェクトを使用する場合、オブジェクトをこのメソッドに渡さなければならない。

DirectSound が NULL の場合にだけ hwnd パラメータが重要になる。DirectSound オブジェクトがアプリケーションによって個別に作成され、このメソッドに渡された場合、DirectSound.SetCooperativeLevel の呼び出しで、アプリケーションがウィンドウ ハンドルを設定しなければならない。

メソッドの呼び出し時にアプリケーション ウィンドウが前面にない場合があるため、hwnd に 0 を渡さないこと。通常、最上位のアプリケーション ウィンドウ ハンドルは、DirectMusicPerformance.Init、DirectSound.SetCooperativeLevel、および DirectDraw7.SetCooperativeLevel に渡さなければならない。

パフォーマンスを解放する前に、DirectMusicPerformance.CloseDown メソッドを使ってパフォーマンスを終了しなければならない。


DirectMusicPerformance.Invalidate

DirectMusicPerformance.Invalidate メソッドは、指定されたタイムより後のタイム スタンプを持つキュー内のすべてのメッセージをフラッシュ (解放) し、指定されたタイムから前方に向かって、すべてのセグメントのすべてのトラックにデータを再送させる。

object.Invalidate(mtTime As Long, flags As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
無効にするタイム。flags によって調整される。この値を 0 に設定すると、即座に無効になる。
flags
mtTime を調整して小節、拍、またはグリッドに揃える。この値は、0 または次に示す CONST_DMUS_SEGF_FLAGS のいずれかのメンバでもよい。

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

注意

mtTime がかなり前のタイムで、そのタイムで無効化が行えない場合は、利用可能な範囲で最も早いタイムを使用する。

参照

DirectMusicPerformance.GetQueueTime


DirectMusicPerformance.IsPlaying

DirectMusicPerformance.IsPlaying メソッドは、特定のセグメントまたはセグメント状態が現在スピーカから演奏されているかどうかを判別する。

object.IsPlaying(segment As DirectMusicSegment, _
    segmentState As DirectMusicSegmentState) As Boolean

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
segment
チェックされる DirectMusicSegment オブジェクト。NULL の場合、segmentState だけをチェックする。
segmentState
チェックされる DirectMusicSegmentState オブジェクト。NULL の場合、セグメントだけをチェックする。

戻り値

このメソッドが成功し、要求したセグメントとセグメント状態のどちらかが演奏されている場合は True を返す。どちらも演奏されていない場合、またはどちらか 1 つだけを要求し、それが演奏されていない場合は、False を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値が設定される。

DMUS_E_NO_MASTER_CLOCK


DirectMusicPerformance.MusicToClockTime

DirectMusicPerformance.MusicToClockTime メソッドは、ミュージックタイム フォーマットのタイムをクロック タイム フォーマットに変換する。

object.MusicToClockTime(mtTime As Long) As Long

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
mtTime
変換されるミュージック タイム フォーマットのタイム。

戻り値

成功すれば、タイムをクロック タイム単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

注意

クロック タイムはミュージック タイムよりも正確であるため、クロック タイムからミュージック タイムに変換し、またクロック タイムに変換したタイムは、おそらく元の値とは異なる。

参照

DirectMusicPerformance.ClockToMusicTime、クロック タイムとミュージック タイム


DirectMusicPerformance.PlaySegment

DirectMusicPerformance.PlaySegment メソッドは、セグメントの再生を開始する。

object.PlaySegment(segment As DirectMusicSegment, _
    lFlags As Long, _
    startTime As Long) As DirectMusicSegmentState

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
segment
演奏される DirectMusicSegment オブジェクト。
lFlags
メソッドの動作を変更するフラグ。「CONST_DMUS_SEGF_FLAGS」を参照すること。
startTime
セグメントの演奏が開始されるタイム。lFlags で指定する任意の分解能境界に調整される。DMUS_SEGF_REFTIME フラグがセットされていない限り、タイムはミュージック タイムで表される。値が 0 の場合、セグメントの演奏はできる限り早く開始される。

戻り値

成功すれば、演奏中のセグメントを表す DirectMusicSegmentState オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値のいずれかが設定される。

DMUS_E_OUTOFMEMORY
DMUS_E_NO_MASTER_CLOCK
DMUS_E_SEGMENT_INIT_FAILED
DMUS_E_TIME_PAST

注意

セグメントの長さは 250 ミリ秒 (ms) を超えているべきである。

lFlags の境界分解能は、現在演奏されているプライマリ セグメントに関連するものである。

プライマリ セグメントの演奏が、別のプライマリ セグメントの演奏中にスケジュール設定されている場合、後に演奏されるセグメントに DMUS_SEGF_QUEUE フラグをセットしない限り、最初のセグメントは停止する。DMUS_SEGF_QUEUE フラグをセットした場合、2 つ目のセグメントは、最初のセグメントの演奏が終わると同時に演奏が開始される。

参照

DirectMusicPerformance.IsPlaying


DirectMusicPerformance.RemoveNotificationType

DirectMusicPerformance.RemoveNotificationType メソッドは、前に追加された通知タイプをパフォーマンスから削除し、そのタイプの通知メッセージがそれ以降送信されないようにする。

object.RemoveNotificationType( _
    type As CONST_DMUS_NOTIFICATION_TYPE)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
type
通知メッセージが送信されないイベントのタイプ。指定できる値については、「CONST_DMUS_NOTIFICATION_TYPE」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_INVALIDARG が設定される。

参照

DirectMusicPerformance.AddNotificationType


DirectMusicPerformance.Reset

DirectMusicPerformance.Reset メソッドは、ポートをリセットする。

object.Reset(resetflags As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
resetflags
フラグ。デフォルト (resetflags = 0) の場合、メソッドは GMReset を実行する。この値が 1 の場合、ポートをいったん閉じ、再度開くことによって、リセットされる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicPerformance.SendCurvePMSG

DirectMusicPerformance.SendCurvePMSG メソッドは、MIDI 曲線に関する情報を含むパフォーマンス メッセージを送信する。

object.SendCurvePMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    msg As DMUS_CURVE_PMSG)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
メッセージの送信先となるパフォーマンス チャンネル。
msg
曲線に関する情報を含む DMUS_CURVE_PMSG 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータが DMUS_PMSGF_REFTIME に設定されている場合、このメッセージは即座に送り出すものとしてキューに挿入される。


DirectMusicPerformance.SendMIDIPMSG

DirectMusicPerformance.SendMIDIPMSG メソッドは、その他のメソッドによって処理されない MIDI チャンネル メッセージに関する情報を含むパフォーマンス メッセージを送信する。

object.SendMIDIPMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    status As Byte, _
    byte1 As Byte, _
    byte2 As Byte)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
メッセージの送信先となるパフォーマンス チャンネル。
status
スタンダード MIDI のステータス バイト。「注意」を参照すること。
byte1
先頭のデータ バイト。これを必要としない MIDI メッセージでは無視される。
byte2
2 番目のデータ バイト。これを必要としない MIDI メッセージでは無視される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータが DMUS_PMSGF_REFTIME に設定されている場合、このメッセージは即座に送り出すものとしてキューに挿入される。

チャンネルは別のパラメータ内で指定されるため、スタンダード MIDI メッセージの場合とは異なり、status の下位 4 ビットにはチャンネル番号が含まれない。したがって、status はノートオフの場合に &H80、ノートオンの場合に &H90 などとなる。その他のステータス バイトについては、MIDI 規格を参照すること。


DirectMusicPerformance.SendNotePMSG

DirectMusicPerformance.SendNotePMSG メソッドは、音符に関する情報を含むパフォーマンス メッセージを送信する。

object.SendNotePMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    msg As DMUS_NOTE_PMSG)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
メッセージの送信先となるパフォーマンス チャンネル。
msg
音符に関する情報を含む DMUS_NOTE_PMSG 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータが DMUS_PMSGF_REFTIME に設定されている場合、このメッセージは即座に送り出すものとしてキューに挿入される。

参照

ミュージック値と MIDI 音符


DirectMusicPerformance.SendPatchPMSG

DirectMusicPerformance.SendPatchPMSG メソッドは、MIDI パッチの変更に関する情報を含むパフォーマンス メッセージを送信する。

object.SendPatchPMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    instrument As Byte, _
    byte1 As Byte, _
    byte2 As Byte)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
メッセージの送信先となるパフォーマンス チャンネル。
instrument
チャンネルに割り当てるパッチ番号。
byte1
バンク セレクトの上位バイト。
byte2
バンク セレクトの下位バイト。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータが DMUS_PMSGF_REFTIME に設定されている場合、このメッセージは即座に送り出すものとしてキューに挿入される。


DirectMusicPerformance.SendTempoPMSG

DirectMusicPerformance.SendTempoPMSG メソッドは、テンポの変更に関する情報を含むパフォーマンス メッセージを送信する。

object.SendTempoPMSG(lTime As Long, _
    flags As Long, _
    tempo As Double)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
tempo
新しいテンポ。1 分あたりの拍数で表す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータが DMUS_PMSGF_REFTIME に設定されている場合、このメッセージは即座に送り出すものとしてキューに挿入される。


DirectMusicPerformance.SendTimeSigPMSG

DirectMusicPerformance.SendCurvePMSG メソッドは、MIDI 曲線に関する情報を含むパフォーマンス メッセージを送信する。

object.SendTimeSigPMSG(lTime As Long, _
    flags As Long, _
    timeSig As DMUS_TIMESIGNATURE)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
timeSig
拍子記号に関する情報を含む DMUS_TIMESIGNATURE 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータが DMUS_PMSGF_REFTIME に設定されている場合、このメッセージは即座に送り出すものとしてキューに挿入される。


DirectMusicPerformance.SendTransposePMSG

DirectMusicPerformance.SendTransposePMSG メソッドは、転調を開始させるパフォーマンス メッセージを送信する。

object.SendTransposePMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    transpose As Integer)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
転調が行われる P チャンネル。
transpose
音符が転調される半音の数。負の値であってもよい。音符の転調によって、スタンダード MIDI の範囲 0 ～ 127 より外側に達した場合は、その音符は演奏されない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータが DMUS_PMSGF_REFTIME に設定されている場合、このメッセージは即座に送り出すものとしてキューに挿入される。


DirectMusicPerformance.SetBumperLength

DirectMusicPerformance.SetBumperLength メソッドは、メッセージがポート バッファに置かれてから、ポートによる処理が開始されるまでの時間を設定する。

object.SetBumperLength(lMilliSeconds As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lMilliSeconds
バンパーの希望の長さ。ミリ秒単位で指定する。デフォルト値は 50 である。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance.GetBumperLength、DirectMusicPerformance.SetPrepareTime


DirectMusicPerformance.SetMasterAutoDownload

DirectMusicPerformance.SetMasterAutoDownload メソッドは、音色の自動ダウンロードをオンまたはオフに切り替える。

object.SetMasterAutoDownload(b As Boolean)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
b
自動ダウンロードをオンにする場合は True、オフにする場合は False を指定する。デフォルト値は False である。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance.GetMasterAutoDownload、DirectMusicSegment.SetAutoDownloadEnable


DirectMusicPerformance.SetMasterGrooveLevel

DirectMusicPerformance.SetMasterGrooveLevel メソッドは、パフォーマンス内のすべてのグルーブ レベルに加算される値を設定する。

object.SetMasterGrooveLevel(level As Integer)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
level
グルーブ レベルに加算される値。-99 ～ 99 の範囲で指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_OUTOFMEMORY

参照

DirectMusicPerformance.GetMasterGrooveLevel

注意

調整されたグルーブ レベルは、常に 1 ～ 100 の範囲にある。


DirectMusicPerformance.SetMasterTempo

DirectMusicPerformance.SetMasterTempo メソッドは、テンポに適用されるスケーリング係数を設定する。

object.SetMasterTempo(tempo As Single)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
tempo
希望のマスタ テンポ。0.25 ～ 2.0 の範囲で指定する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

マスタ テンポはデフォルトで 1 が設定される。値が 0.5 の場合テンポは半分になり、2.0 の場合は 2 倍になる。

参照

DirectMusicPerformance.GetMasterTempo


DirectMusicPerformance.SetMasterVolume

DirectMusicPerformance.SetMasterVolume メソッドは、パフォーマンスのマスタ ボリュームを調整する。

object.SetMasterVolume(vol As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
vol
マスタ ボリュームの調整。1/100 dB (デシベル) 単位で指定する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

マスタ ボリュームは、パフォーマンス全体のデフォルト ボリュームに適用される増幅係数または減衰係数である。設定できる値の範囲はポートによって決まる。

参照

DirectMusicPerformance.GetMasterVolume


DirectMusicPerformance.SetNotificationHandle

DirectMusicPerformance.SetNotificationHandle メソッドは、通知のイベント ハンドルを設定する。シグナルが送信されたら、アプリケーションは DirectMusicPerformance.GetNotificationPMsg メソッドを呼び出して、通知イベントを取り出さなければならない。

object.SetNotificationHandle(hnd As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
hnd
イベント ハンドル。既存のハンドルを消去する場合は 0 を指定する。

参照

DirectXEvent


DirectMusicPerformance.SetPort

DirectMusicPerformance.SetPort メソッドは、パフォーマンスのアクティブ ポートを設定する。このメソッドは、パフォーマンスを初期化した後、および任意の音色をダウンロードまたは任意のセグメントを演奏する前に呼び出さなければならない。

object.SetPort(index As Long, numGroups As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
index
ポートのインデックス。1 ～ DirectMusicPerformance.GetPortCount が返す値の範囲で指定しなければならない。デフォルト ポートの場合は -1 を指定する。
numGroups
ポート上のチャンネル グループの数。lMaxChannelGroups メンバで報告されるチャンネル グループの数以下でなければならない。このメンバは、DirectMusicPerformance.GetPortCaps メソッドによって返される DMUS_PORTCAPS 型のメンバである。

注意

各チャンネル グループは 16 個のチャンネルで構成される。十分な数のチャンネル グループを割り当て、演奏するセグメント内にすべてのパフォーマンス チャンネルが収まるようにする。MIDI ファイルの場合は、1 つのチャンネル グループで十分である。Microsoft Software Synthesizer は、最大 1,000 個までのチャンネル グループをサポートする。


DirectMusicPerformance.SetPrepareTime

DirectMusicPerformance.SetPrepareTime メソッドは、メッセージが準備されてから、処理され、スピーカから聞こえるまでのだいたいの時間を設定する。

object.SetPrepareTime(lMilliSeconds As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
lMilliSeconds
準備時間の長さ。ミリ秒単位で指定する。デフォルト値は 1,000 である。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance.GetPrepareTime、DirectMusicPerformance.SetBumperLength


DirectMusicPerformance.Stop

DirectMusicPerformance.Stop メソッドは、1 つまたは複数のセグメントの再生を停止する。

object.Stop(segment As DirectMusicSegment, _
    segmentState As DirectMusicSegmentState, _
    mtTime As Long, _
    lFlags As Long)

パラメータ

object
DirectMusicPerformance オブジェクトを表すオブジェクト式。
segment
演奏を停止する DirectMusicSegment オブジェクト。このセグメントに基づくすべてのセグメント状態は、mtTime の時点で停止される。「注意」を参照すること。
segmentState
演奏を停止するセグメントのインスタンスを表す DirectMusicSegmentState オブジェクト。「注意」を参照すること。
mtTime
セグメント、セグメント状態、またはその両方を停止するミュージックタイム。このタイムが過去のタイムである場合や、値として 0 を指定した場合は、要求したセグメントとセグメント状態の演奏が即座に停止される。
lFlags
演奏の停止タイムを指定するフラグ。境界は現在のプライマリ セグメントに関連する。次の値のいずれかを使わなければならない。
0
即座に停止する。
DMUS_SEGF_GRID
次のグリッド境界または mtTime の後に停止する。
DMUS_SEGF_MEASURE
次の小節境界または mtTime の後に停止する。
DMUS_SEGF_BEAT
次の拍境界または mtTime の後に停止する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

segment と segmentState の両方が NULL である場合、すべての音楽は停止し、現在キューに置かれているすべてのセグメントが解放される。segment と segmentState のどちらかが NULL ではない場合、指定されたセグメント状態がパフォーマンスから削除される。

すべてのパラメータに NULL または 0 を設定すると、すべての演奏が即座に停止し、コントローラ リセット メッセージおよびノートオフ メッセージが、マップされたすべてのパフォーマンス チャンネルに送信される。

参照

DirectMusicPerformance.PlaySegment、CONST_DMUS_SEGF_FLAGS


DirectMusicSegment

DirectMusicSegment クラスのオブジェクトは、1 曲の音楽または 1 つのテンプレートを表す。

セグメントは通常、DirectMusicLoader.LoadSegment と DirectMusicLoader.LoadSegmentFromResource の各メソッドを呼び出すことによってロードされる。また、DirectMusicComposer オブジェクトのメソッドを使ってミュージック要素からアレンジしたり、DirectMusicSegment.Clone メソッドを使って既存のセグメントから作成したりすることもできる。

DirectMusicSegment オブジェクトのメソッドは、以下のグループにまとめることができる。

タイミングとループ | GetLength
 | GetLoopPointStart
 | GetLoopPointEnd
 | GetRepeats
 | GetStartPoint
 | SetLength
 | SetLoopPoints
 | SetRepeats
 | SetStartPoint
複製 | Clone
音色 | ConnectToCollection
 | Download
 | Unload
パラメータ | SetAutoDownloadEnable
 | SetStandardMidiFile
 | SetTempoEnable
 | SetTimeSigEnable


DirectMusicSegment.Clone

DirectMusicSegment.Clone メソッドは、セグメントのすべてまたはパートのコピーを作成する。

object.Clone(mtStart As Long, _
    mtEnd As Long) As DirectMusicSegment

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
mtStart
複製開始パート。ミュージック タイムで指定する。0 未満の場合や、セグメントの長さを超える場合は、0 が使用される。
mtEnd
複製終了パート。ミュージック タイムで指定する。この値がセグメントの最後を超える場合は、セグメントの最後までコピーされる。0 または mtStart 未満の場合も、最後までコピーされる。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_OUTOFMEMORY が設定される。

注意

DirectMusicSegment.SetStartPoint と DirectMusicSegment.SetLoopPoints の各メソッドによって設定された開始ポイントとループ ポイントは、クローンの内部でデフォルト値 (開始ポイントは 0、ループ ポイントはセグメントの終わりを意味する 0) に設定される。反復回数も 0 にリセットされる。

スタイルベースのセグメントは、mtStart が 0 より大きい場合、小節境界上になければならない。


DirectMusicSegment.ConnectToCollection

DirectMusicSegment.ConnectToCollection メソッドは、セグメントを DLS 音色コレクションに関連付ける。このコレクションは、DirectMusicSegment.Download メソッドを呼び出したときにダウンロードされるコレクションである。

object.ConnectToCollection(c As DirectMusicCollection)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
c
セグメントの演奏で使用される音色を表す DirectMusicCollection オブジェクト。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND

注意

デフォルトでは、Gm.dls ファイル内の General MIDI コレクションが使用される。このメソッドを呼び出す必要があるのは、セグメントをカスタムな音色を使って演奏するときだけである。


DirectMusicSegment.Download

DirectMusicSegment.Download メソッドは、ポートが音色を演奏できるように、セグメントに関連付けられたコレクションをダウンロードする。

object.Download(performance As DirectMusicPerformance)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
performance
ポートに現在音色がダウンロードされている DirectMusicPerformance オブジェクト。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment.ConnectToCollection、DirectMusicSegment.Unload、DirectMusicSegment.SetAutoDownloadEnable


DirectMusicSegment.GetLength

DirectMusicSegment.GetLength メソッドは、セグメントの長さを取り出す。

object.GetLength() As Long

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。

戻り値

成功すれば、セグメントの長さをミュージック タイムで返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

何らかの理由でセグメントの長さが設定されていなかった場合、このメソッドは 0 を返す。

参照

DirectMusicSegment.SetLength


DirectMusicSegment.GetLoopPointEnd

DirectMusicSegment.GetLoopPointEnd メソッドは、反復セクションが終了するセグメント内のポイントを取り出す。

object.GetLoopPointEnd() As Long

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ループの終了ポイントをミュージック タイムで返す。この値が 0 の場合、セグメント全体がループする。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DirectMusicSegment.SetRepeats メソッドを使って反復回数が 1 以上に設定されていない限り、このセクションは反復しない。デフォルトでは、セグメント全体が反復する。

参照

DirectMusicSegment.GetLoopPointStart、DirectMusicSegment.SetLoopPoints、DirectMusicSegment.GetRepeats


DirectMusicSegment.GetLoopPointStart

DirectMusicSegment.GetLoopPointStart メソッドは、反復セクションが開始するセグメント内のポイントを取り出す。

object.GetLoopPointStart() As Long

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ループの開始ポイントをミュージック タイムで返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DirectMusicSegment.SetRepeats メソッドを使って反復回数が 1 以上に設定されていない限り、このセクションは反復しない。デフォルトでは、セグメント全体が反復する。

参照

DirectMusicSegment.GetLoopPointEnd、DirectMusicSegment.SetLoopPoints、DirectMusicSegment.GetRepeats


DirectMusicSegment.GetRepeats

DirectMusicSegment.GetRepeats メソッドは、セグメントのループ部分に設定されている反復回数を取り出す。

object.GetRepeats() As Long

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。

戻り値

成功すれば、ループ部分の反復回数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment.SetRepeats、DirectMusicSegment.SetLoopPoints、DirectMusicSegment.GetLoopPointStart、DirectMusicSegment.GetLoopPointEnd、DirectMusicSegmentState.GetRepeats


DirectMusicSegment.GetStartPoint

DirectMusicSegment.GetStartPoint メソッドは、セグメントが DirectMusicPerformance.PlaySegment メソッドに応答して演奏を開始するポイントを取り出す。

object.GetStartPoint() As Long

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。

戻り値

成功すれば、セグメントの開始ポイントをミュージック タイムで返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment.SetStartPoint


DirectMusicSegment.SetAutoDownloadEnable

DirectMusicSegment.SetAutoDownloadEnable メソッドは、セグメントに関連付けられたコレクション内の音色の自動ダウンロードとアンロードを有効または無効にする。

object.SetAutoDownloadEnable(b As Boolean)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
b
自動ダウンロードを有効にする場合は True、無効にする場合は False を指定する。

注意

自動ダウンロードはデフォルトで無効になっている。自動ダウンロードを有効にすると、音色はセグメントの演奏時に自動的にダウンロードされ、演奏を停止するとアンロードされる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND

参照

DirectMusicSegment.Download


DirectMusicSegment.SetLength

DirectMusicSegment.SetLength メソッドは、セグメントの長さを設定する。

object.SetLength(mtLength As Long)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
mtLength
セグメントの希望の長さ。ミュージック タイムで指定する。0 より大きい値でなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_OUT_OF_RANGE が設定される。

注意

ほとんどの場合、アプリケーションは長さを設定する必要はない。セグメントのロード時に自動的に設定されるためである。ただし、このメソッドを使って、セグメントの長さを短くすることができる。

参照

DirectMusicSegment.GetLength


DirectMusicSegment.SetLoopPoints

DirectMusicSegment.SetLoopPoints メソッドは、セグメント内のループ部分の開始ポイントと終了ポイントを設定する。反復回数は DirectMusicSegment.SetRepeats メソッドによって設定される。

object.SetLoopPoints(mtStart As Long, mtEnd As Long)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
mtStart
ループの開始ポイント。ミュージック タイムで指定する。
mtEnd
ループの終了ポイント。ミュージック タイムで指定する。値 0 は、セグメント全体をループさせることを意味する。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_OUT_OF_RANGE が設定される。

注意

セグメントの演奏時には、開始タイムから mtEnd まで演奏し、mtStart にループする。次に、ループ部分を DirectMusicSegment.SetRepeats によって設定される回数だけ反復し、最後まで演奏する。

デフォルト値は、最初から最後までセグメント全体をループさせるように設定されている。

mtStart の値がセグメントの長さ以上の場合、または mtEnd の値がセグメントの長さを超える場合、メソッドは失敗する。mtEnd が 0 の場合、mtStart も 0 でなければならない。

このメソッドは、このセグメントから作成された、現在演奏中のセグメント状態に影響を及ぼすことはない。

再利用されるセグメントは、内部キャッシュからロードされる可能性もある。その場合、そのセグメントのループ ポイントは、最後に設定された値と同じ値を持つ。オブジェクトを解放またはリセットする前には、ループ ポイントを 0 にリセットするとよい。

参照

DirectMusicSegment.GetLoopPointStart、DirectMusicSegment.GetLoopPointEnd、DirectMusicSegment.SetRepeats


DirectMusicSegment.SetRepeats

DirectMusicSegment.SetRepeats メソッドは、セグメントのループ部分の反復回数を設定する。

object.SetRepeats(lRepeats As Long)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
lRepeats
反復回数。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment.GetRepeats、DirectMusicSegment.SetLoopPoints


DirectMusicSegment.SetStandardMidiFile

DirectMusicSegment.SetStandardMidiFile メソッドは、セグメントが、DirectMusic 用に特別にオーサリングされたものではなく、スタンダード MIDI ファイルに基づいていることを DirectMusic に通知する。このメソッドを呼び出すと、セグメントの演奏時に特定のイベントが適切に処理される。

object.SetStandardMidiFile()

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドは、音色をダウンロードする前に呼び出さなければならない。


DirectMusicSegment.SetStartPoint

DirectMusicSegment.SetStartPoint メソッドは、セグメントが DirectMusicPerformance.PlaySegment メソッドの呼び出しに応答して演奏を開始するポイントを設定する。

object.SetStartPoint(mtStart As Long)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
mtStart
セグメントの演奏開始ポイント。ミュージック タイムで指定する。この値が 0 未満またはセグメントの長さより大きい場合、開始ポイントは 0 に設定される。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_OUT_OF_RANGE が設定される。

注意

デフォルトの開始ポイントは 0 であり、セグメントの先頭から開始することを意味する。

mtStart の値がセグメントの長さ以上の場合、この呼び出しは失敗する。

このメソッドは、このセグメントから作成された、現在演奏中のセグメント状態に影響を及ぼすことはない。

再利用されるセグメントは、内部キャッシュからロードされる可能性もある。その場合、そのセグメントの開始ポイントは、最後に設定された値と同じ値を持つ。オブジェクトを解放またはリセットする前には、開始ポイントを 0 に設定するとよい。

参照

DirectMusicSegment.GetStartPoint、DirectMusicSegmentState.GetStartPoint、DirectMusicSegment.SetLoopPoints


DirectMusicSegment.SetTempoEnable

DirectMusicSegment.SetTempoEnable メソッドは、セグメントのテンポ メッセージを有効または無効にする。

object.SetTempoEnable(b As Boolean)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
b
テンポ メッセージを有効にする場合は True、無効にする場合は False を指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND


DirectMusicSegment.SetTimeSigEnable

DirectMusicSegment.SetTimeSigEnable メソッドは、セグメントの拍子記号メッセージを有効または無効にする。

object.SetTempoEnable(b As Boolean)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
b
拍子記号メッセージを有効にする場合は True、無効にする場合は False を指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND


DirectMusicSegment.Unload

DirectMusicSegment.Unload メソッドは、DirectMusicSegment.Download メソッドによってポートにダウンロードされた音色をアンロードする。

object.Unload(performance As DirectMusicPerformance)

パラメータ

object
DirectMusicSegment オブジェクトを表すオブジェクト式。
performance
ポートから現在音色がアンロードされている DirectMusicPerformance オブジェクト。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment.SetAutoDownloadEnable


DirectMusicSegmentState

DirectMusicSegmentState クラスは、セグメントのインスタンスに関する情報を取得するために使用される。DirectMusicPerformance.PlaySegment メソッドを呼び出すと、セグメントのインスタンスを表す DirectMusicSegmentState オブジェクトが作成され、アプリケーションはそのインスタンスに関する情報を取得できるようになる。このオブジェクトを DirectMusicPerformance のメソッドに渡して、セグメントのインスタンスが演奏中であるかどうかを判別したり、それを停止したりすることもできる。

このクラスは、以下のグループにまとめることができる。

情報 | GetRepeats
 | GetSeek
 | GetSegment
 | GetStartPoint
 | GetStartTime

参照

DirectMusicPerformance.GetSegmentState、DirectMusicPerformance.IsPlaying、DirectMusicPerformance.Stop


DirectMusicSegmentState.GetRepeats

DirectMusicSegmentState.GetRepeats メソッドは、セグメントのループ部分に設定されている反復回数を返す。

object.GetRepeats() As Long

パラメータ

object
DirectMusicSegmentState オブジェクトを表すオブジェクト式。

戻り値

成功すれば、反復回数を返す。値 0 は、そのセグメント全体を 1 回だけ演奏し、反復する部分がないことを意味する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment.SetRepeats


DirectMusicSegmentState.GetSeek

DirectMusicSegmentState.GetSeek メソッドは、セグメント状態内の現在のシーク ポインタを取り出す。シーク ポインタは、メッセージが生成されたセグメント内の最後のポイントの直後にある。

object.GetSeek() As Long

パラメータ

object
DirectMusicSegmentState オブジェクトを表すオブジェクト式。

戻り値

成功すれば、現在のシーク ポインタをミュージック タイムで返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

セグメントを停止すると、既に送信されたものの、ポート バッファのキューにまだ入れられていないメッセージは、フラッシュ (解放) される。したがって、セグメントを停止し、最後のシーク ポインタで再開すると、一部の音符が失われる。


DirectMusicSegmentState.GetSegment

DirectMusicSegmentState.GetSegment メソッドは、このセグメント状態を保持するセグメントを表すオブジェクトを返す。

object.GetSegment() As DirectMusicSegment

パラメータ

object
DirectMusicSegmentState オブジェクトを表すオブジェクト式。

戻り値

成功すれば DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicSegmentState.GetStartPoint

DirectMusicSegmentState.GetStartPoint メソッドは、演奏の開始に使われた、またはこれから使われるセグメントのオフセットを返す。

object.GetStartPoint() As Long

パラメータ

object
DirectMusicSegmentState オブジェクトを表すオブジェクト式。

戻り値

成功すれば、このセグメント状態の開始ポイントをミュージック タイムで返す。このセグメント状態を作成してから、セグメントの開始ポイントを変更した場合、返される値は DirectMusicSegment.GetStartPoint が返す値とは異なる場合がある。演奏中のセグメントの異なるインスタンスは、それぞれ異なる開始ポイントを持つことができる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment.SetStartPoint、DirectMusicSegmentState.GetStartTime


DirectMusicSegmentState.GetStartTime

DirectMusicSegmentState.GetStartTime メソッドは、セグメントが演奏された、またはこれから演奏される演奏タイムを取得する。

object.GetStartTime() As Long

パラメータ

object
DirectMusicSegmentState オブジェクトを表すオブジェクト式。

戻り値

成功すれば、セグメントのこのインスタンスの開始タイムをミュージック タイムで返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_BUFFER_EMPTY が設定される。

注意

セグメントの演奏が開始ポイント以外のほかのポイントから開始された場合、このメソッドが返す値から、DirectMusicSegmentState.GetStartPoint が返すタイムを引くことによって、このセグメントの開始タイムを取り出すことができる。

参照

DirectMusicSegment.SetStartPoint、DirectMusicSegment.GetStartPoint、DirectMusicSegmentState.GetStartPoint


DirectMusicStyle

DirectMusicStyle クラスのオブジェクトは、音楽パターンを演奏するときに必要になる情報をパフォーマンスに提供する。スタイルには通常バンドとモチーフが含まれ、コード マップが含まれる場合もあるため、DirectMusicStyle オブジェクトは、これらのオブジェクトにアクセスするためのメソッドも提供する。

オブジェクトは通常、DirectMusicLoader.LoadStyle または DirectMusicLoader.LoadStyleFromResource の各メソッドを使って取得する。現在の制御セグメントがスタイルに基づいている場合は、DirectMusicPerformance.GetStyle メソッドを使うことによって、オブジェクトをパフォーマンスから取得することもできる。

DirectMusicStyle クラスのメソッドは、以下のグループにまとめることができる。

バンド | GetBand
 | GetBandCount
 | GetBandName
 | GetDefaultBand
モチーフ | GetMotif
 | GetMotifCount
 | GetMotifName
時間 | GetTempo
 | GetTimeSignature


DirectMusicStyle.GetBand

DirectMusicStyle.GetBand メソッドは、名前を使ってバンド オブジェクトを取得する。

object.GetBand(name As String) As DirectMusicBand

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。
name
スタイルの作成者によってバンドに割り当てられた名前。

戻り値

成功すれば DirectMusicBand オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DMUS_E_FAIL が設定される。

参照

DirectMusicStyle.GetBandName、DirectMusicStyle.GetDefaultBand


DirectMusicStyle.GetBandCount

DirectMusicStyle.GetBandCount メソッドは、スタイル内で利用できるバンドの数を取得する。

object.GetBandCount() As Long

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。

戻り値

成功すれば、スタイル内のバンドの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle.GetBand、DirectMusicStyle.GetBandName


DirectMusicStyle.GetBandName

DirectMusicStyle.GetBandName メソッドは、スタイル内のバンドの名前を取得する。

object.GetBandName(index As Long) As String

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。
index
スタイル内のバンドのインデックス。1 ～ DirectMusicStyle.GetBandCount が返す値の範囲で指定する。

戻り値

成功すれば、スタイルの作成者によってバンドに割り当てられた名前を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle.GetBand


DirectMusicStyle.GetDefaultBand

DirectMusicStyle.GetDefaultBand メソッドは、スタイルのデフォルト バンドを取得する。

object.GetDefaultBand() As DirectMusicBand

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。
name
スタイルの作成者によってバンドに割り当てられた名前。

戻り値

成功すれば DirectMusicBand オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle.GetBand


DirectMusicStyle.GetMotif

DirectMusicStyle.GetMotif メソッドは、指定されたモチーフを含むセグメントを作成する。

object.GetMotif(name As String) As DirectMusicSegment

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。
name
スタイルの作成者によってモチーフに割り当てられた名前。

戻り値

成功すれば、モチーフを表す DirectMusicSegment オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle.GetMotifCount、DirectMusicStyle.GetMotifName


DirectMusicStyle.GetMotifCount

DirectMusicStyle.GetMotifCount メソッドは、スタイル内で利用できるモチーフの数を取得する。

object.GetMotifCount() As Long

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。

戻り値

成功すれば、スタイル内のモチーフの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicStyle.GetMotifName

DirectMusicStyle.GetMotifName メソッドは、スタイル内のモチーフの名前を取得する。

object.GetMotifName(index As Long) As String

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。
index
スタイル内のモチーフのインデックス。1 ～ DirectMusicStyle.GetMotifCount が返す値の範囲で指定する。

戻り値

成功すれば、スタイルの作成者によってモチーフに割り当てられた名前を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle.GetMotif


DirectMusicStyle.GetTempo

DirectMusicStyle.GetTempo メソッドは、スタイルの推奨テンポを取り出す。

object.GetTempo() As Double

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。

戻り値

成功すれば、推奨テンポを 1 分あたりの拍数で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectMusicStyle.GetTimeSignature

DirectMusicStyle.GetTimeSignature メソッドは、スタイルの拍子記号を取り出す。

object.GetTimeSignature(pTimeSig As DMUS_TIMESIGNATURE)

パラメータ

object
DirectMusicStyle オブジェクトを表すオブジェクト式。
pTimeSig
拍子記号に関する情報を受け取る DMUS_TIMESIGNATURE 型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


型

ここでは、DirectMusic for Visual Basic で使用される以下の型に関する情報を提供する。

  • DMUS_CURVE_PMSG
  • DMUS_NOTE_PMSG
  • DMUS_NOTIFICATION_PMSG
  • DMUS_PORTCAPS
  • DMUS_TIMESIGNATURE


DMUS_CURVE_PMSG

DMUS_CURVE_PMSG 型は、MIDI 曲線メッセージに関する情報を保持する。

Type DMUS_CURVE_PMSG
    beat As Byte
    ccData As Byte
    curveShape As Byte
    endValue As Integer
    flags As Byte
    grid As Byte
    measure As Integer
    mtDuration As Long
    mtOriginalStart As Long
    mtResetDuration As Long
    offset As Integer
    resetValue As Integer
    startValue As Integer
    type As Byte
End Type

メンバ

beat
この曲線が発生する (小節内の) 拍数。
ccData
コントロール チェンジ タイプの場合は、CC 番号を指定する。
curveShape
曲線のシェイプ。このパラメータには、CONST_DMUS_CURVES 列挙型のいずれかの値を指定できる。
endValue
曲線の終了値。
flags
デフォルトのタイムに達したとき、または移行部が原因で無効化が発生したときに resetValue を設定しなければならない場合は、この値を DMUS_CURVE_RESET に設定する。この値を 0 に設定した場合は、曲線は新しい値に永続的にとどまる。
grid
この曲線が発生する拍からのグリッド オフセット。
measure
曲線が発生する小節。
mtDuration
曲線の持続時間。
mtOriginalStart
オリジナルの開始タイム。ミュージック タイムで指定する。メッセージを作成するときは 0 に設定しなければならない。それ以外の場合は、曲線のオリジナルの開始タイムに設定しなければならない。
mtResetDuration
曲線が終了した後、リセット値を設定するまでの時間。ミュージック タイムで指定する。
offset
曲線が発生するグリッドからのオフセット。ミュージック タイムで指定する。
resetValue
曲線のリセット値。mtResetDuration の経過後、またはフラッシュ (解放) や無効化の際に設定される。
startValue
曲線の開始値。
type
曲線のタイプ。このパラメータには、CONST_DMUS_CURVET 列挙型のいずれかの値を指定できる。

参照

DirectMusicPerformance.SendCurvePMSG


DMUS_NOTE_PMSG

DMUS_NOTE_PMSG 型は、音楽の音符イベント用のデータによって構成されている。

Type DMUS_NOTE_PMSG
    beat as Byte
    durRange As Byte
    flags As Byte
    grid As Byte
    measure As Integer
    midiValue As Byte
    mtDuration As Long
    musicValue As Integer
    offset As Integer
    playModeFlags As Byte
    subChordLevel As Byte
    timeRange As Byte
    velocity As Byte
    velRange As Byte
End Type

メンバ

beat
この音符が発生する (小節内の) 拍数。
durRange
ランダム持続時間の範囲。
flags
DMUS_NOTEF_NOTEON に設定しなければならない。「注意」を参照すること。
grid
この音符が発生する拍からのグリッド オフセット。
measure
音符が発生する小節。
midiValue
musicValue から変換された MIDI 音符の値。
mtDuration
音符の持続時間。
musicValue
音符の記述。ほとんどの演奏モードでは、以下に示すように、パックされた 4 ビット値の配列である。

-2 ～ 14 の範囲のオクターブ。この音符は、1 オクターブの 12 倍で上下に転調される。

0 ～ 15 の範囲のコード位置。ただし、3 を超えてはならない。コード内の最初の位置は 0 である。

0 ～ 15 の範囲のスケール位置。通常は 0 ～ 2 の範囲だが、1 音符のコードにし、コードの上のすべてをスケール位置として解釈することも可能。

-8 ～ 7 の範囲の変化音。通常は -2 ～ 2 の範囲。これは、スケールから音符を取り出すオフセットを表す。

固定演奏モードでは、ミュージック値は 0 ～ 127 の範囲にある MIDI 音符の値である。

offset
音符が発生するグリッドからのオフセット。ミュージック タイムで指定する。
playModeFlags
ミュージック値がコードとサブコードにどのように関連するかを決定する演奏モード。値のリストについては、「CONST_DMUS_PLAYMODE_FLAGS」を参照すること。
subChordLevel
音符が使用するサブコード レベル。
timeRange
ランダム時間の範囲。
velocity
音符のベロシティ。
velRange
ベロシティをランダム化する範囲。

注意

音符メッセージを送信するアプリケーションは、flags、midiValue、mtDuration、および velocity の各メンバだけに値を提供しなければならない。その他のメンバはツールだけによって利用される。ツールは DirectX for Visual Basic でサポートされていない。

アプリケーションは通常、flags を DMUS_NOTEF_NOTEON に設定する。アプリケーションはノートオフ メッセージを送信する必要はない。DirectMusic 出力ツールは、DMUS_NOTE_PMSG を受け取り、DMUS_NOTEF_NOTEON が設定されていることを認識すると、フラグを消去し、タイム スタンプに mtDuration を加え、メッセージを要求する。その結果、適切なタイムに音符は終了する。

ただし、アプリケーションは、flags が 0 にセットされた同じチャンネル上の同じ音符を送信することによって、音符を途中で停止することができる。

参照

DirectMusicPerformance.SendNotePMSG、ミュージック値と MIDI 音符


DMUS_NOTIFICATION_PMSG

DMUS_NOTIFICATION_PMSG 型は、パフォーマンスによって送信された通知メッセージに関する情報を保持する。

Type DMUS_NOTIFICATION_PMSG
    ctTime As Long
    lField1 As Long
    lField2 As Long
    lNotificationOption As Long
    lNotificationType As Long
    mtTime As Long
End Type

メンバ

ctTime
メッセージのタイム スタンプ。クロック タイムで指定する。
lField1
通知タイプに固有の追加データ。DMUS_NOTIFY_ON_MEASUREANDBEAT 通知の場合、このメンバは小節内の拍番号を返す。
lField2
通知タイプに固有の追加データ。将来の使用またはアプリケーションによって定義される使用に備えて予約されている。
lNotificationOption
CONST_DMUS_NOTIFICATION_SUBTYPE 列挙型の通知サブタイプの識別子。

通知タイプが DMUS_NOTIFY_ON_SEGMENT の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_SEGABORT
セグメントが DirectMusicPerformance.Stop によって停止された。
DMUS_NOTIFICATION_SEGALMOSTEND
セグメントが終了タイムから準備時間を引いたタイムに達した。
DMUS_NOTIFICATION_SEGEND
セグメントが終了した。
DMUS_NOTIFICATION_SEGLOOP
セグメントがループした。
DMUS_NOTIFICATION_SEGSTART
セグメントが開始した。

通知タイプが DMUS_NOTIFY_ON_COMMAND の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_GROOVE
グルーブ チェンジ。
DMUS_NOTIFICATION_EMBELLISHMENT
装飾コマンド (イントロ、フィル、ブレーク、またはエンド)。

通知タイプが DMUS_NOTIFY_ON_PERFORMANCE の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_MUSICSTARTED
再生が開始した。
DMUS_NOTIFICATION_MUSICSTOPPED
再生が停止した。

通知タイプが DMUS_NOTIFY_ON_MEASUREANDBEAT の場合、このメンバは DMUS_NOTIFICATION_MEASUREBEAT を保持する。その他のサブタイプは定義されない。

通知タイプが DMUS_NOTIFY_ON_CHORD の場合、このメンバは DMUS_NOTIFICATION_CHORD を保持する。その他のサブタイプは定義されない。

lNotificationType
CONST_DMUS_NOTIFICATION_TYPE 列挙型の通知タイプの識別子。
mtTime
メッセージのタイム スタンプ。ミュージック タイムで指定する。

参照

DirectMusicPerformance.AddNotificationType、DirectMusicPerformance.GetNotificationPMSG


DMUS_PORTCAPS

DMUS_PORTCAPS 型は、ポートの能力に関する情報を返す。この型は、DirectMusicPerformance.GetPortCaps メソッドに渡される。

Type DMUS_PORTCAPS
    lClass as Long
    lEffectFlags As Long
    lFlags As Long
    lMaxAudioChannels As Long
    lMaxChannelGroups As Long
    lMaxVoices As Long
    lMemorySize As Long
    lType As Long
End Type

メンバ

lClass
このポートのクラス。CONST_DMUS_PC_CLASS 列挙型のいずれかのメンバである。
lEffectFlags
ポート上でどのようなオーディオ エフェクトを利用できるのかを示す、CONST_DMUS_EFFECT_FLAGS 列挙型のフラグ。
lFlags
ポートのさまざまな能力を記述するフラグ。「CONST_DMUS_PC_FLAGS」を参照すること。
lMaxAudioChannels
ポートによってレンダリングできるオーディオ チャンネルの最大数。このパラメータが返されることをドライバがサポートしていない場合、値は -1 でもよい。
lMaxChannelGroups
このポートがサポートするチャンネル グループの最大数。1 つのチャンネル グループは、16 個の MIDI チャンネルから成るセットである。
lMaxVoices
このポートを開いたときに割り当てのできる発音の最大数。このパラメータが返されることをドライバがサポートしていない場合、値は -1 でもよい。
lMemorySize
DLS 音色の保存に利用できるメモリの量。ポートがシステム メモリを使っていて、利用可能なシステム メモリによりその量が制限を受ける場合、このフィールドは DMUS_PC_SYSTEMMEMORY を保持する。
lType
このポートのタイプ。「CONST_DMUS_PORT_TYPE」を参照すること。


DMUS_TIMESIGNATURE

DMUS_TIMESIGNATURE 型は、拍子記号に関する情報を保持する。この型は、DirectMusicPerformance.GetTimeSig と DirectMusicStyle.GetTimeSignature の各メソッドに渡され、DirectMusicPerformance.SendTimeSigPMSG メソッドが送信するメッセージ内でも使用される。

Type DMUS_TIMESIGNATURE
    beat As Byte
    beatsPerMeasure As Byte
    gridsPerBeat As Integer
    mtTime As Long
End Type

メンバ

beat
拍子記号の分母。
beatsPerMeasure
拍子記号の分子。
gridsPerBeat
拍あたりのグリッド (小分割)。この値は、特定の音楽イベントのタイミング分解能を決定する。たとえば、DMUS_SEGF_GRID フラグを使ったセグメントの挿入が挙げられる (「CONST_DMUS_SEGF_FLAGS」を参照)。
mtTime
この拍子記号が発生するミュージック タイム。


列挙型

DirectMusic for Visual Basic では、定数をグループ化する列挙型を使って、Microsoft® Visual Studio® 開発環境のステートメント終了機能を活用する。

ここでは、以下の列挙型に関するリファレンス情報を提供する。

  • CONST_DMUS
  • CONST_DMUS_COMMANDT_TYPES
  • CONST_DMUS_COMPOSEF_FLAGS
  • CONST_DMUS_CURVE_FLAGS
  • CONST_DMUS_CURVES
  • CONST_DMUS_CURVET
  • CONST_DMUS_EFFECT_FLAGS
  • CONST_DMUS_NOTEF_FLAGS
  • CONST_DMUS_NOTIFICATION_SUBTYPE
  • CONST_DMUS_NOTIFICATION_TYPE
  • CONST_DMUS_PC_CLASS
  • CONST_DMUS_PC_FLAGS
  • CONST_DMUS_PLAYMODE_FLAGS
  • CONST_DMUS_PMSGF_FLAGS
  • CONST_DMUS_PORT_TYPE
  • CONST_DMUS_SEGF_FLAGS
  • CONST_DMUS_SHAPET_TYPES
  • CONST_DMUSERR


CONST_DMUS

CONST_DMUS 列挙型は、DirectMusic で使用されるさまざまな定数を保持する。

Enum CONST_DMUS
    DMUS_MAXSUBCHORD = 8
    DMUS_TEMPO_MAX = 350 (&H15E)
    DMUS_TEMPO_MIN =  10
End Enum
DMUS_MAXSUBCHORD
コード内で許可されるサブコードの最大数。
DMUS_TEMPO_MAX
最大テンポ。1 分あたりの拍数で表す。
DMUS_TEMPO_MIN
最小テンポ。1 分あたりの拍数で表す。


CONST_DMUS_COMMANDT_TYPES

CONST_DMUS_COMMANDT_TYPES 列挙型のメンバは、音楽パターンを確立するコマンドを表す。これらのメンバは、DirectMusicComposer.AutoTransition と DirectMusicComposer.ComposeTransition の各メソッドの lCommand パラメータ内で使用され、DirectMusicPerformance.GetCommand メソッドによって返される。

Type CONST_DMUS_COMMANDT_TYPES
    DMUS_COMMANDT_BREAK       = 3
    DMUS_COMMANDT_END         = 4
    DMUS_COMMANDT_ENDANDINTRO = 5
    DMUS_COMMANDT_FILL        = 1
    DMUS_COMMANDT_GROOVE      = 0
    DMUS_COMMANDT_INTRO       = 2
End Enum
DMUS_COMMANDT_BREAK
コマンドは変換点である。
DMUS_COMMANDT_END
コマンドは終了部である。
DMUS_COMMANDT_ENDANDINTRO
コマンドは終了部と導入部である。
DMUS_COMMANDT_FILL
コマンドはフィルである。
DMUS_COMMANDT_GROOVE
コマンドはグルーブ コマンドである。
DMUS_COMMANDT_INTRO
コマンドは導入部である。


CONST_DMUS_COMPOSEF_FLAGS

CONST_DMUS_COMPOSEF_FLAGS 列挙型のメンバは、DirectMusicComposer.AutoTransition と DirectMusicComposer.ComposeTransition の各メソッドの lFlags パラメータ内で使用される。

Enum CONST_DMUS_COMPOSEF_FLAGS
    DMUS_COMPOSEF_AFTERPREPARETIME = 64 (&H40)
    DMUS_COMPOSEF_ALIGN             = 1
    DMUS_COMPOSEF_BEAT             = 16 (&H10)
    DMUS_COMPOSEF_GRID              = 8
    DMUS_COMPOSEF_IMMEDIATE         = 4
    DMUS_COMPOSEF_LONG           = 8192 (&H2000)
    DMUS_COMPOSEF_MEASURE          = 32 (&H20)
    DMUS_COMPOSEF_MODULATE       = 4096 (&H1000)
    DMUS_COMPOSEF_NONE              = 0
    DMUS_COMPOSEF_OVERLAP           = 2
End Enum
DMUS_COMPOSEF_AFTERPREPARETIME
AutoTransition のみ。移行部を挿入するときは、DMUS_SEGF_AFTERPREPARETIME フラグ (「CONST_DMUS_SEGF_FLAGS」を参照) を使用する。
DMUS_COMPOSEF_ALIGN
移行部を、現在演奏されているセグメントの拍子記号に揃える。現在実装されていない。
DMUS_COMPOSEF_BEAT
AutoTransition のみ。拍の境界から移行部を開始する。
DMUS_COMPOSEF_GRID
AutoTransition のみ。グリッド境界から移行部を開始する。
DMUS_COMPOSEF_IMMEDIATE
AutoTransition のみ。ミュージック タイムまたはクロック タイムの境界から移行部を開始する。
DMUS_COMPOSEF_MEASURE
AutoTransition のみ。小節境界から移行部を開始する。
DMUS_COMPOSEF_LONG
長い移行部をアレンジする。このフラグがセットされていない場合、ComposeTransition または AutoTransition の lCommand パラメータで終了部を指定し、スタイルに 1 小節より長い終了部が含まれていない限り、移行部の長さは最大でも 1 小節である。このフラグがセットされている場合、移行部の長さは 1 小節増える。
DMUS_COMPOSEF_MODULATE
toSeg のコードを使って、fromSeg から toSeg へスムーズに変化する移行部をアレンジする。
DMUS_COMPOSEF_NONE
フラグなし。デフォルトでは、移行部は小節境界から開始する。
DMUS_COMPOSEF_OVERLAP
移行部を toSeg に重ねる (オーバーラップ)。現在実装されていない。


CONST_DMUS_CURVE_FLAGS

CONST_DMUS_CURVE_FLAGS 列挙型は、DMUS_CURVE_PMSG 型で使用される 1 つの定数を保持する。

Enum CONST_DMUS_CURVE_FLAGS
    DMUS_CURVE_RESET = 1
End Enum
DMUS_CURVE_RESET
デフォルトのタイムに達したとき、または移行部が原因で無効化が発生したときにリセット値を設定しなければならない。


CONST_DMUS_CURVES

CONST_DMUS_CURVES 列挙型のメンバは、DMUS_CURVE_PMSG 型内で曲線のシェイプを定義する際に使用される。

Enum CONST_DMUS_CURVES
    DMUS_CURVES_EXP =     2
    DMUS_CURVES_INSTANT = 1
    DMUS_CURVES_LINEAR =  0
    DMUS_CURVES_LOG =     3
    DMUS_CURVES_SINE =    4
End Enum
DMUS_CURVES_EXP
指数曲線シェイプ。
DMUS_CURVES_INSTANT
即時曲線シェイプ (曲線の開始と終了がほとんど同時に発生する)。
DMUS_CURVES_LINEAR
線状曲線シェイプ。
DMUS_CURVES_LOG
対数曲線シェイプ。
DMUS_CURVES_SINE
正弦曲線シェイプ。


CONST_DMUS_CURVET

CONST_DMUS_CURVET 列挙型のメンバは、DMUS_CURVE_PMSG 型内で曲線のタイプを記述する際に使われる。

Enum CONST_DMUS_CURVET
    DMUS_CURVET_CCCURVE =  4
    DMUS_CURVET_MATCURVE = 5
    DMUS_CURVET_PATCURVE = 6
    DMUS_CURVET_PBCURVE =  3
End Enum
DMUS_CURVET_CCCURVE
コンティニュアス コントローラ曲線 (MIDI Control Change チャンネル発音メッセージ。ステータス バイトは &HBn。n はチャンネル番号を表す)。
DMUS_CURVET_MATCURVE
モノフォニック アフタータッチ曲線 (MIDI Channel Pressure チャンネル発音メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PATCURVE
ポリフォニック アフタータッチ曲線 (MIDI Poly Key Pressure チャンネル発音メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PBCURVE
ピッチベンド曲線 (MIDI Pitch Bend チャンネル発音メッセージ。ステータス バイトは &HEn)。


CONST_DMUS_EFFECT_FLAGS

CONST_DMUS_EFFECT_FLAGS 列挙型のメンバは、ポートがサポートするエフェクトの種類を指定するために DMUS_PORTCAPS 型内で使用される。

Enum CONST_DMUS_EFFECT_FLAGS
    DMUS_EFFECT_CHORUS = 2
    DMUS_EFFECT_NONE   = 0
    DMUS_EFFECT_REVERB = 1
End Enum
DMUS_EFFECT_CHORUS
ポートはコーラスをサポートする。
DMUS_EFFECT_NONE
ポートはどのエフェクトもサポートしない。
DMUS_EFFECT_REVERB
ポートはリバーブをサポートする。


CONST_DMUS_NOTEF_FLAGS

CONST_DMUS_NOTEF_FLAGS 列挙型は、音符メッセージで使用される 1 つの定数を保持する。

Enum CONST_DMUS_NOTEF_FLAGS
    DMUS_NOTEF_NOTEON = 1
End Enum
DMUS_NOTEF_NOTEON
「DMUS_NOTE_PMSG」の「注意」を参照すること。


CONST_DMUS_NOTIFICATION_SUBTYPE

CONST_DMUS_NOTIFICATION_SUBTYPE 列挙型のメンバは、通知メッセージ内で報告される音楽イベントに関する情報を提供する。

Enum CONST_DMUS_NOTIFICATION_SUBTYPE
    DMUS_NOTIFICATION_CHORD =         0
    DMUS_NOTIFICATION_EMBELLISHMENT = 1
    DMUS_NOTIFICATION_GROOVE =        0
    DMUS_NOTIFICATION_MEASUREBEAT =   0
    DMUS_NOTIFICATION_MUSICSTARTED =  0
    DMUS_NOTIFICATION_MUSICSTOPPED =  1
    DMUS_NOTIFICATION_SEGABORT =      4
    DMUS_NOTIFICATION_SEGALMOSTEND =  2
    DMUS_NOTIFICATION_SEGEND =        1
    DMUS_NOTIFICATION_SEGLOOP =       3
    DMUS_NOTIFICATION_SEGSTART =      0
End Enum

値の説明については、「DMUS_NOTIFICATION_PMSG」を参照すること。


CONST_DMUS_NOTIFICATION_TYPE

CONST_DMUS_NOTIFICATION_TYPE 列挙型のメンバは、通知タイプを識別する。これらのメンバは、DirectMusicPerformance.AddNotificationType と DirectMusicPerformance.RemoveNotificationType の各メソッドに渡され、DirectMusicPerformance.GetNotificationPMSG が取り出すメッセージ内の通知タイプを識別する。

Enum CONST_DMUS_NOTIFICATION_TYPE
    DMUS_NOTIFY_ON_CHORD          = 1
    DMUS_NOTIFY_ON_COMMAND        = 2
    DMUS_NOTIFY_ON_MEASUREANDBEAT = 3
    DMUS_NOTIFY_ON_PERFORMANCE    = 4
    DMUS_NOTIFY_ON_SEGMENT        = 5
End Enum
DMUS_NOTIFY_ON_CHORD
コード チェンジ。
DMUS_NOTIFY_ON_COMMAND
コマンド イベント。
DMUS_NOTIFY_ON_MEASUREANDBEAT
小節および拍イベント。
DMUS_NOTIFY_ON_PERFORMANCE
パフォーマンス イベント。この値が DMUS_NOTIFICATION_PMSG 型の lNotificationType メンバ内で見つかった場合、イベントは lNotificationOption メンバ内でさらに定義される。
DMUS_NOTIFY_ON_SEGMENT
セグメント イベント。この値が DMUS_NOTIFICATION_PMSG 型の lNotificationType メンバ内で見つかった場合、イベントは lNotificationOption メンバ内でさらに定義される。

参照

DMUS_NOTIFICATION_PMSG


CONST_DMUS_PC_CLASS

CONST_DMUS_PC_CLASS 列挙型のメンバは、ポートのクラスを指定するために DMUS_PORTCAPS 型内で使用される。

Enum CONST_DMUS_PC_CLASS
    DMUS_PC_INPUTCLASS =  0
    DMUS_PC_OUTPUTCLASS = 1
End Enum
DMUS_PC_INPUTCLASS
入力ポート。
DMUS_PC_OUTPUTCLASS
出力ポート。


CONST_DMUS_PC_FLAGS

CONST_DMUS_PC_FLAGS 列挙型のメンバは、ポートのさまざまな能力を記述するために、DMUS_PORTCAPS 型内で使用される。

Enum CONST_DMUS_PC_FLAGS
    DMUS_PC_DIRECTSOUND =         128 (&H80)
    DMUS_PC_DLS =                   1
    DMUS_PC_EXTERNAL =              2
    DMUS_PC_GMINHARDWARE =         16 (&H10)
    DMUS_PC_GSINHARDWARE =         32 (&H20)
    DMUS_PC_MEMORYSIZEFIXED =       8
    DMUS_PC_SHAREABLE =           256 (&H100)
    DMUS_PC_SOFTWARESYNTH =         4
    DMUS_PC_SYSTEMMEMORY = 2147483647 (&H7FFFFFFF)
    DMUS_PC_XGINHARDWARE =         64 (&H40)
End Enum
DMUS_PC_DIRECTSOUND
ポートは DirectSound に送るストリーミング ウェーブ データをサポートする。
DMUS_PC_DLS
ポートは DLS レベル 1 のサンプル コレクションをサポートする。
DMUS_PC_EXTERNAL
ポートはホストの外部にあるデバイスに接続されている。たとえば、MPU-401 のような外部 MIDI ポートを通してデバイスに接続されている。
DMUS_PC_GMINHARDWARE
シンセサイザは独自の GM 音色セットを持っている。そのため、GM 音色はダウンロードする必要がない。
DMUS_PC_GSINHARDWARE
このポートは、ハードウェア内に Roland GS サウンド セットを保持している。
DMUS_PC_MEMORYSIZEFIXED
DLS 音色で利用できるメモリは調整できない。
DMUS_PC_SHAREABLE
デバイス上にあるチャンネル グループの同じ範囲を使うポートは複数作成できる。このビットをセットしない限り、ポートは排他モードでのみ開くことができる。排他モードでは、作成された要求への割り当てに利用できるチャンネル グループがない限り、ポートを作成する試みは失敗する。
DMUS_PC_SOFTWARESYNTH
ポートはソフトウェア シンセサイザである。
DMUS_PC_SYSTEMMEMORY
ポートはシステム メモリを使っているため、そのメモリ量は利用可能なシステム メモリだけによって制限される。この定数は、lFlags ではなく、DMUS_PORTCAPS.lMemorysize 内で使用される。
DMUS_PC_XGINHARDWARE
このポートは、ハードウェア内に Yamaha XG 拡張を保持している。


CONST_DMUS_PLAYMODE_FLAGS

CONST_DMUS_PLAYMODE_FLAGS 列挙型のメンバは、DMUS_NOTE_PMSG メッセージ タイプ内で演奏モードを設定する際に使われる。演奏モードによって、音符が MIDI 音符に変換される前に、現在のコードに転調される方法が決まる。

Enum CONST_DMUS_PLAYMODE_FLAGS
    DMUS_PLAYMODE_ALWAYSPLAY     = 14
    DMUS_PLAYMODE_CHORD_INTERVALS = 8
    DMUS_PLAYMODE_CHORD_ROOT      = 2
    DMUS_PLAYMODE_FIXED           = 0
    DMUS_PLAYMODE_FIXEDTOCHORD    = 2
    DMUS_PLAYMODE_FIXEDTOKEY      = 1
    DMUS_PLAYMODE_KEY_ROOT        = 1
    DMUS_PLAYMODE_MELODIC         = 6
    DMUS_PLAYMODE_NONE           = 16 (&H10)
    DMUS_PLAYMODE_NORMALCHORD    = 10
    DMUS_PLAYMODE_PEDALPOINT      = 5
    DMUS_PLAYMODE_SCALE_INTERVALS = 4
End Enum

以下のメンバは基本的なフラグである。

DMUS_PLAYMODE_CHORD_INTERVALS
コード パターンのコードの音程を使用する。
DMUS_PLAYMODE_CHORD_ROOT
コードのルート音上に転調する。
DMUS_PLAYMODE_KEY_ROOT
キーのルート音上に転調する。
DMUS_PLAYMODE_NONE
モードなし。親パートのモードを使用する必要があることを示す。
DMUS_PLAYMODE_SCALE_INTERVALS
スケール パターンのスケールの音程を使用する。
以下のメンバは基本的なフラグの組み合わせを表す。
DMUS_PLAYMODE_ALWAYSPLAY
DMUS_PLAYMODE_SCALE_INTERVALS、DMUS_PLAYMODE_CHORD_INTERVALS、および DMUS_PLAYMODE_CHORD_ROOT の組み合わせ。コードの最高音より高い音符を演奏することが望ましい場合、このモードは、スケールの音程を使うことによって音符の位置を検索する。つまり、このモードは通常の演奏モードと旋律系の演奏モードの組み合わせであり、通常モードで失敗すると 2 回目の試行が旋律系モードで強制的に行われる。
DMUS_PLAYMODE_FIXED
ミュージック値を MIDI 値として解釈する。これは 0 として定義され、その他のフラグがないことを意味する。このフラグは、ドラム、サウンド エフェクト、およびコードまたはスケールによって転調してはならない、シーケンス化された音符について使用される。
DMUS_PLAYMODE_FIXEDTOCHORD
DMUS_PLAYMODE_CHORD_ROOT と同じ。ミュージック値は固定の MIDI 値であるが、コードのルート音上に転調される。
DMUS_PLAYMODE_FIXEDTOKEY
DMUS_PLAYMODE_KEY_ROOT と同じ。ミュージック値は固定の MIDI 値であるが、キーのルート音上に転調される。
DMUS_PLAYMODE_MELODIC
DMUS_PLAYMODE_CHORD_ROOT と DMUS_PLAYMODE_SCALE_INTERVALS の組み合わせ。コードのルート音は使われるが、音符はスケール内の音程だけを追う。キーのルート音とコードの音程は無視される。これは、コードのルート音を基準にして演奏される旋律系のラインにとって便利である。
DMUS_PLAYMODE_NORMALCHORD
DMUS_PLAYMODE_CHORD_ROOT と DMUS_PLAYMODE_CHORD_INTERVALS の組み合わせ。これは一般的な再生モードである。音符はコード内の音程を追う。コードはコードのルート音に基づいている。ミュージック値にスケール要素がある場合、ほかの音程は音階から取り出され、追加される。コードがミュージック値のコード要素と一致する音程を持っていない場合、音符は無音である。
DMUS_PLAYMODE_PEDALPOINT
DMUS_PLAYMODE_KEY_ROOT と DMUS_PLAYMODE_SCALE_INTERVALS の組み合わせ。キーのルート音が使われ、音符はスケール内の音程だけを追う。コードのルート音と音程は無視される。これは、キーのルート音を基準にして演奏される旋律系のラインにとって便利である。


CONST_DMUS_PMSGF_FLAGS

CONST_DMUS_PMSGF_FLAGS 列挙型のメンバは、メッセージをツールに配信するタイムを指定するために、DirectMusicPerformance のさまざまなメッセージ送信メソッド内で使用される。

Enum CONST_DMUS_PMSGF_FLAGS
    DMUS_PMSGF_MUSICTIME      = 2
    DMUS_PMSGF_REFTIME        = 1
    DMUS_PMSGF_TOOL_ATTIME   = 16 (&H10)
    DMUS_PMSGF_TOOL_FLUSH    = 32 (&H20)
    DMUS_PMSGF_TOOL_IMMEDIATE = 4
    DMUS_PMSGF_TOOL_QUEUE     = 8
End Enum
DMUS_PMSGF_REFTIME
タイム スタンプはクロック タイムで表される。
DMUS_PMSGF_MUSICTIME
タイプ スタンプはミュージック タイムで表される。
DMUS_PMSGF_TOOL_IMMEDIATE
DMUS_PMSGF_TOOL_QUEUE
DMUS_PMSGF_TOOL_ATTIME
DMUS_PMSGF_TOOL_FLUSH
「注意」を参照すること。

注意

DirectX for Visual Basic は DirectMusic ツールをサポートしないため、DMUS_PMSGF_REFTIME と DMUS_PMSGF_MUSICTIME だけが現在有効である。メッセージのタイムはデフォルトでミュージック タイムで表されるため、DMUS_PMSGF_REFTIME はアプリケーションが通常使用する唯一のフラグである。


CONST_DMUS_PORT_TYPE

CONST_DMUS_PORT_TYPE 列挙型は、ポートのドライバ モデルを指定するために、DMUS_PORTCAPS 型内で使用される。

Enum CONST_DMUS_PORT_TYPE
    DMUS_PORT_KERNEL_MODE =     2
    DMUS_PORT_USER_MODE_SYNTH = 1
    DMUS_PORT_WINMM_DRIVER =    0
End Enum
DMUS_PORT_WINMM_DRIVER
Windows マルチメディア ドライバ。
DMUS_PORT_USER_MODE_SYNTH
ユーザーモード シンセサイザ。
DMUS_PORT_KERNEL_MODE
WDM (Windows Driver Model) ドライバ。


CONST_DMUS_SEGF_FLAGS

CONST_DMUS_SEGF_FLAGS 列挙型のメンバは、セグメントに対するアクションのタイミングやその他の要素を制御するために、DirectMusicPerformance オブジェクトのさまざまなメソッド内で使用される。

Enum CONST_DMUS_SEGF_FLAGS
    DMUS_SEGF_AFTERPREPARETIME = 1024 (&H400)
    DMUS_SEGF_BEAT             = 4096 (&H1000)
    DMUS_SEGF_CONTROL           = 512 (&H200)
    DMUS_SEGF_DEFAULT         = 16384 (&H4000)
    DMUS_SEGF_GRID             = 2048 (&H800)
    DMUS_SEGF_MEASURE          = 8192 (&H2000)
    DMUS_SEGF_NOINVALIDATE    = 32768 (&H8000)
    DMUS_SEGF_QUEUE             = 256 (&H100)
    DMUS_SEGF_REFTIME            = 64 (&H40)
    DMUS_SEGF_SECONDARY         = 128 (&H80)
End Enum
DMUS_SEGF_AFTERPREPARETIME
準備時間の後に演奏する (「DirectMusicPerformance.GetPrepareTime」を参照)。
DMUS_SEGF_BEAT
拍の境界で演奏する。
DMUS_SEGF_CONTROL
制御セグメントとして演奏する (セカンダリ セグメントのみ)。「注意」を参照すること。
DMUS_SEGF_DEFAULT
セグメントのデフォルトの境界を使用する。
DMUS_SEGF_GRID
グリッド境界で演奏する。
DMUS_SEGF_MEASURE
小節境界で演奏する。
DMUS_SEGF_NOINVALIDATE
プライマリ セグメントまたは制御セグメントについて、このフラグを DirectMusicPerformance.PlaySegment 内でセットすると、新しいセグメントで無効化が発生しない。このフラグがないと無効化が発生し、演奏中の曲線や音符が途切れ、リセットされる。このフラグは DMUS_SEGF_AFTERPREPARETIME と組み合わせなければならない。そうすることによって、新しいセグメント内の音符は、古いセグメントが演奏する音符に重ねて演奏しない。
DMUS_SEGF_QUEUE
プライマリ セグメント キューの最後に置く (プライマリ セグメントのみ)。
DMUS_SEGF_REFTIME
タイム パラメータはクロック タイムで表される。
DMUS_SEGF_SECONDARY
セカンダリ セグメント。

注意

通常、プライマリ セグメントは制御セグメントである。DMUS_SEGF_CONTROL フラグを使って、セカンダリ セグメントを制御セグメントにすることができる。ただし、制御セグメントが存在できるのは一度に 1 つだけである (複数の制御セグメントを作成することはできるが、実際にどの制御セグメントが DirectMusic によって使われるかは保証されない)。デフォルトでは、制御セグメントだけがテンポ メッセージを送信する。

DMUS_SEGF_CONTROL フラグをセットすると、DMUS_SEGF_SECONDARY が想定される。

参照

DirectMusicPerformance.GetResolvedTime、DirectMusicPerformance.Invalidate、DirectMusicPerformance.PlaySegment、DirectMusicPerformance.Stop


CONST_DMUS_SHAPET_TYPES

CONST_DMUS_SHAPET_TYPES 列挙型のメンバは、DirectMusicComposer.ComposeSegmentFromShape と DirectMusicComposer.ComposeTemplateFromShape の各メソッドの wShape パラメータ内で使用され、グルーブ レベルの希望のパターンを指定する。

Enum CONST_DMUS_SHAPET_TYPES
    DMUS_SHAPET_FALLING  = 0
    DMUS_SHAPET_LEVEL    = 1
    DMUS_SHAPET_LOOPABLE = 2
    DMUS_SHAPET_LOUD     = 3
    DMUS_SHAPET_PEAKING  = 5
    DMUS_SHAPET_QUIET    = 4
    DMUS_SHAPET_RANDOM   = 6
    DMUS_SHAPET_RISING   = 7
    DMUS_SHAPET_SONG     = 8
End Enum
DMUS_SHAPET_FALLING
グルーブ レベルは下降する。
DMUS_SHAPET_LEVEL
グルーブ レベルは均等に保たれる。
DMUS_SHAPET_LOOPABLE
セグメントは先頭にループするよう調整されている。
DMUS_SHAPET_LOUD
グルーブ レベルは高い。
DMUS_SHAPET_PEAKING
グルーブ レベルはピークまで上昇し、その後下降する。
DMUS_SHAPET_QUIET
グルーブ レベルは低い。
DMUS_SHAPET_RANDOM
グルーブ レベルはランダムである。
DMUS_SHAPET_RISING
グルーブ レベルは上昇する。
DMUS_SHAPET_SONG
セクションは歌の形式である。6 ～ 8 小節から成る複数の楽句をアレンジし、まとめることによって、グルーブ レベルにバリエーションのあるヴァースコーラス エフェクトが生み出される。


CONST_DMUSERR

CONST_DMUSERR 列挙型は、DirectMusic のエラー コードを表す。


エラー コード

ここでは、DirectMusic のメソッドによって返されるさまざまなエラー コードについて簡単に説明する。各メソッドが返す特定のエラー コードのリストについては、個別のメソッドの説明を参照すること。これらのリストは必ずしも包括的なものとは限らない。

DMUS_E_ALL_TRACKS_FAILED
セグメント オブジェクトは、IStream オブジェクト データからすべてのトラックをロードできなかった。これは、ストリーム内でエラーが発生したか、トラックがクライアント上で不正に登録されていることが原因と考えられる。
DMUS_E_ALREADY_ACTIVATED
ポートは既にアクティブ化されており、パラメータは変更できない。
DMUS_E_ALREADY_DOWNLOADED
バッファは既にダウンロードされている。
DMUS_E_ALREADY_EXISTS
ツールはグラフ内に既に含まれている。新しいインスタンスを作成しなければならない。
DMUS_E_ALREADY_INITED
オブジェクトは既に初期化されている。
DMUS_E_ALREADY_LOADED
DLS コレクションは既に開いている。
DMUS_E_ALREADY_SENT
メッセージは既に送信されている。
DMUS_E_ALREADYCLOSED
ポートは開いていない。
DMUS_E_ALREADYOPEN
ポートは既に開いていた。
DMUS_E_BADARTICULATION
DLS コレクション内に無効なアーティキュレーション チャンクがある。
DMUS_E_BADINSTRUMENT
DLS コレクション内に無効な音色チャンクがある。
DMUS_E_BADOFFSETTABLE
オフセット テーブルにエラーがある。
DMUS_E_BADWAVE
ウェーブ ヘッダーが壊れている。
DMUS_E_BADWAVELINK
DLS コレクション内のウェーブリンク チャンクが無効なウェーブを指している。
DMUS_E_BUFFER_EMPTY
バッファ内にデータがない。
DMUS_E_BUFFER_FULL
指定したバイト数が最大バッファ サイズを超えている。
DMUS_E_BUFFERNOTAVAILABLE
このバッファはダウンロードに利用できない。
DMUS_E_BUFFERNOTSET
データ用に準備されたバッファが存在しない。
DMUS_E_CANNOT_OPEN_PORT
デフォルトのシステム ポートを開くことができなかった。
DMUS_E_DEVICE_IN_USE
デバイスは既に使われており (おそらく DirectMusic 以外のクライアントによって)、再度開くことができない。
DMUS_E_DMUSIC_RELEASED
DirectMusic オブジェクトの最後のインスタンスが解放されたため、操作を実行できない。DirectMusic オブジェクトの最後の解放が終わるまで、ポートは使用できない。
DMUS_E_DRIVER_FAILED
ドライバまたはハードウェアでの障害の可能性を示す予想外のエラーがデバイス ドライバから返された。
DMUS_E_DSOUND_ALREADY_SET
DirectSound オブジェクトは既に設定されている。
DMUS_E_DSOUND_NOT_SET
DirectSound オブジェクトが指定されていないため、ポートを作成できなかった。
DMUS_E_FAIL
このメソッドは成功しなかった。
DMUS_E_GET_UNSUPPORTED
パラメータの取得はサポートしていない。
DMUS_E_INSUFFICIENTBUFFER
要求された操作を実行するためのバッファが十分な大きさではない。
DMUS_E_INVALIDARG
無効な引数。
DMUS_E_INVALID_BAND
ファイルに有効なバンドが含まれていない。
DMUS_E_INVALID_DOWNLOADID
ダウンロード バッファの作成プロセスで、無効なダウンロード識別子が使われた。
DMUS_E_INVALID_EVENT
イベントは、有効な MIDI メッセージではない、または動作ステータスを利用しておりバッファ内にパックできない。
DMUS_E_INVALIDBUFFER
無効な DirectSound バッファがポートに渡された。
DMUS_E_INVALIDFILE
ファイルが無効である。
DMUS_E_INVALIDPATCH
コレクション内の音色がパッチ番号と一致しない。
DMUS_E_INVALIDPOS
DLS コレクションからウェーブ データを読み込み中にエラーが発生した。これは、不正なファイルであることを意味する。
DMUS_E_LOADER_BADPATH
ファイルパスが無効である。
DMUS_E_LOADER_FAILEDCREATE
オブジェクトが見つからなかった、または作成できなかった。
DMUS_E_LOADER_FAILEDOPEN
ファイルが存在していないかロックされているのが原因で、ファイルを開くことに失敗した。
DMUS_E_LOADER_FORMATNOTSUPPORTED
データ フォーマットがサポートされていないため、オブジェクトをロードできない。
DMUS_E_LOADER_OBJECTNOTFOUND
オブジェクトが見つからなかった。
DMUS_E_NO_MASTER_CLOCK
パフォーマンス内にマスタ クロックが存在しない。DirectMusicPerformance.Init メソッドを必ず呼び出すこと。
DMUS_E_NOINTERFACE
利用可能なオブジェクト インターフェイスがない。
DMUS_E_NOT_DOWNLOADED_TO_PORT
オブジェクトがポート上にないため、アンロードできない。
DMUS_E_NOT_FOUND
要求された項目はオブジェクトに含まれていない。
DMUS_E_NOT_INIT
必要なオブジェクトは初期化されていないか、初期化に失敗した。
DMUS_E_NOTADLSCOL
ロード中のオブジェクトは有効な DLS コレクションではない。
DMUS_E_NOTIMPL
このメソッドは実装されていない。動作に必要な機能をドライバがサポートしていないために、このメソッドが返されることがある。
DMUS_E_OUT_OF_RANGE
要求されたタイムはセグメントの範囲外である。
DMUS_E_OUTOFMEMORY
メモリ不足のため、タスクを完了できない。
DMUS_E_PORT_NOT_RENDER
出力ポートではない。
DMUS_E_PORTS_OPEN
システム内の任意のプロセスにインスタンス化されたポートがあるときは、要求された操作を実行できない。
DMUS_E_SEGMENT_INIT_FAILED
セグメントの初期化に失敗した。メモリで重大な問題が発生したと考えられる。
DMUS_E_SET_UNSUPPORTED
パラメータの設定はサポートしていない。
DMUS_E_TIME_PAST
要求されたタイムは過去のタイムである。
DMUS_E_TRACK_NOT_FOUND
要求されたタイプのトラックがない。
DMUS_E_TYPE_DISABLED
パラメータは無効化されているため利用できない。
DMUS_E_TYPE_UNSUPPORTED
パラメータはこのトラック上でサポートされていない。
DMUS_E_UNKNOWN_PROPERTY
このポートにはプロパティ セットや項目が実装されていない。
DMUS_E_UNSUPPORTED_STREAM
ストリームは、ロード中のオブジェクトがサポートしているデータを含んでいない。


DirectMusic サンプル

ここでは、DirectX SDK に含まれている、DirectMusic を使ったサンプル アプリケーションについて説明する。説明する内容は以下のとおりである。

  • DirectMusic C/C++ サンプル
  • DirectMusic Visual Basic サンプル


DirectMusic C/C++ サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

次のサンプル アプリケーションでは、DirectMusic® アプリケーション プログラミング インターフェイスの使用方法と機能を示している。

  • 3DMusic サンプル
  • DMBoids サンプル
  • DMDonuts サンプル
  • DirectMusic MIDI サンプル
  • DirectMusic Shell サンプル
  • EchoTool サンプル
  • MusicLines サンプル
  • PlayMotif サンプル
  • PlayPrimary サンプル

DirectX® サンプルには Microsoft Visual C++ プロジェクト ワークスペース ファイルが含まれているが、読者の開発環境で正しくコンパイルできるかどうかを確認する必要がある。詳しくは、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル.」を参照すること。


3DMusic サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

3DMusic サンプルでは、カスタム DirectSound 3-D バッファで MIDI ファイルを演奏する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\3DMusic

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin\3DMusic.exe

ユーザーズ ガイド

表示されるアイコンは、3-D 環境における聴取者と音源を表している。ただし、移動と方向の設定は 2 次元のみとなる。

音源を移動するには、方向キーを使用する。聴取者の方向を変更するには、数値キーパッドを使用する。

[File] メニューの [Play Stereo Drip] を選択すると、滴の落ちるサウンドが、ランダムなパンおよびボリューム設定で再生される。これにより、2-D バッファで、どのように疑似 3-D エフェクトが生成されているかを確認することができる。

プログラミング上の注意

プログラムは、DirectX SDK セットアップで設定されたレジストリ キーを使って、メディア ファイル パスを検索する。

Helper.cpp には、DirectMusic を設定するための有用な関数が含まれている。これらの関数は、Soud.cpp から呼び出される。


DMBoids サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

DMBoids は、Boids に DirectMusic サポートを追加したサンプルである。オブジェクトを簡単な地形の上を飛行させ、ユーザーの入力および画面上のイベントに反応して音楽を演奏する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\DMBoids

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin\Dmboids.exe

ユーザーズ ガイド

メイン メニューにアクセスするには、F10 キーを押す。[Drivers] メニューを使うと、ドライバ、デバイス、およびビデオ モードを変更できる。アプリケーションは、フルスクリーン モードでのみ実行される。

A (整列)、C (集合)、および O キー (障害) を押すと、キーを押している間、ボイドの動きがさまざまに変化する。

S キーまたは Space キーを押し続けると、鳥が近くに集まる。キーを離すと散開する。この動作に合わせて、モチーフが使用されている点に注意すること。

M キーを押し続けると、鳥はコースを外れる。音楽が完全に変化する点に注意すること。キーを離すと、最終的に鳥はコースに戻る。

Esc キーを押すと終了する。

プログラミング上の注意

DirectMusic の次のような機能が使用されている。

  • DLS によるソフトウェア合成。アプリケーションは、GS サウンド セットの楽器に加えて、惑星 (障害物) に近づいたときに再生される音声など、独自のダウンローダブル サウンドを使用する。
  • スタイルに基づくセグメントの作成と演奏。
  • スタイルに基づくモチーフとセグメントの挿入を使った音楽の移行。
  • コード化されたエコー/アーティキュレーション ツール。音楽を演奏するときに、鳥の接近からエコーと音符の長さを調整する。


DMDonuts サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

DM Donuts は、Space Donuts サンプルに、ゲーム イベントに応じた音楽を追加したものである。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\DMDonuts

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin\Dmdonuts.exe

ユーザーズ ガイド

ドーナツが宇宙に浮かんでいる間は、静かな音楽である点に注意すること。方向キーを押すと、宇宙船が移動する。宇宙船が周囲で跳ね返ったときに、それに合わせて音楽とリズムが変化することを確認する。

Space キーを押して、ドーナツに弾を当てる。直ちに爆発音が鳴り、バックグランド ミュージックが大きくなる。

数値キーパッドの 7 キーを押すと、シールドがオンになる。シールドの内側で聞いているかのように、音楽が消音されている点に注意する。

すべてのドーナツの断片を破壊すると、直ちに音楽は終了部に移り、次のレベルが、次のミュージック テーマの先頭から開始される点に注意すること。

音楽が同じでない点に注意すること。

[Game] メニューで入力デバイスを変更すると、ジョイスティックで宇宙船を操作することができる。

次の一覧に、すべてのゲーム コマンドを示す。数字はすべて数値キーパッドから入力しなければならない。"Joy" はジョイスティック ボタンを表す。

キー | コマンド
ESC、F12 | 終了
4 | 左旋回
6 | 右旋回
5 (Joy 3) | 停止
8 | 前方へ加速
2 | 後方へ加速
7 (Joy 2) | シールド
Space (Joy 1) | 発射
Enter | ゲーム開始
F1 | 残像エフェクトのオン/オフ
F5 | フレーム レートの表示のオン/オフ
F7 | 音楽のオン/オフ
F10 | メイン メニュー

デフォルトの表示は、640x480 で 256 色である。コマンド ラインで、別の解像度と色数を指定することができる。

このゲームでは、次のコマンド ライン スイッチが使用される。大文字と小文字は区別される。

e | ハードウェア アクセラレーションではなく、ソフトウェア エミュレーションを使用する。
t | テスト モード。入力を必要としない。
x | ストレス モード。プレーヤーが操作しなければ止まらない。

これらのスイッチの後に、x 解像度、y 解像度、およびピクセルあたりのビット数を指定することもできる。たとえば、次のように指定する。

donuts -t 800 600 16

プログラミング上の注意

ここでは、次のテクニックが使用されている。

  • スタイルに基づくセグメントの作成と演奏。
  • ゲーム ステージが変わるときの自動移行。
  • アクションを強調するモチーフ (短いミュージック クリップ)。モチーフは基調となる音楽のリズムと和音に追随するため、音楽に音響的な強化が加わる。
  • リアルタイム イベントに応じて、オーケストレーションを変化させる動的なバンド。

デフォルトでは、このサンプルはソフトウェア シンセサイザで動作する。ハードウェアでの DLS 合成をサポートするオペレーティングシステムでは、_SOFTWARE_SYNTH_ コンパイル フラグを定義せずに、サンプルを再コンパイルすること。


DirectMusic MIDI サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

DirectMusic MIDI サンプルは、簡単な MIDI ファイル プレーヤーである。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\DMusMIDI

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin\Dmusmidi.exe

ユーザーズ ガイド

[File] メニューの [Open] を選択して、MIDI ファイルをロードする (\Samples\Multimedia\DMusic\Media フォルダに、サンプル ファイルが用意されている)。ドラッグ アンド ドロップ操作でも、ファイルをロードすることができる。[Option] メニューの [Autoplay Dropped Files] が選択されている場合は、ドロップしたファイルが自動的に演奏される。

ロードしたファイルは、[File] メニューまたはツール バーから、演奏、一時停止、および停止することができる。

[Options] メニューでは、リバーブを追加するかどうかを選択したり、インターフェイスを選択することができる。時間は、演奏開始からの時間、分、および秒、またはミュージック タイムのティックで表示される。

音楽を演奏していないときに、[Device] メニューからポートを選択することができる。"MIDI Out" ポートから音楽を聴くには、外部シンセサイザを接続する必要がある点に注意すること。

プログラミング上の注意

アプリケーションでは、MIDI ファイルをセグメントとしてロードする方法、演奏と停止の方法、および演奏を最初からまたは停止した位置から再開する方法を示している。リバーブ プロパティの設定方法も示されている。

コードは純粋な C で記述されている。したがって、メソッドは vtables へのポインタを通して呼び出される。詳細については、「C からの COM オブジェクトへのアクセス」を参照すること。


DirectMusic Shell サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

DirectMusic Shell サンプルでは、Windows のシステム イベントに応答するインタラクティブ ミュージックを示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\DMShell

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin\Dmshell.exe

ユーザーズ ガイド

プログラムを実行すると、タスク バーのトレイにインジケータ アイコンが表示される。アイコンをクリックするとメニューが表示され、音楽スキームの変更、出力デバイスの選択、音楽の開始と停止、およびプログラムの終了を実行することができる。

システム イベントに応じて音楽が変化するようす、およびモチーフが挿入されるようすに注意すること。システム イベントには、ウィンドウの最小化、復元、または終了、アプリケーション メニューまたはスタート メニューの表示、キーの押し下げ (いくつかのキーでは特殊なサウンドが発生する) などがある。

プログラミング上の注意

Windows のシステム メッセージは、Dmhook.dll で取得される。ソース コードは (SDK ルート)\Samples\Multimedia\Dmusic\Src\DMHook フォルダにある(Dmhook.dll は、Microsoft のコンパイラでコンパイルしなければならない)。


EchoTool サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

EchoTool サンプルでは、DirectMusic でツールを実装する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\EchoTool

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin

ユーザーズ ガイド

エコーの遅延を変更するには、オプション ボタンを選択する。アプリケーションを終了するには、[Close] ボタンをクリックする。

プログラミング上の注意

ツールでは、演奏している音楽の遅延したエコーを最大 4 つまで作成する。

Helper.cpp には、DirectMusic を設定するための有用な関数が含まれている。これらの関数は、Main.cpp から呼び出される。Echotool.cpp には、ツール コードが含まれている。

詳細については、「チュートリアル 2 : ツールの使い方」を参照すること。


MusicLines サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

MusicLines サンプルでは、インタラクティブ ミュージック要素を簡単なゲームで説明している。特に、音楽によってゲーム要素が駆動されるようすが示されている。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\MusicLines

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin

ユーザーズ ガイド

表示されるダイアログ ボックスで、ウィンドウ モードとフルスクリーン モード、難易度、およびプレーヤーを人間とコンピュータのどちらにするかを選択する。2 人でプレイする場合、1 人は方向キーを使い、もう 1 人は AZSW キーを使う。方向キーを押して、移動を開始する。

ゲームの目的は、移動した後に残るラインに相手のプレーヤーを衝突させることである。

方向キー、または AZSW キーを押して、線の向きを変更する。プレイの現在の状態に応じてメインの音楽がどのように変化するか、衝突などのイベントを知らせるためにモチーフがどのように使用されているか、および線のスピードが音楽によって実際にどのように制御されているかに注意すること。

コンピュータに勝った場合、線を伸ばし続けるか、わざと衝突してゲームを終了することができる。もう一度プレイするには、Space キーを押す。終了するには、Alt キーを押しながら F4 キーを押す。

プログラミング上の注意

音楽ロジックは Mlmusic.cpp にあり、ファイル中に詳細にコメントされている。


PlayMotif サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプル アプリケーションでは、プライマリ セグメント上でモチーフをどのように演奏できるかを示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\PlayMotf

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin

ユーザーズ ガイド

ボタンをクリックすると、メインで演奏されているプライマリ セグメント上で、さまざまなセカンダリ セグメント (モチーフ) が演奏される。アプリケーションを終了するには、[Close] をクリックする。

プログラミング上の注意

プログラムは、DirectX SDK セットアップで設定されたレジストリ キーを使って、メディア ファイル パスを検索する。


PlayPrimary サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectMusic Visual Basic サンプル」を参照すること。

[C++]

説明

PlayPrimary サンプルでは、オーサリングされたミュージック セクション上でプライマリ セグメントを演奏する方法を示す。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dmusic\Src\PlayPri

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DMusic\Bin

ユーザーズ ガイド

[Close] をクリックすると、プログラムが終了する。

プログラミング上の注意

プログラムは、DirectX SDK セットアップで設定されたレジストリ キーを使って、メディア ファイル パスを検索する。


DirectMusic Visual Basic サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ サンプル」を参照すること。

[Visual Basic]

次のサンプル アプリケーションには、DirectMusic® アプリケーション プログラミング インターフェイスの使い方と機能が示されている。

  • ClubMet サンプル
  • DLSEffects サンプル
  • DMDrums サンプル
  • PlayDMusic サンプル


ClubMet サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ サンプル」を参照すること。

[Visual Basic]

説明

ClubMet サンプル アプリケーションでは、DirectMusic が入力イベントに対してどのように応答するかを示す。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dmusic\Src\ClubMet

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DMusic\Bin\ClubMet.exe

ユーザーズ ガイド

曜日とボタンをクリックする。選択した曜日に応じてスタイルが変化するようすに注意すること。また、ボタンのクリックに応じてモチーフが演奏されるようすにも注意する。

プログラミング上の注意

このサンプルは、DirectMusicComposer によって、セグメントと移行部がスタイルからどのように作成されるかを示している。


DLSEffects サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ サンプル」を参照すること。

[Visual Basic]

説明

DLSEffects サンプル アプリケーションでは、音楽以外のサウンド エフェクトに対して、アプリケーションが DirectMusic と DLS ファイルをどのように使用するかを示す。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dmusic\Src\DLSEffects

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DMusic\Bin\DLSEffects.exe

ユーザーズ ガイド

[C3] から [C10] までのラベルが付いたボタンをクリックすると、音声のエフェクトが演奏される。[On] をクリックすると鼓動音のエフェクトが連続して演奏され、[Note] および [Pitch Bend] スライダを使うとピッチが変化する。右側のスライダを使って、音符のベロシティ (ボリューム) を設定する。ベロシティの変更は、変更後に開始された音符にだけ適用される。

プログラミング上の注意

このアプリケーションは、ダウンローダブル サウンドをサウンド エフェクトに使う方法と、MIDI 音符の送信方法を示している。

DLS 音色は Boids.dls から取得している。コレクションには、"Vocals" という 1 つの音色のみが含まれている。ただし、音色が基づいているウェーブ サンプルは、"リージョン" または音符の範囲によって異なっている。たとえば、最初のスピーチのサウンドは、C3 ～ B3 の間の音符が送信されたときに使用される。スピーチのサウンドは、リージョンで最も低い音符のときにだけ、正しいピッチで演奏される。

Heartbeat のサンプルは、B7 ～ B8 の範囲で有効である。これは音声のサンプルではないので、ピッチを適度に変化させることができる。この処理は、スライダ設定で決定した、範囲内のさまざまな音符で演奏することで実行される。

Heartbeat は、DLS コレクションで唯一の、ループしたウェーブに基づくサンプルでもある。したがって、音符の最大の継続時間まで連続して演奏することができる。ほかのサンプルは、送信された音符の継続時間にかかわらず、一度しか演奏されない。


DMDrums サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ サンプル」を参照すること。

[Visual Basic]

説明

DMDrums サンプル アプリケーションでは、マスタ グルーブ レベル、バンド、ボリューム、およびテンポを変更して、アプリケーションがどのように音楽を変更するかを示す。ユーザーの入力に応じて、モチーフを変奏する方法も示されている。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dmusic\Src\DMDrums

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DMusic\Bin\Dmdrums.exe

ユーザーズ ガイド

緑および赤のボタンをクリックすると、音楽が開始または停止する。上側のリスト ボックスで音楽の種類を選択し、下側のリスト ボックスでバンドを選択する。上向き矢印と下向き矢印のボタンで、テンポとボリュームを調整する。ドラム ボタンをクリックすると、ドラムのモチーフが演奏される。

プログラミング上の注意

音楽の "スタイル" は、実際にはマスタ グルーブ レベルで決定される。これにより、セグメントに関連付けられたスタイル オブジェクトから、異なるパターンが選択される。

各ドラム ボタンで、それぞれ異なるモチーフが演奏される。ボタンに関連付けられている音色は、モチーフで割り当てられる。


PlayDMusic サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectMusic C/C++ サンプル」を参照すること。

[Visual Basic]

説明

PlayDMusic サンプルでは、オーサリングされたセグメントとスタンダード MIDI ファイルをロードして演奏する方法を示す。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dmusic\Src\Play

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DMusic\Bin\Playdmusic.exe

ユーザーズ ガイド

[File] メニューの [Open] をクリックするか、アイコンをクリックして、セグメントまたは MIDI ファイルをロードする。それぞれのボタンを使って、セグメントを演奏、一時停止、または停止する。ボリュームを調整するには、矢印をクリックする。

[Option] メニューの [Show] をクリックして、表示する時間の単位を、秒またはミュージック タイム ティックのどちらにするか選択する。

バンドを別の DLS コレクションに接続することができる。また、[File] メニューから、GMReset コマンドを実行することもできる。

プログラミング上の注意

プログラムでは、2 つ目のパフォーマンスを使用して、セグメントを演奏する前にその情報を取得している。


DirectPlay

DirectPlay® アプリケーション プログラミング インターフェイス (API) は、DirectX® のコンポーネントであり、マルチプレーヤー ゲームなどのネットワーク アプリケーションの記述を可能にする。

DirectPlay に関する情報は、次のトピックを参照すること。

  • DirectPlay について
  • DirectPlay を使用する理由
  • DirectPlay アーキテクチャ
  • DirectPlay の要点
  • DirectPlay チュートリアル
  • DirectPlay リファレンス
  • DirectPlay のツールとサンプル


DirectPlay について

Microsoft Windows® 用の Microsoft® DirectPlay® アプリケーション プログラミング インターフェイス (API) を使用すると、開発者は個別のトランスポート、プロトコル、またはオンライン サービス用のコードを記述せずに、マルチプレーヤー ゲーム、ゲーム サーバー、チャット クライアント、およびその他のネットワーク アプリケーションを作成することができる。

DirectPlay は、次のタスクのためのサービスを提供する。

  • ネットワーク、インターネット、またはドメインを介して、コンピュータ間の接続を確立する。
  • ロビーを介して通信する。ロビーでは、参加者が互いに会ったり、セッションを編成したりすることができる。
  • セッションを作成したり、セッションに参加したりする。
  • セッション内のプレーヤーとグループを管理する。
  • メッセージの交換によって、異なるコンピュータ上でセッション状態を一致させる。


DirectPlay を使用する理由

DirectPlay は、明確に定義された汎用的な通信機能を提供する。開発者は、さまざまな接続ソリューションがもたらす違いに対処する必要はない。DirectPlay は、基盤となる多様な接続の実装の複雑さを開発者から隠し、優れたアプリケーションを作成することに集中できるようにする。

DirectPlay アプリケーション プログラミング インターフェイス (API) は、ネットワーク アブストラクションであり、分散オブジェクト システムである。この API は、抽象的な DirectPlay ネットワークの機能を定義する。すべての機能は、実際に基盤となっているネットワークがその機能をサポートしているかどうかに関係なく、アプリケーションから利用可能である。基盤となるネットワークが機能をサポートしていない場合、DirectPlay はその機能をエミュレートする。例として、グループ メッセージングや保証メッセージングなどがある。

DirectPlay はロビーもサポートしている。ロビーとは、さまざまなアプリケーションのユーザーが会ったり、メッセージを交換したり、ゲーム セッションを編成したり、アプリケーションを起動したりする場所である。エンド ユーザーにとって、ロビーの大きな利点は、ほかのプレーヤーと共にセッションを簡単に確立できることだ。ロビーはプレーヤーが対戦相手を見つける場所を提供するだけではない。アプリケーションが起動したとき、ユーザーは次のことを実行せずに済む。

  • サービス プロバイダの選択。ロビーによって、使用するサービス プロバイダが指定される。
  • ネットワーク アドレスの入力とネットワークの構成。これらの情報が必要な場合は、ロビーによって提供される。
  • プレーヤーの名前の入力。ロビーによって、プレーヤーがロビーに接続するために入力した名前が渡される。

ロビーのその他の利点として、次のものがある。

  • 実行中のセッションを追跡し、ユーザーがセッションに参加できるようにする。
  • セッションからステータス メッセージを受信し、スコアボード上でほかのユーザーに進行状況を表示する。
  • トーナメントプレイで最終スコアを取得し、プレーヤーランキングをメンテナンスする。


DirectPlay アーキテクチャ

DirectPlay のサービス プロバイダのアーキテクチャは、アプリケーションをそれが実行されているネットワークから切り離す。アプリケーションは、DirectPlay にネットワークの特定の機能、たとえば待ち時間や帯域幅を問い合わせ、それに応じて通信を調整することができる。

次の図は、DirectPlay サービス プロバイダのアーキテクチャを示している。

DirectPlay を使用するための最初のステップは、使用するサービス プロバイダを選択することである。サービス プロバイダによって、通信に利用するネットワークまたはプロトコルの種類が決まる。プロトコルは、インターネット上の TCP/IP 、IPX ローカル エリア ネットワーク、さらには 2 つのコンピュータ間のシリアル接続まで、多岐に及ぶ。

アプリケーションは、サービス プロバイダを使用して、ネットワーク上のあるポイントへの接続を確立する。接続を確立するには、ユーザーが追加情報を提供しなければならない場合もある。または、アプリケーションで接続パラメータを指定することもできる。

DirectPlay アーキテクチャに関するさらに詳細な情報は、次のトピックを参照すること。

  • 通信モデル
  • ロビー
  • サービス プロバイダ
  • セキュリティ
  • DirectPlay インターフェイスの概要 [C++]
  • DirectPlay クラスの概要 [Visual Basic]


通信モデル

ここでは、ネットワーク ゲームまたは同様のアプリケーションにおける通信と、共通の状態の維持に関する一般的な原則について説明する。アプリケーションで DirectPlay を使用すると、以下に説明するいずれかのモデルを利用して、アプリケーション自体のデータを維持することができる。

ネットワークに対応したマルチプレーヤー ゲームを記述する際の主要な関心事は、セッションに参加しているすべてのコンピュータにどのようにして状態情報を伝えるかということである。セッションの状態は、ユーザーが自分のコンピュータ上で見るものと、ユーザーが実行できることを定義する。一般に、セッション状態は 2 つのものによって構成される。つまり、「環境」と、個別のユーザーまたはプレーヤーである。

注 : "ユーザー" と "プレーヤー" は一般的には同じ意味で使用されることが多いが、プレーヤーは DirectPlay アプリケーションの論理概念でもあることを覚えておくことが重要である。アプリケーションでは、2 人以上のプレーヤーによって表現される、あるユーザーをも許容する。

「環境」は、プレーヤーが対話したり、操作したりするオブジェクトによって構成される。たとえば、ダンジョン、レースコース、一連のチャット メッセージなどである。また、「環境」には、コンピュータによって制御されるプレーヤーが含まれる場合もある。

「環境」内では、各プレーヤーがプレーヤーの現在のプロパティを示す状態を保持する。これらのプロパティには、位置、速度、エネルギー、防具などが含まれる。

プレーヤーがセッションに最初に参加するときは、「環境」を含むセッションの現在の状態と、ほかのプレーヤーの状態をダウンロードする必要がある。

ユーザーが実行する動作と、ゲームの自然な進行により、セッション状態が変化する。このような変化が発生した場合、その変化をメッセージによってセッションに参加しているほかのコンピュータに伝える必要がある。セッション状態を更新する方法はいくつもあるが、これらの方法はいずれもコンピュータ間でのメッセージの送信に依存している。

セッションで状態データを維持するための方法は、主に 2 つある。1 つは、ピアツーピアと呼ばれる方法である。ピアツーピア セッションでは、セッションに参加しているすべてのコンピュータが「環境」およびすべてのプレーヤーについての完全な状態を保持する。あるコンピュータ上で状態の変更が発生したら、それをセッションに参加するほかのすべてのコンピュータに伝える必要がある。1 台のコンピュータが状態データを管理するわけではない。

セッション状態を維持するためのもう 1 つの方法は、クライアント/サーバーと呼ばれるものである。クライアント/サーバー セッションでは、1 台のコンピュータがサーバーとして指定され、そのコンピュータがゲームの完全な状態を維持し、衝突を解決する。セッション内のほかのすべてのコンピュータはクライアントとなる。各クライアントは、そのコンピュータに関連する情報だけを保持し、その情報をサーバーから受け取る。あるコンピュータが何かを変更したときは、その変更をサーバーに伝える。続いてサーバーは、その変更を伝えるべきクライアントを判断する。

DirectPlay を使用すると、ピアツーピア アプリケーションとクライアント/サーバー アプリケーションの両方を作成および管理することができる。DirectPlay は、ネットワークに対応したマルチプレーヤー アプリケーションを記述するために必要なツールをすべて提供する。これを実現するために、DirectPlay は、プレーヤーを管理し、プレーヤー間でメッセージを送信し、すべてのコンピュータ間で状態を自動的に伝達するためのサービスを提供する。

以下のトピックでは、DirectPlay セッションにおける 2 つの通信モデルについて説明する。

  • ピアツーピア セッション
  • クライアント/サーバー セッション


ピアツーピア セッション

ピアツーピア セッションでは、1 台のコンピュータがネーム サーバーに指定される。このコンピュータは、列挙要求に応答し、セッションに参加するコンピュータを調整し、セッションに参加した新しいコンピュータにセッションの状態をダウンロードし、プレーヤーおよびグループが作成されるたびに ID 番号を生成する。しかしそれ以前に、ネーム サーバーはセッションにおける 1 つのピアであり、ほかのすべてのピアと同じアプリケーションを実行する。メッセージはネーム サーバーを経由しない。また、ネーム サーバーはすべてのシステム メッセージを生成するわけではない。

DirectPlay は、ネーム サーバー機能を自動的に実行する。このネーム サーバー機能は、いかなる方法でもアプリケーションに公開されない。ネーム サーバー上で実行される DirectPlay アプリケーションのインスタンスは、セッションのホストでもある。セッション記述のデータを変更できるのは、ホスト インスタンスだけである。セッション内の各ピア アプリケーションは、セッションに参加しているプレーヤーとグループの完全なリストにアクセスでき、セッション内のほかのプレーヤーとの間でメッセージを送受信したり、セッション内のほかのグループにメッセージを送信したりすることができる。詳細については、「セッション管理」を参照すること。

セッションのネットワーク アドレスは、ネーム サーバーのネットワーク アドレスに対応する。コンピュータは、セッションに参加する必要がある場合、参加要求をネーム サーバーに送る。ネーム サーバーはこれに応答し、セッション状態を新しいコンピュータにダウンロードする。ネーム サーバーがセッションを離れると、新しいコンピュータがネーム サーバーとして選択される。ネーム サーバーが移行すると、セッションのネットワーク アドレスも変更される。

次の図は、セッションへの参加を示している。コンピュータがセッションに参加するには、セッションのネーム サーバーに参加要求を送る必要がある。

ピアツーピア セッションでは、すべてのコンピュータにおけるすべての状態変更 (プレーヤーの移動など) を、セッション内のほかのすべてのコンピュータにブロードキャストする必要がある。コンピュータが電話回線を使用して接続されている場合は特にそうだが、コンピュータが受信できるデータの量には制限があるため、アプリケーションでは参加できるコンピュータの数を制限すべきである。データ変更の量と頻度を最小限に抑えると、パフォーマンスを低下させずにセッションに参加できるコンピュータの数を増やすことができる。

ピアツーピアの DirectPlay セッションに参加しているコンピュータは、互いに直接通信する。つまり、メッセージは中間のコンピュータを経由して転送先に送信されるわけではない (ただし、ルーターを経由する場合がある)。同じメッセージを複数のコンピュータに送信する必要がある場合、DirectPlay はサービス プロバイダ内の任意のマルチキャスト機能の使用を試みる。マルチキャストがサポートされていない場合は、個別のユニキャスト メッセージが転送先の各コンピュータに送信される。

次の図は、マルチキャストを使用しない場合のグループ メッセージングを示している。メッセージをブロードキャストするために、個別のメッセージが各マシンに送信される。

グループ メッセージングは、4 人以上が参加するセッションでは効率を低下させる原因となる場合がある。セッションにマルチキャスト サーバーを追加すると、効率の低下を緩和することができる。マルチキャスト サーバーは、単一のメッセージを複数の転送先に転送するコンピュータである。セッションに参加しているほかのすべてのコンピュータにメッセージをブロードキャストするコンピュータは、1 つのメッセージをマルチキャスト サーバーに送信する。これに対し、マルチキャスト サーバーは、各メッセージをほかのすべてのコンピュータに送信する。この方法は、ほかのコンピュータが低速リンク (電話回線など) でネットワークに接続していて、サーバーが高速リンク (T1 回線など) で接続していれば、より効率が高くなる。

次の図は、マルチキャスト サーバーを使用したグループ メッセージングを示している。プレーヤー対プレーヤーのメッセージは、転送先に直接送信される。グループ メッセージはマルチキャスト サーバーに送信され、マルチキャスト サーバーがそのメッセージをすべての転送先マシンに転送する。

DirectPlay は、セッションでのマルチキャスト サーバーの作成をサポートしている。ネーム サーバーが十分に高速なリンクで接続している場合は、そのネーム サーバーをセッションに対するマルチキャスト サーバーとしても機能させることが可能である。マルチキャスト サーバーをセッションに追加しても、グループ メッセージ (ブロードキャストを含む) のルーティング方法が変わるだけであり、アプリケーションの動作は変わらない。プレーヤー対プレーヤーのユニキャスト メッセージは、引き続き転送先へ直接送信される。


クライアント/サーバー セッション

DirectPlay のクライアント/サーバー セッションでは、1 台のコンピュータがサーバーとして指定される。このコンピュータは、ピアツーピアのネーム サーバーと同じく、列挙要求に応答したり、セッションに参加するコンピュータを制御したり、セッション状態を新たにセッションに参加したコンピュータにダウンロードしたり、プレーヤーとグループが作成されるたびに ID 番号を生成したりする。クライアント/サーバー モデルがピアツーピア モデルと異なる点は、セッションにおけるすべてのメッセージがサーバーを経由してルーティングされることである。

サーバー コンピュータは、アプリケーションの特別なバージョンを実行する。これをアプリケーション サーバーと言う。アプリケーション サーバーは、ゲームのマスタ状態を維持し、クライアント コンピュータが実行したアクションに応じてその状態を更新し、関連するイベントを個別のクライアントに通知することができる。アプリケーション サーバーは、サーバー プレーヤーという特別なプレーヤーを作成する。すべてのクライアントは、サーバー プレーヤーにメッセージを直接送信し、サーバー プレーヤーからメッセージを直接受信することができる。サーバー プレーヤーは、メッセージを受信すると、ほかのクライアント プレーヤーにメッセージを送信して、状態の変化を通知することができる。

次の図は、クライアント/サーバーの通信を示している。各コンピュータは、サーバーとのみ直接通信する。サーバーはメッセージをほかのクライアントに転送することができる。

クライアント コンピュータは、アプリケーションのクライアント バージョンを実行する。このバージョンは、ローカルな状態を維持し、その状態をサーバーからのメッセージに応じて更新し、ローカルなアクションが発生した場合にサーバーにメッセージを送信することができる。

クライアント/サーバーは 2 つの方法で実装できる。1 つは、ピアツーピアとクライアント/サーバーの混合である。この場合、各クライアント アプリケーションは、自らが利用可能なプレーヤーとグループ (サーバー プレーヤーを含む) の完全なリストを保持する。クライアント プレーヤーは、セッションに参加している任意のプレーヤーにメッセージを直接送信することができる。各プレーヤーまたはグループは、それ自体に関するデータ (名前やリモート データなど) を保持することができる。このデータは、変更があるたびに、すべてのコンピュータ上で更新される。ピアツーピアの状態伝達の利点をすべて活用できるだけでなく、サーバー プレーヤーも利用できる。しかし、プレーヤー対プレーヤーのデータの伝達を制御することはできない。プレーヤーとグループが作成および破棄されたり、またはそれらのデータが変更されたりする頻度によっては、クライアント コンピュータが着信メッセージで過負荷になる場合がある。このタイプのセッションは、プレーヤーが約 16 人以上になると対応が困難である。このセッションは、サーバー プレーヤーが存在し、すべてのメッセージがサーバーを経由してルーティングされ、サーバー プレーヤーがサーバーを通過するすべてのメッセージのコピーを受信するという点を除けば、ピアツーピア セッションとそれほど大きな違いはない。

もう 1 つの方法は、真のクライアント/サーバー モードである。各クライアント アプリケーションはサーバー プレーヤーとセッション内の自身のローカル プレーヤーだけを参照する。クライアント プレーヤーは、サーバー プレーヤーにのみメッセージを送信することができ、サーバー プレーヤーからのメッセージのみを受信することができる。アプリケーション サーバーは、すべてのクライアント上のすべてのプレーヤーを参照することができる。サーバーはクライアントからメッセージを受信すると、アプリケーションのマスタ状態を更新する方法と、その更新をクライアントに通知する方法を判断する。この方法では、クライアント アプリケーションはプレーヤーと各プレーヤーに関連するデータのリストを維持する必要がある。

次の図は、DirectPlay クライアント/サーバー セッションの内容を論理的に示したものである。

ピアツーピア セッションの場合と同じく、セッションのネットワーク アドレスはサーバーのネットワーク アドレスに対応する。コンピュータがセッションに参加するには、参加要求をサーバーに送信する。これに対し、サーバーはセッション状態を新しいコンピュータにダウンロードする。サーバーがセッションを離れると、セッションが終了する。

すべてのメッセージがサーバーを経由してルーティングされるため、サーバーは自動的にマルチキャスト サーバーとして機能することになる。


ロビー

DirectPlay の ロビー サーバー は、(最低でも) DirectPlay アプリケーションの進行中のセッションと接続しているユーザーを追跡するための、ネットワーク上の共通の場所である。ユーザーはロビー サーバーを経由して興味のある場所を見つけたり、ほかのユーザーとチャットしたり、セッションに参加したり、プレーヤーのグループを作成して新しいセッションを開始したりすることができる。

ロビー サーバーの大きな利点は、それが中央の既知の位置として機能し、そこでユーザーがセッションを検索したり、対話相手のユーザーを見つけたりできるということだ。ロビー サーバーはさまざまなプレーヤーおよびセッションのネットワーク アドレスをすべて管理し、ユーザーのコンピュータ上でアプリケーションを自動的に起動して、それをユーザーの介在なしに適切なネットワーク アドレスに接続することができる。セッション、プレーヤー、およびネットワーク アドレスの管理は、インターネット上では特に有効である。

ロビー サーバーは、多数のサービスをユーザーに提供するように拡張することができる。たとえば、トーナメント、個別のスコア追跡、ハイスコア リスト、パーソナル プロファイル、アバター (ユーザーを表すグラフィカル要素)、掲示板、ニュース、会員の認証、ソフトウェアの更新などのサービスを提供することができる。

ロビー対応アプリケーションは、ロビー サーバーと共に機能するように特別に設計されたアプリケーションである。ユーザーが利用するロビーには 2 つの種類がある。つまり、外部ロビーと内部ロビーである。

外部ロビーは、ロビー サーバーおよびロビー サーバーに接続しているほかのユーザーとやり取りすることを唯一の目的としたクライアント アプリケーションである。ロビー クライアントは、アプリケーション セッションを開始したり、アプリケーション セッションに参加したりするときに、アプリケーションを独立したプロセスで起動し、セッションへの接続を確立するために必要な情報をすべて提供する。外部ロビーの起動に対するサポートを DirectPlay アプリケーションに追加することは簡単である。詳細については、「外部ロビーによる開始のサポート」で説明している。

内部ロビーは、ロビーのユーザー インターフェイスであり、アプリケーション自体に統合されている。内部ロビーは実装するのが難しい。これは、アプリケーションでゲームに対するユーザーインターフェイスだけでなく、ロビーに対するユーザー インターフェイスも実装しなければならないからである。しかし、アプリケーションのテーマに応じてロビーをカスタマイズできるという利点がある。

DirectPlay ロビーのアーキテクチャは、すべてのアプリケーション (外部ロビーのクライアントや、ロビー クライアントが組み込まれたアプリケーションを含む) が DirectPlay 互換のロビー サーバーに接続するために使用するクライアント API で構成される。このアーキテクチャは、ロビー プロバイダのインターフェイスを介して実現している。ロビー プロバイダは、サービス プロバイダと同じような機能を持ち、ロビー サーバーとのやり取りを抽象化する。ロビー サーバー アプリケーションの作成者は、クライアント コンピュータ上に常駐するロビー プロバイダを記述する必要がある。アプリケーションが標準の DirectPlay メソッドを呼び出すと、ロビー プロバイダのダイナミックリンク ライブラリ (DLL) が、ロビー サーバー ソフトウェアと通信することでこれらのメソッドをサポートする。

次の図は、DirectPlay ロビーのアーキテクチャを示している。異なるロビー クライアントのアプリケーションが DirectPlay API を介して、同じロビー サーバーに接続することができる。

最後に、ロビー サーバーは現在接続しているすべてのユーザーを追跡し、それらをグループ化して管理し、アプリケーション セッションの起動を同期させる必要がある。

DirectPlay API は、すべてのロビー サーバーに対する共通レベルの機能を定義する。任意の汎用ロビー クライアント アプリケーションが任意の汎用ロビー サーバーに接続し、DirectPlay API とロビー プロバイダのアーキテクチャを介して共に機能することができる。アプリケーションは、メッセージに対応して変更可能なプロパティを定義することにより、基本的な機能を拡張することができる。特定のロビー サーバーと共に機能するように設計されたロビー クライアントは、DirectPlay API で定義されていない拡張機能を実装することができる。


サービス プロバイダ

DirectPlay オブジェクトは、セッション、プレーヤー、およびグループ管理、データの管理および伝達、ネットワーク上のほかのプレーヤーを検索するためのロビー サービスなどのための共通のインターフェイスである。

サービス プロバイダは、DirectPlayの要求に応じて、ネットワークに固有の通信サービスを供給する。サービス プロバイダは、DirectPlay と既存のトランスポート (Windows Sockets など) の間の単なるレイヤになることも、オンライン サービス上の特別なリソース (マルチキャスト サーバー、品質が強化されたサービス、請求書送付サービスなど) を利用することもできる。

Microsoft は、DirectPlay に 4 つの汎用サービス プロバイダを用意している。つまり、モデムツーモデム (TAPI)、シリアル リンク、TCP/IP (Windows Sockets を使用)、および IPX (こちらも Windows Sockets を使用) の 4 つである。オンライン サービスとネットワーク オペレータは、ほかのサービス プロバイダを提供することができる。

DirectPlay は、通信リンクを確立するために必要な固有のタスクと複雑さを、サービス プロバイダの実装内に隠蔽する。DirectPlay を使用するアプリケーションは、DirectPlay によって提供される仮想ネットワークのパフォーマンスと能力だけを配慮すればよい。モデム、ネットワーク カード、オンライン サービスのいずれがメディアを提供しているのを把握する必要はない。

DirectPlay は、ユーザーのシステムにインストールされている任意の DirectPlay プロバイダに動的にバインドする。アプリケーションは、DirectPlay オブジェクトとやり取りする。DirectPlay オブジェクトは、利用可能な DirectPlay サービス プロバイダのいずれかとやり取りする。選択されたサービス プロバイダは、トランスポート、プロトコル、およびその他のネットワーク リソースとやり取りする。


セキュリティ

DirectPlay のセキュリティ機能を用いることにより、サーバー上で実行されるアプリケーションは、セキュア セッションを作成することができる。DirectPlay は、Windows 上の Security Support Provider Interface (SSPI) を介してセキュリティを実装する。セキュア セッションで DirectPlay によりサポートされる主な機能は次のとおりである。

  • ユーザーの身元を確認するための認証。ユーザーを認証すると、デジタル署名を添付するか、またはメッセージを暗号化することにより、クライアントとサーバーの間の通信を安全に実行することができる。
  • 送信側の身元を確認するための、デジタル署名付きのシステム メッセージ。
  • 重要なシステム メッセージの暗号化。

次の図は、DirectPlay のセキュリティのアーキテクチャを示している。

凡例

SSPI
Security Support Provider Interface
CAPI
CryptoAPI
MS RSA Base CP
Microsoft RSA Base Cryptographic Provider

DirectPlay は、Windows Cryptography Application Programming Interface (CAPI) を介して、メッセージの暗号化をサポートする。CAPI は SSPI に似た標準インターフェイスで、ソフトウェアが Windows オペレーティング システムの下でさまざまな暗号化パッケージにアクセスできるようにする。このアーキテクチャにより、DirectPlay アプリケーションは、法的に許可されている必要なレベルの暗号化レベル (40 ビット、128 ビットなど) を提供する暗号化パッケージを適用することが可能になる。

DirectPlay の暗号化サービスに対するデフォルトの CryptoAPI (CAPI) プロバイダは、Microsoft RSA Base Cryptographic Provider バージョン 1.0 である。このデフォルト CAPI プロバイダのタイプは、PROV_RSA_FULL である。デフォルトの暗号化アルゴリズムは、CALG_RC4 ストリーム サイファである。このプロバイダは、32 ビットの Microsoft Windows オペレーティング システムに含まれている。

DirectPlay は、Windows 上の SSPI (Security Support Provider Interface) を介して、ユーザーとメッセージの認証 (デジタル署名) を提供する。これは、ソフトウェアが Windows OS の下でさまざまなセキュリティ パッケージにアクセスすることを可能にする標準的なインターフェイスである。セキュリティ パッケージとは、クライアントの身元を確認し、デジタル署名などのセキュリティ サービスも提供する、クライアントとサーバーの間のプロトコルの実装である。DirectPlay が使用するデフォルトのセキュリティパッケージは、NTLM Security Support Provider (NTLMSSP) と呼ばれる。

このセキュリティ パッケージは、NTLM の認証プロトコルに基づいている。NTLM は､秘密を共有する、ユーザーのチャレンジ/レスポンス認証プロトコルである。このプロトコルは、サーバーのドメインまたは現在のドメインのドメイン コントローラによって信頼されるドメインのドメイン コントローラに対するパススルー認証をサポートしている。このプロトコルでは、パスワードがネットワーク上に送り出されることがないため、高いセキュリティが実現する。NTLMSSP は Windows オペレーティング システムに付属している。

セキュア セッションの開始方法、セキュリティ パッケージの指定方法、ファイアウォールに対するサポートの追加方法などの詳細については、「セキュリティと認証」を参照すること。


DirectPlay インターフェイスの概要

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectPlay は、コンポーネント オブジェクト モデル (COM) に基づいたオブジェクトとインターフェイスによって構成される。概要については、「コンポーネント オブジェクト モデル」を参照すること。

このセクションでは、DirectPlay COM インターフェイスの概要について、次のトピックに分けて記述する。

  • Unicode インターフェイス対 ANSI インターフェイス
  • IDirectPlay4 インターフェイス
  • IDirectPlayLobby3 インターフェイス


Unicode インターフェイス対 ANSI インターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectPlay は、Unicode 文字列と ANSI 文字列の両方をサポートする。これを実現するために、文字列ポインタを、構造体内で Unicode 文字列ポインタ (LPWSTR) および ANSI 文字列ポインタ (LPSTR) の組み合わせとして定義している。2 つの文字列ポインタは異なる名前を持つ。通常、ANSI メンバは、最後に “A” という文字が付く。使用する DirectPlay インターフェイス (Unicode の場合は IDirectPlay4、ANSI の場合は IDirectPlay4A) または DirectPlayLobby インターフェイス (Unicode の場合は IDirectPlayLobby3、ANSI の場合は IDirectPlayLobby3A) に応じて、アプリケーションは適切な構造体から文字列を読み書きし、もう一方を無視する。


IDirectPlay4 インターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

IDirectPlay4 インターフェイスは、ロビー サービスを提供せず、要求もしないネットワーク アプリケーションを作成するために必要な唯一のインターフェイスである。

Dplay.h は、このインターフェイスの以前のバージョンを含んでいる。これらが含まれているのは、DirectX の以前のバージョンで記述されたアプリケーションとの互換性を確保するためである。

  • IDirectPlay は、DirectX SDK バージョン 1 および 2 で記述されたアプリケーションを実行するために必要なメソッドを含んでいる。さらに、Dplay.h は、元の IDirectPlay インターフェイスのメソッドでのみ使用される定義と構造体を多数含んでいる。これらの旧式の要素を無視するには、コードまたはコンパイラで IDIRECTPLAY2_OR_GREATER を定義する。
  • IDirectPlay2 は、DirectX バージョン 3 で記述されたアプリケーションを実行するために必要なメソッドを含んでいる。
  • IDirectPlay3 は、DirectX バージョン 5.0 で記述されたアプリケーションを実行するために必要なメソッドを含んでいる。

これらの旧式のインターフェイスのいずれかを使用して新しいアプリケーションを作成することも可能だが、新しい IDirectPlay4 インターフェイスを使用して、新たな機能を利用することを推奨する。IDirectPlay4 は IDirectPlay3 を直接継承しているため、IDirectPlay3 を使用するように記述されたアプリケーションは、修正を加えなくても IDirectPlay4 で機能する。詳細については、「DirectX の以前のバージョンからの移行」を参照すること。


IDirectPlayLobby3 インターフェイス

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

ゲーム開発者は IDirectPlayLobby3 インターフェイスを使用して、外部アプリケーションを起動したり、アプリケーションとロビー クライアント間の通信を可能にしたり、DirectPlay アドレスを操作したりすることができる。ロビー セッションの概要については、「ロビー」を参照すること。外部ロビーによる起動の検出と、ロビー対応アプリケーションの登録に関する実用的な情報については、「ロビー対応アプリケーションの作成」を参照すること。

インクルード ファイル Dplobby.h は、COM インターフェイスの IDirectPlayLobby と IDirectPlayLobby2 も宣言する。IDirectPlayLobby は、DirectX バージョン 1、2、および 3 で記述されたアプリケーションを実行するために必要なメソッドを含んでいる。IDirectPlayLobby2 は、DirectX バージョン 5.0 で記述されたアプリケーションを実行するために必要なメソッドを含んでいる。これらのインターフェイスを使用して新しいアプリケーションを作成することも可能だが、新たな機能を利用するには、IDirectPlayLobby3 を使用することを推奨する。詳細については、「DirectX の以前のバージョンからの移行」を参照すること。


DirectPlay クラスの概要

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

あらゆる DirectPlay アプリケーションの中心となるオブジェクトは、DirectPlay4 クラスのインスタンスである。このオブジェクトのメソッドを使用して、接続、セッション、プレーヤー、およびグループを管理する。

DirectPlaySessionData クラスは、セッションに関するデータを表す。このクラスのオブジェクトを使用して、セッションの列挙、作成、およびセッションへの参加を処理する。

DirectPlayLobby3 クラスは、ロビーを介したアプリケーション間通信と、ロビー サーバーによるアプリケーションの起動を可能にする。通常、アプリケーションでロビーを使用する必要がない場合は、DirectPlayLobby3 オブジェクトを作成する必要はない。しかし、このクラスは、モデムを列挙したり、非ロビー アプリケーションで使用される DirectPlay アドレスを作成したりするためのメソッドを保持している。

DirectPlayLobbyConnection クラスは、アプリケーションがロビーによって起動されたときに、アプリケーションに渡される接続データを表す。

さまざまな種類のデータの収集 (列挙と言う) は、次のクラスのオブジェクトによって管理される。

  • DirectPlayEnumConnections
  • DirectPlayEnumLocalApplications
  • DirectPlayEnumPlayers
  • DirectPlayEnumSessions

たとえば、利用可能な接続に関する情報をアプリケーションで取得するには、DirectPlayEnumConnections オブジェクトを作成する。このオブジェクトのメソッドを使用すると、任意の接続に関するデータを取得することができる。

DirectPlayMessage クラスのオブジェクトは、アプリケーションまたはロビーとの間で送受信されるメッセージを表す。

DirectPlayAddress クラスは、IP アドレスや電話番号など、アプリケーションによって使用される既知の接続データをカプセル化する。ほとんどのアプリケーションではこのクラスを使用する必要はない。

最後に、DirectPlaySessionData クラスのオブジェクトは、既存のセッションまたはこれから作成されるセッションに関する情報を保持する。


DirectPlay の要点

ここでは、DirectPlay® API を実装するための実践的なガイドを提供する。次のトピックについて説明する。

  • DirectPlay アプリケーションを記述するための基本手順
  • DirectPlay プロバイダの使用
  • ロビー プロバイダ
  • セッション管理
  • プレーヤー管理
  • グループ管理
  • ロビー セッション
  • ロビー対応アプリケーションの作成
  • DirectPlay メッセージ
  • DirectPlay アドレス
  • DirectPlay プロトコル
  • DirectPlay プロトコルを使用した非同期ネットワーキング
  • セキュリティと認証
  • DirectX の以前のバージョンからの移行


DirectPlay アプリケーションを記述するための基本手順

このセクションでは、非ロビー型マルチプレーヤー ゲームまたはその他のネットワーク アプリケーションに参加するために、典型的なアプリケーションがとる基本ステップについて簡単に説明する。

[C++]

これらのステップを実行したコード例を確認するには、Duel サンプルのコードを参照すること。また、「チュートリアル 2 : ダイアログ ボックスを使用した接続」も参照すること。

1. DirectPlay を初期化する

アプリケーションは、最初に IDirectPlay4 インターフェイスのインスタンスを作成して、DirectPlay オブジェクトを作成しなければならない。このインターフェイスのメソッドを使用して、ロビーの外部における通信の要素をすべて管理する。

2. サービス プロバイダを列挙する

アプリケーションは、IDirectPlay4::EnumConnections メソッドを使用して、システム上で利用可能なサービス プロバイダを列挙する。通常は利用可能な接続がリスト ボックスで提示され、ユーザーはその中から 1 つを選択するように求められる。

3. 接続を初期化する

ユーザーが接続を選択すると、アプリケーションは IDirectPlay4::InitializeConnection を呼び出す。このとき、サービス プロバイダはユーザーに対し、使用するモデムや電話番号などの追加情報を求める場合がある。ユーザーがサービス プロバイダのダイアログをキャンセルした場合、セッションを作成することは可能だが、既存のセッションに参加することはできない。

4. セッションを作成するか、またはセッションに参加する

アプリケーションでは通常、新しいセッションを作成するか、既存のセッションに参加するかをユーザーに選択させる。既存のセッションのリストを取得するには、IDirectPlay4::EnumSessions を呼び出す。セッションを作成したり、既存のセッションに参加したりするには、IDirectPlay4::Open メソッドまたは IDirectPlay4::SecureOpen メソッドを使用する。セッションを作成するアプリケーションは、自動的にそのセッションに参加し、通常はそのセッションのホストになる。

5. プレーヤーを作成する

アプリケーションは、セッションに参加すると、識別とメッセージ管理のために最低 1 人のプレーヤーを作成しなければならない。それには、IDirectPlay4::CreatePlayer メソッドを使用する。

IDirectPlay4::EnumPlayers を呼び出すと、作成したプレーヤーを列挙することができる。アプリケーションは、たとえばセッションに現在参加しているプレーヤーの名前を一覧表示するために、このメソッドを呼び出すことができる。

また、プレーヤーをグループまたはサブグループで整理することもできる。詳細については、「グループ管理」を参照すること。

6. ゲームを開始する

アプリケーションは、ゲーム (またはその他の種類のセッション) をいつ、どのように開始するかを判断する。プレーヤーが一定の人数に達した後にホスト ユーザーがいつでもゲームを開始できるようにする場合もあれば、一定人数のユーザーが参加したときにゲームが自動的に開始されるようにする場合もある。ホストはすべてのプレーヤーにメッセージを送信し、ゲームが始まったことを通知する。プレーヤーは、IDirectPlay4::Send、IDirectPlay4::SendEx、および IDirectPlay4::Receive メソッドを使用してメッセージを交換し、ゲームの状態を更新する。

[Visual Basic]

これらのステップを実行したコード例を確認するには、「チュートリアル 1 : 簡単なネットワーク ゲームの作成」を参照すること。

1. DirectPlay を初期化する

アプリケーションは、最初に DirectX7.DirectPlayCreate を呼び出して、DirectPlay4 オブジェクトを作成する必要がある。DirectPlay4 クラスのメンバを使用して、ロビーを使用しない場合の通信の要素をすべて管理する。

2. サービス プロバイダを列挙する

アプリケーションは、DirectPlay4.GetDPEnumConnections メソッドを使用して、システム上でさまざまなサービス プロバイダを介して利用可能な接続を列挙する。通常は利用可能な接続がリスト ボックスで提示され、ユーザーはその中から 1 つを選択するように求められる。

3. 接続を初期化する

ユーザーが接続を選択すると、アプリケーションは DirectPlay4.InitializeConnection を呼び出す。これにより、DirectPlay が特定のサービス プロバイダにバインドされる。このとき、サービス プロバイダはユーザーに対し、使用するモデムや電話番号などの追加情報を求める場合がある。ユーザーがサービス プロバイダのダイアログ ボックスをキャンセルした場合、セッションを作成し、別のプレーヤーが (ダイヤル インなどによって) 接続できるようになるまで物理接続の確立を延期することができる。

4.セッションを作成するか、またはセッションに参加する

アプリケーションでは通常、新しいセッションを作成するか、既存のセッションに参加するか (物理セッションが確立している場合) をユーザーに選択させる。既存のセッションのリストを取得するには、DirectPlay4.GetDPEnumSessions を呼び出す。セッションを作成したり、セッションに参加したりするには、DirectPlay4.Open メソッドまたは DirectPlay4.SecureOpen メソッドを使用する。セッションを作成するアプリケーションは、自動的にそのセッションに参加し、通常はそのセッションのホストになる。

5. プレーヤーを作成する

アプリケーションは、セッションに参加すると、識別とメッセージ管理のために最低 1 人のプレーヤーを作成しなければならない。それには、DirectPlay4.CreatePlayer メソッドを使用する。

DirectPlay4.GetDPEnumPlayers を呼び出すと、作成したプレーヤーを列挙することができる。アプリケーションは、たとえばセッションに現在参加しているプレーヤーの名前を一覧表示するために、このメソッドを呼び出すことができる。

また、プレーヤーをグループまたはサブグループで整理することもできる。詳細については、「グループ管理」を参照すること。

6. ゲームを開始する

アプリケーションは、ゲーム (またはその他の種類のセッション) をいつ、どのように開始するかを判断する。プレーヤーが一定の人数に達した後にホスト ユーザーがいつでもゲームを開始できるようにする場合もあれば、一定人数のユーザーが参加したときにゲームが自動的に開始されるようにする場合もある。ホストはすべてのプレーヤーにアプリケーションで定義されたメッセージを送信し、ゲームが始まったことを通知する。プレーヤーは、DirectPlay4.Send、DirectPlay4.SendEx、および DirectPlay4.Receive メソッドを使用してメッセージを交換し、ゲームの状態を更新する。


DirectPlay プロバイダの使用

サービス プロバイダは、DirectPlay の要求に応じて、ネットワークに固有の通信サービスを提供する。概要については、「サービス プロバイダ」を参照すること。

Microsoft は、DirectPlay に次のサービス プロバイダを含めている。

  • TCP/IP
  • IPX
  • モデムツーモデム
  • シリアル リンク

ここでは、デフォルトのサービス プロバイダを使用してできることについて簡単に説明する。サードパーティのサービス プロバイダの動作に関する情報を取得するには、ネットワーク事業者に問い合わせること。


TCP/IP

TCP/IP (転送制御プロトコル/インターネット プロトコル) サービス プロバイダは、TCP/IP プロトコルを利用し、Windows Sockets を使用して、インターネットまたはローカル エリア ネットワーク (LAN) を介して通信する。このサービス プロバイダは、非保証メッセージングには UDP (User Datagram Protocol) パケットを使用し、保証メッセージングには TCP を使用する。1 台のコンピュータで、TCP/IPを使用して複数の DirectPlay セッションをホストすることができる。

アプリケーションがセッションを列挙すると、TCP/IP がダイアログ ボックスを表示して、セッションの IP アドレスをユーザーにたずねる。インターネット上のセッションの場合、ユーザーは参加するセッションをホストするコンピュータの IP アドレスを入力する必要がある。コンピュータが名前を持っている場合 (microsoft.com など)、その名前を IP アドレスの代わりに使用することができる。その場合、DirectPlay は DNS (Domain Name System) ルックアップを使用してその名前を検索する。また、ユーザーはアドレスを空のままにして [OK] をクリックすることもできる。その場合、DirectPlay はメッセージをブロードキャストしてセッションを検索する。この処理は、通常は LAN 上および同一サブネット上でのみ機能する。

[C++]

セッションをホストしている場合は、アプリケーションで IDirectPlay4::GetPlayerAddress を使用してローカル IP アドレスを取得することができる。

アプリケーションは、IDirectPlay4::InitializeConnection メソッドを使用するか、または IDirectPlayLobby3::SetConnectionSettings メソッドを使用してから IDirectPlayLobby3::Connect メソッドを呼び出すことにより、DirectPlay アドレスのサービス プロバイダに IP アドレスを提供することができる。アドレスは、null で終わる ANSI または Unicode 文字列でなければならない (それぞれ異なるデータ タイプ GUID を持つ)。セッションのブロードキャスト列挙が望ましい場合、アドレスは、長さ 0 の文字列、つまり null ターミネータだけからなる文字列でなければならない。詳細については、「DirectPlay アドレス」を参照すること。

TCP/IP サービス プロバイダは、ポート 47624 を使用して列挙要求を送受信する。通信は、ポート 2300 ～ 2400 の間で送信される。ファイアウォールを通過して通信するには、すべてのコンピュータが DirectX 6.0 以降とポート 47624 を使用し、内向きと外向きの両方の TCP および UDP トラフィックに対してポート 2300 ～ 2400 を空けておく必要がある。詳細については、「ファイアウォールのサポート」を参照すること。

注 : DirectPlay は、最初にポート 2300 を割り当て、以降のポートを順に割り当てる。開くポートの範囲が 2400 に満たない場合もある。

アプリケーションは、使用する特定のポートを選択することができる。そのためには、DPAID_INetPort というデータを含む DirectPlay アドレスを使用して TCP/IP サービス プロバイダを初期化する必要がある。詳細については、「DirectPlay アドレス」および「DirectPlay アドレスのデータ型」を参照すること。アプリケーションが使用する特定のポートを選択すると、すべての通信はそのポートを経由して送信される。この場合、TCP および UDP を使用した外向きおよび内向きの両方の通信に対して、そのポートを開くだけでよい。

TCP/IP サービス プロバイダの GUID は、DPSPGUID_TCPIP と定義されている。

[Visual Basic]

セッションをホストしている場合は、アプリケーションで DirectPlay4.GetPlayerAddress を使用してローカル IP アドレスを取得することができる。

アプリケーションは、DirectPlayLobby3.CreateINetAddress メソッドを使用して DirectPlay アドレスを作成することができる。作成したアドレスは、DirectPlayAddress オブジェクトを DirectPlay4.InitializeConnection メソッドに渡すか、またはそのオブジェクトを DirectPlayLobby3.SetConnectionSettings に渡してから DirectPlayLobby3.Connect を呼び出すことにより、サービス プロバイダに渡すことができる。詳細については、「DirectPlay アドレス」を参照すること。

DirectPlay ロビーのサポートを追加すると、ユーザーはゲームの開始時に IP アドレスを入力する必要がなくなる。詳細については、「同期起動」を参照すること。


IPX

IPX サービス プロバイダは、IPX (Internet Packet Exchange) プロトコルを利用し、Windows Sockets を使用してローカル エリア ネットワーク (LAN) を介して通信を行う。このサービス プロバイダは、非保証メッセージングだけをサポートする。IPX 上で保証メッセージングを実行するには、DirectPlay プロトコルを使用する。1 台のコンピュータで IPX を使用してホストできる DirectPlay セッションは 1 つだけである。

IPX は、ネットワーク上のセッションを検索するために、常にブロードキャストを使用する。そのため、このサービス プロバイダは、追加情報を要求するダイアログ ボックスを表示することはない。

IPX は、別のサブネット上のセッションは列挙しない。

セッションが確立すると、パケットはコンピュータ間で直接送信される (ブロードキャストされない)。

IPX サービス プロバイダの GUID は、DPSPGUID_IPX と指定することができる。


モデムツーモデム

モデムツーモデム サービス プロバイダは、テレフォニー API (TAPI) を使用してほかのモデムと通信する。このサービス プロバイダは、非保証メッセージングだけをサポートする。モデム セッションで保証メッセージングを実行するには、DirectPlay プロトコルを使用する。

セッションを作成すると、ダイアログ ボックスが表示される。ユーザーはモデムとその設定を選択してから、モデムを自動応答モードに設定する。セッションを列挙した場合もダイアログ ボックスが表示され、電話番号と使用するモデムがたずねられる。情報が入力されると、DirectPlay はモデムにダイヤルし、先方のコンピュータがホストしているセッションを検索する。

[C++]

ダイアログ ボックスを表示せずにモデム セッションを列挙するには (たとえば、アプリケーションが電話番号を把握していて、IDirectPlay4::InitializeConnection が呼び出されたときにその電話番号がサービス プロバイダに渡されていた場合)、DPENUMSESSIONS_RETURNSTATUS フラグを設定せずに IDirectPlay4::EnumSessions をループで使用する (詳細については、EnumSessions を参照)。DP_OK が返された場合、アプリケーションは EnumSessions をもう一度使用して実際のセッションのリストを取得する必要がある。

このようにして EnumSessions をループで使用する場合、アプリケーションではウィンドウ メッセージのループを次のように実装する必要がある。

while (lpDPLAY->EnumSessions(lpsd, 0, lpEnumSessionsCallback,
        lpContext, DPENUMSESSIONS_RETURNSTATUS) == DPERR_CONNECTING)
{
    MSG    msg;

    if (PeekMessage(&msg, 0, 0, 0, PM_REMOVE))
    {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }

    Sleep(500);
}

メッセージ処理に挿入する遅延時間が長すぎると、パケットを失う場合がある。たとえば、大量のデバッグ情報を出力する場合などに、こうしたことが起こる可能性がある。

利用可能なモデムの最新のリストをサービス プロバイダから取得するには、そのサービス プロバイダを初期化し、プレーヤー ID にゼロを指定して IDirectPlay4::GetPlayerAddress メソッドを呼び出す。返される DirectPlay アドレスには、ANSI のモデム名 (DPAID_Modem) と Unicode のモデム名 (DPAID_ModemW) が含まれている。モデムのリストは、null で終わる一連の文字列で、リストの最後に長さゼロの文字列が含まれている。詳細については、「DirectPlay アドレスのデータ型」を参照すること。

[Visual Basic]

ダイアログ ボックスを表示せずにモデム セッションを列挙するには (たとえば、アプリケーションが電話番号を把握していて、DirectPlay4.InitializeConnection が呼び出されたときにその電話番号がサービス プロバイダに渡されていた場合)、DPERR_CONNECTING エラーが発生しなくなるまで、DPENUMSESSIONS_RETURNSTATUS フラグを設定して DirectPlay4.GetDPEnumSessions を繰り返し呼び出す。ループの実行中にイベントを処理できるようにする必要がある。これを行う方法の一例を次のサンプル コードに示す。

' objDPlay は DirectPlay4 オブジェクト。
' SessionData は、有効な情報を含む DirectPlaySessionData オブジェクト。

On Error GoTo DO_AGAIN
Do While DoEvents
    objDPlay.GetDPEnumSessions(SessionData, 0, _
          DPENUMSESSIONS_AVAILABLE Or DPENUMSESSIONS_RETURNSTATUS)
    Exit Do    ' エラーなし。列挙完了。
DO_AGAIN:
    ' ほかのエラーの場合は、あきらめる。
    if Err.Number <> DPERR_CONNECTING Then
        ' エラーを処理する - セッションを列挙できない。
        Exit Do
    End If
    ' まだ接続しているので、再度試みる。
Loop
On Error GoTo 0

利用可能なモデムの名前をサービス プロバイダから取得するには、そのサービス プロバイダを初期化し、インデックス値 1 から DirectPlayLobby3.GetModemCount によって返される値までに対して、DirectPlayLobby3.GetModemName メソッドを呼び出す。

モデムツーモデム サービス プロバイダの GUID は、DPSPGUID_MODEM と指定することができる。


シリアル リンク

シリアル リンクは、ほかのコンピュータとシリアル ポートを介して通信するために利用される。このサービス プロバイダは、非保証メッセージングだけをサポートする。シリアル リンクで保証メッセージングを実行するには、DirectPlay プロトコルを使用する。

セッションを作成するか、またはセッションを列挙すると、シリアル ポートを構成するようにユーザーにたずねるダイアログ ボックスが表示される。ポートは両方のコンピュータで同じように構成されている必要がある。

シリアル リンク サービス プロバイダは、DPSPGUID_SERIAL と指定することができる。


ロビー プロバイダ

ロビー プロバイダは、ロビー サーバーの開発者によって提供されるクライアント コンポーネント (DLL) である。ロビー プロバイダは、DirectPlay の要求に応じて、ロビー サーバーとの通信機能を実装する。DirectPlay API を使用して記述されたロビー クライアントは、システム上に存在するどのロビー プロバイダ DLL のロビー サーバーともやり取りすることができる。

DirectX SDK は、SDK に含まれているテスト用のロビー サーバーおよびクライアントで使用するロビー プロバイダをインストールする。このロビー プロバイダを使用するには、DirectX SDK ディレクトリの \Samples\Multimedia\DPlay\Bin フォルダにある Dpldplay.reg をダブルクリックしてそれを登録する必要がある。詳細については、「Bellhop サンプル」を参照すること。


セッション管理

DirectPlay セッションは、2 つ以上のアプリケーションまたはアプリケーションのインスタンスの間の通信チャネルである。

注 : 接続の種類によっては、1 台のコンピュータ上の複数のアプリケーション インスタンスがセッションに参加する場合がある。たとえば、最大 4 人のプレーヤーが IPX または TCP/IP 接続を使用して 1 台のコンピュータ上で Memory サンプルをプレイすることができる。しかし、ほとんどの場合は、セッションには独立したコンピュータが含まれる。説明を簡単にするために、以下では、セッションの各参加者を "コンピュータ" と呼ぶ。

コンピュータは、2 つの方法のいずれかでセッションの一部となる。つまり、コンピュータはネットワーク上の既存のセッションをすべて列挙してそのうちのいずれかに参加するか、または新しいセッションを作成してほかのコンピュータが参加するのを待機することができる。アプリケーションがセッションの一部になると、プレーヤーを作成し、セッション内のほかのすべてのプレーヤーとの間でメッセージをやり取りすることができる。

各セッションには、ホストとして 1 台のコンピュータが割り当てられる。ホストは、セッションの所有者であり、セッションのプロパティを変更できる唯一のコンピュータである。

次の図は、DirectPlay のセッション モデルを示している。

DirectPlay は、次のセッション管理用メソッドを提供する。

[C++]
  • IDirectPlay4::EnumSessions は、利用可能なセッションをすべて列挙する。
  • IDirectPlay4::Open は、列挙したセッションのいずれかに参加するか、または新しいセッションを作成する。
  • IDirectPlay4::SecureOpen は、IDirectPlay4::Open と同じ機能を実行するが、アプリケーションによるデフォルトのオープン動作の変更を可能にする。
  • IDirectPlay4::StartSession は、ステージング領域からセッションを開始する。
  • IDirectPlay4::Close は、現在開いているセッションを離れる。
  • IDirectPlay4::GetSessionDesc は、カレント セッションのプロパティを取得する。
  • IDirectPlay4::SetSessionDesc は、カレント セッションのプロパティを変更する。
  • IDirectPlay4::GetCaps は、基盤となるネットワークの通信機能を取得する。
[Visual Basic]
  • DirectPlay4.GetDPEnumSessions は、利用可能なセッションをすべて列挙する。
  • DirectPlay4.Open は、列挙したセッションのいずれかに参加するか、または新しいセッションを作成する。
  • DirectPlay4.SecureOpen は、DirectPlay4.Open と同じ機能を実行するが、アプリケーションによるデフォルトのオープン動作の変更を可能にする。
  • DirectPlay4.StartSession は、ステージング領域からセッションを開始する。
  • DirectPlay4.Close は、現在開いているセッションを離れる。
  • DirectPlay4.CreateSessionData は、セッションの記述に使用される DirectPlaySessionData オブジェクトを作成する。
  • DirectPlay4.GetSessionDesc は、カレント セッションのプロパティを取得する。
  • DirectPlay4.SetSessionDesc は、カレント セッションのプロパティを変更する。
  • DirectPlay4.GetCaps は、基盤となるネットワークの通信機能を取得する。


プレーヤー管理

プレーヤーは、メッセージを送受信できる、セッション内の論理オブジェクトを表す。プレーヤーを作成すると、DirectPlay によって、セッションが続いている限り再利用されない一意の ID 番号が割り当てられる。

各プレーヤーは、ローカル プレーヤー (ローカルのコンピュータ上に存在する) またはリモート プレーヤー (ほかのコンピュータ上に存在する) として識別される。各コンピュータは、メッセージの送受信を開始する前に最低 1 人のプレーヤーを保持していなければならない。各コンピュータは、1 人以上のローカル プレーヤーを保持することができる。

アプリケーションがメッセージを送信する場合、そのメッセージは別のコンピュータではなく、常に別のプレーヤーに向かう。送信先のプレーヤーは、ほかのローカル プレーヤー (この場合、メッセージはネットワーク上には送出されない) またはリモート プレーヤーのどちらでもよい。同様に、アプリケーションがメッセージを受信する場合、それらは常に特定の (ローカル) プレーヤーに送られ、ほかのプレーヤーからのものであるとマークされる (ただし、システム メッセージは常に DPID_SYSMSG からのものであるとマークされる)。

DirectPlay は、アプリケーションで利用可能な追加のプレーヤー管理メソッドを提供する。これらを使用すると、名前をプレーヤーと関連付け、その名前をセッションに参加しているほかのすべてのコンピュータに自動的に伝承することができる。同様に、セッション内のほかのすべてのプレーヤーに伝承される任意のデータをプレーヤーに関連付けることもできる。また、ローカル コンピュータだけが使用できるプライベートなローカル データをプレーヤーに関連付けることもできる。

[C++]

DirectPlay は、プレーヤー管理に必須の以下のメソッドを提供する。

  • IDirectPlay4::EnumPlayers は、セッション内のすべてのプレーヤーを列挙する。
  • IDirectPlay4::CreatePlayer は、ローカル プレーヤーを作成する。
  • IDirectPlay4::DestroyPlayer は、ローカル プレーヤーを破棄する。

DirectPlay は、プレーヤー情報を管理するための以下の追加メソッドを提供する。

  • IDirectPlay4::GetPlayerAccount は、プレーヤーのアカウント情報を取得する。
  • IDirectPlay4::GetPlayerAddress は、プレーヤーのネットワーク固有アドレスを取得する。
  • IDirectPlay4::GetPlayerData は、プレーヤーに関連付けられたアプリケーション固有データを取得する。
  • IDirectPlay4::GetPlayerFlags は、プレーヤーに関する追加情報を取得する。
  • IDirectPlay4::GetPlayerCaps は、プレーヤーの通信能力に関する情報を取得する。
  • IDirectPlay4::GetPlayerName は、プレーヤーのフレンドリ名と正式名を取得する。
  • IDirectPlay4::SetPlayerName は、プレーヤーのフレンドリ名と正式名を変更する。
  • IDirectPlay4::SetPlayerData は、アプリケーションに固有のデータをプレーヤーに関連付ける。
[Visual Basic]

DirectPlay は、プレーヤー管理に必須の以下のメソッドを提供する。

  • DirectPlay4.GetDPEnumPlayers は、セッション内のすべてのプレーヤーを列挙する。
  • DirectPlay4.CreatePlayer は、ローカル プレーヤーを作成する。
  • DirectPlay4.DestroyPlayer は、ローカル プレーヤーを破棄する。

DirectPlay は、プレーヤー情報を管理するための以下の追加メソッドを提供する。

  • DirectPlay4.GetPlayerAccountId は、プレーヤーのアカウント情報を取得する。
  • DirectPlay4.GetPlayerAddress は、プレーヤーのネットワーク固有アドレスを取得する。
  • DirectPlay4.GetPlayerCaps は、プレーヤーの通信能力を取得する。
  • DirectPlay4.GetPlayerData は、プレーヤーに関連付けられたアプリケーション固有データを取得する。
  • DirectPlay4.GetPlayerFlags は、プレーヤーに関する追加情報を取得する。
  • DirectPlay4.GetPlayerFormalName は、プレーヤーの正式名 ("長い" 名前) を取得する。
  • DirectPlay4.GetPlayerFriendlyName は、プレーヤーのフレンドリ名 ("短い" 名前) を取得する。
  • DirectPlay4.SetPlayerName は、プレーヤーのフレンドリ名と正式名を変更する。
  • DirectPlay4.SetPlayerData は、アプリケーションに固有のデータをプレーヤーに関連付ける。


グループ管理

DirectPlay は、セッション内のグループをサポートする。グループは、プレーヤーの論理的な集まりである。アプリケーションはメッセージをグループに送信することができる。すると、そのグループ内のすべてのプレーヤーがメッセージを受信する。プレーヤーと同じく、グループは、セッションの継続中に再利用されない一意の番号によって識別される。

グループは、セッションに参加しているプレーヤーを整理するために利用できる。たとえば、チーム別に整理することが可能である。プレーヤーは 2 つ以上のグループに属することができる。グループを破棄すると、すべてのプレーヤーがグループから削除されるが、プレーヤー自体は破棄されない。

また、グループはサブグループや、グループへのショートカットを保持することができる。CreateGroup メソッドを使用してグループを作成すると、そのグループが最上位のグループ (A とする) になる。このグループへのショートカットを、AddGroupToGroup メソッドを使用してほかのグループ (B とする) に追加することができる。グループ B を破棄すると、A へのショートカットも破棄されるが、A は最上位のグループとして残る。一方、CreateGroupInGroup メソッドを使用してグループ B 内でグループ A を作成した場合、A は最上位グループではないので、B を破棄すると、A も破棄される。

グループに送信されたメッセージは、そのグループに直接または間接的に属するすべてのプレーヤーに送られる。たとえば、Quarterback というプレーヤーを BlueOffense というグループに追加し、BlueOffense グループを BlueTeam グループに追加したとしよう。Quarterback は BlueTeam に直接追加されたわけではないが、BlueOffense に送信されたメッセージだけではなく、BlueTeam に送信されたメッセージもすべて受信する。

プレーヤーのグループを管理するための独自のシステムを実装するよりも、DirectPlay のグループ管理方法を利用した方が賢明である。DirectPlay は、サービス プロバイダのあらゆるマルチキャスティング機能を利用してグループ メッセージを送信し、メッセージ トラフィックを軽減することができる。詳細については、「ピアツーピア セッション」を参照すること。

[C++]

DirectPlay は、グループとそのメンバを管理するために不可欠な以下のメソッドを提供する。

IDirectPlay4::AddPlayerToGroup は、プレーヤーをグループに追加する。

IDirectPlay4::CreateGroup は、新しい最上位グループを作成する。

IDirectPlay4::DeletePlayerFromGroup は、プレーヤーをグループから削除する。

IDirectPlay4::DestroyGroup は、グループを破棄する。

IDirectPlay4::EnumGroupPlayers は、グループ内のプレーヤーを列挙する。

IDirectPlay4::EnumGroups は、セッション内のすべてのグループを列挙する。

DirectPlay は、グループとグループ情報を管理するための以下の追加メソッドを提供する。

IDirectPlay4::AddGroupToGroup は、グループのショートカットを既存のグループに追加する。

IDirectPlay4::CreateGroupInGroup は、既存のグループ内にグループを作成する。

IDirectPlay4::DeleteGroupFromGroup は、AddGroupToGroup を使用してグループに追加されたグループを削除する。ただし、削除されたグループは破棄されない。

IDirectPlay4::EnumGroupsInGroup は、グループ内のグループをすべて列挙する。

IDirectPlay4::GetGroupConnectionSettings は、グループの接続設定を取得する。

IDirectPlay4::GetGroupData は、グループに関連付けられたアプリケーション固有データを取得する。

IDirectPlay4::GetGroupFlags は、グループの作成方法に関する追加情報を取得する。

IDirectPlay4::GetGroupName は、グループの名前を取得する。

IDirectPlay4::GetGroupOwner は、グループの所有者を取得する。

IDirectPlay4::GetGroupParent は、CreateGroupInGroup を使用して作成されたサブグループの親の ID を取得する。

IDirectPlay4::SetGroupConnectionSettings は、グループの接続設定を行う。

IDirectPlay4::SetGroupData は、当該のコンピュータによって作成されたグループに関連付けられているアプリケーション固有データを変更する。

IDirectPlay4::SetGroupName は、当該のコンピュータによって作成されたグループの名前を変更する。

IDirectPlay4::SetGroupOwner は、グループの所有者を変更する。

[Visual Basic]

DirectPlay は、グループとそのメンバを管理するために不可欠な以下のメソッドを提供する。

DirectPlay4.AddPlayerToGroup は、プレーヤーをグループに追加する。

DirectPlay4.CreateGroup は、新しい最上位グループを作成する。

DirectPlay4.DeletePlayerFromGroup は、プレーヤーをグループから削除する。

DirectPlay4.DestroyGroup は、グループを破棄する。

DirectPlay4.GetDPEnumGroupPlayers は、グループ内のプレーヤーを列挙する。

DirectPlay4.GetDPEnumGroups は、セッション内のすべてのグループを列挙する。

DirectPlay は、グループとグループ情報を管理するための以下の追加メソッドを提供する。

DirectPlay4.AddGroupToGroup グループのショートカットを既存のグループに追加する。

DirectPlay4.CreateGroupInGroup は、既存のグループ内にグループを作成する。

DirectPlay4.DeleteGroupFromGroup は、AddGroupToGroup を使用してグループに追加されたグループを削除する。ただし、削除されたグループは破棄されない。

DirectPlay4.GetDPEnumGroupsInGroup は、グループ内のグループをすべて列挙する。

DirectPlay4.GetGroupData は、グループに関連付けられたアプリケーション固有データを取得する。

DirectPlay4.GetGroupFlags は、グループの作成方法に関する追加情報を取得する。

DirectPlay4.GetGroupLongName は、グループのログオン名または正式名を取得する。

DirectPlay4.GetGroupOwner は、グループの所有者を取得する。

DirectPlay4.GetGroupParent は、CreateGroupInGroup を使用して作成されたサブグループの親の ID を取得する。

DirectPlay4.GetGroupShortName は、グループのショートカット名またはフレンドリ名を取得する。

DirectPlay4.SetGroupConnectionSettings は、ロビー セッションにおけるグループの接続設定を行う。

DirectPlay4.SetGroupData は、当該のコンピュータによって作成されたグループに関連付けられているアプリケーション固有データを変更する。

DirectPlay4.SetGroupName は、グループのロング ネームとショート ネームを変更する。

DirectPlay4.SetGroupOwner は、グループの所有者を変更する。


ロビー セッション

ロビー セッションは、DirectPlay クライアント/サーバー セッション (「クライアント/サーバー セッション」の図を参照) によく似ている。ロビー セッションとは、ロビー サーバーへの接続を表す。この場合、クライアントとサーバーは、共同で機能するようには記述されていない。アプリケーション セッションとは、伝統的な DirectPlay セッションを表す。このセッションでは、すべてのクライアントとサーバーは、共同で機能するように記述されている。

DirectPlay を使用してロビー サーバーと通信するための最初のステップは、使用するロビー プロバイダと接続するロビー サーバーを選択することである。利用可能なプロバイダをほかの DirectPlay サービス プロバイダと同じように列挙し、接続を同じ方法で確立する。「DirectPlay アプリケーションを記述するための基本手順」を参照すること。

ロビー クライアントは、アプリケーション クライアントがアプリケーション セッションを検索してそれに参加する方法と同じ方法でロビー セッションを検索し、それに参加する (「セッション管理」を参照)。ロビー セッションに参加すると、クライアント アプリケーションはロビー サーバー上のすべての情報にアクセスできるようになり、ユーザーはロビー サーバー上のほかのユーザーとやり取りできるようになる。

DirectPlay アプリケーション セッションの場合と同じく、プレーヤーはロビー セッションにおける基本エンティティである。各プレーヤーは、ロビー サーバーに接続しているクライアント コンピュータ上のユーザーを表す。また、ロビー サーバーを表すサーバー プレーヤーも存在する。ロビー クライアントは、(ロビー セッションに参加することにより) ロビー サーバーに接続した後、ユーザーの存在を確立しなければならない。そのために、プレーヤーを作成し、そのプレーヤーがサーバーやほかのプレーヤーとの通信を開始する前に、そのプレーヤーを初期グループに追加する。事実、セッションに接続しているほかのユーザーは、このようにしてユーザーの存在が確立されるまでは、そのユーザーの存在に気付かない。

ロビー セッションに参加しているプレーヤーを管理するためには、アプリケーション セッションで利用するプレーヤー管理方法と同じ方法を使用する。「プレーヤー管理」を参照。

ロビー セッションに参加しているプレーヤーは、通常のメッセージを互いにやり取りすることはできない。DirectPlay のロビー構造では、DirectPlay API を使用する任意のアプリケーションは、任意のロビー サーバーに接続できる。つまり、同じロビー セッション内に複数の異なるロビー クライアント アプリケーションが存在し、それらすべてがアプリケーションで定義された異なるメッセージ セットを使用している可能性がある。

[C++]

しかし、クライアントは、標準のロビー メッセージと IDirectPlayLobby3::SendLobbyMessage メソッドを使用して、ロビーとメッセージをやり取りすることができる。さらに、プレーヤーは IDirectPlay4::SendChatMessage メソッドを使用して、互いにテキストを送信することができる。このメソッドを使用すると、ロビーはチャット メッセージを含むシステム メッセージを受け手に送信する。

[Visual Basic]

しかし、クライアントは、標準のロビー メッセージと DirectPlayLobby3.SendLobbyMessage メソッドを使用して、ロビーとメッセージをやり取りすることができる。さらに、プレーヤーは DirectPlay4.SendChatMessage メソッドを使用して、互いにテキストを送信することができる。このメソッドを使用すると、ロビーはチャット メッセージを含むシステム メッセージを受け手に送信する。

グループは、ロビー セッションではより重要な役割を果たす。これは、グループはロビー サーバー全体の編成を定義し、アプリケーション セッションを起動するために利用されるからである。

ロビー サーバーの目的上、グループはルームまたはステージング領域のいずれかに区分される。

ルームは、プレーヤーやほかのグループを保持できる標準のグループである。ルームは、主にプレーヤーがロビーのコンテキスト内でほかのプレーヤーとやり取りする出会いの場として利用される。ルームは、ほかのルームへのリンクと、もう 1 つの種類のグループ、つまりステージング領域へのリンクを保持する。

ステージング領域は、通常はプレーヤーだけを保持する。ステージング領域は、新しいセッションの開始にあたってプレーヤーを整理するために利用される。セッションを開始した後は、ステージング領域を破棄するか、または新しいプレーヤーが進行中のセッションに参加できるようにそのまま維持しておくことができる。

ルーム グループは、主に階層構造で整理される。最上位グループがいくつか作成され、続いて既存のグループ内にほかのグループが作成される。ロビー クライアントは、最上位グループと、グループ内に含まれているグループをすべて列挙することができる。ロビー サーバーは、グループを Web 構造に整理することもできる。作成したグループは、ほかのグループに追加することができる。すると、2 つのグループ間にリンクが作成される。ロビー クライアントがグループ内のグループを列挙すると、サブグループとリンク先グループがすべて返される。

次の図は、ロビー セッションの編成を示している。

プレーヤーは、グループに参加するまでは、認識されない。プレーヤーは一度に 2 つ以上のグループに属することができる。

通常、プレーヤーが確認できるロビー セッションの範囲は、そのプレーヤーが属するグループによって制限される。この制限により、サーバーがクライアントにダウンロードしなければならない情報量が軽減される。プレーヤーは、自らを現在のグループから削除し、新しいグループに追加することにより、ロビー サーバーの空間を移動することができる。


同期起動

[C++]

アプリケーション セッションは、ステージング領域で準備され、起動される。1 人のプレーヤーがステージング領域を作成し、ほかのプレーヤーがそれに参加するのを待機する。プレーヤーは、IDirectPlay4::SetGroupConnectionSettings メソッドを使用して、作成されるアプリケーション セッションのプロパティを設定することができる。グループへの参加を検討しているほかのプレーヤーは、IDirectPlay4::GetGroupConnectionSettings メソッドを呼び出して、アプリケーション セッションのプロパティを確認することができる。十分な人数のプレーヤーがステージング領域に集まったら、任意のプレーヤーが IDirectPlay4::StartSession メソッドを呼び出して同期起動のシーケンスを開始することができる。

ステージング領域内のすべてのプレーヤーは、DPLCONNECTION 構造体を含む DPMSG_STARTSESSION システム メッセージを受信する。プレーヤーが外部ロビー クライアントを使用している場合、そのロビー クライアントは接続情報を IDirectPlayLobby3::RunApplication メソッドに渡すことにより、アプリケーションを起動することができる。プレーヤーが内部ロビーを使用している場合、アプリケーションは IDirectPlayLobby3::ConnectEx を呼び出すことにより、適切なセッションへの接続を確立することができる。詳細については、「外部ロビーによる開始のサポート」を参照すること。

[Visual Basic]

アプリケーション セッションは、ステージング領域で準備され、起動される (「ロビー セッション」を参照)。1 人のプレーヤーがステージング領域を作成し、ほかのプレーヤーがそれに参加するのを待機する。

プレーヤーは、DirectPlay4.SetGroupConnectionSettings メソッドを使用して、作成されるアプリケーション セッションのプロパティを設定することができる。十分な人数のプレーヤーがステージング領域に集まったら、任意のプレーヤーが DirectPlay4.StartSession メソッドを呼び出して同期起動のシーケンスを開始することができる。

ステージング領域内のすべてのプレーヤーは、接続に関する情報を含む DPSYS_STARTSESSION システム メッセージを受信する。プレーヤーが外部ロビー クライアントを使用している場合、そのロビー クライアントは DirectPlayLobby3.RunApplication メソッドを使用して、アプリケーションを起動することができる。プレーヤーが内部ロビーを使用している場合、アプリケーションは DirectPlayMessage.ReadSysMsgConnection を呼び出して接続設定を取得し、DirectPlayLobby3.SetConnectionSettings によってそれを設定してから DirectPlayLobby3.Connect を呼び出すことにより、適切なセッションへの接続を確立することができる。詳細については、「外部ロビーによる開始のサポート」を参照すること。


ロビー対応アプリケーションの作成

DirectPlay アプリケーションがロビー対応となるためには、最低でもロビーからの起動をサポートする必要がある。その他の機能を追加して、ロビーとの統合を強化することもできる。詳細については、次のトピックを参照すること。

  • ロビー対応アプリケーションの登録
  • 外部ロビーによる開始のサポート
  • リップル起動のサポート
  • 動的ロビー接続のサポート
  • ロビーとの関係の維持

DirectX のサンプルには、テスト用のロビー サーバー (Lserver.exe) とロビー クライアント (Bellhop.exe) が含まれている。これらを組み合わせて使用すると、アプリケーションのロビー対応機能をテストすることができる。


ロビー対応アプリケーションの登録

アプリケーションが DirectPlay ロビー クライアントから認識および起動されるようにするには、そのアプリケーションを DirectPlay アプリケーションとしてシステム レジストリに登録する必要がある。通常、アプリケーションはセットアップ中に登録するが、それにはセットアップ プログラムで DirectPlayLobby3 オブジェクトを作成する必要がある。また、アプリケーションをアンインストールした場合は、その登録を解除する必要がある。

[C++]

アプリケーションを登録するには、DPAPPLICATIONDESC 構造体または DPAPPLICATIONDESC2 構造体に必要な情報を入力し、それを IDirectPlayLobby3::RegisterApplication に渡す。レジストリ エントリを削除するには、IDirectPlayLobby3::UnRegisterApplication を呼び出す。

また、DirectX のセットアップ処理中にロビー対応アプリケーションを登録することもできる。それには、DirectXRegisterApplication 関数を呼び出す。この関数の長所は、DirectPlay のランタイム ファイルをインストールする前に呼び出せるということである。

[Visual Basic]

アプリケーションを登録するには、DPAPPLICATIONDESC2 型に必要な情報を入力し、それを DirectPlayLobby3.RegisterApplication に渡す。レジストリ エントリを削除するには、DirectPlayLobby3.UnRegisterApplication を呼び出す。


外部ロビーによる開始のサポート

ロビーの起動を把握し、アプリケーション セッションに参加するための基本的なステップは、次のとおりである。

[C++]
  1. スタートアップ時に、CoCreateInstance 関数を使用して IDirectPlayLobby3 インターフェイスを作成する。
  2. IDirectPlayLobby3::GetConnectionSettings メソッドを呼び出す (通常は、必要なバッファのサイズを取得するためと、バッファを割り当てた後の合計 2 回呼び出す)。このメソッドが DPERR_NOTLOBBIED を返す場合、アプリケーションはロビーによって起動されておらず、ユーザーによって通常の方法で実行された可能性が高い。非ロビー セッションの作成または接続をユーザーに許可するコード パスに従って先に進む。GetConnectionSettings が成功した場合、ロビーによって設定された接続設定 (セッション記述を含む) を保持する DPLCONNECTION 構造体が返される。変更を加えるには、IDirectPlayLobby3::SetConnectionSettings を使用する。
  3. IDirectPlayLobby3::ConnectEx を呼び出して、アプリケーション セッションを作成するか、またはアプリケーション セッションに参加する (アプリケーションは DPLCONNECTION.dwFlags を調べて、セッションを作成するか、またはセッションに参加するかを判断する)。
  4. ステップ 2 で取得した DPLCONNECTION 構造体によって提供される名前情報を使用して、プレーヤーを作成する。

この時点で、アプリケーションは、ユーザーが接続を手動で選択し、セッションに参加するかまたは作成し、作成するプレーヤーの名前を入力した場合と同じコード パスに従って、先に進むことができる。

ゲームでロビーに情報を返す場合は、IDirectPlayLobby3 インターフェイスを保存できる (「ロビーとの関係の維持」を参照)。それ以外の場合は、Release メソッドを使用してこのインターフェイスを削除できる。

追加情報とサンプル コードについては、Duel (Lobby.c) サンプルと ChatConnect (Lobby.cpp) サンプル、および「チュートリアル 1 : ロビーを使用した接続」を参照すること。

[Visual Basic]
  1. スタートアップ時に、DirectX7.DirectPlayLobbyCreate メソッドを使用して DirectPlayLobby3 オブジェクトを作成する。
  2. DirectPlayLobby3.GetConnectionSettings メソッドを呼び出す。このメソッドにより DPERR_NOTLOBBIED エラーが発生する場合、アプリケーションはロビーによって起動されておらず、ユーザーによって通常の方法で実行された可能性が高い。非ロビー セッションの作成または接続をユーザーに許可するコード パスに従って先に進む。GetConnectionSettings が成功した場合、ロビーによって設定された接続設定 (セッション記述を含む) を表す DirectPlayLobbyConnection オブジェクトが返される。変更を加えるには、DirectPlayLobby3.SetConnectionSettings を使用する。
  3. DirectPlayLobby3.Connect を呼び出して、アプリケーション セッションを作成するか、またはそれに参加する (アプリケーションは、DirectPlayLobbyConnection.GetFlags によって返される値を調べて、セッションを作成するか、またはセッションに参加するかを判断する)。
  4. ステップ 2 で取得した irectPlayLobbyConnection オブジェクトによって提供される名前情報を使用して、プレーヤーを作成する。

この時点で、アプリケーションは、ユーザーが接続を手動で選択し、セッションに参加するかまたは作成し、作成するプレーヤーの名前を入力した場合と同じコード パスに従って、先に進むことができる。

ゲームでロビーに情報を返す場合は、DirectPlayLobby3 オブジェクトを保存できる (「ロビーとの関係の維持」を参照)。

ロビーの多くは、アプリケーションを起動してからサスペンド モードに入り、アプリケーションが終了するのを待機する。DirectPlay は、起動したアプリケーションが終了したときに、ロビーに通知する。そのため、ロビーによって起動されたアプリケーションがほかのアプリケーションを起動しないことが重要である (しかし、正しく登録されたアプリケーション自体をランチャによって起動することが可能である「リップル起動のサポート」を参照)。


リップル起動のサポート

リップル起動とは、それ自体がロビーによって起動された別のアプリケーションからアプリケーションを実行することである。以下の説明では、ロビーによって実行されるプログラムをランチャと呼び、ランチャが起動するプログラムをアプリケーションと呼ぶ。

[C++]

アプリケーションでリップル起動をサポートするためには、IDirectPlayLobby3::RegisterApplication に DPAPPLICATIONDESC2 構造体を渡して、そのアプリケーションを登録する必要がある。この構造体には、ランチャの名前を保持する lpszAppLauncherName というメンバが含まれている。ランチャはアプリケーションと同じディレクトリに位置している必要がある。

ロビー クライアントが IDirectPlayLobby3::RunApplication を呼び出してアプリケーションを実行すると、DirectPlay はレジストリ内でランチャの名前を検索し、アプリケーションではなく、ランチャを実行する。アプリケーションを実行するのはランチャの役目である。

ランチャは、渡されたコマンドライン パラメータをアプリケーションにすべて渡す必要がある。アプリケーションは、理解できないコマンドライン パラメータを単純に無視する。

アプリケーションは、IDirectPlayLobby3::WaitForConnectionSettings を使用する前に、最低 1 回は必ず IDirectPlayLobby3::GetConnectionSettings を呼び出す (「動的ロビー接続のサポート」を参照)。

以下の例は、リップル起動のアプリケーションを登録する方法を示している。lpDPLobby3A は、IDirectPlayLobby3 インターフェイスを示している。

DPAPPLICATIONDESC2  dpad2;

dpad2.dwSize = sizeof (DPAPPLICATIONDESC2);
dpad2.dwFlags = 0;
dpad2.lpszApplicationNameA= "MyApp";
dpad2.guidApplication = {12345678-...};
dpad2.lpszFilenameA= "myapp.exe";
dpad2.lpszCommandLineA= "/lobbied";
dpad2.lpszPathA= "C:\\games";
dpad2.lpszCurrentDirectoryA= "C:\\games";
dpad2.lpszDescriptionA= "My Application";
dpad2.lpszDescriptionW= L"My Application";
dpad2.lpszAppLauncherNameA= "launcher.exe";

HRESULT hr = lpDPLobby3A->RegisterApplication(0, &dpad2);

以下の例は、Duel サンプルを起動する完全なコンソール アプリケーションである。

#include <windows.h>
#include "stdio.h"

int main(int argc, char* argv[])
{
  PROCESS_INFORMATION ProcInfo;
  STARTUPINFO StartupInfo;
  BOOL bCreated;

  LPTSTR lpCommandLine;

  printf("Launcher application\n");

  lpCommandLine = GetCommandLineA();

  // EXE 名をコマンド ラインから取り除き、
  // 残りをリップル起動アプリケーションに渡す。

  while(*lpCommandLine && *lpCommandLine!= ' ') lpCommandLine++;

  printf("passing command line: %s\n",lpCommandLine);

  memset(&StartupInfo,0,sizeof(StartupInfo));
  StartupInfo.cb = sizeof(StartupInfo);

  bCreated=CreateProcessA(
    "duel.exe",
    lpCommandLine,
    NULL,
    NULL,
    TRUE,
    0,
    NULL,
    NULL,
    &StartupInfo,
    &ProcInfo);

  if(bCreated){
    printf("Waiting for application to exit\n");
    WaitForSingleObject(ProcInfo.hThread, INFINITE);
  } else {
    printf("Failed to create process\n");
  }

  printf("launcher application has left the building...\n");

  return 0;
}
[Visual Basic]

アプリケーションでリップル起動をサポートするためには、DirectPlayLobby3.RegisterApplication に DPAPPLICATIONDESC2 型を渡して、そのアプリケーションを登録する必要がある。この型には、ランチャの名前を保持する strAppLauncherName というメンバが含まれている。ランチャはアプリケーションと同じディレクトリに位置している必要がある。

ロビー クライアントが DirectPlayLobby3.RunApplication を呼び出してアプリケーションを実行すると、DirectPlay はレジストリ内でランチャの名前を検索し、アプリケーションではなく、ランチャを実行する。アプリケーションを実行するのはランチャの役目である。

ランチャは、渡されたコマンドライン パラメータをアプリケーションにすべて渡す必要がある。アプリケーションは、理解できないコマンドライン パラメータを単純に無視する。

アプリケーションは、DirectPlayLobby3.WaitForConnectionSettings を使用する前に、最低 1 回は必ず DirectPlayLobby3.GetConnectionSettings を呼び出す (「動的ロビー接続のサポート」を参照)。

以下の例は、リップル起動のアプリケーションを登録する方法を示している。DPLobby3 は、DirectPlayLobby3 オブジェクトである。

Dim dpad2 As DPAPPLICATIONDESC2

With dpad2
  .lFlags = 0
  .strAppLauncherName= "launcher.exe"
  .strApplicationName= "MyApp"
  .strCommandLine= "/lobbied"
  .strCurrentDirectory= "C:\games"
  .strDescription= "My Application"
  .strFilename= "myapp.exe"
  .strGuid = "{AC330441-9B71-11D2-9AAB-0020781461AC}"
  .strPath= "C:\games"
End With

Call DPLobby3.RegisterApplication(dpad2)


動的ロビー接続のサポート

外部ロビー起動の欠点は、アプリケーションのインスタンスが既に実行中の場合でも、ロビー サーバーがロビー クライアントに対して常に新しいインスタンスを起動するように指示することである。動的ロビー接続をサポートすれば、冗長的な起動を避けることができる。

ここでの説明は、アプリケーションが既に実行中であり、接続設定を返すロビー サーバーへの接続が確立されていることを前提とする。

[C++]
  1. スタートアップ時に、CoCreateInstance 関数を使用して IDirectPlayLobby3 インターフェイスを作成する。
  2. ユーザーに、手動接続を確立させるのではなく、"ロビー接続をお待ちください" またはそのエフェクトを示す語を選択させる。その選択が実行された場合に限り、以下のステップを実行する (実装例については、「Duel サンプル」を参照)。
  3. IDirectPlayLobby3::WaitForConnectionSettings を呼び出して、アプリケーションを待機モードにする。このとき、実行は中断されない。アプリケーションがアクティブであり、接続を待機しているということが DirectPlay に伝えられるだけである。したがって、ロビー クライアントが DirectPlayLobby3.RunApplication を呼び出しても、別のインスタンスは起動されない。
  4. IDirectPlayLobby3::ReceiveLobbyMessage を使用して、送信されるロビー メッセージを待機する。待機するメッセージ タイプは DPLSYS_NEWCONNECTIONSETTINGS システム メッセージである。ユーザーがキャンセルした場合は、WaitForConnectionSettings をもう一度呼び出して待機モードをキャンセルすることができる。
  5. システム メッセージを受信したら、ロビーによって渡された接続情報を調べ、必要に応じて設定を変更する。IDirectPlayLobby3::GetConnectionSettings メソッドは、接続設定を含む DPLCONNECTION 構造体を返す。新しく設定を行うには、IDirectPlayLobby3::SetConnectionSettings を使用する。
  6. IDirectPlayLobby3::ConnectEx を呼び出してアプリケーション セッションを作成するか、またはそれに接続する (アプリケーションは DPLCONNECTION.dwFlags を調べて、セッションを作成するか、またはセッションに参加するかを判断する)。
  7. ステップ 5 で取得した DPLCONNECTION 構造体によって提供される名前情報を使用して、プレーヤーを作成する。
[Visual Basic]
  1. スタートアップ時に、DirectX7.DirectPlayLobbyCreate メソッドを使用して DirectPlayLobby3 オブジェクトを作成する。
  2. ユーザーに、手動接続を確立させるのではなく、"ロビー接続をお待ちください" またはそのエフェクトを示す語を選択させる。その選択が実行された場合に限り、以下のステップを実行する
  3. DirectPlayLobby3.WaitForConnectionSettings を呼び出して、アプリケーションを待機モードにする。このとき、実行は中断されない。アプリケーションがアクティブであり、接続を待機しているということが DirectPlay に伝えられるだけである。したがって、ロビー クライアントが DirectPlayLobby3.RunApplication を呼び出しても、別のインスタンスは起動されない。
  4. DirectPlayLobby3.ReceiveLobbyMessage を使用して、送信されるロビー メッセージを待機する。待機するメッセージ タイプは、DPLSYS_NEWCONNECTIONSETTINGS システム メッセージである。ユーザーがキャンセルした場合は、WaitForConnectionSettings をもう一度呼び出して待機モードをキャンセルすることができる。
  5. システム メッセージを受信したら、ロビーによって渡された接続情報を調べ、必要に応じて設定を変更する。DirectPlayLobby3.GetConnectionSettings メソッドは、接続設定を含む DirectPlayLobbyConnection オブジェクトを返す。新しく設定を行うには、DirectPlayLobby3.SetConnectionSettings. を使用する。
  6. DirectPlayLobby3.Connect を呼び出してアプリケーション セッションを作成するか、またはそれに接続する (アプリケーションは、DirectPlayLobbyConnection.GetFlags によって返される値を調べて、セッションを作成するか、またはセッションに参加するかを判断する)。
  7. ステップ 5 で取得した DirectPlayLobbyConnection オブジェクトによって提供される名前情報を使用して、プレーヤーを作成する。


ロビーとの関係の維持

アプリケーションでは、ロビーによって起動されたり、ロビーに動的に接続した後で、ロビーとの情報の交換を継続したい場合がある。たとえば、ロビー サーバーでは、現在ゲームに参加しているプレーヤーの人数やそのスコアをロビー内のほかのユーザーに表示するために、これらの情報を追跡したい場合がある。同様に、プレーヤーやゲームの構成がアプリケーション自体ではなく、ロビーで設定されている場合には、それらのデータを受信したい場合もある。

[C++]

ロビーとメッセージを交換するには、IDirectPlayLobby3::SendLobbyMessage メソッドと IDirectPlayLobby3::ReceiveLobbyMessage メソッドを使用する。

情報は、プロパティを設定することにより、ロビーに送信される。アプリケーションは、DPLMSG_SETPROPERTY メッセージ構造体を作成してデータを代入し、SendLobbyMessage メソッドを使用してそれをロビーに送信する必要がある。各プロパティは、データの個別のタイプを識別する。アプリケーション開発者は、デザイン時に、設定可能な各プロパティに GUID を割り当てる。ロビー オペレータは、この GUID のリストと、各プロパティの説明およびデータ構造体をアプリケーション開発者から取得する必要がある。

アプリケーションは、プロパティが正しく設定されたことの確認を求めることができる。それには、DPLMSG_SETPROPERTY.dwRequestID にゼロ以外の値を指定する。すると、ロビーは DPLMSG_SETPROPERTYRESPONSE メッセージを返す。

ロビーから情報を取得するときも、同じようにプロパティを要求する。アプリケーションは、DPLMSG_GETPROPERTY 構造体にデータを代入し、SendLobbyMessage メソッドを使用してそれをロビーに送信する。ロビーは、要求されたプロパティ データを含む DPLMSG_GETPROPERTYRESPONSE 構造体を返す。先ほどと同じく、アプリケーション開発者は各プロパティに対する GUID を作成し、それらをロビー開発者と共有する。

すべてのロビーがこれらの標準のロビー メッセージをサポートできるわけではない。アプリケーションでは、起動元のロビーが標準のロビー メッセージをサポートしているかどうかを判断することができる。それには、DPLMSG_GETPROPERTY メッセージを送信し、DPLPROPERTY_MessagesSupported プロパティを要求する。

詳細については、「DirectPlay 定義済みプロパティ」を参照すること。

[Visual Basic]

ロビーとメッセージを交換するには、DirectPlayLobby3.SendLobbyMessage メソッドと DirectPlayLobby3.ReceiveLobbyMessage メソッドを使用する。

情報は、プロパティを設定することにより、ロビーに送信される。アプリケーションは、DirectPlayMessage.WriteLong メソッドと DirectPlayMessage.WriteGuid メソッドを使用し、DPLMSG_SETPROPERTY C 構造体と同じ順序でデータを含む DirectPlayMessage オブジェクトを作成する必要がある。

ロビーから情報を取得するときも、同じようにプロパティを要求する。アプリケーションは、DPLMSG_GETPROPERTY C 構造体に含まれているデータと同じデータを含むメッセージを作成し、それをロビーに送信する。ロビーは、要求されたプロパティ データを含む DPLMSG_GETPROPERTYRESPONSE メッセージを返す。データを取得するには、DirectPlayMessage.ReadLong メソッドと DirectPlayMessage.ReadGuid メソッドを使用する。

詳細については、このトピックの C++ の記述を参照すること。


DirectPlay メッセージ

アプリケーションでプレーヤーを作成すると、そのプレーヤーはセッションに参加しているほかのプレーヤーとプレーヤー メッセージをやり取りすることができる。さらに、DirectPlay 自体がシステム メッセージを作成し、プレーヤーにイベントを通知する。このイベントには、プレーヤーのセッションへの参加や退出などが含まれる。

プレーヤー メッセージは、個別のプレーヤー、すべてのプレーヤー、グループとして定義されたプレーヤーのサブセットのいずれかに送信することができ、送信側プレーヤーの ID によって識別される。システム メッセージは、セッションに参加しているすべてのプレーヤーに送信され、定数 DPID_SYSMSG と同じ値の送信側 ID を保持する。

アプリケーションが受信したメッセージは、すべて受信キューに入れられる。アプリケーションは、各メッセージをキューから取り出し、それに応じて動作する必要がある。アプリケーションは、受信キューをポーリングしてメッセージを調べるか、新しいメッセージが到着したという通知に対する同期イベントに依存することができる。

以下のトピックでは、DirectPlay でメッセージを使用する方法について詳しく説明する。

  • メッセージの受信
  • 同期化
  • プレーヤー メッセージの使用
  • システム メッセージの使用
  • 非同期メッセージング
  • ロビー メッセージの使用


メッセージの受信

[C++]

アプリケーションは、IDirectPlay4::Receive を呼び出して、キューの中の次のメッセージを取り出す。

2 人以上のローカル プレーヤーがいる場合 (つまり、アプリケーションの当該のインスタンスによって、2 人以上のプレーヤーが作成されている場合) は、メッセージの送信側のプレーヤーの ID を Receive メソッドの lpidTo パラメータに渡し、DPRECEIVE_TOPLAYER フラグを設定する必要がある。

メッセージ データを取り出すには、最初に適切な量のメモリを割り当てる必要がある。必要なバッファのサイズを判断するには、最初に lpData パラメータに NULL を設定してメソッドを呼び出すか、または任意のサイズの既存のバッファへのポインタを渡して、*lpdwDataSize に現在の長さを設定する。待機中のメッセージがあるのに、lpData が NULL であるか、またはバッファのサイズが小さすぎる場合、メソッドは DPERR_BUFFERTOOSMALL で失敗し、必要なメモリ量が *lpdwDataSize に返される。その場合は、割り当てを再度実行してメソッドを再試行する。

メソッドが成功し、バッファにメッセージ データが入れられると、そのメッセージがシステム メッセージの場合は、*lpidFrom が DPID_SYSMSG に等しくなる。その場合は、「システム メッセージの使用」のステップに従う。そうでない場合は、「プレーヤー メッセージの使用」のステップに従う。

この処理の例については、Duel サンプルの ReceiveMessages 関数を参照すること。

[Visual Basic]

DirectPlay4.Receive メソッドは、キューの中の次のメッセージを取り出し、メッセージ データを含む DirectPlayMessage オブジェクトを返す。さらに、このメソッドは送信側のプレーヤーの ID (システム メッセージの場合は DPID_SYSMSG) と受信側のプレーヤーの ID を返す。これらは、メソッドに渡された変数に返される。

2 人以上のローカル プレーヤーがいる場合 (つまり、アプリケーションの当該のインスタンスによって、2 人以上のプレーヤーが作成されている場合) は、メッセージの送信側のプレーヤーの ID を Receive メソッドの toPlayerId パラメータに渡し、DPRECEIVE_TOPLAYER フラグを設定する必要がある。

以下のサンプル関数は、待機中のメッセージをすべて取り出す。

' gObjDPlay は DirectPlay4 オブジェクト。
' gMyPlayerID はプレーヤーの ID。

Sub ReceiveMessages
    Dim MsgCount as Long
    Dim MsgType as Long
    Dim FromPlayerID As Long
    Dim ToPlayerID As Long
    Dim dpMsg as DirectPlayMessage

    MsgCount = gObjDPlay.GetMessageCount(gMyPlayerID)
    For X% = 1 to MsgCount
        Set dpMsg = gObjDPlay.Receive(FromPlayerID, _
            ToPlayerID, DPRECEIVE_ALL)
        If FromPlayerID = DPID_SYSMSG Then
            MsgType = dpMsg.ReadLong()
           ' ここでシステム メッセージを処理する。
        Else
           ' ここでプレーヤー メッセージを処理する。
        End If
    Next X
End Sub

受信したメッセージの処理方法の詳細については、次のトピックを参照すること。

  • システム メッセージの使用
  • プレーヤー メッセージの使用
  • ロビー メッセージの使用


同期化

[C++]

アプリケーションで DirectPlay のメッセージを取得するために使用できる方法は 2 つある。1 つは、アプリケーションのメイン ループで受信キューをチェックする方法である。これは通常、アプリケーションがシングルスレッドであることを意味する。

もう 1 つは、アプリケーションで独立したスレッドを確保し、メッセージを待機してそれを処理する方法である。この場合、アプリケーションはプレーヤーを作成するときに、非 NULL の自動リセット同期イベント (Win32® の CreateEvent 関数を参照) へのハンドルを提供する必要がある。DirectPlay は、作成されたプレーヤーに対するメッセージが到着したときに、このイベントを設定する。

続いて、メッセージ処理スレッドは Win32 の WaitForSingleObject 関数を使用して、イベントが設定されるのを待機する。DPERR_NOMESSAGES が返され、メッセージ キューにメッセージが残っていないことが示されるまで、IDirectPlay4::Receive を呼び出し続ける。

アプリケーションで複数のローカル プレーヤーを作成する場合は、すべてのプレーヤーが同じイベントを共有するか、または各プレーヤーが独立したイベントを確保することができる。

[Visual Basic]

アプリケーションで DirectPlay のメッセージを取得するために使用できる方法は 2 つある。1 つは、アプリケーションのメイン ループで受信キューをチェックする方法である。Visual Basic では、以下のサンプル コードに示すように、Sub Main でメッセージをポーリングすることができる。

Public Sub Main()

    Do While DoEvents()  ' イベント処理を許可する。
        ReceiveMessages  ' 「メッセージの受信」を参照。
    Loop
End Sub

もう 1 つは、プレーヤーがメッセージを受信するたびに合図されるイベントを作成する方法である。この方法を利用するには、フォームまたはクラス モジュールに DirectXEvent クラスを実装し、DirectXEvent.DXCallBack メソッドを用意する必要がある。続いて、DirectX7.CreateEvent メソッドに DirectXEvent オブジェクト (通常は、DirectXEvent クラスを実装するフォーム) を渡してイベント ハンドルを取得し、そのハンドルを DirectPlay4.CreatePlayer メソッドの receiveEvent パラメータに渡す。すると、メッセージがそのプレーヤーの受信キューに入れられるたびに DXCallBack メソッドが自動的に呼び出される。アプリケーションは、このプロシージャ内でキューから任意の保留メッセージを取り出すことができる。

アプリケーションで複数のローカル プレーヤーを作成する場合は、すべてのプレーヤーが同じイベントを共有するか、または各プレーヤーが独立したイベントを確保することができる。


プレーヤー メッセージの使用

[C++]

プレーヤー メッセージは、IDirectPlay4::Send または IDirectPlay4::SendEx を使用して送信することができる。SendEx によって送信されるメッセージには、優先順位を割り当てることができる。優先順位の高いメッセージが最初に送信される。優先順位は、メッセージの受信順位には影響を与えない。

プレーヤー メッセージ内のデータの編成は、アプリケーションによってのみ決められる。慣例では、最初の要素は、アプリケーションで定義されるメッセージ識別子である。

通常、C++ アプリケーションは、IDirectPlay4::Receive を使用してメッセージ バッファを取得し、それを DPMSG_GENERIC にキャストし、メッセージが DPID_SYSMSG から送信されたものかどうかを確認する。DPID_SYSMSG から送信されたものではない場合、アプリケーションはデータをアプリケーションで定義された汎用タイプにキャストし、その構造体内のメッセージ タイプを確認し、そのメッセージに適したアプリケーション定義タイプに再度キャストする。例として、「Duel サンプル」を参照すること。ここでは、ReceiveMessages 関数と DoApplicationMessage 関数を使用している。

[Visual Basic]

プレーヤー メッセージは、DirectPlay4.Send または DirectPlay4.SendEx. を使用して送信することができる。SendEx によって送信されるメッセージには、優先順位を割り当てることができる。優先順位の高いメッセージが最初に送信される。優先順位は、メッセージの受信順位には影響を与えない。

プレーヤー メッセージ内のデータの編成は、アプリケーションによってのみ決められる。慣例では、最初の要素は、アプリケーションで定義されるメッセージ識別子である。

メッセージ データは、DirectPlayMessage オブジェクトによって表される。送信側のアプリケーションは、DirectPlay4.CreateMessage メソッドを使用して、このオブジェクトを取得する。

プレーヤー メッセージのデータを構築する方法は 2 つある。1 つは、DirectPlayMessage のさまざまな記述用メソッドを使用して、データの要素を 1 つずつ記述する方法である。各要素を記述するごとに、内部の記述ポインタが進む。もう 1 つは、DirectPlayMessage.SetMessageData にユーザー定義型を渡す方法である。ほとんどのアプリケーションでは、最初の方法を使用する。これは、SetMessageData を使用するには、メソッドに渡されるデータの正確なサイズを把握している必要があるからである。このサイズは、常に簡単に把握できるとは限らない。

注 : メッセージ データを設定するためのこれら 2 つの方法を組み合わせて使用することはできない。たとえば、DirectPlayMessage.WriteLong を使用してメッセージ タイプを記述してから、SetMessageData を使用して追加データを記述することはできない。SetMessageData は、メッセージの中身全体を設定する。

データをメッセージから取得するには、DirectPlayMessage の対応する読み取り用メソッドを使用するか、または DirectPlayMessage.GetMessageData を使用する。読み取りメソッドを使用するとき、アプリケーションはデータ要素を記述された順序と同じ順序で読み取る必要がある。GetMessageData は、データが SetMessageData によって設定された場合にのみ使用する。


システム メッセージの使用

[C++]

IDirectPlay4::Receive メソッドによって DPID_SYSMSG というプレーヤー ID から返されるメッセージは、システム メッセージである。すべてのシステム メッセージは、dwType の値によって指定される識別子から始まる。IDirectPlay4::Receive メソッドによって返されるバッファを汎用メッセージ (DPMSG_GENERIC) にキャストし、dwType 要素を調べることができる。この要素は、DPSYS_ という接頭辞の付くメッセージ タイプ識別子のいずれかに等しい値を持つ。アプリケーションでシステム メッセージの種類を判断したら、バッファを適切な構造体 (接頭辞 DPMSG_ で始まる) にキャストして、データを読み取る。

アプリケーションでは、以下のシステム メッセージを処理できるようにしておく必要がある。

dwType の値 | メッセージ構造体 | 原因
DPSYS _ADDGROUPTOGROUP | DPMSG_ADDGROUPTOGROUP | 既存のグループに既存のグループが追加された。
DPSYS _ADDPLAYERTOGROUP | DPMSG_ADDPLAYERTOGROUP | 既存のグループに既存のプレーヤーが追加された。
DPSYS_CHAT | DPMSG_CHAT | チャット メッセージが届いた。
DPSYS _CREATEPLAYERORGROUP | DPMSG_CREATEPLAYERORGROUP | 新しいプレーヤーまたはグループが作成された。
DPSYS _DELETEGROUPFROMGROUP | DPMSG_DELETEGROUPFROMGROUP | グループがグループから削除された。
DPSYS _DELETEPLAYERFROMGROUP | DPMSG_DELETEPLAYERFROMGROUP | プレーヤーがグループから削除された。
DPSYS _DESTROYPLAYERORGROUP | DPMSG_DESTROYPLAYERORGROUP | 既存のプレーヤーまたはグループが破棄された。
DPSYS_HOST | DPMSG_HOST | 現在のホストがセッションを離れ、このアプリケーションが新しいホストになった。
DPSYS _SECUREMESSAGE | DPMSG_SECUREMESSAGE | デジタル署名または暗号化が施されたメッセージが届いた。
DPSYS _SENDCOMPLETE | DPMSG_SENDCOMPLETE | 非同期送信が完了した。
DPSYS _SESSIONLOST | DPMSG_SESSIONLOST | セッションの接続が失われた。
DPSYS _SETGROUPOWNER | DPMSG_SETGROUPOWNER | グループの所有者が変更された。
DPSYS _SETPLAYERORGROUPDATA | DPMSG_SETPLAYERORGROUPDATA | プレーヤーまたはグループのデータが変更された。
DPSYS _SETPLAYERORGROUPNAME | DPMSG_SETPLAYERORGROUPNAME | プレーヤーまたはグループの名前が変更された。
DPSYS _SETSESSIONDESC | DPMSG_SETSESSIONDESC | セッション記述が変更された。
DPSYS _STARTSESSION | DPMSG_STARTSESSION | ロビー サーバーが、セッションを開始するように要求している。

[Visual Basic]

DirectPlay4.Receive メソッドによって返され、プレーヤー ID DPID_SYSMSG からのものであるとマークされているメッセージは、システム メッセージである。すべてのシステム メッセージは、Long という型識別子から始まる。

システム メッセージを解析するには、最初に DirectPlayMessage.ReadLong メソッドを使用して、その型識別子を取得する必要がある。次に、DirectPlayMessage のさまざまな読み取りメソッドを使用して、メッセージ データの要素を取り出す。要素は、メッセージ タイプに記載されているのと同じ順序で取り出す必要がある (「CONST_DPSYSMSGTYPES」を参照)。

プレーヤー メッセージとシステム メッセージに使用される標準の読み取りメソッドに加えて、DirectPlay はシステム メッセージを解析するための以下のメソッドを提供する。

  • DirectPlayMessage.MoveToSecureMessage
  • DirectPlayMessage.ReadSysMsgData
  • DirectPlayMessage.ReadSysChatString
  • DirectPlayMessage.ReadSysMsgConnection
  • DirectPlayMessage.ReadSysMsgSessionDesc

ReadSysChatString、ReadSysMsgConnection、および ReadSysMsgSessionDesc は、読み取りポインタの位置に関係なく呼び出すことができる。また、これらのメソッドを呼び出しても、読み取りポインタは進まない。一方、ReadSysMsgData を呼び出せるのは、メッセージ内の前のデータがすべて取り出されている場合だけである。また、このメソッドを呼び出すと、読み出しポインタが進む。これは、最初の 3 つのメソッドは使用するデータの基盤となるメッセージ構造体内での場所を常に把握しているが、ReadSysMsgData を使用すると、異なるメッセージ タイプの異なる場所からデータを取り出すことができるからである。


非同期メッセージング

メッセージを非同期に送信できれば、アプリケーションの通信コードが各メッセージを転送する間に制御を独占するのを避けることができる。これにより、送出するメッセージを管理するための負担を DirectPlay に転嫁し、なおかつアプリケーションでメッセージ キューを監視してメッセージをキャンセルすることが可能になる。

非同期メッセージング機能は、セッションで DirectPlay プロトコルを使用しているか、またはサービス プロバイダによってこの機能がサポートされている場合にのみ利用できる。たとえば、TCP/IP サービス プロバイダは、コンピュータが Windows Sockets 2.0 以降を使用している場合のみ、非同期メッセージをサポートする。

[C++]

DirectPlay プロトコルを使用していない場合は、セッションが確立した後に IDirectPlay4::GetCaps メソッドを使用して DPCAPS_ASYNCSUPPORTED フラグを調べ、非同期メッセージがサポートされているかどうかを判断することが重要である。

非同期メッセージを送信するには、IDirectPlay4::SendEx メソッドを使用する。このとき、dwFlags パラメータに DPSEND_ASYNC フラグを設定する。SendEx は、直ちに戻る。後ほど、アプリケーションは送信したメッセージの結果を示す状態を含む DPMSG_SENDCOMPLETE システム メッセージを受信する。この通知が実行されないようにするには、メッセージを送信するときに DPSEND_NOSENDCOMPLETEMSG フラグを設定する。アプリケーションは、SendEx によって返される dwMsgID パラメータを使用して、個々のメッセージを追跡することができる。この ID は、個々のメッセージをキャンセルしたり、完了通知メッセージと比較する際に使用することができる。

SendEx を使用すると、タイムアウト値と優先順位をサポートするセッション内のメッセージに、それらの値を割り当てることができる。また、IDirectPlay4::CancelMessage メソッドまたは IDirectPlay4::CancelPriority メソッドを使用して、送信キュー内のメッセージをキャンセルすることもできる。タイムアウト、優先順位、およびキャンセルの機能には、DirectPlay プロトコルまたはサービス プロバイダによるサポートが必要である。これらは、IDirectPlay4::GetCaps メソッドによって判断される。

[Visual Basic]

DirectPlay プロトコルが使用されていない場合は、セッションが確立した後で DirectPlay4.GetCaps メソッドを使用して DPCAPS_ASYNCSUPPORTED フラグをチェックし、非同期メッセージがサポートされているかどうかを確認することが重要である。

非同期メッセージを送信するには、DirectPlay4.SendEx メソッドを使用する。このとき、flags パラメータに DPSEND_ASYNC フラグを設定する。SendEx は直ちに戻る。後ほど、アプリケーションは送信したメッセージの結果を示す状態を含む DPMSG_SENDCOMPLETE システム メッセージを受信する。この通知が実行されないようにするには、メッセージを送信するときに DPSEND_NOSENDCOMPLETEMSG フラグを設定する。アプリケーションは、SendEx によって返される dwMsgID パラメータを使用して、個々のメッセージを追跡することができる。この ID は、個々のメッセージをキャンセルしたり、完了通知メッセージと比較する際に使用することができる。

SendEx を使用すると、タイムアウト値と優先順位をサポートするセッション内のメッセージに、それらの値を割り当てることができる。また、DirectPlay4.CancelMessage メソッドまたは DirectPlay4.CancelPriority メソッドを使用して、送信キュー内のメッセージをキャンセルすることもできる。タイムアウト、優先順位、およびキャンセルの機能には、DirectPlay プロトコルまたはサービス プロバイダによるサポートが必要である。これらは、DirectPlay4.GetCaps メソッドによって判断される。

非同期メッセージと同期メッセージを組み合わせて使用する場合は、十分な注意が必要である。キュー内の非同期メッセージに続いて同期メッセージが送信されると、その同期メッセージが完了するまで、制御がブロックされる。

タイムアウトと優先順位がサポートされている場合は、これらを同期メッセージで使用できる。IDによるメッセージの追跡とキャンセルは、同期メッセージには適用されない。

非同期メッセージングは、帯域幅を拡大したり、待ち時間を軽減したりするものではない。

非同期メッセージを効果的に使用する方法の詳細については、「DirectPlay プロトコルを使用した非同期ネットワーキング」を参照すること。


ロビー メッセージの使用

ロビー メッセージは、2 つのカテゴリに分けることができる。つまり、DirectPlay によって定義されるメッセージと、アプリケーションによって定義されるメッセージである。

DirectPlay 定義のメッセージは、DirectPlay によって自動的に生成され、アプリケーションの変更を通知するためにロビーに送信されるシステム メッセージか、アプリケーションとロビーの間でやり取りされる標準のメッセージ タイプのいずれかである。

アプリケーション定義のメッセージに対する標準メッセージの利点は、受信側が常に標準メッセージを解釈できるということである。ロビー クライアントは、必ずしもアプリケーションからのカスタム メッセージを処理できるとは限らない。また、アプリケーションもロビー クライアントからのカスタム メッセージを処理できない場合がある。

[C++]

ロビー メッセージを受信するには、IDirectPlayLobby3::ReceiveLobbyMessage メソッドを使用する。メッセージのカテゴリは、lpdwMessageFlags パラメータを調べることによって判断することができる。DPLMSG_SYSTEM または DPLMSG_STANDARD のどちらでもない場合、メッセージはアプリケーション定義である。

ロビーは、すべての標準メッセージを処理できる必要がある。アプリケーションで DPLMSG_GETPROPERTY メッセージを使用する場合は、DPLMSG_GETPROPERTYRESPONSE メッセージを処理できる必要がある (「ロビーとの関係の維持」を参照)。

DirectPlay 定義のメッセージは、すべてメッセージ タイプを示す DWORD 値から始まる。ReceiveLobbyMessage を使用してメッセージを取得したら、*lpData を DPLMSG_GENERIC 構造体にキャストして、その構造体の dwType メンバを調べる。続いて、*lpData を適切なメッセージ構造体にキャストし、以降の処理に備える。

以下は、標準メッセージに対する DPLMSG_GENERIC.dwType の値と、それぞれの値の構造体および原因を示している。

dwType の値 | メッセージ構造体 | 原因
DPLSYS _APPTERMINATED | DPLMSG_SYSTEMMESSAGE | アプリケーションが終了した。
DPLSYS _CONNECTIONSETTINGSREAD | DPLMSG_SYSTEMMESSAGE | アプリケーションが接続設定を読み取った。
DPLSYS _DPLAYCONNECTFAILED | DPLMSG_SYSTEMMESSAGE | アプリケーションが DirectPlay セッションへの接続に失敗した。
DPLSYS _DPLAYCONNECTSUCCEEDED | DPLMSG_SYSTEMMESSAGE | アプリケーションが DirectPlay セッションへの接続に成功した。
DPLSYS _GETPROPERTY | DPLMSG_GETPROPERTY | アプリケーションがロビーのプロパティを要求している。「ロビーとの関係の維持」を参照。
DPLSYS _GETPROPERTYRESPONSE | DPLMSG_GETPROPERTYRESPONSE | ロビーが DPLMSG_GETPROPERTY メッセージに応答している。「ロビーとの関係の維持」を参照。
DPLSYS _NEWCONNECTIONSETTINGS | DPLMSG_SYSTEMMESSAGE | ロビー クライアントが RunApplication を呼び出したときに、待機中のアプリケーションが見つかった。「動的ロビー接続のサポート」を参照。
DPLSYS _NEWSESSIONHOST | DPLMSG_NEWSESSIONHOST | アプリケーション セッションの所有者が新しくなった。
DPLSYS _SETPROPERTY | DPLMSG_SETPROPERTY | アプリケーションがロビーのプロパティを設定している。「ロビーとの関係の維持」を参照。
DPLSYS _SETPROPERTYRESPONSE | DPLMSG_SETPROPERTYRESPONSE | ロビーが DPLMSG_SETPROPERTY メッセージに応答している。「ロビーとの関係の維持」を参照。

[Visual Basic]

ロビー メッセージを受信するには、DirectPlayLobby3.ReceiveLobbyMessage メソッドを使用する。メッセージのカテゴリは、messageFlags パラメータに返される値によって判断することができる。DPLMSG_SYSTEM または DPLMSG_STANDARD のどちらでもない場合、メッセージはアプリケーション定義である。

ロビーは、すべての標準メッセージを処理できる必要がある。アプリケーションで DPLSYS_GETPROPERTY メッセージを使用する場合は、DPLSYS_GETPROPERTYRESPONSE メッセージを処理できなければならない (「ロビーとの関係の維持」を参照)。

DirectPlay 定義のメッセージはすべて、メッセージ タイプを識別する CONST_DPSYSMSGTYPES 列挙型の値から始まる。この値を取得するには、DirectPlayMessage.ReadLong を使用する。

以下は、メッセージ タイプと、それぞれの値に関連するメッセージの原因を示している。

メッセージ タイプ | 原因
DPLSYS _APPTERMINATED | アプリケーションが終了した。
DPLSYS _CONNECTIONSETTINGSREAD | アプリケーションが接続設定を読み取った。
DPLSYS _DPLAYCONNECTFAILED | アプリケーションが DirectPlay セッションへの接続に失敗した。
DPLSYS _DPLAYCONNECTSUCCEEDED | アプリケーションが DirectPlay セッションへの接続に成功した。
DPLSYS _GETPROPERTY | アプリケーションがロビーのプロパティを要求している。「ロビーとの関係の維持」を参照。
DPLSYS _GETPROPERTYRESPONSE | ロビーが DPLMSG_GETPROPERTY メッセージに応答している。「ロビーとの関係の維持」を参照。
DPLSYS _NEWCONNECTIONSETTINGS | ロビー クライアントが RunApplication を呼び出したときに、待機中のアプリケーションが見つかった。「動的ロビー接続のサポート」を参照。
DPLSYS _NEWSESSIONHOST | アプリケーション セッションの所有者が新しくなった。
DPLSYS _SETPROPERTY | アプリケーションがロビーのプロパティを設定している。「ロビーとの関係の維持」を参照。
DPLSYS _SETPROPERTYRESPONSE | ロビーが DPLMSG_SETPROPERTY メッセージに応答している。「ロビーとの関係の維持」を参照。


DirectPlay アドレス

DirectPlay アドレスは、DirectPlay がロビー サーバー、アプリケーション、DirectPlay、およびサービス プロバイダの間でアドレス情報を渡すために使用するデータ書式である。このアドレスは、可変長データと GUID で構成され、DirectPlay が必要とするアドレス情報をすべて保持する。例として、サーバーのネットワーク アドレス、プレーヤーのネットワーク アドレス、セッションのネットワーク アドレス、ダイヤルアップ接続のモデムおよび電話番号などがある。

DirectPlay を使用するために、DirectPlay アドレスを理解する必要はない。DirectPlay アドレスについて学ぶ必要があるのは、以下のいずれかを実行する場合だけである。

  • 標準のサービス プロバイダのダイアログ ボックスを置き換える。この場合は、使用するサービス プロバイダを指定し、そのサービス プロバイダが接続を確立するために必要とする情報をすべて含む DirectPlay アドレスを作成する。そのアドレスを使用して、接続を初期化する。
  • 外部の DirectPlay アプリケーションを起動するロビー クライアントを記述する。このロビー クライアントは、使用するサービス プロバイダを指定し、そのサービス プロバイダが接続を確立してセッションのクライアントに接続するために必要とする情報をすべて含む DirectPlay アドレスを作成する必要がある。この情報を、アプリケーションの起動時に渡す。

詳細情報については、次のトピックを参照すること。

  • サービス プロバイダ ダイアログの置換
  • DirectPlay アドレスのデータ型
  • DirectPlay アドレスの使用例


サービス プロバイダ ダイアログの置換

DirectPlay が接続を列挙するときに取得する DirectPlay アドレスは、ユーザーが選択可能な登録済みの DirectPlay プロバイダに過ぎず、接続を確立するために必要な情報をすべて含んでいる必要はない。これらのアドレスのいずれかを使用してセッションを列挙すると、サービス プロバイダがユーザーに追加情報を問い合わせる場合がある。

たとえば、ユーザーがサービス プロバイダのリストから "Modem Connection for DirectPlay" を選択し、アプリケーションがその接続を初期化してセッションの列挙を開始すると、モデムを選択して電話番号を入力するように要求するダイアログ ボックスが表示される。ユーザーがこのダイアログ ボックスをキャンセルすると、セッションを作成することはできるが、既存のセッションに参加することはできない。ユーザーがセッションの作成を選択すると、呼び出しに応答するためのモデムを選択および構成できる別のダイアログ ボックスが表示される。

[C++]

この動作が望ましくない場合もある。アプリケーションは、必要な接続情報 (ゲームをホストしている中央サイトの IP アドレスなど) を既に保持している場合や、独自のインターフェイスを介してユーザーから情報を取得する場合もある。これらの場合、アプリケーションは IDirectPlay4::InitializeConnection に完全な接続情報を渡して、サービス プロバイダが追加情報を要求しないようにすることができる。

DirectPlay アドレスを作成するには、IDirectPlayLobby3::CreateAddress メソッドまたは IDirectPlayLobby3::CreateCompoundAddress メソッドを呼び出す。CreateAddress は、単一の要素 (IP アドレスなど) を含んでいる単純なアドレスの場合に限り使用できる。CreateCompoundAddress を使用すると、モデムと電話番号の両方を含む電話アドレスなど、より複雑なアドレスを作成できる。DirectPlay で定義されている要素のタイプについては、「DirectPlay アドレスのデータ型」を参照すること。

[Visual Basic]

この動作が望ましくない場合もある。アプリケーションは、必要な接続情報 (ゲームをホストしている中央サイトの IP アドレスなど) を既に保持している場合や、独自のインターフェイスを介してユーザーから情報を取得する場合もある。これらの場合、アプリケーションは DirectPlay4.InitializeConnection に完全な接続情報を渡して、サービス プロバイダが追加情報を要求しないようにすることができる。

DirectPlayLobby3 クラスには、さまざまな種類の DirectPlayAddress オブジェクトを作成するための以下のようなメソッドがある。

  • CreateComPortAddress
  • CreateCustomAddress
  • CreateINetAddress
  • CreateLobbyProviderAddress
  • CreateModemAddress
  • CreateServiceProviderAddress


DirectPlay アドレスのデータ型

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic 用の DirectX では、DirectPlayAddress オブジェクトのデータ書式は、そのオブジェクトを作成するために使用された DirectPlayLobby3 によって決まる。

[C++]

以下は、IDirectPlayLobby3::CreateCompoundAddress を使用して作成された DirectPlay アドレスに含まれているデータ チャンク (DPCOMPOUNDADDRESSELEMENT) の標準のデータ型を示している。

GuidDataType | lpData
DPAID_ComPort | COM ポートのすべての設定を含む DPCOMPORTADDRESS 構造体。シリアル接続サービス プロバイダは、この情報を使用してシリアル ポートを構成する。
DPAID_INet | IP アドレス ("192.168.0.1" など) またはドメイン名 ("microsoft.com" など) を含む、Null で終わる ANSI 文字列。dwDataSize にはターミネータが含まれている必要がある。 空のアドレスが提供されると、インターネット TCP/IP 接続サービス プロバイダは、この情報を使用して指定されたネットワーク アドレス上のセッションを列挙するか、サブネット上でブロードキャストを実行する。空のアドレスは、ANSI のターミネータ (0x00) だけを含む、長さが 1 バイトの文字列である。
DPAID_INetW | IP アドレスまたはドメイン名を含む、Null で終わる ANSI 文字列。dwDataSize にはターミネータが含まれている必要がある。 空のアドレスが提供されると、インターネット TCP/IP 接続サービス プロバイダは、この情報を使用して指定されたネットワーク アドレス上のセッションを列挙するか、サブネット上でブロードキャストを実行する。空のアドレスは、Unicode のターミネータ (0x0000) だけを含む、長さが 2 バイトの文字列である。
DPAID_INetPort | 使用する特定のポート番号を含む整数。TCP/IP のポートの選択に関する項目を参照。この DirectPlay アドレスの使い方については、「ファイアウォールのサポート」を参照。
DPAID _LobbyProvider | この DirectPlay アドレスが適用されるロビー プロバイダを指定する GUID。
DPAID_Modem | 使用するモデムを指定する、NULL で終わる可変長の ANSI 文字列。dwDataSize にはターミネータが含まれている必要がある。モデム サービス プロバイダは、ユーザーに使用するモデムをたずねるダイアログ ボックスを表示せずに、このモデムを使用する。
DPAID_ModemW | 使用するモデムを指定する、NULL で終わる可変長の Unicode 文字列。dwDataSize にはターミネータが含まれている必要がある。モデム サービス プロバイダは、ユーザーに使用するモデムをたずねるダイアログ ボックスを表示せずに、このモデムを使用する。利用可能なモデムを判断するには、IDirectPlay4::GetPlayerAddress メソッドを使用する。
DPAID_Phone | 電話番号を含む、NULL で終わる可変長の ANSI 文字列。dwDataSize にはターミネータが含まれている必要がある。モデム サービス プロバイダは、IDirectPlay4::EnumSessions メソッドでこの電話番号に電話をかける。モデムが指定されていない場合は、最初のモデムが使用される。
DPAID_PhoneW | 電話番号を含む、NULL で終わる可変長の Unicode 文字列 (LPWSTR)。dwDataSize にはターミネータが含まれている必要がある。モデム サービス プロバイダは、IDirectPlay4::EnumSessions メソッドでこの電話番号に電話をかける。モデムが指定されていない場合は、最初のモデムが使用される。
DPAID _ServiceProvider | この DirectPlay アドレスが適用されるサービス プロバイダの 16 バイト GUID。
DPAID_TotalSize | DirectPlay アドレス全体のサイズを含む DWORD。このデータ チャンクは、CreateCompoundAddress によって自動的に追加される。


DirectPlay アドレスの使用例

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic 用の DirectX では、DirectPlayAddress クラスのオブジェクトがアドレス情報を保持する。このオブジェクトは、DirectPlayLobby3 のいずれかのメソッドによって作成される。詳細については、「サービス プロバイダ ダイアログの置換」を参照すること。

[C++]

ここでは、DirectPlay アドレスとそれに含まれるデータを、接続形態ごとに説明する。

IPX 接続を記述する DirectPlay アドレス

この接続を初期化すると、DirectPlay オブジェクトが IPX サービス プロバイダにバインドされる。

guidDataType | dwDataSize | データ
DPAID_ServiceProvider | 16 | {685BC400-9D2C-11cf-A9CD-00AA006886E3}

モデム接続を記述する DirectPlay アドレス

この接続を初期化すると、DirectPlay がモデム サービス プロバイダにバインドされ、電話番号が格納される。アプリケーションがセッションの列挙を開始すると、サービス プロバイダはユーザーに電話番号をたずねることなく、この番号に電話する。

guidDataType | dwDataSize | データ
DPAID_ServiceProvider | 16 | {44EAA760-CB68-11cf-9C4E-00A0C905425E}
DPAID_Phone | 9 (NULL ターミネータを含む) | "555-8237"

TCP/IP 接続を記述する DirectPlay アドレス

この接続を初期化すると、DirectPlay が TCP/IP サービス プロバイダにバインドされ、IP アドレスが格納される。アプリケーションがセッションを列挙するとき、サービス プロバイダはユーザーに IP アドレスをたずねない。

guidDataType | dwDataSize | データ
DPAID_ServiceProvider | 16 | {36E95EE0-8577-11cf-960C-0080C7534E82}
DPAID_INet | 10 (NULL ターミネータを含む) | "127.0.0.1"


DirectPlay プロトコル

DirectPlay プロトコルは、保証されていないサービス プロバイダ上における保証メッセージングの実装である。たとえば、IPX (Internetwork Packet Exchange) サービス プロバイダはその性質上、保証メッセージングをサポートしていない。アプリケーションが IPX 上で保証メッセージを送信しようとすると、DirectPlay プロトコルがメッセージの転送を保証するために必要な処理をすべて実行する。

DirectPlay プロトコルは、非同期メッセージングと、メッセージのスロットリングもサポートしている。ただし、サービス プロバイダがこれらの機能を最適化する場合もある。

アプリケーションは、セッションを作成するときに DPSESSION_DIRECTPLAYPROTOCOL フラグを設定して、DirectPlay プロトコルを起動する。

システム メッセージは、サービス プロバイダが保証メッセージをネイティブにサポートしているかどうかに関係なく、また、DirectPlay プロトコル フラグを設定してあるかどうかに関係なく、常に保証付きで送信される。システム メッセージを保証付きで送信する場合は、DirectPlay プロトコルが自動的に使用される。

[C++]

システム メッセージ以外の場合は、アプリケーションが DirectPlay プロトコル フラグを設定し、(IDirectPlay4::SendEx で DPSEND_GUARANTEED フラグを設定することにより) メッセージを保証付きで送信すると、サービス プロバイダが保証メッセージをサポートしているかどうかに関係なく、メッセージは保証付きで送信される。

[Visual Basic]

システム メッセージ以外の場合は、アプリケーションが DirectPlay プロトコル フラグを設定し、(DirectPlay4.SendEx で DPSEND_GUARANTEED フラグを設定することにより) メッセージを保証付きで送信すると、サービス プロバイダが保証メッセージをサポートしているかどうかに関係なく、メッセージは保証付きで送信される。

アプリケーションが DirectPlay フラグを設定せずにメッセージを保証付きで送信すると、DPSEND_GUARANTEED フラグに関係なく、サービス プロバイダが保証メッセージをサポートする場合に限り、転送が保証される。

アプリケーションは、サービス プロバイダによって実装されたデフォルトの保証メッセージングの代わりに、DirectPlay プロトコルを使用するように指定することもできる。この指定は、セッションを作成するときに DPSESSION_DIRECTPLAYPROTOCOL フラグを設定して行うこともできる。

以下は、システム メッセージ以外のメッセージが送信されるしくみをまとめたものである。

DirectPlay プロトコル フラグが設定されていない場合

サービス プロバイダ | 保証付きで送信されるメッセージが使用するもの | 保証なしで送信されるメッセージが使用するもの
IPX | IPX。保証付きでは送信されない | IPX
TCP/IP | TCP | UDP
モデム | モデム。保証付きでは送信されない | モデム

DirectPlay プロトコル フラグが設定されている場合

サービス プロバイダ | 保証付きで送信されるメッセージが使用するもの | 保証なしで送信されるメッセージが使用するもの
IPX | DirectPlayProtocol/IPX | DirectPlayProtocol/IPX
TCP/IP | DirectPlayProtocol/UDP | DirectPlayProtocol/UDP
モデム | DirectPlayProtocol/モデム | DirectPlayProtocol/モデム

DirectPlay プロトコル フラグが設定されていない場合、アプリケーションは (セッションが開いた後に) サービス プロバイダの能力を調べて、非同期メッセージング、メッセージのキャンセル、メッセージのタイムアウト、メッセージの優先順位などに関連して利用できる機能を判断する必要がある。DirectPlay プロトコル フラグが設定されている場合は、これらの機能をすべて利用できる。


DirectPlay プロトコルを使用した非同期ネットワーキング

ネットワーク対応のゲーム アプリケーションを設計するときは、ネットワーキング コードのオブジェクトが、同期されたゲーム環境の基盤を多数のプレーヤーに提供する。ネットワーキング コードでは、多数の異なるネットワーク環境を処理する必要がある。これらの環境は、待ち時間、帯域幅、信頼性の程度が異なる場合がある。

DirectPlay を利用する前に、ゲーム開発者は、ネットワーク リンクの性質を判断し、ゲームを適切に適応させる必要がある。通常、開発者が採用する解決策は、送信するデータの量と頻度を最小限に抑えるというものだ。この方法は過酷な環境でもうまく機能するが、エンド ユーザーに最高のゲーム体験を提供することはできない。多くの場合は、ゲームでより多くのアップデートまたはアップデートごとの情報を送信することにより、ユーザーの体感を向上させ、ゲーム環境をより密に同期させることができる。

ネットワーク コードの目標は、利用可能な帯域幅をすべて利用してゲーム状態を更新することである。同時に、リンクの処理能力を超えてデータを速く送信することにより発生する接続のバックログを防ぐ必要がある。バックログが発生すると、待ち時間が増えたり、ゲームの同期がうまくいかなくなる。

DirectPlay プロトコルと非同期メッセージングが提供する環境では、アプリケーションのネットワーク コードが、リンクの能力を判断し、利用可能な帯域幅を最大限に活用できるように自らの動作を適応させることができる。

DirectPlay プロトコルは、受信側からのフィードバックを使用し、受信側に届いたデータ量を把握する。既存のネットワーク プロトコルと違い、DirectPlay プロトコルはフィードバックを使用することにより送信レートを正確に制御し、送信側と受信側の間でメッセージ パケットのバックログが作成されないようにすることができる。

DirectPlay プロトコルは、このフィードバックを非保証メッセージにも適用する。送信メッセージのスロットリングは、クライアント アプリケーションがバックログを作成することによりゲームに余分な待ち時間を発生させないようにするだけでなく、クライアントが自らをメッセージに適応させることを可能にする。クライアントは、送信キューを確認することにより、リンクの転送能力よりも速くデータを送信している状態や、クライアントが利用可能な帯域幅をいっぱいに使用している状態を認識することができる。これにより、クライアントは既存のリンクの能力に応じて、送信方法を調整することが可能になる。

DirectPlay プロトコルを最大限に活用するには、メッセージを非同期的に送信する必要がある (この方法の詳細については、「非同期メッセージング」を参照)。非同期的に送信されたメッセージは、制御を占有しない。メッセージを非同期的に送信すると、SendEx が戻る時点では、送信は完了していない。後で送信が完了すると、完了メッセージが受信キューに送られる。

非同期送信を利用すると、DirectPlay プロトコルは、保証付きおよび保証なしの両方のメッセージを、リンク上で同時に多数送信することができる。つまり、あるメッセージの完了を待機せずに、次のメッセージを送信できる。これにより、単一のパケットが失われたことによってリンクを使用できなくなるという事態を防ぐことができる。また、保証付きのパケットが 1 つ失われたことによってほかの保証メッセージの転送が遅れるということもなくなる。

従来、ネットワーク ゲームでは、リアルタイムのゲーム状態を転送する場合に限り、保証なしのメッセージを利用するのが一般的だった。これは、保証なしのメッセージを送信すると、通常は制御が占有されず、多数のメッセージを待ち時間なしで送信できるからである。DirectPlay プロトコルを使用すると、制御を占有しない保証メッセージを送信し、各接続に対する多数の送信を未完の状態にしておくことができる。つまり、ゲームで保証送信を利用し、なおかつ非保証送信を利用するゲームと同程度の応答性を確保できる。これにより、ゲーム状態の更新に関する設計が大幅に簡素化され、インクリメンタルな更新が可能になる。これを非保証送信で実現するのは、ほぼ不可能である。

DirectPlay プロトコルを使用するときには、以下の事項に注意する必要がある。

  • DirectPlay プロトコルがアクティブな場合は、スロットリングが原因で、同期型の非保証送信が制御を占有する場合がある。送信時に非同期フラグを設定すると、非保証送信が直ちに戻るようにし、ゲームのスレッドが制御を占有するのを防ぐことができる。
  • DirectPlay プロトコルを使用すると、ネットワーク リンクを有効に活用できるが、依然として送信するデータの量を最小限に抑えるように注意する必要がある。状態の更新時に送信するデータは、少なければ少ないほどよい。また、最終的な目標は、1 秒間の更新回数を増やして、ユーザーの体感を向上させることである。
  • 非同期送信を実行すると、プロトコルは送信データのコピーをとる。そのため、バッファを再利用することができる (または、メッセージをスタックに割り当てることができる)。したがって、依然としてペンディング キューに含まれているすべての送信メッセージは、その送信と同じサイズのメモリ割り当てを表している。送信キューを無制限に大きくしてはいけない。通常は、特定のプレーヤーに対する送信キューを 16 送信以上にしても、何の利点も得られない。DirectPlay プロトコルの現在の実装では、送信キュー内のメッセージの数は 29 に制限されている。それ以上の送信は、同時に送信される。つまり、ほかの送信が終了するのを待機してから、パケットがネットワーク リンクに送信される。各プレーヤーの送信キューまたは受信キューを調べるには、GetMessageQueue を使用する。
  • 特定のプレーヤーに対する送信キューと、すべての送信キューの違いに注意しなければならない。送信をスロットリングする場合、通常はすべてのプレーヤーに対してではなく、送信先のプレーヤーに対するキューを取得する必要がある。これは、グループ送信ではなく、直接送信を使用する場合にも当てはまる。
  • 送信キューが常に空の場合は、データの送信レートを高くし、ゲームの同期処理を向上させるべきである。このプロトコルは受信側からフィードバックを取得するので、受信側に悪影響を与える心配はない。空のキューは、帯域幅の無駄を意味する。
  • キューを確認するときには、ループをタイトにせず、適度なスリープ時間を挿入する。スレッドを常時確認すると、CPU サイクルをすべて使用する可能性がある。スリープ時間は、キューに次の送信を実行するまでの時間を基にして決める。
  • 送信キューはバックログを表す。送信キューが長くなるほど、以降の送信の待ち時間は長くなる。キューが長くなりすぎた場合は、メッセージをキャンセルする。


セキュリティと認証

DirectPlay のセキュリティを利用すると、サーバー上で実行されるアプリケーションで、ユーザーのセッションへの参加を許可する前に、そのユーザーを既知のユーザーのデータベースに照らし合わせて認証することができる。ユーザーが認証されると、クライアントとサーバー間のすべての通信は、デジタル署名付きメッセージ (送信側の身元を確認するため) または暗号化メッセージにより、安全に実行される。

構造に関する概要については、「セキュリティ」を参照すること。

その他の情報については、次のトピックを参照すること。

  • ユーザーとメッセージの認証
  • メッセージの暗号化
  • ファイアウォールのサポート
  • セキュア セッション


ユーザーとメッセージの認証

DirectPlay は、Windows® Security Support Provider Interface (SSPI) を介して、ユーザーとメッセージの認証 (デジタル署名) に対するサポートを提供する。DirectPlay が使用するデフォルトのセキュリティ パッケージは、NTLM Security Support Provider である。

[Visual Basic]

DirectPlay アプリケーションは、セッションの作成時に DirectPlay4.SecureOpen を使用して、異なる SSPI セキュリティ パッケージを選択することができる。たとえば、組織が大規模な顧客ベース (数十万単位) に対してメンバシップ サービスを提供するために利用できるセキュリティ パッケージとして、DPA (Distributed Password Authentication) がある。このセキュリティ パッケージは、Microsoft Commercial Internet Services (MCIS) Membership Server を介して利用できる。

[C++]

DirectPlay アプリケーションは、セッションの作成時に IDirectPlay4::SecureOpen を使用して、異なる SSPI セキュリティ パッケージを選択することができる。たとえば、組織が大規模な顧客ベース (数十万単位) に対してメンバシップ サービスを提供するために利用できるセキュリティ パッケージとして、DPA (Distributed Password Authentication) がある。このセキュリティ パッケージは、Microsoft Commercial Internet Services (MCIS) Membership Server を介して利用できる。


メッセージの暗号化

DirectPlay は、Windows Cryptography Application Programming Interface (CAPI) を介して、メッセージの暗号化に対するサポートを提供する。DirectPlay の暗号化サービスに対するデフォルトの CAPI プロバイダは、Microsoft RSA Base Cryptographic Provider バージョン 1.0 である。このデフォルトの CAPI プロバイダのタイプは PROV_RSA_FULL であり、デフォルトの暗号化アルゴリズムは CALG_RC4 ストリーム サイファである。

[C++]

DirectPlay アプリケーションは、セッションの作成時に IDirectPlay4::SecureOpen メソッドを使用して、異なる暗号化プロバイダを選択することができる。ただし、DirectPlay はストリーム サイファのみをサポートすることに注意すること。

[Visual Basic]

DirectPlay アプリケーションは、セッションの作成時に DirectPlay4.SecureOpen メソッドを使用して、異なる暗号化プロバイダを選択することができる。ただし、DirectPlay はストリーム サイファのみをサポートすることに注意すること。


ファイアウォールのサポート

DirectPlay のファイアウォール サポートを利用するために、アプリケーションを書き直す必要はない。デフォルトの動作では、DirectPlay のレンジから動的に割り当てられるポートを使用する。これにより、既存のアプリケーションとの後方互換性が確保されると共に、1 台のコンピュータ上で複数の DirectPlay アプリケーションを使用することが可能になる。

また、DirectPlay の新しい固定ポート機能を利用するようにアプリケーションを記述することもできる。開発者は、アプリケーション用の特定のポートを選択することができる。ファイアウォール管理者は、そのポートだけを開けばよい。詳細については、TCP/IP の該当する項目を参照すること。

DirectX 6.0 以降のユーザーは、ファイアウォールが介在していない場合に限り、DirectX 5.0 のユーザーと通信することができる。つまり、コンピュータが 1 台でもファイアウォールの後ろに位置していれば、DirectX 5.0 コンピュータとのピアツーピア ゲームは機能しない。クライアント/サーバー ゲームは、ホストが DirectX 6.0 以上であり、なおかつホストとクライアント間の通信がファイアウォールを経由する各部分で、クライアントが DirectPlay 6.0 以降である場合に限り、機能する。

プロキシの構造上、利用できるコンピュータは 1 台に制限される。しかし、そのコンピュータ上で複数のアプリケーションを実行することが可能である (各アプリケーションは、DirectPlay の動的なレンジまたはアプリケーション定義の一意のポートを使用する)。

DirectPlay を使用してファイアウォールをサポートする方法の詳細については、次のトピックを参照すること。

  • DirectPlay の動的レンジを使用したクライアントのファイアウォール サポートの設定
  • DirectPlay の動的レンジを使用したホストのファイアウォール サポートの設定
  • アプリケーションで指定される固定ポートの使用
  • アプリケーションで指定されるポートを使用したクライアントのファイアウォール サポートの設定
  • アプリケーションで指定されるポートを使用したホストのファイアウォール サポートの設定
  • 動的レンジのポートに関する参照表
  • DirectX 5.0 と DirectX 6.0 の互換性に関する参照表


DirectPlay の動的レンジを使用したクライアントのファイアウォール サポートの設定

ファイアウォールを介してゲームに参加するには、DirectX 6.0 以降を使用しているクライアントが、DirectX 6.0 以降を使用しているホストと通信しなければならい。DirectPlay の動的レンジを使用しているアプリケーションをサポートするには、ファイアウォール管理者は、初期の外向き TCP 接続をポート 47624 上で許可し、2 次的な内向き TCP 接続をポート 2300 ～ 2400、外向き TCP 接続をポート 2300 ～ 2400、内向き UDP 接続をポート 2300 ～ 2400、外向き UDP 接続をポート 2300 ～ 2400 でそれぞれ許可する必要がある。これらの要件を示す表については、「動的レンジのポートに関する参照表」を参照すること。

Microsoft Proxy Server 2.0 の構成例

  • Internet Service Manager、Windows Sockets Proxy サービス : サービスのプロパティ
    • [プロトコル] タブをクリックし、"DirectPlay (client)" というプロトコルを追加する。
      • 初期接続
        • 47624 TCP 外向き
      • 2 次的な接続
        • 2300 ～ 2400 TCP 内向き
        • 2300 ～ 2400 TCP 外向き
        • 2300 ～ 2400 UDP 内向き
        • 2300 ～ 2400 UDP 外向き
    • [許可] タブをクリックし、[DirectPlay (client)] プロトコルに適切なアクセス権を許可する。
  • mspclnt.ini ファイルに以下の内容を追加する。このファイルは、デフォルトでは C:\Msp\Clients フォルダにある。
    • [Common Configuration]
    • RemoteBindUdpPorts=2300-2400
    • ServerBindTcpPorts=2300-2400
    • KillOldSession=1


DirectPlay の動的レンジを使用したホストのファイアウォール サポートの設定

ファイアウォールを介してゲームをホストするには、ホストが DirectX 6.0 以降を使用し、ファイアウォールの後ろに位置するクライアントも DirectX 6.0 以降を使用している必要がある。DirectPlay の動的レンジを使用するアプリケーションをサポートするには、ファイアウォール管理者は、初期の内向き TCP 接続を ポート 47624 上で許可し、2 次的な内向き TCP 接続をポート 2300 ～ 2400、外向き TCP 接続をポート 2300 ～ 2400、内向き UDP 接続をポート 2300 ～ 2400、外向き UDP 接続をポート 2300 ～ 2400 でそれぞれ許可する必要がある。これらの要件を示す表については、「動的レンジのポートに関する参照表」を参照すること。

Microsoft Proxy Server 2.0 の理論上の構成

  • Internet Service Manager、Windows Sockets Proxy サービス : サービスのプロパティ
    • [プロトコル] タブをクリックし、"DirectPlay (host)" というプロトコルを追加する。
      • 初期接続
        • 47624 TCP 内向き
      • 2 次的な接続
        • 2300-2400 TCP 内向き
        • 2300-2400 TCP 外向き
        • 2300-2400 UDP 内向き
        • 2300-2400 UDP 外向き
    • [許可] タブをクリックし、[DirectPlay (host)] プロトコルに適切なアクセス権を許可する。
  • mspclnt.ini ファイルに以下の内容を追加する。このファイルは、デフォルトでは C:\Msp\Clients フォルダにある。
    • [Common Configuration]
    • RemoteBindUdpPorts=2300-2400
    • ServerBindTcpPorts=2300-2400
    • KillOldSession=1

残念ながら、Microsoft Proxy Server 2.0 を含む一部のファイアウォール ソリューションは、これ以外の内向き接続を 2 次的な接続として認識しない。この問題を回避するには、アプリケーションで指定される固定ポートと同じように、レンジ内の各ポート (2300、2301、2302 など) に独自のプロトコル定義を設定する必要がある。詳細については、「アプリケーションで指定されるポートを使用したホストのファイアウォール サポートの設定」を参照すること。実際には、アクティブな DirectPlay アプリケーションの数だけポートを開く必要がある。つまり、"SuperDuperGame" と "WackyFunGame" を同時に実行すると、ポート 2300 と 2301 だけが使用される。


アプリケーションで指定される固定ポートの使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

アプリケーションは、DirectPlay のデフォルトのポートではなく、固定ポートを選択することができる。この場合、そのアプリケーションをファイアウォールを介して機能させるには、1 つのポートだけを開けばよい。

アプリケーションで固定ポートを指定するには、DPAID_InetPort 用のデータ チャンクを含む DirectPlay アドレスを作成する必要がある。アプリケーションは、このデータ チャンクを IDirectPlay4::InitializeConnection に渡す前に、IDirectPlay4::EnumConnections によって返される lpAddress に添付することができる。または、完全な DirectPlay アドレス (サービス プロバイダ、IP アドレス、およびポート番号を指定する) を作成し、それを InitializeConnection に渡すこともできる。

詳細については、「DirectPlay アドレス」を参照すること。


アプリケーションで指定されるポートを使用したクライアントのファイアウォール サポートの設定

ファイアウォールを介してゲームに参加するには、DirectX 6.0 以降を使用しているクライアントが、DirectX 6.0 以降を使用しているホストと通信しなければならい。アプリケーションで指定される固定ポート n を使用するアプリケーションをサポートするには、ファイアウォール管理者は、初期の外向き TCP 接続をポート n で許可し、2 次的な内向き TCP 接続をポート n、内向き UDP 接続をポート n、外向き UDP 接続をポート n でそれぞれ許可する必要がある。

アプリケーション "SuperDuperGame" (superdg.exe) がポート 12345 を指定している場合の、Microsoft Proxy Server 2.0 の構成例

  • Internet Service Manager、Windows Sockets Proxy サービス : サービスのプロパティ
    • [プロトコル] タブをクリックし、" SuperDuperGame (client)" というプロトコルを追加する。
      • 初期接続
        • 12345 TCP 外向き
      • 2 次的な接続
        • 12345 TCP 内向き
        • 12345 UDP 内向き
        • 12345 UDP 外向き
    • [許可] タブをクリックし、[SuperDuperGame] プロトコルに適切なアクセス権を許可する。
  • mspclnt.ini ファイルに以下の内容を追加する。このファイルは、デフォルトでは C:\Msp\Clients フォルダにある。
    • [superdg]
    • RemoteBindUdpPorts=12345
    • ServerBindTcpPorts=12345
    • KillOldSession=1


アプリケーションで指定されるポートを使用したホストのファイアウォール サポートの設定

ファイアウォールを介してゲームをホストするには、ホストが DirectX 6.0 以降を使用し、ファイアウォールの後ろに位置するクライアントも DirectX 6.0 以降を使用している必要がある。アプリケーションで指定される固定ポート n を使用するアプリケーションをサポートするには、ファイアウォール管理者は、初期の内向き TCP 接続をポート n で許可し、2 次的な外向き TCP 接続をポート n、内向き UDP 接続をポート n、外向き UDP 接続をポート n でそれぞれ許可する必要がある。

アプリケーション "SuperDuperGame" (superdg.exe) がポート 12345 を指定している場合の、Microsoft Proxy Server 2.0 の構成例

  • Internet Service Manager、Windows Sockets Proxy サービス : サービスのプロパティ
    • [プロトコル] タブをクリックし、" SuperDuperGame (host)" というプロトコルを追加する。
      • 初期接続
        • 12345 TCP 内向き
      • 2 次的な接続
        • 12345 TCP 外向き
        • 12345 UDP 内向き
        • 12345 UDP 外向き
    • [許可] タブをクリックし、[SuperDuperGame] プロトコルに適切なアクセス権を許可する。
  • mspclnt.ini ファイルに以下の内容を追加する。このファイルは、デフォルトでは C:\Msp\Clients フォルダにある。
    • [superdg]
    • RemoteBindUdpPorts=12345
    • ServerBindTcpPorts=12345
    • KillOldSession=1


動的レンジのポートに関する参照表

以下は、DirectPlay の動的レンジを使用するアプリケーションに対して、管理者が開く必要のあるポートを示している。

接続 | クライアントの構成 | ホストの構成
初期 TCP 接続 | 47624 外向き | 47624 内向き
2 次的な内向き TCP 接続 | 2300 ～ 2400 | 2300 ～ 2400
2 次的な外向き TCP 接続 | 2300 ～ 2400 | 2300 ～ 2400
2 次的な内向き UDP 接続 | 2300 ～ 2400 | 2300 ～ 2400
2 次的な外向き UDP 接続 | 2300 ～ 2400 | 2300 ～ 2400


DirectX 5.0 と DirectX 6.0 の互換性に関する参照表

以下は、バージョン間の互換性を示している。ここでは、コンピュータが 2 台だけで、ファイアウォールが両方にとって物理的に同じファイアウォールである (つまり、クライアントとホストの両方が同じファイアウォールの後ろに位置する) と仮定している。ここで言う DirectX 6.0 とは、"DirectX 6.0 以降" を意味する。

 | インターネット上の DirectX 5.0 ホスト | ファイアウォールの後ろに位置する DirectX 5.0 ホスト | インターネット上の DirectX 6.0 ホスト | ファイアウォールの後ろに位置する DirectX 6.0 ホスト
インターネット上の DirectX 5.0 クライアント | あり | なし | あり | なし
ファイアウォールの後ろに位置する DirectX 5.0 クライアント | なし | あり | なし | あり
インターネット上の DirectX 6.0 クライアント | あり | なし | あり | あり
ファイアウォールの後ろに位置する DirectX 6.0 クライアント | なし | あり | あり | あり

この表は、セッションがクライアント/サーバー型であれば、コンピュータが 3 台以上の場合にも当てはまる。3 台以上のコンピュータが存在し、セッションがピアツーピアで、ファイアウォールがどこかに存在する場合は、すべてのコンピュータが DirectX 6.0 以降を使用する必要がある。


セキュア セッション

セキュア セッションは、認証されたユーザーのみが参加可能なセッションである。これは、パスワードによる保護とは異なる。認証では、ユーザーがサーバーの管理者によってメンバシップ データベースに追加されているかどうかに基づいて、そのユーザーにサーバーへのアクセスが許可されているかどうかを判断する。セッションへの参加を許可されるのは、メンバシップ データベースに含まれているユーザーだけである。パスワードは、セキュア セッションであるかどうかに関係なく、任意のセッションに追加することができる。セキュア セッションをホストできるのは認証をサポートするコンピュータだけであるが、セッションにパスワードを追加するのはどのコンピュータでも可能である。

[C++]

DirectPlay のセキュア セッションを作成するには、サーバー アプリケーションが、IDirectPlay4::Open または IDirectPlay4::SecureOpen に渡す DPSESSIONDESC2 構造体で、DPSESSION_SECURESERVER フラグを設定するだけでよい。Open を使用すると、デフォルトのセキュリティ パッケージを使用し、クライアントがセッションに参加したときには認証を要求しないセッションを作成することができる。

DirectPlay アプリケーションは、セッションを作成するときに SecureOpen メソッドを呼び出し、使用するプロバイダを DPSECURITYDESC 構造体で指定することにより、別のプロバイダを選択することができる。ユーザーおよびメッセージの認証に使用する SSPI プロバイダが異なる場合、アプリケーションは DPSECURITYDESC 構造体の lpszSSPIProvider メンバにプロバイダの名前を指定する必要がある。メッセージのプライバシに使用する CryptoAPI プロバイダが異なる場合は、プロバイダの名前、タイプ、および暗号化アルゴリズムを、それぞれ lpszCAPIProvider、dwCAPIProviderType、および dwEncryptionAlgorithm メンバに指定する必要がある。

クライアントがこのセッションを列挙すると、IDirectPlay4::EnumSessions によって返される DPSESSIONDESC2 構造体で DPSESSION_SECURESERVER フラグが設定される。このフラグはクライアントに対し、セッションに参加するためには、認証用の信用証明が必要であることを伝える。クライアントが IDirectPlay4::Open を使用してセッションへの参加を試みると、そのユーザーの信用証明がシステムへのログ オンを通して既に確立されていれば、セキュリティ パッケージによりユーザーの参加が許可される場合がある。それ以外の場合は、DPERR_LOGONDENIED エラーが返される。その場合、アプリケーションはユーザーから信用証明を収集し、それを DPCREDENTIALS 構造体に格納し、その構造体を渡して IDirectPlay4::SecureOpen を呼び出して、セッションへの参加を再度試みる必要がある。セキュリティ上の理由により、SecureOpen が推奨されている。

[Visual Basic]

DirectPlay のセキュア セッションを作成するには、サーバー アプリケーションが、DirectPlay4.Open または DirectPlay4.SecureOpen に渡す DirectPlaySessionData オブジェクトで、DPSESSION_SECURESERVER フラグを設定するだけでよい。Open を使用すると、デフォルトのセキュリティ パッケージを使用し、クライアントがセッションに参加したときには認証を要求しないセッションを作成することができる。

DirectPlay アプリケーションは、セッションを作成するときに SecureOpen メソッドを呼び出し、使用するプロバイダを DPSECURITYDESC 型に指定することにより、別のプロバイダを選択することができる。ユーザーおよびメッセージの認証に使用する SSPI プロバイダが異なる場合、アプリケーションは DPSECURITYDESC 型の strSSPIProvider メンバにプロバイダの名前を指定する必要がある。メッセージのプライバシに使用する CryptoAPI プロバイダが異なる場合は、プロバイダの名前、タイプ、および暗号化アルゴリズムを、それぞれ strCAPIProvider、lCAPIProviderType、および lEncryptionAlgorithm メンバに指定する必要がある。

クライアントがこのセッションを列挙すると、DirectPlayEnumSessions.GetItem によって返される DirectPlaySessionData オブジェクトで DPSESSION_SECURESERVER フラグが設定される。このフラグはクライアントに対し、セッションに参加するためには、認証用の信用証明が必要であることを伝える。クライアントが DirectPlay4.Open を使用してセッションへの参加を試みると、そのユーザーの信用証明がシステムへのログ オンを通して既に確立されていれば、セキュリティ パッケージによりユーザーの参加が許可される場合がある。それ以外の場合は、DPERR_LOGONDENIED エラーが返される。その場合、アプリケーションはユーザーから信用証明を収集し、それを DPCREDENTIALS 型に格納し、それを渡して DirectPlay4.SecureOpen を呼び出して、セッションへの参加を再度試みる必要がある。

セキュア セッションでは、DirectPlay のシステム メッセージには、送信側の身元がわかるように、すべてデジタル署名が施される。重要な情報を運ぶ一部のシステム メッセージは、暗号化される。あるプレーヤーから発生し、セッション内のほかのすべてのプレーヤーにブロードキャストしなければならないシステム メッセージは、まずサーバーに送信される。サーバーは、自らの署名をメッセージに加えて、そのメッセージをセッション内のほかのすべてのコンピュータに送信する。デフォルトでは、プレーヤー対プレーヤーのメッセージには署名は加えられず、サーバーも経由しない。

アプリケーションは、メッセージの送信時に DPSEND_SIGNED フラグまたは DPSEND_ENCRYPTED フラグを設定して、プレーヤー対プレーヤーのメッセージに署名するか、または暗号化するかを選択することができる。署名されたメッセージと暗号化されたメッセージは、サーバーを経由し、セキュアなシステム メッセージとして届けられる。プレーヤーがセキュアなメッセージを受信すると、署名が加えられているか、または暗号化されているかを示すフラグがメッセージに含まれている。確認処理をパスしないメッセージは、破棄される。


DirectX の以前のバージョンからの移行

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectPlay API の現在のバージョンは、DirectX の以前のバージョンで記述されたアプリケーションとの完全な互換性を備える。つまり、コードに変更を加えることなく、アプリケーションをDirectX の現在のバージョン用に再コンパイルすることができる。しかし、新しい機能を利用するには、コードを修正しなければならない場合がある。

詳細については、次のトピックを参照すること。

  • DirectX 3.0 以降からの移行
  • DirectX 2.0 からの移行


DirectX 3.0 以降からの移行

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectX バージョン 3.0 以降の一部であったバージョンから DirectPlay の現在のバージョンに以降する場合は、いかなる変更も加える必要はない。しかし、新しい IDirectPlay4 または IDirectPlay4A インターフェイスを使用する場合は、アプリケーションをアップグレードする必要がある。

一部のシステム メッセージは DirectX 6.0 で変更され、新しいデータ メンバが最後に追加された。これらの新しいメンバは、現在のバージョンでも継続して利用される。従来のランタイム ファイルとの互換性を確保しなければならないアプリケーションでは、以下のいずれかを行う必要がある。

  • DirectX 3.0 のヘッダー ファイルおよびライブラリと共にコンパイルする。
  • 新しいデータ メンバへの参照を避ける。
  • DirectX 3.0 と現在のランタイム ファイルの両方でテストする。

バージョン 5.0 に対して新しいメンバが追加されたシステム メッセージ構造体は、以下のとおりである。

構造体 | 新しいメンバ
DPMSG_CREATEPLAYERORGROUP | DPID dpIdParent
 | DWORD dwFlags
DPMSG_DESTROYPLAYERORGROUP | DPNAME dpnName
 | DPID dpIdParent
 | DWORD dwFlags


DirectX 2.0 からの移行

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectX バージョン 3.0 以降の DirectPlay の DLL の名前は、それ以前のバージョンのものとは異なる。Applications compiled with DirectX 2.0 以前と互換性があるアプリケーションは、DirectPlay の新しい DLL を使用しない。これらの新しい DLL を使用するには、アプリケーションを再コンパイルして、インポート ライブラリ Dplayx.lib にリンクしなければならない。

また、アプリケーションをロビーに対応させるためのコードも追加すべきである。これにより、外部ロビーまたは仲介プログラムがアプリケーションを開始し、セッションに接続するために必要な情報をすべて提供できるようになる。アプリケーションでは、サービス プロバイダを決めたり、セッションを選択したり、その他の情報 (電話番号、ネットワーク アドレスなど) を提供したりするように、ユーザーに要求する必要はない。

さらに、DirectX バージョン 6.0 では、ほかにも新しい機能がいくつか追加された。これらの新機能には、以下のようなものがある。

  • 保証メッセージング
  • 非同期メッセージング
  • メッセージのスロットリング
  • ファイアウォールのサポート
  • ロビーの改善
  • セキュリティの改善
  • ローカライズ サポートの改善
  • アプリケーションを登録および登録解除するための API
  • グループ所有権の管理の改善
  • キープアライブのサポートの改善
  • プライベートなサービス プロバイダ

DirectPlay バージョン 2.0 以前で作成されたアプリケーションを移行させるには、次のステップを実行する。

アプリケーションがロビー クライアントから起動されていたかどうかを確認する。詳細については、「ステップ 2 : 接続設定の取得」を参照すること。

アプリケーションがサービス プロバイダを列挙している場合は、DirectPlay4::EnumConnections メソッドを使用して、サービス プロバイダが利用可能かどうかを判断する。利用可能な場合は、そのサービス プロバイダに対して DirectPlay4::InitializeConnection メソッドを呼び出す。InitializeConnection がエラーを返す場合、サービス プロバイダをシステム上で実行することはできないので、そのサービス プロバイダをユーザーに表示するリストに追加すべきではない。呼び出しが成功した場合は、Release メソッドを使用して DirectPlay オブジェクトを解放し、そのサービス プロバイダをリストに追加する。

IDirectPlay インターフェイス上の QueryInterface メソッドを呼び出し、IDirectPlay4 (Unicode) または IDirectPlay4A (ANSI) インターフェイスを取得する。2 つのインターフェイスの違いは、構造体内の文字列を読み書きする方法だけである。Unicode インターフェイスの場合は、構造体の LPWSTR 型のメンバに Unicode 文字列が読み書きされる。ANSI インターフェイスの場合は、構造体の LPSTR 型のメンバに ANSI 文字列が読み書きされる。

既存の API で新しい構造体を使用するために必要な変更をすべて加える。たとえば、次のようなコードがあるとする。

lpDP->SetPlayerName(pidPlayer, lpszFriendlyName, lpszFormalName)

lpDP は、IDirectPlay インターフェイスである。この場合は、次のようなコードを使用する。

DPNAME PlayerName, *lpPlayerName
PlayerName.dwSize = sizeof(DPNAME)
lpPlayerName = &PlayerName

lpPlayerName->lpszShortNameA = lpszFriendlyName
lpPlayerName->lpszLongNameA = lpszFormalName
lpDP4A->SetPlayerName(pidPlayer, lpPlayerName, 0)

lpDP4A は、IDirectPlay4A インターフェイスである。このアプリケーションで Unicode 文字列を使用している場合 (したがって、IDirectPlay4 インターフェイスのインスタンスを作成する場合) は、次のようなコードを使用する。

lpPlayerName->lpszShortName = lpwszFriendlyName
lpPlayerName->lpszLongName = lpwszFormalName
lpDP4->SetPlayerName(pidPlayer, lpPlayerName, 0)

lpDP4 は、IDirectPlay4 インターフェイスである。

以下のシステム メッセージを更新する。

DPSYS_ADDPLAYER は、DPSYS_CREATEPLAYERORGROUP に置き換えられた。

DPSYS_DELETEPLAYER と DPSYS_DELETEGROUP は、単一の DPSYS_DESTROYPLAYERORGROUP メッセージに統一された。

DPSYS_DELETEPLAYERFROMGRP は、DPSYS_DELETEPLAYERFROMGROUP に変更された。

アプリケーションを更新し、プレーヤーまたはグループの名前が変更されたときに DPSYS_SETPLAYERORGROUPNAME メッセージを生成し、プレーヤーまたはグループのデータが変更されたときに DPSYS_SETPLAYERORGROUPDATA メッセージを生成するようにする。

DPSESSIONDESC 構造体を DPSESSIONDESC2 に更新し、DPCAPS 構造体に新しいメンバを追加する。

IDirectPlay4::EnumSessions、IDirectPlay4::EnumGroups、IDirectPlay4::EnumGroupPlayers、および IDirectPlay4::EnumPlayers に対するコールバック関数を更新する。

hEvent パラメータを IDirectPlay4::CreatePlayer メソッドに渡す方法を更新する。DirectPlay の以前のバージョンでは、このパラメータは lpEvent だった。DirectPlay はイベントを返さないので、アプリケーションでそれを作成する必要がある。これにより、アプリケーションでは、すべてのプレーヤーに対して 1 つのイベントを作成するという柔軟性が得られる。

プレーヤーがゲームから不適切な方法で退出したことを DirectPlay によって検出したい場合は、DPSESSIONDESC2 構造体の DPSESSION_KEEPALIVE フラグを設定する。

アプリケーションを更新し、DPSESSION_MIGRATEHOST フラグを設定してセッションを作成するようにする。これにより、現在のホストがセッションを退出したときに、別のコンピュータがホストになることが可能になる。ホストだけが実行する特別なコードがアプリケーションにある場合は、アプリケーションでセッションを作成するときに、このフラグを設定する必要がある。または、DPSYS_HOST システム メッセージに対するサポートも追加すべきである。システム メッセージの一覧については、「システム メッセージの使用」を参照すること。

IDirectPlay4 インターフェイスの新しいメソッドに慣れ、それらをアプリケーションで使用する。プレーヤーの状態に関する情報をほかのすべてのプレーヤーにブロードキャストするコードは、IDirectPlay4::SendEx メソッドと IDirectPlay4::Receive メソッドを使用して置き換えられる場合がある。


DirectPlay チュートリアル

ここでは、アプリケーションに DirectPlay 機能を実装する方法を示すチュートリアルを提供する。チュートリアルは、言語ごとに次のグループに分かれている。

  • DirectPlay C/C++ チュートリアル
  • DirectPlay Visual Basic チュートリアル


DirectPlay C/C++ チュートリアル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

このトピックは、次のチュートリアルで構成される。これらのチュートリアルは、DirectPlay の実装をステップ バイ ステップで説明する。

  • チュートリアル 1 : ロビーを使用した接続 (DPChat)
  • チュートリアル 2 : ダイアログ ボックスを使用した接続 (DPChat)
  • チュートリアル 3 : サービス プロバイダ ダイアログの書き換え
  • チュートリアル 4 : 自動リフレッシュ式セッション リストの作成

注 : これらのチュートリアルのサンプル コードは C++ で記述されている。C コンパイラを使う場合、うまくコンパイルできるようにファイルを適切に変更する必要がある。詳細については、「C からの COM オブジェクトへのアクセス」を参照すること。


チュートリアル 1 : ロビーを使用した接続

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

IDirectPlayLobby3 インターフェイスを使用するように記述されたアプリケーションでは、ユーザーに接続情報をダイアログ ボックスに手作業で入力するように要求せずに、セッションに接続することができる。ロビーを使用したアプリケーションの作成方法を示すために、SimpleConnect サンプル では次のステップを実行する。

  • ステップ 1 : DirectPlayLobby オブジェクトの作成
  • ステップ 2 : 接続設定の取得
  • ステップ 3 : セッション記述の構成
  • ステップ 4 : セッションへの接続
  • ステップ 5 : プレーヤーの作成


ステップ 1 : DirectPlayLobby オブジェクトの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

DirectPlay ロビーを使用するには、まず CoCreateInstance を呼び出して DirectPlayLobby オブジェクトのインスタンスを作成する。次の例は、DirectPlayLobby オブジェクトの作成方法の一例を示している。

// IDirectPlayLobby3A インターフェイスを作成する。
if ( FAILED( hr = CoCreateInstance( CLSID_DirectPlayLobby, NULL,
        CLSCTX_INPROC_SERVER,
        IID_IDirectPlayLobby3A,
        (VOID**)&g_pDPLobby ) ) )
    return hr;

次項 : ステップ 2 : 接続設定の取得


ステップ 2 : 接続設定の取得

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

DirectPlayLobby を作成したら、IDirectPlayLobby3::GetConnectionSettings メソッドを使用して、ロビーから返される接続設定を取得する。このメソッドがDPERR_NOTLOBBIED を返す場合、ロビーはこのアプリケーションを起動しておらず、ユーザーは接続を手作業で構成する必要がある。その他のエラーが発生した場合、アプリケーションではエラーを報告し、アプリケーションのロビーが失敗したことを知らせる必要がある。

次の例は、接続設定の取得方法を示している。

// ロビーから接続設定を取得し、g_pdplConnection に設定する。
hr = g_pDPLobby->GetConnectionSettings( 0, NULL, &dwSize );
if ( FAILED(hr) && (DPERR_BUFFERTOOSMALL != hr) )
{
    if( DPERR_NOTLOBBIED == hr )
    {
        *pbLaunchedByLobby = FALSE;

        // ロビーから起動したわけではないので、クリーンアップする。
        SAFE_DELETE_ARRAY( g_pDPLConnection );
        SAFE_RELEASE( g_pDPLobby );

        return S_OK;
    }

    return hr;
}

// 接続にメモリを割り当てる。
SAFE_DELETE_ARRAY( g_pDPLConnection );
g_pDPLConnection = (DPLCONNECTION*)new BYTE[ dwSize ];

// 接続設定を取得する。
if ( FAILED( hr = g_pDPLobby->GetConnectionSettings(
         0, g_pDPLConnection, &dwSize ) ) )
    return hr;

次項 : ステップ 3 : セッション記述の構成


ステップ 3 : セッション記述の構成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

DPSESSIONDESC2 構造体を調べ、アプリケーションに必要なフラグとプロパティがすべて正しく設定されているかどうかを確認する必要がある。修正が必要な場合は、IDirectPlayLobby3::SetConnectionSettings メソッドを使用して、修正した接続設定を格納する。

次の例は、セッション記述を構成し、接続設定を設定する方法を示している。

// セッション フラグを設定する。
g_pDPLConnection->lpSessionDesc->dwFlags =
        DPSESSION_KEEPALIVE | DPSESSION_MIGRATEHOST;

// 接続フラグをロビーに伝える。
if ( FAILED( hr = g_pDPLobby->SetConnectionSettings(
        0, 0, g_pDPLConnection ) ) )
    return hr;

次項 : ステップ 4 : セッションへの接続


ステップ 4 : セッションへの接続

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

セッション記述を正しく構成したら、アプリケーションではIDirectPlayLobby3::ConnectEx メソッドを使って自らを起動し、セッションに接続することができる。このメソッドが DP_OK を返す場合、1 つ以上のプレーヤーを作成できる。このメソッドが DPERR_NOTLOBBIED を返す場合、ユーザーはアプリケーションに対する通信媒体を手作業で選択する必要がある (IDirectPlay4::EnumConnections メソッドを使用すると、システムにインストールされているサービス プロバイダを識別することができる)。その他のエラー値を返す場合、アプリケーションではエラーを報告し、アプリケーションのロビーが失敗したことを知らせる必要がある。

次の例は、セッションへの接続方法を示している。

if ( FAILED( hr = g_pDPLobby->ConnectEx( 0, IID_IDirectPlay4A,
        (VOID**)&g_pDP, NULL ) ) )
    return hr;

次項 : ステップ 5 : プレーヤーの作成


ステップ 5 : プレーヤーの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

IDirectPlayLobby3::ConnectEx メソッドによってアプリケーションの起動に成功したら、1 つ以上のプレーヤーを作成することができる。プレーヤーを作成するには、IDirectPlay4::CreatePlayer メソッドを使用し、名前を DPNAME 構造体 (この構造体は IDirectPlayLobby3::GetConnectionSettings メソッドによって設定される) で指定する。

次の例は、プレーヤーの作成方法を示している。

DPNAME dpname;
ZeroMemory( &dpname, sizeof(DPNAME) );
dpname.dwSize  = sizeof(DPNAME);
dpname.lpszShortNameA = g_strLocalPlayerName;

if ( FAILED( hr = g_pDP->CreatePlayer( &g_LocalPlayerDPID, &dpname,
        NULL, NULL, 0, 0 ) ) )
    return hr;

これでアプリケーションへの接続が完了し、再生する準備が整った。


チュートリアル 2 : ダイアログ ボックスを使用した接続

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

ロビーによってアプリケーションが起動しない場合、ユーザーが接続情報を手作業で入力できるようにするコードを加える必要がある。セッションへの接続と 1 つ以上のプレーヤーの作成を手作業で実行する方法を示すために、SimpleConnect サンプル では次のステップを実行する。

  • ステップ 1 : DirectPlay オブジェクトの作成
  • ステップ 2 : サービス プロバイダの列挙と初期化
  • ステップ 3 : セッションへの参加
  • ステップ 4 : セッションの作成
  • ステップ 5 : 新しいプレーヤーの作成


ステップ 1 : DirectPlay オブジェクトの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

メソッドを呼び出す前に、アプリケーションでは DirectPlay オブジェクトへのインターフェイスを取得する必要がある。

次の例は、IDirectPlay4 インターフェイスを取得する方法を示している。

if ( FAILED( hr = CoCreateInstance( CLSID_DirectPlay, NULL,
        CLSCTX_ALL, IID_IDirectPlay4A, (VOID**)&g_pDP ) ) )
    return hr;

次項 : ステップ 2 : サービス プロバイダの列挙と初期化


ステップ 2 : サービス プロバイダの列挙と初期化

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

手動接続を作成するための次のステップは、アプリケーションに対する通信媒体を選択するようにユーザーに要求することである。アプリケーションでは、EnumConnections メソッドを使用して、パーソナル コンピュータにインストールされているサービス プロバイダを識別することができる。

次の例は、サービス プロバイダを列挙する方法を示している。

// DirectPlay 接続をすべて列挙し
// それらをリストボックスに格納する。
if ( FAILED( hr = pDP->EnumConnections( &g_AppGUID,
        DPConnect_EnumConnectionsCallback, hWndListBox, 0 ) ) )
{
    SAFE_RELEASE( pDP );
    return hr;
}

EnumConnections メソッドの 2 番目のパラメータは、DirectPlay によって登録されたサービス プロバイダを列挙するコールバックである。次の例は、SimpleConnect サンプル におけるこのコールバック関数の実装方法を示している。

BOOL FAR PASCAL DPConnect_EnumConnectionsCallback(
        LPCGUID   pguidSP,
        VOID*     pConnection,
        DWORD     dwConnectionSize,
        LPCDPNAME pName,
        DWORD     dwFlags,
        VOID*     pvContext )
{
    HRESULT       hr;
    LPDIRECTPLAY4 pDP = NULL;
    VOID*         pConnectionBuffer = NULL;
    HWND          hWndListBox = (HWND)pvContext;
    LRESULT       iIndex;

    // IDirectPlay オブジェクトを作成する。
    if ( FAILED( hr = CoCreateInstance( CLSID_DirectPlay, NULL,
            CLSCTX_ALL, IID_IDirectPlay4A, (VOID**)&pDP ) ) )
            return FALSE; // エラー。列挙を中止する。

    // 初期化を試みて、接続が利用できるかどうか
    // テストする。
        // 接続。
    if( FAILED( hr = pDP->InitializeConnection( pConnection, 0 ) ) )
    {
        SAFE_RELEASE( pDP );
        return TRUE; // 利用できない接続。列挙を続ける。
    }

    // IDirectPlay インターフェイスはこれ以上必要ないので、解放する。
    SAFE_RELEASE( pDP );

    // 適切な接続が見つかったので、これをリストボックスに代入する。
    iIndex = SendMessage( hWndListBox, LB_ADDSTRING, 0,
            (LPARAM)pName->lpszShortNameA );
    if( iIndex == CB_ERR )
        return FALSE; // エラー。列挙を中止する。

    pConnectionBuffer = new BYTE[ dwConnectionSize ];
    if( pConnectionBuffer == NULL )
        return FALSE; // エラー。列挙を中止する。

    // GUID へのポインタをリストボックスに格納する。
    memcpy( pConnectionBuffer, pConnection, dwConnectionSize );
    SendMessage( hWndListBox, LB_SETITEMDATA, iIndex,
            (LPARAM)pConnectionBuffer );

    return TRUE; // 列挙を続ける。
}

ユーザーが使用する接続を選択したら、列挙によって返される接続データを取得し、そのデータを使って DirectPlay オブジェクトを初期化する必要がある。

if ( FAILED( hr = g_pDP->InitializeConnection( pConnection, 0 ) ) )
    return hr;

次項 : ステップ 3 : セッションへの参加


ステップ 3 : セッションへの参加

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

ユーザーが既存のセッションへの参加を求めている場合は、IDirectPlay4::EnumSessions メソッドを使用して利用可能なセッションを列挙し、ユーザーに選択肢を示す。次に、DPOPEN_JOIN フラグを設定して IDirectPlay4::Open メソッドを呼び出し、セッションに接続する。セッションを列挙する前に、サービス プロバイダによってユーザーに情報を要求するダイアログ ボックスが表示される場合もある。

非同期の EnumSessions 機能に関する詳細については、「チュートリアル 4 : 自動リフレッシュ式セッション リストの作成」を参照すること。

次の例は、利用可能なセッションを列挙する方法を示している。

// セッションを列挙し、DirectPlay にタイムアウトを判断させる。
ZeroMemory( &dpsd, sizeof(dpsd) );
dpsd.dwSize          = sizeof(dpsd);
dpsd.guidApplication = g_AppGUID;

// 選択された接続で、アクティブな DirectPlay ゲームを
// すべて列挙する。
hr = g_pDP->EnumSessions( &dpsd, 0,
        DPConnect_EnumSessionsCallback, NULL,
        DPENUMSESSIONS_ALL | DPENUMSESSIONS_ASYNC );

IDirectPlay4::EnumSessions メソッドの 3 番目のパラメータは、利用可能なセッションを列挙するコールバックである。次のコードは、SimpleConnect サンプル におけるこのコールバック関数の実装方法を示している。

BOOL FAR PASCAL DPConnect_EnumSessionsCallback(
        LPCDPSESSIONDESC2 pdpsd,
        DWORD*            pdwTimeout,
        DWORD             dwFlags,
        VOID*             pvContext )
{
    DPSessionInfo* pDPSINew = NULL;

    if ( dwFlags & DPESC_TIMEDOUT )
        return FALSE; // タイムアウト。列挙を中止する。

    // 適切なセッションが見つかった。これを保存する。
    pDPSINew = new DPSessionInfo;
    if ( NULL == pDPSINew )
        return FALSE;

    ZeroMemory( pDPSINew, sizeof(DPSessionInfo) );

    // 情報を pDPSINew にコピーする。
    pDPSINew->guidSession = pdpsd->guidInstance;
    sprintf( pDPSINew->szSession, "%s (%d/%d)",
            pdpsd->lpszSessionNameA,
            pdpsd->dwCurrentPlayers,
            pdpsd->dwMaxPlayers );

    // pDPSINew を循環型のリンク リスト g_pDPSIFirst に追加する。
    pDPSINew->pDPSINext = g_DPSIHead.pDPSINext;
    g_DPSIHead.pDPSINext = pDPSINew;

    return TRUE;
}

ユーザーがセッションを選択したら、アプリケーションでは既存のセッションへの参加を許可することができる。次の例は、既存のセッションへ参加する方法を示している。

// DPSESSIONDESC2 を設定し、リストボックスの選択された項目から
// セッションの GUID を取得する。
ZeroMemory( &dpsd, sizeof(dpsd) );
dpsd.dwSize          = sizeof(dpsd);
dpsd.guidInstance    = pDPSISelected->guidSession;
dpsd.guidApplication = g_AppGUID;

// セッションに参加する。
g_bHostPlayer = FALSE;
if ( FAILED( hr = g_pDP->Open( &dpsd, DPOPEN_JOIN ) ) )
    return hr;

次項 : ステップ 4 : セッションの作成


ステップ 4 : セッションの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

ユーザーが新しいセッションを作成する場合は、アプリケーションで IDirectPlay4::Open メソッドを呼び出し、DPOPEN_CREATE フラグを設定することにより、新規のセッションを作成することができる。この場合も、セッションを作成する前に、サービス プロバイダによってユーザーに情報を要求するダイアログ ボックスが表示されることがある。

次の例は、新しいセッションの作成方法を示している。

ZeroMemory( &dpsd, sizeof(dpsd) );
dpsd.dwSize           = sizeof(dpsd);
dpsd.guidApplication  = g_AppGUID;
dpsd.lpszSessionNameA = g_strSessionName;
dpsd.dwMaxPlayers     = 10;
// DPSESSION_KEEPALIVE フラグは、プレーヤーが
// 異常終了した場合にセッションを維持する。
dpsd.dwFlags          = DPSESSION_KEEPALIVE | DPSESSION_MIGRATEHOST;
if ( g_bUseProtocol )
    dpsd.dwFlags |= DPSESSION_DIRECTPLAYPROTOCOL;

// 新しいセッションを作成する。
g_bHostPlayer = TRUE;
if ( FAILED( hr = g_pDP->Open( &dpsd, DPOPEN_CREATE ) ) )
    return hr;

次項 : ステップ 5 : 新しいプレーヤーの作成


ステップ 5 : 新しいプレーヤーの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

セッションを作成するか、または既存のセッションに参加したら、アプリケーションでは IDirectPlay4::CreatePlayer メソッドを使って 1 つ以上のプレーヤーを作成することができる。次のコードは、SimpleConnect サンプル におけるプレーヤーの作成方法を示している。

DPNAME dpname;
ZeroMemory( &dpname, sizeof(DPNAME) );
dpname.dwSize         = sizeof(DPNAME);
dpname.lpszShortNameA = g_strLocalPlayerName;

if ( FAILED( hr = g_pDP->CreatePlayer( &g_LocalPlayerDPID, &dpname,
        NULL, NULL, 0, 0 ) ) )
    return hr;

アプリケーションでは、IDirectPlay4::GetCaps メソッドと IDirectPlay4::GetPlayerCaps メソッドを使用して、プレーヤーの通信機能を判断することができる。別のプレーヤーを見つけるには、IDirectPlay4::EnumPlayers メソッドを使用する。

これでアプリケーションへの接続が完了し、プレーする準備が整った。


チュートリアル 3 : サービス プロバイダ ダイアログの書き換え

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションで DirectPlay を使うとき、サービス プロバイダの標準のダイアログを隠蔽できるようになった。以下に、そのための方法を簡単に示す。コード例は、Override サンプル アプリケーションにある。

一般に、サービス プロバイダのダイアログをすべて隠蔽するのは不可能である。標準の TCP/IP、モデム、およびシリアル サービス プロバイダのダイアログは隠蔽することが可能である (IPX にはダイアログ ボックスは存在ない)。しかし、サード パーティのサービス プロバイダがユーザーからの比較的複雑な情報を必要としていて、それを一般的な方法で書き換えられない場合がある。この問題に対する解決策は、それらのダイアログ ボックスをアプリケーションのユーザー インターフェイスで表示することである。アプリケーションが DirectDraw® のフルスクリーン アプリケーションの場合、IDirectPlay4::EnumSessions または IDirectPlay4::Open を呼び出してセッションを作成する前に、ページ フリッピングをオフにしておく必要がある。

サービス プロバイダのダイアログ ボックスを隠蔽するためのもう 1 つの方法は、アプリケーションをロビーに対応させることである。サード パーティのサービス プロバイダのほとんどは、ゲームを起動するためのロビーも用意している。ロビーから起動されたゲームは、接続のダイアログ ボックスを表示しない。

アプリケーションでは、最初に IDirectPlay4::EnumConnections を呼び出して利用可能な接続を確認し、それらの接続のリストを提供し、ユーザーに接続を選択させる。ユーザーが接続を選択したら、IDirectPlay4::EnumSessions または IDirectPlay4::Open を呼び出す前に、ダイアログ ボックスの書き換えを試みる。

サービス プロバイダのダイアログ ボックスを書き換えるためのステップは次のとおりである。

選択されたサービス プロバイダのサービス プロバイダ GUID を調べて、それがアプリケーションが書き換え方法を把握している既知のサービス プロバイダのいずれかと一致するかどうかを確認する。サービス プロバイダ GUID が既知のものでない場合は、以下のステップをとばして、ダイアログ ボックスの表示を許可する。

特定のサービス プロバイダに必要な情報をユーザーから収集するための適切なユーザー インターフェイスを表示する。IPX の場合は、情報は不要である。TCP/IP の場合は、EnumSessions に対する IP アドレス (DPAID_INet または DPAID_INetW) が必要だが、Open を使用してセッションを作成するために必要なものはない。モデム ツー モデムの場合は、ユーザーがモデム (DPAID_Modem または DPAID_ModemW) を選択するだけでなく、EnumSessions を呼び出すときに電話番号 (DPAID_Phone または DPAID_PhoneW) も必要である。シリアル リンクの場合は、EnumSessions と Open に対してCOM ポートを構成するために、DPCOMPORTADDRESS 構造体 (DPAID_ComPort) にデータを代入する必要がある。

IDirectPlayLobby3::CreateCompoundAddress メソッドを使用して、DirectPlay アドレス を作成する。渡す必要のあるアドレス要素は、サービス プロバイダ GUID (DPAID_ServiceProvider) と、選択されたサービス プロバイダの個別のアドレス コンポーネントである。

DirectPlay アドレス を使用して InitializeConnection を呼び出し、DirectPlay オブジェクトを初期化する。

DPENUMSESSIONS_RETURNSTATUS フラグを設定して EnumSessions を呼び出す。これにより、あらゆるステータス ダイアログ ボックスが表示されなくなる。接続をすぐに実行できない場合、EnumSessions は DPERR_CONNECTING エラーを返す。アプリケーションでは、DP_OK が返される (列挙に成功したことを意味する) か、またはその他のエラーが返される (呼び出しに失敗したことを意味する) まで、EnumSessions を定期的に呼び出す必要がある。

Open メソッドで DPOPEN_CREATE を使用してセッションを作成する場合は、DPOPEN_RETURNSTATUS フラグも指定する。DPENUMSESSIONS_RETURNSTATUS と同じく、このフラグによってステータス ダイアログ ボックスが隠蔽され、関数が完了するまで DPERR_CONNECTING が返される。

注 : 場合によっては、アプリケーションで実行時にサービス プロバイダを問い合わせて、特定の DirectPlay アドレス 要素に対する有効な選択肢のリストを取得しなければならない場合もある。たとえば、システムにインストールされているモデムのリストを取得する場合などである。この場合、アプリケーションでは別の DirectPlay オブジェクトを作成し、モデム サービス プロバイダを初期化してから、DirectPlay ID にゼロを設定して IDirectPlay4::GetPlayerAddress を呼び出し、モデムのリストを保持する DirectPlay アドレス を取得する必要がある。DirectPlay オブジェクトを解放したら、IDirectPlayLobby3::EnumAddress を使ってアドレスを解析し、モデム リストを抽出してユーザーに提示する必要がある。


チュートリアル 4 : 自動リフレッシュ式セッション リストの作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションでは、IDirectPlay4::EnumSessions を非同期的に呼び出して、自動リフレッシュ式のセッション リストを維持することができる。この方法は、Bellhop、DPChat、DPSlots、Duel、および Override の 5 つの DirectPlay サンプルで利用されている。これらのサンプル アプリケーションのコード例は、いずれも参照可能である。

自動リフレッシュ式のセッション リストを作成するためのステップは、次のとおりである。

  1. IDirectPlay4::EnumSessions を呼び出す。このとき、DPENUMSESSIONS_ASYNC フラグを設定し、タイムアウトをゼロに設定する (これにより、サービス プロバイダのデフォルト値が使用される)。このメソッドはセッションを列挙せず、直ちに戻る。しかし、DirectPlay はバックグラウンドでセッションを列挙している。
  2. すべてのセッションを表示するユーザー インターフェイスを表示する。セッション リストのリフレッシュを実行する間隔に応じて、タイマを設定する。アプリケーションで列挙のデフォルトのタイムアウト間隔を確認するには、IDirectPlay4::GetCaps を呼び出す。
  3. タイマが開始するたびに、EnumSessions を呼び出して現在のセッション リストを取得する。このリストは、アクティブなセッションの完全なリストである。古いセッションは削除され、新しいセッションは追加され、既存のセッションは更新されている。EnumSessions を呼び出す前にリストからすべての項目を削除し、EnumSessionsCallback2 関数によってリストにセッションを再度追加する。
  4. DPERR_CONNECTING 以外のエラーが返された場合は、EnumSessions によって返されたエラー結果を確認し、タイマを停止する。これによりユーザーは、接続を解除したり、キャンセルしたりすることができるようになる。


DirectPlay Visual Basic チュートリアル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここでは、次のチュートリアルを使って、Visual Basic アプリケーションに DirectPlay を実装する方法を説明する。

  • チュートリアル 1 : 簡単なネットワーク ゲームの作成
  • チュートリアル 2 : ロビーによる開始のサポート


チュートリアル 1 : 簡単なネットワーク ゲームの作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、DirectX for Visual Basic を使用して DirectPlay アプリケーションを記述するために不可欠な手順について説明する。サンプル コードは、Memory サンプル アプリケーションに基づいている。

このチュートリアルは、次のステップで構成されている。

  • ステップ 1 : DirectPlay の初期化とプロバイダの列挙
  • ステップ 2 : 接続の初期化とセッションの列挙
  • ステップ 3 : セッションの作成またはセッションへの参加
  • ステップ 4 : プレーヤーの作成
  • ステップ 5 : ゲームの開始とメッセージの交換


ステップ 1 : DirectPlay の初期化とプロバイダの列挙

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C/C++ チュートリアル」を参照すること。

[Visual Basic]

アプリケーションで DirectPlay を実装するための最初のステップは、DirectPlay4 オブジェクトを作成し、利用可能な接続またはサービス プロバイダを列挙することである。Memory サンプルでは、いくつかのグローバル宣言の後で、InitDPlay プロシージャ内で次の手順を実行している。

Public gObjDX As New DirectX7
Public gObjDPlay As DirectPlay4
Public gObjEnumConnections As DirectPlayEnumConnections

Public Sub InitDPlay()

  On Error GoTo FAILED
  Set gObjDPlay = gObjDX.DirectPlayCreate("")
  Set gObjEnumConnections = gObjDPlay.GetDPEnumConnections( _
          "", DPCONNECTION_DIRECTPLAY)
  Exit Sub

FAILED:
  MsgBox ("Failed to initialize DirectPlay.")
  End
End Sub

DirectPlay4.GetDPEnumConnections を呼び出して、サービス プロバイダのコレクションを作成する。guid パラメータには、空の文字列を渡す。アプリケーション専用に設計されたサービス プロバイダを検索する場合に限り、アプリケーションの GUID を渡す。DP_CONNECTION_DIRECTPLAY フラグは、このアプリケーションでロビー プロバイダを使用しないことを示す。

InitDPlay プロシージャは、InitConnectionList 関数から呼び出される。その後、この関数は、利用可能なサービス プロバイダをリスト ボックスに代入する。この関数全体は、次のようになっている。

Public Function InitConnectionList() As Boolean

  Dim NumConnections As Long
  Dim strName As String
  Dim X As Long

  Call InitDPlay     ' 失敗したら、プログラムを中断する。

  lstConnections.Clear

  On Error GoTo FAILED
  NumConnections = gObjEnumConnections.GetCount
  For X = 1 To NumConnections
    strName = gObjEnumConnections.GetName(X)
    Call lstConnections.AddItem(strName)
  Next X

  ' 選択肢を初期化する。
  lstConnections.ListIndex = 0
  InitConnectionList = True
  Exit Function

  ' エラー ハンドラ。
FAILED:
  InitConnectionList = False
  Exit Function

End Function

DirectPlayEnumConnections コレクションは、1 から始まる。これは、DirectX for Visual Basic のほかの列挙されたコレクションでも同じである。

次項 : ステップ 2 : 接続の初期化とセッションの列挙


ステップ 2 : 接続の初期化とセッションの列挙

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C/C++ チュートリアル」を参照すること。

[Visual Basic]

ユーザーが [Multiple Player] ダイアログ ボックスでサービス プロバイダとプレーヤー名を選択し、[OK] をクリックすると、Memory アプリケーションは選択された接続を初期化する。DirectPlay4.InitializeConnection は接続を DirectPlay にバインドし、以降のメソッド呼び出しがその接続に対して行われるようにする。ただし、物理接続を確立するわけではない。物理接続は、セッションが列挙されたときに確立される。

この接続上でセッションの列挙を試みると、サービス プロバイダによっては (モデム サービス プロバイダなど)、物理接続を確立するための追加情報を要求するダイアログ ボックスが表示される場合がある。ユーザーは、既存のゲームに参加するのではなく、新しいゲームを作成する場合は、これらのダイアログ ボックスをキャンセルすることができる。

Memory では、ユーザーが既存のセッションを表示するつもりがなく、新しいセッションを直接作成したい場合でも、セッションが列挙される。実際のアプリケーションでは、この動作を変更し、ユーザーが既存のセッションのリストを要求した場合以外は、DirectPlay4.GetDPEnumSessions を呼び出さないようにしてもよい。このメソッドを呼び出さないと、場合によってはユーザーに対する処理を簡素化することができる。たとえば、モデム サービス プロバイダには、2 つの異なるダイアログ ボックスがある。1 つはダイヤル用で、もう 1 つは応答用である。新しいゲームを作成するプレーヤーには、ダイヤル用のプロンプトは不要である。これは、モデム ゲームのホストは、常にほかのプレーヤーからの呼び出しを待機するものだからである。セッションの列挙を省略して DirectPlay4.Open を呼び出すと、ホストにダイヤル用のプロンプトが表示されなくなる。

frmMultiplayer 内の以下のプロシージャは、選択された接続を初期化して、次のダイアログ ボックスに表示されるリスト ボックスに利用可能なセッションを代入する。

Private Sub cmdOK_Click()

  Dim CIndex As Long
  Dim ConnectionMade As Boolean
  Dim objDPAddress As DirectPlayAddress

  CIndex = lstConnections.ListIndex + 1

列挙されたコレクションは 1 から始まるが、リスト ボックス内のリストは 0 から始まる。そのため、コレクションのインデックスを調整する必要がある。

ここで、アプリケーションは接続の DirectPlay アドレスを取得し、それを初期化する。
  On Error GoTo INITIALIZEFAILED
  Set objDPAddress = gObjEnumConnections.GetAddress(CIndex)
  Call gObjDPlay.InitializeConnection(objDPAddress)
  On Error GoTo 0

次の呼び出しについては、後で詳しく説明する。

  ConnectionMade = frmSessions.UpdateSessionList

フォームが閉じ、新しいフォームが表示される。このフォームには、セッションのリストと、セッションへの参加または作成を許可するボタンが表示されている。

  If ConnectionMade Then
    Hide
    frmSessions.Show
  Else
    InitDPlay
  End If
  Exit Sub
  ' エラー ハンドラ。

INITIALIZEFAILED:
  If Err.Number <> DPERR_ALREADYINITIALIZED Then
    MsgBox ("Failed to initialize connection.")
    Exit Sub
  End If

End Sub

セッションの列挙は以下の関数で実行する。この関数は、新しいセッションが利用可能になったり、古いセッションが削除されたときに、セッションのリストを更新するためにも利用される。

Public Function UpdateSessionList() As Boolean

  Dim SessionCount As Integer
  Dim X As Integer
  Dim SessionData As DirectPlaySessionData
  Dim Details As String

  ' 古いリストを削除する。
  lstSessions.Clear

  Set SessionData = gObjDPlay.CreateSessionData

DirectPlaySessionData オブジェクトは、列挙するセッションを記述する。Memory では、ほかのアプリケーションのセッションを利用しないので、独自に定義したアプリケーション GUID を (文字列の形式で) 指定する。特定のパスワードを備えるセッションだけを列挙できるようにする場合は、ここでセッション記述にパスワードも設定する。

  Call SessionData.SetGuidApplication(AppGuid)
  Call SessionData.SetSessionPassword("")

DirectPlay4.GetDPEnumSessions を呼び出すと、利用可能なセッションだけが必要であるということが指定される。これには、プレーヤーの最大人数に達していなければ参加できないセッションは含まれない。

  On Error GoTo USERCANCEL
  Set gObjDPEnumSessions = gObjDPlay.GetDPEnumSessions(SessionData, _
          0, DPENUMSESSIONS_AVAILABLE)
  On Error GoTo 0

このメソッドは、ユーザーがサービス プロバイダのダイアログ ボックスをキャンセルした場合には失敗する。その場合、アプリケーションでは、プレーヤーが新しいセッションを作成しようとしていると想定する。したがって、これを致命的なエラーとは見なさない。

列挙に成功すると、アプリケーションは DirectPlayEnumSessions オブジェクトを使用して、各セッションに関する情報を取得する。これには、セッションの名前、現在のプレーヤー数、最大プレーヤー数などが含まれる。これらの情報を組み合わせて文字列を作成し、その文字列をリスト ボックスに表示する。

  On Error GoTo ENUM_ERROR
  SessionCount = gObjDPEnumSessions.GetCount
  For X = 1 To SessionCount
    Set SessionData = gObjDPEnumSessions.GetItem(X)
    Details = SessionData.GetSessionName & " (" _
            & SessionData.GetCurrentPlayers _
            & "/" & SessionData.GetMaxPlayers & ")"
    Call lstSessions.AddItem(Details)
  Next X

ここでは省略するが、この関数の以降の部分では、インターフェイスを更新し、エラーを処理する。

次項 : ステップ 3 : セッションの作成またはセッションへの参加


ステップ 3 : セッションの作成またはセッションへの参加

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C/C++ チュートリアル」を参照すること。

[Visual Basic]

ユーザーは、Memory サンプルの frmSessions フォームで、一覧に表示されたセッションに参加するか、または新しいセッションを作成するかを選択する。

いずれの場合も、手続きは同じである。セッションを DirectPlaySessionData オブジェクトに記述し、そのオブジェクトを DirectPlay4.Open に渡す。

以下のコードは、frmCreateGame の cmdCreate_Click メソッドから抜粋したものである。このコードでは、2 ～ 4 人までのプレーヤーを受け入れる新しいゲームを作成する。プレーヤーの数は、オプション ボタンによって指定される。

Dim SessionData As DirectPlaySessionData

Set SessionData = gObjDPlay.CreateSessionData
.
.
.
  ' プレーヤー数を設定する。
If Option1.Value = True Then
    Call SessionData.SetMaxPlayers(2)
ElseIf Option2.Value = True Then
    Call SessionData.SetMaxPlayers(3)
Else
    Call SessionData.SetMaxPlayers(4)
End If

' セッションの記述を終了する。
Call SessionData.SetSessionName(txtGameName.Text)
Call SessionData.SetGuidApplication(AppGuid)
Call SessionData.SetFlags(DPSESSION_MIGRATEHOST)

' セッションを作成 (および参加) する。
' ユーザーがサービス プロバイダのダイアログ ボックスを
' キャンセルした場合は、失敗する。モデムの場合は、
' これが "答え" である。

  On Error GoTo FAILEDOPEN
  Call gObjDPlay.Open(SessionData, DPOPEN_CREATE)
.
.
.
End Sub

セッションに参加する場合は、処理が若干簡単になる。これは、frmSessions の cmdJoin_Click のように、列挙からセッション記述を取得するだけでよいからである。

Dim SessionData As DirectPlaySessionData

Set SessionData = gObjDPEnumSessions.GetItem( _
        lstSessions.ListIndex + 1)
On Error GoTo NOSESSION
Call gObjDPlay.Open(SessionData, DPOPEN_JOIN)

次項 : ステップ 4 : プレーヤーの作成


ステップ 4 : プレーヤーの作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C/C++ チュートリアル」を参照すること。

[Visual Basic]

これで、アプリケーションはオープン セッションの一部になった。しかし、ユーザーは、プレーヤーを作成するまでは、参加することができない。

この手順はきわめて簡単である。DirectPlay4.CreatePlayer にいくつかの名前を渡すと、プレーヤーに対する一意の ID が返される。この ID は、メッセージでプレーヤーを識別するものなので、重要である。Memory では、この ID をグローバル変数 gMyPlayerID に保持する。

Memory サンプルでは、PlayerName 文字列 が、ユーザーによって提供される名前である (デフォルトの文字列は、システムによる Win32 の GetUserName の呼び出しによって取得される)。アプリケーションでは、この名前を、プレーヤーに対するフレンドリ名として使用する。PlayerHandle をほかの目的で内部的に使用することも可能だが、Memory では不要である。

PlayerName = frmMultiplayer.txtYourName.Text
PlayerHandle = "Player"

On Error GoTo FAILEDCREATE
gMyPlayerID = gObjDPlay.CreatePlayer(PlayerName, PlayerHandle, 0, 0)

次項 : ステップ 5 : ゲームの開始とメッセージの交換


ステップ 5 : ゲームの開始とメッセージの交換

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectPlay は、最低 1 人のプレーヤーがセッションに参加すると、直ちにメッセージの送信を開始する。プレーヤーがセッションに参加したり、セッションから離れたりするたびに、システム メッセージが送信される。Memory サンプルでは、このメッセージをきっかけとして、frmWaiting 内のプレーヤーのリストが更新される。

ゲーム (またはほかの形式の DirectPlay セッション) をどのように開始するかは、アプリケーション次第である。DirectPlay から見ると、アプリケーションがメッセージを送信してゲームの状態を更新していようがいまいが、セッションはセッションである。

Memory サンプルでは、最低 1 人のプレーヤーが参加したときに、ホストがセッションを開始できる。ホストが [Start] ボタンをクリックしたら、ますセッションへの参加を不可能にし、新しいユーザーがそのセッションを利用できないようにする。

Set SessionData = gObjDPlay.CreateSessionData
Call gObjDPlay.GetSessionDesc(SessionData)
Call SessionData.SetFlags(SessionData.GetFlags + _
        DPSESSION_JOINDISABLED)
Call gObjDPlay.SetSessionDesc(SessionData)

次に、タイプ識別子、プレイする順番に従ったプレーヤー ID のリスト、およびゲーム ボードのタイルの配置を含むメッセージを作成する。このメッセージに応答して、アプリケーションのほかのインスタンスが、プレーヤーの順番とゲーム ボードに関する情報を更新する。このメッセージは、プレーヤーがゲームの状態に関する情報を交換する方法の一例を示している。

まず、DirectPlayMessage のさまざまな書き込みメソッドを使用して、データをメッセージに組み込む。

Dim dpMsg As DirectPlayMessage

Set dpMsg = gObjDPlay.CreateMessage

' メッセージ タイプを組み込む。
Call dpMsg.WriteLong(MSG_SETUPBOARD)

' プレーヤーの数を組み込む。
Call dpMsg.WriteByte(gNumPlayers)

' プレーヤー ID を組み込む。
Dim PlayerID As Long
For X = 0 To gNumPlayers - 1
    PlayerID = objDPEnumPlayers.GetDPID(X + 1)
    dpMsg.WriteLong (PlayerID)
    ' プレーヤー ID のローカル コピーを保持する。
    gPlayerIDs(X) = PlayerID
    ' プレイの順番をホストに割り当てる。
    If PlayerID = gMyPlayerID Then gMyTurn = X
Next X

' タイルの配置を組み込む。
For X = 0 To NumCells - 1
    dpMsg.WriteByte (gPicArray(X))
Next X

ホストのアプリケーション インスタンスは、ここで自らのゲーム状態を更新する必要がある。アプリケーションのインスタンスは、ホストが送信したメッセージを受信しない。そのため、ホストにとっては、ここがほかのインスタンスがメッセージを受信したときに実行する更新を実行する最後のチャンスである。

次に、DPSEND_GUARANTEED フラグを使用して、このメッセージをほかのすべてのプレーヤーに送信する。このフラグを設定するのは、ほかのすべてのプレーヤーがこの情報を受信する必要があるからである (動きの速いアクション ゲームでわずかな変更を通知する場合は、保証なしのメッセージで十分である)。

Call gObjDPlay.Send(gMyPlayerID, DPID_ALLPLAYERS, _
        DPSEND_GUARANTEED, dpMsg)

受信側では、Sub Main プロシージャでメッセージを検索する。このとき、DoEvents を使用して、問い合わせ中にほかの処理を実行できるようにする。

Do While DoEvents()
    GetDPMessages
Loop

GetDPMessages プロシージャでは、保留になっているメッセージの数を確認する。

Dim MsgCount As Long
MsgCount = gObjDPlay.GetMessageCount(gMyPlayerID)

次に、各メッセージを取得し、それを DirectPlayMessage オブジェクトの dpMsg に代入する。さらに、メッセージのタイプを取得する。これは、システム メッセージの場合も、Memory で定義されるメッセージの場合も、常に最初の Long 値である。

Dim FromPlayerID As Long
Dim ToPlayerID As Long
Dim dpMsg As DirectPlayMessage
Dim MsgType As Long
' 一部の宣言については省略する。GlobalModule.bas を参照すること。
.
.
.
Do While MsgCount > 0
    Set dpMsg = gObjDPlay.Receive(FromPlayerID, ToPlayerID, _
            DPRECEIVE_ALL)
    MsgType = dpMsg.ReadLong()

    MsgCount = MsgCount - 1

システム メッセージの場合、FromPlayerID は DPSYS_MESSAGE である。それ以外は、すべてアプリケーション定義のメッセージである。Memory は、MSG_SETUPBOARD というタイプのアプリケーション定義を見つけると、データを組み込まれている順番で読み取り、いくつかの追加処理を実行してゲーム状態を更新し、プレイを開始できるようにする。

    Select Case MsgType

        Case MSG_SETUPBOARD

          ' プレーヤーの数。
          gNumPlayers = dpMsg.ReadByte

          ' プレイ順のプレーヤー ID。使用されていないプレーヤーの ID は 0。
          For X = 0 To gNumPlayers - 1
              gPlayerIDs(X) = dpMsg.ReadLong
              If gPlayerIDs(X) = gMyPlayerID Then gMyTurn = X
          Next X

          ' タイルの配置。
          For X = 0 To NumCells - 1
              gPicArray(X) = dpMsg.ReadByte
          Next X

          ' ゲーム ボードを表示する。
          frmWaiting.Hide
          gGameUnderway = True
          frmGameBoard.Show
.
.
.
    End Select
.
.
.
Loop


チュートリアル 2 : ロビーによる開始のサポート

このチュートリアルでは、アプリケーションでロビーによる外部からの開始と、ロビーにより開始されたセッションへの接続をサポートする方法を示す。これらのテクニックを使用しているアプリケーションは、ロビーまたはユーザーから起動することができ、ロビーで作成されたアプリケーション セッションに自動的に参加する。

これらのトピックの概要については、「ロビー対応アプリケーションの作成」を参照すること。

このチュートリアルは、次のステップで構成されている。

  • ステップ 1 : アプリケーションの登録
  • ステップ 2 : 接続設定の取得
  • ステップ 3 : セッションへの参加

このサンプル コードは、Chat サンプルに基づいている。


ステップ 1 : アプリケーションの登録

ロビー クライアントからアプリケーションを認識できるようにするには、アプリケーションを登録する必要がある。ロビー対応アプリケーションを登録するには、DirectSetupの DirectXRegisterApplication C/C++ 関数を使用するか、DirectPlayLobby3.RegisterApplication メソッドを使用する独自の登録ユーティリティを提供する。以下のサンプル プロシージャは、DXVBChat.exe を登録する。このとき、DXVBChat.exe は登録を行うアプリケーションと同じフォルダになければならない。

Dim dx As New DirectX7
Dim dpl As DirectPlayLobby3
Const AppGuid = "{EB5E7E20-0303-11d3-9AAB-00104BCC1EAA}"

Private Sub RegisterApp()

  Dim dpappdesc As DPAPPLICATIONDESC2
  Dim dpl as DirectPlayLobby3

  With dpappdesc
    .strApplicationName = "DXVBChat"
    .strCommandLine = ""
    .strCurrentDirectory = App.Path
    .strDescription = "Chat (DirectX for Visual Basic)"
    .strFilename = "DXVBChat.exe"
    .strGuid = AppGuid
    .strPath = App.Path
  End With

  On Local Error GoTo ERRORS

  Set dpl = dx.DirectPlayLobbyCreate
  Call dpl.RegisterApplication(dpappdesc)
  Exit Sub

ERRORS:
  MsgBox "Failed to register application."
  Unload Me

End Sub

以下のプロシージャは、同じアプリケーションの登録を解除する。

Private Sub UnregisterApp()

  On Local Error GoTo FAILED
  Call dpl.UnregisterApplication(AppGuid)
  MsgBox "Unregistration successful."
  Exit Sub

FAILED:
  If Err.Number = DPERR_UNKNOWNAPPLICATION Then
    MsgBox "Application not registered."
  End If
  Unload Me

End Sub

次項 : ステップ 2 : 接続設定の取得


ステップ 2 : 接続設定の取得

このステップでは、アプリケーションで DirectPlay を初期化し、アプリケーションがロビーによって開始されているかどうかを判断する。ロビーによって開始されている場合は、直ちに接続設定を取得する。そうでない場合は、接続設定を待機する。

最初に、DirectPlayLobby3 オブジェクトを作成する。それには、初期化された DirectX7 オブジェクトの objDX を使用する。

Public Function InitDPlay() As Boolean

  InitDPlay = True

  On Local Error GoTo FAILED
  Set objDPLobby = objDX.DirectPlayLobbyCreate

次に、DirectPlayLobby3.GetConnectionSettings を呼び出す。アプリケーションが、ロビー クライアント内での DirectPlayLobby3.RunApplication の呼び出しに応答して開始されている場合、GetConnectionSettings は成功する。そうでない場合は、DPERR_NOTLOBBIED が返される。

  On Local Error Resume Next
  Set objDPLConnection = objDPLobby.GetConnectionSettings(0)

  ' アプリケーションはロビーによって開始された。
  If Err.Number = 0 Then GoTo GOTCONNECTION

アプリケーションがロビーによって起動されていない場合は、この時点でユーザーに対して、シングルプレーヤー ゲームを開始するか、内部ロビー クライアントを介してセッションに接続するかを選択させることもできる。サンプル アプリケーションでは、ロビー接続を待機する方法を採用している。まず、DirectPlayLobby3.WaitForConnectionSettings. を呼び出して、待機モードに入る。これにより、ユーザーがロビー クライアントでアプリケーション セッションを作成したり、またはアプリケーション セッションに参加したりしたときに、RunApplication によってアプリケーションの別のインスタンスが実行されなくなる。代わりに、このインスタンスで接続設定を利用できるようになる。

  On Local Error GoTo FAILED
  Call objDPLobby.WaitForConnectionSettings(DPLWAIT_DEFAULT)

ここで、サンプル アプリケーションはダイアログ ボックスを表示する。このダイアログ ボックスは、接続が確立されるか、またはユーザーがキャンセルするまで、アクティブなままになっている。

  frmWaiting.Show
  Call WaitForConnectionMessage

アプリケーションが実際に待機するのは、この部分である。WaitForConnectionMessage 関数は、ロビーから DPLSYS_NEWCONNECTIONSETTINGS メッセージを受信するか、またはユーザーがキャンセルするまで、ブロックする。

Public Sub WaitForConnectionMessage()
  Dim msg As DirectPlayMessage
  Dim flags As Long
  Dim MsgType As Long

  On Local Error Resume Next
  gGotConnection = False
  Do While DoEvents
      Set msg = objDPLobby.ReceiveLobbyMessage(0, flags)
      If Not (msg Is Nothing) Then
        MsgType = msg.ReadLong
        If MsgType = DPLSYS_NEWCONNECTIONSETTINGS Then
          gGotConnection = True
          Exit Do
        End If
      End If
  Loop
  Exit Sub
End Sub

サンプル アプリケーションでは、ユーザーがダイアログ ボックスをキャンセルすると、FALSE が返される。これは、可視状態のフォームがほかに存在せず、DoEvents が FALSE を返すからである。可視状態のフォームがほかに存在するアプリケーションでは、ほかの方法を使用して、ユーザーがキャンセルを選択したときにループを抜ける必要がある。

呼び出し側のプロシージャでは、DPLSYS_NEWCONNECTIONSETTINGS を受け取ると、状態のダイアログ ボックスを閉じて、DirectPlayLobbyConnection オブジェクトを取得する。

  If gGotConnection Then
    frmWaiting.Hide
    Set objDPLConnection = objDPLobby.GetConnectionSettings(0)
  Else
    GoTo FAILED  ' ユーザーがキャンセルした。
  End If

次項 : ステップ 3 : セッションへの参加


ステップ 3 : セッションへの参加

ここで、2 つのコード ブランチ (ロビーによる開始と、ユーザーによる開始) が 1 つに集まる。プログラムでは、ロビーから接続設定を取得したので、アプリケーション セッションをローカルな DirectPlay4 オブジェクトに接続することができる。このオブジェクトは、以下では objDPlay と表されている。

GOTCONNECTION:
  On Local Error GoTo FAILED
  Set objDPlay = objDPLobby.Connect(0)

これで、アプリケーションはセッションに関して必要な情報を何でも取得し、接続データの情報に基づいてプレーヤーを作成できるようになった。

  ' 以下は、グローバルに宣言される。
  ' Dim objDPSessionData as DirectPlaySessionData
  ' Dim gMyPlayerName As String
  ' Dim gMyPlayerID As Long

  Set objDPSessionData = objDPLConnection.GetSessionDesc
  ' セッション データには、セッションの名前、プレーヤーの数などが
  ' 含まれている。これらはすべて、ステージング領域で設定されている。

  gMyPlayerName = objDPLConnection.GetPlayerShortName
  gMyPlayerID = objDPlay.CreatePlayer(gMyPlayerName, "PLAYER", _
          0, DPPLAYER_DEFAULT)
  Exit Function

これで、プレーヤーがメッセージの送受信を開始するために必要な準備が整った。

処理がうまくいかなかった場合は、エラー ハンドラによって InitDPlay の戻り値を FALSE に設定する。これで、アプリケーションをすみやかに終了できるようになる。

FAILED:
  InitDPlay = False

End Function


DirectPlay リファレンス

ここでは、DirectPlay® が提供する C/C++ と Visual Basic® のアプリケーション プログラミング インターフェイス (API) 要素についてのリファレンス情報を示す。リファレンスは言語別に編成されている。

  • DirectPlay C/C++ リファレンス
  • DirectPlay Visual Basic リファレンス


DirectPlay C/C++ リファレンス

DirectPlay C/C++ アプリケーション プログラミング インターフェイスのリファレンスは、次のように分類される。

  • インターフェイス
  • 関数
  • コールバック関数
  • 構造体
  • システム メッセージ
  • 標準ロビー メッセージ
  • DirectPlay 定義済みプロパティ
  • 戻り値


インターフェイス

ここでは、DirectPlay の次のインターフェイスのメソッドに関するリファレンスを示す。

  • IDirectPlay4
  • IDirectPlayLobby3


IDirectPlay4

アプリケーションでは、IDirectPlay4 インターフェイスのメソッドを使用して DirectPlay オブジェクトを作成し、システム レベル変数を使用する (IDirectPlay4A インターフェイスは、IDirectPlay4 インターフェイスと同じである。ただし、IDirectPlay4A では ANSI 文字を使用し、IDirectPlay4 では Unicode を使用する)。

IDirectPlay4 インターフェイスのメソッドは、次のように分類できる。

セッション管理 | Close
 | EnumConnections
 | EnumSessions
 | GetCaps
 | GetGroupConnectionSettings
 | GetSessionDesc
 | InitializeConnection
 | Open
 | SecureOpen
 | SetGroupConnectionSettings
 | SetSessionDesc
 | StartSession
プレーヤー管理 | CreatePlayer
 | DestroyPlayer
 | EnumPlayers
 | GetPlayerAccount
 | GetPlayerAddress
 | GetPlayerCaps
 | GetPlayerData
 | GetPlayerFlags
 | GetPlayerName
 | SetPlayerData
 | SetPlayerName
メッセージ管理 | CancelMessage
 | CancelPriority
 | GetMessageCount
 | GetMessageQueue
 | Receive
 | Send
 | SendChatMessage
 | SendEx
グループ管理 | AddGroupToGroup
 | AddPlayerToGroup
 | CreateGroup
 | CreateGroupInGroup
 | DeleteGroupFromGroup
 | DeletePlayerFromGroup
 | DestroyGroup
 | EnumGroupPlayers
 | EnumGroups
 | EnumGroupsInGroup
 | GetGroupData
 | GetGroupFlags
 | GetGroupName
 | GetGroupOwner
 | GetGroupParent
 | SetGroupData
 | SetGroupName
 | SetGroupOwner
初期化 | Initialize

IDirectPlay4 インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスは、次の 3 つのメソッドをサポートしている。

IUnknown | AddRef
 | QueryInterface
 | Release

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。


IDirectPlay4::AddGroupToGroup

IDirectPlay4::AddGroupToGroup メソッドは、あるグループへのショートカットを既存のグループに追加する。これにより、リンクしたグループを IDirectPlay4::EnumGroupsInGroup メソッドで列挙することが可能になる。グループのショートカットを別のグループから削除するには、DeleteGroupFromGroup を呼び出す。

HRESULT AddGroupToGroup(
  DPID idParentGroup,
  DPID idGroup
);

パラメータ

idParentGroup
ショートカットの追加先グループのグループ ID。有効な任意のグループ ID を指定可能。
idGroup
ショートカットを追加するグループのグループ ID。有効な任意のグループ ID を指定可能。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP

注意

このメソッドを使用して、あるグループを複数のグループ「内」に配置できる。

この変更をプレーヤーに知らせるために、DPMSG_ADDGROUPTOGROUP システム メッセージが生成される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreateGroupInGroup、IDirectPlay4::DeleteGroupFromGroup、IDirectPlay4::EnumGroupsInGroup、DPMSG_ADDGROUPTOGROUP


IDirectPlay4::AddPlayerToGroup

IDirectPlay4::AddPlayerToGroup メソッドは、プレーヤーを既存のグループに追加する。プレーヤーは、複数のグループのメンバになることができる。この API を使用して、グループを別のグループに追加することはできない (IDirectPlay4::AddGroupToGroup を参照)。アプリケーションでは、任意のプレーヤーを任意のグループに追加できる (ローカルに作成されていないプレーヤーおよびグループを含む)。

HRESULT AddPlayerToGroup(
  DPID idGroup,
  DPID idPlayer
);

パラメータ

idGroup
追加するグループのグループ ID。
idPlayer
グループに追加するプレーヤーのプレーヤー ID。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_NOSESSIONS

idPlayer がプレーヤー ID でない場合、または ID がローカル プレーヤーのものでない場合は、DPERR_INVALIDPLAYER を返す。

注意

DPMSG_ADDPLAYERTOGROUP システム メッセージが作成され、その他のすべてのプレーヤーに送信される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreateGroup、IDirectPlay4::DeletePlayerFromGroup、DPMSG_ADDPLAYERTOGROUP


IDirectPlay4::CancelMessage

IDirectPlay4::CancelMessage メソッドは、送信キューにまだ残っている特定のメッセージ (またはすべてのメッセージ) を取り消す。CancelMessage は、非同期メッセージにのみ適用される。

特定のメッセージを取り消すためには、アプリケーションで IDirectPlay4::SendEx メソッドにより返されるメッセージ ID を取得して保存する必要がある。

メッセージ キューに残っているものの、一部が既に送信されているメッセージについては、取り消すことができない。グループに送信されるメッセージは、グループの一部のメンバに既に送信されていると取り消すことができない。

メッセージを取り消しても、その旨を示す DPMSG_SENDCOMPLETE システム メッセージは生成される。

HRESULT CancelMessage(
  DWORD dwMsgID,
  DWORD dwFlags
);

パラメータ

dwMsgID
取り消す特定のメッセージの ID。この ID は、IDirectPlay4::SendEx を使用してメッセージを送信すると返される。すべてのメッセージを取り消す場合は 0 を指定する。
dwFlags
このパラメータは将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CANCELFAILED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNKNOWNMESSAGE
DPERR_UNSUPPORTED

メッセージを取り消すことができなかった場合は、DPERR_CANCELFAILED を返す。また、取り消すメッセージの ID が無効な場合は、DPERR_UNKNOWNMESSAGE を返す。送信キューにメッセージがなかった場合は、DP_OK を返す。

注意

DirectPlay プロトコルがセッション記述で指定されている場合、CancelMessage のすべてのオプションを使用できる。それ以外の場合、アプリケーションでは サービス プロバイダにより実装されているオプションを判定するために、GetCaps を呼び出す必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::SendEx、IDirectPlay4::Send、IDirectPlay4::GetMessageQueue、DPMSG_SENDCOMPLETE、IDirectPlay4::CancelPriority


IDirectPlay4::CancelPriority

IDirectPlay4::CancelPriority メソッドは、まだ送信キューに入っている特定の、または特定範囲の優先順位のメッセージを、すべて取り消すときに使用する。CancelPriority は、非同期メッセージにのみ適用される。

メッセージ キューに残っているものの、一部が既に送信されているメッセージについては、取り消すことはできない。グループに送信されるメッセージで、そのグループの一部に既に送信されている場合は取り消すことができない。

メッセージを取り消しても、メッセージが取り消されたことを示す DPMSG_SENDCOMPLETE システム メッセージは生成される。

HRESULT CancelPriority(
  DWORD dwMinPriority,
  DWORD dwMaxPriority,
  DWORD dwFlags
);

パラメータ

dwMinPriority
取り消す優先順位の範囲で、最も低い優先順位。
dwMaxPriority
取り消す優先順位の範囲で、最も高い優先順位。dwMinPriority よりも高くなければならない。可能な最高優先順位の MAXPRIORITY を設定する。
dwFlags
このパラメータは将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED

送信キューにメッセージがまったくない場合は、DP_OK を返す。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::SendEx、IDirectPlay4::Send、IDirectPlay4::GetMessageQueue、DPMSG_SENDCOMPLETE、IDirectPlay4::CancelMessage


IDirectPlay4::Close

IDirectPlay4::Close メソッドは、前に開いたセッションを閉じる。ローカルに作成されたグループは、セッションのホストによって所有されるようになる。

HRESULT Close( );

パラメータ

なし。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

注意

ローカルに作成されたプレーヤーはすべて破棄され、ほかのセッション参加者には適切な DPMSG_DELETEPLAYERFROMGROUP システム メッセージと DPMSG_DESTROYPLAYERORGROUP システム メッセージが送信される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::DestroyPlayer、DPMSG_DESTROYPLAYERORGROUP、IDirectPlay4::Open


IDirectPlay4::CreateGroup

IDirectPlay4::CreateGroup メソッドは、カレント セッション内でグループを作成する。グループとは、プレーヤーまたはその他のグループの論理的な集合である。

HRESULT CreateGroup(
  LPDPID lpidGroup,
  LPDPNAME lpGroupName,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

パラメータ

lpidGroup
DirectPlay グループ ID が設定される変数へのポインタ。この値は、DirectPlay により定義される。
lpGroupName
グループの名前が設定されている DPNAME 構造体へのポインタ。NULL が設定されている場合は、グループに初期設定名がないことを示す。lpGroupName の名前はユーザーが使用するためだけに設定する。システム内では使用されないので、一意でなくてもかまわない。
lpData
システム内でグループ ID に関連付けるアプリケーションにより定義されたリモート データのブロックへのポインタ。NULL が設定されている場合は、グループに初期設定名がないことを示す。ここで指定したデータは、IDirectPlay4::SetGroupData が呼び出された場合と同じように、セッション内のその他すべてのアプリケーションに伝播されるリモート データであると見なされる。
dwDataSize
lpData が示すデータ ブロックのサイズ (バイト単位)。
dwFlags
作成するグループのタイプを示すフラグ。デフォルト (dwFlags = 0) では、グループの所有権は所有者がセッションを離れた時点でホストに移行し、グループは明示的に破棄されるまで存続する。

設定可能な値は、次のいずれかである。

DPGROUP_HIDDEN
隠しフラグによりグループを作成する。グループが列挙されると、隠しフラグが設定される。ロビー セッションでは、隠しグループは IDirectPlay4::AddGroupToGroup により作成されたショートカットからのみ使用できる。このフラグは、プレーヤーにとって DPPLAYER_SPECTATOR フラグと同じように機能する。
DPGROUP_STAGINGAREA
グループをステージング領域として作成する。ステージング領域は、新しいセッションを起動するためにプレーヤーを整列するときに使用する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

注意

グループがクライアント／サーバー セッションで作成された場合、グループ通知メッセージは送信されない。グループは、マシンがクライアントであるかホストであるかに関係なく、そのグループを作成したマシンでしか表示できない。

グループがピアツーピア セッションで作成された場合、CreateGroup によりその他のすべてのプレーヤーに送信される DPMSG_CREATEPLAYERORGROUP システム メッセージが生成される。アプリケーションで IDirectPlay4::Send を使用すると、1 つのメッセージをグループ ID に送信するだけでそのグループ内のすべてのプレーヤーにメッセージを送信できる。DirectPlay は、マルチキャストを使用して、このメッセージを送信する (この機能がサービス プロバイダによりサポートされている場合) か、または各メッセージをグループ内の各プレーヤーに送信する。

メッセージの受け渡しやデータの関連付けでグループを識別するときは、アプリケーションに返されるグループ ID を使用する。DirectPlay により割り当てられたプレーヤー ID やグループ ID はセッション内で常に一意である。

CreateGroup により作成されるグループは、セッション内で最上位グループとなる。これらは、IDirectPlay4::EnumGroups により列挙される。IDirectPlay4::CreateGroupInGroup メソッドでは、親グループのサブグループとなるグループが作成される。

グループは、一般企業のアプリケーションでも使用できる。ロビー セッションでは、プレーヤーを収集するメカニズムとしてステージング領域を使用し、IDirectPlay4::StartSession を使用して新しいアプリケーション セッションを起動する。

グループを作成したプレーヤーが、そのデフォルトの所有者となる。名前やリモート データなどのグループ プロパティを変更できるのは、所有者だけである。所有者がセッションを抜けると、所有権はセッションのホストに移る。

セッション内のグループを認識しているプレーヤーであれば、グループのメンバを変更したり、グループを削除したりできる。

グループは、明示的に破棄されるまでセッション内に存続する。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPNAME、DPMSG_CREATEPLAYERORGROUP、IDirectPlay4::AddGroupToGroup、IDirectPlay4::DestroyGroup、IDirectPlay4::EnumGroups、IDirectPlay4::EnumGroupPlayers、IDirectPlay4::Send、IDirectPlay4::SetGroupData、IDirectPlay4::SetGroupName、IDirectPlay4::CreateGroupInGroup、IDirectPlay4::GetGroupFlags


IDirectPlay4::CreateGroupInGroup

IDirectPlay4::CreateGroupInGroup メソッドは、既存のグループ内にグループを作成する。別のグループ内に作成したグループを列挙できるのは、IDirectPlay4::EnumGroupsInGroup メソッドだけである。この方法で作成したグループを破棄するには、IDirectPlay4::DestroyGroup メソッドを呼び出す。

HRESULT CreateGroupInGroup(
  DPID idParentGroup,
  LPDPID lpidGroup,
  LPDPNAME lpGroupName,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

パラメータ

idParentGroup
グループの作成先グループの ID。このグループは既存のグループでなければならない。
lpidGroup
作成したグループの DirectPlay グループ ID を受け取る変数のアドレス。
lpGroupName
作成するグループの名前を保持している DPNAME 構造体へのポインタ。NULL が設定されている場合は、グループに初期設定名がないことを示す。
lpData
最初にグループ ID に関連付けるアプリケーションにより定義されたリモート データのブロックへのポインタ。NULL が設定されている場合は、グループに初期データがないことを示す。ここで指定したデータは、IDirectPlay4::SetGroupData が呼び出された場合と同じように、セッション内のその他すべてのアプリケーションに伝播されるリモート データであると見なされる。
dwDataSize
lpData パラメータのポイント先データ ブロックのサイズ (バイト単位)。
dwFlags
作成するグループのタイプを示すフラグ。デフォルト (dwFlags = 0) は、通常のグループである。
DPGROUP_HIDDEN
隠しフラグによりグループを作成する。グループが列挙されるとき、隠しフラグが設定される。ロビー セッションでは、隠しグループは IDirectPlay4::AddGroupToGroup により作成されたショートカットからのみ使用できる。
DPGROUP_STAGINGAREA
グループをステージング領域として作成する。ステージング領域は、IDirectPlay4::StartSession メソッドを使用して DirectPlay セッションを起動するときに使用する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

グループが作成できなかった場合は DPERR_CANTADDPLAYER を返す。また、親グループ ID が無効である場合は、DPERR_INVALIDGROUP を返す。

注意

グループがクライアント／サーバー セッションで作成された場合、グループ通知メッセージは送信されない。グループは、マシンがクライアントであるかホストであるかに関係なく、そのグループを作成したマシンでしか表示できない。

グループがピアツーピア セッションで作成された場合、CreateGroupInGroup により、この変更をプレーヤーに知らせるために DPMSG_CREATEPLAYERORGROUP システム メッセージが生成される。

最上位グループを破棄した場合、それに含まれるメンバ グループもすべて破棄され、破棄メッセージが送信される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::DestroyGroup、IDirectPlay4::EnumGroupsInGroup、DPMSG_CREATEPLAYERORGROUP


IDirectPlay4::CreatePlayer

IDirectPlay4::CreatePlayer メソッドは、カレント セッションにローカル プレーヤーを作成する。

HRESULT CreatePlayer(
  LPDPID lpidPlayer,
  LPDPNAME lpPlayerName,
  HANDLE hEvent,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

パラメータ

lpidPlayer
DirectPlay プレーヤー ID が設定される変数へのポインタ。この値は、DirectPlay により定義される。
lpPlayerName
プレーヤーの名前が設定されている DPNAME 構造体へのポインタ。NULL が設定されている場合は、プレーヤーに初期設定名がないことを示す。lpPlayerName の名前はユーザーが使用するためだけに設定する。システム内では使用されないので、一意でなくてもかまわない。
hEvent
プレーヤー宛てに設定されたメッセージが受信されたときに DirectPlay からその通知を受けたアプリケーションにより作成されるイベント オブジェクト。
lpData
プレーヤー ID に関連付けるアプリケーションにより定義されたデータのブロックへのポインタ。NULL が設定されている場合は、プレーヤーに初期データがないことを示す。ここで指定したデータは、IDirectPlay4::SetPlayerData が呼び出された場合と同じように、セッション内のその他すべてのアプリケーションに伝播されるリモート データであると見なされる。
dwDataSize
LpData パラメータのポイント先データ ブロックのサイズ (バイト単位)。
dwFlags
作成するプレーヤーのタイプを示すフラグ。デフォルト (dwFlags = 0) は、観客ではなく、サーバーでもないプレーヤーを示す。
DPPLAYER_SERVERPLAYER
プレーヤーは、クライアント／サーバー通信のサーバー プレーヤーである。サーバー プレーヤーを作成できるのは、ホストだけである。1 つのセッションに存在できるサーバー プレーヤーは 1 人だけである。このフラグが指定されている場合、CreatePlayer からは DPID_SERVERPLAYER のプレーヤー ID が必ず返される。
DPPLAYER_SPECTATOR
プレーヤーは観客として作成される。観客 プレーヤーは、観客としてフラグが設定されることを除けば、通常のプレーヤーと同じである。アプリケーションで、観客 プレーヤーの機能を制限できる。観客 プレーヤーの動作はすべて、アプリケーションが定義する。DirectPlay は、ただこのフラグを伝播するだけである。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CANTADDPLAYER
DPERR_CANTCREATEPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION

注意

1 つのプロセスで、複数のローカル プレーヤーが、同じコンピュータの他のプレーヤーやリモート コンピュータのプレーヤーと DirectPlay オブジェクトを介して通信することが可能である。

処理が正常に終了すると、このメソッドは、新規プレーヤーがセッションに参加したことを知らせる DPMSG_CREATEPLAYERORGROUP システム メッセージをセッションの他のすべてのプレーヤーに送信する。デフォルトでは、すべてのローカル プレーヤーはすべてのシステム メッセージのコピーを受信する。

メッセージの受け渡しやデータの関連付けでプレーヤーを識別するときは、アプリケーションに返されるプレーヤー ID を使用する。DirectPlay により割り当てられたプレーヤー ID やグループ ID はセッション内で常に一意である。

プレーヤーを作成したアプリケーションでのみ、次の処理が可能である。

  • プレーヤーの名前を変更する。
  • プレーヤーのリモート データを変更する。
  • プレーヤーからのメッセージを送信する。

アプリケーションがセッションを閉じた場合、作成されたローカル プレーヤーはすべて自動的に破棄される。IDirectPlay4::DestroyPlayer を使用すると、プレーヤーを作成したセッション ホストやアプリケーションはいつでもそれを破棄できる。

アプリケーションが DirectPlay メッセージを取得するのに別のスレッドを使用した場合、NULL以外の hEvent を指定して、それを同期処理で使用することを強く推奨する。このイベントは、プレーヤーがメッセージを受信すると設定される。メッセージ受信スレッド内で、プレーヤーがメッセージを持っているかどうかを判定するには、スレッド内の Win32® API WaitForSingleObject を使用する (または、複数のイベントが使用されている場合は WaitForMultipleObjects を使用する)。メッセージを待っている別のスレッド内の IDirectPlay4::Receive でループ処理を行うのは非効率的である。すべてのローカル プレーヤーで同じイベントを使用することも、プレーヤーごとに別のイベントをアプリケーションで指定することも可能である。イベントの作成、破棄は、アプリケーションの役割である。詳細については、「同期」を参照すること。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPNAME、DPMSG_CREATEPLAYERORGROUP、IDirectPlay4::DestroyPlayer、IDirectPlay4::EnumPlayers、IDirectPlay4::Receive、IDirectPlay4::Send、IDirectPlay4::SetPlayerData、IDirectPlay4::SetPlayerName、IDirectPlay4::GetPlayerFlags


IDirectPlay4::DeleteGroupFromGroup

IDirectPlay4::DeleteGroupFromGroup メソッドは、IDirectPlay4::AddGroupToGroup メソッドにより追加されたグループへのショートカットをグループから削除する。ショートカットを削除しても、グループは破棄されない。

HRESULT DeleteGroupFromGroup(
  DPID idParentGroup,
  DPID idGroup
);

パラメータ

idParentGroup
削除するショートカットが含まれているグループの ID。有効な任意のグループの ID を指定可能。
idGroup
削除するグループの ID。有効な任意のグループの ID を指定可能。

戻り値

処理が成功した場合は DP_OK を返す。失敗した場合は、次のエラー メッセージのいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP

注意

この変更をプレーヤーに知らせるために、DPMSG_DELETEGROUPFROMGROUP システム メッセージが生成される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::AddGroupToGroup、DPMSG_DELETEGROUPFROMGROUP


IDirectPlay4::DeletePlayerFromGroup

IDirectPlay4::DeletePlayerFromGroup メソッドは、プレーヤーをグループから削除する。

HRESULT DeletePlayerFromGroup(
  DPID idGroup,
  DPID idPlayer
);

パラメータ

idGroup
調整するグループのグループ ID。
idPlayer
グループから削除するプレーヤーのプレーヤー ID。

戻り値

処理が成功した場合は DP_OK を返す。失敗した場合は、次のエラー メッセージのいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

注意

ここでの変更をほかのプレーヤーに知らせるために、DPMSG_DELETEPLAYERFROMGROUP システム メッセージが生成される。システム メッセージのリストについては、「システム メッセージの使用」を参照すること。

別のコンピュータで作成されたグループでも、プレーヤーは任意のプレーヤーをそのグループから削除できる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::AddPlayerToGroup、DPMSG_DELETEPLAYERFROMGROUP


IDirectPlay4::DestroyGroup

IDirectPlay4::DestroyGroup メソッドは、グループをセッションから削除する。このグループに属する ID は、カレント セッションでは再利用されない。

HRESULT DestroyGroup(
  DPID idGroup
);

パラメータ

idGroup
ゲームから削除されるグループの ID。

戻り値

処理が成功した場合は DP_OK を返す。失敗した場合は、次のエラー メッセージのいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

グループを削除する前に、そのグループを空にする必要はない。そのグループに属する個別のプレーヤーは、破棄されない。このメソッドは、グループのプレーヤーごとに DPMSG_DELETEPLAYERFROMGROUP システム メッセージを作成してから、DPMSG_DESTROYPLAYERORGROUP システム メッセージを作成する。システム メッセージのリストについては、「システム メッセージの使用」を参照すること。

アプリケーションでは、ローカルに作成されたグループでなくても、任意のグループを破棄できる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreateGroup、DPMSG_DESTROYPLAYERORGROUP


IDirectPlay4::DestroyPlayer

IDirectPlay4::DestroyPlayer メソッドは、ローカル プレーヤーをセッションから削除し、そのプレーヤー宛てのペンディング状態のメッセージをメッセージ キューから削除し、プレーヤーが属するすべてのグループからプレーヤーを削除する。このプレーヤー ID は、カレント セッションで再利用されない。

一般には、プレーヤーを作成したアプリケーションだけがそのプレーヤーを破棄できる。しかし、セッションのホストも、プレーヤーを破棄できる。

HRESULT DestroyPlayer(
  DPID idPlayer
);

パラメータ

idPlayer
ローカルに所有されているプレーヤーで、セッションから削除するプレーヤーのプレーヤー ID。セッションのホストから DestroyPlayer を呼び出す場合は、この ID はローカル プレーヤーの ID でも、リモート プレーヤーの ID でもかまわない。

戻り値

処理が成功した場合は DP_OK を返す。失敗した場合は、次のエラー メッセージのいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

注意

このメソッドは、プレーヤーが属するグループごとに DPMSG_DELETEPLAYERFROMGROUP システム メッセージを作成してから、DPMSG_DESTROYPLAYERORGROUP システム メッセージを作成する。

プレーヤーの送信キューにペンディング状態の非同期メッセージがある場合、そのプレーヤーは破棄できない。すべてのメッセージを完了するか、または取り消す必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreatePlayer、DPMSG_DESTROYPLAYERORGROUP


IDirectPlay4::EnumConnections

IDirectPlay4::EnumConnections メソッドは、アプリケーションで使用可能な登録済みサービス プロバイダとロビー プロバイダをすべて列挙する。ユーザーはこれらの中から、サービス プロバイダとロビー プロバイダを選択する。ユーザーが選択した接続は、IDirectPlay4::InitializeConnection メソッドに渡される。

HRESULT EnumConnections(
  LPCGUID lpguidApplication,
  LPDPENUMCONNECTIONSCALLBACK lpEnumCallback,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

lpguidApplication
アプリケーションのグローバル ユニーク識別子 (GUID) へのポインタ。アプリケーションで使用可能な登録済みサービス プロバイダとロビー プロバイダだけが返される。NULL ポインタを設定した場合、アプリケーション GUID に関係なく、すべての接続が列挙される。
lpEnumCallback
使用可能な接続ごとに呼び出される、ユーザー指定の EnumConnectionsCallback 関数へのポインタ。
lpContext
コールバック関数へ渡される、ユーザー定義のコンテキストへのポインタ。
dwFlags
列挙される接続のタイプを指定するフラグ。デフォルト (dwFlags = 0) では、DPCONNECTION_DIRECTPLAY と同じ結果となる。

次に、可能な値を示す。

DPCONNECTION_DIRECTPLAY
アプリケーション セッションで通信する DirectPlay サービス プロバイダのみを列挙する。
DPCONNECTION_DIRECTPLAYLOBBY
ロビー サーバーと通信する DirectPlay ロビー プロバイダのみを列挙する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

注意

このメソッドは、DirectPlayEnumerate 関数の代わりとなる。DirectPlayEnumerate 関数は依然として機能するが、登録済みサービス プロバイダしか返さない。

サービス プロバイダとロビー プロバイダが返される順序は、EnumConnections を呼び出した順序と同じであるとは限らない。

列挙された接続のすべてを使用できるわけではない。たとえば、このメソッドはユーザーがモデムをインストールしていなくてもモデム サービス プロバイダを返す。アプリケーションでは、接続ごとに IDirectPlay4::InitializeConnection メソッドを呼び出し、エラー コードを調べてサービス プロバイダが使用可能であるかどうかを判断することができる。

IDirectPlay4A(ANSI) インタフェースでこのメソッドを呼び出すと、必ず適切にローカライズされた 1 バイト文字の文字列が返される。マルチ バイト文字の文字列は使用されないので、それをサポートしていないフォントを使用しても文字列を表示するときに問題が発生しない。IDirectPlay4(Unicode) インタフェースでこのメソッドを呼び出すと、ローカライズされたワイド文字の記述が返される。

サービス プロバイダの中には、それらをプライベートとして登録できるものもある。これらのサービス プロバイダは、このメソッドを使用しても列挙されない。プライベートのサービス プロバイダを使用するには、ロビーによりアプリケーションを起動するか、または DirectPlay アドレスを作成してそれを InitializeConnection に渡し、プライベートのサービス プロバイダをその GUID により明示的に参照する必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::InitializeConnection、EnumConnectionsCallback


IDirectPlay4::EnumGroupPlayers

IDirectPlay4::EnumGroupPlayers メソッドは、現在開いているセッションの特定のグループに属しているプレーヤーを列挙する。開いているセッションがない場合は、DPENUMPLAYERS_SESSION フラグとセッションの guidInstance を指定すると、リモート セッションのプレーヤーを列挙できる。パスワードで保護されたリモート セッションは列挙できない。

アプリケーションで実装するコールバック関数へのポインタは必ず指定する。DirectPlay は、グループの中で dwFlags で指定された条件に一致するプレーヤーごとにそのコールバック関数を呼び出す。

接続していないロビー セッションで EnumGroupPlayers を使用することはできない。

HRESULT EnumGroupPlayers(
  DPID idGroup,
  LPGUID lpguidInstance,
  LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

idGroup
列挙するプレーヤーのグループの ID。
lpguidInstance
列挙するセッションを識別するためのグローバル ユニーク識別子 (GUID) へのポインタ。このパラメータは、DPENUMPLAYERS_SESSION フラグが指定されていない場合は無視される。GUID は、IDirectPlay4::EnumSessions により列挙されるセッションのいずれかでなければならない。
lpEnumPlayersCallback2
グループ内で dwFlags で指定された条件に一致するすべてのプレーヤーに対して呼び出す EnumPlayersCallback2 関数へのポインタ。
lpContext
各列挙コールバック関数に渡される、アプリケーション定義のコンテキストへのポインタ。
dwFlags
列挙方法を指定するフラグ。デフォルト (dwFlags = 0) では、現在アクティブなセッションのグループのプレーヤーが列挙される。指定したいフラグに対して論理演算子の OR を実行する。指定したフラグの条件をすべて満たすプレーヤーのみが列挙される。たとえば、(DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_SPECTATOR) と指定すると、グループの中でローカルで、なおかつ観客 プレーヤーであるプレーヤーのみが列挙される。(DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_REMOTE) と指定すると、プレーヤーが同時にローカルかつリモートになることはあり得ないので、プレーヤーはまったく列挙されない。

次の値のいずれかまたはいくつかを指定できる。

DPENUMPLAYERS_LOCAL
この DirectPlay オブジェクトによりローカルに作成されたプレーヤーを列挙する。
DPENUMPLAYERS_OWNER
このグループの所有者であるプレーヤーのみを列挙する。
DPENUMPLAYERS_REMOTE
リモートの DirectPlay オブジェクトにより作成されたプレーヤーを列挙する。
DPENUMPLAYERS_SERVERPLAYER
サーバー プレーヤーを列挙する。
DPENUMPLAYERS_SESSION
lpguidInstance により指定されたセッションのプレーヤーを列挙する。このフラグは、現在開いているセッションがない場合にのみ使用できる。このフラグは、ロビー セッションでは使用できない。
DPENUMPLAYERS_SPECTATOR
観客 プレーヤーであるプレーヤーを列挙する。

戻り値

処理が成功した場合は DP_OK を返す。失敗した場合は、次のエラー メッセージのいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDGROUP
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

セッションがユーザーにより接続されていないロビー セッションである場合は、DPERR_ACCESSDENIED を返す。コールバックが無効な場合、guidInstance が無効な場合、または無効なフラグが指定された場合は、DPERR_INVALIDPARAMS を返す。アクティブなセッションがない場合は、DPERR_NOSESSIONS を返す。セッションを列挙できなかった場合は、DPERR_UNAVAILABLE を返す。

注意

デフォルトでは、このメソッドはカレント セッションのすべてのプレーヤーを列挙する。DPENUMPLAYERS_SESSION フラグは、セッション インスタンスの GUID と共に使用して、セッションのホストにその列挙用リストを提供するように要求できる。このメソッドで DPENUMPLAYERS_SESSION フラグを使用するときは、IDirectPlay4::EnumSessions メソッドが呼び出された後で、また IDirectPlay4::Close メソッドや IDirectPlay4::Open メソッドを呼び出す前に行う必要がある。

グループの所有者であるプレーヤーを示すために、コールバック関数で DPENUMPLAYERS_OWNER フラグが返される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreatePlayer、IDirectPlay4::DestroyPlayer、IDirectPlay4::AddPlayerToGroup、IDirectPlay4::DeletePlayerFromGroup


IDirectPlay4::EnumGroups

IDirectPlay4::EnumGroups メソッドは、カレント セッションの最上位グループをすべて列挙する。最上位グループとは、IDirectPlay4::CreateGroup メソッドにより作成されたグループである。開いているセッションがない場合は、DPENUMGROUPS_session フラグとセッションの guidInstance を指定すると、リモート セッションのグループを列挙できる。パスワードで保護されたリモート セッションは列挙できない。

アプリケーションで実装するコールバック関数へのポインタは必ず指定する。DirectPlay は、セッション内で dwFlags で指定された条件に一致するグループごとにそのコールバック関数を呼び出す。

接続していないロビー セッションで EnumGroups を使用することはできない。

HRESULT EnumGroups(
  LPGUID lpguidInstance,
  LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

lpguidInstance
現在開いているセッション内のグループを列挙するには、このパラメータに NULL を指定する。開いているセッションがない場合は、このパラメータに、列挙するセッションを識別するためのグローバル ユニーク識別子 (GUID) へのポインタを指定できる。この GUID は、IDirectPlay4::EnumSessions により列挙されるセッションのいずれかでなければならない。このパラメータは、DPENUMGROUPS_SESSION フラグが指定されていない場合は無視される。
lpEnumPlayersCallback2
セッション内で dwFlags で指定された条件に一致するすべてのグループに対して呼び出す EnumPlayersCallback2 関数へのポインタ。
lpContext
各列挙コールバック関数に渡される、アプリケーション定義のコンテキストへのポインタ。
dwFlags
列挙方法を指定するフラグ。デフォルト (dwFlags = 0) では、現在アクティブなセッションのグループがすべて列挙される。指定したいフラグに対して論理演算子の OR を実行する。指定したフラグの条件をすべて満たすグループのみが列挙される。たとえば、(DPENUMGROUPS_LOCAL | DPENUMGROUPS_STAGINGAREA) と指定すると、ローカルで、なおかつステージング領域であるグループのみが列挙される。(DPENUMGROUPS_LOCAL | DPENUMGROUPS_REMOTE) と指定すると、グループが同時にローカルかつリモートになることはあり得ないので、グループはまったく列挙されない。

次の値のいずれかまたはいくつかを指定できる。

DPENUMGROUPS_ALL
このセッション内のすべてのグループを列挙する。
DPENUMGROUPS_HIDDEN
現在使用可能な隠しグループのみを列挙する。
DPENUMGROUPS_LOCAL
この DirectPlay オブジェクトによりローカルに作成されたグループを列挙する。
DPENUMGROUPS_REMOTE
リモートの DirectPlay オブジェクトにより作成されたグループを列挙する。
DPENUMGROUPS_SESSION
lpguidInstance パラメータにより指定されたセッションで列挙を実行する。このフラグは、現在アクティブなセッションがない場合にのみ使用できる。このフラグは、ロビー セッションでは使用できない。
DPENUMGROUPS_STAGINGAREA
ステージング領域であるグループを列挙する (ステージング領域は、新しいセッションを起動するためにプレーヤーを整列するときに使用する)。

戻り値

処理が成功した場合は DP_OK を返す。失敗した場合は、次のエラー メッセージのいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

コールバックが無効な場合、guidInstance が無効な場合、または無効なフラグが指定された場合は、DPERR_INVALIDPARAMS を返す。開いているセッションがない場合は、DPERR_NOSESSIONS を返す。リモート セッションを列挙できなかった場合は、DPERR_UNAVAILABLE を返す。

注意

グループ内のサブグループを列挙するには、IDirectPlay4::EnumGroupsInGroup を使用すること。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

EnumPlayersCallback2、IDirectPlay4::CreateGroup、IDirectPlay4::DestroyGroup、IDirectPlay4::EnumSessions


IDirectPlay4::EnumGroupsInGroup

IDirectPlay4::EnumGroupsInGroup メソッドは、別のグループに含まれるすべてのグループとグループへのショートカットを列挙する。グループを別のグループ内に配置するには、IDirectPlay4::CreateGroupInGroup メソッドを使用してグループを作成するか、またはIDirectPlay4::AddGroupToGroup メソッドによりグループを別のグループに追加する。このメソッドは、再帰的でない。

接続していないロビー セッションで EnumGroupsInGroup を使用することはできない。

HRESULT EnumGroupsInGroup(
  DPID idGroup,
  LPGUID lpguidInstance,
  LPDPENUMPLAYERSCALLBACK2 lpEnumCallback,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

idGroup
列挙するサブグループが含まれるグループの ID。
lpguidInstance
列挙するセッションを識別するためのグローバル ユニーク識別子 (GUID) へのポインタ。このパラメータは、DPENUMPLAYERS_SESSION フラグが指定されていない場合は無視される。GUID は、IDirectPlay4::EnumSessions メソッドにより列挙されるセッションのいずれかでなければならない。
lpEnumCallback
グループ内で dwFlags で指定された条件に一致するすべてのグループに対して呼び出す EnumPlayersCallback2 関数へのポインタ。
lpContext
各列挙コールバック関数に渡される、アプリケーション定義のコンテキストへのポインタ。
dwFlags
列挙方法を指定したフラグ。デフォルト (dwFlags = 0) では、現在アクティブなセッションのグループがすべて列挙される。指定したいフラグに対して論理演算子の OR を実行する。指定したフラグの条件をすべて満たすグループのみが列挙される。たとえば、(DPENUMGROUPS_LOCAL | DPENUMGROUPS_STAGINGAREA) と指定すると、ローカルで、なおかつステージング領域であるグループのみが列挙される。(DPENUMGROUPS_LOCAL | DPENUMGROUPS_REMOTE) と指定すると、グループが同時にローカルかつリモートになることはあり得ないので、グループはまったく列挙されない。

次の値のいずれかまたはいくつかを指定できる。

DPENUMGROUPS_ALL
グループ内のすべてのグループを列挙する。
DPENUMGROUPS_HIDDEN
グループ内で現在使用可能な隠しグループのみを列挙する。
DPENUMGROUPS_LOCAL
この DirectPlay オブジェクトによりローカルに作成されたグループ内のグループを列挙する。
DPENUMGROUPS_REMOTE
リモートの DirectPlay オブジェクトにより作成されたグループ内のグループを列挙する。
DPENUMGROUPS_SESSION
lpguidInstance パラメータにより指定されたセッションで列挙を実行する。このフラグは、現在アクティブなセッションがない場合にのみ使用できる。このフラグは、ロビー セッションでは使用できない。
DPENUMGROUPS_SHORTCUT
IDirectPlay4::AddGroupToGroupメソッドを使用してグループに追加されたショートカットであるグループを列挙する (ショートカットとは、別のグループへのリンクである)。
DPENUMGROUPS_STAGINGAREA
ステージング領域であるグループ内のグループを列挙する (ステージング領域は、新しいセッションを起動するためにプレーヤーを整列するときに使用する)。

戻り値

処理が成功した場合は DP_OK を返す。失敗した場合は、次のエラー メッセージのいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNSUPPORTED

コールバックが無効な場合、または無効な guidInstance が指定された場合は、DPERR_INVALIDPARAMS を返す。アクティブなセッションがない場合は、DPERR_NOSESSIONS を返す。セッションを列挙できなかった場合は、DPERR_UNSUPPORTED を返す。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreateGroupInGroup、IDirectPlay4::DestroyGroup、IDirectPlay4::AddGroupToGroup、IDirectPlay4::DeleteGroupFromGroup


IDirectPlay4::EnumPlayers

IDirectPlay4::EnumPlayers メソッドは、現在開いているセッションのプレーヤーを列挙する。開いているセッションがない場合は、DPENUMPLAYERS_SESSION フラグとセッションの guidInstance を指定すると、リモート セッションのプレーヤーを列挙できる。パスワードで保護されたリモート セッションは列挙できない。

アプリケーションで実装するコールバック関数へのポインタは必ず指定する。DirectPlay は、セッションの中で dwFlags で指定された条件に一致するプレーヤーごとにそのコールバック関数を呼び出す。

このメソッドは、ロビー セッション内では必ず DPERR_ACCESSDENIED を返す。

HRESULT EnumPlayers(
  LPGUID lpguidInstance,
  LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

lpguidInstance
現在開いているセッション内のプレーヤーを列挙するには、このパラメータに NULL を指定する。開いているセッションがない場合は、このパラメータに、列挙するセッションを識別するための GUID へのポインタを指定できる。この GUID は、IDirectPlay4::EnumSessions により列挙されるセッションのいずれかでなければならない。このパラメータは、DPENUMPLAYERS_SESSION フラグが指定されていない場合は無視される。
lpEnumPlayersCallback2
セッション内で dwFlags で指定された条件に一致するすべてのプレーヤーに対して呼び出す EnumPlayersCallback2 関数へのポインタ。
lpContext
各列挙コールバック関数に渡される、アプリケーション定義のコンテキストへのポインタ。
dwFlags
列挙方法を指定するフラグ。デフォルト (dwFlags = 0) では、現在アクティブなセッションのプレーヤーがすべて列挙される。指定したいフラグに対して論理演算子の OR を実行する。指定したフラグの条件をすべて満たすプレーヤーのみが列挙される。たとえば、(DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_SPECTATOR) と指定すると、グループの中でローカルで、なおかつ観客 プレーヤーであるプレーヤーのみが列挙される。(DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_REMOTE) と指定すると、プレーヤーが同時にローカルかつリモートになることはあり得ないので、プレーヤーはまったく列挙されない。

次の値のいずれかまたはいくつかを指定できる。

DPENUMPLAYERS_ALL
このセッション内のすべてのプレーヤーを列挙する。
DPENUMPLAYERS_GROUP
プレーヤーの列挙にグループを含める。
DPENUMPLAYERS_LOCAL
この DirectPlay オブジェクトによりローカルに作成されたプレーヤーを列挙する。
DPENUMPLAYERS_REMOTE
リモートの DirectPlay オブジェクトにより作成されたプレーヤーを列挙する。
DPENUMPLAYERS_SERVERPLAYER
サーバー プレーヤーを列挙する。
DPENUMPLAYERS_SESSION
lpguidInstance により指定されたセッションのプレーヤーを列挙する。このフラグは、現在開いているセッションがない場合にのみ使用できる。
DPENUMPLAYERS_SPECTATOR
観客 プレーヤーであるプレーヤーを列挙する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

コールバックが無効な場合、guidInstance が無効な場合、または無効なフラグが指定された場合は、DPERR_INVALIDPARAMS を返す。開いているセッションがない場合は、DPERR_NOSESSIONS を返す。リモート セッションを列挙できなかった場合は、DPERR_UNAVAILABLE を返す。

注意

このメソッドは、デフォルトでは、現在開いているセッションのプレーヤーを列挙する。DPENUMPLAYERS_GROUP フラグを使用すると、グループも列挙に含めることができる。DPENUMPLAYERS_SESSION フラグは、セッション インスタンスの GUID と共に使用して、セッションのホストにその列挙用リストを提供するように要求できる。このメソッドは、IDirectPlay4::EnumSessions 列挙内からは呼び出すことができない。また、このメソッドで DPENUMPLAYERS_SESSION フラグを使用するときは、IDirectPlay4::EnumSessions メソッドが呼び出された後で、また IDirectPlay4::Close メソッドや IDirectPlay4::Open メソッドを呼び出す前に行う必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreatePlayer、IDirectPlay4::DestroyPlayer、IDirectPlay4::EnumSessions


IDirectPlay4::EnumSessions

IDirectPlay4::EnumSessions メソッドは、特定のアプリケーションのアクティブなセッションと、特定のアプリケーションを提供しているアクティブなロビー セッションのすべてを列挙する。このメソッドは、DirectPlayCreate メソッドまたは IDirectPlay4::InitializeConnection メソッドのいずれかにより オブジェクトを作成および初期化した後に呼び出すことができる。

このメソッドは、セッションがまだ開いている間に呼び出されると、エラーを返す。

HRESULT EnumSessions(
  LPDPSESSIONDESC2 lpsd,
  DWORD dwTimeout,
  LPDPENUMSESSIONSCALLBACK2 lpEnumSessionsCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

lpsd
列挙するセッションを記述した DPSESSIONDESC2 構造体へのポインタ。この構造体に設定されている条件を満たすセッションのみが列挙される。guidApplication メンバに、それが認識されているとき目的のアプリケーションのグローバル ユニーク識別子 (GUID) を設定したり、または GUID_NULL を設定してすべてのセッションを取得することができる。lpszPassword メンバは、プライベート セッションを希望する場合にのみ必要となる。guidApplication と lpszPassword 以外のデータ メンバはすべて無視される。
dwTimeout
同期の場合、DirectPlay が列挙要求に対する応答を待っている時間 (列挙と列挙の間の時間ではない)(ミリ秒単位)。このタイムアウト値が経過してから応答を受信しても、それらはすべて無視される。アプリケーションは、タイムアウト値を経過するまでブロックされる。

非同期の場合、この値は、内部セッション リストを更新するために DirectPlay により列挙要求がブロードキャストされる間隔 (ミリ秒単位) を示す。

タイムアウト値に 0 を設定すると、サービス プロバイダと接続タイプに適合したデフォルトのタイムアウト値が使用される。この値に 0 を設定することを推奨する。アプリケーションでは、IDirectPlay4::GetCaps メソッドを呼び出して DPCAPS 構造体の dwTimeout データ メンバを調べることにより、このタイムアウト値を判定できる。

lpEnumSessionsCallback2
DirectPlay セッションの応答ごとに呼び出される、アプリケーションにより指定された EnumSessionsCallback2 関数へのポインタ。
lpContext
各列挙コールバック関数へ渡される、ユーザー定義のコンテキストへのポインタ。
dwFlags
デフォルトは 0 であり、DPENUMSESSIONS_AVAILABLE と等価である。DPENUMSESSIONS_ALL または DPENUMSESSIONS_PASSWORDREQUIRED を使用して列挙するとき、参加できないセッションや、ユーザーが警告したり、パスワード入力を要求できるようにパスワードで保護されているセッションを、アプリケーションで認識することが重要である。
DPENUMSESSIONS_ALL
セッションが新しいプレーヤーを受け付けているかどうかに関係なく、すべてのアクティブなセッションを列挙する。プレーヤー制限に達したセッション、新しいプレーヤーが無効になったセッション、または参加が無効になったセッションを列挙する。

パスワードにより保護されたセッションは、DPENUMSESSIONS_PASSWORDREQUIRED フラグも指定されていなければ列挙されない。

DPENUMSESSIONS_ALL が指定されていない場合は、DPENUMSESSIONS_AVAILABLE であると見なされる。

DPENUMSESSIONS_ASYNC
セッション キャッシュのカレント セッションをすべて列挙し、即座に戻る。非同期列挙プロセスがまだ起動されていない場合は、それを起動する。DPENUMSESSIONS_STOPASYNC フラグを指定して EnumSessions を呼び出すか、または Open や Release を呼び出して取り消すまで、セッション リストは更新され続ける。

このフラグが指定されていない場合、列挙は同期をとりながら実行される。

DPENUMSESSIONS_AVAILABLE
新しいプレーヤーの参加を受け付けているセッションをすべて列挙する。プレーヤーの最大数に達しているセッション、新しいプレーヤーが無効になったセッション、または参加が無効になったセッションは列挙しない。

パスワードにより保護されたセッションは、DPENUMSESSIONS_PASSWORDREQUIRED フラグも指定されていなければ列挙されない。

DPENUMSESSIONS_PASSWORDREQUIRED
DPENUMSESSIONS_AVAILABLE フラグまたは DPENUMSESSIONS_ALL フラグのいずれかと共に使用すると、パスワードにより保護されていないセッションに加えて、パスワードにより保護されているセッションも列挙される。

このフラグを指定しない場合は、パスワードにより保護されているセッションは返されない。

DPENUMSESSIONS_RETURNSTATUS
このフラグを指定した場合は、列挙時に接続の進行状況を示すダイアログ ボックスが表示されない。すぐに接続できない場合、メソッドは DPERR_CONNECTING エラーを返す。アプリケーションは、正常終了を示す DP_OK が返されるか、またはエラーを示すそのほかのエラー コードが返されるまで EnumSessions を呼び出し続ける必要がある。
DPENUMSESSIONS_STOPASYNC
セッション キャッシュのカレント セッションをすべて列挙し、非同期列挙プロセスを取り消す。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION
DPERR_UNINITIALIZED
DPERR_USERCANCEL

セッションが既に開いている場合は、DPERR_GENERIC を返す。DirectPlay オブジェクトが初期化されていない場合は、DPERR_UNINITIALIZED を返す。ユーザーが列挙プロセスを取り消した場合 (一般にサービス プロバイダのダイアログボックスを取り消すことにより) は DPERR_USERCANCEL を返し、ユーザーが TCP/IP サービス プロバイダのダイアログ ボックスに IP アドレスに変換できないコンピュータ名を入力した場合は DPERR_INVALIDPARAMS を返す。メソッドがネットワークへ接続中の場合は、DPERR_CONNECTING を返す。

注意

EnumSessions は、サービス プロバイダがネットワーク上のホストを検索し、それらを列挙要求に送信するように要求することで機能する。受信した応答により、列挙されるセッションがすべて揃う。

EnumSessions は、同期 (デフォルト) または非同期に呼び出すことができる。同期をとりながら呼び出した場合、DirectPlay は内部セッション キャッシュをクリアし、列挙要求を送信して、指定されたタイムアウトになるまで応答を収集する。各セッションは、コールバック関数によりアプリケーションに返される。アプリケーションは、すべてのセッションがコールバック関数から返されるまでブロックされる。

非同期に呼び出された場合 (DPENUMSESSIONS_ASYNC)、セッション キャッシュのカレント セッション (存在する場合) はすべてコールバック関数によりアプリケーションに返され、またメソッドは戻る。DirectPlay は、タイムアウト パラメータを指定して列挙要求を自動的に送信し、応答が返されるのを待つ。次のように、各応答を使用してセッション キャッシュを更新する。

  • キャッシュ内に既に存在するセッションを更新する。
  • 設定された期間に更新されず、タイムアウト時間に達したセッションを削除する。
  • 新しいセッションを追加する。

アプリケーションは、失効したセッションをすべて削除し、新しいセッションを追加し、またセッションを更新した最新のセッション リストを取得するために、EnumSessions を (DPENUMSESSIONS_ASYNC フラグを設定して) 再度呼び出す必要がある。それ以降は EnumSessions を呼び出しても列挙要求は生成されない。DPENUMSESSIONS_STOPASYNC フラグを設定して EnumSessions を呼び出し、プロセスを取り消すか、IDirectPlay4::Open メソッドを使用してセッションを開くか、または DirectPlay オブジェクトを解放するまで、列挙要求は DirectPlay により定期的に作成される。

非同期に列挙するセッションの記述を変更するには、非同期列挙を停止して、それを再起動する必要がある。たとえば、パスワードを指定しなければ列挙を起動できないので、後から非同期呼び出しでパスワードを追加し、それによりそのパスワードを使用してプライベート セッションの列挙を開始する。反対に、正しいパスワードを指定してから、不正なパスワードに変更しても、そのセッションは列挙される。ただし、DPENUMSESSIONS_STOPASYNC フラグを指定して EnumSessions を呼び出し、パスワードを指定すると、プライベート セッションが列挙される。

使用可能なセッションの列挙が完了したら、アプリケーションは IDirectPlay4::Open メソッドを使用してセッションのいずれかに参加できる。開くことが可能なのは、セッション キャッシュのセッションだけである。アプリケーションは、最後に EnumSessions を呼び出してエラーが返されてから、失効したセッションを開くこともできる。

認証は、保証サーバーでセッションを列挙するときには実行されない。列挙条件を満たすセッションがすべて返される。アプリケーションで IDirectPlay4::Open または IDirectPlay4::SecureOpen を使用してこれらのセッションのいずれかを開こうとすると、認証が行われる。

アプリケーションがロビーにより起動されたのではない場合、ネットワークで列挙を実行するための情報 (電話番号や IP アドレスなど) が IDirectPlay4::InitializeConnection に渡されていなければ、サービス プロバイダはダイアログ ボックスを表示してユーザーにそれらの情報を入力するように要求できる。サービス プロバイダがブロードキャスト列挙を実行できる場合、ユーザーに情報を入力してもらう必要がなければ、ダイアログ ボックスは表示されない。ユーザーがサービス プロバイダのダイアログ ボックスを取り消すと、EnumSessions は DPERR_USERCANCEL を返す。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPSESSIONDESC2、IDirectPlay4::Open、IDirectPlay4::SecureOpen


IDirectPlay4::GetCaps

IDirectPlay4::GetCaps メソッドは、該当する DirectPlay オブジェクトの能力を取得する。

HRESULT GetCaps(
  LPDPCAPS lpDPCaps,
  DWORD dwFlags
);

パラメータ

lpDPCaps
DirectPlay オブジェクトの能力を受け取る DPCAPS 構造体へのポインタ。IDirectPlay4::GetCaps を使用する前に DPCAPS 構造体の dwSize メンバを設定する必要がある。
dwFlags
このパラメータに 0 を設定した場合、保証なしのメッセージ処理に対する能力が計算される。
DPGETCAPS_GUARANTEED
保証付きのメッセージ配信の能力を取得する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

注意

IDirectPlay4::GetPlayerCaps メソッドが要求されたプレーヤーの能力を返すのに対して、このメソッドはカレント セッションの能力を返す。

ただし、セッションが開いている間は、SendEx でサポートされているオプションを示す能力を使用できない。セッションのホストであるアプリケーションが DPSESSIONDESC2 構造体で DPSESSION_DIRECTPLAYPROTOCOL フラグを指定している場合は、すべての SendEx オプションがサポートされる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPCAPS、IDirectPlay4::GetPlayerCaps、IDirectPlay4::Send


IDirectPlay4::GetGroupConnectionSettings

IDirectPlay4::GetGroupConnectionSettings メソッドは、DPLCONNECTION 構造体からグループの接続設定を取得する。このグループから起動されたセッションはすべて、これらの設定値を使用する。このメソッドは、ロビー セッションでのみ使用できる。

HRESULT GetGroupConnectionSettings(
  DWORD dwFlags,
  DPID idGroup,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

dwFlags
使用しない。0 に設定しておく。
idGroup
接続設定を取得するグループの ID。
lpData
DPLCONNECTION 構造体とその全データをコピーするバッファへのポインタ。データのサイズのみを要求する場合は、このパラメータに NULL を設定する。lpdwDataSize パラメータには、データを保持するために必要な最低サイズを設定する。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータにはデータのサイズがバイト単位で設定されている。バッファが小さすぎる場合 (DPERR_BUFFERTOOSMALL)、このパラメータには最低限必要なバッファのサイズが設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED

注意

グループの接続設定は、ステージング領域のグループにのみ関係がある。

DPSESSIONDESC2 構造体の guidInstance データ メンバを参照すると、ゲームが起動されているかどうかを調べることができる。この構造体のポインタは、このメソッドで返される DPLCONNECTION 構造体の lpSessionDesc データ メンバに格納されている。guidInstance は、ゲームが起動されるまでは GUID_NULL である。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPLCONNECTION、IDirectPlayLobby3::RunApplication、IDirectPlay4::SetGroupConnectionSettings


IDirectPlay4::GetGroupData

IDirectPlay4::GetGroupData メソッドは、IDirectPlay4::SetGroupData を使用して、グループ ID に関連付けられたアプリケーション固有のデータ ブロックを取得する。

HRESULT GetGroupData(
  DPID idGroup,
  LPVOID lpData,
  LPDWORD lpdwDataSize,
  DWORD dwFlags
);

パラメータ

idGroup
データを要求するグループ ID。
lpData
アプリケーション固有のグループ データを書き込むバッファへのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに必要なサイズに設定される。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータにはグループ データのサイズがバイト単位で設定されている。バッファが小さすぎる場合 (DPERR_BUFFERTOOSMALL)、このパラメータには必要なバッファのサイズが設定される。
dwFlags
このパラメータに 0 を設定した場合、リモート データが取得される。
DPGET_LOCAL
アプリケーションにより設定されたローカル データを取得する。
DPGET_REMOTE
リモートの共有データ領域からカレント データを取得する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

DirectPlay では、ローカルとリモートの両方のグループ データを維持できる。アプリケーションは、検索するデータのタイプを指定する必要がある。ローカル データは、この DirectPlay オブジェクトにより、DPSET_LOCAL フラグを使用して設定されている。リモート データは、セッション内の任意のアプリケーションにより、DPSET_REMOTE フラグを使用して設定されている可能性がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::SetGroupData


IDirectPlay4::GetGroupFlags

IDirectPlay4::GetGroupFlags メソッドは、グループについて記述しているフラグを返す。

HRESULT GetGroupFlags(
  DPID idGroup,
  LPDWORD lpdwFlags
);

パラメータ

idGroup
フラグ設定を取得するグループの ID。
lpdwFlags
グループのフラグ設定を設定する DWORD へのポインタ。次のいずれかまたはいくつかを設定する。
DPGROUP_LOCAL
グループは、このアプリケーションにより作成されたものである。このフラグが指定されない場合、グループはリモート グループである。
DPGROUP_STAGINGAREA
グループは、ステージング領域である。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreateGroup


IDirectPlay4::GetGroupName

IDirectPlay4::GetGroupName メソッドは、グループに関連付けられている名前を返す。

HRESULT GetGroupName(
  DPID idGroup,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

idGroup
名前が要求されているグループの ID。
lpData
名前データを書き込むバッファへのポインタ。データのサイズのみを要求する場合は、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに必要なサイズに設定される。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータには名前データのサイズがバイト単位で設定されている。バッファが小さすぎる場合 (DPERR_BUFFERTOOSMALL)、このパラメータには必要なバッファのサイズが設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

メソッドが戻ったら、ポインタ lpData を DPNAME 構造体にキャストして、グループ名データを読み取る必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPNAME、IDirectPlay4::SetGroupName


IDirectPlay4::GetGroupOwner

IDirectPlay4::GetGroupOwner メソッドは、グループの現在の所有者の ID を返す。このメソッドは、ロビー セッションでのみ有効である。

HRESULT GetGroupOwner(
  DPID idGroup,
  LPDPID lpidOwner
);

パラメータ

idGroup
所有者が要求されたグループの ID。
lpidOwner
所有者の ID を受け取る変数のアドレス。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_GENERIC
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::SetGroupOwner


IDirectPlay4::GetGroupParent

IDirectPlay4::GetGroupParent メソッドは、グループの親グループの ID を返す。

HRESULT GetGroupParent(
  DPID idGroup,
  LPDPID lpidParent
);

パラメータ

idGroup
親グループが要求されたグループの ID。
lpidParent
親グループの ID を受け取る変数のアドレス。このメソッドで返された親グループの ID が 0 の場合、そのグループはルート グループである。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreateGroupInGroup


IDirectPlay4::GetMessageCount

IDirectPlay4::GetMessageCount メソッドは、特定のローカル プレーヤーの受信キューのメッセージ数を問い合わせる。

HRESULT GetMessageCount(
  DPID idPlayer,
  LPDWORD lpdwCount
);

パラメータ

idPlayer
メッセージ数が要求されているプレーヤーの ID。プレーヤーは、ローカルでなければならない。
lpdwCount
メソッドによってメッセージ数が返される変数のポインタ。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::Receive


IDirectPlay4::GetMessageQueue

IDirectPlay4::GetMessageQueue メソッドは、送信キューまたは受信キュー内のメッセージ数を判定する。送信キューのステータスをモニターすることで、アプリケーションは基底ネットワークの帯域幅に基づいてセッション内のその他のプレーヤーに送信するメッセージの数を調整できる。

1 台のコンピュータのセッションに複数のプレーヤーが存在する場合、コンピュータのキュー サイズは個別のプレーヤーではなく、そのコンピュータのセッションの全プレーヤーに対応しているので、注意すること。

HRESULT GetMessageQueue(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPDWORD lpdwNumMsgs,
  LPDWORD lpdwNumBytes
);

パラメータ

idFrom
キューのステータスを取得したいメッセージ送信元のプレーヤーの ID。0 を指定すると、送信されたすべてのメッセージに関する情報が返される。idTo も指定した場合、idFrom のプレーヤーから idTo のプレーヤーに送信されたメッセージに関する情報のみが返される。
idTo
キューのステータスを取得したいメッセージ送信先のプレーヤーの ID。0 を指定すると、送信されたすべてのメッセージに関する情報が返される。idFrom も指定した場合、idFrom のプレーヤーから idTo のプレーヤーに送信されたメッセージに関する情報のみが返される。ただし、idTo にグループ ID は指定できない。
dwFlags
キューに関する情報で取得するタイプを指定する。デフォルト (dwFlags = 0) では、送信キューに関する情報が返される。次の値のいずれかを 1 つだけ指定できる。
DPMESSAGEQUEUE_SEND
送信キューに関する情報を取得する。
DPMESSAGEQUEUE_RECEIVE
受信キューに関する情報を取得する。
lpdwNumMsgs
キューのメッセージ数が設定される DWORD へのポインタ。NULL の場合、値は何も返されない。
lpdwNumBytes
キューのバイト総数が設定される DWORD へのポインタ。NULL の場合、値は何も返されない。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_UNSUPPORTED

ユーザーがリモート プレーヤーの idTo を指定して受信キューを調べた場合は (DPMESSAGEQUEUE_RECEIVE)、DPERR_INVALIDPLAYER が返される。リモート プレーヤーの idFrom を指定して送信キューを調べた場合も (DPMESSAGEQUEUE_SEND)、DPERR_INVALIDPLAYER が返される。受信キュー フラグと送信キュー フラグの両方を指定した場合 (dwFlags = DPMESSAGEQUEUE_RECEIVE|DPMESSAGEQUEUE_SEND) は、DPERR_INVALIDFLAGS が返される。DirectPlay プロトコルがオンになっておらず、またサービス プロバイダで送信キューのチェック機能がサポートされていない場合に、送信キューを調べようとすると、DPERR_UNSUPPORTED が返される。

注意

リモート コンピュータ上のメッセージ キューを調べることはできない。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::Send、IDirectPlay4::SendEx


IDirectPlay4::GetPlayerAccount

IDirectPlay4::GetPlayerAccount メソッドは、セキュア セッションでセッションのホストから呼び出して、指定したプレーヤーに関するアカウント情報を取得できる。

HRESULT GetPlayerAccount(
  DPID idPlayer,
  DWORD dwFlags,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

idPlayer
アカウント情報を取得するプレーヤーの ID。
dwFlags
使用しない。0 に設定しておく。
lpData
アカウント データが書き込まれているバッファ (アプリケーションにより割り当てられた) へのポインタ。DPACCOUNTDESC 構造体は、構造体のメンバにより参照されるデータと共にコピーされる。そのため、コピーされるバイト数は可変となる。名前を読み取るには、lpData パラメータを LPDPACCOUNTDESC にキャストする。アプリケーションでは、NULL を指定して、必要なバイト数を lpdwDataSize パラメータに設定するように要求できる。その後、その領域を割り当て、このメソッドを再度呼び出すことができる。
lpdwDataSize
バッファのサイズを指定して初期化された DWORD へのポインタ。メソッドが戻ると、lpdwDataSize には実際にバッファにコピーされたバイト数が設定される。バッファが小さすぎる場合、メソッドからは DPERR_BUFFERTOOSMALL が返され、lpdwDataSize には必要な最低バッファ サイズが設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

GetPlayerAccount から返される情報では、アカウントが一意に識別される。この情報を使用して、ログオンしたプレーヤーのトランザクションやその他のアクティビティを記録できる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::SecureOpen


IDirectPlay4::GetPlayerAddress

IDirectPlay4::GetPlayerAddress メソッドは、プレーヤーの DirectPlay アドレスを取得する。

DirectPlay アドレスは、特定のサービス プロバイダを使用しているプレーヤーのネットワーク アドレスである。IDirectPlay4::GetPlayerAddress により取得されたバッファを解析するには、IDirectPlayLobby3::EnumAddress メソッドを呼び出す。

このメソッドをローカル プレーヤーに対して呼び出すと、そのコンピュータのネットワーク アドレスが取得可能であればそれが返される。場合によっては、複数のアドレスが返されることもある (たとえば、ネットワーク カードとダイヤルアップ インターネット接続の両方が搭載されているコンピュータの TCP/IP の場合など)。

HRESULT GetPlayerAddress(
  DPID idPlayer,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

idPlayer
アドレスを要求するプレーヤーの ID。0 を指定すると、サービス プロバイダの有効なアドレス オプションのリストが取得できる (たとえば、モデム間サービス プロバイダの有効なモデム オプションのリストなど)。
lpData
DirectPlay アドレスを書き込むバッファへのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに必要なサイズに設定される。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータには DirectPlay アドレス データのサイズがバイト単位で設定されている。バッファが小さすぎる場合、このパラメータには必要なバッファ サイズが設定され、メソッドからは DPERR_BUFFERTOOSMALL が返される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

要求されたプレーヤー ID のアドレスが取得できない場合は、DPERR_UNAVAILABLE を返す。

注意

有効なモデム オプションのリストを取得するには、idPlayer パラメータに 0 を指定する。モデム オプションのリストは、ANSI 文字列または Unicode 文字列のリストで、終端に長さが 0 の文字列が設定されて返される。

このメソッドを呼び出したときのインタフェースに関係なく、DirectPlay アドレスにはアドレスと共に ANSI 文字列と Unicode 文字列の両方が設定される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::EnumAddress、DirectPlay アドレス


IDirectPlay4::GetPlayerCaps

IDirectPlay4::GetPlayerCaps メソッドは、指定されたプレーヤーの現在の能力を取得する。

HRESULT GetPlayerCaps(
  DPID idPlayer,
  LPDPCAPS lpPlayerCaps,
  DWORD dwFlags
);

パラメータ

idPlayer
能力を計算するプレーヤーの ID。
lpPlayerCaps
能力を指定する DPCAPS 構造体へのポインタ。DPCAPS 構造体の dwSize メンバは、IDirectPlay4::GetPlayerCaps を使用する前に指定する必要がある。
dwFlags
このパラメータに 0 を設定した場合、保証なしのメッセージ処理の能力が計算される。
DPGETCAPS_GUARANTEED
保証付きのメッセージ処理の能力を取得する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

IDirectPlay4::GetCaps メソッドがカレント セッションの能力を返すのに対して、このメソッドは要求されたプレーヤーの能力を返す。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPCAPS、IDirectPlay4::GetCaps、IDirectPlay4::Send


IDirectPlay4::GetPlayerData

メソッドは、IDirectPlay4::SetPlayerData を使用してプレーヤー ID に関連付けられたアプリケーション固有のデータ ブロックを取得する。

HRESULT GetPlayerData(
  DPID idPlayer,
  LPVOID lpData,
  LPDWORD lpdwDataSize,
  DWORD dwFlags
);

パラメータ

idPlayer
データを要求するプレーヤー ID。
lpData
アプリケーション固有のプレーヤー データを書き込むバッファへのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに必要なサイズに設定される。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータにはプレーヤー データのサイズがバイト単位で設定されている。バッファが小さすぎる場合 (DPERR_BUFFERTOOSMALL)、このパラメータには必要なバッファのサイズが設定される。
dwFlags
このパラメータに 0 を設定した場合、リモート データが取得される。
DPGET_LOCAL
アプリケーションにより設定されたローカル データを取得する。
DPGET_REMOTE
リモートの共有データ領域からカレント データを取得する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

注意

DirectPlay では、ローカルとリモートの両方のプレーヤー データを保守できる。アプリケーションは、検索するデータのタイプを指定する必要がある。ローカル データは、この DirectPlay オブジェクトにより DPSET_LOCAL フラグを使用して設定されている。リモート データは、セッション内の任意のアプリケーションにより DPSET_REMOTE フラグを使用して設定されている可能性がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::SetPlayerData


IDirectPlay4::GetPlayerFlags

IDirectPlay4::GetPlayerFlags メソッドは、プレーヤーについて記述しているフラグを返す。

HRESULT GetPlayerFlags(
  DPID idPlayer,
  LPDWORD lpdwFlags
);

パラメータ

idPlayer
フラグ設定を取得するプレーヤーの ID。
lpdwFlags
プレーヤーのフラグ設定が設定される DWORD へのポインタ。次のいずれかまたはいくつかを設定する。
DPPLAYER_LOCAL
プレーヤーはこのアプリケーションにより作成された。このフラグが指定されない場合、プレーヤーはリモート グループである。
DPPLAYER_SERVERPLAYER
プレーヤーは、クライアント／サーバー通信のサーバー プレーヤーである。
DPPLAYER_SPECTATOR
プレーヤーは、観客として作成された。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::CreatePlayer


IDirectPlay4::GetPlayerName

IDirectPlay4::GetPlayerName メソッドは、プレーヤーに関連付けられている名前を返す。

HRESULT GetPlayerName(
  DPID idPlayer,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

idPlayer
名前が要求されているプレーヤーの ID。
lpData
名前データを書き込むバッファへのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに必要なサイズに設定される。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータには名前データのサイズがバイト単位で設定されている。バッファが小さすぎる場合 (DPERR_BUFFERTOOSMALL)、このパラメータには必要なバッファのサイズが設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

注意

メソッドが戻ったら、ポインタ lpData を DPNAME 構造体にキャストして、グループ名データを読み取る必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPNAME、IDirectPlay4::SetPlayerName


IDirectPlay4::GetSessionDesc

IDirectPlay4::GetSessionDesc メソッドは、現在開いているセッションのプロパティを取得する。

HRESULT GetSessionDesc(
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

lpData
セッション記述データを書き込むバッファへのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに必要なサイズに設定される。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータにはセッション データのサイズがバイト単位で設定されている。バッファが小さすぎる場合 (DPERR_BUFFERTOOSMALL)、このパラメータには必要なバッファのサイズが設定される。このパラメータに NULL を指定すると、メソッドから DPERR_INVALIDPARAM が返される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION

注意

このメソッドが返されたら、ポインタ lpData を DPSESSIONDESC2 構造体にキャストして、セッション記述データを読み取る必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPSESSIONDESC2、IDirectPlay4::EnumSessions、IDirectPlay4::Open


IDirectPlay4::Initialize

IDirectPlay4::Initialize メソッドは、COM プロトコルに準拠するために用意されている。

HRESULT Initialize(
  LPGUID lpGUID
);

パラメータ

lpGUID
インタフェース識別子として使用されるグローバル ユニーク識別子 (GUID) へのポインタ。

戻り値

DPERR_ALREADYINITIALIZED を返す。

注意

DirectPlay オブジェクトは作成時に初期化されるので、このメソッドは戻り値として必ず DPERR_ALREADYINITIALIZED を返す。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IUnknown::AddRef、IUnknown::QueryInterface


IDirectPlay4::InitializeConnection

IDirectPlay4::InitializeConnection メソッドは、DirectPlay 接続を初期化する。使用するサービス プロバイダ、サーバーのネットワーク アドレス、セッションの GUID など、接続に関するすべての情報が、lpConnection パラメータを介して渡される

HRESULT InitializeConnection(
  LPVOID lpConnection,
  DWORD dwFlags
);

パラメータ

lpConnection
DirectPlay アドレスとして初期化する接続に関するすべての情報が格納されるバッファへのポインタ。
dwFlags
使用しない。0 に設定しておく。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ALREADYINITIALIZED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

InitializeConnection が以前にこのオブジェクトについて呼び出されたことがある場合は、DPERR_ALREADYINITIALIZED を返す。サービス プロバイダを初期化できない場合は、DPERR_UNAVAILABLE を返す。このような事態は、このサービス プロバイダを操作するために必要なリソースが存在しないために発生することがある (たとえば、TCP/IP スタックが存在しない場合など)。

注意

このメソッドで指定する lpConnection パラメータは、IDirectPlay4::EnumConnections メソッドから取得するか、またはアプリケーションでIDirectPlayLobby3::CreateCompoundAddress メソッドを使用して直接作成できる。

このメソッドは、該当するサービス プロバイダをロードして初期化する。このサービス プロバイダに lpConnection パラメータを渡し、関連情報を抽出して保存する。この情報は、サービス プロバイダでその情報を入力するためのダイアログ ボックスを表示しないで IDirectPlay4::EnumSessions メソッドまたは IDirectPlay4::Open メソッドを呼び出すときに使用される。

このメソッドは DirectPlayCreate の代わりに使用して、サービス プロバイダを DirectPlay オブジェクトにバインドすることができる。InitializeConnection の主な利点は、サービス プロバイダのダイアログ ボックスを上書きして、ロビー プロバイダを初期化できることにある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::EnumConnections、IDirectPlayLobby3::CreateCompoundAddress、DirectPlay アドレス


IDirectPlay4::Open

IDirectPlay4::Open メソッドは、IDirectPlay4::EnumSessions メソッドの呼び出しで列挙したセッションに参加したり、別のユーザーが列挙および参加できる新しいセッションを作成するときに使用される。

HRESULT Open(
  LPDPSESSIONDESC2 lpsd,
  DWORD dwFlags
);

パラメータ

lpsd
作成または参加するセッションを記述した DPSESSIONDESC2 構造体へのポインタ。セッションに参加する場合は、dwSize、guidInstance、lpszPassword データ メンバのみを指定すればよい。列挙したセッションで DPSESSION_PASSWORD フラグが設定されている場合は、パスワードのみを指定すればよい。

セッションを作成する場合、アプリケーションで、作成するセッションのプロパティを使用して DPSESSIONDESC2 構造体をすべて設定する必要がある。guidInstance は、DirectPlay により作成される。

dwFlags
次のフラグのいずれかを 1 つだけ設定する。
DPOPEN_CREATE
アプリケーション セッションの新しいインスタンスを作成する。ローカル コンピュータが、セッションのネーム サーバー兼ホストになる。
DPOPEN_JOIN
アプリケーション セッションの既存のインスタンスに参加する。アプリケーションはプレーヤーを作成して、メッセージを送受信できる。
DPOPEN_RETURNSTATUS
このフラグを指定した場合は、接続の進行状況を示すダイアログ ボックスが表示されない。すぐに接続できない場合、メソッドは DPERR_CONNECTING エラーを返す。アプリケーションは、正常終了を示す DP_OK が返されるか、またはエラーを示すそのほかのエラー コードが返されるまで Open を呼び出し続ける必要がある。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTCREATEPLAYER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_ENCRYPTIONNOTSUPPORTED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_NOSESSIONS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

この DirectPlay オブジェクトでセッションが既に開かれている場合は、DPERR_ALREADYINITIALIZED を返す。

セッション記述の最大プレーヤー数に既に達している場合は、DPERR_CANTCREATEPLAYER を返す。

セッションから Open 要求へ応答が返されなかった場合は、DPERR_TIMEOUT を返す。

ユーザーが列挙要求を取り消した場合 (一般に、サービス プロバイダのダイアログボックスを取り消すことにより) は、DPERR_USERCANCEL を返す。

既存のセッションに参加するために呼び出されたが、セッションが内部セッション リストになかった場合 (またはセッションの guidInstance が破損していた場合) は、DPERR_NOSESSIONS を返す。

注意

アプリケーションがセッションに参加すると、プレーヤーを作成して、セッション内の別のプレーヤーと通信を開始することができる。ただし、IDirectPlay4::CreatePlayer メソッドを使用してローカル プレーヤーを作成するまでは、この DirectPlay オブジェクトでメッセージは受信されず、またメッセージを送信することはできない。

アプリケーションで同時に 2 つのセッションを開くには、DirectPlay オブジェクトを 2 つ作成して、それぞれに 1 つずつセッションを開く必要がある。

セッションに参加するには、DPSESSIONDESC2 構造体の dwSize メンバと guidInstance メンバを指定するだけでよい。セッションがパスワード保護とマークされていれば、lpszPassword メンバも指定する必要がある。列挙されたセッションでパスワードが必要な場合は、そのセッションに DPSESSION_PASSWORDREQUIRED フラグが設定される。

セキュア セッションに参加する場合は、SecureOpen を使用してログオン証明書を指定する必要がある。列挙されたセッションで証明書が必要な場合は、そのセッションに DPSESSION_SECURESERVER フラグが設定される。

DPSESSIONDESC2 構造体の DPSESSION_SECURESERVER フラグを指定すると、セッションはデフォルトのセキュリティ パッケージの NTLM(NT LAN Manager) で開かれる。別のセキュリティ パッケージを指定するには、SecureOpen を使用する。

アプリケーションでセッションに参加する場合、サーバーは Open 要求を拒否したり、それを無視することができる (Open が時間切れの場合)。新規プレーヤーが無効なセッション、参加が無効なセッション、プレーヤーの制限に達しているセッション、または不正なパスワードが指定されたセッションに参加しようとすると、DPERR_NONEWPLAYERS エラーまたは DPERR_INVALIDPASSWORD エラーが発生する。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPSESSIONDESC2、IDirectPlay4::Close、IDirectPlay4::SecureOpen、IDirectPlay4::EnumSessions


IDirectPlay4::Receive

IDirectPlay4::Receive メソッドは、メッセージ キューからメッセージを取得する。

HRESULT Receive(
  LPDPID lpidFrom,
  LPDPID lpidTo,
  DWORD dwFlags,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

lpidFrom
送信側プレーヤーの ID を受け取る変数のアドレス。DPRECEIVE_FROMPLAYER フラグを指定する場合、この変数は、このメソッドを呼び出す前にプレーヤー ID により初期化する必要がある。
lpidTo
受信側プレーヤーの ID を受け取る変数のアドレス。DPRECEIVE_TOPLAYER フラグを指定する場合、この変数は、このメソッドを呼び出す前にプレーヤー ID により初期化する必要がある。
dwFlags
次のコントロール フラグのいずれかまたはいくつかを設定できる。デフォルト (dwFlags = 0) では、最初の使用可能なメッセージが取得される。
DPRECEIVE_ALL
最初の使用可能なメッセージを返す。これがデフォルトである。
DPRECEIVE_PEEK
ほかのフラグにより指定されたようにメッセージを返すが、それをメッセージ キューから削除しない。このフラグは、lpData が NULL の場合に指定する必要がある。
DPRECEIVE_TOPLAYER および DPRECEIVE_FROMPLAYER
DPRECEIVE_TOPLAYER と DPRECEIVE_FROMPLAYER を両方とも指定した場合、Receive は 1) lpidTo により指定されたプレーヤーに送信されたメッセージと、2) lpidFrom により指定されたプレーヤーから送信されたメッセージのみを返す。ただし、これら両方の条件が満たされなければならない。

DPRECEIVE_TOPLAYER lpidTo により指定されたプレーヤーに送信されたメッセージのみを返す。

DPRECEIVE_FROMPLAYER のみを指定した場合、Receive は lpidFrom により指定されたプレーヤーから送信されたメッセージのみを返す。

DPRECEIVE_TOPLAYER も DPRECEIVE_FROMPLAYER も設定しない場合、Receive は最初に使用可能なメッセージを返す。

lpData
メッセージ データを書き込むバッファへのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに必要なサイズに設定される。プレーヤー ID が DPID_SYSMSGのプレーヤーからメッセージが送信されている場合、アプリケーションは lpData を DPMSG_GENERIC に設定し、dwType メンバを調べてシステム メッセージのタイプを調べてからそれを処理する。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された DWORD へのポインタ。メソッドが戻ると、このパラメータにはバッファにコピーされたバイト数が設定されている。バッファが小さすぎる場合 (DPERR_BUFFERTOOSMALL)、このパラメータには必要なバッファのサイズが設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOMESSAGES

注意

DPID_SYSMSG として定義されたプレーヤー ID から受信したメッセージは、セッションでアプリケーションに変更を通知するときに使用するシステム メッセージである。これらの場合、システム メッセージの lpData を DPMSG_GENERIC に設定し、dwType メンバを調べて何に固有のシステム メッセージかを調べる。

DPID_ALLPLAYERS として定義されたプレーヤー ID、またはグループ ID に送信されたメッセージは、送信元のプレーヤー ID から取得したかのように表示される。アプリケーションは、ローカル プレーヤーに送信されたメッセージのみを受信する。プレーヤーは、lpidFrom と lpidTo がポイントしている値が同じであるメッセージは受信できない。

セッション記述で DPSESSION_NOMESSAGEID を指定した場合、lpidFrom は必ず 0xFFFFFFFF となり、また lpidTo 値は任意となる。

DirectPlay に搭載されているサービス プロバイダはすべて、データを破損から守るために整合性チェックを行なう。Receive を使用して取得したメッセージは、破損していないと保証されている。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPMSG_GENERIC、IDirectPlay4::Send


IDirectPlay4::SecureOpen

IDirectPlay4::SecureOpen メソッドは、セキュア セッションを作成したり、そのセッションに参加したりする。セキュア セッションに参加するとき、このメソッドを使用してログオン証明書を指定する。

新しいセッションを作成するとき、ホスト コンピュータは使用する代替セキュリティ パッケージを指定できる。セッションに参加するときは、ユーザー名とパスワードを指定できる。

HRESULT SecureOpen(
  LPCDPSESSIONDESC2 lpsd,
  DWORD dwFlags,
  LPCDPSECURITYDESC lpSecurity,
  LPCDPCREDENTIALS lpCredentials
);

パラメータ

lpsd
作成または参加するセッションについて記述した DPSESSIONDESC2 構造体へのポインタ。セッションに参加する場合、guidInstance メンバと lpszPassword メンバを指定するだけでよい。列挙されたセッションで DPSESSION_PASSWORDREQUIRED フラグが設定されている場合は、パスワードを指定するだけでよい。

セッションを作成する場合は、アプリケーションで、作成するセッションのプロパティを使用して DPSESSIONDESC2 構造体をすべて設定する必要がある。guidInstance は、DirectPlay により作成される。ただし、セッションを開こうとするコンピュータはすべて認証されていなければならないことを示すために、DPSESSION_SECURESERVER フラグを設定する必要がある。

DPSESSIONDESC2 構造体を設定する場合に DPSESSION_SECURESERVER フラグを指定しなければ、SecureOpen は Open が呼び出されたときと同じように非セキュア セッションを開く。

dwFlags
次のフラグのいずれかを指定する。
DPOPEN_CREATE
セキュア セッションの新しいインスタンスを作成する。
DPOPEN_JOIN
セキュア セッションの既存のインスタンスに参加する。
DPOPEN_RETURNSTATUS
このフラグを指定した場合は、接続の進行状況を示すダイアログ ボックスが表示されない。すぐに接続できない場合、メソッドは DPERR_CONNECTING エラーを返す。アプリケーションは、正常終了を示す DP_OK が返されるか、またはエラーを示すそのほかのエラー コードが返されるまで SecureOpen を呼び出し続ける必要がある。
lpSecurity
使用するセキュリティ パッケージが格納されている DPSECURITYDESC 構造体へのポインタ。デフォルトのセキュリティ パッケージ (NT LAN Manager) や CryptoAPI パッケージ (Microsoft RSA Base Cryptographic Provider) を使用するときは、このパラメータに NULL を設定する。これは、セッションを作成する場合にのみ関係がある。セッションに参加するときは NULL を設定しなければならない。
lpCredentials
サーバーで認証するログオン名、パスワード、ドメインが格納されている DPCREDENTIALS 構造体へのポインタ。証明書がない場合は、NULL を指定する。セッションを作成するとき、証明書は無視される。

戻り値

成功すれば DP_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_ENCRYPTIONNOTSUPPORTED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

無効な証明書を使用して呼び出された場合、または証明書が必要なのにそれを指定しないで呼び出された場合は、DPERR_LOGONDENIED を返す。アプリケーションはユーザーの証明書を収集して、SecureOpen を再度呼び出す必要がある。

注意

セッションに参加する場合、最初に証明書を指定しないで SecureOpen を呼び出す。メソッドから DPERR_LOGONDENIED が返されたら、ユーザーにユーザー名とパスワードを入力してもらって、ユーザーの証明書を lpCredentials パラメータに指定して SecureOpen を再度呼び出す必要がある。メソッドから DP_OK が返された場合、プレーヤーは前にシステム ログオン (NTLM でのネットワーク ログオン) 時に指定した証明書を使用してログオンできる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::Open


IDirectPlay4::Send

IDirectPlay4::Send メソッドは、メッセージをセッション内の別のプレーヤー、プレーヤーのグループ、またはすべてのプレーヤーに送信する。メッセージを別のプレーヤーに送信するには、その対象となるプレーヤーのプレーヤー ID を指定する。メッセージをプレーヤーのグループに送信するには、メッセージをグループに割り当てられたグループ ID に送信する。メッセージをセッション全体に送信するには、メッセージをプレーヤー ID の DPID_ALLPLAYERS に送信する。メッセージは、メッセージごとに保証付きプロトコルまたは保証なしプロトコルのいずれを使用しても送信できる。セッションが保証サーバーにある場合、メッセージはメッセージごとに暗号化して (プライバシーを保護するため)、またはデジタル署名をして (認証を行うため) 送信できる。

HRESULT Send(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPVOID lpData,
  DWORD dwDataSize
);

パラメータ

idFrom
送信側プレーヤーの ID。プレーヤー ID は、このコンピュータのローカル プレーヤーのいずかに対応していなければならない。
idTo
メッセージの送信先 ID。メッセージを別のプレーヤーに送信するには、プレーヤーの ID を指定する。メッセージをグループ内のすべてのプレーヤーに送信するには、グループの ID を指定する。メッセージをセッション内のすべてのプレーヤーに送信するには、定数記号の DPID_ALLPLAYERS を使用する。メッセージをサーバー プレーヤーに送信するには、定数記号の DPID_SERVERPLAYER を指定する。プレーヤーは、それ自体にメッセージを送信することはできない。
dwFlags
メッセージの送信方法を指定する。デフォルト (dwFlags = 0) では、メッセージは保証なしで送信される。
DPSEND_ENCRYPTED
メッセージを暗号化して送信する。これは、セキュア セッションでのみ行われる。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合にのみ使用できる。メッセージは、DPMSG_SECUREMESSAGE システム メッセージとして送信される。
DPSEND_GUARANTEED
保証付き配信方式を使用してメッセージを送信する。
DPSEND_SIGNED
デジタル署名を使用してメッセージを送信する。これは、セキュア セッションでのみ行うことができる。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合にのみ使用できる。メッセージは、DPMSG_SECUREMESSAGE システム メッセージとして送信される。
lpData
送信するデータへのポインタ。
dwDataSize
送信するデータの長さ。

戻り値

成功すれば DP_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG

保証付き配信方式を使用するように指定されていないメッセージに暗号化フラグや署名フラグが指定された場合は、DPERR_INVALIDPARAMS を返す。クライアント アプリケーションが最初にログオンしないで機密保護メッセージを送信しようとした場合は、DPERR_NOTLOGGEDIN を返す。

メッセージをグループに送信した場合、戻り値の DP_OK が、グループ内のすべてのプレーヤーがメッセージを受信したことを示すとは限らない。メッセージを保証付きで送信した場合、DP_OK は DirectPlay がメッセージをグループ内のすべてのプレーヤーに送信するように最善を尽くしたことを意味している。一般に、メッセージを受信していないプレーヤーは、その接続に問題があって削除されている。

注意

非同期送信オプションでは、IDirectPlay4::SendEx を使用すること。

メッセージは、保証付き、または保証なしで送信できる。デフォルトでは、メッセージは保証なしで送信される。つまり、DirectPlay は、メッセージが目的の受信者に届いているかどうかを検証しない。保証付きメッセージを送信すると、時間がかかる。少なくとも、保証なしメッセージの2～3倍の時間がかかる。アプリケーションは、できる限り保証付きメッセージの送信を少なくし、また喪失メッセージに耐えられるように設計する必要がある。DirectPlay に搭載されているサービス プロバイダはすべて、データを破損から守るために整合性チェックを行っている。このメソッドを使用して送信されたメッセージは、破損していないと保証される。

サービス プロバイダが保証付きメッセージをサポートしているかどうかに関係なく、また DirectPlay プロトコル フラグを設定しているかどうかに関係なく、システム メッセージは常に保証付きで送信される。保証付きシステム メッセージを送信するときは、DirectPlay プロトコルが自動的に使用される。

システム メッセージ以外で、アプリケーションが DirectPlay プロトコル フラグを設定して、メッセージを保証付きで送信した (DPSEND_GUARANTEED フラグを設定する) 場合、サービス プロバイダが保証付きメッセージをサポートしているかどうかに関係なく、そのメッセージは保証付きで送信される。

システム メッセージ以外で、アプリケーションが DirectPlay プロトコル フラグを設定しないで、メッセージを保証付きで送信した場合、そのメッセージは、サービス プロバイダが保証付きメッセージをサポートしているときのみ保証付きで送信される。サービス プロバイダがそれをサポートしていない場合、DPSEND_GUARANTEED フラグに関係なく、メッセージは保証付きで送信されない。

アプリケーションは、セッション作成時に DPSESSION_DIRECTPLAYPROTOCOL フラグを設定して DirectPlay プロトコルを起動する。

プレーヤーは、自分自身にメッセージを送信することはできない。プレーヤーが、DPID_ALLPLAYERS に含まれるグループや DPID_ALLPLAYERS にメッセージを送信した場合、プレーヤーにはそのメッセージのコピーが送信されない。ただし、セッション記述 (DPSESSIONDESC2) に DPSESSION_NOMESSAGEID が指定されている場合は例外である。この場合、プレーヤーはグループに送信したメッセージを受信できる。このメッセージには DirectPlay メッセージ ID ヘッダー (メッセージの送信者を示す) がないので、メッセージ ID に基づいてメッセージがフィルタリングされない。

DPSESSION_NOMESSAGEID を使用している場合、idFrom パラメータは意味がなくなり、また idTo パラメータは正しいターゲット コンピュータにメッセージを方向付けるためだけに使用される。ターゲット コンピュータに複数のプレーヤーがある場合は、メッセージを設定する受信キューを特定できない。メッセージは、受信されても DPID_UNKNOWN プレーヤーから送信されたものと表示される。

Send メソッドを使用して転送可能なメッセージのサイズには制限がない。DirectPlay は、サイズの大きなメッセージを自動的にいくつかのパケットに分割し、受信側でそれらを組み立てる。サイズの大きなメッセージを保証なしで送信する場合は、そのパケットのうち 1 つでも受信側に到達しなければ、メッセージ全体が無視される。アプリケーションは、GetCaps を呼び出して DPCAPS 構造体の dwMaxBufferSize メンバを調べることにより、1 つのパケットで送信可能なメッセージの最大サイズを判定できる。

暗号化メッセージや署名付きメッセージを送信した場合、そのメッセージはアプリケーション メッセージではなく、システム メッセージの DPMSG_SECUREMESSAGE として配布される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::Receive、IDirectPlay4::SendEx、IDirectPlay4::SendChatMessage、DPMSG_SECUREMESSAGE


IDirectPlay4::SendChatMessage

IDirectPlay4::SendChatMessage メソッドは、テキスト メッセージを別のプレーヤー、プレーヤーのグループ、またはすべてのプレーヤーに送信する。このメソッドは、Unicode 文字列 (IDirectPlay4 インターフェイス) と ANSI 文字列 (IDirectPlay4A インターフェイス) を両方ともサポートしている。チャット メッセージを受信したプレーヤーには、プレーヤーの受信キューの DPMSG_CHAT システム メッセージにより通知がある。このメソッドは、ロビー セッションで使用される。

HRESULT SendChatMessage(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPDPCHAT lpChatMessage
);

パラメータ

idFrom
送信側プレーヤーの ID。プレーヤー ID は、このコンピュータのローカル プレーヤーのいずかに対応していなければならない。
idTo
メッセージの送信先であるプレーヤーの ID またはプレーヤーのグループの ID、あるいはメッセージをセッション内のすべてのプレーヤーに送信するときは DPID_ALLPLAYERS。
dwFlags
メッセージの送信方法を指定する。このパラメータに 0 を設定した場合、メッセージは保証なしで送信される。
DPSEND_GUARANTEED
保証付き配信方式を使用できる場合は、それによりメッセージを送信する。
lpChatMessage
送信するメッセージが格納されている DPCHAT 構造体へのポインタ。

戻り値

成功すれば DP_OK、失敗すれば次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

idTo の ID が有効なプレーヤーまたはグループでない場合は、DPERR_INVALIDPARAMS を返す。idFrom の ID が有効なプレーヤーまたはグループでない場合は、DPERR_INVALIDPLAYER を返す。idFrom の ID がローカル プレーヤーでない場合は、DPERR_ACCESSDENIED を返す。

注意

このメソッドは、異なるクライアント アプリケーションを接続可能なロビー セッション内でのプレーヤー間のチャットを容易にする。このメソッドは、ロビー セッションで使用する。アプリケーション セッションでの使用は、オプションである。

受信側プレーヤーは、システム メッセージ (idFrom = DPID_SYSMSG) を受信する。DPCHAT 構造体は、チャット メッセージの送信元プレーヤーを指定する。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPCHAT、DPMSG_CHAT、IDirectPlay4::Send


IDirectPlay4::SendEx

IDirectPlay4::SendEx メソッドは、メッセージをセッション内の別のプレーヤー、プレーヤーのグループ、またはすべてのプレーヤーに送信する。SendEx は、Send メソッドを強化したものであり、使用可能なオプションも多い。SendEx では、保証付きメッセージと保証なしメッセージの両方をサポートしている。また、非同期メッセージを送信したり、メッセージの優先順位やタイムアウトを設定することもできる。

HRESULT SendEx(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwPriority,
  DWORD dwTimeout,
  LPVOID lpContext,
  LPDWORD lpdwMsgID
);

パラメータ

idFrom
送信側プレーヤーの ID。プレーヤー ID は、メッセージの送信元コンピュータのローカル プレーヤーのいずかに対応していなければならない。
idTo
メッセージの送信先 ID。メッセージを別のプレーヤーに送信するには、プレーヤーの ID を指定する。メッセージをグループ内のすべてのプレーヤーに送信するには、グループの ID を指定する。メッセージをセッション内のすべてのプレーヤーに送信するには、定数記号の DPID_ALLPLAYERS を使用する。メッセージをサーバー プレーヤーに送信するには、定数記号の DPID_SERVERPLAYER を指定する。プレーヤーが自分にメッセージを送信することはできない。
dwFlags
メッセージの送信方法を指定する。デフォルト (dwFlags = 0) では、メッセージは保証なしで送信される。
DPSEND_ASYNC
メッセージを非同期に送信する。関数はすぐに戻り、lpdwMsgID パラメータには値が設定されている。このフラグを指定しない場合、メッセージが送信される (保証付きで送信されている場合は、肯定応答を受け取る) まで関数は戻らない。送信が完了すると、DPMSG_SENDCOMPLETE システム メッセージが送られる。

このフラグを使用した場合、メッセージが送信キューに設定されたときは、戻り値が DPERR_PENDING となる。これは、致命的なエラーではなく、メッセージがすぐに送信されなかったことをユーザーにただ知らせるための戻り値である。

DPSEND_ENCRYPTED
メッセージを暗号化して送信する。これは、セキュア セッションでのみ行われる。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合にのみ使用できる。メッセージは、DPMSG_SECUREMESSAGE システム メッセージとして送信される。
DPSEND_GUARANTEED
保証付き配信方式が使用可能な場合、それによりメッセージを送信する。
DPSEND_NOSENDCOMPLETEMSG
このフラグを設定した場合、未完了メッセージが送信される。このフラグは、DPSEND_ASYNC フラグも設定されている場合にのみ使用できる。
DPSEND_SIGNED
デジタル署名を使用してメッセージを送信する。これは、セキュア セッションでのみ行うことができる。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合にのみ使用できる。メッセージは、DPMSG_SECUREMESSAGE システム メッセージとして送信される。
lpData
送信するデータへのポインタ。
dwDataSize
送信するデータの長さ。
dwPriority
メッセージの優先順位で、範囲は 0～65535 である。0 が最低の優先順位のメッセージとなる。値が大きければ大きいほど、メッセージの優先順位は高くなる。キューの中に、ここで指定した優先順位より高い優先順位のメッセージがない場合にのみ、そのメッセージが送信される。

メモ すべてのサービス プロバイダでこのオプションがサポートされているとは限らない。これがサポートされていない場合、0 以外の優先順位を指定すると、DPERR_UNSUPPORTED エラーが返される。このオプションがサポートされているかどうかを判定するには、GetCaps を呼び出す。

dwTimeout
メッセージ配信時の時間制限をアプリケーションがオプションで指定するタイムアウト (ミリ秒単位)。この時間内にメッセージを配信できない場合、そのメッセージは自動的に取り消されて、DPMSG_SENDCOMPLETE メッセージが送信される。0 は、タイムアウトを使用することを示す。

メモ すべてのサービス プロバイダでこのオプションがサポートされているとは限らない。サポートされていない場合、0 以外のタイムアウトを指定すると、DPERR_UNSUPPORTED エラーが返される。このオプションがサポートされているかどうかを判定するには、GetCaps を呼び出す。

lpContext
アプリケーションにより定義されたコンテキストで、送信が完了したときに完了メッセージの一部としてアプリケーションに返されるもの。NULL も設定できる。
lpdwMsgID
DirectPlay によりメッセージ用に生成された ID が設定される DWORD へのポインタ。この ID は、メッセージのステータスを調べたり、それを取り消すときに使用する。メッセージ ID が必要ない場合は、NULL を指定する。このパラメータは、非同期メッセージの場合にのみ返される。

戻り値

同期メッセージの場合は、処理が成功すると DP_OK を返す。非同期メッセージの場合は、送信処理でメッセージをキューに設定できると DPERR_PENDING を返す。ユーザーは、DPMSG_SENDCOMPLETE メッセージから完了情報を取得する。それ以外の場合は、次のエラー値のいずれかかを返す。

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_INVALIDPRIORITY
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG
DPERR_UNSUPPORTED

保証付きとして指定されていないメッセージに暗号化フラグや署名付きフラグが指定された場合、または非同期でないメッセージに DPSEND_NOCOMPLETEMSG フラグが指定された場合は、DPERR_INVALIDPARAMS を返す。優先順位が 0～65535 の範囲内にない場合は、DPERR_INVALIDPRIORITY を返す。0 以外の優先順位が指定された場合にサービス プロバイダが優先順位をサポートしていないとき、または 0 以外のタイムアウトが指定された場合にサービス プロバイダがこのオプションをサポートしていないときは、DPERR_NOTSUPPORTED を返す。

注意

DirectPlay プロトコルがセッション記述に指定されている (DPSESSIONDESC2 構造体の DPSESSION_DIRECTPLAYPROTOCOL フラグを設定することにより) 場合、SendEx のすべてのオプションを使用できる。それ以外の場合、アプリケーションは GetCaps を呼び出してサービス プロバイダで実装されているオプションを判定する必要がある。SendEx は、保証付きメッセージと保証なしメッセージの両方をサポートしている。保証付きで送信されたメッセージは、受信側からの肯定応答を待っているペンディング状態のメッセージがあってもブロックされない。

メッセージが非同期に送信された (DPSEND_ASYNC フラグを設定することにより) 場合、そのメッセージは送信キューに設定されて、SendEx 関数はすぐに戻る。システム メッセージ (DPMSG_SENDCOMPLETE) が送信側プレーヤーの受信キューに設定され、それにより送信結果が示される。

メッセージに優先順位を設定できる。メッセージは、送信されるのを待機しているメッセージの中に、それよりも優先順位が高いメッセージがなく、また使用可能な帯域幅がある場合に送信される。

メッセージのタイムアウトを指定できる。DirectPlay が指定された時間内にメッセージを配信できなかった場合、それは取り消される。

DPSESSION_NOPRESERVEORDER フラグがセッション記述 (DPSESSIONDESC2) に設定されているために、保証付きメッセージの配布順序が保持されない場合、DPSEND_SIGNED フラグや DPSEND_ENCRYPTED フラグを使用することはできない。

さまざまな優先順位を指定してメッセージを送信した場合は、署名や暗号が機能しない。アプリケーションでは、機密保護メッセージの優先順位を 1 つに決定し、またその優先順位でのみセキュリティ フラグを使用するとよい。これは、機密保護メッセージの検証がその受信順序に基づいて行われ、また優先順位を設定するとその順序が変更される可能性があるためである。

DirectPlay プロトコルは、アクティブな場合、送信方向のネットワーク トラフィックを抑制しようとする。つまり、必ずしもできる限り速くパケットを送信するわけではない。それは、受信側コンピュータの受信方向の帯域幅に影響を与えない範囲でできる限り速くパケットを送信する。

サービス プロバイダが保証付きメッセージをサポートしてるかどうかに関係なく、また DirectPlay プロトコル フラグを設定しているかどうかに関係なく、システム メッセージは常に保証付きで送信される。保証付きシステム メッセージを送信すると、DirectPlay プロトコルが自動的に使用される。

システム メッセージ以外で、アプリケーションが DirectPlay プロトコル フラグを設定して、メッセージを保証付きで送信した (DPSEND_GUARANTEED フラグを設定することにより) 場合、サービス プロバイダが保証付きメッセージをサポートしているかどうかに関係なく、そのメッセージは保証付きで送信される。

システム メッセージ以外で、アプリケーションが DirectPlay プロトコル フラグを設定しないで、メッセージを保証付きで送信した場合、そのメッセージは、サービス プロバイダが保証付きメッセージをサポートしているときのみ保証付きで送信される。サービス プロバイダがそれをサポートしていない場合、DPSEND_GUARANTEED フラグに関係なく、メッセージは保証付きで送信されない。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::Send、IDirectPlay4::CancelMessage、IDirectPlay4::CancelPriority、IDirectPlay4::GetMessageQueue、DPMSG_SENDCOMPLETE


IDirectPlay4::SetGroupConnectionSettings

IDirectPlay4::SetGroupConnectionSettings メソッドは、このグループから起動されるセッションの接続設定を設定する。このメソッドは、ロビー セッションでのみ使用できる。

HRESULT SetGroupConnectionSettings(
  DWORD dwFlags,
  DPID idGroup,
  LPDPLCONNECTION lpConnection
);

パラメータ

dwFlags
使用しない。0 に設定しておく。
idGroup
接続設定を設定するグループの ID。
lpConnection
起動するアプリケーション、使用するサービス プロバイダ、作成するセッションのセッション記述を記述した DPLCONNECTION 構造体へのポインタ。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED

注意

DPLCONNECTION 構造体のメンバの中にデフォルト値 (NULL 以外または 0 以外) が既に設定されているものがあるかどうかを調べるには、SetGroupConnectionSettings を呼び出す前に IDirectPlay4::GetGroupConnectionSettings を呼び出す。デフォルト値が設定されている場合に、それらを変更しようとすると、エラーが返されることがある。

SetGroupConnectionSettingsにより DPLCONNECTION 構造体の lpAddress データ メンバや dwAddressSize データ メンバを設定する必要はない。DPLCONNECTION 構造体内の DPSESSIONDESC2 構造体の guidInstance メンバも指定する必要はない。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPLCONNECTION、IDirectPlayLobby3::RunApplication、IDirectPlay4::GetGroupConnectionSettings


IDirectPlay4::SetGroupData

IDirectPlay4::SetGroupData メソッドは、アプリケーション固有のデータ ブロックをグループ ID に関連付ける。グループに関連付けられたリモート データを変更できるのは、それを作成したコンピュータのみである。

HRESULT SetGroupData(
  DPID idGroup,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

パラメータ

idGroup
データを設定するグループ ID。
lpData
設定するデータへのポインタ。既存のグループ データをクリアするには、NULL を設定する。
dwDataSize
データ バッファのサイズ。lpData が NULL であり、このパラメータが 0 でない場合、メソッドは DPERR_INVALIDPARAMS を返す。
dwFlags
グループ データの伝播方法を示すフラグ。このパラメータに 0 を設定した場合、リモート グループ データは保証なしメッセージ方式で設定および伝播される。
DPSET_GUARANTEED
保証付きメッセージ方式 (可能な場合) によりデータを伝播する。このフラグは、DPSET_REMOTE でのみ使用できる。
DPSET_LOCAL
データはローカルにしか使用されず、伝播されない。
DPSET_REMOTE
このデータは、すべてのアプリケーションにより使用されるので、セッション内のその他すべてのアプリケーションに伝播される。このフラグは、ローカル セッションにより所有されているグループでのみ使用できる。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

注意

DirectPlay では、ローカルとリモートの両方のグループ データを保守できる。ローカル データは、ローカル コンピュータのアプリケーションでのみ使用できる。リモート データは、セッション内のその他すべてのアプリケーションに伝播される。セッション記述で DPSESSION_NODATAMESSAGES が設定されている場合を除き、すべてのプレーヤー (送信元のプレーヤーを含む) に変更を知らせる DPMSG_SETPLAYERORGROUPDATA システム メッセージが送信される。リソースへのポインタは、ローカル データに安全に保存できる。グループが壊れてもローカル データ ブロックは使用できる (DPMSG_DESTROYPLAYERORGROUP システム メッセージにおいて) ので、アプリケーションはそのリソースを解放できる。

このメソッドを使用すると、オーバヘッドが生じるので、リアルタイムの情報 (位置の更新など) を更新する場合は使用しないこと。IDirectPlay4::Send の方が、リアルタイムの情報を更新するには有効である。また、あまり頻繁に変更されず、また時間を重視しない (チーム カラーなど) 共有状態の情報については、IDirectPlay4::SetGroupData がより適している。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPMSG_SETPLAYERORGROUPDATA、IDirectPlay4::GetGroupData、IDirectPlay4::Send


IDirectPlay4::SetGroupName

IDirectPlay4::SetGroupName メソッドは、グループの作成後にその名前を設定する。グループの名前を設定できるのは、それを作成したコンピュータのみである。セッション記述で DPSESSION_NODATAMESSAGES が設定されている場合を除き、その他すべてのプレーヤーに、変更を知らせる DPMSG_SETPLAYERORGROUPNAME システム メッセージが送信される。

HRESULT SetGroupName(
  DPID idGroup,
  LPDPNAME lpGroupName,
  DWORD dwFlags
);

パラメータ

idGroup
名前を設定するグループ ID。
lpGroupName
グループの名前情報が格納されている DPNAME 構造体へのポインタ。グループに名前情報がない場合は、このパラメータに NULL を設定する。
dwFlags
このパラメータに 0 を設定した場合、名前は、保証なしメッセージ方式ですべてのリモート システムに伝播される。この値は、ローカル セッションにより所有されているグループでのみ使用できる。
DPSET_GUARANTEED
保証付きメッセージ方式 (可能な場合) によりデータを伝播する。
DPSET_LOCAL
データはローカルにしか使用されず、伝播されない。
DPSET_REMOTE
このデータは、すべてのアプリケーションにより使用されるので、セッション内のその他すべてのアプリケーションに伝播される。このフラグは、ローカル セッションにより所有されているグループでのみ使用できる。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPNAME、DPMSG_SETPLAYERORGROUPNAME、IDirectPlay4::GetGroupName、IDirectPlay4::Send


IDirectPlay4::SetGroupOwner

IDirectPlay4::SetGroupOwner メソッドは、グループの所有者を変更する。このメソッドは、ロビー セッションでのみ使用できる。DPMSG_SETGROUPOWNER システム メッセージが生成される。

HRESULT SetGroupOwner(
  DPID idGroup,
  DPID idOwner
);

パラメータ

idGroup
所有者を変更するグループの ID。
idOwner
グループの所有者として設定するプレーヤーの ID。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_GENERIC
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

セッションがロビー セッションでない場合は、DPERR_UNAVAILABLE を返す。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::GetGroupOwner、DPMSG_SETGROUPOWNER


IDirectPlay4::SetPlayerData

IDirectPlay4::SetPlayerData メソッドは、アプリケーション固有のデータ ブロックをプレーヤー ID に関連付ける。

HRESULT SetPlayerData(
  DPID idPlayer,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

パラメータ

idPlayer
データを設定するプレーヤーの ID。
lpData
設定するデータへのポインタ。既存のプレーヤー データをクリアするには、このパラメータに NULL を、dwDataSize に 0 を設定する。
dwDataSize
データ バッファのサイズ。lpData が NULL であり、このパラメータが 0 でない場合、メソッドは DPERR_INVALIDPARAMS を返す。
dwFlags
このパラメータに 0 を設定した場合、リモート プレーヤー データは保証なしメッセージ方式で設定および伝播される。
DPSET_GUARANTEED
保証付きメッセージ方式 (可能な場合) によりデータを伝播する。このフラグは、DPSET_REMOTE でのみ使用できる。
DPSET_LOCAL
このデータはローカルにしか使用されず、伝播されない。
DPSET_REMOTE
このデータは、すべてのアプリケーションにより使用されるので、セッション内のその他すべてのアプリケーションに伝播される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

SetPlayerData を使用すると、オーバヘッドが生じるので、リアルタイムの情報 (位置の更新など) を更新する場合は使用しないこと。このような処理には、Send の方が有効である。また、あまり頻繁に変更されず、時間を重視しない (プレーヤーの名前など) 共有状態の情報については、SetPlayerData の方が適している。

DirectPlay では、ローカルとリモートの両方のプレーヤー データを保守できる。ローカル データは、ローカル コンピュータのアプリケーションでのみ使用できる。リモート データは、セッション内のその他すべてのアプリケーションに伝播される。リモート プレーヤーのプレーヤー データを設定しようとすると、DPERR_ACCESSDENIED が返される。セッション記述で DPSESSION_NODATAMESSAGES が設定されている場合を除き、すべてのプレーヤー (送信元のプレーヤーを含む) に、変更を知らせる DPMSG_SETPLAYERORGROUPDATA システム メッセージが送信される。リソースへのポインタは、ローカル データに保存すれば安全である。プレーヤーが壊れてもローカル データ ブロックは使用できる (DPMSG_DESTROYPLAYERORGROUP システム メッセージにおいて) ので、アプリケーションはそのリソースを解放できる。システム メッセージのリストについては、「システム メッセージの使用」を参照すること。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPMSG_SETPLAYERORGROUPDATA、IDirectPlay4::GetPlayerData、IDirectPlay4::Send


IDirectPlay4::SetPlayerName

IDirectPlay4::SetPlayerName メソッドは、ローカル プレーヤーの作成後にその名前を設定する。プレーヤーの名前を設定できるのは、それを作成したコンピュータのみである。セッション記述で DPSESSION_NODATAMESSAGES が設定されている場合を除き、その他すべてのプレーヤーに、変更を知らせる DPMSG_SETPLAYERORGROUPNAME システム メッセージが送信される。

HRESULT SetPlayerName(
  DPID idPlayer,
  LPDPNAME lpPlayerName,
  DWORD dwFlags
);

パラメータ

idPlayer
データを送信するローカル プレーヤーの ID。
lpPlayerName
プレーヤーの名前情報が格納されている DPNAME 構造体へのポインタ。プレーヤーに名前情報がない場合は、このパラメータに NULL を設定する。
dwFlags
名前の伝播方法を示すフラグ。次のいずれかの値を指定できる。
DPSET_GUARANTEED
保証付きメッセージ方式 (可能な場合) によりデータを伝播する。
DPSET_LOCAL
データはその他のプレーヤーに伝播されない。
DPSET_REMOTE
保証なしメッセージ方式で、セッション内のすべてのプレーヤーにデータを伝播する。これがデフォルト値である。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CONNECTIONLOST
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPNAME、DPMSG_SETPLAYERORGROUPNAME、IDirectPlay4::GetPlayerName、IDirectPlay4::Send


IDirectPlay4::SetSessionDesc

IDirectPlay4::SetSessionDesc メソッドは、カレント セッションのプロパティを変更する。セッション プロパティを変更できるのは、セッションのホストだけである。ホスト以外からこのメソッドを呼び出そうとすると、DPERR_ACCESSDENIED が返される。

更新されたセッション記述が、セッション内のその他すべてのコンピュータに伝播される。各プレーヤーには、DPMSG_SETSESSIONDESC システム メッセージが送信される。

SetSessionDesc は、ロビー セッションでは使用できない。

HRESULT SetSessionDesc(
  LPDPSESSIONDESC2 lpSessDesc,
  DWORD dwFlags
);

パラメータ

lpSessDesc
新しい設定値が格納されている DPSESSIONDESC2 構造体へのポインタ。
dwFlags
現在、このメソッドでフラグは使用されていない。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

このコンピュータにセッションを変更する権限がない場合は、DPERR_ACCESSDENIED を返す。セッション プロパティを変更できるのはホストだけである。アプリケーションが変更不可能なセッション記述のプロパティを変更しようとした場合、またはプロパティに無効な値を指定した場合は、DPERR_INVALIDPARAMS を返す。

注意

セッション記述を変更すると、DPMSG_SETSESSIONDESC システム メッセージがセッション内のその他すべてのコンピュータで生成される。

DPSESSIONDESC2 構造体の次のメンバとフラグは、IDirectPlay4::SetSessionDesc を使用して変更できる。

dwFlags
DPSESSION_JOINDISABLED

DPSESSION_NEWPLAYERSDISABLED

DPSESSION_NODATAMESSAGES

DPSESSION_PRIVATE

dwMaxPlayers
最大プレーヤー数に現在のプレーヤー数よりも少ない値を設定すると、DPERR_INVALIDPARAMS が返される。
lpszSessionName / lpszSessionNameA
lpszPassword / lpszPasswordA
dwUser1
dwUser2
dwUser3
dwUser4

DPSESSIONDESC2 構造体の次のメンバとフラグが変更されると、エラーが発生する (たとえば、DPSESSION_KEEPALIVE フラグが現在設定さている場合に、このビットを設定しようとしてもエラーは発生しないが、そのビットをクリアしようとするとエラーが発生し、IDirectPlay4::SetSessionDesc は失敗する)。

dwSize
dwFlags
DPSESSION_NOMESSAGEID

DPSESSION_KEEPALIVE

DPSESSIONDESC2 構造体の次のメンバは無視される (つまり、このメンバに何を指定しても、DirectPlay は必ず IDirectPlay4::Open が呼び出されたときに渡された値を使用する)。

guidInstance
guidApplication
dwCurrentPlayers
dwReserved1
dwReserved2

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPSESSIONDESC2、IDirectPlay4::GetSessionDesc


IDirectPlay4::StartSession

IDirectPlay4::StartSession メソッドは、ステージング領域から DirectPlay セッションを起動する。まず、SetGroupConnectionSettings を呼び出して起動するアプリケーション、使用するサービス プロバイダ、および使用するセッション記述を指定する。

StartSession が呼び出されると、グループ内の各プレーヤーは、プレーヤーにセッションを起動するように指示された DPMSG_STARTSESSION を受信する。

HRESULT StartSession(
  DWORD dwFlags,
  DPID idGroup
);

パラメータ

dwFlags
使用しない。0 に設定しておく。
idGroup
セッション起動コマンドを送信するグループの ID。グループは、ステージング領域でなければならない。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

指定されたグループ ID が有効なステージング領域でない場合は、DPERR_INVALIDGROUP を返す。

注意

セッションが既に起動されているステージング領域グループに参加するプレーヤーは、このメソッドを呼び出せばセッションに参加できる。プレーヤーは、セッションへの参加方法を指示した DPMSG_STARTSESSION メッセージを受け取る。

IDirectPlay4::GetGroupConnectionSettings を呼び出して、DPLCONNECTION 構造体のポインタを介して DPSESSIONDESC2 構造体に返される guidInstance パラメータを調べると、セッションが既に処理されているかどうかを判定できる。guidInstance が GUID_NULL の場合、処理中のセッションはない。その他の値の場合、セッションは既に処理されている。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

同期起動


IDirectPlayLobby3

アプリケーションは、IDirectPlayLobby3 インターフェイスの各メソッドを使用して、アプリケーションやそれに関連付けられているデータを管理する。ここでは、IDirectPlayLobby3 インターフェイスの各メソッドのリファレンスを提供します。

IDirectPlayLobby3 インターフェイスのメソッドは、以下のグループにまとめることができる。

アドレス管理 | CreateAddress
 | CreateCompoundAddress
 | EnumAddress
 | EnumAddressTypes
アプリケーション管理 | Connect
 | ConnectEx
 | EnumLocalApplications
 | RegisterApplication
 | RunApplication
 | UnregisterApplication
 | WaitForConnectionSettings
データ管理 | GetConnectionSettings
 | ReceiveLobbyMessage
 | SendLobbyMessage
 | SetConnectionSettings
 | SetLobbyMessageEvent

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。


IDirectPlayLobby3::Connect

IDirectPlayLobby3::Connect メソッドは、DirectPlayLobby オブジェクトで現在格納されている DPLCONNECTION 構造体により指定されたセッションにアプリケーションを接続する。

メモ このメソッドは、IDirectPlay2 または IDirectPlay2A インターフェイスを返す。これが目的の DirectPlay COM インターフェイスでない場合 (たとえば、IDirectPlay4 または IDirectPlay4A)、アプリケーションは QueryInterface を使用してカレント インターフェイスを取得し、このインターフェイスを解放する必要がある。最新メソッドの IDirectPlayLobby3::ConnectEx を使用すると、アプリケーションで返される DirectPlay COM インターフェイスを指定できる。

Connect は、デフォルトでは、接続された後、または接続が時間切れになったときに戻る。DPCONNECT_RETURNSTATUS フラグを使用した場合、Connect はすぐに戻り、そのとき接続が処理中であることを示す DPERR_CONNECTING エラー コードが返される。アプリケーションは、DP_OK または障害コードが返されるまで、このメソッドを定期的に呼び出し続ける必要がある。アプリケーションは、IDirectPlayLobby3 インターフェイスを解放することで接続を取り消すことができる。

HRESULT Connect(
  DWORD dwFlags,
  LPDIRECTPLAY2 *lplpDP,
  IUnknown FAR *pUnk
);

パラメータ

dwFlags
接続方法を示すフラグ。デフォルト (dwFlags = 0) では、接続が確立されるか、または処理が時間切れになると、メソッドが返される。
DPCONNECT_RETURNSTATUS
メソッドはすぐに戻り、そのとき接続のステータスが返される。アプリケーションは、正常終了を示すコードまたは障害コードが返されるまで、Connect を呼び出し続ける必要がある。
lplpDP
IDirectPlay2(IDirectPlayLobby3 で呼び出された場合) または IDirectPlay2A(IDirectPlayLobby3A で呼び出された場合) のいずれかの有効なインターフェイスにより初期化されたポインタへのポインタ。ただし、その他のインターフェイスを希望する場合は、アプリケーションで QueryInterface を使用して新規インターフェイスへのポインタを取得し、それを解放すること。あるいは、ConnectEx メソッドを使用してもよい。
pUnk
含まれている IUnknown インターフェイスへのポインタ。このパラメータは、将来 COM 集合化機能と互換性をとるために用意されている。ただし、現在はこのパラメータに NULL 以外の値を指定すると IDirectPlayLobby3::Connect からエラーが返される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

CLASS_E_NOAGGREGATION
DPERR_CONNECTING
DPERR_INVALIDFLAGS
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY

接続処理が実行されている間は DPERR_CONNECTING を返す。最新のステータスを取得するには、メソッドを再度呼び出す。

注意

接続のタイムアウトの上限は 1 分である。

このメソッドが正常に終了した後は、アプリケーションで IDirectPlay4::InitializeConnection、IDirectPlay4::EnumSessions、IDirectPlay4::Open を呼び出す処理を省略できる。アプリケーションはユーザーに名前を問い合わせるのではなく、DPLCONNECTION 構造体のプレーヤー名情報を使用してプレーヤーを作成する。

アプリケーションは、このメソッドを呼び出す前に、IDirectPlayLobby3::GetConnectionSettings メソッドを使用してアプリケーションを起動するときに使用された接続設定を調べることができる。続いて、IDirectPlayLobby3::SetConnectionSettings メソッドによりそれらの設定値を変更し、設定できる。ただし、適切なセッション プロパティが設定されていることを確認するために、DPSESSIONDESC2 構造体、特に dwFlags、dwMaxPlayers、dwUser メンバに注意する必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::ConnectEx


IDirectPlayLobby3::ConnectEx

IDirectPlayLobby3::ConnectEx メソッドは、DirectPlayLobby オブジェクトで現在格納されている DPLCONNECTION 構造体により指定されたセッションにアプリケーションを接続する。

このメソッドは、Connect メソッドを拡張したものである。これを使用すると、アプリケーションで返される DirectPlay\ COM インターフェイスのバージョンを指定できる。

ConnectEx は、デフォルトでは、接続された後、または接続が時間切れになった後に戻る。DPCONNECT_RETURNSTATUS フラグを使用した場合、ConnectEx はすぐに戻り、そのとき接続が処理中であることを示す DPERR_CONNECTING エラー コードが返される。アプリケーションは、DP_OK または障害コードが返されるまで、このメソッドを定期的に呼び出し続ける必要がある。アプリケーションは、IDirectPlayLobby3 インターフェイスを解放することで接続を取り消すことができる。

HRESULT ConnectEx(
  DWORD dwFlags,
  REFIID riid,
  LPVOID *lplpDP,
  IUnknown FAR *pUnk
);

パラメータ

dwFlags
接続方法を示すフラグ。デフォルト (dwFlags = 0) では、接続が確立されるか、または処理が時間切れになった後、メソッドが返される。
DPCONNECT_RETURNSTATUS
メソッドはすぐに戻り、そのとき接続のステータスが返される。アプリケーションは、正常終了を示すコードまたは障害コードが返されるまで、ConnectEx を呼び出し続ける必要がある。
riid
返される特定の DirectPlay COM インターフェイスの IID。たとえば、IID_IDirectPlay4A となる。
lplpDP
riid パラメータにより指定された DirectPlay インターフェイスで初期化されたポインタへのポインタ。
pUnk
含まれている IUnknown インターフェイスへのポインタ。このパラメータは、将来 COM 集合化機能と互換性をとるために用意されている。ただし、現在はこのパラメータに NULL 以外の値を指定すると IDirectPlayLobby3::ConnectEx からエラーが返される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CONNECTING
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

接続処理が実行されている間は DPERR_CONNECTING を返す。最新のステータスを取得するには、メソッドを再度呼び出す。

注意

接続のタイムアウトの上限は 1 分である。

このメソッドか正常に終了した後は、アプリケーションで IDirectPlay4::InitializeConnection、IDirectPlay4::EnumSessions、IDirectPlay4::Open を呼び出す処理を省略できる。アプリケーションはユーザーに名前を問い合わせるのではなく、DPLCONNECTION 構造体のプレーヤー名情報を使用してプレーヤーを作成する。

アプリケーションは、このメソッドを呼び出す前に、IDirectPlayLobby3::GetConnectionSettings メソッドを使用してアプリケーションを起動するときに使用された接続設定を調べることができる。それから、IDirectPlayLobby3::SetConnectionSettings メソッドによりそれらの設定値を変更し、設定できる。ただし、適切なセッション プロパティが設定されていることを確認するために、DPSESSIONDESC2 構造体、特に dwFlags、dwMaxPlayers、dwUser メンバに注意する必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::ConnectEx

Built on 2000年4月13日


IDirectPlayLobby3::CreateAddress

IDirectPlayLobby3::CreateAddress メソッドは、サービス プロバイダに固有のネットワーク アドレスを指定して DirectPlay アドレスを作成する。結果出力されたアドレスには、サービス プロバイダのグローバル ユニーク識別子 (GUID) と、サービス プロバイダがネットワーク アドレスとして解釈可能なデータが含まれている。

ただし、IDirectPlayLobby3::CreateCompoundAddress では、複数のデータ チャンクを使用してアドレスを使用できる。そのため、IDirectPlayLobby3::CreateCompoundAddress を使用する必要がある。

HRESULT CreateAddress(
  REFGUID guidSP,
  REFGUID guidDataType,
  LPCVOID lpData,
  DWORD dwDataSize,
  LPVOID lpAddress,
  LPDWORD lpdwAddressSize
);

パラメータ

guidSP
サービス プロバイダの GUID へのポインタ (C++ の場合、これは GUID へのリファレンスである)。
guidDataType
使用されている特定のネットワーク アドレス タイプを識別する GUID へのポインタ(C++ の場合、これは GUID へのリファレンスである)。事前に定義されているネットワーク アドレス タイプについては、DirectPlay アドレス を参照すること。
lpData
特定のネットワーク アドレスが格納されているバッファへのポインタ。
dwDataSize
lpData 内のネットワーク アドレスのサイズ (バイト単位)。
lpAddress
作成した DirectPlay アドレスを書き込むバッファへのポインタ。
lpdwAddressSize
DirectPlay アドレス バッファのサイズが格納されている変数へのポインタ。サービス プロバイダは、このメソッドを呼び出す前に、lpdwAddressSize をバッファのサイズに初期化する必要がある。メソッドが戻った後、このパラメータには lpAddress に書き込まれたバイト数が設定されている。バッファが小さすぎた場合 (DPERR_BUFFERTOOSMALL)、このパラメータには DirectPlay アドレスを格納するのに必要なサイズが設定されている。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDPARAMS

注意

IDirectPlayLobby3::CreateCompoundAddress メソッドを使用すると、CreateAddress で許可されているよりも長い DirectPlay アドレスを作成できる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::EnumAddress、IDirectPlayLobby3::CreateCompoundAddress、DirectPlay アドレス、DirectPlay アドレスのデータ型


IDirectPlayLobby3::CreateCompoundAddress

IDirectPlayLobby3::CreateCompoundAddress メソッドは、個別のデータ チャンクのリストから DirectPlay アドレス を作成する。このメソッドを使用すると、IDirectPlayLobby3::CreateAddress で許可されているよりも長い DirectPlay アドレスを作成できる。

HRESULT CreateCompoundAddress(
  LPDPCOMPOUNDADDRESSELEMENT lpElements,
  DWORD dwElementCount,
  LPVOID lpAddress,
  LPDWORD lpdwAddressSize
);

パラメータ

lpElements
DirectPlay アドレスを生成するときに使用する DPCOMPOUNDADDRESSELEMENT 構造体の配列の先頭要素へのポインタ。
dwElementCount
lpElements パラメータが指している配列のアドレス要素の数。
lpAddress
完全な DirectPlay アドレスを書き込むバッファへのポインタ。バッファの必要なサイズを取得する場合は、NULL を指定する。
lpdwAddressSize
lpAddress バッファのサイズが格納される DWORD へのポインタ。DWORD は、バッファに実際にコピーされたバイト数を示すように変更される。バッファが小さすぎる場合、必要なバイト数が設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::CreateAddress、IDirectPlayLobby3::EnumAddress、DPCOMPOUNDADDRESSELEMENT、DirectPlay アドレス


IDirectPlayLobby3::EnumAddress

IDirectPlayLobby3::EnumAddress メソッドは、DirectPlay アドレス バッファからチャンクを解析する。

HRESULT EnumAddress(
  LPDPENUMADDRESSCALLBACK lpEnumAddressCallback,
  LPCVOID lpAddress,
  DWORD dwAddressSize,
  LPVOID lpContext
);

パラメータ

lpEnumAddressCallback
DirectPlay アドレスの情報チャンクごとに呼び出す EnumAddressCallback 関数へのポインタ。
lpAddress
DirectPlay アドレス バッファの先頭へのポインタ。
dwAddressSize
DirectPlay アドレスのサイズ。
lpContext
コールバック関数へ渡すコンテキスト。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_EXCEPTION
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::CreateAddress、DirectPlay アドレス


IDirectPlayLobby3::EnumAddressTypes

IDirectPlayLobby3::EnumAddressTypes メソッドは、特定のサービス プロバイダが DirectPlay アドレスを構築するのに必要なアドレス タイプをすべて列挙する。アプリケーションまたはロビーは、この情報を使用して、ユーザーから正しい情報を取得したり、DirectPlay アドレスを作成したりすることができる。

HRESULT EnumAddressTypes(
  LPDPLENUMADDRESSTYPESCALLBACK lpEnumAddressTypeCallback,
  REFGUID guidSP,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

lpEnumAddressTypeCallback
サービス プロバイダのアドレス タイプごとに呼び出す EnumAddressTypeCallback 関数へのポインタ。サービス プロバイダでアドレス タイプが使用されない場合は、コールバック関数は呼び出されない。
guidSP
列挙するアドレス タイプのサービス プロバイダの GUID へのポインタ (C++ の場合、これは GUID へのリファレンスである)。
lpContext
コールバック関数へ渡すコンテキスト。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_EXCEPTION
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

注意

EnumAddressTypes を使用すると、サービス プロバイダがユーザーに情報の入力を要求するダイアログ ボックスを表示するかどうかを判定できる。このダイアログ ボックスには、IP アドレスを入力するように要求するものなどがある。サービス プロバイダでアドレス タイプが使用されない場合、情報は不要なので、ダイアログ ボックスは表示されない。

アプリケーションは、IDirectPlay4::GetPlayerAddress を呼び出せば、アドレス タイプとして選択可能な項目のリストを取得できる。これは、モデム間サービス プロバイダでのみ使用できる。ANSI 文字列 (最後が NULL) である DirectPlay アドレスのデータ型の最後が W でない (たとえば、DPAID_INet) のに対して、Unicode 文字列 (最後が NULL) である DirectPlay アドレスのデータ型の最後は W である (たとえば、DPAID_INetW)。事前に定義された Microsoft 社のデータ タイプのリストについては、DirectPlay アドレスのデータ型を参照すること。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DirectPlay アドレス、IDirectPlayLobby3::CreateAddress


IDirectPlayLobby3::EnumLocalApplications

IDirectPlayLobby3::EnumLocalApplications メソッドは、DirectPlay により登録されたアプリケーションを列挙する。

IDirectPlayLobby3A(ANSI) インタフェースでこのメソッドを呼び出すと、適切にローカライズされた 1 バイト文字の文字列が返される。マルチ バイト文字の文字列は使用されないので、それをサポートしていないフォントを使用しても文字列を表示するときに問題が発生しない。IDirectPlayLobby3(Unicode) インタフェースでこのメソッドを呼び出すと、ローカライズされたワイド文字の記述が返される。特別にローカライズしたロビーは、このメソッドを Unicode インターフェイスで呼び出す必要がある。

HRESULT EnumLocalApplications(
  LPDPENUMLOCALAPPLICATIONSCALLBACK lpEnumLocalAppCallback,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

lpEnumLocalAppCallback
列挙されたアプリケーションごとに呼び出される EnumLocalApplicationsCallback 関数へのポインタ。
lpContext
コールバック関数へ渡されるコンテキスト。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPLAPPINFO


IDirectPlayLobby3::GetConnectionSettings

IDirectPlayLobby3::GetConnectionSettings メソッドは、アプリケーションを起動して接続するために必要なすべての情報が格納された DPLCONNECTION 構造体を取得する。返されたデータは、ロビー クライアントにより IDirectPlayLobby3::RunApplication メソッドへ渡されたデータや、IDirectPlayLobby3::SetConnectionSettings メソッドを呼び出して設定されたデータと同じである。

HRESULT GetConnectionSettings(
  DWORD dwAppID,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

dwAppID
(複数のアプリケーションと通信する) ロビー クライアントから呼び出したときに取得するアプリケーションの接続設定を指定する。(1 つのロビー クライアントとのみ通信する) アプリケーションから呼び出すときは、このパラメータは 0 でなければならない。この ID 番号は、IDirectPlayLobby3::RunApplication から取得する。
lpData
接続設定を書き込むバッファへのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに最低限必要なサイズに設定される。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータにはデータのサイズがバイト単位で設定されている。バッファが小さすぎる (DPERR_BUFFERTOOSMALL) 場合、このパラメータには最低限必要なバッファのサイズが設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY

注意

メソッドが戻ったら、lpData メンバを DPLCONNECTION 構造体にキャストし、データを読み取る必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

DPLCONNECTION、IDirectPlayLobby3::RunApplication、IDirectPlayLobby3::SetConnectionSettings、IDirectPlayLobby3::WaitForConnectionSettings


IDirectPlayLobby3::ReceiveLobbyMessage

IDirectPlayLobby3::ReceiveLobbyMessage メソッドは、ロビー クライアント アプリケーションと DirectPlay アプリケーションの間で送信されるメッセージを取得する。メッセージはキューに設定されるので、時間内に読み取られなくてもデータがなくなってしまう危険性はない。

HRESULT ReceiveLobbyMessage(
  DWORD dwFlags,
  DWORD dwAppID,
  LPDWORD lpdwMessageFlags,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。
dwAppID
(複数のアプリケーションと通信している) ロビー クライアントから呼び出したときに取得するアプリケーションのメッセージを指定する。(1 つのロビー クライアントとのみ通信している) アプリケーションから呼び出すときは、このパラメータは 0 でなければならない。この ID 番号は、IDirectPlayLobby3::RunApplication メソッドから取得する。
lpdwMessageFlags
返されるメッセージのタイプを指定するフラグ。デフォルト (lpdwMessageFlags = 0) は、メッセージが送信者によりカスタム定義されたものであると指定する。このタイプのメッセージの処理は、オプションである。受信者は、送信側アプリケーションの識別情報に基づいてこのメッセージを解釈する必要がある。ロビーは、起動されたアプリケーションの GUID に基づいて送信側アプリケーションを識別できる。アプリケーションは、識別 GUID を要求する標準メッセージをロビーに送信することで、ロビーを識別する必要がある。
DPLMSG_STANDARD
DirectPlay により定義されたメッセージであると指定する。このタイプのメッセージの処理は、オプションである。
DPLMSG_SYSTEM
ロビーにより起動されたアプリケーションのステータスが変更されたことをそのロビーに通知するときに使用される DirectPlay により生成されたシステム メッセージであると指定する。
lpData
メッセージが書き込まれるバッファへのポインタ。メッセージのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータには、メッセージを保持するのに最低限必要なサイズが設定される。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された変数へのポインタ。メソッドが戻ると、このパラメータにはメッセージのサイズがバイト単位で設定されている。バッファが小さすぎる (DPERR_BUFFERTOOSMALL) 場合、このパラメータには最低限必要なバッファのサイズが設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_APPNOTSTARTED
DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOMESSAGES
DPERR_OUTOFMEMORY

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::RunApplication、IDirectPlayLobby3::SendLobbyMessage


IDirectPlayLobby3::RegisterApplication

IDirectPlayLobby3::RegisterApplication メソッドは、DirectPlay によりロビーアウェア アプリケーションを登録する。DirectPlay ロビーからの起動が可能なように、アプリケーションを登録する必要がある。

アプリケーションの登録は 1 度だけ行なう必要がある。また、アプリケーションでは、アンインストールされたときに登録を解除する必要がある (IDirectPlayLobby3::UnregisterApplication を参照すること)。

HRESULT RegisterApplication(
  DWORD  dwFlags,
  LPVOID lpAppDesc
);

パラメータ

dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。
lpAppDesc
アプリケーションのすべての登録値により設定された DPAPPLICATIONDESC 構造体または DPAPPLICATIONDESC2 構造体へのポインタ。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::UnregisterApplication、DirectXRegisterApplication


IDirectPlayLobby3::RunApplication

IDirectPlayLobby3::RunApplication メソッドは、アプリケーションを起動して、それをセッションに接続するために必要なすべての情報をそのアプリケーションに渡す。このメソッドは、ロビー クライアントにより使用される。

HRESULT RunApplication(
  DWORD dwFlags,
  LPDWORD lpdwAppID,
  LPDPLCONNECTION lpConn,
  HANDLE hReceiveEvent
);

パラメータ

dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。
lpdwAppID
起動されたアプリケーションを識別する ID が設定される変数へのポインタ。ロビー クライアントは、IDirectPlayLobby3::SendLobbyMessage メソッドや IDirectPlayLobby3::ReceiveLobbyMessage メソッドを呼び出すときに使用するために、このアプリケーション ID を保存しておく必要がある。
lpConn
起動するアプリケーションや、ユーザー ダイアログ ボックスを表示しないでセッション インスタンスにそのアプリケーションを接続する方法を指定するのに必要な情報がすべて格納された DPLCONNECTION 構造体へのポインタ。
hReceiveEvent
ロビー メッセージが受信されたときに設定される同期イベントを指定する。このイベントは、IDirectPlayLobby3::SetLobbyMessageEvent メソッドを使用すると、後で変更できる。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CANTCREATEPROCESS
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_UNKNOWNAPPLICATION

注意

このメソッドは、アプリケーション プロセスが作成された後で戻る。ロビー クライアントは、アプリケーションのステータスを示すシステム メッセージを受け取る。ロビー クライアントがセッションのホストであるアプリケーションを起動している場合、セッションに参加するその他のアプリケーションを起動するときは、DPLSYS_DPLAYCONNECTSUCCEEDED システム メッセージを受け取るまで待ってから処理を行う。アプリケーションがセッションを作成したり、参加したりできない場合は、DPLSYS_DPLAYCONNECTFAILED メッセージが生成される。またロビー クライアントは、アプリケーションが接続設定を読み取ったときは DPLSYS_CONNECTIONSETTINGSREAD システム メッセージを、アプリケーションが終了したときは DPLSYS_APPTERMINATED システム メッセージを受け取る。

ロビー クライアントが DPLSYS_CONNECTIONSETTINGSREAD システム メッセージを受け取る前に、その IDirectPlayLobby3 インターフェイスを解放しないことは重要である。ロビー クライアントは、メッセージを受信するまで IDirectPlayLobby3::ReceiveLobbyMessage をループ処理でチェックすることも、同期イベントを指定することもできる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::ReceiveLobbyMessage、IDirectPlayLobby3::GetConnectionSettings,、IDirectPlayLobby3::SetLobbyMessageEvent


IDirectPlayLobby3::SendLobbyMessage

IDirectPlayLobby3::SendLobbyMessage メソッドは、アプリケーションとロビー クライアントの間でメッセージを送信する。

HRESULT SendLobbyMessage(
  DWORD dwFlags,
  DWORD dwAppID,
  LPVOID lpData,
  DWORD dwDataSize
);

パラメータ

dwFlags
送信するメッセージのタイプを示すフラグ。デフォルト (dwFlags = 0) は、送信元アプリケーションにより定義されたカスタム メッセージである。次に、その他の値を示す。
DPLMSG_STANDARD
DirectPlay により定義された標準のメッセージ。
dwAppID
(複数のアプリケーションと通信している) ロビー クライアントから呼び出したときにメッセージを送信するアプリケーションを指定する。(1 つのロビー クライアントとのみ通信している) アプリケーションから呼び出すときは、このパラメータは 0 でなければならない。この ID は、IDirectPlayLobby3::RunApplication メソッドを使用して取得する。
lpData
送信するメッセージが格納されているバッファへのポインタ。
dwDataSize
バッファのサイズ (バイト単位)。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_APPNOTSTARTED
DPERR_BUFFERTOOLARGE
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_TIMEOUT

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::RunApplication、IDirectPlayLobby3::ReceiveLobbyMessage、DPLMSG_SETPROPERTY、DPLMSG_SETPROPERTYRESPONSE、DPLMSG_GETPROPERTY、DPLMSG_GETPROPERTYRESPONSE,


IDirectPlayLobby3::SetConnectionSettings

IDirectPlayLobby3::SetConnectionSettings メソッドは、アプリケーションを起動および接続するときに使用する設定値を変更する。

HRESULT SetConnectionSettings(
  DWORD dwFlags,
  DWORD dwAppID,
  LPDPLCONNECTION lpConn
);

パラメータ

dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。
dwAppID
(複数のアプリケーションと通信している) ロビー クライアントから呼び出すとき、このパラメータは設定するアプリケーションの接続設定を指定する。(1 つのロビー クライアントとのみ通信している) アプリケーションから呼び出すときは、このパラメータは 0 でなければならない。この ID は、IDirectPlayLobby3::RunApplication メソッドを使用して取得する。
lpConn
起動するアプリケーションや、ユーザー ダイアログ ボックスを表示しないでそのアプリケーションをセッション インスタンスに接続する方法を指定するのに必要な情報がすべて格納された DPLCONNECTION 構造体へのポインタ。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::GetConnectionSettings


IDirectPlayLobby3::SetLobbyMessageEvent

IDirectPlayLobby3::SetLobbyMessageEvent メソッドは、ロビー メッセージを受信したときに設定されるイベントを登録する。アプリケーションは、メッセージと同期をとる必要がある場合、このメソッドを呼び出さなければならない。ロビー クライアントは、このメソッドを呼び出すと、IDirectPlayLobby3::RunApplication メソッドへの呼び出しで指定されたイベントを変更できる。

HRESULT SetLobbyMessageEvent(
  DWORD dwFlags,
  DWORD dwAppID,
  HANDLE hReceiveEvent
);

パラメータ

dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。
dwAppID
(複数のアプリケーションと通信している) ロビー クライアントから呼び出すとき、イベントが関連付けられたアプリケーションを指定する。(1 つのロビー クライアントとのみ通信している) アプリケーションから呼び出すときは、このパラメータは 0 でなければならない。この ID 番号は、IDirectPlayLobby3::RunApplication メソッドから取得する。
hReceiveEvent
メッセージを受信したときに設定されるイベント ハンドル。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::ReceiveLobbyMessage、IDirectPlayLobby3::SendLobbyMessage


IDirectPlayLobby3::UnregisterApplication

IDirectPlayLobby3::UnregisterApplication メソッドは、DirectPlay アプリケーションの登録エントリを削除する。アプリケーションをアンインストールしたら、このエントリを削除する必要がある。

HRESULT UnregisterApplication(
  DWORD dwFlags,
  REFGUID guidApplication
);

パラメータ

dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。
guidApplication
レジストリから削除するアプリケーションのグローバル ユニーク識別子 (GUID)。C 言語の場合、このパラメータは GUID へのポインタである。C++ 言語の場合、これは GUID へのリファレンスである。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNKNOWNAPPLICATION

アプリケーションの GUID がレジストリ内にない場合は、DPERR_UNKNOWNAPPLICATION を返す。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlayLobby3::RegisterApplication、DirectXUnregisterApplication


IDirectPlayLobby3::WaitForConnectionSettings

IDirectPlayLobby3::WaitForConnectionSettings メソッドは、アプリケーションを待機モードに設定する。このモードでは、アプリケーションは接続設定が送信されるのを待機する。アプリケーションが待機モードのとき、RunApplication を使用しているロビー クライアントは新しいアプリケーションのインスタンスを起動しないで、既に待機モードで実行されているアプリケーションに接続設定を直接送信する。

アプリケーションは、待機モードのとき、DPLSYS_NEWCONNECTIONSETTINGS システム メッセージが送信されているかどうかをポーリングする必要がある。アプリケーションは、このメッセージを受信すると、自動的に待機モードを終了する。アプリケーションは、ConnectEx を使用してセッションに接続できる。

HRESULT WaitForConnectionSettings(
  DWORD dwFlags
);

パラメータ

dwFlags
アプリケーションを待機モードに設定したり、待機モードを終了させるフラグ。デフォルト (dwFlags = 0) では、メソッドはアプリケーションを待機モードに設定する。dwFlags に DPLWAIT_CANCEL を設定すると、アプリケーションは待機モードを終了する。ロビー クライアントにより接続設定が送信されるとすぐに、アプリケーションは待機モードを終了する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_INVALIDFLAGS
DPERR_UNAVAILABLE

待機モードを取り消すようにフラグを設定していて、アプリケーションが待機モードでない場合は、DPERR_UNAVAILABLE を返す。

注意

ロビー クライアントが RunApplication を使用すると、DirectPlay は接続設定が送信されるのを待っているアプリケーションのインスタンスを検索する。そのようなインスタンスが見つからない場合は、新しいアプリケーションのインスタンスが起動される。待機中のアプリケーションか見つかった場合、DirectPlay は DPLSYS_NEWCONNECTIONSETTINGS システム メッセージを送信する。アプリケーションは、GetConnectionSettings により接続設定を読み取り、ConnectEx を使用してセッションに参加することができる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。


関数

次に、DirectPlay の関数を示す。

  • DirectPlayCreate。この関数は使用されていないので注意すること。代わりに、CoCreateInstance を使用することを推奨する。
  • DirectPlayEnumerate。この関数は使用されていないので注意すること。代わりに、IDirectPlay4::EnumConnections を使用することを推奨する。
  • DirectPlayLobbyCreate


DirectPlayCreate

この関数はもう使用されていないが、DirectX 3 を使用して作成されたアプリケーションとの互換性を保つために残されている。アプリケーションで目的の DirectPlay インターフェイスを作成するときは CoCreateInstance を直接使用することを推奨する。CoCreateInstance を使用すると、IDirectPlay インターフェイスを取得して、QueryInterface により IDirectPlay4 インターフェイスにアクセスし、IDirectPlay インターフェイスを解放しなくても IDirectPlay4 インターフェイスを直接取得できる。

DirectPlayCreate 関数は、新しい DirectPlay オブジェクトを作成し、IDirectPlay インターフェイス ポインタを取得する。アプリケーションで lpGUIDSP パラメータに GUID_NULL が指定された場合、この関数は、DirectPlay オブジェクトは作成するが、サービス プロバイダは初期化しない。アプリケーションは、IDirectPlay4::InitializeConnection メソッドを呼び出してサービス プロバイダまたはロビー プロバイダを初期化する。

アプリケーションは、サービス プロバイダの GUID (DirectPlayEnumerate を参照すること) を指定して、バインドするサービス プロバイダを指定できる。

最新の DirectPlay 機能を使用するために、アプリケーションは QueryInterface メソッドを使用して IDirectPlay4 または IDirectPlay4A インターフェイス ポインタを取得する必要がある。

HRESULT WINAPI DirectPlayCreate(
  LPGUID lpGUIDSP,
  LPDIRECTPLAY FAR *lplpDP,
  IUnknown *lpUnk
);

パラメータ

lpGUIDSP
DirectPlay オブジェクトを初期化するときに使用するサービス プロバイダの GUID へのポインタ。初期化しないで DirectPlay オブジェクトを作成するには、GUID_NULL へのポインタを渡す。
lplpDP
有効な IDirectPlay インターフェイスにより初期化するインターフェイス ポインタへのポインタ。アプリケーションでは、QueryInterface メソッドを使用して、IDirectPlay2、IDirectPlay4 インターフェイス (UNICODE 文字列)、または IDirectPlay2A、IDirectPlay4A インターフェイス (ANSI 文字列) を取得する必要がある。
lpUnk
含まれている IUnknown へのポインタ。このパラメータは、将来 COM 集合化機能と互換性をとるために用意されている。ただし、現在はこのパラメータに NULL 以外の値を指定すると DirectPlayCreate からエラーが返される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

CLASS_E_NOAGGREGATION
DPERR_EXCEPTION
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

DirectPlay オブジェクトを作成できなかった場合は、DPERR_UNAVAILABLE を返す。指定された GUID が無効な場合は、DPERR_INVALIDPARAMS を返す。

注意

この関数は、DirectPlay オブジェクトを初期化して、それが成功した場合はそのオブジェクトへのポインタを設定しようとする。アプリケーションは、使用可能なサービス プロバイダのタイプを判定するために、初期化処理の直前に DirectPlayEnumerate 関数を呼び出す (DirectPlayEnumerate 関数により DirectPlayCreate の lpGUIDSP パラメータが設定される)。

この関数は、IDirectPlay インターフェイスへのポインタを返す。カレント インターフェイスは、IDirectPlay4 と IDirectPlay4A であり、これらはこの IDirectPlay インターフェイスで QueryInterface メソッドを呼び出して取得する必要がある。詳細については、DirectPlay インターフェイスの概要を参照すること。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::InitializeConnection、DirectPlayEnumerate


DirectPlayEnumerate

DirectPlayEnumerate 関数は、システムにインストールされている DirectPlay サービス プロバイダを列挙する。

この関数はもう使用されていないが、DirectX 3 を使用して作成されたアプリケーションとの互換性を保つために残されている。これは、サービス プロバイダのみを列挙し、DirectPlay アドレス (接続) は列挙しない。IDirectPlay4 インターフェイスを作成した後でアプリケーションで使用可能な接続をすべて列挙するときは、アプリケーションで IDirectPlay4::EnumConnections メソッドを使用することを推奨する。

この関数は、レジストリの Enumerate 値に 0 が設定されているサービス プロバイダは列挙しない。前のバージョンとの互換性を保つため、"サービス プロバイダ" レジストリ キーで登録されているサービス プロバイダを 1 つだけ返す。

HRESULT WINAPI DirectPlayEnumerate(
  LPDPENUMDPCALLBACK lpEnumCallback,
  LPVOID lpContext
);

パラメータ

lpEnumCallback
システムにインストールされている各 DirectPlay サービス プロバイダの記述を使用して呼び出すコールバック関数へのポインタ。UNICODE が定義されているかどうかにより、コールバック関数のプロトタイプはサービス プロバイダ名の lpSPName を LPWSTR(Unicode の場合) または LPSTR(ANSI の場合) として定義する。
lpContext
関数が呼び出されるたびに、コールバック関数に渡されるアプリケーションにより定義された構造体へのポインタ。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDPARAMS

無効な列挙コールバック関数が指定された場合は、DPERR_INVALIDPARAMS を返す。

注意

この関数は、システムがそれにインストールされたサービス プロバイダを使用できなくても、それらを列挙する。たとえば、システムでモデムがインストールされていなくても、TAPI サービス プロバイダは列挙される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::EnumConnections、DirectPlayCreate


DirectPlayLobbyCreate

DirectPlayLobbyCreate 関数は、DirectPlayLobby オブジェクトのインスタンスを作成し、IDirectPlayLobby インターフェイスへのポインタを返す。

HRESULT WINAPI DirectPlayLobbyCreate(
  LPGUID lpGUIDSP,
  LPDIRECTPLAYLOBBY *lplpDPL,
  IUnknown *lpUnk,
  LPVOID lpData,
  DWORD dwDataSize
);

パラメータ

lpGUIDSP
将来の使用に備えて予約されているので、NULL に設定しておく。
lplpDPL
有効な IDirectPlayLobby インターフェイスにより初期化されたポインタへのポインタ。IDirectPlayLobby3 インターフェイスを取得するには、この関数を使用して IDirectPlayLobby インターフェイスを取得してから、次のように QueryInterface を呼び出す。
IDirectPlayLobby->QueryInterface( IID_IDirectPlayLobby3,
        (LPVOID*) &lpDP2 );
lpUnk
含まれている IUnknown インターフェイスへのポインタ。このパラメータは、将来 COM 集合化機能と互換性をとるために用意されている。ただし、現在はこのパラメータに NULL 以外の値を指定すると DirectPlayLobbyCreate からエラーが返される。
lpData
DirectPlayLobby オブジェクトを作成するのに必要な余分のデータ。このパラメータには NULL を設定しておく。
dwDataSize
このパラメータには、0 を設定しておく。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

CLASS_E_NOAGGREGATION
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。


コールバック関数

次に、DirectPlay のコールバック関数を示す。

  • EnumAddressCallback
  • EnumAddressTypeCallback
  • EnumConnectionsCallback
  • EnumDPCallback
  • EnumLocalApplicationsCallback
  • EnumPlayersCallback2
  • EnumSessionsCallback2


EnumAddressCallback

EnumAddressCallback は、IDirectPlayLobby3::EnumAddress メソッドに対するアプリケーション定義のコールバック関数である。

BOOL FAR PASCAL EnumAddressCallback(
  REFGUID guidDataType,
  DWORD dwDataSize,
  LPCVOID lpData,
  LPVOID lpContext
);

パラメータ

guidDataType
このデータ チャンクのタイプを示すグローバル ユニーク識別子 (GUID) へのポインタ。たとえば、このパラメータには &DPAID_Phone や &DPAID_INet が設定される (C++ の場合、これは GUID へのリファレンスである)。
dwDataSize
データ チャンクのサイズ (バイト単位)。
lpData
定数データへのポインタ。
lpContext
コールバック関数に渡すコンテキスト。

戻り値

列挙を継続する場合は、TRUE を返す。列挙を停止する場合は、FALSE を返す。

注意

サービス プロバイダは、guidDataType パラメータの GUID を調べて、lpData に指定された値を処理または保存する。guidDataType で認識されていない値は、無視してもよい。

コールバック関数で返されるポインタは一時的なものであり、コールバック関数の内部でのみ有効である。アプリケーションでは、ポインタ情報を保存する必要がある場合、データを保持するためのメモリを割り当て、データをコピーしてから、この新しいデータへのポインタを保存する必要がある。この関数で、lpData は一時的なものである。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。


EnumAddressTypeCallback

EnumAddressTypeCallback は、IDirectPlayLobby3::EnumAddressTypes メソッドに対するアプリケーション定義のコールバック関数である。

BOOL FAR PASCAL EnumAddressTypeCallback(
  REFGUID guidDataType,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

guidDataType
アドレス タイプを示すグローバル ユニーク識別子 (GUID) へのポインタ (C++ の場合、これは GUID へのリファレンスである)。事前に定義されているアドレス タイプは、DPAID_Phone、DPAID_INet、DPAID_ComPort である。これらのアドレス タイプの詳細については、DirectPlay アドレスを参照すること。
lpContext
コールバック関数に渡すコンテキスト。
dwFlags
将来の使用に備えて予約されているので、使用しないこと。

戻り値

列挙を継続する場合は、TRUE を返す。列挙を停止する場合は、FALSE を返す。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Requires Windows 98.
ヘッダー : dplay.h で宣言。


EnumConnectionsCallback

EnumConnectionsCallback は、IDirectPlay4::EnumConnections メソッドに対するアプリケーション定義のコールバック関数である。

BOOL FAR PASCAL EnumConnectionsCallback(
  LPCGUID lpguidSP,
  LPVOID lpConnection,
  DWORD dwConnectionSize,
  LPCDPNAME lpName,
  DWORD dwFlags,
  LPVOID lpContext
);

パラメータ

lpguidSP
接続に関連付けられた DirectPlay サービス プロバイダまたはロビー プロバイダの GUID。この GUID を使用すると、列挙の順序や名前を使用しなくても、サービス プロバイダやロビー プロバイダを一意に識別できる。
lpConnection
接続が格納されているバッファへの読み取り専用ポインタ。このパラメータは、DirectPlay オブジェクトを初期化するために IDirectPlay4::InitializeConnection メソッドに渡される。このバッファには、DirectPlay アドレスが格納されている。
dwConnectionSize
lpConnection バッファのサイズ (バイト単位)。
lpName
DPNAME 構造体への読み取り専用ポインタ。この構造体には、ユーザーに表示する接続の短縮名が格納されている。

ANSI インターフェイスで IDirectPlay4::EnumConnections を呼び出す場合は、文字列を ANSI として参照すること。Unicode インターフェイスで EnumConnections を呼び出す場合は、文字列を Unicode として参照すること。

dwFlags
接続のタイプを示すフラグ。EnumConnections に渡される dwFlags と等価である。
lpContext
アプリケーションにより定義されたコンテキストへのポインタ。

戻り値

列挙を継続する場合は、TRUE を返す。列挙を停止する場合は、FALSE を返す。

注意

アプリケーションは、IDirectPlay4::EnumConnections メソッドを使用するために、この関数を実装する必要がある。この関数は、列挙された接続ごとに 1 回ずつ呼び出される。

アプリケーションは、ユーザーに表示したり、IDirectPlay4::InitializeConnectionメソッドで使用するために、メモリを割り当て、各接続をコピーする。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::EnumConnections、IDirectPlay4::InitializeConnection


EnumDPCallback

EnumDPCallback は、DirectPlayEnumerate 関数に対してアプリケーションにより定義されたコールバック関数である。UNICODE が定義されているかどうかにより、コールバック関数のプロトタイプは lpSPName を LPWSTR 型 (Unicode の場合) または LPSTR 型 (ANSI の場合) のいずれかとして定義する。

BOOL FAR PASCAL EnumDPCallback(
  LPGUID lpguidSP,
  LPSTR/LPWSTR lpSPName,
  DWORD dwMajorVersion,
  DWORD dwMinorVersion,
  LPVOID lpContext
);

パラメータ

lpguidSP
DirectPlay サービス プロバイダの一意の識別子へのポインタ。
lpSPName
ドライバの記述が格納されている文字列へのポインタ。UNICODE シンボルが定義されているかどうかにより、パラメータは LPWSTR 型 (Unicode) または LPSTR 型 (ANSI) のいずれかとなる。
dwMajorVersion および dwMinorVersion
ドライバのメジャー バージョンとマイナー バージョン。
lpContext
アプリケーションにより定義されたコンテキストへのポインタ。

戻り値

列挙を継続する場合は、TRUE を返す。列挙を停止する場合は、FALSE を返す。

注意

コールバック関数で返されるポインタは一時的なものであり、コールバック関数の内部でのみ有効である。アプリケーションは、ポインタ情報を保存する必要がある場合、データを保持するためのメモリを割り当て、データをコピーしてから、この新しいデータへのポインタを保存する必要がある。この関数で、lpguidSP と lpSPName は一時的なものである。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。


EnumLocalApplicationsCallback

EnumLocalApplicationsCallback は、IDirectPlayLobby3::EnumLocalApplications メソッドに対するアプリケーション定義のコールバック関数である。

BOOL FAR PASCAL EnumLocalApplicationsCallback(
  LPCDPLAPPINFO lpAppInfo,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

lpAppInfo
列挙されるアプリケーションに関する情報が格納されている DPLAPPINFO 構造体への読み取り専用ポインタ。
lpContext
IDirectPlayLobby3::EnumLocalApplications 呼び出しから渡されるコンテキスト。
dwFlags
将来の使用に備えて予約されている。使用しないこと。

戻り値

列挙を継続する場合は、TRUE を返す。列挙を停止する場合は、FALSE を返す。

注意

コールバック関数で返されるポインタは一時的なものであり、コールバック関数の内部でのみ有効である。アプリケーションは、ポインタ情報を保存する必要がある場合、データを保持するためのメモリを割り当て、データをコピーしてから、この新しいデータへのポインタを保存する必要がある。この関数で、lpAppInfo は一時的なものである。また、lpAppInfo パラメータで指定された構造体内のポインタの lpszAppNameA と lpszAppName も一時的なものであるので注意すること。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。


EnumPlayersCallback2

EnumPlayersCallback2 は、アプリケーションにより定義されたコールバック関数である。アプリケーションでは、この関数を実装して、IDirectPlay4::EnumGroups メソッド、IDirectPlay4::EnumGroupPlayers メソッド、IDirectPlay4::EnumPlayers メソッド、および IDirectPlay4::EnumGroupsInGroup メソッドに関数へのポインタを渡す必要がある。このコールバック関数は、列挙されるプレーヤーまたはグループごとに 1 回ずつ呼び出される。

BOOL FAR PASCAL EnumPlayersCallback2(
  DPID dpId,
  DWORD dwPlayerType,
  LPCDPNAME lpName,
  DWORD dwFlags,
  LPVOID lpContext
);

パラメータ

dpId
列挙するプレーヤーまたはグループの ID。
dwPlayerType
DPPLAYERTYPE_GROUP または DPPLAYERTYPE_PLAYER のいずれかのエンティティのタイプ。
lpName
プレーヤーまたはグループの名前が格納されている DPNAME 構造体への読み取り専用ポインタ。このポインタは、コールバック関数の処理中にのみ有効である。後から参照するためにデータを保存するときは、それをアプリケーションが所有しているメモリにコピーする必要がある。
dwFlags
列挙するグループやプレーヤーを記述したフラグ。
DPENUMGROUPS_HIDDEN
グループは、隠しフラグを使用して作成された。
DPENUMGROUPS_SHORTCUT
グループは、ショートカットである。
DPENUMGROUPS_STAGINGAREA
グループは、ステージング領域である。
DPENUMPLAYERS_GROUP
プレーヤーとグループの両方が列挙されている。このフラグは、このコールバック関数の呼び出し元の列挙メソッドでそれが指定されていた場合にのみ返される。
DPENUMPLAYERS_LOCAL
プレーヤーまたはグループはローカル コンピュータ上に存在する。このフラグは、このコールバック関数の呼び出し元の列挙メソッドでそれが指定されていた場合にのみ返される。
DPENUMPLAYERS_OWNER
プレーヤーは、グループの所有者である。このコールバック関数の呼び出し元の IDirectPlay4::EnumGroupPlayers メソッドでそれが指定されていた場合にのみ返される。
DPENUMPLAYERS_REMOTE
プレーヤーやグループは、リモート コンピュータ上に存在する。このフラグは、このコールバック関数の呼び出し元の列挙メソッドでそれが指定されていた場合にのみ返される。
DPENUMPLAYERS_SERVERPLAYER
プレーヤーは、アプリケーション/サーバー セッションのサーバー プレーヤーである。各セッションにサーバー プレーヤーは 1 つしか存在しない。
DPENUMPLAYERS_SESSION
プレーヤーやグループは、列挙メソッドの lpguidInstance により指定されたセッションに存在する。このフラグは、このコールバック関数の呼び出し元の列挙メソッドでそれが指定されていた場合にのみ返される。
DPENUMPLAYERS_SPECTATOR
プレーヤーは、観客である (プレーヤーにのみ適用される)。
lpContext
アプリケーションにより定義されたコンテキストへのポインタ。

戻り値

列挙を継続する場合は、TRUE を返す。列挙を停止する場合は、FALSE を返す。

注意

コールバック関数で返されるポインタは一時的なものであり、コールバック関数の内部でのみ有効である。アプリケーションは、ポインタ情報を保存する必要がある場合、データを保持するためのメモリを割り当て、データをコピーしてから、この新しいデータへのポインタを保存する必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

DPNAME、IDirectPlay4::EnumGroups、IDirectPlay4::EnumPlayers、IDirectPlay4::EnumGroupPlayers、IDirectPlay4::EnumGroupsInGroup


EnumSessionsCallback2

EnumSessionsCallback2 は、IDirectPlay4::EnumSessions メソッドに対するアプリケーション定義のコールバック関数である。

BOOL FAR PASCAL EnumSessionsCallback2(
  LPCDPSESSIONDESC2 lpThisSD,
  LPDWORD lpdwTimeOut,
  DWORD dwFlags,
  LPVOID lpContext
);

パラメータ

lpThisSD
列挙されるセッションを記述した DPSESSIONDESC2 構造体へのポインタ。列挙処理が時間切れになった場合、このパラメータには NULL が設定される。
lpdwTimeOut
現行のタイムアウト値が格納される変数へのポインタ。セッションからの応答をもっと待ちたい場合に DPESC_TIMEDOUT フラグが返されたとき、このパラメータはリセットできる。
dwFlags
一般に、このフラグは 0 に設定される。
DPESC_TIMEDOUT
列挙処理が時間切れになった。処理を続行するには lpdwTimeOut をリセットして TRUE を返す。処理を停止するには、FALSE を返す。
lpContext
アプリケーションにより定義されたコンテキストへのポインタ。

戻り値

列挙を継続する場合は、TRUE を返す。列挙を停止する場合は、FALSE を返す。

注意

アプリケーションでは、IDirectPlay4::EnumSessions メソッドを使用するために、この関数を実装する必要がある。このコールバック関数は、列挙されたセッションごとに 1 回ずつ呼び出される。すべてのセッションが列挙されたら、このコールバック関数は DPESC_TIMEDOUT フラグを設定してもう一度呼び出される。

アプリケーションでセッションの性質を判定するには、DPSESSIONDESC2 の各フラグを調べる。

セキュア セッション の場合、DPSESSIONDESC2 の dwMaxPlayers メンバと dwCurrentPlayers メンバには 0 が設定される。

コールバック関数で返されるポインタは一時的なものであり、コールバック関数の内部でのみ有効である。アプリケーションは、ポインタ情報を保存する必要がある場合、データを保持するためのメモリを割り当て、データをコピーしてから、この新しいデータへのポインタを保存する必要がある。この関数で、lpThisSD は一時的なものである。また、lpThisSD パラメータで指定された構造体内のポインタの lpszSessionName/lpszSessionNameA と lpszPassword/lpszPasswordA も一時的なものであるので注意すること。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。


構造体

DirectX 5.0 の DirectPlay 構造体には新しいデータ メンバがいくつか追加されたが、それらは現在のバージョンでもサポートされている。DirectPlay の以前のバージョンの実行時ファイルとの互換性を確保しなければならないアプリケーションでは、次のいずれかを行なう必要がある。

  • DirectX 3.0 のヘッダー ファイルに存在する構造体を使用する。
  • 構造体のすべてのメンバにアクセスする前に、各構造体の dwSize メンバを調べる。

次に、DirectPlay 構造体を示す。

  • DPACCOUNTDESC
  • DPAPPLICATIONDESC
  • DPAPPLICATIONDESC2
  • DPCAPS
  • DPCHAT
  • DPCOMPORTADDRESS
  • DPCOMPOUNDADDRESSELEMENT
  • DPCREDENTIALS
  • DPLAPPINFO
  • DPLCONNECTION
  • DPNAME
  • DPSECURITYDESC
  • DPSESSIONDESC2


DPACCOUNTDESC

DPACCOUNTDESC 構造体は、特定のプレーヤーのアカウント情報を記述する。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    union {
        LPWSTR  lpszAccountID;
        LPSTR   lpszAccountIDA;
    };
} DPACCOUNTDESC, FAR *LPDPACCOUNTDESC;

メンバ

dwSize
DPACCOUNTDESC 構造体のサイズ。dwSize = sizeof(DPACCOUNTDESC)。
dwFlags
使用しない。0 に設定しておく。
lpszAccountID
アカウント識別子が格納されている Unicode 文字列へのポインタ。これは、安全にログオンしたプレーヤーを記述した一意の識別子。識別子のフォーマットは、使用されているセキュリティ サポート プロバイダ インターフェイス (SSPI) パッケージによって決まる。
lpszAccountIDA
アカウント識別子が格納されている ANSI 文字列へのポインタ。これは、安全にログオンしたプレーヤーを記述した一意の識別子。識別子のフォーマットは、使用されている SSPI パッケージによって決まる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::GetPlayerAccount


DPAPPLICATIONDESC

DPAPPLICATIONDESC 構造体は、IDirectPlayLobby3::RegisterApplication を使用してロビー対応アプリケーションを登録するために必要な情報をすべて記述する。

typedef struct {
    DWORD   dwSize;
    DWORD   dwFlags;
    union {
      LPSTR    lpszApplicationNameA;
      LPWSTR   lpszApplicationName;
    }
    GUID    guidApplication;
    union {
      LPSTR     lpszFilenameA;
      LPWSTR    lpszFilename;
    }
    union {
      LPSTR   lpszCommandLineA;
      LPWSTR  lpszCommandLine;
    }
    union {
      LPSTR   lpszPathA;
      LPWSTR  lpszPath;
    }
    union {
      LPSTR    lpszCurrentDirectoryA;
      LPWSTR   lpszCurrentDirectory;
    }
    LPSTR   lpszDescriptionA;
    LPWSTR  lpszDescriptionW;
} DPAPPLICATIONDESC, *LPDPAPPLICATIONDESC;

メンバ

dwSize
DPAPPLICATIONDESC 構造体のサイズ。dwSize = sizeof(DPAPPLICATIONDESC)。
dwFlags
使用しない。0 に設定しておく。
lpszApplicationNameA, lpszApplicationName
アプリケーションの名前が格納されている文字列へのポインタ。メモ: このタイトルはローカライズされない。アプリケーション名をローカライズするには、lpszDescriptionA メンバと lpszDescriptionW メンバを使用する。
guidApplication
アプリケーションのグローバル ユニーク識別子 (GUID)。これは、ゲーム セッションのホストであるときは DPSESSIONDESC2 構造体の guidApplication メンバで使用される値と同じでなければならない。
lpszFilenameA, lpszFilename
起動される実行可能プログラムの名前が格納されている文字列へのポインタ。メモ: ロビーから起動するときは、スタブの実行可能プログラムを使用しないこと。ロビーから起動するときは、スタブは省略されて、メインの実行可能プログラムが起動される。
lpszCommandLineA, lpszCommandLine
ロビーにより起動されるとき、実行可能プログラムに渡されるコマンド行の引数が格納された文字列へのポインタ。
lpszPathA, lpszPath
実行可能プログラムが置かれているパスが格納されている文字列へのポインタ。
lpszCurrentDirectoryA, lpszCurrentDirectory
カレント ディレクトリを設定するパスが格納されている文字列へのポインタ。一般に、これは lpszPath または lpszPathA と同じである。
lpszDescriptionA
アプリケーションのローカライズされた記述が格納されている ANSI の 1 バイト文字列へのポインタ。ANSI インターフェイス (IDirectPlayLobby3A など) で EnumLocalApplications が呼び出された場合、その文字列があれば、それが返される。それ以外の場合、lpszApplicationName データ メンバが返される。メモ: この文字列には複数文字は設定されない。ローカライズした ANSI 記述が必要でない場合は、NULL を設定する。
lpszDescriptionW
アプリケーションのローカライズされた記述が格納されている Unicode 文字列へのポインタ。Unicode インターフェイス (IDirectPlayLobby3 など) で EnumLocalApplications が呼び出された場合、その文字列があれば、それが返される。その文字列がない場合は、lpszDescriptionA データ メンバが Unicode に変換されて返される。lpszDescriptionA も lpszDescriptionW も存在しない場合、lpszApplicationName データ メンバが返される。メモ: この文字列は Unicode 文字だけで構成されなければならない。ローカライズした Unicode 記述が必要でない場合は、NULL を設定する。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。

参照

IDirectPlayLobby3::RegisterApplication、DPAPPLICATIONDESC2


DPAPPLICATIONDESC2

DPAPPLICATIONDESC2 構造体は、IDirectPlayLobby3::RegisterApplication を使用してロビー対応アプリケーションを登録するために必要な情報をすべて記述する。アプリケーションを起動アプリケーションにより起動する場合は、代わりに DPAPPLICATIONDESC を使用する。

typedef struct {
    DWORD   dwSize;
    DWORD   dwFlags;
    union {
      LPSTR    lpszApplicationNameA;
      LPWSTR   lpszApplicationName;
    }
    GUID    guidApplication;
    union {
      LPSTR     lpszFilenameA;
      LPWSTR    lpszFilename;
    }
    union {
      LPSTR   lpszCommandLineA;
      LPWSTR  lpszCommandLine;
    }
    union {
      LPSTR   lpszPathA;
      LPWSTR  lpszPath;
    }
    union {
      LPSTR    lpszCurrentDirectoryA;
      LPWSTR   lpszCurrentDirectory;
    }
    LPSTR   lpszDescriptionA;
    LPWSTR  lpszDescriptionW;
    union
    {
      LPSTR   lpszAppLauncherNameA;
      LPWSTR  lpszAppLauncherName;
    };
} DPAPPLICATIONDESC2, *LPDPAPPLICATIONDESC2;

メンバ

dwSize
DPAPPLICATIONDESC2 構造体のサイズ。dwSize = sizeof(DPAPPLICATIONDESC2)。
dwFlags
使用しない。0 に設定しておく。
lpszApplicationNameA, lpszApplicationName
アプリケーションの名前が格納されている文字列へのポインタ。メモ: このタイトルはローカライズされない。アプリケーション名をローカライズするには、lpszDescriptionA メンバと lpszDescriptionW メンバを使用する。
guidApplication
アプリケーションのグローバル ユニーク識別子 (GUID)。これは、ゲーム セッションのホストであるときは DPSESSIONDESC2 構造体の guidApplication メンバで使用される値と同じでなければならない。
lpszFilenameA, lpszFilename
起動される実行可能プログラムの名前が格納されている文字列へのポインタ。メモ: ロビーから起動するときは、スタブの実行可能プログラムを使用しないこと。ロビーから起動するときは、スタブは省略されて、メインの実行可能プログラムが起動される。
lpszCommandLineA, lpszCommandLine
ロビーにより起動されるとき、実行可能プログラムに渡されるコマンド行の引数が格納された文字列へのポインタ。
lpszPathA, lpszPath
実行可能プログラムが置かれているパスが格納されている文字列へのポインタ。
lpszCurrentDirectoryA, lpszCurrentDirectory
カレント ディレクトリを設定するパスが格納されている文字列へのポインタ。一般に、これは lpszPath または lpszPathA と同じである。
lpszDescriptionA
アプリケーションのローカライズされた記述が格納されている ANSI の 1 バイト文字列へのポインタ。ANSI インターフェイス (IDirectPlayLobby3A など) で EnumLocalApplications が呼び出された場合、その文字列があれば、それが返される。それ以外の場合、lpszApplicationName データ メンバが返される。メモ: この文字列には複数文字は設定されない。ローカライズした ANSI 記述が必要でない場合は、NULL を設定する。
lpszDescriptionW
アプリケーションのローカライズされた記述が格納されている Unicode 文字列へのポインタ。Unicode インターフェイス (IDirectPlayLobby3 など) で EnumLocalApplications が呼び出された場合、その文字列があれば、それが返される。その文字列がない場合は、lpszDescriptionA データ メンバが Unicode に変換されて返される。lpszDescriptionA も lpszDescriptionW も存在しない場合、lpszApplicationName データ メンバが返される。メモ: この文字列は Unicode 文字だけで構成されなければならない。ローカライズした Unicode 記述が必要でない場合は、NULL を設定する。
lpszAppLauncherNameA, lpszAppLauncherName
起動アプリケーションの実行可能プログラムの名前が格納されている文字列へのポインタ。起動アプリケーションはロビーにより起動され、それが lpszApplicationName に記述されたアプリケーションを起動する。起動アプリケーションは、そのアプリケーションと同じディレクトリになければならない。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。

参照

IDirectPlayLobby3::RegisterApplication


DPCAPS

DPCAPS 構造体は、IDirectPlay4::GetCaps メソッドや IDirectPlay4::GetPlayerCaps メソッドを呼び出した後で、DirectPlay オブジェクトの能力を保持する。これらの能力は、要求された能力が保証付きであるか、保証なしであるかにより異なる。この構造体は、読み取り専用である。IDirectPlay4::SendEx メソッドでサポートされている部分を示す能力 (dwFlags の DPCAPS_SENDPRIORITYSUPPORTED フラグと DPCAPS_SENDTIMEOUTSUPPORTED フラグなど) は、セッションが開かれるまで使用できない。セッションのホストであるアプリケーションが DPSESSIONDESC2 構造体の DPSESSION_DIRECTPLAYPROTOCOL フラグを指定している場合、すべての SendEx オプションがサポートされる。

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;

メンバ

dwSize
DPCAPS 構造体のメンバ。dwSize = sizeof(DPCAPS)。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する。設定しなければ、エラーが発生する。
dwFlags
DirectPlay オブジェクトのプロパティを示すフラグ。
DPCAPS_ASYNCCANCELALLSUPPORTED
ペンディング状態の非同期メッセージをすべて取り消す機能がサポートされていることを示す。このフラグは、サポートされている取り消し処理のタイプが未送信メッセージを取り消す処理だけであることを示す。優先順位の範囲やメッセージ ID を指定してメッセージを取り消そうとすると、DPERR_UNSUPPORTED が返される。対照的に、DPCAPS_ASYNCCANCELSUPPORTED フラグは取り消し処理のすべてのタイプがサポートされていることを示す。ただし、SendEx でサポートされている部分を示す能力は、セッションが開かれるまで使用できない。
DPCAPS_ASYNCCANCELSUPPORTED
非同期メッセージを取り消す機能がサポートされていることを示す。メッセージ ID による取り消し、優先順位の範囲による取り消し、すべての未送信メッセージの取り消しといったすべてのタイプの取り消し処理がサポートされている。ただし、SendEx でサポートされている部分を示す能力は、セッションが開かれるまで使用できない。
DPCAPS_ASYNCSUPPORTED
非同期メッセージ処理がサポートされていることを示す。そのため、アプリケーションは SendEx で DPSEND_ASYNC フラグを使用できる。詳細については、「注意」を参照すること。ただし、SendEx でサポートされている部分を示す能力は、セッションが開かれるまで使用できない。
DPCAPS_ENCRYPTIONSUPPORTED
セッションがセキュア セッションであるため、またはサービス プロバイダでメッセージを暗号化できるため、この DirectPlay オブジェクトによりメッセージの暗号化がサポートされていることを示す。
DPCAPS_GROUPOPTIMIZED
この DirectPlay オブジェクトにバインドされているサービス プロバイダがグループ (マルチキャスト) のメッセージ処理を最適化できることを示す。
DPCAPS_GUARANTEEDOPTIMIZED
この DirectPlay オブジェクトにバインドされているサービス プロバイダで保証付きメッセージ配信がサポートされていることを示す。
DPCAPS_GUARANTEEDSUPPORTED
保証付きメッセージ配信は、それがサービス プロバイダでサポートされているため、または保証なしサービス プロバイダで DirectPlay によりそれが実装されているため、それがこの DirectPlay オブジェクトによりサポートされていることを示す。
DPCAPS_ISHOST
呼び出し元アプリケーションにより作成された DirectPlay オブジェクトがセッション ホストであることを示す。
DPCAPS_KEEPALIVEOPTIMIZED
サービス プロバイダがセッションへの接続がいつ喪失したかを検出できることを示す。
DPCAPS_SENDPRIORITYSUPPORTED
SendEx で設定されたメッセージの優先順位がサポートされていることを示す。ただし、SendEx でサポートされている部分を示す能力は、セッションが開かれるまで使用できない。
DPCAPS_SENDTIMEOUTSUPPORTED
SendEx で指定されたメッセージのタイムアウトがサポートされていることを示す。このフラグは、サービス プロバイダまたは DirectPlay により設定できる。ただし、SendEx でサポートされている部分を示す能力は、セッションが開かれるまで使用できない。
DPCAPS_SIGNINGSUPPORTED
セキュア セッションであるため、またはサービス プロバイダでメッセージに署名を設定できるため、メッセージ認証がこの DirectPlay オブジェクトによりサポートされていることを示す。
dwMaxBufferSize
このサービス プロバイダによりシングル パケットで送信できる最大バイト数。比較的サイズの大きなメッセージは、複数のパケットを使用して送信される。
dwMaxQueueSize
このメンバは、使用されなくなっている。
dwMaxPlayers
この DirectPlay オブジェクトによりセッション内でサポートされているローカル プレーヤーとリモート プレーヤーの最大数。
dwHundredBaud
1 秒あたりの帯域幅 (100 ビットの倍数で指定)。たとえば、値が 24 のとき、1 秒あたり 2400 ビットの帯域幅となる。
dwLatency
サービス プロバイダによる遅延時間の見積もり (ミリ秒単位)。この値が 0 の場合、DirectPlay は見積もることができない。サービス プロバイダの精度は、平均メッセージ サイズを考慮に入れたアプリケーション間のテストにより決まる。遅延時間は、アプリケーションが保証付きメッセージ配信方式と保証なしメッセージ配信方式のどちらを使用しているかにより異なることがある。
dwMaxLocalPlayers
セッションでサポートされるローカル プレーヤーの最大数。
dwHeaderLength
この DirectPlay オブジェクトによりプレーヤー メッセージに追加されるヘッダーのサイズ (バイト単位)。ただし、ヘッダーのサイズは、使用しているサービス プロバイダにより異なるので注意すること。
dwTimeout
サービス プロバイダの推奨タイムアウト値。デフォルトで DirectPlay は、メッセージへの応答を待つときこのタイムアウト値を使用する。

注意

DPCAPS_ASYNCSUPPORTED フラグ、DPCAPS_SENDTIMEOUTSUPPORTED フラグ、DPCAPS_SENDPRIORITYSUPPORTED フラグ、DPCAPS_ASYNCCANCELSUPPORTED フラグ、および DPCAPS_ASYNCCANCELALLSUPPORTED フラグは、カレント セッションの通信能力を示している。

アプリケーションが SendEx で DPSEND_ASYNC を使用できるようにするには、次の条件のいずれか (または両方) が真でなければならない。

セッションが作成されたときに DPSESSION_DIRECTPLAYPROTOCOL フラグを指定した。

サービス プロバイダで非同期メッセージ処理がサポートされている。

これは、モデム、シリアル、インターネット パケット交換機 (IPX) サービス プロバイダは、それらが使用可能な保証付きメッセージ処理を実行できるが、非同期のメッセージ処理については DPSESSION_DIRECTPLAYPROTOCOL フラグを明示的に設定しない限り実行できないことを意味する。コンピュータに Windows Sockets 2.0 が搭載されている場合、TCP/IP サービス プロバイダは非同期メッセージ処理を実装している。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::Send、IDirectPlay4::SendEx、IDirectPlay4::GetCaps、IDirectPlay4::GetPlayerCaps


DPCHAT

DPCHAT 構造体は、DirectPlay チャット メッセージを保持する。チャット メッセージは、IDirectPlay4::SendChatMessage メソッドにより送信される。

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    union{
      LPWSTR lpszMessage;
      LPSTR  lpszMessageA;
    };
} DPCHAT, FAR *LPDPCHAT;

メンバ

dwSize
DPCHAT 構造体のサイズ。dwSize = sizeof(DPCHAT)。
dwFlags
使用しない。0 に設定しておく。
lpszMessage
送信するメッセージが格納されている Unicode 文字列へのポインタ。Unicode インターフェイス (IDirectPlay4) でのみ使用できる。
lpszMessageA
送信するメッセージが格納されている ANSI 文字列へのポインタ。ANSI インターフェイス (IDirectPlay4A) でのみ使用できる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::SendChatMessage


DPCOMPORTADDRESS

DPCOMPORTADDRESS 構造体は、COM ポートの構成に関する情報を保持する。

typedef struct DPCOMPORTADDRESS{
    DWORD dwComPort;
    DWORD dwBaudRate;
    DWORD dwStopBits;
    DWORD dwParity;
    DWORD dwFlowControl;
} DPCOMPORTADDRESS;

typedef DPCOMPORTADDRESS FAR* LPDPCOMPORTADDRESS;

メンバ

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 で定義されている。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。


DPCOMPOUNDADDRESSELEMENT

DPCOMPOUNDADDRESSELEMENT 構造体は、DirectPlay アドレスのデータ チャンクを記述する。

typedef struct {
    GUID    guidDataType;
    DWORD   dwDataSize;
    LPVOID  lpData;
} DPCOMPOUNDADDRESSELEMENT, FAR *LPDPCOMPOUNDADDRESSELEMENT;

メンバ

guidDataType
この構造体に格納されているデータのタイプを指定した GUID。
dwDataSize
データのサイズ (バイト単位)。
lpData
データが格納されているバッファへのポインタ。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。

参照

IDirectPlayLobby3::CreateCompoundAddress、DirectPlay アドレスのデータ型


DPCREDENTIALS

DPCREDENTIALS 構造体は、保証サーバーに接続するためのユーザー名、パスワード、ドメインを保持する。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    union {
           LPWSTR lpszUsername;
           LPSTR  lpszUsernameA;
          };
    union {
           LPWSTR lpszPassword;
           LPSTR  lpszPasswordA;
          };
    union {
           LPWSTR lpszDomain;
           LPSTR  lpszDomainA;
          };

} DPCREDENTIALS, FAR *LPDPCREDENTIALS;

メンバ

dwSize
DPCREDENTIALS 構造体のサイズ。dwSize = sizeof(DPCREDENTIALS)。
dwFlags
使用しない。0 に設定しておく。
lpszUsername, lpszPassword, lpszDomain
ユーザー名、パスワード、ドメインが格納されている Unicode 文字列へのポインタ。Unicode インターフェイスでのみ使用できる。
lpszUsernameA, lpszPasswordA, lpszDomainA
ユーザー名、パスワード、ドメインが格納されている ANSI 文字列へのポインタ。ANSI インターフェイスでのみ使用できる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::SecureOpen


DPLAPPINFO

DPLAPPINFO 構造体は、レジストリ内のアプリケーションに関する情報を保持する。この構造体は、IDirectPlayLobby3::EnumLocalApplications コールバック関数に渡される。

typedef struct {
    DWORD  dwSize;
    GUID   guidApplication;
    union {
           LPSTR  lpszAppNameA;
           LPWSTR lpszAppName;
          };
} DPLAPPINFO, FAR *LPDPLAPPINFO;

メンバ

dwSize
DPLAPPINFO 構造体のサイズ。dwSize = sizeof(DPLAPPINFO)。アプリケーションは、この構造体を使用する前に、このメンバを設定する必要がある。設定しなければ、エラーが発生する。
guidApplication
アプリケーションのグローバル ユニーク識別子 (GUID)。
lpszAppNameA, lpszAppName
ANSI または Unicode のアプリケーション名。ANSI または Unicode であるかは、使用しているインターフェイスにより決まる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。


DPLCONNECTION

DPLCONNECTION 構造体は、アプリケーションをセッションに接続するために必要な情報を保持する。

typedef struct {
    DWORD            dwSize;
    DWORD            dwFlags;
    LPDPSESSIONDESC2 lpSessionDesc;
    LPDPNAME         lpPlayerName;
    GUID             guidSP;
    LPVOID           lpAddress;
    DWORD            dwAddressSize;
} DPLCONNECTION, FAR *LPDPLCONNECTION;

メンバ

dwSize
DPLCONNECTION 構造体のサイズ。dwSize = sizeof(DPLCONNECTION)。アプリケーションは、この構造体を使用する前に、このメンバを設定する必要がある。設定しなければ、エラーが発生する。
dwFlags
セッションの開き方を示す。
DPLCONNECTION_CREATESESSION
セッション記述に記述されているように新しいセッションを作成する。
DPLCONNECTION_JOINSESSION
セッション記述に記述されているように既存のセッションに参加する。
lpSessionDesc
作成するセッションまたは参加するセッションを記述した DPSESSIONDESC2 構造体へのポインタ。
lpPlayerName
プレーヤーを作成するときに使用する名前を保持した DPNAME 構造体へのポインタ。これは、ロビーに登録された人物の名前である。アプリケーションでは、この名前を無視してもよい。
guidSP
セッションを接続するときに使用するサービス プロバイダのグローバル ユニーク識別子 (GUID)。
lpAddress
サービス プロバイダがセッションを接続するときに必要な情報が格納されている DirectPlay アドレスへのポインタ。
dwAddressSize
アドレス データのサイズ (バイト単位)。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。

参照

IDirectPlayLobby3::RunApplication、IDirectPlayLobby3::GetConnectionSettings、IDirectPlayLobby3::SetConnectionSettings、DirectPlay アドレス


DPNAME

DPNAME 構造体は、プレーヤーやグループなどの DirectPlay エンティティの名前情報を保持する。

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    union {
        LPWSTR lpszShortName;
        LPSTR  lpszShortNameA;
    };
    union {
        LPWSTR lpszLongName;
        LPSTR  lpszLongNameA;
    };
} DPNAME, FAR *LPDPNAME;

メンバ

dwSize
DPNAME 構造体のサイズ。dwSize = sizeof(DPNAME)。アプリケーションは、この構造体を使用する前に、このメンバを設定する必要がある。設定しなければ、エラーが発生する。
dwFlags
構造体に固有のフラグ。現在は 0 に設定されている。
lpszShortName および lpszLongName
プレーヤーやグループの短い名前 (友人間で使用) と長い名前 (正式に使用) が格納されている Unicode 文字列へのポインタ。これらのメンバは、IDirectPlay4 インターフェイスが使用されている場合にのみ使用する。
lpszShortNameA および lpszLongNameA
プレーヤーやグループの短い名前 (友人間で使用) と長い名前 (正式に使用) が格納されている ANSI 文字列へのポインタ。これらのメンバは、IDirectPlay4A インターフェイスが使用されている場合にのみ使用する。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::CreateGroup、IDirectPlay4::CreatePlayer、IDirectPlay4::GetGroupName、IDirectPlay4::GetPlayerName、IDirectPlay4::SetGroupName、IDirectPlay4::SetPlayerName


DPSECURITYDESC

DPSECURITYDESC 構造体は、DirectPlay セッションのインスタンスのセキュリティ プロパティについて記述する。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    union {
        LPWSTR  lpszSSPIProvider;
        LPSTR   lpszSSPIProviderA;
    };
    union {
        LPWSTR lpszCAPIProvider;
        LPSTR  lpszCAPIProviderA;
    };
    DWORD  dwCAPIProviderType;
    DWORD  dwEncryptionAlgorithm;
} DPSECURITYDESC, FAR *LPDPSECURITYDESC;

メンバ

dwSize
DPSECURITYDESC 構造体のサイズ。dwSize = sizeof(DPSECURITYDESC)。
dwFlags
使用しない。0 に設定しておく。
lpszSSPIProvider, lpszSSPIProviderA
認証ログオンで使用するセキュリティ サポート プロバイダ インターフェイス (SSPI) パッケージを記述した Unicode 文字列または ANSI 文字列へのポインタ。デフォルトの NTLM(NT LAN Manager) セキュリティ プロバイダを使用するときは、NULL を渡す。
lpszCAPIProvider, lpszCAPIProviderA
暗号化サービスで使用する CryptoAPI パッケージを記述した Unicode 文字列または ANSI 文字列へのポインタ。デフォルトの Microsoft RSA Base Cryptographic Provider v. 1.0 を使用するときは、NULL を渡す。
dwCAPIProviderType
CryptoAPI サービス プロバイダ タイプ。デフォルト タイプの PROV_RSA_FULL を使用するときは、0 を渡す。
dwEncryptionAlgorithm
使用する暗号化アルゴリズム。DirectPlay は、ストリーム暗号のみをサポートしている。デフォルトの CALG_RC4 ストリーム暗号を使用するときは、0 を渡す。

注意

DirectPlay は、ブロック暗号をサポートしていない。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::SecureOpen


DPSESSIONDESC2

DPSESSIONDESC2 構造体は、セッションの能力の記述を保持する。

ただし、セッション記述フラグの一部は読み取り専用であり、変更できない。また、残りのフラグはホストしか変更できないので注意すること。dwFlags メンバの説明を参照すること。

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;

メンバ

dwSize
DPSESSIONDESC2 構造体のサイズ。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する必要がある。
dwFlags
DPSESSION_CLIENTSERVER、DPSESSION_DIRECTPLAYPROTOCOL、DPSESSION_KEEPALIVE、DPSESSION_MIGRATEHOST、DPSESSION_MULTICASTSERVER、DPSESSION_NOMESSAGEID、DPSESSION_OPTIMIZELATENCY、および DPSESSION_SECURESERVER のフラグの組み合わせ。セッションが起動されている場合、これらのフラグは変更できない。その他のフラグの DPSESSION_JOINDISABLED、DPSESSION_NEWPLAYERSDISABLED、DPSESSION_NODATAMESSAGES、DPSESSION_NOPRESERVEORDER、DPSESSION_PASSWORDREQUIRED、および DPSESSION_PRIVATE は、IDirectPlay4::SetSessionDesc によりセッションが起動された後でも変更できるが、変更できるのはホストだけである。
DPSESSION_CLIENTSERVER
これが、アプリケーション サーバー プロセスがホストのクライアント／サーバー セッションであると指定する。このフラグは、セッションが作成されたときに指定する必要がある。このセッションに参加したクライアントは、そのサーバー プレーヤーとローカル プレーヤーを列挙することしかできない。セッションのホストでは、すべてのプレーヤーが列挙される。このフラグが設定されていない場合、セッションはピアツーピア セッションである。このフラグが設定されている場合、サーバー プレーヤーを作成できるのはホストだけである。このフラグは、DPSESSION_MIGRATEHOST では使用できない。
DPSESSION_DIRECTPLAYPROTOCOL
このセッションではサービス プロバイダにより実装されるプロトコルではなく、DirectPlay の保証付きプロトコルを使用するように指定する。メッセージ スロットリングによりパフォーマンスを向上させたい場合、または IDirectPlay4::SendEx のすべての機能を使用できるようにしたい場合に、このフラグを使用する。このフラグを設定すると、信頼性の低いプロバイダでの保証付き送信も可能になる。また、このフラグにより、TCP/IP 上で DirectPlay の信頼性の高いコードを使用することが可能になる。これにより、一般にスループットと配信の両方の面でパフォーマンスが向上する。
DPSESSION_JOINDISABLED
新しいアプリケーションがこのセッションに参加できないように指定する。IDirectPlay4::Open メソッドで DPOPEN_JOIN フラグを設定して呼び出したり、またこのセッションのインスタンスのグローバル ユニーク識別子 (GUID) により、エラーが発生する。このフラグが指定されていない場合、新しいリモート アプリケーションはセッション プレーヤーの制限に達するまでセッションに参加できる。
DPSESSION_KEEPALIVE
リモート プレーヤーがゲームを異常に退出すると、このセッションがそれを自動的に検出するように指定する。そのプレーヤーは、セッションから削除される。一時的なネットワークの容量不足によりプレーヤーを喪失した場合、そのプレーヤーには戻ったときに、セッションから退出させられたことが DPMSG_SESSIONLOST システム メッセージにより知らされる。このフラグは、セッションが作成されたときに指定する必要がある。このフラグが指定されていない場合、プレーヤーが異常終了すると DirectPlay によりそのセッションが自動的に維持されない。
DPSESSION_MIGRATEHOST
カレント ホストが存在する場合にセッション内の別のコンピュータがホストになるように指定する。新しいホスト コンピュータのプレーヤーは、DPMSG_HOST システム メッセージを受け取る。このフラグは、セッションが作成されたときに指定する必要がある。このフラグが設定されていない場合、ホストは移行せず、新しいコンピュータはセッションに参加できない。また、カレント ホストが退出すると新しいプレーヤーを作成できない。DPSESSION_MIGRATEHOST フラグは、DPSESSION_CLIENTSERVER フラグ、DPSESSION_MULTICASTSERVER フラグ、または DPSESSION_SECURESERVER フラグと一緒に使用できないので注意すること。
DPSESSION_MULTICASTSERVER
ピアツーピア セッションでブロードキャスト メッセージやグループ メッセージが、マルチキャスト サーバーのように機能するホストからルーティングされるように指定する。このフラグは、セッションが作成されたときに指定する必要がある。このフラグは、ホストがネットワークへ高帯域幅で接続されている場合にのみ有用である。このフラグが指定されていない場合、ブロードキャスト メッセージやグループ メッセージはピア間で直接送信される。このフラグは、DPSESSION_MIGRATEHOST で使用できない。
DPSESSION_NEWPLAYERSDISABLED
新しいプレーヤーをセッション内で作成できないように指定する。セッション内のアプリケーションが IDirectPlay4::CreatePlayer メソッドを呼び出すと、エラーが発生する。また、新しいアプリケーションはセッションに参加できない。このフラグが指定されていない場合、プレーヤーは、セッション プレーヤーの制限に達するまで作成できる。
DPSESSION_NODATAMESSAGES
IDirectPlay4::SetPlayerData、IDirectPlay4::SetGroupData、IDirectPlay4::SetPlayerName、IDirectPlay4::SetGroupName、または IDirectPlay4::SetSessionDesc メソッドにより、リモート プレーヤー データ、グループ データ、またはセッション データを変更したときに、セッションでシステム メッセージを送信しないように指定する。フラグが指定されていない場合、データが変更されたことを示すメッセージが生成される。

ただし、このフラグを設定すると DPMSG_SETSESSIONDESC メッセージも抑制される。

DPSESSION_NOMESSAGEID
セッションで、メッセージの送信元や送信先のプレーヤーを示すメッセージをデータに添付しないように指定する。このフラグを設定すると、この情報が関係ない場合、メッセージのオーバヘッドが抑えられる (詳細については、IDirectPlay4::Receive メソッドを参照すること)。このフラグが指定されていない場合、メッセージ ID が追加される。このフラグは、セッションが作成されたときに指定する必要がある。
DPSESSION_NOPRESERVEORDER
セッションで保証付きメッセージの受信順序を保持しないように指定する。デフォルトでは、保証付きメッセージの受信順序が保持される。この順序が必要ない場合、このフラグを使用すると、配信時の遅延をなくすことができる。
DPSESSION_OPTIMIZELATENCY
サービス プロバイダに遅延時間について最適化を行うように要求する (TCP/IP でナグリング機能をオフにする)。デフォルトでは、帯域幅について最適化が行われる。
DPSESSION_PASSWORDREQUIRED
このセッションがパスワードにより保護されるように指定する。セッションに参加したいアプリケーションは、IDirectPlay4::Open 呼び出しでパスワードを指定する必要がある。これは、読み取り専用フラグである。セッションのホストで NULL 以外のパスワードが指定されると、これは DirectPlay により自動的に設定される。
DPSESSION_PRIVATE
これがプライベート セッションであると指定する。これは、要求に NULL 以外の一致するパスワードが含まれていない限り、列挙要求に応答できない。このフラグが指定されていない場合、セッションは列挙要求に応答する。
DPSESSION_SECURESERVER
セッションが、開く前に認証証明書を要求する保証サーバーをホストとするように指定する。ホストは、セッションが作成されるときにこのフラグを指定する必要がある。IDirectPlay4::SetSessionDesc を使用しても後で変更することはできない。このフラグは、DPSESSION_MIGRATEHOST フラグでは使用でない。
guidInstance
セッション インスタンスの GUID。
guidApplication
セッション インスタンスで実行されているアプリケーションの GUID。これは、DirectPlay が同じアプリケーションを実行しているその他のコンピュータにのみ接続されるように、アプリケーションを一意に識別する。このメンバに GUID_NULL を設定すれば、任意のアプリケーションのセッションを列挙できる。
dwMaxPlayers
このセッションで許可されているプレーヤーの最大数。この値が 0 のときは、最大数が指定されていないことを意味する。
dwCurrentPlayers
セッション内の現在のプレーヤー数。
lpszSessionName
セッションの名前が格納されている Unicode 文字列へのポインタ。Unicode DirectPlay インターフェイス (IDirectPlay4 インターフェイス) が使用されている場合にのみ使用する。
lpszSessionNameA
セッションの名前が格納されている ANSI 文字列へのポインタ。ANSI DirectPlay インターフェイス (IDirectPlay4A) が使用されている場合にのみ使用する。
lpszPassword
参加するためにセッションに参加するときに使用されるパスワードが格納されている Unicode 文字列へのポインタ。Unicode DirectPlay インターフェイス (IDirectPlay4 インターフェイス) が使用されている場合にのみ使用する。
lpszPasswordA
セッションに参加するときに使用されるパスワードが格納されている ANSI 文字列へのポインタ。ANSI DirectPlay インターフェイス (IDirectPlay4A) が使用されている場合にのみ使用する。
dwReserved1 および dwReserved2
0 でなければならない。
dwUser1、dwUser2、dwUser3、および dwUser4
セッションのアプリケーション固有のデータ。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::EnumSessions、IDirectPlay4::GetSessionDesc、IDirectPlay4::Open、IDirectPlay4::SecureOpen、IDirectPlay4::SetSessionDesc、IDirectPlay4::CreatePlayer


システム メッセージ

次に、DirectPlay のシステム メッセージを示す。

  • DPMSG_ADDGROUPTOGROUP
  • DPMSG_ADDPLAYERTOGROUP
  • DPMSG_CHAT
  • DPMSG_CREATEPLAYERORGROUP
  • DPMSG_DELETEGROUPFROMGROUP
  • DPMSG_DELETEPLAYERFROMGROUP
  • DPMSG_DESTROYPLAYERORGROUP
  • DPMSG_GENERIC
  • DPMSG_HOST
  • DPMSG_SECUREMESSAGE
  • DPMSG_SENDCOMPLETE
  • DPMSG_SESSIONLOST
  • DPMSG_SETGROUPOWNER
  • DPMSG_SETPLAYERORGROUPDATA
  • DPMSG_SETPLAYERORGROUPNAME
  • DPMSG_SETSESSIONDESC
  • DPMSG_STARTSESSION


DPMSG_ADDGROUPTOGROUP

グループがグループに追加されると、DirectPlay は DPMSG_ADDGROUPTOGROUP 構造体を生成し、それをすべてのプレーヤーに送信する。

typedef struct{
    DWORD    dwType;
    DPID     dpIdParentGroup;
    DPID     dpIdGroup;
} DPMSG_ADDGROUPTOGROUP, FAR *LPDPMSG_ADDGROUPTOGROUP;
dwType
メッセージを識別する。このメンバは、DPSYS_ADDGROUPTOGROUP である。
dpIdParentGroup
グループの追加先グループの ID。
dpIdGroup
グループに追加されたグループの ID。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::AddGroupToGroup


DPMSG_ADDPLAYERTOGROUP

DPMSG_ADDPLAYERTOGROUP 構造体には、DPSYS_ADDPLAYERTOGROUP システム メッセージに関する情報が格納される。プレーヤーがグループに追加されると、DirectPlay はこのメッセージを生成し、それをすべてのプレーヤーに送信する。

このアプリケーションでは、このメッセージの IDirectPlay4::GetPlayerCaps、IDirectPlay4::GetPlayerName、および IDirectPlay4::GetPlayerData を使用して起動されたプレーヤーの情報を取得したり、またはこのメッセージの IDirectPlay4::GetGroupName や IDirectPlay4::GetGroupData を使用して起動されたグループの詳細情報を取得できる。

typedef struct{
    DWORD dwType;
    DPID  dpIdGroup;
    DPID  dpIdPlayer;
} DPMSG_ADDPLAYERTOGROUP, FAR *LPDPMSG_ADDPLAYERTOGROUP;
dwType
メッセージを識別する。このメンバは、DPSYS_ADDPLAYERTOGROUP である。
dpIdGroup
プレーヤーの追加先グループの ID。
dpIdPlayer
グループに追加されるプレーヤーの ID。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::AddPlayerToGroup


DPMSG_CHAT

DPMSG_CHAT 構造体は、DPSYS_CHAT システム メッセージに関する情報を保持する。このシステム メッセージは、別のプレーヤーからチャット メッセージを受け取ったローカル プレーヤーに対して生成される。

typedef struct{
    DWORD dwType;
    DWORD dwFlags;
    DPID  idFromPlayer;
    DPID  idToPlayer;
    DPID  idToGroup;
    LPDPCHAT  lpChat;
} DPMSG_CHAT, FAR *LPDPMSG_CHAT;
dwType
メッセージを識別する。このメンバには、DPSYS_CHAT 値が設定される。
dwFlags
使用しない。
idFromPlayer
メッセージの送信元プレーヤーの ID。DPID_SERVERPLAYER は、メッセージの発信元がサーバーであることを示している。
idToPlayer
メッセージの送信先プレーヤーの ID。この値が 0 の場合、メッセージはグループに送信されるか、またはすべてにブロードキャストされる。
idToGroup
メッセージの送信先グループの ID。この値が 0 で、また idToPlayer も 0 の場合、メッセージはすべてにブロードキャストされる。
lpChat
受信したチャット メッセージのコンテンツが格納されている DPCHAT 構造体へのポインタ。

注意

この idFromPlayer 値を使用して、メッセージの送信元を判定する。Receive で使用可能な lpidFrom の値は常に 0 なので、DPMSG_CHAT 構造体の idFromPlayer の値を取得する必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::SendChatMessage、DPCHAT、IDirectPlay4::Receive


DPMSG_CREATEPLAYERORGROUP

DPMSG_CREATEPLAYERORGROUP 構造体は、DPSYS_CREATEPLAYERORGROUP システム メッセージに関する情報を保持する。プレーヤーやグループがセッションで作成されると、システムによりこのメッセージが生成される。

DirectPlay は、新しいプレーヤーやグループがセッションで作成されると、このメッセージを生成して各プレーヤーに送信する。

typedef struct{
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    DWORD  dwCurrentPlayers;
    LPVOID lpData;
    DWORD  dwDataSize;
    DPNAME dpnName;
    DPID   dpIDParent;
    DWORD  dwFlags;
} DPMSG_CREATEPLAYERORGROUP, FAR *LPDPMSG_CREATEPLAYERORGROUP;
dwType
メッセージを識別する DWORD。このメンバには、DPSYS_CREATEPLAYERORGROUP を設定すること。
dwPlayerType
メッセージをプレーヤー (DPPLAYERTYPE_PLAYER) またはグループ (DPPLAYERTYPE_GROUP) のいずれに適用するかを指定する DWORD。
dpId
作成するプレーヤーまたはグループの ID。
dwCurrentPlayers
セッション内のプレーヤー数。
lpData
このプレーヤーやグループに関連付けられているアプリケーションに固有のリモート データへのポインタ。このメンバが NULL の場合、リモート データはない。
dwDataSize
lpData により参照されるバッファに格納されているデータのサイズ。
dpnName
プレーヤーやグループの名前が格納されている構造体。
dpIDParent
IDirectPlay4::CreateGroupInGroup を呼び出したためにこのメッセージが生成された場合は親グループの ID。それ以外の場合、この値は 0 となる。
dwFlags
プレーヤーまたはグループのフラグ。
DPGROUP_HIDDEN
隠しグループが作成されるとき、設定される。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::CreateGroup、IDirectPlay4::CreatePlayer、IDirectPlay4::CreateGroupInGroup


DPMSG_DELETEGROUPFROMGROUP

DirectPlay は、グループがグループから削除されると、DPMSG_DELETEGROUPFROMGROUP 構造体を生成し、それをすべてのプレーヤーに送信する。この構造体は DPMSG_ADDGROUPTOGROUP と同じであるので注意すること。

typedef struct{
    DWORD    dwType;
    DPID     dpIdParentGroup;
    DPID     dpIdGroup;
} DPMSG_ADDGROUPTOGROUP, FAR *LPDPMSG_ADDGROUPTOGROUP;
typedef DPMSG_ADDGROUPTOGROUP DPMSG_DELETEGROUPFROMGROUP;
dwType
メッセージを識別する。このメンバは、DPSYS_DELETEGROUPFROMGROUP である。
dpIdParentGroup
グループを削除するグループの ID。
dpIdGroup
グループから削除されるグループの ID。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::DeleteGroupFromGroup


DPMSG_DELETEPLAYERFROMGROUP

DPMSG_DELETEPLAYERFROMGROUP 構造体は、DPSYS_DELETEPLAYERFROMGROUP システム メッセージに関する情報を保持する。DirectPlay は、プレーヤーがグループから削除されると、このメッセージを生成し、それをコンピュータ上の各ローカル プレーヤーに送信する。

構造体のメンバについては、DPMSG_ADDPLAYERTOGROUP 構造体を参照すること。

このアプリケーションでは、このメッセージの IDirectPlay4::GetPlayerCaps、IDirectPlay4::GetPlayerName、および IDirectPlay4::GetPlayerData を使用して起動されたプレーヤーの情報を取得したり、またはこのメッセージの IDirectPlay4::GetGroupName や IDirectPlay4::GetGroupData を使用して起動されたグループの詳細情報を取得できる。

typedef struct{
    DWORD dwType;
    DPID  dpIdGroup;
    DPID  dpIdPlayer;
} DPMSG_ADDPLAYERTOGROUP, FAR *LPDPMSG_ADDPLAYERTOGROUP;
typedef DPMSG_ADDPLAYERTOGROUP DPMSG_DELETEPLAYERFROMGROUP;
dwType
メッセージを識別する。このメンバは、DPSYS_DELETEPLAYERFROMGROUP である。
dpIdGroup
プレーヤーを削除するグループの ID。
dpIdPlayer
グループから削除されるプレーヤーの ID。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::DeletePlayerFromGroup


DPMSG_DESTROYPLAYERORGROUP

DPMSG_DESTROYPLAYERORGROUP 構造体は、DPSYS_DESTROYPLAYERORGROUP システム メッセージに関する情報を保持する。DirectPlay は、プレーヤーやグループがセッション内で壊れると、このメッセージを生成し、各プレーヤーに送信する。

typedef struct{
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    LPVOID lpLocalData;
    DWORD  dwLocalDataSize;
    LPVOID lpRemoteData;
    DWORD  dwRemoteDataSize;
    DPNAME dpnName;
    DPID   dpIdParent;
    DWORD  dwFlags;
} DPMSG_DESTROYPLAYERORGROUP, FAR *LPDPMSG_DESTROYPLAYERORGROUP;
dwType
メッセージを識別する DWORD。このメンバは、DPSYS_DESTROYPLAYERORGROUP である。
dwPlayerType
メッセージをプレーヤー (DPPLAYERTYPE_PLAYER) またはグループ (DPPLAYERTYPE_GROUP) のいずれに適用するかを指定する DWORD。
dpId
壊されたプレーヤーまたはグループの ID。
lpLocalData
このプレーヤーまたはグループに関連付けられたローカル データへのポインタ。
dwLocalDataSize
ローカル データのサイズ (バイト単位)。
lpRemoteData
このプレーヤーまたはグループに関連付けられたリモート データへのポインタ。
dwRemoteDataSize
リモート データのサイズ (バイト単位)。
dpnName
プレーヤーやグループの名前が格納されている構造体。
dpIdParent
壊されたグループが親グループのサブグループの場合、つまり壊されたグループが IDirectPlay4::CreateGroupInGroupを呼び出して作成された場合、親グループの ID。それ以外の場合、この値は 0 となる。
dwFlags
プレーヤーまたはグループのフラグ。次の値のいずれか、またはいくつかとなる。
DPGROUP_HIDDEN
隠しグループが壊れたとき、設定される。
DPGROUP_STAGINGAREA
ステージング領域であるグループが壊れたとき、設定される。
DPPLAYER_SERVERPLAYER
壊れたプレーヤーがクライアント／サーバー通信のサーバー プレーヤーのとき、設定される。
DPPLAYER_SPECTATOR
壊れたプレーヤーが観客のとき、設定される。

注意

DirectX 5.0 では、この構造体のバージョンで dpnName、dpIdParent、dwFlags の 3 つのメンバが最後に追加されている。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::DestroyGroup、IDirectPlay4::DestroyPlayer


DPMSG_GENERIC

DPMSG_GENERIC 構造体は、メッセージ処理のために提供されている。

typedef struct{
    DWORD dwType;
} DPMSG_GENERIC, FAR *LPDPMSG_GENERIC;
dwType
システム メッセージのタイプを識別する。タイプ リストについては、システム メッセージの使用 を参照すること。

注意

システム メッセージを受け取ると (つまり、lpidFrom パラメータによりポイントされている値が DPID_SYSMSG であると)、まず未確認のメッセージ データを DPMSG_GENERIC 型に設定し、さらに dwType の値に基づいて処理を実行する。メッセージ タイプが判定された後、そのメッセージは、さらに処理するためにシステム メッセージの既知のタイプのいずれかに設定できる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。


DPMSG_HOST

カレント セッションのホストがセッションを終了すると、ホストの仕事を継承するコンピュータ上のすべてのプレーヤーに DPMSG_HOST メッセージが送信される。

typedef DPMSG_GENERIC    DPMSG_HOST;
typedef DPMSG_HOST  FAR *LPDPMSG_HOST;

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

DPMSG_GENERIC


DPMSG_SECUREMESSAGE

DirectPlay は、別のプレーヤーから署名付きメッセージまたは暗号化メッセージを受け取ると DPMSG_SECUREMESSAGE 構造体を生成する。

typedef struct {
    DWORD   dwType;
    DWORD   dwFlags;
    DPID    dpIdFrom;
    LPVOID  lpData;
    DWORD   dwDataSize;
} DPMSG_SECUREMESSAGE, FAR *LPDPMSG_SECUREMESSAGE;
dwType
システム メッセージのタイプを識別する。これは、DPSYS_SECUREMESSAGE となる。
dwFlags
送信者によるメッセージの保護方法を示すフラグ。次の値のいずれかとなる。
DPSEND_SIGNED
メッセージは送信者により署名されており、その署名は検証済みである。
DPSEND_ENCRYPTED
メッセージは送信者により暗号化されており、正常に解読された。
dpIdFrom
機密保護メッセージを送信したプレーヤーの DPID。
lpData
完全に検証されたメッセージが格納されたバッファへのポインタ。
dwDataSize
メッセージが格納されているバッファのサイズ。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::Send


DPMSG_SENDCOMPLETE

DPMSG_SENDCOMPLETE 構造体は、アプリケーションに非同期送信の完了ステータスを知らせるために受信キューに送信される。デフォルトでは、非同期メッセージが IDirectPlay4::SendEx の DPSEND_ASYNC フラグを使用して送信されると、このメッセージが生成される。

typedef struct{
    DWORD    dwType;
    DPID     idFrom;
    DPID     idTo;
    DWORD    dwFlags;
    DWORD    dwPriority;
    DWORD    dwTimeout;
    LPVOID   lpContext;
    DWORD    dwMsgID;
    HRESULT  hr;
    DWORD    dwSendTime;
} DPMSG_SENDCOMPLETE, FAR *LPDPMSG_SENDCOMPLETE;
dwType
メッセージを識別する値。このメンバは、DPSYS_SENDCOMPLETE である。
idFrom
メッセージを送信するプレーヤーの DPID。
idTo
メッセージの送信先プレーヤーの DPID。
dwFlags
メッセージが送信されたときに SendEx で指定されたフラグ。
dwPriority
メッセージ送信時の優先順位。
dwTimeout
メッセージ送信時に指定されたタイムアウト (SendEx で指定)。0 は、デフォルトのタイムアウトを示す。
lpContext
アプリケーションにより SendEx に渡される lpContext パラメータ。
dwMsgID
DirectPlay により SendEx からアプリケーションに返される dwMsgID。
hr
非同期メッセージの HRESULT。次の値のいずれかとなる。
DP_OK
メッセージは正常に送信された。
DPERR_ABORTED
メッセージは、転送時に取り消された。
DPERR_CANCELLED
メッセージは、まだ送信キューにあるときに取り消された。
DPERR_GENERIC
メッセージは送信できなかった。
DPERR_TIMEOUT
メッセージは時間切れとなり、送信キューから削除された。
dwSendTime
アプリケーションがメッセージを (SendEx を呼び出すことにより) 送信してから、DirectPlay がメッセージを送信できるまでの経過時間 (ミリ秒単位)。これには、送信キューでの経過時間や、サービス プロバイダにメッセージを渡すための時間も含まれる。保証付きメッセージの場合は、メッセージ配信の肯定応答を返すための時間も含まれる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::SendEx


DPMSG_SESSIONLOST

DPMSG_SESSIONLOST 構造体は、セッション内のその他すべてのプレーヤーへの接続が喪失したときに DirectPlay により生成される。セッションが喪失した後は、メッセージをリモート プレーヤーに送信できないが、セッション喪失時のデータはすべてまだ使用できる。このメッセージを受け取ったら、アプリケーションで回復を試みて、終了すること。

typedef DPMSG_GENERIC    DPMSG_SESSIONLOST;
typedef DPMSG_SESSIONLOST  FAR  *LPDPMSG_SESSIONLOST;

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

DPMSG_GENERIC


DPMSG_SETGROUPOWNER

DPMSG_SETGROUPOWNER 構造体は、グループの所有者が変更されたときに DirectPlay により生成される。グループの所有権は、現在の所有者がセッションを退出したり、IDirectPlay4::SetGroupOwner を呼び出したことにより、または任意でロビー セッションのロビー サーバーにより変更される。

typedef struct{
  DWORD   dwType;
  DPID    idGroup;
  DPID    idNewOwner;
  DPID    idOldOwner;
} DPMSG_SETGROUPOWNER, FAR *LPDPMSG_SETGROUPOWNER;
dwType
メッセージを識別する値。このメンバは、DPSYS_SETGROUPOWNER である。
idGroup
所有者が変更されたグループの ID。
idNewOwner
グループの新しい所有者であるプレーヤーの ID。
idOldOwner
グループの古い所有者であるプレーヤーの ID。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::SetGroupOwner


DPMSG_SETPLAYERORGROUPDATA

DPMSG_SETPLAYERORGROUPDATA メッセージ構造体は、DPSYS_SETPLAYERORGROUPDATA システム メッセージに関する情報を保持する。DirectPlay は、プレーヤーやグループのリモート データが変更されると、このメッセージを生成して各プレーヤーに送信する。このメッセージは、セッション記述で DPSESSION_ NODATAMESSAGES フラグが指定されている場合は生成されない。

typedef struct {
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    LPVOID lpData;
    DWORD  dwDataSize;
} DPMSG_SETPLAYERORGROUPDATA, FAR *LPDPMSG_SETPLAYERORGROUPDATA;
dwType
メッセージを識別する。この値は、常に DPSYS_SETPLAYERORGROUPDATA である。
dwPlayerType
メッセージをプレーヤー (DPPLAYERTYPE_PLAYER) またはグループ (DPPLAYERTYPE_GROUP) のいずれに適用するかどうかを識別する。
dpId
データが変更されるプレーヤーまたはグループの ID。
lpData
データのアプリケーション固有のブロックへのポインタ。
dwDataSize
lpData により参照されるバッファに格納されているデータのサイズ。

注意

データは IDirectPlay4::GetPlayerData または IDirectPlay4::GetGroupData を使用していつでも取得できるので、アプリケーションがこのメッセージからデータを保存する必要はない。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::SetPlayerData、IDirectPlay4::SetGroupData


DPMSG_SETPLAYERORGROUPNAME

DPMSG_SETPLAYERORGROUPNAME 構造体は、DPSYS_SETPLAYERORGROUPNAME システム メッセージに関する情報を保持する。DirectPlay は、プレーヤーまたはグループの名前が変更されると、このメッセージを生成して、コンピュータ上の各ローカル プレーヤーに送信する。このメッセージは、セッション記述で DPSESSION_NODATAMESSAGES フラグが指定されている場合は生成されない。

typedef struct {
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    DPNAME dpnName;
} DPMSG_SETPLAYERORGROUPNAME, FAR *LPDPMSG_SETPLAYERORGROUPNAME;
dwType
メッセージを識別する。この値は、常に DPSYS_SETPLAYERORGROUPNAME となる。
dwPlayerType
メッセージをプレーヤー (DPPLAYERTYPE_PLAYER) またはグループ (DPPLAYERTYPE_GROUP) のいずれに適用するかどうかを識別する。
dpId
名前が変更されるプレーヤーまたはグループの ID。
dpnName
プレーヤーまたはグループの新しい名前情報が格納されている構造体。

注意

dpnName は IDirectPlay4::GetPlayerName または IDirectPlay4::GetGroupName を使用していつでも取得できるので、アプリケーションがこのメッセージからそれを保存する必要はない。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::GetPlayerName、IDirectPlay4::GetGroupName、IDirectPlay4::SetPlayerName、IDirectPlay4::SetGroupName


DPMSG_SETSESSIONDESC

DPMSG_SETSESSIONDESC は、DPSYS_SETSESSIONDESC システム メッセージに関する情報を保持する。セッション記述が変更されると、すべてのプレーヤーがこのシステム メッセージを受け取る。

このメッセージは、セッション記述で DPSESSION_NODATAMESSAGES フラグが指定されている場合は生成されない。

typedef struct {
    DWORD           dwType;
    DPSESSIONDESC2  dpDesc;
} DPMSG_SETSESSIONDESC, FAR *LPDPMSG_SETSESSIONDESC;
dwType
メッセージを識別する。この値は、常に DPSYS_SETSESSIONDESC となる。
dpDesc
更新されたセッション記述が格納されている DPSESSIONDESC2 構造体へのポインタ。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::GetSessionDesc、IDirectPlay4::SetSessionDesc


DPMSG_STARTSESSION

DPMSG_STARTSESSION メッセージ構造体は、DPSYS_STARTSESSION システム メッセージに関する情報を保持する。ロビー サーバーは、プレーヤーがアプリケーション セッションに参加する時間になると、そのグループの各プレーヤーにこのメッセージを送信する。

typedef struct {
   DWORD            dwType;
   LPDPLCONNECTION  lpConn;
} DPMSG_STARTSESSION, FAR *LPDPMSG_STARTSESSION;
dwType
メッセージを識別する。この値は、常に DPSYS_STARTSESSION となる。
lpConn
セッションでアプリケーションを起動するのに必要なすべての情報が格納されている DPLCONNECTION 構造体へのポインタ。この構造体を IDirectPlayLobby3::RunApplication に渡したり (外部アプリケーションが起動される場合)、IDirectPlayLobby3::SetConnectionSettings に渡した後、IDirectPlayLobby3::Connect が呼び出される (カレント アプリケーションをセッションに接続するため)。

注意

スタンドアローンのロビー クライアントがこのメッセージを受け取った場合、クライアントは DPLCONNECTION 構造体を使用して IDirectPlayLobby3::RunApplication メソッドを呼び出し、アプリケーションを起動する必要がある。

内部ロビーでアプリケーションがこのメッセージを受け取った場合、そのアプリケーションは IDirectPlayLobby3::SetConnectionSettings メソッドを呼び出して接続設定を設定してから、IDirectPlayLobby3::Connect メソッドを使用してセッションに接続する必要がある。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。

参照

IDirectPlay4::StartSession、IDirectPlayLobby3::RunApplication、IDirectPlayLobby3::SetConnectionSettings、IDirectPlayLobby3::Connect


標準ロビー メッセージ

アプリケーションを起動したロビーで標準ロビー メッセージがサポートされているかどうかを判定するには、ロビーに最初に DPLMSG_GETPROPERTY 要求を送信して、それに応答があるかどうかを調べる。要求するプロパティは、DPLPROPERTY_MessagesSupported である。

ロビーからの応答が TRUE であった場合、それ以降のメッセージにもすべて応答が返されると見なすことできる。応答が FALSE であるか、または指定されたタイムアウトの時間内にまったく応答がなかった場合、そのメッセージはサポートされていないと見なされる。

アプリケーションは、観客 プレーヤーをサポートしている場合、プレーヤーを作成するとき、その前にそれを観客として作成するかどうかを判定するために DPLPROPERTY_PlayerGuid を要求することも必要である。

次に、DirectPlay 標準ロビー メッセージを示す。

  • DPLMSG_GENERIC
  • DPLMSG_GETPROPERTY
  • DPLMSG_GETPROPERTYRESPONSE
  • DPLMSG_NEWSESSIONHOST
  • DPLMSG_SETPROPERTY
  • DPLMSG_SETPROPERTYRESPONSE
  • DPLMSG_SYSTEMMESSAGE

参照

ロビー メッセージの使用、ロビーとの関係の維持


DPLMSG_GENERIC

DPLMSG_GENERIC は、ロビー クライアントとアプリケーションの間で送受信されるシステム メッセージの汎用構造体である。

typedef struct {
    DWORD dwType;
} DPLMSG_GENERIC, FAR *LPDPLMSG_GENERIC;
dwType
受信されたシステム メッセージのタイプを識別する。

注意

ロビー システム メッセージが受信されると (つまり、lpidFrom パラメータによりポイントされた値が DPID_SYSMSG であると)、まず未確認のメッセージ データを DPLMSG_GENERIC 型にキャストし、さらに dwType の値に基づいて処理を実行する。メッセージ タイプが判定された後、そのメッセージは、さらに処理するためにロビー システム メッセージの既知のタイプのいずれかに設定できる。

ロビー メッセージのタイプ リストについては、ロビー メッセージの使用 を参照すること。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。

参照

DPLMSG_SYSTEMMESSAGE


DPLMSG_GETPROPERTY

DPLMSG_GETPROPERTY メッセージは、アプリケーションにより、プロパティの現在の値を要求するために送信される。これらのプロパティは、プレーヤーのランキング、プレーヤーを表すビットマップ、またはロビー内で行われたゲームやプレーヤーの初期構成情報などの情報でもある。

typedef struct {
    DWORD   dwType;
    DWORD   dwRequestID;
    GUID    guidPlayer;
    GUID    guidPropertyTag;
} DPLMSG_GETPROPERTY, FAR *LPDPLMSG_GETPROPERTY;
dwType
メッセージを識別する。この値は、DPLSYS_ GETPROPERTY である。
dwRequestID
要求を識別するためにアプリケーションにより生成された ID。ロビーから応答が返されるとき、この要求 ID が設定されている。アプリケーションは、この要求 ID を使用して、応答をペンディング状態の要求と照合できる。
guidPlayer
このプロパティが適用される (適用可能な場合) プレーヤーを識別する GUID。プロパティがプレーヤーに固有でない場合、このメンバには GUID_NULL が設定される。このアプリケーションにより生成されたプレーヤーの GUID は、DPLPROPERTY_PlayerGuid プロパティを要求することによりロビーから取得できる。
guidPropertyTag
要求されたプロパティを識別する GUID。このプロパティは「DirectPlay 定義済みプロパティ」に示している事前に定義された GUID のいずれかであるか、またはアプリケーションやロビーにより追加プロパティに独自の GUID を定義することもできる。」

注意

各プロパティは、GUID (アプリケーション開発者またはロビー開発者により定義される) により識別される。プロパティ要求が行われると、ロビーは DPLMSG_GETPROPERTYRESPONSE メッセージを使用して応答を返す。ロビーは、情報を提供できない場合でも、その情報が使用不可能であることを示すエラーを返す。

アプリケーションでは、応答を待機するのではなく、ペンディング状態の要求が満たされなければそれらを時間切れにすべきである。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。

参照

DPLMSG_GETPROPERTYRESPONSE


DPLMSG_GETPROPERTYRESPONSE

DPLMSG_GETPROPERTYRESPONSE メッセージは、ロビーにより、DPLMSG_GETPROPERTY メッセージへの応答としてアプリケーションに送信される。要求が満たされた場合、その要求は dwRequestID メンバにより識別される。

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    HRESULT  hr;
    DWORD    dwDataSize;
    DWORD    dwPropertyData[1];
} DPLMSG_GETPROPERTYRESPONSE, FAR *LPDPLMSG_GETPROPERTYRESPONSE;
dwType
メッセージを識別する。この値は、DPLSYS_ GETPROPERTYRESPONSE である。
dwRequestID
このメッセージの応答先の DPLMSG_GETPROPERTY メッセージを識別する ID。
guidPlayer
このプロパティが適用される (適用可能な場合) プレーヤーを識別する GUID。プロパティがプレーヤーに固有でない場合、このメンバには GUID_NULL が設定される。これは、DPLMSG_GETPROPERTY メッセージの GUID と同じである。
guidPropertyTag
要求されたプロパティを識別する GUID。これは、DPLMSG_GETPROPERTY メッセージの GUID と同じである。
hr
プロパティ取得要求の戻りコード。次の値のいずれかである。
DP_OK
プロパティは正常に返された。
DPERR_UNKNOWNMESSAGE
要求されたプロパティは、ロビーでは確認されていない。
DPERR_UNAVAILABLE
要求されたプロパティは、使用不可能な状態である。
dwDataSize
プロパティ データのサイズ (バイト単位)。
dwPropertyData
プロパティ データが格納されている可変サイズのバッファ。プロパティ タグは、このデータの解釈方法を定義している。

注意

ロビーは、すべての DPLMSG_GETPROPERTY 要求に応答するか、またはまったく応答しない。

このメッセージを構成するとき、ロビーは DPLMSG_GETPROPERTYRESPONSE 構造体と完全なプロパティ データを保持するのに十分なメモリを割り当てる必要がある。たとえば、プロパティ データで 52 バイトが必要な場合、ロビーは (sizeof(DPLMSG_GETPROPERTYRESPONSE) + 52) バイトを割り当て、それを DPLMSG_GETPROPERTYRESPONSE ポインタに割り当てる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。

参照

DPLMSG_GETPROPERTY


DPLMSG_NEWSESSIONHOST

DPLMSG_NEWSESSIONHOST メッセージは、コンピュータ上のクライアントがアプリケーション セッションの新しいホストになったとき、DirectPlay により生成され、ロビー クライアント/プロバイダに送信される。

typedef struct {
    DWORD    dwType;
    GUID     guidInstance;
} DPLMSG_NEWSESSIONHOST, FAR *LPDPLMSG_NEWSESSIONHOST;
dwType
メッセージを識別する値。この値は、DPLSYS_NEWSESSIONHOST である。
guidInstance
セッションのこのインスタンスのグローバル ユニーク識別子 (GUID) を識別する値。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。


DPLMSG_SETPROPERTY

DPLMSG_SETPROPERTY メッセージは、特定のプレーヤーのプロパティまたはセッションのプロパティが変更されたことをロビーに知らせるために、アプリケーションによりロビーに送信される。これらのプロパティには、プレーヤーのスコアや状態から、ゲームのカレント レベルやセッションの現在の状態までが含まれる。

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    DWORD    dwDataSize;
    DWORD    dwPropertyData[1];
} DPLMSG_SETPROPERTY, FAR *LPDPLMSG_SETPROPERTY;
dwType
メッセージを識別する。この値は、DPLSYS_SETPROPERTY である。
dwRequestID
データが認識されて適切に設定されたことを確認したい場合にアプリケーションにより指定される 0 以外の要求 ID。確認の必要がない場合は、これには DPL_NOCONFIRMATION が設定される。
guidPlayer
このプロパティが適用される (適用可能な場合) プレーヤーを識別する GUID。プロパティがプレーヤーに固有でない場合、このメンバには GUID_NULL が設定される。このアプリケーションにより生成されたプレーヤーの GUID は、DPLPROPERTY_PlayerGuid プロパティを要求することによりロビーから取得できる。
guidPropertyTag
設定されたプロパティを識別する GUID。このプロパティは「DirectPlay 定義済みプロパティ」に示している事前に定義された GUID のいずれかであるか、またはアプリケーションやロビーにより追加プロパティに独自の GUID を定義することもできる。
dwDataSize
プロパティ データのサイズ (バイト単位)。
dwPropertyData
プロパティ データが格納されている可変サイズのバッファ。プロパティ タグは、このデータの解釈方法を定義している。

注意

各プロパティは、GUID (アプリケーション開発者またはロビー開発者により定義される) により識別される。さまざまなアプリケーションのプロパティ GUID からその記述やデータ タイプへのマッピングを保持するのは、ロビーの役割である。ロビー サーバーは、情報に基づいて処理するようにも、それを無視するようにも選択できる。

このメッセージを構成するとき、アプリケーションは DPLMSG_SETPROPERTY 構造体と完全なプロパティ データを保持するのに十分なメモリを割り当てる必要がある。たとえば、プロパティ データで 52 バイトが必要な場合、アプリケーションは (sizeof(DPLMSG_SETPROPERTY) + 52) バイトを割り当て、それを LPDPLMSG_SETPROPERTY ポインタに割り当てる。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplobby.h で宣言。

参照

DPLMSG_SETPROPERTYRESPONSE


DPLMSG_SETPROPERTYRESPONSE

DPLMSG_SETPROPERTYRESPONSE メッセージは、DPLMSG_SETPROPERTY メッセージの確認としてロビーによりアプリケーションに送信される。確認するメッセージは、dwRequestID メンバにより識別される。

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    HRESULT  hr;
} DPLMSG_SETPROPERTYRESPONSE, FAR *LPDPLMSG_SETPROPERTYRESPONSE;
dwType
メッセージを識別する。この値は、DPLSYS_SETPROPERTYRESPONSE である。
dwRequestID
確認する DPLMSG_SETPROPERTY メッセージを識別する ID。
guidPlayer
このプロパティが適用される (適用可能な場合) プレーヤーを識別する GUID。プロパティがプレーヤーに固有でない場合、このメンバには GUID_NULL が設定される。このアプリケーションにより生成されたプレーヤーの GUID は、DPLMSG_SETPROPERTY メッセージからの GUID と同じである。
guidPropertyTag
設定されたプロパティを識別する GUID。これは、DPLMSG_SETPROPERTY メッセージの GUID と同じである。
hr
確認の結果。次の値のいずれかである。
DP_OK
プロパティは正常に設定された。
DPERR_ACCESSDENIED
ロビーにより変更が許可されていないプロパティを設定しようとした。
DPERR_UNKNOWNMESSAGE
プロパティは、ロビーで確認されていない。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。

参照

DPLMSG_SETPROPERTY


DPLMSG_SYSTEMMESSAGE

DPLMSG_SYSTEMMESSAGE 構造体は、ロビーとアプリケーション間で送受信されるシステム メッセージである。

typedef struct {
    DWORD    dwType;
    GUID     guidInstance;
} DPLMSG_SYSTEMMESSAGE, FAR *LPDPLMSG_SYSTEMMESSAGE;
dwType
受け取ったシステム メッセージのタイプを識別する。
DPLSYS_APPTERMINATED
IDirectPlayLobby3::RunApplication メソッドにより起動されたアプリケーションが終了したことを示す。
DPLSYS_CONNECTIONSETTINGSREAD
IDirectPlayLobby3::RunApplication メソッドにより起動されたアプリケーションが接続設定を読み取ったことを示す。
DPLSYS_DPLAYCONNECTFAILED
IDirectPlayLobby3::RunApplication メソッドにより起動されたアプリケーションでセッションへの接続が失敗したことを示す。
DPLSYS_DPLAYCONNECTSUCCEEDED
IDirectPlayLobby3::RunApplication メソッドにより起動されたアプリケーションがセッションを作成し、ほかのアプリケーションが参加するための準備を整えたか、またはセッションへの参加が成功したことを示す。
DPLSYS_NEWCONNECTIONSETTINGS
ロビー クライアントが RunApplication を呼び出したときに待機中のアプリケーションが見つかったことを示す。待機中のアプリケーションは、このとき GetConnectionSettings により接続設定を読み取って、ConnectEx を使用してセッションに参加することができる。
guidInstance
このメッセージが対応している DirectPlay セッションのインスタンスを識別する GUID。

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。


DirectPlay 定義済みプロパティ

ここでは、アプリケーションによりロビーから設定したり、取得できる事前に定義されたプロパティについて説明する。

DPLMSG_GETPROPERTYRESPONSE メッセージを受け取ると、その guidPropertyTag メンバにはプロパティを識別するための情報が、dwPropertyData メンバにはプロパティ情報が格納されている。この情報を抽出するには、dwPropertyData メンバに適切な値を設定する。たとえば、次のルーチンでは指定したメッセージから DPLDATA_PLAYERGUID 構造体を取得する (DPLPROPERTY_PlayerGuid を参照すること)。

BOOL GetPlayerGuid(
        LPDPLMSG_GETPROPERTYRESPONSE lpPropertyResponseMsg,
        LPDPLDATA_PLAYERGUID lpPlayerGuid)
{
   if (IsEqualGUID(lpPropertyResponseMsg->guidPropertyTag,
           DPLPROPERTY_PlayerGuid))
   {
      *lpPlayerGuid = *((LPDPLDATA_PLAYERGUID)
              lpPropertyResponseMsg->dwPropertyData);
      return (TRUE);
   }
   else
   {
      return (FALSE);
   }
}

事前に定義されたプロパティについては、以下を参照すること。

  • DPLPROPERTY_LobbyGuid
  • DPLPROPERTY_MessagesSupported
  • DPLPROPERTY_PlayerGuid
  • DPLPROPERTY_PlayerScore


DPLPROPERTY_LobbyGuid

DPLPROPERTY_LobbyGuid は、ロビー ソフトウェアを識別するときに使用する。アプリケーションがカスタム メッセージを使用して特定のロビーと相互操作するように設計されている場合、ロビーを識別するときにこのプロパティを使用す。

ただし、できるだけ多くのロビーと相互操作できるようにするために、アプリケーションでは可能な限り標準メッセージを使用すべきである。

このプロパティの場合、DPLMSG_GETPROPERTYRESPONSE 構造体の dwPropertyData メンバの内容は次のようになる。

GUID  guidLobby;

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。


DPLPROPERTY_MessagesSupported

DPLPROPERTY_MessagesSupported は、ロビーで標準メッセージがサポートされているかどうかを示すブール値である。アプリケーションは、標準メッセージがサポートされているかどうかを判定するために、ロビーのこのプロパティを要求できる。ロビーがこのメッセージに応答しなかった場合、または FALSE が返された場合、アプリケーションでは標準ロビー メッセージがサポートされていないと見なされ、それ以降はメッセージを送信しない。ロビーから TRUE が返された場合、アプリケーションは支障なく標準メッセージをロビーに送信し、さらにロビーのプロパティを問い合わせる。

このプロパティの場合、DPLMSG_GETPROPERTYRESPONSE 構造体の dwPropertyData メンバの内容は次のとおりである。

BOOL  fMessagesSupported;

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。


DPLPROPERTY_PlayerGuid

DPLPROPERTY_PlayerGuid は、アプリケーションのローカル プレーヤーを一意に識別するときに使用する。プレーヤーの GUID を必要とする DPLMSG_SETPROPERTY メッセージや DPLMSG_GETPROPERTY メッセージは、ロビーと通信するときにこの値を使用する必要がある。

アプリケーションは、別のコンピュータ上のリモート プレーヤーのプロパティを操作できる。アプリケーションは、リモート プレーヤーから (ロビーからではなく) プレーヤーの GUID を取得するだけでよい。

アプリケーションは観客 プレーヤーをサポートしている場合、プレーヤーを作成するときに使用するフラグ (存在する場合) を判定するために、プレーヤーを作成する前にこのプロパティを要求する必要がある。そのフラグは、DPPLAYER_SPECTATOR や DPPLAYER_SERVERPLAYER などである。

このプロパティの場合、DPLMSG_GETPROPERTYRESPONSE 構造体の dwPropertyData メンバの内容は次のとおりである。

typedef struct {
    GUID  guidPlayer;
    DWORD dwPlayerFlags;
} DPLDATA_PLAYERGUID, FAR *LPDPLDATA_PLAYERGUID;

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。


DPLPROPERTY_PlayerScore

DPLPROPERTY_PlayerScore は、ロビーに複合スコア値を報告するときにアプリケーションで使用できる汎用構造体である。スコアが適用されるプレーヤーの guidPlayer GUID は、このプロパティを設定したり取得するときに指定しなければならない。この構造体では、プレーヤーのスコアを集合的に表した long 型整数値の任意のリストを扱うことができる。アプリケーションは、すべてのスコアを保持するのに十分なメモリを割り当てる必要がある。たとえば、スコアが N 個の整数として渡された場合、アプリケーションは ( sizeof(DPLDATA_PLAYERSCORE) + N*sizeof(LONG) ) バイトを割り当て、そのポインタを LPDPLDATA_PLAYERSCORE に設定する必要がある。

このプロパティの場合、DPLMSG_GETPROPERTYRESPONSE 構造体の dwPropertyData メンバの内容は次のとおりである。

typedef struct {
    DWORD   dwScoreCount;
    LONG    Score[1];
} DPLDATA_PLAYERSCORE, FAR *LPDPLDATA_PLAYERSCORE;

必要条件

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : Dplobby.h で宣言。
インポート ライブラリ : dplayx.lib を使用。


戻り値

エラーは負の値で表され、それらを組み合わせることはできない。次の表に、IDirectPlay4 インターフェイスと IDirectPlayLobby3 インターフェイスのすべてのメソッドにより返される値を示す。各メソッドにより返されるエラー値については、個別のメソッドの説明を参照すること。

DirectPlay サンプルの多くには、HRESULT 値を DirectPlay エラーの文字列名に変換する GetDirectPlayErrStr 関数が含まれている。開発者は、診断トレースやエラー レポート用に各自のアプリケーションにこのコードをコピーできる。

CLASS_E_NOAGGREGATION
DirectPlayCreate、DirectPlayLobbyCreate、または IDirectPlayLobby3::Connect の pUnkOuter パラメータに、NULL 以外の値が渡された。
DP_OK
要求は正常に終了した。
DPERR_ABORTED
操作は、完了前に取り消された。
DPERR_ACCESSDENIED
セッションがいっぱいであるか、または不正なパスワードが指定された。
DPERR_ACTIVEPLAYERS
既存のアクティブなプレーヤーが存在していて、要求された操作が実行できなかった。
DPERR_ALREADYINITIALIZED
このオブジェクトは既に初期化されている。
DPERR_APPNOTSTARTED
アプリケーションがまだ起動されていない。
DPERR_AUTHENTICATIONFAILED
指定されたパスワードまたは証明書が認証できなかった。
DPERR_BUFFERTOOLARGE
データ バッファが大きすぎて保存できない。
DPERR_BUFFERTOOSMALL
指定されたバッファが、要求されたデータを格納するのに十分な大きさでない。
DPERR_BUSY
伝送媒体がビジー状態であるため、メッセージを送信できない。
DPERR_CANCELFAILED
おそらくメッセージがグループのメンバに既に送信されているグループ メッセージであるために、取り消すことができなかった。
DPERR_CANCELLED
操作が取り消された。
DPERR_CANNOTCREATESERVER
新しいセッションでサーバーを作成できない。
DPERR_CANTADDPLAYER
プレーヤーをセッションに追加できない。
DPERR_CANTCREATEGROUP
新しいグループを作成できない。
DPERR_CANTCREATEPLAYER
新しいプレーヤーを作成できない。
DPERR_CANTCREATEPROCESS
アプリケーションを起動できない。
DPERR_CANTCREATESESSION
新しいセッションを作成できない。
DPERR_CANTLOADCAPI
証明書が指定されず、また暗号化サービスで使用する CryptoAPI パッケージ (CAPI) をロードできない。
DPERR_CANTLOADSECURITYPACKAGE
ソフトウェア セキュリティ パッケージをロードできない。
DPERR_CANTLOADSSPI
証明書が指定されず、また証明書を要求するセキュリティ サポート プロバイダ インターフェイス (SSPI) をロードできない。
DPERR_CAPSNOTAVAILABLEYET
DirectPlay オブジェクトの能力がまだ決定されていない。このエラーは、DirectPlay オブジェクトが使用可能な帯域幅と遅延時間を判定するためにポーリングする必要がある接続ソリューションに実装されている場合に発生する。
DPERR_CONNECTING
このメソッドは、ネットワークに接続中である。アプリケーションは、正常終了を示す DP_OK が返されるまで、または別のエラーが返されるまでこのメソッドを使用し続ける。
DPERR_CONNECTIONLOST
データの送信中にサービス プロバイダ接続がリセットされた。
DPERR_ENCRYPTIONFAILED
要求された情報がデジタル式に暗号化できなかった。メッセージのプライバシーを保護するために暗号化機能が使用される。このエラーは、セキュア セッションにのみ関係がある。
DPERR_ENCRYPTIONNOTSUPPORTED
DPSECURITYDESC 構造体で要求された暗号化のタイプは使用できない。このエラーは、セキュア セッションにのみ関係がある。
DPERR_EXCEPTION
要求処理時に例外が発生した。
DPERR_GENERIC
未定義エラー条件が発生した。
DPERR_INVALIDFLAGS
このメソッドに渡されたフラグが無効であった。
DPERR_INVALIDGROUP
グループ ID が、このゲーム セッションの有効なグループ ID として認識されない。
DPERR_INVALIDINTERFACE
インターフェイス パラメータが無効である。
DPERR_INVALIDOBJECT
DirectPlay オブジェクト ポインタが無効である。
DPERR_INVALIDPARAMS
メソッドに渡されたパラメータのいずれかまたはいくつかが無効である。
DPERR_INVALIDPASSWORD
パスワードが必要なセッションに参加しようとしたときに、無効なパスワードが指定された。
DPERR_INVALIDPLAYER
プレーヤー ID がこのゲーム セッションの有効なプレーヤー ID として認識されない。
DPERR_INVALIDPRIORITY
指定された優先順位が、許可されている優先順位の範囲 (0 以上 65535 以下) 外である。
DPERR_LOGONDENIED
証明書が要求されているのに、証明書が指定されていないか、または証明書が無効であるため、セッションを開くことができなかった。
DPERR_NOCAPS
DirectPlay が使用しようとしている通信リンクでは、この機能を使用できない。
DPERR_NOCONNECTION
通信リンクが確立されなかった。
DPERR_NOINTERFACE
インターフェイスがサポートされていない。
DPERR_NOMESSAGES
受信キューにメッセージがない。
DPERR_NONAMESERVERFOUND
ネーム サーバー (ホスト) を見つけることができなかったか、作成できなかった。プレーヤーを作成するには、ホストが存在していなければならない。
DPERR_NONEWPLAYERS
セッションは、新しいプレーヤーを受け付けていない。
DPERR_NOPLAYERS
セッション内にアクティブなプレーヤーがいない。
DPERR_NOSESSIONS
このゲームに対応する既存のセッションがない。
DPERR_NOTLOBBIED
アプリケーションが IDirectPlayLobby3::RunApplication メソッドを使用して起動されなかった場合、またはこの DirectPlayLobby オブジェクトに対して現在初期化されている DPLCONNECTION 構造体がない場合、IDirectPlayLobby3::Connect メソッドにより返される。
DPERR_NOTLOGGEDIN
プレーヤー アプリケーションまたはクライアント アプリケーションがログオンされていないので、処理を実行できない。クライアント アプリケーションがログオンしないで機密保護メッセージを送信しようとすると、IDirectPlay4::Send メソッドにより返される。
DPERR_OUTOFMEMORY
要求された操作を実行するには、メモリが不足している。
DPERR_PENDING
エラーではない。この戻り値は、非同期送信で、キューへの設定が成功するところまで処理が進んだことを示す。詳細については、IDirectPlay4::SendEx を参照すること。
DPERR_PLAYERLOST
プレーヤーは、セッションへの接続を喪失した。
DPERR_SENDTOOBIG
IDirectPlay4::Send メソッドにより送信されているメッセージが大きすぎる。
DPERR_SESSIONLOST
セッションへの接続が喪失した。
DPERR_SIGNFAILED
要求された情報に、デジタル署名できなかった。デジタル署名は、メッセージを認証するときに使用される。
DPERR_TIMEOUT
指定された時間内に処理を完了できなかった。
DPERR_UNAVAILABLE
この時点では、要求された関数を使用できない。
DPERR_UNINITIALIZED
要求されたオブジェクトが初期化されていない。
DPERR_UNKNOWNAPPLICATION
未確認のアプリケーションが指定された。
DPERR_UNKNOWNMESSAGE
メッセージ ID が有効でない。取り消すメッセージの ID が無効の場合に、IDirectPlay4::CancelMessage から返される
DPERR_UNSUPPORTED
関数または機能を、この実装やこのサービス プロバイダで使用できない。IDirectPlay4::GetGroupConnectionSettings や IDirectPlay4::SetGroupConnectionSettings ロビー セッションでないセッションから呼び出された場合に、それらから返される。優先順位やタイムアウトが設定されている場合に、それらがサービス プロバイダによりサポートされておらず、また DirectPlay プロトコルがオンでないときに、IDirectPlay4::SendEx から返される。送信キューをチェックする場合に、それがサービス プロバイダによりサポートされておらず、また DirectPlay プロトコルがオンでないとき、IDirectPlay4::GetMessageQueue から返される。
DPERR_USERCANCEL
次の場合に返される。1) ユーザーが IDirectPlay4::Open メソッドを呼び出している最中に接続プロセスを取り消した場合。2) IDirectPlay4::EnumSessions を呼び出している最中に、ユーザーが DirectPlay サービス プロバイダのダイアログ ボックスのいずれかで [キャンセル] をクリックした場合。
E_UNKNOWN
一般に、なんらかの重大な障害が発生したことを示す。たとえば、サービス プロバイダが正しく初期化できなかったり、IPX などのプロトコルがコンピュータに正しくインストールされなかった。


DirectPlay Visual Basic リファレンス

ここでは、DirectPlay® for Visual Basic® のアプリケーション プログラミング インターフェイス (API) 要素のリファレンス情報を記述する。リファレンス情報は、以下のカテゴリに分類される。

  • クラス
  • 型
  • 列挙型
  • エラー コード


クラス

このセクションは、以下の DirectPlay クラスのメソッドに関するリファレンス情報を提供する。

  • DirectPlay4
  • DirectPlayAddress
  • DirectPlayEnumConnections
  • DirectPlayEnumLocalApplications
  • DirectPlayEnumPlayers
  • DirectPlayEnumSessions
  • DirectPlayLobby3
  • DirectPlayLobbyConnection
  • DirectPlayMessage
  • DirectPlaySessionData


DirectPlay4

アプリケーションは、DirectPlay4 クラスのメソッドを使用して、DirectPlay オブジェクトを作成したり、列挙を実行したり、接続を確立したり、セッション、プレーヤー、およびグループを管理したりする。

DirectX7.DirectPlayCreate メソッドを使用し、各アプリケーションに対して 1 つの DirectPlay4 オブジェクトを作成する。

DirectPlay4 クラスのメソッドは、以下のグループにまとめることができる。

接続 | GetDPEnumConnections
 | InitializeConnection
 | SetGroupConnectionSettings
セッション | Close
 | CreateSessionData
 | GetDPEnumSessions
 | GetCaps
 | GetSessionDesc
 | Open
 | SecureOpen
 | SetSessionDesc
 | StartSession
プレーヤー | CreatePlayer
 | DestroyPlayer
 | GetDPEnumPlayers
 | GetPlayerAccountId
 | GetPlayerAddress
 | GetPlayerCaps
 | GetPlayerData
 | GetPlayerFlags
 | GetPlayerFormalName
 | GetPlayerFriendlyName
 | SetPlayerData
 | SetPlayerName
メッセージ | CancelMessage
 | CancelPriority
 | CreateMessage
 | GetMessageCount
 | GetMessageQueue
 | Receive
 | Send
 | SendChatMessage
 | SendEx
グループ | AddGroupToGroup
 | AddPlayerToGroup
 | CreateGroup
 | CreateGroupInGroup
 | DeleteGroupFromGroup
 | DeletePlayerFromGroup
 | DestroyGroup
 | GetDPEnumGroupPlayers
 | GetDPEnumGroups
 | GetDPEnumGroupsInGroup
 | GetGroupData
 | GetGroupFlags
 | GetGroupLongName
 | GetGroupShortName
 | GetGroupOwner
 | GetGroupParent
 | SetGroupData
 | SetGroupName
 | SetGroupOwner


DirectPlay4.AddGroupToGroup

DirectPlay4.AddGroupToGroup メソッドは、グループへのショートカットを、既存のグループに追加する。これにより、リンクされたグループを、DirectPlay4.GetDPEnumGroupsInGroup メソッドで列挙できるようになる。グループのショートカットを別のグループから削除するには、DirectPlay4.DeleteGroupFromGroup を呼び出す。

object.AddGroupToGroup(ParentGroupId As Long, _
    GroupId As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
ParentGroupId
ショートカットの追加先のグループの ID。任意の有効なグループ ID を使用できる。
GroupId
追加するショートカットが示すグループの ID。任意の有効なグループ ID を使用できる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP

注意

このメソッドを使用すると、2 つ以上のグループ内にグループを配置することができる。

この変更をプレーヤーに通知するために、DPSYS_ADDGROUPTOGROUP システム メッセージが生成される。

参照

DirectPlay4.CreateGroupInGroup


DirectPlay4.AddPlayerToGroup

DirectPlay4.AddPlayerToGroup メソッドは、プレーヤーを既存のグループに追加する。プレーヤーは、複数のグループのメンバになることができる。アプリケーションは、任意のプレーヤーを任意のグループに追加することができる (ローカルに作成されていないプレーヤーおよびグループを含む)。このメソッドを使用して、グループをほかのグループに追加することはできない (「DirectPlay4.AddGroupToGroup」を参照)。

object.AddPlayerToGroup(GroupId As Long, _
    playerId As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
追加先のグループの ID。
playerId
グループに追加するプレーヤーの ID。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_NOSESSIONS

プレーヤーの DirectPlay ID がプレーヤー ID でない場合、またはその ID がローカル プレーヤーのものでない場合は、DPERR_INVALIDPLAYER を返す。

注意

DPSYS_ADDPLAYERTOGROUP システム メッセージが生成され、ほかのすべてのプレーヤーに送信される。

参照

DirectPlay4.CreateGroup、DirectPlay4.DeletePlayerFromGroup


DirectPlay4.CancelMessage

DirectPlay4.CancelMessage メソッドは、送信キュー内の特定のメッセージまたはすべてのメッセージをキャンセルする。CancelMessage は、非同期メッセージにのみ適用される。特定のメッセージをキャンセルするには、アプリケーションで DirectPlay4.SendEx メソッドによって返されるメッセージ ID を取得し、それを保存する必要がある。

既にメッセージ キューを離れていて、部分的に送信されるメッセージは、キャンセルすることができない。グループに送信されたメッセージは、グループの最低 1 人のメンバに送信された後では、キャンセルすることができない。

object.CancelMessage(msgid As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
msgid
キャンセルするメッセージの ID。この ID は、DirectPlay4.SendEx を使用してメッセージが送信されたときに返される。すべてのメッセージをキャンセルするには、0 を指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CANCELFAILED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNKNOWNMESSAGE
DPERR_UNSUPPORTED

参照

DirectPlay4.CancelPriority、DirectPlay4.Send


DirectPlay4.CancelPriority

DirectPlay4.CancelPriority メソッドは、送信キューに残っているメッセージのうち、特定の優先順位に該当するものや、特定の優先順位の範囲に該当するものをキャンセルする。CancelPriority は、非同期メッセージにのみ適用される。

既にメッセージ キューを離れていて、部分的に送信されるメッセージは、キャンセルすることができない。グループに送信されたメッセージは、グループの最低 1 人のメンバに送信された後では、キャンセルすることができない。

object.CancelPriority(minPriority As Long, _
    maxPriority As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
minPriority
キャンセルする優先順位の範囲の最小値。
maxPriority
キャンセルする優先順位の範囲の最大値 minPriority よりも大きくなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

参照

DirectPlay4.SendEx、DirectPlay4.Send、DirectPlay4.CancelMessage


DirectPlay4.Close

DirectPlay4.Close メソッドは、既に開かれているセッションを閉じる。ローカルに作成されたグループは、セッションのホストに所有されるように移行する。

object.Close()

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

注意

ローカルに作成されたプレーヤーはすべて破棄され、適切な DPSYS_DELETEPLAYERFROMGROUP および DPSYS_DESTROYPLAYERORGROUP システム メッセージがほかのすべてのセッション参加者に送信される。

参照

DirectPlay4.DestroyPlayer、DirectPlay4.Open


DirectPlay4.CreateGroup

DirectPlay4.CreateGroup メソッドは、現在のセッション内でグループを作成する。

object.CreateGroup(friendlyName As String, _
    formalName As String, _
    flags As CONST_DPGROUPFLAGS) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
friendlyName
作成されるグループを識別し、そのグループにアクセスするために使用するハンドル。このトークン識別子は、formalName とは異なるものでなければならない。
formalName
作成されるグループを識別し、そのグループにアクセスするために使用するハンドル。このトークン識別子は、friendlyName とは異なるものでなければならない。
flags
CONST_DPGROUPFLAGS 列挙型のフラグで、作成するグループのタイプを示す。DPGROUP_DEFAULT、DPGROUP_HIDDEN、または DPGROUP_STAGINGAREA のいずれかになる。

戻り値

グループ ID を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

注意

グループをクライアント/サーバー セッションで作成した場合、グループ通知メッセージは送信されない。グループは、コンピュータがクライアントであるか、ホストであるかに関係なく、そのグループを作成したコンピュータからしか認識することができない。

グループをピアツーピア セッションで作成した場合、CreateGroup は、ほかのすべてのプレーヤーに送信される DPSYS_CREATEPLAYERORGROUP システム メッセージを生成する。アプリケーションでは、DirectPlay4.Send メソッドを使用し、1 つのメッセージをグループ ID に送信することによって、メッセージをグループ内のすべてのプレーヤーに送信することができる。DirectPlay は、マルチキャストを使用してメッセージを送信するか (サービス プロバイダがマルチキャストをサポートする場合)、または個々のメッセージをグループ内の個々のプレーヤーに送信する。

アプリケーションに返されたグループ ID を使用して、メッセージを送信するグループや、関連するデータを識別する。DirectPlay によって割り当てられるプレーヤーとグループの ID は、セッション内では常に一意である。

CreateGroup によって作成したグループは、セッション内の最上位のグループである。これらのグループは、DirectPlay4.GetDPEnumGroups によって列挙される。一方、DirectPlay4.CreateGroupInGroup メソッドは、親グループのサブグループに相当するグループを作成する。

アプリケーションでは、一般的な整理目的でグループを使用することもできる。ロビー セッションでは、DirectPlay4.StartSession. を使用して新しいアプリケーション セッションを作成するためにプレーヤーを収集するメカニズムとして、ステージング領域が使用される。

グループを作成したプレーヤーは、そのグループのデフォルトの所有者になる。所有者だけが、名前やリモート データなどのグループのプロパティを変更したり、グループのメンバを変更したり、グループを削除したりすることができる。所有者がセッションを離れると、セッションのホストに所有権が渡される。

グループは、明示的に破棄されるまで、セッション内に存続する。

参照

DirectPlay4.AddGroupToGroup、DirectPlay4.DestroyGroup、DirectPlay4.GetDPEnumGroupPlayers、DirectPlay4.GetGroupFlags、DirectPlay4.SetGroupData、DirectPlay4.SetGroupName


DirectPlay4.CreateGroupInGroup

DirectPlay4.CreateGroupInGroup メソッドは、既存のグループ内にグループを作成する。ほかのグループ内に作成されたグループが列挙されるのは、DirectPlay4.GetDPEnumGroupsInGroup メソッドを使用した場合だけである。このようにして作成されたグループを破棄するには、DirectPlay4.DestroyGroup メソッドを呼び出す。

object.CreateGroupInGroup(parentid As Long,
  friendlyName As String,
  formalName As String,
  flags As CONST_DPGROUPFLAGS) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
parentid
グループの作成先となる、既存のグループの DirectPlay ID。
friendlyName
作成されたグループを識別し、それにアクセスするために使用するハンドル。このトークン識別子は、formalName とは異なるものでなければならない。
formalName
作成されたグループを識別し、それにアクセスするために使用するハンドル。このトークン識別子は、friendlyName とは異なるものでなければならない。
flags
CONST_FLAGS 列挙型のフラグで、作成するグループのタイプを示す。DPGROUP_LOCAL または DPGROUP_STAGINGAREA のいずれかになる。DPGROUP_LOCAL が設定されていない場合、グループはリモート グループである。

戻り値

作成されたグループの DirectPlay ID を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

グループを作成できなかった場合は、DPERR_CANTADDPLAYER を返す。親グループの ID が無効の場合は、DPERR_INVALIDGROUP を返す。

注意

グループをクライアント/サーバー セッションで作成した場合、グループ通知メッセージは送信されない。グループは、コンピュータがクライアントであるか、ホストであるかに関係なく、そのグループを作成したコンピュータからしか認識することができない。

グループをピアツーピア セッションで作成した場合、CreateGroupInGroup は、DPSYS_CREATEPLAYERORGROUP システム メッセージを生成して、この変更をほかのプレーヤーに通知する。

最上位グループを破棄すると、そのグループに含まれるメンバもすべて破棄され、適切な破棄メッセージが送信される。


DirectPlay4.CreateMessage

DirectPlay4.CreateMessage メソッドは、メッセージ オブジェクトを作成する。このオブジェクトは、データと組み合わせて送信することができる。

object.CreateMessage() As DirectPlayMessage

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectPlayMessage オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlay4.Send


DirectPlay4.CreatePlayer

DirectPlay4.CreatePlayer メソッドは、現在のセッションに対するローカル プレーヤーを作成する。

object.CreatePlayer(friendlyName As String, _
    formalName As String, _
    receiveEvent As Long, _
    flags As CONST_DPPLAYERFLAGS) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
friendlyName
作成されるプレーヤーを識別し、そのプレーヤーにアクセスするために使用するハンドル。このトークン識別子は、formalName とは異なるものでなければならない。
formalName
作成されるプレーヤーを識別し、そのプレーヤーにアクセスするために使用するハンドル。このトークン識別子は、friendlyName とは異なるものでなければならない。
receiveEvent
アプリケーションによって作成されるイベント。DirectPlay は、このプレーヤーに対して送信されたメッセージを受信したときに、このイベントを発生させる。
flags
プレーヤーのタイプを示すフラグ。デフォルト (flags = 0) は、観客ではなく、サーバー プレーヤーではないプレーヤーである。
DPPLAYER_SERVERPLAYER
プレーヤーは、クライアント/サーバー通信のサーバー プレーヤーである。サーバー プレーヤーを作成できるのは、ホストだけである。1 つのセッションに対するサーバー プレーヤーは、1 人だけである。このフラグが設定されている場合、CreatePlayer は常に DPID_SERVERPLAYER のプレーヤー ID を返す。
DPPLAYER_SPECTATOR
プレーヤーは観客として作成される。観客プレーヤーの動作は、アプリケーションによって完全に定義される。DirectPlay は、このフラグを単純に伝承する。

戻り値

成功すれば、一意のプレーヤー ID を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CANTADDPLAYER
DPERR_CANTCREATEPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION

注意

単一のプロセスで、複数のローカル プレーヤーを持つことができる。これらのプレーヤーは、DirectPlay オブジェクトを介して、同じコンピュータ上のほかのプレーヤーや、リモート コンピュータ上のプレーヤーと通信する。

このメソッドは、適切に終了すると、DPSYS_CREATEPLAYERORGROUP システム メッセージをセッション内のすべてのプレーヤーに送信し、新しいプレーヤーがセッションに参加したことを伝える。デフォルトでは、すべてのローカル プレーヤーが、すべてのシステム メッセージのコピーを受信する。

アプリケーションでは、返されたプレーヤー ID を使用し、メッセージの送信やデータの関連付けのためにプレーヤーを識別する必要がある。DirectPlay によって割り当てられるプレーヤーとグループの ID は、セッション内では常に一意である。

以下のことを実行できるのは、プレーヤーを作成したアプリケーションだけである。

  • プレーヤーの名前の変更
  • プレーヤーのリモート データの変更
  • プレーヤーからのメッセージの送信

アプリケーションがセッションを閉じると、作成されたローカル プレーヤーは、自動的に破棄される。セッションのホストまたはプレーヤーを作成したアプリケーションは、DirectPlay4.DestroyPlayer メソッドを使用して、いつでもプレーヤーを破棄することができる。

参照

DirectPlay4.GetDPEnumPlayers、DirectPlay4.GetPlayerFlags、DirectPlay4.Send、DirectPlay4.SetPlayerData、DirectPlay4.SetPlayerName、DirectX7.CreateEvent


DirectPlay4.CreateSessionData

DirectPlay4.CreateSessionData メソッドは、セッションに関する情報を設定および取得するために利用されるオブジェクトを作成する。

object.CreateSessionData() As DirectPlaySessionData

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectPlaySessionData オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlay4.DeleteGroupFromGroup

DirectPlay4.DeleteGroupFromGroup メソッドは、DirectPlay4.AddGroupToGroup メソッドによって追加されたショートカットを、グループから削除する。ショートカットを削除しても、グループは破棄されない。

object.DeleteGroupFromGroup(groupParentId As Long, _
    GroupId As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
groupParentId
削除するショートカットを含むグループの DirectPlay ID。
GroupId
削除するグループの DirectPlay ID。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP

注意

この変更をプレーヤーに通知するために、DPSYS_DELETEGROUPFROMGROUP システム メッセージが生成される。


DirectPlay4.DeletePlayerFromGroup

DirectPlay4.DeletePlayerFromGroup メソッドは、グループからプレーヤーを削除する。

object.DeletePlayerFromGroup(GroupId As Long, _
    playerId As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
プレーヤーを削除するグループの ID。
playerId
グループから削除するプレーヤーの ID。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

注意

この変更を通知するために、DPSYS_DELETEPLAYERFROMGROUP システム メッセージが生成される。

プレーヤーは、グループがほかのコンピュータによって作成されたものであっても、グループから任意のプレーヤーを削除することができる。

参照

DirectPlay4.AddPlayerToGroup


DirectPlay4.DestroyGroup

DirectPlay4.DestroyGroup メソッドは、セッションからグループを削除する。

object.DestroyGroup(GroupId As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
ゲームから削除されるグループの ID。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

グループは、削除する前に空である必要はない。削除するグループに属する個々のプレーヤーは、破棄されない。

このメソッドは、グループ内の各プレーヤーに対して、DPSYS_DELETEPLAYERFROMGROUP システム メッセージを生成し、さらに DPSYS_DESTROYPLAYERORGROUP システム メッセージを生成する。

グループがローカルに作成されたものでない場合でも、任意のアプリケーションで任意のグループを破棄することができる。

破棄するグループの ID は、現在のセッションが継続している間は、再利用されない。

参照

DirectPlay4.CreateGroup


DirectPlay4.DestroyPlayer

DirectPlay4.DestroyPlayer メソッドは、セッションからローカル プレーヤーを削除し、そのプレーヤーに対する保留中のメッセージを送信キューから削除し、そのプレーヤーが属するすべてのグループからそのプレーヤーを削除する。

一般に、プレーヤーを削除できるのは、そのプレーヤーを作成したアプリケーションだけである。しかし、セッションのホストも、プレーヤーを削除することができる。

object.DestroyPlayer(playerId As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
セッションから削除する、ローカルに保持されるプレーヤーの ID。セッションのホストが DestroyPlayer を呼び出す場合、この ID は、ローカルまたはリモートに関係なく、任意のプレーヤーの ID でよい。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

注意

このメソッドは、プレーヤーが属する各グループに対して DPSYS_DELETEPLAYERFROMGROUP システム メッセージを生成し、さらに DPSYS_DESTROYPLAYERORGROUP システム メッセージを生成する。

プレーヤーに対する非同期メッセージが送信キュー内で保留状態になっていると、そのプレーヤーを破棄することはできない。このメソッドは、削除するプレーヤーに対する保留中のメッセージを、

プレーヤー ID は、現在のセッションが継続している間は、再利用されない。

参照

DirectPlay4.CreatePlayer


DirectPlay4.GetCaps

DirectPlay4.GetCaps メソッドは、現在の DirectPlay 接続およびセッションの能力を取得する。

object.GetCaps(caps As DPCAPS, _
    flags As CONST_DPGETCAPSFLAGS)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
caps
DirectPlay オブジェクトの能力が設定される DPCAPS 型。
flags
CONST_DPGETCAPSFLAGS 列挙型のいずれかのメンバ。このパラメータを DPGETCAPS_DEFAULT (または 0) に設定すると、保証なしのメッセージングに対する能力が計算される。DPGETCAPS_GUARANTEED に設定すると、保証付きのメッセージ配信に対する能力が取得される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_UNINITIALIZED

注意

このメソッドを呼び出す前に、接続が初期化されていなければならない。開いたセッションが存在しない場合、DPCAPS の一部のメンバは、有効な値を返さない。

参照

DirectPlay4.GetPlayerCaps、DirectPlay4.InitializeConnection


DirectPlay4.GetDPEnumConnections

DirectPlay4.GetDPEnumConnections メソッドは、アプリケーションで利用可能な登録済みのサービス プロバイダおよびロビー プロバイダを列挙する。通常は、これらをユーザーに選択を促す形で提示し、選択された接続を DirectPlay4.InitializeConnection メソッドに渡す。

object.GetDPEnumConnections(guid As String, _
    flags As CONST_DPENUMCONNECTIONFLAGS) _
    As DirectPlayEnumConnections

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
guid
アプリケーションのグローバル ユニーク識別子 (GUID)。このアプリケーションで利用可能なサービス プロバイダとロビー プロバイダだけが返される。"" に設定すると、アプリケーションの GUID に関係なく、すべての接続が列挙される。
flags
列挙される接続のタイプを指定する CONST_DPENUMCONNECTIONFLAGS フラグ。デフォルト (flags = 0) では、DPCONNECTION_DIRECTPLAY と同じ結果が得られる。

戻り値

成功すれば、DirectPlayEnumConnections オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

注意

返されるサービス プロバイダとロビー プロバイダの順番は、以降の GetDPEnumConnections の呼び出しと同じになるとは限らない。

列挙された接続がすべて利用可能なわけではない。たとえば、このメソッドは、ユーザーがモデムをインストールしていない場合でも、モデム サービス プロバイダを返す。アプリケーションでは、それぞれの接続に対して DirectPlay4.InitializeConnection メソッドを呼び出し、エラー コードをチェックして、サービス プロバイダが利用可能かどうかを判断することができる。

サービス プロバイダの中には、自らをプライベートなものとして登録できるものがある。これらのサービス プロバイダは、このメソッドでは列挙されない。プライベートなサービス プロバイダを使用するには、それらを GUID によって明示的に参照する必要がある。それには、アプリケーションをロビーから起動するか、または DirectPlay アドレスを作成して、それを InitializeConnection に渡す。

参照

GUID の使用


DirectPlay4.GetDPEnumGroupPlayers

DirectPlay4.GetDPEnumGroupPlayers メソッドは、現在のオープン セッション内で特定のグループに属するプレーヤーを列挙する。

GetDPEnumGroupPlayers(GroupId As Long, _
    sessionGuid As String, _
    flags As CONST_DPENUMPLAYERFLAGS) _
    As DirectPlayEnumPlayers

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
列挙するプレーヤーが属するグループの DirectPlay ID。
sessionGuid
列挙するセッションを示すグローバル ユニーク識別子 (GUID)。DPENUMPLAYERS_SESSION フラグが設定されている場合を除き、このパラメータは無視される。この GUID は、DirectPlay4.GetDPEnumSessions メソッドにより列挙されるセッションのいずれかと同じでなければならない。
flags
列挙の方法を指定するフラグ。デフォルト (flags = 0) では、現在のアクティブなセッション内のグループのプレーヤーを列挙する。指定するフラグを組み合わせるには、論理 Or 演算を使用する。組み合わせられたフラグのすべての条件に一致するプレーヤーだけが、列挙される。たとえば、(DPENUMPLAYERS_LOCAL Or DPENUMPLAYERS_SPECTATOR) と指定すると、グループ内の、ローカルで、なおかつ観客であるプレーヤーだけが列挙される。(DPENUMPLAYERS_LOCAL Or DPENUMPLAYERS_REMOTE) と指定すると、ローカルで、なおかつリモートなプレーヤーは存在しないため、プレーヤーは列挙されない。

このフラグには、CONST_DPENUMPLAYERFLAGS 列挙型の以下の 1 つ以上の値を設定できる。

DPENUMPLAYERS_LOCAL
DPENUMPLAYERS_OWNER
DPENUMPLAYERS_REMOTE
DPENUMPLAYERS_SERVERPLAYER
DPENUMPLAYERS_SESSION
DPENUMPLAYERS_SPECTATOR

戻り値

成功すれば、DirectPlayEnumPlayers オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDGROUP
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

このメソッドは、セッションが、接続先ではないロビー セッションの場合は、DPERR_ACCESSDENIED を返す。sessionGuid またはフラグが無効な場合は、DPERR_INVALIDPARAMS を返す。アクティブなセッションが存在しない場合は、DPERR_NOSESSIONS を返す。セッションを列挙できなかった場合は、DPERR_UNAVAILABLE を返す。

注意

パスワードで保護されたリモート セッションは列挙されない。接続していないロビー セッションでこのメソッドを使用することはできない。

このメソッドは、デフォルトでは、現在のセッション内のすべてのプレーヤーを列挙する。セッションのホストが列挙用のリストを提供するように要求するには、DPENUMPLAYERS_SESSION フラグと、セッション インスタンスの GUID を使用する。DPENUMPLAYERS_SESSION フラグをこのメソッドで使用するのは、DirectPlay4.GetDPEnumSessions メソッドを呼び出した後で、なおかつ DirectPlay4.Close メソッドまたは DirectPlay4.Open メソッドを呼び出す前でなければならない。

参照

DirectPlay4.CreatePlayer、DirectPlay4.DestroyPlayer、DirectPlay4.AddPlayerToGroup、DirectPlay4.DeletePlayerFromGroup、GUID の使用


DirectPlay4.GetDPEnumGroups

DirectPlay4.GetDPEnumGroups メソッドは、現在のセッション内の最上位グループをすべて列挙する。最上位グループは、DirectPlay4.CreateGroup メソッドを使用して作成されたグループである。

object.GetDPEnumGroups(sessionGuid As String, _
    flags As CONST_DPENUMGROUPFLAGS) _
    As DirectPlayEnumPlayers

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
sessionGuid
列挙するセッションを識別するグローバル ユニーク識別子 (GUID)。現在開いているセッションのグループを列挙するには、このパラメータを "" に設定する。それ以外の場合、この GUID は、DirectPlay4.GetDPEnumSessions.によって列挙されるセッションのいずれかと等しくなければならない。
flags
列挙の方法を指定するフラグ。デフォルトでは (flags = 0)、現在のアクティブ セッション内のグループをすべて列挙する。組み合わせられたフラグのすべての条件に一致するグループだけが列挙される。たとえば、(DPENUMGROUPS_LOCAL Or DPENUMGROUPS_STAGINGAREA) と指定すると、ローカルで、なおかつステージング領域であるグループだけが列挙される。(DPENUMGROUPS_LOCAL Or DPENUMGROUPS_REMOTE) と指定すると、ローカルでなおかつリモートであるグループは存在しないので、グループは列挙されない。

このフラグには、CONST_DPENUMGROUPFLAGS 列挙型の以下のいずれかの値を設定できる。

DPENUMGROUPS_ALL
セッション内のすべてのグループを列挙する。
DPENUMGROUPS_LOCAL
この DirectPlay オブジェクトによってローカルに作成されたグループを列挙する。
DPENUMGROUPS_REMOTE
リモートの DirectPlay オブジェクトによって作成されたグループを列挙する。
DPENUMGROUPS_SESSION
sessionGuid パラメータによって指定されるセッション内で列挙を実行する。このフラグは、現在アクティブなセッションが存在しない場合にのみ使用できる。このフラグをロビー セッションで使用することはできない。
DPENUMGROUPS_STAGINGAREA
ステージング領域にあるグループを列挙する (ステージング領域は、新しいセッションを開始する際に、プレーヤーを配置するために利用される)。

戻り値

成功すれば、DirectPlayEnumPlayers オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

このメソッドは、提供された sessionGuid またはフラグが無効な場合は、DPERR_INVALIDPARAMS を返す。開いたセッションが存在しない場合は、DPERR_NOSESSIONS を返す。リモート セッションを列挙できなかった場合は、DPERR_UNAVAILABLE を返す。

注意

接続していないロビー セッションで、GetDPEnumGroups を使用することはできない。

開いたセッションが存在しない場合は、DPENUMGROUPS_SESSION フラグを指定し、セッションの sessionGuid を指定することにより、リモート セッションのグループを列挙することができる。パスワードで保護されたリモート セッションを列挙することはできない。

グループ内のサブグループを列挙するには、DirectPlay4.GetDPEnumGroupsInGroup を使用する。

参照

DirectPlay4.DestroyGroup、DirectPlay4.GetDPEnumSessions、GUID の使用


DirectPlay4.GetDPEnumGroupsInGroup

DirectPlay4.GetDPEnumGroupsInGroup メソッドは、別のグループに含まれているグループおよびグループへのショートカットをすべて列挙する。グループを DirectPlay4.CreateGroupInGroup メソッドによって作成するか、または DirectPlay4.AddGroupToGroup メソッドによって別のグループに追加すると、そのグループは別のグループの内部に配置される。このメソッドは再帰的ではない。

object.GetDPEnumGroupsInGroup(GroupId As Long, _
    sessionGuid As String, _
    flags As CONST_DPENUMGROUPFLAGS) _
    As DirectPlayEnumPlayers

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
列挙するサブグループが属するグループの ID。
sessionGuid
列挙するセッションのグローバル ユニーク識別子 (GUID)。DPENUMPLAYERS_SESSION フラグが設定されている場合を除き、このパラメータは無視される。この GUID は、DirectPlay4.GetDPEnumSessions メソッドによって列挙されるセッションのいずれかと等しくなければならない。
flags
列挙の方法を指定するフラグ。デフォルト (flags = 0) では、現在のアクティブなセッション内のグループをすべて列挙する。組み合わせられたフラグのすべての条件に一致するグループだけが、列挙される。たとえば、(DPENUMGROUPS_LOCAL Or DPENUMGROUPS_STAGINGAREA) と指定すると、ローカルで、なおかつステージング領域であるグループだけが列挙される。(DPENUMGROUPS_LOCAL Or DPENUMGROUPS_REMOTE) と指定すると、ローカルで、なおかつリモートなグループは存在しないため、グループは列挙されない。

このフラグには、CONST_DPENUMGROUPFLAGS 列挙型の以下の 1 つ以上の値を設定できる。

DPENUMGROUPS_ALL
グループ内のすべてのグループを列挙する。
DPENUMGROUPS_HIDDEN
グループ内の現在利用可能な隠れたグループのみを列挙する。
DPENUMGROUPS_LOCAL
この DirectPlay オブジェクトによってローカルに作成されたグループ内のグループのみを列挙する。
DPENUMGROUPS_REMOTE
リモートの DirectPlay オブジェクトによって作成されたグループ内のグループのみを列挙する。
DPENUMGROUPS_SESSION
sessionGuid パラメータによって指定されるセッション内で列挙を実行する。このフラグは、現在アクティブなセッションが存在しない場合にのみ使用できる。このフラグをロビー セッションで使用することはできない。
DPENUMGROUPS_SHORTCUT
DirectPlay4.AddGroupToGroup を使用してグループに追加されたショートカットであるグループを列挙する (ショートカットは、別のグループへのリンクである)。
DPENUMGROUPS_STAGINGAREA
ステージング領域であるグループ内のグループを列挙する (ステージング領域は、新しいセッションを開始する際に、プレーヤーを配置するために利用される)。

戻り値

成功すれば、DirectPlayEnumPlayers オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNSUPPORTED

このメソッドは、渡された sessionGuid が無効の場合は、DPERR_INVALIDPARAMS を返す。アクティブなセッションが存在しない場合は、DPERR_NOSESSIONS を返す。セッションを列挙できなかった場合は、DPERR_UNSUPPORTED を返す。

注意

このメソッドを、接続していないロビー セッションで使用することはできない。

参照

DirectPlay4.DeleteGroupFromGroup、DirectPlay4.DestroyGroup、GUID の使用


DirectPlay4.GetDPEnumPlayers

DirectPlay4.GetDPEnumPlayers メソッドは、現在開いているセッション内のプレーヤーを列挙し、オプションでグループも列挙する。開いたセッションが存在しない場合は、リモート セッション内のプレーヤーを列挙できる。

object.GetDPEnumPlayers(sessionGuid As String, _
    flags As CONST_DPENUMPLAYERFLAGS) _
    As DirectPlayEnumPlayers

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
sessionGuid
現在開いているセッションのプレーヤーを列挙する場合は、このパラメータを "" に設定する必要がある。開いたセッションが存在しない場合、このパラメータには、列挙するセッションの GUID を指定できる。この GUID は、DirectPlay4.GetDPEnumSessions によって設定されるセッションのいずれかに属していなければならない。DPENUMPLAYERS_SESSION フラグが設定されている場合を除き、このパラメータは無視される。
flags
列挙の方法を指定するフラグ。デフォルト (flags = 0) では、現在のアクティブなセッション内のプレーヤーをすべて列挙する。組み合わせられたフラグのすべての条件に一致するプレーヤーだけが、列挙される。たとえば、(DPENUMPLAYERS_LOCAL Or DPENUMPLAYERS_SPECTATOR) と指定すると、ローカルで、なおかつ観客であるプレーヤーだけが列挙される。(DPENUMPLAYERS_LOCAL Or DPENUMPLAYERS_REMOTE) と指定すると、ローカルで、なおかつリモートであるプレーヤーは存在しないので、プレーヤーは列挙されない。

このフラグには、CONST_DPENUMPLAYERFLAGS 列挙型の以下の 1 つ以上の値を設定できる。

DPENUMPLAYERS_ALL
DPENUMPLAYERS_GROUP
DPENUMPLAYERS_LOCAL
DPENUMPLAYERS_REMOTE
DPENUMPLAYERS_SERVERPLAYER
DPENUMPLAYERS_SESSION
DPENUMPLAYERS_SPECTATOR

戻り値

成功すれば、DirectPlayEnumPlayers オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

このメソッドは、渡された sessionGuid またはフラグが無効な場合は、DPERR_INVALIDPARAMS を返す。開いたセッションが存在しない場合は、DPERR_NOSESSIONS を返す。リモート セッションを列挙できなかった場合は、DPERR_UNAVAILABLE を返す。

このメソッドは、ロビー セッション内では、常に DPERR_ACCESSDENIED を返す。

注意

このメソッドは、デフォルトでは、現在開いているセッション内のプレーヤーを列挙する。DPENUMPLAYERS_GROUP フラグを使用すると、グループを列挙に含めることができる。セッションのホストが列挙用にリストを提供するように要求するには、DPENUMPLAYERS_SESSION フラグと、セッション インスタンスの GUID を使用する。このメソッドは、DirectPlay4.GetDPEnumSessions の列挙から呼び出すことはできない。さらに、DPENUMPLAYERS_SESSION フラグをこのメソッドで使用するのは、GetDPEnumSessions メソッドを呼び出した後で、なおかつ DirectPlay4.Close メソッドまたは DirectPlay4.Open メソッドを呼び出す前でなければならない。

参照

DirectPlay4.CreatePlayer、DirectPlay4.DestroyPlayer、GUID の使用


DirectPlay4.GetDPEnumSessions

DirectPlay4.GetDPEnumSessions メソッドは、特定のアプリケーションに対するアクティブ セッションと、特定のアプリケーションに対してサービスを提供するアクティブ ロビー セッションのいずれかまたは両方をすべて列挙する。このメソッドは、DirectPlay4.InitializeConnection によって接続が作成され、初期化された後に呼び出すことができる。

このメソッドは、セッションが既に開いているときに呼び出されると、エラーを返す。

object.GetDPEnumSessions( _
    sessionDesc As DirectPlaySessionData, _
    timeOut As Long, _
    flags As CONST_DPENUMSESSIONFLAGS) _
    As DirectPlayEnumSessions

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
sessionDesc
列挙されるセッションの記述を表す DirectPlaySessionData オブジェクト。このオブジェクトを取得するには、DirectPlay4.CreateSessionData メソッドを使用する。GuidApplication メンバには、対象となるアプリケーションがわかっている場合にはそのグローバル ユニーク識別子 (GUID)、すべてのセッションを取得する場合には "" を設定できる。SessionPassword メンバは、プライベート セッションを列挙する場合にのみ必要である。ほかのデータ メンバは、すべて無視される。
timeOut
同期を取る場合は、DirectPlay が列挙要求の応答を待機する時間 (各列挙間の時間ではない) をミリ秒で指定する。ここに指定した時間が経過した後に受信された応答は、すべて無視される。このタイムアウト時間が経過するまで、アプリケーションはブロックする。

非同期の場合は、内部セッション リストを更新するために DirectPlay が列挙要求をブロードキャストする間隔をミリ秒単位で指定する。

このタイムアウトを 0 に設定すると、サービス プロバイダと接続のタイプに適したデフォルトのタイムアウトが使用される。この値は、0 に設定するように推奨されている。アプリケーションでは、DirectPlay4.GetCaps を呼び出し、DPCAPS 型の lTimeout メンバを調べて、このタイムアウトを判断することができる。

flags
CONST_DPENUMSESSIONFLAGS 列挙型の 0 個以上のフラグ。デフォルトは 0 であり、これは DPENUMSESSIONS_AVAILABLE に等しい。DPENUMSESSIONS_ALL または DPENUMSESSIONS_PASSWORDREQUIRED でセッションを列挙するときは、どのセッションが参加不可能で、どのセッションがパスワードで保護されているかをアプリケーションで把握し、ユーザーに警告したり、パスワードを要求できるようにすることが重要である。

戻り値

成功すれば、DirectPlayEnumSessions オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION
DPERR_UNINITIALIZED
DPERR_USERCANCEL

このメソッドは、セッションが既に開いている場合は、DPERR_GENERIC を返す。DirectPlay オブジェクトがまだ初期化されていない場合は、DPERR_UNINITIALIZED を返す。ユーザーが列挙処理をキャンセルした場合 (通常は、サービス プロバイダのダイアログ ボックスをキャンセルすることにより、列挙処理がキャンセルされる) は、DPERR_USERCANCEL を返す。ネットワークへの接続処理で使用されている場合は、DPERR_CONNECTING を返す。

注意

このメソッドは、1 つ以上のホストをネットワーク上で見つけ、それらに列挙要求を送信するようにサービス プロバイダに要求することによって機能する。受信された応答が、列挙されたセッションを形成する。

このメソッドは、同期的 (デフォルト) または非同期的に呼び出すことができる。同期的に呼び出すと、DirectPlay が内部のセッション キャッシュを消去し、列挙要求を送信して、指定されたタイムアウトが経過するまで応答を収集する。すると、各セッションがアプリケーションに返される。アプリケーションは、すべてのセッションが返されるまでブロックする。

非同期的に呼び出すと (DPENUMSESSIONS_ASYNC)、セッション キャッシュ内のすべてのカレント セッション (存在する場合) がアプリケーションに返され、その後でメソッドが戻る。その後、DirectPlay はタイムアウト パラメータに設定された間隔で列挙要求を自動的に送信し、応答を待機する。各応答は、セッション キャッシュを更新するために利用される。

  • キャッシュ内に既に存在するセッションが更新される。
  • 設定された時間内に更新されていない (したがって、失効した) セッションが削除される。
  • 新しいセッションが追加される。

アプリケーションでは、DPENUMSESSIONS_ASYNC フラグを設定して GetDPEnumSessions をもう一度呼び出し、失効したセッションが削除され、新しいセッションが追加され、セッションが更新された最新のセッション リストを取得する必要がある。以降に GetDPEnumSessions を呼び出すと、列挙要求は生成されない。列挙要求は、プロセスが DPENUMSESSIONS_STOPASYNC を設定した GetDPEnumSessions の呼び出しによってキャンセルされるか、DirectPlay4.Open メソッドによってセッションが開かれるか、または DirectPlay オブジェクトが解放されるまで、DirectPlay によって定期的に生成される。

非同期的に列挙されているセッションの記述を変更するには、非同期の列挙を中止して、再度開始する必要がある。たとえば、パスワードなしでセッションを開始し、後で非同期呼び出しのときにパスワードを追加して、そのパスワードを使用してプライベート セッションの列挙を開始させることはできない。逆に、正しいパスワードを設定し、それを間違ったパスワードに変更しても、依然としてセッションを列挙することができる。しかし、DPENUMSESSIONS_STOPASYNC フラグを設定して GetDPEnumSessions を呼び出してからパスワードを設定すると、プライベート セッションが列挙される。

利用可能なセッションの列挙が完了したら、アプリケーションでは DirectPlay4.Open メソッドを使用して、いずれかのセッションに参加することができる。開くことができるのは、セッション キャッシュ内のセッションだけである。アプリケーションでは、GetDPEnumSessions が最後に呼び出されてから失効したセッションを開くことを試みることができる。この場合、エラーが返される。

保証サーバー上でセッションを列挙するときは、認証は実行されない。列挙の条件に合うセッションがすべて返される。認証は、アプリケーションがそれらのセッションのいずれかを Open または DirectPlay4.SecureOpen メソッドで開こうとしたときに実行される。

アプリケーションがロビーによって起動されていない場合、サービス プロバイダはダイアログ ボックスを表示し、ネットワーク上で列挙を実行するための情報のうち、DirectPlay4.InitializeConnection で提供されていないもの (電話番号、IP アドレスなど) をユーザーに要求することができる。サービス プロバイダがブロードキャスト列挙を実行でき、ユーザーに追加情報を要求しない場合、ダイアログ ボックスは表示されない。


DirectPlay4.GetGroupData

DirectPlay4.GetGroupData メソッドは、グループに関連付けられた、アプリケーションに固有の文字列を取得する。

object.GetGroupData(GroupId As Long, _
    flags As CONST_DPGETFLAGS) As String

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
データを要求するグループの ID。
flags
CONST_DPGETFLAGS 列挙型の値で、取得するグループ データのタイプ (ローカルまたはリモート) を示す。このパラメータを 0 に設定すると、リモート データが取得される。

戻り値

成功すれば、DirectPlay4.SetGroupData メソッドによってグループに関連付けられたデータを含む文字列を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

DirectPlay は、ローカルまたはリモートのいずれかのタイプのグループ データを維持することができる。アプリケーションでは、どちらのタイプのデータを取得するのか指定する必要がある。ローカル データは、この DirectPlay オブジェクトにより、DPSET_LOCAL フラグを使用して設定されている。リモート データは、セッション内の任意のアプリケーションにより、DPSET_REMOTE フラグを使用して設定されている。


DirectPlay4.GetGroupFlags

DirectPlay4.GetGroupFlags メソッドは、指定されたグループを記述するフラグを取得する。

object.GetGroupFlags(GroupId As Long) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
フラグ設定を取得するグループの ID。

戻り値

成功すれば、グループ フラグの設定に設定された値を返す。この値は、CONST_DPGROUPFLAGS 列挙型の以下のメンバのいずれかまたは両方になる。

DPGROUP_LOCAL
グループは、このアプリケーションによって作成された。このフラグが指定されていない場合、グループはリモート グループである。
DPGROUP_STAGINGAREA
グループはステージング領域である。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS.

参照

DirectPlay4.CreateGroup


DirectPlay4.GetGroupLongName

DirectPlay4.GetGroupLongName メソッドは、グループに関連付けられたロング ネームを取得する。

object.GetGroupLongName(GroupId As Long) As String

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
名前を要求するグループの ID。

戻り値

このメソッドは、グループのロング ネームを返す。この名前は、DirectPlay4.CreateGroup、DirectPlay4.CreateGroupInGroup、または DirectPlay4.SetGroupName メソッドの formalName パラメータとして渡される値に等しい。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlay4.GetGroupOwner

DirectPlay4.GetGroupOwner メソッドは、グループの現在の所有者の ID を取得する。このメソッドは、ロビー セッションでのみ有効である。

object.GetGroupOwner(GroupId As Long) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
所有者を要求するグループの ID。

戻り値

グループの所有者の DirectPlay ID を返す。所有者は、DirectPlay4.SetGroupOwner メソッドにより設定されている。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlay4.GetGroupParent

DirectPlay4.GetGroupParent メソッドは、グループを含んでいるグループの ID を取得する。

object.GetGroupParent(GroupId As Long) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
親を要求するグループの ID。

戻り値

DirectPlay4.CreateGroupInGroup により、グループがほかのグループ内で作成されている場合は、親の DirectPlay ID を返す。グループが別のグループ内で作成されていない場合は、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlay4.CreateGroupInGroup


DirectPlay4.GetGroupShortName

DirectPlay4.GetGroupShortName メソッドは、グループに関連付けられているショート ネームを取得する。

object.GetGroupShortName(GroupId As Long) As String

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
名前を要求するグループの ID。

戻り値

グループのショート ネームを返す。この名前は、DirectPlay4.CreateGroup、DirectPlay4.CreateGroupInGroup、または DirectPlay4.SetGroupName メソッドの friendlyName パラメータとして渡される値に等しい。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlay4.GetMessageCount

DirectPlay4.GetMessageCount メソッドは、指定されたローカル プレーヤーの受信キュー内にあるメッセージの数を取得する。

object.GetMessageCount(playerId As Long) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
メッセージ数を要求するプレーヤーの ID。このプレーヤーはローカルでなければならない。

戻り値

メッセージの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlay4.Receive


DirectPlay4.GetMessageQueue

DirectPlay4.GetMessageQueue メソッドは、ローカル プレーヤーに対する送信または受信キューに関する情報を取得する。1 台のマシン上で 1 つのセッション内に 2 人以上のプレーヤーが存在する場合、返されるデータは、それらのプレーヤーすべての組み合わせに対して有効である。

object.GetMessageQueue(from As Long, _
    to As Long, _
    flags As CONST_DPMESSAGEQUEUEFLAGS, _
    nMessage As Long, _
    nBytes As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
from
キュー状態の取得対象となる、メッセージを送信しているプレーヤーの ID。0 を指定すると、送信されたすべてのメッセージに関する情報が返される。to も指定した場合は、from に指定されたプレーヤーからのメッセージと、to に指定されたメッセージに対するメッセージだけが返される。
to
キュー状態の取得対象となる、メッセージが送信されたプレーヤーの ID。0 を指定すると、送信されたすべてのメッセージに関する情報が返される。from も指定した場合は、from に指定されたプレーヤーからのメッセージと、to に指定されたメッセージに対するメッセージだけが返される。グループ ID を to に指定することはできない。
flags
キューに関して取得する情報のタイプを指定するフラグ。デフォルト (flags = 0) では、送信キューに関する情報を返す。このフラグには、以下のいずれかの値のみを設定できる。
DPMESSAGEQUEUE_SEND
送信キューに関する情報を取得する。
DPMESSAGEQUEUE_RECEIVE
受信キューに関する情報を取得する。
nMessage
キュー内のメッセージの数を受け取る変数。
nBytes
キュー内のすべてのメッセージのバイト数を受け取る変数。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_UNSUPPORTED

このメソッドは、to にリモート プレーヤーを指定して受信キュー (DPMESSAGEQUEUE_RECEIVE) をチェックすると、DPERR_INVALIDPLAYER を返す。from にリモート プレーヤーを指定して送信キュー (DPMESSAGEQUEUE_SEND) をチェックすると、DPERR_INVALIDPLAYER を返す。flags が DPMESSAGEQUEUE_RECEIVE Or DPMESSAGEQUEUE_SEND の場合は、DPERR_INVALIDFLAGS を返す。DirectPlay プロトコルがオンになっておらず、サービス プロバイダが送信キューのチェックをサポートしていない場合に送信キューをチェックしようとすると、DPERR_UNSUPPORTED を返す。

注意

アプリケーションでは、送信キュー状態を監視することにより、基盤となるネットワークの帯域幅に基づいて、セッション内のほかのプレーヤーに送信するメッセージの数を調節することができる。


DirectPlay4.GetPlayerAccountId

DirectPlay4.GetPlayerAccountId メソッドは、保証セッションでセッションのホストによって呼び出された場合に、指定されたプレーヤーのアカウント識別子を取得する。

object.GetPlayerAccountId(playerId As Long) As String

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
アカウント情報を取得するプレーヤーの ID。

戻り値

このメソッドは、安全な方法でログオンしているプレーヤーを記述する一意の識別子を返す。識別子の形式は、使用している Security Support Provider Interface (SSPI) パッケージによって異なる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドによって返される情報は、アカウントを一意に識別する。この情報を使用して、ログオンしているプレーヤーのトランザクションやほかの動作を記録することができる。

参照

DirectPlay4.SecureOpen


DirectPlay4.GetPlayerAddress

DirectPlay4.GetPlayerAddress メソッドは、プレーヤーのDirectPlay アドレスを取得する。

ローカル プレーヤーに対して呼び出された場合は、そのコンピュータのネットワーク アドレス (利用可能な場合) を返す。場合によっては、2 つ以上のアドレスが返される場合がある (たとえば、TCP/IP で、コンピュータがネットワーク カードとダイヤルアップ インターネット接続の両方を備えている場合など)。

object.GetPlayerAddress(playerId As Long) _
    As DirectPlayAddress

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
アドレスを要求するプレーヤーの ID。0 を渡すと、サービス プロバイダに対して有効なアドレス オプションのリストが返される。

戻り値

成功すれば、DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、要求されたプレーヤー ID が利用できない場合は、Err.Number に DPERR_UNAVAILABLE が設定される。


DirectPlay4.GetPlayerCaps

DirectPlay4.GetPlayerCaps メソッドは、指定されたプレーヤーの現在の能力を取得する。

object.GetPlayerCaps(playerId As Long, _
    caps As DPCAPS, _
    flags As CONST_DPGETCAPSFLAGS)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
能力を取得するプレーヤーの ID。
caps
能力が設定される DPCAPS 型。
flags
能力の計算方法を示す値。0 を設定すると、保証なしのメッセージングに対する能力が計算される。DPGETCAPS_GUARANTEED を設定すると、保証メッセージングに対する能力が取得される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

参照

DirectPlay4.GetCaps、DirectPlay4.Send


DirectPlay4.GetPlayerData

DirectPlay4.GetPlayerData メソッドは、DirectPlay4.SetPlayerData によってプレーヤー ID に関連付けられた、アプリケーション固有のデータ ブロックを所得する。

object.GetPlayerData(playerId As Long, _
    flags As CONST_DPGETFLAGS) As String

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
データを要求するプレーヤーの ID。
flags
取得するプレーヤー データのタイプ (ローカルまたはリモート) を示す、CONST_DPGETFLAGS 列挙型の値。このパラメータに 0 を設定すると、リモート データが取得される。

戻り値

アプリケーション定義のデータを含む文字列を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

注意

ローカル データは、現在の DirectPlay オブジェクトにより、DirectPlay4.SetPlayerData で DPSET_LOCAL フラグを使用して設定されている。リモート データは、セッション内の任意のアプリケーションにより、DPSET_REMOTE フラグを使用して設定された可能性がある。


DirectPlay4.GetPlayerFlags

DirectPlay4.GetPlayerFlags メソッドは、プレーヤーが作成されたときに、そのプレーヤーを記述するために使用されたフラグを取得する。

object.GetPlayerFlags(id As Long) As CONST_DPPLAYERFLAGS

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
id
フラグ設定を取得するプレーヤーの ID。

戻り値

プレーヤーのフラグ設定を返す。戻り値には、以下の 1 つ以上の値が含まれる。

DPPLAYER_LOCAL
プレーヤーは、このアプリケーションによって作成された。このフラグが指定されていない場合、プレーヤーはリモート プレーヤーである。
DPPLAYER_SERVERPLAYER
プレーヤーは、クライアント/サーバー通信のサーバー プレーヤーである。
DPPLAYER_SPECTATOR
プレーヤーは、観客として作成された。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlay4.CreatePlayer


DirectPlay4.GetPlayerFormalName

DirectPlay4.GetPlayerFormalName メソッドは、プレーヤーに関連付けられている正式名を取得する。

object.GetPlayerFormalName(playerId As Long) As String

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
名前を要求するプレーヤーの ID。

戻り値

成功すれば、プレーヤーの正式名を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

参照

DirectPlay4.CreatePlayer、DirectPlay4.GetPlayerFriendlyName、DirectPlay4.SetPlayerName


DirectPlay4.GetPlayerFriendlyName

DirectPlay4.GetPlayerFriendlyName メソッドは、プレーヤーに関連付けられているフレンドリ名を取得する。

object.GetPlayerFriendlyName(playerId As Long) As String

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
名前を要求するプレーヤーの ID。

戻り値

成功すれば、プレーヤーのフレンドリ名を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

参照

DirectPlay4.CreatePlayer、DirectPlay4.GetPlayerFormalName、DirectPlay4.SetPlayerName


DirectPlay4.GetSessionDesc

DirectPlay4.GetSessionDesc メソッドは、現在開いているセッションのプロパティを取得する。

object.GetSessionDesc(sessionDesc As DirectPlaySessionData)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
sessionDesc
セッションに関する情報を受け取る DirectPlaySessionData オブジェクト。このオブジェクトは、DirectPlay4.CreateSessionData メソッドを使用して取得される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION


DirectPlay4.InitializeConnection

DirectPlay4.InitializeConnection メソッドは、DirectPlay 接続を初期化する。使用するサービス プロバイダ、サーバーのネットワーク アドレス、セッションの GUID など、接続に関するすべての情報は、addr パラメータを介して渡される。

object.InitializeConnection(addr As DirectPlayAddress)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
addr
初期化する接続に関するすべての情報へのアクセスを提供する DirectPlayAddress オブジェクト。「注意」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ALREADYINITIALIZED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

このメソッドは、このオブジェクトに対して、InitializeConnection が既に呼び出されている場合は、DPERR_ALREADYINITIALIZED を返す。サービス プロバイダを初期化できなかった場合は、DPERR_UNAVAILABLE を返す。この状態は、当該のサービス プロバイダを利用するための必要なリソースが存在しない場合 (たとえば、TCP/IP スタックが存在しない場合など) に発生する可能性がある。

注意

このメソッドに渡される addr パラメータは、DirectPlay4.GetDPEnumConnections メソッドから取得することができる。または、DirectPlayLobby3 のアドレス作成メソッドのいずれかを使用して、このパラメータを直接作成することもできる。

このメソッドは、適切なサービス プロバイダをロードして、初期化する。addr パラメータは、サービス プロバイダに渡される。サービス プロバイダは、関連する情報を取り出して保存する。この情報は、DirectPlay4.GetDPEnumSessions メソッドまたは DirectPlay4.Open メソッドを呼び出すときに使用される。これにより、サービス プロバイダが同じ情報を要求するダイアログ ボックスを表示しないようにする。

参照

DirectPlayAddress


DirectPlay4.Open

DirectPlay4.Open メソッドは、DirectPlay4.GetDPEnumSessions メソッドを呼び出して列挙されたセッションに参加するとき、またはユーザーが列挙および参加可能な新しいセッションを作成するときに使用する。

object.Open(sessionDesc As DirectPlaySessionData, _
    flags As CONST_DPOPENFLAGS)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
sessionDesc
セッションを記述する DirectPlaySessionData オブジェクト。このオブジェクトは、DirectPlay4.CreateSessionData メソッドを使用して取得される。

セッションを作成する場合は、作成するセッションのプロパティ (DirectPlay によって提供される GuidInstance を除く) を使用して、DirectPlaySessionData オブジェクトを完全に初期化する必要がある。

flags
CONST_DPOPENFLAGS 列挙型のフラグ。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTCREATEPLAYER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_NOSESSIONS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

このメソッドは、この DirectPlay オブジェクト上に既に開いたセッションが存在する場合は、DPERR_ALREADYINITIALIZED を返す。

セッション記述の最大プレーヤー数に既に達している場合は、DPERR_CANTCREATEPLAYER を返す。

セッションが Open 要求に応答しなかった場合は、DPERR_TIMEOUT を返す。

ユーザーが列挙処理をキャンセルした場合 (通常は、サービス プロバイダのダイアログ ボックスをキャンセルすることにより、列挙処理をキャンセルする) は、DPERR_USERCANCEL を返す。

記述に一致するオープン セッションが存在しない場合、セッションが内部セッション リストに存在しない場合、またはセッション GUID が不正な場合は、DPERR_NOSESSIONS を返す。

注意

アプリケーションがセッションに参加すると、プレーヤーを作成し、セッション内のほかのプレーヤーとの通信を開始することができる。アプリケーションは、DirectPlay4.CreatePlayer を使用してローカル プレーヤーを作成するまでは、この DirectPlay オブジェクト上でメッセージを受信することも、メッセージを送信することもできない。

2 つのセッションを同時に開いておくには、2 つの DirectPlay オブジェクトを作成し、それぞれでセッションを開く必要がある。

セッションをパスワードで保護する場合は、DirectPlaySessionData.SetSessionPassword を呼び出す必要がある。セッションを列挙すると、パスワードを要求するセッションには、DPSESSION_PASSWORDREQUIRED フラグが設定される。

保証セッションに参加する場合は、DirectPlay4.SecureOpen を使用して、ログオン用の信用情報を提供する必要がある。セッションを列挙すると、信用情報を要求するセッションには、DPSESSION_SECURESERVER フラグが設定される。

DPSESSION_SECURESERVER フラグを設定すると、セッションはデフォルトのセキュリティ パッケージである NTLM を使用して開かれる。別のセキュリティ パッケージを指定するには、SecureOpen を使用する。

アプリケーションがセッションに参加しようとするとき、サーバーは Open 要求を拒否するか、または無視する (この場合、Open はタイムアウトになる) ことができる。新しいプレーヤーが無効になっていたり、参加が無効になっていたり、プレーヤーの限度に達していたり、間違ったパスワードが提供されていたりするセッションに参加しようとすると、DPERR_NONEWPLAYERS エラーまたは DPERR_INVALIDPASSWORD エラーが返される。

参照

DirectPlay4.Close


DirectPlay4.Receive

DirectPlay4.Receive メソッドは、メッセージ キューからメッセージを取り出す。

object.Receive(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPRECEIVEFLAGS) As DirectPlayMessage

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
fromPlayerId
このメソッドが戻ったときに、送信側のプレーヤーの ID が設定される変数。DPRECEIVE_FROMPLAYER フラグを指定した場合、このメソッドを呼び出す前に、プレーヤー ID を使用してこのパラメータを初期化する必要がある。
toPlayerId
このメソッドが戻ったときに、受信側のプレーヤーの ID が設定される変数。DPRECEIVE_TOPLAYER フラグを指定した場合、このメソッドを呼び出す前に、プレーヤー ID を使用してこのパラメータを初期化する必要がある。
flags
CONST_DPRECEIVEFLAGS 列挙型のフラグで、メッセージの取得方法を示す。以下の 1 つ以上の制御フラグを設定できる。デフォルト (flags = 0) では、利用可能な最初のメッセージが取得される。
DPRECEIVE_ALL
利用可能な最初のメッセージを返し、そのメッセージをメッセージ キューから削除する。これがデフォルトである。
DPRECEIVE_PEEK
ほかのフラグによって指定されたメッセージを返すが、そのメッセージをメッセージ キューから削除しない。
DPRECEIVE_TOPLAYER および DPRECEIVE_FROMPLAYER
DPRECEIVE_TOPLAYER と DPRECEIVE_FROMPLAYER の両方を指定した場合、Receive により、(1) toPlayerId によって指定されるプレーヤーに送信されたメッセージと、(2) fromPlayerId によって指定されるプレーヤーから送信されたメッセージのみが返される。両方の条件を満たしていなければならない。

IDPRECEIVE_TOPLAYER だけを指定した場合、Receive は、toPlayerId で指定されるプレーヤーに送信されたメッセージだけを返す。

DPRECEIVE_FROMPLAYER だけを指定した場合、Receive は、fromPlayerId によって指定されるプレーヤーから送信されたメッセージだけを返す。

DPRECEIVE_TOPLAYER と DPRECEIVE_FROMPLAYER のどちらも設定していない場合、Receive は利用可能な最初のメッセージを返す。

戻り値

成功すれば、メッセージの中身を取得するために使用するメソッドを持つ DirectPlayMessage オブジェクトを返す。保留中のメッセージが存在しない場合は、Nothing を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

DPID_ALLPLAYERS と定義されるプレーヤー ID に送信されたメッセージ、またはグループ ID に送信されたメッセージも、送信側のプレーヤー ID から送信されたように認識される。アプリケーションは、ローカル プレーヤーに送信されたメッセージだけを受信する。プレーヤーは、fromPlayerId で示される値と、toPlayerId で示される値が等しいメッセージを受信することはできない。

DPSESSION_NOMESSAGEID がセッション記述で指定されている場合、fromPlayerId は常に 0xFFFFFFFF になり、toPlayerId の値は任意になる。

DirectPlay に付属しているすべてのサービス プロバイダは、破壊を防ぐために、データに対して整合性チェックを実行する。Receive を使用して取得したメッセージは、すべて破壊から保護される。

参照

DirectPlay4.Send


DirectPlay4.SecureOpen

DirectPlay4.SecureOpen メソッドは、保証セッションを作成するか、または参加する。保証セッションに参加するには、このメソッドを使用して、ログオン用の認証情報を渡す。

新しいセッションを作成する場合、ホスト コンピュータは、使用する別のセキュリティ パッケージを指定することができる。セッションに参加する場合、コンピュータは、ユーザー名とパスワードを指定することができる。

object.SecureOpen(sessionDesc DirectPlaySessionData, _
    flags As CONST_DPOPENFLAGS, _
    security As DPSECURITYDESC,
    credentials As DPCREDENTIALS))

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
sessionDesc
作成または参加するセッションを記述するDirectPlaySessionData オブジェクト。セッションに参加する場合は、SetGuidInstance メソッドと SetSessionPassword メソッドだけを呼び出して、オブジェクトを初期化すればよい。パスワードを渡す必要があるのは、列挙されたセッションに DPSESSION_PASSWORDREQUIRED フラグが設定されている場合だけである。

セッションを作成する場合は、作成するセッションのプロパティ (ただし、DirectPlay が提供する、インスタンスの GUID を除く) を使用して、DirectPlaySessionData オブジェクトを完全に初期化する必要がある。

セッションを開くすべてのコンピュータを認証する必要があることを示すために、DPSESSION_SECURESERVER フラグを設定する。DPSESSION_SECURESERVER フラグを設定しない場合、SecureOpen は、DirectPlay4.Open を呼び出したときと同じように、非保証セッションを開く。

flags
CONST_DPOPENFLAGS 列挙型のフラグ。
security
使用するセキュリティ パッケージを含む DPSECURITYDESC 型。デフォルトのセキュリティ パッケージ (NTLM) と CryptoAPI パッケージ (Microsoft RSA Base Cryptographic Provider) を使用する場合は、この型のすべてのメンバを 0 に初期化する。このメンバは、セッションを作成する場合にのみ関係がある。セッションに参加する場合は、初期化されていない構造体を渡してもよい。
credentials
ログオン名、パスワード、およびサーバー上で認証するドメインを含む DPCREDENTIALS 型。信用情報が存在しない場合は、この型のメンバを 0 に初期化する。セッションを作成するときには、信用情報は無視される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

無効な信用情報を使用して呼び出された場合、または信用情報が必要な場合に信用情報なしで呼び出された場合は、DPERR_LOGONDENIED を返す。アプリケーションでは、ユーザーの信用情報を収集して、SecureOpen を再度呼び出す必要がある。

注意

セッションに参加する場合は、まず信用情報を使用せずに SecureOpen を呼び出す。DPERR_LOGONDENIED が返されたら、ユーザーからユーザー名とパスワードを取得して SecureOpen を再度呼び出し、credentials パラメータを介してユーザーに信用情報を渡す必要がある。DP_OK が返されたら、プレーヤーは、システムへのログオン時 (NTLMでは、ネットワーク ログオン) に指定した信用情報を使用して、ログオンできたことになる。


DirectPlay4.Send

DirectPlay4.Send メソッドは、別のプレーヤー、プレーヤーのグループ、またはセッション内のすべてのプレーヤーにメッセージを送信する。

メッセージは、メッセージごとに保証付きまたは保証なしのプロトコルを使用して送信することができる。セッションが保証サーバーによってホストされている場合は、メッセージごとに暗号化 (プライバシを保証するため) またはデジタル署名 (身元を保証するため) を施して、メッセージを送信することができる。

object.Send(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    msg As DirectPlayMessage)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
fromPlayerId
送信側プレーヤーの ID。このプレーヤー ID は、コンピュータ上のローカル プレーヤーのいずれかに一致していなければならない。
toPlayerId
メッセージの送信先 ID。メッセージをほかのプレーヤーに送信するには、送信先のプレーヤーの ID を指定する。メッセージをグループ内のすべてのプレーヤーに送信するには、そのグループの ID を指定する。メッセージをセッション内のすべてのプレーヤーに送信するには、定数 DPID_ALLPLAYERS を使用する。メッセージをサーバー プレーヤーに送信するには、定数 DPID_SERVERPLAYER を使用する。プレーヤーは、自らにメッセージを送信することはできない。
flags
メッセージの送信方法を指定する値。デフォルト (flags = 0) では、メッセージは保証なしで送信される。
DPSEND_ENCRYPTED
メッセージを暗号化して送信する。これができるのは、保証セッションの場合だけである。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合に限り、使用できる。メッセージは、DPSYS_SECUREMESSAGE システム メッセージとして送信される。
DPSEND_GUARANTEED
保証された配信方法を使用して、メッセージを送信する。
DPSEND_SIGNED
デジタル署名を加えて、メッセージを送信する。これができるのは、保証セッションの場合だけである。このフラグは、DPSEND_SIGNED フラグも設定されている場合に限り、使用できる。メッセージは、DPSYS_SECUREMESSAGE システム メッセージとして送信される。
msg
送信されるデータを表す DirectPlayMessage オブジェクト。このオブジェクトは、DirectPlay4.CreateMessage メソッドを使用して取得される。また、このオブジェクト自体のメソッドを使用して、オブジェクトにデータを代入することができる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG

保証付きと指定されていないメッセージに暗号化または署名のフラグが設定されている場合は、DPERR_INVALIDPARAMS を返す。クライアント アプリケーションが、最初にログオンせずに保証メッセージを送信しようとした場合は、DPERR_NOTLOGGEDIN を返す。

メッセージをグループに送信する場合、戻り値 DP_OK は、必ずしもグループ内のすべてのプレーヤーがメッセージを受信したことを示すわけではない。メッセージを保証付きで送信した場合、DP_OK は、DirectPlay がそのメッセージをグループ内のすべてのプレーヤーに送信するために全力を尽くしたことを意味する。通常、このメッセージを受信しないプレーヤーは、セッションから削除される。これは、それらのプレーヤーの接続に問題があるからである。

注意

非同期送信のオプションを使用する場合は、DirectPlay4.SendEx を使用する。

システム メッセージ以外のメッセージは、保証付きまたは保証なしのどちらかで送信できる。デフォルトでは、非システム メッセージは、保証なしで送信される。これは、DirectPlay が、メッセージが送信先に届いたことを保証しないということである。保証メッセージの送信には、かなりの時間がかかる。最低でも、保証なしのメッセージの 2 倍から 3 倍の時間がかかる。アプリケーションでは、保証メッセージの送信をできるだけ少なくすると共に、メッセージの喪失に耐えられるようにする必要がある。

システム メッセージは、サービス プロバイダが保証メッセージをネイティブにサポートしているかどうか、または DirectPlay プロトコルのフラグが設定されているかどうかに関係なく、常に保証付きで送信される。システム メッセージを保証付きで送信する場合は、DirectPlay プロトコルが自動的に使用される。

システム メッセージ以外のメッセージの場合、アプリケーションが DirectPlay プロトコルのフラグを設定し、メッセージを保証付きで送信すると (DPSEND_GUARANTEED フラグを設定する)、サービス プロバイダが保証メッセージをサポートするかどうかに関係なく、メッセージは保証付きで送信される。

システム メッセージ以外のメッセージの場合、アプリケーションが DirectPlay プロトコルのフラグを設定せず、メッセージを保証付きで送信すると、サービス プロバイダが保証メッセージをサポートする場合に限り、メッセージは保証付きで送信される。サービス プロバイダが保証メッセージをサポートしない場合、DPSEND_GUARANTEED フラグに関係なく、メッセージは保証付きでは送信されない。

アプリケーションは、セッションを作成するときに DPSESSION_DIRECTPLAYPROTOCOL フラグを設定して、DirectPlay プロトコルを開始する。

DirectPlay に付属しているすべてのサービス プロバイダは、破壊を防ぐために、データに対して整合性チェックを実行する。このメソッドを使用して送信されたメッセージは、すべて破壊から保護される。

プレーヤーは、自らにメッセージを送信することはできない。プレーヤーが、DPID_ALLPLAYERS の一部であるグループまたは DPID_ALLPLAYERS にメッセージを送信すると、プレーヤーはそのメッセージのコピーを受け取らない。ただし、セッション記述で DPSESSION_NOMESSAGEID が指定されている場合は例外である。この場合、プレーヤーは、自らがグループに送信したメッセージを受信することができる。このメッセージには、メッセージの送信者を示す DirectPlay の ID ヘッダーが存在しないため、メッセージ ID に基づいてメッセージをフィルタリングすることはできない。

ターゲット コンピュータ上に 2 人以上のプレーヤーがいる場合、メッセージが誰の受信キューに現れるかを判断することはできない。メッセージを受信すると、そのメッセージは、DPID_UNKNOWN というプレーヤーから送信されたように見える。

Send メソッドを使用して送信できるメッセージのサイズに制限はない。DirectPlay は、サイズの大きなメッセージを自動的にパケットに分割 (パケット化) し、受信側でそれらを再度組み立てる。大きなメッセージを保証なしで送信する場合には注意が必要である。パケットが 1 つでも送信先に届かないと、メッセージ全体が無視される。アプリケーションでは、GetCaps を呼び出して、DPCAPS 型の lMaxBufferSize メンバを調べることにより、パケットの最大サイズを判断することができる。

暗号化されたメッセージまたは署名付きのメッセージを送信すると、そのメッセージは、アプリケーション メッセージではなく、DPSYS_SECUREMESSAGE システム メッセージとして転送される。

参照

DirectPlay4.Receive、DirectPlay4.SendChatMessage、CONST_DPIDFLAGS


DirectPlay4.SendChatMessage

DirectPlay4.SendChatMessage メソッドは、ほかのプレーヤー、プレーヤーのグループ、またはすべてのプレーヤーにテキスト メッセージを送信する。チャット メッセージを受信しているプレーヤーは、プレーヤーの受信キュー内の DPSYS_CHAT システム メッセージで通知される。このメソッドは、ロビー セッションで使用する必要がある。

object.SendChatMessage(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    message As String)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
fromPlayerId
送信側のプレーヤーの ID。このプレーヤー ID は、このコンピュータ上のローカル プレーヤーのいずれかに一致していなければならない。
toPlayerId
メッセージを送信するプレーヤーの ID、プレーヤーのグループの ID、またはセッション内のすべてのプレーヤーにメッセージを送信する場合は DPID_ALLPLAYERS。
flags
メッセージの送信方法を示す値。このパラメータに 0 を設定すると、メッセージは保証なしで送信される。
DPSEND_GUARANTEED
利用可能であれば、保証された配信方法を使用してメッセージを送信する。
message
送信するメッセージ。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

toPlayerId の ID が有効なプレーヤーまたはグループでない場合は、DPERR_INVALIDPARAMS を返す。fromPlayerId の ID が有効なプレーヤーでない場合は、DPERR_INVALIDPLAYER を返す。fromPlayerId の ID がローカル プレーヤーでない場合は、DPERR_ACCESSDENIED を返す。

注意

このメソッドは、異なるクライアント アプリケーションが接続可能なロビー セッション内でのプレーヤー対プレーヤーのチャットを可能にする。アプリケーション セッションでは、DirectPlay4.Send メソッドを使用してチャット メッセージを送信することができる。

受信側のプレーヤーは、システム メッセージ (fromPlayerId = DPID_SYSMSG) を受け取る。


DirectPlay4.SendEx

DirectPlay4.SendEx メソッドは、ほかのプレーヤー、プレーヤーのグループ、またはセッション内のすべてのプレーヤーにメッセージを送信する。SendEx は、DirectPlay4.Send メソッドの強化版であり、より多くのオプションを利用できる。SendEx は、保証付きおよび保証なしの両方のメッセージをサポートする。また、非同期メッセージの送信と、メッセージの優先順位およびタイムアウトの設定を可能にする。

object.SendEx(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    msg As DirectPlayMessage, _
    priority As Long, _
    timeOut As Long, _
    context As Long) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
fromPlayerId
送信側のプレーヤーの ID。このプレーヤー ID は、このメッセージを発信したコンピュータ上のローカル プレーヤーのいずれかに一致していなければならない。
toPlayerId
メッセージの送信先の ID。メッセージをほかのプレーヤーに送信するには、そのプレーヤーの ID を設定する。メッセージをグループ内のすべてのプレーヤーに送信するには、そのグループの ID を指定する。メッセージをセッション内のすべてのプレーヤーに送信するには、定数 DPID_ALLPLAYERS を使用する。メッセージをサーバー プレーヤーに送信するには、定数 DPID_SERVERPLAYER を指定する。プレーヤーは、自らにメッセージを送信することはできない。
flags
メッセージの送信方法を指定する、CONST_DPSENDFLAGS 列挙型のフラグ。デフォルト (flags = 0) では、メッセージは保証なしで送信される。
DPSEND_ASYNC
メッセージを非同期で送信する。メソッドは直ちに戻る。このフラグを指定しない場合、メソッドは、メッセージが送信されるまで (および、保証付きで送信される場合は、送信が確認されるまで) 戻らない。送信が完了すると、DPSYS_SENDCOMPLETE システム メッセージが送信される。

このフラグを使用すると、メッセージが送信キューに配置された場合は、戻り値が DPERR_PENDING になる。これは致命的なエラーではなく、メッセージが送信されなかったことを直ちに伝えるだけである。

DPSEND_ENCRYPTED
メッセージを暗号化して送信する。これができるのは、保証セッションの場合だけである。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合に限り、使用できる。メッセージは、DPSYS_SECUREMESSAGE システム メッセージとして送信される。
DPSEND_GUARANTEED
利用可能であれば、保証された配信方法を使用してメッセージを送信する。
DPSEND_NOSENDCOMPLETEMSG
このフラグを設定すると、完了メッセージは送信されない。このフラグは、DPSEND_ASYNC も設定されている場合に限り、使用できる。
DPSEND_SIGNED
デジタル署名付きでメッセージを送信する。これができるのは、保証セッションの場合だけである。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合に限り、使用できる。メッセージは、DPSYS_SECUREMESSAGE システム メッセージとして送信される。
msg
送信するデータを表す DirectPlayMessage オブジェクト。このオブジェクトは、DirectPlay4.CreateMessage メソッドを使用して取得される。このオブジェクト自体のメソッドを使用して、オブジェクトにデータを代入することができる。
priority
メッセージの優先順位を、0 ～ 65535 の範囲で指定する。0 は、最も優先順位が低い。番号が大きくなるほど、優先順位は高い。優先順位の設定されたメッセージは、キュー内にそのメッセージよりも優先順位の高いメッセージがなくなってから、送信される。

すべてのサービス プロバイダが、このオプションをサポートしているわけではない。サポートされていない場合は、0 以外の優先順位を指定すると、DPERR_UNSUPPORTED エラーが返される。このオプションがサポートされているかどうかを判断するには、DirectPlay4.GetCaps を呼び出す。

timeOut
アプリケーションで提供されるオプションのタイムアウト。メッセージを送信する時間制限を、ミリ秒単位で指定する。この時間内にメッセージを送信できなかった場合、メッセージは自動的にキャンセルされる。0 を指定すると、タイムアウトは使用されない。

すべてのサービス プロバイダがこのオプションをサポートしているわけではない。サポートしていない場合は、0 以外のタイムアウトを指定すると、DPERR_UNSUPPORTED エラーが返される。このオプションがサポートされているかどうかを判断するには、DirectPlay4.GetCaps を呼び出す。

context
送信が完了したときに、完了メッセージの一部としてアプリケーションに返される、アプリケーション定義のコンテキスト。0 に設定することもできる。

戻り値

DirectPlay によって生成された、メッセージに対する ID を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_INVALIDPRIORITY
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG
DPERR_UNSUPPORTED

保証付きと指定されていないメッセージに対して暗号化または署名のフラグが設定されている場合は、DPERR_INVALIDPARAMS を返す。優先順位の値が 0 ～ 65535 でない場合は、DPERR_INVALIDPRIORITY を返す。優先順位に 0 以外の値が指定され、サービス プロバイダが優先順位をサポートしない場合、またはタイムアウトに 0 以外の値を指定し、サービス プロバイダがそのオプションをサポートしない場合は、DPERR_UNSUPPORTED を返す。

注意

このメソッドは、保証付きのメッセージと保証なしのメッセージをサポートする。保証付きで送信されるメッセージは、受信側に認識されるのを待機している保留中のメッセージが存在する場合に、ブロックしない。

メッセージを非同期で送信すると、メッセージは送信キューに入れられ、SendEx メソッドは直ちに戻る。送信の結果を示すために、システム メッセージが送信側のプレーヤーの受信キューに入れられる。

メッセージに優先順位を設定することができる。メッセージは、そのメッセージよりも優先順位の高いメッセージが送信を待機しておらず、十分な帯域幅が利用可能な場合に、送信される。

メッセージにタイムアウトを設定することができる。DirectPlay が指定された時間内にメッセージを配信できない場合、メッセージはキャンセルされる。

セッション記述でフラグが設定されているために、保証メッセージの配信の順番が確保されていない場合は、DPSEND_SIGNED フラグと DPSEND_ENCRYPTED フラグを使用することはできない。

異なる優先順位を使用してメッセージを送信すると、署名と暗号化はうまくいかない場合がある。アプリケーションでは、安全なメッセージのための優先順位レベルを 1 つ決め、そのレベルでのみセキュリティ フラグを使用すべきである。これは、安全なメッセージの確認は受信された順序に基づいていて、優先順位によってこの順序が変更される可能性があるからである。

DirectPlay プロトコルがアクティブであると、外向きのネットワーク トラフィックをスロットリングしようとする。つまり、パケットを常に可能な限り速く送信するわけではないということである。DirectPlay プロトコルは、受信側のコンピュータの内向きの帯域幅に影響を与えない範囲で、可能な限り高速にパケットを送信する。

システム メッセージは、サービス プロバイダが保証メッセージをネイティブにサポートしているかどうか、または DirectPlay プロトコルのフラグが設定されているかどうかに関係なく、常に保証付きで送信される。システム メッセージを保証付きで送信する場合は、DirectPlay プロトコルが自動的に使用される。

システム メッセージ以外のメッセージの場合、アプリケーションが DirectPlay プロトコルのフラグを設定し、メッセージを保証付きで送信すると (DPSEND_GUARANTEED フラグを設定する)、サービス プロバイダが保証メッセージをサポートするかどうかに関係なく、メッセージは保証付きで送信される。

システム メッセージ以外のメッセージの場合、アプリケーションが DirectPlay プロトコルのフラグを設定せず、メッセージを保証付きで送信すると、サービス プロバイダが保証メッセージをサポートする場合に限り、メッセージは保証付きで送信される。サービス プロバイダが保証メッセージをサポートしない場合、DPSEND_GUARANTEED フラグに関係なく、メッセージは保証付きでは送信されない。

参照

DirectPlay4.Send、DirectPlay4.CancelMessage、DirectPlay4.CancelPriority


DirectPlay4.SetGroupConnectionSettings

DirectPlay4.SetGroupConnectionSettings メソッドは、グループによって開始されるセッションの接続設定を行う。このメソッドは、ロビー セッションでのみ使用できる。

object.SetGroupConnectionSettings(id As Long, _
    connection As DirectPlayLobbyConnection)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
id
接続設定を行うグループの ID。
connection
起動するアプリケーションについての記述、使用するサービス プロバイダ、および作成するセッションについての記述へのアクセスを提供する、DirectPlayLobbyConnection オブジェクト。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED

参照

DirectPlayLobby3.RunApplication


DirectPlay4.SetGroupData

DirectPlay4.SetGroupData メソッドは、アプリケーションに固有のデータをグループ ID に関連付ける。グループに関連付けられているリモート データを変更できるのは、そのグループを作成したコンピュータだけである。

object.SetGroupData(GroupId As Long, _
    data As String, _
    flags As CONST_DPSETFLAGS)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
データを設定するグループ ID。
data
格納するデータ。既存のデータを消去する場合は、"" を設定する。
flags
グループ データの伝承方法を指定する、CONST_DPGETCAPSFLAGS 列挙型のフラグ。このパラメータに 0 を設定すると、保証なしのメッセージングによってリモート グループ データが設定され、伝承される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

注意

DirectPlay は、ローカルとリモートの 2 種類のグループ データを維持できる。ローカル データは、ローカル コンピュータ上のアプリケーションだけで利用できる。リモート データは、セッション内のほかのすべてのアプリケーションに伝承される。セッション記述に DPSESSION_NODATAMESSAGES が設定されている場合を除き、変更を通知するために、すべてのプレーヤー (送信したプレーヤーを含む) に DPSYS_SETPLAYERORGROUPDATA システム メッセージが送信される。リソースへのポインタを、ローカル データに安全に保存しておくことができる。このローカル データ ブロックは、グループが破棄されるときに (DPSYS_DESTROYPLAYERORGROUP システム メッセージ内で) 利用できる。そのため、アプリケーションでは、これらのリソースを解放することができる。

このメソッドは、オーバーヘッドが生じるため、リアルタイム情報の更新 (位置の更新など) のためには使用すべきではない。そのような場合は、DirectPlay4.Send の方が格段に効率的である。めったに変更されず、時間が重要ではない共有状態情報 (チーム カラーなど) には、SetGroupData の方が適している。

参照

DirectPlay4.GetGroupData


DirectPlay4.SetGroupName

DirectPlay4.SetGroupName メソッドは、グループが作成された後に、その名前を設定する。グループの名前を設定できるのは、そのグループを作成したコンピュータだけである。

object.SetGroupName(GroupId As Long, _
    friendlyName As String, _
    formalName As String, _
    flags As CONST_DPSETFLAGS)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
名前を設定するグループの ID。
friendlyName
グループのショート ネーム。グループがフレンドリ名を持たない場合は、"" を設定する。
formalName
グループのロング ネーム。グループが正式名を持たない場合は、"" を設定する。
flags
データ伝承のオプションを設定する、CONST_DPSETFLAGS 列挙型のフラグ。このパラメータに 0 を設定すると、名前は保証なしのメッセージングを使用して、すべてのリモート システムに伝承される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

セッション記述で DPSESSION_NODATAMESSAGES が設定されている場合を除き、変更を通知するために、ほかのすべてのプレーヤーに DPSYS_SETPLAYERORGROUPNAME システム メッセージが送信される。

参照

DirectPlay4.GetGroupLongName、DirectPlay4.GetGroupShortName、DirectPlay4.Send


DirectPlay4.SetGroupOwner

DirectPlay4.SetGroupOwner メソッドは、グループの所有者を変更する。このメソッドは、ロビー セッションでのみ使用できる。

object.SetGroupOwner(GroupId As Long, _
    ownerId As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
GroupId
所有者を変更するグループの ID。
ownerId
グループの所有者として設定するプレーヤーの ID。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTIONLOST
DPERR_GENERIC
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

セッションがロビー セッションでない場合は、DPERR_UNAVAILABLE を返す。

参照

DirectPlay4.GetGroupOwner


DirectPlay4.SetPlayerData

DirectPlay4.SetPlayerData メソッドは、アプリケーションに固有のデータ ブロックを、プレーヤー ID に関連付ける。

object.SetPlayerData(playerId As Long, _
    data As String, _
    flags As CONST_DPSETFLAGS)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
データを設定するプレーヤーの ID。
data
設定するデータ。既存のプレーヤー データを消去する場合は、"" を設定する。
flags
データ伝承のオプションを設定する、CONST_DPSETFLAGS 列挙型のフラグ。このパラメータに 0 (DPGET_REMOTE) を設定すると、保証なしのメッセージングを使用して、リモート プレーヤーのデータが設定および伝承される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

注意

このメソッドは、オーバーヘッドが生じるため、リアルタイム情報の更新 (位置の更新など) のためには使用すべきではない。そのような場合は、DirectPlay4.Send の方が格段に効率的である。めったに変更されず、時間が重要ではない共有状態情報 (プレーヤーの名前など) には、SetPlayerData の方が適している。

DirectPlay は、ローカルとリモートの 2 種類のグループ データを維持できる。ローカル データは、ローカル コンピュータ上のアプリケーションだけで利用できる。リモート データは、セッション内のほかのすべてのアプリケーションに伝承される。リモート プレーヤーに対してプレーヤー データを設定しようとすると、DPERR_ACCESSDENIED が返される。セッション記述に DPSESSION_NODATAMESSAGES が設定されている場合を除き、変更を通知するために、すべてのプレーヤー (送信したプレーヤーを含む) に DPSYS_SETPLAYERORGROUPDATA システム メッセージが送信される。リソースへのポインタを、ローカル データに安全に保存しておくことができる。このローカル データ ブロックは、グループが破棄されるときに (DPSYS_DESTROYPLAYERORGROUP システム メッセージ内で) 利用できる。そのため、アプリケーションでは、これらのリソースを解放することができる。

参照

DirectPlay4.GetPlayerData


DirectPlay4.SetPlayerName

DirectPlay4.SetPlayerName メソッドは、ローカル プレーヤーの正式名およびフレンドリ名を変更する。名前を変更できるのは、そのプレーヤーを作成したコンピュータだけである。

object.SetPlayerName(playerId As Long, _
  friendlyName As String, _
  formalName As String, _
  flags As CONST_DPSETFLAGS)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
playerId
データを送信するローカル プレーヤーの ID。
friendlyName
プレーヤーのフレンドリ ("ショート") 名。
formalName
プレーヤーの正式 ("ロング") 名。
flags
名前の伝承方法を示す、CONST_DPSETFLAGS 列挙型のフラグ。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

注意

セッション記述に DPSESSION_NODATAMESSAGES が設定されている場合を除き、変更を通知するために、ほかのすべてのプレーヤーに DPSYS_SETPLAYERORGROUPNAME システム メッセージが送信される。

参照

DirectPlay4.GetPlayerFriendlyName、DirectPlay4.GetPlayerFormalName


DirectPlay4.SetSessionDesc

DirectPlay4.SetSessionDesc メソッドは、現在のセッションのプロパティを変更する。セッションのプロパティを変更できるのは、セッションのホストだけである。

このメソッドは、ロビー セッションでは使用できない。

object.SetSessionDesc(sessionDesc As DirectPlaySessionData)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
sessionDesc
新しい設定を含む DirectPlaySessionData オブジェクト。このオブジェクトは、DirectPlay4.GetSessionDesc メソッドを使用して取得できる。このオブジェクト自体のメソッドを使用して、データを変更することができる。「注意」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

このコンピュータがセッションを変更する権限を持っていない場合は、DPERR_ACCESSDENIED を返す。アプリケーションが変更できないセッション記述のプロパティを変更しようとした場合や、プロパティに無効な値を設定しようとした場合は、DPERR_INVALIDPARAMS を返す。

注意

更新されたセッション記述は、セッション内のほかのすべてのコンピュータに伝承される。各プレーヤーは、DPSYS_SETSESSIONDESC システム メッセージを受信する。

以下のメソッドを使用して、セッション記述の変更可能な要素を設定することができる。

DirectPlaySessionData.SetFlags
以下のフラグを追加または削除できる。

DPSESSION_JOINDISABLED
DPSESSION_NEWPLAYERSDISABLED
DPSESSION_NODATAMESSAGES
DPSESSION_PRIVATE

以下のフラグを維持する必要がある。そうでない場合、SetSessionDesc を呼び出したときに、エラーが発生する。
DPSESSION_NOMESSAGEID
DPSESSION_KEEPALIVE
DirectPlaySessionData.SetMaxPlayers
現在のプレーヤー数よりも少ない最大プレーヤー数が設定された場合は、DPERR_INVALIDPARAMS を返す。
DirectPlaySessionData.SetSessionName
DirectPlaySessionData.SetSessionPassword
DirectPlaySessionData.SetUser1
DirectPlaySessionData.SetUser2
DirectPlaySessionData.SetUser3
DirectPlaySessionData.SetUser4

DirectPlaySessionData.SetGuidInstance または DirectPlaySessionData.SetGuidApplication を呼び出してオブジェクトのほかのプロパティを変更した場合は、新しい設定は無視される。つまり、DirectPlay は、DirectPlay4.Open が呼び出されたときの値を常に使用する。

参照

DirectPlay4.GetSessionDesc


DirectPlay4.StartSession

DirectPlay4.StartSession メソッドは、ステージング領域から DirectPlay セッションを開始する。最初に、SetGroupConnectionSettings を呼び出して、起動するアプリケーション、使用するサービス プロバイダ、および使用するセッション記述を指定する。

object.StartSession(id As Long)

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
id
セッションを開始するコマンドを送信するグループの ID。このグループは、ステージング領域でなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

指定されたグループ ID が有効なステージング領域ではない場合は、DPERR_INVALIDGROUP を返す。

注意

StartSession を呼び出すと、グループ内の各プレーヤーは、セッションを開始するように指示する DPSYS_STARTSESSION システム メッセージを受信する。

セッションが既に開始されているステージング領域のグループに参加するプレーヤーは、このメソッドを呼び出してセッションに参加することができる。プレーヤーは、セッションに参加する方法に関する情報を含む DPSYS_STARTSESSION メッセージを受け取る。

参照

同期起動


DirectPlayAddress

DirectPlayAddress クラスは、DirectPlay が、ロビー サーバー、アプリケーション、DirectPlay、およびサービス プロバイダの間でアドレス情報を渡すために使用するデータ書式を表す。概要については、「DirectPlay アドレス」を参照すること。

DirectPlayAddress オブジェクトは、以下のメソッドによって返される。

  • DirectPlay4.GetPlayerAddress
  • DirectPlayEnumConnections.GetAddress
  • DirectPlayLobby3.CreateComPortAddress
  • DirectPlayLobby3.CreateCustomAddress
  • DirectPlayLobby3.CreateINetAddress
  • DirectPlayLobby3.CreateIPXAddress
  • DirectPlayLobby3.CreateLobbyProviderAddress
  • DirectPlayLobby3.CreateModemAddress
  • DirectPlayLobby3.CreateServiceProviderAddress
  • DirectPlayLobbyConnection.GetAddress

DirectPlayAddress クラス自体は、パブリック メソッドを持たない。

参照

DirectPlay4.InitializeConnection、DirectPlayLobbyConnection.SetAddress


DirectPlayEnumConnections

DirectPlayEnumConnections クラスは、接続を列挙する。アプリケーションでは、DirectPlayEnumConnections クラス オブジェクトのメソッドを使用して、列挙された項目に関する情報を取得することができる。

DirectPlayEnumConnections オブジェクトを取得するには、DirectPlay4.GetDPEnumConnections メソッドを使用する。

DirectPlayEnumConnections クラスには、以下のメソッドがある。

列挙 | GetAddress
 | GetCount
 | GetFlags
 | GetGuid
 | GetName


DirectPlayEnumConnections.GetAddress

DirectPlayEnumConnections.GetAddress メソッドは、列挙型からアドレス オブジェクトを取得する

object.GetAddress(index As Long) As DirectPlayAddress

パラメータ

object
DirectPlayEnumConnections オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumConnections.GetCount

DirectPlayEnumConnections.GetCount メソッドは、列挙型オブジェクトの要素の数を取得する。

object.GetCount() As Long

パラメータ

object
DirectPlayEnumConnections オブジェクトを表すオブジェクト式。

戻り値

列挙型オブジェクトの要素の数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumConnections.GetFlags

DirectPlayEnumConnections.GetFlags メソッドは、列挙された接続に対するフラグを取得する。

object.GetFlags(index As Long) As Long

パラメータ

object
DirectPlayEnumConnections オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

接続に対するフラグを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

戻り値は、DirectPlay4.GetDPEnumConnections に渡されるフラグに等しい。


DirectPlayEnumConnections.GetGuid

DirectPlayEnumConnections.GetGuid メソッドは、列挙された接続に対するグローバル ユニーク識別子 (GUID) を返す。

object.GetGuid(index As Long) as String

パラメータ

object
DirectPlayEnumConnections オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

接続の GUID を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectPlayEnumConnections.GetName

DirectPlayEnumConnections.GetName メソッドは、列挙型から名前オブジェクトを取得する。

object.GetName(index As Long) As String

パラメータ

object
DirectPlayEnumConnections オブジェクトを表すオブジェクト式。
index
データを取得する列挙型の要素。

戻り値

接続の名前 (たとえば、"IPX Connection for DirectPlay") を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumLocalApplications

DirectPlayEnumLocalApplications クラスは、ローカル アプリケーションを列挙する。アプリケーションは、DirectPlayEnumLocalApplications クラスのメソッドを使用して、列挙された項目に関する情報を取得する。

DirectPlayEnumLocalApplications オブジェクトは、DirectPlayLobby3.GetDPEnumLocalApplications メソッドによって返される。

DirectPlayEnumLocalApplications クラスには、以下のメソッドがある。

列挙 | GetCount
 | GetGuid
 | GetName


DirectPlayEnumLocalApplications.GetCount

DirectPlayEnumLocalApplications.GetCount メソッドは、列挙型オブジェクトのエントリの数を返す。

object.GetCount() As Long

パラメータ

object
DirectPlayEnumLocalApplications オブジェクトを表すオブジェクト式。

戻り値

列挙型オブジェクトのエントリの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumLocalApplications.GetGuid

DirectPlayEnumLocalApplications.GetGuid メソッドは、列挙されたアプリケーションのグローバル ユニーク識別子 (GUID) を取得する。

object.GetItem(index As Long) as String

パラメータ

object
DirectPlayEnumLocalApplications オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

アプリケーションの GUID を表す文字列を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectPlayEnumLocalApplications.GetName

DirectPlayEnumLocalApplications.GetName メソッドは、列挙されたアプリケーションの名前を返す。

object.GetItem(index As Long) as String

パラメータ

object
DirectPlayEnumLocalApplications オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

アプリケーションの名前を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumPlayers

DirectPlayEnumPlayers クラスは、セッションまたはグループ内のプレーヤーまたはグループを列挙する。アプリケーションは、DirectPlayEnumPlayers クラスのメソッドを使用して、列挙されたプレーヤーまたはグループに関する情報を取得する。

DirectPlayEnumPlayers オブジェクトは、以下のメソッドによって返される。

  • DirectPlay4.GetDPEnumGroups
  • DirectPlay4.GetDPEnumGroupsInGroup
  • DirectPlay4.GetDPEnumGroupPlayers
  • DirectPlay4.GetDPEnumPlayers

DirectPlayEnumPlayers クラスには、以下のメソッドがある。

列挙 | GetCount
 | GetDPID
 | GetFlags
 | GetLongName
 | GetShortName
 | GetType


DirectPlayEnumPlayers.GetCount

DirectPlayEnumPlayers.GetCount メソッドは、列挙型オブジェクトのエントリの数を取得する。

object.GetCount() As Long

パラメータ

object
DirectPlayEnumPlayers オブジェクトを表すオブジェクト式。

戻り値

列挙型オブジェクト内のエントリの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumPlayers.GetDPID

DirectPlayEnumPlayers.GetDPID メソッドは、列挙されたプレーヤーまたはグループの数値の識別子を返す。

object.GetDPID(index As Long) As Long

パラメータ

object
DirectPlayEnumPlayers オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

プレーヤーまたはグループが作成されたときに割り当てられた一意の識別子を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumPlayers.GetFlags

DirectPlayEnumPlayers.GetFlags メソッドは、列挙されたプレーヤーまたはグループに関する多様な情報を取得する。

object.GetFlags(index As Long) As Long

パラメータ

object
DirectPlayEnumPlayers オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

プレーヤーに対するフラグを返す。これには、列挙型を作成したメソッドに渡されたフラグが含まれる。これらは、特定のプレーヤーまたはグループに関する追加情報と組み合わせられている。

DIRECTPLAYENUMGROUPS_ALL
このセッション内のすべてのグループ。
DIRECTPLAYENUMGROUPS_LOCAL
この DirectPlay オブジェクトによってローカルに作成されたグループ。
DIRECTPLAYENUMGROUPS_REMOTE
リモートの DirectPlay オブジェクトによって作成されたグループ。
DIRECTPLAYENUMGROUPS_SESSION
指定されたセッションに対するグループ
DIRECTPLAYENUMGROUPS_SHORTCUT
DirectPlay4.AddGroupToGroup によってグループに追加されたグループ (ショートカットは、別のグループへのリンクである)。
DIRECTPLAYENUMGROUPS_STAGINGAREA
ステージング領域である、グループ内のグループ (ステージング領域は、新しいセッションを起動する際に、プレーヤーを配置するために使用される)。
DIRECTPLAYENUMPLAYERS_LOCAL
この DirectPlay オブジェクトによってローカルに作成されたプレーヤー。
DIRECTPLAYENUMPLAYERS_OWNER
このグループの所有者であるプレーヤー。
DIRECTPLAYENUMPLAYERS_REMOTE
リモートの DirectPlay オブジェクトによって作成されたプレーヤー。
DIRECTPLAYENUMPLAYERS_SERVERPLAYER
サーバー プレーヤー。
DIRECTPLAYENUMPLAYERS_SESSION
指定されたセッションに対するプレーヤー。このフラグは、現在開いているセッションが存在しない場合にのみ使用できる。ロビー セッションでは使用できない。
DIRECTPLAYENUMPLAYERS_SPECTATOR
観客であるプレーヤー。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlay4.GetDPEnumGroups、DirectPlay4.GetDPEnumGroupsInGroup、DirectPlay4.GetDPEnumPlayers、DirectPlay4.GetDPEnumGroupPlayers


DirectPlayEnumPlayers.GetLongName

DirectPlayEnumPlayers.GetLongName メソッドは、プレーヤーまたはグループの正式名を取得する。

object.GetLongName(index As Long) As String

パラメータ

object
DirectPlayEnumPlayers オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

プレーヤーまたはグループが作成されたときに割り当てられた正式名またはハンドルを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumPlayers.GetShortName

DirectPlayEnumPlayers.GetShortName メソッドは、プレーヤーまたはグループのフレンドリ名を取得する。

object.GetShortName(index As Long) As String

パラメータ

object
DirectPlayEnumPlayers オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

プレーヤーまたはグループが作成されたときに割り当てられたショート ネームまたはフレンドリ名を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumPlayers.GetType

DirectPlayEnumPlayers.GetType メソッドは、列挙された項目がプレーヤーまたはグループのどちらであるのかを確認する。

object.GetType(index As Long) As Long

パラメータ

object
DirectPlayEnumPlayers オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

列挙された項目のタイプ (DPPLAYERTYPE_GROUP または DPPLAYERTYPE_PLAYER) を、CONST_DPPLAYERTYPEFLAGS 列挙型から返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumSessions

DirectPlayEnumSessions クラスは、特定のアプリケーションに対するアクティブ セッションまたは特定のアプリケーションにサービスを提供するすべてのアクティブ ロビー セッションを列挙する。

DirectPlayEnumSessions オブジェクトを取得するには、DirectPlay4.GetDPEnumSessions メソッドを使用する。

このクラスには、以下のメソッドがある。

列挙 | GetCount
 | GetItem


DirectPlayEnumSessions.GetCount

DirectPlayEnumSessions メソッドは、列挙型オブジェクトのエントリの数を返す。

object.GetCount() As Long

パラメータ

object
DirectPlayEnumSessions オブジェクトを表すオブジェクト式。

戻り値

列挙型オブジェクトのエントリの数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayEnumSessions.GetItem

DirectPlayEnumSessions.GetItem メソッドは、列挙されたセッションに対するデータを表す DirectPlaySessionData オブジェクトを取得する。

object.GetItem(index As Long) As DirectPlaySessionData

パラメータ

object
DirectPlayEnumSessions オブジェクトを表すオブジェクト式。
index
データを取得する列挙型オブジェクトの要素。

戻り値

成功すれば、DirectPlaySessionData オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayLobby3

アプリケーションは、DirectPlayLobby3 クラスのメソッドを使用して、アプリケーションとそれに関連するデータを管理する。

DirectPlayLobby3 オブジェクトを取得するには、DirectX7.DirectPlayLobbyCreate メソッドを使用する。

DirectPlayLobby3 インターフェイスのメソッドは、以下のグループにまとめることができる。

アドレス | CreateComPortAddress
 | CreateCustomAddress
 | CreateInetAddress
 | CreateIPXAddress
 | CreateLobbyProviderAddress
 | CreateModemAddress
 | CreateServiceProviderAddress
 | GetModemCount
 | GetModemName
アプリケーション | Connect
 | GetDPEnumLocalApplications
 | RegisterApplication
 | RunApplication
 | UnregisterApplication
 | WaitForConnectionSettings
メッセージ | CreateMessage
 | ReceiveLobbyMessage
 | SendLobbyMessage
 | SetLobbyMessageEvent
接続 | CreateConnectionData
 | GetConnectionSettings
 | SetConnectionSettings


DirectPlayLobby3.Connect

DirectPlayLobby3.Connect メソッドは、現在 DirectPlayLobby3 オブジェクトと共に格納されている DirectPlayLobbyConnection オブジェクトによって指定されるセッションに、アプリケーションを接続する。

object.Connect(flags As Long) As DirectPlay4

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
flags
接続の方法を示す、CONST_DPCONNECTFLAGS 列挙型のメンバ。デフォルト (flags = 0 または DPCONNECTION_DEFAULT) では、接続が確立されるか、または操作がタイムアウトになってから、メソッドが戻る。このフラグが DPCONNECTION_RETURNSTATUS の場合、メソッドは接続の状態と共に直ちに戻る。

戻り値

成功すれば、DirectPlay4 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CONNECTING
DPERR_INVALIDFLAGS
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY

注意

デフォルトでは、Connect は接続が確立されるか、または接続がタイムアウトになった後で戻る。DPCONNECT_RETURNSTATUS フラグを使用すると、Connect は、接続が進行中であることを示す DPERR_CONNECTING エラー コードと共に直ちに戻る。アプリケーションは、メソッドが成功するか、または別の失敗コードが返されるまで、このメソッドを繰り返し呼び出す必要がある。接続をキャンセルするには、DirectPlayLobby3 オブジェクトを解放する。

接続のタイムアウトの上限は、1 分である。

このメソッドが適切に完了すると、アプリケーションは DirectPlay4.InitializeConnection、DirectPlay4.GetDPEnumSessions、および DirectPlay4.Open を呼び出す手順を省略することができる。アプリケーションでは、ユーザーに名前をたずねるべきではない。代わりに、DirectPlayLobbyConnection インターフェイスでプレーヤー名を使用してプレーヤーを作成すべきである。

アプリケーションでは、このメソッドを呼び出す前に、DirectPlayLobby3.GetConnectionSettings メソッドを使用して、アプリケーションを起動するために使用される接続設定を調べることができる。DirectPlayLobby3.SetConnectionSettings メソッドを使用すると、これらの設定を修正および設定することができる。DirectPlaySessionData オブジェクトには特に注意を払い、セッションの適切なプロパティが設定されるようにする必要がある。


DirectPlayLobby3.CreateComPortAddress

DirectPlayLobby3.CreateComPortAddress メソッドは、COM ポートに対する DirectPlay アドレスを作成する。

object.CreateComPortAddress(port As Long, _
    baudRate As Long, _
    stopBits As Long, _
    parity As Long, _
    flowcontrol As Long) As DirectPlayAddress

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
port
使用する COM ポートの番号。1、2、3、4 のいずれかを設定できる。
baudRate
ポートのボー レート。以下のいずれかの値を設定できる。
110 | 300 | 600
1200 | 2400 | 4800
9600 | 14400 | 19200
38400 | 56000 | 57600
115200 | 128000 | 256000

stopBits
ストップ ビットの番号。0 (ストップ ビットなし)、1 (1.5 ストップ ビット)、2 (2 ストップ ビット) のいずれかを設定できる。
parity
パリティ。以下のいずれかの値を設定できる。
0 | パリティなし
1 | 奇数パリティ
2 | 偶数パリティ
3 | マーク パリティ

flowcontrol
フロー制御の方法。以下のいずれかの値を設定できる。
0 | フロー制御なし
1 | ソフトウェア フロー制御 (xon/xoff)
2 | RTS を使用したハードウェア フロー制御
3 | DTR を使用したハードウェア フロー制御
4 | RTS と DTR を使用したハードウェア フロー制御

戻り値

成功すれば、DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値が設定される。

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateConnectionData

DirectPlayLobby3.CreateConnectionData メソッドは、接続設定を行うために使用できるオブジェクトを作成する。

object.CreateConnectionData() As DirectPlayLobbyConnection

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectPlayLobbyConnection オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlayLobby3.SetConnectionSettings


DirectPlayLobby3.CreateCustomAddress

DirectPlayLobby3.CreateCustomAddress メソッドは、ほかのアドレス作成メソッドでサポートされていない種類の DirectPlay アドレスを作成する。

object.CreateCustomAddress(size As Long, _
    data As Any) As DirectPlayAddress

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
size
データのサイズ。
data
アドレスに組み込まれるデータ。

戻り値

成功すれば、DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値が設定される。

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateINetAddress

DirectPlayLobby3.CreateINetAddress メソッドは、インターネット アドレスに対する DirectPlay アドレスを作成する。

object.CreateINetAddress(addr As String, _
    port As Long) As DirectPlayAddress

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
addr
IP アドレス ("192.168.0.1" など) またはドメイン名 ("microsoft.com" など)。
port
接続に使用するポート。デフォルトのポートを指定するには、0 を設定する。詳細については、「TCP/IP」を参照すること。

戻り値

成功すれば、DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値が設定される。

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateIPXAddress

DirectPlayLobby3.CreateIPXAddress メソッドは、IPX サービス プロバイダに対する DirectPlay アドレスを作成する。

object.CreateIPXAddress() As DirectPlayAddress

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlayLobby3.CreateServiceProviderAddress


DirectPlayLobby3.CreateLobbyProviderAddress

DirectPlayLobby3.CreateLobbyProviderAddress メソッドは、ロビー プロバイダに対する DirectPlay アドレスを作成する。

object.CreateLobbyProviderAddress( _
    guid As String) As DirectPlayAddress

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
guid
ロビー プロバイダに対する一意の識別子。

戻り値

成功すれば、DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値が設定される。

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateMessage

DirectPlayLobby3.CreateMessage メソッドは、ロビー メッセージを作成する。

object.CreateMessage() As DirectPlayMessage

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectPlayMessage オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayLobby3.CreateModemAddress

DirectPlayLobby3.CreateModemAddress メソッドは、モデムに対する DirectPlay アドレスを作成する。

object.CreateModemAddress( _
    modem As String, _
    phone as String) As DirectPlayAddress

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
modem
モデムの名前。利用可能なモデムの名前を取得するには、DirectPlayLobby3.GetModemName メソッドを使用する。デフォルトのモデムを指定するには、空の文字列を使用する。
phone
ダイヤルする電話番号。

戻り値

成功すれば、DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値が設定される。

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateServiceProviderAddress

DirectPlayLobby3.CreateServiceProviderAddress メソッドは、サービス プロバイダに対する DirectPlay アドレスを作成する。

object.CreateServiceProviderAddress( _
    guid as String) As DirectPlayAddress

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
guid
サービス プロバイダの一意の識別子。

戻り値

成功すれば、DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次の値が設定される。

DPERR_INVALIDPARAMS

参照

DirectPlayLobby3.CreateIPXAddress


DirectPlayLobby3.GetConnectionSettings

DirectPlayLobby3.GetConnectionSettings メソッドは、アプリケーションを開始および接続するために必要な情報をすべて含む DirectPlayLobbyConnection オブジェクトを取得する。返される情報は、ロビー クライアントによって DirectPlayLobby3.RunApplication メソッドに渡されたデータ、または DirectPlayLobby3.SetConnectionSettings メソッドの呼び出しによって設定されたデータと同じである。

object.GetConnectionSettings(applicationId As Long) _
    As DirectPlayLobbyConnection

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
applicationId
(複数のアプリケーションと通信する) ロビー クライアントから呼び出される場合は、どのアプリケーションの接続設定を取得するのかを指定する。この ID 番号は、DirectPlayLobby3.RunApplication から取得される。(1 つのロビー クライアントと通信している) アプリケーションから呼び出される場合は、このパラメータは 0 である。

戻り値

成功すれば、DirectPlayLobbyConnection オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY

参照

DirectPlayLobby3.WaitForConnectionSettings


DirectPlayLobby3.GetDPEnumLocalApplications

DirectPlayLobby3.GetDPEnumLocalApplications メソッドは、DirectPlay によって登録されたアプリケーションを列挙する。

object.GetDPEnumLocalApplications() _
    As DirectPlayEnumLocalApplications

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、DirectPlayEnumLocalApplications オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY


DirectPlayLobby3.GetModemCount

DirectPlayLobby3.GetModemCount メソッドは、プレーヤーのシステム上で利用可能なモデムの数を取得する。

object.GetModemCount() As Long

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。

戻り値

成功すれば、利用可能なモデムの数を返す。これらのモデムの名前は、DirectPlayLobby3.GetModemName メソッドを使用して取得することができる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayLobby3.GetModemName

DirectPlayLobby3.GetModemName メソッドは、プレーヤーのシステム上で利用可能なモデムの名前を取得する。

object.GetModemName(index As Long) As String

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
index
利用可能なモデムのリストのインデックス。値は、1 から DirectPlayLobby3.GetModemCount までの範囲でなければならない。

戻り値

成功すれば、モデムの名前を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlayLobby3.CreateModemAddress


DirectPlayLobby3.ReceiveLobbyMessage

DirectPlayLobby3.ReceiveLobbyMessage メソッドは、ロビー クライアント アプリケーションと DirectPlay アプリケーションの間で送信されるメッセージを取得する。メッセージはキューに入れられるので、時間内に読めなくても、データを失う危険はない。

object.ReceiveLobbyMessage(applicationId As Long, _
    messageFlags As Long) As DirectPlayMessage

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
applicationId
メッセージを受信するアプリケーションの識別子。(複数のアプリケーションと通信する) ロビー クライアントから呼び出される場合、この ID 番号は、DirectPlayLobby3.RunApplication メソッドにより取得されるもののいずれかになる。(1 つのロビー クライアントのみと通信する) アプリケーションから呼び出される場合、このパラメータには 0 を設定する必要がある。
messageFlags
返されるメッセージのタイプを示す、CONST_DPLMSG 列挙型のフラグ。デフォルト (messageFlags = 0 または DPLMSG_USERDEFINED) は、メッセージが送信側によって独自に定義されたものであることを示す。この種のメッセージの処理はオプションである。受信側は、このメッセージを、送信側のアプリケーションの身元に応じて解釈する必要がある。ロビーは、起動されたアプリケーションの GUID に応じて、送信側のアプリケーションを識別することができる。アプリケーションは、識別用の GUID を要求する標準のメッセージを送信することにより、ロビーを識別する必要がある。

戻り値

成功すれば、DirectPlayMessage オブジェクトを返す。このオブジェクトのメソッドを使用して、メッセージのデータを取り出すことができる。保留中のメッセージが存在しない場合は、Nothing を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_APPNOTSTARTED
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

参照

DirectPlayLobby3.SendLobbyMessage


DirectPlayLobby3.RegisterApplication

DirectPlayLobby3.RegisterApplication メソッドは、DirectPlay にロビー対応アプリケーションを登録する。DirectPlay ロビーからアプリケーションを起動できるようにするには、そのアプリケーションを登録する必要がある。

アプリケーションは 1 回だけ登録すればよい。アンインストール時には、アプリケーションの登録を解除する必要がある。

object.RegisterApplication( _
    ApplicationInfo As DPAPPLICATIONDESC2)

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
ApplicationInfo
登録するアプリケーションを記述する DPAPPLICATIONDESC2 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS.

参照

DirectPlayLobby3.UnregisterApplication


DirectPlayLobby3.RunApplication

DirectPlayLobby3.RunApplication メソッドは、アプリケーションを開始し、そのアプリケーションをセッションに接続するために必要な情報をすべて渡す。このメソッドは、ロビー クライアントによって使用される。

object.RunApplication( _
    connection As DirectPlayLobbyConnection, _
    receiveEvent As Long) As Long

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
connection
ユーザーにダイアログ ボックスを表示せずに、開始するアプリケーションと、セッションのインスタンスに接続する方法を指定するために必要な情報をすべて含む、DirectPlayLobbyConnection インターフェイス。
receiveEvent
ロビー メッセージを受信したときに設定される同期イベントへのハンドル。このイベントは、後で DirectPlayLobby3.SetLobbyMessageEvent メソッドを使用して変更することができる。

戻り値

開始されたアプリケーションの ID を返す。ロビー クライアントは、このアプリケーション ID を保存して、DirectPlayLobby3.SendLobbyMessage メソッドおよび DirectPlayLobby3.ReceiveLobbyMessage メソッドの呼び出しで使用できるようにする必要がある。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_CANTCREATEPROCESS
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_UNKNOWNAPPLICATION

注意

このメソッドは、アプリケーション プロセスが作成された後に戻る。ロビー クライアントは、アプリケーションの状態を示すシステム メッセージを受信する。ロビー クライアントがセッションをホストするアプリケーションを起動している場合は、DPLSYS_DPLAYCONNECTSUCCEEDED システム メッセージを受信してから、そのセッションに参加するほかのアプリケーションを起動する必要がある。アプリケーションがセッションを作成または参加できなかった場合は、DPLSYS_DPLAYCONNECTFAILED メッセージが生成される。また、ロビー クライアントは、アプリケーションが接続設定を読み取ったときに DPLSYS_CONNECTIONSETTINGSREAD システム メッセージを受信し、アプリケーションが終了したときに DPLSYS_APPTERMINATED システム メッセージを受信する。

ロビー クライアントは、DPLSYS_CONNECTIONSETTINGSREAD システム メッセージを受信するまで、DirectPlayLobby3 オブジェクトを解放しないことが重要である。ロビー クライアントは、ReceiveLobbyMessage メッセージを受信するまでループで確認するか、または同期イベントを提供することができる。

参照

DirectPlayLobby3.GetConnectionSettings、DirectX7.CreateEvent


DirectPlayLobby3.SendLobbyMessage

DirectPlayLobby3.SendLobbyMessage メッセージは、アプリケーションとロビー クライアントの間でメッセージを送信する。

object.SendLobbyMessage(flags As CONST_DPLMSG, _
    applicationId As Long, _
    msg As DirectPlayMessage)

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
flags
送信するメッセージのタイプを示す、CONST_DPLMSG 列挙型のフラグ。デフォルト (flags = 0 または DPLMSG_USERDEFINED) は、送信するアプリケーションによって定義されるカスタム メッセージである。ほかには、DirectPlay で定義される標準メッセージを示す DPLMSG_STANDARD を指定できる。
applicationId
(複数のアプリケーションと通信する) ロビー クライアントから呼び出される場合は、メッセージを送信するアプリケーションを指定する。(1 つのロビー クライアントとのみ通信する) アプリケーションから呼び出される場合は、このパラメータは 0 でなければならない。この ID を取得するには、DirectPlayLobby3.RunApplication メソッドを使用する。
msg
送信するメッセージを表す DirectPlayMessage オブジェクト。このオブジェクトを取得するには、DirectPlayLobby3.CreateMessage メソッドを使用する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_APPNOTSTARTED
DPERR_BUFFERTOOLARGE
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_TIMEOUT

参照

DirectPlayLobby3.ReceiveLobbyMessage


DirectPlayLobby3.SetConnectionSettings

DirectPlayLobby3.SetConnectionSettings メソッドは、アプリケーションを起動および接続するために必要な情報を変更する。

object.SetConnectionSettings(applicationId As Long, _
    connection As DirectPlayLobbyConnection)

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
applicationId
(複数のアプリケーションと通信する) ロビー クライアントから呼び出される場合は、接続設定を行うアプリケーションを識別する。この ID を取得するには、DirectPlayLobby3.RunApplication メソッドを使用する。(1 つのロビー クライアントのみと通信する) アプリケーションから呼び出される場合は、0 でなければならない。
connection
ユーザーにダイアログ ボックスを表示せずに、開始するアプリケーションと、セッションのインスタンスに接続する方法を指定するために必要な情報をすべて含む、DirectPlayLobbyConnection オブジェクト。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

参照

DirectPlayLobby3.GetConnectionSettings


DirectPlayLobby3.SetLobbyMessageEvent

DirectPlayLobby3.SetLobbyMessageEvent メソッドは、ロビー メッセージを受信したときに設定されるイベントを登録する。アプリケーションでは、メッセージとの同期が必要な場合は、このメソッドを呼び出す必要がある。ロビー クライアントは、このメソッドを呼び出して、DirectPlayLobby3.RunApplication メソッドの呼び出しで指定されたイベントを変更することができる。

object.SetLobbyMessageEvent(applicationId As Long, _
    receiveEvent As Long)

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
applicationId
(複数のアプリケーションと通信する) ロビー クライアントから呼び出される場合は、イベントを関連付けるアプリケーションを識別する。この ID 番号は、RunApplication から取得する。(1 つのロビー クライアントのみと通信する) アプリケーションから呼び出される場合は、0 でなければならない。
receiveEvent
メッセージを受信したときに設定されるイベントへのハンドル。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

参照

DirectPlayLobby3.ReceiveLobbyMessage、DirectPlayLobby3.SendLobbyMessage、DirectX7.CreateEvent


DirectPlayLobby3.UnregisterApplication

DirectPlayLobby3.UnregisterApplication メソッドは、DirectPlay アプリケーションのレジストリ エントリを削除する。

object.UnregisterApplication(GuidApplication As String)

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
GuidApplication
レジストリから削除するアプリケーションのグローバル ユニーク識別子 (GUID)。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNKNOWNAPPLICATION

アプリケーションの GUID がレジストリで見つからなかった場合は、DPERR_UNKNOWNAPPLICATION を返す。

参照

DirectPlayLobby3.RegisterApplication、DPAPPLICATIONDESC2


DirectPlayLobby3.WaitForConnectionSettings

DirectPlayLobby3.WaitForConnectionSettings メソッドは、アプリケーションを待機モードに設定する。待機モードでは、接続設定を待機する。アプリケーションが待機モードに設定されている場合、aDirectPlayLobby3.RunApplication メソッドを使用するロビー クライアントは、アプリケーションの新しいインスタンスを起動せず、既に待機モードで実行されているアプリケーションに接続設定を直接送信する。

アプリケーションは、DirectPlayLobby3.Connect メソッドを使用してセッションに接続することができる。

object.WaitForConnectionSettings(flags As CONST_DPLWAIT)

パラメータ

object
DirectPlayLobby3 オブジェクトを表すオブジェクト式。
flags
アプリケーションを待機モードに設定するか、または待機モードから解除する、CONST_DPLWAIT 列挙型のフラグ。デフォルト (flags = DPLWAIT_DEFAULT または 0) では、アプリケーションを待機モードに設定する。DPLWAIT_CANCEL を設定すると、アプリケーションを待機モードから解除する。ロビー クライアントから接続設定が送信されると、アプリケーションは直ちに待機モードから自動的に解除される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_INVALIDFLAGS
DPERR_UNAVAILABLE

アプリケーションが待機モードに設定されていない場合に、待機モードをキャンセルするフラグを設定した場合は、DPERR_UNAVAILABLE を返す。

ロビー クライアントが RunApplication を使用すると、DirectPlay は、接続設定を待機しているアプリケーションのインスタンスを検索する。それが見つからない場合は、アプリケーションの新しいインスタンスを起動する。待機中のアプリケーションが見つかった場合は、DirectPlayLobby3.GetConnectionSettings メソッドを使用して接続設定を読み取り、Connect を使用してセッションに接続する。


DirectPlayLobbyConnection

DirectPlayLobbyConnection クラスは、アプリケーションをセッションに接続するために必要な情報にアクセスするメソッドを提供する。このクラスのオブジェクトは、DirectPlayLobby3.CreateConnectionData メソッドおよび DirectPlayLobby3.GetConnectionSettings メソッドによって返される。

DirectPlayLobbyConnection クラスのメソッドは、以下のグループにまとめることができる。

取得 | GetAddress
 | GetFlags
 | GetGuidSP
 | GetPlayerLongName
 | GetPlayerShortName
 | GetSessionDesc
設定 | SetAddress
 | SetFlags
 | SetGuidSP
 | SetPlayerLongName
 | SetPlayerShortName
 | SetSessionDesc


DirectPlayLobbyConnection.GetAddress

DirectPlayLobbyConnection.GetAddress メソッドは、サービス プロバイダがセッションに接続するために必要な情報へのアクセスを提供する DirectPlay アドレスを取得する。

object.GetAddress() As DirectPlayAddress

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。

戻り値

DirectPlayAddress オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayLobbyConnection.GetFlags

DirectPlayLobbyConnection.GetFlags メソッドは、セッションを開く方法を示すフラグを取得する。

object.GetFlags() As Long

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。

戻り値

セッションを開く方法を示す、CONST_DPLCONNECTIONFLAGS 列挙型のいずれかのフラグを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayLobbyConnection.GetGuidSP

DirectPlayLobbyConnection.GetGuidSP メソッドは、セッションに接続するために利用するサービス プロバイダのグローバル ユニーク識別子 (GUID) を取得する。

object.GetGuidSP() As String

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。

戻り値

サービス プロバイダの GUID を、文字列形式で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectPlayLobbyConnection.GetPlayerLongName

DirectPlayLobbyConnection.GetPlayerLongName メソッドは、プレーヤーの正式名を取得する。アプリケーションでは、この名前を無視することができる。

object.GetPlayerLongName() As String

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。

戻り値

プレーヤーの正式名を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlayLobbyConnection.SetPlayerLongName


DirectPlayLobbyConnection.GetPlayerShortName

DirectPlayLobbyConnection.GetPlayerShortName メソッドは、プレーヤーのフレンドリ名を取得する。アプリケーションでは、この名前を無視することができる。

object.GetPlayerShortName() As String

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。

戻り値

プレーヤーのフレンドリ名を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlayLobbyConnection.SetPlayerShortName


DirectPlayLobbyConnection.GetSessionDesc

DirectPlayLobbyConnection.GetSessionDesc メソッドは、セッションを記述するデータを含むオブジェクトを取得する。

object.GetSessionDesc() As DirectPlaySessionData

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。

戻り値

DirectPlaySessionData オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlay4.Open、DirectPlay4.SecureOpen、DirectPlay4.SetSessionDesc


DirectPlayLobbyConnection.SetAddress

DirectPlayLobbyConnection.SetAddress メソッドは、サービス プロバイダがセッションに接続するために必要な情報へのアクセスを提供する DirectPlay アドレスを設定する。

object.SetAddress(address As DirectPlayAddress)

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。
address
DirectPlayAddress オブジェクト。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayLobbyConnection.SetFlags

DirectPlayLobbyConnection.SetFlags メソッドは、セッションを開く方法を示すフラグを設定する。

object.SetFlags(flags As CONST_DPLCONNECTIONFLAGS)

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。
flags
セッションを開く方法を示す、CONST_DPLCONNECTIONFLAGS 列挙型のフラグ。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayLobbyConnection.SetGuidSP

DirectPlayLobbyConnection.SetGuidSP メソッドは、セッションに接続するために利用するサービス プロバイダのグローバル ユニーク識別子 (GUID) を設定する。

object.SetGuidSP(guid As String)

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。
guid
サービス プロバイダの GUID。以下の文字列エイリアスのいずれかを設定できる。
DPSPGUID_IPX
DPSPGUID_TCPIP
DPSPGUID_SERIAL
DPSPGUID_MODEM

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectPlayLobbyConnection.SetPlayerLongName

DirectPlayLobbyConnection.SetPlayerLongName メソッドは、プレーヤーの正式名を設定する。この名前は、ロビーに登録されるユーザーの正式名になる。アプリケーションでは、この名前を無視することができる。

object.SetPlayerLongName(name As String)

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。
name
設定するプレーヤーの正式名

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlayLobbyConnection.SetPlayerShortName


DirectPlayLobbyConnection.SetPlayerShortName

DirectPlayLobbyConnection.SetPlayerShortName メソッドは、プレーヤーのフレンドリ名を設定する。この名前は、ロビーに登録されるユーザーのフレンドリ名になる。アプリケーションでは、この名前を無視することができる。

object.SetPlayerShortName(name As String)

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。
name
設定するプレーヤーのフレンドリ名。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectPlayLobbyConnection.SetPlayerLongName


DirectPlayLobbyConnection.SetSessionDesc

DirectPlayLobbyConnection.SetSessionDesc メソッドは、作成または参加するセッションに関する記述を設定する。

object.SetSessionDesc(sessionDesc As DirectPlaySessionData)

パラメータ

object
DirectPlayLobbyConnection オブジェクトを表すオブジェクト式。
sessionDesc
セッションを記述する DirectPlaySessionData オブジェクト。このオブジェクトを取得するには、DirectPlay4.CreateSessionData メソッドを使用する。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage

DirectPlayMessage クラスは、メッセージ データを読み書きするためのメソッドを提供する。アプリケーションで DirectPlayMessage オブジェクトを作成するには、DirectPlay4.CreateMessage メソッドを使用する。メッセージ オブジェクトは、DirectPlay4.Receive メソッドまたは DirectPlayLobby3.ReceiveLobbyMessage メソッドによって取得される。

メッセージには、任意のタイプのデータを含めることができる。これらのタイプは、メッセージ内で自由に組み合わせることができる。アプリケーションでは、データが記述された順序と同じ順序で、データを読み取る必要がある。

システム メッセージには、メッセージのタイプを示す最初の要素として、Long が常に存在する。この値を読み取ってメッセージのタイプを判断したら、DirectPlayMessage の読み取りメソッドを使用して、残りのデータを適切に解析することができる。各種のシステム メッセージのデータ書式に関する詳細については、「CONST_DPSYSMSGTYPES」を参照すること。

DirectPlayMessage クラスのメソッドは、以下のグループにまとめることができる。

データの読み取り | GetMessageData
 | MoveToSecureMessage
 | MoveToTop
 | ReadByte
 | ReadDouble
 | ReadGuid
 | ReadLong
 | ReadShort
 | ReadSingle
 | ReadString
 | ReadSysChatString
 | ReadSysMsgConnection
 | ReadSysMsgData
 | ReadSysMsgSessionDesc
データの書き込み | SetMessageData
 | WriteByte
 | WriteDouble
 | WriteGuid
 | WriteLong
 | WriteShort
 | WriteSingle
 | WriteString
その他 | Clear
 | GetMessageSize


DirectPlayMessage.Clear

DirectPlayMessage.Clear メソッドは、メッセージ オブジェクトのデータをすべて消去する。

object.Clear()

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

アプリケーションでメッセージを送信するたびに新しいオブジェクトを作成するよりも、既存のメッセージ オブジェクトを消去し、それに新しいデータを設定して再利用した方が、時間がかからない。


DirectPlayMessage.GetMessageData

DirectPlayMessage.GetMessageData メソッドは、メッセージから生のデータを取得する。

object.GetMessageData(userDefinedType As Any)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
userDefinedType
メッセージ データを受け取るユーザー定義型。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドは、DirectPlayMessage.SetMessageData を使用して記述されたメッセージからデータを取得する場合にのみ使用すべきである。このメソッドは、メッセージの一部が 1 つ以上のDirectPlayMessage.ReadX メソッドによって既に取得されているかどうかに関係なく、メッセージ全体を取得する。


DirectPlayMessage.GetMessageSize

DirectPlayMessage.GetMessageSize メソッドは、メッセージのサイズを取得する。

object.GetMessageSize() As Long

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージのサイズをバイト単位で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.MoveToSecureMessage

DirectPlayMessage.MoveToSecureMessage は、保証メッセージ内で、読み取りポインタをメッセージ データの最初の部分に移動する。

object.MoveToSecureMessage()

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

保証システム メッセージは、メッセージのタイプ (DPSYS_SECUREMESSAGE) を示す Long、フラグを示す Long、メッセージを発信したプレーヤーの ID を示す Long、およびメッセージ データへのポインタで構成される。MoveToSecureMessage メソッドは、読み取りポインタをデータの開始部分に移動し、DirectPlayMessage.ReadLong などほかのメソッドを使用して、データを解析できるようにする。

参照

CONST_DPSYSMSGTYPES


DirectPlayMessage.MoveToTop

DirectPlayMessage.MoveToTop メソッドは、メッセージ データの最初の部分に読み取りポインタを移動する。

object.MoveToTop()

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

DirectPlayMessage.ReadX メソッドのいずれかによってメッセージ データの要素を取得するたびに、読み取りポインタが進む。MoveToTop を使用すると、メッセージを最初から再度読み取ることができる。


DirectPlayMessage.ReadByte

DirectPlayMessage.ReadByte メソッドは、メッセージ データから Byte 型の値を読み取り、読み取りポインタを進める。

object.ReadByte() As Byte

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージの Byte 型の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.ReadDouble

DirectPlayMessage.ReadDouble メソッドは、メッセージ データから Double 型の値を読み取り、読み取りポインタを進める。

object.ReadDouble() As Double

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージの Double 型の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.ReadGuid

DirectPlayMessage.ReadGuid メソッドは、メッセージ データから GUID を読み取り、読み取りポインタを進める。

object.ReadGuid() As String

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

GUID を文字列形式で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectPlayMessage.ReadLong

DirectPlayMessage.ReadLong メソッドは、メッセージから Long 型の値を読み取り、読み取りポインタを進める。

object.ReadLong() As Long

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージの Long 型の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.ReadShort

DirectPlayMessage.ReadShort メソッドは、メッセージ データから Integer 型の値を読み取り、読み取りポインタを進める。

object.ReadShort() As Integer

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージの Integer 型の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.ReadSingle

DirectPlayMessage.ReadSingle メソッドは、メッセージ データから Single 型の値を読み取り、読み取りポインタを進める。

object.ReadSingle() As Single

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージの Single 型の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.ReadString

DirectPlayMessage.ReadString メソッドは、メッセージ データから文字列を読み取り、読み取りポインタを進める。

object.ReadString() As String

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージの文字列を返す。

エラー コード

敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.ReadSysChatString

DirectPlayMessage.ReadSysChatString メソッドは、DPSYS_CHAT メッセージから文字列を読み取る。

object.ReadSysChatString() As String

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージの文字列を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.ReadSysMsgConnection

DirectPlayMessage.ReadSysMsgConnection メソッドは、DPSYS_STARTSESSION メッセージから DirectPlayLobbyConnection オブジェクトを取得する。

object.ReadSysMsgConnection() As DirectPlayLobbyConnection

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

DirectPlayLobbyConnection オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.ReadSysMsgData

DirectPlayMessage.ReadSysMsgData メソッドは、DPSYS_CREATEPLAYERORGROUP メッセージ、DPSYS_DESTROYPLAYERORGROUP メッセージ、または DPSYS_SETPLAYERORGROUPDATA メッセージからデータを取得する。

object.ReadSysMsgData() As String

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

メッセージ データを含む文字列を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドを正しく呼び出すには、読み取りポインタがメッセージ内の正しい位置にある必要がある。たとえば、DPSYS_DESTROYPLAYERORGROUP メッセージを解析する場合は、まず DirectPlayMessage.ReadLong を 3 回呼び出して、メッセージのタイプ、プレーヤーのタイプ、およびプレーヤーの ID を取得する必要がある。ReadSysMsgData を呼び出すと、読み取りポインタは、メッセージ タイプの参照で記述されている次のフィールドに進む (「CONST_DPSYSMSGTYPES」を参照)。この点から考えると、このメソッドは、DirectPlayMessage.ReadSysChatString、DirectPlayMessage.ReadSysMsgConnection、および DirectPlayMessage.ReadSysMsgSessionDesc とは異なる。これらのメソッドは、メッセージの一部が取得済みかどうかに関係なくデータを取得し、読み取りポインタを進めない。


DirectPlayMessage.ReadSysMsgSessionDesc

DirectPlayMessage.ReadSysMsgSessionDesc メソッドは、DPSYS_SETSESSIONDESC システム メッセージからセッション記述を取得する。

object.ReadSysMsgSessionDesc() As DirectPlaySessionData

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。

戻り値

DirectPlaySessionData オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.SetMessageData

DirectPlayMessage.SetMessageData メソッドは、ユーザー定義型のデータをメッセージに書き込む。

object.SetMessageData(userDefinedType As Any, size As Long)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
userDefinedType
メッセージ データを含む型。このユーザー定義型のすべてのメンバは、文字列ではなく、数値型でなければならない。通常、この型の最初のメンバは、メッセージの種類を定義する Long 型の値である。
size
userDefinedType のバイト単位のサイズ。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

SetMessageData は、メッセージ全体の中身を設定する場合にのみ使用できる。1 つのメッセージに対して 2 回以上呼び出してはならず、またほかの書き込みメソッドと組み合わせて使用することはできない。このデータを取得するには、DirectPlayMessage.GetMessageData を使用する。

このメソッドは、上級ユーザーのみが使用するように推奨されている。ほとんどの場合は、DirectPlayMessage.WriteX メソッドを使用してメッセージ データを作成してから、対応する DirectPlayMessage.ReadX メソッドを使用してデータを読み込む方がよい。


DirectPlayMessage.WriteByte

DirectPlayMessage.WriteByte メソッドは、メッセージ データに Byte 型の値を書き込み、書き込みポインタを進める。

object.WriteByte(val As Byte)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
val
メッセージに書き込む値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.WriteDouble

DirectPlayMessage.WriteDouble メソッドは、Double 型の値をメッセージ データに書き込み、書き込みポインタを進める。

object.WriteDouble(val As Double)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
val
メッセージに書き込む値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.WriteGuid

DirectPlayMessage.WriteGUID メソッドは、GUID 文字列をメッセージ データに書き込み、書き込みポインタを進める。

object.WriteGUID(val As String)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
val
メッセージに書き込む値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectPlayMessage.WriteLong

DirectPlayMessage.WriteLong メソッドは、Long 型の値をメッセージ データに書き込み、書き込みポインタを進める。

object.WriteLong(val As Long)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
val
メッセージに書き込む値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.WriteShort

DirectPlayMessage.WriteShort メソッドは、Integer 型の値をメッセージ データに書き込み、書き込みポインタを進める。

object.WriteShort(val As Integer)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
val
メッセージに書き込む値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.WriteSingle

DirectPlayMessage.WriteSingle メソッドは、Single 型の値をメッセージ データに書き込み、書き込みポインタを進める。

object.WriteSingle(val As Single)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
val
メッセージに書き込む値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlayMessage.WriteString

DirectPlayMessage.WriteString メソッドは、String 型の値をメッセージ データに書き込み、書き込みポインタを進める。

object.WriteString(val As String)

パラメータ

object
DirectPlayMessage オブジェクトを表すオブジェクト式。
val
メッセージに書き込む値。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData

DirectPlaySessionData クラスは、セッションに関連する記述データを表す。このクラスのオブジェクトは、DirectPlay4.CreateSessionData メソッドによって返され、DirectPlay4.Open または DirectPlay4.SecureOpen に渡される。また、このクラスのオブジェクトは、セッション記述を設定および取得するために、ほかのさまざまなメソッドによって使用される。

DirectPlaySessionData クラスには、以下のメソッドがある。

データの取得 | GetCurrentPlayers
 | GetFlags
 | GetGuidApplication
 | GetGuidInstance
 | GetMaxPlayers
 | GetSessionName
 | GetSessionPassword
 | GetUser1
 | GetUser2
 | GetUser3
 | GetUser4
データの設定 | SetFlags
 | SetGuidApplication
 | SetGuidInstance
 | SetMaxPlayers
 | SetSessionName
 | SetSessionPassword
 | SetUser1
 | SetUser2
 | SetUser3
 | SetUser4

参照

DirectPlay4.GetSessionDesc、DirectPlay4.SetSessionDesc、DirectPlayLobbyConnection.GetSessionDesc、DirectPlayLobbyConnection.SetSessionDesc、DirectPlay4.GetDPEnumSessions、DirectPlayEnumSessions.GetItem


DirectPlaySessionData.GetCurrentPlayers

DirectPlaySessionData.GetCurrentPlayers メソッドは、セッション内のプレーヤーの現在の数を取得する。

object.GetCurrentPlayers() As Long

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。

戻り値

プレーヤーの現在の数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.GetFlags

DirectPlaySessionData.GetFlags メソッドは、セッションに対するフラグを取得する。

object.GetFlags() As Long

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。

戻り値

セッションを記述する、CONST_DPSESSIONFLAGS 列挙型のフラグを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.GetGuidApplication

DirectPlaySessionData.GetGuidApplication メソッドは、セッションを作成したアプリケーションの GUID を取得する。

object.GetGuidApplication() As String

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。

戻り値

アプリケーションの GUID を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.GetGuidInstance

DirectPlaySessionData.GetGuidInstance メソッドは、セッション インスタンスの GUID を取得する。

object.GetGuidInstance() As String

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。

戻り値

セッションが作成されたときに、アプリケーションによって割り当てられた GUID を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.GetMaxPlayers

DirectPlaySessionData.GetMaxPlayers メソッドは、セッションに参加可能なプレーヤーの最大数を取得する。

object.GetMaxPlayers() As Long

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。

戻り値

プレーヤーの最大数を返す。最大数が存在しない場合は、0 を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.GetSessionName

DirectPlaySessionData.GetSessionName メソッドは、セッションの名前を取得する。

object.GetSessionName() As String

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。

戻り値

セッションの名前を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.GetSessionPassword

DirectPlaySessionData.GetSessionPassword メソッドは、セッションに対するパスワードを取得する。

object.GetSessionPassword() As String

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。

戻り値

セッションに参加するために必要なパスワードを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.GetUser1

「DirectPlaySessionData.GetUser(n)」を参照。


DirectPlaySessionData.GetUser2

「DirectPlaySessionData.GetUser(n)」を参照。


DirectPlaySessionData.GetUser3

「DirectPlaySessionData.GetUser(n)」を参照。


DirectPlaySessionData.GetUser4

「DirectPlaySessionData.GetUser(n)」を参照。


DirectPlaySessionData.GetUser(n)

DirectPlaySessionData.GetUser1 メソッド、DirectPlaySessionData.GetUser2 メソッド、DirectPlaySessionData.GetUser3 メソッド、およびDirectPlaySessionData.GetUser4 メソッドは、セッションに対するアプリケーション定義のデータを取得する。

object.GetUser1() As Long

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。

戻り値

アプリケーション定義のデータを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.SetFlags

DirectPlaySessionData.SetFlags メソッドは、セッションに対するフラグを設定する。

object.SetFlags(val As CONST_DPSESSIONFLAGS)

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。
val
セッションを記述する、CONST_DPSESSIONFLAGS 列挙型のフラグ。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.SetGuidApplication

DirectPlaySessionData.SetGuidApplication メソッドは、セッション記述内のアプリケーションの GUID を設定する。

object.SetGuidApplication(guid As String)

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。
guid
アプリケーションの GUID。このメンバに空の文字列を設定すると、任意のアプリケーションに対するセッションを列挙することができる。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.SetGuidInstance

DirectPlaySessionData.SetGuidInstance メソッドは、セッション インスタンスに対する GUID を設定する。

object.SetGuidInstance(guid As String)

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。
guid
セッションの GUID。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.SetMaxPlayers

DirectPlaySessionData.SetMaxPlayers メソッドは、セッションに参加可能なプレーヤーの最大数を設定する。

object.SetMaxPlayers(val As Long)

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。
val
プレーヤーの最大数。0 の場合、最大数は存在しない。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.SetSessionName

DirectPlaySessionData.SetSessionName メソッドは、セッションの名前を設定する。

object.SetSessionName(val As String)

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。
val
セッションの名前。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.SetSessionPassword

DirectPlaySessionData.SetSessionPassword メソッドは、セッションに対するパスワードを設定する。

object.SetSessionPassword(val As String)

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。
val
セッションに対するパスワード

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectPlaySessionData.SetUser1

「DirectPlaySessionData.SetUser(n)」を参照。


DirectPlaySessionData.SetUser2

「DirectPlaySessionData.SetUser(n)」を参照。


DirectPlaySessionData.SetUser3

「DirectPlaySessionData.SetUser(n)」を参照。


DirectPlaySessionData.SetUser4

「DirectPlaySessionData.SetUser(n)」を参照。


DirectPlaySessionData.SetUser(n)

DirectPlaySessionData.SetUser1 メソッド、DirectPlaySessionData.SetUser2 メソッド、DirectPlaySessionData.SetUser3 メソッド、および DirectPlaySessionData.SetUser4 メソッドは、セッションに対するアプリケーション定義のデータを設定する。

object.SetUser1(val As Long)

パラメータ

object
DirectPlaySessionData オブジェクトを表すオブジェクト式。
val
アプリケーション定義のデータ。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


型

ここでは、DirectPlay 用に定義されている以下の型に関するリファレンスを提供する。

  • DPAPPLICATIONDESC2
  • DPCAPS
  • DPCREDENTIALS
  • DPSECURITYDESC


DPAPPLICATIONDESC2

DPAPPLICATIONDESC2 型は、DirectPlayLobby3.RegisterApplication メソッドを使用して登録されるアプリケーションに関する情報を含んでいる。

Type DPAPPLICATIONDESC2
    lFlags As Long
    strAppLauncherName As String
    strApplicationName As String
    strCommandLine As String
    strCurrentDirectory As String
    strDescription As String
    strFilename As String
    strGuid As String
    strPath As String
End Type

メンバ

lFlags
使用しない。0 にすること。
strAppLauncherName
ランチャの実行可能ファイルの名前。ランチャは、ロビーによって開始され、strApplicationName で記述されるアプリケーションを起動する役目を果たす。ランチャは、アプリケーションと同じディレクトリに存在していなければならない。
strApplicationName
アプリケーションの名前。このタイトルをローカライズしないこと。アプリケーション名をローカライズする場合は、strDescription メンバを使用する。
strCommandLine
ロビーによって起動されたときに実行可能ファイルに渡される、コマンドライン引数。
strCurrentDirectory
カレント ディレクトリを設定するパス。
strDescription
アプリケーションの、ローカライズされた記述。DirectPlayLobby3.GetDPEnumLocalApplications を呼び出すと、この文字列が返される。
strFilename
起動する実行可能ファイルの名前。注 : ロビーから起動する場合は、スタブの実行可能ファイルの使用は避けるべきである。ロビーから起動するシナリオでは、スタブをバイパスし、メインの実行可能ファイルを起動すべきである。
strGuid
アプリケーションのグローバル ユニーク識別子 (GUID)。これは、ゲーム セッションをホストする場合には、DirectPlaySessionData.SetGuidApplication によって設定される値と同じである必要がある。
strPath
実行可能ファイルが存在するパス。


DPCAPS

DPCAPS 型は、DirectPlay4.GetCaps メソッドまたは DirectPlay4.GetPlayerCaps メソッドを呼び出した後に、DirectPlay オブジェクトの能力を保持する。保証付きまたは保証なしのどちらの能力を必要としているかに応じて、これらの能力の任意のものを変更することができる。

Type DPCAPS
    lFlags As Long
    lHeaderLength As Long
    lHundredBaud As Long
    lLatency As Long
    lMaxBufferSize As Long
    lMaxLocalPlayers As Long
    lMaxPlayers As Long
    lMaxQueueSize As Long
    lTimeout As Long
End Type

メンバ

lFlags
DirectPlay オブジェクトのプロパティを示す、CONST_DPCAPSFLAGS 列挙型のメンバ。DPCAPS_ASYNCSUPPORTED フラグ、DPCAPS_SENDTIMEOUTSUPPORTED フラグ、DPCAPS_SENDPRIORITYSUPPORTED フラグ、DPCAPS_ASYNCCANCELSUPPORTED フラグ、および DPCAPS_ASYNCCANCELALLSUPPORTED フラグは、現在のセッションの通信能力を示す。
lHeaderLength
この DirectPlay オブジェクトによってプレーヤー メッセージに追加されるヘッダーの、バイト単位のサイズ。このヘッダー サイズは、使用するサービス プロバイダによって異なる。
lHundredBaud
1 秒あたりの帯域幅を 100 ビットの倍数で示す。たとえば、この値が 24 の場合は、2400 ビット/秒を示す。
lLatency
サービス プロバイダによる推定の遅延時間をミリ秒単位で指定する。この値が 0 の場合、DirectPlay は遅延時間を推定できない。サービス プロバイダによっては、メッセージ サイズの平均を考慮し、アプリケーション間テストに基づいた精度になる。遅延時間は、アプリケーションで保証付きまたは保証なしのどちらのメッセージ配信を利用するかによって異なる場合がある。
lMaxBufferSize
このサービス プロバイダが 1 つのパケットで送信できるバイト数。これより大きなメッセージは、2 つ以上のパケットを使用して送信される。
lMaxLocalPlayers
セッションでサポートされるローカル プレーヤーの最大数。
lMaxPlayers
この DirectPlay オブジェクトにより、セッション内でサポートされるローカル プレーヤーとリモート プレーヤーの最大数。
lMaxQueueSize
使用されない。
lTimeout
サービス プロバイダが提案するタイムアウト値。デフォルトでは、DirectPlay はメッセージへの応答を待機するときに、このタイムアウト値を使用する。

注意

DirectPlay4.SendEx メソッドのどの要素がサポートされているかを示す能力 (lFlags の DPCAPS_SENDPRIORITYSUPPORTED フラグ、DPCAPS_SENDTIMEOUTSUPPORTED フラグなど) は、セッションが開いた後でなければ利用できない。

SendEx で DPSEND_ASYNC を使用するには、以下の条件のいずれかまたは両方が真でなければならない。

  • セッションを作成するときに、DPSESSION_DIRECTPLAYPROTOCOL フラグを設定した。
  • サービス プロバイダが、非同期メッセージングをサポートしている。

つまり、モデム、シリアル、および IPX (Internetwork Packet Exchange) のサービス プロバイダでは、保証メッセージングを利用できるが、DPSESSION_DIRECTPLAYPROTOCOL フラグを明示的に設定しなければ、非同期メッセージングを実行できないということである。TCP/IP サービス プロバイダは、コンピュータに Windows Sockets 2.0 が存在する場合に、非同期メッセージングを実装する。

セッションをホストしているアプリケーションが DirectPlaySessionData オブジェクトで DPSESSION_DIRECTPLAYPROTOCOL フラグを設定した場合、SendEx のすべてのオプションがサポートされる。


DPCREDENTIALS

DPCREDENTIALS 型は、保証サーバーに接続するためのユーザーのドメイン、パスワード、および名前を含む。

Type DPCREDENTIALS
    lFlags As Long
    strDomain As String
    strPassword As String
    strUsername As String
End Type

メンバ

lFlags
使用しない。0 に設定すること。
strDomain、strPassword、strUsername
ユーザーのドメイン、パスワード、および名前を含む ANSI 文字列。


DPSECURITYDESC

DPSECURITYDESC 型は、DirectPlay セッションのインスタンスのセキュリティ プロパティを記述する。

Type DPSECURITYDESC
    lCAPIProviderType As Long
    lEncryptionAlgorithm As Long
    lFlags As Long
    strCAPIProvider As String
    strSSPIProvider As String
End Type

メンバ

lCAPIProviderType
CryptoAPI サービス プロバイダ タイプ。デフォルトのタイプ PROV_RSA_FULL を使用する場合は、0 を渡す。
lEncryptionAlgorithm
使用する暗号化アルゴリズム。DirectPlay は、ストリーム サイファだけをサポートする。デフォルトの CALG_RC4 ストリーム サイファを使用する場合は、0 を渡す。
lFlags
使用しない。0 を設定すること。
strCAPIProvider
暗号化サービスのために使用する CryptoAPI パッケージを記述する、Unicode または ANSI の文字列。デフォルトの Microsoft RSA Base Cryptographic Provider 1.0 を使用する場合は、NULL を渡す。
strSSPIProvider
認証ログオンに使用する Security Support Provider Interface (SSPI) パッケージを記述する、Unicode または ANSI の文字列。デフォルトの NTLM セキュリティ プロバイダを使用する場合は、NULL を渡す。


列挙型

ここでは、DirectPlay for Visual Basic で使用する以下の列挙型に関するリファレンスを提供する。

  • CONST_DPCAPSFLAGS
  • CONST_DPCONNECTFLAGS
  • CONST_DPENUMCONNECTIONFLAGS
  • CONST_DPENUMGROUPFLAGS
  • CONST_DPENUMPLAYERFLAGS
  • CONST_DPENUMSESSIONFLAGS
  • CONST_DPGETCAPSFLAGS
  • CONST_DPGETFLAGS
  • CONST_DPGROUPFLAGS
  • CONST_DPIDFLAGS
  • CONST_DPLAYERR
  • CONST_DPLCONNECTIONFLAGS
  • CONST_DPLMSG
  • CONST_DPLWAIT
  • CONST_DPMESSAGEQUEUEFLAGS
  • CONST_DPOPENFLAGS
  • CONST_DPPLAYERFLAGS
  • CONST_DPPLAYERTYPEFLAGS
  • CONST_DPRECEIVEFLAGS
  • CONST_DPSENDFLAGS
  • CONST_DPSESSIONFLAGS
  • CONST_DPSETFLAGS
  • CONST_DPSYSMSGTYPES


CONST_DPCAPSFLAGS

CONST_DPCAPSFLAGS 列挙型の定数は、DirectPlay オブジェクトの能力を指定するために、DPCAPS 型で使用される。

Enum CONST_DPCAPSFLAGS
    DPCAPS_ASYNCCANCELALLSUPPORTED = 8192 (&H2000)
    DPCAPS_ASYNCCANCELSUPPORTED =    4096 (&H1000)
    DPCAPS_ASYNCSUPPORTED =         65536 (&H10000)
    DPCAPS_ENCRYPTIONSUPPORTED =      256 (&H100)
    DPCAPS_GROUPOPTIMIZED =             8
    DPCAPS_GUARANTEEDOPTIMIZED =       32 (&H20)
    DPCAPS_GUARANTEEDSUPPORTED =       64 (&H40)
    DPCAPS_ISHOST =                     2
    DPCAPS_KEEPALIVEOPTIMIZED =        16 (&H10)
    DPCAPS_SENDPRIORITYSUPPORTED =  32768 (&H8000)
    DPCAPS_SENDTIMEOUTSUPPORTED =   16384 (&H4000)
    DPCAPS_SIGNINGSUPPORTED =         128 (&H80)
End Enum
DPCAPS_ASYNCCANCELALLSUPPORTED
保留中のすべての非同期メッセージのキャンセルをサポートしている。このフラグは、サポートされているキャンセルの形式が、送信されていないすべてのメッセージのキャンセルであることを示している。優先順位の範囲またはメッセージ ID を指定してメッセージをキャンセルすると、DPERR_UNSUPPORTED が返される。一方、DPCAPS_ASYNCCANCELSUPPORTED フラグは、すべての種類のキャンセルがサポートされていることを示す。SendEx のどの要素がサポートされているかを示す能力は、セッションが開いてからでなければ利用できない。
DPCAPS_ASYNCCANCELSUPPORTED
非同期メッセージのキャンセルをサポートしている。メッセージ ID によるキャンセル、優先順位の範囲によるキャンセル、送信されていないすべてのメッセージのキャンセルなど、すべての種類のキャンセルがサポートされている。SendEx のどの要素がサポートされているかを示す能力は、セッションが開いてからでなければ利用できない。
DPCAPS_ASYNCSUPPORTED
非同期メッセージングをサポートしている。そのため、アプリケーションでは、SendEx で DPSEND_ASYNC フラグを使用できる。SendEx のどの要素がサポートされているかを示す能力は、セッションが開いてからでなければ利用できない。
DPCAPS_ENCRYPTIONSUPPORTED
この DirectPlay オブジェクトは、メッセージの暗号化をサポートしている。これは、セッションが保証セッションであるか、またはサービス プロバイダがメッセージを暗号化できるためである。
DPCAPS_GROUPOPTIMIZED
この DirectPlay オブジェクトに結合しているサービス プロバイダは、グループ (マルチキャスト) メッセージングを最適化できる。
DPCAPS_GUARANTEEDOPTIMIZED
この DirectPlay オブジェクトに結合しているサービス プロバイダは、保証メッセージ配信をサポートしている。
DPCAPS_GUARANTEEDSUPPORTED
この DirectPlay オブジェクトは、保証メッセージ配信をサポートする。これは、サービス プロバイダが保証メッセージ配信をサポートしているか、または DirectPlay がそれを保証なしのサービス プロバイダ上で実装するためである。
DPCAPS_ISHOST
呼び出し側のアプリケーションによって作成された DirectPlay オブジェクトは、セッションのホストである。
DPCAPS_KEEPALIVEOPTIMIZED
このサービス プロバイダは、セッションへの接続が解除されたタイミングを把握することができる。
DPCAPS_SENDPRIORITYSUPPORTED
SendEx で設定されるメッセージの優先順位をサポートする。SendEx のどの要素がサポートされているかを示す能力は、セッションが開いてからでなければ利用できない。
DPCAPS_SENDTIMEOUTSUPPORTED
SendEx で指定されるメッセージのタイムアウトをサポートする。このフラグを設定できるのは、サービス プロバイダまたは DirectPlay である。SendEx のどの要素がサポートされているかを示す能力は、セッションが開いてからでなければ利用できない。
DPCAPS_SIGNINGSUPPORTED
この DirectPlay オブジェクトは、メッセージの認証をサポートする。これは、このオブジェクトが保証セッションをサポートしているか、またはサービス プロバイダが署名を添付できるからである。


CONST_DPCONNECTFLAGS

CONST_DPCONNECTFLAGS 列挙型のメンバは、メソッドが戻るタイミングを指定するために、DirectPlayLobby3.Connect メソッドで使用される。

Enum CONST_DPCONNECTFLAGS
    DPCONNECTION_DEFAULT =        0
    DPCONNECTION_RETURNSTATUS = 128 (&H80)
End Enum
DPCONNECTION_DEFAULT
メソッドは、接続が確立されるか、または操作がタイムアウトになった後で戻る。
DPCONNECTION_RETURNSTATUS
メソッドは、接続の状態と共に直ちに戻る。


CONST_DPENUMCONNECTIONFLAGS

CONST_DPENUMCONNECTIONFLAGS 列挙型のメンバは、列挙する接続の種類を指定するために、DirectPlay4.GetDPEnumConnections メソッドで使用される。

Enum CONST_DPENUMCONNECTIONFLAGS
    DPCONNECTION_DIRECTPLAY = 1
    DPCONNECTION_DIRECTPLAYLOBBY = 2
End Enum
DPCONNECTION_DIRECTPLAY
アプリケーション セッションで通信するための、DirectPlay サービス プロバイダを列挙する。
DPCONNECTION_DIRECTPLAYLOBBY
ロビー サーバーと通信するための、DirectPlay ロビー プロバイダを列挙する。


CONST_DPENUMGROUPFLAGS

CONST_DPENUMGROUPFLAGS 列挙型のメンバは、列挙するグループの種類を指定するために、DirectPlay4.GetDPEnumGroups メソッドおよび DirectPlay4.GetDPEnumGroupsInGroup メソッドで使用される。

Enum CONST_DPENUMGROUPFLAGS
    DPENUMGROUPS_ALL =            0
    DPENUMGROUPS_HIDDEN =      4096 (&H1000)
    DPENUMGROUPS_LOCAL =          8
    DPENUMGROUPS_REMOTE =        16 (&H10)
    DPENUMGROUPS_SESSION =      128 (&H80)
    DPENUMGROUPS_SHORTCUT =    1024 (&H400)
    DPENUMGROUPS_STAGINGAREA = 2048 (&H800)
End Enum
DPENUMGROUPS_ALL
すべてのグループを列挙する。
DPENUMGROUPS_HIDDEN
グループ内の現在利用可能な隠れグループを列挙する。GetDPEnumGroupsInGroup でのみ有効である。
DPENUMGROUPS_LOCAL
この DirectPlay オブジェクトによってローカルに作成されたグループを列挙する。
DPENUMGROUPS_REMOTE
リモートの DirectPlay オブジェクトによって作成されたグループを列挙する。
DPENUMGROUPS_SESSION
sessionGuid パラメータで指定されるセッション内で列挙を実行する。このフラグは、現在アクティブなセッションが存在しない場合にのみ使用でき、ロビー セッションでは使用できない。
DPENUMGROUPS_SHORTCUT
DirectPlay4.AddGroupToGroup を使用してグループに追加されたショートカットであるグループを列挙する (ショートカットは、別のグループへのリンクである)。GetDPEnumGroupsInGroup でのみ有効である。
DPENUMGROUPS_STAGINGAREA
ステージング領域であるグループを列挙する (ステージング領域は、新しいセッションを起動する際に、プレーヤーを配置するために利用される)。


CONST_DPENUMPLAYERFLAGS

CONST_DPENUMPLAYERFLAGS 列挙型のメンバは、列挙するプレーヤーの種類を指定するために、DirectPlay4.GetDPEnumPlayers メソッドおよび DirectPlay4.GetDPEnumGroupPlayers メソッドで使用される。

Enum CONST_DPENUMPLAYERFLAGS
    DPENUMPLAYERS_ALL =            0
    DPENUMPLAYERS_GROUP =         32 (&H20)
    DPENUMPLAYERS_LOCAL =          8
    DPENUMPLAYERS_OWNER =       8192 (&H2000)
    DPENUMPLAYERS_REMOTE =        16 (&H10)
    DPENUMPLAYERS_SERVERPLAYER = 200 (&H100)
    DPENUMPLAYERS_SESSION =      128 (&H80)
    DPENUMPLAYERS_SPECTATOR =    512 (&H200)
End Enum
DPENUMPLAYERS_ALL
このセッションのすべてのプレーヤー。
DPENUMPLAYERS_GROUP
グループ。
DPENUMPLAYERS_LOCAL
この DirectPlay オブジェクトによってローカルに作成されたプレーヤー。
DPENUMPLAYERS_OWNER
グループの所有者。
DPENUMPLAYERS_REMOTE
リモートの DirectPlay オブジェクトによって作成されたプレーヤー。
DPENUMPLAYERS_SERVERPLAYER
サーバー プレーヤー。
DPENUMPLAYERS_SESSION
sessionGuid によって指定されるセッションのプレーヤー。このフラグは、現在開いているセッションが存在しない場合にのみ、使用できる。
DPENUMPLAYERS_SPECTATOR
観客プレーヤー。


CONST_DPENUMSESSIONFLAGS

CONST_DPENUMSESSIONFLAGS 列挙型のメンバは、列挙するセッションを指定するために、DirectPlay4.GetDPEnumSessions メソッドで使用される。

Enum CONST_DPENUMSESSIONFLAGS
    DPENUMSESSIONS_ALL =               2
    DPENUMSESSIONS_ASYNC =            16 (&H10)
    DPENUMSESSIONS_AVAILABLE =         1
    DPENUMSESSIONS_PASSWORDREQUIRED = 64 (&H40)
    DPENUMSESSIONS_RETURNSTATUS =    128 (&H80)
    DPENUMSESSIONS_STOPASYNC =        16 (&H10)
End Enum
DPENUMSESSIONS_ALL
セッションが新しいプレーヤーを受け入れるかどうかに関係なく、すべてのアクティブ セッションを列挙する。プレーヤーの限度に達しているセッション、新しいプレーヤーを無効にしているセッション、または参加を無効にしているセッションも列挙される。パスワードで保護されたセッションは、DPENUMSESSIONS_PASSWORDREQUIRED フラグも指定されている場合を除いて、列挙されない。
DPENUMSESSIONS_ASYNC
セッション キャッシュ内の現在のセッションをすべて列挙し、直ちに戻る。非同期列挙処理がまだ始まっていない場合は、それを開始する。セッション リストの更新は、DPENUMSESSIONS_STOPASYNC フラグを設定して GetDPEnumSessions を呼び出すか、または DirectPlay4.Open を呼び出すまで、継続する。

このフラグを指定しない場合、列挙は非同期で行われる。

DPENUMSESSIONS_AVAILABLE
新しいプレーヤーの参加を受け入れるセッションをすべて列挙する。プレーヤーの限度に達しているセッション、新しいプレーヤーを無効にしているセッション、または参加を無効にしているセッションは列挙されない。パスワードで保護されたセッションは、DPENUMSESSIONS_PASSWORDREQUIRED フラグも指定されている場合を除いて、列挙されない。
DPENUMSESSIONS_PASSWORDREQUIRED
DPENUMSESSIONS_AVAILABLE または DPENUMSESSIONS_ALL と組み合わせて使用すると、パスワードで保護されたセッションが、パスワードで保護されていないセッションと共に列挙される。
DPENUMSESSIONS_RETURNSTATUS
このフラグを指定すると、列挙時に、接続の進行状況を示すダイアログ ボックスが表示されない。接続を直ちに確立できない場合は、DPERR_CONNECTING エラーを返す。アプリケーションでは、メソッドが成功するか、またはほかのエラー コードが返されるまで、GetDPEnumSessions を呼び出し続ける必要がある。
DPENUMSESSIONS_STOPASYNC
セッション キャッシュ内の現在のセッションをすべて列挙し、非同期の列挙処理をキャンセルする。


CONST_DPGETCAPSFLAGS

CONST_DPGETCAPSFLAGS 列挙型のメンバは、DirectPlay およびプレーヤーの能力を示すために利用される。これらのフラグは、DirectPlay4.GetCaps メソッドおよび DirectPlay4.GetPlayerCaps メソッドによって返される。

Enum CONST_DPGETCAPSFLAGS
    DPGETCAPS_DEFAULT =    0
    DPGETCAPS_GUARANTEED = 1
End Enum
DPGETCAPS_DEFAULT
保証なしのメッセージングに対する能力。
DPGETCAPS_GUARANTEED
保証付きのメッセージングに対する能力。


CONST_DPGETFLAGS

CONST_DPGETFLAGS 列挙型のメンバは、DirectPlay4.GetGroupData メソッドおよび DirectPlay4.GetPlayerData メソッドによって返されるデータを決めるために使用される。

Enum CONST_DPGETFLAGS
    DPGET_LOCAL = 1
    DPGET_REMOTE = 0
End Enum
DPGET_LOCAL
このアプリケーションによって設定されたローカル データを取得する。
DPGET_REMOTE
リモートの共有データ空間から現在のデータを取得する。

参照

CONST_DPSETFLAGS


CONST_DPGROUPFLAGS

Members of the CONST_DPGROUPFLAGS 列挙型のメンバは、作成するグループの種類を指定するために、DirectPlay4.CreateGroup メソッドと DirectPlay4.CreateGroupInGroup メソッドで使用される。これらのメンバは、DirectPlay4.GetGroupFlags メソッドによって返される。

Enum CONST_DPGROUPFLAGS
    DPGROUP_DEFAULT =        0
    DPGROUP_HIDDEN =      4096 (&H1000)
    DPGROUP_LOCAL =          8
    DPGROUP_STAGINGAREA = 2048 (&H800)
End Enum
DPGROUP_DEFAULT
グループは、以下の特性をいずれも持たない。
DPGROUP_HIDDEN
グループは隠されている。ロビー セッションでは、隠しグループを利用するには、DirectPlay4.AddGroupToGroup によって作成されたショートカットを使用する必要がある。このフラグは、プレーヤーに対する DPPLAYER_SPECTATOR フラグと同じように機能する。
DPGROUP_LOCAL
グループは、このアプリケーションによって作成された。このグループを指定しない場合、グループはリモート グループである。
DPGROUP_STAGINGAREA
グループは、ステージング領域である。ステージング領域は、新しいセッションを開始する際に、プレーヤーを配置するために利用される。


CONST_DPIDFLAGS

CONST_DPIDFLAGS 列挙型のメンバは、特別なプレーヤー ID に対して使用される。

Enum CONST_DPIDFLAGS
    DPID_ALLPLAYERS   = 0
    DPID_SERVERPLAYER = 1
    DPID_SYSMSG       = 0
    DPID_UNKNOWN     = -1 (&HFFFFFFFF)
End Enum
DPID_ALLPLAYERS
すべてのプレーヤーに送信されたメッセージを識別する。
DPID_SERVERPLAYER
サーバー プレーヤーを識別する。この ID は、DirectPlay4.CreatePlayer で DPPLAYER_SERVERPLAYER フラグを設定して作成されたプレーヤーに対して割り当てられる。
DPID_SYSMSG
システムによって送信されたメッセージを識別する。
DPID_UNKNOWN
メッセージの送信者または受信者が不明である。


CONST_DPLAYERR

CONST_DPLAYERR 列挙型のメンバは、DirectPlay のエラー コードを表す。


CONST_DPLCONNECTIONFLAGS

CONST_DPLCONNECTIONFLAGS 列挙型のメンバは、DirectPlayLobbyConnection オブジェクトのフラグで使用される。

Enum CONST_DPLCONNECTIONFLAGS
    DPLCONNECTION_CREATESESSION = 2
    DPLCONNECTION_JOINSESSION =   1
End Enum
DPLCONNECTION_CREATESESSION
セッション記述で記述されているとおりに、新しいセッションを作成する。
DPLCONNECTION_JOINSESSION
セッション記述で記述されているとおりに、既存のセッションに参加する。

参照

DirectPlayLobbyConnection.GetFlags、DirectPlayLobbyConnection.SetFlags


CONST_DPLMSG

CONST_DPLMSG 列挙型は、ロビーに送信されるメッセージと、ロビーから送信されるメッセージを識別するために使用される。

Enum CONST_DPLMSG
    DPLMSG_STANDARD =    2
    DPLMSG_SYSTEM =      1
    DPLMSG_USERDEFINED = 0
End Enum
DPLMSG_STANDARD
DirectPlay で定義されたメッセージである。この種のメッセージの処理はオプションである。
DPLMSG_SYSTEM
DirectPlay によって生成されたシステム メッセージである。このメッセージは、ロビーに起動されたアプリケーションの立場で、ロビーに変更を通知するために利用される。
DPLMSG_USERDEFINED
メッセージは、アプリケーションによって定義されている。

参照

DirectPlayLobby3.ReceiveLobbyMessage、DirectPlayLobby3.SendLobbyMessage


CONST_DPLWAIT

CONST_DPLWAIT 列挙型は、DirectPlayLobby3.WaitForConnectionSettings メソッドで使用される。

Enum CONST_DPLWAIT
    DPLWAIT_CANCEL =  1
    DPLWAIT_DEFAULT = 0
End Enum
DPLWAIT_CANCEL
メソッドは、アプリケーションを待機モードから解除する。
DPLWAIT_DEFAULT
メソッドは、アプリケーションを待機モードに設定する。


CONST_DPMESSAGEQUEUEFLAGS

CONST_DPMESSAGEQUEUEFLAGS 列挙型のメンバは、DirectPlay4.GetMessageQueue メソッドで使用される。

Enum CONST_DPMESSAGEQUEUEFLAGS
    DPMESSAGEQUEUE_RECEIVE = 2
    DPMESSAGEQUEUE_SEND =    1
End Enum
DPMESSAGEQUEUE_RECEIVE
受信キューに関するメッセージを取得する。
DPMESSAGEQUEUE_SEND
送信キューに関するメッセージを取得する。


CONST_DPOPENFLAGS

CONST_DOPENFLAGS 列挙型のメンバは、セッションを開く方法を指定するために、DirectPlay4.Open メソッドと DirectPlay4.SecureOpen メソッドで使用される。

Enum CONST_DOPENFLAGS
    DPOPEN_CREATE =         2
    DPOPEN_JOIN =           1
    DPOPEN_RETURNSTATUS = 128 (&H80)
End Enum
DPOPEN_CREATE
アプリケーション セッションの新しいインスタンスを作成する。ローカル コンピュータは、セッションのネーム サーバーおよびホストになる。
DPOPEN_JOIN
アプリケーション セッションの既存のインスタンスに参加する。アプリケーションでは、プレーヤーを作成し、メッセージを送受信できるようになる。DPOPEN_CREATE と組み合わせて使用することはできない。
DPOPEN_RETURNSTATUS
このフラグを指定すると、接続の進行状況を示すダイアログ ボックスが表示されない。接続を直ちに確立できない場合は、メソッドが DPERR_CONNECTING エラーと共に直ちに戻る。アプリケーションでは、メソッドが成功するか、またはほかのエラー コードが返されるまで、メソッドを呼び出し続ける必要がある。


CONST_DPPLAYERFLAGS

CONST_DPPLAYERFLAGS 列挙型のメンバは、DirectPlay4.CreatePlayer メソッドでプレーヤーに割り当てられ、DirectPlay4.GetPlayerFlags を使用して取得することができる。

Enum CONST_DPPLAYERFLAGS
    DPPLAYER_LOCAL          = 8
    DPPLAYER_SERVERPLAYER = 256 (&H100)
    DPPLAYER_SPECTATOR    = 512 (&H200)
End Enum
DPPLAYER_LOCAL
プレーヤーは、このアプリケーションによって作成された。このフラグを指定しない場合、プレーヤーはリモート プレーヤーである。
DPPLAYER_SERVERPLAYER
プレーヤーは、クライアント/サーバー通信のサーバー プレーヤーである。
DPPLAYER_SPECTATOR
プレーヤーは、観客として作成された。


CONST_DPPLAYERTYPEFLAGS

CONST_DPPLAYERTYPEFLAGS 列挙型のメンバは、項目がプレーヤーまたはグループのどちらに属するかを示すために、DirectPlayEnumPlayers オブジェクトと、さまざまなシステム メッセージで使用される。

Enum CONST_DPPLAYERTYPEFLAGS
    DPPLAYERTYPE_GROUP =  0
    DPPLAYERTYPE_PLAYER = 1
End Enum
DPPLAYERTYPE_GROUP
項目は、グループに属する。
DPPLAYERTYPE_PLAYER
項目は、プレーヤーに属する。


CONST_DPRECEIVEFLAGS

CONST_DPRECEIVEFLAGS 列挙型のメンバは、取得するメッセージの種類と取得方法を指定するために使用される。

Enum CONST_DPRECEIVEFLAGS
    DPRECEIVE_ALL =        1
    DPRECEIVE_FROMPLAYER = 4
    DPRECEIVE_PEEK =       8
    DPRECEIVE_TOPLAYER =   2
End Enum

これらの値の意味については、DirectPlay4.Receive を参照すること。


CONST_DPSENDFLAGS

CONST_DPSENDFLAGS 列挙型のメンバは、メッセージの送信方法を制御するために使用される。

Enum CONST_DPSENDFLAGS
    DPSEND_ASYNC =              512 (&H200)
    DPSEND_DEFAULT =              0
    DPSEND_ENCRYPTED =           64 (&H40)
    DPSEND_GUARANTEED =           1
    DPSEND_NOSENDCOMPLETEMSG = 1024 (&H400)
    DPSEND_SIGNED =              32 (&H20)
End Enum

これらの値の意味については、「DirectPlay4.Send」および「DirectPlay4.SendEx」を参照すること。


CONST_DPSESSIONFLAGS

CONST_DPSESSIONFLAGS 列挙型のメンバは、セッションの特性を記述するために使用される。

Enum CONST_DPSESSIONFLAGS
    DPSESSION_CLIENTSERVER       = 4096 (&H1000)
    DPSESSION_DIRECTPLAYPROTOCOL = 8192 (&H2000)
    DPSESSION_JOINDISABLED         = 32 (&H20)
    DPSESSION_KEEPALIVE            = 64 (&H40)
    DPSESSION_MIGRATEHOST           = 4
    DPSESSION_MULTICASTSERVER    = 2048 (&H800)
    DPSESSION_NEWPLAYERSDISABLED    = 1
    DPSESSION_NODATAMESSAGES      = 128 (&H80)
    DPSESSION_NOMESSAGEID           = 8
    DPSESSION_NOPRESERVEORDER   = 16384 (&H4000)
    DPSESSION_OPTIMIZELATENCY   = 32768 (&H8000)
    DPSESSION_PASSWORDREQUIRED   = 1024 (&H400)
    DPSESSION_PRIVATE             = 512 (&H200)
    DPSESSION_SECURESERVER        = 256 (&H100)
End Enum
DPSESSION_CLIENTSERVER
アプリケーション-サーバー プロセスによってホストされる、クライアント/サーバー セッションである。このフラグは、セッションの作成時に指定する必要がある。サーバー プレーヤーと任意のローカル プレーヤーを列挙できるのは、このセッションに参加するクライアントだけである。セッションのホストは、すべてのプレーヤーを認識できる。このフラグを設定しない場合、セッションはピアツーピア セッションである。このフラグを設定した場合、サーバー プレーヤーを作成できるのはホストだけである。このフラグは、DPSESSION_MIGRATEHOST と共に使用することはできない。
DPSESSION_DIRECTPLAYPROTOCOL
このセッションでは、サービス プロバイダによって実装されたプロトコルではなく、DirectPlay の保証付きプロトコルを使用する必要がある。メッセージ スロットリング (およびそれによるパフォーマンスの向上) が必要な場合は、このフラグを使用する。
DPSESSION_JOINDISABLED
新しいアプリケーションは、このセッションに参加できない。DPOPEN_JOIN フラグと、このセッション インスタンスのグローバル ユニーク識別子 (GUID) を設定して DirectPlay4.Open メソッドを呼び出すと、エラーが発生する。このフラグを指定しない場合、新しいリモート アプリケーションは、セッションにおけるプレーヤーの限度に達するまで、そのセッションに参加できる。
DPSESSION_KEEPALIVE
このセッションは、リモート プレーヤーがゲームから不正に退出したことを、自動的に検出する。これらのプレーヤーは、セッションから削除される。ネットワークの一時的な障害によってプレーヤーが失われた場合、そのプレーヤーが戻ったときに、DPSYS_SESSIONLOST システム メッセージにより、セッションから抜けたことを知らされる。このフラグは、セッションの作成時に指定する必要がある。このフラグを設定しない場合、DirectPlay は、プレーヤーが不正に終了したときに、セッションを自動的には維持しない。
DPSESSION_MIGRATEHOST
現在のホストがセッションを抜けると、セッション内の別のコンピュータがホストになる。新しいホスト コンピュータ上のプレーヤーは、DPSYS_HOST システム メッセージを受信する。このフラグは、セッションの作成時に指定する必要がある。このフラグを指定しない場合、現在のホストがセッションを離れると、ホストは移行されず、新しいコンピュータはセッションに参加できず、新しいプレーヤーを作成することもできなくなる。DPSESSION_MIGRATEHOST フラグは、DPSESSION_CLIENTSERVER フラグ、DPSESSION_MULTICASTSERVER フラグ、または DPSESSION_SECURESERVER フラグと組み合わせて使用することはできない。
DPSESSION_MULTICASTSERVER
ピアツーピア セッションでは、ブロードキャストとグループ メッセージが、マルチキャスト サーバーのように機能するホストを介して送信される。このフラグは、セッションの作成時に指定する必要がある。このフラグは、ホストがネットワークに高い帯域幅で接続している場合にのみ、有効である。このフラグを指定しない場合、ブロードキャストとグループ メッセージは、ノード間で直接送信される。このフラグは、DPSESSION_MIGRATEHOST と共に使用することはできない。
DPSESSION_NEWPLAYERSDISABLED
セッション内で新しいプレーヤーを作成できない。セッション内のアプリケーションが DirectPlay4.CreatePlayer メソッドを呼び出すと、エラーが発生する。また、新しいアプリケーションがセッションに参加することもできない。このフラグを設定しない場合は、セッションにおけるプレーヤーの限度に達するまで、プレーヤーを作成することができる。
DPSESSION_NODATAMESSAGES
このセッションは、リモート プレーヤー データ、グループ データ、またはセッション データが、DirectPlay4.SetPlayerData メソッド、DirectPlay4.SetGroupData メソッド、DirectPlay4.SetPlayerName メソッド、DirectPlay4.SetGroupName メソッド、または DirectPlay4.SetSessionDesc メソッドのいずれかにより変更された場合に、システム メッセージを送信しない。このフラグを指定しない場合は、データの変更を示すメッセージが生成される。

このフラグを設定すると、DPSYS_SETSESSIONDESC システム メッセージも省略される。

DPSESSION_NOMESSAGEID
セッションが、メッセージを発信したプレーヤーとメッセージが送信されるプレーヤーを示すデータをメッセージに添付しないことを指定する。このフラグを設定すると、このメッセージが関係のないものである場合に、メッセージのオーバーヘッドを防ぐことができる。このフラグを指定しない場合、メッセージ ID が追加されるこのフラグは、セッションの作成時に指定する必要がある。
DPSESSION_NOPRESERVEORDER
このセッションが、保証付きのメッセージの受信順序を保存しないことを指定する。デフォルトでは、保証メッセージの受信順序は保存される。この順序が不要な場合は、このフラグを使用して、配信の遅れを防ぐことができる。
DPSESSION_OPTIMIZELATENCY
サービス プロバイダに、遅延時間に対して最適化するように要求する (これにより、TCP/IP のナグリングがオフになる)。デフォルトでは、帯域幅に対して最適化する。
DPSESSION_PASSWORDREQUIRED
このセッションが、パスワードで保護されていることを指定する。このセッションに参加するアプリケーションは、DirectPlay4.Open の呼び出しでパスワードを提供する必要がある。このフラグは、読み取り専用である。セッションのホストがパスワードを指定すると、自動的に設定される。
DPSESSION_PRIVATE
セッションが、プライベート セッションであることを指定する。要求に、NULL 以外の一致するパスワードが含まれている場合を除いて、列挙要求に応答することはできない。このフラグを指定しない場合、セッションは列挙要求に応答する。
DPSESSION_SECURESERVER
このセッションが、開く前に認証情報を要求する保証サーバー上でホストされていることを指定する。ホストは、セッションの作成時に、このフラグを指定する必要がある。このフラグは、後で DirectPlay4.SetSessionDesc によって変更することはできない。また、DPSESSION_MIGRATEHOST と組み合わせて使用することはできない。

注意

以下のフラグは、セッションの開始後には変更できない。

DPSESSION_CLIENTSERVER
DPSESSION_DIRECTPLAYPROTOCOL
DPSESSION_KEEPALIVE
DPSESSION_MIGRATEHOST
DPSESSION_MULTICASTSERVER
DPSESSION_NOMESSAGEID
DPSESSION_OPTIMIZELATENCY
DPSESSION_SECURESERVER

以下のフラグは、DirectPlay4.SetSessionDesc を使用して設定できる。ただし、それができるのはホストだけである。

DPSESSION_JOINDISABLED
DPSESSION_NEWPLAYERSDISABLED
DPSESSION_NODATAMESSAGES
DPSESSION_NOPRESERVEORDER
DPSESSION_PASSWORDREQUIRED
DPSESSION_PRIVATE


CONST_DPSETFLAGS

CONST_DPSETFLAGS 列挙型のメンバは、DirectPlay4.SetGroupData メソッド、DirectPlay4.SetGroupName メソッド、DirectPlay4.SetPlayerData メソッド、および DirectPlay4.SetPlayerName メソッドによって設定されるデータを決めるために使用される。

Enum CONST_DPSETFLAGS
    DPSET_GUARANTEED = 2
    DPSET_LOCAL = 1
    DPSET_REMOTE = 0
End Enum
DPSET_GUARANTEED
保証メッセージングを使用して (利用可能な場合)、データを伝承する。このフラグは、DPSET_LOCAL と組み合わせて使用することはできない。
DPSET_LOCAL
このデータは、ローカルにしか使用できず、伝承されない。
DPSET_REMOTE
このデータは、すべてのアプリケーションが利用でき、セッション内のほかのすべてのアプリケーションに伝承される。このフラグは、グループに対しては、ローカル セッションによって所有されているグループに対してのみ使用できる。

参照

CONST_DPGETFLAGS


CONST_DPSYSMSGTYPES

CONST_DPSYSMSGTYPES 列挙型のメンバは、システム メッセージとロビー メッセージの異なる種類を識別するために利用される。システム メッセージまたはロビー メッセージを表す各 DirectPlayMessage オブジェクトは、DirectPlayMessage.ReadLong の最初の呼び出しから、これらの定数のいずれかを返す。メッセージの種類を判断し、DirectPlayMessage のさまざまな読み取りメソッドを呼び出してデータを解析するのは、アプリケーションの役割である

DPLSYS_GETPROPERTY および DPLSYS_SETPROPERTY の 2 つのロビー メッセージは、システムではなく、アプリケーションによって送信される。アプリケーションでは、DirectPlayMessage の適切な書き込みメソッドを使用して、タイプ識別子と、管理する残りのデータを記述する必要がある。

アプリケーションでは、通常のシステム メッセージとロビー メッセージを分けて扱うことが重要である。一部のロビー メッセージと非ロビー メッセージは、同じ値を共有する (DPLSYS_SETPROPERTY と DPSYS_DESTROYPLAYERORGROUP など)。したがって、メッセージがロビー メッセージか非ロビー メッセージかを示す情報を使用せずに、すべてのメッセージを共通のハンドラに送るのは賢明ではない。

Enum CONST_DPSYSMSGTYPES
    DPLSYS_APPTERMINATED =          4
    DPLSYS_CONNECTIONSETTINGSREAD = 1
    DPLSYS_DPLAYCONNECTFAILED =     2
    DPLSYS_DPLAYCONNECTSUCCEEDED =  3
    DPLSYS_GETPROPERTY =            7
    DPLSYS_GETPROPERTYRESPONSE =    8
    DPLSYS_NEWCONNECTIONSETTINGS = 10
    DPLSYS_NEWSESSIONHOST =         9
    DPLSYS_SETPROPERTY =            5
    DPLSYS_SETPROPERTYRESPONSE  =   6
    DPSYS_ADDGROUPTOGROUP =       261 (&H105)
    DPSYS_ADDPLAYERTOGROUP =        7
    DPSYS_CHAT =                  265 (&H109)
    DPSYS_CREATEPLAYERORGROUP =     3
    DPSYS_DELETEGROUPFROMGROUP =  262 (&H106)
    DPSYS_DELETEPLAYERFROMGROUP =  33 (&H21)
    DPSYS_DESTROYPLAYERORGROUP =    5
    DPSYS_HOST =                  257 (&H101)
    DPSYS_SECUREMESSAGE =         263 (&H107)
    DPSYS_SENDCOMPLETE =          269 (&H10D)
    DPSYS_SESSIONLOST =            49 (&H31)
    DPSYS_SETGROUPOWNER =         266 (&H10A)
    DPSYS_SETPLAYERORGROUPDATA =  258 (&H102)
    DPSYS_SETPLAYERORGROUPNAME =  259 (&H103)
    DPSYS_SETSESSIONDESC =        260 (&H104)
    DPSYS_STARTSESSION =          264 (&H108)
End Enum

以下の記述には、各メッセージ タイプの余分なデータ メンバのリストが含まれている。これらは、基になる構造体で使用される順番に書かれている (基になる C/C++ 構造体の詳細については、「システム メッセージ」を参照すること)。ここでは、アプリケーションが ReadLong を使用して、既にメッセージ タイプを取得したものと仮定している。

メッセージ データが Long 型の値と、それに続く GUID で構成されている場合、アプリケーションでは、最初に DirectPlayMessage.ReadLong を呼び出し、次に DirectPlayMessage.ReadString を呼び出して、データを解析することができる。基になる構造体にバッファへのポインタが含まれている場合、DirectPlayMessage.ReadSysChatString などの特別なメソッドを使用して、バッファからデータを取得する必要がある。

標準ロビー メッセージ
DPLSYS_APPTERMINATED
DirectPlayLobby3.RunApplication によって開始されたアプリケーションが終了した。
GUID
ロビー メッセージを適用するセッションの一意の識別子。
DPLSYS_CONNECTIONSETTINGSREAD
DirectPlayLobby3.RunApplication によって開始されたアプリケーションが、接続設定を読み取った。
GUID
ロビー メッセージを適用するセッションの一意の識別子。
DPLSYS_DPLAYCONNECTFAILED
DirectPlayLobby3.RunApplication によって開始されたアプリケーションが、セッションへの接続に失敗した。
GUID
ロビー メッセージを適用するセッションの一意の識別子。
DPLSYS_DPLAYCONNECTSUCCEEDED
DirectPlayLobby3.RunApplication によって開始されたアプリケーションが、セッションを作成してほかのアプリケーションの参加を待機しているか、またはセッションへの参加に成功した。
GUID
ロビー メッセージを適用するセッションの一意の識別子。
DPLSYS_GETPROPERTY
アプリケーションからロビーに対し、プロパティの現在の値を要求するために送信されるメッセージ。
Long
要求を識別するアプリケーションによって生成される ID。ロビーの応答は、この ID に送信される。アプリケーションでは、この要求 ID を使用して、応答を保留中の要求に一致させることができる。
GUID
このプロパティが適用されるプレーヤーの一意な識別子 (適用される場合)。このプロパティがプレーヤーに固有のものではない場合、このメンバには空の文字列を設定する必要がある。
GUID
要求されているプロパティの一意な識別子。DirectPlay は、特定のプロパティを定義する。アプリケーションまたはロビーは、追加のプロパティに対する独自の GUID を定義することができる。詳細については、DirectPlay C++ リファレンスの「DirectPlay 定義済みプロパティ」を参照すること。
DPLSYS_GETPROPERTYRESPONSE
DPLSYS_GETPROPERTY メッセージに応答して、ロビーからアプリケーションに送信されるメッセージ。
Long
応答している要求の ID。
GUID
このプロパティが適用されるプレーヤーの一意な識別子。このプロパティがプレーヤーに固有のものでない場合は、このメンバには空の文字列を設定する。この値は、DPLSYS_GETPROPERTY メッセージで渡された値と同じである。
GUID
要求されているプロパティの一意な識別子。この値は、DPLSYS_GETPROPERTY メッセージで渡された値と同じである。
Long
プロパティを取得する要求に対する戻りコード。要求が成功した場合は 0、それ以外の場合は

DPERR_UNKNOWNMESSAGE または

DPERR_UNAVAILABLE のいずれかになる。

Long
データのサイズを示すバイト数。この値の後に、プロパティ データを含む可変サイズのバッファが続く。このプロパティ タグにより、このデータの読み取り方法と解釈方法が決まる。詳細については、DirectPlay C++ リファレンスの「DirectPlay 定義済みプロパティ」を参照すること。
DPLSYS_NEWCONNECTIONSETTINGS
ロビー システム メッセージ。ロビー クライアントが DirectPlayLobby3.RunApplication を呼び出すと、待機中のアプリケーションが見つかる。待機中のアプリケーションは、DirectPlayLobby3.GetConnectionSettings を使用して、接続設定を読み取ることができる。
GUID
ロビー メッセージを適用するセッションの一意の識別子。
DPLSYS_NEWSESSIONHOST
ロビーから、新たにセッションのホストになったアプリケーション インスタンスに送信されるメッセージ。
GUID
このインスタンスの、一意な識別子。
DPLSYS_SETPROPERTY
プロパティの値を設定するために、アプリケーションからロビーに送信されるメッセージ。
Long
要求を識別する、アプリケーションによって生成される ID。ロビーの応答は、この ID に送信される。アプリケーションでは、この要求 ID を使用して、応答を保留中の要求に一致させることができる。
GUID
このプロパティが適用されるプレーヤーの一意な識別子。このプロパティがプレーヤーに固有のものでない場合は、このメンバには空の文字列を設定する。
GUID
要求されているプロパティの一意な識別子。DirectPlay は、特定のプロパティを定義する。アプリケーションまたはロビーは、追加のプロパティに対する独自の GUID を定義することができる。
Long
データのサイズを示すバイト。この値の後に、プロパティ データを含む可変サイズのバッファが続く。このプロパティ タグにより、このデータの整理方法と書き込み方法が決まる。たとえば、DPLPROPERTY_PlayerScore プロパティの場合は、DirectPlayMessage.WriteLong を 1 回呼び出してスコアの数を記録し、各スコアに対してこのメソッドを再度呼び出す。詳細については、DirectPlay C++ リファレンスの「DirectPlay 定義済みプロパティ」を参照すること。
DPLSYS_SETPROPERTYRESPONSE
DPLSYS_SETPROPERTY メッセージに応答して、ロビーからアプリケーションに送信されるメッセージ。
Long
応答している要求の ID。
GUID
このプロパティが適用されるプレーヤーの一意な識別子 (適用される場合)。このプロパティがプレーヤーに固有のものではない場合、このメンバには空の文字列を設定する。この値は、DPLSYS_SETPROPERTY メッセージで渡された値と同じである。
GUID
要求されているプロパティの一意な識別子。この値は、DPLSYS_SETPROPERTY メッセージで渡された値と同じである。
Long
プロパティを設定する要求に対する戻りコード。要求が成功した場合は 0、それ以外の場合は DPERR_ACCESSDENIED または

DPERR_UNKNOWNMESSAGE のいずれかになる。

非ロビー システム メッセージ
DPSYS_ADDGROUPTOGROUP
グループがグループに追加された。
Long
グループが追加されたグループの ID。
Long
グループに追加されたグループの ID。
DPSYS_ADDPLAYERTOGROUP
プレーヤーがグループに追加された。
Long
プレーヤーが追加されたグループの ID。
Long
グループに追加されたプレーヤーの ID。
DPSYS_CHAT
メッセージは、ロビーを介して転送されるチャット文字列である。
Long
フラグ。常に 0。
Long
メッセージを発信したプレーヤーの ID。DPID_SERVERPLAYER は、メッセージがサーバーから発信されたことを示す。
Long
メッセージが送信されたプレーヤーの ID。この ID が 0 の場合、メッセージはグループに送信されたか、全員にブロードキャストされた。
Long
メッセージが送信されたグループの ID。この ID が 0 で、直前の Long も 0 の場合、メッセージは全員にブロードキャストされた。
Long
チャット文字列へのポインタ。この文字列を読み取るには、DirectPlayMessage.ReadSysChatString メソッドを使用する。
DPSYS_CREATEPLAYERORGROUP
プレーヤーまたはグループが作成された。
Long
プレーヤー (DPPLAYERTYPE_PLAYER) またはグループ (DPPLAYERTYPE_GROUP) のどちらが作成されたのかを示すフラグ。
Long
作成されたプレーヤーまたはグループの ID。
Long
セッション内のプレーヤーの数。
Long (2)
グループに対するローカル データを含むバッファへのポインタと、そのサイズ。このバッファの中身を取得するには、DirectPlayMessage.ReadSysMsgData メソッドを使用する。
Long (2)
グループに対するリモート データを含むバッファへのポインタと、そのサイズ。このバッファの中身を取得するには、ReadSysMsgData を使用する。
Long
基になる名前構造体のサイズをバイトで示す。無視できる。
Long
名前構造体に対するフラグ。常に 0。
String
グループのショート ネーム。
String
グループのロング ネーム。
Long
グループが DirectPlay4.CreateGroupInGroup の呼び出しによって作成された場合は、親グループの ID。それ以外の場合は 0。
Long
プレーヤーまたはグループのフラグ。0 または DPGROUP_HIDDEN になる (「CONST_DPGROUPFLAGS」を参照)。
DPSYS_DELETEGROUPFROMGROUP
グループからグループが削除された。
Long
グループが削除されたグループの ID。
Long
削除されたグループの ID。
DPSYS_DELETEPLAYERFROMGROUP
グループからプレーヤーが削除された。
Long
プレーヤーが削除されたグループの ID。
Long
削除されたプレーヤーの ID。
DPSYS_DESTROYPLAYERORGROUP
プレーヤーまたはグループが破棄された。
Long
プレーヤー (DPPLAYERTYPE_PLAYER) またはグループ (DPPLAYERTYPE_GROUP) のどちらが破棄されたのかを示すフラグ。
Long
破棄されたプレーヤーまたはグループの ID。
Long (2)
グループに対するローカル データを含むバッファへのポインタと、そのサイズ。このバッファの中身を取得するには、DirectPlayMessage.ReadSysMsgData メソッドを使用する。
Long (2)
グループに対するリモート データを含むバッファへのポインタと、そのサイズ。このバッファの中身を取得するには、ReadSysMsgData を使用する。
Long
基になる名前構造体のサイズをバイトで示す。無視できる。
Long
名前構造体に対するフラグ。常に 0。
String
グループのショート ネーム。
String
グループのロング ネーム。
Long
破棄されているグループが親グループのサブグループである場合、つまり、破棄されているグループが DirectPlay4.CreateGroupInGroup の呼び出しによって作成されたものである場合は、親グループの ID。それ以外の場合は 0。
Long
プレーヤーまたはグループのフラグ。CONST_DPGROUPFLAGS 列挙型の以下のいずれかの値を含むことができる。

DPGROUP_HIDDEN

隠れたグループが破棄されたときに設定される。

DPGROUP_STAGINGAREA

ステージング領域であるグループが破棄されたときに設定される。

DPPLAYER_SERVERPLAYER

破棄されているプレーヤーがクライアント/サーバー通信のサーバー プレーヤーである場合に設定される。

DPPLAYER_SPECTATOR

破棄されているプレーヤーが観客である場合に設定される。

DPSYS_HOST
メッセージを受信しているプレーヤーは、セッションのホストである。このメッセージは、それ以上のデータを含んでいない。
DPSYS_SECUREMESSAGE
別のプレーヤーが署名付きまたは暗号化されたメッセージを受信した。
Long
送信者によるメッセージの保証方法を示すフラグ。CONST_DPSENDFLAGS 列挙型の以下のいずれかの値になる。

DPSEND_SIGNED

メッセージは送信者によって署名され、その署名は正しいものであると確認された。

DPSEND_ENCRYPTED

メッセージは送信者によって暗号化され、正しく復号化された。

Long
メッセージを送信したプレーヤーの ID。

復号化されたメッセージを読み取るには、DirectPlayMessage.MoveToSecureMessage メソッドを使用して、読み取りポインタをデータ バッファの開始部分に移動する。データを読み取るには、DirectPlayMessage の標準の読み取りメソッドを使用する。

DPSYS_SENDCOMPLETE
非同期送信の完了状態を通知するために、アプリケーションに送信されるメッセージ。このメッセージは、デフォルトでは、DirectPlay4.SendEx で DPSEND_ASYNC フラグを使用して非同期メッセージが送信されるたびに、生成される。
Long
メッセージを送信したプレーヤーの ID。
Long
メッセージが送信されたプレーヤーの ID。
Long
メッセージが送信されたときに、SendEx で指定されたフラグ。
Long
メッセージの送信時の優先順位。
Long
メッセージが送信されたときに、SendEx で指定されたタイムアウト。0 は、デフォルトのタイムアウトを示す。
Long
アプリケーションから SendEx に提供された context パラメータ。
Long
SendEx によってアプリケーションに返されたメッセージ ID。
Long
非同期メッセージの結果。メッセージが正しく送信された場合は 0、それ以外の場合は、以下のいずれかのエラー コードになる。

DPERR_ABORTED

メッセージは、転送中にキャンセルされた。

DPERR_CANCELLED

メッセージは、送信キュー内でキャンセルされた。

DPERR_GENERIC

メッセージを送信できなかった。

DPERR_TIMEOUT

メッセージはタイムアウトになり、送信キューから削除された。

Long
アプリケーションによってメッセージが送信されてから、DirectPlay がそのメッセージを送信したときまでの経過時間をミリ秒で示す。これには、送信キュー内で費やした時間と、メッセージをサービス プロバイダに渡すまでに費やした時間が含まれる。保証付きのメッセージの場合は、メッセージの配信の確認に要した時間も含まれる。
DPSYS_SESSIONLOST
ほかのすべてのプレーヤーへの接続が失われた。セッションが失われると、リモート プレーヤーにメッセージを送信することはできないが、セッションが失われたときのデータは依然としてすべて利用可能である。アプリケーションでこのメッセージを受信した場合は、すみやかに復元し、終了する必要がある。このメッセージには、これ以上のデータはない。
DPSYS_SETGROUPOWNER
グループの所有者が変更した。グループの所有権は、セッションを離れる現在の所有者が DirectPlay4.SetGroupOwner を呼び出して変更するか、またはロビー セッション内のロビー サーバーが変更することができる。
Long
所有者が変更したグループの ID。
Long
グループの新しい所有者のプレーヤー ID。
Long
グループの古い所有者のプレーヤー ID。
DPSYS_SETPLAYERORGROUPDATA
DirectPlay は、プレーヤーまたはグループのリモート データが変更されたときに、このメッセージを生成して、各プレーヤーに送信する。セッション記述で DPSESSION_NODATAMESSAGES フラグが設定されている場合は、このメッセージは生成されない。
Long
メッセージがプレーヤー (DPPLAYERTYPE_PLAYER) またはグループ (DPPLAYERTYPE_GROUP) のどちらに適用されるのかを示す。
Long
データが変更されたプレーヤーまたはグループの ID。
Long (2)
アプリケーションに固有のデータを含むバッファへのポインタと、そのサイズ。このバッファの中身を取得するには、DirectPlayMessage.ReadSysMsgData メソッドを使用する。
DPSYS_SETPLAYERORGROUPNAME
DirectPlay は、プレーヤーまたはグループの名前が変更されたときに、このメッセージを生成し、コンピュータ上の各ローカル プレーヤーに送信する。セッション記述で DPSESSION_NODATAMESSAGES フラグが設定されている場合は、このメッセージは生成されない。
Long
メッセージがプレーヤー (DPPLAYERTYPE_PLAYER) またはグループ (DPPLAYERTYPE_GROUP) のどちらに適用されるのかを示す。
Long
名前が変更されたプレーヤーまたはグループの ID。
Long
基になる名前構造体のサイズ。無視できる。
Long
フラグ。常に 0。
String
プレーヤーまたはグループの新しいショート ネーム。
String
プレーヤーまたはグループの新しいロング ネーム。
DPSYS_SETSESSIONDESC
すべてのプレーヤーは、セッション記述が変更されたときに、このメッセージを受信する。新しいセッション記述を取得するには、DirectPlayMessage.ReadSysMsgSessionDesc メソッドを使用する。
DPSYS_STARTSESSION
ロビー サーバーは、グループ内の各プレーヤーがアプリケーション セッションに参加するときに、それらのプレーヤーにこのメッセージを送信する。接続データを取得するには、DirectPlayMessage.ReadSysMsgConnection メソッドを使用する。


エラー コード

ここでは、DirectPlay クラスのメソッドによって返される値を記述する。各メソッドが返すエラー コードの一覧については、それぞれのメソッドの説明を参照すること。

DirectPlay のエラー定数は、CONST_DPLAYERR 列挙型のメンバである。

DP_OK
要求は正しく完了した。
DPERR_ABORTED
処理は、完了する前にキャンセルされた。
DPERR_ACCESSDENIED
セッションが定員に達しているか、または不正なパスワードが指定された。
DPERR_ACTIVEPLAYERS
アクティブなプレーヤーが既に存在するため、要求された処理を実行できない。
DPERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DPERR_APPNOTSTARTED
アプリケーションはまだ開始されていない。
DPERR_AUTHENTICATIONFAILED
パスワードまたは身元証明を認証できなかった。
DPERR_BUFFERTOOLARGE
データ バッファが大きすぎて格納できない。
DPERR_BUFFERTOOSMALL
指定されたバッファが小さすぎて、要求されたデータを格納できない。
DPERR_BUSY
転送メディアがビジーであるため、メッセージを送信できない。
DPERR_CANCELFAILED
メッセージをキャンセルできなかった。おそらくこのメッセージは、グループ内の 1 人以上のメンバに既に送信されたグループ メッセージである。
DPERR_CANCELLED
処理がキャンセルされた。
DPERR_CANNOTCREATESERVER
新しいセッションに対するサーバーを作成できない。
DPERR_CANTADDPLAYER
プレーヤーをセッションに追加できない。
DPERR_CANTCREATEGROUP
新しいグループを作成できない。
DPERR_CANTCREATEPLAYER
新しいプレーヤーを作成できない。
DPERR_CANTCREATEPROCESS
アプリケーションを開始できない。
DPERR_CANTCREATESESSION
新しいセッションを作成できない。
DPERR_CANTLOADCAPI
身元情報が提供されておらず、暗号化サービスに使用する CryptoAPI パッケージ (CAPI) をロードできない。
DPERR_CANTLOADSECURITYPACKAGE
ソフトウェア セキュリティ パッケージをロードできない。
DPERR_CANTLOADSSPI
身元情報が提供されておらず、身元情報を要求する Security Support Provider Interface (SSPI) をロードできない。
DPERR_CAPSNOTAVAILABLEYET
DirectPlay オブジェクトの能力が、まだ決められていない。このエラーは、DirectPlay オブジェクトが、ポーリングによって利用可能な帯域幅と遅延時間を判断する接続ソリューションに実装されている場合に発生する。
DPERR_CONNECTING
メソッドはネットワークへの接続処理中である。アプリケーションでは、正しく完了したことを示す DP_OK か、または異なるエラーが返されるまで、このメソッドを使い続ける必要がある。
DPERR_CONNECTIONLOST
データの送信中に、サービス プロバイダの接続がリセットされた。
DPERR_ENCRYPTIONFAILED
要求された情報を暗号化できなかった。暗号化は、メッセージのプライバシを保護するために利用される。このエラーは、保証セッションでのみ発生する。
DPERR_EXCEPTION
要求を処理しているときに例外が発生した。
DPERR_GENERIC
定義されていないエラー条件が発生した。
DPERR_INVALIDFLAGS
このメソッドに渡されたフラグは無効である。
DPERR_INVALIDGROUP
グループ ID が、このゲーム セッションに対する有効なグループ ID として認識されていない。
DPERR_INVALIDINTERFACE
インターフェイス パラメータが無効である。
DPERR_INVALIDOBJECT
DirectPlay オブジェクトが無効である。
DPERR_INVALIDPARAMS
メソッドに渡された 1 つ以上のパラメータが無効である。
DPERR_INVALIDPASSWORD
パスワードを要求するセッションに参加するときに、無効なパスワードが提供された。
DPERR_INVALIDPLAYER
プレーヤー ID が、このゲーム セッションに対する有効なプレーヤー ID として認識されていない。
DPERR_INVALIDPRIORITY
指定された優先順位が、指定可能な範囲内 (0 ～ 65535) ではない。
DPERR_LOGONDENIED
身元証明が要求されているか、身元証明が提示されなかったか、または身元証明が無効であったため、セッションを開くことができなかった。
DPERR_NOCAPS
DirectPlay が使用する通信リンクが、この関数に対応していない。
DPERR_NOCONNECTION
通信リンクが確立されていない。
DPERR_NOINTERFACE
インターフェイスがサポートされていない。
DPERR_NOMESSAGES
受信キューにメッセージが存在しない。
DPERR_NONAMESERVERFOUND
ネーム サーバー (ホスト) が見つからないか、または作成できなかった。プレーヤーの作成にはホストが必要である。
DPERR_NONEWPLAYERS
セッションが新しいプレーヤーを受け入れていない。
DPERR_NOPLAYERS
セッション内にアクティブなプレーヤーが存在しない。
DPERR_NOSESSIONS
呼び出されたメソッドの対象となるセッションが存在しない。
DPERR_NOTLOBBIED
アプリケーションが DirectPlayLobby3.RunApplication メソッドによって開始されていない場合、またはこの DirectPlayLobby オブジェクトに対して DirectPlayLobbyConnection インターフェイスが現在初期化されていない場合に、DirectPlayLobby3.Connect メソッドから返される。
DPERR_NOTLOGGEDIN
プレーヤーまたはクライアント アプリケーションがログオンしていないため、動作を実行できない。クライアント アプリケーションがログオンせずに保証メッセージを送信したときに、DirectPlay4.Send メソッドから返される。
DPERR_OUTOFMEMORY
要求された処理を実行するために必要な量のメモリが存在しない。
DPERR_PENDING
エラーではない。非同期送信が、正しくキューに入れられるポイントに達したことを示す。詳細については、「SendEx」を参照すること。
DPERR_PLAYERLOST
プレーヤーがセッションへの接続を失った。
DPERR_SENDTOOBIG
DirectPlay4.Send メソッドによって送信されたメッセージが大きすぎる。
DPERR_SESSIONLOST
セッションへの接続が失われた。
DPERR_SIGNFAILED
要求された情報にデジタル署名を追加できない。デジタル署名は、メッセージが本物であることを示すために使用される。
DPERR_TIMEOUT
指定された時間内に処理を完了できなかった。
DPERR_UNAVAILABLE
要求された関数は現在利用できない。
DPERR_UNINITIALIZED
要求されたオブジェクトが初期化されていない。
DPERR_UNKNOWNAPPLICATION
不明なアプリケーションが指定された。
DPERR_UNKNOWNMESSAGE
メッセージ ID が有効ではない。キャンセルするメッセージの ID が無効な場合に、DirectPlay4.CancelMessage から返される。
DPERR_UNSUPPORTED
関数または機能が、この実装またはサービス プロバイダでは利用できない。ロビー セッションではないセッションから DirectPlay4.SetGroupConnectionSettings メソッドが呼び出された場合に、返される。また、優先順位またはタイムアウトが設定されていて、これらの機能がサービス プロバイダによってサポートされておらず、DirectPlay プロトコルがオンになっていない場合に、DirectPlay4.SendEx から返される。さらに、送信キューをチェックして、それがサービス プロバイダによってサポートされておらず、DirectPlay プロトコルがオンになっていない場合は、DirectPlay4.GetMessageQueue から返される。
DPERR_USERCANCEL
ユーザーが DirectPlay4.Open メソッドの呼び出し中に接続処理をキャンセルした場合、またはユーザーが DirectPlay4.GetDPEnumSessions の呼び出し中に DirectPlay サービス プロバイダのダイアログ ボックスで [キャンセル] をクリックした場合に返される。


DirectPlay のツールとサンプル

ここでは、DirectX SDK に含まれているサンプル アプリケーションについて説明する。これらのアプリケーションは、DirectPlay と、アプリケーションをテストするために利用できるツールの使い方を示している。説明は次のように分かれている。

  • DirectPlay ツール
  • DirectPlay C++ サンプル
  • DirectPlay Visual Basic サンプル


DirectPlay ツール

次のツールを使用すると、C++ または Visual Basic で記述された DirectPlay アプリケーションをテストすることができる。

  • DirectPlay Simulator
  • ロビー サーバー


DirectPlay Simulator

説明

DirectPlay Simulator ツールは、ネットワーク アプリケーションの堅牢性をテストするための擬似環境を提供する。高速なローカル エリア ネットワーク上で低帯域幅または遅延時間の長い接続をシミュレートし、任意またはプログラミングされたメッセージ転送の失敗を生成することができる。

パス

実行可能ファイルと DLL: (SDK ルート)\Samples\Multimedia\DPlay\Bin

DPSimcfg.exe は、このツールを構成するために使われる。ツールの機能は DPSim.dll に含まれている。このファイルを Windows システム ディレクトリにコピーする必要がある。

ユーザーズ ガイド

DPSimcfg.exe は、DirectPlay Simulator によって使用されるレジストリ パラメータを構成するために利用される。また、サービス プロバイダのレジストリ エントリを追加または削除することによって、DirectPlay Simulator を起動または停止させる。DirectPlay Simulator がアクティブなときは、それをサービス プロバイダのリストから選択できる。DirectPlay Simulator は、TCP/IP サービス プロバイダ上に実装される。

以下の操作モードを切り替えるには、矢印ボタンをクリックする。

  • パケットをドロップしない。
  • n% のパケットを任意にドロップする。パーセンテージはスライダで設定する。
  • n パケットごとに 1 つのパケットをドロップする。n の値はスライダで設定する。
  • パターンに従ってパケットをドロップする。テキスト ボックスに、渡されるパケット数、ドロップするパケット数、渡されるパケット数といったように一連の数字を入力する。それぞれの数字はカンマまたはスペースで区切る。一連の数字の最後に達すると、パターンが繰り返される。

通信が始まってから一定の期間 (ミリ秒) が経過するまでパケットのドロップが発生しないように指定したり、一定の期間 (ミリ秒) が経過するまでパケットのドロップを継続するように指定することができる。これらの期間を定義するには、[Start After] テキスト ボックスと [Stop After] テキスト ボックスに値を入力する。[Stop After] テキスト ボックスの値がゼロの場合、パケットのドロップは無限に実行される。

メッセージのドロップを確実に実行するには、[Drop Guaranteed] チェック ボックスをオンにする。

送信メッセージと受信メッセージの両方に遅延時間を設定するには、[Latency] をクリックする。スライダを使って、遅延時間をミリ秒単位で設定する。それぞれの遅延時間は、+/- 同じ配分で可変レンジになっている。

注 : スライダ コントロールを細かく調整するには、スライダ コントロールをクリックし、方向キーを使用して値を増加または減少させる。

遅延時間ではなく、シミュレートする帯域幅を選択するには、[Bandwidth] をクリックしてテキスト ボックスにボー レートを入力するか、または矢印ボタンをクリックしてボー レートを選択する。

[Activate] をクリックして、DirectPlay Simulator をサービス プロバイダとして利用できるようにする。


ロビー サーバー

説明

ロビー サーバー アプリケーションは、ロビー セッションを作成し、異なるコンピュータを使っているユーザーが Bellhop サンプルなどのロビー クライアントを使用してやり取りできるようにする。

パス

実行可能フィル: (SDK ルート)\Samples\Multimedia\DPlay\Bin\LServer.exe

ユーザーズ ガイド

ロビー サーバーをデフォルト モードで初期化するには、[Server] メニューの [Start] をクリックする。次に、ロビー セッションの名前を入力する。ロビー サーバーは最上位レベルのデフォルトのグループをいくつか作成する。ユーザーが実行できるのは、最上位レベルのグループ内にサブグループを作成すること、ステージング エリアを作成すること、およびステージング エリアへのショートカットを作成することだけである。

ロビー サーバー アプリケーションは、ユーザーの便宜のために、最上位レベルのグループが自動的に作成されないテスト モードを提供する。ユーザーは任意のグループ階層を、任意の深さで作成することができる。ロビー サーバーをテスト モードに設定する作業は、[Server] メニューの [Start] をクリックする前に行う必要がある。ロビー サーバーをテスト モードに設定するには、[Server] メニューの [Test Mode] をクリックする。次に [Server] メニューの [Start] をクリックすると、ロビー サーバーがテスト モードで起動する。

[Server] メニューの [Secure Mode] をクリックしてから [Start] をクリックし、なおかつロビー サーバーが Windows NT 4.0 または Windows 2000 上で実行されている場合、クライアントはログインするように要求される。

クライアントは、使用するサービス プロバイダを尋ねられる。サーバーに接続するすべてのクライアントが同じサービス プロバイダを選択する必要がある。続いて、ロビー サーバー セッションの名前を提供するように求められる。


DirectPlay C++ サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

以下のサンプルは、DirectPlay の使い方を示している。これらのサンプルは C++ で記述されている。

  • Bellhop サンプル
  • ChatConnect サンプル
  • DPLaunch サンプル
  • DPSlots サンプル
  • Duel サンプル
  • Override サンプル
  • SimpleConnect サンプル
  • StagedConnect サンプル


Bellhop サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

説明

Bellhop サンプルは、IDirectPlay4 インターフェイスを使用してロビー サーバーとやり取りするロビー クライアントプログラムである。Bellhop を実行するには、ロビー サーバー アプリケーションを実行しておく必要がある。

Bellhop を使用すると、アプリケーションのロビー サポートをテストすることができる。

パス

ソース : (SDK ルート)\Samples\Multimedia\DPlay\Src\Bellhop

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DPlay\Bin\Bellhop.exe

ユーザーズ ガイド

Bellhop を起動すると、ロビー プロバイダを選択するように求められる。ロビー サーバー アプリケーションが実行中の場合は、[Lobby Connection for DirectPlay] を選択する。

サービス プロバイダを選択するダイアログ ボックスが表示される。サンプルのロビー サーバーとロビー クライアントは、DirectPlay でサポートされている任意のネットワーク上で機能する。適切なサービス プロバイダ (TCP/IP など) を選択し、[OK] をクリックする。

TCP/IP 接続を選択した場合は、ロビー サーバーのアドレスを要求される。このアドレスを空にして、ローカル ネットワーク上でアドレスを検索することができる。あるいは、コンピュータ名または IP アドレスを入力してもよい。ロビー セッション名が表示されたら、プレーヤーまたは観客としてそのセッションに参加する (両者に実質的な違いはない。アプリケーションでは、プレーヤーと観客は同じように扱われる)。

ロビー サーバーがテスト モードで実行されていない場合、グループまたはルームを表すドアがいくつか表示される。いずれかのドアをダブルクリックする。仮想ゲーム環境でユーザーを表す文字が表示される。最初のグループを離れることなく別のグループに参加するには、参加したいグループのドアをダブルクリックする。ルームを離れるには、プレーヤー アイコンをマウスの右ボタンでクリックし、[Delete Player From Group] をクリックする。あるルームを離れると同時に別のルームに入るには、自分のプレーヤーを表すアイコンをドラッグ アンド ドロップする。

表示できるのは、自分が参加したルームの中身だけである。ルームを離れると、そのルームにあるドア (サブグループ) とプレーヤーはすべて消える。

Bellhop は状況依存のメニューを提供する。プレーヤーまたはグループをマウスの右ボタンでクリックすると、そのアイテムで利用可能な固有のオプションが表示される。背景をマウスの右ボタンでクリックすると、その表示をリフレッシュすることができる。利用可能なすべてのグループとプレーヤーが再度列挙される。

既存のルームでサブグループまたはステージング エリアを作成したい場合は、フォルダをマウスの右ボタンでクリックする。表示されるメニューで [Create Group In Group] をクリックする。ステージング エリアを選択した場合は、プレイするゲームをリストから選択する必要がある。DirectPlay に登録されたアプリケーションだけが表示される。ネットワーク上で実行されているその他のアプリケーションは無視される。ゲームだけでなく、ゲームを開始するために使用する接続も選択する必要がある。オプションとして、セッションに対するパスワードを指定したり、プレーヤーの最大数を指定することができる。

ステージング エリアに参加する場合は、そのアイコンをマウスの右ボタンでクリックし、表示されるメニューで[Connection Settings] をクリックする。ステージング エリアのプロパティが表示される。これらのプロパティの設定を変更することができる。

ステージング エリアからゲームを開始するには、ステージング エリアのアイコンをマウスの右ボタンでクリックし、[Start Session] をクリックする。これにより、ステージング エリアにいるすべてのユーザーのマシン上でアプリケーションが起動し、それらのユーザーがセッションに接続される。セッションが開始したあとでステージング エリアに移動するには、[Start Session] をクリックして進行中のセッションに参加する。セッションの進行中は、アイコンが緑の三角形から赤と黒の三角形に変化する。

ローカル グループまたはプレーヤーの名前を変更するには、グループまたはプレーヤーをマウスの右ボタンでクリックし、[Set Group Name] または [Set Player Name] をクリックする。あるいは、グループまたはプレーヤーの名前のテキストをクリックしてもよい。

同じルームにいる他のプレーヤーにチャット メッセージを送信するには、画面の下にあるテキスト ボックスにテキストを入力し、[Send] をクリックする。


ChatConnect サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

説明

ChatConnect サンプルは、ロビーから実行可能なチャット プログラムである。

パス

ソース : (SDK ルート)\Samples\Multimedia\DPlay\Src\ChatConnect

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DPlay\Bin\ChatConnect.exe.

ユーザーズ ガイド

プレーヤーの名前を入力し、接続の種類を選択するか、またはリストから [Wait for Lobby Connection] を選択する。[Multiplayer Games] ダイアログ ボックスで、[Create] をクリックしてセッションを開始するか、または [Start Search] をクリックしてアクティブなセッションを検索する。アクティブなセッションに参加するには、セッションを選択して [Join] をクリックする。セッションに参加するか、またはセッションを作成すると、直ちにチャットが始まる。他のプレーヤーはチャットにいつでも参加できる。DirectPlayer はホスト プレーヤーを自動的に移行するので、ホスト プレーヤーはいつでもチャットをやめることができる。

TCP/IP サービス プロバイダを使用すると、単一のマシン上でサンプルの複数のインスタンスをテストすることができる。

プログラミングの注意

このサンプルは、DirectPlay をチャット セッション用に使用する方法を示している。


DPLaunch サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

説明

DPLaunch サンプルは、IDirectPlayLobby3 インターフェイスを使用して既存のソースから DirectPlay アプリケーションを起動する方法を示すスタンドアロンのアプリケーションである。また、このサンプルを使用してアプリケーションのロビー サポートをテストすることもできる。

パス

ソース : (SDK ルート)\Samples\Multimedia\DPlay\Src\DPLaunch

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DPlay\Bin\DPLaunch.exe

ユーザーズ ガイド

DPLaunch を起動すると、コンピュータに登録された DirectPlay アプリケーションのリストが表示される。実行するアプリケーションを選択したら、接続方法を選択し、自分のプレーヤー名を指定する。さらに、セッション名を選択し、既存のセッションに参加するのか、または新しいセッションを作成するのかを指定する必要がある。


DPSlots サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

説明

DPSlots サンプルは、DirectPlay のセキュリティ機能を利用する、クライアント／サーバー型のスロット マシン シミュレータである。

サーバーはすべてのスロット マシンを制御し、各プレーヤーが所有する金額を追跡する。クライアントはサーバーに確実にログオンする。

パス

ソース : (SDK ルート)\Samples\Multimedia\DPlay\Src\DPSlots

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DPlay\Bin\DPSlots.exe

ユーザーズ ガイド

DPSlots は、実際には 2 つのアプリケーションで構成される。ユーザーがセッションをホストする場合、DPSlots はサーバーとして機能する。ユーザーがセッションに参加する場合、DPSlots はクライアントとして機能する。

サーバーは、ログオンの許可されたすべてのユーザーに対する取引残高の簡単なデータベースを管理する。クライアントはサーバーに対し、現在の残金を要求できる。また、クライアントはサーバーに対し、スロット マシンを実行し、勝ち負けの合計金額を計算するように要求することができる。サーバーは Slotsdb.txt という簡単なテキスト データベースを維持する。このデータベースは、各ユーザーの残金を記録する。テキスト ファイルの各行には、次の例に示すように、ユーザー アカウントの ID と 残金を示す 8 文字の数字がカンマで区切られて格納されている。

Account1,    1000
Account2,     500

このファイルにユーザーごとに行を手作業で入力する必要がある。"Account1"の部分には、ネットワーク ユーザー名を入力する。

ユーザーがセッションに参加すると、DPSlots はクライアントとして機能し、すべての操作に対するメッセージをサーバーに送信する。クライアントは、名前とパスワードを使用してユーザーをサーバーにログオンするように要求される場合がある。

セキュリティを使用して DPSlots をホストするには、ホストすることを選択した後に、[Require Secure Login] チェックボックスをオンにする。[Security Provider] テキスト ボックスを空白のままにすると、デフォルトの NTLM セキュリティ パッケージが使用される。別の SSPI セキュリティ パッケージをインストールしている場合は、ここでそのパッケージを指定できる。

セキュリティ プロバイダを設定すると、サーバーはセキュア セッションを提供できるようになる。クライアントがセッションに参加するには、ユーザー名とパスワードを使って安全にログオンする必要がある。クライアントとサーバー間でやり取りされるメッセージは、すべてデジタル署名され、暗号化される。

安全なサーバーをホストするときは、使用しているセキュリティ パッケージによって各ユーザーのアカウント ID が定義される。このアカウント ID を、適切な残金と共にデータベース ファイルに格納する必要がある。デフォルトのセキュリティ パッケージは NTLM である。NTLM は、ドメインとユーザー名を使用してアカウント ID を定義する。たとえば、NTLM を使用している場合、ドメインが"GAMES"で、"Bob"および"Jane"という 2 人のユーザーがいれば、データベース ファイルは次のようになる。

GAMES/Bob,    1000
GAMES/Jane,    500

現在、セキュア セッションをホストできるのは、Windows NT または Windows 2000 のワークステーションまたはサーバー上で NTLM を使用している場合だけである。


Duel サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

説明

Duel サンプルは、ロビーから実行可能なマルチプレーヤー ゲームである。このサンプルは、DirectPlay の使い方を示すだけでなく、DirectDraw、DirectInput、および DirectSound も利用している。

パス

ソース : (SDK ルート)\Samples\Multimedia\DPlay\Src\Duel

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DPlay\Bin\Duel.exe

ユーザーズ ガイド

Enter キーを押して開始する。新しいゲームをホストするか、または既存のゲームに参加するかを選択することができる。

ゲームのプレーヤーは、すべて小惑星フィールドの小さな宇宙船で表される。宇宙船を左に旋回させるには左向きの方向キーを、右に旋回させるには右向きの方向キーを使用する。上向きの方向キーは宇宙船を前進させ、下向きの方向キーは後退させる。攻撃するには、Space キーを押す。ゲームを終了するには、ESC キーまたは F12 キーを押す。

TCP/IP 接続を使用すると、単一のコンピュータ上でプログラムの複数のインスタンスを実行することができる。ただし、更新されるのは前面のインスタンスだけである。

インターネット上で TCP/IP を使用してプレイするには、ゲームに参加しているユーザーがゲームをホストするマシンの IP アドレスを入力する必要がある。Windows 95 または Windows 98 のユーザーは、Winipcfg.exe を実行してローカル IP アドレスを判断することができる。Windows 2000 では、lpconfig.exe を実行して同じことができる。ユーザーが LAN とダイヤルアップによるインターネット サービス プロバイダ (ISP) の両方に接続している場合は、コンピュータが 2 つの IP アドレスを持っている場合がある。その場合は、ゲームに対して適切な IP アドレスを選択する必要がある。ダイヤルアップ ISP のほとんどは、動的な IP アドレスを割り当てる。この IP アドレスは、ユーザーがログオンするたびに変化する

このゲームは、プロキシまたはファイアウォールを介した場合には機能しない。


Override サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

説明

Override サンプルは、DirectPlay のサービス プロバイダ ダイアログ ボックスを書き換えるための方法を簡単に示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\DPlay\Src\Override

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DPlay\Bin\Override.exe

ユーザーズ ガイド

プログラムが起動したら、サービス プロバイダを選択する。サービス プロバイダを選択すると、そのサービス プロバイダに必要な情報を集めるために作成されたダイアログ ボックスが表示される。プログラムによって把握されていないサービス プロバイダを選択すると、サービス プロバイダのダイアログ ボックスは書き換えられず、デフォルトのダイアログ ボックスが表示される。

ユーザーからサービス プロバイダの情報を収集したら、それを DirectPlay のアドレスに書式設定する必要がある。このアドレスを使用して、サービス プロバイダを初期化することができる。

IDirectPlay4::EnumSessions メソッドと IDirectPlay4::Open メソッドを呼び出すときに、dwFlags パラメータに値 DPENUMSESSIONS_RETURNSTATUS を設定する必要がある。これにより、接続の進行状況を示すために表示されるステータス ダイアログ ボックスがすべて隠蔽される。


SimpleConnect サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

説明

SimpleConnect サンプルは、DirectPlay セッションを作成する方法とセッションへ参加する方法、およびメッセージを送受信する方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\DPlay\Src\SimpleConnect

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DPlay\Bin\SimpleConnect.exe

ユーザーズ ガイド

プレーヤーの名前を入力し、接続の種類を選択するか、またはリストから [Wait for Lobby Connection] を選択する。[Multiplayer Games] ダイアログ ボックスで、[Create] をクリックして新しいセッションを開始するか、または [Start Search] をクリックしてアクティブなセッションを検索する。アクティブなセッションに参加するには、そのセッションを選択して [Join] をクリックする。"ゲーム"は始まるが、他のプレーヤーはいつでもゲームに参加することができる。セッションに参加している他のすべてのプレーヤーにメッセージを送信するには、[Wave to Other Players] をクリックする。DirectPlayer はホスト プレーヤーを自動的に移行するので、ホスト プレーヤーはいつでもゲームを離れることができる。

TCP/IP サービス プロバイダを使用すると、単一のマシン上でサンプルの複数のインスタンスをテストすることができる。

プログラミングの注意

このサンプルは、DirectPlay をゲームに使用する方法の基本を示している。


StagedConnect サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectPlay Visual Basic サンプル」を参照すること。

[C++]

説明

StagedConnect サンプルは、ChatConnect サンプルとSimpleConnect サンプルの高性能版である。このサンプルでは、セッションはステージング エリアから始まる。ステージング エリアでは、ホストがプレーヤーの数を制限したり、プレーヤーを拒否したり、ゲームを開始したりすることができる。また、ステージング エリアでは、プレーヤーはゲームが始まる前にチャットを行ったり、ゲームを離れたりすることができる。

パス

ソース : (SDK ルート)\Samples\Multimedia\DPlay\Src\StagedConnect

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DPlay\Bin\StagedConnect.exe

ユーザーズ ガイド

プレーヤーの名前を入力し、接続の種類を選択するか、またはリストから [Wait for Lobby Connection] を選択する。[Multiplayer Games] ダイアログ ボックスで、[Create] をクリックして新しいセッションを開始するか、または [Start Search] をクリックしてアクティブなセッションを検索する。アクティブなセッションに参加するには、そのセッションを選択して [Join] をクリックする。

セッションに参加する場合は、ステージング エリアで自分の名前の横にあるチェックボックスをオンにする。ステージング エリアにいる他のプレーヤーにチャット メッセージを送信するには、下にあるテキスト ボックスにメッセージを入力し、Enter キーを押す。

ホストは、スロットのボタンをクリックすることにより、スロットを閉じたり、そのスロットでプレーヤーを拒否したりすることができる。また、[Start Game] をクリックしてプレイを開始することができる。ゲームは、すべてのプレーヤーが揃って初めて開始できる。

プログラミングの注意

このサンプルは、ロビー セッションではなく、アプリケーション セッション内でステージング エリアをセット アップする方法を示している。


DirectPlay Visual Basic サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C++ サンプル」を参照すること。

[Visual Basic]

以下のサンプルは、DirectPlay の使い方を示している。これらのサンプルは Visual Basic で記述されている。

  • Chat サンプル
  • Memory サンプル
  • Whiteboard サンプル


Chat サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C++ サンプル」を参照すること。

[Visual Basic]

説明

Chat サンプルは、簡単なチャット クライアントである。このサンプルは、ロビー クライアントから起動することも、ユーザーによって起動された後にロビー セッションに参加することも可能である。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DPlay\Src\Chat

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DPlay\Bin\DXVBChat.exe

ユーザーズ ガイド

チャットを開始するには、次の手順を実行する。

1. コンピュータ上でロビー サーバーを実行する。通常のセッションを開始する。

2. 各クライアント マシン上でBellhop サンプルを実行し、ロビー サーバーによって作成されたロビー セッションに参加する。

3. 1 台のクライアント上の Bellhop で、DXVBChat に対するステージング領域を作成する (Chat ドアをマウスの右ボタンでクリックし、[CreateGroupInGroup] をクリックする)。

4. 各クライアント上で、三角形をダブルクリックして、ステージング領域に入る。1 台のクライアント上で、三角形をマウスの右ボタンでクリックし、[StartSession] をクリックして、セッションを開始する。これにより、ステージング領域内のすべてのクライアント上で DXVBChat が実行されるか、または DXVBChat が待機モードから抜ける。

セッションが始まった後に新しいプレーヤーが参加するには、ステージング領域に入り、セッションを再度 "開始" する。

セッションが始まる前に DXVBChat を実行することは可能だが、Visual Basic 環境から実行することはできない。DXVBChat.exe を実行する必要がある。

1 台のコンピュータ上でアプリケーションの複数のインスタンスをテストするには、TCP/IP を使用する。実行されている処理を詳しく確認するには、Bellhop の各インスタンスで異なるプレーヤー名を選択する。

プログラミング上の注意

InitDPlay 関数は、アプリケーションがユーザーによって起動されたか (接続の設定を待機する必要がある)、またはロビーによって起動されたかを判断する方法を示している。


Memory サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C++ サンプル」を参照すること。

[Visual Basic]

説明

Memory は、4 人までのプレーヤーが参加できる簡単なネットワーク ゲームである。このゲームは、接続を確立し、セッションを作成するかまたはセッションに参加し、プレーヤーを作成し、DirectPlay メッセージを送受信する方法を示している。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DPlay\Src\Memory

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DPlay\Bin\Memory.exe

ユーザーズ ガイド

ネットワーク セッションを作成するか、またはネットワーク セッションに参加するには、[Multiplayer] ボタンをクリックする。接続の種類を選択し、オプションでプレーヤーの名前を変更して、[OK] をクリックする。セッションをホストしている場合は、サービス プロバイダのあらゆるダイアログ ボックスをキャンセルすることができる。

TCP/IP 接続を選択すると、1 台のコンピュータ上で複数のセッションを実行し、ゲームをプレイすることができる。

[Join or Create Game] ダイアログ ボックスで、[New] をクリックして新しいゲームを作成するか、またはリストからゲームを選択して [Join] をクリックする。このリストは自動的には更新されないので、ほかのプレーヤーがゲームを作成するのを待機している場合は、[Refresh] ボタンを定期的にクリックする必要がある。

ゲームを作成する場合は、プレーヤーの最大数と名前を設定して、[Create] をクリックする。[Waiting for Host to Start Game] ダイアログ ボックスが表示される。最低 1 人のプレーヤーがリストに表示されていれば、ゲームを直ちに開始することができる。

ゲームをプレイするには、自分の名前がスコアボードに強調表示されるのを待って、任意の 2 つのタイルをクリックする。タイルが一致したら、もう一度プレイする。一致したタイルが最も多いプレーヤーが勝ちである。一致しないタイルは、次のプレーヤーがタイルをクリックすると、直ちに隠される。

ほかのすべてのプレーヤーにチャット メッセージを送信するには、Enter キーを押す。

途中でゲームを抜けると、ほかのプレーヤーがホストになる。

プログラミング上の注意

アプリケーションは、GlobalModule.bas モジュールの Sub Main でメッセージを問い合わせる。また、ほとんどのフォームに、DirectPlay のコードが含まれている。


Whiteboard サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectPlay C++ サンプル」を参照すること。

[Visual Basic]

説明

Whiteboard サンプルは、ロビーに対応していないチャット アプリケーションである。このアプリケーションでは、ユーザーがスケッチ ボード上で共同作業したり、テキスト メッセージを交換したりすることができる。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DPlay\Src\Whiteboard

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DPlay\Bin\Whiteboard.exe

ユーザーズ ガイド

いずれかのユーザーが、[Sessions] メニューの [Create Host] をクリックして、セッションを開始する必要がある。このセッションに、ほかのプレーヤーが参加する。

メッセージを送信するには、画面の下部にあるテキスト ボックスに入力して、[Send] ボタンをクリックする。ホワイトボードに描画するには、マウスをドラッグする。描いたものを消すには、[Clear] をクリックする。

プログラミング上の注意

メッセージは、タイマ イベントに応じて取得される。


DirectSetup

ここでは、Platform Software Development Kit (SDK) またはスタンドアローン DirectX SDK における Microsoft® DirectX® アプリケーション プログラミング インターフェイス (API) の Microsoft® DirectSetup® コンポーネントに関する情報を以下の項目に分けて説明する。

  • DirectSetup について
  • DirectSetup の要点
  • DirectSetup リファレンス
  • DirectSetup サンプル


DirectSetup について

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

DirectSetup は、DirectX のすべてのコンポーネントを一度の呼び出しでインストールするためのシンプルな API である。この API の意義は、単に便利というだけにとどまらない。DirectX は複雑な構成になっているため、インストールも複雑なタスクとなる。そのため、DirectX のインストールは手動で行うべきではない。

さらに、DirectSetup を使用することで、DirectPlayLobby オブジェクトを用いるアプリケーションに必要な Microsoft® Windows® オペレーティング システムのレジストリ情報を自動的にインストールできる。このレジストリ情報は、DirectPlayLobby オブジェクトによるアプリケーションの列挙および起動に必要とされる。

DirectSetup には、いくつかの API 関数と構造体が含まれる。そのほか、インストール プロセス用のユーザー インターフェイスをアプリケーション側でカスタマイズするためのプロトタイプとして、DirectXSetupCallbackFunction も用意されている。DirectX SDK には、このコールバック関数の使用例を示すサンプル アプリケーションが収録されている。詳細については、「Dinstall サンプル」を参照すること。


DirectSetup の要点

ここでは、DirectSetup コンポーネントの概要について説明する。説明する内容は以下のとおりである。

  • DirectSetup のセットアップの概要
  • DirectX for Visual Basic アプリケーションのインストール
  • セットアップ フォルダの準備
  • セットアップのカスタマイズ
  • セットアップ プログラムのテスト
  • AutoPlay の使用


DirectSetup のセットアップの概要

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

DirectX をベースとするアプリケーションおよびゲームは、DirectXSetup 関数を使用して、既にインストールされている Windows システムに必要なシステム コンポーネントをインストールすることができる。この関数では、ディスプレイやオーディオ デバイスで適切に DirectX がサポートされるよう、ドライバのアップデートも行うことができる。DirectXSetup は、通常、アプリケーション ファイルのインストールに使用するプログラムから呼び出す。

注 : DirectXSetup 関数は、旧バージョンの DirectX システム コンポーネントを上書きする。たとえば、既に DirectX 5.0 のコンポーネントが存在するシステムに DirectX 7.0 をインストールすると、DirectX 5.0 のコンポーネントすべてが上書きされる。ただし、DirectX のコンポーネントはすべてコンポーネント オブジェクト モデル (COM) の下位互換性規則に準拠しているので、DirectX 5.0 用に記述したソフトウェアも引き続き正常に機能する。

DirectXSetup 関数は、DirectX コンポーネント、ディスプレイ ドライバ、オーディオ ドライバのアップグレードが必要なことを知らせることができる。また、これらのコンポーネントを、Windows オペレーティング システムに悪影響を与えることなしにアップグレードできるかどうかも判断できる。これがいわゆるセーフ アップグレードである。アップグレードの際は、コンピュータ上で動作しているアプリケーションだけでなく、オペレーティング システムに対する安全性も考慮する。また、Windows にとっては安全でも、一部のハードウェア依存アプリケーションに悪影響を与えてしまう場合もある。

デフォルトでは、DirectXSetup 関数は安全なアップグレードのみを実行する。デバイス ドライバのアップグレードによって Windows の動作に悪影響が及ぶ可能性がある場合、アップグレードは行われない。

セットアップ処理中、DirectSetup は置き換えるシステム コンポーネントとドライバのバックアップ コピーを作成する。これらのコピーは、問題が発生した場合に復元するためのものである。

ディスプレイ ドライバまたはオーディオ ドライバをアップグレードするとき、DirectXSetup 関数は、Microsoft 社が作成したデータベースを利用してアップグレード プロセスを管理する。このデータベースには、Microsoft 社、ハードウェアの製造業者、またはハードウェアの販売店が提供するドライバについての情報が含まれている。また、Microsoft 社やその他での検査に基づくそれぞれのドライバのアップグレード状況も登録されている。

DirectXSetup 関数を実行したら、戻り値をチェックする。戻り値が DSETUPERR_SUCCESS_RESTART の場合は、再起動するまで変更内容が有効にならないことをユーザーに知らせ、すぐに再起動するかどうか選択させる。この方法については、Dinstall サンプル アプリケーションの Dinstall.c の例を参照すること。


DirectX for Visual Basic アプリケーションのインストール

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。

[Visual Basic]

モジュール内で関数に参照を宣言すると、Visual Basic アプリケーションで DirectSetup 関数を使用できるが、推奨方法はアプリケーション ウィザードの使用である。CD でアプリケーションを配布するには、次の手順を実行する。

Visual Basic アプリケーションの配布

1. アプリケーション ウィザードを起動する。

2. 依存リストから DxVBLib.dll を削除する。

3. Direct SDK CD の Redist フォルダ (リテール用 \Dxf\Redist\Directx7、デバッグ用 \Dxf\Debug) のすべてのファイルを追加する。

4. [Finish] ボタンをクリックし、アプリケーション ウィザードを終了する。

5. DirectX SDK CD の support フォルダにある Setup1.exe を (アプリケーション ウィザードで作成された) Setup1.exe に上書きする。

6. Visual Basic 5.0 を使用している場合は、圧縮ユーティリティを使って Setup1.exe を Setup1.ex_ に圧縮する。Visual Basic 6.0 で開発している場合は、アプリケーション ウィザードで作成されたバッチ ファイルを実行する。

7. これで、CD でファイルを配布する準備が整う。


セットアップ フォルダの準備

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

DirectXSetup 関数は、インストールのルート ディレクトリを示すパラメータ lpszRootPath を取る。このパラメータを NULL にして、現在のディレクトリ (つまり、セットアップ プログラムが保存されているディレクトリ) をルート パスとすることもできる。

ルート ディレクトリには、dsetup.dll と dsetup32.dll を保存する必要がある。また、この中には「DirectX」 (大文字小文字の区別なし) という名前のフォルダを用意し、再配布可能なすべてのファイルおよびドライバを保存する。正しい構造のアプリケーション セットアップ ディスクは、DirectX SDK ディスクの Dxf\Redist\DirectX7 フォルダの内容すべてをセットアップ プログラムのルート パスにコピーすると作成できる。このフォルダは、SDK のインストール時に開発用のコンピュータにコピーされないので、オリジナル ディスクから別途コピーする必要がある。


セットアップのカスタマイズ

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

DirectSetup では、DirectX セットアップ プロセスをカスタマイズするためのコールバック関数を定義することができる。このコールバック関数は、DirectSetup ドキュメントの中では DirectXSetupCallbackFunction と呼ばれているが、実際には任意の名前を割り当てることができる。

セットアップ プログラムでコールバック関数を使用しない場合、DirectXSetup 関数は、Microsoft® Win32® MessageBox 関数を呼び出して、ダイアログ ボックス内にステータス情報やエラー情報を表示し、ユーザー入力の取得を行う。コールバック関数を使用する場合、このステータス ダイアログまたはメッセージ ボックスの作成に使用されるはずの情報は、代わりにコールバック関数に渡される。コールバック関数は、インストールまたはアップグレード可能な DirectX コンポーネントおよびデバイス ドライバごとに一度ずつ呼び出される。

コールバック関数は、以下の用途に使用できる。

  • カスタムインターフェイスの使用 － MessageBox や Windows の標準ダイアログ ボックス以外の方法で、セットアップ プログラムのメッセージを表示できる。コールバック関数を使うことで、DirectX コンポーネントのインストール用メッセージを、独自のインターフェイスに統合できる。
  • プログレス インジケータの更新
  • ステータス メッセージおよびエラー メッセージの表示制御 － 初心者向けのプログラムを開発する場合には、エラー メッセージを制御して、セットアップ プログラムにエラーの処理やアップグレードの選択を自動的に処理させたい場合がある。このようなセットアップ プログラムの開発には手間がかかるが、対象ユーザー層を考えると適切な措置といえる。

セットアップのカスタマイズにあたっては、次の各トピックを参考にすること。

  • DirectSetup コールバック関数の作成
  • コールバック関数の設定
  • コールバック関数でのアップグレード フラグの使用
  • コールバック関数によるデフォルト動作の無効化


DirectSetup コールバック関数の作成

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

セットアップ プロセスをカスタマイズするには、まず次の宣言で示した DirectXSetupCallbackFunction プロトタイプに適合するコールバック関数を作成する。

DWORD WINAPI DirectXSetupCallbackFunction(
        DWORD dwReason,
        DWORD dwMsgType,
        LPSTR szMessage,
        LPSTR szName,
        void *pInfo);

この例 (Dinstall を修正したもの) では、関数名がプロトタイプと同じになっているが、これは変更可能である。パラメータ名は、dsetup.h ヘッダー ファイルで宣言されているプロトタイプと若干異なるが、以下の説明ではこれらの名前を使用する。

パラメータ

dwReason は、コールバック関数が呼び出された理由を示すパラメータである。有効値の一覧および各有効値の説明については、DirectXSetupCallbackFunction のリファレンスを参照すること。

dwMsgType パラメータは、DirectSetup がデフォルトで MessageBox に渡すフラグ (表示するボタンやアイコンを制御するフラグなど) と同等のフラグを受け取る。中でも、ボタン フラグは、必要な戻り値の指定に使用できる。この値が 0 の場合、イベントはユーザー入力を要求しないため、DirectSetup は通常ステータス メッセージを表示する。

szMessage パラメータは、コールバック関数を使用しない場合に DirectSetup がステータス ダイアログ ボックスまたは MessageBox に渡すものと同じテキストを受け取る。

ドライバがアップグレード対象の場合、szName パラメータにドライバ名が渡され、pInfo はアップグレードの処理方法 (既存のドライバの使用を推奨する、アップグレードを推奨するなど) に関する情報を示す。詳細については、「コールバック関数でのアップグレード フラグの使用」を参照すること。

コールバック関数が各パラメータをどのように解釈するかについては、開発者の裁量で決定する。通常は、表示するメッセージ (dwReason に基づく) とユーザーに選択肢を提示するタイミングを選択し、それに応じてインターフェイスを変更する。

戻り値

コールバック関数からの戻り値は、次の規則に従う必要がある。

  • dwMsgType が 0 の場合、戻り値は IDOK でなければならない。この場合、ユーザーには選択肢は与えられない (ユーザー入力を要求しない場合でも、アプリケーションからステータス メッセージを表示することは差し支えない)。
  • dwMsgType が 0 以外の場合の戻り値は、MessageBox を使用した場合にユーザーが同様の選択をしたときに返される値と同じ値でなければならない。

dwMsgType が 0 以外の場合の適切な戻り値を確認するには、通常ならどのようなボタンがメッセージ ボックスに表示されるか実際にテストしてみる。次の例 (Dinstall の GetReply 関数より) は、このテスト方法を示したものである。

/* グローバル g_wReply は、ユーザーが選択したカスタム
   ダイアログ ボタンを示す。 */

switch (dwMsgType & 0x0000000F)
{
   / * 通常は、[OK] ボタンと [Concel] ボタンがある。
       このルーチンでは、IDBUT1 が [OK] ボタンに相当する。
       このボタンが選択されない場合は [Cancel] になる。 */
    case MB_OKCANCEL:
        wDefaultButton = (g_wReply == IDBUT1) ? IDOK : IDCANCEL;
        break;

    / * ほかのボタンの組み合わせでも同様。 */
    case MB_OK:
        wDefaultButton = IDOK;
        break;
    case MB_RETRYCANCEL:
        wDefaultButton = (g_wReply == IDBUT1) ? IDRETRY : IDCANCEL;
        break;
    case MB_ABORTRETRYIGNORE:
        if (g_wReply == IDBUT1)
            wDefaultButton = IDABORT;
        else if (g_wReply == IDBUT2)
            wDefaultButton = IDRETRY;
        else
            wDefaultButton = IDIGNORE;
        break;
    case MB_YESNOCANCEL:
        if (g_wReply == IDBUT1)
            wDefaultButton = IDYES;
        else if (g_wReply == IDBUT2)
            wDefaultButton = IDNO;
        else
            wDefaultButton = IDCANCEL;
        break;
    case MB_YESNO:
        wDefaultButton = (g_wReply == IDBUT1) ? IDYES : IDNO;
        break;
    default:
        wDefaultButton = IDOK;
}

このルーチンは、カスタム インターフェイスからのボタン クリックを、コールバック関数なしの場合に DirectSetup が作成する標準ダイアログ ボックス内の対応するボックス識別子に変換する。wDefaultButton 変数は、対応する標準ダイアログ ボックス ボタンの識別子に設定される。コールバック関数から返されるのは、この値である。

dwMsgType が 0 以外の値の場合でも、必ずしもユーザーに選択肢を与える必要はない。たとえば、DirectSetup が通常ユーザーに確認を求めるような場合でも、自動的にドライバをアップグレードすることも可能である。サンプルの Dinstall では、問題のある場合のみメッセージを表示するようユーザーが選択している場合で、しかもドライバをアップグレードしても安全であると考えられるときに、次のように自動アップグレードを行うようになっている。

case DSETUP_CB_UPGRADE_SAFE:
    switch (dwMsgType & 0x0000000F)
    {
        case MB_YESNO:
        case MB_YESNOCANCEL:
            return IDYES;
        case MB_OKCANCEL:
        case MB_OK:
        default:
            return IDOK;
    }
    break;

コールバック関数は、ユーザーにアップグレードを続行するかどうか確認するダイアログ ボックスで肯定を表すボタンに応じて、IDYES または IDOK を返す。


コールバック関数の設定

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

コールバック関数を使用する場合は、DirectXSetup を呼び出す前にシステムに知らせておく必要がある。これには、コールバックへのポインタをパラメータとして渡して DirectXSetupSetCallback 関数を呼び出す。次の例を参照すること。

DirectXSetupSetCallback(
        (DSETUP_CALLBACK) DirectXSetupCallbackFunction);


コールバック関数でのアップグレード フラグの使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

アプリケーションで定義されたコールバック関数 DirectXSetupCallbackFunction が DirectXSetup 関数で呼び出されると、コールバック関数に呼び出し理由を示すパラメータが渡される。理由が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE の場合、pInfo パラメータは、DirextXSetup 関数が推奨する DirectX コンポーネントおよびドライバのアップグレード方法をまとめたフラグを保持する DSETUP_CB_UPGRADEINFO 構造体を示す。これらのフラグを格納する構造体メンバは、UpgradeFlags と呼ばれる。

UpgradeFlags には次のようなカテゴリがある。

一次アップグレード フラグ
これらのフラグは互いに排他的である。構造体メンバ UpgradeFlags には常にいずれか 1 つのフラグが存在する。フラグを抽出するには、DSETUP_CB_UPGRADE_TYPE_MASK とのビットごとの AND 処理をとる。

DSETUP_CB_UPGRADE_FORCE

DSETUP_CB_UPGRADE_KEEP

DSETUP_CB_UPGRADE_SAFE

DSETUP_CB_UPGRADE_UNKNOWN

二次アップグレード フラグ
次のいずれかまたは両方のフラグが存在する。

DSETUP_CB_UPGRADE_CANTBACKUP

DSETUP_CB_UPGRADE_HASWARNINGS

デバイス アクティブ フラグ
ドライバをアップグレード中のデバイスがアクティブな場合に存在するフラグ。ほかのフラグと組み合わせて使用できる。

DSETUP_CB_UPGRADE_DEVICE_ACTIVE

デバイス クラス フラグ
これらのフラグは互いに排他的である。どちらかのフラグが必ず存在する。

DSETUP_CB_UPGRADE_DISPLAY

DSETUP_CB_UPGRADE_MEDIA

つまり、Reason パラメータの値が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE であれば、pInfo で指定される構造体メンバ UpgradeFlags には、常に 1 つの一次アップグレード フラグ、0 個以上の二次アップグレード フラグ、0 個または 1 つのデバイス アクティブ フラグ、および 1 つのデバイス クラス フラグが含まれる。

UpgradeFlags のメンバに DSETUP_CB_UPGRADE_KEEP が設定されている場合は、Windows が正常に機能しなくなる恐れがあるため、DirectX コンポーネントやデバイス ドライバをアップグレードすることはできない。DirectXSetup 関数によるコンポーネントまたはドライバのアップグレードは行われない。

UpgradeFlags に DSETUP_CB_UPGRADE_FORCE という値がある場合は、Windows を正常に機能させるため、コンポーネントまたはドライバのアップグレードが必要である。このため、DirectXSetup 関数は、ドライバまたはコンポーネントのアップグレードを行う。ただし、アップグレードによって、システム上の一部のプログラムに悪影響が及ぶ可能性がある。DirectXSetup 関数がこの状態を検出すると、UpgradeFlags のメンバは (DSETUP_CB_UPGRADE_FORCE | DSETUP_CB_UPGRADE_HAS_WARNINGS) に設定される。この場合、DirectXSetup 関数は、アップグレードを実行する一方で、ユーザーに警告を発する。

コンポーネントおよびドライバをインストールしても Windows の動作に悪影響が及ばない場合、そのコンポーネントやドライバは安全にアップグレードできると見なされる。この場合、UpgradeFlags のメンバには DSETUP_CB_UPGRADE_SAFE が設定される。ただし、Windows に対しては安全であっても、システムにインストールされているプログラムに問題が発生する可能性はある。DirectXSetup 関数がこの状態を検出すると、UpgradeFlags のメンバには、値 (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS) が格納される。この場合、DirectXSetup 関数のデフォルト動作では、アップグレードは実行されない。


コールバック関数によるデフォルト動作の無効化

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

アプリケーションで定義された関数 DirectXSetupCallbackFunction の戻り値を使って、DirectXSetup 関数のデフォルト動作の一部を無効化することができる。

たとえば、DirectXSetup のデフォルト動作では、pInfo パラメータが示す構造体内のアップグレード タイプが (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS) に設定されているとコンポーネントはインストールされない。この場合、コールバック関数の MsgType パラメータは (MB_YESNO | MB_DEFBUTTON2) に設定される。コールバック関数を使用しない場合は、[No] がデフォルト ボタンになったダイアログ ボックスがユーザーに表示される。ユーザー入力を調べずにデフォルトを受け付ける場合、コールバック関数は IDNO を返す。デフォルトを無効にする場合は、IDYES を返す。デフォルトを無効にする場合、DirectXSetup 関数はユーザーに通知する。


セットアップ プログラムのテスト

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

作成したセットアップ プログラムの DirectSetup コンポーネントをテストするには、DirectXSetup 関数に DSETUP_TESTINSTALL フラグを渡したバージョンをコンパイルする。そして、「セットアップ フォルダの準備」で説明したインストール ディレクトリをセットアップする。

セットアップ プログラムを実行すると、DirectSetup は、実際にはコンポーネントをインストールせずに、DirectX インストール時の模擬動作を行う。コールバック関数を設定している場合は、コールバック関数の動作も調べられる。


AutoPlay の使用

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic で記述されたアプリケーションの配布については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。

[C++]

AutoPlay 対応の CD タイトルを作成するには、DirectX SDK CD のルート ディレクトリ中の Autorun.inf ファイルを、アプリケーション ディレクトリのルートにコピーする。Autorun.inf は、以下の情報を格納するテキスト ファイルである。

[autorun]
OPEN=SETUP.EXE

アプリケーションのセットアップ プログラム名が Setup.exe の場合、このファイルを変更する必要はない。それ以外の名前が付いている場合は、実際のセットアップ プログラム名に合わせてこのファイルを編集しなければならない。


DirectSetup リファレンス

ここでは、Microsoft® DirectSetup® の API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • 関数
  • 構造体
  • 戻り値

このリファレンスは主に、C++ でプログラミングを行うときに使用する。Microsoft® DirectX® for Visual Basic のセットアップ情報については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。


関数

ここでは、DirectSetup で使用する以下のグローバル関数について説明する。

  • DirectXRegisterApplication
  • DirectXSetup
  • DirectXSetupCallbackFunction
  • DirectXSetupGetVersion
  • DirectXSetupSetCallback
  • DirectXUnRegisterApplication


DirectXRegisterApplication

DirectXRegisterApplication 関数は、アプリケーションを DirectPlayLobby 対応アプリケーションとして登録する。

int WINAPI DirectXRegisterApplication(
  HWND hWnd,
  LPDIRECTXREGISTERAPP lpDXRegApp
);

パラメータ

hWnd
親ウィンドウのハンドル。このパラメータが NULL の場合は、デスクトップが親ウィンドウとなる。
lpDXRegApp
DirectPlayLobby で正しくアプリケーションを動作させるために必要なレジストリ エントリを含む DIRECTXREGISTERAPP 構造体のアドレス。

戻り値

成功すれば TRUE を返す。失敗すれば FALSE を返す。GetLastError 関数を使用すると、拡張エラー情報を取得できる。

注意

DirectXRegisterApplication 関数では、システムにインストールされていない dsetup.dll と dsetup32.dll の両方が必要となるが、両方共 SDK に準備されている。

DirectXRegisterApplication 関数は、アプリケーションが DirectPlayLobby で動作するのに必要なレジストリ エントリを挿入するが、ロビー アプリケーションのインストールとアンインストールには、IDirectPlayLobby3::RegisterApplication と IDirectPlayLobby3::UnregisterApplication の各メソッドの使用を推奨する。そのため、DirectXRegisterApplication を使用した場合、アプリケーションのアンインストール時には、DirectXUnRegisterApplication でこれらのレジストリ エントリを削除する必要がある。

市販されているインストール プログラムの多くは、プログラムのアンインストール時にレジストリ エントリを自動的に削除する。ただし、これは、プログラム自体がレジストリ エントリを追加した場合に限られる。DirectXRegisterApplication によって DirectPlayLobby のレジストリ エントリが追加された場合は、市販のインストール プログラムでアンインストールしても、レジストリ エントリが削除されない。したがって、DirectXRegisterApplication によって作成された DirectPlayLobby のレジストリ エントリは、DirectXUnRegisterApplication を使って削除しなければならない。

DirectPlayLobby アクセスに必要なレジストリ エントリは、DirectXRegisterApplication を使用しなくても作成できる。ただし、この方法は一般に推奨されるものではない。Microsoft® DirectPlay® の「ロビー対応アプリケーションの登録」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXUnRegisterApplication


DirectXSetup

DirectXSetup 関数は、1 つまたは複数の DirectX コンポーネントをインストールする。

int WINAPI DirectXSetup(
  HWND  hWnd,
  LPSTR lpszRootPath,
  DWORD dwFlags
);

パラメータ

hWnd
セットアップ ダイアログ ボックスの親ウィンドウのハンドル。
lpszRootPath
DirectX コンポーネント ファイルのルート パスを含む文字列のアドレス。この文字列には、ファイル dsetup.dll および dsetup.dll32 と、再配布可能ファイルを格納した「DirectX」 (大文字小文字の区別なし) ディレクトリのあるディレクトリへのフル パスを指定しなければならない。この値が NULL の場合は、現在の作業ディレクトリが使用される。
dwFlags
インストール対象となる DirectX コンポーネントを示す 1 つまたは複数のフラグ。推奨は、フル インストール (DSETUP_DIRECTX)。
DSETUP_D3D | 使用しない。このフラグを使用する DirectX 3 のプログラムはすべての DirectX コンポーネントをインストールする。
DSETUP_DDRAW | 使用しない。このフラグを使用する DirectX 3 のプログラムはすべての DirectX コンポーネントをインストールする。
DSETUP_DDRAWDRV | DirectX 7.0 では使用しない。
DSETUP_DINPUT | 使用しない。このフラグを使用する DirectX 3 のプログラムはすべての DirectX コンポーネントをインストールする。
DSETUP_DIRECTX | DirectX と互換性のあるディスプレイ ドライバおよびオーディオ ドライバに加え、DirectX ランタイム コンポーネントをインストールする。
DSETUP_DIRECTXSETUP | 使用しない。このフラグを使用する DirectX 3 のプログラムはすべての DirectX コンポーネントをインストールする。
DSETUP_DPLAY | 使用しない。このフラグを使用する DirectX 3 のプログラムはすべての DirectX コンポーネントをインストールする。
DSETUP_DPLAYSP | 使用しない。このフラグを使用する DirectX 3 のプログラムはすべての DirectX コンポーネントをインストールする。
DSETUP_DSOUND | 使用しない。このフラグを使用する DirectX 3 のプログラムはすべての DirectX コンポーネントをインストールする。
DSETUP_DSOUNDDRV | DirectX 7.0 では使用しない。
DSETUP_DXCORE | DirectX ランタイム コンポーネントをインストールする。DirectX と互換性のあるディスプレイ ドライバとオーディオ ドライバはインストールしない。
DSETUP_TESTINSTALL | インストール内容をテストする。新しいコンポーネントをインストールすることはない。
DSETUP_USEROLDERFLAG | -14 を返せる。これは、インストールされている DirectX のバージョンがインストールするバージョンよりも新しいことを意味する。

戻り値

成功すれば DSETUPERR_SUCCESS または DSETUPERR_SUCCESS_RESTART (変更内容を有効にするためにシステムを再起動する必要がある場合) を返す。失敗すればエラー コードを返す。戻り値については、「戻り値」を参照すること。

注意

セットアップ プログラムで DirectXSetup 関数を使用する前に、システムに最低 15 MB の空きディスク領域があることを確認すること。これは適切なファイルをセット アップするために DirectX が必要とする最大領域である。ただし、システムに DirectX ファイルが既に存在する場合は必要ない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。


DirectXSetupCallbackFunction

DirectXSetupCallbackFunction は、オプションでセットアップ プログラムに設定するコールバック関数のプレースホルダ名である。設定されたコールバック関数は、セットアップ プロセスの各ステップごとに一度ずつ呼び出される。

DWORD DirectXSetupCallbackFunction(
  DWORD  Reason,
  DWORD  MsgType,
  char  *szMessage,
  char  *szName,
  void  *pInfo
);

パラメータ

Reason
コールバックの理由。次のいずれかの値を取る。
DSETUP_CB_MSG_BEGIN_INSTALL
DirectXSetup が DirectX コンポーネントとデバイス ドライバのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_INSTALL_DRIVERS
DirectXSetup がデバイス ドライバのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_INSTALL_RUNTIME
DirectXSetup が DirectX コンポーネントのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_RESTORE_DRIVERS
DirectXSetup が以前のドライバの復元を始めようとしている。
DSETUP_CB_MSG_CANTINSTALL_BETA
Microsoft® Windows® 95 オペレーティング システムのベータ バージョンが検出された。DirectX コンポーネントまたはデバイス ドライバをインストールできない。
DSETUP_CB_MSG_CANTINSTALL_NOTWIN32
Windows 32 ビット以外のオペレーティング システムが検出された。DirectX は Windows3.x と互換性はない。
DSETUP_CB_MSG_CANTINSTALL_NT
DirectX コンポーネントまたはデバイス ドライバは、バージョン 4.0 より前の Microsoft® Windows NT® オペレーティング システムにはインストールできない。
DSETUP_CB_MSG_CANTINSTALL_UNKNOWNOS
オペレーティング システムが既知のものではない。DirectX コンポーネントまたはデバイス ドライバをインストールできない。
DSETUP_CB_MSG_CANTINSTALL_WRONGLANGUAGE
DirectX コンポーネントまたはデバイス ドライバを、Windows で使用されている言語にローカライズすることができない。
DSETUP_CB_MSG_CANTINSTALL_WRONGPLATFORM
DirectX コンポーネントまたはデバイス ドライバが別の種類のコンピュータ用のものである。
DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE
ドライバのアップグレードが必要と考えられる。ユーザー側の確認を推奨する。
DSETUP_CB_MSG_FILECOPYERROR
DirectX コンポーネントまたはデバイス ドライバ ファイルのセットアップがコピー プロセス中に失敗した。
DSETUP_CB_MSG_INTERNAL_ERROR
内部エラーが発生した。DirectX コンポーネントまたはデバイス ドライバのセットアップが失敗した。
DSETUP_CB_MSG_NOMESSAGE
表示するメッセージがない。コールバック関数は戻らなければならない。
DSETUP_CB_MSG_NOTPREINSTALLEDONNT
使用している Windows NT または Microsoft® Windows® 2000 のバージョンに DirectX コンポーネントまたはデバイス ドライバがインストールできない。
DSETUP_CB_MSG_OUTOFDISKSPACE
DirectX コンポーネントのセットアップがディスク領域不足のために失敗した。
DSETUP_CB_MSG_PREINSTALL_NT
使用している Windows NT または Windows 2000 のバージョンに既に DirectX がインストールされている。
DSETUP_CB_MSG_SETUP_INIT_FAILED
DirectX コンポーネントまたはデバイス ドライバのセットアップが失敗した。
MsgType
メッセージ ボックスの表示を制御するフラグ。これらのフラグは、MessageBox 関数に渡すことができる。MsgType が 0 のときは例外で、セットアップ プログラムはステータス情報を表示することはできるが、ユーザーからの入力待ちをしてはいけない。
szMessage
エラー メッセージまたはステータス情報を含むローカライズ文字列で、MessageBox 関数で作成されるダイアログ ボックスに表示できる。
szName
Reason パラメータが DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE でない限り NULL である。この場合、szName にはアップグレードするドライバの名前が入る。
pInfo
アップグレード情報を含む構造体のアドレス。Reason が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE の場合は、セットアップ プログラムがドライバのアップグレード中で、ユーザーにアップグレードを行うべきかどうかを問い合わせている。この場合、pInfo は、アップグレードに関する情報を格納する DSETUP_CB_UPGRADEINFO 構造体を示す。

戻り値

1 つの例外を除いて、戻り値は MessageBox 関数から返される戻り値と同じでなければならない。この関数が 0 を返した場合、DirectXSetup 関数は デフォルトの動作で DirectX コンポーネントまたはドライバのアップグレードを実行する。

注意

DirectXSetupCallbackFunction の名前はセットアップ プログラムから与えられる。DirectXSetupSetCallback 関数は、DirectSetup にコールバック関数のアドレスを渡す際に使用される。

MsgType が 0 の場合、セットアップ プログラムでステータス情報を表示できるが、ユーザーからの入力待ちをしてはいけない。この場合、関数は IDOK を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : ユーザー定義。

参照

MessageBox、DirectXSetupSetCallback、セットアップのカスタマイズ


DirectXSetupGetVersion

DirectXSetupGetVersion 関数は、現在インストールされている DirectX コンポーネントのバージョン番号を取得する。

INT WINAPI DirectXSetupGetVersion(
  DWORD  *pdwVersion,
  DWORD  *pdwRevision
);

パラメータ

pdwVersion
バージョン番号を受け取る変数のアドレス。バージョン番号が不要の場合は NULL でも可。
pdwRevision
リビジョン番号を受け取る変数のアドレス。リビジョン番号が不要の場合は NULL でも可。

戻り値

成功すれば 0 以外の値を返す。失敗すれば 0 を返す。

注意

DirectXSetupGetVersion 関数は、DirectXSetup 関数を呼び出す前後にバージョン番号とリビジョン番号を取得するために使用する。DirectXSetup の呼び出し前にこの関数を呼び出した場合は、現在インストールされている DirectX コンポーネントのバージョン番号とリビジョン番号が与えられる。DirectXSetup の呼び出し後で、しかもコンピュータを再起動する前にこの関数を呼び出した場合は、コンピュータを再起動した後に有効になる DirectX コンポーネントのバージョン番号とリビジョン番号が与えられる。

pdwVersion パラメータに格納されるバージョン番号は、メジャー バージョン番号とマイナー バージョン番号から成る。関数から返されたメジャー バージョン番号は、DWORD の上位 16 ビットに格納される。関数から返されたマイナー バージョン番号は、DWORD の下位 16 ビットに格納される。バージョン番号と実際のバージョンは次のように対応している。

DirectX バージョン | pdwVersion によってポイントされる値
DirectX 1 | 0x00040001
DirectX 2 | 0x00040002
DirectX 3 | 0x00040003
DirectX 5,0 | 0x00040005
DirectX 6.0 | 0x00040006
DirectX 7,0 | 0x00040007

DirectX のバージョン 4 は存在しない。

pdwRevision パラメータに格納されるバージョン番号は、リリース番号とビルド番号から成る。関数から返されたリリース番号は、DWORD の上位 16 ビットに格納される。関数から返されたビルド番号は、DWORD の下位 16 ビットに格納される。

次のサンプル コードは、DirectXSetupGetVersion から返された情報を取り出して使用する方法を示したものである。

DWORD dwVersion;
DWORD dwRevision;
if (DirectXSetupGetVersion(&dwVersion, &dwRevision))
{
    printf("DirectX version is %d.%d.%d.%d\n",
           HIWORD(dwVersion), LOWORD(dwVersion),
           HIWORD(dwRevision), LOWORD(dwRevision));
}

バージョン番号とリビジョン番号は、64 ビット データに結合して比較することができる。このとき、バージョン番号は上位 32 ビットに、リビジョン番号は下位 32 ビットにそれぞれ格納される。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXSetup


DirectXSetupSetCallback

DirectXSetupSetCallback 関数は、DirectXSetup から周期的に呼び出されるコールバック関数にポインタをセットする。コールバック関数は、セットアップの進行状況の通知と、アプリケーションのセットアップ プログラム用のカスタム ユーザー インターフェイスの実装に使用することができる。詳細については、DirectXSetupCallbackFunction を参照すること。セットアップ プログラムがコールバック関数を与えない場合、DirectXSetupSetCallback は呼び出されない。

INT WINAPI DirectXSetupSetCallback(
  DSETUP_CALLBACK  Callback
);

パラメータ

Callback
コールバック関数のアドレス。

戻り値

現状では 0 を返す。

注意

コールバック関数を設定するには、DirectXSetup を呼び出す前に DirectXSetupSetCallback を呼び出さなければならない。

DirectXSetupSetCallback に渡されるコールバック関数の名前は、セットアップ プログラムによって与えられるが、DirectXSetupCallbackFunction で与えられるプロトタイプに適合するものでなければならない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXSetupCallbackFunction、DirectXSetup


DirectXUnRegisterApplication

DirectXUnRegisterApplication 関数は、DirectPlayLobby 対応アプリケーションの登録を削除する。

int WINAPI DirectXUnRegisterApplication(
  HWND   hWnd,
  LPGUID lpGUID
);

パラメータ

hWnd
親ウィンドウのハンドル。デスクトップが親ウィンドウのときは、このパラメータに NULL を設定する。
lpGUID
削除対象となる DirectPlay アプリケーションの GUID のアドレス。

戻り値

成功すれば、登録削除が完了したことを示す TRUE を返す。失敗すれば FALSE を返す。

注意

DirectXUnRegisterApplication 関数では、システムにインストールされていない dsetup.dll と dsetup32.dll の両方が必要となるが、両方共 SDK に準備されている。

DirectXRegisterApplication 関数は、アプリケーションが DirectPlayLobby で動作するのに必要なレジストリ エントリを挿入するが、ロビー アプリケーションのインストールとアンインストールには、IDirectPlayLobby3::RegisterApplication と IDirectPlayLobby3::UnregisterApplication の各メソッドの使用を推奨する。アプリケーションのインストール時に DirectXRegisterApplication を使用した場合は、アンインストール プログラムで必ず DirectXUnRegisterApplication を使用しなければならない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXRegisterApplication


構造体

ここでは、DirectSetup で使用される以下の構造体について説明する。

  • DIRECTXREGISTERAPP
  • DSETUP_CB_UPGRADEINFO

注 : DirectX 構造体のメモリはすべて、使用前に 0 に初期化しなければならない。また、dwSize メンバを持つすべての構造体は、使用前にこのメンバを構造体のサイズ (バイト単位) に設定しなければならない。これらのタスクを構造体 DDCAPS で実行している Microsoft® DirectDraw® の例を次に示す。

DDCAPS ddcaps; // この構造体はまだ使用できない。

ZeroMemory(&ddcaps, sizeof(ddcaps));
ddcaps.dwSize = sizeof(ddcaps);

// 構造体は使用可能。
.
.


DIRECTXREGISTERAPP

DIRECTXREGISTERAPP 構造体は、DirectPlayLobby 対応アプリケーションに必要なレジストリ エントリを格納する。

typedef struct _DIRECTXREGISTERAPP {
    DWORD  dwSize;
    DWORD  dwFlags;
    LPSTR  lpszApplicationName;
    LPGUID lpGUID;
    LPSTR  lpszFilename;
    LPSTR  lpszCommandLine;
    LPSTR  lpszPath;
    LPSTR  lpszCurrentDirectory;
} DIRECTXREGISTERAPP, *PDIRECTXREGISTERAPP, *LPDIRECTXREGISTERAPP;

メンバ

dwSize
構造体の大きさ。DIRECTXREGISTERAPP 構造体の大きさに初期化されなければならない。
dwFlags
予約ビット。
lpszApplicationName
アプリケーションの名称。
lpGUID
アプリケーションのグローバル ユニーク識別子 (GUID)。
lpszFilename
呼び出される実行ファイル名。
lpszCommandLine
実行ファイルのコマンドライン引数。
lpszPath
実行ファイルのパス。
lpszCurrentDirectory
カレント ディレクトリ。通常は lpszPath と同じ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsetup.h で宣言。


DSETUP_CB_UPGRADEINFO

DSETUP_CB_UPGRADEINFO 構造体は、パラメータとしてアプリケーションで定義した DirectXSetupCallbackFunction へ渡される。この構造体には、Reason パラメータが DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE のときだけ、有効な情報が格納される。コールバック関数は、この構造体を使用して、実行するアップグレードに関するステータス情報を取得することができる。

typedef struct _DSETUP_CB_UPGRADEINFO {
    DWORD UpgradeFlags;
} DSETUP_CB_UPGRADEINFO;

メンバ

UpgradeFlags
アップグレード ステータスは 1 つ以上のフラグで示される。次の各値が定義されている。
DSETUP_CB_UPGRADE_CANTBACKUP
古いシステム コンポーネントをバック アップできない。アップグレードは実行可能だが、アップグレード後のコンポーネントやドライバの復元はできない。
DSETUP_CB_UPGRADE_DEVICE_ACTIVE
デバイスは現在使用中である。
DSETUP_CB_UPGRADE_DEVICE_DISPLAY
アップグレード対象のデバイス ドライバは、ディスプレイ デバイス用のドライバである。
DSETUP_CB_UPGRADE_DEVICE_MEDIA
アップグレード対象のデバイス ドライバは、メディア デバイス用のドライバである。
DSETUP_CB_UPGRADE_FORCE
コンポーネントがアップグレードされなければ、Windows が正常に機能しない恐れがある。アップグレードは実行される。
DSETUP_CB_UPGRADE_HASWARNINGS
DirectSetup でこのデバイスのドライバをアップグレードすることはできるが、システム上の 1 つ以上のプログラムに影響を与える恐れがある。影響を受けると見られるプログラムの名前は szMessage に格納される。アップグレードは推奨されない。
DSETUP_CB_UPGRADE_KEEP
このデバイス ドライバをアップグレードすると、システムに障害が発生する恐れがある。アップグレードは許可されない。
DSETUP_CB_UPGRADE_SAFE
DirectSetup はこのデバイス ドライバを安全にアップグレードできる。アップグレードが推奨される。安全なアップグレードとは、Windows の動作に悪影響を与えないことを示す。ハードウェアに依存する一部のプログラムについては、悪影響が及ぶ可能性がある。
DSETUP_CB_UPGRADE_UNKNOWN
このデバイスの既存のドライバが認識できない。この値の状況は頻繁に発生する。アップグレードすることにより、このデバイスの使用に悪影響を与える可能性がある。アップグレードを実行しないよう強く推奨する。

注意

UpgradeFlags からアップグレード タイプ (FORCE、KEEP、SAFE、または UNKNOWN) を取得するには、値 DSETUP_CB_UPGRADE_TYPE_MASK を使用する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsetup.h で宣言。

参照

DirectXSetupCallbackFunction


戻り値

DirectXSetup 関数は以下の値を返す。この関数では標準 COM エラーを返すこともできる。

DSETUPERR_SUCCESS
セットアップが成功した。再起動の必要はない。
DSETUPERR_SUCCESS_RESTART
セットアップが成功した。再起動する必要がある。
DSETUPERR_BADSOURCESIZE
ファイル サイズを検証できなかったか、誤りであった。
DSETUPERR_BADSOURCETIME
ファイルの日付およびタイムを検証できなかったか、誤りであった。
DSETUPERR_BADWINDOWSVERSION
DirectX はこのバージョンの Windows をサポートしていない。
DSETUPERR_CANTFINDDIR
セットアップ プログラムで作業ディレクトリが見つからなかった。
DSETUPERR_CANTFINDINF
必要な .inf ファイルが見つからなかった。
DSETUPERR_INTERNAL
内部エラーが発生した。
DSETUPERR_NEWERVERSION
DirectX の上位バージョンが既にインストールされている。上位バージョンが上書きされることはなく、以前のバージョン用に記述されたアプリケーションとも完全に互換性があるため、アプリケーションは安全にこのエラーを無視できる。
DSETUPERR_NOCOPY
ファイルのバージョンを検証できなかったか、誤りであった。
DSETUPERR_NOTPREINSTALLEDONNT
システムの Windows NT または Windows 2000 のバージョンに、DirectX の最新バージョンが含まれていない。DirectX の古いバージョンが存在するか、DirectX のどのバージョンも存在しないか、どちらかの可能性がある。
DSETUPERR_OUTOFDISKSPACE
セットアップ プログラムによるインストール中にディスク領域が足りなくなった。
DSETUPERR_SOURCEFILENOTFOUND
必要なソース ファイルのうちのいずれかが見つからなかった。
DSETUPERR_UNKNOWNOS
サポートされていないバージョンのオペレーティング システムである。
DSETUPERR_USERHITCANCEL
アプリケーションのインストールが完了する前に、[Cancel] ボタンが押された。


DirectSetup サンプル

DirectSetup の使用方法および機能を説明するサンプルとして、次のプログラムが提供されている。

  • Dinstall サンプル (C/C++)
  • DXVBSetup サンプル (Visual Basic)

DirectX サンプルには Microsoft® Visual C++® のプロジェクト ワークスペース ファイルが含まれているが、各自の開発環境で正しくコンパイルできるようにほかの設定を確認する必要がある場合がある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。


Dinstall サンプル

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。Visual Basic については、「DXVBSetup サンプル」を参照すること。

[C++]

説明

Dinstall は、DirectSetup 関数を使って DirectX サブシステムおよび DirectX ドライバをインストールするサンプルである。ここでは、コールバック関数を使って、カスタム インターフェイス (この場合はシンプルなモードレス ダイアログ ボックス) 経由でメッセージの表示とユーザー入力の取得を行う例を示している。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Dxmisc\Src\Setup

ユーザーズ ガイド

まず、DirectX SDK CD の \Redist\DirectX7 フォルダの内容をすべて Dinstall.exe と同じフォルダにコピーする。開発環境の作業ディレクトリもこのフォルダに設定する (Microsoft® Visual C++® では、[Project Settings] ダイアログ ボックスの [Debug] ページにこの設定がある)。

プログラムを実行し、[File] メニューの [Start Install] をクリックする。DirectSetup は、DirectX の模擬インストールを実行し (「プログラミング上の注意」を参照)、モードレス ダイアログ ボックスに進捗状況を表示する。[Options] メニューでは、表示するメッセージ レベルを変更できる。ただし、模擬インストールのみを行う場合は、問題発生メッセージやアップデート メッセージは表示されない。

[File] メニューの [Get Version] をクリックすると、システムに現在インストールされている DirectX のバージョン番号およびリビジョン番号が表示される。

プログラミング上の注意

\Redist\DirectX7\Directx\Drivers の各ドライバ フォルダには、Microsoft が提供する DirectX ドライバのローカライズ バージョンが保存されている。ディスク容量を節約したい場合は、作業ディレクトリからこれらのフォルダを適宜削除するとよい。

デフォルトでは、プログラムは DirectXSetup 関数に DSETUP_TESTINSTALL を渡す。これは、実際にファイルはコピーされず、レジストリの変更も行われないことを示す。実際にインストールを行うには、このフラグを関数呼び出しから削除する。

Dinstall では、インストール進捗状況の監視やメッセージのインターセプトにコールバック関数を使用している。ユーザーが指定した警告レベル (g_fStatus で追跡) に応じて、メッセージを無視したり、モードレス ダイアログ ボックスにメッセージを表示したりできる。ユーザー入力が必要な場合は適切なボタンが表示され、いずれかのボタンが押されるまで GetReply 関数がメッセージ キューを監視する。


DXVBSetup サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Dinstall サンプル」を参照すること。

[Visual Basic]

説明

DXVBSetup サンプルは、DirectSetup を Visual Basic アプリケーションで使用する方法を示したものである。

パス

Visual Basic 5 ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Dxmisc\Src\DXVB5Setup

Visual Basic 6 ソース ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Dxmisc\Src\DXVB6Setup

ユーザーズ ガイド

セットアップ アプリケーション ディレクトリには、dsetup.dll および dsetup32.dll を含む Setup というサブフォルダがなければならない。また、この中には「DirectX」 (大文字小文字の区別なし) という名前のフォルダを用意し、再配布可能なすべてのファイルおよびドライバを保存する。正しい構造のアプリケーション セットアップ ディスクは、DirectX SDK ディスクの Dx\Redist\DirectX7 フォルダの内容をすべてセットアップ プログラムのルート パスにコピーするだけで作成できる。このフォルダは、SDK のインストール時に開発用のマシンにコピーされないので、オリジナル ディスクから別途コピーする必要がある。

プログラミング上の注意

\Redist\DirectX7\Directx\Drivers の各ドライバ フォルダには、Microsoft が提供する DirectX ドライバのローカライズ バージョンが保存されている。ディスク容量を節約したい場合は、作業ディレクトリからこれらのフォルダを適宜削除するとよい。


DirectSound

ここでは、Microsoft DirectX® アプリケーション プログラミング インターフェイス (API) の DirectSound® コンポーネントに関する情報を以下のトピックに分けて説明する。

  • DirectSound について
  • DirectSound を使用する理由
  • DirectSound アーキテクチャ
  • DirectSound の要点
  • DirectSound チュートリアル
  • DirectSound リファレンス
  • DirectSound のツールとサンプル


DirectSound について

Microsoft® DirectSound® アプリケーション プログラミング インターフェイス (API) は、DirectX® API のウェーブ オーディオ コンポーネントである。DirectSound は、遅延時間 (レイテンシ) の少ないミキシング、ハードウェア アクセラレーション、サウンド デバイスへの直接アクセスを実現する。既存のデバイス ドライバとの間の互換性を維持しながら、この機能を提供する。

DirectSound により、ウェーブ サウンドのキャプチャと再生が可能になる。また C++ ではプロパティ セットもサポートし、アプリケーション開発者は、サウンド カードと関連ドライバの提供する拡張サービスを活用できる。


DirectSound を使用する理由

DirectX の最優先の設計目標はスピードにある。DirectX の他のコンポーネントと同様、DirectSound はデバイスに依存しないインターフェイスを採用し、開発者にハードウェア個別の詳細の知識を要求することなく、ハードウェアを最高の効率で使用できるようにする。アプリケーションは最も簡素なオーディオ ハードウェアでも適切に動作するが、DirectSound 用に機能拡張されたカードやドライバの特別な機能も活用できる。

ほかにも DirectSound は以下のことを容易にする。

  • 実行時にハードウェア能力を問い合わせ、特定のパーソナル コンピュータの構成に対する最善のソリューションを決定する。
  • C++ でプログラミングする場合、プロパティ セットを使用することによって、DirectSound がハードウェアを直接サポートしていない場合でも、新しいハードウェアの能力を活用できるようにする。
  • 応答を高速化するため、オーディオ ストリームの遅延時間の少ないミキシングを行う。
  • 3D サウンドを実装する。
  • サウンドをキャプチャする。

DirectSound にはこのような利点があるが、特定の状況では Windows® 標準のウェーブフォーム オーディオ機能が引き続き実用的なソリューションとなる。たとえば、アプリケーションは PlaySound や waveOut の各関数を使って、導入ミュージックのような単一のサウンドまたはオーディオ ストリームを容易に演奏できる。


DirectSound アーキテクチャ

ここでは、DirectSound コンポーネントを紹介し、DirectSound をハードウェアやほかのアプリケーションと組み合わせたときにどのように動作するかを説明する。以下のトピックについて説明する。

  • DirectSound アーキテクチャの概要
  • サウンド データ
  • 再生の概要
  • キャプチャの概要
  • プロパティ セットの概要
  • ハードウェア アブストラクションとエミュレーション
  • システムの統合


DirectSound アーキテクチャの概要

DirectSound は、デジタル サウンドのサンプルの再生とキャプチャリング、およびサンプル ソースのミキシング用の新しいモデルを実装している。DirectX API の他の要素と同様、DirectSound はハードウェアの機能を最大限に引き出し、ハードウェアがサポートしていない特定の機能をソフトウェアでエミュレートする。

[C++]

DirectSound の再生機能は、IDirectSound コンポーネント オブジェクト モデル (COM) インターフェイスと、サウンド バッファおよび 3D エフェクトを操作する他のインターフェイスによって構築されている。これらのインターフェイスは、IDirectSoundBuffer、IDirectSound3DBuffer、IDirectSound3DListener である。

DirectSound キャプチャは、IDirectSoundCapture および IDirectSoundCaptureBuffer の各 COM インターフェイスに基づいている。

もう 1 つの COM インターフェイスである IKsPropertySet は、将来採用されるものも含めたサウンド カードの拡張機能をアプリケーションが活用するための手段を提供する。

最後に IDirectSoundNotify インターフェイスは、再生やキャプチャがバッファの特定のポイントに達したときに、イベントのシグナルを送る。

DirectX API を使ったアプリケーションを作成するために理解すべき COM の概念については、「コンポーネント オブジェクト モデル」を参照すること。

[Visual Basic]

DirectSound の再生機能は、DirectSound クラスと、サウンド バッファおよび 3D エフェクトを操作する他のクラスによって構築されている。これらのクラスは、DirectSoundBuffer、DirectSound3DBuffer、DirectSound3DListener である。

DirectSound キャプチャは、DirectSoundCapture および DirectSoundCaptureBuffer の各クラスに基づいている。

最後に DirectXEvent クラスは、再生やキャプチャがバッファの特定のポイントに達したときに、DirectX7.CreateEvent メソッドで作成されたイベントと共にイベントのシグナルを送る。


サウンド データ

[C++]

IDirectSound と IDirectSoundCapture は、固定周波数のサウンドによって構成されるウェーブフォーム オーディオ データを使って機能を果たす。サウンドの特定のフォーマットは、WAVEFORMATEX 構造体を使って記述できる。この構造体は Platform SDK ドキュメントの「Multimedia Structures」でドキュメント化されているが、簡便のためにここでも簡単に説明する。

typedef struct {
    WORD  wFormatTag;
    WORD  nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD  nBlockAlign;
    WORD  wBitsPerSample;
    WORD  cbSize;
} WAVEFORMATEX;

wFormatTag メンバは、Microsoft が割り当てた一意の識別子を保持する。完全なリストはヘッダー ファイル Mmreg.h に記述されている。DirectSound で有効な唯一のタグは WAVE_FORMAT_PCM である。このタグは PCM (Pulse Code Modulation)、つまり各サンプルがサンプリング時点での振幅の信号を表す非圧縮フォーマットを意味する。DirectSoundCapture は、Audio Compression Manager を使うことにより、他のフォーマットのデータもキャプチャできる。

DirectSound で PCM 以外のデータを扱う方法の詳細については、「圧縮ウェーブ フォーマット」を参照すること。

nChannels メンバは、チャンネルの数を記述する。通常は 1 (モノラル) か 2 (ステレオ) である。ステレオ データの場合、サンプルはインターリーブされる。nSamplesPerSec メンバは、サンプリング レート (サンプリング周波数) をヘルツ (Hz) 単位で記述する。標準的な値は、11,025、22,050、44,100 である。

wBitsPerSample メンバは、各サンプルのサイズを記述する。通常は 8 ビットか 16 ビットである。nBlockAlign の値は、完全なサンプルを記録するのに必要なバイト数を意味し、PCM フォーマットでは (wBitsPerSample * nChannels / 8) に等しい値になる。nAvgBytesPerSec の値は、nBlockAlign と nSamplesPerSec の積である。

最後に、cbSize は特別なウェーブ フォーマットを記述するのに必要な追加フィールドのサイズを示す。PCM フォーマットでは、このメンバの値は常に 0 である。

[Visual Basic]

DirectSound と DirectSoundCapture は、固定周波数のサウンドによって構成されるウェーブフォーム オーディオ データを使って機能を果たす。サウンドのフォーマットは、WAVEFORMATEX 型を使って記述できる。


再生の概要

DirectSoundBuffer オブジェクトは、サウンド データを保持するバッファを表す。バッファ オブジェクトは、サウンドの再生の開始、停止、一時停止と、周波数やフォーマットなどの属性を設定するために使われる。

プライマリ サウンド バッファは、リスナーが実際に聞くオーディオを保持する。各セカンダリ サウンド バッファは、1 つのサウンドまたはオーディオ ストリームを保持する。DirectSound は自動的にプライマリ バッファを作成するが、セカンダリ バッファはアプリケーションが作成しなければならない。セカンダリ バッファ内のサウンドが再生されると、DirectSound はプライマリ バッファ内でこれらをミキシングし、出力デバイスへ送り出す。DirectSound がミキシングできるバッファ数は処理時間にのみ制限され、処理時間が許す限りミキシングすることができる。

1 つのサウンド デバイスに対して複数のアプリケーションが DirectSound オブジェクトを作成することができる。入力フォーカスがあるアプリケーションから他のアプリケーションへ移動する際に、オーディオ出力はあるアプリケーションのストリームから他のアプリケーションのストリームへと自動的に切り替わる。したがって、入力フォーカスが移動する際に、アプリケーションはバッファの再生と停止を繰り返す必要はない。

[C++]

データを正しいフォーマットに整えてセカンダリ バッファに送り込むのは、開発者の責任である。DirectSound には、サウンド ファイルやウェーブ リソースを解析する機能はない。しかし、関連するサンプル アプリケーション内に、このタスクを支援するコードが記述されている。詳細については、「ウェーブ ファイルの使い方」と、「リソースからのウェーブ データの読み込み」を参照すること。

アプリケーションは IDirectSoundNotify インターフェイスを通して、ストリーム バッファが新しいデータを受信する準備ができたときや、バッファのいずれかが停止したときにそのことを把握できる。カレント プレイ ポジションがこれらの位置のいずれかに到達すると、信号が送信される。代わりに、アプリケーションは再生カーソルの位置を定期的にポーリングすることもできる。

[Visual Basic]

短いウェーブ ファイルとリソースは、バッファが作成されるとセカンダリ バッファに直接ロードされる。さらに長いファイルでは、ファイルを解析してデータを送り込むのは開発者の責任である。詳細については、「ウェーブ ファイルの使い方」と、「リソースからのウェーブ データの読み込み」を参照すること。

アプリケーションは DirectX7.CreateEvent メソッドでイベントを作成してから DirectSoundBuffer.SetNotificationPositions メソッドを呼び出して通知位置を設定することにより、ストリーム バッファが新しいデータを受信する準備ができたときや、バッファのいずれかが停止したときにそのことを把握できる。カレント プレイ ポジションがこれらの位置のいずれかに到達すると、信号が送信される。代わりに、アプリケーションはカレント プレイ ポジションを定期的にポーリングすることもできる。

通知の詳細については、「再生バッファの通知」を参照すること。


キャプチャの概要

[C++]

DirectSoundCapture オブジェクトは、サウンド キャプチャ デバイスの能力の問い合わせや、入力ソースからオーディオをキャプチャするためのバッファの作成に使われる。DirectSoundCapture を使うと、PCM フォーマットまたは圧縮フォーマットでデータをキャプチャできる。

DirectSoundCaptureBuffer オブジェクトは、入力デバイスからデータをキャプチャするために使われるバッファを表す。再生バッファと同様、このバッファは循環という概念を採用している。入力ポインタがバッファの最後に到達すると、自動的に開始点に戻る。

DirectSoundCaptureBuffer オブジェクトのメソッドを使うと、バッファのプロパティの取得、オーディオ キャプチャの開始と停止、メモリの一部のロックができるので、ファイルに保存するなどの目的でデータを安全に取得できる。

再生の場合と同様、DirectSound は、キャプチャしたデータがバッファ内の指定された位置に到達したときや、キャプチャリングが停止したときに、その旨を通知するように要求することができる。このサービスは、IDirectSoundNotify インターフェイスで提供される。

[Visual Basic]

DirectSoundCapture オブジェクトは、サウンド キャプチャ デバイスの能力の問い合わせや、入力ソースからオーディオをキャプチャするためのバッファの作成に使われる。DirectSoundCapture を使うと、PCM フォーマットまたは圧縮フォーマットでデータをキャプチャできる。

DirectSoundCaptureBuffer オブジェクトは、入力デバイスからデータをキャプチャするために使われるバッファを表す。再生バッファと同様、このバッファは循環という概念を採用している。入力ポインタがバッファの最後に到達すると、自動的に開始点に戻る。

DirectSoundCaptureBuffer オブジェクトのメソッドを使うと、バッファのプロパティの取得、オーディオ キャプチャの開始と停止、メモリの一部のロックができるので、ファイルに保存するなどの目的でデータを安全に取得できる。

再生の場合と同様、DirectSound は、キャプチャしたデータがバッファ内の指定された位置に到達したときや、キャプチャリングが停止したときに、その旨を通知するように要求することができる。このサービスは、DirectX7.CreateEvent メソッドでイベントを作成し、DirectSoundCaptureBuffer.SetNotificationPositions メソッドで通知位置を設定することにより提供される。

通知の詳細については、「キャプチャ バッファの通知」を参照すること。


プロパティ セットの概要

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

DirectSound はプロパティセットを通して、サウンド カードと関連ドライバのメーカーが提供する拡張サービスをサポートできる。

ハードウェア ベンダーは新しい能力をプロパティとして定義し、そのプロパティの仕様を発表する。このドキュメントの対象読者であるアプリケーション開発者は、IKsPropertySet インターフェイスのメソッドを使用して、目的のハードウェア上で特定のプロパティ セットが提供されているかどうかを確認し、たとえば個別の特殊効果のオン、オフを行って、それらのプロパティを操作できる。

プロパティ セットは、DirectSound の能力を無制限に拡張することを見込んだものである。開発者は IKsPropertySet::Set という 1 つのメソッドを使って、メーカーの仕様に基づいて任意の方法でデバイスの状態を変更できる。

詳細については、「DirectSound プロパティ セット」を参照すること。


ハードウェア アブストラクションとエミュレーション

DirectSound は、オーディオ デバイス ドライバが実装するインターフェイス、つまり DirectSound ハードウェア アブストラクション レイヤ (HAL) を使ってサウンド機器へアクセスする。

DirectSound HAL は、以下の機能を提供する。

  • オーディオ機器に対するコントロールの取得と解放
  • オーディオ機器の能力の評価
  • ハードウェアが利用可能な場合の特定の操作の実行
  • ハードウェアが利用不可能な場合に障害を報告する操作の要求

デバイス ドライバは、ソフトウェア エミュレーションを一切行わない。ハードウェアの能力を DirectSound へ通知し、DirectSound からの要求をハードウェアに伝えるだけである。要求された操作をハードウェアが実行できない場合には、デバイス ドライバが要求の失敗を報告した後、DirectSound がその操作をエミュレートする。

DirectX の実行時ファイルがユーザーのシステム上にある限り、アプリケーションは DirectSound を利用できる。サウンド機器に対応する DirectSound ドライバが実装されていない場合は、DirectSound は Windows のマルチメディア ウェーブフォーム オーディオ関数 (waveIn と waveOut) を利用したハードウェア エミュレーション レイヤ (HEL) を使う。DirectSound のほとんどの機能は、HEL を通して利用できるが、ハードウェア アクセラレーションは当然不可能である。アプリケーションがエミュレーション ドライバを使って動作しているかどうかを調べるには、C++ の IDirectSound::GetCaps メソッド、または Visual Basic の DirectSound.GetCaps メソッドを呼び出し、DSCAPS_EMULDRIVER フラグをチェックする。

DirectSound は、ハードウェア ミキシングやハードウェア サウンドバッファ メモリなどのサウンド機器のアクセラレーション機能を自動的に活用する。このハードウェア アクセラレーションを使うときに、アプリケーションからハードウェアやプログラムに特に問い合わせる必要はない。ただし、ハードウェア リソースを最大限に利用するには、(さまざまな GetCaps メソッドを使って) 実行時に DirectSound への問い合わせを行ってサウンド機器の能力の全情報を入手し、特定の機能の有無に応じて最適のルーチンを使う。また、どのサウンド バッファにハードウェア アクセラレーションを適用するかを指定することもできる。


システムの統合

次の図は、DirectSound と他のシステム オーディオ コンポーネントとの関係を示している。

DirectSound 関数と Windows 標準のウェーブフォーム オーディオ関数を使うと、サウンド機器のウェーブフォーム オーディオ部分へのパスに選択肢が与えられる。1 つのデバイスでは、一度にアクセスを提供するパスは 1 つである。ウェーブフォーム オーディオ ドライバがあるデバイスを割り当てた場合、DirectSound での同デバイスへの割り当ては失敗する。同様に、DirectSound が 1 つのデバイスを割り当てた場合、ウェーブフォーム オーディオ ドライバでのデバイスの割り当ては失敗する。

2 つのサウンド デバイスがシステムにインストールされている場合、アプリケーションはDirectSound 関数とウェーブフォーム オーディオ関数のどちらかを使って、それぞれのデバイスに独立してアクセスできる。

注 : Microsoft Video for Windows は現在、ウェーブフォーム オーディオ関数を使用して、avi (audio visual interleaved、オーディオ ビデオ インターリーブ) ファイルのオーディオ トラックを再生する。したがって、アプリケーションが DirectSound を使用しているときに、ユーザーが同時に avi ファイルを再生しようとしても、そのオーディオ トラックを聞くことはできない。同様に、avi ファイルの再生と DirectSound オブジェクトの作成を同時に行おうとすると、作成関数はエラーを返す。

現在のところ、アプリケーションが DirectSound オブジェクトを解放するためには、avi ファイルを再生する前に C++ の IDirectSound::Release を呼び出すか、Visual Basic の DirectSound オブジェクトを Nothing に設定する。アプリケーションは、ビデオの再生終了後にオブジェクトとそのバッファ オブジェクトの作成と初期化をもう一度行える。


DirectSound の要点

ここでは、サウンドの再生とキャプチャを行うためのさまざまな DirectSound インターフェイスの使い方の概要を記述する。以下のトピックについて説明する。

  • DirectSound デバイス
  • DirectSound バッファ
  • DirectSound の 3D への応用
  • DirectSound 3D バッファ
  • DirectSound 3D リスナー
  • DirectSoundCapture
  • DirectSound プロパティ セット
  • DirectSound の性能の最適化
  • ウェーブ ファイルの使い方
  • リソースからのウェーブ データの読み込み
[C++]

注 : このトピックのメソッド呼び出し例のほとんどは C 言語形式で与えられ、関数へのポインタから成るテーブルへのポインタを使ってメソッドにアクセスするが、どの呼び出しでもこのポインタを最初のパラメータとする必要がある。たとえば、C から IDirectSound::GetCaps メソッドを呼び出すときは、次の形をとる。

lpDirectSound->lpVtbl->GetCaps(lpDirectSound, &dscaps);

C++ 形式で同じメソッドを呼び出すときは、COM インターフェイス メソッドをクラス メソッドのように扱い、次のようになる。

lpDirectSound->GetCaps(&dscaps);

Dsound.h に定義されているマクロは、環境に応じて、C と C++ どちらの形式のメソッド呼び出しをも拡張する。これらのマクロは C による呼び出しを簡易化し、どちらの言語でも利用できるルーチンを開発可能にする。たとえば、次のようにできる。

IDirectSound_GetCaps(lpDirectSound, &dscaps);

[C++,Visual Basic]


DirectSound デバイス

アプリケーションにDirectSound を実装する最初のステップは、サウンド デバイスを表す DirectSound オブジェクトを作成することである。

ここでは、利用可能なサウンド デバイスの列挙、デバイスに対する DirectSound オブジェクトの作成、オブジェクトのメソッドを使った協調レベルの設定、デバイス能力の取得、サウンド バッファの作成、システム スピーカの構成、ハードウェア メモリの圧縮をアプリケーションが行う方法について説明する。

  • サウンド デバイスの列挙
  • DirectSound オブジェクトの作成
  • 協調レベル
  • デバイスの能力
  • スピーカの構成
  • ハードウェア メモリの圧縮


サウンド デバイスの列挙

[C++]

ユーザーが好む再生装置で単純にサウンドを再生するだけのアプリケーションでは、利用可能なデバイスを列挙する必要はない。デバイス識別子として NULL を指定して DirectSound オブジェクトを作成する場合、デフォルトのデバイスが存在すると、インターフェイスは自動的にそのデバイスに関連付けられる。デバイス ドライバが存在しない場合は、DirectSoundCreate 関数の呼び出しは失敗する。

しかし、特定の種類のデバイスを探している場合や、複数のデバイスを使って動作する必要がある場合は、システム上で利用可能なデバイスを DirectSound に列挙させなければならない。

列挙は 3 つの目的で使われる。

  • 利用可能なハードウェアを報告。
  • 各デバイスに GUID を供給。
  • 各デバイスを列挙したときに、デバイスに対して DirectSound を初期化。その結果、各デバイスの能力をチェックできる。

デバイスを列挙するには、DirectSound がデバイスを見つけるたびに呼び出すコールバック関数を最初に作成しなければならない。必要なすべての処理をこの関数内で実行し、関数に任意の名前を付けることができるが、この関数はプロトタイプである DSEnumCallback と同じ形式で宣言しなければならない。このコールバック関数は、列挙を続ける場合は TRUE、その他 (たとえば必要な能力を備えたデバイスを見つけた後など) の場合は FALSE を返さなければならない。

次のコールバック関数は、列挙された各デバイスに関する情報をコンボ ボックスに追加する。最初の 3 つのパラメータがデバイス ドライバによって供給されている点に注意すること。4 番目のパラメータは DirectSoundEnumerate 関数から引き渡される。

BOOL CALLBACK DSEnumProc(LPGUID lpGUID,
                         LPCTSTR lpszDesc,
                         LPCTSTR lpszDrvName,
                         LPVOID lpContext )
{
    HWND   hCombo = *(HWND *)lpContext;
    LPGUID lpTemp = NULL;

    if ( lpGUID != NULL )
    {
        if (( lpTemp = malloc( sizeof(GUID))) == NULL )
        return( TRUE );

        memcpy( lpTemp, lpGUID, sizeof(GUID));
    }

    ComboBox_AddString( hCombo, lpszDesc );
    ComboBox_SetItemData( hCombo,
                ComboBox_FindString( hCombo, 0, lpszDesc ),
                lpTemp );
    return( TRUE );
}

コンボ ボックスを含むダイアログを初期化する際に、列挙を行う。

if FAILED(DirectSoundEnumerate((LPDSENUMCALLBACK)DSEnumProc,
        &hCombo))
{
    EndDialog( hDlg, TRUE );
    return( TRUE );
}

この例では、コンボ ボックスのハンドルのアドレスは DirectSoundEnumerate に送られ、次にコールバック関数に渡される。このパラメータは、コールバック関数内でアクセスしたい任意の 32 ビットの値とすることができる。

[Visual Basic]

ユーザーが好む再生装置で単純にサウンドを再生するだけのアプリケーションでは、利用可能なデバイスを列挙する必要はない。デバイス識別子として空の文字列を渡して DirectSound オブジェクトを作成する場合、デフォルトのデバイスが存在すると、オブジェクトは自動的にそのデバイスに関連付けられる。デバイス ドライバが存在しない場合は、DirectX7.DirectSoundCreate メソッドの呼び出しは失敗する。

しかし、特定の種類のデバイスを探している場合や、複数のデバイスを使って動作する必要がある場合は、システム上で利用可能なデバイスを DirectSound に列挙させなければならない。

列挙は 3 つの目的で使われる。

  • 利用可能なハードウェアを報告。
  • 各デバイスに GUID を供給。
  • 各デバイスを列挙したときに、デバイスに対して DirectSound を初期化。その結果、各デバイスの能力をチェックできる。

デバイスを列挙するには、DirectX7.GetDSEnum メソッドを最初に呼び出して、DirectSound の利用可能なデバイスのコレクションを保持する DirectSoundEnum オブジェクトを作成しなければならない。利用可能なデバイス数を決定するには、DirectSoundEnum.GetCount メソッドを呼び出す。そして各デバイスの情報は、DirectSoundEnum.GetDescription、DirectSoundEnum.GetGuid、DirectSoundEnum.GetName の各メソッドを呼び出し、コレクション内の特定のデバイスをインデックス引数として渡すことで取得する。


DirectSound オブジェクトの作成

[C++]

DirectSound オブジェクトを作成する最も簡単な方法は、DirectSoundCreate 関数を使うことである。この関数の最初のパラメータは、このオブジェクトに関連付けられるデバイスの GUID を指定する。この GUID は、「サウンド デバイスの列挙」で取得できる。ほかに、デフォルトのデバイスに対応するオブジェクトを作成するには、単純に NULL を渡せばよい。

LPDIRECTSOUND lpds;
HRESULT hr = DirectSoundCreate(NULL, &lpds, NULL));

サウンド デバイスが存在しない場合や、ウェーブフォーム オーディオ関数 (DirectSound ではない) を利用するアプリケーションがサウンド デバイスを制御している場合は、この関数はエラーを返す。アプリケーションはこの呼び出しが失敗した場合に備えて、サウンドなしでアプリケーションを続行するか、既にサウンド デバイスを使っているアプリケーションを閉じるようユーザーにプロンプトを表示するか、どちらかの準備をする必要がある。

CoCreateInstance 関数を使って、次のように DirectSound オブジェクトを作成することもできる。

  1. アプリケーションの起動時に CoInitialize を呼び出し、NULL を指定して COM を初期化する。
    if FAILED(CoInitialize(NULL))
    return FALSE;
  2. DirectSoundCreate 関数ではなく、CoCreateInstance と IDirectSound::Initialize の各メソッドを使って DirectSound オブジェクトを作成する。
    LPDIRECTSOUND lpds;
dsrval = CoCreateInstance(&CLSID_DirectSound,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          &IID_IDirectSound,
                          &lpds);
if SUCCEEDED(dsrval)
    dsrval = IDirectSound_Initialize(lpds, NULL);

CLSID_DirectSound は、DirectSound のドライバ オブジェクト クラスのクラス識別子であり、IID_IDirectSound は必須の DirectSound インターフェイスである。lpds パラメータは、CoCreateInstance が返す、初期化されていないオブジェクトである。

CoCreateInstance 関数を使って作成した DirectSound を使う前に、IDirectSound::Initialize メソッドを呼び出さなければならない。このメソッドは、DirectSoundCreate が使うドライバの GUID パラメータ (この場合は NULL) を取る。DirectSound オブジェクトを初期化した後、DirectSoundCreate 関数を使って作成した場合と同様、このオブジェクトの使用と解放が行える。

アプリケーションを閉じる前に、次のように CoUninitialize 関数を呼び出して COM ライブラリを閉じる。

CoUninitialize();
[Visual Basic]

DirectX7.DirectSoundCreate メソッドを使って DirectSound オブジェクトを作成する。単一のパラメータで、このオブジェクトに関連付けるデバイスの GUID を指定する。この GUID は、「サウンド デバイスの列挙」で取得できる。ほかに、デフォルトのデバイスに対応するオブジェクトを作成するには、次のように空の文字列を渡せばよい。

Dim m_dx As New DirectX7
Dim m_ds As DirectSound
Set m_ds = m_dx.DirectSoundCreate("")

サウンド デバイスが存在しない場合や、標準的なウェーブフォーム オーディオ関数 (DirectSound ではない) を利用するアプリケーションがサウンド デバイスを制御している場合は、このメソッドはエラーとなる。アプリケーションはこの呼び出しが失敗した場合に備えて、サウンドなしでアプリケーションを続行するか、サウンド デバイスを使っているアプリケーションを閉じるようユーザーにプロンプトを表示するか、どちらかの準備をする必要がある。


協調レベル

Windows はマルチタスク環境なので、複数のアプリケーションが任意の時点で同じデバイス ドライバを使って動作することがある。DirectX は協調レベルを使って、各アプリケーションが不適切な方法または不適切なタイミングでデバイスにアクセスしないことを保証する。DirectSound の各アプリケーションは、デバイスに対して認められるアクセス範囲を決定する 1 つの協調レベルを持つ。

[C++]

DirectSound オブジェクトを作成した後で、サウンドを再生する前に IDirectSound::SetCooperativeLevel メソッドを使ってデバイスの協調レベルを設定しなければならない。

[Visual Basic]

DirectSound オブジェクトを作成した後で、サウンドを再生する前に DirectSound.SetCooperativeLevel メソッドを使ってデバイスの協調レベルを設定しなければならない。

DirectSound は、標準、優先、排他、書き込み優先の 4 つの協調レベルを定義している。これらは、DSSCL_NORMAL、DSSCL_PRIORITY、DSSCL_EXCLUSIVE、DSSCL_WRITEPRIMARY の値で表される。

ゲーム アプリケーションは、ほとんどすべての環境で DSSCL_PRIORITY を使用する。このレベルは、サンプリング レートとビット深度に対するアプリケーション制御を可能にしながら、最も強力に動作する。また、優先協調レベルでは、他のアプリケーション (IP テレフォニなど) からのオーディオをゲームからのオーディオと共に聞くこともできる。優先レベルと排他レベルは同じ性能を提供するので、DSSCL_EXCLUSIVE は他のすべてのアプリケーションを無音にするよう要求するアプリケーションに対してのみ使うべきである。たとえば、ミュージックオーサリング アプリケーションでは、再生中に他のオーディオが聞こえないことが重要である。

[C++]

次の C の例は「DirectSound オブジェクトの作成」で初期化した DirectSound デバイスの協調レベルを設定する。hwnd パラメータは、アプリケーション ウインドウへのハンドルである。

HRESULT hr = lpDirectSound->lpVtbl->SetCooperativeLevel(
        lpDirectSound, hwnd, DSSCL_PRIORITY);
[Visual Basic]

次のコード例は「DirectSound オブジェクトの作成」で初期化した DirectSound デバイスの協調レベルを設定する。hwnd 引数は、アプリケーション ウインドウへのハンドルである。

m_ds.SetCooperativeLevel Me.hWnd, DSSCL_PRIORITY

標準協調レベル

標準協調レベルでは、アプリケーションは、プライマリ サウンド バッファのフォーマットの設定、プライマリ バッファへの書き込み、デバイスのオンボード メモリの圧縮が行えない。この協調レベルを使うすべてのアプリケーションは、22kHz、ステレオ サウンド、8 ビット サンプリングのプライマリ バッファ フォーマットを使うので、デバイスはアプリケーション間で最も円滑に切り替えられる。

優先協調レベル

優先協調レベルで DirectSound デバイスを使うと、アプリケーションはハードウェア ミキシングなどのハードウェア リソースに対して最高の権限を確保し、プライマリ サウンド バッファのフォーマットの設定、デバイスのオンボード メモリの圧縮を行える。

排他協調レベル

排他協調レベルでは、アプリケーションは優先レベルのすべての特権を持つほか、そのアプリケーションがフォアグラウンドで実行されている場合は、そのプライマリ サウンド バッファの音だけが聞こえる。

書き込み優先協調レベル

最上位の協調レベルは書き込み優先である。この協調レベルで DirectSound デバイスを使うと、アプリケーションはプライマリ サウンド バッファに直接アクセスできる。このモードでは、アプリケーションはプライマリ バッファに直接書き込みを行わなければならない。この書き込み中は、セカンダリ バッファを再生できない。

[C++]

プライマリ バッファ内のオーディオ サンプルに直接書き込みのアクセスをするには、アプリケーションを書き込み優先レベルに設定しなければならない。アプリケーションをこのレベルに設定しておかないと、プライマリ バッファに対する C++ の IDirectSoundBuffer::Lock メソッド、または Visual Basic の DirectSoundBuffer.ReadBuffer と DirectSoundBuffer.WriteBuffer のすべての呼び出しは失敗する。

書き込み優先協調レベルに設定されたアプリケーションがフォアグラウンドになると、他のアプリケーションのすべてのセカンダリ バッファは停止され、「失われた」とマークされる。最初のアプリケーションがバックグラウンドに移ると、そのプライマリ バッファは「失われた」とマークされ、アプリケーションが再度フォアグラウンドに移るときにはこのバッファを復元しなければならない。詳細については、「バッファ管理」を参照すること。

DirectSound ドライバがユーザーのシステムに存在していない場合は、書き込み優先レベルの設定はできない。この状況に該当するかどうかを確認するには、C++ の IDirectSound::GetCaps メソッドか Visual Basic の DirectSound.GetCaps メソッドを呼び出して、DSCAPS 構造体の DSCAPS_EMULDRIVER フラグをチェックする。

詳細については、「プライマリ バッファへのアクセス」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでは、DSSCL_WRITEPRIMARY 協調レベルを使うべきではない。


デバイスの能力

DirectSound を使うと、アプリケーションはサウンド デバイスのハードウェア能力を取得できる。DirectSound は利用可能なハードウェア アクセラレーションを自動的に利用するので、アプリケーションでは、通常この取得を行う必要はない。しかし高性能のアプリケーションはこの情報を利用し、利用可能なハードウェアに対してサウンドの要求事項を評価できる。たとえば、ハードウェア ミキシングが利用可能な場合は、利用不可能な場合に比べて、アプリケーションがより多くのサウンドを再生できるはずである。

[C++]

DirectSoundCreate 関数を呼び出して DirectSound オブジェクトを作成した後は、IDirectSound::GetCaps メソッドを使ってサウンド デバイスの能力を取得できる。

次の例は、「DirectSound オブジェクトの作成」で初期化したデバイスの能力を取得する。

DSCAPS dscaps;

dscaps.dwSize = sizeof(DSCAPS);
HRESULT hr = lpDirectSound->lpVtbl->GetCaps(lpDirectSound,
    &dscaps);

DSCAPS 構造体は、サウンド デバイスの能力とリソースに関する情報を受け取るが、この中にはタイプごとの最大のリソースと現在利用可能なリソースが含まれる。このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しなければならない点に注意すること。

アプリケーションがハードウェア能力を評価する場合は、バッファ割り当てを行うたびに IDirectSound::GetCaps メソッドを呼び出して、次のバッファを作成するのに十分なリソースがあるかどうかを確認すべきである。

[Visual Basic]

DirectX7.DirectSoundCreate メソッドを呼び出して DirectSound オブジェクトを作成した後は、DirectSound.GetCaps メソッドを使ってサウンド デバイスの能力を取得できる。

次の例は、「DirectSound オブジェクトの作成」で初期化したデバイスの能力を取得する。

Dim DSCAPS As DSCAPS

m_ds.GetCaps DSCAPS

DSCAPS 型は、サウンド デバイスの能力とリソースに関する情報を受け取るが、この中にはタイプごとの最大のリソースと現在利用可能なリソースが含まれる。

アプリケーションがハードウェア能力を評価する場合は、バッファ割り当てを行うたびに DirectSound.GetCaps メソッドを呼び出して、次のバッファを作成するのに十分なリソースがあるかどうかを確認すべきである。


スピーカの構成

DirectSound は、スピーカがリスナーに対する相対的な位置をとるスピーカ構成を使って、ユーザーのサウンド システムに合わせて 3D エフェクトを最適化する。

[C++]

Windows 98 と Windows 2000 では、ユーザーはコントロール パネルを使ってスピーカ構成を設定できる。アプリケーションは IDirectSound::GetSpeakerConfig を使ってこの値を取り出し、IDirectSound::SetSpeakerConfig を呼び出してその値を変更できる。

[Visual Basic]

Windows 98 と Windows 2000 では、ユーザーはコントロール パネルを使ってスピーカ構成を設定できる。アプリケーションは DirectSound.GetSpeakerConfig を使ってこの値を取り出し、DirectSound.SetSpeakerConfig を呼び出してその値を変更できる。

Windows 95 では、GetSpeakerConfig は単純に、デフォルトの値または SetSpeakerConfig で設定した直前の値を返す。


ハードウェア メモリの圧縮

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

アプリケーションは最小限の協調レベルを備えていることを前提として、IDirectSound::Compact メソッドを使って、任意のオンボード サウンド メモリを移動して連続ブロックを形成し、フリー メモリの最大部分を使用可能にできる。


DirectSound バッファ

ここでは、サウンドを再生するための基本的な機構である DirectSoundBuffer オブジェクトの作成と管理について扱う。次のトピックを取り上げる。

  • バッファの基本
  • セカンダリ バッファの作成
  • ダイナミック ボイス管理
  • バッファ コントロール オプション
  • プライマリ バッファへのアクセス
  • スタティック バッファの書き込みと再生
  • ストリーム バッファの使い方
  • 再生のコントロール
  • カレント プレイ ポジションとカレント ライト ポジション
  • 再生バッファの通知
  • サウンドのミキシング
  • カスタム ミキサー
  • バッファ管理
  • 圧縮ウェーブ フォーマット


バッファの基本

アプリケーションが DirectSound を初期化すると、DirectSound はサウンドのミキシングと出力デバイスへの送信をするために、プライマリ サウンド バッファの作成と管理を自動的に行う。

アプリケーションは、個々のサウンドの保存と再生をするために、少なくとも 1 つのセカンダリ サウンド バッファを作成しなければならない。この方法の詳細については、「セカンダリ バッファの作成」を参照すること。

セカンダリ バッファは、アプリケーションが動作している間常に持続することも、不要になったときに削除することもできる。セカンダリ バッファには、ゲーム中の効果音など繰り返し再生される 1 つのサウンドを格納したり、適宜新しいデータを記録することもできる。アプリケーションは、セカンダリ バッファに記憶されているサウンドを 1 つのイベント、または連続再生されるループ サウンドとして再生できる。サウンド ファイルのデータが非常に大きく、メモリに記憶しておくことが実用的ではない場合、データをストリームするためにセカンダリ バッファを利用できる。

[C++]

IDirectSound::DuplicateSoundBuffer メソッドを使って、複数のセカンダリ バッファを同じ物理メモリ内に作成できる。プライマリ サウンド バッファは複製できない。元のバッファがハードウェア メモリに置かれていて、重複バッファ用のハードウェア リソースが利用不可能な場合は、この呼び出しは失敗する。同様に、たとえ呼び出しが成功したとしても、実際に重複バッファが元のバッファとメモリを共有するとは限らないので、これらの変更がすべての重複バッファに反映されるであろうという予測のもとにバッファを変更するべきではない。

[Visual Basic]

DirectSound.DuplicateSoundBuffer メソッドを使って、複数のセカンダリ バッファを同じ物理メモリ内に作成できる。プライマリ サウンド バッファは複製できない。元のバッファがハードウェア メモリに置かれていて、重複バッファ用のハードウェア リソースが利用不可能な場合は、この呼び出しは失敗する。

異なるセカンダリ バッファのサウンドは、これらを同時に再生するだけでミキシングできる。処理能力の限界内であれば、任意の数のセカンダリ バッファを同時に再生できる。

DirectSound ミキサーの遅延時間は 20 ミリ秒の短さなので、再生開始までの遅れは感知できない。この状態では、アプリケーションがバッファを再生し、即座に画面でアニメーションを開始すると、オーディオとビデオは同時にスタートするように見える。ただし、DirectSound がハードウェア機能をソフトウェアでエミュレートしなければならない場合は、ミキサーは短い遅延時間を達成できず、サウンドが再生されるまでにやや長め (標準では 100～150 ミリ秒) の遅れが生じる。

[C++]

通常、開発者はプライマリ バッファを意識する必要はまったくない。DirectSound が内部で管理を行う。しかし、アプリケーションが固有のミキシングを行う場合は、開発者がプライマリ バッファに直接書き込みを行う必要がある。これを行うと、セカンダリ バッファを同時には利用できない。詳細については、「プライマリ バッファへのアクセス」を参照すること。


セカンダリ バッファの作成

[C++]

サウンド バッファを作成するには、アプリケーションが DSBUFFERDESC 構造体への書き込みを行い、そのアドレスを IDirectSound::CreateSoundBuffer メソッドに渡す。このメソッドは DirectSoundBuffer オブジェクトを作成し、IDirectSoundBuffer インターフェイスへのポインタを返す。アプリケーションはこのインターフェイスをバッファの操作と再生に使用する。

次の例は、基本的なセカンダリ サウンド バッファを作成する方法を示す。

BOOL AppCreateBasicBuffer(
        LPDIRECTSOUND lpDirectSound,
        LPDIRECTSOUNDBUFFER *lplpDsb)
{
    PCMWAVEFORMAT pcmwf;
    DSBUFFERDESC dsbdesc;
    HRESULT hr;

    // ウェーブ フォーマット構造体を設定する。
    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));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags =
        DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY;

    // 3 秒のバッファ。
    dsbdesc.dwBufferBytes = 3 * pcmwf.wf.nAvgBytesPerSec;
    dsbdesc.lpwfxFormat = (LPWAVEFORMATEX)&pcmwf;
    // バッファを作成する。
    hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound,
        &dsbdesc, lplpDsb, NULL);
    if SUCCEEDED(hr)
    {
        // 有効なインターフェイスは *lplpDsb 内にある。
        return TRUE;
    }
    else
    {
        // 失敗。
        *lplpDsb = NULL;
        return FALSE;
    }
}

アプリケーションは、最も重要なサウンドのバッファを最初に作成すべきである。DirectSound はハードウェア リソースを最初のバッファに割り当て、その利点を生かす。ハードウェア バッファはサウンド カード プロセッサでミキシングされるので、アプリケーション性能にほとんど影響を及ぼさない。

バッファの位置を DirectSound に決めさせずに自分で指定したい場合は、DSBUFFERDESC 構造体に DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE のどちらかのフラグを設定する。DSBCAPS_LOCHARDWARE フラグを設定し、ハードウェア リソースが不足している場合、バッファの作成要求は失敗する。

DirectSound のボイス管理機能を利用したい場合は、バッファの作成時に DSBCAPS_LOCDEFER フラグを指定する。このフラグは、バッファに対するリソースの割り当てを、バッファが再生されるまで遅延する。

既存のバッファの位置を確認するには、IDirectSoundBuffer::GetCaps メソッドを使い、DSBCAPS 構造体の dwFlags メンバをチェックして、DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらのフラグになっているかを調べる。どちらかが必ず指定されている。

DSBCAPS_STATIC フラグを設定すると、可能な場合はバッファをオンボードのハードウェア メモリに作成すべきであることが DirectSound に通知される。ハードウェア バッファが利用できない場合でも、IDirectSound::CreateSoundBuffer メソッドは失敗しない。このフラグは、バッファ用にシステム メモリを使う最近のサウンド カードの多くには影響しない。ハードウェア スタティック バッファは、繰り返し再生される短いサウンドに対してだけ使うべきである。

DirectSoundBuffer オブジェクトは、これを作成した DirectSound オブジェクトが所有する。DirectSound オブジェクトが解放されると、このオブジェクトが作成したすべてのバッファも解放され、参照できなくなる。

[Visual Basic]

サウンド バッファを作成するには、DirectSound.CreateSoundBuffer、DirectSound.CreateSoundBufferFromFile、または DirectSound.CreateSoundBufferFromResource メソッドを呼び出す。このメソッドは、バッファの操作と再生に使われる DirectSoundBuffer オブジェクトを作成して返す。

DirectSound.CreateSoundBufferFromFile と DirectSound.CreateSoundBufferFromResource は、サウンドがそれほど長くない場合に使うのに適したメソッドである。DirectSound は、サウンド全体を保持するのに十分なバッファを作成し、ファイルやリソースからのデータをそのバッファに書き込む。DirectSound.CreateSoundBuffer はストリーム バッファに適しているが、開発者がウェーブ ファイルやリソースを解析し、バッファに対するデータのストリーミング処理を行わなければならない。

CreateSoundBuffer は、DirectSound3Dlistener オブジェクトを取得できるプライマリ バッファの作成にも使われる。詳細については、「DirectSound3DListener オブジェクトの取得」を参照すること。

次の例は、基本的なセカンダリ サウンド バッファを作成する方法を示す。

Dim m_dx As New DirectX7
Dim m_ds As DirectSound

Private Sub Form_Load()
  Set m_ds = m_dx.DirectSoundCreate("")
  CreateSoundBuffer
End Sub

Public Sub CreateSoundBuffer()
  Dim m_dsb As DirectSoundBuffer
  Dim buffdesc As DSBUFFERDESC
  Dim format As WAVEFORMATEX

  ' ウェーブ フォーマットを指定する。

  format.nFormatTag = WAVE_FORMAT_PCM
  format.nChannels = 2
  format.lSamplesPerSec = 22050
  format.nBitsPerSample = 16
  format.nBlockAlign = (format.nChannels * format.nBitsPerSample) / 8
  format.lAvgBytesPerSec = format.lSamplesPerSec * format.nBlockAlign
  format.nSize = 0

  ' 作成するサウンド バッファを記述する。

  buffdesc.lBufferBytes = format.lAvgBytesPerSec
  buffdesc.lFlags = DSBCAPS_CTRLPAN Or DSBCAPS_CTRLVOLUME _
          Or DSBCAPS_CTRLFREQUENCY

  ' バッファを作成する。

  Set m_dsb = m_ds.CreateSoundBuffer(buffdesc, format)
End Sub

DSBUFFERDESC 型は、フォーマット、サイズ、能力など、希望のバッファの特性を記述する。アプリケーションは必要な能力を指定しなければならない。さもないと、それらの能力は利用できない。たとえば、アプリケーションが DSBCAPS_CTRLFREQUENCY フラグを指定せずにバッファを作成すると、DirectSoundBuffer.SetFrequency に対するすべての呼び出しは失敗する。

アプリケーションは、最も重要なサウンドのバッファを最初に作成すべきである。DirectSound はハードウェア リソースを最初のバッファに割り当て、その利点を生かす。ハードウェア バッファはサウンド カード プロセッサでミキシングされるので、アプリケーション性能にほとんど影響を及ぼさない。

バッファの位置を DirectSound に決めさせずに自分で指定したい場合は、DSBUFFERDESC 型に DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE のどちらかのフラグを設定する。DSBCAPS_LOCHARDWARE フラグを設定し、ハードウェア リソースが不足している場合、バッファの作成要求は失敗する。

既存のバッファの位置を確認するには、DirectSoundBuffer.GetCaps メソッドを使い、DSBCAPS 型の lFlags メンバをチェックして、DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらのフラグになっているかを調べる。どちらかが必ず指定されている。

DSBCAPS_STATIC フラグを設定すると、可能な場合はバッファをオンボードのハードウェア メモリに作成すべきであることが DirectSound に通知される。ハードウェア バッファが利用できない場合でも、IDirectSound::CreateSoundBuffer メソッドは失敗しない。このフラグは、バッファ用にシステム メモリを使う最近のサウンド カードの多くには影響しない。ハードウェア スタティック バッファは、繰り返し再生される短いサウンドに対してだけ使うべきである。


ダイナミック ボイス管理

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

多くのサウンド カードは固有のセカンダリ バッファを維持し、3D エフェクトとそのミキシングを処理する。これらのハードウェア バッファは、呼び出しの際、通常はカード自体ではなくシステム メモリに配置される。しかし、これらはデバイスが管理するので、システム プロセッサ上ではソフトウェア バッファよりも要求ははるかに少なくなる。したがって、ハードウェアにできる限り多くのバッファ、特に 3D バッファを持つことが最も効率的である。

デフォルトでは、DirectSound は可能であれば常にバッファをハードウェアに置く。しかし、DirectSound はデバイスが一度に再生できるだけのハードウェア バッファしか作成できない。つまり、ハードウェア バッファ数は、利用可能なハードウェア ボイスで制限される。DirectSound は、バッファが作成されるときにハードウェア ボイスを割り当て、バッファが不要になったときだけ解放する。ボイスは、バッファが再生中でないときもフリーではない。アプリケーションが多くのバッファを作成する場合、いくつかのバッファがソフトウェアに存在する可能性がある。つまり、サウンド カードではなく CPU でバッファの管理とミキシングが行われる。

ダイナミック ボイス管理を使うと、バッファが再生されるまでボイス割り当てを遅延したり、DirectSound が優先順位の低いサウンドを早めに停止してリソースを新しいサウンドに割り当てることにより、ハードウェア リソースの利用制限を克服できる。

ハードウェア ミキシングと 3D エフェクトに対するリソースの割り当てをバッファが再生されるまで遅延するには、IDirectSound::CreateSoundBuffer に渡される DSBUFFERDESC 構造体に DSBCAPS_LOCDEFER フラグを指定する。DSBCAPS_LOCDEFER フラグによって作成されたバッファ上の IDirectSoundBuffer::Play を呼び出す場合、DirectSound は可能であればハードウェアにバッファを配置し、それ以外の場合はソフトウェアに配置する。

Play を呼び出す場合は、下表に示すフラグの 1 つ、もしくは最初の 2 つのフラグのどちらかを 3 番目のフラグと組み合わせて渡すことで、バッファに対するハードウェア ボイスの解放を試みることができる。その後、DirectSound はフラグの指定する終了基準に適した再生バッファを検索する。

フラグ | 基準
DSBPLAY_TERMINATEBY_TIME | どの候補バッファよりも長く再生されているバッファを選択する。
DSBPLAY_TERMINATEBY_DISTANCE | リスナーから最も遠い 3D の候補バッファを選択する。
DSBPLAY_TERMINATEBY_PRIORITY | IDirectSoundBuffer::Play の dwPriority パラメータの設定に基づき、候補バッファのうち最も優先度の低いバッファを選択する。このフラグを他の 2 つのフラグのどちらかと組み合わせると、そのフラグは優先度が等しい場合だけに使われる。

適切なバッファが見つかると、DirectSound はそのバッファを停止し、使用していたボイスを新たに再生されるバッファに割り当てる。どのバッファも終了基準に適していない場合は、DSBPLAY_LOCHARDWARE フラグが指定されていなければ、新たに再生されるバッファはソフトウェアで再生される。このフラグが指定されている場合、Play に対する呼び出しは失敗する。

遅延バッファの再生時の処理についての詳細は、IDirectSoundBuffer::Play を参照すること。

注 : バッファの作成時は、DSBCAPS_LOCDEFER フラグを DSBCAPS_STATIC フラグと組み合わせて使わないこと。PCI カードのあるものの場合のように、オンカード メモリが利用可能なときには、DSBCAPS_STATIC バッファはこのメモリに置かれる。DSBCAPS_LOCDEFER フラグでこのようなバッファを作成する場合、バッファ メモリは IDirectSoundBuffer::Play に対する最初の呼び出しまでサウンド カードにコピーされず、不適切な遅れが生じる。


バッファ コントロール オプション

[C++]

サウンド バッファを作成するときに、バッファが必要とするコントロール オプションを指定しなければならない。これには DSBUFFERDESC 構造体の dwFlags メンバを使用する。この構造体は、1 つまたは複数の DSBCAPS_CTRL* フラグを保持できる。次のコントロールが利用できる。

  • 3D プロパティ
  • 周波数
  • パン
  • ボリューム
  • 位置の通知

あらゆるサウンド カードから最高の性能を得るには、アプリケーションが使うオプションだけを指定すべきである。

DirectSound はコントロール オプションを使って、サウンド バッファにハードウェア リソースを割り当てられるかどうかを決定する。たとえば、あるデバイスがハードウェア バッファをサポートしていて、それらのバッファにパン コントロールを提供していないとする。この場合、DirectSound は DSBCAPS_CTRLPAN フラグが指定されていない場合に限って、ハードウェア アクセラレーションを使う。

バッファが備えていないコントロールを使おうとすると、メソッドは失敗する。たとえば、IDirectSoundBuffer::SetVolume メソッドを使ってボリュームを変更しようとするとき、そのバッファの作成時に DSBCAPS_CTRLVOLUME フラグが指定されていた場合に限ってメソッドは成功する。このフラグが指定されていなかった場合はメソッドは失敗に終わり、DSERR_CONTROLUNAVAIL エラーコードが返される。

[Visual Basic]

サウンド バッファを作成するときに、バッファが必要とするコントロール オプションを指定しなければならない。これには DSBUFFERDESC 型の lFlags メンバを使用する。この構造体は、1 つまたは複数の DSBCAPS_CTRL* フラグを保持できる。次のコントロールが利用できる。

  • 3D プロパティ
  • 周波数
  • パン
  • ボリューム
  • 位置の通知

あらゆるサウンド カードから最高の性能を得るには、アプリケーションが使うオプションだけを指定すべきである。

DirectSound はコントロール オプションを使って、サウンド バッファにハードウェア リソースを割り当てられるかどうかを決定する。たとえば、あるデバイスがハードウェア バッファをサポートしていて、それらのバッファにパン コントロールを提供していないとする。この場合、DirectSound は DSBCAPS_CTRLPAN フラグが指定されていない場合に限って、ハードウェア アクセラレーションを使う。

バッファが備えていないコントロールを使おうとすると、メソッドは失敗する。たとえば、DirectSoundBuffer.SetVolume メソッドを使ってボリュームを変更しようとするとき、そのバッファの作成時に DSBCAPS_CTRLVOLUME フラグが指定されていた場合に限ってメソッドは成功する。このフラグが指定されていなかった場合はメソッドは失敗に終わり、DSERR_CONTROLUNAVAIL エラー値が返される。

パン コントロールと 3D 処理は、互いに排他的である。バッファの作成時に DSBCAPS_CTRL3D と DSBCAPS_CTRLPAN をともに指定すると、エラーになる。


プライマリ バッファへのアクセス

[Visual Basic]

バッファ記述で DSBCAPS_PRIMARYBUFFER フラグを指定し、この記述を DirectSound.CreateSoundBuffer に渡すことにより、プライマリ バッファ オブジェクトを作成できる。このような処理を行う最も一般的な状況として、プライマリ バッファの DirectSoundBuffer.Play メソッドを呼び出し、短時間のサウンド中断の頻発を防止することが挙げられる。詳細については、「プライマリ バッファの連続再生」を参照すること。

DirectX for Visual Basic アプリケーションでは、プライマリ バッファへの書き込みアクセスの取得を試みないこと。

[C++]

セカンダリ バッファがサポートしていない特別なミキシングや他のエフェクトを必要とするアプリケーションに対して、DirectSound はプライマリ バッファへの直接アクセスを許可する。

プライマリ サウンド バッファへの書き込みアクセスを取得すると、DirectSound の他の機能は利用できなくなる。セカンダリ バッファのミキシングも行われないので、ハードウェア アクセラレーション ミキシングも利用できなくなる。

ほとんどのアプリケーションは、プライマリ バッファへ直接アクセスせずにセカンダリ バッファを使う。セカンダリ バッファへの書き込みは簡単に行える。より大きなバッファにより、次のデータ ブロックの書き込みまでの時間が長くなり、オーディオの音が途切れる危険が最小限に抑えられる。アプリケーションが必要とするオーディオが、ミキシングを必要としない 1 つのオーディオ ストリームのような単純なものであっても、セカンダリ バッファを使ってオーディオ データを再生することにより、より高い性能が実現できる。

プライマリ バッファのサイズは指定できず、バッファを作成した後に返されるサイズを受け入れなければならない。通常、プライマリ バッファは極めて小さく、もしアプリケーションがこのようなバッファに直接書き込む場合は短い間隔でデータ ブロックを書き込み、以前のデータがもう一度再生されることを防がなければならない。

DSBUFFERDESC 構造体に DSBCAPS_PRIMARYBUFFER フラグを指定し、この構造体を IDirectSound::CreateSoundBuffer メソッドに渡して、アクセス可能なプライマリ バッファを作成する。バッファに書き込みをしたい場合は、協調レベルは DSSCL_WRITEPRIMARY でなければならない。

プライマリ バッファがハードウェア上に存在していない限り、そのバッファの書き込みアクセスは取得できない。これに該当するかどうかを確認するには、IDirectSoundBuffer::GetCaps メソッドを呼び出して DSBCAPS 構造体の dwFlags メンバ内の SBCAPS_LOCHARDWARE フラグの有無をチェックする。ソフトウェアでエミュレートしたプライマリ バッファをロックしようとすると、呼び出しは失敗する。

プライマリ サウンド バッファは、ループして再生しなければならない。その目的で、DSBPLAY_LOOPING フラグが設定されていることを確認する。

次の例は、プライマリ バッファへの書き込みアクセスを取得する方法を示す。

BOOL AppCreateWritePrimaryBuffer(
    LPDIRECTSOUND lpDirectSound,
    LPDIRECTSOUNDBUFFER *lplpDsb,
    LPDWORD lpdwBufferSize,
    HWND hwnd)
{
    DSBUFFERDESC dsbdesc;
    DSBCAPS dsbcaps;
    HRESULT hr;
    WAVEFORMATEX wf;

    // ウェーブ フォーマット構造体を設定する。
    memset(&wf, 0, sizeof(WAVEFORMATEX));
    wf.wFormatTag = WAVE_FORMAT_PCM;
    wf.nChannels = 2;
    wf.nSamplesPerSec = 22050;
    wf.nBlockAlign = 4;
    wf.nAvgBytesPerSec =
        wf.nSamplesPerSec * wf.nBlockAlign;
    wf.wBitsPerSample = 16;

    // DSBUFFERDESC 構造体を設定する。
    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags = DSBCAPS_PRIMARYBUFFER;
    // バッファサイズは、サウンド ハードウェアによって決まる。
    dsbdesc.dwBufferBytes = 0;
    dsbdesc.lpwfxFormat = NULL; // プライマリ バッファでは NULL でなければならない。

    // 書き込み優先協調レベルを取得する。
    hr = lpDirectSound->lpVtbl->SetCooperativeLevel(lpDirectSound,
        hwnd, DSSCL_WRITEPRIMARY);
    if SUCCEEDED(hr)
    {
        // バッファの作成を試みる。
        hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound,
            &dsbdesc, lplpDsb, NULL);
        if SUCCEEDED(hr)
        {
            // プライマリ バッファを希望のフォーマットに設定する。
            hr = (*lplpDsb)->lpVtbl->SetFormat(*lplpDsb, &wf);
            if SUCCEEDED(hr)
            {
                // バッファのサイズを知りたい場合は GetCaps を呼び出す。
                    dsbcaps.dwSize = sizeof(DSBCAPS);
                (*lplpDsb)->lpVtbl->GetCaps(*lplpDsb, &dsbcaps);
                *lpdwBufferSize = dsbcaps.dwBufferBytes;
                return TRUE;
            }
        }
    }
    // 失敗。
    *lplpDsb = NULL;
    *lpdwBufferSize = 0;
    return FALSE;
}

DSSCL_WRITEPRIMARY 以外の協調レベルを指定すると、書き込みアクセスがなくてもプライマリ バッファ オブジェクトを作成できる。このような処理を行う状況の 1 つとして、プライマリ バッファに対して IDirectSoundBuffer::Play メソッドを呼び出し、短時間のサウンド中断の頻発を防止することが挙げられる。詳細については、「プライマリ バッファの連続再生」および「カスタム ミキサー」を参照すること。


スタティック バッファの書き込みと再生

独立したサウンド全体を保持するセカンダリ バッファを、スタティック バッファという。同じバッファを異なるサウンドで再利用することもできるが、通常はデータを一度だけスタティック バッファに記述する。

注 : スタティック バッファは必ずしも、DSBCAPS_STATIC フラグをバッファ記述に設定することで作成されるわけではない。このフラグはサウンド カードのメモリの割り当てを要求するが、このメモリは利用不可能になっていることが多い。スタティック バッファはシステム メモリ内に置かれ、DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE のどちらかのフラグで作成される。

[C++]

スタティック バッファへのデータのロードは、3 つのステップで行われる。

  1. IDirectSoundBuffer::Lock を使ってバッファ全体をロックする。記述を始めるバッファ内のオフセットを指定し (通常は 0)、その位置のメモリ アドレスを返す。
  2. 標準のメモリコピー ルーチンを使って、返されたアドレスにオーディオ データを書き込む。
  3. IDirectSoundBuffer::Unlock を使って、バッファをアンロックする。

これらのステップを次の例で示す。lpdsbStatic は IDirectSoundBuffer インターフェイス ポインタであり、pbData はデータ ソースのアドレスである。

LPVOID lpvWrite;
DWORD  dwLength;

if (DS_OK == lpdsbStatic->Lock(
        0,              // ロックを開始する場所のオフセット。
        0,              // ロックのサイズ。フラグにより無視される。
        &lpvWrite,      // ロックの最初の部分のアドレスを取得する。
        &dwLength,      // ロックの最初の部分のサイズを取得する。
        NULL,           // ラップ アラウンドのアドレスは不要。
        NULL,           // ラップ アラウンドのサイズは不要。
        DSBLOCK_ENTIREBUFFER))  // フラグ。
    {
    memcpy(lpvWrite, pbData, dwLength);
    lpdsbStatic->Unlock(
        lpvWrite,       // ロック開始のアドレス。
        dwLength,       // ロックのサイズ。
        NULL,           // ラップ アラウンド部分はなし。
        0);             // ラップ アラウンド サイズはなし。
    }

次の例は、IDirectSoundBuffer::Play を呼び出してバッファを再生する。

lpdsbStatic->SetCurrentPosition(0);
HRESULT hr = lpdsbStatic->Play(
        0,    // 未使用。
        0,    // ボイス管理用に優先。
        0);   // フラグ。

この例では DSBPLAY_LOOPING フラグを設定していないので、バッファは最後に到達すると自動的に停止する。また、IDirectSoundBuffer::Stop を使うとバッファを早めに停止できる。バッファを早めに停止する場合は、現在の読み込み位置がその場所にとどまる。したがって、例の IDirectSoundBuffer::SetCurrentPosition に対する呼び出しは、バッファが始めから開始することを保証するものである。

[Visual Basic]

スタティック バッファは、DirectSound.CreateSoundBufferFromFile または DirectSound.CreateSoundBufferFromResource のどちらかのメソッドの呼び出しを使って作成され、データが書き込まれる。

次のサンプル コードは、リソース ファイルで "bounce" として識別されるウェーブからスタティック バッファを作成する。m_ds は DirectSound オブジェクトと仮定する。

Dim dsbd As DSBUFFERDESC
Dim dsbResource As DirectSoundBuffer
Dim waveFormat As WAVEFORMATEX

dsbd.lFlags = DSBCAPS_CTRLVOLUME
Set dsbResource = m_ds.CreateSoundBufferFromResource( _
        "", "bounce", dsbd, waveFormat)

リソース ファイルは実行可能ファイルにコンパイルされているので、モジュール名を与える必要はない。同様に、メソッドがデータのサイズからバッファのサイズを決定するので、DSBUFFERDESC 型の lBufferBytes メンバの値も設定する必要はない。WAVEFORMATEX 型は、ファイルやリソースに格納されたヘッダーからウェーブ フォーマットについての情報を受け取る。

バッファを再生するには、次のように DirectSoundBuffer.Play を呼び出す。

dsbResource.SetCurrentPosition 0
dsbResource.Play 0

この例では DSBPLAY_LOOPING フラグを設定していないので、バッファは最後に到達すると自動的に停止する。また、DirectSoundBuffer.Stop を使うとバッファを早めに停止できる。バッファを早めに停止する場合は、現在の読み込み位置がその場所にとどまる。したがって、例の DirectSoundBuffer.SetCurrentPosition に対する呼び出しは、バッファが始めから開始することを保証するものである。

また、DirectSound.CreateSoundBuffer を使ってスタティック バッファを作成した後、DirectSoundBuffer.WriteBuffer メソッドを使ってメモリの他の位置からデータを書き込むこともできる。

セカンダリ バッファへの書き込みについての詳細は、「ストリーム バッファの使い方」を参照すること。


ストリーム バッファの使い方

ストリーム バッファは、一度にバッファに収まらない長いサウンドを再生する。バッファが再生されるにつれ、古いデータは定期的に新しいデータに置き換わる。

[C++]

ストリーム バッファを再生するには、dwFlags パラメータに DSBPLAY_LOOPING を指定して IDirectSoundBuffer::Play メソッドを呼び出す。

再生を停止するには、IDirectSoundBuffer::Stop メソッドを呼び出す。このメソッドはバッファを即時に停止するので、すべてのデータが再生されたことを確認する必要がある。これを行うには、再生位置をポーリングするか、通知位置を設定する。

バッファにストリーミングするには、次のステップが必要である。

  1. IDirectSoundBuffer::Lock を使って、バッファの一部をロックする。このメソッドは、データが記述される 1 つ、もしくは 2 つのアドレスを返す。
  2. この 1 つまたは 2 つのアドレスに対して、標準のメモリコピー ルーチンを使ってオーディオ データを書き込む。
  3. IDirectSoundBuffer::Unlock を使って、バッファをアンロックする。

IDirectSoundBuffer::Lock が 2 つのアドレスを返すことがあるのは、開始位置にかかわらず、バッファのサイズまでのバイト数をロックできるからである。必要に応じて、ロックされる部分はバッファの先頭にラップされる。ラップされる場合は、2 つの個別のメモリ コピーを実行しなければならない。

たとえば 40,000 バイトのバッファで、オフセット 20,000 で始まる 30,000 バイトをロックする場合、Lock を呼び出すと 4 つの値が返される。

  • オフセット 20,000 のアドレス。
  • バッファのその位置から最後までのロックされたバイト数 (20,000)。最初のアドレスにこのバイト数だけ記述する。
  • オフセット 0 のアドレス。
  • その位置からロックされたバイト数 (10,000)。2 番目のアドレスにこのバイト数だけ記述する。

ラップ アラウンドが必要ない場合は、最後の 2 つの値がそれぞれ NULL と 0 になる。

バッファ全体をロックすることもできるが、再生中に行うべきではない。毎回バッファの一部だけをリフレッシュすること。たとえば、再生位置が 2/4 に達したらすぐに、バッファの最初の 1/4 をロックして書き込むようにする。オーディオ出力が途切れる可能性を最小限に抑えるために、カレント プレイ ポジションの少なくとも 1 秒前方に書き込みを行うべきである。

次の C 関数は、dwOffset に渡されたバッファのオフセットから、データをサウンド バッファに書き込む。

BOOL AppWriteDataToBuffer(
    LPDIRECTSOUNDBUFFER lpDsb,  // DirectSound バッファ。
    DWORD dwOffset,             // このサンプル固有の書き込みカーソル。
    LPBYTE lpbSoundData,        // このサンプル固有のデータ開始点。
    DWORD dwSoundBytes)         // コピーされるブロックのサイズ。
{
    LPVOID  lpvPtr1;
    DWORD   dwBytes1;
    LPVOID  lpvPtr2;
    DWORD   dwBytes2;
    HRESULT hr;

    // 書き込みブロックのメモリ アドレスを取得する。ブロックがラップ アラウンドする
    // (先頭に戻る) 場合、書き込みブロックは 2 つの部分に分かれている。
    hr = lpDsb->lpVtbl->Lock(lpDsb, dwOffset, dwSoundBytes, &lpvPtr1,
        &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    // DSERR_BUFFERLOST が返された場合、復元とロックの再試行を行う。
    if (DSERR_BUFFERLOST == hr)
    {
        lpDsb->lpVtbl->Restore(lpDsb);
        hr = lpDsb->lpVtbl->Lock(lpDsb, dwOffset, dwSoundBytes,
            &lpvPtr1, &dwAudio1, &lpvPtr2, &dwAudio2, 0);
    }
    if SUCCEEDED(hr)
    {
        // ポインタに書き込む。
        CopyMemory(lpvPtr1, lpbSoundData, dwBytes1);
        if (NULL != lpvPtr2)
        {
            CopyMemory(lpvPtr2, lpbSoundData+dwBytes1, dwBytes2);
        }
        // データを解放して DirectSound へ返す。
        hr = lpDsb->lpVtbl->Unlock(lpDsb, lpvPtr1, dwBytes1, lpvPtr2,
            dwBytes2);
        if SUCCEEDED(hr)
        {
            // 成功。
            return TRUE;
        }
    }
    // ロック、アンロック、復元のいずれかが失敗。
    return FALSE;
}
[Visual Basic]

ストリーム バッファを再生するには、flags パラメータに DSBPLAY_LOOPING を指定して DirectSoundBuffer.Play メソッドを呼び出す。

再生を停止するには、DirectSoundBuffer.Stop メソッドを呼び出す。このメソッドはバッファを即時に停止するので、すべてのデータが再生されたことを確認する必要がある。これを行うには、再生位置をポーリングするか、通知位置を設定する。

DirectSoundBuffer.WriteBuffer メソッドを使ってバッファにデータをストリーミングする。このメソッドにより、バッファの任意の部分にデータを書き込める。バッファ全体に書き込むこともできるが、再生中に行うべきではない。毎回バッファの一部だけをリフレッシュすること。たとえば、カレント プレイ ポジションが 2/4 に達したらすぐに、バッファの最初の 1/4 に書き込むようにする。オーディオ出力が途切れる可能性を最小限に抑えるために、カレント プレイ ポジションの少なくとも 1 秒前方に書き込みを行うべきである。

次のサンプル コードは、バイト配列 myBuffer から、dsb で表された DirectSoundBuffer の先頭にデータ 1,000 バイトを書き込む。

dsb.WriteBuffer 0, 1000, myBuffer(0), DSBLOCK_DEFAULT

WriteBuffer は、ラップ アラウンドを透過的に処理する。たとえば、セカンダリ バッファが 10,000 バイトで作成されており、アプリケーションがバッファの中間を過ぎたオフセットに 5,000 バイト書き込む場合は、次のようになる。

dsb.WriteBuffer 8000, 5000, myBuffer(0), DSBLOCK_DEFAULT

この呼び出しは、バッファの最後に最初の 2,000 バイトを書き込み、バッファの先頭に次の 3,000 バイトを書き込む。

続くデータ記述に対するオフセットを追跡するのは、アプリケーションの責任である。この処理の最も簡単な方法は、通知位置を設定し、イベントがトリガされるたびに固定したバイト数を書き込むことである。

詳細情報については、次のトピックを参照すること。

  • カレント プレイ ポジションとカレント ライト ポジション
  • 再生バッファの通知


再生のコントロール

[C++]

IDirectSoundBuffer::GetVolume と IDirectSoundBuffer::SetVolume の各メソッドを使うと、再生中のバッファのボリュームの取得と設定が行える。プライマリ サウンド バッファのボリュームを設定すると、サウンド カードのウェーブフォーム オーディオのボリュームが変更される。

同様に、IDirectSoundBuffer::GetFrequency と IDirectSoundBuffer::SetFrequency の各メソッドを使うと、サンプリング オーディオの再生周波数の取得と設定が行える。プライマリ バッファの周波数は変更できない。

パンの取得と設定を行うには、IDirectSoundBuffer::GetPan と IDirectSoundBuffer::SetPan の各メソッドを呼び出す。プライマリ バッファのパンは変更できない。

[Visual Basic]

DirectSoundBuffer.GetVolume と DirectSoundBuffer.SetVolume の各メソッドを使うと、再生中のバッファのボリュームの取得と設定が行える。プライマリ サウンド バッファのボリュームを設定すると、サウンド カードのウェーブフォーム オーディオのボリュームが変更される。

同様に、DirectSoundBuffer.GetFrequency と DirectSoundBuffer.SetFrequency の各メソッドを使うと、サンプリング オーディオの再生周波数の取得と設定が行える。プライマリ バッファの周波数は変更できない。

パンの取得と設定を行うには、DirectSoundBuffer.GetPan と DirectSoundBuffer.SetPan の各メソッドを呼び出す。プライマリ バッファのパンは変更できない。

これらのコントロールのいずれかを使うには、バッファを作成する際に適切なフラグを設定しなければならない。「バッファ コントロール オプション」を参照すること。


カレント プレイ ポジションとカレント ライト ポジション

DirectSound はバッファに対し、カレント プレイ ポジション (再生カーソルとも呼ばれる) とカレント ライト ポジション (書き込みカーソルとも呼ばれる) という 2 つのポインタを維持している。これらの位置はバッファのバイト オフセットであり、メモリの絶対アドレスではない。

[C++]

IDirectSoundBuffer::Play メソッドは、常にカレント プレイ ポジションからバッファの再生を開始する。バッファを作成した時点で、再生位置は 0 に設定される。サウンドが再生されるにつれ、再生位置は移動し、次に出力されるデータ バイトを示す。バッファが停止したときは、再生位置は次のデータ バイトにとどまる。

[Visual Basic]

DirectSoundBuffer.Play メソッドは、常にカレント プレイ ポジションからバッファの再生を開始する。バッファを作成した時点で、再生位置は 0 に設定される。サウンドが再生されるにつれ、再生位置は移動し、次に出力されるデータ バイトを示す。バッファが停止したときは、再生位置は次のデータ バイトにとどまる。

バッファでカレント ライト ポジションより後の場所には、データを安全に書き込める。カレント プレイ ポジションとカレント ライト ポジションの間にあるブロックは、既に再生が確定していて、安全に変更することはできない。

バッファを時計の文字盤で表し、時計回りの方向にデータを書き込むと考える。再生位置と書き込み位置は、この文字盤上で同じ速度で回転する 2 本の針にたとえられ、書き込み位置は、常に再生位置の少し前方にある。再生位置が 1 を示し、書き込み位置が 2 を示している場合は、データを書き込んでも安全なのは 2 の後だけである。1 と 2 の間のデータは DirectSound が既に再生キューに入れている可能性もあるので、変更すべきではない。

書き込み位置は、バッファに書き込まれたデータではなく再生位置に合わせて移動する。データをストリーミングする場合、次に書き込みを行うデータ ブロックの位置を示すために、開発者は独自のポインタを維持する責任を負う。

[C++]

IDirectSoundBuffer::Lock メソッドの dwWriteCursor パラメータが、カレント ライト ポジションではない点に注意すること。これはバッファ内で実際にデータを書き込むオフセットである。カレント ライト ポジションで書き込みを始めたい場合は、dwFlags パラメータに DSBLOCK_FROMWRITECURSOR を指定する。この場合、dwWriteCursor パラメータは無視される。

アプリケーションは、IDirectSoundBuffer::GetCurrentPosition メソッドを呼び出すことにより、カレント プレイ ポジションとカレント ライト ポジションを取得できる。IDirectSoundBuffer::SetCurrentPosition メソッドを使うと、カレント プレイ ポジションを設定できるが、カレント ライト ポジションは変更できない。

カレント プレイ ポジションをできるだけ正確に報告するには、セカンダリ バッファを作成する際に DSBCAPS_GETCURRENTPOSITION2 フラグを指定しなければならない。詳細については、DSBUFFERDESC を参照すること。

[Visual Basic]

DirectSoundBuffer.WriteBuffer メソッドの start パラメータが、カレント ライト ポジションではない点に注意すること。これはバッファ内で実際にデータを書き込むオフセットである。カレント ライト ポジションで書き込みを始めたい場合は、flags パラメータに DSBLOCK_FROMWRITECURSOR を指定する。この場合、start パラメータは無視される。

アプリケーションは、DirectSoundBuffer.GetCurrentPosition メソッドを呼び出すことにより、カレント プレイ ポジションとカレント ライト ポジションを取得できる。DirectSoundBuffer.SetCurrentPosition メソッドを使うと、カレント プレイ ポジションを設定できるが、カレント ライト ポジションは変更できない。

カレント プレイ ポジションをできるだけ正確に報告するには、セカンダリ バッファを作成する際に DSBCAPS_GETCURRENTPOSITION2 フラグを指定しなければならない。詳細については、DSBUFFERDESC を参照すること。


再生バッファの通知

[C++]

データがセカンダリ バッファにストリーミングされる場合、カレント プレイ ポジションがバッファ内のある点に到達したときや、再生が停止したときに、アプリケーションへの通知を発生させたいことがある。IDirectSoundNotify::SetNotificationPositions メソッドを使うと、イベントのシグナルを送信するポイントをバッファ内にいくつでも設定できる。ただし、バッファの再生中はイベント ポイントの設定を行えない。

最初に IDirectSoundNotify インターフェイスへのポインタを取得しなければならない。この取得は、バッファ オブジェクトの QueryInterface メソッドを使って行う。次に C++ による例を示す。lpDsbSecondary は IDirectSoundBuffer インターフェイス ポインタである。

LPDIRECTSOUNDNOTIFY lpDsNotify;

HRESULT hr = lpDsbSecondary->QueryInterface(IID_IDirectSoundNotify,
                                            (LPVOID *)&lpDsNotify);
if SUCCEEDED(hr)
{
    // 先に進んで、lpDsNotify->SetNotificationPositions を使う。
}

IDirectSoundNotify インターフェイスは、ポインタを取得したバッファに関連付けられている。新しいインターフェイスのメソッドは自動的にこのバッファに適用される。

ここで Win32 の CreateEvent 関数を使ってイベント オブジェクトを作成する。このイベントのハンドルを DSBPOSITIONNOTIFY 構造体の hEventNotify メンバに書き込む。この構造体の dwOffset メンバで、バッファ内でイベントのシグナルを送信したい位置のオフセットを指定する。次にこの構造体のアドレスを、または複数の通知位置を設定したい場合は構造体の配列を、IDirectSoundNotify::SetNotificationPositions メソッドに渡す。

次の例は、1 つの通知位置を設定する。ループしない条件でバッファの終了位置に到達したか、アプリケーションが IDirectSoundBuffer::Stop メソッドを呼び出したか、どちらかの理由で再生が停止したときに、イベントのシグナルが送信される。

DSBPOSITIONNOTIFY PositionNotify;

PositionNotify.Offset = DSBPN_OFFSETSTOP;
PositionNotify.hEventNotify = hMyEvent;
// hMyEvent は、CreateEvent() が返したハンドルである。

lpDsNotify->SetNotificationPositions(1, &PositionNotify);

ボイス管理を使っている場合は、通知位置に到達する前にバッファを終了できる。DSBPOSITIONNOTIFY の注意を参照すること。

[Visual Basic]

データがセカンダリ バッファにストリーミングされる場合、カレント プレイ ポジションがバッファ内のある点に到達したときや、再生が停止したときに、アプリケーションへの通知を発生させたいことがある。DirectSoundBuffer.SetNotificationPositions メソッドを使うと、イベントのシグナルを送信するポイントをバッファ内にいくつでも設定できる。ただし、バッファの再生中はイベント ポイントの設定を行えない。

バッファに通知イベントを設定するには、バッファのコードを保持するフォームに DirectXEvent オブジェクトを実装しなくてはならない。そして DirectX7.CreateEvent メソッドを呼び出して、イベント ハンドルを作成する。このイベント ハンドルを DSBPOSITIONNOTIFY 型の hEventNotify メンバに配置する。この型を DirectSoundBuffer.SetNotificationPositions メソッドに渡す。

再生位置がバッファの通知位置に到達すると、DirectXEvent.DXCallback が呼び出される。

ボイス管理を使っている場合は、通知位置に到達する前にバッファを終了できる。DSBPOSITIONNOTIFY の注意を参照すること。

次のコードの例で、単一の通知位置の設定方法を示す。以下は、モジュールの宣言セクションの行である。

Dim gDX As New DirectX7
Dim gDSB As DirectSoundBuffer
Dim dsbpn(0) As DSBPOSITIONNOTIFY
Dim endEvent As Long
Implements DirectXEvent

dsbpn は単一の通知位置だけを保持するが、配列でなくてはならないことに注意すること。

フォームがロードされると、イベントが作成される。

endEvent = gDX.CreateEvent(Me)

DirectSoundBuffer オブジェクトの作成後、通知位置が設定され、次のようにイベントに関連付けられる。

With dsbpbn(0)
  .hEventNotify = endEvent
  .lOffset = DSBPN_OFFSETSTOP
End With
gDX.SetEvent endEvent
gDSB.SetNotificationPositions 1, dsbpn()

ループしない条件でバッファの終了位置に到達したか、アプリケーションが DirectSoundBuffer.Stop メソッドを呼び出したか、どちらかの理由でバッファが再生を停止したとき、通知のオフセットは DSBPN_OFFSETSTOP または –1 という、イベントが設定されることを示す特別な値を取る。これが発生すると、アプリケーション定義のコールバック関数が自動的に呼び出され、パラメータとして endEvent イベント識別子が渡される。

Private Sub DirectXEvent_DXCallback(ByVal eventid As Long)
  If eventid = endEvent Then
    lblStatusDesc.Caption = "Buffer stopped."
  End If
End Sub


サウンドのミキシング

[C++]

DirectSound で複数のストリームをミキシングするのは簡単である。単純にセカンダリ サウンド バッファを作成し、各サウンドに対する IDirectSoundBuffer インターフェイスを取得するだけである。次にそれらのバッファを同時に再生する。DirectSound は、プライマリ サウンド バッファでミキシングを行い、その結果を再生する。

[Visual Basic]

DirectSound で複数のストリームをミキシングするのは簡単である。単純にセカンダリ サウンド バッファを作成し、各サウンドに対する DirectSoundBuffer オブジェクトを取得するだけである。次にそれらのバッファを同時に再生する。DirectSound は、プライマリ サウンド バッファでミキシングを行い、その結果を再生する。

アプリケーション内のすべてのサウンドが同じウェーブ フォーマットを使用し、ハードウェア出力フォーマットがそれらのサウンドのフォーマットと一致している場合、DirectSound ミキサーは最高の品質のサウンドをもたらす。この場合、ミキサーはフォーマット変換をする必要がない。

[C++]

ハードウェア出力フォーマットを変更するには、プライマリ サウンド バッファを作成し、IDirectSoundBuffer::SetFormat メソッドを呼び出す。このプライマリ バッファはコントロールの目的でだけ使える点に注意すること。このバッファの作成は、「プライマリ バッファへのアクセス」で説明したプライマリ バッファへの書き込みアクセスの取得と同じことを意味せず、協調レベルを DSSCL_WRITEPRIMARY に設定する必要もない。しかし、SetFormat メソッドを呼び出すために、DSSCL_PRIORITY またはそれ以上の協調レベルを設定する必要がある。アプリケーションが入力フォーカスを取得するたびに、DirectSound はハードウェア フォーマットを、前回の呼び出しで指定されたフォーマットに復元する。

[Visual Basic]

アプリケーションでハードウェア出力フォーマットを変更するには、プライマリ サウンド バッファを作成し、DirectSoundBuffer.SetFormat メソッドを呼び出す。SetFormat メソッドを呼び出すには、DSSCL_PRIORITY の協調レベルまたはそれ以上のレベルが必要である。アプリケーションが入力フォーカスを取得するたびに、DirectSound はハードウェア フォーマットを、前回の呼び出しで指定されたフォーマットに復元する。


カスタム ミキサー

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

ほとんどのアプリケーションは DirectSound ミキサーを使用する。このミキサーはほぼすべてのミキシングの要求を満たし、利用可能なすべてのハードウェア アクセラレーションを自動的に活用する。しかし、DirectSound が提供しない機能をアプリケーションが必要とする場合は、プライマリ サウンド バッファへの書き込みアクセスを取得し、そこでストリームを直接ミキシングできる。

カスタム ミキサーを実装するには、アプリケーションは最初に DSSCL_WRITEPRIMARY 協調レベルを設定し、プライマリ サウンド バッファを作成しなければならない。(「プライマリ バッファへのアクセス」を参照。)次にバッファをロックし、データを書き込み、バッファをアンロックし、他のバッファと同じように再生する。ただし、DSBPLAY_LOOPING フラグを指定しなければならない。さもないと IDirectSoundBuffer::Play の呼び出しが失敗する点に注意すること。

次の例は、アプリケーションがカスタム ミキサーを実装する方法を示す。サウンド デバイスがデータ ブロックの再生を繰り返さないよう、AppMixIntoPrimaryBuffer 関数を一定の間隔で呼び出さなければならない。CustomMixer 関数はアプリケーションが定義した関数であり、アプリケーションが定義した AppStreamInfo 構造体の指定に従って複数のストリームをミキシングし、結果を指定のポインタに書き込む。

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 SUCCEEDED(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 SUCCEEDED(hr)
        {
            return TRUE;
        }
    }
    // ロックまたはアンロックが失敗した。
    return FALSE;
}


バッファ管理

[C++]

IDirectSoundBuffer::GetCaps は、DirectSoundBuffer オブジェクトの能力を取得する。

アプリケーションは IDirectSoundBuffer::GetStatus メソッドを使って、現在のサウンド バッファが再生中か停止しているかを確認できる。

IDirectSoundBuffer::GetFormat メソッドを使うと、バッファ内のサウンド データのフォーマット情報を取得できる。IDirectSoundBuffer::GetFormat と IDirectSoundBuffer::SetFormat の各メソッドを使って、プライマリ サウンド バッファ内のサウンド データのフォーマットの取得と設定も行える。

注 : セカンダリ サウンド バッファを作成した後、そのフォーマットが固定される。他のフォーマットを使うセカンダリ バッファが必要な場合は、そのフォーマットを指定して新しいサウンド バッファを作成しなければならない。

サウンド バッファ用のメモリは特定の状況で失われることがある。たとえば、バッファがサウンド カードのメモリに置かれていて、他のアプリケーションがハードウェア リソースの制御を取得した場合である。書き込み優先の協調レベルで動作するアプリケーションがフォアグラウンドに移動した場合も、メモリが失われることがある。この場合、他のすべてのサウンド バッファは失われるので、フォアグラウンドに移動したアプリケーションはプライマリ バッファに直接書き込める。

失われたバッファに対して IDirectSoundBuffer::Lock、IDirectSoundBuffer::Play メソッドのいずれかを呼び出すと、DSERR_BUFFERLOST エラーコードが返される。バッファを失わせたアプリケーションの協調レベルが書き込み優先から下がったり、そのアプリケーションがバックグラウンドに移動した場合は、他のアプリケーションは IDirectSoundBuffer::Restore メソッドを呼び出してバッファ メモリの再配置を試みることができる。成功した場合、このメソッドはバッファ メモリと、ボリュームやパンの設定など他のすべての設定を復元する。しかし、復元されたバッファは有効なサウンド データを保持していない。したがって、アプリケーションは復元されたバッファにデータをもう一度書き込むべきである。

[Visual Basic]

DirectSoundBuffer.GetCaps メソッドは、DirectSoundBuffer オブジェクトの能力を取得する。

アプリケーションは DirectSoundBuffer.GetStatus メソッドを使って、現在のサウンド バッファが再生中か停止しているかを確認できる。

DirectSoundBuffer.GetFormat メソッドを使うと、バッファ内のサウンド データのフォーマット情報を取得できる。DirectSoundBuffer.GetFormat と DirectSoundBuffer.SetFormat の各メソッドを使って、プライマリ サウンド バッファ内のサウンド データのフォーマットの取得と設定も行える。

注 : セカンダリ サウンド バッファを作成した後、そのフォーマットが固定される。他のフォーマットを使うセカンダリ バッファが必要な場合は、そのフォーマットを指定して新しいサウンド バッファを作成しなければならない。

サウンド バッファ用のメモリは特定の状況で失われることがある。たとえば、バッファがサウンド カードのメモリに置かれていて、他のアプリケーションがハードウェア リソースの制御を取得した場合である。書き込み優先の協調レベルで動作するアプリケーションがフォアグラウンドに移動した場合も、メモリが失われることがある。この場合、他のすべてのサウンド バッファは失われるので、フォアグラウンドに移動したアプリケーションはプライマリ バッファに直接書き込める。

失われたバッファに対して DirectSoundBuffer.WriteBuffer、DirectSoundBuffer.Play メソッドのいずれかを呼び出すと、DSERR_BUFFERLOST エラー コードが返される。バッファを失わせたアプリケーションの協調レベルが書き込み優先から下がったり、そのアプリケーションがバックグラウンドに移動した場合は、他のアプリケーションは DirectSoundBuffer.Restore メソッドを呼び出してバッファ メモリの再配置を試みることができる。成功した場合、このメソッドはバッファ メモリと、ボリュームやパンの設定など他のすべての設定を復元する。しかし、復元されたバッファは有効なサウンド データを保持していない。したがって、アプリケーションは復元されたバッファにデータをもう一度書き込むべきである。


圧縮ウェーブ フォーマット

DirectSound は現在、圧縮ウェーブ フォーマットをサポートしていない。アプリケーションはサウンド バッファにデータを書き込む前に、Platform SDK 内の Win32 API で提供されているオーディオ圧縮マネージャ (ACM) 関数を使って、圧縮されたオーディオ データを PCM (pulse-code modulation) データに変換すべきである。実際、サウンドバッファ メモリへのポインタをロックし、ACM にこのポインタを渡すと、データは最大の効率でサウンド バッファに直接デコードできる。


DirectSound の 3D への応用

DirectSound により、アプリケーションは音源やリスナーの見かけの位置 (定位) や方向を変更できる。さらに、ドップラー シフトを使って音源とリスナーの相対速度も示唆できる。

次のトピックでは、3D サウンドの基本的概念をいくつか紹介する。

  • Direct3D への統合
  • モノラル音源とステレオ音源
  • 音源位置の認識

次のトピックでは、アプリケーション内での 3D サウンドの使い方についての情報を示す。

  • DirectSound 3D バッファ
  • DirectSound 3D リスナー


Direct3D への統合

[C++]

IDirectSound3DBuffer と IDirectSound3DListener の各インターフェイスは、Direct3D® と組み合わせて動作するよう設計されている。Direct3D が仮想環境内のオブジェクトを配列する際に使う位置決め情報は、音源を配列する目的でも使える。Direct3D プログラマにとって既知の D3DVECTOR と D3DVALUE の各構造体は、IDirectSound3DBuffer と IDirectSound3DListeners の各インターフェイスでも使われる。また、Direct3D で使われている左手座標系と同じものが DirectSound でも採用されている。(座標系については、Direct3D の「3D 座標系」を参照すること。)

Direct3D のシステム コールバック メカニズムを使って、アプリケーションへの 3D サウンドの実装を簡素化できる。たとえば、アプリケーション定義関数 D3DRMFRAMEMOVECALLBACK を使って、アプリケーション内のフレームの動きを監視し、ある条件が成立したときだけサウンド環境を変更できる。

[Visual Basic]

DirectSound3DBuffer と DirectSound3DListener の各クラスは、Direct3D® と組み合わせて動作するよう設計されている。Direct3D が仮想環境内のオブジェクトを配列する際に使う位置決め情報は、音源を配列する目的でも使える。Direct3D プログラマにとって既知の D3DVECTOR 型は、DirectSound3DBuffer と DirectSound3DListener の各クラスでも使われる。また、Direct3D で使われている左手座標系と同じものが DirectSound でも採用されている。(座標系については、Direct3D の「3D 座標系」を参照すること。)

通常、DirectSound では距離はメートル単位で測定される。アプリケーションが 3D グラフィックの測定単位としてメートル以外のものを使っている場合、距離係数を設定し、アプリケーションの使う距離単位が何メートルに相当するかを浮動小数点の値として表現する。たとえば、アプリケーションがフィート単位を使っている場合、DirectSound の距離係数として 0.3048 を指定するが、これは 1 フィートをメートル単位で表現したものである。


モノラル音源とステレオ音源

DirectSound はモノラル入力から固有のステレオ出力を作成するので、DirectSound の 3D サウンド環境ではステレオ音源が特に役立つわけではない。アプリケーションがステレオ サウンド バッファを使う場合、各サンプルの左右それぞれの値を平均化した後で、3D 処理を適用する。

DirectSound の 3D 能力を利用するときは、アプリケーションはモノラル音源を提供すべきである。システムがステレオ音源をモノラルに変換する機能を備えている場合でも、ステレオを供給する理由はなく、変換が時間の無駄となる。


音源位置の認識

現実の世界では、空間内の音源位置の認識は、多数の要素に影響される。次にその一部を示す。

  • ボリューム。音を出す物体がリスナーから離れるほど、その音は小さくなっていく。この現象はロールオフと呼ばれている。
  • 聴感上の強度の違い。リスナーの右方向で発生した音は、左耳より右耳の方で大きく聞こえる。このエフェクトは、ステレオ サウンド システムの音を聞くことに似ている。
  • 到達のずれ。リスナーの右方向で発生した音は、左耳より少しだけ早く右耳に到達する。(このずれの時間は、約 1 ミリ秒である。)
  • 消音。耳は前向きについているので、リスナーの後ろ方向で発生した音は、前で発生した音に比べてかすかに弱くなっている。さらに、右方向で音が発生した場合、左耳に届く音は、頭部に遮られることと左耳の向きによって弱まる。

人間が音の位置を識別するための手がかりはこれだけではないが、ここに挙げたのは主要なものである。そして DirectSound の位置決めシステムはこれらの要素を提供する。3D サウンド用に最適化されたハードウェアは、異なる方向から発せられる音の高さやタイミングに対する耳たぶのエフェクトなど、他の手がかりもサポートできる。このエフェクトの背景にある数学的理論を頭部伝達関数と呼ぶ。

しかし、非常に重要な音の位置識別要素は、音源の視覚的な見かけの位置である。たとえば、遠くにある小さな点として見えていた発射体が、大陸間弾道ミサイルの大きさになり、非常に大きな音を出して観察者の頭上を越えて行けば、リスナーは音源の位置と速度を把握するための音響上のささいな手がかりを必要としない。


DirectSound 3D バッファ

[C++]

3D サウンド バッファは他のサウンド バッファと同じ方法で作成と管理が行われ、IDirectSoundBuffer インターフェイスのすべてのメソッドも利用できる。ただし、3D のパラメータを設定するには、バッファ用の IDirectSound3DBuffer インターフェイスを取得する必要がある。このインターフェイスをサポートするのは、DSBCAPS_CTRL3D フラグを指定して作成されたサウンド バッファだけである。

ここでは、アプリケーションが IDirectSound3DBuffer インターフェイスを使ってバッファを管理する方法と、インターフェイスのメソッドを使用したバッファ パラメータの管理について説明する。次のトピックを取り上げる。

[Visual Basic]

3D 環境における各音源は、その取得元となる DirectSoundBuffer の 3D プロパティを制御する DirectSound3DBuffer オブジェクトで表される。DirectSound3DBuffer オブジェクトは、DSBCAPS_CTRL3D フラグで作成された DirectSoundBuffer からのみ取得できる。

ここでは、アプリケーションが DirectSound3DBuffer クラス メソッド使ってバッファを管理する方法について説明する。次のトピックを取り上げる。

  • DirectSound3DBuffer オブジェクトの取得
  • DirectSound3DBuffer のバッチ パラメータ
  • 最小距離と最大距離
  • 処理モード
  • バッファの位置と速度
  • サウンド コーン


DirectSound3DBuffer オブジェクトの取得

[C++]

IDirectSound3DBuffer インターフェイスへのポインタを取得するには、最初にセカンダリ 3D サウンド バッファを作成しなければならない。これを作成するには、IDirectSound::CreateSoundBuffer メソッドを使い、DSBUFFERDESC 構造体の dwFlags メンバに DSBCAPS_CTRL3D フラグを指定する。そして作成されたバッファに対して IDirectSoundBuffer::QueryInterface メソッドを呼び出し、そのバッファの IDirectSound3Dlistener インターフェイスへのポインタを取得する。

次の例では C++ の構文で QueryInterface メソッドを呼び出す。

// LPDIRECTSOUNDBUFFER lpDsbSecondary;
// DSBCAPS_CTRL3D を指定して作成したバッファ。
LPDIRECTSOUND3DBUFFER lpDs3dBuffer;

HRESULT hr = lpDsbSecondary->QueryInterface(IID_IDirectSound3DBuffer,
                                            (LPVOID *)&lpDs3dBuffer);
if SUCCEEDED(hr)
{
    // このサウンドの 3D パラメータを設定する。
    .
    .
    .
}
[Visual Basic]

DirectSound3DBuffer オブジェクトを取得するには、最初にセカンダリ 3D サウンド バッファを作成しなければならない。これを作成するには、DirectSound.CreateSoundBuffer メソッドを使い、DSBUFFERDESC 型の lFlags メンバに DSBCAPS_CTRL3D フラグを指定する。そして作成されたバッファに対して、DirectSoundBuffer.GetDirectSound3DBuffer メソッドを呼び出す。

次の例は、DirectSound3DBuffer オブジェクトの作成方法を示す。

Dim dsbd As DSBUFFERDESC
Dim dsBuffer As DirectSoundBuffer
Dim waveFormat As WAVEFORMATEX
Dim ds3dBuffer As DirectSound3DBuffer

' ウェーブ フォーマットを設定する。

With waveFormat
    .nSize = LenB(waveFormat)
    .nFormatTag = WAVE_FORMAT_PCM
    .nChannels = 2
    .lSamplesPerSec = 22050
    .nBitsPerSample = 16
    .nBlockAlign = _
            waveFormat.nBitsPerSample / 8 * waveFormat.nChannels
    .lAvgBytesPerSec = _
            waveFormat.lSamplesPerSec * waveFormat.nBlockAlign
End With

' セカンダリ バッファの作成。

dsbd.lFlags = DSBCAPS_CTRL3D
Set dsBuffer = m_ds.CreateSoundBuffer(dsbd, waveFormat)

' 3D バッファ オブジェクトの取得。

Set ds3dBuffer = dsBuffer.GetDirectSound3DBuffer


DirectSound3Dbuffer のバッチ パラメータ

[C++]

アプリケーションは、3D サウンド パラメータの取得や設定を個別またはバッチ単位で実施できる。個別の値を設定するには、アプリケーションで適用可能な IDirectSound3DBuffer インターフェイス メソッドを使用できる。しかし、すべての値を一度に設定または取得する必要が生じることもよくある。その場合は、IDirectSound3DBuffer::GetAllParameters と IDirectSound3DBuffer::SetAllParameters の各メソッドを使う。

[Visual Basic]

アプリケーションは、3D サウンド パラメータの取得や設定を個別またはバッチ単位で実施できる。個別の値を設定するには、アプリケーションで適用可能な DirectSound3DBuffer オブジェクト メソッドを使用できる。しかし、すべての値を一度に設定または取得する必要が生じることもよくある。その場合は、DirectSound3DBuffer.GetAllParameters と DirectSound3DBuffer.SetAllParameters の各メソッドを使う。

また、パラメータの変更は、それらに遅延のフラグを付けておき、その後すべてを一度に実行することでより効率的に行える。詳細については、「遅延設定」を参照すること。


最小距離と最大距離

リスナーが音源に近づくにつれ音は大きくなる。距離が半分になればボリュームは倍になる。しかし、特定の点を過ぎると、ボリュームが増加し続けるのは合理的ではない。これが音源の最小距離である。

アプリケーションが異なる音の絶対ボリューム レベルの差を補正しなければならない場合、最小距離は特に役立つ。たとえば、ジェット エンジンの音は蜂の羽音よりもずっと大きいが、実用上の理由でこれらの音を同程度の絶対ボリュームで録音しなければならない。アプリケーションはジェット エンジンの最小距離を 100 メートル、蜂の最小距離を 2 センチに設定することが考えられる。これらの設定では、リスナーが 200 メートル離れるとジェット エンジンは半分のボリュームになり、リスナーが 4 センチ離れると蜂の羽音は半分のボリュームになる。

サウンド バッファのデフォルトの最小距離は、DS3D_DEFAULTMINDISTANCE であり、現在は 1 単位と定義されている。この値を変更しない限り、ユーザーから 2 メートル離れると音は半分の大きさ、4 メートル離れると 1/4 の大きさになる。ほとんどのサウンドでは、おそらくこれより大きい最大距離を設定するはずである。

音源の最大距離とは、それ以上離れても音がより小さくならない距離を意味する。DirectSound の 3D バッファのデフォルトの最大距離 (DS3D_DEFAULTMAXDISTANCE) は非常に大きな値であり、音が聞こえなくなったとしても引き続き減衰を計算しなければならないことを意味する。不必要な処理を避けるために、アプリケーションは適切な最大距離を設定し、バッファを作成する際に DSBCAPS_MUTE3DATMAXDISTANCE フラグを含めるべきである。

サウンドが聞こえなくなることを防止する目的でも、最大距離を利用できる。たとえば、あるサウンドの最小距離を 100 メートルに設定し、1,000 メートル以上離れるとそのサウンドが事実上聞こえなくなると仮定する。ここで最大距離を 800 メートルに設定すると、距離にかかわりなく、そのサウンドは最大ボリュームの少なくとも 1/8 で聞こえることが保証される。もちろん、この場合は DSBCAPS_MUTE3DATMAXDISTANCE フラグを設定しない。

次の図は、最小距離と最大距離の概念を示す。

[C++]

最小距離値の設定と取得を行うには IDirectSound3DBuffer::SetMinDistance と IDirectSound3DBuffer::GetMinDistance の各メソッドを使う。同様に、最大距離値の設定と取得を行うには IDirectSound3DBuffer::SetMaxDistance と IDirectSound3DBuffer::GetMaxDistance の各メソッドを使う。

[Visual Basic]

最小距離値の設定と取得を行うには DirectSound3DBuffer.SetMinDistance と DirectSound3DBuffer.GetMinDistance の各メソッドを使う。同様に、最大距離値の設定と取得を行うには DirectSound3DBuffer.SetMaxDistance と DirectSound3DBuffer.GetMaxDistance の各メソッドを使う。

デフォルトでは、距離値はメートル単位で表される。「距離係数」を参照すること。

すべてのサウンド バッファで、距離がボリュームに及ぼすエフェクトを調整するには、ロールオフ係数を変更する。


処理モード

サウンド バッファは、標準、頭相対 (リスナー相対)、無効の 3 つの処理モードを持つ。

標準モードでは、音源はワールド スペース内の絶対位置と絶対方向に基づいて処理される。これはデフォルトのモードである。

[C++]

頭相対 (リスナー相対) モードでは、リスナーの移動と回転に応じて、バッファはワールド スペース内で自動的に位置調整される。IDirectSound3DBuffer::SetPosition、IDirectSound3DBuffer::SetVelocity、IDirectSound3DBuffer::GetConeOrientation などのメソッドで値の設定と取得が行えるが、これらはいずれもリスナーの現在の位置、速度、方向に対する相対的なものである。

無効モードでは 3D サウンド処理は無効になり、サウンドはリスナーの頭の中心で発生しているように聞こえる。

アプリケーションは IDirectSound3DBuffer::SetMode メソッドを使って 3D サウンド バッファのモードを設定する。

[Visual Basic]

頭相対 (リスナー相対) モードでは、リスナーの移動と回転に応じて、バッファはワールド スペース内で自動的に位置調整される。DirectSound3DBuffer.SetPosition、DirectSound3DBuffer.SetVelocity、DirectSound3DBuffer.GetConeOrientation などのメソッドで値の設定と取得が行えるが、これらはいずれもリスナーの現在の位置、速度、方向に対する相対的なものである。

無効モードでは 3D サウンド処理は無効になり、サウンドはリスナーの頭の中心で発生しているように聞こえる。

アプリケーションは DirectSound3DBuffer.SetMode メソッドを使って 3D サウンド バッファのモードを設定する。


バッファの位置と速度

[C++]

アプリケーションは、IDirectSound3DBuffer::SetPosition と IDirectSound3DBuffer::GetPosition の各メソッドを使って、3D 空間での音源の位置の設定と取得を行える。ポジションは処理モードに基づき、ワールド スペースかリスナーのどちらかを基準とした相対的なベクトルとして表される。

DirectSound がリスナーに対するドップラー シフト エフェクトを計算する際に使う速度値の設定や取得を行うには、IDirectSound3DBuffer::SetVelocity と IDirectSound3DBuffer::GetVelocity の各メソッドを使う。速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。

[Visual Basic]

アプリケーションは、DirectSound3DBuffer.SetPosition と DirectSound3DBuffer.GetPosition_ の各メソッドを使って、3D 空間での音源の位置の設定と取得を行える。ポジションは処理モードに基づき、ワールド スペースかリスナーのどちらかを基準とした相対的なベクトルとして表される。

DirectSound がリスナーに対するドップラー シフト エフェクトを計算する際に使う速度値の設定や取得を行うには、DirectSound3DBuffer.SetVelocity と DirectSound3DBuffer.GetVelocity の各メソッドを使う。速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。

速度がバッファの実際の位置や移動から完全に独立している点に注意すること。バッファの適切な速度を設定する作業は、完全にアプリケーションに依存している。


サウンド コーン

どの方向でも、距離に応じて音の大きさが決まる。方向のある音はサウンド コーンである。

[C++]

DirectSound のサウンド コーンは、内部コーンと外部コーンで形成される。内部コーンの内側では、ボリュームはコーンが存在しない場合と同じ大きさになる。言い換えると、通常のボリュームからの減衰は発生しない。(もちろん、通常のボリュームは最大ボリュームとは限らない。通常のボリュームは IDirectSoundBuffer::SetVolume メソッドによって設定されるもので、さらにリスナーとの距離、リスナーの方向、ロールオフ係数、バッファの最小距離によって決まる。)。外部コーンの外側では、通常のボリュームはアプリケーションによって設定されたデシベル数だけ減衰する。内部コーンと外部コーンの間の角度は、内部ボリュームから外部ボリュームへの移行地帯である。

[Visual Basic]

DirectSound のサウンド コーンは、内部コーンと外部コーンで形成される。内部コーンの内側では、ボリュームはコーンが存在しない場合と同じ大きさになる。言い換えると、通常のボリュームからの減衰は発生しない。(もちろん、通常のボリュームは最大ボリュームとは限らない。通常のボリュームは DirectSoundBuffer.SetVolume メソッドによって設定されるもので、さらにリスナーとの距離、リスナーの方向、ロールオフ係数、バッファの最小距離によって決まる。)。外部コーンの外側では、通常のボリュームはアプリケーションによって設定されたデシベル数だけ減衰する。内部コーンと外部コーンの間の角度は、内部ボリュームから外部ボリュームへの移行地帯である。

次の図は、サウンド コーンの概念を示す。

技術的には、DirectSound 内のすべての 3D バッファはサウンド コーンである。しかし、外部ボリュームは 0 (つまり減衰が存在しない)、内部コーンと外部コーンの角度はどちらも 360 度なので、デフォルトではバッファは単一方向の音源として動作する。アプリケーションがこれらの値を変更するまでは、サウンドには見かけの方向はない。

サウンド コーンを適切に設計すると、アプリケーションに劇的なエフェクトが追加される。たとえば音源を部屋の中央に置き、音源の方向を、廊下に面して開いたドアの方向に設定する。次にそのドアの幅に合わせて内部コーンの角度を設定する。外部コーンをそれより少しだけ広く設定し、外部コーンのボリュームを聴取不可能に設定する。リスナーが廊下を歩き、ドアの近くまで来るとサウンドが聞こえ始める。そして開いているドアの正面に来るとサウンドは最大になる。

[C++]

アプリケーションは、IDirectSound3DBuffer::SetConeAngles と IDirectSound3DBuffer::GetConeAngles の各メソッドを使って、サウンド コーンを定義する角度の設定と取得を行う。外部コーンの角度は、常に内部コーンの角度以上でなければならない。

アプリケーションは、IDirectSound3DBuffer::SetConeOrientation と IDirectSound3DBuffer::GetConeOrientation の各メソッドを使って、サウンド コーンの方向の設定と取得を行う。

アプリケーションは、IDirectSound3DBuffer::SetConeOutsideVolume と IDirectSound3DBuffer::GetConeOutsideVolume の各メソッドを使って、外部コーンのボリュームの設定と取得を行う。外部コーンのボリュームは、1/100 dB 単位の負の数で表される。デフォルトのボリュームを 0 とし、このボリュームはそこからの減衰を表すからである。

[Visual Basic]

アプリケーションは、DirectSound3DBuffer.SetConeAngles と DirectSound3DBuffer.GetConeAngles の各メソッドを使って、サウンド コーンを定義する角度の設定と取得を行う。外部コーンの角度は、常に内部コーンの角度以上でなければならない。

アプリケーションは、DirectSound3DBuffer.SetConeOrientation と DirectSound3DBuffer.GetConeOrientation の各メソッドを使って、サウンド コーンの方向の設定と取得を行う。

アプリケーションは、DirectSound3DBuffer.SetConeOutsideVolume と DirectSound3DBuffer.GetConeOutsideVolume の各メソッドを使って、外部コーンのボリュームの設定と取得を行う。外部コーンのボリュームは、1/100 dB 単位の負の数で表される。デフォルトのボリュームを 0 とし、このボリュームはそこからの減衰を表すからである。


DirectSound 3D リスナー

サウンドは、聞こえているときに限ってサウンドと言える。DirectSound アプリケーションの 3D サウンド エフェクトは、サウンド バッファの位置と方向と速度だけではなく、リスナーの位置と方向と速度の影響を受ける。

[C++]

IDirectSound3DListener インターフェイスは、3D 空間におけるリスナーの位置、方向、見かけの速度をコントロールする。ドップラー効果の量や距離に応じたボリュームの減衰など、聴感環境の一般的なパラメータもコントロールする。

ここでは、IDirectSound3Dlistener インターフェイスへのポインタを取得する方法と、インターフェイス メソッドを使ってリスナー パラメータを管理する方法を説明する。次のトピックを取り上げる。

[Visual Basic]

DirectSound3DListener クラスは、3D 空間におけるリスナーの位置、方向、見かけの速度をコントロールする。ドップラー効果の量や距離に応じたボリュームの減衰など、聴感環境の一般的なパラメータもコントロールする。

ここでは、DirectSound3DListener オブジェクトを取得する方法と、インターフェイス メソッドを使ってリスナー パラメータを管理する方法を説明する。次のトピックを取り上げる。

  • DirectSound3DListener オブジェクトの取得
  • DirectSound3Dlistener のバッチ パラメータ
  • 遅延設定
  • 距離係数
  • リスナーの方向
  • リスナーの位置と速度
  • ドップラー係数
  • ロールオフ係数


DirectSound3DListener オブジェクトの取得

[C++]

IDirectSound3DListener インターフェイスへのポインタを取得するには、最初にプライマリ 3D サウンド バッファを作成しなければならない。これを作成するには、IDirectSound::CreateSoundBuffer メソッドを使い、関連する DSBUFFERDESC 構造体の dwFlags メンバで DSBCAPS_CTRL3D と DSBCAPS_PRIMARYBUFFER の各フラグを指定する。そして作成されたバッファに対して IDirectSoundBuffer::QueryInterface メソッドを呼び出し、そのバッファの IDirectSound3Dlistener インターフェイスへのポインタを取得する。C++ の構文による次の例はこれを示す。

/* この例では、lpds が DirectSound オブジェクトへの
   有効なポインタであると想定する。*/

DSBUFFERDESC        dsbd;
LPDIRECTSOUNDBUFFER lpdsbPrimary;

ZeroMemory(&dsbd, sizeof(DSBUFFERDESC));
dsbd.dwSize = sizeof(DSBUFFERDESC);
dsbd.dwFlags = DSBCAPS_CTRL3D | DSBCAPS_PRIMARYBUFFER;
if SUCCEEDED(lpds->CreateSoundBuffer(&dsbd, &lpdsbPrimary, NULL))
{
    // リスナー インターフェイスを取得する。
    if FAILED(lpdsbPrimary->QueryInterface(IID_IDirectSound3DListener,
            (LPVOID *)&lp3DListener))
    {
    lpdsbPrimary->Release();
    }
}
[Visual Basic]

DirectSound3DListener オブジェクトを取得するには、最初にプライマリ 3D サウンド バッファを作成しなければならない。これを作成するには、DirectSound.CreateSoundBuffer メソッドを使い、関連する DSBUFFERDESC 型の lFlags メンバで DSBCAPS_CTRL3D と DSBCAPS_PRIMARYBUFFER の各フラグを指定する。そして作成されたバッファに対して DirectSoundBuffer.GetDirectSound3DListener メソッドを呼び出し、DirectSound3DListener オブジェクトを取得する。次の例でこのステップを示す。ds はグローバルな DirectSound オブジェクトである。

Dim dsbd As DSBUFFERDESC
Dim dsbPrimary As DirectSoundBuffer
Dim waveFormat As WAVEFORMATEX
Dim ds3dListener As DirectSound3DListener

' プライマリ バッファを作成する。プライマリ バッファでは
' waveFormat パラメータは無視されるので、初期化しなくてよい。

dsbd.lFlags = DSBCAPS_CTRL3D Or DSBCAPS_PRIMARYBUFFER
Set dsbPrimary = ds.CreateSoundBuffer(dsbd, waveFormat)

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

Set ds3DListener = dsbPrimary.GetDirectSound3DListener

リスナーを取得した後は、プライマリ バッファ オブジェクトは必要なくなり、スコープ外に出せる。


DirectSound3Dlistener のバッチ パラメータ

[C++]

アプリケーションは、3D リスナー オブジェクト パラメータの取得や設定を個別またはバッチ単位で実施できる。個別の値を設定するには、アプリケーションで適用可能な IDirectSound3DListener インターフェイス メソッドを使用できる。しかし、リスナーを表現するすべての値を一度に設定または取得する必要が生じることもよくある。その場合は、IDirectSound3DListener::GetAllParameters と IDirectSound3DListener::SetAllParameters の各メソッドを使うと、バッチ パラメータ操作を 1 回の呼び出しで実行できる。

[Visual Basic]

アプリケーションは、3D リスナー オブジェクト パラメータの取得や設定を個別またはバッチ単位で実施できる。個別の値を設定するには、アプリケーションで適用可能な DirectSound3DListener オブジェクト メソッドを使用できる。しかし、リスナーを表現するすべての値を一度に設定または取得する必要が生じることもよくある。その場合は、DirectSound3DListener.GetAllParameters と DirectSound3DListener.SetAllParameters の各メソッドを使うと、バッチ パラメータ操作を 1 回の呼び出しで実行できる。

また、パラメータの変更は、それらに遅延のフラグを付けておき、その後すべてを一度に実行することでより効率的に行える。詳細については、「遅延設定」を参照すること。


遅延設定

[C++]

3D サウンド バッファとリスナーの設定を変更するたびに、DirectSound ミキサーは再ミキシングを行い、CPU サイクルを消費する。3D 設定の変更による処理性能への影響を最小限に抑えるには、3D 設定を変更する IDirectSound3DListener と IDirectSound3DBuffer のいずれかのメソッドの dwApply パラメータで DS3D_DEFERRED フラグを指定する。その後 IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出し、遅延されていたすべてのコマンドを 1 回で実行する。

[Visual Basic]

3D サウンド バッファとリスナーの設定を変更するたびに、DirectSound ミキサーは再ミキシングを行い、CPU サイクルを消費する。3D 設定の変更による処理性能への影響を最小限に抑えるには、3D 設定を変更する DirectSound3DListener と DirectSound3DBuffer のいずれかのメソッドの applyFlag パラメータで DS3D_DEFERRED フラグを指定する。その後 DirectSound3DListener.CommitDeferredSettings メソッドを呼び出し、遅延されていたすべてのコマンドを 1 回で実行する。

注 : CommitDeferredSettings メソッドを呼び出す前に、アプリケーションが DS3D_IMMEDIATE フラグを指定して同じ設定メソッドを呼び出すと、あらゆる遅延設定値が上書きされる。たとえば、DS3D_DEFERRED フラグを指定してリスナー速度を (1.0, 0.0, 0.0) に設定した後、DS3D_IMMEDIATE フラグを指定してリスナー速度を (2.0, 0.0, 0.0) に設定すると、速度は (2.0, 0.0, 0.0) になる。その後、アプリケーションが CommitDeferredSettings メソッドを呼び出した場合でも、速度は (2.0, 0.0, 0.0) のままで変化しない。


距離係数

DirectSound はデフォルトの距離測定単位としてメートルを使う。アプリケーションがメートルを使わない場合、距離係数、つまりベクトルの単位となる任意の乗数を設定できる。

[C++]

リスナーに対する距離係数を設定した後、リスナーに適用できる任意のメソッドを呼び出す際に、アプリケーション固有の距離単位を使う。たとえば、現在のアプリケーションが測定の基本単位としてフィートを使っているとする。その場合、IDirectSound3DListener::SetDistanceFactor メソッドを呼び出して、flDistanceFactor パラメータに 0.3048 (1 フィートのメートル換算値) を指定する。それ以降、メソッドを呼び出す際にパラメータをフィート単位で指定すると、それらの値はメートル単位に自動的に換算される。

IDirectSound3DListener::GetDistanceFactor メソッドを使うと、リスナーに対して設定されている現在の距離係数を取得できる。

[Visual Basic]

リスナーに対する距離係数を設定した後、リスナーに適用できる任意のメソッドを呼び出す際に、アプリケーション固有の距離単位を使う。たとえば、現在のアプリケーションが測定の基本単位としてフィートを使っているとする。その場合、DirectSound3DListener.SetDistanceFactor メソッドを呼び出して、distanceFactor パラメータに 0.3048 (1 フィートのメートル換算値) を指定する。それ以降、メソッドを呼び出す際にパラメータをフィート単位で指定すると、それらの値はメートル単位に自動的に換算される。

DirectSound3DListener.GetDistanceFactor メソッドを使うと、リスナーに対して設定されている現在の距離係数を取得できる。

距離係数は (1 秒あたり n 単位で表される実際の速度を変更することにより) 主にドップラー効果に影響を及ぼす。ロールオフに直接的な影響を及ぼすことはない。距離に応じた減衰率は、この単位を使った最小距離に基づいているからである。あるサウンドの最小距離を 2 単位に設定した場合、4 単位離れるとボリュームは半分になる。距離がフィートやメートルや他の単位であっても、これは共通である。詳細については、「最小距離と最大距離」を参照すること。


リスナーの方向

リスナーの方向は、リスナーの頭の中心を原点とする 2 つのベクトル、上方ベクトルと前方ベクトルの関係によって定義される。上方ベクトルは頭頂部を通る上向きの直線で、前方ベクトルは上方ベクトルと直角をなしリスナーの顔を通る直線である。次の図はこれらの関係を示す。

[C++]

アプリケーションは IDirectSound3DListener::SetOrientation と IDirectSound3DListener::GetOrientation の各メソッドを使って、リスナーの方向の設定と取得を行う。デフォルトでは、前方ベクトルが (0, 0, 1.0)、上方ベクトルが (0, 1.0, 0) である。

[Visual Basic]

アプリケーションは DirectSound3DListener.SetOrientation と DirectSound3DListener.GetOrientation の各メソッドを使って、リスナーの方向の設定と取得を行う。デフォルトでは、前方ベクトルが (0, 0, 1.0)、上方ベクトルが (0, 1.0, 0) である。

これら 2 つのベクトルは、常に互いに対して直角でなければならない。必要に応じて、DirectSound は前方ベクトルに調整を加え、上方ベクトルに対して直角の関係を保つ。


リスナーの位置と速度

[C++]

アプリケーションは IDirectSound3DListener::SetPosition と IDirectSound3DListener::GetPosition の各メソッドを使って、3D 空間におけるリスナーの位置の設定と取得を行える。

DirectSound がリスナーに対するドップラー効果を計算する際に使う速度値の設定と取得を行うには、IDirectSound3DListener::SetVelocity と IDirectSound3DListener::GetVelocity の各メソッドを使う。速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。

[Visual Basic]

アプリケーションは DirectSound3DListener.SetPosition と DirectSound3DListener.GetPosition の各メソッドを使って、3D 空間におけるリスナーの位置の設定と取得を行える。

DirectSound がリスナーに対するドップラー効果を計算する際に使う速度値の設定と取得を行うには、DirectSound3DListener.SetVelocity と DirectSound3DListener.GetVelocity の各メソッドを使う。速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。

バッファと同様、リスナーの位置と速度とは完全に独立している。リスナーの適切な速度を設定する作業は、完全にアプリケーションに依存している。


ドップラー係数

DirectSound は、速度を持つバッファやリスナーに対して、自動的にドップラー効果を作成する。このエフェクトは累積する。リスナーとサウンド バッファの両方が移動している場合、システムは相対速度を自動的に計算し、それに従ってドップラー効果を調整する。

現実的なドップラー効果をアプリケーションに追加するには、移動しているあらゆるオブジェクトの速度を計算し、その音源またはリスナーの適切な速度を設定しなければならない。特定の状況では特殊効果をもたらすために、この値を自由に誇張または減少させてよい。ドップラー係数を変更すると、ドップラー シフトを全体的に増加または減少させられる。

ドップラー係数は、DS3D_MINDOPPLERFACTOR から DS3D_MAXDOPPLERFACTOR の範囲で変更できるが、これらは現在 Dsound.h 内で 0.0 と 10.0 に設定されている。値 0 は、サウンドにドップラー シフトを適用しないことを意味する。他の値は、実世界のドップラー シフトに対する乗数を表す。言い換えれば、値 1 (または DS3D_DEFAULTDOPPLERFACTOR) は実世界で体験するドップラー シフトをサウンドに適用すること、値 2 は実世界のドップラー シフトの 2 倍を意味する。以下同様である。

[C++]

IDirectSound3DListener::SetDopplerFactor と IDirectSound3DListener::GetDopplerFactor の各メソッドを使うと、ドップラー係数の設定と取得が行える。

[Visual Basic]

DirectSound3DListener.SetDopplerFactor と DirectSound3DListener.GetDopplerFactor の各メソッドを使うと、ドップラー係数の設定と取得が行える。


ロールオフ係数

ロールオフとは、リスナーとサウンドの距離によって生じる音の減衰の度合である。DirectSound はロールオフ係数と呼ぶ変数により、ロールオフの無視、誇張、実世界と同じエフェクトの再現ができる。

ロールオフ係数は、DS3D_MINROLLOFFFACTOR から DS3D_MAXROLLOFFFACTOR の範囲で変更できるが、これらは現在 Dsound.h 内で 0.0 と 10.0 に設定されている。値 DS3D_MINROLLOFFFACTOR は、サウンドにロールオフを適用しないことを意味する。他の値は、実世界のロールオフに対する乗数を表す。言い換えれば、値 1 (DS3D_DEFAULTROLLOFFFACTOR) は実世界で体験するロールオフをサウンドに適用すること、値 2 は実世界のロールオフの 2 倍を意味する。以下同様である。

[C++]

IDirectSound3DListener::SetRolloffFactor と IDirectSound3DListener::GetRolloffFactor の各メソッドを使うと、ロールオフ係数の設定と取得が行える。

[Visual Basic]

DirectSound3DListener.SetRolloffFactor と DirectSound3DListener.GetRolloffFactor の各メソッドを使うと、ロールオフ係数の設定と取得が行える。

個別のサウンド バッファのロールオフを変更するために、そのバッファの最小距離を設定できる。詳細については、「最小距離と最大距離」を参照すること。


DirectSoundCapture

[C++]

DirectSoundCapture は、入力源からデジタル オーディオ データをキャプチャするためのツールのセットをアプリケーションに提供する。DirectSoundCapture を使うには、IDirectSoundCapture インターフェイスのインスタンスを作成し、そのメソッドを使って 1 つのキャプチャ バッファを作成する。実際のキャプチャリングは、バッファ オブジェクトのメソッドによって行われる。

[Visual Basic]

DirectSoundCapture は、入力源からデジタル オーディオ データをキャプチャするためのツールのセットをアプリケーションに提供する。DirectSoundCapture を使うには、DirectSoundCapture オブジェクトを作成し、そのメソッドを使って 1 つのキャプチャ バッファを作成する。実際のキャプチャリングは、DirectSoundCaptureBuffer オブジェクトのメソッドによって行われる。

ここでは、次のトピックを取り上げる。

  • キャプチャ デバイスの列挙
  • DirectSoundCapture オブジェクトの作成
  • キャプチャ デバイスの能力
  • キャプチャ バッファの作成
  • キャプチャ バッファの情報
  • キャプチャ バッファの通知
  • キャプチャ バッファの使い方


キャプチャ デバイスの列挙

[C++]

ユーザーが好む再生装置で単純にサウンドを再生するだけのアプリケーションでは、利用可能なデバイスを列挙する必要はない。デバイス識別子として NULL を指定して DirectSoundCapture オブジェクトを作成する場合、デフォルトのデバイスが存在すると、インターフェイスは自動的にそのデバイスに関連付けられる。デバイス ドライバが存在しない場合は、DirectSoundCaptureCreate 関数の呼び出しは失敗する。

[Visual Basic]

ユーザーが好む再生装置で単純にサウンドを再生するだけのアプリケーションでは、利用可能なデバイスを列挙する必要はない。デバイス識別子として空の文字列を指定して DirectSoundCapture オブジェクトを作成する場合、デフォルトのデバイスが存在すると、インターフェイスは自動的にそのデバイスに関連付けられる。デバイス ドライバが存在しない場合は、DirectX7.DirectSoundCaptureCreate 関数の呼び出しは失敗する。

しかし、特定の種類のデバイスを探している場合や、複数のデバイスを使って動作する必要がある場合は、システム上で利用可能なデバイスを列挙しなければならない。

列挙は 3 つの目的で使われる。

  • 利用可能なハードウェアを報告。
  • 各デバイスに GUID を供給。
  • 各デバイスを列挙したときに、デバイスに対して DirectSoundCapture を初期化。その結果、各デバイスの能力をチェックできる。
[C++]

デバイスを列挙するには、DirectSound がデバイスを見つけるたびに呼び出すコールバック関数を最初に作成しなければならない。必要なすべての処理をこの関数内で実行し、関数に任意の名前を付けることができるが、この関数はプロトタイプである DSEnumCallback と同じ形式で宣言しなければならない。このコールバック関数は、列挙を続ける場合は TRUE、その他 (たとえば必要な能力を備えたデバイスを見つけた後など) の場合は FALSE を返さなければならない。

コールバック関数の例については、「サウンド デバイスの列挙」を参照すること。各デバイスの GUID が、この関数に渡されるパラメータの 1 つとして取得される点に注意すること。

列挙は DirectSoundCaptureEnumerate 関数を使うことにより動作に移される。

DWORD pv;  // 任意の 32 ビット値。

HRESULT hr = DirectSoundCaptureEnumerate(
        (LPDSENUMCALLBACK)DSEnumProc,
        &pv)
[Visual Basic]

デバイスを列挙するには、DirectX7.GetDSCaptureEnum メソッドを最初に呼び出し、デバイスのコレクションを表す DirectSoundEnum オブジェクトを作成しなければならない。その後 DirectSoundEnum.GetDescription、DirectSoundEnum.GetGuid、DirectSoundEnum.GetName の各メソッドを使って各デバイスについて問い合わせできる。


DirectSoundCapture オブジェクトの作成

[C++]

DirectSoundCapture オブジェクトを作成するには、DirectSoundCaptureCreate 関数を呼び出す。この関数は、IDirectSoundCapture インターフェイスへのポインタを返す。

DirectSoundCaptureCreate に渡される lpGUID パラメータは、列挙によって取得された GUID、または好みのキャプチャ デバイスを指す場合は NULL であってもよい。ほとんどの場合、NULL を渡す。

CoCreateInstance 関数を使ってオブジェクトを作成することもできる。その手順は、DirectSound オブジェクトを作成する手順と同様である。詳細については、「DirectSound オブジェクトの作成」を参照すること。CoCreateInstance を使う場合、マルチメディア コントロール パネルでユーザーが選択したデフォルトのキャプチャ デバイスに対応するオブジェクトが作成される。

DirectSound オブジェクトと DirectSoundCapture オブジェクトを共存させたい場合は、DirectSoundCapture オブジェクトの作成と初期化を行う前に、DirectSound オブジェクトの作成と初期化を行う。

オーディオ機器によっては、デフォルトで全二重オーディオ構成になっていないものもある。DirectSound オブジェクトと DirectSoundCapture オブジェクトの作成と初期化の際に問題が発生した場合は、ユーザーに対してオーディオ デバイス プロパティのチェックと、全二重オーディオが有効になっていることの確認を求めなければならない。

[Visual Basic]

DirectSoundCapture オブジェクトを作成するには、DirectX7.DirectSoundCaptureCreate メソッドを呼び出す。このメソッドは、DirectSoundCapture オブジェクトを返す。

DirectSoundCaptureCreate に渡される guid パラメータは、列挙によって取得された GUID、または好みのキャプチャ デバイスを指す場合は空の文字列であってもよい。ほとんどの場合、空の文字列を渡す。

DirectSound オブジェクトと DirectSoundCapture オブジェクトを共存させたい場合は、DirectSoundCapture オブジェクトを作成する前に、DirectSound オブジェクトを作成する。

オーディオ機器によっては、デフォルトで全二重オーディオ構成になっていないものもある。DirectSound オブジェクトと DirectSoundCapture オブジェクトの作成と初期化の際に問題が発生した場合は、ユーザーに対してオーディオ デバイス プロパティのチェックと、全二重オーディオが有効になっていることの確認を求めなければならない。


キャプチャ デバイスの能力

[C++]

キャプチャ デバイスの能力を取得するには、IDirectSoundCapture::GetCaps メソッドを呼び出す。このメソッドの引数は、DSCCAPS 構造体である。ほかの構造体と同様、この引数を渡す前に dwSize メンバを初期化しておかなければならない。戻り値として、この構造体はこのデバイスがサポートするチャンネル数、およびサポートされるフォーマットに関する値の組み合わせを保持する。後者の値は、Win32 ウェーブフォーム オーディオ関数で使われている WAVEINCAPS 構造体の値と同等である。

[Visual Basic]

キャプチャ デバイスの能力を取得するには、DirectSoundCapture.GetCaps メソッドを呼び出す。このメソッドの引数は、DSCCAPS 型である。戻り値として、この型はこのデバイスがサポートするチャンネル数、およびサポートされるフォーマットに関する値の組み合わせを保持する。


キャプチャ バッファの作成

[C++]

DirectSoundCapture オブジェクトの IDirectSoundCapture::CreateCaptureBuffer メソッドを呼び出して、キャプチャ バッファを作成する。

このメソッドに渡されるパラメータの 1 つは DSCBUFFERDESC 構造体であり、これは希望のバッファの特性を記述している。この構造体の最後のメンバは、WAVEFORMATEX 構造体であるが、希望のウェーブ フォーマットの詳細に従ってこの構造体を初期化しなければならない。この構造体のメンバの情報は、「サウンド データ」を参照すること。

アプリケーションが DirectSound と DirectSoundCapture の両方を使う場合、キャプチャ バッファのフォーマットがプライマリ バッファのフォーマットと異なっていると、キャプチャ バッファの作成は失敗する。一部のカードはクロックを 1 つしか用意していないため、2 つの異なった周波数でキャプチャと再生を行えないのが原因である。

次の例では、およそ 1 秒分のデータを保持するキャプチャ バッファを設定する。

/* この例では、pDSC が DirectSoundCapture オブジェクトへの
   有効なポインタであることを想定する。*/

DSCBUFFERDESC              dscbd;
LPDIRECTSOUNDCAPTUREBUFFER pDSCB;
WAVEFORMATEX               wfx =
    {WAVE_FORMAT_PCM, 2, 44100, 176400, 4, 16, 0};
    // wFormatTag、nChannels、nSamplesPerSec、mAvgBytesPerSec、
    // nBlockAlign、wBitsPerSample、cbSize
dscbd.dwSize = sizeof(DSCBUFFERDESC);
dscbd.dwFlags = 0;
dscbd.dwBufferBytes = wfx.nAvgBytesPerSec;
dscbd.dwReserved = 0;
dscbd.lpwfxFormat = &wfx;

pDSCB = NULL;

HRESULT hr = pDSC->CreateCaptureBuffer(&dscbd,
        &pDSCB, NULL);
[Visual Basic]

DirectSoundCapture.CreateCaptureBuffer メソッドを呼び出して、キャプチャ バッファを作成する。

このメソッドに渡される 1 つのパラメータは DSCBUFFERDESC 型であり、これは希望のバッファの特性を記述している。fxFormat メンバは WAVEFORMATEX 型であるが、希望のウェーブ フォーマットの詳細に従ってこの型を初期化しなければならない。

アプリケーションが DirectSound と DirectSoundCapture の両方を使う場合、キャプチャ バッファのフォーマットがプライマリ バッファのフォーマットと異なっていると、キャプチャ バッファの作成は失敗する。一部のカードはクロックを 1 つしか用意していないため、2 つの異なった周波数でキャプチャと再生を行えないのが原因である。

次の例では、およそ 1 秒分のデータを保持するキャプチャ バッファを設定する。

' DSC は DirectSoundCapture オブジェクト。

Dim dscbd As DSCBUFFERDESC
Dim DSCB As DirectSoundCaptureBuffer
Dim waveFormat As WAVEFORMATEX

' ウェーブ フォーマットを設定する。

waveFormat.nSize = LenB(waveFormat)
    waveFormat.nFormatTag = WAVE_FORMAT_PCM
    waveFormat.nChannels = 2
    waveFormat.lSamplesPerSec = 22050
    waveFormat.nBitsPerSample = 16
    waveFormat.nBlockAlign = _
            waveFormat.nBitsPerSample / 8 * WaveFormat.nChannels
    waveFormat.lAvgBytesPerSec = _
            waveFormat.lSamplesPerSec * waveFormat.nBlockAlign

' DSCBUFFERDESC を設定する。

dscbd.lFlags = DSCBCAPS_DEFAULT
dscbd.lBufferBytes = waveFormat.lAvgBytesPerSec
dscbd.fxFormat = waveFormat

' キャプチャ バッファを作成する。

Set DSCB = DSC.CreateCaptureBuffer (dscbd)


キャプチャ バッファの情報

[C++]

IDirectSoundCaptureBuffer::GetCaps メソッドを使って、キャプチャ バッファのサイズを取得する。この構造体をパラメータとして渡す前に、DSCBCAPS 構造体の dwSize メンバを初期化しておかなければならない。バッファ作成時に設定された、バッファ内のデータ フォーマットの情報を取得することもできる。IDirectSoundCaptureBuffer::GetFormat メソッドを呼び出すと、このメソッドは WAVEFORMATEX 構造体を使ってフォーマット情報を返す。この構造体のメンバの情報は、「サウンド データ」を参照すること。

lpwfxFormat パラメータで NULL を指定して GetFormat メソッドを最初に呼び出すことにより、アプリケーションが WAVEFORMATEX 構造体を通して追加のフォーマット情報を入手できる点に注意すること。この場合、lpdwSizeWritten パラメータが指す DWORD が、完全なフォーマット情報を受け取るのに必要な構造体のサイズを受け取る。

キャプチャ バッファが現在行っていることを把握するには、IDirectSoundCaptureBuffer::GetStatus メソッドを呼び出す。このメソッドはフラグの組み合わせを変数 DWORD に書き込むが、そのフラグはバッファがキャプチャリングでビジーであるかどうか、ビジーの場合はループしているかどうか (つまり IDirectSoundCaptureBuffer::Start を直前に呼び出した時点で DSCBSTART_LOOPING フラグをセットしていたか) を示す。

最後に、IDirectSoundCaptureBuffer::GetCurrentPosition メソッドは、バッファ内での現在の読み込み位置とキャプチャ位置を返す。読み込み位置は、この時点でキャプチャされてバッファに置かれたデータの最後である。キャプチャ位置は、現在ハードウェアからコピーされている最中のデータ ブロックの最後である。バッファから安全にコピーできるのは読み込み位置までのデータのみである。

[Visual Basic]

DirectSoundCaptureBuffer.GetCaps メソッドを使って、バッファ能力についての情報を取得する。バッファ作成時に設定されたバッファのデータ フォーマットについての情報を取得するには、DirectSoundCaptureBuffer.GetFormat メソッドを呼び出す。

キャプチャ バッファが行っていることを把握するには、DirectSoundCaptureBuffer.GetStatus メソッドを呼び出す。このメソッドはフラグの組み合わせを返すが、そのフラグはバッファがキャプチャリングでビジーであるかどうか、ビジーの場合はループしているかどうか (つまり DirectSoundCaptureBuffer.Start を直前に呼び出した時点で DSCBSTART_LOOPING フラグをセットしていたか) を示す。

最後に、DirectSoundCaptureBuffer.GetCurrentPosition メソッドは、バッファ内での現在の読み込み位置とキャプチャ位置を返す。読み込み位置は、この時点でキャプチャされてバッファに置かれたデータの最後である。キャプチャ位置は、ハードウェアからコピーされている最中のデータ ブロックの最後である。バッファから安全にコピーできるのは読み込み位置までのデータのみである。


キャプチャ バッファの通知

[C++]

現在の読み込み位置がバッファ内のある位置または最後に達したときに、アプリケーションへの通知を発生させたいことがある。バッファ内で現在の読み込み位置までの部分は、安全に読み込みができる。IDirectSoundNotify::SetNotificationPositions メソッドを使うと、イベントのシグナルを送信するポイントをバッファ内にいくつでも設定できる。

最初に IDirectSoundNotify インターフェイスへのポインタを取得しなければならない。「再生バッファの通知」で説明したとおり、キャプチャ バッファの QueryInterface メソッドを使ってこの取得が行える。

次に、Win32 の CreateEvent 関数を使って、イベント オブジェクトを作成する。このイベントへのハンドルを DSBPOSITIONNOTIFY 構造体の hEventNotify メンバに書き込み、この構造体の dwOffset メンバで、バッファ内でイベントのシグナルを送信したい位置のオフセットを指定する。そしてこの構造体のアドレスを、または複数の通知位置を設定したい場合は構造体の配列を、IDirectSoundNotify::SetNotificationPositions メソッドに渡す。

次の例は、3 つの通知位置を設定する。1 つのイベントは読み込み位置がバッファ内の中央に達したとき、2 番目は最後の近くに達したとき、3 番目はキャプチャが停止したときに、それぞれシグナルを送信する。

#define cEvents  3

/* この例では、次の各変数が既に正しく初期化されていて、
   バッファを作成する際にそれらの変数の wfx がバッファ記述に
   含められたことを想定する。

   LPDIRECTSOUNDNOTIFY  lpDsNotify;
   WAVEFORMATEX          wfx;
*/

HANDLE             rghEvent[cEvents] = {0};
DSBPOSITIONNOTIFY  rgdsbpn[cEvents];
HRESULT            hr;
int                i;

// イベントを作成する。
for (i = 0; i < cEvents; ++i)
{
    rghEvent[i] = CreateEvent(NULL, TRUE, FALSE, NULL);
    if (NULL == rghEvent[i])
    {
        hr = GetLastError();
        goto Error;
    }
}

// 通知を記述する。

rgdsbpn[0].dwOffset = (wfx.nAvgBytesPerSec/2) -1;
rgdsbpn[0].hEventNotify = rghEvent[0];

rgdsbpn[1].dwOffset = wfx.nAvgBytesPerSec - 1;
rgdsbpn[1].hEventNotify = rghEvent[1];

rgdsbpn[2].dwOffset = DSBPN_OFFSETSTOP;
rgdsbpn[2].hEventNotify = rghEvent[2];

// 通知を作成する。

hr = lpDsNotify->SetNotificationPositions(cEvents, rgdsbpn);
[Visual Basic]

現在の読み込み位置がバッファ内のある位置または最後に達したときに、アプリケーションへの通知を発生させたいことがある。バッファ内で現在の読み込み位置までの部分は、安全に読み込みができる。DirectSoundCaptureBuffer.SetNotificationPositions メソッドを使うと、イベントのシグナルを送信するポイントをバッファ内にいくつでも設定できる。

バッファに通知イベントを設定するには、バッファのコードを保持するフォームに DirectXEvent オブジェクトを最初に実装しなければならない。次に、DirectX7.CreateEvent メソッドを呼び出してイベント ハンドルを作成し、そのイベント ハンドルを DSBPOSITIONNOTIFY 型の hEventNotify メンバに渡す。そして DSBPOSITIONNOTIFY 型を DirectSoundCaptureBuffer.SetNotificationPositions メソッドに渡す。

再生位置がバッファの通知位置に達すると、DirectXEvent.DXCallback が呼び出される。


キャプチャ バッファの使い方

[C++]

サウンドのキャプチャは、次のステップで構成される。

  1. IDirectSoundCaptureBuffer::Start メソッドを呼び出してバッファリングを開始する。入力デバイスから得たオーディオ データを、バッファの開始位置以降に書き込む。
  2. 希望の量のデータが利用可能になるまで待つ。キャプチャ位置が特定の地点に達する時期を決定する方法の 1 つについては、「キャプチャ バッファの通知」を参照すること。
  3. 十分なデータが利用可能になったとき、IDirectSoundCaptureBuffer::Lock メソッドを呼び出してキャプチャ バッファの一部をロックする。

    ロックを試みる部分が、キャプチャに使われようとしているメモリ部分と重なっていないことを確認するには、最初に IDirectSoundCaptureBuffer::GetCurrentPosition を呼び出して現在の読み込み位置を取得する。読み込み位置については、「キャプチャ バッファの情報」を参照すること。

    Lock メソッドのパラメータとして、読み込みたいメモリ ブロックのサイズとオフセットを渡す。このメソッドは、メモリ ブロック開始位置のアドレスへのポインタと、ブロックのサイズを返す。ブロックがバッファの最後から最初へラップ アラウンドしている (先頭へ戻っている) 場合、ブロックのセクションごとに 1 つ、合計 2 つのポインタが返される。バッファのロック部分がラップ アラウンドしていない場合は、2 番目のポインタは NULL である。

  4. Lock メソッドが返したアドレスとブロック サイズを使って、バッファからデータをコピーする。
  5. IDirectSoundCaptureBuffer::Unlock メソッドを使って、バッファをアンロックする。
  6. 全データのキャプチャが終わるまで、ステップ 2 から 5 を繰り返す。次に、IDirectSoundCaptureBuffer::Stop メソッドを呼び出す。

通常、キャプチャ位置がバッファの最後に達すると、バッファはキャプチャリングを自動的に停止する。しかし、IDirectSoundCaptureBuffer::Start メソッドに渡す dwFlags パラメータで DSCBSTART_LOOPING フラグをセットした場合は、アプリケーションが IDirectSoundCaptureBuffer::Stop メソッドを呼び出すまでキャプチャは続行される。

[Visual Basic]

サウンドのキャプチャは、次のステップで構成される。

  1. DirectSoundCaptureBuffer.Start メソッドを呼び出してバッファリングを開始する。入力デバイスから得たオーディオ データを、バッファの開始位置以降に書き込む。
  2. 希望の量のデータが利用可能になるまで待つ。キャプチャ位置が特定の地点に達する時期を決定する方法の 1 つについては、「キャプチャ バッファの通知」を参照すること。
  3. 十分なデータが利用可能になったとき、DirectSoundCaptureBuffer.ReadBuffer メソッドを呼び出してキャプチャ バッファの一部を読み込む。

    読み込みを試みる部分が、キャプチャに使われようとしているメモリ部分と重なっていないことを確認するには、DirectSoundCaptureBuffer.GetCurrentPosition を呼び出して現在の読み込み位置を取得する。読み込み位置については、「キャプチャ バッファの情報」を参照すること。

  4. 全データのキャプチャが終わるまで、ステップ 2 から 3 を繰り返す。次に、DirectSoundCaptureBuffer.Stop メソッドを呼び出す。

デフォルトでは、キャプチャ位置がバッファの最後に達すると、バッファはキャプチャリングを自動的に停止する。しかし、DirectSoundCaptureBuffer.Start メソッドに渡す flags パラメータで DSCBSTART_LOOPING フラグをセットした場合は、アプリケーションが DirectSoundCapture.Stop メソッドを呼び出すまでキャプチャは続行される。


DirectSound プロパティ セット

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

IKsPropertySet インターフェイスを通して、DirectSound はサウンド カードとその関連ドライバの提供する拡張サービスをサポートできる。

プロパティはセットに編成される。GUID がセットを識別し、ULONG がセット内の特定のプロパティを識別する。たとえば、ハードウェア ベンダーが反響エフェクトを作成できるカードを設計し、DSPROPERTY_REVERBPROPERTIES_HALL と DSPROPERTY_REVERBPROPERTIES_STADIUM などのプロパティを保持するプロパティ セット DSPROPSETID_ReverbProperties を定義することも考えられる。

通常、番号 0 で始まる C 言語の列挙型を使ってプロパティ識別子を定義する。

個別のプロパティにパラメータを関連付けてもよい。IKsPropertySet インターフェイスの仕様は、意図的にそれらのパラメータを未定義にしているので、プロパティセットの設計者は、設計対象のセット内のプロパティにとって最も役立つ方法で設計を行える。パラメータの正確な意味は、プロパティの定義によって決まる。

サウンド カード上の拡張プロパティを利用するには、最初にそのドライバが IKsPropertySet インターフェイスをサポートしているかどうかを確認し、サポートしている場合はそのインターフェイスへのポインタを取得しなければならない。これを行うには、DirectSound3DBuffer オブジェクト上の現存するインターフェイスに対して QueryInterface メソッドを呼び出す。

HRESULT hr = lpDirectSound3DBuffer->QueryInterface(
        IID_IKsPropertySet,
        (void**)&lpKsPropertySet));

この例では、lpDirectSound3DBuffer はバッファのインターフェイスへのポインタであり、IKsPropertySet インターフェイスが見つかった場合は、lpKsPropertySet はそのアドレスを受け取る。IID_lpKsPropertySet は、Dsound.h 内で定義されている GUID である。

バッファがハードウェア アクセラレートされている場合に限り、この呼び出しは成功する。成功した場合は、IKsPropertySet::QuerySupport メソッドを使って特定のプロパティを検索できる。PropertySetId パラメータの値は、ハードウェア ベンダーによって定義された GUID である。

特定のプロパティに対するサポートが存在すると確認した後は、IKsPropertySet::Set メソッドによるプロパティの状態の変更と、IKsPropertySet::Get メソッドによる現在の状態の確認が行える。pPropertyData パラメータを使って、プロパティの状態の設定と取得を行う。

IKsPropertySet::Set の pPropertyParams パラメータが指す構造体内のオブジェクトに、追加のプロパティ パラメータを渡してもよい。このパラメータの正確な使用方法は、プロパティ セットに関するハードウェア ベンダーの仕様書で定義されるが、プロパティ セットのインスタンスを定義するために使われるのが普通である。実際には、pPropertyParams を使うことはほとんどない。

少し変わった例について取り上げる。あるサウンド カードには、数人の有名なテノール歌手の声で一連の歌を演奏する機能が備わっているとする。ドライバ開発者は、DSPROPERTY_SONG_IRISH_EYES や DSPROPERTY_SONG_O_SOLE_MIO などのプロパティを保持するプロパティ セット DSPROPSETID_Song を作成する。ドライバ開発者はこのプロパティ セットをすべてのテノール歌手に適用し、pPropertyParams がテノールのインスタンスを定義すると指定した。ここでアプリケーション開発者は、Caruso (カルーゾ) にこれらの歌のいずれかを歌わせたいと考えている。

/* ハードウェア ベンダーが既にヘッダー ファイル内で CARUSO と START
   を定義していることを想定する。*/

DWORD dwTenor = CARUSO;
BOOL  StartOrStop = START;

HRESULT hr = lpKsPropertySet->Set(
        DSPROPSETID_Song,
        DSPROPERTY_SONG_IRISH_EYES,
        &dwTenor,
        sizeof(dwTenor),
        &StartOrStop,
        sizeof(StartOrStop));


DirectSound の性能の最適化

ここでは、DirectSound の性能を向上させる他のいくつかのヒントを提供する。次のトピックを取り上げる。

  • バッファ フォーマットのマッチング
  • プライマリ バッファの連続再生
  • ハードウェア ミキシングの利用
  • コントロールの変更の最少化
  • 3D バッファに関係する CPU の考慮事項


バッファ フォーマットのマッチング

DirectSound ミキサーは、各セカンダリ バッファから得たデータをプライマリ バッファ用のフォーマットに変換する。この変換はデータをプライマリ バッファにミキシングする際にその場で行われ、CPU サイクルを消費する。プライマリ バッファのフォーマットをセカンダリ バッファ (つまりウェーブ ファイル) に合わせることにより、このオーバーヘッドを排除できる。

DirectSound の採用するフォーマット変換方法では、サンプリング レートとチャンネル数を合わせるだけでよい。サンプリング サイズ (8 ビットか 16 ビットか) は関係ない。


プライマリ バッファの連続再生

[C++]

サウンドが再生されていない場合、DirectSound はミキサー エンジンを停止し、DMA (ダイレクト メモリ アクセス) を停止させる。再生なしの状態が頻繁に発生するアプリケーションでは、サウンドを再生するたびにミキサーの開始と停止を行う場合のオーバーヘッドは、ミキサーを常時アクティブにする場合の DMA のオーバーヘッドより大きくなることがある。また、サウンド機器やドライバによっては、再生の頻繁な開始と停止により不要な雑音を出すこともある。アプリケーションがほぼ連続的に再生を行い、休止時間が少ない場合は、プライマリ バッファに対して IDirectSoundBuffer::Play メソッドを呼び出し、ミキサー エンジンを常時アクティブにもできる。ミキサーは音を出さずに連続運転する。

サウンドの再生がないときにミキサー エンジンを停止するデフォルトの状態に戻すには、プライマリ バッファに対して IDirectSoundBuffer::Stop メソッドを呼び出す。

[Visual Basic]

サウンドが再生されていない場合、DirectSound はミキサー エンジンを停止し、DMA (ダイレクト メモリ アクセス) を停止させる。再生なしの状態が頻繁に発生するアプリケーションでは、サウンドを再生するたびにミキサーの開始と停止を行う場合のオーバーヘッドは、ミキサーを常時アクティブにする場合の DMA のオーバーヘッドより大きくなることがある。また、サウンド機器やドライバによっては、再生の頻繁な開始と停止により不要な雑音を出すこともある。アプリケーションがほぼ連続的に再生を行い、休止時間が少ない場合は、プライマリ バッファに対して DirectSoundBuffer.Play メソッドを呼び出し、ミキサー エンジンを常時アクティブにもできる。ミキサーは音を出さずに連続運転する。

サウンドの再生がないときにミキサー エンジンを停止するデフォルトの状態に戻すには、プライマリ バッファに対して DirectSoundBuffer.Stop メソッドを呼び出す。

詳細については、「プライマリ バッファへのアクセス」を参照すること。


ハードウェア ミキシングの利用

ほとんどのサウンド カードは、対応する DirectSound ドライバが存在すれば、何らかのレベルのハードウェア ミキシングをサポートする。次のヒントは、ハードウェア ミキシングをできるだけ利用するのに役立つ。

[C++]
  • 実行時に IDirectSound::GetCaps メソッドを呼び出して、サウンドアクセラレータ ハードウェアがサポートしているフォーマットを確認し、できる限りそのフォーマットを使う。
  • 最も利用の多いサウンドのサウンド バッファを最初に作成する。ハードウェアでミキシングできるバッファ数には限度がある。
  • バッファをハードウェアに必ず作成するには、DSBUFFERDESC 構造体の dwFlags メンバに DSBCAPS_LOCHARDWARE フラグを指定する。このフラグを指定し、ハードウェア ミキシングに対するリソースが利用できない場合は、IDirectSound::CreateSoundBuffer メソッドは失敗する。
  • ボイス管理を使って、ハードウェア リソースが利用可能なときにバッファをリソースに割り当てたり、あまり重要でないバッファを強制終了させてハードウェア リソースを解放できるようにする。詳細については、「ダイナミック ボイス管理」を参照すること。
[Visual Basic]

ほとんどのサウンドカードは、対応する DirectSound ドライバが存在すれば、何らかのレベルのハードウェア ミキシングをサポートする。次のヒントは、ハードウェア ミキシングをできるだけ利用するのに役立つ。

  • 実行時に DirectSound.GetCaps メソッドを呼び出して、サウンドアクセラレータ ハードウェアがサポートしているフォーマットを確認し、できる限りそのフォーマットを使う。
  • 最も利用の多いサウンドのサウンド バッファを最初に作成する。ハードウェアでミキシングできるバッファ数には限度がある。
  • バッファをハードウェアに必ず作成するには、DSBUFFERDESC 型の lFlags メンバに DSBCAPS_LOCHARDWARE フラグを指定する。このフラグを指定し、ハードウェア ミキシングに対するリソースが利用できない場合は、DirectSound.CreateSoundBuffer メソッドは失敗する。


コントロールの変更の最少化

セカンダリ バッファのパン、ボリューム、周波数を変更すると性能に影響する。サウンド出力が途切れることを防止するには、DirectSound ミキサーは 20ms から 100ms、またはそれ以上先行してミキシングを行わなければならない。コントロールを変更した場合は、ミキサーは先行ミキシング バッファをフラッシュ (消去) し、変更後のサウンドを使って再ミキシングを行わなければならない。

[C++]

送信するコントロールの変更回数を最少にすることは良い考えである。IDirectSoundBuffer::SetVolume、IDirectSoundBuffer::SetPan、IDirectSoundBuffer::SetFrequency の各メソッドを使うルーチンの呼び出し回数を減らすよう努める。たとえば、アニメーションのフレームに同期して音を左スピーカから右スピーカへ動かすルーチンを使っている場合、SetPan メソッドを 1 フレームごとに 2 回でなく 1 回呼ぶことを試みる。

[Visual Basic]

送信するコントロールの変更回数を最少にすることは良い考えである。DirectSoundBuffer.SetVolume、DirectSoundBuffer.SetPan、DirectSoundBuffer.SetFrequency の各メソッドを使うルーチンの呼び出し回数を減らすよう努める。たとえば、アニメーションのフレームに同期して音を左スピーカから右スピーカへ動かすルーチンを使っている場合、SetPan メソッドを 1 フレームごとに 2 回でなく 1 回呼ぶことを試みる。

注 : 3D コントロール (方向、位置、速度、ドップラー係数など) を変更した場合も、DirectSound ミキサーは先行ミキシング バッファを再ミキシングしなければならない。しかし、3D コントロールの変更をグループ化し、再ミキシングを 1 回に削減できる。「遅延設定」を参照すること。


3D バッファに関係する CPU の考慮事項

ソフトウェアによる 3D バッファのエミュレーションは、多くの計算処理を要する。たとえば、各バッファが Pentium 90 の処理時間の約 6 パーセントを消費することもある。アプリケーション内の 3D バッファの使用時期と使用方法を決める際にこのことを考慮する必要がある。

[C++]

3D サウンドの利用は最小限に抑え、3D エフェクトが利点とならないサウンドには 3D サウンドを適用しない。各サウンドの 3D エフェクトを簡単に有効または無効にできるようアプリケーションを設計する。任意の 3D サウンド バッファに対する 3D 処理を停止するには、DS3DMODE_DISABLE フラグを指定して IDirectSound3DBuffer::SetMode メソッドを呼び出す。

[Visual Basic]

3D サウンドの利用は最小限に抑え、3D エフェクトが利点とならないサウンドには 3D サウンドを適用しない。各サウンドの 3D エフェクトを簡単に有効または無効にできるようアプリケーションを設計する。任意の 3D サウンド バッファに対する 3D 処理を停止するには、DS3DMODE_DISABLE フラグを指定して DirectSound3DBuffer.SetMode メソッドを呼び出す。

DirectSound は、3D オーディオ バッファのアクセラレーションを実現するための手段をハードウェア メーカに提供する。それらのオーディオ カードでは、ホスト CPU の消費を考慮する必要はない。


ウェーブ ファイルの使い方

[Visual Basic]

DirectSound でウェーブ ファイルを使う情報は、次のトピックで取り上げる。

[C++]

IDirectSound と IDirectSoundCapture の各インターフェースは、ウェーブ ファイルを処理するためのメソッドを備えていない。しかし、いくつかのサンプル アプリケーションのソース コードは、ウェーブ ファイルを開き、作成し、ファイル ヘッダーの読み込みと書き込みを行い、ファイルとの間でデータのストリーミングを行う関数をインクルードしている。これらの関数は、Wavread.cpp と Wavwrite.cpp にある。

ウェーブ ファイルは RIFF (Resource Interchange File Format、リソース交換ファイル フォーマット) を採用しており、ヘッダー情報 (たとえばサウンド サンプルのウェーブ フォーマット) とデータ (サンプル自体) を保持する、任意の数の「チャンク」によって構成されている。Win32 API は、RIFF ファイルを開いたり閉じたりするための関数や、チャンクの検索関数などを提供する。名前が「mmio」で始まるこれらの関数は、サンプル コード内のラッパー関数によって使われている。

ラッパー関数の使い方についての詳細は、次の 2 つのトピックで取り上げる。

  • ウェーブ ファイルの読み込み
  • ウェーブ ファイルへの書き込み


ウェーブ ファイルの読み込み

[Visual Basic]

短いサウンドでは、DirectSound.CreateSoundBufferFromFile メソッドを使ってスタティック バッファにウェーブ ファイルをロードすることが、ウェーブ ファイルを再生する最も簡単な方法である。メモリに都合よく収まらないほどの長いファイルでは、ストリーム バッファを作成し、部分的にファイルを読み込まなくてはならない。

ウェーブ ファイルは RIFF (Resource Interchange File Format、リソース交換ファイル フォーマット) を採用しており、ファイル ヘッダーと、それぞれヘッダーとデータから成る任意の数の「チャンク」によって構成されている。チャンク ヘッダーは、データの型を識別する 4 文字のタグとデータの長さを与える Long で構成される。

ウェーブ ファイル ヘッダーは次のようになる。

  • 文字列 "RIFF"。Long &H46464952 としても読み取り可能。
  • ファイルのサイズを与える Long。
  • 文字列 "WAVE"。Long &H45564157 としても読み取り可能。

最初のチャンクは常にフォーマット チャンクであり、次のようなフォーマットになる。

  • 文字列 "fmt" とそれに続くスペース。
  • フォーマット データのサイズを与える Long。
  • データのウェーブ フォーマットを記述するデータ。PCM フォーマットのファイルでは、このデータは WAVEFORMATEX 型のデータと同じ (編成は異なる) 16 バイトのデータとなる。

ウェーブ ファイルの PCM サンプル データは、文字列 "data" で始まるチャンクに保持される。これは、Long &H61746164 としても読み取られる。ほとんどの場合このチャンクはフォーマット チャンクに直接続くが、RIFF が拡張可能なフォーマットなので、他のタイプのチャンクが先行しないという保証はない。ファイル パーサーには、処理できないチャンクを無視できる能力が必要である。

ウェーブ ファイルを解析するには、3 つのユーザー定義型を準備するとよい。最初のタイプは、ファイル ヘッダーとフォーマット チャンクのヘッダー内の情報をすべて受け取る。

Private Type FileHeader
    lRiff As Long
    lFileSize As Long
    lWave As Long
    lFormat As Long
    lFormatLength As Long
End Type

2 番目のタイプは、フォーマット データを受け取る。これには、メンバが異なる順序である WAVEFORMATEX 型は使えない。この型は、16 バイトのチャンクのうち 14 バイトだけを取得しなければならない。なぜなら、最後の Integer 値は WAVEFORMATEX.lExtra と同等で、PCM ファイルでは使われないからである。

Private Type WaveFormat
    wFormatTag As Integer
    nChannels As Integer
    nSamplesPerSec As Long
    nAvgBytesPerSec As Long
    nBlockAlign As Integer
    wBitsPerSample As Integer
End Type

3 番目のタイプは、データ チャンクも含め任意のチャンクのヘッダーを取得するのに使われる。

Private Type ChunkHeader
    lType As Long
    lLen As Long
End Type

次のサンプル関数は、ファイルが RIFF ウェーブ ファイルであることを確認し、サンプル データの始まりを検索し、ウェーブ フォーマットについての情報を保持する WAVEFORMATEX 型を返す。

Dim FileFree As Long           ' グローバルなファイル ハンドル。
Dim lDataLength As Long        ' グローバルなデータ長。

Private Function FillFormat(FileName As String) As WAVEFORMATEX

    Dim Header As FileHeader
    Dim HdrFormat As WaveFormat
    Dim chunk As ChunkHeader
    Dim by As Byte
    Dim i As Long

    ' ファイルを開き、ヘッダーを読み込む。

    Close #FileFree
    FileFree = FreeFile
    Open FileName For Binary Access Read As #FileFree
    Get #FileFree, , Header

    ' "RIFF" タグをチェックし、見つからない場合は終了する。

    If Header.lRiff <> &H46464952 Then
        Exit Function
    End If

    ' "WAVE" タグをチェックし、見つからない場合は終了する。

    If Header.lWave <> &H45564157 Then
        Exit Function
    End If

    ' フォーマット チャンクの長さをチェックする。16 バイトよりも
    ' 少ない場合は、PCM データではないので使えない。

    If Header.lFormatLength < 16 Then
        Exit Function
    End If

    ' フォーマットを取得する。

    Get #FileFree, , HdrFormat

    ' フォーマット バイトを捨て、次のチャンクを検索する。

    For i = 1 To Header.lFormatLength - 16
        Get #FileFree, , by
    Next

    ' "data" チャンクに達するまでチャンクを無視する。

    Get #FileFree, , chunk
    Do While chunk.lType <> &H61746164
        For i = 1 To chunk.lLen
            Get #FileFree, , by
        Next
        Get #FileFree, , chunk
    Loop

    ' データのサイズを取得する。

    lDataLength = chunk.lLen

   ' フォーマット情報を返された型に書き込む。

    With FillFormat
        .lAvgBytesPerSec = HdrFormat.nAvgBytesPerSec
        .lExtra = 0
        .lSamplesPerSec = HdrFormat.nSamplesPerSec
        .nBitsPerSample = HdrFormat.wBitsPerSample
        .nBlockAlign = HdrFormat.nBlockAlign
        .nChannels = HdrFormat.nChannels
        .nFormatTag = HdrFormat.wFormatTag
    End With

End Function

これでアプリケーションは、ファイルからのデータを読み込み、セカンダリ サウンド バッファにそのデータをストリーミングできるようになる。ファイルからデータを直接 DirectSoundBuffer に読み込む方法はないので、最初にプライベート バッファにそのデータを読み込んでから、DirectSoundBuffer.WriteBuffer を使ってそのデータを書き込まなければならない。詳細については、「ストリーム バッファの使い方」を参照すること。

[C++]

Wavread.cpp 内でラッパー関数を使うには、次の 4 つの変数を宣言しなければならない。

WAVEFORMATEX  *pwfx;          // ウェーブ フォーマット情報。
HMMIO         hmmio;          // ファイル ハンドル。
MMCKINFO      mmckinfoData;   // チャンク情報。
MMCKINFO      mmckinfoParent; // 親チャンクの情報。

ウェーブ ファイルを読み込む最初のステップは、WaveOpenFile 関数を呼び出すことである。この関数はファイルへのハンドルを取得し、そのファイルが RIFF フォーマットであることを確認し、ウェーブ フォーマットに関する情報を取得する。パラメータとして、ファイル名と、宣言した変数のうち 3 つの変数のアドレスを指定する。

if (WaveOpenFile(lpzFileName, &hmmio, &pwfx, &mmckinfoParent) != 0)
{
    // 失敗。
}

どのラッパー関数も、成功した場合は 0 を返す点に注意すること。

次のステップは WaveStartDataRead 関数を呼び出し、ファイル ポインタを使ってデータ チャンクに到達することである。この関数はデータ チャンク用の MMCKINFO 構造体への書き込みを行うので、利用可能なデータの量を把握できる。

if (WaveStartDataRead(&hmmio, &mmckinfoData, &mmckinfoParent) != 0)
    {
    // 失敗。
    }

これで、アプリケーションはファイルからセカンダリ バッファへのコピーを開始できる。通常は、データ チャンクのサイズとウェーブのフォーマットを取得するまではサウンド バッファを作成しない。次のコードは、ファイル内の全データを保持するのにちょうど良いサイズのスタティック バッファを作成する。

/* lpds が DirectSound オブジェクトへの有効なポインタである
   と想定する。*/

LPDIRECTSOUNDBUFFER  lpdsbStatic;
DSBUFFERDESC         dsbdesc;

memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
dsbdesc.dwSize = sizeof(DSBUFFERDESC);
dsbdesc.dwFlags = DSBCAPS_STATIC;
dsbdesc.dwBufferBytes = mmckinfoData.cksize;
dsbdesc.lpwfxFormat = pwfx;

if FAILED(lpds->CreateSoundBuffer(&dsbdesc, &lpdsbStatic, NULL))
{
    WaveCloseReadFile(&hmmio, &pwfx);
    return FALSE;
}

この場合は、アプリケーションはデータのストリーミングを行わず、単純にスタティック バッファへの書き込みを行うので、バッファ全体は先頭からロックされる。ラップ アラウンド (先頭へ戻る) も発生しないので、必要なのは 1 つのポインタとバイト カウントである。

LPVOID lpvAudio1;
DWORD  dwBytes1;

if FAILED(lpdsbStatic->Lock(
        0,              // ロック開始のオフセット。
        0,              // ロックのサイズ。この場合は無視される。
        &lpvAudio1,     // ロック開始のアドレス。
        &dwBytes1,      // ロックされたバイト数。
        NULL,           // ラップ アラウンドの開始。不使用。
        NULL,           // ラップ アラウンドのサイズ。不使用。
        DSBLOCK_ENTIREBUFFER))  // フラグ。
{
    // エラー処理。
    Close();
    .
    .
    .
}

WaveReadFile 関数は、ファイルからバッファのポインタへデータをコピーし、成功した場合は 0 を返す。

UINT cbBytesRead;

if (WaveReadFile(
        hmmio,              // ファイル ハンドル。
        dwBytes1,           // 読み込むべきバイト数。
        (BYTE *) lpvAudio1, // コピー先。
        &mmckinfoData,      // ファイル チャンク情報。
        &cbBytesRead))      // 実際に読み込まれたバイト数。
{
    // 0 以外の値が返された場合の失敗を処理する。
    WaveCloseReadFile(&hmmio, &pwfx);
    .
    .
    .
}

最後にアプリケーションはバッファをアンロックし、ウェーブ ファイルを閉じる。

lpdsbStatic->Unlock(lpvAudio1, dwBytes1, NULL, 0);
Close();

ストリーム バッファの場合は、通常は現在の読み込み位置によって決定された一定の間隔で WaveReadFile を呼び出す。(「再生バッファの通知」を参照。) バッファ内のロックされた部分がラップ アラウンドして (先頭に戻って) いる場合は、もちろんロックされているセグメントごとに WaveReadFile を 1 回呼び出すべきである。


ウェーブ ファイルへの書き込み

[Visual Basic]

DirectSoundBuffer.SaveToFile を使うと、短いサウンドをセカンダリ バッファからウェーブ ファイルに保存できる。このメソッドはバッファの内容全体をファイルにコピーする。

多くの場合、サウンドの保存はキャプチャ バッファから始める。次のコードは、キャプチャ バッファ dscb から、ファイルに保存できるセカンダリ バッファにデータを移動する方法を示す。

Dim ByteBuffer() As Integer
Dim dsc As DirectSoundCapture
Dim dscd As DSCBUFFERDESC
Dim dsd As DSBUFFERDESC
Dim capCURS As DSCURSORS
.
.
.
' dscd はキャプチャ バッファのフォーマットで初期化され、
' dsb が同じサイズのセカンダリ バッファを
' 表すと仮定する。

' キャプチャ バッファと同じフォーマットで
' セカンダリ バッファを作成する。

Set dsb = ds.CreateSoundBuffer(dsd, dscd.fxFormat)

' キャプチャ バッファの書き込みカーソルまでの内容を保持できる
' 大きさでプライベート バッファを作成する。

dscb.GetCurrentPosition capCURS
ReDim ByteBuffer(capCURS.lWrite + 1)

' キャプチャ バッファの内容をプライベート バッファに読み込む。

dscb.ReadBuffer 0, capCURS.lWrite * dscd.fxFormat.nBlockAlign, _
        ByteBuffer(0), DSCBLOCK_DEFAULT

' プライベート バッファをセカンダリ バッファに書き込む。

dsb.WriteBuffer 0, capCURS.lWrite, ByteBuffer(0), DSBLOCK_DEFAULT

キャプチャ バッファの長さを超えてしまうサウンドに対しては、開発者自身がウェーブ ファイルを作成し、そのファイルにデータをストリーミングしなければならない。キャプチャされたデータをウェーブ ファイルにストリーミングするのは、次のステップで行う。

  1. ファイルを作成し、ファイル ヘッダー、フォーマット チャンク、およびデータ チャンクのヘッダーを書き込む。フォーマット チャンクは、DirectSoundCaptureBuffer.GetFormat で取得できるキャプチャ バッファのフォーマットを記述しなければならない。ただし、フォーマットの要素は WAVEFORMATEX 型と同じ順番ではないことに注意すること。ヘッダーとチャンクの編成についての情報は、「ウェーブ ファイルの読み込み」を参照すること。
  2. キャプチャ バッファからプライベート バッファまで、またそのバッファからファイルまでのデータのストリーミングを行う。このとき、書き込まれたバイトの数を追跡する。詳細については、「キャプチャ バッファの使い方」を参照すること。
  3. キャプチャが停止し、すべてのデータが書き込まれたら、データ チャンクの長さとファイルの合計サイズを計算し、これらの値をデータ チャンク ヘッダーとファイル ヘッダーのそれぞれの適切な位置に書き込む。
[C++]

ウェーブ ファイルへの書き込みを準備するには、アプリケーションは最初に、Wavwrite.cpp 内の関数に渡される 4 つの変数を宣言しなければならない。

WAVEFORMATEX  wfx;            // ウェーブ フォーマット情報。
HMMIO         hmmio;          // ファイル ハンドル。
MMCKINFO      mmckinfoData;   // チャンク情報。
MMCKINFO      mmckinfoParent; // 親チャンク (ファイル) 情報。

キャプチャ バッファの情報を使って WAVEFORMATEX 構造体の初期化も行わなければならない。

次に WaveOpenFile 関数を呼び出し、希望のファイル名とグローバル変数のアドレスを渡す。この関数は指定されたファイルを作成し、何らかのヘッダー情報を書き込む。Wavwrite.cpp 内の他の関数と同様、WaveOpenFile は成功した場合に 0 を返す。

if (WaveOpenFile(pszFileName, &hmmio, &wfx,
        &mmckinfoData, &mmckinfoParent))
{
    // 失敗。
}

次に WaveStartDataWrite 関数を呼び出す。この関数は、データ チャンクを初期化する。

if (WaveStartDataWrite(&hmmio, &mmckinfoData, &mmioinfo))
{
     // 失敗。
}

これでファイルはデータを受け取る準備ができた。次の部分的なコードは、キャプチャ バッファからファイルへデータをコピーする方法を示す。

/* 次の変数に有効な値が割り当てられていることを
   想定する。
LPDIRECTSOUNDCAPTUREBUFFER lpdscb;    // キャプチャ バッファ。
DSCBUFFERDESC    dscbDesc;            // キャプチャ バッファの記述。
DWORD            dwReadCursor;        // バッファ内の内部カーソル。
DWORD            dwNumBytes;          // 利用可能なバイト数。
DWORD            dwTotalBytesWritten; // 現時点までにファイル内に書き込まれた合計バイト数。
*/

LPBYTE pbInput1, pbInput2; // バッファ内のデータへのポインタ。
DWORD  cbInput1, cbInput2; // ロックされた部分のバイト カウント。
UINT   BytesWritten;       // ファイルに書き込まれたバイト カウント。

if FAILED(hr = lpdscb->Lock(dwReadCursor, dwNumBytes,
                      (LPVOID *)&pbInput1, &cbInput1,
                      (LPVOID *)&pbInput2, &cbInput2, 0))
{
    // 失敗。
}
else
{
    if (WaveWriteFile(hmmio, cbInput1, pbInput1, &mmckinfoData,
                    &dwBytesWritten, &mmioinfo))
    {
        // 失敗。
    }
    else dwTotalBytesWritten += BytesWritten;
    if (pbInput2 != NULL)
    {
        if (WaveWriteFile(hmmio, cbInput2, pbInput2, &mmckinfoData,
                    &BytesWritten, &mmioinfo))
        {
            // 失敗。
        }
        else dwTotalBytesWritten += BytesWritten;

    }
    lpdscb->Unlock(pbInput1, cbInput1, pbInput2, cbInput2);

    // 内部カーソルをインクリメントし、ラップ アラウンド (先頭へ戻る) を補正する。
    dwReadCursor += dwNumBytes;
    while (dwReadCursor >= dscbDesc.dwBufferBytes)
                dwMyReadCursor -= dscbDesc.dwBufferBytes;

}

データのキャプチャリングが終わった後で、ファイルを閉じる。

WaveCloseWriteFile(&hmmio, &mmckinfoData,
        &mmckinfoParent, &mmioinfo,
        dwTotalBytesWritten / (wfx.wBitsPerSample / 8));

WaveCloseWriteFile 関数は、ファイル内のサンプルの合計数を計算し、その値をデータ チャンクのヘッダーに書き込む。


リソースからのウェーブ データの読み込み

[Visual Basic]

リソースとして格納されたサウンドは短いことが多いので、スタティック バッファで再生されることが望ましい。スタティック バッファを作成し、リソースからのデータをそのバッファに書き込むには、DirectSound.CreateSoundBufferFromResource メソッドを使う。例として、「スタティック バッファの書き込みと再生」を参照すること。

さらに長いサウンドはウェーブ ファイルに格納され、ストリーム バッファから再生される。詳細については、次のトピックを参照すること。

  • ストリーム バッファの使い方
  • ウェーブ ファイルの読み込み
[C++]

DirectSound API は、リソースからウェーブを読み込むメソッドを備えていない。しかし、Dsutil3d.c にはいくつかのヘルパー関数があり、DirectMusic サンプル ディレクトリ にある 3DMusic サンプル用のソース コードが付属している。

実行可能ファイルか DLL にウェーブ サウンドを保存するには、ウェーブ ファイルをリソースとしてインポートし、文字列の名前を割り当てる。Dsutil3d.c がこれらのリソースを "WAV" タイプであると期待する点に注意すること。Microsoft® Visual C++® を使う場合、インポートされたウェーブ ファイルは "WAVE" タイプのリソースに変換される。リソース ファイルを編集してこの名称を "WAV" に変更するか、Dsutil3d.c 内の c_szWAV の代入を変更しなければならない。その結果、FindResource 関数は "WAVE" リソースを検索できる。

DSLoadSoundBuffer 関数が適切なコントロール フラグだけをセットするよう、Dsutil3d.c を変更することもできる。

スタティック バッファを作成して、サウンドをこのバッファにロードするには、単純に IDirectSound インターフェイス ポインタとリソースの名前を DSLoadSoundBuffer 関数に渡す。成功した場合、この関数はバッファへのポインタを返す。次はサンプルの呼び出しであり、lpds は IDirectSound インターフェイスへのポインタである。

#include "dsutil.h"

LPDIRECTSOUNDBUFFER  lpdsbFootstep;

lpdsbFootstep = DSLoadSoundBuffer(lpds, "FOOTSTEP");
if (lpdsbFootstep == NULL)
{
    // 失敗。
}


DirectSound チュートリアル

ここでは、DirectSound の基本的な機能を C/C++ または Visual Basic アプリケーションに実装する方法についてステップ バイ ステップで説明するチュートリアルを提供する。各チュートリアルは、この SDK の \Samples\Multimedia\DSound\Tutorials ディレクトリで提供される一連のサンプル ファイルと対応し、コードの流れに沿って説明する。サンプル コードを参照しながらチュートリアルを読み進めていくことを勧める。

  • DirectSound C/C++ チュートリアル
  • DirectSound Visual Basic チュートリアル


DirectSound C/C++ チュートリアル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

ここでは、次のチュートリアルを使用して、DirectSound の基本的な機能を実装する方法をステップ バイ ステップで説明する。

  • チュートリアル 1 : サウンドの再生

    最初のチュートリアルは、DirectSound システムの設定、セカンダリ バッファの作成、ウェーブ ファイルからのデータの再生を行う方法を示す。

  • チュートリアル 2 : サウンドのキャプチャ

    2 番目のチュートリアルは、DirectSoundCapture オブジェクトとキャプチャ バッファの作成、およびデータをウェーブ ファイルに書き込む方法を示す。


チュートリアル 1 : サウンドの再生

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルは、任意のサイズのウェーブ ファイルを再生する、単純な DirectSound アプリケーションを作成する方法を示す。

ウェーブ ファイルを開き、読み込み、閉じる関数は、DirectX SDK 内の DSShow3D ツール アプリケーションに付属のモジュールである Wavread.cpp ファイル内に記述されている。このチュートリアルで示す手法を実装するには、Wavread.cpp と Wavread.h をプロジェクトに追加し、Winmm.lib にリンクしなければならない。ほかに、同じサンプル ディレクトリの Debug.c と Debug.h を追加するか、標準的な assert 関数を呼び出すよう、Wavread.cpp ファイル内の ASSERT マクロの呼び出しを変更しなければならない。

このチュートリアル内のメソッド呼び出しは、C と C++ のどちらでも有効な、Dsound.h 内のマクロを通して行っている。

このチュートリアルは、以下のステップで構成されている。

  • ステップ 1 : DirectSound の設定
  • ステップ 2 : ウェーブ ファイルを開く
  • ステップ 3 : セカンダリ サウンド バッファの作成
  • ステップ 4 : 再生の通知の設定
  • ステップ 5 : 再生の通知の処理
  • ステップ 6 : ウェーブ ファイルからのデータのストリーミング
  • ステップ 7 : DirectSound のシャット ダウン


ステップ 1 : DirectSound の設定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、以下の定義とグローバル変数を必要とする。

#define NUMEVENTS 2

LPDIRECTSOUND               lpds;
DSBUFFERDESC                dsbdesc;
LPDIRECTSOUNDBUFFER         lpdsb;
LPDIRECTSOUNDBUFFER         lpdsbPrimary;
LPDIRECTSOUNDNOTIFY         lpdsNotify;
WAVEFORMATEX                *pwfx;
HMMIO                       hmmio;
MMCKINFO                    mmckinfoData, mmckinfoParent;
DSBPOSITIONNOTIFY           rgdsbpn[NUMEVENTS];
HANDLE                      rghEvent[NUMEVENTS];

最初のステップは、DirectSound オブジェクトを作成し、協調レベルを確立し、プライマリ バッファのフォーマットを設定することである。これらはいずれも、次のコードで示す InitDSound 関数内で行われる。

この関数はパラメータとしてメイン ウィンドウ ハンドルとサウンド デバイスの GUID へのポインタの 2 つを取る。ほとんどの場合、2 番目のパラメータに NULL を渡し、デフォルトのデバイスを使うよう指示するが、デバイス列挙により GUID の取得もできる。

BOOL InitDSound(HWND hwnd, GUID *pguid)
{
   // DirectSound を作成する。

    if FAILED(DirectSoundCreate(pguid, &lpds, NULL))
        return FALSE;

    // 協調レベルを設定する。

    if FAILED(IDirectSound_SetCooperativeLevel(
            lpds, hwnd, DSSCL_PRIORITY))
        return FALSE;

ここではプライマリ バッファのフォーマットを設定できるよう、プライマリ協調レベルを設定した。デフォルトのフォーマットに変更を加えない場合、入力のフォーマットにかかわりなく、出力は 8 ビット、22 kHz フォーマットになる。プライマリ バッファをこれより上のフォーマットに設定しても、問題はない。セカンダリ バッファがこれより下のフォーマットだったとしても、DirectSound がサンプルの変換を自動的に行うからである。IDirectSoundBuffer::SetFormat の呼び出しが失敗した場合も、問題はない点に注意すること。ハードウェアはこの上位フォーマットをサポートしないからである。DirectSound は単純に、利用できる中で最も近いフォーマットに設定する。

プライマリ バッファのフォーマットを設定するには、最初にグローバルな DSBUFFERDESC 構造体でそのフォーマットを記述し、次にその記述を IDirectSound::CreateSoundBuffer メソッドに渡す。

    // プライマリ バッファを取得する。

    ZeroMemory(&dsbdesc, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags = DSBCAPS_PRIMARYBUFFER;
    if FAILED(lpds->CreateSoundBuffer(&dsbdesc, &lpdsbPrimary, NULL))
        return FALSE;

プライマリ バッファ オブジェクトを取得した後で、希望のウェーブ フォーマットを記述し、その記述を IDirectSoundBuffer::SetFormat メソッドに渡す。

    // プライマリ バッファのフォーマットを設定する。

    WAVEFORMATEX wfx;
    memset(&wfx, 0, sizeof(WAVEFORMATEX));
    wfx.wFormatTag = WAVE_FORMAT_PCM;
    wfx.nChannels = 2;
    wfx.nSamplesPerSec = 44100;
    wfx.wBitsPerSample = 16;
    wfx.nBlockAlign = wfx.wBitsPerSample / 8 * wfx.nChannels;
    wfx.nAvgBytesPerSec = wfx.nSamplesPerSec * wfx.nBlockAlign;

    hr = lpdsbPrimary->SetFormat(&wfx);

    return TRUE;
}  // InitDSound()

次項 : ステップ 2 : ウェーブ ファイルを開く


ステップ 2 : ウェーブ ファイルを開く

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

このサンプル プログラムは汎用のウェーブ ファイル リーダーであり、サウンド データが特定のフォーマットであることを期待していない。この場合は、データのフォーマットが把握できるまで、セカンダリ サウンド バッファの作成を待たなければならない。

ファイルを開き、セカンダリ バッファを作成するステップは、SetupStreamBuffer 関数内にまとめられている。この関数は最初に、直前にサウンドが演奏されていた状態をクリーンアップするために必要なすべての作業を行う。

BOOL SetupStreamBuffer(LPSTR lpzFileName)
{
    // 開いているすべてのファイルを閉じ、インターフェイスを解放する。

    Close();  // Wavread.cpp の関数。

    if (lpdsNotify != NULL)
    {
        lpdsNotify->Release();
        lpdsNotify = NULL;
    }

    if (lpdsb != NULL)
    {
        lpdsb->Release();
        lpdsb = NULL;
    }

この関数は次にウェーブ ファイルを開き、そのフォーマットを取得し、ファイル ポインタをサウンド データの先頭へ進める。この作業は Wavread.cpp 内の 2 つの関数を使って行う。

    if (WaveOpenFile(lpzFileName, &hmmio, &pwfx,
            &mmckinfoParent) != 0)
        return FALSE;
    if (WaveStartDataRead(&hmmio, &mmckinfoData,
            &mmckinfoParent) != 0)
        return FALSE;

WaveOpenFile 関数は、このチュートリアルの先頭で宣言した 3 つのグローバル関数、つまりファイル ハンドル、WAVEFORMATEX 構造体へのポインタ、親チャンク (ファイル全体に関する情報) の MMCKINFO 構造体を初期化する。

次にファイル ハンドルとチャンク情報は WaveStartDataRead 関数に渡され、この関数は mmckinfoData 内のデータ チャンクに関する情報を返す。全データ バイトを保持するのにちょうどの大きさのスタティック バッファを作成したい場合は、この構造体が重要になる。しかしこのチュートリアルではストリーム バッファを作成するので、データ チャンクのサイズを把握する必要はない。

次項 : ステップ 3 : セカンダリ サウンド バッファの作成


ステップ 3 : セカンダリ サウンド バッファの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

ここでは引き続き SetupStreamBuffer 関数の内部を調べる。今度はウェーブ ファイルと同じフォーマットでセカンダリ サウンド バッファを作成する。このプロセスは、プライマリ バッファを作成したステップ 1 に似ている。最初に、グローバルな DSBUFFERDESC 構造体でこのバッファについて記述し、次にその記述を IDirectSound::CreateSoundBuffer メソッドに渡す。

    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags =
            DSBCAPS_GETCURRENTPOSITION2   // これを行うのは常に良い考えである。
            | DSBCAPS_GLOBALFOCUS         // バックグラウンド再生を可能にする。
            | DSBCAPS_CTRLPOSITIONNOTIFY; // 通知に必要である。

    // バッファのサイズは任意であるが、再生位置の十分
    // 先でデータを書き込めるように、少なくとも 2 秒の長さに
    // すべきである。

    dsbdesc.dwBufferBytes = pwfx->nAvgBytesPerSec * 2;
    dsbdesc.lpwfxFormat = pwfx;

    if FAILED(IDirectSound_CreateSoundBuffer(
            lpds, &dsbdesc, &lpdsb, NULL))
    {
        WaveCloseReadFile(&hmmio, &pwfx);
        return FALSE;
    }

次項 : ステップ 4 : 再生の通知の設定


ステップ 4 : 再生の通知の設定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

ここまででストリーム バッファの作成に成功したので、次はカレント プレイ ポジションがバッファ内の特定の位置に達したときに通知を受け、他のデータをストリームする時期を把握できるようにする。この例では、これらの位置をバッファの先頭と中間に設定する。

最初に、必要な数のイベントを作成し、それらのハンドルを rghEvent 配列に保存する。

    for (int i = 0; i < NUMEVENTS; i++)
    {
        rghEvent[i] = CreateEvent(NULL, FALSE, FALSE, NULL);
        if (NULL == rghEvent[i]) return FALSE;
    }

次に、DSBPOSITIONNOTIFY 構造体の配列を作成する。各構造体は、バッファ内の位置をイベント ハンドルに関連付ける。

    rgdsbpn[0].dwOffset = 0;
    rgdsbpn[0].hEventNotify = rghEvent[0];
    rgdsbpn[1].dwOffset = (dsbdesc.dwBufferBytes/2);
    rgdsbpn[1].hEventNotify = rghEvent[1];

さらにセカンダリ バッファから IDirectSoundNotify インターフェイスを取得し、DSBPOSITIONNOTIFY 配列を SetNotificationPositions メソッドに渡す。

    if FAILED(IDirectSoundBuffer_QueryInterface(lpdsb,
            IID_IDirectSoundNotify, (VOID **)&lpdsNotify))
        return FALSE;

    if FAILED(IDirectSoundNotify_SetNotificationPositions(
             lpdsNotify, NUMEVENTS, rgdsbpn))
    {
        IDirectSoundNotify_Release(lpdsNotify);
        return FALSE;
    }

これで、ストリーム バッファの設定が完了する。既にウェーブ ファイルを開き、データのストリーミングを開始する準備ができているので、ここでバッファの設定を順次実施できる。サウンド全体の再生が終わるまで動作を続けたいので、DSBPLAY_LOOPING フラグをセットする。

    IDirectSoundBuffer_Play(lpdsb, 0, 0, DSBPLAY_LOOPING);

    return TRUE;
} // SetupStreamBuffer() の終わり。

次項 : ステップ 5 : 再生の通知の処理


ステップ 5 : 再生の通知の処理

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

通知は、WinMain 関数のメッセージ ループ内で、シグナル送信されたイベントとして受信される。次の部分的なコードは、ループでどのようにしてシグナル送信されたイベントと標準的なメッセージを取り込むかを示す。

BOOL Done = FALSE;
while (!Done)
{
    DWORD dwEvt = MsgWaitForMultipleObjects(
            NUMEVENTS,      // 考えられるイベント数。
            rghEvent,       // ハンドルの位置。
            FALSE,          // すべてを待つか。
            INFINITE,       // 待機時間の長さ。
            QS_ALLINPUT);   // あらゆるメッセージはイベントである。

    // WAIT_OBJECT_0 == 0 以外では最初のイベントに割り当てられた
    // 任意のインデックス値として適切に扱われるので、dwEvt から
    // この値を引いて、0 から始まるイベントのインデックスを取得する。

    dwEvt -= WAIT_OBJECT_0;

    // バッファがイベントを設定していた場合、このプロセスへの
    // 入力が発生する。

    if (dwEvt < NUMEVENTS)
    {
        StreamToBuffer(dwEvt); // データを出力ストリームにコピーする。
    }

    // これが最後のイベントである場合、そのイベントはメッセージである。

    else if (dwEvt == NUMEVENTS)
    {
        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))
        {
            if (msg.message == WM_QUIT)
            {
                Done = TRUE;
            }
            else
            {
                TranslateMessage(&msg);
                DispatchMessage(&msg);
            }
        }
    }  // メッセージ処理の終了。
} // while (!Done)

次項 : ステップ 6 : ウェーブ ファイルからのデータのストリーミング


ステップ 6 : ウェーブ ファイルからのデータのストリーミング

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

前の 2 つのステップで通知の設定と処理を行ったのは、バッファ内のデータの半分が再生されたときにアラートを送ることを目的としている。カレント プレイ ポジションがバッファの先頭または中間を過ぎたらすぐに、再生を終えたばかりのバッファ セグメントにデータを書き込む。(バッファが開始された直後に通知を受け取り、バッファの後半に書き込みを行う。) このバッファは 2 秒分のデータを保持するので、カレント プレイ ポジションよりほぼ 1 秒先にデータを書き込むことになるが、これは再生位置が新しいデータに達する前に処理を完了するのに十分な時間である。

WinMain 関数では、イベントのシグナルが送信されたときに、このイベントのインデックスを StreamToBuffer 関数に渡す。このインデックスは、DSBPOSITIONNOTIFY 配列内で通知が占める位置のインデックスに対応する。

ここに、StreamToBuffer 関数の先頭部分を示す。

BOOL StreamToBuffer(DWORD dwPos)
{
    LONG            lNumToWrite;
    DWORD           dwStartOfs;
    VOID            *lpvPtr1, *lpvPtr2;
    DWORD           dwBytes1, dwBytes2;
    UINT            cbBytesRead;
    static DWORD    dwStopNextTime = 0xFFFF;

    if (dwStopNextTime == dwPos)   // すべてのデータが再生された。
    {
        lpdsb->Stop();
        dwStopNextTime = 0xFFFF;
        return TRUE;
    }

    if (dwStopNextTime != 0xFFFF)  // ストリームすべきものはないが、
                                 // データの最後まで演奏を続ける。
        return TRUE;

dwStopNextTime 変数は、ファイルの最後に達したことを示すフラグである。関数の残りの部分でこの変数をセットする。この値が 0 ではない場合、ストリームすべきデータはもう存在しない。dwStopNextTime の値が処理中の通知のインデックスに等しい場合、ファイルの終わりに達したときに相当する場所へ、カレント プレイ ポジションが戻ったこと、つまりバッファにコピーしたデータの最後のセグメントが既に再生されたことがわかる。この場合はバッファを停止すべきであり、古いデータの再生を続けない。

StreamToBuffer 関数の続く部分では、バッファ内で、新しいデータのコピーを開始する場所のオフセットを決定する。このチュートリアルのバッファには通知位置が 2 つしかないが、このコードは任意の通知数で動作するよう設計されている。dwPos が、カレント プレイ ポジションによって渡されたばかりの通知位置のインデックスである点に注意すること。直前の通知位置から始まるバッファ セグメントに書き込みを行うことになる。

    if (dwPos == 0)
        dwStartOfs = rgdsbpn[NUMEVENTS - 1].dwOffset;
    else
        dwStartOfs = rgdsbpn[dwPos-1].dwOffset;

ここで、バッファ セグメントのサイズを決定する。

    lNumToWrite = (LONG) rgdsbpn[dwPos].dwOffset - dwStartOfs;
    if (lNumToWrite < 0) lNumToWrite += dsbdesc.dwBufferBytes;

ここまでで、データ書き込みを行うためにバッファをロックするのに必要なすべての情報を入手した。

    IDirectSoundBuffer_Lock(lpdsb,
                     dwStartOfs,       // ロック開始位置のオフセット。
                     lNumToWrite,      // ロックされるバイト数。
                     &lpvPtr1,         // ロック開始アドレス。
                     &dwBytes1,        // ロックされるバイト カウント。
                     &lpvPtr2,         // ラップ アラウンド アドレス。
                     &dwBytes2,        // ラップ アラウンド バイト カウント。
                     0);               // フラグ。

この例では、ロックは決してラップ アラウンドしない (ロックされた部分がバッファの先頭へ戻り、バッファの最後と先頭の 2 つにまたがることはない) ので、ファイルから 1 回のデータ コピーを行うだけで十分である。Wavread.cpp 内の WaveReadFile 関数を呼び出して、データを取得する。

    WaveReadFile(hmmio,                // ファイル ハンドル。
                 dwBytes1,             // 取得されるバイト数。
                 (BYTE *) lpvPtr1,     // 書き込み先。
                 &mmckinfoData,        // ファイル チャンク情報。
                 &cbBytesRead);        // 実際に読み込むバイト。

今度は、ファイルの最後に達したかどうかを判断する。達した場合は、ファイルを閉じ、このセグメントの残りの部分に無音のデータを書き込み (セグメント全体を再生した後でバッファを停止する仕様となっているため)、dwStopNextTime フラグをセットする。

    if (cbBytesRead < dwBytes1)        // ファイルの最後に達した。
    {
        WaveCloseReadFile(&hmmio, &pwfx);
        FillMemory((PBYTE)lpvPtr1 + cbBytesRead,
                dwBytes1 - cbBytesRead,
                (dsbdesc.lpwfxFormat->wBitsPerSample==8) ? 128 : 0);
        dwStopNextTime = dwPos;
    }

最後にバッファをアンロックし、メッセージ ループへ戻る。

    IDirectSoundBuffer_Unlock(lpdsb,
            lpvPtr1, dwBytes1, lpvPtr2, dwBytes2);

    return TRUE;
} // StreamToBuffer() の終わり。

次項 : ステップ 7 : DirectSound のシャット ダウン


ステップ 7 : DirectSound のシャット ダウン

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションを終了する前に、開いているすべてのウェーブ ファイルを閉じ、DirectSoundNotify オブジェクトと DirectSound オブジェクトを解放する必要がある。DirectSoundBuffer オブジェクトから IDirectSoundNotify インターフェイスを問い合わせたため、DirectSound を解放する前に DirectSoundNotify オブジェクトを解放しなければならない。DirectSound を解放すると、既存のバッファも自動的に解放される。

次の関数は、必要なすべてのクリーンアップを実施する。

void DSExit(void)
{
    Close();
    if (lpdsNotify)
        lpdsNotify->Release();
    if (lpds)
        lpds->Release();
}


チュートリアル 2 : サウンドのキャプチャ

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルは、(通常はマイク入力から) サウンドをキャプチャして、ウェーブ ファイルに書き込む DirectSoundCapture を実装する方法を示す。

ウェーブ ファイルを作成し、書き込み、閉じる関数は、DirectX SDK 内の CaptureSound サンプル アプリケーションに付属のモジュール、Wavwrite.cpp ファイル内に記述されている。このチュートリアルで示す手法を実装するには、Wavwrite.cpp と Wavwrite.h をプロジェクトに追加し、Winmm.lib にリンクしなければならない。ほかに、同じサンプル ディレクトリの Debug.c と Debug.h を追加するか、標準的な assert 関数を呼び出すよう、Wavwrite.cpp ファイル内の ASSERT マクロの呼び出しを変更しなければならない。

このチュートリアル内のメソッド呼び出しは、C と C++ のどちらでも有効な、Dsound.h 内のマクロを通して行っている。

このチュートリアルは、以下のステップで構成されている。

  • ステップ 1 : DirectSoundCapture の設定
  • ステップ 2 : キャプチャ フォーマットの設定
  • ステップ 3 : キャプチャ バッファの作成
  • ステップ 4 : キャプチャの通知の設定
  • ステップ 5 : ウェーブ ファイルの作成
  • ステップ 6 : キャプチャの通知の処理
  • ステップ 7 : ウェーブ ファイルへのデータのストリーミング
  • ステップ 8 : キャプチャの停止
  • ステップ 9 : DirectSoundCapture のシャット ダウン


ステップ 1 : DirectSoundCapture の設定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、以下の定義とグローバル宣言を必要とする。

#define NUMCAPTUREEVENTS 2

LPDIRECTSOUNDCAPTURE        lpdsc;
LPDIRECTSOUNDCAPTUREBUFFER  lpdscb;
LPDIRECTSOUNDNOTIFY         lpdsNotify;
DSCBUFFERDESC               dscbDesc;
HANDLE                      rghEvent[NUMCAPTUREEVENTS];
DSBPOSITIONNOTIFY           rgdscbpn[NUMCAPTUREEVENTS];
WAVEFORMATEX                wfx =
                       {WAVE_FORMAT_PCM, 1, 22050, 44100, 2, 16, 0};
HMMIO                       hmmio;
MMCKINFO                    mmckinfoData, mmckinfoParent;
MMIOINFO                    mmioinfo;
DWORD                       dwTotalBytesWritten;

DirectSoundCapture を使うために、DirectSound オブジェクトを作成する必要はない。しかし、アプリケーションがサウンドの録音に加えて再生を行う場合は、最初に DirectSound を作成すべきである。

このチュートリアルでは、キャプチャ システムのすべての初期化は、パラメータをとらない関数 InitDSoundCapture の中で実施される。最初のステップは、DirectSoundCapture オブジェクトを作成することである。DirectSoundCaptureCreate 関数の最初のパラメータとして NULL を渡すことにより、このオブジェクトにデフォルトのキャプチャ デバイスを関連付ける。

BOOL InitDSoundCapture(void)
{

    if FAILED(DirectSoundCaptureCreate(NULL, &lpdsc, NULL))
        return FALSE;

次項 : ステップ 2 : キャプチャ フォーマットの設定


ステップ 2 : キャプチャ フォーマットの設定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

DirectSoundCapture を作成した後で、ユーザーのデバイスがサポートしているウェーブ フォーマットを選択すべきである。これを行う 1 つの方法は、最も上のフォーマットから始めて、作成メソッドが成功するまで、各フォーマットのキャプチャ バッファを順に作成することである。(さまざまなフォーマットを順に作成する方法の例は、サンプル プログラム Fdfilter 内の Fdaudio.cpp を参照すること。) このチュートリアルでは単純に、デバイスの能力をチェックして、デフォルトの 16 ビット フォーマット (WAVEFORMATEX 構造体の宣言により定義されている) がサポートされているかどうかをチェックする。サポートされていない場合、すべてのデバイスがサポートしている 8 ビット フォーマットを選択する。

次のコードは、InitDSoundCapture 関数から抜粋したものである。

    DSCCAPS dsccaps;

    dsccaps.dwSize = sizeof(DSCCAPS);
    if FAILED(IDirectSoundCapture_GetCaps(lpdsc, &dsccaps))
        return FALSE;

    if ((dsccaps.dwFormats & WAVE_FORMAT_2M16) == 0)
    {
        wfx.nSamplesPerSec = 11025;
        wfx.nAvgBytesPerSec = 11025;
        wfx.nBlockAlign = 1;
        wfx.wBitsPerSample = 8;
    }

アプリケーションで DirectSound の再生も利用している場合は、プライマリ バッファのフォーマットと互換性のあるキャプチャ フォーマットを選択しなければならない。詳細については、次の「ステップ 3 : キャプチャ バッファの作成」を参照すること。


ステップ 3 : キャプチャ バッファの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

ユーザーのデバイスにとって WAVEFORMATEX 構造体が有効であることを確認した後、先へ進んでそのフォーマットでキャプチャ バッファを作成できる。

    dscbDesc.dwSize = sizeof(DSCBUFFERDESC);
    dscbDesc.dwFlags = 0;
    // バッファは 1 秒分のオーディオを保持する。
    dscbDesc.dwBufferBytes = wfx.nAvgBytesPerSec;
    dscbDesc.dwReserved = 0;
    dscbDesc.lpwfxFormat = &wfx;

    if FAILED(IDirectSoundCapture_CreateCaptureBuffer(lpdsc,
            &dscbDesc, &lpdscb, NULL))
        return FALSE;

これでバッファ オブジェクトへのポインタを lpdscb に取得できた。

次項 : ステップ 4 : キャプチャの通知の設定


ステップ 4 : キャプチャの通知の設定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

InitDSoundCapture 関数の最後の初期化ステップとして、キャプチャ バッファ内の通知位置を設定し、アプリケーションが他のデータをファイルにストリームする時期を把握できるようにする。この例では、これらの位置をバッファの先頭と中間に設定する。

最初に、必要な数のイベントを作成し、それらのハンドルを rghEvent 配列に保存する。

    for (int i = 0; i < NUMCAPTUREEVENTS; i++)
    {
        rghEvent[i] = CreateEvent(NULL, FALSE, FALSE, NULL);
        if (NULL == rghEvent[i]) return FALSE;
    }

次に、DSBPOSITIONNOTIFY 構造体の配列を作成する。各構造体は、バッファ内の位置をイベント ハンドルに関連付ける。

    rgdscbpn[0].dwOffset = 0;
    rgdscbpn[0].hEventNotify = rghEvent[0];
    rgdscbpn[1].dwOffset = dscbDesc.dwBufferBytes/2;
    rgdscbpn[1].hEventNotify = rghEvent[1];

最後にキャプチャ バッファから IDirectSoundNotify インターフェイスを取得し、DSBPOSITIONNOTIFY 配列を SetNotificationPositions メソッドに渡す。

    if FAILED(IDirectSoundCaptureBuffer_QueryInterface(lpdscb,
            IID_IDirectSoundNotify, (VOID **)&lpdsNotify))
        return FALSE;

    if FAILED(IDirectSoundNotify_SetNotificationPositions(lpdsNotify,
            NUMCAPTUREEVENTS, rgdscbpn))
    {
        IDirectSoundNotify_Release(lpdsNotify);
        return FALSE;
    }

    return TRUE;
}  // InitDSoundCapture() の終わり。

キャプチャ バッファとセカンダリ (出力) バッファの両方に通知を設定する必要がある場合、イベント ハンドルを同じ rghEvent 配列に保存しなければならない。メッセージ ループ内で通知を受け取ったときに、インデックス番号によってそれら 2 種類のイベントを区別できる。

次項 : ステップ 5 : ウェーブ ファイルの作成


ステップ 5 : ウェーブ ファイルの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

この時点で、既に有効なファイル名を取得し、ウェーブ ファイルへのサウンド データの保存を開始する準備ができていることを想定する。このプロセスは、次の関数内で実施される。

BOOL StartWrite(TCHAR *pszFileName)
{
    if (WaveOpenFile(pszFileName, &hmmio, &wfx,
            &mmckinfoData, &mmckinfoParent))
      return FALSE;

    if (WaveStartDataWrite(&hmmio, &mmckinfoData, &mmioinfo))
    {
        WaveCloseWriteFile(&hmmio, &mmckinfoData,
                &mmckinfoParent, &mmioinfo,
                dwTotalBytesWritten / (wfx.wBitsPerSample / 8));
        DeleteFile(pszFileName);
        return FALSE;
    }
    if FAILED(IDirectSoundCaptureBuffer_Start(lpdscb,
            DSCBSTART_LOOPING))
    {
        WaveCloseWriteFile(&hmmio, &mmckinfoData,
                &mmckinfoParent, &mmioinfo, 0);
        DeleteFile(pszFileName);
        return FALSE;
    }

    dwTotalBytesWritten = 0;

    return TRUE;
}

この関数は最初に Wavwrite.cpp 内の WaveOpenFile 関数を呼び出し、RIFF ファイルの作成とウェーブ フォーマットに関連するヘッダーを書き込む。次に WaveStartDataWrite 関数を呼び出し、ファイル ポインタをデータ チャンクに進める。最後に、バッファのキャプチャを開始する。バッファの半分に相当する 1 秒が経過した時点で、アプリケーションはデータが利用可能であるとの通知を受けるので、その時点までにデータをファイルにコピーする準備をしておかなければならない。

dwTotalBytesWritten の初期化にも注意すること。キャプチャを終えた後で、データ チャンクのヘッダーはこの値を必要とする。

次項 : ステップ 6 : キャプチャの通知の処理


ステップ 6 : キャプチャの通知の処理

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

再生の通知と同様、メッセージ ループ内で、イベントとしてキャプチャの通知を受け取る。ここにサンプル ループを示す。

BOOL Done = FALSE;
while (!Done)
{
    DWORD dwEvt = MsgWaitForMultipleObjects(
            NUMCAPTUREEVENTS,  // 考えられるイベント数。
            rghEvent,          // ハンドルの位置。
            FALSE,             // すべてを待つか。
            INFINITE,          // 待機時間の長さ。
            QS_ALLINPUT);      // あらゆるメッセージはイベントである。

    dwEvt -= WAIT_OBJECT_0;

    // バッファがイベントを設定していた場合、このプロセスへの
    // 入力が発生する。

    if (dwEvt < NUMCAPTUREEVENTS)
    {
        StreamToFile();
    }

    // これが最後のイベントである場合、そのイベントはメッセージである。

    else if (dwEvt == NUMCAPTUREEVENTS)
    {
        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))
        {
            if (msg.message == WM_QUIT)
            {
                Done = TRUE;
            }
            else
            {
                TranslateMessage(&msg);
                DispatchMessage(&msg);
            }
        }
    }  // メッセージ処理の終了。
} // while (!Done)

前述のとおり、キャプチャ バッファとセカンダリ (出力) バッファの両方から通知を受け取った場合、dwEvt 内のインデックス番号を使ってこれら 2 種類のイベントを識別しなければならない。たとえば、イベント 0 と 1 は再生の通知、イベント 2 と 3 はキャプチャの通知ということが考えられる。

次項 : ステップ 7 : ウェーブ ファイルへのデータのストリーミング


ステップ 7 : ウェーブ ファイルへのデータのストリーミング

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

最初のチュートリアルでは、通知位置のオフセットをチェックすることにより、安全に書き込みが行えるバッファ セグメントを識別する方法を学んだ。この手法は、このチュートリアルのキャプチャ バッファにも同様に適用できるが、ここでは多少異なった作業を行う必要がある。

前のステップでは、通知イベントに応答して StreamToFile 関数を呼び出す方法を学んだ。最初のチュートリアルの StreamToBuffer 関数とは異なり、この関数はパラメータとしてイベント インデックスをとらない。

BOOL StreamToFile(void)
{
    DWORD               dwReadPos;
    DWORD               dwNumBytes;
    LPBYTE              pbInput1, pbInput2;
    DWORD               cbInput1, cbInput2;
    static DWORD        dwMyReadCursor = 0;
    UINT                dwBytesWritten;

dwMyReadCursor がスタティックとして宣言されている点に注意すること。これは、読み込みたい次のデータ バイトのオフセットである。言い換えると、直前に読み込んでこの関数を通して渡したバイトのすぐ後のバイトである。

この関数は最初に、現在の読み込み位置を検索する。この位置が、読み込んでも安全なデータの最初の位置を示している点に注意すること。これは通知位置に一致するとは限らない。イベントがシグナル送信された後、おそらく現在の読み込み位置は先へ進んでいるからである。

    IDirectSoundCaptureBuffer_GetCurrentPosition(lpdscb,
            NULL, &dwReadPos);

次にこの関数は、(ラップ アラウンドに対処した後) 現在の読み込み位置からアプリケーション内部の読み込みカーソルを引き、新しいデータが何バイト利用できるかを決定する。

    if (dwReadPos < dwMyReadCursor)
            dwReadPos += dscbDesc.dwBufferBytes;
    dwNumBytes = dwReadPos - dwMyReadCursor;

次にバッファをロックして、コピーを行う。利用可能なものとして識別したデータ セグメントは、バッファの先頭と中間にある通知位置と必ずしも一致しているわけではないので、バッファのロック位置はラップ アラウンドしている (ロックされた部分がバッファの先頭へ戻り、バッファの最後と先頭の 2 つにまたがる) 可能性がある。この場合、コピー作業を 2 回行う必要がある。

    if FAILED(IDirectSoundCaptureBuffer_Lock(lpdscb,
            dwMyReadCursor, dwNumBytes,
            (LPVOID *)&pbInput1, &cbInput1,
            (LPVOID *)&pbInput2, &cbInput2, 0))
        OutputDebugString("Capture lock failure");

    else
        {
        if (WaveWriteFile(hmmio, cbInput1, pbInput1, &mmckinfoData,
                        &dwBytesWritten, &mmioinfo))
          OutputDebugString("ファイルへのデータの書き込みに失敗しました。\n");
        dwTotalBytesWritten += dwBytesWritten;

        // ラップ アラウンド。
        if (pbInput2 != NULL)
        {
            if (WaveWriteFile(hmmio, cbInput2, pbInput2,
                    &mmckinfoData, &dwBytesWritten, &mmioinfo))
              OutputDebugString("ファイルへのデータの書き込みに失敗しました。\n");
            dwTotalBytesWritten += dwBytesWritten;
        }

        IDirectSoundCaptureBuffer_Unlock(lpdscb,
                pbInput1, cbInput1,
                pbInput2, cbInput2);
    }

WaveWriteFile 関数は、成功した場合は 0 を返し、実際にファイルにコピーしたバイト数を dwBytesWritten に書き込む。この値を累積合計に追加する。累積合計は、ファイルを閉じるときに必要になる。

最後に、内部の読み込みカーソルを更新して、ラップ アラウンドを補正し、メッセージ ループへ戻る。

    dwMyReadCursor += dwNumBytes;
    if (dwMyReadCursor >= dscbDesc.dwBufferBytes)
                dwMyReadCursor -= dscbDesc.dwBufferBytes;

    return TRUE;
} // StreamToFile() の終わり。

次項 : ステップ 8 : キャプチャの停止


ステップ 8 : キャプチャの停止

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

ここで録音を停止する。次の関数を呼び出す。

BOOL StopWrite()
{
    IDirectSoundCaptureBuffer_Stop(lpdscb);
    StreamToFile();
    WaveCloseWriteFile(&hmmio, &mmckinfoData,
            &mmckinfoParent, &mmioinfo,
            dwTotalBytesWritten / (wfx.wBitsPerSample / 8));
    return TRUE;
}

この関数はバッファのキャプチャを停止し、StreamToFile 関数をもう一度呼び出し、現在の読み込み位置までのすべてのデータを保存し、ファイルを閉じる。Wavwrite.cpp 内の WaveCloseWriteFile 関数は、サンプルの合計数を書き込むことにより、データ チャンクのヘッダーをも更新する。

次項 : ステップ 9 : DirectSoundCapture のシャット ダウン


ステップ 9 : DirectSoundCapture のシャット ダウン

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションを終了する前に、キャプチャ システムをシャット ダウンしなければならない。これは単純に、すべてのオブジェクトを解放することを意味する。キャプチャ バッファを解放する前に、IDirectSoundNotify インターフェイスを解放しなければならない。

void CleanupDSoundCapture(void)
{
    if (lpdsNotify)
        IDirectSoundNotify_Release(lpdsNotify);
    if (lpdscb)
        IDirectSoundCaptureBuffer_Release(lpdscb);
    if (lpdsc)
        IDirectSoundCapture_Release(lpdsc);
}


DirectSound Visual Basic チュートリアル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここでは、次のチュートリアルを使用して、DirectSound の基本的な機能を実装する方法を段階的に説明する。このチュートリアルは、DirectX SDK インストレーションの \samples\Multimedia\VBSamples\DSound\src\Tutorial1 と \samples\Multimedia\VBSamples\DSound\src\Tutorial2 の各フォルダにあるサンプルを基にしている。

  • チュートリアル 1 : サウンドのロードと再生
  • チュートリアル 2 : 3D サウンドのロードと再生


チュートリアル 1 : サウンドのロードと再生

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルは、DirectSound の最も基本的な機能の 1 つであるサウンドのロードと再生について説明する。これは、ウェーブ ファイルをバッファにロードし、バッファ データを再生することで行われる。コードは、DirectX SDK インストレーションの \samples\Multimedia\VBSamples\DSound\src\Tutorial1 フォルダのサンプル アプリケーションを基にしている。

このチュートリアルは以下のステップに分類される。

  • ステップ 1 : DirectSound オブジェクトの作成
  • ステップ 2 : ウェーブ ファイルのバッファへのロード
  • ステップ 3 : サウンドの再生


ステップ 1 : DirectSound オブジェクトの作成

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectSound アプリケーションの主なオブジェクトは、DirectSound クラスのインスタンスである。アプリケーションは、DirectSound オブジェクトのメソッドを使ってサウンド環境を設定し、オーディオ データを保持するバッファを作成する。

このオブジェクトは、すべての DirectX for Visual Basic アプリケーションの核であるグローバルな DirectX7 オブジェクトを作成した後に、DirectX7.DirectSoundCreate メソッドを呼び出すことで取得される。

以下のグローバル宣言は、DirectX7 オブジェクト、および DirectSound オブジェクトと 2 つのバッファに対する変数を作成する。

Dim m_dx As New DirectX7
Dim m_ds As DirectSound
Dim m_dsBuffer(2) As DirectSoundBuffer

スタートアップ コードでは、次のように DirectSound オブジェクトを作成する。

On Local Error Resume Next

Set m_ds = m_dx.DirectSoundCreate("")

If Err.Number <> 0 Then
    MsgBox "DirectSound を開始することができません。サウンド カードが適切に" & _
           "インストールされているかどうか確認してください。"
    End
End If

空の文字列を DirectSoundCreate メソッドに渡すことで、システムにデフォルトのサウンド デバイスを配置することを示す。

ここで、サウンド デバイスに協調レベルを設定しなければならない。チュートリアル 1 のサンプルでは、次のステートメントで設定している。

m_ds.SetCooperativeLevel Me.hWnd, DSSCL_PRIORITY

最初の引数は、アプリケーションへのウィンドウ ハンドルである。フォームの hWnd プロパティは、フォームが表示されるまで設定されないことに注意すること。通常、フォームはフォームの Load プロシージャが完全に実行された後に表示される。このサンプルでは、フォーム ウィンドウに対する Show がプロシージャの最初に呼び出されるため、hWnd が利用可能になる。

2 番目の引数は、多くのアプリケーションに最適な優先協調レベルを設定する。

次項 : チュートリアル 1 : ステップ 2 : ウェーブ ファイルのバッファへのロード

次項 : チュートリアル 2 : ステップ 2 : リスナーの取得


ステップ 2 : ウェーブ ファイルのバッファへのロード

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ チュートリアル」を参照すること。

[Visual Basic]

主な DirectSound オブジェクトを作成した後、次のステップではセカンダリ サウンド バッファを作成し、ウェーブ ファイルをそのバッファにロードする。

DSBUFFERDESC 型にバッファの特性を記述する。最初のメンバはバッファのサイズを設定する。ただし、ファイルからバッファを作成するため、このメンバを初期化する必要はない。DirectSound は、ファイルのデータに適したサイズでバッファを作成する。2 番目のメンバには、バッファに要求するさまざまな能力を記述する。次のコード例は、アプリケーションが周波数、パン、ボリュームを変更できるバッファを記述する。さらに DDSBCAPS_STATIC フラグで、サウンド カードのメモリが利用可能な場合にバッファをそこへ配置すべきであることを示す。サウンド カードのメモリは通常は利用不可である。

Dim bufferDesc As DSBUFFERDESC
Dim waveFormat As WAVEFORMATEX

bufferDesc.lFlags = DSBCAPS_CTRLFREQUENCY Or DSBCAPS_CTRLPAN _
                    Or DSBCAPS_CTRLVOLUME Or DSBCAPS_STATIC

作成メソッドに渡すべき他の変数は、WAVEFORMATEX 型である。DirectSound はファイルから必要なウェーブ フォーマット情報を再度取得するため、この型を初期化する必要はない。メソッドを呼び出した後、必要に応じてこの型をチェックし、設定されたフォーマットを確認できる。

バッファを作成するには、次のように DirectSound.CreateSoundBufferFromFile メソッドを呼び出す。

Set m_dsBuffer(i) = m_ds.CreateSoundBufferFromFile( _
                   sfile, bufferDesc, waveFormat)

次項 : ステップ 3 : サウンドの再生


ステップ 3 : サウンドの再生

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ チュートリアル」を参照すること。

[Visual Basic]

チュートリアル 1 のサンプルでは、ユーザーが [Play] ボタンをクリックすると、サウンドがサウンド バッファにロードされる。同時に、Volume と Pan の各スライダの状態が Scroll プロシージャの呼び出しでチェックされ、サウンド バッファのプロパティがスライダの状態に応じて調整される。

Private Sub scrlVol_Scroll(i As Integer)
    If m_dsBuffer(i) Is Nothing Then Exit Sub
    m_dsBuffer(i).SetVolume scrlVol(i).Value
End Sub

Private Sub scrlPan_Scroll(i As Integer)
    If m_dsBuffer(i) Is Nothing Then Exit Sub
    m_dsBuffer(i).SetPan scrlPan(i).Value
End Sub

これらのプロシージャとそれに対応する Change プロシージャは、ユーザーがボリュームとパンのスライダを調整するとき常に呼び出される。アプリケーションは、バッファの再生中にボリュームとパンを変更できる。

また、このサンプルは [Loop Play] チェックボックスの状態もチェックし、これがオンの場合、フラグを 1 (DSBPLAY_LOOPING) に設定する。

Dim flag As Long
flag = 0
If chLoop(i).Value <> 0 Then flag = 1

このフラグは、次のように DirectSoundBuffer.Play メソッドに渡される。

m_dsBuffer(i).Play flag

サウンドがループする場合、ユーザーは [Stop] ボタンをクリックするか [Loop Play] チェックボックスをオフにしてサウンドを停止できる。これに応答して、アプリケーションはバッファを停止し、カレント プレイ ポジションを先頭に設定し直す。

m_dsBuffer(i).Stop
m_dsBuffer(i).SetCurrentPosition 0

ユーザーが [Pause] ボタンをクリックすると、バッファは停止するが、カレント プレイ ポジションはその場に残る。このため、DirectSoundBuffer.Play が次に呼び出されたとき、サウンドは同じ場所に戻る。


チュートリアル 2 : 3D サウンドのロードと再生

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルは、3 次元におけるサウンドの再生方法を示す。これは、DirectX SDK インストレーションの \samples\Multimedia\VBSamples\DSound\src\Tutorial2 フォルダのサンプル アプリケーションを基にしている。ユーザー インターフェイスは、「チュートリアル 1 : サウンドのロードと再生」で使ったサンプルと似ているが、リスナーの位置と 2 つのサウンドを表示するのに使うピクチャ ボックス コントロールが付いている。

このチュートリアルは、以下のステップに分類される。ステップ 1 は、チュートリアル 1 のステップ 1 と同じである。

  • ステップ 1 : DirectSound オブジェクトの作成
  • ステップ 2 : リスナーの取得
  • ステップ 3 : ウェーブ ファイルの 3D バッファへのロード
  • ステップ 4 : 3D サウンドの再生と変更


ステップ 2 : リスナーの取得

ステップ 1 で採用したグローバル変数に加え、チュートリアル 2 では次のグローバル変数を使う。

Dim m_ds3dBuffer(2) As DirectSound3DBuffer
Dim m_dsPrimaryBuffer As DirectSoundBuffer
Dim m_dsListener As DirectSound3DListener

DirectSound オブジェクトを作成した後、3D サウンド環境を設定する次のステップでは DirectSound3DListener オブジェクトを取得する。このオブジェクトは、この環境の仮想リスナーの位置と方向を含むグローバル サウンド パラメータの制御に使われる。

リスナーはプライマリ バッファから取得されるので、適切な DirectSoundBuffer オブジェクトを作成しなければならない。このバッファには 2 つのフラグを設定して、バッファが 3D 能力のあるプライマリ バッファとして作成されるようにする。WAVEFORMATEX 型は、プライマリ バッファのデフォルトのウェーブ フォーマットを取得する。この型の初期化は必要ない。

Dim primDesc As DSBUFFERDESC
Dim format As WAVEFORMATEX

primDesc.lFlags = DSBCAPS_CTRL3D Or DSBCAPS_PRIMARYBUFFER
Set m_dsPrimaryBuffer = m_ds.CreateSoundBuffer(primDesc, format)

次に DirectSoundBuffer.GetDirectSound3DListener を呼び出し、プライマリ バッファからリスナーを取得する。

Set m_dsListener = m_dsPrimaryBuffer.GetDirectSound3DListener()

チュートリアル 2 のサンプルでは DirectSound3DListener を使わない。ただしこのオブジェクトは、サウンド バッファに対する相対的なリスナーの位置と方向の変更、ロールオフ係数のようなグローバル サウンド パラメータの変更、およびすべての 3D バッファの遅延設定のコミットに使われる。

次項 : ステップ 3 : ウェーブ ファイルの 3D バッファへのロード


ステップ 3 : ウェーブ ファイルの 3D バッファへのロード

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ チュートリアル」を参照すること。

[Visual Basic]

次のステップでは、ウェーブ ファイルをサウンド バッファにロードする。セカンダリ バッファについては、チュートリアル 1 で説明している。「ステップ 2 : ウェーブ ファイルのバッファへのロード」を参照すること。今度は、DSBCAPS_CTRLPAN でなく DSBCAPS_CTRL3D を必要とする。3D バッファでは、2D エフェクトのパンを使わない。

チュートリアル 2 の SDK サンプルから採用された次のコードでは、ファイルが有効なウェーブ ファイルの名前になる。

Dim bufferDesc1 As DSBUFFERDESC
Dim waveFormat1 As WAVEFORMATEX

bufferDesc1.lFlags = DSBCAPS_CTRL3D Or DSBCAPS_CTRLFREQUENCY _
    Or DSBCAPS_CTRLVOLUME Or DSBCAPS_STATIC
Set m_dsBuffer(i) = m_ds.CreateSoundBufferFromFile( _
    file, bufferDesc1, waveFormat1)

ここで DirectSound3DBuffer オブジェクトを作成し、サウンド バッファの 3D プロパティをカプセル化する。

Set m_ds3dBuffer(i) = m_dsBuffer(i).GetDirectSound3DBuffer

次項 : ステップ 4 : 3D サウンドの再生と変更


ステップ 4 : 3D サウンドの再生と変更

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ チュートリアル」を参照すること。

[Visual Basic]

ここまでで 3D サウンド バッファが 2 つのオブジェクトで表された。バッファの標準機能を備えた DirectSoundBuffer オブジェクトと、バッファの 3D プロパティを制御する DirectSound3DBuffer オブジェクトである。

このバッファを再生するには、2D バッファの場合と同じようにする。チュートリアル 1 の「ステップ 3 : サウンドの再生」を参照すること。

バッファの 3D プロパティの変更は、再生中か否かにかかわらずいつでも行える。このサンプル アプリケーションでは、バッファを作成するときや、ユーザーが [Direction] スクロールバーやバッファを示す三角形を動かすのに応答して、プロパティが設定される。

バッファに対するサウンド コーンの方向は、[Direction] スクロールバーの Change プロシージャで設定される。

Private Sub scrlAngle_Change(i As Integer)

  Dim x As Single
  Dim z As Single

  '方向ベクトルを計算する。
  '単位の度をラジアンに変換し、cos または sin を取得する。

  x = 5 * Cos(3.141 * scrlAngle(0).Value / 180)
  z = 5 * Sin(3.141 * scrlAngle(0).Value / 180)

  'グラフィックスを更新する。

  DrawPositions

  If m_dsBuffer(i) Is Nothing Then Exit Sub
  m_ds3dBuffer(i).SetConeOrientation x, 0, z, DS3D_IMMEDIATE

End Sub

このサンプルでは、ユーザーがマウスの左ボタンや右ボタンをクリックしたり、サウンドを表す三角形を移動することで、リスナーに対する相対的な 2 つのサウンドの位置を移動できる。サウンドの位置は、DirectSound3DBuffer.SetPosition メソッドで変更する。サンプルの UpdatePosition プロシージャを参照すること。


DirectSound リファレンス

ここでは、C/C++ および Visual Basic の DirectSound が提供するアプリケーション プログラミング インターフェイス (API) 要素のリファレンス情報を記述する。リファレンス情報は以下の言語別に構成される。

  • DirectSound C/C++ リファレンス
  • DirectSound Visual Basic リファレンス


DirectSound C/C++ リファレンス

ここでは、DirectSound が提供する API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • インターフェイス
  • 関数
  • コールバック関数
  • 構造体
  • 戻り値


インターフェイス

ここでは、以下の DirectSound インターフェイスのメソッドに関するリファレンスを提供する。

  • IDirectSound
  • IDirectSound3DBuffer
  • IDirectSound3DListener
  • IDirectSoundBuffer
  • IDirectSoundCapture
  • IDirectSoundCaptureBuffer
  • IDirectSoundNotify
  • IKsPropertySet


IDirectSound インターフェイス

アプリケーションは、IDirectSound インターフェイスのメソッドを使って、DirectSound オブジェクトの作成と環境設定を行う。ここでは、IDirectSound インターフェイスのメソッドのリファレンスを提供する。

このインターフェイスは、DirectSoundCreate 関数を使って取得する。

IDirectSound インターフェイスのメソッドは、以下のグループにまとめることができる。

初期化 | Initialize
 | SetCooperativeLevel
バッファ作成 | CreateSoundBuffer
 | DuplicateSoundBuffer
デバイスの能力 | GetCaps
メモリ管理 | Compact
スピーカの構成 | GetSpeakerConfig
 | SetSpeakerConfig

すべての COM インターフェイスと同様、IDirectSound インターフェイスは IUuknown インターフェイス メソッドを継承する。IUnknown インターフェイスは以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND 型は、IDirectSound インターフェイスへのポインタとして定義されている。

typedef struct IDirectSound    *LPDIRECTSOUND;

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound::Compact

IDirectSound::Compact メソッドは、オンボード サウンド メモリに未使用部分が存在する場合、これらを移動して連続ブロックを形成し、空きメモリ領域を最大にする。

HRESULT Compact();

パラメータ

なし。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
DSERR_UNINITIALIZED

注意

アプリケーションの DirectSound オブジェクトは、少なくとも DSSCL_PRIORITY の協調レベルを備えていなければならない。IDirectSound::SetCooperativeLevel を参照すること。

進行中の操作がほかに 1 つでも存在すると、このメソッドは失敗する。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound::CreateSoundBuffer

IDirectSound::CreateSoundBuffer メソッドは、サンプリング オーディオのシーケンスを保持するための DirectSoundBuffer オブジェクトを作成する。

HRESULT CreateSoundBuffer(
  LPCDSBUFFERDESC lpcDSBufferDesc,
  LPLPDIRECTSOUNDBUFFER lplpDirectSoundBuffer,
  IUnknown FAR * pUnkOuter
);

パラメータ

lpcDSBufferDesc
作成されるサウンド バッファの記述を保持する DSBUFFERDESC 構造体へのポインタ。
lplpDirectSoundBuffer
新規の DirectSoundBuffer オブジェクトへのポインタ。バッファを作成できない場合は NULL。
pUnkOuter
全体の未定義のコントロール。この値は NULL でなければならない。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_ALLOCATED
DSERR_CONTROLUNAVAIL
DSERR_BADFORMAT
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

DSBCAPS_CTRLDEFAULT は、これが表す個別のフラグを使うようにと削除された。DSBCAPS_CTRLDEFAULT は、DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY として定義された。必要なフラグだけを指定することにより、不必要なリソースを減らすことができる。

サウンド バッファを再生する前に、アプリケーションは IDirectSound::SetCooperativeLevel メソッドを使って DirectSound オブジェクトの協調レベルを指定しなければならない。

lpDSBufferDesc パラメータは、フォーマット、サイズ、能力など、希望のバッファのタイプ情報を含む構造体を指す。アプリケーションは必要な能力を指定しなければならない。さもないと、それらの能力は利用できない。たとえば、DirectSound オブジェクトを作成するときに DSBCAPS_CTRLFREQUENCY フラグを指定しておかないと、IDirectSoundBuffer::SetFrequency の呼び出しはすべて失敗する。

DSBCAPS_STATIC フラグを指定することもできる。その場合、DirectSound はオンボード メモリ (使用可能な場合) にバッファを格納し、ハードウェア ミキシングを利用できる。ハードウェアまたはソフトウェアのミキシングをバッファに使わせるには、それぞれ DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE フラグを使う。さらに、DirectSound は DSBCAPS_LOCDEFER フラグを使用することで、再生中にハードウェアやソフトウェアのリソースを割り当てる。

バッファがハードウェアかソフトウェアに作成されたことを把握するには、IDirectSoundBuffer:GetCaps メソッドを呼び出し、返された DSBCAPS 構造体の dwFlags メンバの DBSCAPS_LOCHARDWARE フラグ、または DSBCAPS_LOCSOFTWARE フラグをチェックする。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 :Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

DSBUFFERDESC、IDirectSound::DuplicateSoundBuffer、IDirectSound::SetCooperativeLevel、IDirectSoundBuffer, IDirectSoundBuffer::GetFormat、IDirectSoundBuffer::GetVolume、IDirectSoundBuffer::Lock、IDirectSoundBuffer::Play、IDirectSoundBuffer::SetFormat、IDirectSoundBuffer::SetFrequency


IDirectSound::DuplicateSoundBuffer

IDirectSound::DuplicateSoundBuffer メソッドは、新しい DirectSoundBuffer オブジェクトを作成する。このオブジェクトは、オリジナルのオブジェクトと同じバッファ メモリを使う。

HRESULT DuplicateSoundBuffer(
  LPDIRECTSOUNDBUFFER lpDsbOriginal,
  LPLPDIRECTSOUNDBUFFER lplpDsbDuplicate
);

パラメータ

lpDsbOriginal
複製される DirectSoundBuffer オブジェクトへのポインタ。
lplpDsbDuplicate
新しい DirectSoundBuffer オブジェクトへのポインタ。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_ALLOCATED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

注意

新しいオブジェクトはオリジナルのオブジェクトと同じ方法で使用できる。

複製直後のバッファは、オリジナル バッファと同じパラメータを持つ。ただし、アプリケーションは各バッファのパラメータを個別に変更でき、各バッファは違いに影響を及ぼすことなく再生と停止を行える。

どちらかのオブジェクトがバッファ内のデータを変更すると、バッファ メモリが共有されているため、その変更はもう一方のオブジェクトにも反映される。

後に残った参照側オブジェクトが解放されると、バッファ メモリは解放される。

アプリケーションは、サウンド バッファの複製作業が常に成功するとは想定できない。特に、DirectSound はハードウェア バッファのソフトウェア複製を作成できない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound::CreateSoundBuffer


IDirectSound::GetCaps

IDirectSound::GetCaps メソッドは、DirectSound オブジェクトとして表されているハードウェア デバイスの能力を取得する。

HRESULT GetCaps(
  LPDSCAPS lpDSCaps
);

パラメータ

lpDSCaps
サウンド デバイスの能力を保持している DSCAPS 構造体へのポインタ。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

DSCAPS 構造体に保持されている情報は、ハードウェア ミキシング チャンネルの数、オンボード サウンド メモリの容量など、サウンド デバイスの最大能力と、現在使用可能な能力を記述する。これらの情報を使って性能を調整し、リソースの割り当てを最適化できる。

リソースの共有が前提となっているため、ある分野で最大の能力を利用すると、他の分野がその影響を受けることがある。たとえば、最大数のストリーム サウンド バッファをハードウェア ミキシングすると、ハードウェア スタティック サウンド バッファは 1 つも利用できなくなる。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

DirectSoundCreate


IDirectSound::GetSpeakerConfig

IDirectSound::GetSpeakerConfig メソッドは、DirectSound オブジェクトに割り当てられたスピーカの構成を取得する。

HRESULT GetSpeakerConfig(
  LPDWORD lpdwSpeakerConfig
);

パラメータ

lpdwSpeakerConfig
この DirectSound オブジェクト用のスピーカの構成へのポインタ。スピーカの構成は以下の値のいずれかで指定される。
DSSPEAKER_5POINT1
オーディオはサブウーファ付きのサラウンド スピーカのスピーカ配置から出力される。
DSSPEAKER_HEADPHONE
オーディオはヘッドホンから出力される。
DSSPEAKER_MONO
オーディオはモノラル スピーカから出力される。
DSSPEAKER_QUAD
オーディオは 4 チャンネル ステレオ スピーカから出力される。
DSSPEAKER_STEREO
オーディオはステレオ スピーカから出力される (デフォルト値)。
DSSPEAKER_SURROUND
オーディオはサラウンド スピーカから出力される。
DSSPEAKER_STEREO は以下の値のいずれかとの組み合わせになる。
DSSPEAKER_GEOMETRY_WIDE
2 つのスピーカはリスナーを中心として 20 度の角度に置かれている。
DSSPEAKER_GEOMETRY_NARROW
2 つのスピーカはリスナーを中心として 10 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MIN
2 つのスピーカはリスナーを中心として 5 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MAX
2 つのスピーカはリスナーを中心として 180 度の角度に置かれている。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

lpdwSpeakerConfig に返される値は、構成とジオメトリ情報の両方を保持するパック DWORD となることがある。DWORD をアンパックするには、次の例のように DSSPEAKER_CONFIG と DSSPEAKER_GEOMETRY の各マクロを使う。

if (DSSPEAKER_CONFIG(dwSpeakerConfig) == DSSPEAKER_STEREO)
    {
    if (DSSPEAKER_GEOMETRY(dwSpeakerConfig) ==
                      DSSPEAKER_GEOMETRY_WIDE)
       {...}
    }

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound::SetSpeakerConfig、スピーカの構成


IDirectSound::Initialize

IDirectSound::Initialize メソッドは、CoCreateInstance 関数を使って作成した DirectSound オブジェクトを初期化する。

HRESULT Initialize(
  LPCGUID lpcGuid
);

パラメータ

lpcGuid
DirectSound オブジェクトに割り当てられるサウンド ドライバを指定する GUID (グローバル ユニーク識別子) アドレス。プライマリ サウンド ドライバを選択するには、NULL を渡す。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_ALREADYINITIALIZED
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_NODRIVER

注意

このメソッドは COM プロトコルに準拠して提供されている。DirectSoundCreate 関数を使って DirectSound オブジェクトを作成した場合は、このメソッドは DSERR_ALREADYINITIALIZED を返す。CoCreateInstance を使って DirectSound オブジェクトを作成した後、IDirectSound::Initialize を呼び出さないと、その後に呼び出したすべてのメソッドは DSERR_UNINITIALIZED を返す。

lLpcGuid パラメータは、DirectX 7.0 で LPGUID から LPCGUID に変更された。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

DirectSoundCreate


IDirectSound::SetCooperativeLevel

IDirectSound::SetCooperativeLevel メソッドは、このサウンド デバイスのアプリケーション協調レベルを設定する。

HRESULT SetCooperativeLevel(
  HWND hwnd,
  DWORD dwLevel
);

パラメータ

hwnd
アプリケーションへのウィンドウ ハンドル。「注意」を参照すること。
dwLevel
要求される優先レベル。以下の値のいずれかを指定する。
DSSCL_EXCLUSIVE
アプリケーションを排他レベルに設定する。入力フォーカスが置かれているアプリケーションだけが音を出せる (DSBCAPS_GLOBALFOCUS フラグが設定されているアプリケーションのサウンドは無音になる)。このレベルに設定されたアプリケーションは、DSSCL_PRIORITY レベルのすべての特権をも備えている。アプリケーションが入力フォーカスを得ると、DirectSound は前回 IDirectSoundBuffer::SetFormat メソッドを呼び出したときに指定されたハードウェア フォーマットを復元する。(どの優先レベルが設定されていても、DirectSound は常にウェーブ フォーマットを復元する点に注意すること。)
DSSCL_NORMAL
アプリケーションを完全に協調可能なステータスに設定する。このレベルでは最もスムーズなマルチタスキングとリソース共有の動作が得られるが、プライマリ バッファのフォーマットの変更は行えず、出力もデフォルトの 8 ビット フォーマットに限定される。
DSSCL_PRIORITY
アプリケーションを優先レベルに設定する。この協調レベルに設定されたアプリケーションは IDirectSoundBuffer::SetFormat と IDirectSound::Compact の各メソッドを呼び出せる。
DSSCL_WRITEPRIMARY
これは最上位の優先レベルである。このアプリケーションはプライマリ サウンド バッファへの書き込みアクセスを保持する。セカンダリ サウンド バッファはいずれも再生できない。デバイスが DirectSound ドライバでエミュレートされている場合、つまり IDirectSound::GetCaps メソッドが DSCAPS 構造体内に DSCAPS_EMULDRIVER フラグを返した場合は、このレベルは設定できない。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

アプリケーションはバッファを再生する前に、このメソッドを呼び出して協調レベルを設定しなければならない。推奨される協調レベルは DSSCL_PRIORITY である。他の優先レベルは必要に応じて使用する。詳細については、「協調レベル」を参照すること。

hwnd パラメータは、最上位のウィンドウ ハンドルとすべきである。DirectDraw をも使っている場合は、IDirectDraw7::SetCooperativeLevel メソッドに渡したのと同じハンドルを指定しなければならない。

アプリケーションがウィンドウ ハンドルを簡単に提供できない場合、次のコードを使ってウィンドウ ハンドルを取得できる。

HWND hWnd = GetForegroundWindow();
if (hWnd == NULL)
{
    hWnd = GetDesktopWindow();
}

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound::Compact、IDirectSoundBuffer::GetFormat、IDirectSoundBuffer::GetVolume、IDirectSoundBuffer::Lock、IDirectSoundBuffer::Play、IDirectSoundBuffer::Restore、IDirectSoundBuffer::SetFormat


IDirectSound::SetSpeakerConfig

IDirectSound::SetSpeakerConfig メソッドは、DirectSound オブジェクトのスピーカ構成を指定する。

HRESULT SetSpeakerConfig(
  DWORD dwSpeakerConfig
);

パラメータ

dwSpeakerConfig
DirectSound オブジェクトのスピーカ構成。このパラメータに、以下の値のいずれかを指定する。
DSSPEAKER_HEADPHONE
スピーカはヘッドホンである。
DSSPEAKER_MONO
スピーカはモノラルである。
DSSPEAKER_QUAD
スピーカは 4 チャンネルである。
DSSPEAKER_STEREO
スピーカはステレオである (デフォルト値)。
DSSPEAKER_SURROUND
スピーカはサラウンド サウンドである。

DSSPEAKER_STEREO は、以下の値のいずれかとの組み合わせになる。

DSSPEAKER_GEOMETRY_WIDE
2 つのスピーカはリスナーを中心として 20 度の角度に置かれている。
DSSPEAKER_GEOMETRY_NARROW
2 つのスピーカはリスナーを中心として 10 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MIN
2 つのスピーカはリスナーを中心として 5 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MAX
2 つのスピーカはリスナーを中心として 180 度の角度に置かれている。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

ジオメトリ値を使うには、DSSPEAKER_STEREO フラグと組み合わせた上で DWORD にパックしなければならない。次の C++ による例に示すように、DSSPEAKER_COMBINED マクロを使ってこのパックを行う。

lpds->SetSpeakerConfig(DSSPEAKER_COMBINED(
    DSSPEAKER_STEREO, DSSPEAKER_GEOMETRY_WIDE));

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー :dsound.h で宣言。
インポート ライブラリ :dsound.lib を使用。

参照

IDirectSound::GetSpeakerConfig、スピーカの構成


IDirectSound3DBuffer インターフェイス

アプリケーションは IDirectSound3DBuffer インターフェイスのメソッドを使って、3D 空間におけるリスナーの位置、方向、環境を記述するパラメータの取得と設定を行う。ここでは、IDirectSound3DBuffer インターフェイスのメソッドのリファレンスを提供する。概要については、「DirectSound 3D バッファ」を参照すること。

IDirectSound3DBuffer は、IDirectSoundBuffer::QueryInterface メソッドを使って取得する。詳細については、「DirectSound3DBuffer オブジェクトの取得」を参照すること。

IDirectSound3DBuffer インターフェイスのメソッドは、以下のグループにまとめることができる。

バッチ パラメータ操作 | GetAllParameters
 | SetAllParameters
距離 | GetMaxDistance
 | GetMinDistance
 | SetMaxDistance
 | SetMinDistance
操作モード | GetMode
 | SetMode
位置 | GetPosition
 | SetPosition
サウンド プロジェクション コーン | GetConeAngles
 | GetConeOrientation
 | GetConeOutsideVolume
 | SetConeAngles
 | SetConeOrientation
 | SetConeOutsideVolume
速度 | GetVelocity
 | SetVelocity

すべての COM インターフェイスと同様、IDirectSound3DBuffer インターフェイスは IUuknown インターフェイス メソッドを継承している。IUnknown インターフェイスは以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND3DBUFFER 型は、IDirectSound3DBuffer インターフェイスへのポインタとして定義されている。

typedef struct IDirectSound3DBuffer    *LPDIRECTSOUND3DBUFFER;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DBuffer::GetAllParameters

IDirectSound3DBuffer::GetAllParameters メソッドは、指定した時点でのサウンド バッファの 3D 特性に関する情報を取得する。

HRESULT GetAllParameters(
  LPDS3DBUFFER lpDs3dBuffer
);

パラメータ

lpDs3dBuffer
DS3DBUFFER 構造体のアドレス。この構造体はサウンド バッファの 3D 特性に関する情報を保持している。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DBuffer::GetConeAngles

IDirectSound3DBuffer::GetConeAngles メソッドは、サウンド バッファのサウンド プロジェクション コーンの内部角度と外部角度を取得する。

HRESULT GetConeAngles(
  LPDWORD lpdwInsideConeAngle,
  LPDWORD lpdwOutsideConeAngle
);

パラメータ

lpdwInsideConeAngle、lpdwOutsideConeAngle
サウンド プロジェクション コーンの内部角度と外部角度を保持する各変数のアドレス。単位は度 (゜)。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

最小、最大、デフォルトの各コーン角度は dsound.h 内でそれぞれ DS3D_MINCONEANGLE、DS3D_MAXCONEANGLE、DS3D_DEFAULTCONEANGLE として定義される。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DBuffer::GetConeOrientation

IDirectSound3DBuffer::GetConeOrientation メソッドは、サウンド バッファのサウンド プロジェクション コーンの方向を取得する。

HRESULT GetConeOrientation(
  LPD3DVECTOR lpvOrientation
);

パラメータ

lpvOrientation
D3DVECTOR 構造体のアドレス。この構造体は、サウンド プロジェクション コーンの現在の方向を保持する。ベクトル情報はサウンド コーンの中心を表す。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

戻り値は必ずしも IDirectSound3DBuffer::SetConeOrientation メソッドを使って設定したのと同じ値ではない。DirectSound は方向ベクトルに調整を加え、それらの大きさを 1.0 以下にする。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::SetConeOrientation、IDirectSound3DBuffer::SetConeAngles、IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::GetConeOutsideVolume

IDirectSound3DBuffer::GetConeOutsideVolume メソッドは、サウンド バッファの現在のコーン外部ボリュームを取得する。

HRESULT GetConeOutsideVolume(
  LPLONG lplConeOutsideVolume
);

パラメータ

lplConeOutsideVolume
バッファの現在のコーン外部ボリュームを保持する変数のアドレス。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

ボリューム レベルは減衰によって表される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。デフォルト値は DS3D_DEFAULTCONEOUTSIDEVOLUME (減衰なし) である。これらの値は dsound.h 内で定義されている。現在 DirectSound は増幅をサポートしていない。

コーン外部ボリュームの概念については、「サウンド コーン」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer::SetVolume


IDirectSound3DBuffer::GetMaxDistance

IDirectSound3DBuffer::GetMaxDistance メソッドは、サウンド バッファの現在の最大距離を取得する。

HRESULT GetMaxDistance(
  LPD3DVALUE lpflMaxDistance
);

パラメータ

lpflMaxDistance
現在の最大距離の設定を保持する変数のアドレス。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

デフォルトの最大距離は DS3D_DEFAULTMAXDISTANCE によって定義され、実質的に無限大である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::GetMinDistance、IDirectSound3DBuffer::SetMaxDistance


IDirectSound3DBuffer::GetMinDistance

IDirectSound3DBuffer::GetMinDistance メソッドは、サウンド バッファの現在の最小距離を取得する。

HRESULT GetMinDistance(
  LPD3DVALUE lpflMinDistance
);

パラメータ

lpflMinDistance
現在の最小距離の設定を保持する変数のアドレス。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

デフォルトでは、最小距離値は DS3D_DEFAULTMINDISTANCE であり、現在は 1.0 と定義されている (デフォルトの距離係数 1.0 を使った場合は、1 単位は 1.0 メートルに相当する)。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::SetMinDistance、IDirectSound3DBuffer::GetMaxDistance


IDirectSound3DBuffer::GetMode

IDirectSound3DBuffer::GetMode メソッドは、3D サウンド処理の現在の操作モードを取得する。

HRESULT GetMode(
  LPDWORD lpdwMode
);

パラメータ

lpdwMode
現在の操作モードの設定を保持する変数のアドレス。次の値のいずれかが返される。
DS3DMODE_DISABLE
3D サウンド処理は無効になる。サウンドはリスナーの頭の中心で発生しているように聞こえる。
DS3DMODE_HEADRELATIVE
サウンド パラメータ (位置、速度、方向) はリスナーのパラメータに対する相対的なものである。このモードでは、リスナーのパラメータが変化したときにサウンドの絶対パラメータが自動的に更新されるので、相対パラメータは一定に保たれる。
DS3DMODE_NORMAL
標準の処理。これはデフォルトのモードである。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DBuffer::GetPosition

IDirectSound3DBuffer::GetPosition メソッドは、サウンド バッファの現在位置を距離単位で取得する。デフォルトでは距離単位はメートルであるが、IDirectSound3DListener::SetDistanceFactor メソッドを使って単位を変更できる。

HRESULT GetPosition(
  LPD3DVECTOR lpvPosition
);

パラメータ

lpvPosition
D3DVECTOR 構造体のアドレス。この構造体は、サウンド バッファの現在位置を保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DBuffer::GetVelocity

IDirectSound3DBuffer::GetVelocity メソッドは、サウンド バッファの現在の速度を取得する。速度は、秒速単位で計測される。デフォルトの単位はメートル/秒であるが、IDirectSound3DListener::SetDistanceFactor メソッドを使って変更できる。

HRESULT GetVelocity(
  LPD3DVECTOR lpvVelocity
);

パラメータ

lpvVelocity
D3DVECTOR 構造体のアドレス。この構造体はサウンド バッファの現在の速度を保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

速度はドップラー効果でのみ使われる。実際にバッファを移動することはない。詳細については、「ドップラー係数」を参照すること。

デフォルトの計測単位はメートル/秒であるが、IDirectSound3DListener::SetDistanceFactor メソッドを使って変更できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::SetPosition、IDirectSound3DBuffer::SetVelocity


IDirectSound3DBuffer::SetAllParameters

IDirectSound3DBuffer::SetAllParameters メソッドは、DS3DBUFFER 構造体で指定した、すべての 3D サウンド バッファ パラメータを設定する。この構造体は、ある瞬間のサウンド バッファのすべての状態を記述する。

HRESULT SetAllParameters(
  LPCDS3DBUFFER lpcDs3dBuffer,
  DWORD dwApply
);

パラメータ

lpcDs3dBuffer
DS3DBUFFER 構造体のアドレス。この構造体はサウンド バッファの 3D 特性を保持している。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DBuffer::SetConeAngles

IDirectSound3DBuffer::SetConeAngles メソッドは、サウンド バッファのサウンド プロジェクション コーンの内部角度と外部角度を設定する。

HRESULT SetConeAngles(
  DWORD dwInsideConeAngle,
  DWORD dwOutsideConeAngle,
  DWORD dwApply
);

パラメータ

dwInsideConeAngle、dwOutsideConeAngle
サウンド プロジェクション コーンの内部角度と外部角度。単位は度 (゜)。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

最小、最大、デフォルトの各コーン角度は dsound.h 内でそれぞれ DS3D_MINCONEANGLE、DS3D_MAXCONEANGLE、DS3D_DEFAULTCONEANGLE として定義される。各角度の範囲は、0 度 (コーンなし) から 360 度 (全範囲) までである。デフォルト値は 360 である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::GetConeOutsideVolume、IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::SetConeOrientation

IDirectSound3DBuffer::SetConeOrientation メソッドは、サウンド バッファのサウンド プロジェクション コーンの方向を設定する。コーン角度とコーン ボリューム係数が既に設定されていない限り、このメソッドは何もしない。

HRESULT SetConeOrientation(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、z
D3DVALUE 型の値。これらの値は、サウンド コーンの新しい方向ベクトルの座標を表す。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::SetConeAngles、IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::SetConeOutsideVolume

IDirectSound3DBuffer::SetConeOutsideVolume メソッドは、サウンド バッファの現在のコーン外部ボリュームを設定する。

HRESULT SetConeOutsideVolume(
  LONG lConeOutsideVolume,
  DWORD dwApply
);

パラメータ

lConeOutsideVolume
サウンド バッファのコーン外部ボリュームを 100 分の 1 デシベル (dB) の単位で指定する。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。これらの値は dsound.h 内で定義されている。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

ボリューム レベルは減衰によって表される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。デフォルト値は DS3D_DEFAULTCONEOUTSIDEVOLUME (減衰なし) である。これらの値は dsound.h 内で定義されている。現在 DirectSound は増幅をサポートしていない。

コーン外部ボリュームの概念については、「サウンド コーン」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer::SetVolume


IDirectSound3DBuffer::SetMaxDistance

IDirectSound3DBuffer::SetMaxDistance メソッドは、現在の最大距離値を設定する。

HRESULT SetMaxDistance(
  D3DVALUE flMaxDistance,
  DWORD dwApply
);

パラメータ

flMaxDistance
新しい最大距離値。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

デフォルトの最大距離は DS3D_DEFAULTMAXDISTANCE によって定義され、実質的に無限大である。

動作環境

Windows NT/2000 :Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::GetMaxDistance、IDirectSound3DBuffer::SetMinDistance


IDirectSound3DBuffer::SetMinDistance

IDirectSound3DBuffer::SetMinDistance メソッドは、現在の最小距離値を設定する。

HRESULT SetMinDistance(
  D3DVALUE flMinDistance,
  DWORD dwApply
);

パラメータ

flMinDistance
新しい最小距離値。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

デフォルトでは、最小距離値は DS3D_DEFAULTMINDISTANCE であり、現在は 1.0 と定義されている (デフォルトの距離係数 1.0 を使った場合は、1 単位は 1.0 メートルに相当する)。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::SetMaxDistance


IDirectSound3DBuffer::SetMode

IDirectSound3DBuffer::SetMode メソッドは、3D サウンド処理の操作モードを設定する。

HRESULT SetMode(
  DWORD dwMode,
  DWORD dwApply
);

パラメータ

dwMode
設定される 3D サウンド処理モードを指定するフラグ。
DS3DMODE_DISABLE
3D サウンド処理は無効になる。サウンドはリスナーの頭の中心で発生しているように聞こえる。
DS3DMODE_HEADRELATIVE
サウンド パラメータ (位置、速度、方向) はリスナーのパラメータに対する相対的なものである。このモードでは、リスナーのパラメータが変化したときにサウンドの絶対パラメータは自動的に更新されるので、相対パラメータは一定に保たれる。
DS3DMODE_NORMAL
標準の処理。これはデフォルトのモードである。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DBuffer::SetPosition

IDirectSound3DBuffer::SetPosition メソッドは、サウンド バッファの現在位置を距離単位で設定する。デフォルトでは距離単位はメートルであるが、IDirectSound3DListener::SetDistanceFactor メソッドを使って単位を変更できる。

HRESULT SetPosition(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、z
D3DVALUE 型の値。これらの値は、新しい位置ベクトルの座標を表す。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある点に注意すること。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DBuffer::SetVelocity

IDirectSound3DBuffer::SetVelocity メソッドは、サウンド バッファの現在の速度を設定する。

HRESULT SetVelocity(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、z
D3DVALUE 型の値。これらの値は、新しい速度ベクトルの座標を表す。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある点に注意すること。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

速度はドップラー効果でのみ使われる。実際にバッファを移動することはない。詳細については、「ドップラー係数」を参照すること。

デフォルトの計測単位はメートル/秒であるが、IDirectSound3DListener::SetDistanceFactor メソッドを使って変更できる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DBuffer::SetPosition、IDirectSound3DBuffer::GetVelocity


IDirectSound3DListener インターフェイス

アプリケーションは IDirectSound3DListener インターフェイスのメソッドを使って、3D 空間でのリスナーの位置、方向、リスニング環境を記述するパラメータの取得と設定を行う。ここでは、IDirectSound3DListener インターフェイスのメソッドのリファレンスを提供する。概要については、「DirectSound 3D リスナー」を参照すること。

IDirectSoundBuffer::QueryInterface メソッドを使って、このインターフェイスを取得する。詳細については、「DirectSound3DListener オブジェクトの取得」を参照すること。

IDirectSound3DListener インターフェイスのメソッドは、以下のグループにまとめることができる。

バッチ パラメータ操作 | GetAllParameters
 | SetAllParameters
遅延設定 | CommitDeferredSettings
距離係数 | GetDistanceFactor
 | SetDistanceFactor
ドップラー係数 | GetDopplerFactor
 | SetDopplerFactor
方向 | GetOrientation
 | SetOrientation
位置 | GetPosition
 | SetPosition
ロールオフ係数 | GetRolloffFactor
 | SetRolloffFactor
速度 | GetVelocity
 | SetVelocity

すべての COM インターフェイスと同様、IDirectSound3DListener インターフェイスは IUuknown インターフェイス メソッドを継承している。IUnknown インターフェイスは以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND3DLISTENER 型は、IDirectSound3DListener インターフェイスへのポインタとして定義されている。

typedef struct IDirectSound3DListener    *LPDIRECTSOUND3DLISTENER;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DListener::CommitDeferredSettings

IDirectSound3DListener::CommitDeferredSettings メソッドは、前回このメソッドを呼び出した後に行われた遅延設定をコミットする。

HRESULT CommitDeferredSettings();

パラメータ

なし。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

最大の効率をもたらす遅延設定の使い方については、「遅延設定」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSound3DListener::GetAllParameters

IDirectSound3DListener::GetAllParameters メソッドは、3D ワールドとリスナーの現在の状態を表す情報を取得する。

HRESULT GetAllParameters(
  LPDS3DLISTENER lpListener
);

パラメータ

lpListener
DS3DLISTENER 構造体のアドレス。この構造体は 3D ワールドとリスナーの現在の状態を保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::SetAllParameters


IDirectSound3DListener::GetDistanceFactor

IDirectSound3DListener::GetDistanceFactor メソッドは、現在の距離係数を取得する。

HRESULT GetDistanceFactor(
  LPD3DVALUE lpflDistanceFactor
);

パラメータ

lpflDistanceFactor
D3DVALUE 型の変数のアドレス。この変数は、現在の距離係数の値を保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

距離係数の詳細については、「距離係数」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::SetDistanceFactor


IDirectSound3DListener::GetDopplerFactor

IDirectSound3DListener::GetDopplerFactor メソッドは、現在のドップラー効果係数を取得する。

HRESULT GetDopplerFactor(
  LPD3DVALUE lpflDopplerFactor
);

パラメータ

lpflDopplerFactor
D3DVALUE 型の変数のアドレス。この変数は現在のドップラー係数の値を保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

ドップラー係数の範囲は、DS3D_MINDOPPLERFACTOR (ドップラー効果なし) から DS3D_MAXDOPPLERFACTOR (現在の定義では実世界の 10 倍のドップラー効果) までである。デフォルト値は DS3D_DEFAULTDOPPLERFACTOR (1.0) である。詳細については、「ドップラー係数」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::SetDopplerFactor


IDirectSound3DListener::GetOrientation

IDirectSound3DListener::GetOrientation メソッドは、前方ベクトルと上方ベクトルの 2 つのベクトルにより、リスナーの現在の方向を取得する。

HRESULT GetOrientation(
  LPD3DVECTOR lpvOrientFront,
  LPD3DVECTOR lpvOrientTop
);

パラメータ

lpvOrientFront
D3DVECTOR 構造体のアドレス。この構造体はリスナーの前方ベクトルを保持する。
lpvOrientTop
D3DVECTOR 構造体のアドレス。この構造体はリスナーの上方ベクトルを保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

前方ベクトルはリスナーの鼻の方向、上方ベクトルはリスナーの頭頂部の方向を指す。デフォルトでは、前方ベクトルは (0, 0, 1.0)、上方ベクトルは (0, 1.0, 0) である。

戻り値は必ずしも IDirectSound3DListener::SetOrientation を使って設定したのと同じ値ではない。DirectSound は方向ベクトルに調整を加えて、それらが互いに直交するようにし、両方の大きさを 1.0 以下にする。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::SetOrientation


IDirectSound3DListener::GetPosition

IDirectSound3DListener::GetPosition メソッドは、リスナーの現在位置を距離単位で取得する。デフォルトでは距離単位はメートルであるが、IDirectSound3DListener::SetDistanceFactor メソッドを使って単位を変更できる。

HRESULT GetPosition(
  LPD3DVECTOR lpvPosition
);

パラメータ

lpvPosition
D3DVECTOR 構造体のアドレス。この構造体はリスナーの現在位置を保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::SetPosition


IDirectSound3DListener::GetRolloffFactor

IDirectSound3DListener::GetRolloffFactor メソッドは、現在のロールオフ係数を取得する。

HRESULT GetRolloffFactor(
  LPD3DVALUE lpflRolloffFactor
);

パラメータ

lpflRolloffFactor
D3DVALUE 型の変数のアドレス。この変数は現在のロールオフ係数の値を保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

ロールオフ係数は、DS3D_MINROLLOFFFACTOR (ロールオフなし) から DS3D_MAXROLLOFFFACTOR (現在の定義では実世界の 10 倍) までの範囲をとる。デフォルト値は DS3D_DEFAULTROLLOFFFACTOR (1.0) である。詳細については、「ロールオフ係数」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::SetRolloffFactor


IDirectSound3DListener::GetVelocity

IDirectSound3DListener::GetVelocity メソッドは、リスナーの現在の速度を取得する。

HRESULT GetVelocity(
  LPD3DVECTOR lpvVelocity
);

パラメータ

lpvVelocity
D3DVECTOR 構造体のアドレス。この構造体はリスナーの現在の速度を保持する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

速度はドップラー効果でのみ使われる。実際にリスナーを移動することはない。リスナーの位置を変更するには IDirectSound3DListener::SetPosition メソッドを使う。デフォルトの速度は (0,0,0) である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::SetVelocity


IDirectSound3DListener::SetAllParameters

IDirectSound3DListener::SetAllParameters メソッドは、DS3DLISTENER 構造体で指定した、すべての 3D リスナー パラメータを設定する。この構造体はある瞬間のリスナーのすべての状態を記述する。

HRESULT SetAllParameters(
  LPCDS3DLISTENER lpcListener,
  DWORD dwApply
);

パラメータ

lpcListener
DS3DLISTENER 構造体のアドレス。この構造体は現在の 3D リスナーのすべてのパラメータ情報を保持する。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::GetAllParameters


IDirectSound3DListener::SetDistanceFactor

IDirectSound3DListener::SetDistanceFactor メソッドは、現在の距離係数を設定する。

HRESULT SetDistanceFactor(
  D3DVALUE flDistanceFactor,
  DWORD dwApply
);

パラメータ

flDistanceFactor
新しい距離係数。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

距離係数の詳細については、「距離係数」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::GetDistanceFactor


IDirectSound3DListener::SetDopplerFactor

IDirectSound3DListener::SetDopplerFactor メソッドは、現在のドップラー効果係数を設定する。

HRESULT SetDopplerFactor(
  D3DVALUE flDopplerFactor,
  DWORD dwApply
);

パラメータ

flDopplerFactor
新しいドップラー係数の値。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

ドップラー係数の範囲は、DS3D_MINDOPPLERFACTOR (ドップラー効果なし) から DS3D_MAXDOPPLERFACTOR (現在の定義では実世界の 10 倍のドップラー効果) までである。デフォルト値は DS3D_DEFAULTDOPPLERFACTOR (1.0) である。詳細については、「ドップラー係数」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::GetDopplerFactor


IDirectSound3DListener::SetOrientation

IDirectSound3DListener::SetOrientation メソッドは、前方ベクトルと上方ベクトルの 2 つのベクトルにより、リスナーの現在の方向を設定する。

HRESULT SetOrientation(
  D3DVALUE xFront,
  D3DVALUE yFront,
  D3DVALUE zFront,
  D3DVALUE xTop,
  D3DVALUE yTop,
  D3DVALUE zTop,
  DWORD dwApply
);

パラメータ

xFront、yFront、zFront
D3DVALUE 型の値。これらの値は、前方ベクトルの座標を示す。
xTop、yTop、zTop
D3DVALUE 型の値。これらの値は、上方ベクトルの座標を示す。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

前方ベクトルはリスナーの鼻の方向、上方ベクトルはリスナーの頭頂部の方向を指す。デフォルトでは、前方ベクトルは (0, 0, 1.0)、上方ベクトルは (0, 1.0, 0) である。

上方ベクトルは前方ベクトルに対して直角でなければならない。必要に応じて、DirectSound は前方ベクトルを設定した後で上方ベクトルを調整する。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::GetOrientation


IDirectSound3DListener::SetPosition

IDirectSound3DListener::SetPosition メソッドは、リスナーの現在位置を距離単位で設定する。デフォルトでは距離単位はメートルであるが、IDirectSound3DListener::SetDistanceFactor メソッドを使って単位を変更できる。

HRESULT SetPosition(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、z
D3DVALUE 型の値。これらの値は、リスナーの新しい位置ベクトルの座標を表す。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある点に注意すること。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::GetPosition


IDirectSound3DListener::SetRolloffFactor

IDirectSound3DListener::SetRolloffFactor メソッドは、ロールオフ係数を設定する。

HRESULT SetRolloffFactor(
  D3DVALUE flRolloffFactor,
  DWORD dwApply
);

パラメータ

flRolloffFactor
新しいロールオフ係数。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

ロールオフ係数は、DS3D_MINROLLOFFFACTOR (ロールオフなし) から DS3D_MAXROLLOFFFACTOR (現在の定義では実世界の 10 倍) までの範囲をとる。デフォルト値は DS3D_DEFAULTROLLOFFFACTOR (1.0) である。詳細については、「ロールオフ係数」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::GetRolloffFactor


IDirectSound3DListener::SetVelocity

IDirectSound3DListener::SetVelocity メソッドは、リスナーの速度を設定する。

HRESULT SetVelocity(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、z
D3DVALUE 型の値。これらの値は、リスナーの新しい速度座標を表す。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある点に注意すること。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener::CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

速度はドップラー効果でのみ使われる。実際にリスナーを移動することはない。リスナーの位置を変更するには IDirectSound3DListener::SetPosition メソッドを使う。デフォルトの速度は (0,0,0) である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound3DListener::GetVelocity


IDirectSoundBuffer インターフェイス

アプリケーションは IDirectSoundBuffer インターフェイスのメソッドを使って、DirectSoundBuffer オブジェクトの作成と環境設定を行う。

IDirectSound::CreateSoundBuffer メソッドを使ってこのインターフェイスを取得する。

IDirectSoundBuffer インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetCaps
 | GetFormat
 | GetStatus
 | SetFormat
メモリ管理 | Initialize
 | Restore
再生管理 | GetCurrentPosition
 | Lock
 | Play
 | SetCurrentPosition
 | Stop
 | Unlock
サウンド管理 | GetFrequency
 | GetPan
 | GetVolume
 | SetFrequency
 | SetPan
 | SetVolume

すべての COM インターフェイスと同様に、IDirectSoundBuffer インターフェイスも IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDBUFFER 型は、IDirectSoundBuffer インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundBuffer    *LPDIRECTSOUNDBUFFER;

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundBuffer::GetCaps

IDirectSoundBuffer::GetCaps メソッドは、DirectSoundBuffer オブジェクトの能力を取得する。

HRESULT GetCaps(
  LPDSBCAPS lpDSBufferCaps
);

パラメータ

lpDSBufferCaps
DSBCAPS 構造体のアドレス。この構造体は、サウンド バッファの能力を保持している。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

DSBCAPS 構造体は、IDirectSound::CreateSoundBuffer メソッドに渡される DSBUFFERDESC 構造体と同等の情報に加えて、いくつかの追加情報を保持している。追加情報として、バッファの位置 (ハードウェアまたはソフトウェア) と、コスト測定値が挙げられる。コスト測定値には、ハードウェア バッファへのダウンロード所要時間、バッファがシステム メモリ内に配置されている場合のミキシングや再生処理のオーバーヘッドが含まれる。

DSBCAPS 構造体の dwFlags メンバ内で指定されるフラグは、DSBUFFERDESC 構造体で使われるフラグと同じものである。唯一の違いは、DSBCAPS 構造体ではバッファ メモリの場所に応じて DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらかが指定されることである。DSBUFFERDESC 構造体ではこれらのフラグはオプションであり、フラグの指定に応じて、バッファをハードウェアとソフトウェアのどちらかに強制的に配置できる。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

DSBCAPS、DSBUFFERDESC、IDirectSoundBuffer、IDirectSound::CreateSoundBuffer


IDirectSoundBuffer::GetCurrentPosition

IDirectSoundBuffer::GetCurrentPosition メソッドは、サウンド バッファ内の再生カーソルと書き込みカーソルの現在の位置を取得する。

HRESULT GetCurrentPosition(
  LPDWORD lpdwCurrentPlayCursor,
  LPDWORD lpdwCurrentWriteCursor
);

パラメータ

lpdwCurrentPlayCursor
DirectSoundBuffer オブジェクト内のカレント プレイ ポジションを保持する変数のアドレス。この位置はサウンド バッファ内のオフセットであり、バイト単位で指定される。カレント プレイ ポジションが必要ない場合は、このパラメータは NULL であってもよい。
lpdwCurrentWriteCursor
DirectSoundBuffer オブジェクト内のカレント ライト ポジションを保持する変数のアドレス。この位置はサウンド バッファ内のオフセットであり、バイト単位で指定される。カレント ライト ポジションが必要ない場合は、このパラメータは NULL であってもよい。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

書き込みカーソルは、バッファへのデータ書き込みを安全に行える位置を示す。書き込みカーソルは通常、再生カーソルより 15 ミリ秒のオーディオ データ分だけ先行している。詳細については、「カレント プレイ ポジションとカレント ライト ポジション」を参照すること。

lpdwCurrentPlayCursor パラメータが示す位置より後の場所では、必ずデータを安全に変更できる。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::SetCurrentPosition


IDirectSoundBuffer::GetFormat

IDirectSoundBuffer::GetFormat メソッドは、バッファ内のサウンド データのフォーマットに関する情報、またはフォーマットの記述を取得するのに必要なバッファ サイズを取得する。

HRESULT GetFormat(
  LPWAVEFORMATEX lpwfxFormat,
  DWORD dwSizeAllocated,
  LPDWORD lpdwSizeWritten
);

パラメータ

lpwfxFormat
バッファ内のサウンド データに関する情報を保持する WAVEFORMATEX 構造体のアドレス。フォーマットの記述を保持するのに必要なバッファ サイズを取得するには NULL を指定する。この場合、lpdwSizeWritten パラメータが指す DWORD が、完全なフォーマット情報を受け取るのに必要な構造体のサイズを受け取る。
dwSizeAllocated
WAVEFORMATEX 構造体のサイズ。単位はバイト。DirectSound がポインタへ書き込むバイト数は、最大で dwSizeAllocated バイトである。WAVEFORMATEX 構造体がそれより多くのメモリを必要とする場合、切り捨てが行われる。
lpdwSizeWritten
WAVEFORMATEX 構造体に書き込まれたバイト数を保持する変数のアドレス。このパラメータは NULL にしてもよい。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

注意

WAVEFORMATEX 構造体は、フォーマットの詳細に応じた可変長であってもよい。アプリケーションはフォーマットの記述を取得する前に、lpwfxFormat パラメータに NULL を指定してこのメソッドを呼び出し、フォーマットのサイズに関して DirectSoundBuffer へクエリーを行うべきである。構造体のサイズは lpdwSizeWritten パラメータへ返される。その後、アプリケーションは十分なメモリを割り当て、もう一度 IDirectSoundBuffer::GetFormat を呼び出し、フォーマットの記述を取得できる。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::SetFormat


IDirectSoundBuffer::GetFrequency

IDirectSoundBuffer::GetFrequency メソッドは、バッファの再生が行われている場所での 1 秒あたりのサンプリング回数を周波数として取得する。

HRESULT GetFrequency(
  LPDWORD lpdwFrequency
);

パラメータ

lpdwFrequency
オーディオ バッファが再生されている場所での周波数を示す変数のアドレス。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

周波数の値は、DSBFREQUENCY_MIN から DSBFREQUENCY_MAX の範囲をとる。現在これらの値は、dsound.h 内でそれぞれ 100、100,000 と定義されている。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::SetFrequency


IDirectSoundBuffer::GetPan

IDirectSoundBuffer::GetPan メソッドは、左右のオーディオ チャンネルの相対ボリュームを示す変数を取得する。

HRESULT GetPan(
  LPLONG lplPan
);

パラメータ

lplPan
左右の相対ミキシング率を保持する変数のアドレス。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

戻り値は DSBPAN_LEFT から DSBPAN_RIGHT の範囲で、100 分の 1 デシベル (dB) 単位で測定される。現在これらの値は、dsound.h 内でそれぞれ 10,000、-10,000 と定義されている。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値は DSBPAN_CENTER であり、0 と定義されている。lplPan が 0 であるとき、両方のチャンネルが最大ボリュームであることを意味する (どちらも 0 dB の減衰である)。DSBPAN_CENTER 以外の値はどれも、一方が最大ボリュームでもう一方が減衰していることを意味する。

パンの値が -2,173 のとき、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様にパンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。DSBPAN_LEFT のパンは、右チャンネルが無音で、サウンドが左からのみ発生していることを意味する。一方、DSBPAN_RIGHT のパンは、左チャンネルが無音で、サウンドが右からのみ発生していることを意味する。

パン コントロールの効果は、ボリューム コントロールに累積される。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::GetVolume、IDirectSoundBuffer::SetPan、IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::GetStatus

IDirectSoundBuffer::GetStatus メソッドは、サウンド バッファの現在のステータスを取得する。

HRESULT GetStatus(
  LPDWORD lpdwStatus
);

パラメータ

lpdwStatus
サウンド バッファのステータスを保持する変数のアドレス。ステータスは、以下のフラグの組み合わせである。
DSBSTATUS_BUFFERLOST
バッファは失われており、再生やロックを行う前に復元しなければならない。
DSBSTATUS_LOOPING
バッファはループしている。この値が設定されていない場合、バッファのサウンド データの最後に達すると再生は停止する。この値が設定されているとき、バッファは必ず再生されている点に注意すること。
DSBSTATUS_PLAYING
バッファは再生中である。この値が設定されていない場合、バッファは停止している。
DSBSTATUS_LOCSOFTWARE
ソフトウェアのバッファは再生中である。DSBCAPS_LOCDEFER フラグで作成したバッファにだけ設定する。
DSBSTATUS_LOCHARDWARE
ハードウェアのバッファは再生中である。DSBCAPS_LOCDEFER フラグで作成したバッファにだけ設定する。
DSBSTATUS_TERMINATED
ボイス管理がバッファを早めに終了し、バッファは停止している。DSBCAPS_LOCDEFER フラグで作成したバッファにだけ設定する。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer


IDirectSoundBuffer::GetVolume

IDirectSoundBuffer::GetVolume メソッドは、サウンド バッファの現在のボリュームを取得する。

HRESULT GetVolume(
  LPLONG lplVolume
);

パラメータ

lplVolume
指定された DirectSound バッファに関連付けられたボリュームを保持する変数のアドレス。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

ボリュームは 100 分の 1 デシベル (dB) 単位で指定される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。現在これらの値は、dsound.h 内でそれぞれ 0、-10,000 と定義されている。値 DSBVOLUME_MAX は、ストリーム本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。現在、DirectSound は増幅をサポートしていない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::Initialize

IDirectSoundBuffer::Initialize メソッドは、初期化されていない DirectSoundBuffer オブジェクトを初期化する。

HRESULT Initialize(
  LPDIRECTSOUND lpDirectSound,
  LPCDSBUFFERDESC lpcDSBufferDesc
);

パラメータ

lpDirectSound
DirectSoundBuffer オブジェクトに関連付けられた DirectSound オブジェクトのアドレス。
lpcDSBufferDesc
このサウンド バッファを初期化するために使われる値を保持する DSBUFFERDESC 構造体のアドレス。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

注意

IDirectSound::CreateSoundBuffer メソッドは内部で IDirectSoundBuffer::Initialize を呼び出すので、現在のリリースの DirectSound では Initialize を明示的に呼び出す必要はない。Initialize メソッドは将来の拡張性に備えて用意されている。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

DSBUFFERDESC、IDirectSound::CreateSoundBuffer、IDirectSoundBuffer


IDirectSoundBuffer::Lock

IDirectSoundBuffer::Lock メソッドは、サウンド バッファのオーディオ データに対する有効な書き込みポインタを取得する。

HRESULT Lock(
  DWORD dwWriteCursor,
  DWORD dwWriteBytes,
  LPVOID lplpvAudioPtr1,
  LPDWORD lpdwAudioBytes1,
  LPVOID lplpvAudioPtr2,
  LPDWORD lpdwAudioBytes2,
  DWORD dwFlags
);

パラメータ

dwWriteCursor
バッファの先頭からロック開始位置までのオフセット。単位はバイト。dwFlags パラメータで DSBLOCK_FROMWRITECURSOR フラグが指定されている場合は、このパラメータは無視される。
dwWriteBytes
ロックされるバッファ部分のサイズ。単位はバイト。サウンド バッファは概念的には循環バッファである点に注意すること。
lplpvAudioPtr1
ロックされるサウンド バッファの最初のブロックを保持するポインタのアドレス。
lpdwAudioBytes1
lplpvAudioPtr1 パラメータが指すバイト数を保持する変数のアドレス。この値が dwWriteBytes パラメータより小さい場合、lplpvAudioPtr2 はサウンド データの 2 番目のブロックを指す。
lplpvAudioPtr2
ロックされるサウンド バッファの 2 番目のブロックを保持するポインタのアドレス。このパラメータの値が NULL の場合、lplpvAudioPtr1 パラメータはサウンド バッファのロックされた部分全体を指す。
lpdwAudioBytes2
lplpvAudioPtr2 パラメータが指すバイト数を保持する変数のアドレス。lplpvAudioPtr2 が NULL の場合、この値は 0 になる。
dwFlags
ロックイベントに変更を加えるフラグ。以下のフラグが定義されている。
DSBLOCK_FROMWRITECURSOR
カレント ライト ポジションからロックを行う。この結果、IDirectSoundBuffer::GetCurrentPosition の呼び出しが不要になる。このフラグを指定すると dwWriteCursor パラメータは無視される。
DSBLOCK_ENTIREBUFFER
バッファ全体をロックする。dwWriteBytes パラメータは無視される。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

このメソッドはオフセットとバイト カウントを受け取り、2 つの書き込みポインタとそれぞれに関連するサイズを返す。サウンド バッファが循環するため、2 つのポインタが必要である。ロックされたバイトがバッファの最後からラップ アラウンドしない (先頭へ戻らない) 場合、2 番目のポインタである lplpvAudioBytes2 は NULL になる。ただし、バイトがラップ アラウンドする場合は、2 番目のポインタはバッファの先頭を指す。

アプリケーションが lplpvAudioPtr2 と lpdwAudioBytes2 の各パラメータに NULL を渡すと、DirectSound はバッファのラップアラウンド部分をロックしない。

アプリケーションは、IDirectSoundBuffer::Lock メソッドが返したポインタにデータを書き込み、IDirectSoundBuffer::Unlock メソッドを呼び出し、バッファを解放して DirectSound へ返すべきである。サウンド バッファは長時間にわたってロックすべきではない。長時間のロックを行うと、再生カーソルがロックされた部分に達してしまい、機器構成に依存するランダム ノイズなどのオーディオの問題が発生することがある。

警告：このメソッドは、書き込みポインタのみを返す。アプリケーションは、そのポインタを使ったサウンド データの読み込みを行うべきではない。DirectSoundBuffer オブジェクトが有効なサウンド データを保持している場合でも、そのデータが有効でない可能性がある。たとえば、バッファがオンボード メモリに配置されている場合、そのポインタはメイン システム メモリ内の一時バッファのアドレスとなっていることも考えられる。IDirectSoundBuffer::Unlock を呼び出すと、この一時バッファはオンボード メモリに転送される。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::GetCurrentPosition、IDirectSoundBuffer::Unlock


IDirectSoundBuffer::Play

IDirectSoundBuffer::Play メソッドは、サウンド バッファを現在の位置から再生する。

HRESULT Play(
  DWORD dwReserved1,
  DWORD dwPriority,
  DWORD dwFlags
);

パラメータ

dwReserved1
このパラメータは予約されている。この値は 0 でなければならない。
dwPriority
サウンドの優先度。この優先度は、ハードウェア ミキシング リソースを割り当てる際にボイス管理が使用する。最も低い優先度は 0、最も高い優先度は 0xFFFFFFFF である。バッファが DSBCAPS_LOCDEFER フラグで作成されていない場合、この値は 0 である。
dwFlags
バッファの再生方法を指定するフラグ。以下のフラグが定義されている。
DSBPLAY_LOOPING
オーディオ バッファの最後に達すると、バッファの先頭から再生を再開する。明示的に停止するまで再生が続く。このフラグは、プライマリ サウンド バッファを再生する際に設定しなければならない。
ボイス割り当てフラグ
ボイス割り当てフラグは、バッファが DSBCAPS_LOCDEFER フラグで作成されたときのみ有効である。サウンド処理をハードウェアかソフトウェアで強制的に行うには、次のフラグのいずれかを使うこともできる。DBSPLAY_LOCHARDWARE と DBSPLAY_LOCSOFTWARE のどちらも設定されていない場合は、メソッドが呼び出されたときにリソースが利用可能かどうかによって、サウンドがソフトウェアまたはハードウェアで再生される。「注意」を参照すること。
DSBPLAY_LOCHARDWARE
ハードウェア バッファのみでボイスを再生する。ハードウェアに利用可能なボイスがなく、ボイス管理フラグも設定されていない場合、IDirectSoundBuffer::Play に対する呼び出しは失敗する。このフラグを DSBPLAY_LOCSOFTWARE と組み合わせることはできない。
DSBPLAY_LOCSOFTWARE
ソフトウェア バッファのみでボイスを再生する。このフラグを DSBPLAY_LOCHARDWARE やボイス管理フラグのどれかと組み合わせることはできない。
ボイス管理フラグ
ボイス管理フラグは、バッファが DSBCAPS_LOCDEFER フラグで作成されたときにのみ有効であり、ハードウェアで再生するサウンドに使われる。これらのフラグは、使用中のハードウェア リソースに現在のサウンドが受け渡されるようにする。DSBCAPS_LOCDEFER フラグで作成されたバッファのみが、早めに終了される候補となる。「注意」を参照すること。
DSBPLAY_TERMINATEBY_TIME
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中のバッファを停止する。早めに終了されるバッファは、再生の残り時間が最も少ないバッファである。
DSBPLAY_TERMINATEBY_DISTANCE
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中のバッファを停止する。早めに終了されるバッファは、DSBCAPS_MUTE3DATMAXDISTANCE フラグがセットされ、最大距離を超えているものの中から選択される。このようなバッファがない場合、メソッドは失敗する。
DSBPLAY_TERMINATEBY_PRIORITY
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中のバッファを停止する。早めに終了されるバッファは、IDirectSoundBuffer::Play に渡される dwPriority パラメータで設定された優先度が最も低いバッファである。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_BUFFERLOST
DSERR_HWUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

IDirectSound::SetCooperativeLevel を呼び出していない場合でも、メソッドは DS_OK を返す。ただし、協調レベルが設定されるまでサウンドは出力されない。

このメソッドが指定したバッファが既に再生中だった場合、メソッドの呼び出しは成功し、バッファは再生を続ける。ただし最新の呼び出しで定義したフラグは、以前の呼び出しで定義されていたフラグを置き換える。

このメソッドがプライマリ バッファで呼び出された場合は、サウンド デバイスでバッファの再生が開始される。アプリケーションが DSSCL_WRITEPRIMARY の協調レベルに設定されている場合は、アプリケーションによりプライマリ バッファに置かれた任意のオーディオ データがサウンド デバイスに送られる。アプリケーションが他の協調レベルに設定されている場合は、セカンダリ バッファが再生されていないと、プライマリ バッファは無音となる。プライマリ バッファは、DSBPLAY_LOOPING フラグで再生しなければならない。詳細については、「プライマリ バッファの連続再生」を参照すること。

このメソッドが DSBCAPS_LOCDEFER フラグで作成されていないバッファ上に設定されたボイス割り当てフラグ、もしくはボイス管理フラグで呼び出されると、この呼び出しは失敗し、DSERR_INVALIDPARAM が返される。

DSBPLAY_TERMINATEBY_TIME と DSBPLAY_TERMINATEBY_DISTANCE を組み合わせることはできないが、このどちらかと DSBPLAY_TERMINATEBY_PRIORITY を組み合わせることができる。この場合、DSBPLAY_TERMINATEBY_TIME または DSBPLAY_TERMINATEBY_DISTANCE フラグは、優先度が等しい場合にどのバッファを終了すべきかを決定するのに使われる。

次の表は、ハードウェア ボイスの空きを利用できない場合に、ボイス割り当てフラグとボイス管理フラグの組み合わせによって決まるメソッドの動作を示す。

 | DSBPLAY_LOCHARDWARE | DSBPLAY_LOCHARDWARE と DSBPLAY_LOCSOFTWARE のどちらも使わない | DSBPLAY_LOCSOFTWARE
DSBPLAY_TERMINATEBY_TIME | 再生の残り時間が最も少ないサウンドを終了し、新しいサウンドを解放したボイスで再生する。 | 再生の残り時間が最も少ないサウンドを終了し、新しいサウンドを解放したボイスで再生する。 | 新しいサウンドをソフトウェアで再生する。
DSBPLAY_TERMINATEBY_DISTANCE | ハードウェアで現在再生中のサウンドが最大距離を超えており、DSBCAPS_MUTE3DATMAXDISTANCE フラグがセットされている場合、そのいずれかを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 | ハードウェアで現在再生中のサウンドが最大距離を超えており、DSBCAPS_MUTE3DATMAXDISTANCE フラグがセットされている場合、そのいずれかを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 | 新しいサウンドをソフトウェアで再生する。
DSBPLAY_TERMINATEBY_PRIORITY | 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 | 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 | 新しいサウンドをソフトウェアで再生する。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSound::SetCooperativeLevel


IDirectSoundBuffer::Restore

IDirectSoundBuffer::Restore メソッドは、指定された DirectSoundBuffer オブジェクトに関連付けられていた、失われたサウンド バッファへのメモリ割り当てを復元する。

HRESULT Restore();

パラメータ

なし。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

アプリケーションに入力フォーカスが置かれていないと、IDirectSoundBuffer::Restore は成功しないことがある。たとえば、入力フォーカスが置かれているアプリケーションが DSSCL_WRITEPRIMARY (書き込み優先) 協調レベルに設定されている場合、他のどのアプリケーションもバッファを復元できない。同様に DSSCL_WRITEPRIMARY 協調レベルのアプリケーションがプライマリ サウンド バッファを復元するには、入力フォーカスが必要である。

DirectSound がバッファ メモリを復元した後、有効なサウンド データを書き込み直す必要がある。DirectSound はメモリを復元するが、メモリの内容は復元できない。

アプリケーションはバッファを指定して IDirectSoundBuffer::Lock または IDirectSoundBuffer::Play の各メソッドを呼び出すと、そのバッファが失われている場合に通知を受けられる。バッファが失われている場合は、これらのメソッドは DSERR_BUFFERLOST を返す。IDirectSoundBuffer::GetStatus メソッドを使って、サウンド バッファのステータスの取得と DSBSTATUS_BUFFERLOST フラグのテストを行うこともできる。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::Lock、IDirectSoundBuffer::Play、IDirectSoundBuffer::GetStatus


IDirectSoundBuffer::SetCurrentPosition

IDirectSoundBuffer::SetCurrentPosition メソッドは、セカンダリ サウンド バッファのカレント プレイ ポジションを移動する。

HRESULT SetCurrentPosition(
  DWORD dwNewPosition
);

パラメータ

dwNewPosition
サウンド バッファの再生に使われる新しい位置。バッファの先頭からのオフセット値で指定する。単位はバイト。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

プライマリ サウンド バッファに対しては、このメソッドを呼び出せない。

バッファが再生中のときにこのメソッドを呼び出すと、即座に新規の位置へ移動して再生を続行する。バッファが停止している場合は、次に IDirectSoundBuffer::Play メソッドを呼び出したときに、新しい位置から再生を開始する。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::GetCurrentPosition、IDirectSoundBuffer::Play


IDirectSoundBuffer::SetFormat

IDirectSoundBuffer::SetFormat メソッドは、このアプリケーション用のプライマリ サウンド バッファのフォーマットを設定する。このアプリケーションに入力フォーカスが置かれるたびに、DirectSound はプライマリ バッファを指定されたフォーマットに設定する。

HRESULT SetFormat(
  LPCWAVEFORMATEX lpcfxFormat
);

パラメータ

lpcfxFormat
WAVEFORMATEX 構造体のアドレス。この構造体は、プライマリ サウンド バッファの新しいフォーマットを記述する。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED
DSERR_UNSUPPORTED

注意

書き込み優先協調レベルでアクセスされているプライマリ バッファに対してこのメソッドを呼び出す場合は、IDirectSoundBuffer::SetFormat を呼び出す前にバッファを停止しておかなければならない。書き込み優先以外の協調レベルのプライマリ バッファに対してこのメソッドを呼び出す場合は、DirectSound はプライマリ バッファを明示的に停止し、フォーマットを変更し、プライマリを再開する。アプリケーションがこれらの作業を明示的に行う必要はない。

ハードウェアが、要求されたフォーマットをサポートしていない場合でも、このメソッドは成功する。DirectSound はバッファを、要求に最も近いフォーマットに設定し、要求されたフォーマットでサウンドをミックスし、変換した上でプライマリ バッファに送る。このような状況が発生しているかどうかを判断するには、アプリケーションはプライマリ バッファに対して IDirectSoundBuffer::GetFormat メソッドを呼び出し、その結果を、SetFormat メソッドで要求したフォーマットと比較する。

アプリケーションが DSSCL_NORMAL 協調レベルに設定されている場合、このメソッドの呼び出しは失敗する。

このメソッドはセカンダリ サウンド バッファには有効ではない。セカンダリ サウンド バッファがフォーマットの変更を必要とする場合、アプリケーションは新しいフォーマットを使う新しい DirectSoundBuffer オブジェクトを作成すべきである。

DirectSound は PCM フォーマットをサポートしている。現在、圧縮フォーマットはサポートしていない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::GetFormat


IDirectSoundBuffer::SetFrequency

IDirectSoundBuffer::SetFrequency メソッドは、サンプリング オーディオの再生周波数を設定する。

HRESULT SetFrequency(
  DWORD dwFrequency
);

パラメータ

dwFrequency
サンプリング オーディオを再生する新しい周波数で、単位はヘルツ (Hz) である。値の範囲は DSBFREQUENCY_MIN から DSBFREQUENCY_MAX の間でなければならない。現在これらの値は dsound.h 内で、それぞれ 100、100,000 と定義されている。

値が DSBFREQUENCY_ORIGINAL の場合、周波数は現在のバッファ フォーマット内のデフォルト値にリセットされる。このフォーマットは IDirectSound::CreateSoundBuffer メソッドで指定されたものである。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

周波数を上下させると、オーディオ データの認識ピッチが変化する。このメソッドはバッファのフォーマットには影響を及ぼさない。

このメソッドはプライマリ サウンド バッファには有効ではない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSound::CreateSoundBuffer、IDirectSoundBuffer::GetFrequency、IDirectSoundBuffer::Play、IDirectSoundBuffer::SetFormat


IDirectSoundBuffer::SetPan

IDirectSoundBuffer::SetPan メソッドは、左右のチャンネルの相対ボリュームを設定する。

HRESULT SetPan(
  LONG lPan
);

パラメータ

lPan
左右のチャンネルの相対ボリューム。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

LPan の値は DSBPAN_LEFT から DSBPAN_RIGHT の範囲で、100 分の 1 デシベル (dB) 単位で測定される。現在これらの値は、dsound.h 内でそれぞれ 10,000、-10,000 と定義されている。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値は DSBPAN_CENTER であり、0 と定義されている。lplPan が 0 であるとき、両方のチャンネルが最大ボリュームであることを意味する (どちらも 0 dB の減衰である)。DSBPAN_CENTER 以外の値はどれも、一方が最大ボリュームでもう一方が減衰していることを意味する。

パンの値が -2,173 のとき、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様にパンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。DSBPAN_LEFT のパンは、右チャンネルが無音で、サウンドが左からのみ発生していることを意味する。一方、DSBPAN_RIGHT のパンは、左チャンネルが無音で、サウンドが右からのみ発生していることを意味する。

パン コントロールの効果は、ボリューム コントロールに累積される。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::GetPan、IDirectSoundBuffer::GetVolume、IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::SetVolume

IDirectSoundBuffer::SetVolume メソッドは、サウンド バッファのボリュームを変更する。

HRESULT SetVolume(
  LONG lVolume
);

パラメータ

lVolume
このサウンド バッファで要求する新しいボリューム。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

ボリュームは 100 分の 1 デシベル (dB) 単位で指定される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。現在これらの値は、dsound.h 内でそれぞれ 0、-10,000 と定義されている。値 DSBVOLUME_MAX は、ストリーム本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。現在、DirectSound は増幅をサポートしていない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::GetPan、IDirectSoundBuffer::GetVolume、IDirectSoundBuffer::SetPan


IDirectSoundBuffer::Stop

IDirectSoundBuffer::Stop メソッドは、サウンド バッファの再生を停止する。

HRESULT Stop();

パラメータ

なし。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

セカンダリ サウンド バッファに対して IDirectSoundBuffer::Stop を呼び出すと、現在のバッファの位置が、直前に再生されたサンプルの直後のサンプルに設定される。これは、そのバッファに対して次に IDirectSoundBuffer::Play メソッドを呼び出すと、以前に再生を停止した場所から再生が再開されることを意味する。

DSSCL_WRITEPRIMARY レベルに設定されたアプリケーションがプライマリ サウンド バッファに対してこのメソッドを呼び出すと、このメソッドはバッファを停止し、現在のポジションを 0 (バッファの先頭) にリセットする。ほとんどのサウンド カードはバッファの先頭からのみ再生を行えるので、このような処理が必要である。

しかし、書き込み優先以外の協調レベルに設定されているアプリケーションが、プライマリ バッファに対して IDirectSoundBuffer::Stop を呼び出した場合は、このメソッドは IDirectSoundBuffer::Play とは逆のエフェクトをもたらすだけである。セカンダリ バッファが再生されていない場合はプライマリ バッファを停止するように設定する。このアプリケーションまたは他のアプリケーションが他のバッファを再生している場合、それらの再生が停止するまでプライマリ バッファも実際には停止しない。たとえ振幅が 0 dB であっても、バッファがサウンド データを再生している場合は処理のオーバーヘッドが発生するので、このメソッドを使ってプライマリ バッファを停止することは役に立つ。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::Play


IDirectSoundBuffer::Unlock

IDirectSoundBuffer::Unlock メソッドは、サウンド バッファをアンロックする。

HRESULT Unlock(
  LPVOID lpvAudioPtr1,
  DWORD dwAudioBytes1,
  LPVOID lpvAudioPtr2,
  DWORD dwAudioBytes2
);

パラメータ

lpvAudioPtr1
IDirectSoundBuffer::Lock メソッドの lplpvAudioPtr1 パラメータで取得した値のアドレス。
dwAudioBytes1
lpvAudioPtr1 パラメータに実際に書き込まれたバイト数。IDirectSoundBuffer::Lock メソッドが返したバイト数以下とすべきである。
lpvAudioPtr2
IDirectSoundBuffer::Lock メソッドの lplpvAudioPtr2 パラメータで取得した値のアドレス。
dwAudioBytes2
lpvAudioPtr2 パラメータに実際に書き込まれたバイト数。IDirectSoundBuffer::Lock メソッドが返したバイト数以下とすべきである。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

アプリケーションは、IDirectSoundBuffer::Lock と IDirectSoundBuffer::Unlock を正しく組み合わせて、IDirectSoundBuffer::Lock メソッドが返したポインタ lpvAudioPtr1 と lpvAudioPtr2 の両方を IDirectSoundBuffer::Unlock に渡さなければならない。たとえ 2 番目のポインタに 0 バイトが書き込まれた場合でも、2 番目のポインタは必要である。

アプリケーションは 2 つのポインタに実際に書き込まれたバイト数を、dwAudioBytes1 と dwAudioBytes2 の各パラメータに渡さなければならない。

サウンド バッファのロック状態を長時間維持しないよう注意すること。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBuffer、IDirectSoundBuffer::GetCurrentPosition、IDirectSoundBuffer::Lock


IDirectSoundCapture インターフェイス

IDirectSoundCapture インターフェイスのメソッドは、サウンド キャプチャ バッファを作成するために使われる。

DirectSoundCaptureCreate 関数を使ってこのインターフェイスを取得する。

IDirectSoundCapture インターフェイスのメソッドは、以下のグループにまとめることができる。

作成 | CreateCaptureBuffer
 | Initialize
能力 | GetCaps

すべての COM インターフェイスと同様に、IDirectSoundCapture インターフェイスも IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTURE 型は、IDirectSoundCapture インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundCapture    *LPDIRECTSOUNDCAPTURE;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCapture::CreateCaptureBuffer

IDirectSoundCapture::CreateCaptureBuffer メソッドは、キャプチャ バッファを作成する。

出力の目的で複数のサウンドを 1 つのサウンドにミキシングできる DirectSound とは異なり、DirectSoundCapture はその逆、つまり 1 つの入力サウンドから複数のサウンドを抽出することはできない。DirectSoundCapture の最初のバージョンは、1 つのキャプチャ デバイスに対して、どの時点でも 1 つのキャプチャ バッファの存在しか認めていない。

HRESULT CreateCaptureBuffer(
  LPDSCBUFFERDESC lpDSCBufferDesc,
  LPLPDIRECTSOUNDCAPTUREBUFFER lplpDirectSoundCaptureBuffer,
  LPUNKNOWN pUnkOuter
);

パラメータ

lpDSCBufferDesc
DSCBUFFERDESC 構造体へのポインタ。この構造体は、作成されるキャプチャ バッファ用の値を保持している。
lplpDirectSoundCaptureBuffer
成功の場合、IDirectSoundCaptureBuffer インターフェイス ポインタのアドレス。
pUnkOuter
全体の IUnknown のコントロール。この値は NULL でなければならない。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_BADFORMAT
DSERR_GENERIC
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCapture::GetCaps

IDirectSoundCapture::GetCaps メソッドは、キャプチャ デバイスの能力を取得する。

HRESULT GetCaps(
  LPDSCCAPS lpDSCCaps
);

パラメータ

lpDSCCaps
DSCCAPS 構造体へのポインタ。キャプチャ デバイスは、この構造体に書き込みを行う。このメソッドを呼び出すには、dwSize メンバは構造体のサイズをバイト単位で指定しなければならない。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCapture::Initialize

CoCreateInstance を使って DirectSoundCapture オブジェクトを作成した場合、IDirectSoundCapture::Initialize メソッドを使ってこのオブジェクトを初期化しなければならない。DirectSoundCaptureCreate 関数を使用してオブジェクトを作成した場合は、このメソッドを呼び出す必要はない。

HRESULT Initialize(
  LPCGUID lpcGuid
);

パラメータ

lpcGuid
DirectSoundCapture オブジェクトに結合されるサウンド ドライバを指定する GUID のアドレス。プライマリ サウンド ドライバを選択するには、NULL または GUID_NULL を指定する。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_ALREADYINITIALIZED

注意

lpcGuid パラメータは、DirectX 7.0 で LPGUID から LPCGUID に変更された。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer インターフェイス

IDirectSoundCaptureBuffer インターフェイスのメソッドは、サウンド キャプチャ バッファを操作するために使われる。

IDirectSoundCapture::CreateCaptureBuffer メソッドを呼び出してこのインターフェイスを取得する。

IDirectSoundCaptureBuffer インターフェイスのメソッドは、以下のグループにまとめることができる。

初期化 | Initialize
情報 | GetCaps
 | GetCurrentPosition
 | GetFormat
 | GetStatus
キャプチャ管理 | Lock
 | Start
 | Stop
 | Unlock

すべての COM インターフェイスと同様に、IDirectSoundCaptureBuffer インターフェイスも IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTUREBUFFER 型は、IDirectSoundCaptureBuffer インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundCaptureBuffer  *LPDIRECTSOUNDCAPTUREBUFFER;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer::GetCaps

IDirectSoundCaptureBuffer::GetCaps メソッドは、DirectSound キャプチャ バッファの能力を返す。

HRESULT GetCaps(
  LPDSCBCAPS lpDSCBCaps
);

パラメータ

lpDSCBCaps
DSCBCAPS 構造体へのポインタ。キャプチャ バッファは、この構造体に書き込みを行う。入力時に、dwSize メンバは構造体のサイズをバイト単位で指定しなければならない。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer::GetCurrentPosition

IDirectSoundCaptureBuffer::GetCurrentPosition メソッドは、バッファ内の現在のキャプチャ位置と読み込み位置を取得する。

キャプチャ位置は、読み込み位置より前方にある。物理デバイスまたはホストがキャプチャ データをバッファリングする可能性があるので、これらの位置は常に同一になるとは限らない。読み込み位置より後でキャプチャ位置より前のデータは (キャプチャ位置を含む)、必ずしも有効なデータとは限らない。

HRESULT GetCurrentPosition(
  LPDWORD lpdwCapturePosition,
  LPDWORD lpdwReadPosition
);

パラメータ

lpdwCapturePosition
DirectSoundCaptureBuffer オブジェクト内の現在のキャプチャ位置を受け取る変数のアドレス。この位置は、キャプチャ バッファ内のオフセットであり、バイト単位で指定する。呼び出し側がこの位置情報に関心がない場合には、この値を NULL にできる。
lpdwReadPosition
DirectSoundCaptureBuffer オブジェクト内で、安全にデータを読み込める現在位置を受け取る変数のアドレス。この位置は、キャプチャ バッファ内のオフセットであり、バイト単位で指定する。呼び出し側がこの位置情報に関心がない場合には、この値を NULL にできる。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer::GetFormat

IDirectSoundCaptureBuffer::GetFormat メソッドは、サウンド キャプチャ バッファの現在のフォーマットを取得する。

HRESULT GetFormat(
  LPWAVEFORMATEX lpwfxFormat,
  DWORD dwSizeAllocated,
  LPDWORD lpdwSizeWritten
);

パラメータ

lpwfxFormat
WAVEFORMATEX 変数のアドレス。この変数は、キャプチャ バッファ内のサウンド データの記述を保持している。フォーマットの記述を保持するのに必要なバッファ サイズを取得するには NULL を指定する。この場合、lpdwSizeWritten パラメータが指す DWORD が、完全なフォーマット情報を受け取るのに必要な構造体のサイズを受け取る。
dwSizeAllocated
WAVEFORMATEX 構造体のサイズ。単位はバイト。DirectSoundCapture が構造体へ書き込むバイト数は、最大で dwSizeAllocated バイトである。構造体がそれより多くのメモリを必要とする場合、切り捨てが行われる。
lpdwSizeWritten
WAVEFORMATEX 構造体に書き込まれたバイト数を受け取る変数のアドレス。このパラメータは NULL にしてもよい。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer::GetStatus

IDirectSoundCaptureBuffer::GetStatus メソッドは、サウンド キャプチャ バッファの現在のステータスを取得する。

HRESULT GetStatus(
  DWORD *lpdwStatus
);

パラメータ

lpdwStatus
キャプチャ バッファのステータスを保持する変数のアドレス。ステータスとして、以下の値の 1 つまたは複数を設定できる。
DSCBSTATUS_CAPTURING
バッファは現在オーディオ データをキャプチャしている。
DSCBSTATUS_LOOPING
バッファは現在ループしている。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer::Initialize

IDirectSoundCaptureBuffer::Initialize メソッドは、DirectSoundCaptureBuffer オブジェクトがまだ初期化されていない場合、このオブジェクトを初期化する。

HRESULT Initialize(
  LPDIRECTSOUNDCAPTURE lpDirectSoundCapture,
  LPCDSCBUFFERDESC lpcDSCBufferDesc
);

パラメータ

lpDirectSoundCapture
DirectSoundCaptureBuffer オブジェクトに関連付けられた DirectSoundCapture オブジェクトのアドレス。
lpcDSCBufferDesc
このサウンド バッファを初期化するために使われる値を保持する DSBUFFERDESC 構造体のアドレス。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

注意

IDirectSoundCapture::CreateCaptureBuffer メソッドは内部で IDirectSoundCaptureBuffer::Initialize メソッドを呼び出すので、現在のリリースの DirectSound では Initialize を明示的に呼び出す必要はない。Initialize メソッドは将来の拡張性に備えて用意されている。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

DSBUFFERDESC、IDirectSoundCapture::CreateCaptureBuffer


IDirectSoundCaptureBuffer::Lock

IDirectSoundCaptureBuffer::Lock メソッドは、バッファをロックする。バッファをロックすると、そのバッファへのポインタが返され、アプリケーションがそのメモリに対してオーディオ データを読み書きできるようになる。

HRESULT Lock(
  DWORD dwReadCursor,
  DWORD dwReadBytes,
  LPVOID *lplpvAudioPtr1,
  LPDWORD lpdwAudioBytes1,
  LPVOID *lplpvAudioPtr2,
  LPDWORD lpdwAudioBytes2,
  DWORD dwFlags
);

パラメータ

dwReadCursor
バッファの先頭からロック開始位置までのオフセット。単位はバイト。
dwReadBytes
ロックされるバッファ部分のサイズ。単位はバイト。サウンド キャプチャ バッファは概念的には循環バッファである点に注意すること。
lplpvAudioPtr1
ロックされるサウンド キャプチャ バッファの最初のブロックを保持するポインタのアドレス。
lpdwAudioBytes1
lplpvAudioPtr1 パラメータが指すバイト数を保持する変数のアドレス。この値が、dwReadBytes パラメータより小さい場合、lplpvAudioPtr2 は 2 番目のデータ ブロックを指す。
lplpvAudioPtr2
ロックされるサウンド キャプチャ バッファの 2 番目のブロックを保持するポインタのアドレス。このパラメータの値が NULL の場合、lplpvAudioPtr1 パラメータはサウンド キャプチャ バッファのロックされた部分全体を指す。
lpdwAudioBytes2
lplpvAudioPtr2 パラメータが指すバイト数を保持する変数のアドレス。lplpvAudioPtr2 が NULL の場合、この値は 0 になる。
dwFlags
ロックイベントに変更を加えるフラグ。この値は NULL または次のフラグである。
DSCBLOCK_ENTIREBUFFER
dwReadBytes パラメータを無視し、キャプチャ バッファ全体をロックする。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

注意

このメソッドは、オフセットとバイト カウントを受け取り、2 つの読み込みポインタとそれぞれに関連するサイズを返す。サウンド キャプチャ バッファが循環するため、2 つのポインタが必要である。ロックされたバイトがバッファの最後からラップ アラウンドしない (先頭へ戻らない) 場合、2 番目のポインタである lplpvAudioBytes2 は NULL になる。ただし、バイトがラップ アラウンドする場合は、2 番目のポインタはバッファの先頭を指す。

アプリケーションが lplpvAudioPtr2 と lpdwAudioBytes2 の各パラメータに NULL を渡すと、DirectSoundCapture は、バッファのラップアラウンド部分をロックしない。

アプリケーションは、IDirectSoundCaptureBuffer::Lock メソッドが返したポインタからデータを読み込み、IDirectSoundCaptureBuffer::Unlock メソッドを呼び出し、バッファを解放して DirectSoundCapture に返すべきである。サウンド バッファは長時間にわたってロックすべきではない。長時間のロックを行うと、キャプチャ カーソルがロックされたバイトに達してしまい、機器構成に依存するオーディオの問題が発生することがある。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer::Start

IDirectSoundCaptureBuffer::Start メソッドは、キャプチャ バッファをキャプチャ状態に置き、バッファへのデータのキャプチャリングを開始する。キャプチャ バッファが既にキャプチャ状態にある場合には、このメソッドは何もしない。

HRESULT Start(
  DWORD dwFlags
);

パラメータ

dwFlags
サウンド データをキャプチャリングするときのキャプチャ バッファの動作を指定するフラグ。次のフラグが定義されている。
DSCBSTART_LOOPING
バッファの最後に達したら、先頭からキャプチャを再開し、明示的に停止されるまで続行する。

戻り値

成功すればDS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer::Stop

IDirectSoundCaptureBuffer::Stop メソッドは、キャプチャ バッファを「停止」状態に置き、データのキャプチャを停止する。キャプチャ バッファが既に停止状態にある場合は、このメソッドは何もしない。

HRESULT Stop();

パラメータ

なし。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_NODRIVER
DSERR_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundCaptureBuffer::Unlock

IDirectSoundCaptureBuffer::Unlock メソッドは、バッファをアンロックする。

HRESULT Unlock(
  LPVOID lpvAudioPtr1,
  DWORD dwAudioBytes1,
  LPVOID lpvAudioPtr2,
  DWORD dwAudioBytes2
);

パラメータ

lpvAudioPtr1
IDirectSoundCaptureBuffer::Lock メソッドの lplpvAudioPtr1 パラメータで取得した値のアドレス。
dwAudioBytes1
lpvAudioPtr1 パラメータから実際に読み込まれたバイト数。IDirectSoundCaptureBuffer::Lock メソッドが返したバイト数以下とすべきである。
lpvAudioPtr2
IDirectSoundCaptureBuffer::Lock メソッドの lplpvAudioPtr2 パラメータで取得した値のアドレス。
dwAudioBytes2
lpvAudioPtr2 パラメータから実際に読み込まれたバイト数。IDirectSoundCaptureBuffer::Lock メソッドが返したバイト数以下とすべきである。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

注意

アプリケーションは、IDirectSoundCaptureBuffer::Lock と IDirectSoundCaptureBuffer::Unlock を正しく組み合わせて、IDirectSoundCaptureBuffer::Lock メソッドが返した 2 つのポインタ lpvAudioPtr1 と lpvAudioPtr2 の両方を IDirectSoundCaptureBuffer::Unlock に渡さなければならない。たとえ 2 番目のポインタに 0 バイトが書き込まれた場合でも、2 番目のポインタは必要である。

アプリケーションは 2 つのポインタに実際に書き込まれたバイト数を、dwAudioBytes1 と dwAudioBytes2 の各パラメータに渡さなければならない。

サウンド キャプチャ バッファのロック状態を長時間維持しないよう注意すること。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundNotify インターフェイス

IDirectSoundNotify インターフェイスは、再生バッファやキャプチャ バッファの通知イベントを設定するメカニズムを提供する。

DirectSoundBuffer オブジェクト上の既存のインターフェイスに対して QueryInterface メソッドを呼び出して、このインターフェイスを取得する。具体的な例については、「再生バッファの通知」を参照すること。

IDirectSoundNotify インターフェイスは、次のメソッドをサポートする。

SetNotificationPositions

すべての COM インターフェイスと同様に、IDirectSoundNotify インターフェイスも IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDNOTIFY 型は、IDirectSoundNotify インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundNotify    *LPDIRECTSOUNDNOTIFY;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IDirectSoundNotify::SetNotificationPositions

IDirectSoundCaptureBuffer::SetNotificationPositions メソッドは通知位置を設定する。キャプチャや再生の間、呼び出し側が供給した配列内の DSBPOSITIONNOTIFY 構造体のいずれかで指定されているオフセットにキャプチャ位置が達すると、関連するイベントがシグナル送信される。再生時にはカレント プレイ ポジションを追跡する。キャプチャ時には現在の読み込み位置を追跡する。

HRESULT SetNotificationPositions(
  DWORD cPositionNotifies,
  LPCDSBPOSITIONNOTIFY lpcPositionNotifies
);

パラメータ

cPositionNotifies
DSBPOSITIONNOTIFY 構造体の数。
lpcPositionNotifies
DSBPOSITIONNOTIFY 構造体から成る配列へのポインタ。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY

注意

dwOffset メンバで値 DSBPN_OFFSETSTOP を指定すると、IDirectSoundBuffer::Stop や IDirectSoundCaptureBuffer::Stop メソッドを呼び出したとき、またはバッファの最後に達してループ再生を行わないときに、関連イベントをシグナル送信するよう DirectSound に指示できる。この値を使うときは、位置通知配列の最後の項目とすべきである。

位置通知配列が既に設定されている場合、この関数をもう一度呼び出すと以前の位置通知配列が置き換えられる。

このメソッドを呼び出すときは、バッファを停止させなければならない。

注 : VxD ドライバでは、サウンド バッファが DSBCAPS_CTRLPOSITIONNOTIFY で作成される場合、このバッファは常にソフトウェア バッファになる。これは、VxD ドライバ モデルが通知インターフェイスをサポートしないためである。ハードウェアが利用可能な場合は、WDM ドライバにより、位置通知可能なバッファがハードウェアに存在することがある。

ボイス管理の TERMINATEBY フラグと共に LOC_DEFER と NOTIFY を使用している場合、まだ到達せず、通知設定を保持するサウンドは、ボイス管理によって終了されることもある。この場合、通知イベントは発生しない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


IKsPropertySet インターフェイス

IKsPropertySet インターフェイスは、WDM KS (Win32® driver model kernel streaming、Win32® ドライバ モデルのカーネル ストリーミング) アーキテクチャの一部である。ドライバはこのインターフェイスを使うことにより、API に拡張を加えることなく、利用できる拡張機能を提供することが可能になる。DirectSound は、サウンド ドライバのプロパティにアクセスできるよう、このインターフェイスをサポートする。

DirectSound バッファの任意のインターフェイスの QueryInterface メソッドを呼び出して、このインターフェイスを取得する。

IKsPropertySet インターフェイスは、次のメソッドをサポートする。

IKsPropertySet | Get
 | QuerySupport
 | Set

すべての COM インターフェイスと同様に、IKsPropertySet インターフェイスも IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


IKsPropertySet::Get

IKsPropertySet::Get メソッドは、プロパティ セット内の特定の項目に対応するデータを取り出す。

HRESULT Get(
  REFGUID rguidPropSet,
  ULONG ulId,
  LPVOID pInstanceData,
  ULONG ulInstanceLength,
  LPVOID pPropertyData,
  ULONG ulDataLength,
  ULONG * pulBytesReturned
);

パラメータ

rguidPropSet
アクセスすべきプロパティ セットを表す GUID への参照 (C++) またはアドレス (C)。
ulId
アクセスすべきプロパティ セット内の項目。項目は 0 から始まるインデックス番号を割り当てられており、特定のプロパティ セット GUID では常に同じである。
pInstanceData
Get 呼び出しの対象となるインスタンス データ。
ulInstanceLength
pInstanceData が指すバイト数。
pPropertyData
この項目から取得されるデータ。
ulDataLength
pPropertyData が指すバイト数。
pulBytesReturned
pPropertyData に書き込まれたバイト数を受け取る変数のアドレス。

戻り値

戻り値は、プロパティ セットの設計者によって決定される。

成功すれば S_OK、失敗すれば E_POINTER を返す。

注意

pInstanceData と pPropertyData の各データのフォーマットは、項目ごとに異なる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


IKsPropertySet::QuerySupport

IKsPropertySet::QuerySupport メソッドは、プロパティ セット内のあるプロパティがポートまたはデバイスによってサポートされているかどうかを決定する。

HRESULT QuerySupport(
  REFGUID rguidPropSet,
  ULONG ulId,
  ULONG* pulTypeSupport
);

パラメータ

rguidPropSet
問い合わせるべきプロパティ セットを表す GUID への参照 (C++) またはアドレス (C)。
ulId
アクセスすべきプロパティ セット内の項目。項目は 0 から始まるインデックス番号を割り当てられており、特定のプロパティ セット GUID では常に同じである。
pulTypeSupport
プロパティのサポートに関する情報を受け取る変数のアドレス。プロパティまたはプロパティ セットが存在しない場合、この値は 0 に設定される。それ以外の場合は、以下のフラグの 1 つまたは両方を保持する。
KSPROPERTY_SUPPORT_GET
プロパティ項目は取得できる。
KSPROPERTY_SUPPORT_SET
プロパティ項目は設定できる。

戻り値

戻り値は、プロパティ セットの設計者によって決定される。

成功すれば S_OK (「注意」を参照すること)、失敗すれば次のエラー値のいずれかを返す。

E_NOTIMPL (「注意」を参照)
E_POINTER

注意

セット内で特定のプロパティをサポートするかどうかは、プロパティ セットの定義に依存する。関心のあるプロパティ セットについては、ハードウェア メーカーの仕様を参照すること。

ある仕様ではプロパティがサポートされていない場合に S_OK を返し、他の仕様では E_NOTIMPL を返す。プロパティがサポートされているかどうかを確認するには、このメソッドの戻り値と、pulTypeSupport の戻り値の両方をチェックすべきである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


IKsPropertySet::Set

IKsPropertySet::Set メソッドは、プロパティ セット内の特定のプロパティの値を設定する。

HRESULT Set(
  REFGUID rguidPropSet,
  ULONG ulId,
  LPVOID pInstanceData,
  ULONG ulInstanceLength,
  LPVOID pPropertyData,
  ULONG ulDataLength
);

パラメータ

rguidPropSet
アクセスすべきプロパティ セットを表す GUID への参照 (C++) またはアドレス (C)。
ulId
アクセスすべきプロパティ セット内の項目。項目は 0 から始まるインデックス番号を割り当てられており、特定のプロパティ セット GUID では常に同じである。
pInstanceData
Set 呼び出しの対象となるインスタンス データ。この操作を実行できるオブジェクトがポート内に複数存在する場合、インスタンス データはどのオブジェクトを使うべきかを指定する。DirectMusic® API レベルでは、標準的なプロパティ セットのどの項目もインスタンス データを使っていない。しかし、ベンダーが定義した拡張では、インスタンス データを自由に使ってよい。
ulInstanceLength
pInstanceData が指すバイト数。
pPropertyData
この項目に設定されるプロパティ データ。
ulDataLength
pPropertyData が指すバイト数。

戻り値

戻り値は、プロパティ セットの設計者によって決定される。

成功すれば S_OK、失敗すれば E_POINTER を返す。

注意

pInstanceData と pPropertyData の各データのフォーマットは、項目ごとに異なる。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


関数

ここでは、DirectSound と DirectSoundCapture の以下のグローバル関数のリファレンス情報を提供する。

  • DirectSoundCaptureCreate
  • DirectSoundCaptureEnumerate
  • DirectSoundCreate
  • DirectSoundEnumerate


DirectSoundCaptureCreate

DirectSoundCaptureCreate 関数は、IDirectSoundCapture インターフェイスをサポートするオブジェクトの作成と初期化を行う。

HRESULT WINAPI DirectSoundCaptureCreate(
  LPCGUID lpcGUID,
  LPDIRECTSOUNDCAPTURE *lplpDSC,
  LPUNKNOWN pUnkOuter
);

パラメータ

lpcGUID
サウンド キャプチャ デバイスを識別する GUID のアドレス。このパラメータの値は、DirectSoundCaptureEnumerate が返した GUID のいずれか、またはデフォルトのデバイスを指定する NULL でなければならない。
lplpDSC
この関数が作成した DirectSoundCapture オブジェクトへのポインタのアドレス。
pUnkOuter
全体の未定義のコントロール。この値は NULL でなければならない。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY

注意

全二重をサポートしないサウンド カードでは、このメソッドは失敗し、DSERR_ALLOCATED を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


DirectSoundCaptureEnumerate

DirectSoundCaptureEnumerate 関数は、システムにインストールされている DirectSoundCapture オブジェクトを列挙する。

HRESULT WINAPI DirectSoundCaptureEnumerate(
  LPDSENUMCALLBACK lpDSEnumCallback,
  LPVOID lpContext
);

パラメータ

lpDSEnumCallback
DSEnumCallback 関数のアドレス。この関数は、システムにインストールされている各 DirectSoundCapture オブジェクトに対して呼び出される。
lpContext
ユーザー定義コンテキストのアドレス。列挙型コールバック関数を呼び出すたびに、その関数にこのコンテキストが渡される。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


DirectSoundCreate

DirectSoundCreate 関数は、IDirectSound インターフェイスの作成と初期化を行う。

HRESULT WINAPI DirectSoundCreate(
  LPCGUID lpcGuid,
  LPDIRECTSOUND * ppDS,
  LPUNKNOWN  pUnkOuter
);

パラメータ

lpcGuid
サウンド デバイスを識別する GUID のアドレス。このパラメータの値は DirectSoundEnumerate が返した GUID のいずれか、またはデフォルトのデバイスを指定する NULL でなければならない。
ppDS
この関数が作成した DirectSound オブジェクトへのポインタのアドレス。
pUnkOuter
全体の未定義のコントロール。この値は NULL でなければならない。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_NODRIVER
DSERR_OUTOFMEMORY

注意

アプリケーションは DirectSound オブジェクトを作成した直後に、IDirectSound::SetCooperativeLevel メソッドを呼び出さなければならない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound::GetCaps、IDirectSound::SetCooperativeLevel


DirectSoundEnumerate

DirectSoundEnumerate 関数は、システムにインストールされている DirectSound ドライバを列挙する。

HRESULT WINAPI DirectSoundEnumerate(
  LPDSENUMCALLBACK lpDSEnumCallback,
  LPVOID lpContext
);

パラメータ

lpDSEnumCallback
DSEnumCallback 関数のアドレス。この関数は、システムにインストールされている各 DirectSound オブジェクトに対して呼び出される。
lpContext
ユーザー定義コンテキストのアドレス。列挙型コールバック関数を呼び出すたびに、その関数にこのコンテキストが渡される。

戻り値

成功すれば DS_OK、失敗すれば DSERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

DSEnumCallback


コールバック関数

ここでは、DirectSound コールバック関数のリファレンス情報を提供する。

  • DSEnumCallback


DSEnumCallback

DSEnumCallback は、DirectSound ドライバを列挙するアプリケーション定義コールバック関数である。アプリケーションが直前に呼び出した DirectSoundEnumerate 関数または DirectSoundCaptureEnumerate 関数に応答して、システムはこの関数を呼び出す。

BOOL CALLBACK DSEnumCallback(
  LPGUID lpGuid,
  LPCSTR lpcstrDescription,
  LPCSTR lpcstrModule,
  LPVOID lpContext
);

パラメータ

lpGuid
列挙中の DirectSound ドライバを識別する GUID のアドレス。この値を DirectSoundCreate 関数に渡すと、ドライバの DirectSound オブジェクトを作成できる。
lpcstrDescription
DirectSound デバイスのテキスト記述を提供する、NULL で終わる文字列のアドレス。
lpcstrModule
このデバイスに対応する DirectSound ドライバのモジュール名を指定する、NULL で終わる文字列のアドレス。
lpContext
アプリケーション定義データのアドレス。このデータは、各コールバック関数へ渡される。

戻り値

ドライバの列挙が続行する場合は TRUE、終了する場合は FALSE を返す。

注意

アプリケーションは lpstrDescription と lpstrModule の各パラメータに渡された文字列を、ヒープから割り当てられたメモリにコピーすることにより、これらの文字列を保存できる。文字列をこのコールバック関数へ渡すのに使われたメモリは、このコールバック関数が実行中のときにのみ有効になる。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。
インポート ライブラリ : ユーザー定義。

参照

DirectSoundEnumerate


構造体

ここでは、DirectSound が使う以下の構造体のリファレンス情報を提供する。

  • DS3DBUFFER
  • DS3DLISTENER
  • DSBCAPS
  • DSBPOSITIONNOTIFY
  • DSBUFFERDESC
  • DSBUFFERDESC1
  • DSCAPS
  • DSCBCAPS
  • DSCBUFFERDESC
  • DSCCAPS

注 : すべての DirectX 構造体用のメモリは、使用前に初期化しなければならない。加えて、dwSize メンバを保持する構造体では、使用前にそのメンバを構造体のバイト単位のサイズに設定しなければならない。次の例は、よく使われる構造体 DSCAPS に対してこれらの処理を実行する。

DSCAPS dscaps; // まだこの構造体は利用できない。

ZeroMemory(&dscaps, sizeof(dscaps));
dscaps.dwSize = sizeof(dscaps);

// これでこの構造体が利用可能になった。
.
.


DS3DBUFFER

DS3DBUFFER 構造体は、3D サウンド バッファの位置、方向、動作を一意に記述するために必要なすべての情報を保持している。この構造体は、IDirectSound3DBuffer::GetAllParameters と IDirectSound3DBuffer::SetAllParameters の各メソッドと共に使われる。

typedef struct {
    DWORD      dwSize;
    D3DVECTOR  vPosition;
    D3DVECTOR  vVelocity;
    DWORD      dwInsideConeAngle;
    DWORD      dwOutsideConeAngle;
    D3DVECTOR  vConeOrientation;
    LONG       lConeOutsideVolume;
    D3DVALUE   flMinDistance;
    D3DVALUE   flMaxDistance;
    DWORD      dwMode;
} DS3DBUFFER, *LPDS3DBUFFER;

typedef const DS3DBUFFER *LPCDS3DBUFFER;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
vPosition
3D サウンド バッファの現在の位置を記述する D3DVECTOR 構造体。
vVelocity
3D サウンド バッファの現在の速度を記述する D3DVECTOR 構造体。
dwInsideConeAngle
内側サウンド プロジェクション コーンの角度。
dwOutsideConeAngle
外側サウンド プロジェクション コーンの角度。
vConeOrientation
この 3D サウンド バッファ プロジェクション コーンの現在の方向を記述する D3DVECTOR 構造体。
lConeOutsideVolume
コーン外部ボリューム。
flMinDistance
最小距離。
flMaxDistance
最大距離。
dwMode
設定される 3D サウンド処理モード。
DS3DMODE_DISABLE
3D サウンド処理は無効になる。サウンドはリスナーの頭の中心で発生しているように聞こえる。
DS3DMODE_HEADRELATIVE
サウンド パラメータ (位置、速度、方向) はリスナーのパラメータに対する相対的なものである。このモードでは、リスナーのパラメータが変化したときにサウンドの絶対パラメータは自動的に更新されるので、相対パラメータは一定に保たれる。
DS3DMODE_NORMAL
標準の処理。これはデフォルトのモードである。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


DS3DLISTENER

DS3DLISTENER 構造体は、3D ワールド パラメータとリスナーの位置を一意に記述するために必要なすべての情報を保持している。この構造体は、IDirectSound3DListener::GetAllParameters と IDirectSound3DListener::SetAllParameters の各メソッドと共に使われる。

typedef struct {
    DWORD      dwSize;
    D3DVECTOR  vPosition;
    D3DVECTOR  vVelocity;
    D3DVECTOR  vOrientFront;
    D3DVECTOR  vOrientTop;
    D3DVALUE   flDistanceFactor;
    D3DVALUE   flRolloffFactor;
    D3DVALUE   flDopplerFactor;
} DS3DLISTENER, *LPDS3DLISTENER;

typedef const DS3DLISTENER *LPCDS3DLISTENER;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
vPosition、vVelocity、vOrientFront、vOrientTop
リスナーの位置、速度、前方向、上方向のそれぞれを記述する D3DVECTOR 構造体。
flDistanceFactor、flRolloffFactor、flDopplerFactor
それぞれ現在の距離係数、ロールオフ係数、ドップラー係数。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


DSBCAPS

DSBCAPS 構造体は DirectSound バッファ オブジェクトの能力を指定する。IDirectSoundBuffer::GetCaps メソッドで使われる。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwBufferBytes;
    DWORD  dwUnlockTransferRate;
    DWORD  dwPlayCpuOverhead;
} DSBCAPS, *LPDSBCAPS;

typedef const DSBCAPS *LPCDSBCAPS;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
バッファ オブジェクトの能力を指定するフラグ。
DSBCAPS_CTRL3D
バッファは 3D コントロール能力を備えている。
DSBCAPS_CTRLFREQUENCY
バッファは周波数コントロール能力を備えている。
DSBCAPS_CTRLPAN
バッファはパン コントロール能力を備えている。
DSBCAPS_CTRLVOLUME
バッファはボリューム コントロール能力を備えている。
DSBCAPS_CTRLPOSITIONNOTIFY
バッファは位置通知能力を備えている。VxD ドライバでは、このフラグで作成されたサウンド バッファは常にソフトウェア バッファになる。これは、VxD ドライバ モデルが通知をサポートしないためである。ハードウェアが利用可能な場合は、WDM ドライバにより、通知可能なバッファがハードウェアに存在することがある。このフラグは、DSBPLAY_LOCHARDWARE フラグが IDirectSoundBuffer::Play メソッドに渡された場合に、メソッドが失敗する原因となる。
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer::GetCurrentPosition では、再生カーソルの新しい動作を使うべきである。DirectX 1 の DirectSound では、エミュレートされたサウンド カード上で再生カーソルは実際に再生されているサウンドよりはるかに前方にあり、書き込みカーソルの直後に置かれていた。以後のバージョンでは、DSBCAPS_GETCURRENTPOSITION2 フラグを指定すると、アプリケーションはより正確な再生位置を取得できる。このフラグを指定しない場合、互換性を保つ目的で以前の動作が維持される。このフラグは、エミュレートされたサウンド カードにのみ影響を及ぼす。DirectSound ドライバが存在する場合、DirectX のどのバージョンでも、DirectSound の再生カーソルは正確な位置を示す。
DSBCAPS_GLOBALFOCUS
このバッファはグローバルなサウンド バッファである。このフラグを設定すると、ユーザーが他のアプリケーションにフォーカスを移動し、その新しいアプリケーションが DirectSound を使う場合でも、DirectSound を使っているアプリケーションは引き続きそのバッファを再生できる。1 つの例外は、協調レベルで DSSCL_WRITEPRIMARY フラグを設定した DirectSound アプリケーションにフォーカスを移動した場合である。この場合、他のアプリケーションからのグローバルなサウンドは聞こえなくなる。
DSBCAPS_LOCDEFER
再生時、バッファはハードウェアまたはソフトウェアのリソースに割り当てられる。
DSBCAPS_LOCHARDWARE
バッファはハードウェア ミキシングを使う。
DSBCAPS_LOCSOFTWARE
バッファはソフトウェア メモリ内にあり、ソフトウェア ミキシングを使う。
DSBCAPS_MIXIN
バッファは他のバッファからの送信を受け取ることができる。
DSBCAPS_MUTE3DATMAXDISTANCE
サウンドは、最大距離で無音になる。最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないですむ。
DSBCAPS_PRIMARYBUFFER
このバッファはプライマリ サウンド バッファである。この値を指定しない場合、セカンダリ サウンド バッファが作成される。
DSBCAPS_STATIC
バッファはオンボード ハードウェア メモリにある。
DSBCAPS_STICKYFOCUS
バッファはスティッキー フォーカスを備えている。ユーザーが DirectSound を使っていない他のアプリケーションに切り替えた場合、バッファは引き続き音を出す。ただし、ユーザーが他の DirectSound アプリケーションに切り替えた場合、バッファは無音になる。
dwBufferBytes
このバッファのサイズ。単位はバイト。
dwUnlockTransferRate
IDirectSoundBuffer::Unlock を呼び出したときにデータをバッファ メモリに転送する速度。単位は 1 秒あたりのキロバイト (KB/s)。高性能のアプリケーションはこの値を使って、IDirectSoundBuffer::Unlock を実行するのに必要な時間を決定できる。システム メモリ内に配置されているソフトウェア バッファの場合、処理が不要なので転送速度は非常に高い。ハードウェア バッファの場合、バッファをサウンド カードにロードしなければならない可能性があるので、転送速度はより遅くなる可能性がある。その結果、転送速度が制限されることがある。
dwPlayCpuOverhead
処理のオーバーヘッド。これは、サウンド バッファをミキシングするのに必要なメイン処理サイクルのパーセンテージである。ハードウェア バッファの場合、サウンド デバイスがミキシングを行うので、このメンバは 0 である。ソフトウェア バッファの場合、このメンバの値はバッファ フォーマットとシステム プロセッサの速度に依存する。

注意

DSBCAPS 構造体は、IDirectSound::CreateSoundBuffer メソッドに渡される DSBUFFERDESC 構造体に似た情報と、それ以外のいくつかの追加情報を保持している。追加情報として、バッファの位置 (ハードウェアまたはソフトウェア) と、いくつかのコスト測定値、たとえば、バッファがハードウェアに配置されている場合はダウンロード時間、ソフトウェアでバッファをミキシングする場合は再生処理のオーバーヘッドなどが挙げられる。

注 : DSBCAPS 構造体の dwFlags メンバが保持するフラグは、DSBUFFERDESC 構造体で使われるフラグと同じものである。唯一の違いは、DSBCAPS 構造体ではバッファの場所に応じて DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらかが指定されることである。DSBUFFERDESC 構造体ではこれらのフラグはオプションであり、フラグの指定に応じて、バッファをハードウェアとソフトウェアのどちらかに強制的に配置できる。

DSBCAPS_CTRLPOSITIONNOTIFY フラグで作成されたサウンド バッファには、通知イベントを設定しなければならない。このフラグでサウンド バッファを作成し、何も通知を設定しないと、動作が定義されず、サウンドが 2 回再生されることがある。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。

参照

IDirectSound::CreateSoundBuffer、IDirectSoundBuffer::GetCaps


DSBPOSITIONNOTIFY

DSBPOSITIONNOTIFY 構造体は、IDirectSoundNotify::SetNotificationPositions メソッドによって使われる。

typedef struct {
    DWORD   dwOffset;
    HANDLE  hEventNotify;
} DSBPOSITIONNOTIFY, *LPDSBPOSITIONNOTIFY;

typedef const DSBPOSITIONNOTIFY *LPCDSBPOSITIONNOTIFY;

メンバ

dwOffset
バッファの先頭から、通知イベントがトリガされる場所までのオフセット、または DSBPN_OFFSETSTOP。
hEventNotify
指定のオフセットに達したときにシグナル送信されるイベントへのハンドル。

注意

dwOffset メンバ内で値 DSBPN_OFFSETSTOP が設定されている場合、再生またはキャプチャがバッファの最後に達した (そして再生またはキャプチャがループしていない) か、アプリケーションが IDirectSoundBuffer::Stop または IDirectSoundCaptureBuffer::Stop のどちらかのメソッドを呼び出したことが原因で、再生またはキャプチャが停止すると、イベントがシグナル送信される。

注 : ボイス管理の TERMINATEBY フラグと共に LOC_DEFER と NOTIFY を使用している場合、まだ到達せず、通知設定を保持するサウンドは、ボイス管理によって終了されることもある。この場合、通知イベントは発生しない。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


DSBUFFERDESC

DSBUFFERDESC 構造体は、新しい DirectSoundBuffer オブジェクトの特徴を示す。この構造体は、IDirectSound::CreateSoundBuffer メソッドによって使われる。

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
    GUID            guid3DAlgorithm;
} DSBUFFERDESC, *LPDSBUFFERDESC;

typedef const DSBUFFERDESC *LPCDSBUFFERDESC;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
新しい DirectSoundBuffer オブジェクトを作成するときに含める能力を識別するフラグ。以下のフラグが定義されている。「注意」を参照すること。
DSBCAPS_CTRL3D
バッファは 3D コントロール能力を備えていなければならない。
DSBCAPS_CTRLFREQUENCY
バッファは周波数コントロール能力を備えていなければならない。
DSBCAPS_CTRLPAN
バッファはパン コントロール能力を備えていなければならない。
DSBCAPS_CTRLPOSITIONNOTIFY
バッファは位置通知能力を備えていなければならない。VxD ドライバでは、サウンド バッファが DSBCAPS_CTRLPOSITIONNOTIFY で作成される場合、このバッファは常にソフトウェア バッファになる。ハードウェア バッファが利用可能な場合、WDM ドライバにより、通知可能なバッファがハードウェアに存在することがある。「注意」を参照すること。
DSBCAPS_CTRLVOLUME
バッファはボリューム コントロール能力を備えていなければならない。
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer::GetCurrentPosition では、再生カーソルの新しい動作を使うべきである。DirectX 1 の DirectSound では、エミュレートされたサウンド カード上で再生カーソルは実際に再生されているサウンドよりはるかに前方にあり、書き込みカーソルの直後に置かれていた。以後のバージョンでは、DSBCAPS_GETCURRENTPOSITION2 フラグを指定すると、アプリケーションはより正確な再生位置を取得できる。このフラグを指定していない場合、互換性を保つ目的で以前の動作が維持される。このフラグは、エミュレートされたサウンド カードにのみ影響を及ぼす。DirectSound ドライバが存在する場合、どのバージョンの DirectX でも DirectSound の再生カーソルは正確な位置を示す。
DSBCAPS_GLOBALFOCUS
このバッファはグローバルなサウンド バッファである。このフラグを設定すると、ユーザーが他のアプリケーションにフォーカスを移動し、その新しいアプリケーションが DirectSound を使う場合でも、DirectSound を使っているアプリケーションは引き続きそのバッファを再生できる。1 つの例外は、協調レベルで DSSCL_WRITEPRIMARY フラグを設定した DirectSound アプリケーションにフォーカスを移動した場合である。この場合、他のアプリケーションからのグローバルなサウンドは聞こえなくなる。
DSBCAPS_LOCDEFER
再生時、バッファはハードウェアまたはソフトウェアのリソースに割り当てられる。このフラグは、ボイス管理を使うバッファに設定されなければならない。
DSBCAPS_LOCHARDWARE
バッファはハードウェア ミキシングを使う。デバイスがハードウェア ミキシングをサポートしていない場合や、必要なハードウェア メモリが利用不可能な場合は、IDirectSound::CreateSoundBuffer メソッドの呼び出しは失敗する。アプリケーションは、このバッファがミキシング チャンネルを利用可能であると保証する必要がある。この状況は保証されていない。
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC が指定されていて、ハードウェア リソースが利用可能であっても、バッファをソフトウェア メモリに配置して、ソフトウェア ミキシングを使うようにする。
DSBCAPS_MUTE3DATMAXDISTANCE
サウンドは、最大距離で無音になる。最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないですむ。
DSBCAPS_PRIMARYBUFFER
このバッファはプライマリ サウンド バッファである。この値を指定しない場合、セカンダリ サウンド バッファが作成される。
DSBCAPS_STATIC
オンボード ハードウェア メモリが利用可能な場合、バッファはそこに置かれる。このようなメモリが利用できない場合、エラーは発生しない。これに対して DSBCAPS_LOCHARDWARE は、バッファを強制的にハードウェア メモリ (おそらく、ドライバがバッファのミキシングに使うシステム メモリ) に置くので、このようなメモリが利用できない場合はエラーを引き起こす。
DSBCAPS_STICKYFOCUS
バッファは、スティッキー フォーカスを持つことになる。ユーザーが DirectSound を使っていない他のアプリケーションに切り替えた場合、アプリケーションの標準バッファは無音になるが、スティッキー フォーカス バッファは引き続き音を出す。
dwBufferBytes
新しいバッファのサイズ。単位はバイト。プライマリ バッファを作成するときは、この値は 0 でなければならない。セカンダリ バッファで許容される最小サイズと最大サイズは、dsound.h 内で定義される DSBSIZE_MIN、DSBSIZE_MAX である。
dwReserved
このメンバは予約されている。
lpwfxFormat
このバッファのウェーブ フォーマットを指定する構造体のアドレス。プライマリ バッファでは、この値は NULL でなければならない。アプリケーションは IDirectSoundBuffer::SetFormat を使って、プライマリ バッファのフォーマットを設定できる。
guid3DAlgorithm
DirectSound3D HEL が使う二重スピーカの仮想アルゴリズムのユニーク識別子。サウンド バッファに DSCAPS_CTRL3D フラグが設定されていない場合、この値は無視される。DSBCAPS_CTRL3D が dwFlags に設定されていない場合、このメンバは GUID_NULL (DS3DALG_DEFAULT) にすべきである。DirectX 7.0 以降のバージョンで有効。「注意」を参照すること。

次のアルゴリズム識別子が定義されている。

DS3DALG_DEFAULT
HEL がデフォルト アルゴリズムとして設定される。現在、これは DS3DALG_NO_VIRTUALIZATION アルゴリズムを選択する。このアルゴリズムは、3D エフェクト以外の CPU 効率を提供する。

ソフトウェア ミキシングのみに適用される。WDM または VxD ドライバで利用できる。

DS3DALG_NO_VIRTUALIZATION
Direct3D API は、標準の左右ステレオのパンにマップされる。左に 90 度のとき、サウンドは左スピーカだけから聞こえ、右に 90 度のとき、サウンドは右スピーカだけから聞こえる。垂直軸では、距離によってボリュームが調節されるだけである。このバッファでは、ドップラー シフトとボリューム調節は適用されるが、3D フィルタリングは行われない。これは最も効率的なソフトウェアの実装であるが、仮想 3D オーディオ エフェクトは提供しない。DS3DALG_NO_VIRTUALIZATION フラグを指定すると、HRTF 処理は行われない。DS3DALG_NO_VIRTUALIZATION は標準のステレオのパンのみを使うので、このアルゴリズムで作成されたバッファは、3D ハードウェア ボイスの空きを利用できない場合、2D ハードウェア ボイスによってアクセラレートされる。

ソフトウェア ミキシングにのみ適用される。WDM または VxD ドライバで利用できる。

DS3DALG_HRTF_FULL
3D API は、高品質な 3D オーディオ アルゴリズムで処理される。このフラグは、ソフトウェア HEL にのみ適用される。このアルゴリズムは最高品質の 3D オーディオ エフェクトを与えるが、より多くの CPU サイクルを使う。「注意」を参照すること。

ソフトウェア ミキシングにのみ適用される。WDM ドライバを使うと、Microsoft® Windows® 98 Second Edition と Windows 2000 で利用できる。

注 : サウンド バッファを HRTF アルゴリズムを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。

DS3DALG_HRTF_LIGHT
3D API は、効率的な 3D オーディオ アルゴリズムで処理される。このフラグは、ソフトウェア HEL のみに適用される。このアルゴリズムは優れた 3D オーディオ エフェクトを与え、DS3DALG_HRTF_FULL ほど CPU に負荷をかけない。

ソフトウェア ミキシングにのみ適用される。WDM ドライバを使うと、Windows 98 Second Edition と Windows 2000 で利用できる。

注 : サウンド バッファを HRTF アルゴリズムを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。

注意

プライマリ バッファを作成する際、アプリケーションは dwBufferBytes メンバを 0 に設定しなければならない。DirectSound は、使用する特定のサウンド デバイスに対して最適なバッファ サイズを決定する。作成されたプライマリ バッファのサイズを取得するには、IDirectSoundBuffer::GetCaps を呼び出す。

DSBCAPS_CTRLDEFAULT フラグはもうサポートされていない。このフラグは、DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY として定義された。必要なフラグだけを指定することにより、不必要なリソースを減らすことができる。

DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE の各フラグはオプションであり、互いに排他的である。DSBCAPS_LOCHARDWARE は、強制的にバッファをハードウェアに配置する。これは、バッファがサウンド カードによってミキシングされることを意味する。DSBCAPS_LOCSOFTWARE は、強制的にバッファをソフトウェアに配置する。この場合、バッファは CPU によってミキシングされる。これらのフラグは DSBCAPS 構造体の dwFlags メンバ用にも定義されている。このメンバでこれらのフラグを使う場合、フラグは DirectSoundBuffer オブジェクトの実際の場所を示す。

3D アルゴリズムは、ソフトウェア エミュレーション レイヤのみの選択を行う。これは、アクセラレーション用のハードウェアがない場合に使われるソフトウェア アルゴリズムである。ハードウェアの利用を最大にするには、DS3DALG_NO_VIRTUALIZATION が特別な場合として扱われる。3D ハードウェア ボイスの空きを利用できない場合、バッファは 3D API コントロールと共に 2D バッファとして扱われる。特に、サウンド バッファを DS3DALG_NO_VIRTUALIZATION と DSBCAPS_LOCDER で作成する場合は、次の手順に従う。

  • 3D ハードウェア ボイスの空きが利用可能な場合は、その 3D ハードウェア ボイスを使う。
  • 3D ハードウェア ボイスの空きが利用不可能で、2D ハードウェア ボイスが利用可能な場合は、その 2D ハードウェア ボイスを使う。これが可能なのは、DS3DALG_NO_VIRTUALIZATION アルゴリズムが単純なステレオ パン アルゴリズムだからである。
  • 2D または 3D ハードウェア ボイスの空きが利用不可能な場合、ボイスは DS3DALG_NO_VIRTUALIZATION アルゴリズムを使ってソフトウェアで再生される。

DSSPEAKER_HEADPHONE や DSSPEAKER_STEREO 以外のスピーカ構成が有効な場合、この処理は二重スピーカ構成に対する処理と同じように行われる。

バッファを HRTF アルゴリズムを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。

DSBCAPS_CTRLPOSITIONNOTIFY フラグで作成されたサウンド バッファには、通知イベントを設定すべきである。このフラグでサウンド バッファを作成し、何も通知を設定しないと、動作は定義されない。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。

参照

DSBUFFERDESC1


DSBUFFERDESC1

DSBUFFERDESC1 構造体は、新しい DirectSoundBuffer オブジェクトの必須の特徴を示す。この構造体は、DirectX 7.0 以前のバージョンで DirectSound アプリケーションを作成する際、IDirectSound::CreateSoundBuffer メソッドによって使われる。

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
} DSBUFFERDESC, *LPDSBUFFERDESC;

typedef const DSBUFFERDESC *LPCDSBUFFERDESC;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
新しい DirectSoundBuffer オブジェクトを作成するときに含める能力を識別する。以下の 1 つまたは複数を指定する。
DSBCAPS_CTRL3D
このバッファは、3D コントロールを使う、プライマリ バッファまたはセカンダリ バッファのどちらかである。
DSBCAPS_CTRLFREQUENCY
バッファは周波数コントロール能力を備えていなければならない。
DSBCAPS_CTRLPAN
バッファはパン コントロール能力を備えていなければならない。
DSBCAPS_CTRLPOSITIONNOTIFY
バッファは位置通知能力を備えていなければならない。VxD ドライバでは、サウンド バッファが DSBCAPS_CTRLPOSITIONNOTIFY で作成される場合、このバッファは常にソフトウェア バッファになる。これは、VxD ドライバ モデルが通知インターフェイスをサポートしないためである。ハードウェアが利用可能な場合、WDM ドライバにより、位置通知可能なバッファがハードウェアに存在することがある。このフラグ設定で作成されたバッファの再生中は、DSBPLAY_LOCHARDWARE フラグによる IDirectSoundBuffer::Play の呼び出しは失敗する。
DSBCAPS_CTRLVOLUME
バッファはボリューム コントロール能力を備えていなければならない。
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer::GetCurrentPosition が再生カーソルの新しい動作を使うべきであることを示す。DirectX 1 の DirectSound では、エミュレートされたサウンド カード上で再生カーソルは実際に再生されているサウンドよりはるかに前方にあり、書き込みカーソルの直後に置かれていた。現在は、DSBCAPS_GETCURRENTPOSITION2 フラグを指定すると、アプリケーションはより正確な再生位置を取得できる。このフラグを指定していない場合、互換性を保つ目的で過去の動作が維持される。このフラグは、エミュレートされたサウンド カードにのみ影響を及ぼす点に注意すること。DirectSound ドライバが存在する場合、DirectX のどのバージョンでも、DirectSound の再生カーソルは正確な位置を示す。
DSBCAPS_GLOBALFOCUS
このバッファはグローバルなサウンド バッファである。このフラグを設定すると、ユーザーが他のアプリケーションにフォーカスを移動し、その新しいアプリケーションが DirectSound を使う場合でも、DirectSound を使っているアプリケーションは引き続きそのバッファを再生できる。1 つの例外は、協調レベルで DSSCL_EXCLUSIVE または DSSCL_WRITEPRIMARY フラグを設定した DirectSound アプリケーションにフォーカスを移動した場合である。この場合、他のアプリケーションからのグローバルなサウンドは聞こえなくなる。
DSBCAPS_LOCHARDWARE
DSBCAPS_STATIC が指定されていない場合でも、強制的にバッファにハードウェア ミキシングを使わせる。デバイスがハードウェア ミキシングをサポートしていない場合や、必要なハードウェア メモリが利用不可能な場合は、IDirectSound::CreateSoundBuffer の呼び出しは失敗する。アプリケーションは、このバッファがミキシング チャンネルを利用可能であると保証する必要がある。この状況は保証されていない。
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC が指定されていて、ハードウェア リソースが利用可能であっても、強制的にバッファをソフトウェア メモリに配置して、ソフトウェア ミキシングを使うようにする。
DSBCAPS_MUTE3DATMAXDISTANCE
サウンドは、最大距離で無音になる。最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないですむ。
DSBCAPS_PRIMARYBUFFER
このバッファがプライマリ サウンド バッファであることを示す。この値を指定しない場合、セカンダリ サウンド バッファが作成される。
DSBCAPS_STATIC
このバッファをスタティック サウンド データ用に使うことを示す。一般に、このようなバッファは 1 回ロードされ、何回も再生される。このようなバッファはハードウェア メモリに配置されることがある。
DSBCAPS_STICKYFOCUS
サウンド バッファのフォーカスの動作を変更する。IDirectSound::CreateSoundBuffer を呼び出す際に、このフラグを指定できる。このフラグを設定すると、ユーザーが DirectSound を使っていない他のアプリケーションに切り替えた場合でも、DirectSound を使っているアプリケーションはスティッキー フォーカス バッファの再生を続行できる。この状態でアプリケーションの標準バッファは無音になるが、スティッキー フォーカス バッファは引き続き音を出す。たとえばユーザーが Microsoft Word や Microsoft Excel で入力をしながら、ゲーム以外のアプリケーション、たとえば映画再生 (DirectShow ™) でサウンド トラックを聞きたいと考える場合に役立つ。しかし、ユーザーが他の DirectSound アプリケーションに切り替えると、すべてのサウンド バッファ、この例では標準バッファとスティッキー フォーカス バッファの両方が無音になる。
dwBufferBytes
新しいバッファのサイズ。単位はバイト。プライマリ バッファを作成するときは、この値は 0 でなければならない。セカンダリ バッファで許容される最小サイズと最大サイズは、dsound.h 内で定義される DSBSIZE_MIN、DSBSIZE_MAX である。
dwReserved
このメンバは予約されている。使わないこと。
lpwfxFormat
このバッファのウェーブ フォーマットを指定する構造体のアドレス。プライマリ バッファでは、この値は NULL でなければならない。アプリケーションは IDirectSoundBuffer::SetFormat を使って、プライマリ バッファのフォーマットを設定できる。

注意

この構造体は、DirectX 6.1 以前のバージョンのみで使用可能である。DirectX 7.0 と互換性のあるアプリケーションでは、DSBUFFERDESC 構造体を使う必要がある。

dwFlags メンバで使われる DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE の各フラグはオプションであり、互いに排他的である。DSBCAPS_LOCHARDWARE は、強制的にバッファをサウンド カードのメモリに配置する。DSBCAPS_LOCSOFTWARE は、可能であれば、強制的にバッファをメイン システム メモリに配置する。

これらのフラグは DSBCAPS 構造体の dwFlags メンバでも使うように定義されている。このメンバでこれらのフラグを使う場合、フラグは DirectSoundBuffer オブジェクトの実際の場所を示す。

プライマリ バッファを作成する際、アプリケーションは dwBufferBytes メンバを 0 に設定しなければならない。DirectSound は、使用中の特定のサウンド デバイスに対する最適なバッファ サイズを決定する。作成されたプライマリ バッファの大きさを取得するには、IDirectSoundBuffer::GetCaps を呼び出す。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。

参照

IDirectSound::CreateSoundBuffer


DSCAPS

DSCAPS 構造体は、DirectSound デバイスの能力を指定する。IDirectSound::GetCaps メソッドで使われる。

typedef {
    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;

typedef const DSCAPS *LPCDSCAPS;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
デバイスの能力を指定する。以下の 1 つまたは複数が指定できる。
DSCAPS_CERTIFIED
このドライバは Microsoft により試験と保証が行われている。
DSCAPS_CONTINUOUSRATE
このデバイスは、dwMinSecondarySampleRate と dwMaxSecondarySampleRate の各メンバ値の間のすべてのサンプリング レートをサポートする。一般にこれは、実際の出力レートが要求された周波数の ±10 ヘルツ (Hz) 以内であることを意味する。
DSCAPS_EMULDRIVER
このデバイスには DirectSound ドライバがインストールされていない。ウェーブフォーム オーディオ機能を通してエミュレートされている。性能の低下が予想される。
DSCAPS_PRIMARY16BIT
このデバイスは 16 ビット サンプリングでプライマリ サウンド バッファをサポートする。
DSCAPS_PRIMARY8BIT
このデバイスは 8 ビット サンプリングでプライマリ バッファをサポートする。
DSCAPS_PRIMARYMONO
このデバイスは単音のプライマリ バッファをサポートする。
DSCAPS_PRIMARYSTEREO
このデバイスはステレオのプライマリ バッファをサポートする。
DSCAPS_SECONDARY16BIT
このデバイスは、16 ビット サンプリングでハードウェア ミキシングのセカンダリ サウンド バッファをサポートする。
DSCAPS_SECONDARY8BIT
このデバイスは、8 ビット サンプリングでハードウェア ミキシングのセカンダリ バッファをサポートする。
DSCAPS_SECONDARYMONO
このデバイスは、ハードウェア ミキシングの単音セカンダリ バッファをサポートする。
DSCAPS_SECONDARYSTEREO
このデバイスは、ハードウェア ミキシングのステレオ セカンダリ バッファをサポートする。
dwMinSecondarySampleRate、dwMaxSecondarySampleRate
このデバイスのハードウェア セカンダリ サウンド バッファがサポートする最小と最大のサンプリング レートの仕様。
dwPrimaryBuffers
サポートされているプライマリ バッファの数。この値は常に 1 である。
dwMaxHwMixingAllBuffers
ハードウェアでミキシングできるバッファの合計数を指定する。このメンバは dwMaxHwMixingStaticBuffers と dwMaxHwMixingStreamingBuffers の合計より小さい値を取る。リソースのトレードオフがしばしば発生する。
dwMaxHwMixingStaticBuffers
スタティック サウンド バッファの最大数を指定する。
dwMaxHwMixingStreamingBuffers
ストリーム サウンド バッファの最大数を指定する。
dwFreeHwMixingAllBuffers、dwFreeHwMixingStaticBuffers、dwFreeHwMixingStreamingBuffers
空きまたは未割り当てのデバイスのハードウェア ミキシング能力の記述。アプリケーションはこれらの値を使って、セカンダリ サウンド バッファの割り当てにハードウェア リソースが利用可能かどうかを判断できる。また、最大のミキシング能力を指定するメンバとこれらの値を比較すると、既に割り当てられているリソースを決定できる。「注意」を参照すること。
dwMaxHw3DallBuffers、dwMaxHw3DstaticBuffers、dwMaxHw3DStreamingBuffers
デバイスのハードウェア 3D 定位能力の記述。
dwFreeHw3DallBuffers、dwFreeHw3DstaticBuffers、dwFreeHw3DStreamingBuffers
空きまたは未割り当てのデバイスのハードウェア 3D 定位能力の記述。「注意」を参照すること。
dwTotalHwMemBytes
スタティックサウンド バッファを保持するサウンド カード上のメモリ容量のサイズ。単位はバイト。
dwFreeHwMemBytes
サウンド カード上の空きメモリのサイズ。単位はバイト。
dwMaxContigFreeHwMemBytes
サウンド カード上の空きメモリのうち、最大の連続ブロックのサイズ。単位はバイト。
dwUnlockTransferRateHwBuffers
ハードウェア スタティック サウンド バッファへのデータ転送速度。単位は 1 秒あたりのキロバイト (KB/s)。この速度と転送バイト数により、IDirectSoundBuffer::Unlock メソッドを呼び出したときの実行時間が決まる。
dwPlayCpuOverheadSwBuffers
(メイン システム メモリ内の) ソフトウェア バッファをミキシングするのに必要な処理オーバーヘッドを、CPU パーセンテージで記述した値。この値は、バス タイプ、プロセッサ タイプ、クロック速度に応じて変化する。

ソフトウェア バッファのアンロック転送速度は 0 である。データをどこにも転送する必要がないからである。同様に、ハードウェア バッファの再生オーバーヘッドも、ミキシングがサウンド デバイスによって処理されるため、0 である。

dwReserved1、dwReserved2
将来の使用に予約。

注意

いくつかのオーディオ サウンド カードは、利用可能なハードウェア バッファやその空きを正確に報告できない場合がある。これはたとえば、カードが、高いサンプリング レートよりも低いサンプリング レートでより多くのサウンドを再生できるときに発生する。通常、ハードウェア バッファの空き数に関係するメンバの値が 0 以外のとき、適切なタイプのハードウェア リソースが少なくとも 1 つ利用できることを示す。

動作環境

Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。

参照

IDirectSound::GetCaps


DSCBCAPS

DSCBCAPS 構造体は、IDirectSoundCaptureBuffer::GetCaps メソッドによって使われる。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwBufferBytes;
    DWORD  dwReserved;
} DSCBCAPS, *LPDSCBCAPS;

typedef const DSCBCAPS *LPCDSCBCAPS;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
デバイスの能力を指定する。0 または次のフラグを指定する。
DSCBCAPS_WAVEMAPPED
このデバイスがサポートしないフォーマットに対して、Win32 ウェーブ マッパーを使う。
dwBufferBytes
キャプチャ バッファのサイズ。単位はバイト。
dwReserved
将来の使用に予約。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


DSCBUFFERDESC

DSCBUFFERDESC 構造体は、IDirectSoundCapture::CreateCaptureBuffer メソッドによって使われる。

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
} DSCBUFFERDESC, *LPDSCBUFFERDESC;

typedef const DSCBUFFERDESC *LPCDSCBUFFERDESC;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
デバイスの能力を指定する。0 または次のフラグを指定する。
DSCBCAPS_WAVEMAPPED
このデバイスがサポートしないフォーマットに対して、Win32 ウェーブ マッパーを使う。
dwBufferBytes
作成されるキャプチャ バッファのサイズ。単位はバイト。
dwReserved
将来の使用に予約。
lpwfxFormat
データのキャプチャに使うフォーマットを保持する WAVEFORMATEX 構造体へのポインタ。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


DSCCAPS

DSCCAPS 構造体は、IDirectSoundCapture::GetCaps メソッドによって使われる。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwFormats;
    DWORD  dwChannels;
} DSCCAPS, *LPDSCCAPS;

typedef const DSCCAPS *LPCDSCCAPS;

メンバ

dwSize
この構造体のサイズ。単位はバイト。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
デバイスの能力を指定する。0 または次のフラグを指定する。
DSCCAPS_EMULDRIVER
このデバイス用の DirectSoundCapture ドライバは存在しない。そのため、標準のウェーブ オーディオ関数が使われている。
DSCCAPS_CERTIFIED
このデバイス用のドライバは、認証済みの WDM ドライバである。
dwFormats
サポートされている標準フォーマット。これらは Win32 ウェーブフォーム オーディオ関数で使われている WAVEINCAPS 構造体の値と同じものである。簡便のためここに掲載する。
値 | 意味
WAVE_FORMAT_1M08 | 11.025kHz、モノラル、8 ビット
WAVE_FORMAT_1M16 | 11.025kHz、モノラル、16 ビット
WAVE_FORMAT_1S08 | 11.025kHz、ステレオ、8 ビット
WAVE_FORMAT_1S16 | 11.025kHz、ステレオ、16 ビット
WAVE_FORMAT_2M08 | 22.05kHz、モノラル、8 ビット
WAVE_FORMAT_2M16 | 22.05kHz、モノラル、16 ビット
WAVE_FORMAT_2S08 | 22.05kHz、ステレオ、8 ビット
WAVE_FORMAT_2S16 | 22.05kHz、ステレオ、16 ビット
WAVE_FORMAT_4M08 | 44.1kHz、モノラル、8 ビット
WAVE_FORMAT_4M16 | 44.1kHz、モノラル、16 ビット
WAVE_FORMAT_4S08 | 44.1kHz、ステレオ、8 ビット
WAVE_FORMAT_4S16 | 44.1kHz、ステレオ、16 ビット

dwChannels
デバイスがサポートするチャンネル数を指定する数値。1 はモノラル、2 はステレオを意味する。以下同様である。

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dsound.h で宣言。


戻り値

エラーは負の値で表され、組み合わされることはない。この表は、IDirectSound と IDirectSoundBuffer のすべてのメソッドが返す可能性のある値の一覧である。個別のメソッドの返すエラー コードのリストについては、そのメソッドの記述を参照すること。

DS_OK
要求は成功し完了した。
DSERR_ACCESSDENIED
アクセスが拒否されたため、要求は失敗した。
DSERR_ALLOCATED
優先レベルなどのリソースが他の呼び出しによって既に使用中であるため、要求は失敗した。
DSERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DSERR_BADFORMAT
指定したウェーブ フォーマットはサポートされていない。
DSERR_BUFFERLOST
バッファ メモリが失われたため、復元しなければならない。
DSERR_CONTROLUNAVAIL
呼び出し元が要求するバッファ コントロール (ボリューム、パンなど) は利用できない。
DSERR_GENERIC
DirectSound サブシステム内で不確定のエラーが発生した。
DSERR_HWUNAVAIL
DirectSound ハードウェア デバイスは利用不可能である。
DSERR_INVALIDCALL
このオブジェクトの現在の状態では、この関数は有効ではない。
DSERR_INVALIDPARAM
無効なパラメータが関数に渡された。
DSERR_NOAGGREGATION
このオブジェクトは COM 集合化をサポートしない。
DSERR_NODRIVER
利用可能なサウンド ドライバが存在しない。
DSERR_NOINTERFACE
要求された COM インターフェイスは利用できない。
DSERR_OTHERAPPHASPRIO
他のアプリケーションがより高い優先レベルを持っているため、この呼び出しは成功しなかった。
DSERR_OUTOFMEMORY
DirectSound サブシステムは、呼び出し元の要求を完了するための十分なメモリを割り当てられなかった。
DSERR_PRIOLEVELNEEDED
呼び出し元は、関数を成功させるために必要な優先レベルを持っていない。
DSERR_UNINITIALIZED
他のメソッドを呼び出す前に IDirectSound::Initialize メソッドを呼び出さなかったか、呼び出しが成功しなかった。
DSERR_UNSUPPORTED
呼び出した関数はこの時点ではサポートされていない。


DirectSound Visual Basic リファレンス

ここでは、Microsoft® Visual Basic® における Microsoft® DirectSound® の API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • クラス
  • 型
  • 列挙
  • エラー コード


クラス

ここでは、以下の DirectSound クラスのリファレンスを記述する。

  • DirectSound
  • DirectSound3DBuffer
  • DirectSound3DListener
  • DirectSoundBuffer
  • DirectSoundCapture
  • DirectSoundCaptureBuffer
  • DirectSoundEnum


DirectSound クラス

アプリケーションは DirectSound クラスのメソッドを使って、DirectSound オブジェクトの作成と環境設定を行う。ここでは、DirectSound クラスのメソッドのリファレンスを提供する。

このオブジェクトは、DirectX7.DirectSoundCreate 関数を使って取得する。

DirectSound クラスのメソッドは、以下のグループにまとめることができる。

初期化 | SetCooperativeLevel
バッファ作成 | CreateSoundBuffer
 | CreateSoundBufferFromFile
 | CreateSoundBufferFromResource
 | DuplicateSoundBuffer
デバイスの能力 | GetCaps
スピーカの構成 | GetSpeakerConfig
 | SetSpeakerConfig


DirectSound.CreateSoundBuffer

DirectSound.CreateSoundBuffer メソッドは、サンプリング オーディオのシーケンスを保持するための DirectSoundBuffer オブジェクトを作成する。

object.CreateSoundBuffer(bufferDesc As DSBUFFERDESC, _
    format As WAVEFORMATEX) As DirectSoundBuffer

パラメータ

object
DirectSound オブジェクトを表すオブジェクト式。
bufferDesc
作成するサウンド バッファの記述を指定する DSBUFFERDESC 型。
format
バッファが再生するデータのフォーマットを指定する WAVEFORMATEX 型。

戻り値

成功すれば DirectSoundBuffer オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

参照

DirectSound.CreateSoundBufferFromFile、DirectSound.CreateSoundBufferFromResource、DirectSound.DuplicateSoundBuffer


DirectSound.CreateSoundBufferFromFile

DirectSound.CreateSoundBufferFromFile メソッドは、サンプリング オーディオのシーケンスを保持するための DirectSoundBuffer オブジェクトを作成し、ファイルからのデータをバッファにロードする。

object.CreateSoundBufferFromFile(filename As String, _
    bufferDesc As DSBUFFERDESC, _
    format As WAVEFORMATEX) As DirectSoundBuffer

パラメータ

object
DirectSound オブジェクトを表すオブジェクト式。
filename
作成したバッファにロードするウェーブ ファイル名。
bufferDesc
作成するサウンド バッファの記述を指定する DSBUFFERDESC 型。lBufferBytes メンバは無視される。
format
ファイルのウェーブ フォーマットの情報を受け取る WAVEFORMATEX 型。メソッドにこの型を渡す前にメンバを初期化する必要はない。

戻り値

成功すれば DirectSoundBuffer を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

参照

DirectSound.CreateSoundBuffer、DirectSound.CreateSoundBufferFromResource、DirectSound.DuplicateSoundBuffer


DirectSound.CreateSoundBufferFromResource

DirectSound.CreateSoundBufferFromResource メソッドは、サンプリング オーディオのシーケンスを保持する DirectSoundBuffer オブジェクトを作成し、リソースからのデータをバッファにロードする。サウンド リソースは、WAV もしくは WAVE のどちらかのタイプでなければならない。

object.CreateSoundBufferFromResource( _
    dll As String, _
    resourceName As String, _
    bufferDesc As DSBUFFERDESC, _
    format As WAVEFORMATEX) As DirectSoundBuffer

パラメータ

object
DirectSound オブジェクトを表すオブジェクト式。
dll
リソースや、リソースを実行可能ファイルに含む場合の空の文字列を含む DLL 名。
resourceName
作成されたサウンド バッファにロードするリソース名。
bufferDesc
作成するサウンド バッファの記述を指定する DSBUFFERDESC 型。lBufferBytes メンバは無視される。
format
リソースのウェーブ フォーマットの情報を受け取る WAVEFORMATEX 型。メソッドにこの型を渡す前にメンバを初期化する必要はない。

戻り値

成功すれば DirectSoundBuffer を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

参照

DirectSound.CreateSoundBuffer、DirectSound.CreateSoundBufferFromFile、DirectSound.DuplicateSoundBuffer


DirectSound.DuplicateSoundBuffer

DirectSound.DuplicateSoundBuffer メソッドは、新しい DirectSoundBuffer オブジェクトを作成する。このオブジェクトは、オリジナルのオブジェクトと同じバッファ メモリを使う。

object.DuplicateSoundBuffer( _
    original As DirectSoundBuffer) _
    As DirectSoundBuffer

パラメータ

object
DirectSound オブジェクトを表すオブジェクト式。
original
複製する DirectSoundBuffer オブジェクト。

戻り値

成功すれば DirectSoundBuffer を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_ALLOCATED
DSERR_INVALIDCALL
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

注意

新しいオブジェクトはオリジナルのオブジェクトと同じ方法で使用できる。

複製直後のバッファは、オリジナル バッファと同じパラメータを持つ。ただし、アプリケーションは各バッファのパラメータを個別に変更でき、各バッファは互いに影響を及ぼすことなく再生と停止を行える。

どちらかのオブジェクトがバッファ内のデータを変更すると、バッファ メモリが共有されているため、通常その変更はもう一方のオブジェクトにも反映される。ただし、いくつかの環境では複製バッファが固有のメモリを保持するため、この動作をあてにすべきではない。

後に残った参照側オブジェクトが解放されると、バッファ メモリは解放される。

アプリケーションは、サウンド バッファの複製作業が成功するとは想定できない。特に、DirectSound はハードウェア バッファのソフトウェア複製を作成できない。

参照

DirectSound.CreateSoundBuffer、DirectSound.CreateSoundBufferFromFile、DirectSound.CreateSoundBufferFromResource


DirectSound.GetCaps

DirectSound.GetCaps メソッドは、DirectSound オブジェクトとして表されているハードウェア デバイスの能力を取得する。

object.GetCaps(caps As DSCAPS)

パラメータ

object
DirectSound オブジェクトを表すオブジェクト式。
caps
サウンド デバイスの能力を保持している DSCAPS 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_GENERIC
DSERR_UNINITIALIZED

注意

DSCAPS 型に保持されている情報は、ハードウェア ミキシング チャンネルの数、オンボード サウンド メモリの容量など、サウンド デバイスの最大能力と、現在使用可能な能力を記述する。これらの情報を使って性能を調整し、リソースの割り当てを最適化できる。

リソースの共有が前提となっているため、ある分野で最大の能力を利用すると、他の分野がその影響を受けることがある。たとえば、ハードウェア スタティック サウンド バッファが 1 つも利用できない場合は、最大数のストリーム サウンド バッファのハードウェア ミキシングが使用可能になる。

参照

DirectX7.DirectSoundCreate


DirectSound.GetSpeakerConfig

DirectSound.GetSpeakerConfig メソッドは、DirectSound オブジェクトに割り当てられたスピーカの構成を取得する。

object.GetSpeakerConfig() As CONST_DSSPEAKERFLAGS

パラメータ

object
DirectSound オブジェクトを表すオブジェクト式。

戻り値

成功すれば CONST_DSSPEAKERFLAGS 列挙の定数の 1 つまたは複数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

スピーカのジオメトリはデフォルトで 0 に設定される。これは、スピーカのジオメトリが未定義の状態である。ジオメトリは、DirectSound.SetSpeakerConfig メソッドを使って DSSPEAKER_STEREO フラグにスピーカのジオメトリ フラグの 1 つを渡すことにより、明示的に設定しなければならない。

参照

DirectSound.SetSpeakerConfig


DirectSound.SetCooperativeLevel

DirectSound.SetCooperativeLevel メソッドは、このサウンド デバイスのアプリケーション協調レベルを設定する。

object.SetCooperativeLevel(hwnd As Long, _
    level As CONST_DSSCLFLAGS)

パラメータ

object
DirectSound オブジェクトを表すオブジェクト式。
hwnd
アプリケーションへのウィンドウ ハンドル。「注意」を参照すること。
level
要求される優先レベル。CONST_DSSCLFLAGS 列挙の定数でなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

アプリケーションはバッファを再生する前に、このメソッドを呼び出して協調レベルを設定しなければならない。推奨される協調レベルは DSSCL_PRIORITY であり、他の優先レベルは必要に応じて使用する。

hwnd パラメータは、最上位のアプリケーション ウィンドウ ハンドルとすべきである。DirectDraw も使っている場合は、DirectDraw7.SetCooperativeLevel メソッドに渡したのと同じハンドルを指定しなければならない。


DirectSound.SetSpeakerConfig

DirectSound.SetSpeakerConfig メソッドは、DirectSound オブジェクトのスピーカ構成を指定する。

object.SetSpeakerConfig( _
    speakerConfig As CONST_DSSPEAKERFLAGS)

パラメータ

object
DirectSound オブジェクトを表すオブジェクト式。
speakerConfig
DirectSound オブジェクトのスピーカ構成。CONST_DSSPEAKERFLAGS 列挙の定数の 1 つまたは複数を指定しなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

スピーカのジオメトリはデフォルトで 0 に設定される。これは、スピーカのジオメトリが未定義の状態である。ジオメトリは、DSSPEAKER_STEREO フラグと組み合わせたスピーカのジオメトリ フラグの 1 つを渡すことにより、明示的に設定しなければならない。

参照

DirectSound.GetSpeakerConfig


DirectSound3Dbuffer クラス

アプリケーションは DirectSound3DBuffer クラスのメソッドを使って、3D 空間におけるサウンド バッファの位置、方向、環境を記述するパラメータの取得と設定を行う。ここでは、DirectSound3Dbuffer クラスのメソッドのリファレンスを提供する。

DirectSound3DBuffer は、3D 能力で作成されたセカンダリ バッファの DirectSoundBuffer.GetDirectSound3DBuffer メソッドを使って取得する。

DirectSound3DBuffer クラスのメソッドは、以下のグループにまとめることができる。

バッチ パラメータ操作 | GetAllParameters
 | SetAllParameters
距離 | GetMaxDistance
 | GetMinDistance
 | SetMaxDistance
 | SetMinDistance
取得オブジェクト | GetDirectSound3DListener
 | GetDirectSoundBuffer
操作モード | GetMode
 | SetMode
位置 | GetPosition
 | SetPosition
サウンド プロジェクション コーン | GetConeAngles
 | GetConeOrientation
 | GetConeOutsideVolume
 | SetConeAngles
 | SetConeOrientation
 | SetConeOutsideVolume
速度 | GetVelocity
 | SetVelocity


DirectSound3DBuffer.GetAllParameters

DirectSound3DBuffer.GetAllParameters メソッドは、サウンド バッファの 3D 特性に関する情報を取得する。

object.GetAllParameters(buffer As DS3DBUFFER)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
buffer
サウンド バッファの 3D 特性の記述を受け取る DS3DBUFFER 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DBuffer.GetConeAngles

DirectSound3DBuffer.GetConeAngles メソッドは、サウンド バッファのサウンド プロジェクション コーンの内部角度と外部角度を取得する。

object.GetConeAngles(inCone As Long, _
    outCone As Long)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
inCone
サウンド プロジェクション コーンの内部角度を受け取る変数。単位は度 (゜)。
outCone
サウンド プロジェクション コーンの外部角度を受け取る変数。単位は度 (゜)。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

最小、最大、デフォルトの各コーン角度はそれぞれ DS3D_MINCONEANGLE、DS3D_MAXCONEANGLE、DS3D_DEFAULTCONEANGLE として定義される。


DirectSound3DBuffer.GetConeOrientation

DirectSound3DBuffer.GetConeOrientation メソッドは、サウンド バッファのサウンド プロジェクション コーンの方向を取得する。

object.GetConeOrientation(orientation As D3DVECTOR)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
orientation
サウンド プロジェクション コーンの現在の方向を受け取る D3DVECTOR 型。ベクトル情報はサウンド コーンの中心を表す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

戻り値は必ずしも DirectSound3DBuffer.SetConeOrientation メソッドを使って設定したのと同じ値ではない。DirectSound は方向ベクトルに調整を加え、それらの大きさを 1.0 以下にする。

参照

DirectSound3DBuffer.SetConeOrientation、DirectSound3DBuffer.SetConeAngles、DirectSound3DBuffer.SetConeOutsideVolume


DirectSound3DBuffer.GetConeOutsideVolume

DirectSound3DBuffer.GetConeOutsideVolume メソッドは、サウンド バッファの現在のコーン外部ボリュームを取得する。

object.GetConeOutsideVolume() As Long

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すればこのサウンド バッファの現在のコーン外部ボリュームを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ボリューム レベルは減衰によって表される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。デフォルト値は DS3D_DEFAULTCONEOUTSIDEVOLUME (減衰なし) である。DirectSound は増幅をサポートしていない。


DirectSound3DBuffer.GetDirectSound3DListener

DirectSound3DBuffer.GetDirectSound3DListener メソッドは、DirectSound3DListener オブジェクトを返す。

object.GetDirectSound3DListener() As DirectSound3DListener

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すれば DirectSound3DListener オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に E_NOINTERFACE が設定される。

注意

このメソッドは、プライマリ バッファを表す DirectSoundBuffer から取得された DirectSound3DBuffer からのリスナーの取得に使われる。多くのアプリケーションは DirectSoundBuffer.GetDirectSound3DListener を呼び出し、プライマリ バッファを表すオブジェクトから直接リスナーを取得する。


DirectSound3DBuffer.GetDirectSoundBuffer

DirectSound3DBuffer.GetDirectSoundBuffer メソッドは、DirectSoundBuffer オブジェクトを返す。

object.GetDirectSoundBuffer() As DirectSoundBuffer

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すれば DirectSoundBuffer オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドは、DirectSound3DBuffer オブジェクトを取得した DirectSoundBuffer が既に利用できない場合、DirectSoundBuffer を取得するのに使われる。


DirectSound3DBuffer.GetMaxDistance

DirectSound3DBuffer.GetMaxDistance メソッドは、サウンド バッファの現在の最大距離を取得する。これは、ボリュームがそれ以上減衰しなくなる距離である。

object.GetMaxDistance() As Single

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すれば現在の最大距離の設定値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの最大距離は DS3D_DEFAULTMAXDISTANCE によって定義され、実質的に無限大である。

参照

DirectSound3DBuffer.GetMinDistance、DirectSound3DBuffer.SetMaxDistance


DirectSound3DBuffer.GetMinDistance

DirectSound3DBuffer.GetMinDistance メソッドは、サウンド バッファの現在の最小距離を取得する。これは、サウンドが最大ボリュームとなる距離である。

object.GetMinDistance() As Single

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すれば現在の最小距離の設定値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトでは、最小距離値は DS3D_DEFAULTMINDISTANCE であり、現在は 1.0 と定義されている (デフォルトの距離係数 1.0 を使った場合、1 単位は 1.0 メートルに相当する)。

参照

DirectSound3DBuffer.SetMinDistance、DirectSound3DBuffer.GetMaxDistance


DirectSound3DBuffer.GetMode

DirectSound3DBuffer.GetMode メソッドは、3D サウンド処理の現在の操作モードを取得する。

object.GetMode() As CONST_DS3DMODEFLAGS

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すれば現在のモードの設定を含む値を返す。この値は、CONST_DS3DMODEFLAGS 列挙の定数のいずれかである。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DBuffer.GetPosition

DirectSound3DBuffer.GetPosition メソッドは、サウンド バッファの位置を距離単位で取得する。

object.GetPosition(position As D3DVECTOR)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
position
サウンド バッファの位置を受け取る D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの距離単位はメートルであるが、DirectSound3DListener.SetDistanceFactor メソッドを使って単位を変更できる。


DirectSound3DBuffer.GetVelocity

DirectSound3DBuffer.GetVelocity メソッドは、サウンド バッファの現在の速度を取得する。

object.GetVelocity(velocity As D3DVECTOR)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
velocity
バッファの現在の速度を受け取る D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

速度はドップラー効果でのみ使われる。バッファを移動することはない。詳細については、「ドップラー係数」を参照すること。

デフォルトの計測単位はメートル/秒であるが、DirectSound3DListener.SetDistanceFactor メソッドを使って変更できる。

参照

DirectSound3DBuffer.SetPosition、DirectSound3DBuffer.SetVelocity


DirectSound3DBuffer.SetAllParameters

DirectSound3DBuffer.SetAllParameters メソッドは、サウンド バッファのすべての 3D パラメータを設定する。

object.SetAllParameters(buffer As DS3DBUFFER, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
buffer
サウンド バッファの 3D 特性を記述する情報を含む DS3DBUFFER 型。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DBuffer.SetConeAngles

DirectSound3DBuffer.SetConeAngles メソッドは、サウンド バッファのサウンド プロジェクション コーンの内部角度と外部角度を設定する。

object.SetConeAngles(inCone As Long, _
    outCone As Long, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
inCone
サウンド プロジェクション コーンの内部角度。単位は度 (゜)。
outCone
サウンド プロジェクション コーンの外部角度。単位は度 (゜)。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

最小、最大、デフォルトのコーン角度はそれぞれ DS3D_MINCONEANGLE、DS3D_MAXCONEANGLE、DS3D_DEFAULTCONEANGLE として定義される。各角度の範囲は、0 度 (コーンなし) から 360 度 (全範囲) までである。デフォルト値は 360 である。

参照

DirectSound3DBuffer.GetConeOutsideVolume、DirectSound3DBuffer.SetConeOutsideVolume


DirectSound3DBuffer.SetConeOrientation

DirectSound3DBuffer.SetConeOrientation メソッドは、サウンド バッファのサウンド プロジェクション コーンの方向を設定する。コーン角度とコーン ボリューム係数が既に設定されていない限り、このメソッドは何もしない。

object.SetConeOrientation( _
    x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
x、y、z
サウンド コーンの新しい方向ベクトルの座標。
applyFlag
設定が適用されるタイミングを示す値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DBuffer.SetConeAngles、DirectSound3DBuffer.SetConeOutsideVolume


DirectSound3DBuffer.SetConeOutsideVolume

DirectSound3DBuffer.SetConeOutsideVolume メソッドは、サウンド バッファのコーン外部ボリュームを設定する。

object.SetConeOutsideVolume(coneOutsideVolume As Long, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
coneOutsideVolume
サウンド バッファのコーン外部ボリュームを 100 分の 1 デシベル (dB) の単位で指定する。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ボリューム レベルは減衰によって表される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。デフォルト値は DS3D_DEFAULTCONEOUTSIDEVOLUME (減衰なし) である。

参照

DirectSoundBuffer.SetVolume


DirectSound3DBuffer.SetMaxDistance

DirectSound3DBuffer.SetMaxDistance メソッドは、バッファの最大距離を設定する。これは、ボリュームがそれ以上減衰しなくなる距離である。

object.SetMaxDistance(maxDistance As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
maxDistance
最大距離値。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの最大距離は DS3D_DEFAULTMAXDISTANCE によって定義され、実質的に無限大である。

参照

DirectSound3DBuffer.GetMaxDistance、DirectSound3DBuffer.SetMinDistance


DirectSound3DBuffer.SetMinDistance

DirectSound3DBuffer.SetMinDistance メソッドは、バッファの最小距離を設定する。これは、サウンドが最大ボリュームとなる距離である。

object.SetMinDistance(minDistance As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
minDistance
最小距離値。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトでは、最小距離値は DS3D_DEFAULTMINDISTANCE であり、1.0 と定義されている (デフォルトの距離係数 1.0 を使った場合、1 単位は 1.0 メートルに相当する)。

参照

DirectSound3DBuffer.SetMaxDistance


DirectSound3DBuffer.SetMode

DirectSound3DBuffer.SetMode メソッドは、3D サウンド処理の操作モードを設定する。

object.SetMode(mode As CONST_DS3DMODEFLAGS, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
mode
設定する 3D サウンド処理モードを示す CONST_DS3DMODEFLAGS 列挙の定数の 1 つを指定する。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DBuffer.SetPosition

DirectSound3DBuffer.SetPosition メソッドは、サウンド バッファの位置を距離単位で設定する。

object.SetPosition(x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
x、y、z
位置ベクトルの座標を表す値。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

10 以上または –10 以下の値を渡すと、オーディオの限界を超えてサウンドが減衰する可能性がある。

デフォルトの距離単位はメートルであるが、DirectSound3DListener.SetDistanceFactor メソッドを使って単位を変更できる。


DirectSound3DBuffer.SetVelocity

DirectSound3DBuffer.SetVelocity メソッドは、サウンド バッファの速度を設定する。

object.SetVelocity(x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DBuffer オブジェクトを表すオブジェクト式。
x、y、z
速度ベクトルの座標を表す値。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

速度はドップラー効果でのみ使われる。バッファを移動することはない。

デフォルトの計測単位はメートル/秒であるが、DirectSound3DListener.SetDistanceFactor メソッドを使って単位を変更できる。

参照

DirectSound3DBuffer.SetPosition、DirectSound3DBuffer.GetVelocity


DirectSound3DListener クラス

アプリケーションは DirectSound3DListener クラスのメソッドを使って、3D 空間でのリスナーの位置、方向、リスニング環境を記述するパラメータの取得と設定を行う。ここでは、DirectSound3DListener クラスのメソッドのリファレンスを提供する。

DirectSoundBuffer.GetDirectSound3DListener メソッドを使って、このクラスのオブジェクトを取得する。リスナーから取得されるバッファは、DSBCAPS_PRIMARYBUFFER フラグで作成されなくてはならない。また、プライマリ バッファから取得される DirectSound3DBuffer オブジェクトの DirectSound3DBuffer.GetDirectSound3DListener メソッドを呼び出すと、リスナーも取得できる。

DirectSound3DListener クラスのメソッドは、以下のグループにまとめることができる。

バッチ パラメータ | GetAllParameters
 | SetAllParameters
遅延設定 | CommitDeferredSettings
距離係数 | GetDistanceFactor
 | SetDistanceFactor
ドップラー係数 | GetDopplerFactor
 | SetDopplerFactor
オブジェクトの取得 | GetDirectSoundBuffer
方向 | GetOrientation
 | SetOrientation
位置 | GetPosition
 | SetPosition
ロールオフ係数 | GetRolloffFactor
 | SetRolloffFactor
速度 | GetVelocity
 | SetVelocity


DirectSound3DListener.CommitDeferredSettings

DirectSound3DListener.CommitDeferredSettings メソッドは、前回このメソッドを呼び出した後に行われた遅延設定をコミットする。

object.CommitDeferredSettings()

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DListener.GetAllParameters

DirectSound3DListener.GetAllParameters メソッドは、3D ワールドとリスナーの状態を取得する。

object.GetAllParameters(listener As DS3DLISTENER)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
listener
パラメータを受け取る DS3DLISTENER 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener.SetAllParameters


DirectSound3DListener.GetDirectSoundBuffer

DirectSound3DListener.GetDirectSoundBuffer メソッドは、プライマリ バッファを表す DirectSoundBuffer オブジェクトを返す。

object.GetDirectSoundBuffer() As DirectSoundBuffer

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。

戻り値

成功すれば DirectSoundBuffer オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_OUTOFMEMORY が設定される。


DirectSound3DListener.GetDistanceFactor

DirectSound3DListener.GetDistanceFactor メソッドは、ベクトル単位のメートル数で距離係数を取得する。

object.GetDistanceFactor() As Single

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。

戻り値

成功すれば距離係数の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener.SetDistanceFactor


DirectSound3DListener.GetDopplerFactor

DirectSound3DListener.GetDopplerFactor メソッドは、ドップラー効果係数を取得する。

object.GetDopplerFactor() As Single

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。

戻り値

成功すればドップラー係数の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

Remarks

ドップラー係数の範囲は、DS3D_MINDOPPLERFACTOR (ドップラー効果なし) から DS3D_MAXDOPPLERFACTOR (実世界の 10 倍のドップラー効果) までである。デフォルト値は DS3D_DEFAULTDOPPLERFACTOR (1.0) である。

参照

DirectSound3DListener.SetDopplerFactor


DirectSound3DListener.GetOrientation

DirectSound3DListener.GetOrientation メソッドは、3D 空間のリスナーの方向を取得する。

object.GetOrientation(orientFront As D3DVECTOR, _
    orientTop As D3DVECTOR)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
orientFront
リスナーの前方ベクトルを受け取る D3DVECTOR 型。
orientTop
リスナーの上方ベクトルを受け取る D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

前方ベクトルはリスナーの鼻の方向、上方ベクトルはリスナーの頭頂部の方向を指す。デフォルトでは、前方ベクトルは (0,0,1.0)、上方ベクトルは (0,1.0,0) である。

戻り値は必ずしも DirectSound3DListener.SetOrientation メソッドを使って設定したのと同じ値ではない。DirectSound は方向ベクトルに調整を加え、それらが互いに直角になるようにし、両方の大きさを 1.0 以下にする。


DirectSound3DListener.GetPosition

DirectSound3DListener.GetPosition メソッドは、3D 空間におけるリスナーの位置を取得する。

object.GetPosition(position As D3DVECTOR)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
position
リスナーの位置ベクトルを受け取る D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener.SetPosition


DirectSound3DListener.GetRolloffFactor

DirectSound3DListener.GetRolloffFactor メソッドは、距離に応じた減衰率を制御するロールオフ係数を取得する。

object.GetRolloffFactor() As Single

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。

戻り値

成功すればロールオフ係数の値を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ロールオフ係数は、DS3D_MINROLLOFFFACTOR (ロールオフなし) から DS3D_MAXROLLOFFFACTOR (実世界の 10 倍のロールオフ) までの範囲をとる。デフォルト値は DS3D_DEFAULTROLLOFFFACTOR (1.0) である。

参照

DirectSound3DListener.SetRolloffFactor


DirectSound3DListener.GetVelocity

DirectSound3DListener.GetVelocity メソッドは、リスナーの速度を取得する。

object.GetVelocity() As D3DVECTOR

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。

戻り値

成功すればリスナーの速度を含む D3DVECTOR 型を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの速度は (0,0,0) である。

速度はドップラー効果でのみ使われる。リスナーを移動することはない。

参照

DirectSound3DListener.SetVelocity


DirectSound3DListener.SetAllParameters

DirectSound3DListener.SetAllParameters メソッドは、すべての 3D リスナーのプロパティとグローバル サウンド パラメータを設定する。

object.SetAllParameters(listener As DS3DLISTENER, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
listener
すべての 3D リスナーのパラメータ情報を保持する DS3DLISTENER 型。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener.GetAllParameters


DirectSound3DListener.SetDistanceFactor

DirectSound3DListener.SetDistanceFactor メソッドは、距離係数を設定する。

object.SetDistanceFactor(distanceFactor As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
distanceFactor
距離係数。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

距離係数の詳細については、「距離係数」を参照すること。

参照

DirectSound3DListener.GetDistanceFactor


DirectSound3DListener.SetDopplerFactor

DirectSound3DListener.SetDopplerFactor メソッドは、ドップラー効果係数を設定する。

object.SetDopplerFactor(dopplerFactor As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
dopplerFactor
ドップラー係数の値。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ドップラー係数の範囲は、DS3D_MINDOPPLERFACTOR (ドップラー効果なし) から DS3D_MAXDOPPLERFACTOR (実世界の 10 倍のドップラー効果) までである。デフォルト値は DS3D_DEFAULTDOPPLERFACTOR (1.0) である。

参照

DirectSound3DListener.GetDopplerFactor


DirectSound3DListener.SetOrientation

DirectSound3DListener.SetOrientation メソッドは、前方ベクトルと上方ベクトルの 2 つのベクトルにより、リスナーの方向を設定する。

object.SetOrientation(xFront As Single, _
    yFront As Single, _
    zFront As Single, _
    xTop As Single, _
    yTop As Single, _
    zTop As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
xFront、yFront、zFront
前方ベクトルの座標を示す値。
xTop、yTop、zTop
上方ベクトルの座標を示す値。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

前方ベクトルはリスナーの鼻の方向、上方ベクトルはリスナーの頭頂部の方向を指す。デフォルトでは、前方ベクトルは (0,0,1.0)、上方ベクトルは (0,1.0,0) である。

上方ベクトルは前方ベクトルに対して直角でなければならない。必要に応じて、DirectSound は前方ベクトルを設定した後で上方ベクトルを調整する。

参照

DirectSound3DListener.GetOrientation


DirectSound3DListener.SetPosition

DirectSound3DListener.SetPosition メソッドは、リスナーの位置を距離単位で設定する。

object.SetPosition(x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
x、y、z
リスナーの位置ベクトルの座標を表す値。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトではこれらの単位はメートルだが、DirectSound3DListener.SetDistanceFactor メソッドを使って単位を変更できる。

参照

DirectSound3DListener.GetPosition


DirectSound3DListener.SetRolloffFactor

DirectSound3DListener.SetRolloffFactor メソッドは、ロールオフ係数を設定する。

object.SetRolloffFactor(rolloffFactor As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
rolloffFactor
ロールオフ係数。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ロールオフ係数は、DS3D_MINROLLOFFFACTOR (ロールオフなし) から DS3D_MAXROLLOFFFACTOR (実世界の 10 倍のロールオフ) までの範囲をとる。デフォルト値は DS3D_DEFAULTROLLOFFFACTOR (1.0) である。

参照

DirectSound3DListener.GetRolloffFactor


DirectSound3DListener.SetVelocity

DirectSound3DListener.SetVelocity メソッドは、リスナーの速度を設定する。

object.SetVelocity(x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

パラメータ

object
DirectSound3DListener オブジェクトを表すオブジェクト式。
x、y、z
リスナーの速度ベクトルの座標を表す値。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある。
applyFlag
設定が適用されるタイミングを示す値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの速度は (0,0,0) である。

速度はドップラー効果でのみ使われる。リスナーを移動することはない。リスナーの位置を変更するには DirectSound3DListener.SetPosition メソッドを使う。

参照

DirectSound3DListener.GetVelocity


DirectSoundBuffer クラス

アプリケーションは DirectSoundBuffer クラスのメソッドを使って、DirectSoundBuffer オブジェクトの作成と環境設定を行う。

DirectSound.CreateSoundBuffer、DirectSound.CreateSoundBufferFromFile、DirectSound.CreateSoundBufferFromResource の各メソッドを使ってこのオブジェクトを取得する。

DirectSoundBuffer メソッドは、以下のグループにまとめることができる。

情報 | GetCaps
 | GetFormat
 | GetStatus
 | SetFormat
メモリ管理 | Restore
その他 | SaveToFile
オブジェクトの取得 | GetDirectSound3DBuffer
 | GetDirectSound3DListener
再生管理 | GetCurrentPosition
 | Play
 | ReadBuffer
 | SetCurrentPosition
 | SetNotificationPositions
 | Stop
 | WriteBuffer
サウンド管理 | GetFrequency
 | GetPan
 | GetVolume
 | SetFrequency
 | SetPan
 | SetVolume


DirectSoundBuffer.GetCaps

DirectSoundBuffer.GetCaps メソッドは、バッファの能力を取得する。

object.GetCaps(caps As DSBCAPS)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
caps
サウンド バッファの能力を保持している DSBCAPS 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

DSBCAPS 型は、DirectSound.CreateSoundBuffer メソッドに渡される DSBUFFERDESC 型と同等の情報に加えて、いくつかの追加情報を保持している。この情報として、バッファの位置 (ハードウェアとソフトウェアのどちらか) と、コスト測定値が挙げられる。コスト測定値の例には、ハードウェア バッファへのダウンロード所要時間、バッファがソフトウェア内に配置されている場合のミキシングや再生処理のオーバーヘッドが含まれる。

DSBCAPS 型の lFlags メンバ内のフラグは、DSBUFFERDESC 型で使われるフラグと同じものである。唯一の違いは、DSBCAPS 型ではバッファ メモリの場所に応じて DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらかが指定されることである。DSBUFFERDESC 型ではこれらのフラグはオプションであり、フラグの指定に応じて、バッファをハードウェアとソフトウェアのどちらかに強制的に配置できる。


DirectSoundBuffer.GetCurrentPosition

DirectSoundBuffer.GetCurrentPosition メソッドは、サウンド バッファ内の再生カーソルと書き込みカーソルの位置を取得する。

object.GetCurrentPosition(cursors As DSCURSORS)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
cursors
バッファのカレント プレイ ポジションとカレント ライト ポジションを受け取る DSCURSORS 型。この位置はサウンド バッファ内のオフセットであり、バイト単位で指定される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

書き込みカーソルは通常、再生カーソルより 15 ミリ秒のオーディオ データ分だけ常に先行している。再生位置と書き込み位置の間のデータの書き込みは安全に行えない。

参照

DirectSoundBuffer、DirectSoundBuffer.SetCurrentPosition


DirectSoundBuffer.GetDirectSound3DBuffer

DirectSoundBuffer.GetDirectSound3DBuffer メソッドは、DirectSound3DBuffer オブジェクトを返す。

object.GetDirectSound3DBuffer() As DirectSound3DBuffer

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すれば DirectSound3DBuffer オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に E_NOINTERFACE または DSERR_OUTOFMEMORY が設定される。

注意

このメソッドは、DSBCAPS_CTRL3D フラグで作成されたバッファだけで成功する。

参照

DirectSound.CreateSoundBuffer


DirectSoundBuffer.GetDirectSound3DListener

DirectSoundBuffer.GetDirectSound3DListener メソッドは、DirectSound3DListener オブジェクトを返す。

object.GetDirectSound3DListener() As DirectSound3DListener

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すれば DirectSound3DListener オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

注意

このメソッドは、DSBCAPS_CTRL3D と DSBCAPS_PRIMARYBUFFER のフラグで作成されたバッファだけで成功する。

参照

DirectSound.CreateSoundBuffer


DirectSoundBuffer.GetFormat

DirectSoundBuffer.GetFormat メソッドは、バッファのウェーブ フォーマットの記述を取得する。

object.GetFormat(format As WAVEFORMATEX)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
format
バッファのウェーブ フォーマットの記述を受け取る WAVEFORMATEX 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSoundBuffer.SetFormat


DirectSoundBuffer.GetFrequency

DirectSoundBuffer.GetFrequency メソッドは、バッファの再生が行われている場所での 1 秒あたりのサンプリング回数を周波数として取得する。

object.GetFrequency() As Long

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。

戻り値

オーディオ バッファの再生が行われている場所の周波数。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

周波数の値は、DSBFREQUENCY_MIN (100) から DSBFREQUENCY_MAX (100,000) の範囲をとる。

参照

DirectSoundBuffer.SetFrequency


DirectSoundBuffer.GetPan

DirectSoundBuffer.GetPan メソッドは、左右のオーディオ チャンネルの相対ボリュームを示す変数を取得する。

object.GetPan() As Long

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。

戻り値

左右のスピーカの相対ミキシング率。「注意」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

戻り値は DSBPAN_LEFT (-10,000) から DSBPAN_RIGHT (10,000) の範囲で、100 分の 1 デシベル (dB) 単位である。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値は DSBPAN_CENTER (0) であり、両方のチャンネルが最大ボリュームであることを意味する (0 dB の減衰)。

DSBPAN_CENTER 以外の値はどれも、一方が最大ボリュームでもう一方が減衰していることを意味する。たとえば、値が -2,173 のとき、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様にパンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。

パン コントロールのエフェクトは、ボリューム コントロールに累積される。

参照

DirectSoundBuffer.GetVolume、DirectSoundBuffer.SetPan、DirectSoundBuffer.SetVolume


DirectSoundBuffer.GetStatus

DirectSoundBuffer.GetStatus メソッドは、サウンド バッファのステータスを取得する。

object.GetStatus() As CONST_DSBSTATUSFLAGS

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。

戻り値

サウンド バッファのステータス。ステータスはバッファが失われているか再生中のどちらでもないことを示す 0、または CONST_DSBSTATUSFLAGS 列挙の定数の組み合わせである。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

DirectSoundBuffer


DirectSoundBuffer.GetVolume

DirectSoundBuffer.GetVolume メソッドは、サウンド バッファのボリュームを取得する。

object.GetVolume() As Long

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。

戻り値

バッファのボリュームを返す。「注意」を参照すること。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

ボリュームは 100 分の 1 デシベル (dB) 単位で指定される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。これらの値は、それぞれ 0、-10,000 と定義されている。値 DSBVOLUME_MAX は、サウンド本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。

参照

DirectSoundBuffer.SetVolume、DirectSoundBuffer.GetPan


DirectSoundBuffer.Play

DirectSoundBuffer.Play メソッドは、サウンド バッファをカレント プレイ ポジションから再生する。

object.Play(flags As CONST_DSBPLAYFLAGS)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
flags
バッファの再生方法を指定するフラグ。CONST_DSBPLAYFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

このメソッドはセカンダリ サウンド バッファをプライマリ サウンド バッファにミキシングし、サウンド デバイスに送信する。

このメソッドが指定したバッファが既に再生中だった場合、メソッドの呼び出しは成功し、バッファは再生を続ける。ただし最新の呼び出しで定義したフラグは、以前の呼び出しで定義されたフラグを置き換える。

このメソッドがサウンド バッファで呼び出される前に、アプリケーションは DirectSound.SetCooperativeLevel メソッドを呼び出さなければならない。


DirectSoundBuffer.ReadBuffer

DirectSoundBuffer.ReadBuffer メソッドは、サウンド バッファのセグメントを読み込み、アプリケーション バッファにそのデータを格納する。

object.ReadBuffer(start As Long, _
    size As Long, _
    buffer As Any, _
    flags As CONST_DSBLOCKFLAGS)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
start
バッファの先頭から読み込み開始位置までのオフセット。単位はバイト。DSBLOCK_FROMWRITECURSOR を flags パラメータに指定すると、このパラメータは無視される。
size
読み込むバッファ部分のサイズ。単位はバイト。サウンド バッファは概念的には循環バッファなので、この値はバッファの先頭から最後までのバイト数よりも大きくなることもある。DSBLOCK_ENTIREBUFFER を flags パラメータに指定すると、このパラメータは無視される。
buffer
読み込むデータを保持する変数。通常これはバイトの配列であり、配列の最初の要素を渡す。
flags
CONST_DSBLOCKFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

DirectSoundCaptureBuffer.ReadBuffer


DirectSoundBuffer.Restore

DirectSoundBuffer.Restore メソッドは、失われたサウンド バッファへのメモリ割り当てを復元する。

object.Restore()

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_PRIOLEVELNEEDED

注意

アプリケーションに入力フォーカスが置かれていないと、DirectSoundBuffer.Restore は成功しないことがある。たとえば、入力フォーカスが置かれているアプリケーションが DSSCL_WRITEPRIMARY (書き込み優先) 協調レベルに設定されている場合、ほかのどのアプリケーションもバッファを復元できない。

DirectSound がバッファ メモリを復元した後、有効なサウンド データを書き込み直す必要がある。DirectSound はメモリ自体を復元するが、メモリの内容は復元できない。

アプリケーションはバッファを指定して DirectSoundBuffer.WriteBuffer または DirectSoundBuffer.Play の各メソッドを呼び出すと、そのバッファが失われている場合に通知を受けられる。バッファが失われている場合は、これらのメソッドは DSERR_BUFFERLOST を返す。DirectSoundBuffer.GetStatus メソッドを使って、サウンド バッファのステータスの取得と DSBSTATUS_BUFFERLOST フラグのテストを行うこともできる。

参照

DirectSoundBuffer.GetStatus


DirectSoundBuffer.SaveToFile

DirectSoundBuffer.SaveToFile メソッドは、DirectSound バッファの内容をウェーブ ファイルに保存する。

object.SaveToFile(filename As String)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
filename
サウンド バッファが保存される場所のファイル名。その名前のファイルが存在する場合、データはファイルに追加されるのではなく、ファイルが上書きされる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM


DirectSoundBuffer.SetCurrentPosition

DirectSoundBuffer.SetCurrentPosition メソッドは、バッファのカレント プレイ ポジションを移動する。

object.SetCurrentPosition(newPosition As Long)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
newPosition
再生位置に対するバッファの先頭からのオフセット。単位はバイト。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

プライマリ サウンド バッファに対しては、このメソッドを呼び出せない。

バッファが既に再生中の場合は、即座に新規の位置へ移動して再生を続行する。バッファが停止している場合は、次に DirectSoundBuffer.Play メソッドを呼び出したときに、新しい位置から再生を開始する。

参照

DirectSoundBuffer.GetCurrentPosition


DirectSoundBuffer.SetFormat

DirectSoundBuffer.SetFormat メソッドは、このアプリケーション用のプライマリ サウンド バッファのフォーマットを設定する。このアプリケーションに入力フォーカスが置かれるたびに、DirectSound はプライマリ バッファを指定されたフォーマットに設定する。

object.SetFormat(format As WAVEFORMATEX)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
format
プライマリ サウンド バッファの新しいフォーマットを指定する WAVEFORMATEX 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED
DSERR_UNSUPPORTED

注意

ハードウェアが要求されたフォーマットをサポートしない場合でも、このメソッドは成功する。DirectSound はバッファを、要求に最も近いフォーマットに設定し、要求されたフォーマットでサウンドをミックスし、変換した上でプライマリ バッファに送る。このような状況が発生しているかどうかを判断するには、アプリケーションはプライマリ バッファに対して DirectSoundBuffer.GetFormat メソッドを呼び出し、その結果を、SetFormat メソッドで要求したフォーマットと比較する。

呼び出すアプリケーションに DSSCL_NORMAL 協調レベルが設定されていると、このメソッドは失敗する。

このメソッドはセカンダリ サウンド バッファには有効ではない。セカンダリ サウンド バッファがフォーマットの変更を必要とする場合、アプリケーションは新規のフォーマットを使う新しい DirectSoundBuffer オブジェクトを作成すべきである。


DirectSoundBuffer.SetFrequency

DirectSoundBuffer.SetFrequency メソッドは、サンプリング オーディオの再生周波数を設定する。

object.SetFrequency(frequency As Long)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
frequency
サンプリング オーディオを再生する新しい周波数で、単位はヘルツ (Hz) である。値の範囲は DSBFREQUENCY_MIN (100) から DSBFREQUENCY_MAX (100,000) の間でなければならない。

値が DSBFREQUENCY_ORIGINAL の場合、周波数は現在のバッファ フォーマット内のデフォルト値にリセットされる。このフォーマットは DirectSound.CreateSoundBuffer メソッドで指定されたものである。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

周波数を上下させると、オーディオ データの認識ピッチが変化する。このメソッドはバッファのフォーマットに影響を及ぼさない。

このメソッドはプライマリ サウンド バッファには有効ではない。

参照

DirectSoundBuffer.GetFrequency


DirectSoundBuffer.SetNotificationPositions

DirectSoundBuffer.SetNotificationPositions メソッドは、通知位置を設定する。再生中にカレント プレイ ポジションが指定されたオフセットに到達するたびに、関連するイベントがシグナル送信される。

object.SetNotificationPositions(nElements As Long, _
    psa() As DSBPOSITIONNOTIFY)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
nElements
psa 配列の要素数。
psa
DSBPOSITIONNOTIFY 型の配列。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundBuffer.SetPan

DirectSoundBuffer.SetPan メソッドは、左右のチャンネルの相対ボリュームを設定する。

object.SetPan(pan As Long)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
pan
左右のチャンネルの相対ボリューム。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

戻り値は DSBPAN_LEFT (-10,000) から DSBPAN_RIGHT (10,000) の範囲で、100 分の 1 デシベル (dB) 単位である。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値は DSBPAN_CENTER (0) であり、両方のチャンネルが最大ボリュームであることを意味する (0 dB の減衰)。

DSBPAN_CENTER 以外の値はどれも、一方が最大ボリュームでもう一方が減衰していることを意味する。たとえば、値が -2,173 のとき、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様にパンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。

パン コントロールのエフェクトーム コントロールに累積される。

参照

DirectSoundBuffer.GetPan、DirectSoundBuffer.SetVolume


DirectSoundBuffer.SetVolume

DirectSoundBuffer.SetVolume メソッドは、サウンド バッファのボリュームを変更する。

object.SetVolume(volume As Long)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
volume
このサウンド バッファで要求するボリューム。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

ボリュームは、減衰の 100 分の 1 デシベル (dB) 単位で指定される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。これらの値は、それぞれ 0、-10,000 と定義されている。値 DSBVOLUME_MAX は、サウンド本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオ ボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。

参照

DirectSoundBuffer.GetVolume、DirectSoundBuffer.SetPan


DirectSoundBuffer.Stop

DirectSoundBuffer.Stop メソッドは、サウンド バッファの再生を停止する。

object.Stop()

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

このメソッドは、バッファのカレント プレイ ポジションを直前に再生されたサンプルの直後のサンプルに設定する。そのバッファに対して次に DirectSoundBuffer.Play メソッドを呼び出すと、以前に再生を停止した場所から再生が再開される。


DirectSoundBuffer.WriteBuffer

DirectSoundBuffer.WriteBuffer メソッドは、オーディオ データを保持するアプリケーション バッファから、サウンド バッファのセグメントへの書き込みを行う。

object.WriteBuffer(start As Long, _
    size As Long, _
    buffer As Any, _
    flags As CONST_DSBLOCKFLAGS)

パラメータ

object
DirectSoundBuffer オブジェクトを表すオブジェクト式。
start
バッファの先頭から読み込みを開始する場所までのオフセット。単位はバイト。DSBLOCK_FROMWRITECURSOR 定数を flags パラメータに指定すると、このパラメータは無視される。
size
読み込むバッファ部分のサイズ。単位はバイト。サウンド バッファは概念的には循環バッファなので、この値はバッファの先頭から最後までのバイト数よりも大きくなることもある。DSBLOCK_ENTIREBUFFER を flags パラメータに指定すると、このパラメータは無視される。
buffer
サウンド バッファに書き込むデータを保持する変数。通常これはバイトの配列であり、配列の最初の要素を渡す。
flags
データを書き込む方法を示す CONST_DSBLOCKFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundCapture クラス

DirectSoundCapture クラスのオブジェクトは、サウンド キャプチャ デバイスを表す。このクラスのメソッドは、サウンド キャプチャ バッファの作成とそのデバイス能力の問い合わせに使われる。

DirectX7.DirectSoundCaptureCreate メソッドを使ってこのクラスのオブジェクトを取得する。

DirectSoundCapture クラスのメソッドは、以下のグループにまとめることができる。

バッファの作成 | CreateCaptureBuffer
能力 | GetCaps


DirectSoundCapture.CreateCaptureBuffer

DirectSoundCapture.CreateCaptureBuffer メソッドは、キャプチャ バッファを作成する。

object.CreateCaptureBuffer( _
    bufferDesc As DSCBUFFERDESC) _
    As DirectSoundCaptureBuffer

パラメータ

object
DirectSoundCapture オブジェクトを表すオブジェクト式。
bufferDesc
作成されるキャプチャ バッファ用の値を指定する DSCBUFFERDESC 型。

戻り値

成功すれば DirectSoundCaptureBuffer オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_BADFORMAT
DSERR_GENERIC
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

注意

キャプチャ デバイスでは、1 つのキャプチャ バッファのみ存在できる。


DirectSoundCapture.GetCaps

DirectSoundCapture.GetCaps メソッドは、キャプチャ デバイスの能力を取得する。

object.GetCaps(caps As DSCCAPS)

パラメータ

object
DirectSoundCapture オブジェクトを表すオブジェクト式。
caps
キャプチャ デバイスの能力を受け取る DSCCAPS 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED


DirectSoundCaptureBuffer クラス

DirectSoundCaptureBuffer クラスのメソッドは、サウンド キャプチャ バッファを操作するために使われる。

DirectSoundCapture.CreateCaptureBuffer メソッドを呼び出してこのクラスのオブジェクトを取得する。

DirectSoundCaptureBuffer クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetCaps
 | GetCurrentPosition
 | GetFormat
 | GetStatus
バッファ | ReadBuffer
 | WriteBuffer
通知 | SetNotificationPositions
キャプチャ管理 | Start
 | Stop


DirectSoundCaptureBuffer.GetCaps

DirectSoundCaptureBuffer.GetCaps メソッドは、バッファの能力を返す。

object.GetCaps(caps As DSCBCAPS)

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。
caps
キャプチャ バッファの能力を受け取る DSCBCAPS 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer.GetCurrentPosition

DirectSoundCaptureBuffer.GetCurrentPosition メソッドは、バッファの現在のキャプチャ位置と読み込み位置を取得する。

object.GetCurrentPosition(cursors As DSCURSORS)

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。
cursors
現在のキャプチャ位置 (lPlay) と読み込み位置 (lWrite) を受け取る DSCURSORS 型。それぞれの位置はキャプチャ バッファのオフセットであり、バイト単位で指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

注意

キャプチャ位置は読み込み位置より前方にあり、データがキャプチャされる位置を示す。読み込み位置 (DSCURSORS.lWrite) までの位置では、データを安全に読み込みできる。バッファリングのため、読み込み位置より後でキャプチャ位置より前のデータは (キャプチャ位置を含む)、必ずしも有効なデータとは限らない。


DirectSoundCaptureBuffer.GetFormat

DirectSoundCaptureBuffer.GetFormat メソッドは、キャプチャ バッファのフォーマットを取得する。

object.GetFormat(waveformat As WAVEFORMATEX)

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。
waveformat
キャプチャ バッファ フォーマットの記述を受け取る WAVEFORMATEX 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSoundCaptureBuffer.GetStatus

DirectSoundCaptureBuffer.GetStatus メソッドは、キャプチャ バッファの現在のステータスを取得する。

object.GetStatus() As CONST_DSCBSTATUSFLAGS

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。

戻り値

成功すればキャプチャ バッファのステータスを返す。ステータスは、CONST_DSCBSTATUSFLAGS 列挙の定数の 1 つまたは複数である。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSoundCaptureBuffer.ReadBuffer

DirectSoundCaptureBuffer.ReadBuffer メソッドは、サウンド キャプチャ バッファのセグメントを読み込み、そのデータをアプリケーション バッファに格納する。

object.ReadBuffer(start As Long, _
    size As Long, _
    buffer As Any, _
    flags As CONST_DSCBLOCKFLAGS)

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。
start
バッファの先頭から読み込み開始位置までのオフセット。単位はバイト。
size
読み込むバッファ部分のサイズ。単位はバイト。サウンド バッファは概念的には循環バッファなので、この値はバッファの先頭から最後までのバイト数よりも大きくなることもある。DSCBLOCK_ENTIREBUFFER 定数を flags 引数に設定すると、このパラメータは無視される。
buffer
読み込むデータを保持する変数。通常これはバイトの配列であり、配列の最初の要素を渡す。
flags
CONST_DSCBLOCKFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundCaptureBuffer.SetNotificationPositions

DirectSoundCaptureBuffer.SetNotificationPositions メソッドは、通知イベントがシグナル送信されるバッファの位置を設定する。現在の読み込み位置が通知位置に到達すると、イベントがシグナル送信される。

object.SetNotificationPositions(nElements As Long, _
    psa() As DSBPOSITIONNOTIFY)

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。
nElements
psa 配列の要素数。
psa
DSBPOSITIONNOTIFY 型の配列。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

DirectSoundCaptureBuffer.GetCurrentPosition


DirectSoundCaptureBuffer.Start

DirectSoundCaptureBuffer.Start メソッドは、バッファへのデータのキャプチャリングを開始する。キャプチャ バッファが既にキャプチャ状態にある場合には、このメソッドは何もしない。

object.Start(flags As CONST_DSCBSTARTFLAGS)

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。
flags
サウンド データをキャプチャリングするときのキャプチャ バッファの動作を指定するフラグ。CONST_DSCBSTARTFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer.Stop

DirectSoundCaptureBuffer.Stop メソッドは、データのキャプチャを停止する。キャプチャ バッファが既に停止している場合は、このメソッドは何もしない。

object.Stop()

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_NODRIVER
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer.WriteBuffer

DirectSoundCaptureBuffer.WriteBuffer メソッドは、オーディオ データを保持するアプリケーション バッファから、サウンド キャプチャ バッファのセグメントへの書き込みを行う。

object.WriteBuffer(start As Long, _
    size As Long, _
    buffer As Any, _
    flags As CONST_DSCBLOCKFLAGS)

パラメータ

object
DirectSoundCaptureBuffer オブジェクトを表すオブジェクト式。
start
バッファの先頭から書き込みを開始する位置までのオフセット。単位はバイト。
size
読み込むバッファ部分のサイズ。単位はバイト。サウンド バッファは概念的に循環バッファなので、この値はバッファの先頭から最後までのバイト数よりも大きくなることもある。DSCBLOCK_ENTIREBUFFER を flags パラメータに設定すると、このパラメータは無視される。
buffer
キャプチャ バッファに書き込むデータを保持する変数。通常この値はバイトの配列であり、配列の最初の要素を渡す。
flags
CONST_DSCBLOCKFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundEnum クラス

DirectSoundEnum クラスのオブジェクトは、DirectSound で利用可能なデバイスのコレクションを表す。DirectX7.GetDSEnum メソッドを呼び出してこのオブジェクトを取得する。

このクラスには以下のメソッドがある。

情報 | GetCount
 | GetDescription
 | GetGuid
 | GetName


DirectSoundEnum.GetCount

DirectSoundEnum.GetCount メソッドは、列挙内のデバイス数を取得する。

object.GetCount() As Long

パラメータ

object
DirectSoundEnum オブジェクトを表すオブジェクト式。

戻り値

成功すれば列挙内のエントリ数を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectSoundEnum.GetDescription

DirectSoundEnum.GetDescription メソッドは、列挙内のデバイスのドライバ記述を取得する。

object.GetDescription(index As Long) As String

パラメータ

object
DirectSoundEnum オブジェクトを表すオブジェクト式。
index
列挙内のデバイスのインデックス。

戻り値

成功すればデバイスのドライバ記述を返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。


DirectSoundEnum.GetGuid

DirectSoundEnum.GetGuid メソッドは、列挙内のデバイスのユニーク識別子を取得する。

object.GetGuid(index As Long) As String

パラメータ

object
DirectSoundEnum オブジェクトを表すオブジェクト式。
index
列挙内のデバイスのインデックス。

戻り値

成功すればデバイスの GUID を文字列形式で返す。

エラー コード

失敗すればエラーが発生し、Err.Number が設定される。

参照

GUID の使用


DirectSoundEnum.GetName

DirectSoundEnum.GetName メソッドは、列挙内のデバイス ドライバの名前を返す。

object.GetName(index As Long) As String

パラメータ

object
DirectSoundEnum オブジェクトを表すオブジェクト式。
index
列挙内のデバイスのインデックス。

戻り値

成功すればデバイス ドライバ名を返す。これは一般的なデバイス名ではなく、DirectSoundEnum.GetDescription によって返される。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


型

ここでは、DirectSound が使う以下の型のリファレンス情報を提供する。

  • DS3DBUFFER
  • DS3DLISTENER
  • DSBCAPS
  • DSBPOSITIONNOTIFY
  • DSBUFFERDESC
  • DSCAPS
  • DSCBCAPS
  • DSCBUFFERDESC
  • DSCCAPS
  • DSCURSORS
  • WAVEFORMATEX


DS3DBUFFER

DS3DBUFFER 型は、3D サウンド バッファの位置、方向、動作を記述する。この型は、DirectSound3DBuffer.GetAllParameters と DirectSound3DBuffer.SetAllParameters の各メソッドと共に使われる。

Type DS3DBUFFER
    lConeOutsideVolume As Long
    lInsideConeAngle As Long
    lMode As CONST_DS3DMODEFLAGS
    lOutsideConeAngle As Long
    maxDistance As Single
    minDistance As Single
    vConeOrientation As D3DVECTOR
    vPosition As D3DVECTOR
    vVelocity As D3DVECTOR
End Type

メンバ

lConeOutsideVolume
サウンド コーン外部ボリューム。
lInsideConeAngle
内側サウンド プロジェクション コーンの角度。
lMode
設定される 3D サウンド処理モード。CONST_DS3DMODEFLAGS 列挙の定数のいずれかである。
lOutsideConeAngle
外側サウンド プロジェクション コーンの角度。
maxDistance
最大距離。
minDistance
最小距離。
vConeOrientation
サウンド プロジェクション コーンの方向を記述する D3DVECTOR 型。
vPosition
バッファの位置を記述する D3DVECTOR 型。
vVelocity
バッファの速度を記述する D3DVECTOR 型。


DS3DLISTENER

DS3DLISTENER 型は、3D グローバル パラメータとリスナーのプロパティを記述する。この型は、DirectSound3DListener.GetAllParameters と DirectSound3DListener.SetAllParameters の各メソッドと共に使われる。

Type DS3DLISTENER
    distanceFactor As Single
    dopplerFactor As Single
    rolloffFactor As Single
    vOrientFront As D3DVECTOR
    vOrientTop As D3DVECTOR
    vPosition As D3DVECTOR
    vVelocity As D3DVECTOR
End Type

メンバ

distanceFactor
距離単位でのメートル数。
dopplerFactor
速度を保持するバッファに対するドップラー シフトに適用される係数。
rolloffFactor
距離によるサウンドの減衰に適用される係数。
vOrientFront
リスナーの前方向を記述する D3DVECTOR 型。
vOrientTop
リスナーの上方向を記述する D3DVECTOR 型。
vPosition
リスナーの位置を記述する D3DVECTOR 型。
vVelocity
リスナーの速度を記述する D3DVECTOR 型。


DSBCAPS

DSBCAPS 型は、DirectSoundBuffer オブジェクトの能力を記述する。この型は、DirectSoundBuffer.GetCaps メソッドで使われる。

Type DSBCAPS
    lBufferBytes As Long
    lFlags As CONST_DSBCAPSFLAGS
    lPlayCpuOverhead As Long
    lUnlockTransferRate As Long
End Type

メンバ

lBufferBytes
バッファのサイズ。単位はバイト。
lFlags
CONST_DSBCAPSFLAGS 列挙の定数の 1 つまたは複数を指定する。
lPlayCpuOverhead
処理のオーバーヘッド。これは、サウンド バッファをミキシングするのに必要なメイン処理サイクルのパーセンテージとして指定される。ハードウェア バッファの場合、サウンド デバイスがミキシングを行うので、この値は 0 である。ソフトウェア バッファの場合、この値はバッファ フォーマットとシステム プロセッサの速度に依存する。
lUnlockTransferRate
データをバッファ メモリに転送する速度。単位は 1 秒あたりのキロバイト (KB/s)。

注意

DSBCAPS 型は、DirectSound.CreateSoundBuffer メソッドに渡される DSBUFFERDESC 型に似た情報を保持している。

DSBCAPS 型の lFlags メンバが保持するフラグは、DSBUFFERDESC 型で使われるフラグと同じものである。唯一の違いは、DSBCAPS 型ではバッファ メモリの場所に応じて DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらかのフラグが指定されることである。DSBUFFERDESC 型ではこれらのフラグはオプションであり、フラグの指定に応じて、バッファをハードウェアとソフトウェアのどちらかに強制的に配置できる。


DSBPOSITIONNOTIFY

DSBPOSITIONNOTIFY 型は、DirectSoundBuffer.SetNotificationPositions と DirectSoundCaptureBuffer.SetNotificationPositions の各メソッドによって使われる。

Type DSBPOSITIONNOTIFY
    hEventNotify As Long
    lOffset As Long
End Type

メンバ

hEventNotify
指定のオフセットに達したときにシグナル送信するイベントへのハンドル。DirectX7.CreateEvent メソッドを使ってこのハンドルを取得する。
lOffset
バッファの先頭から、通知イベントがトリガされる場所までのオフセット、または DSBPN_OFFSETSTOP。「注意」を参照すること。

注意

lOffset メンバ内で値 DSBPN_OFFSETSTOP が設定されている場合、再生またはキャプチャがバッファの最後に達した (そして再生またはキャプチャがループしていない) か、アプリケーションが DirectSoundBuffer.Stop または DirectSoundCaptureBuffer.Stop のどちらかのメソッドを呼び出したことが原因で、再生またはキャプチャが停止すると、イベントがシグナル送信される。

ボイス管理フラグと共に DSBCAPS_LOCDEFER と DSBCAPS_NOTIFY を使用している場合は、通知を保持するサウンドは設定できるが、到達することなくボイス管理によって終了されることもある。この場合、通知イベントは発生しない。


DSBUFFERDESC

DSBUFFERDESC 型は、新しい DirectSoundBuffer オブジェクトの必要な特徴を記述する。この型は、DirectSound.CreateSoundBuffer メソッドによって使われる。

Type DSBUFFERDESC
    lBufferBytes As Long
    lFlags As CONST_DSBCAPSFLAGS
End Type

メンバ

lBufferBytes
バッファのサイズ。単位はバイト。プライマリ バッファを作成するときは、この値は 0 でなければならない。セカンダリ バッファのサイズは、4 から &H0FFFFFFF (268,435,455) までの範囲でなければならない。
lFlags
バッファの能力を識別するフラグ。0、または CONST_DSBCAPSFLAGS 列挙の定数の 1 つまたは複数を指定する。

注意

lFlags メンバで使われる DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE の各フラグはオプションであり、互いに排他的である。DSBCAPS_LOCHARDWARE は、強制的にバッファをサウンド カードに配置されたメモリに配置する。DSBCAPS_LOCSOFTWARE は、可能であれば、強制的にバッファをメイン システム メモリに配置する。

DSBCAPS_CTRLPOSITIONNOTIFY フラグで作成されたサウンド バッファは、通知イベントを設定すべきである。このフラグでサウンド バッファを作成し、何も通知を設定しない場合、動作は定義されない。


DSCAPS

DSCAPS 型は、DirectSound.GetCaps メソッドが使う DirectSound デバイスの能力を指定する。

Type DSCAPS
    lFlags As CONST_DSCAPSFLAGS
    lFreeHw3DAllBuffers As Long
    lFreeHw3DStaticBuffers As Long
    lFreeHw3DStreamingBuffers As Long
    lFreeHwMemBytes As Long
    lFreeHwMixingAllBuffers As Long
    lFreeHwMixingStaticBuffers As Long
    lFreeHwMixingStreamingBuffers As Long
    lMaxContigFreeHwMemBytes As Long
    lMaxHw3DAllBuffers As Long
    lMaxHw3DStaticBuffers As Long
    lMaxHw3DStreamingBuffers As Long
    lMaxHwMixingAllBuffers As Long
    lMaxHwMixingStaticBuffers As Long
    lMaxHwMixingStreamingBuffers As Long
    lMaxSecondarySampleRate As Long
    lMinSecondarySampleRate As Long
    lPlayCpuOverheadSwBuffers As Long
    lPrimaryBuffers As Long
    lReserved1 As Long
    lReserved2 As Long
    lTotalHwMemBytes As Long
    lUnlockTransferRateHwBuffers As Long
End Type

メンバ

lFlags
デバイスの能力。CONST_DSCAPSFLAGS 列挙からの定数の 1 つまたは複数を指定する。
lFreeHw3DallBuffers、lFreeHw3DstaticBuffers、lFreeHw3DStreamingBuffers
空きまたは未割り当てのデバイスのハードウェア 3D 定位能力の記述。
lFreeHwMemBytes
サウンド カードの空きメモリのサイズ。単位はバイト。
lFreeHwMixingAllBuffers, lFreeHwMixingStaticBuffers、lFreeHwMixingStreamingBuffers
空きまたは未割り当てのデバイスのハードウェア ミキシング能力の記述。アプリケーションはこれらの値を使って、セカンダリ サウンド バッファの割り当てにハードウェア リソースが利用可能かどうかを判断できる。また、最大のミキシング能力を指定するメンバとこれらの値を比較すると、既に割り当てられているリソースを決定できる。
lMaxContigFreeHwMemBytes
サウンド カード上の空きメモリのうち、最大の連続ブロックのサイズ。単位はバイト。
lMaxHw3DallBuffers、lMaxHw3DstaticBuffers、lMaxHw3DStreamingBuffers
デバイスのハードウェア 3D 定位能力の記述。
lMaxHwMixingAllBuffers
ハードウェアでミキシングできるバッファの合計数。このメンバは lMaxHwMixingStaticBuffers と lMaxHwMixingStreamingBuffers の合計より小さい値を取る。リソースのトレードオフがしばしば発生する。
lMaxHwMixingStaticBuffers
スタティック サウンド バッファの最大数。
lMaxHwMixingStreamingBuffers
ストリーム サウンド バッファの最大数。
LMaxSecondarySampleRate、lMinSecondarySampleRate
このデバイスのハードウェア セカンダリ サウンド バッファがサポートする最小と最大のサンプリング レートの仕様。
lPlayCpuOverheadSwBuffers
(メイン システム メモリ内の) ソフトウェア バッファをミキシングするのに必要な処理オーバーヘッドを、CPU パーセンテージで記述した値。この値は、バス タイプ、プロセッサ タイプ、およびクロック速度に応じて変化する。

ソフトウェア バッファのアンロック転送速度は、データをどこにも転送する必要がないため 0 である。同様に、ハードウェア バッファの再生オーバーヘッドも、ミキシングがサウンド デバイスによって処理されるため 0 である。

lPrimaryBuffers
サポートされているプライマリ バッファの数。この値は常に 1 である。
lReserved1、lReserved2
将来の使用に予約。
lTotalHwMemBytes
スタティック サウンド バッファを保持するサウンド カード上のメモリ容量のサイズ。単位はバイト。
lUnlockTransferRateHwBuffers
ハードウェア スタティック サウンド バッファへのデータ転送速度。単位は 1 秒あたりのキロバイト (KB/s)。


DSCBCAPS

DSCBCAPS 型は、キャプチャ バッファの能力を記述する。この型は、DirectSoundCaptureBuffer.GetCaps メソッドによって使われる。

Type DSCBCAPS
    lBufferBytes As Long
    lFlags As CONST_DSCBCAPSFLAGS
    lReserved As Long
End Type

メンバ

lBufferBytes
キャプチャ バッファのサイズ。単位はバイト。
lFlags
デバイス能力を記述するフラグ。CONST_DSCBCAPSFLAGS 列挙の定数のいずれかを指定する。
lReserved
将来の使用に予約。


DSCBUFFERDESC

DSCBUFFERDESC 型は、キャプチャ バッファを記述する。この型は、DirectSoundCapture.CreateCaptureBuffer メソッドによって使われる。

Type DSCBUFFERDESC
    fxFormat As WAVEFORMATEX
    lBufferBytes As Long
    lFlags As CONST_DSCBCAPSFLAGS
End Type

メンバ

fxFormat
データのキャプチャに使うフォーマットを保持する WAVEFORMATEX 型。
lBufferBytes
作成されるキャプチャ バッファのサイズ。単位はバイト。
lFlags
デバイスの能力を指定するフラグ。CONST_DSCBCAPSFLAGS 列挙の定数のいずれかを指定する。


DSCCAPS

DSCCAPS 型は、キャプチャ デバイスの能力を記述する。この型は、DirectSoundCapture.GetCaps メソッドによって使われる。

Type DSCCAPS
    lChannels As Long
    lFlags As CONST_DSCCAPSFLAGS
    lFormats As CONST_WAVEFORMATFLAGS
End Type

メンバ

lChannels
デバイスがサポートするチャンネル数。1 はモノラル、2 はステレオを意味する。以下同様である。
lFlags
デバイスの能力。CONST_DSCCAPSFLAGS 列挙のメンバのいずれかを指定する。
lFormats
サポートされている標準フォーマット。CONST_WAVEFORMATFLAGS 列挙の定数の 1 つまたは複数を指定する。


DSCURSORS

DSCURSORS 型は、DirectSoundBuffer.GetCurrentPosition と DirectSoundCaptureBuffer.GetCurrentPosition の各メソッドによって使われる。

Type DSCURSORS
    lPlay As Long
    lWrite As Long
End Type

メンバ

lPlay
DirectSoundBuffer のカレント プレイ ポジション、または DirectSoundCaptureBuffer の現在のキャプチャ位置。
lWrite
DirectSoundBuffer のカレント ライト ポジション、または DirectSoundCaptureBuffer オブジェクトの現在の読み込み位置。この位置はサウンド バッファ内のオフセットであり、バイト単位で指定される。

注意

値はバッファの先頭からのオフセットであり、単位はバイトである。

lPlay が表すカーソルは、lWrite が表すカーソルのわずか前方にある。2 つのカーソル間のバッファ部分は、読み書きの準備ができていない。lWrite までの位置では、アプリケーションはキャプチャ バッファからのデータの読み込みと、セカンダリ バッファへのデータの書き込みを安全に行える。


WAVEFORMATEX

WAVEFORMATEX 型は、ウェーブフォーム オーディオ データのフォーマットを定義する。

Type WAVEFORMATEX
    lAvgBytesPerSec As Long
    lExtra As Long
    lSamplesPerSec As Long
    nBitsPerSample As Integer
    nBlockAlign As Integer
    nChannels As Integer
    nFormatTag As Integer
    nSize As Integer
End Type

メンバ

lAvgBytesPerSec
フォーマット用に要求された平均データ転送速度。単位は 1 秒あたりのバイト数である。nFormatTag が WAVE_FORMAT_PCM の場合、nAvgBytesPerSec は lSamplesPerSec と nBlockAlign の積に等しくなる。
lExtra
不使用。0 に設定する。
lSamplesPerSec
各チャンネルの再生や録音におけるサンプリング レート。単位は 1 秒あたりのサンプリング回数 (ヘルツ)。nFormatTag が WAVE_FORMAT_PCM の場合、lSamplesPerSec の通常の値は 8.0 kHz、11.025 kHz、22.05 kHz、および 44.1 kHz である。
nBitsPerSample
サンプリングあたりのビット数。nFormatTag が WAVE_FORMAT_PCM の場合、nBitsPerSample は 8 か 16 でなければならない。
nBlockAlign
ブロック アライメント。単位はバイト。ブロック アライメントは、nFormatTag フォーマット タイプのデータの最小単位である。nFormatTag が WAVE_FORMAT_PCM の場合、nBlockAlign は 8 (バイトあたりのビット数) で割った nChannels と nBitsPerSample の積に等しくなる。

バッファに読み書きされるデータは、常にブロックの先頭で開始しなければならない。たとえば、PCM データの再生を、サンプルの中間、つまり非ブロック整列の境界から開始するのは間違いである。

nChannels
ウェーブフォーム オーディオ データのチャンネル数。モノラル データは 1 つのチャンネルを使い、ステレオ データは 2 つのチャンネルを使う。
nFormatTag
ウェーブフォーム オーディオ フォーマットのタイプ。DirectSound では、このメンバが常に WAVE_FORMAT_PCM でなければならない。
nSize
追加フォーマット情報のサイズ。単位はバイト。WAVE_FORMAT_PCM フォーマットでは、このメンバは無視される。


列挙

DirectSound は列挙を使い、Visual Basic のステートメント補完機能を利用して定数をグループ化する。DirectSound で使う列挙を以下に示す。

  • CONST_DS3DAPPLYFLAGS
  • CONST_DS3DMODEFLAGS
  • CONST_DSBCAPSFLAGS
  • CONST_DSBLOCKFLAGS
  • CONST_DSBPLAYFLAGS
  • CONST_DSBSTATUSFLAGS
  • CONST_DSCAPSFLAGS
  • CONST_DSCBCAPSFLAGS
  • CONST_DSCBLOCKFLAGS
  • CONST_DSCBSTARTFLAGS
  • CONST_DSCBSTATUSFLAGS
  • CONST_DSCCAPSFLAGS
  • CONST_DSOUND
  • CONST_DSSCLFLAGS
  • CONST_DSSPEAKERFLAGS
  • CONST_WAVEFORMATFLAGS


CONST_DS3DAPPLYFLAGS

CONST_DS3DAPPLYFLAGS 列挙は、DirectSound3DBuffer と DirectSound3DListener の各クラスのさまざまなメソッドに対するパラメータとして使われる。この列挙のメンバは、新しい設定を適用するときの指定に使われる。

Enum CONST_DS3DAPPLYFLAGS
    DS3D_DEFERRED  = 1
    DS3D_IMMEDIATE = 0
End Enum
DS3D_DEFERRED
アプリケーションが DirectSound3DListener.CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。
DS3D_IMMEDIATE
即時に設定を適用する。

注意

いくつかのパラメータをすぐに変更する場合は、それらに DS3D_DEFERRED のフラグを付け、1 回の呼び出しでコミットするとより効率的である。


CONST_DS3DMODEFLAGS

CONST_DS3DMODEFLAGS 列挙は、DirectSound3DBuffer.GetMode と DirectSound3DBuffer.SetMode の各メソッドで使われ、3D サウンド処理の操作モードの設定と取得を行う。

Enum CONST_DS3DMODEFLAGS
    DS3DMODE_DISABLE      = 2
    DS3DMODE_HEADRELATIVE = 1
    DS3DMODE_NORMAL       = 0
End Enum
DS3DMODE_DISABLE
3D サウンド処理は無効になる。サウンドは、リスナーの頭の中心で発生しているように聞こえる。
DS3DMODE_HEADRELATIVE
サウンド パラメータ (位置、速度、および方向) は、リスナーのパラメータに対する相対的なものである。このモードでは、リスナーのパラメータが変化したときにサウンドの絶対パラメータが更新されるので、相対パラメータは一定に保たれる。
DS3DMODE_NORMAL
サウンド パラメータは、ワールド スペースに対する相対的なものである。これはデフォルトのモードである。


CONST_DSBCAPSFLAGS

CONST_DSBCAPSFLAGS 列挙は、DSBCAPS と DSBUFFERDESC の各型の lFlags メンバで使われ、バッファの能力を指定する。

Enum CONST_DSBCAPSFLAGS
    DSBCAPS_CTRL3D              =     16 (&H10)
    DSBCAPS_CTRLFREQUENCY       =     32 (&H20)
    DSBCAPS_CTRLPAN             =     64 (&H40)
    DSBCAPS_CTRLPOSITIONNOTIFY  =    256
    DSBCAPS_CTRLVOLUME          =    128 (&H80)
    DSBCAPS_GETCURRENTPOSITION2 =  65536 (&H10000)
    DSBCAPS_GLOBALFOCUS         =  32768 (&H8000)
    DSBCAPS_LOCHARDWARE         =      4
    DSBCAPS_LOCSOFTWARE         =      8
    DSBCAPS_MUTE3DATMAXDISTANCE = 131072 (&H20000)
    DSBCAPS_PRIMARYBUFFER       =      1
    DSBCAPS_STATIC              =      2
    DSBCAPS_STICKYFOCUS         =  16384 (&H4000)
End Enum
DSBCAPS_CTRL3D
バッファは 3D コントロールを使う。
DSBCAPS_CTRLFREQUENCY
バッファは周波数コントロール能力を備えていなければならない。
DSBCAPS_CTRLPAN
バッファはパン コントロール能力を備えていなければならない。
DSBCAPS_CTRLPOSITIONNOTIFY
バッファは位置通知能力を備えていなければならない。「注意」を参照すること。
DSBCAPS_CTRLVOLUME
バッファはボリューム コントロール能力を備えていなければならない。
DSBCAPS_GETCURRENTPOSITION2
DirectSoundBuffer.GetCurrentPosition が再生カーソルの新しい動作を使うべきであることを示す。DirectX for Visual Basic アプリケーションでは、常にこのフラグを設定する。
DSBCAPS_GLOBALFOCUS
バッファはグローバルなサウンド バッファである。このフラグを設定すると、ユーザーが他のアプリケーションにフォーカスを移動し、その新しいアプリケーションが DirectSound を使う場合でも、DirectSound を使っているアプリケーションは引き続きそのバッファを再生できる。例外は、協調レベルで DSSCL_EXCLUSIVE または DSSCL_WRITEPRIMARY フラグを設定した DirectSound アプリケーションにフォーカスを移動した場合である。この場合、他のアプリケーションからのグローバルなサウンドは聞こえなくなる。
DSBCAPS_LOCHARDWARE
バッファはハードウェア ミキシングを使う。デバイスがハードウェア ミキシングをサポートしていない場合や、必要なハードウェア メモリが利用不可能な場合は、DirectSound.CreateSoundBuffer メソッドの呼び出しは失敗する。アプリケーションは、このバッファがミキシング チャンネルを利用可能であると保証する必要がある。この状況は保証されていない。
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC が指定されていて、ハードウェア リソースが利用可能であっても、バッファをソフトウェア メモリに配置して、ソフトウェア ミキシングを使うようにする。
DSBCAPS_MUTE3DATMAXDISTANCE
最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないですむ。
DSBCAPS_PRIMARYBUFFER
バッファがプライマリ サウンド バッファであることを示す。この値を指定しない場合、セカンダリ サウンド バッファが作成される。
DSBCAPS_STATIC
サウンド カードのメモリが利用可能な場合、バッファがそこに置かれることを示す。バッファを強制的にメモリ (通常はドライバが管理するシステム メモリ) に配置する DSBCAPS_LOCHARDWARE とは異なる。
DSBCAPS_STICKYFOCUS
サウンド バッファのフォーカスの動作を変更する。ユーザーが DirectSound を使っていない他のアプリケーションに切り替えた場合でも、DirectSound を使っているアプリケーションはスティッキー フォーカス バッファの再生を続行できる。この状態ではアプリケーションの標準バッファは無音になるが、スティッキー フォーカス バッファは引き続き音を出す。ユーザーが他のアプリケーションを使いながら、ゲーム以外のアプリケーションのサウンドトラックを聞きたいと考える場合に役立つ。しかし、ユーザーが他の DirectSound アプリケーションに切り替えると、今までのアプリケーションのすべてのサウンド バッファ、この場合は標準バッファとスティッキー フォーカス バッファの両方が無音になる。

注意

VxD ドライバでは、サウンド バッファが DSBCAPS_CTRLPOSITIONNOTIFY で作成される場合、このバッファは常にソフトウェア バッファになる。これは、VxD ドライバ モデルが通知インターフェイスをサポートしないためである。ハードウェアが利用可能な場合、WDM ドライバにより、位置通知可能なバッファがハードウェアに存在することがある。このフラグ設定で作成されたバッファの再生中は、DSBPLAY_LOCHARDWARE フラグによる DirectSoundBuffer.Play の呼び出しは失敗する。

DSBCAPS_CTRLPOSITIONNOTIFY フラグで作成されたサウンド バッファには、通知イベントを設定しなければならない。NOTIFY フラグでサウンド バッファを作成し、何も通知を設定しないと、動作が定義されず、サウンドが 2 回再生される可能性がある。したがって、アプリケーションは通知イベントが設定されるまで、DSBCAPS_CTRLPOSITIONNOTIFY を使うべきではない。


CONST_DSBLOCKFLAGS

CONST_DSBLOCKFLAGS 列挙のメンバは、DirectSoundBuffer.ReadBuffer と DirectSoundBuffer.WriteBuffer の各メソッドの flags パラメータで使われ、バッファの読み込みと書き込み位置を指定する。

Enum CONST_DSBLOCKFLAGS
    DSBLOCK_DEFAULT         = 0
    DSBLOCK_ENTIREBUFFER    = 2
    DSBLOCK_FROMWRITECURSOR = 1
End Enum
DSBLOCK_DEFAULT
start パラメータで指定された位置からの読み込みと書き込みを行う。
DSBLOCK_FROMWRITECURSOR
カレント ライト ポジションへ書き込み、現在の読み込み位置から読み込む。この結果、DirectSoundBuffer.GetCurrentPosition メソッドの呼び出しが不要になる。start パラメータは無視される。
DSBLOCK_ENTIREBUFFER
バッファ全体からの読み込みとバッファ全体への書き込みを行う。size パラメータは無視される。


CONST_DSBPLAYFLAGS

CONST_DSBPLAYFLAGS 列挙は、DirectSoundBuffer.Play メソッドの flags パラメータで使われ、バッファの再生方法を指定する。

Enum CONST_DSBPLAYFLAGS
    DSBPLAY_DEFAULT = 0
    DSBPLAY_LOOPING = 1
End Enum
DSBPLAY_DEFAULT
カレント プレイ ポジションからオーディオ バッファの最後までを再生する。
DSBPLAY_LOOPING
カレント プレイ ポジションからバッファの最後までを再生し、バッファの先頭で再生を再開する。明示的に停止されるまで再生を続行する。


CONST_DSBSTATUSFLAGS

CONST_DSBSTATUSFLAGS 列挙のメンバは、バッファのステータスを記述し、DirectSoundBuffer.GetStatus メソッドによって返される。

Enum CONST_DSBSTATUSFLAGS
    DSBSTATUS_BUFFERLOST = 2
    DSBSTATUS_LOOPING    = 4
    DSBSTATUS_PLAYING    = 1
End Enum
DSBSTATUS_BUFFERLOST
バッファは失われており、再生やロックを行う前に復元しなければならない。
DSBSTATUS_LOOPING
バッファはループしている。この値が設定されていない場合、サウンド データの最後に達するとバッファが停止する。この値は、常に DSBSTATUS_PLAYING との組み合わせで返される。
DSBSTATUS_PLAYING
バッファは再生中である。


CONST_DSCAPSFLAGS

CONST_DSCAPSFLAGS 列挙は、DSCAPS 型の lFlags メンバで使われ、デバイスの能力を記述する。

Enum CONST_DSCAPSFLAGS
    DSCAPS_CERTIFIED       =   64 (&H40)
    DSCAPS_CONTINUOUSRATE  =   16 (&H10)
    DSCAPS_EMULDRIVER      =   32 (&H20)
    DSCAPS_PRIMARY16BIT    =    8
    DSCAPS_PRIMARY8BIT     =    4
    DSCAPS_PRIMARYMONO     =    1
    DSCAPS_PRIMARYSTEREO   =    2
    DSCAPS_SECONDARY16BIT  = 2048 (&H800)
    DSCAPS_SECONDARY8BIT   = 1024 (&H400)
    DSCAPS_SECONDARYMONO   =  256 (&H100)
    DSCAPS_SECONDARYSTEREO =  512 (&H200)
End Enum
DSCAPS_CERTIFIED
このドライバは Microsoft により試験と保証が行われている。
DSCAPS_CONTINUOUSRATE
このデバイスは、lMinSecondarySampleRate と lMaxSecondarySampleRate の各メンバ値の間のすべてのサンプリング レートをサポートする。一般にこれは、実際の出力レートが要求された周波数の ±10 ヘルツ (Hz) 以内であることを意味する。
DSCAPS_EMULDRIVER
このデバイスには DirectSound ドライバがインストールされていない。ウェーブフォーム オーディオ機能を通してエミュレートされている。性能の低下が予想される。
DSCAPS_PRIMARY16BIT
このデバイスは 16 ビット サンプリングでプライマリ サウンド バッファをサポートする。
DSCAPS_PRIMARY8BIT
このデバイスは 8 ビット サンプリングでプライマリ バッファをサポートする。
DSCAPS_PRIMARYMONO
このデバイスは単音のプライマリ バッファをサポートする。
DSCAPS_PRIMARYSTEREO
このデバイスはステレオのプライマリ バッファをサポートする。
DSCAPS_SECONDARY16BIT
このデバイスは、16 ビット サンプリングでハードウェア ミキシングのセカンダリ サウンド バッファをサポートする。
DSCAPS_SECONDARY8BIT
このデバイスは、8 ビット サンプリングでハードウェア ミキシングのセカンダリ バッファをサポートする。
DSCAPS_SECONDARYMONO
このデバイスは、ハードウェア ミキシングの単音セカンダリ バッファをサポートする。
DSCAPS_SECONDARYSTEREO
このデバイスは、ハードウェア ミキシングのステレオ セカンダリ バッファをサポートする。


CONST_DSCBCAPSFLAGS

CONST_DSCBCAPSFLAGS 列挙は、DSCBCAPS 型の lFlags メンバで使われ、デバイスの能力を指定する。

Enum CONST_DSCBCAPSFLAGS
    DSCBCAPS_DEFAULT    =  0
    DSCBCAPS_WAVEMAPPED = -2147483648 (&H80000000)
End Enum
DSCBCAPS_WAVEMAPPED
デバイスがサポートしないフォーマットに対して、Win32 ウェーブ マッパーを使う。


CONST_DSCBLOCKFLAGS

CONST_DSCBLOCKFLAGS 列挙は、DirectSoundCaptureBuffer.ReadBuffer と DirectSoundCaptureBuffer.WriteBuffer の各メソッドによって使われ、サウンド キャプチャ バッファからの読み込みとそのバッファへの書き込みを指定する。

Enum CONST_DSCBLOCKFLAGS
    DSCBLOCK_DEFAULT      = 0
    DSCBLOCK_ENTIREBUFFER = 1
End Enum
DSCBLOCK_DEFAULT
start パラメータの指定するオフセットで読み込みと書き込みを行う。
DSCBLOCK_ENTIREBUFFER
バッファ全体の読み込みと書き込みを行う。size パラメータは無視される。start が 0 でない場合、データ転送は start で開始し、バッファの先頭までラップ アラウンドする。


CONST_DSCBSTARTFLAGS

CONST_DSCBSTARTFLAGS 列挙のメンバは、DirectSoundCaptureBuffer.Start メソッドの flags メンバで使われ、サウンド データのキャプチャリングのときにキャプチャ バッファの動作を指定する。

Enum CONST_DSCBSTARTFLAGS
    DSCBSTART_DEFAULT = 0
    DSCBSTART_LOOPING = 1
End Enum
DSCBSTART_DEFAULT
バッファの最後に達するとキャプチャは停止する。
DSCBSTART_LOOPING
バッファの最後に達したら、先頭からキャプチャを再開し、明示的に停止されるまで続行する。


CONST_DSCBSTATUSFLAGS

CONST_DSCBSTATUSFLAGS 列挙のメンバは、キャプチャ バッファのステータスを記述し、DirectSoundCaptureBuffer.GetStatus メソッドによって返される。

Enum CONST_DSCBSTATUSFLAGS
    DSCBSTATUS_CAPTURING = 1
    DSCBSTATUS_LOOPING   = 2
End Enum
DSCBSTATUS_CAPTURING
キャプチャ バッファはサウンド データをキャプチャしている。
DSCBSTATUS_LOOPING
キャプチャ バッファはループしている。この値は、常に DSCBSTATUS_CAPTURING との組み合わせで返される。


CONST_DSCCAPSFLAGS

CONST_DSCCAPSFLAGS 列挙は、DSCCAPS 型の lFlags メンバで使われ、キャプチャ デバイス能力を記述する。

Enum CONST_DSCCAPSFLAGS
    DSCCAPS_DEFAULT    = 0
    DSCCAPS_EMULDRIVER = 32 (&H20)
End Enum
DSCCAPS_DEFAULT
デバイスは DirectSound キャプチャ可能である。
DSCCAPS_EMULDRIVER
デバイスに対して利用可能なドライバがないため、標準のウェーブ オーディオ機能が使われている。


CONST_DSOUND

CONST_DSOUND 列挙は、DirectSound 全体で使用されるいくつかの定数を保持する。

Enum
    DS3D_DEFAULTCONEANGLE         = 360 (&H168)
    DS3D_DEFAULTCONEOUTSIDEVOLUME = 0
    DS3D_DEFAULTDISTANCEFACTOR    = 1
    DS3D_DEFAULTDOPPLERFACTOR     = 1
    DS3D_DEFAULTMAXDISTANCE       = 1000000000 (&H3B9ACA00)
    DS3D_DEFAULTMINDISTANCE       = 1
    DS3D_DEFAULTROLLOFFFACTOR     = 1
    DS3D_MAXCONEANGLE             = 360 (&H168)
    DS3D_MAXDISTANCEFACTOR        = 10
    DS3D_MAXDOPPLERFACTOR         = 10
    DS3D_MAXROLLOFFFACTOR         = 10
    DS3D_MINCONEANGLE             = 0
    DS3D_MINDISTANCEFACTOR        = 0
    DS3D_MINDOPPLERFACTOR         = 0
    DS3D_MINROLLOFFFACTOR         = 0
    DSBFREQUENCY_MAX              = 100000 (&H186A0)
    DSBFREQUENCY_MIN              = 100 (&H64)
    DSBFREQUENCY_ORIGINAL         = 0
    DSBPAN_CENTER                 = 0
    DSBPAN_LEFT                   = -10000 (&HFFFFD8F0)
    DSBPAN_RIGHT                  = 10000 (&H2710)
    DSBPN_OFFSETSTOP              = -1 (&HFFFFFFFF)
    DSBSIZE_MAX                   = 268435455 (&HFFFFFFF)
    DSBSIZE_MIN                   = 4
    DSBVOLUME_MAX                 = 0
    DSBVOLUME_MIN                 = -10000 (&HFFFFD8F0)
    WAVE_FORMAT_PCM               = 1
End Enum


CONST_DSSCLFLAGS

CONST_DSSCLFLAGS 列挙は、DirectSound.SetCooperativeLevel メソッドの level パラメータで使われ、優先レベルを指定する。

Enum CONST_DSSCLFLAGS
    DSSCL_EXCLUSIVE    = 3
    DSSCL_NORMAL       = 1
    DSSCL_PRIORITY     = 2
    DSSCL_WRITEPRIMARY = 4
End Enum
DSSCL_EXCLUSIVE
アプリケーションを排他レベルに設定する。入力フォーカスが置かれているアプリケーションだけが音を出せる。DSBCAPS_GLOBALFOCUS フラグが設定されているアプリケーションのサウンドは無音になる。このレベルに設定されたアプリケーションは、DSSCL_PRIORITY レベルのすべての特権をも備えている。このレベルのアプリケーションが入力フォーカスを得ると、DirectSound は前回 DirectSoundBuffer.SetFormat メソッドを呼び出したときに指定されたハードウェア フォーマットを復元する。
DSSCL_NORMAL
アプリケーションを完全に協調可能なステータスに設定する。このレベルでは最もスムーズなマルチタスキングとリソース共有の動作が得られるが、プライマリ バッファのフォーマットの変更は行えず、出力もデフォルトの 8 ビット フォーマットに限定される。
DSSCL_PRIORITY
アプリケーションを優先レベルに設定する。この協調レベルに設定されたアプリケーションは、プライマリ サウンド バッファの DirectSoundBuffer.SetFormat メソッドを呼び出せる。
DSSCL_WRITEPRIMARY
アプリケーションを最上位の優先レベルに設定する。このアプリケーションはプライマリ サウンド バッファへの書き込みアクセスを保持する。DirectX for Visual Basic アプリケーションではこの協調レベルを設定すべきではない。


CONST_DSSPEAKERFLAGS

CONST_DSSPEAKERFLAGS 列挙は、DirectSound.GetSpeakerConfig と DirectSound.SetSpeakerConfig の各メソッドで使われ、スピーカ構成を指定する。

Enum CONST_DSSPEAKERFLAGS
    DSSPEAKER_GEOMETRY_MAX    = 180 (&HB4)
    DSSPEAKER_GEOMETRY_MIN    =   5
    DSSPEAKER_GEOMETRY_NARROW =  10
    DSSPEAKER_GEOMETRY_WIDE   =  20 (&H14)
    DSSPEAKER_HEADPHONE       =   1
    DSSPEAKER_MONO            =   2
    DSSPEAKER_QUAD            =   3
    DSSPEAKER_STEREO          =   4
    DSSPEAKER_SURROUND        =   5
End Enum
DSSPEAKER_GEOMETRY_MAX
2 つのスピーカはリスナーを中心として 180 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MIN
2 つのスピーカはリスナーを中心として 5 度の角度に置かれている。
DSSPEAKER_GEOMETRY_NARROW
2 つのスピーカはリスナーを中心として 10 度の角度に置かれている。
DSSPEAKER_GEOMETRY_WIDE
2 つのスピーカはリスナーを中心として 20 度の角度に置かれている。
DSSPEAKER_HEADPHONE
スピーカはヘッドホンである。
DSSPEAKER_MONO
スピーカはモノラルである。
DSSPEAKER_QUAD
スピーカは 4 チャンネルである。
DSSPEAKER_STEREO
スピーカはステレオである。
DSSPEAKER_SURROUND
スピーカはサラウンド サウンドである。


CONST_WAVEFORMATFLAGS

CONST_WAVEFORMATFLAGS 列挙は、DSCCAPS 型の lFormats メンバで使われ、サポートされる標準フォーマットを指定する。

Enum CONST_WAVEFORMATFLAGS
    WAVE_FORMAT_1M08 =    1
    WAVE_FORMAT_1M16 =    4
    WAVE_FORMAT_1S08 =    2
    WAVE_FORMAT_1S16 =    8
    WAVE_FORMAT_2M08 =   16 (&H10)
    WAVE_FORMAT_2M16 =   64 (&H40)
    WAVE_FORMAT_2S08 =   32 (&H20)
    WAVE_FORMAT_2S16 =  128 (&H80)
    WAVE_FORMAT_4M08 =  256 (&H100)
    WAVE_FORMAT_4M16 = 1024 (&H400)
    WAVE_FORMAT_4S08 =  512 (&H200)
    WAVE_FORMAT_4S16 = 2048 (&H800)
End Enum
WAVE_FORMAT_1M08
11.025 kHz、モノラル、8 ビット
WAVE_FORMAT_1M16
11.025 kHz、モノラル、16 ビット
WAVE_FORMAT_1S08
11.025 kHz、ステレオ、8 ビット
WAVE_FORMAT_1S16
11.025 kHz、ステレオ、16 ビット
WAVE_FORMAT_2M08
22.05 kHz、モノラル、8 ビット
WAVE_FORMAT_2M16
22.05 kHz、モノラル、16 ビット
WAVE_FORMAT_2S08
22.05 kHz、ステレオ、8 ビット
WAVE_FORMAT_2S16
22.05 kHz、ステレオ、16 ビット
WAVE_FORMAT_4M08
44.1 kHz、モノラル、8 ビット
WAVE_FORMAT_4M16
44.1 kHz、モノラル、16 ビット
WAVE_FORMAT_4S08
44.1 kHz、ステレオ、8 ビット
WAVE_FORMAT_4S16
44.1 kHz、ステレオ、16 ビット


エラー コード

エラーは負の値で表され、組み合わされることはない。この表は、DirectSound と DirectSoundBuffer のすべてのメソッドが返す可能性のある値の一覧である。個別のメソッドの返すエラー コードのリストについては、そのメソッドの記述を参照すること。

DS_OK
要求は成功し完了した。
DSERR_ALLOCATED
優先レベルなどのリソースが他の呼び出しによって既に使用中であるため、要求は失敗した。
DSERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DSERR_BADFORMAT
指定したウェーブ フォーマットはサポートされていない。
DSERR_BUFFERLOST
バッファ メモリが失われたため、復元しなければならない。
DSERR_CONTROLUNAVAIL
呼び出し元が要求するコントロール (ボリューム、パンなど) は利用できない。
DSERR_GENERIC
DirectSound サブシステム内で不確定のエラーが発生した。
DSERR_INVALIDCALL
このオブジェクトの現在の状態では、この関数は有効ではない。
DSERR_INVALIDPARAM
無効なパラメータが関数に渡された。
DSERR_NOAGGREGATION
このオブジェクトは COM 集合化をサポートしない。
DSERR_NODRIVER
利用可能なサウンド ドライバが存在しない。
DSERR_NOINTERFACE
要求された COM インターフェイスは利用できない。
DSERR_OTHERAPPHASPRIO
他のアプリケーションより高い優先レベルを持っているため、この呼び出しは成功しなかった。
DSERR_OUTOFMEMORY
DirectSound サブシステムは、呼び出し元の要求を完了するための十分なメモリを割り当てられなかった。
DSERR_PRIOLEVELNEEDED
呼び出し元は、関数を成功させるために必要な優先レベルを持っていない。
DSERR_UNINITIALIZED
DirectSound デバイスは初期化されていなかった。
DSERR_UNSUPPORTED
呼び出した関数はこの時点ではサポートされていない。


DirectSound のツールとサンプル

ここでは、DirectX SDK に含まれるサンプル アプリケーションについて説明し、DirectSound の使い方を例示する。説明する内容は次のとおりである。

  • DirectSound ツール
  • DirectSound C/C++ サンプル
  • DirectSound Visual Basic サンプル


DirectSound ツール

ここでは、DirectSound 能力のテストに使われる以下のアプリケーションについての情報を示す。

  • DSShow3D


DSShow3D

説明

DSShow3D を使うと、サウンド バッファと 3D リスナーのパラメータを変更できる。

パス

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DSound\Bin

ユーザーズ ガイド

[File] メニューの [Open] を選択すると、1 つまたは複数の短いサウンド ファイルを開き、それらを同時に再生できる。3D プロパティにアクセスするには、［File Open］ ダイアログ ボックスの ［Create as a 3D Buffer］ を選択しなければならないことに注意すること。今後、このオプションが自動的に設定されるようにするには、［Option］ メニューの ［Setting］ を選択し、［Open 3D as Default］ を選択する。

ファイルをこのプログラムのアイコンへドラッグして、そのファイルをロードすることもできる。または、次の構文に従ってコマンド ラインで指定してもよい。

DSShow3D [/PLAY [/LOOP]] [file] [file] ...

/PLAY を指定すると、指定したファイルは開いたと同時に再生される。/LOOP を追加すると、それらのファイルはループ再生される。しかし、/PLAY を省略して /LOOP だけを指定しても、何も起こらない。ファイル名は引用符 (' ') で囲んでもよい。

ウェーブ ファイルを開くたびに、DSShow3D はクライアント ウィンドウに一連のバッファ コントロールを表示する。すべての 3D バッファに適用されるリスナーの設定は、個別のウィンドウ内に表示される。

サウンドを再生するには、そのウィンドウ内の [Play] ボタンをクリックする。サウンドを連続再生するには、[Looped] ボタンをクリックする。クライアント ウィンドウのメニューから [Duplicate!] を選択すると、サウンド バッファの複製を作成できる。

バッファを閉じるには、バッファ ウィンドウの [File] メニューから [Close] を選択するか、単純にウィンドウを閉じる。

メイン ウィンドウの [Options] メニューから [Output Format] を選択すると、プライマリ バッファのフォーマットを変更できる。[Options] メニューの [Settings] を選択すると、好みの設定を行い、次にこのアプリケーションを起動したときにその設定を有効にできる。

[3DListener Object Settings] ウィンドウに変更を加えた場合、[Commit] ボタンをクリックするまではその変更結果は有効にならない。


DirectSound C/C++ サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

ここでは、DirectSound コンポーネントを使ったサンプル プログラムを取り上げる。以下のサンプル プログラムには、DirectSound の使い方と機能が示されている。

  • AdjustSound サンプル
  • CaptureSound サンプル
  • EnumDevices サンプル
  • FullDuplexFilter サンプル
  • Play3DSound サンプル
  • PlaySound サンプル
  • PlayStreaming サンプル
  • VoiceManagement サンプル

DirectX のサンプルには、Microsoft® Visual C++® のプロジェクト ワークスペース ファイルも含まれているが、これらのサンプルを正しくコンパイルする上で、開発環境の他の設定を検査する必要が生じることがある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。


AdjustSound サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

説明

AdjustSound は、スタティック DirectSound バッファを使ってウェーブ ファイルを再生する方法と、フォーカス、周波数、パン、およびボリュームを設定する方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\DSound\Src\AdjustSound

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DSound\Bin\AdjustSound.exe

ユーザーズ ガイド

[Sound File] ボタンをクリックし、ウェーブ ファイルをロードする。設定を選択し、[Play] ボタンをクリックする。サウンドの再生中でも設定を変更できる。

プログラミング上の注意

このサンプルは、2D セカンダリ バッファを使う基本的な手法を示す。


CaptureSound サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

説明

CaptureSound プログラムは、DirectSound を使ってサウンドをウェーブ ファイルへキャプチャする方法を示す。

マイクロフォン、または他のオーディオ入力が必要である。

パス

ソース : (SDK ルート)\Samples\Multimedia\DSound\Src\CaptureSound

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DSound\Bin\CaptureSound.exe

ユーザーズ ガイド

キャプチャ フォーマットをハイライトし、[OK] ボタンをクリックする。[Sound File] ボタンをクリックし、既存のファイルを開くか、新しいファイルを作成する。[Record] ボタンをクリックして録音を開始し、同じボタンをクリックして停止する。

プログラミング上の注意

このサンプルは、サウンドのキャプチャとウェーブ ファイルへの書き込みの基本的な手法を示す。


EnumDevices サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

説明

EnumDevices プログラムは、DirectSound と DirectSoundCapture デバイスを列挙する方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\DSound\Src\EnumDevices

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DSound\Bin\EnumDevices.exe

ユーザーズ ガイド

ドロップダウン リストから再生およびキャプチャするデバイスを選択し、[Create] ボタンをクリックする。

プログラミング上の注意

このサンプル コードは、DirectSoundEnumerate、DirectSoundCreate、DirectSoundCaptureEnumerate、DirectSoundCaptureCreate 関数の使い方を示す。


FullDuplexFilter サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

説明

FullDuplexFilter プログラムは、DirectSound を使って全二重オーディオとフィルタを実装する方法を示す。

マイクロフォン、または他のオーディオ入力が必要である。

パス

ソース : (SDK ルート)\Samples\Multimedia\DSound\Src\FullDuplexFilter

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DSound\Bin\FullDuplexFilter.exe

ユーザーズ ガイド

入力バッファのフォーマットと、次の出力バッファのフォーマットをハイライトする。[OK] ボタンをクリックする。

このプログラムは、オプショナルのフィルタを有効にできるダイアログ ボックスを表示し、キャプチャと再生を開始できるようにする。

プログラミング上の注意

このサンプルは主に、入力ソースとして waveIn、出力デバイスとして DirectSound を使って全二重オーディオを実現するために、システムに実装されているサウンド デバイスを扱う適切な順序を示すことを目的としている。


Play3DSound サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

説明

このアプリケーションは、DirectSound を使ってウェーブ ファイルを 3D ポジショニングにより再生する方法を示す。

パス

ソース : Mssdk\Samples\Multimedia\DSound\Src\Play3DSound

実行可能ファイル : Mssdk\Samples\Multimedia\DSound\Bin\Play3DSound.exe

ユーザーズ ガイド

[Sound File] ボタンをクリックし、ウェーブ ファイルをロードする。次に、[Select 3-D Algorithm] ダイアログ ボックスのオプションを選択する。[Play] ボタンをクリックしてサウンドをループ再生する。スライダを使って再生プロパティを調整する。変更をすぐに適用したくない場合は、[Defer] ボタンをクリックする。新しい設定を確定する頻度は、このボタンの横にあるスライダを使って調整できる。リスナーに対する音源の位置は、グラフ上に赤の点で表示される。グラフの下と横のスライダを使い、サウンドの動きの範囲を調整する。

プログラミング上の注意

このサンプルは、DirectSound の 3D 機能を使ったサウンドの基本的な再生と、IDirectSound3DListener::CommitDeferredSettings を使って同時に複数のパラメータを変更する方法を示す。


PlaySound サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルは、スタティック DirectSoundBuffer を使ってウェーブ ファイルを再生する方法を示す。

パス

ソース : Mssdk\Samples\Multimedia\DSound\Src\PlaySound

実行可能ファイル : Mssdk\Samples\Multimedia\DSound\Bin\PlaySound.exe

ユーザーズ ガイド

[Sound File] ボタンをクリックし、ウェーブ ファイルをロードする。次に、[Play] ボタンをクリックしてサウンドを再生する。サウンドを繰り返し再生するには、[Loop] を選択する。

プログラミング上の注意

ストリーム バッファを使う「PlayStreaming サンプル」と比較すること。


PlayStreaming サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルは、ストリーミングする DirectSoundBuffer を使ってウェーブ ファイルを再生する方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\DSound\Src\PlayStreaming

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DSound\Bin\PlayStreaming.exe

ユーザーズ ガイド

[Sound File] ボタンをクリックし、ウェーブ ファイルをロードする。次に、[Play] ボタンをクリックしてサウンドを再生する。サウンドを繰り返し再生するには、[Loop] を選択する。

プログラミング上の注意

スタティック バッファを使う「PlaySound サンプル」と比較すること。


VoiceManagement サンプル

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectSound Visual Basic サンプル」を参照すること。

[C++]

説明

このサンプルは、DirectDound バッファを再生するときに、ボイス割り当ておよびボイス管理のフラグを使う方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\DSound\Src\VoiceManagement

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DSound\Bin\VoiceManagement.exe

ユーザーズ ガイド

[Sound File] ボタンをクリックし、ウェーブ ファイルをロードする。ボイス管理オプションを選択する。(選択したオプションは、[Expected Behavior] フレームで説明される。)サウンドを繰り返し再生したい場合は、[Loop] を選択する。[Play] ボタンをクリックしてサウンドの再生を開始する。

プログラミング上の注意

バッファは、DSBCAPS_LOCDEFER フラグを使って作成されなければならない。これ以外のフラグで作成された場合は、DirectSound は実行時にハードウェアまたはソフトウェアへバッファを動的に配置できなくなる。


DirectSound Visual Basic サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ サンプル」を参照すること。

[Visual Basic]

ここでは、主に DirectSound コンポーネントを例示することを意図している、DirectX SDK 内のアプリケーションの要約を提供する。以下のサンプル プログラムは、DirectSound の使い方と能力を示す。

  • Capture サンプル
  • Full Duplex サンプル
  • Memo サンプル
  • PlaySound サンプル
  • SoundMix サンプル
  • StreamFrom サンプル
  • StreamTo サンプル

参照

DirectSound Visual Basic チュートリアル


Capture サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ サンプル」を参照すること。

[Visual Basic]

説明

Capture アプリケーションは、ウェーブ入力デバイスからサウンドをキャプチャする方法を示す。通常このデバイスは、マイクロフォン付きのサウンド カードである。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Src\Capture

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Bin\Capture.exe

ユーザーズ ガイド

[Record] ボタンをクリックし、サウンドを 20 秒間キャプチャしてから [Stop] ボタンをクリックする。バッファを再生でき、そのバッファをウェーブ ファイルに保存できる。

プログラミング上の注意

サウンド データを保存するためには、プログラムは DirectSoundBuffer.SaveToFile メソッドを使用できるように、出力バッファにこのデータをコピーしなければならない。


Full Duplex サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ サンプル」を参照すること。

[Visual Basic]

説明

Full Duplex アプリケーションは、サウンドのキャプチャと再生を同時に行う方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Src\Fullduplex

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Bin\Fullduplex.exe

ユーザーズ ガイド

[Select Device] ダイアログ ボックスで、入力デバイスと出力デバイスを選択する。サウンド カードを使って再生と録音を同時に行うには、コントロール パネルで設定を変更しなければならないことに注意すること。

[Select Formats] ダイアログ ボックスで、入力フォーマットを選択する。互換性のある出力フォーマットが一覧表示される。この一覧から 1 つを選択する。

[Full Duplex] ウィンドウで [Run] ボタンをクリックし、キャプチャと再生を開始する。

プログラミング上の注意

キャプチャ バッファと再生バッファは同じサイズなので、一方から読み込み、もう一方へコピーする際、アプリケーションはただ 1 つのポインタだけを保持する必要がある。


Memo サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ サンプル」を参照すること。

[Visual Basic]

説明

Memo サンプルは、データベースに格納するボイス メモを録音できる。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Src\Memo

実行可能ファイル : なし

ユーザーズ ガイド

このアプリケーションを実行するには、Microsoft Data Access Components がシステムにインストールされていなければならない。

カレンダの月を変更するには、矢印ボタンを使うか、先月もしくは翌月のグレーの日付上をクリックする。日付に対する [Current Memo] ダイアログ ボックスを表示するには、今月の日付上をダブルクリックする。メモを管理するにはボタンを使う。メモは 30 秒間表示できる。

プログラミング上の注意

キャプチャ バッファは、未加工のデータとしてデータベースに書き込まれる。


PlaySound サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ サンプル」を参照すること。

[Visual Basic]

説明

PlaySound サンプルは、DirectSound バッファの基本的な再生を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Src\PlaySound

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Bin\Vb_PlaySound.exe

ユーザーズ ガイド

[Sound File] ボタンをクリックし、ウェーブ ファイルをロードする。サウンドを連続して聞きたい場合は [Loop Sound] を選択してから、[Play] ボタンをクリックする。サウンドの再生中に周波数、パン、ボリュームを調整できる。

プログラミング上の注意

このサンプルは、ファイルからサウンド バッファを作成する方法、バッファを再生する方法、およびパラメータを変更する方法を示す。


SoundMix サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ サンプル」を参照すること。

[Visual Basic]

説明

SoundMix アプリケーションは、複数の DirectSound バッファを同時に再生する方法と、再生中にバッファのパラメータを変更する方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Src\SoundMix

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Bin\SoundMix.exe

ユーザーズ ガイド

[Load] ボタンをクリックし、1 つまたは複数のウェーブ ファイルをロードする。短いサウンドが繰り返されるよう、[Loop Play] チェック ボックスをオンにする。ボタンを使ってサウンドの再生、一時停止、停止を行い、スライダを使ってパラメータを変更する。

プログラミング上の注意

このアプリケーションは、サウンド バッファを個別に操作する方法と、プライマリ バッファにミキシングする方法を示す。


StreamFrom サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ サンプル」を参照すること。

[Visual Basic]

説明

StreamFrom アプリケーションは、ストリーム バッファとイベント通知を使って、ウェーブ ファイルからサウンドをストリームする方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Src\StreamFrom

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Bin\Streamfrom.exe

ユーザーズ ガイド

[Load File] ボタンをクリックし、比較的大きなウェーブ ファイルを開く。

プログラミング上の注意

このサンプルはプライマリ バッファ オブジェクトを作成し、ファイルが再生されていないときでも再生を行う。「プライマリ バッファの連続再生」を参照すること。


StreamTo サンプル

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「DirectSound C/C++ サンプル」を参照すること。

[Visual Basic]

説明

StreamTo アプリケーションは、サウンドをキャプチャ バッファへストリームする方法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Src\StreamTo

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DSound\Bin\Streamto.exe

ユーザーズ ガイド

バッファへのサウンドのキャプチャリングを開始するには、[Start Streaming] ボタンをクリックする。[End Streaming] ボタンをクリックすると、ファイル名を入力でき、サウンドをファイルに保存できる。

プログラミング上の注意

キャプチャ バッファは、サウンドを 2 秒保持できる。イベント通知は、データの一時ファイルへの書き込みをトリガするのに使われる。ユーザーがキャプチャを停止し、ファイル名を与えると、未加工のデータがウェーブ フォーマット情報と共に Resource Interchange File Format (RIFF) で保存される。


用語集

ここでは、Microsoft® DirectX® DSK のドキュメントで使用される技術用語を解説する。

A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z


A

アルファ チャネル (alpha channel)
アルファ値によって定義される、画像の不透明度。不透明度を定義するアルファ値は、ピクセルごとにほかの色成分と一緒に与えられるか (ARGB などの場合)、独立したアルファ サーフェス内でピクセルごとに与えられるか、またはサーフェス全体に固定の値で与えられる。
アルファ色成分 (alpha color component)
32 ビット カラーの不透明度を決める部分。32 ビット カラーの場合、アルファ値は、ピクセルごとにほかの色成分と一緒に与えられる (ARGB など)。まれに、独立したアルファ サーフェス内にピクセルごとのアルファ値が格納されている画像のアルファ値を指して ”アルファ成分” という場合もある。
アルファ定数 (alpha constant)
サーフェス全体に適用される不透明度 (アルファ値)。
アルファ エッジ ブレンド (alpha edge blend)
アルファ ブレンディング (およびアルファ チャネル情報) の用法の 1 つ。ピクセルの適用範囲に基づいてエッジを混色することにより、エイリアシングを減少させる方法である。
アンビエント属性 (ambient property)
環境光属性、ライトからの角度に依存せず反射するマテリアル属性。オブジェクトの向き、位置、表面特性などに関係なく、シーンのすべてを照らす光源およびマテリアル属性。シーンのすべての場所を同じ光源で照らすため、アンビエント光源に置かれたフレームの位置や向きは重要ではない。1 つのシーンでは、複数のアンビエント光源が結合されている。
異方性フィルタリング (anisotropic filtering)
異方性の歪みを補正するミップマップ フィルタリング モードの 1 つ。
異方性 (anisotropy)
表面が表示面に対して角度を持って位置する 3D オブジェクトのイメージに生じる、目に見える歪み。異方性はテクスチャ空間へ逆マップされたスクリーン ピクセルの伸び (長さ÷幅) として計測できる。
配列オブジェクト (array object)
1 つの配列にまとめられたオブジェクト群。配列オブジェクトを使うと、一連のオブジェクトすべてに何らかの処理を行う場合の操作が簡単になる。配列オブジェクトを扱うことができる COM インターフェイスには、GetElement と GetSize というメソッドが用意されている。この 2 つのメソッドはそれぞれ、配列要素へのポインタの取得、および配列サイズの取得を行う。
アタッチ (attach)
複数の DirectDrawSurface オブジェクトを接続して、Z バッファ付きの 3D ページ フリップングをサポートする場合などに必要となる複合構造体にすること。アタッチは双方向的なものではない。サーフェスをそのサーフェス自身にアタッチすることはできない。また、(システム メモリ内で) エミュレートされているサーフェスを、エミュレートによらないサーフェスにアタッチすることもできない。2 つのサーフェスをアタッチする場合、片方のサーフェスがテクスチャ マップでない限り、アタッチされるサーフェスどうしは同一サイズでなければならない。
アタッチ状態 (attached)
システムに物理的に接続されている状態。デバイスは、インストールされていても、アタッチ状態にはない場合もある。
アタック (attack)
マグニチュードが基本レベル (維持期間レベル) に達してフォース フィードバック エフェクトが始まるときの初期期間。
オーディオ ストリーム (audio stream)
サウンド データのこと。ミキシングされているものも、されていないものも含む。DirectSound は、再生中の各セカンダリ サウンド バッファから得たオーディオ ストリームをミキシングし、結果をプライマリ サウンド バッファに出力する。プライマリ サウンド バッファは、サウンド ハードウェアにオーディオ データを供給するバッファである。


B

バック バッファ (back buffer)
画面に表示されていないサーフェス。アプリケーションは、プライマリ サーフェスのイメージが画面に表示されている間に、ビットマップやその他のイメージをバック バッファに描き込むことができる。
後方クリップ面 (back clipping plane)
視錐台の奥行きの限界。この向こう側にあるオブジェクトはレンダリングされない。「前方クリップ面」を参照すること。
バンク セレクト (bank select)
MIDI のコントロール チェンジ。異なるグループ (バンク) からの音色選択を可能にする。各バンクの識別には、2 バイト コードが使用される。
ビルボード (billboard)
1 つの面がビューアに向くような方向で 3D シーンへ挿入されたプリミティブ。テクスチャ (通常は、アニメーション化されたスプライト) をビルボードに適用すると、3D オブジェクトがシーン上に現れる。
ビルボーディング (billboarding)
シーン上の 3D オブジェクトの外観をシミュレートする 2D 技法。アプリケーションは、プリミティブ (通常は矩形) を 1 つの面がビューアに向くような方向でシーンに挿入し、1 つのテクスチャまたは一連のテクスチャをそこへ適用する。適用されたテクスチャは、アニメーション化された 3D オブジェクトに見える。
ブレンディング係数 (blend factor)
テクスチャ ブレンディングにおいて、各色成分がどのように混色されるかを示す係数。
ブレンディング モード (blend mode)
テクスチャが適用先のサーフェスの色とどのように混色されるかを決定するアルゴリズム。
ブレンディング ステージ (blending stage)
テクスチャ カスケードの 1 ステップ。ブレンディング ステージは、1 つのテクスチャと、複数のテクスチャを混色する際に使用される一連のテクスチャ ブレンディング処理から成る。
ブリット (blit)
ビットのブロック転送。
境界チェック (bounds checking)
画面上のイメージが画面の境界内に表示されているかどうかをチェックする処理。
バンプ マッピング (bump mapping)
3D シーンでサーフェスが凸凹した外観をシミュレートする技法。深さの変化がテクスチャ内に格納され、標準のテクスチャ ブレンディング技術を使ってプリミティブに適用される。


C

カメラ (camera)
表示位置と方向を定義するため、ビューポートが用いる Direct3DRMFrame オブジェクト。ビューポートは、カメラ フレームの正の z 軸上にある可視オブジェクトだけを、y 軸上の正方向にレンダリングする。
カメラ空間 (camera space)
視点が原点に位置し、そこから z 軸の正の方向を見ている基準フレーム。オブジェクトの座標は、ビュー トランスフォームによりワールド空間からカメラ空間へとトランスフォームされる。
クライアント/サーバー セッション (client/server session)
サーバーだけがセッションの完全な状態を格納する DirectPlay セッション。各クライアントはセッション状態のサブセットだけを保持する。各クライアントは、サーバーからそのコンピュータに関する情報だけを受け取る。あるコンピュータで何かを変更した場合は、サーバーにその変更を伝える。その後、サーバーは変更についてどのクライアントに通知すべきかを判断する。「ピアツーピア セッション」を参照すること。
クリップ リスト (clip list)
サーフェスの可視領域を示す矩形のリスト。既に DirectDrawClipper オブジェクトにウィンドウ ハンドルが結び付けられている場合は、クリップ リストを設定することはできない。
クリッパー (clipper)
DirectDrawClipper オブジェクトのこと。
コーデック (codec)
COmpressor and DECompressor (圧縮伸張システム) を表す略語。
衝突検出 (collision detection)
2 つのイメージに画面上の同じ位置を共有するピクセルがないか判断する処理。「ヒット検出」を参照すること。
カラー キー (color key)
透明エフェクトや半透明エフェクトに使用される色を示す値。たとえば、ハードウェアのブリット機能を使用した場合、矩形領域内のカラー キーとして設定された値を持つピクセル以外のすべてのピクセルがブリットされる。これは、矩形でないスプライトをサーフェス上に作成する。
色空間 (color space)
3 つ以上の座標値で色を表すモデルのこと。色空間モデルは、色の各成分を、3 次元以上のデカルト座標系にマッピングする。色空間は、色のコード化と可視化に複数の手法を用いる場合もある。最も一般的な色空間モデルは、RGB と YUV の 2 つである。
色空間の変更 (color-space conversion)
異なる色空間間で色を変換すること。通常は、ビデオ ソースの YUV カラーから表示用の RGB 色への変更のことをいう。
カラー テーブル (color table)
n 色のカラー値の配列 (通常は RGB 三原色)。
複合サーフェス (complex surface)
ルート サーフェスにアタッチされている複数の DirectDrawSurface オブジェクトをまとめて指す用語。複合サーフェス構造体は、ルートを破棄することによってしか破棄できない。
制御セグメント (control segment)
再生の一定局面を制御するミュージカル セグメント。通常はプライマリ セグメントであるが、制御セグメントとしてセカンダリ セグメントを指定することができる。
カリング (culling)
レンダリング処理で 3D プリミティブの背面等を省くこと。
カレント プレイ ポジション (current play position)
DirectSound バッファ内での現在のサウンドの再生位置。
カレント ライト ポジション (current write position)
DirectSound バッファ内の安全にデータを変更できる位置。


D

暗色光 (dark light)
シーンからライトを除去する光源。ライトの色に負の値を指定することにより作成できる。
DCI
Display Control Interface (ディスプレイ コントロール インターフェイス) の略。DCI は、Intel® および Microsoft® により定義されたインターフェイスで、ビデオ メモリに直接アクセスすることによって、より高いグラフィックス パフォーマンスを提供する。
デッド ゾーン (dead zone)
その範囲内では軸が中心に位置していると見なされる軸内の領域。
デカール (decal)
ビジュアル オブジェクトとして直接レンダリングされるテクスチャ。ビューポートに位置を合わせた矩形にレンダリングされる。
転送先カラー キー (destination color key)
ブリットの場合は置き換えられる色、オーバーレイの場合は転送先のサーフェス上で覆い隠される色のこと。
デバイス ウィンドウ (device window)
Microsoft® DirectDraw® が表示用に使用するアプリケーション ウィンドウ。必ず画面に表示される。アプリケーションは、与えられたコンピュータにアタッチされている各表示デバイスに 1 つずつデバイス ウィンドウを持つことができる。「フォーカス ウィンドウ」を参照すること。
ディフューズ属性 (diffuse property)
ディフーズ反射属性、ライトからの入射角に依存して反射するマテリアル属性。マテリアルの反射および発光を決定する属性は 4 つあるが、ディフューズ属性はそのうちの 1 つである。エミッション属性、アンビエント属性、および「スペキュラ属性」を参照すること。
ディレクショナル (directional)
フレームにアタッチされるが、すべてのオブジェクトを同じ輝度で照らす光源の記述。あたかも光源がオブジェクトから無限の距離に位置するかのようなエフェクトを与える。ディレクショナル ライトは、向きは持つが位置を持たず、一般に、太陽のような遠く離れた光源をシミュレートするために用いられる。
DirectPlay アドレス (DirectPlay address)
Microsoft® DirectPlay® がロビー サーバー、アプリケーション、DirectPlay、およびサービス プロバイダの間でアドレス情報を渡すために使用するデータ形式。DirectPlay アドレスは、グローバル ユニーク識別子 (GUID) でタグ付けされた一連の可変長のデータ チャンクである。GUID は、DirectPlay に必要なアドレス情報をすべて提供する。アドレス情報の例として、サーバーのネットワーク アドレス、プレーヤーのネットワーク アドレス、プレーヤーの電子メール名、セッションのネットワーク アドレスなどが挙げられる。
DLS
DownLoadable Sounds (ダウンローダブル サウンド) の略。DownLoadable Sample (ダウンローダブル サンプル) の略として使用される場合もある。ソフトウェアのデジタル サンプルで、シンセサイザが楽器の音色を生成する際に使用される。


E

エミッション属性 (emissive property)
自己発色属性、マテリアル (素材) のライトに依存しない色属性を示すマテリアル属性、発光または発色。マテリアルの反射および発光を決定する属性は 4 つあるが、エミッション属性はそのうちの 1 つである。アンビエント属性、ディフューズ属性、および「スペキュラ属性」を参照すること。
エミッション設定 (emissive setting)
「エミッション属性」を参照すること。
有効フレーム (enable frame)
光源を適用することができるフレーム。
エンベロープ (envelope)
初期 (アタック) と終期 (フェード) でのマグニチュードを変更することにより、フォース フィードバック エフェクトの形状を定義する一連の値。
偶数フィールド (even field)
ビデオ フレームを構成する奇数/偶数のフィールド セットの 2 つ目のフィールド。フィールド 2 とも呼ばれる。
実行バッファ (execute buffer)
3D シーンを記述する、すべての情報が格納されていて独立した情報パケット。実行バッファには、頂点のリストが格納され、それに続いて命令ストリームが格納される。命令ストリームは、オペレーション コード (オペコード) と、そのオペコードによる処理の対象となるデータから成る。


F

面 (face)
メッシュ内の単一のポリゴン。
フェード (fade)
フォース フィードバック エフェクトの中央部分 (維持期間) からフォース フィードバック エフェクトが終わるまでの期間。
フォールオフ (falloff)
スポットライトの内側の円錐面と外側の円錐面との間の光の減衰。
フィールド (field)
ビデオ ストリーム内の単一のビデオ フレームの半分に相当するデータ。各フィールドには、1 つおきの走査ラインのデータが格納される。フィールドの送受信は、奇数フィールド、偶数フィールドの順で行われる。
フィールド極性 (field polarity)
フィールドが偶数フィールドと奇数フィールドのどちらであるかを表す特性。走査ライン中に VREF の立ち下がりエッジが発生しない場合は、奇数フィールドである。走査ライン中に VREF の立ち下がりエッジが発生すれば、偶数フィールドである。
フリマリング (flimmering)
z 値の分離が不完全なため、転写時に 3D プリミティブ上に発生する表示のちらつき。背面のテクスチャの一部のピクセルが前面のテクスチャ上にレンダリングされたり、その逆が起こったりする。
フリップ (flip)
バック バッファとフロント バッファのアドレスをスワップ (交換) すること。これにより、バック バッファ内のイメージをフロント バッファへコピーまたはブリットする必要がない、その結果、バック バッファ内にあったイメージを効率よく画面に表示できる。
フリッピング チェーン (flipping chain)
相互に接続されており、フリップ可能な一連のサーフェス。フリップを参照すること。
フリッピング サーフェス (flipping surface)
フリッピング可能なメモリ。フリップを参照すること。
フォーカス ウィンドウ (focus window)
DirectDraw がウィンドウ メッセージを受け取るために使用するアプリケーション ウィンドウ。実際に画面に表示される場合もあれば、表示されない場合もある。フォーカス ウィンドウのメッセージ ハンドラは、DirectDraw により転送された入力メッセージを受け取る。アプリケーションが持つことのできるフォーカス ウィンドウは 1 つだけである。「デバイス ウィンドウ」を参照すること。
フレーム (frame)
シーン上のオブジェクトの配置の基になる非表示のボックス。シーン上でのオブジェクトの位置は、適切な基準フレームに対する空間的な関係を指定することによって決めることができる。ビジュアル オブジェクトは、その位置や向きをフレームから取得する。

動画やアニメーション内の単一のイメージも同様である。

フロント バッファ (front buffer)
フリッピング チェーンの先頭のバッファ。多くの場合、画面に表示されるプライマリ サーフェスを指す。ただし、ほかの場合 (テクスチャのフリッピング チェーンなど) は、3D エンジンがそこからテクスチャを取得してくるためのサーフェスであって、プライマリ サーフェスでもなければ表示もされない場合もある。また、フリッピング オーバーレイ サーフェスの場合のフロント バッファは、画面に表示されはするが、プライマリ サーフェスにオーバーレイされたサーフェスにすぎない。「プライマリ サーフェス」を参照すること。
前方クリップ面 (front clipping plane)
視錐台の前面の限界。前方クリップ面よりもカメラ寄りにあるオブジェクトはレンダリングされない。前方クリップ面の高さにより、ビューのフィールドが決まる。「後方クリップ面」を参照すること。


G

ゲンロッキング (genlocking)
2 つのビデオ信号の同期を取る処理。ジェンロッキングされた信号は元の信号と同期が取れているため、元の信号とミキシングすることができ、ディゾルブ、ワイプなどのトランジション エフェクトが可能となる。
グリッド (grid)
拍 (ビート) の小分割。ビートごとのグリッド数は、Microsoft® DirectMusic® の拍子記号の一部である。
グルーブ レベル (groove level)
スタイルの再生中にミュージックに指定される値。指定された時間にどのパターンを選択できるかを判断する。コンポーザは、広範囲のグルーブ レベルを各パターンに割り当てる。
グループ (group)
プレーヤーの論理的な集まり。DirectPlay はセッション内でグループをサポートする。プレーヤーのグループを作成することにより、アプリケーションはグループに単一のメッセージを送信でき、グループ内のすべてのプレーヤーがそのメッセージを受信できる。これにより、グループがネットワークのマルチキャスト機能をアプリケーションに示す手段になる。

グループは、セッション内のプレーヤーをまとめるために使用することができる。プレーヤーは、1 つ以上のグループに属すことができる。DirectPlay では、グループやそのメンバシップを管理することができる。


H

HAL
Hardware Abstraction Layer (ハードウェア アブストラクション レイヤ) の略。ハードウェアおよびデバイス ドライバのメカニズムにより構成され、個々のデバイス固有の実装詳細をアプリケーションから隠す働きを担う。使用しているハードウェアが、アプリケーションから要求された機能を実装していなかった場合は、その機能をソフトウェアによりエミュレートする。
ハードウェア ブリット (ブロック転送) (hardware blitter)
ディスプレイ アダプタに組み込まれており、効果的なブリット処理を行うハードウェア コンポーネント。
HEL
Hardware Emulation Layer (ハードウェア エミュレーション レイヤ) の略。ハードウェアがサポートしていない機能をソフトウェアによりエミュレートする。
HID
Human Interface Device (ヒューマン インターフェイス デバイス) の略。人間がコンピュータを制御できるデバイスを示す USB クラス。
ヒット検出 (hit detection)
「衝突検出」を参照すること。
ホスト (host)
DirectPlay で、DPID_SYSMSG という ID を持つ仮想プレーヤー。ホストは、システム メッセージやセッション内のすべてのプレーヤーに送られるメッセージを管理する。
HREF
Horizontal REFresh (水平リフレッシュ) の略。HREF 信号は、ビデオ ストリーム内で、ディスプレイが新しい走査ラインを開始しようとしていることを知らせるときにアクティブになる。「VREF」を参照すること。


I

インデックス パレット (index palette)
ほかのパレット オブジェクトのインデックスとなるエントリを持つ DirectDrawPalette オブジェクト。
IPX サービス プロバイダ (IPX service provider)
Internetwork Packet Exchange (IPX) プロトコルを使ってローカル エリア ネットワーク (LAN) 上で通信を行うために Windows Sockets を使用するサービス プロバイダ。このサービス プロバイダは、非保証のメッセージ交換だけをサポートする。1 台のコンピュータは、IPX を使って 1 つの DirectPlay セッションのみのホストとして機能する。
IRE 率 (IRE scale)
International Radio Engineers の割合。IRE は、ブロードキャスト ビデオ信号の輝度を定義する 0 ~ 100 までの範囲の値。IRE 値が高くなると、ビデオ信号の輝度が増加する。7.5 IRE の輝度ユニット (National Television System Committee (NTSC) 信号の黒によるカットオフのしきい値) では、NTSC ディスプレイ デバイスの電子銃はカットオフされ、画面にはイメージが表示されない。


L

遅延時間 (latency)
応答遅延時間。たとえば Microsoft® DirectSound® では、サウンド バッファが再生されてから実際にサウンドがスピーカから出てくるまでの間の時間である。DirectPlay では、パケットが指定された宛先に到達するまでの時間である。
ライト マップ (light map)
3D シーンのライティング情報の入ったテクスチャ。
ロビーアウェア アプリケーション (lobby-aware application)
ロビーからの起動を最小限サポートするアプリケーション。
ロビー クライアント (lobby client)
ユーザーのコンピュータ上で実行されるロビー管理ルーチン。アプリケーションの起動、ユーザー インターフェイスの更新、ロビー サーバーとの通信を行う。
ロビー プロバイダ (lobby provider)
ロビー サーバーの開発者が提供するクライアント コンポーネント (ダイナミックリンク ライブラリ)。これには、DirectPlay の要求に応じてロビー サーバーとの通信機能が実装される。
ロビー サーバー (lobby server)
リモート サーバー上で実行されるロビー管理ルーチン。ロビー サーバーは、管理対象のアプリケーションに接続してきたユーザーに関するすべての情報を調整する。
ロビー セッション (lobby session)
クライアントとサーバーが相互運用するよう特別に記述されていなかったロビー サーバーへの接続。


M

マッハ バンド (Mach bands)
3D プリミティブのブレンディングがスムーズに行われない色範囲。
マテリアル (material)
サーフェスがどのように光を反射および発色するかを決定する属性。マテリアル (素材) には、エミッション属性 (ライトに依存せず発色)、アンビエント属性、ディフューズ属性、およびスペキュラ属性の 4 つの構成要素がある。反射の明るさは、強度の設定により決定される。
メッシュ (mesh)
単純なポリゴンで表現される面が集まったもの。
ミップマップ (mipmap)
MIP マップとも呼ばれる。(MIP は、英語の "much in little" を意味するラテン語 “multium in parvo” の略。) 同一イメージが徐々に低解像度になっていく一連のテクスチャのことで、1 つのイメージに何種類ものフィルタをかけることにより作成される。オブジェクトが近くに表示されるときには高解像度のイメージが使用され、オブジェクトが遠ざかるに従って (つまり画面での表示が小さくなるに従って) 低解像度のイメージが使用される。
ミキシング (mixing)
DirectSound で、再生中の複数のサウンド バッファを合成し、生成されたサウンドをプライマリ サウンド バッファ (サウンド ハードウェアにオーディオ データを出力するバッファ) へ書き込む処理。処理時間が範囲内に収まるかどうかを考慮しなければ、ミキシングできるバッファの数に制限はない。
モード X (Mode X)
標準 VGA のモード 13 から派生したハイブリッド ディスプレイ モード。このモードでは、VGA ディスプレイ アダプタの EGA マルチ ビデオ プレーン システムを使用することにより、最大 256 KB のディスプレイ メモリが使用可能となっている (モード 13 で使用可能なディスプレイ メモリ量は 64 KB)。
モデル座標 (model coordinates)
ローカル原点に対する相対座標。「モデル空間」、「ワールド座標」を参照すること。
モデル空間 (model space)
単一の 3D モデル用のローカル原点に対する相対的な頂点を使用する (モデル座標のための) 基準フレーム。
マルチパス テクスチャ ブレンディング (multipass texture blending)
各パスごとに一度ずつテクスチャ上にブレンディングして、3D プリミティブを繰り返しレンダリングする手法。この手法は、さまざまな特殊エフェクトを得るために幅広く使用されている。


N

ナグリング (nagling)
TCP/IP サービス プロバイダに、小さなデータ パケットをバッファに入れて大きなデータ パケットにしてから送信させるようにするアルゴリズム。ナグリングは、小さなデータ パケットを 1 つの大きなパケットに結合できるまで蓄積するか、事前のパケットの確認を受け取るまでサーバーに待機するよう要求することにより、TCP/IP サーバーが多くの非常に小さなパケットを送信しないようにする。ナグリングはメッセージ送信のオーバーヘッド (および必要な帯域幅) を削減できるが、小さなデータ パケットを送信する前に遅れが生じる (遅延時間が増える)。
法線ベクトル (normal vector)
サーフェスから垂直に伸びる架空の線で、面の向きの定義に使用される。


O

奇数フィールド (odd field)
ビデオ フレームを構成する奇数/偶数のフィールド セットの 1 つ目のフィールド。
オフスクリーン サーフェス (off-screen surface)
メモリ上の概念的な矩形領域。一般に、表示する前にバック バッファへブリットするビットマップを格納するのに使用する。通常、スプライトが格納される。
オペコード (opcode)
実行バッファ内の頂点を解釈する方法やシステムの状態を変更する方法を定義するオペレーション コード。
オーバードロー (overdraw)
スクリーン ピクセルが描画される平均回数。
オーバーレイ サーフェス (overlay surface)
メモリ上の概念的な矩形領域。オーバーレイ サーフェスに格納されたイメージ情報は、そのオーバーレイ サーフェスが適用されるプライマリ サーフェスのイメージ情報の上に被せられる。オーバーレイは、その他のすべてのスクリーン要素よりも上にあるものとして処理される。
オーバーレイ Z オーダー (overlay z-order)
オーバーレイどうしのクリッピングの順番を決定する。これにより、ハードウェア スプライト システムを DirectDraw に実装することが可能になる。


P

ページ フリッピング (page flipping)
「フリップ」を参照すること。
パレット (palette)
オブジェクトやアプリケーションが使用する色セット。DirectX では、DirectDrawPalette オブジェクトのことを指す。
パレット インデックス (palette index)
色を選択するときに使用されるパレット テーブル配列のインデックスとなる整数。
パレット化されたサーフェス (palettized surface)
アタッチされたパレットを色情報の格納場所として使用する DirectDrawSurface オブジェクト。
パン値 (pan value)
左右のオーディオ チャネルの相対音量。100 分の 1 デシベル単位で表される。
パラレル ポイント (parallel point)
平行な光線でオブジェクトを照らすが、光の向きはその位置から決定されるような光源の記述。たとえば、パラレル ポイント光源の両側に置かれた 2 つのメッシュがある場合、各メッシュは光源に面している方の面が照らされる。
P チャンネル (PChannel)
Performance channel (パフォーマンス チャンネル) の略。特定のポート上にある特定のチャンネル グループ内の MIDI チャンネル。
ピアツーピア セッション (peer-to-peer session)
セッションの完全な状態がそのセッション内のすべてのコンピュータ上に複製される DirectPlay セッション。セッション記述データ (プレーヤーとグループのリスト、および各セッションに関する名前とリモート データ) は、すべてのコンピュータに複製される。1 台のコンピュータで何か変更した場合は、ほかのすべてのコンピュータに即座に通知される。これは、DirectPlay の通信のデフォルト モードである。「クライアント/サーバー セッション」を参照すること。
パースペクティブ補正 (perspective correction)
遠近補正のこと。カメラから角度をなして離れていくポリゴンにテクスチャ マップを適用する際に、ポリゴンの奥行きがわかるようにテクスチャをポリゴン上に広げる技法。Direct3D では、パースペクティブ補正は自動的に行われる。
ピッキング (pick)
ビューポートの 2D 座標で与えられた場所にあるビジュアル オブジェクトをシーン内で探すこと。
PID
Physical Interface Device (物理インターフェイス デバイス) の略。人間がコンピュータからフォース フィードバックを感じることのできる USB クラス。
ピッチ (pitch)
ビットマップ ラインの先頭を表すアドレスと次のラインの先頭を表すアドレスの間の距離。バイト単位で表される。すべてのディスプレイ メモリが 1 つの線形ブロックとして配置されているとは限らないので、メモリ ピッチとメモリ幅を混同しないこと。たとえば、矩形メモリのように、ビットマップの幅とキャッシュ部分が足されたものがディスプレイ メモリのピッチとなっている場合もある。「幅」、「ストライド」を参照すること。
プレーヤー (player)
DirectPlay セッションの参加者。各プレーヤーには、プレーヤー間でのメッセージ交換を可能にするためにプレーヤー ID が与えられる。
プレーヤー ID (player ID)
DirectPlay セッションの参加者の作成時に参加者に与えられる、その参加者固有の番号。アプリケーションは、プレーヤー ID を使って参加者どうしにメッセージ交換を行わせる。ホストには、常に DPID_SYSMSG というプレーヤー ID が与えられる。
ポイント ライト (point light)
その起点からすべての方向へ均等に光を放射する光源。
点リスト (point list)
最も単純な 3D プリミティブ。3D 空間内の互いに接続されていない点の集まりである。
強度 (power)
マテリアルのスペキュラ属性で、スペキュラ ハイライトの鮮明度を決める値。この値が 5 のときは金属的な外観になり、値がもっと高くなるとよりプラスチック的な外観になる。
プライマリ サウンド バッファ (primary sound buffer)
ゲーム中にユーザーの耳に聞こえる音が格納されるバッファ。一般にはセカンダリ バッファのサウンドをミキシングした結果の出力先とされるが、カスタム ミキシングやその他の特別処理を行うために直接アクセスすることもできる。
プライマリ サーフェス (primary surface)
ディスプレイに表示されるイメージが格納されるメモリ領域。DirectX では、プライマリ サーフェスは、プライマリ DirectDrawSurface オブジェクトにより表される。
射影空間 (projection space)
射影トランスフォームによってワールド空間の位置からトランスフォームされた頂点の入った基準フレーム。射影空間は、シーン上のすべての頂点が -1.0 ~ 1.0 の範囲内の x 座標と y 座標、および 0.0 ~ 1.0 の範囲内の z 座標を持つ同次立方体空間である。遠近補正後同次空間とも呼ばれる場合もある。
射影トランスフォーム (projection transformation)
頂点に行列を適用して、頂点をカメラ空間から射影空間へ変更するトランスフォーム。


Q

クオータニオン (quaternion)
ベクトルを定義する [x, y, z] 値に追加される 4 つ目の要素。3D 軸とその回りの回転を定義する。


R

参照カウント (reference count)
コンポーネント オブジェクト モデル (COM) オブジェクトをコントロールするためのカウンタ。参照カウントは、オブジェクトが作成されたときに 1 に設定される。その後、インターフェイスがオブジェクトに結び付けられるたびにインクリメントされ、インターフェイス接続が切断されるとデクリメントされる。参照カウントが 0 になると、オブジェクトは破棄される。破棄されたオブジェクトへのインターフェイスはすべて無効となる。
リージョン (region)
DirectMusic では、楽器の音色を合成する際に、そのデジタル サンプルが使用される音色の範囲。
ルート フレーム (root frame)
Direct3D での、親フレームを持たない (つまり、フレームの階層構造の最上位に位置する) フレーム。ルート フレームには、シーンを構成する一連のオブジェクトすべてが格納される。「シーン」を参照すること。


S

飽和 (saturation)
ある範囲において、実際の値が極限に近くなったときに極限値を調整すること。たとえば、値の範囲の最大値が 1,000 だった場合に、最大飽和点を 900 に設定すると、899 より大きい値はすべて 1,000 に調整される。
シーン (scene)
仮想環境を構成する一連のオブジェクトすべてを指す。可視オブジェクト、サウンド、ライト、フレームが含まれる。Direct3D では、ルート フレーム内のオブジェクト全体のことを指す。
スクリーン空間 (screen space)
座標がフレーム バッファ内の 2D (2 次元) の位置に直接マッピングされている基準フレーム。ディスプレイやその他の表示デバイスに表示するためのフレームである。スクリーン空間の座標は、ビューポートのパラメータから作成したトランスフォーム行列を使って射影空間の座標をトランスフォームすることにより得られる。
セカンダリ サウンド バッファ (secondary sound buffer)
オーディオ メモリ内の部分のうち、アプリケーションで再生される個々のサウンドが格納される部分。ここに格納されたサウンドは、1 回のイベントとして再生することもできれば、ループ サウンドとして繰り返し再生することもできる。セカンダリ バッファを使うと、実際に利用できるサウンド バッファ メモリよりも大きいサウンドを再生することも可能である。この場合、セカンダリ バッファは、サウンドのこれから再生される部分だけを格納したキューとしての役割を果たす。
セキュア セッション (secure session)
セッションに参加する前に、既知のユーザーのデータベースに対してすべてのユーザーが認証されたセッション。セキュア セッションでは、DirectPlay のシステム メッセージはすべてデジタル署名され、送信元の身元が確認される。機密性の高い情報を送信する特定のシステム メッセージは暗号化される。1 人のプレーヤーから発生し、セッション内のほかのすべてのプレーヤーにブロードキャストしなければならないシステム メッセージは、まず最初にサーバーに送信される。その後、サーバーはメッセージに署名し、セッション内のほかのすべてのコンピュータにメッセージを転送する。デフォルトでは、プレーヤーからプレーヤーへのメッセージは署名されず、サーバー経由でルーティングされない。
サービス プロバイダ (service provider)
DirectPlay がネットワークを介した通信を行うために使用するダイナミックリンク ライブラリ。サービス プロバイダには、メッセージを送受信するために必要となるネットワーク固有のコードがすべて含まれている。各種オンライン サービスやネットワーク オペレータは、サービス プロバイダを提供することにより、ハードウェア、プロトコル、通信媒体、ネットワーク資源などに特殊なものを使用することができる。
セッション (session)
DirectPlay で、リモート コンピュータ上で実行され互いに通信し合っているいくつかのアプリケーションのインスタンス。アプリケーションがほかのコンピュータとの通信を開始する場合、アプリケーションはいずれかのセッションに属している必要がある。アプリケーションはネットワーク上の既存のセッションすべてを列挙し、それらの 1 つに参加したり、新しいセッションを作成し、作成したセッションにほかのコンピュータが参加するのを待機したりすることができる。アプリケーションがセッションの一部になると、プレーヤーを作成し、セッション内のほかのすべてのプレーヤーとメッセージを交換できる。
サウンド バッファ (sound buffer)
DirectSound のオーディオ データが格納されるメモリ部分。サウンド バッファには、プライマリとセカンダリがあり、またスタティックとストリームの区別もある。
転送元カラー キー (source color key)
ブリットの場合は転送でコピーされない色、オーバーレイの場合は出力先で表示されない色のこと。
スペキュラ属性 (specular property)
スペキュラ反射属性、ライトからの入射光の角度と視点への反射光の角度の両方に依存したマテリアル属性。マテリアルの光の反射および発色を決定する属性は 4 つあるが、スペキュラ属性はそのうちの 1 つである。アンビエント属性、ディフューズ属性、および「エミッション属性」を参照すること。
スポットライト (spotlight)
円錐状の光を放つ光源。円錐の中にあるオブジェクトだけが照らされる。円錐は 2 つの輝度を生成する。中央の明るい部分はポイント ライトと同じ働きをし、周囲の薄暗い部分は周辺の暗い影とマージされる。
スタティック サウンド バッファ (static sound buffer)
完全なサウンドが格納される部分。サウンド全体を一度にバッファに書き込めるため、便利である。
スティッキー フォーカス (sticky focus)
DirectSound で、バッファを所有するアプリケーションが入力フォーカスを持っていないときにもサウンド バッファを再生できる能力。たとえば、ユーザーがほかのアプリケーションで作業している間にも、DirectSound アプリケーションはサウンド バッファを再生し続けることができる。
ストリーム サウンド バッファ (streaming sound buffer)
バッファの再生中に動的にオーディオ データを読み込めるため、サイズが小さいにもかかわらず長いサウンドを再生できるサウンド バッファ。たとえば、3 秒間分のオーディオ データを格納できるバッファを使って 2 分間のサウンドを再生したりできる。ストリーム バッファを使うと、スタティック バッファの場合よりも必要なメモリ量がはるかに少なくなる。
伸縮 (stretching)
サイズの異なる転送先にイメージをブリットすること。この処理を直接サポートするハードウェアもある。
ストライド (stride)
ピッチと同義。「幅」を参照すること。
サーフェス (surface)
ビジュアル イメージが格納されるメモリ。たいていの場合はディスプレイ メモリ内に置かれるが、システム メモリに置くこともできる。「複合サーフェス」、「オフスクリーン サーフェス」、「オーバーレイ サーフェス」、「プライマリ サーフェス」を参照すること。
維持期間 (sustain)
フォース フィードバック エフェクトの基本マグニチュードが到達されている期間。アタッチからフェードまでの間。
システム メッセージ (system message)
DirectPlay では、プレーヤー ID の DPID_SYSMSG からのメッセージ。すべてのシステム メッセージは DWORD 値で始まる。


T

TCP/IP サービス プロバイダ (TCP/IP service provider)
TCP/IP プロトコルを使ってインターネットやローカル エリア ネットワーク (LAN) 上で通信を行うために Windows Sockets を使用するサービス プロバイダ。非保証メッセージに User Datagram Protocol (UDP) パケットを使用し、保証付きメッセージに TCP を使用する。1 台のコンピュータは、TCP/IP を使って複数の DirectPlay セッションのホストとして機能できる。
テアリング (tearing)
スクリーンのリフレッシュ レートがアプリケーションのフレーム レートと同期していないときに発生する、表示がうねるように見える現象。1 つのフレームの上部が別のフレームの下部と同じに表示され、2 つのイメージの間に裂け目が生じる。
テッセレーション (tessellation)
3D グラフィックスでオブジェクトのサーフェスを三角形ポリゴンに細分化すること。
テクセル (texel)
テクスチャ内の単一の要素。テクスチャがオブジェクトに適用されたとき、テクセルがスクリーン上のピクセルに対応することはめったにない。アプリケーションは、テクスチャ フィルタリングを使って、シーン内にピクセルを作成するためにシステムがテクセル間を補間する方法を制御できる。
テクスチャ (texture)
Direct3D でビジュアル オブジェクトに適用される、ピクセルが矩形に並んだ配列。
テクスチャ ブレンディング (texture blending)
テクスチャの色をマップ先のサーフェスの色と組み合わせる技法。
テクスチャ座標 (texture coordinates)
各テクスチャのどのテクセルがオブジェクトの各頂点に割り当てられるかを決める座標。
テクスチャ フィルタリング (texture filtering)
1 つまたは複数のテクスチャから得たテクセルの色を、3D プリミティブのイメージを構成するピクセルにマップする処理。
テクスチャ マッピング (texture mapping)
テクスチャをオブジェクトに適用すること。テクスチャはフラットなイメージなのに対し、多くの場合オブジェクトは立方体であるため、テクスチャは、テクスチャ座標とラッピング フラグを使って、オブジェクトの表面にマップされなければならない。テクスチャ座標と「ラップ」を参照すること。
スラッシング (thrashing)
次のフレームでテクスチャ メモリを再利用するよう、現在のフレームで使用したテクスチャを削除すること。
スロットリング (throttling)
元の伝送形態よりもメッセージを早く送信しないよう、メッセージ数を制限すること。


U

単位ベクトル (unit vector)
マグニチュード (長さ) 1.0 のベクトル。
USB
Universal Serial Bus (ユニバーサル シリアル バス) の略。


V

VBI
Vertical Blanking Interval (垂直帰線消去間隔) の略。ブロードキャスト ビデオでは、ビデオ フレーム間に短い時間がある。この間に、ディスプレイ デバイスは次のフレームのためにディスプレイをリフレッシュする。
ベロシティ (velocity)
ミュージックでは、MIDI キーが押される速度。この速度は、いくつかの音色のティンバーで音符が再生される動的レベルとほぼ等しい。

3D サウンドでは、ドップラー シフトを計算するために音源またはリスナーが移動していると見なされる場合の速度。

頂点 (vertex)
3D 空間の点。ポリゴンやプリミティブは複数の頂点を持つ。頂点は 3D 座標だけではなく、法線、マテリアル、テクスチャ座標などの属性を持つことができる。
ビデオ フレーム (video frame)
ビデオ ストリーム内の単一のイメージ。1 つの奇数フィールドと 1 つの偶数フィールドから成る。「フィールド」を参照すること。
ビュー空間 (view space)
「カメラ空間」を参照すること。
ビュー トランスフォーム (view transformation)
モデルの頂点に行列を適用して、モデルの向きをワールド空間からビュー空間へ変えるトランスフォーム。
視錐台 (viewing frustum)
ビューポートのカメラに対して相対的に配置されたシーン内の 3D ボリューム。視錐台の中にあるオブジェクトは、画面に表示される。遠近ビューでは、前方クリップ面と後方クリップ面の間にある仮想的なピラミッド型のボリュームとなる。正射ビューでは、立方体になる。
ビューポート (viewport)
3D シーンがどのように 2D ウィンドウにレンダリングされるかを決める矩形。ビューポートは、デバイス上での、オブジェクトがレンダリングされる領域も決める。
VREF
Vertical REFresh (垂直リフレッシュ) の略。VREF は、ビデオ ストリーム内で、ディスプレイが新しい画面を開始しようとしていることを知らせるときにアクティブになる。「HREF」を参照すること。


W

幅 (width)
メモリ内に格納されているビットマップの 1 つのラインの始点を表すアドレスとそのラインの終点を表すアドレスの距離。この距離は、メモリ内でのビットマップの幅だけを表すものである。矩形メモリ内のキャッシュなどでビットマップの次のラインの始点に達するまでに必要となるような余分なメモリは、この距離には含まれない。
ワールド座標 (world coordinates)
シーンの頂点に達する相対座標。「モデル座標」、「ワールド空間」を参照すること。
ワールド空間 (world space)
ワールド座標 (3D シーン内の単一の原点に対する相対的な頂点を表す) により使用される基準フレーム。
ワールド トランスフォーム (world transformation)
モデルの頂点に行列を適用して、モデルの向きをモデル空間からワールド空間へ変えるトランスフォーム。
ラップ (wrap)
面やメッシュのテクスチャ座標の計算に使用される処理。基本的なラッピング タイプには、フラット、円柱、球体、クロムがある。


Z

Z バッファ (z-buffer)
シーン上の各ピクセルの深度を格納したバッファ。z 値の小さいピクセルは z 値の大きいピクセルを上書きする。
Z ファイティング (z fighting)
「フリマリング」を参照すること。


Direct3D 保持モードの紹介

Microsoft® Direct3D® 保持モードにようこそ。保持モードでは、パーソナル コンピュータ上で 3 次元 (3D) グラフィックス環境の作成、リアルタイム操作が可能になる。

最終更新日: 2000年4月13日

保持モードについて
Direct3D保持モードの概要を簡単に紹介する。
はじめに
Direct3D保持モード バージョン 6.x の新機能、学習を始めるポイント、共通項目の参照先について説明する。さらに、3D で点を操作するのに必要な基礎的な知識も一部紹介する。座標系、変換、ポリゴン、三角形の展開図と扇形、ベクトル、頂点、クォータニオンなどについても説明する。
基礎知識
3Dグラフィックスを組み込むプログラムを作成する際に理解しておくべき技術的な基礎知識について説明する。この節では、座標系と変換の基礎について説明する。
アーキテクチャ
Direct3D保持モード オブジェクト、およびオブジェクトがサポートするインターフェイスについて説明する。参照カウントや Z バッファに関するヒントも紹介する。
概要
いくつかの Direct3D保持モード インターフェイスの使い方を説明する。すべての保持モード インターフェイスの詳細については、「C++/COMリファレンス」を参照すること。
チュートリアル
簡単な保持モード アプリケーションのコードを、順を追って説明する。
C++/COMリファレンス
インターフェイス メソッド、非メンバ関数、コールバック関数について、構文、パラメータの記述、フラグの記述、使用上の注意を説明する。さらに、Direct3D 構造体のメンバ、列挙型、その他の定義型、および返される可能性のあるエラー値についても説明する。
Visual Basicリファレンス
インターフェイス、クラス、メソッド、およびコールバック インターフェイスについて、構文、パラメータの記述、フラグの記述を説明する。さらに、Direct3D 保持モード型のメンバ、列挙型、その他の定義型、および返される可能性のあるエラー値についても説明する。
サンプルのイントロダクション
Microsoft Developer Studio™ を使用して Direct3D保持モードのサンプルをビルドする方法を説明する。参考にするサンプルを決められるように、サンプルの要約も紹介する。
DirectXファイルフォーマット
DirectX (.x) ファイルのファイル フォーマットについて説明する。.x ファイルを使用すると、アプリケーションは事前定義オブジェクトを読み込み、構築したメッシュ情報をリアルタイムで書き込むことができるようになる。テンプレート、サンプル、ファイルのバイナリフォーマット、および他のパッケージの 3D モデルを xファイルにコンバートする Conv3ds.exe についても説明する。
用語集
Direct3D保持モードで使用されている基本的なグラフィクス用語を定義する。

注 : アイコン external link は、microsoft.com 以外のサイトへアクセスする URL を表している。Direct3D保持モード サイトに戻るには、［戻る］ ボタンを使用する。ほとんどの外部リンクは、Microsoftが管理していないサーバにつながっている。管理外のサーバに関する Microsoft の公式見解を参照していただきたい。


保持モードについて

Microsoft® Direct3D®保持モードは、パーソナルコンピュータ上で3次元（3D）グラフィックスを実現するためにMicrosoftが提供するソリューションである。3D環境を作成し、リアルタイムに処理したい場合は、Direct3D保持モードAPIを使用するべきである。

Direct3D保持モードの基礎にある概念は、以前に3Dグラフィックスのコードを書いたことのある開発者にとっては馴染み深いものだろう。しかし、初めて3Dプログラミングを行う開発者は、「Direct3D保持モードアーキテクチャ」および「基礎知識」の説明を十分に理解する必要がある。これから3Dプログラミングの経験のある開発者も、始めたばかりの開発者も、このSoftware Development Kitに含まれているサンプルコードを注意深く読んでいただきたい。サンプルコードは、実際のアプリケーションに保持モードを実装する方法を示している。

Direct3D保持モードのプログラミングのガイダンスについては、「Direct3D保持モードチュートリアル」を参照すること。


はじめに

この節では、Microsoft® Direct3D® 保持モード バージョン 6.x の新機能、およびマニュアルで特定の項目を調べる参照先について説明する。また、詳細なコメントを付けたサンプル コードのウォークスルーも行う。

  • Direct3D保持モードの新機能
  • ドキュメントの構成
  • オブジェクトの回転：RMBegin1サンプル
  • フレーム階層：RMBegin2サンプル
  • デバイスの列挙：RMEnumサンプル


Direct3D保持モードの新機能

この節では、Microsoft ® Direct3D ® 保持モード バージョン 6.0 の新機能とドキュメントについて説明する。

Microsoft Visual Basic のプログラマは、Direct3D 保持モードの使い方について、「Visual Basic リファレンス」を参照すること。

この項では次の項目について説明する。

  • 新しい項目
  • 新しいインターフェイス

新しい項目

「はじめに」の大半は、新しく作成されており、以下の項目を含んでいる。

  • 「ドキュメントの構成」では、特定の項目についてドキュメントを調べる場合の参照先を解説している。
  • 「オブジェクトの回転：サンプル RMBegin1」では、オブジェクトを回転する簡単なサンプルのウォークスルーを行う。
  • 「フレーム階層：サンプル RMBegin2」 では、太陽、地球、月が他のオブジェクトのまわりを正しく回転する簡単なサンプルを順を追って説明する。
  • 「デバイスの列挙：RMEnumサンプル」では、デバイスを列挙するサンプルを順を追って説明する。
  • 「冗長な状態変更の削除」では、パフォーマンスを向上するために、現在値と同じ値になる状態の設定を回避する方法について説明する。

このドキュメントの「サンプル」の節は、新しく作成したものである。この節は、「Direct3D保持モードサンプルのイントロダクション」から始まる。ここには、次の新しい項目が含まれている。

  • Developer Studio 5.0 を使用したサンプルのビルド
  • Direct3D保持モードのサンプル

「Direct3D保持モードの概要」には、次の新しい項目が含まれている。

  • インターフェイス階層
  • インターフェイスの変更点

新しいインターフェイス

Microsoft® Direct3D® 保持モードバージョン6.0では、いくつかのインターフェイス、および、新しいメソッドにより旧バージョンのインターフェイスに新機能を追加した多数のインターフェイスが導入されている。新しいインターフェイスおよびメソッドの完全なリストについては、「インターフェイスの変更点」を参照すること。インターフェイスの継承については、「インターフェイス階層」を参照すること。

このドキュメントでは、最新バージョンのインターフェイスを紹介するものとし、バージョンによる機能の相違については説明するが、重複した説明は行わない。たとえば、旧バージョンのマニュアルでは、IDirect3DRMTexture3::GetDecalSize、IDirect3DRMTexture2::GetDecalSize、IDirect3DRMTexture::GetDecalSizeについて、ほとんど同じ説明が別々に記述されていたが、このドキュメントでは、最新バージョンのIDirect3DRMTexture3::GetDecalSizeでまとめて説明している。

「C++/COMリファレンス」には、以下の新しいインターフェイスが含まれている。

  • 保持モードバージョン6.0では、新しいIDirect3DRM3インターフェイスとDirect3DRM3オブジェクトが導入された。IDirect3DRM3で作成されたMeshBuilder3オブジェクトは、Direct3D直接モードのDrawPrimitiveインターフェイスを使用する。IDirect3DRM3で作成された照明は、直接モードの新機能を利用して、直接モードのD3DLIGHT2構造体を使用する。IDirect3DRM3は、IDirect3DRM2とIDirect3DRMの全機能を提供する。フラグパラメータがCreateDeviceFromSurfaceに追加され、Zバッファを作成しないことを通知できるようになった。RegisterClientメソッドとUnregisterClientメソッドが追加された。さらに、IDirect3DRM3により、使用するジオメトリが右手座標系か左手座標系かを設定および取得するGetOptionsメソッドとSetOptionsメソッドが追加された。

  • すべてのオブジェクトは、新しいIDirect3DRMObject2インターフェイスを実装している。IDirect3DRMObject2は、他の新しいインターフェイスと異なり、旧バージョンのメソッドをすべて実装しているわけではない。IDirect3DRMObject2とIDirect3DRMObjectについては、このドキュメントで個別に説明する。IDirect3DRMObject2には、新しいIDirect3DRM3::RegisterClientメソッドとIDirect3DRM3::UnregisterClientメソッドとともに動作するSetClientDataメソッドとGetClientDataメソッドが追加された。さらに、IDirect3DRMObject2には、GetDirect3DRMメソッドとGetAgeメソッドも追加された。

  • IDirect3DRMAnimation2には、AddKey、DeleteKeyByID、GetKeys、ModifyKeyメソッドが追加され、アニメーションキーへのアクセスが可能になった。また、対応するアニメーションのフレームを返すGetFrameメソッドも追加された。

  • 新しいIDirect3DRMAnimationArrayインターフェイスを使用すると、GetSizeを使って配列のアニメーション数を取得し、GetElementを使ってアニメーションのインターフェイスを要求できる。

  • IDirect3DRMAnimationSet2にGetAnimationsメソッドが追加され、構成アニメーションを取得できるようになった。

  • 新しいIDirect3DRMClippedVisualインターフェイスを使用すると、レンダリング前に任意のプレーンにビジュアルオブジェクトをクリップできる。新しいClippedVisualオブジェクトは、Direct3DRM3オブジェクトから作成する。

  • IDirect3DRMDevice3に、所定の基準に従ってテクスチャ形式を選択するFindPreferredTextureFormatメソッドが追加された。また、IDirect3DRMDevice3にはいくつかのメソッド (GetStateChangeOptions、LightStateChange、RenderStateChange、SetStateChangeOptions)が追加されて、冗長な状態変更を削除できるようになった。

  • IDirect3DRMFace2にSetTextureメソッドが追加され、高さと幅が2の累乗以外のテクスチャを指定できるようになった。

  • IDirect3DRMFrame3は、モデル空間とワールド空間との間でより多彩な変換を行うメソッドを提供する。4×4行列を取得し、トラバーサルオプションを設定および取得し、フォグ処理に頂点フォグまたはテーブルフォグのどちらを使用するかを取得および設定する。また、IDirect3DRMFrame3は、マテリアルのオーバーライドを設定および取得するメソッドも提供する。SetOrientationメソッドは、スケーリングと傾斜を処理できるようになった。

  • IDirect3DRMMaterial2にGetAmbientメソッドとSetAmbientメソッドが追加され、マテリアルのプロパティが詳細に制御できるようになった。

  • IDirect3DRMMeshBuilder3に、面、法線、頂点オブジェクトを削除するメソッドが追加された。また、EmptyメソッドとOptimizeメソッドも追加された。他の新しいIDirect3DRMMeshBuilder3メソッドは、1本または複数の法線、法線数、テクスチャトポロジ、1つまたは複数の頂点、およびメッシュビルダの状態 (有効または無効) を取得する。このインターフェイスを使用すると、頂点と法線を設定したり、サブメッシュおよびメッシュビルダの親メッシュを作成および取得することができる。また、IDirect3DRMMeshBuilder3により、アプリケーションは、AddTrianglesを使用して新しい三角形を追加したり、新しい面を明示的に作成することができる。

  • IDirect3DRMShadow2にメソッドが追加され、ビジュアル、照明、プレーン、オプションシャドウパラメータを作成後に変更できるようになった。SetOptionsを使用すると、ブレンドの透明度を有効にするときに、ビジュアルアーチファクトを削除するオプションを設定できる。

  • IDirect3DRMTexture3は、Changedメソッドを拡張して、テクスチャの変更済領域を指定できるようにした。IDirect3DRMTexture3は、さらに、テクスチャ管理キャッシングメソッドのGetCacheOptionsとSetCacheOptionsも提供している。新しいIDirect3DRMTexture3のメソッドとしては、他に、GetSurface、SetDownSampleCallback、SetValidationCallbackがある。

  • IDirect3DRMViewport2は、Clearにフラグパラメータを追加して、ターゲットサーフェス、Zバッファサーフェス、ダーティ矩形リストをクリアするかどうか通知する。


ドキュメントの構成

ここでは、Microsoft® Direct3D® 保持モードのドキュメントで特定の項目を探す参照先について説明する。

保持モードを初めて使用する場合は、「インターフェイスの概要」を最初に読み、一般的な概念を理解すること。3Dプログラミングを初めて行う場合は、「基礎知識」を読むこと。 これにより、チュートリアルとサンプルに対する理解が深まる。「サンプル」と「チュートリアル」に掲載したコードの処理の詳細については、「リファレンス」および「インターフェイス」を読むこと。「用語集」では、一般的な用語の定義を説明している。

上級開発者は、DirectX ファイル フォーマットの詳細情報が必要になる可能性がある。 .

どこを参照するか

次のリストは、C++/COM のプログラマがよく使う情報と、その参照先の一覧である。
情報 | 参照先
エラーコード | 戻り値
インターフェイスの継承 | インターフェイス階層
インターフェイスの履歴 | インターフェイスの変更点
インターフェイス | インターフェイス
定数 | 定数
列挙型 | 列挙型
構造体 | 構造体
サンプルのビルド | Developer Studio 5.0によるサンプルのビルド
Developer Studio | Developer Studio 5.0によるサンプルのビルド
サンプルコード | サンプル
保持モードオブジェクトおよび関連COMインターフェイス | アーキテクチャ
3Dグラフィックス概念 | 基礎知識
DirectXファイル | DirectXファイルフォーマット

次のリストは、Microsoft Visual Basic のプログラマがよく使う情報と、その参照先の一覧である。
情報 | 参照先
エラーコード | 戻り値
インターフェイス | インターフェイス
コールバック | コールバック関数
列挙型 | 列挙型
構造体 | 構造体
3Dグラフィックス概念 | 基礎知識
DirectXファイル | DirectXファイルフォーマット


オブジェクトの回転：RMBegin1サンプル

デバイスの作成、シーンの構築と移動は、Microsoft® Direct3D®保持モードの基本的な概念である。RMBegin1サンプルでは、デフォルトのデバイスを作成し、Microsoft DirectX®ファイルからメッシュをロードし、オブジェクトに色を追加し、シーンに照明を追加し、オブジェクトを回転することで、この基本的な概念を具体的に示す。サンプルでは、シーンの構築時にメッシュビルダ、フレーム、照明、マテリアルを使用する。さらに、DirectDrawClipperオブジェクト、ビューポート、カメラも作成する。

この項では、RMBegin1サンプルのコードのウォークスルーを行う。サンプルソースコードは、必要な要素をすべて備えた1つのファイル (RMBegin1.cpp) で構成されており、Microsoft Windows® DirectDraw®およびDirect3D保持モードの標準ヘッダファイル以外の個別のヘッダファイルは使用していない。これは、わかりやすくするためである。メニューやアイコンなどのリソースも使用していない。

このサンプルは、DirectX Foundation SDK (Software Development Kit) のTeapot.xファイルを使用して、シーンにティーポットの画像を与える。デフォルトでは、SDKをインストールすると、SDKのセットアッププログラムは、環境変数をSDKのメディアディレクトリに設定する。Teapot.xファイルはメディアディレクトリにあるので、アプリケーションはファイルを自動的に検出する。SDKをインストールしないでRMBegin1.exeを実行する場合、Teapot.xファイルはRMBegin1.exeと同じディレクトリに置く必要がある。

この項は、ユーザがCまたはC++のプログラミング経験があること、また、メッセージループ、ウィンドウの作成、メニューの使用など、Windowsプログラミングの基本概念に精通していることを前提にしている。

この項は、次の項目に分かれている。

  • 前提
  • グローバル宣言
  • 関数概要
  • 関連トピック

前提

  • RMBegin1はDDraw.libとD3DRM.libをリンクする。
  • RMBegin1は、前述のように、Teapot.xからティーポットの画像をロードする。
  • Direct3Dアプリケーションは、グローバルユニーク識別子 (GUID) を適切に初期化するために、コードの先頭で次の定義を行う必要がある。
    #define INITGUID
  • サンプルのRMBegin1.cppファイルは次のヘッダファイルをインクルードしている。
    #include <windows.h>   // 標準 Windows ヘッダファイル
#include <direct.h>    // DirectDraw の定義
#include <d3drmwin.h>  // Direct3D 保持モードの定義

グローバル宣言

このサンプルでは、いくつかの定数とグローバル変数を定義して、情報を整理する。

アプリケーションで定義されているRELEASEマクロは、オブジェクトがNULL以外の場合にだけオブジェクトを解放し、解放後にオブジェクトをNULLに初期化する。すでに解放したオブジェクトを解放すると、ページフォールトなどの予期せぬ結果が発生するが、この手順によって、そうした問題が回避できる。

// オブジェクトを解放するマクロ
#define RELEASE(x) if (x != NULL) {x->Release(); x = NULL;}

アプリケーションで定義されているDISPLAYMSGマクロは、Windows MessageBox関数を使用してユーザに対して情報を表示する。このマクロを使用すると、サンプルコードでMessageBoxを直接呼び出すよりも、コードが簡素化されて読みやすくなる。

// 与えられた文字列を含むメッセージボックスを表示するマクロ
#define DISPLAYMSG(x) MessageBox(NULL, x, "D3DRM Sample", MB_OK);

グローバル変数は、Direct3D保持モードおよびDirectDrawClipperオブジェクトなどの主要なオブジェクトを追跡する。DirectDrawClipperオブジェクトは、描画を指定した領域に制限する。myglobs構造体は、デバイス、ビューポート、シーン、カメラに関する情報に加えて、アプリケーションの最小化やオブジェクトの初期化に関する情報も収集する。

// グローバル変数
LPDIRECT3DRM lpD3DRM = NULL;            // Direct3DRMオブジェクト
LPDIRECTDRAWCLIPPER lpDDClipper = NULL; // DirectDrawClipperオブジェクト

// グローバル構造体
struct _myglobs {

    // Direct3D保持モードデバイス
    LPDIRECT3DRMDEVICE dev;

    // シーンを表示するDirect3D保持モードビューポート
    LPDIRECT3DRMVIEWPORT view;

    // 他のフレームを配置するマスターフレーム
    LPDIRECT3DRMFRAME scene;

    // ユーザの視点を記述するフレーム
    LPDIRECT3DRMFRAME camera;

    // アプリケーションは最小化されている。
    BOOL bMinimized;

    // Direct3D保持モードの全オブジェクトが初期化されている。
    BOOL bInitialized;

} myglobs;

関数概要

RMBegin1.cppには、以下の関数が含まれている。

BuildScene関数は、レンダリングするシーンを作成する。DirectXファイルからメッシュをロードし、色をメッシュに追加し、シーンに照明を追加する。さらに、BuildSceneは、オブジェクトの位置と回転の方法を設定する。グローバル変数を初期化し、デフォルトのデバイス、フレーム、ビューポートを作成するCreateObjectsが、この関数を使用する。

BOOL BuildScene(LPDIRECT3DRM, LPDIRECT3DRMDEVICE,
                LPDIRECT3DRMFRAME, LPDIRECT3DRMFRAME);

RenderScene関数は、BuildSceneが作成したシーンを描画する。WinMainがこの関数を使用するたびに、RenderSceneはシーンを移動して、オブジェクトに回転効果を与える。

static BOOL RenderScene(void);

CreateObjects関数は、グローバル変数を初期化して、デフォルトのデバイス、カメラフレーム、シーンフレーム、ビューポートを作成する。CreateObjectsはBuildSceneを使用して、レンダリングするシーンを作成する。InitAppがCreateObjectsを使用する。

BOOL CreateObjects(HWND win);

InitApp関数は、Windowsアプリケーションの標準的なコードにより、ウィンドウクラスとアプリケーションのウィンドウを作成する。InitAppは、CreateObjectsを使用して、グローバルオブジェクトを初期化する。

static HWND InitApp(HINSTANCE, int);

WinMain関数は、アプリケーションのメッセージループを提供する。InitAppを使用してアプリケーションを初期化し、RenderSceneを使用してシーンを描画する。

int APIENTRY WinMain(HINSTANCE, HINSTANCE, LPSTR, int);

WindowProc関数は、アプリケーションのメッセージを処理する。アプリケーションの最小化や破棄を処理する。

LRESULT CALLBACK WindowProc(HWND, UINT, WPARAM, LPARAM);

以上の関数の詳細については、この項の次の項目を参照すること。

  • BuildScene
  • RenderScene
  • CreateObjects
  • InitApp
  • WinMain
  • WindowProc

BuildScene

BuildScene関数は、レンダリングするシーンを作成する。Direct3D保持モードのすべてのアプリケーションはシーンを作成する必要があるが、必要なコードはシーンに依存する。アプリケーションは通常、フレームと照明を作成し、視覚的な要素をシーンに追加し、オブジェクトの位置を設定する。

この節では、BuildScene関数のコードを部分的に示して、RMBegin1サンプルがシーンを構築する手順について説明する。さらに、RMBegin1サンプルのBuildScene関数に関するすべてのソースコードも示す。エラーが発生した場合は、goto文で関数の最後にジャンプして、関数から返る前に、すべてのオブジェクトを適切に解放する。

  1. IDirect3DRM3::CreateMeshBuilderとIDirect3DRMMeshBuilder3::Loadメソッドを使用して、DirectXファイルからメッシュをロードする。
        if (FAILED(lpD3DRM->CreateMeshBuilder(&meshbuilder)))
        goto generic_error;

    rval = meshbuilder->Load("teapot.x",
                              NULL, D3DRMLOAD_FROMFILE, NULL, NULL);
  2. IDirect3DRM3::CreateFrameメソッドを使用して、シーンの子フレームを作成する。
        if (FAILED(lpD3DRM->CreateFrame(scene, &childframe)))
        goto generic_error;
  3. IDirect3DRMFrame3::AddVisualメソッドを使用して、ロードしたメッシュを子フレームに追加する。
        if (FAILED(childframe->AddVisual((LPDIRECT3DRMVISUAL)meshbuilder)))
        goto generic_error;
  4. IDirect3DRMFrame3::SetPositionメソッドを使用して、シーンにカメラ位置を設定する。
        rval = camera->SetPosition(scene, D3DVAL(0), D3DVAL(0), -D3DVAL(7));
  5. IDirect3DRMFrame3::SetRotationメソッドを使用して、子フレームの回転を設定する。
        if (FAILED(childframe->SetRotation(scene,
                                       D3DVAL(0), D3DVAL(1), D3DVAL(0),
                                       D3DVAL(0.03)))) // 角度
        goto generic_error;
  6. IDirect3DRM3::CreateFrameメソッドを使用して、シーンの子フレームになる照明フレームを作成する。
        if (FAILED(lpD3DRM->CreateFrame(scene, &lights)))
        goto generic_error;
  7. IDirect3DRMFrame3::SetPositionメソッドを使用して、シーンに照明フレームを配置する。
        if (FAILED(lights->SetPosition(scene,
                                   D3DVAL(5), D3DVAL(0), -D3DVAL(7))))
        goto generic_error;
  8. IDirect3DRM3::CreateLightRGBとIDirect3DRMFrame3::AddLightメソッドを使用して、明るいパラレルポイント照明を作成し、照明フレームに追加する。
        if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_PARALLELPOINT,
                                       D3DVAL(1.0), D3DVAL(0.8),
                                       D3DVAL(0.9), &light1)))
        goto generic_error;

    if (FAILED(lights->AddLight(light1)))
        goto generic_error;
  9. IDirect3DRM3::CreateLightRGBとIDirect3DRMFrame3::AddLightメソッドをもう一度使用して、暗いアンビエント照明を作成し、シーンに追加する。
        if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_AMBIENT,
                                       D3DVAL(0.1), D3DVAL(0.1),
                                       D3DVAL(0.1), &light2)))
        goto generic_error;

    if (FAILED(scene->AddLight(light2)))
        goto generic_error;
  10. IDirect3DRM3::CreateMaterialとIDirect3DRMMeshBuilder3::SetMaterialメソッドを使用して、マテリアルを作成し、反射特性を設定する。
        if (FAILED(lpD3DRM->CreateMaterial(D3DVAL(10.0), &mat)))
        goto generic_error;

    if (FAILED(meshbuilder->SetMaterial(mat)))
        goto generic_error;
  11. IDirect3DRMMeshBuilder3::SetColorRGBメソッドを使用して、メッシュの色を設定する。
        if (FAILED(meshbuilder->SetColorRGB(D3DVAL(0.0),   // 赤
                                        D3DVAL(0.7),   // 緑
                                        D3DVAL(0.0)))) // 青
        goto generic_error;
  12. この関数で作成したすべてのオブジェクトを解放して終了する。
        RELEASE(childframe);
    RELEASE(lights);
    RELEASE(meshbuilder);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(mat);

BuildScene関数ソースコード

// レンダリングするシーンを作成する。

BOOL BuildScene(LPDIRECT3DRM lpD3DRM,
                LPDIRECT3DRMDEVICE dev,
                LPDIRECT3DRMFRAME scene,
                LPDIRECT3DRMFRAME camera)
{
    LPDIRECT3DRMFRAME lights = NULL;
    LPDIRECT3DRMMESHBUILDER meshbuilder = NULL;
    LPDIRECT3DRMFRAME childframe = NULL;
    LPDIRECT3DRMLIGHT light1 = NULL;
    LPDIRECT3DRMLIGHT light2 = NULL;
    LPDIRECT3DRMMATERIAL mat = NULL;
    HRESULT rval;

    // irectX ファイルからメッシュをロードする。
    if (FAILED(lpD3DRM->CreateMeshBuilder(&meshbuilder)))
        goto generic_error;

    rval = meshbuilder->Load("teapot.x",
                              NULL, D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to load .x file.");
        goto ret_with_error;
    }

    // シーンの子フレームを作成する。
    if (FAILED(lpD3DRM->CreateFrame(scene, &childframe)))
        goto generic_error;

    // ロードしたメッシュを子フレームに追加する。
    if (FAILED(childframe->AddVisual((LPDIRECT3DRMVISUAL)meshbuilder)))
        goto generic_error;

    // カメラフレーム位置を設定する。カメラと同じ x 値と
    // y 値を持つオブジェクトは、まっすぐに表示される。
    // z 値がマイナスであると、オブジェクトは遠ざかり、
    // 負数の絶対値が大きくなるほど、オブジェクトは小さくなる。
    rval = camera->SetPosition(scene, D3DVAL(0), D3DVAL(0), -D3DVAL(7));
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to position the camera in the frame.");
        goto ret_with_error;
    }

    // 子メッシュを y 軸に沿って回転させる (x 値と z 値はゼロ)。
    // 小さな回転角を使用して、ゆっくり回転させる。
    if (FAILED(childframe->SetRotation(scene,
                                       D3DVAL(0), D3DVAL(1), D3DVAL(0),
                                       D3DVAL(0.03)))) // angle
        goto generic_error;

    // シーンの照明を初期化する。シーンの子フレームになる
    // 照明フレームを作成する。
    if (FAILED(lpD3DRM->CreateFrame(scene, &lights)))
        goto generic_error;

    // 照明フレームをシーンに配置する。光はカメラの右側から照らす。
    // x 値は異なるが、y 値と z 値はカメラ位置と同じである。
    if (FAILED(lights->SetPosition(scene,
                                   D3DVAL(5), D3DVAL(0), -D3DVAL(7))))
        goto generic_error;

    // 明るいパラレルポイント照明を作成して、照明フレームに追加する。
    // カラー値は、0.0 (暗い) から1.0 (明るい) までの範囲とする。
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_PARALLELPOINT,
                                       D3DVAL(1.0), D3DVAL(0.8),
                                       D3DVAL(0.9), &light1)))
        goto generic_error;

    if (FAILED(lights->AddLight(light1)))
        goto generic_error;

    // 暗いアンビエント照明を作成して、シーンのフレームに追加し、
    // シーン全体に適用する。アンビエント照明は全方向から照らす。したがって、
    // 明るいアンビエント照明はオブジェクトの色を薄くする。
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_AMBIENT,
                                       D3DVAL(0.1), D3DVAL(0.1),
                                       D3DVAL(0.1), &light2)))
        goto generic_error;

    if (FAILED(scene->AddLight(light2)))
        goto generic_error;

    // マテリアルを作成し、前にロードしたメッシュの反射特性を設定する
    // (5.0 は金属的な外観になり、それ以上の値では、より柔らかい外観となる)。
    if (FAILED(lpD3DRM->CreateMaterial(D3DVAL(10.0), &mat)))
        goto generic_error;

    if (FAILED(meshbuilder->SetMaterial(mat)))
        goto generic_error;

    // メッシュの色を設定する。ここでは明るい緑にする。
    if (FAILED(meshbuilder->SetColorRGB(D3DVAL(0.0),   // 赤
                                        D3DVAL(0.7),   // 緑
                                        D3DVAL(0.0)))) // 青
        goto generic_error;

    // 終了処理。
    RELEASE(childframe);
    RELEASE(lights);
    RELEASE(meshbuilder);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(mat);
    return TRUE;

generic_error:
    DISPLAYMSG("A failure occured while building the scene.");
ret_with_error:
    RELEASE(childframe);
    RELEASE(lights);
    RELEASE(meshbuilder);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(mat);
    return FALSE;
}

RenderScene

RenderScene関数は、実際にシーンをスクリーンに描画する。BuildSceneが作成したシーンを次の手順に従って描画する。

  1. IDirect3DRMFrame3::Moveを使用して、シーンを移動する。
  2. IDirect3DRMViewport2::Clearを使用して、ビューポートをクリアする。
  3. IDirect3DRMViewport2::Renderを使用して、シーンをレンダリングする。
  4. IDirect3DRMDevice3::Updateを使用して、ウィンドウを更新する。

RenderScene関数ソースコード

// ビューポートをクリアし、次のフレームをレンダリングして、ウィンドウを更新する。

static BOOL RenderScene()
{
    HRESULT rval;

    // シーンの移動。
    rval = myglobs.scene->Move(D3DVAL(1.0));
    if (FAILED(rval))
    {
        DISPLAYMSG("Moving scene failed.");
        return FALSE;
    }

    // ビューポートのクリア。
    rval = myglobs.view->Clear();
    if (FAILED(rval))
    {
        DISPLAYMSG("Clearing viewport failed.");
        return FALSE;
    }

    // シーンをビューポートにレンダリングする。
    rval = myglobs.view->Render(myglobs.scene);
    if (FAILED(rval))
    {
        DISPLAYMSG("Rendering scene failed.");
        return FALSE;
    }

    // ウィンドウの更新。
    rval = myglobs.dev->Update();
    if (FAILED(rval))
    {
        DISPLAYMSG("Updating device failed.");
        return FALSE;
    }
    return TRUE;
}

CreateObjects

CreateObjectsは、サンプルのグローバル変数を初期化し、オブジェクトを作成する。グローバル変数を初期化した後、デバイスの作成に必要な手順を実行し、デバイスをアプリケーションのメインウィンドウに関連付け、マスターシーンフレーム、カメラフレーム、ビューポートを作成する。以下の手順に従う。

  1. irectDrawのDirectDrawCreateClipper関数を使用して、DirectDrawClipperオブジェクトを作成する。
  2. DirectDrawClipperのSetHWndメソッドを使用して、アプリケーションのウィンドウをDirectDrawClipperに関連付ける。DirectDrawClipperオブジェクトは、後続の描画を、指定した領域 (ここでは、アプリケーションのウィンドウ)に制限する。
  3. Direct3DRMCreate関数を使用して、Direct3D保持モードオブジェクトを作成する。
  4. WindowsのGetClientRect関数を使用して、アプリケーションのメインウィンドウの高さと幅を取得する。
  5. Direct3D保持モードオブジェクトのCreateDeviceFromClipperメソッドを使用してデバイスを作成し、NULLを渡してデフォルトデバイスを作成する。さらに、アプリケーションのウィンドウの幅と高さをメソッドに渡す。
  6. IDirect3DRM3::CreateFrameを使用して、マスターシーンフレームを作成する。
  7. IDirect3DRM3::CreateFrameを使用して、カメラフレームを作成する。
  8. IDirect3DRM3::CreateViewportを使用して、Direct3D保持モードのビューポートを作成する。
  9. BuildSceneを使用して、シーンを作成する。

CreateObjects関数ソースコード

// グローバル変数を初期化して、デバイスとオブジェクトを作成する。

BOOL CreateObjects(HWND win)
{
    HRESULT rval; // 戻り値
    RECT rc;      // メインウィンドウの矩形の境界
    int width;    // デバイスの幅
    int height;   // デバイスの高さ

    // グローバル変数構造体の全体をゼロに初期化する。
    memset(&myglobs, 0, sizeof(myglobs));

    // DirectDrawClipperオブジェクトを作成し、ウィンドウを関連付ける。
    rval = DirectDrawCreateClipper(0, &lpDDClipper, NULL);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create DirectDrawClipper object");
        return FALSE;
    }

    rval = lpDDClipper->SetHWnd(0, win);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to set the window handle for the DirectDrawClipper");
        return FALSE;
    }

    // Direct3D保持モードオブジェクトを作成する。
    rval = Direct3DRMCreate(&lpD3DRM);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create Direct3DRM.");
        return FALSE;
    }

    // Direct3D保持モードのデフォルトデバイスを作成する。
    GetClientRect(win, &rc);

    rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                           NULL, // デフォルトデバイス
                           rc.right, rc.bottom, &myglobs.dev);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create the D3DRM device.");
        return FALSE;
    }

    // マスターシーンフレームとカメラフレームを作成する。
    rval = lpD3DRM->CreateFrame(NULL, &myglobs.scene);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create the master scene frame.");
        return FALSE;
    }

    rval = lpD3DRM->CreateFrame(myglobs.scene, &myglobs.camera);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create the camera's frame.");
        return FALSE;
    }

    // デバイス、カメラフレーム、デバイスの幅と高さを使用して、
    // Direct3D保持モードのビューポートを作成する。
    wid
    height = myglobs.dev->GetHeight();

    rval = lpD3DRM->CreateViewport(myglobs.dev, myglobs.camera, 0, 0,
                                   width, height, &myglobs.view);
    if (FAILED(rval))
    {
        myglobs.bInitialized = FALSE;
        RELEASE(myglobs.dev);
        return FALSE;
    }

    // レンダリングするシーンを作成する。
    if (!BuildScene(lpD3DRM, myglobs.dev, myglobs.scene,
                    myglobs.camera))
        return FALSE;

    // グローバル変数は初期化された。
    myglobs.bInitialized = TRUE;

    return TRUE;
}

InitApp

InitApp関数は、メインウィンドウクラスとメインウィンドウを作成する。これは、Windowsアプリケーションでは一般的な処理である。InitAppから呼び出されるDirect3D保持モードは、CreateObjectsの呼び出しだけである。

InitApp関数ソースコード

// メインウィンドウを作成し、オブジェクトを初期化する。

static HWND InitApp(HINSTANCE this_inst, int cmdshow)
{
    HWND win;     // メインウィンドウハンドル
    WNDCLASS wc;  // ウィンドウクラス

    // ウィンドウクラスを設定して登録する。
    wc.style = CS_HREDRAW | CS_VREDRAW;
    wc.lpfnWndProc = WindowProc;
    wc.cbClsExtra = 0;
    wc.cbWndExtra = sizeof(DWORD);
    wc.hInstance = this_inst;
    wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);
    wc.hCursor = LoadCursor(NULL, IDC_ARROW);
    wc.hbrBackground = (HBRUSH)GetStockObject(BLACK_BRUSH);
    wc.lpszMenuName = NULL;
    wc.lpszClassName = "D3DRM Example";
    if (!RegisterClass(&wc))
        return FALSE;

    // ウィンドウの作成。
    win = CreateWindow(
            "D3DRM Example",                   // クラス
            "RMBegin1: Direct3DRM Sample One", // キャプション
            WS_OVERLAPPEDWINDOW,               // スタイル
            CW_USEDEFAULT,                     // init. x pos
            CW_USEDEFAULT,                     // init. y pos
            350,                               // init. x size
            300,                               // init. y size
            NULL,                              // 親ウィンドウ
            NULL,                              // メニューハンドル
            this_inst,                         // プログラムハンドル
            NULL);                             // 作成パラメータ

    if (!win)
        return FALSE;

    // グローバル変数を初期化し、Direct3D保持モード
    // オブジェクトを作成する。
    if (!CreateObjects(win))
        return FALSE;

    // ウィンドウの表示。
    ShowWindow(win, cmdshow);
    UpdateWindow(win);

    return win;
}

WinMain

WinMain関数は、アプリケーションのメッセージループを提供する。グローバル変数が初期化されていて、アプリケーションが最小化されていなければ、WinMainはRenderSceneを使用してシーンをスクリーンに描画する。

WinMain関数ソースコード

// アプリケーションを初期化し、メッセージを処理して、シーンをレンダリングする。

int APIENTRY WinMain (HINSTANCE this_inst,
                      HINSTANCE prev_inst,
                      LPSTR cmdline,
                      int cmdshow)
{
    HWND    hwnd;
    MSG     msg;
    prev_inst;
    cmdline;

    // ウィンドウを作成し、オブジェクトを初期化する。
    if (!(hwnd = InitApp(this_inst, cmdshow)))
        return 1;

    while (TRUE)
    {
        // メッセージキューを監視して、メッセージを処理する。PeekMessageは
        // 制御を即座にアプリケーションに返すので、アプリケーションは
        // メッセージの処理とレンダリングを継続できる。
        // メッセージがWM_QUITであれば、アプリケーションが終了しているため、
        // この関数を抜ける。
        if (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))
        {
            if (msg.message == WM_QUIT)
                break;
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }

        // アプリケーションが最小化されておらず、Direct3D保持モード
        // オブジェクトが初期化されていれば、レンダリングを行う。
        if (!myglobs.bMinimized && myglobs.bInitialized)
        {
            // シーンを1フレーム、レンダリングする。レンダリングが失敗したら、
            // WM_DESTROYメッセージを発行する。これにより、アプリケーションが
            // 終了する前に、リソースを解放できる。
            if (!RenderScene())
            {
                DISPLAYMSG("Rendering failed. Aborting execution.");
                PostMessage(NULL, WM_DESTROY, 0, 0);
                break;
            }

        // このアプリケーションが現在レンダリングをしていなければ、
        // 他のアプリケーションに制御を渡す。
        } else
              WaitMessage();

    }
    return msg.wParam;
}

WindowProc

WindowProcは、アプリケーションのメインウィンドウのメッセージを処理する。フラグをセットして、アプリケーションが最小化されているときはレンダリングを停止させる。さらに、この関数は、アプリケーションがシャットダウンしたときにオブジェクトを解放する。

WindowProc関数ソースコード

// メインウィンドウのメッセージを処理する。

LRESULT CALLBACK WindowProc(HWND win,
                            UINT msg,
                            WPARAM wparam,
                            LPARAM lparam)
{
    switch (msg)
    {
        case WM_SIZE:
            // ウィンドウの最小化を処理する。アプリケーションが最小化されて
            // いれば、フラグをセットして、最小化時にはレンダリングを停止する。
            // それ以外の場合は、レンダリングを継続する。
            if (SIZE_MINIMIZED == wparam)
                myglobs.bMinimized = TRUE;
            else
                myglobs.bMinimized = FALSE;
            break;

        case WM_DESTROY:
            // bInitializedフラグをクリアし、オブジェクトを解放して、
            // WM_QUITメッセージを発行して、アプリケーションを終了する。
            // デバイスを解放する前に、ビューポートを解放すること。
            // この順序を間違えると、一般保護違反が発生する。
            myglobs.bInitialized = FALSE;
            RELEASE(myglobs.view);
            RELEASE(myglobs.dev);
            RELEASE(lpD3DRM);
            RELEASE(lpDDClipper);
            PostQuitMessage(0);
            break;

        default:
            return DefWindowProc(win, msg, wparam, lparam);
    }
    return 0L;
}

関連トピック

ここではDirect3D保持モードを使用してオブジェクトを作成し、スクリーンに配置する基本を学習した。Direct3D保持モードのサンプルコードが、前よりも簡単に理解できるようになったであろう。ほとんどのサンプルは、RMMainが提供するヘルパコードを使用してデバイスを作成し、シーンをレンダリングしているが、独自のBuildScene関数により、それぞれのシーンを作成している。

次のステップとしては、RMBegin1の機能を拡張した、RMBegin2サンプルを見るとよい。また、RMBegin1と似た機能を持つEggやGlobeなどのDirect3D保持モードサンプルを調べてもよい。

もう一つのDirect3D保持モードの一般的なタスクについては、「デバイスの列挙：サンプルRMEnum」を参照すること。この節では、RMEnumのサンプルコードのウォークスルーを行う。RMEnumは、デバイスを列挙する方法に焦点を当てている。

保持モードサンプルのすべての概要については、「サンプル」を参照すること。


フレーム階層：RMBegin2サンプル

デバイスの作成、シーンの構築と移動は、Microsoft® Direct3D®保持モードの基本的な概念である。RMBegin2サンプルは、RMBegin1サンプルで紹介した、この基本概念の上に構築されている。この節では、RMBegin2サンプルのコードのウォークスルーを行う。

RMBegin2サンプルは、RMBegin1と同様、デフォルトデバイスを作成し、Microsoft DirectX®ファイルからメッシュをロードし、オブジェクトに色を追加し、シーンに照明を追加し、オブジェクトを回転する。RMBegin2サンプルでは、RMBegin1よりも複雑なシーンを構築し、オブジェクトをスケーリングし、フレーム階層を使用する。シーンを構築する際、このサンプルでは、3つのメッシュビルダ、複数のフレーム、複数の照明を使用する。また、DirectDrawClipperオブジェクト、ビューポート、カメラも作成する。RMBegin2サンプルには、アプリケーションのウィンドウサイズを変更する際シーンをリサイズし、WM_ACTIVATEメッセージとWM_PAINTメッセージを処理する新しい機能が追加されている。

RMBegin2では、3つの球体 (太陽、地球、月) のフレーム階層を使用する。各球体はそれぞれの親フレームのまわりを回転する。

RMBegin2サンプルのコードは、必要な要素をすべて備えた1つのファイル (RMBegin2.cpp) で構成されている。分かりやすくするため、Microsoft Windows® DirectDraw®およびDirect3D保持モードの標準ヘッダファイル以外の個別のヘッダファイルは使用していない。メニューやアイコンなどのリソースも使用していない。

このサンプルは、DirectX Foundation SDK (Software Development Kit) のSphere0.x、Sphere1.x、Sphere2.xファイルを使用して、シーンに月、地球、太陽の画像を与える。デフォルトでは、SDKをインストールすると、SDKのセットアッププログラムは、環境変数をSDKのメディアディレクトリに設定する。3つのDirectX (.x) ファイルはメディア・ディレクトリにあるので、アプリケーションはファイルを自動的に検出する。SDKをインストールしないでRMBegin2.exeを実行する場合、DirectXファイルはRMBegin2.exeと同じディレクトリに置く必要がある。

この項は、ユーザがCまたはC++のプログラミング経験があること、およびメッセージループ、ウィンドウの作成、メニューの使用など、Windowsプログラミングの基本概念に精通していることを前提にしている。

この項は、次の項目に分かれている。

  • 前提
  • グローバル宣言
  • 関数概要
  • 関連トピック

前提

  • RMBegin2はDDraw.libとD3DRM.libをリンクする。
  • RMBegin2は、前述のように、Sphere0.x、Sphere1.x、Sphere2.x から球体の画像をロードする。
  • Direct3Dアプリケーションは、グローバルユニーク識別子 (GUID) を適切に初期化するために、コードの先頭で次の定義を行う必要がある。
    #define INITGUID
  • サンプルのRMBegin2.cppファイルは次のヘッダファイルをインクルードしている。
    #include <windows.h>   // 標準Windowsヘッダファイル
#include <direct.h>    // DirectDraw定義
#include <d3drmwin.h>  // Direct3D保持モード定義

グローバル宣言

このサンプルでは、いくつかの定数とグローバル変数を定義して、情報を整理する。

アプリケーションで定義されているRELEASEマクロは、オブジェクトがNULL以外の場合にだけオブジェクトを解放し、解放後にオブジェクトをNULLに初期化する。すでに解放したオブジェクトを解放すると、ページフォールトなどの予期せぬ結果が発生するが、この手順によって、そうした問題が回避できる。

// オブジェクトを解放するマクロ
#define RELEASE(x) if (x != NULL) {x->Release(); x = NULL;}

アプリケーションで定義されているDISPLAYMSGマクロは、Windows MessageBox関数を使用してユーザに対して情報を表示する。このマクロを使用すると、サンプルコードでMessageBoxを直接呼び出すよりも、コードが簡素化されて読みやすくなる。

// 与えられた文字列を含むメッセージボックスを表示するマクロ
#define DISPLAYMSG(x) MessageBox(NULL, x, "D3DRM Sample", MB_OK);

グローバル変数は、Direct3D保持モードおよびDirectDrawClipperオブジェクトなどの主要なオブジェクトを追跡する。DirectDrawClipperオブジェクトは、描画を指定した領域に制限する。myglobs構造体は、デバイス、ウィンドウデバイス、ビューポート、シーン、カメラに関する情報に加えて、アプリケーションの最小化やオブジェクトの初期化に関する情報も収集する。RMBegin2では、RMBegin1で使用していたオブジェクトにDirect3D保持モードのウィンドウデバイスを追加していることに注意する。

// グローバル変数
LPDIRECT3DRM lpD3DRM = NULL;            // Direct3D保持モードブジェクト
LPDIRECTDRAWCLIPPER lpDDClipper = NULL; // DirectDrawClipperオブジェクト

// グローバル構造体
struct _myglobs {

    // Direct3D保持モードデバイス
    LPDIRECT3DRMDEVICE dev;

    // Direct3D保持モードウィンドウデバイス
    LPDIRECT3DRMWINDEVICE windevice;

    // シーンを表示するDirect3D保持モードビューポート
    LPDIRECT3DRMVIEWPORT view;

    // 他のフレームを配置するマスターフレーム
    LPDIRECT3DRMFRAME scene;

    // ユーザの視点を記述するフレーム
    LPDIRECT3DRMFRAME camera;

    // アプリケーションは最小化されている。
    BOOL bMinimized;

    // Direct3D保持モードの全オブジェクトが初期化されている。
    BOOL bInitialized;

} myglobs;

関数概要

RMBegin2.cppには、以下の関数が含まれている。

BuildScene関数は、レンダリングするシーンを作成する。DirectXファイルからメッシュをロードし、メッシュをスケーリングし、色をメッシュに追加し、フレームの階層を作成し、シーンに照明を追加する。さらに、BuildSceneは、オブジェクトの位置と回転の方法を設定する。グローバル変数を初期化し、デフォルトのデバイス、フレーム、ビューポートを作成するCreateObjectsが、この関数を使用する。基本的には、RMBegin1のBuildScene関数に似ているが、RMBegin2のBuildScene関数は、より複雑なシーンを作成する。

BOOL BuildScene(LPDIRECT3DRM, LPDIRECT3DRMDEVICE,
                LPDIRECT3DRMFRAME, LPDIRECT3DRMFRAME);

RenderScene関数は、BuildSceneが作成したシーンを描画する。WinMainがこの関数を使用するたびに、RenderSceneはシーンを移動して、オブジェクトに回転効果を与える。この関数は、RMBegin1サンプルのRenderScene関数と同じである。

static BOOL RenderScene(void);

CreateObjects関数は、グローバル変数を初期化して、デフォルトのデバイス、ウィンドウデバイス、カメラフレーム、シーンフレーム、ビューポートを作成する。CreateObjectsはBuildSceneを使用して、レンダリングするシーンを作成する。アプリケーションのウィンドウを作成するInitAppが、CreateObjectsを使用する。この関数は、ウィンドウデバイスを作成する点を除けば、RMBegin1サンプルのCreateObjects関数と同じである。

BOOL CreateObjects(HWND win);

InitApp関数は、Windowsアプリケーションの標準的なコードにより、ウィンドウクラスとアプリケーションのウィンドウを作成する。InitAppは、CreateObjectsを使用して、グローバルオブジェクトを初期化する。この関数は、ウィンドウキャプションが異なることを除けば、RMBegin1サンプルのInitApp関数と同じである。

static HWND InitApp(HINSTANCE, int);

WinMain関数は、アプリケーションのメッセージループを提供する。InitAppを使用してアプリケーションを初期化し、RenderSceneを使用してシーンを描画する。この関数は、RMBegin1サンプルのWinMain関数と同じである。

int APIENTRY WinMain(HINSTANCE, HINSTANCE, LPSTR, int);

WindowProc関数は、アプリケーションのメッセージを処理する。アプリケーションの最小化、サイズ変更、アクティブ化、描画、破棄を処理する。

LRESULT CALLBACK WindowProc(HWND, UINT, WPARAM, LPARAM);

以上の関数の詳細については、この項の次の項目を参照すること。

  • BuildScene
  • RenderScene
  • CreateObjects
  • InitApp
  • WinMain
  • WindowProc

BuildScene

BuildScene関数は、レンダリングするシーンを作成する。Direct3D保持モードのすべてのアプリケーションはシーンを作成する必要があるが、必要なコードはシーンに依存する。アプリケーションは通常、フレームと照明を作成し、視覚的な要素をシーンに追加し、オブジェクトの位置を設定する。この関数は、さらに、オブジェクトをスケーリングし、フレーム階層を設定する。

この節では、BuildScene関数のコードを部分的に示して、RMBegin2サンプルが太陽、地球、月のシーンを構築する手順について説明する。さらに、RMBegin2サンプルのBuildScene関数に関するすべてのソースコードも示す。エラーが発生した場合は、goto文で関数の最後にジャンプして、関数から返る前に、すべてのオブジェクトを適切に解放する。

  1. IDirect3DRM3::CreateMeshBuilderとIDirect3DRMMeshBuilder3::Loadメソッドを使用して、DirectXファイルからメッシュをロードする。次のコードは、1つのメッシュをロードしている。サンプルでは、同じ処理を使用して、他のメッシュもロードしている。
        if (FAILED(lpD3DRM->CreateMeshBuilder(&sun_builder)))
        goto generic_error;

    rval = sun_builder->Load("sphere2.x", NULL,
                    D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to load sun .x file.");
        goto ret_with_error;
    }
  2. メッシュをスケーリングして色を追加する。サンプルがロードする3つの球体は、ほぼ同じ大きさなので、太陽を拡大し、地球と月を縮小する。次のコードは、1つのメッシュに対して、この処理を行っている。
        if (FAILED(sun_builder->Scale(D3DVAL(1.2), D3DVAL(1.2),
                                  D3DVAL(1.2))))
        goto generic_error;
    if (FAILED(sun_builder->SetColorRGB(D3DVAL(1.0), D3DVAL(1.0),
                                        D3DVAL(0.0))))
        goto generic_error;
  3. IDirect3DRM3::CreateFrameメソッドを使用して、シーンのフレーム階層を作成する。次のコードでは、マスターシーンフレームに太陽のフレーム、太陽のフレームに地球のフレーム、地球のフレームに月のフレームを作成している。オブジェクトの回転を設定するとき、このフレーム階層は、どのオブジェクトの回りを、どのオブジェクトが公転するかを管理する。
        if (FAILED(lpD3DRM->CreateFrame(scene, &sun)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateFrame(sun, &planet)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateFrame(planet, &moon)))
        goto generic_error;
  4. IDirect3DRMMeshBuilder3::CreateMeshを使用して、メッシュビルダオブジェクトをメッシュに変換する。次のコードは太陽のメッシュを作成する。
        if (FAILED(sun_builder->CreateMesh(&sun_mesh)))
        goto generic_error;
  5. IDirect3DRMFrame3::AddVisualメソッドを使用して、ロードしたメッシュを適切な子フレームに追加する。次のコードは、太陽のメッシュを太陽のフレームに追加する。
        if (FAILED(sun->AddVisual((LPDIRECT3DRMVISUAL) sun_mesh)))
        goto generic_error;
  6. IDirect3DRMFrame3::SetPositionメソッドを使用して、シーンにカメラ位置を設定する。他のオブジェクトの位置も設定する。次のコードはカメラと太陽の位置を設定する。太陽の位置とカメラ位置のx座標とy座標が、ともに(0,0)であるため、太陽はカメラの正面の直線上に表示される。
        if (FAILED(camera->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                   -D3DVAL(25))))
        goto generic_error;
    if (FAILED(sun->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                D3DVAL(0))))
        goto generic_error;
  7. IDirect3DRMFrame3::SetRotationメソッドを使用して、フレームの回転を設定する。次のコードは、太陽の回転を設定する。
        if (FAILED(sun->SetRotation(scene, D3DVAL(0), D3DVAL(0),
                                D3DVAL(1),
                                D3DVAL(0.01))))
  8. IDirect3DRM3::CreateFrameメソッドを使用して、シーンの子フレームになる照明フレームを作成する。IDirect3DRMFrame3::SetPositionメソッドを使用して、シーンに照明フレームを配置する。IDirect3DRM3::CreateLightRGBとIDirect3DRMFrame3::AddLightメソッドを使用して、明るいポイント照明を作成し、照明フレームに追加する。
        if (FAILED(lpD3DRM->CreateFrame(scene, &lights)))
        goto generic_error;
    if (FAILED(lights->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                -D3DVAL(7))))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_POINT, D3DVAL(0.9),
                                  D3DVAL(0.8), D3DVAL(0.7), &light1)))
        goto generic_error;
    if (FAILED(lights->AddLight(light1)))
        goto generic_error;
  9. IDirect3DRM3::CreateLightRGBとIDirect3DRMFrame3::AddLightメソッドをもう一度使用して、暗いアンビエント照明を作成し、シーンに追加する。
        if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_AMBIENT, D3DVAL(0.1),
                                  D3DVAL(0.1), D3DVAL(0.1), &light2)))
        goto generic_error;
    if (FAILED(scene->AddLight(light2)))
        goto generic_error;
  10. アンビエント照明の作成と同じメソッドを使用して、明るいパラレルポイント照明を作成し、照明フレームに追加する。
        if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_PARALLELPOINT,
                                  D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9),
                                  &light3)))
        goto generic_error;
    if (FAILED(sun->AddLight(light3)))
        goto generic_error;
  11. この関数で作成したすべてのオブジェクトを解放して終了する。
        RELEASE(sun_builder);
    RELEASE(planet_builder);
    RELEASE(moon_builder);
    RELEASE(sun_mesh);
    RELEASE(planet_mesh);
    RELEASE(moon_mesh);
    RELEASE(sun);
    RELEASE(planet);
    RELEASE(moon);
    RELEASE(lights);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(light3);

BuildScene関数ソースコード

// レンダリングするシーンを作成する。

BOOL BuildScene(LPDIRECT3DRM lpD3DRM,
                LPDIRECT3DRMDEVICE dev,
                LPDIRECT3DRMFRAME scene,
                LPDIRECT3DRMFRAME camera)
{
    LPDIRECT3DRMMESHBUILDER sun_builder = NULL;
    LPDIRECT3DRMMESHBUILDER planet_builder = NULL;
    LPDIRECT3DRMMESHBUILDER moon_builder = NULL;
    LPDIRECT3DRMMESH sun_mesh = NULL;
    LPDIRECT3DRMMESH planet_mesh = NULL;
    LPDIRECT3DRMMESH moon_mesh = NULL;
    LPDIRECT3DRMFRAME sun = NULL;
    LPDIRECT3DRMFRAME planet = NULL;
    LPDIRECT3DRMFRAME moon = NULL;
    LPDIRECT3DRMLIGHT light1 = NULL;
    LPDIRECT3DRMLIGHT light2 = NULL;
    LPDIRECT3DRMLIGHT light3 = NULL;
    LPDIRECT3DRMFRAME lights = NULL;
    HRESULT rval;

    // ロードするDirectXファイル (太陽、地球、月) ごとに、メッシュビルダを
    // 作成して、メッシュをロードする。
    if (FAILED(lpD3DRM->CreateMeshBuilder(&sun_builder)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateMeshBuilder(&planet_builder)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateMeshBuilder(&moon_builder)))
        goto generic_error;

    rval = sun_builder->Load("sphere2.x", NULL,
                    D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to load sun .x file.");
        goto ret_with_error;
    }

    rval = planet_builder->Load("sphere1.x", NULL,
                    D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to load planet .x file.");
    goto ret_with_error;
    }

    rval = moon_builder->Load("sphere0.x", NULL,
                    D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to load moon .x file.");
        goto ret_with_error;
    }

    // 太陽、地球、月のメッシュのサイズを調整する。
    // x 軸、y 軸、z 軸に同じ大きさでスケーリングして、メッシュの球体を保つ。
    // 太陽のサイズは増やし、
    // 地球と月のサイズは減らして、
    // 適切な相対的な大きさを得る。
    if (FAILED(sun_builder->Scale(D3DVAL(1.2), D3DVAL(1.2),
                                  D3DVAL(1.2))))
        goto generic_error;
    if (FAILED(planet_builder->Scale(D3DVAL(0.5), D3DVAL(0.5),
                                     D3DVAL(0.5))))
        goto generic_error;
    if (FAILED(moon_builder->Scale(D3DVAL(0.2), D3DVAL(0.2),
                                   D3DVAL(0.2))))
        goto generic_error;

    // 太陽、地球、月のメッシュの色を調整する。
    // 太陽は黄色、地球は緑がかった青色、
    // 月は赤色に設定する。
    if (FAILED(sun_builder->SetColorRGB(D3DVAL(1.0), D3DVAL(1.0),
                                        D3DVAL(0.0))))
        goto generic_error;
    if (FAILED(planet_builder->SetColorRGB(D3DVAL(0.2), D3DVAL(1.0),
                                           D3DVAL(0.8))))
        goto generic_error;
    if (FAILED(moon_builder->SetColorRGB(D3DVAL(0.7), D3DVAL(0.2),
                                         D3DVAL(0.3))))
        goto generic_error;

    // フレームの階層を作成する。
    // - マスターシーンフレームに太陽のフレーム、
    // - 太陽のフレームに地球のフレーム、
    // - 地球のフレームに月のフレームを作成する。
    if (FAILED(lpD3DRM->CreateFrame(scene, &sun)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateFrame(sun, &planet)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateFrame(planet, &moon)))
        goto generic_error;

    // メッシュビルダからメッシュを作成して、Direct3D保持モードが同じ変換を
    // 繰り返すのを避ける。メッシュビルダはここで解放することもできるが、
    // コードを分かりやすくするために、この関数の最後で、
    // 他のオブジェクトと一緒に解放する。
    if (FAILED(sun_builder->CreateMesh(&sun_mesh)))
        goto generic_error;
    if (FAILED(planet_builder->CreateMesh(&planet_mesh)))
        goto generic_error;
    if (FAILED(moon_builder->CreateMesh(&moon_mesh)))
        goto generic_error;

    // メッシュをフレームに追加する。
    if (FAILED(sun->AddVisual((LPDIRECT3DRMVISUAL) sun_mesh)))
        goto generic_error;
    if (FAILED(planet->AddVisual((LPDIRECT3DRMVISUAL) planet_mesh)))
        goto generic_error;
    if (FAILED(moon->AddVisual((LPDIRECT3DRMVISUAL) moon_mesh)))
        goto generic_error;

    // フレームの位置を設定する。
    if (FAILED(camera->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                   -D3DVAL(25))))
        goto generic_error;
    if (FAILED(sun->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                D3DVAL(0))))
        goto generic_error;
    if (FAILED(planet->SetPosition(sun, D3DVAL(7), D3DVAL(0),
                                   D3DVAL(0))))
        goto generic_error;
    if (FAILED(moon->SetPosition(planet, D3DVAL(0), D3DVAL(3),
                                 D3DVAL(0))))
        goto generic_error;

    // フレームの回転を設定する。
    if (FAILED(sun->SetRotation(scene, D3DVAL(0), D3DVAL(0),
                                D3DVAL(1),
                                D3DVAL(0.01))))
        goto generic_error;
    if (FAILED(planet->SetRotation(sun, D3DVAL(1), D3DVAL(0),
                                   D3DVAL(0),
                                   D3DVAL(0.02))))
        goto generic_error;
    if (FAILED(moon->SetRotation(planet, D3DVAL(0.1), D3DVAL(0.2),
                               D3DVAL(0.7),
                               D3DVAL(0.03))))
       goto generic_error;

    // シーンの照明を初期化する。
    // - 照明フレームを作成し、シーンに配置する位置を設定する
    //   (太陽の正面の直線上に置き、太陽を照らす)。
    //   ポイント照明を照明フレームにアタッチする。
    // - ソフトなアンビエント照明を作成して、シーンに追加する。
    // - 明るいパラレルポイント照明を作成して、太陽のフレームに
    //   追加する。地球と月が太陽の回りを公転する際、
    //   適切に照らすようにする。

    // 太陽の正面にポイント照明を作成する。
    if (FAILED(lpD3DRM->CreateFrame(scene, &lights)))
        goto generic_error;
    if (FAILED(lights->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                -D3DVAL(7))))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_POINT, D3DVAL(0.9),
                                  D3DVAL(0.8), D3DVAL(0.7), &light1)))
        goto generic_error;
    if (FAILED(lights->AddLight(light1)))
        goto generic_error;

    // アンビエント照明を作成し、シーンに追加する。
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_AMBIENT, D3DVAL(0.1),
                                  D3DVAL(0.1), D3DVAL(0.1), &light2)))
        goto generic_error;
    if (FAILED(scene->AddLight(light2)))
        goto generic_error;

    // パラレルポイント照明を作成し、太陽のフレームに追加する。
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_PARALLELPOINT,
                                  D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9),
                                  &light3)))
        goto generic_error;
    if (FAILED(sun->AddLight(light3)))
        goto generic_error;

    // 終了処理
    RELEASE(sun_builder);
    RELEASE(planet_builder);
    RELEASE(moon_builder);
    RELEASE(sun_mesh);
    RELEASE(planet_mesh);
    RELEASE(moon_mesh);
    RELEASE(sun);
    RELEASE(planet);
    RELEASE(moon);
    RELEASE(lights);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(light3);
    return TRUE;

generic_error:
    DISPLAYMSG("A failure occurred while building the scene.");
ret_with_error:
    RELEASE(sun_builder);
    RELEASE(planet_builder);
    RELEASE(moon_builder);
    RELEASE(sun_mesh);
    RELEASE(planet_mesh);
    RELEASE(moon_mesh);
    RELEASE(sun);
    RELEASE(planet);
    RELEASE(moon);
    RELEASE(lights);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(light3);
    return FALSE;
}

RenderScene

RenderScene関数は、実際にシーンをスクリーンに描画する。BuildSceneが作成したシーンを次の手順に従って描画する。

  1. IDirect3DRMFrame3::Moveを使用して、シーンを移動する。
  2. IDirect3DRMViewport2::Clearを使用して、ビューポートをクリアする。
  3. IDirect3DRMViewport2::Renderを使用して、シーンをレンダリングする。
  4. IDirect3DRMDevice3::Updateを使用して、ウィンドウを更新する。

RenderScene関数ソースコード

// ビューポートをクリアし、次のフレームをレンダリングし、ウィンドウを更新する。

static BOOL RenderScene()
{
    HRESULT rval;

    // シーンの移動。
    rval = myglobs.scene->Move(D3DVAL(1.0));
    if (FAILED(rval))
    {
        DISPLAYMSG("Moving scene failed.");
        return FALSE;
    }

    // ビューポートのクリア。
    rval = myglobs.view->Clear();
    if (FAILED(rval))
    {
        DISPLAYMSG("Clearing viewport failed.");
        return FALSE;
    }

    // シーンをビューポートにレンダリングする。
    rval = myglobs.view->Render(myglobs.scene);
    if (FAILED(rval))
    {
        DISPLAYMSG("Rendering scene failed.");
        return FALSE;
    }

    // ウィンドウの更新。
    rval = myglobs.dev->Update();
    if (FAILED(rval))
    {
        DISPLAYMSG("Updating device failed.");
        return FALSE;
    }
    return TRUE;
}

CreateObjects

CreateObjectsは、サンプルのグローバル変数を初期化し、オブジェクトを作成する。グローバル変数を初期化した後、デバイスの作成に必要な手順を実行し、デバイスをアプリケーションのメインウィンドウに関連付け、マスターシーンフレーム、カメラフレーム、ビューポートを作成する。以下の手順に従う。

  1. DirectDrawのDirectDrawCreateClipper関数を使用して、DirectDrawClipperオブジェクトを作成する。
  2. DirectDrawClipperオブジェクトのSetHWndメソッドを使用して、アプリケーションのウィンドウをDirectDrawClipperに関連付ける。DirectDrawClipperオブジェクトは、後続の描画を、指定した領域 (ここではアプリケーションのウィンドウ) に制限する。
  3. Direct3DRMCreate関数を使用して、Direct3D保持モードオブジェクトを作成する。
  4. WindowsのGetClientRect関数を使用して、アプリケーションのメインウィンドウの高さと幅を取得する。
  5. Direct3D保持モードオブジェクトのCreateDeviceFromClipperメソッドを使用してデバイスを作成し、NULLを渡してデフォルトデバイスを作成する。さらに、アプリケーションのウィンドウの幅と高さをメソッドに渡す。
  6. IDirect3DRMWinDeviceインターフェイスをサポートするデバイスを問い合わせて、Direct3D保持モードのウィンドウデバイスを作成する。ウィンドウデバイスは、WM_ACTIVATEメッセージとWM_PAINTメッセージを処理する。
  7. IDirect3DRM3::CreateFrameを使用して、マスターシーンフレームを作成する。
  8. IDirect3DRM3::CreateFrameを使用して、カメラフレームを作成する。
  9. IDirect3DRM3::CreateViewportを使用して、Direct3D保持モードのビューポートを作成する。
  10. BuildSceneを使用して、シーンを作成する。

CreateObjects関数ソースコード

// グローバル変数を初期化し、デバイスとオブジェクトを作成する。

BOOL CreateObjects(HWND win)
{
    HRESULT rval; // 戻り値
    RECT rc;      // メインウィンドウの矩形の境界
    int width;    // デバイスの幅
    int height;   // デバイスの高さ

    // グローバル変数構造体の全体をゼロに初期化する。
    memset(&myglobs, 0, sizeof(myglobs));

    // DirectDrawClipperオブジェクトを作成し、ウィンドウを関連付ける。
    rval = DirectDrawCreateClipper(0, &lpDDClipper, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create DirectDrawClipper object.");
        return FALSE;
    }
    rval = lpDDClipper->SetHWnd(0, win);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to set the window handle for the DirectDrawClipper.");
        return FALSE;
    }

    // Direct3D保持モードオブジェクトを作成する。
    rval = Direct3DRMCreate(&lpD3DRM);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create Direct3DRM.");
        return FALSE;
    }

    // Direct3D保持モードのデフォルトデバイスを作成する。
    GetClientRect(win, &rc);

    rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                           NULL, // Default device
                           rc.right, rc.bottom, &myglobs.dev);

    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create the D3DRM device.");
        return FALSE;
    }

    // WM_ACTIVATEとWM_PAINTメッセージを処理するため、
    // Direct3D保持モードのウィンドウデバイスを作成する。
    rval = myglobs.dev->QueryInterface(IID_IDirect3DRMWinDevice,
                                       (void **) &myglobs.windevice);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create the window device.");
        return FALSE;
    }

    // マスターシーンフレームとカメラフレームを作成する。
    rval = lpD3DRM->CreateFrame(NULL, &myglobs.scene);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create the master scene frame.");
        return FALSE;
    }

    rval = lpD3DRM->CreateFrame(myglobs.scene, &myglobs.camera);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create the camera's frame.");
        return FALSE;
    }

    // デバイス、カメラフレーム、デバイスの幅と高さを使用して、
    // Direct3D保持モードのビューポートを作成する。
    width = myglobs.dev->GetWidth();
    height = myglobs.dev->GetHeight();

    rval = lpD3DRM->CreateViewport(myglobs.dev, myglobs.camera, 0, 0,
                                   width, height, &myglobs.view);
    if (FAILED(rval)) {
        myglobs.bInitialized = FALSE;
        RELEASE(myglobs.dev);
        return FALSE;
    }

    // レンダリングするシーンを作成する。
    if (!BuildScene(lpD3DRM, myglobs.dev, myglobs.scene,
                    myglobs.camera))
        return FALSE;

    // グローバル変数は初期化された。
    myglobs.bInitialized = TRUE;

    return TRUE;
}

InitApp

InitApp関数は、メインウィンドウクラスとメインウィンドウを作成する。これは、Windows アプリケーションでは一般的な処理である。InitApp から呼び出されるDirect3D保持モードは、CreateObjectsの呼び出しだけである。

InitApp関数ソースコード

// メインウィンドウを作成し、オブジェクトを初期化する。

static HWND InitApp(HINSTANCE this_inst, int cmdshow)
{
    HWND win;     // メインウィンドウハンドル
    WNDCLASS wc;

    // ウィンドウクラスを設定して登録する。
    wc.style = CS_HREDRAW | CS_VREDRAW;
    wc.lpfnWndProc = WindowProc;
    wc.cbClsExtra = 0;
    wc.cbWndExtra = sizeof(DWORD);
    wc.hInstance = this_inst;
    wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);
    wc.hCursor = LoadCursor(NULL, IDC_ARROW);
    wc.hbrBackground = (HBRUSH)GetStockObject(BLACK_BRUSH);
    wc.lpszMenuName = NULL;
    wc.lpszClassName = "D3DRM Example";
    if (!RegisterClass(&wc))
        return FALSE;

    // ウィンドウの作成。
    win = CreateWindow(
            "D3DRM Example",                   // クラス
            "RMBegin2: Direct3DRM Sample Two", // キャプション
            WS_OVERLAPPEDWINDOW,               // スタイル
            CW_USEDEFAULT,                     // init. x pos
            CW_USEDEFAULT,                     // init. y pos
            350,                               // init. x size
            300,                               // init. y size
            NULL,                              // 親ウィンドウ
            NULL,                              // メニューハンドル
            this_inst,                         // プログラムハンドル
            NULL                               // 作成パラメータ
        );
    if (!win)
        return FALSE;

    // グローバル変数を初期化し、デバイスを列挙し、
    // Direct3D保持モードオブジェクトを作成する。
    if (!CreateObjects(win))
        return FALSE;

    // ウィンドウの表示。
    ShowWindow(win, cmdshow);
    UpdateWindow(win);

    return win;
}

WinMain

WinMain関数は、アプリケーションにメッセージループを提供する。グローバル変数が初期化されていて、アプリケーションが最小化されていなければ、WinMainはRenderSceneを使用してシーンをスクリーンに描画する。

WinMain関数ソースコード

// アプリケーションを初期化し、メッセージを処理して、シーンをレンダリングする。
int APIENTRY WinMain (HINSTANCE this_inst,
                      HINSTANCE prev_inst,
                      LPSTR cmdline,
                      int cmdshow)
{
    HWND    hwnd;
    MSG     msg;
    prev_inst;
    cmdline;

    // ウィンドウを作成し、オブジェクトを初期化する。
    if (!(hwnd = InitApp(this_inst, cmdshow)))
        return 1;

    while (TRUE) {
        // メッセージキューを監視して、メッセージを処理する。PeekMessageは
        // 制御を即座にアプリケーションに返すので、アプリケーションは
        // メッセージの処理とレンダリングを継続できる。
        // メッセージがWM_QUITであれば、アプリケーションが終了しているため、
        // この関数を抜ける。
        if (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {

            if (msg.message == WM_QUIT)
                break;
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }

        // アプリケーションが最小化されておらず、Direct3D保持モード
        // オブジェクトが初期化されていれば、レンダリングを行う。
        if (!myglobs.bMinimized && myglobs.bInitialized) {

            // シーンを1フレーム、レンダリングする。レンダリングが失敗したら、
            // WM_DESTROYメッセージを発行する。これにより、アプリケーションが
            // 終了する前に、リソースを解放できる。
            if (!RenderScene()) {
                DISPLAYMSG("Rendering failed. Aborting execution.");
                PostMessage(NULL, WM_DESTROY, 0, 0);
                break;
            }

        // このアプリケーションが現在レンダリングをしていなければ、
        // 他のアプリケーションに制御を渡す。
        } else
              WaitMessage();

    }
    return msg.wParam;
}

WindowProc

WindowProcは、アプリケーションのメインウィンドウのメッセージを処理する。フラグをセットして、アプリケーションが最小化されているときはレンダリングを停止させる。さらに、この関数は、アプリケーションウィンドウのサイズ変更、ウィンドウのアクティブ化、描画、アプリケーションがシャットダウンしたときのオブジェクト解放を行う。

ユーザがアプリケーションウィンドウのサイズを変更すると、RMBegin2サンプルはシーンのサイズを増減することで、ウィンドウの画像を継続して表示させる。この関数は、以下の手順に従って、WM_SIZEメッセージ(ウィンドウのサイズ変更)を処理する。

  • アプリケーションが最小化されている場合、サイズを変更する必要がないため、最小化フラグをセットして、関数から抜ける。
  • 現在のウィンドウ、ビューポート、デバイスの幅と高さを取得する。
  • アプリケーションウィンドウが現在のデバイスよりも大きく変更された場合、前のビューポート、デバイス、ウィンドウデバイスを破棄して、新しく作成する。アプリケーションウィンドウが現在のデバイスよりも小さく変更された場合は、ビューポートだけを作成し直す。

WindowProcは、IDirect3DRMWinDevice::HandleActivateメソッドを使用して WM_ACTIVATE メッセージを、IDirect3DRMWinDevice::HandlePaintメソッドを使用して WM_PAINT メッセージを処理する。

WindowProc関数ソースコード

// メインウィンドウのメッセージを処理する。

LRESULT CALLBACK WindowProc(HWND win,
                            UINT msg,
                            WPARAM wparam,
                            LPARAM lparam)
{
HRESULT rval;

switch (msg) {

    case WM_SIZE:
        // ウィンドウのサイズ変更を処理する。アプリケーションが最小化されて
        // いれば、フラグをセットし、最小化時のレンダリングを停止し、
        // 関数から抜ける。それ以外の場合は、最小化フラグが
        // クリアされていることを確認して、最小化以外の
        // ウィンドウサイズの変更のための検査を行う。
        {
        if (SIZE_MINIMIZED == wparam)
        {
            myglobs.bMinimized = TRUE;
            break;
        }
        else
            myglobs.bMinimized = FALSE;

        // ウィンドウサイズの変更を処理する。ウィンドウの現在の幅と高さを
        // 取得する。
        int width = LOWORD(lparam);
        int height = HIWORD(lparam);

        // ビューポートやデバイスなどのグローバル変数が初期化されていれば、
        // ビューポートとデバイスの幅と高さを取得する。
        // 必要に応じて、新しいデバイスとウィンドウデバイス、またはビューポート
        // を作成する。新しいデバイスとウィンドウデバイスは、
        // ウィンドウが前のデバイスよりも大きな場合にだけ必要になる。
        if (myglobs.bInitialized)
        {
            int view_width = myglobs.view->GetWidth();
            int view_height = myglobs.view->GetHeight();
            int dev_width = myglobs.dev->GetWidth();
            int dev_height = myglobs.dev->GetHeight();

            // ウィンドウサイズの幅または高さが増えているか調べる。
            if (width > dev_width || height > dev_height)
            {
                // アプリケーションウィンドウは現在のデバイスよりも大きくなっている。
                // 前のビューポートとデバイスを破棄して、新しく作成する。
                // デバイスを解放する前に、ビューポートを解放すること。
                // この順序を間違えると、一般保護違反が発生する。
                myglobs.bInitialized = FALSE;
                RELEASE(myglobs.view);
                RELEASE(myglobs.dev);

                // デフォルトのDirect3D保持モードデバイスを新規作成する。
                rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                                        NULL, // Default device
                                        width, height,
                                        &myglobs.dev);

                if (FAILED(rval))
                {
                    // 新しいデバイスが作成できない場合、ユーザに通知して、
                    // アプリケーションをシャットダウンする。
                    DISPLAYMSG("Failed to create the D3DRM device.");
                    PostMessage(NULL, WM_DESTROY, 0, 0);
                    return FALSE;
                }

                // 前のDirect3D保持モードウィンドウデバイスを破棄し、
                // 新規作成したデバイスと一致する新しいウィンドウデバイ
                // スを作成する。ウィンドウデバイスは、WM_ACTIVATEと
                // WM_PAINTメッセージを処理する。
                RELEASE(myglobs.windevice);
                rval = myglobs.dev->QueryInterface(
                                       IID_IDirect3DRMWinDevice,
                                       (void **) &myglobs.windevice);
                if (FAILED(rval)) {
                    DISPLAYMSG("Failed to create the window device.");
                    return FALSE;
                }

            }

            // ウィンドウのサイズが変更されていれば、前のビューポートを
            // 解放して、新しいビューポートを適切なサイズで作成する。
            myglobs.bInitialized = FALSE;
            RELEASE(myglobs.view);
            rval = lpD3DRM->CreateViewport(myglobs.dev,
                                           myglobs.camera,
                                           0, 0, width, height,
                                           &myglobs.view);
            if (FAILED(rval))
            {
                // 新しいビューポートが作成できない場合、ユーザに通知して、
                // アプリケーションをシャットダウンする。
                DISPLAYMSG("Failed to create a new viewport.");
                PostMessage(NULL, WM_DESTROY, 0, 0);
                break;
            }

            myglobs.bInitialized = TRUE;
        }
        }
        break;

    case WM_ACTIVATE:
        // ウィンドウデバイスのHandleActivateメソッドを使用して、
        // ウィンドウのアクティブ化を処理する。
        if (myglobs.bInitialized)
            if (FAILED(myglobs.windevice->HandleActivate(wparam)))
                DISPLAYMSG("Failed to handle WM_ACTIVATE.");
        break;

    case WM_PAINT:
        // グローバル変数が初期化されていれば、
        // ウィンドウデバイスのHandlePaintメソッドを使用して、
        // 再描画を処理する。
        if (!myglobs.bInitialized)
            return DefWindowProc(win, msg, wparam, lparam);

        // ウィンドウデバイスを使用して、再描画を処理する。
        RECT rc;
        PAINTSTRUCT ps;

        if (GetUpdateRect(win, &rc, FALSE)) {
            BeginPaint(win, &ps);
            if (FAILED(myglobs.windevice->HandlePaint(ps.hdc)))
                DISPLAYMSG("Failed to handle WM_PAINT.");
        }
        EndPaint(win, &ps);
        break;

    case WM_DESTROY:
        // bInitializedフラグをクリアし、オブジェクトを解放して、
        // WM_QUITメッセージを発行して、アプリケーションを終了する。
        // デバイスを解放する前に、ビューポートを解放すること。
        // この順序を間違えると、一般保護違反が発生する。
        myglobs.bInitialized = FALSE;
        RELEASE(myglobs.view);
        RELEASE(myglobs.windevice);
        RELEASE(myglobs.dev);
        RELEASE(lpD3DRM);
        RELEASE(lpDDClipper);
        PostQuitMessage(0);
        break;

    default:
        return DefWindowProc(win, msg, wparam, lparam);
    }
    return 0L;
}

関連トピック

ここではDirect3D保持モードを使用してオブジェクトを作成し、スクリーンに配置する基本を学習した。Direct3D保持モードのサンプルコードが、前よりも簡単に理解できるようになったであろう。ほとんどのサンプルは、RMMainが提供するヘルパコードを使用してデバイスを作成し、シーンをレンダリングしているが、独自のBuildScene関数により、それぞれのシーンを作成している。

次のステップとしては、EggやGlobeなどのDirect3D保持モードサンプルを見るとよい。このサンプルは、RMBegin1やRMBegin2と似た機能を持つ。

もう1つのDirect3D保持モードの一般的なタスクについては、「デバイスの列挙：RMEnumサンプル」を参照すること。この節では、RMEnumのサンプルコードのウォークスルーを行う。RMEnumは、デバイスを列挙する方法に焦点を当てている。

保持モードサンプルのすべての概要については、「サンプル」を参照すること。


デバイスの列挙：RMEnumサンプル

デバイスの列挙は、Microsoft® Direct3D®保持モードの基本的な概念である。デフォルトデバイスは、デバイスを列挙せずに作成できる。 デバイスを列挙すると、システムにあるデバイスを識別し、もっとも適切なデバイスを選択して、より高度な機能が使用できる。

この項では、サンプルRMEnumのコードのウォークスルーを行う。RMEnumはシステムのハードウェアデバイスおよびソフトウェアデバイスを列挙し、最適なデバイスを選択して、デバイスを作成する。さらに、列挙したデバイスをアプリケーションの [ファイル] メニューに追加し、ユーザがメニューからデバイスを選択できるようにする。実際のDirect3D保持モードアプリケーションとは異なり、RMEnumは3Dオブジェクトの表示とレンダリングは行わない。このサンプルは、説明を簡潔にするために、列挙だけを扱っている。

この項は、ユーザがCまたはC++のプログラミング経験があること、および、メッセージループ、ウィンドウの作成、メニューの使用など、Windowsプログラミングの基本概念に精通していることを前提にしている。

この項は、次の項目に分かれている。

  • 前提
  • グローバル宣言
  • 関数概要
  • 関連トピック

前提

RMEnumはDDraw.libとD3DRM.libをリンクする。RMEnumは、Error.cのMsgとD3DRMErrorToString ヘルパ関数を使用して、エラー発生時に詳細情報を表示する。デフォルトでは、Error.cはMicrosoft® DirectX® Software Development Kit (SDK)のSamples\Miscディレクトリに入っている。ヘルパ関数を使用する代わりに、Microsoft® Windows®の標準MessageBox関数を使用するだけでもよいが、わかりやすく詳細なエラー報告は得られない。サンプルは、RMEnum.rcが提供するメニューなどのリソースもリンクしている。

グローバルユニーク識別子(GUID)を適切に初期化するために、Direct3D アプリケーションは、 コードの先頭で次の定義を行う必要がある。

#define INITGUID

サンプルのRMEnum.cpp ファイルは次のヘッダファイルをインクルードする。

#include <windows.h>   /* 標準Windowsヘッダファイル */
#include <direct.h>    /* DirectDrawの定義 */
#include <d3drmwin.h>  /* Direct3D保持モードの定義 */
#include "RMEnum.h"    /* RMEnum.rcで使用する定数の定義 */
#include "rmerror.h"   /* rmerror.cの、エラー報告関数のプロトタイプ */

グローバル宣言

このサンプルでは、いくつかの定数とグローバル変数を定義して、情報を整理する。

RMEnum.cppでは、コードを簡略化するために、列挙するドライバの数を制限しているが、1回ドライバを列挙して使用可能なドライバ数を調べた後、もう1度列挙してドライバの機能を調べることもできる。実際のアプリケーションでは、このサンプルのようにサイズを固定した配列ではなく、ドライバ情報の動的なリストを管理することもある。

#define MAX_DRIVERS 5  /* 検出するDirect3Dのドライバ数を
                          恣意的に制限する。 */

アプリケーションで定義されているRELEASEマクロは、オブジェクトがNULL以外の場合にだけオブジェクトを解放し、解放後にオブジェクトをNULLに初期化する。すでに解放したオブジェクトを解放すると、ページフォールトなどの予期せぬ結果が発生するが、この手順によって、そうした問題が回避できる。

/* オブジェクトを解放するマクロ。 */
#define RELEASE(x) if (x != NULL) {x->Release(); x = NULL;}

myglobs構造体は、アプリケーションの現在の状態に加えて、デバイスとドライバの情報を収集する。Direct3D保持モードおよびDirectDrawClipperオブジェクトもグローバルである(DirectDrawClipperオブジェクトは、描画を指定した領域に制限する)。

/*
 * グローバル変数
 */
LPDIRECT3DRM lpD3DRM = NULL;            /* Direct3DRMオブジェクト */
LPDIRECTDRAWCLIPPER lpDDClipper = NULL; /* DirectDrawClipperオブジェクト */

struct _myglobs {
    /* Direct3DRMデバイス */
    LPDIRECT3DRMDEVICE dev;

    /* 使用可能なDirect3D (D3D)ドライバのGUID */
    GUID DriverGUID[MAX_DRIVERS];

    /* 使用可能なD3Dドライバの名前 */
    char DriverName[MAX_DRIVERS][50];

    /* 使用可能なD3Dドライバ数を示すカウンタ */
    int  NumDrivers;

    /* 現在使用中のD3Dドライバの数。enumDeviceFuncで、
     * 指定したドライバに設定する。 */
    int  CurrDriver;

    /* プログラムは終了中である。*/
    BOOL bQuit;

    /* すべてのD3Dオブジェクトは初期化されている。 */
    BOOL bInitialized;

    /* 現在のディスプレイモードのビット深度。 */
    DWORD BPP;
} myglobs;

関数概要

RMEnum.cppには、以下の関数が含まれている。

CreateObjectsは、グローバル変数を初期化するマスタ関数であり、EnumDevicesを使用してデバイスを列挙し、オブジェクトを作成する。InitAppはCreateObjectsを使用する。

BOOL CreateObjects(HWND win);

GetCurrentBitDepthは、現在のビット深度をCreateObjectsに返す。

static DWORD GetCurrentBitDepth(HWND);

EnumDevicesは、デバイスの列挙に使用するDirect3Dオブジェクトを取得し、直接モードのIDirect3D2::EnumDevices関数を使用して、パラメータとしてenumDeviceFuncコールバック関数を渡し、列挙したデバイスを [ファイル] メニューに入れる。

static BOOL EnumDevices(HWND);

enumDeviceFuncコールバック関数は、使用可能なドライバを循環し、最適なドライバを選択する。

static HRESULT WINAPI enumDeviceFunc(LPGUID,
                                            LPSTR,
                                            LPSTR,
                                            LPD3DDEVICEDESC,
                                            LPD3DDEVICEDESC,
                                            LPVOID);

RMEnumは、ユーザのメニュー選択に応じて、ChangeDriverを使用して他の使用可能なドライバに切り替える。

void ChangeDriver(HWND, WPARAM);

CleanUpAndQuitは、アプリケーションを終了する前にオブジェクトを解放する。

static void CleanUpAndQuit(void);

その他の関数 (InitApp、WinMain、AppAbout、WindowProc) は、標準 Windows関数を基に、サンプルRMEnum固有のコードを少し含んでいる。

static HWND InitApp(HINSTANCE, int);
int APIENTRY WinMain (HINSTANCE, HINSTANCE, LPSTR, int);
LRESULT CALLBACK AppAbout(HWND, UINT, WPARAM, LPARAM);
LRESULT CALLBACK WindowProc(HWND, UINT, WPARAM, LPARAM);

以上の関数の詳細については、この項の次の項目を参照すること。

  • CreateObjects
  • GetCurrentBitDepth
  • EnumDevices
  • enumDeviceFunc
  • ChangeDriver
  • CleanUpAndQuit
  • 標準Windows関数

CreateObjects

CreateObjectsは、サンプルRMEnumの核となるコードである。グローバル変数を初期化し、現在のビット深度を取得した後、EnumDevicesを使用して実際にデバイスを列挙する。enumDeviceFuncコールバック関数は、後でビット深度を使用して、現在のビット深度をサポートするドライバを決定する。

CreateObjectsは、デバイスを列挙した後、デバイスの作成に必要な手順を実行し、アプリケーションのメインウィンドウに関連付ける。以下の手順に従う。

  1. Direct3DRMCreateを使用して、Direct3D保持モードオブジェクトを作成する。
  2. DirectDrawのDirectDrawCreateClipper関数を使用して、DirectDrawClipperオブジェクトを作成する。
  3. DirectDrawClipperのSetHWndメソッドを使用して、アプリケーションのウィンドウをクリッパに関連付ける。DirectDrawClipperオブジェクトは、後続の描画を、指定した領域 (ここではアプリケーションのウィンドウ) に制限する。
  4. WindowsのGetClientRect関数を使用して、アプリケーションのメインウィンドウの高さと幅を取得する。
  5. Direct3D保持モードオブジェクトのCreateDeviceFromClipperメソッドを使用してデバイスを作成し、列挙により選択したドライバ、およびアプリケーションウィンドウの幅と高さをメソッドに渡す。

次に、CreateObjects関数のソースコードを示す。

/*
 * グローバル変数を初期化し、デバイスを列挙して、オブジェクトを作成する。
 */
BOOL CreateObjects(HWND win)
{
    HRESULT rval; /* 戻り値 */
    RECT rc;      /* メインウィンドウの矩形の境界 */

    /*
     * グローバル変数の初期化。
     */
    memset(&myglobs, 0, sizeof(myglobs));

    /*
     * ディスプレイの現在のビット深度を記録する。
     */
     myglobs.BPP = GetCurrentBitDepth(win);

    /*
     * D3Dドライバを列挙し、1つを選択する。
     */
    if (!EnumDevices(win))
        return FALSE;

    /*
     * Direct3DRMオブジェクトとウィンドウオブジェクトを作成する。
     */
    rval = Direct3DRMCreate(&lpD3DRM);
    if (rval != D3DRM_OK) {
        Msg("Failed to create Direct3DRM.\n%s", D3DRMErrorToString(rval));
        return FALSE;
    }

    /*
     * DirectDrawClipperオブジェクトを作成し、ウィンドウに関連付ける。
     */
    rval = DirectDrawCreateClipper(0, &lpDDClipper, NULL);
    if (rval != DD_OK) {
        Msg("Failed to create DirectDrawClipper object");
        return FALSE;
    }
    rval = lpDDClipper->SetHWnd(0, win);
    if (rval != DD_OK) {
        Msg("Failed to set the window handle for the DirectDrawClipper");
        return FALSE;
    }
    /*
     * 選択したD3DドライバでD3DRMデバイスを作成する。GUIDを
     * NULLにセットすると、列挙なしにデフォルトデバイスを作成できる。
     */
    GetClientRect(win, &rc);

    rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                           &myglobs.DriverGUID[myglobs.CurrDriver],
                           rc.right, rc.bottom, &myglobs.dev);

    if (rval) {
        Msg("Failed to create the D3DRM device.\n%s",
            D3DRMErrorToString(rval));
        return FALSE;
    }

    /*
     * グローバル変数は初期化された。
     */
    myglobs.bInitialized = TRUE;

    return TRUE;
}

GetCurrentBitDepth

GetCurrentBitDepth関数は、現在のデバイスのビット深度性能を決定して、DirectDraw ビット深度フラグの形式で情報を返す。ビット深度は、デバイスのカラー設定 (8ビット、16ビット、または24ビットカラー) を表わす。

/*
 * 現在のディスプレイのビット深度をBPP (bits per pixel) で表わす
 * DirectDrawビット深度フラグを取得する。
 */
static DWORD GetCurrentBitDepth(HWND win)
{
    HDC hdc;
    int BPP;

    /*
     * 現在のディスプレイのBPPを記録する。
     */
    hdc = GetDC(win);
    BPP = GetDeviceCaps(hdc, BITSPIXEL);
    ReleaseDC(win, hdc);

    /*
     * BPP値をDirectDrawビット深度にマッピングする。
     */
    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;
    }
}

EnumDevices

RMEnumのEnumDevices関数は、以下の手順に従って、デバイスを列挙する。手順には、サンプルの変数とコードの一部も示す。

  1. DirectDrawCreate関数を使用して、DirectDrawオブジェクトを作成する。
    LPDIRECTDRAW lpDD;
HRESULT rval;
rval = DirectDrawCreate(NULL, &lpDD, NULL);
  2. DirectDrawオブジェクトのQueryInterfaceメソッドを使用して、Direct3D 直接モードオブジェクトを取得する。Direct3D直接モードの詳細については、「Direct3D直接モード」を参照すること。
    LPDIRECT3D lpD3D;
rval = lpDD->QueryInterface(IID_IDirect3D, (void**) &lpD3D);
  3. Direct3D 直接モードオブジェクトのIDirect3D2::EnumDevices関数を使用して、システムのデバイスを列挙する。IDirect3D2::EnumDevicesはenumDeviceFuncコールバック関数をパラメータとして渡す。
    rval = lpD3D->EnumDevices(enumDeviceFunc, &myglobs.CurrDriver);

    このコールバック関数は、使用可能なデバイスを循環し、ある基準に合うドライバを選択する。

ARMEnumのEnumDevices関数はドライバを列挙した後、DirectDrawとDirect3Dのデバイスを解放し、アプリケーションの [ファイル] メニューにドライバを追加する。

lpD3D->Release();
lpDD->Release();

次に、RMEnumのEnumDevices関数の全ソースコードを示す。

/*
 * EnumDevices
 * 使用可能なDirect3Dドライバを列挙し、[ファイル] メニューに追加し、
 * 使用するドライバを1つ選択する。
 */
static BOOL EnumDevices(HWND win)
{
    LPDIRECTDRAW lpDD;
    LPDIRECT3D lpD3D;
    HRESULT rval;
    HMENU hmenu;
    int i;

    /*
     * DirectDrawオブジェクトを作成し、ドライバの列挙に使用する
     * Direct3Dインターフェイスを問い合わせる。
     */
    rval = DirectDrawCreate(NULL, &lpDD, NULL);
    if (rval != DD_OK) {
        Msg("Creation of DirectDraw HEL failed.\n%s",
            D3DRMErrorToString(rval));
        return FALSE;
    }
    rval = lpDD->QueryInterface(IID_IDirect3D, (void**) &lpD3D);
    if (rval != DD_OK) {
        Msg("Creation of Direct3D interface failed.\n%s",
            D3DRMErrorToString(rval));
        lpDD->Release();
        return FALSE;
    }
    /*
     * ドライバを列挙する。アプリケーション定義データとして、
     * 任意の値である-1を渡す。enumDeviceFuncコールバック関数は、
     * -1に対応して、特殊な初期化コードを実行する。
     */
    myglobs.CurrDriver = -1;
    rval = lpD3D->EnumDevices(enumDeviceFunc, &myglobs.CurrDriver);
    if (rval != DD_OK) {
        Msg("Enumeration of drivers failed.\n%s",
            D3DRMErrorToString(rval));
        return FALSE;
    }
    /*
     * 有効なドライバが少なくとも1つあることを保証する。
     */
    if (myglobs.NumDrivers == 0) {
        Msg("Could not find a D3D driver that is compatible with this \
            display depth");
        return FALSE;
    }
    lpD3D->Release();
    lpDD->Release();
    /*
     * ドライバ名を [ファイル] メニューに追加する。
     */
    hmenu = GetSubMenu(GetMenu(win), 0);
    for (i = 0; i < myglobs.NumDrivers; i++) {
        InsertMenu(hmenu, 2 + i, MF_BYPOSITION | MF_STRING,
                   MENU_FIRST_DRIVER + i,
                   myglobs.DriverName[i]);
    }
    return TRUE;
}

enumDeviceFunc

Direct3D 直接モードは、システムにインストールされたDirect3Dデバイスを列挙するコールバック関数のプロトタイプ定義として、D3DENUMDEVICESCALLBACKを定義している。RMEnumはenumDeviceFuncを列挙コールバック関数として提供する。Direct3D直接モードは、システムにインストールされたデバイスごとにenumDeviceFuncを呼び出し、デバイス情報をenumDeviceFuncに渡す。D3D直接モードが使用可能なドライバをループする間、enumDeviceFuncは、現在のディスプレイのビット深度でレンダリング可能なドライバに関する情報をグローバル変数に格納する。enumDeviceFuncは、ソフトウェアエミュレーションドライバよりも、ハードウェアドライバを優先的に選択する(ハードウェアドライバは一般的にレンダリングが高速なためである)。また、3次元照明の効果を上げるために、モノクロ照明よりもカラー照明を優先的に選択する。このサンプルでは、RMEnumが実際にはレンダリングを行わないため、この選択の効果は現れない。しかし、実際のアプリケーションでは、こうした選択によって、3Dグラフィックスの表示状態に大きな影響が出る。

enumDeviceFuncのパラメータには、デバイスのグローバルユニーク識別子 (GUID)、デバイスのテキスト記述、およびデバイス名がある。その他に、Direct3D 直接モードのD3DDEVICEDESC構造体が2つ含まれる。最初の構造体 (lpHWDesc) には、Direct3D デバイスのハードウェア能力、2つめの構造体 (lpHELDesc) には、デバイスのハードウェアエミュレーションレイヤ (HEL) のソフトウェアエミュレーション能力がそれぞれ格納される。最後のパラメータは、Direct3D 直接モードがこのコールバック関数を最初に呼び出すときに、アプリケーション定義データとして渡される。

次に、RMEnumのenumDeviceFuncコールバック関数の全ソースコードを示す。

/*
 * enumDeviceFunc
 * 使用可能なD3Dドライバの名前とGUIDを記録するコールバック関数。
 * システムのドライバを選択する。ソフトウェアドライバよりも
 * ハードウェアドライバ、また、モノクロ照明よりもカラー照明を
 * 優先的に選択する。myglobs.CurrDriverに、選択したドライバを
 * 設定する。
 */
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;       /* 現在のドライバの記述。*/

    /*
     * このアプリケーションが定義するデータ。-1であれば、
     * 最初に列挙されたドライバを現在のドライバにすることを示す。
     */
    int *lpStartDriver = (int *)lpContext;

    /*
     * どのデバイス記述を調べるか決定する。ドライバはハードウェア (HW) か
     * ソフトウェアである。ソフトウェアドライバは、HEL (ハードウェア
     * エミュレーションレイヤ) でサポートされる。
     */
    lpDesc = lpHWDesc->dcmColorModel ? lpHWDesc : lpHELDesc;
    /*
     * このドライバが、現在のディスプレイのビット深度ではレンダリングできない
     * 場合、D3DENUMRET_OKを返して、このドライバをスキップする。
     * 3D3は次のドライバに対して enumDeviceFuncを再び呼び出すので、
     * 列挙は自動的に継続される。
     */
    if (!(lpDesc->dwDeviceRenderBitDepth & myglobs.BPP))
        return D3DENUMRET_OK;
    /*
     * このドライバのGUIDと名前を記録する。
     */
    memcpy(&myglobs.DriverGUID[myglobs.NumDrivers], lpGuid, sizeof(GUID));
    lstrcpy(&myglobs.DriverName[myglobs.NumDrivers][0], lpDeviceName);
    /*
     * ソフトウェアよりもハードウェアを、モノクロ照明よりもカラー照明を
     * 選択する。
     */
    if (*lpStartDriver == (int)-1) {
        /*
         * これが最初の有効なドライバである。そこで、これがハードウェア
         * ドライバであるかどうか、モノクロ照明に限定されているかどうかを
         * 記録する。
         */
        myglobs.CurrDriver = myglobs.NumDrivers;
        hardware = lpDesc == lpHWDesc ? TRUE : FALSE;
        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;
    } else if (lpDesc == lpHWDesc && !hardware) {
        /*
         * このドライバがハードウェアドライバであり、開始ドライバが
         * ハードウェアドライバでなければ、このドライバを新しいドライバにして、
         * ハードウェアかつモノクロ性能であることを記録する。D3Dが
         * enumDeviceFuncを次に呼び出すとき、そのドライバは、
         * この新しい開始ドライバと比較される。
         */
        myglobs.CurrDriver = 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_RGB && mono) {
            /*
             * このドライバと開始ドライバが同じタイプ
             * (両方ともハードウェアか、両方ともソフトウェア) で、このドライバは
             * カラー照明だが開始ドライバはカラー照明でなければ、このドライバを
             * 新しいドライバに設定して、性能を記録する。
             * D3DがenumDeviceFuncを次に呼び出すとき、そのドライバは、
             * この新しい開始ドライバと比較される。
             */
            myglobs.CurrDriver = myglobs.NumDrivers;
            hardware = lpDesc == lpHWDesc ? TRUE : FALSE;
            mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;
        }
    }
    /*
     * 次のドライバに備えて、現在のドライバ番号を
     * 増やす。
     */
    myglobs.NumDrivers++;

    /* ドライバの最大数に達したら、列挙を停止する。 */
    if (myglobs.NumDrivers == MAX_DRIVERS)
        return (D3DENUMRET_CANCEL);
    /*
     * ドライバの列挙を継続する。D3Dは次のドライバに対して、
     * この情報を使ってenumDeviceFuncを呼び出す。
     */
    return (D3DENUMRET_OK);
}

ChangeDriver

ChangeDriverは、サンプルRMEnumにとって必須の関数ではないが、ユーザがドライバを選択する柔軟性を付加する。ChangeDriverは、メニュー選択に応じて現在のドライバを変更する。そして、RMEnumのCreateObjects関数がデバイスを最初に作成したように、Direct3D保持モードオブジェクトのCreateDeviceFromClipperメソッドを使用してデバイスを再作成する。

次に、ChangeDriverのソースコードを示す。

/*
 * 現在のデバイスを解放して、新しいデバイスを作成する。
 */
void ChangeDriver(HWND win, WPARAM wparam)
{
    HRESULT rval;
    RECT rc;

    /*
     * 前のドライバ選択をLastDriverとして保存する。
     */
    int LastDriver = myglobs.CurrDriver;

    /*
     * 選択内容が変更されたため、グローバル変数は正確でなくなる。
     */
    myglobs.bInitialized = FALSE;

    /*
     * 現在のデバイスを解放する。
     */
    RELEASE(myglobs.dev);

    /*
     * 現在のドライバをメニューから選択されたドライバに設定する。
     */
    myglobs.CurrDriver = LOWORD(wparam)-MENU_FIRST_DRIVER;

    /*
     * ウィンドウの境界矩形を取得する。グローバルオブジェクトDirectDrawClipper
     * を使用して、そのウィンドウの新しい現在のドライバを作成する。
     */
    GetClientRect(win, &rc);

    rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                             &myglobs.DriverGUID[myglobs.CurrDriver],
                             rc.right, rc.bottom, &myglobs.dev);

    /*
     * エラーが発生したら、前のドライバを再作成する。
     */
    if (rval) {
        myglobs.CurrDriver = LastDriver;

        rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                                 &myglobs.DriverGUID[myglobs.CurrDriver],
                                 rc.right, rc.bottom, &myglobs.dev);
        if (rval) {
            Msg("Failed to create the D3DRM device.\n%s",
                D3DRMErrorToString(rval));
            CleanUpAndQuit();
        }
        else {
            Msg("There was not enough video memory available to use the \
                 3D accelerated hardware device.\nRestoring old software \
                 device.");
            myglobs.bInitialized = TRUE;
        }
    }
    else {
        /*
         * グローバル変数は、再び適切に初期化された。
         */
        myglobs.bInitialized = TRUE;
    }
}

CleanUpAndQuit

ごく短いCleanUpAndQuit関数は、グローバルオブジェクトを解放して、quitフラグをTRUEに設定し、アプリケーションの終了準備が整ったことを示す。

void CleanUpAndQuit(void)
{
    myglobs.bInitialized = FALSE;
    RELEASE(myglobs.dev);
    RELEASE(lpD3DRM);
    RELEASE(lpDDClipper);
    myglobs.bQuit = TRUE;
}

標準Windows関数

RMEnum.cppの、その他の関数 (InitApp、WinMain、AppAbout、WindowProc) は、本来は標準Windows関数で、サンプルRMEnumに固有の短いコードを含んでいる。詳細については、RMEnumのサンプルコードを参照すること。

  • InitAppは、メインウィンドウを作成し、サンプルのCreateObjects関数を使用する。
  • WinMainは、InitApp関数を呼び出す。 この関数は、Windowsのメインメッセージループを含んでおり、グローバル変数 myglobs.bQuitがTRUEになるまで、メッセージを処理する。WinMainは、アプリケーションの終了を通知する標準Windows WM_QUITメッセージに応じてCleanUpAndQuitを使用する。
  • AppAboutは、アプリケーションの [About] ダイアログボックスのメッセージを処理する。
  • WindowProcは、アプリケーションのメインウィンドウのメッセージを処理する。列挙したドライバを選択できるよう [ファイル] メニューを初期化し、アプリケーションのChangeDriver関数を使用して、ユーザのドライバ選択を処理する。WindowProcはCleanUpAndQuitを使用して、標準Windows WM_DESTROYメッセージに応じてリソースを解放する。このメッセージは、ユーザがアプリケーションを終了したので、Windowsがアプリケーションウィンドウを破棄中であることを通知するものである。

関連トピック

ここではデバイスを列挙する方法を学習した。Direct3D保持モードのサンプルコードが、前よりも簡単に理解できるようになったであろう。ほとんどのサンプルは、RMMainが提供するヘルパコードを使用してデバイスを列挙する。次のステップとしては、EggやGlobeなどのサンプルを見て、シーンの裏でデバイスの列挙を行っていることを念頭におきながら、レンダリングする方法を調べるとよい。

保持モードサンプルのすべての概要については、「サンプル」を参照すること。


基礎知識

以下のトピックでは、3Dグラフィックスを組み込むプログラムを書く前に理解する必要のある技術的な概念をいくつか説明する。それらの項では、座標系と変換の一般的な説明を行っている。これは、モデル、照明、ビューイングパラメータの設定などの、幅広いアーキテクチャ上の詳細事項を説明するものではない。そうした事項の詳細については、「Direct3D保持モードアーキテクチャ」を参照すること。

3Dグラフィックスを作った経験がある場合には、Microsoft® Direct3D® 保持モードに特有の情報だけを調べるように以下のトピックを読むこと。

  • 3D座標系
  • 3D変換
  • ポリゴン
  • 三角形の展開図と扇形
  • ベクトル、頂点、および4元数
  • Zバッファとオーバーレイ

3D座標系

3Dグラフィックスアプリケーションでは、通常、左手座標系と右手座標系の2つのデカルト座標系を使用する。両方の座標系で、x軸の正方向は右側であり、y軸の正方向は上方である。z軸の正方向は、x軸の正方向に左手または右手の指を向け、それをy軸の正の方向に回転した方向になる。親指の方向、手前または奥が、この座標系でのz軸の正方向である。

この項は、Direct3Dの座標系とユーザのアプリケーションが使用できる座標タイプを説明する。

  • Direct3Dの座標系
  • U座標とV座標

Direct3Dの座標系

Direct3Dはデフォルトでは左手座標系を使用する。つまり、下の図に示すように正のz軸が見る者から離れる方向を指す。

左手座標系では、回転は、見る者を指す任意の軸の周囲を時計回りに回転する。

右手座標系で作業する必要のある場合、たとえば、右手座標系に従うアプリケーションを移植する場合には、Direct3Dに渡されるデータに2つの単純な変更を加えるだけで行うことができる。

注: DirectXバージョン6.0からは、IDirect3DRM3::SetOptionsを使用して、Direct3D保持モードに対して右手座標系を使用することを指示できる。IDirect3DRM3::SetOptionsを使用すると、データを変更する必要がなくなる。

DirectX バージョン6.0より前のバージョンでは、右手座標系を使用する場合、Direct3D保持モードに渡すデータを、次のように変更する必要がある。

  • 三角形の頂点の順序を反転し、システムが前から時計回りにたどれるようにする。つまり、頂点をv0、v1、v2とすると、Direct3Dにはv0、v2、v1として渡す。
  • ビュー マトリックスを使用して、ワールド空間をz軸方向に-1スケーリングする。そのためには、ビュー マトリックスに使用するD3DMATRIX構造体の_13、_23、_33、_43の各メンバの符号を反転する。

U座標とV座標

Direct3Dは、テクスチャ座標も使用する。この座標(uとv)は、オブジェクト上にテクスチャをマップするときに使用する。vベクトルは、テクスチャの方向または向きを表し、z軸に沿って存在する。uベクトル(またはアップベクトル)は通常、y軸に沿って存在し、その原点は[0,0,0]にある。uとv座標の詳細については、「ラップ」を参照すること。

3D変換

3Dグラフィックスと機能するプログラムでは、幾何変換を使用して次のことが可能である。

  • 別のオブジェクトを基準にしてオブジェクトの位置を表すこと。
  • オブジェクトを回転、切断、サイズを変更すること。
  • 見る位置、方向、およびパースペクティブを変更すること。

4×4行列を使用して、任意の点を別の点に変換することができる。以下の例では、行列を使用して点(x,y,z)を変換して新しい点(x', y', z')を作り出している。

以下の操作を(x, y, z)および行列に実行して点(x', y', z')を作り出す。

最も普通の変換は、平行移動、回転およびスケーリングである。これらの効果を作り出す行列を1つの行列に結合して、複数の変換を一度に計算することができる。たとえば、1つの行列を作成して、一連の点を平行移動し回転することができる。

行列は行順に指定される。たとえば、次の行列は、配列で表すことも可能である。

この行列に対応する配列は、以下のようになる。

D3DMATRIX scale = {
    D3DVAL(s),    0,            0,            0,
    0,            D3DVAL(s),    D3DVAL(t),    0,
    0,            0,            D3DVAL(s),    D3DVAL(v),
    0,            0,            0,            D3DVAL(1)
};

この項では、Direct3を介してユーザのアプリケーションが使用できる3D変換を説明する。

  • 平行移動
  • 回転
  • スケーリング

このマニュアルの他の部分でも変換について説明している。保持モードのビューポートだけを取り扱った項「変換」に変換の一般的な説明がある。フレーム中の変換の説明については、「変換」を参照すること。以上の各項では、保持モードAPIを説明しているが、変換のアーキテクチャと数学は、保持モードと直接モードの両方に適用される。

平行移動

以下の変換は、点(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次元オブジェクトは、メッシュで構成される。メッシュとは、面の集合であり、各面は単純なポリゴンで表される。基本的なポリゴンのタイプは、三角形である。保持モードアプリケーションでは、4頂点以上のポリゴンを指定できるにもかかわらず、システムは、オブジェクトをレンダリングする前にポリゴンを三角形に変換する。直接モードアプリケーションでは、三角形を使用しなければならない。

この項では、ユーザのアプリケーションがDirect3Dポリゴンをどのように使用するかを説明する。

  • 図形要件
  • 面法線と頂点法線
  • シェーディングモード
  • 三角形補間要素

図形要件

三角形はよく使用されるポリゴンのタイプである。三角形は、レンダラがポリゴンに要求する2条件 (常に凸であり、常に平坦である) を満たすからである。ポリゴンは、ポリゴンの任意の2点を直線で結んだとき、その直線がまたポリゴンの内部に存在する場合に凸であるという。

三角形の3頂点は、常に平面を表すが、もう1つの頂点を追加することによって、非平面のポリゴンを作成することは簡単である。

面法線と頂点法線

メッシュ中の各面には、垂直面の法線ベクトルがある。法線ベクトル の方向は、頂点が定義されている順序と座標系が、左手座標系か右手座標系かによって決定される。面の法線ベクトルが見る者の方向に向かっている場合には、その側の面が前になる。Direct3Dでは、面の前側だけが可視であり、前面は、その中で頂点が時計回りに定義されるものになる。

Direct3Dアプリケーションは面法線を指定する必要はない。必要なときはシステムが面法線を自動的に計算する。システムは、フラットシェーディングモードでは面法線を、グーローシェーディングモードでは頂点法線を使用する。また、Direct3Dは照明効果とテクスチャ効果の制御にも頂点法線を使用する。

シェーディングモード

フラットシェーディングモードでは、システムは、1つの頂点の色をプリミティブの他の面のすべてに再現する。グーローとフォンシェーディングモードでは、頂点法線は、ポリゴンオブジェクトが円滑に見えるようにするために使用する。グーローシェーディングでは、隣接の頂点の色と輝度は、頂点を隔てている空間に渡って補間される。フォンシェーディングでは、システムが面上の各ピクセルに対する適切なシェーディング値を算出する。

注 フォンシェーディングは、現在サポートされていない。

アプリケーションは、普通、オブジェクトを滑らかに見せ、また計算も効率的であるので、グーローシェーディングを使用する。ただし、グーローシェーディングは、フォンシェーディングが見逃さない細部を見逃す場合がある。この例として挙げたのが次の図である。ここでは、スポットライトがポリゴンの表面に完全に吸収されてしまっている。

この場合、フォンシェーディングモードは、各ピクセルに対する値を計算し、スポットライトを表示する。グーローシェーディングモードは、頂点の間を補間するので、スポットライトはすべて省略され、あたかもスポットライトが存在しないかのように面がレンダリングされる。

フラットシェーディングモードでは、次のピラミッドは隣接する面の間に鋭いエッジがあるように表示される。システムは、自動的に面法線を生成する。しかし、グーローまたはフォンシェーディングモードでは、シェーディング値がエッジ全体に補間され、最終的に曲面のサーフェスが表示される。

グーローまたはフォンシェーディングモードを使用して曲面を表示し、また、鋭いエッジを持つ複数のオブジェクトを含めたい場合、ユーザのアプリケーションでは、次の図で示すように鋭いエッジを必要とする面の任意の交わりで頂点法線を再現する必要がある。

単一のオブジェクトに、曲面と平面の両方を持つようにするのに加えて、グーローシェーディングモードは、平坦なサーフェスを、フラットシェーディングモードよりも現実感のあるように光で照らす。フラットシェーディングモードでのサーフェスは一様な色であるが、グーローシェーディングモードでは、光が面全般に正しく当たるようにできる。この効果は近くに点ソースがある場合に、特に目に付くことになる。グーローシェーディングモードは、多くのDirect3Dアプリケーションが求めるシェーディングモードである。

三角形補間要素

システムは、面をレンダリングするとき三角形全体で三角形の頂点の特性を補間する。三角形補間要素は次のとおりである。

  • 色
  • 反射色
  • フォグ
  • アルファ

これらの三角形補間要素はすべて、現在のシェーディングモードによって変わる。

フラット | 補間は行われない。その代わり、三角形の最初の頂点の色が面全体に適用される。
グーロー | 線形補間が3つの頂点すべての間で実行される。
フォン | 頂点パラメータが、現在の照明を使用して、面の各ピクセルに対して再計算される。フォンシェーディングモードは、現在サポートされていない。

色補間要素と反射色補間要素の処理は色モデルによって異なる。RGB色モデル（D3DCOLOR_RGB）では、システムは赤色、緑色、および青色成分を使って補間を行う。モノクロモデル（D3DCOLOR_MONO）では、システムは頂点色の青色成分のみ使用する。

たとえば、頂点1の色の赤成分が0.8、頂点2の赤成分が0.4であるとすると、グーローシェーディングモードとRGB色モデルでは、システムは補間を使用して、それらの頂点の線分の中点にあるピクセルに赤成分の0.6を割り当てる。

色のアルファ成分は、別個の補間要素として処理される。デバイスドライバが透明性を、テクスチャブレンディングまたは点描による2とおりの方法で実装できるからである。

アプリケーションは、D3DPRIMCAPS構造体のdwShadeCapsメンバを使用して、現在のデバイスドライバがサポートする補間の形式を確認することができる。

三角形の展開図と扇形

各三角形の3頂点すべてを指定することなく、三角形展開図と三角形扇形を使用して全面を指定することができる。たとえば、以下の三角形の展開図を定義するには、7つの頂点しか必要としない。

システムが、頂点のv1、v2、v3を使用して最初の三角形を、v2、v4、v3を使用して2番目の三角形を、v3、v4、v5を使用して3番目の三角形を、v4、v6、v5を使用して4番目の三角形を、という手順で描画していく。2番目と4番目の三角形の頂点が順序通りでないことに注意する。これは、すべての三角形が時計回りの方向に描画することを保証するために必要となる。

三角形扇形は、すべての三角形が1つの頂点を共有する点を除けば、三角形展開図に類似している。

システムは、頂点v1、v2、v3を使用して最初の三角形を、v3、v4、v1を使用して2番目の三角形を、v1、v4、v5を使用して3番目の三角形を、という手順で描画していく。

D3DTRIANGLE構造体のwFlagsメンバを使用して、三角形展開図と扇形を作成するフラグを指定することができる。

ベクトル、頂点、および4元数

Direct3D全体を通じて、頂点は位置と方向を表す。プリミティブ中の各頂点は、その位置を与えるベクトルと、その方向を与える法線ベクトル、テクスチャ座標、および色によって記述される(保持モードでは、D3DRMVERTEX構造体が以上の値を格納する)。

4元数は、ベクトルを定義する [x, y, z] 値に4番目の要素を追加する。4元数は、3D回転に使用される行列メソッドに代わるものである。4元数は、3D空間での軸とその軸を中心とする回転を表す。たとえば、4元数は、(1,1,2)軸と1ラジアンの回転を表すこともできる。4元数は、重要な情報を伝えるが、その本当の威力は、それに対して実行できる2つの操作の合成と補間にある。

4元数に合成を実行するのは、結合することと類似している。2つの4元数の合成は、以下のように表される。

図形に適用される2つの4元数の合成は、「軸2の回りに回転2で図形を回転させた後、軸1の回りに回転1で回転させる」ことを意味する。この場合、Qが単一の軸の回りの回転を表し、その結果がq2に適用された後、q1が図形に適用される。

4元数補間を使用すると、アプリケーションは、1つの軸と方向から別の軸と方向へ、滑らかで合理性のあるパスを算出することができる。したがって、q1とq2の間の補間は、1つの方向から別の方向へアニメーションを動かす簡単な方法を提供する。

合成と補間を同時に使用すると、複雑に見えるが、実は単純な方法で図形を処理することができる。たとえば、指定の方向に回転させたい図形があるものと仮定する。軸2を中心にr2度回転させた後、軸1を中心にr1度回転させたいことまではわかっているが、最終的な4元数はわからない。合成を使用して、図形上の2つの回転を合成し、結果として単一の4元数を得ることができる。その後、元の4元数から合成された4元数まで補間して、一方から他方への滑らかな移行を実現する。

Direct3D保持モードには、4元数を使用する上で、ユーザの助けになる関数がいくつか含まれている。たとえば、D3DRMQuaternionFromRotation関数は、回転値を回転軸を定義するベクトルに追加し、結果をD3DRMQUATERNION構造体が定義する4元数に返す。また、D3DRMQuaternionMultiply関数は、4元数を合成して、D3DRMQuaternionSlerpは、2つの4元数間で球面線形補間を実行する。

保持モードアプリケーションは、以下の関数を使用してベクトルと4元数を使用する作業を簡単にすることができる。

  • D3DRMQuaternionFromRotation
  • D3DRMQuaternionMultiply
  • D3DRMQuaternionSlerp
  • D3DRMVectorAdd
  • D3DRMVectorCrossProduct
  • D3DRMVectorDotProduct
  • D3DRMVectorModulus
  • D3DRMVectorNormalize
  • D3DRMVectorRandom
  • D3DRMVectorReflect
  • D3DRMVectorRotate
  • D3DRMVectorScale
  • D3DRMVectorSubtract

Zバッファとオーバーレイ

Zバッファの順序は、オーバーレイが互いにクリッピングするその順序を決める。オーバーレイは、他のすべてのスクリーンコンポーネントの先頭にくるものと仮定されている。指定 Zオーダーを持たないオーバーレイは、プライマリサーフェスの同じ領域でオーバーレイを行うときに予測できない動作をする。Zバッファがないと、Direct3D保持モードはオーバーレイをソートしない。指定 Zオーダーを持たないオーバーレイはZオーダー0を持つものとされ、レンダリングする順序で現れる。オーバーレイのZオーダーの可能な範囲は、プライマリサーフェスのすぐ上である0から、見る人にできる限り近い40億までである。Zオーダー2のオーバーレイは、Zオーダー1のオーバーレイを覆い隠す。どのオーバーレイも、他のオーバーレイと同一のZオーダーを持つことはできない。


アーキテクチャ

この節では、Microsoft® Direct3D® 保持モードオブジェクトおよびCOMアーキテクチャについて解説する。次の項目について説明する。

  • 「Direct3D保持モードオブジェクト」では、Direct3D保持モードオブジェクトについて簡単に説明する。
  • 「オブジェクトとインターフェイス」では、各オブジェクトがサポートするインターフェイス、および、単一オブジェクトと配列オブジェクトの両方に、インターフェイスを作成するための情報を列挙している。
  • 「オブジェクトと参照カウント」では、Direct3D保持モードの参照カウントに関するヒントを与える。

Direct3D保持モードオブジェクト

Direct3D保持モードへのアクセスは、わずかな数のオブジェクトを通して行われる。以下の表にこれらのオブジェクトをリストアップし、それぞれについて簡単に説明する。

オブジェクト | 説明
Direct3DRMAnimation2 | 多くの場合、Direct3DRMFrame3オブジェクトに関連して、変換をいかに変更するかを定義する。 したがって、このオブジェクトを使用してDirect3DRMVisual、Direct3DRMLightおよびDirect3DRMViewport2オブジェクトの位置、方向およびスケールのアニメーションを行うことができる。Direct3DRMAnimationオブジェクトと同じだが、アニメーションのキーとフレームにアクセスできる。
Direct3DRMAnimationArray | 配列のアニメーション数、および要求したアニメーションへのインターフェイスを取得する。
Direct3DRMAnimationSet2 | Direct3DRMAnimation2オブジェクトをグループ化する。Direct3DRMAnimationSetオブジェクトと同じだが、構成要素アニメーションにアクセスできる。
Direct3DRMClippedVisual | レンダリング前に、ビジュアルを任意のプレーンにクリッピングできる。
Direct3DRMDevice3 | レンダラのビジュアル表示先を表す。Direct3DRMDevice2オブジェクトを拡張して、ユーザによるマテリアルの設定と取得を可能にした。Direct3DRMDevice2はDirect3DRMDeviceオブジェクトと同じ機能を持つが、透明度の制御が拡張されている。
Direct3DRMFace2 | メッシュ上の1つのポリゴンを表す。
Direct3DRMFrame3 | シーンにオブジェクトを配置し、ビジュアルオブジェクトの位置や向きを定義する。フレーム軸、境界ボックス、およびマテリアルに対するアクセスを有効にすることによって、Direct3DRMFrameオブジェクトを拡張する。光線ピックもサポートする。Direct3DRMFrame2オブジェクトを拡張して、変換、トラバーサル、フォグ処理の機能を追加した。
Direct3DRMInterpolator | アクションを格納し、中間値を自動計算してオブジェクトにそのアクションを適用する。
Direct3DRMLight | 5種類の照明の1つを定義し、シーンのビジュアルオブジェクトを彩色するために用いられる。
Direct3DRMMaterial2 | サーフェスの反射特性を定義する。Direct3DRMMaterialオブジェクトと同じだが、マテリアルのプロパティを、より細かく調整できる。
Direct3DRMMesh | ポリゴンの面のセットを含む。面や頂点のグループを操作するために使うことができる。
Direct3DRMMeshBuilder3 | メッシュにある個々の頂点や面を操作することができる。Direct3DRMMeshBuilderオブジェクトを拡張して、法線に対する制御を強化し、メッシュの面を取得可能にした。Direct3DRMMeshBuilder2オブジェクトを拡張して、IDirect3DRM3インターフェイスによる作成時に、直接モードのDrawPrimitiveインターフェイスを使用するようにした。
Direct3DRMObject | Direct3Dの他のすべての保持モードオブジェクトによって基本クラスとして用いられる。すべてのオブジェクトに共通な特徴を保持している。
Direct3DRMObject2 | Direct3Dの他のすべての保持モードオブジェクトによって基本クラスとして用いられる。すべてのオブジェクトに共通な特徴を保持している。Direct3DRMObjectを拡張して、オブジェクトにデータを、より柔軟に関連付けられるようにした。
Direct3DRMPickedArray | 与えられた2Dの点に対応するビジュアルオブジェクトを識別する。
Direct3DRMPicked2Array | 与えられた光線の交線に対応するビジュアルオブジェクトを識別する。
Direct3DRMProgressiveMesh | “メッシュを段階的に詳細なものにする方法を記述するレコード”と“粗いベースメッシュ”で構成される。これは、一般的なレベルの詳細項目をメッシュ上でセットするとともに、リモートソースからのメッシュを段階的にダウンロードすることも可能にする。
Direct3DRMShadow2 | 影を定義する。Direct3DRMShadowオブジェクトと同じだが、影のプロパティを設定したり、作成後に取得することができる。
Direct3DRMTexture3 | 色の付いたピクセルが矩形に並んで構成される。Direct3DRMTextureオブジェクトと同じであるが、現在実行しているファイル以外のファイルからリソースをロードでき、テクスチャはメモリのイメージから作成でき、またミップマップを生成できる点が異なる。Direct3DRMTexture2オブジェクトを拡張して、テクスチャ管理を詳細に行えるようにした。
Direct3DRMUserVisual | システムが提供しない機能を実現する。アプリケーションによって定義される。
Direct3DRMViewport2 | 3Dシーンがどのように2Dウィンドウにレンダリングされるかを定義する。Direct3DRMViewportオブジェクトと同じだが、クリアする対象を指定できる。
Direct3DRMVisual | シーンにレンダリングすることができる。ビジュアルオブジェクトは可視状態でなくてもよい。たとえば、フレームをビジュアルオブジェクトとして追加することもできる。
Direct3DRMWrap | 面やメッシュのテクスチャ座標を計算する。

多くのオブジェクトは、配列オブジェクトと呼ばれる配列にグループ化することができる。配列オブジェクトによって、グループ全体に操作を適用することが容易になる。配列オブジェクトを使うことができるCOM（Component Object Model）インターフェイスには、GetElementとGetSizeメソッドが含まれている。これらのメソッドは、配列要素へのポインタと配列のサイズを受け取る。配列インターフェイスの詳細については、「インターフェイスリファレンス」を参照すること。

オブジェクトとインターフェイス

IObjectName::QueryInterfaceは、オブジェクトがそのインターフェイスをサポートしている場合のみ、有効なインターフェイスへのポインタを取得する。したがって、IDirect3DRMDevice3::QueryInterfaceを使ってIDirect3DRMWinDeviceインターフェイスを受け取ることはできるが、IDirect3DRMVisualインターフェイスを受け取ることはできない。

オブジェクト名 | サポートされるインターフェイス
Direct3DRMAnimation2 | IDirect3DRMAnimation2
Direct3DRMAnimationSet2 | IDirect3DRMAnimationSet2
Direct3DRMClippedVisual | IDirect3DRMClippedVisual, IDirect3DRMVisual
Direct3DRMDevice3 | IDirect3DRMDevice3, IDirect3DRMWinDevice
Direct3DRMFace2 | IDirect3DRMFace2
Direct3DRMFrame3 | IDirect3DRMFrame3, IDirect3DRMVisual
Direct3DRMInterpolator | IDirect3DRInterpolator
Direct3DRMLight | IDirect3DRMLight
Direct3DRMMaterial2 | IDirect3DRMMaterial2
Direct3DRMMesh | IDirect3DRMMesh, IDirect3DRMVisual
Direct3DRMMeshBuilder3 | IDirect3DRMMeshBuilder3, IDirect3DRMVisual
Direct3DRMProgressiveMesh | IDirect3DRMProgressiveMesh, IDirect3DRMVisual
Direct3DRMShadow2 | IDirect3DRMShadow2, IDirect3DRMVisual
Direct3DRMTexture3 | IDirect3DRMTexture3, IDirect3DRMVisual
Direct3DRMUserVisual | IDirect3DRMUserVisual, IDirect3DRMVisual
Direct3DRMViewport2 | IDirect3DRMViewport2
Direct3DRMWrap | IDirect3DRMWrap

次のサンプルでは、1つのDirect3DRMDevice3オブジェクトに2つのインターフェイスを生成する方法を説明している。IDirect3DRM3::CreateObjectメソッドは、初期化されていないDirect3DRMDevice3オブジェクトを生成する。オブジェクトの初期化は、IDirect3DRMDevice3::InitFromClipperメソッドによって行われる。IDirect3DRMDevice3::QueryInterfaceメソッドの呼び出しは、Direct3DRMDevice3オブジェクトへの2つめのインターフェイス（WM_PAINTおよびWM_ACTIVATEメッセージへの応答時に用いられるIDirect3DRMWinDeviceインターフェイス）を生成する。

d3drmapi->CreateObject(CLSID_CDirect3DRMDevice, NULL,
    IID_IDirect3DRMDevice3,(LPVOID FAR*)&dev1);
dev1->InitFromClipper(lpDDClipper, IID_IDirect3DRMDevice3,
    r.right, r.bottom);
dev1->QueryInterface(IID_IDirect3DRMWinDevice, (LPVOID*) &dev2);

2つのインターフェイスが同一のオブジェクトを参照しているかどうかを判定するには、それぞれのインターフェイスについてQueryInterfaceメソッドを使って、返されるポインタの値を比較する。ポインタの値が等しい場合、インターフェイスは同じオブジェクトを参照している。

すべてのDirect3D保持モードオブジェクトは、前述したリスト中のインターフェイスに加え、IDirect3DRMObjectインターフェイスとIDirect3DRMObject2インターフェイス、IUnknownインターフェイスをサポートしている。IDirect3DRMObjectは配列オブジェクトを提供しない。配列オブジェクトは、必要がないため、クラス識別子（CLSID）を持っていない。IDirect3DRM3::CreateObjectメソッドの呼び出しでは、配列オブジェクトを作成することはできない。その代わり、各インターフェイスについて以下の生成メソッドを使用する。

配列インターフェイス | 生成メソッド
IDirect3DRMAnimationArray | IDirect3DRMAnimationSet2::GetAnimations
IDirect3DRMDeviceArray | IDirect3DRM3::GetDevices
IDirect3DRMFaceArray | IDirect3DRMMeshBuilder3::GetFaces
IDirect3DRMFrameArray | IDirect3DRMPickedArray::GetPick, IDirect3DRMPicked2Array::GetPickまたはIDirect3DRMFrame3::GetChildren
IDirect3DRMLightArray | IDirect3DRMFrame3::GetLights
IDirect3DRMObjectArray | IDirect3DRMInterpolator::GetAttachedObjects
IDirect3DRMPickedArray | IDirect3DRMViewport2::Pick
IDirect3DRMPicked2Array | IDirect3DRMFrame3::RayPick
IDirect3DRMViewportArray | IDirect3DRM3::CreateFrame
IDirect3DRMVisualArray | IDirect3DRMFrame3::GetVisuals

オブジェクトと参照カウント

オブジェクトが生成されると、その参照カウントがインクリメントされる。アプリケーションがオブジェクトの子を作成したり、メソッドがオブジェクトへのポインタを返したりするたびに、システムはそのオブジェクトの参照カウントを増加させる。オブジェクトは、参照カウントが0になるまで削除されることはない。オブジェクトに対する操作が完了したら、Releaseメソッドを呼び出して、参照カウントを必ずデクリメントする。たとえば、IDirect3DRM3::CreateMeshBuilderを呼び出してIDirect3DRMMeshBuilder3オブジェクトを作成し、IDirect3DRMMeshBuilder3::GetFacesを呼び出してIDirect3DRMFaceArrayオブジェクトを取得したとする。この場合、アプリケーションを終了する前に、IDirect3DRMMeshBuilder3オブジェクトのReleaseメソッドを呼び出し、IDirect3DRMFaceArrayオブジェクトのReleaseメソッドも呼び出す。Releaseメソッドを呼び出さないと、オブジェクトは適切に解放されず、リソースが浪費される。オブジェクトを解放するサンプルについては、Direct3D保持モードのサンプルコードを参照すること。

Direct3D保持モードには、内部参照カウントと外部参照カウントがある。テクスチャなどのオブジェクトを作成またはインポートし、フレームやメッシュなどのシーンにオブジェクトを適用すると、作成またはインポートしたオブジェクトのインターフェイスのコピーは解放できる。オブジェクトを使用するシーンが完了すると、そのオブジェクトはD3DRMによって自動的に解放される。たとえば、メッシュビルダオブジェクトを作成すると、参照カウントは1にセットされる。次に、オブジェクトをフレームに追加すると、参照カウントは2にセットされる。その後、メッシュビルダオブジェクトへのポインタのコピーを解放すると、メッシュビルダオブジェクトの参照カウントは1に戻される。さらに、そのフレームを含むシーンを解放すると、メッシュビルダオブジェクトの参照カウントはデクリメントされて0になり、オブジェクトが解放される。もう1つ例を示す。テクスチャをインポートすると、テクスチャオブジェクトの参照カウントは1にセットされる。テクスチャをメッシュに適用すると、参照カウントは2になる。テクスチャオブジェクトへのポインタのコピーを解放すると、参照カウントは1に戻る。メッシュを解放すると、テクスチャオブジェクトの参照カウントはデクリメントされて解放される。

シーンに適用した後でオブジェクトを解放したら、アプリケーションは参照カウントを追跡する必要はなく、シーンのルートだけ追跡すればよい。保持モードは他の参照カウントを自動的に追跡する。この場合、クリーンアップが完了してアプリケーションを終了する前に、アプリケーションは、シーン、ビューポート、デバイスを解放するだけでよい。アプリケーションがビューポートを解放すると、システムはカメラの参照カウントを自動的に調整する。

子オブジェクトやビジュアルオブジェクトの参照カウントは、フレームに追加されるときに増やされる。IDirect3DRMFrame3::AddChildメソッドを使用して、ある親オブジェクトから別の親に子オブジェクトを移動すると、システムは自動的に参照カウントを操作する。

アプリケーションがビジュアルオブジェクトをシーンにロードした後は、シーンがオブジェクトの参照カウントを管理する。アプリケーションにとっては、ビジュアルオブジェクトはもう不要となり、解放することができる。

ラップの作成と適用は、どのオブジェクトの参照カウントも増加させない。ラッピングは、単にテクスチャの座標を計算するだけの便利なメソッドにすぎないためである。


概要

この節では、Microsoft® Direct3D® 保持モードをさまざまな観点から解説する。最初の2つのトピックでは、Direct3D保持モードインターフェイスに関する一般情報を提供する。この中には、階層図、およびインターフェイスの履歴とバージョン間の違いを詳述する資料が含まれる。

  • インターフェイス階層
  • インターフェイスの変更点

次に、Direct3D保持モードを特定の観点から説明する。各インターフェイスのメソッドについては、対応する「リファレンス」を参照すること。

  • 冗長な状態変更の削除
  • フレーム
  • インターポレータ
  • 照明
  • 出力デバイス
  • テクスチャ
  • ビューポート
  • ラップ

Direct3D保持モードバージョン6では、外部ビジュアルのサポートが追加された。外部ビジュアルは、Direct3D保持モード (D3DRM) の階層でカスタムヒエラルキーオブジェクトを許可するメソッドを提供する。外部ビジュアルは、COMオブジェクトであり、IDirect3DRMExternalVisualインターフェイス (および、必要に応じた他のインターフェイス) をサポートする。D3DRMは、このオブジェクトをファーストクラスビジュアルオブジェクトとして扱い、カスタムレンダリング、ピッキング、バウンディングボックスレポートなどの動作を許可する。D3DRMの旧バージョンでサポートされていたユーザビジュアルは、コールバック関数を使用したカスタムレンダリングしか認めていなかったが、それに比べると外部ビジュアルは一段と強化されている。外部ビジュアルは、変形可能なメッシュやインバースキネマティックソルバなど、あらゆるタイプのビジュアルオブジェクトをD3DRM ビジュアル階層に挿入する拡張機能を提供する。

外部ビジュアルにはD3DRMからアクセスすることもできるが、外部ビジュアルはDirectX変換インターフェイスをサポートしているので、DirectX Transform DXETool.exeでも使用できる。理由は、DirectX Media SDKの「DirectX Transform」で説明する。外部ビジュアルの詳細については、DirectX Media SDKの「DirectX Transform」マニュアルの「リファレンス」を参照すること。


インターフェイス階層

 IUnknown
 |
 +--IDirect3DRM (差し替え)
 |
 +--IDirect3DRM2 (差し替え)
 |
 +--IDirect3DRM3
 |
 +--IDirect3DRMArray
 |  |
 |  +--IDirect3DRMAnimationArray
 |  |
 |  +--IDirect3DRMDeviceArray
 |  |
 |  +--IDirect3DRMFaceArray
 |  |
 |  +--IDirect3DRMFrameArray
 |  |
 |  +--IDirect3DRMLightArray
 |  |
 |  +--IDirect3DRMObjectArray
 |  |
 |  +--IDirect3DRMPicked2Array
 |  |
 |  +--IDirect3DRMPickedArray
 |  |
 |  +--IDirect3DRMViewportArray
 |  |
 |  +--IDirect3DRMVisualArray
 |
 +--IDirect3DRMObject
 |  |
 |  +--IDirect3DRMAnimation (差し替え)
 |  |
 |  +--IDirect3DRMAnimation2
 |  |
 |  +--IDirect3DRMAnimationSet (差し替え)
 |  |
 |  +--IDirect3DRMAnimationSet2
 |  |
 |  +--IDirect3DRMDevice (差し替え)
 |  |  |
 |  |  +--IDirect3DRMDevice2 (差し替え)
 |  |
 |  +--IDirect3DRMDevice3
 |  |
 |  +--IDirect3DRMFace2
 |  |
 |  +--IDirect3DRMInterpolator
 |  |
 |  +--IDirect3DRMLight
 |  |
 |  +--IDirect3DRMMaterial (差し替え)
 |  |
 |  +--IDirect3DRMMaterial2
 |  |
 |  +--IDirect3DRMViewport (差し替え)
 |  |
 |  +--IDirect3DRMViewport2
 |  |
 |  +--IDirect3DRMVisual
 |  |  |
 |  |  +--IDirect3DRMFrame (差し替え)
 |  |  |  |
 |  |  |  +--IDirect3DRMFrame2 (差し替え)
 |  |  |
 |  |  +--IDirect3DRMFrame3
 |  |  |
 |  |  +--IDirect3DRMMesh
 |  |  |
 |  |  +--IDirect3DRMMeshBuilder (差し替え)
 |  |  |  |
 |  |  |  +--IDirect3DRMMeshBuilder2 (差し替え)
 |  |  |
 |  |  +--IDirect3DRMMeshBuilder3
 |  |  |
 |  |  +--IDirect3DRMProgressiveMesh
 |  |  |
 |  |  +--IDirect3DRMShadow (差し替え)
 |  |  |
 |  |  +--IDirect3DRMShadow2
 |  |  |
 |  |  +--IDirect3DRMTexture (差し替え)
 |  |  |  |
 |  |  |  +--IDirect3DRMTexture2 (差し替え)
 |  |  |
 |  |  +--IDirect3DRMTexture3
 |  |  |
 |  |  +--IDirect3DRMUserVisual
 |  |
 |  +--IDirect3DRMWinDevice
 |  |
 |  +--IDirect3DRMWrap
 |
 +--IDirect3DRMObject2


インターフェイスの変更点

この項では、Microsoft® Direct3D® 保持モードインターフェイスの履歴と変更について説明する。連番が付いているインターフェイスの命名規則について説明し、旧バージョンおよび置き換えられたインターフェイスのリストを示す。さらに、新しいインターフェイスで追加されたメソッド、および従来からのインターフェイスにおいて追加されたメソッドのリストも示す。

この項では次の項目について説明する。

  • 連番付きのインターフェイスとメソッド
  • 新しいインターフェイスおよび置き換えられたインターフェイス
  • 追加および変更されたメソッド

連番付きのインターフェイスとメソッド

Direct3D保持モードのような COM (コンポーネントオブジェクトモデル) システムでは、新しいメソッドと機能は、連番を付けた新しいインターフェイスによって提供される。たとえば、IDirect3DRMFrame3インターフェイスは、IDirect3DRMFrame2で開示されたものにメソッドを追加し、IDirect3DRMFrame2はIDirect3DRMFrameで開示されたものにメソッドを追加する。

DirectX 6.0から、新しいDirect3D保持モードインターフェイスは、旧バージョンのインターフェイスから継承されなくなった。たとえば、DirectX 5.0で導入されたIDirect3DRMFrame2は、IDirect3DRMFrame から直接継承されるが、DirectX 6.0で導入されたIDirect3DRMFrame3は、IDirect3DRMFrame2 や IDirect3DRMFrame から継承されない。すべてのDirect3D保持モードインターフェイスの関係を示す図は、「インターフェイス階層」を参照すること。

DirectX 6.0から、新しいDirect3D保持モードインターフェイスは、最新のインターフェイスオブジェクトへのポイントなど、入力パラメータとして最新バージョンを要求する。旧バージョンのインターフェイスは変更していないため、既存のアプリケーションを書き直す必要はない。たとえば、IDirect3DRMFrame3は、IDirect3DRMFrame2とIDirect3DRMFrameの全機能を提供している。IDirect3DRMFrame3::AddChildは、IDirect3DRMFrame3インターフェイスへのポインタをパラメータとして受け取る。一方、旧バージョンのインターフェイスのメソッドは、パラメータとしてIDirect3DRMFrameの基本インターフェイスへのポインタを受け取る。DirectX 6.0で導入されたインターフェイスのリストは、この項の「新しいインターフェイスおよび置き換えられたインターフェイス」を参照すること。

Direct3D保持モードライブラリとランタイムには、旧バージョンとの互換性を保つために、古いインターフェイスが変更されずに含まれている。しかし、このマニュアルでは説明が冗長にならないように、最新のインターフェイスとメソッドだけを説明する。この項では、変更について広く説明する。個々のインターフェイスとメソッドに関する説明では、バージョン間の変更点について、やや限定的に説明する。旧バージョンのインターフェイスを使用しても、新しいアプリケーションを作成することはできるが、新しいインターフェイスを使用して、強化された機能を活用することを推奨する。

DirectX 6.0以前では、新しいDirect3D保持モードメソッドは、入力パラメータとして常に基本インターフェイスオブジェクトを受け取っていた。新しいメソッドは、出力パラメータとして、新しいインターフェイスかオブジェクトを返す。あるメソッドのパラメータが変更された場合、変更されたメソッドの名前は連番が付けられて (たとえば、名前に"2"を付けて)、新しいインターフェイスに追加される。たとえば、IDirect3DRMFrame::AddMoveCallbackには2つのパラメータがある。機能を拡張するために、パラメータを追加した新しいバージョンのメソッドは、IDirect3DRMFrame2::AddMoveCallback2のように、連番を付けた新しいインターフェイスで開示された。しかし、DirectX 6.0からは、新しいインターフェイスは古いインターフェイスを継承しないため、変更したメソッドの名前に番号を付加する方法は不必要になった。そのため DirectX 6.0以降では、DirectX 5.0で"2"を付けた Direct3D保持モードメソッドの名前から、"2"が削除されている。IDirect3DRMFrame2::AddMoveCallback2はIDirect3DRMFrame3::AddMoveCallbackに、IDirect3DRMMeshBuilder2::GenerateNormals2はIDirect3DRMMeshBuilder3::GenerateNormalsに置き換えられている。

新しいインターフェイスおよび置き換えられたインターフェイス

次のリストは、Microsoft DirectX® Software Development Kit (SDK) バージョン6で新たに導入されたインターフェイスを示している。新しいインターフェイスと置き換えられた古いインターフェイスも示している。
古いインターフェイス | 新しいインターフェイス
なし | IDirect3DRMClippedVisual
なし | IDirect3DRMAnimationArray
なし | IDirect3DRMObject2
IDirect3DRM | IDirect3DRM3
IDirect3DRM2 | IDirect3DRM3
IDirect3DRMAnimation | IDirect3DRMAnimation2
IDirect3DRMAnimationSet | IDirect3DRMAnimationSet2
IDirect3DRMDevice | IDirect3DRMDevice3
IDirect3DRMDevice2 | IDirect3DRMDevice3
IDirect3DRMFrame | IDirect3DRMFrame3
IDirect3DRMFrame2 | IDirect3DRMFrame3
IDirect3DRMMaterial | IDirect3DRMMaterial2
IDirect3DRMMeshBuilder | IDirect3DRMMeshBuilder3
IDirect3DRMMeshBuilder2 | IDirect3DRMMeshBuilder3
IDirect3DRMShadow | IDirect3DRMShadow2
IDirect3DRMTexture | IDirect3DRMTexture3
IDirect3DRMTexture2 | IDirect3DRMTexture3
IDirect3DRMViewport | IDirect3DRMViewport2

追加および変更されたメソッド

以下のリストは、メソッドとインターフェイスが追加または変更されたメソッドとバージョンを列記して、Direct3D保持モードの履歴を示している。3つ以上のバージョンが存在する場合 (IDirect3DRM3、IDirect3DRM2、IDirect3DRMなど) は、最初を除くすべてのバージョンを掲載して、バージョン間の機能強化を示す。Direct3D保持モードが最初に開発されて以降、変更されていないインターフェイスは示してない。インターフェイスが導入されたときのDirectX SDKのバージョンは、インターフェイス名の横にカッコ書きで示す。

  • IDirect3DRM2 (DirectX 5.0。DirectX 6.0ではIDirect3DRM3に置き換え)
    • CreateProgressiveMesh
  • IDirect3DRM3 (DirectX 6.0)
    • CreateDeviceFromSurface
    • GetOptions
    • RegisterClient
    • SetOptions
    • UnregisterClient
  • IDirect3DRMAnimation2 (DirectX 6.0)
    • AddKey
    • DeleteKeyByID
    • GetFrame
    • GetKeys
    • ModifyKey
  • IDirect3DRMAnimationArray (DirectX 6.0)
    • GetElement
    • GetSize
  • IDirect3DRMAnimationSet2 (DirectX 6.0)
    • GetAnimations
  • IDirect3DRMClippedVisual (DirectX 6.0)
    • AddPlane
    • DeletePlane
    • GetPlane
    • GetPlaneIDs
    • Init
    • SetPlane
  • IDirect3DRMDevice2 (DirectX 5.0。DirectX 6.0ではIDirect3DRMDevice3に置き換え)
    • GetDirect3DDevice2
    • GetRenderMode
    • InitFromD3D2
    • InitFromSurface
    • SetRenderMode
  • IDirect3DRMDevice3 (DirectX 6.0)
    • FindPreferredTextureFormat
  • IDirect3DRMFrame2 (DirectX 5.0。DirectX 6.0ではIDirect3DRMFrame3に置き換え)
    • AddMoveCallback2 (IDirect3DRMFrame3::AddMoveCallbackに置き換え)
    • GetAxes
    • GetBox
    • GetBoxEnable
    • GetHierarchyBox
    • GetInheritAxes
    • GetMaterial
    • RayPick
    • Save
    • SetAxes
    • SetBox
    • SetBoxEnable
    • SetInheritAxes
    • SetMaterial
    • SetQuaternion
  • IDirect3DRMFrame3 (DirectX 6.0)
    • GetMaterialOverride
    • GetSceneFogMethod
    • GetTransform (IDirect3DRMFrame::GetTransformを拡張)
    • GetTraversalOptions
    • InverseTransformVectors
    • SetMaterialOverride
    • SetSceneFogMethod
    • SetTraversalOptions
    • TransformVectors
  • IDirect3DRMMaterial2 (DirectX 6.0)
    • GetAmbient
    • SetAmbient
  • IDirect3DRMMeshBuilder2 (DirectX 5.0。DirectX 6.0ではIDirect3DRMMeshBuilder3に置き換え)
    • GenerateNormals2 (IDirect3DRMMeshBuilder3::GenerateNormalsに置き換え)
    • GetFace
  • IDirect3DRMMeshBuilder3 (DirectX 6.0)
    • AddFacesIndexed
    • AddTriangles
    • CreateSubMesh
    • DeleteFace
    • DeleteNormals
    • DeleteSubMesh
    • DeleteVertices
    • Empty
    • Enable
    • GetEnable
    • GetNormal
    • GetGeometry (IDirect3DRMMeshBuilder::GetVerticesに置き換え)
    • GetNormalCount
    • GetNormals
    • GetParentMesh
    • GetSubMeshes
    • GetVertex
    • GetVertices (IDirect3DRMMeshBuilder::GetVerticesのGetGeometryを参照)
    • Optimize
    • SetNormals
    • SetVertices
  • IDirect3DRMObject2 (DirectX 6.0)

    このインターフェイスは、IDirect3DRMObjectの置き換えではないので注意すること。

    • AddDestroyCallback
    • Clone
    • DeleteDestroyCallback
    • GetAge
    • GetClientData
    • GetDirect3DRM
    • GetName
    • SetClientData
    • SetName
  • IDirect3DRMShadow2 (DirectX 6.0)
    • GetLight
    • GetOptions
    • GetPlane
    • GetVisual
    • SetLight
    • SetOptions
    • SetPlane
    • SetVisual
  • IDirect3DRMTexture2 (DirectX 5.0。DirectX 6.0ではIDirect3DRMTexture3に置き換え)
    • GenerateMIPMap
    • InitFromImage
    • InitFromResource2
  • IDirect3DRMTexture3 (DirectX 6.0)
    • Changed (IDirect3DRMTexture::Changedを拡張)
    • GetCacheOptions
    • GetSurface
    • SetCacheOptions
    • SetDownsampleCallback
    • SetValidationCallback
  • IDirect3DRMViewport2 (DirectX 6.0)
    • Clear (IDirect3DRMViewport::Clearを拡張)


冗長な状態変更の削除

旧バージョンのMicrosoft® Direct3D® 保持モードでは、ある呼び出しから次の呼び出しまでレンダリング状態と照明状態が変更されない可能性があることを考慮していなかった。この結果、保持モードは現在値と同じ値を設定するため、一般的なアプリケーションで冗長な状態変更が多数発生した。IDirect3DRMDevice3インターフェイスでは、パフォーマンスを向上させるため、こうした冗長な状態変更を解消するGetStateChangeOptions、LightStateChange、RenderStateChange、SetStateChangeOptionsメソッドが導入された。以上のメソッドを使用するには、以下の手順に従う。

  1. IDirect3DRMDevice3インターフェイスの2つのメソッドを使用して、冗長状態変更チェックをオンにする。これは、レンダリング状態や照明状態を変更する場合に、通知することを示す。
    Dev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER, 0,
                            D3DRMSTATECHANGE_NONVOLATILE);
Dev3->SetStateChangeOptions(D3DRMSTATECHANGE_LIGHT, 0, D3DRMSTATECHANGE_NONVOLATILE);
  2. 実行バッファまたはDraw Primitiveメソッドでレンダリング状態または照明状態を変更する場合、状態キャッシュを更新するために、Direct3D保持モードに変更を通知する必要がある。通知には2通りの方法がある。保持モードで状態を変更するか (冗長な変更は防止する)、状態を新しい値に変更したことを保持モードに通知する。どちらの場合もLightStateChangeおよびRenderStateChangeメソッドを使用する。

たとえば、次のコードは、テクスチャハンドルを変更して、状態キャッシュを更新する方法を示している。

Dev3->RenderStateChange(D3DRENDERSTATE_TEXTUREHANDLE, hTex, 0UL);

状態を変更して、保持モードに状態キャッシュを更新させるには、UPDATEONLYフラグを次のように使用する。

Dev3->RenderStateChange(D3DRENDERSTATE_TEXTUREHANDLE, hTex,
                        D3DRMSTATECHANGE_UPDATEONLY);

状態値を何度も変更するため、保持モードに現在値を追跡させたくない場合、次のコードに示すように、指定した状態に対する冗長状態チェックをオフに設定する。ただし、この方法はパフォーマンスが向上しないため推奨しない。

Dev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER, D3DRENDERSTATE_TEXTUREHANDLE,
                            D3DRMSTATECHANGE_VOLATILE);


フレーム

フレームという用語は、オブジェクトの物理フレームを参照していることに由来している。保持モードにおけるフレームの役割は、ウィンドウシステムにおけるウィンドウの役割に似ている。オブジェクトは、単にワールド空間に置かれるのではなく、関連する参照フレームとの空間的なリレーションシップ（相互関係）を記述することによってシーンに配置される。フレームはオブジェクトをシーンに配置する。また、ビジュアルオブジェクトを表示するときには、フレームから位置や向きを取得する。

保持モードのシーンは、親フレームを持たないフレームが定義する。すなわち、フレーム階層の最上位フレームが定義する。また、このフレームはルートフレームまたはマスタフレームと呼ばれることもある。シーンは、他のすべてのオブジェクトに対して参照フレームを定義する。シーンの作成は、IDirect3DRM3::CreateFrameメソッドを呼び出して、最初のパラメータをNULLに指定して行うことができる。

IDirect3DRMFrame3インターフェイスは、IDirect3DRMFrame2インターフェイスの拡張である。また、IDirect3DRMFrame2は、マテリアル、境界ボックス、およびフレーム付きの軸の使用を可能にするメソッドを備えている。IDirect3DRMFrame2は、光線ピックもサポートする。

IDirect3DRMFrame3::SetAxesおよびIDirect3DRMViewport2::SetProjectionメソッドで、D3DRMPROJECTIONTYPE構造体の右手投影タイプを使用して、右手投影を可能にできる。

関連情報については、「IDirect3DRMFrame3」を参照すること。

この項では、フレームとその使用法について説明する。

  • 階層
  • 変換
  • 運動（モーション）
  • コールバック関数

階層

シーンのフレームは階層構造になっている。フレームは親フレームや子フレームを持つことができる。親フレームを持たないフレームはルートフレームと呼ばれ、シーンを定義する。

子フレームは、親フレームに対して相対的な位置と向きを示している。親フレームが移動すると、子フレームも移動する。

フレームの位置や向きは、シーン上の他のフレームからの相対値で設定することができる。絶対位置を設定する必要がある場合は、ルートフレームからの相対値が使用できる。また、ある親フレームからフレームを削除し、IDirect3DRMFrame3::AddChildメソッドにより、いつでも他のフレームに追加することができる。子フレームを完全に削除するにはIDirect3DRMFrame3::DeleteChildメソッドを使用する。子フレームや親フレームを取得するには、IDirect3DRMFrame3::GetChildrenおよびIDirect3DRMFrame3::GetParentメソッドを使用する。

フレームは、他のフレームのビジュアルオブジェクトとして追加でき、与えられた階層構造を、シーン全体に渡って何度も利用することが可能になる。新しい階層はインスタンスと呼ばれる。パフォーマンスの低下を防ぐため、親フレームを子フレームに入れ込まないように注意が必要である。保持モードは、実行時に巡回階層のチェックを行わない。巡回階層の作成は、IDirect3DRMFrame3インターフェイスのメソッドではできず、フレームをビジュアルオブジェクトとして追加するときにのみ可能である。

変換

フレームの位置や向きは、親フレームへの相対的な線形変換と考えることもできる。この変換は親フレームから子フレームへの相対ベクトルを取得し、親フレームへの相対ベクトルを求める。

変換は4×4行列で表すことができ、座標は4要素の行ベクトル [x, y, z,1] で表すことができる。

子フレームにおける座標をvchildとすると、同じ座標を親フレームvparentで表す式は、次のように定義される。

Tchildは、子フレームの変換行列である。

子フレームからルートフレームまでのすべての親フレームの変換は、子フレームがワールド座標を生成する変換と結び付けられている。このワールド変換は、レンダリングの前に、子フレーム上のビジュアルオブジェクトに対して適用される。子フレームに対する相対座標は、モデル座標と呼ばれることがある。ワールド変換が行われた座標は、ワールド座標と呼ばれる。

フレームの変換は、IDirect3DRMFrame3::AddTransform、IDirect3DRMFrame3::AddScale、IDirect3DRMFrame3::AddRotation、IDirect3DRMFrame3::AddTranslationの各メソッドによって、直接変更することができる。それぞれのメソッドにはD3DRMCOMBINETYPE列挙型のメンバを渡し、どのようにアプリケーションが提供した行列を現在のフレームの行列と合成するかを指定する。

IDirect3DRMFrame3::GetRotationとIDirect3DRMFrame3::GetTransformメソッドは、フレームの回転軸と変換行列を取得する。フレームの回転を変更するには、IDirect3DRMFrame3::SetRotationメソッドを利用する。

ワールド座標とモデル座標を変換するには、IDirect3DRMFrame3::TransformとIDirect3DRMFrame3::InverseTransformメソッドを使用する。

変換のさらに一般的な説明は、ビューポートだけを取り扱った項「変換」にある。変換の数学の概要については、「3D変換」を参照すること。

運動（モーション）

各フレームは固有の回転や速度で動く。回転も移動もしないフレームでは、これらの属性は0である。これらの属性は、シーンをレンダリングしてオブジェクトを動かす前に使用され、単純なアニメーションを作成することもできる。

コールバック関数

フレームは、より複雑なアニメーションを実現するため、コールバック関数をサポートしている。アプリケーションが登録したコールバック関数は、モーション属性が適用される前にフレームから呼び出される。階層に複数のフレームがあり、それぞれがコールバック関数に関連付けられている場合は、子フレームの前に親フレームが呼び出される。このような階層では、コールバック関数のすべてが呼び出されるまで、レンダリングは実行されない。

コールバック関数を追加するには、IDirect3DRMFrame3::AddMoveCallbackメソッドを使用する。コールバック関数を削除するには、IDirect3DRMFrame3::DeleteMoveCallbackメソッドを使用する。

これらのコールバック関数を用いると、プログラム済みのアニメーションシーケンスに新しい位置や向きを設定したり、シーン上の他のオブジェクトの位置によってビジュアルオブジェクトの動作を動的にインプリメントすることができる。


インターポレータ

インターポレータは、アクションを格納した後、中間値を自動計算してオブジェクトにアクションを適用する方法を提供する。たとえば、ユーザは時間0で赤を、時間10で緑をシーンの背景色にセットすることができる。その後、インターポレータは自動的に、連続するシーンに色合いを付けて赤から緑に混合するようにできる。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、またほかのさまざまな変換も行うことができる。

Direct3D保持モード実装では、インターポレータは、ユーザがアニメートできるオブジェクトパラメータの種類を増加させるIDirect3DRMAnimation2インターフェイスの一般化である。IDirect3DRMAnimation2インターフェイスがオブジェクトの位置、サイズ、および方向のアニメーションを可能にする一方で、IDirect3DRMInterpolatorインターフェイスはさらに色、メッシュ、テクスチャ、およびマテリアルのアニメーションをイネーブルにする。

この項では、次の項目について説明する。

  • インターポレータキー
  • インターポレータタイプ
  • インターポレータの例
  • インターポレータがサポートするメソッド
  • インターポレータインデックススパン
  • 補間オプション

インターポレータキー

インターポレータが格納するアクションは、キーと呼ばれる。キーは、格納されたプロシージャ呼び出しで、それに関連したインデックスを持つ。インターポレータは、自動的に中間のキー値を計算する。

サポートされているインターポレート可能なインターフェイスメソッドの1つを呼び出して、キーをインターポレータの中に格納する。メソッドとメソッドに渡されるパラメータ値がキーを構成する。「インターポレータがサポートするメソッド」に、サポートされているメソッドの一覧がある。

インターポレータ内部に格納されている各キーには、インデックス値がある。キーが記録されるとき、キーには、現在のインターポレータインデックス値のスタンプが押される。このキーのインデックス値は、この値をいったん設定すると絶対に変ることはない。

インターポレータタイプ

オブジェクトは、関連タイプのインターポレータに接続することができる。たとえば、Meshは、MeshInterpolatorに接続できる。インターポレータには、以下のタイプがある。

  • FrameInterpolator
  • LightInterpolator
  • MaterialInterpolator
  • MeshInterpolator
  • TextureInterpolator
  • ViewportInterpolator

あるインターポレータを別のインターポレータに接続することも可能である。インターポレータのインデックスを変更すると、任意の接続する先のインターポレータのインデックスに同じ値をセットすることになる。

MeshInterpolatorsの場合、MeshInterpolatorオブジェクトのIDirect3DRMMeshインターフェイス上で、SetVerticesを呼び出すことによって、MeshInterpolatorオブジェクトにSetVerticesキーを追加することに注意する。SetVerticesで使用されるグループインデックスは、Meshオブジェクトまたはインターポレータが適用されるオブジェクト中の有効なグループインデックスに対応しなければならない。

インターポレータの例

例として、フレームの位置を補間したい場合を考える。この場合、2つのインターフェイスIDirect3DRMInterpolatorおよびIDirect3DRMFrame3を持つFrameInterpolatorオブジェクトが必要になる。

pd3drm->CreateObject(CLSID_CDirect3DRMFrameInterpolator, 0,

     IID_IDirect3DRMInterpolator, &pInterp);
pInterp->QueryInterface(IID_IDirect3DRMFrame3, &pFrameInterp);

位置キーをインターポレータに追加するには、IDirect3DRMInterpolator::SetIndexを呼び出してインターポレータの内部インデックスを設定し、IDirect3DRMFrame3インターフェイスのSetPositionメソッドを呼び出してその位置を記録する。このメソッドは、実際のフレームではなく、インターポレータに適用される。関数呼び出しとそのパラメータが、現在のインデックス付きの新しいキーとして格納される。

pInterp->SetIndex(keytime);
pFrameInterp->SetPosition(NULL, keypos.x, keypos.y, keypos.z);

1つまたは複数のオブジェクトのメソッドが、後に続くIDirect3DRMInterpolator::SetIndexを使用してインデックスを設定する処理を繰り返すことによって、複数のキーを追加することができる。実際のフレームを介して逆方向にアクションを再生するには、そのフレームをインターポレータに接続する。

pInterp->AttachObject(pRealFrame);

ここで、IDirect3DRMInterpolator::Interpolateを呼び出して、補間された位置を使用してpRealFrameの位置をセットする。

pInterp->Interpolate(time, NULL,

      D3DRMINTERPOLATIONSPLINE | D3DRMINTERPOLATION_OPEN);

インターポレータは、最も近いSetPositionキーどうしを（この場合、Bスプラインを使用して）補間して算出した位置を渡し、接続されているフレームのSetPositionメソッドを呼び出す。

または、直接形式のInterpolateを使用して、オブジェクトを2番目のパラメータとして渡すことができる。この操作は、接続されているオブジェクトのすべてに優先する。

pInterp->Interpolate(time, pRealFrame, D3DRMINTERPOLATIONSPLINE | D3DRMINTERPOLATION_OPEN);

同じインターポレータを使用して方向、スケール、速度、およびカラーキーなどの他のキーを格納することができる。各プロパティは、平行のタイムライン上に存在し、Interpolateの呼び出しは、各プロパティの補間された値を接続されているフレームに割り当てる。

複数のメソッドを補間することも可能である。たとえば、SetGroupColorおよびSetVerticesの各キーを同じインターポレータに格納することも可能である。異なるメソッドのキーどうしを補間することはできないので、キーチェインと呼ばれる並行実行スレッドに格納される。また、SetGroupColor(0, black)およびSetGroupColor(2, white)などの異なるグループから2つのキーを指定する場合は、キーが異なるグループに適用されるので、インターポレータがSetGroupColor(1, gray)の中間アクションを生成することは無意味である。この場合、キーは別個のチェインにも格納される。

インターポレータがサポートするメソッド

ビューポート

SetFront(value)
SetBack(value)
SetField(value)
SetPlane(left, right, bottom, top)

フレーム

SetPosition(reference*, x, y, z)
SetRotation(reference*, x, y, z, theta)
SetVelocity(reference*, x, y, z, withRotation*)
SetOrientation(reference*, dx, dy, dz, ux, uy, uz)
SetColor(color)
SetColorRGB(red, green, blue)
SetSceneBackground(color)
SetSceneBackgroundRGB(red, green, blue)
SetSceneFogColor(color)
SetSceneFogParams(start, end, density)
SetQuaternion(reference*, quat)

メッシュ

Translate(x, y, z)
SetVertices(group*, index*, count*, vertices)
SetGroupColor(group*, color)
SetGroupColorRGB(group*, red, green, blue)

ライト

SetColor(color)
SetColorRGB(red, green, blue)
SetRange(value)
SetUmbra(value)
SetPenumbra(value)
SetConstantAttenuation(value)
SetLinearAttenuation(value)
SetQuadraticAttenuation(value)

テクスチャ

SetDecalSize(width, height)
SetDecalOrigin(x, y)
SetDecalTransparentColor(color)

マテリアル

SetPower(value)
SetSpecular(red, green, blue)
SetEmissive(red, green, blue)

*は、このパラメータに対して異なる値のキーが別のチェインに挿入されることを示す。

サポートされていないキーを設定しようとすると、致命的ではないが、D3DRMERR_BADOBJECTエラーの原因となる。

インターポレータインデックススパン

インターポレータは、ある範囲のインデックス値を受け付ける。このインデックスの範囲は、以下の規則により指示される。

  • 範囲の始点は、すべてのキーインデックス値と現在のインデックスの中の最小値である。
  • 範囲の終点は、すべてのキーインデックス値と現在のインデックスの中の最大値である。

補間オプション

IDirect3DRMInterpolator::Interpolateのd3drmInterpFlagsパラメータに、次のオプションから1つ以上を指定して、補間を実行する。

  • D3DRMINTERPOLATION_CLOSED
  • D3DRMINTERPOLATION_LINEAR
  • D3DRMINTERPOLATION_NEAREST
  • D3DRMINTERPOLATION_OPEN
  • D3DRMINTERPOLATION_SLERPNORMALS
  • D3DRMINTERPOLATION_SPLINE
  • D3DRMINTERPOLATION_VERTEXCOLOR

インターポレータがCLOSEDで実行される場合、補間は循環的になる。キーは、実際には、インデックス範囲に等しい時間で永遠に繰り返される。アニメーションとの互換性をとるために、インデックス範囲の終点に等しいインデックスのキーは、すべて無視される。

補間がOPENの場合には、各キーチェインの最初と最後のキーがインデックス範囲外の補間値を修正する。

NEAREST、LINEAR、SPLINEオプションは、各キーチェインで補間がどのように行われるかを指定する。中間値はキーチェイン間の値から計算され、キーデータのポイントを滑らかに結合する。NEARESTが指定されると、一番近いキーの値が使用される。LINEARは、線形補間を2つの最も近いキーの間で行う。SPLINEは、Bスプライン混合関数を4つの最も近いキーに対して使用する。

次の2つのオプションは、IDirect3DRMMesh::SetVerticesの補間だけに影響する。

  • VERTEXCOLORは、頂点の色を補間するように指定する。
  • SLERPNORMALSは、頂点の法線が球面補間されるように指定する（現在未実装）。


照明

シーンをリアルに見せるためには、照明効果を利用する。システムは、シーンの照明に対するオブジェクトの向きに基づいて、すべてのオブジェクトを彩色する。オブジェクトの色は、レンダリング中に各照明の影響を考慮して決定される。すべての照明は色と輝度を持っており、別々に変化させることができる。

アプリケーションはフレームに光をアタッチし、シーンに照明を与えることができる。フレームにアタッチされた光は、シーン上のビジュアルオブジェクトを明るくする。フレームは、光の位置と向きの両方を提供する。言い換えれば、光はアタッチされたフレームの原点から広がっていく。アプリケーションは、照明がアタッチされたフレームを動かしたり回転することによって、照明の移動や方向転換を簡単に実現することができる。

各ビューポートは、1つまたは複数の照明を所有する。照明が、複数のビューポートによって所有されることはない。

現状では、保持モードは、アンビエント（環境光）、ディレクショナル、パラレルポイント、ポイント、スポットライトの5種類の照明を提供している。

IDirect3DRMLightインターフェイスのメソッドのリファレンスは、「IDirect3DRMLight」を参照すること。

このセクションでは、Direct3Dで利用することができる照明効果とその使い方について説明する。

  • アンビエント（環境光）
  • ディレクショナル
  • パラレルポイント
  • ポイント
  • スポットライト

アンビエント

アンビエント照明は、オブジェクトの向き、位置、サーフェスの特性などと関係なく、シーン上のすべてを照らす光である。シーンのすべての場所を同じ光度で照らすため、アタッチされたフレームの位置や向きは重要でない。1つのシーンには、複数のアンビエントライトが結合されている。

ディレクショナル

ディレクショナル（有向）照明は向きを持つが、位置は持っていない。フレームにアタッチされるとすべてのオブジェクトを同じ輝度で照らし、照明がオブジェクトからずっと離れた位置にあるような効果を与える。ディレクショナル照明は、太陽のような遠く離れた照明をシミュレートするために利用される。

パラレルポイント

パラレルポイント照明はパラレルライトでオブジェクトを照らすが、光の向きは光源の位置から決定される。つまり、パラレルポイント照明にはディレクショナル照明のように向きがあり、さらに位置も持っている。たとえば、パラレルポイント照明の両側にメッシュがある場合、照明に面しているほうのメッシュが明るくなる。パラレルポイント照明のレンダリングスピードは、ディレクショナル照明と同等である。

ポイント

ポイント照明は、光源から放射状に光を放つ。光が当たる面や法線のそれぞれについて、新しい光のベクトルを計算する必要があるため、パラレルポイント照明よりも計算時間がかかる。しかし、より正確な照明効果が実現できるので、リアルな表示が要求される場合に利用するべきである。

スポットライト

スポットライト照明は円錐状の光を生成する。光は、円錐の内部にあるオブジェクトにのみ当てられる。円錐は2つの輝度を生成する。中央の明るい部分（明部）はポイント照明と同じ働きをし、周囲の薄暗い部分（暗影部）は、その周辺の暗い影とマージされる。この2つの部分の角度は、IDirect3DRMLight::GetPenumbra 、IDirect3DRMLight::GetUmbra、IDirect3DRMLight::SetPenumbra、およびIDirect3DRMLight::SetUmbraによって個々に指定することができる。


出力デバイス

レンダリングされたすべての出力形式は、出力デバイスと関連していなくてはならない。デバイスオブジェクトは、レンダリングの出力先の可視ディスプレイを表している。

デバイスオブジェクトは、レンダリングの出力先の可視ディスプレイを表している。 レンダリングの動作は、指定された出力デバイスのタイプに依存する。デバイスに複数のビューポートを定義し、同時に表示されるシーンに異なる視点を与えることもできる。また、デバイスはいくつでも指定でき、同じシーンに複数の出力先を用意することも可能である。

保持モードは、スクリーンやウィンドウ、またはアプリケーションメモリに直接レンダリングするデバイスをサポートする。

アプリケーションは、IDirect3DRMDevice3、IDirect3DRMDevice2、IDirect3DRMDeviceインターフェイスを使用して、出力デバイスと対話する。詳細については「IDirect3DRMDevice3」を参照すること。

このセクションでは、Direct3Dイメージを出力デバイスに表示する際に有効なオプションについて説明する。

  • クオリティ
  • カラーモデル
  • ウィンドウ管理

クオリティ

シーンやその構成要素は、出力デバイスによって、リアルの程度をさまざまに変えてレンダリングすることができる。レンダリングクオリティとは、デバイスのレンダリングサーフェス上で実行されるレンダリングのクオリティの最大値である。メッシュ、プログレッシブメッシュおよびメッシュビルダオブジェクトでも、レンダリングクオリティを指定することができる。

デバイスまたはオブジェクトのクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーローで、フォンは実装されていない。デフォルトはグーローシェーディング)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

IDirect3DRMDevice3::SetQualityメソッドを用いて、デバイスのクオリティを設定する。デフォルトで、デバイスクオリティはD3DRMRENDER_FLAT (フラットシェーディング、照明オンおよびソリッド塗りつぶし) である。

Direct3DRMProgressiveMesh、Direct3DRMMeshBuilder3またはDirect3DRMMeshBuilder3オブジェクトのクオリティは、それぞれのSetQualityメソッド、つまりIDirect3DRMProgressiveMesh::SetQuality、IDirect3DRMMeshBuilder3::SetQuality、およびIDirect3DRMMeshBuilder3::SetQualityを用いて設定することができる。デフォルトで、これらのオブジェクトのクオリティはD3DRMRENDER_GOURAUD (グーローシェーディング、照明オンおよびソリッド塗りつぶし) である。

ヒント: グーローシェーディングを使用すると、詳細レベルを高速に変更するプログレッシブメッシュオブジェクトのパフォーマンスが向上する。

Direct3D保持モードは、デバイスやオブジェクトの個々のコンポーネントに対する現在の設定の中でもっとも低位のクオリティで、オブジェクトにレンダリングを行う。たとえば、オブジェクトの現在のクオリティ設定がD3DRMRENDER_GOURAUDで、デバイスがD3DRMRENDER_FLATであると、オブジェクトはフラットシェーディング、ソリッド塗りつぶしおよび照明オンでレンダリングされる。

オブジェクトの現在のクオリティ設定がD3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAMEで、デバイスのクオリティ設定がD3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINTであると、オブジェクトはフラットシェーディング、照明オフおよびポイント塗りつぶしモードでレンダリングされる。

これらのルールは、Direct3DRMMeshBuilder3オブジェクトおよびDirect3DRMProgressiveMeshオブジェクトに適用される。しかし、Direct3DRMMeshオブジェクトはこれらのルールに従わない。メッシュオブジェクトはデバイスのクオリティ設定を無視し、グループクオリティ設定を用いる(デフォルトでD3DRMRENDER_GOURAUD)。

カラーモデル

保持モードは、RGBモデルとモノクロ（ランプ）モデルの2つのカラーモデルをサポートする。カラーモデルを取得するためには、アプリケーションからIDirect3DRMDevice3::GetColorModelメソッドを使用する。

RGBモデルは、色を赤、緑、青の光の組み合わせとして扱い、色の付いた複数の照明をサポートする。シーンで使われる色数には制限がない。このモデルは、8、16、24、32ビットのディスプレイで利用することができる。ディスプレイの表示可能色数が24ビットよりも少ないと、色解像度の制限によって階段状に階調が変化するのが目立つバンディング（マッハバンドとも呼ぶ）が発生する場合がある。これは、オプションのディザ処理を用いることで回避することができる。

モノクロモデルでも複数の照明はサポートされるが、その色要素は無視される。それぞれの照明は、グレーの光度で設定される。頂点のRGBカラーは輝度として解釈される。異なる明るさで頂点の間の輝度が（グーローシェーディングモードでは）補間される。モノクロモデルでは、シーン上のオブジェクトの色数が制限される。システムパレットの空きエントリをすべて使い尽くすと、システム内部のパレットマネージャは、指定された色に最も近い色をパレット内から探す。モノクロモデルは、RGBモデルと同様に、8、16、24、32ビットのディスプレイで使用することができる（ただし、モノクロモデルは8ビットのテクスチャしかサポートしない）。RGBモデルの代わりにモノクロモデルを使用する利点は、パフォーマンスがかなり向上することである。

Direct3Dデバイスのカラーモデルは、変更することができない。アプリケーションは、必要なカラーモデルをサポートしたドライバを識別するために、IDirect3D::EnumDevicesメソッドかIDirect3D::FindDeviceメソッドを使用し、デバイス作成メソッドの中でそのドライバを指定しなくてはならない。

パレットはテクスチャ、オフスクリーンサーフェスおよびオーバーレイサーフェスでサポートされており、プライマリサーフェスと同一のパレットである必要はない。デバイスが4ビットインデックス付きパレット (16色) をサポートし、8ビットインデックス付き作品 (256色) がある場合、保持モードはパレットから最初の16エントリを取り出して再マッピングを行い、4ビットとして作品のレンダリングを行う。したがって、可能であれば望ましい16色をパレットの初めの部分に配置するとよい。

ウィンドウ管理

正しい操作を行うために、オペレーティングシステムからWM_MOVEやWM_PAINT、WM_ACTIVATEメッセージを受け取ったとき、アプリケーションは、IDirect3DRMWinDevice::HandlePaintおよびIDirect3DRMWinDevice::HandleActivateメソッドを使用してDirect3Dに通知しなくてはならない。

関連情報については、「IDirect3DRMWinDevice」を参照すること。


テクスチャ

テクスチャは、色付きのピクセルが矩形に並んだものである（矩形は必ずしも正方形でなくてもよいが、システムが最も効率的に動作するのは正方形の場合である）。テクスチャはテクスチャマッピングの面として使うこともできるが、この場合は正方形でなくてはならない。

アプリケーションは、D3DRMIMAGE構造体からテクスチャを作成するために、IDirect3DRM3::CreateTextureメソッドを使うことができる。また、IDirect3DRM3::CreateTextureFromSurfaceメソッドによってDirectDrawサーフェスからテクスチャを作成することもできる。さらに、IDirect3DRM3::LoadTextureメソッドを用いると、ファイルからテクスチャをロードすることができる。この場合、テクスチャはMicrosoft® Windows®のビットマップ（.bmp）か、ポータブルピクスマップフォーマット（.ppm）でなくてはならない。テクスチャを作成するときに不必要な遅延を避けるため、再利用するテクスチャは保持するようにし、必要になるたびに作成しなくて済むようにする。最適なパフォーマンスを得るには、使用するデバイスのサポートするテクスチャサーフェスフォーマットを使う。これにより、テクスチャを作成した後でそれが変更されるときに、手間のかかるフォーマット変換を回避することができる。テクスチャが16色以下で構成されている場合、4ビットでパレット化したサーフェスフォーマットを使用して、ハードウェアデバイスのビデオメモリ使用量を減らす。

各面のテクスチャ座標は、その特定の面にマッピングされるテクスチャのリージョンを定義している。アプリケーションは、テクスチャ座標を計算するためにラップを利用することができる。詳細情報は、「ラップ」を参照すること。

IDirect3DRMTexture3インターフェイスは、（IDirect3DRMTextureインターフェイスの拡張である）IDirect3DRMTexture2インターフェイスの拡張である。

テクスチャは、右側を上にしてIDirect3DRMTexture3::InitFromFile,、IDirect3DRMTexture3::InitFromResource2、およびIDirect3DRMTexture2インターフェイスでの同じメソッドで、BMPとDIB（デバイス独立ビットマップ）ファイルからロードされる。これは、反転されたロードされるIDirect3DRMTexture::InitFromFileおよびIDirect3DRMTexture::InitFromResource2とは異なる。

これらのインターフェイスのメソッドについては、「IDirect3DRMTexture3」を参照すること。

この項では、Direct3Dがサポートするテクスチャの種類と使い方を説明する。

  • デカール
  • テクスチャの色
  • ミップマップ
  • テクスチャフィルタリング
  • テクスチャの透明化
  • テクスチャフォーマット選択ルール

デカール

テクスチャは、ビジュアルオブジェクトとして直接レンダリングすることができる。このように用いられるテクスチャは、デカールとして知られている。デカールとは保持モードで採用された用語である。デカールは、ビューポートと一致した矩形にレンダリングされる。この矩形は、オプションとして、デカールの立体位置によるスケーリングが可能である。IDirect3DRMTexture3::SetDecalSizeメソッドを使用すると、フレームに対して相対的に定義された矩形からデカールのサイズを設定することができる（アプリケーションは、IDirect3DRMTexture3::GetDecalSizeメソッドによってデカールのサイズを知ることができる）。その後、デカールは変換され、透視投影される。

デカールの原点は、アプリケーションから設定および取得することができる。これにはIDirect3DRMTexture3::SetDecalOriginおよびIDirect3DRMTexture3::GetDecalOriginメソッドを用いる。原点は、デカールの左上隅からのオフセットで表される。デフォルトの原点は[0, 0]である。レンダリングの際には、デカールの原点はフレームの位置に合わせられる。

テクスチャの色

テクスチャのレンダリングで用いられる色数の取得や設定を行うには、IDirect3DRMTexture3::SetColorsおよびIDirect3DRMTexture3::GetColorsメソッドを利用する。

RGB色モデルを用いるアプリケーションでは、8ビット、24ビット、32ビットのテクスチャを使用することができる。しかし、モノクロ (ランプ) カラーモデルを用いる場合には、8ビットのテクスチャのみ使用できる。

シーンに光を適用するとき、それぞれの色の影が使用される。使われている影の数の設定や取得を行うには、アプリケーションからIDirect3DRMTexture3::SetShadesおよびIDirect3DRMTexture3::GetShadesメソッドを呼び出す。

Direct3DRMTextureオブジェクトは、テクスチャがレンダリングされる元となるビットマップを定義するためにD3DRMIMAGE構造体を使用する。アプリケーションがD3DRMIMAGE構造体を提供すれば、レンダリング中に簡単にテクスチャを動かしたり変更できる。

ミップマップ

ミップマップとは連続したテクスチャを示し、各テクスチャは、同じイメージにフィルタをかけて徐々に低解像度にしたものである。ミップマップは、計算上低コストにテクスチャのレンダリング精度を高める手段である。ミップマップ中のフィルタされたイメージやレベルは、前のレベルよりも小さくなっていく。ミップマップは、IDirect3DRMDevice3::SetTextureQualityメソッドを呼び出してテクスチャをフィルタリングするときに指定することができる。

ミップマップの詳細については、「ミップマップ」を参照すること。

テクスチャフィルタリング

テクスチャが面にマッピングされた後は、テクスチャ要素（テクセル）が最終イメージの個々のピクセルと一致することは滅多にない。最終イメージ中のピクセルは、テクセルの大きな集合体か、1つのテクセルの小部分に相当する。ピクセルにテクセルの値を補間する方法を指定するには、テクスチャフィルタリングを利用する。

アプリケーションは、IDirect3DRMDevice3::SetTextureQualityメソッドとD3DRMTEXTUREQUALITY列挙型を使用して、テクスチャフィルタリングモードを指定することができる。

テクスチャの透明化

透明なテクスチャを生成するにはIDirect3DRMTexture3::SetDecalTransparencyメソッドを利用する。テクスチャを透明化する他の方法としては、DirectDrawがサポートするカラーキーを使用する方法がある。カラーキーとは、ブロック転送やオーバーレイ操作における、転送元あるいは転送先部分の色または色の範囲である。これらの色は、つねに上書きされるようにも、決して変更されないようにも指定することができる。

DirectDrawのカラーキーサポートの詳細については、「カラーキーイング」を参照すること。

テクスチャフォーマット選択ルール

デバイス独立ソースイメージを使用して、レンダリングするデバイス依存テクスチャサーフェスを作成する場合、以下のルールがある(優先順位順)。

1. RGB/パレット化特性を保存する。

2. アルファチャネルを保存する。

3. ビット深度またはパレットサイズを保存する。

4. RBGAマスクを保存する。

5. 8ビットパレット化または16ビットRGBを優先する。

テクスチャピクセルフォーマットの詳細については、「テクスチャマップフォーマット」を参照すること。

関連情報については、「IDirect3DRMTexture3」を参照すること。


ビューポート

ビューポートは、3Dシーンがどのように2Dウィンドウにレンダリングされるかを定義する。ビューポートは、オブジェクトがレンダリングされるデバイス上の矩形領域を定義する。

このインターフェイスのメソッドのリファレンスは、「IDirect3DRMViewport2」を参照すること。

このセクションでは、ビューポートとその構成要素、使用上のテクニックについて説明する。

  • カメラ
  • 視錘台
  • 変換
  • ピッキング

カメラ

ビューポートはDirect3DRMFrameオブジェクトをカメラとして使用する。カメラフレームは、レンダリングされるシーン、表示位置および方向を定義する。ビューポートは、カメラフレームの正のz軸上にある可視オブジェクトだけを、y軸上の正方向にレンダリングする。

アプリケーションは、与えられたビューポートにカメラをセットするために、IDirect3DRMViewport2::SetCameraメソッドを用いることができる。このメソッドは、ビューポートの位置、方向、向きをカメラフレームに設定する。現在のカメラの設定を取得するには、IDirect3DRMViewport2::GetCameraメソッドを呼び出す。

視錐台

視錐台は、ビューポートカメラと相対して置かれた、シーン中の3Dボリュームである。パースペクティブビューイングでは、カメラは想像上のピラミッドの頂点に置かれる。このピラミッドは、2つのクリップ面のフロントクリッピングプレーンとバッククリッピングプレーンと交差する。この前後のクリップ面の間にあるピラミッドの体積が視錐台である。視錐台内のオブジェクトだけが可視状態になる。

カメラのz軸は、ピラミッドの頂点からバッククリッピングプレーンの中心を通る。ユーザのアプリケーションが、前後のクリッププレーンの位置を設定、取り出すには、IDirect3DRMViewport2::SetFront、IDirect3DRMViewport2::SetBack、IDirect3DRMViewport2::GetFront、およびIDirect3DRMViewport2::GetBackメソッドを使用して行うことができる。

フロントクリッピングプレーン上のビューポートの次元がカメラのレンズの見かけ上の焦点長を決定する（これは、錐台の中のオブジェクトの拡大率を設定する方法と考えることもできる）。フロントクリッピングプレーン上のビューポート用の比例次元を設定、取り出すには、IDirect3DRMViewport2::SetFieldおよびIDirect3DRMViewport2::GetFieldメソッドを使用する。フロントクリッピングプレーン上のビューポート用の任意の次元を設定、取り出すには、IDirect3DRMViewport2::SetPlaneおよびIDirect3DRMViewport2::GetPlaneメソッドを使用する。

以下の式を使用して、フロントクリッピングプレーンの高さ (または幅) とビューイング角度との関係を決定することができる。

この式で、ビューイング角度はA、フロントクリッピングプレーンのカメラからの距離はD、フロントクリッピングプレーンの高さは2hである。デバイスが正方形でなければ、したがってクリップ面が正方形でなければ、ビューイング角度はフロントクリッピングプレーンの半分の高さまたは幅の大きい方を用いて計算される。縮尺係数は、歪んだオブジェクトにならないよう、デバイスの主軸にセットする。これを望まない場合は、一様スケーリングを設定する必要がある。

視錘台のピラミッドは、透視投影の場合にのみ適用される。平行投影においては、視錘台は立方体になる。ビューのタイプ（または投影方法）はD3DRMPROJECTIONTYPE列挙型で定義されており、IDirect3DRMViewport2::GetProjectionおよびIDirect3DRMViewport2::SetProjectionメソッドで使われる。

単位

DirectSoundは、デフォルトの単位 (メートル) が決まっている唯一のDirectXモジュールである。デフォルト単位は距離係数を使用して変更できる。しかし、Direct3D直接モードおよび保持モードでは特定のデフォルト単位がない。開発者はアプリケーションに最適な単位を決めて、プログラムに組み込む必要がある。ほとんどのアプリケーションでは、メートルかフィートが適切だが、そうでない場合もある。たとえば、太陽と月を画面に配置するときは、距離をマイル単位で計測する。また、昆虫や原子の粒子をモデリングするときは、単位をメートルやフィートよりもはるかに小さくする必要がある。DirectXは単純に「単位」ベースで動作し、実際の距離の概念は持たない。

単位を指定せずにシーンを構築すると、各種ソースからDirectXファイルをインポートするときに問題が発生する。単位はファイルに含まれておらず、任意の「単位」が自由に使えるため、標準単位を必要としない。そのため、異なるソースからインポートした2機の飛行機を正しくスケーリングすることは難しい。一方のモデルがメートル、もう一方がフィートでモデリングされていれば、一方のモデルをロードするときに、スケーリングすればよい。IDirect3DRMMeshBuilder3::Scale関数は、モデルの単位が分かっているときに使用する。モデル作成時に使用した単位が分からない場合、開発者は試行錯誤と直感的な推量で作業を進める必要がある。

DirectSoundを使用する場合は、アプリケーション全体でデフォルトの単位をメートルに設定するとよい。詳細については、DirectSound の「最小距離と最大距離」と「距離係数」を参照すること。

変換

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はカメラからの距離、Dはフロントクリッピングプレーンのz座標を示している。

射影をした後、次のステップは、クリッピングおよびビューポート内のスクリーンピクセル座標へのxとyの変換である。このために、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;

dwXおよびdwYフィールドは、サーフェス上のビューポートの左上へのオフセットをスクリーンピクセルで指定する。

dwWidthおよびdwHeightフィールドは、スクリーンピクセルで表したビューポートの幅と高さである。

dvScaleXおよびdvScaleYフィールドは、スクリーン座標を生成するためにx値およびy値に適用される縮尺係数である。通常、次の等式を用いて、正規化透視ビューボリューム全体をビューポートにマッピングする。

  dvScaleX = dwWidth / 2
  dvScaleY = dwHeight / 2

たとえば－1から1のX座標は、－dwWidth / 2からdwWidth / 2にスケーリングされ、次いで、dwWidth / 2のオフセットが加えられる。このスケーリングは、クリッピングの後に行われる。

ウィンドウが正方形でなく、正しいアスペクト比を保持したければ、2つのウィンドウディメンジョンの大きい方を両スケーリング値として用いる。また、ビューボリュームの一部をクリップする必要がある。

dvMaxX、dvMaxY、dvinZ、およびdvMaxZフィールドは、クリップ面を指定する。x = dvMaxX、x =－dvMaxX、y = dvMaxy、y =－dvMaxY、z = dvMinZ、z = dvMaxZ。たとえば、ビューボリュームを表示するには、dvMaxX = dvMaxY = dvMaxZ = 1およびdvMinZ = 0とする。上述したように、非正方形ウィンドウで正しいアスペクト比を保持したければ、ビューボリュームの一部をクリップする必要がある。それには、以下の等式を用いる。これらの等式は、正方形ビューポートの場合にも使用することができ、したがって常に使うことができる。

dvMaxX = dwWidth / (2 * dvScaleX)
dvMaxY = dwHeight / (2 * dvScaleY)

ビューポート変換を用いると、ワールド座標でのオブジェクトの移動距離をカメラから奥行きまでの距離と一致させることができる。IDirect3DRMViewport2::Transformメソッドの結果は、4つの要素を持つベクトルで表されることに注意されたい。これによって、カメラの位置に限りなく近い座標で生じる問題を回避することができる。

フレームの変換については、「変換」を参照すること。変換の数学の概要については、「3D変換」を参照すること。

ピッキング

ピッキングとは、ビューポートのウィンドウで、2D座標からシーン上のビジュアルオブジェクトを探索するプロセスである。アプリケーションはIDirect3DRMViewport2::Pickメソッドを使用して、シーン上の最も近いオブジェクト、またはオブジェクトの重なり順のリストを取得することができる。


ラップ

ラップは、面やメッシュのテクスチャ座標の計算に使用することができる。ラップを作成するには、アプリケーションは、ラップのタイプや参照フレーム、原点、方向ベクトル、上ベクトルを指定しなくてはならない。また、スケーリング係数とテクスチャ座標の原点も指定する必要がある。

アプリケーションは、IDirect3DRM3::CreateWrapメソッドを呼び出してIDirect3DRMWrapインターフェイスを生成する。このインターフェイスには、IDirect3DRMWrap::ApplyとIDirect3DRMWrap::ApplyRelativeの2つの特有なメソッドが含まれている。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)を通過する。
  • D3DRMMAP_WRAPUまたはD3DRMMAP_WRAPVのいずれかがセットされた場合、テクスチャは円周1.0の終わりのない円筒形になる。1.0以上のテクスチャ座標は、ラップされていない範囲内のみ有効である。テクスチャ座標間の最短距離はラッピングフラグによって異なる。D3DRMMAP_WRAPUがセットされているときは、点(0.1, 0.1)から(0.9, 0.9)までの最短の直線は、点（0, 0.5）を通過する。
  • D3DRMMAP_WRAPUとD3DRMMAP_WRAPVフラグの両方がセットされたときは、テクスチャは円環体（ドーナツ）状になる。システムは閉鎖しているため、1.0以上のテクスチャ座標は無効である。点(0.1, 0.1)から(0.9, 0.9)までの最短の直線は、点(0, 0)を通過する。

無効領域にあったテクスチャ座標を有効領域に収めたとしても、そのときの動作は保証されていない。

一般にアプリケーションは、テクスチャの交線が面の辺と一致しないとき、円柱状にラップするためにラッピングフラグをセットする。1つの面にテクスチャの半分以上が使用される場合には、ラッピングフラグは設定しない。

平面

平面ラップでは、テクスチャは、オブジェクト上にストレッチされたゴムのようにオブジェクトの面に一致する。

次の等式により、ベクトル[x y z]から[u v]座標が求められる。

平面ラップのベクトルから [u v] 座標を求める式

これらの公式において、sはウィンドウのスケーリング係数、oはウィンドウの原点を示している。アプリケーションは、1組のスケーリング係数と、uおよびvが有効な値を取るようにxとyを0から1の範囲にマップするためのオフセットを決定しなくてはならない。

円柱

円柱ラップでは、テクスチャは円柱の回りを包む紙のように扱われ、その左端は右端につながっている。オブジェクトは円周の中央に配置され、オブジェクトのサーフェスに合わせてテクスチャが変形される。

次の図は、円柱テクスチャマップにおける各ベクトルの効果を示したものである。

方向ベクトルは円柱の軸を示し、上ベクトルは円筒の外側のu = 0である点を示す。システムは、ベクトル[x y z]に対するテクスチャの[u v]座標を計算するために、次の等式を使用する。

円柱ラップのベクトルから [u v] 座標を求める式

通常、uはスケーリングされないままである。vが有効な値を取るように zを0から1の範囲にマップして、vのスケーリングと変換が行われる。

球体

球体ラップでは、ベクトル[x y 0]とx軸の角度から（円柱ラップと同様に）u座標が求められる。v座標は、ベクトル[x y z]とz軸の角度から求められる。このマッピングでは、z軸上に歪みが生じることに注意が必要である。

これは次の等式で表される。

球体ラップのベクトルから [u v] 座標を求める式

ここでは、スケーリングされていないuとvの範囲は常に0から1であるため、スケーリング係数とテクスチャの原点は必要とされないことが多い。

クロム

クロムラップは、テクスチャがオブジェクト上に反射して見えるようにテクスチャ座標を割り当てる。クロムラップは参照フレームの位置を取得し、反射ベクトルを計算するためにメッシュの頂点法線を使用する。その後、メッシュを取り囲む仮想の球体を利用して、反射ベクトルの交線からテクスチャのuおよびv座標を計算する。これによって、球体に何がラップされていても、メッシュに反射効果が与えられる。


チュートリアル

Microsoft® Windows®ベースのDirect3D®保持モードアプリケーションを作成するためには、異なる2つの環境を設定しなくてはならない。1つは、デバイス、ビューポート、色解像度といったWindows環境であり、もう1つは、モデル、テクスチャ、照明、位置といった仮想環境である。このチュートリアルでは、簡単な保持モードアプリケーションの全コードを紹介している。次の図は、動作中のアニメーションのフレームの1つである。

このチュートリアルは、以下のセクションに分けられている。

  • Helworldサンプルの作成
  • マクロ定義とグローバル変数
  • Windowsのセットアップと初期化
  • デバイスドライバの列挙
  • 3D環境のセットアップ
  • レンダリングループ
  • シーンの作成
  • 終了処理

Helworldサンプルの作成

このチュートリアルには、実際のDirect3D保持モードアプリケーションのすべてのコードが含まれている。以下の条件を満たすと、チュートリアルからこのコードを単一の.cファイルにコピーし、コンパイルして実行することができる。

  • Direct3Dヘッダファイル(D3d.h、D3drm.hなど)をインクルードパスに設定していること。
  • Winmm.lib、D3drm.lib、およびDdraw.lib静的ライブラリとリンクしていること。
  • 使用するコンパイラが、Microsoft® DirectX® Software Development KitのMediaディレクトリ中のSphere3.xファイルを発見できること。
  • Tutor.bmpファイルを供給すること。

    このビットマップのピクセルサイズは、2の累乗でなければならないことに注意する。たとえば、16×16ピクセルビットマップ、128×1024ピクセルビットマップ、512×256ピクセルビットマップなどである。

このサンプルの中で、3D効果を受け持つコードの大半は、別個の関数に分割されているので、ユーザは、サンプルの一部を徐々に修正して実験することができる。Direct3Dのさらに複雑な機能を実装するには、DirectX SDKのサンプルを調べる必要がある。

以下の項目は、単純なDirect3D保持モードアプリケーションの開発全般に適用できる事項をいくつか説明するものである。

  • サンプルの制限
  • DirectDrawのウィンドウモード

サンプルの制限

このチュートリアルには、Helworld.cのサンプルコードが含まれている。そのコードは、球を生成して、その球にテクスチャを適用し、ウィンドウの中で回転させる。これは、このアプリケーションを作成するのに必要な、ただ1つのCソースファイルである。他に必要なファイルは、Sphere3.x、DirectX SDKのMediaディレクトリの中で配布されている1つのメッシュファイル、ユーザが供給するビットマップのTutor.bmpだけである（ユーザのインクルードパス中にDirect3Dヘッダファイルを設定していること、Winmm.lib、D3drm.lib、およびDdraw.lib静的ライブラリにリンクしていることが前提であることに注意する)。

このチュートリアルは、DirectX SDKの一部であるGlobeサンプルを簡単にしたものである。Globeサンプルは、SDKのすべてのDirect3D保持モードサンプルと同様に、Rmmain.cppファイルといくつかのヘッダファイルをインクルードすることを必要とする。Helworld.cでは、Rmmain.cppの使用可能部分をC++からCに変換してソースコードに取り込んである。

このチュートリアルで示すコードは、実用コードと間違えてはいけない。プログラムと可能なユーザの対話型操作は、プログラムを起動、停止することと、実行中にウィンドウを最小化することに限定されている。コードを分かりやすくするため、エラーチェックの大半は除いてある。このサンプルの目的は、煩雑なことを最小限にして出力を行う、"Hello, world!"を画面上に表示する初歩のプログラムの目的に似ている。

DirectDrawのウィンドウモード

ほとんどすべてのDirect3Dアプリケーションは、DirectDraw®を用いてスクリーンにグラフィックスを表示する。これらのアプリケーションは、DirectDrawの排他（フルスクリーン）モードまたは非排他（ウィンドウ）モードのいずれかを使用する。このドキュメントのコードはウィンドウモードを使っている。フルスクリーンモードはパフォーマンス上の利点や快適さを提供するが、ウィンドウモードで書かれたコードのほうがデバッグが簡単である。ほとんどの開発者はウィンドウモードでコードを書き、デバッグ終了後、フルスクリーンモードに移行させる。

マクロ定義とグローバル変数

以下は、Helworld.cサンプルの最初の数行である。このアプリケーションをビルドするのに他のCソースファイルは必要ないが、ファイルの拡張子は.cppではなく .cにする。Cコンパイラは、拡張子.cppの付いたファイルをC++のコードとみなし、lpVtbl ポインタと追加パラメータのthisを扱う。詳しくは、DirectX SDKドキュメントの「CからのCOMオブジェクトへのアクセス」を参照すること。このチュートリアルはCで書かれているため、明示的にlpVtbl ポインタをインクルードし、初期thisパラメータを追加している。このファイルの拡張子を.cppにすると、コンパイラは多数のコンパイルエラーを生成する。

INITGUIDは、他のインクルードやマクロ定義よりも前に定義されていなくてはならない。これは、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の初期化関数（InitApp）は、ほとんどのWindowsベースのアプリケーションと同様に、ウィンドウクラスを登録し、メインアプリケーションウィンドウを作成する。この後、InitApp関数はDirectDrawやDirect3Dを用いるアプリケーションに特有の処理を行う。

次に、InitApp関数は、現在のディスプレイのピクセル当たりのビット数を取得する。この値は、アプリケーションがレンダリングのクオリティを設定する際に使用される。詳しくは「レンダリングステートの設定」を参照すること。

その後、どのDirect3Dドライバが有効であるかを決定し、適切なドライバを選択するために、ローカル定義のEnumDrivers関数を使用する。ドライバの列挙について詳しくは、「デバイスドライバの列挙」を参照すること。

次に、Direct3DRMCreate関数を使って、IDirect3DRM3インターフェイスを作成する。このインターフェイスは、シーンやカメラフレームを作成したり、カメラをシーンに設置するため、IDirect3DRM3::CreateFrameやIDirect3DRMFrame3::SetPositionを呼び出すときに使用される。

DirectDrawClipperオブジェクトは、どの部分の3Dシーンを可視状態にするかを制御するクリップ面の管理を簡単にする。Helworld.cは、DirectDrawCreateClipper関数を使ってIDirectDrawClipperインターフェイスを生成した後、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ドライバを列挙し、1つを選択する。

    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:
        {

        // このメッセージを処理する、ウィンドウ固有の
        // Direct3D保持モードウィンドウデバイスを作成する。

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

        // このメッセージを処理する、ウィンドウ固有の
        // Direct3D保持モードウィンドウデバイスを作成する。

        if (GetUpdateRect(win, &r, FALSE)) {
            BeginPaint(win, &ps);
            myglobs.dev->lpVtbl->QueryInterface(myglobs.dev,
                &IID_IDirect3DRMWinDevice, (void **) &lpD3DRMWinDev);
            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（Component Object Model）インターフェイスは、実際にはDirectDrawオブジェクトに対するインターフェイスであるので、この列挙関数が最初にすることは、DirectDrawCreate関数を使ってDirectDrawObjectを作成することである。その後、EnumDriversがQueryInterfaceメソッドを使用してIDirect3Dインターフェイスを生成する。QueryInterfaceのCの実装が、単純に定数自体ではなく（C++の実装のように）、2番目のパラメータとしてインターフェイス識別子のアドレスを渡すことを要求することに注意する。

ドライバの列挙は、IDirect3D::EnumDevicesメソッドによって行われる。IDirect3D::EnumDevicesメソッドは、ローカルに定義されたenumDeviceFuncコールバック関数を利用する。このコールバック関数の詳細については、「enumDeviceFuncコールバック関数」を参照すること。

IDirect3D::EnumDevicesはDirect3Dメソッドであり、Direct3DRMメソッドではないことに注意が必要である。保持モードのAPIには、列挙を行うメソッドは存在しない。これは、1つのアプリケーションで保持モードと直接モードの両方を使用する場合の良い例である。

/////////////////////////////////////////////////////////////////////
//
// EnumDrivers
// 有効なD3Dドライバを列挙し、1つを選択する。
//
/////////////////////////////////////////////////////////////////////

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

    // 少なくとも有効なドライバが1つはあることを保証する。

    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環境を構築する部分について説明する。以下のセクションは、この処理を実行するための2つの関数について説明している。

  • デバイスとビューポートの作成
  • レンダリングステートの設定

これらの関数は、3D環境にオブジェクトやフレーム、光を配置するものではない。シーンの作成は、MyScene関数と、MyScene関数が使う関数群によって実現される。3D環境にシーンを設定する方法については、「シーンの作成」を参照すること。

デバイスとビューポートの作成

Direct3Dデバイスとビューポートは、アプリケーションの初期化の一環として作成される。InitApp関数は、DirectDrawClipperオブジェクトを生成した後、DirectDrawClipperオブジェクトと選択されたドライバ、およびクライアント矩形の寸法をパラメータとして、CreateDevAndView関数を使用する。

CreateDevAndView関数は、列挙プロセスで選択されたドライバを使用して、IDirect3DRM3::CreateDeviceFromClipperメソッドによってDirect3DRMデバイスを作成する。このIDirect3DRMDevice3インターフェイスは、デバイスの幅および高さを取得するIDirect3DRMDevice3::GetWidthとIDirect3DRMDevice3::GetHeightメソッドの使用で用いられる。CreateDevAndView関数は、デバイスの幅や高さの情報を受け取った後、IDirect3DRM3::CreateViewportメソッドを使ってIDirect3DRMViewport2インターフェイスを取得する。

次に、CreateDevAndView関数が、IDirect3DRMViewport2::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関数は、光をオン、塗りつぶしモードをソリッドにし、グーローシェーディングモードを用いるように指定して、IDirect3DRMDevice3::SetQualityメソッドを使う。このとき、ディザモードやテクスチャのクオリティを変更する必要があるアプリケーションは、IDirect3DRMDevice3::SetDitherメソッドやIDirect3DRMDevice3::SetTextureQualityメソッドを使うことができる。

/////////////////////////////////////////////////////////////////////
//
// 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を使う。

   return TRUE;
}

レンダリングループ

WinMain関数は、次のフレームを描画するため、RenderLoop関数を使う。RenderLoop関数は、いくつかの単純な処理を実行する。

  • IDirect3DRMFrame3::Move メソッドを使って、階層下のすべてのフレームの回転や速度の適用を行う。
  • IDirect3DRMViewport2::Clearメソッドを使って、現在のビューポートを背景色でクリアする。
  • IDirect3DRMViewport2::Renderメソッドを使って、現在のシーンをビューポートにレンダリングする。
  • IDirect3DRMDevice3::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関数はIDirect3DRMFrame3::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関数は、IDirect3DRM3::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関数はIDirect3DRM3::CreateLightRGBとIDirect3DRMFrame3::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関数は、この処理をIDirect3DRMFrame3::SetPositionおよびIDirect3DRMFrame3::SetOrientationメソッドの使用によって実行する。IDirect3DRMFrame3::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関数はIDirect3DRM3::CreateMeshBuilderメソッドを使ってIDirect3DRMMeshBuilder3インターフェイスを生成する。次に、IDirect3DRMMeshBuilder3::Load、IDirect3DRMMeshBuilder3::Scale、およびIDirect3DRMMeshBuilder3::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関数は、球体を含む境界ボックスを取得するためにIDirect3DRMMeshBuilder3::GetBoxメソッドを呼び出し、その境界ボックスのサイズをIDirect3DRM3::CreateWrapメソッドの呼び出し時に使用する。IDirect3DRM3::CreateWrapメソッドは円柱のテクスチャラップを作成し、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は、IDirect3DRM3::LoadTextureメソッドを使ってTutor.bmpビットマップをロードした後、IDirect3DRMMeshBuilder3::SetTextureメソッドを呼び出してそのビットマップを球に関連付ける。

/////////////////////////////////////////////////////////////////////
//
// AddMyTexture
// ラップを作成し、テクスチャに適用する。
//
/////////////////////////////////////////////////////////////////////

void AddMyTexture(LPDIRECT3DRMMESHBUILDER  lpSphere3_builder,
    LPDIRECT3DRMTEXTURE * lplpTex)
{
    lpD3DRM->lpVtbl->LoadTexture(lpD3DRM, "tutor.bmp", 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;
}


C++/COMリファレンス

Microsoft® Direct3D®保持モードのリファレンスは、インターフェイス、メソッド (インターフェイス メンバ関数)、非メンバ関数、コールバック関数について、構文、パラメータ記述、フラグ記述などの詳細情報を提供する。また、Direct3D 保持モードの構造体メンバ、列挙型、その他の定義済タイプ、返される可能性のあるエラー値についても記述する。この項には、次のトピックが含まれる。

関数とインターフェイス

  • コールバック関数
  • インターフェイス
  • 非メンバ関数

データタイプ

  • 定数
  • 列挙型
  • 構造体

他のトピック

  • 戻り値
  • 追加情報


C++コールバック関数

Microsoft® Direct3D® 保持モードのC++コールバック関数は次の通りである。

  • D3DRMDEVICE3UPDATECALLBACK (D3DRMUPDATECALLBACKと差し替え)
  • D3DRMDOWNSAMPLECALLBACK
  • D3DRMFRAME3MOVECALLBACK (D3DRMFRAMEMOVECALLBACKと差し替え)
  • D3DRMLOADCALLBACK
  • D3DRMLOADTEXTURECALLBACK
  • D3DRMLOADTEXTURE3CALLBACK
  • D3DRMOBJECTCALLBACK
  • D3DRMUSERVISUALCALLBACK
  • D3DRMVALIDATIONCALLBACK
  • D3DRMWRAPCALLBACK

D3DRMDEVICE3UPDATECALLBACK

デバイスが変更されたときはアプリケーションに警告する。このコールバック関数の実体はアプリケーション定義である。

構文

void (*D3DRMDEVICE3UPDATECALLBACK)(
  LPDIRECT3DRMDEVICE3 lpobj,
  LPVOID lpArg,
  int iRectCount,
  LPD3DRECT d3dRectUpdate);

パラメータ

lpobj
コールバック関数を適用するDirect3DRMDevice3オブジェクトへのポインタのアドレス。
lpArg
コールバック関数に渡されるアプリケーション定義のデータへのポインタのアドレス。
iRectCount
d3dRectUpdateパラメータに指定された矩形の数。
d3dRectUpdate
更新される領域を表す、1つ以上のD3DRECT構造体の配列。座標はデバイス単位で指定される。

戻り値

なし。

注意

システムは、コールバック関数を使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を使う。

D3DRMDEVICE3UPDATECALLBACKはDirectX version 6.0で導入され、以前のD3DRMUPDATECALLBACKの差し替えである。この2つのコールバックの相違は、新規のコールバックがlpobjパラメータについてはDirect3DRMDeviceオブジェクトでなくDirect3DRMDevice3オブジェクトをとることだけである。

参照

IDirect3DRMDevice3::AddUpdateCallback, IDirect3DRMDevice3::DeleteUpdateCallback, IDirect3DRMDevice3::Update

D3DRMDOWNSAMPLECALLBACK

ビデオメモリがオーバーロードし、テクスチャサーフェスのサイズを削減する必要があるときに呼び出される。Direct3D保持モードでは、DirectDrawブロック転送と双一次フィルタリングなどのテクスチャサイズを削減するデフォルトのメソッドが提供されるが、ユーザは、独自のメソッドを定義して、このコールバック関数でテクスチャサイズをスケールダウンすることができる。このコールバック関数の実体はアプリケーションで定義される。

構文

HRESULT (*D3DRMDOWNSAMPLECALLBACK)(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  LPVOID lpArg,
  LPDIRECTDRAWSURFACE pDDSSrc,
  LPDIRECTDRAWSURFACE pDDSDst);

パラメータ

lpDirect3DRMTexture
コールバック関数を適用するDirect3DRMTexture3オブジェクトへのポインタのアドレス。
lpArg
コールバック関数に渡されるアプリケーション定義のデータへのポインタのアドレス。
pDDSSrc
システムメモリプロトタイプサーフェスへのポインタ。
pDDSDst
スケールダウンされたサーフェスへのポインタ。

戻り値

なし。

注意

D3DRMDOWNSAMPLECALLBACKは、DirectX version 6.0とともに導入された。

参照

IDirect3DRMTexture3::SetDownsampleCallback

D3DRMFRAME3MOVECALLBACK

フレームの移動や更新時に、アプリケーションがカスタマイズしたアルゴリズムを適用できるようにする。フレームレートを変更するためにこのコールバック関数を使用することができる。このコールバック関数の実体はアプリケーションで定義される。

構文

void (*D3DRMFRAME3MOVECALLBACK)(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame,
  LPVOID lpArg,
  D3DVALUE delta);

パラメータ

lpD3DRMFrame
変更しようとしているDirect3DRMFrame3オブジェクトへのポインタのアドレス。
lpArg
コールバック関数に渡されるアプリケーション定義のデータへのポインタのアドレス。
delta
運動に適用される変化量。フレームの位置を変更するには、直線と回転の2つの要素がある。各要素における変更は、velocity_of_component×deltaに等しい。これらの一方または両方の速度は、任意のフレームを起点として設定することができるが、システムは、自動的にデルタ時間を適用するので、親フレームを起点とした速度に変換する。

戻り値

なし。

注意

アプリケーションは、親フレームを基準にしてフレームの加速を合成することができる。そのためには、各ティックで、アプリケーションは、子フレームの速度をアプリケーション自身を基準とした（1ティックあたりaユニット）×1ティックに設定する必要がある。ここで、aは要求された加速度である。これは、ティック当たりのa×deltaに等しい。内部的には、子フレームを基準としたティック当たりのa×deltaは、親フレームを基準とした（v+(a×delta)）ユニットに変換される。ここで、vは、親を基準とする子フレームの現在の速度である。

このコールバック関数を追加／削除するには、IDirect3DRMFrame3::AddMoveCallbackおよびIDirect3DRMFrame3::DeleteMoveCallbackメソッドを使用する。

システムは、コールバック関数を使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を使う。

D3DRMFRAME3MOVECALLBACKは、DirectX version 6.0で導入され、旧のD3DRMFRAMEMOVECALLBACKを置換する。この2つのコールバックの相違は、新規のコールバックがlpD3DRMFrameパラメータについてはDirect3DRMFrameオブジェクトでなくDirect3DRMFrame3オブジェクトをとることだけである。

D3DRMLOADCALLBACK

IDirect3DRM3::Loadメソッド内部でオブジェクトのロードを行う。このコールバック関数の実体はアプリケーションで定義される。

構文

void (*D3DRMLOADCALLBACK)(
  LPDIRECT3DRMOBJECT lpObject,
  REFIID ObjectGuid,
  LPVOID lpArg);

パラメータ

lpObject
ロードされるDirect3DRMObjectへのポインタのアドレス。
ObjectGuid
ロードされるオブジェクトのグローバルユニーク識別子（GUID）。
lpArg
コールバック関数に渡されるアプリケーション定義のデータへのポインタのアドレス。

戻り値

なし。

注意

システムは、コールバック関数を使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を使う。

参照

IDirect3DRM3::Load

D3DRMLOADTEXTURECALLBACK

Loadメソッドの内部で、テクスチャファイル（もしくはリソース）の実際の読み込みを行う。このコールバック関数の実体はアプリケーションで定義される。

構文

HRESULT (*D3DRMLOADTEXTURECALLBACK)(
  char *tex_name,
  void *lpArg,
  LPDIRECT3DRMTEXTURE *lpD3DRMTex);

パラメータ

tex_name
テクスチャ名へのポインタのアドレス。
lpArg
アプリケーション固有のデータへのポインタのアドレス。
lpD3DRMTex
Direct3DRMTextureオブジェクトへのポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

正確な参照カウントを維持するには、テクスチャコールバックで作成されたテクスチャオブジェクト上のAddRefを呼び出す。

アプリケーションは、Microsoft® Windows®ビットマップ（.bmp）やポータブルピクセルマップビットマップ（.ppm）P6形式以外のテクスチャのサポートをインプリメントするため、このコールバック関数を使用することができる。P6フォーマットは、色イメージのバイナリファイルフォーマットである。

システムは、コールバック関数を使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を使う。

参照

IDirect3DRM3::Load, IDirect3DRMAnimationSet2::Load, IDirect3DRMFrame3::Load, IDirect3DRMMeshBuilder3::Load

D3DRMLOADTEXTURE3CALLBACK

Loadメソッドの内部で、テクスチャファイル（もしくはリソース）の実際の読み込みを行う。このコールバック関数の実体はアプリケーションで定義される。

構文

HRESULT (*D3DRMLOADTEXTURE3CALLBACK)(
  char *tex_name,
  void *lpArg,
  LPDIRECT3DRMTEXTURE3 *lpD3DRMTex3);

パラメータ

tex_name
テクスチャ名へのポインタのアドレス。
lpArg
アプリケーション固有のデータへのポインタのアドレス。
lpD3DRMTex3
Direct3DRMTexture3オブジェクトへのポインタのアドレス。

戻り値

成功すればD3DRM_OKを返す。失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

正確な参照カウントを維持するには、テクスチャコールバックで作成されたテクスチャオブジェクト上のAddRefを呼び出す。

アプリケーションは、Microsoft® Windows®ビットマップ（.bmp）やポータブルピクセルマップビットマップ（.ppm）P6形式以外のテクスチャのサポートをインプリメントするため、このコールバック関数を使用することができる。P6フォーマットは、色イメージのバイナリファイルフォーマットである。

システムは、コールバック関数を使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を使う。

参照

IDirect3DRM3::Load, IDirect3DRMAnimationSet2::Load, IDirect3DRMFrame3::Load, IDirect3DRMMeshBuilder3::Load

D3DRMOBJECTCALLBACK

IDirect3DRM3::EnumerateObjectsメソッドの呼び出しに応答するオブジェクトを列挙する。このコールバック関数の実体はアプリケーション定義である。

構文

void (*D3DRMOBJECTCALLBACK)(
  LPDIRECT3DRMOBJECT lpD3DRMobj,
  LPVOID lpArg);

パラメータ

lpD3DRMobj
オブジェクトを列挙するIDirect3DRMObjectインターフェイスへのポインタ。アプリケーションは、列挙された各オブジェクトについてReleaseメソッドを呼び出さなくてはならない。
lpArg
コールバック関数に渡されるアプリケーション定義のデータへのポインタのアドレス。

戻り値

なし。

注意

システムは、コールバック関数を使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を使う。

参照

IDirect3DRM3::EnumerateObjects

D3DRMUSERVISUALCALLBACK

ユーザビジュアルオブジェクトを提供するアプリケーションに、実行バッファを実行する必要があることを通知する。このコールバック関数の実体はアプリケーション定義である。

構文

int (*D3DRMUSERVISUALCALLBACK)(
  LPDIRECT3DRMUSERVISUAL lpD3DRMUV,
  LPVOID lpArg,
  D3DRMUSERVISUALREASON lpD3DRMUVreason,
  LPDIRECT3DRMDEVICE lpD3DRMDev,
  LPDIRECT3DRMVIEWPORT lpD3DRMview);

パラメータ

lpD3DRMUV
Direct3DRMUserVisualオブジェクトへのポインタのアドレス。
lpArg
コールバック関数に渡されるアプリケーション定義のデータへのポインタのアドレス。
lpD3DRMUVreason
D3DRMUSERVISUALREASON列挙型のメンバの1つ。
D3DRMUSERVISUAL_CANSEE
ユーザビジュアルオブジェクトがビューポート内で可視状態であれば、アプリケーションはTRUEを返す。この場合、アプリケーションは、lpD3DRMviewパラメータで指定されたデバイスを使用する。
D3DRMUSERVISUAL_RENDER
アプリケーションは、ユーザビジュアルエレメントをレンダリングしなくてはならない。この場合、アプリケーションは、lpD3DRMDevパラメータで指定されたデバイスを使う。
lpD3DRMDev
Direct3DRMUserVisualオブジェクトをレンダリングするために使われるDirect3DRMDeviceオブジェクトへのポインタのアドレス。
lpD3DRMview
Direct3DRMUserVisualオブジェクトが可視状態かどうかを決定するために使われるDirect3DRMViewportオブジェクトへのポインタのアドレス。

戻り値

lpD3DRMUVreasonパラメータにD3DRMUSERVISUAL_CANSEEが指定され、ユーザビジュアルオブジェクトがビューポート内で可視状態の場合はTRUEを返す。そうでない場合はFALSEを返す。lpD3DRMUVreasonパラメータにD3DRMUSERVISUAL_RENDERが指定されている場合はアプリケーション定義の戻り値となる。この場合、つねにTRUEを返すのが安全である。

注意

アプリケーションがレンダリング状態を変更する場合、この関数から復帰する前にレンダリング状態を復元する必要がある。

システムは、コールバック関数を使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバック関数を使う。

参照

IDirect3DRMUserVisual::Init, IDirect3DRM3::CreateUserVisual

D3DRMVALIDATIONCALLBACK

変更済であるが更新されていないことを意味する、無効のマークが付けられたテクスチャリージョンを更新する必要があるときに呼び出される。このコールバック関数の実体はアプリケーションで定義される。

構文

HRESULT (*D3DRMVALIDATIONCALLBACK)(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  LPVOID lpArg,
  DWORD dwFlags,
  DWORD dwcRects,
  LPRECT pRects);

パラメータ

lpDirect3DRMTexture
コールバック関数を適用するDirect3DRMTexture3オブジェクトへのポインタのアドレス。
lpArg
コールバック関数に渡されるアプリケーション定義のデータへのポインタのアドレス。
dwFlags
使わない。0にすること
dwcRects
pRectsパラメータに指定された矩形の数。
pRects
更新される領域を表す、1つ以上のRECT構造体の配列。座標はデバイス単位で指定される。

戻り値

なし。

注意

Direct3D保持モードに対して、テクスチャリージョンの変更を通知するが、その変更を保留する場合、リージョンは無効であると宣言し、リージョンをpRectsが指す配列に格納することができる。その後、テクスチャが必要になれば、このコールバック関数を呼び出し、アプリケーションにテクスチャリージョンを更新することを通知する。

D3DRMVALIDATIONCALLBACKは、DirectX version 6.0とともに導入された。

参照

IDirect3DRMTexture3::SetValidationCallback

D3DRMWRAPCALLBACK

このコールバック関数はサポートされていない。

構文

void (*D3DRMWRAPCALLBACK)(
  LPD3DVECTOR lpD3DVector,
  int *lpU,
  int *lpV,
  LPD3DVECTOR lpD3DRMVA,
  LPD3DVECTOR lpD3DRMVB,
  LPVOID lpArg);


C++インターフェイス

この項には、次のMicrosoft® Direct3D®保持モードのC++インターフェイスに関する情報が含まれる。

  • IDirect3DRM3
  • IDirect3DRMAnimation2
  • IDirect3DRMAnimationArray
  • IDirect3DRMAnimationSet2
  • IDirect3DRMArray
  • IDirect3DRMClippedVisual
  • IDirect3DRMDevice3
  • IDirect3DRMDeviceArray
  • IDirect3DRMFace2
  • IDirect3DRMFaceArray
  • IDirect3DRMFrame3
  • IDirect3DRMFrameArray
  • IDirect3DRMInterpolator
  • IDirect3DRMLight
  • IDirect3DRMLightArray
  • IDirect3DRMMaterial2
  • IDirect3DRMMesh
  • IDirect3DRMMeshBuilder3
  • IDirect3DRMObject
  • IDirect3DRMObject2
  • IDirect3DRMObjectArray
  • IDirect3DRMPicked2Array
  • IDirect3DRMPickedArray
  • IDirect3DRMProgressiveMesh
  • IDirect3DRMShadow2
  • IDirect3DRMTexture3
  • IDirect3DRMUserVisual
  • IDirect3DRMViewport2
  • IDirect3DRMViewportArray
  • IDirect3DRMVisual
  • IDirect3DRMVisualArray
  • IDirect3DRMWinDevice
  • IDirect3DRMWrap


IDirect3DRM3

アプリケーションは、IDirect3DRM3インターフェイスを使用してDirect3DRM3オブジェクトを生成し、システムレベル変数に従って動作する。Direct3D保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRM3、IDirect3DRM2、およびIDirect3DRMインターフェイスのメソッドは、次のオブジェクトを作成する。

  • アニメーションとアニメーションセット
  • クリップビジュアル
  • デバイス
  • 面
  • フレーム
  • 汎非初期化オブジェクト
  • 照明
  • マテリアル
  • メッシュとメッシュビルダ
  • 影
  • テクスチャ
  • ユーザビジュアル
  • ビューポート
  • ラップ

Microsoft DirectX version 6.0は、IDirect3DRM3インターフェイスを導入している。IDirect3DRM3は、IDirect3DRM2とIDirect3DRMインターフェイスが提供するすべてのメソッドをサポートし、これら2つの旧インターフェイスを置換する。これは、フラグパラメータをIDirect3DRM2のCreateDeviceFromSurfaceに追加し、RegisterClient、UnregisterClientおよびCreateClippedVisualメソッドをIDirect3DRM2が提供するメソッドに追加する。IDirect3DRM3は、左手または右手ジオメトリのどちらを使用するかをセットし取り出すGetOptionsとSetOptionsメソッドも追加する。

IDirect3DRM3は、IDirect3DRM2と同様にIDirect3DRM中のすべてのメソッドをサポートする。これは、CreateProgressiveMeshメソッドをIDirect3DRMが提供するメソッドに追加する。CreateDeviceFromSurface、CreateDeviceFromD3DおよびCreateDeviceFromClipperメソッドはすべて、IDirect3DRM2によって DIRECT3DRMDEVICE2オブジェクトを作成し、IDirect3DRM3によって DIRECT3DRMDEVICE3オブジェクトを作成する。CreateViewportメソッドは、DirectDRMDevice2オブジェクト上にビューポートを作成する。LoadTextureとLoadTextureFromResourceメソッドは、IDirect3DRM2によって Direct3DRMTexture2オブジェクトをロードし、IDirect3DRM3によって Direct3DRMTexture3オブジェクトをロードする。

IDirect3DRM3またはIDirect3DRM2 COM (Component Object Model) インターフェイスにアクセスするには、Direct3DRMCreateによってIDirect3DRMオブジェクトを作成し、次にIDirect3DRMからそれぞれIDirect3DRM3またはIDirect3DRM2を照会する。また、CoCreateInstanceを直接使用してメインのDirect3D保持モードオブジェクトにアクセスすることができる。

IDirect3DRM3インターフェイスを使用して MeshBuilderオブジェクトを作成すると、MeshBuilderは、そのインプリメンテーションに直接モードのDrawPrimitiveインターフェイスを使用する。

IDirect3DRM3インターフェイスを使用して照明を作成すると、照明は最新の直接モード機能を活用し、D3DLIGHT2構造体を使用することになる。

アプリケーションはIDirect3DRMDevice3、IDirect3DRMDevice2、IDirect3DRMDeviceインターフェイスを使用して出力デバイスと会話する。IDirect3DRM3、IDirect3DRM2またはIDirect3DRMインターフェイスを使用して作成する際の出力デバイス機能の詳細については、「IDirect3DRMDevice3」を参照すること。出力デバイスの概要については、「出力デバイス」を参照すること。

IDirect3DRM3インターフェイスのメソッドは、以下のグループにまとめることができる。
アニメーション | CreateAnimation
 | CreateAnimationSet
アプリケーション固有のデータ | RegisterClient
 | UnregisterClient
クリップビジュアル | CreateClippedVisual
デバイス | CreateDevice
 | CreateDeviceFromClipper
 | CreateDeviceFromD3D
 | CreateDeviceFromSurface
 | GetDevices
列挙 | EnumerateObjects
面 | CreateFace
フレーム | CreateFrame
照明 | CreateLight
 | CreateLightRGB
マテリアル | CreateMaterial
メッシュ | CreateMesh
 | CreateMeshBuilder
その他 | CreateObject
 | CreateUserVisual
 | GetNamedObject
 | GetOptions
 | Load
 | SetOptions
 | Tick
プログレッシブメッシュ | CreateProgressiveMesh
パス検索 | AddSearchPath
 | GetSearchPath
 | SetSearchPath
影 | CreateShadow
テクスチャ | CreateTexture
 | CreateTextureFromSurface
 | LoadTexture
 | LoadTextureFromResource
 | SetDefaultTextureColors
 | SetDefaultTextureShades
ビューポート | CreateViewport
ラップ | CreateWrap

すべてのCOMインターフェイスと同様、IDirect3DRM3インターフェイスは、IUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは次の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

IDirect3DRM3::AddSearchPath

IDirect3DRM3

現在のファイル検索パスの最後にディレクトリのリストを追加する。

構文

HRESULT AddSearchPath(
  LPCSTR lpPath
  );

パラメータ

lpPath
現在の検索パスに追加するパスを指定するヌル終端文字列のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

Microsoft® Windows®では、パスは、セミコロン(;)で区切られたリストにする必要がある。

参照

IDirect3DRM3::SetSearchPath

IDirect3DRM3::CreateAnimation

IDirect3DRM3

空のDirect3DRMAnimationオブジェクトを生成する。

構文

HRESULT CreateAnimation(
  LPDIRECT3DRMANIMATION2  *lplpD3DRMAnimation
  );

パラメータ

lplpD3DRMAnimation
呼び出しが成功した場合、IDirect3DRMAnimation2インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::CreateAnimationSet

IDirect3DRM3

空のDirect3DRMAnimationSetオブジェクトを作成する。

構文

HRESULT CreateAnimationSet (
  LPDIRECT3DRMANIMATIONSET2  *lplpD3DRMAnimationSet
  );

パラメータ

lplpD3DRMAnimationSet
呼び出しが成功すれば、IDirect3DRMAnimationSet2インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::CreateClippedVisual

IDirect3DRM3

クリップビジュアルオブジェクトを作成する。

構文

HRESULT CreateClippedVisual(
  LPDIRECT3DRMVISUAL lpVisual,
  LPDIRECT3DRMCLIPPEDVISUAL  *lpClippedVisual);

パラメータ

lpVisual
メッシュビルダオブジェクトなどのビジュアルオブジェクトへのポインタ。
lpClippedVisual
作成されたIDirect3DRMClippedVisualクリップビジュアルオブジェクトを受け取るポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRM3::CreateDevice

IDirect3DRM3

Windowsプラットフォームでは未実装である。

構文

HRESULT CreateDevice(
  DWORD dwWidth,
  DWORD dwHeight,
  LPDIRECT3DRMDEVICE3 *lplpD3DRMDevice
  );

IDirect3DRM3::CreateDeviceFromClipper

IDirect3DRM3

指定されたDirectDrawClipperオブジェクトを使用してDirect3D保持モードWindowsデバイスを生成する。

構文

HRESULT CreateDeviceFromClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper,
  LPGUID lpGUID,
  int width,
  int height,
  LPDIRECT3DRMDEVICE3  *lplpD3DRMDevice
  );

パラメータ

lpDDClipper
DirectDrawClipperオブジェクトのアドレス。
lpGUID
グローバルユニーク識別子(GUID)のアドレス。このパラメータはNULLにできる。
width, height
作成すべきデバイスの幅と高さ。
lplpD3DRMDevice
呼び出しが成功した場合、IDirect3DRMDevice3インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

lpGUIDパラメータがNULLの場合、システムは、デバイス性能のデフォルトセットを検索する。これは、保持モードデバイスを生成する方法として推奨する。なぜなら、ユーザが新しいハードウェアをインストールした場合でも、常に機能するからである。

システムは、内部デバイス列挙の呼び出しで、D3DPRIMCAPS構造体からの以下のフラグを使用して、デフォルト設定値を記述する。
D3DPSHADECAPS_ALPHAFLATSTIPPLED
D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE
D3DPMISCCAPS_CULLCCW
D3DPRASTERCAPS_FOGVERTEX
D3DPCMPCAPS_LESSEQUAL
D3DPTFILTERCAPS_NEAREST
D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY
D3DPTADDRESSCAPS_WRAP

ハードウェアデイバスが検出されなかった場合には、モノクロ(ランプ)のソフトウェアドライバがロードされる。特別な要件があって、デフォルト設定値のこのリストでは満足できない場合、アプリケーションは、lpGUIDに対してNULLを指定する代わりにデバイスを列挙する必要がある。

デバイスについての詳細は、「出力デバイス」および「IDirect3DRMDevice3」を参照すること。

IDirect3DRM3::CreateDeviceFromD3D

IDirect3DRM3

指定されたDirect3Dオブジェクトを使用して、Direct3D保持モードWindowsデバイスを生成する。

構文

HRESULT CreateDeviceFromD3D(
  LPDIRECT3D2 lpD3D,
  LPDIRECT3DDEVICE2 lpD3DDev,
  LPDIRECT3DRMDEVICE3  *lplpD3DRMDevice
  );

パラメータ

lpD3D
Direct3D直接モードDirect3D2オブジェクトのインスタンスへのポインタ。
lpD3DDev
Direct3D直接モードDirect3DDevice2オブジェクトへのポインタ。
lplpD3DRMDevice
呼び出しが成功した場合、IDirect3DRMDevice3インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デバイスについての詳細は、「出力デバイス」および「IDirect3DRMDevice3」を参照すること。

IDirect3DRM3::CreateDeviceFromSurface

IDirect3DRM3

指定されたDirectDrawサーフェスからレンダリングするためのDirect3D保持モードWindowsデバイスを生成する。

構文

HRESULT CreateDeviceFromSurface(
  LPGUID lpGUID,
  LPDIRECTDRAW lpDD,
  LPDIRECTDRAWSURFACE lpDDSBack,
  DWORD dwFlags,
  LPDIRECT3DRMDEVICE3 *lplpD3DRMDevice);

パラメータ

lpGUID
要求されたデバイスドライバとして使用されるグローバルユニーク識別子(GUID)のアドレス。このパラメータがNULLの場合、デフォルトのデバイスドライバが使用される。
lpDD
DirectDrawサーフェスのソースであるDirectDrawオブジェクトのアドレス。
lpDDSBack
バックバッファを表すDirectDrawSurfaceオブジェクトのアドレス。
dwFlags
現在定義されている唯一のフラグは、次の通りである。
D3DRMDEVICE_NOZBUFFER
lpDDSBackパラメータにzバッファがアタッチされていなければ、zバッファが作成されないことを示す。デフォルトでは、zバッファが作成される。
lplpD3DRMDevice
呼び出しが成功した場合、IDirect3DRMDevice3インターフェイスへのポインタがセットされるアドレス。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。このメソッドは、dwFlagsパラメータを、それが置換する旧のIDirect3DRM2::CreateDeviceFromSurfaceメソッドに追加する。

デバイスについての詳細は、「出力デバイス」および「IDirect3DRMDevice3」を参照すること。

IDirect3DRM3::CreateFace

IDirect3DRM3

IDirect3DRMFace2インターフェイスのインスタンスを生成する。

構文

HRESULT CreateFace(
  LPDIRECT3DRMFACE2  *lplpd3drmFace2
  );

パラメータ

lplpd3drmFace2
呼び出しが成功した場合、IDirect3DRMFace2インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::CreateFrame

IDirect3DRM3

指定の親フレームの新しい子フレーム (Direct3DRMFrame3オブジェクト) を生成する。

構文

HRESULT CreateFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame,
  LPDIRECT3DRMFRAME3 *lplpD3DRMFrame
  );

パラメータ

lpD3DRMFrame
新しいフレームの親となるIDirect3DRMFrame3オブジェクトのアドレス。
lplpD3DRMFrame
呼び出しが成功した場合、IDirect3DRMFrame3インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

子フレームは、その親から運動属性を継承する。たとえば、親が一定の速度で動いているときには、子フレームも同じ速度で動く。さらに、親に回転がセットされると、子フレームは、親の原点の周囲を回転する。親を持たないフレームは、シーンと呼ばれる。シーンを作成するには、親としてNULLを指定する。アプリケーションは、親のないフレームを作成した後、IDirect3DRMFrame3::AddChildメソッドを使用して、後で親フレームに関連させることができる。

アプリケーションが右手ジオメトリをセットするためにIDirect3DRM3::SetOptionsを呼び出した場合、ルートフレーム (親として NULLを持つフレーム) のデフォルト軸は、v = (0, 0, -1) かつ u = (0, 1, 0) になる。このため、IDirect3DRMFrame3::GetOrientationとIDirect3DRMFrame3::SetOrientationは、右手モードで正しく機能する。

参照

IDirect3DRMFrame3::AddChild

IDirect3DRM3::CreateLight

IDirect3DRM3

指定のタイプと色で、新しい照明を作成する。

構文

HRESULT CreateLight(
  D3DRMLIGHTTYPE d3drmltLightType,
  D3DCOLOR cColor,
  LPDIRECT3DRMLIGHT *lplpD3DRMLight
  );

パラメータ

d3drmltLightType
D3DRMLIGHTTYPE列挙型で与えられる照明タイプの1つ。
cColor
照明の色。
lplpD3DRMLight
呼び出しが成功した場合、IDirect3DRMLightインターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::CreateLightRGB

IDirect3DRM3

指定のタイプと色で、新しい照明を作成する。

構文

HRESULT CreateLightRGB(
  D3DRMLIGHTTYPE ltLightType,
  D3DVALUE vRed,
  D3DVALUE vGreen,
  D3DVALUE vBlue,
  LPDIRECT3DRMLIGHT *lplpD3DRMLight
  );

パラメータ

ltLightType
D3DRMLIGHTTYPE列挙型で与えられる照明タイプの1つ。
vRed, vGreen, vBlue
照明の色。色の各要素は、0.0から1.0の範囲にある必要がある。
lplpD3DRMLight
呼び出しが成功した場合、IDirect3DRMLightインターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

次のコード部分は、CreateLightRGBを呼び出して明るいディレクショナル照明を作成する。これは、Direct3DRMCreate関数を使用してすでにDirect3D保持モードオブジェクトが作成されていることを前提としている。

LPDIRECT3DRM3 lpD3DRM;
LPDIRECT3DRMLIGHT light;

if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_DIRECTIONAL,
                                   D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9),
                                   &light))
{
    // エラー
}

IDirect3DRM3::CreateMaterial

IDirect3DRM3

指定の反射プロパティを持つマテリアルを作成する。

構文

HRESULT CreateMaterial(
  D3DVALUE vPower,
  LPDIRECT3DRMMATERIAL2  *lplpD3DRMMaterial
  );

パラメータ

vPower
反射するハイライトの鋭さ。レンダリングする表面に、5の値は金属の外観を与え、より大きい値はよりプラスチック的な外観を与える。
lplpD3DRMMaterial
呼び出しが成功した場合、IDirect3DRMMaterial2インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::CreateMesh

IDirect3DRM3

面をもたない新しいメッシュオブジェクトを生成する。このメッシュは、フレームに追加されるまでは目に見えない。

構文

HRESULT CreateMesh(
  LPDIRECT3DRMMESH *lplpD3DRMMesh
  );

パラメータ

lplpD3DRMMesh
呼び出しが成功した場合、IDirect3DRMMeshインターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::CreateMeshBuilder

IDirect3DRM3

新しいメッシュビルダオブジェクトを生成する。

構文

HRESULT CreateMeshBuilder(
  LPDIRECT3DRMMESHBUILDER3  *lplpD3DRMMeshBuilder3
  );

パラメータ

lplpD3DRMMeshBuilder3
呼び出しが成功した場合、IDirect3DRMMeshBuilder3インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デフォルトでは、パースペクティブ補正がオンである。

IDirect3DRM3::CreateObject

IDirect3DRM3

オブジェクトを初期化することなく新しいオブジェクトを生成する。

構文

HRESULT CreateObject(
  REFCLSID rclsid,
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID FAR *ppv
  );

パラメータ

rclsid
新しいオブジェクトのクラス識別子。
pUnkOuter
COM集合化を可能にする外部IUnknownインターフェイスへのポインタ。
riid
作成するオブジェクトのインターフェイス識別子。
ppv
メソッドが戻ったときのオブジェクトへのポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドを呼び出したアプリケーションが生成したオブジェクトの初期化を行わなければならない（他のIDirect3DRM3インターフェイスの生成メソッドは、自動的にオブジェクトの初期化を行う）。ある場合、たとえば、Direct3DRMViewport2オブジェクトに関するそのオブジェクトに、Initメソッドを使用することができる。アプリケーションは、任意のオブジェクトを初期化するのにInitメソッドを呼び出すのは一度限りにする必要がある。

アプリケーションは、このメソッドを使用してDirect3DRMオブジェクトの集合体を実装することができる。

IDirect3DRM3::CreateProgressiveMesh

IDirect3DRM3

面をもたない新しいプログレッシブメッシュオブジェクトを生成する。メッシュは、フレームに追加されるまで目に見えない。

構文

HRESULT CreateProgressiveMesh(
  LPDIRECT3DRMPROGRESSIVEMESH *lplpD3DRMProgressiveMesh
  );

パラメータ

lplpD3DRMProgressiveMesh
呼び出しが成功した場合、IDirect3DRMProgressiveMeshインターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::CreateShadow

IDirect3DRM3

指定のビジュアルと照明を使用して影を作成し、指定の平面にその影を投影する。影も一種のビジュアルであり、ビジュアルを含むフレームに追加する必要がある。

構文

HRESULT CreateShadow(
  LPUNKNOWN pUnk,
  LPDIRECT3DRMLIGHT lpLight,
  D3DVALUE px,
  D3DVALUE py,
  D3DVALUE pz,
  D3DVALUE nx,
  D3DVALUE ny,
  D3DVALUE nz,
  LPDIRECT3DRMSHADOW2  *lplpShadow
  );

パラメータ

pUnk
影を投影するオブジェクトのアドレス。
lpLight
照明であるIDirect3DRMLightインターフェイスのアドレス。
px, py, pz
影が投影される平面。
nx, ny, nz
影が投影される平面に対する法線。
lplpShadow
呼び出しが成功した場合、影ビジュアルに対する有効なポインタで初期化されるポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::CreateTexture

IDirect3DRM3

メモリのイメージからテクスチャを作成する。

構文

HRESULT CreateTexture(
  LPD3DRMIMAGE lpImage,
  LPDIRECT3DRMTEXTURE3 *lplpD3DRMTexture3
  );

パラメータ

lpImage
テクスチャのソースを記述するD3DRMIMAGE構造体のアドレス。
lplpD3DRMTexture3
呼び出しが成功した場合、IDirect3DRMTexture3インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

イメージに関連するメモリは、Direct3D保持モードのバッファにコピーされるのではなく、テクスチャがレンダリングされるたびに使用される。これは、イメージがレンダリング対象およびテクスチャの両方として使用されることを可能にする。

IDirect3DRM3::CreateTextureFromSurface

IDirect3DRM3

指定したDirectDrawサーフェスからテクスチャを作成する。

構文

HRESULT CreateTextureFromSurface(
  LPDIRECTDRAWSURFACE lpDDS,
  LPDIRECT3DRMTEXTURE3  *lplpD3DRMTexture3
  );

パラメータ

lpDDS
テクスチャを格納するDirectDrawSurfaceオブジェクトのアドレス。
lplpD3DRMTexture3
呼び出しが成功した場合、IDirect3DRMTexture3インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

DirectDrawサーフェスからテクスチャを作成する場合、システムメモリ中にサーフェスを作成するのが最善である。これでソフトウェアデバイスの最適なパフォーマンスが可能になり、Direct3D保持モードがハードウェアデバイスに対してビデオメモリの使用をより効率的に管理できるようになる。

IDirect3DRM3::CreateUserVisual

IDirect3DRM3

アプリケーション定義のビジュアルオブジェクトを生成する。作成されたオブジェクトは、アプリケーション定義ハンドラを使用してシーンに追加したり、レンダリングしたりすることができる。

構文

HRESULT CreateUserVisual(
  D3DRMUSERVISUALCALLBACK fn,
  LPVOID lpArg,
  LPDIRECT3DRMUSERVISUAL  *lplpD3DRMUV
  );

パラメータ

fn
アプリケーション定義D3DRMUSERVISUALCALLBACKコールバック関数。

lpArg
コールバック関数に渡されたアプリケーション定義データのアドレス。
lplpD3DRMUV
呼び出しが成功した場合、IDirect3DRMUserVisualインターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMUserVisual::Init

IDirect3DRM3::CreateViewport

IDirect3DRM3

デバイス座標が(dwXPos, dwYPos)から(dwXPos + dwWidth, dwYPos + dwHeight)までのデバイス上で、ビューポートを作成する。

構文

HRESULT CreateViewport(
  LPDIRECT3DRMDEVICE3 lpDev,
  LPDIRECT3DRMFRAME3 lpCamera,
  DWORD dwXPos,
  DWORD dwYPos,
  DWORD dwWidth,
  DWORD dwHeight,
  LPDIRECT3DRMVIEWPORT2 *lplpD3DRMViewport
  );

パラメータ

lpDev
作成するビューポートが存在するIDirect3DRMDevice3デバイスのアドレス。
lpCamera
ビューの位置と方向を記述するフレームのアドレス。
dwXPos, dwYPos, dwWidth, dwHeight
デバイス座標でのビューポートの位置とサイズ。ビューポートサイズは物理デバイスより大きくできない。大きくすると、メソッドは失敗に終わる。
lplpD3DRMViewport
呼び出しが成功した場合、IDirect3DRMViewport2インターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。ビューポートサイズが物理デバイスより大きければ、D3DRMERR_BADVALUEを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

ビューポートは、カメラを含むシーンの中で、カメラから取ったビュー方向とアップベクトルを使用してオブジェクトを表示する。ビューポートサイズは、物理デバイスよりも大きくできない。

デバイスに関する詳細は、「出力デバイス」と「IDirect3DRMDevice3」を参照すること。

IDirect3DRM3::CreateWrap

IDirect3DRM3

面とメッシュにテクスチャ座標を割り当てるのに使用できるラッピング関数を作成する。ベクトル[ox oy oz]は、ラップの原点を[dx dy dz]はラップのz軸を、[ux uy uz]はラップのy軸をそれぞれ与える。2Dベクトルの[ou ov]と[su sv]は、ラッピング関数の結果に適用されるテクスチャの原点とスケールファクタを与える。

構文

HRESULT CreateWrap(
  D3DRMWRAPTYPE type,
  LPDIRECT3DRMFRAME3 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
  );

パラメータ

type
D3DRMWRAPTYPE列挙型のメンバの1つ。
lpRef
ラップの参照フレーム。
ox, oy, oz
ラップの原点。
dx, dy, dz
ラップのz軸。
ux, uy, uz
ラップのy軸。
ou, ov
テクスチャの原点。
su, sv
テクスチャのスケールファクタ。
lplpD3DRMWrap
呼び出しが成功した場合、IDirect3DRMWrapインターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMWrap

IDirect3DRM3::EnumerateObjects

IDirect3DRM3

各Direct3DRMオブジェクトのfuncパラメータによって指定されるコールバック関数を使用する。

構文

HRESULT EnumerateObjects(
  D3DRMOBJECTCALLBACK func,
  LPVOID lpArg
  );

パラメータ

func
各Direct3DRMObjectオブジェクトおよびアプリケーション定義引数によって使われるアプリケーション定義のD3DRMOBJECTCALLBACKコールバック関数。
lpArg
コールバック関数に渡されたアプリケーション定義データのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::GetDevices

IDirect3DRM3

システムで作成されたすべてのDirect3DRMデバイスを返す。

構文

HRESULT GetDevices(
  LPDIRECT3DRMDEVICEARRAY *lplpDevArray
  );

パラメータ

lplpDevArray
Direct3DRMデバイスの結果の配列がセットされるポインタのアドレス。Direct3DRMDeviceArrayオブジェクトの詳細については、「IDirect3DRMDeviceArray」を参照すること。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::GetNamedObject

IDirect3DRM3

指定の名前でDirect3DRMObjectを取得する。

構文

HRESULT GetNamedObject(
  const char  *lpName,
  LPDIRECT3DRMOBJECT *lplpD3DRMObject
  );

パラメータ

lpName
検索するオブジェクトの名前。
lplpD3DRMObject
呼び出しが成功した場合に、有効なDirect3DRMObjectポインタで初期化されるポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

システムがlpNameパラメータで指定した名前のオブジェクトを発見しなかった場合に、このメソッドは、D3DRM_OKを返すが、lplpD3DRMObjectパラメータはNULLとなる。

IDirect3DRM3::GetOptions

IDirect3DRM3

Direct3D保持モードで左手または右手ジオメトリのどちらを使用するかを引き出す。

構文

HRESULT GetOptions(
  LPDWORD lpdwOptions);

パラメータ

lpdwOptions
現在のDirect3D保持モードオプションを示すフラグ値へのポインタ。現在定義されているフラグは、次の通りである。
D3DRMOPTIONS_LEFTHANDED
左手ジオメトリを使用する。これはデフォルト値である。
D3DRMOPTIONS_RIGHTHANDED
右手ジオメトリを使用する。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

D3DRMOPTIONS_LEFTHANDEDとD3DRMOPTIONS_RIGHTHANDEDは、ピッキングと光線ピッキングはもちろんのこと、次のオブジェクトにも影響を与える。

  • IDirect3DRMClippedVisual
  • IDirect3DRMMesh
  • IDirect3DRMMeshBuilder3
  • IDirect3DRMProgressiveMesh
  • IDirect3DRMShadow2
  • IDirect3DRMTexture3
  • IDirect3DRMViewport2

このメソッドは、DirectX version 6.0で導入された。

参照

「Direct3Dの座標系 」

IDirect3DRM3::SetOptions

IDirect3DRM3::GetSearchPath

IDirect3DRM3

現在の検索パスを返す。Windowsでは、パスは、セミコロン(;)で区切られたディレクトリのリストである。

構文

HRESULT GetSearchPath(
  DWORD  *lpdwSize,
  LPSTR lpszPath
  );

パラメータ

lpdwSize
DWORD値へのポインタ。GetSearchPathが使われたとき、lpszPathの長さを含む必要がある。戻ったときには、現在の検索パスを含むlpszPathの文字列の長さを格納する。このパラメータはNULLにできない。
lpszPath
検索パスを指定するヌル終端の文字列へのポインタ。GetSearchPathが使われたとき、lpszPathがNULLの場合、このメソッドは、lpdwSizeパラメータが指す位置にある現在の文字列の長さを返す。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRM3::SetSearchPath

IDirect3DRM3::Load

IDirect3DRM3

オブジェクトをロードする。

構文

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  LPIID  *lplpGUIDs,
  DWORD dwcGUIDs,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADCALLBACK d3drmLoadProc,
  LPVOID lpArgLP,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP,
  LPDIRECT3DRMFRAME3 lpParentFrame
  );

パラメータ

lpvObjSource
ロードするオブジェクトのソース。このソースは、d3drmLOFlagsパラメータで指定されたソースフラグに従って、ファイル、リソース、メモリブロック、またはストリームにすることができる。
lpvObjID
ロードするオブジェクトの名前または位置。このパラメータの使用は、d3drmLOFlagsパラメータで指定されている識別フラグに依存する。D3DRMLOAD_BYPOSITIONフラグが指定されていれば、このパラメータは、ファイル中のオブジェクトの順を与えるDWORD値へのポインタとなる。このパラメータはNULLにできる。
lplpGUIDs
ロードするインターフェイス識別子の配列のアドレス。たとえば、このパラメータがIID_IDirect3DRMMeshBuilder3およびIID_IDirect3DRMAnimationSet2を格納する2つの要素の配列であれば、このメソッドは、すべてのアニメーションセットオブジェクトとメッシュビルダオブジェクトをロードする。可能なGUIDは、IID_IDirect3DRMProgressiveMesh、IID_IDirect3DRMMeshBuilder3、IID_IDirect3DRMAnimationSet2、IID_IDirect3DRMAnimation2、およびIID_IDirect3DRMFrame3の中の1つ以上でなければならない。
dwcGUIDs
lplpGUIDsパラメータで指定されている要素の数。
d3drmLOFlags
ロードオプションを記述するD3DRMLOADOPTIONS型の値。
d3drmLoadProc
システムが指定のオブジェクトを読み込んだときに使われるD3DRMLOAD3CALLBACKコールバック関数。
lpArgLP
D3DRMLOADCALLBACKコールバック関数に渡されるアプリケーション定義データのアドレス。
d3drmLoadTextureProc
D3DRMLOADTEXTURE3CALLBACKコールバック関数。これは、特別なフォーマットを必要とするオブジェクトが用いるテクスチャを読み出すときに呼び出される。このパラメータにはNULLを指定することができる。
lpArgLTP
D3DRMLOADTEXTURE3CALLBACKコールバック関数に渡されるアプリケーション定義データのアドレス。
lpParentFrame
親Direct3DRMFrameオブジェクトのアドレス。この引数は、アニメーションセットのロードだけに影響する。Xファイルからロードされたアニメーションが、Xファイル中の親のないフレームを参照するときは、その親には、lpParentFramがセットされる。ただし、Xファイル中の任意のフレームをロードするように、Loadを使った場合には、lpParentFrameは、親のないXファイル中のフレームに対する親フレームとして使用されることはない。すなわち、lpParentFrameは、アニメーションセットをロードしたときに限り使用される。lpParentFrameの値はNULLにすることができる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デフォルトでは、パースペクティブ補正がオンである。

このメソッドによって、Microsoft® DirectX® ファイルからのオブジェクトのロードが極めて柔軟に行えるようになる。次にその使用法の例を示す。

サンプルコード

#include <windows.h>
#include <stdio.h>
#include <initguid.h>
#include <d3drm.h>

LPDIRECT3DRM d3dApi;

int totalMesh = 0, totalAnim = 0, totalFrames = 0;

HRESULT loadTexture(LPSTR name, LPVOID lpArg, LPDIRECT3DRMTEXTURE *tex)
{
    return d3dApi->lpVtbl->LoadTexture(d3dApi, name, tex);
}

void loadCallback(LPDIRECT3DRMOBJECT lpObject, REFIID objGuid, LPVOID lpArg)
{
    if (IsEqualIID(objGuid, &IID_IDirect3DRMFrame3)) {
        totalFrames ++;
        return;
    }

    if (IsEqualIID(objGuid, &IID_IDirect3DRMAnimationSet2)) {
        totalAnim ++;
        return;
    }

    if (IsEqualIID(objGuid, &IID_IDirect3DRMMeshBuilder)) {
        totalMesh ++;
        return;
    }

    return;
}

BOOL loadObjects(LPSTR filename)
{
    LPGUID guids[] = { (LPGUID)&IID_IDirect3DRMMeshBuilder,
        (LPGUID)&IID_IDirect3DRMAnimationSet2,
        (LPGUID)&IID_IDirect3DRMFrame3 };

    /* ローダにどのオブジェクトを対象とするかを告げる */

    if (FAILED(d3dApi->lpVtbl->Load(d3dApi, filename, NULL,
            guids, 3, D3DRMLOAD_FROMFILE,
            loadCallback, NULL, loadTexture, NULL, NULL)))
        return FALSE;

    printf("Total Frames loaded = %d\n", totalFrames);
    printf("Total Animation Sets loaded = %d\n", totalAnim);
    printf("Total Meshbuilders loaded = %d\n", totalMesh);

    return TRUE;
}

int main(int argc, char **argv)
{

    if (FAILED(Direct3DRMCreate(&d3dApi)))
        return FALSE;

    if (argc != 2) {
        fprintf(stderr, "usage: %s filename\n", argv[0]);
        return FALSE;
    }

    if (!loadObjects(argv[1])) return FALSE;

  return(0);
}

IDirect3DRM3::LoadTexture

IDirect3DRM3

指定ファイルからDirect3DRMTexture2テクスチャをロードする。このテクスチャは、8、24、または32ビット/ピクセルをとることができる。そのフォーマットは、Windows ビットマップ (.bmp) かPortable Pixmap (.ppm) P6フォーマットのどちらかにする必要がある。

構文

HRESULT LoadTexture(
  const char  *lpFileName,
  LPDIRECT3DRMTEXTURE3 *lplpD3DRMTexture
  );

パラメータ

lpFileName
必要な.bmpまたは.ppmファイルの名前のアドレス。
lplpD3DRMTexture
この呼び出しが成功した場合に、有効なIDirect3DRMTexture3ポインタで初期化されるポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

LoadTextureは、テクスチャがBMPフォーマットであるかPPMフォーマットであるかをチェックする。LoadTextureは、両フォーマットをロードすることができる。その他のフォーマットをロードするには、D3DRMIMAGE構造体へのイメージロード用のコードをコールバック関数に追加し、それからIDirect3DRM3::CreateTextureを使う。

独自のテクスチャコールバック関数を書くとき、テクスチャコールバック関数のLoadTexture呼び出しはテクスチャへの参照を受け取らない。たとえば、

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE2 *tex)
{
    return lpD3DRM2->LoadTexture(name, tex);
}

この例で、texの参照を受け取ることはできない。テクスチャコールバック関数でロードした各テクスチャへの参照を保持するには、テクスチャにAddRefする。たとえば、

LPDIRECT3DRMTEXTURE2 *texarray;

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE2 *tex)
{
    if (FAILED(lpD3DRM2->LoadTexture(name, tex)) {
        return NULL;
    }

    texArray[current++] = tex;
    tex->AddRef();

    return tex;
}

IDirect3DRM3::LoadTextureFromResource

IDirect3DRM3

指定のリソースからDirect3DRMTexture2テクスチャをロードする。

構文

HRESULT LoadTextureFromResource(
  HMODULE hModule,
  LPCTSTR strName,
  LPCTSTR strType,
  LPDIRECT3DRMTEXTURE3  *lplpD3DRMTexture
  );

パラメータ

hModule
モジュールのハンドル。そのモジュールの実行可能ファイルがリソースを含む。
strName
テキスチャとして使われるリソース名を指定するヌル終端文字列。
strType
リソースのタイプ名を指定するヌル終端文字列を指す。このパラメータは、以下のリソースのタイプのいずれか、またはユーザ定義タイプにすることができる。
値 | 意味
RT_BITMAP | ビットマップリソース
RT_RCDATA | アプリケーション定義リソース(生データ)
lplpD3DRMTexture
この呼び出しが成功した場合に、有効なIDirect3DRMTexture3オブジェクトで初期化されるポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRM3::RegisterClient

IDirect3DRM3

データを関連付けるクライアント (アプリケーション) を登録する。

構文

HRESULT RegisterClient(
  REFGUID rguid,
  LPDWORD lpdwID);

パラメータ

rguid
アプリケーションを表すGUIDへの参照。
lpdwID
データを保持モードオブジェクトに関連付けるために、アプリケーションがIDirect3DRMObject2::SetClientDataとIDirect3DRMObject2::GetClientDataとともに使用する一意のIDを受け取るアドレス。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DD_OK

注意

アプリケーションはGUIDを渡し、DWORD 識別子を受け取る。次に、この識別子をIDirect3DRMObject2::SetClientDataとIDirect3DRMObject2::GetClientDataで使用して、データを保持モードオブジェクトに関連付ける。アプリケーションがIDirect3DRMObject2::SetClientDataを使用する場合、IDirect3DRMObject2::SetClientDataによってアプリケーションが格納する任意のデータは、そのタイプに応じてリリースされる。同じ GUIDを持つこのメソッドを複数回呼び出しても、同じIDが返される。このメソッドは、DirectX version 6.0で導入された。

IDirect3DRM3::SetDefaultTextureColors

IDirect3DRM3

Direct3DRMTexture2オブジェクトに対して使用するデフォルトの色を設定する。

構文

HRESULT SetDefaultTextureColors(
  DWORD dwColors
  );

パラメータ

dwColors
色の数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、IDirect3DRM3::CreateTextureメソッドの前に使われたときに限りテクスチャの色に影響する。すでに作成されているテクスチャには、何の効果もない。

IDirect3DRM3::SetDefaultTextureShades

IDirect3DRM3

Direct3DRMTexture2オブジェクトに対して使用するデフォルトのシェードを設定する。

構文

HRESULT SetDefaultTextureShades(
  DWORD dwShades
  );

パラメータ

dwShades
シェード数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、IDirect3DRM3::CreateTextureメソッドの前に使われたときに限りテクスチャのシェードに影響する。すでに作成されているテクスチャには、何の効果もない。

IDirect3DRM3::SetOptions

IDirect3DRM3

Direct3D保持モードで左手または右手ジオメトリのどちらを使用するかをセットする。

構文

HRESULT SetOptions(
  LPDWORD dwOptions);

パラメータ

dwOptions
現在のDirect3D保持モードオプションを示すフラグ値。現在定義されているフラグは、次の通りである。
D3DRMOPTIONS_LEFTHANDED
左手ジオメトリを使用する。これはデフォルト値である。
D3DRMOPTIONS_RIGHTHANDED
右手ジオメトリを使用する。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

D3DRMOPTIONS_LEFTHANDEDとD3DRMOPTIONS_RIGHTHANDEDは、ピッキングと光線ピッキングはもちろんのこと、次のオブジェクトにも影響を与える。

  • IDirect3DRMClippedVisual
  • IDirect3DRMMesh
  • IDirect3DRMMeshBuilder3
  • IDirect3DRMProgressiveMesh
  • IDirect3DRMShadow2
  • IDirect3DRMTexture3
  • IDirect3DRMViewport2

このメソッドは、DirectX version 6.0で導入された。

参照

「Direct3Dの座標系」

IDirect3DRM3::GetOptions

IDirect3DRM3::SetSearchPath

IDirect3DRM3

ディレクトリのリストから現在のファイル検索パスを設定する。Windowsでは、パスは、セミコロン(;)で区切られたリストにする必要がある。

構文

HRESULT SetSearchPath(
  LPCSTR lpPath
  );

パラメータ

lpPath
現在の検索パスとして設定するパスを指定するヌル終端の文字列のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デフォルトの検索パスは、D3DPATH環境変数の値が採用される。環境変数が設定されていなければ、検索パスは空になる。ファイルのオープン時、システムは、まず、現在の作業ディレクトリ中でファイルを探し、次に、検索パス中の各ディレクトリをチェックする。

D3DPATHは、デフォルトの検索パスを設定する環境変数である。

参照

IDirect3DRM3::GetSearchPath

IDirect3DRM3::Tick

IDirect3DRM3

Direct3DRMシステムのハートビートを行う。このメソッドが使われると、すべての可動フレームの位置は、現在の運動属性にしたがって更新され、シーンが現在のデバイスにレンダリングされる。また、関連したコールバック関数が、適切なタイミングで呼び出される。このメソッドは、レンダリングサイクルが完了したときに制御を返す。

構文

HRESULT Tick(
  D3DVALUE d3dvalTick
  );

パラメータ

d3dvalTick
IDirect3DRMFrame3::SetRotationおよびIDirect3DRMFrame3::SetVelocityメソッドに対する速度と回転のステップ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

シーンのレンダリングに柔軟性を持たせるため、保持モードの他のメソッドを使用して、このメソッドを実装することもできる。

IDirect3DRM3::UnregisterClient

IDirect3DRM3

IDirect3DRMObject2::SetClientDataによってセットしたすべてのデータとオブジェクトの関連をなくし、データをそのタイプに応じて開放する。

構文

HRESULT UnregisterClient(
  REFGUID rguid);

パラメータ

rguid
アプリケーションを表すGUIDへの参照。

戻り値

次の値のうち1つを返す。
D3DRMERR_CLIENTNOTREGISTERED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。


IDirect3DRMAnimation2

アプリケーションはIDirect3DRMAnimation2インターフェイスのメソッドを利用して、位置、向き、ビジュアルオブジェクトのスケーリング、照明、ビューポートのアニメーションを行うことができる。

保持モードのアニメーションは、キーセットによって定義される。キーはスケーリング操作、方向、または位置に関連付けられた時間値である。Direct3DRMAnimationオブジェクトは、時間値に応じた変換の修正方法を定義する。アニメーションをDirect3DRMFrameオブジェクト上で動作するようにセットし、Direct3DRMVisual、Direct3DRMLightおよびDirect3DRMViewportオブジェクトの位置、方向、スケーリングのアニメーションを行うために使用することができる。

IDirect3DRMAnimation2::AddPositionKey、AddRotateKeyおよびAddScaleKeyの各メソッドは、単位が任意の時間値を指定する。アプリケーションが時間値99の位置キーを追加した場合、たとえば、時間値49の新しい位置キーは、アニメーションの(0を基準とした) 開始点と最初の位置キーとの間のちょうど中間で発生する。

アニメーションの操作は、IDirect3DRMAnimation2::SetTimeメソッドを呼び出すことで行われる。これは、ビジュアルオブジェクトの変換をアニメーション中の近くのキーの補間位置、方向、スケールにセットする。アニメーションキーを追加するメソッドと同様に、IDirect3DRMAnimation2::SetTimeの時間値は、アプリケーションがすでに追加済のキー位置に基づく任意の値である。

Microsoft DirectX version 6.0は、IDirect3DRMAnimation2インターフェイスを導入している。IDirect3DRMAnimation2は、アニメーションのキーへのアクセスを可能にするAddKey、DeleteKeyByID、GetKeysおよびModifyKeyメソッドを追加することで、それが置換する旧のIDirect3DRMAnimationインターフェイスを拡張する。これは、対応するアニメーションのフレームを返すGetFrameメソッドも追加する。Direct3D保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRMAnimation2インターフェイスのメソッドは、以下のグループにまとめることができる。

キー | AddKey
 | AddPositionKey
 | AddRotateKey
 | AddScaleKey
 | DeleteKey
 | DeleteKeyByID
 | GetKeys
 | ModifyKey
その他 | GetFrame
 | SetFrame
 | SetTime
オプション | GetOptions
 | SetOptions

すべてのCOMインターフェイスと同様、IDirect3DRMAnimation2インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは次の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらにIDirect3DRMAnimation2インターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMAnimationオブジェクトは、IDirect3DRM3::CreateAnimationメソッドの呼び出しによって取得できる。

IDirect3DRMAnimation2::AddKey

IDirect3DRMAnimation2

新しいキーを追加する。

構文

HRESULT AddKey
(LPD3DRMANIMATIONKEY lpKey);

パラメータ

lpKey
新しいキーを定義するD3DRMANIMATIONKEY構造体。構造体のdwIDメンバは無視され、返る時点で新しいキーのIDがセットされる。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMAnimation2::AddPositionKey

IDirect3DRMAnimation2

アニメーションに位置キーを追加する。

構文

HRESULT AddPositionKey(
  D3DVALUE rvTime,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

パラメータ

rvTime
アニメーションの中で位置キーを設定するときの時間。0を原点とする任意の単位の時間を指定することができる。最後のキーのrvTimeの値が99のとき、rvTimeが49であるキーがアニメーションのちょうど中間である。
rvX, rvY, rvZ
位置。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドによって移動変換が行われるようになる。変換を含む行列計算については、「3D変換」を参照すること。

参照

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::AddRotateKey

IDirect3DRMAnimation2

アニメーションに回転キーを追加する。

構文

HRESULT AddRotateKey(
  D3DVALUE rvTime,
  D3DRMQUATERNION *rqQuat
  );

パラメータ

rvTime
アニメーションの中で回転キーを設定するときの時間。0を基準とする任意の単位の時間を指定することができる。最後のキーのrvTimeの値が99のとき、rvTimeが49であるキーがアニメーションのちょうど中間である。
rqQuat
回転を表す4次元行列。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドによって、回転変換が適用される。変換を含む行列計算については、「3D変換」を参照すること。

参照

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::AddScaleKey

IDirect3DRMAnimation2

アニメーションにスケールキーを追加する。

構文

HRESULT AddScaleKey(
  D3DVALUE rvTime,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

パラメータ

rvTime
アニメーションの中でスケールキーを記憶するときの時間。0を原点とする任意の単位の時間を指定できる。最後のキーのrvTimeの値が99のとき、rvTimeが49であるキーがアニメーションのちょうど中間である。
rvX, rvY, rvZ
スケール係数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドによって、スケール変換が適用される。変換を含む行列計算については、「3D変換」を参照すること。

参照

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2

キーをアニメーションから削除する。たとえば、アニメーションに時間tのスケールキーと時間tの回転キーがある場合、両方のキーが削除される。

構文

HRESULT DeleteKey(
  D3DVALUE rvTime
  );

パラメータ

rvTime
アニメーションから削除されるキーを識別する時間。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMAnimation2::DeleteKeyByID

IDirect3DRMAnimation2

固有のIDに対応するキーを削除する。

構文

HRESULT DeleteKeyByID
(DWORD dwID);

パラメータ

dwID
削除するキーのID。

戻り値

次の値のうち1つを返す。
D3DRMERR_NOSUCHKEY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMAnimation2::GetFrame

IDirect3DRMAnimation2

アニメーションに対応するフレームを取り出す。

構文

HRESULT GetFrame
(LPDIRECT3DRMFRAME3 *lplpFrame);

パラメータ

lplpFrame
アニメーションが参照する現在のDirect3DRMFrameオブジェクトのインターフェイスを受け取るポインタ。この値はNULLが可能である。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMAnimation2::GetKeys

IDirect3DRMAnimation2

固有の時間に対応するキーを取り出す。

構文

HRESULT GetKeys
(D3DVALUE dvTimeMin,
D3DVALUE dvTimeMax,
LPDWORD lpdwNumKeys,
LPD3DRMANIMATIONKEY lpKey);

パラメータ

dvTimeMin
返されるキーの最小時間値。
dvTimeMax
返されるキーの最大時間値。
lpdwNumKeys
中に返されるキーの数を含む変数へのポインタ。lpKeyがNULLの場合、lpdwNumKeysは指定の時間にキーの数がセットされる。
lpKey
キー値がセットされるD3DRMANIMATIONKEY構造体へのポインタ。lpKeyがNULLの場合、lpdwNumKeysは指定の時間にキーの数がセットされる。lpKeyがNULLでない場合、lpdwNumKeysiで示されるキーの最大数まで指定の時間に対応するキーがセットされる。

戻り値

次の値のうち1つを返す。
D3DRMERR_NOSUCHKEY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMAnimation2::GetOptions

IDirect3DRMAnimation2

アニメーションオプションを取得する。

構文

D3DRMANIMATIONOPTIONS GetOptions( );

戻り値

アニメーションオプションを示すD3DRMANIMATIONOPTIONS型の値を返す。

参照

IDirect3DRMAnimation2::SetOptions

IDirect3DRMAnimation2::ModifyKey

IDirect3DRMAnimation2

キー値を修正する。

構文

HRESULT Modify
(LPD3DRMANIMATIONKEY lpKey);

パラメータ

lpKey
既存のキーの値を定義するD3DRMANIMATIONKEY構造体。構造体のdwIDメンバは、既存のキーでなければならない。

戻り値

次の値のうち1つを返す。
D3DRMERR_INCOMPATIBLEKEY
D3DRMERR_NOSUCHKEY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

キーのタイプを修正することはできない。キーのタイプを変更するには、オリジナルキーを削除し、新しいキーを追加しなければならない。キーの時間、位置、回転、スケール値を修正することはできる。

IDirect3DRMAnimation2::SetFrame

IDirect3DRMAnimation2

アニメーションにフレームを設定する。

構文

HRESULT SetFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame
  );

パラメータ

lpD3DRMFrame
アニメーションに設定するフレームを指定する変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMAnimation2::SetOptions

IDirect3DRMAnimation2

アニメーションオプションを設定する。

構文

HRESULT SetOptions(
  D3DRMANIMATIONOPTIONS d3drmanimFlags
  );

パラメータ

d3drmanimFlags
アニメーションオプションを指定するD3DRMANIMATIONOPTIONS型の値のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMAnimation2::GetOptions

IDirect3DRMAnimation2::SetTime

IDirect3DRMAnimation2

アニメーションに現在の時間を設定する。

構文

HRESULT SetTime(
  D3DVALUE rvTime
  );

パラメータ

rvTime
アニメーションに設定する新しい現在の時間。0を原点とする任意の単位の時間を指定することができる。最後のキーのrvTimeの値が99のとき、rvTimeが49であるキーがアニメーションのちょうど中間である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。


IDirect3DRMAnimationArray

IDirect3DRMAnimationArrayインターフェイスは、配列中のアニメーションの数を取り出し、インターフェイスにアニメーションの実行を要求できるようにする。

IDirect3DRMAnimationArrayインターフェイスは、GetElementおよびGetSizeメソッドをサポートする。

すべてのCOMインターフェイスと同様に、IDirect3DRMAnimationArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。このインターフェイスは、次の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

IDirect3DRMAnimationArray::GetElement

IDirect3DRMAnimationArray

要求されたアニメーションに対するインターフェイスを取得する。

構文

DWORD GetElement(
  DWORD dwIndex,
  LPDIRECT3DRMANIMATION2 &lplpDirect3DRMAnimation);

パラメータ

dwIndex
取得されるアニメーションの配列内のインデックス。
lplpDirect3DRMAnimation
Direct3DRMAnimationオブジェクトへのポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMAnimationArray::GetSize

IDirect3DRMAnimationArray

配列中のアニメーションの数を取得する。

構文

DWORD GetSize();

戻り値

アニメーションの数を返す。

注意

このメソッドは、DirectX version 6.0とともに導入された。


IDirect3DRMAnimationSet2

アプリケーションは、Direct3DRMAnimationオブジェクトをグループ化するためにIDirect3DRMAnimationSet2インターフェイスのメソッドを使用することができる。このインターフェイスによって複雑なアニメーションの流れを再生することが簡単になる。

Direct3DRMAnimationSetオブジェクトによって、Direct3DRMAnimationオブジェクトをグループにまとめることができる。これで、アニメーションセット中のすべてのアニメーションが同じ時間パラメータを共有し、複雑に分割されたアニメーションの流れを簡単に再生できるようになる。アプリケーションは、IDirect3DRMAnimationSet2::AddAnimationメソッドを使用してアニメーションをアニメーションセットに追加し、IDirect3DRMAnimationSet2::DeleteAnimationメソッドを使用してそれを削除できる。アニメーションセットは、IDirect3DRMAnimationSet2::SetTimeメソッドを呼び出すことで操作する。

Microsoft DirectX version 6.0は、IDirect3DRMAnimationSet2インターフェイスを導入している。IDirect3DRMAnimationSet2は、構成アニメーションの取り出しを可能にするGetAnimationsメソッドを追加することで、それが置換する旧のIDirect3DRMAnimationSetインターフェイスを拡張する。Direct3D保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRMAnimationSet2インターフェイスのメソッドは、以下のグループにまとめることができる。

追加、削除、取得、ロード | AddAnimation
 | DeleteAnimation
 | GetAnimations
 | Load
時間 | SetTime

すべてのCOMインターフェイスと同様、IDirect3DRMAnimationSet2インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMAnimationSet2インターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMAnimationSetオブジェクトは、IDirect3DRM3::CreateAnimationSetの呼び出しによって取得できる。

IDirect3DRMAnimationSet2::AddAnimation

IDirect3DRMAnimationSet2

アニメーションをアニメーションセットに追加する。

構文

HRESULT AddAnimation(
  LPDIRECT3DRMANIMATION2 lpD3DRMAnimation
  );

パラメータ

lpD3DRMAnimation
アニメーションセットに追加するDirect3DRMAnimationオブジェクト。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMAnimationSet2::DeleteAnimation

IDirect3DRMAnimationSet2

アニメーションをアニメーションセットから削除する。

構文

HRESULT DeleteAnimation(
  LPDIRECT3DRMANIMATION2 lpD3DRMAnimation
  );

パラメータ

lpD3DRMAnimation
アニメーションセットから削除されるDirect3DRMAnimationオブジェクト。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMAnimationSet2::GetAnimations

IDirect3DRMAnimationSet2

アニメーションセット中のアニメーションを含む配列を取り出す。

構文

HRESULT GetAnimations
(LPDIRECT3DRMANIMATIONARRAY *lplpArray);

パラメータ

lplpArray
対応するDirect3DRMAnimationArrayオブジェクトへのポインタを受け取る配列。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMAnimationSet2::Load

IDirect3DRMAnimationSet2

アニメーションセットをロードする。

構文

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP,
  LPDIRECT3DRMFRAME3 lpParentFrame
  );

パラメータ

lpvObjSource
オブジェクトがロードされるソースへのポインタ。d3drmLOFlagsパラメータが示すソースフラグによって、ファイル、リソース、メモリブロック、またはストリームを指定する。
lpvObjID
ロードするオブジェクトの名前または位置へのポインタ。このパラメータは、d3drmLOFlagsパラメータが示す識別子フラグによって解釈される。D3DRMLOAD_BYPOSITIONフラグを指定した場合、このパラメータは、ファイルの中のオブジェクトの順序を示すDWORD値へのポインタである。このパラメータにはNULLを指定することもできる。
d3drmLOFlags
ロードオプションを示すD3DRMLOADOPTIONS型の値。
d3drmLoadTextureProc
D3DRMLOADTEXTURE3CALLBACKコールバック関数。これは、特別なフォーマットを必要とするオブジェクトが用いるテクスチャを読み出すときに呼び出される。このパラメータにはNULLを指定することができる。
lpArgLTP
D3DRMLOADTEXTURE3CALLBACKコールバック関数に渡されるアプリケーション定義のデータ。
lpParentFrame
親Direct3DRMFrameオブジェクトのアドレス。この引数は、アニメーションセットのロードだけに影響する。xファイルからロードされたアニメーションが、xファイル中の親のないフレームを参照するときは、その親には、lpParentFramがセットされる。ただし、xファイル中の任意のフレームをロードするように、Loadを使った場合には、lpParentFrameは、親のないxファイル中のフレームに対する親フレームとして使用されることはない。すなわち、lpParentFrameは、アニメーションセットをロードしたときに限り使用される。lpParentFrameの値はNULLにすることができる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デフォルトでは、このメソッドはlpvObjSourceパラメータで指定されるファイルの最初のアニメーションセットをロードする。デフォルトでは、パースペクティブ補正がオンである。

IDirect3DRMAnimationSet2::SetTime

IDirect3DRMAnimationSet2

アニメーションの現在の時間を設定する。

構文

HRESULT SetTime(
  D3DVALUE rvTime
  );

パラメータ

rvTime
新しい時間。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。


IDirect3DRMArray

IDirect3DRMArrayインターフェイスはオブジェクトのグループを管理する。通常、アプリケーションはこのインターフェイスを直接使わず、（IDirect3DRMFaceArrayなどの）特別な配列インターフェイスを利用する。

IDirect3DRMArrayインターフェイスは、GetSizeメソッドをサポートする。

すべてのCOMインターフェイスと同様、IDirect3DRMArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

IDirect3DRMArray::GetSize

IDirect3DRMArray

Direct3DRMArrayオブジェクトのサイズを、オブジェクト単位で取得する。

構文

DWORD GetSize( );

戻り値

サイズを返す。


IDirect3DRMClippedVisual

Microsoft® DirectX® version 6.0は、IDirect3DRMClippedVisualインターフェイスを導入している。このインターフェイスによって、アプリケーションは、レンダリングの前にワールド空間中で指定された任意のプレーンに対してビジュアルオブジェクトをクリップすることができる。別のビジュアルから影を作成するのとほとんど同じように、別のビジュアルからクリップビジュアルを作成する。たとえば、球体からクリップビジュアルを作成し、球体の真中から直線的にクリッピングプレーンを渡し、球体の半分だけをレンダリングさせることができる。IDirect3DRM3::CreateClippedVisualメソッドを呼び出すことで、クリップビジュアルオブジェクトを作成する。次に、IDirect3DRMFrame3::AddVisualメソッドを使用して、クリップビジュアルをシーンに追加する。

IDirect3DRMClippedVisualは、その他のビジュアルインターフェイスと同様にIDirect3DRMVisualを継承する。参照フレームが移動するとき、クリッピングプレーンは移動しない (詳細については、「AddPlaneメソッド」を参照すること)。

Microsoft Direct3D® 保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRMClippedVisualインターフェイスのメソッドは、以下のグループにまとめることができる。
初期化 | Init
プレーン | AddPlane
 | DeletePlane
 | GetPlane
 | GetPlaneIDs
 | SetPlane

すべてのCOMインターフェイスと同様、IDirect3DRMClippedVisualインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらにIDirect3DRMClippedVisualインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRM3インターフェイスを使用して、Direct3DRMClippedVisualオブジェクトを作成することができる。

IDirect3DRMClippedVisual::AddPlane

IDirect3DRMClippedVisual

クリッピングプレーンを追加する。

構文

HRESULT AddPlane(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags,
  LPDWORD lpdwReturnID);

パラメータ

lpRef
ポイントと法線パラメータの参照フレーム。
lpdvPoint
参照フレームを起点とするプレーン上のポイント。
lpdvNormal
参照フレームを起点とするプレーンに垂直なベクトル。
dwFlags
未使用フラグ。0でなければならない。
lpdwReturnID
呼び出しが成功した場合に、プレーンの一意なID番号を受け取るポインタ。

戻り値

DD_OKまたはDDERR_INVALIDPARAMSを返す。

注意

クリッピングプレーンは、ワールド座標として内部的に格納される。参照フレームが移動するとき、クリッピングプレーンは移動しない。必要に応じてクリッピングプレーンの位置と方向を更新するには、SetPlaneメソッドを使用する。

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMClippedVisual::DeletePlane

IDirect3DRMClippedVisual

クリッピングプレーンを削除する。

構文

HRESULT DeletePlane(
  DWORD dwID,
  DWORD dwFlags);

パラメータ

dwID
削除するプレーンのID番号。
dwFlags
未使用フラグ。

戻り値

成功すればDD_OKを返す。

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMClippedVisual::GetPlane

IDirect3DRMClippedVisual

クリッピングプレーンに関する情報を取り出す。

構文

HRESULT GetPlane(
  DWORD dwID,
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags);

パラメータ

lpRef
該当する操作の参照フレーム。
dwID
プレーンのID。
lpdvPoint
呼び出しが成功した場合に、参照フレームを起点とするプレーン上のポイントを受け取るポインタ。
lpdvNormal
呼び出しが成功した場合に、参照フレームを起点とするプレーンに垂直なベクトルを受け取るポインタ。
dwFlags
未使用フラグ。0でなければならない。

戻り値

DD_OKまたはDDERR_INVALIDPARAMSを返す。

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMClippedVisual::GetPlaneIDs

IDirect3DRMClippedVisual

IDの配列を取り出す。

構文

HRESULT GetPlanes(
  LPDWORD lpdwCount,
  LPDWORD lpdwID,
  DWORD dwFlags);

パラメータ

lpdwCount
呼び出しが成功した場合に、プレーンの数を受け取るポインタ。
lpdwID
すべてのプレーンID番号の配列を入れるのに十分な大きさのバッファのアドレス。呼び出しが成功した場合、プレーンIDが入っている。NULLならば、プレーンの数のみ返される。
dwFlags
未使用フラグ。0でなければならない。

戻り値

DD_OKまたはDDERR_INVALIDPARAMSを返す。

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMClippedVisual::Init

IDirect3DRMClippedVisual

クリップビジュアルを初期化する。

構文

HRESULT Init(
  LPDIRECT3DRMVISUAL lpD3DRMVisual);

パラメータ

lpD3DRMVisual
クリップし、レンダリングするビジュアル。

戻り値

成功すればDD_OKを返す。

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMClippedVisual::SetPlane

IDirect3DRMClippedVisual

すでに追加されたクリッピングプレーンのパラメータを変更する。

構文

HRESULT SetPlane(
  DWORD dwID,
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags);

パラメータ

dwID
変更するプレーンのID番号。
lpRef
ポイントと法線パラメータの参照フレーム。このパラメータがNULLならば、lpdvPointとlpdvNormalはワールド空間中にある。
lpdvPoint
参照フレームを起点とするプレーン上のポイント。
lpdvNormal
参照フレームを起点とするプレーンに垂直なベクトル。
dwFlags
フラグ値。0でなければならない。
lpdwReturnID
呼び出しが成功した場合に、プレーンの一意なID番号を受け取るポインタ。

戻り値

DD_OKまたはDDERR_INVALIDPARAMSを返す。

注意

このメソッドは、DirectX version 6.0とともに導入された。


IDirect3DRMDevice3

アプリケーションは、IDirect3DRMDevice3、IDirect3DRMDevice2およびIDirect3DRMDeviceインターフェイスを使用して出力デバイスと会話する。概要については、「出力デバイス」を参照すること。

IDirect3DRMDevice3は、旧のIDirect3DRMDevice2とIDirect3DRMDeviceインターフェイス中のすべてのメソッドを含むが、ある基準に基づいてテクスチャフォーマットを選択するFindPreferredTextureFormatメソッドを追加し、冗長な状態変更 (状態に現在の値と等しい値の設定) を排除する、次の4つのメソッドも追加する。GetStateChangeOptions、LightStateChange、RenderStateChangeおよびSetStateChangeOptionsである。

IDirect3DRMDevice2は、IDirect3DRMDeviceのすべてのメソッドに加えて、透明性の制御を可能にする2つのメソッド、GetRenderModeとSetRenderMode、1つの初期化メソッドInitFromSurface、さらにIDirect3DRMDeviceオブジェクトではなくIDirect3DRMDevice2オブジェクトを取り出したり初期化する2つの変更メソッドGetDirect3DDevice2とInitFromD3D2を含む。

IDirect3DRMDevice3またはIDirect3DRMDevice2インターフェイスを、それぞれIDirect3DRM3またはIDirect3DRM2インターフェイスから作成するか、あるいは対応するIDirect3DRMDevice3メソッド、InitFromClipper、InitFromD3D2、またはInitFromSurfaceを使用してどちらかのインターフェイスを初期化する場合、そのインターフェイスはIDirect3DDevice3またはIDirect3DDevice2直接モードデバイスとともにそれぞれ機能する。IDirect3DDevice3とIDirect3DDevice2デバイスは、DrawPrimitiveインターフェイスとともに実行バッファもサポートし、プログレッシブメッシュ、アルファブレンディング、透明オブジェクトのソートに必要となる。IDirect3DRMインターフェイスから旧のIDirect3DRMDeviceインターフェイスを作成する場合、IDirect3DRMDevice保持モードインターフェイスはIDirect3DDevice直接モードデバイスとともに機能する。

InitFromClipperとInitFromSurfaceメソッドは、IDirect3DRM3::CreateDeviceを使用してDirect3DRMDevice3オブジェクトを生成する。

InitFromD3D2メソッドは、IDirect3D2直接モードオブジェクトとIDirect3DDevice2直接モードデバイスを使用してIDirect3DDevice2 Direct3D保持モードデバイスを初期化する。

ユーザは、引き続きIDirect3DRMDevice3、IDirect3DRMDevice2、IDirect3DRMDeviceインターフェイスの間を照会することができる。主な相違点は、基底の直接モードデバイスの生成方法にある。

IDirect3DRMDevice3インターフェイスのメソッドは、以下のグループにまとめることができる。
バッファカウント | GetBufferCount
 | SetBufferCount
カラーモデル | GetColorModel
ディザリング | GetDither
 | SetDither
冗長な状態変更の削除 | GetStateChangeOptions
 | LightStateChange
 | RenderStateChange
 | SetStateChangeOptions
初期化 | Init
 | InitFromClipper
 | InitFromD3D2
 | InitFromSurface
その他 | GetDirect3DDevice2
 | GetHeight
 | GetTrianglesDrawn
 | GetViewports
 | GetWidth
 | GetWireframeOptions
 | Update
通知 | AddUpdateCallback
 | DeleteUpdateCallback
レンダリングクオリティ | GetQuality
 | SetQuality
シェーディング | GetShades
 | SetShades
テクスチャ | FindPreferredTextureFormat
 | GetTextureQuality
 | SetTextureQuality
透明性 | GetRenderMode
 | SetRenderMode

すべてのCOMインターフェイスと同様、IDirect3DRMDevice3インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMDevice3インターフェイスは、IDirect3DRMObjectインターフェイスから以下のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMDevice3オブジェクトは、IDirect3DRM3::CreateDeviceメソッドを呼び出すことによって取得される。

IDirect3DRMDevice3::AddUpdateCallback

IDirect3DRMDevice3

デバイスに変化が発生したとき、アプリケーションに警告を与えるコールバック関数を追加する。システムは、アプリケーションがIDirect3DRMDevice3::Updateメソッドを使ったときにはいつも、必ずこのコールバック関数を呼び出す。

構文

HRESULT AddUpdateCallback(
  D3DRMDEVICE3UPDATECALLBACK d3drmUpdateProc,
  LPVOID arg
  );

パラメータ

d3drmUpdateProc
アプリケーション定義コールバック関数D3DRMDEVICE3UPDATECALLBACKへのポインタ。
arg
更新コールバック関数に渡すプライベートデータへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

IDirect3DRMDevice2::AddUpdateCallbackとIDirect3DRMDevice::AddUpdateCallbackは、d3drmUpdateProcパラメータに対してD3DRMUPDATECALLBACKタイプのコールバックをとる。DirectX version 6.0については、IDirect3DRMDevice3は、より新しいD3DRMDEVICE3UPDATECALLBACKコールバックを導入している。

参照

IDirect3DRMDevice3::DeleteUpdateCallback, IDirect3DRMDevice3::Update, D3DRMDEVICE3UPDATECALLBACK

IDirect3DRMDevice3::DeleteUpdateCallback

IDirect3DRMDevice3

IDirect3DRMDevice3::AddUpdateCallbackメソッドを使って追加された更新コールバック関数を削除する。

構文

HRESULT DeleteUpdateCallback(
  D3DRMDEVICE3UPDATECALLBACK d3drmUpdateProc,
  LPVOID arg
  );

パラメータ

d3drmUpdateProc
アプリケーション定義のD3DRMDEVICE3UPDATECALLBACKコールバック関数のアドレス。
arg
更新コールバック関数に渡されるプライベートなデータへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

IDirect3DRMDevice2::DeleteUpdateCallbackとIDirect3DRMDevice::DeleteUpdateCallbackは、d3drmUpdateProcパラメータに対してD3DRMUPDATECALLBACKタイプのコールバックをとる。DirectX version 6.0については、IDirect3DRMDevice3は、より新しいD3DRMDEVICE3UPDATECALLBACKコールバックを導入している。

参照

IDirect3DRMDevice3::AddUpdateCallback, IDirect3DRMDevice3::Update, D3DRMDEVICE3UPDATECALLBACK

IDirect3DRMDevice3::FindPreferredTextureFormat

IDirect3DRMDevice3

ユーザの基準を満たし、下層の直接モードデバイスがサポートするテクスチャフォーマットを検索する。テクスチャキャッシュの最適なパフォーマンスを得るためには、この関数を使用してテクスチャサーフェスのピクセルフォーマットを選択する。

構文

HRESULT FindPreferredTextureFormat(
  DWORD dwBitDepths,
  DWORD dwFlags,
  LPDDPIXELFORMAT  lpDDPF);

パラメータ

dwBitDepths
要求されたテクスチャフォーマットビット深度。ビット深度が一切受容できないことを示すには、0を指定する。次のDirectDraw ビット深度フラグの1つ以上の論理的な組み合わせを使用して、その他の値を指定する。
DDBD_4
DDBD_8
DDBD_16
DDBD_24
DDBD_32
dwFlags
追加の要件を指定するフラグ。デフォルトの設定を使用するには、0を指定する。その他の有効値は、次の値の1つ以上の論理的な組み合わせでなければならない。
D3DRMFPTF_ALPHA
返されるテクスチャフォーマットには、アルファチャネルがなければならない。
D3DRMFPTF_NOALPHA
返されるテクスチャフォーマットには、アルファチャネルがあってはならない。アルファチャネルの欠落を希望するが、欠落を必須としないことを示すには、D3DRMFPTF_ALPHAとD3DRMFPTF_NOALPHAの両フラグを省略する。
D3DRMFPTF_PALETTIZED
D3DRMFPTF_PALETTIZED
返されるテクスチャフォーマットは、パレット化しなければならない。
D3DRMFPTF_NOTPALETTIZED
返されるテクスチャフォーマットは、パレット化してはならない。パレットの欠落を希望するが、欠落を必須としないことを示すには、D3DRMFPTF_PALETTIZEDとD3DRMFPTF_NOTPALETTIZEDの両フラグを省略する。
lpDDPF
テクスチャフォーマットを受け取るポインタ。

戻り値

次の値のうち1つを返す。
D3DRMERR_TEXTUREFORMATNOTFOUND
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

FindPreferredTextureFormatは、受入可能なフォーマットを検索できない場合D3DRMERR_TEXTUREFORMATNOTFOUNDを返す。

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMDevice3::GetBufferCount

IDirect3DRMDevice3

IDirect3DRMDevice3::SetBufferCountメソッドに対する呼び出しでセットされた値を取得する。

構文

DWORD GetBufferCount( );

戻り値

バッファの数であり、シングルバッファリングに対しては1、ダブルバッファリングに対しては2、などを返す。

IDirect3DRMDevice3::GetColorModel

IDirect3DRMDevice3

デバイスのカラーモデルを取得する。

構文

D3DCOLORMODEL GetColorModel( );

戻り値

Direct3Dカラーモデル(RGBまたはモノクロ)を記述するD3DCOLORMODEL列挙型から値を返す。

参照

「カラーモデル」

IDirect3DRMDevice3::GetDirect3DDevice2

IDirect3DRMDevice3

IDirect3DDevice2直接モードデバイスへのポインタを取得する。

構文

HRESULT GetDirect3DDevice2(
  LPDIRECT3DDEVICE2 *lplpD3DDevice
  );

パラメータ

lplpD3DDevice
IDirect3DDevice2直接モードデバイスオブジェクトへのポインタを使用して初期化されるポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

IDirect3DDevice2デバイスは、DrawPrimitiveインターフェイスとともに実行バッファもサポートし、プログレッシブメッシュ、アルファブレンディング、および透明オブジェクトのソートに必要となる。

IDirect3DRMDevice3::GetDither

IDirect3DRMDevice3

デバイスのディザリングフラグを取得する。

構文

BOOL GetDither( );

戻り値

ディザリングフラグがセットされていればTRUE、そうでなければFALSEを返す。

参照

IDirect3DRMDevice3::SetDither

IDirect3DRMDevice3::GetHeight

IDirect3DRMDevice3

デバイスの高さをピクセル単位で取得する。このメソッドは、便利な関数である。

構文

DWORD GetHeight( );

戻り値

高さを返す。

IDirect3DRMDevice3::GetQuality

IDirect3DRMDevice3

デバイスのレンダリングクオリティを取得する。

構文

D3DRMRENDERQUALITY GetQuality( );

戻り値

D3DRMRENDERQUALITY列挙型で表された列挙型の1つまたは複数のメンバを返す。

参照

IDirect3DRMDevice3::SetQuality

IDirect3DRMDevice3::GetRenderMode

IDirect3DRMDevice3

現在の透明性フラグを取得する。

構文

DWORD GetRenderMode( );

戻り値

現在の透明性フラグの値を返す。

注意

透明性フラグは、以下の値を持つ。
フラグ | 値
フラグのセットなし(デフォルト) | 0
D3DRMRENDERMODE_BLENDEDTRANSPARENCY | 1
D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE | 32
D3DRMRENDERMODE_LIGHTINMODELSPACE | 8
D3DRMRENDERMODE_SORTEDTRANSPARENCY | 2
D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR | 16

参照

IDirect3DRMDevice3::SetRenderMode

IDirect3DRMDevice3::GetShades

IDirect3DRMDevice3

シェーディングに使用される色のランプでのシェード数を取得する。

構文

DWORD GetShades( );

戻り値

シェード数を返す。

参照

IDirect3DRMDevice3::SetShades

IDirect3DRMDevice3::GetStateChangeOptions

IDirect3DRMDevice3

レンダリングまたは照明状態に関連付けられた状態変更オプションフラグを取得する。詳細については、「冗長な状態変更の削除」を参照すること。

構文

HRESULT GetStateChangeOptions(
  DWORD dwStateClass,
  DWORD dwStateNum,
  LPDWORD pdwFlags
  );

パラメータ

該当する状態が属する状態のクラス。この値には、D3DRMSTATECHANGE_LIGHTまたはD3DRMSTATECHANGE_RENDERをセットできる。
dwStateNum
該当するD3DRENDERSTATEまたはD3DLIGHTSTATEの番号。値0は、所定のクラスのすべての状態が影響を受けることを示す。
pdwFlags
オプションフラグへのポインタ。次の値のどれか1つを含む。
D3DRMSTATECHANGE_NONVOLATILE
D3DRMSTATECHANGE_VOLATILE

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、DirectX version 6.0とともに導入された。

次のコード例は、テクスチャハンドルレンダリング状態に関するオプションを取得する。

lpDirect3DRMDev3->GetStateChangeOptions(D3DRMSTATECHANGE_RENDER,
                          D3DRENDERSTATE_TEXTUREHANDLE, &dwFlags);

参照

IDirect3DRMDevice3::SetStateChangeOptions

IDirect3DRMDevice3::GetTextureQuality

IDirect3DRMDevice3

デバイスの現在のテクスチャクオリティパラメータを取得する。テクスチャクオリティは、RGBデバイスだけに関係する。

構文

D3DRMTEXTUREQUALITY GetTextureQuality( );

戻り値

D3DRMTEXTUREQUALITY列挙型のメンバの1つを返す。

参照

IDirect3DRMDevice3::SetTextureQuality

IDirect3DRMDevice3::GetTrianglesDrawn

IDirect3DRMDevice3

デバイスが作成されて以降、そのデバイスに描画された三角形の数を取得する。このメソッドは、便利な関数である。

構文

DWORD GetTrianglesDrawn( );

戻り値

三角形の数を返す。

注意

三角形の数は、レンダラに渡されたが、裏（カメラの向きと逆の面）に隠されたために描画されなかったものを含む。視錐台の外側にあって拒絶された三角形は含まれない。

IDirect3DRMDevice3::GetViewports

IDirect3DRMDevice3

デバイスから現在構築されているビューポートを表すDirect3DRMViewportArrayオブジェクトを構築する。

構文

HRESULT GetViewports(
  LPDIRECT3DRMVIEWPORTARRAY *lplpViewports
  );

パラメータ

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

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMDevice3::GetWidth

IDirect3DRMDevice3

デバイスのピクセル単位の幅を取得する。このメソッドは、便利な関数である。

構文

DWORD GetWidth( );

戻り値

ピクセル単位で、デバイスの幅を返す。

IDirect3DRMDevice3::GetWireframeOptions

IDirect3DRMDevice3

指定のデバイスのワイヤフレームオプションを取得する。

構文

DWORD GetWireframeOptions( );

戻り値

以下の値のビットごとのOR演算の結果を返す。

D3DRMWIREFRAME_CULL
裏に隠された面は、描画されない。
D3DRMWIREFRAME_HIDDENLINE
ワイヤフレームレンダリングされた線は、隣接のオブジェクトで隠される。

IDirect3DRMDevice3::Init

IDirect3DRMDevice3

Microsoft® Windows®プラットフォームでは未実装である。

構文

HRESULT Init(
  ULONG width,
  ULONG height
  );

IDirect3DRMDevice3::InitFromClipper

IDirect3DRMDevice3

IDirect3DRM3::CreateDeviceを使用して、指定のDirectDrawClipperオブジェクトのIDirect3DDevice2デバイスを初期化する。

構文

HRESULT InitFromClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper,
  LPGUID lpGUID,
  int width,
  int height
  );

パラメータ

lpDDClipper
初期化手段として使用するDirectDrawClipperオブジェクトへのポインタ。
lpGUID
使用するDirect3Dデバイスドライバ。
width, height
ピクセル単位でのデバイスの幅と高さ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMDevice3::InitFromD3D2

IDirect3DRMDevice3

IDirect3D2直接モードオブジェクトとIDirect3DDevice2直接モードデバイスから、IDirect3DRMDevice2保持モードデバイスを初期化する。

構文

HRESULT InitFromD3D2(
  LPDIRECT3D2 lpD3D,
  LPDIRECT3DDEVICE2 lpD3DIMDev
  );

パラメータ

lpD3D
保持モードデバイスを初期化するのに使用するIDirect3D2直接モードオブジェクトへのポインタ。
lpD3DIMDev
保持モードデバイスを初期化するのに使用する IDirect3DDevice2直接モードデバイスへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

IDirect3DRMDevice2から初期化されたIDirect3DDevice2デバイスは、DrawPrimitiveインターフェイスとともに実行バッファもサポートし、プログレッシブメッシュ、アルファブレンディング、および透明オブジェクトのソートに必要になる。

IDirect3DRMDevice3::InitFromSurface

IDirect3DRMDevice3

IDirect3DRM3::CreateDeviceを使用して、指定したDirectDrawサーフェスからIDirect3DDevice2デバイスを初期化する。

構文

HRESULT InitFromSurface(
  LPGUID lpGUID,
  LPDIRECTDRAW lpDD,
  LPDIRECTDRAWSURFACE lpDDSBack
  );

パラメータ

lpGUID
使用するDirect3Dデバイスを識別するグローバルユニーク識別子(GUID)へのポインタ。
lpDD
DirectDrawSurfaceを生成したDirectDrawオブジェクトのインターフェイスへのポインタ。
lpDDSBack
DirectDrawSurfaceバックバッファのインターフェイスへのポインタ。そのバックバッファ上でデバイスがレンダリングを行う。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

初期化されたIDirect3DRMDevice2デバイスは、DrawPrimitiveインターフェイスとともに実行バッファをサポートし、プログレッシブメッシュ、アルファブレンディング、および透明オブジェクトのソートに必要となる。

IDirect3DRMDevice3::LightStateChange

IDirect3DRMDevice3

照明状態を変更するか、またはDirect3D保持モードにレンダリング状態への変更を通知する。D3DRMSTATECHANGE_NONVOLATILEフラグがレンダリング状態に関連付けられている場合、保持モードはIDirect3DRMDevice3を使用して行った冗長な状態変更を排除する(状態を現在の値に等しい値にセットすることをしない)。詳細については、「冗長な状態変更の削除」を参照すること。

構文

HRESULT LightStateChange(
  DWORD dwStateNum,
  DWORD dwVal,
  DWORD dwFlags
  );

パラメータ

dwStateNum
該当するD3DLIGHTSTATE番号。
dwVal
状態の新しい値。
dwFlags
保持モードがキャッシュのみを更新するかどうかを示すフラグ。このフラグがD3DRMSTATECHANGE_UPDATEONLYにセットされている場合、内部キャッシュに保持されている値のみ更新される。D3DRMSTATECHANGE_UPDATEONLYを使用して、状態変更を示すことができる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、DirectX version 6.0とともに導入された。

次のコードはマテリアルハンドル照明状態をセットし、D3DRMSTATECHANGE_NONVOLATILEフラグがその状態に関連付けられている場合には冗長な変更を排除する。

lpDirect3DRMDev3->LightStateChange(D3DLIGHTSTATE_MATERIAL, hMat, 0);

次にフォグモードへの変更を示す。

lpDirect3DRMDev3->LightStateChange(D3DLIGHTSTATE_FOGMODE, D3DFOG_NONE,
                                   D3DRMSTATECHANGE_UPDATEONLY);

参照

IDirect3DRMDevice3::SetStateChangeOptions

IDirect3DRMDevice3::RenderStateChange

IDirect3DRMDevice3

レンダリング状態を変更するか、またはレンダリング状態への変更を示す。D3DRMSTATECHANGE_NONVOLATILEフラグがレンダリング状態に関連付けられている場合、保持モードはIDirect3DRMDevice3を使用して行った冗長な状態変更を排除する(状態を現在の値に等しい値にセットすることをしない)。詳細については、「冗長な状態変更の削除」を参照すること。

構文

HRESULT RenderStateChange(
  DWORD dwStateNum,
  DWORD dwVal,
  DWORD dwFlags
  );

パラメータ

dwStateNum
該当するD3DRENDERSTATE番号。
dwVal
状態の新しい値。
dwFlags
キャッシュのみ更新するかどうかを示すフラグ。このフラグがD3DRMSTATECHANGE_UPDATEONLYにセットされている場合、内部キャッシュに保持されている値のみ更新される。D3DRMSTATECHANGE_UPDATEONLYを使用して、状態の変更を示すことができる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、DirectX version 6.0とともに導入された。

次のコードは塗りつぶしモードレンダリング状態をセットし、D3DRMSTATECHANGE_NONVOLATILEフラグがその状態に関連付けられている場合には冗長な変更を排除する。

lpDirect3DRMDev3->RenderStateChange(D3DRENDERSTATE_FILLMODE,
                          D3DFILL_SOLID, 0);

次のコードは、テクスチャハンドルレンダリング状態への変更を示す。

lpDirect3DRMDev3->RenderStateChange(D3DRENDERSTATE_TEXTUREHANDLE, hTex,
                                    D3DRMSTATECHANGE_UPDATEONLY);

参照

IDirect3DRMDevice3::SetStateChangeOptions

IDirect3DRMDevice3::SetBufferCount

IDirect3DRMDevice3

現在アプリケーションで使用されているバッファの数を設定する。

構文

HRESULT SetBufferCount(
  DWORD dwCount
  );

パラメータ

dwCount
バッファの数を、シングルバッファリングに対しては1、ダブルバッファリングに対しては2などと指定する。デフォルト値は1であり、シングルバッファリングウィンドウ操作に対してのみ有効である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

アプリケーションが、ダブルバッファリングやトリプルバッファリングを行うときは、このメソッドで、使用するバッファ数をシステムに通知し、システムが各フレームに対して、ウィンドウのどの部分をクリアおよび更新するかを計算できるようにしなければならない。

参照

IDirect3DRMDevice3::GetBufferCount

IDirect3DRMDevice3::SetDither

IDirect3DRMDevice3

デバイスのディザリングフラグを設定する。

構文

HRESULT SetDither(
  BOOL bDither
  );

パラメータ

bDither
デバイスの新しいディザリングモード。デフォルトはTRUEである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMDevice3::GetDither

IDirect3DRMDevice3::SetQuality

IDirect3DRMDevice3

デバイスのレンダリングクオリティを設定する。

構文

HRESULT SetQuality (
  D3DRMRENDERQUALITY rqQuality
  );

パラメータ

rqQuality
D3DRMRENDERQUALITY列挙型で表された列挙型の1つまたは複数のメンバ。デフォルト設定値は、D3DRMRENDER_FLATである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

レンダリングクオリティは、デバイスのレンダリング面上で実行されるレンダリングのクオリティの最大値である。

オブジェクトクオリティには、3つのコンポーネントがある。すなわち、シェーディングモード (フラットまたはグーローで、フォンは実装されていない。デフォルトはグーローシェーディング)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

デバイスのクオリティを設定するには、SetQualityを用いる。デフォルトでは、デバイスクオリティはD3DRMRENDER_FLAT (フラットシェーディング、照明オンおよびソリッド塗りつぶし) である。

Direct3DRMProgressiveMesh 、またはDirect3DRMMeshBuilder3オブジェクトのクオリティは、それぞれのSetQualityメソッドを用いて設定することができる。デフォルトでは、これらのオブジェクトのクオリティは、D3DRMRENDER_GOURAUD（グーローシェーディング、照明オンおよびソリッド塗りつぶし）である。

ヒント: グーローシェーディングは、詳細レベルを頻繁にまたは素早く変更するプログレッシブメッシュオブジェクトについて、よりよいパフォーマンスを得られる。

Direct3D保持モードは、デバイスやオブジェクトの個々のコンポーネントに対する現在の設定の中で、最も低位のクオリティで、オブジェクトにレンダリングを行う。たとえば、オブジェクトの現在のクオリティ設定がD3DRMRENDER_GOURAUDで、デバイスがD3DRMRENDER_FLATであると、オブジェクトはフラットシェーディング、ソリッド塗りつぶし、および照明オンでレンダリングされる。

オブジェクトの現在のクオリティ設定がD3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAMEで、デバイスのクオリティ設定がD3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINTであると、オブジェクトはフラットシェーディング、照明オフ、およびポイント塗りつぶしモードでレンダリングされる。

これらのルールは、Direct3DRMMeshBuilder3オブジェクトおよびDirect3DRMProgressiveMeshオブジェクトに適用される。しかし、Direct3DRMMeshオブジェクトはこれらのルールに従わない。メッシュオブジェクトはデバイスのクオリティ設定を無視し、グループクオリティ設定を用いる（デフォルトでD3DRMRENDER_GOURAUD)。

参照

IDirect3DRMDevice3::GetQuality

IDirect3DRMDevice3::SetRenderMode

IDirect3DRMDevice3

透明モードを設定する。モードタイプは、オブジェクトをどの程度透明にレンダリングするかを決定する。デフォルトモードでは、透明点描で透明オブジェクトをレンダリングする。

構文

HRESULT SetRenderMode(
  DWORD dwFlags
  );

パラメータ

dwFlags
1つまたは複数の透明モードフラグ。デフォルト （dwFlags = 0）では、透明モードを透明点描に設定する。点描 (または「スクリーンドア」) による透明モードは、あるイメージ中のいくつかのピクセルをその他のイメージのピクセルで置換 (あたかも、あるイメージを2番目のイメージで塗られたスクリーンドアを通して見るかのように) することにより達成される。

さらに、フラグは1つ以上の、以下の値を持つことができる。

D3DRMRENDERMODE_BLENDEDTRANSPARENCY (dwFlags = 1) は、透明モードをアルファブレンディングに設定する。ブレンディングによる透明モードは、各ピクセルでカラー値を追加し2つのイメージを組み合わせることにより達成される。
D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE (dwFlags = 32) は、ソートされた透明オブジェクトを描画する際、zバッファに深度情報を書き込まないことを指定する。
D3DRMRENDERMODE_LIGHTINMODELSPACE (dwFlags = 8) は、予約済み。使用しないこと。
D3DRMRENDERMODE_SORTEDTRANSPARENCY (dwFlags = 2) は、シーン中の透明ポリゴンが第2パスでバッファリング、ソート、およびレンダリングされるように透明モードを設定する。このフラグは、D3DRMRENDERMODE_BLENDEDTRANSPARENCYフラグも同時にセットされていない場合には、何の効果もない。外部ビジュアルまたはユーザビジュアル中の透明ポリゴンはソートされない。ネイティブ D3DRM ビジュアル (D3DRMMeshオブジェクトとD3DRMMeshBuilderオブジェクトなど) のみソートされる。
D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR (dwFlags = 16) は、光源方向とビューアの位置の両方に依存する、より現実的な反射光を可能にする。DirectX Foundationの以前のバージョンのみ、ビューアの位置を考慮しないフラットな反射光をサポートする。このフラグがセットされていると、Direct3D直接モードはD3DLIGHT2構造体を使用して、Direct3D直接モードのIDirect3DLight::SetLight呼び出し時に照明タイプを定義する。このフラグがセットされていない場合、D3DRMはD3DLIGHT構造体を使用し、DirectXの以前のバージョンのライティング動作を得ることになる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

D3DRMRENDERMODE_BLENDEDTRANSPARENCYおよびD3DRMRENDERMODE_SORTEDTRANSPARENCYの両フラグが、同時にセットされていれば、2つの透明オブジェクトが、一方を他方でレンダリングするように保証し、イメージは、期待通りのビジュアル効果を作り出すように正しい順で混合される。

D3DRMRENDERMODE_SORTEDTRANSPARENCYは、アルファポリゴンの三角形ごとの、後ろから前へのソートをオンにする。ネイティブ D3DRM ビジュアル (D3DRMMeshオブジェクトとD3DRMMeshBuilderオブジェクトなど) のみソートされる。外部ビジュアルの三角形をソートリストに追加することはできない。

D3DRMRENDERMODE_BLENDEDTRANSPARENCYフラグは、点描アルファに対抗して真のアルファブレンディングをオンにする。真のアルファブレンディングでは、重複する三角形のピクセルはまとめて混合される。点描アルファでは、前面にある三角形のピクセルのいくつかは、下にある三角形を表示するような描画が行われない (これは、スクリーンドアの透明とも呼ばれる)。点描アルファを実行する場合、三角形をどのような順序でレンダリングするかにかかわらず、結果が同じであるため、三角形をソートする必要はない。

SetSortModeに対する有効なパラメータは、0 (ソートなしの点描アルファ)、BLENDEDTRANSPARENCY (ソートなしの真のアルファ)、およびBLENDEDTRANSPARENCYとSORTEDTRANSPARENCY (三角形ごとにソートされた真のアルファ) の両方だけである。

参照

IDirect3DRMDevice3::GetRenderMode

IDirect3DRMDevice3::SetShades

IDirect3DRMDevice3

モノクロ (ランプ) モデルシェーディングに使用される色のランプでのシェード数を設定する。

構文

HRESULT SetShades(
  DWORD ulShades
  );

パラメータ

ulShades
新しいシェード数。このパラメータは、2の累乗でなければならない。デフォルトは、32である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMDevice3::GetShades

IDirect3DRMDevice3::SetStateChangeOptions

IDirect3DRMDevice3

1つ以上のレンダリングまたは照明状態に関連付けられたオプションフラグを変更する。すべてのレンダリングと照明状態のデフォルト値は、D3DRMSTATECHANGE_VOLATILEである。D3DRMSTATECHANGE_NONVOLATILEフラグがレンダリングまたは照明状態に関連付けられている場合、Direct3D保持モードはその値をキャッシュし、冗長な変更を排除する (状態を現在の値に等しい値にセットすることをしない)。しかし、LightStateChangeまたはRenderStateChangeメソッドのどちらかによっていつ状態を変更したかを示さなければならない。詳細については、「冗長な状態変更の削除」を参照すること。

構文

HRESULT SetStateChangeOptions(
  DWORD dwStateClass,
  DWORD dwStateNum,
  DWORD dwFlags
  );

パラメータ

dwStateClass
該当する状態が属する状態のクラス。この値には、D3DRMSTATECHANGE_LIGHTまたはD3DRMSTATECHANGE_RENDERをセットできる。
dwStateNum
該当するD3DRENDERSTATEまたはD3DLIGHTSTATEの番号。値0は、所定のクラスのすべての状態が影響を受けることを示す。
dwFlags
オプションフラグ。次の値のどれか1つである。
D3DRMSTATECHANGE_NONVOLATILE
D3DRMSTATECHANGE_VOLATILE

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、DirectX version 6.0とともに導入された。

次のコードは、すべてのレンダリング状態でD3DRMSTATECHANGE_NONVOLATILEフラグをオンにセットする。

lpDirect3DRMDev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER, 0,
                                        D3DRMSTATECHANGE_NONVOLATILE);

次のコードは、テクスチャハンドルレンダリング状態でD3DRMSTATECHANGE_VOLATILEフラグをオンにセットする。

lpDirect3DRMDev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER,
                                        D3DRENDERSTATE_TEXTUREHANDLE,
                                        D3DRMSTATECHANGE_VOLATILE);

参照

IDirect3DRMDevice3::GetStateChangeOptions

IDirect3DRMDevice3::SetTextureQuality

IDirect3DRMDevice3

デバイスに対するテクスチャクオリティを設定する。

構文

HRESULT SetTextureQuality(
  D3DRMTEXTUREQUALITY tqTextureQuality
  );

パラメータ

tqTextureQuality
D3DRMTEXTUREQUALITY列挙型のメンバの1つ。デフォルトは、D3DRMTEXTURE_NEARESTである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMDevice3::GetTextureQuality

IDirect3DRMDevice3::Update

IDirect3DRMDevice3

レンダリングされているイメージをディスプレイにコピーする。また、デバイスドライバにハートビート関数も与える。そして、イメージをいつ更新するかを知らせる。

構文

HRESULT Update( );

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドに対する各呼び出しは、システムにアプリケーション定義コールバック関数のD3DRMDEVICE3UPDATECALLBACKを呼び出させる。コールバック関数を追加するには、IDirect3DRMDevice3::AddUpdateCallbackメソッドを使用する。

IDirect3DRMDevice2::UpdateとIDirect3DRMDevice::Updateは、システムがD3DRMUPDATECALLBACKタイプコールバックを呼び出すようにする。DirectX version 6.0については、IDirect3DRMDevice3は、より新しいD3DRMDEVICE3UPDATECALLBACKコールバックを導入する。

参照

IDirect3DRMDevice3::AddUpdateCallback, D3DRMDEVICE3UPDATECALLBACK


IDirect3DRMDeviceArray

アプリケーションは、IDirect3DRMDeviceArrayインターフェイスのメソッドを使用してデバイスオブジェクトを整理する。この項は、このインターフェイスのメソッドのリファレンスである。概要については、「出力デバイス」を参照すること。

IDirect3DRMDeviceArrayインターフェイスは、次のメソッドをサポートする。
GetElement
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMDeviceArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMDeviceArrayオブジェクトは、IDirect3DRM3::GetDevicesメソッドの呼び出しによって取得される。

IDirect3DRMDeviceArray::GetElement

IDirect3DRMDeviceArray

Direct3DRMDeviceArrayオブジェクトから指定された要素を取得する。

構文

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMDEVICE *lplpD3DRMDevice
  );

パラメータ

index
配列要素。
lplpD3DRMDevice
IDirect3DRMDeviceインターフェイスへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

QueryInterfaceを使用して、たとえば、IDirect3DRMDevice3などの希望するIDirect3DRMDeviceのバージョンへのポインタを取得することができる。lplpD3DRMDeviceパラメータを、単純に異なるバージョンに型変換することはできない。QueryInterfaceを使用しなければならない。

IDirect3DRMDeviceArray::GetSize

IDirect3DRMDeviceArray

Direct3DRMDeviceArrayオブジェクトに含まれる要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMFace2

アプリケーションは、面と互いにやり取りするためにIDirect3DRMFace2インターフェイスのメソッドを使用する。面は、メッシュ上の1つのポリゴンである。アプリケーションは、IDirect3DRMFace2::SetColor、IDirect3DRMFace2::SetColorRGB、IDirect3DRMFace2::SetTexture、およびIDirect3DRMFace2::SetMaterialメソッドを使用して、面の色、テクスチャ、マテリアルをセットすることができる。

面は、IDirect3DRMFace2::AddVertexとIDirect3DRMFace2::AddVertexAndNormalIndexedメソッドを使用して頂点から構築する。アプリケーションは、IDirect3DRMFace2::GetVerticesとIDirect3DRMFace2::GetVertexメソッドを使用して面の頂点を読み込むことができる。

IDirect3DRMFace2では、SetTextureメソッドは、その幅と高さが2の累乗でないテクスチャを指定することができる。

IDirect3DRMFace2インターフェイスのメソッドは、以下のグループにまとめることができる。

色 | GetColor
 | SetColor
 | SetColorRGB
マテリアル | GetMaterial
 | SetMaterial
テクスチャ | GetTexture
 | GetTextureCoordinateIndex
 | GetTextureCoordinates
 | SetTexture
 | SetTextureCoordinates
 | SetTextureTopology
頂点と法線 | AddVertex
 | AddVertexAndNormalIndexed
 | GetNormal
 | GetVertex
 | GetVertexCount
 | GetVertexIndex
 | GetVertices

すべてのCOMインターフェイスと同様、IDirect3DRMFace2インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMFace2インターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMFace2オブジェクトは、IDirect3DRM3::CreateFaceメソッドの呼び出しによって取得される。

IDirect3DRMFace2::AddVertex

IDirect3DRMFace2

Direct3DRMFace2オブジェクトに頂点を追加する。

構文

HRESULT AddVertex(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

パラメータ

x, y, z
新しい頂点位置のx、y、z座標。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFace2::AddVertexAndNormalIndexed

IDirect3DRMFace2

頂点と法線をDirect3DRMFace2オブジェクトに追加する。このとき、メッシュビルダに含まれる頂点のインデックスと法線のインデックスを使用する。面、頂点、法線は、Direct3DRMMeshBuilder3オブジェクトの一部でなくてはならない。

構文

HRESULT AddVertexAndNormalIndexed(
  DWORD vertex,
  DWORD normal
  );

パラメータ

vertex, normal
追加する頂点と法線のインデックス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFace2::GetColor

IDirect3DRMFace2

Direct3DRMFace2オブジェクトの色を取得する。

構文

D3DCOLOR GetColor( );

戻り値

色を返す。

参照

IDirect3DRMFace2::SetColor

IDirect3DRMFace2::GetMaterial

IDirect3DRMFace2

Direct3DRMFace2オブジェクトのマテリアルを取得する。

構文

HRESULT GetMaterial(
  LPDIRECT3DRMMATERIAL *lplpMaterial
  );

パラメータ

lplpMaterial
面に適用されているDirect3DRMMaterialオブジェクトへのポインタを受け取る変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFace2::SetMaterial

IDirect3DRMFace2::GetNormal

IDirect3DRMFace2

Direct3DRMFace2オブジェクトの法線ベクトルを取得する。

構文

HRESULT GetNormal(
  D3DVECTOR *lpNormal
  );

パラメータ

lpNormal
面の法線ベクトルを受け取るD3DVECTOR構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFace2::GetTexture

IDirect3DRMFace2

Direct3DRMFace2オブジェクトに適用されたテクスチャを取得する。

構文

HRESULT GetTexture(
  LPDIRECT3DRMTEXTURE *lplpTexture
  );

パラメータ

lplpTexture
面に適用されたテクスチャへのポインタを受け取る変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFace2::SetTexture

IDirect3DRMFace2::GetTextureCoordinateIndex

IDirect3DRMFace2

面のメッシュにある頂点のインデックスをテクスチャ座標で取得する。面を起点とする頂点インデックスをwhichパラメータで渡すと、このメソッドは、対応するメッシュを起点とする頂点インデックスを返す。

構文

int GetTextureCoordinateIndex(
  DWORD which
  );

パラメータ

which
対応するメッシュ頂点インデックスを取り出し中の頂点の面内のインデックス。

戻り値

面のメッシュを起点とする頂点インデックスを返す。

IDirect3DRMFace2::GetTextureCoordinates

IDirect3DRMFace2

Direct3DRMFace2オブジェクト中の頂点のテクスチャ座標を取得する。

構文

HRESULT GetTextureCoordinates(
  DWORD index,
  D3DVALUE *lpU,
  D3DVALUE *lpV
  );

パラメータ

index
頂点のインデックス。
lpU, lpV
点のテクスチャ座標を受け取る変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFace2::GetVertex

IDirect3DRMFace2

Direct3DRMFace2オブジェクト中の頂点の位置と法線を取得する。

構文

HRESULT GetVertex(
  DWORD index,
  D3DVECTOR *lpPosition,
  D3DVECTOR *lpNormal
  );

パラメータ

index
頂点のインデックス。
lpPosition, lpNormal
頂点の位置と法線を受け取るD3DVECTOR構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFace2::GetVertexCount

IDirect3DRMFace2

Direct3DRMFace2オブジェクトの頂点の数を取得する。

構文

int GetVertexCount( );

戻り値

頂点の数を返す。

IDirect3DRMFace2::GetVertexIndex

IDirect3DRMFace2

面のメッシュにある頂点のインデックスを取得する。面を起点とする頂点インデックスをwhichパラメータで渡すと、このメソッドは、対応するメッシュを起点とする頂点インデックスを返す。

構文

int GetVertexIndex (
  DWORD which
  );

パラメータ

which
対応するメッシュ頂点インデックスを取り出し中の頂点の面内のインデックス。

戻り値

メッシュを起点とする頂点インデックスを返す。

IDirect3DRMFace2::GetVertices

IDirect3DRMFace2

Direct3DRMFace2オブジェクト中のそれぞれの頂点について、位置と法線ベクトルを取得する。

構文

HRESULT GetVertices(
  DWORD *lpdwVertexCount,
  D3DVECTOR *lpPosition,
  D3DVECTOR *lpNormal
  );

パラメータ

lpdwVertexCount
頂点の数を受け取る変数のアドレス。このパラメータにNULLを指定することはできない。
lpPosition, lpNormal
頂点の位置と法線ベクトルを受け取るD3DVECTOR構造体の配列。両方ともNULLの場合、このメソッドはlpdwVertexCountパラメータに頂点の数を格納する。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFace2::SetColor

IDirect3DRMFace2

Direct3DRMFace2オブジェクトの色を設定する。

構文

HRESULT SetColor(
  D3DCOLOR color
  );

パラメータ

color
設定する色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。RGBA_MAKE DirectXマクロによってこれらの値を指定することができる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFace2::GetColor

IDirect3DRMFace2::SetColorRGB

IDirect3DRMFace2

Direct3DRMFace2オブジェクトの色をR, G, B値で設定する。

構文

HRESULT SetColorRGB(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

パラメータ

red, green, blue
赤、緑、青の色要素。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFace2::SetMaterial

IDirect3DRMFace2

Direct3DRMFace2オブジェクトにマテリアルをセットする。

構文

HRESULT SetMaterial(
  LPDIRECT3DRMMATERIAL lpD3DRMMaterial
  );

パラメータ

lpD3DRMMaterial
マテリアルのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFace2::GetMaterial

IDirect3DRMFace2::SetTexture

IDirect3DRMFace2

Direct3DRMFace2オブジェクトにテクスチャをセットする。

構文

HRESULT SetTexture(
  LPDIRECT3DRMTEXTURE lpD3DRMTexture
  );

パラメータ

lpD3DRMTexture
テクスチャのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

まず、DirectX Foundation 6については、テクスチャの幅と高さが2の累乗である必要はない。

参照

IDirect3DRMFace2::GetTexture

IDirect3DRMFace2::SetTextureCoordinates

IDirect3DRMFace2

Direct3DRMFace2オブジェクト中の頂点のテクスチャ座標を設定する。

構文

HRESULT SetTextureCoordinates(
  DWORD vertex,
  D3DVALUE u,
  D3DVALUE v
  );

パラメータ

vertex
設定する頂点のインデックス。たとえば、面が三角形のとき、頂点は0、1、2となる。
u, v
指定された頂点に割り当てるテクスチャ座標。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFace2::SetTextureTopology

IDirect3DRMFace2

Direct3DRMFace2オブジェクトにテクスチャ位相を設定する。

構文

HRESULT SetTextureTopology(
  BOOL cylU,
  BOOL cylV
  );

パラメータ

cylU, cylV
テクスチャがuとvのどちらの次元で円柱位相を持っているかを示す。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

いくつかのインターフェイスでSetTextureTopologyメソッドが提供される。SetTextureTopologyメソッドとの関係の詳細、およびcylU、cylVパラメータの目的に関する詳細については、「IDirect3DRMeshBuilder3::SetTextureTopology」を参照すること。


IDirect3DRMFaceArray

メッシュ上の面をグループ化するには、IDirect3DRMFaceArrayインターフェイスのメソッドを利用する。面の概要については、「IDirect3DRMFace2」を参照すること。

IDirect3DRMFaceArrayインターフェイスは、次のメソッドをサポートする。
GetElement
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMFaceArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMFaceArrayオブジェクトはIDirect3DRMMeshBuilder3::GetFacesメソッドの呼び出しによって取得される。

IDirect3DRMFaceArray::GetElement

IDirect3DRMFaceArray

Direct3DRMFaceArrayオブジェクトから指定された要素を取得する。

構文

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMFACE *lplpD3DRMFace
  );

パラメータ

index
配列要素。
lplpD3DRMFace
IDirect3DRMFaceインターフェイスへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFaceArray::GetSize

IDirect3DRMFaceArray

Direct3DRMFaceArrayオブジェクトに含まれる要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMFrame3

アプリケーションは、IDirect3DRMFrame3インターフェイスのメソッドを使用してオブジェクトの参照フレームと対話する。この概念の概要については、「フレーム」を参照すること。

IDirect3DRMFrame3インターフェイスは、IDirect3DRMFrame2インターフェイスの拡張である。IDirect3DRMFrame3は、追加変換機能、横断オプションのセットと取り出し、シーンフォグメソッドのセットと取り出しを可能にするメソッドを提供する。

IDirect3DRMFrame2は、マテリアル、境界ボックス、フレーム付きの軸を有効にする追加メソッドを提供することで、IDirect3DRMFrame機能を構築する。IDirect3DRMFrame2は、指定の位置と方向の光線とフレーム中のビジュアルの交点を計算するためのRayPickメソッドも追加された。さらに、IDirect3DRMFrame2には、変更されたメソッドAddMoveCallback2が含まれている。

各インターフェイスにより追加されたすべてのメソッドのリストについては、「インターフェイスの変更点」を参照すること。

IDirect3DRMFrame3インターフェイスのメソッドは、以下のグループにまとめることができる。

軸 | GetAxes
 | GetInheritAxes
 | SetAxes
 | SetInheritAxes
背景 | GetSceneBackground
 | GetSceneBackgroundDepth
 | SetSceneBackground
 | SetSceneBackgroundDepth
 | SetSceneBackgroundImage
 | SetSceneBackgroundRGB
境界ボックス | GetBox
 | GetBoxEnable
 | GetHierarchyBox
 | SetBox
 | SetBoxEnable
色 | GetColor
 | SetColor
 | SetColorRGB
フォグ | GetSceneFogColor
 | GetSceneFogEnable
 | GetSceneFogMethod
 | GetSceneFogMode
 | GetSceneFogParams
 | SetSceneFogColor
 | SetSceneFogEnable
 | SetSceneFogMethod
 | SetSceneFogMode
 | SetSceneFogParams
階層 | AddChild
 | DeleteChild
 | GetChildren
 | GetParent
 | GetScene
照明 | AddLight
 | DeleteLight
 | GetLights
ロード | Load
マテリアル | GetMaterial
 | GetMaterialOverride
 | SetMaterial
 | SetMaterialOverride
マテリアルモード | GetMaterialMode
 | SetMaterialMode
位置指定と運動 | AddMoveCallback
 | AddRotation
 | AddScale
 | AddTranslation
 | DeleteMoveCallback
 | GetOrientation
 | GetPosition
 | GetRotation
 | GetVelocity
 | LookAt
 | Move
 | SetOrientation
 | SetPosition
 | SetQuaternion
 | SetRotation
 | SetVelocity
光線ピック | RayPick
ソート | GetSortMode
 | GetZbufferMode
 | SetSortMode
 | SetZbufferMode
テクスチャ | GetTexture
 | SetTexture
変換 | AddTransform
 | GetTransform
 | InverseTransform
 | InverseTransformVectors
 | Transform
 | TransformVectors
横断 | GetTraversalOptions
 | SetTraversalOptions
ビジュアルオブジェクト | AddVisual
 | DeleteVisual
 | GetVisuals

すべてのCOMインターフェイスと同様、IDirect3DRMFrame3インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMFrame3インターフェイスは、IDirect3DRMObjectインターフェイスから以下のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMFrame3オブジェクトは、IDirect3DRM3::CreateFrameメソッドを呼び出すことによって取得される。


IDirect3DRMFrameArray

アプリケーションは、IDirect3DRMFrameArrayインターフェイスのメソッドを使用してフレームオブジェクトを整理する。この項は、このインターフェイスのメソッドのリファレンスである。概要については、「フレーム」を参照すること。

IDirect3DRMFrameArrayインターフェイスは、次のメソッドをサポートする。
GetElement
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMFrameArraインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

IDirect3DRMPickedArray::GetPick、IDirect3DRMPicked2Array::GetPick、またはIDirect3DRMFrame3::GetChildrenメソッドの呼び出しによって取得される。

IDirect3DRMFrameArray::GetElement

IDirect3DRMFrameArray

Direct3DRMFrameArrayオブジェクトから指定された要素を取得する。

構文

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMFRAME *lplpD3DRMFrame
  );

パラメータ

index
配列要素。
lplpD3DRMFrame
IDirect3DRMFrameインターフェイスへのポインタを受け取るアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

QueryInterfaceを使用して、たとえば、IDirect3DRMFrame3などの希望するIDirect3DRMFrame3のバージョンへのポインタを取得することができる。lplpD3DRMFrameパラメータを単純に異なるバージョンに型変換することはできない。QueryInterfaceを使用しなければならない。

IDirect3DRMFrameArray::GetSize

IDirect3DRMFrameArray

Direct3DRMFrameArrayオブジェクトに含まれている要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMInterpolator

インターポレータは、アクションを格納した後、中間値を自動計算して、オブジェクトにアクションを適用する方法を提供する。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、さらに、ほかのさまざまな変換も行うことができる。

IDirect3DRMInterpolatorインターフェイスは、IDirect3DRMAnimation2インターフェイスを包含する集合であり、アニメーションを行うことができるオブジェクトパラメータの種類が多くなっている。IDirect3DRMAnimation2インターフェイスがオブジェクトの位置、サイズ、および方向のアニメーションを可能にする一方で、IDirect3DRMInterpolatorは、色、メッシュ、テクスチャ、およびマテリアルのアニメーションも使用可能にしている。

概要は、「IDirect3DRMInterpolatorインターフェイス」を参照すること。

標準的なIUnknownおよびIDirect3DRMObjectメソッドに加えて、IDirect3DRMInterpolatorは、以下のメンバも含む。

オブジェクトの接続 | AttachObject
 | DetachObject
 | GetAttachedObjects
補間の実行 | GetIndex
 | Interpolate
 | SetIndex

すべてのCOMインターフェイスと同様、IDirect3DRMInterpolatorインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMInterpolatorインターフェイスは、IDirect3DRMObjectインターフェイスから以下のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRMInterpolator::AttachObject

IDirect3DRMInterpolator

オブジェクトをインターポレータに接続する。

構文

HRESULT AttachObject(
  LPDIRECT3DRMOBJECT lpD3DRMObject
  )

パラメータ

lpD3DRMObject
インターポレータに接続されるIDirect3DRMObjectオブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

接続されるオブジェクトは、別のインターポレータでも、インターポレータがxInterpolator型となるタイプxのオブジェクトでも良い。たとえば、ビューポートは、ViewportInterpolatorに接続できる。インターポレータのタイプは、以下のとおりである。

  • FrameInterpolator
  • LightInterpolator
  • MaterialInterpolator
  • MeshInterpolator
  • TextureInterpolator
  • ViewportInterpolator

IDirect3DRMInterpolator::DetachObject

IDirect3DRMInterpolator

インターポレータからオブジェクトの接続を解除する。

構文

HRESULT DetachObject(
  LPDIRECT3DRMOBJECT lpD3DRMObject
  )

パラメータ

lpD3DRMObject
インターポレータから接続を外すIDirect3DRMObjectオブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMInterpolator::GetAttachedObjects

IDirect3DRMInterpolator

インターポレータに現在接続されているオブジェクトの配列を取得する。

構文

HRESULT GetAttachedObjects(
  LPDIRECT3DRMOBJECTARRAY lpD3DRMObjectArray
  )

パラメータ

lpD3DRMObjectArray
現在インターポレータに付加されているIDirect3DRMObjectオブジェクトを含んだIDirect3DRMObjectArrayオブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMInterpolator::GetIndex

IDirect3DRMInterpolator

インターポレータの現在の内部インデックス（時間）を取得する。

構文

D3DVALUE GetIndex( )

戻り値

インターポレータの現在の内部インデックスを含むD3DVALUEを返す。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

IDirect3DRMInterpolator::Interpolate

IDirect3DRMInterpolator

インターポレータに格納されているキー間を補間して、一連のアクションを生成する。その後、アクションは、指定のオブジェクトに適用される。オブジェクトの指定がなければ、アクションは、現在接続されているオブジェクトに適用される。

構文

HRESULT Interpolate(
  D3DVALUE d3dVal,
  LPDIRECT3DRMOBJECT lpD3DRMObject,
  D3DRMINTERPOLATIONOPTIONS d3drmInterpFlags
  )

パラメータ

d3dVal
インターポレータの現在の内部インデックスを含むD3DVALUE。
lpD3DRMObject
IDirect3DRMObjectオブジェクトのアドレス。このオブジェクトは、インターポレータに格納されているすべてのプロパティに対する補間値を割り当てるオブジェクトを表す。このポインタはNULLでも良い。その場合には、すべての接続されているオブジェクトのプロパティ値には、補間値がセットされる。
d3drmInterpFlags
実行する補間の種類を制御する1つまたは複数のフラグ。可能な値は、以下のとおりである。
D3DRMINTERPOLATION_CLOSED
D3DRMINTERPOLATION_LINEAR
D3DRMINTERPOLATION_NEAREST
D3DRMINTERPOLATION_OPEN
D3DRMINTERPOLATION_SLERPNORMALS
D3DRMINTERPOLATION_SPLINE
D3DRMINTERPOLATION_VERTEXCOLOR
これらのオプションの記述は、「補間オプション」を参照すること。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMInterpolator::SetIndex

IDirect3DRMInterpolator

インターポレータの内部インデックス（時間）に指定の値をセットする。他のインターポレータがそのインターポレータに接続されていれば、このメソッドは、再帰的にそれらのインデックスを同じ値に同期させる。

構文

HRESULT SetIndex(
  D3DVALUE d3dVal
  )

パラメータ

d3dVal
インターポレータの内部インデックスに対してセットされる時間。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。


IDirect3DRMLight

アプリケーションは、照明と互いにやり取りするためにIDirect3DRMLightインターフェイスのメソッドを使用する。このセクションは、IDirect3DRMLightインターフェイスメソッドのリファレンスである。概念については、「照明」を参照すること。

IDirect3DRMLightインターフェイスのメソッドは、以下のグループにまとめることができる。
減衰 | GetConstantAttenuation
 | GetLinearAttenuation
 | GetQuadraticAttenuation
 | SetConstantAttenuation
 | SetLinearAttenuation
 | SetQuadraticAttenuation
色 | GetColor
 | SetColor
 | SetColorRGB
有効フレーム | GetEnableFrame
 | SetEnableFrame
照明タイプ | GetType
 | SetType
範囲 | GetRange
 | SetRange
スポット照明オプション | GetPenumbra
 | GetUmbra
 | SetPenumbra
 | SetUmbra

すべてのCOMインターフェイスと同様、IDirect3DRMLightインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMLightインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMLightオブジェクトは、IDirect3DRM3::CreateLightおよびIDirect3DRM3::CreateLightRGBメソッドの呼び出しによって取得される。

IDirect3DRMLight::GetColor

IDirect3DRMLight

現在のDirect3DRMLightオブジェクトの色を取得する。

構文

D3DCOLOR GetColor( );

戻り値

色を返す。

参照

IDirect3DRMLight::SetColor

IDirect3DRMLight::GetConstantAttenuation

IDirect3DRMLight

Direct3DRMLightオブジェクトの減衰定数を取得する。

構文

D3DVALUE GetConstantAttenuation( );

戻り値

減衰定数を返す。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、光源からの距離に基づいて照明の減衰を計算できる。

使用される照明の減衰公式は、D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされているかどうかに依存する。このフラグは、IDirect3DRMDevice3::SetRenderMode中にセットされている。

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされている場合、次の公式が照明の減衰に使用される。

距離正規化の公式は次の通りである。

normalized_distance = (distance_from_light - light_range)/light_range

light_rangeのデフォルト値は、256モデル空間単位である。

全減衰係数の公式は次の通りである。

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされていない場合、次の公式が照明の減衰に使用される。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。

減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、線形減衰係数に対しては0.0、二次減衰係数に対しては0.0である。

参照

IDirect3DRMLight::SetConstantAttenuation

IDirect3DRMLight::GetEnableFrame

IDirect3DRMLight

照明を設定するのに有効フレームを取得する。

構文

HRESULT GetEnableFrame(
  LPDIRECT3DRMFRAME  *lplpEnableFrame
  );

パラメータ

lplpEnableFrame
現在のDirect3DRMFrameオブジェクトの有効フレームを受け取るポインタへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMLight::SetEnableFrame

IDirect3DRMLight::GetLinearAttenuation

IDirect3DRMLight

照明の1次減衰係数を取得する。

構文

D3DVALUE GetLinearAttenuation( );

戻り値

1次減衰係数を返す。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、光源からの距離に基づいて照明の減衰を計算できる。

使用される照明の減衰公式は、D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされているかどうかに依存する。このフラグは、IDirect3DRMDevice3::SetRenderMode中にセットされている。

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされている場合、次の公式が照明の減衰に使用される。

距離正規化の公式は次の通りである。

normalized_distance = (distance_from_light - light_range)/light_range

light_rangeのデフォルト値は、256モデル空間単位である。

全減衰係数の公式は次の通りである。

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされていない場合、次の公式が照明の減衰に使用される。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。

減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、線形減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

参照

IDirect3DRMLight::SetLinearAttenuation

IDirect3DRMLight::GetPenumbra

IDirect3DRMLight

スポットライトの暗影部の角度を取得する。

構文

D3DVALUE GetPenumbra( );

戻り値

暗影部の値を返す。

注意

詳細は、「照明」の「スポットライト」を参照すること。

参照

IDirect3DRMLight::SetPenumbra

IDirect3DRMLight::GetQuadraticAttenuation

IDirect3DRMLight

照明の2次減衰係数を取得する。

構文

D3DVALUE GetQuadraticAttenuation( );

戻り値

2次減衰係数を返す。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

使用される照明の減衰公式は、D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされているかどうかに依存する。このフラグは、IDirect3DRMDevice3::SetRenderMode中にセットされている。

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされている場合、次の公式が照明の減衰に使用される。

距離正規化の公式は次の通りである。

normalized_distance = (distance_from_light - light_range)/light_range

light_rangeのデフォルト値は、256モデル空間単位である。

全減衰係数の公式は次の通りである。

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされていない場合、次の公式が照明の減衰に使用される。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。

減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、線形減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

参照

IDirect3DRMLight::SetQuadraticAttenuation

IDirect3DRMLight::GetRange

IDirect3DRMLight

現在のDirect3DRMLightオブジェクトの範囲を取得する。

構文

D3DVALUE GetRange( );

戻り値

範囲を示す値を返す。

参照

IDirect3DRMLight::SetRange

IDirect3DRMLight::GetType

IDirect3DRMLight

指定された照明のタイプを取得する。

構文

D3DRMLIGHTTYPE GetType( );

戻り値

D3DRMLIGHTTYPE列挙型のメンバの1つを返す。

参照

IDirect3DRMLight::SetType

IDirect3DRMLight::GetUmbra

IDirect3DRMLight

Direct3DRMLightオブジェクトの明部の角度を取得する。デフォルトは、0.4ラジアンである。

構文

D3DVALUE GetUmbra( );

戻り値

明部の角度を返す。

注意

詳細については、「照明」の「スポットライト」を参照すること。

参照

IDirect3DRMLight::SetUmbra

IDirect3DRMLight::SetColor

IDirect3DRMLight

指定された照明の色を設定する。

構文

HRESULT SetColor(
  D3DCOLOR rcColor
  );

パラメータ

rcColor
照明の新しい色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。RGBA_MAKE DirectXマクロによってこれらの値を指定することができる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMLightInterpolatorオブジェクトにRGBカラーキーを追加するためにも使用する。

参照

IDirect3DRMLight::GetColor

IDirect3DRMLight::SetColorRGB

IDirect3DRMLight

指定された照明の色をR, B, Gそれぞれの値で設定する。

構文

HRESULT SetColorRGB(
  D3DVALUE rvRed,
  D3DVALUE rvGreen,
  D3DVALUE rvBlue
  );

パラメータ

rvRed, rvGreen, rvBlue
照明の新しい色。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMLightInterpolatorオブジェクトにRGBカラーキーを追加するためにも使用する。

IDirect3DRMLight::SetConstantAttenuation

IDirect3DRMLight

照明の減衰係数を設定する。

構文

HRESULT SetConstantAttenuation(
  D3DVALUE rvAtt
  );

パラメータ

rvAtt
新しい減衰定数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

使用される照明の減衰公式は、D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされているかどうかに依存する。このフラグは、IDirect3DRMDevice3::SetRenderMode中にセットされている。

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされている場合、次の公式が照明の減衰に使用される。

距離正規化の公式は次の通りである。

normalized_distance = (distance_from_light - light_range)/light_range

light_rangeのデフォルト値は、256モデル空間単位である。

全減衰係数の公式は次の通りである。

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされていない場合、次の公式が照明の減衰に使用される。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。

減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、線形減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに減衰定数キーを追加するためにも使用する。

参照

IDirect3DRMLight::GetConstantAttenuation

IDirect3DRMLight::SetEnableFrame

IDirect3DRMLight

照明の有効フレームを設定する。

構文

HRESULT SetEnableFrame(
  LPDIRECT3DRMFRAME lpEnableFrame
  );

パラメータ

lpEnableFrame
照明の有効フレームへのポインタ。このフレームには親フレームと同様の照明となる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMLight::GetEnableFrame

IDirect3DRMLight::SetLinearAttenuation

IDirect3DRMLight

照明の1次減衰係数を設定する。

構文

HRESULT SetLinearAttenuation(
  D3DVALUE rvAtt
  );

パラメータ

rvAtt
新しい線形減衰係数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

使用される照明の減衰公式は、D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされているかどうかに依存する。このフラグは、IDirect3DRMDevice3::SetRenderMode中にセットされている。

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされている場合、次の公式が照明の減衰に使用される。

距離正規化の公式は次の通りである。

normalized_distance = (distance_from_light - light_range)/light_range

light_rangeのデフォルト値は、256モデル空間単位である。

全減衰係数の公式は次の通りである。

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされていない場合、次の公式が照明の減衰に使用される。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。

減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、線形減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに線形減衰定数キーを追加するためにも使用する。

参照

IDirect3DRMLight::GetLinearAttenuation

IDirect3DRMLight::SetPenumbra

IDirect3DRMLight

円錐の暗影部の角度をセットする。

構文

HRESULT SetPenumbra(
  D3DVALUE rvAngle
  );

パラメータ

rvAngle
ラジアン単位の新しい暗影部の角度。この角度は暗部の角度より大きいか、等しくなくてはいけない。暗影部の角度を明部の角度よりも小さく設定した場合、暗影部は明部と同じ角度になる。デフォルト値は0.5ラジアンである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに影角度キーを追加するためにも使用する。

詳細については、「照明」の「スポットライト」を参照すること。

参照

IDirect3DRMLight::GetPenumbra

IDirect3DRMLight::SetQuadraticAttenuation

IDirect3DRMLight

照明の2次減衰係数を設定する。

構文

HRESULT SetQuadraticAttenuation(
  D3DVALUE rvAtt
  );

パラメータ

rvAtt
新しい2次減衰係数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

使用される照明の減衰公式は、D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされているかどうかに依存する。このフラグは、IDirect3DRMDevice3::SetRenderMode中にセットされている。

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされている場合、次の公式が照明の減衰に使用される。

距離正規化の公式は次の通りである。

normalized_distance = (distance_from_light - light_range)/light_range

light_rangeのデフォルト値は、256モデル空間単位である。

全減衰係数の公式は次の通りである。

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULARフラグがセットされていない場合、次の公式が照明の減衰に使用される。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。

減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、線形減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに2次減衰キーを追加するためにも使用する。

参照

IDirect3DRMLight::GetQuadraticAttenuation

IDirect3DRMLight::SetRange

IDirect3DRMLight

スポットライトの範囲を設定する。この照明は、範囲内にあるオブジェクトに限り影響する。

構文

HRESULT SetRange(
  D3DVALUE rvRange
  );

パラメータ

rvRange
新しい範囲。デフォルト値は、256モデル空間単位である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

範囲プロパティは、スポットライトだけのものである。このメソッドは、Direct3DRMLightInterpolatorオブジェクトに範囲キーを追加するためにも使用する。

参照

IDirect3DRMLight::GetRange

IDirect3DRMLight::SetType

IDirect3DRMLight

照明のタイプを変更する。

構文

HRESULT SetType(
  D3DRMLIGHTTYPE d3drmtType
  );

パラメータ

d3drmtType
新しい照明タイプをD3DRMLIGHTTYPE列挙型のメンバの1つで指定する。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMLight::GetType

IDirect3DRMLight::SetUmbra

IDirect3DRMLight

円錐の明部の角度を設定する。

構文

HRESULT SetUmbra(
  D3DVALUE rvAngle
  );

パラメータ

rvAngle
ラジアン単位の新しい明部の角度。この角度は、暗影部の角度よりも小さいか、等しくなくてはいけない。明部の角度を暗影部の角度より大きく設定した場合、明部は暗影部と同じ角度となる。デフォルト値は0.4ラジアンである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに影角度キーを追加するためにも使用する。

詳細については、「照明」の「スポットライト」を参照すること。

参照

IDirect3DRMLight::GetUmbra


IDirect3DRMLightArray

アプリケーションは、照明オブジェクトをグループ化するためにIDirect3DRMLightArrayインターフェイスのメソッドを利用する。このセクションは、IDirect3DRMLightArrayインターフェイスメソッドのリファレンスである。概念についての概要は、「照明」を参照すること。

IDirect3DRMLightArrayインターフェイスは、次のメソッドをサポートする。
GetElement
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMLightArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMLightArrayオブジェクトは、IDirect3DRMFrame3::GetLightsメソッドの呼び出しによって取得される。

IDirect3DRMLightArray::GetElement

IDirect3DRMLightArray

Direct3DRMLightArrayオブジェクトから指定された要素を取得する。

構文

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMLIGHT  *lplpD3DRMLight
  );

パラメータ

index
配列要素。
lplpD3DRMLight
IDirect3DRMLightインターフェイスへのポインタを受け取るアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMLightArray::GetSize

IDirect3DRMLightArray

Direct3DRMLightArrayオブジェクトに含まれている要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMMaterial2

アプリケーションは、マテリアルオブジェクトと互いにやり取りするためにIDirect3DRMMaterial2インターフェイスのメソッドを使用する。

マテリアルでは、サーフェスがどのように光を反射するかを定義する。マテリアルには、放射プロパティ(光を放射するかどうか)と反射プロパティの2つの要素があり、その輝度は強度設定によって決まる。指数の値は反射するハイライトの鋭さを決め、5の値は金属の外観を与え、より大きい値はよりプラスチック的な外観を与える。

アプリケーションは、GetEmissiveとSetEmissiveメソッドを使用してマテリアルの放射を、GetSpecularとSetSpecularメソッドを使用して反射要素を、GetPowerとSetPowerメソッドを使用して指数を制御することができる。

Microsoft DirectX version 6.0は、IDirect3DRMMaterial2インターフェイスを導入している。IDirect3DRMMaterial2は、マテリアルプロパティに対するより洗練された制御を可能にするGetAmbientとSetAmbientメソッドを追加することで、それが置換する旧のIDirect3DRMMaterialインターフェイスを拡張する。IDirect3DRMMaterialについては、アンビエントカラーを修正することはできず、常に面の色と等しくなる。IDirect3DRMMaterial2オブジェクトは、SetAmbientが呼び出されるまで、オブジェクトの面の色をアンビエントカラーとして使用する。Direct3D保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRMMaterial2インターフェイスのメソッドは、以下のグループにまとめることができる。
アンビエント | GetAmbient
 | SetAmbient
放射 | GetEmissive
 | SetEmissive
反射指数の | GetPower
指数 | SetPower
反射 | GetSpecular
 | SetSpecular

すべてのCOMインターフェイスと同様、IDirect3DRMMaterial2インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMMaterial2インターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMMaterialオブジェクトは、IDirect3DRM3::CreateMaterialメソッドの使用によって取得される。

IDirect3DRMMaterial2::GetAmbient

IDirect3DRMMaterial2

マテリアルの現在のアンビエント値を取得する。

構文

HRESULT GetAmbient(
LPD3DVALUE lpdvRed,
LPD3DVALUE lpdvGreen,
LPD3DVALUE lpdvBlue);

パラメータ

lpdvRed
アンビエントカラーの赤要素がセットされる。
lpdvGreen
アンビエントカラーの緑要素がセットされる。
lpdvBlue
アンビエントカラーの青要素がセットされる。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMaterial2::GetEmissive

IDirect3DRMMaterial2

マテリアルの放射プロパティの設定を取得する。このプロパティの設定は、色とオブジェクトが発散する光の指数を示す。

構文

HRESULT GetEmissive(
  D3DVALUE *lpr,
  D3DVALUE *lpg,
  D3DVALUE *lpb
  );

パラメータ

lpr, lpg, lpb
メソッドが制御を返すとき、放射の赤、緑、青の色要素を受け取るアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMaterial2::SetEmissive

IDirect3DRMMaterial2::GetPower

IDirect3DRMMaterial2

指定されたマテリアルでの反射指数の強度を取得する。

構文

D3DVALUE GetPower( );

戻り値

反射指数の指数を示す値を返す。

参照

IDirect3DRMMaterial2::SetPower

IDirect3DRMMaterial2::GetSpecular

IDirect3DRMMaterial2

マテリアルの反射ハイライトの色を取得する。

構文

HRESULT GetSpecular(
  D3DVALUE *lpr,
  D3DVALUE *lpg,
  D3DVALUE *lpb
  );

パラメータ

lpr, lpg, lpb
メソッドが制御を返すとき、反射ハイライトの赤、緑、青の色要素を受け取るアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMaterial2::SetSpecular

IDirect3DRMMaterial2::SetAmbient

IDirect3DRMMaterial2

マテリアルのアンビエント値を設定する。デフォルトは拡散色である。拡散色とは、サーフェスの乱反射する(つやのない)色のことである。

構文

HRESULT SetAmbient(
    D3DVALUE dvRed,
    D3DVALUE dvGreen,
    D3DVALUE dvBlue);

パラメータ

dvRed
アンビエントカラーの赤要素。
dvGreen
アンビエントカラーの緑要素。
dvBlue
アンビエントカラーの青要素。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMaterial2::SetEmissive

IDirect3DRMMaterial2

マテリアルの放射プロパティを設定する。

構文

HRESULT SetEmissive(
  D3DVALUE r,
  D3DVALUE g,
  D3DVALUE b
  );

パラメータ

r, g, b
放射の色の赤、緑、青要素。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMMaterialInterpolatorオブジェクトに放射プロパティキーを追加するためにも使用する。

参照

IDirect3DRMMaterial2::GetEmissive

IDirect3DRMMaterial2::SetPower

IDirect3DRMMaterial2

マテリアルの反射指数の強度を設定する。

構文

HRESULT SetPower(
  D3DVALUE rvPower
  );

パラメータ

rvPower
新しい反射指数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMMaterialInterpolatorオブジェクトに反射指数キーを追加するためにも使用する。

参照

IDirect3DRMMaterial2::GetPower

IDirect3DRMMaterial2::SetSpecular

IDirect3DRMMaterial2

マテリアルの反射ハイライトの色を設定する。

構文

HRESULT SetSpecular(
  D3DVALUE r,
  D3DVALUE g,
  D3DVALUE b
  );

パラメータ

r, g, b
反射ハイライトの色の赤、緑、青の各要素。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMMaterialInterpolatorオブジェクトに反射カラーキーを追加するためにも使用する。

参照

IDirect3DRMMaterial2::GetSpecular


IDirect3DRMMesh

アプリケーションは、IDirect3DRMMeshインターフェイスのメソッドを使用して、メッシュのグループと会話する。メッシュは、ポリゴン面のセットから構成されるビジュアルオブジェクトである。メッシュは、頂点のセットと面のセット (面はメッシュの頂点と法線によって定義される) を定義する。いくつかの面が使用している頂点または法線を変更すると、それを共有するすべての面の外観が変わる。

メッシュの頂点はメッシュ中の面の位置を定義し、これらを使用してテクスチャマップ内の2D座標を定義することもできる。

IDirect3DRMMeshとIDirect3DRMMeshBuilder3を使用して、保持モードでメッシュを操作することができる。

アプリケーションで、同じ特性 (マテリアル、テクスチャなど) をいくつかの頂点または面に割り当てる必要がある場合、IDirect3DRMMeshインターフェイスを使用して、これらを1つのグループにまとめることができる。アプリケーションが2つの異なるグループ間で頂点を共有する必要がある場合 (たとえば、メッシュ中の隣接する面の色が異なる場合)、頂点は両方のグループに重複していなければならない。IDirect3DRMMesh::AddGroupメソッドは、グループ識別子を面の集合に割り当てる。この識別子を使用して、後続の呼び出しでグループを参照する。

IDirect3DRMMeshBuilder3とIDirect3DRMMeshインターフェイスによって、アプリケーションは3つ以上の側面を持つ面を作成することができる。たとえば、アプリケーションがレンダリングしているハードウェアに64Kの制限があり、メッシュがそのサイズを超えている場合、これらはメッシュを自動的に複数のバッファに分割する。これらの機能は、Direct3DRMMeshとDirect3DRMMeshBuilder3 APIをDirect3D APIから切り離してセットする。

IDirect3DRMMesh::SetGroupColor、SetGroupColorRGB、SetGroupTextureおよびSetGroupMaterialメソッドを使用して、メッシュの各面またはメッシュのすべての面に対して同時に、個別の色、テクスチャ、マテリアルプロパティを定義することができる。

レンダリングするメッシュについては、IDirect3DRMFrame3::AddVisualメソッドを使用して、最初にフレームに追加しなければならない。単一のメッシュを複数のフレームに追加して、そのメッシュの複数のインスタンスを作成することができる。

IDirect3DRMMesh::SetGroupQualityメソッドに対する呼び出しで指定されたように、アプリケーションは、フラット、グーロー、フォンシェードモードを使用することができる (しかし、フォンシェーディングはまだ利用可能ではない)。このメソッドは、D3DRMRENDERQUALITY列挙型の値を使用する。シェーディングモードの詳細については、「ポリゴン」を参照すること。

IDirect3DRMMeshインターフェイスのメソッドは、以下のグループにまとめることができる。
色 | GetGroupColor
 | SetGroupColor
 | SetGroupColorRGB
作成と | AddGroup
情報 | GetBox
 | GetGroup
 | GetGroupCount
マテリアル | GetGroupMaterial
 | SetGroupMaterial
その他 | Scale
 | Translate
レンダリングクオリティ | GetGroupQuality
 | SetGroupQuality
テクスチャマッピング | GetGroupMapping
 | SetGroupMapping
テクスチャ | GetGroupTexture
 | SetGroupTexture
頂点の位置 | GetVertices
 | SetVertices

すべてのCOMインターフェイスと同様、IDirect3DRMMeshインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMMeshインターフェイスはIDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMMeshオブジェクトは、IDirect3DRM3::CreateMeshメソッドの使用によって取得される。

IDirect3DRMMesh::AddGroup

IDirect3DRMMesh

面の集まりをグループ化し、そのグループの識別子を取得する。メッシュに最初に追加されるグループのインデックスは、常に0である。以降のグループのインデックスは、それぞれ1ずつ増加する。

構文

HRESULT AddGroup(
  unsigned vCount,
  unsigned fCount,
  unsigned vPerFace,
  unsigned *fData,
  D3DRMGROUPINDEX *returnId
  );

パラメータ

vCount, fCount
グループに含まれる頂点と面の数。
vPerFace
すべての面が同じ数の頂点を持つ場合、面当たりの頂点の数。グループ中の面が持つ頂点の数が一定でないときは、このパラメータに0を指定しなくてはならない。
fData
面データのアドレス。vPerFaceパラメータに値が設定されている場合、このデータは単に、グループの頂点配列へのインデックスリストである。vPerFaceが0のときは、頂点インデックスよりも、その面の頂点の数を示す整数値を優先しなくてはならない。たとえば、vPerFaceが0で、グループを構成する面が三角形と四角形である場合、データは次のようになる。[ 3, インデックス, インデックス, インデックス, 4, インデックス, インデックス, インデックス, インデックス, 3, インデックス, インデックス, インデックス, ...]
returnId
メソッドが制御を返すとき、グループの識別子を受け取る変数へのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

新しく追加されたグループには、以下のデフォルトのプロパティが与えられる。

  • 白。
  • テクスチャなし。
  • 反射なし。
  • 頂点配列の各頂点の位置、法線、色は0。

頂点の位置を設定するには、IDirect3DRMMesh::SetVerticesメソッドを使用する。

IDirect3DRMMesh::GetBox

IDirect3DRMMesh

Direct3DRMMeshオブジェクトを含む方形範囲を取得する。方形範囲は、それぞれの次元のモデル座標の最小値と最大値を示す。

構文

HRESULT GetBox(
  D3DRMBOX  *lpD3DRMBox
  );

パラメータ

lpD3DRMBox
境界ボックス座標を受け取るD3DRMBOX構造体。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMesh::GetGroup

IDirect3DRMMesh

指定されたグループに関連付けられているデータを取得する。

構文

HRESULT GetGroup(
  D3DRMGROUPINDEX id,
  unsigned *vCount,
  unsigned *fCount,
  unsigned *vPerFace,
  DWORD *fDataSize,
  unsigned *fData
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使用して生成されたものでなくてはならない。
vCount, fCount
メソッドが制御を返すとき、グループの頂点の数と面の数を受け取る変数のアドレス。これらのパラメータにはNULLを指定することができる。
vPerFace
メソッドが制御を返すとき、面当たりの頂点の数を受け取る変数のアドレス。これらのパラメータにはNULLを指定することができる。
fDataSize
fDataパラメータが指すバッファの中の、符号なし要素の数を示す変数のアドレス。このパラメータにNULLを指定することはできない。
fData
メソッドが制御を返すとき、グループの面データを格納するバッファのアドレス。このデータの形式は、IDirect3DRMMesh::AddGroupメソッドの呼び出しで指定したものと同じである。このパラメータがNULLのとき、必要なバッファのサイズがfDataSizeパラメータに返される。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMesh::GetGroupColor

IDirect3DRMMesh

グループの色を取得する。

構文

D3DCOLOR GetGroupColor(
  D3DRMGROUPINDEX id
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。

戻り値

成功すれば、色を示すD3DCOLOR値を返す。失敗すれば0を返す。

参照

IDirect3DRMMesh::SetGroupColor, IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh::GetGroupCount

IDirect3DRMMesh

指定されたDirect3DRMMeshオブジェクト中のグループの数を取得する。

構文

unsigned GetGroupCount( );

戻り値

成功すればグループの数を返す。失敗すれば0を返す。

IDirect3DRMMesh::GetGroupMapping

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中のグループに対して、どのようにテクスチャがマップされるかを取得する。

構文

D3DRMMAPPING GetGroupMapping(
  D3DRMGROUPINDEX id
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。

戻り値

成功すれば、グループへのテクスチャのマップ方法を示すD3DRMMAPPING値の1つを返す。失敗すれば0を返す。

参照

IDirect3DRMMesh::SetGroupMapping

IDirect3DRMMesh::GetGroupMaterial

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中のグループに関連付けられたマテリアルへのポインタを取得する。

構文

HRESULT GetGroupMaterial(
  D3DRMGROUPINDEX id,
  LPDIRECT3DRMMATERIAL *returnPtr
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
returnPtr
メソッドが制御を戻すとき、グループのIDirect3DRMMaterialインターフェイスを受け取る変数へのポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMesh::SetGroupMaterial

IDirect3DRMMesh::GetGroupQuality

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中の指定されたグループのレンダリングクオリティを取得する。

構文

D3DRMRENDERQUALITY GetGroupQuality(
  D3DRMGROUPINDEX id
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。

戻り値

成功すれば、D3DRMRENDERQUALITYで示される列挙型の値を返す。失敗すれば0を返す。これらの値には、オブジェクトのシェーディングモードや照明モード、塗りつぶしモードが含まれている。

参照

IDirect3DRMMesh::SetGroupQuality

IDirect3DRMMesh::GetGroupTexture

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中のグループに関連付けられたテクスチャへのポインタを取得する。

構文

HRESULT GetGroupTexture(
  D3DRMGROUPINDEX id,
  LPDIRECT3DRMTEXTURE *returnPtr
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
returnPtr
メソッドが制御を返すとき、グループのIDirect3DRMTextureインターフェイスを受け取る変数へのポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMesh::SetGroupTexture

IDirect3DRMMesh::GetVertices

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中の指定のグループに対する頂点情報を取得する。

構文

HRESULT GetVertices(
  D3DRMGROUPINDEX id,
  DWORD index,
  DWORD count,
  D3DRMVERTEX *returnPtr
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
index
頂点位置を取得する始点を示すD3DRMVERTEX構造体の配列のインデックス。
count
パラメータで与えられているインデックス以降の、取得するD3DRMVERTEX構造体（頂点）の数。このパラメータはNULLにできない。グループ中の頂点の数を取得するには、IDirect3DRMMesh::GetGroupメソッドを呼び出す。
returnPtr
メソッドが戻ったとき、頂点情報（頂点位置、色、テクスチャ座標など）を格納するD3DRMVERTEX構造体からなる配列。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMesh::GetGroup, IDirect3DRMMesh::SetVertices

IDirect3DRMMesh::Scale

IDirect3DRMMesh

モデル座標のx軸、y軸、z軸に対し、与えられたスケール係数によってDirect3DRMMeshオブジェクトをスケーリングする。

構文

HRESULT Scale(
  D3DVALUE sx,
  D3DVALUE sy,
  D3DVALUE sz
  );

パラメータ

sx, sy, sz
x軸、y軸、z軸に沿って適用されるスケール係数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMesh::SetGroupColor

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中のグループの色を設定する。

構文

HRESULT SetGroupColor(
  D3DRMGROUPINDEX id,
  D3DCOLOR value
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupを使って生成されたものでなくてはならない。
value
グループの色。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMMeshInterpolatorオブジェクトにグループRGBキーを追加するためにも使用する。

参照

IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh

RGB値を使用して、Direct3DRMMeshオブジェクト中のグループの色を設定する。

構文

HRESULT SetGroupColorRGB(
  D3DRMGROUPINDEX id,
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
red, green, blue
グループの色の赤、緑、青の各要素。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMMeshInterpolatorオブジェクトにグループRGBキーを追加するためにも使用する。

参照

IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColor

IDirect3DRMMesh::SetGroupMapping

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中のグループにマッピングを設定する。マッピングは、どのようにテクスチャが面にマップされるかを決定する。

構文

HRESULT SetGroupMapping(
  D3DRMGROUPINDEX id,
  D3DRMMAPPING value
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
value
グループのマッピングを指定するD3DRMMAPPING型の値。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMesh::GetGroupMapping

IDirect3DRMMesh::SetGroupMaterial

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中のグループにマテリアルを関連付ける。

構文

HRESULT SetGroupMaterial(
  D3DRMGROUPINDEX id,
  LPDIRECT3DRMMATERIAL value
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
value
Direct3DRMMeshオブジェクトに関連付けるIDirect3DRMMaterialインターフェイスのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMesh::GetGroupMaterial

IDirect3DRMMesh::SetGroupQuality

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中の指定されたグループのレンダリングクオリティを設定する。

構文

HRESULT SetGroupQuality(
  D3DRMGROUPINDEX id,
  D3DRMRENDERQUALITY value
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
value
D3DRMRENDERQUALITY型で表される列挙型の値。これらの値には、オブジェクトのシェーディングモードや照明モード、塗りつぶしモードが含まれている。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMesh::GetGroupQuality

IDirect3DRMMesh::SetGroupTexture

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中のグループにテクスチャを関連付ける。

構文

HRESULT SetGroupTexture(
  D3DRMGROUPINDEX id,
  LPDIRECT3DRMTEXTURE value
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
value
Direct3DRMMeshオブジェクトに関連付けるIDirect3DRMTextureインターフェイスのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMesh::GetGroupTexture

IDirect3DRMMesh::SetVertices

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中の指定されたグループの頂点の位置を設定する。

構文

HRESULT SetVertices(
  D3DRMGROUPINDEX id,
  unsigned index,
  unsigned count,
  D3DRMVERTEX *values
  );

パラメータ

id
グループの識別子。この識別子はIDirect3DRMMesh::AddGroupメソッドを使って生成されたものでなくてはならない。
index
修正するメッシュグループの最初の頂点のインデックス。
count
セットする連続頂点の数。values配列は、少なくともcount数の要素を格納しなければならない。
values
設定する頂点位置を示すD3DRMVERTEX構造体の配列。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

頂点情報はグループごとに持つ。2つの異なったグループ間で頂点を共有する必要がある場合（たとえば、メッシュ上の隣接した面の色が異なるとき）、両方のグループで頂点をコピーしなくてはならない。

このメソッドは、Direct3DRMMeshInterpolatorオブジェクトに頂点位置キーを追加するためにも使用する。

参照

IDirect3DRMMesh::GetVertices

IDirect3DRMMesh::Translate

IDirect3DRMMesh

Direct3DRMMeshオブジェクト中の頂点の位置に、指定されたオフセットを追加する。

構文

HRESULT Translate(
  D3DVALUE tx,
  D3DVALUE ty,
  D3DVALUE tz
  );

パラメータ

tx, ty, tz
各頂点位置のx座標、y座標、z座標に追加されるオフセット。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。


IDirect3DRMMeshBuilder3

アプリケーションは、IDirect3DRMMeshBuilder3インターフェイスのメソッドを使用してメッシュオブジェクトと会話する。メッシュの詳細については、「IDirect3DRMMesh」を参照すること。Microsoft® DirectX® version 6.0は、IDirect3DRMMeshBuilder3インターフェイスを導入している。Direct3D保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRMMeshBuilder3::AddVertex、AddFace、およびAddFacesメソッドを使用して、メッシュに対して個別に頂点と面を追加することができる。GetFaceメソッドによって個別の面を取得することができる。

法線 (単位ベクトルでなければならない) をセットするか、あるいは、GenerateNormalsメソッドを使用して、囲んでいる面の面法線を平均化して法線を計算することができる。

IDirect3DRMMeshBuilder3は、それが置換する旧のIDirect3DRMMeshBuilder2とIDirect3DRMMeshBuilderのインターフェイスを拡張する。これは、これらのオブジェクトを削除するためにDeleteFace、DeleteNormals、およびDeleteVerticesメソッドを追加し、これらのオブジェクトを取得するためにGetNormalメソッドとGetVertexメソッドを追加する。また、IDirect3DRMMeshBuilder3はEmptyメソッドとOptimizeメソッドも追加する。

他の新しいIDirect3DRMMeshBuilder3メソッドは、1つ以上の法線、法線の数、面、1つ以上の頂点、およびメッシュビルダの状態 (有効または無効) を取得する。このインターフェイスによって、頂点と法線のセット、メッシュビルダの新しいサブメッシュと親メッシュの作成と取り出しを行うことができる。また、IDirect3DRMMeshBuilder3では、アプリケーションが新しい三角形 (一般的なポリゴンと対立的な意味で) をIDirect3DRMMeshBuilder3オブジェクトに追加し、AddTrianglesメソッドを使用して、処理中に暗黙に新しい面を作成できる。

IDirect3DRMMeshBuilder3と旧のIDirect3DRMMeshBuilder2は、IDirect3DRMMeshBuilderの機能を含んだ上に、さらにGenerateNormalsメソッドを拡張して生成済みのメッシュ法線に対してより多くの制御ができるようしている。また、IDirect3DRMMeshBuilder3とIDirect3DRMMeshBuilder2では、GetFaceによって単一のメッシュ面を取得することも可能になる。

DirectX 6.0以降では、IDirect3DRM3インターフェイスを使用してDirect3DRMMeshBuilder3オブジェクトを作成することができる。この場合、Direct3DRMMeshBuilder3オブジェクトは、そのインプリメンテーションのために直接モードのDrawPrimitiveインターフェイスを使用する。

IDirect3DRMMeshBuilder3インターフェイスのメソッドは、以下のグループにまとめることができる。
色 | GetColorSource
 | SetColor
 | SetColorRGB
 | SetColorSource
生成 | GetBox
面 | AddFace
 | AddFaces
 | AddFacesIndexed
 | CreateFace
 | DeleteFace
 | GetFaceCount
 | GetFace
 | GetFaces
ロード | Load
メッシュ | AddMesh
 | CreateMesh
その他 | AddFrame
 | AddMeshBuilder
 | AddTriangles
 | Empty
 | Enable
 | GetEnable
 | Optimize
 | ReserveSpace
 | Save
 | Scale
 | SetMaterial
 | Translate
法線 | AddNormal
 | DeleteNormals
 | GenerateNormals
 | GetNormal
 | GetNormals
 | GetNormalCount
 | SetNormal
 | SetNormals
パースペクティブ | GetPerspective
 | SetPerspective
レンダリングクオリティ | GetQuality
 | SetQuality
サブメッシュ |
 | CreateSubMesh
 | DeleteSubMesh
 | GetParentMesh
 | GetSubMeshes
テクスチャ | GetTextureCoordinates
 | SetTexture
 | SetTextureCoordinates
 | SetTextureTopology
頂点 | AddVertex
 | DeleteVertices
 | GetGeometry
 | GetVertex
 | GetVertexColor
 | GetVertexCount
 | GetVertices
 | SetVertex
 | SetVertices
 | SetVertexColor
 | SetVertexColorRGB

すべてのCOMインターフェイスと同様、IDirect3DRMMeshBuilder3インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMMeshBuilder3インターフェイスは、IDirect3DRMObjectインターフェイスから以下のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMMeshBuilder3オブジェクトは、IDirect3DRM3::CreateMeshBuilderメソッドを呼び出して取得される。


IDirect3DRMObject

アプリケーションは、Microsoft® Direct3D®保持モードオブジェクトのスーパークラスとやりとりするために、IDirect3DRMObjectインターフェイスのメソッドを使用する。

Direct3DRMObjectは、システム中のすべてのオブジェクトの共通スーパークラスである。Direct3DRMObjectオブジェクトには、すべてのオブジェクトに共通する特性がある。

各Direct3DRMObjectオブジェクトは、COMオブジェクトとしてインスタンス化される。IUnknownインターフェイスのメソッドに加えて、各オブジェクトにはすべてに共通なメソッドの標準セットがある。

オブジェクトを作成するには、アプリケーションは、最初に、Direct3DRMCreate関数を呼び出すことでDirect3D保持モードオブジェクトをインスタンス化しなければならない。次に、アプリケーションは、オブジェクトを作成するオブジェクトのインターフェイスメソッドを呼び出し、オブジェクトに固有のパラメータを指定する。たとえば、Direct3DRMAnimationオブジェクトを作成するには、アプリケーションはIDirect3DRM3::CreateAnimationメソッドを呼び出すことになる。次に、作成メソッドは新しいオブジェクトを作成し、パラメータ中で (その他すべてはデフォルト値のまま) 渡されるデータのオブジェクト属性のいくつかを初期化し、オブジェクトを返す。次に、アプリケーションは、このオブジェクトのインターフェイスを指定し、オブジェクトの修正と使用を行える。

任意のオブジェクトは、アプリケーション固有データの32ビットを格納することができる。このデータを保持モードで解釈または変更できない。アプリケーションは、IDirect3DRMObject::GetAppDataメソッドを使用してこのデータを読み込み、IDirect3DRMObject::SetAppDataメソッドを使用してこのデータに書き込みすることができる。アプリケーションがDirect3DRMFrameの各オブジェクトの構造体を保持していれば、このデータの検索は簡単になる。たとえば、IDirect3DRMFrame3::GetParentメソッドの呼び出しでDirect3DRMFrameオブジェクトを取得する場合、アプリケーションはそのプライベート構造体へのポインタを使用して、データを簡単に取り出し、時間のかかる検索を避けることができる。

アプリケーションを編成する支援のために、またはアプリケーションのユーザインターフェイスの一部として、「名前」をオブジェクトに割り当てたい場合もあると思われる。IDirect3DRMObject::SetNameとIDirect3DRMObject::GetNameメソッドを使用して、オブジェクト名をセットし、取得することができる。

アプリケーション固有データの可能な用途のもう1つの例は、アプリケーションでメッシュ内の面をサブセット (たとえば、前面と後面) にグループ化する必要がある場合である。面の中のアプリケーションデータを使用して、面をこれらのグループのどこに入れるかを注記することができる。

アプリケーションでは、オブジェクトが破棄された場合に呼び出す関数を指定することができる。たとえば、アプリケーションでオブジェクトに関連付けられたメモリの割り当て解除を行う必要がある場合などである。このためには、IDirect3DRMObject::AddDestroyCallbackメソッドを使用する。このメソッドで以前に登録した関数を削除するには、IDirect3DRMObject::DeleteDestroyCallbackメソッドを使用する。

コールバック関数は、オブジェクトが破棄された場合にのみ呼び出される。すなわち、オブジェクトの参照カウントが0になり、システムがオブジェクトのメモリの割り当てを解除しようとする場合である。アプリケーションがオブジェクトに関する追加データを保持している場合 (たとえば、ダイナミックスをインプリメントするために)、アプリケーションはデータの処理が可能であることを自分自身に通知する手段として、このコールバック関数を使用することができる。

オブジェクトのグループ化については、「IDirect3DRMObjectArray」を参照すること。

IDirect3DRMObjectインターフェイスのメソッドは、以下のグループにまとめることができる。
アプリケーション固有の | GetAppData
データ | SetAppData
複製 | Clone
名前 | GetClassName
 | GetName
 | SetName
通知 | AddDestroyCallback
 | DeleteDestroyCallback

すべてのCOMインターフェイスと同様、IDirect3DRMObjectインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMObjectオブジェクトは、適切なQueryInterfaceメソッドを呼び出すことにより、どの保持モードオブジェクトからでも取得することができる。すべての保持モードオブジェクトは、IDirect3DRMObjectインターフェイスメソッドを継承する。

IDirect3DRMObject::AddDestroyCallback

IDirect3DRMObject

オブジェクトが破棄されるときに呼び出される関数を登録する。

構文

HRESULT AddDestroyCallback(
  D3DRMOBJECTCALLBACK lpCallback,
  LPVOID lpArg
  );

パラメータ

lpCallback
オブジェクトが破棄されるときに使われる、ユーザ定義のコールバック関数。
lpArg
コールバック関数に渡されたアプリケーション定義データのアドレス。この関数はオブジェクトが破棄された後に使われるため、引数としてオブジェクトを渡してはならない。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMObject::Clone

IDirect3DRMObject

オブジェクトの複製を作成する。

構文

HRESULT Clone(
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID *ppvObj
  );

パラメータ

pUnkOuter
COM集合化を可能にする外部IUnknownインターフェイスへのポインタ。
riid
複製するオブジェクトの識別子。
ppvObj
メソッドが制御を返すとき、オブジェクトの複製を格納するアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMObject::DeleteDestroyCallback

IDirect3DRMObject

IDirect3DRMObject::AddDestroyCallbackメソッドによって登録された関数を削除する。

構文

HRESULT DeleteDestroyCallback(
  D3DRMOBJECTCALLBACK d3drmObjProc,
  LPVOID lpArg
  );

パラメータ

d3drmObjProc
オブジェクトが破棄されるときに使われる、ユーザ定義のD3DRMOBJECTCALLBACKコールバック関数。
lpArg
コールバック関数に渡されたアプリケーション定義データのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMObject::GetAppData

IDirect3DRMObject

オブジェクトから、アプリケーション固有の32ビットデータを取得する。データのデフォルト値は0である。

構文

DWORD GetAppData( );

戻り値

アプリケーションによって定義されたデータ値を返す。

参照

IDirect3DRMObject::SetAppData

IDirect3DRMObject::GetClassName

IDirect3DRMObject

オブジェクトのクラス名を取得する。

構文

HRESULT GetClassName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

パラメータ

lpdwSize
lpNameパラメータが示すバッファのサイズがバイト単位で入る変数のアドレス。
lpName
メソッドが制御を返すとき、クラス名を示すNULLで終わる文字列のアドレス。このパラメータがNULLの場合、lpdwSizeパラメータには文字列に必要なサイズが設定される。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMObject::GetName

IDirect3DRMObject

オブジェクト名を取得する。

構文

HRESULT GetName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

パラメータ

lpdwSize
lpNameパラメータが示すバッファのサイズがバイト単位で入る変数のアドレス。
lpName
メソッドが制御を返すとき、オブジェクトの名前を示すNULLで終わる文字列のアドレス。このパラメータがNULLの場合、lpdwSizeパラメータには文字列に必要なサイズが設定される。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMObject::SetName

IDirect3DRMObject::SetAppData

IDirect3DRMObject

オブジェクトにアプリケーション固有の32ビットデータを設定する。

構文

HRESULT SetAppData(
  DWORD ulData
  );

パラメータ

ulData
オブジェクトに格納されるユーザ定義のデータ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMObject::GetAppData

IDirect3DRMObject::SetName

IDirect3DRMObject

オブジェクトの名前を設定する。

構文

HRESULT SetName(
  const char  *lpName
  );

パラメータ

lpName
オブジェクトの名前を示すユーザ定義のデータ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMObject::GetName


IDirect3DRMObject2

アプリケーションは、IDirect3DRMObject2インターフェイスのメソッドを使用して、Microsoft® Direct3D®保持モードオブジェクトのオブジェクト2スーパークラスに働きかける。Microsoft DirectX version 6.0は、すべての保持モードオブジェクトがインプリメントするIDirect3DRMObject2インターフェイスを導入する。任意のDirect3D保持モードオブジェクト上のQueryInterfaceを使用して、このインターフェイスへのポインタを取得することができる。

IDirect3DRMObject2は、同名のIDirect3DRMObjectメソッドと等価な次のメソッドをインプリメントする。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetName
SetName

IDirect3DRMObject2がIDirect3DRMObjectと共有するメソッドに加えて、次のメソッドもインプリメントする。
GetDirect3DRM
GetClientData
GetAge
SetClientData

IDirect3DRMObject2::GetClientDataとIDirect3DRMObject2::SetClientDataは、オブジェクトとのデータ結合を提供する。これは、旧のIDirect3DRMObject::GetAppDataとIDirect3DRMObject::SetAppDataメソッドよりも柔軟性が高い。

旧のオブジェクトインターフェイスの概念の概要については、「IDirect3DRMObject」を参照すること。Direct3D保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRMObject2インターフェイスのメソッドは、以下のグループにまとめることができる。
アプリケーション固有のデータ | GetClientData
 | SetClientData
複製 | Clone
名前 | GetName
 | SetName
その他 | GetAge
 | GetDirect3DRM
通知 | AddDestroyCallback
 | DeleteDestroyCallback

すべてのCOMインターフェイスと同様、IDirect3DRMObject2インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMObject2オブジェクトは、適切なQueryInterfaceメソッドを呼び出すことにより、どの保持モードオブジェクトからでも取得することができる。すべての保持モードオブジェクトは、IDirect3DRMObject2インターフェイスメソッドを継承する。

IDirect3DRMObject2::AddDestroyCallback

IDirect3DRMObject2

オブジェクトが破棄されるときに呼び出される関数を登録する。

構文

HRESULT AddDestroyCallback(
  D3DRMOBJECTCALLBACK lpCallback,
  LPVOID lpArg
  );

パラメータ

lpCallback
オブジェクトが破棄されるときに使われる、ユーザ定義のコールバック関数。
lpArg
コールバック関数に渡されたアプリケーション定義データのアドレス。この関数はオブジェクトが破棄された後に使われるため、引数としてオブジェクトを渡してはならない。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、IDirect3DRMObjectの同名のメソッドと同等である。

IDirect3DRMObject2::Clone

IDirect3DRMObject2

オブジェクトの複製を作成する。

構文

HRESULT Clone(
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID *ppvObj
  );

パラメータ

pUnkOuter
COM集合化を可能にする外部IUnknownインターフェイスへのポインタ。
riid
複製するオブジェクトの識別子。
ppvObj
メソッドが制御を返すとき、オブジェクトの複製を格納するアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMObject2::DeleteDestroyCallback

IDirect3DRMObject2

IDirect3DRMObject2::AddDestroyCallbackメソッドによって登録された関数を削除する。

構文

HRESULT DeleteDestroyCallback(
  D3DRMOBJECTCALLBACK d3drmObjProc,
  LPVOID lpArg
  );

パラメータ

d3drmObjProc
オブジェクトが破棄されるときに使われる、ユーザ定義のD3DRMOBJECTCALLBACKコールバック関数。
lpArg
コールバック関数に渡されたアプリケーション定義データのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、IDirect3DRMObjectの同名のメソッドと同等である。

IDirect3DRMObject2::GetAge

IDirect3DRMObject2

オブジェクトの現在の年齢を報告する。

構文

HRESULT GetAge(
  DWORD dwFlags,
  LPDWORD lpdwAge);

パラメータ

dwFlags
フラグ値。オブジェクトがメッシュビルダでない場合、0でなければならない。オブジェクトがメッシュビルダである場合、次の値のどれか1つをセットできる。
デフォルト(0)
メッシュビルダは通常通りに年をとる(エージングはメッシュビルダに対する何らかの変更によって引き起こされる)。
D3DRMMESHBUILDERAGE_GEOMETRY
メッシュビルダは、メッシュジオメトリが変更されるたびに年をとる(たとえば、頂点、面または別のメッシュビルダの追加)。
D3DRMMESHBUILDERAGE_MATERIALS
メッシュビルダは、メッシュのマテリアル関連プロパティが変更されるたびに、あるいは、面または別のメッシュが追加された場合に年をとる。
D3DRMMESHBUILDERAGE_TEXTURES
メッシュビルダは、メッシュのテクスチャ関連プロパティが変更されるたびに、あるいは、面または別のメッシュが追加された場合に年をとる。
lpdwAge
年齢を受け取るポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

オブジェクトが修正されると、年齢が増える。

このメソッドはDirectX version 6.0で導入された。DirectX 6.0以降では、次のオブジェクトのみエージングをサポートする。
Direct3DRMDevice3
Direct3DRMTexture3
Direct3DRMMeshBuilder3
Direct3DRMUserVisual
Direct3DRMShadow2
Direct3DRMWrap

IDirect3DRMObject2::GetClientData

IDirect3DRMObject2

SetClientDataの呼び出しを介して、オブジェクトに以前に関連付けられたデータを取得する。

構文

HRESULT GetClientData(
  DWORD dwID,
  LPVOID *lplpvData);

パラメータ

dwID
RegisterClientの呼び出しにより取得されるアプリケーションID。
lplpvData
関連データを受け取る変数のアドレス。
NULL値は、 データがセットされていないことを示す。

戻り値

次の値のうち1つを返す。
D3DRMERR_CLIENTNOTREGISTERED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_NOTINITIALIZED
DD_OK

注意

データのタイプがIUnknownであるならば、このメソッドは、データを呼び出し元に返す前に参照カウントをインクリメントする。このメソッドは、DirectX version 6.0で導入された。

IDirect3DRMObject2::GetDirect3DRM

IDirect3DRMObject2

このオブジェクトの作成にかかわる最後のDirect3DRMオブジェクトのインターフェイスへのポインタを取得する。

構文

HRESULT GetDirect3DRM(
  LPLPDIRECT3DRM lplpD3DRM);

パラメータ

lplpD3DRM
lpDirect3DRMObjectで指定したオブジェクトの作成にかかわる、最後のDirect3D保持モードオブジェクトのインターフェイスへのポインタを受け取るアドレス。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMObject2::GetName

IDirect3DRMObject2

オブジェクト名を取得する。

構文

HRESULT GetName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

パラメータ

lpdwSize
lpNameパラメータが示すバッファのサイズがバイト単位で入る変数のアドレス。
lpName
メソッドが制御を返すとき、オブジェクトの名前を示すNULLで終わる文字列のアドレス。このパラメータがNULLの場合、lpdwSizeパラメータには文字列に必要なサイズが設定される。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMObject2::SetName

注意

このメソッドは、IDirect3DRMObjectの同名のメソッドと同等である。

IDirect3DRMObject2::SetClientData

IDirect3DRMObject2

保持モードオブジェクトを持つデータ項目を関連付ける。

構文

HRESULT SetClientData(
  DWORD dwID,
  LPVOID lpvData,
  DWORD dwFlags);

パラメータ

dwID
IDirect3DRM3::RegisterClientの呼び出しにより取得されるアプリケーションID。
lpvData
オブジェクトに関連付けられるアプリケーション固有のデータ。
dwFlags
保持モードによるデータの解釈方法を決めるフラグ。
フラグ | D3DRMCLIENTDATA_NONE | D3DRMCLIENTDATA_LOCALFREE | D3DRMCLIENTDATA_IUNKNOWN
データの解釈 | 解釈なし | データはクライアントにより割り当てられる。Direct3DRMは、結合解除の際にそれを開放する必要がある。 | データはIUnknownインターフェイスをポイントすることを前提とする。
SetClientData上の動作 | 動作なし | 動作なし | Direct3D保持モードは、インターフェイス上の参照カウントをインクリメントする。
GetClientData上の動作 | 動作なし | 動作なし | Direct3D保持モードは、呼び出し元にそれを渡す前にインターフェイス上の参照カウントをインクリメントする。
データがオブジェクトから結合解除された場合に動作 | 動作なし | データ上ではLocalFreeが使用される。 | Direct3D保持モードは、インターフェイス上の参照カウントをデクリメントする。

戻り値

次の値のうち1つを返す。
D3DRMERR_CLIENTNOTREGISTERED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

データの削除は、NULLをlpvDataパラメータとしてこのメソッドを呼び出すか、 オブジェクトの破棄によるか、またはIDirect3DRM3::UnregisterClientを使用して行うことができる。 dwIDで指定されるIDを使用して以前にデータをオブジェクトに関連付けた場合、 以前のデータはリリースされる。破棄メソッドは、dwFlagsパラメータ中でこのメソッドに渡されるフラグに依存する。 GetClientDataの呼び出しによって、データを取得することができる。このメソッドは、DirectX version 6.0で導入された。

IDirect3DRMObject2::SetName

IDirect3DRMObject2

オブジェクトの名前を設定する。

構文

HRESULT SetName(
  const char  *lpName
  );

パラメータ

lpName
オブジェクトの名前を示すユーザ定義のデータ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、IDirect3DRMObjectの同名のメソッドと同等である。

参照

IDirect3DRMObject2::GetName


IDirect3DRMObjectArray

Direct3DRMObjectオブジェクトをグループ化するには、IDirect3DRMObjectArrayインターフェイスのメソッドを利用する。Direct3DRMObjectについての詳細は、「IDirect3DRMObject」を参照すること。

IDirect3DRMObjectArrayインターフェイスは、次のメソッドをサポートする。
GetElement
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMObjectArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMObjectArrayオブジェクトは、IDirect3DRMInterpolator::GetAttachedObjectsメソッドの呼び出しによって取得される。

IDirect3DRMObjectArray::GetElement

IDirect3DRMObjectArray

Direct3DRMObjectArrayオブジェクトから指定された要素を取得する。

構文

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMOBJECT  *lplpD3DRMObject
  );

パラメータ

index
配列要素。
lplpD3DRMObject
IDirect3DRMObjectインターフェイスへのポインタを受け取るアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMObjectArray::GetSize

IDirect3DRMObjectArray

Direct3DRMObjectArrayオブジェクトに含まれている要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMPicked2Array

ピックオブジェクトをグループ化し、より多くの情報を返すには、アプリケーションは、IDirect3DRMPicked2Arrayインターフェイスのメソッドを利用する。ピックの詳細については、「IDirect3DRMPickedArray」を参照すること。

IDirect3DRMFrame3::RayPickメソッドを使用して、IDirect3DRMPicked2Arrayインターフェイスを取得する。次に、IDirect3DRMPicked2Array::GetPickメソッドを呼び出して、IDirect3DRMFrameArrayインターフェイス、ビジュアルオブジェクト、および光線が交差するオブジェクトに関する情報を取得することができる。この情報には、面とグループの識別子、ピック位置、およびオブジェクトの頂点、頂点法線、色に対する水平と垂直テクスチャ座標が含まれる。フレームの配列は、ビジュアルオブジェクトに通じる階層へのパスである。

IDirect3DRMPicked2Array::GetPickによって返されるD3DRMPICKDESC2構造体には、面やグループの識別子、ピックの位置、頂点の水平および垂直テクスチャ座標、頂点の法線および交差したオブジェクトの色が含まれている。このインターフェイスポインタへのポインタは、光線のピック中にIDirect3DRMFrame3::RayPickメソッドで返される。

IDirect3DRMPicked2Arrayインターフェイスは、次のメソッドをサポートする。
GetPick
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMPicked2ArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMPicked2Arrayオブジェクトは、IDirect3DRMFrame3::RayPickメソッドの呼び出しによって取得される。

IDirect3DRMPicked2Array::GetPick

IDirect3DRMPicked2Array

指定されたピックによって交差するDirect3DRMVisualとDirect3DRMFrameオブジェクトを取得する。

構文

HRESULT GetPick(
  DWORD index,
  LPDIRECT3DRMVISUAL  *lplpVisual,
  LPDIRECT3DRMFRAMEARRAY  *lplpFrameArray,
  LPD3DRMPICKDESC2 lpD3DRMPickDesc2
  );

パラメータ

index
情報を取得するピックを識別する、ピック配列へのインデックス。
lplpVisual
指定されたピックに関連付けられたDirect3DRMVisualオブジェクトのポインタのアドレス。
lplpFrameArray
指定されたピックに関連付けられたDirect3DRMFrameArrayオブジェクトのポインタのアドレス。
lpD3DRMPickDesc
面やグループの識別子、ピックの位置、頂点の水平および垂直テクスチャ座標、頂点の法線および交差したオブジェクトの色が指定するD3DRMPICKDESC2構造体へのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、D3DRMPICKDESC構造体ではなくD3DRMPICKDESC2構造体中のu値とv値を取得する点を除けば、IDirect3DRMPickedArray::GetPickと類似している。

参照

IDirect3DRMFrame3::RayPick

IDirect3DRMPicked2Array::GetSize

IDirect3DRMPicked2Array

Direct3DRMPicked2Arrayオブジェクトに含まれている要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMPickedArray

アプリケーションは、IDirect3DRMPickedArrayインターフェイスのメソッドを使用して、ピックオブジェクトをグループ化する。ピッキングは、ビューポート中で2D座標またはフレーム中でベクトルが与えられたときに、シーン上のビジュアルを検索するプロセスである。光線ピックについては、「IDirect3DRMPicked2Array」を参照すること。

IDirect3DRMViewport2::Pickメソッドを使用して、IDirect3DRMPickedArrayインターフェイスを取得する。次に、IDirect3DRMPickedArray::GetPickメソッドを呼び出して、IDirect3DRMFrameArrayインターフェイスとビジュアルオブジェクトを取得することができる。フレームの配列は、階層を経てビジュアルオブジェクトに通じるパスである。これは、すなわち、階層中の最上部の親が配列の最初に来るビジュアルオブジェクトの親フレームの階層リストである。

IDirect3DRMPickedArrayインターフェイスは、次のメソッドをサポートする。
GetPick
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMPickedArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMPickedArrayオブジェクトは、IDirect3DRMViewport2::Pickメソッドの呼び出しによって取得される。

IDirect3DRMPickedArray::GetPick

IDirect3DRMPickedArray

指定されたピックによって交差するDirect3DRMVisualとDirect3DRMFrameオブジェクトを取得する。

構文

HRESULT GetPick(
  DWORD index,
  LPDIRECT3DRMVISUAL  *lplpVisual,
  LPDIRECT3DRMFRAMEARRAY  *lplpFrameArray,
  LPD3DRMPICKDESC lpD3DRMPickDesc
  );

パラメータ

index
情報を取得するピックを識別する、ピック配列へのインデックス。
lplpVisual
指定されたピックに関連付けられたDirect3DRMVisualオブジェクトのポインタのアドレス。
lplpFrameArray
指定されたピックに関連付けられたDirect3DRMFrameArrayオブジェクトのポインタのアドレス。
lpD3DRMPickDesc
ピックの位置、面、取得するオブジェクトのグループ識別子を指定するD3DRMPICKDESC構造体へのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMViewport2::Pick

IDirect3DRMPickedArray::GetSize

IDirect3DRMPickedArray

Direct3DRMPickedArrayオブジェクトに含まれている要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMProgressiveMesh

メッシュは、ポリゴン面のセットから構成されるビジュアルオブジェクトである。メッシュは、頂点のセットと面のセットを定義する。メッシュの詳細については、「IDirect3DRMMesh」を参照すること。

プログレッシブメッシュは、ベースメッシュ (粗いバージョン) およびメッシュをさらに精製するために使用される頂点分割レコードのセットとして格納されるメッシュである。すなわち、プログレッシブな精製が可能である。これによって、メッシュ用のレンダリングの詳細レベルをセットし、リモートソースからのプログレッシブダウンロードも可能になる。

プログレッシブメッシュは、Microsoft® Direct3D®保持モードのビジュアルであり、ビジュアル処理の標準的な方法で使用することができる。すなわち、プログレッシブメッシュは、フレーム階層に追加すること、複数回のインスタンス化、およびピックも可能である。

IDirect3DRMProgressiveMeshインターフェイスのメソッドを使用して、レンダリングする頂点または面の数をセットし、レンダリング詳細を制御することができる。レンダリングに必要な最小詳細レベルを指定することもできる。通常、プログレッシブメッシュは、ベースメッシュが一度使用可能になるとレンダリングされるが、IDirect3DRMProgressiveMesh::SetMinRenderDetailメソッドによってレンダリングの前にそれ以上の詳細レベルが必要であると指定することができる。また、IDirect3DRMProgressiveMesh::CreateMeshメソッドを使用して、プログレッシブメッシュ固有の状態からDirect3DRMMeshオブジェクトを構築することもできる。

プログレッシブメッシュを、ファイル、リソース、メモリ、またはURLからロードすることができる。ローディングは同期式でも非同期式でも行える。ダウンロードの状態はIDirect3DRMProgressiveMesh::GetLoadStatusメソッドによってチェックし、IDirect3DRMProgressiveMesh::Abortメソッドでダウンロードを終了することができる。ローディングが非同期式の場合、ロードの進行状態を調べるためにIDirect3DRMProgressiveMesh::RegisterEventsとIDirect3DRMProgressiveMesh::GetLoadStatusメソッドを介してイベントを使用するかどうかはアプリケーション次第である。

Direct3DRMProgressiveMeshオブジェクトは、IDirect3DRM3::CreateProgressiveMeshメソッドを使うことによって作成される。作成後、オブジェクトは階層に追加できるが、少なくともベースメッシュが使用可能になるまで、レンダリングされない。

標準的なIUnknownおよびIDirect3DRMObjectメソッドに加えて、このAPIは、以下のメンバを含む。

メッシュの生成とコピー | Clone
 | CreateMesh
 | Duplicate
 | GetBox
ロード | Abort
 | GetLoadStatus
 | Load
クオリティの設定 | SetQuality
 | GetQuality
詳細の管理 | GetDetail
 | GetFaceDetail
 | GetFaceDetailRange
 | GetVertexDetail
 | GetVertexDetailRange
 | SetDetail
 | SetFaceDetail
 | SetMinRenderDetail
 | SetVertexDetail
イベントの登録 | RegisterEvents

すべてのCOMインターフェイスと同様、IDirect3DRMProgressiveMeshインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMProgressiveMeshインターフェイスは、IDirect3DRMObjectインターフェイスから以下のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRMProgressiveMesh::Abort

IDirect3DRMProgressiveMesh

現在アクティブなダウンロードを中止する。

構文

HRESULT Abort(
  DWORD dwFlags
  )

パラメータ

dwFlags
0でなければならない。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

注意

このメソッドが使われる前にベースメッシュがダウンロードされている場合、その効果は、プログレッシブメッシュがロードされ、分割頂点が有効な状態にあり、プログレッシブメッシュがレンダリング可能である場合と同じである。他のプログレッシブメッシュメソッドも使うことができる。IDirect3DRMProgressiveMesh::Abortを呼び出す前にベースメッシュがダウンロードされておらず、シーンにプログレッシブメッシュを追加した場合、IDirect3DRMViewport2::Renderは成功するが、プログレッシブメッシュへのレンダリングは行われない。また、プログレッシブメッシュを使用するとき (たとえば、メッシュやクローンを作成するため) にベースメッシュがダウンロードされていなければ、呼び出しはD3DRMERR_NOTENOUGHDATAを返す。

IDirect3DRMProgressiveMesh::Clone

IDirect3DRMProgressiveMesh

現在ロードされているDirect3DRMProgressiveMeshオブジェクトのコピーを作成する。

構文

HRESULT Clone(
  LPDIRECT3DRMPROGRESSIVEMESH *lplpD3DRMPMesh
  )

パラメータ

lplpD3DRMPMesh
新しく生成されるDirect3DRMProgressiveMeshオブジェクトへのポインタでセットされるDirect3DRMProgressiveMeshポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

注意

クローン中のプログレッシブメッシュには、少なくともそのベースメッシュをロードしておかなければならない。現在、非同期でロード中のプログレッシブメッシュ上でこのメソッドを使うと、クローンされたメッシュはロードしているプログレッシブメッシュがクローンされたときに持っていた詳細レベルしか持たない。複製後にロードされた分割頂点は、クローンされたメッシュでは利用できない。

このメソッドはプログレッシブメッシュの内部データを共有しようとはしないが、IDirect3DRMProgressiveMesh::Duplicateは共有しようとする。

参照

IDirect3DRMProgressiveMesh::Duplicate

IDirect3DRMProgressiveMesh::CreateMesh

IDirect3DRMProgressiveMesh

現在の詳細レベルでメッシュを作成する。

構文

HRESULT CreateMesh(
  LPDIRECT3DRMMESH *lplpD3DRMMesh
  )

パラメータ

lplpD3DRMMesh
新しく生成されるDirect3DRMMeshオブジェクトへのポインタでセットされるDirect3DRMMeshポインタへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

注意

アプリケーションが、まだ使用可能になっていない詳細レベルを要求するか、またはベースメッシュが、まだ使用可能になっていないかのいずれかの場合には、このメソッドはエラーD3DRMERR_NOTENOUGHDATAを返す。

IDirect3DRMProgressiveMesh::Duplicate

IDirect3DRMProgressiveMesh

Direct3DRMProgressiveMeshオブジェクトのコピーを作成する。このコピーは、オリジナルと幾何図形や面データをすべて共有する。しかし、オリジナルとは別に詳細レベルを設定することができる。これは、同一のメッシュデータを階層の異なる部分で、ただし、異なる詳細レベルで使用できるようにする。本質的に、フレーム階層内にプログレッシブメッシュの2つのインスタンスがあると言える。

構文

HRESULT Duplicate(
  LPDIRECT3DRMPROGRESSIVEMESH *lplpD3DRMPMesh
  )

パラメータ

lplpD3DRMPMesh
新しく生成されるDirect3DRMProgressiveMeshオブジェクトへのポインタでセットされるDirect3DRMProgressiveMeshポインタのアドレス。

戻り値

失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

注意

複製中のプログレッシブメッシュには、少なくともそのベースメッシュをロードしておかなければならない。現在、非同期でロード中のプログレッシブメッシュ上でこのメソッドを使うと、複製されたメッシュはロードしているプログレッシブメッシュが複製されたときに持っていた詳細レベルしか持たない。複製後にロードされた分割頂点は、複製されたメッシュでは利用できない。

プログレッシブメッシュは、ベースメッシュを表すデータセットと、分割頂点を表すデータセットを持っている。ベースメッシュデータおよびプログレッシブメッシュの現状や現在の詳細レベルを記述するデータは、複製されたメッシュ間で共有されない。しかし、分割頂点データは共有される。このメソッドはプログレッシブメッシュの新しいインスタンスを作成する。このインスタンスは、オリジナルと幾何図形や面データをすべて共有するが、その詳細レベルはオリジナルとは無関係に設定することができる。

IDirect3DRMProgressiveMesh::GetBox

IDirect3DRMProgressiveMesh

Direct3DRMProgressiveMeshオブジェクトを含む境界ボックスを取得する。境界ボックスは、各次元で、子フレームを基準とする最小および最大の座標を与える。

構文

HRESULT GetBox(
  D3DRMBOX  *lpD3DRMBox
  );

パラメータ

lpD3DRMBox
境界ボックスの座標がセットされるD3DRMBOX構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMProgressiveMesh::GetDetail

IDirect3DRMProgressiveMesh

0.0と1.0の間に正規化された現在の詳細レベルのプログレッシブメッシュを返す。

構文

HRESULT GetDetail(
  LPD3DVALUE lpdvVal
  )

パラメータ

lpdvVal
現在の詳細レベルのプログレッシブメッシュがセットされるD3DVALUEのアドレス。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

注意

ベースメッシュがダウンロードされていなければ、このメソッドは、D3DRMERR_PENDINGを返す。要求されている詳細レベルが設定されていれば、戻り値は、要求レベルが満足されるまで以降の呼び出しごとに増加される。レベルが要求されていなければ、詳細レベルは、すべての分割頂点のダウンロードが完了するまで上昇する。

正規化された値0.0は頂点の最小数を表し (ベースメッシュ中の頂点数)、正規化された値1.0は頂点の最大数を表す。

IDirect3DRMProgressiveMesh::GetFaceDetail

IDirect3DRMProgressiveMesh

プログレッシブメッシュにある面の数を取得する。

構文

HRESULT GetFaceDetail(
  LPDWORD lpdwCount
  )

パラメータ

lpdwCount
プログレッシブメッシュの面の数がセットされるDWORDのアドレス。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_PENDING
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

注意

面の数が利用できなければ、このメソッドはD3DRMERR_PENDINGを返す。

IDirect3DRMProgressiveMesh::GetFaceDetailRange

IDirect3DRMProgressiveMesh

プログレッシブメッシュで使用可能な最小および最大の面カウントを返す。

構文

HRESULT GetFaceDetailRange(
  LPDWORD lpdwMinFaces,
  LPDWORD lpdwMaxFaces
  )

パラメータ

lpdwMinFaces
面の最小数がセットされるDWORD値のアドレス。
lpdwMaxFaces
面の最大数がセットされるDWORD値のアドレス。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

注意

面カウントが取得できない場合には、D3DRMERR_PENDINGを返す。

IDirect3DRMProgressiveMesh::GetLoadStatus

IDirect3DRMProgressiveMesh

ロードの現在の状態をアプリケーションが照会することを可能にする。

構文

HRESULT GetLoadStatus(
  LPD3DRMPMESHLOADSTATUS lpStatus
  )

パラメータ

lpStatus
プログレッシブメッシュのロード状態を含むD3DRMPMESHLOADSTATUS構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

注意

メッシュのレンダリングが可能な（ベースメッシュのダウンロードが完了し、データが壊れていない）場合には、dwFlagsメンバには、D3DRMPMESHSTATUS_RENDERABLEを格納する。ダウンロードが割り込みを受けた場合には、dwFlagsメンバには、D3DRMPMESHSTATUS_INTERRUPTEDを格納する。

IDirect3DRMProgressiveMesh::GetQuality

IDirect3DRMProgressiveMesh

プログレッシブメッシュのレンダリングクオリティを指定するD3DRMRENDERQUALITY列挙型のメンバを取得する。

構文

HRESULT GetQuality(
  LPD3DRMRENDERQUALITY lpQuality
  );

パラメータ

lpQuality
成功すれば、レンダリングクオリティを指定するD3DRMRENDERQUALITYメンバへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。

D3DRMERR_BADOBJECT
プログレッシブメッシュは無効。
D3DRMERR_BADVALUE
D3DRMRENDERQUALITYメンバへのポインタは無効。

参照

IDirect3DRMProgressiveMesh::SetQuality

IDirect3DRMProgressiveMesh::GetVertexDetail

IDirect3DRMProgressiveMesh

プログレッシブメッシュにある頂点の数を返す。

構文

HRESULT GetVertexDetail(
  LPDWORD lpdwCount
  )

パラメータ

lpdwCount
プログレッシブメッシュにある頂点の数がセットされるDWORDのアドレス。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

注意

頂点の数が取得できない場合には、このメソッドはD3DRMERR_PENDINGを返す。

IDirect3DRMProgressiveMesh::GetVertexDetailRange

IDirect3DRMProgressiveMesh

メッシュ中で使用可能な最小および最大の頂点カウントを返す。

構文

HRESULT GetVertexDetailRange(
  LPDWORD lpdwMinVertices,
  LPDWORD lpdwMaxVertices
  )

パラメータ

lpdwMinVertices
頂点の最小数がセットされるDWORD値のアドレス。
lpdwMaxVertices
頂点の最大数がセットされるDWORD値のアドレス。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

注意

頂点カウントが取得できない場合には、このメソッドはD3DRMERR_PENDINGを返す。

IDirect3DRMProgressiveMesh::Load

IDirect3DRMProgressiveMesh

プログレッシブメッシュオブジェクトをメモリ、ファイル、リソース、またはURLからロードする。ロードは同期式でも非同期式でも良い。

構文

HRESULT Load(
  LPVOID lpSource,
  LPVOID lpObjID,
  D3DRMLOADOPTIONS dloLoadflags,
  D3DRMLOADTEXTURECALLBACK lpCallback,
  LPVOID lpArg
  )

パラメータ

lpSource
ロードするオブジェクトのソースのアドレス。このソースは、dloLoadflagsパラメータで指定されているソースフラグによって、ファイル、リソース、メモリブロック、またはストリームのどれかにできる。
lpObjID
プログレッシブメッシュであるDirectXファイルレコードのIDのアドレス。これは、文字列またはUUID （dloLoadflagsによって決まる）にすることができる。lpObjIDがNULLの場合、dloLoadflagsはD3DRMLOAD_FIRSTでなければならない。
dloLoadflags
ロードを実行する方法を記述するD3DRMLOADOPTIONS型の値。以下の2つのグループのフラグをそれぞれ1つずつ含めなければならない。
  • DirectXファイル中のどのオブジェクトをロードするかを決定するには、以下のフラグを使う。
    D3DRMLOAD_BYNAME
    lpObjIDパラメータは文字列と解釈する。
    D3DRMLOAD_BYGUID
    lpObjIDパラメータはUUIDと解釈する。
    D3DRMLOAD_FIRST
    最初に発見されたプログレッシブメッシュをロードする。
  • DirectXファイルのソースを決定するには、以下のフラグを使う。
    D3DRMLOAD_FROMFILE
    lpSourceパラメータはローカルファイル名を表す文字列と解釈する。
    D3DRMLOAD_FROMRESOURCE
    lpSourceパラメータはD3DRMLOADRESOURCE構造体へのポインタとして解釈する。
    D3DRMLOAD_FROMMEMORY
    lpSourceパラメータはD3DRMLOADMEMORY構造体へのポインタとして解釈する。
    D3DRMLOAD_FROMURL
    lpSourceパラメータはURLとして解釈する。

さらに、ダウンロードを同期式か非同期式にするかを指定できる。デフォルトでは、ロードは同期式であり、Load呼び出しは、すべてのデータのロードが完了するまで、あるいはエラーが発生するまで戻らない。非同期式ロードを指定するには、以下のフラグを含める。

D3DRMLOAD_ASYNCHRONOUS － Load呼び出しは直ちに戻る。ロードの進行状態をチェックするのに、IDirect3DRMProgressiveMesh::RegisterEventsおよびIDirect3DRMProgressiveMesh::GetLoadStatusによってイベントを使用するのは、アプリケーションの責任となる。

lpCallback
D3DRMLOADTEXTURECALLBACKコールバック関数のアドレス。遭遇した任意のテクスチャをロードするのに使用される。このコールバック関数は、ローダが遭遇したテクスチャ名と、ユーザ定義のlpArgパラメータによって使われる。新しいスレッドは、このコールバック関数に対しては生成されない。アプリケーションが、テクスチャを漸次的にダウンロードしたければ、スレッドを生成し、いつものようにLPDIRECT3DRMTEXTUREを戻り値として戻らなければならない。
lpArg
D3DRMLOADTEXTURECALLBACKコールバック関数に渡されるユーザ定義データのアドレス。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_BADPMDATA
D3DRMERR_BADFILE
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

注意

プログレッシブメッシュは、初期化しない限り有効にならない。非同期式ダウンロードが指定されていれば、このAPIは、直ちに戻り、別のスレッドがダウンロードを実行するために生成される。

このメソッド、IDirect3DRMProgressiveMesh::CloneおよびIDirect3DRMProgressiveMesh::Duplicateはすべて、プログレッシブメッシュを初期化する。オブジェクトは一度しか初期化できない。したがって、プログレッシブメッシュをクローンまたは複製してから、そのクローンまたは複製したメッシュにロードすることも、以前にロードしたメッシュにロードすることもできない。

IDirect3DRMProgressiveMesh::RegisterEvents

IDirect3DRMProgressiveMesh

アプリケーションが、プログレッシブメッシュオブジェクトにイベントを登録するのを可能にする。イベントは、適切な条件が満足されたときに通知される。

構文

HRESULT RegisterEvents(
  HANDLE hEvent,
  DWORD dwFlags,
  DWORD dwReserved
  )

パラメータ

hEvent
必要な条件が満足されたときに通知されるイベント。
dwFlags
以下のフラグの1つとなる。
D3DRMPMESHEVENT_BASEMESH
ベースメッシュのダウンロードが完了すると通知されるイベント。
D3DRMPMESHEVENT_COMPLETE
すべてのデータのダウンロードが完了すると通知されるイベント。
dwReserved
0でなければならない。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。

D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

注意

このメソッドは、ロードの進行状態を監視するために使用できる。イベントは、エラーが発生した場合にも通知されるので、アプリケーションは、通知後にIDirect3DRMProgressiveMesh::GetLoadStatusメソッドを使う必要がある。

IDirect3DRMProgressiveMesh::SetDetail

IDirect3DRMProgressiveMesh

要求された詳細レベルを0.0と1.0の間に正規化して設定する。

構文

HRESULT SetDetail(
  D3DVALUE dvVal
  )

パラメータ

dvVal
詳細の要求レベル。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

注意

十分な詳細項目のダウンロードがまだ完了していなければ （ただし、時間がたてば使用可能）、要求は受け入れられて、D3DRMERR_PENDINGが返る。このエラーは通知であり、要求されたレベルが、十分な詳細が使用可能になると直ちに設定されるということを示すものである。

正規化した値0.0は頂点の最小数を表し (ベースメッシュにある頂点の数)、正規化した値1.0は頂点の最大数を表す。

IDirect3DRMProgressiveMesh::SetFaceDetail

IDirect3DRMProgressiveMesh

要求された面詳細レベルを設定する。

構文

HRESULT SetFaceDetail(
  DWORD dwCount
  )

パラメータ

dwCount
要求される面の数。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE

注意

ときには、常に要求された値から1以内であるにもかかわらず、プログレッシブメッシュを要求された面の数に設定できないことがある。これは、分割頂点が1ないし2面加えることができるからである。たとえば、SetFaceDetail(20)を使うと、プログレッシブメッシュは面の詳細を19または21だけにしか設定できないかもしれない。プログレッシブメッシュにある面の実際の数は、常にIDirect3DRMProgressiveMesh::GetFaceDetailメソッドを使って取得することができる。

十分な詳細項目のダウンロードがまだ完了していなければ（ただし、時間がたてば使用可能）、要求は受け入れられて、D3DRMERR_PENDINGが返る。このエラーは、通知であり、要求されたレベルが、十分な詳細が使用可能になると直ちに設定されるということを示すものである。要求されている詳細レベルが、プログレッシブメッシュで使用可能な詳細レベルより大きければ、D3DRMERR_REQUESTTOOLARGEが返る。

参照

IDirect3DRMProgressiveMesh::GetFaceDetail

IDirect3DRMProgressiveMesh::SetMinRenderDetail

IDirect3DRMProgressiveMesh

0.0（最小詳細レベル）から1.0（最大詳細レベル）の範囲で、ロード中にレンダリングする詳細の最小レベルを設定する。通常、プログレッシブメッシュは、ベースメッシュが使用可能になった（およびメッシュがシーングラフ中に存在するようになった）後でレンダリングされる。

構文

HRESULT SetMinRenderDetail(
  D3DVALUE dvCount
  )

パラメータ

dvCount
要求されている最小詳細。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE
D3DRMERR_REQUESTTOOSMALL

注意

このAPIは、ロード中にレンダリングされる面または頂点の（ベースメッシュより大きい）最小数を設定する。

以降のIDirect3DRMProgressiveMesh::SetDetail、IDirect3DRMProgressiveMesh::SetFaceDetail、またはIDirect3DRMProgressiveMesh::SetVertexDetail呼び出しはいつでも、このメソッドより優先される。

IDirect3DRMProgressiveMesh::SetQuality

IDirect3DRMProgressiveMesh

Direct3DRMProgressiveMeshオブジェクトのレンダリングクオリティを設定する。

構文

HRESULT SetQuality(
  D3DRMRENDERQUALITY quality
  );

パラメータ

quality
使用する新しいレンダリングクオリティを指定するD3DRMRENDERQUALITY列挙型のメンバ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

オブジェクトクオリティには、3つのコンポーネントがある。すなわち、シェーディングモード (フラットまたはグーロー。フォンは実装されておらず、デフォルトでグーローシェーディングになる)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

デバイスのクオリティを設定するには、IDirect3DRMDevice3::SetQualityを用いる。デフォルトで、デバイスクオリティはD3DRMRENDER_FLAT (フラットシェーディング、照明オン、およびソリッド塗りつぶし) である。

YDirect3DRMProgressiveMeshオブジェクトのクオリティを設定するには、SetQualityメソッドを用いる。デフォルトで、Direct3DRMProgressiveMeshオブジェクトのクオリティはD3DRMRENDER_GOURAUD (グーローシェーディング、照明オン、およびソリッド塗りつぶし) である。

ヒント: グーローシェーディングは、詳細レベルを頻繁にまたは素早く変更するプログレッシブメッシュオブジェクトについて、よりよいパフォーマンスを得られる。

Direct3D保持モードは、デバイスやオブジェクトの個々のコンポーネントに対する現在の設定の中で最も低位のクオリティで、オブジェクトにレンダリングを行う。たとえば、オブジェクトの現在のクオリティ設定がD3DRMRENDER_GOURAUDで、デバイスがD3DRMRENDER_FLATであると、オブジェクトはフラットシェーディング、ソリッド塗りつぶし、および照明オンでレンダリングされる。

オブジェクトの現在のクオリティ設定がD3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAMEで、デバイスのクオリティ設定がD3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINTであると、オブジェクトはフラットシェーディング、照明オフ、およびポイント塗りつぶしモードでレンダリングされる。

これらのルールは、Direct3DRMMeshBuilder3オブジェクトおよびDirect3DRMProgressiveMeshオブジェクトに適用される。しかし、Direct3DRMMeshオブジェクトはこれらのルールに従わない。メッシュオブジェクトはデバイスのクオリティ設定を無視し、グループクオリティ設定を用いる(デフォルトでD3DRMRENDER_GOURAUD)。

参照

IDirect3DRMProgressiveMesh::GetQuality

IDirect3DRMProgressiveMesh::SetVertexDetail

IDirect3DRMProgressiveMesh

要求された頂点詳細レベルを設定する。

構文

HRESULT SetVertexDetail(
  DWORD dwCount
  )

パラメータ

dwCount
要求されている頂点の数。

戻り値

成功すればD3DRM_OK、失敗すれば次のいずれかのエラーを返す。
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE

注意

十分な詳細項目のダウンロードが、まだ完了していなければ（ただし、時間が経てば使用可能）、要求は受け入れられて、D3DRMERR_PENDINGが返る。このエラーは通知であり、要求されたレベルが、十分な詳細が使用可能になると直ちに設定されるということを示すものである。要求されている詳細レベルが、プログレッシブメッシュで使用可能な詳細レベルより大きければ、D3DRMERR_REQUESTTOOLARGEが返る。

参照

IDirect3DRMProgressiveMesh::GetVertexDetail


IDirect3DRMShadow2

アプリケーションは、Direct3DRMShadow2オブジェクトおよびDirect3DRMShadowオブジェクトを初期化するためにIDirect3DRMShadow2インターフェイスおよびIDirect3DRMShadowインターフェイスのメソッドをそれぞれ使用する。アプリケーションがIDirect3DRM3::CreateShadowメソッドを使うときは、この初期化は不要である。初期化が必要なのは、IDirect3DRM3::CreateObjectメソッドを使って影を生成する場合だけである。 IDirect3DRM3::CreateObjectを呼び出すアプリケーションは、次にIDirect3DRMShadow2::Initメソッドを呼び出し、影を初期化する。

IDirect3DRMShadow2は、ビジュアル、照明、プレーン、オプションの影のパラメータを作成後に変更可能にすることで、IDirect3DRMShadowの機能を拡張する。 IDirect3DRMShadow2::SetOptionsによって、透明ブレンディングが有効なときにビジュアル効果を排除するオプションをセットできる。 IDirect3DRMShadow2は、IDirect3DRMShadowが提供するInitメソッドに加えて、SetVisual、GetVisual、SetLight、GetLight、SetPlane、GetPlane、SetOptions、GetOptionsメソッドを提供する。

IDirect3DRMShadow2インターフェイスのメソッドは、以下のグループにまとめることができる。
初期化 | Init
パラメータの設定と取得 | GetLight
 | GetOptions
 | GetPlane
 | GetVisual
 | SetLight
 | SetOptions
 | SetPlane
 | SetVisual

すべてのCOMインターフェイスと同様、IDirect3DRMShadow2およびIDirect3DRMShadowインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMShadow2およびIDirect3DRMShadowインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMShadow2オブジェクトは、IDirect3DRM3::CreateShadowメソッドの使用によって取得される。

IDirect3DRMShadow2::GetLight

IDirect3DRMShadow2

影の作成時に使用する照明ソースを取得する。照明が影に関連付けられていない場合、エラーが返される。

構文

HRESULT GetLight(
  LPDIRECT3DRMLIGHT  *lplpDirect3DRMLight);

パラメータ

lplpDirect3DRMLight
照明ソースを受け取るポインタ。

戻り値

次の値のうち1つを返す。
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMShadow2::GetOptions

IDirect3DRMShadow2

影のオプションフラグを取得する。

構文

HRESULT GetOptions(
  LPDWORD pdwOptions);

パラメータ

pdwOptions
現在の影のオプションを取得するポインタ。有効なフラグは次の通りである。
D3DRMSHADOW_TRUEALPHA
真のアルファが有効なときにレンダリングした場合、ビジュアル効果を持たない影を作成する。

戻り値

次の値のうち1つを返す。
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMShadow2::GetPlane

IDirect3DRMShadow2

影のプレーンを取得する。ポイントは 影のフレームを起点とする。法線はワールド空間中にある。

構文

HRESULT SetPlane(
  LPD3DVALUE pdvPX,
  LPD3DVALUE pdvPY,
  LPD3DVALUE pdvPZ,
  LPD3DVALUE pdvNX,
  LPD3DVALUE pdvNY,
  LPD3DVALUE pdvNZ);

パラメータ

pdvPX, pdvPY, pdvPZ
影のフレームを起点とする影のプレーン上のポイントのx、y、z値を受け取るポインタ。この値は、D3DVALUEデータタイプへのポインタとして指定される。
pdvNX, pdvNY, pdvNZ
影のプレーンに対する法線のx、y、z値をワールド空間ベクトルとして受け取るポインタ。この値は、D3DVALUEデータタイプへのポインタとして指定される。

戻り値

次の値のうち1つを返す。
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMShadow2::GetVisual

IDirect3DRMShadow2

影を作成するビジュアルを取得する。

構文

HRESULT GetVisual(
  LPDIRECT3DRMVISUAL  *lplpDirect3DRMVisual);

パラメータ

lplpDirect3DRMVisual
影を作成するビジュアルを受け取るポインタ。

戻り値

次の値のうち1つを返す。
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMShadow2::Init

IDirect3DRMShadow2

Direct3DRMShadow2オブジェクトを初期化する。

構文

HRESULT Init(
  LPUNKNOWN pUnk,
  LPDIRECT3DRMLIGHT lpD3DRMLight,
  D3DVALUE px,
  D3DVALUE py,
  D3DVALUE pz,
  D3DVALUE nx,
  D3DVALUE ny,
  D3DVALUE nz);

パラメータ

pUnk
影を付けるオブジェクトへのポインタ。
lpD3DRMLight
影の元になる照明を 提供するDirect3DRMLightオブジェクトへのポインタ。
px, py, pz
影が付けられるプレーン上の点の座標。
nx, ny, nz
影が付けられるプレーン上の法線ベクトルの座標。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

影を初期化するためこのメソッドを呼び出した後、IDirect3DRMFrame3::AddVisualを使用して、影を作成するビジュアルが存在するフレームと同じフレームに影を追加する。

IDirect3DRMShadow2::SetLight

IDirect3DRMShadow2

影の作成時に使用する照明を設定する。

構文

HRESULT SetLight(
  LPDIRECT3DRMLIGHT lpDirect3DRMLight,
  DWORD dwFlags);

パラメータ

lpDirect3DRMLight
影の作成時に使用する照明。
dwFlags
予約済み。0でなければならない。

戻り値

次の値のうち1つを返す。
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMShadow2::SetOptions

IDirect3DRMShadow2

影のオプションフラグを設定する。

構文

HRESULT SetOptions(
  DWORD dwOptions);

パラメータ

dwOptions
影のオプション。有効なフラグは次の通りである。
D3DRMSHADOW_TRUEALPHA
透明ブレンディング (アルファブレンディング) が有効なときにビジュアル効果を持たない影を作成する。IDirect3DRMDevice3::SetRenderModeを呼び出し、透明ブレンディングを有効にする。

戻り値

次の値のうち1つを返す。
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMShadow2::SetPlane

IDirect3DRMShadow2

影のプレーンを設定する。ポイントは影のフレームを起点とする。法線はワールド空間中にある。

構文

HRESULT SetPlane(
  D3DVALUE dvPX,
  D3DVALUE dvPY,
  D3DVALUE dvPZ,
  D3DVALUE dvNX,
  D3DVALUE dvNY,
  D3DVALUE dvNZ,
  DWORD dwFlags);

パラメータ

dvPX, dvPY, dvPZ
D3DVALUEデータタイプで指定した影のフレームを起点とする、影のプレーン上のポイント。
dvNX, dvNY, dvNZ
D3DVALUEデータタイプとして指定した、ワールド空間ベクトルとしての影のプレーンに対する法線。
dwFlags
予約済み。0でなければならない。

戻り値

次の値のうち1つを返す。
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMShadow2::SetVisual

IDirect3DRMShadow2

影を作成するビジュアルを設定する。

構文

HRESULT SetVisual(
    LPDIRECT3DRMVISUAL lpDirect3DRMVisual,
    DWORD dwFlags);

パラメータ

lpDirect3DRMVisual
影を作成するビジュアル。
dwFlags
予約済み。0でなければならない。

戻り値

次の値のうち1つを返す。
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

このメソッドは、DirectX version 6.0とともに導入された。


IDirect3DRMTexture3

Microsoft DirectX version 6.0は、IDirect3DRMTexture3インターフェイスを導入している。IDirect3DRMTexture3は、それが置換する旧のIDirect3DRMTexture2とIDirect3DRMTextureインターフェイスを拡張し、テクスチャ管理に対するより洗練された制御を可能にする。テキスチャ管理の概要は、「テクスチャ」を参照すること。Direct3D保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRMTexture3は、テクスチャの変更リージョンを指定可能にすることで、Changedメソッドの機能を拡張する。また、これは、テクスチャ管理キャッシングメソッドのGetCacheOptionsとSetCacheOptionsも提供する。IDirect3DRMTexture3が提供するその他の新しいメソッドとして、GetSurface、SetDownSampleCallback、および<SetValidationCallbackがある。

旧のIDirect3DRMTexture2が追加し、IDirect3DRMTexture3もサポートする以前の新しいメソッドには、InitFromResource2が含まれる。これは、DLLおよび現在の実行ファイルを除く実行可能プログラムからリソースをロードできるようにする。InitFromImageメソッドは、メモリ中のイメージからテクスチャを生成する。このメソッドは、IDirect3DRM3::CreateTextureメソッドと同等である。GenerateMIPMapメソッドは、ソースイメージからミップマップを作り出す。

テクスチャを作成するときに不必要な遅延を避けるため、再利用するテクスチャは保持しておいて、必要になるたびに作成しなくてすむようにする。最適なパフォーマンスを得るには、使用するデバイスのサポートするテクスチャサーフェスフォーマットを使う。これにより、テクスチャを作成してから変更するときに、手間のかかるフォーマット変換を回避することができる。

IDirect3DRM3::LoadTextureによりテクスチャコールバック関数にロードされたテクスチャへの参照を保持する方法を示す例は、IDirect3DRM3::LoadTextureの注意を参照すること。

IDirect3DRMTexture3インターフェイスのメソッドは、以下のグループにまとめることができる。
色 | GetColors
 | SetColors
デカール | GetDecalOrigin
 | GetDecalScale
 | GetDecalSize
 | GetDecalTransparency
 | GetDecalTransparentColor
 | SetDecalOrigin
 | SetDecalScale
 | SetDecalSize
 | SetDecalTransparency
 | SetDecalTransparentColor
イメージ | GetImage
初期化 | InitFromFile
 | InitFromImage
 | InitFromResource2
 | InitFromSurface
ミップマップ生成 | GenerateMIPMap
その他 | GetCacheOptions
 | GetSurface
 | SetCacheOptions
 | SetDownsampleCallback
 | SetValidationCallback
レンダラ通知 | Changed
シェーディング | GetShades
 | SetShades

すべてのCOMインターフェイスと同様、IDirect3DRMTexture3インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMTexture3インターフェイスは、IDirect3DRMObjectインターフェイスから以下のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRMTexture3オブジェクトを作成するには、IDirect3DRM3::CreateTextureまたはIDirect3DRM3::CreateTextureFromSurfaceを呼び出す。

IDirect3DRMTexture3::Changed

IDirect3DRMTexture3

アプリケーションでテクスチャのどのリージョンを変更するかを指定可能にする。

構文

HRESULT Changed(
  DWORD dwFlags,
  DWORD dwcRects,
  LPRECT pRects);

パラメータ

dwFlags
次のフラグを定義する。
D3DRMTEXTURE_CHANGEDPIXELS
ピクセル値が変更されたことを示す。
D3DRMTEXTURE_CHANGEDPALETTE
パレットが変更されたことを示す。
D3DRMTEXTURE_INVALIDATEONLY
テクスチャリージョンが無効になったが、アプリケーションで更新する必要がないことを示す。これは、Direct3D保持モードがテクスチャをレンダリングする前に、アプリケーションを呼び出し、1次ソースを更新する。このコールバックはSetValidationCallbackによってセットされる。
dwcRects
pRectsがポイントするRECT構造体の数。この値が0で、dwFlagsにD3DRMTEXTURE_CHANGEDPIXELSまたはD3DRMTEXTURE_INVALIDATEONLYが含まれる場合、テクスチャ全体が更新される。
pRects
変更されたピクセルのリージョンを記述するRECT構造体の配列。dwFlagsにD3DRMTEXTURE_CHANGEDPIXELSまたはD3DRMTEXTURE_INVALIDATEONLYが含まれる場合、pRectsパラメータだけが有効である。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入されたこのメソッドは、旧のIDirect3DRMTexture::Changedメソッドを置換する。この旧のメソッドには、アプリケーションがテクスチャのピクセルまたはパレットを変更したかどうかを示す2つのブールパラメータがある。

IDirect3DRMTexture3::GenerateMIPMap

IDirect3DRMTexture3

単一のイメージソースからミップマップを生成する。

構文

HRESULT GenerateMIPMap(
  DWORD dwFlags
  );

パラメータ

dwFlags
0をセットする必要がある。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、テクスチャの作成後はいつでも呼び出すことができる。このメソッドは、レベル間の双一次フィルタリングによってソースイメージのミップマップを1×1の解像度まで生成できる。ミップマップが生成されると、マップはいつでも使用可能で、IDirect3DRMTexture3::Changedを呼び出して、更新することができる。ミップマッピングを使用する場合には、IDirect3DRMDevice3::SetTextureQualityを使用して、テクスチャのクオリティをD3DRMTEXTURE_MIPNEAREST、D3DRMTEXTURE_MIPLINEAR、D3DRMTEXTURE_LINEARMIPNEAREST、またはD3DRMTEXTURE_LINEARMIPLINEARに変更することを忘れてはならない。特別のミップマップレベルは、テクスチャクオリティがミップマッピング型を含み、かつハードウェアデバイスがミップマッピングをサポートしない限り、ハードウェアデバイスのビデオメモリに格納されない。

参照

「ミップマップ」

IDirect3DRMTexture3::GetCacheOptions

IDirect3DRMTexture3

テクスチャメモリが制限されている場合に、テクスチャ管理で現在のテクスチャをどのように処理するかに関する情報を取得する。

構文

HRESULT GetCacheOptions(
  LPLONG lplImportance,
  LPDWORD lpdwFlags);

パラメータ

lplImportance
テクスチャの相対的な重要度を示す符号付きの値。デフォルトは0である。値が大きければ、重要度が高いことを示す。この値を使用して、テクスチャメモリが制限されている場合にどのテクスチャを最後にダウンサンプルするかを計算する。
lpdwFlags
現在のテクスチャに関するテクスチャ管理システムを制御するフラグ。現在定義されているフラグは、次の通りである。
D3DRMTEXTURE_FORCERESIDENT
テクスチャを(ハードウェアシナリオ中の) ビデオメモリに保持することを示す。
D3DRMTEXTURE_STATIC
テクスチャが変わらないことを示す。アプリケーションは、決してChangedメソッドを使用しない。
D3DRMTEXTURE_DOWNSAMPLEPOINT
テクスチャのダウンサンプル時にポイントフィルタリングを使用することを示す。
D3DRMTEXTURE_DOWNSAMPLEBILINEAR
テクスチャのダウンサンプル時に双一次フィルタリングを使用することを示す。
D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH
テクスチャのダウンサンプル時にピクセル深度が減少することを示す。
D3DRMTEXTURE_DOWNSAMPLENONE
テクスチャを決してダウンサンプルしないことを示す。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMTexture3::GetColors

IDirect3DRMTexture3

Direct3DRMTexture2オブジェクトをレンダリングするために使用する色の最大数を取得する。

構文

DWORD GetColors( );

戻り値

色の数を返す。

注意

このメソッドは、Direct3DRMTexture2オブジェクトが作成された元のイメージ中の色の数ではなく、Direct3DRMTexture2オブジェクトが量子化された色の数を返す。したがって、戻り値の色の数は通常、IDirect3DRM3::SetDefaultTextureColorsメソッドを呼び出して設定した色に一致する。ただし、IDirect3DRMTexture3::SetColorsメソッドを明示的に呼び出してDirect3DRMTexture2オブジェクトの色を変更した場合は、そうはならない。

参照

IDirect3DRMTexture3::SetColors

IDirect3DRMTexture3::GetDecalOrigin

IDirect3DRMTexture3

デカールの現在の原点を取得する。

構文

HRESULT GetDecalOrigin(
  LONG  *lplX,
  LONG  *lplY
  );

パラメータ

lplX, lplY
メソッドが戻ったとき、デカールの原点がセットされる変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMTexture3::SetDecalOrigin

IDirect3DRMTexture3::GetDecalScale

IDirect3DRMTexture3

指定のデカールのスケーリングプロパティを取得する。

構文

DWORD GetDecalScale( );

戻り値

成功すればスケーリングプロパティ、失敗すれば-1を返す。

参照

IDirect3DRMTexture3::SetDecalScale

IDirect3DRMTexture3::GetDecalSize

IDirect3DRMTexture3

デカールのサイズを取得する。

構文

HRESULT GetDecalSize(
  D3DVALUE *lprvWidth,
  D3DVALUE *lprvHeight
  );

パラメータ

lprvWidth, lprvHeight
メソッドが戻ったとき、デカールの幅と高さがセットされる変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMTexture3::SetDecalSize

IDirect3DRMTexture3::GetDecalTransparency

IDirect3DRMTexture3

デカールの透明プロパティを取得する。

構文

BOOL GetDecalTransparency( );

戻り値

デカールが透明な色を持っているとTRUE、そうでないとFALSEを返す。

参照

IDirect3DRMTexture3::SetDecalTransparency

IDirect3DRMTexture3::GetDecalTransparentColor

IDirect3DRMTexture3

デカールの透明な色を取得する。

構文

D3DCOLOR GetDecalTransparentColor( );

戻り値

透明な色の値を返す。

参照

IDirect3DRMTexture3::SetDecalTransparentColor

IDirect3DRMTexture3::GetImage

IDirect3DRMTexture3

テクスチャを作成したときに使用したイメージのアドレスを返す。

構文

D3DRMIMAGE *GetImage( );

戻り値

現在のDirect3DRMTexture2オブジェクトを生成するのに使用したD3DRMIMAGE構造体のアドレスを返す。

IDirect3DRMTexture3::GetShades

IDirect3DRMTexture3

レンダリング時にテクスチャ中の各色に対して使用されるシェード数を返す。

構文

DWORD GetShades( );

戻り値

シェード数を返す。

参照

IDirect3DRMTexture3::SetShades

IDirect3DRMTexture3::GetSurface

IDirect3DRMTexture3

テクスチャを作成するために使用したDirectDrawサーフェスを取得する。これは、CreateTextureFromSurfaceまたはInitFromSurfaceがテクスチャの作成に使用された場合にのみ、サーフェスを取得する。

構文

HRESULT GetSurface(
  DWORD dwFlags,
  LPDIRECTDRAWSURFACE *lplpDDS);

パラメータ

dwFlags
フラグ値。0でなければならない。
lplpDDS
対応するDirectDrawサーフェスのインターフェイスへのポインタを受け取る変数のアドレス。インターフェイスの参照カウントは、インターフェイスが呼び出し元に渡される前にインクリメントされることに注意すること。

戻り値

次の値のうち1つを返す。
D3DRMERR_NOTCREATEDFROMDDS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMTexture3::InitFromFile

IDirect3DRMTexture3

指定ファイル中の情報を使用してDirect3DRMTexture2オブジェクトを初期化する。

構文

HRESULT InitFromFile(
  LPCSTR filename
  );

パラメータ

filename
テクスチャの初期化情報を取得するファイルを指定する文字列。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

IDirect3DRM3::CreateTextureまたはIDirect3DRM3::CreateTextureFromSurfaceメソッドを使用して、初期化するDirect3DRMTexture2オブジェクトを作成しておかなければならない。

参照

IDirect3DRMTexture3::InitFromImage, IDirect3DRMTexture3::InitFromResource2, IDirect3DRMTexture3::InitFromSurface

IDirect3DRMTexture3::InitFromImage

IDirect3DRMTexture3

メモリ中のイメージからテクスチャを初期化する。

構文

HRESULT InitFromImage(
  LPD3DRMIMAGE lpImage
  );

パラメータ

lpImage
テクスチャのソースを記述するD3DRMIMAGE構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

IDirect3DRM3::CreateTextureまたはIDirect3DRM3::CreateTextureFromSurfaceメソッドを使用して、初期化するIDirect3DRMTexture3オブジェクトを作成しておかなければならない。

参照

IDirect3DRMTexture3::InitFromFile, IDirect3DRMTexture3::InitFromResource2, IDirect3DRMTexture3::InitFromSurface

IDirect3DRMTexture3::InitFromResource2

IDirect3DRMTexture3

指定のリソースからDirect3DRMTexture2オブジェクトを初期化する。

構文

HRESULT InitFromResource2(
  HModule hModule,
  LPCTSTR strName,
  LPCTSTR strType
  );

パラメータ

hModule
指定のリソースのハンドル。
strName
テクスチャを初期化するのに使用するリソース名。
strType
テクスチャを初期化するのに使用するリソースのタイプ名。テクスチャは、RT_BITMAおよびRT_RCDATAリソースタイプまたはユーザ定義タイプの中に格納できる。リソースタイプがユーザ定義されていれば、このメソッドは、そのリソースモジュールハンドル、リソース名、およびリソースタイプをFindResource Win32 APIに渡す。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

IDirect3DRM3::CreateTextureまたはIDirect3DRM3::CreateTextureFromSurfaceメソッドを使用して、初期化するIDirect3DRMTexture3オブジェクトを作成しておかなければならない。

参照

IDirect3DRMTexture3::InitFromFile, IDirect3DRMTexture3::InitFromImage, IDirect3DRMTexture3::InitFromSurface

IDirect3DRMTexture3::InitFromSurface

IDirect3DRMTexture3

指定したDirectDrawサーフェスからのデータを使用して、Direct3DRMTexture2オブジェクトを初期化する。このメソッドは、IDirect3DRMTexture3::InitFromSurfaceと同じ機能を実行する。

構文

HRESULT InitFromSurface(
  LPDIRECTDRAWSURFACE lpDDS
  );

パラメータ

lpDDS
初期化情報を取得するDirectDrawサーフェスのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

DirectDrawサーフェスからテクスチャを作成する場合、サーフェスをシステムメモリ中に作成するのが最善である。これによって、ソフトウェアデバイスの最適なパフォーマンスが可能になり、Direct3D保持モードがハードウェアデバイスに対してビデオメモリの使用をより効率的に管理できるようになる。

参照

IDirect3DRMTexture3::InitFromFile, IDirect3DRMTexture3::InitFromImage, IDirect3DRMTexture3::InitFromResource2

IDirect3DRMTexture3::SetCacheOptions

IDirect3DRMTexture3

テクスチャメモリが制限されている場合に、テクスチャ管理でこのテクスチャをどのように処理するかに関する情報を提供する。

構文

HRESULT SetCacheOptions(
  LONG lImportance,
  DWORD dwFlags);

パラメータ

lImportance
テクスチャの相対的な重要度を示す符号付きの値。デフォルトは0である。値が大きければ、重要度が高いことを示す。この値を使用して、テクスチャメモリが制限されている場合にどのテクスチャを最後にダウンサンプルするかを計算する。
dwFlags
現在のテクスチャに関するテクスチャ管理システムを制御するフラグ。現在定義されているフラグは、次の通りである。
D3DRMTEXTURE_FORCERESIDENT
テクスチャを(ハードウェアシナリオ中の) ビデオメモリに保持することを示す。
D3DRMTEXTURE_STATIC
テクスチャが変わらないことを示す。
D3DRMTEXTURE_DOWNSAMPLEPOINT
テクスチャのダウンサンプル時にポイントフィルタリングを使用することを示す。
D3DRMTEXTURE_DOWNSAMPLEBILINEAR
テクスチャのダウンサンプル時に双一次フィルタリングを使用することを示す。
D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH
テクスチャのダウンサンプル時にピクセル深度が減少することを示す。下位ビットの深度が使用可能でなければ、テクスチャのサイズが減少する。
D3DRMTEXTURE_DOWNSAMPLENONE
テクスチャを決してダウンサンプルしないことを示す。デフォルト値はD3DRMTEXTURE_DOWNSAMPLEPOINTである。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMTexture3::SetColors

IDirect3DRMTexture3

Direct3DRMTexture2オブジェクトをレンダリングするのに使用する色の最大数を設定する。このメソッドは、ランプカラーモデルに限り必要となる。

構文

HRESULT SetColors(
  DWORD ulColors
  );

パラメータ

ulColors
色の数。デフォルト値は8である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMTexture3::GetColors

IDirect3DRMTexture3::SetDecalOrigin

IDirect3DRMTexture3

デカールの左上からのオフセットとしてデカールの原点を設定する。

構文

HRESULT SetDecalOrigin(
  LONG lX,
  LONG lY
  );

パラメータ

lX, lY
デカール座標でのデカールの新しい原点。デフォルトの原点は[0, 0]である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デカール原点は、レンダリング時にそのフレームの位置にマップされる。たとえば、十字のデカールの原点は、デカールの中点に設定され、下向きの矢印の原点は、底辺にそった中点に設定される。

このメソッドは、Direct3DRMTextureInterpolatorオブジェクトにデカール原点を追加するためにも使用する。

参照

IDirect3DRMTexture3::GetDecalOrigin

IDirect3DRMTexture3::SetDecalScale

IDirect3DRMTexture3

デカールのスケーリングプロパティを設定する。

構文

HRESULT SetDecalScale(
  DWORD dwScale
  );

パラメータ

dwScale
このパラメータがTRUEの場合、デカールをスケーリングする場合に深度が考慮され、デカールがシーンのフレーム上のテクスチャである場合、ビューアから遠くにあれば小さく、ビューアの近くにあれば大きくスケーリングされる。FALSEの場合、深度情報は無視され、デカールはビューアからの遠近にかかわらず同じサイズとなる。デフォルト値はTRUEである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMTexture3::GetDecalScale

IDirect3DRMTexture3::SetDecalSize

IDirect3DRMTexture3

シーン中のデカールの深度に従って、デカールがスケーリングされる場合に、使用されるデカールのサイズを設定する。

構文

HRESULT SetDecalSize(
  D3DVALUE rvWidth,
  D3DVALUE rvHeight
  );

パラメータ

rvWidth, rvHeight
モデル座標における、デカールの新しい幅と高さ。デフォルトサイズは、[1, 1]である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMTextureInterpolatorオブジェクトにデカールサイズキーを追加するためにも使用する。

参照

IDirect3DRMTexture3::GetDecalSize

IDirect3DRMTexture3::SetDecalTransparency

IDirect3DRMTexture3

デカールの透明プロパティを設定する。

構文

HRESULT SetDecalTransparency(
  BOOL bTransp
  );

パラメータ

bTransp
このパラメータがTRUEの場合、デカールは透明の色を持つ。FALSEの場合、不透明の色を持つ。デフォルト値はFALSEである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMTexture3::GetDecalTransparency

IDirect3DRMTexture3::SetDecalTransparentColor

IDirect3DRMTexture3

デカールの透明な色を設定する。

構文

HRESULT SetDecalTransparentColor(
  D3DCOLOR rcTransp
  );

パラメータ

rcTransp
新しい透明な色。デフォルトの透明な色は黒である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMTextureInterpolatorオブジェクトにデカールの透明色キーを追加するためにも使用する。

参照

IDirect3DRMTexture3::GetDecalTransparentColor

IDirect3DRMTexture3::SetDownsampleCallback

IDirect3DRMTexture3

テクスチャのダウンサンプル時に、D3DRM 組み込みメソッドを使用するのではなく、テクスチャ管理が使用するコールバックを指定する。コールバックがすでに指定されている場合、新しいコールバックは旧のものを置換する。コールバックがNULLならば、現在のコールバックは削除される。

構文

typedef HRESULT (CDECL *D3DRMDOWNSAMPLECALLBACK)
  (LPVOID pArg,
  LPDIRECTDRAWSURFACE pDDSSrc,
  LPDIRECTDRAWSURFACE pDDSDst);

HRESULT SetDownsampleCallback(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  D3DRMDOWNSAMPLECALLBACK pCallback,
  LPVOID pArg);

パラメータ

pCallback
ダウンサンプリングを実行するために呼び出されるコールバック関数へのポインタ。値NULLは、現在のコールバックが削除されることを示す。
pArg
呼び出し時にコールバックに渡されるアプリケーション固有のデータ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

ダウンサンプリングは、ビデオメモリがオーバーロードになり、テクスチャサーフェスのサイズを削減する必要があるときに実行される。Direct3D保持モードでは、DirectDrawブロック転送や双一次フィルタリングなどの、テクスチャサイズを削減するデフォルトのメソッドが提供されるが、ユーザは独自のメソッドを持つコールバックを定義してテクスチャサイズをスケールダウンすることができる。

このメソッドは、DirectX version 6.0とともに導入された。

参照

D3DRMDOWNSAMPLECALLBACK

IDirect3DRMTexture3::SetShades

IDirect3DRMTexture3

レンダリング時に、Direct3DRMTexture2オブジェクトの各色に対して使用するシェードの最大数を設定する。このメソッドは、ランプカラーモデルに限り必要となる。

構文

HRESULT SetShades(
  DWORD ulShades
  );

パラメータ

ulShades
新しいシェード数。この値は、2の累乗でなければならない。デフォルト値は16である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMTexture3::GetShades

IDirect3DRMTexture3::SetValidationCallback

IDirect3DRMTexture3

1次ソーステクスチャの妥当性検査と更新を行うコールバック関数をセットする。

構文

typedef HRESULT (CDECL *D3DRMVALIDATIONCALLBACK)
  (LPVOID pArg,
  DWORD dwFlags,
  DWORD dwcRects,
  LPRECT pRects);

HRESULT SetValidationCallback(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  D3DRMVALIDATIONCALLBACK pCallback,
  LPVOID pArg);

パラメータ

pCallback
妥当性検査を実行するために呼び出されるコールバック関数へのポインタ。コールバックがすでに指定されている場合、新しいコールバックは旧のものを置換する。NULLが指定されていれば、現在のコールバックは削除される。
pArg
呼び出し時にコールバックに渡されるアプリケーション固有のデータ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

Direct3D保持モードは、変更済みであるが更新されていないことを意味する無効のマークが付けられたテクスチャリージョンを、更新する必要があるときに、テクスチャ妥当性検査コールバックを呼び出す。アプリケーションは1次ソースを更新し、戻る。

このメソッドは、DirectX version 6.0とともに導入された。

参照

D3DRMVALIDATIONCALLBACK


IDirect3DRMUserVisual

アプリケーションは、Direct3DRMUserVisualオブジェクトを初期化するためにIDirect3DRM3::CreateUserVisualインターフェイスのメソッドを使用する。アプリケーションがIDirect3DRM3::CreateObjectメソッドを使うときは、この初期化は不要である。初期化が必要なのは、IDirect3DRM3::CreateObjectメソッドを使ってビジュアルオブジェクトを生成する場合だけである。IDirect3DRM3::CreateObjectを呼び出すアプリケーションは、次にIDirect3DRMUserVisual::Initメソッドを呼び出し、オブジェクトを初期化する。

ユーザビジュアルオブジェクトはアプリケーション定義データであり、アプリケーションはこれをシーンに追加し、一般にはカスタマイズしたレンダリングモジュールを使用してレンダリングすることができる。たとえば、アプリケーションは、サウンドをユーザビジュアルオブジェクトとしてシーンに追加し、再生中にレンダリングすることができる。D3DRMUSERVISUALCALLBACKコールバック関数実行中にアプリケーションがレンダリング状態を変更する場合、この関数から復帰する前にレンダリング状態を復元する必要もある。

IDirect3DRMUserVisualインターフェイスはInitメソッドをサポートする。

すべてのCOMインターフェイスと同様、IDirect3DRMUserVisuaインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMUserVisualインターフェイスは、IDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMUserVisualオブジェクトは、IDirect3DRM3::CreateUserVisualメソッドの使用によって取得される。

IDirect3DRMUserVisual::Init

IDirect3DRMUserVisual

Direct3DRMUserVisualオブジェクトを初期化する。

構文

HRESULT Init(
  D3DRMUSERVISUALCALLBACK d3drmUVProc,
  void  *lpArg
  );

パラメータ

d3drmUVProc
アプリケーション定義のD3DRMUSERVISUALCALLBACKコールバック関数。
lpArg
コールバック関数に渡されるアプリケーション定義のデータ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

アプリケーションはIDirect3DRM3::CreateUserVisualメソッドを呼び出し、ユーザビジュアルオブジェクトの作成と初期化を同時に行うことができる。IDirect3DRMUserVisual::Initを使う必要があるのは、IDirect3DRM3::CreateObjectメソッドによってユーザビジュアルオブジェクトを作成した場合だけである。


IDirect3DRMViewport2

アプリケーションは、ビューポートオブジェクトと互いにやり取りするためにIDirect3DRMViewport2インターフェイスのメソッドを使用する。概念の概要については、「ビューポート」を参照すること。Microsoft DirectX version 6.0は、IDirect3DRMViewport2インターフェイスを導入している。IDirect3DRMViewport2は、何をクリアするかを示すフラグパラメータをClearメソッドに追加することで、それが置換する旧のIDirect3DRMViewportインターフェイスを拡張する。Direct3D保持モードインターフェイスの履歴については、「インターフェイスの変更点」を参照すること。

IDirect3DRMViewport2インターフェイスのメソッドは、以下のグループにまとめることができる。

カメラ | 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
 | InverseTransformVectors
 | Transform
 | TransformVectors

すべてのCOMインターフェイスと同様、IDirect3DRMViewport2インターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMViewport2インターフェイスはIDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMViewportオブジェクトは、IDirect3DRM3::CreateViewportメソッドの使用によって取得される。

IDirect3DRMViewport2::Clear

IDirect3DRMViewport2

現在の背景色で、指定されたビューポートをクリアする。これは、何をクリアするかを示すフラグを提供するIDirect3DRMViewport::Clearの拡張バージョンである。IDirect3DRMViewport::Clearはパラメータをとらない。

構文

HRESULT Clear(
  DWORD dwFlags);

パラメータ

dwFlags
次のフラグは、現在定義されているもので、論理的に組み合わせることが可能である。
D3DRMCLEAR_TARGET
出力先レンダリングサーフェスのみをクリアする。
D3DRMCLEAR_ZBUFFER
zバッファサーフェスのみをクリアする。
D3DRMCLEAR_DIRTYRECTS
使用済み方形リストのみをクリアする。
D3DRMCLEAR_ALL
ターゲット、zバッファ、使用済み方形リストをクリアする。このフラグはIDirect3DRMViewport::Clearの使用と類似している。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMViewport2::Configure

IDirect3DRMViewport2

ビューポートの原点とサイズを再設定する。

構文

HRESULT Configure(
  LONG lX,
  LONG lY,
  DWORD dwWidth,
  DWORD dwHeight
  );

パラメータ

lX, lY
ビューポートの新しい位置。
dwWidth, dwHeight
ビューポートの新しい幅と高さ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

lX + dwWidthがデバイスの幅より大きい場合、lY + dwHeightがデバイスの高さより大きい場合、あるいはlX、lY、dwWidth、dwHeightのいずれかの値が0以下である場合、このメソッドはD3DRMERR_BADVALUEを返す。

IDirect3DRMViewport2::ForceUpdate

IDirect3DRMViewport2

ビューポートの領域を強制的に更新する。指定された領域は、次回のIDirect3DRMDevice3::Updateメソッドの呼び出しでスクリーンにコピーされる。

構文

HRESULT ForceUpdate(
  DWORD dwX1,
  DWORD dwY1,
  DWORD dwX2,
  DWORD dwY2
  );

パラメータ

dwX1, dwY1
更新領域の左上隅の座標。
dwX2, dwY2
更新領域の右下隅の座標。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

システムは、指定された矩形よりも大きなリージョンを更新することがある。場合によっては、ウィンドウ全体が更新されることもある。

IDirect3DRMViewport2::GetBack

IDirect3DRMViewport2

ビューポートのバッククリッピングプレーンの位置を取得する。

構文

D3DVALUE GetBack( );

戻り値

バッククリッピングプレーンとカメラとの距離を記述する値を返す。

参照

IDirect3DRMViewport2::SetBack, 「視錐台」

IDirect3DRMViewport2::GetCamera

IDirect3DRMViewport2

ビューポートのカメラを取得する。

構文

HRESULT GetCamera(
  LPDIRECT3DRMFRAME3 *lpCamera
  );

パラメータ

lpCamera
カメラを表すDirect3DRMFrameオブジェクトが入る変数へのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMViewport2::SetCamera, 「カメラ」

IDirect3DRMViewport2::GetDevice

IDirect3DRMViewport2

ビューポートと関連付けられたデバイスを取得する。

構文

HRESULT GetDevice(
  LPDIRECT3DRMDEVICE3 *lpD3DRMDevice
  );

パラメータ

lpD3DRMDevice
デバイスオブジェクトを示す変数のアドレス。デバイスに関する詳細は、「出力デバイス」を参照すること。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMViewport2::GetDirect3DViewport

IDirect3DRMViewport2

現在のDirect3DRMViewportに対応するDirect3Dビューポートを取得する。

構文

HRESULT GetDirect3DViewport(
  LPDIRECT3DVIEWPORT  *lplpD3DViewport
  );

パラメータ

lplpD3DViewport
Direct3DViewportオブジェクトへのポインタが入るアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMViewport2::GetField

IDirect3DRMViewport2

ビューポートのビューフィールドを取得する。

構文

D3DVALUE GetField( );

戻り値

ビューのフィールドを示す値を返す。

参照

IDirect3DRMViewport2::SetField, 「視錐台」

IDirect3DRMViewport2::GetFront

IDirect3DRMViewport2

ビューポートのフロントクリッピングプレーンの位置を取得する。

構文

D3DVALUE GetFront( );

戻り値

カメラからフロントクリッピングプレーンまでの距離を記述する値を返す。

参照

IDirect3DRMViewport2::SetFront, 「視錐台」

IDirect3DRMViewport2::GetHeight

IDirect3DRMViewport2

ビューポートの高さをピクセル単位で取得する。

構文

DWORD GetHeight( );

戻り値

高さをピクセル単位で返す。

IDirect3DRMViewport2::GetPlane

IDirect3DRMViewport2

フロントクリッピングプレーン上のビューポートのサイズを取得する。

構文

HRESULT GetPlane(
  D3DVALUE *lpd3dvLeft,
  D3DVALUE *lpd3dvRight,
  D3DVALUE *lpd3dvBottom,
  D3DVALUE *lpd3dvTop
  );

パラメータ

lpd3dvLeft, lpd3dvRight, lpd3dvBottom, lpd3dvTop
フロントクリッピングプレーン上のビューポートのサイズを受け取る変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMViewport2::SetPlane

IDirect3DRMViewport2::GetProjection

IDirect3DRMViewport2

ビューポートの射影タイプを取得する。ビューポートには、平行投影と透視投影のどちらでも用いることができる。

構文

D3DRMPROJECTIONTYPE GetProjection( );

戻り値

D3DRMPROJECTIONTYPE列挙型のメンバの1つを返す。

参照

IDirect3DRMViewport2::SetProjection

IDirect3DRMViewport2::GetUniformScaling

IDirect3DRMViewport2

ウィンドウのサイズより大きな表示ボリュームをスケーリングするために用いられる、スケール特性を取得する。

構文

BOOL GetUniformScaling( );

戻り値

ビューポートが一定の比率でスケーリングされる場合はTRUE、そうでなければFALSEを返す。

参照

IDirect3DRMViewport2::SetUniformScaling

IDirect3DRMViewport2::GetWidth

IDirect3DRMViewport2

ビューポートの幅をピクセル単位で取得する。

構文

DWORD GetWidth( );

戻り値

幅をピクセル単位で返す。

IDirect3DRMViewport2::GetX

IDirect3DRMViewport2

デバイスの上のビューポート始点のx座標オフセットを取得する。

構文

LONG GetX( );

戻り値

xオフセットを返す。

IDirect3DRMViewport2::GetY

IDirect3DRMViewport2

デバイスの上のビューポート始点のy座標オフセットを取得する。

構文

LONG GetY( );

戻り値

yオフセットを返す。

IDirect3DRMViewport2::Init

IDirect3DRMViewport2

Direct3DRMViewportオブジェクトを初期化する。

構文

HRESULT Init(
  LPDIRECT3DRMDEVICE3 lpD3DRMDevice,
  LPDIRECT3DRMFRAME3 lpD3DRMFrameCamera,
  DWORD xpos,
  DWORD ypos,
  DWORD width,
  DWORD height
  );

パラメータ

lpD3DRMDevice
このビューポートに関連付けられたデバイスオブジェクトのアドレス。デバイスに関する詳細は、「出力デバイス」を参照すること。
lpD3DRMFrameCamera
このビューポートに関連付けられたカメラフレームのアドレス。
xpos, ypos
ビューポートの左上隅のx座標およびy座標。
width, height
ビューポートの幅と高さ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2

lprvSrcパラメータが示すベクトルをワールド座標からモデル座標に変換し、結果をlprvDstパラメータに返す。

構文

HRESULT InverseTransform(
  D3DVECTOR  *lprvDst,
  D3DRMVECTOR4D  *lprvSrc
  );

パラメータ

lprvDst
メソッドが制御を返すときに処理結果を受け取るD3DVECTOR構造体のアドレス。
lprvSrc
変換されるD3DRMVECTOR4D構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMViewport2::InverseTransformVectors, IDirect3DRMViewport2::Transform

IDirect3DRMViewport2::InverseTransformVectors

IDirect3DRMViewport2

これは、スクリーン座標におけるlpSrcVectorsパラメータのベクトルの配列をワールド座標に変換し、結果をlprvDstVectorsパラメータ中に返す。

構文

HRESULT InverseTransformVectors(
   DWORD dwNumVectors,
   LPD3DVECTOR	lpDstVectors,
   LPD3DRMVECTOR4D lpSrcVectors);

パラメータ

dwNumVectors
座標を変換する必要のあるベクトル数。
lpDstVectors
変換の出力先。
lpSrcVectors
変換するベクトルを表すD3DRMVECTOR4D構造体の配列。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

IDirect3DRMViewport2::TransformVectors, IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2::Pick

IDirect3DRMViewport2

深度によって分類されたオブジェクト（関連があれば面も）のリストを見つけ出す。取得した配列には、ルートからオブジェクトを含むフレームに到達するまでの階層パスが格納される。

構文

HRESULT Pick(
  LONG lX,
  LONG lY,
  LPDIRECT3DRMPICKEDARRAY *lplpVisuals
  );

パラメータ

lX, lY
ピッキングに使われる座標。
lplpVisuals
呼び出しが成功したとき、IDirect3DRMPickedArrayインターフェイスへの有効なポインタが入るポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMViewport2::Render

IDirect3DRMViewport2

フレーム階層を、指定されたビューポートにレンダリングする。指定されたフレーム上のビジュアルと、その下の階層のフレームだけがレンダリングされる。

構文

HRESULT Render(
  LPDIRECT3DRMFRAME lpD3DRMFrame
  );

パラメータ

lpD3DRMFrame
レンダリングするフレーム階層を示すDirect3DRMFrameオブジェクトを示す変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。このメソッドは、IDirect3DRM3::SetOptionsメソッドの使用により右手サポートを指示する際にエラーを返し、それと同時に旧の方法 (IDirect3DRMViewport2::SetProjection)を使用した右手サポートを提供する。

IDirect3DRMViewport2::SetBack

IDirect3DRMViewport2

ビューポートのバッククリッピングプレーンの位置を設定する。

構文

HRESULT SetBack(
  D3DVALUE rvBack
  );

パラメータ

rvBack
カメラとバッククリッピングプレーンの間の距離。デフォルト値は100.0である。適正な値はその他の視錐台設定に依存する。詳細については、「ビューポート」を参照すること。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMViewportInterpolatorオブジェクトにバッククリッピングプレーンの位置キーを追加するためにも使用する。

参照

IDirect3DRMViewport2::GetBack, IDirect3DRMViewport2::SetFront, 「視錐台」

IDirect3DRMViewport2::SetCamera

IDirect3DRMViewport2

カメラフレームをビューポートに設定する。

構文

HRESULT SetCamera(
  LPDIRECT3DRMFRAME3 lpCamera
  );

パラメータ

lpCamera
カメラを示すDirect3DRMFrameオブジェクトを指す変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、ビューポートの位置、方向、向きを指定されたカメラフレームと同じに設定する。ビューは、カメラフレームの正のz軸方向に沿って、正のy軸の上方向に向けられる。

参照

IDirect3DRMViewport2::GetCamera, 「カメラ」

IDirect3DRMViewport2::SetField

IDirect3DRMViewport2

ビューポートにビューのフィールドを設定する。

構文

HRESULT SetField(
  D3DVALUE rvField
  );

パラメータ

rvField
ビューの新しいフィールド。この値は視角の端数である。デフォルト値は0.5である。この値に0以下を指定すると、このメソッドはD3DRMERR_BADVALUEエラーを返す。視角は、フロントクリッピングプレーンのアークタンジェントの2倍割るカメラからの距離として定義される。視角の詳細については、「視錐台」を参照すること。rvFieldの値0.5は、「視錐台」の項で示す視角Aの半分である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMViewportInterpolatorオブジェクトにビューのフィールドキーを追加するためにも使用する。

参照

IDirect3DRMViewport2::GetField, 「視錐台」

IDirect3DRMViewport2::SetFront

IDirect3DRMViewport2

ビューポートのフロントクリッピングプレーンの位置を設定する。

構文

HRESULT SetFront(
  D3DVALUE rvFront
  );

パラメータ

rvFront
カメラからフロントクリッピングプレーンまでの距離。デフォルト値は1.0である。適正な値はその他の視錐台設定に依存する。詳細については、「ビューポート」を参照すること。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

0以下の値が渡されると、このメソッドはD3DRMERR_BADVALUEエラーを返す。

このメソッドは、Direct3DRMViewportInterpolatorオブジェクトにフロントクリッピングプレーン位置キーを追加するためにも使用する。

参照

IDirect3DRMViewport2::GetFront, 「視錐台」

IDirect3DRMViewport2::SetPlane

IDirect3DRMViewport2

カメラのz軸に対するビューポートのサイズをフロントクリッピングプレーンに設定する。

構文

HRESULT SetPlane(
  D3DVALUE rvLeft,
  D3DVALUE rvRight,
  D3DVALUE rvBottom,
  D3DVALUE rvTop
  );

パラメータ

rvLeft, rvRight, rvBottom, rvTop
ビューポートの最小のx座標 、最大のx座標、最小のy座標、最大のy座標。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

中央に調整されたビューポートを指定するIDirect3DRMViewport2::SetFieldメソッドと異なり、このメソッドによって、任意の比率と位置のビューポートを指定することができる。たとえば、分離した視錐台を構築して、右目や左目のステレオビューをインプリメントすることができる。

このメソッドは、Direct3DRMViewportInterpolatorオブジェクトにプレーンキーを追加するためにも使用する。

参照

IDirect3DRMViewport2::GetPlane, IDirect3DRMViewport2::SetField

IDirect3DRMViewport2::SetProjection

IDirect3DRMViewport2

ビューポートに射影タイプを設定する。

構文

HRESULT SetProjection(
  D3DRMPROJECTIONTYPE rptType
  );

パラメータ

rptType
D3DRMPROJECTIONTYPE列挙型のメンバの1つ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

DirectX version 6.0以降では、IDirect3DRM3::SetOptionsを使用して右手ジオメトリを指定する。

参照

IDirect3DRMViewport2::GetProjection

IDirect3DRMViewport2::SetUniformScaling

IDirect3DRMViewport2

表示ボリュームをウィンドウのサイズよりも大きくスケーリングするときに用いられる、スケール特性を設定する。

構文

HRESULT SetUniformScaling(
  BOOL bScale
  );

パラメータ

bScale
新しいスケール特性。このパラメータにTRUEを指定すると、水平方向と垂直方向に同じスケール係数が使用される。そうでなければ、表示ボリュームをウィンドウに一致させるため、異なるスケール係数が用いられる。デフォルトの設定はTRUEである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

通常このメソッドは、バンディングをサポートするためにIDirect3DRMViewport2::SetPlaneメソッドとともに使用される。

参照

IDirect3DRMViewport2::GetUniformScaling

IDirect3DRMViewport2::Transform

IDirect3DRMViewport2

lprvSrcパラメータが示すベクトルをワールド座標からスクリーン座標に変換し、結果をlprvDstパラメータに返す。

構文

HRESULT Transform(
  D3DRMVECTOR4D  *lprvDst,
  D3DVECTOR  *lprvSrc
  );

パラメータ

lprvDst
変換操作の出力先となるD3DRMVECTOR4D構造体のアドレス。
lprvSrc
変換処理のソースとなるD3DVECTOR構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

変換結果には、4要素の同種のベクトルが返される。以下の方程式が真であれば、結果のベクトルが示す点は可視状態である。

参照

IDirect3DRMViewport2::TransformVectors, IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2::TransformVectors

IDirect3DRMViewport2

これは、ワールド座標におけるlpSrcVectorsパラメータのベクトルの配列をスクリーン座標に変換し、結果をlprvDstVectorsパラメータ中に返す。

構文

HRESULT TransformVectors(
  DWORD dwNumVectors,
  LPD3DRMVECTOR4D lpDstVectors,
  LPD3DVECTOR lpSrcVectors);

パラメータ

dwNumVectors
変換する必要のあるベクトル数。
lpDstVectors
スクリーン座標に変換されたベクトルを表すD3DRMVECTOR4D構造体の配列。
lpSrcVectors
変換するベクトルの配列。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

IDirect3DRMViewport2::Transform, IDirect3DRMViewport2::InverseTransformVectors


IDirect3DRMViewportArray

アプリケーションは、ビューポートオブジェクトをグループ化するため、IDirect3DRMViewportArrayインターフェイスのメソッドを利用する。このセクションはこのインターフェイスメソッドのリファレンスである。概念についての概要は、「ビューポート」を参照すること。

IDirect3DRMViewportArrayインターフェイスは次のメソッドをサポートする。
GetElement
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMViewportArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMViewportArrayオブジェクトは、IDirect3DRMDevice3::GetViewportsメソッドの呼び出しによって取得される。

IDirect3DRMViewportArray::GetElement

IDirect3DRMViewportArray

Direct3DRMViewportArrayオブジェクトから指定された要素を取得する。

構文

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMVIEWPORT  *lplpD3DRMViewport
  );

パラメータ

index
配列要素。
lplpD3DRMViewport
IDirect3DRMViewportインターフェイスを受け取るアドレスへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

QueryInterfaceを使用して、たとえば、IDirect3DRMViewport2などの希望するIDirect3DRMViewportのバージョンへのポインタを取得することができる。lplpD3DRMViewportパラメータを、異なるバージョンに単純に型変換することはできない。QueryInterfaceを使用しなければならない。

IDirect3DRMViewportArray::GetSize

IDirect3DRMViewportArray

Direct3DRMViewportArrayオブジェクトに含まれている要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMVisual

IDirect3DRMVisualは、Microsoft® Direct3D® 保持モードメソッドをなにも提供しないが、ビジュアルオブジェクトのインターフェイスはIDirect3DRMVisualインターフェイスから引き出される。インターフェイス階層の完全な説明については、「Direct3D保持モードのインターフェイス階層」を参照すること。

ビジュアルは、シーン上にレンダリングできるオブジェクトである。ビジュアルが可視になるのは、そのシーンのフレームに追加された場合のみである。アプリケーションは、IDirect3DRMFrame3::AddVisualメソッドを使用して、ビジュアルをフレームに追加することができる。フレームは、レンダリングのための位置と方向をビジュアルに提供する。

次のインターフェイスは、IDirect3DRMVisualから引き出される。

  • IDirect3DRMFrame3
  • IDirect3DRMMesh
  • IDirect3DRMProgressiveMesh
  • IDirect3DRMShadow2
  • IDirect3DRMTexture3
  • IDirect3DRMUserVisual

すべてのCOMインターフェイスと同様、IDirect3DRMVisualインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release


IDirect3DRMVisualArray

アプリケーションは、ビジュアルオブジェクトをグループ化するには、IDirect3DRMVisualArrayインターフェイスのメソッドを利用する。

ビジュアルは、シーン上にレンダリングできるオブジェクトである。ビジュアルが可視になるのは、そのシーンのフレームに追加された場合のみである。アプリケーションは、IDirect3DRMFrame3::AddVisualメソッドを使用して、ビジュアルをフレームに追加することができる。フレームは、ビジュアルにレンダリングのための位置と方向を提供する。

注: IDirect3DRMVisual COMインターフェイスはあるが、これはDirect3D保持モードの固有のメソッドを持たない。

最も一般的なビジュアルタイプは、Direct3DRMMeshBuilder3とDirect3DRMTextureオブジェクトである。

IDirect3DRMVisualArrayインターフェイスは次のメソッドをサポートする。
GetElement
GetSize

すべてのCOMインターフェイスと同様、IDirect3DRMVisualArrayインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMVisualArrayオブジェクトはIDirect3DRMFrame3::GetVisualsメソッドの呼び出しによって取得される。

IDirect3DRMVisualArray::GetElement

IDirect3DRMVisualArray

Direct3DRMVisualArrayオブジェクトから指定された要素を取得する。

構文

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMVISUAL  *lplpD3DRMVisual
  );

パラメータ

index
配列要素。
lplpD3DRMVisual
IDirect3DRMVisualインターフェイスを受け取るポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMVisualArray::GetSize

IDirect3DRMVisualArray

Direct3DRMVisualArrayオブジェクトに含まれている要素数を取得する。

構文

DWORD GetSize( );

戻り値

要素数を返す。


IDirect3DRMWinDevice

アプリケーションは、ウィンドウプロシージャでウィンドウメッセージに応答するためにIDirect3DRMWinDeviceインターフェイスのメソッドを使用する。このセクションはIDirect3DRMWinDeviceインターフェイスメソッドのリファレンスである。概念についての概要は、「ウィンドウ管理」を参照すること。

IDirect3DRMWinDeviceインターフェイスは次のメソッドをサポートする。
HandleActivate
HandlePaint

すべてのCOMインターフェイスと同様、IDirect3DRMWinDeviceインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

Direct3DRMWinDeviceオブジェクトは、IID_IDirect3DRMWinDeviceを指定してIDirect3DRMObject::QueryInterfaceメソッド呼び出すか、IDirect3DRM3::CreateDeviceFromD3Dのようなメソッドを使用すれば取得できる。IDirect3DRMWinDeviceメソッドは、IDirect3DRMDevice3インターフェイスから継承される。

IDirect3DRMWinDevice::HandleActivate

IDirect3DRMWinDevice

Microsoft® Windows®のWM_ACTIVATEメッセージに応答する。これにより、アクティブなレンダリングウィンドウで色を正しく保つことができる。

構文

HRESULT HandleActivate(
  WORD wParam
  );

パラメータ

wParam
メッセージ処理プロシージャに渡される、WM_ACTIVATEのWPARAMパラメータ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMWinDevice::HandlePaint

IDirect3DRMWinDevice

WindowsのWM_PAINTメッセージに応答する。hDCパラメータは、WindowsのBeginPaint関数に渡されるPAINTSTRUCT構造体から取得される。このメソッドは、デバイス上に作成されたビューポートの外側の領域を再描画することがあるため、ウィンドウ内のアプリケーション領域を再描画する前に必ず呼び出す必要がある。

構文

HRESULT HandlePaint(
  HDC hDC
  );

パラメータ

hDC
デバイスコンテキスト（DC）のハンドル。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。


IDirect3DRMWrap

アプリケーションは、ラップオブジェクトとやり取りするためにIDirect3DRMWrapインターフェイスのメソッドを使用する。このセクションはIDirect3DRMWrapインターフェイスメソッドのリファレンスである。概念についての概要は、「ラップ」を参照すること。

IDirect3DRMWrapインターフェイスのメソッドは、以下のグループにまとめることができる。
初期化 | Init
ラップ | Apply
 | ApplyRelative

すべてのCOMインターフェイスと同様、IDirect3DRMWrapインターフェイスはIUnknownインターフェイスメソッドを継承する。IUnknownインターフェイスは、以下の3つのメソッドをサポートする。
AddRef
QueryInterface
Release

さらに、IDirect3DRMWrapインターフェイスはIDirect3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMWrapオブジェクトは、IDirect3DRM3::CreateWrapメソッドの呼び出しによって取得される。

IDirect3DRMWrap::Apply

IDirect3DRMWrap

Direct3DRMWrapオブジェクトをその出力先オブジェクトに適用する。一般に出力先オブジェクトは、面またはメッシュである。

構文

HRESULT Apply(
  LPDIRECT3DRMOBJECT lpObject
  );

パラメータ

lpObject
出力先オブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRM3::CreateWrap

IDirect3DRMWrap::ApplyRelative

IDirect3DRMWrap

オブジェクトの頂点にラップを設定する。最初に各頂点にフレームのワールド変換を行い、次にラップの参照フレームの逆ワールド変換を設定する。

構文

HRESULT ApplyRelative(
  LPDIRECT3DRMFRAME frame,
  LPDIRECT3DRMOBJECT mesh
  );

パラメータ

frame
ラッピングするオブジェクトを含むDirect3DRMFrameオブジェクト。
mesh
適用するDirect3DRMWrapオブジェクト。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRM3::CreateWrap

IDirect3DRMWrap::Init

IDirect3DRMWrap

Direct3DRMWrapオブジェクトを初期化する。

構文

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

パラメータ

d3drmwt
D3DRMWRAPTYPE列挙型のメンバの1つ。
lpd3drmfRef
このDirect3DRMWrapオブジェクトの参照フレームを示すDirect3DRMFrameオブジェクトのアドレス。
ox, oy, oz
ラップの原点。
dx, dy, dz
ラップのz軸。
ux, uy, uz
ラップのy軸。
ou, ov
テクスチャの原点。
su, sv
テクスチャのスケール係数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRM3::CreateWrap


C++非メンバ関数

Microsoft® Direct3D® 保持モードのC++非メンバ関数は、次の通りである。

  • D3DRMColorGetAlpha
  • D3DRMColorGetBlue
  • D3DRMColorGetGreen
  • D3DRMColorGetRed
  • D3DRMCreateColorRGB
  • D3DRMCreateColorRGBA
  • D3DRMMatrixFromQuaternion
  • D3DRMQuaternionFromRotation
  • D3DRMQuaternionMultiply
  • D3DRMQuaternionSlerp
  • D3DRMVectorAdd
  • D3DRMVectorCrossProduct
  • D3DRMVectorDotProduct
  • D3DRMVectorModulus
  • D3DRMVectorNormalize
  • D3DRMVectorRandom
  • D3DRMVectorReflect
  • D3DRMVectorRotate
  • D3DRMVectorScale
  • D3DRMVectorSubtract
  • Direct3DRMCreate

D3DRMColorGetAlpha

色のアルファ要素を取得する。

構文

D3DVALUE D3DRMColorGetAlpha(
  D3DCOLOR d3drmc
  );

パラメータ

d3drmc
アルファ要素を取得する色。0から255の間の値。

戻り値

成功すればアルファ値、失敗すれば0を返す。

参照

D3DRMColorGetBlue, D3DRMColorGetGreen, D3DRMColorGetRed

D3DRMColorGetBlue

色の青要素を取得する。

構文

D3DVALUE D3DRMColorGetBlue(
  D3DCOLOR d3drmc
  );

パラメータ

d3drmc
青要素を取得する色。0から255の間の値。

戻り値

成功すれば青色値、失敗すれば0を返す。

参照

D3DRMColorGetAlpha, D3DRMColorGetGreen, D3DRMColorGetRed

D3DRMColorGetGreen

色の緑要素を取得する。

構文

D3DVALUE D3DRMColorGetGreen(
  D3DCOLOR d3drmc
  );

パラメータ

d3drmc
緑要素を取得する色。0から255の間の値。

戻り値

成功すれば緑色値、失敗すれば0を返す。

参照

D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetRed

D3DRMColorGetRed

色の赤要素を取得する。

構文

D3DVALUE D3DRMColorGetRed(
  D3DCOLOR d3drmc
  );

パラメータ

d3drmc
赤要素を取得する色。

戻り値

成功すれば赤色値、失敗すれば0を返す。

参照

D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetGreen

D3DRMCreateColorRGB

与えられた赤、緑および青要素からRGB色を作成する。

構文

D3DCOLOR D3DRMCreateColorRGB(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

パラメータ

red, green, blue
RGB色の構成要素。

戻り値

成功すれば新しいRGB値、失敗すれば0を返す。

参照

D3DRMCreateColorRGBA

D3DRMCreateColorRGBA

与えられた赤、緑、青色、およびアルファ要素からRGBA色を作成する。

構文

D3DCOLOR D3DRMCreateColorRGBA(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue,
  D3DVALUE alpha
  );

パラメータ

red, green, blue, alpha
RGBA色の構成要素。0から1の間の値。

戻り値

成功すれば新しいRGBA値、失敗すれば0を返す。

参照

D3DRMCreateColorRGB

D3DRMMatrixFromQuaternion

回転を示す行列を計算する。

構文

void D3DRMMatrixFromQuaternion (
  D3DRMMATRIX4D mat,
  LPD3DRMQUATERNION lpquat
  );

パラメータ

mat
関数が制御を返すとき、計算された行列が入るアドレス。（D3DRMMATRIX4D型は配列である）
lpquat
D3DRMQUATERNION構造体。

戻り値

なし。

D3DRMQuaternionFromRotation

指定された軸を中心に、指定された角度（ラジアン単位）の回転を行う。

構文

LPD3DRMQUATERNION D3DRMQuaternionFromRotation(
  LPD3DRMQUATERNION lpquat,
  LPD3DVECTOR lpv,
  D3DVALUE theta
  );

パラメータ

lpquat
操作結果を受け取るD3DRMQUATERNION構造体。
lpv
回転の軸を指定するD3DVECTOR構造体。
theta
パラメータによって指定された軸の周りを回転する角度（ラジアン単位）。

戻り値

成功すれば、第1パラメータとして渡された4次行列へのポインタを返す。失敗すれば0を返す。

D3DRMQuaternionMultiply

2つのベクトルの積を計算する。

構文

LPD3DRMQUATERNION D3DRMQuaternionMultiply(
  LPD3DRMQUATERNION lpq,
  LPD3DRMQUATERNION lpa,
  LPD3DRMQUATERNION lpb
  );

パラメータ

lpq
乗算の結果を受け取るD3DRMQUATERNION構造体。
lpa, lpb
乗算するD3DRMQUATERNION構造体。

戻り値

成功すれば、第1パラメータとして渡された構造体へのポインタを返す。失敗すれば0を返す。

D3DRMQuaternionSlerp

球面線形補間を使用して2つの構造体を補完する。

構文

LPD3DRMQUATERNION D3DRMQuaternionSlerp(
  LPD3DRMQUATERNION lpq,
  LPD3DRMQUATERNION lpa,
  LPD3DRMQUATERNION lpb,
  D3DVALUE alpha
  );

パラメータ

lpq
補完した結果を受け取るD3DRMQUATERNION構造体。
lpa, lpb
補完の開始位置と終了位置として用いられるD3DRMQUATERNION構造体。
alpha
lpaとlpbの間に補間する距離を示す、0から1の間の値。

戻り値

成功すれば、第1パラメータとして渡された構造体を返す。失敗すれば0を返す。

D3DRMVectorAdd

2つのベクトルを加算する。

構文

LPD3DVECTOR D3DRMVectorAdd(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lps1,
  LPD3DVECTOR lps2
  );

パラメータ

lpd
加算の結果を受け取るD3DVECTOR構造体。
lps1, lps2
加算されるD3DVECTOR構造体。

戻り値

成功すれば、第1パラメータとして渡されたベクトルを返す。失敗すれば0を返す。

D3DRMVectorCrossProduct

2つのベクトルの外積を計算する。

構文

LPD3DVECTOR D3DRMVectorCrossProduct(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lps1,
  LPD3DVECTOR lps2
  );

パラメータ

lpd
外積の結果を受け取るD3DVECTOR構造体。
lps1, lps2
外積が計算されるD3DVECTOR構造体。

戻り値

成功すれば、第1パラメータとして渡されたベクトルを返す。失敗すれば0を返す。

D3DRMVectorDotProduct

ベクトルの内積を返す。

構文

D3DVALUE D3DRMVectorDotProduct(
  LPD3DVECTOR lps1,
  LPD3DVECTOR lps2
  );

パラメータ

lps1, lps2
内積が計算されるD3DVECTOR構造体。

戻り値

成功すれば内積の結果、失敗すれば0を返す。

D3DRMVectorModulus

以下の式にしたがってベクトルの長さを返す。

x2乗 + y2乗 + z2乗の平方根

構文

D3DVALUE D3DRMVectorModulus(
  LPD3DVECTOR lpv
  );

パラメータ

lpv
長さを計算するD3DVECTOR構造体。

戻り値

成功すれば、D3DVECTOR構造体に長さを返す。失敗すれば0を返す。

D3DRMVectorNormalize

絶対値が1になるようにベクトルをスケーリングする。

構文

LPD3DVECTOR D3DRMVectorNormalize(
  LPD3DVECTOR lpv
  );

パラメータ

lpv
スケーリング操作の結果を受け取るD3DVECTOR構造体。

戻り値

成功すれば、第1パラメータとして渡されたベクトルを返す。たとえば0ベクトルが渡された場合など、エラーが発生すると0を返す。

D3DRMVectorRandom

ランダムなベクトルユニットを返す。

構文

LPD3DVECTOR D3DRMVectorRandom(
  LPD3DVECTOR lpd
  );

パラメータ

lpd
ランダムなベクトルユニットを受け取るD3DVECTOR構造体。

戻り値

成功すれば、第1パラメータとして渡されたベクトルを返す。失敗すれば0を返す。

D3DRMVectorReflect

指定された法線について、光線を反射する。

構文

LPD3DVECTOR D3DRMVectorReflect(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lpRay,
  LPD3DVECTOR lpNorm
  );

パラメータ

lpd
処理結果を受け取るD3DVECTOR構造体。
lpRay
法線で反射されるD3DVECTOR構造体。
lpNorm
lpRayで指定された光線を反射する法線を示すD3DVECTOR構造体。

戻り値

成功すれば、第1パラメータとして渡されたベクトルを返す。失敗すれば0を返す。

D3DRMVectorRotate

指定された軸を中心にベクトルを回転させる。成功すると、正規化されたベクトルを返す。

構文

LPD3DVECTOR D3DRMVectorRotate(
  LPD3DVECTOR lpr,
  LPD3DVECTOR lpv,
  LPD3DVECTOR lpaxis,
  D3DVALUE theta
  );

パラメータ

lpr
処理結果を受け取るD3DVECTOR構造体。
lpv
与えられた軸の回りを回転するD3DVECTOR構造体。
lpaxis
回転の軸を示すD3DVECTOR構造体。
theta
ラジアン単位での回転角度。

戻り値

成功すれば、第1パラメータとして渡されたベクトルを返す。失敗すれば0を返す。このベクトルは正規化されている。

D3DRMVectorScale

3つの軸について同じ比率で、ベクトルをスケーリングする。

構文

LPD3DVECTOR D3DRMVectorScale(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lps,
  D3DVALUE factor
  );

パラメータ

lpd
処理結果を受け取るD3DVECTOR構造体。
lps
スケーリングされるD3DVECTOR構造体。
factor
スケール係数。この値が1のとき、スケーリングは行われない。この値が2のときは2倍になる。

戻り値

成功すれば、第1パラメータとして渡されたベクトルを返す。失敗すれば0を返す。

D3DRMVectorSubtract

2つのベクトル間で減算を行う。

構文

LPD3DVECTOR D3DRMVectorSubtract(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lps1,
  LPD3DVECTOR lps2
  );

パラメータ

lpd
処理結果を受け取るD3DVECTOR構造体。
lps1
lps2が引かれるD3DVECTOR構造体。
lps2
lps1から引くD3DVECTOR構造体。

戻り値

成功すれば、第1パラメータとして渡されたベクトルを返す。失敗すれば0を返す。

Direct3DRMCreate

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

構文

HRESULT Direct3DRMCreate(
  LPDIRECT3DRM FAR  *lplpD3DRM
  );

パラメータ

lplpD3DRM
呼び出しが成功した場合、有効なDirect3DRMポインタが入るポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMObject


C++定数

Microsoft® Direct3D®保持モードには、構造体または列挙型のどちらにも入らない、その他のタイプのC++の定義がある。それらを次に示す。

  • D3DRMANIMATIONOPTIONS
  • D3DRMCOLORMODEL
  • D3DRMINTERPOLATIONOPTIONS
  • D3DRMLOADOPTIONS
  • D3DRMMAPPING
  • D3DRMMATRIX4D
  • D3DRMSAVEOPTIONS

D3DRMANIMATIONOPTIONS

アニメーションの再生方法を定義する値を指定する。IDirect3DRMAnimation2::GetOptions、IDirect3DRMAnimation2::SetOptionsおよびD3DRMANIMATIONKEYで用いられる。

構文

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

パラメータ

D3DRMANIMATION_CLOSED
アニメーションは繰り返し再生され、終点に達すると開始点に戻ってループする。閉じられたアニメーションでは、終点から開始点へ滑らかに遷移させたい場合、アニメーションの最後のキーは最初のキーの繰り返しでなくてはならない。この繰り返しキーを利用して、ループするアニメーションにおける最後と最初のキー間の時間の差が表される。しかし、最後のキーが最初のキーの繰り返しでない場合、新しいインターフェイス (IDirect3DRMAnimation2, IDirect3DRMAnimationSet2) で、これは無視されなくなる。これは効果を生み、アニメーションは即時に開始点に戻る。
D3DRMANIMATION_LINEARPOSITION
アニメーションの位置は線形に設定される。
D3DRMANIMATION_OPEN
アニメーションは1回だけ再生され、停止する。
D3DRMANIMATION_POSITION
アニメーションの位置行列によって、他のメソッドが設定するどんな変換行列も上書きされる。
D3DRMANIMATION_SCALEANDROTATION
アニメーションのスケールと回転行列によって、他のメソッドが設定するどんな変換行列も上書きされる。
D3DRMANIMATION_SPLINEPOSITION
アニメーションの位置はスプラインで設定される。

D3DRMCOLORMODEL

デバイスがインプリメントするカラーモデルを示す。詳細についてはD3DCOLORMODEL列挙型を参照すること。

構文

typedef D3DCOLORMODEL D3DRMCOLORMODEL;

参照

D3DCOLORMODEL

D3DRMINTERPOLATIONOPTIONS

IDirect3DRMInterpolator::Interpolateメソッドに対するオプションを定義する。それらのオプションは、オブジェクトのロードの仕方を変更する。

構文

typedef DWORD D3DRMINTERPOLATIONOPTIONS;
#define D3DRMINTERPOLATION_OPEN 0x01L
#define D3DRMINTERPOLATION_CLOSED 0x02L
#define D3DRMINTERPOLATION_NEAREST 0x0100L
#define D3DRMINTERPOLATION_LINEAR 0x04L
#define D3DRMINTERPOLATION_SPLINE 0x08L
#define D3DRMINTERPOLATION_VERTEXCOLOR 0x40L
#define D3DRMINTERPOLATION_SLERPNORMALS 0x80L

パラメータ

D3DRMINTERPOLATION_OPEN
各キーチェインの先頭と最後のキーが、インデックスの範囲外の補間値を修正する。
D3DRMINTERPOLATION_CLOSED
補間は循環的である。キーは、実際には、インデックス範囲に等しい間隔で無限に繰り返す。アニメーションとの互換性のため、範囲の最後に等しいインデックスの任意のキーは、無視される。
D3DRMINTERPOLATION_NEAREST
最近似のキー値が、各キーチェインの中間値を決定するために使用される（実行スレッド）。
D3DRMINTERPOLATION_LINEAR
2つの最近似キー間の線形補間が、各キーチェインの中間値を決定するために使用される。
D3DRMINTERPOLATION_SPLINE
4つの最近似キーに対するBスプライン混合関数が、各キーチェインの中間値を決定するために使用される。
D3DRMINTERPOLATION_VERTEXCOLOR
頂点の色が補間されるように指定する。IDirect3DRMMesh::SetVerticesの補間だけに影響する。
D3DRMINTERPOLATION_SLERPNORMALS
頂点の法線が球面補間されるように指定する（現在未実装）。IDirect3DRMMesh::SetVerticesの補間だけに影響する。

D3DRMLOADOPTIONS

DIDirect3DRM3::Load、IDirect3DRMAnimationSet2::Load、IDirect3DRMFrame3::Load、IDirect3DRMMeshBuilder3::Load、およびIDirect3DRMProgressiveMesh::Loadメソッドのオプションを定義する。それらのオプションは、オブジェクトのロードの仕方を変更する。

構文

typedef DWORD D3DRMLOADOPTIONS;
#define D3DRMLOAD_FROMFILE             0x00L
#define D3DRMLOAD_FROMRESOURCE         0x01L
#define D3DRMLOAD_FROMMEMORY           0x02L
#define D3DRMLOAD_FROMURL              0x08L
#define D3DRMLOAD_BYNAME               0x10L
#define D3DRMLOAD_BYPOSITION           0x20L
#define D3DRMLOAD_BYGUID               0x30L
#define D3DRMLOAD_FIRST                0x40L
#define D3DRMLOAD_INSTANCEBYREFERENCE  0x100L
#define D3DRMLOAD_INSTANCEBYCOPYING    0x200L
#define D3DRMLOAD_ASYNCHRONOUS         0x400L

パラメータ

ソースフラグ
D3DRMLOAD_FROMFILE
ファイルからロードする。これはデフォルト設定である。
D3DRMLOAD_FROMRESOURCE
リソースからロードする。このフラグを指定した場合、Loadメソッドの呼び出しのlpvObjSourceパラメータは、D3DRMLOADRESOURCE構造体を指さなくてはならない。
D3DRMLOAD_FROMMEMORY
メモリからロードする。このフラグを指定した場合、Loadメソッドの呼び出しのlpvObjSourceパラメータは、D3DRMLOADMEMORY構造体を指さなくてはならない。
D3DRMLOAD_FROMURL
URLからロードする。
識別子フラグ
D3DRMLOAD_BYNAME
指定された名前を使用してオブジェクトをロードする。
D3DRMLOAD_BYPOSITION
与えられた、0から始まる位置に、スタンドアロンのオブジェクトをロードする（つまり、ファイル中のn番目のオブジェクトをロードする）。スタンドアロンのオブジェクトは他のオブジェクトを含むことができるが、他のオブジェクトに含まれることはない。
D3DRMLOAD_BYGUID
指定されたグローバルユニーク識別子（GUID）を使用してオブジェクトをロードする。
D3DRMLOAD_FIRST
これはデフォルト設定である。与えられたタイプのスタンドアロンのオブジェクトをロードする（たとえば、アプリケーションがIDirect3DRMMeshBuilder3::Loadを呼び出す場合はメッシュをロードする）。スタンドアロンのオブジェクトは他のオブジェクトを含むことができるが、他のオブジェクトに含まれることはない。
インスタンスフラグ
D3DRMLOAD_INSTANCEBYREFERENCE
指定された名前と同じ名前のオブジェクトが存在するかどうかをチェックする。存在する場合、新しいオブジェクトを作成する代わりに、そのオブジェクトのインスタンスを使用する。
D3DRMLOAD_INSTANCEBYCOPYING
指定された名前と同じ名前のオブジェクトが存在するかどうかをチェックする。存在する場合、新しいオブジェクトを作成する代わりに、そのオブジェクトをコピーする。
ソースフラグ
D3DRMLOAD_ASYNCHRONOUS
Load呼び出しは、直ちに戻る。ロードの進行状態をチェックするのにイベントを使用するのは、アプリケーションの責任となる。デフォルトでは、ロードは、同期式で行われ、Load呼び出しは、すべてのデータのロードが完了するまで、またはエラーが発生するまでは戻らない。

注意

各Loadメソッドは、lpvObjSourceパラメータを使用してオブジェクトのソースを指定し、lpvObjIDパラメータによってオブジェクトを識別する。システムはソースフラグの選択に基づいてlpvObjSourceパラメータを解釈する。そして、識別子フラグの選択に基づいてlpvObjIDパラメータの内容を解釈する。

インスタンスフラグは、パラメータの解釈方法には何も変更を加えない。D3DRMLOAD_INSTANCEBYREFERENCEフラグを用いると、新しいオブジェクトを作成することなく同じファイルを2回ロードすることができる。オブジェクトが名前を持っていない場合、D3DRMLOAD_INSTANCEBYREFERENCEフラグをセットすると、D3DRMLOAD_INSTANCEBYCOPYINGフラグをセットしたときと同じ効果を得ることができる。ローダは、同一のオブジェクトが存在しても、各名前なしオブジェクトを新しいオブジェクトとして作成する。

D3DRMMAPPING

テクスチャのグループへのマッピング方法を定義する値である。IDirect3DRMMesh::GetGroupMappingやIDirect3DRMMesh::SetGroupMappingメソッドによって用いられる。

構文

typedef DWORD D3DRMMAPPING, D3DRMMAPPINGFLAG;
static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPU = 1;
static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPV = 2;
static const D3DRMMAPPINGFLAG D3DRMMAP_PERSPCORRECT = 4;

パラメータ

D3DRMMAPPINGFLAG
D3DRMMAPPINGと型が同じ。
D3DRMMAP_WRAPU
u方向にテクスチャをラップする。
D3DRMMAP_WRAPV
v方向にテクスチャをラップする。
D3DRMMAP_PERSPCORRECT
テクスチャラッピングはパースペクティブ補正される。

注意

D3DRMMAP_WRAPUとD3DRMMAP_WRAPフラグは、ラスタライザがテクスチャ座標を解釈する方法を決定する。ラスタライザは常に、テクスチャ座標で最も短い距離、つまり直線を補間する。この直線のパスと、uおよびv座標の有効値は、ラッピングフラグの使い方によって異なる。一方または両方のフラグがセットされると、直線はuまたはv方向のテクスチャの辺をラップアラウンドする。この場合、テクスチャは円柱状かドーナツ上の位相を持っているかのように見える。詳細については「ラップ」を参照すること。

参照

「ラップ」, IDirect3DRMMesh::GetGroupMapping, IDirect3DRMMesh::SetGroupMapping

D3DRMMATRIX4D

変換を行列として表す。行列エントリは、D3DRMMATRIX4D[row][column]から構成される。

構文

typedef D3DVALUE D3DRMMATRIX4D[4][4];

参照

IDirect3DRMFrame3::AddTransform, IDirect3DRMFrame3::GetTransform

D3DRMSAVEOPTIONS

IDirect3DRMMeshBuilder3::Saveメソッドのオプションを定義する。

構文

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
#define D3DRMSAVE_TEXTURETOPOLOGY 32

パラメータ

D3DRMXOFSAVE_NORMALS
基本的な面に加え、法線ベクトルを保存する。
D3DRMXOFSAVE_TEXTURECOORDINATES
基本的な面に加え、テクスチャ座標を保存する。
D3DRMXOFSAVE_MATERIALS
基本的な面に加え、マテリアルを保存する。
D3DRMXOFSAVE_TEXTURENAMES
基本的な面に加え、テクスチャの名前を保存する。
D3DRMXOFSAVE_ALL
基本的な面に加え、法線ベクトル、テクスチャ座標、マテリアル、テクスチャの名前を保存する。
D3DRMXOFSAVE_TEMPLATES
ファイルのテンプレートを保存する。デフォルトではテンプレートは保存されない。
D3DRMSAVE_TEXTURETOPOLOGY
メッシュの面ラップ値 (IDirect3DRMMeshBuilder3::SetTextureTopologyまたはIDirect3DRMFace2::SetTextureTopologyにより設定される)を保存する。このフラグは、SaveメソッドにD3DRMXOFSAVE_ALLを渡した場合には含まれない。すべてを本当に保存したければ、D3DRMSAVE_TEXTURETOPOLOGY|D3DRMXOFSAVE_ALLを渡す。IDirect3DRMMeshBuilder3::SetTextureTopologyまたはIDirect3DRMFace2::SetTextureTopologyを呼び出し、設定した値を保持したい場合は、このフラグを渡すだけでよい。


C++列挙型

Microsoft®Direct3D® 保持モードのC++列挙型は、次の通りである。

  • D3DRMCOLORSOURCE
  • D3DRMCOMBINETYPE
  • D3DRMFILLMODE
  • D3DRMFOGMODE
  • D3DRMFRAMECONSTRAINT
  • D3DRMLIGHTMODE
  • D3DRMLIGHTTYPE
  • D3DRMMATERIALMODE
  • D3DRMPALETTEFLAGS
  • D3DRMPROJECTIONTYPE
  • D3DRMRENDERQUALITY
  • D3DRMSHADEMODE
  • D3DRMSORTMODE
  • D3DRMTEXTUREQUALITY
  • D3DRMUSERVISUALREASON
  • D3DRMWRAPTYPE
  • D3DRMXOFFORMAT
  • D3DRMZBUFFERMODE

D3DRMCOLORSOURCE

Direct3DRMMeshBuilder3オブジェクトのカラーソースを記述する。カラーソースを設定するには、IDirect3DRMMeshBuilder3::SetColorSourceを使用する。カラーソースを取得するには、IDirect3DRMMeshBuilder3::GetColorSourceメソッドを使用する。

構文

typedef enum _D3DRMCOLORSOURCE{
    D3DRMCOLOR_FROMFACE,
    D3DRMCOLOR_FROMVERTEX
} D3DRMCOLORSOURCE;

値

D3DRMCOLOR_FROMFACE
オブジェクトのカラーソースは面である。
D3DRMCOLOR_FROMVERTEX
オブジェクトのカラーソースは頂点である。

参照

IDirect3DRMMeshBuilder3::SetColorSource, IDirect3DRMMeshBuilder3::GetColorSource

D3DRMCOMBINETYPE

2つの行列の合成方法を指定する。

構文

typedef enum _D3DRMCOMBINETYPE{
    D3DRMCOMBINE_REPLACE,
    D3DRMCOMBINE_BEFORE,
    D3DRMCOMBINE_AFTER
} D3DRMCOMBINETYPE;

値

D3DRMCOMBINE_REPLACE
与えられた行列により、フレームの現在の行列を置き換える。
D3DRMCOMBINE_BEFORE
与えられた行列とフレームの現在の行列の積を求める。計算においては、与えられた行列が現在の行列よりも先に指定される。
D3DRMCOMBINE_AFTER
与えられた行列とフレームの現在の行列の積を求める。計算においては、与えられた行列が現在の行列の後に指定される。

注意

行列の乗算は可換ではないため、与えられた行列と現在の行列を掛け合わせる順序は重要である。

参照

IDirect3DRMFrame3::AddRotation, IDirect3DRMFrame3::AddScale, IDirect3DRMFrame3::AddTransform, IDirect3DRMFrame3::AddTranslation

D3DRMFILLMODE

D3DRMRENDERQUALITY型の定義で使われる。

構文

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;

値

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乗に比例して指数関数的に強くなる。次の公式で表わされる。

注意

フォグは視界の基準と見なされることに注意しなくてはならない。方程式の1つから求められるフォグ値が低いほど、オブジェクトは見えにくくなる。

フォグの密度、始点、終点は、IDirect3DRMFrame3::SetSceneFogParamsメソッドによって指定することができる。指数フォグモードの方程式では、eは自然対数の底を表し、その値は約2.71828である。

参照

IDirect3DRMFrame3::SetSceneFogMode, IDirect3DRMFrame3::SetSceneFogParams

D3DRMFRAMECONSTRAINT

Direct3DRMFrameオブジェクトを表示するときに強制的に回転する軸を記述する。この列挙型はIDirect3DRMFrame3::LookAtメソッドによって使用される。

構文

typedef enum _D3DRMFRAMECONSTRAINT {
    D3DRMCONSTRAIN_Z,
    D3DRMCONSTRAIN_Y,
    D3DRMCONSTRAIN_X
} D3DRMFRAMECONSTRAINT;

値

D3DRMCONSTRAIN_Z
xおよびy回転のみ使用する。
D3DRMCONSTRAIN_Y
xおよびz回転のみ使用する。
D3DRMCONSTRAIN_X
yおよびz回転のみ使用する。

参照

IDirect3DRMFrame3::LookAt

D3DRMLIGHTMODE

D3DRMRENDERQUALITY型の定義で使われる。

構文

typedef enum _D3DRMLIGHTMODE {
    D3DRMLIGHT_OFF      = 0 *D3DRMSHADE_MAX,
    D3DRMLIGHT_ON       = 1 *D3DRMSHADE_MAX,
    D3DRMLIGHT_MASK     = 7 *D3DRMSHADE_MAX,
    D3DRMLIGHT_MAX      = 8 *D3DRMSHADE_MAX
} D3DRMLIGHTMODE;

値

D3DRMLIGHT_OFF
照明はオフである。
D3DRMLIGHT_ON
照明はオンである。
D3DRMLIGHT_MASK
照明はマスクを使用する。
D3DRMLIGHT_MAX
照明モードの最大値。

参照

D3DRMFILLMODE, D3DRMSHADEMODE, D3DRMRENDERQUALITY

D3DRMLIGHTTYPE

IDirect3DRM3::CreateLightメソッドを使って、照明タイプを定義する。

構文

typedef enum _D3DRMLIGHTTYPE{
    D3DRMLIGHT_AMBIENT,
    D3DRMLIGHT_POINT,
    D3DRMLIGHT_SPOT,
    D3DRMLIGHT_DIRECTIONAL,
    D3DRMLIGHT_PARALLELPOINT
} D3DRMLIGHTTYPE;

値

D3DRMLIGHT_AMBIENT
アンビエント照明。
D3DRMLIGHT_POINT
ポイント照明。
D3DRMLIGHT_SPOT
スポットライト照明。
D3DRMLIGHT_DIRECTIONAL
ディレクショナル照明。
D3DRMLIGHT_PARALLELPOINT
パラレルポイント照明。

D3DRMMATERIALMODE

フレームとともにレンダリングされるビジュアルのマテリアル情報のソースを記述する。

構文

typedef enum _D3DRMMATERIALMODE{
    D3DRMMATERIAL_FROMMESH,
    D3DRMMATERIAL_FROMPARENT,
    D3DRMMATERIAL_FROMFRAME
} D3DRMMATERIALMODE;

値

D3DRMMATERIAL_FROMMESH
マテリアル情報はビジュアルオブジェクト（メッシュ）そのものから取得される。これはデフォルト設定である。
D3DRMMATERIAL_FROMPARENT
マテリアル情報は、色やテクスチャ情報とともに親フレームから継承される。
D3DRMMATERIAL_FROMFRAME
マテリアル情報はフレームから取得され、ビジュアルオブジェクトが保持していた以前の情報をオーバーライドする。

参照

IDirect3DRMFrame3::GetMaterialMode, IDirect3DRMFrame3::SetMaterialMode

D3DRMPALETTEFLAGS

D3DRMPALETTEENTRY構造体での色の使用方法を定義する。

構文

typedef enum _D3DRMPALETTEFLAGS {
    D3DRMPALETTE_FREE,
    D3DRMPALETTE_READONLY,
    D3DRMPALETTE_RESERVED
} D3DRMPALETTEFLAGS;

値

D3DRMPALETTE_FREE
レンダラーはこのエントリを自由に使用できる。
D3DRMPALETTE_READONLY
固定されているが、レンダラーが使うことができる。
D3DRMPALETTE_RESERVED
レンダラーが使うことはできない。

参照

D3DRMPALETTEENTRY

D3DRMPROJECTIONTYPE

Direct3DRMViewportオブジェクトで使用される投影のタイプを定義する。IDirect3DRMViewport2::GetProjectionおよびIDirect3DRMViewport2::SetProjectionメソッドは、この列挙型を使用する。右手タイプは、右手投影をイネーブルにする。

注: DirectX version 6.0以降では、IDirect3DRM3::SetOptionsを使用して右手ジオメトリを指定する。

カメラの軸（IDirect3DRMFrame3::SetAxes参照）は、カメラの面する方向を決定するために、左手投影と右手投影の両方で使用される。

構文

typedef enum _D3DRMPROJECTIONTYPE{
    D3DRMPROJECT_PERSPECTIVE,
    D3DRMPROJECT_ORTHOGRAPHIC,
    D3DRMPROJECT_RIGHTHANDPERSPECTIVE,
    D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
} D3DRMPROJECTIONTYPE;

値

D3DRMPROJECT_PERSPECTIVE
投影は、左手のパースペクティブである。
D3DRMPROJECT_ORTHOGRAPHIC
投影は、左手の正射影法である。
D3DRMPROJECT_RIGHTHANDPERSPECTIVE
投影は、右手のパースペクティブである。
D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
投影は、右手の正射影法である。

参照

IDirect3DRMViewport2::GetProjection, IDirect3DRMViewport2::SetProjection

D3DRMRENDERQUALITY

Direct3DRMMeshオブジェクトのシェーディングモード、照明モード、塗りつぶしモードを結合する。

構文

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)

値

D3DRMSHADEMODE, D3DRMLIGHTMODE, D3DRMFILLMODE
シェーディング、照明、塗りつぶしモードを示す。

D3DRMRENDER_WIREFRAME
辺のみを表示する。
D3DRMRENDER_UNLITFLAT
照明なしのフラットシェーディング。
D3DRMRENDER_FLAT
フラットシェーディング。
D3DRMRENDER_GOURAUD
グーローシェーディング。
D3DRMRENDER_PHONG
フォンシェーディング。このシェーディングモードは現在はサポートされていない。

参照

IDirect3DRMMesh::GetGroupQuality, IDirect3DRMMesh::SetGroupQuality,IDirect3DRMDevice3::SetRenderMode

D3DRMSHADEMODE

D3DRMRENDERQUALITY型の定義で使われる。

構文

typedef enum _D3DRMSHADEMODE {
    D3DRMSHADE_FLAT     = 0,
    D3DRMSHADE_GOURAUD  = 1,
    D3DRMSHADE_PHONG    = 2,
    D3DRMSHADE_MASK     = 7,
    D3DRMSHADE_MAX      = 8
} D3DRMSHADEMODE;

参照

D3DRMFILLMODE, D3DRMLIGHTMODE, D3DRMRENDERQUALITY

D3DRMSORTMODE

シーン上にどのように子フレームがソートされるかを示す。

構文

typedef enum _D3DRMSORTMODE {
    D3DRMSORT_FROMPARENT,
    D3DRMSORT_NONE,
    D3DRMSORT_FRONTTOBACK,
    D3DRMSORT_BACKTOFRONT
} D3DRMSORTMODE;

値

D3DRMSORT_FROMPARENT
子フレームは親フレームのソート順序を継承する。これはデフォルト設定である。
D3DRMSORT_NONE
子フレームはソートされない。
D3DRMSORT_FRONTTOBACK
子フレームは前から後ろへソートされる。
D3DRMSORT_BACKTOFRONT
子フレームは後ろから前へソートされる。

参照

IDirect3DRMFrame3::GetSortMode, IDirect3DRMFrame3::SetSortMode

D3DRMTEXTUREQUALITY

デバイスが、いかにテクスチャのピクセルとビューポートのピクセルの間を補間するかを記述する。この列挙型はIDirect3DRMDevice3::SetTextureQualityおよびIDirect3DRMDevice3::GetTextureQualityメソッドによって使用される。

構文

typedef enum _D3DRMTEXTUREQUALITY{
    D3DRMTEXTURE_NEAREST,
    D3DRMTEXTURE_LINEAR,
    D3DRMTEXTURE_MIPNEAREST,
    D3DRMTEXTURE_MIPLINEAR,
    D3DRMTEXTURE_LINEARMIPNEAREST,
    D3DRMTEXTURE_LINEARMIPLINEAR
} D3DRMTEXTUREQUALITY;

値

D3DRMTEXTURE_NEAREST
テクスチャの最も近いピクセルを選択する。ミップマッピングをサポートしない。
D3DRMTEXTURE_LINEAR
4つの最も近いピクセルを線形に補間する。ミップマッピングをサポートしない。
D3DRMTEXTURE_MIPNEAREST
D3DRMTEXTURE_NEARESTに似ているが、テクスチャの代わりに適切なミップマップを使用する。ピクセルサンプリングとミップマッピングは両方とも最近似である。
D3DRMTEXTURE_MIPLINEAR
D3DRMTEXTURE_LINEARに似ているが、テクスチャの代わりに適切なミップマップを使用する。ピクセルサンプリングは線形である。ミップマッピングは最近似である。
D3DRMTEXTURE_LINEARMIPNEAREST
D3DRMTEXTURE_MIPNEARESTに似ているが、2つの最近似ミップマップ間を補間する。ピクセルサンプリングは最近似である。ミップマッピングは線形である。
D3DRMTEXTURE_LINEARMIPLINEAR
D3DRMTEXTURE_MIPLINEARに似ているが、2つの最近似ミップマップ間を補間する。ピクセルサンプリングとミップマッピングは、両方とも線形である。

D3DRMUSERVISUALREASON

システムがD3DRMUSERVISUALCALLBACKコールバック関数を使用した理由を定義する。

構文

typedef enum _D3DRMUSERVISUALREASON {
    D3DRMUSERVISUAL_CANSEE,
    D3DRMUSERVISUAL_RENDER
} D3DRMUSERVISUALREASON;

値

D3DRMUSERVISUAL_CANSEE
ユーザビジュアルオブジェクトがビューポート上で可視状態であれば、コールバック関数はTRUEを返さなくてはならない。
D3DRMUSERVISUAL_RENDER
コールバック関数はユーザビジュアルオブジェクトをレンダリングしなくてはならない。

参照

D3DRMUSERVISUALCALLBACK

D3DRMWRAPTYPE

IDirect3DRM3::CreateWrapメソッドによって作成されるDirect3DRMWrapオブジェクトのタイプを定義する。またIDirect3DRMWrap::Initメソッドの呼び出しの中で、Direct3DRMWrapオブジェクトを初期化するためにこの列挙型を使用することができる。

構文

typedef enum _D3DRMWRAPTYPE{
    D3DRMWRAP_FLAT,
    D3DRMWRAP_CYLINDER,
    D3DRMWRAP_SPHERE,
    D3DRMWRAP_CHROME
} D3DRMWRAPTYPE;

値

D3DRMWRAP_FLAT
プレーンラップ。
D3DRMWRAP_CYLINDER
円柱ラップ。
D3DRMWRAP_SPHERE
球体ラップ。
D3DRMWRAP_CHROME
ラップは、テクスチャがオブジェクト上で反射されるようにテクスチャ座標を割り当てる。

参照

IDirect3DRM3::CreateWrap, IDirect3DRMWrap::Init, 「ラップ」

D3DRMXOFFORMAT

IDirect3DRMMeshBuilder3::Saveメソッドで使用されるファイルタイプを定義する。

構文

typedef enum _D3DRMXOFFORMAT{
    D3DRMXOF_BINARY,
    D3DRMXOF_COMPRESSED,
    D3DRMXOF_TEXT
} D3DRMXOFFORMAT;

値

D3DRMXOF_BINARY
ファイルはバイナリフォーマットである。これはデフォルト設定である。
D3DRMXOF_COMPRESSED
現在はサポートされていない。
D3DRMXOF_TEXT
ファイルはテキストフォーマットである。

注意

D3DRMXOF_BINARYとD3DRMXOF_TEXT設定を同時に使用することはできない。

参照

IDirect3DRMMeshBuilder3::Save

D3DRMZBUFFERMODE

Zバッファが有効かどうかを示す。

構文

typedef enum _D3DRMZBUFFERMODE {
    D3DRMZBUFFER_FROMPARENT,
    D3DRMZBUFFER_ENABLE,
    D3DRMZBUFFER_DISABLE
} D3DRMZBUFFERMODE;

値

D3DRMZBUFFER_FROMPARENT
フレームは親フレームからZバッファの設定を継承する。これはデフォルト設定である。
D3DRMZBUFFER_ENABLE
Zバッファは有効である。
D3DRMZBUFFER_DISABLE
Zバッファは無効である。

参照

IDirect3DRMFrame3::GetZbufferMode, IDirect3DRMFrame3::SetZbufferMode


C++構造体

Microsoft® Direct3D®保持モードのC++構造体は、次の通りである。

  • D3DRMANIMATIONKEY
  • D3DRMBOX
  • D3DRMIMAGE
  • D3DRMLOADMEMORY
  • D3DRMLOADRESOURCE
  • D3DRMMATERIALOVERRIDE
  • D3DRMPALETTEENTRY
  • D3DRMPICKDESC
  • D3DRMPICKDESC2
  • D3DRMPMESHLOADSTATUS
  • D3DRMQUATERNION
  • D3DRMRAY
  • D3DRMVECTOR4D
  • D3DRMVERTEX

D3DRMANIMATIONKEY

IDirect3DRMAnimation2::AddKeyメソッド、GetKeysメソッド、ModifyKeyメソッドが使用するキーを定義する。

構文

typedef struct _D3DRMANIMATIONKEY
{
    DWORD dwSize;
    DWORD dwKeyType;
    D3DVALUE dvTime;
    DWORD dwId ;
    union
    {
        D3DRMQUATERNION dqRotateKey;
        D3DVECTOR dvScaleKey;
        D3DVECTOR dvPositionKey;
    };
} D3DRMANIMATIONKEY;
typedef D3DRMANIMATIONKEY *LPD3DRMANIMATIONKEY;

メンバ

dwSize
アニメーションのサイズ。
dwKeyType
キーのタイプ。アニメーションの再生方法を定義するD3DRMANIMATIONOPTIONS定数の1つ。
dvTime
D3DVALUE型の任意の単位とメンバの時間値。
dwId
キー識別子。
dqRotateKey
回転を定義するD3DRMQUATERNION構造体タイプの値。
dvScaleKey
スケールを定義するD3DVECTOR構造体タイプの値。
dvPositionKey
位置を定義するD3DVECTOR構造体タイプの値。

D3DRMBOX

IDirect3DRMMesh::GetBoxやIDirect3DRMMeshBuilder3::GetBoxメソッドで取得する矩形範囲を定義する。

構文

typedef struct _D3DRMBOX {
    D3DVECTOR min, max;
}D3DRMBOX;
typedef D3DRMBOX *LPD3DRMBOX;

メンバ

min, max
矩形範囲を定義する値。これらの値はD3DVECTOR構造体である。

参照

D3DVECTOR, IDirect3DRMMesh::GetBox, IDirect3DRMMeshBuilder3::GetBox

D3DRMIMAGE

IDirect3DRM3::CreateTextureメソッドによってテクスチャにアタッチされるイメージを記述する。IDirect3DRMTexture3::GetImageは、このイメージのアドレスを返す。

構文

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;

メンバ

width, height
ピクセル単位でのイメージの幅と高さ。
aspectx, aspecty
非正方形ピクセルのアスペクト比。
depth
ピクセル当たりのビット数。
rgb
ピクセルがRGB値であるかパレットインデックスであるかを示すフラグ。このメンバがFALSEの場合、ピクセルはパレットのインデックスを示す。このメンバがTRUEのときは、ピクセルはコード化されたRGB値である。
bytes_per_line
1ライン当たりのバイト数。この値は4の倍数である。
buffer1
レンダリングが行われるメモリ（最初のバッファ）のアドレス。
buffer2
ダブルバッファリングの2番目のレンダリングバッファ。シングルバッファリングのときはNULLを設定する。
red_mask, green_mask, blue_mask, alpha_mask
RGBピクセルまたはピクセルパレットインデックスのマスク。rgbがTRUEのとき、これらのメンバはピクセルの赤、緑、青部分のマスクである。rgbがFALSEのときは、パレット中で重要な赤、緑、青の各要素ビットのマスクである。たとえば多くのスーパーVGA（SVGA）ディスプレイでは、使用する赤、緑、青の度合は64であるため、すべてのマスクは0xfcにセットされる。
palette_size
パレットエントリの数。
palette
使用されるカラーパレットを示すD3DRMPALETTEENTRY構造体のポインタ。この構造体は、D3DRMIMAGEのrgbメンバがFALSEの場合にだけ使用される。

参照

IDirect3DRM3::CreateTexture, IDirect3DRMTexture3::GetImage

D3DRMLOADMEMORY

アプリケーションがD3DRMLOAD_FROMMEMORYを指定してIDirect3DRM3::Loadメソッド（または他のLoadメソッド）を使用したときにロードされるリソースを示す。

構文

typedef struct _D3DRMLOADMEMORY {
    LPVOID lpMemory;
    DWORD  dSize;
} D3DRMLOADMEMORY, *LPD3DRMLOADMEMORY;

メンバ

lpMemory
ロードされるメモリブロック。
dSize
ロードされるメモリブロックのサイズをバイト単位で示す。

参照

IDirect3DRM3::Load, IDirect3DRMAnimationSet2::Load, IDirect3DRMFrame3::Load, IDirect3DRMMeshBuilder3::Load, D3DRMLOADOPTIONS, D3DRMLOADRESOURCE

D3DRMLOADRESOURCE

アプリケーションがD3DRMLOAD_FROMRESOURCEを指定してIDirect3DRM3::Loadメソッド（または他のLoadメソッドの1つ）を使ったときにロードされるリソースを示す。

構文

typedef struct _D3DRMLOADRESOURCE {
    HMODULE hModule;
    LPCTSTR lpName;
    LPCTSTR lpType;
} D3DRMLOADRESOURCE, *LPD3DRMLOADRESOURCE;

メンバ

hModule
ロードされるリソースを含むモジュールのハンドル。リソースが、呼び出し元の実行可能ファイル、またはリソースを使用しているダイナミックリンクライブラリ（DLL）にアタッチされているときは、このメンバにNULLを指定する。

lpName
ロードされるリソースの名前。たとえば、リソースがメッシュであれば、このメンバにメッシュファイルの名前を指定する。
lpType
リソースを識別するユーザ定義のタイプ。

注意

lpNameやlpTypeメンバの上位ワードが0の場合、下位ワードは、その名前の整数識別子または指定されたリソースのタイプを示す。そうでなければ、これらのパラメータはNULLで終わる文字列へのロングポインタである。文字列の先頭文字がシャープ記号（#）のときは、残りの文字はリソースの名前やタイプの整数識別子を示す10進数を表す。たとえば、文字列"#258"は整数識別子258を表す。名前の代わりに整数識別子を参照すれば、リソースが必要とするメモリの量を減らすことができる。

D3DRMLOAD_FROMRESOURCEを指定してLoadメソッドを使えば、アプリケーションでリソースを探したりアンロックする必要はない。この場合、システムが自動的にその処理を行う。

参照

IDirect3DRM3::Load, IDirect3DRMAnimationSet2::Load, IDirect3DRMFrame3::Load, IDirect3DRMMeshBuilder3::Load, D3DRMLOADMEMORY, D3DRMLOADOPTIONS

D3DRMMATERIALOVERRIDE

IDirect3DRMFrame3::SetMaterialOverrideメソッドとIDirect3DRMFrame3::GetMaterialOverrideメソッドのオーバーライドを記述する。

構文

typedef struct _D3DRMMATERIALOVERRIDE
{
    DWORD         dwSize;
    DWORD         dwFlags;
    D3DCOLORVALUE dcDiffuse;
    D3DCOLORVALUE dcAmbient;
    D3DCOLORVALUE dcEmissive;
    D3DCOLORVALUE dcSpecular;
    D3DVALUE      dvPower;
    LPUNKNOWN     lpD3DRMTex;
} D3DRMMATERIALOVERRIDE, *LPD3DRMMATERIALOVERRIDE;

メンバ

dwSize
この構造体のバイトサイズ。
dwFlags
この構造体のどのフィールドが有効かを示す、フラグの論理的組み合わせ。可能な値は次の通りである。
D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAONLY
D3DRMMATERIALOVERRIDE_DIFFUSE_RGBONLY
D3DRMMATERIALOVERRIDE_DIFFUSE
D3DRMMATERIALOVERRIDE_AMBIENT
D3DRMMATERIALOVERRIDE_EMISSIVE
D3DRMMATERIALOVERRIDE_SPECULAR
D3DRMMATERIALOVERRIDE_POWER
D3DRMMATERIALOVERRIDE_TEXTURE
D3DRMMATERIALOVERRIDE_ALL
dcDiffuse
D3DCOLORVALUE型の拡散RGBAカラー設定。
dcAmbient
D3DCOLORVALUE型のアンビエントRGBカラー設定。
dcEmissive
D3DCOLORVALUE型の放射RGBカラー設定。
dcSpecular
D3DCOLORVALUE型の反射RGBカラー設定。
dvPower
D3DVALUE型の強度設定。
lpD3DRMTex
テクスチャインターフェイスへのポインタ。

D3DRMPALETTEENTRY

D3DRMIMAGE構造体で使用されるカラーパレットを記述する。この構造体は、D3DRMIMAGE構造体のrgbメンバにFALSEが指定されているときのみ利用される（TRUEが指定されているときは、RGB値が用いられる）。

構文

typedef struct _D3DRMPALETTEENTRY {
    unsigned char red;
    unsigned char green;
    unsigned char blue;
    unsigned char flags;
}D3DRMPALETTEENTRY;
typedef D3DRMPALETTEENTRY, *LPD3DRMPALETTEENTRY;

メンバ

red, green, blue
パレットを定義する原色要素を定義する値。0から255の範囲の値を指定することができる。
flags
レンダリング時にパレットがどのように使用されるかを定義する値。この値はD3DRMPALETTEFLAGS列挙型のメンバの1つである。

参照

D3DRMIMAGE, D3DRMPALETTEFLAGS

D3DRMPICKDESC

IDirect3DRMPickedArray::GetPickメソッドによって取得された、ピックの位置、面、グループ識別子を格納する。

構文

typedef struct _D3DRMPICKDESC {
    ULONG       ulFaceIdx;
    LONG        lGroupIdx;
    D3DVECTOR   vPosition;
} D3DRMPICKDESC, *LPD3DRMPICKDESC;

メンバ

ulFaceIdx
取得されたオブジェクトの面のインデックス。
lGroupIdx
取得されたオブジェクトのグループ識別子。
vPosition
取得されたオブジェクトの位置を示す値。この値はD3DVECTOR構造体である。

参照

D3DVECTOR, IDirect3DRMPickedArray::GetPick

D3DRMPICKDESC2

IDirect3DRMPicked2Array::GetPickメソッドによって取り出された面やグループの識別子、ピックの位置、頂点の水平および垂直テクスチャ座標、頂点の法線およびオブジェクトの色を格納する。

構文

typedef struct _D3DRMPICKDESC2
{
    ULONG	ulFaceIdx;
    LONG	lGroupIdx;
    D3DVECTOR	dvPosition;
    D3DVALUE	tu;
    D3DVALUE	tv;
    D3DVECTOR	dvNormal;
    D3DCOLOR	dcColor;

} D3DRMPICKDESC2, *LPD3DRMPICKDESC2;

メンバ

ulFaceIdx
取得されたオブジェクトの面のインデックス。
lGroupIdx
取得されたオブジェクトのグループ識別子。
vPosition
取得されたオブジェクトの位置を示す値。この値はD3DVECTOR構造体である。
tu, tv
頂点の水平および垂直テクスチャ座標。
dvNormal
頂点の法線ベクトル。
dcColor
頂点の色。

D3DRMPMESHLOADSTATUS

IDirect3DRMProgressiveMesh::Loadメソッドを使用してロードされたプログレッシブメッシュのロード状態を格納する。この構造体は、IDirect3DRMProgressiveMesh::GetLoadStatusメソッドを使用して取得できる。

構文

typedef struct _D3DRMPMESHLOADSTATUS {
    DWORD dwSize;
    DWORD dwPMeshSize;
    DWORD dwBaseMeshSize;
    DWORD dwBytesLoaded;
    DWORD dwVerticesLoaded;
    DWORD dwFacesLoaded;
    DWORD dwFlags;
} D3DRMPMESHLOADSTATUS;
typedef D3DRMPMESHLOADSTATUS *LPD3DRMPMESHLOADSTATUS;

メンバ

dwSize
構造体のサイズ。
dwPMeshSize
プログレッシブメッシュのバイト単位の全体サイズ。
dwBaseMeshSize
ベースメッシュのバイト単位のサイズ。
dwBytesLoaded
ロードされた合計バイト数。
dwVerticesLoaded
ロードされた頂点の数。
dwFacesLoaded
ロードされた面の数。
dwFlags
プログレッシブメッシュロードの状態を示すフラグ。以下の値の1つを取ることができる。

D3DRMPMESHSTATUS_VALID － プログレッシブメッシュオブジェクトは、有効なデータを含む。
D3DRMPMESHSTATUS_INTERRUPTED － ダウンロードは、アプリケーションがIDirect3DRMProgressiveMesh::Abortを使ったか、または接続が失われたかのいずれかの理由で割り込みを受けた。
D3DRMPMESHSTATUS_BASEMESHCOMPLETE － ベースメッシュのダウンロードが完了した。
D3DRMPMESHSTATUS_COMPLETE － すべてのデータのダウンロードが完了した。
D3DRMPMESHSTATUS_RENDERABLE － メッシュのレンダリングは、現在可能である。

参照

IDirect3DRMProgressiveMesh::GetLoadStatus, IDirect3DRMProgressiveMesh::Load

D3DRMQUATERNION

IDirect3DRMAnimation2::AddRotateKeyメソッドで用いられる回転と、IDirect3DRMFrame3::SetQuaternionで用いられる4元数を記述する。また、Direct3Dの数学関数のいくつかでも使用される。

構文

typedef struct _D3DRMQUATERNION {
    D3DVALUE   s;
    D3DVECTOR  v;
}D3DRMQUATERNION;
typedef D3DRMQUATERNION, *LPD3DRMQUATERNION;

参照

IDirect3DRMAnimation2::AddRotateKey, IDirect3DRMFrame3::SetQuaternion, D3DRMQuaternionFromRotation, D3DRMQuaternionMultiply, D3DRMQuaternionSlerp, D3DRMMatrixFromQuaternion

D3DRMRAY

光線の方向と開始位置をIDirect3DRMFrame3::RayPickに定義する。

構文

typedef struct _D3DRMRAY
{   D3DVECTOR dvDir;
    D3DVECTOR dvPos;
} D3DRMRAY, *LPD3DRMRAY;

メンバ

dvDir
光線ピックで用いられる光線の方向。
dvPos
光線ピックで用いられる光線の開始位置。

D3DRMVECTOR4D

スクリーン座標を記述する。この構造体は、IDirect3DRMViewport2::TransformおよびIDirect3DRMViewport2::TransformVectorsメソッドによる変換の出力先として、およびIDirect3DRMViewport2::InverseTransformおよびIDirect3DRMViewport2::InverseTransformVectorsメソッドによる変換のソースとして使用される。

構文

typedef struct _D3DRMVECTOR4D {
    D3DVALUE x;
    D3DVALUE y;
    D3DVALUE z;
    D3DVALUE w;
}D3DRMVECTOR4D;
typedef D3DRMVECTOR4D, *LPD3DRMVECTOR4D;

メンバ

x, y, z, w
D3DVALUE型の値。変換結果が入る。

参照

IDirect3DRMViewport2::Transform, IDirect3DRMViewport2::TransformVectors, IDirect3DRMViewport2::InverseTransform, IDirect3DRMViewport2::InverseTransformVectors

D3DRMVERTEX

Direct3DRMMeshオブジェクト中の頂点を記述する。

構文

typedef struct _D3DRMVERTEX{
    D3DVECTOR position;
    D3DVECTOR normal;
    D3DVALUE  tu, tv;
    D3DCOLOR  color;
} D3DRMVERTEX;

メンバ

position
頂点の位置。
normal
頂点の法線ベクトル。
tu, tv
頂点の水平および垂直テクスチャ座標。
color
頂点の色。

参照

IDirect3DRMMesh::GetVertices, IDirect3DRMMesh::SetVertices


C++戻り値

Microsoft® Direct3D®保持モード（COM）インターフェイスメソッドは、次の値を返す。

D3DRM_OK
成功。DD_OKと同等。
D3DRMERR_BADALLOC
メモリ不足。
D3DRMERR_BADDEVICE
デバイスはレンダラーと互換性がない。
D3DRMERR_BADFILE
データファイルが不正。
D3DRMERR_BADMAJORVERSION
DLLのメジャーバージョンが不正。
D3DRMERR_BADMAJORVERSION
DLLのマイナーバージョンが不正。
D3DRMERR_BADOBJECT
引数にはオブジェクトが必要。
D3DRMERR_BADPMDATA
.xファイル中のデータが不正。プログレッシブメッシュへの変換は成功したが、無効なプログレッシブメッシュが.xファイルに作成された。
D3DRMERR_BADTYPE
不正な型の引数が渡された。
D3DRMERR_BADVALUE
不正な値の引数が渡された。
D3DRMERR_BOXNOTSET
境界ボックスがフレームに設定されてないときに、境界ボックスにアクセスしようとした(たとえば、IDirect3DRMFrame3::GetBoxを用いて)。
D3DRMERR_CLIENTNOTREGISTERED
クライアントが登録されていない。IDirect3DRM3::RegisterClientを呼び出す。
D3DRMERR_CONNECTIONLOST
ロード、クローンまたは複製中にデータ接続が失われた。
D3DRMERR_ELEMENTINUSE
使用中は要素の修正または削除はできない。サブメッシュを空にするには、その親に対してEmpty()を呼び出す。
D3DRMERR_ENTRYINUSE
頂点または法線エントリは現在面が使用中であり、削除できない。
D3DRMERR_FACEUSED
面はメッシュ上で使用済みである。
D3DRMERR_FILENOTFOUND
ファイルを開くことができない。
D3DRMERR_INCOMPATIBLEKEY
指定されたアニメーションキーは互換性がない。キーを修正することはできない。
D3DRMERR_INVALIDLIBRARY
指定されたライブラリは無効である。
D3DRMERR_INVALIDOBJECT
メソッドが、無効なオブジェクトへのポインタを受け取った。
D3DRMERR_INVALIDPARAMS
メソッドに渡されたパラメータの1つが無効である。
D3DRMERR_LIBRARYNOTFOUND
指定されたライブラリが見つからない。
D3DRMERR_LOADABORTED
ロードがユーザによって強制終了させられた。
D3DRMERR_NOSUCHKEY
指定されたアニメーションキーは存在しない。
D3DRMERR_NOTCREATEDFROMDDS
指定されたテクスチャがDirectDrawサーフェスから作成されていない。
D3DRMERR_NOTDONEYET
実装されていない。
D3DRMERR_NOTENOUGHDATA
要求された処理を行うために十分なデータがロードされていない。
D3DRMERR_NOTFOUND
指定されたプレーンにオブジェクトが見つからない。
D3DRMERR_OUTOFRANGE
指定された値は範囲外である。
D3DRMERR_PENDING
要求された情報を供給するために必要なデータのロードが終了していない。
D3DRMERR_REQUESTTOOLARGE
利用可能な最大詳細レベルよりも大きな詳細レベルをプログレッシブメッシュに設定しようとした。
D3DRMERR_REQUESTTOOSMALL
ベースメッシュの詳細よりも小さなプログレッシブメッシュの最低レンダリング詳細を設定しようとした (レンダリングの最小値)。
D3DRMERR_TEXTUREFORMATNOTFOUND
指定された基準を満たし、下層の直接モードデバイスがサポートするテクスチャフォーマットが見つからなかった。
D3DRMERR_UNABLETOEXECUTE
プロシージャを実行できない。
DD_OK
要求は成功し完了した。D3DRM_OKと同等。
DDERR_INVALIDOBJECT
無効なオブジェクトのポインタを受け取った。
DDERR_INVALIDPARAMS
メソッドに渡された1つ以上のパラメータが不正である。
DDERR_NOTFOUND
要求された項目が見つからなかった。
DDERR_NOTINITIALIZED
オブジェクトが初期化される前に、CoCreateInstanceで作成したオブジェクトのインターフェイスメソッドを呼び出そうとした。
DDERR_OUTOFMEMORY
DirectDrawが処理を行うのに十分なメモリがない。


C++/COMプログラマのための追加情報

この項には、Microsoft® Direct3D® 保持モードのC++/COMリファレンスに関する次のトピックが含まれる。

  • カラーキーイング
  • D3DCOLOR_MONO
  • D3DCOLOR_RGB
  • D3DCOLORMODEL
  • D3DCOLORVALUE
  • D3DDEVICEDESC
  • D3DENUMDEVICESCALLBACK
  • D3DMATRIX
  • D3DPRIMCAPS
  • D3DRECT
  • D3DTRIANGLE
  • D3DVALUE
  • D3DVECTOR
  • DirectDrawCreate
  • DirectDrawCreateClipper
  • DrawPrimitive
  • IDirect3D3
  • IDirectDrawClipper
  • IUnknownインターフェイス
  • ミップマップ
  • テクスチャマップフォーマット

カラーキーイング
カラーキーは、一般にはアーティストが透明性のためにしか使用しない単一で共通性のない色であるが、これを指定した色範囲にすることもできる。IDirectDrawSurface3::SetColorKeyメソッドを使用して、サーフェスのカラーキーをセットすることができる。カラーキーをセットすると、IDirectDrawSurface3::BltFastに対する後続の呼び出しはそのカラーキーを活用し、一致するピクセルを無視する。このタイプのカラーキーは、ソースカラーキーと呼ばれる。ソースカラーキーは「透明」なピクセルが出力先に書き込まれないようにするため、オリジナルの背景ピクセルはこれらの場所に保存され、非方形オブジェクトであるスプライトが背景を横切っているかのように見える。出力先サーフェスに効果を与えるカラーキー (出力先カラーキー) を使用することもできる。

出力先カラーキーは、スプライトで上書き可能なピクセルに使用されるサーフェス上の色である。再度、アーティストは、イメージ中の他の場所で使用されていない任意の色を選択し、ブロック転送可能なイメージの一部としてそれを予約する。指定された出力先カラーキーによってスプライトを出力先サーフェスにブロック転送すると、スプライトのピクセルは、出力先カラーキーを使用中の出力先上のピクセルにのみブロック転送される。法線の出力先ピクセルは保存されているので、スプライトが出力先サーフェス上のイメージの背後を横切っているかのように見える。詳細については、 DirectX Foundation SDKの「DirectDrawの要点」セクションの「サーフェス」の項内の「透過型ブロック転送」を参照すること。

D3DCOLOR_MONO
モノクロモデル (ランプモデル) の使用をシステムに指示するD3DRMCOLORMODEL定数の値。このモデルでは、頂点の色の青要素を使用して、照らされる頂点の輝度を定義する。
D3DCOLOR_RGB
フルRGBモデルの使用をシステムに指示するD3DRMCOLORMODEL定数の値。
D3DCOLORMODEL
システムが実行するカラーモデルを定義する定数。
typedef enum _D3DCOLORMODEL {
    D3DCOLOR_MONO = 1,
    D3DCOLOR_RGB  = 2,
} D3DCOLORMODEL;
D3DCOLORVALUE
色の値を記述する構造体。dvR、dvG、dvB、dvAは、色の赤、緑、青、アルファ要素を指定するD3DVALUE型の値である。これらの値は、一般には0.0から1.0の範囲にあり、0.0は黒を指定する。
typedef struct _D3DCOLORVALUE {
    union {
        D3DVALUE r;
        D3DVALUE dvR;
    };
    union {
        D3DVALUE g;
        D3DVALUE dvG;
    };
    union {
        D3DVALUE b;
        D3DVALUE dvB;
    };
    union {
        D3DVALUE a;
        D3DVALUE dvA;
    };
} D3DCOLORVALUE;
D3DDEVICEDESC
現在のデバイスの記述を含む構造体。詳細については、「Direct3D直接モードリファレンス」の「構造体」の項のD3DDEVICEDESCを参照すること。
D3DENUMDEVICESCALLBACK
導入済みのDirect3D デバイスを列挙するコールバック関数のプロトタイプ定義。詳細については、「Direct3D直接モードリファレンス」の「コールバック関数」を参照すること。
typedef HRESULT (FAR PASCAL * LPD3DENUMDEVICESCALLBACK)
  (LPGUID lpGuid,
  LPSTR lpDeviceDescription,
  LPSTR lpDeviceName,
  LPD3DDEVICEDESC lpD3DHWDeviceDesc,
  LPD3DDEVICEDESC lpD3DHELD9eviceDesc,
  LPVOID lpUserArg
);
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;
D3DPRIMCAPS
各プリミティブタイプの機能を定義する構造体。IDirect3DRM3::CreateDeviceFromClipperを使用して、これらのデフォルト機能をセットする。

D3DPCMPCAPS_LESSEQUAL － 新しいz値が現在のz値以下の場合、zバッファ比較を渡す。

D3DPMISCCAPS_CULLCCW － このドライバは、D3DRENDERSTATE_CULLMODE状態を介して、時計と逆回りのカリングをサポートする (これは三角形プリミティブにのみ適用される)。

D3DPRASTERCAPS_FOGVERTEX － このデバイスは、ライティング操作中にフォグ値を計算し、D3DTLVERTEX構造体の反射メンバに与えられた D3DCOLOR値のアルファ要素にその値を配置し、ラスター化の際にフォグ値を補間する。

D3DPSHADECAPS_ALPHAFLATSTIPPLED － このデバイスは、フラット透明ブレンディングと透明点描 (D3DSHADEMODE列挙型のD3DSHADE_FLAT 状態) のアルファ要素をそれぞれサポートすることができる。これらのモードでは、プリミティブのアルファ色要素は、プリミティブの最初の頂点の色の一部として提供される。

D3DPTADDRESSCAPS_WRAP － このデバイスは、アドレスに対してテクスチャをラップすることができる。

D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE － コピーテクスチャブレンディングモード (D3DTEXTUREBLEND列挙型からのD3DTBLEND_COPY) と変調テクスチャブレンディングモード (D3DTEXTUREBLEND列挙型からのD3DTBLEND_MODULATE) がサポートされる。

D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY － パースペクティブ補正とテクスチャ透明性がサポートされる。

D3DPTFILTERCAPS_NEAREST － 希望するピクセル値に最も近い座標を持つテクセル (テクスチャの単一要素) が使用される。これは、ズームインとズームアウトの両方に適用される。ズームインとズームアウトのどちらかをサポートしている場合、両方をサポートしなければならない。

D3DRECT
方形を定義する構造体。
typedef struct _D3DRECT {
    union {
        LONG x1;
        LONG lX1;  //左上 x
    };
    union {
        LONG y1;
        LONG lY1;  //左上 y
    };
    union {
        LONG x2;
        LONG lX2; //右下 x
    };
    union {
        LONG y2;
        LONG lY2;  //右下 y
    };
} D3DRECT, *LPD3DRECT;
D3DTRIANGLE
すべての三角形のベースタイプを記述する構造体。三角形は主要なレンダリングプリミティブである。
D3DVALUE
基本的な Direct3D fractionalデータ型。
typedef float D3DVALUE, *LPD3DVALUE;
D3DVECTOR
Direct3DとDirect3D保持モードの多くのメソッドと構造体のベクトルを定義する構造体。
typedef struct _D3DVECTOR {
    union {
        D3DVALUE x;
        D3DVALUE dvX;
    };
    union {
        D3DVALUE y;
        D3DVALUE dvY;
    };
    union {
        D3DVALUE z;
        D3DVALUE dvZ;
    };
} D3DVECTOR, *LPD3DVECTOR;
DirectDrawCreate
DirectDrawオブジェクトのインスタンスを作成する関数。詳細については、「DirectDrawリファレンス」のDirectDrawCreate関数を参照すること。
DirectDrawCreateClipper
DirectDrawオブジェクトと関連付けられていない DirectDrawClipperオブジェクトのインスタンスを作成する関数。詳細については、「DirectDrawリファレンス」のDirectDrawCreateClipper関数を参照すること。
DrawPrimitive
IDirect3DDevice3::DrawPrimitiveメソッドは、指定された頂点配列を特定のタイプの幾何プリミティブのシーケンスとして描画する。幾何プリミティブのタイプには、点、線、三角形、三角形の扇形、三角形の展開などがある。
IDirect3D3
アプリケーションは、IDirect3D3インターフェイスのメソッドを使用してDirect3Dオブジェクトを作成し、環境をセットする。詳細については、「Direct3D直接モードリファレンス」の「IDirect3D3インターフェイス」を参照すること。
IDirect3D3::EnumDevices － このメソッドは、システムに導入済みのすべてのDirect3Dデバイスドライバを列挙する。
IDirect3D3::FindDevice － このメソッドは、指定した特性を持つデバイスを見つけ、その記述を取得する。
IDirectDrawClipper
アプリケーションは、IDirectDrawClipperインターフェイスのメソッドを使用して、クリップリストを管理する。詳細については、「DirectDrawリファレンス」の「IDirectDrawClipperインターフェイス」を参照すること。
IDirectDrawClipper::SetHWnd － このメソッドは、クリッピング情報を取得するウィンドウハンドルをセットする。
IUnknownインターフェイス
すべてのCOM (Component Object Model) インターフェイスは、IUnknownインターフェイスから引き出される。このインターフェイスは、オブジェクトの存続期間の制御と複数のインターフェイスを移動する機能を提供する。IUnknownには次の3つのメソッドがある。AddRef。これは、インターフェイスまたは別のアプリケーションが自分自身をオブジェクトにバインドしたときに、オブジェクトの参照カウントを1だけインクリメントする。QueryInterface。これは、固有のインターフェイスに対してポインタを要求することで、それがサポートする機能についてオブジェクトの照会を行う。Release。これは、オブジェクトの参照カウントを1だけデクリメントする。カウントが0になると、オブジェクトの割り当ては解除される。

IUnknown::AddRefおよびIUnknown::Release － これらのIUnknownメソッドは、オブジェクトの参照カウントを保守する。たとえば、DirectPlayオブジェクトを (たとえば、CoCreateInstanceによって) 作成する場合、オブジェクトの参照カウントは1にセットされる。関数がポインタをそのオブジェクトのインターフェイスに返すたびに、関数はそのポインタを介してAddRefを呼び出し、参照カウントをインクリメントしなければならない。また、各々のAddRef呼び出しとReleaseの呼び出しを照合しなければならない。ポインタを破棄する前に、そのポインタを介してReleaseを呼び出さなければならない。オブジェクトの参照カウントが0になると、オブジェクトは破棄され、それに対するすべてのインターフェイスが無効になる。
IUnknown::QueryInterface － このIUnknownメソッドは、オブジェクトが固有のインターフェイスをサポートするかどうかを決める。オブジェクトがインターフェイスをサポートする場合、QueryInterfaceはポインタをそのインターフェイスに返す。これで、そのインターフェイスに含まれるメソッドを使用して、オブジェクトと会話することができる。QueryInterfaceがポインタをインターフェイスに返すことに成功した場合、それは暗黙にAddRefを呼び出し、参照カウントをインクリメントする。このため、アプリケーションは、インターフェイスへのポインタを破棄する前に、Releaseを呼び出し、参照カウントをデクリメントしなければならない。
ミップマップ
ミップマップは、それぞれのテクスチャは解像度が漸次低くなる、同じイメージを事前にフィルタリングした表現である。ミップマップ中の各フィルタリングイメージまたはレベルは、以前のレベルより2の累乗ずつ小さくなっている。高解像度レベルは、ビューアに近いオブジェクトに使用される。オブジェクトが遠くに移動するにつれ、より低解像度のレベルが使用される。ミップマッピングは、テクスチャのレンダリングクオリティを向上する、計算上費用のかからない方法である。詳細については、「Direct3D直接モード」の「テクスチャ」の「ミップマップ」を参照すること。
テクスチャマップフォーマット
広範なテクスチャピクセルフォーマットが、Microsoft® DirectX® ハードウェアエミュレーションレイヤでサポートされている。これらのフォーマットについては、「DirectDrawリファレンス」の「テクスチャマップフォーマット」の表を参照すること。


Visual Basicリファレンス

Microsoft® Direct3D® 保持モードの Microsoft Visual Basic® リファレンスは、インターフェイス、クラス、メソッド、およびコールバックインターフェイスについて、構文、パラメータ記述、フラグ記述などの詳細情報を提供する。また、Direct3D 保持モード型のメンバ、列挙型、その他の定義済タイプ、返される可能性のあるエラー値についても記述する。この項には、次のトピックが含まれる。

インターフェイス

  • コールバックインターフェイス
  • インターフェイス

データタイプ

  • 列挙型
  • 型

その他のトピック

  • エラー値
  • 追加情報


Visual Basicコールバックインターフェイス

Microsoft® Direct3D® 保持モードの Microsoft Visual Basic® コールバックインターフェイスは次のとおりである。

  • Direct3DRMCallback
  • Direct3DRMDeviceUpdateCallback3
  • Direct3DRMEnumerateObjectsCallback
  • Direct3DRMFrameMoveCallback3
  • Direct3DRMLoadCallback
  • Direct3DRMLoadTextureCallback3

コールバックインターフェイスを使うには、たとえばDirect3DRMDeviceUpdateCallback3の場合であれば、次のような操作を行う。

  1. コードエディタウィンドウに次の行をコピーする。
    Implements Direct3DRMDeviceUpdateCallback3
  2. Enterキーを押す。
  3. [オブジェクト] ボックスの [Direct3DRMDeviceUpdateCallback3] をクリックする。Direct3DRMDeviceUpdateCallback3 インターフェイスの構文ブロックが表示される。
    Private Sub Direct3DRMDeviceUpdateCallback3_CallbackRMUpdate(
    ByVal f As DxVBLib.Direct3DRMDevice3, ByVal arg As Object,
    ByVal n As Long, Update As DxVBLib.D3DRECT)
    'do something
End Sub

Direct3DRMCallback.CallbackRMDestroyObject

オブジェクトを削除する。

構文

object_CallbackRMDestroyObject(ByVal args As Object)

要素

object
Direct3DRMCallbackオブジェクトを表すオブジェクト式。
args
このコールバックに渡されるアプリケーション定義のデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMDeviceUpdateCallback3.CallbackRMUpdate

デバイスが変更されたときはアプリケーションに警告する。このコールバックはアプリケーションで定義される。

構文

object_CallbackRMUpdate(ByVal f As DxVBLib.Direct3DRMDevice3,
  ByVal arg As Object,
  ByVal n As Long,
  Update As DxVBLib.D3DRECT)

要素

object
Direct3DRMDeviceUpdateCallback3オブジェクトを表すオブジェクト式。
f
このコールバックが適用されるDirect3DRMDevice3オブジェクト。
arg
このコールバックに渡されるアプリケーション定義のデータ。
n
Updateパラメータに指定された矩形の数。
Update
更新する領域を表すD3DRECTのタイプ。座標はデバイス単位で指定される。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMEnumerateObjectsCallback.CallbackRMEnumerateObjects

Direct3DRM3.EnumerateObjectsメソッドの呼び出しに応答するオブジェクトを列挙する。このコールバックはアプリケーションで定義される。

構文

object_CallbackRMEnumerateObjects(ByVal Object As DxVBLib.Direct3DRMObject,
  ByVal userArgument As Object)

要素

object
Direct3DRMEnumerateObjectsCallbackオブジェクトを表すオブジェクト式。
object
Direct3DRMObjectオブジェクト。
userArgument
このコールバックに渡されるアプリケーション定義のデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameMoveCallback3.CallbackRMFrameMove

フレームの移動や更新時に、アプリケーションがカスタマイズしたアルゴリズムを適用できるようにする。フレームレートを変更するためにこのコールバックを使用することができる。このコールバックはアプリケーションで定義される。

構文

object_CallbackRMFrameMove(ByVal f As DxVBLib.Direct3DRMFrame3,
  ByVal arg As Object,
  ByVal delta As Single)

要素

object
Direct3DRMFrameMoveCallback3オブジェクトを表すオブジェクト式。
f
変更しようとしているDirect3DRMFrame3オブジェクト。
arg
このコールバックに渡されるアプリケーション定義のデータ。
delta
運動に適用される変化量。フレームの位置を変更するには、直線と回転の2つの要素がある。各要素における変更は、velocity_of_component × deltaに等しい。これらの一方または両方の速度は、任意のフレームを起点として設定することができるが、システムは、自動的にデルタ時間を適用するので、親フレームを起点とした速度に変換する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アプリケーションは、親フレームを基準にしてフレームの加速を合成することができる。そのためには、各ティックで、アプリケーションは、子フレームの速度をアプリケーション自身を基準とした（1ティックあたりaユニット）× 1ティックに設定する必要がある。ここで、aは要求された加速度である。これは、ティック当たりのa× deltaに等しい。内部的には、子フレームを基準としたティック当たりのa × deltaは、親フレームを基準とした（v + (a × delta)）ユニットに変換される。ここで、vは、親を基準とする子フレームの現在の速度である。

このコールバックを追加または削除するには、Direct3DRMFrame3.AddMoveCallbackおよびDirect3DRMFrame3.DeleteMoveCallbackメソッドを使用する。

システムは、コールバックを使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバックを使う。

Direct3DRMLoadCallback.CallbackRMLoad

Direct3DRM3.LoadFromFileメソッド内部でオブジェクトのロードを行う。このコールバックはアプリケーションで定義される。

構文

object_CallbackRMLoad(Obj As DxVBLib.Direct3DRMObject,
  ByVal guid As String,
  ByVal userArgument As Object)

要素

object
Direct3DRMLoadCallbackオブジェクトを表すオブジェクト式。
Obj
ロードされるDirect3DRMObjectオブジェクト。
guid
ロードされるオブジェクトのグローバルユニーク識別子（GUID）。
userArgument
このコールバックに渡されるアプリケーション定義のデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

システムは、コールバックを使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバックを使う。

参照

Direct3DRM3.LoadFromFile

Direct3DRMLoadTextureCallback3.CallbackRMLoadTexture

LoadFromFileメソッドの内部で、テクスチャファイル (またはリソース) の実際の読み込みを行う。テクスチャは、2で割れる幅と長さでなければならない。このコールバックはアプリケーションで定義される。

構文

object_CallbackRMLoadTexture(ByVal textureName As String,
  ByVal userArgument As Object) As DxVBLib.Direct3DRMTexture3

要素

object
Direct3DRMLoadTextureCallback3オブジェクトを表すオブジェクト式。
textureName
テクスチャ名に含まれる文字列。
userArgument
このコールバックに渡されるアプリケーション定義のデータ。

戻り値

Direct3DRMTexture3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アプリケーションは、Microsoft® Windows®ビットマップ（.bmp）やポータブルピクセルマップビットマップ（.ppm） P6形式以外のテクスチャのサポートをインプリメントするため、このコールバックを使用することができる。P6フォーマットは、色イメージのバイナリファイルフォーマットである

システムは、コールバックを使う順序を決定するため、まず階層のトップレベルにあるオブジェクトを検索する。次に、作成された順番にコールバックを使う。

参照

Direct3DRM3.LoadFromFile、Direct3DRMAnimationSet2.LoadFromFile、Direct3DRMFrame3.LoadFromFile、Direct3DRMMeshBuilder3.LoadFromFile


Visual Basicインターフェイス

Microsoft® Direct3D® 保持モードのMicrosoft Visual Basic®インターフェイスは次のとおりである。

  • Direct3DRM3
  • Direct3DRMAnimation2
  • Direct3DRMAnimationArray
  • Direct3DRMAnimationSet2
  • Direct3DRMClippedVisual
  • Direct3DRMDevice3
  • Direct3DRMDeviceArray
  • Direct3DRMFace2
  • Direct3DRMFaceArray
  • Direct3DRMFrame3
  • Direct3DRMFrameArray
  • Direct3DRMFrameInterpolator
  • Direct3DRMLight
  • Direct3DRMLightArray
  • Direct3DRMLightInterpolator
  • Direct3DRMMaterial2
  • Direct3DRMMaterialInterpolator
  • Direct3DRMMesh
  • Direct3DRMMeshBuilder3
  • Direct3DRMMeshInterpolator
  • Direct3DRMObject
  • Direct3DRMObjectArray
  • Direct3DRMPick2Array
  • Direct3DRMPickArray
  • Direct3DRMProgressiveMesh
  • Direct3DRMShadow2
  • Direct3DRMTexture3
  • Direct3DRMTextureInterpolator
  • Direct3DRMViewport2
  • Direct3DRMViewportArray
  • Direct3DRMViewportInterpolator
  • Direct3DRMVisual
  • Direct3DRMVisualArray
  • Direct3DRMWrap


Direct3DRM3

アプリケーションは、Direct3DRM3インターフェイスを使用してDirect3DRM3オブジェクトを生成し、システムレベル変数に従って動作する。

Direct3DRM3インターフェイスのメソッドは、次のオブジェクトを作成する。

  • アニメーションとアニメーションセット
  • クリップビジュアル
  • デバイス
  • 面
  • フレーム
  • 汎非初期化オブジェクト
  • 照明
  • マテリアル
  • メッシュとメッシュビルダ
  • 影
  • テクスチャ
  • ビューポート
  • ラップ

アプリケーションはDirect3DRMDevice3インターフェイスを使用して出力デバイスと対話する。Direct3DRM3インターフェイスを使用して作成する際の出力デバイス機能の詳細については、 「Direct3DRMDevice3」を参照すること。

Direct3DRM3インターフェイスのメソッドは、以下のグループにまとめることができる。

アニメーション | CreateAnimation
CreateAnimationSet
クリップビジュアル | CreateClippedVisual
デバイス | CreateDeviceFromClipper
CreateDeviceFromD3D
CreateDeviceFromSurface
GetDevices
列挙 | EnumerateObjects
面 | CreateFace
フレーム | CreateFrame
インターポレータ | CreateInterpolatorFrame
CreateInterpolatorLight
CreateInterpolatorMaterial
CreateInterpolatorMesh
CreateInterpolatorTexture
CreateInterpolatorViewport
照明 | CreateLight
CreateLightRGB
マテリアル | CreateMaterial
メッシュ | CreateMesh
CreateMeshBuilder
その他 | GetNamedObject
GetOptions
LoadFromFile
SetOptions
Tick
プログレッシブメッシュ | CreateProgressiveMesh
パス検索 | AddSearchPath
GetSearchPath
SetSearchPath
影 | CreateShadow
テクスチャ | CreateTextureFromSurface
LoadTexture
SetDefaultTextureColors
SetDefaultTextureShades
ビューポート | CreateViewport
ラップ | CreateWrap

Direct3DRM3.AddSearchPath

Direct3DRM3

現在のファイル検索パスの最後にディレクトリのリストを追加する。

構文

object.AddSearchPath(name As String)

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
name
現在の検索パスに追加するパスを指定する文字列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

Microsoft® Windows®では、パスは、セミコロン(;)で区切られたリストにする必要がある。

参照

Direct3DRM3.SetSearchPath

Direct3DRM3.CreateAnimation

Direct3DRM3

空のDirect3DRMAnimation2オブジェクトを生成する。

構文

object.CreateAnimation( ) As Direct3DRMAnimation2

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMAnimation2オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateAnimationSet

Direct3DRM3

空のDirect3DRMAnimationSet2オブジェクトを作成する。

構文

object.CreateAnimationSet( ) As Direct3DRMAnimationSet2

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMAnimationSet2 オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateClippedVisual

Direct3DRM3

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

構文

object.CreateClippedVisual(vis As Direct3DRMVisual)
  As Direct3DRMClippedVisual

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
vis
Direct3DRMMeshBuilder3オブジェクトなどのDirect3DRMVisualオブジェクト。

戻り値

Direct3DRMClippedVisual オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateDeviceFromClipper

Direct3DRM3

指定されたDirectDrawClipperオブジェクトを使用してDirect3DRMDevice3オブジェクトを作成する。

構文

object.CreateDeviceFromClipper(DDClipper As DirectDrawClipper,
  guid As String,
  width As Long,
  height As Long) As Direct3DRMDevice3

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
DDClipper
DirectDrawClipperオブジェクト。
guid
グローバルユニーク識別子(GUID)。 このパラメータは""にできる。
width, height
作成するデバイスのピクセル単位の幅と高さ。

戻り値

Direct3DRMDevice3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

guidパラメータが""の場合、システムは、デバイス性能のデフォルトセットを検索する。これは、保持モードデバイスを生成する方法として推奨する。なぜなら、ユーザが新しいハードウェアをインストールした場合でも、常に機能するからである。

システムは、内部デバイス列挙の呼び出しで、D3DPRIMCAPS型を使用して、デフォルト設定値を記述する。

ハードウェアデイバスが検出されなかった場合には、モノクロ(ランプ)のソフトウェアドライバがロードされる。デフォルト設定値のこのリストでは満たされない特別な要件がある場合、アプリケーションは、guidパラメータに対して""を指定する代わりにデバイスを列挙する必要がある。guidパラメータに""を指定すると、使用可能なものがあればハードウェアデバイスが選択され、なければデフォルトでソフトウェアラスタライザに設定される。

デバイスを指定するには、GetDirect3Dメソッドを呼び出し、DirectDraw4を介してDirect3D3オブジェクトを取得することで適切なGUIDを検索する。次に、Direct3D3オブジェクト上のGetDevicesEnumを呼び出してDirect3DEnumDevicesオブジェクトを取得する。Direct3DEnumDevicesオブジェクトから、GUIDをデバイスの記述と機能に合わせることができる。

デバイスの詳細については、「Direct3DRMDevice3」を参照すること。

Direct3DRM3.CreateDeviceFromD3D

Direct3DRM3

指定されたDirect3Dを使用してDirect3D保持モードWindowsデバイスを生成する。

構文

object.CreateDeviceFromD3D(D3D As Direct3D3,
  dev As Direct3DDevice3) As Direct3DRMDevice3

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
D3D
Direct3D3直接モードオブジェクトのインスタンス。
dev
Direct3DDevice3直接モードデバイスオブジェクト。

戻り値

Direct3DRMDevice3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デバイスの詳細については、「Direct3DRMDevice3」を参照すること。

Direct3DRM3.CreateDeviceFromSurface

Direct3DRM3

指定されたDirectDrawサーフェスからレンダリングするためのDirect3D保持モードWindowsデバイスを生成する。

構文

object.CreateDeviceFromSurface(g As String,
  dd As DirectDraw4,
  ddS As DirectDrawSurface4,
  flags As CONST_D3DRMCREATEDEVICEFLAGS) As Direct3DRMDevice3

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
g
要求されたデバイスドライバとして使用されるグローバルユニーク識別子(GUID)。このパラメータが""の場合、デフォルトのデバイスドライバが使用される。
dd
DirectDrawサーフェスのソースであるDirectDraw4オブジェクト
ddS
バックバッファを表すDirectDrawSurface4オブジェクト
flags
CONST_D3DRMCREATEDEVICEFLAGS列挙型からの1つ以上の値。

戻り値

Direct3DRMDevice3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デバイスの詳細については、「Direct3DRMDevice3」を参照すること。

Direct3DRM3.CreateFace

Direct3DRM3

Direct3DRMFace2インターフェイスのインスタンスを生成する。

構文

object.CreateFace( ) As Direct3DRMFace2

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMFace2オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateFrame

Direct3DRM3

指定の親フレームの新しい子フレームを生成する。

構文

object.CreateFrame(parent As Direct3DRMFrame3) As Direct3DRMFrame3

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
parent
新しいフレームの親となるDirect3DRMFrame3オブジェクト。

戻り値

Direct3DRMFrame3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

子フレームは、その親から運動属性を継承する。たとえば、親が一定の速度で動いているときには、子フレームも同じ速度で動く。さらに、親に回転がセットされると、子フレームは、親の原点の周囲を回転する。親を持たないフレームは、シーンと呼ばれる。シーンを作成するには、親としてNOTHINGを指定する。アプリケーションは、親のないフレームを作成した後、Direct3DRMFrame3.AddChildメソッドを使用して、後で親フレームに関連させることができる。

アプリケーションが右手ジオメトリをセットするためにDirect3DRM3.SetOptionsを呼び出した場合、ルートフレーム (親としてNOTHINGを持つフレーム) のデフォルト軸は、v = (0, 0, -1) かつ u = (0, 1, 0) になる。このため、Direct3DRMFrame3.GetOrientationとDirect3DRMFrame3.SetOrientationは、右手モードで正しく機能する。

Direct3DRM3.CreateInterpolatorFrame

Direct3DRM3

Direct3DRMFrameInterpolatorインターフェイスのインスタンスを生成する。

構文

object.CreateInterpolatorFrame( ) As Direct3DRMFrameInterpolator

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMFrameInterpolatorオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateInterpolatorLight

Direct3DRM3

Direct3DRMLightInterpolatorインターフェイスのインスタンスを生成する。

構文

object.CreateInterpolatorLight( ) As Direct3DRMLightInterpolator

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMLightInterpolatorオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateInterpolatorMaterial

Direct3DRM3

Direct3DRMMaterialInterpolatorインターフェイスのインスタンスを生成する。

構文

object.CreateInterpolatorMaterial( ) As Direct3DRMMaterialInterpolator

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMMaterialInterpolatorオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateInterpolatorMesh

Direct3DRM3

Direct3DRMMeshInterpolatorインターフェイスのインスタンスを生成する。

構文

object.CreateInterpolatorMesh( ) As Direct3DRMMeshInterpolator

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMMeshInterpolatorオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateInterpolatorTexture

Direct3DRM3

Direct3DRMTextureInterpolatorインターフェイスのインスタンスを生成する。

構文

object.CreateInterpolatorTexture( ) As Direct3DRMTextureInterpolator

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMTextureInterpolatorオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateInterpolatorViewport

Direct3DRM3

Direct3DRMViewportInterpolatorインターフェイスのインスタンスを生成する。

構文

object.CreateInterpolatorViewport( ) As Direct3DRMViewportInterpolator

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMViewportInterpolatorオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateLight

Direct3DRM3

指定のタイプと色で、新しい照明を作成する。

構文

object.CreateLight(lt As CONST_D3DRMLIGHTTYPE,
  color As Long) As Direct3DRMLight

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
lt
CONST_D3DRMLIGHTTYPE列挙型で与えられる照明タイプの1つ。
color
照明の色を表す4バイトのLong値。最後の3バイトは、色のRGB要素を表す。色のLong値を返すために、DirectX 7オブジェクトのCreateColorRGBを使うことができる。異なる照明タイプの記述については、Direct3D保持モードのC++に関するマニュアルの概要セクションを参照すること。

戻り値

Direct3DRMLightオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateLightRGB

Direct3DRM3

指定の赤、緑、青の要素で、新しい照明を作成する。

構文

object.CreateLightRGB(lt As CONST_D3DRMLIGHTTYPE,
  vred As Single,
  vgreen As Single,
  vblue As Single) As Direct3DRMLight

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
lt
CONST_D3DRMLIGHTTYPE列挙型で与えられる照明タイプの1つ。
vred, vgreen, vblue
照明の色。色の各要素は、0.0から1.0の範囲にある必要がある。

戻り値

Direct3DRMLightオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateMaterial

Direct3DRM3

C指定の反射プロパティを持つマテリアルを作成する。

構文

object.CreateMaterial(d As Single) As Direct3DRMMaterial2

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
d
反射するハイライトの鋭さ。レンダリングする表面に、5の値は金属の外観を与え、より大きい値はよりプラスチック的な外観を与える。

戻り値

Direct3DRMMaterial2オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateMesh

Direct3DRM3

面をもたない新しいメッシュオブジェクトを生成する。このメッシュは、フレームに追加されるまでは目に見えない。

構文

object.CreateMesh( ) As Direct3DRMMesh

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMMeshオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateMeshBuilder

Direct3DRM3

新しいメッシュビルダオブジェクトを生成する。

構文

object.CreateMeshBuilder( ) As Direct3DRMMeshBuilder3

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMMeshBuilder3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デフォルトでは、パースペクティブ補正がオンである。

Direct3DRM3.CreateProgressiveMesh

Direct3DRM3

面をもたない新しいプログレッシブメッシュオブジェクトを生成する。 メッシュは、フレームに追加されるまで目に見えない。

構文

object.CreateProgressiveMesh( ) As Direct3DRMProgressiveMesh

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMProgressiveMeshオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateShadow

Direct3DRM3

指定のビジュアルと照明を使用して影を作成し、指定の平面にその影を投影する。影も一種のビジュアルであり、ビジュアルを含むフレームに追加する必要がある。

構文

object.CreateShadow(visual As Direct3DRMVisual,
  light As Direct3DRMLight,
  px As Single,
  py As Single,
  pz As Single,
  nx As Single,
  ny As Single,
  nz As Single) As Direct3DRMShadow2

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
visual
Direct3DRMVisualオブジェクト。
light
照明であるDirect3DRMLightオブジェクト。
px, py, pz
影が投影される平面。
nx, ny, nz
影が投影される平面に対する法線。

戻り値

Direct3DRMShadow2オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateTextureFromSurface

Direct3DRM3

指定されたDirectDrawサーフェスからテクスチャを作成する。

構文

object.CreateTextureFromSurface(
    ddS As DirectDrawSurface4)
    As Direct3DRMTexture3

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
ddS
テクスチャを格納するDirectDrawSurface4オブジェクト。

戻り値

Direct3DRMTexture3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.CreateViewport

Direct3DRM3

デバイス座標が(x, y)から(x + w, y + h)までのデバイス上で、ビューポートを作成する。

構文

object.CreateViewport(dev As Direct3DRMDevice3,
  fr As Direct3DRMFrame3,
  x As Long,
  y As Long,
  w As Long,
  h As Long) As Direct3DRMViewport2

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
dev
ビューポートの作成先であるDirect3DRMDevice3オブジェクト。
fr
ビューの位置と方向を記述するDirect3DRMFrame3オブジェクト。
x, y, w, h
デバイス座標でのビューポートの位置とサイズ。ビューポートサイズは物理デバイスより大きくできない。大きくすると、メソッドは失敗に終わる。

戻り値

Direct3DRMViewport2オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

ビューポートは、カメラ (fr) を含むシーンの中で、カメラから取ったビュー方向とアップベクトルを使用してオブジェクトを表示する。ビューポートサイズは、物理デバイスよりも大きくできない。

デバイスの詳細については、「Direct3DRMDevice3」を参照すること。

Direct3DRM3.CreateWrap

Direct3DRM3

面とメッシュにテクスチャ座標を割り当てるのに使用できるラッピング関数を作成する。

構文

object.CreateWrap(t As CONST_D3DRMWRAPTYPE,
  f As Direct3DRMFrame3,
  ox As Single,
  oy As Single,
  oz As Single,
  dx As Single,
  dy As Single,
  dz As Single,
  ux As Single,
  uy As Single,
  uz As Single,
  ou As Single,
  ov As Single,
  su As Single,
  sv As Single) As Direct3DRMWrap

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
t
CONST_D3DRMWRAPTYPE列挙型のメンバの1つ。
f
ラップの参照Direct3DRMFrame3オブジェクト。
ox, oy, oz
ラップの原点。
dx, dy, dz
ラップのz軸。
ux, uy, uz
ラップのy軸。
ou, ov
テクスチャの原点。
su, sv
テクスチャのスケール係数。

戻り値

Direct3DRMWrapオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

ラップの記述については、Direct3D保持モードのC++に関するマニュアルの概要セクションを参照すること。

Direct3DRM3.EnumerateObjects

Direct3DRM3

アクティブなDirect3D保持モードのオブジェクト上に指定されるコールバックを使用する。

構文

object.EnumerateObjects(
    enumerateObjectsImplementation As Direct3DRMEnumerateObjectsCallback,
    userArgument As object)

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
enumerateObjectsImplementation
各Direct3DRMObjectオブジェクトおよびアプリケーション定義引数によって使われるアプリケーション定義のDirect3DRMEnumerateObjectsCallbackコールバックインターフェイス。
userArgument
コールバックに渡されるアプリケーション定義データ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.GetDevices

Direct3DRM3

システムで作成されたすべてのDirect3D保持モードデバイスを取得する。

構文

object.GetDevices( ) As Direct3DRMDeviceArray

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMDeviceArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRM3.GetNamedObject

Direct3DRM3

指定の名前でDirect3DRMObjectオブジェクトを検索する。

構文

object.GetNamedObject(name As String) As Direct3DRMObject

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
name
検索するオブジェクトの名前。

戻り値

Direct3DRMObjectオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

システムがnameパラメータで指定した名前のオブジェクトを発見しなかった場合に、このメソッドは、D3DRM_OKを返すが、nameパラメータは""となる。

例

Set O = rm.GetNamedObject("object")
If O is Nothing then
    Debug.Print "Object not found"
End If

Direct3DRM3.GetOptions

Direct3DRM3

Direct3D保持モードで左手または右手ジオメトリのどちらを使用するかを取得する。

構文

object.GetOptions( ) As CONST_D3DRMHANDEDNESS

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

現在のDirect3D保持モードオプションを示すCONST_D3DRMHANDEDNESS列挙型から値を返す。

エラー値

エラーが発生した場合は、DDERR_INVALIDOBJECTまたはDDERR_INVALIDPARAMSを返す。

参照

Direct3DRM3.SetOptions

Direct3DRM3.GetSearchPath

Direct3DRM3

現在の検索パスを返す。Windowsでは、パスは、セミコロン(;)で区切られたディレクトリのリストである。

構文

object.GetSearchPath( ) As String

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。

戻り値

文字列で現在の検索パスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRM3.SetSearchPath

Direct3DRM3.LoadFromFile

Direct3DRM3

オブジェクトをロードする。

構文

object.LoadFromFile(filename As String,
  id As String,
  guidArray() As String,
  count As Long,
  options As CONST_D3DRMLOADFLAGS,
  loadCallbackImplementation As Direct3DRMLoadCallback,
  loadArgument As object,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  loadTextureArgument As object,
  parentFrame As Direct3DRMFrame3)

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
filename
ファイルのフルパス。
id
ロードするオブジェクトの名前または位置。idが""の場合、optionsパラメータをD3DRMLOAD_FIRSTに設定しなければならない。Microsoft Visual Basic® は、String データ型が指定されている場合でも、ロードするアイテムの位置を示すidパラメータの中のIntegerを受け入れる。たとえば、idパラメータに1が設定されていると、1番目の位置のオブジェクトがロードされる。
guidArray
ロードするインターフェイス識別子。たとえば、このパラメータがIID_Direct3DRMMeshBuilder3およびIID_Direct3DRMAnimationSet2を格納する2つの要素の配列であれば、このメソッドは、すべてのアニメーションセットオブジェクトとメッシュビルダオブジェクトをロードする。可能なGUIDは、IID_Direct3DRMProgressiveMesh、IID_Direct3DRMMeshBuilder3、IID_Direct3DRMAnimationSet2、IID_Direct3DRMAnimation2、IID_Direct3DRMFrame3の中の1つ以上でなければならない。「注意」を参照すること。
count
guidArrayパラメータで指定されている要素の数。
options
ロードオプションを記述するCONST_D3DRMLOADFLAGS列挙型の1つ以上の値。
loadCallbackImplementation
システムが指定のオブジェクトを読み込んだときに使われるDirect3DRMLoadCallbackコールバックインターフェイス。
loadArgument
Direct3DRMLoadCallbackコールバックインターフェイスに渡されるアプリケーション定義データ。
loadTextureImplementation
Direct3DRMLoadTextureCallback3コールバックインターフェイス。これは、特別なフォーマットを必要とするオブジェクトが用いるテクスチャを読み出すときに呼び出される。テクスチャは2で割れる幅と長さでなければならない。このパラメータにはNOTHINGを指定することができる。
loadTextureArgument
Direct3DRMLoadTextureCallback3コールバックインターフェイスに渡されるアプリケーション定義データ。
parentFrame
親Direct3DRMFrame3オブジェクト。この引数は、アニメーションセットのロードだけに影響する。Xファイルからロードされたアニメーションが、Xファイル中の親のないフレームを参照するときは、その親には、fがセットされる。ただし、Xファイル中の任意のフレームをロードするように、LoadFromFileがセットされる。ただし、Xファイル中の任意のフレームをロードするように、parentFrameは、親のないXファイル中のフレームに対する親フレームとして使用されることはない。つまり、parentFrameは、アニメーションセットをロードしたときに限り使用される。fパラメータはNOTHINGにすることができる。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デフォルトでは、パースペクティブ補正がオンである。

各LoadFromFileメソッドは、filenameパラメータを使用してオブジェクトのソースを指定し、idパラメータによってオブジェクトを識別する。システムはソースフラグの選択に基づいてfilenameパラメータを解釈する。そして、識別子フラグの選択に基づいてidパラメータの内容を解釈する。

インスタンスフラグは、パラメータの解釈方法には何も変更を加えない。D3DRMLOAD_INSTANCEBYREFERENCEフラグを用いると、新しいオブジェクトを作成することなく同じファイルを2回ロードすることができる。オブジェクトが名前を持っていない場合、D3DRMLOAD_INSTANCEBYREFERENCEフラグをセットすると、D3DRMLOAD_INSTANCEBYCOPYINGフラグをセットしたときと同じ効果を得ることができる。ローダは、同一のオブジェクトが存在しても、各名前なしオブジェクトを新しいオブジェクトとして作成する。

注意

count値が3の場合、guidArrayは次のようになる。

Dim guidArray(3) As String

guidArray(0)="IID_Direct3DRMMeshBuilder3"
guidArray(1)="IID_Direct3DRMFrame3"
guidArray(2)="IID_Direct3DRMAnimationSet2"

Direct3DRM3.LoadTexture

Direct3DRM3

指定ファイルからDirect3DRMTexture3テクスチャをロードする。このテクスチャは、8、24、または32ビット/ピクセルをとることができる。そのフォーマットは、Windows ビットマップ(.bmp)かPortable Pixmap (.ppm) P6フォーマットのどちらかにする必要がある。

構文

object.LoadTexture(name As String) As Direct3DRMTexture3

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
name
必要な.bmpまたは.ppmファイルの名前

戻り値

Direct3DRMTexture3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

LoadTextureは、テクスチャがBMPフォーマットであるかPPMフォーマットであるかをチェックする。LoadTextureは、両フォーマットをロードすることができる。

Direct3DRM3.SetDefaultTextureColors

Direct3DRM3

Direct3DRMTexture3オブジェクトで使用するデフォルトの色を設定する。

構文

object.SetDefaultTextureColors(numTextureColors As Long)

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
numTextureColors
色数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRM3.CreateTextureFromSurfaceメソッドの前に使われたときに限りテクスチャの色に影響する。既に作成されているテクスチャには、何の効果もない。

Direct3DRM3.SetDefaultTextureShades

Direct3DRM3

Direct3DRMTexture3オブジェクトに対して使用するデフォルトのシェードを設定する。

構文

object.SetDefaultTextureShades(numTextureShades As Long)

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
numTextureShades
シェード数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRM3.CreateTextureFromSurfaceメソッドの前に使われたときに限りテクスチャのシェードに影響する。既に作成されているテクスチャには、何の効果もない。

Direct3DRM3.SetOptions

Direct3DRM3

Direct3D保持モードで左手または右手ジオメトリのどちらを使用するかを設定する。

構文

object.SetOptions(options As CONST_D3DRMHANDEDNESS)

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
options
現在のDirect3D保持モードオプションを示すCONST_D3DRMHANDEDNESSからの値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRM3.GetOptions

Direct3DRM3.SetSearchPath

Direct3DRM3

ディレクトリのリストから現在のファイル検索パスを設定する。Windowsでは、パスは、セミコロン(;)で区切られたリストにする必要がある。

構文

object.SetSearchPath(name As String)

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
name
現在の検索パスとして設定するパスの文字列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRM3.GetSearchPath

Direct3DRM3.Tick

Direct3DRM3

システムのハートビートを行う。このメソッドが使われると、すべての可動フレームの位置は、現在の運動属性にしたがって更新され、シーンが現在のデバイスにレンダリングされる。また、関連したコールバックが、適切なタイミングで呼び出される。このメソッドは、レンダリングサイクルが完了したときに制御を返す。

構文

object.Tick(tic As Single)

要素

object
Direct3DRM3オブジェクトを表すオブジェクト式。
tic
任意の単位を表す値。たとえば、速度を1,0,0に設定し (「Direct3DRMFrame3.SetVelocity」を参照)、ティック値 (tic) を1に設定すると、アニメーションはx方向に1単位移動する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

シーンのレンダリングに柔軟性を持たせるため、保持モードの他のメソッドを使用して、このメソッドを実装することもできる。

  • Direct3DRMFrame3.SetRotation
  • Direct3DRMFrame3.SetVelocity
  • Direct3DRMFrame3.Move


Direct3DRMAnimation2

アプリケーションはDirect3DRMAnimation2インターフェイスのメソッドを利用して、位置、向き、ビジュアルオブジェクトのスケーリング、照明、ビューポートのアニメーションを行うことができる。

保持モードのアニメーションは、キーセットによって定義される。キーはスケーリング操作、方向、または位置に関連付けられた時間値である。Direct3DRMAnimationオブジェクトは、時間値に応じた変換の修正方法を定義する。アニメーションをDirect3DRMFrameオブジェクト上で動作するようにセットし、Direct3DRMVisual、Direct3DRMLightおよびDirect3DRMViewportオブジェクトの位置、方向、スケーリングのアニメーションを行うために使用することができる。

Direct3DRMAnimation2.AddPositionKey、AddRotateKeyおよびAddScaleKeyの各メソッドは、単位が任意の時間値を指定する。アプリケーションが時間値99の位置キーを追加した場合、たとえば、時間値49の新しい位置キーは、アニメーションの (ゼロを基準とした) 開始点と最初の位置キーとの間のちょうど中間で発生する。

アニメーションの操作は、Direct3DRMAnimation2.SetTimeメソッドを呼び出すことで行われる。これは、ビジュアルオブジェクトの変換をアニメーション中の近くのキーの補間位置、方向、スケールにセットする。アニメーションキーを追加するメソッドと同様に、SetTimeの時間値は、アプリケーションが既に追加済みのキー位置に基づく任意の値である。

IDirect3DRMAnimation2インターフェイスのメソッドは、以下のグループにまとめることができる。

キー | AddKey
 | AddPositionKey
 | AddRotateKey
 | AddScaleKey
 | DeleteKey
 | DeleteKeyByID
 | GetKeys
 | GetKeysCount
 | ModifyKey
その他 | GetFrame
 | SetFrame
 | SetTime
オプション | GetOptions
 | SetOptions

Direct3DRMAnimation2インターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMAnimationオブジェクトは、Direct3DRM3.CreateAnimationメソッドの呼び出しによって取得できる。

Direct3DRMAnimation2.AddKey

Direct3DRMAnimation2

新しいキーを追加する。

構文

object.AddKey(key As D3DRMANIMATIONKEY)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
key
新しいキーを定義するD3DRMANIMATIONKEYのタイプ。タイプのidメンバは無視され、返る時点で新しいキーのIDがセットされる。

エラー値

エラーが発生した場合は、DDERR_INVALIDOBJECTまたはDDERR_INVALIDPARAMSを返す。

Direct3DRMAnimation2.AddPositionKey

Direct3DRMAnimation2

アニメーションに位置キーを追加する。

構文

object.AddPositionKey(time As Single,
  x As Single,
  y As Single,
  z As Single)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
time
アニメーションの中で位置キーを設定するときの時間。0を原点とする任意の単位の時間を指定することができる。最後のキーのtimeの値が99のとき、timeが49であるキーがアニメーションのちょうど中間である。
x, y, z
アニメーションに追加する位置キーの座標。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドによって適用される変換は平行移動である。点 (x, y, z) は新しい点 (x', y', z') に平行移動する。

点を平行移動する行列.

参照

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.AddRotateKey

Direct3DRMAnimation2

アニメーションに回転キーを追加する。

構文

object.AddRotateKey(time As Single,
  q As D3DRMQUATERNION)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
time
アニメーションの中で回転キーを設定するときの時間。0を基準とする任意の単位の時間を指定することができる。最後のキーのtimeの値が99のとき、timeが49であるキーがアニメーションのちょうど中間である。
q
回転を表すD3DRMQUATERNIONのタイプ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドによって、回転変換が適用される。

参照

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.AddScaleKey

Direct3DRMAnimation2

アニメーションにスケールキーを追加する。

構文

object.AddScaleKey(time As Single,
  x As Single,
  y As Single,
  z As Single)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
time
アニメーションの中でスケールキーを記憶するときの時間。0を原点とする任意の単位の時間を指定できる。最後のキーのtimeの値が99のとき、timeが49であるキーがアニメーションのちょうど中間である。
x, y, z
アニメーションに追加するスケールキーの座標。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドによって、スケール変換が適用される。

参照

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2

キーをアニメーションから削除する。たとえば、アニメーションに時間tのスケールキーと時間tの回転キーがある場合、両方のキーが削除される。

構文

object.DeleteKey(time As Single)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
time
アニメーションから削除されるキーを識別する時間。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMAnimation2.DeleteKeyByID

Direct3DRMAnimation2

固有のIDに対応するキーを削除する。

構文

object.DeleteKeyByID(id As Long)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
id
削除するキーのID。

エラー値

エラーが発生した場合は、次の値のうちの1つを返す。

  • D3DRMERR_NOSUCHKEY
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

Direct3DRMAnimation2.GetFrame

Direct3DRMAnimation2

アニメーションに対応するフレームを取り出す。

構文

object.GetFrame( ) As Direct3DRMFrame3

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。

戻り値

アニメーションが参照する現在のDirect3DRMFrameオブジェクトのインターフェイスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMAnimation2.GetKeys

Direct3DRMAnimation2

固有の時間に対応するキーを取り出す。

構文

object.GetKeys(timeMin As Single,
  timeMax As Single,
  keyArray() As D3DRMANIMATIONKEY)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
timeMin
返されるキーの最小時間値。
timeMax
返されるキーの最大時間値。
keyArray
キー値がセットされるD3DRMANIMATIONKEYのタイプの配列。

エラー値

エラーが発生した場合は、次の値のうちの1つを返す。

  • D3DRMERR_NOSUCHKEY
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS
  • DD_OK

Direct3DRMAnimation2.GetKeysCount

Direct3DRMAnimation2

2つの固有の時間の間にあるキーを取得する。

構文

object.GetKeysCount(timeMin As Single,
  timeMax As Single) As Long

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
timeMin
返されるキーの最小時間値。
timeMax
返されるキーの最大時間値。

戻り値

timeMinとtimeMaxの間にあるキーの数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMAnimation2.GetOptions

Direct3DRMAnimation2

アニメーションオプションを取得する。

構文

object.GetOptions( ) As CONST_D3DRMANIMATIONFLAGS

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。

戻り値

アニメーションオプションを示すCONST_D3DRMANIMATIONFLAGS列挙の値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMAnimation2.SetOptions

Direct3DRMAnimation2.ModifyKey

Direct3DRMAnimation2

キー値を修正する。

構文

object.ModifyKey(key As D3DRMANIMATIONKEY)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
key
既存のキーの値を定義するD3DRMANIMATIONKEYのタイプ。構造体のIDメンバは、既存のキーでなければならない。

エラー値

エラーが発生した場合は、次の値のうちの1つを返す。

  • D3DRMERR_INCOMPATIBLEKEY
  • D3DRMERR_NOSUCHKEY
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

注意

キーのタイプを修正することはできない。キーのタイプを変更するには、オリジナルキーを削除し、新しいキーを追加しなければならない。キーの時間、位置、回転、およびスケール値を修正することはできる。

Direct3DRMAnimation2.SetFrame

Direct3DRMAnimation2

アニメーションにフレームを設定する。

構文

object.SetFrame(frame As Direct3DRMFrame3)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
frame
アニメーションに設定するDirect3DRMFrame3オブジェクトを指定する変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMAnimation2.SetOptions

Direct3DRMAnimation2

アニメーションオプションを設定する。

構文

object.SetOptions(flags As CONST_D3DRMANIMATIONFLAGS)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
flags
アニメーションオプションを指定するCONST_D3DRMANIMATIONFLAGS列挙の1つまたは複数の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMAnimation2.GetOptions

Direct3DRMAnimation2.SetTime

Direct3DRMAnimation2

アニメーションに現在の時間を設定する。

構文

object.SetTime(time As Single)

要素

object
Direct3DRMAnimation2オブジェクトを表すオブジェクト式。
time
アニメーションに設定する新しい現在の時間。0を原点とする任意の単位の時間を指定することができる。最後のキーのtimeの値が99のとき、timeが49であるキーがアニメーションのちょうど中間である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMAnimationArray

Direct3DRMAnimationArrayインターフェイスは、配列中のアニメーションの数を取り出し、インターフェイスにアニメーションの実行を要求できるようにする。アニメーションの配列は0が基準になっている(0～N-1)。

このインターフェイスは、GetElementおよびGetSizeメソッドをサポートする。

Direct3DRMAnimationArray.GetElement

Direct3DRMAnimationArray

要求されたアニメーションに対するインターフェイスを取得する。

構文

object.GetElement( ) As Direct3DRMAnimation2

要素

object
Direct3DRMAnimationArrayオブジェクトを表すオブジェクト式。

戻り値

Direct3DRMAnimation2オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMAnimationArray.GetSize

Direct3DRMAnimationArray

配列中のアニメーションの数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMAnimationArrayオブジェクトを表すオブジェクト式。

戻り値

アニメーションの数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMAnimationSet2

Direct3DRMAnimationSet2オブジェクトによって、Direct3DRMAnimation2オブジェクトをグループにまとめることができる。これで、アニメーションセット中のすべてのアニメーションが同じ時間パラメータを共有し、複雑に分割されたアニメーションの流れを簡単に再生できるようになる。アプリケーションは、Direct3DRMAnimationSet2.AddAnimationメソッドを使用してアニメーションをアニメーションセットに追加し、Direct3DRMAnimationSet2.DeleteAnimationメソッドを使用してそれを削除できる。アニメーションセットは、Direct3DRMAnimationSet2.SetTimeメソッドを呼び出すことで操作する。

Direct3DRMAnimationSet2インターフェイスのメソッドは、以下のグループにまとめることができる。

追加、削除、取得、ロード | AddAnimation
DeleteAnimation
GetAnimations
LoadFromFile
時間 | SetTime

Direct3DRMAnimationSet2インターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMAnimationSet2オブジェクトは、Direct3DRM3.CreateAnimationSetメソッドの呼び出しによって取得できる。

Direct3DRMAnimationSet2.AddAnimation

Direct3DRMAnimationSet2

アニメーションをアニメーションセットに追加する。

構文

object.AddAnimation(aid As Direct3DRMAnimation2)

要素

object
Direct3DRMAnimationSet2オブジェクトを表すオブジェクト式。
aid
アニメーションセットに追加するDirect3DRMAnimation2オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMAnimationSet2.DeleteAnimation

Direct3DRMAnimationSet2

アニメーションをアニメーションセットから削除する。

構文

object.DeleteAnimation(aid As Direct3DRMAnimation2)

要素

object
Direct3DRMAnimationSet2オブジェクトを表すオブジェクト式。
aid
アニメーションセットから削除されるDirect3DRMAnimation2オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMAnimationSet2.GetAnimations

Direct3DRMAnimationSet2

アニメーションセット中のアニメーションを含む配列を取り出す。

構文

object.GetAnimations( ) As Direct3DRMAnimationArray

要素

object
Direct3DRMAnimationSet2オブジェクトを表すオブジェクト式。

戻り値

アニメーションセット中のアニメーションにアクセスできるようにするDirect3DRMAnimationArrayインターフェイスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMAnimationSet2.LoadFromFile

Direct3DRMAnimationSet2

アニメーションセットをロードする。

構文

object.LoadFromFile(filename As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As object,
  parentFrame As Direct3DRMFrame3)

要素

object
Direct3DRMAnimationSet2オブジェクトを表すオブジェクト式。
filename
オブジェクトがロードされるソースへのポインタ。flagsパラメータが示すソースフラグによって、ファイル、リソース、メモリブロック、またはストリームを指定する。
id
ロードするオブジェクトの名前または位置へのポインタ。idが""の場合は、D3DRMLOAD_FIRSTにoptionsパラメータを設定する必要がある。Microsoft Visual Basic®は、Stringデータ型が指定されていても、ロードされる項目の位置を示すidパラメータの中のIntegerを解釈する。たとえば、idパラメータで1を指定すると、オブジェクトは1番目の位置にロードされる。
options
ロードオプションを示すCONST_D3DRMLOADFLAGS列挙型からの1つまたは複数の値。
loadTextureImplementation
Direct3DRMLoadTextureCallback3インターフェイス。これは、特別なフォーマットを必要とするオブジェクトが用いるテクスチャを読み出すときに使われる。テクスチャは、2で割れる幅と長さでなければならない。このパラメータにはNOTHINGを指定することができる。
userArgument
Direct3DRMLoadTextureCallback3インターフェイスに渡されるアプリケーション定義のデータ。
parentFrame
親Direct3DRMFrameオブジェクト。この引数は、アニメーションセットのロードだけに影響する。xファイルからロードされたアニメーションが、xファイル中の親のないフレームを参照するときは、その親には、parentFrameがセットされる。ただし、xファイル中の任意のフレームをロードするように、LoadFromFileを使った場合には、parentFrameは、親のないxファイル中のフレームに対する親フレームとして使用されることはない。つまり、lpParentFrameは、アニメーションセットをロードしたときに限り使用される。parentFrameの値はNOTHINGにすることができる。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デフォルトでは、このメソッドはfilenameパラメータで指定されるファイルの最初のアニメーションセットをロードする。デフォルトでは、パースペクティブ補正がオンである。

Direct3DRMAnimationSet2.SetTime

Direct3DRMAnimationSet2

アニメーションの現在の時間を設定する。

構文

object.SetTime(time As Single)

要素

object
Direct3DRMAnimationSet2オブジェクトを表すオブジェクト式。
time
新しい時間。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMClippedVisual

Direct3DRMClippedVisualインターフェイスによって、アプリケーションは、レンダリングの前にワールド空間で指定された任意のプレーンに対してビジュアルオブジェクトをクリップすることができる。別のビジュアルから影を作成するのとほとんど同じように、別のビジュアルからクリップビジュアルを作成する。たとえば、球体からクリップビジュアルを作成し、球体の真中から直線的にクリッピングプレーンを渡し、球体の半分だけをレンダリングさせることができる。Direct3DRM3.CreateClippedVisualメソッドを呼び出すことで、クリップビジュアルオブジェクトを作成する。次に、Direct3DRMFrame3.AddVisualメソッドを使用して、クリップビジュアルをシーンに追加する。

Direct3DRMClippedVisualは、その他のビジュアルインターフェイスと同様にDirect3DRMVisualを継承する。参照フレームが移動するとき、クリッピングプレーンは移動しない (詳細については、「AddPlaneメソッド」を参照すること)。

Direct3DRMClippedVisualインターフェイスは、以下のメソッドをサポートする。

  • AddPlane
  • DeletePlane
  • GetPlane
  • GetPlaneIds
  • GetPlaneIdsCount
  • SetPlane

Direct3DRMClippedVisualインターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRM3インターフェイスを使用して、Direct3DRMClippedVisualオブジェクトを作成することができる。

Direct3DRMClippedVisual.AddPlane

Direct3DRMClippedVisual

クリッピングプレーンを追加する。

構文

object.AddPlane(ref As Direct3DRMFrame3,
  point As D3DVECTOR,
  normal As D3DVECTOR) As Long

要素

object
Direct3DRMClippedVisualオブジェクトを表すオブジェクト式。
ref
ポイントと法線パラメータの参照フレーム。
point
参照フレームを起点とするプレーン上のポイント。
normal
参照フレームを起点とするプレーンに垂直なベクトル。

戻り値

呼び出しが成功した場合に、プレーンの一意なID番号を返す。

エラー値

エラーが発生した場合は、DDERR_INVALIDPARAMSを返す。

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

クリッピングプレーンは、ワールド座標として内部的に格納される。参照フレームが移動するとき、クリッピングプレーンは移動しない。必要に応じてクリッピングプレーンの位置と方向を更新するには、SetPlaneメソッドを使用する。

参照

D3DVECTOR

Direct3DRMClippedVisual.DeletePlane

Direct3DRMClippedVisual

クリッピングプレーンを削除する。

構文

object.DeletePlane(id As Long)

要素

object
Direct3DRMClippedVisualオブジェクトを表すオブジェクト式。
id
削除するプレーンのID番号。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMClippedVisual.GetPlane

Direct3DRMClippedVisual

クリッピングプレーンに関する情報を取り出す。

構文

object.GetPlane(id As Long,
  ref As Direct3DRMFrame3,
  point As D3DVECTOR,
  normal As D3DVECTOR)

要素

object
Direct3DRMClippedVisualオブジェクトを表すオブジェクト式。
id
プレーンのID。
ref
この操作の参照Direct3DRMFrame3オブジェクト。
point
呼び出し成功時の参照フレームを起点とするプレーン上のポイント。
normal
呼び出し成功時の参照フレームを起点とするプレーンに垂直なベクトル。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

D3DVECTOR

Direct3DRMClippedVisual.GetPlaneIds

Direct3DRMClippedVisual

IDの配列を取り出す。

構文

object.GetPlaneIds(count As Long,
  arrayOfIds() As Long)

要素

object
Direct3DRMClippedVisualオブジェクトを表すオブジェクト式。
count
arrayOfIds配列のバイト単位のサイズ。
arrayOfIds
すべてのプレーンID番号の配列。呼び出しが成功した場合、プレーンIDが入っている。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMClippedVisual.GetPlaneIdsCount

Direct3DRMClippedVisual

プレーンの数を取り出す。

構文

object.GetPlaneIdsCount( ) As Long

要素

object
Direct3DRMClippedVisualオブジェクトを表すオブジェクト式。

戻り値

プレーンの数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMClippedVisual.SetPlane

Direct3DRMClippedVisual

既に追加されたクリッピングプレーンのパラメータを変更する。

構文

object.SetPlane(id As Long,
  ref As Direct3DRMFrame3,
  point As D3DVECTOR,
  normal As D3DVECTOR)

要素

object
Direct3DRMClippedVisualオブジェクトを表すオブジェクト式。
id
変更するプレーンのID番号。
ref
ポイントと法線パラメータの参照Direct3DRMFrame3オブジェクト。このパラメータがNOTHINGならば、pointとnormalはワールド空間中にある。
point
参照フレームを起点とするプレーン上のポイント。
normal
参照フレームを起点とするプレーンに垂直なベクトル。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

D3DVECTOR


Direct3DRMDevice3

Direct3DRMDevice3インターフェイスをDirect3DRM3インターフェイスから作成する場合、Direct3DDevice3インターフェイスは直接モードデバイスと共に機能する。Direct3DDevice3デバイスは、バッファを実行し、プログレッシブメッシュ、アルファブレンディング、透明オブジェクトに必要となる。

Direct3DRMDevice3インターフェイスのメソッドは、以下のグループにまとめることができる。

バッファカウント | GetBufferCount
SetBufferCount
カラーモデル | GetColorModel
ディザリング | GetDither
SetDither
その他 | GetDirect3DDevice3
GetHeight
GetTrianglesDrawn
GetViewports
GetWidth
GetWireframeOptions
Update
通知 | AddUpdateCallback
DeleteUpdateCallback
レンダリングクオリティ | GetQuality
SetQuality
シェーディング | GetShades
SetShades
テクスチャ | FindPreferredTextureFormat
GetTextureQuality
SetTextureQuality
透過性 | GetRenderMode
SetRenderMode

Direct3DRMDevice3インターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMDevice3オブジェクトは、Direct3DRM3.CreateDeviceFromClipper、Direct3DRM3.CreateDeviceFromD3DまたはDirect3DRM3.CreateDeviceFromSurfaceメソッドを呼び出すことによって取得される。

Direct3DRMDevice3.AddUpdateCallback

Direct3DRMDevice3

デバイスに変化が発生したとき、アプリケーションに警告を与えるコールバックを追加する。システムは、アプリケーションがDirect3DRMDevice3.Updateメソッドを使ったときに、このコールバックを呼び出す。

構文

object.AddUpdateCallback(
    updateCallbackImplementation As Direct3DRMDeviceUpdateCallback3,
    userArgument As object)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
updateCallbackImplementation
アプリケーション定義のコールバックインターフェイス Direct3DRMDeviceUpdateCallback3。
userArgument
更新コールバックに渡すプライベートデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.DeleteUpdateCallback

Direct3DRMDevice3.DeleteUpdateCallback

Direct3DRMDevice3

Direct3DRMDevice3.AddUpdateCallbackメソッドを使って追加された更新コールバックを削除する。

構文

object.DeleteUpdateCallback(
    updateCallbackImplementation As Direct3DRMDeviceUpdateCallback3,
    userArgument As Object)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
updateCallbackImplementation
アプリケーション定義のコールバック Direct3DRMDeviceUpdateCallback3。
userArgument
更新コールバックに渡されるプライベートデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.Update

Direct3DRMDevice3.FindPreferredTextureFormat

Direct3DRMDevice3

ユーザの基準を満たし、下層の直接モードデバイスがサポートするテクスチャフォーマットを検索する。テクスチャキャッシュの最適なパフォーマンスを得るためには、このメソッドを使用してテクスチャサーフェスのピクセルフォーマットを選択する。

構文

object.FindPreferredTextureFormat(bitDepth As CONST_DDBITDEPTHFLAGS,
  flags As CONST_D3DRMFPTFFLAGS,
  ddpf As DDPIXELFORMAT)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
CONST_DDBITDEPTHFLAGS
要求されたテクスチャフォーマットビット深度。ビット深度が一切受容できないことを示すには、ゼロを指定する。次のMicrosoft® DirectDraw® ビット深度フラグの1つ以上の論理的な組み合わせを使用して、その他の値を指定する。
  • DDBD_4
  • DDBD_8
  • DDBD_16
  • DDBD_24
  • DDBD_32
flags
CONST_D3DRMFPTFFLAGS列挙型からの1つ以上の値。
ddpf
テクスチャフォーマットを受け取る変数。

エラー値

エラーが発生した場合は、次の値のうちの1つを返す。

  • D3DRMERR_TEXTUREFORMATNOTFOUND
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

このメソッドは、受入可能なフォーマットを検索できない場合、D3DRMERR_TEXTUREFORMATNOTFOUNDを返す。

Direct3DRMDevice3.GetBufferCount

Direct3DRMDevice3

Direct3DRMDevice3.SetBufferCountメソッドに対する呼び出しでセットされた値を取得する。

構文

object.GetBufferCount( ) As Long

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

バッファの数であり、シングルバッファリングに対しては1、ダブルバッファリングに対しては2、などを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMDevice3.GetColorModel

Direct3DRMDevice3

デバイスのカラーモデルを取得する。

構文

object.GetColorModel( ) As CONST_D3DCOLORMODEL

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

Direct3Dカラーモデル(RGBまたはモノクロ)を記述するCONST_D3DCOLORMODEL列挙型から値を返す。CONST_D3DCOLORMODEL列挙型とその設定については、追加情報の「CONST_D3DCOLORMODEL」を参照すること。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMDevice3.GetDirect3DDevice3

Direct3DRMDevice3

Direct3DDevice3直接モードデバイスを取得する。

構文

object.GetDirect3DDevice3( ) As Direct3DDevice3

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

Direct3DDevice3直接モードデバイスオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

Direct3DDevice3デバイスは、Microsoft DirectX® DrawPrimitiveインターフェイスと共にバッファの実行もサポートし、プログレッシブメッシュ、アルファブレンディング、および透明オブジェクトのソートに必要となる。

Direct3DRMDevice3.GetDither

Direct3DRMDevice3

デバイスのディザリングフラグを取得する。

構文

object.GetDither( ) As CONST_DBOOLFLAGS

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

ディザリングフラグがセットされていれば1、そうでなければ0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.SetDither

Direct3DRMDevice3.GetHeight

Direct3DRMDevice3

デバイスの高さを取得する。このメソッドは、便利な関数である。

構文

object.GetHeight( ) As Long

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

高さをピクセル単位で返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMDevice3.GetQuality

Direct3DRMDevice3

デバイスのレンダリングクオリティを取得する。

構文

object.GetQuality( ) As CONST_D3DRMRENDERQUALITY

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMRENDERQUALITY列挙型から1つ以上の値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

レンダリングクオリティは、デバイスのレンダリング面上で実行されるレンダリングのクオリティの最大値である。

オブジェクトクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーロー)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

このメソッドがクオリティのqを返した後は、照明がオンかどうか((q And D3DRMLIGHT_MASK) = D3DRMLIGHT_ON)、シェーディングの使用((q And D3DRMSHADE_MASK)= D3DRMSHADE_PHONG)、および塗りつぶしの使用((q And D3DRMFILL_MASK)=D3DRMFILL_SOLID)を判別するために照会することができる。

参照

Direct3DRMDevice3.SetQuality

Direct3DRMDevice3.GetRenderMode

Direct3DRMDevice3

現在の透過性フラグを取得する。

構文

object.GetRenderMode( ) As CONST_D3DRMRENDERMODEFLAGS

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMRENDERMODEFLAGS列挙型から値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.SetRenderMode

Direct3DRMDevice3.GetShades

Direct3DRMDevice3

モノクロ (ランプ) モデルシェーディングに使用される色のランプでのシェード数を取得する。

構文

object.GetShades( ) As Long

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

シェード数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.SetShades

Direct3DRMDevice3.GetTextureQuality

Direct3DRMDevice3

デバイスの現在のテクスチャクオリティパラメータを取得する。テクスチャクオリティは、RGBデバイスだけに関係する。

構文

object.GetTextureQuality( ) As CONST_D3DRMTEXTUREQUALITY

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMTEXTUREQUALITY列挙型のメンバの1つを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.SetTextureQuality

Direct3DRMDevice3.GetTrianglesDrawn

Direct3DRMDevice3

デバイスが作成されて以降、そのデバイスに描画された三角形の数を取得する。このメソッドは、便利な関数である。

構文

object.GetTrianglesDrawn( ) As Long

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

三角形の数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

三角形の数は、レンダラに渡されたが、裏（カメラの向きと逆の面）に隠されたために描画されなかったものを含む。視錐台の外側にあって拒絶された三角形は含まれない。

Direct3DRMDevice3.GetViewports

Direct3DRMDevice3

デバイスから現在構築されているビューポートを表すDirect3DRMViewportArrayオブジェクトを構築する。

構文

object.GetViewports( ) As Direct3DRMViewportArray

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

呼び出しが成功した場合は、Direct3DRMViewportArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMDevice3.GetWidth

Direct3DRMDevice3

デバイスの幅を取得する。このメソッドは、便利な関数である。

構文

object.GetWidth( ) As Long

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

デバイスの幅をピクセル単位で返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMDevice3.GetWireframeOptions

Direct3DRMDevice3

指定のデバイスのワイヤフレームオプションを取得する。

構文

object.GetWireframeOptions( ) As CONST_D3DRMWIREFRAMEFLAGS

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMWIREFRAMEFLAGS列挙型から値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMDevice3.SetBufferCount

Direct3DRMDevice3

現在アプリケーションで使用されているバッファの数を設定する。

構文

object.SetBufferCount(count As Long)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
count
バッファの数を、シングルバッファリングに対しては1、ダブルバッファリングに対しては2などと指定する。デフォルト値は1であり、シングルバッファリングウィンドウ操作に対してのみ有効である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アプリケーションが、ダブルバッファリングやトリプルバッファリングを行うときは、このメソッドで、使用するバッファ数をシステムに通知し、システムが各フレームに対して、ウィンドウのどの部分をクリアおよび更新するかを計算できるようにしなければならない。

参照

Direct3DRMDevice3.GetBufferCount

Direct3DRMDevice3.SetDither

Direct3DRMDevice3

デバイスのディザリングフラグを設定する。

構文

object.SetDither(ditherEnabled As CONST_DBOOLFLAGS)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
ditherEnabled
デバイスの新しいディザリングモード。ディザリングを有効にするには D_TRUE、そうでなければ D_FALSE を指定する。デフォルトは D_TRUE である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.GetDither

Direct3DRMDevice3.SetQuality

Direct3DRMDevice3

デバイスのレンダリングクオリティを設定する。

構文

object.SetQuality(q As CONST_D3DRMRENDERQUALITY)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
q
CONST_D3DRMRENDERQUALITY列挙型からの1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

レンダリングクオリティは、デバイスのレンダリング面上で実行されるレンダリングのクオリティの最大値である。

オブジェクトクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーローで、フォンは実装されていない。デフォルトはグーローシェーディング)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

シェードモード、照明タイプ、および塗りつぶしモードは、CONST_D3DRMRENDERQUALITY列挙のメンバと共に指定される。

Direct3DRMProgressiveMeshまたはDirect3DRMMeshBuilder3オブジェクトのクオリティは、それぞれSetQualityメソッドを用いて設定できる。デフォルトでは、これらのオブジェクトのクオリティはD3DRMRENDER_GOURAUDである。D3DRMRENDER_GOURAUDは、D3DRMLIGHT_ON、D3DRMFILL_SOLIDまたはD3DRMSHADE_GOURAUDと同じである。

ヒント グーローシェーディングは、詳細レベルを頻繁にまたはすばやく変更するプログレッシブメッシュオブジェクトについて、よりよいパフォーマンスを得られる。

Direct3D保持モードは、デバイスやオブジェクトの個々のコンポーネントに対する現在の設定の中で、最も低位のクオリティで、オブジェクトにレンダリングを行う。たとえば、オブジェクトの現在のクオリティ設定がD3DRMRENDER_GOURAUDで、デバイスがD3DRMRENDER_FLATであると、オブジェクトはフラットシェーディング、ソリッド塗りつぶしおよび照明オンでレンダリングされる。

これらのルールは、Direct3DRMMeshBuilder3オブジェクトおよびDirect3DRMProgressiveMeshオブジェクトに適用される。しかし、Direct3DRMMeshオブジェクトはこれらのルールに従わない。メッシュオブジェクトはデバイスのクオリティ設定を無視し、グループクオリティ設定を用いる（デフォルトでD3DRMRENDER_GOURAUD)。

参照

Direct3DRMDevice3.GetQuality

Direct3DRMDevice3.SetRenderMode

Direct3DRMDevice3

透明モードを設定する。モードタイプは、オブジェクトをどの程度透明にレンダリングするかを決定する。

構文

object.SetRenderMode(flags As CONST_D3DRMRENDERMODEFLAGS)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
flags
透明モードを示すCONST_D3DRMRENDERMODEFLAGS列挙型からの1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.GetRenderMode

Direct3DRMDevice3.SetShades

Direct3DRMDevice3

モノクロ (ランプ) モデルシェーディングに使用される色のランプでのシェード数を設定する。

構文

object.SetShades(numShades As Long)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
numShades
新しいシェード数。このパラメータは、2の累乗でなければならない。デフォルトは、32である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.GetShades

Direct3DRMDevice3.SetTextureQuality

Direct3DRMDevice3

デバイスに対するテクスチャクオリティを設定する。

構文

object.SetTextureQuality(d As CONST_D3DRMTEXTUREQUALITY)

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。
d
CONST_D3DRMTEXTUREQUALITY列挙型のメンバの1つ。デフォルトは、D3DRMTEXTURE_NEARESTである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMDevice3.GetTextureQuality

Direct3DRMDevice3.Update

Direct3DRMDevice3

レンダリングされているイメージをディスプレイにコピーする。また、デバイスドライバにハートビート関数を与え、イメージをいつ更新するかを知らせる。

構文

object.Update( )

要素

object
Direct3DRMDevice3オブジェクトを表すオブジェクト式。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドに対する各呼び出しは、システムにアプリケーション定義コールバックインターフェイスのD3DRMDeviceUpdateCallback3を呼び出させる。コールバックを追加するには、Direct3DRMDevice3.AddUpdateCallbackメソッドを使用する。


Direct3DRMDeviceArray

アプリケーションは、Direct3DRMDeviceArrayインターフェイスのメソッドを使用してデバイスオブジェクトを整理する。この項は、このインターフェイスの次のメソッドのリファレンスである。

デバイスの配列は、0が基準になっている (0～N-1)。

  • GetElement
  • GetSize

Direct3DRMDeviceArrayオブジェクトは、 Direct3DRM3.GetDevicesメソッドの呼び出しによって取得される。

Direct3DRMDeviceArray.GetElement

Direct3DRMDeviceArray

Direct3DRMDeviceArrayオブジェクトから指定された要素を取得する。

構文

object.GetElement(index As Long) As Direct3DRMDevice3

要素

object
Direct3DRMDeviceArrayオブジェクトを表すオブジェクト式。
index
配列要素。

戻り値

Direct3DRMDeviceArrayオブジェクトのindexパラメータによって指定された要素を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMDeviceArray.GetSize

Direct3DRMDeviceArray

Direct3DRMDeviceArrayオブジェクトに含まれる要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMDeviceArrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMFace2

アプリケーションは、面と互いにやり取りするためにDirect3DRMFace2インターフェイスのメソッドを使用する。 面は、メッシュ上の1つのポリゴンである。アプリケーションは、Direct3DRMFace2.SetColor、Direct3DRMFace2.SetColorRGB、Direct3DRMFace2.SetTexture、およびDirect3DRMFace2.SetMaterialメソッドを使用して、面の色、テクスチャ、マテリアルをセットすることができる。

面は、Direct3DRMFace2.AddVertexとDirect3DRMFace2.AddVertexAndNormalIndexedメソッドを使用して頂点から構築する。アプリケーションは、Direct3DRMFace2.GetVerticesとDirect3DRMFace2.GetVertexメソッドを使用して面の頂点を読み込むことができる。

Direct3DRMFace2では、SetTextureメソッドは、その幅と高さが2の累乗でないテクスチャを指定することができる。

Direct3DRMFace2インターフェイスのメソッドは、以下のグループにまとめることができる。

色 | GetColor
SetColor
SetColorRGB
マテリアル | GetMaterial
SetMaterial
テクスチャ | GetTexture
GetTextureCoordinateIndex
GetTextureCoordinates
GetTextureTopology
SetTexture
SetTextureCoordinates
SetTextureTopology
頂点と法線 | AddVertex
AddVertexAndNormalIndexed
GetNormal
GetVertex
GetVertexCount
GetVertexIndex
GetVertices

Direct3DRMFace2インターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMFace2オブジェクトは、Direct3DRM3.CreateFaceメソッドの呼び出しによって取得される。

Direct3DRMFace2.AddVertex

Direct3DRMFace2

Direct3DRMFace2オブジェクトに頂点を追加する。

構文

object.AddVertex(x As Single,
  y As Single,
  z As Single)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
x, y, z
新しい頂点位置のx、y、z座標。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.AddVertexAndNormalIndexed

Direct3DRMFace2

頂点と法線をDirect3DRMFace2オブジェクトに追加する。このとき、メッシュビルダに含まれる頂点のインデックスと法線のインデックスを使用する。面、頂点、法線は、Direct3DRMMeshBuilder3オブジェクトの一部でなくてはならない。

構文

object.AddVertexAndNormalIndexed(vertexIndex As Long,
  normalIndex As Long)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
vertexIndex, normal
追加する頂点と法線のインデックス。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.GetColor

Direct3DRMFace2

Direct3DRMFace2オブジェクトの色を取得する。

構文

object.GetColor( ) As Long

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。

戻り値

色を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFace2.SetColor

Direct3DRMFace2.GetMaterial

Direct3DRMFace2

Direct3DRMFace2オブジェクトのマテリアルを取得する。

構文

object.GetMaterial( ) As Direct3DRMMaterial2

要素

object
Object expression that resolves to a Direct3DRMFace2 object.

戻り値

面に適用されているDirect3DRMMaterialオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFace2.SetMaterial

Direct3DRMFace2.GetNormal

Direct3DRMFace2

Direct3DRMFace2オブジェクトの法線ベクトルを取得する。

構文

object.GetNormal(val As D3DVECTOR)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
val
面の法線ベクトルを受け取るD3DVECTORタイプ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.GetTexture

Direct3DRMFace2

Direct3DRMFace2オブジェクトに適用されたDirect3DRMTexture3を取得する。

構文

object.GetTexture( ) As Direct3DRMTexture3

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMTexture3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFace2.SetTexture

Direct3DRMFace2.GetTextureCoordinateIndex

Direct3DRMFace2

面のメッシュにある頂点のインデックスをテクスチャ座標で取得する。

構文

object.GetTextureCoordinateIndex(which As Long) As Long

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
which
対応するメッシュ頂点インデックスを取り出し中の頂点の面内のインデックス。

戻り値

面のメッシュを起点とする頂点インデックスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.GetTextureCoordinates

Direct3DRMFace2

Direct3DRMFace2オブジェクト中の頂点のテクスチャ座標を取得する。

構文

object.GetTextureCoordinates(Vertex As Long,
  u As Single,
  v As Single)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
Vertex
頂点のインデックス。
u, v
点のテクスチャ座標を受け取る変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.GetTextureTopology

Direct3DRMFace2

Direct3DRMFace2オブジェクトのテクスチャ位相を取得する。

構文

object.GetTextureTopology(u As Long,
  v As Long)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
u, v
テクスチャ座標を受け取る変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.GetVertex

Direct3DRMFace2

Direct3DRMFace2オブジェクト中の頂点の位置と法線を取得する。

構文

object.GetVertex(idx As Long,
  vert As D3DVECTOR,
  norm As D3DVECTOR)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
idx
頂点のインデックス。
vert, norm
それぞれ、頂点の位置と法線を受け取るD3DVECTORタイプ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.GetVertexCount

Direct3DRMFace2

Direct3DRMFace2オブジェクトの頂点の数を取得する。

構文

object.GetVertexCount( ) As Long

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。

戻り値

頂点の数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.GetVertexIndex

Direct3DRMFace2

面のメッシュにある頂点のインデックスを取得する。

構文

object.GetVertexIndex(which As Long) As Long

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
which
対応するメッシュ頂点インデックスを取り出し中の頂点の面内のインデックス。

戻り値

メッシュを起点とする頂点インデックスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.GetVertices

Direct3DRMFace2

Direct3DRMFace2 オブジェクト中のそれぞれの頂点について、位置と法線ベクトルを取得する。

構文

object.GetVertices(vertexCount As Long,
  coord() As D3DVECTOR,
  normals() As D3DVECTOR)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
vertexCount
頂点の数を受け取る変数。このパラメータにNOTHINGを指定することはできない。
coord, normals
それぞれ、頂点の位置と法線ベクトルを受け取るD3DVECTORタイプの配列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

vertexCountを決定し、coordとnormalsにそのサイズを設定するには、GetVertexCountを使用する。

Direct3DRMFace2.SetColor

Direct3DRMFace2

Direct3DRMFace2オブジェクトの色を設定する。

構文

object.SetColor(c As Long)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
c
設定する色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。色は4バイトのLongで表される。高バイトはアルファ要素であり、後続のバイトが赤、緑、青を定義する。より簡単に色を構築するにはDirectX7オブジェクトのCreateColorRGBAを使い、フルアルファを希望しているだけの場合はSetColorRGBを使う。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFace2.GetColor

Direct3DRMFace2.SetColorRGB

Direct3DRMFace2

Direct3DRMFace2オブジェクトの赤、緑、青の色要素を設定する。

構文

object.SetColorRGB(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
r, g, b
赤、緑、青の色要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.SetMaterial

Direct3DRMFace2

Direct3DRMFace2オブジェクトのマテリアルを設定する。

構文

object.SetMaterial(ref As Direct3DRMMaterial2)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
ref
マテリアルとして使用するDirect3DRMMaterialオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFace2.GetMaterial

Direct3DRMFace2.SetTexture

Direct3DRMFace2

Direct3DRMFace2オブジェクトのテクスチャを設定する。

構文

object.SetTexture(ref As Direct3DRMTexture3)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
ref
テクスチャとして使用するDirect3DRMTexture3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

まず、DirectX Foundation 6については、テクスチャの幅と高さが2の累乗である必要はない。

参照

Direct3DRMFace2.GetTexture

Direct3DRMFace2.SetTextureCoordinates

Direct3DRMFace2

Direct3DRMFace2オブジェクト中の頂点のテクスチャ座標を設定する。

構文

object.SetTextureCoordinates(Vertex As Long,
  u As Single,
  v As Single)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
Vertex
設定する頂点のインデックス。たとえば、面が三角形のとき、頂点は0、1、2となる。
u, v
指定された頂点に割り当てるテクスチャ座標。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFace2.SetTextureTopology

Direct3DRMFace2

Direct3DRMFace2オブジェクトにテクスチャ位相を設定する。

構文

object.SetTextureTopology(wrap_u As CONST_DBOOLFLAGS,
  wrap_v As CONST_DBOOLFLAGS)

要素

object
Direct3DRMFace2オブジェクトを表すオブジェクト式。
wrap_u, wrap_v
テクスチャの位相をuとvの次元で円柱にしたい場合は、これらのパラメータのいずれか、または両方にD_TRUEを指定する。そうでなければ、D_FALSEを指定する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

いくつかのインターフェイスでSetTextureTopologyメソッドが提供される。SetTextureTopologyメソッドとの関係の詳細、およびwrap_uとwrap_vパラメータの目的に関する詳細については、「Direct3DRMeshBuilder3.SetTextureTopology」を参照すること。


Direct3DRMFaceArray

メッシュ上の面をグループ化するには、Direct3DRMFaceArrayインターフェイスのメソッドを利用する。面の配列は、0が基準になっている (0～N-1)。面の概要については、「Direct3DRMFace2」を参照すること。

Direct3DRMFaceArrayインターフェイスは、次のメソッドをサポートする。

  • GetElement
  • GetSize

Direct3DRMFaceArrayオブジェクトは、Direct3DRMMeshBuilder3.GetFacesメソッドの呼び出しによって取得される。

Direct3DRMFaceArray.GetElement

Direct3DRMFaceArray

Direct3DRMFaceArrayオブジェクトから指定された要素を取得する。

構文

object.GetElement(index As Long) As Direct3DRMFace2

要素

object
Direct3DRMFaceArrayオブジェクトを表すオブジェクト式。
index
配列要素。

戻り値

Direct3DRMFaceArrayオブジェクトのindexパラメータで指定されたDirect3DRMFace要素を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFaceArray.GetSize

Direct3DRMFaceArray

Direct3DRMFaceArrayオブジェクトに含まれる要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMFaceArrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMFrame3

アプリケーションは、Direct3DRMFrame3インターフェイスのメソッドを使用してオブジェクトの参照フレームと対話する。

Direct3DRMFrame3は、追加変換機能、横断オプションのセットと取り出し、シーンフォグメソッドのセットと取り出しを可能にするメソッドを提供する。メソッドは、「Direct3DRMFrame3メソッドA～M」と「Direct3DRMFrame3メソッドN～Z」の2つのセクションに分かれている。

Direct3DRMFrame3インターフェイスのメソッドは、以下のグループにまとめることができる。

軸 | GetAxes
GetInheritAxes
SetAxes
SetInheritAxes
背景 | GetSceneBackground
GetSceneBackgroundDepth
SetSceneBackground
SetSceneBackgroundDepth
SetSceneBackgroundImage
SetSceneBackgroundRGB
境界ボックス | GetBox
GetBoxEnable
GetHierarchyBox
SetBox
SetBoxEnable
色 | GetColor
SetColor
SetColorRGB
フォグ | GetSceneFogColor
GetSceneFogEnable
GetSceneFogMethod
GetSceneFogMode
GetSceneFogParams
SetSceneFogColor
SetSceneFogEnable
SetSceneFogMethod
SetSceneFogMode
SetSceneFogParams
階層 | AddChild
DeleteChild
GetChildren
GetParent
GetScene
照明 | AddLight
DeleteLight
GetLights
ロード | LoadFromFile
マテリアル | GetMaterial
GetMaterialOverride
GetMaterialOverrideTexture
SetMaterial
SetMaterialOverride
SetMaterialOverrideTexture
マテリアルモード | GetMaterialMode
SetMaterialMode
位置指定と運動 | AddMoveCallback
AddRotation
AddScale
AddTranslation
DeleteMoveCallback
GetOrientation
GetPosition
GetRotation
GetVelocity
LookAt
Move
SetOrientation
SetPosition
SetQuaternion
SetRotation
SetVelocity
光線ピック | RayPick
保存 | Save
ソート | GetSortMode
GetZbufferMode
SetSortMode
SetZbufferMode
テクスチャ | GetTexture
SetTexture
変換 | AddTransform
GetTransform
InverseTransform
InverseTransformVectors
Transform
TransformVectors
横断 | GetTraversalOptions
SetTraversalOptions
ビジュアルオブジェクト | AddVisual
DeleteVisual
GetVisual
GetVisuals
GetVisualCount

Direct3DRMFrame3インターフェイスは、Direct3DRMObjectインターフェイスから以下のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMFrame3オブジェクトは、Direct3DRM3.CreateFrameメソッドを呼び出すことによって取得される。


Direct3DRMFrameArray

アプリケーションは、Direct3DRMFrameArrayインターフェイスのメソッドを使用してフレームオブジェクトを整理する。フレームの配列は、0が基準になっている (0～N-1)。この項は、このインターフェイスのメソッドのリファレンスである。

Direct3DRMFrameArray次のメソッドをサポートする。

  • GetElement
  • GetSize

Direct3DRMFrameArrayオブジェクトは、Direct3DRMPickArray.GetPickFrame、Direct3DRMPick2Array.GetPickFrameまたはDirect3DRMFrame3.GetChildrenメソッドの呼び出しによって取得される。

Direct3DRMFrameArray.GetElement

Direct3DRMFrameArray

Direct3DRMFrameArrayオブジェクトから指定された要素を取得する。

構文

object.GetElement(index As Long) As Direct3DRMFrame3

要素

object
Direct3DRMFrameArrayオブジェクトを表すオブジェクト式。
index
配列要素。

戻り値

Direct3DRMFrame3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameArray.GetSize

Direct3DRMFrameArray

Direct3DRMFrameArrayオブジェクトに含まれている要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMFrameArrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMFrameInterpolator

インターポレータは、アクションを格納した後、中間値を自動計算して、オブジェクトにアクションを適用する方法を提供する。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、さらに、ほかのさまざまな変換も行うことができる。

Direct3DRMFrame3オブジェクトは、Direct3DRMFrameInterpolatorオブジェクトにアタッチできる。インターポレータの詳細については、追加情報の「インターポレータ」を参照すること。

Direct3DRMFrameInterpolatorには次のメソッドが含まれる。

オブジェクトのアタッチ | AttachObject
DetachObject
GetAttachedObjects
背景 | SetSceneBackground
SetSceneBackgroundRGB
色 | SetColor
SetColorRGB
フォグ | SetSceneFogColor
SetSceneFogParams
補間の実行 | GetIndex
Interpolate
SetIndex
位置指定と移動 | SetOrientation
SetPosition
SetQuaternion
SetRotation
SetVelocity

さらに、Direct3DRMFrameInterpolatorは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMFrameInterpolator.AttachObject

Direct3DRMFrameInterpolator

オブジェクトをインターポレータに接続する。

構文

object.AttachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータに接続するDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

接続されるオブジェクトは、別のインターポレータでも、インターポレータがxInterpolator型となるタイプxのオブジェクトでも良い。たとえば、Direct3DRMFrame3オブジェクトは、Direct3DRMFrameInterpolatorオブジェクトにアタッチできる。

Direct3DRMFrameInterpolator.DetachObject

Direct3DRMFrameInterpolator

インターポレータからオブジェクトのアタッチを解除する。

構文

object.DetachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータからアタッチを解除するDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.GetAttachedObjects

Direct3DRMFrameInterpolator

インターポレータに現在アタッチされているオブジェクトの配列を取得する。

構文

object.GetAttachedObjects( ) As Direct3DRMObjectArray

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。

戻り値

Direct3DRMObjectArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.GetIndex

Direct3DRMFrameInterpolator

インターポレータの現在の内部インデックス（時間）を取得する。

構文

object.GetIndex( ) As Single

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。

戻り値

インターポレータの現在の内部インデックスを含む値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMFrameInterpolator.Interpolate

Direct3DRMFrameInterpolator

インターポレータに格納されているキー間を補間して、一連のアクションを生成する。その後、アクションは、指定のオブジェクトに適用される。オブジェクトの指定がなければ、アクションは、現在アタッチされているオブジェクトに適用される。

構文

object.Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの現在の内部インデックスを含む値。
mObject
Direct3DRMObjectオブジェクト。このオブジェクトは、インターポレータに格納されているすべてのプロパティに対する補間値を割り当てるオブジェクトを表す。このポインタはNOTHINGでも良い。その場合、すべてのアタッチされているオブジェクトのプロパティ値には、補間値がセットされる。
options
実行する補間の種類を制御するCONST_D3DRMINTERPOLATIONFLAGS列挙型の値の1つ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.SetColor

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolatorオブジェクトにカラーキーを追加する。

構文

object.SetColor(c As Long)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
c
フレームの新しい色。赤、緑、青の色要素のほかにアルファ要素 もセットする。そうしないと、オブジェクトが可視にならないことがある。 オブジェクトの色をアルファ要素を含めて指定するには、オブジェクト上のDirectX7インターフェイスからCreateColorRGBAメソッドを呼び出す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.SetColorRGB

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolatorオブジェクトにRGBカラーキーを追加する。

構文

object.SetColorRGB(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
r, g, b
フレームの新しい色。各色要素は、0.0～1.0の範囲 である必要がある。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.SetIndex

Direct3DRMFrameInterpolator

インターポレータの内部インデックス（時間）に指定の値をセットする。他のインターポレータがそのインターポレータにアタッチされていれば、このメソッドは、再帰的にそれらのインデックスを同じ値に同期させる。

構文

object.SetIndex(val As Single)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの内部インデックスに対してセットされる時間。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMFrameInterpolator.SetOrientation

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolatorオブジェクトに方向キーを追加する。

構文

object.SetOrientation(reference As Direct3DRMFrame3,
  dx As Single,
  dy As Single,
  dz As Single,
  ux As Single,
  uy As Single,
  uz As Single)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrame3オブジェクトを表す変数。
dx, dy, dz
フレームの新しいz軸。ベクトルの各要素は、 1.0～1.0の範囲である必要がある。
ux, uy, uz
フレームの新しいy軸。ベクトルの各要素は、 1.0～1.0の範囲である必要がある。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

フレームのデフォルト方向は、[0, 0, 1] の方向ベクトルと [0, 1, 0] のアップベクトルを持つ。

[ux, uy, uz] が [dx, dy, dz]に平行な場合には、D3DRMERR_BADVALUEエラー値が戻る。そうでない場合には、渡された [ux, uy, uz] ベクトルは、[dx, dy, dz]に垂直なプレーンに投影される。

Direct3DRMFrameInterpolator.SetPosition

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolatorオブジェクトに位置キーを追加する。

構文

object.SetPosition(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrame3オブジェクトを表す変数。
x, y, z
フレームの新しい位置。位置には単位がない。 視錐台を使って適当な数を選択する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.SetQuaternion

Direct3DRMFrameInterpolator

単位4元数を用いて、参照フレームに対してフレームの向きを設定する。

構文

object.SetQuaternion(reference As Direct3DRMFrame3,
  quat As D3DRMQUATERNION)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrame3オブジェクトを表す変数。
quat
フレームの方向を設定するD3DRMQUATERNION型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

4元数とは、任意の回転を表すために用いられる4値ベクトルで、向きの間で補間を行うときに有用な特性を持っている。4元数は、s**2 + x**2 + y**2 + z**2 = 1であれば単位4元数である。

Direct3DRMFrameInterpolator.SetRotation

Direct3DRMFrameInterpolator

Direct3DRM3.TickまたはDirect3DRMFrame3.Moveメソッドに対する呼び出しごとに、指定のベクトルの周囲に指定の角度でフレームの回転を設定する。方向ベクトル [x, y, z] は参照フレームで定義される。

構文

object.SetRotation(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single,
  theta As Single)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
reference
参照フレームとして使用されるDirect3DRMFrame3 オブジェクトを表す変数。
x, y, z
V回転の中心のベクトル。有効な値は、 1.0～1.0の範囲にある必要がある。
theta
ラジアン単位の回転角。角度が大きければ大きいほど、 オブジェクトの回転は速くなる。MoveとTickメソッドが、この値をスケーリングする。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

指定された回転はレンダリングごとに行列を変更する。

Direct3DRMFrameInterpolator.SetSceneBackground

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolatorオブジェクトに背景カラーキーを追加する。

構文

object.SetSceneBackground(c As Long)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
c
背景の新しい色。オブジェクトの色をアルファ要素を含めて指定するには、オブジェクト上のDirectX7インターフェイスからCreateColorRGBAメソッドを呼び出す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.SetSceneBackgroundRGB

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolatorオブジェクトに背景RGBカラーキーを追加する。

構文

object.SetSceneBackgroundRGB(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
r, g, b
背景の新しい色。赤、緑、青の各色要素は 0.0～1.0の範囲である必要がある。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.SetSceneFogColor

Direct3DRMFrameInterpolator

Direct3DRMRFrameInterpolatorオブジェクトにフォグカラーキーを追加する。

構文

object.SetSceneFogColor(c As Long)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
c
フォグの新しい色。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.SetSceneFogParams

Direct3DRMFrameInterpolator

Direct3DRMRFrameInterpolatorオブジェクトにフォグパラメータキーを追加する。

構文

object.SetSceneFogParams(start As Single,
  End As Single,
  density As Single)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
start, End
線形フォグモードのフォグ開始および終了ポイント。 この設定は、フォグ効果が最初に見えるようになるときのカメラからの距離と、フォグが最大密度になるときの距離を決める。
density
指数フォグモードでのフォグ密度。 この値は、0から1の値でなければならない。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrameInterpolator.SetVelocity

Direct3DRMFrameInterpolator

参照フレームを基準として指定のフレームの速度を設定する。 フレームはDirect3DRM3.TickまたはDirect3DRMFrame3.Moveメソッドに対する連続呼び出しごとに、参照フレームを基準として [x, y, z] ベクトル分だけ移動する。

構文

object.SetVelocity(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single,
  with_rotation As CONST_DBOOLFLAGS)

要素

object
Direct3DRMFrameInterpolatorオブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrame3オブジェクト。
x, y, z
フレームの新しい速度。回転速度には単位がないので、 任意の値にできる。MoveとTickメソッドは、この値をスケーリングする。
with_rotation
直線速度を設定するときに、オブジェクトの回転速度を考慮する かどうかを指定するフラグ。 D_TRUEの場合、オブジェクトの回転速度が計算に含まれる。 そうでなければ、D_FALSEに設定する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMLight

Aアプリケーションは、照明と互いにやり取りするためにDirect3DRMLightインターフェイスのメソッドを使用する。

Direct3DRMLightインターフェイスのメソッドは、以下のグループにまとめることができる。

減衰 | GetConstantAttenuation
GetLinearAttenuation
GetQuadraticAttenuation
SetConstantAttenuation
SetLinearAttenuation
SetQuadraticAttenuation
色 | GetColor
SetColor
SetColorRGB
有効フレーム | GetEnableFrame
SetEnableFrame
照明タイプ | GetType
SetType
範囲 | GetRange
SetRange
スポット照明オプション | GetPenumbra
GetUmbra
SetPenumbra
SetUmbra

Direct3DRMLightインターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMLightオブジェクトは、Direct3DRM3.CreateLightまたはDirect3DRM3.CreateLightRGBメソッドの呼び出しによって取得される。

Direct3DRMLight.GetColor

Direct3DRMLight

現在のDirect3DRMLightオブジェクトの色を取得する。

構文

object.GetColor( ) As Long

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

色を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMLight.SetColor

Direct3DRMLight.GetConstantAttenuation

Direct3DRMLight

Direct3DRMLightオブジェクトの減衰定数を取得する。

構文

object.GetConstantAttenuation( ) As Single

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

減衰定数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、光源からの距離に基づいて照明の減衰を計算できる。

全減衰係数の公式は次のとおりである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

参照

Direct3DRMLight.SetConstantAttenuation

Direct3DRMLight.GetEnableFrame

Direct3DRMLight

照明の有効フレームを取得する。

構文

object.GetEnableFrame( ) As Direct3DRMFrame3

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

成功すればDirect3DRMFrame3オブジェクトを、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMLight.SetEnableFrame

Direct3DRMLight.GetLinearAttenuation

Direct3DRMLight

照明の1次減衰係数を取得する。

構文

object.GetLinearAttenuation( ) As Single

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

1次減衰係数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、光源からの距離に基づいて照明の減衰を計算できる。

T全減衰係数の公式は次のとおりである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

参照

Direct3DRMLight.SetLinearAttenuation

Direct3DRMLight.GetPenumbra

Direct3DRMLight

スポットライトの暗影部の角度を取得する。

構文

object.GetPenumbra( ) As Single

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

ラジアン単位の暗影部の値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMLight.SetPenumbra

Direct3DRMLight.GetQuadraticAttenuation

Direct3DRMLight

照明の2次減衰係数を取得する。

構文

object.GetQuadraticAttenuation( ) As Single

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

2次減衰係数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

全減衰係数の公式は次の通りである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

参照

Direct3DRMLight.SetQuadraticAttenuation

Direct3DRMLight.GetRange

Direct3DRMLight

現在のDirect3DRMLightオブジェクトの範囲を取得する。

構文

object.GetRange( ) As Single

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

範囲を示す値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMLight.SetRange

Direct3DRMLight.GetType

Direct3DRMLight

指定された照明のタイプを取得する。

構文

object.GetType( ) As CONST_D3DRMLIGHTTYPE

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMLIGHTTYPE列挙型のメンバの1つを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMLight.SetType

Direct3DRMLight.GetUmbra

Direct3DRMLight

Direct3DRMLightオブジェクトの明部の角度を取得する。デフォルトは、0.4ラジアンである。

構文

object.GetUmbra( ) As Single

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。

戻り値

ラジアン単位の明部の角度を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMLight.SetUmbra

Direct3DRMLight.SetColor

Direct3DRMLight

指定された照明の色を設定する。

構文

object.SetColor(c As Long)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
c
照明の新しい色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。色は4バイトのLongで表される。高バイトはアルファ要素であり、後続のバイトが赤、緑、青を定義する。より簡単に色を構築するにはDirectX7オブジェクトのCreateColorRGBAを使い、フルアルファを希望しているだけの場合はSetColorRGBを使う。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMLightInterpolatorオブジェクトにカラーキーを追加するためにも使用する。

参照

Direct3DRMLight.GetColor

Direct3DRMLight.SetColorRGB

Direct3DRMLight

指定された照明の色をR、B、Gそれぞれの値で設定する。

構文

object.SetColorRGB(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
r, g, b
照明の新しい色。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMLightInterpolatorオブジェクトにRGBカラーキーを追加するためにも使用する。

Direct3DRMLight.SetConstantAttenuation

Direct3DRMLight

照明の減衰係数を設定する。

構文

object.SetConstantAttenuation(atn As Single)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
atn
新しい減衰定数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

全減衰係数の公式は次のとおりである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに減衰定数キーを追加するためにも使用する。

参照

Direct3DRMLight.GetConstantAttenuation

Direct3DRMLight.SetEnableFrame

Direct3DRMLight

照明の有効フレームを設定する。

構文

object.SetEnableFrame(f As Direct3DRMFrame3)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
f
Direct3DRMLightオブジェクトのDirect3DRMFrame3インターフェイス。このフレームの子フレームも、この照明が有効になる。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMLight.GetEnableFrame

Direct3DRMLight.SetLinearAttenuation

Direct3DRMLight

照明の1次減衰係数を設定する。

構文

object.SetLinearAttenuation(atn As Single)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
atn
新しい1次減衰係数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

全減衰係数の公式は次のとおりである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに1次減衰定数キーを追加するためにも使用する。

参照

Direct3DRMLight.GetLinearAttenuation

Direct3DRMLight.SetPenumbra

Direct3DRMLight

円錐の暗影部の角度を設定する。

構文

object.SetPenumbra(p As Single)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
p
ラジアン単位の新しい暗影部の角度。この角度は暗部の角度より大きいか、等しくなくてはいけない。暗影部の角度を明部の角度よりも小さく設定した場合、暗影部は明部と同じ角度になる。デフォルト値は0.5ラジアンである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに影角度キーを追加するためにも使用する。

参照

Direct3DRMLight.GetPenumbra

Direct3DRMLight.SetQuadraticAttenuation

Direct3DRMLight

照明の2次減衰係数を設定する。

構文

object.SetQuadraticAttenuation(atn As Single)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
atn
新しい2次減衰係数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

全減衰係数の公式は次のとおりである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに2次減衰キーを追加するためにも使用する。

参照

Direct3DRMLight.GetQuadraticAttenuation

Direct3DRMLight.SetRange

Direct3DRMLight

スポットライトの範囲を設定する。この照明は、範囲内にあるオブジェクトに限り影響する。

構文

object.SetRange(mg As Single)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
mg
新しい範囲。デフォルト値は、256モデル空間単位である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

範囲プロパティは、スポットライトだけのものである。このメソッドは、Direct3DRMLightInterpolatorオブジェクトに範囲キーを追加するためにも使用する。

参照

Direct3DRMLight.GetRange

Direct3DRMLight.SetType

Direct3DRMLight

照明のタイプを変更する。

構文

object.SetType(t As CONST_D3DRMLIGHTTYPE)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
t
新しい照明タイプをCONST_D3DRMLIGHTTYPE列挙型のメンバの1つで指定する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMLight.GetType

Direct3DRMLight.SetUmbra

Direct3DRMLight

円錐の明部の角度を設定する。

構文

object.SetUmbra(u As Single)

要素

object
Direct3DRMLightオブジェクトを表すオブジェクト式。
u
ラジアン単位の新しい明部の角度。この角度は、暗影部の角度よりも小さいか、等しくなくてはいけない。明部の角度を暗影部の角度より大きく設定した場合、明部は暗影部と同じ角度となる。デフォルト値は0.4ラジアンである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに影角度キーを追加するためにも使用する。

参照

Direct3DRMLight.GetUmbra


Direct3DRMLightArray

アプリケーションは、Direct3DRMLightArrayインターフェイスのメソッドを使って照明オブジェクトをグループ化する。照明の配列は、0が基準になっている (0～N-1)。

Direct3DRMLightArrayインターフェイスは、次のメソッドをサポートする。

  • GetElement
  • GetSize

Direct3DRMLightArrayオブジェクトは、Direct3DRMFrame3.GetLightsメソッドの呼び出しによって取得される。

Direct3DRMLightArray.GetElement

Direct3DRMLightArray

Direct3DRMLightArrayオブジェクトから指定された要素を取得する。

構文

object.GetElement(index As Long) As Direct3DRMLight

要素

object
Direct3DRMLightArrayオブジェクトを表すオブジェクト式。
index
配列要素。

戻り値

Direct3DRMLightオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMLightArray.GetSize

Direct3DRMLightArray

Direct3DRMLightArrayオブジェクトに含まれている要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMLightArrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMLightInterpolator

インターポレータは、アクションを格納した後、中間値を自動計算して、オブジェクトにアクションを適用する方法を提供する。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、さらに、ほかのさまざまな変換も行うことができる。

Direct3DRMLightオブジェクトは、Direct3DRMLightInterpolatorオブジェクトにアタッチできる。インターポレータの詳細については、追加情報の「インターポレータ」を参照すること。

Direct3DRMLightInterpolatorインターフェイスには、次のメソッドが含まれる。

オブジェクトのアタッチ | AttachObject
DetachObject
GetAttachedObjects
減衰 | SetConstantAttenuation
SetLinearAttenuation
SetQuadraticAttenuation
色 | SetColor
SetColorRGB
補間の実行 | GetIndex
Interpolate
SetIndex
範囲 | SetRange
スポットライトオプション | SetPenumbra
SetUmbra

さらに、Direct3DRMLightInterpolatorは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMLightInterpolator.AttachObject

Direct3DRMLightInterpolator

オブジェクトをインターポレータに接続する。

構文

object.AttachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータにアタッチするDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アタッチされるオブジェクトは、別のインターポレータでも、インターポレータがxInterpolator型となるタイプxのオブジェクトでも良い。たとえば、Direct3DRMLightオブジェクトは、Direct3DRMLightInterpolatorオブジェクトにアタッチできる。

Direct3DRMLightInterpolator.DetachObject

Direct3DRMLightInterpolator

インターポレータからオブジェクトのアタッチを解除する。

構文

object.DetachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータからアタッチを外すDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMLightInterpolator.GetAttachedObjects

Direct3DRMLightInterpolator

インターポレータに現在アタッチされているオブジェクトを取得する。

構文

object.GetAttachedObjects( ) As Direct3DRMObjectArray

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。

戻り値

Direct3DRMObjectArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMLightInterpolator.GetIndex

Direct3DRMLightInterpolator

インターポレータの現在の内部インデックス（時間）を取得する。

構文

object.GetIndex( ) As Single

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。

戻り値

インターポレータの現在の内部インデックスを含む値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMLightInterpolator.Interpolate

Direct3DRMLightInterpolator

インターポレータに格納されているキー間を補間して、一連のアクションを生成する。その後、アクションは、指定のオブジェクトに適用される。オブジェクトの指定がなければ、アクションは、現在アタッチされているオブジェクトに適用される。

構文

object.Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの現在の内部インデックスを含む値。
mObject
Direct3DRMObjectオブジェクト。このオブジェクトは、インターポレータに格納されているすべてのプロパティに対する補間値を割り当てるオブジェクトを表す。このポインタはNOTHINGでも良い。その場合には、すべての接続されているオブジェクトのプロパティ値には、補間値がセットされる。
options
実行する補間の種類を制御するCONST_D3DRMINTERPOLATIONFLAGS列挙型の値の1つ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMLightInterpolator.SetColor

Direct3DRMLightInterpolator

Direct3DRMLightInterpolatorオブジェクトにカラーキーを追加する。

構文

object.SetColor(c As Long)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
c
フレームの新しい色。赤、緑、青の色要素のほかにアルファ要素もセットする。そうしないと、オブジェクトが可視にならないことがある。色は4バイトのLongで表される。高バイトはアルファ要素であり、後続のバイトが赤、緑、青を定義する。より簡単に色を構築するにはDirectX7オブジェクトのCreateColorRGBAを使い、フルアルファを希望しているだけの場合はSetColorRGBを使う。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMLightInterpolator.SetColorRGB

Direct3DRMLightInterpolator

Direct3DRMLightInterpolatorオブジェクトにRGBカラーキーを追加する。

構文

object.SetColorRGB(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
r, g, b
照明の新しい赤、緑、青の色要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMLightInterpolator.SetConstantAttenuation

Direct3DRMLightInterpolator

Direct3DRMLightInterpolatorオブジェクトに減衰定数キーを追加する。

構文

object.SetConstantAttenuation(atn As Single)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
atn
新しい減衰定数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

全減衰係数の公式は次のとおりである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに減衰定数キーを追加するためにも使用する。

Direct3DRMLightInterpolator.SetIndex

Direct3DRMLightInterpolator

インターポレータの内部インデックス（時間）に指定の値をセットする。他のインターポレータがそのインターポレータにアタッチされていれば、このメソッドは、再帰的にそれらのインデックスを同じ値に同期させる。

構文

object.SetIndex(val As Single)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの内部インデックスに対してセットされる時間。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMLightInterpolator.SetLinearAttenuation

Direct3DRMLightInterpolator

Direct3DRMLightInterpolatorオブジェクトに1次減衰キーを追加する。

構文

object.SetLinearAttenuation(atn As Single)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
atn
新しい1次減衰係数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

全減衰係数の公式は次のとおりである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

Direct3DRMLightInterpolator.SetPenumbra

Direct3DRMLightInterpolator

Direct3DRMLightInterpolatorオブジェクトに影角度キーを追加する。

構文

object.SetPenumbra(p As Single)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
p
ラジアン単位の新しい暗影部の角度。この角度は暗部の角度より大きいか、等しくなくてはいけない。暗影部の角度を明部の角度よりも小さく設定した場合、暗影部は明部と同じ角度になる。デフォルト値は0.5ラジアンである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMLightInterpolator.SetQuadraticAttenuation

Direct3DRMLightInterpolator

Direct3DRMLightInterpolatorオブジェクトに2次減衰キーを追加する

構文

object.SetQuadraticAttenuation(atn As Single)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
atn
新しい2次減衰係数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

位置を持つ（無限に遠くない）照明には減衰定数があり、照明からの距離に基づいて照明の減衰を計算できる。

全減衰係数の公式は次のとおりである。

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

全減衰係数は1より大きくならない。減衰係数が指定されないと、デフォルト値は、減衰定数に対しては1.0、1次減衰係数に対しては0.0、2次減衰係数に対しては0.0である。

このメソッドは、Direct3DRMLightInterpolatorオブジェクトに2次減衰キーを追加するためにも使用する。

参照

Direct3DRMLight.GetQuadraticAttenuation

Direct3DRMLightInterpolator.SetRange

Direct3DRMLightInterpolator

Direct3DRMLightInterpolatorオブジェクトに範囲キーを追加する。

構文

object.SetRange(mg As Single)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
mg
新しい範囲。デフォルト値は、256モデル空間単位である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

範囲プロパティは、スポットライトだけのものである。

Direct3DRMLightInterpolator.SetUmbra

Direct3DRMLightInterpolator

Direct3DRMLightInterpolatorオブジェクトに影角度キーを追加する。

構文

object.SetUmbra(u As Single)

要素

object
Direct3DRMLightInterpolatorオブジェクトを表すオブジェクト式。
u
ラジアン単位の新しい明部の角度。この角度は、暗影部の角度よりも小さいか、等しくなくてはいけない。明部の角度を暗影部の角度より大きく設定した場合、明部は暗影部と同じ角度となる。デフォルト値は0.4ラジアンである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMMaterial2

アプリケーションは、マテリアルオブジェクトと互いにやり取りするためにDirect3DRMMaterial2インターフェイスのメソッドを使用する。

マテリアルでは、サーフェスがどのように光を反射するかを定義する。マテリアルには、放射プロパティと反射プロパティの2つの要素があり、その輝度は強度設定によって決まる。指数の値は反射するハイライトの鋭さを決め、5の値は金属の外観を与え、より大きい値はよりプラスチック的な外観を与える。

アプリケーションは、GetEmissiveとSetEmissiveメソッドを使用してマテリアルの放射を、GetSpecularとSetSpecularメソッドを使用して反射要素を、GetPowerとSetPowerメソッドを使用して指数を制御することができる。

Direct3DRMMaterial2オブジェクトは、SetAmbientが呼び出されるまで、オブジェクトの面の色をアンビエントの色として使用する。

Direct3DRMMaterial2インターフェイスのメソッドは、以下のグループにまとめることができる。

アンビエント | GetAmbient
SetAmbient
放射 | GetEmissive
SetEmissive
反射指数 | GetPower
SetPower
反射 | GetSpecular
SetSpecular

Direct3DRMMaterial2インターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMaterialオブジェクトは、Direct3DRM3.CreateMaterialメソッドの使用によって取得される。

Direct3DRMMaterial2.GetAmbient

Direct3DRMMaterial2

マテリアルの現在のアンビエント値を取得する。

構文

object.GetAmbient(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMaterial2オブジェクトを表すオブジェクト式。
r
アンビエントカラーの赤要素。
g
アンビエントカラーの緑要素。
b
アンビエントカラーの青要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMaterial2.GetEmissive

Direct3DRMMaterial2

マテリアルの放射プロパティの設定を取得する。このプロパティの設定は、色とオブジェクトが発散する光の指数を示す。

構文

object.GetEmissive(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMaterial2オブジェクトを表すオブジェクト式。
r, g, b
放射の赤、緑、青の色要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMaterial2.SetEmissive

Direct3DRMMaterial2.GetPower

Direct3DRMMaterial2

指定されたマテリアルでの反射指数を取得する。

構文

object.GetPower( ) As Single

要素

object
Direct3DRMMaterial2オブジェクトを表すオブジェクト式。

戻り値

反射指数の指数を示す値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMaterial2.SetPower

Direct3DRMMaterial2.GetSpecular

Direct3DRMMaterial2

マテリアルの反射ハイライトの色を取得する。

構文

object.GetSpecular(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMaterial2オブジェクトを表すオブジェクト式。
r, g, b
メソッドが制御を返すときの反射ハイライトの赤、緑、青の色要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMaterial2.SetSpecular

Direct3DRMMaterial2.SetAmbient

Direct3DRMMaterial2

マテリアルのアンビエント値を設定する。デフォルトは拡散色である。

構文

object.SetAmbient(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMaterial2オブジェクトを表すオブジェクト式。
r
アンビエントカラーの赤要素。
g
アンビエントカラーの緑要素。
b
アンビエントカラーの青要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMaterial2.SetEmissive

Direct3DRMMaterial2

マテリアルの放射プロパティを設定する。

構文

object.SetEmissive(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMaterial2オブジェクトを表すオブジェクト式。
r, g, b
放射の色の赤、緑、青要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMMaterialInterpolatorオブジェクトに放射プロパティキーを追加するためにも使用する。

参照

Direct3DRMMaterial2.GetEmissive

Direct3DRMMaterial2.SetPower

Direct3DRMMaterial2

マテリアルの反射指数の指数を設定する。

構文

object.SetPower(power As Single)

要素

object
Direct3DRMMaterial2オブジェクトを表すオブジェクト式。
power
新しい反射指数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMMaterialInterpolatorオブジェクトに反射指数キーを追加するためにも使用する。

参照

Direct3DRMMaterial2.GetPower

Direct3DRMMaterial2.SetSpecular

Direct3DRMMaterial2

マテリアルの反射ハイライトの色を設定する。

構文

object.SetSpecular(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMaterial2オブジェクトを表すオブジェクト式。
r, g, b
反射ハイライトの色の赤、緑、青の各要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMMaterialInterpolatorオブジェクトに反射カラーキーを追加するためにも使用する。

参照

Direct3DRMMaterial2.GetSpecular


Direct3DRMMaterialInterpolator

インターポレータは、アクションを格納した後、中間値を自動計算して、オブジェクトにアクションを適用する方法を提供する。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、さらに、ほかのさまざまな変換も行うことができる。

Direct3DRMMaterial2オブジェクトは、Direct3DRMMaterialInterpolatorオブジェクトにアタッチできる。インターポレータの詳細については、追加情報の「インターポレータ」を参照すること。

Direct3DRMMaterialInterpolatorには次のメソッドが含まれる。

オブジェクトのアタッチ | AttachObject
DetachObject
GetAttachedObjects
放射 | SetEmissive
補間の実行 | GetIndex
Interpolate
SetIndex
反射指数 | SetPower
反射 | SetSpecular

さらに、Direct3DRMMaterialInterpolatorは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMaterialInterpolator.AttachObject

Direct3DRMMaterialInterpolator

オブジェクトをインターポレータに接続する。

構文

object.AttachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータにアタッチするDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アタッチされるオブジェクトは、別のインターポレータでも、インターポレータがxInterpolator型となるタイプxのオブジェクトでも良い。たとえば、Direct3DRMMaterial2オブジェクトは、Direct3DRMMaterialInterpolatorオブジェクトにアタッチできる。

Direct3DRMMaterialInterpolator.DetachObject

Direct3DRMMaterialInterpolator

インターポレータからオブジェクトのアタッチを解除する。

構文

object.DetachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータからアタッチを外すDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMaterialInterpolator.GetAttachedObjects

Direct3DRMMaterialInterpolator

インターポレータに現在アタッチされているオブジェクトを取得する。

構文

object.GetAttachedObjects( ) As Direct3DRMObjectArray

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。

戻り値

Direct3DRMObjectArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMaterialInterpolator.GetIndex

Direct3DRMMaterialInterpolator

インターポレータの現在の内部インデックス（時間）を取得する。

構文

object.GetIndex( ) As Single

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。

戻り値

インターポレータの現在の内部インデックスを含む値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMMaterialInterpolator.Interpolate

Direct3DRMMaterialInterpolator

インターポレータに格納されているキー間を補間して、一連のアクションを生成する。その後、アクションは、指定のオブジェクトに適用される。オブジェクトの指定がなければ、アクションは、現在アタッチされているオブジェクトに適用される。

構文

object.Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの現在の内部インデックスを含む値。
mObject
Direct3DRMObjectオブジェクト。このオブジェクトは、インターポレータに格納されているすべてのプロパティに対する補間値を割り当てるオブジェクトを表す。このポインタはNOTHINGでも良い。その場合、すべてのアタッチされているオブジェクトのプロパティ値には、補間値がセットされる。
options
実行する補間の種類を制御するCONST_D3DRMINTERPOLATIONFLAGS列挙型の値の1つ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMaterialInterpolator.SetEmissive

Direct3DRMMaterialInterpolator

Direct3DRMMaterialInterpolatorオブジェクトに放射プロパティキーを追加する。

構文

object.SetEmissive(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。
r, g, b
放射の色の赤、緑、青要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMaterialInterpolator.SetIndex

Direct3DRMMaterialInterpolator

インターポレータの内部インデックス（時間）に指定の値をセットする。他のインターポレータがそのインターポレータにアタッチされていれば、このメソッドは、再帰的にそれらのインデックスを同じ値に同期させる。

構文

object.SetIndex(val As Single)

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの内部インデックスに対してセットされる時間。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMMaterialInterpolator.SetPower

Direct3DRMMaterialInterpolator

Direct3DRMMaterialInterpolatorオブジェクトに反射指数キーを追加する。

構文

object.SetPower(power As Single)

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。
power
新しい反射指数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

マテリアルの反射プロパティでは、powerパラメータの値によって反射するハイライトの鋭さが決まる。5の値は金属の外観を与え、より大きい値はよりプラスチック的な外観を与える。

Direct3DRMMaterialInterpolator.SetSpecular

Direct3DRMMaterialInterpolator

Direct3DRMMaterialInterpolatorオブジェクトに反射カラーキーを追加する。

構文

object.SetSpecular(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMaterialInterpolatorオブジェクトを表すオブジェクト式。
r, g, b
反射ハイライトの色の赤、緑、青の各要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMMesh

アプリケーションは、Direct3DRMMeshインターフェイスのメソッドを使用して、メッシュのグループと会話する。メッシュは、ポリゴン面のセットから構成されるビジュアルオブジェクトである。メッシュは、頂点のセットと面のセット (面はメッシュの頂点と法線によって定義される) を定義する。いくつかの面が使用している頂点または法線を変更すると、それを共有するすべての面の外観が変わる。

メッシュの頂点はメッシュ中の面の位置を定義し、これらを使用してテクスチャマップ内の2D座標を定義することもできる。

Direct3DRMMeshとDirect3DRMMeshBuilder3を使用して、Microsoft® Direct3D® 保持モードでメッシュを操作することができる。

アプリケーションで、同じ特性 (マテリアル、テクスチャなど) をいくつかの頂点または面に割り当てる必要がある場合、Direct3DRMMeshインターフェイスを使用して、これらを1つのグループにまとめることができる。アプリケーションが2つの異なるグループ間で頂点を共有する必要がある場合 (たとえば、メッシュ中の隣接する面の色が異なる場合)、頂点は両方のグループに重複していなければならない。Direct3DRMMesh.AddGroupメソッドは、グループ識別子を面の集合に割り当てる。この識別子を使用して、後続の呼び出しでグループを参照する。

Direct3DRMMeshBuilder3とDirect3DRMMeshインターフェイスによって、アプリケーションは3つ以上の側面を持つ面を作成することができる。たとえば、アプリケーションがレンダリングしているハードウェアに64Kの制限があり、メッシュがそのサイズを超えている場合、これらはメッシュを自動的に複数のバッファに分割する。これらの機能は、Direct3DRMMeshとDirect3DRMMeshBuilder3 APIをDirect3D APIから切り離してセットする。

Direct3DRMMesh.SetGroupColor、SetGroupColorRGB、SetGroupTexture、およびSetGroupMaterialメソッドを使用して、メッシュの各面またはメッシュのすべての面に対して同時に、個別の色、テクスチャ、マテリアルプロパティを定義することができる。

レンダリングするメッシュについては、Direct3DRMFrame3.AddVisualメソッドを使用して、最初にフレームに追加しなければならない。単一のメッシュを複数のフレームに追加して、そのメッシュの複数のインスタンスを作成することができる。

Direct3DRMMesh.SetGroupQualityメソッドに対する呼び出しで指定されたように、アプリケーションは、フラット、グーロー、フォンシェードモードを使用することができる(しかし、フォンシェーディングはまだ利用可能ではない)。

Direct3DRMMeshインターフェイスのメソッドは、以下のグループにまとめることができる。

色 | GetGroupColor
SetGroupColor
SetGroupColorRGB
作成と情報 | AddGroup
GetBox
GetGroupCount
GetGroupData
GetSizes
GetGroupDataSize
マテリアル | GetGroupMaterial
SetGroupMaterial
その他 | Scale
Translate
レンダリングクオリティ | GetGroupQuality
SetGroupQuality
テクスチャマッピング | GetGroupMapping
SetGroupMapping
テクスチャ | GetGroupTexture
SetGroupTexture
頂点の位置 | GetVertex
GetVertexCount
GetVertices
SetVertex
SetVertices

Direct3DRMMeshインターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMeshオブジェクトは、Direct3DRM3.CreateMeshメソッドの使用によって取得される。

Direct3DRMMesh.AddGroup

Direct3DRMMesh

面の集まりをグループ化し、そのグループの識別子を取得する。メッシュに最初に追加されるグループのインデックスは、常に0である。以降のグループのインデックスは、それぞれ1ずつ増加する。

構文

object.AddGroup(vertexCount As Long,
  faceCount As Long,
  verticesPerFace As Long,
  fdata() As Long) As Long

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
vertexCount, faceCount
グループに含まれる頂点と面の数。
verticesPerFace
すべての面が同じ数の頂点を持つ場合、面当たりの頂点の数。グループ中の面が持つ頂点の数が一定でないときは、このパラメータに0を指定しなくてはならない。
fdata
面データ。verticesPerFaceパラメータに値が設定されている場合、このデータは単に、グループの頂点配列へのインデックスリストである。verticesPerFaceが0のときは、頂点インデックスよりも、その面の頂点の数を示す整数値を優先しなくてはならない。たとえば、verticesPerFaceが0で、グループを構成する面が三角形と四角形である場合、データは次のようになる。[ 3, インデックス, インデックス, インデックス, 4, インデックス, インデックス, インデックス, インデックス, 3, インデックス, インデックス, インデックス, ...]

戻り値

グループを識別する値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

新しく追加されたグループには、以下のデフォルトのプロパティが与えられる。

  • 白。
  • テクスチャなし。
  • 反射なし。
  • 頂点配列の各頂点の位置、法線、色は0。

頂点の位置を設定するには、Direct3DRMMesh.SetVerticesメソッドを使用する。

Direct3DRMMesh.GetBox

Direct3DRMMesh

Direct3DRMMeshオブジェクトを含む境界ボックスを取得する。境界ボックスは、それぞれの次元のモデル座標の最小値と最大値を示す。

構文

object.GetBox(vector As D3DRMBOX)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
vector
境界ボックス座標を受け取るD3DRMBOX型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMesh.GetGroupColor

Direct3DRMMesh

グループの色を取得する。

構文

object.GetGroupColor(id As Long) As Long

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。

戻り値

成功すれば、色を示す値を返す。失敗すれば0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.SetGroupColor、Direct3DRMMesh.SetGroupColorRGB

Direct3DRMMesh.GetGroupCount

Direct3DRMMesh

指定されたDirect3DRMMeshオブジェクト中のグループの数を取得する。

構文

object.GetGroupCount( ) As Long

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。

戻り値

成功すればグループの数を返す。失敗すれば0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMesh.GetGroupData

Direct3DRMMesh

指定されたグループに関連付けられた面データを取得する。

構文

object.GetGroupData(id As Long,
  psa() As Long)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
psa
面データを受け取る配列。このデータは、その面の頂点の数を示す整数値が前に指定されたグループの頂点配列へのインデックスリストである。たとえば、グループを構成する面が三角形と四角形である場合、データは次のようになる。[ 3, インデックス, インデックス, インデックス, 4, インデックス, インデックス, インデックス, インデックス, 3, インデックス, インデックス, インデックス, ...]

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMesh.GetGroupDataSize

Direct3DRMMesh

特定のグループに関連付けられたデータ配列中の要素数を取得する。

構文

object.GetGroupDataSize(id As Long) As Long

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使用して生成されたものでなくてはならない。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMesh.GetGroupMapping

Direct3DRMMesh

Direct3DRMMeshオブジェクト中のグループに対して、どのようにテクスチャがマップされるかを取得する。

構文

object.GetGroupMapping(id As Long) As CONST_D3DRMMAPPINGFLAGS

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。

戻り値

グループへのテクスチャのマップ方法を示すCONST_D3DRMMAPPINGFLAGS列挙型から次の値のうちの1つを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.SetGroupMapping

Direct3DRMMesh.GetGroupMaterial

Direct3DRMMesh

Direct3DRMMeshオブジェクト中のグループに関連付けられたマテリアルを取得する。

構文

object.GetGroupMaterial(id As Long) As Direct3DRMMaterial2

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。

戻り値

Direct3DRMMaterial2オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.SetGroupMaterial

Direct3DRMMesh.GetGroupQuality

Direct3DRMMesh

Direct3DRMMeshオブジェクト中の指定されたグループのレンダリングクオリティを取得する。

構文

object.GetGroupQuality(id As Long) As CONST_D3DRMRENDERQUALITY

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。

戻り値

成功すれば、レンダリングクオリティを示すCONST_D3DRMRENDERQUALITY列挙型の値を返す。失敗すれば0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

レンダリングクオリティとは、デバイスのレンダリングサーフェス上で実行されるレンダリングのクオリティの最大値である。

オブジェクトのクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーロー)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

参照

Direct3DRMMesh.SetGroupQuality

Direct3DRMMesh.GetGroupTexture

Direct3DRMMesh

Direct3DRMMeshオブジェクト中のグループに関連付けられたテクスチャを取得する。

構文

object.GetGroupTexture(id As Long) As Direct3DRMTexture3

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。

戻り値

Direct3DRMTexture3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.SetGroupTexture

Direct3DRMMesh.GetSizes

Direct3DRMMesh

Direct3DRMMeshオブジェクト中の指定のグループに対する情報を取得する。

構文

object.GetSizes(id As Long, cnt1 As Long,
  cnt2 As Long,
  cnt3 As Long,
  cnt4 As Long)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
cnt1
グループ中の頂点の数を受け取る。
cnt2
グループ中の面の数を受け取る。
cnt3
すべての面が同じ頂点カウントを持つ場合は、グループ中の各面の頂点の数を受け取る。グループに異なる頂点カウントを持つ面がある場合、このパラメータは0を受け取る。
cnt4
GetGroupDataによって要求されたpsaの必須サイズを受け取る。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.SetVertices

Direct3DRMMesh.GetVertex

Direct3DRMMesh

特定のグループから1つの頂点を取得する。

構文

object.GetVertex(id As Long,
  idx As Long,
  ret As D3DRMVERTEX)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupを使って生成されたものでなくてはならない。
idx
頂点位置を取得する始点を示すD3DRMVERTEX型の配列のインデックス。
ret
メソッドが戻ったとき、頂点情報（頂点位置、色、テクスチャ座標など）を格納するD3DRMVERTEX型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.SetVertices

Direct3DRMMesh.GetVertexCount

Direct3DRMMesh

指定されたDirect3DRMMeshオブジェクトの頂点の数を取得する。

構文

object.GetVertexCount(id As Long) As Long

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupを使って生成されたものでなくてはならない。

戻り値

成功すれば頂点の数を返す。失敗すれば0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.SetVertices

Direct3DRMMesh.GetVertices

Direct3DRMMesh

Direct3DRMMeshオブジェクト中の指定のグループに対する頂点情報を取得する。

構文

object.GetVertices(id As Long,
  idx As Long,
  cnt As Long,
  vertexArray() As D3DRMVERTEX)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
idx
頂点位置を取得する始点を示すD3DRMVERTEX型の配列のインデックス。
cnt
idxパラメータで与えられているインデックス以降の、取得するD3DRMVERTEX型 (頂点) の数。このパラメータはNOTHINGにできない。グループ中の頂点の数を取得するには、Direct3DRMMesh.GetVertexCountメソッドを呼び出す。
vertexArray
メソッドが戻ったとき、頂点情報（頂点位置、色、テクスチャ座標など）を格納するD3DRMVERTEX型の配列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.SetVertices

Direct3DRMMesh.Scale

Direct3DRMMesh

モデル座標のx軸、y軸、z軸に対し、与えられたスケール係数によってDirect3DRMMeshオブジェクトをスケーリングする。

構文

object.Scale(sx As Single,
  sy As Single,
  sz As Single)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
sx, sy, sz
x軸、y軸、z軸に沿って適用されるスケール係数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMesh.SetGroupColor

Direct3DRMMesh

Direct3DRMMeshオブジェクト中のグループの色を設定する。

構文

object.SetGroupColor(id As Long,
  val As Long)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupを使って生成されたものでなくてはならない。
val
グループの色。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMMeshInterpolatorオブジェクトにグループカラーキーを追加するためにも使用する。

参照

Direct3DRMMesh.GetGroupColor、Direct3DRMMesh.SetGroupColorRGB

Direct3DRMMesh.SetGroupColorRGB

Direct3DRMMesh

RGB値を使用して、Direct3DRMMeshオブジェクト中のグループの色を設定する。

構文

object.SetGroupColorRGB(id As Long,
  r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
r, g, b
グループの色の赤、緑、青の各要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMMeshInterpolatorオブジェクトにグループRGBキーを追加するためにも使用する。

参照

Direct3DRMMesh.GetGroupColor、Direct3DRMMesh.SetGroupColor

Direct3DRMMesh.SetGroupMapping

Direct3DRMMesh

Direct3DRMMeshオブジェクト中のグループにマッピングを設定する。マッピングは、どのようにテクスチャが面にマップされるかを決定する。

構文

object.SetGroupMapping(id As Long,
  value As CONST_D3DRMMAPPINGFLAGS)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
value
グループのマッピングを指定するCONST_D3DRMMAPPINGFLAGS列挙型からの値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.GetGroupMapping

Direct3DRMMesh.SetGroupMaterial

Direct3DRMMesh

Direct3DRMMeshオブジェクト中のグループにマテリアルを関連付ける。

構文

object.SetGroupMaterial(id As Long,
  val As Direct3DRMMaterial2)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
val
Direct3DRMMeshオブジェクトのDirect3DRMMaterial2インターフェイス。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.GetGroupMaterial

Direct3DRMMesh.SetGroupQuality

Direct3DRMMesh

Direct3DRMMeshオブジェクト中の指定されたグループのレンダリングクオリティを設定する。

構文

object.SetGroupQuality(id As Long,
  value As CONST_D3DRMRENDERQUALITY)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
value
レンダリングクオリティを示すCONST_D3DRMRENDERQUALITY列挙型の値。これらの値には、オブジェクトのシェーディングモードや照明モード、塗りつぶしモードが含まれている。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

レンダリングクオリティは、デバイスのレンダリング面上で実行されるレンダリングのクオリティの最大値である。

オブジェクトクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーローで、フォンは実装されていない。デフォルトはグーローシェーディング)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

参照

Direct3DRMMesh.GetGroupQuality

Direct3DRMMesh.SetGroupTexture

Direct3DRMMesh

Direct3DRMMeshオブジェクト中のグループにテクスチャを関連付ける。

構文

object.SetGroupTexture(id As Long,
  val As Direct3DRMTexture3)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
val
Direct3DRMMeshオブジェクトに関連付けるDirect3DRMTexture3インターフェイス。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMesh.GetGroupTexture

Direct3DRMMesh.SetVertex

Direct3DRMMesh

Direct3DRMMeshオブジェクト中の既存グループのジオメトリを修正する。

構文

object.SetVertex(id As Long,
  idx As Long,
  values As D3DRMVERTEX)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
idx
修正するメッシュグループの最初の頂点のインデックス。
values
セットする頂点位置を指定するD3DRMVERTEX型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

頂点情報はグループごとに持つ。2つの異なったグループ間で頂点を共有する必要がある場合（たとえば、メッシュ上の隣接した面の色が異なるとき）、両方のグループで頂点をコピーしなくてはならない。

このメソッドは、Direct3DRMMeshInterpolatorオブジェクトに頂点位置キーを追加するためにも使用する。

参照

Direct3DRMMesh.GetVertices

Direct3DRMMesh.SetVertices

Direct3DRMMesh

Direct3DRMMeshオブジェクト中の指定されたグループに頂点位置を設定する。

構文

object.SetVertices(id As Long,
  idx As Long,
  count As Long,
  vertexArray() As D3DRMVERTEX)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
idx
修正するメッシュグループの最初の頂点のインデックス。
count
セットする連続頂点の数。vertexArray配列は、少なくともcount数の要素を格納しなければならない。
vertexArray
設定する頂点位置を示すD3DRMVERTEX型の配列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

頂点情報はグループごとに持つ。2つの異なったグループ間で頂点を共有する必要がある場合（たとえば、メッシュ上の隣接した面の色が異なるとき）、両方のグループで頂点をコピーしなくてはならない。

このメソッドは、Direct3DRMMeshInterpolatorオブジェクトに頂点位置キーを追加するためにも使用する。

参照

Direct3DRMMesh.GetVertices

Direct3DRMMesh.Translate

Direct3DRMMesh

Direct3DRMMeshオブジェクト中の頂点の位置に、指定されたオフセットを追加する。

構文

object.Translate(tx As Single,
  ty As Single,
  tz As Single)

要素

object
Direct3DRMMeshオブジェクトを表すオブジェクト式。
tx, ty, tz
各頂点位置のx座標、y座標、z座標に追加されるオフセット。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMMeshBuilder3

アプリケーションは、IDirect3DRMMeshBuilder3インターフェイスのメソッドを使用してメッシュオブジェクトと対話する。メッシュの詳細については、「Direct3DRMMesh」を参照すること。

Direct3DRMMeshBuilder3.AddVertex、AddFaceおよびAddFacesメソッドを使用して、メッシュに対して個別に頂点と面を追加することができる。

法線 (単位ベクトルでなければならない) をセットするか、またはGenerateNormalsメソッドを使用して、囲んでいる面の面法線を平均化して法線を計算することができる。

Direct3DRMMeshBuilder3メソッドは、1つ以上の法線、法線の数、面、1つ以上の頂点、およびメッシュビルダの状態 (有効または無効)を取得する。このインターフェイスによって、頂点と法線のセット、メッシュビルダの新しいサブメッシュと親メッシュの作成と取り出しを行うことができる。また、Direct3DRMMeshBuilder3では、アプリケーションが新しい三角形 (一般的なポリゴンと対立的な意味で) をDirect3DRMMeshBuilder3オブジェクトに追加し、AddTrianglesメソッドを使用して、処理中に暗黙に新しい面を作成できる。

保持モード6.xでは、Direct3DRM3インターフェイスを使用してDirect3DRMMeshBuilder3オブジェクトを作成することができる。この場合、Direct3DRMMeshBuilder3オブジェクトは、その実装のために直接モードのDrawPrimitiveインターフェイスを使用する。

Direct3DRMMeshBuilder3インターフェイスのメソッドは、以下のグループにまとめることができる。

色 | GetColorSource
SetColor
SetColorRGB
SetColorSource
生成 | GetBox
面 | AddFace
AddFaces
AddFacesIndexed
CreateFace
DeleteFace
GetFaceCount
GetFaceDataSize
GetFace
GetFaces
ロード | LoadFromFile
メッシュ | AddMesh
CreateMesh
その他 | AddFrame
AddMeshBuilder
AddTriangles
Empty
Enable
GetEnable
Optimize
Save
ScaleMesh
SetMaterial
Translate
法線 | AddNormal
GenerateNormals
GetNormals
GetNormalCount
SetNormal
パースペクティブ | GetPerspective
SetPerspective
レンダリングクオリティ | GetQuality
SetQuality
サブメッシュ | CreateSubMesh
DeleteSubMesh
GetParentMesh
GetSubMeshCount
GetSubMeshes
テクスチャ | GetTextureCoordinates
SetTexture
SetTextureCoordinates
SetTextureTopology
頂点 | AddVertex
GetGeometry
GetVertex
GetVertexColor
GetVertexCount
SetVertex
SetVertexColor
SetVertexColorRGB

Direct3DRMMeshBuilder3インターフェイスは、Direct3DRMObjectインターフェイスから以下のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMeshBuilder3オブジェクトは、Direct3DRM3.CreateMeshBuilderメソッドの呼び出しによって取得される。

Direct3DRMMeshBuilder3.AddFace

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに1つの面を追加する。

構文

object.AddFace(f As Direct3DRMFace2)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
f
追加するDirect3DRMFace2オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

どの1つの面も、一度に1つのメッシュにしか存在できない。

Direct3DRMMeshBuilder3.AddFaces

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに複数の面を追加する。

構文

object.AddFaces(vc As Long,
  vertexArray() As D3DVECTOR,
  nc As Long,
  normalArray() As D3DVECTOR,
  data() As Long) As Direct3DRMFaceArray

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
vc
頂点の数。
vertexArray
頂点位置を格納するD3DVECTOR型の配列。
nc
法線の数。
normalArray
法線の位置を格納するD3DVECTOR型の配列。
data
各面に対して、このパラメータは、頂点カウントとそれに続いて頂点配列のインデックスを含む必要がある。ncが0でなければ、このパラメータは、頂点カウントとそれに続いてインデックスの対を含む必要がある。そのインデックスの対の最初のインデックスは、頂点配列に対するインデックスであり、2番目のインデックスは、法線の配列に対するインデックスである。インデックスのリストは、0で終了しなければならない。

戻り値

新しく作成された面へのポインタがセットされるDirect3DRMFaceArrayインターフェイスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.AddFacesIndexed

Direct3DRMMeshBuilder3

既存の頂点と法線 (オプション) を使用するメッシュビルダ上に、多数の面を作成できるようにする。

構文

object.AddFacesIndexed(flags As CONST_D3DRMADDFACESFLAGS,
  indexArray() As Long) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
flags
法線インデックスの処理方法を指定するCONST_D3DRMADDFACESFLAGS列挙型の値。値がD3DRMADDFACES_DEFAULTならば、既存の法線インデックスはindexArrayパラメータ中に指定されていなければならない。そうでない場合、対応するインデックスを持つ法線が各頂点に対して自動的に使用される。
indexArray
各面に対して次のものを指定する、符号なし整数のタップルの連続する配列。
  • 頂点の数 n、ここでnは3以上
  • 頂点インデックス
  • 法線インデックス (オプション)

次のテーブルは、flagsパラメータの値とindexArrayパラメータの必須面タップル形式との関係を示す。

flags | 必須面タップル形式
D3DRMADDFACES_DEFAULT | {<n>, <vIndex0>, <nIndex0>,...,<vIndex n-1>, <nIndex n-1>}
D3DRMADDFACES_VERTICESONLY | {<n>, <vIndex0>,...,<vIndex n-1>}

vIndexとnIndexの値は、メッシュビルダ内に既に存在している頂点と法線にインデックス付けするのに必要となる。タップルの配列は値0で終了する必要がある。

戻り値

メッシュビルダに追加される最初の新しい面のインデックスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.AddFrame

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトにフレームの内容を追加する。

構文

object.AddFrame(f As Direct3DRMFrame3)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
f
その内容が追加されるDirect3DRMFrame3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、指定されたフレーム階層 (より大きなフレーム階層のサブ分岐も可) からDirect3DRMMeshBuilder3オブジェクトへ、すべてのメッシュとメッシュビルダの面のコピーを追加する。フレームツリーは、ルートフレームを渡すことで指定する。面は、それらが内包する要素フレームの位置と方向によって追加される。ルートフレームに親があっても、指定されたルートフレームの変換は無視される。

ソースフレームは、この操作によって変更または参照もされない。

Direct3DRMMeshBuilder3.AddMesh

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトにメッシュを追加する。

構文

object.AddMesh(m As Direct3DRMMesh)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
m
追加されるDirect3DRMMeshオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.AddMeshBuilder

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの内容を別のDirect3DRMMeshBuilder3オブジェクトに追加する。内包するDirect3DRMMeshBuilder3ソースオブジェクトと面のもとにあるすべてのサブメッシュビルダは、Direct3DRMMeshBuilder3ターゲットオブジェクトのもとで重複する。

構文

object.AddMeshBuilder(meshbuilder As Direct3DRMMeshBuilder3,
  flags As CONST_D3DRMADDMESHBUILDERFLAGS)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
meshbuilder
その内容を追加するDirect3DRMMeshBuilder3オブジェクト。
flags
コピーオプションを示すCONST_D3DRMADDMESHBUILDERFLAGS列挙型の1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

ソースのDirect3DRMMeshBuilder3オブジェクトは、この操作で変更または参照もされない。

Direct3DRMMeshBuilder3.AddNormal

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに法線を追加する。

構文

object.AddNormal(x As Single,
  y As Single,
  z As Single) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
x, y, z
新しい法線の方向のx、y、zの各要素。

戻り値

法線のインデックスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.AddTriangles

Direct3DRMMeshBuilder3

アプリケーションが (一般的なポリゴンと対立的な意味で) 新しい三角形をDirect3DRMMeshBuilder3オブジェクトに追加し、処理中に暗黙に新しい面を作成できるようにする。

構文

object.AddTriangles(flags As Long,
  format As CONST_D3DRMADDTRIANGLESVT,
  vertexCount As Long,
  data As Any)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
flags
0でなければならない。
format
頂点データのフォーマットを記述するCONST_D3DRMADDTRIANGLESVT列挙型の値の論理的な組み合わせ。すべての有効な値が含まれている場合、頂点データは次のD3DRMFLEXVERTEXユーザ定義型によって記述できる。

構文

Type D3DRMFLEXVERTEX
  IType As Long
  color As Long
  normal As D3DVECTOR
  position As D3DVECTOR
  tu As Single
  tv As Single
End Type

Dim verts(100) As D3DRMFLEXVERTEX

AddTriangles(D3DRMFVF_TYPE Or D3DRMFVF_NORMAL Or D3DRMFVF_COLOR Or D3DRMFVF_TEXTURECOORDS, 100, verts(0))

有効な値としては、次の値の任意の論理的組み合わせが可能であり、これらはD3DRMFLEXVERTEX型のどのメンバを各要素の記述に含めるかを示す。positionメンバは常に存在する。

D3DRMFVF_TYPE
ITypeメンバを含める。ITypeメンバが存在する場合、その中には次のどれか1つがなければならない。
D3DRMVERTEX_LIST
新しいリストを開始するか、あるいは以前に開始したリストのメンバである。以前の頂点 (またはその前の頂点) にこのフラグのマークが付いていない場合、最低1つの三角形が形成されるまで、次の頂点にこのフラグのマークが付いていなければならない。
D3DRMVERTEX_STRIP
以前の2つの頂点を持つ新しい三角形を細片フォーマットで形成する。
D3DRMVERTEX_FAN
以前の頂点と扇の最初の頂点を持つ新しい三角形を形成する。
D3DRMFVF_NORMAL
normalメンバを含める。
D3DRMFVF_COLOR
colorメンバを含める。
D3DRMFVF_TEXTURECOORDS
tuとtvメンバを含める。
vertexCount
頂点の数。
data
formatで記述されるデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、三角形を記述するアプリケーションに柔軟性を提供する。三角形は頂点のセットで記述される。各頂点は位置を持つが、オプションで法線、テクスチャ座標、または色を持つことも、持たないこともできる。

次の例は、図中の各頂点に対して適切なITypeフラグを示す。

頂点数 | ITypeフラグ
0 | D3DRMVERTEX_STRIP
1 | D3DRMVERTEX_STRIP
2 | D3DRMVERTEX_STRIP
3 | D3DRMVERTEX_STRIP
4 | D3DRMVERTEX_STRIP
5 | D3DRMVERTEX_FAN
6 | D3DRMVERTEX_FAN
7 | D3DRMVERTEX_FAN
8 | D3DRMVERTEX_LIST
9 | D3DRMVERTEX_LIST
10 | D3DRMVERTEX_LIST
11 | D3DRMVERTEX_LIST
12 | D3DRMVERTEX_LIST
13 | D3DRMVERTEX_LIST

Direct3DRMMeshBuilder3.AddVertex

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに頂点を追加する。

構文

object.AddVertex(x As Single,
  y As Single,
  z As Single) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
x, y, z
新しい頂点の位置のx、y、zの各要素。

戻り値

頂点のインデックスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.CreateFace

Direct3DRMMeshBuilder3

頂点のない新しい面を作成し、Direct3DRMMeshBuilder3オブジェクトに追加する。

構文

object.CreateFace( ) As Direct3DRMFace2

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

新しく作成された面を受け取るDirect3DRMFace2オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.CreateMesh

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトから新しいメッシュを作成する。

構文

object.CreateMesh( ) As Direct3DRMMesh

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMMeshオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.CreateSubMesh

Direct3DRMMeshBuilder3

現在のDirect3DRMMeshBuilder3オブジェクトに対して、新しいサブメッシュを作成する。

構文

object.CreateSubMesh( ) As Direct3DRMMeshBuilder3

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMMeshBuilder3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

サブメッシュは、Direct3DRMMeshBuilder3インターフェイスをサポートし、それ自体もサブメッシュを持てるという点で、メッシュビルダオブジェクトに類似している。サブメッシュとメッシュビルダの相違は、すべてのサブメッシュが頂点と法線を、サブメッシュの連鎖中の大元の祖先と共有することである。メッシュビルダは頂点と法線を共有しない。

参照

Direct3DRMMeshBuilder3.DeleteSubMesh、Direct3DRMMeshBuilder3.GetSubMesh、Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.DeleteFace

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの面を削除する。

構文

object.DeleteFace(face As Direct3DRMFace2)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
face
Direct3DRMMeshBuilder3オブジェクトから削除するDirect3DRMFace2オブジェクトのインターフェイス。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.DeleteSubMesh

Direct3DRMMeshBuilder3

サブメッシュを削除する。サブメッシュは、現在のDirect3DRMMeshBuilder3オブジェクトのすぐ下の子でなければならない。

構文

object.DeleteSubMesh(mesh As Direct3DRMMeshBuilder3)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
mesh
削除するサブメッシュのDirect3DRMMeshBuilder3インターフェイス。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.CreateSubMesh、Direct3DRMMeshBuilder3.GetSubMesh、Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.Empty

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトから、すべての面、頂点、法線を削除する。

構文

object.Empty( )

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.Enable

Direct3DRMMeshBuilder3

このDirect3DRMMeshBuilder3オブジェクトを、レンダリングとピッキング用に有効にするか無効にするかを指定する。

構文

object.Enable(flags As CONST_D3DRMADDMESHBUILDERFLAGS)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
flags
レンダリングとピッキングを有効にするかどうかを指定するCONST_D3DRMMESHBUILDERENABLEFLAGS列挙型の1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.GetEnable

Direct3DRMMeshBuilder3.GenerateNormals

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトを処理し、頂点を共有する各面に対する面法線を平均化することによって、メッシュ中の各頂点に対して法線を生成する。新しい法線は、頂点を共有する面が、面どうしの角度が折れ目の角度より大きい場合に生成される。

構文

object.GenerateNormals(angle As Single,
  flags As CONST_D3DRMGENERATENORMALSFLAGS)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
angle
ラジアン単位の、新しい法線を生成できる面どうしの最小可能角度。
flags
CONST_D3DRMGENERATENORMALSFLAGS列挙型の1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

D3DRMGENERATENORMALS_PRECOMPACTフラグを指定すると、プリコンパクトパスは、メッシュ中のすべての頂点を検索し、同じ頂点をすべてマージする。これは、ロードされているメッシュをコンパクトにするのに賢明な方法である。メッシュの中には、頂点に複数の法線を持つ場合に、複数の頂点を持つものがある。これは、Direct3D保持モードでは必要とならない。このフラグの指定は、複数の頂点を除去する場合の定番的方法である。

コンパクト処理の後、法線が生成される。面どうしの間の辺が調べられ、面が辺でなす角度が、折り目角より小さい場合には、面法線は平均化され、頂点法線が生成される。角度が折り目角より大きい場合には、新しい法線が生成される。新しい頂点は、生成されないことに注意する。

Direct3DRMMeshBuilder3.GetBox

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトを含む境界ボックスを取得する。境界ボックスは、各次元での最小、最大のモデル座標を与える。

構文

object.GetBox(retV As D3DRMBOX)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
retV
境界ボックスの座標がセットされるD3DRMBOX型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.GetColorSource

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの色ソースを取得する。色ソースは、面でも頂点でも良い。

構文

object.GetColorSource( ) As CONST_D3DRMCOLORSOURCE

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMCOLORSOURCE列挙型のメンバを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.SetColorSource

Direct3DRMMeshBuilder3.GetEnable

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトを有効にするか無効にするかを示す値を取得する。

構文

object.GetEnable( ) As CONST_D3DRMADDMESHBUILDERFLAGS

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

このDirect3DRMMeshBuilder3オブジェクトの現在の有効状態を示すCONST_D3DRMMESHBUILDERENABLEFLAGS列挙型から値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.Enable

Direct3DRMMeshBuilder3.GetFace

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの単一面を取得する。

構文

object.GetFace(id As Long) As Direct3DRMFace2

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
id
取得するメッシュ面のインデックス。この面はDirect3DRMMeshBuilder3オブジェクトの一部になっていなければならない。

戻り値

面を受け取るDirect3DRMFace2インターフェイスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.GetFaceCount

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの面の数を取得する。

構文

object.GetFaceCount( ) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

面の数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.GetFaceDataSize

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの面データ配列のサイズを取得する。

構文

object.GetFaceDataSize( ) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

GetGeometryに必要なsizeData引数の値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMMeshBuilder3.GetGeometryに必要なfaceData配列のサイズを取得する。

Direct3DRMMeshBuilder3.GetFaces

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの面を取得する。

構文

object.GetFaces( ) As Direct3DRMFaceArray

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

面を受け取るDirect3DRMFaceArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.GetGeometry

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの頂点、法線、面データを取得する。

構文

object.GetGeometry(vertexCount As Long,
  vertexArray() As D3DVECTOR,
  normalCount As Long,
  normalArray() As D3DVECTOR,
  sizeData As Long,
  faceData() As Long)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
vertexCount
vertexArray中の頂点の数。
vertexArray
D3DVECTOR型の配列。これはDirect3DRMMeshBuilder3オブジェクトの頂点を含む。GetVertexCountを使って、この配列の最小サイズを決める。
normalCount
normalArray中の法線の数。
normalArray
D3DVECTOR型の配列。これはDirect3DRMMeshBuilder3オブジェクトの法線を含む。GetNormalCountを使って、この配列のサイズを決める。
sizeData
faceData中の要素数を指定する値。
faceData
Direct3DRMMeshBuilder3オブジェクトの面データ。このデータは、NULLで終わる点を除いて、Direct3DRMMeshBuilder3.AddFacesメソッドで指定されたフォーマットと同じである。GetFaceDataSizeを呼び出して配列のサイズを決める。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.GetNormal

Direct3DRMMeshBuilder3

法線ベクトルを取得する。

構文

object.GetNormal(index As Long,
  desc As D3DVECTOR)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
index
返す法線のインデックス。
desc
法線のx、y、z座標がセットされるD3DVECTOR型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.GetNormalCount

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクト中の法線の数を取得する。

構文

object.GetNormalCount( ) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMMeshBuilder3オブジェクト中の法線の数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.GetNormal、Direct3DRMMeshBuilder3.SetNormal

Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3

このDirect3DRMMeshBuilder3オブジェクトの親メッシュを取得する。

構文

object.GetParentMesh(
    flags As CONST_D3DRMPARENTINGFLAGS)
    As Direct3DRMMeshBuilder3

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
flags
どのDirect3DRMMeshBuilder3オブジェクトを取得するかを定義するCONST_D3DRMPARENTINGFLAGS列挙型の1つ以上の値。

戻り値

Direct3DRMMeshBuilder3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.GetSubMesh

Direct3DRMMeshBuilder3.GetPerspective

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに対して、パースペクティブ補正がオンであるかどうかを判別する。

構文

object.GetPerspective( ) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

パースペクティブ補正がオンの場合は–1、オンでない場合は0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.GetQuality

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのレンダリングクオリティを取得する。

構文

object.GetQuality( ) As CONST_D3DRMRENDERQUALITY

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

メッシュのレンダリングクオリティを指定するCONST_D3DRMRENDERQUALITY列挙型から値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

レンダリングクオリティは、デバイスのレンダリング面上で実行されるレンダリングのクオリティの最大値である。

オブジェクトクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーローで、フォンは実装されていない。デフォルトはグーローシェーディング)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

参照

Direct3DRMMeshBuilder3.SetQuality

Direct3DRMMeshBuilder3.GetSubMeshCount

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに含まれるサブメッシュの数を取得する。

構文

object.GetSubMeshCount( ) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

サブメッシュの数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.GetSubMeshes

Direct3DRMMeshBuilder3

このDirect3DRMMeshBuilder3オブジェクトに含まれるサブメッシュのリストを取得する。

構文

object.GetSubMeshes(count As Long,
  arrayOfMeshBuilders() As Direct3DRMMeshBuilder3)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
count
返される予定のサブメッシュの数。countがポイントする値は、実際に取得されたサブメッシュの数を受け取る。
arrayOfMeshBuilders
子サブメッシュを含むDirect3DRMMeshBuilder3オブジェクトの配列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.GetTextureCoordinates

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点のテクスチャ座標を取得する。

構文

object.GetTextureCoordinates(idx As Long,
  u As Single,
  v As Single)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
idx
頂点のインデックス。
u, v
返された頂点のテクスチャ座標。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.SetTextureCoordinates

Direct3DRMMeshBuilder3.GetVertex

Direct3DRMMeshBuilder3

頂点ベクトルを取得する。

構文

object.GetVertex(id As Long,
  vec As D3DVECTOR)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
id
返す頂点のID。
vec
頂点のx、y、z座標がセットされるD3DVECTOR型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.GetVertexColor

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の色を取得する。

構文

object.GetVertexColor(index As Long) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
index
頂点のインデックス。

戻り値

色を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.SetVertexColor

Direct3DRMMeshBuilder3.GetVertexCount

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクト中の頂点の数を取得する。

構文

object.GetVertexCount( ) As Long

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

戻り値

頂点の数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.LoadFromFile

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトをロードする。

構文

object.LoadFromFile(filename As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As Object)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
filename
ロードするオブジェクトのソース。ソースは、flagsパラメータで指定されたソースフラグに従って、ファイル、リソース、メモリブロック、またはストリームにできる。
id
ロードするオブジェクトの名前または位置。idが""の場合は、optionsパラメータをD3DRMLOAD_FIRSTに設定しなければならない。Microsoft Visual Basic® は、Stringデータ型が指定されている場合でも、ロードするアイテムの位置を示すidパラメータの中のIntegerを受け入れる。たとえば、idパラメータに1が設定されていると、1番目の位置のオブジェクトがロードされる。
options
ロードオプションを記述するCONST_D3DRMLOADFLAGS列挙型の1つ以上の値。
loadTextureImplementation
Direct3DRMLoadTextureCallback3コールバックインターフェイス。特殊なフォーマッティングを必要とするオブジェクトによって使用される、任意のテクスチャをロードするために使われる。テクスチャは、2で割れる幅と長さでなければならない。このパラメータはNOTHINGにできる。
userArgument
コールバックに渡されるアプリケーション定義データ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デフォルトでは、このメソッドはfilenameパラメータで指定されているソースから最初のメッシュをロードする。

このメソッドは、Direct3DRM3.SetOptionsがセットする右手と左手ジオメトリオプションを考慮する。

そのロードメソッドを複数回を呼び出すことで、複数のオブジェクトをDirect3DRMMeshBuilder3オブジェクトにロードすることができる。

各LoadFromFileメソッドは、filenameパラメータを使用してオブジェクトのソースを指定し、idパラメータによってオブジェクトを識別する。システムはソースフラグの選択に基づいてfilenameパラメータを解釈する。そして、識別子フラグの選択に基づいてidパラメータの内容を解釈する。

インスタンスフラグは、パラメータの解釈方法には何も変更を加えない。D3DRMLOAD_INSTANCEBYREFERENCEフラグを用いると、新しいオブジェクトを作成することなく同じファイルを2回ロードすることができる。オブジェクトが名前を持っていない場合、D3DRMLOAD_INSTANCEBYREFERENCEフラグをセットすると、D3DRMLOAD_INSTANCEBYCOPYINGフラグをセットしたときと同じ効果を得ることができる。ローダは、同一のオブジェクトが存在しても、各名前なしオブジェクトを新しいオブジェクトとして作成する。

Direct3DRMMeshBuilder3.Optimize

Direct3DRMMeshBuilder3

現在のデバイスに対してDirect3DRMMeshBuilder3オブジェクトを最適化する。この操作は高価になることがある。

構文

object.Optimize( )
object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.Save

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトを保存する。

構文

object.Save(fname As String,
  xFormat As CONST_D3DRMXOFFORMAT,
  Save As CONST_D3DRMSAVEFLAGS)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
fname
作成されるファイルの名前。このファイルのファイル名拡張子は、.xでなければならない。
xFormat
CONST_D3DRMXOFFORMAT列挙型のD3DRMXOF_TEXT値。
Save
保存オプションを示すCONST_D3DRMSAVEFLAGS列挙型の1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.ScaleMesh

Direct3DRMMeshBuilder3

指定のスケーリング係数を使用してモデル座標でx軸、y軸、z軸に平行にDirect3DRMMeshBuilder3オブジェクトをスケーリングする。

構文

object.ScaleMesh(sx As Single,
  sy As Single,
  sz As Single)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
sx, sy, sz
x軸、y軸、z軸に沿って適用されるスケーリング係数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.SetColor

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのすべての面に指定の色を設定する。

構文

object.SetColor(col As Long)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
col
面の色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。色は4バイトのLongで表される。高バイトはアルファ要素であり、後続のバイトが赤、緑、青を定義する。より簡単に色を構築するにはDirectX7オブジェクトのCreateColorRGBAを使い、フルアルファを希望しているだけの場合はSetColorRGBを使う。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.SetColorRGB

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのすべての面に赤、緑、青の色要素を設定する。

構文

object.SetColorRGB(red As Single,
  green As Single,
  blue As Single)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
red, green, blue
色の赤、緑、青の各成分。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.SetColorSource

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの色ソースを設定する。

構文

object.SetColorSource(val As CONST_D3DRMCOLORSOURCE)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
val
使用する新しい色ソース指定するCONST_D3DRMCOLORSOURCE列挙型のメンバ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.GetColorSource

Direct3DRMMeshBuilder3.SetMaterial

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのすべての面のマテリアルを設定する。

構文

object.SetMaterial(mat As Direct3DRMMaterial2)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
mat
Direct3DRMMeshBuilder3オブジェクトのDirect3DRMMaterial2インターフェイス。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.SetNormal

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の法線ベクトルを設定する。

構文

object.SetNormal(idx As Long,
  x As Single,
  y As Single,
  z As Single)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
idx
設定する法線のインデックス。
x, y, z
指定の法線に割り当てるベクトルのx、y、ｚの各要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.SetPerspective

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに対するパースペクティブ補正テクスチャマッピングを有効または無効にする。

構文

object.SetPerspective(perspectiveEnabled As CONST_DBOOLFLAGS)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
perspectiveEnabled
メッシュをパースペクティブ補正でテクスチャマップする必要があればD_TRUEを、そうでなければD_FALSEを指定する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.SetQuality

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのレンダリングクオリティを設定する。

構文

object.SetQuality(q As CONST_D3DRMRENDERQUALITY)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
q
使用する新しいレンダリングクオリティを指定するCONST_D3DRMRENDERQUALITY列挙型のメンバ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

オブジェクトクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーロー。フォンは実装されておらず、デフォルトでグーローシェーディングになる)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

デバイスのクオリティを設定するには、Direct3DRMDevice3.SetQualityを用いる。デフォルトで、デバイスクオリティはD3DRMRENDER_FLAT (フラットシェーディング、照明オンおよびソリッド塗りつぶし) である。

Direct3DRMMeshBuilder3オブジェクトのクオリティを設定するには、SetQualityメソッドを用いる。デフォルトで、Direct3DRMMeshBuilder3オブジェクトのクオリティはD3DRMRENDER_GOURAUD (グーローシェーディング、照明オンおよびソリッド塗りつぶし) である。

ヒント: グーローシェーディングは、詳細レベルを頻繁にまたはすばやく変更するプログレッシブメッシュオブジェクトについて、フォンシェーディングよりもよいパフォーマンスを得られる。

Direct3D保持モードは、デバイスやオブジェクトの個々のコンポーネントに対する現在の設定の中で最も低位のクオリティで、オブジェクトにレンダリングを行う。たとえば、オブジェクトの現在のクオリティ設定がD3DRMRENDER_GOURAUDで、デバイスがD3DRMRENDER_FLATであると、オブジェクトはフラットシェーディング、ソリッド塗りつぶし、および照明オンでレンダリングされる。

オブジェクトの現在のクオリティ設定がD3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAMEで、デバイスのクオリティ設定がD3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINTであると、オブジェクトはフラットシェーディング、照明オフ、およびポイント塗りつぶしモードでレンダリングされる。

これらのルールは、Direct3DRMMeshBuilder3オブジェクトおよびDirect3DRMProgressiveMeshオブジェクトに適用される。しかし、Direct3DRMMeshオブジェクトはこれらのルールに従わない。メッシュオブジェクトはデバイスのクオリティ設定を無視し、グループクオリティ設定を用いる(デフォルトでD3DRMRENDER_GOURAUD)。

参照

Direct3DRMMeshBuilder3.GetQuality

Direct3DRMMeshBuilder3.SetTexture

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのすべての面のテクスチャを設定する。

構文

object.SetTexture(tex As Direct3DRMTexture3)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
tex
必要なDirect3DRMTexture3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.SetTextureCoordinates

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点のテクスチャ座標を設定する。

構文

object.SetTextureCoordinates(idx As Long,
  u As Single,
  v As Single)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
idx
設定する頂点のインデックス。
u, v
T指定のメッシュ頂点に割り当てるテクスチャ座標。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.GetTextureCoordinates

Direct3DRMMeshBuilder3.SetTextureTopology

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのテクスチャトポロジを設定する。

構文

object.SetTextureTopology(wrap_u As CONST_DBOOLFLAGS,
  wrap_v As CONST_DBOOLFLAGS)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
wrap_u, wrap_v
テクスチャトポロジを示す値。円筒形トポロジを、それぞれu次元およびv次元でテクスチャに持たせたい場合、この2つのパラメータの、少なくとも一方にD_TRUEを、そうでない場合には、D_FALSEを指定する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

テクスチャトポロジフラグ、wrap_u、wrap_vは Direct3D直接モードレンダリング状態D3DRENDERSTATE_WRAPU、D3DRENDERSTATE_WRAPVの設定を制御する。ラッピングフラグがD_TRUEのとき、ラスタライザは、それが2つのテクスチャ座標間で短い方のパスであれば、テクスチャの1つの辺から反対側の辺に横断 (トロイダルマッピング) する。

1つの辺に沿って0.1から0.9の範囲のv座標を持つ三角形があるとする。WRAPVがD_FALSEであれば、テクスチャのほぼ全長が三角形に沿ってレンダリングされる。WRAPVがD_TRUEであれば、テクスチャの上部と下部のスライバがレンダリングされる。さらに、ラッピングフラグがD_TRUEのとき、テクスチャ座標の一部分だけが1.0より大きい値を持つとみなされるため、ラップがD_TRUEのときテクスチャは面に沿ってタイル化されないことになる。

ラッピング動作の制御は、テクスチャ座標の正しい解釈にとって必要である。単一のテクスチャが多くの面に沿ってラップされている場合、wrap_uとwrap_vパラメータをD_TRUEにセットする。モデルが面当たり1つのテクスチャしか持たないか、または1より大きいテクスチャ座標を使用してテクスチャの複数のコピーを単一の面に沿ってタイル化する場合、wrap_uとwrap_vをD_FALSEにセットする。

いくつかのインターフェイスは、SetTextureTopologyメソッドをエクスポーズする。Direct3DRMMeshBuilder3.SetTextureTopologyは、すべての要素面上のトポロジを更新し、Direct3DRMFace2.SetTextureTopologyによる設定をオーバーライドする。デフォルトでは、Direct3DRMFrame3.SetTextureTopologyは、デフォルトのマテリアルモードがD3DRMMATERIAL_FROMMESHであるため、メッシュを読み込む。マテリアルモードがD3DRMMATERIAL_FROMMESHでない場合、Direct3DRMFrame3.SetTextureTopologyはDirect3DRMMeshBuilder3.SetTextureTopologyによる設定をオーバーライドする。

Direct3DRMMeshBuilder3.SetVertex

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の位置を設定する。

構文

object.SetVertex(idx As Long,
  x As Single,
  y As Single,
  z As Single)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
idx
設定する頂点のインデックス。
x, y, z
指定の頂点に割り当てる位置のx、y、zの各要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.SetVertexColor

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の色を設定する。

構文

object.SetVertexColor(idx As Long,
  c As Long)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
idx
設定する頂点のインデックス。
c
指定の頂点に割り当てる色。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMMeshBuilder3.GetVertexColor

Direct3DRMMeshBuilder3.SetVertexColorRGB

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の赤、緑、青の色要素を設定する。

構文

object.SetVertexColorRGB(idx As Long,
  r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
idx
設定する頂点のインデックス。
r, g, b
指定の頂点に割り当てる色の赤、緑、青の各成分。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshBuilder3.Translate

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの頂点の位置に指定のオフセットを追加する。

構文

object.Translate(tx As Single,
  ty As Single,
  tz As Single)

要素

object
Direct3DRMMeshBuilder3オブジェクトを表すオブジェクト式。
tx, ty, tz
各頂点位置のx座標、y座標、z座標に追加されるオフセット。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMMeshInterpolator

インターポレータは、アクションを格納した後、中間値を自動計算して、オブジェクトにアクションを適用する方法を提供する。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、さらに、ほかのさまざまな変換も行うことができる。

Direct3DRMMeshオブジェクトは、Direct3DRMMeshInterpolatorオブジェクトにアタッチできる。インターポレータの詳細については、追加情報の「インターポレータ」を参照すること。

Direct3DRMMeshInterpolatorインターフェイスには、次のメソッドが含まれる。

オブジェクトのアタッチ | AttachObject
DetachObject
GetAttachedObjects
色 | SetGroupColor
SetGroupColorRGB
補間の実行 | GetIndex
Interpolate
SetIndex
その他 | Translate
頂点位置 | SetVertices

さらに、Direct3DRMMeshInterpolatorは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMeshInterpolator.AttachObject

Direct3DRMMeshInterpolator

オブジェクトをインターポレータに接続する。

構文

object.AttachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータにアタッチするDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アタッチされるオブジェクトは、別のインターポレータでも、インターポレータがxInterpolator型となるタイプxのオブジェクトでも良い。たとえば、Direct3DRMMeshオブジェクトは、Direct3DRMMeshInterpolatorオブジェクトにアタッチできる。

Direct3DRMMeshInterpolator.DetachObject

Direct3DRMMeshInterpolator

インターポレータからオブジェクトのアタッチを解除する。

構文

object.DetachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータからアタッチを外すDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshInterpolator.GetAttachedObjects

Direct3DRMMeshInterpolator

インターポレータに現在アタッチされているオブジェクトを取得する。

構文

object.GetAttachedObjects( ) As Direct3DRMObjectArray

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。

戻り値

Direct3DRMObjectArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshInterpolator.GetIndex

Direct3DRMMeshInterpolator

インターポレータの現在の内部インデックス（時間）を取得する。

構文

object.GetIndex( ) As Single

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。

戻り値

インターポレータの現在の内部インデックスを含む値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMMeshInterpolator.Interpolate

Direct3DRMMeshInterpolator

インターポレータに格納されているキー間を補間して、一連のアクションを生成する。その後、アクションは、指定のオブジェクトに適用される。オブジェクトの指定がなければ、アクションは、現在アタッチされているオブジェクトに適用される。

構文

object.Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの現在の内部インデックスを含む値。
mObject
Direct3DRMObjectオブジェクト。このオブジェクトは、インターポレータに格納されているすべてのプロパティに対する補間値を割り当てるオブジェクトを表す。このポインタはNOTHINGでも良い。その場合、すべてのアタッチされているオブジェクトのプロパティ値には、補間値がセットされる。
options
実行する補間の種類を制御するCONST_D3DRMINTERPOLATIONFLAGS列挙型の値の1つ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshInterpolator.SetGroupColor

Direct3DRMMeshInterpolator

Direct3DRMMeshInterpolatorオブジェクトにカラーキーを追加する。

構文

object.SetGroupColor(id As Long,
  val As Long)

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupを使って生成されたものでなくてはならない。
val
グループの色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。色は4バイトのLongで表される。高バイトはアルファ要素であり、後続のバイトが赤、緑、青を定義する。より簡単に色を構築するにはDirectX7オブジェクトのCreateColorRGBAを使い、フルアルファを希望しているだけの場合はSetColorRGBを使う。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshInterpolator.SetGroupColorRGB

Direct3DRMMeshInterpolator

Direct3DRMMeshInterpolatorオブジェクトにグループRGBキーを追加する。

構文

object.SetGroupColorRGB(id As Long,
  r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupを使って生成されたものでなくてはならない。
r, g, b
グループカラーの赤、緑、青の色要素。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshInterpolator.SetIndex

Direct3DRMMeshInterpolator

インターポレータの内部インデックス（時間）に指定の値をセットする。他のインターポレータがそのインターポレータにアタッチされていれば、このメソッドは、再帰的にそれらのインデックスを同じ値に同期させる。

構文

object.SetIndex(val As Single)

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの内部インデックスに対してセットされる時間。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMMeshInterpolator.SetVertices

Direct3DRMMeshInterpolator

Direct3DRMMeshInterpolatorオブジェクトに頂点位置キーを追加する。

構文

object.SetVertices(id As Long,
  idx As Long,
  count As Long,
  vertexArray() As D3DRMVERTEX)

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。
id
グループの識別子。この識別子はDirect3DRMMesh.AddGroupメソッドを使って生成されたものでなくてはならない。
idx
修正するメッシュグループの最初の頂点のインデックス。
count
セットする連続頂点の数。vertexArray配列は、少なくともcount数の要素を格納しなければならない。
vertexArray
設定する頂点位置を示すD3DRMVERTEX型の配列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMMeshInterpolator.Translate

Direct3DRMMeshInterpolator

Direct3DRMMeshInterpolatorオブジェクト中の頂点の位置に、指定されたオフセットを追加する。

構文

object.Translate(tx As Single,
  ty As Single,
  tz As Single)

要素

object
Direct3DRMMeshInterpolatorオブジェクトを表すオブジェクト式。
tx, ty, tz
各頂点位置のx座標、y座標、z座標に追加されるオフセット。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMObject

アプリケーションは、Microsoft® Direct3D® 保持モードオブジェクトのスーパークラスとやりとりするために、Direct3DRMObjectインターフェイスのメソッドを使用する。

Direct3DRMObjectは、システム中のすべてのオブジェクトの共通スーパークラスである。Direct3DRMObjectオブジェクトには、すべてのオブジェクトに共通する特性がある。

オブジェクトを作成するには、アプリケーションは、最初に、Direct3D保持モードオブジェクトをインスタンス化しなければならない。次に、アプリケーションは、オブジェクトを作成するオブジェクトのインターフェイスメソッドを呼び出し、オブジェクトに固有のパラメータを指定する。たとえば、Direct3DRMAnimationオブジェクトを作成するには、アプリケーションはDirect3DRM3.CreateAnimationメソッドを呼び出すことになる。次に、作成メソッドは新しいオブジェクトを作成し、パラメータ中で (その他すべてはデフォルト値のまま) 渡されるデータのオブジェクト属性のいくつかを初期化し、オブジェクトを返す。次に、アプリケーションは、このオブジェクトのインターフェイスを指定し、オブジェクトを修正および使用することができる。

任意のオブジェクトは、アプリケーション固有データの32ビットを格納することができる。このデータを保持モードで解釈または変更できない。アプリケーションは、Direct3DRMObject.GetAppDataメソッドを使用してこのデータを読み込み、Direct3DRMObject.SetAppDataメソッドを使用してこのデータに書き込みすることができる。アプリケーションがDirect3DRMFrameの各オブジェクトの構造体を保持していれば、このデータの検索は簡単になる。たとえば、Direct3DRMFrame3.GetParentメソッドの呼び出しでDirect3DRMFrameオブジェクトを取得する場合、アプリケーションはそのプライベート構造体にアクセスして、データを簡単に取り出し、時間のかかる検索を避けることができる。

アプリケーションを編成する支援のために、またはアプリケーションのユーザインターフェイスの一部として、名前をオブジェクトに割り当てたい場合もあると思われる。Direct3DRMObject.SetNameとDirect3DRMObject.GetNameメソッドを使用して、オブジェクト名をセットし、取得することができる。

アプリケーション固有データの可能な用途のもう1つの例は、アプリケーションでメッシュ内の面をサブセット (たとえば、前面と後面) にグループ化する必要がある場合である。面の中のアプリケーションデータを使用して、面をこれらのグループのどこに入れるかを注記することができる。

アプリケーションでは、オブジェクトが破棄された場合に呼び出す関数を指定することができる。たとえば、アプリケーションでオブジェクトに関連付けられたメモリの割り当て解除を行う必要がある場合などである。このためには、Direct3DRMObject.AddDestroyCallbackメソッドを使用する。このメソッドで以前に登録した関数を削除するには、Direct3DRMObject.DeleteDestroyCallbackメソッドを使用する。

コールバックは、オブジェクトが破棄され、システムがオブジェクトのメモリ割り当てを解除しようとした場合にのみ呼び出される。アプリケーションがオブジェクトに関する追加データを保持している場合 (たとえば、ダイナミックスを実装するために)、アプリケーションはデータの処理が可能であることを自分自身に通知する手段として、このコールバックを使用することができる。

Direct3DRMObjectインターフェイスのメソッドは、以下のグループにまとめることができる。

アプリケーション固有のデータ | GetAppData
SetAppData
複製 | CloneObject
名前 | GetClassName
GetName
SetName
通知 | AddDestroyCallback
DeleteDestroyCallback

すべての保持モードオブジェクトは、Direct3DRMObjectインターフェイスメソッドを継承する。

Direct3DRMObject.AddDestroyCallback

Direct3DRMObject

オブジェクトが破棄されるときに呼び出される関数を登録する。

このメソッドは実装されていない。

構文

object.AddDestroyCallback(fn As Direct3DRMCallback,
  arg As Variant)

要素

object
Direct3DRMObjectオブジェクトを表すオブジェクト式。
fn
オブジェクトが破棄されるときに使われる、ユーザ定義のDirect3DRMCallbackコールバックインターフェイス。
arg
コールバックに渡されるアプリケーション定義データ。この関数はオブジェクトが破棄された後に使われるため、引数としてオブジェクトと共に使用してはならない。

エラー値

このメソッドはE_NOTIMPLを返す。

Direct3DRMObject.CloneObject

Direct3DRMObject

オブジェクトの複製を作成する。

構文

object.CloneObject( ) As Direct3DRMObject

要素

object
Direct3DRMObjectオブジェクトを表すオブジェクト式。

戻り値

オブジェクトの複製を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMObject.DeleteDestroyCallback

Direct3DRMObject

Direct3DRMObject.AddDestroyCallbackメソッドによって登録された関数を削除する。

このメソッドは実装されていない。

構文

object.DeleteDestroyCallback(fn As Direct3DRMCallback,
  args As Variant)

要素

object
Direct3DRMObjectオブジェクトを表すオブジェクト式。
fn
オブジェクトが破棄されるときに使われる、ユーザ定義のDirect3DRMCallbackインターフェイス。
args
コールバックに渡されるアプリケーション定義データ。

エラー値

このメソッドはE_NOTIMPLを返す。

Direct3DRMObject.GetAppData

Direct3DRMObject

オブジェクトから、アプリケーション固有の32ビットデータを取得する。データのデフォルト値は0である。

構文

object.GetAppData( ) As Long

要素

object
Direct3DRMObjectオブジェクトを表すオブジェクト式。

戻り値

アプリケーションによって定義されたデータ値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMObject.SetAppData

Direct3DRMObject.GetClassName

Direct3DRMObject

オブジェクトのクラス名を取得する。

構文

object.GetClassName( ) As String

要素

object
Direct3DRMObjectオブジェクトを表すオブジェクト式。

戻り値

クラス名を識別する文字列を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMObject.GetName

Direct3DRMObject

オブジェクト名を取得する。

構文

object.GetName( ) As String

要素

object
Direct3DRMObjectオブジェクトを表すオブジェクト式。

戻り値

オブジェクトを識別する文字列を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMObject.SetName

Direct3DRMObject.SetAppData

Direct3DRMObject

オブジェクトにアプリケーション固有の32ビットデータを設定する。

構文

object.SetAppData(data As Long)

要素

object
Direct3DRMObjectオブジェクトを表すオブジェクト式。
data
オブジェクトに格納されるユーザ定義のデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMObject.GetAppData

Direct3DRMObject.SetName

Direct3DRMObject

オブジェクトの名前を設定する。

構文

object.SetName(name As String)

要素

object
Direct3DRMObjectオブジェクトを表すオブジェクト式。
name
オブジェクトの名前を示すユーザ定義のデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMObject.GetName


Direct3DRMObjectArray

アプリケーションは、Direct3DRMObjectオブジェクトをグループ化するためにDirect3DRMObjectArrayインターフェイスのメソッドを利用する。オブジェクト配列は、0が基準になっている (0～N-1)。

Direct3DRMObjectArrayインターフェイスは、次のメソッドをサポートする。

  • GetElement
  • GetSize

Direct3DRMObjectArrayオブジェクトは、インターポレータオブジェクト上のGetAttachedObjectsの呼び出しによって取得される。

Direct3DRMObjectArray.GetElement

Direct3DRMObjectArray

Direct3DRMObjectArrayオブジェクトから指定された要素を取得する。

構文

object.GetElement(index As Long) As Direct3DRMObject

要素

object
Direct3DRMObjectArrayオブジェクトを表すオブジェクト式。
index
配列要素。

戻り値

Direct3DRMObjectオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMObjectArray.GetSize

Direct3DRMObjectArray

Direct3DRMObjectArrayオブジェクトに含まれている要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMObjectArrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMPick2Array

アプリケーションは、ピックオブジェクトをグループ化し、より多くの情報を返すために、Direct3DRMPick2Arrayインターフェイスのメソッドを利用する。ピック配列は、0が基準になっている (0～N-1)。ピックの詳細については、「Direct3DRMPickArray」を参照すること。

Direct3DRMFrame3.RayPickメソッドを使用して、Direct3DRMPick2Arrayオブジェクトを取得する。次に、Direct3DRMPick2Array.GetPickFrameメソッドを呼び出して、Direct3DRMFrameArray インターフェイス、ビジュアルオブジェクト、および光線が交差するオブジェクトに関する情報を取得することができる。この情報には、面とグループの識別子、ピック位置、およびオブジェクトの頂点、頂点法線、色に対する水平と垂直テクスチャ座標が含まれる。フレームの配列は、ビジュアルオブジェクトに通じる階層へのパスである。

Direct3DRMPick2Arrayインターフェイスは、次のメソッドをサポートする。

  • GetPickFrame
  • GetPickVisual
  • GetSize

Direct3DRMPick2Arrayオブジェクトは、Direct3DRMFrame3.RayPickメソッドの呼び出しによって取得される。

Direct3DRMPick2Array.GetPickFrame

Direct3DRMPick2Array

指定されたピックによって交差するDirect3DRMFrameArrayオブジェクトを取得する。

構文

object.GetPickFrame(index As Long,
  pickDesc As D3DRMPICKDESC2) As Direct3DRMFrameArray

要素

object
Direct3DRMPick2Arrayオブジェクトを表すオブジェクト式。
index
情報を取得するピックを識別する、ピック配列へのインデックス。
pickDesc
面やグループの識別子、ピックの位置、頂点の水平および垂直テクスチャ座標、頂点の法線および交差したオブジェクトの色が指定するD3DRMPICKDESC2型。

戻り値

指定されたピックに関連付けられたDirect3DRMFrameArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、D3DRMPICKDESC型ではなくD3DRMPICKDESC2型のu値とv値を取得する点を除けば、Direct3DRMPickedArray.GetPickFrameと類似している。

参照

Direct3DRMFrame3.RayPick

Direct3DRMPick2Array.GetPickVisual

Direct3DRMPick2Array

指定されたピックによって交差したDirect3DRMVisualオブジェクトを取得する。

構文

object.GetPickVisual(index As Long,
  pickDesc As D3DRMPICKDESC2) As Direct3DRMVisual

要素

object
Direct3DRMPick2Arrayオブジェクトを表すオブジェクト式。
index
情報を取得するピックを識別する、ピック配列へのインデックス。
pickDesc
面やグループの識別子、ピックの位置、頂点の水平および垂直テクスチャ座標、頂点の法線および交差したオブジェクトの色が指定するD3DRMPICKDESC2型。

戻り値

指定されたピックに関連付けられたDirect3DRMVisualオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、D3DRMPICKDESC型ではなくD3DRMPICKDESC2型のu値とv値を取得する点を除けば、Direct3DRMPickArray.GetPickVisualと類似している。

参照

Direct3DRMFrame3.RayPick

Direct3DRMPick2Array.GetSize

Direct3DRMPick2Array

Direct3DRMPick2Arrayオブジェクトに含まれる要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMPick2Arrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMPickArray

アプリケーションは、Direct3DRMPickArrayインターフェイスのメソッドを使用して、ピックオブジェクトをグループ化する。ピック配列は、0が基準になっている (0～N-1)。

ピッキングは、ビューポート中で2D座標またはフレーム中でベクトルが与えられたときに、シーン上のビジュアルを検索するプロセスである。光線ピックについては、「Direct3DRMPick2Array」を参照すること。

Direct3DRMViewport2.Pickメソッドを使用して、Direct3DRMPickArrayオブジェクトを取得する。次に、Direct3DRMPickArray.GetPickFrameメソッドを呼び出して、Direct3DRMFrameArrayインターフェイスとビジュアルオブジェクトを取得することができる。フレームの配列は、階層を経てビジュアルオブジェクトに通じるパスである。これは、つまり、階層中の最上部の親が配列の最初にくるビジュアルオブジェクトの親フレームの階層リストである。

Direct3DRMPickArrayインターフェイスは、次のメソッドをサポートする。

  • GetPickFrame
  • GetPickVisual
  • GetSize

Direct3DRMPickArrayオブジェクトは、Direct3DRMViewport2.Pickメソッドの呼び出しによって取得される。

Direct3DRMPickArray.GetPickFrame

Direct3DRMPickArray

指定されたピックによって交差するDirect3DRMFrameArrayオブジェクトを取得する。

構文

object.GetPickFrame(index As Long,
  pickDesc As D3DRMPICKDESC) As Direct3DRMFrameArray

要素

object
Direct3DRMPickArrayオブジェクトを表すオブジェクト式。
index
情報を取得するピックを識別する、ピック配列へのインデックス。
pickDesc
ピックの位置、面、取得するオブジェクトのグループ識別子を指定するD3DRMPICKDESC型。

戻り値

指定されたピックに関連付けられたDirect3DRMFrameArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.Pick

Direct3DRMPickArray.GetPickVisual

Direct3DRMPickArray

指定されたピックによって交差するDirect3DRMVisualオブジェクトを返す。

構文

object.GetPickVisual(index As Long,
  pickDesc As D3DRMPICKDESC) As Direct3DRMVisual

要素

object
Direct3DRMPickArrayオブジェクトを表すオブジェクト式。
index
情報を取得するピックを識別する、ピック配列へのインデックス。
pickDesc
ピックの位置、面、取得するオブジェクトのグループ識別子を指定するD3DRMPICKDESC型。

戻り値

指定されたピックに関連付けられたDirect3DRMVisualオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.Pick

Direct3DRMPickArray.GetSize

Direct3DRMPickArray

Direct3DRMPickArrayオブジェクトに含まれている要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMPickArrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMProgressiveMesh

メッシュは、ポリゴン面のセットから構成されるビジュアルオブジェクトである。メッシュは、頂点のセットと面のセットを定義する。メッシュの詳細については、「Direct3DRMMesh」を参照すること。

プログレッシブメッシュは、ベースメッシュ (粗いバージョン) およびメッシュをさらに精製するために使用される頂点分割レコードのセットとして格納されるメッシュである。つまり、プログレッシブな精製が可能である。これによって、メッシュ用のレンダリングの詳細レベルをセットし、リモートソースからのプログレッシブダウンロードも可能になる。

プログレッシブメッシュは、Microsoft® Direct3D®保持モードのビジュアルであり、ビジュアル処理の標準的な方法で使用することができる。つまり、プログレッシブメッシュは、フレーム階層に追加すること、複数回のインスタンス化、およびピックも可能である。

Direct3DRMProgressiveMeshインターフェイスのメソッドを使用して、レンダリングする頂点または面の数をセットし、レンダリング詳細を制御することができる。レンダリングに必要な最小詳細レベルを指定することもできる。通常、プログレッシブメッシュは、ベースメッシュが一度使用可能になるとレンダリングされるが、Direct3DRMProgressiveMesh.SetMinRenderDetailメソッドによってレンダリングの前にそれ以上の詳細レベルが必要であると指定することができる。また、Direct3DRMProgressiveMesh.CreateMeshメソッドを使用して、プログレッシブメッシュ固有の状態からDirect3DRMMeshオブジェクトを構築することもできる。

プログレッシブメッシュを、ファイル、リソース、メモリ、またはURLからロードすることができる。ローディングは同期式でも非同期式でも行える。ダウンロードの状態はDirect3DRMProgressiveMesh.GetLoadStatusメソッドによってチェックし、Direct3DRMProgressiveMesh.Abortメソッドでダウンロードを終了することができる。ローディングが非同期式の場合、ロードの進行状態を調べるためにDirect3DRMProgressiveMesh.RegisterEventsとDirect3DRMProgressiveMesh.GetLoadStatusメソッドを介してイベントを使用するかどうかはアプリケーション次第である。

Direct3DRMProgressiveMeshオブジェクトは、Direct3DRM3.CreateProgressiveMeshメソッドを使うことによって作成される。作成後、オブジェクトは階層に追加できるが、少なくともベースメッシュが使用可能になるまで、レンダリングされない。

Direct3DRMProgressiveMeshインターフェイスのメソッドは、以下のグループにまとめることができる。

メッシュの生成とコピー | CreateMesh
 | Duplicate
 | GetBox
ロード | Abort
 | GetLoadStatus
 | LoadFromFile
クオリティの設定 | SetQuality
 | GetQuality
詳細の管理 | GetDetail
 | GetFaceDetail
 | GetFaceDetailRange
 | GetVertexDetail
 | GetVertexDetailRange
 | SetDetail
 | SetFaceDetail
 | SetMinRenderDetail
 | SetVertexDetail
イベントの登録 | RegisterEvents

Direct3DRMProgressiveMeshインターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMProgressiveMesh.Abort

Direct3DRMProgressiveMesh

現在アクティブなダウンロードを中止する。

構文

object.Abort( )

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドが使われる前にベースメッシュがダウンロードされている場合、その効果は、プログレッシブメッシュがロードされ、分割頂点が有効な状態にあり、プログレッシブメッシュがレンダリング可能である場合と同じである。他のプログレッシブメッシュメソッドも使うことができる。Direct3DRMProgressiveMesh.Abortを呼び出す前にベースメッシュがダウンロードされておらず、シーンにプログレッシブメッシュを追加した場合、Direct3DRMViewport2.Renderメソッドは成功するが、プログレッシブメッシュへのレンダリングは行われない。また、プログレッシブメッシュを使用するとき (たとえば、メッシュやクローンを作成するため) にベースメッシュがダウンロードされていなければ、呼び出しはD3DRMERR_NOTENOUGHDATAを返す。

未解決のイベントがあれば、それらが通知される。

Direct3DRMProgressiveMesh.CreateMesh

Direct3DRMProgressiveMesh

現在の詳細レベルでメッシュを構築する。

構文

object.CreateMesh( ) As Direct3DRMMesh

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。

戻り値

新しく生成されたDirect3DRMMeshオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アプリケーションがまだ使用可能になっていない詳細レベルを要求したり、ベースメッシュが使用可能になっていない場合、このメソッドはD3DRMERR_NOTENOUGHDATAというエラーを返す。

Direct3DRMProgressiveMesh.Duplicate

Direct3DRMProgressiveMesh

Direct3DRMProgressiveMeshオブジェクトのコピーを作成する。このコピーは、オリジナルと幾何図形や面データをすべて共有する。しかし、オリジナルとは別に詳細レベルを設定することができる。これは、同一のメッシュデータを階層の異なる部分で、ただし、異なる詳細レベルで使用できるようにする。本質的に、フレーム階層内にプログレッシブメッシュの2つのインスタンスがあると言える。

構文

object.Duplicate( ) As Direct3DRMProgressiveMesh

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。

戻り値

新しく生成されるDirect3DRMProgressiveMeshオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

複製中のプログレッシブメッシュには、少なくともそのベースメッシュをロードしておかなければならない。現在、非同期でロード中のプログレッシブメッシュ上でこのメソッドを使うと、複製されたメッシュはロードしているプログレッシブメッシュが複製されたときに持っていた詳細レベルしか持たない。複製後にロードされた分割頂点は、複製されたメッシュでは利用できない。

プログレッシブメッシュは、ベースメッシュを表すデータセットと、分割頂点を表すデータセットを持っている。ベースメッシュデータおよびプログレッシブメッシュの現状や現在の詳細レベルを記述するデータは、複製されたメッシュ間で共有されない。しかし、分割頂点データは共有される。

Direct3DRMProgressiveMesh.GetBox

Direct3DRMProgressiveMesh

Direct3DRMProgressiveMeshオブジェクトを含む境界ボックスを取得する。境界ボックスは、各次元で、子フレームを基準とする最小および最大の座標を与える。

構文

object.GetBox(box As D3DRMBOX)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
box
境界ボックスの座標がセットされるD3DRMBOX型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMProgressiveMesh.GetDetail

Direct3DRMProgressiveMesh

0.0と1.0の間に正規化された現在の詳細レベルのプログレッシブメッシュを返す。

構文

object.GetDetail( ) As Single

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。

戻り値

現在の詳細レベルのプログレッシブメッシュがセットされる値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

ベースメッシュがダウンロードされていなければ、このメソッドは、D3DRMERR_PENDINGを返す。要求されている詳細レベルが設定されていれば、戻り値は、要求レベルが満たされるまで以降の呼び出し毎に増加される。レベルが要求されていなければ、詳細レベルは、すべての分割頂点のダウンロードが完了するまで上昇する。

正規化された値0.0は頂点の最小数を表し (ベースメッシュ中の頂点数)、正規化された値1.0は頂点の最大数を表す。

Direct3DRMProgressiveMesh.GetFaceDetail

Direct3DRMProgressiveMesh

プログレッシブメッシュにある面の数を取得する。

構文

object.GetFaceDetail( ) As Long

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。

戻り値

プログレッシブメッシュの面の数がセットされる値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

面の数が利用できなければ、このメソッドはD3DRMERR_PENDINGを返す。

Direct3DRMProgressiveMesh.GetFaceDetailRange

Direct3DRMProgressiveMesh

プログレッシブメッシュで使用可能な最小および最大の面カウントを取得する。

構文

object.GetFaceDetailRange(min As Long,
  max As Long)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
min
面の最小数がセットされる値。
max
面の最大数がセットされる値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

面カウントが取得できない場合、このメソッドはD3DRMERR_PENDINGを返す。

Direct3DRMProgressiveMesh.GetLoadStatus

Direct3DRMProgressiveMesh

ロードの現在の状態をアプリケーションが照会することを可能にする。

構文

object.GetLoadStatus(loadStatus As D3DRMPMESHLOADSTATUS)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
loadStatus
プログレッシブメッシュのロード状態を示すD3DRMPMESHLOADSTATUS型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMProgressiveMesh.GetQuality

Direct3DRMProgressiveMesh

プログレッシブメッシュのレンダリングクオリティを示す値を取得する。

構文

object.GetQuality( ) As CONST_D3DRMRENDERQUALITY

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。

戻り値

プログレッシブメッシュのレンダリングクオリティを指定するCONST_D3DRMRENDERQUALITY列挙型のメンバを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMProgressiveMesh.SetQuality

Direct3DRMProgressiveMesh.GetVertexDetail

Direct3DRMProgressiveMesh

プログレッシブメッシュにある頂点の数を取得する。

構文

object.GetVertexDetail( ) As Long

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。

戻り値

プログレッシブメッシュにある頂点の数がセットされる値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

頂点の数が取得できない場合、このメソッドはD3DRMERR_PENDINGを返す。

Direct3DRMProgressiveMesh.GetVertexDetailRange

Direct3DRMProgressiveMesh

メッシュ中で使用可能な最小および最大の頂点カウントを取得する

構文

object.GetVertexDetailRange(min As Long,
  max As Long)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
min
頂点の最小数がセットされる値。
max
頂点の最大数がセットされる値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

頂点カウントが取得できない場合、このメソッドはD3DRMERR_PENDINGを返す。

Direct3DRMProgressiveMesh.LoadFromFile

Direct3DRMProgressiveMesh

プログレッシブメッシュオブジェクトをメモリ、ファイル、リソース、またはURLからロードする。ロードは同期式でも非同期式でも良い。

構文

object.LoadFromFile(sFile As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As Object)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
sFile
ロードするオブジェクトのソース。このソースは、optionsパラメータで指定されているソースフラグによって、ファイル、リソース、メモリブロック、またはストリームのどれかにできる。
id
ロードするオブジェクトの名前または位置。idが""の場合は、optionsパラメータをD3DRMLOAD_FIRSTに設定する。Microsoft Visual Basic® は、String データ型が指定されている場合でも、ロードするアイテムの位置を示すidパラメータの中のIntegerを受け入れる。たとえば、idパラメータに1が設定されていると、1番目の位置のオブジェクトがロードされる。
options
ロードを実行する方法を記述するCONST_D3DRMLOADFLAGS列挙型の1つ以上の値。
loadTextureImplementation
Direct3DRMLoadTextureCallback3コールバックインターフェイス。遭遇した任意のテクスチャをロードするのに使用される。テクスチャは、2で割れる幅と長さでなければならない。このコールバックは、ローダが遭遇したテクスチャ名と、ユーザ定義のargsパラメータによって使われる。新しいスレッドは、このコールバックに対しては生成されない。
userArgument
コールバックに渡されるユーザ定義データ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

プログレッシブメッシュは、初期化しない限り有効にならない。非同期式ダウンロードが指定されていれば、このAPIは直ちに戻り、別のスレッドがダウンロードを実行するために生成される。ロードの進行状態を調べるために、Direct3DRMProgressiveMesh.RegisterEventsとDirect3DRMProgressiveMesh.GetLoadStatusを使ってイベントを使用するかどうかはアプリケーション次第である。

このメソッドとDirect3DRMProgressiveMesh.Duplicateメソッドは、プログレッシブメッシュを初期化する。オブジェクトは一度しか初期化できない。したがって、プログレッシブメッシュをクローンまたは複製してから、そのクローンまたは複製したメッシュにロードすることも、以前にロードしたメッシュにロードすることもできない。

Direct3DRMProgressiveMesh.RegisterEvents

Direct3DRMProgressiveMesh

アプリケーションが、プログレッシブメッシュオブジェクトにイベントを登録するのを可能にする。イベントは、適切な条件が満たされたときに通知される。

構文

object.RegisterEvents(hEvent As Long,
  flags As Long,
  reserved As Long)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
hEvent
必要な条件が満たされたときに通知されるイベント。
flags
CONST_D3DRMPMESHSTATUSFLAGS列挙型の1つ以上の値。
reserved
0でなければならない。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、ロードの進行状態を監視するために使用できる。イベントは、エラーが発生した場合にも通知されるので、アプリケーションは、通知後にDirect3DRMProgressiveMesh.GetLoadStatusメソッドを使う必要がある。

Direct3DRMProgressiveMesh.SetDetail

Direct3DRMProgressiveMesh

要求された詳細レベルを0.0 (最小) と1.0 (最大) の間で正規化して設定する。

構文

object.SetDetail(detail As Single)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
detail
要求された詳細レベル。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

十分な詳細項目のダウンロードがまだ完了していなければ（ただし、時間がたてば使用可能）、要求は受け入れられて、D3DRMERR_PENDINGが返る。このエラーは通知であり、要求されたレベルが、十分な詳細が使用可能になると直ちに設定されるということを示すものである。

正規化した値0.0は頂点の最小数を表し (ベースメッシュにある頂点の数)、正規化した値1.0は頂点の最大数を表す。

Direct3DRMProgressiveMesh.SetFaceDetail

Direct3DRMProgressiveMesh

要求される面の数を設定する。

構文

object.SetFaceDetail(count As Long)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
count
要求される面の数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

ときには、常に要求された値から1以内であるにもかかわらず、プログレッシブメッシュを要求された面の数に設定できないことがある。これは、分割頂点が1ないし2面加えることができるからである。たとえば、SetFaceDetail(20)を使うと、プログレッシブメッシュは面の詳細を19または21だけにしか設定できないかもしれない。プログレッシブメッシュにある面の実際の数は、常にDirect3DRMProgressiveMesh.GetFaceDetailメソッドを使って取得することができる。

十分な詳細項目のダウンロードがまだ完了していなければ（ただし、時間がたてば使用可能）、要求は受け入れられて、D3DRMERR_PENDINGが返る。このエラーは、通知であり、要求されたレベルが、十分な詳細が使用可能になると直ちに設定されるということを示すものである。要求されている詳細レベルが、プログレッシブメッシュで使用可能な詳細レベルより大きければ、D3DRMERR_REQUESTTOOLARGEが返る。

参照

Direct3DRMProgressiveMesh.GetFaceDetail

Direct3DRMProgressiveMesh.SetMinRenderDetail

Direct3DRMProgressiveMesh

0.0（最小詳細レベル）から1.0（最大詳細レベル）の範囲で、ロード中にレンダリングする詳細の最小レベルを設定する。通常、プログレッシブメッシュは、ベースメッシュが使用可能になった（およびメッシュがシーングラフ中に存在するようになった）後でレンダリングされる。

構文

object.SetMinRenderDetail(val As Single)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
val
要求されている最小詳細。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、ロード中にレンダリングされる面または頂点の最小数を設定する。この値は、ベースメッシュで既にレンダリングされているものに追加した値である。

以降のDirect3DRMProgressiveMesh.SetDetail、Direct3DRMProgressiveMesh.SetFaceDetail、またはDirect3DRMProgressiveMesh.SetVertexDetail呼び出しはいつでも、このメソッドより優先される。

Direct3DRMProgressiveMesh.SetQuality

Direct3DRMProgressiveMesh

Direct3DRMProgressiveMeshオブジェクトのレンダリングクオリティを設定する。

構文

object.SetQuality(quality As CONST_D3DRMRENDERQUALITY)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
quality
使用する新しいレンダリングクオリティを指定するCONST_D3DRMRENDERQUALITY列挙型のメンバ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

オブジェクトクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーロー。フォンは実装されておらず、デフォルトでグーローシェーディングになる)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

デバイスのクオリティを設定するには、Direct3DRMDevice3.SetQualityを用いる。デフォルトで、デバイスクオリティはD3DRMRENDER_FLAT (フラットシェーディング、照明オンおよびソリッド塗りつぶし) である。

Direct3DRMProgressiveMeshオブジェクトのクオリティを設定するには、SetQualityメソッドを用いる。デフォルトで、Direct3DRMProgressiveMeshオブジェクトのクオリティはD3DRMRENDER_GOURAUD (グーローシェーディング、照明オンおよびソリッド塗りつぶし) である。

ヒント: グーローシェーディングは、詳細レベルを頻繁にまたはすばやく変更するプログレッシブメッシュオブジェクトについて、よりよいパフォーマンスを得られる。

Direct3D保持モードは、デバイスやオブジェクトの個々のコンポーネントに対する現在の設定の中でもっとも低位のクオリティで、オブジェクトにレンダリングを行う。たとえば、オブジェクトの現在のクオリティ設定がD3DRMRENDER_GOURAUDで、デバイスがD3DRMRENDER_FLATであると、オブジェクトはフラットシェーディング、ソリッド塗りつぶし、および照明オンでレンダリングされる。

オブジェクトの現在のクオリティ設定がD3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAMEで、デバイスのクオリティ設定がD3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINTであると、オブジェクトはフラットシェーディング、照明オフ、およびポイント塗りつぶしモードでレンダリングされる。

これらのルールは、Direct3DRMMeshBuilder3オブジェクトおよびDirect3DRMProgressiveMeshオブジェクトに適用される。しかし、Direct3DRMMeshオブジェクトはこれらのルールに従わない。メッシュオブジェクトはデバイスのクオリティ設定を無視し、グループクオリティ設定を用いる(デフォルトでD3DRMRENDER_GOURAUD)。

参照

Direct3DRMProgressiveMesh.GetRenderQuality

Direct3DRMProgressiveMesh.SetVertexDetail

Direct3DRMProgressiveMesh

要求された頂点詳細レベルを設定する。

構文

object.SetVertexDetail(count As Long)

要素

object
Direct3DRMProgressiveMeshオブジェクトを表すオブジェクト式。
count
要求されている頂点の数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

十分な詳細項目のダウンロードが、まだ完了していなければ（ただし、時間がたてば使用可能）、要求は受け入れられて、D3DRMERR_PENDINGが返る。このエラーは通知であり、要求されたレベルが、十分な詳細が使用可能になると直ちに設定されるということを示すものである。要求されている詳細レベルが、プログレッシブメッシュで使用可能な詳細レベルより大きければ、D3DRMERR_REQUESTTOOLARGEが返る。

参照

Direct3DRMProgressiveMesh.GetVertexDetail


Direct3DRMShadow2

アプリケーションは、Direct3DRMShadow2オブジェクトを初期化するためにDirect3DRM3.CreateShadowインターフェイスのメソッドを使用する。 これらの影オブジェクトは、ビジュアルとしてフレーム階層に作成および追加される。

Direct3DRMShadow2インターフェイスは、Direct3DRMObjectインターフェイスから以下のメソッドを継承する。
AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMShadow2オブジェクトは、Direct3DRM3.CreateShadowメソッドの使用によって取得される。


Direct3DRMTexture3

Direct3DRMTexture3インターフェイスは、テクスチャ管理に対するより洗練された制御を可能にする。 Changedメソッドは、テクスチャの変更リージョンを指定可能にする。また、Direct3DRMTexture3はテクスチャ管理キャッシングメソッドのGetCacheFlags、SetCacheOptions、およびGetCacheImportanceも提供する。

GenerateMIPMapメソッドは、ソースイメージからミップマップを生成する。

テクスチャを作成するときに不必要な遅延を避けるため、再利用するテクスチャは保持しておいて、必要になるたびに作成しなくて済むようにする。最適なパフォーマンスを得るには、使用するデバイスのサポートするテクスチャサーフェスフォーマットを使う。これにより、テクスチャを作成してから変更するときに、手間のかかるフォーマット変換を回避することができる。

Direct3DRMTexture3インターフェイスのメソッドは、以下のグループにまとめることができる。

色 | GetColors
SetColors
デカール | GetDecalOrigin
GetDecalScale
GetDecalSize
GetDecalTransparency
GetDecalTransparentColor
SetDecalOrigin
SetDecalScale
SetDecalSize
SetDecalTransparency
SetDecalTransparentColor
ミップマップ生成 | GenerateMIPMap
その他 | GetCacheFlags
GetCacheImportance
GetSurface
SetCacheOptions
レンダラ通知 | Changed
シェーディング | GetShades
SetShades

Direct3DRMTexture3インターフェイスは、Direct3DRMObjectインターフェイスから以下のメソッドを継承する。

AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMTexture3オブジェクトを作成するには、Direct3DRM3.CreateTextureFromSurfaceメソッドを呼び出す。

Direct3DRMTexture3.Changed

Direct3DRMTexture3

アプリケーションがテクスチャのどのリージョンを変更するかを指定できるようにする。

構文

object.Changed(flags As CONST_D3DRMTEXTURECHANGEDFLAGS,
  nRects As Long,
  rects() As RECT)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
flags
テクスチャの変更を示すCONST_D3DRMTEXTURECHANGEDFLAGS列挙型の1つ以上の値。
nRects
rects中のRECT型の数。この値が0で、flagsにD3DRMTEXTURE_CHANGEDPIXELSまたはD3DRMTEXTURE_INVALIDATEONLYが含まれる場合は、テクスチャ全体が更新される。
rects
変更されたピクセルのリージョンを記述するRECT型の配列。flagsにD3DRMTEXTURE_CHANGEDPIXELSまたはD3DRMTEXTURE_INVALIDATEONLYが含まれる場合は、rectsパラメータだけが有効である。RECTは、方形定義の型である。
Type RECT
  Bottom As Long
  Left As Long
  Right As Long
  Top As Long
End Type

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTexture3.GenerateMIPMap

Direct3DRMTexture3

単一のイメージソースからミップマップを生成する。

構文

object.GenerateMIPMap( )

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、テクスチャの作成後はいつでも呼び出すことができる。このメソッドは、レベル間の双一次フィルタリングによってソースイメージのミップマップを1×1の解像度まで生成できる。ミップマップが生成されると、マップはいつでも使用可能で、Direct3DRMTexture3.Changedを呼び出して、更新することができる。ミップマッピングを使用する場合には、Direct3DRMDevice3.SetTextureQualityを使用して、テクスチャのクオリティをD3DRMTEXTURE_MIPNEAREST、D3DRMTEXTURE_MIPLINEAR、D3DRMTEXTURE_LINEARMIPNEAREST、またはD3DRMTEXTURE_LINEARMIPLINEARに変更することを忘れてはならない。特別のミップマップレベルは、テクスチャクオリティがミップマッピング型を含み、かつハードウェアデバイスがミップマッピングをサポートしない限り、ハードウェアデバイスのビデオメモリに格納されない。

Direct3DRMTexture3.GetCacheFlags

Direct3DRMTexture3

テクスチャメモリが制限されている場合に、テクスチャ管理で現在のテクスチャをどのように処理するかに関する情報を取得する。

構文

object.GetCacheFlags( ) As CONST_D3DRMTEXTURECACHEFLAGS

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMTEXTURECACHEFLAGS列挙型から値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTexture3.GetCacheImportance

Direct3DRMTexture3

テクスチャメモリが制限されている場合に、テクスチャの相対的な重要度に関する情報を取得する。

構文

object.GetCacheImportance( ) As Long

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。

戻り値

テクスチャの相対的な重要度を示す値を返す。デフォルトは0である。値が大きければ、重要度が高いことを示す。この値を使用して、テクスチャメモリが制限されている場合にどのテクスチャを最後にダウンサンプルするかを計算する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTexture3.GetColors

Direct3DRMTexture3

Direct3DRMTexture3オブジェクトをレンダリングするために使用する色の最大数を取得する。

構文

object.GetColors( ) As Long

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。

戻り値

色数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMTexture3オブジェクトが作成された元のイメージ中の色の数ではなく、Direct3DRMTexture3オブジェクトが量子化された色の数を返す。したがって、戻り値の色の数は通常、Direct3DRM3.SetDefaultTextureColorsメソッドを呼び出して設定した色に一致する。ただし、Direct3DRMTexture3.SetColorsメソッドを明示的に呼び出してDirect3DRMTexture3オブジェクトの色を変更した場合は、そうはならない。

Direct3DRMTexture3.GetDecalOrigin

Direct3DRMTexture3

デカールの現在の原点を取得する。

構文

object.GetDecalOrigin(x As Long,
  y As Long)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
x, y
デカールの原点のxおよびy座標。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.SetDecalOrigin

Direct3DRMTexture3.GetDecalScale

Direct3DRMTexture3

指定のデカールのスケーリングプロパティを取得する。

構文

object.GetDecalScale( ) As CONST_DBOOLFLAGS

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。

戻り値

デカールをスケーリングする場合に深度が考慮されるときは–1を返し、デカールがシーンのフレーム上のテクスチャである場合は、ビューアから遠くにあれば小さく、ビューアの近くにあれば大きくスケーリングされる。そうでなければ、深度情報は無視され、デカールはビューアからの遠近にかかわらず同じサイズとなり、0が返される。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.SetDecalScale

Direct3DRMTexture3.GetDecalSize

Direct3DRMTexture3

デカールのサイズを取得する。

構文

object.GetDecalSize(w As Single,
  h As Single)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
w, h
デカールの幅と高さ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.SetDecalSize

Direct3DRMTexture3.GetDecalTransparency

Direct3DRMTexture3

デカールの透明プロパティを取得する。

構文

object.GetDecalTransparency( ) As CONST_DBOOLFLAGS

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。

戻り値

デカールが透明な色を持っている場合は–1、そうでなければ0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.SetDecalTransparency

Direct3DRMTexture3.GetDecalTransparentColor

Direct3DRMTexture3

デカールの透明な色を取得する。

構文

object.GetDecalTransparentColor( ) As Long

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。

戻り値

透明な色の値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.SetDecalTransparentColor

Direct3DRMTexture3.GetShades

Direct3DRMTexture3

レンダリング時にテクスチャ中の各色に対して使用されるシェード数を返す。

構文

object.GetShades( ) As Long

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。

戻り値

シェード数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.SetShades

Direct3DRMTexture3.GetSurface

Direct3DRMTexture3

テクスチャを作成するために使用した Microsoft® DirectDraw®サーフェスを取得する。このメソッドは、Direct3DRM3.CreateTextureFromSurfaceがテクスチャの作成に使用された場合にのみ、サーフェスを取得する。

構文

object.GetSurface(flags As Long) As DirectDrawSurface4

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
flags
フラグ値。0でなければならない。

戻り値

対応するDirectDrawSurface4オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTexture3.SetCacheOptions

Direct3DRMTexture3

テクスチャメモリが制限されている場合に、テクスチャ管理で現在のテクスチャをどのように処理するかに関する情報を提供する。

構文

object.SetCacheOptions(importance As Long
  CONST_D3DRMTEXTURECACHEFLAGS As Long)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
importance
テクスチャの相対的な重要度を示す値。デフォルトは0である。値が大きければ、重要度が高いことを示す。この値を使用して、テクスチャメモリが制限されている場合にどのテクスチャを最後にダウンサンプルするかを計算する。
flags
CONST_D3DRMTEXTURECACHEFLAGS列挙型からの1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTexture3.SetColors

Direct3DRMTexture3

Direct3DRMTexture3オブジェクトをレンダリングするのに使用する色の最大数を設定する。このメソッドは、ランプカラーモデルに限り必要となる。

構文

object.SetColors(c As Long)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
c
色の数。デフォルト値は8である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.GetColors

Direct3DRMTexture3.SetDecalOrigin

Direct3DRMTexture3

デカールの左上からのオフセットとしてデカールの原点を設定する。

構文

object.SetDecalOrigin(x As Long,
  y As Long)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
x, y
デカール座標でのデカールの新しい原点。デフォルトの原点は (0, 0) である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デカール原点は、レンダリング時にそのフレームの位置にマップされる。たとえば、十字のデカールの原点は、デカールの中点に設定され、下向きの矢印の原点は、底辺にそった中点に設定される。

このメソッドは、Direct3DRMTextureInterpolatorオブジェクトにデカール原点キーを追加するためにも使用する。

参照

Direct3DRMTexture3.GetDecalOrigin

Direct3DRMTexture3.SetDecalScale

Direct3DRMTexture3

デカールのスケーリングプロパティを設定する。

構文

object.SetDecalScale(considerScale As CONST_DBOOLFLAGS)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
considerScale
デカールのスケーリング時に深度情報を使用するかどうかを示す値。このパラメータがD_TRUEの場合、デカールをスケーリングする場合に深度が考慮され、デカールがシーンのフレーム上のテクスチャである場合、ビューアから遠くにあれば小さく、ビューアの近くにあれば大きくスケーリングされる。D_FALSEの場合、深度情報は無視され、デカールはビューアからの遠近にかかわらず同じサイズとなる。デフォルト値はD_TRUEである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.GetDecalScale

Direct3DRMTexture3.SetDecalSize

Direct3DRMTexture3

シーン中の深度に従ってデカールがスケーリングされる場合に、使用されるデカールのサイズを設定する。

構文

object.SetDecalSize(width As Single,
  height As Single)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
width, height
モデル座標における、デカールの新しい幅と高さ。デフォルトサイズは、[1, 1]である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMTextureInterpolatorオブジェクトにデカールサイズキーを追加するためにも使用する。

参照

Direct3DRMTexture3.GetDecalSize

Direct3DRMTexture3.SetDecalTransparency

Direct3DRMTexture3

デカールの透明プロパティを設定する。

構文

object.SetDecalTransparency(transparencyEnabled As CONST_DBOOLFLAGS)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
transparencyEnabled
デカールが透明と不透明のどちらの色を持っているかを指定する値。D_TRUEに設定されているとデカールは透明の色を持ち、D_FALSEに設定されていると不透明の色を持つ。デフォルトはD_FALSEである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.GetDecalTransparency

Direct3DRMTexture3.SetDecalTransparentColor

Direct3DRMTexture3

デカールの透明な色を設定する。

構文

object.SetDecalTransparentColor(tcolor As Long)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
tcolor
新しい透明な色。デフォルトの透明な色は黒である。オブジェクトの色をアルファ要素を含めて指定するには、オブジェクト上のDirectX7インターフェイスからCreateColorRGBAメソッドを呼び出す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMTextureInterpolatorオブジェクトにデカールの透明色キーを追加するためにも使用する。

参照

Direct3DRMTexture3.GetDecalTransparentColor

Direct3DRMTexture3.SetShades

Direct3DRMTexture3

レンダリング時に、Direct3DRMTexture3 オブジェクトの各色に対して使用するシェードの最大数を設定する。このメソッドは、ランプカラーモデルに限り必要となる。

構文

object.SetShades(numShades As Long)

要素

object
Direct3DRMTexture3オブジェクトを表すオブジェクト式。
numShades
新しいシェード数。この値は、2の累乗でなければならない。デフォルト値は16である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMTexture3.GetShades


Direct3DRMTextureInterpolator

インターポレータは、アクションを格納した後、中間値を自動計算して、オブジェクトにアクションを適用する方法を提供する。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、さらに、ほかのさまざまな変換も行うことができる。

Direct3DRMTexture3オブジェクトは、Direct3DRMTextureInterpolatorオブジェクトにアタッチできる。インターポレータの詳細については、追加情報の「インターポレータ」を参照すること。

Direct3DRMTextureInterpolatorインターフェイスには、次のメソッドが含まれる。

オブジェクトのアタッチ | AttachObject
DetachObject
GetAttachedObjects
色 | SetDecalOrigin
SetDecalSize
SetDecalTransparentColor
補間の実行 | GetIndex
Interpolate
SetIndex

さらに、Direct3DRMTextureInterpolatorは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMTextureInterpolator.AttachObject

Direct3DRMTextureInterpolator

オブジェクトをインターポレータに接続する。

構文

object.AttachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータにアタッチするDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アタッチされるオブジェクトは、別のインターポレータでも、インターポレータがxInterpolator型となるタイプxのオブジェクトでも良い。たとえば、Direct3DRMTexture3オブジェクトは、Direct3DRMTextureInterpolatorオブジェクトにアタッチできる。

Direct3DRMTextureInterpolator.DetachObject

Direct3DRMTextureInterpolator

インターポレータからオブジェクトのアタッチを解除する。

構文

object.DetachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータからアタッチを外すDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTextureInterpolator.GetAttachedObjects

Direct3DRMTextureInterpolator

インターポレータに現在アタッチされているオブジェクトを取得する。

構文

object.GetAttachedObjects( ) As Direct3DRMObjectArray

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。

戻り値

Direct3DRMObjectArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTextureInterpolator.GetIndex

Direct3DRMTextureInterpolator

インターポレータの現在の内部インデックス（時間）を取得する。

構文

object.GetIndex( ) As Single

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。

戻り値

インターポレータの現在の内部インデックスを含む値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMTextureInterpolator.Interpolate

Direct3DRMTextureInterpolator

インターポレータに格納されているキー間を補間して、一連のアクションを生成する。その後、アクションは、指定のオブジェクトに適用される。オブジェクトの指定がなければ、アクションは、現在アタッチされているオブジェクトに適用される。

構文

object.Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの現在の内部インデックスを含む値。
mObject
Direct3DRMObjectオブジェクト。このオブジェクトは、インターポレータに格納されているすべてのプロパティに対する補間値を割り当てるオブジェクトを表す。このポインタはNOTHINGでも良い。その場合、すべてのアタッチされているオブジェクトのプロパティ値には、補間値がセットされる。
options
実行する補間の種類を制御するCONST_D3DRMINTERPOLATIONFLAGS列挙型

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTextureInterpolator.SetDecalOrigin

Direct3DRMTextureInterpolator

Direct3DRMTextureInterpolatorオブジェクトにデカール原点キーを追加する。

構文

object.SetDecalOrigin(x As Long,
  y As Long)

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。
x, y
デカール座標でのデカールの新しい原点。デフォルトの原点は [0, 0]である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTextureInterpolator.SetDecalSize

Direct3DRMTextureInterpolator

Direct3DRMTextureInterpolatorオブジェクトにデカールサイズキーを追加する。

構文

object.SetDecalSize(width As Single,
  height As Single)

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。
width, height
モデル座標における、デカールの新しい幅と高さ。デフォルトサイズは、[1, 1]である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTextureInterpolator.SetDecalTransparentColor

Direct3DRMTextureInterpolator

Direct3DRMTextureInterpolatorオブジェクトにデカール透明色キーを追加する。

構文

object.SetDecalTransparentColor(tcolor As Long)

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。
tcolor
新しい透明な色。デフォルトの透明な色は黒である。オブジェクトの色をアルファ要素を含めて指定するには、オブジェクト上のDirectX7インターフェイスからCreateColorRGBAメソッドを呼び出す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMTextureInterpolator.SetIndex

Direct3DRMTextureInterpolator

インターポレータの内部インデックス（時間）に指定の値をセットする。他のインターポレータがそのインターポレータにアタッチされていれば、このメソッドは、再帰的にそれらのインデックスを同じ値に同期させる。

構文

object.SetIndex(val As Single)

要素

object
Direct3DRMTextureInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの内部インデックスに対してセットされる時間。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。


Direct3DRMViewport2

アプリケーションは、ビューポートオブジェクトと互いにやり取りするためにDirect3DRMViewport2インターフェイスのメソッドを使用する。Direct3DRMViewport2は、何をクリアするかを示すフラグパラメータをClearメソッドに追加する。

Direct3DRMViewport2インターフェイスのメソッドは、以下のグループにまとめることができる。

カメラ | GetCamera
SetCamera
クリッピングプレーン | GetBack
GetFront
GetPlane
SetBack
SetFront
SetPlane
サイズ | GetHeight
GetWidth
ビューのフィールド | GetField
SetField
その他 | Clear
Configure
ForceUpdate
GetDevice
GetDirect3DViewport3
Pick
Render
オフセット | GetX
GetY
射影タイプ | GetProjection
SetProjection
スケーリング | GetUniformScaling
SetUniformScaling
変換 | InverseTransform
Transform

Direct3DRMViewport2インターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMViewportオブジェクトは、Direct3DRM3.CreateViewportメソッドの使用によって取得される。

Direct3DRMViewport2.Clear

Direct3DRMViewport2

現在の背景色で、指定されたビューポートをクリアする。

構文

object.Clear(flags As CONST_D3DRMVIEWPORTCLEARFLAGS)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
flags
CONST_D3DRMVIEWPORTCLEARFLAGS列挙型の値の論理的な組み合わせ。

エラー値

エラーが発生した場合は、DDERR_INVALIDOBJECTまたはDDERR_INVALIDPARAMSを返す。

すべてのエラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.Configure

Direct3DRMViewport2

ビューポートの原点とサイズを再設定する。

構文

object.Configure(x As Long,
  y As Long,
  width As Long,
  height As Long)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
x, y
ビューポートの新しい位置。
width, height
ビューポートの新しい幅と高さ。

エラー値

x + widthがデバイスの幅より大きい場合、y + heightがデバイスの高さより大きい場合、あるいはx、y、width、heightのいずれかの値が0以下である場合、このメソッドはD3DRMERR_BADVALUEを返す。エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.ForceUpdate

Direct3DRMViewport2

ビューポートの領域を強制的に更新する。指定された領域は、次回のDirect3DRMDevice3.Updateメソッドの呼び出しでスクリーンにコピーされる。

構文

object.ForceUpdate(x1 As Long,
  y1 As Long,
  x2 As Long,
  y2 As Long)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
x1, y1
更新領域の左上隅。
x2, y2
更新領域の右下隅。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

システムは、指定された矩形よりも大きなリージョンを更新することがある。場合によっては、ウィンドウ全体が更新されることもある。

Direct3DRMViewport2.GetBack

Direct3DRMViewport2

ビューポートのバッククリッピングプレーンの位置を取得する。

構文

object.GetBack( ) As Single

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

バッククリッピングプレーンとカメラとの距離を記述する値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.SetBack

Direct3DRMViewport2.GetCamera

Direct3DRMViewport2

ビューポートのカメラを取得する。

構文

object.GetCamera( ) As Direct3DRMFrame3

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

カメラを表すDirect3DRMFrame3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.SetCamera

Direct3DRMViewport2.GetDevice

Direct3DRMViewport2

ビューポートと関連付けられたデバイスを取得する。

構文

object.GetDevice( ) As Direct3DRMDevice3

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

デバイスを表すDirect3DRMDevice3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.GetDirect3DViewport

Direct3DRMViewport2

現在のDirect3DRMViewport2オブジェクトに対応するDirect3Dビューポートを取得する。

構文

object.GetDirect3DViewport( ) As Direct3DViewport3

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

Direct3DViewport3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.GetField

Direct3DRMViewport2

視錐台の角度をラジアン単位で取得する。

構文

object.GetField( ) As Single

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

ビューのフィールドを記述する値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.SetField

Direct3DRMViewport2.GetFront

Direct3DRMViewport2

ビューポートのフロントクリッピングプレーンの位置を取得する。

構文

object.GetFront( ) As Single

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

カメラからフロントクリッピングプレーンまでの距離を記述する値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.SetFront

Direct3DRMViewport2.GetHeight

Direct3DRMViewport2

ビューポートの高さを取得する。

構文

object.GetHeight( ) As Long

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

高さをピクセル単位で返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.GetPlane

Direct3DRMViewport2

フロントクリッピングプレーン上のビューポートのサイズを取得する。

構文

object.GetPlane(l As Single,
  r As Single,
  b As Single,
  t As Single)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
l, r, b, t
フロントクリッピングプレーン上のビューポートの上下左右のサイズ。サイズはピクセル単位で記録される。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.SetPlane

Direct3DRMViewport2.GetProjection

Direct3DRMViewport2

ビューポートの射影タイプを取得する。ビューポートには、平行投影と透視投影のどちらでも用いることができる。

構文

object.GetProjection( ) As CONST_D3DRMPROJECTIONTYPE

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMPROJECTIONTYPE列挙型のメンバの 1 つを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.SetProjection

Direct3DRMViewport2.GetUniformScaling

Direct3DRMViewport2

ウィンドウのサイズより大きな表示ボリュームをスケーリングするために用いられる、スケール特性を取得する。

構文

object.GetUniformScaling( ) As Long

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

ビューポートが一定の比率でスケーリングされる場合は–1、そうでなければ0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMViewport2.SetUniformScaling

Direct3DRMViewport2.GetWidth

Direct3DRMViewport2

ビューポートの幅を取得する。

構文

object.GetWidth( ) As Long

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

幅をピクセル単位で返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.GetX

Direct3DRMViewport2

デバイスの上のビューポート始点のxオフセットを取得する。

構文

object.GetX( ) As Long

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

xオフセットを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.GetY

Direct3DRMViewport2

デバイスの上のビューポート始点のyオフセットを取得する。

構文

object.GetY( ) As Long

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。

戻り値

yオフセットを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.InverseTransform

Direct3DRMViewport2

スクリーン座標の指定されたベクトルをワールド座標に変換し、結果を返す。

構文

object.InverseTransform(d As D3DVECTOR,
  s As D3DRMVECTOR4D)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
d
メソッドが値を返すときに処理結果を受け取るD3DVECTOR型。
s
処理のソースを表すD3DRMVECTOR4D型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.Pick

Direct3DRMViewport2

深度によって分類されたオブジェクト（関連があれば面も）のリストを見つけ出す。取得した配列には、ルートからオブジェクトを含むフレームに到達するまでの階層パスが格納される。

構文

object.Pick(x As Long,
  y As Long) As Direct3DRMPickArray

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
x, y
ピッキングに使われるxおよびy座標。

戻り値

呼び出しが成功すると、Direct3DRMPickArrayインターフェイスを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewport2.Render

Direct3DRMViewport2

フレーム階層を、指定されたビューポートにレンダリングする。指定されたフレーム上のビジュアルと、その下の階層のフレームだけがレンダリングされる。

構文

object.Render(rootFrame As Direct3DRMFrame3)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
rootFrame
レンダリングするフレーム階層を表すDirect3DRMFrame3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

このメソッドは、右手サポートを示すのにDirect3DRM3.SetOptionsメソッドを使おうとしたり、同時に右手サポートを提供する古い方法 (Direct3DRMViewport2.SetProjection) を使うと、エラーを返す。

Direct3DRMViewport2.SetBack

Direct3DRMViewport2

ビューポートのバッククリッピングプレーンの位置を設定する。

構文

object.SetBack(v As Single)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
v
カメラとバッククリッピングプレーンの間の距離。デフォルト値は100.0である。適正な値はその他の視錐台設定に依存する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMViewportInterpolatorオブジェクトにバッククリッピングプレーンの位置キーを追加するためにも使用する。

参照

Direct3DRMViewport2.GetBack、Direct3DRMViewport2.SetFront

Direct3DRMViewport2.SetCamera

Direct3DRMViewport2

カメラをビューポートに設定する。

構文

object.SetCamera(f As Direct3DRMFrame3)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
f
カメラを表すDirect3DRMFrame3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、ビューポートの位置、方向、向きを指定されたカメラフレームと同じに設定する。ビューは、カメラフレームの正のz軸方向に沿って、正のy軸の上方向に向けられる。

参照

Direct3DRMViewport2.GetCamera

Direct3DRMViewport2.SetField

Direct3DRMViewport2

視錐台の角度をラジアン単位で設定する。

構文

object.SetField(v As Single)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
v
ビューの新しいフィールド。この値は視角の端数である。デフォルト値は0.5である。この値に0以下を指定すると、このメソッドはD3DRMERR_BADVALUEエラーを返す。視角は、フロントクリッピングプレーンのアークタンジェントの2倍割るカメラからの距離として定義される。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMViewportInterpolatorオブジェクトにビューのフィールドキーを追加するためにも使用する。

参照

Direct3DRMViewport2.GetField

Direct3DRMViewport2.SetFront

Direct3DRMViewport2

ビューポートのフロントクリッピングプレーンの位置を設定する。

構文

object.SetFront(v As Single)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
v
カメラからフロントクリッピングプレーンまでの距離。デフォルト値は1.0である。適正な値はその他の視錐台設定に依存する。

エラー値

0以下の値が渡されると、このメソッドはD3DRMERR_BADVALUEエラーを返す。エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMViewportInterpolatorオブジェクトにフロントクリッピングプレーン位置キーを追加するためにも使用する。

参照

Direct3DRMViewport2.GetFront

Direct3DRMViewport2.SetPlane

Direct3DRMViewport2

カメラのz軸に対するビューポートのサイズをフロントクリッピングプレーンに設定する。

構文

object.SetPlane(Left As Single,
  Right As Single,
  Bottom As Single,
  Top As Single)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
Left, Right, Bottom, Top
ビューポートの最小のx座標 、最大のx座標、最小のy座標、最大のy座標。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

中央に調整されたビューポートを指定するDirect3DRMViewport2.SetFieldメソッドと異なり、このメソッドによって、任意の比率と位置のビューポートを指定することができる。たとえば、分離した視錐台を構築して、右目や左目のステレオビューをインプリメントすることができる。

このメソッドは、Direct3DRMViewportInterpolatorオブジェクトにプレーンキーを追加するためにも使用する。

参照

Direct3DRMViewport2.GetPlane

Direct3DRMViewport2.SetProjection

Direct3DRMViewport2

ビューポートに射影タイプを設定する。

構文

object.SetProjection(val As CONST_D3DRMPROJECTIONTYPE)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
val
CONST_D3DRMPROJECTIONTYPE列挙型のメンバの1つ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

Direct3DRM3.SetOptionsを使用して右手ジオメトリを指定する。

参照

Direct3DRMViewport2.GetProjection

Direct3DRMViewport2.SetUniformScaling

Direct3DRMViewport2

表示ボリュームをウィンドウのサイズよりも大きくスケーリングするときに用いられる、スケール特性を設定する。

構文

object.SetUniformScaling(flag As CONST_DBOOLFLAGS)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
flag
新しいスケール特性。このパラメータにD_TRUEを指定すると、水平方向と垂直方向に同じスケール係数が使用される。反対に、パラメータにD_FALSEが設定されていると、表示ボリュームをウィンドウに一致させるため、異なるスケール係数が用いられる。デフォルトの設定はD_TRUEである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

通常このメソッドは、バンディングをサポートするためにDirect3DRMViewport2.SetPlaneメソッドと共に使用される。

参照

Direct3DRMViewport2.GetUniformScaling

Direct3DRMViewport2.Transform

Direct3DRMViewport2

ワールド座標の指定されたベクトルをスクリーン座標に変換し、結果を返す。

構文

object.Transform(d As D3DRMVECTOR4D,
  s As D3DVECTOR)

要素

object
Direct3DRMViewport2オブジェクトを表すオブジェクト式。
d
変換操作の出力先となるD3DRMVECTOR4D型。
s
変換処理のソースとなるD3DVECTOR型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

変換結果には、4要素の同種のベクトルが返される。以下の方程式が真であれば、結果のベクトルが示すポイントは可視状態である。

参照

Direct3DRMViewport2.InverseTransform


Direct3DRMViewportArray

アプリケーションは、ビューポートオブジェクトをグループ化するためにDirect3DRMViewportArrayインターフェイスのメソッドを利用する。ビューポートの配列は、0が基準になっている (0～N-1)。

Direct3DRMViewportArrayインターフェイスは次のメソッドをサポートする。
GetElement
GetSize

Direct3DRMViewportArrayオブジェクトは、Direct3DRMDevice3.GetViewportsメソッドの呼び出しによって取得される。

Direct3DRMViewportArray.GetElement

Direct3DRMViewportArray

Direct3DRMViewportArrayオブジェクトから指定された要素を取得する。

構文

object.GetElement(index As Long) As Direct3DRMViewport2

要素

object
Direct3DRMViewportArrayオブジェクトを表すオブジェクト式。
index
配列要素。

戻り値

Direct3DRMViewport2オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewportArray.GetSize

Direct3DRMViewportArray

Direct3DRMViewportArrayオブジェクトに含まれている要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMViewportArrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMViewportInterpolator

インターポレータは、アクションを格納した後、中間値を自動計算して、オブジェクトにアクションを適用する方法を提供する。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、さらに、ほかのさまざまな変換も行うことができる。

Direct3DRMViewport2オブジェクトは、Direct3DRMViewportInterpolatorオブジェクトにアタッチできる。インターポレータの詳細については、追加情報の「インターポレータ」を参照すること。

Direct3DRMViewportInterpolatorインターフェイスには次のメソッドが含まれる。

オブジェクトのアタッチ | AttachObject
DetachObject
GetAttachedObjects
クリッピングプレーン | SetBack
SetFront
ビューのフィールド | SetField
補間の実行 | GetIndex
Interpolate
SetIndex

さらに、Direct3DRMViewportInterpolatorは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMViewportInterpolator.AttachObject

Direct3DRMViewportInterpolator

オブジェクトをインターポレータに接続する。

構文

object.AttachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータにアタッチするDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

アタッチされるオブジェクトは、別のインターポレータでも、インターポレータがxInterpolator型となるタイプxのオブジェクトでも良い。たとえば、Direct3DRMViewport2オブジェクトは、Direct3DRMViewportInterpolatorオブジェクトにアタッチできる。

Direct3DRMViewportInterpolator.DetachObject

Direct3DRMViewportInterpolator

インターポレータからオブジェクトのアタッチを解除する。

構文

object.DetachObject(mObject As Direct3DRMObject)

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。
mObject
インターポレータからアタッチを外すDirect3DRMObjectオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewportInterpolator.GetAttachedObjects

Direct3DRMViewportInterpolator

インターポレータに現在アタッチされているオブジェクトを取得する。

構文

object.GetAttachedObjects( ) As Direct3DRMObjectArray

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。

戻り値

Direct3DRMObjectArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewportInterpolator.GetIndex

Direct3DRMViewportInterpolator

インターポレータの現在の内部インデックス（時間）を取得する。

構文

object.GetIndex( ) As Single

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。

戻り値

インターポレータの現在の内部インデックスを含む値を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。

Direct3DRMViewportInterpolator.Interpolate

Direct3DRMViewportInterpolator

インターポレータに格納されているキー間を補間して、一連のアクションを生成する。その後、アクションは、指定のオブジェクトに適用される。オブジェクトの指定がなければ、アクションは、現在アタッチされているオブジェクトに適用される。

構文

object.Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの現在の内部インデックスを含む値。
mObject
Direct3DRMObjectオブジェクト。このオブジェクトは、インターポレータに格納されているすべてのプロパティに対する補間値を割り当てるオブジェクトを表す。このポインタはNOTHINGでも良い。その場合、すべてのアタッチされているオブジェクトのプロパティ値には、補間値がセットされる。
options
実行する補間の種類を制御するCONST_D3DRMINTERPOLATIONFLAGS列挙型の値の1つ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewportInterpolator.SetBack

Direct3DRMViewportInterpolator

Direct3DRMViewportInterpolatorオブジェクトにバッククリッピングプレーンの位置キーを追加する。

構文

object.SetBack(v As Single)

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。
v
カメラとバッククリッピングプレーンの間の距離。デフォルト値は100.0である。適正な値はその他の視錐台設定に依存する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewportInterpolator.SetField

Direct3DRMViewportInterpolator

Direct3DRMViewportInterpolatorオブジェクトにビューのフィールドキーを追加する。

構文

object.SetField(v As Single)

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。
v
ビューの新しいフィールド。この値は視角の端数である。デフォルト値は0.5である。この値に0以下を指定すると、このメソッドはD3DRMERR_BADVALUEエラーを返す。視角は、フロントクリッピングプレーンのアークタンジェントの2倍割るカメラからの距離として定義される。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewportInterpolator.SetFront

Direct3DRMViewportInterpolator

Direct3DRMViewportInterpolatorオブジェクトにフロントクリッピングプレーン位置キーを追加する。

構文

object.SetFront(v As Single)

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。
v
カメラからフロントクリッピングプレーンまでの距離。デフォルト値は1.0である。適正な値はその他の視錐台設定に依存する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMViewportInterpolator.SetIndex

Direct3DRMViewportInterpolator

インターポレータの内部インデックス（時間）に指定の値をセットする。他のインターポレータがそのインターポレータにアタッチされていれば、このメソッドは、再帰的にそれらのインデックスを同じ値に同期させる。

構文

object.SetIndex(val As Single)

要素

object
Direct3DRMViewportInterpolatorオブジェクトを表すオブジェクト式。
val
インターポレータの内部インデックスに対してセットされる時間。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

インターポレータに格納されている各キーは、インデックス値を持つ。キーを（メソッドを使って）記録するとき、キーには、現在のインターポレータのインデックス値でスタンプが押される。キーのインデックス値は、スタンプを押された後、変わることはない。


Direct3DRMVisual

Direct3DRMVisualは、Microsoft® Direct3D® 保持モードメソッドを何も提供しないが、ビジュアルオブジェクトのインターフェイスはDirect3DRMVisualインターフェイスから引き出される。

ビジュアルは、シーン上にレンダリングできるオブジェクトである。ビジュアルが可視になるのは、そのシーンのフレームに追加された場合のみである。アプリケーションは、Direct3DRMFrame3.AddVisualメソッドを使用して、ビジュアルをフレームに追加することができる。フレームは、ビジュアルにレンダリングのための位置と方向を提供する。

ビジュアルは、以下のコードからキャストできる。

Sub test(visual As Direct3DRMVisual)
    Dim mb As Direct3DRMMeshBuilder3
    Dim mesh As Direct3DRMMesh
    Dim pmesh As Direct3DRMProgressiveMesh
    Dim shadow As Direct3DRMShadow2

    Select Case UCase(visual.GetClassName())
        Case "MESHBUILDER"
            Set mb = visual
        Case "MESH"
            Set mesh = visual
        Case "PROGRESSIVEMESH"
            Set pmesh = visual
        Case "SHADOW"
            Set shadow = visual
    End Select

    '目的のコードを追加

End Sub

以下のインターフェイスは、Direct3DRMVisualオブジェクトから引き出される。

  • Direct3DRMFrame3
  • Direct3DRMMesh
  • Direct3DRMProgressiveMesh
  • Direct3DRMShadow2
  • Direct3DRMTexture3


Direct3DRMVisualArray

アプリケーションは、Direct3DRMVisualArrayインターフェイスのメソッドを利用してビジュアルオブジェクトをグループ化する。ビジュアルの配列は、0が基準になっている (0～N-1)。

ビジュアルは、シーン上にレンダリングできるオブジェクトである。ビジュアルが可視になるのは、そのシーンのフレームに追加された場合のみである。アプリケーションは、Direct3DRMFrame3.AddVisualメソッドを使用して、ビジュアルをフレームに追加することができる。フレームは、ビジュアルにレンダリングのための位置と方向を提供する。

最も一般的なビジュアルタイプは、Direct3DRMMeshBuilder3とDirect3DRMTexture3オブジェクトである。

Direct3DRMVisualArrayインターフェイスは次のメソッドをサポートする。
GetElement
GetSize

Direct3DRMVisualArrayオブジェクトは、Direct3DRMFrame3.GetVisualsメソッドの呼び出しによって取得される。

Direct3DRMVisualArray.GetElement

Direct3DRMVisualArray

Direct3DRMVisualArrayオブジェクトから指定された要素を取得する。

構文

object.GetElement(index As Long) As Direct3DRMVisual

要素

object
Direct3DRMVisualArrayオブジェクトを表すオブジェクト式。
index
配列要素。

戻り値

単一のDirect3DRMVisualオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMVisualArray.GetSize

Direct3DRMVisualArray

Direct3DRMVisualArrayオブジェクトに含まれている要素数を取得する。

構文

object.GetSize( ) As Long

要素

object
Direct3DRMVisualArrayオブジェクトを表すオブジェクト式。

戻り値

要素数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMWrap

アプリケーションは、ラップオブジェクトとやり取りするためにDirect3DRMWrapインターフェイスのメソッドを使用する。このセクションは、このインターフェイスメソッドのリファレンスである。

Direct3DRMWrapインターフェイスは、以下のメソッドをサポートする。

  • Apply
  • ApplyRelative

Direct3DRMWrapインターフェイスは、Direct3DRMObjectインターフェイスから次のメソッドを継承する。
AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMWrapオブジェクトは、Direct3DRM3.CreateWrapメソッドの使用によって取得される。

Direct3DRMWrap.Apply

Direct3DRMWrap

Direct3DRMWrapオブジェクトをその出力先オブジェクトに適用する。一般に出力先オブジェクトは、面またはメッシュである。

構文

object.Apply(visual As Direct3DRMObject)

要素

object
Direct3DRMWrapオブジェクトを表すオブジェクト式。
visual
出力先オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRM3.CreateWrap

Direct3DRMWrap.ApplyRelative

Direct3DRMWrap

オブジェクトの頂点にラップを設定する。最初に各頂点にフレームのワールド変換を行い、次にラップの参照フレームの逆ワールド変換を設定する。

構文

object.ApplyRelative(f As Direct3DRMFrame3,
  visual As Direct3DRMObject)

要素

object
Direct3DRMWrapオブジェクトを表すオブジェクト式。
f
ラッピングするオブジェクトを含むDirect3DRMFrameオブジェクト。
visual
適用するオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRM3.CreateWrap


Visual Basic列挙型

Microsoft® Direct3D® 保持モードの Microsoft Visual Basic® 列挙型は、次のとおりである。

  • CONST_D3DRMADDFACESFLAGS
  • CONST_D3DRMADDMESHBUILDERFLAGS
  • CONST_D3DRMADDTRIANGLESFLAGS
  • CONST_D3DRMADDTRIANGLESVT
  • CONST_D3DRMANIMATIONFLAGS
  • CONST_D3DRMCALLBACKORDERFLAGS
  • CONST_D3DRMCOLORSOURCE
  • CONST_D3DRMCOMBINETYPE
  • CONST_D3DRMCREATEDEVICEFLAGS
  • CONST_D3DRMFOGMETHOD
  • CONST_D3DRMFOGMODE
  • CONST_D3DRMFPTFFLAGS
  • CONST_D3DRMFRAMECONSTRAINT
  • CONST_D3DRMGENERATENORMALSFLAGS
  • CONST_D3DRMHANDEDNESS
  • CONST_D3DRMINTERPOLATIONFLAGS
  • CONST_D3DRMLIGHTTYPE
  • CONST_D3DRMLOADFLAGS
  • CONST_D3DRMMAPPINGFLAGS
  • CONST_D3DRMMATERIALMODE
  • CONST_D3DRMMATERIALOVERRIDEFLAGS
  • CONST_D3DRMMESHBUILDERAGEFLAGS
  • CONST_D3DRMMESHBUILDERENABLEFLAGS
  • CONST_D3DRMPALETTEFLAGS
  • CONST_D3DRMPARENTINGFLAGS
  • CONST_D3DRMPMESHEVENTFLAGS
  • CONST_D3DRMPMESHSTATUSFLAGS
  • CONST_D3DRMPROJECTIONTYPE
  • CONST_D3DRMRAYPICKFLAGS
  • CONST_D3DRMRENDERMODEFLAGS
  • CONST_D3DRMRENDERQUALITY
  • CONST_D3DRMSAVEFLAGS
  • CONST_D3DRMSORTMODE
  • CONST_D3DRMSTATECHANGEFLAGS
  • CONST_D3DRMTEXTURECACHEFLAGS
  • CONST_D3DRMTEXTURECHANGEDFLAGS
  • CONST_D3DRMTEXTUREQUALITY
  • CONST_D3DRMTRAVERALFLAGS
  • CONST_D3DRMVIEWPORTCLEARFLAGS
  • CONST_D3DRMWIREFRAMEFLAGS
  • CONST_D3DRMWRAPTYPE
  • CONST_D3DRMXOFFORMAT
  • CONST_D3DRMZBUFFERMODE

CONST_D3DRMADDFACESFLAGS

法線インデックスの処理方法を示す。

構文

Enum CONST_D3DRMADDFACESFLAGS
  D3DRMADDFACES_DEFAULT
  D3DRMADDFACES_VERTICESONLY
End Enum

値

D3DRMADDFACES_DEFAULT
既存の法線のインデックスが使用される。
D3DRMADDFACES_VERTICESONLY
対応するインデックスを持つ法線が各頂点に対して自動的に使用される。

CONST_D3DRMADDMESHBUILDERFLAGS

コピーのオプションを示す。

構文

Enum CONST_D3DRMADDMESHBUILDERFLAGS
  D3DRMADDMESHBUILDER_DONTCOPYAPPDATA  = 1
  D3DRMADDMESHBUILDER_FLATTENSUBMESHES = 2
  D3DRMADDMESHBUILDER_NOSUBMESHES      = 4
End Enum

値

D3DRMADDMESHBUILDER_DONTCOPYAPPDATA
デフォルトでは、Direct3DRMMeshBuilder3.AddMeshBuilderは、ソースメッシュビルダのアプリケーションデータを出力先にコピーする。D3DRMADDMESHBUILDER_DONTCOPYAPPDATAを指定すると、これが防止される。
D3DRMADDMESHBUILDER_FLATTENSUBMESHES
サブメッシュオブジェクトが重複しないようにする。これらの面は依然コピー可能であるが、出力先メッシュビルダのトップレベルに対してのみである。
D3DRMADDMESHBUILDER_NOSUBMESHES
サブメッシュビルダを無視するようにする。

CONST_D3DRMADDTRIANGLESFLAGS

新しく形成された三角形のオプションを示す。

構文

Enum CONST_D3DRMADDTRIANGLESFLAGS
  D3DRMVERTEX_STRIP = 1
  D3DRMVERTEX_FAN   = 2
  D3DRMVERTEX_LIST  = 4
End Enum

値

D3DRMVERTEX_STRIP
以前の2つの頂点を持つ新しい三角形を細片フォーマットで形成する。
D3DRMVERTEX_FAN
以前の頂点と扇の最初の頂点を持つ新しい三角形を形成する。
D3DRMVERTEX_LIST
新しいリストを開始するか、または以前に開始したリストのメンバである。以前の頂点 (またはその前の頂点) にこのフラグのマークが付いていない場合、最低1つの三角形が形成されるまで、次の頂点にこのフラグのマークが付いていなければならない。

CONST_D3DRMADDTRIANGLESVT

各要素の記述に含めるメソッドを示す。

構文

Enum CONST_D3DRMADDTRIANGLESVT
  D3DRMFVF_TYPE          = 1
  D3DRMFVF_NORMAL        = 2
  D3DRMFVF_COLOR         = 4
  D3DRMFVF_TEXTURECOORDS = 8
End Enum

値

D3DRMFVF_TYPE
CONST_D3DRMADDTRIANGLESFLAGS列挙型からの値。
D3DRMFVF_NORMAL
normalメンバを含める。
D3DRMFVF_COLOR
colorメンバを含める。
D3DRMFVF_TEXTURECOORDS
tuおよびtvメンバを含める。

CONST_D3DRMANIMATIONFLAGS

アニメーションオプションを設定する。

構文

Enum CONST_D3DRMANIMATIONFLAGS
  D3DRMANIMATION_OPEN             = 1
  D3DRMANIMATION_CLOSED           = 2
  D3DRMANIMATION_LINEARPOSITION   = 4
  D3DRMANIMATION_SPLINEPOSITION   = 8
  D3DRMANIMATION_SCALEANDROTATION = 16 (&H10)
  D3DRMANIMATION_POSITION         = 32 (&H20)
End Enum

値

D3DRMANIMATION_OPEN
アニメーションは1回だけ再生され、停止する。
D3DRMANIMATION_CLOSED
アニメーションは繰り返し再生され、終点に達すると開始点に戻ってループする。閉じられたアニメーションでは、終点から開始点へ滑らかに遷移させたい場合、アニメーションの最後のキーは最初のキーの繰り返しでなくてはならない。この繰り返しキーを利用して、ループするアニメーションにおける最後と最初のキー間の時間の差が表される。しかし、最後のキーが最初のキーの繰り返しでない場合、新しいインターフェイス (Direct3DRMAnimation2、Direct3DRMAnimationSet2) で、これは無視されなくなる。これは効果を生み、アニメーションは即時に開始点に戻る。
D3DRMANIMATION_LINEARPOSITION
アニメーションの位置は線形に設定される。
D3DRMANIMATION_SPLINEPOSITION
アニメーションの位置はスプラインで設定される。
D3DRMANIMATION_SCALEANDROTATION
アニメーションのスケールと回転行列によって、他のメソッドが設定するどんな変換行列も上書きされる。
D3DRMANIMATION_POSITION
アニメーションの位置行列によって、他のメソッドが設定するどんな変換行列も上書される。

CONST_D3DRMCALLBACKORDERFLAGS

フレームのコールバックを、子フレームをたどる前と後のどちらに使用するかを指定するために、Direct3DRMFrame3.AddMoveCallbackメソッドによって使われる。

構文

Enum CONST_D3DRMCALLBACKORDERFLAGS
  D3DRMCALLBACK_PREORDER
  D3DRMCALLBACK_POSTORDER
End Enum

値

D3DRMCALLBACK_PREORDER
デフォルト値。Direct3DRMFrame3.Moveメソッドが階層をたどって行くとき、フレームのコールバックは子フレームをたどる前に呼び出される。
D3DRMCALLBACK_POSTORDER
Moveが階層をたどって行くとき、フレームのコールバックは子フレームをたどった後に呼び出される。

CONST_D3DRMCOLORSOURCE

Direct3DRMMeshBuilder3オブジェクトのカラーソースを記述する。カラーソースを設定するには、Direct3DRMMeshBuilder3.SetColorSourceメソッドを使用する。カラーソースを取得するには、Direct3DRMMeshBuilder3.GetColorSourceメソッドを使用する。

構文

Enum CONST_D3DRMCOLORSOURCE
  D3DRMCOLOR_FROMFACE
  D3DRMCOLOR_FROMVERTEX
End Enum

値

D3DRMCOLOR_FROMFACE
オブジェクトのカラーソースは面である。
D3DRMCOLOR_FROMVERTEX
オブジェクトのカラーソースは頂点である。

CONST_D3DRMCOMBINETYPE

2つの行列の合成方法を指定する。

構文

Enum CONST_D3DRMCOMBINETYPE
  D3DRMCOMBINE_REPLACE
  D3DRMCOMBINE_BEFORE
  D3DRMCOMBINE_AFTER
End Enum

値

D3DRMCOMBINE_REPLACE
与えられた行列により、フレームの現在の行列を置き換える。
D3DRMCOMBINE_BEFORE
与えられた行列とフレームの現在の行列の積を求める。計算においては、与えられた行列が現在の行列よりも先に指定される。
D3DRMCOMBINE_AFTER
与えられた行列とフレームの現在の行列の積を求める。計算においては、与えられた行列が現在の行列の後に指定される。

注意

行列の乗算は可換ではないため、与えられた行列と現在の行列を掛け合わせる順序は重要である。

参照

Direct3DRMFrame3.AddRotation、Direct3DRMFrame3.AddScale、Direct3DRMFrame3.AddTransform、Direct3DRMFrame3.AddTranslation

CONST_D3DRMCREATEDEVICEFLAGS

Direct3DRMDevice3オブジェクトの作成時にオプションを定義する。

構文

Enum CONST_D3DRMCREATEDEVICEFLAGS
  D3DRMDEVICE_DEFAULT
  D3DRMDEVICE_NOZBUFFER
End Enum

値

D3DRMDEVICE_DEFAULT
デフォルトのオプションを使用する。
D3DRMDEVICE_NOZBUFFER
Zバッファは無効である。

CONST_D3DRMFOGMETHOD

現在のフォグメソッドを示す。

構文

Enum CONST_D3DRMFOGMETHOD
  D3DRMFOGMETHOD_VERTEX = 1
  D3DRMFOGMETHOD_TABLE  = 2
  D3DRMFOGMETHOD_ANY    = 4
End Enum

値

D3DRMFOGMETHOD_VERTEX
頂点フォグを使用する。
D3DRMFOGMETHOD_TABLE
テーブルフォグを使用する。
D3DRMFOGMETHOD_ANY
Direct3D 保持モードが適用可能なメソッドを選択する。

CONST_D3DRMFOGMODE

カメラからの距離が広がるにつれ、フォグ効果がどのくらいの速さでどのように強くなるかを示す。

モノクロ（ランプ）ライティングモードでは、フォグは、その色が黒の場合に正常に機能する（ライティングがない場合には、どのフォグの色でも働く。その場合には、すべてのフォグの色が実際的には黒となるからである）。

構文

Enum CONST_D3DRMFOGMODE
  D3DRMFOG_LINEAR
  D3DRMFOG_EXPONENTIAL
  D3DRMFOG_EXPONENTIALSQUARED
End Enum

値

D3DRMFOG_LINEAR
フォグ効果は、始点から終点までの間に比例的に強くなる。次の公式で表される。

現在サポートされているフォグモードは、これだけである。

D3DRMFOG_EXPONENTIAL
フォグ効果は、指数関数的に強くなる。次の公式で表される。

D3DRMFOG_EXPONENTIALSQUARED
フォグ効果は、距離の2乗に比例して指数関数的に強くなる。次の公式で表される。

注意

フォグは視界の基準と見なされることに注意しなくてはならない。方程式の1つから求められるフォグ値が低いほど、オブジェクトは見えにくくなる。

フォグの密度、始点、終点は、Direct3DRMFrame3.SetSceneFogParamsメソッドによって指定することができる。指数フォグモードの方程式では、eは自然対数の底を表し、その値は約2.71828である。

参照

Direct3DRMFrame3.SetSceneFogMode

CONST_D3DRMFPTFFLAGS

返されるテクスチャフォーマットのオプションを設定する。

構文

Enum CONST_D3DRMFPTFFLAGS
  D3DRMFPTF_ALPHA         = 1
  D3DRMFPTF_NOALPHA       = 2
  D3DRMFPTF_PALETTIZED    = 4
  D3DRMFPTF_NOTPALETTIZED = 8
End Enum

値

D3DRMFPTF_ALPHA
返されるテクスチャフォーマットには、アルファチャネルがなければならない。
D3DRMFPTF_NOALPHA
返されるテクスチャフォーマットには、アルファチャネルがあってはならない。アルファチャネルの欠落を希望するが、欠落を必須としないことを示すには、D3DRMFPTF_ALPHAとD3DRMFPTF_NOALPHAの両フラグを省略する。
D3DRMFPTF_PALETTIZED
返されるテクスチャフォーマットは、パレット化しなければならない。
D3DRMFPTF_NOTPALETTIZED
返されるテクスチャフォーマットは、パレット化してはならない。パレットの欠落を希望するが、欠落を必須としないことを示すには、D3DRMFPTF_PALETTIZEDとD3DRMFPTF_NOTPALETTIZEDの両フラグを省略する。

CONST_D3DRMFRAMECONSTRAINT

Direct3DRMFrame3オブジェクトを表示するときに強制的に回転する軸を記述する。Direct3DRMFrame3.LookAtメソッドはこの列挙型を使用する。

構文

Enum CONST_D3DRMFRAMECONSTRAINT
  D3DRMCONSTRAIN_Z
  D3DRMCONSTRAIN_Y
  D3DRMCONSTRAIN_X
End Enum

値

D3DRMCONSTRAIN_Z
x軸とy軸の回転だけを使用する。
D3DRMCONSTRAIN_Y
x軸とz軸の回転だけを使用する。
D3DRMCONSTRAIN_X
y軸とz軸の回転だけを使用する。

CONST_D3DRMGENERATENORMALSFLAGS

法線の生成方法を定義するためにDirect3DRMMeshBuilder3.GenerateNormalsメソッドによって使用される値を指定する。

構文

Enum CONST_D3DRMGENERATENORMALSFLAGS
  D3DRMGENERATENORMALS_PRECOMPACT     = 1
  D3DRMGENERATENORMALS_USECREASEANGLE = 2
End Enum

値

D3DRMGENERATENORMALS_PRECOMPACT
アルゴリズムは、法線の生成前にメッシュの頂点のコンパクト化を試みる。
D3DRMGENERATENORMALS_USECREASEANGLE
折り目角を示すパラメータを使用する。そうでなければ、折り目角は無視される。

CONST_D3DRMHANDEDNESS

Direct3D保持モードの座標系の現在のオプションを示す。

構文

Enum CONST_D3DRMHANDEDNESS
  D3DRMOPTIONS_LEFTHANDED  = 1
  D3DRMOPTIONS_RIGHTHANDED = 2
End Enum

値

D3DRMOPTIONS_LEFTHANDED
左手ジオメトリを使用する。この値がデフォルトである。
D3DRMOPTIONS_RIGHTHANDED
右手ジオメトリを使用する。

注意

D3DRMOPTIONS_LEFTHANDEDとD3DRMOPTIONS_RIGHTHANDEDは、ピッキング、光線ピッキング、および次のインターフェイスに影響を与える。

  • Direct3DRMClippedVisual
  • Direct3DRMMesh
  • Direct3DRMMeshBuilder3
  • Direct3DRMProgressiveMesh
  • Direct3DRMShadow2
  • Direct3DRMTexture3
  • Direct3DRMViewport2

CONST_D3DRMINTERPOLATIONFLAGS

インターポレータオブジェクト上のInterpolateメソッドのオプションを定義し、オブジェクトのロード方法を変更する。

構文

Enum CONST_D3DRMINTERPOLATIONFLAGS
  D3DRMINTERPOLATION_OPEN         = 1
  D3DRMINTERPOLATION_CLOSED       = 2
  D3DRMINTERPOLATION_LINEAR       = 4
  D3DRMINTERPOLATION_SPLINE       = 8
  D3DRMINTERPOLATION_VERTEXCOLOR  = 64 (&H40)
  D3DRMINTERPOLATION_SLERPNORMALS = 128 (&H80)
  D3DRMINTERPOLATION_NEAREST      = 256 (&H100)
End Enum

値

D3DRMINTERPOLATION_OPEN
各キーチェイン (実行スレッド) の最初と最後のキーが、インデックス範囲外の補間値を修正する。
D3DRMINTERPOLATION_CLOSED
補間は循環的になる。キーは、実際には、インデックス範囲に等しい時間で永遠に繰り返される。アニメーションとの互換性をとるために、インデックス範囲の終点に等しいインデックスのキーは、すべて無視される。
D3DRMINTERPOLATION_LINEAR
各キーチェイン間の中間値を決定するために、2つの最も近いキーの間で行う線形補間が使用される。
D3DRMINTERPOLATION_SPLINE
各キーチェイン間の中間値を決定するために、4つの最も近いキーのBスプライン混合関数が使用される。
D3DRMINTERPOLATION_VERTEXCOLOR
頂点の色が補間される。Direct3DRMMesh.SetVerticesの補間だけに影響する。
D3DRMINTERPOLATION_SLERPNORMALS
頂点の法線が球面補間される (現在未実装)。SetVerticesの補間にだけ影響する。
D3DRMINTERPOLATION_NEAREST
各キーチェインの中間値を決定するために、一番近いキーの値が使用される。

CONST_D3DRMLIGHTTYPE

Direct3DRM3.CreateLightメソッドで使用される照明タイプを定義する。

構文

Enum CONST_D3DRMLIGHTTYPE
  D3DRMLIGHT_AMBIENT
  D3DRMLIGHT_POINT
  D3DRMLIGHT_SPOT
  D3DRMLIGHT_DIRECTIONAL
  D3DRMLIGHT_PARALLELPOINT
End Enum

値

D3DRMLIGHT_AMBIENT
照明はアンビエントソースである。
D3DRMLIGHT_POINT
照明はポイントソースである。
D3DRMLIGHT_SPOT
照明はスポットライトソースである。
D3DRMLIGHT_DIRECTIONAL
照明はディレクショナルソースである。
D3DRMLIGHT_PARALLELPOINT
照明はパラレルポイントソースである。

CONST_D3DRMLOADFLAGS

Direct3DRM3.LoadFromFile、Direct3DRMAnimationSet2.LoadFromFile、Direct3DRMFrame3.LoadFromFile、Direct3DRMMeshBuilder3.LoadFromFile、およびDirect3DRMProgressiveMesh.LoadFromFileメソッドのオプションを定義する。これらのオプションは、オブジェクトのロード方法を変更する。

構文

Enum CONST_D3DRMLOADFLAGS
  D3DRMLOAD_FROMFILE            = 0
  D3DRMLOAD_FROMRESOURCE        = 1
  D3DRMLOAD_FROMMEMORY          = 2
  D3DRMLOAD_FROMSTREAM          = 4
  D3DRMLOAD_FROMUR              = 8
  D3DRMLOAD_BYNAME              = 16 (&H10)
  D3DRMLOAD_BYPOSITION          = 32 (&H20)
  D3DRMLOAD_BYGUID              = 64 (&H40)
  D3DRMLOAD_FIRST               = 128 (&H80)
  D3DRMLOAD_INSTANCEBYREFERENCE = 256 (&H100)
  D3DRMLOAD_INSTANCEBYCOPYING   = 512 (&H200)
  D3DRMLOAD_ASYNCHRONOUS        = 1024 (&H400)
End Enum

値

ソースフラグ

D3DRMLOAD_FROMFILE
ファイルからロードする。これはデフォルト設定である。
D3DRMLOAD_FROMRESOURCE
リソースからロードする。
D3DRMLOAD_FROMMEMORY
メモリからロードする。
D3DRMLOAD_FROMSTREAM
ストリームからロードする。
D3DRMLOAD_FROMUR
URLからロードする。

識別子フラグ

D3DRMLOAD_BYNAME
指定された名前を使用してオブジェクトをロードする。
D3DRMLOAD_BYPOSITION
与えられた、0から始まる位置に、スタンドアロンのオブジェクトをロードする（つまり、ファイル中のn番目のオブジェクトをロードする）。スタンドアロンのオブジェクトは他のオブジェクトを含むことができるが、他のオブジェクトに含まれることはない。
D3DRMLOAD_BYGUID
指定されたグローバルユニーク識別子（GUID）を使用してオブジェクトをロードする。
D3DRMLOAD_FIRST
これはデフォルト設定である。与えられたタイプのスタンドアロンのオブジェクトをロードする (たとえば、アプリケーションがDirect3DRMMeshBuilder3.LoadFromFileを呼び出す場合はメッシュをロードする)。スタンドアロンのオブジェクトは他のオブジェクトを含むことができるが、他のオブジェクトに含まれることはない。

インスタンスフラグ

D3DRMLOAD_INSTANCEBYREFERENCE
指定された名前と同じ名前のオブジェクトが存在するかどうかをチェックする。存在する場合、新しいオブジェクトを作成する代わりに、そのオブジェクトのインスタンスを使用する。
D3DRMLOAD_INSTANCEBYCOPYING
指定された名前と同じ名前のオブジェクトが存在するかどうかをチェックする。存在する場合、新しいオブジェクトを作成する代わりに、そのオブジェクトをコピーする。

ロードフラグ

D3DRMLOAD_ASYNCHRONOUS
LoadFromFile呼び出しは、直ちに戻る。ロードの進行状態をチェックするのにイベントを使用するのは、アプリケーションの責任となる。デフォルトでは、ロードは、同期式で行われ、LoadFromFile呼び出しは、すべてのデータのロードが完了するまで、またはエラーが発生するまでは戻らない。

注意

各LoadFromFileメソッドは、filenameパラメータを使用してオブジェクトのソースを指定し、idパラメータによってオブジェクトを識別する。システムはソースフラグの選択に基づいてfilenameパラメータを解釈する。そして、識別子フラグの選択に基づいてidパラメータの内容を解釈する。

インスタンスフラグは、パラメータの解釈方法には何も変更を加えない。D3DRMLOAD_INSTANCEBYREFERENCEフラグを用いると、新しいオブジェクトを作成することなく同じファイルを2回ロードすることができる。オブジェクトが名前を持っていない場合、D3DRMLOAD_INSTANCEBYREFERENCEフラグをセットすると、D3DRMLOAD_INSTANCEBYCOPYINGフラグをセットしたときと同じ効果を得ることができる。ローダは、同一のオブジェクトが存在しても、各名前なしオブジェクトを新しいオブジェクトとして作成する。

CONST_D3DRMMAPPINGFLAGS

テクスチャをグループにマッピングする方法を定義する値である。Direct3DRMMesh.GetGroupMappingとDirect3DRMMesh.SetGroupMappingメソッドによって用いられる。

構文

Enum CONST_D3DRMMAPPINGFLAGS
  D3DRMMAP_WRAPU        = 1
  D3DRMMAP_WRAPV        = 2
  D3DRMMAP_PERSPCORRECT = 4
End Enum

値

D3DRMMAP_WRAPU
u方向にテクスチャをラップする。
D3DRMMAP_WRAPV
v方向にテクスチャをラップする。
D3DRMMAP_PERSPCORRECT
テクスチャラッピングはパースペクティブ補正される。

注意

D3DRMMAP_WRAPUとD3DRMMAP_WRAPVフラグは、ラスタライザがテクスチャ座標を解釈する方法を決定する。ラスタライザは常に、テクスチャ座標で最も短い距離、つまり直線を補間する。この直線のパスと、uおよびv座標の有効値は、ラッピングフラグの使い方によって異なる。一方または両方のフラグがセットされると、直線はuまたはv方向のテクスチャの辺をラップアラウンドする。この場合、テクスチャは円柱状かドーナツ上の位相を持っているかのように見える。

D3DRMMAP_WRAPUまたはD3DRMMAP_WRAPVのいずれかがセットされた場合、テクスチャは円周1.0の終わりのない円筒形になる。1.0以上のテクスチャ座標は、ラップされていない範囲内のみ有効である。テクスチャ座標間の最短距離はラッピングフラグによって異なる。D3DRMMAP_WRAPUがセットされているときは、点(0.1, 0.1)から(0.9, 0.9)までの最短の直線は、点（0, 0.5）を通過する。

D3DRMMAP_WRAPUとD3DRMMAP_WRAPVフラグの両方がセットされたときは、テクスチャは円環体（ドーナツ）状になる。システムは閉鎖しているため、1.0以上のテクスチャ座標は無効である。点(0.1, 0.1)から(0.9, 0.9)までの最短の直線は、点(0, 0)を通過する。

CONST_D3DRMMATERIALMODE

フレームと共にレンダリングされるビジュアルのマテリアル情報のソースを記述する。

構文

Enum CONST_D3DRMMATERIALMODE
  D3DRMMATERIAL_FROMMESH
  D3DRMMATERIAL_FROMPARENT
  D3DRMMATERIAL_FROMFRAME
End Enum

値

D3DRMMATERIAL_FROMMESH
マテリアル情報はビジュアルオブジェクト (メッシュ)そのものから取得される。これはデフォルト設定である。
D3DRMMATERIAL_FROMPARENT
マテリアル情報は、色やテクスチャ情報と共に親フレームから継承される。
D3DRMMATERIAL_FROMFRAME
マテリアル情報はフレームから取得され、ビジュアルオブジェクトが保持していた以前の情報をオーバーライドする。

参照

Direct3DRMFrame3.GetMaterialMode、Direct3DRMFrame3.SetMaterialMode

CONST_D3DRMMATERIALOVERRIDEFLAGS

固有のマテリアル属性をセットする。

構文

Enum CONST_D3DRMMATERIALOVERRIDEFLAGS
  D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAONLY     = 1
  D3DRMMATERIALOVERRIDE_DIFFUSE_RGBONLY       = 2
  D3DRMMATERIALOVERRIDE_DIFFUSE               = 3
  D3DRMMATERIALOVERRIDE_AMBIENT               = 4
  D3DRMMATERIALOVERRIDE_EMISSIVE              = 8
  D3DRMMATERIALOVERRIDE_SPECULAR              = 16 (&H10)
  D3DRMMATERIALOVERRIDE_POWER                 = 32 (&H20)
  D3DRMMATERIALOVERRIDE_TEXTURE               = 64 (&H40)
  D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAMULTIPLY = 128 (&H80)
  D3DRMMATERIALOVERRIDE_ALL                   = 255 (&HFF)
End Enum

値

D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAONLY
マテリアルの拡散アルファ値だけをオーバーライドする。
D3DRMMATERIALOVERRIDE_DIFFUSE_RGBONLY
マテリアルの拡散RGB値だけをオーバーライドする。
D3DRMMATERIALOVERRIDE_DIFFUSE
マテリアルの拡散プロパティをオーバーライドする。
D3DRMMATERIALOVERRIDE_AMBIENT
マテリアルのアンビエントプロパティをオーバーライドする。
D3DRMMATERIALOVERRIDE_EMISSIVE
マテリアルの放射プロパティをオーバーライドする。
D3DRMMATERIALOVERRIDE_SPECULAR
マテリアルの反射プロパティをオーバーライドする。
D3DRMMATERIALOVERRIDE_POWER
マテリアルの反射強度プロパティをオーバーライドする。
D3DRMMATERIALOVERRIDE_TEXTURE
マテリアルのテクスチャプロパティをオーバーライドする。
D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAMULTIPLY
マテリアルの拡散アルファ乗算プロパティをオーバーライドする。
D3DRMMATERIALOVERRIDE_ALL
マテリアルのすべてのプロパティをオーバーライドする。

CONST_D3DRMMESHBUILDERAGEFLAGS

メッシュビルダのオプションを示す。デフォルト値は0である。この場合、メッシュビルダは通常どおりに年をとる (エージングはメッシュビルダに対するなんらかの変更によって引き起こされる)。

構造

Enum CONST_D3DRMMESHBUILDERAGEFLAGS
  D3DRMMESHBUILDERAGE_GEOMETRY  = 1
  D3DRMMESHBUILDERAGE_MATERIALS = 2
  D3DRMMESHBUILDERAGE_TEXTURES  = 4
End Enum

値

D3DRMMESHBUILDERAGE_GEOMETRY
メッシュビルダは、メッシュジオメトリが変更されるたびに年をとる (たとえば、頂点、面または別のメッシュビルダの追加)。
D3DRMMESHBUILDERAGE_MATERIALS
メッシュビルダは、メッシュのマテリアル関連プロパティが変更されるたびに、あるいは、面または別のメッシュが追加された場合に年をとる。
D3DRMMESHBUILDERAGE_TEXTURES
メッシュビルダは、メッシュのテクスチャ関連プロパティが変更されるたびに、あるいは、面または別のメッシュが追加された場合に年をとる。

CONST_D3DRMMESHBUILDERENABLEFLAGS

レンダリングとピッキングが有効かどうかを示す。

構文

Enum CONST_D3DRMMESHBUILDERENABLEFLAGS
  D3DRMMESHBUILDER_RENDERENABLE = 1
  D3DRMMESHBUILDER_PICKENABLE   = 2
End Enum

値

D3DRMMESHBUILDER_RENDERENABLE
現在のオブジェクト上ではレンダリングが有効である。
D3DRMMESHBUILDER_PICKENABLE
現在のオブジェクト上ではピッキングが有効である。

CONST_D3DRMPALETTEFLAGS

カラーがどのように使用されるかを定義する。Microsoft DirectDraw® で作成したパレットをDirect3D保持モードで使用するとき、パレットエントリにパレットフラグをセットし、そのエントリを保持モードで変更できるかどうかマークを付けることができる。

構文

Enum CONST_D3DRMPALETTEFLAGS
  D3DRMPALETTE_FREE
  D3DRMPALETTE_READONLY
  D3DRMPALETTE_RESERVED
End Enum

値

D3DRMPALETTE_FREE
レンダラはこのエントリを自由に使用できる。
D3DRMPALETTE_READONLY
固定されているが、レンダラは使用できる。
D3DRMPALETTE_RESERVED
レンダラは使用できない。

CONST_D3DRMPARENTINGFLAGS

取得するDirect3DRMMeshBuilder3オブジェクトを定義する

構文

Enum CONST_D3DRMPARENTINGFLAGS
  D3DRMMESHBUILDER_DIRECTPARENT = 1
  D3DRMMESHBUILDER_ROOTMESH     = 2
End Enum

値

D3DRMMESHBUILDER_DIRECTPARENT
現在のDirect3DRMMeshBuilder3オブジェクトの直接の親を取得する。
D3DRMMESHBUILDER_ROOTMESH
現在のDirect3DRMMeshBuilder3オブジェクトの最後の親 (親を持たない親) を取得する。

CONST_D3DRMPMESHEVENTFLAGS

ベースメッシュ、またはすべてのデータがダウンロードされたことを通知する値である。Direct3DRMProgressiveMesh.RegisterEventsによって使用される。

構文

Enum CONST_D3DRMPMESHEVENTFLAGS
  D3DRMPMESHEVENT_BASEMESH = 1
  D3DRMPMESHEVENT_COMPLETE = 2
End Enum

値

D3DRMPMESHEVENT_BASEMESH
ベースメッシュのダウンロードが完了すると通知されるイベント。
D3DRMPMESHEVENT_COMPLETE
すべてのデータのダウンロードが完了すると通知されるイベント。

CONST_D3DRMPMESHSTATUSFLAGS

Direct3DRMProgressiveMesh.GetLoadStatusメソッドに返されるメッシュの状態を定義する。

構文

Enum CONST_D3DRMPMESHSTATUSFLAGS
  D3DRMPMESHSTATUS_VALID            = 1
  D3DRMPMESHSTATUS_INTERRUPTED      = 2
  D3DRMPMESHSTATUS_BASEMESHCOMPLETE = 4
  D3DRMPMESHSTATUS_COMPLETE         = 8
  D3DRMPMESHSTATUS_RENDERABLE       = 16 (&H10)
End Enum

値

D3DRMPMESHSTATUS_VALID
データは有効である。
D3DRMPMESHSTATUS_INTERRUPTED
ダウンロードは割り込みを受けた。
D3DRMPMESHSTATUS_BASEMESHCOMPLETE
ベースメッシュのダウンロードが完了した。
D3DRMPMESHSTATUS_COMPLETE
ロードが完了した。
D3DRMPMESHSTATUS_RENDERABLE
ベースメッシュのダウンロードが完了し、データは有効である。

CONST_D3DRMPROJECTIONTYPE

Direct3DRMViewportオブジェクトで使用される投影のタイプを定義する。Direct3DRMViewport2.GetProjectionとDirect3DRMViewport2.SetProjectionメソッドはこの列挙型を使用する。右手タイプは、右手投影を有効にする。

注: Direct3DRM3.SetOptionsを使用して右手ジオメトリを指定する。

カメラの軸（「Direct3DRMFrame3.SetAxes」を参照）は、カメラの面する方向を決定するために、左手投影と右手投影の両方で使用される。

構文

Enum CONST_D3DRMPROJECTIONTYPE
  D3DRMPROJECT_PERSPECTIVE
  D3DRMPROJECT_ORTHOGRAPHIC
  D3DRMPROJECT_RIGHTHANDPERSPECTIVE
  D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
End Enum

値

D3DRMPROJECT_PERSPECTIVE
投影は、左手のパースペクティブである。
D3DRMPROJECT_ORTHOGRAPHIC
投影は、左手の正射影法である。
D3DRMPROJECT_RIGHTHANDPERSPECTIVE
投影は、右手のパースペクティブである。
D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
投影は、右手の正射影法である。

CONST_D3DRMRAYPICKFLAGS

ビジュアルと指定された光線の交差部分を計算する値を指定する。DirectDRMFrame3.RayPickメソッドによって使用される

構文

Enum CONST_D3DRMRAYPICKFLAGS
  D3DRMRAYPICK_ONLYBOUNDINGBOXES       = 1
  D3DRMRAYPICK_IGNOREFURTHERPRIMITIVES = 2
  D3DRMRAYPICK_INTERPOLATEUV           = 4
  D3DRMRAYPICK_INTERPOLATECOLOR        = 8
  D3DRMRAYPICK_INTERPOLATENORMAL       = 16 (&H10)
End Enum

値

最適化フラグ

D3DRMRAYPICK_ONLYBOUNDINGBOXES
階層中のビジュアルの境界ボックスのある交差部分だけが返される。正確な面の交差はチェックしない。
D3DRMRAYPICK_IGNOREFURTHERPRIMITIVES
光線に交差する最も近いビジュアルだけが返される。それまでの検索中に発見された最も近いものより遠くにあるビジュアルを無視する。

補間フラグ

D3DRMRAYPICK_INTERPOLATEUV
テクスチャ座標を補間する。
D3DRMRAYPICK_INTERPOLATECOLOR
色を補間する。
D3DRMRAYPICK_INTERPOLATENORMAL
法線を補間する。

CONST_D3DRMRENDERMODEFLAGS

透明オブジェクトの透明モードを指定する。

構文

Enum CONST_D3DRMRENDERMODEFLAGS
  D3DRMRENDERMODE_BLENDEDTRANSPARENCY      = 1
  D3DRMRENDERMODE_SORTEDTRANSPARENCY       = 2
  D3DRMRENDERMODE_LIGHTINMODELSPACE        = 8
  D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR    = 16 (&H10)
  D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE = 32 (&H20)
End Enum

値

D3DRMRENDERMODE_BLENDEDTRANSPARENCY
透明モードをアルファブレンディングに設定する。ブレンディングによる透明モードは、各ピクセルでカラー値を追加し、2つのイメージを組み合わせる。
D3DRMRENDERMODE_SORTEDTRANSPARENCY
シーン中の透明ポリゴンが第2パスでバッファリング、ソート、およびレンダリングされるように透明モードを設定する。このフラグは、D3DRMRENDERMODE_BLENDEDTRANSPARENCYフラグも同時にセットされていない場合には、何の効果もない。外部ビジュアルまたはユーザビジュアル中の透明ポリゴンはソートされない。ネイティブ D3DRM ビジュアル (D3DRMMeshオブジェクトとD3DRMMeshBuilderオブジェクトなど) のみソートされる。
D3DRMRENDERMODE_LIGHTINMODELSPACE
照明がモデル空間でレンダリングされるように透明モードを設定する。
D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR
依存する反射を表示するように透明モードを設定する。
D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE
ソートを無効にするように透明モードを設定する。

注意

D3DRMRENDERMODE_BLENDEDTRANSPARENCYとD3DRMRENDERMODE_SORTEDTRANSPARENCYの両フラグが、同時にセットされていれば、2つの透明オブジェクトが、一方を他方でレンダリングするように保証し、イメージは、期待どおりのビジュアル効果を作り出すように正しい順で混合される。

D3DRMRENDERMODE_SORTEDTRANSPARENCYは、アルファポリゴンの三角形ごとの、後ろから前へのソートをオンにする。

D3DRMRENDERMODE_BLENDEDTRANSPARENCYフラグは、点描アルファに対抗して真のアルファブレンディングをオンにする。真のアルファブレンディングでは、重複する三角形のピクセルはまとめて混合される。点描アルファでは、前面にある三角形のピクセルのいくつかは、下にある三角形を表示するような描画が行われない (これは、スクリーンドアの透明とも呼ばれる)。点描アルファを実行する場合、三角形をどのような順序でレンダリングするかにかかわらず、結果が同じであるため、三角形をソートする必要はない。

CONST_D3DRMRENDERQUALITY

Direct3DRMDevice3.SetQuality、Direct3DRMMeshBuilder3.SetQualityおよびDirect3DRMProgressiveMesh.SetQualityメソッドによって設定されるクオリティオプションを定義する。さらに、CONST_D3DRMRENDERQUALITYは、塗りつぶしモード、照明モードおよびシェーディングモードを定義する

構文

Enum CONST_D3DRMRENDERQUALITY
  D3DRMFILL_POINTS      = 0
  D3DRMFILL_WIREFRAME   = 64(&H40)
  D3DRMFILL_SOLID       = 128(&H80)
  D3DRMFILL_MASK        = 448(&H1C0)
  D3DRMFILL_MAX         = 512(&H200)

  D3DRMLIGHT_OFF        = 0
  D3DRMLIGHT_ON         = 8
  D3DRMLIGHT_MASK       = 56(&H38)
  D3DRMLIGHT_MAX        = 64(&H40)

  D3DRMRENDER_WIREFRAME = 64  (&H40)
  D3DRMRENDER_UNLITFLAT = 128 (&H80)
  D3DRMRENDER_FLAT      = 136 (&H88)
  D3DRMRENDER_GOURAUD   = 137 (&H89)
  D3DRMRENDER_PHONG     = 138 (&H8A)

  D3DRMSHADE_FLAT       = 0
  D3DRMSHADE_GOURAUD    = 1
  D3DRMSHADE_PHONG      = 2
  D3DRMSHADE_MASK       = 7
  D3DRMSHADE_MAX        = 8
End Enum

値

D3DRMFILL_POINTS
点のみを塗りつぶす。最小の塗りつぶしモード。
D3DRMFILL_WIREFRAME
ワイヤフレームを塗りつぶす。
D3DRMFILL_SOLID
ソリッドオブジェクトを塗りつぶす。
D3DRMFILL_MASK
マスクを使用して塗りつぶす。
D3DRMFILL_MAX
塗りつぶしモードの最大値。
D3DRMLIGHT_OFF
照明はオフである。
D3DRMLIGHT_ON
照明はオンである。
D3DRMLIGHT_MASK
照明はマスクを使用する。
D3DRMLIGHT_MAX
最大照明モード。
D3DRMRENDER_WIREFRAME
ワイヤフレーム塗りつぶしモードを指定する。
D3DRMRENDER_UNLITFLAT
フラットシェーディングと照明オフを指定する。
D3DRMRENDER_FLAT
フラットシェーディング、照明オン、ソリッド塗りつぶしを指定する。
D3DRMRENDER_GOURAUD
グーローシェーディング、照明オン、ソリッド塗りつぶしを指定する。
D3DRMRENDER_PHONG
このシェーディングモードは実装されていない。デフォルトはグーローシェーディング。
D3DRMSHADE_FLAT
オブジェクトをフラットシェーディングでレンダリングする。これはデフォルト設定である。
D3DRMSHADE_GOURAUD
オブジェクトをグーローシェーディングでレンダリングする。
D3DRMSHADE_PHONG
オブジェクトをフォンシェーディングでレンダリングする。
D3DRMSHADE_MASK
オブジェクトをマスクシェーディングでレンダリングする。
D3DRMSHADE_MAX
オブジェクトを最大のシェーディングでレンダリングする。

注意

レンダリングクオリティとは、デバイスのレンダリングサーフェス上で実行されるレンダリングのクオリティの最大値である。

オブジェクトのクオリティには、3つのコンポーネントがある。つまり、シェーディングモード (フラットまたはグーロー)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

CONST_D3DRMSAVEFLAGS

Direct3DRMMeshBuilder3.Saveメソッドの保存オプションを定義する。

構文

Enum CONST_D3DRMSAVEFLAGS
  D3DRMXOFSAVE_NORMALS            = 1
  D3DRMXOFSAVE_TEXTURECOORDINATES = 2
  D3DRMXOFSAVE_MATERIALS          = 4
  D3DRMXOFSAVE_TEXTURENAMES       = 8
  D3DRMXOFSAVE_ALL                = 15
  D3DRMXOFSAVE_TEMPLATES          = 16 (&H10)
  D3DRMXOFSAVE_TEXTURETOPOLOGY    = 32 (&H20)
End Enum

値

D3DRMXOFSAVE_NORMALS
基本的な面に加え、法線ベクトルを保存する。
D3DRMXOFSAVE_TEXTURECOORDINATES
基本的な面に加え、テクスチャ座標を保存する。
D3DRMXOFSAVE_MATERIALS
基本的な面に加え、マテリアルを保存する。
D3DRMXOFSAVE_TEXTURENAMES
基本的な面に加え、テクスチャの名前を保存する。
D3DRMXOFSAVE_ALL
基本的な面に加え、法線ベクトル、テクスチャ座標、マテリアル、テクスチャの名前を保存する。
D3DRMXOFSAVE_TEMPLATES
ファイルのテンプレートを保存する。デフォルトではテンプレートは保存されない。
D3DRMSAVE_TEXTURETOPOLOGY
メッシュの面ラップ値 (Direct3DRMMeshBuilder3.SetTextureTopologyまたはDirect3DRMFace2.SetTextureTopologyにより設定される)を保存する。このフラグは、SaveメソッドにD3DRMXOFSAVE_ALLを渡した場合には含まれない。すべてを実際に保存したければ、D3DRMSAVE_TEXTURETOPOLOGYとD3DRMXOFSAVE_ALLを渡す。Direct3DRMMeshBuilder3.SetTextureTopologyまたはDirect3DRMFace2.SetTextureTopologyを呼び出し、設定した値を保持したい場合は、このフラグを渡すだけでよい。

CONST_D3DRMSORTMODE

シーンで子フレームをどのようにソートするかを記述する

構文

Enum CONST_D3DRMSORTMODE
  D3DRMSORT_FROMPARENT
  D3DRMSORT_NONE
  D3DRMSORT_FRONTTOBACK
  D3DRMSORT_BACKTOFRONT
End Enum

値

D3DRMSORT_FROMPARENT
子フレームは親フレームのソート順序を継承する。これはデフォルト設定である。
D3DRMSORT_NONE
子フレームはソートされない。
D3DRMSORT_FRONTTOBACK
子フレームは前から後ろへソートされる。
D3DRMSORT_BACKTOFRONT
子フレームは後ろから前へソートされる。

参照

Direct3DRMFrame3.GetSortMode、Direct3DRMFrame3.SetSortMode

CONST_D3DRMSTATECHANGEFLAGS

状態変更のオプションを設定する。

構文

Enum CONST_D3DRMSTATECHANGEFLAGS
  D3DRMSTATECHANGE_UPDATEONLY  = 1
  D3DRMSTATECHANGE_VOLATILE    = 2
  D3DRMSTATECHANGE_NONVOLATILE = 4
  D3DRMSTATECHANGE_RENDER      = 32 (&H20)
  D3DRMSTATECHANGE_LIGHT       = 64 (&H40)
End Enum

値

D3DRMSTATECHANGE_UPDATEONLY
状態変更を示すフラグ。
D3DRMSTATECHANGE_VOLATILE
状態変更を示すフラグ。
D3DRMSTATECHANGE_NONVOLATILE
状態変更を示すフラグ。
D3DRMSTATECHANGE_RENDER
状態変更を示すフラグ。
D3DRMSTATECHANGE_LIGHT
状態変更を示すフラグ。

CONST_D3DRMTEXTURECACHEFLAGS

現在のテクスチャに関するテクスチャ管理システムを制御する。

構文

Enum CONST_D3DRMTEXTURECACHEFLAGS
  D3DRMTEXTURE_FORCERESIDENT         = 1
  D3DRMTEXTURE_STATIC                = 2
  D3DRMTEXTURE_DOWNSAMPLEPOINT       = 4
  D3DRMTEXTURE_DOWNSAMPLEBILINEAR    = 8
  D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH = 16 (&H10)
  D3DRMTEXTURE_DOWNSAMPLENONE        = 32 (&H20)
End Enum

値

D3DRMTEXTURE_FORCERESIDENT
テクスチャを (ハードウェアシナリオ中の) ビデオメモリに保持することを示す。
D3DRMTEXTURE_STATIC
テクスチャが変わらないことを示す。
D3DRMTEXTURE_DOWNSAMPLEPOINT
テクスチャのダウンサンプル時にポイントフィルタリングを使用することを示す。
D3DRMTEXTURE_DOWNSAMPLEBILINEAR
テクスチャのダウンサンプル時に双一次フィルタリングを使用することを示す。
D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH
テクスチャのダウンサンプル時にピクセル深度が減少することを示す。低いビット深度が使用できない場合は、テクスチャのサイズが減少する。
D3DRMTEXTURE_DOWNSAMPLENONE
テクスチャを決してダウンサンプルしないことを示す。デフォルト値は、D3DRMTEXTURE_DOWNSAMPLEPOINTである。

CONST_D3DRMTEXTURECHANGEDFLAGS

テクスチャでの変更を示す。

構文

Enum CONST_D3DRMTEXTURECHANGEDFLAGS
  D3DRMTEXTURE_CHANGEDPIXELS  = 64 (&H40)
  D3DRMTEXTURE_CHANGEDPALETTE = 128 (&H80)
  D3DRMTEXTURE_INVALIDATEONLY = 256 (&H100)
End Enum

値

D3DRMTEXTURE_CHANGEDPIXELS
ピクセル値が変更されたことを示す。
D3DRMTEXTURE_CHANGEDPALETTE
パレットが変更されたことを示す。
D3DRMTEXTURE_INVALIDATEONLY
テクスチャリージョンが無効になったが、アプリケーションで更新する必要がないことを示す。

CONST_D3DRMTEXTUREQUALITY

デバイスがテクスチャのピクセルとビューポートのピクセルを補間する方法を記述する。この列挙型は、Direct3DRMDevice3.SetTextureQualityとDirect3DRMDevice3.GetTextureQualityによって使用される。

構文

Enum CONST_D3DRMTEXTUREQUALITY
  D3DRMTEXTURE_NEAREST
  D3DRMTEXTURE_LINEAR
  D3DRMTEXTURE_MIPNEAREST
  D3DRMTEXTURE_MIPLINEAR
  D3DRMTEXTURE_LINEARMIPNEAREST
  D3DRMTEXTURE_LINEARMIPLINEAR
End Enum

値

D3DRMTEXTURE_NEAREST
テクスチャの最も近いピクセルを選択する。ミップマッピングをサポートしない。
D3DRMTEXTURE_LINEAR
4つの最も近いピクセルを線形に補間する。ミップマッピングをサポートしない。
D3DRMTEXTURE_MIPNEAREST
D3DRMTEXTURE_NEARESTに似ているが、テクスチャの代わりに適切なミップマップを使用する。ピクセルサンプリングとミップマッピングは両方とも最近似である。
D3DRMTEXTURE_MIPLINEAR
D3DRMTEXTURE_LINEARに似ているが、テクスチャの代わりに適切なミップマップを使用する。ピクセルサンプリングは線形である。ミップマッピングは最近似である。
D3DRMTEXTURE_LINEARMIPNEAREST
D3DRMTEXTURE_MIPNEARESTに似ているが、2つの最近似ミップマップ間を補間する。ピクセルサンプリングは最近似である。ミップマッピングは線形である。
D3DRMTEXTURE_LINEARMIPLINEAR
D3DRMTEXTURE_MIPLINEARに似ているが、2つの最近似ミップマップ間を補間する。ピクセルサンプリングとミップマッピングは、両方とも線形である。

CONST_D3DRMTRAVERALFLAGS

現在のフレームの横断状態を示す。

構文

Enum CONST_D3DRMTRAVERALFLAGS
  D3DRMFRAME_RENDERENABLE        = 1
  D3DRMFRAME_PICKENABLE          = 2
  D3DRMFRAME_RENDERANDPICKENABLE = 3
End Enum

値

D3DRMFRAME_RENDERENABLE
このフレームまたはその子フレームをレンダリングする。
D3DRMFRAME_PICKENABLE
このフレームまたはその子フレーム内のビジュアルをピッキングする。
D3DRMFRAME_RENDERANDPICKENABLE
このフレームまたはその子フレーム内のビジュアルをレンダリングおよびピッキングする。

CONST_D3DRMVIEWPORTCLEARFLAGS

クリアオプションを設定する。

構文

Enum CONST_D3DRMVIEWPORTCLEARFLAGS
  D3DRMCLEAR_TARGET     = 1
  D3DRMCLEAR_ZBUFFER    = 2
  D3DRMCLEAR_DIRTYRECTS = 4
  D3DRMCLEAR_ALL        = 7
End Enum

値

D3DRMCLEAR_TARGET
出力先レンダリングサーフェスのみをクリアする。
D3DRMCLEAR_ZBUFFER
zバッファサーフェスのみをクリアする。
D3DRMCLEAR_DIRTYRECTS
使用済み方形リストのみをクリアする。
D3DRMCLEAR_ALL
ターゲット、zバッファ、使用済み方形リストをクリアする。このフラグはDirect3DRMViewport.Clearの使用と類似している

CONST_D3DRMWIREFRAMEFLAGS

ワイヤフレームオプションを設定する。

構文

Enum CONST_D3DRMWIREFRAMEFLAGS
  D3DRMWIREFRAME_CULL       = 1
  D3DRMWIREFRAME_HIDDENLINE = 2
End Enum

値

D3DRMWIREFRAME_CULL
裏に隠された面は、描画されない。
D3DRMWIREFRAME_HIDDENLINE
ワイヤフレームレンダリングされた線は、隣接のオブジェクトで隠される。

CONST_D3DRMWRAPTYPE

Direct3DRM3.CreateWrapメソッドで作成されたDirect3DRMWrapオブジェクトのタイプを定義する。

構文

Enum CONST_D3DRMWRAPTYPE
  D3DRMWRAP_FLAT
  D3DRMWRAP_CYLINDER
  D3DRMWRAP_SPHERE
  D3DRMWRAP_CHROME
End Enum

値

D3DRMWRAP_FLAT
ラップは平面である。
D3DRMWRAP_CYLINDER
ラップは円柱である。
D3DRMWRAP_SPHERE
ラップは球体である。
D3DRMWRAP_CHROME
ラップは、テクスチャがオブジェクト上で反射されるようにテクスチャ座標を割り当てる。

CONST_D3DRMXOFFORMAT

Direct3DRMMeshBuilder3.Saveメソッドで使用されるファイルタイプを定義する。

構文

Enum CONST_D3DRMXOFFORMAT
  D3DRMXOF_BINARY
  D3DRMXOF_COMPRESSED
  D3DRMXOF_TEXT
End Enum

値

D3DRMXOF_BINARY
ファイルはバイナリフォーマットである。これはデフォルト設定である。
D3DRMXOF_COMPRESSED
現在はサポートされていない。
D3DRMXOF_TEXT
ファイルはテキストフォーマットである。

注意

D3DRMXOF_BINARYとD3DRMXOF_TEXT設定を同時に使用することはできない。

CONST_D3DRMZBUFFERMODE

Zバッファが有効かどうかを示す。

構文

Enum CONST_D3DRMZBUFFERMODE
  D3DRMZBUFFER_FROMPARENT
  D3DRMZBUFFER_ENABLE
  D3DRMZBUFFER_DISABLE
End Enum

値

D3DRMZBUFFER_FROMPARENT
フレームは親フレームからZバッファの設定を継承する。これはデフォルト設定である。
D3DRMZBUFFER_ENABLE
Zバッファは有効である。
D3DRMZBUFFER_DISABLE
Zバッファは無効である。

参照

Direct3DRMFrame3.GetZbufferMode、Direct3DRMFrame3.SetZbufferMode


Visual Basicの型

Microsoft® Direct3D® 保持モードの Microsoft Visual Basic® の型は以下のとおりである。

  • D3DRMANIMATIONKEY
  • D3DRMBOX
  • D3DRMMATERIALOVERRIDE
  • D3DRMPICKDESC
  • D3DRMPICKDESC2
  • D3DRMPMESHLOADSTATUS
  • D3DRMQUATERNION
  • D3DRMRAY
  • D3DRMVECTOR4D
  • D3DRMVERTEX

D3DRMANIMATIONKEY

Direct3DRMAnimation2.AddKey、GetKeys、およびModifyKeyメソッドが使用するキーを定義する。

構文

Type D3DRMANIMATIONKEY
  x As Single
  y As Single
  z As Single
  s As Single
  dvTime As Single
  lID As Long
  lKeyType As Long
End Type

メンバ

x
ベクトルを定義するx値。
y
ベクトルを定義するy値。
z
ベクトルを定義するz値。
s
回転キーで使用されるラジアン単位の角度。
dvTime
任意の単位の時間値。
lID
キー識別子。
lKeyType
キーのタイプ。アニメーションの再生方法を定義する。

注意

メンバのx、y、z、およびsは、それぞれD3DRMQUATERNION型のメンバ [x, y, z, s] か、D3DVECTOR型のメンバ [x, y, z] を表す。回転キーは回転を定義するD3DRMQUATERNION 型、スケールキーはスケールを定義するD3DVECTOR型の値、そして位置キーは位置を定義するD3DVECTOR型の値である。特定のインスタンスで有効なキーは、1つだけである。

D3DRMBOX

Direct3DRMMesh.GetBoxとDirect3DRMMeshBuilder3.GetBoxメソッドによって取得される境界ボックスを定義する。

構文

Type D3DRMBOX
  max As D3DVECTOR
  min As D3DVECTOR
End Type

メンバ

min, max
ボックスの境界を定義する値。これらの値はD3DVECTOR型である。

D3DRMMATERIALOVERRIDE

Direct3DRMFrame3.SetMaterialOverrideとDirect3DRMFrame3.GetMaterialOverrideメソッドのオーバーライドを記述する。

構文

Type D3DRMMATERIALOVERRIDE
  dcAmbient As D3DCOLORVALUE
  dcDiffuse As D3DCOLORVALUE
  dcEmissive As D3DCOLORVALUE
  dcSpecular As D3DCOLORVALUE
  dvPower As Single
  lFlags As Long
End Type

メンバ

dcAmbient
D3DCOLORVALUE型のアンビエントRGBカラー設定。
dcDiffuse
D3DCOLORVALUE型の拡散RGBAカラー設定。
dcEmissive
D3DCOLORVALUE型の放射RGBカラー設定。
dcSpecular
D3DCOLORVALUE型の反射RGBカラー設定。
dvPower
強度設定。
lFlags
この型のどのフィールドが有効かを示す、フラグの論理的組み合わせ。可能な値は以下のとおりである。
D3DRMMATERIALOVERRIDE_ALL
D3DRMMATERIALOVERRIDE_AMBIENT
D3DRMMATERIALOVERRIDE_DIFFUSE
D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAONLY
D3DRMMATERIALOVERRIDE_DIFFUSE_RGBONLY
D3DRMMATERIALOVERRIDE_EMISSIVE
D3DRMMATERIALOVERRIDE_POWER
D3DRMMATERIALOVERRIDE_SPECULAR
D3DRMMATERIALOVERRIDE_TEXTURE

D3DRMPICKDESC

Direct3DRMPickArray.GetPickFrameメソッドによって取得された、ピックの位置、面、グループ識別子を格納する。

構文

Type D3DRMPICKDESC
  lFaceIdx As Long
  lGroupIdx As Long
  vPosition As D3DVECTOR
End Type

メンバ

lFaceIdx
取得されたオブジェクトの面のインデックス。
lGroupIdx
取得されたオブジェクトのグループのインデックス。
vPosition
取得されたオブジェクトの位置を示す値。この値はD3DVECTOR型である。

D3DRMPICKDESC2

Direct3DRMPick2Array.GetPickFrameメソッドによって取り出された面やグループの識別子、ピックの位置、頂点の水平および垂直テクスチャ座標、頂点の法線およびオブジェクトの色を格納する。

構文

Type D3DRMPICKDESC2
  lFaceIdx As Long
  lGroupIdx As Long
  vPosition As D3DVECTOR
  tu As Single
  tv As Single
  vNormal As D3DVECTOR
  color As Long
End Type

メンバ

lFaceIdx
取得されたオブジェクトの面のインデックス。
lGroupIdx
取得されたオブジェクトのグループのインデックス。
vPosition
取得されたオブジェクトの位置を示す値。この値はD3DVECTOR型である。
tu, tv
頂点の水平および垂直テクスチャ座標。
vNormal
頂点の法線ベクトル。この値はD3DVECTOR型である。
color
頂点の色。オブジェクトの色をアルファ要素を含めて指定するには、オブジェクト上のDirectX7インターフェイスからCreateColorRGBAメソッドを呼び出す。

D3DRMPMESHLOADSTATUS

Direct3DRMProgressiveMesh.LoadFromFileメソッドを使用してロードされたプログレッシブメッシュのロード状態を格納する。この型は、Direct3DRMProgressiveMesh.GetLoadStatusメソッドを使用して取得できる。

構文

Type D3DRMPMESHLOADSTATUS
  lBytesLoaded As Long
  lVerticesLoaded As Long
  lFacesLoaded As Long
  lFlags As Long
End Type

メンバ

lBytesLoaded
ロードされた合計バイト数。
lVerticesLoaded
ロードされた頂点の数。
lFacesLoaded
ロードされた面の数。
lFlags
プログレッシブメッシュロードの状態を示すフラグ。以下の値の1つを取ることができる。
D3DRMPMESHSTATUS_VALID
プログレッシブメッシュオブジェクトは、有効なデータを含む。
D3DRMPMESHSTATUS_INTERRUPTED
ダウンロードは、アプリケーションがDirect3DRMProgressiveMesh.Abortを使ったか、または接続が失われたかのいずれかの理由で割込みを受けた。
D3DRMPMESHSTATUS_BASEMESHCOMPLETE
ベースメッシュのダウンロードが完了した。
D3DRMPMESHSTATUS_COMPLETE
すべてのデータのダウンロードが完了した。
D3DRMPMESHSTATUS_RENDERABLE
メッシュのレンダリングは、現在可能である。

D3DRMQUATERNION

Direct3DRMAnimation2.AddRotateKeyメソッドで用いられる回転と、Direct3DRMFrame3.SetQuaternionで用いられる4元数を記述する。また、Direct3Dの数学関数のいくつかでも使用される。

構文

Type D3DRMQUATERNION
  s As Single
  v As D3DVECTOR
End Type

メンバ

s
角度。
v
この値はD3DVECTOR型である。

D3DRMRAY

光線の方向と開始位置をDirect3DRMFrame3.RayPickメソッドで定義する。

構文

Type D3DRMRAY
  dir As D3DVECTOR
  pos As D3DVECTOR
End Type

メンバ

dir
光線ピックで用いられる光線の方向。この値はD3DVECTOR型である。
pos
光線ピックで用いられる光線の開始位置。この値はD3DVECTOR型である。

D3DRMVECTOR4D

スクリーン座標を記述する。これらの座標は、Direct3DRMViewport2.Transformメソッドによる変換の出力先として、およびDirect3DRMViewport2.InverseTransformメソッドによる変換のソースとして使用される。

構文

Type D3DRMVECTOR4D
  x As Single
  y As Single
  z As Single
  w As Single
End Type

メンバ

x, y, z, w
同種の値を示す変数。これらの値は、変換結果を定義する。

D3DRMVERTEX

Direct3DRMMeshオブジェクト中の頂点を記述する。

構文

Type D3DRMVERTEX
  position As D3DVECTOR
  normal As D3DVECTOR
  tu As Single
  tv As Single
  color As Long
End Type

メンバ

position
頂点の位置。この値はD3DVECTOR型である。
normal
頂点の法線ベクトル。この値はD3DVECTOR型である。
tu, tv
頂点の水平および垂直テクスチャ座標。
color
頂点の色。オブジェクトの色をアルファ要素を含めて指定するには、オブジェクト上のDirectX7インターフェイスからCreateColorRGBAメソッドを呼び出す。

参照

Direct3DRMMesh.GetVertices、Direct3DRMMesh.SetVertices


Visual Basicエラー値

Microsoft® Direct3D® 保持モードのインターフェイスのメソッドは、Microsoft Visual Basic® で以下の値を返す。

D3DRM_OK
成功。DD_OKと同等。
D3DRMERR_BADALLOC
メモリ不足。
D3DRMERR_BADDEVICE
デバイスはレンダラと互換性がない。
D3DRMERR_BADFILE
データファイルが不正。
D3DRMERR_BADMAJORVERSION
DLLのメジャーバージョンが不正。
D3DRMERR_BADMINORVERSION
DLLのマイナーバージョンが不正。
D3DRMERR_BADOBJECT
引数にはオブジェクトが必要。
D3DRMERR_BADPMDATA
.xファイル中のデータが不正。プログレッシブメッシュへの変換は成功したが、無効なプログレッシブメッシュが.xファイルに作成された。
D3DRMERR_BADTYPE
不正な型の引数が渡された。
D3DRMERR_BADVALUE
不正な値の引数が渡された。
D3DRMERR_BOXNOTSET
境界ボックスがフレームに設定されてないときに、境界ボックスにアクセスしようとした(たとえば、Direct3DRMFrame3.GetBoxを用いて)。
D3DRMERR_CLIENTNOTREGISTERED
クライアントが登録されていない。
D3DRMERR_CONNECTIONLOST
ロード、クローンまたは複製中にデータ接続が失われた。
D3DRMERR_ELEMENTINUSE
使用中は要素の修正または削除はできない。サブメッシュを空にするには、その親に対して Direct3DRMMeshBuilder3.Emptyを呼び出す。
D3DRMERR_ENTRYINUSE
頂点または法線エントリは現在面が使用中であり、削除できない。
D3DRMERR_FACEUSED
面はメッシュ上で使用済みである。
D3DRMERR_FILENOTFOUND
指定された場所にファイルが見つからない。
D3DRMERR_INCOMPATIBLEKEY
指定されたアニメーションキーは互換性がない。キーを修正することはできない。
D3DRMERR_INVALIDLIBRARY
指定されたライブラリは無効である。
D3DRMERR_INVALIDOBJECT
メソッドが、無効なオブジェクトを受け取った。
D3DRMERR_INVALIDPARAMS
メソッドに渡されたパラメータが少なくとも1つ無効である。
D3DRMERR_LIBRARYNOTFOUND
指定されたライブラリが見つからない。
D3DRMERR_LOADABORTED
ロードがユーザによって強制終了させられた。
D3DRMERR_NOSUCHKEY
指定されたアニメーションキーは存在しない。
D3DRMERR_NOTCREATEDFROMDDS
指定されたテクスチャがMicrosoft DirectDraw®サーフェスから作成されていない。
D3DRMERR_NOTDONEYET
エラーフラグが実装されていない。
D3DRMERR_NOTENOUGHDATA
要求された処理を行うために十分なデータがロードされていない。
D3DRMERR_NOTFOUND
指定された場所にオブジェクトが見つからない。
D3DRMERR_OUTOFRANGE
指定された値は範囲外である。
D3DRMERR_PENDING
要求された情報を供給するために必要なデータのロードが終了していない。
D3DRMERR_REQUESTTOOLARGE
利用可能な最大詳細レベルよりも大きな詳細レベルをプログレッシブメッシュに設定しようとした。
D3DRMERR_REQUESTTOOSMALL
ベースメッシュの詳細よりも小さなプログレッシブメッシュの最低レンダリング詳細を設定しようとした (レンダリングの最小値)。
D3DRMERR_TEXTUREFORMATNOTFOUND
指定された基準を満たし、下層の直接モードデバイスがサポートするテクスチャフォーマットが見つからなかった。
D3DRMERR_UNABLETOEXECUTE
プロシージャを実行できない。
DD_OK
要求は成功し完了した。D3DRM_OKと同等。
DDERR_INVALIDOBJECT
無効なオブジェクトのポインタを受け取った。
DDERR_INVALIDPARAMS
Oメソッドに渡された1つ以上のパラメータが不正である。
DDERR_NOTFOUND
要求された項目が見つからなかった。
DDERR_NOTINITIALIZED
オブジェクトが初期化される前に、オブジェクトのインターフェイスメソッドを呼び出そうとした。
DDERR_OUTOFMEMORY
DirectDrawが処理を行うのに十分なメモリがない。


Visual Basicプログラマのための追加情報

この項には、Microsoft® Direct3D® 保持モードの Microsoft Visual Basic®リファレンスに関する次のトピックが含まれる。

  • カラーキーイング
  • CONST_D3DCOLORMODEL
  • D3DCOLOR_MONO
  • D3DCOLOR_RGB
  • D3DCOLORVALUE
  • D3DMATRIX
  • D3DPRIMCAPS
  • D3DRECT
  • D3DTRIANGLE
  • D3DVECTOR
  • DirectDrawCreate
  • DirectDrawCreateClipper
  • Direct3D3
  • DirectDrawClipper
  • インターポレータ
  • ミップマップ
  • テクスチャマップフォーマット

カラーキーイング
カラーキーは、一般にはアーティストが透明性のためにしか使用しない単一で共通性のない色であるが、これを指定した色範囲にすることもできる。DirectDrawSurface4.SetColorKeyメソッドを使用して、サーフェスのカラーキーをセットすることができる。カラーキーをセットすると、DirectDrawSurface3.BltFastに対する後続の呼び出しはそのカラーキーを活用し、一致するピクセルを無視する。このタイプのカラーキーは、ソースカラーキーと呼ばれる。ソースカラーキーは「透明」なピクセルが出力先に書き込まれないようにするため、オリジナルの背景ピクセルはこれらの場所に保存され、非方形オブジェクトであるスプライトが背景を横切っているかのように見える。出力先サーフェスに効果を与えるカラーキー (出力先カラーキー) を使用することもできる。

出力先カラーキーは、スプライトで上書き可能なピクセルに使用されるサーフェス上の色である。再度、アーティストは、イメージ中の他の場所で使用されていない任意の色を選択し、ブロック転送可能なイメージの一部としてそれを予約する。指定された出力先カラーキーによってスプライトを出力先サーフェスにブロック転送すると、スプライトのピクセルは、出力先カラーキーを使用中の出力先上のピクセルにのみブロック転送される。法線の出力先ピクセルは保存されているので、スプライトが出力先サーフェス上のイメージの背後を横切っているかのように見える。詳細については、 DirectX Foundation SDKの「DirectDrawの要点」セクションの「サーフェス」の項内の「透過型ブロック転送」を参照すること。

CONST_D3DCOLORMODEL
デバイスによって実装されるカラーモデルを記述する列挙型。

構文

Enum CONST_D3DCOLORMODEL
  D3DCOLOR_MONO = 1
  D3DCOLOR_RGB  = 2
End Enum
D3DCOLOR_MONO
モノクロモデル (ランプモデル) の使用をシステムに指示するCONST_D3DCOLORMODEL列挙型からの値。このモデルでは、頂点の色の青要素を使用して、照らされる頂点の輝度を定義する。
D3DCOLOR_RGB
フルRGBモデルの使用をシステムに指示するCONST_D3DCOLORMODEL列挙型からの値。
D3DCOLORVALUE
色の値を記述する型。r、g、b、a は、色の赤、緑、青、アルファ要素を指定する。これらの値は、一般には0.0から1.0の範囲にあり、0.0は黒を指定する。

構文

Type D3DCOLORVALUE
  r As Single
  g As Single
  b As Single
  a As Single
End Type
D3DMATRIX
行列を記述する型。

構文

Type D3DMATRIX
  rc11 As Single, rc12 As Single, rc13 As Single, rc14 As Single
  rc21 As Single, rc22 As Single, rc23 As Single, rc24 As Single
  rc31 As Single, rc32 As Single, rc33 As Single, rc34 As Single
  rc41 As Single, rc42 As Single, rc43 As Single, rc44 As Single
End Type
D3DPRIMCAPS
各プリミティブタイプの機能を定義する型。詳細については、「DirectX Foundation SDK」を参照すること。
D3DRECT
方形を定義する型。

構文

Type D3DRECT
  x1 As Long
  x2 As Long
  y1 As Long
  y2 As Long
End Type
D3DTRIANGLE
すべての三角形のベースタイプを記述する型。三角形は主要なレンダリングプリミティブである。
D3DVECTOR
Microsoft® Direct3D® とDirect3D保持モードの多くのメソッドと型のベクトルを定義する型。

構文

Type D3DVECTOR
  x As Single
  y As Single
  z As Single
End Type
DirectDrawCreate
DirectDrawオブジェクトのインスタンスを作成する関数。
DirectDrawCreateClipper
DirectDrawオブジェクトと関連付けられていないDirectDrawClipperオブジェクトのインスタンスを作成する関数。
Direct3D3
アプリケーションは、Direct3D3インターフェイスのメソッドを使用してDirect3Dオブジェクトを作成し、環境をセットする。
Direct3D3.GetDevicesEnum
このメソッドは、システムに導入済みのすべてのDirect3Dデバイスドライバを列挙する。
DirectDrawClipper
アプリケーションは、IDirectDrawClipperインターフェイスのメソッドを使用して、クリップリストを管理する。
DirectDrawClipper.SetHWnd
このメソッドは、クリッピング情報を取得するウィンドウハンドルをセットする。
インターポレータ
インターポレータは、アクションを格納した後、中間値を自動計算して、オブジェクトにアクションを適用する方法を提供する。たとえば、ユーザは時間0で赤を、時間10で緑をシーンの背景色にセットすることができる。その後、インターポレータは自動的に、連続するシーンに色合いを付けて赤から緑に混合するようにできる。インターポレータを使用して、色を混合し、異なる位置間でオブジェクトを円滑に移動し、メッシュをモーフィングし、さらに、ほかのさまざまな変換も行うことができる。

Direct3D保持モードでは、インターポレータは、ユーザがアニメーションできるオブジェクトパラメータの種類を増やすDirect3DRMAnimation2インターフェイスの一般化である。Direct3DRMAnimation2インターフェイスがオブジェクトの位置、サイズおよび方向のアニメーションを可能にする一方で、インターポレータインターフェイスは、さらに、色、メッシュ、テクスチャ、マテリアルのアニメーションを可能にする。

インターポレータキー
インターポレータによって格納されたアクションをキーと呼ぶ。キーは、格納されたプロシージャ呼び出しで、それに関連したインデックスを持つ。インターポレータは、自動的に中間のキー値を計算する。 サポートされているインターポレート可能なインターフェイスメソッドの1つを呼び出して、キーをインターポレータの中に格納する。メソッドとメソッドに渡されるパラメータ値がキーを構成する。 インターポレータ内部に格納されている各キーには、インデックス値がある。キーが記録されるとき、キーには、現在のインターポレータインデックス値のスタンプが押される。このキーのインデックス値は、この値をいったん設定すると絶対に変ることはない。
インターポレータのタイプ
オブジェクトを関連タイプのインターポレータに接続することができる。たとえば、Direct3DRMMeshオブジェクトは、Direct3DRMMeshInterpolatorオブジェクトに接続できる。インターポレータのタイプは次のとおりである。
  • FrameInterpolator
  • LightInterpolator
  • MaterialInterpolator
  • MeshInterpolator
  • TextureInterpolator
  • ViewportInterpolator

あるインターポレータを別のインターポレータに接続できる。インターポレータのインデックスを変更すると、接続されたインターポレータのインデックスが同じ値に設定される。

Direct3DRMMeshInterpolatorでは、Direct3DRMMeshInterpolatorオブジェクトのDirect3DRMMeshインターフェイス上にあるSetVerticesを呼び出すことにより、Direct3DRMMeshInterpolatorオブジェクトにSetVerticesキーを追加する。 SetVerticesと共に使用されるグループインデックスは、Direct3DRMMesh オブジェクトまたはインターポレータが適用されているオブジェクトの有効なグループインデックスに対応していなければならない。

インターポレータのインデックス値
インターポレータは、ある範囲のインデックス値を受け付ける。インデックス範囲は、次の規則によって決まる。
  • 範囲の始点は、すべてのキーインデックス値と現在のインデックスの中の最小値である。
  • 範囲の終点は、すべてのキーインデックス値と現在のインデックスの中の最大値である。

補間オプションの詳細については、CONST_D3DRMINTERPOLATIONFLAGS列挙型を参照すること。

ミップマップ
ミップマップとは連続したテクスチャで、それぞれのテクスチャは解像度が漸次低くなる、同じイメージを事前にフィルタリングした表現である。ミップマップ中の各フィルタリングイメージまたはレベルは、以前のレベルより2の累乗ずつ小さくなっている。高解像度レベルは、ビューアに近いオブジェクトに使用される。オブジェクトが遠くに移動するにつれ、より低解像度のレベルが使用される。ミップマッピングは、テクスチャのレンダリングクオリティを向上する、計算上費用のかからない方法である。詳細については、「Direct3D直接モード」の「テクスチャ」の「ミップマップ」を参照すること。
テクスチャマップフォーマット
広範なテクスチャピクセルフォーマットが、Microsoft DirectX® ハードウェアエミュレーションレイヤでサポートされている。これらのフォーマットについては、「DirectX Foundation DirectDrawリファレンス」の「テクスチャマップフォーマット」の表を参照すること。


サンプルのイントロダクション

この節では、Microsoft Developer Studio™を使用して、Microsoft® Direct3D®保持モードのサンプルを構築する方法を説明する。サンプルの解説を読み、参照するサンプルを決めること。

  • Developer Studio 5.0を使用したサンプルの構築
  • サンプル


Developer Studio 5.0を使用したサンプルの構築

Microsoft® DirectX® Software Devepoler Kitに同梱されているサンプルには、コマンドラインでサンプルを構築するmakefileが含まれている。サンプルを実行すると、内容が確認できる。興味のあるサンプルについては、理解を深め、コードを変更する。Microsoft Developer Studio™を使用して、サンプル(またはユーザのコード)を構築してデバッグするには、Developer Studioでプロジェクトを作成する。この項では、Developer Studio Version 5.0でプロジェクトを作成する方法について説明する。プロジェクトファイルには、必要なソースファイルとライブラリをインクルードし、Developer Studioを適切なライブラリで構成し、パスをインクルードして、コンパイラが必要なライブラリとヘッダファイルを検出できるようにする必要がある。

注 サンプルをコマンドラインで構築する情報については、DirectX SDK Samples ディレクトリのreadme.txtを読むこと。

この項では、次の項目について説明する。

  • ツールオプション
  • 新しいプロジェクトの作成
  • プロジェクトの設定
  • ライブラリの追加
  • 作業ディレクトリの設定
  • ファイルをプロジェクトに追加

ツールオプション

Developer Studioを使用するには、DirectX SDKのヘッダファイルとライブラリファイルを格納しているパスを指定する必要がある。ここでの設定は、Developer Studioのグローバルな設定になり、プロジェクトごとに設定を繰り返す必要はない。

以下の手順に従って、DirectX SDKのヘッダファイルとライブラリファイルの格納先ディレクトリをインクルードおよびライブラリファイルの検索パスに追加する。

  1. Developer Studioの [ツール] メニューの [オプション] をクリックする。
  2. [ディレクトリ] タブをクリックする。
  3. [表示するディレクトリ] ボックスの [インクルード ファイル] をクリックする。
  4. [ディレクトリ] ボックスの点線で囲まれた四角形のボタンをクリックして、DirectX SDKのインクルードディレクトリをフルパスで入力する。または、四角形のボタンをクリックした際にエントリフィールドの右側に表示される"..."(参照) ボタンをクリックして、適切なディレクトリに移動する。ヘッダ (インクルード) ファイルは、デフォルトでc:\mssdk\includeにインストールされている。
  5. Enterキーを押して、入力を完了する。必要に応じて、新しいエントリを再び選択し、入力したディレクトリ名が一覧の一番上に移動するまで、 [アイテムを上へ移動] ボタン (アイテムを上へ移動) をクリックする。こうすると、DirectXファイルが検索パスの先頭に入り、ファイル名の複製で使用されるようになる。

    次の画面は、[オプション] ダイアログボックスの [ディレクトリ] タブを示している。デフォルトのインクルードディレクトリがディレクトリ一覧の一番上にある。

    [オプション] ダイアログ ボックスの [ディレクトリ] タブ

  6. インクルードディレクトリを追加したら、ライブラリディレクトリを追加する。[表示するディレクトリ] ボックスの [ライブラリ ファイル] をクリックする。
  7. [ディレクトリ] ボックスの点線で囲まれた四角形のボタンをクリックして、DirectX SDKのライブラリディレクトリをフルパスで入力する。または、"..."(参照) ボタンをクリックして、検索パスを指定する。ライブラリファイルは、デフォルトではc:\mssdk\libにインストールされている。
  8. Enterキーを押して入力を完了する。必要に応じて、新しいエントリを再び選択し、入力したアイテムがディレクトリ一覧の一番上に移動するまで、[アイテムを上へ移動] ボタンをクリックする。

新しいプロジェクトの作成

新しいプロジェクトを作成するには、次の手順に従う。

  1. Developer Studioの [ファイル] メニューの [新規作成] をクリックする。
  2. [プロジェクト] タブをクリックする。
  3. 適切なプロジェクトタイプをクリックする。Windows®アプリケーションを作成するには、[Win32 Application] をクリックする。
  4. プロジェクト名を入力する。
  5. 場所を指定してプロジェクトへのパスを編集するか、または、"..."(参照) ボタンをクリックして、ディレクトリを指定する。プロジェクト名がパスに追加されることに注意する。

プロジェクトの設定

この節では、適切なライブラリをプロジェクトに追加し、作業ディレクトリを設定する手順を説明する。作業を進める前に、Developer Studioでプロジェクトを開く。

ライブラリの追加

  1. Developer Studioの [プロジェクト] メニューの [設定] をクリックする。
  2. [リンク] タブをクリックする。
  3. [カテゴリ] ボックスの [一般] をクリックする。
  4. [設定の対象] ボックスの [すべての構成] をクリックする。
  5. [オブジェクト/ライブラリ モジュール] ボックスにプロジェクトに必要なライブラリの名前を入力する。ライブラリ名は通常、一覧の先頭に記述し、定義がコアライブラリから最初に選択されるようにする。

    必要なライブラリは、コードで使用する技術により、プロジェクトごとに異なる。特定のサンプルに必要なライブラリが分からない場合は、サンプルディレクトリにあるmakefileを検索して、同じライブラリリストをインクルードする。次の表は、DirectX SDKで一般的にインクルードされるライブラリの一覧である。Platform SDKでインクルードするWinmm.lib ライブラリは、マルチメディア機能も追加する。
    DirectDraw | ddraw.lib
    Direct3D保持モード | d3drm.lib
    DirectSound | dsound.lib
    DirectPlay | dplayx.lib
    DirectInput | dinput.lib

    たとえば、Tex1サンプルのmakefileは、Microsoft DirectDraw®とDirect3D®保持モードを使用するため、ddraw.libとd3drm.libの一覧を表示する。

次の画面は、[プロジェクトの設定] ダイアログボックスの [リンク] タブを示している。すべての構成の設定が指定され、マルチメディアとDirectX ライブラリが、Developer Studioのデフォルトの [オブジェクト/ライブラリ モジュール] リストに追加されている。

[プロジェクトの設定] ダイアログ ボックスの [リンク] タブ

作業ディレクトリの設定

作業ディレクトリを設定して、プログラムが特定のファイルを検出できるようにする必要がある。たとえば、プログラムが常駐するディレクトリから、画像をロードする必要がある。デフォルトでは、Developer Studioは現在の作業ディレクトリをプログラムが常駐するディレクトリではなく、Developer Studioが常駐するディレクトリに設定する。

作業ディレクトリを設定するには、次の手順に従う。

  1. Developer Studioの [プロジェクト] メニューの [設定] をクリックする。
  2. [デバッグ] タブをクリックする。
  3. [設定の対象] ボックスで適切な構成 (たとえば、[すべての構成] または [Win32 Debug]) をクリックする。
  4. [作業用のディレクトリ] ボックスに作業ディレクトリをフルパスで入力する。

次の画面は、[プロジェクトの設定] ダイアログボックスの [デバッグ] タブを示している。Win32 Debug 構成の作業用ディレクトリが指定されている。

[プロジェクトの設定] ダイアログ ボックスの [デバッグ] タブ

ファイルをプロジェクトに追加

必要なファイルをプロジェクトに追加するには、次の手順に従う。作業を進める前に、Developer Studioを開いておく。

  1. Developer Studioの [プロジェクト] メニューの [プロジェクトへ追加] をポイントする。
  2. ファイルを新規作成する場合は、[新規作成] をクリックし、ファイルタイプを選択して、ファイル名を指定する。
  3. 既存のファイルを開いている場合は、[ファイル] をクリックして、プロジェクトに追加するファイルを選択する。
  4. すべてのソースファイル (.cppまたは.c ファイル)、リソースファイル (.rc ファイル)、その他の必要なファイルをすべて追加するまで、以上の手順を繰り返す。
  5. Developer Studioの [ファイル] メニューの [すべて保存] をクリックして、ソースコード、プロジェクトファイル、作業スペースなどのすべてのファイルを保存する。


サンプル

この項では、Microsoft® Direct3D®保持モードのサンプルについて解説する。各サンプルの要約では、サンプルごとに、Microsoft DirectX®ソフトウェア開発キット (SDK) にデフォルトでインストールされるディレクトリとサンプルの簡単な説明を示してある。

Direct3D保持モードのサンプルは、RMBegin1、RMBegin2、RMEnum、Viewerを除き、すべてのサンプルがRMMainヘルパコードを使用している。RMMainヘルパコードを使用する全サンプルは、Rmmain.cppによってアプリケーションのメインウィンドウを提供し、Rmmain.rcによってメニューとアクセラレータを提供する。これらのサンプルは、Ddraw.libおよびD3drm.lib librariesにもリンクしている。サンプルの各ディレクトリには、Microsoft Developer Studioのプロジェクトファイル (.dsp) がインクルードされる。.dspファイルは、Developer Studioで開き、サンプルを構築するために使用できる。

Direct3D保持モードを初めて使用する場合は、最初にRMBegin1、RMBegin2、RMEnum、Egg、Globe、Hier1、およびTex1サンプルを参照すること。

次の項目では、サンプルコードを順を追って詳述している。

  • オブジェクトの回転：RMBegin1サンプル
  • フレーム階層：RMBegin2サンプル
  • デバイスの列挙：RMEnumサンプル

サンプル一覧

  • Egg
  • Faces
  • Fly
  • Globe
  • Hier1
  • Hier2
  • Morph
  • Quat
  • RMBegin1
  • RMBegin2
  • RMEnum
  • RMMain
  • Shadow
  • Tex1
  • Tex3
  • Tex4
  • Tex5
  • Trans
  • Uvis
  • Viewer

一部のDirectX Foundation SDKサンプルは、複数の技術を使用している。これらのサンプルを参照して、各技術がどのように連係しているか確認することができる。たとえば、DS3dView DirectSoundサンプルは、Direct3D保持モードの3DオブジェクトであるViewerサンプルの単純な拡張である。DS3dViewを使用すると、サウンドをオブジェクトにアタッチし、オブジェクトを3次元空間で移動できる。

Egg

パス

mssdk\samples\multimedia\d3drm\src\Egg

説明

このサンプルは、単一のメッシュオブジェクトで構成した単純なDirectXファイルをロードする。Egg.xはDxsdk\Mediaディレクトリに格納されている。このサンプルは、シーンの照明の初期化、メッシュファイルのロード、シーン上のeggフレームの作成、メッシュのフレームへの追加、フレームの位置、方向、回転の設定を行う。サンプルは、IDirect3DRM3 (CreateFrame、CreateLightRGB、CreateMeshBuilder)、IDirect3DRMFrame3 (SetPosition、AddLight、SetRotation、AddVisual、SetOrientation)、IDirect3DRMMeshBuilder3 (Load) のメソッドを使用している。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

Faces

パス

mssdk\samples\multimedia\d3drm\src\Faces

説明

このサンプルでは、メッシュオブジェクトを1回につき1つの面を作成する。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib.

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

Fly

パス

mssdk\samples\multimedia\d3drm\src\Fly

説明

このサンプルは、アニメーションを使用して、カーブしたパスに沿って、宇宙船の位置を設定する。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

Globe

パス

mssdk\samples\multimedia\d3drm\src\Globe

説明

このサンプルは、テクスチャを伴う単純な単一のメッシュで構成したDirectXファイルをロードする。これは以下のメソッドを使用する。

  • IDirect3DRM3
    • CreateFrame
    • CreateLightRGB
    • CreateMeshBuilder
    • CreateMaterial
    • CreateWrap
    • LoadTexture
    • CreateAnimation
  • IDirect3DRMFrame3
    • GetScene
    • LookAt
    • SetPosition
    • AddLight
    • SetOrientation
    • SetRotation
    • AddVisual
    • AddMoveCallback
    • AddDestroyCallback
  • IDirect3DRMMeshBuilder3
    • Load
    • SetMaterial
    • Scale
    • SetColorRGB
    • GetBox
    • SetTexture
  • IDirect3DRMAnimation
    • SetFrame
    • SetTime
    • SetOptions
    • AddPositionKey
  • IDirect3DRMWrap
    • Apply
  • IDirect3DRMTexture3
    • SetShades

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

Hier1

パス

mssdk\samples\multimedia\d3drm\src\Hier1

説明

このサンプルは、2つのメッシュで構成する単純な階層を作成し、フレームの概念を具体的に示す。シーンの照明を初期化し、2本のメッシュファイルをロードし、フレーム階層 (フレーム内のフレーム) 作成する。Hier1はテクスチャをロードし、メッシュにラッピングし、メッシュをフレームに追加し、フレームの位置、方向、回転を設定する。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

参照

Hier2

Hier2

パス

mssdk\samples\multimedia\d3drm\src\Hier2

説明

このサンプルは、4つのメッシュで構成する単純な階層を具体的に示している。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

参照

Hier1

Morph

パス

mssdk\samples\multimedia\d3drm\src\Morph

説明

このサンプルは、補間の使用法を示している。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

参照

IDirect3DRMInterpolator

Quat

パス

mssdk\samples\multimedia\d3drm\src\Quat

説明

このサンプルは、クォータニオンを使用して、空間内の2本のベクトルを補間する。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

RMBegin1

パス

mssdk\samples\multimedia\d3drm\src\RMBegin1

説明

このサンプルは、Direct3D保持モードのデフォルトデバイスの作成、DirectXファイルからのメッシュのロード、照明の追加、メッシュオブジェクト回転の「要点」を示している。サンプルコード全体に丁寧なコメントを付けて、コードの目的を説明している。

このサンプルは、大部分のDirect3D保持モードサンプルと異なり、RMMainヘルパファイル、Rmmain.cpp、Rmmain.rcが提供する拡張メニューを使用しない。

RMBegin1サンプルのコードの詳細は、「オブジェクトの回転: RMBegin1サンプル」を参照すること。

RMBegin1サンプルコードから構築したサンプルについては、RMBegin2を参照すること。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

RMBegin2

パス

mssdk\samples\multimedia\d3drm\src\RMBegin2

説明

このサンプルは、フレーム階層の「要点」を示している。DirectXファイルから3つのオブジェクトをロードし、スケーリング、照明、マッピングを行う。3つのオブジェクトは、太陽、地球、月を表し、月は地球のまわりを、地球と月は太陽のまわりを回る。このサンプルは、RMBegin1サンプルで使用したコードから構築したものである。RMBegin1の上により複雑なシーンを構築し、ウィンドウサイズを変更し、WM_ACTIVATEとWM_PAINTメッセージを処理している。サンプルコード全体に丁寧なコメントを付けて、コードの目的を説明している。

このサンプルは、大部分のDirect3D保持モードサンプルと異なり、RMMainヘルパファイル、Rmmain.cpp、Rmmain.rcが提供する拡張メニューを使用しない。

RMBegin2サンプルのコードの詳細は、「フレーム階層：RMBegin2サンプル」を参照すること。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

RMEnum

パス

mssdk\samples\multimedia\d3drm\src\Rmenum

説明

これは、デバイスを列挙して、最適なデバイスを選択し、Direct3D保持モードデバイスを作成する「要点」を示したサンプルである。このサンプルではレンダリングはまったく行わない。コードを読みやすくするために、デバイスの列挙だけを扱っている。また、ユーザーがメニューからデバイスを選択できるようにする。

このサンプルは、大部分のDirect3D保持モードサンプルと異なり、RMMainヘルパファイル、Rmmain.cpp、Rmmain.rcが提供する拡張メニューを使用しない。Rmerror.cファイルのエラー報告機能を使用している。

RMEnumサンプルのコードの詳細は、「デバイスの列挙：RMEnumサンプル」を参照すること。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

RMMain

パス

mssdk\samples\multimedia\d3drm\src\Misc

説明

RMMain ヘルパコードは、Microsoft DirectDraw®およびDirect3D保持モードオブジェクトの作成、列挙、管理などの一般的なタスクを処理し、メニューに共通のリソースを提供する。RMMainは、Direct3D保持モードを使用して、レンダリング用のウィンドウを設定し、サンプルが提供するBuildScene関数を呼び出して、サンプルのシーンを構築し、Direct3D保持モードを使用してシーンをレンダリングする。ほとんどのDirect3D保持モードサンプルは、この共通コードにリンクしており、アプリケーション固有のコードを非常に単純化している。RMMainを使用するサンプルは、ウィンドウモードだけで動作する。

RMMainは多数のメニュー項目も提供しており、ユーザーはレンダリングオプションの効果を確認できる。アニメーションを1手順ずつ操作して、レンダリング用のデバイスを選択し、シェーディングモード (フラットまたはグロー) を選択し、照明とディザリングをオンまたはオフに設定し、塗りつぶしオプション (点、ワイヤフレームまたはソリッド) を選択できる。

RMMainヘルパコードは、次のファイルで構成されている。
Rmmain.cpp | WinMainおよびメッセージハンドラをインクルードした基本的なソースファイル。Direct3D保持モードを作成し、保持モードを使用してレンダリング用のウィンドウを設定した後、サンプルを呼び出してシーンを構築する。
Resource.h | Rmmain.rcのヘッダファイル。
Rmmain.rc | Rmmain.cppのリソースファイル。メニュー、キーボードアクセラレータ、および [About] ダイアログボックスを提供する。

Shadow

パス

mssdk\samples\multimedia\d3drm\src\Shadow

説明

このサンプルはメッシュオブジェクトの影を作成する。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

Tex1

パス

mssdk\samples\multimedia\d3drm\src\Tex1

説明

このサンプルは、円柱マッピングを使用してテクスチャをマッピングした単純なメッシュオブジェクトをロードする。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

参照

Tex3、 Tex4、 Tex5

Tex3

パス

mssdk\samples\multimedia\d3drm\src\Tex3

説明

このサンプルは、フレームに関連した球体マッピングを使用して、特殊効果のテクスチャラッピングを使用する。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

参照

Tex1、 Tex4、 Tex5

Tex4

パス

mssdk\samples\multimedia\d3drm\src\Tex4

説明

このサンプルは、カメラに関連した球体マッピングを使用して、特殊効果を出すためにテクスチャラッピングを使用する。テクスチャは、シーンの背景としても使用されている。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

参照

Tex1、 Tex3、 Tex5

Tex5

パス

mssdk\samples\multimedia\d3drm\src\Tex5

説明

このサンプルは、クロムマッピングのラッピング、およびデカールとしてテクスチャマッピングを使用している。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

参照

Tex1、 Tex3、 Tex4

Trans

パス

mssdk\samples\multimedia\d3drm\src\Trans

説明

このサンプルは、透明なテクスチャマッピングの実例を示している。立体の球を回転させ、部分的に透明な格子模様の立方体2つを個別に回転して、球体と交差させる。サンプルは、フレーム、照明、メッシュビルダ、メッシュ、テクスチャ、マテリアルを作成する。IDirect3DRMTexture3::SetDecalTransparencyを呼び出してデカールを透明にする。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

Uvis

パス

mssdk\samples\multimedia\d3drm\src\Uvis

説明

このサンプルは、Direct3D保持モードでDirect3Dを使用する方法を示している。Direct3D保持モードシーンのビジュアルとして、Direct3D直接モードの実行バッファを使用する方法を示す。

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib

必要なRMMainコード

  • Rmmain.cpp
  • Rmmain.rc

Viewer

パス

mssdk\samples\multimedia\d3drm\src\Viewer

説明

Viewer (Direct3D Retained Mode Object Viewer) は、3Dオブジェクトをロードして表示するスタンドアロンタイプの保持モードアプリケーションである。

最初のシーンには右上隅に照明が配置されている。照明を見るには、TまたはRキーを使用して、前後に移動する。追加のオブジェクトは、[File] メニューからロードし、新しい照明は [Lights] メニューで追加する。マウスの左ボタンでオブジェクトを回転し、右ボタンでドラッグできる。

最後に回転またはドラッグしたオブジェクトが現在の選択アイテムになる。

デバイスの質は、[Renderer] メニューで変更する。このメニューを使用すると、使用するデバイスのタイプをランプからRGBに切り替えられる。RGBデバイスを使用すると、シーンの照明が、オブジェクトのカラーを変更するのと同じように変更できる。256色モードでは、RGBデバイスをディザリング処理すると最適な結果が得られる。

制御キーは次のとおりである。
T | 前方
R | 後方
Z | 現在の選択アイテムを前方に移動
X | 現在の選択アイテムを後方に移動
Ctrl+G | グーローシェーディング
Ctrl+F | フラットシェーディング
Ctrl+D | ディザ（トグル）
矢印キー | 左/右/上/下に移動
Del | 現在の選択範囲を削除

必要なライブラリ

  • Ddraw.lib
  • D3drm.lib
  • Comdlg32.lib
  • Winmm.lib
  • Msvcrt.lib


DirectXファイルフォーマット

Microsoft® DirectX® version 6.0では、DirectX (.x)ファイルの読み出しと書き込みを可能にするインターフェイスとメソッドが導入された。詳細については「DirectXファイルリファレンス」を参照すること。

この節は、DirectX 2.0で導入されたファイルフォーマットを規定するものである。このフォーマットのバイナリ版は、続くDirectX3.0でリリースされたものだが、このリファレンスでも詳述する。

DirectXファイルフォーマットは、豊富なテンプレート駆動のフォーマットで、メッシュ、テクスチャ、アニメーション、およびユーザ定義可能なオブジェクトを格納することができる。アニメーションセットを使えば、あらかじめ定義されたパスを、リアルタイムでの再生のために格納することができる。インスタンス化や階層もサポートされている。インスタンス化は、データは1つのファイルに一度だけ格納する一方で、メッシュなどのオブジェクトに対するマルチ参照を可能にする。階層は、データレコード間の関係を表現するのに用いられる。DirectXファイルフォーマットは、Microsoft Direct3D®保持モードAPIによって、ネイティブのファイルフォーマットとして使用され、あらかじめ定義されたオブジェクトをアプリケーション中に読み込んだり、リアルタイムでアプリケーションが作り上げたメッシュ情報を書き込んだりすることをサポートする。

DirectXファイルフォーマットは、ローレベルのデータプリミティブを提供する。アプリケーションは、その上にテンプレートを介してよりハイレベルのプリミティブを定義する。この方法によって、Direct3D保持モードは、ベクトル、メッシュ、行列、色などのハイレベルのプリミティブを定義する。

以下の項で、ファイルフォーマットのAPI独立の機能と、Direct3D保持モードがファイルフォーマットを使用する方法を説明する。

  • DirectXファイルフォーマットアーキテクチャ
  • DirectXファイルテンプレート
  • DirectXファイルの立方体の例
  • DirectXファイルバイナリフォーマット
  • DirectXファイルConv3ds.exeユーティリティ
  • DirectXファイルサンプル
  • DirectXファイルリファレンス


DirectXファイルフォーマットアーキテクチャ

Microsoft® DirectX®ファイルフォーマットは、アーキテクチャから独立し、コンテキストに依存しないファイルフォーマットである。また、テンプレート駆動であり、使用する上で前提とする知識を必要としない。このファイルフォーマットは、すべてのクライアントアプリケーションが使用することができ、現在、Microsoft Direct3D®保持モードが、幾何データ、フレーム階層、およびアニメーションを記述するために使用している。

以下のセクションでは、このファイルフォーマットの内容と構文を説明する。ファイルフォーマットは、DirectX Software Development Kit (SDK) での使用時には拡張子.xを使用する。

  • 予約語
  • ヘッダ
  • コメント
  • テンプレート
  • データ
  • コンマとセミコロンの使用法

予約語

以下の語は、予約されているので使用してはならない。

  • ARRAY
  • BINARY
  • BINARY_RESOURCE
  • CHAR
  • CSTRING
  • DOUBLE
  • DWORD
  • FLOAT
  • SDWORD
  • STRING
  • SWORD
  • TEMPLATE
  • UCHAR
  • ULONGLONG
  • UNICODE
  • WORD

ヘッダ

可変長ヘッダは必須であり、データストリームの先頭になければならない。ヘッダは、以下のものを含む。
タイプ | サブタイプ | サイズ | 内容 | 内容の意味
マジックナンバ（必須） |  | 4バイト | "xof " |
バージョン番号（必須） | メジャー番号 | 2バイト | 03 | メジャーバージョン3
 | マイナー番号 | 2バイト | 02 | マイナーバージョン2
フォーマットタイプ（必須） |  | 4バイト | "txt " | テキストファイル
 |  |  | "bin " | バイナリファイル
 |  |  | "tzip" | MSZip圧縮テキストファイル
 |  |  | "bzip" | MSZip圧縮バイナリファイル
浮動小数点サイズ（必須） |  | 4バイト | 0064 | 64ビット浮動小数点
 |  |  | 0032 | 32ビット浮動小数点

例

xof 0302txt 0064

コメント

コメントは、テキストファイルの中だけで適用できる。コメントは、データストリーム中のどこにでも現れることができる。コメントは、C++式の二重スラッシュ "//"またはシャープ文字 "#"で始まる。コメントは、次の行に継続できる。

# これはコメントである。
// これもコメントである。

テンプレート

テンプレートは、データストリームを解釈する仕方を定義する。データは、テンプレート定義によって調節される。 この節では、テンプレートについて説明する。

  • テンプレートの形式
  • テンプレート名
  • UUID
  • メンバ
  • 制約

テンプレートの例は「例」に示す。

テンプレートの形式

テンプレートの形式は、以下のとおりである。

template <template-name> {
<UUID>
<member 1>;
...
<member n>;
[restrictions]
}

テンプレート名

これは、英数字からなる名前で、下線文字の"_"を含めても良い。数字で始めてはならない。

UUID

国際的に決められた一意な識別子（UUID）で、OSF DCE（Open Software Foundation's Distributed Computing Environment）規格でフォーマット化され、かぎ括弧の"<"と">"で囲まれる。たとえば、<3D82AB43-62DA-11cf-AB39-0020AF71E433>。

メンバ

テンプレートのメンバは、名前付きデータ型とそれに続くオプション名または名前付きデータ型の配列で構成される。有効なプリミティブデータ型は、以下のとおりである。

型 | サイズ
WORD | 16ビット
DWORD | 32ビット
FLOAT | IEEE浮動小数点数
DOUBLE | 64ビット
CHAR | 8ビット
UCHAR | 8ビット
BYTE | 8ビット
STRING | NULL終端文字列
CSTRING | フォーマット済みC文字列 (現在サポートされてない)
UNICODE | Unicode™文字列 (現在サポートされてない)

データストリーム中で前に遭遇した、テンプレートによって定義されている追加のデータ型は、テンプレート定義の中で参照することもできる。前方参照は許されていない。

任意の有効なデータ型は、テンプレート定義中で配列として表現することができる。基本的な構文は、以下のとおりである。

array <data-type> <name>[<dimension-size>];

ここで<dimension-size>は、整数またはその値で置き換えられる他のテンプレートメンバに対する参照名のどちらでも良い。

配列は、n次元でも良い。ここで、nはステートメントに続く対の角括弧の数によって決まる。たとえば、以下のとおりである。

array DWORD FixedHerd[24];
array DWORD Herd[nCows];
array FLOAT Matrix4x4[4][4];

制約

テンプレートにはオープン、クローズ、または制約がある。これらの制限は、テンプレートが定義するデータオブジェクトの直接の階層の中で、どのデータ型が現れるかを決定する。オープンテンプレートには制限がなく、クローズドテンプレートには、すべてのデータ型を拒絶し、制約テンプレートはデータ型の名前付きリストを許す。

角括弧で囲まれた3つのピリオドは、オープンテンプレートを示す。

[ ... ]

名前付きデータ型のコンマで区切られたリストで、その後にオプションの角括弧で囲まれたそのUUIDが続くものは、制約テンプレートであることを示す。

[ { data-type [ UUID ] , }... ]

上記のいずれでもない場合は、クローズドテンプレートであることを示す。

例

template Mesh {
<3D82AB44-62DA-11cf-AB39-0020AF71E433>
DWORD nVertices;
array Vector vertices[nVertices];
DWORD nFaces;
array MeshFace faces[nFaces];
 [ ... ]                // オープンテンプレート
}
template Vector {
<3D82AB5E-62DA-11cf-AB39-0020AF71E433>
FLOAT x;
FLOAT y;
FLOAT z;
}                        // クローズドテンプレート
template FileSystem {
<UUID>
STRING name;
[ Directory <UUID>, File <UUID> ]    // 制約テンプレート
}

特殊なテンプレートが1つある。それはヘッダテンプレートである。各アプリケーションがヘッダテンプレートを定義し、バージョン情報などのアプリケーションに特有の情報を定義することを推奨する。このヘッダは、DirectXファイルフォーマットAPIが読み込み、flagsメンバが使用可能であれば、以下のデータを解釈する仕方を決定するのに使用される。flagsメンバは、定義する場合にはDWORDにする必要がある。ビット0の1ビットが現在定義されている。このビットがクリアされていれば、ファイル中の以下のデータは、バイナリであり、セットされていれば、以下のデータは、テキストである。マルチヘッダデータオブジェクトは、ファイルの中でバイナリとテキストを切り替えるのに使用できる。

データ

データオブジェクトは実際のデータか、データに対する参照を含む。それぞれ、データ型を指定する対応するテンプレートを持つ。

データオブジェクトの形式は以下のとおりである。

<Identifier> [name] { [<UUID>]
<member 1>;
...
<member n>;
}

この節では、データオブジェクトの以下の部分を説明する。

  • 識別子
  • 名前
  • メンバ

テンプレートの例は「例」に示す。

識別子

これは必須であり、以前の定義済みのデータ型またはプリミティブと一致しなければならない。

名前

これはオプションである（構文定義については上記を参照すること）。

メンバ

データメンバは、以下のいずれかである。

データオブジェクト

ネストされたデータオブジェクト。これは、階層的な性質を持つフォーマットを表現することを可能にする。階層内で許されるネストデータオブジェクトの型は制限される。詳細については「テンプレート」を参照すること。

データ参照

前に遭遇したデータ型に対する参照。構文は、以下のとおりである。

{
  name |
  UUID |
  name UUID
}

整数リスト

セミコロンで整数のリストを区切る。例は、以下のとおりである。

1; 2; 3;

浮動小数点リスト

セミコロンで浮動小数点のリストを区切る。例は、以下のとおりである。

1.0; 2.0; 3.0;

文字列リスト

セミコロンで文字列のリストを区切る。例は、以下のとおりである。

"Moose"; "Goats"; "Sheep";

コンマとセミコロンの使用法

これが、おそらくファイルフォーマットの最も複雑な構文問題であり、その使用法に厳密さが求められる。コンマは、配列のメンバを区切るのに使用する。セミコロンは、各データ項目を終了するのに使用する。

たとえば、以下のようにテンプレートを定義したとする。

template mytemp {
DWORD myvar;
}

このインスタンスは、以下のようになる。

mytemp dataTemp {
1;
}

以下のように、テンプレートが別のテンプレートを含む場合がある。

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
FLOAT aFloat;
mytemp aTemp;
}

このインスタンスは、以下のようになる。

container dataContainer {
1.1;
2; 3;;
}

container内部のmytempを表す2番目の行に、2つのセミコロンがその終わりに付いていることに注意する。最初のセミコロンは、データ項目のaTempの終了(container内部)、2番目のセミコロンはcontainerの終わりをそれぞれ示す。

次は、配列の場合である。

Template mytemp {
array DWORD myvar[3];
}

このインスタンスは、以下のようになる。

mytemp aTemp {
1, 2, 3;
}

配列の場合、コンマで区切られているので、データ項目をセミコロンで区切る必要はない。最後のセミコロンは配列の終わりをマークする。

ここで、テンプレートが定義するデータ項目の配列を含むテンプレートを考えてみる。

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
DWORD count;
array mytemp tempArray[count];
}

このインスタンスは、以下のようになる。

container aContainer {
3;
1;2;,3;4;,5;6;;
}


DirectXファイルテンプレート

Microsoft® Direct3D®保持モードによって使用されるテンプレートの一覧を次に示す。Direct3D保持モードのデータ型に精通していることが前提である。

  • テンプレート名：Header
  • テンプレート名：Vector
  • テンプレート名：Coords2d
  • テンプレート名：Quaternion
  • テンプレート名：Matrix4x4
  • テンプレート名：ColorRGBA
  • テンプレート名：ColorRGB
  • テンプレート名：Indexed Color
  • テンプレート名：Boolean
  • テンプレート名：Boolean2d
  • テンプレート名：Material
  • テンプレート名：TextureFilename
  • テンプレート名：MeshFace
  • テンプレート名：MeshFaceWraps
  • テンプレート名：MeshTextureCoords
  • テンプレート名：MeshNormals
  • テンプレート名：MeshVertexColors
  • テンプレート名：MeshMaterialList
  • テンプレート名：Mesh
  • テンプレート名：FrameTransformMatrix
  • テンプレート名：Frame
  • テンプレート名：FloatKeys
  • テンプレート名：TimedFloatKeys
  • テンプレート名：AnimationKey
  • テンプレート名：AnimationOptions
  • テンプレート名：Animation
  • テンプレート名：AnimationSet

テンプレート名：Header

UUID

<3D82AB43-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
major | WORD |  | なし
minor | WORD |  |
flags | DWORD |  |

説明

このテンプレートは、DirectXファイルフォーマットのDirect3D保持モードの使用に対してアプリケーション固有のヘッダを定義する。保持モードは、majorおよびminorフラグを使用して、保持モードファイルフォーマットの現在の主バージョンと副バージョンを指定する。

テンプレート名：Vector

UUID

<3D82AB5E-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
x | FLOAT |  | なし
y | FLOAT |  |
z | FLOAT |  |

説明

このテンプレートは、ベクトルを定義する。

テンプレート名：Coords2d

UUID

<F6F23F44-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
u | FLOAT |  | なし
v | FLOAT |  |

説明

メッシュのテクスチャ座標を定義するのに使用する2次元ベクトル。

テンプレート名：Quaternion

UUID

<10DD46A3-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
s | FLOAT |  | なし
v | Vector |  |

説明

現在未使用。

テンプレート名：Matrix4x4

UUID

<F6F23F45-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
matrix | array FLOAT | 16 | なし

説明

このテンプレートは、4×4行列を定義する。フレーム変換行列に使用される。

テンプレート名：ColorRGBA

UUID

<35FF44E0-6C7C-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
red | FLOAT |  | なし
green | FLOAT |  |
blue | FLOAT |  |
alpha | FLOAT |  |

説明

このテンプレートは、アルファ成分を持つカラーオブジェクトを定義する。マテリアルテンプレート定義中の面の色に使用される。

テンプレート名：ColorRGB

UUID

<D3E16E81-7835-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
red | FLOAT |  | なし
green | FLOAT |  |
blue | FLOAT |  |

説明

このテンプレートは、基本的なRGBカラーオブジェクトを定義する。

テンプレート名：Indexed Color

UUID

<1630B820-7842-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ
index | DWORD |
indexColor | ColorRGBA |

説明

このテンプレートは、インデックスパラメータとRGBAカラーで構成され、メッシュの頂点の色を定義するのに使用する。インデックスは、色を適用する対象の頂点を定義する。

テンプレート名：Boolean

UUID

<4885AE61-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
DWORD | truefalse |  | なし

説明

単純なブール型を定義する。このテンプレートは、0または1をセットする。

テンプレート名：Boolean2d

UUID

<4885AE63-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
u | Boolean |  | なし
v | Boolean |  |

説明

このテンプレートは、MeshFaceWrapsテンプレートで使用される2つのブール値のセットを定義し、個別の面のテクスチャトポロジを定義する。

テンプレート名：Material

UUID

<3D82AB4D-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
faceColor | ColorRGBA |  | Any
power | FLOAT |  |
specularColor | ColorRGB |  |
emissiveColor | ColorRGB |  |

説明

このテンプレートは、メッシュ全体またはメッシュの個別の面のどちらかに適用できる基本的なマテリアルの色を定義する。powerは、マテリアルの反射指数である。アンビエント照明の色がアルファ成分を必要とすることに注意する。

TextureFilenameは、Direct3D保持モードが使用するオプションのデータオブジェクトである。このオブジェクトが存在しない場合、面はテクスチャ化されない。

テンプレート名：TextureFilename

UUID

<A42790E1-7810-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
filename | STRING |  | なし

説明

このテンプレートは、メッシュまたは面に適用されるテクスチャのファイル名を指定することを可能にする。このテンプレートがマテリアルオブジェクト内部に現れる必要がある。

テンプレート名：MeshFace

UUID

<3D82AB5F-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
nFaceVertexIndices | DWORD |  | なし
faceVertexIndices | array DWORD | nFaceVertexIndicies |

説明

このテンプレートは、メッシュの面を定義するために、Meshテンプレートが使用する。nFaceVertexIndices配列の各要素は、面を作るのに使用されるメッシュ頂点を参照する。

テンプレート名：MeshFaceWraps

UUID

<4885AE62-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
nFaceWrapValues | DWORD |  | なし
faceWrapValues | Boolean2d |  |

説明

このテンプレートは、ラップ中の各面のテクスチャトポロジを定義するのに使用する。nFaceWrapValuesメンバの値は、メッシュ内の面の数に等しくする必要がある。

テンプレート名：MeshTextureCoords

UUID

<F6F23F40-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
nTextureCoords | DWORD |  | なし
textureCoords | array Coords2d | nTextureCoords |

説明

このテンプレートは、メッシュのテクスチャ座標を定義する。

テンプレート名：MeshNormals

UUID

<F6F23F43-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
nNormals | DWORD |  | なし
normals | array Vector | nNormals |
nFaceNormals | DWORD |  |
faceNormals | array MeshFace | nFaceNormals |

説明

このテンプレートは、メッシュの法線を定義する。ベクトルの先頭の配列は、それ自体が法線ベクトルであり、2番目の配列は、指定の面にどの法線を適用するかを指定するインデックスの配列である。nFaceNormalsメンバの値は、メッシュ内の面の数に等しくする必要がある。

テンプレート名：MeshVertexColors

UUID

<1630B821-7842-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
nVertexColors | DWORD |  | なし
vertexColors | array IndexedColor | nVertexColors |

説明

このテンプレートは、面ごとにまたはメッシュごとにマテリアルを適用する代わりに、メッシュの頂点の色を指定する。

テンプレート名：MeshMaterialList

UUID

<F6F23F42-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
nMaterials | DWORD |  | Material
nFaceIndexes | DWORD |  |
FaceIndexes | array DWORD | nFaceIndexes |

説明

このテンプレートは、メッシュオブジェクトで使用され、どのマテリアルをどの面に適用するかを指定する。nMaterialsメンバは、存在するマテリアルの数および適用するマテリアルの数を指定する。

テンプレート名：Mesh

UUID

<3D82AB44-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
nVertices | DWORD |  | Any
vertices | array Vector | nVertices |
nFaces | DWORD |  |
faces | array MeshFace | nFaces |

説明

このテンプレートは、単純なメッシュを定義する。1番目の配列は、頂点のリストであり、2番目の配列は、頂点配列に対するインデックスとしてメッシュの面を定義する。

オプションのデータ要素

以下のオプションのデータ要素がDirect3D保持モードによって使用される。

MeshFaceWraps | 指定しない場合、デフォルトでuとvの両方がfalseに設定される。
MeshTextureCoords | 指定しない場合、テクスチャ座標が存在しない。
MeshNormals | 指定しない場合、法線はAPIのGenerateNormalsメソッドを使用して生成される。
MeshVertexColors | 指定しない場合、デフォルトで色は白に設定される。
MeshMaterialList | 指定しない場合、デフォルトでマテリアルは白に設定される。

テンプレート名：FrameTransformMatrix

UUID

<F6F23F41-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
frameMatrix | Matrix4x4 |  | なし

説明

このテンプレートは、フレーム (およびその子オブジェクトすべて) に対するローカル変換を定義する。

テンプレート名：Frame

UUID

<3D82AB46-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
なし |  |  | 任意

説明

このテンプレートは、フレームを定義する。現在、フレームはMesh型のオブジェクトとFrameTransformMatrixを含むことができる。

オプションのデータ要素

以下のオプションのデータ要素がDirect3D保持モードによって使用される。

FrameTransformMatrix | この要素を指定しない場合、ローカル変換がフレームに適用されない。
Mesh | 任意の数のメッシュオブジェクトがフレームの子になる。それらのオブジェクトは、インラインまたは参照で指定することができる。

テンプレート名：FloatKeys

UUID

<10DD46A9-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
nValues | DWORD |  | なし
values | array FLOAT | nValues |

説明

このテンプレートは、浮動小数点数の配列とその配列中の浮動小数点数の数を定義する。アニメーションキーのセットを定義するために使用する。

テンプレート名：TimedFloatKeys

UUID

<F406B180-7B3B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
time | DWORD |  | なし
tfkeys | FloatKeys |  |

説明

このテンプレートは、浮動小数点数のセットとアニメーションで使用される正の時間を定義する。

テンプレート名：AnimationKey

UUID

<10DD46A8-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
keyType | DWORD |  | なし
nKeys | DWORD |  |
keys | array TimedFloatKeys | nKeys |

説明

このテンプレートは、アニメーションキーのセットを定義する。keyTypeメンバは、キーが回転、スケールまたは位置キー (それぞれ整数の0、1、2を使用して) のいずれかを指定する。

テンプレート名：AnimationOptions

UUID

<E2BF56C0-840F-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
openclosed | DWORD |  | なし
positionquality | DWORD |  |

説明

このテンプレートは、Direct3D保持モードのアニメーションオプションの設定を可能にする。openclosedメンバは、クローズドアニメーションに対しては0、オープンアニメーションに対しては1にすることができる。positionqualityメンバは、指定されている任意の位置キーに対して位置の性質を設定するために使用し、スプライン位置に対しては0、線形位置に対しては1にすることができる。デフォルトでは、アニメーションはクローズである。

テンプレート名：Animation

UUID

<3D82AB4F-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
なし |  |  | 任意

説明

このテンプレートは、以前のフレームを参照するアニメーションを含む。フレームに対する1つの参照と少なくてもAnimationKeysの1セットを含む必要がある。また、AnimationOptionsデータオブジェクトを含むこともできる。

オプションのデータ要素

以下のオプションのデータ要素がDirect3D保持モードによって使用される。
AnimationKey | アニメーションは、AnimationKeyがないと無意味になる。
AnimationOptions | この要素を指定しない場合、アニメーションはクローズである。

テンプレート名：AnimationSet

UUID

<3D82AB50-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプション配列サイズ | オプションデータオブジェクト
なし |  |  | Animation

説明

AnimationSetテンプレートは、複数のAnimationオブジェクトを含み、Direct3D保持モードのアニメーションセットと同等である。これは、アニメーションセット内の各アニメーションの時間が任意の点で同じであることを意味する。アニメーションセットの時間を大きくすると、それが含むすべてのアニメーションに対する時間を大きくすることになる。


DirectXファイルの立方体の例

この節では、単純な立方体を例として、テクスチャ、フレーム、アニメーションを立方体に追加する方法を説明する。

  • 単純な立方体
  • テクスチャの追加
  • フレームとアニメーション

単純な立方体

このファイルは、4つの赤い面と2つの緑の面を持つ単純な立方体を定義する。このファイル中のオプション情報が、Meshテンプレートによって定義されるデータオブジェクトに情報を追加するのに使用されていることに注意する。

Material RedMaterial {
1.000000;0.000000;0.000000;1.000000;;    // R = 1.0, G = 0.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
}
Material GreenMaterial {
0.000000;1.000000;0.000000;1.000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
}
// 8頂点と12面(三角形)を持つメッシュを定義する。
// メッシュ中のオプションデータオブジェクトを使用して
// マテリアル、法線およびテクスチャ座標を指定する。
Mesh CubeMesh {
8;                                // 8頂点
1.000000;1.000000;-1.000000;,     // 頂点0
-1.000000;1.000000;-1.000000;,    // 頂点1
-1.000000;1.000000;1.000000;,     // など
1.000000;1.000000;1.000000;,
1.000000;-1.000000;-1.000000;,
-1.000000;-1.000000;-1.000000;,
-1.000000;-1.000000;1.000000;,
1.000000;-1.000000;1.000000;;

12;                      // 12面
3;0,1,2;,                // 面0には3頂点がある。
3;0,2,3;,                // など
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;

// 必須データがすべて定義された。ここで、オプションデータを定義
// する。定義には、ファイルフォーマットの階層的性質を使用する。
MeshMaterialList {
2;                    // 使用するマテリアル数
12;                   // 各面のマテリアル
0,                    // 面0が最初の
0,                    // マテリアルを使用する。
0,
0,
0,
0,
0,
0,
1,                    // 面8が2番目のマテリアルを
1,                    // 使用する。
1,
1;;
{RedMaterial}         // マテリアル0と1の
{GreenMaterial}       // 定義への参照。
}
MeshNormals {
8;                    // 8法線を定義する。
0.333333;0.666667;-0.666667;,
-0.816497;0.408248;-0.408248;,
-0.333333;0.666667;0.666667;,
0.816497;0.408248;0.408248;,
0.666667;-0.666667;-0.333333;,
-0.408248;-0.408248;-0.816497;,
-0.666667;-0.666667;0.333333;,
0.408248;-0.408248;0.816497;;
12;                   // 12面に対して
3;0,1,2;,             // 法線を定義する。
3;0,2,3;,
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;
}
MeshTextureCoords {
8;                        // 各頂点に対して、
0.000000;1.000000;        // テクスチャ座標を定義する。
1.000000;1.000000;
0.000000;1.000000;
1.000000;1.000000;
0.000000;0.000000;
1.000000;0.000000;
0.000000;0.000000;
1.000000;0.000000;;
}
}

テクスチャの追加

テクスチャを追加するには、ファイルフォーマットの階層的性質を利用し、オプションのTextureFilenameデータオブジェクトをMaterialデータオブジェクトに追加する。したがって、Materialオブジェクトは、以下のようになる。

Material RedMaterial {
1.000000;0.000000;0.000000;1.000000;;    // R = 1.0, G = 0.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
TextureFilename {
"tex1.ppm";
}
}
Material GreenMaterial {
0.000000;1.000000;0.000000;1.000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
TextureFilename {
"win95.ppm";
}
}

フレームとアニメーション

この項では、フレームとアニメーションを単純な立方体に追加する方法を説明する。

  • フレーム
  • アニメーションセットとアニメーション

フレーム

フレームは以下の構造体をとることが要求される。

Frame Aframe {        // フレーム名は便宜上選択したものである。
FrameTransformMatrix {
...変換データ...
}
[メッシュ ]および/あるいは[さらにフレーム]
}

事前に定義した立方体メッシュをフレーム内部に恒等変換で置く。その後、アニメーションをこのフレームに追加する。

Frame CubeFrame {
FrameTransformMatrix {
1.000000, 0.000000, 0.000000, 0.000000,
0.000000, 1.000000, 0.000000, 0.000000,
0.000000, 0.000000, 1.000000, 0.000000,
0.000000, 0.000000, 0.000000, 1.000000;;
}
{CubeMesh}        // メッシュインラインを使用することもできる
                  // が、代わりにオブジェクト参照を使用する。
}

アニメーションセットとアニメーション

DirectXファイルフォーマット中のアニメーションとアニメーションセットは、Direct3D保持モードのアニメーションの概念に直接マップされる。

Animation Animation0 {        // 名前は便宜的に選択されたものである。
{ 通常、参照が適用されるフレーム }
AnimationKey {
...アニメーションキーデータ...
}
{ ...さらにアニメーションキー... }
}

この後、次のようにアニメーションは、アニメーションセットにグループ化される。

AnimationSet AnimationSet0 { // 名前は便宜的に選択したものである。
{ アニメーション - インラインでも参照でも良い }
{ ... さらにアニメーション ... }
}

ここですることは、アニメーションを通して立方体をとることである。

AnimationSet AnimationSet0 {
Animation Animation0 {
{CubeFrame}    // 立方体を含むフレームを使用する。
AnimationKey {
2;             // 位置キー
9;             // 9キー
10; 3; -100.000000, 0.000000, 0.000000;;,
20; 3; -75.000000, 0.000000, 0.000000;;,
30; 3; -50.000000, 0.000000, 0.000000;;,
40; 3; -25.500000, 0.000000, 0.000000;;,
50; 3; 0.000000, 0.000000, 0.000000;;,
60; 3; 25.500000, 0.000000, 0.000000;;,
70; 3; 50.000000, 0.000000, 0.000000;;,
80; 3; 75.500000, 0.000000, 0.000000;;,
90; 3; 100.000000, 0.000000, 0.000000;;;
}
}
}


DirectXファイルバイナリフォーマット

この節では、DirectX 3.0のリリースで導入されたMicrosoft® DirectX®ファイルフォーマットのバイナリ版を詳述する。以下は、「DirectXファイルフォーマットアーキテクチャ」を理解した後に読むことが望ましい。

バイナリフォーマットは、テキストフォーマットのトークン化された形式である。トークンは、スタンドアローンでも、プリミティブデータレコードを伴っていても良い。スタンドアローントークンは、文法の構造を与え、レコード付随トークンは、必要なデータを供給する。

すべてのデータは、昇順のフォーマットで格納されることに注意する。

有効なバイナリデータストリームは、ヘッダと、それに続くテンプレートとデータオブジェクトの少なくとも1つから構成される。

この節では、バイナリファイルフォーマットの以下の部分を説明する。

  • ヘッダ
  • トークン
  • トークンレコード
  • テンプレート
  • データ

さらに、テンプレートの例が「テンプレートの例」で提供されている。バイナリデータオブジェクトは「データの例」で示す。

ヘッダ

以下の定義は、バイナリヘッダの直接の読み書きを行う際に使用する必要がある。圧縮データストリームは、現在サポートされていないので、ここで詳述されていないことに注意する。

#define XOFFILE_FORMAT_MAGIC \
  ((long)'x' + ((long)'o' << 8) + ((long)'f' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_VERSION \
  ((long)'0' + ((long)'3' << 8) + ((long)'0' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_BINARY \
  ((long)'b' + ((long)'i' << 8) + ((long)'n' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_TEXT   \
  ((long)'t' + ((long)'x' << 8) + ((long)'t' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_COMPRESSED \
  ((long)'c' + ((long)'m' << 8) + ((long)'p' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_32 \
  ((long)'0' + ((long)'0' << 8) + ((long)'3' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_64 \
  ((long)'0' + ((long)'0' << 8) + ((long)'6' << 16) + ((long)'4' << 24))

トークン

トークンは、昇順のWORDとして書き込まれる。トークン値のリストが続く。リストは、レコード付随とスタンドアローントークンに分けられる。

レコード付随

#define TOKEN_NAME 1
#define TOKEN_STRING 2
#define TOKEN_INTEGER 3
#define TOKEN_GUID 5
#define TOKEN_INTEGER_LIST 6
#define TOKEN_FLOAT_LIST 7

スタンドアロン

#define TOKEN_OBRACE 10
#define TOKEN_CBRACE 11
#define TOKEN_OPAREN 12
#define TOKEN_CPAREN 13
#define TOKEN_OBRACKET 14
#define TOKEN_CBRACKET 15
#define TOKEN_OANGLE 16
#define TOKEN_CANGLE 17
#define TOKEN_DOT 18
#define TOKEN_COMMA 19
#define TOKEN_SEMICOLON 20
#define TOKEN_TEMPLATE 31
#define TOKEN_WORD 40
#define TOKEN_DWORD 41
#define TOKEN_FLOAT 42
#define TOKEN_DOUBLE 43
#define TOKEN_CHAR 44
#define TOKEN_UCHAR 45
#define TOKEN_SWORD 46
#define TOKEN_SDWORD 47
#define TOKEN_VOID 48
#define TOKEN_LPSTR 49
#define TOKEN_UNICODE 50
#define TOKEN_CSTRING 51
#define TOKEN_ARRAY 52

トークンレコード

この項は、それぞれのレコード付随トークンのレコードフォーマットを説明する。

TOKEN_NAME

TOKEN_NAMEは可変長レコードである。tokenの後にはバイト数を指定するcount値が続く。countフィールドの後にnameフィールドが続く。count 長のASCII名がレコードの最後に来る。
フィールド | 型 | サイズ(バイト) | 内容
token | WORD | 2 | TOKEN_NAME
count | DWORD | 4 | バイト単位のnameフィールド長
name | BYTE array | Count | ASCII名

TOKEN_STRING

TOKEN_STRINGは可変長レコードである。tokenの後には、バイト数を指定するcount値が続く。countフィールドの後にstringフィールドが続く。count 長のASCII文字列が終端トークンの前に来る。terminatorの選択は、他の箇所で説明した構文の項目で決定される。
フィールド | 型 | サイズ(バイト) | 内容
token | WORD | 2 | TOKEN_STRING
count | DWORD | 4 | バイト単位のstringフィールド長
string | BYTE array | Count | ASCII文字列
terminator | DWORD | 4 | TOKEN_SEMICOLONまたはTOKEN_COMMA

TOKEN_INTEGER

TOKEN_INTEGERは固定長レコードである。tokenの後には、必須の整数値が続く。
フィールド | 型 | サイズ(バイト) | 内容
token | WORD | 2 | TOKEN_INTEGER
value | DWORD | 4 | 単一整数

TOKEN_GUID

TOKEN_GUIDは固定長レコードである。tokenの後には、OSF DCE基準によって定義されている4つのデータフィールドが続く。
フィールド | 型 | サイズ(バイト) | 内容
token | WORD | 2 | TOKEN_GUID
data1 | DWORD | 4 | UUIDデータフィールド1
data2 | WORD | 2 | UUIDデータフィールド2
data3 | WORD | 2 | UUIDデータフィールド3
data4 | BYTE array | 8 | UUIDデータフィールド4

TOKEN_INTEGER_LIST

TOKEN_INTEGER_LISTは可変長レコードである。tokenの後には、整数の数を指定するcount値が続く。countフィールドの後にはlistフィールドが続く。効率を上げるため、連続する整数リストは、単一のリストに結合する必要がある。
フィールド | 型 | サイズ(バイト) | 内容
token | WORD | 2 | TOKEN_INTEGER_LIST
count | DWORD | 4 | listフィールド内の整数の数
list | DWORD array | 4 x count | 整数リスト

TOKEN_FLOAT_LIST

TOKEN_FLOAT_LISTは可変長レコードである。tokenの後には、浮動小数点数または倍精度浮動小数点数の数を指定するcount値が続き、countフィールドの値にはlistフィールドが続く。浮動小数点数値のサイズ（floatまたはdouble）は、ファイルヘッダ中のfloatサイズ値で決定される。効率を上げるため連続するTOKEN_FLOAT_LISTは、単一リストに結合する必要がある。
フィールド | 型 | サイズ(バイト) | 内容
token | WORD | 2 | TOKEN_FLOAT_LIST
count | DWORD | 4 | フィールド中の浮動小数点または倍精度浮動小数点数の数。
list | float/double array | 4×countまたは8×count | 浮動小数点数または倍精度浮動小数点数のリスト

テンプレート

テンプレートの構文定義は、以下のとおりである。

template              : TOKEN_TEMPLATE name TOKEN_OBRACE
                            class_id
                            template_parts
                            TOKEN_CBRACE

template_parts        : template_members_part TOKEN_OBRACKET
                        template_option_info
                        TOKEN_CBRACKET
                      | template_members_list

template_members_part : /* 空 */
                      | template_members_list

template_option_info  : ellipsis
                      | template_option_list

template_members_list :    template_members
                      | template_members_list template_members

template_members      : primitive
                      | array
                      | template_reference

primitive             : primitive_type optional_name TOKEN_SEMICOLON

array                 : TOKEN_ARRAY array_data_type name dimension_list
                        TOKEN_SEMICOLON

template_reference    : name optional_name YT_SEMICOLON

primitive_type        : TOKEN_WORD
                      | TOKEN_DWORD
                      | TOKEN_FLOAT
                      | TOKEN_DOUBLE
                      | TOKEN_CHAR
                      | TOKEN_UCHAR
                      | TOKEN_SWORD
                      | TOKEN_SDWORD
                      | TOKEN_LPSTR
                      | TOKEN_UNICODE
                      | TOKEN_CSTRING

array_data_type       : primitive_type
                      | name

dimension_list        : dimension
                      | dimension_list dimension

dimension             : TOKEN_OBRACKET dimension_size TOKEN_CBRACKET

dimension_size        : TOKEN_INTEGER
                      | name

template_option_list  : template_option_part
                      | template_option_list template_option_part

template_option_part  : name optional_class_id

name                  : TOKEN_NAME

optional_name         : /* 空 */
                      | name

class_id              : TOKEN_GUID

optional_class_id     : /* 空 */
                      | class_id

ellipsis              : TOKEN_DOT TOKEN_DOT TOKEN_DOT

データ

データオブジェクトの構文定義は、以下のとおりである。

バイナリファイルのnumber_listデータとfloat_listデータには、TOKEN_COMMAとTOKEN_SEMICOLONは使用しない。string_listデータには、コンマとセミコロンを使用する。また、オプションのデータメンバには、data_referenceしか使用できない。

object                : identifier optional_name TOKEN_OBRACE
                            optional_class_id
                            data_parts_list
                            TOKEN_CBRACE
data_parts_list       : data_part
                      | data_parts_list data_part

data_part             : data_reference
                      | object
                      | number_list
                      | float_list
                      | string_list

number_list           : TOKEN_INTEGER_LIST

float_list            : TOKEN_FLOAT_LIST

string_list           : string_list_1 list_separator

string_list_1         : string
                      | string_list_1 list_separator string

list_separator        : comma
                      | semicolon

string                : TOKEN_STRING

identifier            : name
                      | primitive_type

data_reference        : TOKEN_OBRACE name optional_class_id TOKEN_CBRACE

テンプレートの例

2つのバイナリテンプレートの定義を以下に示す。データは、以下の例には示されていない昇順フォーマットで格納されることに注意する。

クローズドテンプレートのRGBは、UUID {55b6d780-37ec-11d0-ab39-0020af71e433}で識別され、それぞれ float型のr、g、bの3メンバを持つ。

TOKEN_TEMPLATE, TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_OBRACE,
TOKEN_GUID, 55b6d780, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_FLOAT, TOKEN_NAME, 1, 'r', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'g', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'b', TOKEN_SEMICOLON,
TOKEN_CBRACE

クローズドテンプレートのMatrix4x4は、UUID {55b6d781-37ec-11d0-ab39-0020af71e433}で識別され、それぞれ float型のmatrixという名前の2次元配列を1つメンバとして持つ。

TOKEN_TEMPLATE, TOKEN_NAME, 9, 'M', 'a', 't', 'r', 'i', 'x', '4', 'x', '4', TOKEN_OBRACE,
TOKEN_GUID, 55b6d781, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_ARRAY, TOKEN_FLOAT, TOKEN_NAME, 6, 'm', 'a', 't', 'r', 'i', 'x',
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_CBRACE

データの例

以下のバイナリデータオブジェクトは、前に定義したRGB テンプレートのインスタンスである。例のオブジェクトには、blueという名前が付けられ、その3つのメンバのr、g、bの値は、それぞれ0.0、0.0、1.0である。以下の例には示されていない昇順フォーマットで格納されることに注意する。

TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_NAME, 4, 'b', 'l', 'u', 'e', TOKEN_OBRACE,
TOKEN_FLOAT_LIST, 3, 0.0, 0.0, 1.0, TOKEN_CBRACE


DirectXファイルConv3ds.exeユーティリティ

Conv3ds.exeユーティリティは、Autodesk 3-D Studioや他のモデリングパッケージで作成された3DモデルをMicrosoft® DirectX®ファイルフォーマットに変換する。デフォルトで、テンプレートなしのバイナリ.xファイルを生成する。

この節では、以下の項目を説明する。

  • Conv3ds.exeの使用
  • Conv3ds.exeオプション引数
  • 光波オブジェクトから作成される3DSファイル
  • ヒントと助言

Conv3ds.exeの使用

Conv3ds.exeはオプションなしで起動することができ、フレームの階層を含む.xファイルを生成する。たとえば、以下のコマンドを考えてみる。

conv3ds File.3ds

このコマンドは、.3dsファイルから、.xファイルを生成する。フレームをロードするためにはIDirect3DRMFrame3::Loadを用いることができる。

Conv3ds.exeオプション引数

Conv3ds.exe -A

.3dsファイルにキーフレームデータが含まれる場合、アニメーションセットを格納する.xファイルを作成するには、-Aオプションを用いる。コマンドは以下のようになる。

conv3ds -A File.3ds

File.3dsパラメータは、変換しようとするファイルの名前である。IDirect3DRMAnimationSet2::Loadを用いて、アニメーションをロードすることができる。

Conv3ds.exe -m

.3dsファイルにあるすべてのオブジェクトからなる1つのメッシュを格納する.xファイルをつくるには、-mオプションを用いる。

conv3ds -m File.3ds

メッシュをロードするには、IDirect3DRMMeshBuilder3::Loadを用いる。

Conv3ds.exe -T

1つのトップレベルフレームにあるすべてのオブジェクトおよびフレーム階層をラップするには、-Tオプションを用いる。このオプションを使うと、IDirect3DRMFrame3::Loadを一度呼び出すだけで、.3dsファイル中のすべてのフレームやオブジェクトをロードすることができる。.xファイルの最初のトップレベルフレーム階層がロードされる。他のすべてのフレームやメッシュを格納するフレームは、"x3ds_filename" (.3ds拡張子なし) と呼ばれる。-Tオプションは-mオプションとともに用いられると、何ら効果はない。

Conv3ds.exe -s

-sオプションを用いると、.3dsファイル中のすべてのオブジェクトを変換する縮尺係数を指定することができる。たとえば、次のコマンドはすべてのオブジェクトを10倍大きくする。

conv3ds -s10 File.3ds

次のコマンドはすべてのオブジェクトを1/10にする。

conv3ds -s0.1 File.3ds

Conv3ds.exe -r

-rオプションは、.3dsファイルが変換されるときに、面を巻く順序を逆転させる。.3dsファイルを変換してDirect3Dで見たときにオブジェクトが裏返しになっているようであれば、-rオプションで変換を試みること。.3dsファイルとしてエクスポートされるすべての光波モデルは、このオプションを必要とする。詳細については、「光波オブジェクトから作成される3DSファイル」を参照すること。

Conv3ds.exe -v

-vオプションは、冗長出力モードをオンにする。その際に整数を指定する。現在サポートされている整数を、以下の表に示す。
オプション | 意味
-v0 | デフォルト。冗長モードをオフにする。
-v1 | 不正なオブジェクトについての警告を印刷し、コンバータが行っていることついての一般情報を印刷する。
-v2 | 基本キーフレーム情報、変換プロセスに含められているオブジェクト、および保存中のオブジェクトについての一般情報を印刷する。
-v3 | 非常に冗長。たいていは、デバッグ情報に有用。

Conv3ds.exe -e

-eオプションにより、テクスチャマップファイルの拡張子を変更することができる。たとえば、次のコマンドを考える。

conv3ds -e"ppm" File.3ds

File.3dsがテクスチャマップファイルBrick.gifを参照するオブジェクトを格納していると、.xファイルはテクスチャマップファイルBrick.ppmを参照する。コンバータはテクスチャマップファイルを変換しない。生成される.xファイルをロードするとき、テクスチャマップファイルはD3DPATHになければならない。D3DPATHは、デフォルト検索パスに設定されている環境変数である。

Conv3ds.exe -x

-xオプションを使うと、バイナリ.xファイルではなく、テキスト.xファイルを作成することができる。テキストファイルは大きくなるが、編集は簡単である。

Conv3ds.exe -X

-Xオプションを使うと、ファイルにDirect3D保持モードの.xファイルのテンプレートを含めることができる。デフォルトで、テンプレートは含まれない。

Conv3ds.exe -t

-tオプションは、作成される.xファイルがテクスチャ情報を格納しないよう指定する。

Conv3ds.exe -N

-Nオプションは、作成される.xファイルが法線ベクトル情報を格納しないよう指定する。Direct3D保持モードのロード呼び出しはすべて、.xファイルに法線ベクトルを持たないオブジェクトに対して法線ベクトルを生成する。

Conv3ds.exe -c

-cオプションは、作成される.xファイルがテクスチャ座標を格納しないよう指定する。デフォルトでは、-mオプションを用いている場合、.3dsオブジェクトがテクスチャ座標を持たなければ、出力されるメッシュは (0,0) uv テクスチャ座標を持つ。

Conv3ds.exe -f

-fオプションは、作成される.xファイルがフレーム変換行列を格納しないよう指定する。

Conv3ds.exe - zおよびConv3ds.exe -Z

-zおよび-Zオプションにより、.xファイルにあるオブジェクトによって参照されるすべてのマテリアルのアルファ面カラー値を調整できるようになる。たとえば、次のコマンドによって、Conv3ds.exeは0.2未満のすべてのアルファ値に0.1を加える。

conv3ds -z0.1 -Z0.2 File.3ds

次のコマンドによって、Conv3ds.exeはすべてのアルファのアルファ値から0.2を差し引く。

conv3ds-z"-0.2" -z1 File.3ds

Conv3ds.exe -o

-oオプションによって、作成されるxファイルのファイル名を指定できるようになる。

Conv3ds.exe -h

-hオプションは、3dsファイル(通常はキーフレーマで作成される)の階層情報を分析しないようコンバータに伝える。-mオプションが用いられていなければ、すべてのオブジェクトはトップレベルフレームで出力される。

光波オブジェクトから作成される3DSファイル

光波のTrans3dプラグインによってエクスポートされる.3dsファイルには、いくつかの問題がある。これらを処理するには、次のConv3ds.exe コマンドを用いるのがよい。

conv3ds -r -N -f -h -T|m trans3dfile.3ds

Trans3dや光波オブジェクトエディタによって作成されるすべての.3dsオブジェクトは、その巻き順を逆転する必要がある。そうしなければ、表示するときに「裏返し」になってしまう。これらのオブジェクトには、サーフェス法線ベクトル情報は格納していない。

ヒントと助言

Conv3ds.exeによって作成されたオブジェクトをDirect3D保持モードビューワにロードして見ることができないとき、縮尺係数を約100にしてスケーリングオプション-sを用いる。これは、.xファイル中のオブジェクトの尺度を増大させる。

オブジェクトをビューワにロードし、フラットシェーディングからグーローシェーディングに変えた後、オブジェクトがダークグレイに変色した場合、-N オプションで再度変換を試みる。

オブジェクトが変換されてからテクスチャがロードされない場合、-e オプションを用いてオブジェクトが.ppmファイルまたは.bmpファイルを参照していることを確認する。また、テクスチャの幅および高さが2の累乗であることも確かめる。さらに、テクスチャがD3DPATHの中の1つのディレクトリに格納されていることを確認する。

現在、Conv3ds.exeは、.3dsアニメーションで用いられるダミーフレームを処理することができず、無視してしまう。ただし、子オブジェクトは変換する。


DirectXファイルサンプル

以下のサンプルで、Microsoft® DirectX®ファイルフォーマットのロード、変換、および保存のデモンストレーションを行う。これらのサンプルはDirectX Foundation 6.x Software Development Kit (SDK)に含まれており、Mssdk\Samples\Multimedia\D3drm\Srcディレクトリ下のフォルダに入っている。

  • CONVXFMT
  • XOFLOAD
  • XOFSAVE
  • XOFUSER

CONVXFMT

パス

Mssdk\Samples\Multimedia\D3drm\Src\Convxfmt

説明

あるDirectXファイルフォーマットを、別のフォーマットに変換する。

XOFLOAD

パス

Mssdk\Samples\Multimedia\D3drm\Src\Xofload

説明

Direct3D保持モードのテンプレートを使用してファイルをロードする。

XOFSAVE

パス

Mssdk\Samples\Multimedia\D3drm\Src\Xofsave

説明

Direct3D保持モードのテンプレートを使用してファイルを保存する。

XOFUSER

パス

Mssdk\Samples\Multimedia\D3drm\Src\Xofuser

説明

ユーザ定義のテンプレートを使用してファイルを保存する。


DirectXファイルリファレンス

この節では、DirectX version 6.0で導入された、Microsoft® DirectX® (.x)ファイルの読み書きに使用する関数、インターフェイス、オブジェクト、データ型について解説する。また、インターフェイス間の関係を簡単に紹介し、インターフェイスの継承を示す階層図も示す。DirectXファイルのメソッドは、テキストファイルとバイナリファイルのどちらの読み書きにも使用できる。

これらのインターフェイスを使用するときは、「DirectXファイルフォーマットアーキテクチャ」で解説しているDirectXファイルのフォーマットに精通しておく必要がある。ファイルフォーマットを理解していると、インターフェイスとそのメソッドの目的をより理解しやすくなる。

この節には、次の項目が含まれている。

  • はじめに
  • インターフェイス階層
  • 関数とインターフェイス
  • データ型
  • 戻り値

はじめに

DirectX (.x)ファイルからのデータのロード方法と、DirectX (.x)ファイルへのデータの保存方法について、概要を説明する。DirectXファイルメソッドは、テキストとバイナリの両方のDirectXファイルを扱い、ファイル、メモリ、リソース、URLなど、各種ソースからのロードをサポートしている。

DirectXファイルのインターフェイスを使用するには、まずDirectXFileCreate関数を使用して IDirectXFileオブジェクトを作成する。

ファイルのロード

次の手順でDirectXファイルをロードする。

  1. DirectXFileCreate関数を使用して、IDirectXFileオブジェクトを作成する。
  2. ロードするDirectXファイルにテンプレートが存在しない場合、IDirectXFile::RegisterTemplatesメソッドを使用してテンプレートを登録する。
  3. IDirectXFile::CreateEnumObjectメソッドを使用して、IDirectXFileEnumObject列挙オブジェクトを作成する。
  4. ファイル内のオブジェクトごとに繰り返す。オブジェクトごとに、次のステップを実行する。
    1. IDirectXFileEnumObject::GetNextDataObjectメソッドを使用して、IDirectXFileDataオブジェクトを取得する。
    2. IDirectXFileData::GetTypeメソッドを使用して、データ型を取得する。
    3. IDirectXFileData::GetDataメソッドを使用して、データをロードする。
    4. オブジェクトにオプションのメンバがあるときは、IDirectXFileData::GetNextObjectメソッドを呼び出して、そのオプションのメンバを取得する。
  5. IDirectXFileDataオブジェクトを解放する。
  6. IDirectXFileEnumObjectオブジェクトを解放する。
  7. IDirectXFileオブジェクトを解放する。

ファイルの保存

次の手順で、DirectXファイルのテンプレートとデータをDirectXファイルに保存する。

  1. DirectXFileCreate関数を使用して、IDirectXFileオブジェクトを作成する。
  2. IDirectXFile::RegisterTemplatesメソッドを使用して、これから使用するテンプレートをDirectXファイルシステムに通知する。
  3. IDirectXFile::CreateSaveObjectメソッドを使用して、IDirectXFileSaveObjectオブジェクトを作成する。
  4. 必要に応じ、IDirectXFileSaveObject::SaveTemplatesメソッドを使用して、テンプレートを保存する。
  5. 保存するオブジェクトごとに繰り返す。トップレベルのオブジェクトごとに、次のステップを実行する。
    1. IDirectXFileSaveObject::CreateDataObjectメソッドを使用して、ファイルのトップレベルのオブジェクトとして、IDirectXFileDataオブジェクトを作成する。トップレベルのデータオブジェクトにオプションの子オブジェクトがある場合、次のステップの「追加方法」の欄にある適切なメソッドを使用して、オブジェクトに子オブジェクトを追加する。
    2. IDirectXFileDataオブジェクトのテンプレートが許可していれば、各オブジェクトはオプションの子オブジェクトを持つことができる。子オブジェクトは、IDirectXFileData、IDirectXFileDataReference、またはIDirectXFileBinaryの3つのオブジェクトタイプのうち、どれでもよい。保存する必要のあるオブジェクトごとに繰り返し、次の表にある、オブジェクトタイプにあった方法で、オプションの子メンバをオブジェクトリストに追加する。
      オブジェクトタイプ | 追加方法
      データ | IDirectXFileSaveObject::CreateDataObjectメソッドを呼び出してIDirectXFileDataオブジェクトを作成し、次にIDirectXFileData::AddDataObjectメソッドを呼び出してオブジェクトの子として追加する。
      データ参照 | IDirectXFileData::AddDataReferenceメソッドを呼び出し、データ参照オブジェクトをオブジェクトの子として作成し追加する。
      バイナリ | IDirectXFileData::AddBinaryObjectメソッドを呼び出し、バイナリオブジェクトをオブジェクトの子として作成し追加する。
    3. IDirectXFileSaveObject::SaveDataメソッドを呼び出し、データオブジェクトと子オブジェクトをすべて保存する。
    4. IDirectXFileDataオブジェクトを解放する。
  6. IDirectXFileSaveObjectオブジェクトを解放する。
  7. IDirectXFileオブジェクトを解放する。

インターフェイス階層

DirectXファイルインターフェイス間の関係を以下に示す。

 IUnknown
 |
 +--IDirectXFile
 |
 +--IDirectXFileEnumObject
 |
 +--IDirectXFileObject
 |  |
 |  +--IDirectXFileBinary
 |  |
 |  +--IDirectXFileData
 |  |
 |  +--IDirectXFileDataReference
 |
 +--IDirectXFileSaveObject

関数とインターフェイス

DirectXでは、次のDirectXファイル関数とインターフェイスが用意されている。

  • DirectXFileCreate関数
  • IDirectXFile
  • IDirectXFileBinary
  • IDirectXFileData
  • IDirectXFileDataReference
  • IDirectXFileEnumObject
  • IDirectXFileObject
  • IDirectXFileSaveObject

次の表で、DirectXファイルの各インターフェイスに対応するグローバルユニーク識別子(GUID)を示す。QueryInterfaceメソッドでGUIDを使用し、子オブジェクトのタイプを判別する方法については、IDirectXFileDataインターフェイスの「はじめに」を参照すること。
インターフェイス | GUID
IDirectXFile | IID_IDirectXFile
IDirectXFileBinary | IID_IDirectXFileBinary
IDirectXFileData | IID_IDirectXFileData
IDirectXFileDataReference | IID_IDirectXFileDataReference
IDirectXFileEnumObject | IID_IDirectXFileEnumObject
IDirectXFileObject | IID_IDirectXFileObject
IDirectXFileSaveObject | IID_IDirectXFileSaveObject

DirectXFileCreate関数

DirectXFileCreate関数は、IDirectXFileインターフェイスを作成する。

構文

STDAPI DirectXFileCreate(LPDIRECTXFILE *ppDirectXFile);

パラメータ

ppDirectXFile
作成されたIDirectXFileインターフェイスを受け取るポインタのアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

この関数を使用した後、IDirectXFileメソッドを使用して、テンプレートの登録 (RegisterTemplates)、列挙オブジェクトの作成 (CreateEnumObject)、または保存オブジェクトの作成 (CreateSaveObject) を行う。

IDirectXFile

IDirectXFileインターフェイスにより、IDirectXFileEnumObjectオブジェクトとIDirectXFileSaveObjectオブジェクトを作成し、テンプレートを登録することができる。

DirectXFileCreate関数を使用して、このオブジェクトのインスタンスを作成する。

IDirectXFileインターフェイスでは、次のメソッドが用意されている。

  • CreateEnumObject
  • CreateSaveObject
  • RegisterTemplates

IDirectXFile::CreateEnumObject

IDirectXFile

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

構文

HRESULT CreateEnumObject(
  LPVOID pvSource,
  DXFILELOADOPTIONS dwLoadOptions,
  LPDIRECTXFILEENUMOBJECT * ppEnumObj);

パラメータ

pvSource
このポインタが指すデータの内容は、dwLoadOptionsの値によって次の表のように異なる。
dwLoadOptions値 | pvSourceの内容
DXFILELOAD_FROMFILE | ファイル名
DXFILELOAD_FROMRESOURCE | DXFILELOADRESOURCE構造体
DXFILELOAD_FROMMEMORY | DXFILELOADMEMORY構造体
DXFILELOAD_FROMURL | URL（Uniform Resource Locator）の名前
dwLoadOptions
データのソースを指定する値。DXFILELOADOPTIONS値の1つ。
ppEnumObj
作成されたIDirectXFileEnumObjectインターフェイスを受け取るポインタのアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADRESOURCE
DXFILEERR_BADVALUE
DXFILEERR_FILENOTFOUND
DXFILEERR_RESOURCENOTFOUND
DXFILEERR_URLNOTFOUND

注意

このメソッドを使用した後、IDirectXFileEnumObjectメソッドの1つを使用し、データオブジェクトを取得する。

IDirectXFile::CreateSaveObject

IDirectXFile

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

構文

HRESULT CreateSaveObject(
  LPCSTR szFileName,
  DXFILEFORMAT dwFileFormat,
  LPDIRECTXFILESAVEOBJECT * ppSaveObj);

パラメータ

szFileName
データを保存するファイルの名前へのポインタ。
dwFileFormat
ファイルフォーマット。DXFILEFORMAT定数の1つ。
ppSaveObj
作成されたIDirectXFileSaveObjectオブジェクトを受け取るポインタのアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADFILE
DXFILEERR_BADVALUE

注意

このメソッドを使用した後、IDirectXFileSaveObjectインターフェイスのメソッドを使用して、データオブジェクトを作成し、テンプレートやデータを保存する。

IDirectXFile::RegisterTemplates

IDirectXFile

カスタムテンプレートを登録する。

構文

HRESULT RegisterTemplates(
  LPVOID pvData,
  DWORD cbSize);

パラメータ

pvData
DirectXファイルを構成するバッファへのポインタ。DirectXファイルは、テンプレートを含むテキストまたはバイナリフォーマットである。
cbSize
pvDataが指すバッファのサイズ。単位はバイト。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADVALUE
DXFILEERR_PARSEERROR

注意

次のコードは、RegisterTemplatesの呼び出し例と、pvDataが指すバッファ内容の例である。

IDirectXFile * pDXFile;

char *szTemplates = "xof 0303txt 0032\
    template SimpleData { \
        <2b934580-9e9a-11cf-ab39-0020af71e433> \
        DWORD item1;DWORD item2;DWORD item3;} \
    template ArrayData { \
        <2b934581-9e9a-11cf-ab39-0020af71e433> \
        DWORD cItems; array DWORD aItem[2][cItems]; [...] } \
    template RestrictedData { \
        <2b934582-9e9a-11cf-ab39-0020af71e433> \
        DWORD item; [SimpleData]}";

hr = pDXFile->RegisterTemplates(szTemplates, strlen(szTemplates));

テンプレートはすべて、名前とUUID (ユニバーサルユニーク識別子) を指定しなければならない。

IDirectXFileBinary

IDirectXFileBinaryインターフェイスにより、バイナリデータの読み込みとデータに関する情報の取得ができる。

IDirectXFileBinaryインターフェイスでは、次のメソッドが用意されている。

  • GetMimeType
  • GetSize
  • Read

また、IDirectXFileBinaryは、IDirectXFileObject::GetIdメソッドとIDirectXFileObject::GetNameメソッドを継承する。

IDirectXFileBinary::GetMimeType

IDirectXFileBinary

バイナリデータのmimeタイプを取得する。

構文

HRESULT GetMimeType(LPCSTR * pszMimeType);

パラメータ

pszMimeType
mimeタイプの文字列を受け取るポインタのアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE

指定された.XファイルのバイナリオブジェクトにMimeタイプが指定されていない場合、この関数は*pszMimeTypeにNULLを設定する。

IDirectXFileBinary::GetSize

IDirectXFileBinary

バイナリデータのサイズを取得する。

構文

HRESULT GetSize(DWORD * pcbSize);

パラメータ

pcbSize
バイナリデータのサイズを受け取るポインタ。単位はバイト。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE

IDirectXFileBinary::Read

IDirectXFileBinary

バイナリデータを読み出す。

構文

HRESULT Read(
  LPVOID pvData,
  DWORD cbSize,
  LPDWORD pcbRead);

パラメータ

pvData
読み出されたデータを受け取るバッファへのポインタ。
cbSize
pvDataが指すバッファのサイズ。単位はバイト。
pcbRead
読み出されたバイト数へのポインタ。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOMOREDATA

IDirectXFileData

IDirectXFileDataインターフェイスでは、データオブジェクトの直接階層の構築またはアクセスができるメソッドが用意されている。テンプレートの制約が階層を決定する。テンプレートにより許可されたデータ型は、オプションメンバと呼ばれる。オプションメンバは必須ではないが、これがないと、オブジェクトから重要な情報が欠落することがある。オプションメンバは、データオブジェクトの子として保存される。子オブジェクトは、別のデータオブジェクト、以前のデータオブジェクトへの参照、またはバイナリオブジェクトである。

オブジェクトをDirectXファイルに保存するときは、AddBinaryObject、AddDataObject、またはAddDataReferenceを使用して、それぞれバイナリオブジェクト、データオブジェクト、またはデータ参照オブジェクトをファイルに追加する。詳細については、「ファイルの保存」を参照すること。

既存のDirectXファイルのオブジェクトを列挙するときは、次のように、GetData、GetNextObject、およびGetTypeメソッドを使用する。

  1. GetTypeを使用して、オブジェクトのテンプレートのGUIDを取得する。たとえば、メッシュオブジェクトの場合、メッシュテンプレートのGUIDを取得する。
  2. GetDataを使用して、連続するメモリチャンクから、必要なオブジェクトメンバを取得する。
  3. 子オブジェクトごとに、次のステップを実行する。
    1. GetNextObjectを使用して、子オブジェクトを取得する。
    2. QueryInterfaceを使用し、IDirectXFileData、IDirectXFileDataReference、およびIDirectXFileBinaryインターフェイスをサポートするかどうかを順に問い合わせて、子オブジェクトのタイプ (データ、データ参照、またはバイナリ) を判別する。サポートされるインターフェイスが、オブジェクトのタイプを示している。次のコードでは、オブジェクトがIDirectXFileBinaryをサポートするかどうかを判別することにより、バイナリオブジェクトかどうかを判別している。
      IDirectXFileObject *DXFileObj;
IDirectXFileBinary *DXFileBinary;

if (FAILED(DXFileObj->QueryInterface(IID_IDirectXFileBinary,
                                     (LPVOID *)&DXFileBinary))
{
    // オブジェクトはIDirectXFileBinaryをサポートしないため、
    // バイナリオブジェクトではない。
}
else
{
    // オブジェクトはバイナリである。
}
    3. 子オブジェクトのタイプを判別した後、そのタイプに合ったインターフェイス (IDirectXFileData、IDirectXFileDataReference、またはIDirectXFileBinary) のメソッドを使用して、子オブジェクトの操作を行う。

IDirectXFileDataインターフェイスでは、次のメソッドが用意されている。

  • AddBinaryObject
  • AddDataObject
  • AddDataReference
  • GetData
  • GetNextObject
  • GetType

また、IDirectXFileDataはIDirectXFileObject::GetIdメソッドとIDirectXFileObject::GetNameメソッドを継承する。

IDirectXFileData::AddBinaryObject

IDirectXFileData

子オブジェクトとしてバイナリオブジェクトを作成して追加する。

構文

HRESULT AddBinaryObject(
  LPCSTR szName,
  const GUID * pguid,
  LPCSTR szMimeType,
  LPVOID pvData,
  DWORD cbSize);

パラメータ

szName
オブジェクトの名前へのポインタ。オプションで、オブジェクトが名前を必要としないときは、NULLを指定する。
pguid
オブジェクトを表すGUIDへのポインタ。オプションで、オブジェクトがGUIDを必要としないときは、NULLを指定する。
szMimeType
オブジェクトのmimeタイプへのポインタ。
pvData
オブジェクトのデータへのポインタ。
cbSize
pvDataが指すバッファのサイズ。単位はバイト。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

子オブジェクトの保存の詳細については、このインターフェイス、IDirectXFileDataの「はじめに」を参照すること。

IDirectXFileData::AddDataObject

IDirectXFileData

子オブジェクトとしてデータオブジェクトを追加する。

構文

HRESULT AddDataObject(LPDIRECTXFILEDATA pDataObj);

パラメータ

pDataObj
子オブジェクトとして追加するIDirectXFileDataオブジェクトへのポインタ。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

このメソッドを呼び出す前に、IDirectXFileSaveObject::CreateDataObjectメソッドを使用して、IDirectXFileDataオブジェクトを作成する。

オブジェクトの保存の詳細については、このインターフェイス、IDirectXFileDataの「はじめに」を参照すること。

IDirectXFileData::AddDataReference

IDirectXFileData

子オブジェクトとしてデータ参照オブジェクトを作成して追加する。

構文

HRESULT AddDataReference(
  LPCSTR szRef,
  const GUID * pguidRef);

パラメータ

szRef
参照されるデータオブジェクトの名前へのポインタ。pguidRefでGUIDが参照できる場合は、NULLでよい。
pguidRef
データを表すGUIDへのポインタ。szRefで名前が参照できる場合は、NULLでよい。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

パラメータszRefまたはpguidRefの少なくともどちらか1つは、非NULLでなければならない。

オブジェクトの保存の詳細については、このインターフェイス、IDirectXFileDataの「はじめに」を参照すること。

IDirectXFileData::GetData

IDirectXFileData

1つのオブジェクトメンバのデータ、またはすべてのメンバのデータを取得する。

構文

HRESULT GetData(
  LPCSTR szMember,
  DWORD * pcbSize,
  void ** ppvData);

パラメータ

szMember
データを取得するメンバの名前。要求された全メンバのデータを取得するときは、NULLを指定する。
pcbSize
ppvDataのバッファサイズを受け取るポインタ。単位はバイト。
ppvData
szMemberに関連するデータを受け取るポインタのアドレス。szMemberがNULLのとき、*ppvDataは、連続するメモリブロックに要求された全メンバのデータが入っているバッファを指すように設定される。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADARRAYSIZE
DXFILEERR_BADDATAREFERENCE
DXFILEERR_BADVALUE

注意

このメソッドは、要求されたデータオブジェクトのメンバのデータを取得するが、オプション (子) メンバのデータは取得しない。子オブジェクトを取得するには、GetNextObjectを使用する。

オブジェクトの列挙の詳細については、このインターフェイス、IDirectXFileDataの「はじめに」を参照すること。

IDirectXFileData::GetNextObject

IDirectXFileData

DirectXファイルの、次の子データオブジェクト、データ参照オブジェクト、またはバイナリオブジェクトを取得する。

構文

HRESULT GetNextObject(LPDIRECTXFILEOBJECT * ppChildObj);

パラメータ

ppChildObj
子オブジェクトのIDirectXFileObjectインターフェイスへのポインタを受け取るアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

注意

取得するオブジェクトのタイプを判別するには、QueryInterfaceを使用して、取得するオブジェクトにIDirectXFileData、IDirectXFileDataReference、またはIDirectXFileBinaryインターフェイスをサポートするかどうかを問い合わせる。サポートされるインターフェイスが、オブジェクトタイプ (データ、データ参照、またはバイナリ) を示している。

子オブジェクト、オブジェクトの列挙、およびオブジェクトタイプの判別に関する詳細については、このインターフェイス、IDirectXFileDataの「はじめに」を参照すること。

IDirectXFileData::GetType

IDirectXFileData

オブジェクトのテンプレートのGUIDを取得する。

構文

HRESULT GetType(const GUID ** ppguid);

パラメータ

ppguid
オブジェクトのテンプレートのGUIDを受け取るポインタのアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE

IDirectXFileDataReference

IDirectXFileDataReferenceインターフェイスは、データ参照オブジェクトをサポートする。データ参照オブジェクトは、ファイル内で既に定義されているデータオブジェクトを参照する。これにより、ファイル内で定義を繰り返さなくても、同じオブジェクトを何度も使用することができる。

オブジェクトがデータ参照オブジェクトであると判別された後、このインターフェイスのResolveメソッドを使用して、ファイル内で既に定義されている実際のオブジェクトを取得する。データ参照オブジェクトの判別方法の詳細については、IDirectXFileDataインターフェイスを参照すること。

また、IDirectXFileDataReferenceは、IDirectXFileObject::GetIdとIDirectXFileObject::GetNameメソッドを継承する。

IDirectXFileDataReference::Resolve

IDirectXFileDataReference

データ参照を解決する。

構文

HRESULT Resolve(LPDIRECTXFILEDATA * ppDataObj);

パラメータ

ppDataObj
IDirectXFileDataオブジェクトを受け取るポインタのアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

IDirectXFileEnumObject

IDirectXFileEnumObjectインターフェイスでは、処理を繰り返して、ファイルの全データオブジェクトを取得したり、GUIDまたは名前でデータオブジェクトを取得することができる。

IDirectXFileEnumObjectインターフェイスでは、次のメソッドが用意されている。

  • GetDataObjectById
  • GetDataObjectByName
  • GetNextDataObject

IDirectXFileEnumObject::GetDataObjectById

IDirectXFileEnumObject

指定したGUIDを持つデータオブジェクトを取得する。

構文

HRESULT GetDataObjectById(
  REFGUID rguid,
  LPDIRECTXFILEDATA * ppDataObj);

パラメータ

rguid
指定したGUIDへの参照。
ppDataObj
取得したIDirectXFileDataオブジェクトを受け取るポインタ。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

IDirectXFileEnumObject::GetDataObjectByName

IDirectXFileEnumObject

指定した名前を持つデータオブジェクトを取得する。

構文

HRESULT GetDataObjectByName(
  LPCSTR szName,
  LPDIRECTXFILEDATA * ppDataObj);

パラメータ

szName
指定された名前へのポインタ。
ppDataObj
取得したIDirectXFileDataオブジェクトを受け取るポインタ。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

IDirectXFileEnumObject::GetNextDataObject

IDirectXFileEnumObject

DirectXファイルのトップレベルの次のオブジェクトを取得する。トップレベルのオブジェクトは常にデータオブジェクトである。データ参照オブジェクトとバイナリオブジェクトは、データオブジェクトの子にしかなれない。

構文

HRESULT GetNextDataObject(
  LPDIRECTXFILEDATA * ppDataObj);

パラメータ

ppDataObj
取得したIDirectXFileDataオブジェクトを受け取るポインタ。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

IDirectXFileObject

IDirectXFileObjectインターフェイスは、DirectXファイルオブジェクトの基本インターフェイスである。IDirectXFileData、IDirectXFileDataReference、およびIDirectXFileBinaryインターフェイスは、すべてこのインターフェイスから継承される。

IDirectXFileObjectインターフェイスでは、次のメソッドが用意されている。

  • GetId
  • GetName

IDirectXFileObject::GetId

IDirectXFileObject

DirectXファイルオブジェクトを識別するGUIDへのポインタを取得する。

構文

HRESULT GetId (LPGUID pGuid)

パラメータ

pGuid
オブジェクトのIDを受け取るGUIDへのポインタ。オブジェクトがIDを持っていない場合、この関数はGUIDにNULL GUIDを設定する。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE

IDirectXFileObject::GetName

IDirectXFileObject

DirectXファイルオブジェクトの名前へのポインタを取得する。

構文

HRESULT GetName (LPSTR pstrNameBuf, LPDWORD pdwBufLen)

パラメータ

pstrNameBuf
DirectXファイルオブジェクトの名前をコピーするバッファへのポインタ。バッファ長のみが必要な場合は、NULLに設定する。
pdwBufLen
pstrNameBufが指すバッファの長さを指定するDWORDへのポインタ。pstrNameBufがNULLであっても、pdwBufLenはオブジェクト名を保持するために必要なバッファ長に変更される。どちらの場合でも、pdwBufLenの元の値がオブジェクト名を保持するために必要な長さに足りないときには、関数はDXFILEERR_BADVALUEを返す。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADALLOC

IDirectXFileSaveObject

IDirectXFileSaveObjectインターフェイスにより、データオブジェクトを作成し、テンプレートとデータオブジェクトを保存することができる。IDirectXFile::CreateSaveObjectを使用して、このオブジェクトのインスタンスを作成する。次に、SaveTemplatesを使用して、テンプレートを保存する。データオブジェクトの作成には、CreateDataObjectを使用し、データの保存にはSaveDataを使用する。

必ずしもすべてのファイルにテンプレートが必要なわけではない。たとえば、すべてのDirectXファイルにそれぞれテンプレートを複製するのではなく、1つのDirectXファイルにテンプレートすべてを置くこともできる。

IDirectXFileSaveObjectインターフェイスでは、次のメソッドが用意されている。

  • CreateDataObject
  • SaveData
  • SaveTemplates

IDirectXFileSaveObject::CreateDataObject

IDirectXFileSaveObject

データオブジェクトを作成する。

構文

HRESULT CreateDataObject(
  REFGUID rguidTemplate,
  LPCSTR szName,
  const GUID * pguid,
  DWORD cbSize,
  LPVOID pvData,
  LPDIRECTXFILEDATA * ppDataObj);

パラメータ

rguidTemplate
データオブジェクトのテンプレートを表すGUID。
szName
データオブジェクトの名前へのポインタ。オプションで、オブジェクトが名前を持っていない場合は、NULLを指定する。このオブジェクトをデータ参照オブジェクトにより参照するには、szNameまたはpguidパラメータの、少なくともどちらか1つは非NULLでなければならない。
pguid
データオブジェクトを表すGUIDへのポインタ。オプションで、オブジェクトがGUIDを持っていない場合は、NULLを指定する。このオブジェクトをデータ参照オブジェクトにより参照するには、szNameまたはpguidパラメータの、少なくともどちらか1つは非NULLでなければならない。
cbSize
データオブジェクトのサイズ。単位はバイト。
pvData
要求されたメンバのデータすべてを格納するバッファへのポインタ。
ppDataObj
作成されたIDirectXFileDataオブジェクトを受け取るポインタのアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

SaveTemplatesメソッドを使用してテンプレートを保存してから、このメソッドで作成したデータを保存する。作成したデータは、SaveDataメソッドを使って保存する。オプションデータを保存する必要があるときは、このメソッドの後、SaveDataの前に、IDirectXFileData::AddDataObjectメソッドを使用する。オブジェクトに子オブジェクトがあるときは、SaveDataを呼び出す前に子オブジェクトを追加する。

IDirectXFileSaveObject::SaveData

IDirectXFileSaveObject

データオブジェクトとその子オブジェクトを、DirectXファイルに保存する。

構文

HRESULT SaveData(
  LPDIRECTXFILEDATA pDataObj);

パラメータ

pDataObj
保存するIDirectXFileDataオブジェクトへのポインタ。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADARRAYSIZE
DXFILEERR_BADVALUE

IDirectXFileSaveObject::SaveTemplates

IDirectXFileSaveObject

テンプレートをDirectXファイルに保存する。

構文

HRESULT SaveTemplates(
  DWORD cTemplates,
  const GUID ** ppguidTemplates);

パラメータ

cTemplates
保存するテンプレートの総数。
ppguidTemplates
保存するすべてのテンプレートに対するGUIDの配列へのポインタのアドレス。

戻り値

次の値のうち1つを返す。
DXFILE_OK
DXFILEERR_BADVALUE

注意

次のコードは、SaveTemplatesの呼び出し例と、ppuuidが指す配列の内容の例である。

IDirectXFileSaveObject * pDXFileSaveObject;

const GUID *aIds[] = {
    &DXFILEOBJ_SimpleData,
    &DXFILEOBJ_ArrayData,
    &DXFILEOBJ_RestrictedData};

hr = pDXFileSaveObject->SaveTemplates(3, aIds);

このメソッドでテンプレートを保存した後、IDirectXFileSaveObject::CreateDataObjectメソッドを使用してデータオブジェクトを作成する。

データ型

DirectXファイルのインターフェイスでは、次の定数と構造体を使用する。

  • DXFILEFORMAT定数
  • DXFILELOADMEMORY構造体
  • DXFILELOADOPTIONS定数
  • DXFILELOADRESOURCE構造体

DXFILEFORMAT定数

IDirectXFile::CreateSaveObjectメソッドで使用される値を指定し、DirectXファイルを保存するときに使用するフォーマットを示す。

構文

typedef DWORD DXFILEFORMAT;
#define DXFILEFORMAT_BINARY     0
#define DXFILEFORMAT_TEXT       1
#define DXFILEFORMAT_COMPRESSED 2

値

DXFILEFORMAT_BINARY
バイナリファイルを示す。
DXFILEFORMAT_TEXT
テキストファイルを示す。
DXFILEFORMAT_COMPRESSED
圧縮ファイルを示す。
ファイルフォーマットのデフォルト値は、DXFILEFORMAT_BINARYである。ファイルフォーマットの値を論理ORで結合して、圧縮テキストファイルや圧縮バイナリファイルを作成することもできる。ファイルがバイナリ (0) とテキスト (1) の両方として指定されている場合、その値はテキストファイルフォーマットの値 (0 + 1 = 1) と区別がつかないので、テキストファイルとして保存される。ファイルフォーマットとしてテキストと圧縮を指定すると、ファイルはまずテキストとして書き込まれてから圧縮される。ただし、圧縮テキストファイルはバイナリテキストファイルほど効率が良くないので、多くの場合、バイナリで圧縮を指定する。フォーマットを指定せずにファイルを圧縮するよう設定すると、バイナリで圧縮されたファイルになる。

DXFILELOADMEMORY構造体

アプリケーションがIDirectXFile::CreateEnumObjectメソッドを使用してDXFILELOAD_FROMMEMORYを指定するとき、ロードするリソースを識別する。

構文

typedef struct _DXFILELOADMEMORY {
    LPVOID lpMemory;
    DWORD dSize;
}DXFILELOADMEMORY, *LPDXFILELOADMEMORY;

メンバ

lpMemory
ロードするメモリブロックへのポインタ。
dSize
ロードするメモリブロックのサイズ。単位はバイト。

DXFILELOADOPTIONS定数

IDirectXFile::CreateEnumObjectメソッドで使用する値を指定し、ファイルデータのソースを示す。

構文

typedef DWORD DXFILELOADOPTIONS;
#define DXFILELOAD_FROMFILE  0x00L
#define DXFILELOAD_FROMRESOURCE 0x01L
#define DXFILELOAD_FROMMEMORY 0x02L
#define DXFILELOAD_FROMSTREAM 0x04L
#define DXFILELOAD_FROMURL 0x08L

値

DXFILELOAD_FROMFILE
ファイルから読み出されたデータを示す。
DXFILELOAD_FROMRESOURCE
リソースから読み出されたデータを示す。
DXFILELOAD_FROMMEMORY
メモリから読み出されたデータを示す。
DXFILELOAD_FROMSTREAM
ストリームから読み出されたデータを示す。現在はサポートされていない。
DXFILELOAD_FROMURL
URL (Uniform Resource Locator) から読み出されたデータを示す。

DXFILELOADRESOURCE構造体

アプリケーションがIDirectXFile::CreateEnumObjectメソッドを使用してDXFILELOAD_FROMRESOURCEを指定するとき、ロードするリソースを識別する。

構文

typedef struct _DXFILELOADRESOURCE {
    HMODULE hModule;
    LPCTSTR lpName;
    LPCTSTR lpType;
}DXFILELOADRESOURCE, *LPDXFILELOADRESOURCE;

メンバ

hModule
ロードするリソースを含むモジュールのハンドル。このメンバがNULLのときは、使用する実行ファイルにリソースをアタッチしなければならない。
lpName
ロードするリソースの名前。たとえば、リソースがメッシュのときは、このメンバはメッシュファイルの名前を指定する。
lpType
リソースを識別するユーザ定義のタイプ。

戻り値

DirectXファイルのCOM (Component Object Model) インターフェイスのメソッドは、標準のCOM戻り値のほかに次の値を返すことがある。

DXFILE_OK
コマンドは正常に完了した。DD_OKと同じ。
DXFILEERR_BADVALUE
パラメータが無効である。
DXFILEERR_BADTYPE
オブジェクトタイプが無効である。
DXFILEERR_BADALLOC
メモリ割り当てに失敗した。
DXFILEERR_NOTFOUND
オブジェクトが見つからない。
DXFILEERR_FILENOTFOUND
ファイルが見つからない。
DXFILEERR_RESOURCENOTFOUND
リソースが見つからない。
DXFILEERR_URLNOTFOUND
URLが見つからない。
DXFILEERR_BADRESOURCE
リソースが無効である。
DXFILEERR_BADFILETYPE
ファイルがDirectXファイルではない。
DXFILEERR_BADFILEVERSION
ファイルのバージョンが無効である。
DXFILEERR_BADFILEFLOATSIZE
浮動小数点のサイズが無効である。
DXFILEERR_BADFILE
ファイルが無効である。
DXFILEERR_PARSEERROR
ファイルが構文解析できない。
DXFILEERR_BADARRAYSIZE
配列のサイズが無効である。
DXFILEERR_BADDATAREFERENCE
データ参照が無効である。
DXFILEERR_NOMOREOBJECTS
オブジェクトは既に、すべて列挙されている。
DXFILEERR_NOMOREDATA
これ以降のデータは取得できない。


動作環境

API 要素の構文を紹介する各トピックには、これらの要素を使うときに必要となる、ビルドおよび実行時の動作環境についての情報が含まれている。動作環境の書式は、次のとおりである。

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降が必要。
Windows CE : バージョン 1.0 以降が必要。
ヘッダー : winuser.h で宣言。
インポート ライブラリ : user32.lib を使用。
Unicode : Windows NT/2000 上の Unicode および ANSI バージョンとして実装される。

1 行目では、API 要素をサポートしている Windows NT のバージョンについての情報が記述されている。この情報には、必要とされるサービス パック、オプション パック、または Internet Explorer などのコンポーネントについての情報が含まれる。Windows NT または Windows 2000 で API 要素がサポートされていない場合は、"Windows NT/2000 : 未対応。" という書式で表される。

2 行目では、API 要素が Windows 95 または Windows 98 上でサポートされているかどうかについての情報が記述されている。この情報には、必要とされる OEM サービス リリース、再配布可能かどうか、または Internet Explorer などのコンポーネントについての情報が含まれる。Windows 95 または Windows 98 で API 要素がサポートされていない場合は、"Windows 95/98 : 未対応。" という書式で表される。

3 行目では、API 要素をサポートしている Windows CE のバージョンについての情報が記述されている。Windows CE で API 要素がサポートされていない場合は、"Windows CE : 未対応。" という書式で表される。

4 行目では、API 要素が定義されているファイルについての情報が記述されている。この情報には、.h ファイル、.idl ファイル、または .odl ファイルについての情報が含まれる。ヘッダ ファイルがユーザーによって提供される場合は、"ヘッダ : ユーザー定義。" という書式で表される。

5 行目では、関数またはメンバへの呼び出しの解決に使用されるファイルについての情報が記述されている。この情報には、.lib ファイル、.dll ファイル、または .tlb ファイルについての情報が含まれる。インポート ライブラリがユーザーによって提供される場合は、"インポート ライブラリ : ユーザー定義。" という書式で表される。インポート ライブラリを必要としない API 要素では、この行は省略される。

6 行目では、API 要素が Unicode (W) バージョンおよび ANSI (A) バージョンの両方でサポートされているかどうかについての情報が記述されている。API 要素が Unicode バージョンでサポートされていない場合、この行は省略される。


カラー キー フォーマット

[C++]

カラー キーは DDCOLORKEY 構造体に記述される。カラー キーが単色の場合、この構造体の両メンバは同じ値に割り当てられる。または、カラー キーが色域となる。

カラー キーは、サーフェスのピクセル フォーマットを用いて指定される。サーフェスがパレット化されたフォーマットである場合、カラー キーはインデックスまたはインデックス域として指定される。サーフェスが非パレット化ディスプレイ モードにある場合、カラー キーは未処理のピクセル フォーマットで指定される。たとえば、真紫のカラー キーを 16 ビットの 5:6:5 モードで設定するには、0xf81F (赤と青の 5 ビットをすべて設定) の値を使用する。

有効なカラー キーの例をいくつか以下に示す。

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

// パレット エントリ 26 はカラー キー。
dwColorSpaceLowValue = 26;
dwColorSpaceHighValue = 26;

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

// 色は真紫。
dwColorSpaceLowValue = 0xf81F;
dwColorSpaceHighValue = 0xf81F;

単色ではなく色域に対するサポートはハードウェアによる。ハードウェアに対する DDCAPS 構造体の dwCKeyCaps メンバをチェックすること。HEL は色域をサポートしない。

[Visual Basic]

カラー キーは DDCOLORKEY 型に記述される。カラー キーが単色の場合、この型の両メンバは同じ値に割り当てられる。または、カラー キーが色域となる。

カラー キーは、サーフェスのピクセル フォーマットを用いて指定される。サーフェスがパレット化されたフォーマットである場合、カラー キーはインデックスまたはインデックス域として指定される。サーフェスが非パレット化ディスプレイ モードにある場合、カラー キーは未処理のピクセル フォーマットで指定される。たとえば、赤のカラー キーを 24 ビット トゥルー カラー モードで設定するには、&HFF (赤の 5 ビットをすべて設定) の値を使用する。

有効なカラー キーの例をいくつか以下に示す。

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

' パレット エントリ 26 はカラー キー。
low = 26
high = 26

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

// 16 進の赤の値がカラー キーになる。
low = &HFF
high = &HFF

単色ではなく色域に対するサポートはハードウェアによる。ハードウェアに対する DDCAPS 型の lCKeyCaps メンバをチェックすること。HEL は色域をサポートしない。


ガンマ ランプ レベルの設定と取得

[C++]

ガンマ ランプ レベルは効果的な参照テーブルであり、DirectDraw が表示される新しいレベルにフレーム バッファ色成分をマップするために使用する。詳細については、「ガンマ ランプ レベルについて」を参照すること。IDirectDrawGammaControl::SetGammaRamp および IDirectDrawGammaControl::GetGammaRamp メソッドを呼び出すことにより、プライマリ サーフェスに対するランプ レベルを設定し、取得できる。両メソッドでは 2 つのパラメータを受け取るが、最初のパラメータは後の使用のために確保し、ゼロに設定しなくてはならない。2 番目のパラメータ lpRampData は、DDGAMMARAMP 構造体のアドレスとする。DDGAMMARAMP 構造体には、WORD の 256 要素配列を 3 つ (1 つの配列ごとに赤、緑、青のガンマ ランプ) 含む。

IDirectDrawGammaControl::SetGammaRamp を呼び出すときに DDSGR_CALIBRATE 値を含むと、新しいガンマレベルを設定するときに口径測定器を起動できる。ガンマ ランプをキャリブレーションするといくらかオーバーヘッドがあるので、頻繁には使えない。調整されたガンマ ランプの設定は、ビューワーやディスプレイ アダプタおよびモニタにかかわらず、一貫性のある完全なガンマ値を提供する。

すべてのシステムでガンマ キャリブレーションをサポートするわけではない。ガンマ キャリブレーションをサポートする場合を決定するには、IDirectDraw7::GetCaps を呼び出して、メソッドが戻った後に関連付けられた DDCAPS 構造体の dwCaps2 メンバを調べる。DDCAPS2_CANCALIBRATEGAMMA 能力フラグが示されていれば、ガンマ キャリブレーションがサポートされる。

新しいランプ レベルを設定する場合、その配列に設定したレベルはアプリケーションがフルスクリーン (排他モード) の場合にだけ使用される。アプリケーションがノーマル モードに変更されると、常にランプ レベルは一時的に設定され、アプリケーションがフルスクリーン モードに復帰されるときに再び取得される。さらに、プライマリ サーフェス以外のサーフェスに対しては、ランプ レベルを設定できないことを思い出すこと。

注 ： Win32® API に非常に精通している方は、Win32 が GetDeviceGammaRamp と SetDeviceGammaRamp 関数を同じサーフェスに対して提供する場合に、DirectDraw が IDirectDrawGammaControl のようなインターフェイスを公開するすることを不思議に思うかもしれない。Win32 API にもこれらの関数はあるが、IDirectDrawGammaControl インターフェイスのメソッドのように、すべての Windows プラットフォームで必ず成功するとはかぎらない。

[Visual Basic]

ガンマ ランプ レベルは効果的な参照テーブルであり、DirectDraw が表示される新しいレベルにフレーム バッファ色成分をマップするために使用する。詳細については、「ガンマ ランプ レベルについて」を参照すること。DirectDrawGammaControl.SetGammaRamp および DirectDrawGammaControl.GetGammaRamp メソッドを呼び出すことにより、プライマリ サーフェスに対するランプ レベルを設定し、取得できる。両メソッドでは 2 つのパラメータを受け取るが、最初のパラメータを使ってキャリブレーションを指定する。2 番目のパラメータ gammaRamp は、DDGAMMARAMP 型である。DDGAMMARAMP 型には、Integer の 256 要素配列を 3 つ (1 つの配列ごとに赤、緑、青のガンマ ランプ) 含む。

DirectDrawGammaControl.SetGammaRamp を呼び出すときに DDSGR_CALIBRATE 値を含むと、新しいガンマ レベルを設定するときに口径測定器を起動できる。ガンマ ランプをキャリブレーションするといくらかオーバーヘッドがあるので、頻繁には使えない。調整されたガンマ ランプの設定は、ビューワーやディスプレイ アダプタおよびモニタにかかわらず、一貫性のある完全なガンマ値を提供する。

すべてのシステムでガンマ キャリブレーションをサポートするわけではない。ガンマ キャリブレーションをサポートする場合を決定するには、DirectDraw7.GetCaps を呼び出して、メソッドが戻った後に関連付けられた DDCAPS 型の lCaps2 メンバを調べる。DDCAPS2_CANCALIBRATEGAMMA 能力フラグが示されていれば、ガンマ キャリブレーションがサポートされる。

新しいランプ レベルを設定する場合、その配列に設定したレベルはアプリケーションがフルスクリーン (排他モード) の場合にだけ使用される。アプリケーションがノーマル モードに変更されると、常にランプ レベルは側に設定され、アプリケーションがフルスクリーン モードに復帰されるときに再び取得される。さらに、プライマリ サーフェス以外のサーフェスに対しては、ランプ レベルを設定できないことを思い出すこと。

注 ： Win32® API に非常に精通している方は、Win32 が GetDeviceGammaRamp と SetDeviceGammaRamp 関数を同じサーフェスに対して提供する場合に、DirectDraw が DirectDrawGammaControl のようなインターフェイスを公開するすることを不思議に思うかもしれない。Win32 API にもこれらの関数はあるが、DirectDrawGammaControl インターフェイスのメソッドのように、すべての Windows プラットフォームで必ず成功するとはかぎらない。


受動ディスプレイ デバイス

ヘッドマウント ディスプレイや自動ステレオグラフィックス ディスプレイなどの受動ステレオ ディスプレイは、能動デバイスよりも制御が簡単である。受動ディスプレイには、各々の眼が別のビューを受け取るように構成された個別の表示 (または単一の表示領域) がある。DirectDraw は、単一の表示サーフェスに左と右のサーフェスを作成する。表示サーフェスのスキャン データがデバイスに送られ、デバイスはそのデータを適切な場所に配置する。たとえば、ヘッドマウント ディスプレイでは、単一の 640 × 480 表示サーフェスを、左右それぞれ 320 × 480 のサーフェスで構成された並列ユニットとして扱う必要がある。この場合、ディスプレイ デバイスは適切なイメージを各眼の前に配置する。

受動デバイスでは同期の問題がないので、サーフェス フリップは、フリップされたサーフェスに論理的に 2 つ (左と右) のサーフェスが存在することを除けば、基本的に非ステレオ サーフェス フリップと同じである。

一般に、受動ディスプレイ デバイスでは、ディスプレイのピクセルの 1/2 を左の眼に、残りの 1/2 を右の眼に表示する。このようなデバイスとしては、ヘッドマウント ディスプレイや、ピクセル列を左と右の眼に交互にフィルタリングする画面のグレーティング オーバーレイ機能を持つモニタなどがある。各眼は、モニタのリフレッシュ レートでイメージを表示する。


アルファ チャネルによるテクスチャ

より複雑な透過性を示すテクスチャ マップの符号化には、2 通りの方法がある。どちらの場合も、透過性を記述するブロックは既に記述されている 64 ビット ブロックより先に起こる。透過性はピクセルごとに 4 ビットの 4 × 4 ビットマップ (明示的な符号化)、またはそれ以下のビットのビットマップのどちらかであり、線形補間は色符号化で使用されることと類似する。

透過性ブロックと色ブロックの配置

単語アドレス | 64 ビット ブロック
3:0 | 透過性ブロック
7:4 | 既に記述された 64 ビット ブロック

明示的なテクスチャ符号化

明示的なテクスチャ符号化 (DXT2 と DXT3 フォーマット) のために、透過性を記述するテクセルのアルファ コンポーネントは、テクセルごとに 4 ビットの 4 × 4 ビットマップで符号化される。これらの 4 ビットは、アルファ データで一番重要な 4 つのビットのディザリングや単なる使用などのさまざまな方法で達成できる。ただし、作成されると、あらゆる補間のフォームがないとそれだけでしか使用できない。

注 ： DirectDraw の圧縮メソッドは、4 つの最上位ビットを使用する。

次に示す表は、アルファ情報が各 16 ビット単語用に配置される方法について示する。

単語 0 用の配置

ビット | アルファ
3:0 (LSB) | [0][0]
7:4 | [0][1]
11:8 | [0][2]
15:12 (MSB) | [0][3]

単語 1 用の配置

ビット | アルファ
3:0 (LSB) | [1][0]
7:4 | [1][1]
11:8 | [1][2]
15:12 (MSB) | [1][3]

単語 2 用の配置

ビット | アルファ
3:0 (LSB) | [2][0]
7:4 | [2][1]
11:8 | [2][2]
15:12 (MSB) | [2][3]

単語 3 用の配置

ビット | アルファ
3:0 (LSB) | [3][0]
7:4 | [3][1]
11:8 | [3][2]
15:12 (MSB) | [3][3]

3 ビット線形アルファ補間

DXT4 および DXT5 フォーマットに対する透過性の符号は、色に使用される線形符号と類似する概念が基となる。2 つの 8 ビット アルファ値とピクセルごとに 3 ビットの 4 × 4 ビットマップは、ブロックの最初の 8 バイトに格納される。典型的なアルファ値は、中間アルファ値を補間するために使用される。追加情報は、2 つのアルファ値を格納する方法で利用できる。アルファ _0 がアルファ _1 より大きい場合、6 つの中間アルファ値が補間により作成される。また、4 つの中間アルファ値が指定されるアルファ極値間で補間される。2 つの追加の明示的なアルファ値は、0 (完全に透過型) と 255 (完全に不透明) となる。

[C++]

次の類似コードでこのアルゴリズムを示す。

// 8 アルファまたは 6 アルファ ブロック?
if (alpha_0 > alpha_1) {
     // 8 アルファ ブロック : 他の 6 つのアルファを派生する。
    // 000 = アルファ 0, 001 = アルファ 1, その他は補間される。
    alpha_2 = (6 * alpha_0 + alpha_1) / 7;      // ビット コード 010
    alpha_3 = (5 * alpha_0 + 2 * alpha_1) / 7;  // ビット コード 011
    alpha_4 = (4 * alpha_0 + 3 * alpha_1) / 7;  // ビット コード 100
    alpha_5 = (3 * alpha_0 + 4 * alpha_1) / 7;  // ビット コード 101
    alpha_6 = (2 * alpha_0 + 5 * alpha_1) / 7;  // ビット コード 110
    alpha_7 = (alpha_0 + 6 * alpha_1) / 7;      // ビット コード 111
  }
else {  // 6 アルファ ブロック : 他のアルファを派生する。
    // 000 = アルファ 0, 001 = アルファ 1, その他は補間される。
    alpha_2 = (4 * alpha_0 + alpha_1) / 5;      // ビット コード 010
    alpha_3 = (3 * alpha_0 + 2 * alpha_1) / 5;  // ビット コード 011
    alpha_4 = (2 * alpha_0 + 3 * alpha_1) / 5;  // ビット コード 100
    alpha_5 = (alpha_0 + 4 * alpha_1) / 5;      // ビット コード 101
    alpha_6 = 0;                                // ビット コード 110
    alpha_7 = 255;                              // ビット コード 111
}

アルファ ブロックのメモリ層を次に示す。

バイト | アルファ
0 | アルファ _0
1 | アルファ _1
2 | [0][2] (2 LSBs) , [0][1], [0][0]
3 | [1][1] (1 LSB) , [1][0], [0][3], [0][2] (1 MSB)
4 | [1][3], [1][2], [1][1] (2 MSBs)
5 | [2][2] (2 LSBs) , [2][1], [2][0]
6 | [3][1] (1 LSB) , [3][0], [2][3], [2][2] (1 MSB)
7 | [3][3], [3][2], [3][1] (2 MSBs)

[C++,Visual Basic]


不透明と 1 ビット アルファ テクスチャ

テクスチャ フォーマット DXT1 は、不透明または単一の透過型色のあるテクスチャ用である。

各不透明または 1 ビット アルファ ブロックのために、2 つの 16 ビット値 (RGB 5:6:5 フォーマット) とピクセルごとに 2 ビットの 4 × 4 ビットマップが格納される。これは、16 テクセルまたは 4 ビット/テクセルに対して合計 64 ビットとなる。ブロック ビットマップには、4 色間を選択するテクセルごとに 2 ビットがある。4 色のうち 2 色は、符号化されたデータに格納される。他の 2 色は、線形補間で格納される色から派生する。

1 ビット アルファ フォーマットは、ブロックに格納される 16 ビットカラー値を比較することにより、不透明フォーマットと区別される。これらは、符号なしの整数として処理される。最初の色が次の色よりも大きい場合は、不透明テクセルだけが定義されていることを意味する。これは、4 色がテクセルを現すために使用されることを意味する。4 色の符号化には 2 つの派生した色があり、全 4 色は RGB 色空間に等しく配布される。このフォーマットは、RGB 5:6:5 フォーマットに類似している。他の点では、1 ビット アルファ透過性用にこれらの色は使用され、4 番目の色は透過型テクセルを現すために確保される。

3 つの色の符号化には 1 つの派生した色があり、4 番目の 2 ビット コードは透過型テクセル (アルファ情報) を含むために確保される。このフォーマットは、アルファ マスクを符号化するために使用される最後のビットのある RGBA 5:5:5:1 に類似している。

[C++]

次に示す類似コードの一部で、3 または 4 色符号化が選択されるかどうかを決定するためのアルゴリズムを説明する。

if (color_0 > color_1)
{
// 4 色ブロック :他の 2 色を派生する。
// 00 = 色 0_, 01 = 色 1, 10 = 色 2, 11 = 色 3
// 64 ビット ブロックに確保される
// 2 ビットフィールドに対応する 2 ビット コード。
     color_2 = (2 * color_0 + color_1) / 3;
     color_3 = (color 0 + 2 * color_1) / 3;
}
else
{
// 3 色ブロック :他の色を派生する。
// 00 = 色 0, 01 = 色 1, 10 = 色 2,
// 11 = 透過型。
// 64 ビット ブロックに確保される
// 2 ビットフィールドに対応する 2 ビット コード。
color_2 = (color_0 + color_1) / 2;
color_3 = transparent;
}

8 バイト ブロック用のメモリ層を次の表で示す。最初のインデックスが y 軸、2 番目のインデックスが x 軸に対応すると考える。たとえば、テクセル [1][2] は (x,y) = (2,1) でテクスチャ マップ ピクセルを参照する。

8 バイト (64 ビット) ブロック用のメモリ層

単語アドレス | 16 ビット単語
0 | 色 _0
1 | 色 _1
2 | ビットマップ単語 _0
3 | ビットマップ単語 _1

色 0 と色 1 (2 極値での色) の配置

ビット | 色
04:00 (LSB) | 青色成分
10:5 | 緑色成分
15:11 | 赤色成分

ビットマップ word_0 の配置

ビット | テクセル
01:00 (LSB) | テクセル [0][0]
3:2 | テクセル [0][1]
5:4 | テクセル [0][2]
7:6 | テクセル [0][3]
9:8 | テクセル [1][0]
11:10 | テクセル [1][1]
13:12 | テクセル [1][2]
15:14 (MSB) | テクセル [1][3]

ビットマップ word_1 の配置

ビット | テクセル
01:00 (LSB) | テクセル [2][0]
3:2 | テクセル [2][1]
5:4 | テクセル [2][2]
7:6 | テクセル [2][3]
9:8 | テクセル [3][0]
11:10 | テクセル [3][1]
13:12 | テクセル [3][2]
15:14 (MSB) | テクセル [3][3]

不透明色符号の例

不透明符号の例として、赤と黒が極値であると仮定する。赤色 _0 および黒色 _1 とする。一様に傾度を互いに分割したフォームの補間した 4 色がある。4 × 4 ビットマップの値を決定するには、次に示す計算式を使用する。

00 ? color_0
01 ? color_1
10 ? 2/3 color_0 + 1/3 color_1
11 ? 1/3 color_0 + 2/3 color_1

1 ビット アルファ符号の例

符号なし 16 ビット整数 (色 _0) が符号なし 16 ビット整数 (色 _1) より小さい場合、このフォーマットが選択される。このフォーマットの使用例としては、青空に対して示される木の葉である。いくつかのテクセルは、3 色の緑の影が葉に対して使用される間に透過型として記される。これらの色の 2 色は極値に適合し、3 番目の色は補間した色となる。

色と透過性に対するビットマップ符号は、次の計算式を使用して決定される。

00 ? color_0
01 ? color_1
10 ? 1/2 color_0 + 1/2 color_1
11   ?   Transparent

[C++,Visual Basic]


能動ディスプレイ デバイス

LCD シャッター レンズなどの能動デバイスでは、左眼のビューと右眼のビューで単一のディスプレイ デバイスを時多重化する。DirectDraw は、能動デバイスに同期化する 2 つのサーフェスを作成する。能動デバイスは、各眼のビューをいつディスプレイに表示するかを制御し、システムがモニタの左眼のビューと右眼のビューを交互にブロックする。各眼は、モニタの 1/2 のリフレッシュ レートのイメージで表される。したがって、アプリケーションはステレオ ビュー機能を高リフレッシュ レートで使用する必要がある。シャッター レンズを使用するには、モニタが十分なリフレッシュ レートをサポートしていなければならない。理想的には、各眼で 60 Hz (またはそれ以上) のリフレッシュ レートが必要である。リフレッシュ レートについては、「リフレッシュ レートの列挙」を参照すること。

シャッター レンズなどのシーケンシャル ディスプレイでは、ドライバはディスプレイと能動デバイスの同期を維持しなければならない。通常、ドライバが能動デバイスの状態をモニタする。たとえば、VESA (Video Electronics Standards Association) の標準ステレオ コネクタは、能動 LCD デバイスのシャッターを制御できる。また、ドライバは、特定の時間にどちらの眼がアクティブになっているかをモニタできる。この情報に基づいて、サーフェス フリップは左と右のイメージが常にペアでディスプレイに表示されるようにする。

DirectDraw は、ダイレクト ステレオ コネクタ付きグラフィックス カードのある能動デバイスだけを公開する。アドイン ゴーグルはサポートされない。


透過型ブリットとは?

透過型ブリットにより、スプライトをアニメーションする際に非矩形のブリットによる動画を作成できる。通常、スプライト イメージは非矩形であるが、ブリットは常に矩形であるため、スプライトの境界矩形内の各ピクセルがデータ転送の一部となる。透過型ブリットにより、スプライト イメージ部分以外の各ピクセルは、ブリットがその転送先にイメージを移動する際に透過型として扱われて転送される。このため、これらのピクセルは、バックグラウンド イメージ上のピクセルの色をオーバーライトしない。

スプライトを作成する場合、透過性カラー キーとして使用する任意の色や色域を選択する。これは、決して透過性カラー キー以外に使用しない単一の色で、要求されるイメージ部分以外のスプライト矩形部分全体を満たすために使用される。スプライトを含むサーフェスのカラー キーを設定するのは実行時である (必要であれば、このカラー キーはイメージの左上隅のピクセル色に自動的に設定できる)。続いて起こるブリットは、色に適合するピクセルを無視するようカラー キーを利用できる。この種のカラー キーは転送元カラー キーという。

また、ハードウェアが転送先カラー キーイングをサポートする転送先サーフェスのカラー キーも使用できる。この転送先カラー キーは、スプライトがオーバーライトできるピクセルに対して使用される。たとえば、前景イメージでタスクをしているとする。このイメージは、窓付きの部屋の壁のように後ろに渡すためのスプライトをサポートする。作業者は任意の色 (イメージ以外の場所で使用されない色) を選択し、窓の外に空を表わす。転送先サーフェスに対してこのカラー キーを設定し、そのサーフェスにスプライトをブリットする場合、スプライトのピクセルは転送先カラー キーを使用するピクセルだけをオーバーライトする。この例では、スプライトは壁や窓枠ではなく窓の中だけに表示される。この結果、スプライトは部屋の外側にあるように見える。

転送元および転送先カラー キーを組み合わせることができる。この例では、スプライトが転送元カラー キーを使用することもできるが、その場合スプライトの境界矩形全体から空のバックグラウンドを切り出すことができない。


ガンマ ランプ レベルについて

DirectDraw のガンマ ランプとは、一連の値を記述するために使用する項である。この一連の値は、フレーム バッファのすべてのピクセルに対して、モニタ上のディスプレイに対するデジタル-アナログ コンバータ (DAC) により受け取られる新しいレベルに、特定の色成分 (赤、緑、および青) のレベルをマップする値である。再マッピングは、3 つの単純な参照テーブル (個々の色成分に対して 1 つ) により実行される。

ここではその方法について説明する。DirectDraw はフレーム バッファからピクセルを取得し、その固有の赤、緑、および青の色成分の項でピクセルを取得する。個々のコンポーネントは 0 から 65535 までの値で表される。DirectDraw は元の値を取得し、その値を使用して 256 要素配列 (ランプ) にインデックスを付ける。この配列には、個々の要素を元の要素と置き換える値を含む。DirectDraw では、フレーム バッファ内の各ピクセルの各色成分に対して " 参照と置き換え " のプロセスを実行し、スクリーン上のすべてのピクセルに対する最終的な色を変更する。

ランプ値のグラフを作成すると、視覚化されて容易に理解できる。次に、2 つのグラフを示す。左側のグラフは色がまったく変更されないランプを示し、右側のグラフは負のバイアスを適用する色成分に置くランプを示す。

左側のグラフの配列要素には、それらのインデックスと等しい値 (インデックス 0 には要素 0、およびインデックス 65535 には 255) が含まれる。これらの値が表示される前の入力値は変更できないため、ランプのこのタイプがデフォルトとなる。右側のグラフの方がより興味深い。このランプには、最初の要素の 0 から最後の要素の 32768 までの値が、中間の比較的一様な範囲の値で含まれる。このエフェクトは、このランプを使用する色成分がディスプレイ上で音を消して表示される。線形グラフの利用だけにかぎらない。つまり、アプリケーションで任意のマッピングを割り当てなくてはならない場合にも同様に行える。さらに、入力をすべてゼロに設定すると、ディスプレイから特定の色成分を設定できる。


ガンマ ランプ サポートの検出

[C++]

IDirectDraw7::GetCaps メソッドを呼び出すことで、ハードウェアがダイナミック ガンマ ランプ調節をサポートするかどうかを決定できる。この呼び出しの後、DDCAPS2_PRIMARYGAMMA フラグが関連する DDCAPS 構造体の dwCaps2 メンバで示される場合、そのハードウェアはダイナミック ガンマ ランプをサポートする。ハードウェアがダイナミック ガンマをサポートしない場合はそれを使用できないため、DirectDraw はこの機能をエミュレートしようとする。

[Visual Basic]

DirectDraw7.GetCaps メソッドを呼び出すことで、ハードウェアがダイナミック ガンマ ランプ調整をサポートするかどうかを決定できる。この呼び出しの後、DDCAPS2_PRIMARYGAMMA フラグが関連する DDCAPS 型の ｌCaps2 メンバで示される場合、そのハードウェアはダイナミック ガンマ ランプをサポートする。ハードウェアがダイナミック ガンマをサポートしない場合はそれを使用できないため、DirectDraw はこの機能をエミュレートしようとする。


カラー キーの設定

[C++]

サーフェスの作成時もしくはその後で、サーフェスに対する転送元または転送先カラー キーを設定できる。

サーフェスの作成時にカラー キーまたはキーを設定する場合は、IDirectDraw7::CreateSurface に渡す DDSURFACEDESC2 構造体の ddckCKSrcBlt および ddckCKDestBlt メンバのどちらかまたは両方に、適切なカラー値を割り当てる。ブリットのカラー キーを確認するには、dwFlags メンバの DDSD_CKSRCBLT および DDSD_CKDESTBLT のどちらかまたは両方にもカラー値を含まなくてはならない。

既存サーフェスのカラー キーを設定するには、IDirectDrawSurface7::SetColorKey メソッドを使用する。lpDDColorKey パラメータのキーを指定し、dwFlags パラメータに DDCKEY_SRCBLT または DDCKEY_DESTBLT のどちらかを設定する。このフラグは、転送元または転送先キーの設定の有無を示す。DDCOLORKEY 構造体に色域が含まれる場合、DDCKEY_COLORSPACE フラグも設定しなくてはならない。このフラグを設定しない場合、構造体の dwColorSpaceLowValue メンバだけが使用される。

[Visual Basic]

サーフェスの作成時もしくはその後で、サーフェスに対する転送元または転送先カラー キーを設定できる。

サーフェスの作成時にカラー キーまたはキーを設定する場合は、DirectDraw7.CreateSurface に渡す DDSURFACEDESC2 型の ddckCKSrcBlt および ddckCKDestBlt メンバのどちらかまたは両方に、適切なカラー値を割り当てる。ブリットのカラー キーを確認するには、lFlags メンバの DDSD_CKSRCBLT および DDSD_CKDESTBLT のどちらかまたは両方にもカラー値を含まなくてはならない。

既存サーフェスのカラー キーを設定するには、DirectDrawSurface7.SetColorKey メソッドを使用する。val パラメータのキーを指定し、flags パラメータに DDCKEY_SRCBLT または DDCKEY_DESTBLT のどちらかを設定する。このフラグは、転送元または転送先キーの設定の有無を示す。DDCOLORKEY 型に色域が含まれる場合、DDCKEY_COLORSPACE フラグも設定しなくてはならない。このフラグを設定しない場合、構造体の low メンバだけが使用される。


カラー キーによるブリット

[C++]

IDirectDrawSurface7::BltFast メソッドの呼び出し時にサーフェスへカラー キーを使用したい場合、dwTrans パラメータに DDBLTFAST_SRCCOLORKEY または DDBLTFAST_DESTCOLORKEY フラグの 1 つもしくは両方を設定しなくてはならない。

IDirectDrawSurface7:Blt の呼び出し時にカラー キーを使用するには、dwFlags パラメータの DDBLT_KEYSRC または DDBLT_KEYDEST フラグの 1 つもしくは両方を渡さなくてはならない。代わりに、DDBLTFX 構造体の ddckDestColorkey および ddckSrcColorkey メンバに適切なカラー値を配置できる。この構造体は、lpDDBltFx パラメータでメソッドに渡される。この場合でも、DBLT_KEYSRCOVERRIDE または DDBLT_KEYDESTOVERRIDE フラグ、もしくはその両方を dwFlags パラメータに設定しなくてはならない。このため、選択されたキーはサーフェス プロパティではなく DDBLTFX 構造体から取得される。

[Visual Basic]

DirectDrawSurface7.BltFast メソッドの呼び出し時にサーフェスへカラー キーを使用したい場合、trans パラメータに DDBLTFAST_SRCCOLORKEY または DDBLTFAST_DESTCOLORKEY フラグの 1 つもしくは両方を設定しなくてはならない。

DirectDrawSurface7.Blt の呼び出し時にカラー キーを使用するには、flags パラメータの DDBLT_KEYSRC または DDBLT_KEYDEST フラグの 1 つもしくは両方を渡さなくてはならない。あるいは、DirectDrawSurface7:BltFx メソッドを使って、DDBLTFX 型の ddckDestColorkey_high、ddckDestColorkey_low、ddckSrcColorkey_high および ddckSrcColorkey_low メンバに適切なカラー値を入れることができる。この型は、BltFx パラメータによってメソッドに渡される。この場合でも、DBLT_KEYSRCOVERRIDE または DDBLT_KEYDESTOVERRIDE フラグ、もしくはその両方を flags パラメータに設定しなくてはならない。このため、選択されたキーはサーフェス プロパティではなく DDBLTFX 型から取得される。


ステップ 4.2 : 転送元矩形と転送先矩形のセットアップ

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

ドライバのオーバーレイ制限を取得した後、それに応じて転送元および転送先矩形にその値を設定する。これにより、オーバーレイをうまく表示できるようになる。Mosquito サンプル アプリケーションの以下のサンプルは、転送元矩形の特性を設定することにより始まる。

// 転送元 RECT に初期値を設定する。
    rs.left=0; rs.top=0;
    rs.right = 320;
    rs.bottom = 240;

// 必要であれば、サイズ アライメント制限を適用する。
    if (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC && uSrcSizeAlign)
        rs.right -= rs.right % uSrcSizeAlign;

上記のコードでは、サーフェス全体の寸法を含むサーフェスに対する初期値を設定する。デバイス ドライバに転送元矩形のサイズ アライメントが必要な場合、それに従うように転送元矩形を調整する。サーフェスを完全に再作成しないと幅を拡張できないため、この例では転送元矩形の幅を元のサイズよりも狭くなるよう調整する。ただし、小さめの矩形でコードを始めるように調整して、ドライバの制限に適合するよう矩形を広げていくこともできる。

転送元矩形の寸法を設定しハードウェア制限に従うようにした後、転送先矩形の寸法の設定と調整が必要となる。矩形を初めに伸縮してからサイズ アライメント制限に適合するよう調整する必要がある場合もあるため、このプロセスでは多少余分なタスクが必要となる。次のコードでは、最小伸縮係数を確保するためのタスクを実行する。

// 転送元 RECT 値で始まる転送先 RECT をセットアップする。
// RECT 値。サーフェス寸法と転送元 RECT 寸法が異なる場合は、
// 転送元 RECT 寸法を使用する。
    rd.left=0; rd.top=0;
    rd.right  = (rs.right*uStretchFactor1000+999)/1000;
// (999 を足して、整数切り捨て問題を回避する）。

// (これは Ddraw では要求されないが、アスペクト比を
//  保持するために高さも伸縮する）。
    rd.bottom = rs.bottom*uStretchFactor1000/1000;

上記のコードでは、転送先矩形の左上角をスクリーンの左上角に設定した後、最小伸縮係数に見合う幅を設定する。伸縮係数による調整中に、幅と伸縮係数の積に 999 を足すことに注意する。これにより、整数切り捨てのために矩形が最小伸縮係数の要求する幅に達しない事態を回避できる。詳細情報は、「最小および最大伸縮係数」を参照すること。また、この例では、幅を伸縮した後に高さも伸縮している。高さの伸縮は必要とはされていないものの、ビットマップのアスペクト比を保持し外観の歪みを防止するために実行する。

転送先矩形を伸縮した後、その矩形をサイズ アライメント制限に従うように調整する。次に例を示す。

// 課されたアライメント制限に適合するよう、
// 転送先 RECT の幅を調整する。
    if (capsDrv.dwCaps & DDCAPS_ALIGNSIZEDEST && uDestSizeAlign)
        rd.right = (int)((rd.right+uDestSizeAlign-1)/uDestSizeAlign)*uDestSizeAlign;

この例では、能力フラグを調べて、ドライバが転送先サイズ アライメント制限を課しているかをみる。制限を課している場合、転送先矩形の幅はアライメント制限を満たすのに十分なピクセル分だけ増やす。矩形は幅を狭めるのではなく、広げることで調整することに注意する。これは、幅を狭めると転送先矩形が最小伸縮係数で要求された幅より狭くなる可能性があり、オーバーレイ サーフェスの表示が失敗するためである。

次項 :ステップ 4.3 : オーバーレイ サーフェスの表示


ステップ 4.2 : サーフェスの作成

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

DDSURFACEDESC2 構造体に情報が埋め込まれたら、その構造体と、DirectDrawCreateEx 関数で作成した DirectDraw オブジェクトへのポインタ g_pDD, を使用して、IDirectDraw7::CreateSurface メソッドを呼び出す。次に例を示す。

hRet = g_pDD->CreateSurface(&ddsd, &g_pDDSPrimary, NULL);
if (hRet != DD_OK)
{
// g_pDDSPrimary は新しいサーフェスへのポインタとなる。
}
else
{
//  サーフェスが作成されなかった。
return FALSE;
}

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

プライマリ サーフェスへのポインタが利用可能になると、バック バッファへのポインタを取得するために IDirectDrawSurface7::GetAttachedSurface メソッドを使用できる。次に例を示す。

ZeroMemory(&ddscaps, sizeof(ddscaps));
ddscaps.dwCaps = DDSCAPS_BACKBUFFER;
hRet = g_pDDSPrimary->GetAttachedSurface(&ddscaps, &g_pDDSBack);
if (hRet != DD_OK)
{
    // g_pDDSBack はバック バッファへのポインタとなる。
}
else
{
    return FALSE;
}

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

次項 :ステップ 5 : サーフェスへの書き込み


ステップ 4.1 : サーフェス要件の定義

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

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

// 1 つのバック バッファのあるプライマリ サーフェスを作成する。
ZeroMemory(&ddsd, sizeof(ddsd));
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE | DDSCAPS_FLIP |
                      DDSCAPS_COMPLEX;
ddsd.dwBackBufferCount = 1;

この例では、dwSize メンバが DDSURFACEDESC2 構造体のサイズに設定される。これは、DirectDraw メソッドの呼び出しで無効なメンバ エラーが返らないようにするためである (dwSize メンバは、DDSURFACEDESC2 構造体の将来の拡張機能に対して用意されたものである)。

dwFlags メンバは、DDSURFACEDESC2 構造体のどのメンバに有効な情報を埋め込むのかを決定する。DDEx1 の例では、dwFlags を設定することで、DDSCAPS 構造体 (DDSD_CAPS) を使ってバック バッファ (DDSD_BACKBUFFERCOUNT) を作成することを指定する。

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

最後に、この例ではバック バッファを 1 つ指定する。バック バッファは、背景とスプライトが実際に書き込まれる場所である。そして、バック バッファはプライマリ サーフェスにフリップされる。DDEx1 の例では、バック バッファの数は 1 に設定されている。ただし、ディスプレイ メモリの許容範囲内であれば、いくつでもバック バッファを作成できる。1 つ以上のバック バッファの作成に関する詳細情報は、「トリプル バッファリング」を参照すること。

サーフェス メモリは、ディスプレイ メモリまたはシステム メモリのどちらかである。アプリケーションがディスプレイ メモリを使い切る場合 (たとえば、1 MB の RAM しかないディスプレイ アダプタ上で複数のバック バッファを指定した場合)、DirectDraw はシステム メモリを使用する。また、DDSCAPS 構造体の dwCaps メンバを DDSCAPS_SYSTEMMEMORY または DDSCAPS_VIDEOMEMORY に設定することにより、システム メモリだけ、またはディスプレイ メモリだけを使用するように指定できる。(DDSCAPS_VIDEOMEMORY を指定したが、サーフェスを作成するための十分なメモリが得られない場合、IDirectDraw7::CreateSurface は DDERR_OUTOFVIDEOMEMORY エラーを返す)。

次項 :ステップ 4.2 : サーフェスの作成


ステップ 4.3 : オーバーレイ サーフェスの表示

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

転送元および転送先の矩形をセットアップした後に、初めてオーバーレイを表示することができる。正しく準備できていれば、簡単なことである。Mosquito サンプルでは次のコードを使い、最初にオーバーレイを表示する。

// UpdateOverlay に送るフラグを設定する。
    dwUpdateFlags = DDOVER_SHOW | DDOVER_DDFX;

// オーバーレイ ハードウェアが転送先カラー キーイングをサポートするか ?
// サポートする場合、イメージの周りの黒いバックグラウンドを隠蔽できる。
// おそらく、YUV フォーマットでは作用できない。
    if (capsDrv.dwCKeyCaps & DDCKEYCAPS_SRCOVERLAY)
        dwUpdateFlags |= DDOVER_KEYSRCOVERRIDE;

// 転送元カラー キーを指定するためのオーバーレイ FX 構造体を
// 作成する。DDOVER_SRCKEYOVERRIDE フラグが設定されていない場合、
// この情報は無視される。
    ZeroMemory(&ovfx, sizeof(ovfx));
    ovfx.dwSize = sizeof(ovfx);

// 黒をカラー キーとして指定する。
    ovfx.dckSrcColorkey.dwColorSpaceLowValue=0;
    ovfx.dckSrcColorkey.dwColorSpaceHighValue=0;

// UpdateOverlay() を呼び出し、スクリーンにオーバーレイを表示する。
// screen.
    ddrval = g_lpddsOverlay->UpdateOverlay(&rs, g_lpddsPrimary, &rd, dwUpdateFlags, &ovfx);
    if(FAILED(ddrval))
        return FALSE;

上記の例では、一時変数 dwUpdateFlags に DDOVER_SHOW および DDOVER_DDFX フラグを設定することで始まる。これらのフラグは、オーバーレイの初回の表示、およびそのために関連する DDOVERLAYFX 構造体のエフェクト情報を使用すべきハードウェアを示している。次に、既存の DDCAPS 構造体を調べて、オーバーレイ転送元カラー キーイングがサポートされているかを判断する。サポートされている場合、転送元カラー キーイングを利用するために dwUpdateFlags 変数に DDOVER_KEYSRCOVERRIDE を含め、それに応じてカラー キー値を設定する。

準備が完了すると、IDirectDrawSurface7::UpdateOverlay メソッドを呼び出してオーバーレイを表示する。この呼び出しでは、最初と 3 番目のパラメータが調整された転送元および転送先矩形のアドレスとなる。2 番目のパラメータは、表示されるオーバーレイのプライマリ サーフェスのアドレスとなる。4 番目のパラメータは、前に準備した dwUpdateFlags 変数に設定したフラグとなる。5 番目のパラメータは、4 番目のパラメータに設定したフラグに適合するように設定されたメンバのある DDOVERLAYFX 構造体のアドレスとなる。

ハードウェアが 1 つのオーバーレイ サーフェスだけをサポートし、そのサーフェスが使われている場合、UpdateOverlay メソッドは DDERR_OUTOFCAPS を返して失敗する。また、UpdateOverlay が失敗すると、ハードウェアが小さすぎる最小伸縮係数を不正確に報告した可能性を考慮して、転送先矩形の幅を広げようとするかもしれない。しかし、これはまれにしか起こらず、UpdateOverlay が成功しない場合、Mosquito は単に失敗する。

次項 :ステップ 5 : オーバーレイ表示位置の更新


ステップ 4.1 : 最小表示要件の決定

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「DirectDraw Visual Basic チュートリアル」を参照すること。

[C++]

大部分のディスプレイ ハードウェアは、オーバーレイ サーフェスの表示に制限を課す。オーバーレイ サーフェスをうまく表示するには、注意深くこれらの制限を見ていかなくてはならない。これらの制限についての情報を取得するには、IDirectDraw7::GetCaps メソッドを呼び出す。このメソッドが埋め込む DDCAPS 構造体には、オーバーレイ能力やその使用法の制限についての情報が含まれている。ハードウェア制限はさまざまなので、常に dwFlags メンバのフラグを調べ適用する制限を決定する。

Mosquito サンプルでは、ハードウェア能力の取得から開始し、次に最小伸縮係数に基づいてアクションを行う。次にこのコードを示す

    // ドライバ能力を取得する。
    ddrval = g_lpdd->GetCaps(&capsDrv, NULL);
    if (FAILED(ddrval))
        return FALSE;

    // 最小伸縮を調べ、それに対応して
    // ローカル変数を設定する。
    if(capsDrv.dwCaps & DDCAPS_OVERLAYSTRETCH)
        uStretchFactor1000 = (capsDrv.dwMinOverlayStretch>1000) ? capsDrv.dwMinOverlayStretch : 1000;
    else
        uStretchFactor1000 = 1000;

上記のコードでは、ハードウェア能力のみを取得するために GetCaps を呼び出す。この呼び出しで、最初のパラメータは、デバイス ドライバ能力の情報を埋め込む DDCAPS 構造体へのポインタとなる。2 番目のパラメータは、エミュレーション情報を取得しないことを示すために NULL とする。

この例では、後で使用するため、一時変数に最小伸縮係数を保持する (伸縮係数は 1000 を掛けて報告されるので、1300 は実際には 1.3 を意味することに注意すること)。ドライバが 1000 以上の値を報告する場合、ドライバは、報告された比率だけすべての転送先矩形が x 軸に沿って伸縮されなければならない。たとえば、ドライバが伸縮係数 1.3 を報告し、転送元矩形の幅が 320 ピクセルである場合、転送先矩形の幅は少なくとも 416 ピクセルなくてはならない。ドライバが 1000 以下の値を報告する場合、ドライバは転送元矩形より小さなオーバーレイを表示できるが、必要に応じてオーバーレイを伸縮できる。

次に、ドライバのサイズ アライメント制限を記述する値を調べる。次に例を示す。

// アライメント制限を取得し、それに対応して
// ローカル変数を設定する。
    uSrcSizeAlign = (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC)?capsDrv.dwAlignSizeSrc:0;
    uDestSizeAlign= (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC)?capsDrv.dwAlignSizeDest:0;

このサンプルでは、より多くの一時変数を使用して、dwAlignSizeSrc および dwAlignSizeDest メンバから報告されるサイズ アライメント制限を保持する。これらの値は、ピクセル幅アライメント制限についての情報を提供し、後でこれらの制限を反映させるために、転送元および転送先矩形の寸法を設定する際に必要となる。転送元および転送先矩形には、これらのメンバ値の倍数となるピクセル幅がなくてはならない。

最後に、転送先矩形の境界アライメントを記述する値を調べる。

// "転送先位置アライメント" グローバルを設定して
// オーバーレイ サーフェスを動かすたびに GetCaps() を呼び出す
// 必要がないようにする。
    if (capsDrv.dwCaps & DDCAPS_ALIGNBOUNDARYDEST)
        g_dwOverlayXPositionAlignment = capsDrv.dwAlignBoundaryDest;
    else
        g_dwOverlayXPositionAlignment = 0;

上記のコードでは、dwAlignBoundaryDest メンバから取得した転送先矩形の境界アライメントに対する値を保持するために、グローバル変数を使用している。この値は、プログラムが後でオーバーレイを再配置するときに使用される (詳細情報は、「ステップ 5 : オーバーレイ表示位置の更新」を参照すること)。転送先矩形の左上角の x 座標は、ピクセル単位でこの値と連続するように設定しなくてはならない。つまり、指定された値が 4 であれば､転送先矩形の左上角の x 座標は、ピクセルで 0、4、8、12 などに指定することしかできない。Mosquito アプリケーションでは、最初にオーバーレイを 0,0 に表示する。したがって、アライメント準拠であると仮定し、オーバーレイが最初に表示されるまで制約情報を取得する必要はない。実装方法はさまざまなので、おそらく、この情報を調べて、オーバーレイを表示する前に転送先矩形を調整する必要がある。

次項 :ステップ 4.2 : 転送元矩形と転送先矩形のセットアップ


GUID_Unload

[C++]
トラック タイプ | バンド。
目的 | トラックのバンドの音色データをアンロードする。「GUID_Download」を参照すること。
データ タイプ (*pParam) | IDirectMusicPerformance ポインタ。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_EnableTimeSig

[C++]
トラック タイプ | 拍子記号、スタイル、およびモチーフ。
目的 | 拍子記号メッセージを無効にする。「メッセージの無効化と有効化」を参照すること。
データ タイプ (*pParam) | なし。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_SeedVariations

[C++]
トラック タイプ | スタイルおよびモチーフ。
目的 | ゼロ以外の数字は、バリエーション選択に使用するランダム値を生成する際のシードとなる。値が 0 の場合はデフォルトの状態に戻り、システム クロックからシードを取得する。
データ タイプ (*pParam) | Long.
mtTime | 未使用。

注意

このパラメータにゼロ以外の値を設定すると、毎回同じ順序でランダムな数字が生成されるので、テストの際に役に立つ。パラメータは、トラックを演奏する前に一度だけ設定する。スタイルとコマンド トラックは、セグメントが演奏されるたびに、セグメントの同じ場所で同じパターンが選択されるように設計しなければならない。各ループは、前回とは異なるバリエーションで演奏されるが、セグメント全体が最初から演奏されるたびに、各ループはセグメントが最初に演奏されたときと同じように聞こえる。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_DisableTempo

[C++]
トラック タイプ | テンポ。
目的 | テンポ メッセージを無効にする。「メッセージの無効化と有効化」を参照すること。
データ タイプ (*pParam) | なし。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


手動によるバンドのダウンロード

[C++]

次のいずれかの方法を使うと、バンドを手動でダウンロードすることができる。

  • ロードされたオブジェクトから IDirectMusicBand インターフェイスを取得し、IDirectMusicBand::Download メソッドを呼び出す (次の例を参照すること)。バンドを使用するセグメントが解放された後にバンドをアンロードする場合は、この方法が適切である。
  • GUID_Download パラメータを使って IDirectMusicSegment::SetParam メソッドを呼び出し、セグメントの最初のバンド トラックにバンドをダウンロードする。IDirectMusicPerformance::SetParam を使って、プライマリ セグメントでこのパラメータを設定したり、IDirectMusicTrack::SetParam を使って、直接バンド トラックに設定することもできる。「トラック パラメータの設定と取り出し」を参照すること。

同じ音色を繰り返しダウンロードしても問題は生じない。1 つのバンド内にある音色が何度も現れる場合や、複数のバンドを同時に開いてダウンロードするときに同じ音色がこれらのバンドで使用されている場合でも、その音色のデータは 1 回だけシンセサイザにダウンロードされる。

次の関数は、ディスクからバンドをロードして、そのバンドをダウンロードする。

HRESULT myDownloadBand(
    IDirectMusicLoader *pILoader,      // ローダー インターフェイス。
    IDirectMusicBand **ppBand,         // ポインタを取り出す。
    IDirectMusicPerformance *pPerf,    // バンドを使うパフォーマンス
    WCHAR *pwszFile)                   // ロードするファイル

{
    HRESULT hr;
    DMUS_OBJECTDESC Desc;              // ディスクリプタ

    // 最初にファイル名とバンド オブジェクトの GUID を
    // 指定して、Desc を初期化する。

    wcscpy(Desc.wszFileName,pwszFile);
    Desc.dwSize = sizeof(Desc);
    Desc.guidClass = CLSID_DirectMusicBand;
    Desc.dwValidData = DMUS_OBJ_CLASS |
            DMUS_OBJ_FILENAME | DMUS_OBJ_FULLPATH;

    hr = pILoader->GetObject(&Desc, IID_IDirectMusicBand,
            (void **) ppBand);
    if (SUCCEEDED(hr))
    {

        // パフォーマンスを通してバンドをダウンロードする。
        hr = (*ppBand)->Download(pPerf);

    }
    return hr;
}
[Visual Basic]

ファイル、リソース、または DirectMusicStyle オブジェクトから DirectMusicBand オブジェクトを取得した後、DirectMusicBand.Download メソッドを使って、バンドを手動でダウンロードすることができる。


コード トラック リスト

コード トラック リストには、トラック形式のコード データが含まれる。構造は次のとおりである。

<cord-list> -> LIST( 'cord'
<crdh-ck>       // ヘッダー
<crdb-ck>       // コード本体のチャンク
    )

サブチャンクの構造は次のとおりである。

<crdh-ck> -> crdh ( <DWORD> )

ヘッダーは DWORD 値で、上位 8 ビットにコード ルート、下位 24 ビットにスケールが含まれる。これらのビットの説明については、DMUS_IO_SUBCHORD を参照すること。

コード トラック リストのデータ本体は、コード変更およびコンポーネント サブコードに関する情報で構成される。

<crdb-ck> -> crdb(
<DWORD>           // DMUS_IO_CHORD のサイズ
<DMUS_IO_CHORD>
<DWORD>           // サブコードの数
<DWORD>           // DMUS_IO_SUBCHORD のサイズ
<DMUS_IO_SUBCHORD>...
    )


システム エクスクルーシブ トラック チャンク

システム エクスクルーシブ トラック チャンクには、トラック形式のデータが含まれる。次の表記法に示すように、システム エクスクルーシブ項目の配列である。

<syex-ck> -> syex(
<DMUS_IO_SYSEX_ITEM>
<BYTE>...// データ
    )...


シーケンス トラック リスト

シーケンス トラック リストには、トラック形式のデータが含まれる。リストの構造は次のとおりである。

<seqt-list> -> LIST('seqt'
<evtl-ck>
<curl-ckt>
    )

リストには、シーケンス項目と曲線項目の、2 つのチャンクが含まれる。

<evtl-ck> -> evtl(
<DWORD>     // DMUS_IO_SEQ_ITEM のサイズ
<DMUS_IO_SEQ_ITEM>...
    )

<curl-ck> -> curl(
<DWORD>     // DMUS_IO_CURVE_ITEM のサイズ
<DMUS_IO_CURVE_ITEM>...
    )


GUID_IDirectMusicStyle

[C++]
トラック タイプ | スタイル。
目的 | スタイルを設定または取得する。
データ タイプ (*pParam) | IDirectMusicStyle ポインタ (SetParam)、またはこのポインタを受け取る変数のアドレス (GetParam)。
mtTime | トラックにスタイルを追加するタイム。または、トラックからスタイルを取り出すタイム、またはその直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_MuteParam

[C++]
トラック タイプ | ミュート。
目的 | チャンネル (マッピング情報) を設定または取得する。
データ タイプ (*pParam) | DMUS_MUTE_PARAM。この構造体を GetParam に渡す前に、dwPChannel メンバを初期化しなければならない。
mtTime | トラックにミュート イベントを追加するタイム。または、トラックからミュート イベントを取り出すタイム、またはその直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


スタイル トラック リスト

スタイル トラック リストには、トラック形式のデータが含まれる。リストの構造は次のとおりである。

<sttr-list> -> LIST('sttr'(
<strf-list>...
    )

データは、タイム スタンプとスタイルへの参照を含む、1 つまたは複数のリストで構成される。

<strf-list> -> LIST('strf'(
<stmp-ck>
<DMRF-list>
    )

<DMRF-list> の詳細については、「共通のチャンク」を参照すること。


ミュート トラック チャンク

ミュート トラック チャンクには、トラック形式のデータが含まれる。チャンクの構造は次のとおりである。

<mute-ck> -> mute(
<DWORD>     //DMUS_IO_MUTE のサイズ
<DMUS_IO_MUTE>...
    )


コマンド トラック チャンク

コマンド トラック チャンクには、トラック形式のデータが含まれる。チャンクの構造は次のとおりである。

<cmnd-ck> -> cmnd(
    <DWORD>    //Size of DMUS_IO_COMMAND
    <DMUS_IO_COMMAND>...
    )


GUID_IDirectMusicBand

[C++]
トラック タイプ | バンド。
目的 | バンドを設定する。
データ タイプ (*pParam) | IDirectMusicBand。
mtTime | トラックにバンドを追加するタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


バンド トラック形式

バンド トラック形式は最上位の形式にも使用できるが、トラック形式のデータ部分としても使用される。バンド トラック形式の構造は、次のとおりである。

RIFF( 'DMBT'
[<bdth-ck>]     // バンド トラック ヘッダー
[<guid-ck>]     // バンド トラックの GUID
[<vers-ck>]     // オプションのバージョン情報
[<UNFO-list>]   // 名前、作者、著作権情報、コメント
<lbdl-list>     // バンド リストのリスト
    )

サブチャンクは次のとおりである。

<bnth-ck> -> bdth( <DMUS_IO_BAND_TRACK_HEADER> )

このオプションのチャンクには、バンド トラックのヘッダー情報が含まれる。構造体のデータは、自動ダウンロードのフラグのみである。

次の 3 つの要素はオプションである。「共通のチャンク」を参照すること。

最後のチャンクには、1 つまたは複数のバンドが含まれる。

<lbdl-list> -> LIST( 'lbdl'
<lbnd-list>...
    )

各バンドは、次のリストにカプセル化される。

<lbnd-list> -> LIST( 'lbnd'
<bdih-ck>
<DMBD-form>
    )

バンド リストは次のヘッダーで始まる。

<bdih-ck> -> ( <DMUS_IO_BAND_ITEM_HEADER> )

ヘッダーの後にバンド形式が続き、バンドの音色に関する情報が含まれる。


バンドの自動ダウンロード

[C++]

バンドの自動ダウンロードは、次のいずれかの方法で有効にできる。

  • GUID_PerfAutoDownload パラメータを使って IDirectMusicPerformance::SetParam メソッドを呼び出す。「グローバル パラメータの設定と取り出し」を参照すること。
  • GUID_Enable_Auto_Download パラメータを使って IDirectMusicSegment::SetParam または IDirectMusicTrack::SetParam メソッドを呼び出す。「トラック パラメータの設定と取り出し」を参照すること。

次のコード例では、パフォーマンス pPerf のグローバル パラメータを、バンドの自動ダウンロードが有効になるように設定している。

BOOL fAuto = TRUE;
pPerf->SetGlobalParam(GUID_PerfAutoDownload, &fAuto, sizeof(BOOL));
[Visual Basic]

DirectMusicPerformance.SetMasterAutoDownload メソッドを使って、パフォーマンス全体でバンドの自動ダウンロードを有効にしたり、DirectMusicSegment.SetAutoDownloadEnable メソッドを使って、セグメントごとに自動ダウンロードを有効にすることができる。


GUID_Disable_Auto_Download

[C++]
トラック タイプ | バンド。
目的 | 音色の自動ダウンロードを無効にする。「バンドの使い方」を参照すること。
データ タイプ (*pParam) | なし。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_EnableTempo

[C++]
トラック タイプ | テンポ。
目的 | テンポ メッセージを有効にする。「メッセージの無効化と有効化」を参照すること。
データ タイプ (*pParam) | なし。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_ConnectToDLSCollection

[C++]
トラック タイプ | バンド。
目的 | バンドを DLS コレクションに接続する。「カスタム音色による MIDI ファイルの演奏」を参照すること。
データ タイプ (*pParam) | IDirectMusicCollection ポインタ。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_TempoParam

[C++]
トラック タイプ | テンポ。
目的 | テンポを設定または取得する。
データ タイプ (*pParam) | DMUS_TEMPO_PARAM。SetParam の場合、構造体の mtTime メンバは無視される。GetParam の場合、mtTime メンバは、要求されたタイムからのテンポ チェンジのオフセットを受け取る。常に 0 以下である。
mtTime | テンポを設定するタイム。または、テンポ チェンジを取り出すタイム、またはその直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_DisableTimeSig

[C++]
トラック タイプ | 拍子記号、スタイル、およびモチーフ。
目的 | 拍子記号メッセージを無効にする。「メッセージの無効化と有効化」を参照すること。
データ タイプ (*pParam) | なし。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_CommandParam2

[C++]
トラック タイプ | コマンド。
目的 | グルーブまたは装飾コマンドを設定または取得する。
データ タイプ (*pParam) | DMUS_COMMAND_PARAM2。この構造体の mtTime メンバは、コマンドの実際のタイムを与える。
mtTime | トラックにコマンドを追加するタイム。または、トラックからコマンドを取り出すタイム、またはその直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_IDirectMusicChordMap

[C++]
トラック タイプ | コード マップ。
目的 | コード マップを設定または取得する。
データ タイプ (*pParam) | IDirectMusicChordMap ポインタ (SetParam)、またはこのポインタを受け取る変数のアドレス (GetParam)。
mtTime | トラックにコード マップを追加するタイム。または、トラックからコード マップを取り出すタイム、またはその直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_Download

[C++]
トラック タイプ | バンド。
目的 | トラックのバンドに音色データをダウンロードする。「カスタム音色による MIDI ファイルの演奏」を参照すること。「GUID_Unload」も参照すること。
データ タイプ (*pParam) | IDirectMusicPerformance ポインタ。
mtTime | 未使用。

注意

IDirectMusicSegment::SetParam を使ってこのパラメータを設定すると、最初のバンド トラックの音色のみがダウンロードされる。ほかのトラックの音色をダウンロードするには、各バンド トラックで IDirectMusicSegment::GetTrack を使い、各トラックで IDirectMusicTrack::SetParam を呼び出す。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_Enable_Auto_Download

[C++]
トラック タイプ | バンド。
目的 | 音色の自動ダウンロードを有効にする。「バンドの使い方」を参照すること。
データ タイプ (*pParam) | なし。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_TimeSignature

[C++]
トラック タイプ | 拍子記号およびスタイル。
目的 | 拍子記号を取得する。
データ タイプ (*pParam) | DMUS_TIMESIGNATURE。mtTime メンバは、要求したタイムからの拍子記号の変更のオフセットを受け取る。この値は、常に 0 以下である。
mtTime | 拍子記号を設定するタイム。または、拍子記号の変更を取り出すタイム、またはその直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


バンドのアンロード

[C++]

バンドはメモリを消費するため、使用しなくなったバンドはアンロードするべきである。自動ダウンロードを有効にしている場合は、セグメントが終了したときに、セグメントに関連付けられているバンドが自動的にアンロードされる。そうでない場合は、次のいずれかの方法を使って、手動でバンドをアンロードすることができる。

  • IDirectMusicBand::Unload メソッドを呼び出す。
  • GUID_Unload パラメータを使って IDirectMusicSegment::SetParam メソッドを呼び出し、セグメントのバンド トラックにあるバンドをアンロードする。IDirectMusicPerformance::SetParam を使って、プライマリ セグメントでこのパラメータを設定したり、IDirectMusicTrack::SetParam を使って、直接バンド トラックに設定することもできる。「トラック パラメータの設定と取り出し」を参照すること。例として、「チュートリアル 1」の「ステップ 6 : DirectMusic のシャットダウン」を参照すること。

IDirectMusicPerformance::CloseDown メソッドでも、ダウンロードされた残りの音色がアンロードされる。

[Visual Basic]

バンドはメモリを消費するため、使用しなくなったバンドはアンロードするべきである。自動ダウンロードを有効にしている場合は、セグメントが終了したときに、セグメントに関連付けられているバンドが自動的にアンロードされる。そうでない場合は、DirectMusicBand.Unload メソッドを使って、手動でバンドをアンロードすることができる。

DirectMusicPerformance.CloseDown メソッドでも、ダウンロードされた残りの音色がアンロードされる。


GUID_Clear_All_Bands

[C++]
トラック タイプ | バンド。
目的 | トラックからすべてのバンドを消去する。
データ タイプ (*pParam) | なし。
mtTime | 未使用。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_ChordParam

[C++]
トラック タイプ | コード。
目的 | コード変更を設定または取得する。
データ タイプ (*pParam) | DMUS_CHORD_PARAM。
mtTime | トラックにコードを追加するタイム。または、トラックからコードを取り出すタイム、またはその直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


GUID_StandardMIDIFile

[C++]
トラック タイプ | バンド。
目的 | スタンダード MIDI ファイル (DirectMusic 用に特別にオーサリングされていない MIDI ファイル) が、正しく演奏されるように保証する。
データ タイプ (*pParam) | なし。
mtTime | 未使用。

注 : このパラメータは、音色がダウンロードされる前に、MIDI ファイルに基づくセグメントで設定されなければならない。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


拍子記号トラック チャンク

拍子記号トラック チャンクには、トラック形式のデータが含まれる。チャンクの構造は次のとおりである。

<tims-ck> -> tims(
<DWORD>    // DMUS_IO_TIMESIGNATURE_ITEM のサイズ
<DMUS_IO_TIMESIGNATURE_ITEM>...
    )


コード マップ トラック リスト

コード マップ トラック リストには、トラック形式のデータが含まれる。リストの構造は次のとおりである。

<pftr-list> -> LIST('pftr'
<pfrf-list>...
    )

データは、タイム スタンプとコード マップへの参照を含む、1 つまたは複数のリストで構成される。

<pfrf-list> -> LIST('pfrf'
<stmp-ck>
<DMRF-list>
    )

タイム スタンプ チャンクの表記法は、次のとおりである。

<stmp-ck> -> stmp( <DWORD> )

<DMRF-list> の詳細については、「共通のチャンク」を参照すること。


GUID_RhythmParam

[C++]
トラック タイプ | コード。
目的 | トラックの小節に格納されている、コードのシーケンスのリズム パターンを取得する。
データ タイプ (*pParam) | DMUS_RHYTHM_PARAM。この構造体を GetParam に渡す前に、TimeSig メンバを初期化しなければならない。
mtTime | トラックから取り出すリズム パターンが含まれている小節の開始、または開始直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


サインポスト トラック チャンク

サインポスト トラック チャンクには、トラック形式のデータが含まれる。チャンクの構造は次のとおりである。

<sgnp-list> -> sgnp(
<DWORD>    // DMUS_IO_SIGNPOST のサイズ
<DMUS_IO_SIGNPOST>...
    )


テンポ トラック チャンク

テンポ トラック チャンクには、トラック形式のデータが含まれる。チャンクの構造は次のとおりである。

<tetr-ck> -> tetr(
<DWORD>    // DMUS_IO_TEMPO_ITEM のサイズ
<DMUS_IO_TEMPO_ITEM>...
    )


GUID_CommandParam

[C++]
トラック タイプ | コマンド。
目的 | グルーブまたは装飾コマンドを設定または取得する。
データ タイプ (*pParam) | DMUS_COMMAND_PARAM2。
mtTime | トラックにコマンドを追加するタイム。または、トラックからコマンドを取り出すタイム、またはその直後のタイム。トラック時間で指定する。

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。


構造体

ここでは、DirectMusic で使われる次の実行時構造体に関するリファレンス情報を提供する。

  • DMUS_BUFFERDESC
  • DMUS_CHORD_PARAM
  • DMUS_CHORD_PARAM
  • DMUS_CLOCKINFO
  • DMUS_COMMAND_PARAM
  • DMUS_COMMAND_PARAM2
  • DMUS_EVENTHEADER
  • DMUS_MUTE_PARAM
  • DMUS_NOTERANGE
  • DMUS_OBJECTDESC
  • DMUS_PORTCAPS
  • DMUS_PORTPARAMS
  • DMUS_RHYTHM_PARAM
  • DMUS_SUBCHORD
  • DMUS_SYNTHSTATS
  • DMUS_TEMPO_PARAM
  • DMUS_TIMESIGNATURE
  • DMUS_VERSION
  • DMUS_WAVES_REVERB_PARAMS
  • KSPROPERTY

構造体の特別なカテゴリは、以下のトピックに記載する。

  • メッセージ
  • ファイル構造体
  • DLS 構造体

注 : すべての DirectX 構造体のメモリは、使用する前に 0 に初期化しなければならない。また、dwSize メンバを含むすべての構造体は、使用する前に、メンバを構造体のサイズにバイト単位で設定しなければならない。次に示す DirectDraw のサンプル コードでは、一般的な構造体 DDCAPS に対してこれらのタスクを実行する。

DDCAPS ddcaps; // まだ使用できない。

ZeroMemory(&ddcaps, sizeof(ddcaps));
ddcaps.dwSize = sizeof(ddcaps);

// これで構造体を使用できる。
.
.


Platform SDK: DirectX

$ IDirectMusicBuffer

IDirectMusicBuffer は、ポートによってシーケンス化される、タイム スタンプの割り当てられたデータ (通常は MIDI メッセージ形式) を含むバッファを表す。セグメントとは異なり、バッファはわずかな量のデータ ( 通常は 200ms 未満 ) を保持し、アプリケーションはイベントの微小性を制御する際にこのデータを利用する。

アプリケーションが独自のシーケンス化を行わない限り、このインターフェイスのこのメソッドを使う必要はない。

IDirectMusicPort::PlayBuffer か IDirectMusicPort::Read どちらかのメソッドを呼び出してバッファをポートに渡すまでは、バッファ オブジェクトはポート オブジェクトから完全に独立している。その後アプリケーションはバッファを解放して、再利用を可能にする。

IDirectMusicBuffer インターフェイスのメソッドは、以下のグループにまとめることができる。

データ | Flush
 | GetNextEvent
 | GetRawBufferPtr
 | PackStructured
 | PackUnstructured
 | ResetReadPtr
パラメータ | GetBufferFormat
 | GetMaxBytes
 | GetUsedBytes
 | SetUsedBytes
時間 | GetStartTime
 | SetStartTime
 | TotalTime

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICBUFFER 型は、IDirectMusicBuffer インターフェイスへのポインタとして定義されている。

typedef IDirectMusicBuffer *LPDIRECTMUSICBUFFER;

動作環境

Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusicc.h で宣言。


メッセージ

DirectMusic のメッセージ構造体は、いずれも DMUS_PMSG 構造体に基づいている。C は継承をサポートしていないので、この構造体のメンバは DMUS_PMSG_PART マクロにより各派生構造体に含まれる。

メッセージの概要については、「DirectMusic メッセージ」を参照すること。

ここでは、メッセージ情報の保持に使われる次の構造体に関する情報を提供する。

  • DMUS_PMSG
  • DMUS_CHANNEL_PRIORITY_PMSG
  • DMUS_CURVE_PMSG
  • DMUS_MIDI_PMSG
  • DMUS_NOTE_PMSG
  • DMUS_NOTIFICATION_PMSG
  • DMUS_PATCH_PMSG
  • DMUS_SYSEX_PMSG
  • DMUS_TEMPO_PMSG
  • DMUS_TIMESIG_PMSG
  • DMUS_TRANSPOSE_PMSG

参照

IDirectMusicPerformance::AllocPMsg、IDirectMusicPerformance::SendPMsg、IDirectMusicPerformance::FreePMsg、IDirectMusicTool::ProcessPMsg


スポット ライト プロパティ

[C++]

C++ の D3DLIGHT7 構造体には、スポット ライトでのみ使用する 3 つのメンバが含まれている。これらのメンバ (dvFalloff、dvTheta、dvPhi) は、スポット ライト オブジェクトの内部コーンと外部コーンの大きさを制御し、両方のコーンの間でライトがどのように減少するかを制御する。これらの特性の一般的な説明については、「スポット ライト」を参照すること。

dvTheta 値はスポット ライトの内部コーンのラジアン角度を表し、dvPhi 値は外部コーンのラジアン角度を表す。dvFalloff 値は、内部コーンの外側エッジと外部コーンの内側エッジとの間で、ライトの強度がどのように減少するかを制御する。ほとんどのアプリケーションでは、dvFalloff を 1.0 に設定して 2 つのコーン間でフォールオフが一様に生じるようにするが、必要に応じてこれ以外の値を設定することもできる。フォールオフの計算において Direct3D が使用する数学的モデルの詳細については、「スポット ライト フォールオフ モデル」を参照すること。

次の図は、メンバの値の間にある関係と、これらの値がスポット ライトの内部コーンと外部コーンに与える影響を示す。

[Visual Basic]

Visual Basic の D3DLIGHT7 型には、スポット ライトでのみ使用する 3 つのメンバが含まれている。これらのメンバ (falloff、theta、phi) は、スポット ライト オブジェクトの内部コーンと外部コーンの大きさを制御し、両方のコーンの間でライトがどのように減少するかを制御する。これらの特性の一般的な説明については、「スポット ライト」を参照すること。

theta 値はスポット ライトの内部コーンのラジアン角度を表し、phi 値は外部コーンのラジアン角度を表す。falloff 値は、内部コーンの外側エッジと外部コーンの内側エッジとの間で、ライトの強度がどのように減少するかを制御する。ほとんどのアプリケーションでは、falloff を 1.0 に設定して 2 つのコーン間でフォールオフが一様に生じるようにするが、必要に応じてこれ以外の値を設定することもできる。フォールオフの計算において Direct3D が使用する数学的モデルの詳細については、「スポット ライト フォールオフ モデル」を参照すること。

次の図は、メンバの値の間にある関係と、これらの値がスポット ライトの内部コーンと外部コーンに与える影響を示す。


キューブ環境マップとは

キューブ環境マップ ("キューブ マップ" と呼ばれることもある) とは、オブジェクトの周囲の景色をオブジェクトが立方体の中心にあるかのように表現した画像データを含むテクスチャである。キューブ環境マップの各面は、水平方向と垂直方向の 90°の視界を対象とし、1 つのキューブ マップには 6 つの面がある。各面の方向は、次の図に示すとおりである。

立方体の各面は、ワールド空間の x/y、y/z、または x/z 平面に垂直に位置座標する。次の図は、各平面と面の対応を示す。

キューブ環境マップは、一連のアタッチされたテクスチャ サーフェスとして実装され、1 回の呼び出しで作成される。これらのテクスチャ サーフェスへのアクセスは、その他のアタッチされているサーフェス セットと同様に行うことができる。アプリケーションでは、キューブ環境マップに静的な画像を使用したり、キューブ マップの面にレンダリングを行うことで動的な環境マッピングを実行することができる (この場合、キューブ マップ サーフェスは有効なレンダリング ターゲット サーフェスでなければならず、DDSCAPS_3DDEVICE で作成されている必要がある)。

キューブ マップの各面には、周囲のシーンが緻密にレンダリングされる必要はない。ほとんどの場合、環境マップは湾曲サーフェスに適用される。大部分のアプリケーションで使用する湾曲の度合いが与えられたとすると、結果としてひずんだ画像が生成されるため、環境マップの緻密さはメモリの点からもレンダリングのオーバーヘッドの点からも無駄になる。


ビューポート クリッピング ボリュームの設定

レンダリング デバイスに対してビューポート パラメータを設定するには、単にビューポートのクリッピング ボリュームを設定するのみである。このためには、クリッピング ボリュームとレンダリング ターゲット サーフェス用のクリッピング値を初期化および設定する。ビューポートは、一般には、レンダリング ターゲット サーフェスの全領域にレンダリングするように設定されるが、必ずしもそうする必要はない。

[C++]

C++ でこれを実現するには、D3DVIEWPORT7 構造体のメンバを次のように設定する。

    memset(&viewData, 0, sizeof(D3DVIEWPORT7));
    viewData.dwX = 0;
    viewData.dwY = 0;
    viewData.dwWidth  = width;
    viewData.dwHeight = height;
    viewData.dvMinZ = 0.0f;
    viewData.dvMaxZ = 1.0f;

D3DVIEWPORT7 構造体に値を設定した後、IDirect3DViewport7::SetViewport メソッドを呼び出してデバイスにビューポート パラメータを適用する。次の例はこの呼び出しを示す。

    HRESULT hr;

    hr = lpD3DDevice->SetViewport(&viewData);
    if(FAILED(hr))
return hr;

この呼び出しが成功すると、ビューポート パラメータが設定され、次回レンダリング メソッドを呼び出したときにこのビューポート パラメータが有効になる。ビューポート パラメータ値を変更する必要がある場合は、D3DVIEWPORT7 構造体の値を更新して、再度 SetViewport 呼び出すだけでよい。

注 : D3DVIEWPORT7 構造体の dvMinZ および dvMaxZ メンバの解釈方法は、旧バージョンの DirectX の場合とはまったく異なる。dvMinZ および dvMaxZ メンバは、現在はシーンがレンダリングされる深度範囲を示し、クリッピングには使用されない。ほとんどのアプリケーションでは、このメンバを 0.0 と 1.0 に設定して、深度バッファ内の深度値の全範囲にレンダリングしている。場合によっては、別の深度範囲を使用して特殊効果を得ることもできる。たとえば、ゲームのヘッドアップ ディスプレイをレンダリングする場合、両方の値を 0.0 に設定してフォアグラウンドのシーン内のオブジェクトを強制的にレンダリングしたり、両方の値を 1.0 に設定して常にバックグラウンドに存在する必要があるオブジェクトをレンダリングすることができる。

[Visual Basic]

次の Visual Basic コードでは、この内容を実現するために D3DVIEWPORT7 型の設定を行う。

Dim viewData As D3DVIEWPORT7

With viewData
.lX = 0:.lY = 0
.lWidth = Width:.lHeight = Height
.minz = 0#:.maxz = 1#
End With

D3DVIEWPORT7 型に値を設定した後、Direct3DDevice7.SetViewport メソッドを呼び出してデバイスにビューポート パラメータを適用する。

' dev 変数には Direct3DDevice7 オブジェクトへの有効な参照が格納される。
Call dev.SetViewport(viewData)

この呼び出しの後、ビューポート パラメータが設定され、次回レンダリング メソッドを呼び出したときにこのビューポート パラメータが有効になる。ビューポート パラメータ値を変更する必要がある場合は、D3DVIEWPORT7 型の値を更新して、再度 SetViewport 呼び出すだけでよい。


テクスチャ座標の自動生成について

Platform SDK: DirectX

テクスチャ座標の自動生成について

システムでは、トランスフォーム後のカメラ空間位置座標または頂点の法線をテクスチャ座標として使用できる。また、キューブ環境マップを実行するための 3 要素ベクトルを計算することも可能である。頂点で明示的に指定するテクスチャ座標と同様、自動生成されたテクスチャ座標は、テクスチャ座標トランスフォーム用の入力として使用される。

テクスチャ座標の自動生成では、頂点フォーマットでの明示的なテクスチャ座標の必要性を排除することで、ジオメトリ データで必要となる帯域幅を大幅に削減できる。多くの場合、システムで生成されたテクスチャ座標は、特殊効果を施すトランスフォームと共に使用できる。もちろん、この機能は特殊な用途に使用されるものであり、明示的なテクスチャ座標を使用するケースも多くある。


クリップ面の有効/無効

[C++]

クリップ面は、IDirect3DDevice7::SetClipPlane メソッドを呼び出しても自動的には有効にならないので注意する必要がある。デバイスに現在設定されているクリップ面を有効または無効にするには、D3DRENDERSTATE_CLIPPLANEENABLE レンダリング ステートを使用する。このレンダリング ステートは DWORD 値を受け取る。最下位ビットから始まる各ビットがクリップ面に対応する。1 ビットが設定されるとクリップ面が有効になり、このビットがクリアされるとそのクリップ面が無効になる。値については、ビット 0 はインデックス 0 のクリップ面を有効および無効にし、ビット 1 はインデックス 1 のクリップ面を制御する、という順でビット 31 まである (Direct3D では一度に最大 32 個の平面でクリッピングが可能であるが、デバイスでそれが可能かどうかはまちまちである)。このようなセマンティクスにより、アプリケーションでは 1 回の呼び出しであらゆるクリップ面を有効または無効にできる。

d3dtypes.h ヘッダー ファイルには D3DCLIPPLANEn マクロが定義されている。このマクロは、D3DRENDERSTATE_CLIPPLANEENABLE レンダリング ステートの値として組み合わせて渡すことができる値のパターンを作成する。次の C++ コードでは、このマクロを使用する。

// この例では、pd3dDevice 変数は IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。

// クリップ面の 0 および 1 を有効にする。
// その他すべてのユーザー定義クリップ面は無効であるとする。
pd3dDevice->SetRenderState( D3DRENDERSTATE_CLIPPLANEENABLE,
D3DCLIPPLANE0 | D3DCLIPPLANE1);
[Visual Basic]

クリップ面は、Direct3DDevice7.SetClipPlane メソッドを呼び出しても自動的には有効にならないので注意する必要がある。デバイスに現在設定されているクリップ面を有効または無効にするには、D3DRENDERSTATE_CLIPPLANEENABLE レンダリング ステートを使用する。このレンダリング ステートの値は、CONST_D3DCLIPPLANEFLAGS 列挙からの値である。この列挙からの値の組み合わせを指定すると、対応するクリップ面が有効になり、これらの値を省略すると、対応するクリップ面が無効になる (D3DCPF_DISABLEALL を使用すると、すべてのクリップ面が無効になる)。このようなセマンティクスにより、アプリケーションでは 1 回の呼び出しであらゆるクリップ面を有効または無効にできる。

次の Visual Basic コードは、このメソッドの使用方法を示す。

' この例では、d3dDevice 変数は Direct3DDevice7 オブジェクトへの
' 有効な参照である。

' クリップ面の 0 および 1 を有効にする。
' その他すべてのユーザー定義クリップ面は無効であるとする。
Call d3dDevice.SetRenderState(D3DRENDERSTATE_CLIPPLANEENABLE, _
(D3DCPF_ENABLEPLANE0 Or D3DCPF_ENABLEPLANE1))


ライト プロパティの取得

[C++]

C++ で、既存の光源のプロパティをすべて取得するには、デバイスに対して IDirect3DDevice7::GetLight メソッドを呼び出す。GetLight メソッドを呼び出すとき、プロパティを取得する光源の 0 から始まるインデックスを第 1 パラメータに渡し、D3DLIGHT7 構造体のアドレスを第 2 パラメータに渡す。デバイスは、D3DLIGHT7 構造体に値を設定して、指定されたインデックスの光源でそのデバイスが使用するライト プロパティを記述する。

次の C++ コードはこの処理を示す。

    /*
* この例では、g_lpd3dDev 変数は IDirect3DDevice7 インターフェイスへの
* 有効なポインタである。
     */
HRESULT hr;
D3DLIGHT7 light;

// 最初のライトについてのプロパティ情報を取得する。
hr = g_lpd3dDev->GetLight(0, light);
if (FAILED(hr))
    {
// エラー処理コード
    }

デバイス内で割り当てられている光源の範囲外のインデックスを指定すると、GetLight メソッドは失敗し、DDERR_INVALIDPARAMS を返す。

[Visual Basic]

Visual Basic アプリケーションで、既存の光源のプロパティを取得するには、デバイスに対して Direct3DDevice7.GetLight メソッドを呼び出す。GetLight メソッドを呼び出すとき、プロパティを取得する光源の 0 から始まるインデックスを第 1 パラメータに渡し、D3DLIGHT7 型の変数を第 2 パラメータに渡す。デバイスは、D3DLIGHT7 型に値を設定して、指定されたインデックスの光源でそのデバイスが使用するライト プロパティを記述する。

次の Visual Basic コードはこの処理を示す。

'
' この例では、d3dDevice 変数に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納される。
'
Dim lightDesc As D3DLIGHT7

' 最初のライトについてのプロパティ情報を取得する。
Call d3dDevice.GetLight(0, lightDesc)
If Err.Number <> DD_OK Then
' エラー処理コード
End If

デバイス内で割り当てられている光源の範囲外のインデックスを指定すると、GetLight メソッドは失敗し、Err.Number の値が DDERR_INVALIDPARAMS になる。


ステート ブロック ハンドル

ステート ブロック ハンドルとは、キャッシュされている、デバイス ステートのグループを一意に識別する 32 ビット値で、レンダリング デバイス内の対応するステート値である。これらのハンドルは、デバイスにステートを適用するために使用したり、レンダリング デバイスの現在のステートを取得したり、あるいはキャッシュされているステートが不要になった場合はそのステートを削除するために使用できる。

[C++]

C++ では、ステート ブロック ハンドルを受け取るのは、IDirect3DDevice7::EndStateBlock メソッドを呼び出してステート ブロックの記録を終了したとき、および IDirect3DDevice7::CreateStateBlock メソッドを呼び出して事前定義されているデバイス ステート データ セットを取得したときである。

[Visual Basic]

Visual Basic では、ステート ブロック ハンドルを受け取るのは、Direct3DDevice7.EndStateBlock メソッドを呼び出してステート ブロックの記録を終了したとき、および Direct3DDevice7.CreateStateBlock メソッドを呼び出して事前定義されているデバイス ステート データ セットを取得したときである。


ステート ブロックの適用

[C++]

IDirect3DDevice7::ApplyStateBlock メソッドは、既存のステート ブロックをデバイスに適用する。ApplyStateBlock メソッドは、パラメータ dwBlockHandle を 1 つだけ受け取る。このパラメータは、適用するステート ブロックを識別する。

注 : ステート ブロックの記録中 (つまり、IDirect3DDevice7::BeginStateBlock から IDirect3DDevice7::EndStateBlock の呼び出しの間)、別のステート ブロックを適用することはできない。これを実行しようとすると失敗し、D3DERR_INBEGINSTATEBLOCK が返される。

[Visual Basic]

Direct3DDevice7.ApplyStateBlock メソッドは、既存のステート ブロックをデバイスに適用する。ApplyStateBlock メソッドは、パラメータ blockHandle を 1 つだけ受け取る。このパラメータは、適用するステート ブロックを識別する。

注 : ステート ブロックの記録中 (つまり、Direct3DDevice7.BeginStateBlock から Direct3DDevice7.EndStateBlock の呼び出しの間)、別のステート ブロックを適用することはできない。これを実行しようとすると失敗し、D3DERR_INBEGINSTATEBLOCK が返される。


テクスチャ座標処理の流れ

次の図は、テクスチャ座標が処理を通してラスタライザに送られるまでの流れを示す。

[C++]

システムでは、2 つのソースからテクスチャ座標を描画できる。所定のテクスチャ ステージでは、頂点フォーマット (D3DFVF_TEX1 ～ D3DFVF_TEX8) に含まれるテクスチャ座標を使用するか、Direct3D で自動生成したテクスチャ座標を使用できる。文字の大文字/小文字の区別の詳細については、「テクスチャ座標の自動生成」を参照すること。現在のテクスチャ ステージの D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートを D3DTTFF_DISABLE に設定すると (デフォルト設定)、入力座標はトランスフォームされない。D3DTSS_TEXTURETRANSFORMFLAGS を別の値に設定すると、そのステージのトランスフォーム行列が入力座標に適用される。

D3DTEXTURETRANSFORMFLAGS 列挙型は、D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートに有効な値を定義する。テクスチャ座標トランスフォームを実行しない D3DTTFF_DISABLE フラグを除き、この列挙に定義される値は、システムによってラスタライザに渡される出力座標の個数を設定する。D3DTTFF_COUNT1 ～ D3DTTFF_COUNT4 フラグの場合、1、2、3、または 4 つの要素が出力座標からラスタライザに渡される (現在 1D テクスチャ座標はサポートされていない)。

D3DTTFF_PROJECTED フラグは特別なフラグである。このフラグは、テクスチャ座標が射影テクスチャ用のものであることをシステムに知らせる。D3DTTFF_PROJECTED フラグと D3DTEXTURETRANSFORMFLAGS のその他のメンバを組み合わせることで、すべての要素を最後の要素で除算してからラスタ化を実行するようにラスタライザに知らせる。たとえば、3 要素のテクスチャ座標 (または、トランスフォーム後の、3 要素のテクスチャ座標) を明示的に使用するとき、D3DTTFF_COUNT3 および D3DTTFF_PROJECTED フラグを組み合わせて使用すると、ラスタライザで最初の 2 つの要素を最後の要素で除算して、2D テクスチャの位置座標指定に必要な 2D テクスチャ座標を生成できる。

[Visual Basic]

システムでは、2 つのソースからテクスチャ座標を描画できる。所定のテクスチャ ステージでは、頂点フォーマット (D3DFVF_TEX1 ～ D3DFVF_TEX8) に含まれるテクスチャ座標を使用するか、Direct3D で自動生成したテクスチャ座標を使用できる。文字の大文字/小文字の区別の詳細については、「テクスチャ座標の自動生成」を参照すること。現在のテクスチャ ステージの D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートを D3DTTFF_DISABLE に設定すると (デフォルト設定)、入力座標はトランスフォームされない。D3DTSS_TEXTURETRANSFORMFLAGS を別の値に設定すると、そのステージのトランスフォーム行列が入力座標に適用される。

CONST_D3DTEXTURETRANSFORMFLAGS 列挙は、D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートに有効な値を定義する。テクスチャ座標トランスフォームを実行しない D3DTTFF_DISABLE フラグを除き、この列挙に定義される値は、システムによってラスタライザに渡される出力座標の個数を設定する。D3DTTFF_COUNT1 ～ D3DTTFF_COUNT4 フラグの場合、1、2、3、または 4 つの要素が出力座標からラスタライザに渡される。

D3DTTFF_PROJECTED フラグは特別なフラグである。このフラグは、テクスチャ座標が射影テクスチャ用のものであることをシステムに知らせる。D3DTTFF_PROJECTED フラグと CONST_D3DTEXTURETRANSFORMFLAGS のその他のメンバを組み合わせることで、すべての要素を最後の要素で除算してからラスタ化を実行するようにラスタライザに知らせる。たとえば、3 要素のテクスチャ座標 (または、トランスフォーム後の、3 要素のテクスチャ座標) を明示的に使用するとき、D3DTTFF_COUNT3 および D3DTTFF_PROJECTED フラグを組み合わせて使用すると、ラスタライザで最初の 2 つの要素を最後の要素で除算して、2D テクスチャの処理に必要な 2D テクスチャ座標を生成できる。

注 : キューブ環境マップを除き、ラスタライザでは 3 つ以上の要素を使用してテクスチャを処理することはできない。カレント テクスチャを処理するために使用できる要素数よりも多くの要素を、テクスチャ ステージに指定した場合、無関係な要素は無視される。これは、1D テクスチャに対して 2D テクスチャ座標を使用するときにも当てはまる。


ライティング ステート

Direct3D のジオメトリ パイプラインを使用するアプリケーションでは、ライティング計算を有効または無効にできる。頂点法線を含む頂点にのみ、ライティングが正しく適用される。頂点法線がない場合は、すべてのライティング計算で 0 の内積が使用される。つまり、法線を使用しない頂点にはライティングが適用されない。詳細については、「Direct3D のライティングにおける数学的計算」を参照すること。

[C++]

アプリケーションで Direct3D のライティングを有効にするには、D3DRENDERSTATE_LIGHTING レンダリング ステートを TRUE (デフォルト設定) に設定し、Direct3D のライティングを無効にするには FALSE に設定する。

ライティング レンダリング ステートは、頂点バッファ内の頂点で可能なライティング計算にはまったく依存しない。IDirect3DVertexBuffer7::ProcessVertices および IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドは、頂点処理の際にライティング計算を制御する、独自のフラグを受け取る。

注 : このレンダリング ステートは、反対ではあるが従来のレンダリング メソッドで使用された D3DDP_DONOTLIGHT フラグと類似している。DirectX 7.0 では、このレンダリング ステートが D3DDP_DONOTLIGHT フラグに置き換わっている。D3DDP_DONOTLIGHT フラグで 1 回の呼び出しごとにライティングを無効にする場合、ステート値がアプリケーションによって再度変更されるまでは、レンダリングに関するすべての呼び出しがこのレンダリング ステートの影響を受ける。

[Visual Basic]

アプリケーションで Direct3D のライティングを有効にするには、D3DRENDERSTATE_LIGHTING レンダリング ステートを TRUE (デフォルト値) に設定し、無効にするには FALSE に設定する。

ライティング レンダリング ステートは、頂点バッファ内の頂点で可能なライティング計算にはまったく依存しない。IDirect3DVertexBuffer7::ProcessVertices および IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドは、頂点処理の際にライティング計算を制御する、独自のフラグを受け取る。

注 : このレンダリング ステートは、反対ではあるが従来のレンダリング メソッドで使用された D3DDP_DONOTLIGHT フラグと類似している。DirectX 7.0 では、このレンダリング ステートが D3DDP_DONOTLIGHT フラグに置き換わっている。D3DDP_DONOTLIGHT フラグで 1 回の呼び出しごとにライティングを無効にする場合、ステート値がアプリケーションによって再度変更されるまでは、レンダリングに関するすべての呼び出しがこのレンダリング ステートの影響を受ける。


フォグ ステート

フォグ エフェクトを使用すると、3D シーンを一層リアルに表現できる。フォグ エフェクトは、単なる霧のシミュレーション以外にも使用できる。フォグ エフェクトで遠くの景色をぼかすことができる。これは、現実の世界で起こることを反映したものである。オブジェクトがビューアから離れるほど、オブジェクトの細部が不明瞭になる。アプリケーションでのフォグの使用の詳細については、「フォグ」を参照すること。

[C++]

C++ アプリケーションでは、デバイス レンダリング ステートを介してフォグを制御する。D3DRENDERSTATETYPE 列挙型には、ピクセル (テーブル) または頂点フォグのいずれが使用されているか、その色、システムが適用するフォグ公式、およびその公式へのパラメータなどを制御するステートが含まれる。

フォグを有効にするには、D3DRENDERSTATE_FOGENABLE レンダリング ステートを TRUE に設定する。フォグ カラーは、任意の D3DCOLOR 値に設定できる (フォグ カラーのアルファ成分は無視される)。詳細については、「D3DRENDERSTATE_FOGCOLOR.」を参照すること。

D3DRENDERSTATE_FOGTABLEMODE および D3DRENDERSTATE_FOGVERTEXMODE レンダリング ステートは、フォグの計算に適用されるフォグ公式を制御し、適用されるフォグの種類を間接的に制御する。この両方のレンダリング ステートは、D3DFOGMODE 列挙型のメンバのいずれかに設定できる。レンダリング ステートのいずれかを D3DFOG_NONE に設定すると、それに応じてピクセルまたは頂点フォグが無効になる。両方のレンダリング ステートを有効なモードに設定した場合は、ピクセル フォグ エフェクトのみ適用される。

D3DRENDERSTATE_FOGSTART および D3DRENDERSTATE_FOGEND レンダリング ステートは、D3DFOG_LINEAR モード用のフォグ公式パラメータを制御する。D3DRENDERSTATE_FOGDENSITY レンダリング ステートは、指数フォグ モードのフォグ濃度を制御する。

詳細については、「フォグ パラメータ」を参照すること。

[Visual Basic]

Visual Basic アプリケーションでは、デバイス レンダリング ステートを介してフォグを制御する。CONST_D3DRENDERSTATETYPE 列挙型には、ピクセル (テーブル) または頂点フォグのいずれが使用されているか、その色、システムが適用するフォグ公式、およびその公式へのパラメータなどを制御するステートが含まれる。

フォグを有効にするには、D3DRENDERSTATE_FOGENABLE レンダリング ステートを TRUE に設定する。フォグ カラーは、DirectX7.CreateColorRGB メソッドが返す、任意の Long 型の値に設定できる。「D3DRENDERSTATE_FOGCOLOR」を参照すること。

D3DRENDERSTATE_FOGTABLEMODE および D3DRENDERSTATE_FOGVERTEXMODE レンダリング ステートは、フォグの計算に適用されるフォグ公式を制御し、適用されるフォグの種類を間接的に制御する。この両方のレンダリング ステートは、CONST_D3DFOGMODE 列挙のメンバのいずれかに設定できる。レンダリング ステートのいずれかを D3DFOG_NONE に設定すると、それに応じてピクセルまたは頂点フォグが無効になる。両方のレンダリング ステートを有効なモードに設定した場合は、ピクセル フォグ エフェクトのみ適用される。

D3DRENDERSTATE_FOGSTART および D3DRENDERSTATE_FOGEND レンダリング ステートは、D3DFOG_LINEAR モード用のフォグ公式パラメータを制御する。D3DRENDERSTATE_FOGDENSITY レンダリング ステートは、指数フォグ モードのフォグ濃度を制御する。

詳細については、「フォグ パラメータ」を参照すること。


レンダリング コマンド バッチ処理ステート

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。

[C++]

注 : このレンダリング ステートは、テクスチャ ハンドルで (IDirect3DDevice2 インターフェイスを使用) レンダリングするアプリケーション以外では使用できない。IDirect3DDevice7 インターフェイスでレンダリングすると、バッチ処理されたプリミティブは暗黙的にフラッシュされる。


サーフェスのクリア

シーンのオブジェクトをレンダリングする前に、レンダリング ターゲット サーフェスのビューポート (またはビューポートのサブセット) をクリアする。ビューポートをクリアすると、システムはレンダリング ターゲット サーフェスの描画部分、およびアタッチされた深度バッファまたはステンシル バッファを指定のステートに設定する。その結果、再度レンダリングするサーフェスの領域がリセットされ、深度バッファとステンシル バッファを使用している場合は、その対応する領域がリセットされる。レンダリング ターゲット サーフェスをクリアすると、指定した領域をデフォルトの色やテクスチャに設定できる。深度バッファおよびステンシル バッファに対しては、深度およびステンシル値を設定できる。

[C++]

IDirect3DDevice7 インターフェイスには、ビューポートをクリアする IDirect3DDevice7::Clear メソッドがある。これらのメソッドの使用方法の詳細については、「ビューポートとクリッピング」セクションの「ビューポートのクリア」を参照すること。

[Visual Basic]

Visual Basic の Direct3DDevice7 クラスには、ビューポートをクリアする Direct3DDevice7.Clear メソッドがある。これらのメソッドの使用方法の詳細については、「ビューポートとクリッピング」セクションの「ビューポートのクリア」を参照すること。

最適化に関する注意 : レンダリング ターゲット サーフェスの全領域に及ぶシーンをレンダリングするアプリケーションで、パフォーマンスを改善するには、レンダリング ターゲットではなく、アタッチされた深度およびステンシル バッファ サーフェス (ある場合) をクリアする。この場合、深度バッファをクリアすると、Direct3D は次にレンダリングするフレームにレンダリング ターゲットを再書き込みすることで、レンダリング ターゲットに対する明示的なクリア処理を冗長にする。ただし、レンダリング ターゲット サーフェスの一部にのみレンダリングする場合は、明示的なクリア処理が必要である。


ディフューズ反射モデル

[C++]

Direct3D では、次の公式を使用してディフューズ反射係数を計算する。

この公式では、Rd はディフューズ反射係数、D は光の方向、N は頂点法線である。ベクトル D は正規化される。ベクトル N は、D3DRENDERSTATE_NORMALIZENORMALS レンダリング ステートが有効になっている場合にのみ正規化される。ライティングの方向ベクトルに -1 を乗じて逆ベクトルにして、方向ベクトルと頂点法線の間の適正な関係付けを作成する。この公式の結果は -1.0 ～ 1.0 の範囲の値である。この値は 0.0 ～ 1.0 の範囲に制限され、頂点から反射されるライティングの強度を調整するために使用される。

ディフューズ反射係数を計算した後で、減衰率を考慮した頂点にあたる光を次のようなディフューズ反射公式に適用して、その頂点におけるディフューズ成分が決定される。次の公式は、アンビエント反射とディフューズ反射を組み合わせて頂点におけるディフューズ成分を作成する。

この公式では、Dv は頂点に対して計算されるディフューズ成分、Ia はシーン内のアンビエント ライト、および A は距離とスポット ライト エフェクトのために減衰した光源のライティング強度 (スポット ライト フォールオフ モデルで乗算された、距離の増加によるライトの減衰)。L 変数はライティングのプロパティを表し、V エントリは頂点色を表す。ここで、それぞれに適用されている添字 a、d、および e は、色の種類のアンビエント (ambient)、ディフューズ (diffuse)、またはエミッション (emissive) を表す。公式で示すように、まず IaVa + Ve が計算され、すべてのアクティブなライティングの A(RdVdLd + VaLa) が加算される。

D3DRENDERSTATE_COLORVERTEX レンダリング ステートが有効になっている場合、D3DRENDERSTATE_AMBIENTMATERIALSOURCE および D3DRENDERSTATE_DIFFUSEMATERIALSOURCE レンダリング ステートに対して設定される値に基づいて V の色が選択される。これらのレンダリング ステートを D3DMATERIALCOLORSOURCE 列挙型のメンバに設定して、現在のマテリアルか、頂点の色を色ソースとして使用する。

詳細については、「スペキュラ反射モデル」を参照すること。

[Visual Basic]

Direct3D では、次の公式を使用してディフューズ反射係数を計算する。

この公式では、Rd はディフューズ反射係数、D の方向、N は頂点法線である。ベクトル D は正規化される。ベクトル N は、D3DRENDERSTATE_NORMALIZENORMALS レンダリング ステートが有効になっている場合にのみ正規化される。ライティングの方向ベクトルに -1 を乗じて逆ベクトルにして、方向ベクトルと頂点法線の間の適正な関係付けを作成する。この公式の結果は -1.0 ～ 1.0 の範囲の値である。この値は 0.0 ～ 1.0 の範囲に制限され、頂点から反射されるライティングの強度を調整するために使用される。

ディフューズ反射係数を計算した後で、その結果を次のようなディフューズ反射公式に適用して、その頂点におけるディフューズ成分が決定される。次の公式は、アンビエント反射とディフューズ反射を組み合わせて頂点におけるディフューズ成分を作成する。

この公式では、Dv は頂点に対して計算されるディフューズ成分、Ia はシーン内のアンビエント ライト、および A は距離とスポット ライト エフェクトのために減衰した高原のライティング強度 (スポット ライト フォールオフ モデル で乗算された、距離の増加によるライトの減衰)。L 変数はライティングのプロパティを表し、V エントリは頂点色を表す。ここで、それぞれに適用されている添字 a、d、および e は、色の種類であるアンビエント (ambient)、ディフューズ (diffuse)、またはエミッション (emissive) を表す。公式で示すように、まず IaVa + Ve が計算され、すべてのアクティブなライティングの A(RdVdLd + VaLa) が加算される。

D3DRENDERSTATE_COLORVERTEX レンダリング ステートが有効になっている場合、D3DRENDERSTATE_AMBIENTMATERIALSOURCE および D3DRENDERSTATE_DIFFUSEMATERIALSOURCE レンダリング ステートに対して設定される値に基づいて V の色が選択される。これらのレンダリング ステートを CONST_D3DMATERIALCOLORSOURCE 列挙のメンバを設定して、現在のマテリアルか、頂点の色を色ソースとして使用する。

詳細については、「スペキュラ反射モデル」を参照すること。


ライト プロパティの設定

[C++]

C++ アプリケーションでライト プロパティを設定するには、D3DLIGHT7 構造体を用意し、次に IDirect3DDevice7::SetLight メソッドを呼び出す。SetLight メソッドは、デバイスがライト プロパティ セットをデバイス内部のライト プロパティのリストに配置する際のインデックスと、そのライト プロパティを定義する D3DLIGHT7 構造体のアドレスを受け取る。ライト プロパティの更新が必要なときは、新しい情報で SetLight を呼び出すことができる。

プロパティを割り当てられていないインデックスで SetLight メソッドを呼び出すたびに、システムはライト プロパティ セットを格納するためのメモリを割り当てる。アプリケーションでは、割り当てられているライトのサブセットを一度に有効にして、数多くのライトを設定できる。デバイスがサポートするアクティブなライトの最大数を決定するためにデバイス機能を取得するときは、D3DDEVICEDESC7 構造体の dwMaxActiveLights メンバをチェックする。特定のライトを使用する必要がなくなった場合は、そのライトを無効にするか、新しいライト プロパティ セットで上書きすることができる。

次の C++ コードは、距離の増加によって減衰しない、白色のポイント ライトのプロパティを準備および設定する。

    /*
* この例では、g_lpd3dDev 変数は、IDirect3DDevice7 インターフェイスへの
* 有効なポインタである。
     */
    D3DLIGHT7 d3dLight;
    HRESULT   hr;

// 構造体を初期化する。
    ZeroMemory(&d3dLight, sizeof(D3DLIGHT7));

// 白色のポイント ライトの設定を行う。
    d3dLight.dltType = D3DLIGHT_POINT;
d3dLight.dcvDiffuse.r = 1.0f;
d3dLight.dcvDiffuse.g = 1.0f;
d3dLight.dcvDiffuse.b = 1.0f;
d3dLight.dcvAmbient.r = 1.0f;
d3dLight.dcvAmbient.g = 1.0f;
d3dLight.dcvAmbient.b = 1.0f;
d3dLight.dcvSpecular.r = 1.0f;
d3dLight.dcvSpecular.g = 1.0f;
d3dLight.dcvSpecular.b = 1.0f;

// ポイント ライトをシーンの上部でビューアの背後に配置する。
// (これらの座標はワールド空間のものである。したがって、
//  "ビューア" はワールド空間内のどの位置座標にでも存在できる。
この例では、
//  ビューアはワールド空間の原点にいるとする)。
    d3dLight.dvPosition.x = 0.0f;
    d3dLight.dvPosition.y = 1000.0f;
    d3dLight.dvPosition.z = -100.0f;

// 減衰させない。
    d3dLight.dvAttenuation0 = 1.0f;
    d3dLight.dvRange = D3DLIGHT_RANGE_MAX;

// 最初のライトのプロパティ情報を設定する。
hr = g_lpd3dDev->SetLight(0, d3dLight);
if (FAILED(hr))
    {
// エラー処理コード
    }

ライト プロパティ セットは、再度 SetLight を呼び出していつでも更新できる。更新するライト プロパティ セットのインデックスと、新しいプロパティを含む D3DLIGHT7 構造体のアドレスを指定するだけである。

注 : ライト プロパティ セットをデバイスに割り当てても、追加されるプロパティを持つ光源が有効になるわけではない。光源を有効にするには、デバイスに対して IDirect3DDevice7::LightEnable メソッドを呼び出す。

[Visual Basic]

Visual Basic アプリケーションでライト プロパティを設定するには、D3DLIGHT7 型を用意し、次に Direct3DDevice7.SetLight メソッドを呼び出す。SetLight メソッドは、デバイスがライト プロパティ セットをデバイス内部のライト プロパティのリストに配置する際のインデックスと、そのライト プロパティを定義する D3DLIGHT7 型のアドレスを受け取る。ライト プロパティの更新が必要なときは、新しい情報で SetLight を呼び出すことができる。

プロパティを割り当てられていないインデックスで SetLight メソッドを呼び出すたびに、システムはライト プロパティ セットを格納するためのメモリを割り当てる。アプリケーションでは、割り当てられているライトのサブセットを一度に有効にして、数多くのライトを設定することができる。デバイスがサポートするアクティブなライトの最大数を決定するためにデバイス機能を取得するときは、D3DDEVICEDESC7 型の lMaxActiveLights メンバをチェックする。特定のライトを使用する必要がなくなった場合は、そのライトを無効にするか、新しいライト プロパティ セットで上書きすることができる。

次の Visual Basic コードは、距離の増加によって減衰しない、白色のポイント ライトのプロパティを準備および設定する。

'
' この例では、d3dDevice 変数に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納される。
'
Dim LightDesc As D3DLIGHT7
Dim c As D3DCOLORVALUE
Dim vPos As D3DVECTOR

' すべての放射光色に同じ色設定を使用する。
With c
.r = 1#:.g = 1#:.b = 1#
.a = 1# ' アルファ成分は使用しない。
End With

With vPos
.x = 0:.y = 1000:.z = -100
End With

With LightDesc
.dltType = D3DLIGHT_POINT
.position = vPos
.Ambient = c:.diffuse = c:.specular = c
.attenuation0 = 1# ' 光を減衰させない。
End With

d3dDevice.SetLight 0, LightDesc

ライト プロパティ セットは、再度 SetLight を呼び出していつでも更新できる。更新するライト プロパティ セットのインデックスと、新しいプロパティを含む D3DLIGHT7 型のアドレスを指定するだけである。

注 : ライト プロパティ セットをデバイスに割り当てても、追加されるプロパティを持つ光源が有効になるわけではない。光源を有効にするには、デバイスに対して Direct3DDevice7.LightEnable メソッドを呼び出す。


スペキュラ ライト マップ

光源で照らしたとき、"光を発する" オブジェクト (反射性の高いマテリアルを使用するオブジェクト) はスペキュラ ハイライトを受け取る。ライティング モジュールで生成されたスペキュラ ハイライトは正確でない場合がある。より効果的なハイライトを生成するために、多くの Direct3D アプリケーションではプリミティブにスペキュラ ライト マップを適用する。

スペキュラ ライト マッピングを実行するには、まずスペキュラ ライト マップをプリミティブの既存のテクスチャに合わせて調節する。次に、モノクロまたは RGB ライト マップを追加する。

[C++]

次のコードは、C++ におけるこの処理を示す。

// この例では、lpD3DDev は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
// lptexBaseTexture は、テクスチャへの有効なポインタである。
// lptexSpecLightMap は、RGB スペキュラ ライト マップ データを含む
// テクスチャへの有効なポインタである。
// lptexLightMap は、RGB ライト マップ データを含む
// テクスチャへの有効なポインタである。

// ベース テクスチャを設定する。
lpD3DDev->SetTexture(0,lptexBaseTexture );

// ベース テクスチャ処理と引数を設定する。
lpD3DDev->SetTextureStageState(0,D3DTSS_COLOROP,
       D3DTOP_MODULATE );
lpD3DDev->SetTextureStageState(0,D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(0,D3DTSS_COLORARG2, D3DTA_DIFFUSE );

// スペキュラ ライト マップを設定する。
lpD3DDev->SetTexture(1,lptexSpecLightMap );

// スペキュラ ライト マップと引数を設定する。
lpD3DDev->SetTextureStageState(1,D3DTSS_COLOROP,
       D3DTOP_ADD );
lpD3DDev->SetTextureStageState(1,D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(1,D3DTSS_COLORARG2, D3DTA_CURRENT );

// RGB ライト マップを設定する。
lpD3DDev->SetTexture(2,lptexLightMap);

// RGB ライト マップ処理と引数を設定する。
lpD3DDev->SetTextureStageState(2,D3DTSS_COLOROP, D3DTOP_MODULATE);
lpD3DDev->SetTextureStageState(2,D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(2,D3DTSS_COLORARG2, D3DTA_CURRENT );
[Visual Basic]

次の Visual Basic コードは、この処理を示す。

' この例では、d3dDev は Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
' texBaseTexture はテクスチャへの有効な参照である。
' texSpecLightMap は、RGB スペキュラ ライト マップ データを含む
' テクスチャへの有効な参照である。
' texLightMap は、RGB ライト マップ データを含む
' テクスチャへの有効な参照である。

' ベース テクスチャを設定する。
Call d3dDev.SetTexture(0, texBaseTexture)

' ベース テクスチャ処理と引数を設定する。
Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, _
D3DTOP_MODULATE );
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

' スペキュラ ライト マップを設定する。
Call d3dDev.SetTexture(1, texSpecLightMap)

' スペキュラ ライト マップ処理と引数を設定する。
Call d3dDev.SetTextureStageState(1, D3DTSS_COLOROP, _
D3DTOP_ADD)
Call d3dDev.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)

' RGB ライト マップを設定する。
Call d3dDev.SetTexture(2, texLightMap)

' RGB ライト マップ処理と引数を設定する。
Call d3dDev.SetTextureStageState(2, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDev.SetTextureStageState(2, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(2, D3DTSS_COLORARG2, D3DTA_CURRENT)


シーンの開始と終了

[C++]

C++ で記述されたアプリケーションでは、IDirect3DDevice7::BeginScene メソッドを呼び出して、Direct3D にシーンのレンダリングの開始を知らせる。BeginScene の命令を受けたシステムは、内部データ構造およびレンダリングするサーフェスの可用性と妥当性をチェックし、シーンが処理中であることを知らせる内部フラグを設定する。シーンの開始後は、さまざまなレンダリング メソッドを呼び出してプリミティブをレンダリングしたり、シーンのオブジェクトを構成する頂点を個別にレンダリングすることができる。シーンの処理中でないときにレンダリング メソッドを呼び出そうとすると失敗し、D3DERR_SCENE_NOT_IN_SCENE が返される。詳細については、「プリミティブのレンダリング」を参照すること。

シーンが完了したら、IDirect3DDevice7::EndScene メソッドを呼び出す。EndScene メソッドは、シーンの処理中であることを知らせる内部フラグをクリアし、キャッシュされていたデータをフラッシュし、レンダリング サーフェスの整合性を検証する。

レンダリング メソッドはすべて、BeginScene メソッドを呼び出してから EndScene メソッドを呼び出すまでの間に実行しなければならない。サーフェスが失われるか、または内部エラーが発生すると、シーンのメソッドはエラー値を返す。BeginScene メソッドが失敗した場合、シーンは開始されず、それに続く EndScene の呼び出しも失敗する。レンダリング中にサーフェスが失われた場合は、EndScene が DDERR_SURFACELOST を返す。BeginScene を呼び出す前にサーフェスが正常に復元されなかった場合、BeginScene も DDERR_SURFACELOST を返す。

これらのケースを以下にまとめる。

  • BeginScene が何らかのエラーを返した場合、シーンは正常に開始されていないため、EndScene を呼び出してはならない。
  • BeginScene は成功したがシーンのレンダリング中にエラーが発生した場合は、EndScene を呼び出す必要がある。
  • 何らかの理由で EndScene が失敗した場合は、これを再度呼び出す必要はない。

たとえば、単純なシーンを処理するコードは次のようになる。

HRESULT hr;

if(SUCCEEDED(lpDevice->BeginScene()))
{
// シーンの開始に成功した場合のみ、
// プリミティブをレンダリングする。

// シーンを閉じる。
    hr = lpDevice->EndScene();
    if(FAILED(hr))
        return hr;
}

シーンを埋め込むことはできない。つまり、次のシーンをレンダリングするには、現在レンダリング中のシーンを完了する必要がある。IDirect3DDevice7::BeginScene が呼び出されていないのに IDirect3DDevice7::EndScene を呼び出した場合、D3DERR_SCENE_NOT_IN_SCENE エラーが返される。同様に、前のシーンが EndScene メソッドでまだ完了していないときに BeginScene を呼び出すと、D3DERR_SCENE_IN_SCENE エラーが発生する。

シーンのレンダリング中 (BeginScene を呼び出してから EndScene を呼び出すまでの間)、レンダリング ターゲットやテクスチャなどの DirectDraw サーフェスに対して GDI 関数を呼び出してはならない。この関数を呼び出そうとすると、GDI 操作の結果が表示されなくなる可能性がある。アプリケーションで GDI 関数を使用する場合は、シーン関数の外ですべての GDI の呼び出しを行うようにする。

[Visual Basic]

Visual Basic アプリケーションでは、Direct3DDevice7.BeginScene メソッドを呼び出して、Direct3D にシーンのレンダリングの開始を知らせる。BeginScene の命令を受けたシステムは、内部データ構造、レンダリングするサーフェスの可用性と妥当性をチェックし、シーンが処理中であることを知らせる内部フラグを設定する。シーンの開始後は、さまざまなレンダリング メソッドを呼び出してプリミティブをレンダリングしたり、シーンのオブジェクトを構成する頂点を個別にレンダリングすることができる。シーンの処理中でないときにレンダリング メソッドを呼び出そうとすると失敗し、D3DERR_SCENE_NOT_IN_SCENE が返される。詳細については、「プリミティブのレンダリング」を参照すること。

シーンが完了したら、Direct3DDevice7.EndScene メソッドを呼び出す。EndScene メソッドは、シーンの処理中であることを知らせる内部フラグをクリアし、キャッシュされていたデータをフラッシュし、レンダリング サーフェスの整合性を検証する。

レンダリング メソッドはすべて、BeginScene メソッドを呼び出してから EndScene メソッドを呼び出すまでの間に実行しなければならない。サーフェスが失われるか、または内部エラーが発生した場合は、シーンのメソッドが失敗し、Err.Number にエラー コードが設定される。BeginScene が失敗した場合、シーンは開始されず、それに続く EndScene の呼び出しも失敗する。レンダリング中にサーフェスが失われた場合は、EndScene が失敗し、DDERR_SURFACELOST エラーが発生する。BeginScene を呼び出す前にサーフェスが正常に復元されなかった場合、BeginScene も DDERR_SURFACELOST を返す。

これらのケースを以下にまとめる。

  • BeginScene が何らかのエラーを返した場合、シーンは正常に開始されていないため、EndScene を呼び出してはならない。
  • BeginScene は成功したがシーンのレンダリング中にエラーが発生した場合、EndScene を呼び出す必要がある。
  • 何らかの理由で EndScene が失敗した場合は、これを再度呼び出す必要はない。

たとえば、単純なシーンを処理するコードは次のようになる。

On Local Error Resume Next

Call d3dDev.BeginScene
If Err.Number = DD_OK Then
' シーンの開始に成功した場合のみ、
' プリミティブをレンダリングする。

' シーンを閉じる。
Call d3dDev.EndScene
If Err.Number <> DD_OK Then
' エラー処理コード
End If
End If

シーンを埋め込むことはできない。つまり、次のシーンをレンダリングするには、現在レンダリング中のシーンを完了する必要がある。Direct3DDevice7.BeginScene が呼び出されていないときに Direct3DDevice7.EndScene を呼び出した場合、D3DERR_SCENE_NOT_IN_SCENE エラーが発生する。同様に、前のシーンが EndScene メソッドでまだ完了していないときに BeginScene を呼び出すと、D3DERR_SCENE_IN_SCENE エラーが発生する。

シーンのレンダリング中 (BeginScene を呼び出してから EndScene を呼び出すまでの間)、レンダリング ターゲットやテクスチャなどの DirectDraw サーフェスに対して GDI 関数を呼び出してはならない。この関数を呼び出そうとすると、GDI 操作の結果が表示されなくなる可能性がある。アプリケーションで GDI 関数を使用する場合は、シーン関数の外ですべての GDI の呼び出しを行うようにする。


球体環境マップの適用

[C++]

環境マップをオブジェクトに適用するときは、その他のテクスチャの場合と同様、IDirect3DDevice7::SetTexture メソッドで適切なテクスチャ ステージにテクスチャを設定する。第 1 パラメータには、希望のテクスチャ ステージのインデックスを設定し、第 2 パラメータには、環境マップのテクスチャの作成時に返された IDirectDrawSurface7 インターフェイスのアドレスを設定する。必要に応じて色およびアルファ ブレンディング処理と引数を設定して、希望のテクスチャ ブレンディング エフェクトを得ることができる。

[Visual Basic]

環境マップをオブジェクトに適用するときは、その他のテクスチャの場合と同様、Direct3DDevice7.SetTexture メソッドで適切なテクスチャ ステージにテクスチャを設定する。第 1 パラメータには、希望のテクスチャ ステージのインデックスを設定し、第 2 パラメータには、環境マップのテクスチャの作成時に返された DirectDrawSurface7 インターフェイスのアドレスを設定する。必要に応じて色およびアルファ ブレンディング処理と引数を設定して、希望のテクスチャ ブレンディング エフェクトを得ることができる。


アウトラインおよび塗りつぶしステート

[C++]

テクスチャが適用されていないプリミティブは、マテリアルによって指定される色、または頂点に指定された色があれば、そのいずれかでレンダリングされる。プリミティブを塗りつぶす方法は、D3DFILLMODE 列挙型で選択できる。「D3DRENDERSTATE_FILLMODE」を参照すること。

アプリケーションでディザリングを有効にするには、第 1 パラメータとして D3DRENDERSTATE_DITHERENABLE 列挙値を IDirect3DDevice7::SetRenderState に渡す必要がある。ディザリングを有効にするには第 2 パラメータを TRUE に設定し、無効にするには FALSE に設定する。

線の最後のピクセルを描画すると周囲のプリミティブと重なり、見た目が悪くなることがある。これは、D3DRENDERSTATE_LASTPIXEL 列挙値を使用して制御できる。ただし、この設定を変更するときは注意が必要である。場合によっては、最後のピクセルを描画しないようにするとプリミティブ間に隙間が生じ、見苦しくなることがある。

デフォルトでは、Direct3D デバイスはプリミティブに実線のアウトラインを使用する。アウトライン パターンは、D3DLINEPATTERN 構造体を使用して変更できる。「D3DRENDERSTATE_LINEPATTERN」を参照すること。

注 : 従来のレンダリング ステート D3DRENDERSTATE_ROP2、D3DRENDERSTATE_STIPPLEENABLE、および D3DRENDERSTATE_STIPPLEPATTERN00 ～ D3DRENDERSTATE_STIPPLEPATTERN31 は、DirectX 7.0 リリースでは使用されない。

[Visual Basic]

テクスチャが適用されていないプリミティブは、マテリアルによって指定される色、または頂点に指定された色があれば、そのいずれかでレンダリングされる。プリミティブを塗りつぶす方法は、CONST_D3DFILLMODE 列挙型で選択できる。「D3DRENDERSTATE_FILLMODE」を参照すること。

アプリケーションでディザリングを有効にするには、第 1 パラメータとして D3DRENDERSTATE_DITHERENABLE 列挙値を Direct3DDevice7::SetRenderState に渡す必要がある。ディザリングを有効にするには第 2 パラメータを True に設定し、無効にするには False に設定する。

線の最後のピクセルを描画すると周囲のプリミティブと重なり、見た目が悪くなることがある。これは、D3DRENDERSTATE_LASTPIXEL 列挙値を使用して制御できる。ただし、この設定を変更するときは注意が必要である。場合によっては、最後のピクセルを描画しないようにするとプリミティブ間に隙間が生じ、見苦しくなることがある。

DirectX for Visual Basic では、D3DRENDERSTATE_LINEPATTERN レンダリング ステートはサポートしていない。


ステート ブロックの記録

[C++]

IDirect3DDevice7 インターフェイスには、アプリケーションからデバイス ステートの要求があったときにそのデバイス ステートをステート ブロックに記録する IDirect3DDevice7::BeginStateBlock メソッドがある。BeginStateBlock メソッドは、デバイス ステートの変更をデバイスに適用するのではなく、デバイス ステートの変更をステート ブロックに記録し始める。BeginStateBlock を呼び出した後、以下のあらゆるメソッドの呼び出しがデバイス ステート ブロックに記録される。

  • IDirect3DDevice7::LightEnable
  • IDirect3DDevice7::SetClipPlane
  • IDirect3DDevice7::SetLight
  • IDirect3DDevice7::SetMaterial
  • IDirect3DDevice7::SetRenderState
  • IDirect3DDevice7::SetTexture
  • IDirect3DDevice7::SetTextureStageState
  • IDirect3DDevice7::SetTransform
  • IDirect3DDevice7::SetViewport

ステート ブロックの記録が終了したら、IDirect3DDevice7::EndStateBlock メソッドを呼び出して記録の停止をシステムに知らせる。EndStateBlock メソッドは、記録したステート ブロックのハンドルを変数に格納する。この変数のアドレスは lpdwBlockHandle パラメータに渡す。アプリケーションでは、このハンドルを使用して、必要に応じてステート ブロックをデバイスに適用したり、新しいステート データをブロックに記録したり、不要になったステート ブロックを削除することができる。

[Visual Basic]

Direct3DDevice7 オブジェクトには、アプリケーションからデバイス ステートの要求があったときにそのデバイス ステートをステート ブロックに記録する Direct3DDevice7.BeginStateBlock メソッドがある。BeginStateBlock メソッドは、デバイス ステートの変更をデバイスに適用するのではなく、デバイス ステートの変更をステート ブロックに記録し始める。BeginStateBlock を呼び出した後、以下のあらゆるメソッドの呼び出しがデバイス ステート ブロックに記録される。

  • Direct3DDevice7.LightEnable
  • Direct3DDevice7.SetClipPlane
  • Direct3DDevice7.SetLight
  • Direct3DDevice7.SetMaterial
  • Direct3DDevice7.SetRenderState
  • Direct3DDevice7.SetTexture
  • Direct3DDevice7.SetTextureStageState
  • Direct3DDevice7.SetTransform
  • Direct3DDevice7.SetViewport

ステート ブロックの記録が終了したら、Direct3DDevice7.EndStateBlock メソッドを呼び出して記録の停止をシステムに知らせる。EndStateBlock メソッドは、記録したステート ブロックのハンドルを、blockHandle パラメータに渡す変数に格納する。アプリケーションでは、このハンドルを使用して、必要に応じてステート ブロックをデバイスに適用したり、新しいステート データをブロックに記録したり、不要になったステート ブロックを削除することができる。

パフォーマンスに関する注意 : 最良の結果を得るためには、BeginStateBlock/EndStateBlock のペア間でのすべてのステート変更をグループ化する。

EndStateBlock メソッドが返すエラー コードをチェックすることが大切である。このメソッドが失敗した場合、その原因の多くはディスプレイ モードが変更されたことであると考えられる (エラー コード DDERR_SURFACELOST)。アプリケーションのサーフェスを作成し直し、再度ステート ブロックを記録することで、このような障害からアプリケーションが回復するように設計する。


スポット ライト

スポット ライトは、色、位置座標、および光を放射する方向を持つ。スポット ライトから放射される光は、C++ の D3DLIGHT7 構造体 (Visual Basic では D3DLIGHT7 型) の関連メンバに加えて、明るい内部コーンとこれより大きな外部コーンで構成される。次の図に示すように、光の強度は 2 つのコーン間で減少する。

スポット ライトは、フォールオフ、減衰、および範囲の影響を受ける。これらの要因は、光が各頂点まで進む距離と同様、シーン内のオブジェクトへのライティング エフェクトを計算するときに考慮に入れる。各頂点に対するこれらのエフェクトをすべて計算する場合、Direct3D 直接モードのすべてのライトの中でコンピュータへの負荷が最も大きいのはスポット ライトである。


ライトの位置座標、範囲、および減衰

[C++]

位置座標、範囲、および減衰プロパティは、ワールド空間でのライトの位置座標、およびライトが放射する光が距離の増加に伴ってどのように変化するかを定義する。C++ で使用するすべてのライト プロパティと同様、これらのプロパティはライトの D3DLIGHT7 構造体に含まれる。

位置座標

ライトの位置座標は、D3DLIGHT7 構造体の dvPosition メンバに D3DVECTOR 構造体を使用して指定する。x、y、z 座標はワールド空間にあると仮定する。ディレクショナル ライトは、位置座標プロパティを使用しない唯一のライトである。

範囲

ライトの範囲プロパティは、オブジェクトが放射した光をシーン内のメッシュが受け取れなくなるまでの、ワールド空間での距離を決める。dvRange メンバには、ワールド空間でのライトの最大範囲を表す浮動小数点値が含まれる。ほとんどのアプリケーションでは、この範囲を D3d.h に定義されている最大値 D3DLIGHT_RANGE_MAX に設定する。ディレクショナル ライトでは範囲プロパティは使用しない。

減衰

減衰は、範囲プロパティで指定した最大距離に近づくにつれてライトの強度がどのように減少するかを制御する。ライトの減衰は、3 つの D3DLIGHT7 構造体の dvAttenuation0、dvAttenuation1、および dvAttenuation2 メンバで表す。これらのメンバには、ライトの減衰を制御する 0.0 ～ 無限大の浮動小数点値が含まれる。アプリケーションによっては、dvAttenuation1 メンバを 1.0 に設定し、その他のメンバを 0.0 に設定することで、ライトの強度が 1 / D として変化するようにする。ここで、D は光源から頂点までの距離である。光源ではライトの強度が最大で、そこから離れるに従って 1 / (ライトの範囲) に減少する。通常、アプリケーションでは dvAttenuation0 を 0.0 に設定し、dvAttenuation1 を定数に設定し、dvAttenuation2 を 0.0 に設定する。

減衰値を組み合わせて、より複雑な減衰エフェクトを出すことができる。また、減衰値を通常の範囲外の値に設定して、さらに珍しい減衰エフェクトを出すことができる。たとえば、負の減衰値を設定すると、距離が増加するに従ってライトが明るくなる。

Direct3D で減衰の計算に使用する数学モデルの詳細については、「距離の増加によるライトの減衰」を参照すること。範囲プロパティと同様、ディレクショナル ライトでは減衰プロパティは使用しない。

[Visual Basic]

D3DLIGHT7 型には、Visual Basic アプリケーションでライトの位置座標、範囲、および減衰プロパティを定義するために使用するメンバが含まれる。これらのプロパティは、ワールド空間でのライトの位置座標と、ライトが放射する光が距離の増加に伴ってどのように変化するかを定義する。

位置座標

ライトの位置座標は、D3DLIGHT7 型の position メンバに D3DVECTOR 型を使用して記述する。x、y、z 座標はワールド空間にあると仮定する。ディレクショナル ライトは、位置座標プロパティを使用しない唯一のライトである。

範囲

ライトの範囲プロパティは、オブジェクトが放射した光をシーン内のメッシュが受け取れなくなるまでの、ワールド空間での距離を決める。range メンバには、ワールド空間でのライトの最大範囲を表す浮動小数点値が含まれる。ほとんどのアプリケーションでは、この範囲を最大値 (18.446+e18) に設定する。ディレクショナル ライトでは範囲プロパティは使用しない。

減衰

減衰は、範囲プロパティで指定した最大距離に近づくにつれてライトの強度がどのように減少するかを制御する。ライトの減衰は、3 つの D3DLIGHT7 メンバ attenuation0、attenuation1、および attenuation2 で表す。これらのメンバには、ライトの減衰を制御する 0.0 ～ 無限大の浮動小数点値が含まれる。アプリケーションによっては、attenuation1 メンバを 1.0 に設定し、その他のメンバを 0.0 に設定することで、ライトの強度が 1 / D として変化するようにする。ここで、D は光源から頂点までの距離である。光源ではライトの強度が最大で、そこから離れるに従って 1 / (ライトの範囲) に減少する。通常、アプリケーションでは dvAttenuation0 を 0.0 に設定し、dvAttenuation1 を定数に設定し、dvAttenuation2 を 0.0 に設定する。

減衰値を組み合わせて、より複雑な減衰エフェクトを出すことができる。また、減衰値を通常の範囲外の値に設定して、さらに珍しい減衰エフェクトを出すことができる。たとえば、負の減衰値を設定すると、距離が増加するに従ってライトが明るくなる。

Direct3D で減衰の計算に使用する数学モデルの詳細については、「距離の増加によるライトの減衰」を参照すること。範囲プロパティと同様、ディレクショナル ライトでは減衰プロパティは使用しない。


範囲の更新ステート

[C++]

Direct3D では、ビューポート範囲を更新することで、レンダリング メソッドによる影響をビューポート領域に反映することができる。C++ で記述されたアプリケーションでは、システムによって実行される範囲の更新を D3DRENDERSTATE_EXTENTS レンダリング ステートを使用して制御する。このステートのデフォルト設定は FALSE で、範囲の更新は無効である。アプリケーションで IDirect3DDevice7::GetClipStatus および IDirect3DDevice7::SetClipStatus メソッドを使用してビューポート範囲を操作する場合は、D3DRENDERSTATE_EXTENTS を TRUE に設定することで範囲の更新を有効にできる。

範囲の更新レンダリング ステートは、頂点バッファで可能な範囲の更新処理にはまったく依存しない。IDirect3DVertexBuffer7::ProcessVertices および IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドは、頂点処理の際に範囲の更新処理を制御する、独自のフラグを受け取る。

注 : このレンダリング ステートは、反対ではあるが従来のレンダリング メソッドで使用された D3DDP_DONOTUPDATEEXTENTS フラグと類似している。DirectX 7.0 では、このレンダリング ステートが D3DDP_DONOTUPDATEEXTENTS フラグに置き換わっている。D3DDP_DONOTUPDATEEXTENTS フラグで 1 回の呼び出しごとに範囲の更新を無効にする場合、ステート値がアプリケーションによって再度変更されるまでは、レンダリングに関するすべての呼び出しがこのレンダリング ステートの影響を受ける。

[Visual Basic]

Direct3D では、ビューポート範囲を更新することで、レンダリング メソッドによる影響をビューポート領域に反映することができる。Visual Basic アプリケーションでは、システムによって実行される範囲の更新を D3DRENDERSTATE_EXTENTS レンダリング ステートを使用して制御できる。このステートのデフォルト設定は False で、範囲の更新は無効である。アプリケーションで Direct3DDevice7.GetClipStatus および Direct3DDevice7.SetClipStatus メソッドを使用してビューポート範囲を操作する場合は、D3DRENDERSTATE_EXTENTS を True に設定することで範囲の更新を有効にできる。

範囲の更新レンダリング ステートは、頂点バッファ内で可能な範囲の更新処理にはまったく依存しない。Direct3DVertexBuffer7.ProcessVertices メソッドは、頂点処理の際に範囲の更新処理を制御する、独自のフラグを受け取る。


フラット シェーディング

フラット シェーディング モードでは、Direct3D レンダリング パイプラインは、ポリゴンの最初の頂点におけるマテリアルの色をポリゴン全体の色として使用して、ポリゴンをレンダリングする。フラット シェーディングでレンダリングした 3D オブジェクトでは、同一平面上にないポリゴンの間に鋭いエッジが現れる。

次の図は、フラット シェーディングでレンダリングしたティーポットを示す。各ポリゴンの輪郭がはっきりと見える。フラット シェーディングは、計算負荷の最も少ないシェーディングである。


カレント テクスチャの割り当て

Direct3D では、最大 8 つまでのカレント テクスチャのリストを利用できる。Direct3D では、レンダリングするすべてのプリミティブに、これらのテクスチャをブレンドする。テクスチャ インターフェイス ポインタとして作成したテクスチャのみ、カレント テクスチャ セットで使用できる。

[C++]

アプリケーションでは、IDirect3DDevice7::SetTexture メソッドを呼び出してカレント テクスチャ セットにテクスチャを割り当てる。第 1 パラメータは、0 ～ 7 の範囲の数値でなければならない。第 2 パラメータとして、テクスチャ インターフェイス ポインタを渡す。

次の C++ コードは、テクスチャをカレント テクスチャ セットに割り当てる方法を示す。

// このコードでは、変数 lpd3dDev が IDirect3DDevice7 インターフェイスへの有効なポインタで、
// 変数 lpd3dTexture が IDirectDrawSurface7 インターフェイスへの
// 有効なポインタであるとする。

// 3 番目のテクスチャを設定する。
lpd3dDev->SetTexture(2, lpd3dTexture);
[Visual Basic]

Visual Basic で記述されたアプリケーションでは、Direct3DDevice7.SetTexture を呼び出してカレント テクスチャ セットにテクスチャを割り当てる。第 1 パラメータは、0 ～ 7 の範囲の数値でなければならない。第 2 パラメータとして、テクスチャ インターフェイス ポインタを渡す。

次の Visual Basic コードは、テクスチャをカレント テクスチャ セットに割り当てる方法を示す。

' このコードでは、変数 d3dDev が Direct3DDevice7 オブジェクトへの有効な参照で、
' d3dTexture が DirectDrawSurface7 オブジェクトへの
' 有効な参照であるとする。

' 3 番目のテクスチャを設定する。
Call d3dDev.SetTexture(2, d3dTexture)

ソフトウェア デバイスでは、テクスチャを一度に複数のテクスチャ ステージに割り当てることはできない。


プリミティブのレンダリング

以下のトピックでは、DrawPrimitive レンダリング メソッドについて、およびこのメソッドのアプリケーションでの使用方法について説明する。

  • DrawPrimitive メソッド
  • ストライド頂点のレンダリング


マテリアル プロパティの設定

Direct3D レンダリング デバイスでは、一度に 1 つのマテリアル プロパティのセットでレンダリングできる。

[C++]

C++ アプリケーションの場合、システムで使用するマテリアル プロパティを設定するには、D3DMATERIAL7 構造体を用意し、次に IDirect3DDevice7::SetMaterial メソッドを呼び出す。

D3DMATERIAL7 構造体を用意するには、この構造体にプロパティ情報を設定して、レンダリングでの希望のエフェクトを作成する。次のコードは、白色のスペキュラ ハイライトがある、紫色のマテリアル用の D3DMATERIAL7 構造体を設定する。

    D3DMATERIAL7 mat;

// ディフューズ反射を表す RGBA を設定する。
    mat.dcvDiffuse.r = (D3DVALUE)0.5;
    mat.dcvDiffuse.g = (D3DVALUE)0.0;
    mat.dcvDiffuse.b = (D3DVALUE)0.5;
    mat.dcvDiffuse.a = (D3DVALUE)1.0;

// アンビエント反射を表す RGBA を設定する。
    mat.dcvAmbient.r = (D3DVALUE)0.5;
    mat.dcvAmbient.g = (D3DVALUE)0.0;
    mat.dcvAmbient.b = (D3DVALUE)0.5;
    mat.dcvAmbient.a = (D3DVALUE)1.0;

// スペキュラ ハイライトの色とシャープさを設定する。
    mat.dcvSpecular.r = (D3DVALUE)1.0;
    mat.dcvSpecular.g = (D3DVALUE)1.0;
    mat.dcvSpecular.b = (D3DVALUE)1.0;
    mat.dcvSpecular.a = (D3DVALUE)1.0;
    mat.dvPower = (float)50.0;

D3DMATERIAL7 構造体を用意したら、レンダリング デバイスの IDirect3DDevice7::SetMaterial メソッドを呼び出してこの構造体を適用する。このメソッドには、用意した D3DMATERIAL7 構造体のアドレスを唯一のパラメータとして指定する。デバイスのマテリアル プロパティの更新が必要なときは、新しい情報で SetMaterial を呼び出すことができる。次の例は、以上の処理をコードで示す。

// このコードでは、このトピックの前の例で mat 変数に対して定義した
// マテリアル プロパティを使用する。lpd3dDev は、IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。
HRESULT hr;
hr = lpd3dDev->SetMaterial(&mat);
if(FAILED(hr))
    {
// エラー処理コード
    }
[Visual Basic]

Visual Basic の場合、システムで使用するマテリアル プロパティを設定するには、D3DMATERIAL7 型を用意し、次に Direct3DDevice7.SetMaterial メソッドを呼び出す。

D3DMATERIAL7 型を用意するには、この型にプロパティ情報を設定して、レンダリングでの希望のエフェクトを作成する。次のコードは、白色のスペキュラ ハイライトがある、紫色のマテリアル用の D3DMATERIAL7 型を設定する。

Dim mat As D3DMATERIAL7

' ディフューズ反射を表す RGBA を設定する。
mat.diffuse.r = 0.5
mat.diffuse.g = 0#
mat.diffuse.b = 0.5
mat.diffuse.a = 1#

' アンビエント反射を表す RGBA を設定する。
mat.ambient.r = 0.5
mat.ambient.g = 0#
mat.ambient.b = 0.5
mat.ambient.a = 1#

' スペキュラ ハイライトの色とシャープさを設定する。
mat.specular.r = 1#
mat.specular.g = 1#
mat.specular.b = 1#
mat.specular.a = 1#
mat.power = 50#

D3DMATERIAL7 型を用意したら、レンダリング デバイスの Direct3DDevice7.SetMaterial メソッドを呼び出してこの構造体を適用する。このメソッドには、用意した D3DMATERIAL7 型のアドレスを唯一のパラメータとして指定する。デバイスのマテリアル プロパティの更新が必要なときは、新しい情報で SetMaterial を呼び出すことができる。次の例は、以上の処理をコードで示す。

' このコードでは、このトピックの前の例で mat 変数に対して定義した
' マテリアル プロパティを使用する。d3dDev には、Direct3DDevice7 オブジェクトへの
' 有効な参照が格納されているとする。
On Local Error Resume Next

Call d3dDev.SetMaterial(mat)
If Err.Number <> DD_OK Then
' エラー処理コード
End If


アルファ ブレンディング ステート

色のアルファ値は透明度を制御する。アルファ ブレンディングを有効にすると、あるサーフェスの色、マテリアル、およびテクスチャを透明度とブレンドして、ほかのサーフェスに適用できる。詳細については、「アルファ テクスチャ ブレンディング」および「マルチパス テクスチャ ブレンディング」を参照すること。

[C++]

C++ で記述されたアプリケーションでは、D3DRENDERSTATE_ALPHABLENDENABLE レンダリング ステートを使用してアルファ透明ブレンディングを有効にする。Direct3D API では、さまざまな種類のアルファ ブレンディングを使用できる。ただし、ユーザーの 3D ハードウェアが Direct3D で可能なブレンディング ステートのすべてに対応するとは限らないので注意が必要である。

実行されるアルファ ブレンディングの種類は、D3DRENDERSTATE_SRCBLEND および D3DRENDERSTATE_DESTBLEND レンダリング ステートによって異なる。転送元および転送先のブレンディング ステートはペアで使用する。次のコードは、転送元のブレンディング ステートを D3DBLEND_SRCCOLOR に設定し、転送先のブレンディング ステートを D3DBLEND_INVSRCCOLOR に設定する方法を示す。

// このコードでは、lpD3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。

// 転送元のブレンディング ステートを設定する。
lpD3DDevice->SetRenderState(D3DRENDERSTATE_SRCBLEND,
                            D3DBLEND_SRCCOLOR);

// 転送先のブレンディング ステートを設定する。
lpD3DDevice->SetRenderState(D3DRENDERSTATE_DESTBLEND,
                            D3DBLEND_INVSRCCOLOR);

この呼び出しの結果、Direct3D は、転送元の色 (現在位置座標でのレンダリング ターゲットのプリミティブの色) および転送先の色 (フレーム バッファ内の現在位置座標の色) の間で線形ブレンディングを実行する。この処理によって、色合いを持つガラスのような外観になる。転送先オブジェクトの色の一部は、転送元オブジェクトから伝わったように見える。その他の部分は吸収されたように見える。

転送元および転送先のブレンディング ステートの設定を変えると、霧やほこりの中でオブジェクトが輝いているような外観になる。たとえば、アプリケーションで、炎、電磁力界、プラズマ光線、またはぼんやりした中で輝いているようなオブジェクトをモデリングする場合、転送元および転送先のブレンディング ステートを D3DBLEND_ONE に設定する。

また、アルファ ブレンディングは 3D シーンのライティングを制御する。これはライト マッピングと呼ばれることもある。転送元のブレンディング ステートを D3DBLEND_ZERO に設定し、転送先のブレンディング ステートを D3DBLEND_SRCALPHA に設定すると、転送元のアルファ情報に従ってシーンが暗くなる。転送元のプリミティブは、フレーム バッファの内容をスケーリングするライト マップとして使用され、必要に応じてシーンを暗くする。これによって、モノクロのライト マッピングが生成される。

カラー ライト マッピングは、転送元のアルファ ブレンディング ステートを D3DBLEND_ZERO に設定し、転送先のブレンディング ステートを D3DBLEND_SRCCOLOR に設定することで実現できる。

Direct3D デバイスがディスプレイ ハードウェアでサポートされている場合は、アルファ値点描を実行できる。「D3DRENDERSTATE_STIPPLEDALPHA」を参照すること。アプリケーションで RGB またはランプ ソフトウェア エミュレーション デバイスを作成する場合、Direct3D はこの列挙値を無視する。

[Visual Basic]

Visual Basic アプリケーションでは、D3DRENDERSTATE_ALPHABLENDENABLE レンダリング ステートを使用してアルファ透明ブレンディングを有効にする。Direct3D API では、さまざまな種類のアルファ ブレンディングを使用できる。ただし、ユーザーの 3D ハードウェアが Direct3D で可能なブレンディング ステートのすべてに対応するとは限らないので注意が必要である。

実行されるアルファ ブレンディングの種類は、D3DRENDERSTATE_SRCBLEND および D3DRENDERSTATE_DESTBLEND レンダリング ステートによって異なる。転送元および転送先のブレンディング ステートはペアで使用する。次のコードは、転送元のブレンディング ステートを D3DBLEND_SRCCOLOR に設定し、転送先のブレンディング ステートを D3DBLEND_INVSRCCOLOR に設定する方法を示す。

' このコードでは、D3DDevice に Direct3DDevice7 オブジェクトへの
' 参照が格納されているとする。

' 転送元のブレンディング ステートを設定する。
Call D3DDevice.SetRenderState(D3DRENDERSTATE_SRCBLEND, _
                              D3DBLEND_SRCCOLOR);

' 転送先のブレンディング ステートを設定する。
Call D3DDevice.SetRenderState(D3DRENDERSTATE_DESTBLEND, _
                              D3DBLEND_INVSRCCOLOR);

この呼び出しの結果、Direct3D は、転送元の色 (現在位置座標でのレンダリング ターゲットのプリミティブの色) および転送先の色 (フレーム バッファ内の現在位置座標の色) の間で線形ブレンディングを実行する。この処理によって、色合いを持つガラスのような外観になる。転送先オブジェクトの色の一部は、転送元オブジェクトから伝わったように見える。その他の部分は吸収されたように見える。

転送元および転送先のブレンディング ステートの設定を変えると、霧やほこりの中でオブジェクトが輝いているような外観になる。たとえば、アプリケーションで、炎、電磁力界、プラズマ光線、またはぼんやりした中で輝いているようなオブジェクトをモデリングする場合、転送元および転送先のブレンディング ステートを D3DBLEND_ONE に設定する。

また、アルファ ブレンディングは 3D シーンのライティングを制御する。これはライト マッピングと呼ばれることもある。転送元のブレンディング ステートを D3DBLEND_ZERO に設定し、転送先のブレンディング ステートを D3DBLEND_SRCALPHA に設定すると、転送元のアルファ情報に従ってシーンが暗くなる。転送元のプリミティブは、フレーム バッファの内容をスケーリングするライト マップとして使用され、必要に応じてシーンを暗くする。これによって、モノクロのライト マッピングが生成される。

カラー ライト マッピングは、転送元のアルファ ブレンディング ステートを D3DBLEND_ZERO に設定し、転送先のブレンディング ステートを D3DBLEND_SRCCOLOR に設定することで実現できる。

Direct3D デバイスがディスプレイ ハードウェアでサポートしている場合は、アルファ値点描を実行できる。「D3DRENDERSTATE_STIPPLEDALPHA」を参照すること。アプリケーションで RGB またはランプ ソフトウェア エミュレーション デバイスを作成する場合、Direct3D はこの列挙値を無視する。


点リスト

Platform SDK: DirectX

点リスト

点リストとは、個々の点としてレンダリングされる頂点の集合である。アプリケーションでは、星のフィールドまたはポリゴンのサーフェス上の点線に、3D シーンの点リストを使用できる。アプリケーションでは、頂点の配列に値を設定することで点リストを作成する。

[C++]

次の C++ コードは、点リストを作成する処理を示す。

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0),D3DVECTOR(0,0,-1),0,0);

IDirect3DDevice7::DrawPrimitive メソッドを使用して点リストをレンダリングする。次のコードは、IDirect3DDevice7::DrawPrimitive を使用して、上の例の点リストを描画する方法を示す。IDirect3DDevice7::DrawPrimitive の呼び出しは、IDirect3DDevice7::BeginScene と IDirect3DDevice7::EndScene の間で行う必要がある。

HRESULT hResult;
// このコードでは、lpDirect3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_POINTLIST,
                                     D3DFVF_VERTEX,
                                     lpVerts,
                                     TOTAL_VERTS,
                                     D3DDP_WAIT);
[Visual Basic]

Visual Basic で記述するアプリケーションでは、次のコードで示すように、頂点の配列に値を設定して点リストを作成する。

' このコードでは、dx は DirectX7 オブジェクトへの
' 有効な参照であるとする。
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

Direct3DDevice7.DrawPrimitive メソッドを使用して点リストをレンダリングする。次のコードは、Direct3DDevice7.DrawPrimitive を使用して、上の例の点リストを描画する方法を示す。Direct3DDevice7.DrawPrimitive の呼び出しは、Direct3DDevice7.BeginScene と Direct3DDevice7.EndScene の間で行う必要がある。

' このコードでは、d3ddev は Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
Call d3ddev.DrawPrimitive(D3DPT_POINTLIST, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
                          D3DDP_WAIT)

If Err.Number <> DD_OK Then
' エラー処理コード
End If

次の図は、結果として描画される点を示す。

点リストにはマテリアルとテクスチャを適用できる。マテリアルまたはテクスチャの色は、描画された点でのみ表示され、点と点の間には表示されない。


カラー キーイング ステート

カラー キーを設定すると、Direct3D はキー カラーを透明色として扱う。Direct3D では、DDSD_CKSRCBLT フラグを使用して作成されたテクスチャをプリミティブに適用するとき、キー カラーと一致するテクセルはすべてプリミティブではレンダリングされない。DDSD_CKSRCBLT フラグを使用しないで作成されたテクスチャの場合は、その中にカラー キーが含まれていてもカラー キー エフェクトが表示されないことに注意する。

[C++]

C++ アプリケーションでは、カラー キーを使用するサーフェス (この場合レンダリング ターゲット サーフェス) に対して、IDirectDrawSurface7::SetColorKey メソッドでカラー キーを設定する。ただし、IDirect3DDevice7::SetRenderState メソッドを呼び出してカラー キーのオン/オフを切り替えることができる。第 1 パラメータを D3DRENDERSTATE_COLORKEYENABLE に設定する。カラー キーを有効にするには第 2 パラメータを TRUE に設定し、無効にするには FALSE に設定する。デフォルトは FALSE である。

// このコードでは、lpD3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。

// カラー キーを無効にする。
lpD3DDevice->SetRenderState(D3DRENDERSTATE_COLORKEYENABLE,
                            FALSE);
[Visual Basic]

Visual Basic で記述されたアプリケーションでは、カラー キーを使用するサーフェス (この場合レンダリング ターゲット サーフェス) に対して、DirectDrawSurface7.SetColorKey メソッドでカラー キーを設定する。ただし、Direct3DDevice7::SetRenderState メソッドを呼び出してカラー キーのオン/オフを切り替えることができる。第 1 パラメータを D3DRENDERSTATE_COLORKEYENABLE に設定する。カラー キーを有効にするには第 2 パラメータを True に設定し、無効にするには False に設定する。デフォルトは False である。

' このコードでは、D3DDevice に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納されているとする。

' カラー キーを無効にする。
Call D3DDevice.SetRenderState(D3DRENDERSTATE_COLORKEYENABLE, _
                              FALSE)


カレント テクスチャ

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、サーフェス オブジェクトおよび Direct3DDevice7.SetTexture メソッドを使用してカレント テクスチャをデバイスに割り当てる。

[C++]

D3DRENDERSTATE_TEXTUREHANDLE レンダリング ステートは現在は使用されていない。アプリケーションでは、IDirect3DDevice7::SetTexture メソッドを呼び出してカレント テクスチャを設定する。


バンプ マッピングのサポートの検出

[C++]

Direct3D デバイスが D3DTOP_BUMPENVMAP または D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディング処理のいずれかをサポートしている場合、そのデバイスではバンプ マッピングを実行できる。また、アプリケーションではデバイス機能を調べることで、そのアプリケーションで適切なブレンディング ステージ数 (通常は 3 つ以上) がサポートされ、少なくとも 1 つのバンプ マッピング ピクセル フォーマットが公開されていることを確認する必要がある。

次のコードは、指定された条件によってデバイス機能を調べて、現在のデバイスでのバンプ マッピングのサポートを検出する。

BOOL SupportsBumpMapping()
{
DDPIXELFORMAT ddpfBumpMap;
D3DDEVICEDESC7 d3dDevDesc;
ZeroMemory( &d3dDevDesc, sizeof(d3dDevDesc) );

// デバイス機能を取得する。
g_pd3dDevice->GetCaps( &d3dDevDesc );

// このデバイスが 2 つのバンプ マッピング ブレンド処理をサポートしているかどうか。
DWORD dwBumpOps = d3dDevDesc.dwTextureOpCaps &
(D3DTEXOPCAPS_BUMPENVMAP | D3DTEXOPCAPS_BUMPENVMAPLUMINANCE);
if ( 0 == dwBumpOps)
return FALSE;

// このデバイスが最大 3 つのブレンディング ステージをサポートしているかどうか。
if( d3dDevDesc.wMaxTextureBlendStages < 3)
return FALSE;

    //
// 有効なバンプ マップ ピクセル フォーマットがあるかどうかを調べる。
    //

// 有効なフォーマットが検出された場合、
// コールバック関数によって g_bFoundBumpFormat グローバル変数が TRUE に設定される。
g_bFoundBumpFormat = FALSE;

g_pd3dDevice->EnumTextureFormats(TextureCallback, (LPVOID) &ddpfBumpMap);
if( FALSE == g_bFoundBumpFormat )
return FALSE;

// 現在 ddpfBumpMap にあるピクセル フォーマットは、
// 有効であることが保証されているサーフェス フォーマットを作成するために使用できる。
return TRUE;
}

次のコードは、コールバック関数が IDirect3DDevice7::EnumTextureFormats メソッドに渡る。

HRESULT CALLBACK TextureCallback( DDPIXELFORMAT* pddpf, VOID* pddpfOut)
{
// 最初に列挙されている DuDv フォーマットを取得する。
if( DDPF_BUMPDUDV == pddpf->dwFlags ){
// 後でサーフェスを作成するときに使用できるように、
// フォーマットを pddpfOut の変数にコピーする。
memcpy( pddpfOut, (LPVOID)pddpf, sizeof(DDPIXELFORMAT) );

// 成功を知らせるグローバル フラグを設定する。
g_bFoundBumpFormat = TRUE;
return D3DENUMRET_CANCEL;
    }

return D3DENUMRET_OK;
}
[Visual Basic]

Direct3D デバイスが D3DTOP_BUMPENVMAP または D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディングのいずれかをサポートしている場合、そのデバイスではバンプ マッピングを実行できる。また、アプリケーションではデバイス機能を調べることで、そのアプリケーションで適切なブレンディング ステージ数 (通常は 3 つ以上) がサポートされ、少なくとも 1 つのバンプ マッピング ピクセル フォーマットが公開されていることを確認する必要がある。

次のコードは、指定された条件によってデバイス機能を調べて、現在のデバイスでのバンプ マッピングのサポートを検出する。

Function SupportsBumpMapping() As Boolean
Dim ddpfBumpMap As DDPIXELFORMAT
Dim d3dDevDesc As D3DDEVICEDESC7

SupportsBumpMapping = True

' デバイス機能を取得する。
Call g_d3dDevice.GetCaps(d3dDevDesc)

' このデバイスが 2 つのバンプ マッピング ブレンド処理をサポートしているかどうか。
Dim lBumpOps As Long
lBumpOps = (d3dDevDesc.lTextureOpCaps And _
(D3DTEXOPCAPS_BUMPENVMAP Or D3DTEXOPCAPS_BUMPENVMAPLUMINANCE))

If lBumpOps = 0 Then SupportsBumpMapping = False

' このデバイスが最大 3 つのブレンディング ステージをサポートしているかどうか。
If d3dDevDesc.nMaxTextureBlendStages < 3 Then SupportsBumpMapping = False

    '
' 有効なバンプ マップ ピクセル フォーマットがあるかどうかを調べる。
    '
Dim BumpEnum As Direct3DEnumPixelFormats
Set BumpEnum = g_d3dDevice.GetTextureFormatsEnum

Dim iLoop As Integer
For iLoop = 0 To BumpEnum.GetCount
Call BumpEnum.GetItem(iLoop, ddpfBumpMap)

' フォーマットが検出されたら、ループを停止する。
If ddpfBumpMap.lFlags And DDPF_BUMPDUDV Then Exit For
Next iLoop

If Not (ddpfBumpMap.lFlags And DDPF_BUMPDUDV) Then
SupportsBumpMapping = False
End If
End Function


三角形ストリップ

Platform SDK: DirectX

三角形ストリップ

三角形ストリップとは、一連の結合された三角形である。三角形は結合されているため、各三角形に対して 3 つの頂点すべてをアプリケーションで繰り返し指定する必要はない。たとえば、次の三角形ストリップを定義する場合、7 つの頂点のみ必要である。

システムでは、頂点の v1、v2、v3 を使用して最初の三角形を、v2、v4、v3 を使用して 2 番目の三角形を、v3、v4、v5 を使用して 3 番目の三角形を、v4、v6、v5 を使用して 4 番目の三角形を、という手順で描画していく。2 番目と 4 番目の三角形の頂点が順序通りでないことに注意する。これは、すべての三角形が時計回りの方向に描画されることを保証するために必要である。

3D シーンのほとんどのオブジェクトは三角形ストリップで構成されている。これは、三角形ストリップを使用して複雑なオブジェクトを指定すると、メモリを効率的に利用して処理時間を短縮できるからである。三角形ストリップは、頂点の配列に値を設定して作成する。

[C++]

次の C++ コードでは、三角形ストリップとして使用するために頂点を配列に格納する。

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0),D3DVECTOR(0,0,-1),0,0);

この後、IDirect3DDevice7::DrawPrimitive メソッドを使用して三角形ストリップをレンダリングできる。次のコードは、IDirect3DDevice7::DrawPrimitive を使用して、上の例の三角形ストリップを描画する方法を示す。IDirect3DDevice7::DrawPrimitive の呼び出しは、IDirect3DDevice7::BeginScene と IDirect3DDevice7::EndScene の間で行う必要がある。

HRESULT hResult;
// このコードでは、lpDirect3DDevice7 は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_TRIANGLESTRIP,
                                      D3DFVF_VERTEX,
                                      lpVerts,
                                      TOTAL_VERTS,
                                      D3DDP_WAIT);
[Visual Basic]

Visual Basic で記述されたアプリケーションでは、次のようなコードで三角形ストリップを設定できる。

' このコードでは、dx は DirectX7 オブジェクトへの
' 有効な参照であるとする。
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

この後、Direct3DDevice7.DrawPrimitive メソッドを使用して三角形ストリップをレンダリングできる。次のコードは、Direct3DDevice7.DrawPrimitive を使用して、上の例の三角形ストリップを描画する方法を示す。Direct3DDevice7.DrawPrimitive の呼び出しは、Direct3DDevice7.BeginScene と Direct3DDevice7.EndScene の間で行う必要がある。

' このコードでは、d3ddev が Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
Call d3ddev.DrawPrimitive(D3DPT_TRIANGLESTRIP, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
D3DDP_WAIT);

If Err.Number <> DD_OK Then
' エラー処理コード
End If

次の図は、結果として描画される三角形ストリップを示す。


テクスチャ アドレッシング モードとテクスチャ ラッピング

Direct3D によって、アプリケーションはテクスチャ ラッピングを実行できる。ただし、テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定することと、テクスチャ ラッピングを実行することは同じではないので注意が必要である。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定すると、現在のプリミティブに適用されているテクスチャのコピーが複数できる。一方、テクスチャ ラッピングを有効にすると、テクスチャ処理したポリゴンに対するシステムのラスタ化の方法が変更される。詳細については、「テクスチャ ラッピング」を参照すること。

テクスチャ ラッピングを有効にすると、効率的に [0.0, 1.0] の範囲外のテクスチャ座標を無効にできる。この場合、この範囲外にあるテクスチャ座標などのラスタ化の動作は定義されない。テクスチャ ラッピングを有効にすると、テクスチャ アドレッシング モードは使用されない。テクスチャ ラッピングが有効になっているときは、0.0 未満または 1.0 を超えるテクスチャ座標をアプリケーションで指定しないように注意すること。


キューブ環境マップのミップマップ化

キューブ環境マップはミップマップ化できる。DDSCAPS_MIPMAP を含めると、アタッチされたミップマップ サーフェスのある各サーフェスが作成される。これらのサーフェスの形状としては、次のようなものがある。

[C++]

ミップマップ化キューブ環境マップを作成するアプリケーションで各サーフェスにアクセスするには、IDirectDrawSurface7::GetAttachedSurface メソッドを呼び出し、"DDSCAPS2_CUBEMAP_" フラグで始まるフラグのいずれかを渡して対応するサーフェスにアクセスする (「キューブ環境マップ サーフェスへのアクセス」で説明する)。次に、そのサーフェスに対して IDirectDrawSurface7::GetAttachedSurface を呼び出し、DDSCAPS_MIPMAP フラグを渡すと、従属ミップマップ レベルを取得できる。

[Visual Basic]

ミップマップ化キューブ環境マップを作成するアプリケーションで各サーフェスにアクセスするには、DirectDrawSurface7.GetAttachedSurface メソッドを呼び出し、"DDSCAPS2_CUBEMAP_" で始まる CONST_DDSURFACECAPS2FLAGS 列挙からのフラグのいずれかを渡して対応するサーフェスにアクセスする (「キューブ環境マップ サーフェスへのアクセス」を説明する)。次に、そのサーフェスに対して DirectDrawSurface7.GetAttachedSurface を呼び出し、DDSCAPS_MIPMAP フラグを渡すと、従属ミップマップ レベルを取得できる。


深度バッファリング ステート

深度バッファリングとは、隠線および隠面を削除する方法である。概要については、「深度バッファとは」を参照すること。デフォルトでは、深度バッファリングは使用されない。

[C++]

C++ アプリケーションでは、D3DZBUFFERTYPE 列挙のメンバのいずれかを使用して新しいステート値を指定することで、D3DRENDERSTATE_ZENABLE レンダリング ステートで深度バッファリング ステートを更新する。

何かの理由で、Direct3D による深度バッファへの書き込みを防止する必要がある場合は、D3DRENDERSTATE_ZWRITEENABLE 列挙値を使用し、IDirect3DDevice7::SetRenderState の呼び出しの第 2 パラメータとして FALSE を指定する。

次のコードは、z バッファリングが有効になるように深度バッファ ステートを設定する方法を示す。

// このコードでは、lpD3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。

// z バッファリングを有効にする。
lpD3DDevice->SetRenderState(D3DRENDERSTATE_ZENABLE,
                            D3DZB_TRUE); // D3DZB_TRUE is the same as TRUE

アプリケーションでは、また、D3DRENDERSTATE_ZFUNC レンダリング ステートを使用して、深度バッファリングの実行時に Direct3D で使用する比較関数を制御できる。

z バイアスとは、互いの深度値が同じであっても、一方のサーフェスを他方のサーフェスより手前に表示する方法である。このテクニックは、さまざまなエフェクトを期待できる。一般的な例として、壁に影を付ける場合を考える。影も壁も深度値は同じである。しかし、どうしても壁に影を付けようとする場合がある。このような場合、影に z バイアスを適用することで、壁の上に影を適切に表示できる (「D3DRENDERSTATE_ZBIAS」を参照すること)。

[Visual Basic]

Visual Basic アプリケーションでは、CONST_D3DZBUFFERTYPE 列挙のメンバのいずれかを使用して新しいステート値を指定することで、D3DRENDERSTATE_ZENABLE レンダリング ステートで深度バッファリング ステートを更新する。

何かの理由で、Direct3D による深度バッファへの書き込みを防止する必要がある場合は、D3DRENDERSTATE_ZWRITEENABLE レンダリング ステートを使用し、Direct3DDevice7::SetRenderState の呼び出しの第 2 パラメータとして D3DZB_FALSE を指定する。

次の Visual Basic コードは、z バッファリングが有効になるように深度バッファ ステートを設定する方法を示す。

' このコードでは、D3DDevice に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納されているとする。

' z バッファリングを有効にする。
Call D3DDevice.SetRenderState(D3DRENDERSTATE_ZENABLE, _
                              D3DZB_TRUE)

アプリケーションでは、また、D3DRENDERSTATE_ZFUNC レンダリング ステートを使用して、深度バッファリングの実行時に Direct3D で使用する比較関数を制御できる。

z バイアスとは、互いの深度値が同じであっても、一方のサーフェスを他方のサーフェスより手前に表示する方法である。このテクニックは、さまざまなエフェクトを期待できる。一般的な例として、壁に影を付ける場合を考える。影も壁も深度値は同じである。しかし、どうしても壁に影を付けようとする場合がある。このような場合、影に z バイアスを適用することで、壁の上に影を適切に表示できる (D3DRENDERSTATE_ZBIAS を参照すること)。


ポイント ライト

ポイント ライトは、シーン内で色と位置座標を持つが、単一の方向は持たない。次の図に示すように、ポイント ライトはすべての方向に均等に光を放つ。

ポイント ライトの例としては電球がある。ポイント ライトは減衰と範囲の影響を受け、頂点ごとにメッシュを照らす。ライティングの実行中、Direct3D は、ワールド空間でのポイント ライトの位置座標とライティングする頂点の座標を使用して、ライトの方向を表すベクトルと光が進んだ距離を取得する。頂点法線に加えて、このベクトルと距離の両方を使用して、サーフェスにどのくらい光が当っているかを計算する。


キューブ環境マップ サーフェスの作成

キューブ環境マップを作成するには、C++ の場合は IDirectDraw7::CreateSurface メソッドを、Visual Basic の場合は DirectDraw7.CreateSurface を呼び出す。キューブ マップは複合サーフェスである。つまり、キューブ マップはアタッチされたサーフェスのセットであり、1 回の呼び出しで DirectDraw によって作成される。個別に作成されたサーフェスは、互いにアタッチしてキューブ環境マップを作成することはできない。キューブ環境マップ テクスチャは矩形でなければならず、その大きさは 2 の累乗である。

[C++]

次のコードは、C++ アプリケーションで単純なキューブ環境マップを作成する方法を示す。

// この例では、pDD 変数は IDirectDraw7 インターフェイスへの
// 有効なポインタである。
DDSURFACEDESC2 ddsd;

ZeroMemory((LPVOID)&ddsd, sizeof(DDSURFACEDESC2));

ddsd.dwSize         = sizeof(DDSURFACEDESC2);
ddsd.dwFlags        = DDSD_CAPS | DDSD_WIDTH |
                      DDSD_HEIGHT | DDSD_PIXELFORMAT;
ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE;

// ピクセル フォーマットを有効なテクスチャ フォーマットに設定する。

// 大きさは任意に指定できるが、2 の累乗でなければならない。
ddsd.dwWidth  = 64;
ddsd.dwHeight = 64;

// 有効なレンダリング ターゲット サーフェスである、システム メモリのキューブ マップ テクスチャの
// 能力を設定する。
ddsd.ddsCaps.dwCaps  = DDSCAPS_COMPLEX | DDSCAPS_3DDEVICE |
DDSCAPS_TEXTURE;
ddsd.ddsCaps.dwCaps2 = DDSCAPS2_CUBEMAP|DDSCAPS2_CUBEMAP_ALLFACES;

LPDIRECTDRAWSURFACE7 pddsCubeMap;

// キューブ マップを作成する。
if( FAILED( pDD->CreateSurface( &ddsd, pddsCubeMap, NULL ) ) )
{
// エラー処理コード
}

注 : キューブ マップのサーフェスに対してレンダリングする場合は、サーフェスを作成するときに定義するサーフェス記述に DDSCAPS_3DDEVICE を含める必要がある。

キューブ マップは管理下のテクスチャにできる。サーフェスを作成するとき、サーフェス能力に DDSCAPS2_TEXTUREMANAGE または DDSCAPS2_TEXTUREMANAGE フラグのいずれかを含めると管理下のテクスチャになる。詳細については、「自動テクスチャ管理」を参照すること。

[Visual Basic]

次のコードは、Visual Basic アプリケーションで単純なキューブ環境マップを作成する方法を示す。

' この例では、dd 変数は DirectDraw7 オブジェクトへの
' 有効な参照である。
On Local Error Resume Next

Dim ddsd As DDSURFACEDESC2

ddsd.lFlags = DDSD_CAPS Or DDSD_WIDTH Or _
DDSD_HEIGHT Or DDSD_PIXELFORMAT

ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE

' ピクセル フォーマットを有効なテクスチャ フォーマットに設定する。

' 大きさは任意に指定できるが、2 の累乗でなければならない。
ddsd.dwWidth = 64:ddsd.dwHeight = 64

' 有効なレンダリング ターゲット サーフェスである、システム メモリのキューブ マップ テクスチャの
' 能力を設定する。
ddsd.ddsCaps.dwCaps = DDSCAPS_COMPLEX Or DDSCAPS_3DDEVICE Or _
DDSCAPS_TEXTURE
ddsd.ddsCaps.dwCaps2 = DDSCAPS2_CUBEMAP Or DDSCAPS2_CUBEMAP_ALLFACES

Dim ddsCubeMap As DirectDrawSurface7

' キューブ マップを作成する。
Set ddsCubeMap = dd.CreateSurface(ddsd)

If Err.Number <> DD_OK Then
' エラー処理コード
End If

注 : キューブ マップのサーフェスに対してレンダリングする場合は、サーフェスを作成するときに定義するサーフェス記述に DDSCAPS_3DDEVICE を含める必要がある。

キューブ マップは管理下のテクスチャにできる。サーフェスを作成するとき、サーフェス能力に DDSCAPS2_TEXTUREMANAGE または DDSCAPS2_TEXTUREMANAGE フラグのいずれかを含めると管理下のテクスチャになる。詳細については、「自動テクスチャ管理」を参照すること。


ラップ テクスチャ アドレッシング モードについて

[C++]

D3DTEXTUREADDRESS 列挙型の D3DTADDRESS_WRAP メンバで指定する "ラップ" テクスチャ アドレッシング モードでは、Direct3D はすべての整数接合でテクスチャを繰り返し適用する。たとえば、プログラムで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) を指定する場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定すると、u および v の両方向でテクスチャが 3 回適用される。

[Visual Basic]

CONST_D3DTEXTUREADDRESS 列挙の D3DTADDRESS_WRAP メンバで指定する "ラップ" テクスチャ アドレッシング モードでは、Direct3D はすべての整数接合でテクスチャを繰り返し適用する。たとえば、プログラムで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) を指定する場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定すると、u および v の両方向でテクスチャが 3 回適用される。

次の図にこれを示す。

このテクスチャ アドレッシング モードのエフェクトは、"ミラー" モードのエフェクトに類似する部分がある。詳細については、「ミラー テクスチャ アドレッシング モードについて」を参照すること。


ミップマップとは

ミップマップとは連続したテクスチャで、各テクスチャは同じ画像を徐々に低解像度にしたものである。ミップマップでの各画像の高さと幅、つまりレベルは、直前のレベルよりも 2 の累乗だけ小さい。ミップマップは正方形である必要はない。

視点に近いオブジェクトには、高解像度ミップマップ画像が使用される。オブジェクトが視点から遠ざかるに従って、低解像度のミップマップ画像が使用される。ミップマップ処理により、レンダリングしたテクスチャの品質が向上するが、使用するメモリは増加する。

Direct3D では、ミップマップはアタッチされたサーフェスのチェーンとして表される。このチェーンの先頭には最高解像度のテクスチャがあり、その後には次のミップマップ レベルのテクスチャが続く。このレベルの後には次のレベルのミップマップが続く、という順に最低解像度のミップマップになるまで続いていく。

次の図はこの例を示す。ビットマップ テクスチャ セットは、一人用ゲームの 3D コンテナの側面にある記号を表している。ミップマップとして作成すると、最高解像度のテクスチャがこのセットの先頭に来る。このミップマップ セットの連続する各テクスチャは、高さと幅が 2 の累乗ずつ小さくなっていく。この場合は、最高解像度のミップマップは、256 x 256 ピクセルである。次のテクスチャは 128x128 である。最後のテクスチャは 64x64 である。

この記号は、可視範囲内の最大距離にある。この記号から遠く離れた位置座標からゲームを開始する場合は、ミップマップ チェーンの中で最小の 64x64 テクスチャが表示される。

プレーヤーの視点がこの記号に近づくにつれて、徐々に高解像度のテクスチャが使用される。

最高解像度のテクスチャが使用されるのは、プレーヤーの視点がこの記号に最も近づいたときである。

これは、テクスチャの遠近エフェクトをシミュレートする方法の中ではオーバーヘッドが低い方法である。1 つのテクスチャを多くの解像度でレンダリングするよりも、さまざまな解像度で複数のテクスチャを使用する方が高速である。

Direct3D では、ミップマップ セットの中でどのテクスチャが最も希望出力に近い解像度であるかを評価し、ピクセルをそのテクセル空間にマッピングできる。最終的な画像の解像度がミップマップ セット内のテクスチャ間にある場合、Direct3D では両方のミップマップのテクセルを調べ、そのカラー値をブレンドする。

アプリケーションでミップマップを使用する場合は、ミップマップ セットを作成する必要がある。詳細については、「ミップマップ セットの作成」を参照すること。アプリケーションでは、ミップマップ セットをカレント テクスチャ セットの最初のテクスチャとして選択して、ミップマップを適用する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

次に、Direct3D でテクセルのサンプリングに使用するフィルタリング方法を設定しなければならない。最も処理が速いミップマップ フィルタリングは、Direct3D で最も近いテクセルを選択する方法である。これ選択するには、D3DTFP_POINT 列挙値を使用する。Direct3D では、D3DTFP_LINEAR 列挙値を使用すると、より高品質なフィルタリング結果が得られる。このフィルタリングでは、最も近いミップマップが選択され、次に現在のピクセルがマッピングされる、テクスチャ内の位置座標の周辺テクセルの加重平均が計算される。


テクスチャ ラッピング ステート

[C++]

注 : u- および v- ラッピング レンダリング ステートの D3DRENDERSTATE_WRAPU および D3DRENDERSTATE_WRAPV は、現在は使用されていない。これらは、D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 までのレンダリング ステートに置き換えられている。

これらのラッピング レンダリング ステートは、デバイスのマルチ テクスチャ カスケードの各種テクスチャに対して、u- および v- ラッピングを有効または無効にする。これらのレンダリング ステートを D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 フラグの組み合わせに設定して、テクスチャの第 1、第 2、第 3、および第 4 方向でのラッピングを有効にする。ゼロを設定すると、ラッピングはすべて無効になる。デフォルトでは、テクスチャ ラッピングは、すべてのテクスチャ ステージの全方向で無効になっている。概要については、「テクスチャ ラッピング」を参照すること。

D3DRENDERSTATE_WRAPU および D3DRENDERSTATE_WRAPV は新しいレンダリング ステートに置き換えられているが、IDirect3DDevice7 インターフェイスではこれらは認識される。これらの旧レンダリング ステートを IDirect3DDevice7::SetRenderState に渡すと、最初のテクスチャ ステージ (ステージ 0) の u- および v- テクスチャ ラッピングが影響を受ける。

[Visual Basic]

D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 レンダリング ステートは、デバイスのマルチテクスチャ カスケードの各種テクスチャに対して、テクスチャ ラッピングを制御する。これらのレンダリング ステートを、CONST_D3D 列挙からの D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 の値の組み合わせに設定して、テクスチャの第 1、第 2、第 3、および第 4 方向でのラッピングを有効にする。ゼロを設定すると、ラッピングはすべて無効になる。デフォルトでは、テクスチャ ラッピングは、すべてのテクスチャ ステージの全方向で無効になっている。概要については、「テクスチャ ラッピング」を参照すること。


テクスチャ座標の自動生成

Direct3D では、頂点に対してテクスチャ座標を自動的に生成できる。このセクションでは、システムが提供する機能とその使用方法について詳しく説明する。説明するトピックは次のとおりである。

  • テクスチャ座標の自動生成について
  • テクスチャ座標の自動生成の構成


キューブ環境マップのテクスチャ座標

[C++]

キューブ環境マップを指し示すテクスチャ座標は、標準テクスチャの適用時に使用する単純な u、v スタイルの座標とは異なる。実際、キューブ環境マップではテクスチャ座標をまったく使用しない。テクスチャ座標セットの代わりに、キューブ環境マップでは 3D ベクトルが必要である。適切な頂点フォーマットを指定することが大切である。また、システムにアプリケーションで使用するテクスチャ座標のセット数を知らせるほかにも、各セット内の要素数についての情報を知らせる必要がある。Direct3D は、これを行うためにマクロのD3DFVF_TEXCOORDSIZEn セットを用意している。これらのマクロにはパラメータが 1 つあり、サイズが記述されるテクスチャ座標セットのインデックスを識別する。3D ベクトルの場合は、D3DFVF_TEXCOORDSIZE3 マクロで作成するビット パターンを含める。次のコードは、このマクロの使用方法を示す。

// 頂点の柔軟な頂点フォーマット記述子を作成する。
// これには、位置座標、法線、および
// 3D テクスチャ座標のセットが 1 つ含まれる。
DWORD dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL |
D3DFVF_TEX1 | D3DFVF_TEXCOORDSIZE3(0);

ディフューズ ライト マッピングなどの場合には、ベクトルにカメラ空間の頂点法線を使用する。スペキュラ環境マッピングなどの場合には、反射ベクトルを使用する (トランスフォーム済み頂点法線については広く理解されているため、ここでは反射ベクトルの計算について詳しく説明する)。

独自に反射ベクトルを計算するには、各頂点の位置座標と、ビューポートからその頂点へのベクトルを知っている必要がある。Direct3D ではジオメトリの反射ベクトルを自動的に計算できる。この機能を使用すれば、メモリを節約できる (環境マップのテクスチャ座標を含める必要がない)。つまり、帯域幅が減少し、TnLHAL デバイスの場合は、アプリケーションで独自に計算するよりもはるかに速く計算を実行できる。この機能を利用するには、キューブ環境マップを含むテクスチャ ステージにおいて、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを、D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグの組み合わせとテクスチャ座標セットのインデックスに設定するだけである (ディフューズ ライト マッピングの場合などには、D3DTSS_TCI_CAMERASPACENORMAL フラグを使用して、システムにカメラ空間のトランスフォーム済み頂点法線をテクスチャのアドレッシング ベクトルとして使用することを知らせることができる)。インデックスは、システムがテクスチャのラッピング モードを決定するためにのみ使用する。

次のコードは、この値の使用方法を示す。

// pd3dDevice 変数は、IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。

// ステージ 2 に対してテクスチャ座標を自動生成する。
// ここでは、ステージ 2 にキューブ マップが割り当てられているとする
// (インデックス 1 のテクスチャ座標セットからのラップ モードを使用する)。
pd3dDevice->SetTextureStageState( 2, D3DTSS_TEXCOORDINDEX,
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR | 1);

自動テクスチャ座標生成を有効にすると、2 つの公式のいずれかを使用して各頂点の反射ベクトルが計算される。D3DRENDERSTATE_LOCALVIEWER レンダリング ステートを TRUE に設定すると、次の公式が使用される。

この公式では、R は計算する反射ベクトル、E は位置座標から視点までの正規化されたベクトル、N はカメラ空間の頂点法線である。

D3DRENDERSTATE_LOCALVIEWER レンダリング ステートを FALSE に設定すると、次の公式が使用される。

この公式では、R および N 要素については前の公式と同じである。Nz 要素は頂点法線のワールド空間 z、I は無限大距離にあるビューポートのベクトル (0,0,1) である。システムでは、いずれかの公式で求めた反射ベクトルを使用して、キューブ マップの適切なサーフェスを選択および処理する。

注 : ほとんどの場合、アプリケーションでは頂点法線の自動正規化を有効にする必要がある。これを有効にするには、D3DRENDERSTATE_NORMALIZENORMALS を TRUE に設定する。このレンダリング ステートを有効にしていない場合、環境マップの外観が期待とは大きく異なるものになる。

[Visual Basic]

キューブ環境マップを指し示すテクスチャ座標は、標準テクスチャの適用時に使用する単純な u、v スタイルの座標とは異なる。実際、キューブ環境マップではテクスチャ座標をまったく使用しない。テクスチャ座標セットの代わりに、キューブ環境マップでは 3D ベクトルが必要である。適切な頂点フォーマットを指定することが大切である。また、システムにアプリケーションで使用するテクスチャ座標のセット数を知らせるほかにも、各セット内の要素数についての情報を知らせる必要がある。Direct3D は、これを行うためにヘルパー関数の D3DFVF_TEXCOORDSIZEn セットを Math.bas ソース ファイルに用意している (Math.bas ファイルはこの SDK に付属している)。これらのヘルパー関数にはパラメータが 1 つあり、サイズが記述されるテクスチャ座標セットのインデックスを識別する。3D ベクトルの場合は、D3DFVF_TEXCOORDSIZE3 ヘルパー関数で作成するビット パターンを含める。次のコードは、この関数の使用方法を示す。

' 頂点の柔軟な頂点フォーマット記述子を作成する。
' これには、位置座標、法線、および
' 3D テクスチャ座標のセットが 1 つ含まれる。
Dim lFVF As Long
lFVF = D3DFVF_XYZ Or D3DFVF_NORMAL Or
D3DFVF_TEX1 Or D3DFVF_TEXCOORDSIZE3(0)

ディフューズ ライト マッピングなどの場合には、ベクトルにカメラ空間の頂点法線を使用する。スペキュラ環境マッピングなどの場合には、反射ベクトルを使用する (トランスフォーム済み頂点法線については広く理解されているため、ここでは反射ベクトルの計算について詳しく説明する)。

独自に反射ベクトルを計算するには、各頂点の位置座標と、ビューポートからその頂点へのベクトルを知っている必要がある。Direct3D ではジオメトリの反射ベクトルを自動的に計算できる。この機能を使用すれば、メモリを節約できる (環境マップのテクスチャ座標を含める必要がない)。つまり、帯域幅が減少し、TnLHAL デバイスの場合は、アプリケーションで独自に計算するよりもはるかに速く計算を実行できる。この機能を利用するには、キューブ環境マップを含むテクスチャ ステージにおいて、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを、D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグの組み合わせとテクスチャ座標セットのインデックスに設定するだけである (ディフューズ ライト マッピングの場合などには、D3DTSS_TCI_CAMERASPACENORMAL フラグを使用して、システムにカメラ空間のトランスフォーム済み頂点法線をテクスチャのアドレッシング ベクトルとして使用することを知らせることができる)。インデックスは、システムがテクスチャのラッピング モードを決定するためにのみ使用する。

次のコードは、この値の使用方法を示す。

' pd3dDevice 変数は、Direct3DDevice7 オブジェクトへの
' 有効な参照である。

' ステージ 2 に対してテクスチャ座標を自動生成する。
' ここでは、ステージ 2 にキューブ マップが割り当てられているとする
' (インデックス 1 のテクスチャ座標セットからのラップ モードを使用する)
Call d3dDevice.SetTextureStageState(2, D3DTSS_TEXCOORDINDEX,
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR Or 1)

自動テクスチャ座標生成を有効にすると、2 つの公式のいずれかを使用して各頂点の反射ベクトルが計算される。D3DRENDERSTATE_LOCALVIEWER レンダリング ステートを True に設定すると、次の公式が使用される。

この公式では、R は計算する反射ベクトル、E は位置座標から視点までの正規化されたベクトル、N はカメラ空間の頂点法線である。

D3DRENDERSTATE_LOCALVIEWER レンダリング ステートを False に設定すると、次の公式が使用される。

この公式では、R および N 要素については前の公式と同じである。Nz 要素は頂点法線のワールド空間 z、I は無限大距離にあるビューポートのベクトル (0,0,1) である。システムでは、いずれかの公式で求めた反射ベクトルを使用して、キューブ マップの適切なサーフェスを選択および処理する。

注 : ほとんどの場合、アプリケーションでは頂点法線の自動正規化を有効にする必要がある。これを有効にするには、D3DRENDERSTATE_NORMALIZENORMALS を True に設定する。このレンダリング ステートを有効にしていない場合、環境マップの外観が期待とは大きく異なるものになる。


ブレンディング行列の設定

[C++]

IDirect3DDevice7::SetTransform メソッドを呼び出して、システムがブレンドする際のトランスフォーム行列を設定する。第 1 パラメータに D3DTRANSFORMSTATETYPE 列挙型から "D3DTRANSFORMSTATE_WORLD" メンバを設定し、第 2 パラメータには設定する行列のアドレスを設定する。

次の C++ コードは、2 つのワールド行列を設定する。これらの行列間でジオメトリをブレンドして腕をつなげる。

// この例では、pd3dDevice 変数は
// 初期化された 3D シーン用の IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
float     fBendAngle = 3.1415926f / 4.0f; // 45°
D3DMATRIX matUpperArm, matLowerArm;

// 上腕は動かない。単位行列を使用する。
D3DUtil_SetIdentityMatrix( matUpperArm );
pd3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD,  &matUpperArm );

// 下腕は x 軸を中心に回転する。これは上腕につなげる。
D3DUtil_SetRotateXMatrix( matLowerArm, -fBendAngle );
pd3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD1, &matLowerArm );

ブレンディング行列を設定しても、システムはその行列を後で使用できるように単にキャッシュするだけで、頂点のブレンドを開始するわけではない。詳細については、「ジオメトリ ブレンディングの有効化」を参照すること。

[Visual Basic]

Direct3DDevice7.SetTransform メソッドを呼び出して、システムがブレンドする際のトランスフォーム行列を設定する。第 1 パラメータに CONST_D3DTRANSFORMSTATETYPE 列挙から "D3DTRANSFORMSTATE_WORLD" メンバを設定し、第 2 パラメータには設定する行列のアドレスを設定する。

次の Visual Basic コードは、2 つのワールド行列を設定する。これらの行列間でジオメトリをブレンドして腕をつなげる。

' この例では、d3dDevice 変数は
' 初期化された 3D シーン用の Direct3DDevice7 オブジェクトへの
有効な参照であるとする。dx 変数は DirectX7 オブジェクトへの有効な参照である。
Dim nBendAngle As Single
Dim matUpperArm As D3DMATRIX, _
matLowerArm As D3DMATRIX

nBendAngle = 3.1415926 / 4#  ' 45°

' 上腕は動かない。単位行列を使用する。
Call dx.IdentityMatrix(matUpperArm)
Call d3dDevice.SetTransform(D3DTRANSFORMSTATE_WORLD, matUpperArm)

' 下腕は x 軸を中心に回転する。これは上腕につなげる。
Call dx.RotateXMatrix(matLowerArm, -nBendAngle)
Call d3dDevice.SetTransform(D3DTRANSFORMSTATE_WORLD1, matLowerArm)

ブレンディング行列を設定しても、システムはその行列を後で使用できるように単にキャッシュするだけで、頂点のブレンドを開始するわけではない。詳細については、「ジオメトリ ブレンディングの有効化」を参照すること。


サブピクセル補正ステート

D3DRENDERSTATE_SUBPIXEL および D3DRENDERSTATE_SUBPIXELX レンダリング ステートは使用されず、システムではこれを無視する。


頂点バッファ レンダリング メソッドの呼び出し

[C++]

IDirect3DDevice7::DrawPrimitiveVB メソッドは、IDirect3DDevice7::DrawPrimitive メソッドに対応する。同様に、DrawPrimitiveVB メソッドも、頂点が頂点バッファ内に順序どおりに現れると見なす。

DrawPrimitiveVB メソッドは 5 つのパラメータを受け取る。d3dptPrimitiveType パラメータには、D3DPRIMITIVETYPE 列挙型のメンバの 1 つを使用して、レンダリングするプリミティブの種類を設定する。第 2 パラメータ lpd3dVertexBuffer には、頂点を含む頂点バッファのアドレスを指定し、次に、dwStartVertex パラメータと dwNumVertices パラメータに、レンダリングする第 1 頂点と頂点の合計数を示す値を設定する。頂点バッファに含まれるすべての頂点をレンダリングする必要はないが、プリミティブの種類に応じた適切な数の頂点を使用しなければならない (D3DPRIMITIVETYPE の参照情報に記述)。最後のパラメータ dwFlags は、レンダリングの動作を決定する。このフラグは他のレンダリング メソッドで使用されるフラグと同一である。レンダリング中にフラグを設定して、ライティングおよびクリッピングを有効にしたり、クリップ範囲を更新することができる。

IDirect3DDevice7::DrawIndexedPrimitiveVB メソッドは、頂点バッファ内の頂点にインデックスを付けてプリミティブをレンダリングする。最初の 2 つのパラメータは、DrawPrimitiveVB メソッドのパラメータと同じである。第 3 および第 4 パラメータには、バッファ内の最初の頂点のインデックスおよびレンダリングする頂点の合計数をそれぞれ設定する。第 5 パラメータ lpwIndices には、レンダリングする頂点にアクセスするためにメソッドが使用する WORD インデックスの順序付き配列のアドレスを設定し、第 6 パラメータ dwIndexCount には、その配列に含まれるインデックス値の個数を設定する。dwFlags パラメータは、DrawPrimitiveVB メソッドの対応するパラメータと同じである。

[Visual Basic]

Direct3DDevice7.DrawPrimitiveVB メソッドは、Direct3DDevice7.DrawPrimitive メソッドに対応する。同じように、DrawPrimitiveVB メソッドも、頂点が頂点バッファ内に順序どおりに現れると見なす。

DrawPrimitiveVB メソッドは 5 つのパラメータを受け取る。d3dpt パラメータには、CONST_D3DPRIMITIVETYPE 列挙のメンバのいずれかを使用して、レンダリングするプリミティブの種類を設定する。第 2 パラメータ vertexBuffer には、頂点を含む Direct3DVertexBuffer7 オブジェクトを指定し、startVertex および numVertices パラメータには、最初の頂点およびレンダリングする頂点の合計数を示す値を指定する。頂点バッファに含まれるすべての頂点をレンダリングする必要はないが、プリミティブの種類に応じた適切な数の頂点を使用しなければならない (D3DPRIMITIVETYPE の参照情報に記述)。最後のパラメータ flags は、レンダリングの動作を決定する。これらフラグは、その他のレンダリング メソッドで使用されるフラグと同じである。レンダリング中にフラグを設定して、ライティングおよびクリッピングを有効にしたり、クリップ範囲を更新することができる。

Direct3DDevice7.DrawIndexedPrimitiveVB メソッドは、頂点バッファ内の頂点にインデックスを付けてプリミティブをレンダリングする。最初の 2 つのパラメータは、DrawPrimitiveVB メソッドのパラメータと同じである。第 3 および第 4 パラメータには、バッファ内の最初の頂点のインデックスおよびレンダリングする頂点の合計数をそれぞれ設定する。第 5 パラメータ indexArray には、レンダリングする頂点にアクセスするためにメソッドが使用する Integer インデックスの順序付き配列のアドレスを設定し、第 6 パラメータ indexCount には、その配列に含まれるインデックス値の個数を設定する。flags パラメータは、DrawPrimitiveVB メソッドの対応するパラメータと同じである。

バッファ内の頂点フォーマットに頂点法線が含まれていない場合は、頂点バッファ レンダリング メソッドにライティングを要求することはできない。また、D3DDP_DONOTCLIP フラグを使用して作成された、トランスフォームされた頂点バッファからのレンダリングを行う場合、レンダリング メソッドに頂点のクリップを要求することはできない (これは、未トランスフォームの頂点バッファに対しては要求できる。レンダリング時にシステムがクリッピング可能なバッファを作成するからである)。利用できないサービスを要求しても、デバッグ ビルドでメソッドが失敗する原因になることはないが、サービスは適用されない。

ハードウェア アクセラレーション トランスフォーム & ライティングが可能な TnLHAL デバイス (IID_IDirect3DTnLHALDevice) とは対照的に、ソフトウェア デバイスまたは HAL デバイス (IID_IDirect3DHALDevice) では、D3DVBCAPS_SYSTEMMEMORY フラグで作成された頂点バッファからのレンダリングのみ実行できる。詳細については、「デバイスの種類と頂点処理の要件」を参照すること。


テクスチャ ステージとテクスチャ ブレンディング カスケード

Direct3Dは、"テクスチャ ステージ" の使用により、シングル パスのマルチ テクスチャ ブレンディングをサポートしている。テクスチャ ステージには 2 つの引数を受け取り、ブレンディング操作を行い、後続の処理またはラスタ化に結果を渡す。テクスチャ ステージは、次の図に示すように図式化できる。

上の図に示すように、テクスチャ ステージは指定のオペレータを使用して 2 つの引数をブレンドする。一般的な操作には、引数の色またはアルファ要素の単純変調や加算があるが、現在、20 以上の操作がサポートされている。ステージの引数は、関連付けられたテクスチャ、反復色または反復アルファ (グーロー シェーディング中の反復)、任意の色とアルファ、または以前のテクスチャ ステージからの結果である。詳細については、「テクスチャ ブレンディング処理と引数」を参照すること。

注 : Direct3D では、色ブレンディングとアルファ ブレンディングを区別する。アプリケーションでは、色とアルファに対して個別にブレンディング処理と引数を設定し、これらの設定が互いの結果に影響することはない。

マルチ ブレンディング ステージで使用される引数と操作の組み合わせは、単純なフローを基本とするブレンディング言語を定義する。1 つのステージからの結果は、別のズテージに流れ、次にそのステージからの結果が次のステージに流れ、以下同じように続く。ステージからステージへの流れが最後にはポリゴン上でラスタ化されるというアイデアは、しばしば「テクスチャ ブレンディング カスケード」と呼ばれる。次の図は、個別のテクスチャ ステージがどのようにテクスチャ ブレンディング カスケードを構成するかを示す。

デバイス内の各ステージは、0 から始まるインデックスを持つ。Direct3D では、現在のところ最大 8 つのブレンディング ステージを利用できる。ただし、現在のハードウェアでサポートされるステージ数を判断するために、デバイス機能を調べる必要がある。第 1 ブレンディング ステージはインデックス 0 にあり、第 2 ステージはインデックス 1 にあり、以下インデックス 7 まで同様である。システムは、インデックスの昇順にステージをブレンドする。

必要な数だけのステージを使用する。使用しないブレンディング ステージはデフォルトで無効になる。アプリケーションが最初の 2 つのステージだけを使う場合は、ステージ 0 と 1 についてだけ設定操作と引数が必要であり、残りのステージはそのままにする。システムは 2 つのステージをブレンドして、無効なステージを無視する。

最適化に関する注意 : オブジェクトによっては 4 つのステージを使用したり、2 つのステージを使用するなど、状況に応じてアプリケーションで使用するステージの数が変わる場合は、以前に使用したすべてのステージを明示的に無効にしなくてもよい。最初の未使用のステージに対して色処理を無効にしても、それよりインデックスが大きいステージでは無効にならない。色処理を最初のテクスチャ ステージ (ステージ 0) に設定すると、すべてのテクスチャ マッピングを無効にできる。


頂点フォグの使用

アプリケーションで頂点フォグを有効にするには、次の手順に従う。

[C++]

C++ アプリケーションで頂点フォグを有効にするには

  1. D3DRENDERSTATE_FOGENABLE を TRUE に設定して、フォグ ブレンディングを有効にする。
  2. D3DRENDERSTATE_FOGCOLOR レンダリング ステートで必要なフォグ カラーを設定する。
  3. D3DRENDERSTATE_FOGVERTEXMODE レンダリング ステートを D3DFOGMODE 列挙型のメンバに設定して、希望のフォグ公式を選択する。
  4. 選択したフォグ公式で必要なフォグ パラメータをレンダリング ステートに設定する。

次に、以上の手順を C++ コードで示す。

// 簡単にするために、この例では、呼び出しの後で
// エラー値をチェックしない。実際のアプリケーションでは、
// エラー値を正しくチェックすること。
//
// この例では、g_lpDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。
void SetupVertexFog(DWORD dwColor, DWORD dwMode, BOOL fUseRange, FLOAT fDensity)
{
    float fStart = 0.5f,    // 線形フォグ距離。
          fEnd   = 0.8f;

    // フォグ ブレンディングを有効にする。
    g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGENABLE, TRUE);

    // フォグ カラーを設定する。
    g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGCOLOR, dwColor);

    // フォグ パラメータを設定する。
    if(D3DFOG_LINEAR == dwMode)
    {
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGVERTEXMODE, dwMode);
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGSTART, *(DWORD *)(&fStart));
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGEND,   *(DWORD *)(&fEnd));
    }
    else
    {
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGVERTEXMODE, dwMode);
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGDENSITY, *(DWORD *)(&fDensity));
    }

    // 必要に応じて、範囲ベースのフォグを有効にする (頂点フォグでのみサポートされる)。
    // この例では、ドライバが D3DPRASTERCAPS_FOGRANGE 能力を公開する場合にのみ、
    // fUseRange はゼロ以外の値に設定されるとする。
    //
    // 注 :  この方が、範囲に基づかないフォグよりも
    //       若干パフォーマンスがよい。
    if(fUseRange)
        g_lpDevice->SetRenderState(
                       D3DRENDERSTATE_RANGEFOGENABLE,
                       TRUE);
}

注 : IDirect3DDevice7::SetRenderState メソッドは、第 2 パラメータに DWORD 値のみ受け取るが、浮動小数点値のフォグ パラメータが要求されることもある。前述の例では浮動小数点の値をメソッドに渡すために、データをトランスフォームするのではなく、浮動小数点変数のアドレスを DWORD ポインタにキャストして、次にそれを参照している。

[Visual Basic]

Visual Basic アプリケーションで頂点フォグを有効にするには

  1. D3DRENDERSTATE_FOGENABLE を True に設定して、フォグ ブレンディングを有効にする。
  2. 希望のフォグ カラーを D3DRENDERSTATE_FOGCOLOR レンダリング ステートに設定する。
  3. D3DRENDERSTATE_FOGVERTEXMODE レンダリング ステートを CONST_D3DFOGMODE 列挙のメンバに設定して、希望のフォグ公式を選択する。
  4. 選択したフォグ公式で必要なフォグ パラメータをレンダリング ステートに設定する。

次に、以上の手順を Visual Basic コードで示す。

' 簡単にするために、この例では、呼び出しの後で
' エラー値をチェックしない。実際のアプリケーションでは、
' エラー値を正しくチェックすること。
'
' この例では、g_d3dDevice は Direct3DDevice7 オブジェクトへの
' 有効な参照を示す。
Sub SetupVertexFog(lColor As Long, Mode As CONST_D3DFOGMODE, _
bUseRange As Boolean, Optional Density As Single)

Dim StartFog As Single, _
EndFog As Single

' 線形フォグの距離を設定する。
StartFog = 0.5:EndFog = 0.8

' フォグ ブレンディングを有効にする。
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGENABLE, True)

' フォグ カラーを設定する。
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGCOLOR, lColor)

' フォグ パラメータを設定する。
If Mode = D3DFOG_LINEAR Then
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGVERTEXMODE, Mode)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGSTART, StartFog)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGEND, EndFog)
Else
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGVERTEXMODE, Mode)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGDENSITY, Density)
End If

' 必要に応じて、範囲ベースのフォグを有効にする (頂点フォグでのみサポートされる)。
' この例では、ドライバが D3DPRASTERCAPS_FOGRANGE 能力を公開する場合にのみ、
' bUseRange は True に設定されるとする。
    '
' 注 :  この方が、範囲に基づかないフォグよりも
'       若干パフォーマンスがよい。
If bUseRange = True Then
Call g_d3dDevice.SetRenderState( _
D3DRENDERSTATE_RANGEFOGENABLE, True)
End If
End Sub


プリミティブ クリッピング ステート

[C++]

Direct3D では、ビューポート外で部分的にレンダリングするプリミティブをクリッピングすることができる。C++ の場合、Direct3D クリッピングは D3DRENDERSTATE_CLIPPING レンダリング ステートで制御する。このレンダリング ステートを TRUE (デフォルト値) に設定すると、プリミティブ クリッピングが有効になる。レンダリング ステートを FALSE に設定すると、Direct3D のクリッピング サービスは無効になる。

プリミティブ クリッピング レンダリング ステートは、頂点バッファ内の頂点で可能なクリッピング処理にはまったく依存しない。IDirect3DVertexBuffer7::ProcessVertices および IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドは、頂点処理の際にプリミティブ クリッピングを制御する、独自のフラグを受け取る。

注 : このレンダリング ステートは、反対ではあるが従来のレンダリング メソッドで使用された D3DDP_DONOTCLIP フラグと類似している。DirectX 7.0 では、このレンダリング ステートが D3DDP_DONOTCLIP フラグに置き換わっている。D3DDP_DONOTCLIP フラグで 1 回の呼び出しごとにクリッピングを無効する場合、ステート値がアプリケーションによって再度変更されるまでは、レンダリングに関するすべての呼び出しがこのレンダリング ステートの影響を受ける。

[Visual Basic]

Direct3D では、ビューポート外で部分的にレンダリングするプリミティブをクリッピングすることができる。Visual Basic アプリケーションでは、Direct3D クリッピングは D3DRENDERSTATE_CLIPPING レンダリング ステートで制御する。このレンダリング ステートを TRUE (デフォルト値) に設定すると、プリミティブ クリッピングが有効になる。レンダリング ステートを FALSE に設定すると、Direct3D のクリッピング サービスは無効になる。

プリミティブ クリッピング レンダリング ステートは、頂点バッファ内の頂点で可能なクリッピング処理にはまったく依存しない。Direct3DVertexBuffer7.ProcessVertices メソッドは、頂点処理の際にプリミティブ クリッピングを制御する、独自のフラグを受け取る。


ディフューズ ライト マップ

光源で照らしたとき、光沢のないサーフェスはディフューズ ライトを放つ。ディフューズ ライトの輝きは、光源からの距離、およびサーフェス法線と光源の方向ベクトルとの角度によって異なる。ライティング計算によってシミュレートするディフューズ ライトのエフェクトは一般的なものである。

[C++]

テクスチャ ライト マップを使用してディフューズ ライトをシミュレートできる。これを行うには、次の C++ コードで示すように、ディフューズ ライト マップをベース テクスチャに追加する。

// この例では、lpD3DDev は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
// lptexBaseTexture は、テクスチャへの有効なポインタである。
// lptexDiffuseLightMap は、RGB ディフューズ ライト マップ データを含む
// テクスチャへの有効なポインタである。

// ベース テクスチャを設定する。
lpD3DDev->SetTexture(0,lptexBaseTexture );

// ベース テクスチャ処理と引数を設定する。
lpD3DDev->SetTextureStageState(0,D3DTSS_COLOROP,
       D3DTOP_MODULATE );
lpD3DDev->SetTextureStageState(0,D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(0,D3DTSS_COLORARG2, D3DTA_DIFFUSE );

// ディフューズ ライト マップを設定する。
lpD3DDev->SetTexture(1,lptexDiffuseLightMap );

// ブレンディング ステージを設定する。
lpD3DDev->SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_MODULATE );
lpD3DDev->SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT );
[Visual Basic]

テクスチャ ライト マップを使用してディフューズ ライトをシミュレートできる。これを行うには、次の Visual Basic コードで示すように、ディフューズ ライト マップをベース テクスチャに追加する。

' この例では、d3dDev は Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
' texBaseTexture は、テクスチャへの有効な参照である。
' texDiffuseLightMap は、RGB ディフューズ ライト マップ データを含む
' テクスチャへの有効な参照である。

' ベース テクスチャを設定する。
Call d3dDev.SetTexture(0, texBaseTexture)

' ベース テクスチャ処理と引数を設定する。
Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, _
D3DTOP_MODULATE );
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

' ディフューズ ライト マップを設定する。
Call d3dDev.SetTexture(1, texDiffuseLightMap)

' ブレンディング ステージを設定する。
Call d3dDev.SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDev.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)


線ストリップ

Platform SDK: DirectX

線ストリップ

線ストリップとは、線分同士を結合したものから構成されるプリミティブである。線ストリップを使用して、閉じていないポリゴンを作成できる。閉じたポリゴンとは、最後の頂点が最初の頂点と線分で結合されているポリゴンである。線ストリップに基づいてポリゴンを作成する場合、そのポリゴンの頂点が同一平面上にあるとは限らない。線ストリップは、頂点の配列に値を設定して作成する。

[C++]

次の C++ コードは、頂点の配列に値を設定する処理を示す。

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0),D3DVECTOR(0,0,-1),0,0);

IDirect3DDevice7::DrawPrimitive メソッドを使用して線リストをレンダリングする。次のコードは、IDirect3DDevice7::DrawPrimitive を使用して、上の例の線ストリップを描画する方法を示す。IDirect3DDevice7::DrawPrimitive の呼び出しは、IDirect3DDevice7::BeginScene と IDirect3DDevice7::EndScene の間で行う必要がある。

HRESULT hResult;
// このコードでは、lpDirect3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_LINESTRIP,
                                      D3DFVF_VERTEX,
                                      lpVerts,
                                      TOTAL_VERTS,
                                      D3DDP_WAIT);
[Visual Basic]

次の Visual Basic コードは、頂点の配列に値を設定する処理を示す。

' このコードでは、dx は DirectX7 オブジェクトへの
' 有効な参照であるとする。
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

Direct3DDevice7.DrawPrimitive メソッドを使用して線リストをレンダリングする。次のコードは、Direct3DDevice7.DrawPrimitive を使用して、上の例の線ストリップを描画する方法を示す。Direct3DDevice7.DrawPrimitive の呼び出しは、Direct3DDevice7.BeginScene と Direct3DDevice7.EndScene の間で行う必要がある。

' このコードでは、d3ddev は Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
Call d3ddev.DrawPrimitive(D3DPT_LINESTRIP, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
                          D3DDP_WAIT)

If Err.Number <> DD_OK Then
' エラー処理コード
End If

次の図は、上のコードによって作成される線ストリップを示す。


レンダリング ステートについて

デバイス レンダリング ステートは、Direct3D デバイスのラスタ化モジュールの動作を制御する。レンダリング ステートの属性を変更すると、使用するシェーディング タイプ、フォグ属性など、多数のラスタ化を指定できる。

[C++]

C++ で記述されたアプリケーションでは、IDirect3DDevice7::SetRenderState メソッドを呼び出して、レンダリング ステートのその他の特性を制御する。D3DRENDERSTATETYPE 列挙型は、可能なレンダリング ステートをすべて指定する。アプリケーションでは、D3DRENDERSTATETYPE 列挙からの値を第 1 パラメータとして IDirect3DDevice7::SetRenderState メソッドに渡す。

レンダリング ステートは、テクスチャのスタイルおよびテクスチャ フィルタリングの方法も制御する。DirectX 6.0 以降では、テクスチャに関するすべてのレンダリング ステートは、IDirect3DDevice7::SetTextureStageState メソッドが提供する対応機能に置き換えられている。これら置き換えられたレンダリング ステートを IDirect3DDevice7 インターフェイスで使用すると失敗する。

D3DRENDERSTATE_TEXTUREADDRESS、D3DRENDERSTATE_TEXTUREADDRESSU、および D3DRENDERSTATE_TEXTUREADDRESSV
D3DTSS_ADDRESS、D3DTSS_ADDRESSU、D3DTSS_ADDRESSV テクスチャ ステージ ステートに置き換えられている。
D3DRENDERSTATE_BORDERCOLOR
D3DTSS_BORDERCOLOR テクスチャ ステージ ステートに置き換えられている。
D3DRENDERSTATE_TEXTUREMAG
D3DTSS_MAGFILTER テクスチャ ステージ ステートに置き換えられている。
D3DRENDERSTATE_TEXTUREMIN
D3DTSS_MINFILTER テクスチャ ステージ ステートに置き換えられている。ミップマップ縮小フィルタリングは D3DTSS_MIPFILTER に置き換えられている。
D3DRENDERSTATE_TEXTUREMAPBLEND
D3DTSS_COLOROP および D3DTSS_ALPHAOP テクスチャ ステージ ステートに置き換えられている。
[Visual Basic]

Visual Basic アプリケーションでは、Direct3DDevice7.SetRenderState メソッドを呼び出して、レンダリング ステートの特性を制御する。CONST_D3DRENDERSTATETYPE 列挙型は、可能なレンダリング ステートをすべて指定する。アプリケーションでは、CONST_D3DRENDERSTATETYPE 列挙の値を第 1 パラメータとして Direct3DDevice7.SetRenderState メソッドに渡す。


頂点色ステート

[C++]

D3DVERTEX、D3DLVERTEX、および D3DTLVERTEX 型の頂点は、色情報と法線情報を同時に持つことはできない。デフォルトのシェーディング モードはグーロー シェーディングで、このモードは頂点の色情報と法線情報の両方に依存するため、Direct3D ではライティング計算に頂点色を使用しなかった。

ところが、DirectX 5.0 で柔軟な頂点フォーマットが導入されたことにより、頂点は色情報と法線情報の両方を持てるようになった。デフォルトでは、この情報を使用してライティング計算が実行される。アプリケーションで頂点のカラー ライティング情報の使用を無効にする場合、IDirect3DDevice7::SetRenderState メソッドを呼び出し、第 1 パラメータとして D3DRENDERSTATE_COLORVERTEX を渡す。第 2 パラメータを FALSE に設定すると頂点のカラー ライティングが無効になり、TRUE に設定すると有効になる。

頂点単位色が有効なっている場合、アプリケーションでは、頂点の色情報の情報ソースを設定できる。D3DRENDERSTATE_DIFFUSEMATERIALSOURCE、D3DRENDERSTATE_SPECULARMATERIALSOURCE、D3DRENDERSTATE_AMBIENTMATERIALSOURCE、および D3DRENDERSTATE_EMISSIVEMATERIALSOURCE レンダリング ステートによって、ディフューズ、スペキュラ、アンビエント、およびエミッション色の色成分ソースの色ソースを制御する。これらの各レンダリング ステートは、D3DMATERIALCOLORSOURCE 列挙型のメンバに設定できる。この列挙型は、現在のマテリアル、ディフューズ色、またはスペキュラ色を、指定された色成分のソースとして使用するようシステムに知らせる定数を定義する。

[Visual Basic]

D3DVERTEX、D3DLVERTEX、および D3DTLVERTEX 型の頂点は、色情報と法線情報を同時に持つことはできない。デフォルトのシェーディング モードはグーロー シェーディングであり、このモードは頂点の色情報と法線情報の両方に依存するため、Direct3D ではライティング計算に頂点色を使用しなかった。

柔軟な頂点フォーマットを使用すると、既に説明した頂点タイプとは対照的に、頂点は色情報と法線情報の両方を持つことができる。デフォルトでは、この情報を使用してライティング計算が実行される。アプリケーションで頂点のカラー ライティング情報に使用を無効にする場合、Direct3DDevice7.SetRenderState メソッドを呼び出し、第 1 パラメータとして D3DRENDERSTATE_COLORVERTEX を渡す。第 2 パラメータを FALSE に設定すると頂点のカラー ライティングが無効になり、TRUE に設定すると有効になる。

頂点単位色が有効になっている場合、アプリケーションでは、頂点の色情報の情報ソースを設定できる。D3DRENDERSTATE_DIFFUSEMATERIALSOURCE、D3DRENDERSTATE_SPECULARMATERIALSOURCE、D3DRENDERSTATE_AMBIENTMATERIALSOURCE、および D3DRENDERSTATE_EMISSIVEMATERIALSOURCE レンダリング ステートによって、ディフューズ、スペキュラ、アンビエント、およびエミッション色の色成分ソースの色ソースを制御する。これらの各レンダリング ステートは、CONST_D3DMATERIALCOLORSOURCE 列挙型のメンバに設定できる。これらの列挙型は、現在のマテリアル、ディフューズ色、またはスペキュラ色を、指定された色成分のソースとして使用するようシステムに知らせる定数を定義する。


ステンシル バッファ ステート

アプリケーションでは、ステンシルバッファを使用して、レンダリング ターゲット サーフェスにピクセルを書き込むかどうかを決める。詳細については、「ステンシル バッファ」を参照すること。

[C++]

C++ で記述されたアプリケーションで、ステンシル処理を有効または無効にするには、IDirect3DDevice7::SetRenderState メソッドを呼び出す。第 1 パラメータの値として D3DRENDERSTATE_STENCILENABLE を渡す。ステンシル処理を有効にするには第 2 パラメータの値を TRUE に設定し、無効にするには FALSE に設定する。

Direct3D のステンシル テストで使用する比較関数は、IDirect3DDevice7::SetRenderState メソッドを呼び出して設定する。第 1 パラメータを D3DRENDERSTATE_STENCILFUNC に設定する。第 2 パラメータの値として D3DCMPFUNC 列挙型のメンバを渡す。

ステンシル参照値とは、ステンシル関数がテストに使用する、ステンシル バッファ内の値である。デフォルトではステンシル参照値はゼロである。アプリケーションでは、IDirect3DDevice7::SetRenderState メソッドを呼び出してこの値を設定できる。第 1 パラメータの値として D3DRENDERSTATE_STENCILREF を渡す。第 2 パラメータの値を新しい参照値に設定する。

Direct3D モジュールは、ピクセルに対するステンシル テストを実行する前に、ステンシル参照値とステンシルマスク値のビット積を計算する。次に、その結果が、ステンシル比較関数を使用してステンシル バッファの内容と比較される。アプリケーションではこのステンシル マスクを設定できる。IDirect3DDevice7::SetRenderState メソッドを使用し、第 1 パラメータの値として D3DRENDERSTATE_STENCILMASK を渡す。第 2 パラメータを新しいステンシル マスクに設定する。

ステンシル テストが失敗したときの Direct3D の処理を設定するには、IDirect3DDevice7::SetRenderState メソッドを呼び出し、第 1 パラメータとして D3DRENDERSTATE_STENCILFAIL を渡す。第 2 パラメータは D3DSTENCILOP 列挙型のメンバでなければならない。

また、ステンシル テストは成功したが z バッファ テストが失敗したときの Direct3D の処理もアプリケーションで制御できる。IDirect3DDevice7::SetRenderState メソッドを呼び出し、第 1 パラメータとして D3DRENDERSTATE_STENCILZFAIL を渡し、第 2 パラメータに D3DSTENCILOP 列挙型のメンバを設定する。

さらに、ステンシル テストと ｚ バッファ テストの両方が成功したときの Direct3D の処理も制御できる。IDirect3DDevice7::SetRenderState メソッドを呼び出し、第 1 パラメータとして D3DRENDERSTATE_STENCILPASS を渡す。この場合も、第 2 パラメータは D3DSTENCILOP 列挙型のメンバでなければならない。

[Visual Basic]

Visual Basic でステンシル処理を有効または無効にするには、Direct3DDevice7.SetRenderState メソッドを呼び出す。第 1 パラメータの値として D3DRENDERSTATE_STENCILENABLE を渡す。ステンシル処理を有効にするには第 2 パラメータの値を True に設定し、無効にするには False に設定する。

Direct3D のステンシル テストで使用する比較関数は、Direct3DDevice7::SetRenderState メソッドを呼び出して設定する。第 1 パラメータの値を D3DRENDERSTATE_STENCILFUNC に設定する。第 2 パラメータの値として CONST_D3DCMPFUNC 列挙型のメンバを渡す。

ステンシル参照値とは、ステンシル関数がテストに使用する、ステンシル バッファ内の値である。デフォルトではステンシル参照値はゼロである。アプリケーションでは、Direct3DDevice7.SetRenderState メソッドを呼び出してこの値を設定できる。第 1 パラメータの値として D3DRENDERSTATE_STENCILREF を渡す。第 2 パラメータの値には新しい参照値に設定する。

Direct3D モジュールは、ピクセルに対するステンシル テストを実行する前に、ステンシル参照値とステンシルマスク値のビット積を計算する。次に、その結果が、ステンシル比較関数を使用してステンシル バッファの内容と比較される。アプリケーションでは、D3DRENDERSTATE_STENCILMASK レンダリング ステートを呼び出して、このステンシル マスクを設定できる。レンダリング ステート値を新しいステンシル マスクに設定する。

ステンシル テストが失敗したときの Direct3D の処理を設定するには、Direct3DDevice7::SetRenderState メソッドを呼び出し、第 1 パラメータとして D3DRENDERSTATE_STENCILFAIL を渡す。第 2 パラメータは CONST_D3DSTENCILOP 列挙のメンバでなければならない。

また、ステンシル テストは成功したが z バッファ テストが失敗したときの Direct3D の処理もアプリケーションで制御できる。Direct3DDevice7::SetRenderState メソッドを呼び出し、第 1 パラメータとして D3DRENDERSTATE_STENCILZFAIL を渡し、第 2 パラメータに D3DSTENCILOP 列挙のメンバを設定する。

さらに、ステンシル テストと z バッファ テストの両方が成功したときの Direct3D の処理も制御できる。Direct3DDevice7::SetRenderState メソッドを使用し、第 1 パラメータとして D3DRENDERSTATE_STENCILPASS を渡す。この場合も、第 2 パラメータは D3DSTENCILOP 列挙のメンバでなければならない。


ライトの種類

[C++]

ライトの種類プロパティは、使用する光源の種類を定義する。C++ の場合、ライトの種類は、ライトの D3DLIGHT7 構造体の dltType メンバに D3DLIGHTTYPE 列挙からの値を使用して設定する。Direct3D 直接モードでは、ポイント ライト、スポット ライト、およびディレクショナル ライトの 3 種類のライトがある。ライトの種類ごとに、シーン内のオブジェクトの照らし方が異なり、計算におけるオーバーヘッドのレベルも異なる。各ライトの作用に関する一般的な情報については、「ライト オブジェクトの概要」を参照すること。

[Visual Basic]

ライトの種類プロパティは、使用する光源の種類を定義する。Visual Basic の場合、ライトの種類は、ライトの D3DLIGHT7 型の dltType メンバに CONST_D3DLIGHTTYPE 列挙からの値を使用して設定する。Direct3D 直接モードでは、ポイント ライト、スポット ライト、およびディレクショナル ライトの 3 種類のライトがある。ライトの種類ごとに、シーン内のオブジェクトの照らし方が異なり、計算におけるオーバーヘッドのレベルも異なる。各ライトの作用に関する一般的な情報については、「ライト オブジェクトの概要」を参照すること。


プリミティブの種類

Direct3D では、以下の種類のプリミティブを作成および操作できる。

  • 点リスト
  • 線リスト
  • 線ストリップ
  • 三角形リスト
  • 三角形ストリップ
  • 三角形ファン
[C++]

C++ アプリケーションでは、IDirect3DDevice7 インターフェイスのレンダリング メソッドを使用して、これらの種類のプリミティブをレンダリングできる。詳細については、「レンダリング」を参照すること (インデックス付きプリミティブ レンダリング メソッドを使用して、点リストをレンダリングすることはできない)。

[Visual Basic]

Visual Basic アプリケーションでは、Direct3DDevice7 インターフェイスのレンダリング メソッドを使用して、これらすべての種類のプリミティブをレンダリングできる。詳細については、「レンダリング」を参照すること。


事前定義するステート ブロックの作成

[C++]

IDirect3DDevice7::CreateStateBlock メソッドは、デバイス ステート セットの全体を含むか、あるいは頂点またはピクセル処理に関するデバイス ステートのみ含む新しいステート ブロックを作成する。CreateStateBlock メソッドは 2 つのパラメータを受け取る。第 1 パラメータは、新しいステート ブロックに取り込むステート情報の種類を識別する。第 2 パラメータは、呼び出しが成功したときに有効なステート ブロック ハンドルを受け取る変数のアドレスである。

第 1 パラメータの有効値は、D3DSTATEBLOCKTYPE 列挙型で定義される。これに含まれるメンバを使用して、デバイス ステート セットの全体 (D3DSBT_ALL)、あるいは点またはピクセル処理 (D3DSBT_VERTEX または D3DSBT_PIXEL) に関するステートのみ取り込むことができる。次の一覧は、D3DSBT_VERTEX または D3DSBT_PIXEL 値を渡したときにシステムによって取り込まれるステートを示す。

  • 頂点関連のステート (D3DSBT_VERTEX)

    すべてのライティングのステート (有効または無効)

    トランスフォーム行例

    ユーザー定義クリップ面

    以下のレンダリング ステートに対する設定値
    D3DRENDERSTATE_AMBIENT

    D3DRENDERSTATE_AMBIENTMATERIALSOURCE

    D3DRENDERSTATE_CLIPPING

    D3DRENDERSTATE_CLIPPLANEENABLE

    D3DRENDERSTATE_COLORVERTEX

    D3DRENDERSTATE_CULLMODE

    D3DRENDERSTATE_DIFFUSEMATERIALSOURCE

    D3DRENDERSTATE_EMISSIVEMATERIALSOURCE

    D3DRENDERSTATE_EXTENTS

    D3DRENDERSTATE_FOGCOLOR

    D3DRENDERSTATE_FOGDENSITY

    D3DRENDERSTATE_FOGENABLE

    D3DRENDERSTATE_FOGEND

    D3DRENDERSTATE_FOGSTART

    D3DRENDERSTATE_FOGTABLEMODE

    D3DRENDERSTATE_FOGVERTEXMODE

    D3DRENDERSTATE_LIGHTING

    D3DRENDERSTATE_LOCALVIEWER

    D3DRENDERSTATE_NORMALIZENORMALS

    D3DRENDERSTATE_RANGEFOGENABLE

    D3DRENDERSTATE_SHADEMODE

    D3DRENDERSTATE_SPECULARENABLE

    D3DRENDERSTATE_SPECULARMATERIALSOURCE

    D3DRENDERSTATE_VERTEXBLEND

    以下のテクスチャ ステージ ステートに対する設定値
    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

  • ピクセル関連のステート (D3DSBT_PIXEL)
    以下のレンダリング ステートに対する設定値
    D3DRENDERSTATE_ALPHABLENDENABLE

    D3DRENDERSTATE_ALPHAFUNC

    D3DRENDERSTATE_ALPHAREF

    D3DRENDERSTATE_ALPHATESTENABLE

    D3DRENDERSTATE_ANTIALIAS

    D3DRENDERSTATE_COLORKEYBLENDENABLE

    D3DRENDERSTATE_COLORKEYENABLE

    D3DRENDERSTATE_DESTBLEND

    D3DRENDERSTATE_DITHERENABLE

    D3DRENDERSTATE_EDGEANTIALIAS

    D3DRENDERSTATE_FILLMODE

    D3DRENDERSTATE_FOGDENSITY

    D3DRENDERSTATE_FOGEND

    D3DRENDERSTATE_FOGSTART

    D3DRENDERSTATE_LASTPIXEL

    D3DRENDERSTATE_LINEPATTERN

    D3DRENDERSTATE_SHADEMODE

    D3DRENDERSTATE_SRCBLEND

    D3DRENDERSTATE_STENCILENABLE

    D3DRENDERSTATE_STENCILFAIL

    D3DRENDERSTATE_STENCILFUNC

    D3DRENDERSTATE_STENCILMASK

    D3DRENDERSTATE_STENCILPASS

    D3DRENDERSTATE_STENCILREF

    D3DRENDERSTATE_STENCILWRITEMASK

    D3DRENDERSTATE_STENCILZFAIL

    D3DRENDERSTATE_STIPPLEDALPHA

    D3DRENDERSTATE_TEXTUREFACTOR

    D3DRENDERSTATE_TEXTUREPERSPECTIVE

    D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7

    D3DRENDERSTATE_ZBIAS

    D3DRENDERSTATE_ZENABLE

    D3DRENDERSTATE_ZFUNC

    D3DRENDERSTATE_ZWRITEENABLE

    以下のテクスチャ ステージ ステートに対する設定値
    D3DTSS_ADDRESS

    D3DTSS_ADDRESSU

    D3DTSS_ADDRESSV

    D3DTSS_ALPHAARG1

    D3DTSS_ALPHAARG2

    D3DTSS_ALPHAOP

    D3DTSS_BORDERCOLOR

    D3DTSS_BUMPENVLOFFSET

    D3DTSS_BUMPENVLSCALE

    D3DTSS_BUMPENVMAT00

    D3DTSS_BUMPENVMAT01

    D3DTSS_BUMPENVMAT10

    D3DTSS_BUMPENVMAT11

    D3DTSS_COLORARG1

    D3DTSS_COLORARG2

    D3DTSS_COLOROP

    D3DTSS_MAGFILTER

    D3DTSS_MAXANISOTROPY

    D3DTSS_MAXMIPLEVEL

    D3DTSS_MINFILTER

    D3DTSS_MIPFILTER

    D3DTSS_MIPMAPLODBIAS

    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

[Visual Basic]

Direct3DDevice7.CreateStateBlock メソッドは、デバイス ステート セットの全体を含むか、または頂点またはピクセル処理に関するデバイス ステートのみ含む新しいステート ブロックを作成する。CreateStateBlock メソッドは 2 つのパラメータを受け取る。第 1 パラメータは、新しいステート ブロックに取り込むステート情報の種類を識別する。第 2 パラメータは、呼び出しが成功したときに有効なステート ブロック ハンドルを受け取る変数のアドレスである。

第 1 パラメータの有効値は、CONST_D3DSTATEBLOCKTYPE 列挙で定義される。この列挙に含まれるメンバを使用して、デバイス ステート セットの全体 (D3DSBT_ALL)、あるいは点またはピクセル処理 (D3DSBT_VERTEX または D3DSBT_PIXEL) に関するステートのみ取り込むことができる。次の一覧は、D3DSBT_VERTEX または D3DSBT_PIXEL 値を渡したときにシステムによって取り込まれるステートを示す。

  • 頂点関連のステート (D3DSBT_VERTEX)

    すべてのライティングのステート (有効または無効)

    トランスフォーム行例

    ユーザー定義クリップ面

    以下のレンダリング ステートに対する設定値
    D3DRENDERSTATE_AMBIENT

    D3DRENDERSTATE_AMBIENTMATERIALSOURCE

    D3DRENDERSTATE_CLIPPING

    D3DRENDERSTATE_CLIPPLANEENABLE

    D3DRENDERSTATE_COLORVERTEX

    D3DRENDERSTATE_CULLMODE

    D3DRENDERSTATE_DIFFUSEMATERIALSOURCE

    D3DRENDERSTATE_EMISSIVEMATERIALSOURCE

    D3DRENDERSTATE_EXTENTS

    D3DRENDERSTATE_FOGCOLOR

    D3DRENDERSTATE_FOGDENSITY

    D3DRENDERSTATE_FOGENABLE

    D3DRENDERSTATE_FOGEND

    D3DRENDERSTATE_FOGSTART

    D3DRENDERSTATE_FOGTABLEMODE

    D3DRENDERSTATE_FOGVERTEXMODE

    D3DRENDERSTATE_LIGHTING

    D3DRENDERSTATE_LOCALVIEWER

    D3DRENDERSTATE_NORMALIZENORMALS

    D3DRENDERSTATE_RANGEFOGENABLE

    D3DRENDERSTATE_SHADEMODE

    D3DRENDERSTATE_SPECULARENABLE

    D3DRENDERSTATE_SPECULARMATERIALSOURCE

    D3DRENDERSTATE_VERTEXBLEND

    以下のテクスチャ ステージ ステートに対する設定値
    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

  • ピクセル関連のステート (D3DSBT_PIXEL)
    以下のレンダリング ステートに対する設定値
    D3DRENDERSTATE_ALPHABLENDENABLE

    D3DRENDERSTATE_ALPHAFUNC

    D3DRENDERSTATE_ALPHAREF

    D3DRENDERSTATE_ALPHATESTENABLE

    D3DRENDERSTATE_ANTIALIAS

    D3DRENDERSTATE_COLORKEYBLENDENABLE

    D3DRENDERSTATE_COLORKEYENABLE

    D3DRENDERSTATE_DESTBLEND

    D3DRENDERSTATE_DITHERENABLE

    D3DRENDERSTATE_EDGEANTIALIAS

    D3DRENDERSTATE_FILLMODE

    D3DRENDERSTATE_FOGDENSITY

    D3DRENDERSTATE_FOGEND

    D3DRENDERSTATE_FOGSTART

    D3DRENDERSTATE_LASTPIXEL

    D3DRENDERSTATE_LINEPATTERN

    D3DRENDERSTATE_SHADEMODE

    D3DRENDERSTATE_SRCBLEND

    D3DRENDERSTATE_STENCILENABLE

    D3DRENDERSTATE_STENCILFAIL

    D3DRENDERSTATE_STENCILFUNC

    D3DRENDERSTATE_STENCILMASK

    D3DRENDERSTATE_STENCILPASS

    D3DRENDERSTATE_STENCILREF

    D3DRENDERSTATE_STENCILWRITEMASK

    D3DRENDERSTATE_STENCILZFAIL

    D3DRENDERSTATE_STIPPLEDALPHA

    D3DRENDERSTATE_TEXTUREFACTOR

    D3DRENDERSTATE_TEXTUREPERSPECTIVE

    D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7

    D3DRENDERSTATE_ZBIAS

    D3DRENDERSTATE_ZENABLE

    D3DRENDERSTATE_ZFUNC

    D3DRENDERSTATE_ZWRITEENABLE

    以下のテクスチャ ステージ ステートに対する設定値
    D3DTSS_ADDRESS

    D3DTSS_ADDRESSU

    D3DTSS_ADDRESSV

    D3DTSS_ALPHAARG1

    D3DTSS_ALPHAARG2

    D3DTSS_ALPHAOP

    D3DTSS_BORDERCOLOR

    D3DTSS_BUMPENVLOFFSET

    D3DTSS_BUMPENVLSCALE

    D3DTSS_BUMPENVMAT00

    D3DTSS_BUMPENVMAT01

    D3DTSS_BUMPENVMAT10

    D3DTSS_BUMPENVMAT11

    D3DTSS_COLORARG1

    D3DTSS_COLORARG2

    D3DTSS_COLOROP

    D3DTSS_MAGFILTER

    D3DTSS_MAXANISOTROPY

    D3DTSS_MAXMIPLEVEL

    D3DTSS_MINFILTER

    D3DTSS_MIPFILTER

    D3DTSS_MIPMAPLODBIAS

    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

注 : CreateStateBlock メソッドが返すエラー コードをチェックすることが大切である。このメソッドが失敗した場合、その原因の多くはディスプレイ モードが変更されたことである考えられる (エラー コード DDERR_SURFACELOST)。アプリケーションのサーフェスを作成し直してステート ブロックを記録することで、このような障害からアプリケーションが回復するように設計する。


テクスチャ ブレンディング処理と引数

アプリケーションでは、ブレンディング ステージをカレント テクスチャ セットの各テクスチャに関連付ける。「テクスチャ ステージとテクスチャ ブレンディング カスケード」で説明するように、Direct3D では、セットの最初のテクスチャから順に 8 番目のテクスチャまで各ブレンディング ステージを評価する。

[C++]

Direct3D では、カレント テクスチャ セットの各テクスチャの情報を、関連付けられているブレンディング ステージに適用する。アプリケーションでは、IDirect3DDevice7::SetTextureStageState を呼び出して、所定のテクスチャ ステージからどの情報を使用するかを制御する。色チャネルとアルファ チャネルの処理は、個別に設定することができる。各処理では 2 つの引数を使用する。色チャネル処理を指定するには、D3DTSS_COLOROP ステージ ステートを使用し、アルファ処理を指定するには、D3DTSS_ALPHAOP ステージ ステートを使用する。これらはともに、D3DTEXTUREOP 列挙型からの値を使用する。

テクスチャ ブレンディング引数には、D3DTEXTURESTAGESTATETYPE 列挙型の D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHARG1、および D3DTSS_ALPHARG2 メンバを使用する。対応する引数は、テクスチャ引数フラグを使用して識別する。

注 : あるテクスチャ ステージの色処理を D3DTOP_DISABLE に設定することで、そのテクスチャ ステージと、それに続くカスケード内のテクスチャ ブレンディング ステージを無効にすることができる。色処理を無効すると、アルファ処理も同様に無効になる。色処理が有効になっているときに、アルファ処理を無効にすることはできない。色ブレンディングが有効な場合にアルファ処理を D3DTOP_DISABLE に設定すると、不定の処理が発生する。

デバイスでサポートされているテクスチャ ブレンディング処理を調べる、D3DDEVICEDESC7 構造体の dwTextureOpCaps メンバに問い合わせる。

[Visual Basic]

Direct3D では、カレント テクスチャ セットの各テクスチャの情報を、関連付けられているブレンディング ステージに適用する。アプリケーションでは、Direct3DDevice7.SetTextureStageState を呼び出して、所定のテクスチャ ステージからどの情報を使用するかを制御する。色チャネルとアルファ チャネルの処理は、個別に設定することができる。各処理では 2 つの引数を使用する。色チャネル処理を指定するには、D3DTSS_COLOROP ステージ ステートを使用し、アルファ処理を指定するには、D3DTSS_ALPHAOP ステージ ステートを使用する。これらはともに、CONST_D3DTEXTUREOP 列挙からの値を使用する。

テクスチャ ブレンディング引数には、CONST_D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHARG1、および D3DTSS_ALPHARG2 メンバを使用する。対応する引数は、テクスチャ引数フラグを使用して識別する。

注 : あるテクスチャ ステージの色処理を D3DTOP_DISABLE に設定することで、そのテクスチャ ステージと、それに続くカスケード内のテクスチャ ブレンディング ステージを無効にすることができる。色処理を無効すると、アルファ処理も同様に無効になる。色処理が有効になっているときは、アルファ処理を無効にすることはできない。色ブレンディングが有効な場合にアルファ処理を D3DTOP_DISABLE に設定すると、不定の処理が発生する。

デバイスでサポートされているテクスチャ ブレンディング処理を調べるには、D3DDEVICEDESC7 型の lTextureOpCaps メンバに問い合わせる。


ライトの色

Direct3D のライトは、システムによるライティング計算で独立して使用される、ディフューズ色、アンビエント色、およびスペキュラ色の 3 つの色を放射する。それぞれの色は、Direct3D ライティング モジュールによって組み込まれ、現在のマテリアルの色と相互作用し、最終的にレンダリングで使用される色が生成される。ディフューズ色は現在のマテリアルのディフューズ プロパティと相互作用し、スペキュラ色はマテリアルのスペキュラ属性と相互作用する、という具合に処理される (Direct3D でのこれらの色の適用方法については、「Direct3D のライティングにおける数学的計算」を参照すること)。

[C++]

C++ アプリケーションの場合、D3DLIGHT7 構造体にこれらの色を表す 3 つのメンバ dcvDiffuse、dcvAmbient、および dcvSpecular が含まれる。各メンバは、放射する色を定義する D3DCOLORVALUE 構造体である。

[Visual Basic]

Visual Basic の場合、D3DLIGHT7 型にこれらの色を表す 3 つのメンバ dcvDiffuse、dcvAmbient、および dcvSpecular が含まれる。各メンバは、放射する色を定義する D3DCOLORVALUE 型である。

システムの計算負荷が最も大きいのは、ディフューズ色である。最も一般的なディフューズ色は白色 (R:1.0 G:1.0 B:1.0) であるが、希望のエフェクトを出すために必要に応じて色を作成できる。たとえば、暖炉に赤色のライトを使用したり、"Go" になった交通信号に緑色を使用することができる。

一般には、ライトの色成分を 0.0 と 1.0 を含む 0.0 ～ 1.0 の値に設定するが、これ以外の値に設定することもできる。たとえば、すべての成分を 2.0 に設定して、"白色よりも明るい" ライトを作成できる。このような設定は、定数以外の減衰設定を使用するときには特に便利である。

Direct3D ではライトに RGBA 値を使用するが、アルファ成分は使用しない。詳細については、「ライティングとマテリアルのカラー値」を参照すること。


ピクセル フォグについて

ピクセル フォグという名前は、デバイス ドライバでピクセル単位に計算が実行されることから付いている (これは頂点フォグとは異なる。頂点フォグの場合、Direct3D はトランスフォーム & ライティングの実行の際にフォグ エフェクトを計算する)。ドライバがブレンディング計算に適用するフォグ係数 (各ピクセルの深度を使用) を決定するために事前に計算されたルックアップ テーブルを使用するため、ピクセル フォグは、「テーブル フォグ」と呼ばれることもある。

[C++]

ピクセル フォグは、D3DFOGMODE 列挙型のメンバにより識別されるフォグ公式のいずれかを使用して適用する。ピクセル フォグ公式の実装はドライバ固有であり、ドライバが複雑なフォグ公式をサポートしていない場合は、あまり複雑でない公式を使用すること。

[Visual Basic]

ピクセル フォグは、CONST_D3DFOGMODE 列挙のメンバで識別するフォグ公式のいずれかを使用して適用できる。ピクセル フォグ公式の実装はドライバ固有であり、ドライバが複雑なフォグ公式をサポートしていない場合は、あまり複雑でない公式を使用すること。

注 : 「範囲ベースのフォグ」で説明するように、ピクセル フォグは範囲ベースの計算では実行されない。


頂点のマニュアル トランスフォーム

Direct3D アプリケーションでは、3 種類の頂点を使用できる。頂点フォーマットの詳細については、「頂点フォーマット」を参照すること。

[C++]
未トランスフォーム 未ライティングの頂点
アプリケーションでライティングもトランスフォームも適用しない頂点。シーンをレンダリングする前に頂点にトランスフォーム & ライティングを適用しない C++ アプリケーションでは、D3DVERTEX 頂点 (または同等の柔軟な頂点フォーマット) を使用できる。ライティング パラメータやトランスフォーム行列を指定しても、計算は Direct3D が実行する。
未トランスフォーム ライティング済みの頂点
アプリケーションでライティングは適用するが、トランスフォームは適用しない頂点。カスタマイズしたライティング エフェクトを使用する C++ アプリケーションでは、D3DLVERTEX 頂点 (または同等の柔軟な頂点フォーマット) を使用できる。
トランスフォーム済み ライティング済みの頂点
アプリケーションでライティングとトランスフォームの両方を適用する頂点。頂点にライティングとトランスフォームを適用する C++ アプリケーションでは、D3DTLVERTEX 頂点 (または同等の柔軟な頂点フォーマット) を使用できる。これらの頂点はジオメトリ パイプラインでトランスフォームされないが、必要に応じてシステムでクリッピングすることができる。アプリケーション自体で頂点をクリッピングする場合に最も良い方法は、レンダリング メソッドを呼び出すときに D3DDP_DONOTCLIP フラグを指定することである。Direct3D で頂点をクリッピングする場合は、D3DDP_DONOTCLIP フラグは指定しない。ただし、トランスフォーム済みライティング済みの頂点のクリッピングを Direct3D で実行する場合、Direct3D はクリッピングのために頂点を射影空間に逆変換してからスクリーン空間に変換し直すため、処理オーバーヘッドが生じることに注意する。

DirectX 7.0 では、頂点バッファを使用して、単純な頂点タイプを複雑な頂点タイプに変えることができる (旧リリースの DirectX では、アプリケーションで IDirect3DViewport3 インターフェイスの TransformVertices メソッドを呼び出すことができた。DirectX 6.0 で頂点バッファが導入されたことにより、このメソッドは使用されなくなった)。頂点バッファとは、高速なレンダリングを実行するために頂点をまとめて格納してバッチ処理するためのオブジェクトで、プロセッサ固有の機能を利用するように最適化できる。頂点バッファには、自動的に頂点トランスフォームを実行する IDirect3DVertexBuffer7::ProcessVertices および IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドがある。このメソッドは、通常 TransformVertices メソッドよりもはるかに処理が速い。ProcessVertices ファミリのメソッドは未トランスフォームの頂点のみ受け取るが、オプションとして頂点へのライティングの適用とクリッピングが可能である。ライティングは ProcessVertices を呼び出したときに適用されるが、クリッピングが実行されるのはレンダリングのときである。

頂点を処理した後、特別なレンダリング メソッドを使用して頂点をレンダリングしたり、頂点バッファ メモリをロックして頂点に直接アクセスすることができる。頂点バッファの使用の詳細については、「頂点バッファ」を参照すること。

[Visual Basic]
未トランスフォーム 未ライティングの頂点
アプリケーションでライティングとトランスフォームを適用しない頂点。シーンをレンダリングする前に頂点にトランスフォーム & ライティングを適用しない Visual Basic アプリケーションでは、D3DVERTEX 頂点 (または同等の柔軟な頂点フォーマット) を使用できる。ライティング パラメータやトランスフォーム行列を指定しても、計算は Direct3D が実行する。
未トランスフォーム ライティング済みの頂点
アプリケーションでライティングは適用するが、トランスフォームは適用しない頂点。カスタマイズしたライティング エフェクトを使用する Visual Basic アプリケーションでは、D3DLVERTEX 頂点 (または同等の柔軟な頂点フォーマット) を使用できる。
トランスフォーム済み ライティング済みの頂点
アプリケーションでライティングとトランスフォームの両方を適用する頂点。頂点にライティングとトランスフォームを適用する Visual Basic アプリケーションでは、D3DTLVERTEX 頂点 (または同等の柔軟な頂点フォーマット) を使用できる。これらの頂点はジオメトリ パイプラインでトランスフォームされないが、必要に応じてシステムでクリッピングすることができる。アプリケーション自体で頂点をクリッピングする場合に最も良い方法は、レンダリング メソッドを呼び出すときに D3DDP_DONOTCLIP フラグを指定することである。Direct3D で頂点をクリッピングする場合は、D3DDP_DONOTCLIP フラグは指定しない。ただし、トランスフォーム済みライティング済みの頂点のクリッピングを Direct3D で実行する場合、Direct3D はクリッピングのために頂点を射影空間に逆変換してからスクリーン空間に変換し直すため、処理オーバーヘッドが生じることに注意する。

頂点バッファを使用して、単純な頂点タイプを複雑な頂点タイプに変えることができる。頂点バッファとは、高速なレンダリングを実行するために頂点をまとめて格納してバッチ処理するためのオブジェクトで、プロセッサ固有の機能を利用するように最適化できる。頂点バッファには、自動的に頂点トランスフォームを実行する Direct3DVertexBuffer7.ProcessVertices メソッドがある。このメソッドは、通常 TransformVertices メソッドよりもはるかに処理が速い。ProcessVertices メソッドは未トランスフォームの頂点のみ受け取るが、オプションとして頂点へのライティングの適用とクリッピングが可能である。ライティングは ProcessVertices を呼び出したときに適用されるが、クリッピングが実行されるのはレンダリングのときである。

頂点を処理した後、特別なレンダリング メソッドを使用して頂点をレンダリングしたり、頂点バッファ メモリをロックして頂点に直接アクセスすることができる。頂点バッファの使用の詳細については、「頂点バッファ」を参照すること。


ステート ブロックの削除

[C++]

IDirect3DDevice7::DeleteStateBlock は、既存のステート ブロックを削除して、このステート ブロックで使用したメモリの割り当てを解除する。DeleteStateBlock メソッドには、そのパラメータでのみ削除するステート ブロックへのハンドルを受け取る。ステート ブロックを削除すると、そのステート ブロックへのハンドルは無効になり、以後使用することはできない。

[Visual Basic]

Direct3DDevice7.DeleteStateBlock は、既存のステート ブロックを削除して、このステート ブロックで使用したメモリの割り当てを解除する。DeleteStateBlock メソッドには、そのパラメータでのみ削除するステート ブロックへのハンドルを受け取る。ステート ブロックを削除すると、そのステート ブロックへのハンドルは無効になり、以後使用することはできない。


境界色テクスチャ アドレッシング モードについて

[C++]

D3DTEXTUREADDRESS 列挙型の D3DTADDRESS_BORDER メンバで指定する "境界色" テクスチャ アドレッシング モードでは、Direct3D は 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲外のすべてのテクスチャ座標に対して、境界色と呼ばれる任意の色を使用する。

[Visual Basic]

CONST_D3DTEXTUREADDRESS 列挙の D3DTADDRESS_BORDER メンバで指定する "境界色" テクスチャ アドレッシング モードでは、Direct3D は 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲外のすべてのテクスチャ座標に対して、境界色と呼ばれる任意の色を使用する。

次の図にこの処理を示す。この図では、アプリケーションは赤色の境界色を使用してテクスチャをプリミティブに適用するように指定している。

[C++]

アプリケーションでは、IDirect3DDevice7::SetTextureStageState を呼び出して境界色を設定する。この呼び出しの第 1 パラメータには希望のテクスチャ ステージ識別子を設定し、第 2 パラメータには D3DTSS_BORDERCOLOR ステージ ステート値を設定し、第 3 パラメータには新しい RGBA 境界色を設定する。

従来の IDirect3DDevice2 インターフェイスを使用する場合、境界色を設定するには、IDirect3DDevice2::SetRenderState メソッドを呼び出し、D3DRENDERSTATE_BORDERCOLOR レンダリング ステート値と新しい RGBA 境界色をパラメータとして指定する (D3DRENDERSTATE_BORDERCOLOR レンダリング ステートは、現在は使用されていないため、IDirect3DDevice7 インターフェイスでは認識されない)。

[Visual Basic]

Visual Basic アプリケーションでは、Direct3DDevice7.SetTextureStageState を呼び出して境界色を設定する。これを呼び出すときの第 1 パラメータには希望のテクスチャ ステージ識別子を設定し、第 2 パラメータには D3DTSS_BORDERCOLOR ステージ ステート値を設定し、第 3 パラメータには新しい RGBA 境界色を設定する。


スペキュラ反射モデル

[C++]

スペキュラ反射をモデル化するには、光の進行方向だけでなく、ビューアの視線の方向もシステムに知らせる必要がある。システムでは Phong スペキュラ反射モデルの簡易バージョンを使用する。このモデルでは、"中間ベクトル" を使用してスペキュラ反射強度を概算する。中間ベクトルは、光源へのベクトルと視点へのベクトルの間の中間に存在する。Direct3D では、アプリケーションは、D3DRENDERSTATE_LOCALVIEWER レンダリング ステートで制御する 2 種類の方法を使用して中間ベクトルを計算できる。D3DRENDERSTATE_LOCALVIEWER を TRUE に設定すると、システムではライティングの方向ベクトルに加えて、カメラの位置座標と頂点の位置座標を使用して中間ベクトルを計算する。次の公式はこの計算を示す。

この公式では、norm() は入力ベクトルを正規化する演算子、VC はベクトルの位置座標から視点 (目) の位置座標までに存在するベクトル、Ld はライトの方向ベクトルである。

この方法で中間ベクトルを決定する場合、いくらかの計算負荷がかかる。別の方法としては、D3DRENDERSTATE_LOCALVIEWER を FALSE に設定する。この場合、z 軸の無限遠方に視点が存在するとして処理される。この設定は計算負荷は少ないが、正確さで劣る。したがって、この方法は、正射影を使用するアプリケーションに最適である。D3DRENDERSTATE_LOCALVIEWER を FALSE に設定した場合、Direct3D では次の公式を使用して中間ベクトルを計算する。

この公式は最初の公式に類似しているが、ベクトル VC を計算する代わりに、z 軸上の無限遠方にある視点を表すベクトル I (0, 0, -1) を使用している。

中間ベクトル H を求めた後、システムは次の公式を使用してスペキュラ反射を計算する。

この公式では、Rs はスペキュラ反射率、N は頂点法線、H は中間ベクトル、p は現在のマテリアルのスペキュラ反射強度 (マテリアルの D3DMATERIAL7 構造体の dvPower メンバで指定) である。ベクトル H は正規化される。ベクトル N は、D3DRENDERSTATE_NORMALIZENORMALS レンダリング ステートが有効になっている場合にのみ正規化される。

ディフューズ反射公式と同様、この公式の結果は -1.0 ～ 1.0 の範囲の値であり、この値は 0.0 ～ 1.0 の範囲に制限され、頂点から反射されるライティングを計算するために使用される。また、ディフューズ反射モデルと同様、その頂点におけるスペキュラ成分を求める次のような公式にその結果が適用される。

この公式では、Sv は計算されるスペキュラ色、A は距離とスポット ライト エフェクト (「距離の増加によるライトの減衰」および「スポット ライト フォールオフ モデル」を参照すること) によって減衰した単一の光源からの光である。Rs 変数は以前に計算されたスペキュラ反射率、Vs は選択された、頂点のスペキュラ成分、Ls はスペキュラ ライトの色である。

D3DRENDERSTATE_COLORVERTEX レンダリング ステートが有効になっている場合、D3DRENDERSTATE_SPECULARMATERIALSOURCE レンダリング ステートの値に基づいて V の色ソースが選択される。このレンダリング ステートを D3DMATERIALCOLORSOURCE 列挙型のメンバに設定して、現在のマテリアルか、頂点の色成分のいずれかを色ソースとして使用できる。

詳細については、「ディフューズ反射モデル」を参照すること。

[Visual Basic]

スペキュラ反射をモデル化するには、光の進行方向だけでなく、ビューアの視線の方向もシステムに知らせる必要がある。システムでは Phong スペキュラ反射モデルの簡易バージョンを使用する。このモデルでは、"中間ベクトル" を使用してスペキュラ反射強度を概算する。中間ベクトルは、光源へのベクトルと視点へのベクトルの間の中間に存在する。Direct3D では、アプリケーションは、D3DRENDERSTATE_LOCALVIEWER レンダリング ステートで制御する 2 種類の方法を使用して中間ベクトルを計算できる。D3DRENDERSTATE_LOCALVIEWER を True に設定すると、システムではライトの方向ベクトルに加えて、カメラの位置座標と頂点の位置座標を使用して中間ベクトルを計算する。次の公式はこの計算を示す。

この公式では、norm() は入力ベクトルを正規化する演算子、VC はベクトルの位置座標から視点 (目) の位置座標までに存在するベクトル、Ld はライティングの方向ベクトルである。

この方法で中間ベクトルを決定する場合、いくらかの計算負荷がかかる。別の方法としては、D3DRENDERSTATE_LOCALVIEWER を False に設定する。この場合、z 軸の無限遠方に視点が存在するとして処理される。この設定は計算負荷は少ないが、正確さで劣る。したがって、この方法は、正射影を使用するアプリケーションに最適である。D3DRENDERSTATE_LOCALVIEWER を False, Direct3D に設定した場合、Direct3D では次の公式を使用して中間ベクトルを計算する。

この公式は最初の公式に類似しているが、ベクトル VC を計算する代わりに、z 軸上の無限遠方にある視点を表すベクトル I (0, 0, -1) を使用している。

中間ベクトル H を求めた後、システムは次の公式を使用してスペキュラ反射を計算する。

この公式では、Rs はスペキュラ反射率、N は頂点法線、H は中間ベクトル、p は現在のマテリアルのスペキュラ反射強度 (マテリアルの D3DMATERIAL7 型の power メンバで指定) である。ベクトル H は正規化される。ベクトル N は、D3DRENDERSTATE_NORMALIZENORMALS レンダリング ステートが有効になっている場合にのみ正規化される。

ディフューズ反射公式と同様、この公式の結果は -1.0 ～ 1.0 の範囲の値であり、この値は 0.0 ～ 1.0 の範囲に制限され、頂点から反射されるライティングを計算するために使用される。また、ディフューズ反射モデルと同様、その頂点におけるスペキュラ成分を求める公式にその結果が適用される。

この公式では、Sv は計算されるスペキュラ色、A は距離とスポット ライト エフェクト (「距離の増加によるライトの減衰」および「スポット ライト フォールオフ モデル」を参照すること) によって減衰した単一の光源からの光である。Rs 変数は以前に計算されたスペキュラ反射率、Vs は選択された、頂点のスペキュラ成分、Ls はスペキュラ ライトの色である。

D3DRENDERSTATE_COLORVERTEX レンダリング ステートが有効になっている場合、D3DRENDERSTATE_SPECULARMATERIALSOURCE レンダリング ステートの値に基づいて V の色ソースが選択される。このレンダリング ステートを CONST_D3DMATERIALCOLORSOURCE 列挙型のメンバに設定して、現在のマテリアルか、頂点の色成分のいずれかを色ソースとして使用できる。

詳細については、「ディフューズ反射モデル」を参照すること。


バンプ マッピング パラメータの設定

アプリケーションでバンプ マップの作成と各ピクセルの内容の設定が完了したら、バンプ マッピング パラメータを設定してレンダリングの準備を行うことができる。バンプ マッピング パラメータには、必要なテクスチャとそのブレンディング処理や、バンプ マップ自体に対するトランスフォームと輝度の制御などを設定する。

[C++]

C++ でバンプ マッピング パラメータを設定するには:

  1. ベース テクスチャ マップ (使用されている場合)、バンプ マップ、および環境マップ テクスチャをテクスチャ ブレンディング ステージに設定する。
  2. 各テクスチャ ステージの色およびアルファ ブレンディング処理を設定する。
  3. バンプ マップ トランスフォーム行列を設定する。
  4. 必要に応じて、輝度スケール値およびオフセット値を設定する。

次のコードでは、ベース テクスチャ マップ、バンプ マップ、およびスペキュラ環境マップの 3 つのテクスチャを、適切なテクスチャ ブレンディング ステージに設定する。

// 3 つのテクスチャを設定する。
    g_pd3dDevice->SetTexture( 0, lpd3dBaseTexture);
    g_pd3dDevice->SetTexture( 1, lpd3dBumpMap);
    g_pd3dDevice->SetTexture( 2, lpd3dEnvMap);

テクスチャをブレンディング ステージに設定した後、次のコードで、各ステージのブレンディング処理および引数を準備する。

    //
// 色処理および引数を設定してバンプ マッピングを準備する。
    //

// ステージ 0:ベース テクスチャ
    g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLOROP, D3DTOP_MODULATE );
    g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );
    g_pd3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAOP, D3DTOP_SELECTARG1 );
    g_pd3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAARG1, D3DTA_TEXTURE );
    g_pd3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX, 1 );

// ステージ 1:バンプ マップ
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_TEXCOORDINDEX, 1 );
// この例では輝度を使用する。
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_COLOROP, D3DTOP_BUMPENVMAPLUMINANCE);
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_COLORARG2, D3DTA_CURRENT );

// ステージ 2:スペキュラ環境マップ
    g_pd3dDevice->SetTextureStageState( 2, D3DTSS_TEXCOORDINDEX, 0 );
    g_pd3dDevice->SetTextureStageState( 2, D3DTSS_COLOROP, D3DTOP_ADD );
    g_pd3dDevice->SetTextureStageState( 2, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    g_pd3dDevice->SetTextureStageState( 2, D3DTSS_COLORARG2, D3DTA_CURRENT );

ブレンディング処理および引数を設定した後、次のコードで、D3DTSS_BUMPENVMAT00 および D3DTSS_BUMPENVMAT11 テクスチャ ステージ ステートを 1.0 に設定して、2×2 バンプ マッピング行列を単位行列に設定する。行列を単位行列に設定すると、システムでは未修正のバンプ マップのデルタ値が使用されるようになるが、これは必ずしも必要ではない。

// バンプ マッピング行列を設定する。
    //
// 注:
//    これらの呼び出しは、以下のインライン ショートカット関数に依存する。
//       inline DWORD F2DW( FLOAT f ) { return *((DWORD*)&f); }
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT00, F2DW(1.0f) );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT01, F2DW(0.0f) );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT10, F2DW(0.0f) );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT11, F2DW(1.0f) );

バンプ マッピング処理に輝度 (D3DTOP_BUMPENVMAPLUMINANCE) を含める場合は、輝度制御を設定する必要がある。輝度制御により、次のステージのテクスチャから色を調整する前にシステムが行う輝度の計算方法を設定する (詳細については、「バンプ マッピングの公式」を参照すること)。

// 輝度制御を設定する。これは、バンプ マップに輝度が含まれている場合、および
// D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディング処理が使用される場合にのみ
// 必要である。
    //
// 注:
//    これらの呼び出しは、以下のインライン ショートカット関数に依存する。
//       inline DWORD F2DW( FLOAT f ) { return *((DWORD*)&f); }
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVLSCALE, F2DW(0.5f) );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVLOFFSET, F2DW(0.0f) );

アプリケーションでバンプ マッピング パラメータを設定した後は、通常どおりにレンダリングを実行でき、レンダリングされるポリゴンにバンプ マッピング エフェクトが適用される。

[Visual Basic]

Visual Basic でバンプ マッピング パラメータを設定するには:

  1. ベース テクスチャ マップ (使用されている場合)、バンプ マップ、および環境マップ テクスチャをテクスチャ ブレンディング ステージに設定する。
  2. 各テクスチャ ステージの色およびアルファ ブレンディング処理を設定する。
  3. バンプ マップ トランスフォーム行列を設定する。
  4. 必要に応じて、輝度スケール値およびオフセット値を設定する。

次のコードでは、ベース テクスチャ マップ、バンプ マップ、およびスペキュラ環境マップの 3 つのテクスチャを、適切なテクスチャ ブレンディング ステージに設定する。

' 3 つのテクスチャを設定する。
Call g_d3dDevice.SetTexture(0, d3dBaseTexture)
Call g_d3dDevice.SetTexture(1, d3dBumpMap)
Call g_d3dDevice.SetTexture(2, d3dEnvMap)

テクスチャをブレンディング ステージに設定した後、次のコードで、各ステージのブレンディング処理および引数を準備する。

' バンプ マップ テクスチャを作成する。

    '
' 色処理および引数を設定してバンプ マッピングを準備する。
    '

' ステージ 0:ベース テクスチャ
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_ALPHAOP, D3DTOP_SELECTARG1)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_ALPHAARG1, D3DTA_TEXTURE)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, 1)

' ステージ 1:バンプ マップ
Call g_d3dDevice.SetTextureStageState(1, D3DTSS_TEXCOORDINDEX, 1)
' この例では輝度を使用する。
Call g_d3dDevice.SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_BUMPENVMAPLUMINANCE)
Call g_d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call g_d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)

' ステージ 2:スペキュラ環境マップ
Call g_d3dDevice.SetTextureStageState(2, D3DTSS_TEXCOORDINDEX, 0)
Call g_d3dDevice.SetTextureStageState(2, D3DTSS_COLOROP, D3DTOP_ADD)
Call g_d3dDevice.SetTextureStageState(2, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call g_d3dDevice.SetTextureStageState(2, D3DTSS_COLORARG2, D3DTA_CURRENT)

ブレンディング処理および引数を設定した後、次のコードで、D3DTSS_BUMPENVMAT00 および D3DTSS_BUMPENVMAT11 テクスチャ ステージ ステートを 1.0 に設定して、2×2 バンプ マッピング行列を単位行列に設定する。行列を単位行列に設定すると、システムでは未修正のバンプ マップのデルタ値が使用されるようになるが、これは必ずしも必要ではない。

' バンプ マッピング行列を設定する。
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT00, 1#)
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT01, 0#)
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT10, 0#)
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT11, 1#)

バンプ マッピング処理に輝度 (D3DTOP_BUMPENVMAPLUMINANCE) を含める場合は、輝度制御を設定する必要がある。輝度制御により、次のステージのテクスチャから色を調整する前にシステムが行う輝度の計算方法を設定する (詳細については、「バンプ マッピングの公式」を参照すること)。

' 輝度制御を設定する。これは、バンプ マップに輝度が含まれている場合、および
' D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディング処理が使用される場合にのみ
' 必要である。
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVLSCALE, 0.5)
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVLOFFSET, 0#)

アプリケーションでバンプ マッピング パラメータを設定した後は、通常どおりにレンダリングを実行でき、レンダリングされるポリゴンにバンプ マッピング エフェクトが適用される。

注 : この例では、パラメータはスペキュラ環境マッピング用に設定されている。ディフューズ ライト マッピングを行う場合は、最後のステージのテクスチャ ブレンディング処理を D3DTOP_MODULATE に設定する。詳細については、「ディフューズ ライト マップ」を参照すること。


クリップ面の設定と取得

[C++]

ユーザー定義クリップ面は、IDirect3DDevice7::SetClipPlane および IDirect3DDevice7::GetClipPlane メソッドを呼び出して設定および取得する。平面を定義する係数は、4 つの要素を持つ D3DVALUE 型の配列に格納される。

SetClipPlane メソッドは、2 つのパラメータを受け取る。第 1 パラメータには、設定するクリップ面の 0 から始まるインデックスを指定する。第 2 パラメータには、一般平面式の係数を格納するバッファのアドレスを指定する。

注 : SetClipPlane に渡す係数は一般平面式の形をとる。メソッドで渡す配列の値がA、B、C、および D (メモリ内で現れる順序) であるとすると、これらの値はこの式に従い Ax + By + Cz + D = 0 になる。Ax + By + Cz + D >= 0 が成り立つ場合、ワールド空間座標 (x, y, z) の点が平面で区切られた半分の空間に表示される。クリップ面上またはその後方にある点はシーンから切り取られる。

次のコードは、C++ におけるこのメソッドの呼び出し方法を示す。

// この例では、pd3dDevice 変数は IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。

// x<=0 を満たす頂点をクリッピングするように
// クリップ面を設定する。
D3DVALUE clip[4];
ZeroMemory( (LPVOID)clip, sizeof(clip) );

clip[0] = 1.0f;
pd3dDevice->SetClipPlane( 0, clip );

クリップ面の係数を設定しても、その面によるクリッピングが有効になるわけではない。詳細については、「クリップ面の有効/無効」を参照すること。

クリップ面は最大 32 個 (D3DMAXUSERCLIPPLANES) まで定義できる。したがって、SetClipPlane メソッドに渡すことができる最大インデックスは 31 である。無効な値を渡すとメソッドは失敗し、DDERR_INVALIDPARAMS を返す。

IDirect3DDevice7::GetClipPlane メソッドは、意味論的には IDirect3DDevice7::SetClipPlane メソッドに類似したメソッドである。次の C++ コードは、インデックス 2 のクリップ面に現在設定されている係数を取得する。

// この例では、pd3dDevice 変数は IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。

D3DVALUE clip[4];
pd3dDevice->GetClipPlane( 2, clip );
[Visual Basic]

ユーザー定義クリップ面は、Direct3DDevice7.SetClipPlane および Direct3DDevice7.GetClipPlane メソッドを呼び出して設定および取得する。平面を定義する係数は、4 つの要素を持つ D3DVALUE 型の配列に格納される。

SetClipPlane への第 1 パラメータには、設定するクリップ面の 0 から始まるインデックスを指定する。その他のパラメータには、一般平面式の係数を格納する。

注 : SetClipPlane に渡す係数は一般平面式の形をとる。メソッドで渡す配列の値がA、B、C、および D (メモリ内で現れる順序) であるとすると、これらの値はこの式に従い Ax + By + Cz + D = 0 になる。Ax + By + Cz + D >= 0 が成り立つ場合、ワールド空間座標 (x, y, z) の点が平面で区切られた半分の空間に表示される。クリップ面上またはその後方にある点はシーンから切り取られる。

次のコードは、Visual Basic におけるこのメソッドの呼び出し方法を示す。

' この例では、d3dDevice 変数は Direct3DDevice オブジェクトへの
' 有効な参照である。

' x<=0 を満たす頂点をクリッピングするように
' クリップ面を設定する。
Dim A As Single, B As Single, _
C As Single, D As Single

A = 1#

Call d3dDevice.SetClipPlane(0, A, B, C, D)

クリップ面の係数を設定しても、その面によるクリッピングが有効になるわけではない。詳細については、「クリップ面の有効/無効」を参照すること。

クリップ面は最大 32 個 (D3DMAXUSERCLIPPLANES) まで定義できる。したがって、SetClipPlane メソッドに渡すことができる最大インデックスは 31 である。無効な値を渡すとメソッドは失敗し、DDERR_INVALIDPARAMS を返す。

Direct3DDevice7.GetClipPlane メソッドは、意味論的には Direct3DDevice7.SetClipPlane メソッドに類似したメソッドである。次の Visual Basic コードは、インデックス 2 のクリップ面に現在設定されている係数を取得する。

' この例では、d3dDevice 変数は Direct3DDevice オブジェクトへの
' 有効な参照である。

Dim A As Single, B As Single, _
C As Single, D As Single

Call d3dDevice.GetClipPlane(2, A, B, C, D)


頂点フォグについて

システムは頂点フォグを実行するとき、ポリゴンの各頂点にフォグ計算を適用し、次に、ラスタライズの際、ポリゴンの面に結果を補間する。頂点フォグのエフェクトは、Direct3D のライティング & トランスフォーム エンジンによって計算される。詳細については、「フォグ パラメータ」を参照すること。

アプリケーションで Direct3D を使用しないでトランスフォーム & ライティングを実行する場合は、アプリケーションで独自にフォグ計算を行う必要がある。この場合、アプリケーションはフォグ係数を計算して、各頂点のスペキュラ色のアルファ成分に置く。公式には、範囲ベースの公式、体積を利用する公式など、どのようなものでも使用できる。Direct3D は与えられたフォグ係数を使用して、各ポリゴンの面を補間する。Direct3D のトランスフォーム & ライティングを使用しないアプリケーションでは、頂点フォグ パラメータを設定する必要はないが、フォグを有効にし、関連するレンダリング ステートによってフォグ カラーを設定しなければならない。詳細については、「フォグ パラメータ」を参照すること。

注 : アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、それ独自のフォグ計算を実行する必要がある。したがって、そのようなアプリケーションでは、「フォグ ブレンディング」および「フォグ カラー」で説明するように、フォグ ブレンディングを有効にして、関連するレンダリング ステートによってフォグ カラーを設定するだけでよい。


線リスト

Platform SDK: DirectX

線リスト

線リストとは、個々の直線の線分のリストである。線リストは、3D シーンでみぞれや大雨を表現するときなどに便利である。アプリケーションでは、頂点の配列に値を設定して線リストを作成する。線リストの頂点の数は、2 以上の偶数でなければならない。

[C++]

次のコードは、C++ でこのタスクを実行する方法を示す。

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0),D3DVECTOR(0,0,-1),0,0);

IDirect3DDevice7::DrawPrimitive メソッドを使用して線リストをレンダリングする。次のコードは、IDirect3DDevice7::DrawPrimitive を使用して、上の例の線リストを描画する方法を示す。IDirect3DDevice7::DrawPrimitive の呼び出しは、IDirect3DDevice7::BeginScene と IDirect3DDevice7::EndScene の間で行う必要がある。

HRESULT hResult;
// このコードでは、lpDirect3DDevice が IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_LINELIST,
                                      D3DFVF_VERTEX,
                                      lpVerts,
                                      TOTAL_VERTS,
                                      D3DDP_WAIT);
[Visual Basic]

Visual Basic アプリケーションでは、次のコードで示すように、配列に値を格納する。

' このコードでは、dx が DirectX7 オブジェクトへの
' 有効な参照であるとする。
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

Direct3DDevice7.DrawPrimitive メソッドを使用して点リストをレンダリングする。次のコードは、Direct3DDevice7.DrawPrimitive を使用して、上の例の線リストを描画する方法を示す。Direct3DDevice7.DrawPrimitive の呼び出しは、Direct3DDevice7.BeginScene と Direct3DDevice7.EndScene の間で行う必要がある。

' このコードでは、d3ddev が Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
Call d3ddev.DrawPrimitive(D3DPT_LINELIST, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
                          D3DDP_WAIT)

If Err.Number <> DD_OK Then
' エラー処理コード
End If

次の図は、結果として描画される線を示す。

線リストにはマテリアルとテクスチャを適用できる。マテリアルまたはテクスチャの色は、描画された線に沿ってのみ表示され、線と線の間には表示されない。


カリング ステート

Direct3D では、プリミティブをレンダリングするときにプリミティブの背面が切り抜かれる。

[C++]

C++ アプリケーションでカリング モードを設定するには、D3DCULL 列挙型を使用する。「D3DRENDERSTATE_CULLMODE」を参照すること。デフォルトでは、反時計回りの頂点を持つ背面が切り抜かれる。

次のサンプル コードは、時計回りの頂点を持つ背面を切り抜くカリング モードを設定する処理を示す。

// このコードでは、lpDirect3DDevice は IDirect3DDevice インターフェイスへの
// 有効なポインタであるとする。

// カリング ステートを設定する。
lpD3DDevice->SetRenderState(D3DRENDERSTATE_CULLMODE,
                            D3DCULL_CW);
[Visual Basic]

Visual Basic アプリケーションでカリング モードを設定するには、CONST_D3DCULL 列挙のメンバを設定できる D3DRENDERSTATE_CULLMODE レンダリング ステートを使用する。デフォルトでは、反時計回りの頂点を持つ背面が切り抜かれる。

次のサンプル コードは、時計回りの頂点を持つ背面を切り抜くカリング モードを設定する処理を示す。

' このコードでは、
' D3DDevice に Direct3DDevice オブジェクトへの参照が格納されているとする。

' カリング ステートを設定する。
Call D3DDevice.SetRenderState(D3DRENDERSTATE_CULLMODE, _
                              D3DCULL_CW)


テクスチャ境界

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic の場合、Direct3DDevice7.SetTextureStageState メソッドで D3DTSS_BORDERCOLOR テクスチャ ステージ ステートを設定して、テクスチャ境界での処理を設定する必要がある。

[C++]

D3DRENDERSTATE_BORDERCOLOR レンダリング ステートは、現在は使用されていない。これは、IDirect3DDevice7::SetTextureStageState メソッドがサポートする D3DTSS_BORDERCOLOR テクスチャ ステージ ステートに置き換えられている。詳細については、「境界色テクスチャ アドレッシング モードについて」を参照すること。

注 : D3DRENDERSTATE_BORDERCOLOR レンダリング ステートは、IDirect3DDevice7 インターフェイスでは認識されない。このレンダリング ステートを IDirect3DDevice7 インターフェイスで使用すると失敗する。


シェーディング ステート

[C++]

Direct3D では、フラット シェーディングとグーロー シェーディングの両方をサポートしている。デフォルトではグーロー シェーディングが設定される。現在のシェーディング モードを制御するために、C++ アプリケーションでは D3DSHADEMODE 列挙型を使用する。「D3DRENDERSTATE_SHADEMODE」を参照すること。

次の C++ コードは、シェーディング ステートをフラット シェーディング モードに設定する処理を示す。

// このコードでは、lpD3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。

// シェーディング ステートを設定する。
lpD3DDevice->SetRenderState(D3DRENDERSTATE_SHADEMODE,
                            D3DSHADE_FLAT);
[Visual Basic]

Direct3D では、フラット シェーディングとグーロー シェーディングの両方をサポートしている。デフォルトではグーロー シェーディングが設定される。Visual Basic アプリケーションで現在のシェーディング モードを制御するには、CONST_D3DSHADEMODE 列挙型を使用する。「D3DRENDERSTATE_SHADEMODE」を参照すること。

次のコードは、シェーディング ステートをフラット シェーディング モードに設定する処理を示す。

' この例では、D3DDevice は Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。

' シェーディング ステートを設定する。
Call D3DDevice.SetRenderState(D3DRENDERSTATE_SHADEMODE, D3DSHADE_FLAT)


カラー ライティング マップ

一般に、カラー ライティング マップを使用すれば、3D シーンをよりリアルにレンダリングできる。カラー ライティング マップは、ライティング情報としてライト マップのRGB データを使用する。

[C++]

次の C++ コードは、RGB 色データを使用したライト マッピングを示す。

// この例では、lpD3DDev は IDirect3DDevice7 インターフェイスへの有効なポインタで、
// lptexLightMap は RGB ライト マップ データを含むテクスチャへの
// 有効なポインタであるとする。

// ライト マップ テクスチャを最初のテクスチャとして設定する。
lpD3DDev->SetTexture(0, lptexLightMap);

lpD3DDev->SetTextureStageState(0,D3DTSS_COLOROP,
       D3DTOP_MODULATE);

lpD3DDev->SetTextureStageState(0,D3DTSS_COLORARG1,
       D3DTA_TEXTURE);

lpD3DDev->SetTextureStageState(0,D3DTSS_COLORARG2,
       D3DTA_DIFFUSE);

この例では、ライト マップを最初のテクスチャとして設定している。その次に、最初のブレンディング ステージのステートを設定して、入力テクスチャ データを調整している。また、最初のテクスチャとプリミティブのカレント カラーを調整処理用の引数として使用している。

[Visual Basic]

次の Visual Basic コードは、RGB 色データを使用したライト マッピングを示す。

' この例では、D3DDev は Direct3DDevice7 オブジェクトへの有効な参照で、
' texLightMap は RGB ライト マップ データを含む DirectDrawSurface7 テクスチャ サーフェスへの
'有効なポインタであるとする。

' ライト マップ テクスチャを最初のテクスチャとして設定する。
Call d3dDev.SetTexture(0, texLightMap)

Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, _
D3DTOP_MODULATE );

Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, _
D3DTA_TEXTURE);

Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG2, _
D3DTA_DIFFUSE);

この例では、ライト マップを最初のテクスチャとして設定している。その次に、最初のブレンディング ステージのステートを設定して、入力テクスチャ データを調整している。また、最初のテクスチャとプリミティブのカレント カラーを調整処理用の引数として使用している。


ミップマップの選択と表示

[C++]

IDirect3DDevice7::SetTexture メソッドを呼び出して、カレント テクスチャの一覧内の先頭のテクスチャとしてミップマップ テクスチャを設定する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

ミップマップ テクスチャ セットを選択した後、D3DTEXTUREMIPFILTER 列挙型からの値を D3DTSS_MIPFILTER テクスチャ ステージ ステートに割り当てなければならない。これにより、Direct3D ではミップマップ テクスチャ フィルタリングを自動的に実行する。

また、IDirectDrawSurface7::GetAttachedSurface メソッドを使用し、DDSCAPS2 構造体の DDSCAPS_MIPMAP および DDSCAPS_TEXTURE フラグを指定することで、ミップマップ サーフェスのチェーンを手動でトラバースできる。次の例では、最高解像度から最低解像度までミップマップ チェーンをトラバースする。

LPDIRECTDRAWSURFACE7 lpDDLevel, lpDDNextLevel;
DDSCAPS2 ddsCaps;
HRESULT ddres;

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))
{
// エラー処理コード
}
.
.
.

チェーンの各サーフェスにビットマップ データをロードするために、アプリケーションではミップマップ チェーンを手動でトラバースする必要がある。通常、この理由からチェーンをトラバースする。

Direct3D では、ミップマップ チェーンのレベルの数を明示的に格納する。アプリケーションでミップマップのサーフェス情報を取得すると (IDirectDrawSurface7::Lock または IDirectDrawSurface7::GetSurfaceDesc メソッドを呼び出す)、DDSURFACEDESC2 構造体の dwMipMapCount メンバに、最上位レベルを含めミップマップのレベルの数が格納される。ミップマップの最上位レベル以外のレベルについては、dwMipMapCount メンバが、そのミップマップから最小ミップマップまでのレベルの数を指定する。

[Visual Basic]

Direct3DDevice7.SetTexture メソッドを呼び出して、カレント テクスチャの一覧内の先頭のテクスチャとしてミップマップ テクスチャを設定する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

ミップマップ テクスチャ セットを選択した後、CONST_D3DTEXTUREMIPFILTER 列挙型からの値を D3DTSS_MIPFILTER テクスチャ ステージ ステートに割り当てなければならない。これにより、Direct3D ではミップマップ テクスチャ フィルタリングを自動的に実行する。

また、DirectDrawSurface7.GetAttachedSurface メソッドを使用し、DDSCAPS2 型の DDSCAPS_MIPMAP および DDSCAPS_TEXTURE フラグを指定することで、ミップマップ サーフェスのチェーンを手動でトラバースできる。次の例では、最高解像度から最低解像度までミップマップ チェーンをトラバースする。

On Local Error Resume Next

Dim DDLevel As DirectDrawSurface7, _
DDNextLevel As DirectDrawSurface7

Dim ddsCaps As DDSCAPS2

DDLevel = DDMipMap
ddsCaps.lCaps = DDSCAPS_TEXTURE Or DDSCAPS_MIPMAP
While Err.Number = DD_OK
' このレベルを処理する。
    ' .
    ' .
    ' .
Set DDNextLevel = DDLevel.GetAttachedSurface(ddsCaps)
DDLevel = DDNextLevel
Wend
If ((Err.Number <> DD_OK) And (Err.Number <> DDERR_NOTFOUND)) Then
' エラー処理コード
End If
.
.
.

チェーンのミップマップ サーフェスの各サーフェスにビットマップ データをロードするために、アプリケーションではミップマップ チェーンを手動でトラバースする必要がある。通常、この理由からチェーンをトラバースする。

Direct3D では、ミップマップ チェーンのレベルの数を明示的に格納する。アプリケーションでミップマップのサーフェス情報を取得すると (DirectDrawSurface7.Lock または DirectDrawSurface7.GetSurfaceDesc メソッドを呼び出す)、DDSURFACEDESC2 型の lMipMapCount メンバに、最上位レベルを含めミップマップのレベルの数が格納される。ミップマップの最上位レベル以外のレベルについては、lMipMapCount メンバが、そのミップマップから最小ミップマップまでのレベルの数を指定する。


テクスチャ座標トランスフォームを有効にする [C++]

Platform SDK: DirectX
テクスチャ座標トランスフォームを有効にする [C++]

D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートは、テクスチャ座標トランスフォームの適用を制御する。このテクスチャ ステージ ステートの値は、D3DTEXTURETRANSFORMFLAGS 列挙型で定義される。

D3DTSS_TEXTURETRANSFORMFLAGS が D3DTTFF_DISABLE (デフォルト値) に設定されているときは、テクスチャ座標トランスフォームは無効である。テクスチャ座標トランスフォームがステージ 0 に対して有効な場合、次のコードはこれを無効にする。

// この例では、lpd3dDevice 変数に IDirect3DDevice7 インターフェイスへの
// 有効なポインタが格納されている。

lpd3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_DISABLE);

D3DTEXTURETRANSFORMFLAGS に定義されているその他の値は、テクスチャ座標トランスフォームを有効にするため、および結果として生成されるテクスチャ座標の要素をラスタライザに渡たす個数を制御するために使用する。例として次のコードを考える。

// この例では、lpd3dDevice 変数に IDirect3DDevice7 インターフェイスへの
// 有効なポインタが格納されている。

lpd3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2);

D3DTTFF_COUNT2 値によって、テクスチャ ステージ 0 用のトランスフォーム行列セットを適用し、トランスフォーム後のテクスチャ座標の最初の 2 つの要素をラスタライザに渡すようシステムに指示する。

D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグは、射影されるテクスチャの座標を示す。このフラグが指定されている場合、ラスタライザはトランスフォーム対象の要素を最後の要素で除算する。例として次のコードを考える。

// この例では、lpd3dDevice 変数に IDirect3DDevice7 インターフェイスへの
// 有効なポインタが格納されている。

lpd3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS,
D3DTTFF_COUNT3 | D3DTTFF_PROJECTED );

このコードでは、3 つのテクスチャ座標要素をラスタライザに渡すようにシステムに知らせる。ラスタライザでは、最初の 2 つの要素を 3 つ目の要素で除算して、テクスチャの処理に必要な 2D テクスチャ座標を生成する。

[Visual Basic]

D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートは、テクスチャ座標トランスフォームの適用を制御する。このテクスチャ ステージ ステートの値は、CONST_D3DTEXTURETRANSFORMFLAGS 列挙で定義されている。

D3DTSS_TEXTURETRANSFORMFLAGS が D3DTTFF_DISABLE (デフォルト値) に設定されているときは、テクスチャ座標トランスフォームは無効である。テクスチャ座標トランスフォームがステージ 0 に対して有効な場合、次のコードはこれを無効にする。

' この例では、d3dDevice 変数に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納されている。

Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
D3DTTFF_DISABLE)

CONST_D3DTEXTURETRANSFORMFLAGS に定義されているその他の値は、テクスチャ座標トランスフォームを有効にするため、および結果として生成されるテクスチャ座標の要素をラスタライザに渡たす個数を制御するために使用する。例として次のコードを考える。

' この例では、d3dDevice 変数に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納されている。

Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
D3DTTFF_COUNT2)

D3DTTFF_COUNT2 値は、テクスチャ ステージ 0 用のトランスフォーム行列セットを適用し、トランスフォーム後のテクスチャ座標の最初の 2 つの要素をラスタライザに渡すようシステムに指示する。

D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグは、射影されるテクスチャの座標を示す。このフラグが指定されている場合、ラスタライザはトランスフォーム対象の要素を最後の要素で除算する。例として次のコードを考える。

' この例では、d3dDevice 変数に IDirect3DDevice7 インターフェイスへの
// 有効なポインタが格納されている。

Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
D3DTTFF_COUNT3 | D3DTTFF_PROJECTED)

このコードでは、3 つのテクスチャ座標要素をラスタライザに渡すようにシステムに知らせる。ラスタライザでは、最初の 2 つの要素を 3 つ目の要素で除算して、テクスチャの処理に必要な 2D テクスチャ座標を生成する。


面マスク ステート

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。

[C++]

注 : D3DRENDERSTATE_PLANEMASK レンダリング ステートは、DirectX 7.0 リリースでは使用されない。アルファ ブレンディングによる色バッファへの書き込みを無効にするには、D3DRENDERSTATE_SRCBLEND を D3DBLEND_ZERO に設定し、D3DRENDERSTATE_DESTBLEND を D3DBLEND_ONE に設定する。


テクスチャ パースペクティブ ステート

[C++]

アプリケーションでは、パースペクティブ補正をテクスチャに適用することで、ビューアから遠ざかるにつれてサイズが小さくなるプリミティブにテクスチャを正しく適用できる。「D3DRENDERSTATE_TEXTUREPERSPECTIVE」を参照すること。

次のコードは、テクスチャ パースペクティブ補正を有効にする処理を示す。

// このコードでは、lpD3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。

// テクスチャ パースペクティブを有効にする。
lpD3DDevice7->SetRenderState(D3DRENDERSTATE_TEXTUREPERSPECTIVE,
                             TRUE);

IDirect3DDevice3 およびIDirect3DDevice7 インターフェイスでは、デフォルト値が TRUE になり、パースペクティブ補正テクスチャ マッピングが有効になる。旧インターフェイスの場合、デフォルト値は FALSE である。多くの 3D アダプタは、テクスチャ パースペクティブ補正を無条件に適用するので注意が必要である。w ベース フォグおよび w バッファを使用するには、パースペクティブ補正を有効にする必要がある。詳細については、「フォグ」セクションの「視点からの相対深度 対 Z ベースの深度」および「深度バッファ」セクションの「深度バッファリングの有効化」を参照すること。

[Visual Basic]

アプリケーションでは、パースペクティブ補正をテクスチャに適用することで、ビューアから遠ざかるにつれてサイズが小さくなるプリミティブにテクスチャを正しく適用できる。「D3DRENDERSTATE_TEXTUREPERSPECTIVE」を参照すること。

次のコードは、テクスチャ パースペクティブ補正を有効にする処理を示す。

' このコードでは、d3dD3DDevice は Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。

' テクスチャ パースペクティブを有効にする。
Call d3dDevice7.SetRenderState(D3DRENDERSTATE_TEXTUREPERSPECTIVE, _
                               True)

デフォルト値は True で、パースペクティブ補正テクスチャ マッピングが有効になる。

多くの 3D アダプタは、テクスチャ パースペクティブ補正を無条件に適用するので注意が必要である。w ベース フォグおよび w バッファを使用するには、パースペクティブ補正を有効にする必要がある。詳細については、「フォグ」セクションの「視点からの相対深度 対 Z ベースの深度」および「深度バッファ」セクションの「深度バッファリングの有効化」を参照すること。


テクスチャ座標トランスフォーム

ここでは、Direct3D 直接モードで提供されるテクスチャ座標トランスフォーム機能の操作について説明する。

  • テクスチャ座標トランスフォームについて
  • テクスチャ座標トランスフォームの設定と取得
  • テクスチャ座標トランスフォームを有効にする


ブレンディング ステージの作成

[C++]

ブレンディング ステージとは、引数を使用してテクスチャのブレンディング方法を定義する、一連のテクスチャ処理である。ブレンディング ステージを作成するとき、C++ アプリケーションでは IDirect3DDevice7::SetTextureStageState メソッドを呼び出す。最初の呼び出しで、実行する処理を指定する。さらに 2 回の呼び出しで、処理を適用する引数を定義する。次のコードは、ブレンディング ステージの作成方法を示す。

// この例では、lpD3DDev が IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。

// 最初のテクスチャの処理を設定する。
lpD3DDev->SetTextureStageState(0,D3DTSS_COLOROP,D3DTOP_ADD);

// テクスチャ処理用の arg1 を設定する。
lpD3DDev->SetTextureStageState(0, // 最初のテクスチャ。
       D3DTSS_COLORARG1,  // 色引数 1 を設定する。
       D3DTA_TEXTURE);    // 色引数 1 の値。

// テクスチャ処理用の arg2 を設定する。
lpD3DDev->SetTextureStageState(0, // 最初のテクスチャ。
       D3DTSS_COLORARG2,  // 色引数 2 を設定する。
       D3DTA_DIFFUSE);    // 色引数 2 の値。

テクスチャのテクセル データには、カラー値とアルファ値が含まれる。プログラムでは、単一のブレンディング ステージでカラー値とアルファ値の両方を定義できる。色処理とアルファ処理には、それぞれ独自の引数がある。詳細については、「D3DTEXTURESTAGESTATETYPE」を参照すること。

次のマクロは Direct3D API の一部ではないが、プログラムに挿入してテクスチャ ブレンディング ステージの作成に必要なコードを短縮できる。

#define SetTextureColorStage( dev, i, arg1, op, arg2 )       \
   dev->SetTextureStageState( i, D3DTSS_COLOROP, op);\
   dev->SetTextureStageState( i, D3DTSS_COLORARG1, arg1 );   \
   dev->SetTextureStageState( i, D3DTSS_COLORARG2, arg2 );

#define SetTextureAlphaStage( dev, i, arg1, op, arg2 )       \
   dev->SetTextureStageState( i, D3DTSS_ALPHAOP, op);\
   dev->SetTextureStageState( i, D3DTSS_ALPHARG1, arg1 );    \
   dev->SetTextureStageState( i  D3DTSS_ALPHARG2, arg2 );
[Visual Basic]

ブレンディング ステージとは、引数を使用してテクスチャのブレンディング方法を定義する、一連のテクスチャ処理である。ブレンディング ステージを作成するとき、Visual Basic アプリケーションでは Direct3DDevice7.SetTextureStageState メソッドを呼び出す。最初の呼び出しで、実行する処理を指定する。さらに 2 回の呼び出しで、処理を適用する引数を定義する。次のコードは、ブレンディング ステージの作成方法を示す。

' この例では、d3dDev は Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。

' 最初のテクスチャの処理を設定する。
Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_ADD)

' arg1 をテクスチャ色に設定する。
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)

' arg2 を、繰り返すディフューズ色に設定する。
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

テクスチャのテクセル データには、カラー値とアルファ値が含まれる。プログラムでは、単一のブレンディング ステージでカラー値とアルファ値の両方を定義できる。色処理とアルファ処理には、それぞれ独自の引数がある。詳細については、「CONST_D3DTEXTURESTAGESTATETYPE」を参照すること。


範囲ベースのフォグ

Direct3D では、Direct3D のトランスフォーム & ライティング エンジンで頂点フォグを使用する場合にのみ、範囲ベースのフォグの計算を実行する。これは、ピクセル フォグはデバイス ドライバに実装され、現在のところ、ピクセル単位の範囲ベースのフォグをサポートするハードウェアは存在しないためである。アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、範囲ベースの計算かその他の計算による独自のフォグ計算を行う必要がある。

フォグを使用すると、オブジェクトがフォグ カラーと直感的でない方法でブレンドされるために生じる不自然なグラフィックス効果が見えることがある。たとえば、2 つのオブジェクトが見えていて、一方はフォグの影響を受けるくらいに遠くにあり、他方は影響されないくらいに近くにあるというシーンを想定する。表示領域が同じ場所で回転した場合、オブジェクトが静止していたとしても、現れるフォグ エフェクトは変化することがある。次の図はこうした状況を見下ろしたステートを示す。

範囲ベースのフォグは、フォグ エフェクトをより正確に決定する方法である。範囲ベースのフォグでは、Direct3D は視点から頂点までの実際の距離をフォグの計算に使用して、シーンの範囲内での頂点の深度ではなく 2 点間の距離の増加に従ってフォグのエフェクトを増加するため、不自然な回転効果が回避される。

[C++]

現在のデバイスが範囲ベースのフォグをサポートしている場合、IDirect3DDevice7::GetCaps メソッドを呼び出したときに、デバイスは D3DPRIMCAPS 構造体の dwRasterCaps メンバに D3DPRASTERCAPS_FOGRANGE 能力フラグを設定する。範囲ベースのフォグを有効にするには、D3DRENDERSTATE_RANGEFOGENABLE レンダリング ステートを TRUE に設定する。

[Visual Basic]

現在のデバイスが範囲ベースのフォグをサポートしている場合、Direct3DDevice7.GetCaps メソッドを呼び出すと、デバイスは D3DPRIMCAPS 型の lRasterCaps メンバに D3DPRASTERCAPS_FOGRANGE 能力フラグを設定する。範囲ベースのフォグを有効にするには、D3DRENDERSTATE_RANGEFOGENABLE レンダリング ステートを TRUE に設定する。

範囲ベースのフォグは、Direct3D により、トランスフォーム & ライティングの間に計算される。「頂点フォグについて」で説明したように、Direct3D トランスフォーム & ライティング エンジンを使用しないアプリケーションは、独自に頂点フォグの計算も行わなければならない。この場合、範囲ベースのフォグ係数を、各頂点のスペキュラ成分のアルファ成分に設定する。


モノクロ ライト マップ

一部の古い 3D アクセラレータ ボードでは、転送先ピクセルのアルファ値を使用するテクスチャ ブレンディングをサポートしていない場合がある (「アルファ テクスチャ ブレンディング」を参照すること)。これらのアダプタでは、一般にマルチ テクスチャ ブレンディングもサポートしていない。このようなアダプタでアプリケーションを実行する場合は、マルチパス テクスチャ ブレンディングを使用してモノクロ ライト マッピングを実行できる。

モノクロ ライト マッピングを実行するには、アプリケーションでライティング情報をライト マップ テクスチャのアルファ データに格納する。プログラムは、Direct3D のテクスチャ フィルタリング機能を使用して、プリミティブ画像の各ピクセルから、ライト マップの対応するテクセルへのマッピングを実行する。プログラムで、転送元ブレンディング係数を対応するテクセルのアルファ値に設定する。

[C++]

次の C++ コードは、アプリケーションでテクスチャをモノクロ ライト マップとして使用する方法を示す。

// この例では、lpD3DDev は IDirect3DDevice7 インターフェイスへの有効なポインタで、
// lptexLightMap はモノクロ ライト マップ データを含むテクスチャへの
// 有効なポインタであるとする。

// ライト マップ テクスチャをカレント テクスチャとして設定する。
lpD3DDev->SetTexture(0,lptexLightMap);

// 色処理を設定する。
lpD3DDev->SetTextureStageState(0,D3DTSS_COLOROP,
       D3DTOP_SELECTARG1);

// 引数 1 を色処理に設定する。
lpD3DDev->SetTextureStageState(0,D3DTSS_COLORARG1,
       D3DTA_TEXTURE | D3DTA_ALPHAREPLICATE);
[Visual Basic]

次の Visial Basic コードは、アプリケーションでテクスチャをモノクロ ライト マップとして使用する方法を示す。

' この例では、d3dDev は Direct3DDevice7 オブジェクトへの有効な参照であり、
' texLightMap はモノクロ ライト マップ データを含む DirectDrawSurface7 テクスチャへの
' 有効な参照であるとする。

' ライト マップ テクスチャをカレント テクスチャとして設定する。
Call d3dDev.SetTexture(0, texLightMap)

' 色処理を設定する。
Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, _
D3DTOP_SELECTARG1);

' 引数 1 を色処理に設定する。
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, _
D3DTA_TEXTURE | D3DTA_ALPHAREPLICATE);

転送先アルファ ブレンディングをサポートしていないディスプレイ アダプタは、通常マルチ テクスチャ ブレンディングをサポートしていないので、この例では、すべての 3D アクセラレータ カードで使用できるライト マップを最初のテクスチャとして設定している。また、この例では、テクスチャのブレンディング ステージに対するカラー値を設定して、テクスチャ データをプリミティブの既存の色とブレンドしている。その次に、入力データとして最初のテクスチャとプリミティブの既存の色を選択している。


グーロー シェーディング

Direct3D では、ポリゴンをグーロー シェーディングでレンダリングするとき、頂点の法線パラメータおよびライティング パラメータを使用して各頂点の色を計算する。そして、ポリゴンの面全体にわたって色が補間される (「面法線ベクトルと頂点法線ベクトル」を参照すること)。補間は線形的に行われる。たとえば、頂点 1 の色の赤成分が 0.8 で頂点 2 の赤成分が 0.4 の場合、Direct3D のライティング モジュールは、グーロー シェーディング モードおよび RGB 色モデルを利用して、2 つの頂点の間の線の中間点にあたるピクセルに 0.6 の赤成分を割り当てる。

次の図はグーロー シェーディングを示す。このティーポットは、多数の平坦な三角形のポリゴンで構成されている。しかし、グーロー シェーディングを使用すると、このオブジェクトのサーフェスは滑らかな曲面のようになる。

グーロー シェーディング モードで、鋭いエッジを持つオブジェクトを表示することもできる。詳細については、「面法線ベクトルと頂点法線ベクトル」を参照すること。


ストライド頂点のレンダリング

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、ストライド頂点のレンダリングはサポートしていない。

[C++]

ストライド頂点は間接的な技法なので、アプリケーションで頂点を適切に設定するには注意が必要がある。詳細については、「ストライド頂点フォーマット」セクションを参照すること。開発者は、頂点成分を D3DDRAWPRIMITIVESTRIDEDDATA 構造体に格納していないことが多い。このような場合でも、レンダリング メソッドが必ずしも失敗するわけではないが、ジオメトリが「失われる」可能性があり、トラブルシューティングが困難になる。

次のコードは、ストライド頂点を設定してレンダリングする方法を示す。

//---------------------------------------------
// XYZ、ディフューズ色、および 2 組のテクスチャ座標を含む
// カスタム頂点フォーマット。
//---------------------------------------------
struct MTVERTEX
{
    FLOAT x, y, z;
    DWORD dwColor;
    FLOAT tuBase, tvBase;
    FLOAT tuLightMap, tvLightMap;
};

// カスタム頂点の配列を作成する。
MTVERTEX g_avVertices[36];
// 配列に頂点を格納する。
//  (インデックス 0 の頂点)
//  .
//  .
//  .
//  (インデックス 35 の頂点)

// 定義済みカスタム頂点の配列を使用して、
// ストライド頂点を構築する。
D3DDRAWPRIMITIVESTRIDEDDATA g_StridedData;

// 交互に配置した各種コンポーネントのアドレスを
// 対応するストライド メンバに割り当てる。
g_StridedData.position.lpvData          = &g_avWallVertices[24].x;
g_StridedData.diffuse.lpvData           = &g_avWallVertices[24].dwColor;
g_StridedData.textureCoords[0].lpvData  = &g_avWallVertices[24].tuBase;
g_StridedData.textureCoords[1].lpvData  = &g_avWallVertices[24].tuLightMap;
g_StridedData.position.dwStride         = sizeof(MTVERTEX);
g_StridedData.diffuse.dwStride          = sizeof(MTVERTEX);
g_StridedData.textureCoords[0].dwStride = sizeof(MTVERTEX);
g_StridedData.textureCoords[1].dwStride = sizeof(MTVERTEX);

// 複数のテクスチャ ブレンディング (調整) で頂点をレンダリングする。
g_pd3dDevice->SetTextureStageState( 1, D3DTSS_COLOROP, D3DTOP_MODULATE );
g_pd3dDevice->SetTexture( 0, g_BaseTextureMap);
g_pd3dDevice->SetTexture( 1, g_LightMap);
g_pd3dDevice->DrawPrimitiveStrided( D3DPT_TRIANGLELIST,
                        D3DFVF_XYZ|D3DFVF_DIFFUSE|D3DFVF_TEX2,
                        &g_StridedData, 12, NULL );


球体環境マップのテクスチャ座標

環境マッピングの対象となる各頂点に指定するテクスチャ座標は、テクスチャを湾曲したサーフェスに映るゆがみの関数として処理する必要がある。アプリケーションでは、各頂点のテクスチャ座標を計算して、希望のエフェクトを実現しなければならない。テクスチャ座標を簡単かつ効果的に生成する方法は、頂点法線を入力として使用することである。方法には何種類かあるが、次の公式は、球体マップによる環境マッピングを実行するアプリケーションで共通の公式である。

この公式では、u および v は計算するテクスチャ座標、Nx および Ny はカメラ空間の頂点法線の x および y 成分である。この公式は単純であるが、有効である。法線に正方向の x 成分がある場合、法線は右方向を指しており、u 座標はテクスチャを適切に処理できるように調整される。v 座標も同様、正方向の y は、法線が上方向を指していることを示す。もちろん、各成分の負の値に対してはこの反対が成り立つ。

法線が直接カメラを指している場合、結果の座標にはゆがみが生じない。両方の座標に +0.5 バイアスを加えると、ゆがみのない点は球体マップの中央に配置され、(0, 0, z) の頂点法線によってこの点が処理される。この公式では、法線の z 成分は考慮されないことに注意する。ただし、この公式を使用するアプリケーションでは、正方向の z 要素のある法線を持つ頂点を省略することで計算を最適化できる。このような処理が行われるのは、カメラ空間で法線がカメラから離れる方向 (z の正方向) を指している場合に、オブジェクトのレンダリング時に頂点が省かれるためである。


テクスチャ フィルタリング ステート

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic の場合、アプリケーションでは、Direct3DDevice7.SetTextureStageState メソッドを使用して、テクスチャフィルタリング処理を設定する必要がある。

[C++]

注 : 従来のレンダリング ステート D3DRENDERSTATE_TEXTUREMAG、D3DRENDERSTATE_TEXTUREMIN、および D3DRENDERSTATE_ANISOTROPY は、DirectX 7.0 リリースでは使用されない。

アプリケーションでは、D3DTSS_MAGFILTER、D3DTSS_MINFILTER、および D3DTSS_MAXANISOTROPY テクスチャ ステージ ステートを使用して、テクスチャ フィルタリングを制御する必要がある。


テクスチャ座標の自動生成の構成

Platform SDK: DirectX

テクスチャ座標の自動生成の構成

[C++]

C++ の場合、(D3DTEXTURESTAGESTATETYPE 列挙型からの) D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを使用して、テクスチャ座標の生成方法を制御する。

[Visual Basic]

Visual Basic の場合、(CONST_D3DTEXTURESTAGESTATETYPE 列挙からの) D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを使用して、テクスチャ座標の生成方法を制御する。

通常、このステートは、頂点フォーマットで符号化された特定のテクスチャ座標セットを使用するようシステムに知らせる。このステートに割り当てる値の中に、D3DTSS_TCI_CAMERASPACENORMAL、D3DTSS_TCI_CAMERASPACEPOSITION、または D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグを含めた場合、システムで実行される処理は大きく異なってくる。これらのフラグのいずれかでも存在しているとき、テクスチャ ステージは頂点フォーマットのテクスチャ座標を無視し、システムが生成する座標を優先する。各フラグの意味は、次のとおりである。

D3DTSS_TCI_CAMERASPACENORMAL
頂点法線を入力テクスチャ座標として使用する。頂点法線はカメラ空間にトランスフォームされる。
D3DTSS_TCI_CAMERASPACEPOSITION
頂点位置座標を入力テクスチャ座標として使用する。頂点位置座標がカメラ空間にトランスフォームされる。
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
反射ベクトルを入力テクスチャ座標として使用する。反射ベクトルがカメラ空間にトランスフォームされる。反射ベクトルは、入力頂点位置座標と法線ベクトルから計算される。

これらのフラグは互いに排他的であるため、組み合わせて使用することはできない。これらのフラグのいずれかを使用する場合は、テクスチャ ラッピング モードを決定するためにシステムで使用するインデックス値を指定できる。

[C++]

次のコードは、C++ でのこれらのフラグの使用方法を示す。

// この例では、lpd3dDevice 変数は IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。

// このテクスチャ ステージの入力テクスチャ座標として
// 頂点位置座標 (カメラ空間) を使用し、
// D3DRENDERSTATE_WRAP1 レンダリング ステートのラップ モード セットを使用する。
lpd3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX,
D3DTSS_TCI_CAMERASPACEPOSITION | 1 );
[Visual Basic]

次のコードは、Visual Basic でのこれらのフラグの使用方法を示す。

' この例では、d3dDevice 変数は Direct3DDevice7 オブジェクトへの
' 有効な参照である。

' このテクスチャ ステージの入力テクスチャ座標として
' 頂点位置座標 (カメラ空間) を使用し、
' D3DRENDERSTATE_WRAP1 レンダリング ステートのラップ モード セットを使用する。
Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, _
D3DTSS_TCI_CAMERASPACEPOSITION Or 1)

注 : 自動生成されたテクスチャ座標は、テクスチャ座標トランスフォームの入力値として非常に便利であり、またキューブ環境マップの 3 要素ベクトルを計算する必要がないという点でも便利である。

参照

テクスチャ座標トランスフォーム、キューブ環境マップ


ジオメトリ ブレンディングの有効化

[C++]

デフォルトでは、ジオメトリ ブレンディングは無効である。ジオメトリ ブレンディングを有効にするには、IDirect3DDevice7::SetRenderState メソッドを呼び出して D3DRENDERSTATE_VERTEXBLEND レンダリング ステートを D3DVERTEXBLENDFLAGS 列挙型からの値に設定する。次のコードは、2 つのワールド行列間でブレンドするための、レンダリング ステートの設定を示す。

pd3dDevice->SetRenderState( D3DRENDERSTATE_VERTEXBLEND, D3DVBLEND_1WEIGHT );

D3DRENDERSTATE_VERTEXBLEND が D3DVBLEND_DISABLE 以外の値に設定されている場合は、頂点フォーマットに適切な個数のブレンディングの重みが含まれていると見なされる。適切な頂点フォーマットを作成すること、およびそのフォーマットの正しい記述を Direct3D レンダリング メソッドに提供することは開発者の責任である。詳細については、「ブレンディング用の頂点の定義」を参照すること。

ジオメトリ ブレンディングが有効になっている場合、DrawPrimitive レンダリング メソッドでレンダリングされるすべてのオブジェクトに対してジオメトリ ブレンディングが実行される。

[Visual Basic]

デフォルトでは、ジオメトリ ブレンディングは無効である。ジオメトリ ブレンディングを有効にするには、Direct3DDevice7.SetRenderState メソッドを呼び出して D3DRENDERSTATE_VERTEXBLEND レンダリング ステートを CONST_D3DVERTEXBLENDFLAGS 列挙からの値に設定する。次のコードは、2 つのワールド行列間でブレンドするための、レンダリング ステートの設定を示す。

Call d3dDevice.SetRenderState(D3DRENDERSTATE_VERTEXBLEND, D3DVBLEND_1WEIGHT)

D3DRENDERSTATE_VERTEXBLEND が D3DVBLEND_DISABLE 以外の値に設定されている場合は、頂点フォーマットに適切な個数のブレンディングの重みが含まれていると見なされる。適切な頂点フォーマットを作成すること、およびそのフォーマットの正しい記述を Direct3D レンダリング メソッドに提供することは開発者の責任である。詳細については、「ブレンディング用の頂点の定義」を参照すること。

ジオメトリ ブレンディングが有効になっている場合、DrawPrimitive レンダリング メソッドでレンダリングされるすべてのオブジェクトに対してジオメトリ ブレンディングが実行される。


マテリアル プロパティの取得

[C++]

デバイスに対して IDirect3DDevice7::GetMaterial メソッドを呼び出して、レンダリング デバイスで現在使用しているマテリアル プロパティを取得する。IDirect3DMaterial7::SetMaterial メソッドの場合とは異なり、GetMaterial では準備は必要ない。GetMaterial メソッドには、D3DMATERIAL7 構造体のアドレスを指定する。このメソッドは、終了前にこの構造体に現在のマテリアル プロパティの情報を書き込む。

// この例では、lpd3dDev 変数は IDerect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
HRESULT hr;
D3DMATERIAL7 mat;

hr = lpd3dDev->GetMaterial(&mat);
if(FAILED(hr))
    {
// エラー処理コード
    }
[Visual Basic]

デバイスに対して Direct3DDevice7.GetMaterial メソッドを呼び出して、レンダリング デバイスで現在使用しているマテリアル プロパティを取得する。Direct3DDevice7.SetMaterial メソッドの場合とは異なり、GetMaterial では準備は必要ない。GetMaterial メソッドには、D3DMATERIAL7 型の変数を指定する。このメソッドは、終了前にこの変数に現在のマテリアル プロパティの情報を書き込む。

' この例では、d3dDev 変数に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納されているとする。
On Local Error Resume Next
Dim mat As D3DMATERIAL7

Call d3dDev.GetMaterial(mat)
If Err.Number <> DD_OK Then
' エラー処理コード
End If


DrawPrimitive メソッド

[C++]

Direct3D には、1 回の呼び出しでプリミティブおよびインデックス付きプリミティブをレンダリングできるいくつかのメソッドがある。IDirect3DDevice7 インターフェイスにあるすべてのレンダリング メソッドは、アプリケーションで使用する頂点の種類を記述する柔軟な頂点フォーマット フラグの組み合わせを受け取る。このフラグは、システムが適用するジオメトリ パイプラインの部分も決定する (これは IDirect3DDevice2 のメソッドとは異なり、この場合のメソッドは、D3DPRIMITIVETYPE 列挙のメンバによって識別する具体的な頂点フォーマットのみ受け取る)。これらの詳細については、「頂点フォーマット」を参照すること。

DrawPrimitive ファミリのレンダリング メソッドには、以下のようにグループ分けできるレンダリング メソッドがある。

基本的なレンダリング
IDirect3DDevice7::DrawPrimitive および IDirect3DDevice7::DrawIndexedPrimitive
頂点バッファ レンダリング
IDirect3DDevice7::DrawPrimitiveVB および IDirect3DDevice7::DrawIndexedPrimitiveVB
ストライド頂点
IDirect3DDevice7::DrawPrimitiveStrided および IDirect3DDevice7::DrawIndexedPrimitiveStrided.頂点バッファは、ストライド頂点のレンダリングに使用できるが、頂点の処理には IDirect3DVertexBuffer7::ProcessVerticesStrided メソッドを使用する必要がある。

プリミティブをレンダリングするとき、対応するメソッドは、レンダリングするプリミティブの種類 (三角形ストリップ、三角形リストなど)、頂点フォーマット、レンダリング方法を定義するフラグ、および頂点に関する情報を示すパラメータを受け取る。これらのフラグとエフェクトについては、レンダリング メソッドの説明に記述されている。

メソッドに指定する頂点の数は、レンダリングするプリミティブの種類によって異なるため注意すること。たとえば、線リストをレンダリングする場合、1 本のラインを定義する少なくとも 2 つの頂点が必要で、頂点の総数は偶数でなければならない。三角形リストの場合も同様、少なくとも 3 つの頂点が必要で、頂点の総数は 3 の倍数でなければならない。その他の種類のプリミティブの頂点数については、「プリミティブの種類」および「D3DPRIMITIVETYPE」を参照すること。

頂点バッファ、およびレンダリングに頂点バッファを使用するメソッドにより、パフォーマンスと使いやすさが向上し、独自のデータ構造による頂点のレンダリングが改善される。詳細については、「頂点バッファ」を参照すること。

[Visual Basic]

Direct3D には、Visual Basic アプリケーションで 1 回の呼び出しでプリミティブをレンダリングできるいくつかのメソッドがある。Direct3DDevice7 クラスにあるすべてのレンダリング メソッドは、アプリケーションで使用する頂点の種類を記述する柔軟な頂点フォーマット フラグの組み合わせを受け取る。このフラグはシステムが適用するジオメトリ パイプラインの部分も決定する。これらの詳細については、「頂点フォーマット」を参照すること。

DrawPrimitive ファミリのレンダリング メソッドには、以下のようにグループ分けできるレンダリング メソッドがある。

基本的なレンダリング
Direct3DDevice7.DrawPrimitive および Direct3DDevice7.DrawIndexedPrimitive
頂点バッファ レンダリング
Direct3DDevice7.DrawPrimitiveVB および Direct3DDevice7.DrawIndexedPrimitiveVB

プリミティブをレンダリングするとき、対応するメソッドは、レンダリングするプリミティブの種類 (三角形ストリップ、三角形リストなど)、頂点フォーマット、レンダリング方法を定義するフラグ、および頂点に関する情報を示すパラメータを受け取る。これらのフラグとエフェクトについては、レンダリング メソッドの説明に記述されている。

メソッドに指定する頂点の数は、レンダリングするプリミティブの種類によって異なるため注意すること。たとえば、線リストをレンダリングする場合、1 本のラインを定義する少なくとも 2 つの頂点が必要で、頂点の総数は偶数でなければならない。三角形リストの場合も同様、少なくとも 3 つの頂点が必要で、頂点の総数は 3 の倍数でなければならない。その他の種類のプリミティブの頂点数については、「プリミティブの種類」および「CONST_D3DPRIMITIVETYPE」を参照すること。

頂点バッファ、およびレンダリングに頂点バッファを使用するメソッドにより、パフォーマンスと使いやすさが向上し、独自のデータ構造による頂点のレンダリングが改善される。詳細については、「頂点バッファ」を参照すること。

注 : DirectX for Visual Basic では、ストライド頂点のレンダリングはサポートしていない。


テクスチャ アドレッシングにおけるデバイス制限

[C++]

システムでは、一般に 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲外のテクスチャ座標を許可しているが、その範囲からの逸脱がどこまで許容されるかは、ハードウェア制限によって異なることが多い。デバイス機能を取得するとき、レンダリング デバイスは D3DDEVICEDESC7 構造体の dwMaxTextureRepeat メンバでこの制限を知らせる。このメンバの値は、デバイスで許容されるテクスチャ座標の全範囲を示す。たとえば、この値が 128 の場合、テクスチャ座標は -128.0 ～ +128.0 の範囲内で入力しなければならない。この範囲外のテクスチャ座標を渡すことは無効である。テクスチャ座標の自動生成およびテクスチャ座標トランスフォームによって生成されるテクスチャ座標に対しても、同じ制限が適用される。

dwMaxTextureRepeat の解釈は、また、D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 能力ビットによって影響される。このビットを設定した場合、D3DDEVICEDESC7 の dwMaxTextureRepeat メンバは記述どおりに使用される。しかし、D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE を設定していない場合、テクスチャ反復制限はテクスチャ座標が指すテクスチャのサイズに依存する。この場合、dwMaxTextureRepeat は、カレント テクスチャのサイズ (詳細の最大レベル) によって調整して、有効なテクスチャ範囲を計算しなければならない。たとえば、テクスチャのサイズが 32、dwMaxTextureRepeat 値が 512 の場合、実際に有効なテクスチャ座標の範囲は、512/32 = 16 である。したがって、このデバイスのテクスチャ座標は、-16.0 ～ +16.0 の範囲内になければならない。

[Visual Basic]

システムでは、一般に 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲外のテクスチャ座標を許可しているが、その範囲からの逸脱がどこまで許容されるかは、ハードウェア制限によって異なることが多い。デバイス機能を取得するとき、レンダリング デバイスは D3DDEVICEDESC7 型の lMaxTextureRepeat メンバでこの制限を知らせる。このメンバの値は、デバイスで許容されるテクスチャ座標の全範囲を示す。たとえば、この値が 128 の場合、テクスチャ座標は -128.0 ～ +128.0 の範囲内で入力しなければならない。この範囲外のテクスチャ座標を渡すことは無効である。テクスチャ座標の自動生成およびテクスチャ座標トランスフォームによって生成されるテクスチャ座標に対しても、同じ制限が適用される。

lMaxTextureRepeat の解釈は、また、D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 能力ビットによって影響される。このビットを設定した場合、D3DDEVICEDESC7 のメンバ lMaxTextureRepeat は記述どおりに使用される。しかし、D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE を設定していない場合、テクスチャ反復制限はテクスチャ座標が指すテクスチャのサイズに依存する。この場合、lMaxTextureRepeat は、カレント テクスチャのサイズ (詳細の最大レベル) によって調整して、有効なテクスチャ範囲を計算しなければならない。たとえば、テクスチャのサイズが 32、lMaxTextureRepeat 値が 512 の場合、実際に有効なテクスチャ座標の範囲は、512/32 = 16 である。したがって、このデバイスのテクスチャ座標は、-16.0 ～ +16.0 の範囲内になければならない。


三角形リスト

Platform SDK: DirectX

三角形リスト

三角形リストとは、個々の三角形のリストである。三角形は互いに隣接していても離れていてもよい。三角形リストには、少なくとも 3 つの頂点が必要である。頂点の総数は 3 の倍数でなければならない。

分離したパーツから構成されるオブジェクトを作成するときは、三角形リストを使用する。たとえば、3D ゲームで電磁力界壁を作成するには、単独の小さな三角形を多数集めたリストを指定する。次に、この三角形リストにマテリアルやテクスチャを適用して光を発しているように見せる。壁の三角形それぞれが輝いて見えるようになる。プレーヤーが電磁力界とはこう見えるだろうと期待するとおりに、壁の背後のシーンが三角形の間の隙間を通して部分的に見えるようになる。

また、三角形リストは、グーロー シェーディングで陰影を付けた、鋭いエッジを持つプリミティブを作成するときに便利である。「面法線ベクトルと頂点法線ベクトル」を参照すること。

[C++]

C++ では、次のコードで示すように、頂点の配列に値を設定して三角形リストを作成する。

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0),D3DVECTOR(0,0,-1),0,0);

IDirect3DDevice7::DrawPrimitive メソッドを使用して三角形リストをレンダリングする。次のコードは、IDirect3DDevice7::DrawPrimitive を使用して、上の例の三角形リストを描画する方法を示す。IDirect3DDevice7::DrawPrimitive の呼び出しは、IDirect3DDevice7::BeginScene と IDirect3DDevice7::EndScene の間で行う必要がある。

HRESULT hResult;
// このコードでは、lpDirect3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_TRIANGLELIST,
                                      D3DFVF_VERTEX,
                                      lpVerts,
                                      TOTAL_VERTS,
                                      D3DDP_WAIT);
[Visual Basic]

Visual Basic では、次のコードで示すように、頂点の配列に値を設定して三角形リストを作成する。

' このコードでは、dx は DirectX7 オブジェクトへの
' 有効な参照であるとする。
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

Direct3DDevice7.DrawPrimitive メソッドを使用して三角形リストをレンダリングする。次の例は、Direct3DDevice7.DrawPrimitive を使用して、上の例の三角形リストを描画する方法を示す。Direct3DDevice7.DrawPrimitive の呼び出しは、Direct3DDevice7.BeginScene と Direct3DDevice7.EndScene の間で行う必要がある。

' このコードでは、d3ddev は Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
Call d3ddev.DrawPrimitive(D3DPT_TRIANGLELIST, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
                          D3DDP_WAIT)

If Err.Number <> DD_OK Then
' エラー処理コード
End If

次の図は、結果として描画される三角形リストを示す。


アルファテスティング ステート

[C++]

C++ アプリケーションでは、アルファ テスティングを使用して、いつピクセルをレンダリング ターゲット サーフェスに書き込むかを制御する。D3DRENDERSTATE_ALPHATESTENABLE 列挙値を使用することにより、アプリケーションでは、アルファ テスト関数に基づいて各ピクセルをテストできるように現在の Direct3D デバイスを設定する。テストが成功すると、ピクセルがサーフェスに書き込まれる。テストが失敗すると、ピクセルは無視される。アルファ テスト関数は、D3DRENDERSTATE_ALPHAFUNC 列挙値で選択する。D3DRENDERSTATE_ALPHAREF レンダリング ステートを使用することにより、アプリケーションでは、比較するすべてのピクセルに参照アルファ値を設定する。

アルファ テスティングは、通常、透明に近いオブジェクトをラスタ化する際のパフォーマンスを改善するために使用する。ラスタ化する色データが指定のピクセル (D3DPCMPCAPS_GREATEREQUAL) よりも不透明の場合、ピクセルが書き込まれる。そうでない場合は、ラスタライザはピクセルを無視し、2 色のブレンドに必要な処理を省略する。次のコードは、指定の比較関数がサポートされているかどうかを調べ、サポートされている場合は、レンダリングのパフォーマンス改善に必要な比較関数のパラメータを設定する。

// この例では、pd3dDeviceDesc は、
// 前の IDirect3DDevice7::GetCaps の呼び出しによって格納された
// D3DDEVICEDESC7 構造体であるとする。
if (pd3dDeviceDesc.dpcTriCaps.dwAlphaCmpCaps & D3DPCMPCAPS_GREATEREQUAL)
{
    dev->SetRenderState( D3DRENDERSTATE_ALPHAREF, (DWORD)0x00000001);
    dev->SetRenderState( D3DRENDERSTATE_ALPHATESTENABLE, TRUE );
    dev->SetRenderState( D3DRENDERSTATE_ALPHAFUNC, D3DCMP_GREATEREQUAL );
}

// 比較関数がサポートされていない場合にもレンダリングを実行する。
// ただし、パフォーマンスは改善されない。

すべてのハードウェアがアルファ テスティング機能をサポートしているわけではない。デバイス機能を調べるには、IDirect3DDevice7::GetCaps メソッドを呼び出す。デバイス機能を取得した後、使用する比較関数の D3DPRIMCAPS 構造体 (関連付けられた D3DDEVICEDESC7 構造体に格納されている) の dwAlphaCmpCaps メンバを調べる。dwAlphaCmpCaps メンバが D3DPCMPCAPS_ALWAYS のみ、または D3DPCMPCAPS_NEVER のみ含んでいる場合、ドライバはアルファ テストをまったくサポートしていない。

[Visual Basic]

Visual Basic で記述されたアプリケーションでは、アルファ テスティングを使用して、いつピクセルをレンダリング ターゲット サーフェスに書き込むかを制御する。D3DRENDERSTATE_ALPHATESTENABLE 列挙値を使用することにより、アプリケーションでは、アルファ テスト関数に基づいて各ピクセルをテストできるように現在の Direct3D デバイスを設定する。テストが成功すると、ピクセルがサーフェスに書き込まれる。テストが失敗すると、ピクセルは無視される。アルファ テスト関数は、D3DRENDERSTATE_ALPHAFUNC 列挙値で選択する。D3DRENDERSTATE_ALPHAREF レンダリング ステートを使用することにより、アプリケーションでは、比較するすべてのピクセルに参照アルファ値を設定する。

アルファ テスティングは、通常、透明に近いオブジェクトをラスタ化する際のパフォーマンスを改善するために使用する。ラスタ化する色データが指定のピクセル (D3DPCMPCAPS_GREATEREQUAL) よりも不透明に近い場合、ピクセルが書き込まれる。そうでない場合は、ラスタライザはピクセルを無視し、2 色のブレンドに必要な処理を省略する。次のコードは、指定の比較関数がサポートされているかどうかを調べ、サポートされている場合は、レンダリングのパフォーマンス改善に必要な比較関数のパラメータを設定する。

' この例では、d3dDeviceDesc は、
' Direct3DDevice7::GetCaps の呼び出しによって格納された
' D3DDEVICEDESC7 型であるとする。
If (d3dDeviceDesc.dpcTriCaps.lAlphaCmpCaps And D3DPCMPCAPS_GREATEREQUAL) Then
        Call dev.SetRenderState(D3DRENDERSTATE_ALPHAREF, &H1)
        Call dev.SetRenderState(D3DRENDERSTATE_ALPHATESTENABLE, True)
        Call dev.SetRenderState(D3DRENDERSTATE_ALPHAFUNC, D3DCMP_GREATEREQUAL)
End If

' 比較関数がサポートされていない場合にもレンダリングを実行する。
' ただし、パフォーマンスは改善されない。

すべてのハードウェアがアルファ テスティング機能をサポートしているわけではない。デバイス機能を調べるには、Direct3DDevice7.GetCaps メソッドを呼び出す。デバイスの機能を検索した後、使用する比較関数の D3DPRIMCAPS 型 (関連付けられた D3DDEVICEDESC7 型に格納されている) の lAlphaCmpCaps メンバを調べる。lAlphaCmpCaps メンバが D3DPCMPCAPS_ALWAYS のみ、または D3DPCMPCAPS_NEVER のみ含んでいる場合、ドライバはアルファ テストをまったくサポートしていない。


テクスチャ アドレッシング ステート

[Visual Basic]

注 : ここでは、C または C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、Direct3DDevice7.SetTextureStageState メソッドを使用してテクスチャ アドレッシング ステートを設定する必要がある。

[C++]

D3DRENDERSTATE_TEXTUREADDRESS、D3DRENDERSTATE_TEXTUREADDRESSU、および D3DRENDERSTATE_TEXTUREADDRESSV レンダリング ステートは、現在は使用されていない。これらは、D3DTSS_ADDRESS、D3DTSS_ADDRESSU、および D3DTSS_ADDRESSV テクスチャ ステージ ステートに置き換えられている。

注 : IDirect3DDevice7 インターフェイスでは、従来の D3DRENDERSTATE_TEXTUREADDRESS、D3DRENDERSTATE_TEXTUREADDRESSU、および D3DRENDERSTATE_TEXTUREADDRESSV レンダリング ステートは認識されない。これらのレンダリング ステートを使用すると失敗する。


三角形ファン

Platform SDK: DirectX

三角形ファン

三角形ファンとは、次の図に示すように、すべての三角形が 1 つの頂点を共有するという点を除いては、三角形ストリップに類似したものである。

システムでは、頂点 v2、v3、v1 を使用して最初の三角形を、v3、v4、v1 を使用して 2 番目の三角形を、v4、v5、v1 を使用して 3 番目の三角形を、という手順で描画していく (フラット シェーディングが有効な場合、三角形は最初の頂点の色でシェーディングされる)。

[C++]

C++ アプリケーションでは、次のコードで示すように、頂点の配列に値を設定して三角形ファンを作成する。

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(0,0,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(-5,-5,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(-3,7,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(0,10,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(3,7,0),D3DVECTOR(0,0,-1),0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(5,5,0),D3DVECTOR(0,0,-1),0,0);

この後、IDirect3DDevice7::DrawPrimitive メソッドを使用して三角形ファンをレンダリングできる。次のコードは、IDirect3DDevice7::DrawPrimitive を使用して、上の例の三角形ファンを描画する方法を示す。IDirect3DDevice7::DrawPrimitive の呼び出しは、IDirect3DDevice7::BeginScene と IDirect3DDevice7::EndScene の間で行う必要がある。

HRESULT hResult;
// このコードでは、lpDirect3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_TRIANGLEFAN,
                                     D3DFVF_VERTEX,
                                     lpVerts,
                                     TOTAL_VERTS,
                                     D3DDP_WAIT);
[Visual Basic]

Visual Basic アプリケーションでは、次のコードで示すように、頂点の配列に値を設定して三角形ファンを作成する。

' このコードでは、dx は DirectX7 オブジェクトへの
' 有効な参照であるとする。
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(0, 0, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(-3, 7, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(0, 10, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(3, 7, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(5, 5, 0, 0, 0, -1, 0, 0)

この後、Direct3DDevice7.DrawPrimitive メソッドを使用して三角形ファンをレンダリングできる。次のコードは、Direct3DDevice7.DrawPrimitive を使用して、上の例の三角形ファンを描画する方法を示す。Direct3DDevice7.DrawPrimitive の呼び出しは、Direct3DDevice7.BeginScene と Direct3DDevice7.EndScene の間で行う必要がある。

' このコードでは、d3ddev が Direct3DDevice7 オブジェクトへの
' 有効な参照であるとする。
Call d3ddev.DrawPrimitive(D3DPT_TRIANGLEFAN, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
D3DDP_WAIT);

If Err.Number <> DD_OK Then
' エラー処理コード
End If

次の図は、結果として描画される三角形ファンを示す。


ミラー テクスチャ アドレッシング モードについて

[C++]

D3DTEXTUREADDRESS 列挙型の D3DTADDRESS_MIRROR メンバで指定する "ミラー" テクスチャ アドレッシング モードでは、Direct3D はすべての整数境界でテクスチャをミラーリングする。たとえば、プログラムで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) を指定する場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_MIRROR に設定すると、u および v の両方向でテクスチャが 3 回適用される。テクスチャが適用されるその他のすべての行と列は、直前の行または列の鏡像になる。

[Visual Basic]

CONST_D3DTEXTUREADDRESS 列挙の D3DTADDRESS_MIRROR メンバで指定する "ミラー" テクスチャ アドレッシング モードでは、Direct3D はすべての整数境界でテクスチャをミラーリングする。たとえば、プログラムで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) を指定する場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_MIRROR に設定すると、u および v の両方向でテクスチャが 3 回適用される。テクスチャが適用されるその他のすべての行と列は、直前の行または列の鏡像になる。

次の図にこれを示す。

このテクスチャ アドレッシング モードのエフェクトは、"ラップ" モードのエフェクトに類似する部分がある。詳細については、「ラップ テクスチャ アドレッシング モードについて」を参照すること。


デバイス列挙の開始

[C++]

C++ アプリケーションでは、IDirect3D7::EnumDevices メソッドを呼び出してデバイスの列挙を開始する。このメソッドは、ハードウェアでサポートされている Direct3D デバイスをすべて列挙する。Direct3D は、D3DEnumDevicesCallback7 関数を呼び出して、使用するデバイスを選択する。D3DEnumDevicesCallback7 関数をアプリケーションに用意しておく。このコールバック関数はアプリケーションから提供されるため、独自の名前を付けることができる。

次のコードは、Direct3D デバイスの列挙する処理を示す。この例では、デバイス列挙コールバック関数の名前を EnumDeviceCallback とする。次のコードでは、EnumDeviceCallback へのポインタを IDirect3D7::EnumDevices メソッドに渡す。その後、このメソッドは列挙する各デバイスに対して EnumDeviceCallback を呼び出し、デバイスを返す。このコールバックは、D3DENUMRET_CANCEL を返すことで、すべてのデバイスが列挙される前に列挙処理を停止できる。

// このコードでは、コードを実行する前にアプリケーションが取得した IDirect3D7 インターフェイスへの
//
// 有効なポインタが変数 lpd3d に格納されている。

BOOL fDeviceFound = FALSE;
hRes = lpd3d->EnumDevices(EnumDeviceCallback, &fDeviceFound);
if (FAILED(hRes))
{
// エラー処理コード
}

if (!fDeviceFound)
{
// エラー処理コード
}
[Visual Basic]

Visual Basic アプリケーションでは、Direct3D7.GetDevicesEnum メソッドを呼び出して Direct3DEnumDevices クラスへの参照を取得することにより、デバイスの列挙を開始する。Direct3DEnumDevices クラスは、列挙するデバイスの数、および各デバイスの情報を取得するメソッドを定義する。

次のコードは、Direct3DEnumDevices クラスを取得する処理を示す。

' この例では、d3d 変数は Direct3D7 クラスへの
' 有効な参照である。
Dim d3dEnum As Direct3DEnumDevices

' 列挙クラスを取得する。
Set d3dEnum = d3d.GetDevicesEnum


クランプ テクスチャ アドレッシング モードについて

[C++]

D3DTEXTUREADDRESS 列挙型の D3DTADDRESS_CLAMP メンバで指定する "クランプ" テクスチャ アドレッシング モードでは、Direct3D はテクスチャ座標を [0.0, 1.0] の範囲に制限する。つまり、テクスチャを 1 回適用し、次に、エッジのピクセルの色を "塗り付けていく"。たとえば、プログラムで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) をそのプリミティブの頂点に割り当てる場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_CLAMP に設定すると、テクスチャが 1 回適用される。最初の列と最後の行のピクセル カラーが、プリミティブの上と右にそれぞれ広がっていく。

[Visual Basic]

CONST_D3DTEXTUREADDRESS 列挙の D3DTADDRESS_CLAMP メンバで指定する "クランプ" テクスチャ アドレッシング モードでは、Direct3D はテクスチャ座標を [0.0, 1.0] の範囲に制限する。つまり、テクスチャを 1 回適用し、次に、エッジのピクセルの色を "塗り付けていく"。たとえば、プログラムで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) をそのプリミティブの頂点に割り当てる場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_CLAMP に設定すると、テクスチャが 1 回適用される。最初の列と最後の行のピクセル カラーが、プリミティブの上と右にそれぞれ広がっていく。

次の図にこれを示す。


ディレクショナル ライト

ディレクショナル ライトは、色と方向を持ち、位置座標は持たない。このライティングは平行な光を放つ。つまり、この光はすべてシーン内で同じ方向に進む。ディレクショナル ライトは、太陽のような遠く離れた光源に例えることができる。ディレクショナル ライトは減衰と範囲の影響を受けないので、Direct3D では指定された色と方向のみ考慮して、頂点の色を計算する。ライティング係数の個数が少ないため、ディレクショナル ライトはコンピュータへの負荷が最も軽いライトである。


アンチエイリアシング ステート

アンチエイリアスとは、線とエッジをスクリーン上でより滑らかに表示する方法である。Direct3D では、エッジ アンチエイリアシングおよびフルシーン アンチエイリアシングの 2 種類のアンチエイリアシングがサポートされている。これらのテクニックの詳細については、「共通のテクノロジと特殊効果」セクションの「アンチエイリアシング」を参照すること。

[C++]

デフォルトでは、Direct3D はアンチエイリアシングを実行しない。D3DRENDERSTATE_ANTIALIAS レンダリング ステートを D3DANTIALIASMODE のメンバに設定して、フルシーン アンチエイリアシングを有効にできる (デフォルト値の D3DANTIALIAS_NONE は、フルシーン アンチエイリアシングを無効にする)。

エッジ アンチエイリアシング (第 2 レンダリング パスが必要) を有効にするには、D3DRENDERSTATE_EDGEANTIALIAS レンダリング ステートを TRUE に設定する。エッジ アンチエイリアシングを無効にするには、D3DRENDERSTATE_EDGEANTIALIAS を FALSE に設定する。

[Visual Basic]

デフォルトでは、Direct3D はアンチエイリアシングを実行しない。D3DRENDERSTATE_ANTIALIAS レンダリング ステートを CONST_D3DANTIALIASMODE 列挙のメンバに設定して、フルシーン アンチエイリアシングを有効にできる (デフォルト値の D3DANTIALIAS_NONE は、フルシーン アンチエイリアシングを無効にする)。

エッジ アンチエイリアシング (第 2 レンダリング パスが必要) を有効にするには、D3DRENDERSTATE_EDGEANTIALIAS レンダリング ステートをゼロ以外の値に設定する。エッジ アンチエイリアシングを無効にするには、D3DRENDERSTATE_EDGEANTIALIAS をゼロに設定する。


ミップマップ セットの作成

[C++]

ミップマップ チェーンを作成するには、IDirectDraw7::CreateSurface メソッドに渡す DDSURFACEDESC2 構造体の DDSCAPS_MIPMAP および DDSCAPS_COMPLEX フラグを指定する。ミップマップはすべてテクスチャでもあるため、DDSCAPS_TEXTURE フラグを指定する必要もある。

次の例は、IDirectDraw7::CreateSurface メソッドを使用して、サイズ 256x256、128x128、64x64、32x32、および 16x16 の 5 つのミップマップ レベルを作成する方法を示す。

// このコードでは、変数 lpDD は DirectDraw インターフェイスへの
// 有効なポインタであるとする。

DDSURFACEDESC2       ddsd;
LPDIRECTDRAWSURFACE7 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))
.
.
.

ミップマップ レベルの数は省略できる。この場合、IDirectDraw7::CreateSurface はサーフェスのチェーンを作成する。各サーフェスは、直前のサーフェスよりも 2 の累乗ずつ小さくなり、最終的に最小サイズになる。幅と高さも省略できる。この場合、IDirectDraw7::CreateSurface は指定されたレベル数を作成する。このときの最小レベル サイズは 1x1 である。

注 : ミップマップ チェーンの各サーフェスの大きさは、直前のサーフェスの半分になる。最上位ミップマップの大きさが 256ｴ128 の場合、次のレベルのミップマップの大きさは 128ｴ64 になり、その次のレベルは 64ｴ32 という順にミップマップの大きさは小さくなり、最終的には 2×1 になる。dwWidth および dwHeight メンバに明示的に大きさを指定した場合は、いくつかの制約がある。つまり、dwMipMapCount でミップマップ レベルの数を指定することはできない。dwMipMapCount では、チェーンのミップマップの幅または高さのいずれかを 1 より小さくなることがある。例として、4×2 の最上位ミップマップ サーフェスの場合を考える。この場合、dwMipMapCount に指定可能な最大値は 2 である。最上位の大きさは 4ｴ2 で、次のレベルの大きさは 2ｴ1 である。dwMipMapCount の値が 2 より大きいと、第 2 レベルのミップマップの高さは分数になる。したがって、これは許可されない。

[Visual Basic]

ミップマップ チェーンを作成するには、DirectDraw7.CreateSurface メソッドに渡す DDSURFACEDESC2 型の DDSCAPS_MIPMAP および DDSCAPS_COMPLEX フラグを指定する。ミップマップはすべてテクスチャでもあるため、DDSCAPS_TEXTURE フラグを指定する必要もある。

次の例は、DirectDraw7.CreateSurface メソッドを使用して、サイズ 256x256、128x128、64x64、32x32、および 16x16 の 5 つのミップマップ レベルを作成する方法を示す。

' このコードでは、変数 DD に DirectDraw7 オブジェクトへの
' 有効な参照が格納されているとする。
On Local Error Resume Next
Dim ddsd As DDSURFACEDESC2
Dim DDMipMap As DirectDrawSurface7

ddsd.lFlags = DDSD_CAPS Or DDSD_MIPMAPCOUNT
ddsd.lMipMapCount = 5
ddsd.ddsCaps.lCaps = DDSCAPS_TEXTURE Or DDSCAPS_MIPMAP Or DDSCAPS_COMPLEX
ddsd.lWidth = 256
ddsd.lHeight = 256

Set DDMipMap = DD.CreateSurface(ddsd)
If Err.Number <> DD_OK Then
' エラー処理コード
End If

ミップマップ レベルの数は省略できる。この場合、DirectDraw7.CreateSurface はサーフェスのチェーンを作成する。各サーフェスは、直前のサーフェスよりも 2 の累乗ずつ小さくなり、最終的に最小サイズになる。幅と高さも省略できる。この場合、DirectDraw7.CreateSurface は指定されたレベル数を作成する。このときの最小レベル サイズは 1x1 である。

注 : ミップマップ チェーンの各サーフェスの大きさは、直前のサーフェスの半分になる。最上位ミップマップの大きさが 256ｴ128 の場合、次のレベルのミップマップの大きさは 128ｴ64 になり、その次のレベルは 64ｴ32 という順にミップマップの大きさは小さくなり、最終的には 2×1 になる。lWidth および lHeight メンバに明示的に大きさを指定した場合は、いくつかの制約がある。つまり、lMipMapCount でミップマップ レベルの数を指定することはできない。lMipMapCount では、チェーンのミップマップの幅または高さのいずれかを 1 より小さくなることがある。例として、4×2 の最上位ミップマップ サーフェスの場合を考える。この場合、lMipMapCount に指定可能な最大値は 2 である。最上位の大きさは 4ｴ2 で、次のレベルの大きさは 2ｴ1 である。lMipMapCount の値が 2 より大きいと、第 2 レベルのミップマップの高さは分数になる。したがって、これは許可されない。


テクスチャ座標トランスフォームについて

Platform SDK: DirectX

テクスチャ座標トランスフォームについて

Direct3D デバイスでは、4×4 行列を適用して、頂点のテクスチャ座標をトランスフォームできる。システムは、テクスチャ座標に対して、ジオメトリの場合と同様にトランスフォームを適用する。適用可能なトランスフォームには、スケーリング、回転、平行移動、射影、せん断、またはこれらの組み合わせなど、4×4 行列で可能なあらゆるトランスフォームがある。

注 : Direct3D では、「トランスフォーム済み ライティング済みの頂点」は修正されない。したがって、「トランスフォーム済み ライティング済みの頂点」を使用するアプリケーションでは、Direct3D によって頂点のテクスチャ座標をトランスフォームすることはできない。

ハードウェア アクセラレーションによるトランスフォーム & ライティング処理をサポートするデバイス (TnLHAL デバイス) では、また、テクスチャ座標トランスフォームは高速処理される。ハードウェア アクセラレーションによるトランスフォームが利用できない場合は、Direct3D ジオメトリ パイプラインのプラットフォーム固有の最適化によってテクスチャ座標トランスフォームが実行される。

テクスチャ座標トランスフォームは、ジオメトリのテクスチャ座標を直接変更しないで特殊効果を出そうとする場合に便利である。単純な平行移動行列や回転行列を使用して、オブジェクト上のテクスチャをリアルに表現したり、Direct3D によって自動生成されるテクスチャ座標をトランスフォームすることで、射影テクスチャや動的ライト マッピングなど高度なエフェクトを単純化し、高速処理することも可能である。また、テクスチャ座標トランスフォームを使用して、テクスチャ座標の単一セットを (複数のテクスチャ ステージでの) さまざまな目的のために "再利用" できる。

詳細については、「テクスチャ座標処理の使用」


アンビエント ライト ステート

アンビエント ライトとは、全方向から照らす環境光である。Direct3D のアンビエント ライトの使用に関する特定の情報については、「ダイレクト ライトとアンビエント ライトの比較」および「Direct3D のライティングにおける数学的計算」を参照すること。

[C++]

C++ アプリケーションでアンビエント ライトの色を設定するには、IDirect3DDevice7::SetRenderState メソッドを呼び出し、第 1 パラメータとして列挙値 D3DRENDERSTATE_AMBIENT を渡す。第 2 パラメータは RGBA フォーマットで表す色である。デフォルトはゼロである。

// このコードでは、lpD3DDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタであるとする。

// アンビエント ライトを設定する。
D3DCOLOR d3dclrAmbientLightColor = D3DRGBA(1.0f,1.0f,1.0f,1.0f);
lpD3DDevice->SetRenderState(D3DRENDERSTATE_AMBIENT,
                            d3dclrAmbientLightColor);
[Visual Basic]

Visual Basic アプリケーションでアンビエント ライトの色を設定するには、Direct3DDevice7.SetRenderState メソッドを呼び出し、列挙値 D3DRENDERSTATE_AMBIENT を第 1 パラメータとして渡す。第 2 パラメータは RGBA フォーマットで表す色である。デフォルトはゼロである。

' このコードでは、D3DDevice に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納され、および dx に DirectX7 オブジェクトへの
' 有効な参照が格納されているとする。
Dim AmbientLightColor As Long

' アンビエント ライトを設定する。
AmbientLightColor = dx.CreateColorRGBA(1#, 1#, 1#, 1#)
Call D3DDevice.SetRenderState(D3DRENDERSTATE_AMBIENT, _
                              AmbientLightColor)


テクスチャ座標処理の使用

[C++]

以下に示すのは、テクスチャ座標処理によって特殊なテクスチャ エフェクトを出す方法およびそのコード例である。

モデル上でテクスチャをアニメーションする (平行移動または回転を利用)

  • 2D テクスチャ座標を頂点フォーマットに定義する。
    // 2D テクスチャ座標を持つ単一のテクスチャを使用する。このビット パターンは、
// 必要に応じて、位置座標、法線、および色情報を追加できるように
// 拡張する必要がある。
DWORD dwFVFTex = D3FVF_TEX1 | D3DFVF_TEXCOORDSIZE2(0);
  • 2D テクスチャ座標を使用するようにラスタライザを設定する。
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2)
  • 適切なテクスチャ座標トランスフォーム行列を定義して設定する。
    // M は、U および V 方向のテクスチャ座標を平行移動するための
// D3DMATRIX である。
//      1   0  0  0
//      0   1  0  0
//      du dv  1  0 (du および dv は各フレームを変更する)
//      0   0  0  1

D3DMATRIX M = D3DUtil_SetIdentityMatrix(); // d3dutil.h に宣言される。
M._31 = du;
M._32 = dv;

モデルのカメラ空間位置座標の線形関数としてテクスチャ座標を作成する

  • D3DTSS_TCI_CAMERASPACEPOSITION フラグを使用して、カメラ空間の頂点位置座標を入力としてテクスチャ トランスフォームに渡す。
    // 入力頂点にはテクスチャ座標がない (これは帯域幅を節約する)。
// 3 つのテクスチャ座標は、カメラ空間 (x, y, z) の頂点位置座標を使用して
// 生成される。
SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION)
  • ラスタライザで 2D テクスチャ座標を評価する。
    // 2 つの出力座標を使用する。
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2)
  • 線形関数を適用する行列を定義して設定する。
    // 次に示すように、
// テクスチャ座標を線形関数として生成する。
//      u = Ux*x + Uy*x + Uz*x + Uw
//      v = Vx*x + Vy*x + Vz*x + Vw
// この場合、行列 M は次のようになる。
//      Ux  Vx  0  0
//      Uy  Vy  0  0
//      Uz  Vz  0  0
//      Uw  Vw  0  0

SetTransform(D3DTRANSFORMSTATE_TEXTURE0, &M)

キューブ環境マップによる環境マッピングを実行する

  • D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグを使用して、キューブ マップ用のテクスチャ座標 (反射ベクトルとして) を自動的に生成する。
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR)
  • ラスタライザで 3 つの要素を持つテクスチャ座標を評価する。
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT3)

射影テクスチャ処理を実行する

  • D3DTSS_TCI_CAMERASPACEPOSITION フラグを使用して、テクスチャ トランスフォームに頂点位置座標を入力として渡す。
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION)
  • テクスチャ射影行列を作成して適用する (これはドキュメントの対象外であり、その他の市販製品で扱う内容である)。
  • ラスタライザで 3 つの要素を持つ射影テクスチャ座標を評価する。
    // 2 つの出力座標を使用する。
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTF_PROJECTED | D3DTTFF_COUNT3)
[Visual Basic]

以下に示すのは、テクスチャ座標処理によって特殊なテクスチャ エフェクトを出す方法およびそのコード例である。

モデル上でテクスチャをアニメーションする (平行移動または回転を利用)

  • 2D テクスチャ座標を頂点フォーマットに定義する。
    ' 2D テクスチャ座標を持つ単一のテクスチャを使用する。このビット パターンは、
' 必要に応じて、位置座標、法線、および色情報を追加できるように
' 拡張する必要がある。
lFVFTex = (D3FVF_TEX1 Or D3DFVF_TEXCOORDSIZE2(0))
  • 2D テクスチャ座標を使用するようにラスタライザを設定する。
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2)
  • 適切なテクスチャ座標トランスフォーム行列を定義して設定する。
    ' M は、U および V 方向のテクスチャ座標を平行移動するための
' D3DMATRIX である。
'      1   0  0  0
'      0   1  0  0
'      du dv  0  0 (du および dv は各フレームを変更する)
'      0   0  0  0
dx.IdentityMatrix(M)
M.rc31 = du
M.ec32 = dv

モデルのカメラ空間位置座標の線形関数としてテクスチャ座標を作成する

  • D3DTSS_TCI_CAMERASPACEPOSITION フラグを使用して、カメラ空間の頂点位置座標を入力としてテクスチャ トランスフォームに渡す。
    ' 入力頂点にはテクスチャ座標がない (これは帯域幅を節約する)。
' 3 つのテクスチャ座標は、カメラ空間 (x, y, z) の頂点位置座標を使用して
' 生成される。
SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION)
  • ラスタライザで 2D テクスチャ座標を評価する。
    ' 2 つの出力座標を使用する。
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2)
  • 線形関数を適用する行列を定義して設定する。
    ' 次に示すように、
' テクスチャ座標を線形関数として生成する。
'      u = Ux*x + Uy*x + Uz*x + Uw
'      v = Vx*x + Vy*x + Vz*x + Vw
' この場合、行列 M は次のようになる。
'      Ux  Vx  0  0
'      Uy  Vy  0  0
'      Uz  Vz  0  0
'      Uw  Vw  0  0

SetTransform(D3DTRANSFORMSTATE_TEXTURE0, M)

キューブ環境マップによる環境マッピングを実行する

  • D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグを使用して、キューブ マップ用のテクスチャ座標 (反射ベクトルとして) を自動的に生成する。
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR)
  • ラスタライザで 3 つの要素を持つテクスチャ座標を評価する。
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT3)

射影テクスチャを実行する

  • D3DTSS_TCI_CAMERASPACEPOSITION フラグを使用して、テクスチャ トランスフォームに頂点位置座標を入力として渡す。
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION)
  • テクスチャ射影行列を作成して適用する (これはドキュメントの対象外であり、その他の市販製品で扱う内容である)。
  • ラスタライザで 3 つの要素を持つ射影テクスチャ座標を評価する。
    ' 2 つの出力座標を使用する。
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTF_PROJECTED | D3DTTFF_COUNT3)


テクスチャ座標のトランスフォームと取得 [C++]

Platform SDK: DirectX
テクスチャ座標のトランスフォームと取得 [C++]

アプリケーションでジオメトリに使用する行列と同様、IDirect3DDevice7::SetTransform および IDirect3DDevice7::GetTransform メソッドを呼び出してテクスチャ座標トランスフォームを設定および取得できる。これらのメソッドは、テクスチャ ステージの 0 ～ 7 のトランスフォーム行列をそれぞれ識別する、D3DTRANSFORMSTATETYPE 列挙型の D3DTRANSFORMSTATE_TEXTURE0 ～ D3DTRANSFORMSTATE_TEXTURE7 メンバを受け取る。

次のコードは、テクスチャ ステージ 0 のテクスチャ座標に適用される行列を設定する。

// この例では、lpd3dDevice 変数に IDirect3DDevice7 インターフェイスへの
// 有効なポインタが格納されている。

D3DMATRIX matTrans  = D3DUtil_SetIdentityMatrix(); // d3dutil.h に宣言される。

// 希望のトランスフォーム用の行列を設定する。
lpd3dDevice->SetTransform(D3DTRANSFORMSTATE_TEXTURE0, &matTrans);
[Visual Basic]

アプリケーションでジオメトリに使用する行列と同様、Direct3DDevice7.SetTransform および Direct3DDevice7.GetTransform メソッドを呼び出してテクスチャ座標トランスフォームを設定および取得できる。これらのメソッドは、テクスチャ ステージの 0 ～ 7 のトランスフォーム行列をそれぞれ識別する、CONST_D3DTRANSFORMSTATETYPE 列挙の D3DTRANSFORMSTATE_TEXTURE0 ～ D3DTRANSFORMSTATE_TEXTURE7 メンバを受け取る。

次のコードは、テクスチャ ステージ 0 のテクスチャ座標に適用される行列を設定する。

' この例では、d3dDevice 変数に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納されており、
' dx には DirectX7 オブジェクトへの有効な参照が格納されている。
Dim matTrans As D3DMATRIX
Call dx.IdentityMatrix(matTrans)

' 希望のトランスフォーム用の行列を設定する。
Call d3dDevice.SetTransform(D3DTRANSFORMSTATE_TEXTURE0, matTrans)


ビューポートのクリア

ビューポートをクリアすると、レンダリング ターゲット サーフェス上のビューポート矩形の内容と、深度バッファ サーフェスおよびステンシル バッファ サーフェス (指定されている場合) の矩形の内容がリセットされる。通常は、新しいフレームをレンダリングする前にビューポートをクリアして、ゴミを表示せずに、グラフィックスなどのデータが新しいレンダリング オブジェクトを受け入れる準備を整える。

[C++]

C++ では、ビューポートをクリアする、IDirect3DDevice7 インターフェイスの IDirect3DDevice7::Clear メソッドを使用できる。このメソッドは、クリアするサーフェス上の領域を定義する 1 つまたは複数の矩形を受け取る。レンダリングするシーンにビューポート矩形全体の移動が含まれている場合 (たとえば、プレーヤーの視点から見た遠近法を使用するゲーム)、各フレームのビューポート全体をクリアすることができる。この場合、dwCount パラメータを 1 に設定し、lpRects パラメータをビューポート領域全体に及ぶ単一の矩形のアドレスに設定する。より便利な方法として、lpRects パラメータを NULL に設定し、dwCount パラメータを 0 に設定して、ビューポート矩形全体のクリアを示すことができる。

Clear メソッドはさまざまな使用方法があり、深度バッファ内のステンシル ビットをクリアすることもできる。dwFlags パラメータは、レンダリング ターゲットおよび関係する深度バッファまたはステンシル バッファのクリア方法を指定する 3 つのフラグを受け取る。このパラメータに D3DCLEAR_TARGET フラグを指定すると、このメソッドは dwColor パラメータで指定した任意の RGBA 色 (マテリアル カラーではない) を使用してビューポートをクリアする。D3DCLEAR_ZBUFFER フラグを指定すると、このメソッドは dwZ パラメータで指定した任意の深度に従って深度バッファをクリアする。0.0 は最も近い距離を表し、1.0 は最も遠い距離を表す。D3DCLEAR_STENCIL フラグを指定すると、このメソッドはステンシル ビットを dwStencil パラメータで指定した値にリセットする。指定できる値は 0 ～ 2n-1 までの整数である。ここで、n はステンシル バッファのビット深度を示す。

注 : DirectX 5.0 では、背景マテリアルは関連付けられたテクスチャを持つことができたので、ビューポートをクリアした後、単純な色ではなくテクスチャを表示できた。この機能はほとんど使用されることがなく、特に効果的でもなかった。DirectX 6.0 以降のインターフェイスは、テクスチャ ハンドルを受け取らなくなり、ビューポートをクリアした後にテクスチャを表示することはできない。したがって、アプリケーションでは手動で背景を描画しなければならない。その結果、レンダリング ターゲット サーフェスのビューポートをクリアする必要はほとんどなくなった。アプリケーションで深度バッファをクリアするだけで、レンダリング ターゲット サーフェス上のすべてのピクセルが上書きされる。

場合によっては、レンダリング ターゲット サーフェスと深度バッファ サーフェスの一部にのみレンダリングすることがある。クリアメソッドは、1 回の呼び出しでサーフェスの複数の領域をクリアすることもできる。これを行うには、dwCount パラメータにクリアする矩形の数を指定し、lpRects パラメータに矩形の配列内の最初の要素のアドレスを指定する。

[Visual Basic]

Visual Basic の Direct3DDevice7 クラスには、ビューポートをクリアする Direct3DDevice7.Clear メソッドがある。このメソッドは、クリアするサーフェス上の領域を定義する 1 つまたは複数の矩形を受け取る。レンダリングするシーンにビューポート矩形全体のモーションが含まれる場合 (たとえば、プレーヤーの視点から見た遠近法を使用するゲーム)、各フレームのビューポート全体をクリアすることができる。この場合、count パラメータを 1 に設定し、recs() パラメータを D3DRECT 変数の単一要素配列に設定する (ここでは、レンダリング ターゲット サーフェスの領域全体に及ぶ矩形を最初の要素でのみ記述する)。

Clear メソッドはさまざまな使用方法があり、深度バッファ内のステンシル ビットをクリアすることもできる。flags パラメータは、レンダリング ターゲットおよび関係する深度バッファまたはステンシル バッファのクリア方法を指定する 3 つのフラグを受け取る。このパラメータに D3DCLEAR_TARGET フラグを指定すると、このメソッドは color パラメータで指定した任意の RGBA 色 (マテリアル カラーではない) を使用してビューポートをクリアする。D3DCLEAR_ZBUFFER フラグを指定すると、このメソッドは z パラメータで指定した任意の深度に従って深度バッファをクリアする。0.0 は最も近い距離を表し、1.0 は最も遠い距離を表す。D3DCLEAR_STENCIL フラグを指定すると、このメソッドはステンシル ビットを stencil パラメータで指定した値にリセットする。指定できる値は 0 ～ 2n-1 までの整数である。ここで、n はステンシル バッファのビット深度を示す。

場合によっては、レンダリング ターゲット サーフェスと深度バッファ サーフェスの一部にのみレンダリングすることがある。クリアメソッドは、1 回の呼び出しでサーフェスの複数の領域をクリアすることもできる。これを行うには、count パラメータにクリアする矩形の数を指定し、recs() パラメータに矩形の配列を指定する。


視点からの相対深度 対 Z ベースの深度

[C++]

深度バッファ内での z 値の不均等なばらつきによって生じる、フォグの不自然なグラフィックス効果を抑えるために、ほとんどのハードウェア デバイスでは、ピクセル フォグに z ベース深度値ではなく視点からの相対深度を使用する。視点からの相対深度とは、本質的には同次座標セットからの w 要素である (Direct3D は、デバイス空間座標から RHW 要素の逆数を取得して真の w を再生成する)。デバイスが視点からの相対フォグをサポートしている場合、IDirect3DDevice7::GetCaps メソッドを呼び出すと、そのデバイスは D3DPRIMCAPS の dwRasterCaps メンバに D3DPRASTERCAPS_WFOG フラグを設定する (GetCaps に渡す D3DDEVICEDESC7 構造体には、各種プリミティブの能力を記述する複数の D3DPRIMCAPS 構造体が含まれている)。

注 : リファレンス ラスタライザを除き、ソフトウェア デバイスは常に z を使用してピクセル フォグ エフェクトを計算する。

視点からの相対フォグがサポートされている場合、設定された射影行列でデバイス空間の w 値に対応する、ワールド空間の z 値を生成するとき、システムは z ベース深度よりも視点からの相対深度を優先して自動的に使用する (射影行列を設定するには、IDirect3DDevice7::SetTransform メソッドを呼び出し、D3DTRANSFORMSTATE_PROJECTION 値を使用し、希望の行列を表す D3DMATRIX 構造体を渡す)。射影行列がこの要件に対応していない場合は、フォグ エフェクトが正しく適用されない。適切な行列の生成の詳細については、「W バッファに有効な射影行列」を参照すること (「射影トランスフォームとは」で説明するパースペクティブ射影行列は、適切な射影行列を生成する)。

使用上の注意 : Direct3D では、現在設定されている射影行列を使用して w ベース深度の計算を実行する。したがって、アプリケーションで Direct3D トランスフォーム パイプラインを使用しない場合であっても、希望の w ベース機能を取得するために適切な射影行列を設定しておく必要がある。

Direct3D は射影行列の第 4 列を調べ、要素が [0,0,0,1] (アフィン射影) の場合には、システムは z ベースの深度値をフォグに使用する。この場合、デバイス空間の線形フォグ エフェクトの開始距離および終了距離を指定する必要もある。この範囲は、ユーザーに最も近い点を 0.0 とし、最も遠い点を 1.0 とした範囲である。

[Visual Basic]

深度バッファ内での z 値の不均等なばらつきによって生じる、フォグの不自然なグラフィックス効果を抑えるために、ほとんどのハードウェア デバイスでは、ピクセル フォグに z ベース深度値ではなく視点からの相対深度を使用する。視点からの相対深度とは、本質的には同次座標セットからの w 要素である (Direct3D は、デバイス空間座標から RHW 要素の逆数を取得して真の w を再生成する)。デバイスが視点からの相対フォグをサポートしている場合、Direct3DDevice7.GetCaps メソッドを呼び出すと、そのデバイスは D3DPRIMCAPS 型の lRasterCaps メンバに D3DPRASTERCAPS_WFOG フラグを設定する (GetCaps に渡す D3DDEVICEDESC7 型には、各種プリミティブの能力を記述する複数の D3DPRIMCAPS 型が含まれている)。

注 : リファレンス ラスタライザを除き、ソフトウェア デバイスは常に z を使用してピクセル フォグ エフェクトを計算する。

視点からの相対フォグがサポートされている場合、設定された射影行列でデバイス空間の w 値に対応する、ワールド空間の z 値を生成するとき、システムは z ベース深度よりも視点からの相対深度を優先して自動的に使用する (射影行列を設定するには、Direct3DDevice7.SetTransform メソッドを呼び出し、CONST_D3DTRANSFORMSTATETYPE からD3DTRANSFORMSTATE_PROJECTION 値を使用し、希望の行列を表す D3DMATRIX 型を渡す)。射影行列がこの要件に対応していない場合は、フォグ エフェクトが正しく適用されない。適切な行列の生成の詳細については、「W バッファに有効な射影行列」を参照すること (「射影トランスフォームとは」で説明するパースペクティブ射影行列は、適切な射影行列を生成する)。

使用上の注意 : Direct3D では、現在設定されている射影行列を使用して w ベース深度の計算を実行する。したがって、アプリケーションで Direct3D トランスフォーム パイプラインを使用しない場合であっても、希望の w ベース機能を取得するために適切な射影行列を設定しておく必要がある。

Direct3D は射影行列の第 4 列を調べ、要素が [0,0,0,1] (アフィン射影) の場合には、システムは z ベースの深度値をフォグに使用する。この場合、デバイス空間の線形フォグ エフェクトの開始距離および終了距離を指定する必要もある。この範囲は、ユーザーに最も近い点を 0.0 とし、最も遠い点を 1.0 とした範囲である。


列挙されたデバイスの選択

[C++]

C++ の場合、Direct3D は、アプリケーションに用意されている D3DEnumDevicesCallback7 関数を、システムにインストールされている各 Direct3D デバイスに対して呼び出す。この関数の呼び出しでは、第 1 パラメータはデバイスを説明する文字列で、第 2 パラメータは分かりやすいデバイス名を示す文字列である。

第 3 パラメータは、デバイスのハードウェア機能についての情報を格納する D3DDEVICEDESC7 構造体へのポインタである。列挙されるデバイスが HAL デバイスであっても、Direct3D で使用可能な機能を特定のハードウェアがすべてサポートするとは限らない。最後のパラメータは、プログラマが定義する値である。アプリケーションでは、この値を IDirect3D7::EnumDevices メソッドに渡す。次に、この値を D3DEnumDevicesCallback7 関数に渡す。

次のコードは、D3DEnumDevicesCallback7 関数の作成方法を示す。この例では、アプリケーションに用意されているコールバック関数の名前を EnumDeviceCallback とする。EnumDeviceCallback 関数では、以下のアルゴリズムを使用して、適切な Direct3D デバイスを選択する。

  1. 現在のディスプレイ深度に一致しないデバイスをすべて廃棄する。
  2. 三角形をグーロー シェーディング処理できないデバイスをすべて廃棄する。
  3. 上の 1 と 2 に当てはまらないハードウェア デバイスがあれば、それを使用する。ただし、アプリケーションをデバッグ モードで実行している場合は、ハードウェア デバイスは使用しない。

EnumDeviceCallback 関数のコード例を以下に示す。

// この関数では、次のグローバル変数が
// プログラムで宣言されているとする。
// DWORD                   g_dwDeviceBitDepth          = 0;
// GUID                    g_guidDevice;
// char                    g_szDeviceName[MAX_PATH];
// char                    g_szDeviceDesc[MAX_PATH];
// D3DDEVICEDESC7          g_d3dDeviceDesc;

static HRESULT WINAPI
EnumDeviceCallback(LPSTR            lpszDeviceDesc,
                   LPSTR            lpszDeviceName,
                   LPD3DDEVICEDESC7 lpd3dEnumDeviceDesc,
                   LPVOID           lpUserArg)
{
    BOOL fIsHardware = FALSE;

    fIsHardware = (lpd3dEnumDeviceDesc->dwDevCaps & D3DDEVCAPS_HWRASTERIZATION);

// デバイスのレンダリングが希望の深度で行われるかどうか。
    if ((lpd3dEnumDeviceDesc->dwDeviceRenderBitDepth & g_dwDeviceBitDepth) == 0)
    {
// そうでなければ、このデバイスはスキップする。

        return D3DENUMRET_OK;
    }

// デバイスは、グーロー シェーディング処理した三角形をサポートする必要がある。
    if (!(lpd3dEnumDeviceDesc->dpcTriCaps.dwShadeCaps &
          D3DPSHADECAPS_COLORGOURAUDRGB))
    {
// グーロー シェーディングをサポートしていない。このデバイスはスキップする。

        return D3DENUMRET_OK;
    }

    //
// このデバイスは必要な機能を備えている。詳細を保存する。
    //
    *(BOOL*)lpUserArg = TRUE;
    CopyMemory(&g_guidDevice, &lpd3dEnumDeviceDesc->deviceGUID, sizeof(GUID));
    strcpy(g_szDeviceDesc, lpszDeviceDesc);
    strcpy(g_szDeviceName, lpszDeviceName);
    CopyMemory(&g_d3dDeviceDesc, lpd3dEnumDeviceDesc,
               sizeof(D3DDEVICEDESC7));

// これがハードウェア デバイスの場合、
// 必要な機能を備えている。
    if (fIsHardware)
        return D3DENUMRET_CANCEL;

// そうでなければ、検索を続ける。

    return D3DENUMRET_OK;
}
[Visual Basic]

Visual Basic では、Direct3DEnumDevices クラスによって、システムにインストールされている Direct3D デバイスを列挙する。このクラスに問い合わせを行い、クラス内の列挙されるデバイスをそのインデックスで識別することで、各デバイスの情報を取得する。デバイスのインデックスは、最初のデバイスには 1、2 つ目のデバイスには 2、という順序で付く。Direct3DEnumDevices.GetCount メソッドは、列挙されるデバイスの数、つまり最大許容インデックス値を返す。

列挙されるデバイスの GUID をテキスト文字列として取得するには、Direct3DEnumDevices.GetGuid メソッドを呼び出す。文字列はデバイスごとに異なる。

デバイスの名前と分かりやすい説明を含むテキスト文字列を取得するには、Direct3DEnumDevices.GetName および Direct3DEnumDevices.GetDescription メソッドを呼び出す。

D3DDEVICEDESC7 型の形式でデバイスの機能についての説明を取得するには、Direct3DEnumDevices.GetDesc メソッドを呼び出す。列挙されるデバイスがハードウェア デバイスであっても、Direct3D API で使用可能な機能を特定のハードウェアがすべてサポートするとは限らない。

次のコードは、デバイス機能を決定するために Direct3DEnumDevices クラスのメソッドを呼び出す関数の作成方法を示す。この例のアプリケーション定義関数では、以下のアルゴリズムを使用して、適切な Direct3D デバイスを選択する。

  1. 現在のディスプレイ深度に一致しないデバイスをすべて廃棄する。
  2. 三角形をグーロー シェーディング処理できないデバイスをすべて廃棄する。
  3. 上の 1 と 2 に当てはまらないハードウェア デバイスがあれば、それを使用する。
Private Sub EnumerateDevices(d3denum As Direct3DEnumDevices)
' この例では、以下のグローバル変数が宣言されているとする。
'   g_lDeviceBitDepth は希望のビット深度を表す (CONST_DDBITDEPTHFLAGS の定数の組み合わせ)。
'   g_DeviceDesc にはデバイス機能を表す D3DDEVICEDESC7 が格納される。
'   g_strDeviceGUID にはデバイスの GUID 文字列が格納される。
'   g_strDeviceDescription にはデバイスを説明するテキスト文字列が格納される。
'   g_strDeviceName にはデバイス名を表す文字列が格納される。

' デバイスの列挙に使用するローカル変数。
Dim iDevice As Integer
Dim DevDesc As D3DDEVICEDESC7
Dim bIsHardware As Boolean

' デバイスの列挙を開始する。
For iDevice = 1 To d3denum.GetCount
Dim checkDesc As D3DDEVICEDESC7
Call d3denum.GetDesc(iDevice, DevDesc)

' このデバイスで使用する機能がハードウェアでサポートされていない場合
bIsHardware = (DevDesc.lDevCaps Or D3DDEVCAPS_HWRASTERIZATION)

' デバイスのレンダリングが希望の深度で行われるかどうか。行われない場合は中止する。
' チェックを行い、次のデバイスを取得する。
If checkDesc.lDeviceRenderBitDepth And Not g_lDeviceBitDepth Then
GoTo NEXT_DEVICE
End If

' デバイスは、グーロー シェーディング処理した三角形をサポートする必要がある。
If (Not checkDesc.dpcTriCaps.lShadeCaps And D3DPSHADECAPS_COLORGOURAUDRGB) Then
' RGB モードのグーロー シェーディングをサポートしていない。このデバイスはスキップする。
GoTo NEXT_DEVICE
End If

        '
' ここに処理が達するまでに適切なデバイスが検出される。
' その結果をグローバル変数に格納する。
        '
g_strDeviceGUID = d3denum.GetGuid(iDevice)
g_strDeviceDescription = d3denum.GetDescription(iDevice)
g_strDeviceName = d3denum.GetName(iDevice)
g_DeviceDesc = DevDesc

' この現在のデバイスがハードウェア アクセラレーションを備えている場合、
' これは適切なデバイスである。
If bIsHardware = True Then Exit For

' ハードウェア アクセラレーションを備えていない場合は処理を次に移す。
NEXT_DEVICE:
Next iDevice
End Sub ' EnumerateDevices


バンプ マップ テクスチャの作成

ほかのテクスチャの場合と同様に、バンプ マップ テクスチャを作成する。アプリケーションでバンプ マッピングのサポートを確認し、有効なピクセル フォーマットを取得したら (「バンプ マッピングのサポートの検出」で説明するように)、バンプ マップ テクスチャ サーフェスを作成できる。サーフェスの作成については、「テクスチャ サーフェス オブジェクトの取得」および「サーフェスの作成」を参照すること。

サーフェスの作成後は、適切なデルタ値を持つ各ピクセルと、輝度 (サーフェス フォーマットに輝度が含まれる場合) をロードできる。各ピクセル コンポーネントの値については、「バンプ マップ ピクセル フォーマット」で説明する。


ライトの有効/無効

[C++]

シーン内の光源のライト プロパティ セットをいったん割り当てると、デバイスに対して IDirect3DDevice7::LightEnable メソッドを呼び出すことで、その光源をアクティブにすることができる。新しく割り当てた光源は、デフォルトでは無効になっている。LightEnable メソッドは、2 つのパラメータを受け取る。第 1 パラメータには、メソッドで処理する光源のインデックス (0 から始まる) を設定する。第 2 パラメータには、ライトを有効にする場合は TRUE を、無効にする場合は FALSE を設定する。

次のコードは、LightEnable メソッドを使用して、デバイスの光源プロパティのリスト内の最初の光源を有効にする方法を示す。

/*
* この例では、g_lpd3dDev は IDirevt3DDevice7 インターフェイスへの
* 有効なポインタである。
 */
HRESULT hr;

hr = g_lpd3dDev->LightEnable(0, TRUE);
if (FAILED(hr))
{
// エラー処理コード
}
[Visual Basic]

シーン内の光源のライト プロパティ セットをいったん割り当てると、デバイスに対して Direct3DDevice7.LightEnable メソッドを呼び出すことで、その光源をアクティブにすることができる。新しく割り当てた光源は、デフォルトでは無効になっている。LightEnable メソッドは、2 つのパラメータを受け取る。第 1 パラメータには、メソッドで処理する光源のインデックス (0 から始まる) を設定する。第 2 パラメータには、ライトを有効にする場合は TRUE を、無効にする場合は FALSE を設定する。

次のコードは、LightEnable メソッドを使用して、デバイスの光源プロパティのリスト内の最初の光源を有効にする方法を示す。

'
' この例では、d3dDevice 変数に Direct3DDevice7 オブジェクトへの
' 有効な参照が格納される。
'
On Local Error Resume Next

Call d3dDevice.LightEnable(0, True)
If Err.Number <> DD_OK Then
' エラー処理コード
End If

プロパティがないライトを有効にする場合、またはデバイス内で割り当てられているライト プロパティ セットの範囲外のインデックスを指定した場合、LightEnable メソッドは以下のプロパティを持つ光源を作成し、その光源を有効または無効にする。

メンバ | デフォルト
dltType | D3DLIGHT_DIRECTIONAL
dcvDiffuse | (R:1, G:1, B:1, A:0)
dcvSpecular | (R:0, G:0, B:0, A:0)
dcvAmbient | (R:0, G:0, B:0, A:0)
dvPosition | (0, 0, 0)
dvDirection | (0, 0, 1)
dvRange | 0
dvFalloff | 0
dvAttenuation0 | 0
dvAttenuation1 | 0
dvAttenuation2 | 0
dvTheta | 0
dvPhi | 0


テクスチャ アドレッシング モードとは

Direct3D アプリケーションでは、どのプリミティブのどの頂点にもテクスチャ座標を割り当てることができる。詳細については、「テクスチャ座標」を参照すること。通常、頂点に割り当てるテクスチャ座標 u および v の範囲は、0.0 と 1.0 を含む 0.0 ～ 1.0 である。しかし、この範囲外のテクスチャ座標を割り当てて、特殊なテクスチャ エフェクトを作成することもできる。

テクスチャ アドレッシング モードを設定することで、[0.0, 1.0] の範囲外のテクスチャ座標で Direct3D が行う処理を制御できる。たとえば、アプリケーションでテクスチャ アドレッシング モードを設定して、プリミティブ全体にテクスチャをタイルのように張ることができる。次のトピックでさらに詳しく説明する。

  • ラップ テクスチャ アドレッシング モードについて
  • ミラー テクスチャ アドレッシング モードについて
  • クランプ テクスチャ アドレッシング モードについて
  • 境界色テクスチャ アドレッシング モードについて


ステート ブロックの取得

[C++]

IDirect3DDevice7::CaptureStateBlock メソッドは、既存のステート ブロック内の値を更新してデバイスの現在のステートに反映する。このメソッドは、パラメータ dwBlockHandle を 1 つだけ受け取る。このパラメータは、呼び出しが成功した場合にデバイスの現在のステートの取り込み先となるステート ブロックを識別する。

アプリケーションで記録済みのステート ブロックを更新して若干異なるステート設定を含める場合には、IDirect3DDevice7::CaptureStateBlock メソッドが特に便利である。これを行うには、既存のステート ブロックを適用し、必要な設定変更を行い、システムのステートをステート ブロックに取り込む。これについて、次のコード例で示す。

// dwMyBlock 変数には、以前に記録されたデバイス ステート セットへの
// ハンドルが格納されている。

// 現在のステート ブロックを設定する。
d3dDevice->ApplyStateBlock(dwMyBlock);

// 必要に応じてステート ブロックを変更する。
.
.
.

// 修正したデバイス ステート データを既存のブロックに取り込む。
d3dDevice->CaptureStateBlock(dwMyBlock);

CaptureStateBlock メソッドは、デバイスのステート全体を取り込むのではなく、ステート ブロック内の既存のステート値を更新するのみである。たとえば、次のコード例で表す 2 つの処理が記録されたステート ブロックがあるとする。

SetRenderState(D3DRENDERSTATE_SHADEMODE, D3DSHADE_GOURAUD);
SetTexture(0, lpd3dAnyTexture);

ステート ブロックが初めに記録されて以降、2 つの設定のいずれかを変更した場合、IDirect3DDevice7::CaptureStateBlock メソッドは、ブロック内で変更されたステートのみ新しい値に更新する。

[Visual Basic]

Direct3DDevice7.CaptureStateBlock メソッドは、既存のステート ブロック内の値を更新してデバイスの現在のステートに反映する。このメソッドは、パラメータ blockHandle を 1 つだけ受け取る。このパラメータは、呼び出しが成功した場合にデバイスの現在のステートの取り込み先となるステート ブロックを識別する。

アプリケーションで記録済みのステート ブロックを更新して若干異なるステート設定を含める場合には、Direct3DDevice7.CaptureStateBlock メソッドが特に便利である。これを行うには、既存のステート ブロックを適用し、必要な設定変更を行い、システムのステートをステート ブロックに取り込む。これについて、次のコード例で示す。

' MyBlock 変数には、以前に記録されたデバイス ステート セットへの
' ハンドルが格納されている。

' 現在のステート ブロックを設定する。
Call d3dDevice.ApplyStateBlock(MyBlock)

' 必要に応じてデバイス ステートを変更する。
.
.
.

' 修正したデバイス ステート データを既存のブロックに取り込む。
Call d3dDevice.CaptureStateBlock(MyBlock)

CaptureStateBlock メソッドは、デバイスのステート全体を取り込むのではなく、ステート ブロック内の既存のステート値を更新するのみである。たとえば、次のコード例で表す 2 つの処理が記録されたステート ブロックがあるとする。

Call SetRenderState(D3DRENDERSTATE_SHADEMODE, D3DSHADE_GOURAUD)
Call SetTexture(0, d3dAnyTexture)

ステート ブロックが初めに記録されて以降、2 つの設定のいずれかを変更した場合、Direct3DDevice7.CaptureStateBlock メソッドは、ブロック内で変更されたステートのみ新しい値に更新する。


ランプ ステート

D3DRENDERSTATE_MONOENABLE レンダリング ステートは、現在は使用されていない。アプリケーションでランプ デバイスを使用すると、ランプ ライティングが自動的に有効になる。詳細については、「従来のデバイスの種類」を参照すること。


頂点のグループ化

プリミティブの頂点は、基本的には以下の 2 つの方法でグループ化できる。

  • プリミティブのすべての頂点を順に配列に格納する。
  • 頂点を任意の順序で配列に格納する。この配列に格納される頂点のインデックス値を順に格納した配列を伴う。このようなプリミティブは、インデックス付きプリミティブと呼ばれる。

DrawPrimitive アーキテクチャを使用すると、プリミティブを定義する頂点のグループを 1 回のメソッド呼び出しでレンダリングしたり、プリミティブを形成する頂点を個別にレンダリングすることができる。詳細については、「プリミティブのレンダリング」を参照すること。


テクスチャ ブレンディング ステート

[Visual Basic]

注 : ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic の場合、アプリケーションでは、Direct3DDevice7.SetTextureStageState メソッドを D3DTSS_COLOROP および D3DTSS_ALPHAOP テクスチャ ステージ ステートで使用して、テクスチャ ブレンディングを制御する必要がある。

[C++]

D3DRENDERSTATE_TEXTUREMAPBLEND レンダリング ステートは、D3DTSS_COLOROP および D3DTSS_ALPHAOP テクスチャ ステージ ステートを介して使用できるテクスチャ ブレンディング ステートに置き換えられている。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

注 : D3DRENDERSTATE_TEXTUREMAPBLEND レンダリング ステートは、現在は使用されていないため、IDirect3DDevice7 インターフェイスでは認識されない。このレンダリング ステートを IDirect3DDevice7 インターフェイスで使用すると失敗する。


ライトの方向

ライトの方向プロパティは、オブジェクトの放射する光がワールド空間内を進む方向を決める。方向は、ディレクショナル ライトとスポット ライトでのみ使用し、ベクトルで定義する。

[C++]

C++ アプリケーションでは、D3DLIGHT7 構造体の dvDirection メンバ (D3DVECTOR 構造体) を使用する。方向ベクトルは、シーン内のライトの位置座標とは無関係に、論理原点からの距離として記述する。したがって、シーンにまっすぐに入射する (z 軸の正方向に沿って) スポット ライトの方向ベクトルは、その位置座標がどこに定義されていても <0,0,1> である。同様に、シーンを真上から照らす太陽光をシミュレートするには、方向が <0,-1,0> のディレクショナル ライトを使用すればよい。必ずしも座標軸に沿って照らすライトを作成する必要がないことは明らかである。値を組み合わせたり、揃えたりして、面白い角度からライトを照らすことができる。

[Visual Basic]

Visual Basic アプリケーションでは、ライトの D3DLIGHT7 型の direction メンバにライトの方向を設定する。direction メンバは、D3DVECTOR 型に属する。方向ベクトルは、シーン内のライトの位置座標とは無関係に、論理原点からの距離として記述する。したがって、シーンにまっすぐに入射する (z 軸の正方向に沿って) スポット ライトの方向ベクトルは、その位置座標がどこに定義されていても <0,0,1> である。同様に、シーンを真上から照らす太陽光をシミュレートするには、方向が <0,-1,0> のディレクショナル ライトを使用すればよい。必ずしも座標軸に沿って照らすライトを作成する必要がないことは明らかである。値を組み合わせたり、揃えたりして、面白い角度からライトを照らすことができる。

注 : ライトの方向ベクトルを正規化する必要はないが、必ずベクトルの大きさを指定すること。つまり、<0,0,0> の方向ベクトルは使用しない。


ブレンディング用の頂点の定義

[C++]

次のユーザー定義構造体は、2 つの行列間でブレンドする頂点に使用できる。

//
// この頂点の柔軟な頂点フォーマット記述子は次のとおりである。
//
//     dwFVF = D3DFVF_XYZB1 | D3DFVF_NORMAL | D3DFVF_TEX1;
//
struct D3DBLENDVERTEX {
D3DVECTOR v;
FLOAT     blend;
D3DVECTOR n;
FLOAT     tu, tv;
};

「ブレンディングの重み」で説明するように、ブレンドの重みは柔軟な頂点フォーマット内の位置座標および RHW データの後ろで、かつ頂点法線の前になければならない。

前の頂点フォーマットには、ブレンディングの重みが 1 つしかないことに注意する。これは、D3DTRANSFORMSTATE_WORLD および D3DTRANSFORMSTATE_WORLD1 トランスフォーム ステートで定義される 2 つのワールド行列があるためである。これら 2 つの行列間でそれぞれの頂点が、1 つの重みを使用してブレンドされる。行列が 3 つある場合、重みは 2 つ必要である。

[Visual Basic]

次のユーザー定義型は、2 つの行列間でブレンドする頂点に使用できる。

'
' この頂点の柔軟な頂点フォーマット記述子は次のとおりである。
'
'     lFVF = (D3DFVF_XYZB1 Or D3DFVF_NORMAL Or D3DFVF_TEX1)
'
Type D3DBLENDVERTEX
v As D3DVECTOR
blend As Single
n As D3DVECTOR
tu As Single
tv As Single
End Type

「ブレンディングの重み」で説明するように、ブレンドの重みは柔軟な頂点フォーマット内の位置座標および RHW データの後ろで、かつ頂点法線の前になければならない。

前の頂点フォーマットには、ブレンディングの重みが 1 つしかないことに注意する。これは、D3DTRANSFORMSTATE_WORLD および D3DTRANSFORMSTATE_WORLD1 トランスフォーム ステートで定義される 2 つのワールド行列があるためである。これら 2 つの行列間でそれぞれの頂点が、1 つの重みを使用してブレンドされる。行列が 3 つある場合、重みは 2 つ必要である。

注 : スキンの重みは簡単に定義できる。ジョイントするオブジェクト間の距離の線形関数を使用するとよいが、より滑らかな S 字関数を使用するとさらによい。スキンの重み分布関数を選択すると、必要に応じてジョイント部に鮮明なしわを付けることができる (短い距離間でスキンの重みの変化を大きくする)。

参照

頂点フォーマットについて、柔軟な頂点フォーマット フラグ


テクスチャ アドレッシング モードの設定と取得

[C++]

IDirect3DDevice7::SetTextureStageState メソッドを呼び出すことで、個々のテクスチャ ステージにテクスチャ アドレッシング モードを設定できる。第 1 パラメータには、希望のテクスチャ ステージ識別子を指定する。第 2 パラメータには、u および v の両方のテクスチャ アドレッシング モードを同時に変更する D3DTSS_ADDRESS を設定するか、u または v のアドレッシング モードを個別に更新する D3DTSS_ADDRESSU または D3DTSS_ADDRESSV を設定する。SetTextureStageState に渡す第 3 パラメータには、設定するモードの種類を指定する。このパラメータには、D3DTEXTUREADDRESS 列挙型のメンバのいずれかを設定できる。指定したテクスチャ ステージの現在のテクスチャ アドレッシング モードを取得するには、IDirect3DDevice7::GetTextureStageState を呼び出して、D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_ADDRESS、D3DTSS_ADDRESSU、または D3DTSS_ADDRESSV メンバを使用して情報を取得するアドレッシング モードを指定する。

従来の IDirect3DDevice2 インターフェイスを使用する場合、テクスチャ アドレッシング モードを設定するには、IDirect3DDevice2::SetRenderState メソッドを呼び出して、u および v のテクスチャ アドレッシング モードを同時に設定する D3DRENDERSTATE_TEXTUREADDRESS レンダリング ステートを使用する。D3DRENDERSTATE_TEXTUREADDRESSU または D3DRENDERSTATE_TEXTUREADDRESSV レンダリング ステートを使用して、u および v のアドレッシング モードを個別に設定できる。SetTextureStageState に対応する、新しいレンダリング ステートと同様、これらのレンダリング ステートも D3DTEXTUREADDRESS 列挙型の値を使用する。

注 : IDirect3DDevice7::SetRenderState メソッドは、IDirect3DDevice2 バージョンとは対照的に、D3DRENDERSTATE_TEXTUREADDRESS、D3DRENDERSTATE_TEXTUREADDRESSU、D3DRENDERSTATE_TEXTUREADDRESSV レンダリング ステートがほかのレンダリング ステートに置き換えられていても、これらのステートを認識する。IDirect3DDevice7 は従来のレンダリング ステートを認識し、そのエフェクトを最初のテクスチャ ステージ (ステージ 0) にマッピングする。従来のレンダリング ステートとそれに対応するテクスチャ ステージ ステートを併用しないこと。予期せぬ結果が生じることがある。

[Visual Basic]

Visual Basic では、Direct3DDevice7.SetTextureStageState メソッドを呼び出すことで、個々のテクスチャ ステージに対してテクスチャ アドレッシング モードを設定する。第 1 パラメータには、希望のテクスチャ ステージ識別子を指定する。第 2 パラメータには、u および v の両方のテクスチャ アドレッシング モードを同時に変更する D3DTSS_ADDRESS を設定するか、u または v のアドレッシング モードを個別に更新する D3DTSS_ADDRESSU または D3DTSS_ADDRESSV を設定する。SetTextureStageState に渡す第 3 パラメータには、設定するモードの種類を指定する。このパラメータには、CONST_D3DTEXTUREADDRESS 列挙のメンバのいずれかを設定できる。

指定したテクスチャ ステージの現在のテクスチャ アドレッシング モードを取得するには、Direct3DDevice7::GetTextureStageState を呼び出して、情報を取得するアドレッシング モードへの CONST_D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_ADDRESS、D3DTSS_ADDRESSU、または D3DTSS_ADDRESSV メンバを使用する。


球体環境マップとは

球体環境マップ、または "球体マップ" は、オブジェクトの周りのシーンの画像またはオブジェクトの周りのライティング エフェクトを含む特殊なテクスチャである。キューブ環境マップとは異なり、球体マップはオブジェクトの周囲の様子を直接表現するわけではない。「環境マッピングとは」のトピックのティーポットの画像は、球体マッピングで実現できる反射エフェクトを示している。

球体マップは、オブジェクトの周囲の 360°の視界を、魚眼レンズで見たように 2D 表現したものである。次は、Spheremap サンプル (C++) で使用する球体マップである。


キューブ環境マップへのレンダリング

キューブ環境マップを DDSCAPS_3DDEVICE で作成する場合、その他のレンダリング ターゲット サーフェスと同様に、キューブ マップの個々のサーフェスにレンダリングすることができる。このレンダリングを行う前に実行する最も大切なことは、カメラを正しく配置し、そのサーフェスに対して正しい方向を向くようにトランスフォーム行列を設定することである。正しい方向とは、前方 (+z)、後方 (-z)、左 (-x)、右 (+x)、上方 (+y)、または下方 (-y) である。

[C++]

次の C++ コードは、レンダリングするサーフェスに応じてビュー行列を用意して設定する。

//
// ppddsFaces 変数は、各サーフェスに対して 1 つある
// IDirectDrawSurface7 インターフェイス ポインタの配列のアドレスである。
//
void RenderFaces(LPDIRECTDRAWSURFACE7* ppddsFaces)
{
// キューブ マップの 6 つのサーフェスに対してループ処理を実行する。
for( DWORD i=0; i<6; i++ )
    {
DDSCAPS2 ddsc;
ZeroMemory( (LPVOID)&ddsc, sizeof(DDSCAPS2) );

// サーフェス能力を取得する (これにより、どのサーフェスであるかを把握する)。
ppddsFaces[i]->GetCaps( &ddsc );

// 以下のように、標準ビューを置き換える。
D3DVECTOR vEnvEyePt = D3DVECTOR( 0.0f, 0.0f, 0.0f );
D3DVECTOR vLookatPt, vUpVec;

switch( ddsc.dwCaps2 & DDSCAPS2_CUBEMAP_ALLFACES )
        {
case DDSCAPS2_CUBEMAP_POSITIVEX:
vLookatPt = D3DVECTOR( 1.0f, 0.0f, 0.0f );
vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
break;
case DDSCAPS2_CUBEMAP_NEGATIVEX:
vLookatPt = D3DVECTOR(-1.0f, 0.0f, 0.0f );
vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
break;
case DDSCAPS2_CUBEMAP_POSITIVEY:
vLookatPt = D3DVECTOR( 0.0f, 1.0f, 0.0f );
vUpVec    = D3DVECTOR( 0.0f, 0.0f,-1.0f );
break;
case DDSCAPS2_CUBEMAP_NEGATIVEY:
vLookatPt = D3DVECTOR( 0.0f,-1.0f, 0.0f );
vUpVec    = D3DVECTOR( 0.0f, 0.0f, 1.0f );
break;
case DDSCAPS2_CUBEMAP_POSITIVEZ:
vLookatPt = D3DVECTOR( 0.0f, 0.0f, 1.0f );
vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
break;
case DDSCAPS2_CUBEMAP_NEGATIVEZ:
vLookatPt = D3DVECTOR( 0.0f, 0.0f,-1.0f );
vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
break;
        }

D3DMATRIX matView;
D3DUtil_SetViewMatrix( matView, vEnvEyePt, vLookatPt, vUpVec );
g_pd3dDevice->SetTransform( D3DTRANSFORMSTATE_VIEW, &matView );

キューブ環境マップの各サーフェスには 90°の視界が含まれることを思い出すこと。アプリケーションで特殊効果などのために視界の角度を変更しない限り、この角度に応じて射影行列を設定するよう注意が必要である。

次のコードは、最も一般的に使用する射影行列を作成および設定する。

// 90°の視界を射影に使用する。
D3DMATRIX matProj;
D3DUtil_SetProjectionMatrix( matProj, g_PI/2, 1.0f, 0.5f, 1000.0f );
g_pd3dDevice->SetTransform( D3DTRANSFORMSTATE_PROJECTION, &matProj );

カメラを正しく配置し、射影行列を設定すると、シーンをレンダリングできる。シーンの各オブジェクトは、通常配置するとおりに配置する。次のコードでは、処理を完全に示すために、このタスクについては大まかに示す。

        //
// シーンのレンダリング
        //

// 深度バッファをサーフェスに入れ替え、レンダリング ターゲットして設定する。
// この関数については、後で詳しく説明する。
ChangeRenderTarget( ppddsFaces[i] );

// z バッファをクリアする。
g_pd3dDevice->Clear( 0, NULL, D3DCLEAR_ZBUFFER, 0x000000ff, 1.0f, 0L );

// アンチエイリアシングを有効する。これにより、環境マップの見た目がきれいになる。
g_pd3dDevice->SetRenderState( D3DRENDERSTATE_ANTIALIAS,
D3DANTIALIAS_TRANSLUCENTSORTINDEPENDENT );

// シーンを開始する。
if( SUCCEEDED( g_pd3dDevice->BeginScene() ) )
        {
// シーンのジオメトリを通常どおりに配置する。
// このためには、レンダリングする各オブジェクトのワールド行列を設定する。

            g_pd3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST,
D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_TEX1 | D3DFVF_TEXCOORDSIZE3(0),
lpVertices, VERTEX_COUNT, 0);

// シーンを終了する。
g_pd3dDevice->EndScene();
        }
    }
}

注 : キューブ環境マップへのレンダリングを実行する際は、ほとんどのアプリケーションでアンチエイリアシングを有効にする必要がある。各サーフェスは比較的小さなものであるため、そのサーフェスへのレンダリングの際にアンチエイリアシングを有効にしておくと、見た目が非常にきれいな環境マップを生成できる。

ChangeRenderTarget 関数の呼び出しには注意すること。キューブ マップ サーフェスにレンダリングするときは、そのサーフェスをカレント レンダリング ターゲット サーフェスとして割り当てる必要がある。深度バッファを使用するアプリケーションでは、そのレンダリング ターゲットに明示的に深度バッファを作成したり、既存の深度バッファをレンダリング ターゲット サーフェスに再割り当てすることができる。次のコードは、後者の方法を使用する。

HRESULT ChangeRenderTarget( LPDIRECTDRAWSURFACE7 pddsNewTarget)
{
LPDIRECTDRAWSURFACE7 pddsOldRenderTarget = NULL;
g_pd3dDevice->GetRenderTarget( &pddsOldRenderTarget );

if( pddsOldRenderTarget )
    {
LPDIRECTDRAWSURFACE7 pddsZBuffer = NULL;
DDSCAPS2 ddscaps = { DDSCAPS_ZBUFFER, 0, 0, 0 };
pddsOldRenderTarget->GetAttachedSurface( &ddscaps, &pddsZBuffer );

if( pddsZBuffer )
        {
pddsOldRenderTarget->DeleteAttachedSurface( 0, pddsZBuffer );
pddsNewRenderTarget->AddAttachedSurface( pddsZBuffer );
pddsZBuffer->Release();
        }
        pddsOldRenderTarget->Release();
    }

g_pd3dDevice->SetRenderTarget( pddsNewRenderTarget, 0 );
    return S_OK;
}
[Visual Basic]

次の Visual Basic コードは、レンダリングするサーフェスに応じてビュー行列を用意して設定する。

'
' ddsFaces 変数は、各サーフェスに対して 1 つある
' DirectDrawSurface7 オブジェクトの配列のアドレスである。
'
Sub RenderFaces(ddsFaces() As DirectDrawSurface7)
Dim i As Integer

' キューブ マップの 6 つのサーフェスに対してループ処理を実行する。
For i = 0 To UBound(ddsFaces)
Dim ddsc As DDSCAPS2
Dim vEnvEyePt As D3DVECTOR, _
vLookatPt As D3DVECTOR, _
vUpVec As D3DVECTOR

' サーフェス能力を取得する (これにより、どのサーフェスであるかを把握する)。
Call ddsFaces(i).GetCaps(ddsc)

Select Case (ddsc.dwCaps2 And DDSCAPS2_CUBEMAP_ALLFACES)
Case DDSCAPS2_CUBEMAP_POSITIVEX:
vLookatPt.x = 1#:vUpVec.y = 1#

Case DDSCAPS2_CUBEMAP_NEGATIVEX:
vLookatPt.x = -1#:vUpVec = 1#

Case DDSCAPS2_CUBEMAP_POSITIVEY:
vLookatPt.y = 1#:vUpVec.z = -1#

Case DDSCAPS2_CUBEMAP_NEGATIVEY:
vLookatPt.y = -1#:vUpVec.z = 1#

Case DDSCAPS2_CUBEMAP_POSITIVEZ:
vLookatPt.z = 1#:vUpVec.y = 1#

Case DDSCAPS2_CUBEMAP_NEGATIVEZ:
vLookatPt.z = -1#:vUpVec.y = 1#

End Select

Dim matView As D3DMATRIX
Call g_dx.ViewMatrix(matView, vEnvEyePt, vLookatPt, vUpVec)
Call g_pd3dDevice.SetTransform(D3DTRANSFORMSTATE_VIEW, matView)

キューブ環境マップの各サーフェスには 90°の視界が含まれることを思い出すこと。アプリケーションで特殊効果などのために視界の角度を変更しない限り、この角度に応じて射影行列を設定するよう注意が必要である。

次のコードは、最も一般的に使用する射影行列を作成および設定する。

' 90°の視界を射影に使用する。
Dim matProj As D3DMATRIX
Call g_dx.ProjectionMatrix(matProj, 0.5, 1000#, 3.1415926535 / 2)
Call g_d3dDevice.SetTransform(D3DTRANSFORMSTATE_PROJECTION, matProj)

カメラを正しく配置し、射影行列を設定すると、シーンをレンダリングできる。シーンの各オブジェクトは、通常配置するとおりに配置する。次のコードでは、処理を完全に示すために、このタスクについては大まかに示す。

        '
' シーンのレンダリング
        '

' 深度バッファをサーフェスに入れ替え、レンダリング ターゲットして設定する。
' この関数については、後で詳しく説明する。
Call ChangeRenderTarget(ddsFaces(i))

Dim rec(1) As RECT
rec.Top = 0:rec.Left = 0

' サーフェスの大きさは 64x64 であるとする。
rec.Bottom = 64:rec.Right = 64

' z バッファをクリアする。
Call g_d3dDevice.Clear(0, rec(), D3DCLEAR_ZBUFFER, _
g_dx.CreateColorRGBA(0, 0, 256, 0), 1#, 0)

' アンチエイリアシングを有効する。これにより、環境マップの見た目がきれいになる。
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_ANTIALIAS, _
D3DANTIALIAS_TRANSLUCENTSORTINDEPENDENT)

' シーンを開始する。
Call g_d3dDevice.BeginScene
If Err.Number = DD_OK Then
' シーンのジオメトリを通常どおりに配置する。
' このためには、レンダリングする各オブジェクトのワールド行列を設定する。

Call g_pd3dDevice.DrawPrimitive(D3DPT_TRIANGLELIST, D3DFVF_XYZ Or D3DFVF_NORMAL Or _
D3DFVF_TEX1 Or D3DFVF_TEXCOORDSIZE3(0), _
g_Vertices(0), VERTEX_COUNT, 0)

// シーンを終了する。
Call g_d3dDevice.EndScene
End If
Next i
End Sub

注 : キューブ環境マップへのレンダリングを実行する際は、ほとんどのアプリケーションでアンチエイリアシングを有効にする必要がある。各サーフェスは比較的小さなものであるため、そのサーフェスへのレンダリングの際にアンチエイリアシングを有効にしておくと、見た目が非常にきれいな環境マップを生成できる。

ChangeRenderTarget サブルーチンの呼び出しには注意すること。キューブ マップ サーフェスにレンダリングするときは、そのサーフェスをカレント レンダリング ターゲット サーフェスとして割り当てる必要がある。深度バッファを使用するアプリケーションでは、そのレンダリング ターゲットに明示的に深度バッファを作成したり、既存の深度バッファをレンダリング ターゲット サーフェスに再割り当てすることができる。次のコードは、後者の方法を使用する。

Sub ChangeRenderTarget(ddsNewTarget As DirectDrawSurface7)
Dim ddsOldRenderTarget As DirectDrawSurface7

Set ddsOldRenderTarget = g_pd3dDevice.GetRenderTarget

If (ddsOldRenderTarget Is Not Nothing) Then
Dim ddsZBuffer As DirectDrawSurface7
Dim ddscaps As DDSCAPS2

ddscaps.lCaps = DDSCAPS_ZBUFFER
Set ddsZBuffer = ddsOldRenderTarget.GetAttachedSurface

If (ddsZBuffer Is Not Nothing) Then
Call ddsOldRenderTarget.DeleteAttachedSurface(ddsZBuffer)
Call ddsNewRenderTarget.AddAttachedSurface(ddsZBuffer)
End If
End If

Call g_pd3dDevice.SetRenderTarget(pddsNewRenderTarget)
End Sub


キューブ環境マップ サーフェスへのアクセス

[C++]

その他の複合サーフェスと同様、IDirectDrawSurface7::GetAttachedSurface メソッドを使用してキューブ環境マップのサーフェスからサーフェスに移動できる。GetAttachedSurface メソッドは、このメソッドで取得する必要があるアタッチされたサーフェスを記述する DDSCAPS2 構造体へのポインタを受け取る。dwCaps2 メンバに、"DDSCAPS2_CUBEMAP_" で始まるフラグのいずれかを DDSCAPS2_CUBEMAP フラグと組み合わせて設定して、対応するサーフェスを取得する。

次のコードは、正方向の y 面 (サーフェス 2) のキューブ マップ サーフェスを取得する。

// この例では、キューブ マップが最初に作成されたときに CreateSurface が返すサーフェスへの
// 有効なポインタが
// pddsMainFace 変数に格納されている。
LPDIRECTDRAWSURFACE7 pddsFace2;

DDSCAPS2 ddsCaps;
ddsCaps.dwCaps2 = DDSCAPS2_CUBEMAP_POSITIVEY | DDSCAPS2_CUBEMAP;

HRESULT hr;
hr = pddsMainFace->GetAttachedSurface( &ddsCaps,
&pddsFace2);

if( FAILED(hr) )
{
// エラー処理コード
}
[Visual Basic]

その他の複合サーフェスと同様、DirectDrawSurface7.GetAttachedSurface メソッドを使用してキューブ環境マップのサーフェスからサーフェスに移動できる。GetAttachedSurface メソッドは、このメソッドで取得する必要があるアタッチされたサーフェスを記述する DDSCAPS2 型を受け取る。lCaps2 メンバに、"DDSCAPS2_CUBEMAP_" で始まる、CONST_DDSURFACECAPS2FLAGS 列挙からのフラグのいずれかを DDSCAPS2_CUBEMAP フラグと組み合わせて指定して、対応するサーフェスを取得する。

次のコードは、正方向の y 面 (サーフェス 2) のキューブ マップ サーフェスを取得する。

' この例では、キューブ マップが最初に作成されたときに CreateSurface が返すサーフェスへの
' 有効な参照が
' ddsMainFace 変数に格納されている。
Dim ddsFace2 As DirectDrawSurface7
Dim ddsCaps As DDSCAPS2

ddsCaps.lCaps2 = DDSCAPS2_CUBEMAP_POSITIVEY Or DDSCAPS2_CUBEMAP

Set ddsFace2 = ddsMainFace.GetAttachedSurface(ddsCaps)

If Err.Number <> DD_OK Then
' エラー処理コード
End If


頂点バッファ レンダリングについて

アプリケーションが頂点を頂点バッファからレンダリングする一般的なステートは 2 つある。最も基本的なレベルで、2 つのステートは、「レンダリング時」に頂点バッファ内にある頂点の種類によって分けられる。しかし、間接的には、アプリケーションの使用する手順が、いつ頂点操作とレンダリング操作を実行するかを決定する。アプリケーションで頂点バッファからレンダリングする場合は、頂点バッファ メソッドを使用する必要がある。次の図表で、未トランスフォーム頂点バッファからのレンダリング処理を説明する。

[C++]

上の図に示すように、IDirect3DDevice7::DrawPrimitiveVB および IDirect3DDevice7::DrawIndexedPrimitiveVB メソッドでは、未トランスフォームの頂点バッファからのレンダリングを実行できる。この場合、レンダリング メソッドを呼び出すたびに、システムは頂点操作とレンダリング操作を行う。この方法を使用しても、従来の DrawPrimitive レンダリング メソッドよりも優れたパフォーマンスが得られるわけではないが、場合によっては便利なときもある。次の図に示すように、可能であればトランスフォームされた頂点データを再使用して、パフォーマンスを最適化できる。

[Visual Basic]

上の図に示すように、Visual Basic の Direct3DDevice7.DrawPrimitiveVB および Direct3DDevice7.DrawIndexedPrimitiveVB メソッドでは、未トランスフォームの頂点バッファからのレンダリングを実行できる。この場合、レンダリング メソッドを呼び出すたびに、システムは頂点操作とレンダリング操作を行う。この方法を使用しても、従来の DrawPrimitive レンダリング メソッドよりも優れたパフォーマンスが得られるわけではないが、場合によっては便利なときもある。次の図に示すように、可能であればトランスフォームされた頂点データを再使用して、パフォーマンスを最適化できる。

[C++]

この場合、アプリケーションは 2 つの頂点バッファを作成する。1 つは未トランスフォームのジオメトリ用で、もう 1 つはトランスフォームされたジオメトリ用である。IDirect3DVertexBuffer7::ProcessVertices が呼び出されたとき、第 2 バッファはトランスフォーム済み頂点データを取得する。ProcessVertices メソッドは、転送元バッファ内の頂点を読み出し、要求された頂点操作を行い、結果を転送先バッファに入れる。未トランスフォームの頂点をレンダリングするように、トランスフォームされた頂点に対して同じレンダリング メソッドを呼び出すことができる。ただし、未トランスフォームの頂点と異なり、Direct3D は頂点バッファ内のデータがトランスフォームされていることを自動的に検出して、直ちにラスタライズされるよう転送する。不必要なトランスフォームを省略して、パフォーマンスのオーバーヘッドは最小に保たれる。

注 : IDirect3DVertexBuffer7 インターフェイスは、新しいメソッドとして IDirect3DVertexBuffer7::ProcessVerticesStrided を提供する。このメソッドは、ストライド頂点を転送先頂点バッファに処理する。

[Visual Basic]

この場合、アプリケーションは 2 つの頂点バッファを作成する。1 つは未トランスフォームのジオメトリ用で、もう 1 つはトランスフォームされたジオメトリ用である。Direct3DVertexBuffer7.ProcessVertices が呼び出されたとき、第 2 バッファはトランスフォーム済み頂点データを受け取る。ProcessVertices メソッドは、転送元バッファ内の頂点を読み出し、要求された頂点操作を行い、結果を転送先バッファに入れる。未トランスフォームの頂点をレンダリングするように、変換された頂点に対して同じレンダリング メソッドを呼び出すことができる。ただし、未変換の頂点と異なり、Direct3D は頂点バッファ内のデータがトランスフォームされていることを自動的に検出して、直ちにラスタライズされるよう転送する。不必要なトランスフォームを省略して、パフォーマンスのオーバーヘッドは最小に保たれる。

頂点バッファの内容を最適化すると、パフォーマンスをさらに向上できる。詳細については、「頂点バッファの最適化」を参照すること。


ピクセル フォグの使用

アプリケーションでピクセル フォグを有効にするには、次の手順を実行する。

[C++]

C++ アプリケーションでピクセル フォグを有効にするには

  1. D3DRENDERSTATE_FOGENABLE レンダリング ステートを TRUE に設定して、フォグ ブレンディングを有効にする。
  2. D3DRENDERSTATE_FOGCOLOR レンダリング ステートで、希望のフォグ カラーを設定する。
  3. D3DRENDERSTATE_FOGTABLEMODE レンダリング ステートを D3DFOGMODE 列挙型の対応するメンバに設定して、使用するフォグ公式を選択する。
  4. 選択したフォグ モードに必要なフォグ パラメータを、関連するレンダリング ステートに設定する。線形フォグの開始距離と終了距離、指数フォグのフォグ密度も含む。

次の例は、以上の手順をコードで示す。

// 簡単にするために、この例では各呼び出しの後で
// エラー値をチェックしない。実際のアプリケーションでは、
// エラー値を適切にチェックすること。
//
// この例では、g_lpDevice は IDirect3DDevice7 インターフェイスへの
// 有効なポインタである。
void SetupPixelFog(DWORD dwColor, DWORD dwMode)
{
    float fStart = 0.5f,    // 線形モード用
          fEnd   = 0.8f,
          fDensity = 0.66;  // 指数モード用

    // フォグ ブレンディングを有効にする。
    g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGENABLE, TRUE);

    // フォグ カラーを設定する。
    g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGCOLOR, dwColor);

    // フォグ パラメータを設定する。
    if(D3DFOG_LINEAR == dwMode)
    {
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGTABLEMODE, dwMode);
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGSTART, *(DWORD *)(&fStart));
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGEND,   *(DWORD *)(&fEnd));
    }
    else
    {
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGTABLEMODE, dwMode);
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGDENSITY, *(DWORD *)(&fDensity));
    }

}

注 : IDirect3DDevice7::SetRenderState メソッドは、第 2 パラメータに DWORD 値だけを受け取るが、浮動小数点のフォグ パラメータが要求されることもある。上の例では浮動小数点の値を SetRenderState に渡すために、データをトランスフォームするのではなく、浮動小数点変数のアドレスを DWORD ポインタにキャストして、次にそれを参照している。

[Visual Basic]

Visual Basic アプリケーションでピクセル フォグを有効にするには

  1. D3DRENDERSTATE_FOGENABLE レンダリング ステートを True に設定して、フォグ ブレンディングを有効にする。
  2. D3DRENDERSTATE_FOGCOLOR レンダリング ステートで、必要なフォグ カラーを設定する。
  3. D3DRENDERSTATE_FOGTABLEMODE レンダリング ステートを CONST_D3DFOGMODE 列挙の対応するメンバに設定して、使用するフォグ公式を選択する。
  4. 選択したフォグ モードに必要なフォグ パラメータを、関連するレンダリング ステートに設定する。線形フォグの開始距離と終了距離、指数フォグのフォグ密度も含む。

次の例は、以上の手順をコードで示す。

' 簡単にするために、この例では各呼び出しの後で
' エラー値をチェックしない。実際のアプリケーションでは、
' エラー値を適切にチェックすること。
'
' この例では、g_d3dDevice は Direct3DDevice7 オブジェクトへの
' 有効なポインタである。
Sub SetupPixelFog(lColor As Long, Mode As CONST_D3DFOGMODE)
Dim StartFog As Single, _
EndFog As Single, _
Density As Single

' 線形モード用
StartFog = 0.5:EndFog = 0.8

' 指数モード用
Density = 0.66

' フォグ ブレンディングを有効にする。
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGENABLE, True)

' フォグ カラーを設定する。
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGCOLOR, lColor)

' フォグ パラメータを設定する。
If Mode = D3DFOG_LINEAR Then
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGTABLEMODE, Mode)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGSTART, StartFog)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGEND, EndFog)
Else
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGTABLEMODE, Mode)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGDENSITY, Density)
End If
End Sub


ステップ 2.1 : ビューポイントを定義する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

このチュートリアルでは、アプリケーション定義サブルーチン App_FrameMove を使用して、円の上でビューポイントを回転させる。ビューポイントは、視点、注視点、および上方向を定義するベクトルの 3 つの D3DVECTOR 構造体で定義するのが最も簡単である。

HRESULT App_FrameMove( LPDIRECT3DDEVICE7 pd3dDevice, FLOAT fTimeKey )
{
    D3DVECTOR vEyePt    = D3DVECTOR( 5*sinf( fTimeKey), 3, 5*cosf( fTimeKey ) );
    D3DVECTOR vLookatPt = D3DVECTOR( 4*sinf( fTimeKey+0.1f), 2.5, 4*cosf( fTimeKey+0.1f ) );
    D3DVECTOR vUpVec    = D3DVECTOR( 0, 1, 0 );

3 つのベクトルを使用して新しいビュー行列を作成する。

    D3DMATRIX matView;
    SetViewMatrix( matView, vEyePt, vLookatPt, vUpVec );

上記のコードでは、視点、注視点、および上方向を定義するベクトルをプログラマ定義の SetViewMatrix メソッドに渡してデバイスに新しいビュー行列を作成する。これについては、「ステップ 2.2 : ビュー行列を作成および設定する」で説明する。


ステップ 1.3 : デバイス情報を列挙する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

IDirect3D7::EnumDevices メソッドは、システムにインストールされているすべての Direct3D デバイス ドライバを列挙する。Enumeration アプリケーションでは、次のパラメータを使用して EnumDevices 関数を呼び出す。

    pD3D->EnumDevices( DeviceEnumCallback, &d3dDeviceInfo );

第 1 引数 DeviceEnumCallback, は、列挙の際 Direct3D デバイスが渡されるたびに呼び出される D3DEnumDevicesCallback7 コールバック関数のアドレスである。第 2 パラメータは、列挙中のデバイスを記述する D3DDEVICEINFO 構造体への参照である。

列挙されるデバイスごとに、次の関数が呼び出される。

static HRESULT WINAPI DeviceEnumCallback(LPSTR strDesc,
                                  LPSTR strName, D3DDEVICEDESC7* pDesc,
                                  VOID* pParentInfo )
{

最初の 2 つのパラメータは、それぞれデバイスの説明および名前の文字列である。第 3 パラメータ pDesc は、Direct3D デバイスのハードウェア能力を記述する D3DDEVICEDESC7 構造体である。この関数の詳細については、SDK リファレンスの「D3DEnumDevicesCallback7」の項目を参照すること。

次のコードで、列挙中のデバイスにデバイス情報を設定できる。

    D3DDEVICEINFO* pDriverInfo = (D3DDEVICEINFO*)pParentInfo;
    D3DDEVICEINFO* pDeviceInfo = &g_d3dDevices[g_dwNumDevices];
    memcpy( &pDeviceInfo->ddDeviceDesc, pDesc, sizeof(D3DDEVICEDESC7) );
    pDeviceInfo->guidDevice   = pDesc->deviceGUID;
    pDeviceInfo->pDeviceGUID  = &pDeviceInfo->guidDevice;
    pDeviceInfo->bHardware    = pDesc->dwDevCaps & D3DDEVCAPS_HWRASTERIZATION;
    pDeviceInfo->dwNumModes   = 0;
    pDeviceInfo->ddDriverCaps = pDriverInfo->ddDriverCaps;
    pDeviceInfo->ddHELCaps    = pDriverInfo->ddHELCaps;

上記のコードでは、D3DDEVICEINFO 構造体 pDeviceInfo にデバイス能力が格納される。pParentInfo は、ここからドライバの GUID および説明を取り出せるように D3DDEVICEINFO 型にキャストされることに注意する。

デバイス情報を取得できたので、デバイス情報を保持する D3DDEVICEINFO 構造体にデバイスのドライバ GUID および説明をコピーする。

        pDeviceInfo->guidDriver  = pDriverInfo->guidDriver;
        pDeviceInfo->pDriverGUID = &pDeviceInfo->guidDriver;
        strncpy( pDeviceInfo->strDesc, pDriverInfo->strDesc, 39 );

ディスプレイ ドライバ、ディスプレイ モード、およびデバイスを列挙したら、次はアプリケーションで使用するデバイスをこれらの中から選択する。これについては、「ステップ 2 : 列挙されたデバイスの選択」で説明する。


ステップ 2.4 : ビューポートを準備する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

レンダリング デバイスを作成した後、ビューポートを作成してデバイスに割り当てることができる。簡単に言えば、ビューポートとは、3D シーンのジオメトリをクリップして 2D 表示空間に表現する方法を決定するものである。(ビューポートの概要については、「ビューポートとクリッピング」を参照すること)。

ビューポートの設定は簡単で、D3DVIEWPORT7 構造体にビューポート パラメータを準備することから始まる。サンプル Triangle では、ビューポート パラメータをレンダリング ターゲット サーフェスのサイズに設定している。

    // ビューポートを作成する。
    DWORD dwRenderWidth  = g_rcScreenRect.right - g_rcScreenRect.left;
    DWORD dwRenderHeight = g_rcScreenRect.bottom - g_rcScreenRect.top;
    D3DVIEWPORT7 vp = { 0, 0, dwRenderWidth, dwRenderHeight, 0.0f, 1.0f };

ビューポート構造体を準備すると、この構造体は Triangle アプリケーションによってレンダリング デバイスに割り当てられる。

    hr = g_pd3dDevice->SetViewport( &vp );
    if( FAILED( hr ) )
        return hr;

ここで、基本的な DirectX オブジェクトの作成が終了したので、シーンのレンダリングに必要な従属オブジェクトの準備を始めることができる。これが、「ステップ 3 : シーンを初期化する」の説明内容である。


ステップ 1.2 : ディスプレイ モード情報を列挙する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

IDirectDraw7::EnumDisplayModes メソッドは、ハードウェアが DirectDraw オブジェクトを介して公開するすべてのディスプレイ モードを列挙する。Enumeration アプリケーションでは、次のパラメータを使用して EnumDisplayModes 関数を呼び出す。

    // フルスクリーン ディスプレイ モードを列挙する。
    pDD->EnumDisplayModes( 0, NULL, &d3dDeviceInfo, ModeEnumCallback );

引数 NULL はすべてのモードの列挙を指定する。第 3 パラメータ &d3dDeviceInfo は、ドライバ情報を格納する D3DDEVICEINFO 構造体のアドレスであり、各列挙メンバに渡される。第 4 パラメータは、EnumModesCallback2 コールバック関数のアドレス ModeEnumCallback であり、ハードウェアが公開する全モードに対して列挙プロシージャで呼び出される。

static HRESULT WINAPI ModeEnumCallback( DDSURFACEDESC2* pddsd,
                                        VOID* pParentInfo )
{
    // ドライバでサポートされるモードのリストにモードをコピーする。
    D3DDEVICEINFO* pDriverInfo = (D3DDEVICEINFO*)pParentInfo;
    pDriverInfo->ddsdModes[pDriverInfo->dwNumModes++] = (*pddsd);

    return DDENUMRET_OK;
}

上記のコードでは、最初のパラメータ pddsd, は、作成可能なディスプレイ モードに関する情報を格納する読み込み専用の DDSURFACEDESC2 構造体である。pParentInfo パラメータ (ディスプレイ ドライバを表すアプリケーション定義データ) は、確実に参照されるように D3DDEVICEINFO 構造体にキャストされる。すべてのディスプレイ モードが列挙されたら、次は Direct3D デバイスを列挙する。このステップについては、「ステップ 1.3 : デバイス情報を列挙する」で説明する。


ステップ 2.2 : ビュー行列を作成および設定する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

視点、注視点、上方向ベクトルを指定すると、アプリケーションに手動で 4×4 ビュー行列を作成できる。まず、奥行きを示す z 軸ベクトルを取得する。

HRESULT SetViewMatrix( D3DMATRIX& mat, D3DVECTOR& vFrom, D3DVECTOR& vAt,
                       D3DVECTOR& vWorldUp )
{
    // 奥行きを示す z 軸ベクトルを取得する。これは注視点に対する
    // 視点とは異なる。
    D3DVECTOR vView = vAt - vFrom;

z 軸ベクトルは、注視点に対する視点とは異なる。z 軸ベクトルは、計算に使用する前に正規化する必要がある。

    FLOAT fLength = Magnitude( vView );
    if( fLength < 1e-6f )
        return E_INVALIDARG;

    // z 軸ベクトルを正規化する。
    vView /= fLength;

上記のコードでは、ビュー ベクトルの絶対値を返す Magnitude 関数を使用している。Magnitude 関数は、プロジェクトで D3D_OVERLOADS を定義するプログラマが使用する。D3D_OVERLOADS の C++ 拡張機能によって提供される。ヘルパー関数の詳細については、「D3D_OVERLOADS ヘルパー関数」を参照すること。

この時点で、内積を取得して z 軸ベクトルにおける上方向ベクトルへの射影を計算できる。最終的にこの射影は ｙ 軸ベクトルになる。

    FLOAT fDotProduct = DotProduct( vWorldUp, vView );

    D3DVECTOR vUp = vWorldUp - fDotProduct * vView;

注 : DotProduct は D3D_OVERLOADS に定義される関数である。

次のコードは、y 軸ベクトルを正規化する。

    vUp /= fLength;

x 軸ベクトルを検出するには、y 軸および z 軸ベクトルの外積を求める。

    D3DVECTOR vRight = CrossProduct( vUp, vView );

注 : CrossProduct は D3D_OVERLOADS に定義される関数である。

この時点で、新しいビュー行列の作成を開始するための情報が揃っている。次のコードでは、最初の 3 つの行に、注視点を指すビューを回転させるための基底ベクトルを含める。

    mat._11 = vRight.x;  mat._12 = vUp.x;  mat._13 = vView.x;  mat._14 = 0.0f;
    mat._21 = vRight.y;  mat._22 = vUp.y;  mat._23 = vView.y;  mat._24 = 0.0f;
    mat._31 = vRight.z;  mat._32 = vUp.z;  mat._33 = vView.z;  mat._34 = 0.0f;

次に平行移動値を設定する。ただし、視点の周りで回転することに注意する。

    mat._41 = - DotProduct( vFrom, vRight );
    mat._42 = - DotProduct( vFrom, vUp );
    mat._43 = - DotProduct( vFrom, vView );
    mat._44 = 1.0f;

平行移動値を設定すると、制御がアプリケーション定義関数 App_FrameMove の呼び出しに戻る。IDirect3DDevice7::SetTransform メソッドを呼び出して、新しいビュー行列を有効にする。

    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_VIEW, &matView );

立方体の頂点はプログラマ定義関数 TransformVertices によってトランスフォームされる。これについては、「ステップ 2.3 : 3D トランスフォームを実行する」で説明する。


ステップ 2.4 : シーンをレンダリングする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

次の IDirect3DDevice7::DrawPrimitive の呼び出しは、D3DVERTEX 型の三角形ストリップから構成される壁セグメントを描く。

    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX,
                               g_pvWall, NUM_WALL_VERTICES, NULL );

次の DrawPrimitive の呼び出しは、カスタム化した「柔軟な頂点フォーマット」を持つ三角形ファンを描く。

    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLEFAN, D3DFVF_XYZ|D3DFVF_NORMAL,
                               g_pvCone, NUM_CONE_VERTICES, NULL );

最後に、次の IDirect3DDevice7::DrawIndexedPrimitive 呼び出しは、アプリケーションでトランスフォーム & ライティングが適用されてインデックス付けが行われた頂点から構成される立方体を描く。

    pd3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, D3DFVF_TLVERTEX,
                                      g_pvCube, NUM_CUBE_VERTICES,
                                      g_pwCubeIndices, NUM_CUBE_INDICES, NULL );


ステップ 1.3 : 立方体を準備する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

立方体は、インデックス付けされたプリミティブとして表される。このため、立方体のレンダリングは、頂点の配列をインデックス付けすることで実行される。特に、レンダリング中は、立方体の頂点リストにインデックスを付けるために次のインデックスが使用される。

    WORD* pwIndex = g_pwCubeIndices;
    *pwIndex++ = 1;  *pwIndex++ = 2;  *pwIndex++ = 3;
    *pwIndex++ = 2;  *pwIndex++ = 1;  *pwIndex++ = 0;
    *pwIndex++ = 4;  *pwIndex++ = 5;  *pwIndex++ = 6;
    *pwIndex++ = 6;  *pwIndex++ = 5;  *pwIndex++ = 7;
    *pwIndex++ = 3;  *pwIndex++ = 2;  *pwIndex++ = 6;
    *pwIndex++ = 3;  *pwIndex++ = 6;  *pwIndex++ = 7;
    *pwIndex++ = 0;  *pwIndex++ = 1;  *pwIndex++ = 4;
    *pwIndex++ = 4;  *pwIndex++ = 1;  *pwIndex++ = 5;
    *pwIndex++ = 2;  *pwIndex++ = 0;  *pwIndex++ = 4;
    *pwIndex++ = 2;  *pwIndex++ = 4;  *pwIndex++ = 6;
    *pwIndex++ = 1;  *pwIndex++ = 3;  *pwIndex++ = 5;
    *pwIndex++ = 5;  *pwIndex++ = 3;  *pwIndex++ = 7;

シーンのすべてのオブジェクトにジオメトリを定義したら、次はシーンをレンダリングおよび表示する。これが、「ステップ 2 : シーンをレンダリング、表示する」の説明内容である。


ステップ 3.2 : マテリアルと初期ライティング ステートをセット アップする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

基本的な 3D レンダリング オブジェクト (DirectDraw オブジェクト、レンダリング デバイス、およびビューポート) を作成すると、単純なシーンをレンダリングするのに必要なすべてのものが、ほぼ揃ったことになる。次にすることは、マテリアルを作成、構成し、初期ライティング ステートを設定することである。設定はすべて、必要に応じて、後で変更することができる。概念的な説明については、「ライティングとマテリアル」を参照すること。

サンプル Triangle では、次のようにマテリアル パラメータを設定する。

    D3DMATERIAL7 mtrl;
    ZeroMemory( &mtrl, sizeof(mtrl) );
    mtrl.ambient.r = 1.0f;
    mtrl.ambient.g = 1.0f;
    mtrl.ambient.b = 0.0f;
    pd3dDevice->SetMaterial( &mtrl );

上記のコードでは、D3DMATERIAL7 構造体で表すマテリアル プロパティを準備している。また、D3DMATERIAL7 構造体によって、アンビエント ライトの赤および緑成分を反射するマテリアルを記述している。これにより、マテリアルはシーンの中で黄色に見える (このチュートリアルでは、アンビエント ライトだけを使用するので、アンビエント反射率プロパティだけを設定する。実際のアプリケーションでは、アンビエント ライトだけでなくダイレクト ライトも使用するので、ディフューズおよびスペキュラ反射率のプロパティも設定する)。マテリアル プロパティを準備した後、このコードでは、IDirect3DDevice7::SetMaterial メソッドを呼び出してこのプロパティをデバイスに適用している。

注 : テクスチャを使用する場合、オブジェクト マテリアルは通常省略されるか白色にされる。

現在のマテリアルを選択すると、すべてのポリゴンが、このマテリアルを使用してレンダリングされる。ただし、シーン中の何かを可視状態にするには、ライティングを与える必要がある。Triangle アプリケーションでは、白色アンビエント ライトの D3DRENDERSTATE_AMBIENT レンダリング ステートを指定した IDirect3DDevice7::SetRenderState メソッドを呼び出して、アンビエント ライト レベルを設定する。

    // アンビエント ライト値は別の状態に設定されている。ここでは、アンビエント ライトを
    // 完全な白色に設定する。
    pd3dDevice->SetRenderState( D3DRENDERSTATE_AMBIENT, 0xffffffff );

ここで、ジオメトリ、マテリアル、および初期ライティング パラメータが設定されたので、サンプル Triangle は、座標トランスフォーム行列のセット アップに進む。これについては、「ステップ 3.3 : 座標トランスフォーム行列を準備、設定する」で説明する。


ステップ 2.1 : デバイスを取得する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

デバイスをテストするには、まずテストするデバイスを取得しなければならない。この項では、デバイスでサポートされるすべてのディスプレイ設定でデバイスをテストできるように、デバイス情報を取得する方法について説明する。

 for( DWORD i=0; i<pDriverInfo->dwNumModes; i++ )
    {
        DDSURFACEDESC2 ddsdMode = pDriverInfo->ddsdModes[i];
        DWORD dwModeDepth = ddsdMode.ddpfPixelFormat.dwRGBBitCount;
        DWORD dwBitDepth  = pDeviceInfo->ddDeviceDesc.dwDeviceRenderBitDepth;
        BOOL  bCompatible = FALSE;

上記のコードによる変数割り当てによって、デバイスのビデオ モード記述を取得し、返されたビデオ モード記述内でピクセルあたりのビット サポートを取得し、デバイスのレンダリング ビット深度を取得する。この情報は、デバイス能力のテストに使用される。

テストするデバイスの情報を取得したら、次はデバイスをテストする。このステップについては、「ステップ 2.2 : デバイスをテストする」で説明する。


ステップ 2.3 : Direct3D を初期化する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーションでシーンをレンダリングおよび表示するために必要なサーフェスを作成した後、DirectDraw オブジェクトの IDirect3D7 インターフェイスへのポインタを取得して、Direct3D オブジェクトを初期化することができる。このインターフェイスは、シーンのレンダリングに必要なすべてのオブジェクトを作成するのに使用する。このインターフェイスは、DirectDraw オブジェクトによって開示され、別のオブジェクトではなく、別の機能のセットを表すことに注意する。IDirect3D7 インターフェイスは、DirectDraw オブジェクトの IUnknown::QueryInterface メソッドを呼び出して取得する。Triangle の次のコードが、このタスクを実行する。

    // Direct3D にアクセスするため、DirectDraw に問い合わせる。
    g_pDD->QueryInterface( IID_IDirect3D7, (VOID**)&g_pD3D );
    if( FAILED( hr) )
        return hr;

IDirect3D7 インターフェイスへのポインタを取得すると、IDirect3D7::CreateDevice メソッドを呼び出してレンダリング デバイスを作成することができる。CreateDevice メソッドは、目的のデバイスのグローバル ユニーク識別子 (GUID)、デバイスがレンダリングするサーフェスの IDirectDrawSurface7 インターフェイスのアドレス、およびデバイス オブジェクトの作成が成功した場合にメソッドが IDirect3DDevice7 インターフェイス ポインタに設定する変数のアドレスを受け取る。チュートリアルでは、GUID をコード中に書き込んで使用しているが、実際のアプリケーションでは、デバイスを列挙して GUID を取得する必要がある。デバイスの列挙については、「Direct3D デバイスの列挙」を参照すること。

(サンプル Triangle では、デバイスの作成前にディスプレイ モードをチェックしている。ディスプレイにパレット モードが設定されている場合、コードは終了する。関連するパレットを持たないパレット サーフェスにデバイスを作成しようとすると、CreateDevice メソッドの失敗を引き起こす。これは、コードを簡単にするために行ったものである。実際のアプリケーションでは、レンダリング ターゲット サーフェスを作成し、パレットをアタッチするか、ディスプレイ モードを 16 ビット カラー以上に設定するよう、ユーザーに要求するかのどちらかを行う)。

Triangle から抜粋した次のコードが、ディスプレイ モードのチェックを行い、レンダリング デバイスを作成する。

    // ディスプレイ モードをチェックする。
    ddsd.dwSize = sizeof(DDSURFACEDESC2);
    g_pDD->GetDisplayMode( &ddsd );
    if( ddsd.ddpfPixelFormat.dwRGBBitCount <= 8 )
        return DDERR_INVALIDMODE;

    // ここでの GUID はコード中に書き込まれている。実際のアプリケーションでは
    // GUID をデバイスの列挙によって取得する必要がある。
    hr = g_pD3D->CreateDevice( IID_IDirect3DHALDevice, g_pddsBackBuffer,
                               &g_pd3dDevice );
    if( FAILED( hr ) )
    {
        // ハードウェア GUID が機能しない場合には、ソフトウェア デバイスを試してみる。
        hr = g_pD3D->CreateDevice( IID_IDirect3DRGBDevice, g_pddsBackBuffer,
                                   &g_pd3dDevice );
        if( FAILED( hr ) )
            return hr;
    }

CreateDevice メソッドは多くの理由から失敗することがある。最も起こりやすい原因は、プライマリ ディスプレイ デバイスが 3D 機能をサポートしない場合である。ほかの可能性として、表示ハードウェアが、現在のディスプレイ モードではレンダリングができないという場合がある。これらの可能性をデバイス列挙の際にチェックしておく必要がある。コードを簡単にするため、Triangle では、ハードウェア デバイスが作成できない場合、ソフトウェア レンダリング デバイスの作成を試みることにしている。

注 : CreateDevice メソッドは DirectDrawSurface オブジェクトへのポインタを受け取るが、レンダリング デバイスはサーフェスではない。レンダリング デバイスは、レンダリングされるシーンのグラフィックスを含むサーフェスを使用する、離散型 COM オブジェクトである。

デバイスが作成されたら、次はビューポートを作成してデバイスに割り当てる。これについては、「ステップ 2.4 : ビューポートを準備する」で説明する。


ステップ 5.3 : ディスプレイを更新する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

レンダリング ターゲット サーフェスに対するシーンのレンダリングを終了すると、その結果を画面上に表示することができる。ウィンドウ アプリケーションの場合、通常、レンダリング ターゲット サーフェスの内容をプライマリ サーフェスにブリットすることにより表示を行う。ページ フリッピングを採用しているフルスクリーン アプリケーションの場合、フリッピング チェーンのサーフェスをフリップするだけで表示を行う。サンプル Triangle は、ウィンドウで実行されるため、次のコードにより、前者の方法を使用する。

HRESULT ShowFrame()
{
    if( NULL == g_pddsPrimary )
        return E_FAIL;

    // ウィンドウ モードなので、バック バッファから
    // プライマリ サーフェスの正確な位置に、ブリットを実行する。
    return g_pddsPrimary->Blt( &g_rcScreenRect, g_pddsBackBuffer,
                               &g_rcViewportRect, DDBLT_WAIT, NULL );
}

上記のアプリケーション定義関数は、レンダリング ターゲット サーフェスの内容全体を、デスクトップのウィンドウにブリットするだけであることに注意する。このチュートリアルでは、ブリット対象の矩形を、グローバル変数 g_rcScreenRect で追跡する。この矩形は、ユーザーがウィンドウを移動するたびに更新される。これについては、「ウィンドウの移動を処理する」で説明する。


ステップ 2.2 : 新しいサーフェスを作成する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

テクスチャに新しいサーフェスを作成するには、IDirectDraw7::CreateSurface メソッドを使用する。

    if( FAILED( hr = pDD->CreateSurface( &ddsd, &pddsTexture, NULL ) ) )
    {
        pDD->Release();
        return NULL;
    }

CreateSurface メソッドの第 1 パラメータは、サーフェス テクスチャ オブジェクトを記述する DDSURFACEDESC2 構造体である。呼び出しが終了すると、第 2 パラメータがテクスチャ サーフェスの IDirectDrawSurface7 インターフェイス ポインタに設定される。

ここでは、テクスチャ サーフェスとして使用するサーフェスを作成した。次は、このテクスチャ サーフェスにビットマップをコピーする。このステップについては、「ステップ 2.3 : レンダリング サーフェスにコピーする」で説明する。


ステップ 1.3 : テクスチャ管理を有効にする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

テクスチャ サーフェス オブジェクトを作成する場合は、まずデバイスのテクスチャ管理を有効する必要がある。テクスチャ管理属性を使用することで、複雑なテクスチャ管理が Direct3D 側で行われるようになる。

ハードウェア デバイスのテクスチャ管理は、次のコードで有効にできる。

    if( ddDesc.deviceGUID == IID_IDirect3DHALDevice )
        ddsd.ddsCaps.dwCaps2 = DDSCAPS2_TEXTUREMANAGE;
    else if( ddDesc.deviceGUID == IID_IDirect3DTnLHalDevice )
        ddsd.ddsCaps.dwCaps2 = DDSCAPS2_TEXTUREMANAGE;
    else
        ddsd.ddsCaps.dwCaps |= DDSCAPS_SYSTEMMEMORY;

テクスチャ管理の詳細については、「自動テクスチャ管理」を参照すること。

次に、ddDesc (レンダリング デバイスの記述を含む D3DDEVICEDESC7 構造体) を使用してデバイス能力を調べる。ドライバでの必要に応じて、サーフェス記述の幅と高さを調整する。

    if( ddDesc.dpcTriCaps.dwTextureCaps & D3DPTEXTURECAPS_POW2 )
    {
        for( ddsd.dwWidth=1;  dwWidth>ddsd.dwWidth;   ddsd.dwWidth<<=1 );
        for( ddsd.dwHeight=1; dwHeight>ddsd.dwHeight; ddsd.dwHeight<<=1 );
    }
    if( ddDesc.dpcTriCaps.dwTextureCaps & D3DPTEXTURECAPS_SQUAREONLY )
    {
        if( ddsd.dwWidth > ddsd.dwHeight ) ddsd.dwHeight = ddsd.dwWidth;
        else                               ddsd.dwWidth  = ddsd.dwHeight;
    }

ここでは、テクスチャ管理を有効にし、サーフェス記述とドライバとの互換性を確認した。次は、テクスチャ フォーマットを列挙する。このタスクについては、「ステップ 1.4 : テクスチャ フォーマットを列挙する」で説明する。


ステップ 1.2 : 円錐を準備する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

円錐のジオメトリの準備には、位置ベクトルおよび法線ベクトルを宣言するだけでよい。このため、DrawPrims アプリケーションの円錐オブジェクトは、次のプログラマ定義構造で定義される。

struct MyFlexibleVertex
{
    D3DVECTOR vPosition;
    D3DVECTOR vNormal;
};

次のコードで、円錐の先端を定義する。

    g_pvCone[0].vPosition = D3DVECTOR( 0, CONE_HEIGHT/2, 0 );
    g_pvCone[0].vNormal   = Normalize( D3DVECTOR( 0, 1, 0 ) );

次の三角関数で、円錐の各側面を計算する。

    for( i=0; i<NUM_CONE_SIDES; i++ )
    {
        FLOAT x = (FLOAT)sin( 2*g_PI*i/(NUM_CONE_SIDES-1) );
        FLOAT y = -CONE_HEIGHT/2;
        FLOAT z = (FLOAT)cos( 2*g_PI*i/(NUM_CONE_SIDES-1) );
        g_pvCone[i+1].vPosition = CONE_RADIUS * D3DVECTOR( x, y, z );

次のコードで、円錐の各側面の位置ベクトルを計算する。

    g_pvCone[i+1].vNormal   = Normalize( D3DVECTOR( x, 0.5f, z ) );
    }

ジオメトリ空間に壁セグメントと円錐を定義したら、次は立方体を準備する。この処理については、「ステップ 1.3 : 立方体を準備する」で説明する。


ステップ 1.4 : テクスチャ フォーマットを列挙する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

テクスチャ フォーマットを列挙することで、レンダリング デバイスでサポートされるテクスチャ フォーマットをアプリケーションで選択できるようになる。IDirect3DDevice7::EnumTextureFormats メソッドを使用して、サポートされるテクスチャ フォーマットのリストについて現在のドライバに問い合わせる。

    pd3dDevice->EnumTextureFormats( TextureSearchCallback, &ddsd.ddpfPixelFormat );

上記の関数呼び出しでは、TextureSearchCallback パラメータは、列挙プロセスで各テクスチャ フォーマットに対して呼び出されるアプリケーション定義コールバック関数 D3DEnumPixelFormatsCallback のアドレスである。

次のコードは TextureSearchCallback コールバック関数の一部である。このコードでは、ループ処理を使用して、デバイスでサポートされるテクスチャ ピクセル フォーマットを検索する。特に、ここで検索するのは 16 ビット テクスチャである。アルファ テクスチャなど、ほかのフォーマットは無視される。

    if( pddpf->dwFlags & (DDPF_LUMINANCE|DDPF_BUMPLUMINANCE|DDPF_BUMPDUDV) )
        return DDENUMRET_OK;

    // すべての FourCC フォーマットをスキップする。
    if( pddpf->dwFourCC != 0 )
        return DDENUMRET_OK;

    // アルファ モードをスキップする。
    if( pddpf->dwFlags&DDPF_ALPHAPIXELS )
        return DDENUMRET_OK;

    // 検索するのは 16 ビット フォーマットであり、それ以外のフォーマットはすべてスキップする。
    if( pddpf->dwRGBBitCount != 16 )
        return DDENUMRET_OK;

    // 一致するフォーマットが見つかった場合は、現在のピクセル フォーマットを出力パラメータに
    // コピーする。
    memcpy( (DDPIXELFORMAT*)param, pddpf, sizeof(DDPIXELFORMAT) );

    // DDENUMRET_CANCEL を返して列挙を終了する。
    return DDENUMRET_CANCEL;
}

ここでは、テクスチャ フォーマットの列挙 TextureEnum から、レンダリング デバイスでサポートされるテクスチャ フォーマットを選択した。次は、テクスチャにサーフェスを作成する。このステップについては、「ステップ 2 : テクスチャ サーフェスを作成する」で詳しく説明する。


ステップ 1.1 : テクスチャ座標を設定する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

Direct3D では、テクスチャは 2 次元配列のカラー値として表される。配列内の各要素は、テクセルとして参照される。テクセルは、それぞれ U および V とラベル付けされた列および行で識別できる。

アプリケーションでは、頂点のテクスチャ座標を記述する値で D3DVERTEX 構造体を初期化して、テクスチャ座標を頂点に直接割り当てる。次は Texture アプリケーションのコードの一部である。このコードでは、立方体の前面を記述する 4 つの頂点を作成している。

    *pVertices++ = D3DVERTEX( D3DVECTOR(-1.0f, 1.0f,-1.0f), n0, 0.0f, 0.0f );
    *pVertices++ = D3DVERTEX( D3DVECTOR( 1.0f, 1.0f,-1.0f), n0, 1.0f, 0.0f );
    *pVertices++ = D3DVERTEX( D3DVECTOR(-1.0f,-1.0f,-1.0f), n0, 0.0f, 1.0f );
    *pVertices++ = D3DVERTEX( D3DVECTOR( 1.0f,-1.0f,-1.0f), n0, 1.0f, 1.0f );

D3DVERTEX の割り当てを行うときは、第 1 引数で頂点を定義し、第 2 引数で頂点の法線ベクトル (法線の定義については、SDK 付属の Texture アプリケーションのコードを参照) の方向を定義し、次の 2 つの引数で頂点のテクスチャ座標を表す。この例では、アプリケーションで立方体の前面にビットマップ テクスチャ全体をマップするので、テクスチャ座標は (0, 0)、(1, 0)、(0, 1)、(1, 1) になる。

テクスチャ座標の詳細については、「テクスチャ座標」を参照すること。

これまで立方体の背面、上面、底面、右側面、および左側面に定義したときと同じ方法を用いる必要がある。この方法については、SDK 付属の Texture アプリケーションのコードを参照すること。

Texture アプリケーションは、テクスチャ サーフェス オブジェクトとして IDirectDrawSurface7 オブジェクトを返すプログラマ定義関数 CreateTexture を実装している。

    g_pddsTexture1 = CreateTexture( pd3dDevice, "tree1.bmp" );
    g_pddsTexture2 = CreateTexture( pd3dDevice, "tex1.bmp" );
    g_pddsTexture3 = CreateTexture( pd3dDevice, "earth.bmp" );

上記のコードでは、ファイルベースのビットマップ "tree1.bmp"、"tex1.bmp"、および "earth.bmp" から 3 つのテクスチャ サーフェス オブジェクトを作成している。それぞれの関数呼び出しにおいて、第 1 引数 pd3dDevice はアプリケーションのレンダリング デバイスへの参照である。返されるテクスチャ サーフェス オブジェクト (g_pddsTexture1、g_pddsTexture2、および g_pddsTexture3) は、レンダリング中に立方体プリミティブに設定される。

プログラマ定義関数 CreateTexture を詳細に調べて、テクスチャ サーフェス オブジェクトの準備方法および作成方法を確認できる。このタスクの最初のステップについては、「ステップ 1.2 : テクスチャ サーフェスを準備する」で説明する。


ステップ 2.3 : レンダリング サーフェスにコピーする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

テクスチャ サーフェスにビットマップをコピーするには、ビットマップのデバイス コンテキスト (DC) およびサーフェスの DC を作成する。

注 : DC はグラフィックス オブジェクトの属性を格納、取得、および修正する GDI 構造体であり、グラフィックス モードを指定する。サーフェスの DC には、レンダリング デバイスでのグラフィックス表示を制御する情報が収められる。ビットマップの DC に格納されるグラフィックス オブジェクトは、コピー用のビットマップである。

ビットマップの DC は、次のコードで取得できる。

    HDC hdcBitmap = CreateCompatibleDC( NULL );
    if( NULL == hdcBitmap )
    {
        pddsTexture->Release();
        return NULL;
    }
    SelectObject( hdcBitmap, hbm );

CreateCompatibleDC 関数は、指定されたデバイス (アプリケーションの現在のスクリーン設定) との互換性を持つメモリ DC を作成する GDI 関数である。詳細については、「プラットフォーム SDK」を参照すること。

次に、サーフェスの DC を取得する。

    HDC hdcTexture;
    if( SUCCEEDED( pddsTexture->GetDC( &hdcTexture ) ) )
    {

上記のコードでは、IDirectDrawSurface7::GetDC メソッドがサーフェスの DC を返す。

次のコードで、ビットマップ画像をサーフェスにコピーする。

        BitBlt( hdcTexture, 0, 0, bm.bmWidth, bm.bmHeight, hdcBitmap,
                0, 0, SRCCOPY );
        pddsTexture->ReleaseDC( hdcTexture );
    }
    DeleteDC( hdcBitmap );

    // 新しく作成されたテクスチャを返す。
    return pddsTexture;
}

BitBlt 関数は、指定された転送元 DC (hdcBitmap) から転送先 DC (hdcTexture) に色データのビット ブリットを行うグラフィックス デバイス インターフェイス (GDI) 関数である。詳細については、「プラットフォーム SDK」を参照すること。

ここでは、テクスチャに新しいサーフェスを作成した。次は、このテクスチャを使用してプリミティブのレンダリングを実行する。このタスクについては、「ステップ 3 : テクスチャ プリミティブのレンダリング」で説明する。


ステップ 1.2 : テクスチャ サーフェスを準備する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

一般に、実際のテクスチャ サーフェスを準備する場合は、まずビットマップのハンドルを作成し、そのハンドルにテクスチャ サーフェスをロードする必要がある。ただし、ビットマップのハンドルを作成する場合は、アプリケーションがビットマップ ファイル ("tree1.bmp"、"tex1.bmp"、および "earth.bmp") を確実に検出できなければならない。最初のステップとして、ビットマップ ファイルの実行可能ファイルのリソースをチェックする。

    HBITMAP hbm = (HBITMAP)LoadImage( GetModuleHandle(NULL), strName,
                              IMAGE_BITMAP, 0, 0,
                              LR_CREATEDIBSECTION);

上記の LoadImage 関数の呼び出しでは、最初の引数は呼び出しプロセスを作成するためのファイルのハンドル、つまり実行可能ファイルのリソースである。この最初のパラメータにより、ロードする画像を格納するモジュールのインスタンスへのハンドルを返すことができる。第 2 パラメータは、ロードするビットマップ画像を特定する。第 3、第 4、および第 5 パラメータは、ビットマップ タイプのロード、およびビットマップ画像の実際の幅と高さを指定する。最後の引数はロード フラグである。これにより、ディスプレイ デバイスのカラーにマッピングせずにビットマップをロードする。

LoadImage の詳細については、「プラットフォーム SDK」を参照すること。

Texture アプリケーションでは、呼び出しプロセスの作成に使用されるファイルへのハンドルを使ってファイルを検出できなかった場合、ビットマップ画像をファイルとしてロードしようとする。ただし、実際のアプリケーションでは、複数のファイル パスを検索してビットマップを探そうとする。

      hbm = (HBITMAP)LoadImage( NULL, strName, IMAGE_BITMAP, 0, 0,
                                LR_LOADFROMFILE|LR_CREATEDIBSECTION );

上記の LoadImage 関数の呼び出しでは、画像を格納するインスタンスのハンドルが指定されていないが、LR_LOADFROMFILE ロード フラグを設定することで、strName パラメータがビットマップ画像を格納するファイル名であることを示している。

テクスチャを準備および作成するタスクは、次のプログラマ定義関数 CreateTextureFromBitmap を呼び出して行う。この関数には、レンダリング デバイスへの参照、およびテクスチャとして使用するビットマップへのハンドルを渡す。

    return CreateTextureFromBitmap( pd3dDevice, hbm );

CreateTextureFromBitmap はデバイス能力を取得する。これにより、デバイスにテクスチャの使用に関する制約があるかどうかを調べることができる。

    D3DDEVICEDESC7 ddDesc;
    ddDesc.dwSize = sizeof(D3DDEVICEDESC7);
    if( FAILED( pd3dDevice->GetCaps( &ddDesc ) ) )
        return NULL;

上記のコードでは、D3DDEVICEDESC7 構造体の ddDesc が初期化される。次に、IDirect3DDevice7::GetCaps メソッドを使用してレンダリング デバイスの記述を取得する。

次に、GetObject 関数を使用して、テクスチャとして使うビットマップを取得する。これにより、ビットマップ グラフィックス オブジェクトの幅と高さを取得できるようになる。

    BITMAP bm;
    GetObject( hbm, sizeof(BITMAP), &bm );
    DWORD dwWidth  = (DWORD)bm.bmWidth;
    DWORD dwHeight = (DWORD)bm.bmHeight;

BITMAP 構造体は、ビットマップを定義する GDI 構造体である。詳細については、「プラットフォーム SDK」を参照すること。

GetObject 関数は、指定されたグラフィックス オブジェクトに関する情報を取得する GDI 関数である。詳細については、「プラットフォーム SDK」を参照すること。

テクスチャ サーフェスの記述には DDSURFACEDESC2 構造体を使用する。この時点で、テクスチャに新しいサーフェス記述を設定できる。

    DDSURFACEDESC2 ddsd;
    ZeroMemory( &ddsd, sizeof(DDSURFACEDESC2) );
    ddsd.dwSize          = sizeof(DDSURFACEDESC2);
    ddsd.dwFlags         = DDSD_CAPS|DDSD_HEIGHT|DDSD_WIDTH|
                           DDSD_PIXELFORMAT|DDSD_TEXTURESTAGE;
    ddsd.ddsCaps.dwCaps  = DDSCAPS_TEXTURE;
    ddsd.dwWidth         = dwWidth;
    ddsd.dwHeight        = dwHeight;

特に制御フラグ DDSCAPS_TEXTURE を設定することで、サーフェスによってテクスチャ サーフェスを記述することをシステムに知らせる。次は、自動テクスチャ管理を有効にする。このステップについては、「ステップ 1.3 : テクスチャ管理を有効にする」で説明する。


ステップ 2.3 : 3D トランスフォームを実行する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

シーンはほぼ完成しているが、立方体の頂点を手動で回転、平行移動、およびスケーリングする処理が残っている。まず、D3DTLVERTEX 構造体の配列 g_pvCube に立方体の未トランスフォーム データを格納する。最初の 3 つのパラメータは、スクリーン座標の各頂点の未トランスフォームの位置座標を表している。

    g_pvCube[0] = D3DTLVERTEX( D3DVECTOR(-1,-1,-1 ), 0, 0xffffffff, 0, 0, 0 );
    g_pvCube[1] = D3DTLVERTEX( D3DVECTOR( 1,-1,-1 ), 0, 0xff00ffff, 0, 0, 0 );
    g_pvCube[2] = D3DTLVERTEX( D3DVECTOR(-1, 1,-1 ), 0, 0xffff00ff, 0, 0, 0 );
    g_pvCube[3] = D3DTLVERTEX( D3DVECTOR( 1, 1,-1 ), 0, 0xff0000ff, 0, 0, 0 );
    g_pvCube[4] = D3DTLVERTEX( D3DVECTOR(-1,-1, 1 ), 0, 0xffffff00, 0, 0, 0 );
    g_pvCube[5] = D3DTLVERTEX( D3DVECTOR( 1,-1, 1 ), 0, 0xff00ff00, 0, 0, 0 );
    g_pvCube[6] = D3DTLVERTEX( D3DVECTOR(-1, 1, 1 ), 0, 0xffff0000, 0, 0, 0 );
    g_pvCube[7] = D3DTLVERTEX( D3DVECTOR( 1, 1, 1 ), 0, 0xff000000, 0, 0, 0 );

次に、プログラマ定義関数 TransformVertices を呼び出して、立方体の 8 つの頂点を手動でトランスフォームする。

    TransformVertices( pd3dDevice, g_pvCube, 8 );

ただし、3D トランスフォームを実装する前に、ビューポートの高さと幅を取得する必要がある。この情報は、レンダリング ウィンドウに合わせてトランスフォーム済み頂点をスケーリングするために使用される。

HRESULT TransformVertices( LPDIRECT3DDEVICE7 pd3dDevice,
                           D3DTLVERTEX* pvVertices, DWORD dwNumVertices )
{
    // ビューポートの幅と高さを取得する。この情報は、レンダリング ウィンドウに合わせて
    // トランスフォーム済み頂点をスケーリングするのに必要である。
    D3DVIEWPORT7 vp;
    pd3dDevice->GetViewport( &vp );
    DWORD dwClipWidth  = vp.dwWidth/2;
    DWORD dwClipHeight = vp.dwHeight/2;

Direct3D は行列を使用してトランスフォームを行う。3D トランスフォームを実行するには、現在の行列セットの値を取得する必要がある。このためには、レンダリング デバイスで IDirect3DDevice7::GetTransform を呼び出す。

    D3DMATRIX matWorld, matView, matProj;
    pd3dDevice->GetTransform( D3DTRANSFORMSTATE_WORLD,      &matWorld );
    pd3dDevice->GetTransform( D3DTRANSFORMSTATE_VIEW,       &matView );
    pd3dDevice->GetTransform( D3DTRANSFORMSTATE_PROJECTION, &matProj );

行列連結には行列乗算を使用する。

    D3DMATRIX matTemp = matWorld * matView;
    D3DMATRIX matSet = matTemp * matProj;

上記のコードでは、トランスフォームの連結値が合成行列 matSet, から算出される。連結の際には、処理を行う順序で行列が乗算されていることを確認する。

行列連結の詳細については、「行列連結」を参照すること。

次に、現在の行列セットを使用して各頂点をトランスフォームする。

    for( DWORD i=0; i<dwNumVertices; i++ )
    {
        // 未トランスフォームの頂点の位置を取得する。
        FLOAT x = pvVertices[i].sx;
        FLOAT y = pvVertices[i].sy;
        FLOAT z = pvVertices[i].sz;

        // 現在の行列セットでトランスフォームする。
        FLOAT xp = matSet._11*x + matSet._21*y + matSet._31*z + matSet._41;
        FLOAT yp = matSet._12*x + matSet._22*y + matSet._32*z + matSet._42;
        FLOAT zp = matSet._13*x + matSet._23*y + matSet._33*z + matSet._43;
        FLOAT wp = matSet._14*x + matSet._24*y + matSet._34*z + matSet._44;

最後に、スクリーン座標に合わせて頂点をスケーリングする。次のコードでは、まず各座標が wp 値で除算されて、座標が 3D 空間から 2D デバイス座標に平面化される。その次に、x および y 成分がデバイス座標からスクリーン座標に変換される。

        pvVertices[i].sx  = ( 1.0f + (xp/wp) ) * dwClipWidth;
        pvVertices[i].sy  = ( 1.0f - (yp/wp) ) * dwClipHeight;
        pvVertices[i].sz  = zp / wp;
        pvVertices[i].rhw = wp;
    }

3D トランスフォームの詳細については、「3D トランスフォーム」を参照すること。

注 : ビューポートでデバイス座標がとる範囲は、-1 から +1 の間の値である。また、sz 座標が Z バッファで使用される。

これで立方体の 8 つの頂点をトランスフォームできた。次は、完成したシーンのフレームをレンダリングする。これについては、「ステップ 2.4 : シーンをレンダリングする」で説明する。


ステップ 3.3 : 座標トランスフォーム行列を準備、設定する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

単純なシーンをセット アップするもう 1 つのステップは、ワールド行列、ビュー行列、および射影行列の設定に関係するものである。システムによってこれらの行列がジオメトリに適用されることで、そのジオメトリがシーンに配置され、カメラの位置と向きが調整され、遠くにあるオブジェクトが近くにあるオブジェクトよりも小さく見えるように頂点データがスケーリングされる。(概要については、「ジオメトリ パイプライン」を参照すること)。

サンプル Triangle では、まず、D3DMATRIX 構造体で単位行列を作成した後、行列を操作し、目的の座標トランスフォームを生成する。行列を準備した後、このコードでは、D3DTRANSFORMSTATE_WORLD、D3DTRANSFORMSTATE_VIEW、または D3DTRANSFORMSTATE_PROJECTION 値を指定して IDirect3DDevice7::SetTransform メソッドを呼び出し、行列をデバイスに割り当てる。

    // まず、単位行列をセット アップする。
    D3DMATRIX mat;
    mat._11 = mat._22 = mat._33 = mat._44 = 1.0f;
    mat._12 = mat._13 = mat._14 = mat._41 = 0.0f;
    mat._21 = mat._23 = mat._24 = mat._42 = 0.0f;
    mat._31 = mat._32 = mat._34 = mat._43 = 0.0f;

    // ワールド行列は、ワールド空間にあるポリゴンの
    // 位置と向きを制御する。後でこれを使用して
    // 三角形を回転する。
    D3DMATRIX matWorld = mat;
    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD, &matWorld );

    // ビュー行列は、
    // カメラの位置と向きを定義する。ここでは、カメラを z 軸に沿って 10 単位後ろに
    // 動かすだけである。
    D3DMATRIX matView = mat;
    matView._43 = 10.0f;
    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_VIEW, &matView );

    // 射影行列は、2D レンダリング ターゲット サーフェス上に、
    // 3D シーンをどのように「射影」するかを定義する。
    // 詳細については、「射影トランスフォームとは」を参照すること。

    // x と y を 2 倍し、z を -1.0 だけ平行移動する、
    // 非常に単純な射影行列をセット アップする。
    D3DMATRIX matProj = mat;
    matProj._11 =  2.0f;
    matProj._22 =  2.0f;
    matProj._34 =  1.0f;
    matProj._43 = -1.0f;
    matProj._44 =  0.0f;
    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_PROJECTION, &matProj );

座標トランスフォームを設定すると、Triangle は、シーンのセット アップを終了したことになる。アプリケーション定義関数 App_InitDeviceObjects が、呼び出し側のアプリケーション定義関数 Initialize3DEnvironment に S_OK を返す。さらに、Initialize3DEnvironment 関数がこの値を WinMain に返す。これにより、WinMain は「ステップ 4 : システム メッセージを監視する」で説明するシステム メッセージの処理に移る。


ステップ 5.1 : シーンを更新する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

サンプル Triangle のアプリケーション定義関数 Render3DEnvironment は、呼び出されるとすぐに、App_FrameMove (別のアプリケーション定義関数) を呼び出す。App_FrameMove 関数は、fTimeKey パラメータにより関数に渡された内部カウント値に基づいて、y 軸を中心とする回転を反映させるため、Direct3D がジオメトリに適用するワールド行列を更新するだけである。回転は、1 フレームにつき一度だけ適用されるため、結果として、モデルが所定の位置で回転しているように見える。

HRESULT App_FrameMove( LPDIRECT3DDEVICE7 pd3dDevice, FLOAT fTimeKey )
{
    // この単純なチュートリアルでは、三角形を y 軸を中心として回転させる。
    // そのためには、新しいワールド座標トランスフォームとして、回転を決定する 4×4 行列を設定するだけである。
    D3DMATRIX matSpin;
    matSpin._11 = matSpin._22 = matSpin._33 = matSpin._44 = 1.0f;
    matSpin._12 = matSpin._13 = matSpin._14 = matSpin._41 = 0.0f;
    matSpin._21 = matSpin._23 = matSpin._24 = matSpin._42 = 0.0f;
    matSpin._31 = matSpin._32 = matSpin._34 = matSpin._43 = 0.0f;

    matSpin._11 = (FLOAT)cos( fTimeKey );
    matSpin._33 = (FLOAT)cos( fTimeKey );
    matSpin._13 = -(FLOAT)sin( fTimeKey );
    matSpin._31 = (FLOAT)sin( fTimeKey );

    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD, &matSpin );

    return S_OK;
}

もちろん、実際のアプリケーションでは、単一のモデルに対して回転を適用する以外にも多数の処理を行う。(回転行列の詳細については、「3D トランスフォーム」の「回転」を参照すること)。

シーンのジオメトリを更新したら、次はそのジオメトリをレンダリング ターゲット サーフェスにレンダリングする。サンプル Triangle では、この処理を「ステップ 5.2 : シーンをレンダリングする」で行う。


ステップ 2.1 : レンダリング ターゲットを取得する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

ここでは、デバイスのレンダリング ターゲットを取得する必要がある。これにより、そのレンダリング ターゲットを使用して DirectDraw オブジェクトへのポインタを取得できるようになる。次に、DirectDraw インターフェイスを取得しなければならない。これにより、サーフェスを作成できるようになる。

    LPDIRECTDRAWSURFACE7 pddsRender;
    LPDIRECTDRAW7        pDD;
    pd3dDevice->GetRenderTarget( &pddsRender );
    pddsRender->GetDDInterface( (VOID**)&pDD );
    pddsRender->Release();

上記のコードでは、IDirect3DDevice7::GetRenderTarget メソッドを使用して、レンダリング ターゲットとして使用する DirectDraw サーフェスへのポインタを取得している。次に、IDirectDrawSurface7::GetDDInterface メソッドを使用して、レンダリング ターゲット サーフェスの作成に使用した DirectDraw オブジェクトへのインターフェイスを取得している。

レンダリング ターゲットおよび DirectDraw インターフェイスへのポインタを取得したら、次はテクスチャにサーフェスを作成する。このタスクについては、「ステップ 2.2 : 新しいサーフェスを作成する」で説明する。


ステップ 2.2 : DirectDraw サーフェスをセットアップする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

DirectDraw オブジェクトを作成し、その協調レベルを設定すると、アプリケーションがシーンのレンダリング、表示に使用するサーフェスが作成できる。サーフェスの作成方法は、アプリケーションがウィンドウ内またはフルスクリーン モードのどちらで実行されるかによって、ほぼ決定される。

フルスクリーン アプリケーションについて : フルスクリーン モードで実行するアプリケーションでは、上記のコードで示すようにしてサーフェスを作成できる。フルスクリーン アプリケーションでは、フルスクリーン排他モードに限って使用できる機能であるページ フリッピングを利用することが頻繁に行われている。この場合、2 つのサーフェスを明示的に作成するのではなく、単一の呼び出しで、サーフェスのフリッピング チェーンを作成することができる。詳細については、「複合サーフェスとフリッピング チェーンの作成」を参照すること。

サンプル Triangle は、ウィンドウ内で実行されるように設計されており、ディスプレイを表すプライマリ サーフェスの作成から始まる。

    DDSURFACEDESC2 ddsd;
    ZeroMemory( &ddsd, sizeof(DDSURFACEDESC2) );
    ddsd.dwSize         = sizeof(DDSURFACEDESC2);
    ddsd.dwFlags        = DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;

    // プライマリ サーフェスを作成する。
    hr = g_pDD->CreateSurface( &ddsd, &g_pddsPrimary, NULL );
    if( FAILED( hr ) )
        return hr;

プライマリ サーフェス記述には、寸法やピクセル フォーマットの情報は含まれない。このような特徴は、ディスプレイ モードと同じであると見なされているからである。現在のディスプレイ モードが、800×600 の 16 ビット カラーであれば、DirectDraw は、プライマリ サーフェスも同じであることを保証する。プライマリ サーフェスを作成すると、レンダリング ターゲットのサーフェスを作成することが可能になる。Triangle の場合、これは次のようにして作成される、別のオフスクリーン サーフェスとなる。

    ddsd.dwFlags        = DDSD_WIDTH | DDSD_HEIGHT | DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN | DDSCAPS_3DDEVICE;

    // バック バッファのサイズを設定する。
    // ウィンドウのサイズが変わる場合は、このサーフェスを破棄し、新しいサーフェスを作成する必要がある。
    GetClientRect( hWnd, &g_rcScreenRect );
    GetClientRect( hWnd, &g_rcViewportRect );
    ClientToScreen( hWnd, (POINT*)&g_rcScreenRect.left );
    ClientToScreen( hWnd, (POINT*)&g_rcScreenRect.right );
    ddsd.dwWidth  = g_rcScreenRect.right - g_rcScreenRect.left;
    ddsd.dwHeight = g_rcScreenRect.bottom - g_rcScreenRect.top;

    // バックバッファを作成する。
    // 最も可能性のあるエラー原因は、ビデオ メモリの不足である (洗練されたアプリケーションなら、このエラーに対処するべきである)。
    hr = g_pDD->CreateSurface( &ddsd, &g_pddsBackBuffer, NULL );
    if( FAILED( hr ) )
        return hr;

上記のコードは、プログラム ウィンドウのサイズと等しいオフスクリーン サーフェスを作成する。ユーザーへの表示範囲はウィンドウのサイズによって決まるため、このサイズより大きなサーフェスを作成する必要はない。(このコードでは、後でビューポートの設定およびアプリケーション ウィンドウのサイズと位置の追跡に使用する 2 つのグローバル変数も初期化する)。上記のコードが示すように、レンダリング ターゲットとして使用するサーフェスには、DDSCAPS_3DDEVICE 能力を指定する必要がある。この能力によって、システムは、3D レンダリングのみに使用される追加の内部データ構造体を割り当てる。プライマリ サーフェスを作成する場合と同様に、オフスクリーン サーフェスのピクセル フォーマットは、サーフェス記述で指定されていなければ、ディスプレイ モードと同じとされる。

注 : 深度バッファを使用するアプリケーションでは、この時点で、1 つの深度バッファを作成して、レンダリング ターゲット サーフェスにアタッチする必要がある。このチュートリアルでは複雑になることを避けて深度バッファを使用していないが、「チュートリアル 2 : 深度バッファを追加する」および「深度バッファ」では使用する。

レンダリング ターゲットのプライマリ サーフェスを作成すると、DirectDrawClipper オブジェクトを作成して表示サーフェスにアタッチすることが可能になる。クリッパーを使用すると、ウィンドウが部分的にほかのウィンドウによって隠された場合や、ウィンドウが部分的に表示領域を越えた場合の処理をしなくて済む。クリッパーは、フルスクリーン モードで実行されるアプリケーションには必要ない。サンプル Triangle は、次のコードを使用してクリッパーを作成し、表示ウィンドウに結合している。

    LPDIRECTDRAWCLIPPER pcClipper;
    hr = g_pDD->CreateClipper( 0, &pcClipper, NULL );
    if( FAILED( hr ) )
        return hr;

    // ウィンドウ ハンドルにクリッパーを割り当てた後、
    // クリッパーを目的のサーフェスに設定する。
    pcClipper->SetHWnd( 0, hWnd );
    g_pddsPrimary->SetClipper( pcClipper );
    pcClipper->Release();

基本的な DirectDraw オブジェクトの作成を終了すると、シーンをレンダリングする Direct3D 主要オブジェクトの作成に進むことができる。サンプル Triangle では、このタスクを「ステップ 2.3 : Direct3D を初期化する」で行う。


ステップ 5.2 : シーンをレンダリングする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

目的の動きを反映するようにジオメトリの更新を終了すると、シーンのレンダリングを行うことができる。サンプル Triangle では、典型的な方法を採用している。サンプルの Render3DEnvironment 関数から呼び出されるアプリケーション定義関数 App_Render は、まず、ビューポートをクリアする。

HRESULT App_Render( LPDIRECT3DDEVICE7 pd3dDevice, D3DRECT* prcViewRect )
{
    // ビューポートを青色にクリアする。
    pd3dDevice->Clear( 1UL, prcViewRect, D3DCLEAR_TARGET, 0x000000ff,
                       0L, 0L );

上記のコードでは、IDirect3DDevice7::Clear メソッドを呼び出してビューポートをクリアしている。Clear メソッドが受け取る最初の 2 つの引数は、レンダリング ターゲット サーフェス上のクリア対象領域を記述する矩形の配列のアドレス、およびその配列からクリアする矩形の個数をメソッドに知らせる値である。通常、レンダリング ターゲット全体を覆う 1 つの矩形を使用する。3 番目のパラメータは、メソッドの動作を決定する。レンダリング ターゲット サーフェス、関連深度バッファ、ステンシル バッファ、またはこの 3 つの任意の組み合わせをクリアすることができる。このチュートリアルでは、深度バッファを使用しないので、D3DCLEAR_TARGET 以外のフラグは使用しない。最後の 3 つのパラメータは、レンダリング ターゲット、深度バッファ、ステンシル バッファのクリア値を反映するように設定する。サンプル Triangle では、レンダリング ターゲット サーフェスのクリアカラーを青に設定している。残りのパラメータは、このチュートリアルでは使用しないため、コードではゼロを設定している。Clear メソッドは、対応するフラグが存在しない場合はパラメータを無視する。

ビューポートをクリアした後、サンプル Triangle は次に示すように、レンダリングの開始を Direct3D に知らせ、シーンをレンダリングし、レンダリングの終了を知らせる。

    // シーンを開始する。
    if( FAILED( pd3dDevice->BeginScene() ) )
        return E_FAIL;

    // DrawPrimitive() コールを使用して、三角形を描画する。
    // チュートリアルでは、以降ポリゴンを描画するさまざまな呼び出しを
    // 詳しく紹介していく。
    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, D3DFVF_VERTEX,
                               g_pvTriangleVertices, 6, NULL );

    // シーンを終了する。
    pd3dDevice->EndScene();

    return S_OK;
}

IDirect3DDevice7::BeginScene および IDirect3DDevice7::EndScene メソッドは、レンダリングの開始時および終了時をそれぞれシステムに知らせる。レンダリング メソッドは、この 2 つのメソッドの呼び出しの間でしか呼び出すことができない。レンダリング メソッドが正常に終了しなかった場合でも、BeginScene を再度呼び出す前に、EndScene を呼び出す必要がある。

シーンをオフスクリーン レンダリング ターゲットにレンダリングすると、ユーザーのディスプレイを更新することが可能になる。チュートリアルのサンプルでは、この処理を「ステップ 5.3 : ディスプレイを更新する」で行う。


ステップ 2.2 : デバイスをテストする

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

次のコードは、すべての 8 ビット モードをスキップしながら、ディスプレイ モードのデバイスとの互換性をチェックする。

        if( (32==dwModeDepth) && (dwBitDepth&DDBD_32) ) bCompatible = TRUE;
        if( (24==dwModeDepth) && (dwBitDepth&DDBD_24) ) bCompatible = TRUE;
        if( (16==dwModeDepth) && (dwBitDepth&DDBD_16) ) bCompatible = TRUE;

特に上記のコードでは、指定されたデバイスのビデオ モードが、列挙されたデバイスのレンダリング深度と互換性を持つかどうかをチェックする。

デバイスに互換性があれば、そのデバイスは受け付けられ、デバイスでサポートされるディスプレイ モードの配列にコピーされる。

       if( bCompatible )
            pDeviceInfo->ddsdModes[pDeviceInfo->dwNumModes++] = ddsdMode;
    }

このループが終了してすべてのデバイスが列挙されると、ディスプレイ モードの配列 ddsdModes は指定条件を満たすディスプレイ モードのリストを格納し、その他のディスプレイ モードは無視される。


ステップ 1.1 : ドライバ情報を列挙する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

Enumeration アプリケーションでは、次のアプリケーション定義コールバック関数を使用して、システムにインストールされているすべての DirectDraw デバイスを列挙する。

static BOOL WINAPI DriverEnumCallback( GUID* pGUID, LPSTR strDesc,
                                       LPSTR strName, VOID*, HMONITOR )

第 1 パラメータ pGUID は、DirectDraw オブジェクトに固有の識別子のアドレスである。次の 2 つのパラメータは、ドライバの説明および名前を記述する文字列である。この関数の詳細については、SDK リファレンスの「DDEnumCallbackEx」の項目を参照すること。

ドライバ情報を列挙する前に、ディスプレイ ドライバを作成する必要がある。アプリケーション定義コールバック関数 DriverEnumCallback に渡されるグローバル ユニーク識別子 (GUID) を使用して、アプリケーションのディスプレイ ドライバを作成する。

hr = DirectDrawCreateEx( pGUID, (VOID**)&pDD, IID_IDirectDraw7, NULL );

引数 NULL は、アクティブなディスプレイ ドライバの使用を指定する。この時点で、Enumeration アプリケーションには、すべての Direct3D デバイスの列挙に使用される IDirect3D7 オブジェクトが作成される。

ドライバ データを D3DDEVICEINFO 構造体にコピーできる。これにより、ドライバ情報がユーザーのアプリケーション定義コールバック関数に渡される。

    // データをデータ情報構造体にコピーする。
    ZeroMemory( &d3dDeviceInfo, sizeof(D3DDEVICEINFO) );
    strncpy( d3dDeviceInfo.strDesc, strDesc, 39 );
    d3dDeviceInfo.ddDriverCaps.dwSize = sizeof(DDCAPS);
    d3dDeviceInfo.ddHELCaps.dwSize    = sizeof(DDCAPS);
    pDD->GetCaps( &d3dDeviceInfo.ddDriverCaps, &d3dDeviceInfo.ddHELCaps );
    d3dDeviceInfo.pDriverGUID = pGUID;

次のサンプル コードを調べて、D3DDEVICEINFO 構造体の ddsdModes メンバが、特定のデバイスでサポートされるディスプレイ モードを記述 (リスト) する DDSURFACEDESC2 型の配列であることに注目する。最終的には、コンボ ボックスをユーザーに表示し、現在のディスプレイ モード (ウィンドウ) のリストに続けて、デバイスでサポートされるフルスクリーン ディスプレイ モードのリストを表示できる。

注 : このチュートリアルでは、Enumeration アプリケーションのグラフィカル ユーザー インタフェース (GUI) の設計および構造については触れない。詳細については、SDK のコードを参照すること。

次のサンプル コードでは、現在のディスプレイ モード設定のディスプレイ モードに関する情報を取得する。

    if( ( NULL == d3dDeviceInfo.pDriverGUID ) &&
        ( d3dDeviceInfo.ddDriverCaps.dwCaps2 & DDCAPS2_CANRENDERWINDOWED ) )
    {
        // 現在のディスプレイ深度を取得する。
        DEVMODE devmode;
        devmode.dmSize = sizeof(DEVMODE);
        EnumDisplaySettings( NULL, ENUM_CURRENT_SETTINGS, &devmode );

        // モード情報を設定する。
        DDSURFACEDESC2* pMode = &d3dDeviceInfo.ddsdModes[0];
        pMode->ddpfPixelFormat.dwRGBBitCount = devmode.dmBitsPerPel;
        pMode->dwWidth  = 0;
        pMode->dwHeight = 0;

        d3dDeviceInfo.dwNumModes = 1;
    }

上記のサンプル コードは、ddsdModes 配列の要素に現在のディスプレイ設定を格納する方法を示している。ddsdModes 配列の残りの要素に値が格納されるのは、各デバイスにフルスクリーン ディスプレイ モードが列挙され、選択された後である。EnumDisplaySettings メソッドは、現在のディスプレイ深度に関する情報の取得に使用されることに注意する。深度設定は DEVMODE 構造体に保存された後、ddsdModes 配列の最初の要素である ddpfPixelFormat.dwRGBBitCount メンバにコピーされる。

        pMode->ddpfPixelFormat.dwRGBBitCount = devmode.dmBitsPerPel;

ここでは、システムの DirectDraw ドライバを列挙して、現在のディスプレイ設定を保存した。次は、ディスプレイ モードを列挙する。

ディスプレイ モードの列挙については、「ステップ 1.2 : ディスプレイ モード情報を列挙する」で詳しく説明する。


ステップ 2.1 : DirectDraw を初期化する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

アプリケーション ウィンドウの作成後、最初に作成するオブジェクトは、DirectDraw オブジェクトである。これは、アプリケーションの協調レベルを設定する場合や、表示やレンダリング デバイスのレンダリング ターゲットとして使用するサーフェスを作成する場合に必要となる。

サンプル Triangle は、次のコードに示すように、DirectDraw オブジェクトを作成し、アプリケーションの協調レベルを設定して、初期化の実行を開始する。

HRESULT Initialize3DEnvironment( HWND hWnd )
{
    HRESULT hr;

    hr = DirectDrawCreateEx( NULL, (VOID**)&g_pDD, IID_IDirectDraw7, NULL );
    if( FAILED( hr ) )
        return hr;

上記のコードでは、DirectDraw グローバル関数 DirectDrawCreateEx を呼び出して DirectDraw オブジェクトを作成している。最初のパラメータとして NULL を渡して、DirectDraw オブジェクトをアクティブなディスプレイ ドライバ用に作成するよう関数に要求する。3D 専用ハードウェアなどの、GDI をサポートしないハードウェアに対しては、最初のパラメータに、適切なドライバのグローバル ユニーク識別子 (GUID) を明示的に指定する必要がある。GUID は通常、列挙型から取得する。2 番目のパラメータはグローバル変数のアドレスで、DirectDrawCreateEx が DirectDraw オブジェクトに対する IDirectDraw7 インターフェイスのアドレスを設定する。最後のパラメータには NULL を設定して、新しいオブジェクトが COM 集約機能で使用されないことを示す。

サンプル コードは、引き続き、次のようにしてアプリケーションの協調レベルを設定する。

    hr = g_pDD->SetCooperativeLevel( hWnd, DDSCL_NORMAL );
    if( FAILED( hr ) )
        return hr;

サンプルでは、IDirectDraw7::SetCooperativeLevel メソッドを呼び出して協調レベルを設定している。協調レベルを設定することで、アプリケーションでレンダリングをフルスクリーン モードまたはウィンドウのどちらで実行するかがシステムに通知される。(ハードウェアによってはウィンドウにレンダリングできない場合がある。そのようなハードウェアは、IDirectDraw7::GetCaps を呼び出してチェックしてみると、DDCAPS2_CANRENDERWINDOWED 能力フラグが設定されていない)。このコードでは、SetCooperativeLevel に渡される DDSCL_NORMAL フラグを第 2 パラメータに設定して、"標準" 協調レベルとも呼ばれるウィンドウ協調レベルを要求している。SetCooperativeLevel メソッドは、別のアプリケーションが排他モードでフルスクリーンを既に制御している場合には失敗することがある。

注 : DDSCL_FPUSETUP 協調レベル フラグを指定すると、パフォーマンスが向上する。この協調フラグ レベルの詳細については、「DirectDraw 協調レベルと FPU 精度」を参照すること。一般的な説明については、DirectDraw の「協調レベル」を参照すること。

DirectDraw オブジェクトを作成し、協調レベルを設定すると、レンダリングされるシーンを含み、表示に使用するサーフェスの準備が可能な状態になる。サンプル Triangle では、このタスクを「ステップ 2.2 : DirectDraw サーフェスをセットアップする」で説明する方法によって行う。


ステップ 1.1 : 壁セグメントを準備する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

チュートリアル「さまざまなプリミティブ スタイルを使用する」では、「未トランスフォーム 未ライティングの頂点」である D3DVERTEX 構造体を使用してシーンの壁セグメントを記述する。「未トランスフォーム 未ライティングの頂点」を使用すると、Direct3D で独自の内部アルゴリズムによってトランスフォーム & ライティング処理を実行するように要求できる。

3D 空間で各壁セグメントを定義するには、次の DrawPrims アプリケーションのコードで示すように、1 組の頂点情報を計算して結果を保存する。

HRESULT App_InitDeviceObjects( LPDIRECT3DDEVICE7 pd3dDevice )
{
    DWORD i;

    for( i=0; i<NUM_WALL_SIDES; i++ )
    {
        FLOAT x = (FLOAT)sin( 2*g_PI*i/(NUM_WALL_SIDES-1) );
        FLOAT z = (FLOAT)cos( 2*g_PI*i/(NUM_WALL_SIDES-1) );

        g_pvWall[2*i+0] = D3DVERTEX( 10.0f * D3DVECTOR( x, -0.1f, z ),
                          D3DVECTOR( -x, 0, -z ), 0, 0 );
        g_pvWall[2*i+1] = D3DVERTEX( 10.0f * D3DVECTOR( x, 0.1f, z ),
                          D3DVECTOR( -x, 0, -z ), 0, 0 );

    }

上記のコードでは、D3DVERTEX 構造体の配列 g_pvWall に頂点成分データを格納している。また、三角関数を使用して頂点の x 座標および z 座標を決めている。D3DVERTEX 構造体では、モデル座標に座標を指定する必要がある。「未トランスフォーム 未ライティングの頂点」を使用しているため、モデル座標にはワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォームが適用されてシーン内に適切に配置される。また、頂点の x、y、および z 座標を 10 ずつスケーリングして壁セグメントを適切なサイズに設定する。

シーンの壁セグメントにジオメトリを定義した後、別のジオメトリ プリミティブである円錐を準備する。この場合も、特定のオブジェクトの定義順序は重要ではない。

3D 空間での円錐の定義については、「ステップ 1.2 : 円錐を準備する」で説明する。


ステップ 3.1 : ジオメトリを準備する

[Visual Basic]

ここでは、C および C++ でのアプリケーション開発について説明する。Visual Basic については、「Direct3D 直接モード Visual Basic チュートリアル」を参照すること。

[C++]

DirectDraw と Direct3D で使用するプライマリ システム オブジェクトを作成すると、シーンの初期化を開始できる。サンプル Triangle では、同時に、D3DVERTEX 構造体の配列で頂点を定義して、ジオメトリの初期化も行っている。技術的には、この時点でジオメトリのセット アップを行う必要はない。

HRESULT App_InitDeviceObjects( LPDIRECT3DDEVICE7 pd3dDevice )
{
    // 三角形のジオメトリのデータ。このチュートリアルでは、
    // アンビエント ライトだけを使用しているので、頂点の法線は、実際には使用されないことに注意する。
    D3DVECTOR p1( 0.0f, 3.0f, 0.0f );
    D3DVECTOR p2( 3.0f,-3.0f, 0.0f );
    D3DVECTOR p3(-3.0f,-3.0f, 0.0f );
    D3DVECTOR vNormal( 0.0f, 0.0f, 1.0f );

    // 三角形の前面の 3 頂点を初期化する。
    g_pvTriangleVertices[0] = D3DVERTEX( p1, vNormal, 0, 0 );
    g_pvTriangleVertices[1] = D3DVERTEX( p2, vNormal, 0, 0 );
    g_pvTriangleVertices[2] = D3DVERTEX( p3, vNormal, 0, 0 );

    // 三角形の背面の 3 頂点を初期化する。
    g_pvTriangleVertices[3] = D3DVERTEX( p1, -vNormal, 0, 0 );
    g_pvTriangleVertices[4] = D3DVERTEX( p3, -vNormal, 0, 0 );
    g_pvTriangleVertices[5] = D3DVERTEX( p2, -vNormal, 0, 0 );

上記の部分コードでは、z=0 の平面上に直立する三角形を定義する、3D 空間の 3 点を定義している。表示するジオメトリを定義した後、サンプル Triangle ではマテリアルおよびライティング パラメータを準備する。これについては、「ステップ 3.2 : マテリアルと初期ライティング ステートをセット アップする」で説明する。


ステップ 1.1 : テクスチャ座標を設定する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

Direct3D では、テクスチャをカラー値の 2 次元配列で表す。配列の各要素をテクセルと呼ぶ。テクセルには、列番号と行番号によってアクセスできる。これらの番号には、それぞれ U と V のラベルが付いている。

アプリケーションでテクスチャ座標を直接頂点に割り当てるには、DirectX7.CreateD3DVertex メソッドを使用する。サンプル Texture の次のコードでは、立方体の前面を表す 4 頂点を作成する。

g_dx.CreateD3DVertex -1, 1, -1, 0, 0, -1, 0, 0, vertices(0)
g_dx.CreateD3DVertex 1, 1, -1, 0, 0, -1, 1, 0, vertices(1)
g_dx.CreateD3DVertex -1, -1, -1, 0, 0, -1, 0, 1, vertices(2)
g_dx.CreateD3DVertex 1, -1, -1, 0, 0, -1, 1, 1, vertices(3)

CreateD3DVertex メソッドを呼び出すごとに、最初の 3 つの引数が頂点を、次の 3 つの引数が頂点法線ベクトルの方向を定義する。この場合、アプリケーションによってビットマップ テクスチャ全体を立方体の前面にマップし、次のテクスチャ座標、(0, 0)、(1, 0)、(0, 1)、および (1, 1) を使用する。

テクスチャ座標の詳細については、「テクスチャ座標」を参照すること。

立方体の背面、上面、底面、右面、および左面にも、同じ手順を実行する必要がある。この手順については、SDK のサンプル Texture コードを参照すること。

サンプル Texture では、プログラマ定義関数 CreateTextureSurface を使って DirectDrawSurface7 オブジェクトを返す。返されたテクスチャ サーフェス オブジェクトは、レンダリング時にプリミティブに設定される。

Set g_ddsTexture1 = CreateTextureSurface("tree1.bmp")
Set g_ddsTexture2 = CreateTextureSurface("tex1.bmp")
Set g_ddsTexture3 = CreateTextureSurface("earth.bmp")

上記のコードでは、ビットマップ ファイル (tree1.bmp、tex1.bmp、および earth.bmp) から 3 つのテクスチャ サーフェス オブジェクトが作成されている。

注 : サンプル Texture を実行するには、Visual Basic アプリケーションがテクスチャ ファイル (tree1.bmp、tex1.bmp、および earth.bmp) を検索できるようにしておかなければならない。サンプル Texture では、サンプル Texture のプロジェクト ファイル (.vbp) が登録されたフォルダでこれらのファイルを検索する。

これで、プログラマ定義サブルーチン CreateTextureSurface の説明は終了し、テクスチャ サーフェス オブジェクトの準備と作成に進む。このタスクの最初のステップが、ステップ 1.2 : テクスチャ サーフェスを準備する」である。


ステップ 3.3 : ジオメトリを準備する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

サンプル Triangle では、三角形を定義する 3 つの頂点と、3D 空間での頂点法線を定義する 1 つの点のベクトル型、合計 4 つの D3DVECTOR 型を定義することにより、アプリケーション定義サブルーチン InitGeometry でジオメトリを初期化する。技術的には、この時点でジオメトリのセット アップを行う必要はない。ジオメトリのセット アップは、レンダリング メソッドを呼び出す前に随時実行できる。

Private Sub InitGeometry()

' 三角形のジオメトリをセット アップする。
Dim p1 As D3DVECTOR, _
p2 As D3DVECTOR, _
p3 As D3DVECTOR, _
vNormal As D3DVECTOR

' 三角形を定義する 3 頂点の値を設定する.
p1.x = 0#:p1.y = 5#:p1.z = 0#
p2.x = 5#:p2.y = -5#:p2.z = 0#
p3.x = -5#:p3.y = -5#:p3.z = 0#

' 三角形の頂点で共有される頂点法線ベクトルを作成する。
' このベクトルは視点の方向を指す。このチュートリアルでは、
' 三角形の背面を定義する頂点法線の z 座標が
' 反転されているので注意する。
vNormal.x = 0#:vNormal.y = 0#:vNormal.z = -1#

DirectX7.CreateD3DVertex メソッドでは、D3DVECTOR 型のメンバを使って、各頂点成分を表す値を D3DVERTEX 型に埋め込む。グローバル D3DVERTEX 型配列 g_TriangleVert には、三角形の頂点情報を埋め込む。

' 三角形の前面の 3 頂点を作成する。
g_dx.CreateD3DVertex p1.x, p1.y, p1.z, vNormal.x, vNormal.y, vNormal.z, 0, 0, _
g_TriangleVert(0)
g_dx.CreateD3DVertex p2.x, p2.y, p2.z, vNormal.x, vNormal.y, vNormal.z, 0, 0, _
g_TriangleVert(1)
g_dx.CreateD3DVertex p3.x, p3.y, p3.z, vNormal.x, vNormal.y, vNormal.z, 0, 0, _
g_TriangleVert(2)

' 三角形の背面に対して同じ処理を実行する。
g_dx.CreateD3DVertex p3.x, p3.y, p3.z, vNormal.x, vNormal.y, -vNormal.z, 0, 0, _
g_TriangleVert(3)
g_dx.CreateD3DVertex p2.x, p2.y, p2.z, vNormal.x, vNormal.y, -vNormal.z, 0, 0, _
g_TriangleVert(4)
g_dx.CreateD3DVertex p1.x, p1.y, p1.z, vNormal.x, vNormal.y, -vNormal.z, 0, 0, _
g_TriangleVert(5)

上記の部分コードでは、z=0 の平面上に直立する三角形を定義する、3D 空間の 3点 を定義している。Direct3D 関連のオブジェクトをすべて作成し、シーンを初期化して、シーンのジオメトリを定義したら、「ステップ 4 : レンダリング ループを実行する」に示す手順でシーンをレンダリングできる。


ステップ 2.3 : シーンをレンダリングする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

次の Direct3DDevice7.DrawPrimitive 呼び出しによって、D3DVERTEX 型三角形ストリップで構成される壁セグメントを描画する。

Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX, g_vWall(0), _
NUM_WALL_VERTICES, D3DDP_DEFAULT)

次の DrawPrimitive 呼び出しによって、カスタム化した「柔軟な頂点フォーマット」の三角形ファンで円錐を描画する。

Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLEFAN, D3DFVF_XYZ Or D3DFVF_NORMAL, g_vCone(0), _
NUM_CONE_VERTICES, D3DDP_DEFAULT)

最後に、次の Direct3DDevice7.DrawIndexedPrimitive 呼び出しによって、アプリケーションでトランスフォーム & ライティング、およびインデックスを付けられた頂点から成る立方体を描画する。

Call g_d3dDevice.DrawIndexedPrimitive(D3DPT_TRIANGLELIST, D3DFVF_TLVERTEX, g_vCube(0), _
NUM_CUBE_VERTICES, g_nCubeIndices, NUM_CUBE_INDICES, D3DDP_DEFAULT)


ステップ 2.3 : Direct3D を初期化する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

アプリケーションがシーンのレンダリングと表示に必要とするサーフェスを作成すると、オブジェクトを作成して、Direct3D オブジェクトの初期化を開始することができる。このオブジェクトは、シーンのレンダリングに必要なすべてのオブジェクトを作成するために使用する。Direct3D7 オブジェクトは、DirectDraw7.GetDirect3D を呼び出して作成する。サンプル Triangle の次のコードが、このタスクを実行する。

Sub InitD3D()
Dim d3d As Direct3D7
Dim ddsd As DDSURFACEDESC2

' DirectDraw7 オブジェクトから
' Direct3D7 クラスへの参照を取得する。
Set d3d = g_dd.GetDirect3D

Direct3D7 オブジェクトを作成したら、レンダリング デバイスを作成して、Direct3D7.CreateDevice メソッドを呼び出す必要がある。CreateDevice メソッドは、目的のデバイスのグローバル ユニーク識別子 (GUID) と、デバイスがレンダリングする DirectDrawSurface7 オブジェクト、g_ddsBackBuffer を受け取る。このサーフェスは、DDSCAPS_3DDEVICE 能力を使って 3D デバイスとして作成しなければならない。

チュートリアルでは、GUID をコード中に書き込んで使用しているが、実際のアプリケーションでは、デバイスを列挙して GUID を取得する必要がある。デバイスの列挙については、「Direct3D デバイスの列挙」を参照すること。

(サンプル Triangle では、デバイスの作成前にディスプレイ モードをチェックしている。ディスプレイがパレット モードに設定されている場合、コードは終了する。関連するパレットを持たないパレット サーフェスを作成しようとすると、CreateDevice メソッドの失敗を引き起こすからである。これは、コードを簡単にするするためであり、実際のアプリケーションでは、レンダリング ターゲット サーフェスを作成し、パレットをアタッチするか、ディスプレイ モードを 16 ビット カラー以上に設定するようユーザーに要求する必要がある)。

サンプル Triangle の次のコードによって、ディスプレイ モードをチェックする。

g_dd.GetDisplayMode ddsd

If ddsd.ddpfPixelFormat.lRGBBitCount <= 8 Then
MsgBox "このアプリケーションでは、" & _
"16 ビット未満のスクリーン ディスプレイ モードをサポートしていない。"
End
End If

サンプル Triangle では次にレンダリング デバイスを作成する。

Set g_d3dDevice = d3d.CreateDevice("IID_IDirect3DHALDevice", g_ddsBackBuffer)

Direct3D7.CreateDevice の呼び出しが失敗する原因はさまざまである。最もよく見られる原因は、プライマリ ディスプレイ デバイスが 3D 機能をサポートしない場合である。ほかの可能性として、表示ハードウェアが、現在のディスプレイ モードではレンダリングができないという場合がある。これらの可能性をデバイス列挙の際にチェックしておく必要がある。コードを簡単にするため、サンプル Triangle では、ハードウェア デバイスが作成できない場合、ソフトウェア レンダリング デバイスの作成を試みることにしている。

注 : CreateDevice メソッドは DirectDrawSurface7 オブジェクトを受け付けるが、DirectDraw サーフェス オブジェクトとは別のデバイス オブジェクトを作成する。デバイスは、レンダリング ターゲットとして DirectDraw サーフェスを使用する。

デバイスを作成すると、「ステップ 2.4 : ビューポートを準備する」で説明するように、ビューポート オブジェクトを作成して、デバイスに割り当てることができるようになる。


ステップ 1.2 : テクスチャ サーフェスを準備する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

DDSURFACEDESC2 型を使って、テクスチャ サーフェスを記述することができる。

Public Function CreateTextureSurface(sFile As String) As DirectDrawSurface7
Dim ddsTexture As DirectDrawSurface7
Dim i As Long
Dim bIsFound As Boolean

' テクスチャ サーフェスを準備する。
Dim ddsd As DDSURFACEDESC2

ddsd.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH Or DDSD_PIXELFORMAT Or DDSD_TEXTURESTAGE

これで、テクスチャ サーフェスを準備できたので、テクスチャ フォーマットを列挙することができる。これについては、「ステップ 1.3 : テクスチャ フォーマットを列挙する」で説明する。


ステップ 4.3 : ディスプレイを更新する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

レンダリング ターゲット サーフェスに対するシーンのレンダリングを終了すると、その結果を画面上に表示することができる。ウィンドウ アプリケーションの場合、通常、レンダリング ターゲット サーフェスの内容をプライマリ サーフェスにブリットすることにより表示を行う。ページ フリッピングを使用するフルスクリーン アプリケーションの場合、フリッピング チェーンのサーフェスをフリップするだけで表示を行う。サンプル Triangle は、ウィンドウで実行されるため、次のコードにより、前者の方法を使用する。

g_dx.GetWindowRect Me.hWnd, g_rcDest

j = g_ddsPrimary.Blt(g_rcDest, g_ddsBackBuffer, g_rcSrc, DDBLT_WAIT)

上記の メソッドは、レンダリング ターゲット サーフェスの内容全体を、デスクトップのウィンドウにブリットするだけである。このチュートリアルでは、ブリット対象の矩形を、グローバル変数 g_rcDeｓt で追跡する。

アプリケーションの実行中、周期的に制御をオペレーティング システムに移行する必要がある。これについては、「ステップ 4.4 : DoEvents を呼び出す」で説明する。


ステップ 4.2 : シーンをレンダリングする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

目的の動きを反映するようにモデルのジオメトリを更新すると、シーンのレンダリングを行うことができる。サンプル Triangle では、典型的な方法を採用している。アプリケーション定義サブルーチン RenderScene は、まず、ビューポートをクリアする。

Private Sub RenderScene()
' ビューポートを青色にクリアする。
g_d3dDevice.Clear 1, g_d3drcViewport(), D3DCLEAR_TARGET, &HFF, 0, 0

上記のコードでは、Direct3DDevice7.Clear メソッドを呼び出して、ビューポートをクリアしている。Clear メソッドが受け付ける最初の 2 つの引数は、レンダリング ターゲット サーフェス上のクリア対象領域を記述する矩形の配列、および、その配列からいくつの矩形をクリアするかをメソッドに通知する値である。通常、サンプル Triangle で行っているように、レンダリング ターゲット全体を覆う 1 つの矩形を使用する。3 番目の引数は、メソッドの動作を決定する。Clear によって、レンダリング ターゲット サーフェス、関連深度バッファ、ステンシル バッファ、あるいはこの 3 つの任意の組み合わせをクリアすることができる。このチュートリアルでは、深度バッファを使用しないので、D3DCLEAR_TARGET 以外のフラグは使用しない。最後の 3 つのパラメータは、レンダリング ターゲット、深度バッファ、ステンシル バッファのクリア値を反映するように設定する。サンプル Triangle では、レンダリング ターゲット サーフェスのクリアカラーを青に設定している。残りのパラメータは、このチュートリアルでは使用しないため、コードではゼロに設定している。Clear メソッドは、対応するフラグが指定されていない場合、引数を無視する。

ビューポートをクリアした後、サンプル Triangle は次に示すように、レンダリングの開始を Direct3D に知らせ、シーンをレンダリングし、レンダリングの終了を知らせる。

' シーンを開始し、三角形をレンダリングして、シーンを終了する。
g_d3dDevice.BeginScene
Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLELIST, D3DFVF_VERTEX, _
g_TriangleVert(0), 6, D3DDP_DEFAULT)
g_d3dDevice.EndScene

Direct3DDevice7.BeginScene および Direct3DDevice7.EndScene メソッドは、それぞれ、レンダリングが始まること、または終了したことをシステムに通知する。レンダリング メソッドは、この 2 つのメソッドの呼び出しの間でしか呼び出すことができない。レンダリング メソッドが正常に終了しなかった場合でも、BeginScene を再度呼び出す前に、EndScene を呼び出す必要がある。

シーンをオフスクリーン レンダリング ターゲットにレンダリングすると、ユーザーのディスプレイを更新することが可能になる。サンプル Triangle では、これを「ステップ 4.3 : ディスプレイを更新する」で実行している。


ステップ 4.4 : DoEvents を呼び出す

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

DoEvents 関数を使用すると、アプリケーションに適用するイベントをオペレーティング システムが起動できる。この場合、オペレーティング システムがキューに入っているイベントを処理した後で、アプリケーションがシーンの各フレームをレンダリングする。サンプル Triangle では、次のコードを使ってイベント キューをクリアする。

DoEvents

この呼び出しが完了したら、アプリケーションはループの最初に戻り、アプリケーション定義サブルーチン RenderScene と FrameMove を呼び出して、単一フレームのシーンをレンダリングする。

これで、アプリケーションの実行が完了したので、このチュートリアルの最後のステップ、「ステップ 5 : シャット ダウンを行う」に進む。


ステップ 1.3 : デバイス情報を列挙する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

デバイスの列挙を開始する前に、現在のディスプレイ デバイスに対する Direct3D オブジェクトを取得する必要がある。

Set g_d3d = g_dd.GetDirect3D()

ここで、Direct3D7.GetDevicesEnum メソッドを呼び出すことにより、Direct3DEnumDevices クラスへの参照を取得する。

Set g_d3dEnumDevices = g_d3d.GetDevicesEnum()
For i = 1 To g_d3dEnumDevices.GetCount()
cmbDevice.AddItem g_d3dEnumDevices.GetName(i)
Next

上記のコードでは、列挙された各デバイスを示す分かりやすい名前を、コンボ ボックス cmbDevice に入れる。Direct3DEnumDevices クラスへの参照を取得したら、列挙されたデバイスの数と、各デバイスに関する情報を返すメソッドを呼び出すことができる。

Direct3DEnumDevices.GetCount メソッドを呼び出すと、列挙されたデバイスの数が返される。最初のデバイスはインデックス 1 であり、0 ではないので注意する。

Direct3DEnumDevices.GetGuid メソッドを呼び出すと、列挙されたデバイスのグローバル ユニーク識別子 (GUID) を表す文字列が返される。

Direct3DEnumDevices.GetName および Direct3DEnumDevices.GetDescription メソッドを呼び出すと、デバイスの名前とユーザーが入力した説明を含む文字列が返される。

Direct3DEnumDevices.GetDesc メソッドを呼び出すと、デバイスの能力の記述が、D3DDEVICEDESC7 型で返される。

ディスプレイ ドライバ、ディスプレイ モード、およびデバイスを列挙したら、アプリケーションで使用するデバイスを選択することができる。これが、「ステップ 2 : 列挙されたデバイスの選択」の説明内容である。


ステップ 2.1 : シーンを更新する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、アプリケーション定義サブルーチン FrameMove を使って、円を中心に視点を回転する。通常、次のコードに示すように、視点は 3 つの D3DVECTOR 型、視点、注視点、および正方向を定義するベクトルによって定義される。

Dim vEyePt As D3DVECTOR, _
vLookatPt As D3DVECTOR, _
vUpVec As D3DVECTOR

vEyePt = MakeVector(5 * Sin(stepVal), 3, 5 * Cos(stepVal))
vLookatPt = MakeVector(4 * Sin(stepVal + 0.1), 2.5, 4 * Cos(stepVal + 0.1))
vUpVec = MakeVector(0, 1, 0)

ここで、3 つのベクトルを使って、新しいビュー行列を作成して設定することができる。

Dim matView As D3DMATRIX

Call g_dx.ViewMatrix(matView, vEyePt, vLookatPt, vUpVec, stepVal / 360)

g_d3dDevice.SetTransform D3DTRANSFORMSTATE_VIEW, matView

上記のコードでは、新しいカメラ位置を DirectX7.ViewMatrix メソッドに渡すことによって、レンダリングされたシーンのフレームごとに新しいビュー行列を作成する。次に、Direct3DDevice7.SetTransform メソッドが、デバイスに新しく生成されたビュー行列を設定する。stepValue の値 (アプリケーション定義メソッド FrameMove に渡された値) によって、視点を 1 度ずつ回転する。これにより、壁セグメントと円錐が 360 度回転したように見える。

これで、シーンはほぼ完成であるが、さらに、立方体の頂点を手動で回転、平行移動、スケールする必要がある。最初に、DirectX7.CreateD3DTLVertex メソッドを使って、D3DTLVERTEX 型に立方体の未トランスフォーム データを埋め込む。DirectX7.CreateD3DTLVertex の最初の 3 つのパラメータは、各頂点の未トランスフォーム位置座標をスクリーン座標で表す。

g_dx.CreateD3DTLVertex -1, -1, -1, 0, &HFFFFFF, 0, 0, 0, g_vCube(0)
g_dx.CreateD3DTLVertex 1, -1, -1, 0, &HFF&, 0, 0, 0, g_vCube(1)
g_dx.CreateD3DTLVertex -1, 1, -1, 0, &HFF00&, 0, 0, 0, g_vCube(2)
g_dx.CreateD3DTLVertex 1, 1, -1, 0, &HFF0000, 0, 0, 0, g_vCube(3)
g_dx.CreateD3DTLVertex -1, -1, 1, 0, &HFFFF&, 0, 0, 0, g_vCube(4)
g_dx.CreateD3DTLVertex 1, -1, 1, 0, &HFF0066, 0, 0, 0, g_vCube(5)
g_dx.CreateD3DTLVertex -1, 1, 1, 0, &H9966FF, 0, 0, 0, g_vCube(6)
g_dx.CreateD3DTLVertex 1, 1, 1, 0, &HFF00FF, 0, 0, 0, g_vCube(7)

ここで、立方体の 8 つの頂点をトランスフォームできる。

Call TransformVertices(g_d3dDevice, g_vCube, NUM_CUBE_VERTICES)

立方体の頂点は、アプリケーション定義関数 TransformVertices によってトランスフォームされる。このトランスフォームについては、「ステップ 2.2 : 3D トランスフォームを実行する」で説明する。


ステップ 1.4 : テクスチャに新規サーフェスを作成する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

テクスチャ サーフェス オブジェクトを作成する前に、DDSCAPS2_TEXTUREMANAGE フラグを使ってデバイスのテクスチャ管理をオンにする必要がある。

ddsd.ddsCaps.lCaps = DDSCAPS_TEXTURE
ddsd.ddsCaps.lCaps2 = DDSCAPS2_TEXTUREMANAGE
ddsd.lTextureStage = 0

また、制御フラグ DDSCAPS_TEXTURE をセットして、テクスチャ サーフェスであることをシステムに通知する。

テクスチャの管理については、「自動テクスチャ管理」を参照すること。

これで、自動テクスチャ管理が有効になり、DDSCAPS_TEXTURE フラグがセットされたので、テクスチャに新しいサーフェスを作成して、そのテクスチャを返すことができる。

Set ddsTexture = g_dd.CreateSurfaceFromFile(sFile, ddsd)

' 新しく作成されたテクスチャを返す。
Set CreateTextureSurface = ddsTexture

テクスチャ サーフェスについては、「テクスチャ サーフェス オブジェクト」を参照すること。

これで、テクスチャに新しいサーフェスを作成したので、プリミティブのレンダリング時にそのテクスチャを使用することができる。この処理を、「ステップ 2 : テクスチャを適用したプリミティブをレンダリングする」で実行する。


ステップ 2.1 : DirectDraw を初期化する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

アプリケーション ウィンドウの作成後、最初に作成するオブジェクトは、DirectDraw オブジェクトである。これは、アプリケーションの協調レベルの設定に必要である。また、この DirectDraw オブジェクトを使って、シーンの表示や、アプリケーションのレンダリング デバイスのレンダリング ターゲットとして使用するサーフェスを作成する。

サンプル Triangle は、次のコードに示すように、DirectDraw オブジェクトを作成して初期化の実行を開始する。

Private Sub InitDDraw()
' DirectDraw オブジェクトを作成してアプリケーションを設定する。
' 協調レベル。
Set g_dd = g_dx.DirectDrawCreate("")

上記のコードは、DirectDraw グローバル関数 DirectDrawCreate を呼び出して、DirectDraw オブジェクトを作成する。空の文字列を渡して、DirectDraw オブジェクトをアクティブなディスプレイ ドライバ用に作成するよう関数に要求する。3D 専用ハードウェアなどの、GDI をサポートしないハードウェアに対しては、適切なドライバのグローバル ユニーク識別子 (GUID) を明示的に指定する必要がある。

サンプル Triangle は、DirectDraw7.SetCooperativeLevel メソッドを呼び出して、協調レベルを設定する。協調レベルの設定により、アプリケーションが、フルスクリーン モードまたは標準ウィンドウ内のどちらでレンダリングするかをシステムに指示する (ウィンドウ内にレンダリングできないハードウェアも存在することに注意する。そうしたハードウェアは、DirectDraw7.GetCaps を呼び出して、DDCAP2_CANRENDERWINDOWED 能力フラグが存在しないことをチェックして、検出することができる)。上記のコードは、2 番目のパラメータに DDSCL_NORMAL フラグを指定し、SetCooperativeLevel に渡して、「標準」協調レベルともいわれるウィンドウ協調レベルを要求している。SetCooperativeLevel メソッドは、別のアプリケーションが排他モードで全画面を既に制御している場合には失敗することがある。

次のコードは、アプリケーションの協調レベルの設定方法を示す。

g_dd.SetCooperativeLevel Me.hWnd, DDSCL_NORMAL

DirectDraw オブジェクトを作成し、協調レベルを設定すると、レンダリングされるシーンを含み、表示に使用するサーフェスの準備が可能な状態になる。サンプル Triangle では、この準備を、「ステップ 2.2 : DirectDraw サーフェスをセット アップする」で行う。


ステップ 1.1 : 壁セグメントを準備する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、D3DVERTEX 型のシーンにおける壁セグメントについて説明する。この頂点は、「未トランスフォーム 未ライティングの頂点」である。「未トランスフォーム 未ライティングの頂点」を使用すると、Direct3D が独自の内部アルゴリズムを使ってトランスフォーム & ライティング処理を実行するように要求することができる。

3D 空間で壁セグメントを定義するには、サンプル DrawPrims の以下のコードに示す方法で、頂点の情報を計算して保存する。

Private Sub InitGeometry()

' 壁ジオメトリをセット アップする
Dim x As Double, _
y As Double, _
z As Double

Dim i As Integer

For i = 0 To NUM_WALL_SIDES - 1
x = Sin(2 * pi * i / (NUM_WALL_SIDES - 1))
z = Cos(2 * pi * i / (NUM_WALL_SIDES - 1))

Call g_dx.CreateD3DVertex(x * 10#, -0.1 * 10#, z * 10#, -x, 0, -z, 0, 0, g_vWall(2 * i + 0))
Call g_dx.CreateD3DVertex(x * 10#, 0.1 * 10#, z * 10#, -x, 0, -z, 0, 0, g_vWall(2 * i + 1))

Next i

上記のコードでは、DirectX7.CreateD3DVertex メソッドを使って、D3DVERTEX 型の配列 g_vWall に頂点成分情報を埋め込む。このコードでは、三角関数を使って頂点の ｘ 座標と ｚ 座標を決める。CreateD3DVertex メソッドを使用する場合、モデル座標で座標を指定する必要がある。「未トランスフォーム 未ライティングの頂点」を使用するので、システムはモデル座標にワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォームを適用し、シーン内の適切な位置に配置する。また、頂点の x、y、および z 座標を 10 でスケールして、壁セグメントを適切なサイズにする。

シーン内の壁セグメントのジオメトリを定義したら、その他のジオメトリ プリミティブの準備に進むことができる。オブジェクトを定義する順序を意識する必要はない。

3D 空間での円錐の定義については、「ステップ 1.2 : 円錐を準備する」で説明する。


ステップ 1.1 : ドライバ情報を列挙する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

グローバル オブジェクト DirectX7 で DirectX7.DirectDrawCreate を呼び出すことにより、アプリケーションのディスプレイ ドライバを作成する。

Set g_dd = g_dx.DirectDrawCreate("")

これで、ドライバ情報を取得することができる。このチュートリアルでは、プライマリ ディスプレイ ドライバだけを使用する。

Set g_ddEnum = g_dx.GetDDEnum()

For i = 1 To g_ddEnum.GetCount()
g_sDriverGUID = g_ddEnum.GetDescription(i)
Next I

上記のコードでは、DirectX7.GetDDEnum メソッドを使って DirectDrawEnum オブジェクトを作成する。次に、DirectDrawEnum オブジェクト g_ddEnum を使って、システムにインストールされているビデオ ドライバ ディスプレイ アダプタを列挙する。プライマリ ディスプレイ ドライバが検出されたら、DirectDrawEnum.GetDescription を使って、指定されたDirectDraw デバイスのドライバ記述を返す。

サンプル Enumeration では、次のアプリケーション定義サブルーチン呼び出しを使って、ディスプレイ モード列挙を実行する。

' ディスプレイ モードを列挙する。
EnumModes

ディスプレイ モード列挙の詳細については、ステップ 1.2 : ディスプレイ モード情報を列挙する」で説明する。


ステップ 3.1 : マテリアルと初期ライティング ステートをセット アップする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

基本的な 3D レンダリング オブジェクト (DirectDraw オブジェクト、レンダリング デバイス、およびビューポート) を作成すると、単純なシーンをレンダリングするのに必要なすべてのものが、ほぼ揃ったことになる。次にすることは、初期ライティング ステートを設定し、マテリアルを作成および構成することである。設定はすべて、必要に応じて、後で変更することができる。概念的な説明については、「ライティングとマテリアル」を参照すること。

次のコードは、Direct3DDevice7.SetRenderState メソッドを呼び出して、初期ライティング ステートをレンダリング デバイス g_d3dDevice に適用する。

g_d3dDevice.SetRenderState D3DRENDERSTATE_AMBIENT, _
g_dx.CreateColorRGBA(1#, 1#, 1#, 1#)

最初のパラメータ、SetRenderState は、D3DRENDERSTATE_AMBIENT フラグを渡し、この呼び出しをシーンのアンビエント ライトの色設定と関連付ける。2 番目の引数では、DirectX7.CreateColorRGBA メソッドを使用して、アンビエント ライトの赤、緑、青のカラー値を、それぞれ 1.0 に設定する。この結果得られたライティングは、白色光を放射する。ライティングではアルファ成分を使用しない。上記のコードでは、アルファ値も 1.0 に設定されている。

D3DMATERIAL7 型を使って、マテリアルのプロパティを指定する。

Dim mtrl As D3DMATERIAL7

mtrl.Ambient.r = 1#:mtrl.Ambient.g = 1#:mtrl.Ambient.b = 0#

' マテリアルをデバイスにコミットする。
g_d3dDevice.SetMaterial mtrl

作成された新しいマテリアルにはプロパティがないので、レンダリングには使用できない。上記のコードでは、アンビエント ライトの赤と緑の要素を反射するマテリアルを記述し、シーン内ではそのマテリアルを黄色で表す D3DMATERIAL7 型のマテリアル プロパティを設定している (サンプル Triangle では、アンビエント ライトだけを使用するので、アンビエント反射率プロパティだけを設定する。実際のアプリケーションでは、アンビエント ライトだけでなくダイレクト ライトも使用するので、ディフューズおよびスペキュラ反射率のプロパティも設定する必要がある)。

注 : テクスチャを使用する場合、オブジェクト マテリアルは通常省略されるか白色にされる。

ここで、マテリアル、および初期ライティング パラメータが設定されたので、サンプル Triangle は、座標トランスフォーム行列のセット アップに進む。これについては、「ステップ 3.2 : 座標トランスフォーム行列を準備、設定する」で説明する。


ステップ 2.1 : デバイスを取得する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

デバイスをテストする前に、テストするデバイスを取得しなければならない。以下のトピックでは、現在のディスプレイ設定と、デバイス参照を取得する方法について説明する。これにより、そのデバイスでサポートされているすべてのディスプレイ設定でデバイスをテストすることができる。

サンプル Enumeration では、DirectDraw7.GetDisplayMode メソッドを使って、現在のディスプレイ モード情報を DDSURFACEDESC2 型で取得する。

g_dd.GetDisplayMode desc
currMode = desc.ddpfPixelFormat.lRGBBitCount

上記のコードでは、現在のディスプレイのビット/ピクセル設定を currMode に保存する。次に、現在のディスプレイ モードをコンボ ボックス cmbMode に追加する。このボックスの内容がユーザーに表示される。

cmbMode.Clear
cmbMode.AddItem Str(currMode) + "- ビット ディスプレイ ウィンドウ"

ここで、テストするデバイスを取得するには、Direct3DEnumDevices.GetDesc メソッドを使って、コンボ ボックス cmbDevice でユーザーが選択しているデバイスを確認する。

Call g_d3dEnumDevices.GetDesc(cmbDevice.ListIndex + 1, deviceDesc)

上記のコードでは、DDSURFACEDESC2 型 deviceDesc を使って、テストするデバイスのサーフェス記述情報を保持する。このデバイスでサポートされるディスプレイ モードのリストが作成される。最終的には、これらのサポートされるディスプレイ モードがコンボ ボックスに表示されるので、ユーザーがサンプル Enumeration でディスプレイ モードを選択することができる。

注 : このチュートリアルでは、サンプル Enumeration のグラフィカル ユーザー インターフェイス (GUI) の設計と構造については取り上げない。このチュートリアルのサンプル コードと GUI の関係については、SDK に含まれるサンプル Enumeration 全体のコードを参照すること。

これで、テストするデバイスへの参照を取得したので、デバイスをテストすることができる。デバイスのテストについては、「ステップ 2.2 : デバイスをテストする」で説明する。


ステップ 3.2 : 座標トランスフォーム行列を準備、設定する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

単純なシーンをセット アップするもう 1 つのステップは、ワールド行列、ビュー行列、および射影行列の設定に関係するものである。システムは、モデルをシーンの中に置くため、カメラの位置と向きを調節するため、および頂点データをスケールして遠くのオブジェクトを近くのオブジェクトよりも小さく見せるために、行列をモデルのジオメトリに適用する (概念的な概要については、「ジオメトリ パイプライン」を参照すること)。

ワールド行列を作成するには、D3DMATRIX 型 matWorld を宣言し、それから単位行列を作成する。次に、D3DTRANSFORMSTATE_WORLD フラグがセットされた Direct3DDevice7.SetTransform メソッドを使って、ワールド ビューの行列を定義する。

' ワールド行列は、ワールド空間にあるポリゴンの位置と向きを制御する。
' 後で、三角形を回転させるために使用する。
Dim matWorld As D3DMATRIX

g_dx.IdentityMatrix matWorld
g_d3dDevice.SetTransform D3DTRANSFORMSTATE_WORLD, matWorld

ビュー行列を作成するには、D3DMATRIX 型 matView を宣言し、それから単位行列を作成する。次に、カメラ座標を DirectX7.ViewMatrix メソッドに渡し、ビュー行列を作成する。レンダリング デバイスのビュー行列を定義するには、SetTransform メソッドを使用する。

' ビュー行列は、カメラの位置と向きを定義する。
' ここでは、カメラを z 軸に沿って 15 単位後ろに動かすだけである。
Dim matView  As D3DMATRIX

g_dx.IdentityMatrix matView

Call g_dx.ViewMatrix(matView, MakeVector(0, 0, -15), MakeVector(0, 0, 0), _
MakeVector(0, 1, 0), 0)

g_d3dDevice.SetTransform D3DTRANSFORMSTATE_VIEW, matView

上記のコードでは、プライベートのアプリケーション定義関数 MakeVector を使って、3 頂点を D3DVECTOR 型にトランスフォームする。

Private Function MakeVector(a As Double, b As Double, c As Double) As D3DVECTOR
Dim vecOut As D3DVECTOR

With vecOut
.x = a
.y = b
.z = c
End With

MakeVector = vecOut
End Function

射影行列を作成するには、D3DMATRIX 型 matProj を宣言し、それから単位行列を作成する。次に、クリップ面と視野角度を DirectX7.ProjectionMatrix メソッドに渡して、射影行列を作成する。レンダリング デバイスの射影行列を定義するには、SetTransform メソッドを使用する。

' 射影行列は、2D レンダリング ターゲット サーフェス (バックバッファ サーフェス) 上に、
' 3D シーンをどのように「射影」するかを定義する。詳細については、
' 射影行列の説明を参照すること。
Dim matProj As D3DMATRIX

g_dx.IdentityMatrix matProj

Call g_dx.ProjectionMatrix(matProj, 1, 1000, pi / 2)
g_d3dDevice.SetTransform D3DTRANSFORMSTATE_PROJECTION, matProj

上記のコードでは、ProjectionMatrix に渡される 2 番目のパラメータが前方クリッピング平面までの距離を、3 番目のパラメータが後方クリッピング平面までの距離を、アプリケーション指定の単位で示す。4 番目のパラメータは、視野角度をラジアンで表す。

マテリアルの準備とトランスフォーム行列の設定が完了したら、シーンのジオメトリをセット アップすることができる。これについては、「ステップ 3.3 : ジオメトリを準備する」で説明する。


ステップ 4.1 : シーンを更新する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

シーンはレンダリングする前に更新しなければならない。RenderScene は、呼び出されるとすぐに、FrameMove (別のアプリケーション定義サブルーチン) を呼び出す。FrameMove は、Direct3D がモデルのジオメトリに適用するワールド行列を更新するだけである。アプリケーションは、stepValue パラメータにより FrameMove に渡された内部カウント値に基づいて、ｙ 軸を中心とする回転を反映させる。回転は、1 フレームにつき 1 度だけ適用されるため、結果として、モデルが所定の位置で回転しているように見える。

Private Sub FrameMove(stepVal As Single)
Dim matSpinY As D3DMATRIX

Call g_dx.RotateYMatrix(matSpinY, stepVal)
Call g_d3dDevice.SetTransform(D3DTRANSFORMSTATE_WORLD, matSpinY)
End Sub

もちろん、現実には、アプリケーションは単一のモデルに単一の回転を適用するだけでなく、さまざまなことを行う (回転行列の詳細については、「3D トランスフォーム」の「回転」を参照すること)。

シーン内のモデルのジオメトリを更新すると、「ステップ 4.2 : シーンをレンダリングする」でサンプル Triangle が行っているように、レンダリング ターゲット サーフェスにジオメトリをレンダリングすることができる。


ステップ 1.2 : ディスプレイ モード情報を列挙する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectDraw7.GetDisplayModesEnum メソッドを使って、DirectDrawEnumModes クラスへの参照を返すことができる。取得されたディスプレイ モード情報は、DDSURFACEDESC2 型 g_enumInfo: に保存される。

Set g_ddEnumModes = g_dd.GetDisplayModesEnum(DDEDM_DEFAULT, g_enumInfo)

上記のコードでは、DDEDM_DEFAULT フラグによって、ディスプレイ モードの標準列挙を実行するようアプリケーションに指示する。使用可能なオプションについては、SDK リファレンスの「CONST_DDEDMFLAGS」のトピックを参照すること。これで、DirectDraw ドライバとディスプレイ モードが列挙されたので、デバイスの列挙に進むことができる。サンプル Enumeration では、次のアプリケーション定義サブルーチンを使ってデバイスを列挙する。

' デバイスを列挙する。
EnumDevices

デバイスの列挙については、「ステップ 1.3 :デバイス情報を列挙する」で説明する。


ステップ 1.3 : テクスチャ フォーマットを列挙する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

テクスチャを列挙する前に、Direct3DEnumPixelFormats オブジェクトを宣言する必要がある。

Dim TextureEnum As Direct3DEnumPixelFormats

次に、レンダリング デバイスで Direct3DDevice7.GetTextureFormatsEnum メソッドを呼び出して、Direct3DEnumPixelFormats オブジェクトを返す。

Set TextureEnum = g_d3dDevice.GetTextureFormatsEnum()

これで、Direct3DEnumPixelFormats オブジェクト、TextureEnum でメソッドを呼び出し、デバイスがそのテクスチャでサポートするピクセル フォーマット情報を取得できる。

サンプル Texture の以下のコードでは、デバイスがサポートするテクスチャ ピクセル フォーマットをループによって検索する。このコードでは、16 ビット テクスチャを検索している。アルファ テクスチャなど、その他のフォーマットはすべて無視されるので注意する。

For i = 1 To TextureEnum.GetCount()
bIsFound = True
Call TextureEnum.GetItem(i, ddsd.ddpfPixelFormat)

With ddsd.ddpfPixelFormat
' 未知のモードはスキップする。
If .lFlags And (DDPF_LUMINANCE Or DDPF_BUMPLUMINANCE Or DDPF_BUMPDUDV) Then bIsFound = False

' FourCC フォーマットはすべてスキップする。
If .lFourCC <> 0 Then bIsFound = False

' アルファ モードはスキップする。
If .lFlags And DDPF_ALPHAPIXELS Then bIsFound = False

' 16 ビット モード以外のモードはすべてスキップする。
If .lRGBBitCount <> 16 Then bIsFound = False
End With

If bIsFound Then Exit For

Next i

これで、列挙されたテクスチャ フォーマット TextureEnum から、レンダリング デバイスでサポートされるテクスチャ フォーマットが選択されたので、そのテクスチャにサーフェスを作成することができる。これについては、「ステップ 1.4 : テクスチャに新規サーフェスを作成する」で説明する。


ステップ 1.3 : 立方体を準備する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

立方体は、インデックス付きプリミティブで表される。すなわち、頂点の配列にインデックスを付けることによって定義される。レンダリング時に立方体の頂点リストにインデックスを付けるには、次のインデックスを使用する。

g_nCubeIndices(0) = 1:g_nCubeIndices(1) = 2:g_nCubeIndices(2) = 3
g_nCubeIndices(3) = 2:g_nCubeIndices(4) = 1:g_nCubeIndices(5) = 0
g_nCubeIndices(6) = 4:g_nCubeIndices(7) = 5:g_nCubeIndices(8) = 6
g_nCubeIndices(9) = 6:g_nCubeIndices(10) = 5:g_nCubeIndices(11) = 7
g_nCubeIndices(12) = 3:g_nCubeIndices(13) = 2:g_nCubeIndices(14) = 6
g_nCubeIndices(15) = 3:g_nCubeIndices(16) = 6:g_nCubeIndices(17) = 7
g_nCubeIndices(18) = 0:g_nCubeIndices(19) = 1:g_nCubeIndices(20) = 4
g_nCubeIndices(21) = 4:g_nCubeIndices(22) = 1:g_nCubeIndices(23) = 5
g_nCubeIndices(24) = 2:g_nCubeIndices(25) = 0:g_nCubeIndices(26) = 4
g_nCubeIndices(27) = 2:g_nCubeIndices(28) = 4:g_nCubeIndices(29) = 6
g_nCubeIndices(30) = 1:g_nCubeIndices(31) = 3:g_nCubeIndices(32) = 5
g_nCubeIndices(33) = 5:g_nCubeIndices(34) = 3:g_nCubeIndices(35) = 7

シーン内のすべてのオブジェクトのジオメトリを定義したら、シーンをレンダリングして表示することができる。これが、「ステップ 2 : シーンをレンダリング、表示する」の説明内容である。


ステップ 2.4 : ビューポートを準備する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

レンダリング デバイスを作成すると、ビューポート オブジェクトを作成し、デバイスに割り当てることが可能になる。簡単に言うと、ビューポートとは、3D シーンにおけるジオメトリをクリップして、2D の表示画面空間に表現する方法を決定するものである。ビューポートの概念的な概要については、「ビューポートとクリッピング」を参照すること。

ビューポートのセット アップは単純明解なプロセスであり、D3DVIEWPORT7 型のビューポート パラメータを準備することから始まる。サンプル Triangle では、シーンがレンダリングされる最小深度と最大深度、つまり 0、0 から 1、0 の標準範囲にあるレンダリング ターゲット サーフェスの寸法を、ビューポートのパラメータに設定している。

Dim VPDesc As D3DVIEWPORT7

VPDesc.lWidth = g_rcDest.Right - g_rcDest.Left
VPDesc.lHeight = g_rcDest.Bottom - g_rcDest.Top
VPDesc.minz = 0#
VPDesc.maxz = 1#

ビューポート パラメータ型の準備が終了すると、Triangle はレンダリング デバイスのビューポート パラメータを設定する。

g_d3dDevice.SetViewport VPDesc

ここで、ビューポート パラメータを RECT 型のキャッシュに入れる。この値は、後で処理をクリアする際に使用する。

With g_d3drcViewport(0)
.X1 = 0:.Y1 = 0
.X2 = VPDesc.lWidth
.Y2 = VPDesc.lHeight
End With

ここで、基本的な DirectX オブジェクトの作成が終了したので、シーンのレンダリングに必要な従属オブジェクトの準備を始めることができる。これが、「ステップ 3 : シーンを初期化する」の説明内容である。


ステップ 2.2 : デバイスをテストする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

次のコードは、デバイスの能力を確認する方法を示す。サンプル Enumeration では、次のアルゴリズムを使って、指定されたデバイスでサポートされるディスプレイ モードを選択する。

  1. DirectDrawEnumModes オブジェクトで指定された要素のビデオ モード記述を返す。
  2. 返されたビデオ モード記述から、サポートされるビット/ピクセルを取得する。
  3. 指定されたデバイスのレンダリング深度を取得する。
  4. DirectDrawEnumModes オブジェクトで指定された要素のビデオ モードが、取得されたデバイスのレンダリング深度と互換性があるかどうかをチェックする。互換性がある場合はそのディスプレイ モードを受け取り、ない場合は拒否する。8 ビット モードはすべてスキップする。

サンプル Enumeration では、次のコードを実行してこのアルゴリズムを実装する。

For j = 1 To g_ddEnumModes.GetCount()
' このディスプレイ モードはテストされていないので、互換性がないものと見なす。
bCompatible = False
' ステップ 1:
g_ddEnumModes.GetItem j, g_enumInfo

' ステップ 2:
modeDepth = g_enumInfo.ddpfPixelFormat.lRGBBitCount

' ステップ 3:
bitDepth = deviceDesc.lDeviceRenderBitDepth

' ステップ 4:
If (32 = modeDepth) And (bitDepth And DDBD_32) Then bCompatible = True
If (24 = modeDepth) And (bitDepth And DDBD_24) Then bCompatible = True
If (16 = modeDepth) And (bitDepth And DDBD_16) Then bCompatible = True

' 必要なディスプレイ モードだけをコンボ ボックスに表示する。
If bCompatible Then
cmbMode.AddItem Str(g_enumInfo.lWidth) + " x" + Str(g_enumInfo.lHeight) + " x" + Str(g_enumInfo.ddpfPixelFormat.lRGBBitCount)
End If
Next j

このアルゴリズムが完了すると、指定された条件に合致するディスプレイ モードのリストがコンボ ボックス cmbMode に保持され、それ以外のディスプレイ モードはすべて無視される。


ステップ 2.2 : DirectDraw サーフェスをセット アップする

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

DirectDraw オブジェクトを作成し、その協調レベルを設定すると、アプリケーションがシーンのレンダリング、表示に使用するサーフェスが作成できる。サーフェスの作成方法は、アプリケーションがウィンドウ内またはフルスクリーン モードのどちらで実行されるかによって、ほぼ決定される。

フルスクリーン アプリケーションについて ： フルスクリーン モードで実行されるアプリケーションは、上記のコード例に示すようにサーフェスを作成することができる。フルスクリーン アプリケーションでは、フルスクリーン排他モードに限って使用できる機能であるページ フリッピングを利用することが頻繁に行われている。フルスクリーン モードの使用については、以下のチュートリアルで説明する。この場合、2 つのサーフェスを明示的に作成するのではなく、単一コールで、サーフェスのフリッピング チェーンを作成することができる。詳細については、「複合サーフェスとフリッピング チェーンの作成」を参照すること。

サンプル Triangle は、ウィンドウ内で実行されるように設計されており、ディスプレイとして機能するプライマリ サーフェスの作成から始まる。

' プライマリ サーフェスを準備して作成する。
    g_ddsd.lFlags = DDSD_CAPS
    g_ddsd.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE

    Set g_ddsPrimary = g_dd.CreateSurface(g_ddsd)

プライマリ サーフェス記述には、寸法やピクセル フォーマットの情報は含まれない。このような特徴は、ディスプレイ モードと同じであると見なされているからである。現在のディスプレイ モードが、800×600 の 16 ビット カラーであれば、DirectDraw は、プライマリ サーフェスも同じであることを保証する。プライマリ サーフェスを作成すると、レンダリング ターゲットのサーフェスを作成することが可能になる。サンプル Triangle の場合、これは、次のようにして作成される、別のオフスクリーン サーフェスとなる。

' レンダリング ターゲットのサーフェスを作成する。ここで g_ddsd を再使用する。
g_ddsd.lFlags = DDSD_HEIGHT Or DDSD_WIDTH Or DDSD_CAPS
g_ddsd.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_3DDEVICE

' フォームのサイズを使ってレンダリング ターゲットのサイズと
' ビューポートの矩形を指定する。
g_dx.GetWindowRect Me.hWnd, g_rcDest

' サーフェス記述のサイズを設定する。
g_ddsd.lWidth = g_rcDest.Right - g_rcDest.Left
g_ddsd.lHeight = g_rcDest.Bottom - g_rcDest.Top

' レンダリング ターゲットのサーフェスを作成する。
Set g_ddsBackBuffer = g_dd.CreateSurface(g_ddsd)

' レンダリング ターゲットのサイズをキャッシュに入れる。このサイズは、
' ブリットで使用される。
With g_rcSrc
.Left = 0:.Top = 0
.Bottom = g_ddsd.lHeight
.Right = g_ddsd.lWidth
End With

上記のコードは、アプリケーション ウィンドウのサイズと等しいオフスクリーン サーフェスを作成する。オフスクリーン サーフェスを使って、後でプライマリ サーフェスにブリットされるイメージをキャッシュに入れる。それより大きいサーフェスは、ウィンドウのサイズによってユーザーに見える範囲が決定されるため、必要とされない (このコードは、ビューポートのセット アップおよびアプリケーション ウィンドウのサイズと位置の追跡を行うために使用する、グローバル変数 g_rcDest の初期化も行っている)。上記のコードが示すように、レンダリング ターゲットとして使用されるサーフェスにはすべて、DDSCAPS_3DDEVICE 能力を含めなければならない。この能力によって、システムは 3D レンダリングに使用される追加の内部データ構造を割り当てる。プライマリ サーフェスを作成する場合と同様に、オフスクリーン サーフェスのピクセル フォーマットは、サーフェス記述で指定されていなければ、ディスプレイ モードと同じとされる。

注 : 深度バッファを使用するアプリケーションでは、この時点で、1 つの深度バッファを作成して、レンダリング ターゲット サーフェスにアタッチする必要がある。理解しやすくするため、このチュートリアルでは深度バッファを使用していないが、深度バッファについては、「チュートリアル 2 : 深度バッファを追加する」および「深度バッファ」で説明する。

レンダリング ターゲットのプライマリ サーフェスを作成すると、DirectDrawClipper オブジェクトを作成して表示サーフェスにアタッチすることが可能になる。クリッパーを使用すると、ウィンドウが部分的にほかのウィンドウによって隠された場合や、ウィンドウが部分的に表示領域を越えた場合の処理をしなくて済む。したがって、クリッパーは、フルスクリーン モードで実行されるアプリケーションには必要ない。サンプル Triangle は、次のコードを使用してクリッパーを作成し、表示ウィンドウに結合している。

' DirectDrawClipper を作成し、プライマリ サーフェスにアタッチする。
Dim pcClipper As DirectDrawClipper

Set pcClipper = g_dd.CreateClipper(0)
pcClipper.SetHWnd Me.hWnd

g_ddsPrimary.SetClipper pcClipper

基本的な DirectDraw オブジェクトの作成を終了すると、シーンをレンダリングする Direct3D 主要オブジェクトのセット アップに進むことができる。サンプル Triangle は、「ステップ 2.3 : Direct3D を初期化する」でこのタスクを行っている。


ステップ 2.2 : 3D トランスフォームを実行する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

このチュートリアルでは、ジオメトリ トランスフォームを使って、立方体の位置座標をシーン内のほかのオブジェクトとの関係で定義し、立方体を回転して、シーン内で立方体をスケールする。

3D トランスフォームを実装する前に、ビューポートの高さと幅を取得する必要がある。この情報を使って、トランスフォームされた頂点をレンダリング ウィンドウに合わせてスケールする。

Private Sub TransformVertices(d3dDevice As Direct3DDevice7, vVertices() As D3DTLVERTEX, nNumVertices As Integer)

Dim vp As D3DVIEWPORT7
Dim nClipWidth As Integer
Dim nClipHeight As Integer

' ビューポートの高さと幅を取得する。この操作は、トランスフォームされた頂点をレンダリング ウィンドウに
' 合わせてスケールするために必要である。
d3dDevice.GetViewport vp
nClipWidth = vp.lWidth / 2
nClipHeight = vp.lHeight / 2

Direct3D では、行列を使ってトランスフォームを実行する。3D トランスフォームを実行するには、現在の行列設定の値を取得する必要がある。この値を取得するには、レンダリング デバイスで Direct3DDevice7.GetTransform を呼び出す。

d3dDevice.GetTransform D3DTRANSFORMSTATE_WORLD, matWorld
d3dDevice.GetTransform D3DTRANSFORMSTATE_VIEW, matView
d3dDevice.GetTransform D3DTRANSFORMSTATE_PROJECTION, matProj

行列を連結するには、行列乗算を使用する。

Dim matSet As D3DMATRIX

g_dx.IdentityMatrix matSet

' 行列を連結する。
g_dx.MatrixMultiply matSet, matWorld, matView
g_dx.MatrixMultiply matSet, matSet, matProj

上記のコードでは、合成行列 matSet を計算して、必要なトランスフォームの積を得る。連結時には、行列が処理順に乗算されるようにする。

行列連結については、「行列連結」を参照すること。

ここで、現在の行列設定によって各頂点をトランスフォームする。

For i = 0 To nNumVertices - 1
' 未トランスフォームの頂点位置を取得する。
x = vVertices(i).sx
y = vVertices(i).sy
z = vVertices(i).sz

xp = matSet.rc11 * x + matSet.rc21 * y + matSet.rc31 * z + matSet.rc41
yp = matSet.rc12 * x + matSet.rc22 * y + matSet.rc32 * z + matSet.rc42
zp = matSet.rc13 * x + matSet.rc23 * y + matSet.rc33 * z + matSet.rc43
wp = matSet.rc14 * x + matSet.rc24 * y + matSet.rc34 * z + matSet.rc44

最後に、スクリーン座標に合わせて頂点をスケールする。次のコードでは、最初のステップで、各座標を wp 値で除算することにより、3D 空間から 2D デバイス座標に変換する。次に、x 座標と y 座標をデバイス座標からスクリーン座標に変換する。

vVertices(i).sx = (1# + (xp / wp)) * nClipWidth
vVertices(i).sy = (1# - (yp / wp)) * nClipHeight
vVertices(i).sz = zp / wp
vVertices(i).rhw = wp
Next i

3D トランスフォームの詳細については、「3D トランスフォーム」を参照すること。

注 : デバイス座標は、ビューポートの -1 から +1 の範囲になる。また、ｚ バッファでは sz 座標を使用する。

これで、立方体の 8 つの頂点をトランスフォームしたので、完成したシーンのフレームをレンダリングすることができる。これが、「ステップ 2.3 : シーンをレンダリングする」の説明内容である。


ステップ 1.2 : 円錐を準備する

[C++]

ここでは、Visual Basic でのアプリケーション開発について説明する。C++ については、「Direct3D 直接モードの C/C++ チュートリアル」を参照すること。

[Visual Basic]

円錐のジオメトリは、位置ベクトルと法線ベクトルを宣言するだけで準備できる。サンプル DrawPrims では、次のプログラマ定義型によって円錐オブジェクトを定義する。

Private Type MyFlexibleVertex
vPosition As D3DVECTOR
vNormal As D3DVECTOR
End Type

円錐の先端は、次のコードで定義できる。

Dim vectorNorm As D3DVECTOR

g_vCone(0).vPosition = MakeVector(0, CONE_HEIGHT / 2, 0)

vectorNorm = MakeVector(0, 1, 0)
Call g_dx.vectorNormalize(vectorNorm)
g_vCone(0).vNormal = vectorNorm

円錐の各面は、次の三角関数で計算できる。

For i = 0 To NUM_CONE_SIDES - 1
x = Sin(2 * pi * i / (NUM_CONE_SIDES - 1))
y = -CONE_HEIGHT / 2
z = Cos(2 * pi * i / (NUM_CONE_SIDES - 1))

g_vCone(i + 1).vPosition = MakeVector(x * CONE_RADIUS, y * CONE_RADIUS, z * CONE_RADIUS)

円錐の各面の位置ベクトルは、次のコードで計算できる。

vectorNorm = MakeVector(x, 0.5, z)
Call g_dx.vectorNormalize(vectorNorm)
g_vCone(i + 1).vNormal = vectorNorm
Next i

ジオメトリ空間で壁セグメントと円錐を定義したら、立方体の準備に進むことができる。この処理については、「ステップ 1.3 : 立方体を準備する」で説明する。


Copyright

本サイトで利用可能なソフトウェアについてのご注意

本使用許諾契約書 (以下「本契約書」といいます) は、このサイト (以下「本サイト」といいます) で利用可能なソフトウェア (以下「本ソフトウェア製品」といいます) に関してお客様 (個人または法人のいずれであるかを問いません) と Microsoft® Corporation (以下「マイクロソフト」といいます) との間に締結される法的な契約書です。本ソフトウェア製品をインストール、複製、または使用することによって、お客様は本契約書の条項に拘束されることに承諾されたものとします。本契約書の条項に同意されない場合、マイクロソフトは、お客様に本ソフトウェア製品のインストール、使用、または複製のいずれも許諾できません。

本ソフトウェア製品は、お客様が本契約書の条項に同意される場合にのみ使用することができます。本契約書の条項に基づかないで本ソフトウェア製品を再ビルドまたは再頒布することは、著作権法および著作権に関する条約をはじめ、その他の無体財産権に関する法律ならびに条約によって禁止されています。

前記の制限にかかわらず、本ソフトウェア製品を、再ビルドまたは再頒布を目的に、いかなるサーバーまたはサイトに対してもコピーおよび再ビルドすることは固く禁止されています。

本ソフトウェア製品は、本契約書の条項に基づいてのみ品質が保証されています。マイクロソフトは、商品性および特定の目的に対する適合性を含む本契約書に規定されていないその他の保証を、明示たると黙示たるとを問わず一切いたしません。

権利の制限。米国およびその機関 (以下「U.S. 政府」といいます) の代表として本サイトから取得したいかなるソフトウェアも、制限された権利の下でのみ提供されます。U.S. 政府による本ソフトウェア製品の使用、複製、または開示は、DFARS 252.227-7013 の Technical Data and Computer Software 条項の「Rights」の (c)(1)(ii)、または 48 CFR 52.227-19 の Commercial Computer Software 条項の「Restricted Rights」の (c)(1) および (2) の項で記述されている制限の下でのみ許可されています。本ソフトウェア製品の製造元は、Microsoft Corporation, One Microsoft Way, Redmond, WA 98052-6399 です。

本サイトで利用可能なドキュメントについてのご注意

本サイトのドキュメント (ホワイト ペーパー、プレス リリース、データベース、FAQ など) の使用は、(1) 下記の著作権表示をドキュメントのすべての複製物に表記する、(2) 本サイトのドキュメントを使用する目的が、情報提供、非営利、または個人的使用に限定されていること、また、本サイトのドキュメントがネットワーク コンピュータにコピーまたは投稿されないこと、さらに、いかなるメディアを通じても本サイトのドキュメントが配信されないこと、(3) ドキュメントのいなかる改竄も行わないこと、という条件が遵守される場合にのみ許可されます。上記以外の目的で、本サイトのドキュメントを使用することは、著作権法および著作権に関する条約によって禁止されています。

上記で規定しているドキュメントには、マイクロソフトの .com Web サイト、またはマイクロソフトが管理、運営するその他のサイトのデザインおよびレイアウトは含まれていません。マイクロソフトの Web サイトのこれらの構成要素は、トレード ドレスまたはその他の法律によって保護されています。また、部分的、全体を問わず、これらの構成要素を複写または模倣することは禁止されています。マイクロソフトの Web サイトのロゴ、グラフィックス、サウンド、およびイメージの使用または変換は、マイクロソフトから明示的に許可されていない限り、禁止されています。

マイクロソフトまたはその供給者は、本サイトのドキュメントおよび関連するグラフィックスに含まれる情報の適合性を保証するものではありません。本サイトのドキュメントおよび関連するグラフィックスは、いかなる保証もなく、現状有姿で提供されます。 マイクロソフトまたはその供給者は、本サイトのドキュメントおよび関連するグラフィックスに含まれる情報に関して、商品性および特定の目的に対する適合性を含む本契約書に規定されていないその他の保証を、明示たると黙示たるとを問わず一切いたしません。 いかなる場合にも、本サイトの情報の利用から生じる損害 (付随的、直接、間接、特別、派生的損害、営業利益損失損害、営業の中断、営業上の情報の喪失、その他金銭的損害を含みますが、それだけに限りません) に対して、マイクロソフトにかかる損害の可能性の通知があった場合でも、マイクロソフトまたはその供給者は、一切責任を負いかねます。

本サイトのドキュメントおよび関連するグラフィックスに含まれる情報は、正確でない可能性があります。また、これらの情報は定期的に更新されます。マイクロソフトまたはその供給者は、本ソフトウェア製品の改善または変更を必要に応じて実施します。

本サイトで利用可能なソフトウェア、ドキュメント、およびサービスについてのご注意

いかなる場合にも、本ソフトウェア製品、本サイトのドキュメント、および本サイトのサービスの使用あるいは使用不能から生じる損害 (付随的、直接、間接、特別、派生的損害、営業利益損失損害、営業の中断、営業上の情報の喪失、その他金銭的損害を含みますが、それだけに限りません) に対して、マイクロソフトにかかる損害の可能性の通知があった場合でも、マイクロソフトまたはその供給者は、一切責任を負いかねます。

サード パーティのサイトへのリンク

サード パーティのサイトから本サイトへリンクが設定されている場合、そのリンクがクリックされることにより、ユーザーは本サイトに移動することができます。本サイトへリンクを設定しているサード パーティのサイトは、マイクロソフトの管理下にはありませんし、マイクロソフトは、これらのサード パーティのサイトのコンテンツおよびリンクに対して一切責任を負いません。マイクロソフトは、これらのリンクを便宜を図るためにのみ提供しています。サード パーティのサイトに本サイトへのリンクが含まれていても、マイクロソフトがそのサード パーティのサイトの安全性を保証しているわけではありません。

著作権についてのご注意。Copyright © 1999 Microsoft およびその供給者, One Microsoft Way, Redmond, Washington 98052-6399 U.S.A. All rights reserved.

商標。Microsoft、Windows、Windows NT、MSN、The Microsoft Network または本サイトで言及されているその他の Microsoft の製品は、Microsoft の商標または登録商標です。本サイトで言及されている実在の会社名および製品名は、各社の商標です。

本サイトで例として取りあげる企業、組織、製品、人物、およびイベントはすべて架空のものです。実在の企業、組織、製品、人物、またはイベントとの関連性を示唆するものではありません。

本契約書のもと明白に許諾されていない権利は、全てマイクロソフトに留保されています。

本サイトのサービスに対してご不明な点やご質問がある場合は、Microsoft までご連絡ください。
**

** ** © 1999 Microsoft Corporation. All rights reserved. Terms of Use.


A

アンビエント（ambient）
オブジェクトの向き、位置、表面特性などに関係なく、シーン上のすべてを照らす光源。シーンのすべての場所を同じ光度で照らすため、そこに置かれたフレームの位置や向きは重要ではない。1つのシーンでは、複数のアンビエント光源が結合されている。
配列オブジェクト（array object）
1つの配列にまとめられたオブジェクト群。配列オブジェクトを使うと、一連のオブジェクトすべてに何らかの処理を行う場合の操作が簡単になる。配列オブジェクトを扱うことができるCOMインターフェイスには、GetElementとGetSizeというメソッドが用意されている。この2つのメソッドはそれぞれ、配列要素へのポインタの取得、および配列サイズの取得を行う。


B

バックバッファ（back buffer）
画面に表示されないサーフェス。アプリケーションは、プライマリサーフェスのイメージが画面に表示されている間に、ビットマップやその他のイメージをバックバッファに描き込むことができる。
バッククリッピングプレーン（back clipping plane）
視錐台の奥行きの限界。この向こう側にあるオブジェクトはレンダリングされない。「フロントクリッピングプレーン」を参照。


C

カメラ（camera）
表示位置と方向を定義するため、ビューポートが用いるDirect3DRMFrameオブジェクト。ビューポートは、カメラフレームの正のz軸上にある可視オブジェクトだけを、y軸上の正方向にレンダリングする。


D

デカール（decal）
ビジュアルオブジェクトとして直接レンダリングされるテクスチャ。ビューポートに位置を合わせた矩形にレンダリングされる。
ディレクショナル（directional）
フレームにアタッチされるが、すべてのオブジェクトを同じ輝度で照らす光源。あたかも光源がオブジェクトから無限の距離に位置するかのような効果を与える。ディレクショナル光は、向きは持つが位置を持たず、一般に、太陽のような遠く離れた光源をシミュレートするために用いられる。


E

放射特性（emissive property）
マテリアル（素材）が光を放射するかどうかを示すマテリアル特性。マテリアルの光の反射具合を決定する特性は２つあるが、放射特性はそのうちの 1 つである。「反射特性」を参照。
有効フレーム（enable frame）
照明を適用することができるフレーム。


F

フロントクリッピングプレーン（front clipping plane）
視錐台の前面の限界。フロントクリッピングプレーンよりもカメラ寄りにあるオブジェクトはレンダリングされない。フロントクリッピングプレーンの高さにより、ビューのフィールドが決まる。「バッククリッピングプレーン」を参照。


M

ミップマップ（mipmap）
同一イメージが徐々に低解像度になっていく一連のテクスチャのことで、1 つのイメージに何種類ものフィルタをかけることにより作成される。オブジェクトが近くに表示されるときには高解像度のイメージが使われ、オブジェクトが遠ざかるにしたがって（つまり画面での表示が小さくなるにしたがって）低解像度のイメージが使われる。
モデル座標（model coordinates）
子フレームに対する相対座標。「ワールド座標」を参照。


N

法線ベクトル（normal vector）
サーフェスから垂直にのびる架空の線で、面の向きの定義に使用される。


P

パラレルポイント（parallel point）
平行な光線でオブジェクトを照らす。光の向きはその位置から決定されるような光源。たとえば、パラレルポイント光源の両側におかれた２つのメッシュがある場合、各メッシュは光源に面している方の面が照らされる。
暗影部（penumbra）
スポットライト照明での周囲の薄暗い部分。暗影部は明部を囲み、その周辺の暗い影とマージされる。「明部」、「スポットライト」を参照。
ポイント（point）
その起点からすべての方向へ均等に光を放射する照明。
強度（power）
マテリアルの反射特性で、反射ハイライトの鮮明度を決める値。この値が５のときは金属的な外観になり、値がもっと高くなるとよりプラスチック的な外観になる。


R

参照カウント（reference count）
COM（コンポーネントオブジェクトモデル）オブジェクトをコントロールするためのカウンタ。参照カウントは、オブジェクトが作成されたときに1に設定される。ポインタがオブジェクトのインターフェイスの1つにポイントが割り当てられると、そのオブジェクトの参照カウントはインクリメントされる。インターフェイス接続が破棄されるとデクリメントされる。参照カウントが0になると、オブジェクトは破棄される。破棄されたオブジェクトへのインターフェイスはすべて無効となる。詳細については、「IUnknownインターフェイス」を参照すること。
ルートフレーム（root frame）
Direct3Dでの、親フレームを持たない（つまり、フレームの階層構造の最上位に位置する）フレーム。ルートフレームには、シーンを構成する一連のオブジェクトすべてが格納される。


S

反射特性（specular property）
光るオブジェクト上の光の点が、反射された光源とどのように対応するかを示すマテリアル特性。マテリアルの光の反射具合を決定する特性は２つあるが、反射特性はそのうちの 1 つである。「放射特性」を参照。
スポットライト（spotlight）
円錐状の光を放つ照明。円錐の中にあるオブジェクトだけが照らされる。円錐は2つの輝度を生成する。中央の明るい部分（明部）はポイント照明と同じ働きをし、周囲の薄暗い部分（暗影部）は周辺の暗い影とマージされる。


T

テクスチャブレンディング（texture blending）
テクスチャの色をマップ先のサーフェスの色と組み合わせる技術。


U

明部（umbra）
照明角度での中央の明るい部分。明部はポイント照明として作用する。「暗影部」、「スポットライト」を参照。


V

頂点分割（vertex split）
頂点分割は、既存の頂点のとなりに新しい頂点を追加し、2つの面を追加する。単一のメッシュ、およびそのメッシュを徐々に精製する頂点分割レコードのセットによって、複合メッシュを構築することができる。これにより、リモートサイトからのメッシュのプログレッシブダウンロードも可能になる。
視錐台（viewing frustum）
ビューポートのカメラに対して相対的に配置されたシーン内の3Dボリューム。視錐台の中にあるオブジェクトは、画面に表示される。遠近ビューでは、フロントクリッピングプレーンとバッククリッピングプレーンの間にある仮想的なピラミッド型のボリュームとなる。正射ビューでは、立方体になる。


W

ワールド座標（world coordinates）
ルートフレームに対する相対座標。「モデル座標」を参照。


GLOSSARY HEAD

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


IDirect3DRMFrame3メソッドA～M

この項は、IDirect3DRMFrame3インターフェイスのメソッドのうち、メソッド名がAからMのものをとりあげるリファレンスページである。

IDirect3DRMFrame3::AddChild

IDirect3DRMFrame3

子フレームをフレーム階層に追加する。

構文

HRESULT AddChild(
  LPDIRECT3DRMFRAME3 lpD3DRMFrameChild
  );

パラメータ

lpD3DRMFrameChild
子として追加するDirect3DRMFrameオブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

子として追加するフレームに、すでに親フレームが存在する場合には、このメソッドは、そのフレームを現在の親から削除した後に新しい親に追加する。子フレームは、Direct3DRMFrameArrayオブジェクトの最後に追加される。Direct3DRMFrameArrayオブジェクトは、IDirect3DRMFrame3::GetChildrenを使って取得できる。

オブジェクトの変換を保存するためには、IDirect3DRMFrame3::GetTransformメソッドを使ってAddChildメソッドを使う前にオブジェクトの変換を取得する。その後、フレームが追加された後でその変換を再適用する。

参照

「階層」

IDirect3DRMFrame3::AddLight

IDirect3DRMFrame3

照明をフレームに追加する。

構文

HRESULT AddLight(
  LPDIRECT3DRMLIGHT lpD3DRMLight
  );

パラメータ

lpD3DRMLight
フレームに追加するDirect3DRMLightオブジェクトを表す変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

照明は、Direct3DRMLightArrayオブジェクトの最後に追加される。Direct3DRMLightArrayオブジェクトは、IDirect3DRMFrame3::GetLightsを使って取得できる。

IDirect3DRMFrame3::AddMoveCallback

IDirect3DRMFrame3

特殊な運動の処理用にコールバック関数を追加する。フレームを移動時または更新時に、このコールバックが呼び出される。

構文

HRESULT AddMoveCallback(
  D3DRMFRAME3MOVECALLBACK d3drmFMC,
  VOID *lpArg,
  DWORD dwFlags
  );

パラメータ

d3drmFMC
アプリケーション定義D3DRMFRAME3MOVECALLBACKコールバック関数。
lpArg
コールバック関数に渡されるアプリケーション定義データ。
dwFlags
以下の値の1つ。
D3DRMCALLBACK_PREORDER － デフォルト値。IDirect3DRMFrame3::Moveが階層をたどって行くとき、フレームのコールバック関数は、子フレームをたどる前に呼び出される。
D3DRMCALLBACK_POSTORDER － IDirect3DRMFrame3::Moveが階層をたどって行くとき、フレームのコールバック関数は, 子フレームをたどった後に呼び出される。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、IDirect3DRMFrame2::AddMoveCallback2を置換する。個々のフレームに対する複数のコールバック関数は、それらの関数の作成順に呼び出される。

参照

IDirect3DRMFrame3::Move, IDirect3DRMFrame3::DeleteMoveCallback

IDirect3DRMFrame3::AddRotation

IDirect3DRMFrame3

(rvX, rvY, rvZ) を中心とする回転を、rvThetaで指定されたラジアンで追加する。

構文

HRESULT AddRotation(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  D3DVALUE rvTheta
  );

パラメータ

rctCombine
新しい回転を現在の任意のフレーム変換と結合する方法を指定するD3DRMCOMBINETYPE列挙型のメンバ。
rvX, rvY, rvZ
回転軸。
rvTheta
ラジアン単位の回転角。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

指定の回転は、このIDirect3DRMFrame3インターフェイスが識別するフレームに対する行列だけを変更する。このメソッドは、レンダリングごとに行列を変更するIDirect3DRMFrame3::SetRotationとは異なりフレームを一度しか変更しない。

参照

「3D変換」, IDirect3DRMFrame3::SetRotation

IDirect3DRMFrame3::AddScale

IDirect3DRMFrame3

フレームのローカル変換を (rvX, rvY, rvZ) でスケーリングする。

構文

HRESULT AddScale(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

パラメータ

rctCombine
新しいスケールを現在の任意のフレーム変換と結合する方法を指定するD3DRMCOMBINETYPE列挙型のメンバ。
rvX, rvY, rvZ
x、y、zの各方向のスケールファクタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

指定の変換は、このIDirect3DRMFrame3インターフェイスが識別するフレームに対する行列だけを変更する。

参照

「3D変換」

IDirect3DRMFrame3::AddTransform

IDirect3DRMFrame3

rctCombineとrmMatrixによって指定されたアフィン変換でフレームのローカル座標を変換する。

構文

HRESULT AddTransform(
  D3DRMCOMBINETYPE rctCombine,
  D3DRMMATRIX4D rmMatrix
  );

パラメータ

rctCombine
新しい変換を現在の任意の変換と結合する方法を指定するD3DRMCOMBINETYPE列挙型のメンバ。
rmMatrix
結合される変換行列を定義するD3DRMMATRIX4D配列のメンバ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

4×4行列が与えられたが、変換がアフィン変換であるためには、最後の列は[0 0 0 1]の転置でなければならない。

指定の変換は、このIDirect3DRMFrame3インターフェイスが識別するフレームに対する行列だけを変更する。

参照

「3D変換」

IDirect3DRMFrame3::AddTranslation

IDirect3DRMFrame3

フレームのローカル座標系に (rvX, rvY, rvZ) による平行移動を追加する。

構文

HRESULT AddTranslation(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

パラメータ

rctCombine
新しい変換を現在の任意の変換と結合する方法を指定するD3DRMCOMBINETYPE列挙型のメンバ。
rvX, rvY, rvZ
x、y、zの各方向での位置変化を定義する。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

指定の変換は、このIDirect3DRMFrame3インターフェイスが識別するフレームに対する行列だけを変更する。

参照

「3D変換」

IDirect3DRMFrame3::AddVisual

IDirect3DRMFrame3

ビジュアルオブジェクトをフレームに追加する。

構文

HRESULT AddVisual(
  LPUNKNOWN lpD3DRMVisual
  );

パラメータ

lpD3DRMVisual
フレームに追加するビジュアルオブジェクトを表す変数へのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

ビジュアルオブジェクトには、メッシュ、プログレッシブメッシュ、テクスチャ、影、ユーザビジュアル、および3D DirectX変換オブジェクトが含まれる。ビジュアルオブジェクトがフレームに追加されると、ビジュアルオブジェクトは、フレームがビュー中にある場合に可視状態になる。フレームはビジュアルオブジェクトを参照する。

IDirect3DRMFrame3::DeleteChild

IDirect3DRMFrame3

階層からフレームを削除する。そのフレームが参照されていなければ、子フレーム、照明、およびメッシュのすべてがともに破棄される。

構文

HRESULT DeleteChild(
  LPDIRECT3DRMFRAME3 lpChild
  );

パラメータ

lpChild
子として使用するDirect3DRMFrameオブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

「階層」

IDirect3DRMFrame3::DeleteLight

IDirect3DRMFrame3

フレームから照明を削除し、フレームが参照されることがなければ破棄する。照明がフレームから削除されると、そのフレームがあったシーンの中のメッシュに以降影響することはない。

構文

HRESULT DeleteLight(
  LPDIRECT3DRMLIGHT lpD3DRMLight
  );

パラメータ

lpD3DRMLight
削除するDirect3DRMLightオブジェクトを表す変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::DeleteMoveCallback

IDirect3DRMFrame3

AddMoveCallbackによって追加されたフレーム移動コールバック関数を削除する。

構文

HRESULT DeleteMoveCallback(
  D3DRMFRAME3MOVECALLBACK d3drmFMC,
  VOID *lpArg
  );

パラメータ

d3drmFMC
アプリケーション定義D3DRMFRAME3MOVECALLBACKコールバック関数。
lpArg
コールバック関数に渡されたアプリケーション定義データ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::AddMoveCallback, IDirect3DRMFrame3::Move

IDirect3DRMFrame3::DeleteVisual

IDirect3DRMFrame3

ビジュアルオブジェクトをフレームから削除し、以降参照されない場合には破棄する。

構文

HRESULT DeleteVisual(
  LPUNKNOWN lpD3DRMVisual
  );

パラメータ

lpD3DRMVisual
削除するDirect3DRMVisualオブジェクトを表す変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::GetAxes

IDirect3DRMFrame3

IDirect3DRMFrame3::SetOrientationメソッドに供給される方向ベクトル (rvDx, rvDy, rvDz) とアップベクトル (rvUx, rvUy, rvUz) と整列するベクトルを取得する。

構文

HRESULT GetAxes(
  LPD3DVECTOR dir,
  LPD3DVECTOR up
  );

パラメータ

dir
フレームのz軸。デフォルトは (0,0,1) である。
up
フレームのy軸。デフォルトは (0,1,0) である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、IDirect3DRMFrame3::SetAxesとともに働き、左手座標系と右手座標系の両方を支援する。SetAxesは、負のz軸がオブジェクトの前面を表すように指定することを可能にする。

参照

IDirect3DRMFrame3::SetAxes, IDirect3DRMFrame3::GetInheritAxes, IDirect3DRMFrame3::SetInheritAxes

IDirect3DRMFrame3::GetBox

IDirect3DRMFrame3

DIRECT3DRMFRAME2オブジェクトを含む境界ボックスを取得する。境界ボックスは、各次元での最小および最大のモデル座標を与える。

構文

HRESULT GetBox(
  D3DRMBOX *lpD3DRMBox
  );

パラメータ

lpD3DRMBox
境界ボックス座標がセットされるD3DRMBOX構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。有効な境界ボックスがすでにフレームに設定されていない場合はD3DRMERR_BOXNOTSETを返す。その他の可能な戻り値のリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、階層的選別に対するフレーム上の境界ボックスをサポートする。有効な境界ボックスは、IDirect3DRMFrame3::SetBoxでフレーム上に設定する必要がある。境界ボックスをイネーブルにするには、IDirect3DRMFrame3::SetBoxEnableメソッドを使ってイネーブルフラグをTRUEにする必要がある。デフォルトで、ボックスイネーブルフラグはFALSEである。デフォルトの境界ボックスはない。

参照

IDirect3DRMFrame3::SetBox, IDirect3DRMFrame3::SetBoxEnable, IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3

境界ボックスがこのDirect3DRMFrame2オブジェクトに対して、イネーブルになっているかどうかを判別するフラグを取得する。

構文

BOOL GetBoxEnable( );

戻り値

境界ボックスがイネーブルであればTRUE、イネーブルでなければFALSEを返す。

注意

境界ボックスをイネーブルにするには、IDirect3DRMFrame3::SetBoxEnableメソッドを使ってイネーブルフラグをTRUEにする必要がある。デフォルトでは、ボックスイネーブルフラグはFALSEである。

参照

IDirect3DRMFrame3::SetBoxEnable IDirect3DRMFrame3::GetBox, IDirect3DRMFrame3::SetBox

IDirect3DRMFrame3::GetChildren

IDirect3DRMFrame3

Direct3DRMFrameArrayオブジェクトの形式で、子フレームのリストを取得する。

構文

HRESULT GetChildren(
  LPDIRECT3DRMFRAMEARRAY *lplpChildren
  );

パラメータ

lplpChildren
この呼び出しが成功した場合に、有効なDirect3DRMFrameArrayポインタで初期化されるポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

DIRECT3DRMFRAMEARRAY, 「階層」

IDirect3DRMFrame3::GetColor

IDirect3DRMFrame3

フレームの色を取得する。

構文

D3DCOLOR GetColor( );

戻り値

Direct3DRMFrame2オブジェクトの色を返す。

参照

IDirect3DRMFrame3::SetColor

IDirect3DRMFrame3::GetHierarchyBox

IDirect3DRMFrame3

このDirect3DRMFrame2オブジェクトをルートとする階層中のすべての幾何図形を含む境界ボックスを計算する。

構文

HRESULT GetHierarchyBox(
  D3DRMBOX *lpD3DRMBox
  );

パラメータ

lpD3DRMBox
境界ボックスの座標がセットされるD3DRMBOX構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::GetBox, IDirect3DRMFrame3::SetBox, IDirect3DRMFrame3::SetBoxEnable, IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3::GetInheritAxes

IDirect3DRMFrame3

フレームの軸が親フレームから継承したものであるかどうかを示すフラグを取得する。

構文

BOOL GetInheritAxes( );

戻り値

フレームが軸を継承する（デフォルト）とTRUE、軸を継承しないとFALSEを返す。

注意

デフォルトでは、軸は親から継承したものである。フレームに親からの継承と設定されていて、親が存在しなければ、フレームはデフォルト軸（方向=(0,0,1)アップ=(0,1,0)）を持つ親から継承したように動作する。

このメソッドおよびIDirect3DRMFrame3::SetInheritAxesメソッドは、階層のルートで設定される軸の単一の方針を許す。

参照

IDirect3DRMFrame3::SetInheritAxes, IDirect3DRMFrame3::GetAxes, IDirect3DRMFrame3::SetAxes

IDirect3DRMFrame3::GetLights

IDirect3DRMFrame3

Direct3DRMLightArrayオブジェクトの形式でフレーム中の照明のリストを取得する。

構文

HRESULT GetLights(
  LPDIRECT3DRMLIGHTARRAY *lplpLights
  );

パラメータ

lplpLights
この呼び出しが成功した場合に、有効なDirect3DRMLightArrayポインタで初期化されるポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMLightArray

IDirect3DRMFrame3::GetMaterial

IDirect3DRMFrame3

Direct3DRMFrame2オブジェクトのマテリアルを取得する。

構文

HRESULT GetMaterial(
  LPDIRECT3DRMMATERIAL2 *lplpMaterial
  );

パラメータ

lplpMaterial
フレームに適用されるDirect3DRMMaterialオブジェクトへのポインタがセットされる変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::SetMaterial

IDirect3DRMFrame3::GetMaterialMode

IDirect3DRMFrame3

フレームのマテリアルモードを取得する。

構文

D3DRMMATERIALMODE GetMaterialMode( );

戻り値

現在のマテリアルモードを指定するD3DRMMATERIALMODE列挙型のメンバを返す。

参照

IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::GetOrientation

IDirect3DRMFrame3

指定の参照フレームを基準とするフレームの方向を取得する。

構文

HRESULT GetOrientation(
  LPDIRECT3DRMFRAME lpRef,
  LPD3DVECTOR lprvDir,
  LPD3DVECTOR lprvUp
  );

パラメータ

lpRef
参照に使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
lprvDir, lprvUp
D3DVECTOR構造体のアドレス。構造体には、それぞれフレームのz軸およびy軸の正規化された方向がセットされる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::SetOrientation

IDirect3DRMFrame3::GetMaterialOverride

IDirect3DRMFrame3

マテリアル属性に対する現在の属性ごとのオーバーライド設定を取得する。

構文

HRESULT GetMaterialOverride(
  LPD3DRMMATERIALOVERRIDE lpdmOverride);

パラメータ

lpdmOverride
オーバーライドするプロパティを記述するD3DRMMATERIALOVERRIDE構造体へのポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

テクスチャがオーバーライドの中にある場合、その参照カウントは戻される前に (AddRefで) インクリメントされており、終了時にテクスチャをリリースする必要がある。このため、テクスチャオーバーライドを適用する場合、リリースを忘れないこと。

参照

SetMaterialOverride

IDirect3DRMFrame3::GetParent

IDirect3DRMFrame3

現在のフレームの親フレームを取得する。

構文

HRESULT GetParent(
  LPDIRECT3DRMRAME3 *lplpParent
  );

パラメータ

lplpParent
フレームの親を表すDirect3DRMFrameオブジェクトへのポインタがセットされたポインタのアドレス。現在のフレームがルートである場合、メソッドの戻り時に、このポインタはNULLになる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::GetPosition

IDirect3DRMFrame3

指定の参照フレームを基準とするフレームの位置を取得する。すなわち、参照フレームからのフレームの距離を取得する。距離は、直線的な値ではなく、ベクトルとしてlprvPosパラメータに格納される。

構文

HRESULT GetPosition(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lprvPos
  );

パラメータ

lpRef
参照フレームとして使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
lprvPos
フレームの位置がセットされるD3DVECTOR構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::SetPosition

IDirect3DRMFrame3::GetRotation

IDirect3DRMFrame3

指定の参照フレームを基準とするフレームの回転を取得する。

構文

HRESULT GetRotation(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lprvAxis,
  LPD3DVALUE lprvTheta
  );

パラメータ

lpRef
参照フレームとして使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
lprvAxis
フレームの回転軸がセットされるD3DVECTOR構造体のアドレス。
lprvTheta
ラジアン単位のフレームの回転となる変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::SetRotation, 「変換」

IDirect3DRMFrame3::GetScene

IDirect3DRMFrame3

指定のフレームを含む階層のルートフレームを取得する。

構文

HRESULT GetScene(
  LPDIRECT3DRMFRAME3 lplpRoot
  );

パラメータ

lplpRoot
シーンのルートフレームを表すDirect3DRMFrameオブジェクトへのポインタがセットされているポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::GetSceneBackground

IDirect3DRMFrame3

シーンの背景色を取得する。

構文

D3DCOLOR GetSceneBackground( );

戻り値

色を返す。

IDirect3DRMFrame3::GetSceneBackgroundDepth

IDirect3DRMFrame3

シーンの現在の背景深度バッファを取得する。

構文

HRESULT GetSceneBackgroundDepth(
  LPDIRECTDRAWSURFACE *lplpDDSurface
  );

パラメータ

lplpDDSurface
現在の背景深度バッファを表すDirectDrawサーフェスのアドレスで初期化されるポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::SetSceneBackgroundDepth

IDirect3DRMFrame3::GetSceneFogColor

IDirect3DRMFrame3

シーンのフォグ色を取得する。

構文

D3DCOLOR GetSceneFogColor( );

戻り値

フォグ色を返す。

IDirect3DRMFrame3::GetSceneFogEnable

IDirect3DRMFrame3

現在このシーンに対してフォグがイネーブルされているかどうかを返す。

構文

BOOL GetSceneFogEnable( );

戻り値

フォグがイネーブルされていればTRUE、イネーブルされていなければFALSEを返す。

IDirect3DRMFrame3::GetSceneFogMethod

IDirect3DRMFrame3

現在のフォグメソッドを取得する。

構文

HRESULT GetSceneFogMethod(
  LPDWORD lpdwFlags);

パラメータ

lpdwFlags
現在のフォグメソッドを受け取るDWORDへのポインタ。現在定義されているフラグは、次の通りである。
D3DRMFOGMETHOD_ANY
Direct3DRMが適用可能なメソッドを選択することを示す。
D3DRMFOGMETHOD_VERTEX
頂点フォグを使用する。
D3DRMFOGMETHOD_TABLE
テーブルフォグを使用する。

戻り値

次の値のうち1つを返す。
D3DRMERR_BADVALUE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMFrame3::GetSceneFogMode

IDirect3DRMFrame3

このシーンに対する現在のフォグモードを返す。

構文

D3DRMFOGMODE GetSceneFogMode( );

戻り値

現在のフォグパラメータを指定するD3DRMFOGMODE列挙型のメンバを返す。

IDirect3DRMFrame3::GetSceneFogParams

IDirect3DRMFrame3

このシーンに対する現在のフォグパラメータを取得する。

構文

HRESULT GetSceneFogParams(
  D3DVALUE *lprvStart,
  D3DVALUE *lprvEnd,
  D3DVALUE *lprvDensity
  );

パラメータ

lprvStart, lprvEnd, lprvDensity
フォグ開始、終了および密度値となる変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::GetSortMode

IDirect3DRMFrame3

子フレームを処理するのに使用されるソートモードを取得する。

構文

D3DRMSORTMODE GetSortMode( );

戻り値

ソートモードを指定するD3DRMSORTMODE列挙型のメンバを返す。

参照

IDirect3DRMFrame3::SetSortMode

IDirect3DRMFrame3::GetTexture

IDirect3DRMFrame3

指定フレームのテクスチャを取得する。

構文

HRESULT GetTexture(
  LPDIRECT3DRMTEXTURE3 *lplpTexture
  );

パラメータ

lplpTexture
フレームのテクスチャを表すDirect3DRMTextureオブジェクトのアドレスがセットされているポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::SetTexture

IDirect3DRMFrame3::GetTransform

IDirect3DRMFrame3

フレームのローカル変換を4×4アフィン行列として取得する。

構文

HRESULT GetTransform(
  LPDIRECT3DRMFRAME lpRefFrame,
  D3DRMMATRIX4D rmMatrix);

パラメータ

lpRefFrame
この呼び出しのためにシーンのルートとして機能するフレーム。この引数がNULLの場合、現在のルートフレーム (GetSceneが返すフレーム) が使用される。
rmMatrix
フレームの変換がセットされるD3DRMMATRIX4D配列。これは、配列なので値はアドレスになる。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。このメソッドは、lpRefFrameパラメータを追加することでIDirect3DRMFrame::GetTransformを拡張する。

参照

「3D変換」

IDirect3DRMFrame3::GetTraversalOptions

IDirect3DRMFrame3

現在のフレームの横断状態を取得する。

構文

HRESULT GetTraversalOptions(
  LPDWORD lpdwFlags);

パラメータ

lpdwFlags
現在の有効状態がセットされるDWORDへのポインタ。現在定義されているフラグは、次の通りである。
D3DRMFRAME_RENDERENABLE
このフレームまたはその子フレームをレンダリングすることを示す。
D3DRMFRAME_PICKENABLE
このフレームまたはその子フレーム中の、任意のビジュアルをピックすることを示す。

戻り値

次の値のうち1つを返す。
D3DRMERR_BADVALUE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMFrame3::GetVelocity

IDirect3DRMFrame3

指定の参照フレームを基準とするフレームの速度を取得する。速度は、ティック当たりの単位で指定される。詳細については、IDirect3DRM3::Tickを参照すること。

構文

HRESULT GetVelocity(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lprvVel,
  BOOL fRotVel
  );

パラメータ

lpRef
参照フレームとして使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
lprvVel
フレームの速度がセットされるD3DVECTOR構造体のアドレス。
fRotVel
直線速度を取得するときに、オブジェクトの回転速度を考慮するかどうかを指定するフラグ。このパラメータがTRUEの場合、オブジェクトの回転速度が計算に含まれる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::SetVelocity

IDirect3DRMFrame3::GetVisuals

IDirect3DRMFrame3

フレーム中のビジュアルのリストを取得する。

構文

HRESULT GetVisuals(
  LPDWORD pdwNumVisuals, LPUNKNOWN *ppUnk
  );

パラメータ

pdwNumVisuals
返される予定のベクトル数を含むDWORD値へのポインタ。ppUnkがNULLならば、GetVisualsはフレームに含まれるビジュアル数を返す。ppUnkがNULLでない場合、DWORD値は実際に取り出されたビジュアル数を受け取る。
ppUnk
初期化されるビジュアルの配列へのポインタ。これをNULLにセットすると、GetVisualsはフレームに含まれるビジュアル数を返すことになる。そうでない場合、これはpdwNumVisualsに対してユーザが割り当てた空間の配列となる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::GetZbufferMode

IDirect3DRMFrame3

Zバッファモードを取得する。すなわち、Zバッファリングがイネーブルまたはディセーブルであるかどうかを確認する。

構文

D3DRMZBUFFERMODE GetZbufferMode( );

戻り値

D3DRMZBUFFERMODE列挙型のメンバの1つを返す。

参照

IDirect3DRMFrame3::SetZbufferMode

IDirect3DRMFrame3::InverseTransform

IDirect3DRMFrame3

ワールド座標のlprvSrcパラメータ中のベクトルをモデル座標に変換して、その結果をlprvDstパラメータに返す。

構文

HRESULT InverseTransform(
  D3DVECTOR *lprvDst,
  D3DVECTOR *lprvSrc
  );

パラメータ

lprvDst
変換の結果がセットされるD3DVECTOR構造体のアドレス。
lprvSrc
変換のソースであるD3DVECTOR構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::Transform, 「3D変換」

IDirect3DRMFrame3::InverseTransformVectors

IDirect3DRMFrame3

ベクトルの配列をワールドからモデル空間に変換する。

構文

HRESULT InverseTransformVectors
(LPDIRECT3DRMFRAME3 lpRefFrame,
DWORD dwNumVectors,
LPD3DVECTOR	lpDstVectors,
LPD3DVECTOR	lpSrcVectors);

パラメータ

lpRefFrame
この呼び出しのためにシーンのルートとして使用されるフレーム。この引数がNULLの場合、現在のルートフレーム (GetSceneが返すフレーム) が使用される。
dwNumVectors
座標を変換する必要があるベクトル数。
lpDstVectors
変換の出力先。
lpSrcVectors
変換するベクトルの配列。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMFrame3::Load

IDirect3DRMFrame3

Direct3DRMFrame2オブジェクトをロードする。

構文

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP
  );

パラメータ

lpvObjSource
ロードするオブジェクトのソース。このソースは、d3drmLOFlagsパラメータで指定されているソースフラグに従い、ファイル、リソース、メモリブロック、またはストリームのいずれかにできる。
lpvObjID
ロードするオブジェクトの名前または位置。このパラメータの使用は、d3drmLOFlagsパラメータで指定されている識別フラグに依存する。D3DRMLOAD_BYPOSITIONフラグが指定されていれば、このパラメータは、ファイル中のオブジェクトの順を与えるDWORD値へのポインタとなる。このパラメータはNULLにできる。
d3drmLOFlags
ロードオプションを記述するD3DRMLOADOPTIONS型の値。
d3drmLoadTextureProc
特殊なフォーマッティングを要求するオブジェクトによって使用される、任意のテクスチャをロードするために呼び出されるD3DRMLOADTEXTURE3CALLBACKコールバック関数。このパラメータはNULLにできる。
lpArgLTP
D3DRMLOADTEXTURE3CALLBACKコールバック関数に渡されるアプリケーション定義データへのポインタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デフォルトでは、このメソッドは、lpvObjSourceパラメータで指定されているファイル中の最初のフレーム階層をロードする。このメソッドを呼び出したフレームは、新しいフレーム階層の親として使用される。デフォルトでは、パースペクティブ補正がオンである。

IDirect3DRMFrame3::LookAt

IDirect3DRMFrame3

指定の参照フレームを基準として、指定の制約によって回転をロックした状態でフレームを対象のフレームに直面させる。

構文

HRESULT LookAt(
  LPDIRECT3DRMFRAME3 lpTarget,
  LPDIRECT3DRMFRAME3 lpRef,
  D3DRMFRAMECONSTRAINT rfcConstraint
  );

パラメータ

lpTarget
対象として使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。
lpRef
参照フレームとして使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
rfcConstraint
D3DRMFRAMECONSTRAINT列挙型のメンバで、軸回転を制約するように指定する。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::Move

IDirect3DRMFrame3

回転と速度を指定の階層のすべてのフレームに適用する。

構文

HRESULT Move(
  D3DVALUE delta
  );

パラメータ

delta
直線と回転速度に対する変化量。各要素における変更は、その要素の速度×deltaに等しい。これらの一方または両方の速度は、任意のフレームを起点として設定することができるが、システムは、自動的にデルタ時間を適用するので、親フレームを起点とした速度に変換する。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。


IDirect3DRMFrame3メソッドN～Z

この項は、IDirect3DRMFrame3インターフェイスのメソッドのうち、メソッド名がNからZのものをとりあげるリファレンスページである。

IDirect3DRMFrame3::RayPick

IDirect3DRMFrame3

このDirect3DRMFrame3オブジェクトを起点として階層を検索し、lpRefFrameパラメータによって指定される座標空間で、任意のビジュアルとdvPosition、dvDirectionパラメータによって指定される光線との交差部分を計算する。

構文

HRESULT RayPick(
  LPDIRECT3DRMFRAME3 lpRefFrame,
  LPD3DRMRAY ray,
  DWORD dwFlags,
  LPD3DRMPICKED2ARRAY *lplpPicked2Array
  );

パラメータ

lpRefFrame
光線を格納するDirect3DRMFrame3オブジェクトのアドレス。
ray
2つのD3DVECTOR構造体を含むD3DRMRAY構造体へのポインタ。最初のD3DVECTOR構造体は、光線のベクトル方向である。二番目のD3DVECTOR構造体は、光線の原点の位置である。
dwFlags
以下のいずれかの値となる。
D3DRMRAYPICK_ONLYBOUNDINGBOXES － 階層中のビジュアルの境界ボックスのある交差部分だけが返される。正確な面の交差はチェックしない。
D3DRMRAYPICK_IGNOREFURTHERPRIMITIVES － 光線に交差する最も近いビジュアルだけが返される。それまでの検索中に発見された最も近いものより遠くにあるビジュアルを無視する。
D3DRMRAYPICK_INTERPOLATEUV － テクスチャ座標を補間する。
D3DRMRAYPICK_INTERPOLATECOLOR － 色を補間する。
D3DRMRAYPICK_INTERPOLATENORMAL － 法線を補間する。
lplpPicked2Array
IDirect3DRMPicked2Arrayインタフェースへの有効なポインタで初期化されるポインタのアドレス。IDirect3DRMPicked2Array::GetPickメソッドを使って、ビジュアルオブジェクト、IDirect3DRMFrameArrayインターフェイス、およびD3DRMPICKDESC2構造体を取得する。フレームの配列は階層を通過するパスで、光線に交差したビジュアルオブジェクトに到達する。D3DRMPICKDESC2構造体には、面やグループの識別子、ピックの位置、頂点の水平および垂直テクスチャ座標、頂点の法線および交差したオブジェクトの色が含まれる。

D3DRMRAYPICK_ONLYBOUNDINGBOXESを指定すると、D3DRMPICKDESC2構造体のテクスチャ、法線および色データは無効になる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

フラグには、最適化フラグと補間フラグの二種類がある。最適化フラグは、検索を制限することができ、したがってそれを高速にする。補間フラグは、プリミティブに行き当たったときに何を補間すべきか指定する。3つの補間選択肢は、色、法線およびテクスチャ座標である。

光線は、参照フレーム座標空間で指定される（lpRefFrameが指す）。参照フレームがNULLの場合には、光線は、ワールド座標で指定される。

IDirect3DRMFrame3::Save

IDirect3DRMFrame3

指定したファイルにDirect3DRMFrame2オブジェクトを保存する。

構文

HRESULT Save(
  LPCSTR lpFilename,
  D3DRMXOFFORMAT d3dFormat,
  D3DRMSAVEOPTIONS d3dSaveFlags
  );

パラメータ

lpFilename
作成したファイルの名前を指定するアドレス。このファイルは、.xファイル名拡張を持たなければならない。
d3dFormat
D3DRMXOFFORMAT列挙型からD3DRMXOF_TEXTの値。
d3dSaveFlags
保存オプションを記述するD3DRMSAVEOPTIONS型の値。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::SetAxes

IDirect3DRMFrame3

IDirect3DRMFrame3::SetOrientationベクトルを変換する座標空間を定義するベクトルを設定する。

構文

HRESULT SetAxes(
  D3DVALUE dx,
  D3DVALUE dy,
  D3DVALUE dz,
  D3DVALUE ux,
  D3DVALUE uy,
  D3DVALUE uz
  );

パラメータ

dx, dy, dz
フレームのz軸。デフォルトは(0,0,1)である。
ux, uy, uz
フレームのy軸。デフォルトは(0,1,0)である。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、左手座標系と右手座標系の両方を支援する。また、負のz軸がオブジェクトの前面を表すように指定することも可能にする。

IDirect3DRMFrame3::SetOrientation方向ベクトル(rvDx, rvDy, rvDz)とアップベクトル(rvUx, rvUy, rvUz)は、SetAxesベクトルの値に従って変換される。

IDirect3DRMFrame3::SetInheritAxesに指定されているように、軸は子フレームによって継承される。

参照

IDirect3DRMFrame3::GetAxes, IDirect3DRMFrame3::GetInheritAxes, IDirect3DRMFrame3::SetInheritAxes

IDirect3DRMFrame3::SetBox

IDirect3DRMFrame3

境界ボックステストで使用するボックスを設定する。境界ボックスが有効であるためには、最小xは最大x以下でなければならず、最小yは最大y以下でなければならず、また最小zは最大z以下でなければならない。

構文

HRESULT SetBox(
  D3DRMBOX *lpD3DRMBox
  );

パラメータ

lpD3DRMBox
境界ボックス座標を含むD3DRMBOX構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、階層的選別に対するフレーム上の境界ボックスをサポートする。境界ボックスをイネーブルにするには、IDirect3DRMFrame3::SetBoxEnableメソッドを使って、イネーブルフラグにTRUEをセットしなければならない。デフォルトでは、ボックスイネーブルフラグはFALSEである。

参照

IDirect3DRMFrame3::GetBox, IDirect3DRMFrame3::SetBoxEnable, IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3::SetBoxEnable

IDirect3DRMFrame3

このDirect3DRMFrame2オブジェクトに対して、境界ボックステストをイネーブルまたはディセーブルする。境界ボックステストをイネーブルにするには、有効な境界ボックスがフレームにすでに設定されていなければならない。

構文

HRESULT SetBoxEnable(
  BOOL bEnableFlag
  );

パラメータ

bEnableFlag
フラグは、境界ボックスがイネーブルかどうかを指定する。TRUEは、境界ボックスをイネーブルにする。境界ボックスがイネーブルでなければFALSE。デフォルトはFALSEである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

境界ボックスをイネーブルにするには、このメソッドを使ってイネーブルフラグにTRUEをセットしなければならない。デフォルトでは、ボックスイネーブルフラグはFALSEである。

境界ボックステストは、以下のように行う。レンダリング時には、境界ボックスはモデル空間に変換して、視錐台との交差部分がないか調べる。ボックス全体が視錐台の外にある場合、フレームや子フレームにあるビジュアルのレンダリングは行わない。それ以外の場合は、通常のレンダリングを続ける。

{0,0,0,0}のボックスで境界ボックステストをイネーブルすると、フレームはまったくレンダリングされない。

参照

IDirect3DRMFrame3::GetBoxEnable, IDirect3DRMFrame3::GetBox, IDirect3DRMFrame3::SetBox

IDirect3DRMFrame3::SetColor

IDirect3DRMFrame3

フレームの色を設定する。この色は、D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEである場合に、フレーム中のメッシュに対して使用される。

構文

HRESULT SetColor(
  D3DCOLOR rcColor
  );

パラメータ

rcColor
フレームの新しい色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。RGBA_MAKE DirectXマクロによって、これらの値を指定することができる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、カラーキーをDIRECT3DRMFRAMEINTERPOLATORオブジェクトに追加するためにも使用する。

参照

IDirect3DRMFrame3::GetColor, IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::SetColorRGB

IDirect3DRMFrame3

フレームの色を設定する。この色は、D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEである場合に、フレーム中のメッシュに対して使用される。

構文

HRESULT SetColorRGB(
  D3DVALUE rvRed,
  D3DVALUE rvGreen,
  D3DVALUE rvBlue
  );

パラメータ

rvRed, rvGreen, rvBlue
フレームの新しい色。色の各要素は、0.0から1.0の範囲にある必要がある。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、RGBカラーキーをDIRECT3DRMFRAMEINTERPOLATORオブジェクトに追加するためにも使用する。

参照

IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::SetInheritAxes

IDirect3DRMFrame3

フレームの軸が親フレームから継承したものであるかどうかを指定する。

構文

HRESULT SetInheritAxes(
  BOOL inherit_from_parent
  );

パラメータ

inherit_from_parent
フレームがその親から軸を継承するかどうかを示すフラグ。TRUEの場合、フレームは軸を継承する（デフォルト）。FALSEの場合、フレームは、軸を継承しない。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デフォルトでは、軸は親から継承したものである。フレームに親からの継承と設定されていて、親が存在しない場合には、フレームは、デフォルト軸(方向=(0,0,1)アップ=(0,1,0))を持つ親から継承したように動作する。このメソッドは、階層のルートで設定される軸の単一の方針を許す。

参照

IDirect3DRMFrame3::GetInheritAxes, IDirect3DRMFrame3::GetAxes, IDirect3DRMFrame3::SetAxes

IDirect3DRMFrame3::SetMaterial

IDirect3DRMFrame3

Direct3DRMFrame2オブジェクトのマテリアルを設定する。

構文

HRESULT SetMaterial(
  LPDIRECT3DRMMATERIAL2 *lplpMaterial
  );

パラメータ

lplpMaterial
フレームに適用されるDirect3DRMMaterialオブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::GetMaterial

IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3

フレームのマテリアルモードを設定する。マテリアルモードは、フレームとレンダリングされるビジュアルのマテリアル情報のソースを決定する。

構文

HRESULT SetMaterialMode(
  D3DRMMATERIALMODE rmmMode
  );

パラメータ

rmmMode
D3DRMMATERIALMODE列挙型のメンバの1つ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::GetMaterialMode

IDirect3DRMFrame3::SetMaterialOverride

IDirect3DRMFrame3

固有のマテリアル属性をセットできるようにする。たとえば、このメソッドはマテリアルの放射プロパティだけをオーバーライドできるようにする。

構文

HRESULT SetMaterialOverride(
  LPD3DRMMATERIALOVERRIDE lpdmOverride);

パラメータ

lpdmOverride
オーバーライドするプロパティを記述するD3DRMMATERIALOVERRIDE構造体へのポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

オーバーライドでは、常に階層をたどってすべてがオーバーライドされる。あるフレームの放射プロパティをオーバーライドする場合、階層をさらにたどって同じプロパティをオーバーライドしようとしても無視される。このオーバーライドは、固有のメッシュ上のマテリアルプロパティだけでなく、標準フレームのオーバーライドよりも優先する。SetMaterialとSetTextureなどのオーバーライドは、このメソッドの動作に対して何の効果も持たない。

このメソッドは、DirectX version 6.0とともに導入された。

参照

GetMaterialOverride

IDirect3DRMFrame3::SetOrientation

IDirect3DRMFrame3

z方向が方向ベクトル [rvDx, rvDy, rvDz] と同方向を指し、y方向がベクトル [rvUx, rvUy, rvUz] と同方向を指すようにフレームを整列する。

構文

HRESULT SetOrientation(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE rvDx,
  D3DVALUE rvDy,
  D3DVALUE rvDz,
  D3DVALUE rvUx,
  D3DVALUE rvUy,
  D3DVALUE rvUz
  );

パラメータ

lpRef
参照フレームとして使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
rvDx, rvDy, rvDz
フレームの新しいz軸。ベクトルの各要素は、-1.0から1.0の範囲にある必要がある。
rvUx, rvUy, rvUz
フレームの新しいy軸。ベクトルの各要素は、-1.0から1.0の範囲にある必要がある。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

フレームのデフォルトの方向は、方向ベクトル [0, 0, 1] およびアップベクトル [0, 1, 0] を持つ。

[rvUx, rvUy, rvUz] が [rvDx, rvDy, rvDz] に平行な場合には、D3DRMERR_BADVALUEエラー値が戻る。そうでない場合には、渡された [rvUx, rvUy, rvUz] ベクトルは、[rvDx, rvDy, rvDz] に垂直なプレーンに投影される。

このメソッドは、Direct3DRMFrameInterpolatorオブジェクトに方向キーを追加するためにも使用する。

DirectX version 6.0以前では、SetOrientationはスケールとせん断について考慮していなかった。これは、DirectX version 6.0では修正されている。

次のコード部分は、SetOrientationを呼び出し、デフォルトの方向をセットする。これは、IDirect3DRM3::CreateFrameメソッドを使用して、カメラとシーンフレームがすでに作成されていることを前提としている。

LPDIRECT3DRMFRAME3 camera;
LPDIRECT3DRMFRAME3 scene;

if (FAILED(camera->SetOrientation(scene, D3DVAL(0), D3DVAL(0), D3DVAL(1),
                                  D3DVAL(0), D3DVAL(1), D3DVAL(0)))
{
    // エラー
}

参照

IDirect3DRMFrame3::GetOrientation

IDirect3DRMFrame3::SetPosition

IDirect3DRMFrame3

参照フレームを基準とするフレームの位置を設定する。フレームを参照フレームから[rvX, rvY, rvZ]の距離に置く。子フレームが親フレーム内に作成される場合、親フレームの[0, 0, 0]に置かれる。

構文

HRESULT SetPosition(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

パラメータ

lpRef
参照フレームとして使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
rvX, rvY, rvZ
フレームの新しい位置。位置は単位を持たない。視錐台を使用して、適正な数字を選択する。詳細については、「ビューポート」を参照すること。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMFrameInterpolatorオブジェクトに位置キーを追加するためにも使用する。

次のコード部分は、SetPositionを呼び出す。これは、IDirect3DRM3::CreateFrameメソッドを使用して、カメラとシーンフレームがすでに作成されていることを前提としている。

LPDIRECT3DRMFRAME3 camera;
LPDIRECT3DRMFRAME3 scene;

if (FAILED(camera->SetPosition(scene, D3DVAL(0), D3DVAL(0), -D3DVAL(10)))
{
    // エラー
}

参照

IDirect3DRMFrame3::GetPosition

IDirect3DRMFrame3::SetQuaternion

IDirect3DRMFrame3

単位4元数を用いて、参照フレームに対してフレームの向きを設定する。

構文

HRESULT SetQuaternion(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DRMQUATERNION *quat
  )

パラメータ

lpRef
参照として用いるDirect3DRMFrame2オブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
quat
単位4元数を保持するD3DRMQUATERNION構造体。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

4元数とは、任意の回転を表すために用いられる四値ベクトルで、向きの間で補間を行うときに有用な特性を持っている。4元数は、s**2 + x**2 + y**2 + z**2 = 1であれば単位4元数である。

関数D3DRMQuaternionFromRotationは、任意の回転値から単位4元数を生成するときに用いる。

SetQuaternionメソッドは、FrameInterpolatorsによりサポートされている。インターポレータについての詳細は、「インターポレータ」を参照すること。

IDirect3DRMFrame3::SetRotation

IDirect3DRMFrame3

IDirect3DRM3::TickまたはIDirect3DRMFrame3::Moveメソッドに対する呼び出しごとに、指定のベクトルの周囲に指定の角度でフレームの回転を設定する。方向ベクトル [rvX, rvY, rvZ] は、参照フレームで定義される。

構文

HRESULT SetRotation(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  D3DVALUE rvTheta
  );

パラメータ

lpRef
参照フレームとして使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
rvX, rvY, rvZ
回転の中心のベクトル。有効な値は、-1.0から1.0の範囲にある必要がある。
rvTheta
ラジアン単位の回転角。角度が大きければ大きいほど、オブジェクトの回転は速くなる。IDirect3DRMFrame3::MoveとIDirect3DRM3::Tickメソッドが、この値をスケーリングする。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

指定の回転は、フレーム中のオブジェクトを一度しか変更しないIDirect3DRMFrame3::AddRotationメソッドとは異なり、レンダリングごとに行列を変更する。

次のコード部分は、SetRotationを呼び出す。これは、IDirect3DRM3::CreateFrameメソッドを使用して、子とシーンフレームがすでに作成されていることを前提としている。

LPDIRECT3DRMFRAME3 child;
LPDIRECT3DRMFRAME3 scene;

if (FAILED(child->SetRotation(scene, D3DVAL(0), D3DVAL(1), D3DVAL(1), D3DVAL(0.02)))
{
    // エラー
}

参照

IDirect3DRMFrame3::AddRotation, IDirect3DRMFrame3::GetRotation

IDirect3DRMFrame3::SetSceneBackground

IDirect3DRMFrame3

シーンの背景色を設定する。

構文

HRESULT SetSceneBackground(
  D3DCOLOR rcColor
  );

パラメータ

rcColor
背景の新しい色。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMFrameInterpolatorオブジェクトへの背景カラーキーを追加するためにも使われる。

IDirect3DRMFrame3::SetSceneBackgroundDepth

IDirect3DRMFrame3

シーンの背景深度バッファを指定する。

構文

HRESULT SetSceneBackgroundDepth(
  LPDIRECTDRAWSURFACE lpImage
  );

パラメータ

lpImage
シーンの新しい背景深度を保存するDirectDrawサーフェスのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

イメージはピクセル単位の深度16を持たなければならない。イメージとビューポートのサイズが異なると、はじめにイメージのスケーリングを行う。背景深度バッファをアニメートするときに最適なパフォーマンスを得るには、イメージはビューポートと同じサイズでなければならない。そうすると、余分なオーバーヘッドなしに、深度バッファはイメージメモリから直接更新することができる。

参照

IDirect3DRMFrame3::GetSceneBackgroundDepth

IDirect3DRMFrame3::SetSceneBackgroundImage

IDirect3DRMFrame3

シーンの背景イメージを指定する。

構文

HRESULT SetSceneBackgroundImage(
  LPDIRECT3DRMTEXTURE3 lpTexture
  );

パラメータ

lpTexture
新しい背景シーンを含むDirect3DRMTextureオブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

イメージのサイズまたはカラー深度がビューポートと異なる場合、まずイメージのスケーリングを行うか、正しい深度に変換する。背景をアニメートするときに最適なパフォーマンスを得るには、イメージはビューポートと同じサイズおよびカラー深度でなければならない。そうすると、余分なオーバーヘッドなしに、直接イメージメモリから背景のレンダリングを行うことができる。

IDirect3DRMFrame3::SetSceneBackgroundRGB

IDirect3DRMFrame3

シーンの背景色を設定する。

構文

HRESULT SetSceneBackgroundRGB(
  D3DVALUE rvRed,
  D3DVALUE rvGreen,
  D3DVALUE rvBlue
  );

パラメータ

rvRed, rvGreen, rvBlue
背景の新しい色。色の各要素は、0.0から1.0の範囲にある必要がある。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMFrameInterpolatorオブジェクトに背景RGBカラーキーを追加するためにも用いられる。

IDirect3DRMFrame3::SetSceneFogColor

IDirect3DRMFrame3

シーンのフォグ色を設定する。

構文

HRESULT SetSceneFogColor(
  D3DCOLOR rcColor
  );

パラメータ

rcColor
フォグの新しい色。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMRFrameInterpolatorオブジェクトにフォグカラーキーを追加するためにも用いられる。

IDirect3DRMFrame3::SetSceneFogEnable

IDirect3DRMFrame3

フォグイネーブル状態を設定する。

構文

HRESULT SetSceneFogEnable(
  BOOL bEnable
  );

パラメータ

bEnable
新しいフォグイネーブル状態。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMFrame3::SetSceneFogMethod

IDirect3DRMFrame3

頂点フォグまたはテーブルフォグを介してフォグを実行するかどうかを指定する。

構文

HRESULT SetSceneFogMethod(
  DWORD dwFlags);

パラメータ

dwFlags
現在定義されているフラグは、次の通りである。
D3DRMFOGMETHOD_ANY
Direct3D保持モードが適用可能なメソッドを選択することを示す。
D3DRMFOGMETHOD_VERTEX
頂点フォグを使用する。
D3DRMFOGMETHOD_TABLE
テーブルフォグを使用する。

戻り値

次の値のうち1つを返す。
D3DRMERR_BADVALUE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

IDirect3DRM3インターフェイスによって作成されるDirect3DRMFrameオブジェクトのデフォルトの動作はD3DRMFOGMETHOD_ANYであり、フォグメソッドはデバイスの機能に基づいて選択される。デバイスが頂点とテーブルを基準とした両方のフォグをサポートする場合、頂点フォグが使用される。アプリケーションでテーブルフォグが要求されたが、テーブルフォグが使用可能でない場合も、頂点フォグが使用される。IDirect3DRMまたはIDirect3DRM2インターフェイスによって作成されるDirect3DRMFrameオブジェクトの動作は、D3DRMFOGMETHOD_VERTEXである。

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMFrame3::SetSceneFogMode

IDirect3DRMFrame3

フォグモードを設定する。

構文

HRESULT SetSceneFogMode(
  D3DRMFOGMODE rfMode
  );

パラメータ

rfMode
D3DRMFOGMODE列挙型のメンバの1つで、新しいフォグモードを指定する。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::SetSceneFogParams

IDirect3DRMFrame3::SetSceneFogParams

IDirect3DRMFrame3

このシーンの現在のフォグパラメータを設定する。

構文

HRESULT SetSceneFogParams(
  D3DVALUE rvStart,
  D3DVALUE rvEnd,
  D3DVALUE rvDensity
  );

パラメータ

rvStart, rvEnd
線形フォグモードのフォグ開始および終了ポイント。この設定は、フォグ効果が最初に見えるようになるときのカメラからの距離と、フォグが最大密度になるときの距離を決める。
rvDensity
指数フォグモードでのフォグ密度。この値は、0から1の値でなければならない。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、Direct3DRMRFrameInterpolatorオブジェクトにフォグパラメータキーを追加するためにも用いられる。

参照

D3DRMFOGMODE, IDirect3DRMFrame3::SetSceneFogMode

IDirect3DRMFrame3::SetSortMode

IDirect3DRMFrame3

子フレームを処理するのに使用するソートモードを設定する。このメソッドを使用して隠面削除アルゴリズムのプロパティを変更することができる。

構文

HRESULT SetSortMode(
  D3DRMSORTMODE d3drmSM
  );

パラメータ

d3drmSM
ソートモードを指定するD3DRMSORTMODE列挙型のメンバの1つ。デフォルト値は、D3DRMSORT_FROMPARENTである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::GetSortMode

IDirect3DRMFrame3::SetTexture

IDirect3DRMFrame3

フレームのテクスチャを設定する。

構文

HRESULT SetTexture(
  LPDIRECT3DRMTEXTURE3 lpD3DRMTexture
  );

パラメータ

lpD3DRMTexture
使用するDirect3DRMTextureオブジェクトを表す変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このテクスチャは、D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEである場合にフレーム中のメッシュに対して使用される。フレームのテクスチャをディセーブルにするには、NULLテクスチャを使用する。

参照

IDirect3DRMFrame3::GetTexture, IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::SetTraversalOptions

IDirect3DRMFrame3

レンダリングとピッキングの際にこのフレームを横断するかどうかを指定する。すなわち、D3DRMFRAME_RENDERENABLEの値なしでこのAPIを使用すると、レンダリングに対してフレームが効率的にオフに切り換わる。デフォルトでは、フレームはレンダリングとピッキングに対して有効になる。

構文

HRESULT SetTraversalOptions
(DWORD dwFlags);

パラメータ

dwFlags
現在定義されているフラグは、次の通りである。
D3DRMFRAME_RENDERENABLE
このフレームまたはその子フレームをレンダリングすることを示す。
D3DRMFRAME_PICKENABLE
このフレームまたはその子フレーム中の、任意のビジュアルをピックすることを示す。

戻り値

次の値のうち1つを返す。
D3DRMERR_BADVALUE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMFrame3::SetVelocity

IDirect3DRMFrame3

参照フレームを基準として指定のフレームの速度を設定するフレームは、IDirect3DRM3::TickまたはIDirect3DRMFrame3::Moveメソッドに対する連続呼び出しごとに、参照フレームを基準として [rvX, rvY, rvZ] ベクトル分だけ移動する。

構文

HRESULT SetVelocity(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  BOOL fRotVel
  );

パラメータ

lpRef
参照フレームとして使用されるDirect3DRMFrameオブジェクトを表す変数のアドレス。これはNULLにすることができる。NULLの場合、メソッドは参照フレームの変換マトリックスではなく、ローカルの変換マトリックスを使う。
rvX, rvY, rvZ
フレームの新しい速度。回転速度は単位を持たず、任意の値をセットできる。IDirect3DRMFrame3::MoveとIDirect3DRM3::Tickメソッドは、この値をスケーリングする。
fRotVel
直線速度を設定するときに、オブジェクトの回転速度を考慮するかどうかを指定するフラグ。TRUEの場合、オブジェクトの回転速度が計算に含まれる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::GetVelocity

IDirect3DRMFrame3::SetZbufferMode

IDirect3DRMFrame3

Zバッファモードを設定する。すなわち、Zバッファリングをイネーブルまたはディセーブルにするかを設定する。

構文

HRESULT SetZbufferMode(
  D3DRMZBUFFERMODE d3drmZBM
  );

パラメータ

d3drmZBM
Zバッファモードを指定するD3DRMZBUFFERMODE列挙型のメンバの1つ。デフォルト値はD3DRMZBUFFER_FROMPARENTである。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::GetZbufferMode

IDirect3DRMFrame3::Transform

IDirect3DRMFrame3

モデル座標のlpd3dVSrcパラメータ中のベクトルを変換し、その結果をワールド座標のlpd3dVDstパラメータに返す。

構文

HRESULT Transform(
  D3DVECTOR *lpd3dVDst,
  D3DVECTOR *lpd3dVSrc
  );

パラメータ

lpd3dVDst
変換操作の結果がセットされるD3DVECTOR構造体のアドレス。
lpd3dVSrc
変換操作のソースであるD3DVECTOR構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMFrame3::InverseTransform, 「3D変換」

IDirect3DRMFrame3::TransformVectors

IDirect3DRMFrame3

ベクトルの配列を、モデルからワールド空間に変換する。

構文

HRESULT TransformVectors(
  LPDIRECT3DRMFRAME3 lpRefFrame,
  DWORD dwNumVectors,
  LPD3DVECTOR lpDstVectors,
  LPD3DVECTOR lpSrcVectors);

パラメータ

lpRefFrame
この呼び出しのためにシーンのルートとして使用されるフレーム。この引数がNULLの場合、現在のルートフレーム(GetSceneが返すフレーム)が使用される。
dwNumVectors
変換する必要のあるベクトル数。
lpDstVectors
変換の出力先。
lpSrcVectors
変換するベクトルの配列。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。


IDirect3DRMMeshBuilder3

IDirect3DRMMeshBuilder3メソッドA～M

この項は、IDirect3DRMMeshBuilder3インターフェイスのメソッドのうち、メソッド名がAからMのものをとりあげるリファレンスページである。

IDirect3DRMMeshBuilder3::AddFace

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに1つの面を追加する。

構文

HRESULT AddFace(
  LPDIRECT3DRMFACE2 lpD3DRMFace
  );

パラメータ

lpD3DRMFace
追加する面へのポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

どの1つの面も、一度に1つのメッシュにしか存在できない。

IDirect3DRMMeshBuilder3::AddFaces

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに複数の面を追加する。

構文

HRESULT AddFaces(
  DWORD dwVertexCount,
  D3DVECTOR  *lpD3DVertices,
  DWORD normalCount,
  D3DVECTOR *lpNormals,
  DWORD *lpFaceData,
  LPDIRECT3DRMFACEARRAY *lplpD3DRMFaceArray
  );

パラメータ

dwVertexCount
頂点の数。
lpD3DVertices
頂点位置を格納するD3DVECTOR構造体からなる配列のベースアドレス。
normalCount
法線の数。
lpNormals
法線の位置を格納するD3DVECTOR構造体からなる配列のベースアドレス。
lpFaceData
各面に対して、このパラメータは、頂点カウントとそれに続いて頂点配列のインデックスを含む必要がある。normalCountが0でなければ、このパラメータは、頂点カウントとそれに続いてインデックスの対を含む必要がある。そのインデックスの対の最初のインデックスは、頂点配列に対するインデックスであり、2番目のインデックスは、法線の配列に対するインデックスである。インデックスのリストは、0で終了しなければならない。
lplpD3DRMFaceArray
IDirect3DRMFaceArrayインターフェイスへのポインタのアドレス。新しく作成された面へのポインタがセットされる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::AddFacesIndexed

IDirect3DRMMeshBuilder3

既存の頂点と法線 (オプション) を使用するメッシュビルダ上に、多数の面を作成できるようにする。

構文

IDirect3DRMMeshBuilder3::AddFacesIndexed(
  DWORD dwFlags,
  DWORD *lpdwvIndices,
  DWORD *lpdwIndexFirst,
  DWORD *lpdwCount);

パラメータ

dwFlags
法線インデックスの処理方法を指定するフラグ値。0またはD3DRMADDFACES_VERTICESONLYのどちらかでなければならない。値が0ならば、既存の法線インデックスはlpdwvIndicesパラメータ中に指定されていなければならない。そうでない場合、対応するインデックスを持つ法線が各頂点に対して自動的に使用される。
lpdwvIndices
各面に対して次のものを指定する、符号なし整数のタップルの連続する配列へのポインタ。
  • 頂点の数n、ここでnは3以上
  • 頂点インデックス
  • 法線インデックス (オプション)

次のテーブルは、dwFlagsパラメータの値とlpdwvIndicesパラメータの必須面タップル形式との関係を示す。
dwFlags | 必須面タップル形式
0 | {<n>, <vIndex0>, <nIndex0>,...,<vIndexn-1>, <nIndexn-1>}
D3DRMADDFACES_VERTICESONLY | {<n>, <vIndex0>,...,<vIndexn-1>}

vIndexとnIndexの値は、メッシュビルダ内にすでに存在している頂点と法線に索引するのに必要となる。タップルの配列は値0で終了する必要がある。

lpdwIndexFirst
メッシュビルダに追加された最初の新しい面のインデックスがセットされるDWORDへのオプションのポインタ。続く面には連続するインデックスが付けられる。面は、lpdwvIndicesパラメータで指定された順に追加される。
lpdwCount
メッシュビルダに追加された面の数がセットされるDWORDへのオプションのポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMeshBuilder3::AddFrame

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトにフレームの内容を追加する。

構文

HRESULT AddFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame
  );

パラメータ

lpD3DRMFrame
その内容が追加されるフレームへのポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、指定されたフレーム階層 (より大きなフレーム階層のサブ分岐も可) からDirect3DRMMeshBuilder3オブジェクトへ、すべてのメッシュとメッシュビルダの面のコピーを追加する。フレームツリーは、ルートフレームを渡すことで指定する。面は、それらが内包する要素フレームの位置と方向によって追加される。ルートフレームに親があっても、指定されたルートフレームの変換は無視される。

ソースフレームは、この操作によって変更または参照もされない。

IDirect3DRMMeshBuilder3::AddMesh

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトにメッシュを追加する。

構文

HRESULT AddMesh(
  LPDIRECT3DRMMESH lpD3DRMMesh
  );

パラメータ

lpD3DRMMesh
追加するメッシュへのポインタのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::AddMeshBuilder

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの内容を別のDirect3DRMMeshBuilder3オブジェクトに追加する。内包するDirect3DRMMeshBuilder3ソースオブジェクトと面のもとにあるすべてのサブメッシュビルダは、Direct3DRMMeshBuilder3ターゲットオブジェクトのもとで重複する。

構文

HRESULT
AddMeshBuilder(
  LPDIRECT3DRMMESHBUILDER3 lpD3DRMMeshBuild
  DWORD dwFlags);
  );

パラメータ

lpD3DRMMeshBuild
その内容を追加するDirect3DRMMeshBuilder3オブジェクトへのポインタ。
dwFlags

次に定義するフラグの1つ。

D3DRMADDMESHBUILDER_FLATTENSUBMESHES
サブメッシュオブジェクトが重複しないようにする。これらの面は依然コピー可能であるが、出力先メッシュビルダのトップレベルに対してのみである。
D3DRMADDMESHBUILDER_NOSUBMESHES
サブメッシュビルダを無視するようにする。
D3DRMADDMESHBUILDER_DONTCOPYAPPDATA
AddMeshBuilder3は、ソースメッシュビルダのアプリケーションデータを出力先にコピーする。D3DRMADDMESHBUILDER_DONTCOPYAPPDATAを指定すると、これが防止される。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

ソースのDirect3DRMMeshBuilder3オブジェクトは、この操作で変更または参照もされない。

IDirect3DRMMeshBuilder3::AddNormal

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに法線を追加する。

構文

int AddNormal(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

パラメータ

x, y, z
新しい法線の方向のx、y、zの各要素。

戻り値

法線のインデックスを返す。

IDirect3DRMMeshBuilder3::AddTriangles

IDirect3DRMMeshBuilder3

アプリケーションが新しい三角形 (一般的なポリゴンと対立的な意味で) をIDirect3DRMMeshBuilder3オブジェクトに追加し、処理中に暗黙に新しい面を作成できるようにする。このメソッドは、三角形を記述するアプリケーションに柔軟性を提供する。三角形は頂点のセットにより記述できる。各頂点は位置を持たなければならないが、オプションで、法線、テクスチャ座標または色のうちどれかを持つか、まったく持たなくてもよい。また、頂点には、この新しい頂点がリスト、細片、または扇を記述するかどうかを示すタイプを持つ。また、このフラグは、該当する三角形を以前の三角形の面に追加するかどうか、または新しい面を作成するかどうかも示す。

構文

HRESULT AddTriangles(
  DWORD dwFlags,
  DWORD dwFormat,
  DWORD dwVertexCount,
  LPVOID lpData);

パラメータ

dwFlags
0でなければならない。
dwFormat
頂点データのフォーマットを記述する値の論理的な組み合わせ。すべての有効な値が含まれている場合、頂点データは次のElement構造体によって記述できる。
struct Element
{
    DWORD     dwType;
    D3DVECTOR dvPosition;
    D3DVECTOR dvNormal;
    D3DCOLOR  dcColor;
    D3DVALUE  tu;
    D3DVALUE  tv;
};

有効な値としては、次の値の任意の組み合わせが可能であり、これらはElement構造体のどのメンバを各要素の記述に含めるかを示す。dvPositionメンバは常に存在する。

D3DRMFVF_TYPE
dwType構造体メンバを含める。dwType構造体メンバが存在する場合、その中には次のどれか1つがなければならない。
D3DRMVERTEX_LIST
新しいリストを開始するか、あるいは以前に開始したリストのメンバである。以前の頂点 (またはその前の頂点) にこのフラグのマークが付いていない場合、最低1つの三角形が形成されるまで、次の頂点にこのフラグのマークが付いていなければならない。
D3DRMVERTEX_STRIP
以前の2つの頂点を持つ新しい三角形を細片フォーマットで形成する。
D3DRMVERTEX_FAN
以前の頂点と扇の最初の頂点を持つ新しい三角形を形成する。
D3DRMFVF_NORMAL
dvNormal構造体メンバを含める。
D3DRMFVF_COLOR
dcColor構造体メンバを含める。
D3DRMFVF_TEXTURECOORDS
tuとtv構造体メンバを含める。
dwVertexCount
頂点の数。
lpvData
dwFormatで記述されるデータへのポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

次の例は、図中の各頂点に対して適切なdwTypeフラグを示す。
頂点数 | dwTypeフラグ
0 | D3DRMVERTEX_STRIP
1 | D3DRMVERTEX_STRIP
2 | D3DRMVERTEX_STRIP
3 | D3DRMVERTEX_STRIP
4 | D3DRMVERTEX_STRIP
5 | D3DRMVERTEX_FAN
6 | D3DRMVERTEX_FAN
7 | D3DRMVERTEX_FAN
8 | D3DRMVERTEX_FAN
9 | D3DRMVERTEX_LIST
10 | D3DRMVERTEX_LIST
11 | D3DRMVERTEX_LIST
12 | D3DRMVERTEX_LIST
13 | D3DRMVERTEX_LIST
14 | D3DRMVERTEX_LIST

IDirect3DRMMeshBuilder3::AddVertex

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに頂点を追加する。

構文

int AddVertex(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

パラメータ

x, y, z
新しい頂点の位置のx、y、zの各要素。

戻り値

頂点のインデックスを返す。

IDirect3DRMMeshBuilder3::CreateFace

IDirect3DRMMeshBuilder3

頂点の新しい面を作成し、Direct3DRMMeshBuilder3オブジェクトに追加する。

構文

HRESULT CreateFace(
  LPDIRECT3DRMFACE2 *lplpD3DRMFace2
  );

パラメータ

lplpD3DRMFace2
IDirect3DRMFace2インターフェイスへのポインタのアドレス。作成された面へのポインタがセットされる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::CreateMesh

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトから新しいメッシュを作成する。

構文

HRESULT CreateMesh(
  LPDIRECT3DRMMESH *lplpD3DRMMesh
  );

パラメータ

lplpD3DRMMesh
<IDirect3DRMMeshインターフェイスへのポインタがセットされるアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::CreateSubMesh

IDirect3DRMMeshBuilder3

現在のDirect3DRMMeshBuilder3オブジェクトに対して、新しいサブメッシュを作成する。サブメッシュは、IDirect3DRMMeshBuilder3インターフェイスをサポートし、それ自体もサブメッシュを持てるという点で、メッシュビルダオブジェクトに類似している。サブメッシュとメッシュビルダの相違は、すべてのサブメッシュが頂点と法線を、サブメッシュの連鎖中の大元の祖先と共有することである。メッシュビルダは頂点と法線を共有しない。

構文

HRESULT CreateSubMesh(
  LPUNKNOWN  *lplpUnk);

パラメータ

lplpUnk
新しいサブメッシュのIUnknownインターフェイスへのポインタを受け取るアドレス。IUnknownインターフェイス上のQueryInterfaceを使用して、IDirect3DRMMeshBuilder3サポートの照会を行うことができる。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

DeleteSubMesh, GetSubMeshes, GetParentMesh

IDirect3DRMMeshBuilder3::DeleteFace

IDirect3DRMMeshBuilder3

IDirect3DRMMeshBuilder3オブジェクトの面を削除する。

構文

HRESULT DeleteFace
(LPDIRECT3DRMFACE2 lpFace);

パラメータ

lpFace
Direct3DRMMeshBuilder3オブジェクトから削除するDirect3DRMFace2オブジェクトのインターフェイスへのポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMeshBuilder3::DeleteNormals

IDirect3DRMMeshBuilder3

法線の内包範囲を削除する。面がどれかの法線を現在使用中であれば、エラーが返されるので、注意すること。

構文

HRESULT DeleteNormals
(DWORD dwFirstIndex,
DWORD dwCount);

パラメータ

dwFirstIndex
削除する最初の法線のインデックス。
dwCount
削除する頂点のカウント。

戻り値

次の値のうち1つを返す。
D3DRMERR_ENTRYINUSE
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMeshBuilder3::DeleteSubMesh

IDirect3DRMMeshBuilder3

サブメッシュを削除する。サブメッシュは、現在のDirect3DRMMeshBuilder3オブジェクトのすぐ下の子でなければならない。

構文

HRESULT DeleteSubMesh(
  LPUNKNOWN lplpUnk);

パラメータ

lplpUnk
削除するサブメッシュのIUnknownインターフェイスへのポインタ。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

CreateSubMesh, GetSubMeshes, GetParentMesh

IDirect3DRMMeshBuilder3::DeleteVertices

IDirect3DRMMeshBuilder3

頂点の内包範囲を削除する。面がどれかの頂点を現在使用中であれば、エラーが返されるので、注意すること。

構文

HRESULT DeleteVertices
(DWORD dwFirstIndex,
DWORD dwCount);

パラメータ

dwFirstIndex
削除する最初の頂点のインデックス。
dwCount
削除する頂点のカウント。

戻り値

次の値のうち1つを返す。
D3DRMERR_ENTRYINUSE
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMeshBuilder3::Empty

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトから、すべての面、頂点、法線を削除する。

構文

HRESULT Empty
(DWORD dwFlags);

パラメータ

dwFlags
フラグ。0でなければならない。

戻り値

次の値のうち1つを返す。
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMeshBuilder3::Enable

IDirect3DRMMeshBuilder3

このDirect3DRMMeshBuilder3オブジェクトを、レンダリングとピッキング用に有効にするか無効にするかを指定する。

構文

HRESULT Enable(
  DWORD dwFlags);

パラメータ

dwFlags

現在定義されているフラグは、次の通りである。

D3DRMADDMESHBUILDER_RENDERENABLE
このDirect3DRMMeshBuilder3オブジェクト上ではレンダリングが有効になっている。この設定はデフォルトである。
D3DRMADDMESHBUILDER_PICKENABLE
このDirect3DRMMeshBuilder3オブジェクト上では、ピッキングが有効になっている。この設定はデフォルトである。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

GetEnable

IDirect3DRMMeshBuilder3::GenerateNormals

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトを処理し、頂点を共有する各面に対する面法線を平均化することによって、メッシュ中の各頂点に対して法線を生成する。新しい法線は、頂点を共有する面が、面同士の角度が折れ目の角度より大きい場合に生成される。

構文

HRESULT GenerateNormals(
  D3DVALUE dvCreaseAngle,
  DWORD dwFlags
  );

パラメータ

dvCreaseAngle
ラジアン単位の、新しい法線を生成できる面同士の最小可能角度。
dwFlags
以下の値の1つ。
D3DRMGENERATENORMALS_PRECOMPACT (dwFlags = 1)
法線の生成前に、アルゴリズムは、メッシュの頂点をコンパクトにするべきかを指定するようになっている。下の「注意」を参照すること。
D3DRMGENERATENORMALS_USECREASEANGLE (dwFlags = 2)
dvCreaseAngleパラメータを使用することを指定する。指定しないと、折り目角は無視される。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、IDirect3DRMMeshBuilder2::GenerateNormals2を置換する。D3DRMGENERATENORMALS_PRECOMPACTフラグを指定すると、プリコンパクトパスは、メッシュ中のすべての頂点を検索し、同じ頂点をすべてマージする。これは、ロードされているメッシュをコンパクトにするのに賢明な方法である。メッシュの中には、頂点に複数の法線を持つ場合に、複数の頂点を持つものがある。これは、Direct3D保持モードでは必要とならない。このフラグの指定は、複数の頂点を除去する場合の定番的方法である。

コンパクト処理の後、法線が生成される。面同士の間の辺が調べられ、面が辺でなす角度が、折り目角より小さい場合には、面法線は平均化され、頂点法線が生成される。角度が折り目角より大きい場合には、新しい法線が生成される。新しい頂点は、生成されないことに注意する。

IDirect3DRMMeshBuilder3::GetBox

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトを含む境界ボックスを取得する。境界ボックスは、各次元での最小、最大のモデル座標を与える。

構文

HRESULT GetBox(
  D3DRMBOX *lpD3DRMBox
  );

パラメータ

lpD3DRMBox
境界ボックスの座標がセットされるD3DRMBOX構造体のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::GetColorSource

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの色ソースを取得する。色ソースは、面でも頂点でも良い。

構文

D3DRMCOLORSOURCE GetColorSource( );

戻り値

D3DRMCOLORSOURCE列挙型のメンバを返す。

参照

IDirect3DRMMeshBuilder3::SetColorSource

IDirect3DRMMeshBuilder3::GetEnable

IDirect3DRMMeshBuilder3

このDirect3DRMMeshBuilder3オブジェクトを有効にするか無効にするかを示す値を取得する。

構文

HRESULT GetEnable(
  LPDWORD lpdwFlags);

パラメータ

lpdwFlags
このDirect3DRMMeshBuilder3オブジェクトの現在の有効状態を示すフラグを受け取るポインタ。現在定義されているフラグは、次の通りである。
D3DRMADDMESHBUILDER_PICKENABLE
このDirect3DRMMeshBuilder3オブジェクト上では、ピッキングが有効になっている。このフラグはデフォルトでセットされる。
D3DRMADDMESHBUILDER_RENDERENABLE
このDirect3DRMMeshBuilder3オブジェクト上では、レンダリングが有効になっている。このフラグはデフォルトでセットされる。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

Enable

IDirect3DRMMeshBuilder3::GetFace

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの単一面を取得する。

構文

HRESULT GetFace(
  DWORD dwIndex,
  LPDIRECT3DRMFACE2 *lplpD3DRMFace2
  );

パラメータ

dwIndex
取得するメッシュ面のインデックス。この面はDirect3DRMMeshBuilder3オブジェクトの一部になっていなければならない。
lplpD3DRMFace2
IDirect3DRMFace2インターフェイスへのポインタのアドレス。面のアドレスがセットされる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::GetFaceCount

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの面の数を取得する。

構文

int GetFaceCount( );

戻り値

面の数を返す。

IDirect3DRMMeshBuilder3::GetFaces

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの面を取得する。

構文

HRESULT GetFaces(
  LPDIRECT3DRMFACEARRAY *lplpD3DRMFaceArray
  );

パラメータ

lplpD3DRMFaceArray
IDirect3DRMFaceArrayインターフェイスへのポインタのアドレス。面のアドレスがセットされる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::GetGeometry

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの頂点、法線、面データを取得する。

構文

HRESULT GetGeometry(
  DWORD *vcount,
  D3DVECTOR *vertices,
  DWORD *ncount,
  D3DVECTOR *normals,
  DWORD *face_data_size,
  DWORD *face_data
  );

パラメータ

vcount
頂点の数が入っている変数のアドレス。
vertices
Direct3DRMMeshBuilder3オブジェクトの頂点を含むD3DVECTOR構造体の配列のアドレス。このパラメータがNULLならば、このメソッドはvcountパラメータ中に頂点の数を返す。
ncount
法線の数が入っている変数のアドレス。
normals
Direct3DRMMeshBuilder3オブジェクトの法線を含むD3DVECTOR構造体の配列のアドレス。このパラメータがNULLならば、このメソッドはncountパラメータ中に法線の数を返す。
face_data_size
パラメータがポイントするバッファのサイズを指定する変数のアドレス。サイズはDWORD値の単位で与えられる。このパラメータはNULLにセットできない。
face_data
Direct3DRMMeshBuilder3オブジェクトの面データのアドレス。このデータは、NULLで終わる点を除いて、IDirect3DRMMeshBuilder3::AddFacesメソッドで指定されたフォーマットと同じである。このパラメータがNULLならば、このメソッドはface_data_sizeパラメータ中に面データバッファの必要サイズの数を返す。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

このメソッドは、DirectX version 6.0とともに導入された。IDirect3DRMMeshBuilderとIDirect3DRMMeshBuilder2インターフェイスは、GetVerticesメソッドを介してこの機能を提供する。旧のメソッドの名前はGetGeometryに変更になるとともに、IDirect3DRMMeshBuilder3インターフェイスではこのメソッドで行うことを記述し、新しいGetVerticesメソッドとの衝突を避けることができる。

IDirect3DRMMeshBuilder3::GetNormal

IDirect3DRMMeshBuilder3

法線ベクトルを取得する。

構文

HRESULT GetNormal
(DWORD dwIndex,
LPD3DVECTOR lpVector);

パラメータ

dwIndex
返す法線のインデックス。
lpVector
法線のx、y、z座標がセットされるD3DVECTOR構造体へのポインタ。

戻り値

次の値のうち1つを返す。
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMeshBuilder3::GetNormalCount

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクト中の法線の数を返す。

構文

DWORD GetNormalCount(void);

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

GetNormals, SetNormals

IDirect3DRMMeshBuilder3::GetNormals

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクト中で以前に定義した法線の配列を取得する。

構文

HRESULT GetNormals(
  DWORD dwFirst,
  LPDWORD lpdwCount,
  LPD3DVECTOR lpdvVector);

パラメータ

dwFirst
返される最初の法線のインデックス。
lpdwCount
返される予定の法線数を含むDWORDへのポインタ。lpdvVectorがNULLならば、このパラメータはdwFirstで与えられるインデックスを起点にした使用可能な法線数を受け取る。lpdvVectorがNULLでない場合、このパラメータには実際に取り出された法線数が入る。dwFirstから始まるすべての使用可能な法線を確実に受け取るには、lpdvVectorをNULLにセットしてこのメソッドを呼び出す。次に、lpdwCount 中に返された値を使用して、lpdvVector中の配列のサイズを計り、再度このメソッドを呼び出す。
lpdvVector
法線データを受け取るベクトルの配列へのポインタ。

戻り値

次の値のうち1つを返す。
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

GetNormalCount, SetNormals

IDirect3DRMMeshBuilder3::GetParentMesh

IDirect3DRMMeshBuilder3

このDirect3DRMMeshBuilder3オブジェクトの親メッシュを取得する。現在のメッシュがサブメッシュでなければ、このメソッドは自分のIUnknownインターフェイスへのポインタを取得する。

構文

HRESULT GetParentMesh(
  DWORD dwFlags,
  LPUNKNOWN  *lplpUnk);

パラメータ

dwFlags
どのDirect3DRMMeshBuilder3オブジェクトを取得するかを定義するフラグ値。現在定義されているフラグは、次の通りである。
D3DRMMESHBUILDER_DIRECTPARENT
このDirect3DRMMeshBuilder3オブジェクトの直接の親。
D3DRMMESHBUILDER_ROOTMESH
親を持たない子のDirect3DRMMeshBuilder3オブジェクトの最終の親。
lplpUnk
親のIUnknownインターフェイスを受け取るポインタのアドレス。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

GetSubMeshes

IDirect3DRMMeshBuilder3::GetPerspective

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに対して、パースペクティブ補正がオンであるかどうかを判別する。

構文

BOOL GetPerspective( );

戻り値

パースペクティブ補正がオンの場合はTRUE、オンでない場合はFALSEを返す。

IDirect3DRMMeshBuilder3::GetQuality

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのレンダリングクオリティを取得する。

構文

D3DRMRENDERQUALITY GetQuality( );

戻り値

メッシュのレンダリングクオリティを指定するD3DRMRENDERQUALITY列挙型のメンバを返す。

参照

IDirect3DRMMeshBuilder3::SetQuality

IDirect3DRMMeshBuilder3::GetSubMeshes

IDirect3DRMMeshBuilder3

このDirect3DRMMeshBuilder3オブジェクトに含まれるサブメッシュのリストを取得する。

構文

HRESULT GetSubMeshes(
  LPDWCOUNT lpdwCount,
  LPUNKNOWN lpUnk);

パラメータ

lpdwCount
返される予定のIUnknownインターフェイスポインタ数を含むDWORD値を指すポインタ。lpUnkがNULLならば、lpdwCountがポイントする値は使用可能なポインタ数を受け取る。そうでない場合は、lpdwCountがポイントする値は実際に取り出されたIUnknownポインタ数を受け取る。
lpUnk
子サブメッシュに対するIUnknownポインタの配列。

戻り値

次の値のうち1つを返す。
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

GetParentMesh

IDirect3DRMMeshBuilder3::GetTextureCoordinates

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点のテクスチャ座標を取得する。

構文

HRESULT GetTextureCoordinates(
  DWORD index,
  D3DVALUE *lpU,
  D3DVALUE *lpV
  );

パラメータ

index
頂点のインデックス。
lpU, lpV
メソッドが戻ったとき、頂点のテクスチャ座標がセットされる変数のアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMeshBuilder3::SetTextureCoordinates

IDirect3DRMMeshBuilder3::GetVertex

IDirect3DRMMeshBuilder3

頂点ベクトルを取得する。

構文

HRESULT GetVertex
(DWORD dwIndex,
LPD3DVECTOR lpVector);

パラメータ

dwIndex
返す頂点のインデックス。
lpVector
頂点のx、y、z座標がセットされるD3DVECTOR構造体へのポインタ。

戻り値

次の値のうち1つを返す。
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMeshBuilder3::GetVertexColor

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の色を返す。

構文

D3DCOLOR GetVertexColor(
  DWORD index
  );

パラメータ

index
頂点のインデックス。

戻り値

色を返す。

参照

IDirect3DRMMeshBuilder3::SetVertexColor

IDirect3DRMMeshBuilder3::GetVertexCount

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクト中の頂点の数を取得する。

構文

int GetVertexCount( );

戻り値

頂点の数を返す。

IDirect3DRMMeshBuilder3::GetVertices

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに対する頂点、法線、面データを取得する。

構文

HRESULT GetVertices(
  DWORD dwFirst,
  LPDWORD lpdwCount,
  LPD3DVECTOR lpdvVector);

パラメータ

dwFirst
返される最初の頂点のインデックス。
lpdwCount
返される予定のベクトル数を含むDWORD値へのポインタ。lpdvVectorがNULLならば、DWORD値は所定のオフセットから使用可能な頂点数を受け取る。そうでない場合、DWORD値は実際に取り出されたベクトル数を受け取る。
lpdvVector
頂点データで初期化されるベクトルの配列へのポインタ。

戻り値

次の値のうち1つを返す。
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入され、旧のIDirect3DRMMeshBuilderとIDirect3DRMMeshBuilder2インターフェイスが提供したGetVerticesメソッドとは異なる。IDirect3DRMMeshBuilder3については、旧のメソッドの名前はその機能をよりよく表すGetGeometryに変更された。

参照

SetVertices, GetGeometry

IDirect3DRMMeshBuilder3::Load

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトをロードする。

構文

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpvArg
  );

パラメータ

lpvObjSource
ロードするオブジェクトのソース。d3drmLOFlagsパラメータで指定されているソースフラグによって、このソースはファイル、リソース、メモリブロック、またはストリームにできる。
lpvObjID
ロードするオブジェクトの名前または位置。このパラメータの使用は、d3drmLOFlagsパラメータで指定されている識別フラグに依存する。D3DRMLOAD_BYPOSITIONフラグが指定されていれば、このパラメータは、ファイル中のオブジェクトの順を与えるDWORD値へのポインタとなる。このパラメータはNULLにできる。
d3drmLOFlags
ロードオプションを記述するD3DRMLOADOPTIONS型の値。
d3drmLoadTextureProc
D3DRMLOADTEXTURE3CALLBACKコールバック関数。特殊なフォーマッティングを必要とするオブジェクトによって使用される、任意のテクスチャをロードするために使われる。このパラメータはNULLにできる。
lpvArg
D3DRMLOADTEXTURE3CALLBACKコールバック関数に渡されるアプリケーション定義データのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

デフォルトでは、このメソッドはlpvObjSourceパラメータで指定されているソースから最初のメッシュをロードする。

このメソッドは、IDirect3DRM3::SetOptionsがセットする右手と左手ジオメトリオプションを考慮する。

そのロードメソッドを複数回を呼び出すことで、複数のオブジェクトをロードすることができる。


IDirect3DRMMeshBuilder3

IDirect3DRMMeshBuilder3メソッドN～Z

この項は、IDirect3DRMMeshBuilder3インターフェイスのメソッドのうち、メソッド名がNからZのものをとりあげるリファレンスページである。

IDirect3DRMMeshBuilder3::Optimize

IDirect3DRMMeshBuilder3

現在のデバイスに対してMeshBuilderオブジェクトを最適化する。この操作は高価であることに注意すること。

構文

HRESULT Optimize
(DWORD dwFlags);

パラメータ

dwFlags
0でなければならない。

戻り値

次の値のうち1つを返す。
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

IDirect3DRMMeshBuilder3::ReserveSpace

IDirect3DRMMeshBuilder3

指定された頂点、法線、および面に対してDirect3DRMMeshBuilder3オブジェクト内のスペースを予約する。これにより、システムがメモリを、より効率的に使用できるようになる。

構文

HRESULT ReserveSpace(
  DWORD vertexCount,
  DWORD normalCount,
  DWORD faceCount
  );

パラメータ

vertexCount, normalCount, faceCount
スペースを割り当てる頂点、法線、および面の数。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::Save

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトを保存する。

構文

HRESULT Save(
  const char * lpFilename,
  D3DRMXOFFORMAT d3drmXOFFormat,
  D3DRMSAVEOPTIONS d3drmSOContents
  );

パラメータ

lpFilename
作成するファイルの名前を指定するアドレス。このファイルのファイル名拡張子は、.xでなければならない。
d3drmXOFFormat
D3DRMXOFFORMAT列挙型のD3DRMXOF_TEXT値。
d3drmSOContents
保存オプションを指定するD3DRMSAVEOPTIONS型の値。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::Scale

IDirect3DRMMeshBuilder3

指定のスケーリングファクタを使用してモデル座標でx軸、y軸、z軸に平行にDirect3DRMMeshBuilder3オブジェクトをスケーリングする。

構文

HRESULT Scale(
  D3DVALUE sx,
  D3DVALUE sy,
  D3DVALUE sz
  );

パラメータ

sx, sy, sz
x軸、y軸、z軸にそって適用されるスケーリングファクタ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetColor

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのすべての面に指定の色を設定する。

構文

HRESULT SetColor(
  D3DCOLOR color
  );

パラメータ

color
面の色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。RGBA_MAKE DirectXマクロによってこれらの値を指定することができる。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetColorRGB

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのすべての面に指定の色を設定する。

構文

HRESULT SetColorRGB(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

パラメータ

red, green, blue
色の赤、緑、青の各成分。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetColorSource

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの色ソースを設定する。

構文

HRESULT SetColorSource(
  D3DRMCOLORSOURCE source
  );

パラメータ

source
使用する新しい色ソース指定するD3DRMCOLORSOURCE列挙型のメンバ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMeshBuilder3::GetColorSource

IDirect3DRMMeshBuilder3::SetMaterial

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのすべての面のマテリアルを設定する。

構文

HRESULT SetMaterial(
  LPDIRECT3DRMMATERIAL2 lpIDirect3DRMmaterial
  );

パラメータ

lpIDirect3DRMmaterial
Direct3DRMMeshBuilder3オブジェクトのIDirect3DRMMaterial2インターフェイスのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetNormal

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の法線ベクトルを設定する。

構文

HRESULT SetNormal(
  DWORD index,
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

パラメータ

index
セットする法線のインデックス。
x, y, z
指定の法線に割り当てるベクトルのx、y、ｚの各要素。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetNormals

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクト中に以前に定義した法線を設定する。

構文

HRESULT SetNormals(
  DWORD dwFirst,
  DWORD dwCount,
  LPD3DVECTOR lpdvVector);

パラメータ

dwFirst
修正する最初の法線のインデックス。
dwCount
修正する法線の数。
lpdvVector
新しい法線データを記述するベクトルの配列。

戻り値

次の値のうち1つを返す。
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

GetNormals

IDirect3DRMMeshBuilder3::SetPerspective

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに対するパースペクティブ補正テクスチャマッピングをイネーブルまたはディセーブルにする。

構文

HRESULT SetPerspective(
  BOOL perspective
  );

パラメータ

perspective
メッシュをパースペクティブ補正でテクスチャマップする必要があればTRUEを、そうでなければFALSEを指定する。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetQuality

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトに対するレンダリングクオリティを設定する。

構文

HRESULT SetQuality(
  D3DRMRENDERQUALITY quality
  );

パラメータ

quality
使用する新しいレンダリングクオリティを指定するD3DRMRENDERQUALITY列挙型のメンバ。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

オブジェクトクオリティには、3つのコンポーネントがある。すなわち、シェーディングモード (フラットまたはグーロー。フォンは実装されておらず、デフォルトでグーローシェーディングになる)、照明タイプ (オンまたはオフ) および塗りつぶしモード (ポイント、ワイヤフレームまたはソリッド) である。

デバイスのクオリティを設定するには、IDirect3DRMDevice3::SetQualityを用いる。デフォルトで、デバイスクオリティはD3DRMRENDER_FLAT (フラットシェーディング、照明オンおよびソリッド塗りつぶし) である。

Direct3DRMMeshBuilder3オブジェクトのクオリティを設定するには、SetQualityメソッドを用いる。デフォルトで、Direct3DRMMeshBuilder3オブジェクトのクオリティはD3DRMRENDER_GOURAUD (グーローシェーディング、照明オンおよびソリッド塗りつぶし) である。

ヒント: グーローシェーディングは、詳細レベルを頻繁にまたは素早く変更するプログレッシブメッシュオブジェクトについて、フォンシェーディングよりもよいパフォーマンスを得られる。

Direct3D保持モードは、デバイスやオブジェクトの個々のコンポーネントに対する現在の設定の中で最も低位のクオリティで、オブジェクトにレンダリングを行う。たとえば、オブジェクトの現在のクオリティ設定がD3DRMRENDER_GOURAUDで、デバイスがD3DRMRENDER_FLATであると、オブジェクトはフラットシェーディング、ソリッド塗りつぶし、および照明オンでレンダリングされる。

オブジェクトの現在のクオリティ設定がD3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAMEで、デバイスのクオリティ設定がD3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINTであると、オブジェクトはフラットシェーディング、照明オフ、およびポイント塗りつぶしモードでレンダリングされる。

これらのルールは、Direct3DRMMeshBuilder3オブジェクトおよびDirect3DRMProgressiveMeshオブジェクトに適用される。しかし、Direct3DRMMeshオブジェクトはこれらのルールに従わない。メッシュオブジェクトはデバイスのクオリティ設定を無視し、グループクオリティ設定を用いる(デフォルトでD3DRMRENDER_GOURAUD)。

参照

IDirect3DRMMeshBuilder3::GetQuality

IDirect3DRMMeshBuilder3::SetTexture

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのすべての面のテクスチャを設定する。

構文

HRESULT SetTexture(
  LPDIRECT3DRMTEXTURE3 lpD3DRMTexture
  );

パラメータ

lpD3DRMTexture
必要なDirect3DRMTextureオブジェクトのアドレス。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetTextureCoordinates

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点のテクスチャ座標を設定する。

構文

HRESULT SetTextureCoordinates(
  DWORD index,
  D3DVALUE u,
  D3DVALUE v
  );

パラメータ

index
セットする頂点のインデックス。
u, v
指定のメッシュ頂点に割り当てるテクスチャ座標。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMeshBuilder3::GetTextureCoordinates

IDirect3DRMMeshBuilder3::SetTextureTopology

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトのテクスチャトポロジーを設定する。

構文

HRESULT SetTextureTopology(
  BOOL cylU,
  BOOL cylV
  );

パラメータ

cylU, cylV
円筒形トポロジーを、それぞれu次元およびv次元でテクスチャに持たせたい場合、この2つのパラメータの、少なくとも一方にTRUEを、そうでない場合には、FALSEを指定する。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

注意

テクスチャトポロジーフラグ、cylUとcylVは Direct3D直接モードレンダリング状態D3DRENDERSTATE_WRAPU、D3DRENDERSTATE_WRAPVの設定を制御する。ラッピングフラグがTRUEのとき、ラスタライザは、それが2つのテクスチャ座標間で短いほうのパスであれば、テクスチャの1つの辺から反対側の辺に横断 (トロイダル マッピング) する。1つの辺に沿って0.1から0.9の範囲のv座標を持つ三角形があるとする。WRAPVがFALSEであれば、テクスチャのほぼ全長が三角形に沿ってレンダリングされる。WRAPVがTRUEであれば、テクスチャの上部と下部のスライバがレンダリングされる。さらに、ラッピングフラグがTRUEのとき、テクスチャ座標の一部分だけが1.0より大きい値を持つとみなされるため、ラップがTRUEのときテクスチャは面に沿ってタイル化されないことになる。

ラッピング動作の制御は、テクスチャ座標の正しい解釈にとって必要である。単一のテクスチャが多くの面に沿ってラップされている場合、cylUとcylVパラメータをTRUEにセットする。モデルが面当たり1つのテクスチャしか持たないか、または1より大きいテクスチャ座標を使用してテクスチャの複数のコピーを単一の面に沿ってタイル化する場合、cylUとcylVをFALSEにセットする。

いくつかのインターフェイスは、SetTextureTopologyメソッドをエクスポーズする。IDirect3DRMMeshBuilder3::SetTextureTopologyは、すべての要素面上のトポロジーを更新し、IDirect3DRMFace2::SetTextureTopologyによる設定をオーバーライドする。デフォルトでは、IDirect3DRMFrame3::SetTextureは、デフォルトのマテリアルモードがD3DRMMATERIAL_FROMMESHであるため、メッシュを読み込む。マテリアルモードがD3DRMMATERIAL_FROMMESHでない場合、IDirect3DRMFrame3::SetTextureはIDirect3DRMMeshBuilder3::SetTextureTopologyによる設定をオーバーライドする。

IDirect3DRMMeshBuilder3::SetVertex

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の位置を設定する。

構文

HRESULT SetVertex(
  DWORD index,
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

パラメータ

index
セットする頂点のインデックス。
x, y, z
指定の頂点に割り当てる位置のx、y、zの各要素。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetVertexColor

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の色を設定する。

構文

HRESULT SetVertexColor(
  DWORD index,
  D3DCOLOR color
  );

パラメータ

index
セットする頂点のインデックス。
color
指定の頂点に割り当てる色。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

参照

IDirect3DRMMeshBuilder3::GetVertexColor

IDirect3DRMMeshBuilder3::SetVertexColorRGB

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの指定されている頂点の色を設定する。

構文

HRESULT SetVertexColorRGB(
  DWORD index,
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

パラメータ

index
セットする頂点のインデックス。
red, green, blue
指定の頂点に割り当てる色の赤、緑、青の各成分。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。

IDirect3DRMMeshBuilder3::SetVertices

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクト中に以前に定義した頂点を設定する。

構文

HRESULT SetVertices(
  DWORD dwFirst,
  DWORD dwCount,
  LPD3DVECTOR lpdvVector);

パラメータ

dwFirst
修正する最初の頂点のインデックス。
dwCount
修正する頂点の数。
lpdvVector
新しい頂点データを記述するベクトルの配列。

戻り値

次の値のうち1つを返す。
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

注意

このメソッドは、DirectX version 6.0とともに導入された。

参照

GetVertices

IDirect3DRMMeshBuilder3::Translate

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3オブジェクトの頂点の位置に指定のオフセットを加算する。

構文

HRESULT Translate(
  D3DVALUE tx,
  D3DVALUE ty,
  D3DVALUE tz
  );

パラメータ

tx, ty, tz
各頂点位置のx座標、y座標、z座標に追加されるオフセット。

戻り値

成功すればD3DRM_OK、失敗すればエラーを返す。エラーのリストについては、「Direct3D保持モードの戻り値」を参照すること。


Direct3DRMFrame3メソッドA～M

この項は、Direct3DRMFrame3インターフェイスのメソッドのうち、メソッド名がAからMのものをとりあげるリファレンスページである。

Direct3DRMFrame3.AddChild

Direct3DRMFrame3

子フレームをフレーム階層に追加する。

構文

object.AddChild(child As Direct3DRMFrame3)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
child
子として追加するDirect3DRMFrame3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

子として追加するフレームに、既に親フレームが存在する場合には、このメソッドは、そのフレームを現在の親から削除した後に新しい親に追加する。

オブジェクトの変換を保存するためには、Direct3DRMFrame3.GetTransformメソッドを使ってAddChildメソッドを使う前にオブジェクトの変換を取得する。その後、フレームが追加された後でその変換を再適用する。

Direct3DRMFrame3.AddLight

Direct3DRMFrame3

照明をフレームに追加する。

構文

object.AddLight(val As Direct3DRMLight)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
val
フレームに追加するDirect3DRMLightオブジェクトを表す変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.AddMoveCallback

Direct3DRMFrame3

特殊な運動の処理用にコールバックを追加する。フレームの移動時または更新時に、このコールバックが呼び出される。

構文

object.AddMoveCallback(frameMoveImplementation As Direct3DRMFrameCallback3
  userArgument As object,
  flags As CONST_D3DRMCALLBACKORDERFLAGS)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
frameMoveImplementation
アプリケーションによって実装されるDirect3DRMFrameCallback3インターフェイス。
userArgument
コールバックに渡されるアプリケーション定義のデータ。
flags
CONST_D3DRMCALLBACKORDERFLAGS列挙型からの1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMFrame2.AddMoveCallback2を置換する。個々のフレームに対する複数のコールバックは、コールバックの作成順に呼び出される。

参照

Direct3DRMFrame3.DeleteMoveCallback

Direct3DRMFrame3.AddRotation

Direct3DRMFrame3

特定の座標についての回転を指定されたラジアンで追加する。

構文

object.AddRotation(combineType As CONST_D3DRMCOMBINETYPE,
  x As Single,
  y As Single,
  z As Single,
  theta As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
combineType
新しい回転を現在の任意のフレーム変換と結合する方法を指定するCONST_D3DRMCOMBINETYPE列挙型のメンバ。
x, y, z
回転軸。
theta
ラジアン単位の回転角。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

指定の回転は、このDirect3DRMFrame3インターフェイスが識別するフレームに対する行列だけを変更する。このメソッドは、レンダリング毎に行列を変更するDirect3DRMFrame3.SetRotationとは異なりフレームを一度しか変更しない。

Direct3DRMFrame3.AddScale

Direct3DRMFrame3

フレームのローカル変換を特定の座標でスケーリングする。

構文

object.AddScale(combineType As CONST_D3DRMCOMBINETYPE,
  sx As Single,
  sy As Single,
  sz As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
combineType
新しいスケールを現在の任意のフレーム変換と結合する方法を指定するCONST_D3DRMCOMBINETYPE列挙型のメンバ。
sx, sy, sz
x、y、zの各方向のスケール係数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

指定の変換は、このDirect3DRMFrame3インターフェイスが識別するフレームに対する行列だけを変更する。

Direct3DRMFrame3.AddTransform

Direct3DRMFrame3

指定されたアフィン変換でフレームのローカル座標を変換する。

構文

object.AddTransform(t As CONST_D3DRMCOMBINETYPE,
  val() As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
t
新しい変換を現在の任意の変換と結合する方法を指定するCONST_D3DRMCOMBINETYPE列挙型のメンバ。
val
4×4行列を表す列順の配列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

4×4行列が与えられたが、変換がアフィン変換であるためには、最後の列は[0 0 0 1]の転調でなければならない。指定の変換は、このDirect3DRMFrame3インターフェイスが識別するフレームに対する行列だけを変更する。

Direct3DRMFrame3.AddTranslation

Direct3DRMFrame3

フレームのローカル座標系に特定の位置変更による平行移動を追加する。

構文

object.AddTranslation(t As CONST_D3DRMCOMBINETYPE,
  x As Single,
  y As Single,
  z As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
t
新しい変換を現在の任意の変換と結合する方法を指定するCONST_D3DRMCOMBINETYPE列挙型のメンバ。
x, y, z
x、y、zの各方向での位置変化を定義する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

指定の変換は、このDirect3DRMFrame3インターフェイスが識別するフレームに対する行列だけを変更する。

Direct3DRMFrame3.AddVisual

Direct3DRMFrame3

ビジュアルオブジェクトをフレームに追加する。

構文

object.AddVisual(v As Direct3DRMVisual)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
v
フレームに追加するDirect3DRMVisualオブジェクトを表す変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

ビジュアルオブジェクトには、メッシュ、プログレッシブメッシュ、テクスチャ、影、ユーザビジュアル、および 3-D Microsoft® DirectX® 変換オブジェクトが含まれる。ビジュアルオブジェクトがフレームに追加されると、ビジュアルオブジェクトは、フレームがビュー中にある場合に可視状態になる。フレームはビジュアルオブジェクトを参照する。

Direct3DRMFrame3.DeleteChild

Direct3DRMFrame3

階層からフレームを削除する。そのフレームが参照されていなければ、子フレーム、照明、およびメッシュのすべてが共に破棄される。

構文

object.DeleteChild(c As Direct3DRMFrame3)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
c
階層から削除されるDirect3DRMFrame3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.DeleteLight

Direct3DRMFrame3

フレームから照明を削除し、フレームが参照されることがなければ破棄する。照明がフレームから削除されると、そのフレームがあったシーンの中のメッシュに以降影響することはない。

構文

object.DeleteLight(l As Direct3DRMLight)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
l
削除するDirect3DRMLightオブジェクトを表す変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.DeleteMoveCallback

Direct3DRMFrame3

AddMoveCallbackによって追加されたフレーム移動コールバックを削除する。

構文

object.DeleteMoveCallback(frameMoveImplementation As Direct3DRMFrameCallback3,
  userArgument As object)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
frameMoveImplementation
アプリケーションによって実装されるDirect3DRMFrameCallback3インターフェイス。
userArgument
コールバックに渡されたアプリケーション定義のデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.Move

Direct3DRMFrame3.DeleteVisual

Direct3DRMFrame3

ビジュアルオブジェクトをフレームから削除し、以降参照されない場合には破棄する。

構文

object.DeleteVisual(v As Direct3DRMVisual)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
v
削除するDirect3DRMVisualオブジェクトを表す変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

ビジュアルオブジェクトには、メッシュ、プログレッシブメッシュ、テクスチャ、影、ユーザビジュアル、および3D DirectX変換オブジェクトが含まれる。ビジュアルオブジェクトがフレームに追加されると、ビジュアルオブジェクトは、フレームがビュー中にある場合に可視状態になる。フレームはビジュアルオブジェクトを参照する。

Direct3DRMFrame3.GetAxes

Direct3DRMFrame3

Direct3DRMFrame3.SetOrientationメソッドに供給される方向ベクトル (dx, dy, dz) とアップベクトル (ux, uy, uz) と整列するベクトルを取得する。

構文

object.GetAxes(dir As D3DVECTOR,
  up As D3DVECTOR)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
dir
フレームのz軸。デフォルトは(0,0,1)である。
up
フレームのy軸。デフォルトは(0,1,0)である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMFrame3.SetAxesと共に働き、左手座標系と右手座標系の両方を支援する。SetAxesは、負のz軸がオブジェクトの前面を表すように指定することを可能にする。

参照

Direct3DRMFrame3.GetInheritAxes、Direct3DRMFrame3.SetInheritAxes、 D3DVECTOR

Direct3DRMFrame3.GetBox

Direct3DRMFrame3

Direct3DRMFrame3オブジェクトを含む境界ボックスを取得する。境界ボックスは、各次元での最小および最大のモデル座標を与える。

構文

object.GetBox(box As D3DRMBOX)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
box
境界ボックス座標を取得するD3DRMBOX型。

エラー値

有効な境界ボックスが既にフレームにセットされていない限り、D3DRMERR_BOXNOTSETを返す。エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、階層的選別に対するフレーム上の境界ボックスをサポートする。有効な境界ボックスは、Direct3DRMFrame3.SetBoxメソッドでフレーム上に設定する必要がある。境界ボックスを有効にするには、Direct3DRMFrame3.SetBoxEnableメソッドを使ってイネーブルフラグをD_TRUEにする必要がある。デフォルトで、ボックスイネーブルフラグはFALSEである。デフォルトの境界ボックスはない。

参照

Direct3DRMFrame3.GetBoxEnable

Direct3DRMFrame3.GetBoxEnable

Direct3DRMFrame3

境界ボックスがこのDirect3DRMFrame3オブジェクトに対して、イネーブルになっているかどうかを判別するフラグを取得する。

構文

object.GetBoxEnable( ) As CONST_DBOOLFLAGS

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

境界ボックスがイネーブルであれば–1、イネーブルでなければ0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

境界ボックスをイネーブルにするには、Direct3DRMFrame3.SetBoxEnableメソッドを使ってイネーブルフラグをD_TRUEにする必要がある。デフォルトでは、ボックスイネーブルフラグはD_FALSEである。

参照

Direct3DRMFrame3.GetBox, Direct3DRMFrame3.SetBox

Direct3DRMFrame3.GetChildren

Direct3DRMFrame3

Direct3DRMFrameArrayオブジェクトの形式で、子フレームのリストを取得する。

構文

object.GetChildren( ) As Direct3DRMFrameArray

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMFrameArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetColor

Direct3DRMFrame3

フレームの色を取得する。

構文

object.GetColor( ) As Long

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMFrame3オブジェクトの色を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetColor

Direct3DRMFrame3.GetHierarchyBox

Direct3DRMFrame3

このDirect3DRMFrame3オブジェクトをルートとする階層中のすべての幾何図形を含む境界ボックスを計算する。

構文

object.GetHierarchyBox(box As D3DRMBOX)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
box
境界ボックスの座標を取得するD3DRMBOX型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.GetBox、Direct3DRMFrame3.SetBox、Direct3DRMFrame3.SetBoxEnable、Direct3DRMFrame3.GetBoxEnable

Direct3DRMFrame3.GetInheritAxes

Direct3DRMFrame3

フレームの軸が親フレームから継承したものであるかどうかを示すフラグを取得する。

構文

object.GetInheritAxes( ) As CONST_DBOOLFLAGS

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

フレームが軸を継承すると–1を返し (デフォルト)、継承しないと0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デフォルトでは、軸は親から継承したものである。フレームに親からの継承と設定されていて、親が存在しなければ、フレームはデフォルト軸（方向=(0,0,1)アップ=(0,1,0)）を持つ親から継承したように動作する。

このメソッドおよびDirect3DRMFrame3.SetInheritAxesメソッドは、階層のルートで設定される軸の単一の方針を許す。

参照

Direct3DRMFrame3.GetAxes、Direct3DRMFrame3.SetAxes

Direct3DRMFrame3.GetLights

Direct3DRMFrame3

Direct3DRMLightArrayオブジェクトの形式でフレーム中の照明のリストを取得する。

構文

object.GetLights( ) As Direct3DRMLightArray

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMLightArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetMaterial

Direct3DRMFrame3

Direct3DRMFrame3オブジェクトのマテリアルを取得する。

構文

object.GetMaterial(ret As Direct3DRMMaterial2)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
ret
フレームに適用されるDirect3DRMMaterial2オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetMaterial

Direct3DRMFrame3.GetMaterialMode

Direct3DRMFrame3

フレームのマテリアルモードを取得する。

構文

object.GetMaterialMode( ) As CONST_D3DRMMATERIALMODE

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

現在のマテリアルモードを指定するCONST_D3DRMMATERIALMODE列挙型のメンバを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3.GetMaterialOverride

Direct3DRMFrame3

マテリアル属性に対する現在の属性ごとのオーバーライド設定を取得する。

構文

object.GetMaterialOverride(override As D3DRMMATERIALOVERRIDE)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
override
オーバーライド情報を持つD3DRMMATERIALOVERRIDE型。

エラー値

メソッドが失敗した場合は、DDERR_INVALIDOBJECTまたはDDERR_INVALIDPARAMSを返す。

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetMaterialOverride

Direct3DRMFrame3.GetMaterialOverrideTexture

Direct3DRMFrame3

オーバーライドテクスチャを取得する。

構文

object.GetMaterialOverrideTexture( ) As Direct3DRMTexture3

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

オーバーライドテクスチャがある場合は、Direct3DRMTexture3オブジェクトを返す。そうでなければ、NOTHINGを返す。

エラー値

メソッドが失敗した場合、DDERR_INVALIDOBJECTまたはDDERR_INVALIDPARAMSを返す。

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。.

参照

Direct3DRMFrame3.SetMaterialOverrideTexture

Direct3DRMFrame3.GetOrientation

Direct3DRMFrame3

指定の参照フレームを基準とするフレームの方向を取得する。

構文

object.GetOrientation(ref As Direct3DRMFrame3,
  dir As D3DVECTOR,
  up As D3DVECTOR)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
ref
参照に使用されるDirect3DRMFrame3オブジェクトを表す変数。
dir, up
それぞれフレームのz軸およびy軸の正規化された方向が設定されたD3DVECTOR型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetOrientation

Direct3DRMFrame3.GetParent

Direct3DRMFrame3

現在のフレームの親フレームを取得する。

構文

object.GetParent( ) As Direct3DRMFrame3

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMFrame3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetPosition

Direct3DRMFrame3

指定の参照フレームを基準とするフレームの位置を取得する。つまり、参照フレームからのフレームの距離を取得する。距離は、直線的な値ではなく、ベクトルとしてpositionパラメータに格納される。

構文

object.GetPosition(ref As Direct3DRMFrame3,
  position As D3DVECTOR)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
ref
参照として使用されるDirect3DRMFrameオブジェクトを表す変数。
position
フレームの位置がセットされるD3DVECTOR型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetPosition

Direct3DRMFrame3.GetRotation

Direct3DRMFrame3

指定の参照フレームを基準とするフレームの回転を取得する。

構文

object.GetRotation(ref As Direct3DRMFrame3,
  axis As D3DVECTOR,
  theta As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
ref
参照として使用されるDirect3DRMFrame3オブジェクトを表す変数。
axis
フレームの回転軸がセットされるD3DVECTOR型。
theta
ラジアン単位のフレームの回転となる変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetRotation

Direct3DRMFrame3.GetScene

Direct3DRMFrame3

指定のフレームを含む階層のルートフレームを取得する。

構文

object.GetScene( ) As Direct3DRMFrame3

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMFrame3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetSceneBackground

Direct3DRMFrame3

シーンの背景色を取得する。

構文

object.GetSceneBackground( ) As Long

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

色を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetSceneBackgroundDepth

Direct3DRMFrame3

シーンの現在の背景深度バッファを取得する。

構文

object.GetSceneBackgroundDepth( ) As DirectDrawSurface4

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

DirectDrawSurface4オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetSceneBackgroundDepth

Direct3DRMFrame3.GetSceneFogColor

Direct3DRMFrame3

シーンのフォグ色を取得する。

object.GetSceneFogColor( ) As Long

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

フォグ色を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetSceneFogEnable

Direct3DRMFrame3

現在このシーンに対してフォグがイネーブルされているかどうかを取得する。

構文

object.GetSceneFogEnable( ) As CONST_DBOOLFLAGS

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

フォグがイネーブルされていれば–1、イネーブルされていなければ0を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetSceneFogMethod

Direct3DRMFrame3

現在のフォグメソッドを取得する。

構文

object.GetSceneFogMethod( ) As CONST_D3DRMFOGMETHOD

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMFOGMETHOD列挙型から値を1つ返す。

エラー値

エラーが発生した場合は、次の値のうちの1つを返す。

  • D3DRMERR_BADVALUE
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

Direct3DRMFrame3.GetSceneFogMode

Direct3DRMFrame3

このシーンに対する現在のフォグモードを返す。

構文

object.GetSceneFogMode( ) As CONST_D3DRMFOGMODE

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

現在のフォグモードを指定するCONST_D3DRMFOGMODE列挙型のメンバを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetSceneFogParams

Direct3DRMFrame3

このシーンに対する現在のフォグパラメータを取得する。

構文

object.GetSceneFogParams(start As Single,
  end As Single,
  density As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
start, end, density
フォグ開始、終了および密度値となる変数。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetSortMode

Direct3DRMFrame3

子フレームを処理するのに使用されるソートモードを取得する。

構文

object.GetSortMode( ) As CONST_D3DRMSORTMODE

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

ソートモードを指定するCONST_D3DRMSORTMODE列挙型のメンバを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetSortMode

Direct3DRMFrame3.GetTexture

Direct3DRMFrame3

指定フレームのテクスチャを取得する。

構文

object.GetTexture( ) As Direct3DRMTexture3

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMTexture3オブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetTexture

Direct3DRMFrame3.GetTransform

Direct3DRMFrame3

フレームのローカル変換を4×4アフィン行列として取得する。

構文

object.GetTransform(referenceFrame As Direct3DRMFrame3
  val() As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
referenceFrame
参照フレームとして使用されるDirect3DRMFrame3オブジェクト。
val
4×4行列を表す列順の配列。

エラー値

エラーが発生した場合は、DDERR_INVALIDOBJECTまたはDDERR_INVALIDPARAMSを返す。

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetTraversalOptions

Direct3DRMFrame3

現在のフレームの横断状態を取得する。

構文

object.GetTraversalOptions( ) As CONST_D3DRMTRAVERALFLAGS

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMTRAVERALFLAGS列挙型から値を1つ返す。

エラー値

エラーが発生した場合は、次の値のうちの1つを返す。

  • D3DRMERR_BADVALUE
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

Direct3DRMFrame3.GetVelocity

Direct3DRMFrame3

指定の参照フレームを基準とするフレームの速度を取得する。速度は、ティック当たりの単位で指定される。詳細については、「IDirect3DRM3.Tick」を参照すること。

構文

object.GetVelocity(ref As Direct3DRMFrame3,
  vel As D3DVECTOR,
  includeRotationalVelocity As CONST_DBOOLFLAGS)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
ref
参照として使用されるDirect3DRMFrame3オブジェクトを表す変数。
vel
フレームの速度がセットされるD3DVECTOR型。
includeRotationalVelocity
D_FALSEまたはD_TRUE。D_TRUEの場合、オブジェクトの回転速度が計算に含まれる。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetVelocity

Direct3DRMFrame3.GetVisual

Direct3DRMFrame3

フレーム中のビジュアルを1つ取得する。

構文

object.GetVisual(index As Long) As Direct3DRMVisual

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
index
取得する単一のDirect3DRMVisualオブジェクトのインデックスを示す変数。サイズNの配列に対して指定できる値の範囲は、0～Nである。

戻り値

Direct3DRMVisualオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetVisualCount

Direct3DRMFrame3

フレーム中のビジュアルの数を取得する。

構文

object.GetVisualCount( ) As Long

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

フレームに含まれるビジュアル数を返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetVisuals

Direct3DRMFrame3

フレーム中のビジュアルのリストを取得する。

構文

object.GetVisuals( ) As Direct3DRMVisualArray

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

Direct3DRMVisualArrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.GetZbufferMode

Direct3DRMFrame3

Zバッファモードを取得する。つまり、Zバッファリングがイネーブルまたはディセーブルであるかどうかを確認する。

構文

object.GetZbufferMode( ) As CONST_D3DRMZBUFFERMODE

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。

戻り値

CONST_D3DRMZBUFFERMODE列挙型のメンバの1つを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetZbufferMode

Direct3DRMFrame3.InverseTransform

Direct3DRMFrame3

ワールド座標の指定ベクトルをモデル座標に変換して、その結果を返す。

構文

object.InverseTransform(d As D3DVECTOR,
  s As D3DVECTOR)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
d
変換の結果がセットされるD3DVECTOR型。
s
変換のソースであるD3DVECTOR型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.Transform

Direct3DRMFrame3.InverseTransformVectors

Direct3DRMFrame3

ベクトルの配列をワールド座標からモデル座標に変換する。

構文

object.GetVelocity(reference As Direct3DRMFrame3,
  num As Long,
  DstVectors() As D3DVECTOR,
  SrcVectors() As D3DVECTOR)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
reference
この呼び出しのためにシーンのルートとして使用されるフレーム。この引数がNOTHINGの場合、現在のルートフレーム (Direct3DRMFrame3.GetSceneが返すフレーム) が使用される。
num
座標を変換する必要があるベクトル数。
DstVectors()
変換の出力先。
SrcVectors()
変換するベクトルの配列。

エラー値

エラーが発生した場合は、DDERR_INVALIDOBJECTまたはDDERR_INVALIDPARAMSを返す。

参照

D3DVECTOR

Direct3DRMFrame3.LoadFromFile

Direct3DRMFrame3

Direct3DRMFrame3オブジェクトをロードする。

構文

object.LoadFromFile(filename As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As Object)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
filename
ロードするオブジェクトのソース。このソースは、flagsパラメータで指定されているソースフラグに従い、ファイル、リソース、メモリブロック、またはストリームのいずれかにできる。
id
ロードするオブジェクトの名前または位置。idが""の場合は、optionsパラメータをD3DRMLOAD_FIRSTに設定する。Microsoft Visual Basic® は、Stringデータ型が指定されている場合でも、ロードするアイテムの位置を示すidパラメータの中のIntegerを受け入れる。たとえば、idパラメータに1が設定されていると、1番目の位置のオブジェクトがロードされる。
options
ロードオプションを記述するCONST_D3DRMLOADFLAGS列挙型の1つ以上の値。
loadTextureImplementation
特殊なフォーマッティングを要求するオブジェクトによって使用される、任意のテクスチャをロードするために呼び出されるDirect3DRMLoadTextureCallback3インターフェイス。テクスチャは、2で割れる幅と長さでなければならない。このパラメータはNOTHINGにできる。
userArgument
コールバックに渡されるアプリケーション定義のデータ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デフォルトでは、このメソッドは、filenameパラメータで指定されているファイル中の最初のフレーム階層をロードする。このメソッドを呼び出したフレームは、新しいフレーム階層の親として使用される。デフォルトでは、パースペクティブ補正がオンである。

インスタンスフラグは、パラメータの解釈方法には何も変更を加えない。D3DRMLOAD_INSTANCEBYREFERENCEフラグを用いると、新しいオブジェクトを作成することなく同じファイルを2回ロードすることができる。オブジェクトが名前を持っていない場合、D3DRMLOAD_INSTANCEBYREFERENCEフラグをセットすると、D3DRMLOAD_INSTANCEBYCOPYINGフラグをセットしたときと同じ効果を得ることができる。ローダは、同一のオブジェクトが存在しても、各名前なしオブジェクトを新しいオブジェクトとして作成する。

Direct3DRMFrame3.LookAt

Direct3DRMFrame3

指定の参照フレームを基準として、指定の制約によって回転をロックした状態でフレームを対象のフレームに直面させる。

構文

object.LookAt(tgt As Direct3DRMFrame3,
  reference As Direct3DRMFrame3,
  contraint As CONST_D3DRMFRAMECONSTRAINT)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
tgt, reference
それぞれ、対象および参照として使用されるDirect3DRMFrame3オブジェクトを表す変数。
contraint
制約する軸回転を指定するCONST_D3DRMFRAMECONSTRAINT列挙型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.Move

Direct3DRMFrame3

直線と回転の速度を指定の階層のすべてのフレームに適用する。

構文

object.Move(delta As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
delta
直線と回転速度に対する変化量。各要素における変更は、その要素の速度× deltaに等しい。これらの一方または両方の速度は、任意のフレームを起点として設定することができるが、システムは、自動的にデルタ時間を適用するので、親フレームを起点とした速度に変換する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。


Direct3DRMFrame3メソッドN～Z

この項は、Direct3DRMFrame3インターフェイスのメソッドのうち、メソッド名がNからZのものをとりあげるリファレンスページである。

Direct3DRMFrame3.RayPick

Direct3DRMFrame3

このDirect3DRMFrame3オブジェクトを起点として階層を検索し、任意のビジュアルと、referパラメータによって参照されるDirect3DRMFrame3インターフェイスで指定される光線との交差部分を計算する。

構文

object.RayPick(refer As Direct3DRMFrame3,
  ray As D3DRMRAY,
  flags As CONST_D3DRMRAYPICKFLAGS) As Direct3DRMPick2Array

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
refer
光線を含むDirect3DRMFrame3オブジェクト。
ray
2つのD3DVECTOR型を含むD3DRMRAY型。最初のD3DVECTOR型は、光線のベクトル方向である。2番目のD3DVECTOR型は、光線の原点の位置である。
flags
計算される交差部分のタイプまたは補間オプションを示すCONST_D3DRMRAYPICKFLAGS列挙型からの1つ以上の値。

戻り値

Direct3DRMPick2Arrayオブジェクトを返す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

フラグには、最適化フラグと補間フラグの2種類がある。最適化フラグは、検索を制限することができ、したがってそれを高速にする。補間フラグは、プリミティブに行き当たったときに何を補間すべきか指定する。3つの補間選択肢は、色、法線およびテクスチャ座標である。

光線は、参照フレーム座標空間で指定される（referが指す）。参照フレームがNOTHINGの場合には、光線は、ワールド座標で指定される。

Direct3DRMFrame3.Save

Direct3DRMFrame3

指定したファイルにDirect3DRMFrame3オブジェクトを保存する。

構文

object.Save(name As String,
  format As CONST_D3DRMXOFFORMAT,
  flags As CONST_D3DRMSAVEFLAGS)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
name
作成したファイルの名前。このファイルは、.xファイル名拡張を持たなければならない。
format
ファイルがテキストフォーマットであることを示すCONST_D3DRMXOFFORMAT列挙型からのD3DRMXOF_TEXT値。
flags
保存オプションを記述するCONST_D3DRMSAVEFLAGS列挙型の1つ以上の値。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.SetAxes

Direct3DRMFrame3

Direct3DRMFrame3.SetOrientationベクトルを変換する座標空間を定義するベクトルを設定する。

構文

object.SetAxes(dx As Single,
  dy As Single,
  dz As Single,
  ux As Single,
  uy As Single,
  uz As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
dx, dy, dz
フレームのz軸。デフォルトは(0,0,1)である。
ux, uy, uz
フレームのy軸。デフォルトは(0,1,0)である。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、左手座標系と右手座標系の両方を支援する。また、負のz軸がオブジェクトの前面を表すように指定することも可能にする。

Direct3DRMFrame3.SetOrientation方向ベクトル (dx, dy, dz) とアップベクトル (ux, uy, uz) は、SetAxesベクトルの値に従って変換される。

Direct3DRMFrame3.SetInheritAxesに指定されているように、軸は子フレームによって継承される。

参照

Direct3DRMFrame3.GetAxes、Direct3DRMFrame3.GetInheritAxes

Direct3DRMFrame3.SetBox

Direct3DRMFrame3

境界ボックステストで使用するボックスを設定する。境界ボックスが有効であるためには、最小xは最大x以下でなければならず、最小yは最大y以下でなければならず、また最小zは最大z以下でなければならない。

構文

object.SetBox(box As D3DRMBOX)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
box
境界ボックス座標を含むD3DRMBOX型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、階層的選別に対するフレーム上の境界ボックスをサポートする。境界ボックスをイネーブルにするには、Direct3DRMFrame3.SetBoxEnableメソッドを使って、イネーブルフラグにD_TRUEをセットしなければならない。デフォルトでは、ボックスイネーブルフラグはD_FALSEである。

参照

Direct3DRMFrame3.GetBox、Direct3DRMFrame3.GetBoxEnable

Direct3DRMFrame3.SetBoxEnable

Direct3DRMFrame3

このDirect3DRMFrame3オブジェクトに対して、境界ボックステストをイネーブルまたはディセーブルする。境界ボックステストをイネーブルにするには、有効な境界ボックスがフレームに既に設定されていなければならない。

構文

object.SetBoxEnable(boxEnable As CONST_DBOOLFLAGS)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
boxEnable
境界ボックスがイネーブルかどうかを指定するフラグ。境界ボックスをイネーブルにするにはD_TRUEを、境界ボックスをディセーブルにするにはD_FALSEを指定する。デフォルトはD_FALSEである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

境界ボックステストは、以下のように行う。レンダリング時には、境界ボックスはモデル空間に変換して、視錐台との交差部分がないか調べる。ボックス全体が視錐台の外にある場合、フレームや子フレームにあるビジュアルのレンダリングは行わない。それ以外の場合は、通常のレンダリングを続ける。

{0,0,0,0}のボックスで境界ボックステストをイネーブルすると、フレームはまったくレンダリングされない。

参照

Direct3DRMFrame3.GetBoxEnable、Direct3DRMFrame3.GetBox、Direct3DRMFrame3.SetBox

Direct3DRMFrame3.SetColor

Direct3DRMFrame3

フレームの色を設定する。この色は、CONST_D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEである場合に、フレーム中のメッシュに対して使用される。

構文

object.SetColor(c As Long)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
c
フレームの新しい色。赤、緑、青の色要素だけでなく、アルファ要素も必ずセットする。そうしないと、オブジェクトが可視にならないことがある。オブジェクトの色をアルファ要素を含めて指定するには、オブジェクト上のDirectX7インターフェイスからCreateColorRGBAメソッドを呼び出す。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.GetColor、Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3.SetColorRGB

Direct3DRMFrame3

フレームの色を設定する。この色は、CONST_D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEである場合に、フレーム中のメッシュに対して使用される。

構文

object.SetColorRGB(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
r, g, b
フレームの新しい色。色の各要素は、0.0から1.0の範囲にある必要がある。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3.SetInheritAxes

Direct3DRMFrame3

フレームの軸が親フレームから継承したものであるかどうかを指定する。

構文

object.SetInheritAxes(inheritFromParent As CONST_DBOOLFLAGS)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
inheritFromParent
フレームがその親から軸を継承するかどうかを示す。D_TRUEの場合、フレームは軸を継承する（デフォルト）。D_FALSEの場合、フレームは軸を継承しない。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

デフォルトでは、軸は親から継承したものである。フレームに親からの継承と設定されていて、親が存在しない場合には、フレームは、デフォルト軸(方向=(0,0,1)アップ=(0,1,0))を持つ親から継承したように動作する。このメソッドは、階層のルートで設定される軸の単一の方針を許す。

参照

Direct3DRMFrame3.GetInheritAxes、 Direct3DRMFrame3.GetAxes、Direct3DRMFrame3.SetAxes

Direct3DRMFrame3.SetMaterial

Direct3DRMFrame3

Direct3DRMFrame3オブジェクトのマテリアルを設定する。

構文

object.SetMaterial(mat As Direct3DRMMaterial2)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
mat
フレームに適用されるDirect3DRMMaterialオブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.GetMaterial

Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3

フレームのマテリアルモードを設定する。マテリアルモードは、フレームとレンダリングされるビジュアルのマテリアル情報のソースを決定する。

構文

object.SetMaterialMode(val As CONST_D3DRMMATERIALMODE)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
val
フレームとレンダリングされるビジュアルのマテリアル情報を記述するCONST_D3DRMMATERIALMODE列挙型のメンバの1つ。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.GetMaterialMode

Direct3DRMFrame3.SetMaterialOverride

Direct3DRMFrame3

固有のマテリアル属性をセットできるようにする。たとえば、このメソッドはマテリアルの放射プロパティだけをオーバーライドできるようにする。

構文

object.SetMaterialOverride(override As D3DRMMATERIALOVERRIDE)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
override
オーバーライドするプロパティを記述するD3DRMMATERIALOVERRIDE型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

オーバーライドでは、常に階層をたどってすべてがオーバーライドされる。あるフレームの放射プロパティをオーバーライドする場合、階層をさらにたどって同じプロパティをオーバーライドしようとしても無視される。このオーバーライドは、固有のメッシュ上のマテリアルプロパティだけでなく、標準フレームのオーバーライドよりも優先する。SetMaterialやSetTextureなどのオーバーライドは、このメソッドの動作に対して何の効果も持たない。

参照

Direct3DRMFrame3.GetMaterialOverride

Direct3DRMFrame3.SetMaterialOverrideTexture

Direct3DRMFrame3

マテリアル属性に対する現在の属性ごとのオーバーライド設定をセットする。

構文

object.SetMaterialOverrideTexture(tex As Direct3DRMTexture3)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
tex
オーバーライドテクスチャとして設定されるDirect3DRMTexture3インターフェイス。

エラー値

メソッドが失敗した場合は、DDERR_INVALIDOBJECTまたはDDERR_INVALIDPARAMSを返す。

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.GetMaterialOverrideTexture

Direct3DRMFrame3.SetOrientation

Direct3DRMFrame3

z方向が方向ベクトル [dx, dy, dz]と同方向を指し、y方向がベクトル[ux, uy, uz]と同方向を指すようにフレームを整列する。

構文

object.SetOrientation(reference As Direct3DRMFrame3,
  dx As Single,
  dy As Single,
  dz As Single,
  ux As Single,
  uy As Single,
  uz As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrameオブジェクトを表す変数。
dx, dy, dz
フレームの新しいz軸。ベクトルの各要素は、1.0から1.0の範囲にある必要がある。
ux, uy, uz
フレームの新しいy軸。ベクトルの各要素は、1.0から1.0の範囲にある必要がある。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

フレームのデフォルトの方向は、方向ベクトル[0, 0, 1]およびアップベクトル[0, 1, 0]を持つ。

[ux, uy, uz] が [dx, dy, dz]に平行な場合には、D3DRMERR_BADVALUEエラー値が戻る。そうでない場合には、渡された [ux, uy, uz] ベクトルは、[dx, dy, dz]に垂直なプレーンに投影される。

このメソッドは、Direct3DRMFrameInterpolatorオブジェクトに方向キーを追加するためにも使用する。

参照

Direct3DRMFrame3.GetOrientation

Direct3DRMFrame3.SetPosition

Direct3DRMFrame3

参照フレームを基準にしてフレームの位置を設定する。フレームを参照フレームから [x, y, z] の距離に置く。親の中に子フレームが作成される場合、子フレームは親フレームの [0, 0, 0] の位置に置かれる。

構文

object.SetPosition(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrameオブジェクトを表す変数。
x, y, z
フレームの新しい位置。位置には単位がない。視錐台を使用して、適正な数字を選択する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMFrameInterpolatorオブジェクトに位置キーを追加するためにも使用する。

参照

Direct3DRMFrame3.GetPosition

Direct3DRMFrame3.SetQuaternion

Direct3DRMFrame3

単位4元数を用いて、参照フレームに対してフレームの向きを設定する。

構文

object.SetQuaternion(reference As Direct3DRMFrame3,
  quat As D3DRMQUATERNION)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrameオブジェクトを表す変数
quat
フレームの方向を設定するD3DRMQUATERNION型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

4元数とは、任意の回転を表すために用いられる4値ベクトルで、向きの間で補間を行うときに有用な特性を持っている。4元数は、s**2 + x**2 + y**2 + z**2 = 1であれば単位4元数である。

SetQuaternionメソッドは、インターポレータによりサポートされている。

Direct3DRMFrame3.SetRotation

Direct3DRMFrame3

Direct3DRM3.TickまたはDirect3DRMFrame3.Moveメソッドに対する呼び出しごとに、指定のベクトルの周囲に指定の角度でフレームの回転を設定する。方向ベクトル [x, y, z] は、参照フレームで定義される。

構文

object.SetRotation(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single,
  theta As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrameオブジェクトを表す変数。
x, y, z
回転の中心のベクトル。有効な値は、1.0から1.0の範囲にある必要がある。
theta
ラジアン単位の回転角。角度が大きければ大きいほど、オブジェクトの回転は速くなる。MoveとTickメソッドが、この値をスケーリングする。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

指定の回転は、フレーム中のオブジェクトを一度しか変更しないDirect3DRMFrame3.AddRotationメソッドとは異なり、レンダリングごとに行列を変更する。

参照

Direct3DRMFrame3.GetRotation

Direct3DRMFrame3.SetSceneBackground

Direct3DRMFrame3

シーンの背景色を設定する。

構文

object.SetSceneBackground(c As Long)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
c
背景の新しい色。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMFrameInterpolatorオブジェクトへの背景カラーキーを追加するためにも使われる。

Direct3DRMFrame3.SetSceneBackgroundDepth

Direct3DRMFrame3

シーンの背景深度バッファを指定する。

構文

object.SetSceneBackgroundDepth(s As DirectDrawSurface4)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
s
シーンの新しい背景深度を保存する Microsoft DirectDraw® サーフェス。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

イメージはピクセル単位の深度16を持たなければならない。イメージとビューポートのサイズが異なると、はじめにイメージのスケーリングを行う。背景深度バッファをアニメーションするときに最適なパフォーマンスを得るには、イメージはビューポートと同じサイズでなければならない。そうすると、余分なオーバーヘッドなしに、深度バッファはイメージメモリから直接更新することができる。

参照

Direct3DRMFrame3.GetSceneBackgroundDepth

Direct3DRMFrame3.SetSceneBackgroundImage

Direct3DRMFrame3

シーンの背景イメージを指定する。

構文

object.SetSceneBackgroundImage(i As Direct3DRMTexture3)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
i
新しい背景シーンを含むDirect3DRMTexture3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

イメージのサイズまたはカラー深度がビューポートと異なる場合、まずイメージのスケーリングを行うか、正しい深度に変換する。背景をアニメーションするときに最適なパフォーマンスを得るには、イメージはビューポートと同じサイズおよびカラー深度でなければならない。そうすると、余分なオーバーヘッドなしに、直接イメージメモリから背景のレンダリングを行うことができる。

Direct3DRMFrame3.SetSceneBackgroundRGB

Direct3DRMFrame3

シーンの背景色を設定する。

構文

object.SetSceneBackgroundRGB(r As Single,
  g As Single,
  b As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
r, g, b
背景の新しい色。色の各要素は、0.0から1.0の範囲にある必要がある。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMFrameInterpolatorオブジェクトに背景RGBカラーキーを追加するためにも用いられる。

Direct3DRMFrame3.SetSceneFogColor

Direct3DRMFrame3

シーンのフォグ色を設定する。

構文

object.SetSceneFogColor(c As Long)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
c
フォグの新しい色。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMRFrameInterpolatorオブジェクトにフォグカラーキーを追加するためにも用いられる。

Direct3DRMFrame3.SetSceneFogEnable

Direct3DRMFrame3

フォグイネーブル状態を設定する。

構文

object.SetSceneFogEnable(enable As CONST_DBOOLFLAGS)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
enable
新しいフォグイネーブル状態。フォグイネーブル状態を無効にするには、このパラメータをD_FALSEに設定し、フォグイネーブル状態を有効にするにはD_TRUEに設定する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.SetSceneFogMethod

Direct3DRMFrame3

頂点フォグまたはテーブルフォグを介してフォグを実行するかどうかを指定する。

構文

object.SetSceneFogMethod(enable As CONST_D3DRMFOGMETHOD)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
enable
フォグの実装方法を示す値。CONST_D3DRMFOGMETHOD列挙型からの値。

エラー値

エラーが発生した場合は、次の値のうちの1つを返す。

  • D3DRMERR_BADVALUE
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

Direct3DRM3インターフェイスによって作成されるDirect3DRMFrame3オブジェクトのデフォルトの動作はD3DRMFOGMETHOD_ANYであり、フォグメソッドはデバイスの機能に基づいて選択される。デバイスが頂点とテーブルを基準とした両方のフォグをサポートする場合、頂点フォグが使用される。アプリケーションでテーブルフォグが要求されたが、テーブルフォグが使用可能でない場合も、頂点フォグが使用される。

Direct3DRMFrame3.SetSceneFogMode

Direct3DRMFrame3

フォグモードを設定する。

構文

object.SetSceneFogMode(c As CONST_D3DRMFOGMODE)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
c
CONST_D3DRMFOGMODE列挙型のメンバの1つで、新しいフォグモードを指定する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.SetSceneFogParams

Direct3DRMFrame3.SetSceneFogParams

Direct3DRMFrame3

シーンのフォグ開始および終了ポイントとフォグの密度を設定する。

構文

object.SetSceneFogParams(start As Single,
  End As Single,
  density As Single)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
start, End
線形フォグモードのフォグ開始および終了ポイント。この設定は、フォグ効果が最初に見えるようになるときのカメラからの距離と、フォグが最大密度になるときの距離を決める。
density
指数フォグモードでのフォグ密度。この値は、0から1の値でなければならない。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このメソッドは、Direct3DRMRFrameInterpolatorオブジェクトにフォグパラメータキーを追加するためにも用いられる。

参照

CONST_D3DRMFOGMODE、Direct3DRMFrame3.SetSceneFogMode

Direct3DRMFrame3.SetSortMode

Direct3DRMFrame3

子フレームを処理するのに使用するソートモードを設定する。このメソッドを使用して隠面削除アルゴリズムのプロパティを変更することができる。

構文

object.SetSortMode(val As CONST_D3DRMSORTMODE)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
val
ソートモードを指定するCONST_D3DRMSORTMODE列挙型のメンバの1つ。デフォルト値は、D3DRMSORT_FROMPARENTである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.GetSortMode

Direct3DRMFrame3.SetTexture

Direct3DRMFrame3

フレームのテクスチャを設定する。

構文

object.SetTexture(t As Direct3DRMTexture3)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
t
使用されるDirect3DRMTexture3オブジェクト。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

注意

このテクスチャは、CONST_D3DRMMATERIALMODE列挙型がD3DRMMATERIAL_FROMFRAMEである場合に、フレーム中のメッシュに対して使用される。フレームのテクスチャをディセーブルにするには、NOTHINGテクスチャを使用する。

参照

Direct3DRMFrame3.GetTexture、Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3.SetTraversalOptions

Direct3DRMFrame3

レンダリングとピッキングの際にこのフレームを横断するかどうかを指定する。

構文

object.SetTraversalOptions(flags As CONST_D3DRMTRAVERALFLAGS)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
flags
このフレームがレンダリングとピッキングのどちらが可能であるか示すCONST_D3DRMTRAVERALFLAGS列挙型の1つ以上の値。D3DRMFRAME_RENDERENABLEの値なしでこのメソッドを使用すると、レンダリングに対してフレームが効率的にオフに切り換わる。デフォルトでは、フレームはレンダリングとピッキングに対して有効になる。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

Direct3DRMFrame3.SetVelocity

Direct3DRMFrame3

参照フレームを基準として指定のフレームの速度を設定する。フレームは、Direct3DRM3.TickまたはDirect3DRMFrame3.Moveメソッドに対する連続呼び出しのたびに、参照フレームを基準として [x, y, z] ベクトル分だけ移動する。

構文

object.SetVelocity(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single,
  with_rotation As CONST_DBOOLFLAGS)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
reference
参照として使用されるDirect3DRMFrameオブジェクト
x, y, z
フレームの新しい速度。回転速度は単位を持たず、任意の値をセットできる。MoveとTickメソッドは、この値をスケーリングする。
with_rotation
直線速度を設定するときに、オブジェクトの回転速度を考慮するかどうかを指定するフラグ。D_TRUEの場合、オブジェクトの回転速度が計算に含まれる。そうでなければ、D_FALSEを設定する。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.GetVelocity

Direct3DRMFrame3.SetZbufferMode

Direct3DRMFrame3

Zバッファリングをイネーブルまたはディセーブルにするかを設定する。

構文

object.SetZbufferMode(val As CONST_D3DRMZBUFFERMODE)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
val
Zバッファモードを指定するCONST_D3DRMZBUFFERMODE列挙型のメンバの1つ。デフォルト値はD3DRMZBUFFER_FROMPARENTである。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.GetZbufferMode

Direct3DRMFrame3.Transform

Direct3DRMFrame3

指定のベクトルを変換し、結果を返す。

構文

object.Transform(d As D3DVECTOR,
  s As D3DVECTOR)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
d
変換操作の結果がセットされるD3DVECTOR型。
s
変換操作のソースであるD3DVECTOR型。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

Direct3DRMFrame3.InverseTransform

Direct3DRMFrame3.TransformVectors

Direct3DRMFrame3

ベクトルの配列を、モデルからワールド空間に変換する。

構文

object.TransformVectors(reference As DIRECT3DRMFrame3,
  num As Long,
  DstVectors() As D3DVECTOR,
  SrcVectors() As D3DVECTOR)

要素

object
Direct3DRMFrame3オブジェクトを表すオブジェクト式。
reference
この呼び出しのためにシーンのルートとして使用されるフレーム。この引数がNOTHINGの場合、現在のルートフレーム(GetSceneが返すフレーム)が使用される。
num
変換する必要のあるベクトル数。
DstVectors()
変換の出力先。
SrcVectors()
変換するベクトルの配列。

エラー値

エラーのリストについては、「Direct3D保持モードのエラー値」を参照すること。

参照

D3DVECTOR