Beginning and Ending a Scene

You notify Direct3D that scene rendering is about to begin by calling the IDirect3DDevice3::BeginScene method. BeginScene causes the system to check its internal data structures, the availability and validity of rendering surfaces, and sets an internal flag to signal that a scene is in progress. After you begin a scene, you can call the various rendering methods to render the primitives or individual vertices that make up the objects in the scene. Attempts to call rendering methods when a scene is not in progress will fail, returning D3DERR_SCENE_NOT_IN_SCENE. For more information about the rendering methods, see Rendering Primitives.

After you complete the scene, call the IDirect3DDevice3::EndScene method. The EndScene method clears an internal flag that signals when a scene is in progress, flushes cached data, and verifies the integrity of the rendering surfaces.

All rendering methods must be bracketed by calls to the BeginScene and EndScene methods. If surfaces are lost, or if internal errors occur, the scene methods return error values. You must call EndScene for each time you call the BeginScene method, even if BeginScene fails. For example, some simple scene code might look like this:

HRESULT hr;
 
if(SUCCEEDED(lpD3D->BeginScene()))
{
    // Render primitives only if the scene
    // started successfully.
} 
 
// Always close the scene, even if BeginScene fails.
hr = lpD3D->EndScene(); 
if(FAILED(hr))
    return hr;
 

You cannot embed scenes; that is, you must complete rendering a scene before you can begin another one. Calling IDirect3DDevice3::EndScene when IDirect3DDevice3::BeginScene has not been called will return the D3DERR_SCENE_NOT_IN_SCENE error value. Likewise, calling BeginScene when a previous scene has not been completed (with the EndScene method) results in the D3DERR_SCENE_IN_SCENE error.

You should not attempt to call GDI functions on DirectDraw surfaces, such as the render target or textures, while a scene is being rendered (between BeginScene and EndScene calls). Attempts to do so can prevent the results of the GDI operations from being visible. If your application uses GDI functions, make sure that all GDI calls are made outside of the scene functions.