BlitzMovie Manual

BlitzMovie 1.2 Manual

Thank you for downloading BlitzMovie 1.2, an extension for Blitz3D. BlitzMovie uses DirectShow 9 so you need to have DirectX 9 installed. BlitzMovie also incorporates Windows Media movie playback capability. Installation of Windows Media Player 9 or later is highly recommended.

NEW IN VERSION 1.2

Thanks to Tom Speed (tom@tomspeed.com) sharing information about how to get at the actual DirectX7 surface in a Blitz3D texture or image, BlitzMovie can now decode directly to those DirectX7 surfaces resulting in the highest speed yet. Please note that this release is quite experimental though and problems are expected, although none were encountered on my machine yet. Also new is the ability to set the volume, mute the audio and ask the movie if it's actually playing or paused.

FIXES FOR VERSION 1.2

In previous versions, the library didn't have a clue whether the movie had stopped or was still playing. This is now fixed and helps the new BLITZMOVIE_IsPlaying command.

NEW IN VERSION 1.1

As Blitz3D's new update 1.88 allows access to core DirectX components, it seemed like a great idea to take advantage of them. Two new functions exist then, BLITZMOVIE_OpenD3D and BLITZMOVIE_DrawD3D. These bypass the old way of decoding a movie frame, which was to retrieve each and every pixel from the currently decoded frame (on the dll's side) into a Blitz image, ready for blitting. Now, you can load the movie, and internally, BlitzMovie will decode to a Direct3D texture (hidden from the user and created in AGP ram if possible, for fast write speed of the movie frame), rendering via the very same Direct3D Device that Blitz3D exposes. This results in a significant speed increase over previous versions (D3D playback is only possible with Blitz3D).

FIXES FOR VERSION 1.1

Lots of people couldn't even run the examples in the last release as the BlitzMovie dll was compiled against Microsoft's dynamic 'C' runtime dll (which of course was missing :-) ) as opposed to their static 'C' runtime lib. This is now fixed.
Although BlitzMovie works (with modification) on BlitzPlus, there was no information about or samples for BlitzPlus. This is now fixed.
There were instances in which the example code could cause exit trouble. This is now fixed.

PLANNED FOR FUTURE VERSIONS

Features planned for future releases include support for BlitzMax (PC and Apple) and support for Apple Quicktime and Xiph.org's Therora (http://www.theora.org). Also, a complete rewrite of BlitzMovie for BlitzPlus is planned that will be just as fast as the Blitz3D version.

LICENSE

BLITZMOVIE IS FREE SOFTWARE WITH NO USAGE RESTRICTIONS. IF YOU USE THIS SOFTWARE, A CREDIT IN YOUR PROGRAM WOULD BE NICE BUT ISN'T NECESSARY.

GETTING STARTED

Go to the directory you installed BlitzMovie to and copy the userlibs folder into your Blitz3D folder, usually 'C:/Program Files/Blitz3D'. BlitzMovie will not work unless you do this. If you want to use BlitzMovie for BlitzPlus, copy the userlibs folder into your BlitzPlus folder, usually 'C:/Program Files/BlitzPlus'. BlitzMovie will not work unless you do this.

FUNCTIONS

BLITZMOVIE_OpenDecodeToDX7Surface(fileName$, buffer%) NEW

Use this function to open a movie file with an absolute or relative filename. buffer is the handle returned by either CreateImage or CreateTexture on Blitz3D's side. Please note that when creating a texture, it's a good idea to force it to hi-colour (flag 512) and NOT make it mipmapped (flag 8). See documentation for CreateTexture for more details.

Returns: 1 - success or 0 - failure

BLITZMOVIE_MuteAudio() NEW

Use this function to mute the sound in a previously opened movie.

Returns: 1 - success or 0 - failure

BLITZMOVIE_IsPlaying() NEW

Use this function to query the state of a previously opened movie.

Returns: 1 - movie is playing, 2 - movie is paused or 0 - movie is not playing or stopped

BLITZMOVIE_SetVolume(volume%) NEW

Use this function to set the volume of the audio in a previously opened movie. volume% is a value between 0 (full volume) to -10000 (silence). This is the same as DirectShow expects.

Returns: 1 - success or 0 - failure

BLITZMOVIE_Open(fileName$)

Use this function to open a movie file with an absolute or relative filename.

Returns: 1 - success or 0 - failure

BLITZMOVIE_Close()

Use this function to close a previously opened movie.

Returns: NOTHING

BLITZMOVIE_Play()

Use this function to play a previously opened movie.

Returns: 1 - success or 0 - failure

BLITZMOVIE_Stop()

Use this function to stop a previously opened movie.

Returns: 1 - success or 0 - failure

BLITZMOVIE_GetWidth()

Use this function to get the width of a previously opened movie.

Returns: width - if movie is valid or 0 - failure

BLITZMOVIE_GetHeight()

Use this function to get the height of a previously opened movie.

Returns: height - if movie is valid or 0 - failure

BLITZMOVIE_GetPixel(offset%)

Use this function to get the 32-bit argb (alpha, red, green, blue) pixel from specified offset of the current frame, of a previously opened movie. The offset is specified in terms of ((y multiplied by image width) + x). In other words, if you had an image of dimensions 128 x 128 and you wanted the third pixel colour of the third scanline, you would call this function with an offset of (128 * 2) + 3 (x = 3, y = 2). If you wanted the third pixel colour of the first scanline, you would call this function with an offset of (128 * 0) + 3 (x = 3, y = 0).

Returns: argb pixel at offset in currently decoded movie frame - if movie is valid or $ff000000 if movie is not valid and / or movie was opened in D3D mode.

BLITZMOVIE_OpenD3D(fileName$, device%, ddraw%)

Use this function to open a movie file with an absolute or relative filename. Use SystemProperty("Direct3DDevice7") and SystemProperty("DirectDraw7") to retrieve the Direct3D device interface and DirectDraw interface.

Returns: 1 - success or 0 - failure

IMPORTANT: MOVIES INTENDED FOR USE WITH D3D PLAYBACK MUST HAVE DIMENSIONS THAT ARE POWERS OF TWO, I.E. 256 x 256 OR 512 X 512. THIS FUNCTION WILL FAIL IF THE ABOVE RULE IS NOT ADHERED TO. ALSO, THE BIGGER THE SIZE, THE SLOWER THE PLAYBACK.

BLITZMOVIE_DrawD3D(x%, y%, width%, height%)

Use this function to draw the currently decoded movie frame at position x, y of the dimensions, width and height.

Returns: 1 - success or 0 - if movie is not valid and / or movie wasn't opened in D3D mode

FAQ

Q: Why is the program so slow at decoding?

A: The c++ and asm code in the BlitzMovie.dll is optimised and fast. However, the movie draw functions (blitz native code contained in blitzmovie.bb) are very slow. Pixel by pixel transfer is basically rubbish. So in answer to this question, either use smaller movies (320x240 etc) and / or non scaled drawing. As of from BlitzMovie 1.1, consider using BLITZMOVIE_OpenD3D / BLITZMOVIE_DrawD3D which process the movie in a way that uses D3D hardware internally, rather than Blitz3D native software blitting code, resulting in much faster performance. As of from BlitzMovie 1.2, use BLITZMOVIE_OpenDecodeToDX7Surface for the fastest performance.

If I use BlitzMovie in my product, is it royalty free?

A: Absolutely.

Q: What if I think I've found a bug?

A: Please email kevan@harrimansoftware.com with details.

Q: Is there a version for BlitzMax?

A: No, but there soon will be, based on Xiph's Theroa patent free codec theora. See www.theora.org for details. BlitzMovie for BlitzMax will be cross platform and I intend to write a DirectShow encoder app with a nice GUI for win32 that you can use to convert your movies to theora format.

Q: Why is the BlitzPlus version so slow?

A: I intend to rewrite BlitzMovie from BlitzPlus but I'm very short of time at the moment and also, I need to buy a copy of BlitzPlus.