DiveAcquireFrameBuffer

This function allows the frame buffer to be serialized. The frame buffer is locked for this instance. No other instance can acquire or switch aperture banks until this instance has deacquired the frame buffer.

Syntax

_DiveAcquireFrameBuffer(hDiveInst, prectlDst)

Parameters

hDiveInst (HDIVE) - input

Display engine DIVE instance.

prectlDst (PRECTL) - input

Indicates the destination rectangle of the output area. On bank-switched systems, the bank is automatically switched to the topmost bank in the specified screen destination rectangle.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

• DIVE_SUCCESS If the function succeeds, 0 is returned.
• DIVE_ERR_ACQUIRE_FAILED The acquire action did not complete successfully.
• DIVE_ERR_INVALID_INSTANCE The DIVE instance handle specified in the hDiveInst parameter is invalid.
• DIVE_ERR_NO_DIRECT_ACCESS The display adapter, display driver, or current video mode does not support direct-to-screen access.

Remarks

If another instance has the frame buffer acquired, the call will block until the frame buffer can be acquired.

The **DiveAcquireFrameBuffer** call and the corresponding DiveDeacquireFrameBuffer call are not necessary if you are using DiveBlitImage rather than writing directly to the screen with the *ppFrameBuffer* from DiveOpen.

Example Code

#include <dive.h>

HDIVE hDiveInst;  /* Display engine DIVE instance. */
PRECTL prectlDst; /* Destination rect of the output */
ULONG rc;         /* Return codes. */

rc = DiveAcquireFrameBuffer(hDiveInst, prectlDst);