Acknowledgments

Discussion

The product name Bink, Bink Video, and the Bink logo are all copyrighted and trademarked by RAD Game Tools, Inc. Copyright 1994-2003 RAD Game Tools, Inc. All Rights Reserved. Printed and produced in the United States of America. As a licensee of Bink, you must abide by the terms set forth in your license agreement. Please refer to that agreement if you have any questions about what you may or may not do with this documentation or the software to which it pertains. Bink is not copy protected, but it is copyrighted. We think our license agreements are fair, and that our software is reasonably priced for the quality and effort we have put into it. Using our software in ways other than allowed by your license agreement violates federal, civil, and criminal law. We rely primarily on your good faith not to violate our copyright; please respect it. This software and documentation are provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. In no event will RAD Game Tools, Inc. be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the product (including, but not limited to, loss of data). Bink and Smacker were written by me, Jeff Roberts. I had lots of help, but, at the end of the day, I wrote them, I documented them, and I decided what they do and what they don't. So, if you hate 'em, then it's my fault. But if you like them, well, that's my fault too... Special thanks to Mitch Soule, John Miles, Casey Muratori, Mike Sartain, Mike Abrash, Steve Theodore, and my wife, Alicia Fukunaga, someone I try to be more like. Lee Powell wrote most of the terrific optimized x86 YUV conversion routines in Bink. John Miles wrote the original speedy x86 YUV convertors. Mark Engelberg and Jeff Roberts did the original research work on Bink. David Lawrence at Blizzard did much of the heavy lifting of porting Bink to MacOS (and he tolerated many questions). Mike Sartain did the port to GameCube and wrote several of the Xbox examples. Thanks also to Brian Kearney, Ken Coburn, Chris Hecker, Access Software, Microsoft (both for the nice tools and the tough competition), and all our Bink and Smacker licensees. RAD's automatic documentation system was written by Casey Muratori. All brand and product names mentioned in this documentation are trademarks or registered trademarks of their respective companies.


Introduction

Discussion

First off, welcome to the Bink SDK, and thanks for your purchase! This documentation will describe the Bink SDK for Win32, Xbox and MacOS programmers. We spend quite a bit of time working on our docs and hope they get you up and running fast. Please give us feedback on what worked for you and what didn't. Just as with the Bink API itself, we strive for continual improvement in our documentation as well. Your feedback is crucial in this regard! Also note that this manual actively updated, so be sure to check out these docs whenever you receive a new Bink version, so that you don't miss anything! The "Bink Overview" chapter of this manual is designed to give you a broad overview of Bink. This is the chapter to read when you're just starting out with our video APIs. Bink is very similar to Smacker, so you Smacker users will have a head-start. The "Bink under Win32" chapter will walk you through the details of using Bink under the weird but strangely compelling Win32 platform. This chapter will discuss how to use Bink specifically under the Microsoft operating systems. The "Bink on Nintendo GameCube" chapter will walk you through the details of using Bink on Nintendo's new GameCube video game console. This chapter will discuss how to use Bink specifically under this great little console. The "Bink on Xbox" chapter will walk you through the details of using Bink on Microsoft's new Xbox video game console. This chapter will discuss how to use Bink specifically under this terrific environment. The "Bink under MacOS" chapter will walk you through the details of using Bink under the aging MacOS 9 platform and the new MacOS X platform. This chapter will discuss how to use Bink specifically under Apple's operating systems. Finally, we'll wrap up with the reference section of our documentation. These reference chapters will describe each and every function in both the Bink API and our blitting API (the BinkBuffer API). Also, note that our printed documentation doesn't include everything in the online documentation. Check out the online documentation for fully hyper-linked and cross-referenced discussions - it's awesome! Again, please send feedback to me as you use Bink - what confused you, what you liked, what you hated, what you'd like to see in future versions, etc. Your feedback is what will keep Bink vital, fun to use, and powerful into the future! Thanks again,
Jeff Roberts - RAD Game Tools - E-mail.

Introduction


Bink Overview

Discussion

This section will describe the Bink SDK in the generic, non-platform-specific sense. We'll talk about creating the Bink files that you'll be playing, then we'll talk about Bink playback itself, and finally we'll wrap up with a description of the YUV colorspace that Bink uses.

Bink Overview
Compressing with Bink
Bink Video Playback
Colorspace - RGB vs. YUV
Audio Tracks in Bink
Critical File I/O handling in Bink


Compressing with Bink

Discussion

The RAD Video Tools are used to compress your video files into Bink files. These tools are supplied on the Bink SDK CD and can also be downloaded from our web-site at any time. Binking your input video files is usually as easy as highlighting the file and clicking 'Bink'. However, for all the details on compressing your files, use the "Help" button inside the RAD Video Tools window.

Next Topic (Bink Video Playback)

Group: Bink Overview


Bink Video Playback

Discussion

Bink is very different than other video codecs. Most noticeably, Bink doesn't plug into one of the monolithic video codec architectures. Instead, it stands on its own two feet, doing everything itself. While this is a little more work on the content creation side (you have to run the Bink tools and actually Bink the file), it is a huge win on the playback side - you just have to ship a single DLL, we can improve the codec much faster than the architectures are updated, we have more control over the various compression stages, we don't have to over-abstract video playback into playback of other media types, etc. Also because Bink stands on its own, we've also been able to create a clean, simple and streamlined way to playback videos. Instead of relying on complicated and difficult-to-debug callbacks or events, your application drives the Bink playback. That means that rather than calling a function like "Play" that goes away for ten minutes, you remain in control the entire time. For example, with Bink, you call a function to decompress a frame, then you call a function to move to the next frame, and then you wait until Bink says it's time to move to the next frame. While this sounds more complicated, it's actually much, much simpler. Let's look at an example. The basic code to open and close a Bink file looks like this (there will be subtle differences on a platform-basis, but this is the gist):

HBINK bink = BinkOpen( "mybink.bik", 0 );
// use the Bink handle to play the movie
BinkClose( bink );

Now that we've got a Bink handle to use, let's look at the basic playback loop:

while ( 1 ){  BinkDoFrame( bink );
  // blit the frame onto the screen here (platform specific)
  if ( bink->FrameNum == bink->Frames )    break;                  // done at the point  else    BinkNextFrame( bink );  // skip to the next frame
  while ( BinkWait( bink ) )    do_idle();              // pump message loop, process other tasks - whatever}

So, basically, we decompress a frame with BinkDoFrame, we move to the next frame with BinkNextFrame, and finally, we wait until BinkWait says that it is time to move on. Pretty simple and you've haven't given up any control at all! This example didn't show the details of blitting the video pixels onto the screen, because that is fairly platform-specific and isn't all that different from any other codec. On Win32, we even supply a high-level blitting API (called the BinkBuffer API) that makes getting the pixels onto the screen completely painless.

Next Topic (Colorspace - RGB vs. YUV)

Previous Topic (Compressing with Bink)

Group: Bink Overview
Related Functions: BinkDoFrame, BinkNextFrame, BinkWait


Colorspace - RGB vs. YUV

Discussion

A colorspace is simply the name given to a system of describing colors. The RGB colorspace is the one we're all familiar with - 8 bits for Red, Green, and Blue. Other colorspaces include CMYK (for printing), and YUV (which Bink uses internally). The YUV (or, more accurately YCrCb) colorspace uses 24 bits to represent color (like RGB), but rather than shades of red, green and blue, YUV uses luminance (kind of like brightness), and two chrominance (color) channels. There are simple formulas to convert back and forth between YUV and RGB losslessly, but this conversion does take cycles - even on a fast CPU, you're looking at 25% to 50% of the total playback time! So why does Bink use this more complicated and slower colorspace? Well, there are two reasons. First, the YUV colorspace is much less correlated than RGB. Being less correlated means that there is less redundacy across the Y, U, and V planes - the planes tend to come apart entropy-wise very cleanly, and less cross-planar redundancy means better compression. The second and more important reason for using YUV colorspace is the fact that people see luminance information much more accurately than they see color information. This means that you don't have to store a U and a V value for every Y value, because humans can't tell the difference anyway. This pre-compression technique is called "sub-sampling". Bink uses a 2 to 1 UV horizontal and vertical sub-sample - so, on a 640x480 image, we store a 640x480 Y plane, but only a 320x240 U and V plane. Bink averages each set of 4x4 pixels in the original 640x480 U and V planes to create the 320x240 U and V planes. Like Bink, MPEG and MPEG II also use a 2 to 1 UV horizontal and vertical sub-sampling. Indeo actually uses a 4 to 1 (!) UV horizontal and vertical sub-sample, but that's a little too aggressive for us and the compression community has been clamoring for Intel to release a 2 to 1 subsampling Indeo version for a long time. Most of the time, you won't have to worry about the YUV colorspace - Bink contains internal highly-optimized routines that automatically convert the YUV data into RGB data. However, interestingly, many video cards also have hardware to convert between YUV and RGB colorspace. This is really cool in theory, because the hardware could do this tricky colorspace conversion faster than our software conversion routines. Unfortunately there's always that pesky reality lurking behind the theory, but more on that in the platform specific chapters.

Previous Topic (Bink Video Playback)

Group: Bink Overview
Related Sections: Scaling


Audio Tracks in Bink

Discussion

Bink allows any number of audio tracks to be added to a Bink file. You can decompress or not decompress any tracks you wish. You could, for example, store all the music in one track, and multiple languages in other tracks. Each audio track in Bink is either a mono or stereo track. The person creating the Bink files chooses a new track ID for each audio file that is mixed in (by default, track zero is used). Generally, audio is automatically routed by Bink to your sound library automatically. You just specify the tracks you want to play with the BinkSetSoundTrack functions and Bink takes care of the rest. The Bink high-level audio functions (BinkSetSoundTrack, BinkSetVolume and BinkSetPan) all take track IDs. These are the same numbers that the person mixing in the audio uses in the RAD Video Tools. So, usually, you simply need to set some standard - track 0 is the music, track 1 is English, track 2 is French, etc. Then, your game can select the correct tracks to start and control with simple defines that specify which localization you are building. Bink also has low-level audio functions that let you query what audio tracks are present and extract the PCM samples directly. These functions take a track index rather than a track ID. A track index ranges from zero to the total number of tracks in the Bink file. So, you could have track IDs of 42 and 118, or, 65 and 12, but the track indexes will still range from zero to one. You can get the total number of audio tracks in a Bink file by looking at the NumTracks field of the BINK structure. You can correlate a track index to a track ID with the BinkGetTrackID function. As noted above, though, you normally just let Bink handle the audio details and you simply choose which tracks to play.

Previous Topic (Colorspace - RGB vs. YUV)

Group: Bink Overview
Related Sections: Sound on the Nintendo GameCube, Sound on the Xbox, Sound under MacOS, Sound under Win32
Related Functions: BinkGetTrackID, BinkSetMixBinVolumes, BinkSetMixBins, BinkSetPan, BinkSetSoundTrack, BinkSetVolume
Related Structures: BINK


Critical File I/O handling in Bink

Discussion

Bink is very conservative about critical errors encountered during playback. We would rather end a movie too soon than potentially crash due to a bad data read. When Bink encounters an I/O error, it will set the ReadError field in the BINK structure to non-zero, and will then skip all remaining frames. This means that if you don't check for I/O errors, then your playback logic will end normally and you won't have to do anything special. If you do want to watch for I/O errors (to display an error message, for example), then you just need to check for ReadError going to non-zero after each call to BinkNextFrame. If you want to restart the movie after an error, then you must close the Bink movie, and then reopen it again. To pick up where you left off in the playback, you can use the BinkGoto function to jump to the right location.

Previous Topic (Audio Tracks in Bink)

Group: Bink Overview
Related Functions: BinkGoto, BinkNextFrame
Related Structures: BINK


The Win32 Platform

Discussion

Bink was first developed on the Win32 platform. Win32 is both wonderful and horrible - often simultaneously. Bink is extremely easy to use and integrate under this platform. This chapter will discuss everything you need to know!

The Win32 Platform
Installation for Win32
Integrating Bink into a Win32 Build Environment
Distributing the Bink DLL under Win32
Bink Playback under Win32
Pros and Cons of Software Blitting under Win32
Pros and Cons of YUV Overlays under Win32
Pros and Cons of YUV Off-screen Buffers under Win32
BinkBuffers to the Rescue
Sound under Win32
Memory management under Win32
Sharing the CPU under Win32
Bink Examples for Win32


Installation for Win32

Discussion

The Bink installer will be launched automatically when you insert the Bink SDK CD into an auto-play capable machine. If auto-play is not enabled on your machine, you can run the installation program manually by executing Bink.exe in the root directory of the Bink SDK CD.
Once the installer has launched, you will be presented with four installation options. These are:
1) Install Bink SDK, which will install the files you need to build programs that incorporate Bink Video.
2) Install RAD Video Tools, which will install the tools used to compress video files into Bink or Smacker formats.
3) Install Miles Sound System demos, which will install demonstrations of RAD's audio technology product.
4) Install Granny demos, which will install demonstrations of RAD's 3D animation product.
All installation options are largely automatic, and will not require much further user input unless you would like to change an installation parameter such as the installation directory.

Next Topic (Integrating Bink into a Win32 Build Environment)

Group: The Win32 Platform


Integrating Bink into a Win32 Build Environment

Discussion

To build an application that uses Bink Video, you must include the Bink SDK in the build process. There are four simple steps to do this: 1) Add the Bink SDK directory to your include and library directories in your project. 2) Include Bink.h in your source files. 3) Link with the BinkW32.lib import library. 4) Place the BinkW32.DLL file in the directory containing your application. And that's it - you should now be able to use Bink!

Next Topic (Distributing the Bink DLL under Win32)

Previous Topic (Installation for Win32)

Group: The Win32 Platform


Distributing the Bink DLL under Win32

Discussion

To distribute an application that uses Bink, you must include the Bink DLL (BinkW32.DLL) in the same directory as your application.
Do not place the BinkW32.DLL in the Windows or the Windows System directories! The BinkW32.DLL must be placed in your application directory!

Next Topic (Bink Playback under Win32)

Previous Topic (Integrating Bink into a Win32 Build Environment)

Group: The Win32 Platform


Bink Playback under Win32

Discussion

True-color video playback under Windows is tricky for several reasons. First off, true color codecs (including Bink) generally don't operate in RGB colorspace, but rather YUV. Secondly, Windows video drivers are generally slower and more bug prone in high-color than 256 colors. Other minor difficulties include a complicated blitting architecture and no asynchronous reads under Win95/98 (which Bink gets around by doing I/O on another thread). I suppose the good news, however, is that using true color means that you never have to wrestle with the palette manager again! On the Windows platform, Bink includes incredibly fast YUV to RGB software conversion routines. We include MMX and non-MMX, 1x and 2x width, height interlacing, height doubling, alpha plane merging, and color or grayscale routines that can copy into 16-bit, 24-bit and 32-bit RGB formats. The permutations total 120 different hand-optimized assembly conversion routines - whew! In fact, unsurprisingly, the majority of the BinkW32.DLL is the colorspace converters. We wrote all of these different YUV to RGB converters because we've found the YUV to RGB hardware on PC video cards to be fairly unreliable - especially when flipping video modes or using the video card's 3D features (which means, sigh, pretty much all PC video games). This means you have a choice between software and, if it is available, hardware blitting. Video cards currently can provide two types of YUV hardware converts - YUV overlays and YUV off-screen buffers. YUV overlays are really amazing when they work - they are basically windows on the desktop that live at a different color resolution than the desktop! You could have a YUV true color overlay being displayed while the rest of the Windows desktop is being displayed at even 256 colors, for example. Fewer cards support overlays than off-screen buffers. YUV off-screen buffers are simply DirectDraw secondary surfaces that convert from YUV to RGB when you blit them onto the primary surface. They are nice because you get things like clipping for free. The conversion technique (software, overlays, or off-screens) that you choose for your game depends on several factors. Let's look at the pros and cons of each technique...

Next Topic (Pros and Cons of Software Blitting under Win32)

Previous Topic (Distributing the Bink DLL under Win32)

Group: The Win32 Platform
Related Sections: Alpha Planes


Pros and Cons of Software Blitting under Win32

Discussion

The RAD software blitters are good, because: 1) They always work and always look the same. You don't have to worry about the hardware failing or behaving weirdly. 2) They are actually faster than hardware on high-end machines like Pentium IIIs and Athlons. 3) They scale better - the faster the machine the faster the blitting (that also works in reverse, though - the slower the machine the slower the blitting). 4) You get guaranteed stretching for 2x width, 2x height, and 2x width and height. Some YUV hardware can't do any stretching at all!
The RAD software blitters are bad, because: 1) It's even more thinking for the CPU to do! On a PII and up, doing the blitting is no big deal. On lower-end machines like Pentiums and K-6s, software blitting will chew up a lot of time (you can use the 1x interlaced mode to save time on these machines, though). 2) The software blitters do no clipping at all.

Next Topic (Pros and Cons of YUV Overlays under Win32)

Previous Topic (Bink Playback under Win32)

Group: The Win32 Platform


Pros and Cons of YUV Overlays under Win32

Discussion

YUV Overlays are good, because: 1) They are super-fast (you don't blit them to the screen, you just draw onto the surface and the pixels appear). 2) They have clipping built-in. 3) They float above your application, so they don't disturb anything in your application. 4) They can do shrinking and stretching for free, CPU-wise.
YUV overlays are bad, because: 1) They are hardware (so you are at the mercy of the video card and video card DirectDraw drivers). 2) They can look different on different video cards (especially when stretching). 3) They float above your application, so it's hard to make them seem completely integrated into your application. 4) They are usually disabled when Direct3D is running.

Next Topic (Pros and Cons of YUV Off-screen Buffers under Win32)

Previous Topic (Pros and Cons of Software Blitting under Win32)

Group: The Win32 Platform


Pros and Cons of YUV Off-screen Buffers under Win32

Discussion

YUV off-screen buffers are good because: 1) They are fast (fast, that is, as long as the YUV conversion is done in hardware - some DirectDraw drivers do the conversion on the host CPU). 2) They can usually perform clipping for free. 3) They basically work like just like a normal blitter (so they aren't any different than plain old off-screen blitters that we all know how to use). 4) They can do shrinking and stretching for free, CPU-wise.
YUV converting-blitters are bad, because: 1) Again, they are in hardware, so you are at the mercy of the video hardware and drivers working correctly. 2) They can be doing the conversion in software and not telling you. 3) They can look different on different video cards (again, especially when stretching).

Next Topic (BinkBuffers to the Rescue)

Previous Topic (Pros and Cons of YUV Overlays under Win32)

Group: The Win32 Platform


BinkBuffers to the Rescue

Discussion

So, which technology should you use? Bink's built-in software, overlays, or off-screen buffers? To help with this dilemma, Bink includes the BinkBuffer API. BinkBuffers hide a bunch of the DirectDraw complexity to make switching between the various colorspace options really easy. The Bink player, the ExamW32.C example, and the ExamMSS.C example all use the BinkBuffer API to make displaying Bink frames simple. Note, however, that the BinkBuffer API is fairly high-level, so if you've already got DirectDraw or Direct3D running in your application, you may simply want to skip BinkBuffers completely and use the internal Bink software routines to convert directly onto the primary or a secondary surface. See the ExamDDP.C file for an example of this type of playback.

Next Topic (Sound under Win32)

Previous Topic (Pros and Cons of YUV Off-screen Buffers under Win32)

Group: The Win32 Platform


Sound under Win32

Discussion

For sound support under Windows, Bink includes drivers for the Miles Sound System and DirectSound. See the descriptions of BinkSoundUseMiles and BinkSoundUseDirectSound for details on sound integration. In general, you will simply have to call one of these two functions to start playing Bink sound - everything else is handled automatically.

Next Topic (Memory management under Win32)

Previous Topic (BinkBuffers to the Rescue)

Group: The Win32 Platform
Related Sections: Audio Tracks in Bink
Related Functions: BinkSoundUseDirectSound, BinkSoundUseMiles


Memory management under Win32

Discussion

By default, Bink handles memory management by calling the Windows memory functions directly. You can, however, replace the Bink allocation and freeing functions with the RADSetMemory function. You can see how much memory is being used and what the peak use was with the BinkGetSummary function.

Next Topic (Sharing the CPU under Win32)

Previous Topic (Sound under Win32)

Group: The Win32 Platform
Related Functions: BinkGetSummary, RADSetMemory


Sharing the CPU under Win32

Discussion

Under Win32, to be polite, we are encouraged to share the processor time with other applications. To do this, we have to process messages while we're waiting for each frame. Bink handles timing with the BinkWait function, so we just need to check this function whenever we're not processing a message. So, we'll simply monitor the BinkWait function in our message loop - when BinkWait tells us that it's time for the next frame, we'll just call the code to advance a frame. A simple example of Windows playback would look something like this:

for ( ; ; ){  // check for a Windows message  if ( PeekMessage( &msg, 0, 0, 0, PM_REMOVE ) )  {    if ( msg.message == WM_QUIT )      break;
    TranslateMessage( &msg );    DispatchMessage( &msg );   }   else   {     // no Windows message, so check on our playback     if ( !BinkWait( bink ) )     {       // go process the next Bink frame       Show_next_frame( bink, bink_buf );     }   }}

Next Topic (Bink Examples for Win32)

Previous Topic (Memory management under Win32)

Group: The Win32 Platform
Related Functions: BinkWait


Bink Examples for Win32

Discussion

The Bink SDK supplies several example programs for Win32. To create these examples in an IDE-based environment, just create a new project and include the appropriate C source file (ExamW32.C, ExamMSS.C, or ExamDDP.C), and then add the Bink for Windows import library to the project (BinkW32.LIB).
The following is a list of the example files that you can experiment with:
For an example player using the BinkBuffer API, see the "ExamW32.C" file.
For an example player using the Miles Sound System and the BinkBuffer API, see the "ExamMSS.C" file.
For an example player using DirectDraw, see the "ExamDDP.C" file.
For an example of using a Bink alpha plane with OpenGL, see the "ExamAlph.C" file. This example can use OpenGL or Direct3D - to use OpenGL just link with the "GLRAD3D.C" file.
For an example of using a Bink alpha plane with Direct3D 8, see the "ExamAlph.C" file. This example can use OpenGL or Direct3D - to use Direct3D just link with the "DX8RAD3D.CPP" file. For an example of using a Bink alpha plane with Direct3D 7, see the "ExamAlph.C" file. This example can use OpenGL or Direct3D - to use Direct3D just link with the "DX7RAD3D.CPP" file.

Previous Topic (Sharing the CPU under Win32)

Group: The Win32 Platform
Related Sections: Alpha Planes, Direct3D, OpenGL


The Nintendo GameCube Platform

Discussion

Bink now runs on Nintendo's wonderful new GameCube console! The GameCube is a great little box - super GPU and excellent CPU! The OS on GameCube is especially nice - lean and mean just like you want on a console. We have been able to really great performance out of this box! Bink is extremely easy to use and integrate under this platform. This chapter will discuss everything you need to know!

The Nintendo GameCube Platform
Installation for the Nintendo GameCube
Integrating Bink into an Nintendo GameCube Build Environment
Distributing Bink on the Nintendo GameCube
Bink Playback on the Nintendo GameCube
NTSC and PAL on the Nintendo GameCube
Gamma on the Nintendo GameCube
Sound on the Nintendo GameCube
Memory management on the Nintendo GameCube
Sharing the CPU on the Nintendo GameCube
Bink Examples for the Nintendo GameCube


Installation for the Nintendo GameCube

Discussion

The Bink installer will be launched automatically when you insert the Bink SDK CD into your Windows 9x or Windows NT development machine. If auto-play is not enabled on your Win32 machine, you can run the installation program manually by executing BinkNGC.exe in the root directory of the Bink SDK CD.
All installation options are largely automatic, and will not require much further user input unless you would like to change an installation parameter such as the installation directory.

Next Topic (Integrating Bink into an Nintendo GameCube Build Environment)

Group: The Nintendo GameCube Platform


Integrating Bink into an Nintendo GameCube Build Environment

Discussion

To build an application that uses Bink Video, you must include the Bink SDK in the build process. There are three simple steps to do this: 1) Add the Bink SDK directory to your include and library directories in your project. 2) Include Bink.h in your source files. 3) Link with the BinkNGC.a static library - Bink is directly linked into your application! And that's it - you should now be able to use Bink!

Next Topic (Distributing Bink on the Nintendo GameCube)

Previous Topic (Installation for the Nintendo GameCube)

Group: The Nintendo GameCube Platform


Distributing Bink on the Nintendo GameCube

Discussion

To distribute an application that uses Bink, you don't have to include anything other than your ELF and the Bink movies that you want to play. Bink is supplied as a static library that is linked directly into your application, so nothing else is required.

Next Topic (Bink Playback on the Nintendo GameCube)

Previous Topic (Integrating Bink into an Nintendo GameCube Build Environment)

Group: The Nintendo GameCube Platform


Bink Playback on the Nintendo GameCube

Discussion

Video playback on the Nintendo GameCube is pretty easy compared to a PC or Mac - the hardware is damn fast and, most importantly, it is constant. If it plays back perfectly on your machine, then it will on everyone else's too! You have a couple options for blitting the video frames onto the screen with a GameCube - copying to the back buffer, or copying to a texture and then rendering. The simplest way is definitely the back buffer option - just have Bink copy its YUV data directly to your screen's YUV back buffer. This is also the highest performance method, because not only do you keep the renderer out of the loop, but Bink doesn't even have to convert from its internal YUV format. Very fast, very simple. See the "ExamNbb.C" for an example of this kind of playback. The more flexible option is to have Bink copy into a texture, and then render that texture onto the screen. This lets you do all kinds of sophisticated stuff like alpha transluncency, animated textures, video in a window with 3D objects in the scene, etc. The GameCube's texture formats are nice and simple. First off, they can be non-power-of-2 which is really nice for video. However, they do have to be swizzled to the GPU's internal format (which is usually painful). Fortunately, the BinkCopyToBuffer functions, automatically swizzle the pixels as it converts its YUV data into the RGB destination. That means you simply need to call BinkCopyToBuffer to move the pixels from Bink's YUV buffers into your RGB texture and your texture is ready! Note that due to the swizzled output, you must use divisible-by-four values for the X offset, Y offset, width, and height parameters in BinkCopyToBuffer on the GameCube. See the "ExamNTex.C" for an example of this kind of playback.

Next Topic (NTSC and PAL on the Nintendo GameCube)

Previous Topic (Distributing Bink on the Nintendo GameCube)

Group: The Nintendo GameCube Platform
Related Sections: Alpha Planes
Related Functions: BinkCopyToBuffer


NTSC and PAL on the Nintendo GameCube

Discussion

NTSC is the refresh standard for TVs in the United States. PAL is the refresh standard for TVs in Europe. These two standards are pretty quirky and pretty different, so you'll have to deal with several issues when playing back your movies: 1) The frame rate on NTSC is 29.97 fps (59.94 fields per second), rather than PAL's is 25 fps (50 fields). You really can't handle this adjustment at compression time or playback time - it will always just look a little wrong to play a 30 fps video at 25 fps. You'll usually see this problem when watching a slow pan - since you will be skipping every 5th frame, the video will pan smoothly, then jump, then pan, then jump, etc. You can't even fix the problem at compression time - you've still got the same sampling problem. So, unfortunately, the only way to fix it completely is to re-render or re-capture your video at 25 fps. Note that if you just don't care and want to play the 30 fps video at 25 fps anyway, then you also need to decouple the decompression and blitting steps in your Bink playback loop. Instead of decompress, blit, decompress, blit, etc (which will be too slow at 25 fps and will start skipping), you need to decompress all of the frames that are pending, then blit, decompress all, then blit, etc. We don't recommend this, though - you should really re-create the source material instead. (Gaming magazines in Europe routinely flame games for poor PAL conversion issues, so be warned).
2) On NTSC, 29.97 fps is NOT 30 fps! This is probably the most common technical support issue on consoles. You can't author a 30 fps movie and play it when your page flipping is set to 29.97 - the flipping won't be fast enough! You'll either: start losing sync with the audio, or frames will start skipping, or the audio will drop out, etc. There are several ways to deal with this. The best is to just create correct 29.97 material (30,000 / 1,001 fps) and then not use BinkWait to do the timing (let the page flipping determine the frame rate). You can also use BinkSetFrameRate to adjust the frame rate of the movie to 29.97 and let the page flipping control the frame rate as in the previous paragraph. Another option is to decouple the decompression from the page flipping. This means one frame every three seconds won't be displayed (but at least you won't lose sync, or drop frames which is worse). However, for the same reasons as the 30 fps to 25 fps issues above, we don't recommend this - it looks terrible once you know what to look for. Re-author the material, or adjust it to 29.97, both solutions look much better than letting frames be skipped.
3) The gamma on PAL is usually about 2.8 instead of NTSC's 2.2 (and PC monitors are 2.5). This means that if you adjust the gamma to look good on NTSC, then it is going to look really dark on PAL. You can split the difference by leaving the gamma alone (at PC levels), but then the video isn't going to look good on either platform! See the "Gamma on the Nintendo GameCube" section for more details on gamma issues.
4) PAL doesn't have "off-limits" colors - they can be fully saturated. You can read about other color differences on Gamasutra.
5) PAL uses slightly a different aspect ratio. Instead of NTSC's 720x480, PAL uses 720x576. If you configure the screen to 640x480, then the hardware will scale to full-screen, so the aspect change won't matter. However, if you use the native modes (which look the best, because there is less filtering), then movies that look great on an NTSC TV, will look squashed on PAL. On some videos this is very noticeable, on others, you can barely tell at all. People look the worst - your game's macho lead character can accidentally look seriously bloated if you forget to handle this (another issue commonly mocked in European game mags). Since you use textures to display frames of Bink video, it's fairly easy to stretch the output a bit to account for the difference. Just shrink the vertical size, or stretch the horizontal size (or re-create the source material).

Previous Topic (Bink Playback on the Nintendo GameCube)

Group: The Nintendo GameCube Platform
Related Sections: Gamma on the Nintendo GameCube
Related Functions: BinkSetFrameRate, BinkWait


Gamma on the Nintendo GameCube

Discussion

On an NTSC TV, the gamma ramp is set to a 2.2 curve. PC monitors use a 2.5 curve. This means that if a movie looks great on a PC, you need to adjust it slightly for good looking playback on a TV. Otherwise, the video will appear to be washed out. If you are compressing CGI scenes, then the best way to handle this is just to set the gamma to 2.2 in your rendering options. It will look a little dark on your PC monitor, but will look great on a TV. If you are capturing video, check out the documentation on the capture software to find the gamma control options. If you can't re-generate original video directly at 2.2, then you can use Bink's built-in gamma adjuster. Just set the gamma option in the Bink compression window to 0.88 to convert from PC 2.5 gamma video to NTSC 2.2 gamma. On a PAL TV, the gamma ramp is set to a 2.8 curve. Again, the best way to deal with this difference is to just recreate the original material (re-render or re-capture). If you can't, however, you can set the gamma option in the Bink compression window to 1.12 to convert from PC 2.5 gamma to PAL 2.8 gamma.

Next Topic (Sound on the Nintendo GameCube)

Previous Topic (NTSC and PAL on the Nintendo GameCube)

Group: The Nintendo GameCube Platform
Related Sections: NTSC and PAL on the Nintendo GameCube


Sound on the Nintendo GameCube

Discussion

For sound support on the Nintendo GameCube, Bink can talk to either the AX audio library or MusyX audio library which in turn talks to the GameCube hardware. Note that the GameCube's hardware DSP runs at 32028 Hz, so any audio frequencies higher than that simply get filtered out. This means you should usually preconvert your audio tracks down to 32028 Hz at authoring time (but Bink can down-convert audio tracks at runtime for a small CPU hit, though). Now let's describe the steps to get AX or MusyX support working (you should also check out ExamNbb.C - it's a simple example that can support AX or MusyX). To use Bink's built-in AX support, you have to perform these three steps (only the third step if you are already playing audio with AX): 1) You have to set up the audio hardware subsystems prior to calling into Bink. This means calling the following code:

  ARInit( aramMemArray, MAX_ARAM_BLOCKS );  ARQInit( );  AIInit( 0 );

2) Next, you must set up the AX library prior to calling Bink. You also usually want to turn the dynamic compressor off for pre-authored. This code looks like this:

  AXInit( );  AXSetCompressor( AX_COMPRESSOR_OFF );

3) Finally, you need to tell Bink to actually use AX by calling the BinkSoundUseAX function. This function also needs the two callbacks to use for requesting audio buffer RAM. So, the code for this step looks something like this:

  void *aram_malloc( U32 num_bytes )  {    return( ( void * ) ARAlloc( num_bytes ) );  }
  void aram_free( void * ptr )  {    U32 length;    ptr = ptr; // ARFree always frees the last pointer allocated    ARFree( &length );  }
  RADARAMCALLBACKS aram_callbacks = { aram_malloc, aram_free };  BinkSoundUseAX( &aram_callbacks );

And that's it - the AX users should be hearing sound now! The setup for MusyX users is just as easy. To start Bink's support for MusyX, follow these similar 3 steps (again, only the third step is necessary if you are already playing audio with MusyX): 1) You have to set up the audio hardware subsystems prior to calling into Bink. This means calling the following code:

  ARInit( aramMemArray, MAX_ARAM_BLOCKS );  ARQInit();  AIInit( 0 );

2) Next, you must set up the MusyX library prior to calling Bink. This code looks something like this:

  sndSetHooks( &ram_callbacks );  sndInit( 16, 8, 8, 1, SND_FLAGS_DEFAULT, 8 * 1024 * 1024 );

3) Finally, you need to tell Bink to actually use MusyX by calling the BinkSoundUseMusyX function. The code for this step is simply:

  BinkSoundUseMusyX( );

And that's it - Bink takes care of everything else!

Next Topic (Memory management on the Nintendo GameCube)

Previous Topic (Gamma on the Nintendo GameCube)

Group: The Nintendo GameCube Platform
Related Sections: Audio Tracks in Bink
Related Functions: BinkSoundUseAX, BinkSoundUseMusyX


Memory management on the Nintendo GameCube

Discussion

By default, Bink handles memory management by calling the OS memory allocation functions directly. You can, however, replace the Bink allocation and freeing functions with the RADSetMemory function. You can see how much memory is being used and what the peak use was with the BinkGetSummary function.

Next Topic (Sharing the CPU on the Nintendo GameCube)

Previous Topic (Sound on the Nintendo GameCube)

Group: The Nintendo GameCube Platform
Related Functions: BinkGetSummary, RADSetMemory


Sharing the CPU on the Nintendo GameCube

Discussion

On the Nintendo GameCube, you don't have to share the CPU with the OS at all! This is the bonus of working on a console - you can hog all the CPU you want! This means the typical Nintendo GameCube Bink playback loop is very simple. Bink handles timing with the BinkWait function, so we just need to check this function while we're playing a video. So, a simple example of Nintendo GameCube playback would look something like this:

for ( ; ; ){   // check on our playback
   if ( !BinkWait( bink ) )   {     // go process the next Bink frame     Show_next_frame( bink, texture );   } }}

Next Topic (Bink Examples for the Nintendo GameCube)

Previous Topic (Memory management on the Nintendo GameCube)

Group: The Nintendo GameCube Platform
Related Functions: BinkWait


Bink Examples for the Nintendo GameCube

Discussion

The Bink SDK supplies several example programs for Nintendo GameCube. To create these examples with SN Systems or CodeWarrior, just create a new project and include the appropriate C source file (ExamNbb.C, ExamNTex.C or ExamNAlf.C), and then add the Bink for Nintendo GameCube static library to the project (BinkNGC.a).
The following is a list of the example files that you can experiment with:
For an example of using Bink to display a video directly to the GameCube's YUV back buffer, see the "ExamNbb.C" file. This example is extremely simple because it doesn't use the GPU to render the video - it's just blasts it right to the back buffer. It's also very fast, because Bink doesn't have to convert out of YUV format.
For an example of using Bink to decompress onto a texture and then render the texture to the screen, see the "ExamNTex.C" file. This example uses our simple 3D wrapper, so be sure to also add the "NGCRAD3D.C" file to your project. Bink converts from YUV format directly into the GameCube's swizzled format inside the BinkCopyToBuffer function, so you can render the texture immediately! For an example of using Bink with alpha videos and then render the textures to the screen, see the "ExamNAlf.C" file. This example also uses our simple 3D wrapper, so be sure to also add the "NGCRAD3D.C" file to your project. You can download a small alpha test movie from our ftp-site. All of these examples also use a simple file to setup the GameCube for use, so you'll also need to include "NGCDemo.c" in your sample projects.

Previous Topic (Sharing the CPU on the Nintendo GameCube)

Group: The Nintendo GameCube Platform
Related Sections: Alpha Planes
Related Functions: BinkCopyToBuffer


The Xbox Platform

Discussion

Bink now runs on Microsoft's new Xbox game console! The Xbox is incredibly fun to work with - all the good things about Windows with almost all of the annoying things removed. We've all become huge fans of the Xbox here at RAD! Bink is extremely easy to use and integrate under this platform. This chapter will discuss everything you need to know!

The Xbox Platform
Installation for the Xbox
Integrating Bink into an Xbox Build Environment
Distributing Bink on the Xbox
Bink Playback on the Xbox
Sections on the Xbox
NTSC and PAL on the Xbox
Gamma on the Xbox
Sound on the Xbox
Memory management on the Xbox
Sharing the CPU on the Xbox
Bink Examples for the Xbox


Installation for the Xbox

Discussion

The Bink installer will be launched automatically when you insert the Bink SDK CD into your Windows 9x or Windows NT development machine. If auto-play is not enabled on your Win32 machine, you can run the installation program manually by executing BinkXbox.exe in the root directory of the Bink SDK CD.
All installation options are largely automatic, and will not require much further user input unless you would like to change an installation parameter such as the installation directory.

Next Topic (Integrating Bink into an Xbox Build Environment)

Group: The Xbox Platform


Integrating Bink into an Xbox Build Environment

Discussion

To build an application that uses Bink Video, you must include the Bink SDK in the build process. There are three simple steps to do this: 1) Add the Bink SDK directory to your include and library directories in your project. 2) Include Bink.h in your source files. 3) Link with either the BinkXbox.lib static library or the BinkXbox.LTCG.lib link-time-code-generatation static library. The LTCG version is both a little smaller and a little faster, but will cause the link to finish more slowly. Either way Bink is directly linked into your application! And that's it - you should now be able to use Bink!

Next Topic (Distributing Bink on the Xbox)

Previous Topic (Installation for the Xbox)

Group: The Xbox Platform


Distributing Bink on the Xbox

Discussion

To distribute an application that uses Bink, you don't have to include anything other than your XBE and the Bink movies that you want to play. Bink is supplied as a static library that is linked directly into your application, so nothing else is required.

Next Topic (Bink Playback on the Xbox)

Previous Topic (Integrating Bink into an Xbox Build Environment)

Group: The Xbox Platform


Bink Playback on the Xbox

Discussion

Video playback on the Xbox is pretty easy compared to a PC - the hardware is damn fast and, most importantly, it is constant. If it plays back perfectly on your machine, then it will on everyone else's too! The other nice thing is that the Xbox gives you so many ways to get video onto the screen. You can use an overlay (by far the easiest way to go), a YUV format D3D texture, a RGB linear format D3D texture (for alpha), or just dump it on the backbuffer before you flip! Overlays are the easiest way to get video into your game. Overlays float over the frame buffer pixels, so they don't disturb anything else in your game. Your rendering and page-flipping code all stays exactly the same with overlays. This is definitely the way to put simple cut-scenes in your game. Overlays can't be textured (but they can be scaled), and they can't do translucency (but they can do color-keyed on/off transparency). See ExamXbox.cpp for an example of using Xbox overlays with Bink. The next display method is using a YUV format texture. Bink's native format is YUV, so it can copy into a YUV texture very quickly. The Xbox graphics chip can then do the conversion to RGB as it renders the texture. This is very fast, and very flexible because you can use the video as a texture for any surface in your game (a TV monitor in a scene for example). The only downside to this method is that YUV textures can't contain an alpha plane. See ExamXTex.cpp for an example of using Xbox YUV textures with Bink. If you need to use an alpha plane, then Bink still has you covered. Just use an RGB format texture like 16-bit RGBA 4444, or 32-bit RGBA 8888 (which Bink can convert directly into using internal super-optimized software converters). The Xbox hardware helps you here too - it supports linear RGB textures, so that you don't even have to swizzle the video frames before passing it to Direct3D. To allocate a linear texture, you just use one of the textures with "_LIN_" in the D3DFORMAT enumerant name. You also have to be careful to select clamping for linear textures - tiling and mirroring isn't supported when using this texture format. See ExamXAlf.cpp for an example of using Xbox alpha RGB textures with Bink. Finally, you can simply lock the video back buffer, and just have Bink copy the video frame directly into the buffer pixels. This is a pretty easy way to get Bink running in your game, but overlays are just about as easy and usually much faster. See ExamXbb.cpp for an example of using the Xbox back buffer with Bink. Video on the Xbox really is an embarassment of riches - you've just got tons of options! To summarize: If you just want to play plain-old, straight-on video (cut-scenes), use overlays. If you want the video textured onto an object, use a YUV texture. If you need alpha support, use a linear RGB texture.

Next Topic (Sections on the Xbox)

Previous Topic (Distributing Bink on the Xbox)

Group: The Xbox Platform
Related Sections: Alpha Planes


Sections on the Xbox

Discussion

Sections are the Xbox's version of overlays. They allow you to link with the Bink static library, but still unload the memory when you aren't actively playing a movie. See the BinkLoad and BinkLoadConverter functions to see how to unload Bink when not in use.

Next Topic (NTSC and PAL on the Xbox)

Previous Topic (Bink Playback on the Xbox)

Group: The Xbox Platform
Related Functions: BinkLoad, BinkLoadConverter


NTSC and PAL on the Xbox

Discussion

NTSC is the refresh standard for TVs in the United States. PAL is the refresh standard for TVs in Europe. These two standards are pretty quirky and pretty different, so you'll have to deal with several issues when playing back your movies: 1) The frame rate on NTSC is 29.97 fps (59.94 fields per second), rather than PAL's is 25 fps (50 fields). You really can't handle this adjustment at compression time or playback time - it will always just look a little wrong to play a 30 fps video at 25 fps. You'll usually see this problem when watching a slow pan - since you will be skipping every 5th frame, the video will pan smoothly, then jump, then pan, then jump, etc. You can't even fix the problem at compression time - you've still got the same sampling problem. So, unfortunately, the only way to fix it completely is to re-render or re-capture your video at 25 fps. Note that if you just don't care and want to play the 30 fps video at 25 fps anyway, then you also need to decouple the decompression and blitting steps in your Bink playback loop. Instead of decompress, blit, decompress, blit, etc (which will be too slow at 25 fps and will start skipping), you need to decompress all of the frames that are pending, then blit, decompress all, then blit, etc. We don't recommend this, though - you should really re-create the source material instead. (Gaming magazines in Europe routinely flame games for poor PAL conversion issues, so be warned).
2) On NTSC, 29.97 fps is NOT 30 fps! This is probably the most common technical support issue on the Xbox. You can't author a 30 fps movie and play it when your page flipping is set to 29.97! Your max frame rate will be 29.97 fps and the movie is 30 fps - it's impossible to keep up! You'll either start losing sync with the audio, or frames will start skipping, or the audio will drop out, etc. There are several ways to deal with this. The best is to just create correct 29.97 material (30,000 / 1,001 fps) and then not use BinkWait to do the timing (let the page flipping determine the frame rate). You can also use BinkSetFrameRate to adjust the frame rate of the movie to 29.97 and let the page flipping control the frame rate as in the previous paragraph. Another option is to let Bink skip frames to keep up. However, for the same reasons as in the 30 fps to 25 fps issue above, we don't recommend this - it looks terrible once it's been pointed out. Re-author the material, or adjust it to 29.97, both solutions look much better than letting frames be skipped.
3) The gamma on PAL is usually about 2.8 instead of NTSC's 2.2 (and PC monitors are 2.5). This means that if you adjust the gamma to look good on NTSC, then it is going to look really dark on PAL. You can split the difference by leaving the gamma alone (at PC levels), but then the video isn't going to look good on either platform! See the "Gamma on the Xbox" section for more details on gamma issues.
4) PAL doesn't have "off-limits" colors - they can be fully saturated. You can read about other color differences on Gamasutra.
5) PAL uses slightly a different aspect ratio. Instead of NTSC's 720x480, PAL uses 720x576. If you configure the screen to 640x480, then the hardware will scale to full-screen, so the aspect change won't matter. However, if you use the native modes (which look the best, because there is less filtering), then movies that look great on an NTSC TV, will look squashed on PAL. On some videos this is very noticeable, on others, you can barely tell at all. People look the worst - your game's macho lead character can accidentally look seriously bloated if you forget to handle this (another issue commonly mocked in European game mags). Since you use textures to display frames of Bink video, it's fairly easy to stretch the output a bit to account for the difference. Just shrink the vertical size, or stretch the horizontal size (or re-create the source material).

Previous Topic (Sections on the Xbox)

Group: The Xbox Platform
Related Sections: Gamma on the Xbox
Related Functions: BinkSetFrameRate, BinkWait


Gamma on the Xbox

Discussion

On an NTSC TV, the gamma ramp is set to a 2.2 curve. PC monitors use a 2.5 curve. This means that if a movie looks great on a PC, you need to adjust it slightly for good looking playback on a TV. Otherwise, the video will appear to be washed out. If you are compressing CGI scenes, then the best way to handle this is just to set the gamma to 2.2 in your rendering options. It will look a little dark on your PC monitor, but will look great on a TV. If you are capturing video, check out the documentation on the capture software to find the gamma control options. If you can't re-generate original video directly at 2.2, then you can use Bink's built-in gamma adjuster. Just set the gamma option in the Bink compression window to 0.88 to convert from PC 2.5 gamma video to NTSC 2.2 gamma. On a PAL TV, the gamma ramp is set to a 2.8 curve. Again, the best way to deal with this difference is to just recreate the original material (re-render or re-capture). If you can't, however, you can set the gamma option in the Bink compression window to 1.12 to convert from PC 2.5 gamma to PAL 2.8 gamma.

Next Topic (Sound on the Xbox)

Previous Topic (NTSC and PAL on the Xbox)

Group: The Xbox Platform
Related Sections: NTSC and PAL on the Xbox


Sound on the Xbox

Discussion

For sound support on the Xbox, Bink hooks directly to DirectSound. You don't have to to anything special at all - everything is handled automatically. If you aren't going to play a 5.1 soundtrack, then Bink will automatically route the default stereo or mono sound track to all of the 5.1 speakers. If you are going to play 5.1 soundtracks with Bink, then you need to setup the Bink file and your playback code using these tips. The first step in 5.1 playback is to make a Bink file that contains multiple audio tracks (check out the Audio-tracks-in-Bink section for more information on audio tracks). You use the Bink Sound Mixer to mix in each of the separate audio tracks. Author the multiple sound tracks like this: Track ID 0 - A stereo track containing the front left and front right channels. Track ID 1 - A mono track containing the center channel. Track ID 2 - A mono track containing the sub-woofer channel. Track ID 3 - A stereo track containing the back left and back right channels. Then, at runtime, you need to tell Bink to open all of the sound tracks simultaneously. To do this, use code something like this:

U32 TrackIDsToPlay[ 4 ] = { 0, 1, 2, 3 };
BinkSetSoundTrack( 4, TrackIDsToPlay );
bink = BinkOpen( "file.bik", BINKSNDTRACK );

Now we have to tell DirectSound where to route each of the sound tracks. To do this, use code like this:

U32 bins[ 2 ];
bins[ 0 ] = DSMIXBIN_FRONT_LEFT;bins[ 1 ] = DSMIXBIN_FRONT_RIGHT;BinkSetMixBins( bink, 0, bins, 2 );
bins[ 0 ] = DSMIXBIN_FRONT_CENTER;BinkSetMixBins( bink, 1, bins, 1 );
bins[ 0 ] = DSMIXBIN_LOW_FREQUENCY;BinkSetMixBins( bink, 2, bins, 1  );
bins[ 0 ] = DSMIXBIN_BACK_LEFT;bins[ 1 ] = DSMIXBIN_BACK_RIGHT;BinkSetMixBins( bink, 3, bins, 2 );

ExamXbox.CPP has example code to do all of this - check out the BINK51 code sections for details.

Next Topic (Memory management on the Xbox)

Previous Topic (Gamma on the Xbox)

Group: The Xbox Platform
Related Sections: Audio Tracks in Bink
Related Functions: BinkSetMixBins, BinkSetSoundTrack


Memory management on the Xbox

Discussion

By default, Bink handles memory management by calling the XTL memory allocation functions directly. You can, however, replace the Bink allocation and freeing functions with the RADSetMemory function. You can see how much memory is being used and what the peak use was with the BinkGetSummary function. You can also load and unload Bink's code memory with the BinkLoad, BinkUnload, BinkLoadConverter, and BinkUnloadConverter functions.

Next Topic (Sharing the CPU on the Xbox)

Previous Topic (Sound on the Xbox)

Group: The Xbox Platform
Related Functions: BinkGetSummary, BinkLoad, BinkLoadConverter, BinkUnload, BinkUnloadConverter, RADSetMemory


Sharing the CPU on the Xbox

Discussion

On Xbox, you don't have to share the CPU with the OS at all! This is a nice retro-style bonus when working on the Xbox - you can hog all the CPU you want! This means an Xbox Bink playback loop is typically very simple. Bink handles timing with the BinkWait function, so we just need to check this function while we're playing a video (unless your video is authored exactly at 29.97 in which case you can let the page-flipping control your frame rate). So, a simple example of Xbox playback would look something like this:

for ( ; ; ){   // check on our playback   //   // Note that if your videos are   //   authored at exactly 29.97 fps,   //   you'll get better performance   //   by not calling BinkWait and   //   letting the page flipping   //   control the speed of playback!!!!!   //
   if ( !BinkWait( bink ) )   {     // go process the next Bink frame     Show_next_frame( bink, linear_texture );   } }}

Next Topic (Bink Examples for the Xbox)

Previous Topic (Memory management on the Xbox)

Group: The Xbox Platform
Related Functions: BinkWait


Bink Examples for the Xbox

Discussion

The Bink SDK supplies several example programs for Xbox. To create these examples in Visual C, just create a new project and include the appropriate C source file (ExamXbox.C, for example), and then add the Bink for Xbox static library to the project (BinkXbox.LIB or BinkXbox.LTCG.LIB).
The following is a list of the example files that you can experiment with:
For an example of using an overlay to display the Bink video, see the "ExamXbox.C" file. This is the best way to get simple video playback into your game quickly.
For an example of using a YUV Direct3D texture to display the Bink video, see the "ExamXTex.C" file. This example uses our simple Direct3D wrapper, so be sure to also add the "XBXRAD3D.CPP" file to your project.
For an example of using a Bink alpha plane with Direct3D, see the "ExamXAlf.C" file. This example uses our simple Direct3D wrapper, so be sure to also add the "XBXRAD3D.CPP" file to your project.
For an example of having Bink copy directly onto the Direct3D back buffer, see the "ExamXbb.C" file. Overlays are almost always preferable to this option, however.

Previous Topic (Sharing the CPU on the Xbox)

Group: The Xbox Platform
Related Sections: Alpha Planes, Direct3D, OpenGL


The MacOS Platform

Discussion

The second operating system that Bink supported was MacOS. MacOS is strange to develop under - some pieces are advanced, some pieces seem comically backwards. Bink was developed on both MacOS 9 and MacOS X. We supply both a standard MacOS 9 shared library as well as a MacOS X Carbon shared library. Carbon shared libraries work under both MacOS 9 and MacOS X natively - see the Apple developer website for more details. Bink is extremely easy to use and integrate under this platform. This chapter will discuss everything you need to know!

The MacOS Platform
Installation for MacOS
Integrating Bink into a MacOS Build Environment
Distributing the Bink Shared Library under MacOS
Bink Playback under MacOS
Pros and Cons of Direct to Screen Blitting under MacOS
Pros and Cons of GWorld Blitting under MacOS
Simplifying MacOS Blitting with BinkBuffers
Sound under MacOS
Memory management under MacOS
Sharing the CPU under MacOS
Bink Examples for MacOS


Installation for MacOS

Discussion

The Bink SDK is provided as a compressed archive in MacBinary format. To install it, simply double-click on the BinkSDK.sit.bin file on the Bink SDK CD. Once installed, you can access this documentation online by clicking on the Bink SDK Help alias in the Bink SDK folder. We've also supplied the RAD Video Tools for Windows on the CD. To compress a file into Bink format, you should install these tools on a Windows machine.

Next Topic (Integrating Bink into a MacOS Build Environment)

Group: The MacOS Platform


Integrating Bink into a MacOS Build Environment

Discussion

To build an application that uses Bink Video, you must include the Bink SDK in the build process. There are three simple steps to do this: 1) Include Bink.h in your source files. 2) Link with the BinkClassicLibrary, the BinkCarbonLibrary, or the libBinkMachO.dylib library file (in CodeWarrior, just drag the library into your project). 3) Place the BinkClassicLibrary, the BinkCarbonLibrary, or the libBinkMachO.dylib library file in the folder containing your application executable. Note that MachO applications place the executables for an application package in a subfolder called "Contents/MacOS". MachO application packages are just a defined set of folders, so to open the Contents subfolder in Finder, Control-click on the application icon and choose "Show Package Contents". Then just place the libBinkMachO.dylib file into the "Contents/MacOS" folder. And that's it - you should now be able to use Bink!

Next Topic (Distributing the Bink Shared Library under MacOS)

Previous Topic (Installation for MacOS)

Group: The MacOS Platform


Distributing the Bink Shared Library under MacOS

Discussion

To distribute an application that uses Bink, you must include the Bink Shared Library in the same folder as your application.
Do not place the Bink Shared Library in the System Folder or the Extensions Folder! The Bink Shared Library must be placed in your application folder!

Next Topic (Bink Playback under MacOS)

Previous Topic (Integrating Bink into a MacOS Build Environment)

Group: The MacOS Platform


Bink Playback under MacOS

Discussion

True-color video playback under MacOS is simpler than Windows (mainly because the hardware is less varied), but still a little tricky. Like most true color codecs, Bink doesn't operate in RGB colorspace, but rather YUV. To get this necessary colorspace conversion fast and reliable, Bink includes built-in, well-optimized YUV to RGB software conversion routines. We include 1x and 2x width, height interlacing, height doubling, alpha plane merging, and color or grayscale routines that can copy into 16-bit and 32-bit RGB formats. The permutations total 80 different hand-optimized routines! As you might guess, the majority of the Bink Shared Library is the colorspace converters. Because Bink buffers your video frames internally in YUV colorspace, it can make a big difference in playback speed to convert from YUV directly into the video frame buffer (directly onto the screen). This is the default mode of playback in Bink - it just tries to get that video onto the screen as fast as possible! There are, however, good reasons to use standard MacOS GWorlds - highest possible compatibility, clipping, and unusual scaling, for example. So, you have a choice between super-fast direct to screen, and not-as-fast GWorlds. Let's look at the pros and cons of each technique...

Next Topic (Pros and Cons of Direct to Screen Blitting under MacOS)

Previous Topic (Distributing the Bink Shared Library under MacOS)

Group: The MacOS Platform
Related Sections: Alpha Planes


Pros and Cons of Direct to Screen Blitting under MacOS

Discussion

The blitting directly to the screen is good, because: 1) It is the very fastest way to display video on MacOS. This is almost always the best method for getting video frames onto the screen. 2) You get fast stretching for 2x width, 2x height, and 2x width and height. Bink can directly stretch 2x in width and/or height.
The blitting directly to the screen is bad, because: 1) Direct to screen isn't as compatible as GWorlds - GWorlds can support any type of video hardware - not just the hardware we knew about when we wrote Bink. 2) When blitting directly to the screen, no clipping is performed at all. 3) Only 2x width and/or height stretching is available.

Next Topic (Pros and Cons of GWorld Blitting under MacOS)

Previous Topic (Bink Playback under MacOS)

Group: The MacOS Platform


Pros and Cons of GWorld Blitting under MacOS

Discussion

GWorld blitting is good, because: 1) It is the most compatible way of getting pixels onto the screen. They will always work. 2) GWorlds can perform clipping during blitting. 3) GWorlds can be scaled to any resolution - not just 2x (this is usually slow, though).
GWorld blitting is bad, because: 1) GWorlds are slow! Even if CopyBits was perfect (which it ain't), there still is an extra frame buffer blit compared to direct-to-screen. 3) GWorlds use more memory. Again, because there is an extra frame buffer, they require more memory than direct-to-screen.

Next Topic (Simplifying MacOS Blitting with BinkBuffers)

Previous Topic (Pros and Cons of Direct to Screen Blitting under MacOS)

Group: The MacOS Platform


Simplifying MacOS Blitting with BinkBuffers

Discussion

So, which method should you use? Direct-to-screen or GWorlds? To help with this dilemma, Bink includes the BinkBuffer API. BinkBuffers hide a bunch of the MacOS weirdness to make switching between these options really easy. The example Bink Player for MacOS uses the BinkBuffer API to make displaying Bink frames simple. Note, however, that the BinkBuffer API is a high-level API, so if you've already got a good blitting solution in your application, you may simply want to skip BinkBuffers completely and have Bink just copy directly into your linear buffers (which could be on-screen, in a GWorld, or in your own format).

Next Topic (Sound under MacOS)

Previous Topic (Pros and Cons of GWorld Blitting under MacOS)

Group: The MacOS Platform


Sound under MacOS

Discussion

For sound support under MacOS, Bink directly hooks to the MacOS Sound Manager. You usually don't have to do anything special for sound support when running under MacOS - everything is handled automatically.

Next Topic (Memory management under MacOS)

Previous Topic (Simplifying MacOS Blitting with BinkBuffers)

Group: The MacOS Platform
Related Sections: Audio Tracks in Bink


Memory management under MacOS

Discussion

By default, Bink handles memory management under MacOS by calling the MacOS memory functions directly. You can, however, replace the Bink allocation and freeing functions with the RADSetMemory function. When allocating memory from MacOS directly, Bink tries to allocate memory in this order:
1) Bink first tries to allocate memory from the application's memory partition. 2) Next, Bink tries to allocate memory from the MultiFinder temporary memory block. 3) Finally, Bink will then try to allocate memory from the temporary system memory pool.
Using this set of memory fallbacks, Bink will usually find the memory it needs no matter where it may be hiding. You can see how much memory is being used and what the peak use was with the BinkGetSummary function.

Next Topic (Sharing the CPU under MacOS)

Previous Topic (Sound under MacOS)

Group: The MacOS Platform
Related Functions: BinkGetSummary, RADSetMemory


Sharing the CPU under MacOS

Discussion

Under MacOS, you must share the processor time with other applications. To do this, we have to process events while we're waiting for each frame. Bink handles timing with the BinkWait function, so we just need to check this function whenever we're not processing an event. So, we'll simply monitor the BinkWait function in our event loop - when BinkWait tells us that it's time for the next frame, we'll just call the code to advance a frame. A simple example of MacOS playback would look something like this:

while ( !done ){  // check for a MacOS event  if ( OSEventAvail( everyEvent, &e ) )  {    WaitNextEvent( everyEvent, &e, 0, 0 );    switch ( e.what )    {      case keyDown:        done=1;        break;
      // rest of your event handling code here    }  }  else  {    // no events, so check on our playback    if ( !BinkWait( bink ) )    {      // go process the next Bink frame      Show_next_frame( bink, bink_buf );    }  }}

Next Topic (Bink Examples for MacOS)

Previous Topic (Memory management under MacOS)

Group: The MacOS Platform
Related Functions: BinkWait


Bink Examples for MacOS

Discussion

The Bink SDK supplies the full source code and resourcses for the Bink Player we supply on our web site. To build the examples, follow these steps:
1) Create a new MacOS Toolbox for C project for Classic, Carbon or MachO in CodeWarrior.
2) Add the "player.c", "player.r", and "playerbinary.rsrc" files into the project. For Carbon projects, also add "carbon.h" to the project.
3) Copy the appropriate Bink library ("BinkClassicLibrary", "BinkCarbonLibrary", or "libBinkMachO.dylib") into the executable directory. Note that MachO applications place the executables for an application package in a subfolder called "Contents/MacOS". MachO application packages are just a defined set of folders, so to open the Contents subfolder in Finder, Control-click on the application icon and choose "Show Package Contents". Then just place the libBinkMachO.dylib file into the "Contents/MacOS" folder.
4) Add the Bink library that you just copied into the project.
5) Remove the sample source files that CodeWarrior places into the project by default.
And that's it! You should be able to build and run the same Bink example that we redistribute.

Previous Topic (Sharing the CPU under MacOS)

Group: The MacOS Platform


Basic Types

Discussion

Bink strives to be as cross-platform as possible. To this end, Bink uses a set of basic types that are configured for each platform to ensure consistency in the API. These basic types include simple integer types, float types, and more. In general, it is best if an application uses Bink's types internally in places where it interfaces to Bink, as this ensures that porting the application to other Bink platforms will be quick and easy.

Basic Types
S8 | describes a signed 8-bit integer.
U8 | describes an unsigned 8-bit integer.
S16 | describes a signed 16-bit integer.
U16 | describes an unsigned 16-bit integer.
S64 | describes a signed 64-bit integer.
U64 | describes an unsigned 64-bit integer.
S32 | describes a signed 32-bit integer.
U32 | describes an unsigned 32-bit integer.
s32_ptr | describes a pointer to a signed 32-bit integer.
u32_ptr | describes a pointer to an unsigned 32-bit integer.
F32 | describes a standard 32-bit floating-point number.
F64 | describes a standard 64-bit double-precision floating-point number.
void | describes a standard C/C++ void return type.
NULL | describes a standard C/C++ NULL pointer.
OS_WND | describes a standard HWND window handle on Win32, or a standard WindowPtr under MacOS.
HCURSOR | describes a standard Win32 HCURSOR cursor handle.
LPDIRECTSOUND | describes a pointer to a DirectSound object.
LPDIRECTDRAW | describes a pointer to a DirectDraw object.
LPDIRECTDRAWSURFACE | describes a pointer to a DirectDraw surface object.
LPDIRECT3DSURFACE8 | describes a pointer to a DirectX 8 Direct3D surface object.
FSSpec_PTR | describes a pointer to a MacOS filespec.
GDHandle | describes a standard MacOS Graphics Device pointer.
VOID_PTR | describes a standard C/C++ untyped memory pointer.
BINK_STRING | describes a normal zero-terminated C-style string.
HBINK | is a handle to an opened Bink file.
HBINKTRACK | is a handle to an opened Bink audio track.
HBINKBUFFER | is a handle to an opened BinkBuffer.
BINKRECT | is a structure describing a rectangular area.
BINKRECT_ARRAY | is an array of structures describing rectangular areas.


S8

The basic type S8 describes a signed 8-bit integer.

Group: Basic Types


U8

The basic type U8 describes an unsigned 8-bit integer.

Group: Basic Types


S16

The basic type S16 describes a signed 16-bit integer.

Group: Basic Types


U16

The basic type U16 describes an unsigned 16-bit integer.

Group: Basic Types


S64

The basic type S64 describes a signed 64-bit integer.

Group: Basic Types


U64

The basic type U64 describes an unsigned 64-bit integer.

Group: Basic Types


S32

The basic type S32 describes a signed 32-bit integer.

Group: Basic Types
Related Functions: BinkBufferCheckWinPos, BinkBufferLock, BinkBufferSetOffset, BinkBufferSetScale, BinkBufferUnlock, BinkCheckCursor, BinkCopyToBuffer, BinkCopyToBufferRect, BinkDoFrame, BinkGetRects, BinkIsSoftwareCursor, BinkPause, BinkRestoreCursor, BinkSetPan, BinkSetSoundOnOff, BinkSetSoundSystem, BinkSetVideoOnOff, BinkSetVolume, BinkSoundUseAX, BinkSoundUseDirectSound, BinkSoundUseMiles, BinkSoundUseMusyX, BinkSoundUseSoundManager, BinkWait
Related Structures: BINKBUFFER, BINKRECT


U32

The basic type U32 describes an unsigned 32-bit integer.

Group: Basic Types
Related Functions: BinkBufferBlit, BinkBufferOpen, BinkBufferSetResolution, BinkBufferSetScale, BinkCheckCursor, BinkCopyToBuffer, BinkCopyToBufferRect, BinkGetKeyFrame, BinkGetRealtime, BinkGetTrackData, BinkGetTrackID, BinkGoto, BinkOpenTrack, BinkSetFrameRate, BinkSetIOSize, BinkSetMixBinVolumes, BinkSetMixBins, BinkSetPan, BinkSetSimulate, BinkSetSoundSystem, BinkSetSoundTrack, BinkSetVolume, RADARAMALLOC, RADMEMALLOC
Related Structures: BINK, BINKBUFFER, BINKREALTIME, BINKSUMMARY, BINKTRACK


s32_ptr

The basic type s32_ptr describes a pointer to a signed 32-bit integer.

Group: Basic Types
Related Functions: BinkSetMixBinVolumes


u32_ptr

The basic type u32_ptr describes a pointer to an unsigned 32-bit integer.

Group: Basic Types
Related Functions: BinkSetMixBinVolumes, BinkSetMixBins, BinkSetSoundTrack


VOID_PTR

The basic type VOID_PTR describes a standard C/C++ untyped memory pointer.

Group: Basic Types
Related Functions: BinkCopyToBuffer, BinkCopyToBufferRect, BinkGetLogoAddress, BinkGetTrackData, BinkSetIO, BinkSetSoundSystem, BinkSoundUseMiles, RADARAMALLOC, RADARAMFREE, RADMEMALLOC, RADMEMFREE
Related Structures: BINKBUFFER


F32

The basic type F32 describes a standard 32-bit floating-point number.

Group: Basic Types


F64

The basic type F64 describes a standard 64-bit double-precision floating-point number.

Group: Basic Types


void

The basic type void describes a standard C/C++ void return type.

Group: Basic Types
Related Functions: BinkBufferBlit, BinkBufferCheckWinPos, BinkBufferClose, BinkBufferSetDirectDraw, BinkBufferSetResolution, BinkClose, BinkCloseTrack, BinkGetRealtime, BinkGetSummary, BinkGoto, BinkLoad, BinkLoadConverter, BinkNextFrame, BinkRestoreCursor, BinkService, BinkSetFrameRate, BinkSetIO, BinkSetIOSize, BinkSetMixBinVolumes, BinkSetMixBins, BinkSetPan, BinkSetSimulate, BinkSetSoundTrack, BinkSetVolume, BinkUnload, BinkUnloadConverter, RADARAMFREE, RADMEMFREE, RADSetMemory


NULL

The basic type NULL describes a standard C/C++ NULL pointer.


OS_WND

The basic type OS_WND describes a standard HWND window handle on Win32, or a standard WindowPtr under MacOS.

Group: Basic Types
Related Functions: BinkBufferOpen, BinkCheckCursor


HCURSOR

The basic type HCURSOR describes a standard Win32 HCURSOR cursor handle.

Group: Basic Types
Related Functions: BinkIsSoftwareCursor


LPDIRECTSOUND

The basic type LPDIRECTSOUND describes a pointer to a DirectSound object.

Group: Basic Types
Related Functions: BinkSoundUseDirectSound


LPDIRECTDRAW

The basic type LPDIRECTDRAW describes a pointer to a DirectDraw object.

Group: Basic Types
Related Functions: BinkBufferSetDirectDraw


LPDIRECTDRAWSURFACE

The basic type LPDIRECTDRAWSURFACE describes a pointer to a DirectDraw surface object.

Group: Basic Types
Related Functions: BinkBufferSetDirectDraw, BinkDDSurfaceType, BinkIsSoftwareCursor


LPDIRECT3DSURFACE8

The basic type LPDIRECT3DSURFACE8 describes a pointer to a DirectX 8 Direct3D surface object.

Group: Basic Types
Related Functions: BinkDX8SurfaceType


FSSpec_PTR

The basic type FSSpec_PTR describes a pointer to a MacOS filespec.

Group: Basic Types
Related Functions: BinkMacOpen


GDHandle

The basic type GDHandle describes a standard MacOS Graphics Device pointer.

Group: Basic Types
Related Functions: BinkGDSurfaceType


BINK_STRING

The basic type BINK_STRING describes a normal zero-terminated C-style string.

Group: Basic Types
Related Functions: BinkBufferGetDescription, BinkBufferGetError, BinkGetError, BinkOpen


HBINK

The basic type HBINK is a handle to an opened Bink file.

Discussion

A HBINK handle is returned from the BinkOpen function. It also points to a BINK structure which contains all sorts of interesting information about the open Bink file. If the BinkOpen call failed, then this handle will be zero.

Group: Basic Types
Related Functions: BinkClose, BinkCopyToBuffer, BinkCopyToBufferRect, BinkDoFrame, BinkGetKeyFrame, BinkGetRealtime, BinkGetRects, BinkGetSummary, BinkGetTrackID, BinkGoto, BinkMacOpen, BinkNextFrame, BinkOpen, BinkOpenTrack, BinkPause, BinkService, BinkSetMixBinVolumes, BinkSetMixBins, BinkSetPan, BinkSetSoundOnOff, BinkSetVideoOnOff, BinkSetVolume, BinkWait
Related Structures: BINK


HBINKTRACK

The basic type HBINKTRACK is a handle to an opened Bink audio track.

Discussion

A HBINKTRACK handle is returned from the BinkOpenTrack function. It also points to a BINKTRACK structure which contains information about the open Bink audio track. If the BinkOpenTrack call failed, then this handle will be zero.

Group: Basic Types
Related Functions: BinkCloseTrack, BinkGetTrackData, BinkOpenTrack
Related Structures: BINKTRACK


HBINKBUFFER

The basic type HBINKBUFFER is a handle to an opened BinkBuffer.

Discussion

A HBINKBUFFER handle is returned from the BinkBufferOpen function. It also points to a BINKBUFFER structure which contains all sorts of interesting information about the BinkBuffer. If the BinkBufferOpen call failed, then this handle will be zero.

Group: Basic Types
Related Functions: BinkBufferBlit, BinkBufferCheckWinPos, BinkBufferClose, BinkBufferGetDescription, BinkBufferLock, BinkBufferOpen, BinkBufferSetOffset, BinkBufferSetScale, BinkBufferUnlock
Related Structures: BINKBUFFER


BINKRECT

The structure BINKRECT is a structure describing a rectangular area.

struct BINKRECT
{
  S32 Left;
  S32 Top;
  S32 Width;
  S32 Height;
};

Out Members

Left
Specifies the left coordinate (zero-based).
Top
Specifies the top coordinate (zero-based).
Width
Specifies the width of the rectangle (one-based).
Height
Specifies the height of the rectangle (one-based).

Group: Basic Types
Related Basic Types: S32


BINKRECT_ARRAY

The basic type BINKRECT_ARRAY is an array of structures describing rectangular areas.

Group: Basic Types
Related Functions: BinkBufferBlit
Related Structures: BINK


Bink API

Discussion

The Bink API is the API that you use to decompress each frame of a Bink file. The Bink API is used to open the file, decompress video frames, wait for the next frame, skip to the next frame, etc. The Bink API doesn't, however, draw anything onto the screen. All the Bink API does is place data into a linear memory buffer. This buffer can be a DirectDraw surface, a DIBSection, or even a plain old malloc-ed chunk of memory. The Bink API doesn't know or care about where it places the data. Because Bink doesn't blit directly to the screen, you have a lot more flexibility - you can use Bink to compress not just to compress videos, but bitmaps, textures, light maps, height maps, etc. Any rectangular data set can be compressed. Blitting is, however, a complicated situation on most platforms (especially Win32), so we also supply a ready-made blitting API (called the BinkBuffer API). This API is separate from the Bink API, though, so it is up to you whether you use it or not. The BinkBuffer API is described later in this manual.

Bink API
BinkOpen | opens the specified Bink file for decompression.
BinkMacOpen | opens the specified Bink file for decompression.
BINK | is a structure returned from BinkOpen.
BINK_OPEN_FLAGS | describes the special or unusual ways of opening a Bink file.
BinkClose | closes the specified Bink handle.
BinkDoFrame | decompresses the next frame of video.
BinkCopyToBuffer | copies a video frame from the internal Bink memory buffers to a specified memory address.
BinkCopyToBufferRect | copies a piece of the video frame from the internal Bink memory buffers to a specified memory address.
BINK_COPY_FLAGS | describes the destination buffer type as well as special or unusual ways of converting Bink's internal YUV data.
BinkNextFrame | moves to the next video frame in the Bink file.
BinkWait | tells you when to move to the next Bink frame (based on the frame rate of the file).
BinkPause | pauses and resumes playback of a Bink file.
BinkGetRects | returns the dirty rectangles of the last decompressed video frame.
BINK_GETRECTS_FLAGS | Specifies the type of rectangle list you'd prefer from the BinkGetRects function.
BinkGoto | jumps to a new frame inside the Bink file.
BINK_GOTO_FLAGS | Specifies the type of jump to perform.
BinkGetKeyFrame | finds a key frame near another specified frame.
BINK_GETKEY_FLAGS | Specifies the type of key frame search to perform.
BinkService | gives some explicit idle time to Bink to service any of its internal tasks.
BinkSoundUseMiles | tells Bink to use the Miles Sound System as its sound output system.
BinkSoundUseDirectSound | tells Bink to use DirectSound as its sound output system.
BinkSoundUseSoundManager | tells Bink to use the MacOS Sound Manager as its sound output system.
BinkSoundUseAX | tells Bink to use AX as its sound output system on the Nintendo GameCube.
BinkSoundUseMusyX | tells Bink to use MusyX as its sound output system on the Nintendo GameCube.
RADARAMCALLBACKS | specifies a set of replacement audio RAM memory management functions for use with AX on the Nintendo GameCube.
RADARAMALLOC | points to a function that will allocate audio memory on Bink's behalf when using AX on the Nintendo GameCube.
RADARAMFREE | points to a function that will free memory allocated by a previous call to the RADARAMALLOC function.
BinkSetSoundSystem | tells Bink to use a custom sound provider as its sound output system.
BinkSetVolume | sets the volume of a Bink sound track.
BinkSetPan | sets the speaker pan (left to right balance) of a Bink sound track.
BinkSetMixBins | sets the mix bin destination of the sound track on an Xbox.
BinkSetMixBinVolumes | sets the volumes of the individual mix bins on an Xbox.
BinkSetVideoOnOff | tells Bink not to decompress the video frames when BinkDoFrame is called.
BinkSetSoundOnOff | tells Bink not to decompress the audio and release any audio resources.
BinkGetSummary | returns playback information about the specified Bink handle.
BINKSUMMARY | is a structure used to return playback summary information from BinkGetSummary.
BinkGetRealtime | returns realtime playback information about the specified Bink handle.
BINKREALTIME | is a structure used to return realtime playback information from BinkGetRealtime.
BinkGetTrackID | returns the track ID for the specified track index.
BinkOpenTrack | opens a handle to the low-level audio track decoder.
BINKTRACK | is a structure returned from BinkOpenTrack.
BinkCloseTrack | closes a low-level audio track decoder handle.
BinkGetTrackData | extracts all of the sound in the current video frame.
BinkSetFrameRate | overrides the Bink file's built-in frame rate.
BinkSetSoundTrack | overrides the Bink file's default sound track.
BinkSetSimulate | tells Bink to simulate a specified device I/O speed.
BinkSetIOSize | Specifies the size of the I/O memory buffer that Bink reads into.
BinkSetIO | specifies a set of replacement file I/O functions.
RADSetMemory | specifies a set of replacement memory management functions.
RADMEMALLOC | points to a function that will allocate memory on Bink's behalf.
RADMEMFREE | points to a function that will free memory allocated by a previous call to the RADMEMALLOC function.
BinkGetError | returns a string that describes the last global Bink error.
BinkGetLogoAddress | returns a pointer to an embedded Bink logo file.
BinkLoad | reloads the Bink sections on an Xbox (if it had been unloaded by BinkUnload).
BinkUnload | unloads the Bink sections on an Xbox.
BinkLoadConverter | reloads one or more of the Bink YUV to RGB converters (if they had been unloaded by BinkUnloadConverter).
BinkUnloadConverter | unloads one or more of the Bink YUV to RGB converters.
BINK_CONVERTER_FLAGS | Specifies the class of Bink YUV converters to load or unload.


BinkOpen

The function BinkOpen opens the specified Bink file for decompression.

HBINK BinkOpen(
  BINK_STRING file_name,
  BINK_OPEN_FLAGS open_flags
);

In Parameters

file_name
The name of the file to open.
open_flags
The flags to use when opening the file.

Returns

Handle to the opened Bink file or zero on error

Discussion

This function returns an HBINK handle which is used with all of the Bink API functions. The returned HBINK handle is also a pointer to a BINK structure which contains information about the opened file. If the BinkOpen call fails, then zero will be returned. You can get a description of the error by calling BinkGetError.

Group: Bink API
Related Sections: Open and Close
Related Functions: BinkBufferSetResolution, BinkClose, BinkDoFrame, BinkGetError, BinkGetLogoAddress, BinkMacOpen, BinkSetFrameRate, BinkSetIO, BinkSetIOSize, BinkSetSimulate, BinkSetSoundSystem, BinkSetSoundTrack, BinkSoundUseAX, BinkSoundUseDirectSound, BinkSoundUseMiles, BinkSoundUseMusyX, BinkSoundUseSoundManager
Related Basic Types: BINK_COPY_FLAGS, BINK_OPEN_FLAGS, BINK_STRING, HBINK
Related Structures: BINK


BinkMacOpen

The function BinkMacOpen opens the specified Bink file for decompression.

HBINK BinkMacOpen(
  FSSpec_PTR file_spec,
  BINK_OPEN_FLAGS open_flags
);

In Parameters

file_spec
The pointer to the MacOS filespec to open.
open_flags
The flags to use when opening the file.

Returns

Handle to the opened Bink file or zero on error

Discussion

This function works exactly like BinkOpen, only it takes a MacOS filespec to be opened. The returned HBINK handle is also a pointer to a BINK structure which contains information about the opened file. If the BinkMacOpen call fails, then zero will be returned. You can get a description of the error by calling BinkGetError.

Group: Bink API
Related Sections: Open and Close
Related Functions: BinkClose, BinkGetError, BinkOpen
Related Basic Types: BINK_OPEN_FLAGS, FSSpec_PTR, HBINK
Related Structures: BINK


BINK

The structure BINK is a structure returned from BinkOpen.

struct BINK
{
  U32 Width;
  U32 Height;
  U32 Frames;
  U32 FrameNum;
  U32 FrameRate;
  U32 FrameRateDiv;
  U32 ReadError;
  BINK_OPEN_FLAGS OpenFlags;
  BINKRECT_ARRAY FrameRects;
  U32 NumRects;
  U32 NumTracks;
};

Out Members

Width
Specifies the width of the Bink file.
Height
Specifies the height of the Bink file.
Frames
Specifies the number of frames in the Bink file.
FrameNum
Specifies the frame to be displayed of the Bink file.
FrameRate
Along with FrameRateDiv, specifies the frame rate of the Bink file. The frame rate is calculated by (bink->FrameRate/bink->FrameRateDiv). So, for example, at 15 fps, FrameRate would be 15 and FrameRateDiv would be 1.
FrameRateDiv
Specifies the frame rate divisor of the Bink file.
ReadError
set to non-zero if an IO error has occurred during playback.
OpenFlags
Specifies the flags currently being used by the open Bink file.
FrameRects
Returns the dirty rectangles from the last call to BinkGetRects.
NumRects
Returns the number of dirty rectangles from the last call to BinkGetRects.
NumTracks
Returns the number of audio tracks in the Bink file.

Discussion

The BINK structure is pointed to by the HBINK handle that is returned from BinkOpen. You can dereference the pointer to access any of these information fields. Note that you should never change any of these values!

Group: Bink API
Related Sections: Audio Tracks in Bink, Critical File I/O handling in Bink
Related Functions: BinkGetRects, BinkGetTrackID, BinkMacOpen, BinkOpen, BinkOpenTrack
Related Basic Types: BINKRECT_ARRAY, BINK_OPEN_FLAGS, HBINK, U32


BINK_OPEN_FLAGS

The basic type BINK_OPEN_FLAGS describes the special or unusual ways of opening a Bink file.

Fundamental Values

Value | Description
BINKFILEHANDLE Use this flag to tell Bink that the file name that you passed in isn't a file name at all, but rather a file handle. Bink will then use this handle instead of opening a new file. Note that you have to typecast the file handle to a "char*" when using this flag. This flag is useful when you'd like to have a resource file that contains multiple Bink files. When you use this flag, Bink won't open (or close) the file handle.

Under Win32 and Xbox, the file handle value must be a handle returned from the system function "CreateFile".

Under MacOS, the file handle value must be a pointer returned from the system function "FSpOpenDF".

On the Nintendo GameCube, this file handle value must be a DVDFileInfo pointer returned from the system function "DVDFastOpen". On the GameCube, you must also fill in the userData field (fileInfo->cb.userData) in the DVDFileInfo pointer with the starting file offset of the video in this file handle (usually zero). This oddness is because there is no system function for determining the current file position on the GameCube. Also note that this starting file offset must be a multiple of 32.
BINKFROMMEMORY | Use this flag to tell Bink that the file name that you passed in isn't a file name at all, but rather a pointer to an entire Bink file already loaded into memory. Bink will then use this memory to play from. You must not free the memory address that you pass in until you have called BinkClose. On MacOS and GameCube, you must first dword endian-swap your memory buffer before passing it to BinkOpen.
BINKSNDTRACK | Use this flag to tell Bink to play a specific sound track. By default, Bink will play the first sound track in the Bink file, so use this flag to force Bink to use the track ID set in a previous call to the BinkSetSoundTrack function. So, to use this flag, you must first call BinkSetSoundTrack with the desired track ID number, and then open the Bink file using this flag.
BINKNOSKIP | Bink will skip frames if the video begins to fall behind the audio. Bink won't skip frames at all if the Bink file contains no audio, or if you use this flag. This flag is useful when you want the video quality to have precedence over the sound quality (good for cartoon-style animations).
BINKPRELOADALL | Use this flag to tell Bink to preload the entire animation into memory. If Bink is unable to preload the animation into memory, then the open will fail.
BINKALPHA | This flag tells Bink that you want to decompress the alpha plane data if it is present in the file. By default, Bink does not decompress the alpha plane, so you must set this flag if you intend to use any of the alpha bitplane formats (BINKSURFACE32A or BINKSURFACE4444).
BINKGRAYSCALE | This flag tells Bink that you want to play the Bink file back in grayscale mode. Grayscale mode is much faster in both the decompression step (Bink only has to decompress the Y plane) and the YUV conversion step. If you compressed the Bink file in grayscale mode, then this flag will automatically be set.
BINKFRAMERATE | Use this flag to tell Bink to override the frame rate in the Bink file and use the frame rate specified by a previous call to the BinkSetFrameRate function. So, to use this flag, you first call BinkSetFrameRate with the desired rate, and then open the Bink file using this flag.
BINKCOPY2XH | Use this flag to tell Bink to playback the video in 2x height doubled mode. This will cause each line to be duplicated (which will double the height). If the video was compressed in 2x height doubled mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY2XHI | Use this flag to tell Bink to playback the video in 2x height interlaced mode. This will cause the video to be expanded to every other scanline (which will double the height). If the video was compressed in interlaced mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY2XW | Use this flag to tell Bink to playback the video in 2x width doubled mode. This will cause each pixel to be duplicated (which will double the width). If the video was compressed in 2x width doubled mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY2XWH | Use this flag to tell Bink to playback the video in 2x width and height doubled mode. This will cause each line and each pixel to be duplicated (which will double both the width and height). If the video was compressed in 2x width and height doubled mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY2XWHI | Use this flag to tell Bink to playback the video in 2x width doubled and height interlaced mode. This will cause each pixel to be duplicated and every other scanline to be skipped (which will double both the width and height). If the video was compressed in 2x width and height interlaced mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY1XI | This copy flag tells Bink to play the movie in normal 1x mode, but to only copy ever other scanline during playback. This saves half the time of a normal frame copy, so it is useful on under-powered machines.
BINKCOPYNOSCALING | Use this flag to tell Bink to playback the video without any doubling or interlacing. Use this flag to counteract the automatic effect of a video compressed in one of the interlaced or doubled modes.
BINKNOMMX | This flag tells Bink not to use MMX while decompressing or when converting colorspaces. Bink runs much slower without MMX, so you will usually just want to leave this flag alone. This flag isn't supported on Xbox - MMX is always used when running on the Xbox.
BINKSIMULATE | Use this flag to tell Bink to simulate the device speed set in a previous call to the BinkSetSimulate function. To use this flag, you first call BinkSetSimulate with the device speed, and then open the Bink file using this flag.
BINKIOSIZE | Use this flag to tell Bink to override the default IO buffer size with the size set in a previous call to the BinkSetIOSize function. To use this flag, you must first call BinkSetIOSize with the IO size, and then open the Bink file using this flag.
BINKNOFILLIOBUF | Use this flag to tell Bink not to fill the IO buffer in BinkOpen. By default, Bink completely fills the IO buffer before returning from BinkOpen. Using this flag will speed up the opening process, but it can cause skipping early in the movie.
BINKIOPROCESSOR | This flag lets you completely replace the file IO system that Bink will use to read the Bink file. This is a not a trivial job, but you can perform any type of IO using this flag (even streaming from an Internet address). If you are interested in using this flag, contact RAD for more information.
BINKNOTHREADEDIO | Use this flag to tell Bink not to use multi-threaded IO. By default, Bink creates a background thread that reads from the Bink file in the background. If you don't want Bink to do any of this background processing, then you can turn it off with this flag.

Discussion

The Bink flags are passed to the BinkOpen function to enable special or unusual processing modes. You will almost always pass zero for the Bink flags, but you can use any of these options when the need arises. The various COPY flags are very useful for creating really scalable video playback. For example, say you have a 320x240 movie, using the different COPY flags, you could offer the following playback modes:
1) No flags - normal 320x240 playback
2) BINKCOPY1XI - 320x240 with 1x interlacing for slow machines.
3) BINKCOPY2XWHI - 640x480 with 2x interlacing for medium machines.
4) BINKCOPY2XWH - 640x480 with 2x doubling for fast machines.

Group: Bink API
Related Sections: Alpha Planes, Scaling
Related Functions: BinkClose, BinkDoFrame, BinkGetLogoAddress, BinkMacOpen, BinkOpen, BinkSetFrameRate, BinkSetIO, BinkSetIOSize, BinkSetSimulate, BinkSetSoundOnOff, BinkSetSoundTrack
Related Basic Types: BINK_COPY_FLAGS, BINK_OPEN_FLAGS
Related Structures: BINK


BinkClose

The function BinkClose closes the specified Bink handle.

void BinkClose(
  HBINK bink
);

In Parameters

bink
Specifies the Bink handle that you wish to close.

Discussion

This function simply closes a Bink file and releases all of the associated memory. You should close all Bink files that you open or you could leak memory or system resources.

Group: Bink API
Related Sections: Open and Close
Related Functions: BinkGetSummary, BinkMacOpen, BinkOpen
Related Basic Types: BINK_OPEN_FLAGS, HBINK, void


BinkDoFrame

The function BinkDoFrame decompresses the next frame of video.

S32 BinkDoFrame(
  HBINK bink
);

In Parameters

bink
Specifies the Bink handle.

Returns

Returns one if the frame was skipped, or zero otherwise.

Discussion

This function does the actual decompression of the next Bink frame. Bink decompresses the compressed Bink frame into the three internal YUV memory buffers, so you must then copy the data out of the internal buffers with the BinkCopyToBuffer function. If the audio is falling behind the video, this function may skip decompressing the video frame. You can determine how many frames have been skipped by examining the SkippedFrames field of the Bink summary structure (see the BinkGetSummary function for details). If you specified the BINKNOSKIP flag in BinkOpen, then BinkDoFrame will never skip a frame. You should call BinkNextFrame before calling this function again. This function returns one if the frame was skipped, or zero otherwise. If you specified the BINKNOSKIP flag in BinkOpen, then this function returns a non-zero value if the frame should have been skipped.

Group: Bink API
Related Sections: Bink Video Playback, Open and Close
Related Functions: BinkCopyToBuffer, BinkCopyToBufferRect, BinkDoFrame, BinkGetRects, BinkGetSummary, BinkNextFrame, BinkOpen, BinkWait
Related Basic Types: BINK_OPEN_FLAGS, HBINK, S32


BinkCopyToBuffer

The function BinkCopyToBuffer copies a video frame from the internal Bink memory buffers to a specified memory address.

S32 BinkCopyToBuffer(
  HBINK bink,
  VOID_PTR dest_addr,
  S32 dest_pitch,
  U32 dest_height,
  U32 dest_x,
  U32 dest_y,
  BINK_COPY_FLAGS copy_flags
);

In Parameters

bink
Specifies the Bink handle.
dest_addr
Address of the destination memory buffer.
dest_pitch
Pitch of the destination buffer in bytes.
dest_height
Height of the destination buffer in pixels.
dest_x
X (left) pixel offset into the destination buffer.
dest_y
Y (top) pixel offset into the destination buffer.
copy_flags
Specifies the flags that describe the destination buffer type and other special copy options.

Returns

Returns one if the frame was skipped, or zero otherwise.

Discussion

Use this function to copy the decompressed pixels from Bink's internal decompression buffers into a destination address. This destination address can be any linear piece of memory - malloc-ed memory, DirectDraw surface pointers, the Buffer address in a BinkBuffer structure, etc. If the destination uses the RGB colorspace, then this function also performs the conversion from YUV to RGB. If you are using the BinkBuffer API, use the bink_buf->Buffer field for the dest_addr parameter, the bink_buf->BufferPitch field for the dest_pitch parameter, the bink_buf->Height field for the dest_height parameter, and the bink_buf->SurfaceType field for the copy_flags parameter. Also make sure you call BinkBufferLock before calling BinkCopyToBuffer and BinkBufferUnlock immediately after. See ExamW32.C for details. If you are using DirectDraw, then simply lock the surface you want to copy to, call BinkCopyToBuffer (with lpSurface for the dest_addr parameter and lPitch for the dest_pitch), and then unlock the surface. See ExamDDP.C for details. Note that if the video is falling behind the audio, then this function may return without copying any pixels. If the copy is skipped, then this function will return a non-zero value. If copy was successful, then a zero will be returned. To copy just a piece of the internal buffers, use the BinkCopyToBufferRect function. On the Nintendo GameCube, note that due to the swizzled output, you must use divisible-by-four values for the X offset, Y offset, width, and height parameters. Inverted scanline buffers (bottom-up) are also supported (although rarely necessary now a days). To specify an inverted buffer, pass in a negative pitch. Inverted buffers will be slower than standard top-down buffers.

Group: Bink API
Related Sections: Bink Examples for the Nintendo GameCube, Bink Playback on the Nintendo GameCube, Scaling
Related Functions: BinkBufferLock, BinkBufferOpen, BinkBufferUnlock, BinkCopyToBufferRect, BinkDDSurfaceType, BinkDX8SurfaceType, BinkDoFrame, BinkGDSurfaceType
Related Basic Types: BINKBUFFER_OPEN_FLAGS, BINK_COPY_FLAGS, HBINK, S32, U32, VOID_PTR
Related Structures: BINKBUFFER


BinkCopyToBufferRect

The function BinkCopyToBufferRect copies a piece of the video frame from the internal Bink memory buffers to a specified memory address.

S32 BinkCopyToBufferRect(
  HBINK bink,
  VOID_PTR dest_addr,
  S32 dest_pitch,
  U32 dest_height,
  U32 dest_x,
  U32 dest_y,
  U32 src_x,
  U32 src_y,
  U32 src_w,
  U32 src_h,
  BINK_COPY_FLAGS copy_flags
);

In Parameters

bink
Specifies the Bink handle.
dest_addr
Address of the destination memory buffer.
dest_pitch
Pitch of the destination buffer in bytes.
dest_height
Height of the destination buffer in pixels.
dest_x
X (left) pixel offset into the destination buffer.
dest_y
Y (top) pixel offset into the destination buffer.
src_x
The X pixel offset in the internal Bink buffer. This must be divisible by 16 unless you use the BINKCOPYALL flag.
src_y
The Y pixel offiset in the internal Bink buffer.
src_w
The width in pixels to copy.
src_h
The height in pixels to copy.
copy_flags
Specifies the flags that describe the destination buffer type and other special copy options.

Returns

Returns one if the frame was skipped, or zero otherwise.

Discussion

Use this function to copy the decompressed pixels from Bink's internal decompression buffers into a destination address just like BinkCopyToBuffer. The only difference between this function and BinkCopyToBuffer is that this function can copy a sub-rectangle of Bink's internal buffers. This is handy when you don't need the entire video frame, or when a single video frame is being broken up into multiple output buffers (like when you are using tiled 256x256 textures, for example. When using this function without the BINKCOPYALL flag, you must use a divisible by 16 value for the src_x parameter.

Group: Bink API
Related Sections: Scaling
Related Functions: BinkCopyToBuffer, BinkDDSurfaceType, BinkDoFrame, BinkGDSurfaceType
Related Basic Types: BINK_COPY_FLAGS, HBINK, S32, U32, VOID_PTR


BINK_COPY_FLAGS

The basic type BINK_COPY_FLAGS describes the destination buffer type as well as special or unusual ways of converting Bink's internal YUV data.

Fundamental Values

Value | Description
BINKSURFACE24 | 24-bit RGB data (BGRBGR, etc). This surface type isn't supported on MacOS, Xbox, or GameCube.
BINKSURFACE32 | 32-bit native RGB data (on x86: BGRxBGRx, etc; on PPC: xRGBxRGB, etc). On GameCube, this format is swizzled.
BINKSURFACE32A | 32-bit native RGB data with alpha (On Win32: BGRABGRA, etc). On GameCube, this format is swizzled.
BINKSURFACE24R | 24-bit reversed RGB data (RGBRGB, etc). This surface type isn't supported on MacOS, Xbox, or GameCube.
BINKSURFACE32R | 32-bit reversed RGB data (RGBxRGBx, etc). This surface type isn't supported on Xbox, or GameCube.
BINKSURFACE32RA | 32-bit reversed RGB data with alpha (RGBARGBA, etc). In OpenGL, this is GL_RGBA. This surface type isn't supported on Xbox, or GameCube.
BINKSURFACE555 | 16-bit 555 RGB high-color surface. On GameCube, this format is swizzled.
BINKSURFACE565 | 16-bit 565 RGB high-color surface. On GameCube, this format is swizzled.
BINKSURFACE655 | 16-bit 655 RGB high-color surface. On GameCube, this format is swizzled.
BINKSURFACE664 | 16-bit 664 RGB high-color surface. On GameCube, this format is swizzled.
BINKSURFACE4444 | 16-bit 4444 RGB high-color surface with alpha. On GameCube, this is actually 4443 format (3-bits of alpha) and is swizzled.
BINKSURFACE5551 | 16-bit 5551 RGB high-color surface with one bit alpha. On GameCube, this format is swizzled.
BINKSURFACEYUY2 | YUY2 format surface (YUYVYUYV, etc.) - effective 16-bits per pixel. This surface type isn't supported on MacOS. On GameCube, this format is not swizzled, so you can use it to copy directly to the video back buffer.
BINKSURFACEUYVY | UYVY format surface (UYVYUYVY, etc.) - effective 16-bits per pixel. This surface type isn't supported on MacOS, Xbox, or GameCube.
BINKSURFACEYV12 | YV12 format planar surface (complete Y plane, complete U plane, complete V plane) - effective 12-bits per pixel (Bink's native internal format). This surface type isn't supported on Xbox.
BINKCOPYALL | Copy all of the pixels to the destination buffer, not just the pixels that changed. Normally, Bink will try to copy just the pixels that changed into the destination buffer - this flag causes Bink to re-copy every pixel over to the destination buffer.
BINKGRAYSCALE | This flag tells Bink that you want to convert the pixels in grayscale mode. Grayscale mode is much faster in blitting, but it can be even faster when we skip the decompression. Therefore, you should usually use this flag in BinkOpen instead of BinkCopyToBuffer, so you get the benefit of the faster decompression too. If you compressed the Bink file in grayscale mode, then this flag will automatically be set.
BINKNOSKIP | Bink will skip the copy step if the video begins to fall behind the audio. Bink won't skip copying at all if the Bink file contains no audio, or if you use this flag. This flag is useful when you want the video quality to have precedence over the sound quality (good for cartoon-style animations).
BINKCOPY2XH | Use this flag to tell Bink to convert the video in 2x height doubled mode. This will cause each line to be duplicated (which will double the height). If the video was compressed in 2x height doubled mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY2XHI | Use this flag to tell Bink to convert the video in 2x height interlaced mode. This will cause the video to be expanded to every other scanline (which will double the height). If the video was compressed in interlaced mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY2XW | Use this flag to tell Bink to convert the video in 2x width doubled mode. This will cause each pixel to be duplicated (which will double the width). If the video was compressed in 2x width doubled mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY2XWH | Use this flag to tell Bink to convert the video in 2x width and height doubled mode. This will cause each line and each pixel to be duplicated (which will double both the width and height). If the video was compressed in 2x width and height doubled mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY2XWHI | Use this flag to tell Bink to convert the video in 2x width doubled and height interlaced mode. This will cause each pixel to be duplicated and every other scanline to be skipped (which will double both the width and height). If the video was compressed in 2x width and height interlaced mode with the Bink compressor, then this flag will automatically be set - you can override it with any of the other COPY flags.
BINKCOPY1XI | This copy flag tells Bink to convert the movie in normal 1x mode, but to only copy ever other scanline during playback. This saves half the time of a normal frame copy, so it is useful on under-powered machines.
BINKCOPYNOSCALING | Use this flag to tell Bink to convert the video without any doubling or interlacing. Use this flag to counteract the automatic effect of a video compressed in one of the interlaced or doubled modes.
BINKNOMMX | This flag tells Bink not to use MMX while when converting colorspaces. Bink runs much slower without MMX, so you will usually just want to leave this flag alone. This flag isn't supported on Xbox - MMX is always used when running on the Xbox.

Discussion

The copy flags passed to BinkCopyToBuffer perform two services. First, they tell Bink what kind of surface you are copying into. And second, they allow you to change the copying style and options during playback instead of just at BinkOpen time. If you are using BinkBuffers, you will usually use the bink_buf->SurfaceType for the copy_flags parameter. If you are using DirectDraw or DirectX 8, then you will usually use the value returned from BinkDDSurfaceType or BinkDX8SurfaceType.

Group: Bink API
Related Sections: Alpha Planes, Scaling
Related Functions: BinkCopyToBuffer, BinkCopyToBufferRect, BinkDDSurfaceType, BinkDX8SurfaceType, BinkGDSurfaceType, BinkLoadConverter, BinkOpen, BinkUnloadConverter
Related Basic Types: BINK_OPEN_FLAGS
Related Structures: BINKBUFFER


BinkNextFrame

The function BinkNextFrame moves to the next video frame in the Bink file.

void BinkNextFrame(
  HBINK bink
);

In Parameters

bink
Specifies the Bink handle.

Discussion

This function actually moves you to the next frame. It is usually called after you have decompressed the frame with BinkDoFrame and have blitted it onto the screen. This function is should be the last function in your playback logic before the BinkWait delay loop. Make sure that you always call this function before waiting in your BinkWait loop, or your playback will be jerky. For example, this is an example of good playback logic:

for( i=0 ; ; i++ ){  BinkDoFrame( bink );  BinkNextFrame( bink );        //***** Good, notice how this line is before the BinkWait delay loop
  while ( BinkWait( bink ) ) ;  //***** Good, notice how this line is after the BinkNextFrame call}

This is an example of incorrect playback logic:

for( i=0 ; ; i++ ){                             //***** THIS IS AN INCORRECT PLAYBACK LOOP!  BinkDoFrame( bink );  while (BinkWait( bink ) ) ; //***** WRONG!! THIS SHOULD BE AFTER BINKNEXTFRAME  BinkNextFrame( bink );      //***** WRONG!! THIS SHOULD BE BEFORE THE BINKWAIT LOOP}

Note that if you call this function on the last frame of a Bink file, then Bink will loop around back to the first frame. This means that if you are only playing your animations once (not looping them), then you need to add extra logic to avoid calling this function for the very last frame (otherwise there will be a delay at the end of your videos while Bink seeks back to the beginning of the file). For example, a simple playback loop that only plays the Bink file once would look like this:

for( i=0 ; ; i++ ){  BinkDoFrame( bink );  if ( i == bink->Frames )  // Break out of loop before BinkNextFrame if at the end of the file    break;
  BinkNextFrame( bink );  while ( BinkWait( bink ) ) ;}

Group: Bink API
Related Sections: Bink Video Playback, Critical File I/O handling in Bink
Related Functions: BinkDoFrame, BinkWait
Related Basic Types: HBINK, void


BinkWait

The function BinkWait tells you when to move to the next Bink frame (based on the frame rate of the file).

S32 BinkWait(
  HBINK bink
);

In Parameters

bink
Specifies the Bink handle.

Discussion

This function tells you whether it's time to move onto the next frame. It will return a 1 if you should keep waiting, and a 0 if you should move onto the next frame. Basically, the core Bink playback loop is:
1) display a frame,
2) wait until BinkWait returns a zero,
3) loop back to step 1.
Note that there is a lot of logic hidden behind this tiny interface: sound-synchronization, preloading upcoming data, sound servicing, etc. Because all this timing sensitive work is being done in this one little function, you need to call it frequently - several times the frame rate frequency at least. Under Windows and MacOS, you need to yield and process messages while you're waiting on BinkWait. The best way to handle this is to place the call to BinkWait inside your message handling loop. For example, you could do something like this on Win32:

if ( PeekMessage( &msg, 0, 0, 0, PM_REMOVE ) ){  if ( msg.message == WM_QUIT )    break;
  TranslateMessage( &msg );  DispatchMessage( &msg );}else{  if ( !BinkWait( bink ) )  {    // do the BinkDoFrame, BinkCopyToBuffer, BinkNextFrame, blitting, etc in this function    Show_next_frame( bink, bink_buf );  }}

Message handling code like this allows Bink to continue to run while other processes still receive their messages. However, sometimes logic like this is difficult to implement (as in MFC or OWL applications). In these cases, it is still best to try to implement message handling like the example above. This can be accomplished by overloading the appropriate message dispatching function (contact RAD Game Tools for more details on this type of code). Another playback alternative is to use a timer callback and check the BinkWait status there. Note that although this technique can work, Bink really needs BinkWait to be called much more frequently than a timer can usually provide. However, if you create a timer callback that operates at 4 or 5 times the frame rate (so, with a 15 fps Bink file, check BinkWait 75 times a second), then this method may be easier to integrate. If neither a message loop nor a timer call back will work for you, contact RAD Game Tools for other more-complicated alternatives.

Group: Bink API
Related Sections: Bink Video Playback, NTSC and PAL on the Nintendo GameCube, NTSC and PAL on the Xbox, Sharing the CPU on the Nintendo GameCube, Sharing the CPU on the Xbox, Sharing the CPU under MacOS, Sharing the CPU under Win32
Related Functions: BinkDoFrame, BinkNextFrame, BinkPause
Related Basic Types: HBINK, S32


BinkPause

The function BinkPause pauses and resumes playback of a Bink file.

S32 BinkPause(
  HBINK bink,
  S32 pause
);

In Parameters

bink
Specifies the Bink handle.
pause
Specifies whether to pause (non-zero) or resume the movie (zero).

Returns

Returns whether the movie is currently paused or playing

Discussion

This function allows you to easily pause the Bink playback. Pass in a non-zero value to pause the movie, and a zero to resume the movie after a pause. Once you call this function, BinkWait will return 1 until you resume the movie. The audio will also be paused after this function has been called.

Group: Bink API
Related Functions: BinkWait
Related Basic Types: HBINK, S32


BinkGetRects

The function BinkGetRects returns the dirty rectangles of the last decompressed video frame.

S32 BinkGetRects(
  HBINK bink,
  BINK_GETRECTS_FLAGS getrects_flags
);

In Parameters

bink
Specifies the Bink handle.
getrects_flags
Specifies the type of rectangle list you'd prefer.

Returns

Returns the number of dirty rectangles found.

Discussion

This function returns one or more dirty rectangles that outline the frame areas that changed in the last call to BinkDoFrame. "Dirty rectangles" are the rectangles that enclose all of the pixels that changes from the previous frame to this frame. The dirty rectangles are placed in the FrameRects field of the BINK structure. You will usually pass the dirty rectangle information directly to the BinkBufferBlit function for blasting onto the screen. If you are using BinkBuffers, you can use the SurfaceType field in your BinkBuffer structure for the getrects_flags parameter. This function returns the number of dirty rectangles found.

Group: Bink API
Related Functions: BinkBufferBlit, BinkDoFrame
Related Basic Types: BINK_GETRECTS_FLAGS, HBINK, S32
Related Structures: BINK


BINK_GETRECTS_FLAGS

The basic type BINK_GETRECTS_FLAGS Specifies the type of rectangle list you'd prefer from the BinkGetRects function.

Fundamental Values

Value | Description
BINKSURFACEFAST | Return lots of little rectangles (for fast blitters).
BINKSURFACESLOW | Return just one or two rectangles (for slow blitters).
BINKSURFACEFAST | Return no rectangles at all (when copying to the primary surface, for example).

Discussion

These flags are used with the BinkGetRects function to specify which type of dirty rectangles you'd prefer.

Group: Bink API
Related Functions: BinkGetRects


BinkGoto

The function BinkGoto jumps to a new frame inside the Bink file.

void BinkGoto(
  HBINK bink,
  U32 frame_num,
  BINK_GOTO_FLAGS goto_flags
);

In Parameters

bink
Specifies the Bink handle.
frame_num
Specifies the frame number to jump to.
goto_flags
Specifies the type of jump to perform.

Discussion

This function allows you to immediately skip to another frame in a Bink file. The frame_num parameter specifies which frame to skip to (the first frame is frame 1). If the new frame data is in Bink's read ahead memory, then this function will be performed instantly (only a few pointers are updated). However, if the new frame data is outside Bink's read buffer, then Bink has to do a seek (slow on a CD-ROM), and then read the frame's data. Even with a seek, though, BinkGoto is still pretty fast. It's often difficult to notice a seek pause at all. You can also find the nearest key frame manually with the BinkGetKeyFrame function.

Group: Bink API
Related Sections: Critical File I/O handling in Bink
Related Functions: BinkGetKeyFrame
Related Basic Types: BINK_GOTO_FLAGS, HBINK, U32, void


BINK_GOTO_FLAGS

The basic type BINK_GOTO_FLAGS Specifies the type of jump to perform.

Fundamental Values

Value | Description
NULL | By default (using no flags), Bink performs a jump by seeking to the nearest key frame and then decompressing up to your specified frame.
BINKGOTOQUICK | Use this flag to force Bink to jump directly to the frame, and not bother with the key frame seek first (this may cause the frames after a jump to be displayed incorrectly).
BINKGOTOQUICKSOUND | Bink stores the first 750 milliseconds of audio in the first frame of the movie. That means if you go to, say, frame 500, Bink has to internally jump to frame 500 minus 750 milliseconds so that the sound starts immediately when you begin playing again. All of these internal gymnastics to start the sound exactly at your frame is transparent to you, except that extra I/O is performed as well as a little extra CPU is consumed to make it all happen. However, if you use the BINKGOTOQUICKSOUND flag, then you save this I/O and CPU - Bink just doesn't skip back the 750 milliseconds, so the first 750 ms after the BinkGoto will be just silence. This is handy when you need the fastest possible jump without concern for the sound.

Discussion

These flags are used with the BinkGoto function to specify which type of jump you want to perform. You can also find the nearest key frame manually with the BinkGetKeyFrame function.

Group: Basic Types, Bink API
Related Functions: BinkGetKeyFrame, BinkGoto


BinkGetKeyFrame

The function BinkGetKeyFrame finds a key frame near another specified frame.

U32 BinkGetKeyFrame(
  HBINK bink,
  U32 frame_num,
  BINK_GETKEY_FLAGS getkey_flags
);

In Parameters

bink
Specifies the Bink handle.
frame_num
Specifies the frame number to search on.
getkey_flags
Specifies the type of key frame search to perform.

Returns

Returns the nearest key frame.

Discussion

This function allows you to find key frames near the specified frame number. Simply pass in the frame number that you're interested in, and Bink will find the closest key frame using the search style specified by the flags parameter.

Group: Bink API
Related Functions: BinkGoto
Related Basic Types: BINK_GETKEY_FLAGS, BINK_GOTO_FLAGS, HBINK, U32


BINK_GETKEY_FLAGS

The basic type BINK_GETKEY_FLAGS Specifies the type of key frame search to perform.

Fundamental Values

Value | Description
BINKGETKEYPREVIOUS | Finds the first key frame before or equal to frame.
BINKGETKEYNEXT | Finds the first key frame after or equal to frame.
BINKGETKEYCLOSEST | Find the key frame closest or equal to frame (searches before and after).
BINKGETKEYNOTEQUAL | You use this flag OR-ed with one of the other flags to tell Bink not to return a key frame equal to your specified frame.

Discussion

These flags are used with the BinkGetKeyFrame function to specify which type of key frame search that you wish to perform.

Group: Bink API
Related Functions: BinkGetKeyFrame


BinkService

The function BinkService gives some explicit idle time to Bink to service any of its internal tasks.

void BinkService(
  HBINK bink
);

In Parameters

bink
Specifies the Bink handle.

Discussion

This function will perform any background Bink services explicitly. This function can be called periodically when you have an extremely CPU-intensive task that is causing the sound to break up.

Group: Bink API
Related Basic Types: HBINK, void


BinkSoundUseMiles

The function BinkSoundUseMiles tells Bink to use the Miles Sound System as its sound output system.

S32 BinkSoundUseMiles(
  VOID_PTR hDigDriver
);

In Parameters

hDigDriver
Specifies the Miles Sound System HDIGDRIVER handle that is returned from the Miles function, AIL_waveOutOpen.

Returns

Returns whether Bink successfully switched to Miles as its output layer (non-zero for success, zero for failure).

Discussion

This function (macro actually) tells Bink to use the Miles Sound System for its audio output. This function is global - you only need to call it once. You must, however, call it before you call BinkOpen for the first time, or the function will fail.

Group: Bink API
Related Sections: Sound under Win32
Related Functions: BinkOpen, BinkSetSoundSystem, BinkSoundUseAX, BinkSoundUseDirectSound, BinkSoundUseMusyX, BinkSoundUseSoundManager
Related Basic Types: S32, VOID_PTR


BinkSoundUseDirectSound

The function BinkSoundUseDirectSound tells Bink to use DirectSound as its sound output system.

S32 BinkSoundUseDirectSound(
  LPDIRECTSOUND lpDirectSound
);

In Parameters

lpDirectSound
Specifies the DirectSound object handle that is returned from the DirectSound function, CreateDirectSound.

Returns

Returns whether Bink successfully switched to DirectSound as its output layer (non-zero for success, zero for failure).

Discussion

This function (macro actually) tells Bink to use DirectSound for its audio output. This function is global - you only need to call it once. You must, however, call it before you call BinkOpen for the first time, or the function will fail.

Group: Bink API
Related Sections: Sound under Win32
Related Functions: BinkOpen, BinkSetSoundSystem, BinkSoundUseAX, BinkSoundUseMiles, BinkSoundUseMusyX, BinkSoundUseSoundManager
Related Basic Types: LPDIRECTSOUND, S32


BinkSoundUseSoundManager

The function BinkSoundUseSoundManager tells Bink to use the MacOS Sound Manager as its sound output system.

S32 BinkSoundUseSoundManager();

Returns

Returns whether Bink successfully switched to Sound Manager as its output layer (non-zero for success, zero for failure).

Discussion

This function (macro actually) tells Bink to use the MacOS Sound Manager for its audio output. You usually don't have to call this function - it is automatically called inside BinkOpen on the Mac. This function is global - you only need to call it once. You must, however, call it before you call BinkOpen for the first time, or the function will fail.

Group: Bink API
Related Functions: BinkOpen, BinkSetSoundSystem, BinkSoundUseAX, BinkSoundUseDirectSound, BinkSoundUseMiles, BinkSoundUseMusyX
Related Basic Types: S32


BinkSoundUseAX

The function BinkSoundUseAX tells Bink to use AX as its sound output system on the Nintendo GameCube.

S32 BinkSoundUseAX(
  RADARAMCALLBACKS const *callbacks
);

In Parameters

callbacks
a pointer to a RADARAMCALLBACKS structure that contains the ARAM memory management callbacks to use.

Returns

Returns whether Bink successfully switched to AX as its output layer (non-zero for success, zero for failure).

Discussion

This function (macro actually) tells Bink to use AX for its audio output on the Nintendo GameCude. MusyX users should use BinkSoundUseMusyX instead. This function is global - you only need to call it once. You must, however, call it before you call BinkOpen for the first time, or the function will fail.

Group: Bink API
Related Sections: Sound on the Nintendo GameCube
Related Functions: BinkOpen, BinkSetSoundSystem, BinkSoundUseDirectSound, BinkSoundUseMiles, BinkSoundUseMusyX, BinkSoundUseSoundManager, RADARAMALLOC, RADARAMFREE
Related Basic Types: S32
Related Structures: RADARAMCALLBACKS


BinkSoundUseMusyX

The function BinkSoundUseMusyX tells Bink to use MusyX as its sound output system on the Nintendo GameCube.

S32 BinkSoundUseMusyX();

Returns

Returns whether Bink successfully switched to MusyX as its output layer (non-zero for success, zero for failure).

Discussion

This function (macro actually) tells Bink to use MusyX for its audio output on the Nintendo GameCude. AX users should use BinkSoundUseAX instead. This function is global - you only need to call it once. You must, however, call it before you call BinkOpen for the first time, or the function will fail.

Group: Bink API
Related Sections: Sound on the Nintendo GameCube
Related Functions: BinkOpen, BinkSetSoundSystem, BinkSoundUseAX, BinkSoundUseDirectSound, BinkSoundUseMiles, BinkSoundUseSoundManager
Related Basic Types: S32


RADARAMCALLBACKS

The structure RADARAMCALLBACKS specifies a set of replacement audio RAM memory management functions for use with AX on the Nintendo GameCube.

struct RADARAMCALLBACKS
{
  RADARAMALLOC mem_alloc;
  RADARAMFREE mem_free;
};

In Members

mem_alloc
Specifies the function to call to allocate audio memory.
mem_free
Specifies the function to call to free audio memory that was allocated by mem_alloc.

Discussion

This structure contains callbacks to an allocation and a free function to manage the audio RAM that Bink uses when using AX on the Nintendo GameCube.

Group: Bink API
Related Functions: BinkSoundUseAX, RADARAMALLOC, RADARAMFREE


RADARAMALLOC

The function RADARAMALLOC points to a function that will allocate audio memory on Bink's behalf when using AX on the Nintendo GameCube.

VOID_PTR RADLINK RADARAMALLOC(
  U32 num_bytes
);

In Parameters

num_bytes
Specifies the number of bytes of memory to allocate.

Returns

Returns the new pointer or 0.

Discussion

This function replaces the function that Bink calls to allocate audio memory when using AX on the Nintendo GameCube. It should return a pointer to at least num_bytes of audio memory. If the allocation fails, you can return 0 and Bink will fail the allocation.

Group: Bink API
Related Functions: BinkSoundUseAX, RADARAMFREE
Related Basic Types: U32, VOID_PTR
Related Structures: RADARAMCALLBACKS


RADARAMFREE

The function RADARAMFREE points to a function that will free memory allocated by a previous call to the RADARAMALLOC function.

void RADLINK RADARAMFREE(
  VOID_PTR ptr
);

In Parameters

ptr
Specifies a pointer that was previously allocated by RADARAMALLOC.

Discussion

This function replaces the function that Bink calls to free audio memory when using AX on the Nintendo GameCube. It should be able to free any pointer that has been returned from RADARAMALLOC.

Group: Bink API
Related Functions: BinkSoundUseAX, RADARAMALLOC
Related Basic Types: VOID_PTR, void
Related Structures: RADARAMCALLBACKS


BinkSetSoundSystem

The function BinkSetSoundSystem tells Bink to use a custom sound provider as its sound output system.

S32 BinkSetSoundSystem(
  VOID_PTR BinkOpenSoundSystemFunction,
  U32 param_value
);

In Parameters

BinkOpenSoundSystemFunction
Specifies the function to call to open the custom sound system object.
param_value
Specifies a 32-bit sound system defined parameter to pass to the OpenSoundSystemFunction function.

Returns

Returns whether Bink successfully switched to the new sound system.

Discussion

This function is the low-level method of switching to a new sound system in Bink. Both BinkSoundUseMiles and BinkSoundUseDirectSound are simply macros that just call this function. You can use this function to write your own sound system provider, but you should note that sound providers are not trivial to write and are almost never necessary. If you are still interested in writing your own provider, contact RAD for details. This function is global - you only need to call it once. You must, however, call it before you call BinkOpen for the first time, or the function will fail.

Group: Bink API
Related Functions: BinkOpen, BinkSoundUseAX, BinkSoundUseDirectSound, BinkSoundUseMiles, BinkSoundUseMusyX, BinkSoundUseSoundManager
Related Basic Types: S32, U32, VOID_PTR


BinkSetVolume

The function BinkSetVolume sets the volume of a Bink sound track.

void BinkSetVolume(
  HBINK bink,
  U32 trackID,
  S32 volume
);

In Parameters

bink
Specifies the Bink handle.
trackID
Specifies the track ID to change the volume for.
volume
Specifies the new volume level.

Discussion

This function sets the volume for the currently playing Bink sound track. The volume parameter specifies the new volume setting from 0 (silent) to 32768 (normal) to 65536 (maximum amplification). Note that most sound systems don't do amplification (neither Miles nor DirectSound does) - in these cases, volumes above 32768 are the same as 32768.

Group: Bink API
Related Sections: Audio Tracks in Bink
Related Functions: BinkSetPan, BinkSetSoundOnOff
Related Basic Types: HBINK, S32, U32, void


BinkSetPan

The function BinkSetPan sets the speaker pan (left to right balance) of a Bink sound track.

void BinkSetPan(
  HBINK bink,
  U32 trackID,
  S32 pan
);

In Parameters

bink
Specifies the Bink handle.
trackID
Specifies the track ID to change the pan for.
pan
Specifies the new pan setting.

Discussion

This function sets the speaker pan (left to right balance) for the currently playing Bink sound track. The pan parameter specifies the new left to right balance setting from 0 (all the way left) to 32768 (split evenly between left and right), and 65536 (all the way right). You can't set the pan on an Xbox. To control the pan on an Xbox, use the BinkSetMixBins and BinkSetMixBinVolumes functions.

Group: Bink API
Related Sections: Audio Tracks in Bink
Related Functions: BinkSetMixBinVolumes, BinkSetMixBins, BinkSetVolume
Related Basic Types: HBINK, S32, U32, void


BinkSetMixBins

The function BinkSetMixBins sets the mix bin destination of the sound track on an Xbox.

void BinkSetMixBins(
  HBINK bink,
  U32 trackID,
  u32_ptr mix_bins,
  U32 total
);

In Parameters

bink
Specifies the Bink handle.
trackID
Specifies the track ID to change the mix bin for.
mix_bins
Points to an array of mix bin destinations.
total
The number of mix bins in the mix_bins array.

Discussion

This function sets the mix bins for the currently playing Bink sound track on an Xbox. See the Xbox documentation for the mix bin destination values. You usually use this function to play back 5.1 sound tracks on an Xbox.

Group: Bink API
Related Sections: Audio Tracks in Bink, Sound on the Xbox
Related Functions: BinkSetMixBinVolumes, BinkSetPan
Related Basic Types: HBINK, U32, u32_ptr, void


BinkSetMixBinVolumes

The function BinkSetMixBinVolumes sets the volumes of the individual mix bins on an Xbox.

void BinkSetMixBinVolumes(
  HBINK bink,
  U32 trackID,
  u32_ptr mix_bins,
  s32_ptr volumes,
  U32 total
);

In Parameters

bink
Specifies the Bink handle.
trackID
Specifies the track ID to change the mix bin volumes for.
mix_bins
Points to an array of the mix bins for each of the volumes.
volumes
Points to an array of the new volume levels.
total
The number of mix bins and volumes in the mix_bins and volumes arrays.

Discussion

This function allows you to set the volume for each of the mix bin destinations on an Xbox. See the Xbox documentation for the mix bin destination values. The volume parameter specifies the new volume setting from 0 (silent) to 32768 (normal) to 65536 (maximum amplification). Note that most sound systems don't do amplification (neither Miles nor DirectSound does) - in these cases, volumes above 32768 are the same as 32768.

Group: Bink API
Related Sections: Audio Tracks in Bink
Related Functions: BinkSetMixBins, BinkSetPan
Related Basic Types: HBINK, U32, s32_ptr, u32_ptr, void


BinkSetVideoOnOff

The function BinkSetVideoOnOff tells Bink not to decompress the video frames when BinkDoFrame is called.

S32 BinkSetVideoOnOff(
  HBINK bink,
  S32 on_off
);

In Parameters

bink
Specifies the Bink handle.
on_off
Specifies the whether the video should be decompressed (non-zero), or whether just the audio should be decompressed (zero).

Returns

Returns whether the video is currently on (non-zero) or off (zero).

Discussion

This function allows you to shut off the video decompression of a playing Bink file. This is useful when you want to only play the audio track of a Bink file and don't care about decompressing the video track. This function is a toggle, so you call it once with a zero to turn off the video, and then you call it again with a non-zero value to start the video playback again. This function returns non-zero if the video is on, and a zero if the video is turned off.

Group: Bink API
Related Functions: BinkSetSoundOnOff
Related Basic Types: HBINK, S32


BinkSetSoundOnOff

The function BinkSetSoundOnOff tells Bink not to decompress the audio and release any audio resources.

S32 BinkSetSoundOnOff(
  HBINK bink,
  S32 on_off
);

In Parameters

bink
Specifies the Bink handle.
on_off
Specifies the whether the sound track should be processed (non-zero), or whether Bink skip decompressing the audio.

Returns

Returns whether the sound is currently on (non-zero) or off (zero).

Discussion

This function allows you to shut off the audio playback of a Bink file. This is useful if you want to stop all sound completely, or if you need to release the digital sound resource handles to play a wave or AVI file. Note that this function is not a mute function! If you want to mute the audio, call BinkSetVolume with zero for the volume level. If you know that you are never going to play the audio, then don't use this function and instead call BinkSetSoundTrack with zero for both parameters before opening the Bink file with the BINKSNDTRACK flag. This function is a toggle, so you call it once with zero to turn off the sound, and then you call it again with a non-zero value to start the audio playback again. This function returns non-zero if the audio is on, and zero if the audio is turned off.

Group: Bink API
Related Functions: BinkSetSoundTrack, BinkSetVideoOnOff, BinkSetVolume
Related Basic Types: BINK_OPEN_FLAGS, HBINK, S32


BinkGetSummary

The function BinkGetSummary returns playback information about the specified Bink handle.

void BinkGetSummary(
  HBINK bink,
  BINKSUMMARY *summary
);

In Parameters

bink
Specifies the Bink handle.

Out Parameters

summary
Specifies the structure to return the summary information in.

Discussion

This function returns all kinds of useful information about a Bink file that you have just played. You will usually call this function right before you close the Bink file.

Group: Bink API
Related Sections: Memory management on the Nintendo GameCube, Memory management on the Xbox, Memory management under MacOS, Memory management under Win32
Related Functions: BinkClose, BinkDoFrame, BinkGetRealtime
Related Basic Types: HBINK, void
Related Structures: BINKSUMMARY


BINKSUMMARY

The structure BINKSUMMARY is a structure used to return playback summary information from BinkGetSummary.

struct BINKSUMMARY
{
  U32 Width;
  U32 Height;
  U32 TotalTime;
  U32 FileFrameRate;
  U32 FileFrameRateDiv;
  U32 FrameRate;
  U32 FrameRateDiv;
  U32 TotalOpenTime;
  U32 TotalFrames;
  U32 TotalPlayedFrames;
  U32 SkippedFrames;
  U32 SkippedBlits;
  U32 SoundSkips;
  U32 TotalBlitTime;
  U32 TotalReadTime;
  U32 TotalVideoDecompTime;
  U32 TotalAudioDecompTime;
  U32 TotalIdleReadTime;
  U32 TotalBackReadTime;
  U32 TotalReadSpeed;
  U32 SlowestFrameTime;
  U32 Slowest2FrameTime;
  U32 SlowestFrameNum;
  U32 Slowest2FrameNum;
  U32 AverageDataRate;
  U32 AverageFrameSize;
  U32 HighestMemAmount;
  U32 TotalIOMemory;
  U32 HighestIOUsed;
  U32 Highest1SecRate;
  U32 Highest1SecFrame;
};

Out Members

Width
Specifies the width of the Bink file.
Height
Specifies the height of the Bink file.
TotalTime
Specifies the total playback time (in milliseconds).
FileFrameRate
Along with FileFrameRateDiv, specifies the original frame rate of the Bink file. The frame rate is calculated by (summary->FileFrameRate/summary->FileFrameRateDiv). The file frame rate is the frame rate of the file before you overrode the frame rate with BinkSetFrameRate.
FileFrameRateDiv
Specifies the original frame rate divisor of the Bink file.
FrameRate
Along with FrameRateDiv, specifies the frame rate of the Bink file. The frame rate is calculated by (summary->FrameRate/summary->FrameRateDiv).
FrameRateDiv
Specifies the frame rate divisor of the Bink file.
TotalOpenTime
Specifies the time to open and prepare the Bink file for decompression.
TotalFrames
Specifies the number of frames in the Bink file.
TotalPlayedFrames
Specifies the number of frames played.
SkippedFrames
Specifies the number of frames that had to be skipped during playback.
SkippedBlits
Specifies the number of blitting stages that had to be skipped during playback.
SoundSkips
Specifies the number of times that the sound dropped out during playback.
TotalBlitTime
Specifies the time spent blitting (in milliseconds).
TotalReadTime
Specifies the time spent reading in the foreground (in milliseconds).
TotalVideoDecompTime
Specifies the time spent decompressing the video (in milliseconds).
TotalAudioDecompTime
Specifies the time spent decompressing the audio (in milliseconds).
TotalIdleReadTime
Specifies the time spent reading at idle time (in milliseconds).
TotalBackReadTime
Specifies the time spent reading in the background thread (in milliseconds).
TotalReadSpeed
Specifies the device reading IO speed (in bytes/second).
SlowestFrameTime
Specifies the slowest single frame time (in milliseconds).
Slowest2FrameTime
Specifies the second-slowest single frame time (in milliseconds).
SlowestFrameNum
Specifies the slowest single frame number.
Slowest2FrameNum
Specifies the second-slowest single frame number.
AverageDataRate
Specifies the average data rate of the movie (in bytes/second).
AverageFrameSize
Specifies the average size of the frames (in bytes).
HighestMemAmount
Specifies the highest amount of memory allocated at one time during playback (in bytes).
TotalIOMemory
Specifies the size of the IO buffer used to read ahead in the Bink file (in bytes).
HighestIOUsed
Specifies the highest level that the read ahead IO buffer was filled to (in bytes).
Highest1SecRate
Specifies the highest one second data rate in the Bink file (in bytes/second).
Highest1SecFrame
Specifies the starting frame of the highest one second data rate in the Bink file.

Discussion

The BINKSUMMARY structure is used in the BinkGetSummary function. It returns the playback statistics of a complete playback of a Bink file.

Group: Bink API
Related Functions: BinkGetSummary, BinkSetFrameRate
Related Basic Types: U32


BinkGetRealtime

The function BinkGetRealtime returns realtime playback information about the specified Bink handle.

void BinkGetRealtime(
  HBINK bink,
  BINKREALTIME *real_time,
  U32 frame_window_length
);

In Parameters

bink
Specifies the Bink handle.
frame_window_length
Specifies the frame window length to return the realtime information for (in frames).

Out Parameters

real_time
Specifies the structure to return the realtime information in.

Discussion

This function returns realtime information about the currently playing Bink file. You can display exactly what's going on in the Bink playback while you watch the movie! You can examine the realtime information over one or more frame's worth of time by setting the frame_window_length parameter. For simplicity, you can just use 0 for the frame_window_length parameter (which tells Bink to report on the last one second's worth of frames).

Group: Bink API
Related Functions: BinkGetSummary
Related Basic Types: HBINK, U32, void
Related Structures: BINKREALTIME


BINKREALTIME

The structure BINKREALTIME is a structure used to return realtime playback information from BinkGetRealtime.

struct BINKREALTIME
{
  U32 FrameNum;
  U32 FrameRate;
  U32 FrameRateDiv;
  U32 Frames;
  U32 FramesTime;
  U32 FrameVideoDecompTime;
  U32 FrameAudioDecompTime;
  U32 FrameReadTime;
  U32 FrameIdleReadTime;
  U32 FrameThreadReadTime;
  U32 FramesBlitTime;
  U32 ReadBufferSize;
  U32 ReadBufferUsed;
  U32 FramesDataRate;
};

Out Members

FrameNum
Specifies the current frame number.
FrameRate
Along with FrameRateDiv, specifies the frame rate of the Bink file. The frame rate is calculated by (realtime->FrameRate/realtime->FrameRateDiv). So, for example, at 15 fps, FrameRate would be 15 and FrameRateDiv would be 1.
FrameRateDiv
Specifies the frame rate divisor of the Bink file.
Frames
Specifies the number of frames in the frame window.
FramesTime
Specifies the total time that the frame window covers (in milliseconds).
FrameVideoDecompTime
Specifies the amount of time spent decompressing the video inside the frame window.
FrameAudioDecompTime
Specifies the amount of time spent decompressing the audio inside the frame window.
FrameReadTime
Specifies the amount of time spent reading from the device in the foreground inside the frame window.
FrameIdleReadTime
Specifies the amount of time spent reading from the device during idle time inside the frame window.
FrameThreadReadTime
Specifies the amount of time spent reading from the device in the background thread inside the frame window.
FramesBlitTime
Specifies the amount of time spent blitting to the screen inside the frame window.
ReadBufferSize
Specifies the current maximum IO buffer size in bytes.
ReadBufferUsed
Specifies the current IO buffer size that is preloaded (divide this value by ReadBufferSize for a percent-full indicator).
FramesDataRate
Specifies the current frame window data rate in bytes per second.

Discussion

The BINKREALTIME structure is used in the BinkGetRealtime function. It returns the realtime playback statistics of a playing Bink file.

Group: Bink API
Related Functions: BinkGetRealtime
Related Basic Types: U32


BinkGetTrackID

The function BinkGetTrackID returns the track ID for the specified track index.

U32 BinkGetTrackID(
  HBINK bink,
  U32 track_index
);

In Parameters

bink
Specifies the Bink handle.
track_index
Specifies the track index to query.

Returns

Returns the track ID of the specified track index.

Discussion

Track indexes in Bink always range from zero to the maximum number of audio tracks in the file. This function allows you to get the original track ID that was entered by the person that mixed your Bink files. The maximum number of tracks in a Bink file is specified by the NumTracks field of the BINK structure. So, if NumTracks was 2, then valid track indexes would be 0 and 1.

Group: Bink API
Related Sections: Audio Tracks in Bink
Related Functions: BinkCloseTrack
Related Basic Types: HBINK, U32
Related Structures: BINK


BinkOpenTrack

The function BinkOpenTrack opens a handle to the low-level audio track decoder.

HBINKTRACK BinkOpenTrack(
  HBINK bink,
  U32 track_index
);

In Parameters

bink
Specifies the Bink handle.
track_index
Specifies the track index to open.

Returns

Returns a track ID handle to extract audio from.

Discussion

This function allows you to open an audio track that you can use to extract the low-level sound data from. This function is usually used by applications that are routing sound to their own audio playback system. The returned HBINKTRACK handle is also a pointer to a BINKTRACK structure which contains format information about the audio track. The maximum number of tracks in a Bink file is specified by the NumTracks field of the BINK structure. So, if NumTracks was 2, then valid track indexes would be 0 and 1. This function is rarely used - most of the time audio playback is completely automatic with Bink.

Group: Bink API
Related Functions: BinkCloseTrack, BinkGetTrackData
Related Basic Types: HBINK, HBINKTRACK, U32
Related Structures: BINK, BINKTRACK


BINKTRACK

The structure BINKTRACK is a structure returned from BinkOpenTrack.

struct BINKTRACK
{
  U32 Frequency;
  U32 Bits;
  U32 Channels;
  U32 MaxSize;
};

Out Members

Frequency
Specifies the sound frequency of the audio track.
Bits
Specifies the bit depth of the audio track (8 or 16).
Channels
Specifies the number of channels in the audio track (1 = mono, 2 = stereo).
MaxSize
Specifies the maximum amount of sound data in bytes that is stored in any one video frame of the movie (usually frame 1). You need to allocate this large of a buffer for the destination address passed to BinkGetTrackData.

Discussion

The BINKTRACK structure is pointed to by the HBINKTRACK handle that is returned from BinkOpenTrack. You can dereference the pointer to access any of these information fields. Note that you should never change any of these values!

Group: Bink API
Related Functions: BinkGetTrackData, BinkOpenTrack
Related Basic Types: HBINKTRACK, U32


BinkCloseTrack

The function BinkCloseTrack closes a low-level audio track decoder handle.

void BinkCloseTrack(
  HBINKTRACK bink_track
);

In Parameters

bink_track
Specifies the handle to close.

Discussion

This function closes a Bink audio track handle that was opened with the BinkOpenTrack function. This function is rarely used - most of the time audio playback is completely automatic with Bink.

Group: Bink API
Related Functions: BinkCloseTrack, BinkGetTrackData, BinkGetTrackID, BinkOpenTrack
Related Basic Types: HBINKTRACK, void


BinkGetTrackData

The function BinkGetTrackData extracts all of the sound in the current video frame.

U32 BinkGetTrackData(
  HBINKTRACK bink_track,
  VOID_PTR dest_addr
);

In Parameters

bink_track
Specifies the handle to extract from.
dest_addr
Address where the samples should be decoded into.

Returns

Returns the number of bytes decoded.

Discussion

This function extracts all of the audio data for the current video frame. The dest_addr pointer must be large enough to contain the maximum amount of sound that will be decoded (which will be on frame 1). You can get the largest size necessary by looking at the MaxSize field in the BINKTRACK structure. This function is rarely used - most of the time audio playback is completely automatic with Bink.

Group: Bink API
Related Functions: BinkCloseTrack, BinkOpenTrack
Related Basic Types: HBINKTRACK, U32, VOID_PTR
Related Structures: BINKTRACK


BinkSetFrameRate

The function BinkSetFrameRate overrides the Bink file's built-in frame rate.

void BinkSetFrameRate(
  U32 frame_rate,
  U32 frame_rate_div
);

In Parameters

frame_rate
Along with FrameRateDiv, specifies the frame rate to use. The frame rate is calculated as FrameRate/FrameRateDiv. So, for example, at 15 fps, FrameRate would be 15 and FrameRateDiv would be 1.
frame_rate_div
Specifies the frame rate divisor.

Discussion

This function allows you to alter the playback speed of a Bink file at run-time. If the Bink file has audio, the sound will be sped-up or slowed-down to maintain audio/video sync. To use this function, you first make this call and then you add the BINKFRAMERATE flag in your BinkOpen call.

Group: Bink API
Related Sections: NTSC and PAL on the Nintendo GameCube, NTSC and PAL on the Xbox
Related Functions: BinkOpen
Related Basic Types: BINK_OPEN_FLAGS, U32, void
Related Structures: BINKSUMMARY


BinkSetSoundTrack

The function BinkSetSoundTrack overrides the Bink file's default sound track.

void BinkSetSoundTrack(
  U32 track_count,
  u32_ptr track_id
);

In Parameters

track_count
Specifies the number of tracks to play (the number of tracks in the track_ids array). To play no sound at all, use zero for this parameter.
track_id
Points to an array of sound track IDs to play.

Discussion

This function allows you to set the sound track IDs to play when opening a Bink file. By default, Bink plays the first sound track in the file. If you don't want any sound tracks to play at all, use zero for the track_count parameter. To use this function, you first make this call and then you add the BINKSNDTRACK flag in your BinkOpen call. You can use this function to play back 5.1 audio on an Xbox.

Group: Bink API
Related Sections: Audio Tracks in Bink, Sound on the Xbox
Related Functions: BinkOpen, BinkSetSoundOnOff
Related Basic Types: BINK_OPEN_FLAGS, U32, u32_ptr, void


BinkSetSimulate

The function BinkSetSimulate tells Bink to simulate a specified device I/O speed.

void BinkSetSimulate(
  U32 sim_speed
);

In Parameters

sim_speed
Specifies the speed in bytes per second to simulate.

Discussion

This function allows you to simulate a given playback speed. This is handy when you want to see how a Bink movie will play on a particular speed of CD-ROM. This value is set in bytes per second, so use 150,000 for a 1xCD, 300,000 for a 2xCD, and 600,000 for a 4xCD. To use this function, you first make this call and then you add the BINKSIMULATE flag in your BinkOpen call.

Group: Bink API
Related Functions: BinkOpen
Related Basic Types: BINK_OPEN_FLAGS, U32, void


BinkSetIOSize

The function BinkSetIOSize Specifies the size of the I/O memory buffer that Bink reads into.

void BinkSetIOSize(
  U32 io_size
);

In Parameters

io_size
Specifies the size in bytes that Bink should use for its read ahead IO buffer.

Discussion

This function allows you to set the size of the IO buffer that Bink uses to read ahead in the Bink file. By default, the IO buffer is the size of the highest one-second data rate in the movie. To use this function, you first make this call and then you add the BINKIOSIZE flag in your BinkOpen call.

Group: Bink API
Related Functions: BinkOpen
Related Basic Types: BINK_OPEN_FLAGS, U32, void


BinkSetIO

The function BinkSetIO specifies a set of replacement file I/O functions.

void BinkSetIO(
  VOID_PTR BinkOpenFileFunction
);

In Parameters

BinkOpenFileFunction
Specifies the function to call to open the Bink file.

Discussion

This function allows you to replace the entire Bink IO system. This is definitely a non-trivial job, but with it, you can cause Bink to read from any type of device. Note that this function is almost never necessary! If you are trying to read out of a packed file, then you should use the BINKFILEHANDLE flag - it is much, much simpler. If you are still interested in this support, give us a call at RAD Game Tools and we can get you the source code for the normal file system IO provider as a reference. To use this function, you first make this call and then you add the BINKIOPROCESSOR flag in your BinkOpen call.

Group: Bink API
Related Functions: BinkOpen
Related Basic Types: BINK_OPEN_FLAGS, VOID_PTR, void


RADSetMemory

The function RADSetMemory specifies a set of replacement memory management functions.

void RADSetMemory(
  RADMEMALLOC mem_alloc,
  RADMEMFREE mem_free
);

In Parameters

mem_alloc
Specifies the function to call to allocate memory.
mem_free
Specifies the function to call to free memory that was allocated by mem_alloc.

Discussion

This function allows you to replace the functions that Bink calls to allocate and free memory. On the Nintendo GameCube, you must return 32-byte aligned memory pointers!

Group: Bink API
Related Sections: Memory management on the Nintendo GameCube, Memory management on the Xbox, Memory management under MacOS, Memory management under Win32
Related Functions: RADMEMALLOC, RADMEMFREE
Related Basic Types: void


RADMEMALLOC

The function RADMEMALLOC points to a function that will allocate memory on Bink's behalf.

VOID_PTR RADLINK RADMEMALLOC(
  U32 num_bytes
);

In Parameters

num_bytes
Specifies the number of bytes of memory to allocate.

Returns

Returns the new pointer or 0 or -1 if the allocation failed.

Discussion

This function replaces the function that Bink calls to allocate memory. It should return a pointer to at least num_bytes of memory. If the allocation fails, you can return 0 and Bink will attempt to allocate memory from the operating system, or you can return -1 and Bink will simply fail the allocation. On the Nintendo GameCube, you must return 32-byte aligned memory pointers!

Group: Bink API
Related Functions: RADMEMFREE, RADSetMemory
Related Basic Types: U32, VOID_PTR


RADMEMFREE

The function RADMEMFREE points to a function that will free memory allocated by a previous call to the RADMEMALLOC function.

void RADLINK RADMEMFREE(
  VOID_PTR ptr
);

In Parameters

ptr
Specifies a pointer that was previously allocated by RADMEMALLOC.

Discussion

This function replaces the function that Bink calls to free memory. It should be able to free any pointer that has been returned from RADMEMALLOC.

Group: Bink API
Related Functions: RADMEMALLOC, RADSetMemory
Related Basic Types: VOID_PTR, void


BinkGetError

The function BinkGetError returns a string that describes the last global Bink error.

BINK_STRING BinkGetError();

Returns

Returns the last global Bink error.

Discussion

This function returns a string describing the last global Bink error. It is especially handy if BinkOpen fails.

Group: Bink API
Related Functions: BinkMacOpen, BinkOpen
Related Basic Types: BINK_STRING


BinkGetLogoAddress

The function BinkGetLogoAddress returns a pointer to an embedded Bink logo file.

VOID_PTR BinkGetLogoAddress();

Returns

Returns a pointer to a Bink file that displays the Bink logo.

Discussion

This function returns the address of the embedded Bink logo file. The address returned from this function can be passed directly to BinkOpen using the BINKFROMMEMORY flag. This is a convenient way to access the Bink logo for credits display.

Group: Bink API
Related Functions: BinkOpen
Related Basic Types: BINK_OPEN_FLAGS, VOID_PTR


BinkLoad

The function BinkLoad reloads the Bink sections on an Xbox (if it had been unloaded by BinkUnload).

void BinkLoad();

Discussion

This function reloads Bink into memory if you have unloaded it with the BinkUnload function. By default, both Bink and all of its YUV converters are loaded when your application starts up. You have to unload it before you will need to call this function.

Group: Bink API
Related Sections: Memory management on the Xbox, Sections on the Xbox
Related Functions: BinkLoadConverter, BinkUnload
Related Basic Types: void


BinkUnload

The function BinkUnload unloads the Bink sections on an Xbox.

void BinkUnload();

Discussion

This function unloads Bink from memory. This will save about 100K of memory. Note that you have to unload the Bink YUV converters before calling this function to free all Bink memory. For example, to unload Bink completely from memory, use something like this:

// unload Bink:BinkUnloadConverters( BINKCONVERTERSALL );BinkUnload();// and then to reload Bink, use:BinkLoad();// plus whatever converters your game uses:BinkLoadConverters( BINKSURFACE32 );

Note that once you have unloaded Bink, you must reload it before calling any Bink function other than BinkLoad.

Group: Bink API
Related Sections: Memory management on the Xbox
Related Functions: BinkLoad, BinkUnloadConverter
Related Basic Types: void


BinkLoadConverter

The function BinkLoadConverter reloads one or more of the Bink YUV to RGB converters (if they had been unloaded by BinkUnloadConverter).

void BinkLoadConverter(
  BINK_CONVERTER_FLAGS flags
);

In Parameters

flags
Specifies the converter to load.

Discussion

This function reloads one or more of the Bink YUV converters into memory. You can use memory most effectively by loading just the YUV converters that your game actually uses. For example, say you use the BINKSURFACE32 and BINKSURFACE32A surface types, use the following code to load the minimum coverters:

// First, unload all of the converters.BinkUnloadConverter( BINKCONVERTERSALL );
// Next, load just the converters you're going to use.BinkLoadConverter( BINKSURFACEYUY2 );BinkLoadConverter( BINKSURFACE32A );

Group: Bink API
Related Sections: Memory management on the Xbox, Sections on the Xbox
Related Functions: BinkLoad, BinkUnloadConverter
Related Basic Types: BINK_CONVERTER_FLAGS, BINK_COPY_FLAGS, void


BinkUnloadConverter

The function BinkUnloadConverter unloads one or more of the Bink YUV to RGB converters.

void BinkUnloadConverter(
  BINK_CONVERTER_FLAGS flags
);

In Parameters

flags
Specifies the converter to unload.

Discussion

This function unloads one or more of the Bink YUV converters from memory. You can use memory most effectively by loading just the YUV converters that your game actually uses. For example, say you use the BINKSURFACE32 and BINKSURFACE32A surface types, use the following code to load the minimum coverters:

// First, unload all of the converters.BinkUnloadConverter( BINKCONVERTERSALL );
// Next, load just the converters you're going to use.BinkLoadConverter( BINKSURFACEYUY2 );BinkLoadConverter( BINKSURFACE32A );

Group: Bink API
Related Sections: Memory management on the Xbox
Related Functions: BinkLoadConverter, BinkUnload
Related Basic Types: BINK_CONVERTER_FLAGS, BINK_COPY_FLAGS, void


BINK_CONVERTER_FLAGS

The basic type BINK_CONVERTER_FLAGS Specifies the class of Bink YUV converters to load or unload.

Fundamental Values

Value | Description
BINKCONVERTERSALL | Loads or unloads all of the Bink YUV converters.
BINKSURFACE32 | 32-bit native RGB data (on Win32: BGRxBGRx, etc; on MacOS: xRGBxRGB, etc).
BINKSURFACE32A | 32-bit native RGB data with alpha (On Win32: BGRABGRA, etc).
BINKSURFACE32R | 32-bit reversed RGB data (RGBxRGBx, etc). This surface type isn't supported on Xbox.
BINKSURFACE32RA | 32-bit reversed RGB data with alpha (RGBARGBA, etc). In OpenGL, this is GL_RGBA. This surface type isn't supported on Xbox.
BINKSURFACE555 | 16-bit 555 RGB high-color surface.
BINKSURFACE565 | 16-bit 565 RGB high-color surface.
BINKSURFACE655 | 16-bit 655 RGB high-color surface.
BINKSURFACE664 | 16-bit 664 RGB high-color surface.
BINKSURFACE4444 | 16-bit 4444 RGB high-color surface with alpha.
BINKSURFACE5551 | 16-bit 5551 RGB high-color surface with one bit alpha.
BINKCONVERTERSMONO | Used with one of the surface flags to test Bink to unload or load the monochrome version of the converter too.
BINKCONVERTERS2X | Used with one of the surface flags to test Bink to unload or load the 2x width version of the converter too.

Group: Bink API
Related Functions: BinkLoadConverter, BinkUnloadConverter


BinkBuffer API

Discussion

The BinkBuffer API was written to make adding YUV blitting to your applications easy. Under Win32, the BinkBuffer API supports five different primary blitting styles (primary, DIBSection, overlay, YUV off-screen and RGB off-screen) and allows you to switch easily between them. Under MacOS, the API the direct-to-screen and GWorld blitting styles. The BinkBuffer API is almost identical on Win32 and MacOS, so porting will be easy. The BinkBuffer API is not supported on the Xbox (see ExamXbox.CPP) or Nintendo GameCube (see ExamNbb.C). Note that the BinkBuffer API will get your applications up and running almost immediately, but it is optional. If you already have DirectDraw, Direct3D or your own blitting solution up and running, you can skip the whole BinkBuffer API completely, and just have the Bink API copy right into your surface pointers. Also, BinkBuffers don't necessarily use any extra system memory. Overlays and most of the off-screen surfaces exist in video memory, and primary surface BinkBuffers don't require any extra memory at all! BinkBuffers are used a lot like the Bink API - you open and receive an HBINKBUFFER handle (which is a pointer to a BINKBUFFER structure), use the handle with the BinkBuffer API functions, and finally, close the BinkBuffer when you're done. See the ExamW32.C or ExampleMac.c files for simple examples.

BinkBuffer API
BinkBufferOpen | opens a BinkBuffer (which simplifies blitting YUV data onto the screen).
BINKBUFFER | is a structure returned from BinkBufferOpen.
BINKBUFFER_OPEN_FLAGS | describes the type and capabilities of the BinkBuffer that you wish to open.
BinkBufferClose | closes the specified BinkBuffer handle.
BinkBufferSetDirectDraw | sets the DirectDraw object and primary surface pointers.
BinkBufferLock | locks the BinkBuffer for reading or writing to the pixel buffer.
BinkBufferUnlock | unlocks a BinkBuffer that has been locked with BinkBufferLock.
BinkBufferBlit | copies the pixel data onto the screen (for the off-screen variety of BinkBuffers).
BinkBufferCheckWinPos | adjusts the specified window position coordinates for validity with the current BinkBuffer type.
BinkBufferSetOffset | tells the BinkBuffer that either the window position on the desktop or that the playback offset within the window has changed.
BinkBufferSetScale | sets a new shrinking or stretching scale to use during blitting.
BinkBufferSetResolution | tells Bink to switch video resolution when opening the BinkBuffer.
BinkBufferGetDescription | returns a string describing the blitting style being used by the BinkBuffer.
BinkBufferGetError | returns a string that describes the last global BinkBuffer error.
BinkDDSurfaceType | returns a value describing the format of the specified DirectDraw surface.
BinkDX8SurfaceType | returns a value describing the format of the specified DirectX 8 surface.
BinkGDSurfaceType | returns a value describing the format of the specified MacOS Graphics Device.
BinkIsSoftwareCursor | determines whether the specified mouse cursor is software-based on the specified DirectDraw surface pointer.
BinkCheckCursor | checks to see if the mouse is currently inside the specified window rectangle, and, if so, hides it.
BinkRestoreCursor | restores the mouse cursor to its original state after a BinkCheckCursor call.


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


BINKBUFFER

The structure BINKBUFFER is a structure returned from BinkBufferOpen.

struct BINKBUFFER
{
  U32 Width;
  U32 Height;
  VOID_PTR Buffer;
  S32 BufferPitch;
  BINK_COPY_FLAGS SurfaceType;
  U32 WindowWidth;
  U32 WindowHeight;
  U32 ScreenWidth;
  U32 ScreenHeight;
  U32 ScreenDepth;
};

Out Members

Width
Specifies the width of the BinkBuffer.
Height
Specifies the height of the BinkBuffer.
Buffer
Specifies the address of the internal pixel buffer. This value is only valid inside of BinkBufferLock and BinkBufferUnlock function calls.
BufferPitch
Specifies the pitch in bytes of the internal pixel buffer. This value is only valid inside of BinkBufferLock and BinkBufferUnlock function calls.
SurfaceType
Specifies the flags that should be passed to BinkCopyToBuffer to copy into this BinkBuffer correctly.
WindowWidth
Specifies the width that you should set your window to - it takes into account alignment and the window style of the window that you pass to BinkBufferOpen.
WindowHeight
Specifies the height that you should set your window to - it takes into account alignment and the window style of the window that you pass to BinkBufferOpen.
ScreenWidth
Specifies the current width of the screen in pixels. This is useful to see if your resolution change request was successful.
ScreenHeight
Specifies the current height of the screen in pixels. This is useful to see if your resolution change request was successful.
ScreenDepth
Specifies the current color depth of the screen (8, 16, 24, or 32) in bits. This is useful to see if your resolution change request was successful.

Discussion

The BINKBUFFER structure is pointed to by the HBINKBUFFER handle that is returned from BinkBufferOpen. You can dereference the pointer to access any of these information fields. Note that you should never change any of these values!

Group: BinkBuffer API
Related Functions: BinkBufferLock, BinkBufferOpen, BinkBufferUnlock, BinkCopyToBuffer
Related Basic Types: BINK_COPY_FLAGS, HBINKBUFFER, S32, U32, VOID_PTR


BINKBUFFER_OPEN_FLAGS

The basic type BINKBUFFER_OPEN_FLAGS describes the type and capabilities of the BinkBuffer that you wish to open.

Fundamental Values

Value | Description
BINKBUFFERAUTO | Chooses the best BinkBuffer blitting style available. On Win32, Bink will try to open each of the blitting styles from BINKBUFFERPRIMARY to BINKBUFFERRGBOFFSCREENSYSTEM, looking for the best blitting style that matches your resolution and scaling requirements. On MacOS, Bink will try the BINKBUFFERDIRECT and the BINKBUFFERGWORLD, looking for the best style that matches your specifications.
BINKBUFFERPRIMARY | Win32: Opens a BinkBuffer to the primary surface. This blitting style uses the built-in Bink YUV to RGB conversions, so it is guaranteed to look perfect - it just might be a little slower than hardware conversion styles. The primary surface blitting style is unable to perform any scaling or clipping (but you can use the 2x stretching flags as a parameter to BinkCopyToBuffer to get simple 2x stretching). BinkBufferBlit doesn't have to do any work with this blitting style, because the pixels are put directly on-screen inside the BinkBufferLock/BinkBufferUnlock block).
BINKBUFFERDIBSECTION | Win32: Opens a BinkBuffer that is just a thin layer on top of a Windows DIBSection. This is the only blitting style that doesn't require DirectDraw. The BinkBuffer DIB will be created in the same format as the desktop for the fastest possible blitting. You can still use the BINKBUFFERRESOLUTION flag with this blit type - it will use ChangeDisplaySettings instead of DirectDraw to switch modes.
BINKBUFFERYV12OVERLAY | Win32: Opens a BinkBuffer to a YV12 overlay surface. This is the fastest possible blitting style, but it is also the rarest for a video card to support (some ATI and nVidia cards support it). This blitting style may or may not be able to perform scaling and clipping. BinkBufferBlit doesn't copy the pixels to the screen with this blitting style, rather, it blits color-keyed pixels onto the screen (which causes the overlay pixels to show through). If the color-keyed pixels are already on the screen, then the converted pixels will appear as soon as they are written to inside the BinkBufferLock/BinkBufferUnlock block - just like the primary surface blitting style.
BINKBUFFERUYVYOVERLAY | See next...
BINKBUFFERYUY2OVERLAY | Win32: These two flags open a BinkBuffer to a YUY2 or UYVY overlay surface. These are the most common overlay surfaces and are supported by almost all video cards. This blitting style may or may not be able to perform scaling and clipping. BinkBufferBlit doesn't copy the pixels to the screen with this blitting style, rather, it blits color-keyed pixels onto the screen (which causes the overlay pixels to show through). If the color-keyed pixels are already on the screen, then the converted pixels will appear as soon as they are written to inside the BinkBufferLock/BinkBufferUnlock block - just like the primary surface blitting style.
BINKBUFFERYV12OFFSCREEN | Win32: Opens a BinkBuffer to a YV12 off-screen buffer. With this blitting style, the video driver converts the YUV data to RGB during the blitting stage. This blitting style may or may not perform scaling or clipping. BinkBufferBlit copies the pixels onto the screen - the BinkBufferLock/BinkBufferUnlock block just loads the Bink pixels into the off-screen buffer. The Bink software blitters are usually faster than this blitting style.
BINKBUFFERUYVYOFFSCREEN | See next...
BINKBUFFERYUY2OFFSCREEN | Win32: These two flags open a BinkBuffer to a YUY2 or UYVY off-screen buffer. With this blitting style, the video driver converts the YUV data to RGB during the blitting stage. This blitting style may or may not perform scaling or clipping. BinkBufferBlit copies the pixels onto the screen - the BinkBufferLock/BinkBufferUnlock block just loads the Bink pixels into the off-screen buffer. Pretty much all video cards support at least this level of hardware YUV to RGB conversion. The Bink software blitters are usually faster than this blitting style.
BINKBUFFERRGBOFFSCREENVIDEO | Win32: Opens a BinkBuffer to an off-screen RGB buffer that resides in the video card RAM. With this blitting style, Bink converts the YUV data to an off-screen RGB format. This blitting style is almost always able to perform scaling and clipping. BinkBufferBlit copies the pixels onto the screen - the BinkBufferLock/BinkBufferUnlock block just gets the RGB Bink pixels into the off-screen buffer.
BINKBUFFERRGBOFFSCREENSYSTEM | Win32: Opens a BinkBuffer to an off-screen RGB buffer that resides in the system card RAM. With this blitting style, Bink converts the YUV data to an off-screen RGB format in system memory. This blitting style supports scaling and clipping, but it is the slowest of all of the blitting styles. BinkBufferBlit copies the pixels onto the screen - the BinkBufferLock/BinkBufferUnlock block just gets the RGB Bink pixels into the off-screen buffer. You should almost always use the BINKBUFFERDIBSECTION style instead of this option - it will have the same or better capabilities and is more more widely compatible.
BINKBUFFERDIRECT | MacOS: Opens a BinkBuffer in direct-to-screen mode. This blitting style uses the built-in Bink YUV to RGB conversions, so it is guaranteed to look perfect and will run very fast. The direct-to-screen blitting style is unable to perform any scaling or clipping (but you can use the 2x stretching flags as a parameter to BinkCopyToBuffer to get simple 2x stretching). BinkBufferBlit doesn't have to do any work with this blitting style, because the pixels are put directly on-screen inside the BinkBufferLock/BinkBufferUnlock block).
BINKBUFFERGWORLD | MacOS: Opens a BinkBuffer to a standard MacOS GWorld graphics buffer. This blitting style is the most compatible on MacOS machines, but it will be slower than BINKBUFFERDIRECT. This blitting style is capable of both clipping and scaling. With this blitting style, BinkCopyToBuffer copies into the GWorld and you use BinkBufferBlit to blit the pixels onto the screen.
BINKBUFFERRESOLUTION | Add this flag to one of the above blitting styles to force Bink to switch video mode resolutions when the BinkBuffer is opened. You must call the BinkBufferSetResolution function before using this flag to tell Bink what resolution to switch into. Note that the BinkBuffer will still be opened even if Bink was unable to switch to your requested mode. You should examine the ScreenWidth, ScreenHeight and ScreenDepth fields of the BinkBuffer structure to see if your requested mode was successfully set.
BINKBUFFERSTRETCHXINT | See next...
BINKBUFFERSTRETCHX | See next...
BINKBUFFERSHRINKXINT | See next...
BINKBUFFERSHRINKX | Add one or more of these flags to request the type of X (width) stretching and/or shrinking that you require. The flags with "INT" on the end mean integral stretching or shrinking (a 2x zoom, or a half-size shrink, for example). Many cards can only do integral scaling, so be sure to use the integral flag if that's all you need, or the BinkBuffer could otherwise fail to open.
BINKBUFFERSTRETCHYINT | See next...
BINKBUFFERSTRETCHY | See next...
BINKBUFFERSHRINKYINT | See next...
BINKBUFFERSHRINKY | Add one or more of these flags to request the type of Y (height) stretching and/or shrinking that you require. The flags with "INT" on the end mean integral stretching or shrinking (a 2x zoom, or a half-size shrink, for example). Many cards can only do integral scaling, so be sure to use the integral flag if that's all you need, or the BinkBuffer could otherwise fail to open.

Discussion

Use these flags as the open_flags parameter in the BinkBufferOpen function. They specify the type and capabilities of the YUV blitting buffer that you require. 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.

Group: BinkBuffer API
Related Sections: Locking and Unlocking, Scaling
Related Functions: BinkBufferBlit, BinkBufferGetDescription, BinkBufferLock, BinkBufferOpen, BinkBufferSetResolution, BinkBufferSetScale, BinkBufferUnlock, BinkCopyToBuffer
Related Basic Types: BINKBUFFER_OPEN_FLAGS


BinkBufferClose

The function BinkBufferClose closes the specified BinkBuffer handle.

void BinkBufferClose(
  HBINKBUFFER bink_buf
);

In Parameters

bink_buf
Specifies the BinkBuffer handle that you wish to close.

Discussion

This function simply closes a BinkBuffer and releases all of the associated memory and system resources. You should close any BinkBuffers that you open or you could leak memory or system resources.

Group: BinkBuffer API
Related Sections: Open and Close
Related Functions: BinkBufferOpen
Related Basic Types: HBINKBUFFER, void


BinkBufferSetDirectDraw

The function BinkBufferSetDirectDraw sets the DirectDraw object and primary surface pointers.

void BinkBufferSetDirectDraw(
  LPDIRECTDRAW lpDirectDraw,
  LPDIRECTDRAWSURFACE lpddsPrimary
);

In Parameters

lpDirectDraw
specifies the DirectDraw object pointer to use.
lpddsPrimary
specifies the DirectDraw primary surface object pointer to use.

Discussion

By default, Bink creates its own DirectDraw and primary surface objects. This function is used when you already have DirectDraw up and running in your application. So, if you have already created your own DirectDraw objects, then you should call this function before your first call to BinkBufferOpen.

Group: BinkBuffer API
Related Functions: BinkBufferOpen
Related Basic Types: LPDIRECTDRAW, LPDIRECTDRAWSURFACE, void


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


BinkBufferUnlock

The function BinkBufferUnlock unlocks a BinkBuffer that has been locked with BinkBufferLock.

S32 BinkBufferUnlock(
  HBINKBUFFER bink_buf
);

In Parameters

bink_buf
Specifies the BinkBuffer handle.

Returns

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

Discussion

This function will unlock a locked BinkBuffer. You must unlock any BinkBuffers that you've locked with the BinkBufferLock function as quickly as possible. If you fail to unlock a BinkBuffer, DirectDraw will usually lock out your display and you'll have to reboot. 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, BinkBufferLock, BinkBufferUnlock, BinkCopyToBuffer
Related Basic Types: BINKBUFFER_OPEN_FLAGS, HBINKBUFFER, S32
Related Structures: BINKBUFFER


BinkBufferBlit

The function BinkBufferBlit copies the pixel data onto the screen (for the off-screen variety of BinkBuffers).

void BinkBufferBlit(
  HBINKBUFFER bink_buf,
  BINKRECT_ARRAY rects,
  U32 num_rects
);

In Parameters

bink_buf
Specifies the BinkBuffer handle.
rects
Specifies a pointer to an array of rectangular areas to copy.
num_rects
Specifies the number rectangles pointed to by the rects parameter.

Discussion

This function blits the pixel data onto the screen for the off-screen style BinkBuffers. For overlay BinkBuffers, this function blits the color key pixels into your window (this allows the overlay to appear on the screen). For primary surface BinkBuffers, this function simply returns without doing anything. You will almost always call this function with the FrameRects field from the Bink structure after calling BinkGetRects. BinkGetRects fills the FrameRects field with the dirty rectangles from the most recently decompressed Bink frame. So, the blitting logic would look 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 ) );

Note that you shouldn't call the BinkBufferBlit function while the buffer is locked - always call BinkBufferUnlock before calling BinkBufferBlit.

Group: BinkBuffer API
Related Functions: BinkBufferLock, BinkBufferOpen, BinkBufferUnlock, BinkGetRects
Related Basic Types: BINKBUFFER_OPEN_FLAGS, BINKRECT_ARRAY, HBINKBUFFER, U32, void


BinkBufferCheckWinPos

The function BinkBufferCheckWinPos adjusts the specified window position coordinates for validity with the current BinkBuffer type.

void BinkBufferCheckWinPos(
  HBINKBUFFER bink_buf,
  S32 *new_window_x,
  S32 *new_window_y
);

In Parameters

bink_buf
Specifies the BinkBuffer handle.

Out Parameters

new_window_x
Specifies the X (left) coordinate that you want to check.
new_window_y
Specifies the Y (top) coordinate that you want to check.

Discussion

This function will adjust the supplied window position coordinates for validity with the current BinkBuffer blitting style. Because different blitting styles have different constraints (the primary surface blitting style can't be positioned partially off-screen, some overlay hardware doesn't allow partially off-screen surfaces, etc), this function will let the playback window be dragged safely. Normally under Win32, you should call this function in your WM_WINDOWPOSCHANGING message handler to prevent the window from ever moving to an invalid location. The NewWindowX and NewWindowY coordinates are global screen coordinates, so your default processing logic for WM_WINDOWPOSCHANGING should look something like this:

case WM_WINDOWPOSCHANGING:  if ( ( ( ( WINDOWPOS* ) lparam )->flags & SWP_NOMOVE ) == 0 )  {    if ( bink_buf )    {      S32 x,y;
      x = ( ( WINDOWPOS* ) lparam )->x;      y = ( ( WINDOWPOS* ) lparam )->y;      BinkBufferCheckWinPos( bink_buf, &x, &y );      ( ( WINDOWPOS* )lparam )->x = x;      ( ( WINDOWPOS* )lparam )->y = y;    }  }  break;

Group: BinkBuffer API
Related Functions: BinkBufferSetOffset
Related Basic Types: HBINKBUFFER, S32, void


BinkBufferSetOffset

The function BinkBufferSetOffset tells the BinkBuffer that either the window position on the desktop or that the playback offset within the window has changed.

S32 BinkBufferSetOffset(
  HBINKBUFFER bink_buf,
  S32 dest_x,
  S32 dest_y
);

In Parameters

bink_buf
Specifies the BinkBuffer handle.
dest_x
Specifies the X (left) coordinate (relative to the upper-left of the window) that you want to blit to.
dest_y
Specifies the Y (top) coordinate (relative to the upper-left of the window) that you want to blit to.

Returns

Returns whether the BinkBuffer was successfully repositioned (non-zero) or whether the specified coordinates were invalid (zero).

Discussion

This function tells the BinkBuffer that either the playback window position itself or the playback offset within the window has been changed. Normally under Win32, you will want to call this function from the WM_WINDOWPOSCHANGED message in your window procedure. The dest_x and dest_y are offsets in client coordinates, so if you want the video to play in the upper left of your window, you should use zero for both offsets. So, the default code for your WM_WINDOWPOSCHANGED message would be:

case WM_WINDOWPOSCHANGED:  if ( bink_buf )    BinkBufferSetOffset( bink_buf, 0, 0 );  break;

DirectDraw overlays won't move if you drag the video playback window to a new position and you fail to call this function. This function will return a non-zero if the BinkBuffer was repositioned, or zero if the BinkBuffer couldn't be positioned to the given coordinates.

Group: BinkBuffer API
Related Functions: BinkBufferCheckWinPos
Related Basic Types: HBINKBUFFER, S32


BinkBufferSetScale

The function BinkBufferSetScale sets a new shrinking or stretching scale to use during blitting.

S32 BinkBufferSetScale(
  HBINKBUFFER bink_buf,
  U32 width,
  U32 height
);

In Parameters

bink_buf
Specifies the BinkBuffer handle.
width
Specifies the width that you would like the blitting stretched or shrunk to.
height
Specifies the height that you would like the blitting stretched or shrunk to.

Returns

Returns whether the BinkBuffer was successfully able to use this scale (non-zero) or whether the specified scale was invalid (zero).

Discussion

This function sets a new shrink/stretch scale to use. Not all of the blitting styles can do shrinking or stretching, so be sure to specify one of the BINKBUFFERSTRETCHX, BINKBUFFERSTRETCHY, BINKBUFFERSHRINKX, or BINKBUFFERSHRINKY constants when you open the BinkBuffer, or your scale factor may be ignored. Stretching and shrinking is almost always faster (even in hardware) when using an integral factor (2x, for example). The WindowWidth and WindowHeight fields in the BinkBuffer structure will be updated to new sizes if this function is successful. This function returns non-zero if the BinkBuffer is able to perform the scale, or zero if the BinkBuffer is unable to scale.

Group: BinkBuffer API
Related Sections: Scaling
Related Functions: BinkBufferOpen
Related Basic Types: BINKBUFFER_OPEN_FLAGS, HBINKBUFFER, S32, U32


BinkBufferSetResolution

The function BinkBufferSetResolution tells Bink to switch video resolution when opening the BinkBuffer.

void BinkBufferSetResolution(
  U32 width,
  U32 height,
  U32 color_depth
);

In Parameters

width
Specifies the screen width that you wish to switch into (in pixels).
height
Specifies the screen height that you wish to switch into (in pixels).
color_depth
Specifies the screen color depth that you wish to switch into (in bits: 8, 16, 24, or 32). You can also use several color depth macros: 1=at least high-color (tries 16-bit, then 32-bit, and then 24-bit), 2=attempt true-color (tries 32-bit, then 24-bit, and then 16-bit), or 3=true-color only (tries 32-bit, then 24-bit).

Discussion

This function tells Bink what resolution to use when playing the Bink file. This function won't actually switch the resolution - it just requests that it be used when the BinkBuffer is opened. To use this function, you first call this function, and then you call call BinkOpen using the BINKBUFFERRESOLUTION flag. Note that if you have already switched the resolution using DirectDraw, then you don't have to do it again with the BinkBuffer API. If you used the BINKBUFFERDIBSECTION flag to open this BinkBuffer, then Bink will use ChangeDisplaySettings to switch the video mode.

Group: BinkBuffer API
Related Functions: BinkBufferOpen, BinkOpen
Related Basic Types: BINKBUFFER_OPEN_FLAGS, U32, void


BinkBufferGetDescription

The function BinkBufferGetDescription returns a string describing the blitting style being used by the BinkBuffer.

BINK_STRING BinkBufferGetDescription(
  HBINKBUFFER bink_buf
);

In Parameters

bink_buf
Specifies the BinkBuffer handle.

Returns

Returns a description string.

Discussion

This function will return a string constant that describes the blitting style used by the specified BinkBuffer. It is useful to display what type of technology the BinkBuffer is using (especially if it was opened with the BINKBUFFERAUTO blitting style).

Group: BinkBuffer API
Related Basic Types: BINKBUFFER_OPEN_FLAGS, BINK_STRING, HBINKBUFFER


BinkBufferGetError

The function BinkBufferGetError returns a string that describes the last global BinkBuffer error.

BINK_STRING BinkBufferGetError();

Returns

Returns the last global BinkBuffer error.

Discussion

This function returns a string describing the last global BinkBuffer error. It is especially handy if BinkBufferOpen fails.

Group: BinkBuffer API
Related Functions: BinkBufferOpen
Related Basic Types: BINK_STRING


BinkDDSurfaceType

The function BinkDDSurfaceType returns a value describing the format of the specified DirectDraw surface.

BINK_COPY_FLAGS BinkDDSurfaceType(
  LPDIRECTDRAWSURFACE lpDirectDrawSurface
);

In Parameters

lpDirectDrawSurface
Specifies the surface that you want to query.

Returns

Returns a value describing the format of the surface.

Discussion

This function returns a value describing the supplied DirectDraw surface. You can use this function to obtain the surface type to pass to the BinkCopyToBuffer function. If the surface type is unknown or unsupported, then this function returns -1. For DirectX 8 surfaces, use the BinkDX8SurfaceType function - not BinkDDSurfaceType! On MacOS, use the BinkGDSurfaceType function.

Group: BinkBuffer API
Related Functions: BinkCopyToBuffer, BinkCopyToBufferRect, BinkDX8SurfaceType, BinkGDSurfaceType
Related Basic Types: BINK_COPY_FLAGS, LPDIRECTDRAWSURFACE


BinkDX8SurfaceType

The function BinkDX8SurfaceType returns a value describing the format of the specified DirectX 8 surface.

BINK_COPY_FLAGS BinkDX8SurfaceType(
  LPDIRECT3DSURFACE8 lpDirect3DSurface
);

In Parameters

lpDirect3DSurface
Specifies the surface that you want to query.

Returns

Returns a value describing the format of the surface.

Discussion

This function returns a value describing the supplied DirectX 8 surface. You can use this function to obtain the surface type to pass to the BinkCopyToBuffer function. If the surface type is unknown or unsupported, then this function returns -1. For earlier versions of DirectX, use the BinkDDSurfaceType function. On MacOS, use the BinkGDSurfaceType function.

Group: BinkBuffer API
Related Functions: BinkCopyToBuffer, BinkDDSurfaceType, BinkGDSurfaceType
Related Basic Types: BINK_COPY_FLAGS, LPDIRECT3DSURFACE8


BinkGDSurfaceType

The function BinkGDSurfaceType returns a value describing the format of the specified MacOS Graphics Device.

BINK_COPY_FLAGS BinkGDSurfaceType(
  GDHandle gdevice
);

In Parameters

gdevice
Specifies the graphics device that you want to query.

Returns

Returns a value describing the format of the surface.

Discussion

This function returns a value describing the supplied Graphics Device. You can use this function to obtain the surface type to pass to the BinkCopyToBuffer function. If the surface type is unknown or unsupported, then this function returns -1. On Win32, use the BinkDDSurfaceType or BinkDX8SurfaceType functions.

Group: BinkBuffer API
Related Functions: BinkCopyToBuffer, BinkCopyToBufferRect, BinkDDSurfaceType, BinkDX8SurfaceType
Related Basic Types: BINK_COPY_FLAGS, GDHandle


BinkIsSoftwareCursor

The function BinkIsSoftwareCursor determines whether the specified mouse cursor is software-based on the specified DirectDraw surface pointer.

S32 BinkIsSoftwareCursor(
  LPDIRECTDRAWSURFACE lpDirectDrawSurface,
  HCURSOR cursor
);

In Parameters

lpDirectDrawSurface
Specifies the surface that you want to check.
cursor
Specifies the cursor to test.

Returns

Returns non-zero if the cursor is software-based, zero if the cursor is hardware-based.

Discussion

This function will figure out if the specified mouse cursor is software-based on the given primary surface pointer. If the cursor is software-based, then you must hide the cursor before drawing on the primary surface (or you get mouse trails on the screen). If the cursor is hardware-based, then you don't need to hide it (hiding and showing the mouse will cause the pointer to flash annoyingly - we should avoid it if we can). This is a pretty slow function (you wouldn't believe how complicated the source code is), so try to call it only once at startup time. For example, to manage the cursor when drawing directly to the primary surface under Win32, do something like this:

HCURSOR Cursor = LoadCursor( 0, IDC_ARROW );S32 Soft_cursor = BinkIsSoftwareCursor( lpDDprim, Cursor );
void Blit_frame( HWND wnd, S32 x, S32 y, S32 w, S32 h ){  S32 count;  DDSURFACEDESC DDSdesc;
  if ( Soft_cursor )    count = BinkCheckCursor( wnd, x, y, w, h );
  lpDDprim->Lock( NULL, &DDSdesc, DDLOCK_WAIT, 0 );
  // do whatever to the primary surface here
  lpDDprim->Unlock( DDSdesc.lpSurface );
  if ( Soft_cursor )    BinkRestoreCursor( count );}

Note that under Win32 if you don't know the HCURSOR, but you do know the HWND, you can use the GetClassLong Windows function with the GCL_HCURSOR flag to find the correct HCURSOR value. This function is automatically called inside the high-level BinkBuffer API.

Group: BinkBuffer API
Related Sections: Mouse Cursors
Related Functions: BinkCheckCursor, BinkRestoreCursor
Related Basic Types: HCURSOR, LPDIRECTDRAWSURFACE, S32


BinkCheckCursor

The function BinkCheckCursor checks to see if the mouse is currently inside the specified window rectangle, and, if so, hides it.

S32 BinkCheckCursor(
  OS_WND window,
  S32 check_x,
  S32 check_y,
  U32 width,
  U32 height
);

In Parameters

window
Specifies the window handle (under Win32) or window pointer (under MacOS) that the check_x and check_y parameters are relative to. You can pass in NULL for this parameter.
check_x
Specifies the X (left) coordinate of the test rectangle.
check_y
Specifies the X (left) coordinate of the test rectangle.
width
Specifies the width of the test rectangle.
height
Specifies the height of the test rectangle.

Returns

Returns the total number of times cursor had to be hidden (which is passed to BinkRestoreCursor).

Discussion

This function will determine if the mouse is currently in the specified window rectangle, and, if it is, hide it. This will let you move the mouse without leaving mouse trails behind with software-drawn mouse cursors. You have to call this function before you lock the primary surface, or the cursor won't be hidden. Check out the BinkIsSoftwareCursor function for an example of how to use this function. This function returns a count value that you need to pass to the BinkRestoreCursor function to restore the mouse cursor to its original state.

Group: BinkBuffer API
Related Sections: Mouse Cursors
Related Functions: BinkIsSoftwareCursor, BinkRestoreCursor
Related Basic Types: OS_WND, S32, U32


BinkRestoreCursor

The function BinkRestoreCursor restores the mouse cursor to its original state after a BinkCheckCursor call.

void BinkRestoreCursor(
  S32 check_count
);

In Parameters

check_count
The count value returned from a call to BinkCheckCursor.

Discussion

This function will restore the mouse cursor to its original state after a BinkCheckCursor call. You have to call this function after you unlock the primary surface, or the cursor won't be restored. Check out the BinkIsSoftwareCursor function for an example of how to use this function.

Group: BinkBuffer API
Related Sections: Mouse Cursors
Related Functions: BinkCheckCursor, BinkIsSoftwareCursor
Related Basic Types: S32, void


Background Concepts

Discussion

Background concepts are short bits of text discussing general topics either directly or indirectly relating to Bink.

Background Concepts
Open and Close
Locking and Unlocking
Alpha Planes
OpenGL
Direct3D
Scaling
Mouse Cursors


Open and Close

Discussion

In Bink, Open functions are functions that allocate resources. Close functions are functions that release these resources. An example of this relationship would be BinkOpen and BinkClose. The Open functions return handles that you use with other related API functions. For example, you can't call BinkDoFrame without the handle returned from BinkOpen. You must make sure that you call the Close function on any handle that is returned from an Open function or you may leak resources.

Group: Background Concepts
Related Functions: BinkBufferClose, BinkBufferOpen, BinkClose, BinkDoFrame, BinkMacOpen, BinkOpen


Locking and Unlocking

Discussion

You must lock and unlock a BinkBuffer before you can access the buffer and buffer_pitch fields inside a BinkBuffer structure. This is to allow the BinkBuffer to lock and unlock the underlying DirectDraw structures. Note that because DirectDraw may be locked inside of a BinkBufferLock/BinkBufferUnlock block, you can't step into a BinkBuffer block in the debugger. If you need this functionality, open the BinkBuffer using the BINKBUFFERDIBSECTION flag (which doesn't require a DirectDraw lock).

Group: Background Concepts
Related Functions: BinkBufferLock, BinkBufferOpen, BinkBufferUnlock
Related Basic Types: BINKBUFFER_OPEN_FLAGS


Alpha Planes

Discussion

Alpha planes are bitplanes that describe what is and what isn't transparent or translucent on a video frame. They are much more useful than simple color keying because you control the transparency right to the pixel - no more weird problems when the color key blends into the edges of the non-transparent pixels! You create alpha planes with a video editing package like Adode Premiere, or by telling your 3D package to generate alpha planes as it renders the video frames. Playing back alpha planes is a little tricky because applying alpha transparency is fairly expensive CPU-wise. To keep performance up, we recommend using your 3D video card to merge bitmap using alpha planes. Harnessing your 3D video card means that you must use OpenGL, Direct3D, or your console's 3D library to talk to your video card. On Win32, Bink includes an example that can play alpha transparent video for both OpenGL and Direct3D ("ExamAlph.C"). To use OpenGL, or Direct3D, you just link to the appropiate 3D interface file ("GLRAD3D.C", "DX8RAD3D.CPP', or "DX7RAD3D.CPP'). On Xbox, Bink include an example that uses Direct3D to play alpha translucent video (ExamXAlf.CPP). You'll also need the Xbox 3D interface file, XbxRAD3D.CPP. On Nintendo GameCube, Bink include an example that uses the OS to play alpha translucent video (ExamNAlf.CPP). You'll also need the GameCube 3D interface file, NGCRAD3D.CPP.

Group: Background Concepts
Related Sections: Bink Examples for Win32, Bink Examples for the Nintendo GameCube, Bink Examples for the Xbox, Bink Playback on the Nintendo GameCube, Bink Playback on the Xbox, Bink Playback under MacOS, Bink Playback under Win32, Direct3D, OpenGL
Related Basic Types: BINK_COPY_FLAGS, BINK_OPEN_FLAGS


OpenGL

Discussion

OpenGL is an industry standard 3D graphics API. It is used to drive your 3D graphics card. You can use OpenGL to do fast alpha-plane controlled transparent video playback (see "ExamAlph.C" and "GLRAD3D.C" for an example). You can read more about OpenGL at the GLSetup website.

Group: Background Concepts
Related Sections: Alpha Planes, Bink Examples for Win32, Bink Examples for the Xbox, Direct3D


Direct3D

Discussion

Direct3D is a Microsoft supplied 3D graphics API. It is used to drive your 3D graphics card. You can use Direct3D to do fast alpha-plane controlled transparent video playback (see "ExamAlph.C" and "DX8RAD3D.CPP" for a DirectX 8 example). You always use Direct3D to display your video frames on the Xbox - there is no 2D blitting API available yet. The Xbox supports linear, non-power-of-2 textures, though, so this won't hurt your video playback at all. You can read more about Direct3D at the Microsoft DirectX website.

Group: Background Concepts
Related Sections: Alpha Planes, Bink Examples for Win32, Bink Examples for the Xbox, OpenGL


Scaling

Discussion

Scaling is the act of shrinking or stretching the pixels during a blitting operation to a different output rectangle size. Scaling is usually much slower than a normal one-to-one blit which can be incredibly optimized (like the Bink software 1x blitters). It is possible to write optimized blitters for other scaling styles, but this is usually impractical and seldom necessary. Bink includes optimized blitters for 1x blitting, 2x width blitting, 2x height blitting, and 2x width and height blitting. Any other scaling type will be handled by performing a 1x copy into an off-screen buffer, and then stretching the 1x off-screen buffer onto the screen. Hardware usually optimizes integral scaling (2x width, or half-size width, or 4x width, etc), so you should try to only scale integrally when possible. If you must stretch non-integrally, the YUV hardware may or may not support it, so you may fall back to software. And even if you are lucky enough to have a video card that accelerates non-integral scaling, this is usually really slow - usually too slow, in fact, for video playback. So, your best option is generally to switch the video mode into a mode where you can use integral scaling and still fill most of the screen. Then you get a nice full or almost-full screen display, and you'll still keep the frame rate nice and brisk.

Group: Background Concepts
Related Sections: Colorspace - RGB vs. YUV
Related Functions: BinkBufferOpen, BinkBufferSetScale, BinkCopyToBuffer, BinkCopyToBufferRect
Related Basic Types: BINKBUFFER_OPEN_FLAGS, BINK_COPY_FLAGS, BINK_OPEN_FLAGS


Mouse Cursors

Discussion

The mouse cursor is that thing that moves around when you move your mouse. You know - the thing that stops moving when Windows crashes. There are two different kinds of mouse cursors - hardware and software. Hardware cursors float above the pixels on the screen not disturbing anything. Some video cards can only do hardware cursors if they are black and white, some video cards can only do non-animated cursors, some video cards can do any type of cursor. Some video cards can't do hardware cursors of any type! When the hardware isn't capable of creating a particular type of cursor, then Windows or MacOS steps in and creates a software cursor. Software cursors are actually drawn by the system - you move the mouse, and the system erases the old mouse bitmap and draws a new one a few pixels over. Normally, you never even need to know this, and everything just works perfectly. However, with DirectDraw or MacOS, you can actually write onto the video memory without Windows knowing about it. So, say you move the mouse on a software cursor system after you've wrote to video memory - Windows or MacOS will erase the old mouse bitmap by drawing the wrong pixels in the old mouse location! These little remnants of garbage are known as mouse trails. To fix mouse trails, you can simply hide the mouse before locking the DirectDraw or MacOS pixmap surface, and then restore it after unlocking the surface. This, however, causes a slight flickering during video playback, so it is best to detect software-cursors and only hide the cursor if a mouse trail might result. Bink supplies the BinkIsSoftwareCursor, BinkCheckCursor, and BinkRestoreCursor functions to deal with this problem. These functions are useful whenever you use DirectDraw or MacOS - they are useful even if you don't use Bink.

Group: Background Concepts
Related Functions: BinkCheckCursor, BinkIsSoftwareCursor, BinkRestoreCursor


Change Log

Bink SDK 1.5v

Discussion

This change log includes the entire Bink development history.

Changes from version 1.5u to 1.5v (04-12-2003)

  • Fixed a bug where the Bink player for Mac couldn't highlight pre-compiled EXE video files.
  • Fixed a bug on the Mac in the BINKSURFACE32R and BINKSURFACE32RA YUV to RGB pixel converters where a non-divisible by 4 right edge would draw with the wrong colors.
  • Fixed a bug in the Mac Classic versions of the library and player where RemoveTimeTask couldn't be found on pre-9.0 MacOS.
  • Added Mach-O format Carbon dynamic libraries for building Project Builder or CodeWarrior Mach-O applications without thunking.
  • Brought Bink Mac up to the latest PC source base (now uses Perforce and command line building just like the PC, so it will always stay in sync).

Changes from version 1.5t to 1.5u (03-16-2003)

  • Bink playback is now much smoother on medium to low-end machines running Win 9x, due to working around a multi-threaded bug in the system function, timeGetTime, that was eating up to 30% of the CPU!
  • Now properly handle the window being minimized when using DirectDraw primary surface blitting in the Bink player.
  • Fixed an edge bug when using BinkCopyToBufferRect with a non-visible-by-4 width or height and a non-zero left or top offset.

Changes from version 1.5s to 1.5t (02-06-2003)

  • Fixed the Smack and SmackMix tools when using old format Bink audio tracks.
  • We more support more dialects of TGA import files. This means we resort to QuickTime less often (which is good because QuickTime is slooow).
  • Fixed an debug assert in the Xbox SDK when setting very quiet (or silent) mix bin volume levels.
  • Fixed a crash when using waveOut audio output and the "play as fast as possible" frame rate option.

Changes from version 1.5r to 1.5s (01-14-2003)

  • Allowed the Smack and SmackMix tools to create old format Bink audio tracks.
  • Increased the Bink I/O block size from 8K to 16K (since Bink videos are slowly using higher data rates).
  • Fixed a setting in the Bink SDK help where the navigation tab would disappear when the focus was lost. One stupid downside is that WinHelp remembers what the setting used to be, so if you have no nagivation tab at all, then choose "Options... Show Tabs" on the menu bar.

Changes from version 1.5q to 1.5r (01-01-2003)

  • Fixed the accidental exclusion of the RADSetMemory function header file from the Bink SDKs.
  • Made the Bink Player only ask to check for updates if it is in the same directory as the RAD Video Tools. This means that the free Bink Player can be distributed without popping up update requests.
  • We now poll the DirectSound buffer positions much less frequently to handle sound drivers that report these positions slowly.
  • We added a non-LTCG version of Bink for Xbox, so that "Edit and Continue" can be used again.

Changes from version 1.5p to 1.5q (11-18-2002)

  • Fixed a problem where our JPEG reader was detecting motion-JPEG QuickTime movies as a single frame JPEG. This had the effect of making motion-JPEG movies only appear to be one frame, so only the first frame of the movie was ever converted. We now force the use of QuickTime when the JPEG file is over 1.5 MB in size, or when the extension is .QT or .MOV.
  • Fixed a bug when using the old Bink audio codec where stereo sound files would get converted to mono during compression. Note that there was no problem if you were using the new Bink audio codec (which you should be anyway).
  • Fixed a bug when compiling a Smacker for DOS or Win16 video executable.
  • Did the big switch over to Perforce source code control.

Changes from version 1.5m to 1.5p (10-18-2002)

  • Added MusyX audio output support for the GameCube SDK. This caused a few API changes on the GameCube (even for non-MusyX games) because we no longer automatically assume you are using AX. So, you must now call BinkSoundUseAX or BinkSoundUseMusyX before the first call to BinkOpen, or you won't get any sound. Also, RADSetAudioMemory has been removed (because only AX used it) - instead, you now pass in the ARAM callbacks to the BinkSoundUseAX function.
  • Updated all of the GameCude examples to let them be built AX or MusyX.

Changes from version 1.5L to 1.5m (10-04-2002)

  • Made the lower Bink audio compression levels less lossy (the levels less than 4).
  • Changed the GameCube I/O code to check the global DVD status (vs. the file status) so that errors are still reported even if other async I/O intervenes.
  • Worked around buggy Windows XP sound drivers that report bogus playback positions (which was causing occasional skips).
  • Switched to using QuickTime to load PNGs when compressing alpha planes.

Changes from version 1.5k to 1.5L (09-25-2002)

  • Fixed a problem on the GameCube where stereo audio playback was overly noisy.
  • Fixed a few subtle timing issues to allow seamless audio looping.

Changes from version 1.5J to 1.5k (09-09-2002)

  • Added batch functionality to the RAD Video Tools! Now you can highlight a group of input files and process them all one by one.
  • The RAD Video Tools now has built-in support for TGA and TIFF alpha planes (previously QuickTime was used for alpha input). Our built-in support is almost 20 times faster than QuickTime, so compressing large numbers of still images is now much, much faster!
  • Fixed a bug in the DirectSound support where changing the volume could be ignored.
  • Bumped up the default compression data rate to 400 kps.
  • Added a warning when you ask to compress an alpha plane and the input file has no alpha plane.
  • Switched to .NET for building the tools (a little faster compiled code, but the debugger is frustrating).
  • Changed the sound support so that we only reset the sound system every 2 minutes of video (less popping at loop points). We also do the reset on the first frame (previously we did it on the last frame which occasionally popped).
  • Moved the end of file logic in the Xbox and GameCube example source to fix a problem where playback could stop one frame early.
  • Show 2 decimal places when displaying frame rates in the RAD Video Tools.
  • We now free the 2x height doubled YUV scanline buffers in BinkClose (vs. shutdown in previous versions). This only saves about 1500 bytes, but it helps with fragmentation.
  • Changed the GameCube SDK to account for the slightly faster rate that the NGC DSP really runs at. Fixes sync problems with longer movies on the GameCube.
  • Changed the Xbox and PC SDK to allocate the sound sample buffer on the stack - saves 16K of global memory.
  • Now build the Xbox library using VC7's link time code generation. This will generate both faster and smaller code. The file size of the library is large because the linker does the compilation - the link size in bytes will be 10K to 50K smaller.

Changes from version 1.5i to 1.5J (06-24-2002)

  • Updated the sound code for the Miles Sound System to work with Miles 6.5.
  • Updated the sound code for DirectSound to be loudness based (vs. amplitude based).
  • Updated the Nintendo GameCube examples to work with Patch 3.

Changes from version 1.5h to 1.5i (06-15-2002)

  • Fixed a no-volume problem when using the latest GameCube audio libraries.

Changes from version 1.5g to 1.5h (06-12-2002)

  • Made BinkOpen use async reads on the GameCube to avoid lock ups when opening the door at the wrong time.
  • Re-enabled the BinkDX8SurfaceType function on the Xbox.

Changes from version 1.5f to 1.5g (05-15-2002)

  • Fixed the GameCube not playing some soundtracks.
  • Fixed two ugly bugs on the GameCube when closing a Bink file.
  • Fixed an periodic clicking on the GameCube with some audio sample rates.
  • Fixed the little glitch of audio when playing 8-bit data on the GameCube.

Changes from version 1.5e to 1.5f (05-08-2002)

  • Fixed a crash when compressing some audio files.

Changes from version 1.5d to 1.5e (04-29-2002)

  • Fixed a bug when compressing or mixing using the old Bink audio compressor.
  • Fixed a debug message that displayed while compressing.

Changes from version 1.5c to 1.5d (04-27-2002)

  • Fixed a few linker errors on GameCube when using CodeWarrior.

Changes from version 1.5b to 1.5c (04-17-2002)

  • Worked around a compiler bug that could cause the Bink compressor to crash on some input files.

Changes from version 1.5a to 1.5b (04-03-2002)

  • Added the BinkCopyToBufferRect function to the Bink SDK. This function allows you to partially copy a Bink frame to another buffer. You can draw with tiled Direct3D textures much faster with this function.
  • Updated the DX8 and DX7 example programs to use the BinkCopyToBufferRect function.
  • Changed the RAD 3D wrapper API slightly on PC to handle direct locking of tiled textures. You now need to call Lock_RAD_3D_image in a loop to obtain each buffer pointer to copy into. See ExamAlph.c for the updated example.
  • Released a new Carbon version of the Mac player (compatible with MacOS X and 9)!
  • Fixed a false positive condition when writing out an AVI that could cause the 'Windows has crashed' message to appear when everything was fine.
  • Updated the Mac version to the latest codebase.
  • Fixed an offset bug on the Mac in BinkBufferLock when running on certain multi-monitor configurations.
  • Switched to an all new internal task sharing model on the Mac - replaces all the cooperative thread stuff with timers and critical sections. Much better IO and sound performance (fixes the MacOS X multi-CPU sound skips).
  • On MacOS X, switched to using normal IO on a background thread instead of async IO.
  • Fixed a few bugs on the GameCube when playing videos with no sound.
  • Fixed the mixer to accept lossy levels greater than 100 (to specify the old Bink encoder format).
  • Fixed the delay when using BinkGoto on a video without sound.

Changes from version 1.2J to 1.5a (03-15-2002)

  • Added an all new Bink audio encoder! Sounds much better and can compress up to half the old data rate!
  • Added crash protection around all calls to Windows or QuickTime - we should now withstand crashes in buggy 3rd party codecs. The specific frame that was being decompressed will be blank, but the rest of the movie should survive.
  • Added several new Xbox SDK examples showing overlay and back buffer support. Overlays are really cool - they are definitely the best way to play most videos on the Xbox.
  • Added YUY2 blitting support to the Xbox SDK - this allows the Xbox hardware to do the YUV to RGB conversion (which is usually much faster). Most of the examples now use YUY2 as the default texture format.
  • Added support for 3D Studio Max's RLA file format. This format supports RGB, alpha, Z-depth info, UV-coordinates, and normals - all per pixel! This lets you do some amazing post-process stuff with video that you'd swear couldn't be pre-rendered. We'll put up some demos of this soon!
  • Added lots of new configuration detection to the System Info button in the RAD Video Tools (Duron, P4, Celeron, Itanium, Me, 2000, XP, video card, audio card, memory, and disk space).
  • Detect larger than 2 GB AVI files and warn the user that they are not supported by the Windows reader.

Changes from version 1.2i to 1.2J (02-18-2002)

  • Released the all new Nintendo GameCube support! The platforms keep coming!
  • Fixed a stupid memory leak in BinkOpen - everyone using 1.2i should upgrade.
  • Rewrote BinkGoto completely - you can now jump directly to a frame and the sound will begin immediately (vs. the old 750 millisecond silence delay).
  • Added new Direct3D 8 example texture support code. Includes support for dynamic and non-power of 2 textures (both of which can improve playback dramatically).

Changes from version 1.2h to 1.2i (01-18-2002)

  • Detected when DirectDraw can't lock the primary surface and switch to DIBSections. This fixes the problem with blank video windows on XP or when NetMeeting was running.
  • Fixed a rare deadlock problem when a movie would loop (or when you called BinkSetSoundOnOff).
  • Fixed a data overrun that could cause pauses when playing a movie that had no sound.
  • Made BinkGoto start the audio from the "gone-to" frame instead of whatever filled up the sound buffer first.
  • Fixed BinkGoto to not unpause the movie if it was previously paused.
  • Removed Windows.h from the Bink header file (for faster compilation).

Changes from version 1.2g to 1.2h (11-07-2001)

  • Made the default mix bins on the Xbox to be all speakers (instead of the normal Xbox default of just the front-left and front-right speakers).

Changes from version 1.2f to 1.2g (11-06-2001)

  • Switched to the November Xbox SDK which required slightly changing the BinkSetMixBins and BinkSetMixBinVolumes functions.

Changes from version 1.2e to 1.2f (10-26-2001)

  • Fixed a silly regression bug where videos without audio would play with the wrong frame rate.

Changes from version 1.2d to 1.2e (10-19-2001)

  • Bink can now play multiple sound tracks at once. This means that the BinkSetSoundTrack function now takes an array of track IDs to play instead of a single value. Also, the BINKNOSOUND constant has been removed - to play without any sound, pass a zero for the track count in BinkSetSoundTrack.
  • Added example code in ExamXbox.cpp that shows how to play 5.1 audio on an Xbox.
  • Added the BinkSetMixBinVolumes function to adjust the mix bin volumes individually on the Xbox.
  • BinkSetVolume, BinkSetPan, BinkSetMixBins functions all now take a track ID to control which sound track is changed.
  • Worked around a DirectSound bug on the Xbox where the audio tracks sometimes wouldn't start. If we notice the sound positions aren't updating, we restart the audio track.

Changes from version 1.2c to 1.2d (10-02-2001)

  • Fixed a bug in the Miles sound module where sound wouldn't restart after a skip.

Changes from version 1.2b to 1.2c (09-30-2001)

  • Worked around a nasty bug in the Xbox system software where the machine can occasionally get in a state where QueryPerformanceCounter actually runs backwards.
  • Fixed a bug where Bink wouldn't play the audio track of very short videos (the entire video had to be less than 250 milliseconds long).

Changes from version 1.2a to 1.2b (09-24-2001)

  • Put all of Bink in separate sections, so that it can be loaded and unloaded on an Xbox. Use the new BinkUnload and BinkUnloadConverters to manage Bink's sections.
  • Set the headroom on the Bink DirectSound buffer to zero (the default is too quiet on the Xbox).
  • Added a new BinkSetMixBins function to allow the management of Xbox mix bin destination buffers.

Changes from version 1.1d to 1.2a (08-28-2001)

  • Huge quality improvements on videos with color gradiants, washes, or fades as a result of cleaning up noise contamination all the way through the Bink pixel pipeline. In some cases, equivalent quality can be obtained at 1/4 the bandwidth! If you need highest possible quality, we recommend recompressing all your Bink videos. The only downside is that video compression time is longer when using super-high data rates (which you may not need any more). These improvements aren't hype - the quality difference is amazing in most cases!
  • Added a new denoising video filter (which is now rarely necessary with the new quality improvements).
  • Fixed a front-end problem in the video converter where half-toning was being applied if you selected "half-tone always" in the 256-color section.

Changes from version 1.1c to 1.1d (08-21-2001)

  • Worked around an Xbox DirectSound bug that caused movies to skip or slip out of synch at the start of a movie.
  • Fixed a bug that caused Bink's DirectSound code to take lock the DirectSound buffer too frequently.
  • Bink for Xbox now allocates it's sound buffer from the RAD memory allocation functions.
  • Bink's threads now use 12K of stack space instead of the executable default. This can save a fair amount of memory on the Xbox.
  • Added a workaround in the Bink timer code for buggy motherboards that advance the QueryPerformanceCounter incorrectly under heavy loads.

Changes from version 1.1b to 1.1c (07-12-2001)

  • Added new QuickTime importing code to support the video track of MPEG and Flash movies. QuickTime doesn't support audio exporting from either of these file types yet, unfortunately.
  • Added new QuickTime importing code to support AVIs that Windows can't open (like DV formatted AVIs).
  • Switched to the July version of the Xbox SDK.

Changes from version 1.1a to 1.1b (06-18-2001)

  • Fixed bug when opening a Bink file with multi-threaded I/O turned off. This caused several of the tools to lock up when processing Bink files as input files.

Changes from version 1.0x to 1.1a (06-14-2001)

  • Added new audio encoder that provides much higher quality sound on deep tones (may still have to use 0 lossy level on some files, though).
  • Rewritten DirectSound layer - much more tolerant of CPU starvation. Also worked around buggy SBLive drivers that would cause periodic skipping under Windows 2000.
  • All new threading model - instead of one thread per open Bink, there are simply two global threads for all open Bink files. Also fixed a few very rare thread deadlocks on multi-CPU machines (typically exhibited after more than 12 hours of looped playback).
  • Built with new beta versions of the Xbox system software - fixes crash in BinkOpen on beta 1 and 2 Xbox hardware.
  • Fixed compression of unusual AVIs where the video stream format doesn't match the file format (usually seen in Debabilizer AVI files).
  • Fixed a bug compressing unusual QuickTime movies where the audio started at a non-zero offset.
  • Improved the Bink I/O system to give better playback when playing files that are very close to the data rate limit of the playback device.
  • Added a new BinkDX8SurfaceType function that returns the type of a DirectX 8 surface.

Changes from version 1.0w to 1.0x (02-15-2001)

  • First release of the Bink SDK for Xbox! Use Bink files on the Xbox!
  • Fixed a several precision issues in the front-end tools that caused a variety of odd problems when working with very long video files.
  • Updated the 3D example files to support scaling the video while blitting.
  • Fixed a thread deadlock when running under Windows 98 and another background application was pounding on the DirectSound device.
  • Fixed a bug on the Mac when using the BINKSURFACE32A surface type.

Changes from version 1.0v to 1.0w (11-26-2000)

  • All Bink example files have been rewritten - much cleaner and easier to understand.
  • The example programs for performing alpha on OpenGL or Direct3D have been merged into one file (ExamAlph.C). The example now uses a simple wrapper API to both OpenGL (GLRAD3D.C) and Direct3D (D3DRAD3D.CPP).
  • Added a Carbon version of the Bink library for MacOS X.
  • Made the Bink Mac player show double-clicked or dropped files from the Finder.
  • Fixed a few bugs in the video resizer - should look better when using small resize ratios (like resizing a 320x240 video to 352x256, for example).
  • Fixed a bug in the video smoother where small artifacts could appear.
  • Allow more video files to be added to a single compiled executable.
  • Fixed a bug where bi-linear filtering was forced on when compressing an alpha plane.
  • When adding three or more files to a list file, the files are sorted as they are placed into the list.
  • List files now store complete pathnames internally, so you can copy them to other locations and the list file will still work.

Changes from version 1.0u to 1.0v (10-03-2000)

  • Fixed a silly bug in the still image importer where the frame range was used incorrectly.

Changes from version 1.0t to 1.0u (09-28-2000)

  • Fixed a bug in Smacker's lossless mode where it wasn't lossless if the input file had a very high data rate.
  • Fixed a bug when using a list file containing a series of still images with local start and end frame offsets.
  • Fixed a display bug in file information window where large file sizes could be displayed as negative numbers.
  • Switched to the new RAD make tool - very cool.

Changes from version 1.0s to 1.0t (09-09-2000)

  • Added video resizing! You can now shrink or zooming during compression or conversion. We use bi-cubic interpolation for extremely high quality scaling.
  • Added a bunch of digital video filters for use during compression and conversion - contrast, smoothing, brightness, clamp to black, gamma correction, and video de-interlacing are all now available!
  • Fixed a subtle bug in the QuickTime importer where the first frame was sometimes duplicated.
  • Added new 256-color small and large icons for Bink and Smacker.
  • Added a workaround to a SBLive driver bug that was causing waveOut mode not to work under Win98.
  • Fixed some thread contention problems that were causing audio decompression to take a bit more CPU than necessary.
  • Fixed the non-client area not being redrawn in the players after a window resize under Win2K.
  • Changed a few variable names in RAD.H to avoid conflicts with AMD's 3DNow header file.
  • Fixed a bug where a list file containing files with different original frame rates would wrap around if an adjusted frame rate was used on the list file.

Changes from version 1.0r to 1.0s (08-08-2000)

  • Made the player periodically ask to check for updates (since many users just double-click in Explorer and never run the tools).
  • Fixed a stupid bug where Bink videos without sound would play as fast possible.

Changes from version 1.0q to 1.0r (08-03-2000)

  • Sped up the decompressor by 12% on Mac and 5% on PC.
  • Fixed a audio problem on the Mac where audio playback was noisy.
  • An error is now shown when the audio track of a locked QuickTime file is opened (rather than just converting silence).
  • When executing an internal video utility and the control key is held down, we now put the command onto the clipboard (this makes it easy to copy the command line into a batch file).
  • An hourglass is displayed when reading long series of image files.
  • Fixed a bug where the wrong window style was used in the Bink player.
  • Fixed a goofy bug where BinkSetSoundOnOff only allowed zero or one (vs. zero or non-zero).

Changes from version 1.0p to 1.0q (07-10-2000)

  • Fixed a subtle aliasing error when using the 'adjust to frame rate' option with non-integral multiples.
  • Fixed a bug where the alpha plane of an imported Bink file was ignored.
  • Fixed a bug where the alpha plane of a TGA file was ignored if you imported the file as one of a series of still images.
  • Switched to a new EXE compressor (UPX) under Win32 that gets better compression and that should be more widely compatible.

Changes from version 1.0n to 1.0p (06-26-2000)

  • Switched to the real FFT instead of the complex FFT which can double audio decompression performance on some CPUs!
  • Made the RAD Video Tools must better at detecting series of numbered files.

Changes from version 1.0m to 1.0n (06-12-2000)

  • Compiled EXE Bink and Smacker files can now be used by most of the tools - you can convert them into AVIs, recompress them, remix audio from them, click on advanced play to change the built-in playback settings, etc.
  • You can now use the Bink and Smacker sound mixers to remove an audio track - just use '-' for the sound filename to mix.
  • The Mac player can now play PC EXE compiled videos - just highlight EXE file and hit Play!
  • Video playback is now centered by default on the Mac.
  • The background screen is cleared to black by default on the Mac.
  • Added options to not clear the background screen and to hide the mouse during playback on the Mac.
  • The Smacker player can now hide the mouse cursor during playback.
  • Fixed crash when encountering a file IO error (such as the CD being ejected during playback) on both PC and Mac.
  • Fixed an offset bug when using negative X offsets in the RAD graphics file importer when outputting true-color files.
  • Added the new RADSetMemory function that allows you to replace Bink's or Smacker's memory allocation and freeing routines on both PC and Mac.

Changes from version 1.0k to 1.0m (06-02-2000)

  • Switched to a faster FFT routine (speeds up audio decompression).
  • Fixed BinkCopyToBuffer to return a 1, if the blit was skipped.
  • Exported the BinkSetIO function correctly.
  • Fixed a wrap around bug when converting long wave files with the Bink converter.

Changes from version 1.0j to 1.0k (05-22-2000)

  • Fixed some surface byte ordering issues on MacOS - BINKSURFACE32 is now the correct format for the MacOS desktop.
  • Fixed a millisecond overflow problem on MacOS.
  • Buffer more sound data on MacOS - should give smoother playback.
  • Use less aggressive frame skipping on both PC and Mac.
  • Fixed a bug in the Bink IO speed simulator.
  • Fixed a crash when importing a Smacker file with Bink audio.
  • Added waveOut support to Bink - it can now run completely without DirectX.

Changes from version 1.0i to 1.0j (04-30-2000)

  • First version of Bink for Mac! The full Bink SDK and player is now available for MacOS!
  • Fixed a bug when pausing a video before a single frame had been decompressed.

Changes from version 1.0h to 1.0i (04-05-2000)

  • Added three new display color depth options to the Bink player - "at least high-color" (tries 16-bit, then 32-bit, and then 24-bit), "try true-color" (tries 32-bit, then 24-bit, and then 16-bit), and "true-color only" (tries 32-bit, and then tries 24-bit).
  • Checks the actual bit depth set after a call to ChangeDisplaySettings to work around a bug in the NVidia drivers.
  • Bink player doesn't decompress sound that is going to be skipped when playing in "as fast as possible" mode.
  • Fixed a bug in the 5551 merged alpha blitters.
  • Added two Bink alpha plane playback examples - DXALPHA.CPP for Direct3D and GLALPHA.C for OpenGL.
  • First version of Smacker 4.0 for the Mac! PowerPC and 68K are both supported (you should avoid using Bink audio in Smacker files that will be played on 68K machines, though).
  • Fixed a bug in the Smacker encoder where files compressed with Bink audio tracks would be aligned incorrectly. This led to too slow Smacker files on the PC and unplayable files on the Mac. You have to recompress the Smacker file to fix the problem, though.
  • Renamed the SmackTimerRead function to RADTimerRead and switched to using QueryPerformanceCounter (from timeGetTime) on Win32 - should make movies play a little more smoothly on Windows NT and 2000.
  • Fixed a bug in the SmackGetRects function where an extra bogus rectangle would be returned on a frame where a palette change occurred, but no pixels changed.
  • In the Smacker player and SDK, broke out the time spent in the audio and video decoders into separate values.
  • Fixed a bug in the Smacker player that cause an extra millisecond of sleep for every frame.
  • Fixed a bug where the Bink encoder wouldn't read the alpha channel out of an input Bink file.
  • Fixed a crash in the Mac SmackBuffer API when a NULL rectangle was passing to SmackBufferBlit.
  • You can now override settings on the command line with a remove switch. For example, if you run "BinkPlay test /L", you can tell Bink to ignore the loop switch with "BinkPlay test /L /-L". The "slash-minus-L" tells Bink to skip the earlier L switch. This is mostly useful for overriding the switches that are compiled into a self-playing Bink or Smacker file.

Changes from version 1.0g to 1.0h (03-14-2000)

  • Under NT, sped up mixing time dramatically by flushing the file less often.
  • Fixed a problem where a user-specified DirectSound object could cause audio not to play.
  • Fixed a bug in the Smacker mixer where forcing a frame rate would cause the audio to be mixed incorrectly.

Changes from version 1.0f to 1.0g (03-08-2000)

  • Added multi-CPU support to the Bink compressor! Compression scales close to linearly with multiple CPUs - twice as fast for two CPUs, four times as fast for four CPUs, etc.
  • Added reversed order blitters (BINKSURFACE24R and BINKSURFACE32R). These are convenient under OpenGL where the reversed byte path is more optimized.
  • Added merging alpha blitters (BINKSURFACE32A, BINKSURFACE32RA, and BINKSURFACE4444). These are used with Bink files that are compressed with an alpha plane to get the merged formats commonly used by the 3D APIs.
  • Added the new online documentation system (with the system that Casey created for Granny).
  • Fixed a bug in the BinkBuffer API where the YUV formats were never tried if the DIBSection blitter failed.

Changes from version 1.0e to 1.0f (02-08-2000)

  • Made the Bink compressor up to 25% faster with better video quality.
  • Made the core Bink decompressor about 12% faster on all CPUs.
  • Made the decompressor another 5% faster if you recompress your Bink files.
  • When compressing with alpha, we now use QuickTime to load the files first (which lets us read the alpha planes out of most files - including TGAs).
  • Fixed a few bugs in the alpha plane compressor and decompressor.
  • Switched to a new internal frame format as a precursor to multi-CPU (SMP) decompression.
  • Merged the Bink for PC and Mac into one code base (for the upcoming Mac release).
  • Fixed a crash in the Bink DLL when shutting down under NT 4.
  • Made the Bink and Smacker players for Win32 take longer lists of filenames (up to 50 files can now be compiled into an EXE).

Changes from version 1.0d to 1.0e (02-01-2000)

  • Worked around a Windows buffer limit that was causing doubled-clicked files in the RAD Video Tools not to play.
  • Fixed a potential crash when decompressing alpha plane data.

Changes from version 1.0c to 1.0d (01-27-2000)

  • Fixed a bug in the QuickTime sound importer - there should be no more glitches with compressed MOV soundtracks, MP3 files or other compressed wave files.
  • Fixed the Bink converter using the wrong value when displaying percent complete during a sound file conversion.
  • Fixed some YUV conversion problems when using non-zero offsets to the BinkCopyToBuffer function.
  • Sped up mono 2x blitting on non-MMX CPUs.
  • Fixed a bug where DirectDraw was still required even when using DIBSections.
  • Fixed a bug in the standalone player where the DirectSound object was deadlocking when being released under NT 4 at shutdown time.
  • Fixed some bugs in the measuring of total read time (and added reporting of idle reading time and background thread reading time in both the summary and the real time statistics).
  • Fixed a bug when simulating a device speed where the device speed was overestimated.
  • Made the list file button handle lists as large as Windows itself can handle.
  • Made the list file button much faster when used with huge lists of files.
  • Made the file info button display the true color depth of an AVI file (8, 16, 24, or 32 instead of always 8 or 24).

Changes from version 1.0c to 1.0b (01-04-2000)

  • Sped up mono blitting on non-MMX CPUs.
  • Fixed a bug in the YUY2 and UYVY 2X stretchers.

Changes from version 1.0a to 1.0b (12-28-1999)

  • Added 2x height, 2x width, and 2x width and height stretching software blitters - up to four times faster than Windows.
  • Added scaling compression support for 2x height, 2x width, and 2x width and height.
  • Fixed the Bink colorspace conversion to match YUV hardware exactly (Bink videos should look identical whether displayed with the hardware or our optimized software blitters now). This also had the nice side effect of making videos with lots of reddish hues compress better.
  • Added much faster blitter support for non-aligned destination memory addresses.
  • Made the Bink compressor display more information when loading lists and runs of files.
  • Fixed a bug in the Smacker player for DOS when playing new Smacker 4.0 files.
  • Fixed a bug in the Smacker player for DOS when playing an audio track compressed with the Bink audio codec.
  • Fixed edge support for mono and 2x blitters.
  • Fixed a bug in both the Bink and Smacker compressors, where the start sound offset would be wrong if you adjusted the output frame rate.
  • Fixed a bug where the Bink player would wait the first frame's time before beginning playback.
  • Fixed a bug in the Bink player where the final frame wasn't displayed long enough.

Changes from version 0.9n to 1.0a (12-01-1999)

  • Bink compression is now twice as fast! Compress your movies in half the time.
  • Bink player now shares the CPU much more nicely.
  • Added video smoothing and contrast control to the Bink compressor (usually makes a huge difference in video quality).
  • Smacker has been upgraded to version 4.0 and has been fully integrated.
  • New Smacker 4.0 compression - double the quality of your Smacker movies!
  • Smacker 4.0 now includes optional Bink audio compression. You can now use Bink's perceptually-lossless 8 to 1 audio compressor.
  • Smacker 4.0 player now shares the CPU much more nicely.
  • Smacker 4.0 player now correctly shows the logo if the movie was paused.
  • Smacker 4.0 DOS player now uses Miles 6.0 (smaller compiled DOS EXEs).
  • Smacker 4.0 uses the Bink bandwidth allocation routines to intelligently reallocate bandwidth to the frames that need it most.
  • Added a SmackGetKeyFrame function to the Smacker 4.0 SDK.
  • The analyze window now tags key frames in Bink and Smacker 4 files.
  • Added an always-on-top option to both the Bink and Smacker players.
  • The Bink compressor can now compress to grayscale-only Bink files.
  • Added an option for the Bink compressor to compress the alpha plane of the input file (only Bink SDK users can access the alpha plane currently).
  • Made window alignment dependent on pixel size (rather than always 4) in Bink.
  • Made the compressors, converter, and mixers front-ends more consistent.
  • Bink video window isn't cleared to black before playback begins.
  • Fixed a nasty bug in the masking YUV blitter that would cause some unusual frames not to be completely copied (leaving little artifacts behind).
  • Fixed a crash when looping short Bink movies.
  • Fixed a bug in the Bink converter when converting RAW sound files into wave files.
  • Fixed a bug in Bink where the first frame would be skipped after a go to or a loop around (which also fixed a weird problem when Smacking a Bink file).

Changes from version 0.9m to 0.9n (11-02-1999)

  • Added new YUV to RGB blitters specifically for video memory - up to 100% faster when converting directly into video memory.
  • Fixed a memory leak in BinkClose.
  • Fixed a bug when playing multiple files when using the fill-screen-to-black option.

Changes from version 0.9k to 0.9m (10-14-1999)

  • Added a grayscale blitting mode (much faster - useful on slow machines).
  • Further tweaked the frame skipping logic for slower machines.
  • Made the DIBSection blitter chosen before the overlay and off-screen surfaces (should be more compatible).

Changes from version 0.9j to 0.9k (10-13-1999)

  • Made sound synchronization much more accurate after a frame skip or a pause - we should recover from frame skips on low end machines much cleaner now.
  • Fixed a problem with videos stopping with the SDK when using Miles.

Changes from version 0.9i to 0.9j (10-11-1999)

  • Further optimized the 24-bit and 32-bit non-MMX blitting routines.
  • Fixed the background of the Bink Tools dialog boxes under NT.
  • Fixed a bug with compiled EXE Bink files not playing under NT.

Changes from version 0.9h to 0.9i (09-09-1999)

  • Added DIB Section support for non-DirectX blitting.
  • Changed DirectDraw off-screen system blitter to check the DirectDraw scale flags to see if it supported stretching.
  • Added new non-MMX 16-bit, 24-bit, and 32-bit blitters that are all much faster on Pentium Pros.
  • Added additional optimized data alignment paths in the 16-bit non-MMX blitters.
  • Fixed a bug in the sound mixer where key frame markers would be lost.
  • Fixed a bug in the compressor where the hint file frame numbers were off by one.
  • Added a switch (/C) to hide the Windows mouse cursor inside the Bink window.

Changes from version 0.9g to 0.9h (09-02-1999)

  • Fixed a stupid, but pesky audio mixing bug where the "mix at what frame" setting could be ignored.
  • Fixed a sporadic crash when compressing file with more than 50000 frames.
  • Fixed a bug where the left edge of the desktop could peek through when using the "clear screen to black" setting.
  • Fixed a bug in the SDK when BinkCopyToBuffer wouldn't work inside when the Bink file was paused.

Changes from version 0.9f to 0.9g (08-05-1999)

  • Added a new P5-scheduled version of the 24-bit RGB blitter.
  • Fixed bug when canceling a Bink compression, but keeping the existing frames.
  • Fixed a bug when skipping into a Bink file inside a list file.

Changes from version 0.9e to 0.9f (08-03-1999)

  • Fixed a goofy bug in the Bink player that causes video EXE files not to use the embedded options.

Changes from version 0.9d to 0.9e (07-30-1999)

  • Added Compile to EXE support for both Bink and Smacker files.
  • Adjusted the Bink data rate algorithms to minimize periodic data spikes and data drop outs. It's usually worthwhile to recompress your videos.
  • Added peak data rate control in the Bink compressor - this allows you to keep the peak rates under control when applying bandwidth reallocation.
  • You can now highlight and play multiple files at once (both in quick mode and advanced).
  • Added a View button to the Bink and Smacker mixers.
  • The players now also adjust the sound playback rate when playing back at a forced frame rate. This keeps the audio in sync on forced frame rates.
  • Added new optimized MMX 24-bit and 32-bit blitters - up to 50% faster blitting in these modes.
  • Added a periodic reminder to check for a new Bink version.

Changes from version 0.9c to 0.9d (07-12-1999)

  • Add detection for the AMD Athlon processor (which is pretty awesome, by the way).
  • Fixed a stupid bug when playing Bink or Smacker files from the front-end that had spaces in the filename.
  • Fixed a bug when pressing Escape while the video was paused.

Changes from version 0.9b to 0.9c (07-01-1999)

  • Made the front-end always call the Bink and Smacker players directly.
  • Fixed the Bink player credits window with playing in 320x200 or 320x240 mode.
  • Fixed a crash in the player when trying to play a non-Smacker file.

Changes from version 0.9a to 0.9b (06-29-1999)

  • Fixed a DirectDraw related bug where the video frames would never be displayed if full screen mode was requested.
  • Split out video decompression time and audio decompression time in the runtime and summary info.

Changes from version 0.8i to 0.9a (06-25-1999)

  • Added separate "Advanced play" windows for Bink and Smacker.
  • Added a button to check for the latest version of the RAD Video Tools.
  • Added the Video Analysis window to the Bink Tools.
  • Fixed looping so that the movie would remain in sync.
  • Added the BinkSetSoundOnOff command to the SDK.
  • Added the Smacker Player and Smacker Mixer to the front-end (just the compressor to go).
  • Wrote and implemented the new Bink help system.
  • Much faster (up to twice as fast) 16-bit RGB blitting on MMX machines.
  • Fixed a bug where the background I/O task would consume too much CPU time when the movie was done streaming (or close to done streaming).
  • Added the BinkBufferSetDDPrimary function call to the SDK to allow BinkBuffers to be used with full-screen DirectDraw applications.
  • Fixed an end-of-movie sound glitch when using DirectSound.

Changes from version 0.8h to 0.8i (05-12-1999)

  • Added the Bink converter which replaces the Graphics and Sound Processor in Smacker.
  • The Bink converter can now convert video *and* audio at the same time - allowing direct conversions from Bink or QuickTime into AVIs.
  • Fixed a threading crash if rapidly opening and closing Bink files.
  • Fixed the importing of 16-bit BMP files.
  • Added importing and exporting of PNG files.
  • Fixed monotonous multiple prompting for series of files when creating a list when a run of files are selected.

Changes from version 0.8g to 0.8h (04-21-1999)

  • Added a frame rate adjustment feature. Unlike the existing frame rate changer, this feature will add or remove frames to maintain your specified frame rate. So, if you have a 15 fps animation and you adjust it to 30 fps, then every frame will be copied twice.
  • Added decoding of Bink audio tracks to the utilities (you can now Bink or Smack a Bink file). This allows you to archive your videos in much, much less space than uncompressed AVIs (just use a really high data rate for archival purposes, say 2000000).

Changes from version 0.8f to 0.8g (04-16-1999)

  • Fixed an overwrite bug when compressing small resolution videos.

Changes from version 0.8e to 0.8f (04-12-1999)

  • Added the Bink SDK manual and cleaned up a few problems in the SDK.
  • Fixed a bug when playing under NT close to the max data rate of the device.

Changes from version 0.8d to 0.8e (04-02-1999)

  • Fixed a nasty overflow in the data rate parameters which could cause the data rate to grow linearly during a compression. If the data rate of your movies seems too high, then you probably ran into this bug.
  • Smoothed playback somewhat for movies that are playing very close to the maximum data rate of the playback device.

Changes from version 0.8c to 0.8d (03-31-1999)

  • Added much better background IO routines - can approach 100% background IO even on Windows 95/98.
  • Made audio decompression much faster.
  • Added better frame skipping techniques.
  • Improved Bink compression speed somewhat.
  • Added a new redistributable Bink player (with no RAD credits) for licensing.

Changes from version 0.8b to 0.8c (03-24-1999)

  • Added a list file editor.
  • Fixed a bug when Binking a wave file.
  • Can detect pretty much any type of CPU now (used the Scitech code).

Changes from version 0.8a to 0.8b (03-23-1999)

  • Rebuilt the Bink installation program to include the mixer.

Changes from version 0.0 to 0.8a (03-22-1999)

  • The first version of Bink for general testing is released (Bink Release Candidate 1)!
  • File format changed from earlier betas, this came with an almost 2x quality improvement however - especially on low-bandwidth materials.
  • Codec technology is completely finished - tools still need minor polishing, including the integration of Smacker.
  • This version of Bink requires DirectX to be installed.


Bink Reference

The Bink Reference is a hyperlinked version of the Bink SDK's printed reference manual.

Acknowledgments
Introduction
Bink Overview
Compressing with Bink
Bink Video Playback
Colorspace - RGB vs. YUV
Audio Tracks in Bink
Critical File I/O handling in Bink
The Win32 Platform
Installation for Win32
Integrating Bink into a Win32 Build Environment
Distributing the Bink DLL under Win32
Bink Playback under Win32
Pros and Cons of Software Blitting under Win32
Pros and Cons of YUV Overlays under Win32
Pros and Cons of YUV Off-screen Buffers under Win32
BinkBuffers to the Rescue
Sound under Win32
Memory management under Win32
Sharing the CPU under Win32
Bink Examples for Win32
The Nintendo GameCube Platform
Installation for the Nintendo GameCube
Integrating Bink into an Nintendo GameCube Build Environment
Distributing Bink on the Nintendo GameCube
Bink Playback on the Nintendo GameCube
NTSC and PAL on the Nintendo GameCube
Gamma on the Nintendo GameCube
Sound on the Nintendo GameCube
Memory management on the Nintendo GameCube
Sharing the CPU on the Nintendo GameCube
Bink Examples for the Nintendo GameCube
The Xbox Platform
Installation for the Xbox
Integrating Bink into an Xbox Build Environment
Distributing Bink on the Xbox
Bink Playback on the Xbox
Sections on the Xbox
NTSC and PAL on the Xbox
Gamma on the Xbox
Sound on the Xbox
Memory management on the Xbox
Sharing the CPU on the Xbox
Bink Examples for the Xbox
The MacOS Platform
Installation for MacOS
Integrating Bink into a MacOS Build Environment
Distributing the Bink Shared Library under MacOS
Bink Playback under MacOS
Pros and Cons of Direct to Screen Blitting under MacOS
Pros and Cons of GWorld Blitting under MacOS
Simplifying MacOS Blitting with BinkBuffers
Sound under MacOS
Memory management under MacOS
Sharing the CPU under MacOS
Bink Examples for MacOS
Basic Types
S8 | describes a signed 8-bit integer.
U8 | describes an unsigned 8-bit integer.
S16 | describes a signed 16-bit integer.
U16 | describes an unsigned 16-bit integer.
S64 | describes a signed 64-bit integer.
U64 | describes an unsigned 64-bit integer.
S32 | describes a signed 32-bit integer.
U32 | describes an unsigned 32-bit integer.
s32_ptr | describes a pointer to a signed 32-bit integer.
u32_ptr | describes a pointer to an unsigned 32-bit integer.
VOID_PTR | describes a standard C/C++ untyped memory pointer.
F32 | describes a standard 32-bit floating-point number.
F64 | describes a standard 64-bit double-precision floating-point number.
void | describes a standard C/C++ void return type.
NULL | describes a standard C/C++ NULL pointer.
OS_WND | describes a standard HWND window handle on Win32, or a standard WindowPtr under MacOS.
HCURSOR | describes a standard Win32 HCURSOR cursor handle.
LPDIRECTSOUND | describes a pointer to a DirectSound object.
LPDIRECTDRAW | describes a pointer to a DirectDraw object.
LPDIRECTDRAWSURFACE | describes a pointer to a DirectDraw surface object.
LPDIRECT3DSURFACE8 | describes a pointer to a DirectX 8 Direct3D surface object.
FSSpec_PTR | describes a pointer to a MacOS filespec.
GDHandle | describes a standard MacOS Graphics Device pointer.
VOID_PTR | describes a standard C/C++ untyped memory pointer.
BINK_STRING | describes a normal zero-terminated C-style string.
HBINK | is a handle to an opened Bink file.
HBINKTRACK | is a handle to an opened Bink audio track.
HBINKBUFFER | is a handle to an opened BinkBuffer.
BINKRECT | is a structure describing a rectangular area.
BINKRECT_ARRAY | is an array of structures describing rectangular areas.
Bink API
BinkOpen | opens the specified Bink file for decompression.
BinkMacOpen | opens the specified Bink file for decompression.
BINK | is a structure returned from BinkOpen.
BINK_OPEN_FLAGS | describes the special or unusual ways of opening a Bink file.
BinkClose | closes the specified Bink handle.
BinkDoFrame | decompresses the next frame of video.
BinkCopyToBuffer | copies a video frame from the internal Bink memory buffers to a specified memory address.
BinkCopyToBufferRect | copies a piece of the video frame from the internal Bink memory buffers to a specified memory address.
BINK_COPY_FLAGS | describes the destination buffer type as well as special or unusual ways of converting Bink's internal YUV data.
BinkNextFrame | moves to the next video frame in the Bink file.
BinkWait | tells you when to move to the next Bink frame (based on the frame rate of the file).
BinkPause | pauses and resumes playback of a Bink file.
BinkGetRects | returns the dirty rectangles of the last decompressed video frame.
BINK_GETRECTS_FLAGS | Specifies the type of rectangle list you'd prefer from the BinkGetRects function.
BinkGoto | jumps to a new frame inside the Bink file.
BINK_GOTO_FLAGS | Specifies the type of jump to perform.
BinkGetKeyFrame | finds a key frame near another specified frame.
BINK_GETKEY_FLAGS | Specifies the type of key frame search to perform.
BinkService | gives some explicit idle time to Bink to service any of its internal tasks.
BinkSoundUseMiles | tells Bink to use the Miles Sound System as its sound output system.
BinkSoundUseDirectSound | tells Bink to use DirectSound as its sound output system.
BinkSoundUseSoundManager | tells Bink to use the MacOS Sound Manager as its sound output system.
BinkSoundUseAX | tells Bink to use AX as its sound output system on the Nintendo GameCube.
BinkSoundUseMusyX | tells Bink to use MusyX as its sound output system on the Nintendo GameCube.
RADARAMCALLBACKS | specifies a set of replacement audio RAM memory management functions for use with AX on the Nintendo GameCube.
RADARAMALLOC | points to a function that will allocate audio memory on Bink's behalf when using AX on the Nintendo GameCube.
RADARAMFREE | points to a function that will free memory allocated by a previous call to the RADARAMALLOC function.
BinkSetSoundSystem | tells Bink to use a custom sound provider as its sound output system.
BinkSetVolume | sets the volume of a Bink sound track.
BinkSetPan | sets the speaker pan (left to right balance) of a Bink sound track.
BinkSetMixBins | sets the mix bin destination of the sound track on an Xbox.
BinkSetMixBinVolumes | sets the volumes of the individual mix bins on an Xbox.
BinkSetVideoOnOff | tells Bink not to decompress the video frames when BinkDoFrame is called.
BinkSetSoundOnOff | tells Bink not to decompress the audio and release any audio resources.
BinkGetSummary | returns playback information about the specified Bink handle.
BINKSUMMARY | is a structure used to return playback summary information from BinkGetSummary.
BinkGetRealtime | returns realtime playback information about the specified Bink handle.
BINKREALTIME | is a structure used to return realtime playback information from BinkGetRealtime.
BinkGetTrackID | returns the track ID for the specified track index.
BinkOpenTrack | opens a handle to the low-level audio track decoder.
BINKTRACK | is a structure returned from BinkOpenTrack.
BinkCloseTrack | closes a low-level audio track decoder handle.
BinkGetTrackData | extracts all of the sound in the current video frame.
BinkSetFrameRate | overrides the Bink file's built-in frame rate.
BinkSetSoundTrack | overrides the Bink file's default sound track.
BinkSetSimulate | tells Bink to simulate a specified device I/O speed.
BinkSetIOSize | Specifies the size of the I/O memory buffer that Bink reads into.
BinkSetIO | specifies a set of replacement file I/O functions.
RADSetMemory | specifies a set of replacement memory management functions.
RADMEMALLOC | points to a function that will allocate memory on Bink's behalf.
RADMEMFREE | points to a function that will free memory allocated by a previous call to the RADMEMALLOC function.
BinkGetError | returns a string that describes the last global Bink error.
BinkGetLogoAddress | returns a pointer to an embedded Bink logo file.
BinkLoad | reloads the Bink sections on an Xbox (if it had been unloaded by BinkUnload).
BinkUnload | unloads the Bink sections on an Xbox.
BinkLoadConverter | reloads one or more of the Bink YUV to RGB converters (if they had been unloaded by BinkUnloadConverter).
BinkUnloadConverter | unloads one or more of the Bink YUV to RGB converters.
BINK_CONVERTER_FLAGS | Specifies the class of Bink YUV converters to load or unload.
BinkBuffer API
BinkBufferOpen | opens a BinkBuffer (which simplifies blitting YUV data onto the screen).
BINKBUFFER | is a structure returned from BinkBufferOpen.
BINKBUFFER_OPEN_FLAGS | describes the type and capabilities of the BinkBuffer that you wish to open.
BinkBufferClose | closes the specified BinkBuffer handle.
BinkBufferSetDirectDraw | sets the DirectDraw object and primary surface pointers.
BinkBufferLock | locks the BinkBuffer for reading or writing to the pixel buffer.
BinkBufferUnlock | unlocks a BinkBuffer that has been locked with BinkBufferLock.
BinkBufferBlit | copies the pixel data onto the screen (for the off-screen variety of BinkBuffers).
BinkBufferCheckWinPos | adjusts the specified window position coordinates for validity with the current BinkBuffer type.
BinkBufferSetOffset | tells the BinkBuffer that either the window position on the desktop or that the playback offset within the window has changed.
BinkBufferSetScale | sets a new shrinking or stretching scale to use during blitting.
BinkBufferSetResolution | tells Bink to switch video resolution when opening the BinkBuffer.
BinkBufferGetDescription | returns a string describing the blitting style being used by the BinkBuffer.
BinkBufferGetError | returns a string that describes the last global BinkBuffer error.
BinkDDSurfaceType | returns a value describing the format of the specified DirectDraw surface.
BinkDX8SurfaceType | returns a value describing the format of the specified DirectX 8 surface.
BinkGDSurfaceType | returns a value describing the format of the specified MacOS Graphics Device.
BinkIsSoftwareCursor | determines whether the specified mouse cursor is software-based on the specified DirectDraw surface pointer.
BinkCheckCursor | checks to see if the mouse is currently inside the specified window rectangle, and, if so, hides it.
BinkRestoreCursor | restores the mouse cursor to its original state after a BinkCheckCursor call.
Background Concepts
Open and Close
Locking and Unlocking
Alpha Planes
OpenGL
Direct3D
Scaling
Mouse Cursors
Change Log