Platform SDK: DirectX |
C++ で記述されたアプリケーションでは、IDirect3DDevice7::BeginScene メソッドを呼び出して、Direct3D にシーンのレンダリングの開始を知らせる。BeginScene の命令を受けたシステムは、内部データ構造およびレンダリングするサーフェスの可用性と妥当性をチェックし、シーンが処理中であることを知らせる内部フラグを設定する。シーンの開始後は、さまざまなレンダリング メソッドを呼び出してプリミティブをレンダリングしたり、シーンのオブジェクトを構成する頂点を個別にレンダリングすることができる。シーンの処理中でないときにレンダリング メソッドを呼び出そうとすると失敗し、D3DERR_SCENE_NOT_IN_SCENE が返される。詳細については、「プリミティブのレンダリング」を参照すること。
シーンが完了したら、IDirect3DDevice7::EndScene メソッドを呼び出す。EndScene メソッドは、シーンの処理中であることを知らせる内部フラグをクリアし、キャッシュされていたデータをフラッシュし、レンダリング サーフェスの整合性を検証する。
レンダリング メソッドはすべて、BeginScene メソッドを呼び出してから EndScene メソッドを呼び出すまでの間に実行しなければならない。サーフェスが失われるか、または内部エラーが発生すると、シーンのメソッドはエラー値を返す。BeginScene メソッドが失敗した場合、シーンは開始されず、それに続く EndScene の呼び出しも失敗する。レンダリング中にサーフェスが失われた場合は、EndScene が DDERR_SURFACELOST を返す。BeginScene を呼び出す前にサーフェスが正常に復元されなかった場合、BeginScene も DDERR_SURFACELOST を返す。
これらのケースを以下にまとめる。
たとえば、単純なシーンを処理するコードは次のようになる。
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 アプリケーションでは、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 を返す。
これらのケースを以下にまとめる。
たとえば、単純なシーンを処理するコードは次のようになる。
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 の呼び出しを行うようにする。