media_play

media_play(STRING* name,BMAP* target, var volume)

media_loop(STRING* name,BMAP* target, var volume)

Plays a movie or audio stream from a file to the screen or to a texture or panel. Media_play plays the stream once, media_loop repeats it until it is explicitly stopped. As many movie, sound or music files as supported by the hardware can be played simultaneously - for instance, to play two midi files at the same time you'd normally need two sound cards. All files playable with the windows media player can be used with this instruction - .avi, .mpg, .wmv, .wma, .wav, .mid, .mp3, .ogg and so on, even some still image formats like .bmp or .jpg..

Parameters:

name	Name of the multimedia file. The file must exist in the game folder, it won't be found in the path or in a resource .
target	Pointer to a bmap that serves as target texture for the video stream, or NULL. The bmap must be a 16 bit texture without alpha channel, like from a .pcx or .bmp image. If at NULL, the video is played on the whole window or screen.
volume	Individual audio volume of the stream, 0 ..100. The master volume for all streams is controlled by the midi_vol variable

Modifies:

media_handle - this variable is automatically set to the handle of the last played movie or audio file.

Returns:

Handle of the multimedia stream, or 0 if the stream couldn't be played.

Speed:

Medium

Edition:

A6C
A7 all editions

Remarks:

License restrictions apply to some file formats, like MP3 or DivX . Check required license fees before including such files in your game.
Keep movies as small and low-res as possible. The media_play instructions use the Microsoft CBaseVideoRenderer filter. If a movie has a higher resolution or frame rate than the PC can decode in real time, frames will be dropped, possibly resulting in low frame rates, flickering, and loss of synchronisation between video and sound. If the movie has no audio, or the volume is set at 0, loss of synchronisation is preferred over dropping frames, i.e. the movie runs in slight 'slow motion'.
Movies are played in high color (16 bit) mode, which offers a better frame rate and less CPU overhead. Thus use 16 bit movies if possible. True color movies (24 bit) are also supported, but play slower and look worse due to the color conversion process.
The target bitmap for video streams can have any size, and can also be displayed with transparency or overlay flags. Of course in most cases the bitmap should have the same size as the video. Mipmapped textures or alpha channel textures can't receive video streams.
For streaming .ogg files, an installer for Ogg Vorbis DirectShow filters (oggds0995.exe) is included in the external folder . Install it by starting the exe. The Ogg Vorbis filter was created by Tobias Waldvogel (http://tobias.everwicked.com ) and can be freely used and distributed for private and commercial purposes.
Some media types, like .bmp or .jpg still images, stream endlessly and must explicitely be stopped by media_stop(). In some Windows versions, still images are not streamed at all, depending on the configuration - so we do not recommend to use this instruction for still images.
Two movies can not be played simultaneously onto the same bitmap.
Multimedia files have to be loaded from virtual memory before playing, so there can be a few milliseconds delay at the beginning or every loop repetition, depending on the hardware and the filter software. For avoiding this, use snd_loop for looping music in .wav or .ogg format.

Example:

// Play music "ribanna.mid" at 50% volume endlessly.
handle = media_loop("ribanna.mid",NULL,50);
// Play movie "news.avi" on the tv_model entity with maximum volume
media_play("news.avi",bmap_for_entity(tv_model,0),100); 
// Play movie "news.mpg" on the full screen with maximum volume
media_play("news.mpg",NULL,100);