Bink SDK 1.5v

BinkBufferLock

The function BinkBufferLock locks the BinkBuffer for reading or writing to the pixel buffer.

S32 BinkBufferLock(
  HBINKBUFFER bink_buf
);

In Parameters

bink_buf
Specifies the BinkBuffer handle.

Returns

Returns whether the BinkBuffer was successfully locked (non-zero) or not (zero).

Discussion

This function locks the BinkBuffer for reading or writing to the pixel buffer. Once you lock a BinkBuffer, the Buffer and BufferPitch fields of the BinkBuffer structure will be set and available for use. Note that DirectDraw can be locked during a BinkBuffer lock, so be quick - do the lock, do whatever you want to the buffer as quickly as possible, and then do the unlock. For primary surface and overlay BinkBuffers, data written to a locked BinkBuffer will appear on the screen immediately. For off-screen BinkBuffers, you must lock, copy the pixel data, unlock, and then blit before the data will appear on the screen. To blit a frame onto the screen, you lock the buffer, copy from the Bink internal buffers into the BinkBuffer, unlock the buffer, and then blit the BinkBuffer onto the screen. So, to blit a frame of a Bink file onto the screen, you'll use code something like this:

BinkDoFrame( bink );                // decompress a frame
if ( BinkBufferLock( bink_buf ) ){ BinkCopyToBuffer( bink, // copy into the BinkBuffer bink_buf->Buffer, bink_buf->BufferPitch, bink_buf->Height, 0,0, bink_buf->SurfaceType );
BinkBufferUnlock( bink_buf );}
// blit the data onto the screenBinkBufferBlit( bink_buf, bink->FrameRects, BinkGetRects( bink, bink_buf->SurfaceType ) );

This function will return a non-zero value if the lock succeeded, and a zero if the BinkBuffer couldn't be locked. Note that DirectDraw doesn't allow you to step through a DirectDraw lock, so never single step over a BinkBufferLock call, or your machine will lock up. Always set a breakpoint after the BinkBufferUnlock call, and then just run to the breakpoint.


Group: BinkBuffer API
Related Sections: Locking and Unlocking
Related Functions: BinkBufferBlit, BinkBufferUnlock, BinkCopyToBuffer
Related Basic Types: BINKBUFFER_OPEN_FLAGS, HBINKBUFFER, S32
Related Structures: BINKBUFFER

For technical support, e-mail Bink1@radgametools.com
© Copyright 1994-2003 RAD Game Tools, Inc. All Rights Reserved.