Bink SDK 1.5v

BinkBufferOpen

The function BinkBufferOpen opens a BinkBuffer (which simplifies blitting YUV data onto the screen).

HBINKBUFFER BinkBufferOpen(
  OS_WND window,
  U32 width,
  U32 height,
  BINKBUFFER_OPEN_FLAGS open_flags
);

In Parameters

window
Specifies the window handle (under Win32) or window pointer (under MacOs) that the Bink file will be playing into. If you are using DirectDraw under Win32, this should be the HWND passed to SetCooperativeLevel.
width
Specifies the non-scaled width of the BinkBuffer (this is usually bink->Width).
height
Specifies the non-scaled height of the BinkBuffer (this is usually bink->Height).
open_flags
Specifies the type of blitting style and blitting functionality that you need. You will almost always just use BINKBUFFERAUTO for the open_flags parameter.

Returns

Returns an HBINKBUFFER handle that the other BinkBuffer API functions require. Returns zero if an error occurs.

Discussion

The BinkBuffer API simply provides an easy, abstracted way to access most of the YUV blitting techniques that are available under Win32 or MacOS. You will usually open a BinkBuffer like:

bink_buf = BinkBufferOpen( ourwind, bink->Width, bink->Height, BINKBUFFERAUTO );

Once the BinkBuffer is open, you must then resize your playback window to fit the Bink output (unless you are running full-screen or under DirectDraw and you've already set up your HWND). To do this under Win32, use a call like this:

SetWindowPos( hwnd, 0, 0, 0, bink_buf->WindowWidth, bink_buf->WindowHeight, SWP_NOMOVE );

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 ) );

Depending on the blitting style, the video's pixels may appear on the screen during the BinkCopyToBuffer call, or later, during the BinkBufferBlit call. If DirectDraw is installed and your aren't scaling, then you will usually be given a BinkBuffer that abstracts the DirectDraw primary video surface. In almost all other cases, you will be given a BinkBuffer that is an abstracted Windows DIBSection. If you want to use a YUV overlay or a YUV off-screen, then you must use the appropriate, specific BinkBuffer flag. Note that if you don't specify any of the various scaling flags, then you might still get a blitting style that allows scaling with BinkBufferSetScale function - but probably not! So, if you know that you're going to be scaling, then you should always use one of the scaling flags when calling BinkBufferOpen. If the BinkBuffer couldn't be created (lack of memory, low resources, etc), then this function will return zero. You must make sure to call BinkBufferClose on any buffer allocated by BinkBufferOpen.


Group: BinkBuffer API
Related Sections: Locking and Unlocking, Open and Close, Scaling
Related Functions: BinkBufferBlit, BinkBufferClose, BinkBufferGetError, BinkBufferSetDirectDraw, BinkBufferSetResolution, BinkBufferSetScale, BinkCopyToBuffer
Related Basic Types: BINKBUFFER_OPEN_FLAGS, HBINKBUFFER, OS_WND, U32
Related Structures: BINKBUFFER

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