RAD Game Tools Bink API

From MultimediaWiki
Jump to navigation Jump to search

Some games that use RAD Game Tools Bink files for their multimedia files distribute a handy Win32 DLL called binkw32.dll.

Data Structures

According to the Media Player Classic (MPC) application, the various Bink file manipulation functions pass around a structure with the following layout (all multi-byte numbers are native endian; pointers are 32-bit memory addresses): 

 bytes 0-3      video width
 bytes 4-7      video height
 bytes 8-11     frame count
 bytes 12-15    current frame
 bytes 16-19    last frame
 bytes 20-23    frames/second multiplier
 bytes 24-27    frames/second divisor
 bytes 28-31    unknown
 bytes 32-35    flags
 bytes 36-295   unknown
 bytes 296-299  current plane
 bytes 300-303  pointer to plane 0
 bytes 304-307  pointer to plane 1
 bytes 308-315  unknown
 bytes 316-319  Y plane width
 bytes 320-323  Y plane height
 bytes 324-327  U&V plane width
 bytes 328-331  U&V plane height

This document will refer to this structure as the BinkStruct.

MPC is interested in the following functions exported by the Bink DLL: 

* BinkSetSoundSystem
* BinkOpenDirectSound
* BinkOpen
* BinkGoto
* BinkDoFrame
* BinkNextFrame
* BinkClose

 int BinkSetSoundSystem(SOUND_FUNC SoundFunction, IDirectSound *pDS);

Description: BinkSetSoundSystem initializes the audio playback subsystem.

Parameters:

  • SoundFunction: This appears to be the function that will be invoked in order to playback the audio. MPC passes in BinkOpenDirectSound as the parameter. BinkOpenDirectSound must meet the qualifications to be a SOUND_FUNC (contrived for this description).
  • pDS: A pointer to an IDirectSound structure.

Returns: 0 if the function failed, non-zero on success. 

 BinkStruct *BinkOpen(HANDLE BinkFile, UINT32 Flags);

Description: BinkOpen opens and initializes a Bink file for playback.

Parameters:

  • BinkFile: A Windows file HANDLE that refers to the Bink file to be read.
  • Flags: The meaning of all the flags is unclear, but MPC calls BinkOpen with 0x00800000.

Returns: A pointer to a BinkStruct that will be used for playing the Bink file. 

 void BinkGoto(BinkStruct *Bink, UINT32 FrameNumber, UINT32 unknown);

Description: BinkGoto signals the playback engine to reposition the Bink file to a requested frame.

Parameters:

  • Bink: A pointer to the BinkStruct returned by BinkOpen.
  • FrameNumber: The frame number where the stream should be positioned to.
  • unknown: MPC sets this parameter to 0.

Returns: No known return value as MPC does not check for one. 

 int BinkDoFrame(BinkStruct *Bink);

Description: BinkDoFrame processes the next frame in the Bink file.

Parameters:

  • Bink: A pointer to the BinkStruct returned by BinkOpen.

Returns: MPC's code comments indicate that this function does return a value, but the meaning is not specified. 

 void BinkNextFrame(BinkStruct *Bink);

Description: BinkNextFrame signals the playback engine to advance the Bink file to the next frame.

Parameters:

  • Bink: A pointer to the BinkStruct returned by BinkOpen.

Returns: No known return value as MPC does not check for one. 

 void BinkClose(BinkStruct *Bink);

Description: BinkClose gracefully closes a Bink file and releases any allocated resources.

Parameters:

  • Bink: A pointer to the BinkStruct returned by BinkOpen.

Returns: No known return value as MPC does not check for one.

Using The Bink DLL

Using the Bink DLL to decode a Bink file operates using the following steps:

  1. Set up the sound system using BinkSetSoundSystem. The Bink DLL provides the BinkOpenDirectSound for audio playback and handles the audio itself.
  2. Call BinkOpen with a handle to the file. The function will allocate and return a BinkStruct data structure. This structure contains parameters regarding the file's video properties, such as width and height. There are pointers to two different planes. The Bink DLL uses a double-buffering scheme when decoding video, and decodes to YUV 4:2:0 data (alias YV12, YUV420P). After decoding a frame of video, one of the two planes will contain a pointer to a buffer that contains all of the Y data, all of the U data, and all of the V data, all back to back. The current plane is indicated in the BinkStruct. The BinkStruct also provides the dimensions of the Y plane and the U&V planes so that the data can be properly sorted out. The data in the buffer is ordered YUV unless bits 15 and 16 in the BinkStruct's flags are set to 1 (BinkStruct.flags & 0x00018000), in which case, the data is ordered YVU.
  3. Call BinkDoFrame to decode the next frame of video. Fetch the video from the BinkStruct and display, convert, manipulate as an application sees fit.
  4. Call BinkNextFrame to advance to the next frame in the file.
  5. Repeat from step 3 while there are frames remaining in the file (the number of frames is specified in the BinkStruct).
  6. Call BinkClose to deallocate the resources used for decoding the Bink file.
  7. Also, BinkGoto can be called to reposition the file during playback.
Retrieved from "https://wiki.multimedia.cx/index.php?title=RAD_Game_Tools_Bink_API&oldid=4611"