Microsoft DirectX 9.0

Beginning and Ending a Scene


Applications written in C++ notify Microsoft® Direct3D® that scene rendering is about to begin by calling the IDirect3DDevice9::BeginScene method. IDirect3DDevice9::BeginScene causes the system to check its internal data structures and the availability and validity of rendering surfaces. It also 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 fail. For more information, see Rendering Primitives.

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

All rendering methods must be bracketed by calls to the IDirect3DDevice9::BeginScene and IDirect3DDevice9::EndScene methods. If surfaces are lost or internal errors occur, the scene methods return error values. If IDirect3DDevice9::BeginScene fails, the scene does not begin, and subsequent calls to IDirect3DDevice9::EndScene will fail.

To summarize these cases:

For example, some simple scene code might look like the following example.

HRESULT hr;

if(SUCCEEDED(pDevice->BeginScene()))
{
    // Render primitives only if the scene
    // starts successfully.

    // Close the scene.
    hr = pDevice->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 IDirect3DDevice9::EndScene when IDirect3DDevice9::BeginScene has not been called returns an error value. Likewise, calling IDirect3DDevice9::BeginScene when a previous scene has not been completed with the IDirect3DDevice9::EndScene method results in an error.

Do not attempt to call Microsoft Windows® Graphics Device Interface (GDI) functions on Direct3D surfaces, such as the render target or textures, while a scene is being rendered—is between IDirect3DDevice9::BeginScene and IDirect3DDevice9::EndScene calls. Attempts to do so can prevent the results of the GDI operations from being visible. If your application uses GDI functions, be sure that all GDI calls are made outside the scene functions.



© 2002 Microsoft Corporation. All rights reserved.