Blitz3D+ Command Reference

OpenMovie ( file$ )

Parameters

file$ - name or path of the video file to open

Description

Opens a video file and returns a movie handle.

This is how a game plays an intro, a cutscene between levels, or a looping video texture on a screen in the corner of a room. Once you have the handle, DrawMovie paints frames wherever you like, MoviePlaying tells you when the video runs out, and CloseMovie gives the memory back.

On the modern runtime the decoding is done by Windows Media Foundation, so the formats you can open are the ones your copy of Windows can already play - MP4 and WMV are the safe bets, and AVI depends on the codec it was encoded with. Only the first video stream is used. Audio is not played: the movie's sound track is switched off when the file is opened, so if your cutscene needs sound, start it separately with PlayMusic or PlaySound and keep the two in step yourself.

The gotcha to plan for is failure. A file that is missing, or in a format Windows has no decoder for, gives a handle of 0 - and the other movie commands do not check what you pass them, so handing that 0 straight to DrawMovie or MovieWidth will take your program down. Always test the handle before you use it, and have a fallback: a still image or a skippable text screen is a much better experience than a crash on someone else's PC.

Opening a movie sets up a decoder and reads the file's headers, which is not instant. Do it during a loading screen rather than in the middle of a frame, and remember the runtime keeps decoding resources alive until you call CloseMovie.

See also: DrawMovie, CloseMovie, MoviePlaying, MovieWidth, MovieHeight, FileType.

Example

; OpenMovie Example
; -----------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

; Blitz3D+ ships no video, so this example plays one of yours: copy a
; video file called my_movie.avi next to this .bb file. Windows Media
; Foundation does the decoding, so anything your PC already plays works.
movie_file$="my_movie.avi"

found=0
If FileType(movie_file)=1 Then found=1

; Show a frame before we block, so the window is never blank
Cls
Text 0,0,"OpenMovie loads a video file and hands back a movie handle."
Text 0,40,"Looking for "+movie_file+" in this example's folder"
If found Then
    Text 0,60,"Found it."
Else
    Text 0,60,"Not there - copy a video file in under that name to see it play."
End If
Text 0,100,"Press and hold Y to open it, or any other key to skip"
Flip

WaitKey

; Only open a file we know is there. OpenMovie returns 0 when the file
; is missing or cannot be decoded, and every other movie command needs
; a real handle, so this is the moment to check.
movie=0
If KeyDown(21) And found Then movie=OpenMovie(movie_file)

spin#=0

While Not KeyDown(1)

    Cls

    If movie<>0 Then
        ; A real movie - draw it at its own size
        DrawMovie movie,20,80
        Text 0,20,"OpenMovie gave a usable handle"
        Text 0,40,"The movie is "+MovieWidth(movie)+" x "+MovieHeight(movie)
    Else
        ; Nothing open - keep something moving so the window is alive
        spin=spin+3
        Color 90,120,190
        Oval 308+Cos(spin)*70,240+Sin(spin)*70,24,24,1
        Color 255,255,255
        Text 0,20,"No movie open - OpenMovie was skipped or returned 0"
        Text 0,40,"A 0 handle means the file was missing or could not be decoded."
        Text 0,60,"Never pass 0 on to DrawMovie or MovieWidth - test it first."
    End If

    Text 0,0,"Esc: exit"

    Flip

Wend

; Hand the movie back when you are finished with it
If movie<>0 Then CloseMovie movie

End

Index