Applications written in C++ notify Direct3D that scene rendering is about to begin by calling the IDirect3DDevice7::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 fail, returning D3DERR_SCENE_NOT_IN_SCENE. For more information, see Rendering Primitives.

After you complete the scene, call the IDirect3DDevice7::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 internal errors occur, the scene methods return error values. If BeginScene fails, the scene does not begin, and subsequent calls to EndScene will fail. When surfaces are lost during rendering, EndScene will return DDERR_SURFACELOST. If surfaces were not successfully restored before calling BeginScene, then BeginScene will also return DDERR_SURFACELOST.

To summarize these cases:

• If BeginScene returns any error, you must not call EndScene because the scene has not successfully begun.
• If BeginScene succeeds, but you get an error while rendering of the scene, you must call EndScene.
• If EndScene fails, for any reason, you need not call it again.

For example, some simple scene code might look like this:

HRESULT hr;
 
if(SUCCEEDED(lpDevice->BeginScene()))
{
    // Render primitives only if the scene
    // starts successfully.
    
    // Close the scene.
    hr = lpDevice->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 IDirect3DDevice7::EndScene when IDirect3DDevice7::BeginScene has not been called returns 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.

Do 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, be sure that all GDI calls are made outside the scene functions.

Visual Basic applications notify Direct3D that scene rendering is about to begin by calling the Direct3DDevice7.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 fail, returning the D3DERR_SCENE_NOT_IN_SCENE error. For more information, see Rendering Primitives.

After you complete the scene, call the Direct3DDevice7.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 internal errors occur, the scene methods fail and Err.Number will be set to an error code. If BeginScene fails, the scene does not begin, and subsequent calls to EndScene will fail. When surfaces are lost during rendering, EndScene will fail, raising the DDERR_SURFACELOST error. If surfaces were not successfully restored before calling BeginScene, then BeginScene will also return DDERR_SURFACELOST.

To summarize these cases:

• If BeginScene returns any error, you must not call EndScene because the scene has not successfully begun.
• If BeginScene succeeds, but you get an error while rendering of the scene, you must call EndScene.
• If EndScene fails, for any reason, you need not call it again.

For example, some simple scene code might look like this:

On Local Error Resume Next

Call d3dDev.BeginScene
If Err.Number = DD_OK Then
    ' Render primitives only if the scene
    ' starts successfully.

    ' Close the scene.
    Call d3dDev.EndScene
    If Err.Number <> DD_OK Then
        ' Code to handle error goes here.
    End If
End If
 

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

Do 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 the scene functions.