Movie Overlays
The movie overlay player provides an interface for scripts to play movies in a created uicomponent. The player functionality allows scripts to specify properties of the uicomponent player and the movie itself, allowing fine control over playback. Through this interface the script can control the size and position of the movie on-screen, how the movie fades in and out and what to do when the movie completes or is skipped, for example. The script may also set a mask image, which can be used to blend the edges of the movie to transparent during playback for a pleasing visual effect.
A movie overlay player may be created with movie_overlay:new
, and then optionally configured with the function calls listed in this documentation. Once configured, movie playback may be started by calling movie_overlay:start
.
The movie overlay interface provides some functions for configuring the player, however other configuration calls may be made to it beyond those listed here. If any call is made to the player which it doesn not recognise then those are passed through to the underlying player uicomponent. This means that any function call provided by the uicomponent
library may be made to a movie overlay object.
The player uicomponent is created the first time a call is made which is to be passed through to it, or when movie_overlay:start
is called. If there is a delay between the creation/configuration of the player and the start of playback then be aware that the uicomponent will exist. It is set to be invisible and non-interactive so it should not affect the game.
If a movie_overlay is not configured before playback is started then the default style is applied using movie_overlay:set_style
, setting the movie to be fullscreen.
Loaded in Campaign | |
Loaded in Battle | |
Loaded in Frontend |
-
movie_overlay:new(
namestring
,
movie pathstring
)
-
Creates and returns a new movie overlay player object.
Parameters:
1
Unique name for this movie overlay object
2
Path to movie file, starting from the Movies folder in working data. The file extension should be omitted.
Returns:
movie overlay objectmovie_overlay
Example - Play the Warhammer intro movie, filename data/Movies/startup_movie_03.ca_vp8:
mo_wh_intro = movie_overlay:new("warhammer_intro", "startup_movie_03"); -- path starts from Movies
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 72
Once a handle to a movie_overlay object is obtained then functions may be called on it to query or modify its state in the following form.
Example - Specification:
<object_name>:<function_name>(<args>)
Example - Creation and Usage:
local mo_chaos_invasion = movie_overlay:new("warhammer_intro", "warhammer/chs_invasion");
mo_chaos_invasion:set_centre_mask_image();
mo_chaos_invasion:PropagatePriority(500); -- function provided by uicomponent interface
-
movie_overlay:move_to(
xnumber
,
ynumber
)
-
Sets the position of the uicomponent by calling
uicomponent:MoveTo
, setting the uicomponent to be unmoveable afterwards. The uicomponent is created at this point if it doesn't already exist.
If a movie_overlay is not configured before playback is started then the default style is applied usingmovie_overlay:set_style
, setting the movie to be fullscreen.Parameters:
1
X screen co-ordinate in pixels.
2
Y screen co-ordinate in pixels.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 192
-
movie_overlay:resize(
widthnumber
,
heightnumber
)
-
Resizes the uicomponent, by calling
uicomponent:Resize
. The uicomponent is created at this point if it doesn't already exist.
If a movie_overlay is not configured before playback is started then the default style is applied usingmovie_overlay:set_style
, setting the movie to be fullscreen.Parameters:
1
Width in pixels.
2
Height in pixels.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 215
-
movie_overlay:set_skippable([
skippableboolean
])
-
Sets whether this movie should be skippable with the ESC key. Movies are skippable by default - use this function to disable this behaviour.
Parameters:
1
optional, default value=true
skippable
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 243
-
movie_overlay:set_end_callback(
callbackfunction
)
-
Sets a callback to be called when the movie ends or is skipped. If a hide animation is set, this callback gets called as the hide animation starts. To set a callback when the hide animation completes, use
movie_overlay:set_destroy_callback
.Parameters:
1
callback
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 255
-
movie_overlay:set_skip_callback(
callbackfunction
)
-
Sets a callback to be called when the movie is skipped. If a hide animation is set, this callback gets called as the hide animation starts, before the end callback if one has been set with
movie_overlay:set_end_callback
.Parameters:
1
callback
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 268
-
movie_overlay:set_destroy_callback(
callbackfunction
)
-
Sets a callback to call when the player uicomponent is destroyed. This will only get called if this movie overlay player destroys itself, not if something else destroys it.
Parameters:
1
callback
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 281
-
movie_overlay:set_hide_on_end(
destroy on endboolean
)
-
Sets whether the overlay should try and hide or destroy itself when it ends. Set this to
false
if some other process will destroy it.Parameters:
1
destroy on end
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 294
-
movie_overlay:set_should_loop([
loopboolean
])
-
Sets the movie to loop. By default, the movie plays only once.
Parameters:
1
optional, default value=true
loop
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 306
-
movie_overlay:set_play_movie_audio([
play audioboolean
])
-
Sets whether the movie audio should play or not. Movie audio plays by default - use this function to disable it.
Parameters:
1
optional, default value=true
play audio
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 318
-
movie_overlay:set_freeze_game_rendering([
should freezeboolean
])
-
Sets whether the game should continue to render while the movie is being played. Game rendering stops during movie playback by default - use this function to enable it.
Parameters:
1
optional, default value=true
should freeze
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 330
-
movie_overlay:set_steal_user_input([
should stealboolean
])
-
Sets whether user input should be stolen by script while the movie is being played. The script establishes an ESC key listener to handle movie skipping if this is set.
Parameters:
1
optional, default value=true
should steal
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 342
-
movie_overlay:set_stop_game_audio([
stop audioboolean
])
-
Sets whether the game audio should stop playing while the movie is being played. By default game audio is stopped/disabled during movie playback - use this function to enable it.
Parameters:
1
optional, default value=true
stop audio
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 354
-
movie_overlay:set_resize_uicomponent_to_fit([
should freezeboolean
])
-
Sets whether the uicomponent should resize itself to match the dimensions of the movie. This behaviour is disabled by default - use this function to enable it.
Parameters:
1
optional, default value=true
should freeze
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 366
-
movie_overlay:force_movie_track(
movie tracknumber
)
-
Forces the movie overlay to use a particular track. If this track is already occupied the previous video will be stopped. Supported track values are 0-3. If no movie track is forced, the system will pick track 2 or 3, depending on which is currently free.
Parameters:
1
movie track
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 378
Callbacks can be registered to be called on certain frames or timestamps during the movie playback using the functions in this section.
-
movie_overlay:add_frame_callback(
callbackfunction
,
frame numbernumber
)
-
Adds a callback to be called when the movie reaches a specified frame. The frame can be specified as a positive number or as a negative number, in which case that number of frames from the end of the movie is considered the trigger frame.
Parameters:
1
callback
2
frame number
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 407
-
movie_overlay:add_timestamp_callback(
callbackfunction
,
timestampnumber
)
-
Adds a callback to be called when the movie reaches a specified timestamp, in seconds. The time can be specified as a positive number or as a negative number, in which case the timestamp is counted backwards from the end of the movie.
Parameters:
1
callback
2
timestamp
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 425
The functions described in this section can be used to set custom show and hide animations for the player uicomponent. The animations should also be added to the movie overlay uicomponent in the UI editor.
-
movie_overlay:set_show_animation(
animation namestring
, [
duration overridenumber
])
-
Sets the uicomponent animation that should be triggered when the movie starts playing. By default an animation called "show" is triggered - use this function to set a different animation. A blank string may be supplied to play no animation as the movie starts.
An optional animation duration in seconds may also be supplied. If set, this causes the player to set the frame time of the last frame of the animation to the supplied duration.Parameters:
1
animation name
2
optional, default value=nil
duration override
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 453
-
movie_overlay:set_hide_animation(
animation namestring
, [
duration overridenumber
])
-
Sets the uicomponent animation that should be triggered when the movie ends. This animation is played when the movie ends naturally, either because playback has finished or the specified movie duration has elapsed. It is also played if the movie is skipped and no skip animation has been set. By default this animation is called "hide" - use this function to set a different animation. A blank string may be supplied to play no animation.
An optional animation duration in seconds may also be supplied. If set, this causes the player to set the frame time of the last frame of the animation to the supplied duration.
Any new hide animation should also be set to destroy the overlay uicomponent on completion.Parameters:
1
animation name
2
optional, default value=nil
duration override
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 478
-
movie_overlay:set_skip_animation(
animation namestring
, [
duration overridenumber
])
-
Sets the uicomponent that should be triggered when the movie is skipped. By default this animation is called "hide" - use this function to set a different animation. A blank string may be supplied to play no animation.
An optional animation duration in seconds may also be supplied. If set, this causes the player to set the frame time of the last frame of the animation to the supplied duration.Parameters:
1
animation name
2
optional, default value=nil
duration override
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 504
The functions described in this section each set a mask image for the movie overlay. The transparency value of each pixel in this image is mapped onto the movie, allowing control over the opacity of each movie pixel during playback. This allows the edges of the movie to be blended to transparent, for example.
Several pre-defined mask images have already been created, or another mask image may be specified. By default, a fully-opaque mask image is used so no blending/transparency is seen during playback.
-
movie_overlay:set_mask_image(
mask image pathstring
)
-
Sets a path to a mask image for the movie overlay. This image should be in png format. The path is specified from the working data folder.
Calling this function creates the movie player uicomponent if it has not already been created.Parameters:
1
mask image path
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 541
-
movie_overlay:set_opaque_mask_image()
-
Sets a mask image of ui/skins/default/mask_movie_unmasked.png. This mask image is fully opaque.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 563
-
movie_overlay:set_top_left_mask_image()
-
Sets a mask image of ui/skins/default/mask_movie_top_left.png. This mask image is intended to be used on movies shown in the top-left corner of the screen, blending to transparent to the bottom and right.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 570
-
movie_overlay:set_top_right_mask_image()
-
Sets a mask image of ui/skins/default/mask_movie_top_right.png. This mask image is intended to be used on movies shown in the top-right corner of the screen, blending to transparent to the bottom and left.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 577
-
movie_overlay:set_bottom_left_mask_image()
-
Sets a mask image of ui/skins/default/mask_movie_bottom_left.png. This mask image is intended to be used on movies shown in the bottom-left corner of the screen, blending to transparent to the top and right.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 584
-
movie_overlay:set_bottom_right_mask_image()
-
Sets a mask image of ui/skins/default/mask_movie_bottom_right.png. This mask image is intended to be used on movies shown in the bottom-right corner of the screen, blending to transparent to the top and left.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 591
-
movie_overlay:set_centre_mask_image()
-
Sets a mask image of ui/skins/default/mask_movie_centre.png. This mask image is intended to be used in a central position on the screen, blending to transparent along all four edges.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 598
Movie overlay styles combine multiple settings into one function call. If it's desired to play multiple movies in the same manner it may be sensible to set up a style to avoid configuring each movie overlay object the same way.
-
movie_overlay:set_style(
style namestring
)
-
Sets a style. Currently recognised styles:
Style Name Description
fullscreen
Sets the movie to be fullscreen and to block rendering update. default
The default style sets the movie to be fullscreen. Parameters:
1
style name
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 618
-
movie_overlay:start()
-
Starts playback of the movie
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 734
-
movie_overlay:is_playing()
-
Returns whether this movie is currently playing.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 964
-
movie_overlay:skip()
-
Causes this movie to skip during playback. This is mainly for internal use but can be called externally.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 971
Windowed Movie Player
The windowed movie player provides a shorthand interface for playing movies in a window, with a close button. It is of most use for playing movies underneath the advisor, for which the constructor windowed_movie_player:new_from_advisor
should be used. However, it may be used in other contexts, for which the more general purpose constructor windowed_movie_player:new
is used.
The windowed movie player makes heavy use of the movie_overlay
system for movie playback.
-
windowed_movie_player:new(
namestring
,
movie pathstring
,
aspect rationumber
, [
ui_rootuicomponent
])
-
Creates and returns a new windowed movie player object. If creating a windowed movie player docked underneath the advisor, the constructor
windowed_movie_player:new_from_advisor
should be used instead.Parameters:
1
Unique name for this windowed movie object
2
Path to movie file, starting from the Movies folder in working data. The file extension should be omitted.
3
Movie aspect ratio. This should be the width divided by the height.
4
optional, default value=ui_root
Parent uicomponent, to which the windowed movie player should be attached.
Returns:
windowed movie player objectwindowed_movie_player
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1132
-
windowed_movie_player:new_from_advisor(
namestring
,
movie pathstring
,
aspect rationumber
)
-
Creates and returns a new windowed movie player object, set up to play underneath the advisor. This sets the
advisor_movie_docker
uicomponent to be the panel parent, and also callswindowed_movie_player:set_hide_animation_slides_off_screen_left
to set custom hide animation behaviour that is appropriate for this display mode.Parameters:
1
Unique name for this windowed movie object.
2
Path to movie file, starting from the Movies folder in working data. The file extension should be omitted.
3
Movie aspect ratio. This should be the width divided by the height.
Returns:
windowed movie player objectwindowed_movie_player
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1179
-
windowed_movie_player:new_centred(
namestring
,
movie pathstring
,
aspect rationumber
)
-
Creates and returns a new windowed movie player object, set up to play in the centre of the screen.
Parameters:
1
Unique name for this windowed movie object.
2
Path to movie file, starting from the Movies folder in working data. The file extension should be omitted.
3
Movie aspect ratio. This should be the width divided by the height.
Returns:
windowed movie player objectwindowed_movie_player
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1201
Once a handle to a windowed_movie_player object is obtained then functions may be called on it to query or modify its state in the following form.
Example - Specification:
<object_name>:<function_name>(<args>)
Example - Creation and Usage:
local wmp_drag_and_select = windowed_movie_player:new_from_advisor("wmp_test", "wh3_drag_and_select", 16/9);
wmp_drag_and_select:set_should_steal_esc_key_focus(true)
wmp_drag_and_select:start()
-
windowed_movie_player:set_width(
panel width in pixelsnumber
)
-
Sets the intended panel width. By default, the panel will use the panel width set in the ui layout. The height will also be scaled, based on the aspect ratio supplied to
windowed_movie_player:new
.Parameters:
1
panel width in pixels
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1246
-
windowed_movie_player:set_docking_point(
docking pointnumber
)
-
Sets the panel docking point, which determines how the panel is docked to its parent uicomponent. Docking points are specified as integer values - a list is available in the
Docking
section of this documentation.Parameters:
1
docking point
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1264
-
windowed_movie_player:set_show_animation(
animation namestring
)
-
Sets an animation to play on the panel when it is showed. By default no animation is triggered. The animation must be present on the panel uicomponent.
Parameters:
1
animation name
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1276
-
windowed_movie_player:set_hide_animation(
animation namestring
)
-
Sets an animation to play on the panel when it is hidden. By default, an animation called "hide" is triggered. The animation must be present on the panel uicomponent.
Parameters:
1
animation name
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1294
-
windowed_movie_player:set_hide_animation_slides_off_screen_left(
hide animation slides leftboolean
)
-
Sets a special flag which adjusts the horizontal movement of the hide animation to match the panel width, so the animation moves the panel fully off-screen regardless of width.
Parameters:
1
hide animation slides left
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1307
-
windowed_movie_player:set_close_callback(
callbackfunction
)
-
Sets a callback to call if this windowed movie player is closed. The callback is triggered at the point of closure, when the panel has yet to animate off-screen.
Parameters:
1
callback
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1319
-
windowed_movie_player:set_show_close_button([
show close buttonboolean
])
-
Sets whether the close button is shown on the windowed movie player. By default the close button is displayed, use this function to not show it if needs be.
Parameters:
1
optional, default value=true
show close button
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1332
-
windowed_movie_player:set_panel_hidden_callback(
callbackfunction
)
-
Sets a callback to call when the windowed movie player is fully hidden after being closed. The supplied callback is triggered immediately prior to the panel being destroyed.
Parameters:
1
callback
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1344
-
windowed_movie_player:set_should_steal_esc_key_focus(
steal esc key focusboolean
)
-
Sets whether the panel should steal escape key focus and therefore close itself when the ESC key is pressed. By default the panel does respond to ESC key presses, use this function to disable this behaviour.
Parameters:
1
steal esc key focus
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1357
-
windowed_movie_player:show()
-
Creates and shows the panel and starts movie playback.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1383
-
windowed_movie_player:hide()
-
Hides and then destroys the windowed movie player if it is showing, playing an animation to do so if one has been set. This is called internally if the close button is clicked, or if the ESC key is pressed when stolen.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1500