MD> RB> Doing serious gaming work with PM is pretty senseless, it just isn't
MD> RB> fast enough.  Dive makes you fiddle with palettes and stuff, but you
MD> RB> will not get faster video anywhere, even under DOS.  I'm currently
MD> RB> working on a 3D shootem up for OS/2 using DIVE V1.

MD>Could you briefly explain how PM and DIVE work together?  Does DIVE allow
MD>one to write into a PM window?  I also heard that DIVE is built into WARP,
MD>but is available for 2.1 as well.  BTW, I look forward to having control
MD>over the palette!   I'm working on a side-view platform game, and I'm
MD>hoping to be able to do an OS/2 version.  After that I'll be doing
MD>adventure and RPG games for OS/2.  So far the market looks wide open =^)

There are two versions of DIVE.  DIVE V1 was included with MMPM/2 in
OS/2 2.1 and was used for Ultimotion software motion video.  DIVE was
significantly expanded and enhanced for Warp. I haven't heard if DIVE 2
will be available for 2.1, there were some structural changes made to PM
to accomodate DIVE2, and I don't know if they are backwards compatible.
Look for DIVE.ZIP and DLIB06.ZIP for information and examples of how
to use DIVE 1.

All DIVE 1 does is give you a pointer to the video RAM that contains the
PM screen, so you can write anywhere on the screen and PM doesn't have
anything to say about it.  Putting your image onto the same spot on the
screen as the window you create for your application is your
responsibility - you have to figure out where the window is in the
video buffer, how wide and high it is, and put your image there
yourself. You also have to worry about the palette, either using PM's
palette functions to put in a custom palette, or using the standard OS/2
one. In any case, you have to figure out what the physical palette is
(there is a PM call that will let you do this) and map your sprites'
colors to that so that the colors show up right on screen. There is no
way to control the physical palette in DIVE 1.

I'm currently working with DIVE 1, because to date, DIVE 2 is not
compatible with OS/2 2.0.  Here are some excerpts from the DIVE 2
READ.ME, it is too big to include the whole thing:

___-------------------------------------------------------------------

What is DIVE ?

Direct Interface Video Extensions (DIVE) is a DLL that provides
optimized blitting performance for motion video subsystems and
applications that perform rapid screen updates in the OS/2 PM and
full-screen environments. Using DIVE interfaces, applications can either
write directly to video memory or use the DIVE blitter to get a high
level of screen update performance, image scaling, color space
conversion, and bank-switch display support.

The DIVE blitter will take advantage of acceleration hardware when
present and applicable to the function being performed. The display
engine consists of a single stand-alone DLL that exports the following
functions:

1. A query for display capabilities
2. Open instance
3. Visible region specification
4. Allocation of image data buffers
5. Buffer to screen/buffer to buffer transfer (blitter) setup
6. 8-bit CLUT color palette simulation/specification
7. Transfer buffer to image display/transfer buffer to buffer
8. Utility functions useful for direct access, including window
   starting address calculation
9. Frame buffer acquire/de-acquire
10.VRAM bank selection (for bank switched displays)
11.Close instance

The display engine enables subsystem components (for example, video
CODECs) and applications to either directly access the video buffer or
to use the display engine screen transfer functions.  If direct access
is used, the using component or application is responsible for writing
to the frame buffer format for the current display mode and correctly
clipping the output. In addition, the component is responsible for
acquiring and bank switching the display apertures.  If display engine
screen transfer functions areused, the display engine will handle
clipping and pel format/color space conversions and any necessary
hardware serialization.

DIVE Palettes

DIVE applications must inform DIVE of the state of the physical palette
upon initialization and whenever the physical palette changes.  At
application initialization, and in response to a WM_REALIZEPALETTE
message, the application calls the following sequence:

BYTE pbPal[1024];
/* Query the physical palette from PM   */
GpiQueryRealColors( hps, 0, 0, 256, (PLONG)pbPal);
/* Pass it to DIVE              */
DiveSetDestinationPalette( hDive, ulStartIndex, ulNumEntries,
(PBYTE)pbRGB2Entries);

If the application itself is using palettes, these palettes must also be
communicated to DIVE through the DiveSetSourcePalette APIs.  For
example, if the application is using DIVE to blit 256-color palettized
images to the screen, the application must send the image palette with a
call to DiveSetSourcePalette.  If a sequence of images are being used
for animation, and the palette remains constant through the series, it
is only necessary to call DiveSetSourcePalette once before blitting the
first image in the series.

DIVE provides high-speed screen updates by bypassing PM.  With such
power comes responsibility.  In order to maintain the integrity of the
PM desktop, DIVE applications must notify DIVE whenever the visible
region of the application window changes so that output may be clipped
accordingly.  In order for the application to provide this information,
a small set of new PM APIs for visible region notification will be made
available.

Direct Frame Buffer Access

As mentioned earlier, the *ppFrameBuffer returned by DiveOpen gives
direct addressability to the frame buffer.  In order to write directly
to the frame buffer, the DIVE application must perform its own clipping,
color conversion and bank switching.  The following functions are
provided for direct frame buffer access:  DiveAcquireFrameBuffer,
DiveDeacquireFrameBuffer, DiveSwitchBank, and
DiveCalcFrameBufferAddress.

The DiveQueryCaps function will return whether the display subsystem is
bank-switched.  DIVE provides DiveCalcFrameBufferAddress to get to a
location in the frame buffer that corresponds to a rectangle in desktop
coordinates:

To accomplish correct clipping, the rectlDest must be in the application
window's visible region.  If the display hardware is bank-switched, then
the application must not write more than ulRemlinesInAperture lines of
output before switching banks.  The data written to pDestinationAddress
must be in the color-encoding scheme of the screen (also provided by
DiveQueryCaps).  (Of course DIVE can be used to convert to the correct
screen color-encoding prior to writing to the frame buffer by doing a
DIVE blit to a destination buffer with the same color-encoding.)
Additionally, if the screen supports only 256 colors, the data must
match the current physical palette.

All write access to the frame buffer must be bracketed by calls to
DiveAcquireFrameBuffer / DiveDeacquireFrameBuffer.  Also, the
application must not attempt to access the frame buffer between receipt
of a WM_VRNDISABLED message and a WM_VRNENABLED message.
___
 X SLMR 2.1a X Yield to temptation, it may not pass your way again.

--- Maximus/2 2.01wb