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 file
formats
supported by installed CODECs
can be played
with this instruction - .avi, .mpg,
.divx,
.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 is streamed from hard disk;
therefore it must exist in the work
folder, and won't be found in the path, in a buffer, or
in a resource.
Playing from a subfolder is only possible when adding the folder name, f.i. media_loop("media\\scene.avi", NULL, 100);. |
target |
C Pointer to a bmap that serves as target texture
for the video stream, or NULL for playing the video in the whole engine window. Using a target texture, the video can be played on a model or sprite surface in the level. |
volume |
Individual audio volume of the stream, 0 ..100. The master
volume for all streams is controlled by the midi_vol variable |
Returns:
Handle of the multimedia stream, or 0 if the stream couldn't be played.Speed:
Medium
Remarks:
-
Windows comes with default CODECs for several basic video formats, such as MPEG-2, WMV, or uncompressed AVI files. CODECs for other video or audio formats files are freely available on the internet. A general CODEC collection for almost all formats can be download at http://sourceforge.net/projects/ffdshow and used under the GPL license. For streaming .ogg files, an installer for Ogg Vorbis DirectShow filters (oggds0995.exe) is included in the external folder. 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.
-
Many video format versions use the same file extension, so the extension alone (such as .avi or .mpg) does not tell you whether a video will play on your PC or not. For testing whether a CODEC for that format is installed on your PC, run a one-line script that just plays a video of the required type:
function main() { media_play("filename.ext",NULL,100); }
- 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 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 true color (24 bit) mode, therefore use 24 bit movies
if possible. High color movies (16 bit) are also supported, but play
slower and
look worse due to the color
conversion
process.
-
C The target bitmap for video streams can also
be displayed with transparency or overlay flags. Normally the bitmap should have the same size as the video;
for scaling the video, play it on a scaled PANEL. The bmap should be a 24 bit texture (such as from a .tga image) without alpha channel.
Compressed textures
or alpha channel textures can't receive video streams. On mipmapped textures, only the first mipmap receives the video stream - for seeing it from a distance, use a non-mippmapped texture or assign a material that switches mipmapping off for that object.
-
Movies play as separate tasks in the background while the normal functions continue. Use the media_playing() function for determining when a movie is finished.
Some media types, like .bmp or .jpg still
images, play 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 audible delay on audio files, use snd_loop for looping music
in .wav or .ogg format.
-
Movies require a DirectX device for playing , and thus can't play in the first frame before the DirectX device is opened.
Example:
// Play music "ribanna.mid" at 50% volume endlessly.
mhandle = 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);
See also:
media_pause,
media_playing, media_start,
media_stop, media_tune,
media_layer,
midi_vol, num_mediastreams,
snd_play
► latest
version online