DIVEing into OS/2 Games!

by Darren Dobkin

Entertainment/education (edutainment) and games software developers all need to perform high-speed animated graphics. The OS/2 operating system has, until now, presented a dilemma for them, with the only choices being VIO APIs in a full-screen session or Presentation Manager.

Either choice came with several disadvantages. The VIO APIs permit fast screen updates, but the synchronized, device-independent, file-format independent multimedia support provided by MMPM/2 is unavailable to VIO programs. Additionally, IBM has tried to discourage use of the VIO APIs by removing them from the documentation in the OS/2 2.x Toolkits.

PM, on the other hand, preserves the integrity of the desktop session by denying frame buffer access to all applications. PM applications can use GpiBitBlt for animated graphics, but the performance is unacceptable for edutainment programs and interactive games.

In addition, many hardware manufactures such as Tseng Labs, Weitek, and S3 Inc. are preparing video acceleration chipsets for their upcoming models that will provide hardware support for the demanding tasks of color conversion, image clipping and display memory bank-switching. Ideally, the OS/2 games programmer must be able to perform high-speed blitting within the context of the PM desktop and also be in a position to exploit the new acceleration hardware when it becomes available.

The Dream Becomes a Reality
The next version of OS/2 will usher in a new era of PM programming that will solve both of these problems and enable edutainment programs and games that we could previously only dream about. These programs will use high-speed graphics comparable to the hottest sellers in the DOS market, yet they will run simultaneously with other applications, sharing audio and screen resources. These programs will combine the double-buffered, fast-blitting techniques of the DOS games market with the message-driven, window-oriented, multithreaded, high-level APIs of the PM and MMPM/2 programming world. They will benefit from new hardware improvements without any code modification.

The next generation of display hardware, through a new API set called the Direct Interface Video Extension (DIVE), will provide relief for the PM performance dilemma and compatibility. Not only will DIVE provide a new method for fast blitting of image data, but also provide support for color-depth conversion, display hardware bank-switching, visible region clipping, and stretch-blitting either to the screen or a destination image buffer. DIVE also will take advantage of stretch-blitting acceleration hardware - whenever such hardware is available. Finally, DIVE will provide the holy grail of the OS/2 game developer: a pointer to the frame buffer.

Some Practical Matters
DIVE applications gain access to DIVE functions by getting a DIVE handle as follows: ULONG ulErrorCode; HDIVE hDive; BOOL fUseScreen; PPVOID ppFrameBuffer; ulErrorCode = DiveOpen( &hDive, fUseScreen, ppFrameBuffer); The corresponding DiveClose( hDive ) must be called at application termination.

If DIVE is to be used for blitting to the screen, set fUseScreen to TRUE. This returns a pointer to the frame buffer in *ppFrameBuffer. If DIVE is to be used only for off-screen stretch-blitting and color-format conversion, set fUseScreen to FALSE.

DIVE Image Buffers
DIVE will use off-screen VRAM where available for acceleration of blitting operations, so the application must allocate all source and destination blitting buffers from DIVE. To allocate a buffer, the application can make the following call: ULONG  ulBufNum; FOURCC fccColorSpace; ULONG  ulWidth, ulHeight; ulErrorCode = DiveAllocImageBuffer(              hDive,                     /* DIVE handle            */               &ulBufNum,                 /* buffer number (output) */               fccColorSpace,             /* color format           */               ulWidth, ulHeight);        /* size of maximum image  */ The corresponding DiveFreeImageBuffer(Dive, ulBufNum) call deallocates the buffer.

The color format of the image buffer is described by fccColorSpace. The DIVE API defines constants for a variety of 8-, 16-, and 24-bit color encoding schemes.

After a buffer is allocated and before it can be used for blitting, it must be accessed as follows: PBYTE pbImageBuffer; ULONG ulScanLineBytes; ulErrorCode = DiveBeginImageBufferAccess(              hDive,                /* DIVE handle                 */               ulBufNum,             /* buffer number               */               &pbImageBuffer,       /* ptr to image buffer(output) */               &ulScanLineBytes);    /* scan line length (output)   */ DIVE calculates the number of bytes-per-scanline for the image buffer (based on the color format) and returns the value in ulScanLineBytes. The application can now write color data into pbImageBuffer. For example, the application can open a bitmap file and read the bitmap data directly into the image buffer. After the data has been written, the application calls DiveEndImageBufferAccess( hDive, ulBufNum)</tt> to deaccess the buffer.

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</tt> 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, (PBYTE)pbPal); If the application itself is using palettes, these palettes also must be communicated to DIVE through the DiveSetSourcePalette</tt> API. 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</tt>. If a sequence of images is being used for animation, and the palette remains constant through the series, you must call DiveSetSourcePalette</tt> only once before blitting the first image in the series.

DIVE provides high-speed screen updates by bypassing PM. However, 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. For the application to provide this information, a small set of new PM APIs for visible region notification will be made available.

The visible region notification APIs are public versions of a private interface originally developed to enable software motion video in MMPM/2. DIVE is based on bank-switching, color conversion, and clipping technology developed for the software motion video stream handler and the Ultimotion and Indeo CODECs. Therefore, expect that the graphics performance of DIVE applications will be comparable to the frame rates achieved by MMPM/2 software motion video.

Every DIVE application will request visible region notification at window initialization time with the following call: WinSetVisibleRegionNotify( hwnd, TRUE); The first parameter is the handle of the window where the graphics operations will appear; the second parameter turns on notification for that window. A corresponding WinSetVisibleRegionNotify( wnd, FALSE)</tt> call turns off notification at window termination time. Whenever the window's visible region changes, either because the window is moved or sized, or another window or icon overlaying the window is moved or sized, the window will receive a WM_VRNENABLED</tt> message. In response to this message, the DIVE application will query the new visible region using WinQueryVisibleRegion as follows: hps = WinGetPS( hwnd ); hrgn = GpiCreateRegion( hps, 0, NULL); WinQueryVisibleRegion( hwnd, hrgn); Whenever the visible region, source-color format, image source, or destination size change, the DIVE application must pass the changes to DIVE with a call to DiveSetupBlitter</tt>. The application must pass the rectangles for the region in window coordinates and the position of the window in desktop coordinates.

First, get the rectangles and window coordinates: Then, pass the information to DIVE: The color format of the source image is described by fccSrcColors</tt>.

In this example, the DIVE blitter is set up to blit to the screen, but that need not be the case. You can also use DIVE to perform color-conversion and stretch-blitting to a destination image. Indicate the destination color encoding format in fccDstColorFormat</tt>; set ulDstWidth</tt> and ulDstHeight</tt> to the size of the destination image; set ulNumDstRects</tt> to 1; point pVisDstRects</tt> to a single rectangle with xLeft=yBottom=0, xRight=ulDstWidth</tt>, and yTop=ulDstHeight</tt>.

A new <tt>WM_VRNDISABLED</tt> PM message serves to notify the application that visible region notification has been suspended until the next <tt>WM_VRNENABLED</tt> message; the application must call <tt>DiveSetupBlitter (Dive, 0)</tt> when it receives this message.

Direct Frame Buffer Access
The <tt>*ppFrameBuffer</tt> returned by DiveOpen gives direct addressability to the frame buffer. To write directly to the frame buffer, the DIVE application must perform its own clipping, color conversion, and bank switching. The <tt>DiveQueryCaps</tt> API will return whether or not the display subsystem is bank-switched.

DIVE will provide another API called <tt>DiveCalcFrameBufferAddress</tt> to get to a location in the frame buffer that corresponds to a rectangle in desktop coordinates: To accomplish correct clipping, the <tt>rectlDest</tt> must be in the application window's visible region. If the display hardware is bank-switched, the application must not write more than <tt>ulRemlinesInAperture</tt> lines of output before switching banks. The data written to <tt>pDestinationAddress</tt> must be in the color-encoding scheme of the screen (also provided by <tt>DiveQueryCaps</tt>). (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 <tt>DiveAcquireFrameBuffer / DiveDeacquireFrameBuffer</tt>. Also, the application must not attempt to access the frame buffer between receipt of a <tt>WM_VRNDISABLED</tt> message and a <tt>WM_VRNENABLED</tt> message.

The First in a Series
Among the first programs to exploit the new DIVE interface will be an OS/2 version of the popular interactive game - DOOM. IBM is backing third-party developer AIC's efforts to port DOOM to the PM desktop using DIVE. IBM and AIC are anticipating delivery of a superior action game that will share audio and screen resources with other programs, yet perform like its DOS counterpart. Several other such efforts to port existing games to OS/2 and develop new games especially for OS/2 are underway.

Enhancements in the next OS/2 release that will enable satisfactory performance in only 4MB of RAM will expand the appeal of OS/2 in the home market. The new DIVE APIs and MMPM/2's video, audio, and animation support will make OS/2 the games platform of choice.

Look to future issues of The Developer Connection News for more information on using the OS/2 platform to develop games.