IDirect3DSwapChain9::Present Method

Presents the contents of the next buffer in the sequence of back buffers owned by the swap chain.

Syntax

HRESULT Present(      

    const RECT *pSourceRect,
    CONST RECT *pDestRect,
    HWND hDestWindowOverride,
    CONST RGNDATA *pDirtyRegion,
    DWORD dwFlags
);

Parameters

pSourceRect

[in] Pointer to a RECT structure that contains the source rectangle. This value must be NULL unless the swap chain was created with D3DSWAPEFFECT_COPY. If NULL, the entire source surface is presented. If the rectangle exceeds the source surface, the rectangle is clipped to the source surface.

pDestRect

[in] Pointer to a RECT structure containing the destination rectangle, in window client coordinates. This value must be NULL unless the swap chain was created with D3DSWAPEFFECT_COPY. If NULL, the entire client area is filled. If the rectangle exceeds the destination client area, the rectangle is clipped to the destination client area.

hDestWindowOverride

[in] Destination window whose client area is taken as the target for this presentation. If this value is NULL, the hWndDeviceWindow member of D3DPRESENT_PARAMETERS is taken.

pDirtyRegion

[in] This value must be NULL unless the swap chain was created with D3DSWAPEFFECT_COPY. For more information about swap chains, see Flipping Surfaces and D3DSWAPEFFECT.

If this value is non-NULL, the contained region is expressed in back buffer coordinates. The rectangles within the region are the minimal set of pixels that need to be updated. This method takes these rectangles into account when optimizing the presentation by copying only the pixels within the region, or some suitably expanded set of rectangles. This is an aid to optimization only, and the application should not rely on the region being copied exactly. The implementation may choose to copy the whole source rectangle.

dwFlags

[in] Allows the application to request that the method return immediately when the driver reports that it cannot schedule a presentation. Valid values are 0, or any combination of D3DPRESENT_DONOTWAIT and D3DPRESENT_LINEAR_CONTENT.

If dwFlags = 0, this method behaves as it did prior to Microsoft?DirectX?9.0. Present will spin until the hardware is free, without returning an error.

If dwFlags = D3DPRESENT_DONOTWAIT, and the hardware is busy processing or waiting for a vsync interval, the method will return D3DERR_WASSTILLDRAWING.

If dwFlags = D3DPRESENT_LINEAR_CONTENT, gamma correction is performed from linear space to sRGB for windowed swap chains. This flag will take effect only when the driver exposes D3DCAPS3_LINEAR_TO_SRGB_PRESENTATION. For more information about gamma correction, see Gamma.

Return Value

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be one of the following values.

D3DERR_DEVICELOST	The device has been lost but cannot be reset at this time. Therefore, rendering is not possible.
D3DERR_DRIVERINTERNALERROR	Internal driver error. Applications should generally shut down when receiving this error. For more information, see Driver Internal Errors.
D3DERR_INVALIDCALL	The method call is invalid. For example, a method's parameter may have an invalid value.
D3DERR_OUTOFVIDEOMEMORY	Microsoft Direct3D?does not have enough display memory to perform the operation.
E_OUTOFMEMORY	Direct3D could not allocate sufficient memory to complete the call.

Remarks

The IDirect3DDevice9::Present method is a shortcut to the IDirect3DSwapChain9::Present. The swap chain method has been updated to take a flag allowing the application to request that the method return immediately when the driver reports that it cannot schedule a presentation.

If necessary, a stretch operation is applied to transfer the pixels within the source rectangle to the destination rectangle in the client area of the target window.

IDirect3DDevice9::Present will fail if called between IDirect3DDevice9::BeginScene and IDirect3DDevice9::EndScene pairs unless the render target is not the current render target (such as the back buffer you get from creating an additional swap chain). This is a new behavior for DirectX 9.0.

See Also

IDirect3DDevice9::Reset