PlayVideo(id[, x, y, table])

PlayVideo() works in an asynchronous manner. It will return immediately once it has started video playback. After you have started a video, you can control playback by calling functions like StopVideo() or StopLayer() depending on whether you use normal or layered playback mode.

Hollywood supports two different video playback modes: Normal playback and layered playback. Normal playback is the fastest and most optimized mode as it can utilize hardware acceleration by using video overlays for example. The disadvantage of normal mode is that it has some restrictions (see below for more information). Layered playback mode, on the other hand, is very flexible as your video will be rendered into a Hollywood layer and so you can use all layer functionality on your video object, e.g. you can rotate it, apply transparency and transition effects or special image filters. The disadvantage of layered mode is that it is quite slow because it cannot use hardware acceleration so you will need lots of raw CPU horsepower to get decent framerates here. For most cases, normal playback mode should be sufficient. Layered playback mode is only necessary if you need to do advanced things during video playback.

It is important to note that PlayVideo() will always use normal playback mode by default, even if layers are enabled for the current BGPic. To make PlayVideo() use layered mode, you will have to request this explicitly by setting the UseLayer tag in the optional table argument to True.

Normal playback mode comes with the restriction that videos will always appear above everything else. This means that it is impossible for you to draw on top of a video. Instead, all graphics commands will always draw beneath the video area. Even sprites will never appear above the video graphics. Also, the video will stay visible until you call StopVideo(). Pausing a video will not remove that video from the display. Instead, the currently displayed frame will be frozen until you call ResumeVideo(). If you want to remove a video completely from the display, you will always have to call StopVideo(). If you would like to move a video or change its size during normal playback mode, you need to use the commands SetVideoPosition() and SetVideoSize() for this task.

In layered playback mode you can use all the functions from Hollywood's layers library to control video playback, i.e. you can change the video's size and orientation using ScaleLayer() and RotateLayer() or redefine the z-order by using SetLayerZPos(). You can also show and hide videos using ShowLayer() and HideLayer() or apply transparency or filters to them using SetLayerTransparency() and SetLayerFilter(). All functions of Hollywood's layers library can be used with video layers. To stop or pause a video layer, use the StopLayer() and PauseLayer() functions respectively. To seek to a new position inside the video, use SeekLayer(). To change the audio volume of a video layer use SetLayerVolume().

Please note that layered playback is only possible if the video has been opened using Hollywood's inbuilt or plugin-based video handler. Layered playback is not supported when using the video renderer provided by the host OS. You can change the video driver by using the Loader tag in OpenVideo() or @VIDEO.

There are no limits as to how many videos can be played concurrently. Hardware acceleration, however, can often be only used when just a single video is played at a time. When multiple videos are playing at the same time, Hollywood often has to switch back to software rendering, which is slower. Please also note that video playback generally requires a strong CPU. 68k processors are much too slow for this task (except on WinUAE).

Note that when switching BGPics using DisplayBGPic(), Hollywood will automatically stop all videos playing in normal mode. Videos playing in layered mode, however, will continue playing even if the BGPic has been changed. Thus, you need to explicitly stop video layers by calling StopLayer() before switching BGPics if you want them to stop on this occasion.

Starting with Hollywood 6.0, PlayVideo() accepts an optional table argument which can be used to configure the following options:

UseLayer:

If you set this tag to True, PlayVideo() will use layered playback mode. You need to enable layers before you can use this tag. See Layers introduction for details. If layered playback mode is used, this command will add a new layer of the type #VIDEO to the layer stack. See above for more information on the difference between normal and layered playback mode. Defaults to False. (V6.0)

Channel:

Channel to use for playback of this video's audio stream. By default, PlayVideo() will automatically choose a vacant channel and will fail if there is no vacant channel. To override this behaviour, you can use this field. When specified, it will always enforce audio playback on the very channel specified here. If the channel is already playing, it will be stopped first. (V6.1)

If layered playback mode is used you can also specify one or more of the standard tags for all drawing commands in the optional table argument. See Standard drawing tags for more information about the standard tags that nearly all Hollywood drawing commands support.

id

identifier of the video to play

x

optional: desired x position for the video (defaults to the position defined using SetVideoPosition() or 0)

y

optional: desired y position for the video (defaults to the position defined using SetVideoPosition() or 0)

table

optional: table configuring further options (V6.0)