The BeginScene and EndScene Methods

[Previous] [Next]

Before getting into the details of rendering primitives, you should know about BeginScene and EndScene. In Direct3D, you indicate that you want to begin rendering a scene by using the IDirect3DDevice7::BeginScene method. This method tells DirectX to verify the rendering data and make sure the rendering surfaces are set up correctly.

After using this method to begin the scene, you can begin using the Direct3D methods to render the primitives constituting the objects in your scene. If you call these methods before calling BeginScene, Direct3D will return D3DERR_SCENE_NOT_IN_SCENE. Once your rendering is complete, you need to call IDirect3DDevice7::EndScene to clear the internal flag that indicates the scene is in progress, flushes the cached data, and makes sure the rendering surfaces are OK.

You need to wrap all your rendering method calls with the BeginScene/EndScene pair. If BeginScene fails, the scene won't begin and any calls to EndScene will fail (since you didn't start the scene in the first place). If a surface isn't restored before a call to BeginScene, it will return DDERR_SURFACELOST. If a surface is lost during rendering, EndScene will return this error value also and calls to the scene methods will return errors also. Note that after BeginScene succeeds, if an error is returned during scene rendering, you need to call EndScene to clean up your rendering process.

One important point to remember is that you must always end rendering one scene before beginning another. If you attempt to nest BeginScene/EndScene pairs, the D3DERR_SCENE_IN_SCENE error will be returned. You'll also get this error if you call EndScene without calling BeginScene.