DiveOpen

This function opens a display engine instance.

Syntax

_DiveOpen(phDiveInst, fNonScreenInstance, ppFrameBuffer)

Parameters

phDiveInst (HDIVE *) - output

Upon successful open of a DIVE instance, this parameter points to the display engine instance. If there is an error, this parameter is set to NULL and an error is returned as the return code.

fNonScreenInstance (BOOL) - input

This parameter indicates whether this DIVE instance should be using the physical display hardware. If *fNonScreenInstance* is **FALSE**, this function returns a pointer to the linear base address to the VRAM and the DiveBlitImage functions in this instance can have screen or non-screen destination buffers. If *fNonScreenInstance* is **TRUE**, the DIVE instance will not use display hardware resources, and only non-screen destination buffers can be used as destination buffers for DiveBlitImage.

ppFrameBuffer (PVOID) - output

This parameter is a pointer on input to a pointer variable that will be set on output to contain the linear address of the VRAM if *fNonScreenInstance* is specified. This address always corresponds to the top left of the screen when aperture bank 0 is selected. If you do **not** intend to use this, pass a 0.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

• DIVE_SUCCESS If the function succeeds, 0 is returned.
• DIVE_ERR_ALLOCATION_ERROR The hardware-blitter memory allocation failed.
• DIVE_ERR_NO_DIRECT_ACCESS The display adapter does not support direct access, the display is in 16-color mode, or the display driver is down-level.
• DIVE_ERR_SSMDD_NOT_INSTALLED The device driver SSMDD.SYS is missing from CONFIG.SYS.
• DIVE_ERR_TOO_MANY_INSTANCES There are not enough resources for another DIVE instance.

Remarks

If the *fNonScreenInstance* parameter is **FALSE**, DIVE will return the linear base address of the VRAM.

DiveOpen does not require direct addressability to the screen because the DIVE display engine is also intended as a color-format conversion tool.

Example Code

#include <dive.h>

HDIVE *phDiveInst;         /* Display engine instance. */
BOOL fNonScreenInstance;   /* Using physical display hardware. */
PVOID ppFrameBuffer;       /* Linear address of the VRAM. */
ULONG rc;                  /* Return codes. */

rc = DiveOpen(phDiveInst, fNonScreenInstance,
        ppFrameBuffer);